@tenorlab/react-dashboard 1.6.5 → 1.6.7

package/dist/core.d.ts

@@ -0,0 +1,591 @@
+export declare const blankDashboardConfig: IDashboardConfig;
+
+/**
+ * @name createDynamicEntry
+ * Helper function to create dynamic entries
+ * This helps keep the catalog registration clean
+ */
+export declare const createDynamicEntry: (key: string, loader: TWidgetFactoryBase, isRemote: boolean, metaData: TWidgetMetaInfoBase) => [string, IDynamicWidgetCatalogEntryBase];
+
+/**
+ * @name createStaticEntry
+ * Helper function to create static entries
+ * This helps keep the catalog registration clean
+ */
+export declare const createStaticEntry: <TFrameworkComponentType = any>(key: string, component: TFrameworkComponentType, metaData?: TWidgetMetaInfoBase) => [string, IDynamicWidgetCatalogEntryBase];
+
+/**
+ * @name cssSettingsCatalog
+ * @description Catalog of available dashboard settings (array of IDashboardSettingEntry)
+ * @see IDashboardSettingEntry
+ * @remarks step should never be less than 0.1 as we do some rounding in other places ...
+ */
+export declare const cssSettingsCatalog: IDashboardSettingEntry[];
+
+/**
+ * @name cssVarsUtils
+ * @description Provides helpers method like getCssVariableValue, setCssVariableValue etc
+ */
+export declare const cssVarsUtils: {
+    /**
+     * @name getCssVariableValue
+     * @description Return the value of a CSS custom property from the current HTML document
+     * @param cssPropertyName
+     * @returns
+     */
+    getCssVariableValue: (cssPropertyName: string) => string | null;
+    /**
+     * @name setCssVariableValue
+     * @description Sets the value of a CSS custom property on the current HTML document
+     * @param cssPropertyName
+     * @param value
+     */
+    setCssVariableValue: (cssPropertyName: string, value: string) => void;
+    /**
+     * @name restoreCssVarsFromSettings
+     * @description
+     * Sets the values of many CSS custom properties on the current HTML document
+     * from the list of dashboard settings provided
+     * @param settings, an array of IDashboardSettingEntry
+     */
+    restoreCssVarsFromSettings: (settings: IDashboardSettingEntry[]) => void;
+};
+
+export declare const DashboardMaxZoomScale: 1;
+
+export declare const DashboardMinZoomScale: 0.7;
+
+/**
+ * @name dashboardSettingsUtils
+ * @description Contains utils for the dashboard custom settings
+ */
+export declare const dashboardSettingsUtils: {
+    /**
+     * @name incrementOrDecrementValue
+     * @description Increments or decrement a value based on the direction parameter
+     * @param item: an instance of IDashboardSettingEntry
+     * @param direction: -1 (for decrement) or 1 (for increment)
+     * @returns the update item
+     */
+    incrementOrDecrementValue: (item: IDashboardSettingEntry, direction: -1 | 1) => IDashboardSettingEntry;
+};
+
+/**
+ * @name dashboardStoreUtils
+ * @description
+ * Framework-agnostic helpers for managing dashboard state. These utilities
+ * are designed to be consumed by specific store implementations.
+ * @see {@link https://www.npmjs.com/package/@tenorlab/react-dashboard | @tenorlab/react-dashboard}
+ * @see {@link https://www.npmjs.com/package/@tenorlab/vue-dashboard | @tenorlab/vue-dashboard}
+ */
+export declare const dashboardStoreUtils: {
+    /**
+     * @name getNextContainerName
+     * @description Generates the next container name based on existing containers in the dashboard configuration
+     * @param dashboardConfig
+     * @returns {string} The next container name in the format 'containerX', where X is the next available number
+     */
+    getNextContainerName: (dashboardConfig: IDashboardConfig) => string;
+    /**
+     * @name getNextContainerKey
+     * @description Generates the next container widget key based on the dashboard configuration and a given container widget key
+     * @param dashboardConfig
+     * @param containerWidgetKey
+     * @returns {TDashboardWidgetKey} The next container widget key
+     */
+    getNextContainerKey: (dashboardConfig: IDashboardConfig, containerWidgetKey: TDashboardWidgetKey) => TDashboardWidgetKey;
+    /**
+     * @description Adds a widget to the configuration. Supports root-level and nested containers.
+     * @param params - Configuration object for adding a widget.
+     * @param params.dashboardConfig - The current {@link IDashboardConfig}.
+     * @param params.widgetKey - The {@link TDashboardWidgetKey} to add.
+     * @param params.parentWidgetKey - Optional parent container key.
+     * @param params.noDuplicatedWidgets - If true, prevents adding the same key twice.
+     * @returns A {@link TCoreResponse} containing the success status and updated config.
+     */
+    addWidget: (params: {
+        dashboardConfig: IDashboardConfig;
+        widgetKey: TDashboardWidgetKey;
+        parentWidgetKey?: TDashboardWidgetKey;
+        noDuplicatedWidgets?: boolean;
+    }) => TCoreResponse<TAddWidgetResponse>;
+    /**
+     * @name removeWidget
+     * @description Removes a widget from the dashboard configuration, either from the root level or from a specified parent container
+     * @param dashboardConfig
+     * @param widgetKey
+     * @param parentWidgetKey
+     * @returns {TCoreResponse<TRemoveWidgetResponse>} The response indicating success or failure and the updated dashboard configuration
+     */
+    removeWidget: (dashboardConfig: IDashboardConfig, widgetKey: TDashboardWidgetKey, parentWidgetKey?: TDashboardWidgetKey) => TCoreResponse<TRemoveWidgetResponse>;
+    /**
+     * @description Moves a widget's position within its current depth (root or container).
+     * @param dashboardConfig - The current {@link IDashboardConfig}.
+     * @param direction - Use `1` for forward/down and `-1` for backward/up.
+     * @param widgetKey - The {@link TDashboardWidgetKey} to move.
+     * @param parentWidgetKey - The container key if the widget is nested.
+     * @returns A {@link TCoreResponse} with the new array order.
+     */
+    moveWidget: (dashboardConfig: IDashboardConfig, direction: -1 | 1, widgetKey: TDashboardWidgetKey, parentWidgetKey?: TDashboardWidgetKey) => TCoreResponse<TMoveWidgetResponse>;
+};
+
+export declare const DashboardZoomStep: 0.05;
+
+/**
+ * @name ensureContainersSequence
+ * @description
+ * Ensures that the container widgets are numbered sequentially in the dashboardConfig, but the original order is preserved.
+ */
+export declare const ensureContainersSequence: (dashboardConfig: IDashboardConfig) => IDashboardConfig;
+
+export declare const ensureZoomScaleIsWithinRange: (value: number) => number;
+
+export declare const getDefaultWidgetMetaFromKey: TGetDefaultWidgetMetaFromKey;
+
+/**
+ * @name getDefaultWidgetMetaFromMap
+ * @description Helper to get widget meta info from the catalog by key.
+ */
+export declare const getDefaultWidgetMetaFromMap: <TFrameworkElementType = any>(widgetKey: TDashboardWidgetKey, defaultWidgetMetaMap: Record<TDashboardWidgetKey, TWidgetMetaInfoBase<TFrameworkElementType>>, options?: {
+    title?: string;
+    description?: string;
+}) => TWidgetMetaInfoBase<TFrameworkElementType>;
+
+/**
+ * @name getDistinctCssClasses
+ * @description Ensures a distinct list off css classes, avoiding duplicates
+ * @param defaultClasses
+ * @param additionalClasses
+ * @returns the distinct list as a string
+ */
+export declare const getDistinctCssClasses: (defaultClasses: string, ...additionalClasses: string[]) => string;
+
+export declare const getMetaInfoFromFile: (widgetMetaModules: Record<string, Record<string, TWidgetMetaInfoBase>>, baseSrcPath: string, folder: string, key: string) => TWidgetMetaInfoBase | undefined;
+
+export declare const getNewZoomScaleWithinRange: (currentZoomScale: number, direction: -1 | 1) => number;
+
+/**
+ * @name getWidgetMetaFromCatalog
+ * @description Helper to get widget meta info from the catalog by key.
+ */
+export declare const getWidgetMetaFromCatalog: <TFrameworkElementType = any, TFrameworkComponentType = any>(widgetKey: TDashboardWidgetKey, widgetsCatalog: TDashboardWidgetCatalogBase<TFrameworkElementType, TFrameworkComponentType>) => TWidgetMetaInfoBase<TFrameworkElementType>;
+
+/**
+ * @name IChildWidgetConfigEntry
+ * @description Interface for a child widget configuration entry
+ * @remarks Used in IDashboardConfig
+ * @see IDashboardConfig
+ */
+export declare interface IChildWidgetConfigEntry {
+    parentWidgetKey: TDashboardWidgetKey;
+    widgetKey: TDashboardWidgetKey;
+}
+
+/**
+ * @name IDashboardConfig
+ * @description Interface for the dashboard configuration
+ * @remarks Used to store the dashboard state
+ * @see IChildWidgetConfigEntry
+ * @see IDashboardSettingEntry
+ */
+export declare interface IDashboardConfig {
+    userID: number | string;
+    clientAppKey: string;
+    dashboardId: string;
+    dashboardName: string;
+    zoomScale: number;
+    responsiveGrid: boolean;
+    widgets: TDashboardWidgetKey[];
+    childWidgetsConfig: IChildWidgetConfigEntry[];
+    savedProps?: IWidgetSavedProps[];
+    cssSettings: IDashboardSettingEntry[];
+    _version?: number;
+    _stateDescription?: string;
+}
+
+/**
+ * @name IDashboardGridPropsBase
+ * @description Base interface for dashboard grid props passed to widgets.
+ * @remarks
+ * - `zoomScale` represents a uniform zoom applied to the dashboard UI. Default
+ *   behavior in the runtime clamps this value to a minimum of `0.7` and default
+ *   is `1` when not explicitly set.
+ * - `responsiveGrid` toggles responsive layout behaviors vs fixed grid sizing.
+ */
+export declare interface IDashboardGridPropsBase {
+    isEditing: boolean;
+    zoomScale: number;
+    responsiveGrid: boolean;
+}
+
+/**
+ * @name IDashboardSettingEntry
+ * @description Interface for a dashboard setting entry
+ * @see cssSettingsCatalog in dashboard-settings.ts
+ */
+export declare interface IDashboardSettingEntry {
+    key: string;
+    name: string;
+    description: string;
+    cssProperty: string;
+    step: number;
+    defaultUnit: string;
+    minValue: number;
+    defaultValue: string;
+    value: string;
+}
+
+/**
+ * @name IDashboardStorageService
+ * @description Interface for the dashboard storage service
+ * @remarks Used to define the storage service methods
+ * @see TGetSavedDashboards
+ * @see TSaveDashboards
+ * @see IDashboardConfig
+ */
+export declare interface IDashboardStorageService {
+    getSavedDashboards: TGetSavedDashboards;
+    saveDashboards: TSaveDashboards;
+}
+
+/**
+ * @name IDashboardWidgetPropsBase
+ * @description Props provided to every widget instance rendered by the dashboard.
+ * @template TExtraProps - Additional, widget-specific props supplied by the
+ * dashboard or integrator via the dynamic loader.
+ * @remarks
+ * - `index` and `maxIndex` indicate the widget's position and the current
+ *   maximum index used for ordering (zero-based indexing is typical).
+ * - `widgetKey` is the stable `TDashboardWidgetKey` identifying the widget
+ *   type; `parentWidgetKey` is set for nested/child widgets.
+ * - Boolean flags like `hideTitle`, `noShadow`, `noBorder`, `noPadding` are
+ *   layout/presentation hints; default behavior should be documented by the
+ *   concrete widget implementation.
+ * - `direction` applies to container widgets only.
+ * - `extraProps` is merged into the widget props by the `DynamicWidgetLoader`.
+ */
+export declare interface IDashboardWidgetPropsBase<TExtraProps = any> {
+    index: number;
+    maxIndex: number;
+    widgetKey: TDashboardWidgetKey;
+    parentWidgetKey?: TDashboardWidgetKey;
+    isEditing: boolean;
+    highlight?: boolean;
+    testId?: string;
+    title?: string;
+    size?: TWidgetSize;
+    borderCssClasses?: string;
+    backgroundCssClasses?: string;
+    addCssClasses?: string;
+    overrideCssClasses?: string;
+    tags?: string[];
+    hideTitle?: boolean;
+    noShadow?: boolean;
+    noBorder?: boolean;
+    noPadding?: boolean;
+    noCollapse?: boolean;
+    direction?: TWidgetDirection;
+    widgetSavedProps?: IWidgetSavedProps;
+    meta?: TWidgetMetaInfoBase;
+    extraProps?: TExtraProps;
+}
+
+/**
+ * @name IDynamicWidgetCatalogEntryBase
+ * @description Catalog entry describing how to create or load a widget.
+ * @template TFrameworkElementType - Framework-specific element type (icon, element)
+ * @template TFrameworkComponentType - Framework-specific component type
+ * @remarks
+ * - `key` must be unique and stable across versions because it is stored in
+ *   saved dashboard configurations.
+ * - `title` is the display name for catalogs and selection UIs.
+ * - `isContainer` indicates a widget that can host children.
+ * - `isRemote` marks entries that are expected to be loaded remotely (CDN,
+ *   external script) and may require extra loading/initialization steps.
+ * - `meta` contains presentation metadata (see `TWidgetMetaInfoBase`).
+ * - `component` is a direct component reference (preferred for static/core widgets).
+ * - `loader` is an async factory used for dynamic/plugin widgets. When both
+ *   `component` and `loader` are provided, loaders are typically used for
+ *   dynamic initialization; concrete loaders/components precedence should be
+ *   defined by the integrator.
+ */
+export declare interface IDynamicWidgetCatalogEntryBase<TFrameworkElementType = any, TFrameworkComponentType = any> {
+    key: TDashboardWidgetKey;
+    title: string;
+    isContainer?: boolean;
+    isRemote?: boolean;
+    meta?: TWidgetMetaInfoBase<TFrameworkElementType>;
+    component?: TFrameworkComponentType;
+    loader?: TWidgetFactoryBase<TFrameworkComponentType>;
+}
+
+export declare interface IWidgetSavedProps {
+    parentWidgetKey?: TDashboardWidgetKey;
+    widgetKey: TDashboardWidgetKey;
+    isCollapsed?: boolean;
+}
+
+/**
+ * @name localWidgetDiscovery
+ * @description Scans local directories for widgets.
+ * If lazy is true, it registers loaders. If false, it registers static components.
+ */
+export declare const localWidgetDiscovery: (baseSrcPath: string, // e.g., "/src/async-widgets" or "/src/bundled-widgets"
+widgetModules: Record<string, any>, widgetMetaModules: Record<string, any>, lazy?: boolean) => [string, IDynamicWidgetCatalogEntryBase][];
+
+export declare const parseContainerTitle: (containerWidgetKey: TDashboardWidgetKey) => string;
+
+/**
+ * Enhanced helper to derive key and title from widget file paths.
+ * Handles:
+ * - widget-total-orders -> WidgetTotalOrders
+ * - widget-revenue-trends1 -> WidgetRevenueTrends1
+ * - widget-with-extraprops -> WidgetWithExtraprops
+ * - widget-revenue-trends-async -> WidgetRevenueTrendsAsync
+ */
+export declare const parseKeyAndTitleFromFilePath: (path: string) => {
+    key: TDashboardWidgetKey;
+    name: string;
+    folder: string;
+} | null;
+
+export declare const remoteWidgetDiscovery: (manifestUrl: string) => Promise<{
+    entries: [string, IDynamicWidgetCatalogEntryBase][];
+    message: string;
+    details: string;
+}>;
+
+export declare const removeEmptyContainers: (dashboardConfig: IDashboardConfig) => IDashboardConfig;
+
+/**
+ * @name resolveColorFromClass
+ * @description Resolves the current computed color using your existing CSS classes
+ * @param classNames, i.e. 'bg-primary'
+ * @param property to resolve, i.e. 'backgroundColor'
+ * @returns
+ */
+export declare const resolveColorFromClass: (classNames: string | string[], property?: "color" | "backgroundColor") => string;
+
+/**
+ * @name TAddWidgetResponse
+ * @description Type for the response of the addWidget mutation
+ * @property {boolean} success - Indicates if the widget was added successfully
+ * @property {string} [message] - Optional message providing additional information
+ * @property {IDashboardConfig} updatedDashboardConfig - The updated dashboard configuration after adding the widget
+ * @property {IDashboardConfig[]} allUpdatedDashboardConfigs - All updated dashboard configurations
+ */
+export declare type TAddWidgetResponse = {
+    success: boolean;
+    message?: string;
+    updatedDashboardConfig: IDashboardConfig;
+    allUpdatedDashboardConfigs: IDashboardConfig[];
+};
+
+declare type TCoreResponse<T> = Omit<T, 'allUpdatedDashboardConfigs'>;
+
+/**
+ * @name TDashboardUndoStatus
+ * @description Type for the dashboard undo/redo status
+ * @remarks Used in dashboard undo/redo functionality
+ */
+export declare type TDashboardUndoStatus = {
+    isUndoDisabled: boolean;
+    isRedoDisabled: boolean;
+    _currentIndex?: number;
+    _historyLength?: number;
+};
+
+/**
+ * @name TDashboardWidgetCatalogBase
+ * @description Map of available widgets used by the dashboard at runtime.
+ * @template TFrameworkElementType - Framework-specific element type
+ * @template TFrameworkComponentType - Framework-specific component type
+ * @remarks Keys are `TDashboardWidgetKey` and values are catalog entries. The
+ * map is typically treated as a read-only registry; replace the map to update
+ * the available widget set rather than mutating entries in-place.
+ */
+export declare type TDashboardWidgetCatalogBase<TFrameworkElementType = any, TFrameworkComponentType = any> = Map<TDashboardWidgetKey, IDynamicWidgetCatalogEntryBase<TFrameworkElementType, TFrameworkComponentType>>;
+
+/**
+ * @name TDashboardWidgetKey
+ * @description Type for the unique key identifying a dashboard widget.
+ * @remarks
+ * This is a simple alias for `string` to allow flexibility in widget keys.
+ * Recommended formats: stable short strings (e.g. `myApp.ChartWidget`),
+ * namespaced identifiers or UUIDs. Consumers should avoid empty strings.
+ */
+export declare type TDashboardWidgetKey = string;
+
+/**
+ * @name TGetDefaultWidgetMetaFromKey
+ * @description Function that returns default `TWidgetMetaInfoBase` metadata for a widget key.
+ * @remarks Implementations should return a new object (not a shared reference)
+ * so callers can safely mutate the result if needed.
+ * @see TWidgetMetaInfoBase
+ * @see TGetDefaultWidgetMetaFromKeyOptions
+ * @returns `TWidgetMetaInfoBase`
+ */
+export declare type TGetDefaultWidgetMetaFromKey = (widgetKey: TDashboardWidgetKey, options?: TGetDefaultWidgetMetaFromKeyOptions) => TWidgetMetaInfoBase<any>;
+
+/**
+ * @name TGetDefaultWidgetMetaFromKeyOptions
+ * @description Optional overrides when generating default widget metadata.
+ * @remarks Fields provided here override the generated metadata's `title`
+ * and/or `description`.
+ */
+export declare type TGetDefaultWidgetMetaFromKeyOptions = {
+    name?: string;
+    description?: string;
+};
+
+/**
+ * @name TGetSavedDashboards
+ * @description Function type to get saved dashboards for a user
+ * @remarks Used in IDashboardStorageService
+ * @see IDashboardConfig
+ * @see TDashboardWidgetCatalogBase
+ * @return Promise<IDashboardConfig[]>
+ */
+export declare type TGetSavedDashboards = (userID: number | string, clientAppKey: string, widgetCatalog: TDashboardWidgetCatalogBase, defaultDashboardConfig: IDashboardConfig) => Promise<IDashboardConfig[]>;
+
+/**
+ * @name TManifestEntry
+ * @description Entry describing a remote widget manifest or resource.
+ * @remarks
+ * - `url` should point to the resource or manifest (absolute URLs recommended).
+ * - `meta` contains widget metadata (see `TWidgetMetaInfoBase`) describing the
+ *   remotely loaded widget.
+ */
+export declare type TManifestEntry = {
+    url: string;
+    meta: TWidgetMetaInfoBase;
+};
+
+export declare type TMoveWidgetResponse = TAddWidgetResponse;
+
+export declare type TRemoveWidgetResponse = TAddWidgetResponse;
+
+/**
+ * @name TSaveDashboards
+ * @description Function type to save dashboards for a user
+ * @remarks Used in IDashboardStorageService
+ * @see IDashboardConfig
+ * @see TDashboardWidgetCatalogBase
+ * @return Promise<boolean>
+ */
+export declare type TSaveDashboards = (userID: number | string, clientAppKey: string, dashboardConfigs: IDashboardConfig[], widgetCatalog: TDashboardWidgetCatalogBase) => Promise<boolean>;
+
+/**
+ * @name TUndoHistoryEntry
+ * @description Type for an undo history entry
+ * @remarks Used in dashboard undo/redo functionality
+ * @see IDashboardConfig
+ */
+export declare type TUndoHistoryEntry = {
+    undoIndex: number;
+    config: IDashboardConfig;
+};
+
+/**
+ * @name TWidgetCategory
+ * @description Type for widget categories used for grouping and UI filters.
+ * @remarks
+ * Typical usage: categorizing widgets in a palette, grouping by behavior
+ * (for instance `Container` widgets may host child widgets).
+ */
+export declare type TWidgetCategory = 'Widget' | 'Chart' | 'Container';
+
+/**
+ * @name TWidgetDirection
+ * @description Direction for layout flow inside container widgets.
+ * @remarks Only meaningful for container-type widgets that arrange children in
+ * either `row` or `column` flow.
+ */
+export declare type TWidgetDirection = 'row' | 'column';
+
+/**
+ * @name TWidgetFactoryBase
+ * @description Async factory used to lazily load a framework component for a widget.
+ * @template TFrameworkComponent - Framework-specific component type (e.g., React component)
+ * @returns Promise resolving to an object with a `default` export containing the component.
+ * @remarks Implementations should throw on unrecoverable load errors so callers
+ * can handle fallbacks; returning a stub is also acceptable when documented.
+ */
+export declare type TWidgetFactoryBase<TFrameworkComponent = any> = () => Promise<{
+    default: TFrameworkComponent;
+}>;
+
+/**
+ * @name TWidgetMetaInfoBase
+ * @description Base metadata for a widget used by catalogs and tooling.
+ * @template TFrameworkElementType - Framework-specific element type (e.g. React element, Vue component)
+ * @remarks
+ * Fields:
+ * - `name` (required): Human readable widget name.
+ * - `description` (required): Short description shown in tooltips or catalog lists.
+ * - `categories` (required): One or more `TWidgetCategory` values used for grouping.
+ * - `noDuplicatedWidgets` (optional): When true, dashboard UI should prevent
+ *   adding multiple instances of this widget.
+ * - `icon` (optional): Framework-specific icon element or component. May be
+ *   `undefined` when not provided.
+ * - `externalDependencies` (required): Array of package identifiers or CDN
+ *   references (e.g. `react@19.2.3`, `https://cdn.example.com/widget.js`). Use
+ *   semantic versions or absolute URLs as appropriate.
+ *
+ * Example:
+ * {
+ *   name: 'Simple Chart',
+ *   description: 'Displays a time series',
+ *   categories: ['Chart'],
+ *   noDuplicatedWidgets: false,
+ *   icon: undefined,
+ *   externalDependencies: ['d3@7.0.0']
+ * }
+ */
+export declare type TWidgetMetaInfoBase<TFrameworkElementType = any> = {
+    name: string;
+    description: string;
+    categories: TWidgetCategory[];
+    noDuplicatedWidgets?: boolean;
+    icon?: TFrameworkElementType | string | undefined;
+    externalDependencies: string[];
+    tags?: string[];
+    noCollapse?: boolean;
+};
+
+/**
+ * @name TWidgetSize
+ * @description Size hint for widgets that can affect layout or styling.
+ * @remarks 'default' represents the standard size; 'large' and 'xlarge' are
+ * larger variants where the dashboard may allocate more grid cells.
+ */
+export declare type TWidgetSize = 'default' | 'large' | 'xlarge';
+
+/**
+ * @name useDashboardStorageService
+ * @description
+ * LocalStorage-backed implementation of `IDashboardStorageService`.
+ *
+ * Behavior:
+ * - Persists an array of `IDashboardConfig` objects under the key
+ *   `dashboards_<clientAppKey>_<userID>` in `localStorage`.
+ * - `getSavedDashboards` performs lightweight validation and normalization when
+ *   reading saved data: fills missing `dashboardId`/`dashboardName`, sanitizes
+ *   CSS settings, filters unknown widget keys, and clamps `zoomScale`.
+ * - `saveDashboards` filters invalid widget keys, ensures required metadata
+ *   (`userID`, `clientAppKey`, `responsiveGrid`, `zoomScale`) and writes the
+ *   JSON-serialized dashboards to `localStorage`.
+ *
+ * Notes / limitations:
+ * - Uses synchronous browser `localStorage` with limited quota — not suitable
+ *   for very large datasets or high-frequency writes.
+ * - Does not provide server-side persistence or multi-user synchronization. To
+ *   persist dashboards centrally, implement a custom service that adheres to
+ *   `IDashboardStorageService` and replace this implementation.
+ *
+ * @returns An object implementing `IDashboardStorageService` with
+ * `getSavedDashboards` and `saveDashboards` methods.
+ */
+export declare const useDashboardStorageService: () => IDashboardStorageService;
+
+export { }