48 lines
2.5 KiB
Markdown
48 lines
2.5 KiB
Markdown
|
# dees-dashboardgrid
|
||
|
|
|
||
|
|
`<dees-dashboardgrid>` renders a configurable dashboard layout with draggable and resizable tiles. The component is now grouped in its own folder alongside supporting utilities and styles.
|
||
|
|
|
||
|
|
## Key Features
|
||
|
|
|
||
|
|
- Pointer-driven drag and resize interactions with keyboard fallbacks (arrow keys to move, `Shift` + arrows to resize).
|
||
|
|
- Collision-aware placement that swaps compatible tiles or displaces blocking tiles into the next free slot.
|
||
|
|
- Context menu (right-click on a tile header) that exposes destructive actions such as tile removal via `dees-contextmenu`.
|
||
|
|
- Layout persistence helpers via `getLayout()`, `setLayout(...)`, and the `layout-change` event.
|
||
|
|
- Responsive presets through the `layouts` map and `applyBreakpointLayout(...)` helper to hydrate per-breakpoint arrangements.
|
||
|
|
|
||
|
|
## Public API Highlights
|
||
|
|
|
||
|
|
| Property | Description |
|
||
|
|
| --- | --- |
|
||
|
|
| `widgets` | Array of tile descriptors (`DashboardWidget`). |
|
||
|
|
| `columns` | Number of grid columns. |
|
||
|
|
| `layouts` | Optional record of named layout definitions. |
|
||
|
|
| `activeBreakpoint` | Name of the currently applied breakpoint layout. |
|
||
|
|
| `editable` | Toggles drag/resize affordances. |
|
||
|
|
|
||
|
|
| Method | Description |
|
||
|
|
| --- | --- |
|
||
|
|
| `addWidget(widget, autoPosition?)` | Adds a tile, optionally auto-placing it into the next free slot. |
|
||
|
|
| `removeWidget(id)` | Removes a tile and emits `widget-remove`. |
|
||
|
|
| `applyBreakpointLayout(name)` | Applies a layout from the `layouts` map. |
|
||
|
|
| `getLayout()` / `setLayout(layout)` | Retrieve or apply persisted layouts. |
|
||
|
|
| `compact(direction?)` | Densifies the grid vertically (default) or horizontally. |
|
||
|
|
|
||
|
|
| Event | Detail payload |
|
||
|
|
| --- | --- |
|
||
|
|
| `widget-move` | `{ widget, displaced, swappedWith }` |
|
||
|
|
| `widget-resize` | `{ widget, displaced, swappedWith }` |
|
||
|
|
| `widget-remove` | `{ widget }` |
|
||
|
|
| `layout-change` | `{ layout }` |
|
||
|
|
|
||
|
|
## Usage Notes
|
||
|
|
|
||
|
|
- **Right-click** a tile header to open the contextual menu and delete the tile.
|
||
|
|
- When resizing, blocking tiles will automatically reflow into free space once the interaction completes.
|
||
|
|
- Listen to `layout-change` to persist layouts to storage; rehydrate using `setLayout` or the `layouts` map.
|
||
|
|
- For responsive dashboards, populate `grid.layouts = { base: [...], mobile: [...] }` and call `applyBreakpointLayout` based on your own breakpoint logic (see the co-located demo for an example).
|
||
|
|
|
||
|
|
## Demo
|
||
|
|
|
||
|
|
The updated `dees-dashboardgrid.demo.ts` showcases live breakpoint switching, layout persistence, and the context menu. Run the demo gallery to explore the interactions end-to-end.
|