@dragonworks/ngx-dashboard 20.0.5 → 20.1.0

package/index.d.ts

@@ -56,6 +56,53 @@ declare const CellIdUtils: {
     equals(a: CellId, b: CellId): boolean;
 };
 
+/**
+ * Branded type for widget identifiers to ensure type safety when working with widget instances.
+ * This prevents accidentally mixing up widget IDs with other string values.
+ */
+type WidgetId = string & {
+    __brand: 'WidgetId';
+};
+/**
+ * Utility functions for working with WidgetId branded type.
+ * WidgetIds are UUIDs that uniquely identify widget instances throughout their lifecycle,
+ * independent of their position on the dashboard grid.
+ */
+declare const WidgetIdUtils: {
+    /**
+     * Generates a new unique WidgetId.
+     * Uses crypto.randomUUID() when available, falls back to timestamp-based ID for older browsers.
+     * @returns A new unique WidgetId
+     */
+    generate(): WidgetId;
+    /**
+     * Validates if a string is a valid WidgetId format.
+     * @param id - The string to validate
+     * @returns True if the string is a valid WidgetId format
+     */
+    validate(id: string): id is WidgetId;
+    /**
+     * Converts a WidgetId to a string for use as map keys or serialization.
+     * @param id - The WidgetId to convert
+     * @returns The string representation of the WidgetId
+     */
+    toString(id: WidgetId): string;
+    /**
+     * Creates a WidgetId from a string, validating the format.
+     * @param str - The string to convert to WidgetId
+     * @returns A WidgetId
+     * @throws Error if the string is not a valid WidgetId format
+     */
+    fromString(str: string): WidgetId;
+    /**
+     * Checks if two WidgetIds are equal.
+     * @param a - First WidgetId
+     * @param b - Second WidgetId
+     * @returns True if the WidgetIds are the same
+     */
+    equals(a: WidgetId, b: WidgetId): boolean;
+};
+
 interface Widget {
     dashboardGetState?(): unknown;
     dashboardSetState?(state?: unknown): void;
@@ -88,9 +135,11 @@ interface CellPosition {
 }
 interface CellComponentPosition extends CellPosition {
     cellId: CellId;
+    widgetId: WidgetId;
 }
 
 interface CellData extends CellPosition {
+    widgetId: WidgetId;
     cellId: CellId;
     flat?: boolean;
     widgetFactory: WidgetFactory;
@@ -271,7 +320,7 @@ declare class DashboardComponent implements OnChanges {
             width: number;
             height: number;
         }>;
-        cellsById: _angular_core.Signal<Record<string, _dragonworks_ngx_dashboard.CellData>>;
+        widgetsById: _angular_core.Signal<Record<string, _dragonworks_ngx_dashboard.CellData>>;
         resizeData: _angular_core.Signal<ResizeData | null>;
         dragData: _angular_core.Signal<_dragonworks_ngx_dashboard.DragData | null>;
         hoveredDropZone: _angular_core.Signal<{
@@ -301,15 +350,14 @@ declare class DashboardComponent implements OnChanges {
         toggleEditMode: () => void;
         setEditMode: (isEditMode: boolean) => void;
         addWidget: (cell: _dragonworks_ngx_dashboard.CellData) => void;
-        removeWidget: (cellId: _dragonworks_ngx_dashboard.CellId) => void;
-        updateWidgetPosition: (cellId: _dragonworks_ngx_dashboard.CellId, row: number, col: number) => void;
+        removeWidget: (widgetId: _dragonworks_ngx_dashboard.WidgetId) => void;
+        updateWidgetPosition: (widgetId: _dragonworks_ngx_dashboard.WidgetId, row: number, col: number) => void;
         createWidget: (row: number, col: number, widgetFactory: _dragonworks_ngx_dashboard.WidgetFactory, widgetState?: string) => void;
-        updateCellSettings: (id: _dragonworks_ngx_dashboard.CellId, flat: boolean) => void;
-        updateWidgetSpan: (id: _dragonworks_ngx_dashboard.CellId, rowSpan: number, colSpan: number) => void;
-        updateWidgetState: (cellId: _dragonworks_ngx_dashboard.CellId, widgetState: unknown) => void;
-        updateAllWidgetStates: (widgetStates: Map<string, unknown>) => void;
+        updateCellSettings: (widgetId: _dragonworks_ngx_dashboard.WidgetId, flat: boolean) => void;
+        updateWidgetSpan: (widgetId: _dragonworks_ngx_dashboard.WidgetId, rowSpan: number, colSpan: number) => void;
+        updateWidgetState: (widgetId: _dragonworks_ngx_dashboard.WidgetId, widgetState: unknown) => void;
+        updateAllWidgetStates: (cellStates: Map<string, unknown>) => void;
         clearDashboard: () => void;
-        syncDragState: (dragData: _dragonworks_ngx_dashboard.DragData | null) => void;
         startDrag: (dragData: _dragonworks_ngx_dashboard.DragData) => void;
         endDrag: () => void;
         setHoveredDropZone: (zone: {
@@ -336,7 +384,7 @@ declare class DashboardComponent implements OnChanges {
             width: number;
             height: number;
         };
-        cellsById: Record<string, _dragonworks_ngx_dashboard.CellData>;
+        widgetsById: Record<string, _dragonworks_ngx_dashboard.CellData>;
         resizeData: ResizeData | null;
         dragData: _dragonworks_ngx_dashboard.DragData | null;
         hoveredDropZone: {
@@ -363,7 +411,8 @@ declare class DashboardComponent implements OnChanges {
 
 declare class CellComponent {
     #private;
-    id: _angular_core.InputSignal<CellId>;
+    widgetId: _angular_core.InputSignal<WidgetId>;
+    cellId: _angular_core.InputSignal<CellId>;
     widgetFactory: _angular_core.InputSignal<WidgetFactory<Widget> | undefined>;
     widgetState: _angular_core.InputSignal<unknown>;
     isEditMode: _angular_core.InputSignal<boolean>;
@@ -375,23 +424,23 @@ declare class CellComponent {
     draggable: _angular_core.InputSignal<boolean>;
     dragStart: _angular_core.OutputEmitterRef<DragData>;
     dragEnd: _angular_core.OutputEmitterRef<void>;
-    edit: _angular_core.OutputEmitterRef<CellId>;
-    delete: _angular_core.OutputEmitterRef<CellId>;
+    edit: _angular_core.OutputEmitterRef<WidgetId>;
+    delete: _angular_core.OutputEmitterRef<WidgetId>;
     settings: _angular_core.OutputEmitterRef<{
-        id: CellId;
+        id: WidgetId;
         flat: boolean;
     }>;
     resizeStart: _angular_core.OutputEmitterRef<{
-        id: CellId;
+        cellId: CellId;
         direction: "horizontal" | "vertical";
     }>;
     resizeMove: _angular_core.OutputEmitterRef<{
-        id: CellId;
+        cellId: CellId;
         direction: "horizontal" | "vertical";
         delta: number;
     }>;
     resizeEnd: _angular_core.OutputEmitterRef<{
-        id: CellId;
+        cellId: CellId;
         apply: boolean;
     }>;
     private container;
@@ -451,7 +500,7 @@ declare class CellComponent {
      */
     getCurrentWidgetState(): unknown | undefined;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<CellComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CellComponent, "lib-cell", never, { "id": { "alias": "id"; "required": true; "isSignal": true; }; "widgetFactory": { "alias": "widgetFactory"; "required": false; "isSignal": true; }; "widgetState": { "alias": "widgetState"; "required": false; "isSignal": true; }; "isEditMode": { "alias": "isEditMode"; "required": false; "isSignal": true; }; "flat": { "alias": "flat"; "required": false; "isSignal": true; }; "row": { "alias": "row"; "required": true; "isSignal": true; }; "column": { "alias": "column"; "required": true; "isSignal": true; }; "rowSpan": { "alias": "rowSpan"; "required": false; "isSignal": true; }; "colSpan": { "alias": "colSpan"; "required": false; "isSignal": true; }; "draggable": { "alias": "draggable"; "required": false; "isSignal": true; }; }, { "row": "rowChange"; "column": "columnChange"; "dragStart": "dragStart"; "dragEnd": "dragEnd"; "edit": "edit"; "delete": "delete"; "settings": "settings"; "resizeStart": "resizeStart"; "resizeMove": "resizeMove"; "resizeEnd": "resizeEnd"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CellComponent, "lib-cell", never, { "widgetId": { "alias": "widgetId"; "required": true; "isSignal": true; }; "cellId": { "alias": "cellId"; "required": true; "isSignal": true; }; "widgetFactory": { "alias": "widgetFactory"; "required": false; "isSignal": true; }; "widgetState": { "alias": "widgetState"; "required": false; "isSignal": true; }; "isEditMode": { "alias": "isEditMode"; "required": false; "isSignal": true; }; "flat": { "alias": "flat"; "required": false; "isSignal": true; }; "row": { "alias": "row"; "required": true; "isSignal": true; }; "column": { "alias": "column"; "required": true; "isSignal": true; }; "rowSpan": { "alias": "rowSpan"; "required": false; "isSignal": true; }; "colSpan": { "alias": "colSpan"; "required": false; "isSignal": true; }; "draggable": { "alias": "draggable"; "required": false; "isSignal": true; }; }, { "row": "rowChange"; "column": "columnChange"; "dragStart": "dragStart"; "dragEnd": "dragEnd"; "edit": "edit"; "delete": "delete"; "settings": "settings"; "resizeStart": "resizeStart"; "resizeMove": "resizeMove"; "resizeEnd": "resizeEnd"; }, never, never, true, never>;
 }
 
 declare class DropZoneComponent {
@@ -525,9 +574,9 @@ declare class DashboardEditorComponent {
     createCellId(row: number, col: number): CellId;
     constructor();
     addWidget: (cellData: CellData) => void;
-    updateCellPosition: (id: CellId, row: number, column: number) => void;
-    updateCellSpan: (id: CellId, colSpan: number, rowSpan: number) => void;
-    updateCellSettings: (id: CellId, flat: boolean) => void;
+    updateCellPosition: (id: WidgetId, row: number, column: number) => void;
+    updateCellSpan: (id: WidgetId, colSpan: number, rowSpan: number) => void;
+    updateCellSettings: (id: WidgetId, flat: boolean) => void;
     onDragOver: (event: {
         row: number;
         col: number;
@@ -538,28 +587,28 @@ declare class DashboardEditorComponent {
     }) => void;
     onDragExit: () => void;
     dragEnd: () => void;
-    onCellDelete: (id: CellId) => void;
+    onCellDelete: (id: WidgetId) => void;
     onCellSettings: (event: {
-        id: CellId;
+        id: WidgetId;
         flat: boolean;
     }) => void;
     onCellResize: (event: {
-        id: CellId;
+        id: WidgetId;
         rowSpan: number;
         colSpan: number;
     }) => void;
     onCellDragStart: (dragData: DragData) => void;
     onCellResizeStart: (event: {
-        id: CellId;
+        cellId: CellId;
         direction: "horizontal" | "vertical";
     }) => void;
     onCellResizeMove: (event: {
-        id: CellId;
+        cellId: CellId;
         direction: "horizontal" | "vertical";
         delta: number;
     }) => void;
     onCellResizeEnd: (event: {
-        id: CellId;
+        cellId: CellId;
         apply: boolean;
     }) => void;
     onDragDrop(event: {
@@ -674,5 +723,5 @@ declare class DefaultCellSettingsDialogProvider extends CellSettingsDialogProvid
  */
 declare const CELL_SETTINGS_DIALOG_PROVIDER: InjectionToken<CellSettingsDialogProvider>;
 
-export { CELL_SETTINGS_DIALOG_PROVIDER, CellIdUtils, CellSettingsDialogProvider, DEFAULT_RESERVED_SPACE, DashboardComponent, DashboardEditorComponent, DashboardService, DashboardViewerComponent, DefaultCellSettingsDialogProvider, WidgetListComponent, createDefaultDashboard, createEmptyDashboard, createFactoryFromComponent };
-export type { CellComponentPosition, CellData, CellDataDto, CellDisplayData, CellId, CellPosition, DashboardDataDto, DragData, ReservedSpace, Widget, WidgetComponentClass, WidgetFactory, WidgetMetadata };
+export { CELL_SETTINGS_DIALOG_PROVIDER, CellIdUtils, CellSettingsDialogProvider, DEFAULT_RESERVED_SPACE, DashboardComponent, DashboardEditorComponent, DashboardService, DashboardViewerComponent, DefaultCellSettingsDialogProvider, WidgetIdUtils, WidgetListComponent, createDefaultDashboard, createEmptyDashboard, createFactoryFromComponent };
+export type { CellComponentPosition, CellData, CellDataDto, CellDisplayData, CellId, CellPosition, DashboardDataDto, DragData, ReservedSpace, Widget, WidgetComponentClass, WidgetFactory, WidgetId, WidgetMetadata };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@dragonworks/ngx-dashboard",
-  "version": "20.0.5",
+  "version": "20.1.0",
   "description": "Angular library for building drag-and-drop grid dashboards with resizable cells and customizable widgets",
   "peerDependencies": {
-    "@angular/common": "^20.0.0",
-    "@angular/core": "^20.0.0",
-    "@angular/material": "^20.0.0",
-    "@angular/cdk": "^20.0.0"
+    "@angular/common": "^20.2.0",
+    "@angular/core": "^20.2.0",
+    "@angular/material": "^20.2.0",
+    "@angular/cdk": "^20.2.0"
   },
   "dependencies": {
     "tslib": "^2.3.0"