@richardmcquiston01/dashboard-widgets-toolkit 0.10.0 → 0.11.1

package/dist/scale-N69bo7wo.d.cts

@@ -1,758 +0,0 @@
-/**
- * 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;
-
-/**
- * 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;
-}
-/**
- * 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;
-    readonly status: 'empty';
-    /** Why there is nothing to show, e.g. "No orders synced yet." */
-    readonly emptyText: string;
-}
-interface ErrorWidget {
-    readonly definition: WidgetDefinition;
-    readonly status: 'error';
-    /** Names the widget and what failed. */
-    readonly error: string;
-}
-/** 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';
-}
-/** 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
-     * 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. */
-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.
- */
-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;
-}
-/** 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;
-
-/**
- * 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;
-
-/** 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;
-
-export { type KpiDeltaOptions as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CachedPayload as C, type DashboardWidget as D, type DetailCell as E, type DetailColumn as F, type GraphWidgetData as G, type DetailMode as H, type DetailPage as I, type DetailProvider as J, type KpiWidgetData as K, type Locale as L, type DetailProviders as M, type NiceDomain as N, type DetailSort as O, EMPTY_LAYOUT as P, type EmptyWidget as Q, type ResolvedTableControls as R, type EnforceLocksOptions as S, type TableWidgetData as T, type Err as U, type ErrorWidget as V, type WidgetSize as W, type FormatOptions as X, type GraphPoint as Y, type GraphSeries as Z, type KpiDelta as _, type WidgetFill as a, queryRows as a$, type LoadingWidget as a0, MAX_DETAIL_PAGE_SIZE as a1, MAX_GRAPH_SERIES as a2, MAX_PAGE_ROWS as a3, MAX_PAGE_TITLE_LENGTH as a4, MAX_PARSED_PAGES as a5, type Ok as a6, type OkWidget as a7, type ProviderOptions as a8, type ResolvedDetailOptions as a9, err as aA, failedWidget as aB, formatCount as aC, formatPercentChange as aD, formatValue as aE, hiddenWidgets as aF, hideWidget as aG, isHidden as aH, isMinimized as aI, isWidgetEmptyState as aJ, isWidgetKind as aK, isWidgetVisibleTo as aL, kpiDelta as aM, labelStride as aN, loadingWidgets as aO, minimizeWidget as aP, moveWidget as aQ, moveWidgetBy as aR, moveWidgetDown as aS, moveWidgetUp as aT, niceDomain as aU, niceStep as aV, ok as aW, parseDetailQuery as aX, parseLayout as aY, percentChange as aZ, pruneLayout as a_, type ResolvedWidget as aa, type ResolvedWidgetLock as ab, type SortDirection as ac, type TableCell as ad, type TableColumn as ae, VALUE_FORMATS as af, type ValueFormat as ag, WIDGET_FILLS as ah, WIDGET_KINDS as ai, WIDGET_SIZES as aj, type WidgetCache as ak, type WidgetDataOf as al, type WidgetDetailOptions as am, type WidgetEmptyState as an, type WidgetLock as ao, type WidgetProvider as ap, type WidgetStatus as aq, type WidgetTableControls as ar, cacheKeyFor as as, defaultDetailQuery as at, defineWidget as au, deriveDetailData as av, describeUnknownError as aw, emptyTextFor as ax, emptyWidget as ay, enforceLocks as az, type WidgetDefinition as b, resolveDetailOptions as b0, resolvePayload as b1, resolveTableControls as b2, resolveWidget as b3, resolveWidgetLock as b4, resolveWidgets as b5, restoreWidget as b6, serializeDetailQuery as b7, serializeLayout as b8, shareOf as b9, showWidget as ba, sortDefinitions as bb, tableDetailData as bc, toggleHidden as bd, toggleMinimized as be, validateDetailData as bf, visibleWidgets as bg, widgetsFor as bh, 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 ResolveOptions as j, type WidgetContext as k, type WidgetProviders as l, type LayoutItem as m, type Result as n, type LayoutPage as o, type WidgetKind as p, type WidgetPayload as q, type AlertListItem as r, type BarListItem as s, DEFAULT_COMPARISON_LABEL as t, DEFAULT_CURRENCY as u, DEFAULT_DETAIL_PAGE_SIZE as v, DEFAULT_EMPTY_TEXT as w, DETAIL_MODES as x, type DeltaDirection as y, type DeltaSentiment as z };