@dragonworks/ngx-dashboard 20.2.0 → 20.3.1

package/index.d.ts

@@ -4,6 +4,8 @@ import { Type, ViewContainerRef, ComponentRef, OnChanges, SimpleChanges, Injecti
 import * as _ngrx_signals from '@ngrx/signals';
 import { SafeHtml } from '@angular/platform-browser';
 
+declare const NGX_DASHBOARD_VERSION = "20.3.1";
+
 /**
  * Branded type for cell identifiers to ensure type safety when working with grid coordinates.
  * This prevents accidentally mixing up row/column numbers with cell IDs.
@@ -86,6 +88,13 @@ interface DashboardDataDto {
     gutterSize: string;
     /** Array of serializable cell data */
     cells: CellDataDto[];
+    /**
+     * Shared states for widget families (optional).
+     * Maps widget type ID to shared state object.
+     * This allows widget families to share configuration across all instances.
+     * @since 1.1.0
+     */
+    sharedStates?: Record<string, unknown>;
 }
 /**
  * Serializable version of CellData that can be safely JSON stringified.
@@ -145,6 +154,20 @@ type DragData = {
     content: WidgetMetadata;
 };
 
+/**
+ * Represents a rectangular selection region in the dashboard grid
+ */
+interface GridSelection {
+    topLeft: {
+        row: number;
+        col: number;
+    };
+    bottomRight: {
+        row: number;
+        col: number;
+    };
+}
+
 /**
  * Defines space that should be reserved around the dashboard component
  * when calculating viewport constraints.
@@ -160,6 +183,110 @@ interface ReservedSpace {
     left: number;
 }
 
+/**
+ * Options for filtering and exporting a selection of the dashboard.
+ *
+ * Used when exporting a subset of the dashboard based on a grid selection.
+ * Provides control over how the selection bounds are calculated and applied.
+ */
+interface SelectionFilterOptions {
+    /**
+     * If true, shrink the export bounds to the minimal bounding box containing all widgets.
+     * If false or undefined (default), use the selection bounds as-is.
+     *
+     * When enabled, the exported dashboard will be tightly cropped to only include
+     * the space occupied by widgets, removing any empty cells around the edges.
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // Export with minimal bounds (tight crop around widgets)
+     * const data = dashboard.exportDashboard(selection, { useMinimalBounds: true });
+     *
+     * // Export with full selection bounds (preserve empty space)
+     * const data = dashboard.exportDashboard(selection, { useMinimalBounds: false });
+     * ```
+     */
+    useMinimalBounds?: boolean;
+    /**
+     * Number of cells to add as padding on each side of the export bounds.
+     *
+     * Padding expands the export area by adding empty cells around the selection.
+     * A padding value of 1 adds 1 row above, 1 row below, 1 column to the left,
+     * and 1 column to the right of the bounds.
+     *
+     * When used with `useMinimalBounds: true`, padding is applied AFTER the bounds
+     * are shrunk to the minimal bounding box containing all widgets.
+     *
+     * The minimum row and column values are clamped to 1 (grid coordinates are 1-based),
+     * so padding will not extend below the grid origin.
+     *
+     * @default 0
+     *
+     * @example
+     * ```typescript
+     * // Export with 1 cell of padding on all sides
+     * const data = dashboard.exportDashboard(selection, { padding: 1 });
+     *
+     * // Export with minimal bounds and 2 cells of padding
+     * const data = dashboard.exportDashboard(selection, {
+     *   useMinimalBounds: true,
+     *   padding: 2
+     * });
+     * ```
+     */
+    padding?: number;
+}
+
+/**
+ * Interface for providing shared state across all instances of a widget type.
+ *
+ * Widget families can implement this interface to manage state that should be
+ * shared across all instances of that widget type (e.g., theme colors, configuration).
+ *
+ * During dashboard serialization, the framework calls getSharedState() once per
+ * widget type (not per instance), and during deserialization, setSharedState()
+ * is called to restore the shared configuration.
+ *
+ * @example
+ * ```typescript
+ * @Injectable({ providedIn: 'root' })
+ * export class ParkingSpaceSharedState implements WidgetSharedStateProvider<ParkingConfig> {
+ *   private state = signal<ParkingConfig>({ color: '#4CAF50', pricePerHour: 5 });
+ *
+ *   getSharedState(): ParkingConfig {
+ *     return this.state();
+ *   }
+ *
+ *   setSharedState(state: ParkingConfig): void {
+ *     this.state.set(state);
+ *   }
+ *
+ *   readonly config = this.state.asReadonly();
+ * }
+ *
+ * // Register with dashboard
+ * dashboardService.registerWidgetType(ParkingSpaceWidget, ParkingSpaceSharedState);
+ * ```
+ */
+interface WidgetSharedStateProvider<T = unknown> {
+    /**
+     * Gets the current shared state for this widget type.
+     * Called during dashboard export/serialization.
+     *
+     * @returns The current shared state, or undefined if no state should be serialized
+     */
+    getSharedState(): T | undefined;
+    /**
+     * Sets the shared state for this widget type.
+     * Called during dashboard import/deserialization before widget instances are created.
+     *
+     * @param state The shared state to restore
+     */
+    setSharedState(state: T): void;
+}
+
 interface ResizeData {
     cellId: CellId;
     originalRowSpan: number;
@@ -283,9 +410,8 @@ declare class DashboardComponent implements OnChanges {
         startResize: (cellId: CellId) => void;
         updateResizePreview: (direction: "horizontal" | "vertical", delta: number) => void;
         endResize: (apply: boolean) => void;
-        exportDashboard: (getCurrentWidgetStates?: () => Map<string, unknown>) => DashboardDataDto;
+        exportDashboard: (getCurrentWidgetStates?: () => Map<string, unknown>, selection?: GridSelection, selectionOptions?: SelectionFilterOptions) => DashboardDataDto;
         loadDashboard: (data: DashboardDataDto) => void;
-        initializeFromDto: (dashboardData: DashboardDataDto) => void;
     } & _ngrx_signals.StateSource<{
         dashboardId: string;
         rows: number;
@@ -308,17 +434,25 @@ declare class DashboardComponent implements OnChanges {
     dashboardData: _angular_core.InputSignal<DashboardDataDto>;
     editMode: _angular_core.InputSignal<boolean>;
     reservedSpace: _angular_core.InputSignal<ReservedSpace | undefined>;
+    enableSelection: _angular_core.InputSignal<boolean>;
+    selectionComplete: _angular_core.OutputEmitterRef<GridSelection>;
     cells: _angular_core.Signal<CellData[]>;
     private dashboardEditor;
     private dashboardViewer;
     constructor();
     ngOnChanges(changes: SimpleChanges): void;
+    /**
+     * Get current widget states from all cell components.
+     * Used during dashboard export to get live widget states.
+     */
+    private getCurrentWidgetStates;
     exportDashboard(): DashboardDataDto;
+    exportDashboard(selection: GridSelection, options?: SelectionFilterOptions): DashboardDataDto;
     loadDashboard(data: DashboardDataDto): void;
     getCurrentDashboardData(): DashboardDataDto;
     clearDashboard(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DashboardComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DashboardComponent, "ngx-dashboard", never, { "dashboardData": { "alias": "dashboardData"; "required": true; "isSignal": true; }; "editMode": { "alias": "editMode"; "required": false; "isSignal": true; }; "reservedSpace": { "alias": "reservedSpace"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<DashboardComponent, "ngx-dashboard", never, { "dashboardData": { "alias": "dashboardData"; "required": true; "isSignal": true; }; "editMode": { "alias": "editMode"; "required": false; "isSignal": true; }; "reservedSpace": { "alias": "reservedSpace"; "required": false; "isSignal": true; }; "enableSelection": { "alias": "enableSelection"; "required": false; "isSignal": true; }; }, { "selectionComplete": "selectionComplete"; }, never, never, true, never>;
 }
 
 interface WidgetDisplayItem extends WidgetMetadata {
@@ -326,6 +460,7 @@ interface WidgetDisplayItem extends WidgetMetadata {
 }
 declare class WidgetListComponent {
     #private;
+    collapsed: _angular_core.InputSignal<boolean>;
     activeWidget: _angular_core.WritableSignal<string | null>;
     gridCellDimensions: _angular_core.Signal<{
         width: number;
@@ -342,14 +477,36 @@ declare class WidgetListComponent {
     onDragEnd(): void;
     getWidgetAriaLabel(widget: WidgetDisplayItem): string;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<WidgetListComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WidgetListComponent, "ngx-dashboard-widget-list", never, {}, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<WidgetListComponent, "ngx-dashboard-widget-list", never, { "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 declare class DashboardService {
     #private;
     readonly widgetTypes: _angular_core.Signal<WidgetComponentClass<_dragonworks_ngx_dashboard.Widget>[]>;
-    registerWidgetType(widget: WidgetComponentClass): void;
+    registerWidgetType<T = unknown>(widget: WidgetComponentClass, sharedStateProvider?: WidgetSharedStateProvider<T> | Type<WidgetSharedStateProvider<T>>): void;
     getFactory(widgetTypeid: string): WidgetFactory;
+    /**
+     * Get the shared state provider for a specific widget type.
+     *
+     * @param widgetTypeid The widget type identifier
+     * @returns The shared state provider, or undefined if none is registered
+     */
+    getSharedStateProvider(widgetTypeid: string): WidgetSharedStateProvider | undefined;
+    /**
+     * Collect shared states for all widget types currently on the dashboard.
+     * Called during dashboard export/serialization.
+     *
+     * @param activeWidgetTypes Set of widget type IDs that are currently in use
+     * @returns Map of widget type IDs to their shared states
+     */
+    collectSharedStates(activeWidgetTypes: Set<string>): Map<string, unknown>;
+    /**
+     * Restore shared states for widget types.
+     * Called during dashboard import/deserialization, before widget instances are created.
+     *
+     * @param states Map of widget type IDs to their shared states
+     */
+    restoreSharedStates(states: Map<string, unknown>): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<DashboardService, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<DashboardService>;
 }
@@ -390,5 +547,120 @@ declare class DefaultCellSettingsDialogProvider extends CellSettingsDialogProvid
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<DefaultCellSettingsDialogProvider>;
 }
 
-export { CELL_SETTINGS_DIALOG_PROVIDER, CellSettingsDialogProvider, DashboardComponent, DashboardService, DefaultCellSettingsDialogProvider, WidgetListComponent, createDefaultDashboard, createEmptyDashboard };
-export type { CellDataDto, DashboardDataDto, ReservedSpace, Widget, WidgetMetadata };
+/**
+ * Context information about the empty cell that was clicked
+ */
+interface EmptyCellContext {
+    /** The row position in the grid (1-indexed) */
+    row: number;
+    /** The column position in the grid (1-indexed) */
+    col: number;
+    /** Total number of rows in the dashboard */
+    totalRows: number;
+    /** Total number of columns in the dashboard */
+    totalColumns: number;
+    /** The gutter size between cells (e.g., '1em') */
+    gutterSize: string;
+    /**
+     * Optional callback to create a widget at this position.
+     * When provided, allows the context provider to create widgets directly.
+     *
+     * @param widgetTypeid - The widget type identifier to create
+     * @returns true if widget was created successfully, false otherwise
+     */
+    createWidget?: (widgetTypeid: string) => boolean;
+}
+/**
+ * Abstract provider for handling context menu events on empty dashboard cells.
+ * Implement this to provide custom behavior when users right-click on unoccupied grid spaces.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * export class CustomEmptyCellProvider extends EmptyCellContextProvider {
+ *   handleEmptyCellContext(event: MouseEvent, context: EmptyCellContext): void {
+ *     event.preventDefault();
+ *     // Show custom menu, open dialog, etc.
+ *   }
+ * }
+ * ```
+ */
+declare abstract class EmptyCellContextProvider {
+    /**
+     * Handle context menu event on an empty dashboard cell.
+     *
+     * @param event - The mouse event from the right-click
+     * @param context - Information about the empty cell and dashboard
+     */
+    abstract handleEmptyCellContext(event: MouseEvent, context: EmptyCellContext): void;
+}
+
+/**
+ * Injection token for the empty cell context provider.
+ * Use this to provide your custom implementation for handling right-clicks on empty dashboard cells.
+ *
+ * @example
+ * ```typescript
+ * // Provide a custom implementation
+ * providers: [
+ *   {
+ *     provide: EMPTY_CELL_CONTEXT_PROVIDER,
+ *     useClass: MyCustomEmptyCellProvider
+ *   }
+ * ]
+ * ```
+ */
+declare const EMPTY_CELL_CONTEXT_PROVIDER: InjectionToken<EmptyCellContextProvider>;
+
+/**
+ * Default empty cell context provider that prevents the browser's context menu
+ * and performs no other action.
+ *
+ * This is the default behavior that allows users to right-click on empty dashboard
+ * cells without triggering the browser's default context menu.
+ */
+declare class DefaultEmptyCellContextProvider extends EmptyCellContextProvider {
+    /**
+     * Default empty cell context handler.
+     * The browser context menu is already prevented by the component.
+     * No additional action is taken by default.
+     */
+    handleEmptyCellContext(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<DefaultEmptyCellContextProvider, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<DefaultEmptyCellContextProvider>;
+}
+
+/**
+ * Context provider that displays a widget list menu when right-clicking on empty cells.
+ *
+ * This provider shows a Material Design context menu with all available widget types.
+ * When a user clicks on a widget in the menu, it's immediately added to the empty cell.
+ *
+ * @example
+ * ```typescript
+ * // In your component or app config
+ * providers: [
+ *   {
+ *     provide: EMPTY_CELL_CONTEXT_PROVIDER,
+ *     useClass: WidgetListContextMenuProvider
+ *   }
+ * ]
+ * ```
+ *
+ * @public
+ */
+declare class WidgetListContextMenuProvider extends EmptyCellContextProvider {
+    #private;
+    /**
+     * Handle empty cell context menu by showing available widgets.
+     *
+     * @param event - The mouse event from the right-click
+     * @param context - Information about the empty cell and dashboard
+     */
+    handleEmptyCellContext(event: MouseEvent, context: EmptyCellContext): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WidgetListContextMenuProvider, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<WidgetListContextMenuProvider>;
+}
+
+export { CELL_SETTINGS_DIALOG_PROVIDER, CellSettingsDialogProvider, DashboardComponent, DashboardService, DefaultCellSettingsDialogProvider, DefaultEmptyCellContextProvider, EMPTY_CELL_CONTEXT_PROVIDER, EmptyCellContextProvider, NGX_DASHBOARD_VERSION, WidgetListComponent, WidgetListContextMenuProvider, createDefaultDashboard, createEmptyDashboard };
+export type { CellDataDto, DashboardDataDto, EmptyCellContext, GridSelection, ReservedSpace, SelectionFilterOptions, Widget, WidgetMetadata, WidgetSharedStateProvider };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dragonworks/ngx-dashboard",
-  "version": "20.2.0",
+  "version": "20.3.1",
   "description": "Angular library for building drag-and-drop grid dashboards with resizable cells and customizable widgets",
   "peerDependencies": {
     "@angular/common": "^20.2.0",