@richardmcquiston01/dashboard-widgets-toolkit 0.10.0 → 0.11.0

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import { ReactNode, RefObject } from 'react';
-import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, h as TextWidgetData, i as WidgetData, j as ResolveOptions, k as WidgetContext, l as WidgetProviders } from './scale-N69bo7wo.cjs';
+import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, O as OptionValues, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, h as DetailSort, i as TextWidgetData, j as WidgetData, k as LayoutPersistence, S as StoreScope, P as PageItem, l as NormalizeOptions, m as ResolveOptions, n as WidgetContext, o as WidgetProviders } from './storage-VaaysVnZ.cjs';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -145,8 +145,10 @@ interface DetailLoadState {
  * `undefined`, `fallback` (for example the card's own complete data) is used
  * instead. `reload` runs it again. Keep `load` and `fallback` referentially
  * stable (`useCallback` / `useMemo`): a new value restarts the load.
+ * `optionValues` (the widget's resolved options) go to the loader as
+ * `options.options`.
  */
-declare function useDetailData(definition: WidgetDefinition, load: DetailLoader | undefined, enabled: boolean, fallback?: DetailData): {
+declare function useDetailData(definition: WidgetDefinition, load: DetailLoader | undefined, enabled: boolean, fallback?: DetailData, optionValues?: OptionValues): {
     readonly state: DetailLoadState;
     readonly reload: () => void;
 };
@@ -382,10 +384,12 @@ declare function GaugeWidget({ data, }: {
     readonly data: GaugeWidgetData;
 }): ReactNode;
 /** TABLE: a data table; cells with a safe `href` become links. */
-declare function TableWidget({ data, controls, }: {
+declare function TableWidget({ data, controls, initialSort, }: {
     readonly data: TableWidgetData;
     /** Search box and sortable headers; see `WidgetDefinition.tableControls`. */
     readonly controls?: ResolvedTableControls | undefined;
+    /** The header sort to start with, for example from a `sort` option. */
+    readonly initialSort?: DetailSort | undefined;
 }): ReactNode;
 /**
  * BAR_LIST: labelled horizontal bars. One series, so one color (slot 1)
@@ -399,12 +403,69 @@ declare function AlertListWidget({ data, }: {
     readonly data: AlertListWidgetData;
 }): ReactNode;
 /** Renders any payload with the renderer for its kind. */
-declare function WidgetContent({ data, tableControls, }: {
+declare function WidgetContent({ data, tableControls, initialSort, }: {
     readonly data: WidgetData;
     /** Search and sort for TABLE data; see `resolveTableControls`. */
     readonly tableControls?: ResolvedTableControls | undefined;
+    /** TABLE header sort to start with; see `sortFromOptions`. */
+    readonly initialSort?: DetailSort | undefined;
 }): ReactNode;
 
+type StoredLayoutStatus = 'loading' | 'ready' | 'saving' | 'error' | 'conflict';
+interface UseStoredLayoutOptions {
+    /** From `createLayoutPersistence`. Keep it referentially stable. */
+    readonly persistence: LayoutPersistence;
+    /** Which dashboard and viewer. Changing its key loads the other layout. */
+    readonly scope: StoreScope;
+    /** Keep stable (module constant or `useMemo`). */
+    readonly definitions: readonly PageItem[];
+    /** The organization default: shown until loaded and when nothing is stored. */
+    readonly defaultLayout: DashboardLayout;
+    /** Wait this long after the last change before saving. Default 500 ms. */
+    readonly saveDelayMs?: number;
+    /** From the server render, to avoid a flash; used instead of `defaultLayout` first. */
+    readonly initialLayout?: DashboardLayout;
+    readonly normalizeOptions?: NormalizeOptions;
+}
+interface StoredLayoutConflict {
+    /** The layout this viewer was saving. */
+    readonly mine: DashboardLayout;
+    /** The layout stored by someone else. */
+    readonly theirs: DashboardLayout;
+}
+interface UseStoredLayoutResult {
+    /** Pass to `Dashboard` as `layout`. */
+    readonly layout: DashboardLayout;
+    /** Pass to `Dashboard` as `onLayoutChange`. Saves after `saveDelayMs`. */
+    readonly setLayout: (layout: DashboardLayout) => void;
+    /** The pre-edit snapshot, or null. */
+    readonly backup: DashboardLayout | null;
+    /** Stores a snapshot at once (not debounced). Pass null to clear it in memory only. */
+    readonly setBackup: (layout: DashboardLayout | null) => void;
+    readonly status: StoredLayoutStatus;
+    /** The latest failure, specific enough to log or show; null when none. */
+    readonly error: string | null;
+    /** Set while `status` is `'conflict'`. */
+    readonly conflict: StoredLayoutConflict | null;
+    /** Settle a conflict: keep this viewer's layout (overwrite) or take the stored one. */
+    readonly resolveConflict: (choice: 'mine' | 'theirs') => void;
+    /**
+     * A change made in another tab or device while this one had unsaved edits.
+     * Without unsaved edits it is applied automatically and this stays null.
+     */
+    readonly remoteLayout: DashboardLayout | null;
+    /** Use or ignore `remoteLayout`. */
+    readonly resolveRemote: (choice: 'use' | 'ignore') => void;
+}
+/**
+ * Joins a `LayoutPersistence` to `Dashboard`. The dashboard never waits on
+ * storage: it shows `initialLayout` or `defaultLayout` while loading, and a
+ * failed load or save keeps the in-memory layout working and reports `error`.
+ * Saves are debounced and flushed when the page is hidden. Effects don't run
+ * on the server, so a server render shows the initial or default layout.
+ */
+declare function useStoredLayout(options: UseStoredLayoutOptions): UseStoredLayoutResult;
+
 interface UseWidgetsOptions extends ResolveOptions {
     /**
      * When each widget's provider starts. `'mount'` (default): right after the
@@ -420,12 +481,21 @@ interface UseWidgetsOptions extends ResolveOptions {
      * tab is hidden, and a widget still loading is not restarted.
      */
     readonly refreshMs?: number;
+    /**
+     * The viewer's chosen option values by widget key (see
+     * `WidgetDefinition.options`). Changing them reloads only the widgets whose
+     * resolved values changed; it never recreates the loader, so it may be a
+     * fresh object each render.
+     */
+    readonly optionValues?: Readonly<Record<string, Readonly<Record<string, unknown>> | undefined>>;
 }
 interface UseWidgetsResult {
     /** Pass to `Dashboard` or `WidgetGrid`: placeholders first, then results. */
     readonly widgets: readonly DashboardWidget[];
     /** Reload one widget (for example from the error card's Retry) or all. */
     readonly refresh: (key?: string) => void;
+    /** Choose option values for one widget; same effect as `optionValues`. */
+    readonly setOptions: (key: string, chosen: Readonly<Record<string, unknown>>) => void;
     /**
      * For `loadWhen: 'visible'`: attach to any element that contains the cards,
      * for example a wrapper `<div ref={gridRef}>` around `Dashboard`.
@@ -444,4 +514,4 @@ interface UseWidgetsResult {
  */
 declare function useWidgets<C extends WidgetContext>(definitions: readonly WidgetDefinition[], providers: WidgetProviders<C>, context: C, options?: UseWidgetsOptions): UseWidgetsResult;
 
-export { AlertListWidget, BarListWidget, DEFAULT_LABELS, DEFAULT_SERIES_COLORS, Dashboard, type DashboardClassNames, type DashboardClassSlot, type DashboardLabels, type DashboardProps, type DetailLoadState, type DetailLoader, GaugeWidget, GraphWidget, KpiWidget, ResolvedWidgetCard, type ResolvedWidgetCardProps, TableWidget, TextWidget, Thumbnail, type UseWidgetsOptions, type UseWidgetsResult, WidgetCard, type WidgetCardProps, WidgetContent, WidgetDetail, WidgetDetailDialog, type WidgetDetailDialogProps, type WidgetDetailProps, WidgetGrid, type WidgetGridProps, WidgetLink, type WidgetSettings, WidgetSettingsProvider, barPath, buildChartModel, describeChart, joinClassNames, seriesColor, useDetailData, useWidgetSettings, useWidgets, widgetTitle };
+export { AlertListWidget, BarListWidget, DEFAULT_LABELS, DEFAULT_SERIES_COLORS, Dashboard, type DashboardClassNames, type DashboardClassSlot, type DashboardLabels, type DashboardProps, type DetailLoadState, type DetailLoader, GaugeWidget, GraphWidget, KpiWidget, ResolvedWidgetCard, type ResolvedWidgetCardProps, type StoredLayoutConflict, type StoredLayoutStatus, TableWidget, TextWidget, Thumbnail, type UseStoredLayoutOptions, type UseStoredLayoutResult, type UseWidgetsOptions, type UseWidgetsResult, WidgetCard, type WidgetCardProps, WidgetContent, WidgetDetail, WidgetDetailDialog, type WidgetDetailDialogProps, type WidgetDetailProps, WidgetGrid, type WidgetGridProps, WidgetLink, type WidgetSettings, WidgetSettingsProvider, barPath, buildChartModel, describeChart, joinClassNames, seriesColor, useDetailData, useStoredLayout, useWidgetSettings, useWidgets, widgetTitle };

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode, RefObject } from 'react';
-import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, h as TextWidgetData, i as WidgetData, j as ResolveOptions, k as WidgetContext, l as WidgetProviders } from './scale-N69bo7wo.js';
+import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, O as OptionValues, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, h as DetailSort, i as TextWidgetData, j as WidgetData, k as LayoutPersistence, S as StoreScope, P as PageItem, l as NormalizeOptions, m as ResolveOptions, n as WidgetContext, o as WidgetProviders } from './storage-VaaysVnZ.js';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -145,8 +145,10 @@ interface DetailLoadState {
  * `undefined`, `fallback` (for example the card's own complete data) is used
  * instead. `reload` runs it again. Keep `load` and `fallback` referentially
  * stable (`useCallback` / `useMemo`): a new value restarts the load.
+ * `optionValues` (the widget's resolved options) go to the loader as
+ * `options.options`.
  */
-declare function useDetailData(definition: WidgetDefinition, load: DetailLoader | undefined, enabled: boolean, fallback?: DetailData): {
+declare function useDetailData(definition: WidgetDefinition, load: DetailLoader | undefined, enabled: boolean, fallback?: DetailData, optionValues?: OptionValues): {
     readonly state: DetailLoadState;
     readonly reload: () => void;
 };
@@ -382,10 +384,12 @@ declare function GaugeWidget({ data, }: {
     readonly data: GaugeWidgetData;
 }): ReactNode;
 /** TABLE: a data table; cells with a safe `href` become links. */
-declare function TableWidget({ data, controls, }: {
+declare function TableWidget({ data, controls, initialSort, }: {
     readonly data: TableWidgetData;
     /** Search box and sortable headers; see `WidgetDefinition.tableControls`. */
     readonly controls?: ResolvedTableControls | undefined;
+    /** The header sort to start with, for example from a `sort` option. */
+    readonly initialSort?: DetailSort | undefined;
 }): ReactNode;
 /**
  * BAR_LIST: labelled horizontal bars. One series, so one color (slot 1)
@@ -399,12 +403,69 @@ declare function AlertListWidget({ data, }: {
     readonly data: AlertListWidgetData;
 }): ReactNode;
 /** Renders any payload with the renderer for its kind. */
-declare function WidgetContent({ data, tableControls, }: {
+declare function WidgetContent({ data, tableControls, initialSort, }: {
     readonly data: WidgetData;
     /** Search and sort for TABLE data; see `resolveTableControls`. */
     readonly tableControls?: ResolvedTableControls | undefined;
+    /** TABLE header sort to start with; see `sortFromOptions`. */
+    readonly initialSort?: DetailSort | undefined;
 }): ReactNode;
 
+type StoredLayoutStatus = 'loading' | 'ready' | 'saving' | 'error' | 'conflict';
+interface UseStoredLayoutOptions {
+    /** From `createLayoutPersistence`. Keep it referentially stable. */
+    readonly persistence: LayoutPersistence;
+    /** Which dashboard and viewer. Changing its key loads the other layout. */
+    readonly scope: StoreScope;
+    /** Keep stable (module constant or `useMemo`). */
+    readonly definitions: readonly PageItem[];
+    /** The organization default: shown until loaded and when nothing is stored. */
+    readonly defaultLayout: DashboardLayout;
+    /** Wait this long after the last change before saving. Default 500 ms. */
+    readonly saveDelayMs?: number;
+    /** From the server render, to avoid a flash; used instead of `defaultLayout` first. */
+    readonly initialLayout?: DashboardLayout;
+    readonly normalizeOptions?: NormalizeOptions;
+}
+interface StoredLayoutConflict {
+    /** The layout this viewer was saving. */
+    readonly mine: DashboardLayout;
+    /** The layout stored by someone else. */
+    readonly theirs: DashboardLayout;
+}
+interface UseStoredLayoutResult {
+    /** Pass to `Dashboard` as `layout`. */
+    readonly layout: DashboardLayout;
+    /** Pass to `Dashboard` as `onLayoutChange`. Saves after `saveDelayMs`. */
+    readonly setLayout: (layout: DashboardLayout) => void;
+    /** The pre-edit snapshot, or null. */
+    readonly backup: DashboardLayout | null;
+    /** Stores a snapshot at once (not debounced). Pass null to clear it in memory only. */
+    readonly setBackup: (layout: DashboardLayout | null) => void;
+    readonly status: StoredLayoutStatus;
+    /** The latest failure, specific enough to log or show; null when none. */
+    readonly error: string | null;
+    /** Set while `status` is `'conflict'`. */
+    readonly conflict: StoredLayoutConflict | null;
+    /** Settle a conflict: keep this viewer's layout (overwrite) or take the stored one. */
+    readonly resolveConflict: (choice: 'mine' | 'theirs') => void;
+    /**
+     * A change made in another tab or device while this one had unsaved edits.
+     * Without unsaved edits it is applied automatically and this stays null.
+     */
+    readonly remoteLayout: DashboardLayout | null;
+    /** Use or ignore `remoteLayout`. */
+    readonly resolveRemote: (choice: 'use' | 'ignore') => void;
+}
+/**
+ * Joins a `LayoutPersistence` to `Dashboard`. The dashboard never waits on
+ * storage: it shows `initialLayout` or `defaultLayout` while loading, and a
+ * failed load or save keeps the in-memory layout working and reports `error`.
+ * Saves are debounced and flushed when the page is hidden. Effects don't run
+ * on the server, so a server render shows the initial or default layout.
+ */
+declare function useStoredLayout(options: UseStoredLayoutOptions): UseStoredLayoutResult;
+
 interface UseWidgetsOptions extends ResolveOptions {
     /**
      * When each widget's provider starts. `'mount'` (default): right after the
@@ -420,12 +481,21 @@ interface UseWidgetsOptions extends ResolveOptions {
      * tab is hidden, and a widget still loading is not restarted.
      */
     readonly refreshMs?: number;
+    /**
+     * The viewer's chosen option values by widget key (see
+     * `WidgetDefinition.options`). Changing them reloads only the widgets whose
+     * resolved values changed; it never recreates the loader, so it may be a
+     * fresh object each render.
+     */
+    readonly optionValues?: Readonly<Record<string, Readonly<Record<string, unknown>> | undefined>>;
 }
 interface UseWidgetsResult {
     /** Pass to `Dashboard` or `WidgetGrid`: placeholders first, then results. */
     readonly widgets: readonly DashboardWidget[];
     /** Reload one widget (for example from the error card's Retry) or all. */
     readonly refresh: (key?: string) => void;
+    /** Choose option values for one widget; same effect as `optionValues`. */
+    readonly setOptions: (key: string, chosen: Readonly<Record<string, unknown>>) => void;
     /**
      * For `loadWhen: 'visible'`: attach to any element that contains the cards,
      * for example a wrapper `<div ref={gridRef}>` around `Dashboard`.
@@ -444,4 +514,4 @@ interface UseWidgetsResult {
  */
 declare function useWidgets<C extends WidgetContext>(definitions: readonly WidgetDefinition[], providers: WidgetProviders<C>, context: C, options?: UseWidgetsOptions): UseWidgetsResult;
 
-export { AlertListWidget, BarListWidget, DEFAULT_LABELS, DEFAULT_SERIES_COLORS, Dashboard, type DashboardClassNames, type DashboardClassSlot, type DashboardLabels, type DashboardProps, type DetailLoadState, type DetailLoader, GaugeWidget, GraphWidget, KpiWidget, ResolvedWidgetCard, type ResolvedWidgetCardProps, TableWidget, TextWidget, Thumbnail, type UseWidgetsOptions, type UseWidgetsResult, WidgetCard, type WidgetCardProps, WidgetContent, WidgetDetail, WidgetDetailDialog, type WidgetDetailDialogProps, type WidgetDetailProps, WidgetGrid, type WidgetGridProps, WidgetLink, type WidgetSettings, WidgetSettingsProvider, barPath, buildChartModel, describeChart, joinClassNames, seriesColor, useDetailData, useWidgetSettings, useWidgets, widgetTitle };
+export { AlertListWidget, BarListWidget, DEFAULT_LABELS, DEFAULT_SERIES_COLORS, Dashboard, type DashboardClassNames, type DashboardClassSlot, type DashboardLabels, type DashboardProps, type DetailLoadState, type DetailLoader, GaugeWidget, GraphWidget, KpiWidget, ResolvedWidgetCard, type ResolvedWidgetCardProps, type StoredLayoutConflict, type StoredLayoutStatus, TableWidget, TextWidget, Thumbnail, type UseStoredLayoutOptions, type UseStoredLayoutResult, type UseWidgetsOptions, type UseWidgetsResult, WidgetCard, type WidgetCardProps, WidgetContent, WidgetDetail, WidgetDetailDialog, type WidgetDetailDialogProps, type WidgetDetailProps, WidgetGrid, type WidgetGridProps, WidgetLink, type WidgetSettings, WidgetSettingsProvider, barPath, buildChartModel, describeChart, joinClassNames, seriesColor, useDetailData, useStoredLayout, useWidgetSettings, useWidgets, widgetTitle };