@richardmcquiston01/dashboard-widgets-toolkit 0.2.0 → 0.4.1

package/dist/{scale-Bhjc5Eqt.d.cts → scale-dWDGE1zW.d.cts}

@@ -37,7 +37,7 @@ interface KpiWidgetData {
     readonly label: string;
     /** Short context under the value, e.g. "Incl. shipping and tax". */
     readonly hint?: string;
-    /** Whether a rise is good news (default true). Colours the change. */
+    /** Whether a rise is good news (default true). Colors the change. */
     readonly higherIsBetter?: boolean;
 }
 /** A value against a maximum, drawn as a meter. */
@@ -155,48 +155,6 @@ declare function isWidgetEmptyState(payload: WidgetPayload): payload is WidgetEm
  */
 declare function emptyTextFor(payload: WidgetPayload): string | null;
 
-/** A size hint for grid layouts; renderers may map it to column spans. */
-declare const WIDGET_SIZES: readonly ["small", "medium", "large", "full"];
-type WidgetSize = (typeof WIDGET_SIZES)[number];
-/**
- * How a widget fills free space in a grid layout. `height` stretches it to
- * the height of its row; `width` widens it to take the columns left over in
- * its row; `both` does both. Absent, a widget is only as big as its content
- * and `defaultSize`.
- */
-declare const WIDGET_FILLS: readonly ["height", "width", "both"];
-type WidgetFill = (typeof WIDGET_FILLS)[number];
-/**
- * What a widget is, independent of its data. Mirrors Maker Toolkit's
- * `widget` table (`widget_key`, `title`, `description`, `view_type`,
- * `roles`, `sort_order`, `active`).
- */
-interface WidgetDefinition {
-    /** Stable, unique id. Layouts and providers are keyed by it. */
-    readonly key: string;
-    readonly title: string;
-    readonly description?: string;
-    readonly kind: WidgetKind;
-    /** Lower comes first. Default 0; ties keep definition order. */
-    readonly sortOrder?: number;
-    /** Roles allowed to see it. Absent or empty means everyone. */
-    readonly roles?: readonly string[];
-    /** False hides it from every user. Default true. */
-    readonly active?: boolean;
-    readonly defaultSize?: WidgetSize;
-    /** Fill free space in the row (height, width or both). Default: none. */
-    readonly fill?: WidgetFill;
-}
-/**
- * Identity helper that keeps the literal `kind` (so typed providers can be
- * checked against it) and gives a definition its type without a cast.
- */
-declare function defineWidget<const D extends WidgetDefinition>(definition: D): D;
-/** Definitions sorted by `sortOrder` (stable: ties keep their input order). */
-declare function sortDefinitions<D extends WidgetDefinition>(definitions: readonly D[]): D[];
-/** Whether a widget is active and visible to someone with these roles. */
-declare function isWidgetVisibleTo(definition: WidgetDefinition, roles: readonly string[] | undefined): boolean;
-
 /**
  * Number formatting via `Intl`, with an injectable locale (undefined uses
  * the runtime's default), plus KPI period-over-period deltas.
@@ -258,77 +216,6 @@ declare const DEFAULT_COMPARISON_LABEL = "previous period";
  */
 declare function kpiDelta(current: number, previous: number | null | undefined, options?: KpiDeltaOptions): KpiDelta | null;
 
-/**
- * A viewer's dashboard customisation: order, hidden and minimised widgets.
- * Pure functions over a small JSON-serialisable object. Persist it however
- * you like (a settings table, localStorage); `parseLayout` tolerates
- * anything, so a corrupt saved value never breaks the dashboard.
- *
- * Generalised from Maker Toolkit's desktop `dashboard-layout.ts`.
- */
-/** What layout functions need from a widget definition. */
-interface LayoutItem {
-    readonly key: string;
-    readonly sortOrder?: number;
-}
-interface DashboardLayout {
-    /** Widget keys in display order. Keys not listed follow, by sortOrder. */
-    readonly order: readonly string[];
-    /** Widget keys removed from the dashboard (restorable). */
-    readonly hidden: readonly string[];
-    /** Widget keys collapsed to their header. */
-    readonly minimized: readonly string[];
-}
-declare const EMPTY_LAYOUT: DashboardLayout;
-/**
- * Reads a saved layout: a JSON string or an already-parsed object. Missing,
- * corrupt or wrongly typed values give the empty layout (or empty lists for
- * the fields that are wrong); non-string and duplicate keys are dropped.
- */
-declare function parseLayout(raw: unknown): DashboardLayout;
-/** The JSON string to persist. */
-declare function serializeLayout(layout: DashboardLayout): string;
-/**
- * The widgets to show, in order: saved keys first (when still present),
- * then widgets the layout doesn't know yet, by sortOrder. Hidden widgets
- * are left out.
- */
-declare function visibleWidgets<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): T[];
-/** Hidden widgets, by sortOrder, for a "restore" menu. */
-declare function hiddenWidgets<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): T[];
-/**
- * Moves `key` to `toIndex` within the current visible order. Returns the
- * same layout object when the key isn't visible or the index is out of
- * range, so callers can skip a save.
- */
-declare function moveWidget<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string, toIndex: number): DashboardLayout;
-/** Moves `key` by `offset` places (negative is earlier). Clamped at the ends. */
-declare function moveWidgetBy<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string, offset: number): DashboardLayout;
-/** Moves `key` one place earlier. */
-declare function moveWidgetUp<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string): DashboardLayout;
-/** Moves `key` one place later. */
-declare function moveWidgetDown<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string): DashboardLayout;
-declare function isHidden(layout: DashboardLayout, key: string): boolean;
-declare function isMinimized(layout: DashboardLayout, key: string): boolean;
-/** Hides `key`. No-op (same object) if already hidden. */
-declare function hideWidget(layout: DashboardLayout, key: string): DashboardLayout;
-/** Shows `key` again, expanded. No-op (same object) if not hidden. */
-declare function showWidget(layout: DashboardLayout, key: string): DashboardLayout;
-/** Hides or shows `key` (showing also clears its minimised state). */
-declare function toggleHidden(layout: DashboardLayout, key: string): DashboardLayout;
-/** Collapses `key` to its header. No-op (same object) if already minimised. */
-declare function minimizeWidget(layout: DashboardLayout, key: string): DashboardLayout;
-/** Expands `key`. No-op (same object) if not minimised. */
-declare function restoreWidget(layout: DashboardLayout, key: string): DashboardLayout;
-/** Minimises or restores `key`. */
-declare function toggleMinimized(layout: DashboardLayout, key: string): DashboardLayout;
-/**
- * Drops keys for widgets that no longer exist. Only pass the full list of
- * definitions (not a role-filtered one), or a viewer's settings for widgets
- * they temporarily can't see are lost.
- */
-declare function pruneLayout<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): DashboardLayout;
-
 /**
  * Runs each widget's data provider and collects the outcome per widget, so
  * one failing provider never breaks the rest of the dashboard. The package
@@ -341,14 +228,31 @@ interface WidgetContext {
     /** The viewer's roles. Widgets with `roles` need at least one of them. */
     readonly roles?: readonly string[];
 }
-/** Loads one widget's payload. May be sync or async; may throw. */
-type WidgetProvider<C = WidgetContext> = (context: C, definition: WidgetDefinition) => WidgetPayload | Promise<WidgetPayload>;
+/** What the resolver hands every provider, after the context and definition. */
+interface ProviderOptions {
+    /**
+     * Aborted when the widget times out, is refreshed, or the dashboard is torn
+     * down. Pass it to `fetch` (or any cancellable call) to stop the work; a
+     * provider that ignores it is still abandoned, just not stopped.
+     */
+    readonly signal: AbortSignal;
+}
+/**
+ * Loads one widget's payload. May be sync or async; may throw. The third
+ * argument is optional to use: a provider that takes only `(context,
+ * definition)` keeps working.
+ */
+type WidgetProvider<C = WidgetContext> = (context: C, definition: WidgetDefinition, options: ProviderOptions) => WidgetPayload | Promise<WidgetPayload>;
 /** Providers keyed by widget key. */
 type WidgetProviders<C = WidgetContext> = Readonly<Record<string, WidgetProvider<C>>>;
 interface OkWidget {
     readonly definition: WidgetDefinition;
     readonly status: 'ok';
     readonly data: WidgetData;
+    /** When the data was produced (epoch ms), set when a provider resolved it. */
+    readonly updatedAt?: number;
+    /** True while cached data is shown and a fresh load is still running. */
+    readonly stale?: boolean;
 }
 interface EmptyWidget {
     readonly definition: WidgetDefinition;
@@ -372,6 +276,20 @@ interface LoadingWidget {
 /** Anything a dashboard can render: resolved, or still loading. */
 type DashboardWidget = ResolvedWidget | LoadingWidget;
 type WidgetStatus = DashboardWidget['status'];
+/** A payload the cache holds, with when it was stored (epoch ms). */
+interface CachedPayload {
+    readonly payload: unknown;
+    readonly storedAt: number;
+}
+/**
+ * Consumer-supplied storage for widget payloads (memory, localStorage, a
+ * database). The package never stores anything itself. Payloads read back
+ * are validated again, so a corrupt entry cannot break a widget.
+ */
+interface WidgetCache {
+    get(key: string): CachedPayload | undefined | Promise<CachedPayload | undefined>;
+    set(key: string, entry: CachedPayload): void | Promise<void>;
+}
 interface ResolveOptions {
     /**
      * Validate each provider's payload with `validateWidgetData` (and check
@@ -379,6 +297,17 @@ interface ResolveOptions {
      * trusted, typed providers.
      */
     readonly validate?: boolean;
+    /**
+     * Give each provider this many milliseconds. A timeout aborts the
+     * provider's signal and yields an `error` widget naming the key.
+     */
+    readonly timeoutMs?: number;
+    /** Cancels loading; affected widgets resolve as `error` (canceled). */
+    readonly signal?: AbortSignal;
+    /** Where to store successful payloads (see `WidgetCache`). */
+    readonly cache?: WidgetCache;
+    /** Cache key for a widget. Default: the widget's `key`. */
+    readonly cacheKey?: (definition: WidgetDefinition) => string;
 }
 /**
  * Turns a payload (typically JSON from an API) into a resolved widget:
@@ -390,7 +319,12 @@ declare function resolvePayload(definition: WidgetDefinition, payload: unknown,
 declare function failedWidget(definition: WidgetDefinition, error: string): ErrorWidget;
 /** Loading placeholders for definitions, before their data arrives. */
 declare function loadingWidgets(definitions: readonly WidgetDefinition[]): LoadingWidget[];
-/** Runs one widget's provider, capturing a throw or bad payload as an error. */
+/** The cache key for a widget under these options. */
+declare function cacheKeyFor(definition: WidgetDefinition, options: ResolveOptions): string;
+/**
+ * Runs one widget's provider, capturing a throw, a timeout, a cancellation or
+ * a bad payload as an error widget. Never rejects.
+ */
 declare function resolveWidget<C extends WidgetContext>(definition: WidgetDefinition, provider: WidgetProvider<C> | undefined, context: C, options?: ResolveOptions): Promise<ResolvedWidget>;
 /**
  * The widgets a viewer can see: active, allowed for `roles`, in sort order.
@@ -404,6 +338,281 @@ declare function widgetsFor(definitions: readonly WidgetDefinition[], roles: rea
  */
 declare function resolveWidgets<C extends WidgetContext>(definitions: readonly WidgetDefinition[], providers: WidgetProviders<C>, context: C, options?: ResolveOptions): Promise<ResolvedWidget[]>;
 
+/**
+ * A small Result type. Functions in this package return a Result rather than
+ * throwing, so the caller has to look at the outcome. `throw` is reserved for
+ * programmer error.
+ */
+interface Ok<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+interface Err {
+    readonly ok: false;
+    /** Specific enough to act on: names the field, the widget and the problem. */
+    readonly error: string;
+}
+type Result<T> = Ok<T> | Err;
+declare function ok<T>(value: T): Ok<T>;
+declare function err(error: string): Err;
+/** Turns an unknown thrown value into a readable message. */
+declare function describeUnknownError(cause: unknown): string;
+
+/**
+ * Detail view, core part: the data and query types, sorting, filtering and
+ * paging, query (de)serialisation for URLs, and validation. Pure functions;
+ * nothing here renders, fetches or reads `location`. See
+ * `docs/design/detail-view.md`.
+ */
+
+/** `client`: the provider returns every row; `server`: it honors the query. */
+declare const DETAIL_MODES: readonly ["client", "server"];
+type DetailMode = (typeof DETAIL_MODES)[number];
+declare const DEFAULT_DETAIL_PAGE_SIZE = 25;
+declare const MAX_DETAIL_PAGE_SIZE = 200;
+/** The `detail` setting on a widget definition. `true` means all defaults. */
+interface WidgetDetailOptions {
+    /** Heading of the detail view. Default: the widget's title. */
+    readonly title?: string;
+    /** Rows per page, 1 to 200. Default 25. */
+    readonly pageSize?: number;
+    /** Default `client`. */
+    readonly mode?: DetailMode;
+}
+/** `WidgetDetailOptions` with every default filled in. */
+interface ResolvedDetailOptions {
+    readonly title: string;
+    readonly pageSize: number;
+    readonly mode: DetailMode;
+}
+interface DetailColumn {
+    /** Stable id used by sort, filters and URLs. Unique within the data. */
+    readonly key: string;
+    readonly label: string;
+    /** Right-aligned, and sorted as numbers when cell values are numbers. */
+    readonly numeric?: boolean;
+    /** Default true. */
+    readonly sortable?: boolean;
+    /** Default false: gets its own filter input when true. */
+    readonly filterable?: boolean;
+}
+interface DetailCell {
+    /** What is shown. */
+    readonly text: string;
+    /** What sorts and filters. Default: `text`. */
+    readonly value?: string | number;
+    /** Renders the cell as a link (http, https, mailto or relative only). */
+    readonly href?: string;
+}
+interface DetailData {
+    readonly columns: readonly DetailColumn[];
+    /** One array of cells per row, each as long as `columns`. */
+    readonly rows: readonly (readonly DetailCell[])[];
+    /** Server mode: rows matching the query across all pages. */
+    readonly totalRows?: number;
+}
+type SortDirection = 'asc' | 'desc';
+interface DetailSort {
+    readonly column: string;
+    readonly direction: SortDirection;
+}
+interface DetailQuery {
+    /** Free text, matched against every column. */
+    readonly search?: string;
+    /** Per-column text, keyed by column key. Blank entries are ignored. */
+    readonly filters?: Readonly<Record<string, string>>;
+    readonly sort?: DetailSort;
+    /** 1-based. */
+    readonly page: number;
+    readonly pageSize: number;
+}
+/** What a detail provider receives beyond the usual arguments. */
+interface DetailProviderOptions extends ProviderOptions {
+    readonly query: DetailQuery;
+}
+/**
+ * Loads the full data for one widget's detail view. In client mode it may
+ * ignore `options.query`; in server mode it returns one page and `totalRows`.
+ */
+type DetailProvider<C = WidgetContext> = (context: C, definition: WidgetDefinition, options: DetailProviderOptions) => DetailData | Promise<DetailData>;
+/** Detail providers keyed by widget key. */
+type DetailProviders<C = WidgetContext> = Readonly<Record<string, DetailProvider<C>>>;
+interface DetailPage {
+    /** The rows of the requested page (after filtering and sorting). */
+    readonly rows: readonly (readonly DetailCell[])[];
+    /** Rows matching the query, across all pages. */
+    readonly totalRows: number;
+    /** The page shown: the requested one, clamped into range. */
+    readonly page: number;
+    readonly pageCount: number;
+}
+/** Reads `definition.detail` with defaults; undefined when there is none. */
+declare function resolveDetailOptions(definition: Pick<WidgetDefinition, 'title' | 'detail'>): ResolvedDetailOptions | undefined;
+/** The first page, unsorted and unfiltered. */
+declare function defaultDetailQuery(pageSize?: number): DetailQuery;
+/**
+ * Filters, sorts and pages `data` in memory (client mode). Matching is
+ * case- and accent-insensitive substring matching on each cell's `value`
+ * (else `text`). Sorting is stable, locale-aware (`locale`, default the
+ * runtime's) and numeric for number values. `page` is clamped into range.
+ * Fails, naming the column, when the query names a column that does not
+ * exist or cannot be sorted.
+ */
+declare function queryRows(data: DetailData, query: DetailQuery, locale?: string): Result<DetailPage>;
+/**
+ * The query as a URL query string without the leading `?`: `q` (search),
+ * `sort` (`column:asc|desc`), `page` and `f.<column>` filters. `pageSize` is
+ * not included: the widget definition owns it. Defaults are left out.
+ */
+declare function serializeDetailQuery(query: DetailQuery): string;
+/**
+ * Reads a query string (with or without the leading `?`) written by
+ * `serializeDetailQuery`. Unknown parameters are ignored, so it can share a
+ * URL with the rest of an app. A malformed value fails with a message naming
+ * the parameter. When `data` is given, column keys are checked against it.
+ */
+declare function parseDetailQuery(queryString: string, pageSize?: number, data?: Pick<DetailData, 'columns'>): Result<DetailQuery>;
+/**
+ * Checks data from a detail provider: unique non-empty column keys, labels,
+ * every row as long as `columns`, cell `text` strings, `value` a string or
+ * finite number, safe `href`s, and `totalRows` a non-negative integer.
+ * Reports every problem, naming the column or row and cell.
+ */
+declare function validateDetailData(data: unknown, subject?: string): Result<DetailData>;
+/**
+ * The detail data for a widget whose card payload is already complete, so a
+ * detail view needs no provider: a TABLE without a `footer` (a footer means
+ * rows were left out) and a BAR_LIST. Returns undefined for everything else
+ * (alert lists, gauges, KPIs, text and charts): those need a detail provider.
+ */
+declare function deriveDetailData(data: WidgetData, locale?: Locale): DetailData | undefined;
+
+/** A size hint for grid layouts; renderers may map it to column spans. */
+declare const WIDGET_SIZES: readonly ["small", "medium", "large", "full"];
+type WidgetSize = (typeof WIDGET_SIZES)[number];
+/**
+ * How a widget fills free space in a grid layout. `height` stretches it to
+ * the height of its row; `width` widens it to take the columns left over in
+ * its row; `both` does both. Absent, a widget is only as big as its content
+ * and `defaultSize`.
+ */
+declare const WIDGET_FILLS: readonly ["height", "width", "both"];
+type WidgetFill = (typeof WIDGET_FILLS)[number];
+/**
+ * What a widget is, independent of its data. Mirrors Maker Toolkit's
+ * `widget` table (`widget_key`, `title`, `description`, `view_type`,
+ * `roles`, `sort_order`, `active`).
+ */
+interface WidgetDefinition {
+    /** Stable, unique id. Layouts and providers are keyed by it. */
+    readonly key: string;
+    readonly title: string;
+    readonly description?: string;
+    readonly kind: WidgetKind;
+    /** Lower comes first. Default 0; ties keep definition order. */
+    readonly sortOrder?: number;
+    /** Roles allowed to see it. Absent or empty means everyone. */
+    readonly roles?: readonly string[];
+    /** False hides it from every user. Default true. */
+    readonly active?: boolean;
+    readonly defaultSize?: WidgetSize;
+    /**
+     * Share of the row the widget takes, in twelfths: an integer from 2 to 12
+     * (6 is half the row, 12 the whole row). When any widget in a grid sets
+     * it, the grid becomes 12 columns wide and widgets without a `width` use
+     * the one their `defaultSize` implies (see `widthForSize`). Narrow grids
+     * give widgets more room automatically.
+     */
+    readonly width?: number;
+    /**
+     * Gives the widget a detail view: a full list with sorting, filtering and
+     * paging. `true` uses defaults. The data comes from a detail provider.
+     */
+    readonly detail?: boolean | WidgetDetailOptions;
+    /** Fill free space in the row (height, width or both). Default: none. */
+    readonly fill?: WidgetFill;
+}
+/**
+ * Identity helper that keeps the literal `kind` (so typed providers can be
+ * checked against it) and gives a definition its type without a cast.
+ */
+declare function defineWidget<const D extends WidgetDefinition>(definition: D): D;
+/** Definitions sorted by `sortOrder` (stable: ties keep their input order). */
+declare function sortDefinitions<D extends WidgetDefinition>(definitions: readonly D[]): D[];
+/** Whether a widget is active and visible to someone with these roles. */
+declare function isWidgetVisibleTo(definition: WidgetDefinition, roles: readonly string[] | undefined): boolean;
+
+/**
+ * A viewer's dashboard customization: order, hidden and minimized widgets.
+ * Pure functions over a small JSON-serialisable object. Persist it however
+ * you like (a settings table, localStorage); `parseLayout` tolerates
+ * anything, so a corrupt saved value never breaks the dashboard.
+ *
+ * Generalised from Maker Toolkit's desktop `dashboard-layout.ts`.
+ */
+/** What layout functions need from a widget definition. */
+interface LayoutItem {
+    readonly key: string;
+    readonly sortOrder?: number;
+}
+interface DashboardLayout {
+    /** Widget keys in display order. Keys not listed follow, by sortOrder. */
+    readonly order: readonly string[];
+    /** Widget keys removed from the dashboard (restorable). */
+    readonly hidden: readonly string[];
+    /** Widget keys collapsed to their header. */
+    readonly minimized: readonly string[];
+}
+declare const EMPTY_LAYOUT: DashboardLayout;
+/**
+ * Reads a saved layout: a JSON string or an already-parsed object. Missing,
+ * corrupt or wrongly typed values give the empty layout (or empty lists for
+ * the fields that are wrong); non-string and duplicate keys are dropped.
+ */
+declare function parseLayout(raw: unknown): DashboardLayout;
+/** The JSON string to persist. */
+declare function serializeLayout(layout: DashboardLayout): string;
+/**
+ * The widgets to show, in order: saved keys first (when still present),
+ * then widgets the layout doesn't know yet, by sortOrder. Hidden widgets
+ * are left out.
+ */
+declare function visibleWidgets<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): T[];
+/** Hidden widgets, by sortOrder, for a "restore" menu. */
+declare function hiddenWidgets<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): T[];
+/**
+ * Moves `key` to `toIndex` within the current visible order. Returns the
+ * same layout object when the key isn't visible or the index is out of
+ * range, so callers can skip a save.
+ */
+declare function moveWidget<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string, toIndex: number): DashboardLayout;
+/** Moves `key` by `offset` places (negative is earlier). Clamped at the ends. */
+declare function moveWidgetBy<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string, offset: number): DashboardLayout;
+/** Moves `key` one place earlier. */
+declare function moveWidgetUp<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string): DashboardLayout;
+/** Moves `key` one place later. */
+declare function moveWidgetDown<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string): DashboardLayout;
+declare function isHidden(layout: DashboardLayout, key: string): boolean;
+declare function isMinimized(layout: DashboardLayout, key: string): boolean;
+/** Hides `key`. No-op (same object) if already hidden. */
+declare function hideWidget(layout: DashboardLayout, key: string): DashboardLayout;
+/** Shows `key` again, expanded. No-op (same object) if not hidden. */
+declare function showWidget(layout: DashboardLayout, key: string): DashboardLayout;
+/** Hides or shows `key` (showing also clears its minimized state). */
+declare function toggleHidden(layout: DashboardLayout, key: string): DashboardLayout;
+/** Collapses `key` to its header. No-op (same object) if already minimized. */
+declare function minimizeWidget(layout: DashboardLayout, key: string): DashboardLayout;
+/** Expands `key`. No-op (same object) if not minimized. */
+declare function restoreWidget(layout: DashboardLayout, key: string): DashboardLayout;
+/** Minimizes or restores `key`. */
+declare function toggleMinimized(layout: DashboardLayout, key: string): DashboardLayout;
+/**
+ * Drops keys for widgets that no longer exist. Only pass the full list of
+ * definitions (not a role-filtered one), or a viewer's settings for widgets
+ * they temporarily can't see are lost.
+ */
+declare function pruneLayout<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): DashboardLayout;
+
 /** Axis maths for charts: clean domains and tick values. Pure. */
 /** The smallest 1, 2 or 5 × 10^n that is at least `value` (1 for 0 or less). */
 declare function niceStep(value: number): number;
@@ -423,4 +632,4 @@ declare function niceDomain(values: readonly number[], tickCount?: number): Nice
  */
 declare function labelStride(count: number, maxLabels?: number): number;
 
-export { emptyWidget as $, type AlertListWidgetData as A, type BarListWidgetData as B, type ValueFormat as C, type DashboardWidget as D, EMPTY_LAYOUT as E, type FormatOptions as F, type GraphWidgetData as G, WIDGET_FILLS as H, WIDGET_KINDS as I, WIDGET_SIZES as J, type KpiWidgetData as K, type Locale as L, MAX_GRAPH_SERIES as M, type NiceDomain as N, type OkWidget as O, type WidgetContext as P, type WidgetDataOf as Q, type ResolveOptions as R, type WidgetEmptyState as S, type TableWidgetData as T, type WidgetProvider as U, VALUE_FORMATS as V, type WidgetSize as W, type WidgetProviders as X, type WidgetStatus as Y, defineWidget as Z, emptyTextFor as _, type WidgetFill as a, failedWidget as a0, formatCount as a1, formatPercentChange as a2, formatValue as a3, hiddenWidgets as a4, hideWidget as a5, isHidden as a6, isMinimized as a7, isWidgetEmptyState as a8, isWidgetKind as a9, isWidgetVisibleTo as aa, kpiDelta as ab, labelStride as ac, loadingWidgets as ad, minimizeWidget as ae, moveWidget as af, moveWidgetBy as ag, moveWidgetDown as ah, moveWidgetUp as ai, niceDomain as aj, niceStep as ak, parseLayout as al, percentChange as am, pruneLayout as an, resolvePayload as ao, resolveWidget as ap, resolveWidgets as aq, restoreWidget as ar, serializeLayout as as, shareOf as at, showWidget as au, sortDefinitions as av, toggleHidden as aw, toggleMinimized as ax, visibleWidgets as ay, widgetsFor as az, type DashboardLayout as b, type GaugeWidgetData as c, type TextWidgetData as d, type WidgetData as e, type WidgetDefinition as f, type WidgetKind as g, type WidgetPayload as h, type AlertListItem as i, type BarListItem as j, DEFAULT_COMPARISON_LABEL as k, DEFAULT_CURRENCY as l, DEFAULT_EMPTY_TEXT as m, type DeltaDirection as n, type DeltaSentiment as o, type EmptyWidget as p, type ErrorWidget as q, type GraphPoint as r, type GraphSeries as s, type KpiDelta as t, type KpiDeltaOptions as u, type LayoutItem as v, type LoadingWidget as w, type ResolvedWidget as x, type TableCell as y, type TableColumn as z };
+export { MAX_GRAPH_SERIES as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CachedPayload as C, type DashboardWidget as D, type DetailPage as E, type DetailProvider as F, type GraphWidgetData as G, type DetailProviders as H, type DetailSort as I, EMPTY_LAYOUT as J, type KpiWidgetData as K, type Locale as L, type EmptyWidget as M, type NiceDomain as N, type Err as O, type ErrorWidget as P, type FormatOptions as Q, type ResolveOptions as R, type GraphPoint as S, type TableWidgetData as T, type GraphSeries as U, type KpiDelta as V, type WidgetSize as W, type KpiDeltaOptions as X, type LayoutItem as Y, type LoadingWidget as Z, MAX_DETAIL_PAGE_SIZE as _, type WidgetFill as a, sortDefinitions as a$, type Ok as a0, type OkWidget as a1, type ProviderOptions as a2, type ResolvedDetailOptions as a3, type ResolvedWidget as a4, type SortDirection as a5, type TableCell as a6, type TableColumn as a7, VALUE_FORMATS as a8, type ValueFormat as a9, isWidgetKind as aA, isWidgetVisibleTo as aB, kpiDelta as aC, labelStride as aD, loadingWidgets as aE, minimizeWidget as aF, moveWidget as aG, moveWidgetBy as aH, moveWidgetDown as aI, moveWidgetUp as aJ, niceDomain as aK, niceStep as aL, ok as aM, parseDetailQuery as aN, parseLayout as aO, percentChange as aP, pruneLayout as aQ, queryRows as aR, resolveDetailOptions as aS, resolvePayload as aT, resolveWidget as aU, resolveWidgets as aV, restoreWidget as aW, serializeDetailQuery as aX, serializeLayout as aY, shareOf as aZ, showWidget as a_, WIDGET_FILLS as aa, WIDGET_KINDS as ab, WIDGET_SIZES as ac, type WidgetCache as ad, type WidgetDataOf as ae, type WidgetDetailOptions as af, type WidgetEmptyState as ag, type WidgetProvider as ah, type WidgetStatus as ai, cacheKeyFor as aj, defaultDetailQuery as ak, defineWidget as al, deriveDetailData as am, describeUnknownError as an, emptyTextFor as ao, emptyWidget as ap, err as aq, failedWidget as ar, formatCount as as, formatPercentChange as at, formatValue as au, hiddenWidgets as av, hideWidget as aw, isHidden as ax, isMinimized as ay, isWidgetEmptyState as az, type WidgetDefinition as b, toggleHidden as b0, toggleMinimized as b1, validateDetailData as b2, visibleWidgets as b3, widgetsFor as b4, type DetailProviderOptions as c, type DetailData as d, type DetailQuery as e, type DashboardLayout as f, type GaugeWidgetData as g, type TextWidgetData as h, type WidgetData as i, type WidgetContext as j, type WidgetProviders as k, type WidgetKind as l, type Result as m, type WidgetPayload as n, type AlertListItem as o, type BarListItem as p, DEFAULT_COMPARISON_LABEL as q, DEFAULT_CURRENCY as r, DEFAULT_DETAIL_PAGE_SIZE as s, DEFAULT_EMPTY_TEXT as t, DETAIL_MODES as u, type DeltaDirection as v, type DeltaSentiment as w, type DetailCell as x, type DetailColumn as y, type DetailMode as z };