@ogidor/dashboard 1.0.6 → 1.0.8

package/README.md

@@ -1,20 +1,38 @@
 # @ogidor/dashboard
 
-A lightweight, content-agnostic drag-and-drop dashboard library for Angular 15.  
-Drop it into any project, feed it your own card content, and get a fully functional multi-workspace grid with persistent layout, pop-out windows, and live cross-tab sync — out of the box.
+A lightweight, content-agnostic drag-and-drop dashboard library for Angular 15.
+Drop it into any project, supply your own card content, and get a fully featured
+multi-workspace grid with persistent layout, pop-out windows, and live cross-tab
+sync — out of the box.
+
+---
+
+## Table of Contents
+
+1. [Features](#features)
+2. [Installation](#installation)
+3. [Quick Start](#quick-start)
+4. [API Reference](#api-reference)
+5. [Models](#models)
+6. [Theming](#theming)
+7. [Pop-out Windows](#pop-out-windows)
+8. [Persisting Layouts](#persisting-layouts)
+9. [Full Integration Example](#full-integration-example)
+10. [Development](#development)
+11. [License](#license)
 
 ---
 
 ## Features
 
-- **Drag & Drop Grid** — smooth cursor-following drag with animated collision resolution and auto-compaction
-- **Resize** — live resize with a bottom-right handle; other cards shift out of the way in real time
-- **Multi-Workspace** — unlimited tabbed workspaces, each with its own independent widget layout
-- **Independent Pop-out Layouts** — each window keeps its own card positions; drag cards in Window B and Window A is completely unaffected
-- **Structural Sync** — adding, removing, or editing a widget in any window immediately appears in all other open windows
-- **Persistent Layout** — layout is saved to `localStorage` and restored on reload
-- **Content-Agnostic Cards** — you own the card body; render any Angular component, chart, or HTML inside
-- **Fully Themeable** — customise every colour (backgrounds, tabs, cards, buttons, handles, placeholders) and font via a `DashboardTheme` input or CSS custom properties
+- **Drag & Drop Grid** — smooth cursor-following drag with collision resolution and auto-compaction.
+- **Live Resize** — bottom-right resize handle; surrounding cards shift out of the way in real time.
+- **Multi-Workspace** — unlimited tabbed workspaces, each with its own independent layout.
+- **Independent Pop-out Layouts** — pop a workspace into its own window; dragging there never affects the main window.
+- **Structural Sync** — adding, removing, or renaming a widget in any window instantly appears in all open windows via `BroadcastChannel`.
+- **Persistent Layout** — state is saved to `localStorage` on every change and restored on reload.
+- **Content-Agnostic Cards** — you own the card body; stamp any Angular component, chart, or markup inside via `ng-template`.
+- **Fully Themeable** — 20 colour tokens plus font family, controllable via a typed `DashboardTheme` input or CSS custom properties.
 
 ---
 
@@ -24,7 +42,7 @@ Drop it into any project, feed it your own card content, and get a fully functio
 npm install @ogidor/dashboard line-awesome
 ```
 
-Add the Line Awesome icon font to your global styles (`angular.json` or `styles.scss`):
+Add Line Awesome to your global styles (`styles.scss` or `angular.json`):
 
 ```scss
 @import "line-awesome/dist/line-awesome/css/line-awesome.css";
@@ -34,7 +52,7 @@ Add the Line Awesome icon font to your global styles (`angular.json` or `styles.
 
 ## Quick Start
 
-### 1. Import the module
+### 1. Import `DashboardModule`
 
 ```typescript
 import { NgModule } from '@angular/core';
@@ -48,14 +66,14 @@ import { DashboardModule } from '@ogidor/dashboard';
 export class AppModule {}
 ```
 
-### 2. Use the component
+### 2. Add the component to your template
 
 ```html
 <app-dashboard
   (addWidgetRequested)="onAddWidget()"
   (editWidgetRequested)="onEditWidget($event)"
 >
-  <!-- Optional: custom card body rendered inside every widget -->
+  <!-- Stamp your own content inside every card -->
   <ng-template gridCell let-widget="widget">
     <div style="padding: 8px; color: white;">
       {{ widget.data | json }}
@@ -64,32 +82,28 @@ export class AppModule {}
 </app-dashboard>
 ```
 
-### 3. Add widgets programmatically
-
-Inject `DashboardStateService` anywhere in your app:
+### 3. Add and edit widgets programmatically
 
 ```typescript
 import { DashboardStateService, Widget } from '@ogidor/dashboard';
 
-@Component({ ... })
 export class AppComponent {
   constructor(private dashboard: DashboardStateService) {}
 
   onAddWidget() {
     this.dashboard.addWidget({
-      title: 'Sales Overview',
+      title: 'Revenue',
       cols: 6,
       rows: 4,
-      cardColor: '#1a1a2e',   // optional — overrides the theme card color
-      data: { metric: 'revenue', period: 'Q1' }, // any shape you need
+      cardColor: '#1a1a2e', // optional — overrides the global card color
+      data: { metric: 'revenue' },
     });
   }
 
   onEditWidget(widget: Widget) {
-    // open your own dialog, then:
+    // open your own dialog, then patch:
     this.dashboard.updateWidget(widget.id, {
       title: 'Updated Title',
-      cardColor: '#0f3460',
       data: { metric: 'users' },
     });
   }
@@ -100,34 +114,36 @@ export class AppComponent {
 
 ## API Reference
 
-### `<app-dashboard>`
+### `app-dashboard`
+
+The main component. Handles tabs, the Add Widget button, and the grid.
 
 #### Inputs
 
-| Input | Type | Default | Description |
-|---|---|---|---|
-| `initialLayout` | `string` | — | JSON string from a previous `serializeLayout()` call. Restores a full layout on load. |
-| `theme` | `DashboardTheme` | See below | Override default colors and font. |
+| Input | Type | Description |
+|---|---|---|
+| `theme` | `DashboardTheme` | Override any colour token or font. All fields optional. |
+| `initialLayout` | `string` | JSON from a previous `serializeLayout()` call. Restores the full layout on load. |
 
 #### Outputs
 
 | Output | Payload | Description |
 |---|---|---|
 | `addWidgetRequested` | `void` | Fires when the user clicks **Add Widget**. Open your own dialog here. |
-| `editWidgetRequested` | `Widget` | Fires when the user clicks the edit icon on a card. Receives the full widget object. |
+| `editWidgetRequested` | `Widget` | Fires when the user clicks the edit icon on a card. |
 
 #### Content children
 
 | Selector | Description |
 |---|---|
-| `<ng-template gridCell let-widget="widget">` | Optional template rendered inside every card body. The `widget` context variable gives you the full `Widget` object including your `data`. |
+| `ng-template[gridCell]` | Rendered inside every card body. Template context exposes `widget: Widget`. |
 
 #### Methods (via `@ViewChild`)
 
 ```typescript
 @ViewChild(DashboardComponent) dash!: DashboardComponent;
 
-// Serialize the current layout to a JSON string (e.g. to save to a backend)
+// Returns the current layout as a JSON string
 const json = this.dash.serializeLayout();
 ```
 
@@ -135,7 +151,7 @@ const json = this.dash.serializeLayout();
 
 ### `DashboardStateService`
 
-The service is provided at root level. Inject it directly for full programmatic control.
+Provided at root. Inject it anywhere for full programmatic control.
 
 ```typescript
 constructor(private state: DashboardStateService) {}
@@ -145,14 +161,15 @@ constructor(private state: DashboardStateService) {}
 
 | Method | Signature | Description |
 |---|---|---|
-| `addWidget` | `(widget: Partial<Widget> & { title: string }) => Widget` | Adds a widget to the active workspace. Returns the created widget with its generated `id`. |
-| `updateWidget` | `(id: string, patch: Partial<Widget>) => void` | Update any widget field except `id`, `x`, `y`, `cols`, `rows`. |
+| `addWidget` | `(widget: Partial<Widget> & { title: string }) => Widget` | Add a widget to the active workspace. Returns the new widget with its generated `id`. |
+| `updateWidget` | `(id: string, patch: Partial<Omit<Widget, 'id'&#124;'x'&#124;'y'&#124;'cols'&#124;'rows'>>) => void` | Update title, cardColor, or data. Use `updateWidgetPosition` for positional fields. |
 | `removeWidget` | `(id: string) => void` | Remove a widget from the active workspace. |
-| `updateWidgetPosition` | `(pageId, widgetId, x, y, cols, rows) => void` | Manually reposition/resize a widget. |
+| `updateWidgetPosition` | `(pageId, widgetId, x, y, cols, rows) => void` | Manually reposition or resize a widget. |
+| `getActivePage` | `() => Page \| undefined` | Returns the currently active `Page` object. |
 | `addPage` | `(name: string) => void` | Add a new workspace tab. |
-| `removePage` | `(id: string) => void` | Remove a workspace tab (minimum 1 kept). |
-| `setActivePage` | `(id: string) => void` | Switch to a workspace by id. |
-| `popOutPage` | `(id: string) => void` | Open a workspace in its own browser window. |
+| `removePage` | `(id: string) => void` | Remove a workspace tab (at least one is always kept). |
+| `setActivePage` | `(id: string) => void` | Switch the active workspace by id. |
+| `popOutPage` | `(id: string) => void` | Open a workspace in a separate browser window. |
 | `loadLayout` | `(config: DashboardConfig) => void` | Load a full layout object (parsed from `serializeLayout`). |
 | `serializeLayout` | `() => string` | Serialize the full layout to a JSON string. |
 
@@ -160,73 +177,163 @@ constructor(private state: DashboardStateService) {}
 
 | Observable | Type | Description |
 |---|---|---|
-| `pages$` | `Observable<Page[]>` | Emits the full page list on every change. |
-| `activePageId$` | `Observable<string>` | Emits the active workspace id on every change. |
+| `pages$` | `Observable<Page[]>` | Emits whenever the page list changes. |
+| `activePageId$` | `Observable<string>` | Emits whenever the active workspace changes. |
+
+---
+
+### `app-grid` (Advanced)
+
+The raw grid engine, exported for advanced use cases. `app-dashboard` uses this internally.
+
+```html
+<app-grid
+  [widgets]="myWidgets"
+  [columns]="12"
+  [gap]="16"
+  [rowHeight]="80"
+  (itemChanged)="onItemChanged($event)"
+  (layoutChanged)="onLayoutChanged($event)"
+>
+  <ng-template gridCell let-widget="widget">
+    <!-- your card here -->
+  </ng-template>
+</app-grid>
+```
+
+#### Inputs
+
+| Input | Type | Default | Description |
+|---|---|---|---|
+| `widgets` | `Widget[]` | `[]` | The widgets to render. |
+| `columns` | `number` | `12` | Number of grid columns. |
+| `gap` | `number` | `16` | Gap between cells in pixels. |
+| `rowHeight` | `number` | `80` | Height of one grid row in pixels. |
+| `minItemCols` | `number` | `1` | Minimum column span during resize. |
+| `minItemRows` | `number` | `1` | Minimum row span during resize. |
+
+#### Outputs
+
+| Output | Payload | Description |
+|---|---|---|
+| `itemChanged` | `Widget` | Fires after a single widget is moved or resized. |
+| `layoutChanged` | `Widget[]` | Fires after any move or resize with the full updated list. |
 
 ---
 
+### Public Exports
+
+```typescript
+export { DashboardModule }          from '@ogidor/dashboard';
+export { DashboardComponent }       from '@ogidor/dashboard';
+export { WidgetRendererComponent }  from '@ogidor/dashboard';
+export { CustomGridComponent }      from '@ogidor/dashboard';
+export { GridCellDirective }        from '@ogidor/dashboard';
+export { DashboardStateService }    from '@ogidor/dashboard';
+export { Widget, Page, DashboardConfig, DashboardTheme } from '@ogidor/dashboard';
+```
+
+---
+
+## Models
+
 ### `Widget`
 
 ```typescript
 export interface Widget {
-  id: string;       // auto-generated — do not set manually
-  x: number;        // grid column (0-based)
-  y: number;        // grid row (0-based)
-  cols: number;     // column span (default: 4)
-  rows: number;     // row span (default: 3)
-  title: string;    // displayed in the card header
-  cardColor?: string; // optional background color for this card
-  data?: any;       // your custom payload — stored & synced, never inspected
+  id: string;          // auto-generated — do not set manually
+  x: number;           // grid column, 0-based
+  y: number;           // grid row, 0-based
+  cols: number;        // column span (default: 4)
+  rows: number;        // row span (default: 3)
+  title: string;       // shown in the card header
+  cardColor?: string;  // per-card background — overrides the global widgetCardColor
+  data?: any;          // custom payload — stored and synced, never inspected
 }
 ```
 
----
+### `Page`
 
-### `DashboardTheme`
+```typescript
+export interface Page {
+  id: string;
+  name: string;
+  widgets: Widget[];
+}
+```
+
+### `DashboardConfig`
+
+```typescript
+export interface DashboardConfig {
+  pages: Page[];
+  activePageId: string;
+}
+```
 
-All fields are optional. Any omitted field falls back to its default.
+### `DashboardTheme`
 
 ```typescript
 export interface DashboardTheme {
-  // ── Layout ──
-  backgroundColor?:          string; // wrapper background              default: #000000
-  panelColor?:               string; // main panel background           default: #1c1c1e
-  widgetCardColor?:          string; // card background (global)        default: #2c2c2e
-  foreColor?:                string; // text / labels                   default: #8e8e93
-  accentColor?:              string; // buttons, active states          default: #0a84ff
-  dangerColor?:              string; // remove / close actions          default: #ff453a
-  fontFamily?:               string; // applied globally                default: system-ui stack
-
-  // ── Header / Tabs ──
-  tabsContainerColor?:       string; // tabs pill background            default: rgba(44,44,46,0.6)
-  tabActiveColor?:           string; // active tab background           default: #3a3a3c
-  tabActiveTextColor?:       string; // active tab text                 default: #ffffff
-  tabHoverTextColor?:        string; // hovered tab text                default: #e5e5ea
-  addWidgetButtonTextColor?: string; // "Add Widget" button text        default: #ffffff
-
-  // ── Pop-out window ──
-  popoutTitleColor?:         string; // pop-out window title text       default: #ffffff
-
-  // ── Widget card ──
-  widgetTitleColor?:         string; // card title text                 default: #ffffff
-  dragHandleColor?:          string; // drag-handle dot icon            default: rgba(255,255,255,0.2)
-  widgetBorderColor?:        string; // card border                     default: rgba(255,255,255,0.07)
-  widgetButtonBgColor?:      string; // edit/remove button background   default: rgba(255,255,255,0.07)
-  widgetButtonColor?:        string; // edit/remove button icon         default: rgba(255,255,255,0.5)
-
-  // ── Grid ──
-  placeholderColor?:         string; // drag/resize ghost overlay       default: #0a84ff (accentColor)
-  resizeHandleColor?:        string; // resize handle icon              default: rgba(255,255,255,0.25)
+  // Layout
+  backgroundColor?:          string;  // outer wrapper          default: #000000
+  panelColor?:               string;  // main panel             default: #1c1c1e
+  widgetCardColor?:          string;  // card background        default: #2c2c2e
+  foreColor?:                string;  // text / labels          default: #8e8e93
+  accentColor?:              string;  // active states, buttons default: #0a84ff
+  dangerColor?:              string;  // destructive actions    default: #ff453a
+  fontFamily?:               string;  // global font stack      default: system-ui
+
+  // Header & Tabs
+  tabsContainerColor?:       string;  // pill background        default: rgba(44,44,46,0.6)
+  tabActiveColor?:           string;  // active tab bg          default: #3a3a3c
+  tabActiveTextColor?:       string;  // active tab text        default: #ffffff
+  tabHoverTextColor?:        string;  // hovered tab text       default: #e5e5ea
+  addWidgetButtonTextColor?: string;  // Add Widget label       default: #ffffff
+
+  // Pop-out Window
+  popoutTitleColor?:         string;  // pop-out title text     default: #ffffff
+
+  // Widget Card
+  widgetTitleColor?:         string;  // card title             default: #ffffff
+  dragHandleColor?:          string;  // drag dots              default: rgba(255,255,255,0.2)
+  widgetBorderColor?:        string;  // card border            default: rgba(255,255,255,0.07)
+  widgetButtonBgColor?:      string;  // icon button bg         default: rgba(255,255,255,0.07)
+  widgetButtonColor?:        string;  // icon button colour     default: rgba(255,255,255,0.5)
+
+  // Grid
+  placeholderColor?:         string;  // drag ghost overlay     default: #0a84ff
+  resizeHandleColor?:        string;  // resize icon            default: rgba(255,255,255,0.25)
 }
 ```
 
-> **Tip:** you can also override individual widget card colors without touching the theme — set `cardColor` on any `Widget` object and it takes priority over `widgetCardColor`.
+> **Per-card colour:** set `cardColor` on any `Widget` to override `widgetCardColor` for just that one card.
 
 ---
 
-## CSS Custom Properties
+## Theming
+
+### Theme Input
 
-You can theme the dashboard entirely via CSS in your global stylesheet instead of (or alongside) the `theme` input. Every `DashboardTheme` property maps 1-to-1 to a CSS custom property:
+Pass a partial `DashboardTheme` to `[theme]`. Only provided fields are overridden.
+
+```typescript
+theme: DashboardTheme = {
+  accentColor:        '#6c63ff',
+  tabActiveColor:     '#2a2a38',
+  tabActiveTextColor: '#ffffff',
+  widgetTitleColor:   '#f0f0f0',
+  placeholderColor:   '#6c63ff',
+};
+```
+
+```html
+<app-dashboard [theme]="theme"></app-dashboard>
+```
+
+### CSS Custom Properties
+
+Every token is also available as a CSS variable. Use them in your global stylesheet:
 
 ```css
 app-dashboard {
@@ -246,7 +353,7 @@ app-dashboard {
   --dash-tab-hover-text:       #d0d0d5;
   --dash-add-widget-text:      #ffffff;
 
-  /* Pop-out window */
+  /* Pop-out */
   --dash-popout-title-color:   #ffffff;
 
   /* Widget card */
@@ -262,9 +369,9 @@ app-dashboard {
 }
 ```
 
-### CSS variable reference
+### CSS Variable Reference
 
-| CSS Variable | `DashboardTheme` property | Default |
+| CSS Variable | `DashboardTheme` field | Default |
 |---|---|---|
 | `--dash-bg` | `backgroundColor` | `#000000` |
 | `--dash-panel-bg` | `panelColor` | `#1c1c1e` |
@@ -291,32 +398,24 @@ app-dashboard {
 
 ## Pop-out Windows
 
-Every workspace tab has a **pop-out** button (the arrow icon, visible on hover). Clicking it opens that workspace in a separate browser window.
+Every workspace tab shows a pop-out button (arrow icon, visible on hover). Clicking it opens that workspace in a new browser window.
 
-The popped-out window:
-- shows only that one workspace — no tabs, no "Add Widget" bar, just the grid
-- has its **own independent card layout** — dragging and resizing cards there does not affect any other window
-- **does** receive structural changes from other windows in real time
+The pop-out window:
 
-### What syncs and what doesn't
+- Shows only that workspace — no tabs, no Add Widget button, just the grid.
+- Has its **own independent layout** — moving cards there never affects the main window.
+- **Receives** structural changes (add/remove widget, metadata edits) from all other windows in real time.
 
-The library separates two kinds of state:
+### Sync behaviour
 
-| State | Synced across windows? | Stored where |
+| State | Synced across windows? | Stored in |
 |---|---|---|
-| Page list (add / remove / rename workspace) | ✅ Yes | `ogidor_shared` in localStorage |
-| Widget list (add / remove a card) | ✅ Yes | `ogidor_shared` in localStorage |
-| Widget metadata (title, card color, data) | ✅ Yes | `ogidor_shared` in localStorage |
-| Card positions and sizes (drag / resize) | ❌ No — local only | `ogidor_positions_<windowId>` |
-
-**Example:** you have your main dashboard open in Tab A, and you pop out "Workspace 2" into Window B.
+| Page list (add / remove / rename) | Yes | `ogidor_shared` |
+| Widget list (add / remove) | Yes | `ogidor_shared` |
+| Widget metadata (title, cardColor, data) | Yes | `ogidor_shared` |
+| Card positions and sizes | No — per window | `ogidor_positions_<windowId>` |
 
-- You drag a card in **Window B** → it stays where you put it in B; Tab A is completely unaffected
-- You add a widget from **Tab A** → the new card appears in **Window B** at its default position
-- You delete a widget in **Window B** → it disappears from **Tab A** immediately
-- Each window remembers its own layout between page reloads
-
-To pop out a workspace programmatically:
+To pop out programmatically:
 
 ```typescript
 this.state.popOutPage(pageId);
@@ -326,32 +425,39 @@ this.state.popOutPage(pageId);
 
 ## Persisting Layouts
 
-The library automatically persists state to `localStorage` on every change using two keys:
+State is saved to `localStorage` automatically on every change.
 
-| Key | Contains |
+| Key | Contents |
 |---|---|
-| `ogidor_shared` | Page list and widget metadata (titles, colors, data). Shared across all windows. |
-| `ogidor_positions_main` | Card positions/sizes for the main window. |
-| `ogidor_positions_<pageId>` | Card positions/sizes for each pop-out window, keyed by the workspace id. |
+| `ogidor_shared` | Page list and widget metadata. Shared across all windows. |
+| `ogidor_positions_main` | Grid positions for the main window. |
+| `ogidor_positions_<pageId>` | Grid positions for each pop-out window. |
 
-To save the full current layout to a backend and restore it later:
+To save and restore via a backend:
 
 ```typescript
-// Save (includes this window's positions)
+// Save
 const json = this.dash.serializeLayout();
-await myApi.saveLayout(json);
+await api.save(json);
 
 // Restore
-const json = await myApi.loadLayout();
+const json = await api.load();
 this.dash.stateService.loadLayout(JSON.parse(json));
 ```
 
 ---
 
-## Example: Full Integration
+## Full Integration Example
 
 ```typescript
-// app.component.ts
+import { Component, ViewChild } from '@angular/core';
+import {
+  DashboardComponent,
+  DashboardStateService,
+  DashboardTheme,
+  Widget,
+} from '@ogidor/dashboard';
+
 @Component({
   selector: 'app-root',
   template: `
@@ -365,38 +471,38 @@ this.dash.stateService.loadLayout(JSON.parse(json));
       </ng-template>
     </app-dashboard>
 
-    <!-- Your own add/edit dialogs -->
-    <my-add-widget-dialog
+    <my-add-dialog
       *ngIf="addOpen"
       (confirmed)="onAddConfirmed($event)"
       (cancelled)="addOpen = false"
-    ></my-add-widget-dialog>
+    ></my-add-dialog>
 
-    <my-edit-widget-dialog
+    <my-edit-dialog
       *ngIf="editTarget"
       [widget]="editTarget"
       (confirmed)="onEditConfirmed($event)"
       (cancelled)="editTarget = null"
-    ></my-edit-widget-dialog>
+    ></my-edit-dialog>
   `,
 })
 export class AppComponent {
+  @ViewChild(DashboardComponent) dash!: DashboardComponent;
+
   theme: DashboardTheme = {
-    accentColor:        '#6c63ff',
-    placeholderColor:   '#6c63ff',
-    tabActiveColor:     '#2a2a38',
-    tabActiveTextColor: '#ffffff',
-    widgetTitleColor:   '#f0f0f0',
+    accentColor:     '#6c63ff',
+    tabActiveColor:  '#2a2a38',
+    widgetTitleColor: '#f0f0f0',
   };
+
   addOpen = false;
   editTarget: Widget | null = null;
 
   constructor(private state: DashboardStateService) {}
 
-  openAddDialog()              { this.addOpen = true; }
-  openEditDialog(w: Widget)    { this.editTarget = w; }
+  openAddDialog()           { this.addOpen = true; }
+  openEditDialog(w: Widget) { this.editTarget = w; }
 
-  onAddConfirmed(payload: { title: string; data: any; cols: number; rows: number }) {
+  onAddConfirmed(payload: Partial<Widget> & { title: string }) {
     this.state.addWidget(payload);
     this.addOpen = false;
   }
@@ -405,11 +511,30 @@ export class AppComponent {
     this.state.updateWidget(this.editTarget!.id, patch);
     this.editTarget = null;
   }
+
+  saveLayout() {
+    return this.dash.serializeLayout();
+  }
 }
 ```
 
 ---
 
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build the library
+npm run build:lib
+
+# Run the local demo app
+npm start
+```
+
+---
+
 ## License
 
 MIT