@richardmcquiston01/dashboard-widgets-toolkit 0.10.0 → 0.11.0

package/dist/storage-VaaysVnZ.d.ts

@@ -0,0 +1,1333 @@
+/**
+ * Widget data payloads, one shape per kind, discriminated by `kind`.
+ *
+ * The kind names are upper case to stay compatible with Maker Toolkit's
+ * `WidgetViewType` (`TEXT`, `GAUGE`, `TABLE`, `GRAPH`). `KPI`, `BAR_LIST`
+ * and `ALERT_LIST` are new. Every payload is plain JSON: strings, finite
+ * numbers, booleans, null, arrays and objects. No dates (send ISO strings),
+ * no functions, no class instances.
+ */
+/** Every widget kind, in a stable order. */
+declare const WIDGET_KINDS: readonly ["TEXT", "KPI", "GAUGE", "TABLE", "BAR_LIST", "ALERT_LIST", "GRAPH"];
+type WidgetKind = (typeof WIDGET_KINDS)[number];
+declare function isWidgetKind(value: unknown): value is WidgetKind;
+/** How a number is shown: a plain count, money, or a fraction as a percent. */
+declare const VALUE_FORMATS: readonly ["number", "currency", "percent"];
+type ValueFormat = (typeof VALUE_FORMATS)[number];
+/** A single headline value as text, e.g. "12" or "Open". */
+interface TextWidgetData {
+    readonly kind: 'TEXT';
+    readonly value: string;
+    readonly label: string;
+}
+/**
+ * A stat tile: one number, optionally compared with the previous period.
+ *
+ * `value` and `previous` are in major units for `currency` (12.5 is $12.50)
+ * and fractions for `percent` (0.25 is 25%).
+ */
+interface KpiWidgetData {
+    readonly kind: 'KPI';
+    readonly value: number;
+    /** The same measure for the previous period; null or absent for none. */
+    readonly previous?: number | null;
+    readonly format: ValueFormat;
+    /** ISO 4217 code for `currency`, e.g. "USD". Defaults to USD. */
+    readonly currency?: string;
+    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). Colors the change. */
+    readonly higherIsBetter?: boolean;
+}
+/** A value against a maximum, drawn as a meter. */
+interface GaugeWidgetData {
+    readonly kind: 'GAUGE';
+    readonly value: number;
+    readonly max: number;
+    readonly label: string;
+}
+interface TableColumn {
+    readonly label: string;
+    /** Right-aligned, tabular figures. */
+    readonly numeric?: boolean;
+}
+interface TableCell {
+    readonly text: string;
+    /** Renders the cell as a link (http, https, mailto or relative only). */
+    readonly href?: string;
+    /**
+     * What the card's table controls (and the detail view) sort and search
+     * on, when `text` is formatted for reading: a timestamp behind "3 days
+     * ago", a rating behind stars, an amount behind "$1,234.00". Default:
+     * `text`.
+     */
+    readonly value?: string | number;
+}
+interface TableWidgetData {
+    readonly kind: 'TABLE';
+    readonly columns: readonly TableColumn[];
+    /** One array of cells per row, each as long as `columns`. */
+    readonly rows: readonly (readonly TableCell[])[];
+    /** A note under the table, e.g. "and 12 more". */
+    readonly footer?: string;
+}
+interface BarListItem {
+    readonly label: string;
+    readonly value: number;
+    /** Text shown beside the bar; defaults to the formatted value. */
+    readonly display?: string;
+}
+/**
+ * Labelled horizontal bars, e.g. ratings or purchases by country. Bars are a
+ * share of `total` when it is given, otherwise of the largest value.
+ */
+interface BarListWidgetData {
+    readonly kind: 'BAR_LIST';
+    readonly items: readonly BarListItem[];
+    readonly total?: number;
+}
+interface AlertListItem {
+    readonly title: string;
+    /** Renders the title as a link (http, https, mailto or relative only). */
+    readonly href?: string;
+    /** A small square image (http, https or relative only). */
+    readonly thumbnailUrl?: string;
+    /** The short figure on the right, e.g. "2 left" or "31 views". */
+    readonly valueLabel: string;
+    /** A secondary line under the title. */
+    readonly detail?: string;
+}
+/**
+ * Things that need attention (low stock, stale listings...). `items` may be
+ * the first few of `total`; the renderer says "and N more".
+ */
+interface AlertListWidgetData {
+    readonly kind: 'ALERT_LIST';
+    readonly items: readonly AlertListItem[];
+    readonly total: number;
+    /** Shown when there is nothing to flag, e.g. "Nothing low on stock." */
+    readonly emptyText: string;
+}
+interface GraphPoint {
+    /** The category or date label on the x axis, e.g. "Oct 2026". */
+    readonly label: string;
+    readonly value: number;
+}
+interface GraphSeries {
+    readonly name: string;
+    readonly points: readonly GraphPoint[];
+}
+/** The most series a graph may carry: the categorical palette's eight slots. */
+declare const MAX_GRAPH_SERIES = 8;
+/**
+ * A bar (grouped for several series) or line chart. All series share the
+ * x labels of the first series, by position, and one y axis.
+ */
+interface GraphWidgetData {
+    readonly kind: 'GRAPH';
+    readonly series: readonly GraphSeries[];
+    readonly chartType: 'bar' | 'line';
+    readonly valueFormat: ValueFormat;
+    /** ISO 4217 code for `currency`. Defaults to USD. */
+    readonly currency?: string;
+    /** Heading for the label column in the table view, e.g. "Month". */
+    readonly xLabel?: string;
+}
+/** Any widget's data, discriminated by `kind`. */
+type WidgetData = TextWidgetData | KpiWidgetData | GaugeWidgetData | TableWidgetData | BarListWidgetData | AlertListWidgetData | GraphWidgetData;
+/** The payload type for one kind, e.g. `WidgetDataOf<'KPI'>`. */
+type WidgetDataOf<K extends WidgetKind> = Extract<WidgetData, {
+    kind: K;
+}>;
+/**
+ * A widget with nothing to show yet, with the reason as text ("No orders
+ * synced yet."). Any widget may return this instead of its kind's payload.
+ */
+interface WidgetEmptyState {
+    readonly empty: true;
+    readonly text: string;
+}
+/** What a provider or API returns for a widget: its data, or an empty state. */
+type WidgetPayload = WidgetData | WidgetEmptyState;
+/** The default text for an empty widget. */
+declare const DEFAULT_EMPTY_TEXT = "Nothing to show yet.";
+/** Builds an empty state. */
+declare function emptyWidget(text?: string): WidgetEmptyState;
+declare function isWidgetEmptyState(payload: WidgetPayload): payload is WidgetEmptyState;
+/**
+ * The empty text for a payload with nothing in it (a table with no rows, a
+ * list with no items, a graph with no points), or null when it has content.
+ * TEXT, KPI and GAUGE always have content.
+ */
+declare function emptyTextFor(payload: WidgetPayload): string | null;
+
+/**
+ * Number formatting via `Intl`, with an injectable locale (undefined uses
+ * the runtime's default), plus KPI period-over-period deltas.
+ */
+
+type Locale = string | readonly string[] | undefined;
+interface FormatOptions {
+    readonly locale?: Locale;
+    /** ISO 4217 code for `currency`. Default "USD". */
+    readonly currency?: string;
+    /** "1.2K" style, for axis ticks. */
+    readonly compact?: boolean;
+}
+declare const DEFAULT_CURRENCY = "USD";
+/**
+ * Formats `value` as a count ("1,284"), money ("$12.50", major units) or a
+ * percent ("25%" from 0.25).
+ */
+declare function formatValue(value: number, format: ValueFormat, options?: FormatOptions): string;
+/** A plain count, e.g. "1,284". */
+declare function formatCount(value: number, locale?: Locale): string;
+/** `part` as a whole percentage of `total` (0 when total is 0 or less). */
+declare function shareOf(part: number, total: number): number;
+/**
+ * Change from `previous` to `current` in percent (unrounded), or null when
+ * there is nothing to compare: no previous value, or a previous of 0.
+ */
+declare function percentChange(current: number, previous: number | null | undefined): number | null;
+/**
+ * "+12%", "-8%", "±0%". Below 10% one decimal is kept ("+2.5%"), so small
+ * changes don't round away.
+ */
+declare function formatPercentChange(change: number, locale?: Locale): string;
+type DeltaDirection = 'up' | 'down' | 'flat';
+type DeltaSentiment = 'good' | 'bad' | 'neutral';
+interface KpiDelta {
+    /** Percent change, unrounded. */
+    readonly percent: number;
+    readonly direction: DeltaDirection;
+    /** Direction combined with whether higher is better. */
+    readonly sentiment: DeltaSentiment;
+    /** "+12%" */
+    readonly text: string;
+    /** "+12% vs previous period" */
+    readonly description: string;
+}
+interface KpiDeltaOptions {
+    /** Default true. */
+    readonly higherIsBetter?: boolean;
+    readonly locale?: Locale;
+    /** What the change is against. Default "previous period". */
+    readonly comparisonLabel?: string;
+}
+/** The default comparison wording in delta descriptions. */
+declare const DEFAULT_COMPARISON_LABEL = "previous period";
+/**
+ * The period-over-period change for a KPI, or null when it can't be worked
+ * out (no previous value, or a previous of 0).
+ */
+declare function kpiDelta(current: number, previous: number | null | undefined, options?: KpiDeltaOptions): KpiDelta | null;
+
+/**
+ * Options a widget author declares and a viewer (or the consumer) can choose:
+ * a default sort, "top N", a period, which columns show. The package never
+ * decides what an option means for your data. It validates the chosen values,
+ * hands them to your provider (`ProviderOptions.options`), keeps cached
+ * payloads for different choices apart, and can sort or trim a payload itself
+ * when the author says so (`apply: 'client'`).
+ *
+ * Definitions stay plain JSON: no functions, no regular expressions.
+ */
+
+/** A chosen option value. Only a `columns` option holds more than a scalar. */
+type OptionValue = string | number | boolean | readonly string[];
+/** Resolved option values by option key. */
+type OptionValues = Readonly<Record<string, OptionValue>>;
+/** Fields every declared option has. */
+interface OptionBase {
+    /** Unique within the widget; letters, digits, `_` and `-`, starting with a letter. */
+    readonly key: string;
+    /** What the viewer sees, in your own words (and language). */
+    readonly label: string;
+}
+/** A pick from a fixed list. */
+interface ChoiceOption extends OptionBase {
+    readonly type: 'choice';
+    readonly choices: readonly {
+        readonly value: string;
+        readonly label: string;
+    }[];
+    readonly default: string;
+}
+interface NumberOption extends OptionBase {
+    readonly type: 'number';
+    readonly min: number;
+    readonly max: number;
+    /** Chosen values must be `min` plus a whole number of steps. */
+    readonly step?: number;
+    readonly default: number;
+}
+interface BooleanOption extends OptionBase {
+    readonly type: 'boolean';
+    readonly default: boolean;
+}
+/** Free text: a search term, a tag. Always plain text, never HTML. */
+interface TextOption extends OptionBase {
+    readonly type: 'text';
+    /** At most 500. */
+    readonly maxLength: number;
+    readonly default: string;
+}
+/** The named ranges a `dateRange` option can use (see `resolveDateRange`). */
+declare const DATE_RANGE_PRESETS: readonly ["today", "yesterday", "last7", "last30", "last90", "thisMonth", "lastMonth", "thisYear", "lastYear"];
+type DateRangePreset = (typeof DATE_RANGE_PRESETS)[number];
+/**
+ * A range of calendar days. The value is a preset key (`last30`) or an ISO
+ * interval `YYYY-MM-DD/YYYY-MM-DD`. Providers always receive the interval.
+ */
+interface DateRangeOption extends OptionBase {
+    readonly type: 'dateRange';
+    /** The presets a viewer may pick. Default: every preset. */
+    readonly presets?: readonly {
+        readonly value: DateRangePreset;
+        readonly label: string;
+    }[];
+    readonly default: string;
+}
+/** A `#rrggbb` color. A color alone should never carry meaning. */
+interface ColorOption extends OptionBase {
+    readonly type: 'color';
+    readonly default: string;
+}
+/**
+ * How rows are ordered. The value is `column:asc` or `column:desc`, where
+ * `column` is a column key: `c0`, `c1`, ... for a TABLE (by position) and
+ * `label` or `value` for a BAR_LIST.
+ */
+interface SortOption extends OptionBase {
+    readonly type: 'sort';
+    readonly columns: readonly {
+        readonly key: string;
+        readonly label: string;
+    }[];
+    /** Absent: no sort until the viewer picks one. */
+    readonly default?: string;
+    /**
+     * `provider` (default): your provider returns the right rows, which a
+     * truncated table needs. `client`: the toolkit sorts the payload it got.
+     */
+    readonly apply?: 'provider' | 'client';
+}
+/** Which TABLE columns show, and in what order. The value is column keys. */
+interface ColumnsOption extends OptionBase {
+    readonly type: 'columns';
+    readonly columns: readonly {
+        readonly key: string;
+        readonly label: string;
+    }[];
+    readonly default: readonly string[];
+    /** `provider` (default) passes the keys on; `client` trims the payload here. */
+    readonly apply?: 'provider' | 'client';
+}
+type WidgetOption = ChoiceOption | NumberOption | BooleanOption | TextOption | DateRangeOption | ColorOption | SortOption | ColumnsOption;
+declare const WIDGET_OPTION_TYPES: readonly ["choice", "number", "boolean", "text", "dateRange", "color", "sort", "columns"];
+/** The most options one widget may declare. */
+declare const MAX_WIDGET_OPTIONS = 20;
+/** The most characters in a `text` option. */
+declare const MAX_TEXT_OPTION_LENGTH = 500;
+/** Allowed option keys. */
+declare const OPTION_KEY_PATTERN: RegExp;
+/** What option resolution needs from the outside world. */
+interface OptionContext {
+    /** "Now" in epoch ms, for date range presets. Default `Date.now()`. */
+    readonly now?: number;
+    /** An IANA time zone for "today". Default `UTC`. */
+    readonly timeZone?: string;
+}
+/** The value a column key refers to in a sort or columns option. */
+declare function isColumnKeyFor(kind: string, key: string): boolean;
+/** Whether the toolkit (not your provider) applies this option. */
+declare function isClientApplied(option: WidgetOption): boolean;
+/** Whether `value` is `YYYY-MM-DD/YYYY-MM-DD` with real days, start not after end. */
+declare function isIsoInterval(value: string): boolean;
+/**
+ * The ISO interval a date range value stands for, or undefined when it is
+ * neither a preset nor a valid interval. Presets, in calendar days of the
+ * context's time zone: `today`, `yesterday`, `last7`, `last30` and `last90`
+ * (ending today), `thisMonth` and `thisYear` (from the first day to today),
+ * `lastMonth` and `lastYear` (the whole of it).
+ */
+declare function resolveDateRange(value: string, context?: OptionContext): string | undefined;
+/** `column:asc|desc` as a detail sort, or undefined when malformed. */
+declare function parseSortValue(value: string): DetailSort | undefined;
+/**
+ * The sort the widget's `sort` option currently selects, or undefined when
+ * the widget has no sort option or no sort is chosen. Use it to seed table
+ * headers and the detail view.
+ */
+declare function sortFromOptions(definition: {
+    readonly options?: readonly WidgetOption[];
+}, values: OptionValues | undefined): DetailSort | undefined;
+/**
+ * A chosen value made valid for `option`, or undefined when it isn't one the
+ * option allows. Text is trimmed, colors lower-cased, date ranges resolved to
+ * an interval.
+ */
+declare function coerceOptionValue(option: WidgetOption, value: unknown, context?: OptionContext): OptionValue | undefined;
+/** The value an option has when nothing valid was chosen. */
+declare function defaultOptionValue(option: WidgetOption, context?: OptionContext): OptionValue | undefined;
+/**
+ * The value of every option a definition declares: the chosen one when it is
+ * valid for that option, else the default. Keys that aren't declared and
+ * values that aren't valid are ignored (never an error), so a layout saved
+ * before an option changed still loads. A `sort` option with no default and
+ * no valid choice is left out. Empty when the definition declares none.
+ */
+declare function resolveOptionValues(definition: {
+    readonly options?: readonly WidgetOption[];
+}, chosen: Readonly<Record<string, unknown>> | undefined, context?: OptionContext): OptionValues;
+/** Whether two sets of resolved values are the same. */
+declare function sameOptionValues(a: OptionValues, b: OptionValues): boolean;
+/**
+ * Text that tells apart the payloads different choices produce, for cache
+ * keys: the values that differ from the default, in key order, and only the
+ * options your provider sees (`apply: 'client'` ones don't change the data it
+ * returns). Empty when everything is on its default, so a widget on defaults
+ * keeps its plain key.
+ */
+declare function optionsCacheSuffix(definition: {
+    readonly options?: readonly WidgetOption[];
+}, values: OptionValues, context?: OptionContext): string;
+/**
+ * Applies the options the author marked `apply: 'client'` to a payload: sorts
+ * the rows of a TABLE or the items of a BAR_LIST, and trims and reorders the
+ * columns of a TABLE. Other payloads, and options whose columns don't fit the
+ * payload, come back unchanged. Sorting happens before trimming, so a sort
+ * can use a column that is then hidden.
+ */
+declare function applyClientOptions(definition: {
+    readonly options?: readonly WidgetOption[];
+}, data: WidgetData, values: OptionValues): WidgetData;
+
+/**
+ * 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
+ * never fetches anything itself: providers are the consumer's functions
+ * (a Prisma query, an HTTP call, a computed value).
+ */
+
+/** The minimum a resolve context carries; add whatever your providers need. */
+interface WidgetContext {
+    /** The viewer's roles. Widgets with `roles` need at least one of them. */
+    readonly roles?: readonly string[];
+}
+/** 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;
+    /**
+     * The widget's declared options, resolved: what was chosen when it is valid,
+     * else the default. Empty when the definition declares none. Treat values
+     * that reach a database query (`text`, `sort`, `columns`) as untrusted input
+     * and check them again on the server.
+     */
+    readonly options: OptionValues;
+}
+/**
+ * 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;
+    /** The widget's resolved option values; present when it declares options. */
+    readonly options?: OptionValues;
+}
+interface EmptyWidget {
+    readonly definition: WidgetDefinition;
+    readonly status: 'empty';
+    /** Why there is nothing to show, e.g. "No orders synced yet." */
+    readonly emptyText: string;
+    /** The widget's resolved option values; present when it declares options. */
+    readonly options?: OptionValues;
+}
+interface ErrorWidget {
+    readonly definition: WidgetDefinition;
+    readonly status: 'error';
+    /** Names the widget and what failed. */
+    readonly error: string;
+    /** The widget's resolved option values; present when it declares options. */
+    readonly options?: OptionValues;
+}
+/** One widget after its provider ran. */
+type ResolvedWidget = OkWidget | EmptyWidget | ErrorWidget;
+/** A widget whose data hasn't arrived yet (for client-side loading states). */
+interface LoadingWidget {
+    readonly definition: WidgetDefinition;
+    readonly status: 'loading';
+    /** The widget's resolved option values; present when it declares options. */
+    readonly options?: OptionValues;
+}
+/** 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 extends OptionContext {
+    /**
+     * The values chosen for each widget's options, by widget key. Values a
+     * widget didn't declare, or that aren't valid for the option, are ignored
+     * and the option's default is used.
+     */
+    readonly optionValues?: Readonly<Record<string, Readonly<Record<string, unknown>> | undefined>>;
+    /**
+     * Validate each provider's payload with `validateWidgetData` (and check
+     * its kind matches the definition). Default true; turn off only for
+     * 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:
+ * validated against the definition's kind, and marked empty when it has
+ * nothing to show.
+ */
+declare function resolvePayload(definition: WidgetDefinition, payload: unknown, options?: ResolveOptions): ResolvedWidget;
+/** A widget that failed, with the reason. */
+declare function failedWidget(definition: WidgetDefinition, error: string): ErrorWidget;
+/** Loading placeholders for definitions, before their data arrives. */
+declare function loadingWidgets(definitions: readonly WidgetDefinition[]): LoadingWidget[];
+/**
+ * The cache key for a widget under these options. With resolved option
+ * `values`, choices that differ from the defaults are appended, so "top 5 by
+ * units" and "top 10 by revenue" are cached apart, while a widget on its
+ * defaults keeps its plain key.
+ */
+declare function cacheKeyFor(definition: WidgetDefinition, options: ResolveOptions, values?: OptionValues): string;
+/** The resolved option values for a widget under these resolve options. */
+declare function optionValuesFor(definition: WidgetDefinition, options: ResolveOptions): OptionValues;
+/**
+ * Applies the options marked `apply: 'client'` to an `ok` widget's payload and
+ * records the resolved values on the widget (when it declares options). Other
+ * widgets only get the values. Returns the same object when nothing changes.
+ */
+declare function finalizeWidget<W extends DashboardWidget>(widget: W, values: OptionValues): W;
+/**
+ * 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>;
+/**
+ * Like `resolveWidget`, but leaves the payload as the provider returned it:
+ * options marked `apply: 'client'` are not applied (see `finalizeWidget`). For
+ * loaders that keep the payload so a client-side choice can change without
+ * asking the provider again.
+ */
+declare function resolveWidgetUnapplied<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.
+ */
+declare function widgetsFor(definitions: readonly WidgetDefinition[], roles: readonly string[] | undefined): WidgetDefinition[];
+/**
+ * Resolves every widget the context's roles may see, in parallel. Inactive
+ * and role-filtered widgets are skipped (and their providers never run).
+ * Results come back in sort order; a provider that throws, is missing or
+ * returns a bad payload yields an `error` widget and never rejects.
+ */
+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;
+}
+/** The `tableControls` setting on a widget definition. `true` means both. */
+interface WidgetTableControls {
+    /** A search box over every column. Default true. */
+    readonly search?: boolean;
+    /** Sortable column headers. Default true. */
+    readonly sort?: boolean;
+}
+/** `WidgetTableControls` with every default filled in. */
+interface ResolvedTableControls {
+    readonly search: boolean;
+    readonly sort: boolean;
+}
+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;
+/**
+ * Reads `definition.tableControls` with defaults; undefined when the widget
+ * has none (or both are turned off).
+ */
+declare function resolveTableControls(definition: Pick<WidgetDefinition, 'tableControls'>): ResolvedTableControls | 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>;
+/**
+ * A TABLE's columns and rows as detail data (column keys `c0`, `c1`, ...),
+ * footer ignored, so the table can be searched and sorted with `queryRows`.
+ */
+declare function tableDetailData(data: TableWidgetData): 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;
+    /**
+     * TABLE widgets only: a search box and sortable column headers in the card
+     * itself, working on the rows the card holds. `true` turns on both. With a
+     * `footer` (rows were left out) they only see the rows shown; use `detail`
+     * for the full list.
+     */
+    readonly tableControls?: boolean | WidgetTableControls;
+    /** Fill free space in the row (height, width or both). Default: none. */
+    readonly fill?: WidgetFill;
+    /**
+     * Keeps viewers from rearranging this widget. `true` locks everything:
+     * move, hide and minimize. Use an object to lock only some; fields left out
+     * are not locked.
+     */
+    readonly locked?: boolean | WidgetLock;
+    /**
+     * The widget's home page in a paged dashboard: a page key or title. A
+     * widget no page lists yet (and a widget locked against moving) shows here;
+     * without it, on the first page. Ignored when the layout has no pages.
+     */
+    readonly page?: string;
+    /**
+     * Choices the author offers, with defaults: a default sort, "top N", a
+     * period, which columns show. The chosen values reach your provider as
+     * `ProviderOptions.options`. See `options.ts`.
+     */
+    readonly options?: readonly WidgetOption[];
+}
+/** What a viewer may not do to a locked widget. */
+interface WidgetLock {
+    /** Can't be reordered, and holds its place (a pinned slot). */
+    readonly move?: boolean;
+    /** Can't be hidden. */
+    readonly hide?: boolean;
+    /** Can't be collapsed to its header. */
+    readonly minimize?: boolean;
+}
+/** `WidgetLock` with every default filled in. */
+type ResolvedWidgetLock = Required<WidgetLock>;
+/**
+ * Reads a widget's `locked` setting with defaults: `true` locks move, hide
+ * and minimize, an object locks the fields it sets to `true`, and anything
+ * else (absent, `false`) locks nothing.
+ */
+declare function resolveWidgetLock(definition: Pick<WidgetDefinition, 'locked'>): ResolvedWidgetLock;
+/**
+ * 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;
+
+/** The parts of a widget definition that decide its place in a grid. */
+interface GridItem {
+    readonly key: string;
+    readonly defaultSize?: WidgetSize;
+    readonly fill?: WidgetFill;
+    readonly width?: number;
+}
+/** Columns in a grid that uses widget `width`. */
+declare const WIDTH_COLUMNS = 12;
+/** Smallest and largest `width`, in twelfths of a row. */
+declare const MIN_WIDGET_WIDTH = 2;
+declare const MAX_WIDGET_WIDTH = 12;
+/** Whether `value` is a valid widget `width`: an integer from 2 to 12. */
+declare function isWidgetWidth(value: unknown): value is number;
+/** The width (in twelfths) a `defaultSize` stands for. Default `medium`. */
+declare function widthForSize(size: WidgetSize | undefined): number;
+/** The 12-column width of an item: its `width`, else from its size. */
+declare function itemWidth(item: GridItem): number;
+/** Whether a grid of `items` should use 12 columns (any item sets `width`). */
+declare function usesWidthColumns(items: readonly GridItem[]): boolean;
+/** Whether the widget should take the columns left over in its row. */
+declare function fillsWidth(fill: WidgetFill | undefined): boolean;
+/** Whether the widget should stretch to the height of its row. */
+declare function fillsHeight(fill: WidgetFill | undefined): boolean;
+/**
+ * Columns a size takes in a grid of `columns` tracks: `large` spans
+ * `largeSpan` (default 2), `full` spans every column, anything else one.
+ */
+declare function baseColumnSpan(size: WidgetSize | undefined, columns: number, largeSpan?: number): number;
+/**
+ * Places `items` in a grid of `columns` tracks the way a sparse grid
+ * auto-places them (left to right, wrapping to a new row when an item does
+ * not fit), then gives the columns left over in each row to the items that
+ * `fill` their width, shared evenly (earlier items get the remainder).
+ *
+ * Returns the column span for each width-filling item, keyed by `key`. Items
+ * that do not fill width keep their normal size and are not in the map.
+ */
+declare function fillColumnSpans(items: readonly GridItem[], columns: number, largeSpan?: number): Map<string, number>;
+/**
+ * Like `fillColumnSpans` for a 12-column grid: each item starts at its
+ * `width` (see `itemWidth`) and width-fillers share the leftover twelfths.
+ */
+declare function fillWidthSpans(items: readonly GridItem[]): Map<string, number>;
+/** One row of a placed grid: the widgets in it and their final column spans. */
+interface PlacedRow {
+    readonly keys: readonly string[];
+    /** Column spans, in `keys` order, after width-fillers took the leftovers. */
+    readonly spans: readonly number[];
+}
+/**
+ * The rows `items` occupy in a 12-column grid, exactly as `fillWidthSpans`
+ * places them: left to right, a widget that doesn't fit in the rest of a row
+ * starts the next row whole (a widget is never split), and width-fillers then
+ * grow into the leftover columns. Growth never changes how many rows there
+ * are.
+ */
+declare function placeRows(items: readonly GridItem[]): readonly PlacedRow[];
+/**
+ * How many of `items`, in order, fit in `maxRows` rows of a 12-column grid.
+ * Placement is left to right, so this is the length of the longest prefix
+ * whose rows number at most `maxRows`.
+ */
+declare function fitCount(items: readonly GridItem[], maxRows: number): number;
+
+/**
+ * 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;
+    /** See `WidgetDefinition.locked`. Pinned widgets hold their slot. */
+    readonly locked?: boolean | WidgetLock;
+    /** See `WidgetDefinition.page`: the widget's home page. */
+    readonly page?: string;
+}
+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[];
+    /**
+     * Pages of widgets. Absent, the lists above are the one and only page. With
+     * pages, each page owns its own lists and the top-level lists are left
+     * empty. See `pages.ts`.
+     */
+    readonly pages?: readonly LayoutPage[];
+}
+/** One page of a paged layout: the same lists as a layout, plus a name. */
+interface LayoutPage {
+    /** Unique within the layout and stable when the page is renamed or moved. */
+    readonly key: string;
+    /** Shown in the page bar. At most `MAX_PAGE_TITLE_LENGTH` characters. */
+    readonly title: string;
+    readonly order: readonly string[];
+    readonly hidden: readonly string[];
+    readonly minimized: readonly string[];
+    /** Rows this page holds, overriding the dashboard's default. */
+    readonly maxRows?: number;
+}
+/** Longest page title; longer saved titles are cut. */
+declare const MAX_PAGE_TITLE_LENGTH = 30;
+/**
+ * Most pages `parseLayout` keeps: a safety ceiling against malformed or
+ * hostile JSON, not a product limit.
+ */
+declare const MAX_PARSED_PAGES = 50;
+/** Most rows a page may be given with `maxRows`. */
+declare const MAX_PAGE_ROWS = 20;
+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. Widgets locked against moving are pinned: each keeps its
+ * place from the definitions (never from `layout.order`) and the others
+ * rearrange around it.
+ */
+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, the index is out of range,
+ * or the move isn't allowed: a pinned widget can't move, and nothing can be
+ * moved onto a pinned slot. Free widgets keep their relative order around
+ * pinned ones, so a move that crosses a pinned slot lands on the nearest
+ * free slot you named.
+ */
+declare function moveWidget<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string, toIndex: number): DashboardLayout;
+/**
+ * Moves `key` by `offset` places (negative is earlier). Pinned slots are
+ * stepped over, not counted, and the move is clamped at the first and last
+ * free slot.
+ */
+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;
+/** Options for `enforceLocks`. */
+interface EnforceLocksOptions {
+    /**
+     * Skip enforcement. Set it server-side only for a user who may rearrange
+     * locked widgets (an administrator editing the default layout), never from
+     * a flag the client sends.
+     */
+    readonly overrideLocks?: boolean;
+}
+/**
+ * Removes whatever a widget's lock forbids from a layout: a hide-locked key
+ * leaves `hidden`, a minimize-locked key leaves `minimized`, and a
+ * move-locked key leaves `order` (a pinned widget's place comes from the
+ * definitions). Idempotent; returns the same object when nothing changes.
+ * Run it on a layout a client sends before saving it.
+ */
+declare function enforceLocks<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, options?: EnforceLocksOptions): DashboardLayout;
+
+/**
+ * Pages of widgets: a dashboard split into pages, like the home screens of a
+ * phone. Each page is a small layout (order, hidden, minimized) with a name
+ * and a capacity of `maxRows` rows of 12 columns. Pure functions, in the
+ * style of `layout.ts`: inputs are never mutated, a refusal is a `Result`
+ * with a specific message, and a no-op returns the same object.
+ *
+ * A layout without `pages` has one implicit page (`DEFAULT_PAGE_KEY`), so
+ * everything here also works on layouts saved before pages existed.
+ */
+
+/** The key of the implicit page of a layout that has no `pages`. */
+declare const DEFAULT_PAGE_KEY = "default";
+/** Rows a page holds unless it (or the dashboard) says otherwise. */
+declare const DEFAULT_PAGE_ROWS = 4;
+/** What the page functions need from a widget definition. */
+type PageItem = LayoutItem & GridItem & {
+    /** Used in messages; the key stands in when absent. */
+    readonly title?: string;
+};
+interface PageOptions {
+    /** Rows a page holds when it has no `maxRows` of its own. Default 4. */
+    readonly maxRows?: number;
+}
+/** Whether the layout has pages of its own (rather than one implicit page). */
+declare function hasPages(layout: DashboardLayout): boolean;
+/**
+ * The layout's pages. A layout without `pages` has one implicit page called
+ * "Page 1" made from its top-level lists.
+ */
+declare function pageList(layout: DashboardLayout): readonly LayoutPage[];
+/**
+ * One page as an ordinary layout, so every function in `layout.ts` (move,
+ * hide, minimize, `visibleWidgets`) works on it unchanged. For a layout with
+ * no pages this is the layout itself. Undefined for an unknown page.
+ */
+declare function pageLayout(layout: DashboardLayout, pageKey: string): DashboardLayout | undefined;
+/**
+ * Writes a page's layout (changed with the functions in `layout.ts`) back
+ * into the whole layout. Returns the same object when nothing changed or the
+ * page doesn't exist.
+ */
+declare function withPageLayout(layout: DashboardLayout, pageKey: string, next: DashboardLayout): DashboardLayout;
+/** The key of the page a `page` reference names: a key, else a title. */
+declare function resolvePageKey(layout: DashboardLayout, reference: string | undefined): string | undefined;
+/**
+ * Which page each widget shows on: the page that lists it (in its order or
+ * hidden list), else its home page (`definition.page`, else the first page).
+ * A widget locked against moving always shows on its home page, so a viewer's
+ * saved layout can't move it. Definitions keep their input order.
+ */
+declare function assignPages<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): Map<string, T[]>;
+/** The key of the page a widget shows on; undefined if it isn't a definition. */
+declare function pageOf<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string): string | undefined;
+/** A page's visible widgets, in display order (minimized ones included). */
+declare function pageWidgets<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, pageKey: string): T[];
+/** How full a page is. */
+interface PageRoom {
+    readonly maxRows: number;
+    readonly rowsUsed: number;
+    readonly rowsFree: number;
+}
+/** Rows a page allows, uses and has left, as the grid will draw them. */
+declare function pageRoom<T extends PageItem>(definitions: readonly T[], layout: DashboardLayout, pageKey: string, options?: PageOptions): PageRoom | undefined;
+/** The first `page-N` key no page uses. */
+declare function nextPageKey(layout: DashboardLayout): string;
+interface AddPageOptions {
+    /** The new page's title. Default: the next free "Page N". */
+    readonly title?: string;
+    /** The new page's key. Default: the next free `page-N`. */
+    readonly key?: string;
+}
+/**
+ * Adds an empty page after the last one. A layout without pages gains an
+ * explicit first page holding everything it had.
+ */
+declare function addPage(layout: DashboardLayout, options?: AddPageOptions): Result<DashboardLayout>;
+/** Renames a page. The same layout comes back when the title is unchanged. */
+declare function renamePage(layout: DashboardLayout, pageKey: string, title: string): Result<DashboardLayout>;
+/**
+ * Moves a page `offset` places (negative is earlier), clamped at the ends.
+ * Returns the same layout when nothing moves.
+ */
+declare function movePage(layout: DashboardLayout, pageKey: string, offset: number): DashboardLayout;
+/**
+ * Removes a page. Its widgets move to the end of the previous page (the next
+ * one when it was first), keeping their hidden and minimized state. Refused
+ * for the only page, and when the widgets wouldn't fit on the pages left.
+ */
+declare function removePage<T extends PageItem>(definitions: readonly T[], layout: DashboardLayout, pageKey: string, options?: PageOptions): Result<DashboardLayout>;
+/**
+ * Moves a widget to the end of another page, keeping its hidden and
+ * minimized state. Refused for an unknown widget or page, for a widget locked
+ * against moving, and when a visible widget wouldn't fit in the page's rows.
+ */
+declare function moveWidgetToPage<T extends PageItem>(definitions: readonly T[], layout: DashboardLayout, widgetKey: string, targetKey: string, options?: PageOptions): Result<DashboardLayout>;
+interface NormalizeOptions extends PageOptions {
+    /** Skip lock enforcement, for a user who may rearrange locked widgets. */
+    readonly overrideLocks?: boolean;
+}
+/**
+ * Repairs a layout so it can be trusted, for the place it is saved: unknown
+ * widgets are dropped, locks are enforced, and in a paged layout each widget
+ * lives on one page, titles are trimmed, unique and short, widgets no page
+ * lists yet are placed (on their home page), and a page that holds too many
+ * rows has its overflow moved, in order, to the next page with room or a new
+ * page after it. Nothing is hidden or dropped to make room. Idempotent;
+ * returns the same object when nothing changes.
+ */
+declare function normalizeLayout<T extends PageItem>(definitions: readonly T[], layout: DashboardLayout, options?: NormalizeOptions): 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;
+interface NiceDomain {
+    readonly min: number;
+    readonly max: number;
+    /** From min to max inclusive, evenly spaced on a clean step. */
+    readonly ticks: readonly number[];
+}
+/**
+ * A y-axis domain that always includes 0 (bars grow from a single
+ * baseline), rounded out to a clean step, with about `tickCount` intervals.
+ */
+declare function niceDomain(values: readonly number[], tickCount?: number): NiceDomain;
+/**
+ * Show every `n`th x label so at most `maxLabels` appear (always at least 1).
+ */
+declare function labelStride(count: number, maxLabels?: number): number;
+
+/**
+ * Storage adapters: the contract a developer implements to keep a layout in
+ * localStorage, IndexedDB, a REST API or a database, plus I/O-free helpers
+ * built on it (`createLayoutPersistence` and small adapter wrappers). The
+ * package does no I/O itself: no timers, DOM, `fetch` or storage globals.
+ * See docs/design/storage-adapters.md.
+ */
+
+type StoreErrorCode = 
+/** Storage can't be reached or is disabled. */
+'unavailable'
+/** Storage is full. */
+ | 'quota'
+/** Not allowed to read or write. */
+ | 'forbidden'
+/** The stored revision is newer than the one given. */
+ | 'conflict'
+/** The adapter was given something it can't store. */
+ | 'invalid'
+/** What is stored can't be read back. */
+ | 'corrupt';
+type StoreResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly code: StoreErrorCode;
+    /** Names the key and the cause. */
+    readonly error: string;
+};
+interface StoredValue {
+    /** The serialized layout. */
+    readonly value: string;
+    /** Opaque version (an ETag, a row version) for conflict detection. */
+    readonly revision?: string;
+}
+interface StorageAdapter {
+    /** Resolves `{ ok: true, value: null }` when nothing is stored. */
+    get(key: string, options: {
+        readonly signal: AbortSignal;
+    }): Promise<StoreResult<StoredValue | null>>;
+    /**
+     * With `ifRevision`, fail with `conflict` when the stored revision differs.
+     * Adapters without revisions ignore it (last write wins).
+     */
+    set(key: string, value: string, options: {
+        readonly signal: AbortSignal;
+        readonly ifRevision?: string;
+    }): Promise<StoreResult<StoredValue>>;
+    remove?(key: string, options: {
+        readonly signal: AbortSignal;
+    }): Promise<StoreResult<null>>;
+    /** Optional: report a change made elsewhere (another tab). Returns an unsubscribe. */
+    subscribe?(key: string, onChange: (stored: StoredValue | null) => void): () => void;
+}
+/** UTF-8 byte length without `TextEncoder` (the core has no DOM or Node lib). */
+declare function utf8Length(text: string): number;
+/** An in-memory adapter with revisions and `subscribe`: tests, SSR, fallback. */
+declare function memoryAdapter(initial?: Readonly<Record<string, string>>): StorageAdapter;
+/** Namespaces every key, for several dashboards or apps in one store. */
+declare function withPrefix(adapter: StorageAdapter, prefix: string): StorageAdapter;
+/**
+ * Reads from `primary`, falling back to `secondary` when it errs or holds
+ * nothing. Writes go to `primary` first, then `secondary` (best effort); a
+ * `conflict` from `primary` is returned as is and writes nothing else. When
+ * `primary` can't be written but `secondary` can, the write counts as saved.
+ */
+declare function withFallback(primary: StorageAdapter, secondary: StorageAdapter): StorageAdapter;
+/** Remembers each key's last read or write, so repeated reads skip the store. */
+declare function withReadCache(adapter: StorageAdapter): StorageAdapter;
+/** Rejects writes with `forbidden`: previewing someone else's layout. */
+declare function readOnly(adapter: StorageAdapter): StorageAdapter;
+interface RetryOptions {
+    /** Total tries, including the first. Default 3. */
+    readonly attempts?: number;
+    /** First wait in ms; doubles each retry. Default 200. */
+    readonly delayMs?: number;
+    /** Waits `ms`. You pass it, so the core has no timers. */
+    readonly sleep: (ms: number, signal: AbortSignal) => Promise<void>;
+}
+/** Retries `unavailable` errors (and nothing else) with doubling waits. */
+declare function withRetry(adapter: StorageAdapter, options: RetryOptions): StorageAdapter;
+interface EncodingOptions {
+    /** Applied before storing: compression, or encryption with your own crypto. */
+    readonly encode: (value: string) => string | Promise<string>;
+    /** Reverses `encode` after reading. */
+    readonly decode: (value: string) => string | Promise<string>;
+}
+/** Transforms values on the way in and out. Keys and revisions pass through. */
+declare function withEncoding(adapter: StorageAdapter, codec: EncodingOptions): StorageAdapter;
+interface StorageLogEvent {
+    readonly operation: 'get' | 'set' | 'remove';
+    readonly key: string;
+    readonly ok: boolean;
+    /** Present when `ok` is false. Values are never logged. */
+    readonly code?: StoreErrorCode;
+}
+/** Reports each operation's key and outcome. Never the stored value. */
+declare function withLogging(adapter: StorageAdapter, log: (event: StorageLogEvent) => void): StorageAdapter;
+interface StoreScope {
+    /** Which dashboard: 'sales'. */
+    readonly dashboardKey: string;
+    /** Who it belongs to; absent for shared defaults. A hint for building the key: a server takes the user from the session. */
+    readonly userKey?: string;
+}
+/** Current envelope version written by `createLayoutPersistence`. */
+declare const LAYOUT_ENVELOPE_VERSION = 1;
+/** Default largest serialized layout (bytes). */
+declare const DEFAULT_MAX_LAYOUT_BYTES: number;
+type ConflictPolicy = 
+/** Save anyway; the other device's change is lost. */
+'overwrite'
+/** Drop the local save and return what is stored. */
+ | 'keep-theirs'
+/** Return `outcome: 'conflict'` and let the UI choose (default). */
+ | 'ask'
+/** Merge, then save the result once. */
+ | ((mine: DashboardLayout, theirs: DashboardLayout) => DashboardLayout);
+interface LayoutPersistenceOptions {
+    /** Default 64 KB. */
+    readonly maxBytes?: number;
+    /** For adapters with revisions. Default `'ask'`. */
+    readonly onConflict?: ConflictPolicy;
+    /** Cancels every operation. */
+    readonly signal?: AbortSignal;
+    /** Epoch ms for the envelope's `savedAt`. Default `Date.now`. */
+    readonly now?: () => number;
+}
+interface LoadedLayout {
+    /** Repaired against the definitions; null when nothing is stored. */
+    readonly layout: DashboardLayout | null;
+    readonly revision?: string;
+    /** ISO time from the envelope; absent for a bare legacy layout. */
+    readonly savedAt?: string;
+}
+interface SavedLayout {
+    /**
+     * `saved`: stored (or merged, then stored). `kept-theirs`: the stored layout
+     * won and `layout` is it. `conflict`: nothing was stored and `layout` is
+     * the stored one; decide, then save again with `force: true`.
+     */
+    readonly outcome: 'saved' | 'kept-theirs' | 'conflict';
+    /** What is now stored (or, for `conflict`, what is stored by someone else). */
+    readonly layout: DashboardLayout;
+    readonly revision?: string;
+}
+interface SaveOptions {
+    /** Skip conflict detection and overwrite. */
+    readonly force?: boolean;
+}
+interface LayoutPersistence {
+    /** The adapter key for a scope, for example `dwt:sales:user-42:layout`. */
+    keyFor(scope: StoreScope, part?: 'layout' | 'backup'): string;
+    load(scope: StoreScope, definitions: readonly PageItem[], options?: NormalizeOptions): Promise<StoreResult<LoadedLayout>>;
+    save(scope: StoreScope, layout: DashboardLayout, options?: SaveOptions): Promise<StoreResult<SavedLayout>>;
+    loadBackup(scope: StoreScope): Promise<StoreResult<DashboardLayout | null>>;
+    saveBackup(scope: StoreScope, layout: DashboardLayout): Promise<StoreResult<null>>;
+    /** Removes the layout and its backup. */
+    reset(scope: StoreScope): Promise<StoreResult<null>>;
+    /** Calls `onChange` when another tab or device changes the layout; needs `adapter.subscribe`. */
+    watch(scope: StoreScope, definitions: readonly PageItem[], onChange: (loaded: LoadedLayout) => void, options?: NormalizeOptions): () => void;
+}
+/**
+ * Persistence for layouts over any `StorageAdapter`: an envelope with a
+ * version, tolerant reads repaired against today's definitions, a size limit,
+ * revision tracking with a conflict policy, and saves serialized per key so
+ * rapid edits never race (while one save is in flight, later ones collapse
+ * into the newest).
+ */
+declare function createLayoutPersistence(adapter: StorageAdapter, options?: LayoutPersistenceOptions): LayoutPersistence;
+
+export { type DetailCell as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CachedPayload as C, type DashboardWidget as D, DATE_RANGE_PRESETS as E, DEFAULT_COMPARISON_LABEL as F, type GraphWidgetData as G, DEFAULT_CURRENCY as H, DEFAULT_DETAIL_PAGE_SIZE as I, DEFAULT_EMPTY_TEXT as J, type KpiWidgetData as K, type Locale as L, DEFAULT_MAX_LAYOUT_BYTES as M, type NiceDomain as N, type OptionValues as O, type PageItem as P, DEFAULT_PAGE_KEY as Q, type ResolvedTableControls as R, type StoreScope as S, type TableWidgetData as T, DEFAULT_PAGE_ROWS as U, DETAIL_MODES as V, type WidgetSize as W, type DateRangeOption as X, type DateRangePreset as Y, type DeltaDirection as Z, type DeltaSentiment as _, type WidgetFill as a, WIDGET_SIZES as a$, type DetailColumn as a0, type DetailMode as a1, type DetailPage as a2, type DetailProvider as a3, type DetailProviders as a4, EMPTY_LAYOUT as a5, type EmptyWidget as a6, type EncodingOptions as a7, type EnforceLocksOptions as a8, type Err as a9, type OptionContext as aA, type OptionValue as aB, type PageOptions as aC, type PageRoom as aD, type PlacedRow as aE, type ProviderOptions as aF, type ResolvedDetailOptions as aG, type ResolvedWidget as aH, type ResolvedWidgetLock as aI, type RetryOptions as aJ, type SaveOptions as aK, type SavedLayout as aL, type SortDirection as aM, type SortOption as aN, type StorageAdapter as aO, type StorageLogEvent as aP, type StoreErrorCode as aQ, type StoreResult as aR, type StoredValue as aS, type TableCell as aT, type TableColumn as aU, type TextOption as aV, VALUE_FORMATS as aW, type ValueFormat as aX, WIDGET_FILLS as aY, WIDGET_KINDS as aZ, WIDGET_OPTION_TYPES as a_, type ErrorWidget as aa, type FormatOptions as ab, type GraphPoint as ac, type GraphSeries as ad, type GridItem as ae, type KpiDelta as af, type KpiDeltaOptions as ag, LAYOUT_ENVELOPE_VERSION as ah, type LayoutItem as ai, type LayoutPage as aj, type LayoutPersistenceOptions as ak, type LoadedLayout as al, type LoadingWidget as am, MAX_DETAIL_PAGE_SIZE as an, MAX_GRAPH_SERIES as ao, MAX_PAGE_ROWS as ap, MAX_PAGE_TITLE_LENGTH as aq, MAX_PARSED_PAGES as ar, MAX_TEXT_OPTION_LENGTH as as, MAX_WIDGET_OPTIONS as at, MAX_WIDGET_WIDTH as au, MIN_WIDGET_WIDTH as av, type NumberOption as aw, OPTION_KEY_PATTERN as ax, type Ok as ay, type OkWidget as az, type WidgetDefinition as b, normalizeLayout as b$, WIDTH_COLUMNS as b0, type WidgetCache as b1, type WidgetDataOf as b2, type WidgetDetailOptions as b3, type WidgetEmptyState as b4, type WidgetLock as b5, type WidgetOption as b6, type WidgetProvider as b7, type WidgetStatus as b8, type WidgetTableControls as b9, hasPages as bA, hiddenWidgets as bB, hideWidget as bC, isClientApplied as bD, isColumnKeyFor as bE, isHidden as bF, isIsoInterval as bG, isMinimized as bH, isWidgetEmptyState as bI, isWidgetKind as bJ, isWidgetVisibleTo as bK, isWidgetWidth as bL, itemWidth as bM, kpiDelta as bN, labelStride as bO, loadingWidgets as bP, memoryAdapter as bQ, minimizeWidget as bR, movePage as bS, moveWidget as bT, moveWidgetBy as bU, moveWidgetDown as bV, moveWidgetToPage as bW, moveWidgetUp as bX, nextPageKey as bY, niceDomain as bZ, niceStep as b_, addPage as ba, applyClientOptions as bb, assignPages as bc, baseColumnSpan as bd, cacheKeyFor as be, coerceOptionValue as bf, createLayoutPersistence as bg, defaultDetailQuery as bh, defaultOptionValue as bi, defineWidget as bj, deriveDetailData as bk, describeUnknownError as bl, emptyTextFor as bm, emptyWidget as bn, enforceLocks as bo, err as bp, failedWidget as bq, fillColumnSpans as br, fillWidthSpans as bs, fillsHeight as bt, fillsWidth as bu, finalizeWidget as bv, fitCount as bw, formatCount as bx, formatPercentChange as by, formatValue as bz, type DetailProviderOptions as c, ok as c0, optionValuesFor as c1, optionsCacheSuffix as c2, pageLayout as c3, pageList as c4, pageOf as c5, pageRoom as c6, pageWidgets as c7, parseDetailQuery as c8, parseLayout as c9, tableDetailData as cA, toggleHidden as cB, toggleMinimized as cC, usesWidthColumns as cD, utf8Length as cE, validateDetailData as cF, visibleWidgets as cG, widgetsFor as cH, widthForSize as cI, withEncoding as cJ, withFallback as cK, withLogging as cL, withPageLayout as cM, withPrefix as cN, withReadCache as cO, withRetry as cP, parseSortValue as ca, percentChange as cb, placeRows as cc, pruneLayout as cd, queryRows as ce, readOnly as cf, removePage as cg, renamePage as ch, resolveDateRange as ci, resolveDetailOptions as cj, resolveOptionValues as ck, resolvePageKey as cl, resolvePayload as cm, resolveTableControls as cn, resolveWidget as co, resolveWidgetLock as cp, resolveWidgetUnapplied as cq, resolveWidgets as cr, restoreWidget as cs, sameOptionValues as ct, serializeDetailQuery as cu, serializeLayout as cv, shareOf as cw, showWidget as cx, sortDefinitions as cy, sortFromOptions as cz, type DetailData as d, type DetailQuery as e, type DashboardLayout as f, type GaugeWidgetData as g, type DetailSort as h, type TextWidgetData as i, type WidgetData as j, type LayoutPersistence as k, type NormalizeOptions as l, type ResolveOptions as m, type WidgetContext as n, type WidgetProviders as o, type WidgetKind as p, type Result as q, type WidgetPayload as r, type AddPageOptions as s, type AlertListItem as t, type BarListItem as u, type BooleanOption as v, type ChoiceOption as w, type ColorOption as x, type ColumnsOption as y, type ConflictPolicy as z };