@richardmcquiston01/dashboard-widgets-toolkit 0.2.0 → 0.4.0

package/dist/react.d.cts

@@ -1,14 +1,20 @@
-import { ReactNode } from 'react';
-import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, L as Locale, b as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, c as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, d as TextWidgetData, e as WidgetData } from './scale-Bhjc5Eqt.cjs';
+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, h as TextWidgetData, i as WidgetData, R as ResolveOptions, j as WidgetContext, k as WidgetProviders } from './scale-dWDGE1zW.cjs';
 
 interface WidgetCardProps {
     readonly title: string;
     readonly description?: string;
-    /** Extra controls in the header (move, hide...), before the minimise toggle. */
+    /** Extra controls in the header (move, hide...), before the minimize toggle. */
     readonly actions?: ReactNode;
     readonly minimized?: boolean;
-    /** Shows the minimise/expand toggle when given. */
+    /** Shows the minimize/expand toggle when given. */
     readonly onToggleMinimized?: () => void;
+    /**
+     * Opens the widget's detail view. Adds a "View" icon button to the header
+     * actions and makes the title clickable (for mouse and touch; the button is
+     * the accessible control).
+     */
+    readonly onView?: () => void;
     /** Default 'ok', which renders `children`. */
     readonly status?: 'ok' | 'loading' | 'empty' | 'error';
     readonly emptyText?: string;
@@ -24,6 +30,13 @@ interface WidgetCardProps {
      * width-filling card the columns left over in its row.
      */
     readonly columnSpan?: number;
+    /** 12-column width (see `WidgetDefinition.width`); sets `--dwt-width`. */
+    readonly width?: number;
+    /**
+     * The widget's key, rendered as `data-widget-key` so `useWidgets` can tell
+     * which card scrolled into view. `ResolvedWidgetCard` sets it for you.
+     */
+    readonly widgetKey?: string;
     /** 2 to 6; default 2. */
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
@@ -31,18 +44,22 @@ interface WidgetCardProps {
 }
 /**
  * The frame every widget sits in: title, optional description and actions,
- * a minimise toggle, and loading, empty and error states.
+ * a minimize toggle, and loading, empty and error states.
  */
-declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, status, emptyText, error, onRetry, footer, size, fill, columnSpan, headingLevel, className, children, }: WidgetCardProps): ReactNode;
+declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, onView, status, emptyText, error, onRetry, footer, size, fill, columnSpan, width, widgetKey, headingLevel, className, children, }: WidgetCardProps): ReactNode;
 /** The title to show: alert lists add their total, e.g. "Low stock (3)". */
 declare function widgetTitle(widget: DashboardWidget): string;
 interface ResolvedWidgetCardProps {
     readonly widget: DashboardWidget;
     /** See `WidgetCardProps.columnSpan`. */
     readonly columnSpan?: number;
+    /** 12-column width (see `WidgetDefinition.width`); sets `--dwt-width`. */
+    readonly width?: number;
     readonly actions?: ReactNode;
     readonly minimized?: boolean;
     readonly onToggleMinimized?: () => void;
+    /** See `WidgetCardProps.onView`. */
+    readonly onView?: () => void;
     readonly onRetry?: () => void;
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
@@ -68,8 +85,65 @@ declare function GraphWidget({ data, title, }: {
     readonly title?: string;
 }): ReactNode;
 
+/**
+ * Loads a widget's full detail data. Close over your own context (a Prisma
+ * client, a fetch) here; the package never fetches. See `DetailProvider`.
+ */
+type DetailLoader = (definition: WidgetDefinition, options: DetailProviderOptions) => DetailData | Promise<DetailData>;
+interface WidgetDetailProps {
+    /** Table caption: the widget's title. */
+    readonly title: string;
+    /** The rows to show. Absent while `status` is `loading` or `error`. */
+    readonly data?: DetailData;
+    /** Controlled: you own the query, so you can keep it in the URL. */
+    readonly query: DetailQuery;
+    readonly onQueryChange: (query: DetailQuery) => void;
+    /** Default `ok`. */
+    readonly status?: 'ok' | 'loading' | 'error';
+    readonly error?: string;
+    readonly onRetry?: () => void;
+    /** Heading level of the title, 2 to 6. Default 2. */
+    readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /** Id of the heading, so a dialog can label itself with it. */
+    readonly headingId?: string;
+    readonly className?: string;
+}
+/**
+ * The detail view of a widget: search and column filters, a sortable table
+ * and paging, over data you give it (client mode: it filters, sorts and pages
+ * in memory with `queryRows`). Controlled by `query`. Use it on its own as a
+ * page, or inside `WidgetDetailDialog`.
+ */
+declare function WidgetDetail({ title, data, query, onQueryChange, status, error, onRetry, headingLevel, headingId, className, }: WidgetDetailProps): ReactNode;
+interface WidgetDetailDialogProps {
+    readonly title: string;
+    readonly open: boolean;
+    /** Called on Esc, the Close button and a click on the backdrop. */
+    readonly onClose: () => void;
+    readonly children: ReactNode;
+}
+/**
+ * A native modal `<dialog>`: focus is trapped, Esc closes it, the page behind
+ * is inert, and focus returns to the control that opened it.
+ */
+declare function WidgetDetailDialog({ title, open, onClose, children, }: WidgetDetailDialogProps): ReactNode;
+interface DetailLoadState {
+    readonly status: 'loading' | 'ok' | 'error';
+    readonly data?: DetailData;
+    readonly error?: string;
+}
+/**
+ * Loads a widget's detail data while `enabled`: calls `load` with an abort
+ * signal (aborted on close, retry or unmount), validates the result and
+ * reports loading, ok or error. `reload` runs it again.
+ */
+declare function useDetailData(definition: WidgetDefinition, load: DetailLoader | undefined, enabled: boolean): {
+    readonly state: DetailLoadState;
+    readonly reload: () => void;
+};
+
 /** Every element that carries a stable `dwt-*` class, for `classNames`. */
-type DashboardClassSlot = 'dashboard' | 'hiddenBar' | 'grid' | 'card' | 'cardHeader' | 'cardTitle' | 'cardDescription' | 'cardActions' | 'cardBody' | 'cardFooter' | 'button' | 'status' | 'empty' | 'error' | 'text' | 'kpi' | 'gauge' | 'table' | 'barList' | 'alertList' | 'chart' | 'legend' | 'tooltip' | 'tableTwin';
+type DashboardClassSlot = 'dashboard' | 'hiddenBar' | 'grid' | 'card' | 'cardHeader' | 'cardTitle' | 'cardDescription' | 'cardActions' | 'cardBody' | 'cardFooter' | 'button' | 'status' | 'empty' | 'error' | 'text' | 'kpi' | 'gauge' | 'table' | 'barList' | 'alertList' | 'chart' | 'legend' | 'tooltip' | 'tableTwin' | 'detail';
 /**
  * Extra classes per slot, appended to the `dwt-*` class (never replacing
  * it), e.g. `{ card: 'rounded-lg shadow-sm' }` for Tailwind.
@@ -87,6 +161,22 @@ interface DashboardLabels {
     readonly moveEarlier: (title: string) => string;
     readonly moveLater: (title: string) => string;
     readonly hiddenWidgets: string;
+    readonly minimizedWidgets: string;
+    /** Added to the accessible name of links that open in a new tab. */
+    readonly opensInNewTab: string;
+    /** The card's View button, opening the detail view. */
+    readonly view: (title: string) => string;
+    readonly close: string;
+    readonly search: string;
+    readonly filterBy: (column: string) => string;
+    readonly sortBy: (column: string) => string;
+    readonly noResults: string;
+    /** e.g. "Showing 1–25 of 312 results". */
+    readonly showingRows: (from: number, to: number, total: number) => string;
+    readonly previousPage: string;
+    readonly nextPage: string;
+    readonly pageOf: (page: number, pageCount: number) => string;
+    readonly pagination: string;
     readonly allHidden: string;
     readonly noWidgets: string;
     readonly andMore: (count: number) => string;
@@ -131,28 +221,40 @@ interface DashboardProps extends WidgetSettings {
     /** The viewer's saved layout. Default: none saved. */
     readonly layout?: DashboardLayout;
     /**
-     * Called with the next layout after a move, hide, show, minimise or
+     * Called with the next layout after a move, hide, show, minimize or
      * restore; persist it. Without it the layout is read-only (no controls).
      */
     readonly onLayoutChange?: (layout: DashboardLayout) => void;
     readonly onRetry?: (key: string) => void;
+    /**
+     * Loads the full data for a widget's detail view (widgets whose definition
+     * sets `detail`). Close over your own context. Without it, TABLE widgets
+     * with no footer and BAR_LIST widgets show their card data; other widgets
+     * get no View button.
+     */
+    readonly loadDetail?: DetailLoader;
+    /**
+     * Called with the widget key when the viewer opens a detail view, instead
+     * of the built-in dialog: navigate to your own page.
+     */
+    readonly onOpenDetail?: (key: string) => void;
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
 }
 /**
  * A full dashboard: widgets ordered by the viewer's layout, with move,
- * hide/show and minimise controls when `onLayoutChange` is given. Settings
+ * hide/show and minimize controls when `onLayoutChange` is given. Settings
  * (locale, link target, classNames, labels) apply to every widget inside.
  */
 declare function Dashboard({ locale, linkTarget, classNames, labels, ...props }: DashboardProps): ReactNode;
 
 /**
- * Default colours, used as `var(--dwt-*, fallback)` so charts read correctly
+ * Default colors, used as `var(--dwt-*, fallback)` so charts read correctly
  * without the stylesheet. `styles.css` redefines them for dark mode, and an
  * app can override any of them with its own CSS custom properties.
  *
  * The categorical order is the dataviz reference palette, validated for
- * colour-vision deficiency on adjacent pairs in light and dark modes. Slots
+ * color-vision deficiency on adjacent pairs in light and dark modes. Slots
  * are assigned in this fixed order, never cycled, and follow the series
  * (its position in the payload), never its rank.
  */
@@ -180,7 +282,7 @@ declare function TextWidget({ data, }: {
 }): ReactNode;
 /**
  * KPI: a stat tile. The change against the previous period carries an arrow
- * and signed text as well as colour, so it never relies on colour alone.
+ * and signed text as well as color, so it never relies on color alone.
  */
 declare function KpiWidget({ data, }: {
     readonly data: KpiWidgetData;
@@ -194,7 +296,7 @@ declare function TableWidget({ data, }: {
     readonly data: TableWidgetData;
 }): ReactNode;
 /**
- * BAR_LIST: labelled horizontal bars. One series, so one colour (slot 1)
+ * BAR_LIST: labelled horizontal bars. One series, so one color (slot 1)
  * for every bar; the value text sits beside the bar, never inside it.
  */
 declare function BarListWidget({ data, }: {
@@ -209,4 +311,43 @@ declare function WidgetContent({ data, }: {
     readonly data: WidgetData;
 }): ReactNode;
 
-export { AlertListWidget, BarListWidget, DEFAULT_LABELS, DEFAULT_SERIES_COLORS, Dashboard, type DashboardClassNames, type DashboardClassSlot, type DashboardLabels, type DashboardProps, GaugeWidget, GraphWidget, KpiWidget, ResolvedWidgetCard, type ResolvedWidgetCardProps, TableWidget, TextWidget, Thumbnail, WidgetCard, type WidgetCardProps, WidgetContent, WidgetGrid, type WidgetGridProps, WidgetLink, type WidgetSettings, WidgetSettingsProvider, barPath, buildChartModel, describeChart, joinClassNames, seriesColor, useWidgetSettings, widgetTitle };
+interface UseWidgetsOptions extends ResolveOptions {
+    /**
+     * When each widget's provider starts. `'mount'` (default): right after the
+     * first render, so the page and the dashboard shell appear first and each
+     * card fills in as its data arrives. `'visible'`: only once the card is
+     * near the viewport (attach `gridRef` to an element around the cards).
+     */
+    readonly loadWhen?: 'mount' | 'visible';
+    /** `IntersectionObserver` margin for `loadWhen: 'visible'`. Default `'200px'`. */
+    readonly rootMargin?: string;
+    /**
+     * Reload started widgets every this many ms. Ticks are skipped while the
+     * tab is hidden, and a widget still loading is not restarted.
+     */
+    readonly refreshMs?: number;
+}
+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;
+    /**
+     * For `loadWhen: 'visible'`: attach to any element that contains the cards,
+     * for example a wrapper `<div ref={gridRef}>` around `Dashboard`.
+     */
+    readonly gridRef: RefObject<HTMLDivElement | null>;
+}
+/**
+ * Loads widget data after the page has rendered and returns widgets for
+ * `Dashboard`. The first render never waits for data (so server rendering
+ * and first paint are unaffected); every widget starts as `loading`, loads
+ * independently, and replaces its placeholder when its own data arrives.
+ *
+ * Keep `definitions`, `providers`, `context` and `options.cache` referentially
+ * stable (module constants or `useMemo`): a changed value restarts loading,
+ * aborting whatever is in flight.
+ */
+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 };

package/dist/react.d.ts

@@ -1,14 +1,20 @@
-import { ReactNode } from 'react';
-import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, L as Locale, b as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, c as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, d as TextWidgetData, e as WidgetData } from './scale-Bhjc5Eqt.js';
+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, h as TextWidgetData, i as WidgetData, R as ResolveOptions, j as WidgetContext, k as WidgetProviders } from './scale-dWDGE1zW.js';
 
 interface WidgetCardProps {
     readonly title: string;
     readonly description?: string;
-    /** Extra controls in the header (move, hide...), before the minimise toggle. */
+    /** Extra controls in the header (move, hide...), before the minimize toggle. */
     readonly actions?: ReactNode;
     readonly minimized?: boolean;
-    /** Shows the minimise/expand toggle when given. */
+    /** Shows the minimize/expand toggle when given. */
     readonly onToggleMinimized?: () => void;
+    /**
+     * Opens the widget's detail view. Adds a "View" icon button to the header
+     * actions and makes the title clickable (for mouse and touch; the button is
+     * the accessible control).
+     */
+    readonly onView?: () => void;
     /** Default 'ok', which renders `children`. */
     readonly status?: 'ok' | 'loading' | 'empty' | 'error';
     readonly emptyText?: string;
@@ -24,6 +30,13 @@ interface WidgetCardProps {
      * width-filling card the columns left over in its row.
      */
     readonly columnSpan?: number;
+    /** 12-column width (see `WidgetDefinition.width`); sets `--dwt-width`. */
+    readonly width?: number;
+    /**
+     * The widget's key, rendered as `data-widget-key` so `useWidgets` can tell
+     * which card scrolled into view. `ResolvedWidgetCard` sets it for you.
+     */
+    readonly widgetKey?: string;
     /** 2 to 6; default 2. */
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
@@ -31,18 +44,22 @@ interface WidgetCardProps {
 }
 /**
  * The frame every widget sits in: title, optional description and actions,
- * a minimise toggle, and loading, empty and error states.
+ * a minimize toggle, and loading, empty and error states.
  */
-declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, status, emptyText, error, onRetry, footer, size, fill, columnSpan, headingLevel, className, children, }: WidgetCardProps): ReactNode;
+declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, onView, status, emptyText, error, onRetry, footer, size, fill, columnSpan, width, widgetKey, headingLevel, className, children, }: WidgetCardProps): ReactNode;
 /** The title to show: alert lists add their total, e.g. "Low stock (3)". */
 declare function widgetTitle(widget: DashboardWidget): string;
 interface ResolvedWidgetCardProps {
     readonly widget: DashboardWidget;
     /** See `WidgetCardProps.columnSpan`. */
     readonly columnSpan?: number;
+    /** 12-column width (see `WidgetDefinition.width`); sets `--dwt-width`. */
+    readonly width?: number;
     readonly actions?: ReactNode;
     readonly minimized?: boolean;
     readonly onToggleMinimized?: () => void;
+    /** See `WidgetCardProps.onView`. */
+    readonly onView?: () => void;
     readonly onRetry?: () => void;
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
@@ -68,8 +85,65 @@ declare function GraphWidget({ data, title, }: {
     readonly title?: string;
 }): ReactNode;
 
+/**
+ * Loads a widget's full detail data. Close over your own context (a Prisma
+ * client, a fetch) here; the package never fetches. See `DetailProvider`.
+ */
+type DetailLoader = (definition: WidgetDefinition, options: DetailProviderOptions) => DetailData | Promise<DetailData>;
+interface WidgetDetailProps {
+    /** Table caption: the widget's title. */
+    readonly title: string;
+    /** The rows to show. Absent while `status` is `loading` or `error`. */
+    readonly data?: DetailData;
+    /** Controlled: you own the query, so you can keep it in the URL. */
+    readonly query: DetailQuery;
+    readonly onQueryChange: (query: DetailQuery) => void;
+    /** Default `ok`. */
+    readonly status?: 'ok' | 'loading' | 'error';
+    readonly error?: string;
+    readonly onRetry?: () => void;
+    /** Heading level of the title, 2 to 6. Default 2. */
+    readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
+    /** Id of the heading, so a dialog can label itself with it. */
+    readonly headingId?: string;
+    readonly className?: string;
+}
+/**
+ * The detail view of a widget: search and column filters, a sortable table
+ * and paging, over data you give it (client mode: it filters, sorts and pages
+ * in memory with `queryRows`). Controlled by `query`. Use it on its own as a
+ * page, or inside `WidgetDetailDialog`.
+ */
+declare function WidgetDetail({ title, data, query, onQueryChange, status, error, onRetry, headingLevel, headingId, className, }: WidgetDetailProps): ReactNode;
+interface WidgetDetailDialogProps {
+    readonly title: string;
+    readonly open: boolean;
+    /** Called on Esc, the Close button and a click on the backdrop. */
+    readonly onClose: () => void;
+    readonly children: ReactNode;
+}
+/**
+ * A native modal `<dialog>`: focus is trapped, Esc closes it, the page behind
+ * is inert, and focus returns to the control that opened it.
+ */
+declare function WidgetDetailDialog({ title, open, onClose, children, }: WidgetDetailDialogProps): ReactNode;
+interface DetailLoadState {
+    readonly status: 'loading' | 'ok' | 'error';
+    readonly data?: DetailData;
+    readonly error?: string;
+}
+/**
+ * Loads a widget's detail data while `enabled`: calls `load` with an abort
+ * signal (aborted on close, retry or unmount), validates the result and
+ * reports loading, ok or error. `reload` runs it again.
+ */
+declare function useDetailData(definition: WidgetDefinition, load: DetailLoader | undefined, enabled: boolean): {
+    readonly state: DetailLoadState;
+    readonly reload: () => void;
+};
+
 /** Every element that carries a stable `dwt-*` class, for `classNames`. */
-type DashboardClassSlot = 'dashboard' | 'hiddenBar' | 'grid' | 'card' | 'cardHeader' | 'cardTitle' | 'cardDescription' | 'cardActions' | 'cardBody' | 'cardFooter' | 'button' | 'status' | 'empty' | 'error' | 'text' | 'kpi' | 'gauge' | 'table' | 'barList' | 'alertList' | 'chart' | 'legend' | 'tooltip' | 'tableTwin';
+type DashboardClassSlot = 'dashboard' | 'hiddenBar' | 'grid' | 'card' | 'cardHeader' | 'cardTitle' | 'cardDescription' | 'cardActions' | 'cardBody' | 'cardFooter' | 'button' | 'status' | 'empty' | 'error' | 'text' | 'kpi' | 'gauge' | 'table' | 'barList' | 'alertList' | 'chart' | 'legend' | 'tooltip' | 'tableTwin' | 'detail';
 /**
  * Extra classes per slot, appended to the `dwt-*` class (never replacing
  * it), e.g. `{ card: 'rounded-lg shadow-sm' }` for Tailwind.
@@ -87,6 +161,22 @@ interface DashboardLabels {
     readonly moveEarlier: (title: string) => string;
     readonly moveLater: (title: string) => string;
     readonly hiddenWidgets: string;
+    readonly minimizedWidgets: string;
+    /** Added to the accessible name of links that open in a new tab. */
+    readonly opensInNewTab: string;
+    /** The card's View button, opening the detail view. */
+    readonly view: (title: string) => string;
+    readonly close: string;
+    readonly search: string;
+    readonly filterBy: (column: string) => string;
+    readonly sortBy: (column: string) => string;
+    readonly noResults: string;
+    /** e.g. "Showing 1–25 of 312 results". */
+    readonly showingRows: (from: number, to: number, total: number) => string;
+    readonly previousPage: string;
+    readonly nextPage: string;
+    readonly pageOf: (page: number, pageCount: number) => string;
+    readonly pagination: string;
     readonly allHidden: string;
     readonly noWidgets: string;
     readonly andMore: (count: number) => string;
@@ -131,28 +221,40 @@ interface DashboardProps extends WidgetSettings {
     /** The viewer's saved layout. Default: none saved. */
     readonly layout?: DashboardLayout;
     /**
-     * Called with the next layout after a move, hide, show, minimise or
+     * Called with the next layout after a move, hide, show, minimize or
      * restore; persist it. Without it the layout is read-only (no controls).
      */
     readonly onLayoutChange?: (layout: DashboardLayout) => void;
     readonly onRetry?: (key: string) => void;
+    /**
+     * Loads the full data for a widget's detail view (widgets whose definition
+     * sets `detail`). Close over your own context. Without it, TABLE widgets
+     * with no footer and BAR_LIST widgets show their card data; other widgets
+     * get no View button.
+     */
+    readonly loadDetail?: DetailLoader;
+    /**
+     * Called with the widget key when the viewer opens a detail view, instead
+     * of the built-in dialog: navigate to your own page.
+     */
+    readonly onOpenDetail?: (key: string) => void;
     readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
     readonly className?: string;
 }
 /**
  * A full dashboard: widgets ordered by the viewer's layout, with move,
- * hide/show and minimise controls when `onLayoutChange` is given. Settings
+ * hide/show and minimize controls when `onLayoutChange` is given. Settings
  * (locale, link target, classNames, labels) apply to every widget inside.
  */
 declare function Dashboard({ locale, linkTarget, classNames, labels, ...props }: DashboardProps): ReactNode;
 
 /**
- * Default colours, used as `var(--dwt-*, fallback)` so charts read correctly
+ * Default colors, used as `var(--dwt-*, fallback)` so charts read correctly
  * without the stylesheet. `styles.css` redefines them for dark mode, and an
  * app can override any of them with its own CSS custom properties.
  *
  * The categorical order is the dataviz reference palette, validated for
- * colour-vision deficiency on adjacent pairs in light and dark modes. Slots
+ * color-vision deficiency on adjacent pairs in light and dark modes. Slots
  * are assigned in this fixed order, never cycled, and follow the series
  * (its position in the payload), never its rank.
  */
@@ -180,7 +282,7 @@ declare function TextWidget({ data, }: {
 }): ReactNode;
 /**
  * KPI: a stat tile. The change against the previous period carries an arrow
- * and signed text as well as colour, so it never relies on colour alone.
+ * and signed text as well as color, so it never relies on color alone.
  */
 declare function KpiWidget({ data, }: {
     readonly data: KpiWidgetData;
@@ -194,7 +296,7 @@ declare function TableWidget({ data, }: {
     readonly data: TableWidgetData;
 }): ReactNode;
 /**
- * BAR_LIST: labelled horizontal bars. One series, so one colour (slot 1)
+ * BAR_LIST: labelled horizontal bars. One series, so one color (slot 1)
  * for every bar; the value text sits beside the bar, never inside it.
  */
 declare function BarListWidget({ data, }: {
@@ -209,4 +311,43 @@ declare function WidgetContent({ data, }: {
     readonly data: WidgetData;
 }): ReactNode;
 
-export { AlertListWidget, BarListWidget, DEFAULT_LABELS, DEFAULT_SERIES_COLORS, Dashboard, type DashboardClassNames, type DashboardClassSlot, type DashboardLabels, type DashboardProps, GaugeWidget, GraphWidget, KpiWidget, ResolvedWidgetCard, type ResolvedWidgetCardProps, TableWidget, TextWidget, Thumbnail, WidgetCard, type WidgetCardProps, WidgetContent, WidgetGrid, type WidgetGridProps, WidgetLink, type WidgetSettings, WidgetSettingsProvider, barPath, buildChartModel, describeChart, joinClassNames, seriesColor, useWidgetSettings, widgetTitle };
+interface UseWidgetsOptions extends ResolveOptions {
+    /**
+     * When each widget's provider starts. `'mount'` (default): right after the
+     * first render, so the page and the dashboard shell appear first and each
+     * card fills in as its data arrives. `'visible'`: only once the card is
+     * near the viewport (attach `gridRef` to an element around the cards).
+     */
+    readonly loadWhen?: 'mount' | 'visible';
+    /** `IntersectionObserver` margin for `loadWhen: 'visible'`. Default `'200px'`. */
+    readonly rootMargin?: string;
+    /**
+     * Reload started widgets every this many ms. Ticks are skipped while the
+     * tab is hidden, and a widget still loading is not restarted.
+     */
+    readonly refreshMs?: number;
+}
+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;
+    /**
+     * For `loadWhen: 'visible'`: attach to any element that contains the cards,
+     * for example a wrapper `<div ref={gridRef}>` around `Dashboard`.
+     */
+    readonly gridRef: RefObject<HTMLDivElement | null>;
+}
+/**
+ * Loads widget data after the page has rendered and returns widgets for
+ * `Dashboard`. The first render never waits for data (so server rendering
+ * and first paint are unaffected); every widget starts as `loading`, loads
+ * independently, and replaces its placeholder when its own data arrives.
+ *
+ * Keep `definitions`, `providers`, `context` and `options.cache` referentially
+ * stable (module constants or `useMemo`): a changed value restarts loading,
+ * aborting whatever is in flight.
+ */
+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 };