@richardmcquiston01/dashboard-widgets-toolkit 0.10.0 → 0.11.1

package/dist/core.d.cts

@@ -1,5 +1,5 @@
-import { b as WidgetDefinition, W as WidgetSize, a as WidgetFill, D as DashboardWidget, k as WidgetContext, j as ResolveOptions, l as WidgetProviders, m as LayoutItem, f as DashboardLayout, n as Result, o as LayoutPage, p as WidgetKind, q as WidgetPayload } from './scale-N69bo7wo.cjs';
-export { r as AlertListItem, A as AlertListWidgetData, s as BarListItem, B as BarListWidgetData, C as CachedPayload, t as DEFAULT_COMPARISON_LABEL, u as DEFAULT_CURRENCY, v as DEFAULT_DETAIL_PAGE_SIZE, w as DEFAULT_EMPTY_TEXT, x as DETAIL_MODES, y as DeltaDirection, z as DeltaSentiment, E as DetailCell, F as DetailColumn, d as DetailData, H as DetailMode, I as DetailPage, J as DetailProvider, c as DetailProviderOptions, M as DetailProviders, e as DetailQuery, O as DetailSort, P as EMPTY_LAYOUT, Q as EmptyWidget, S as EnforceLocksOptions, U as Err, V as ErrorWidget, X as FormatOptions, g as GaugeWidgetData, Y as GraphPoint, Z as GraphSeries, G as GraphWidgetData, _ as KpiDelta, $ as KpiDeltaOptions, K as KpiWidgetData, a0 as LoadingWidget, L as Locale, a1 as MAX_DETAIL_PAGE_SIZE, a2 as MAX_GRAPH_SERIES, a3 as MAX_PAGE_ROWS, a4 as MAX_PAGE_TITLE_LENGTH, a5 as MAX_PARSED_PAGES, N as NiceDomain, a6 as Ok, a7 as OkWidget, a8 as ProviderOptions, a9 as ResolvedDetailOptions, R as ResolvedTableControls, aa as ResolvedWidget, ab as ResolvedWidgetLock, ac as SortDirection, ad as TableCell, ae as TableColumn, T as TableWidgetData, h as TextWidgetData, af as VALUE_FORMATS, ag as ValueFormat, ah as WIDGET_FILLS, ai as WIDGET_KINDS, aj as WIDGET_SIZES, ak as WidgetCache, i as WidgetData, al as WidgetDataOf, am as WidgetDetailOptions, an as WidgetEmptyState, ao as WidgetLock, ap as WidgetProvider, aq as WidgetStatus, ar as WidgetTableControls, as as cacheKeyFor, at as defaultDetailQuery, au as defineWidget, av as deriveDetailData, aw as describeUnknownError, ax as emptyTextFor, ay as emptyWidget, az as enforceLocks, aA as err, aB as failedWidget, aC as formatCount, aD as formatPercentChange, aE as formatValue, aF as hiddenWidgets, aG as hideWidget, aH as isHidden, aI as isMinimized, aJ as isWidgetEmptyState, aK as isWidgetKind, aL as isWidgetVisibleTo, aM as kpiDelta, aN as labelStride, aO as loadingWidgets, aP as minimizeWidget, aQ as moveWidget, aR as moveWidgetBy, aS as moveWidgetDown, aT as moveWidgetUp, aU as niceDomain, aV as niceStep, aW as ok, aX as parseDetailQuery, aY as parseLayout, aZ as percentChange, a_ as pruneLayout, a$ as queryRows, b0 as resolveDetailOptions, b1 as resolvePayload, b2 as resolveTableControls, b3 as resolveWidget, b4 as resolveWidgetLock, b5 as resolveWidgets, b6 as restoreWidget, b7 as serializeDetailQuery, b8 as serializeLayout, b9 as shareOf, ba as showWidget, bb as sortDefinitions, bc as tableDetailData, bd as toggleHidden, be as toggleMinimized, bf as validateDetailData, bg as visibleWidgets, bh as widgetsFor } from './scale-N69bo7wo.cjs';
+import { b as WidgetDefinition, D as DashboardWidget, n as WidgetContext, m as ResolveOptions, o as WidgetProviders, p as WidgetKind, q as Result, r as WidgetPayload } from './storage-VaaysVnZ.cjs';
+export { s as AddPageOptions, t as AlertListItem, A as AlertListWidgetData, u as BarListItem, B as BarListWidgetData, v as BooleanOption, C as CachedPayload, w as ChoiceOption, x as ColorOption, y as ColumnsOption, z as ConflictPolicy, E as DATE_RANGE_PRESETS, F as DEFAULT_COMPARISON_LABEL, H as DEFAULT_CURRENCY, I as DEFAULT_DETAIL_PAGE_SIZE, J as DEFAULT_EMPTY_TEXT, M as DEFAULT_MAX_LAYOUT_BYTES, Q as DEFAULT_PAGE_KEY, U as DEFAULT_PAGE_ROWS, V as DETAIL_MODES, f as DashboardLayout, X as DateRangeOption, Y as DateRangePreset, Z as DeltaDirection, _ as DeltaSentiment, $ as DetailCell, a0 as DetailColumn, d as DetailData, a1 as DetailMode, a2 as DetailPage, a3 as DetailProvider, c as DetailProviderOptions, a4 as DetailProviders, e as DetailQuery, h as DetailSort, a5 as EMPTY_LAYOUT, a6 as EmptyWidget, a7 as EncodingOptions, a8 as EnforceLocksOptions, a9 as Err, aa as ErrorWidget, ab as FormatOptions, g as GaugeWidgetData, ac as GraphPoint, ad as GraphSeries, G as GraphWidgetData, ae as GridItem, af as KpiDelta, ag as KpiDeltaOptions, K as KpiWidgetData, ah as LAYOUT_ENVELOPE_VERSION, ai as LayoutItem, aj as LayoutPage, k as LayoutPersistence, ak as LayoutPersistenceOptions, al as LoadedLayout, am as LoadingWidget, L as Locale, an as MAX_DETAIL_PAGE_SIZE, ao as MAX_GRAPH_SERIES, ap as MAX_PAGE_ROWS, aq as MAX_PAGE_TITLE_LENGTH, ar as MAX_PARSED_PAGES, as as MAX_TEXT_OPTION_LENGTH, at as MAX_WIDGET_OPTIONS, au as MAX_WIDGET_WIDTH, av as MIN_WIDGET_WIDTH, N as NiceDomain, l as NormalizeOptions, aw as NumberOption, ax as OPTION_KEY_PATTERN, ay as Ok, az as OkWidget, aA as OptionContext, aB as OptionValue, O as OptionValues, P as PageItem, aC as PageOptions, aD as PageRoom, aE as PlacedRow, aF as ProviderOptions, aG as ResolvedDetailOptions, R as ResolvedTableControls, aH as ResolvedWidget, aI as ResolvedWidgetLock, aJ as RetryOptions, aK as SaveOptions, aL as SavedLayout, aM as SortDirection, aN as SortOption, aO as StorageAdapter, aP as StorageLogEvent, aQ as StoreErrorCode, aR as StoreResult, S as StoreScope, aS as StoredValue, aT as TableCell, aU as TableColumn, T as TableWidgetData, aV as TextOption, i as TextWidgetData, aW as VALUE_FORMATS, aX as ValueFormat, aY as WIDGET_FILLS, aZ as WIDGET_KINDS, a_ as WIDGET_OPTION_TYPES, a$ as WIDGET_SIZES, b0 as WIDTH_COLUMNS, b1 as WidgetCache, j as WidgetData, b2 as WidgetDataOf, b3 as WidgetDetailOptions, b4 as WidgetEmptyState, a as WidgetFill, b5 as WidgetLock, b6 as WidgetOption, b7 as WidgetProvider, W as WidgetSize, b8 as WidgetStatus, b9 as WidgetTableControls, ba as addPage, bb as applyClientOptions, bc as assignPages, bd as baseColumnSpan, be as cacheKeyFor, bf as coerceOptionValue, bg as createLayoutPersistence, bh as defaultDetailQuery, bi as defaultOptionValue, bj as defineWidget, bk as deriveDetailData, bl as describeUnknownError, bm as emptyTextFor, bn as emptyWidget, bo as enforceLocks, bp as err, bq as failedWidget, br as fillColumnSpans, bs as fillWidthSpans, bt as fillsHeight, bu as fillsWidth, bv as finalizeWidget, bw as fitCount, bx as formatCount, by as formatPercentChange, bz as formatValue, bA as hasPages, bB as hiddenWidgets, bC as hideWidget, bD as isClientApplied, bE as isColumnKeyFor, bF as isHidden, bG as isIsoInterval, bH as isMinimized, bI as isWidgetEmptyState, bJ as isWidgetKind, bK as isWidgetVisibleTo, bL as isWidgetWidth, bM as itemWidth, bN as kpiDelta, bO as labelStride, bP as loadingWidgets, bQ as memoryAdapter, bR as minimizeWidget, bS as movePage, bT as moveWidget, bU as moveWidgetBy, bV as moveWidgetDown, bW as moveWidgetToPage, bX as moveWidgetUp, bY as nextPageKey, bZ as niceDomain, b_ as niceStep, b$ as normalizeLayout, c0 as ok, c1 as optionValuesFor, c2 as optionsCacheSuffix, c3 as pageLayout, c4 as pageList, c5 as pageOf, c6 as pageRoom, c7 as pageWidgets, c8 as parseDetailQuery, c9 as parseLayout, ca as parseSortValue, cb as percentChange, cc as placeRows, cd as pruneLayout, ce as queryRows, cf as readOnly, cg as removePage, ch as renamePage, ci as resolveDateRange, cj as resolveDetailOptions, ck as resolveOptionValues, cl as resolvePageKey, cm as resolvePayload, cn as resolveTableControls, co as resolveWidget, cp as resolveWidgetLock, cq as resolveWidgetUnapplied, cr as resolveWidgets, cs as restoreWidget, ct as sameOptionValues, cu as serializeDetailQuery, cv as serializeLayout, cw as shareOf, cx as showWidget, cy as sortDefinitions, cz as sortFromOptions, cA as tableDetailData, cB as toggleHidden, cC as toggleMinimized, cD as usesWidthColumns, cE as utf8Length, cF as validateDetailData, cG as visibleWidgets, cH as widgetsFor, cI as widthForSize, cJ as withEncoding, cK as withFallback, cL as withLogging, cM as withPageLayout, cN as withPrefix, cO as withReadCache, cP as withRetry } from './storage-VaaysVnZ.cjs';
 
 /**
  * Maker Toolkit compatibility. Its API (`apps/api/src/widgets`) serves
@@ -33,71 +33,6 @@ interface LegacyWidgetDefinition {
  */
 declare function fromLegacyDefinition(legacy: LegacyWidgetDefinition): WidgetDefinition | null;
 
-/** 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;
-
 /**
  * Loads widgets one by one, after the first render, and reports each result
  * as it arrives. It is the logic behind the React `useWidgets` hook, kept
@@ -137,122 +72,21 @@ interface WidgetLoader {
      * than the interval would otherwise be restarted forever and never finish).
      */
     refresh(key?: string, options?: RefreshOptions): void;
+    /**
+     * Sets the values chosen for a widget's options (all of them: keys left out
+     * go back to their defaults). A choice only the toolkit applies (`sort` or
+     * `columns` with `apply: 'client'`) re-derives the payload it already has.
+     * A choice your provider sees reloads that widget alone: what is shown stays
+     * (marked `stale`) until the new data arrives, and an earlier answer for the
+     * same choices comes back from the cache. Does nothing when the resolved
+     * values don't change.
+     */
+    setOptions(key: string, chosen: Readonly<Record<string, unknown>>): void;
     /** Aborts everything in flight and ignores any later result. */
     dispose(): void;
 }
 declare function createWidgetLoader<C extends WidgetContext>(options: WidgetLoaderOptions<C>): WidgetLoader;
 
-/**
- * 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;
-
 /**
  * Link and image URL checks. Payloads often come from an API, so a link is
  * only rendered when it can't run script: http(s), mailto, or a relative
@@ -290,4 +124,4 @@ declare function validateWidgetData(value: unknown, options?: ValidateWidgetData
  */
 declare function validateWidgetDefinition(value: unknown): Result<WidgetDefinition>;
 
-export { type AddPageOptions, DEFAULT_PAGE_KEY, DEFAULT_PAGE_ROWS, DashboardLayout, DashboardWidget, type GridItem, LayoutItem, LayoutPage, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, MAX_WIDGET_WIDTH, MIN_WIDGET_WIDTH, type NormalizeOptions, type PageItem, type PageOptions, type PageRoom, type PlacedRow, type RefreshOptions, ResolveOptions, Result, type ValidateWidgetDataOptions, WIDTH_COLUMNS, WidgetContext, WidgetDefinition, WidgetFill, WidgetKind, type WidgetLoader, type WidgetLoaderOptions, WidgetPayload, WidgetProviders, WidgetSize, addPage, assignPages, baseColumnSpan, createWidgetLoader, fillColumnSpans, fillWidthSpans, fillsHeight, fillsWidth, fitCount, fromLegacyDefinition, hasPages, isSafeHref, isSafeImageUrl, isWidgetWidth, itemWidth, movePage, moveWidgetToPage, nextPageKey, normalizeLayout, pageLayout, pageList, pageOf, pageRoom, pageWidgets, placeRows, removePage, renamePage, resolvePageKey, upgradeLegacyWidgetData, usesWidthColumns, validateWidgetData, validateWidgetDefinition, widthForSize, withPageLayout };
+export { DashboardWidget, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, type RefreshOptions, ResolveOptions, Result, type ValidateWidgetDataOptions, WidgetContext, WidgetDefinition, WidgetKind, type WidgetLoader, type WidgetLoaderOptions, WidgetPayload, WidgetProviders, createWidgetLoader, fromLegacyDefinition, isSafeHref, isSafeImageUrl, upgradeLegacyWidgetData, validateWidgetData, validateWidgetDefinition };

package/dist/core.d.ts

@@ -1,5 +1,5 @@
-import { b as WidgetDefinition, W as WidgetSize, a as WidgetFill, D as DashboardWidget, k as WidgetContext, j as ResolveOptions, l as WidgetProviders, m as LayoutItem, f as DashboardLayout, n as Result, o as LayoutPage, p as WidgetKind, q as WidgetPayload } from './scale-N69bo7wo.js';
-export { r as AlertListItem, A as AlertListWidgetData, s as BarListItem, B as BarListWidgetData, C as CachedPayload, t as DEFAULT_COMPARISON_LABEL, u as DEFAULT_CURRENCY, v as DEFAULT_DETAIL_PAGE_SIZE, w as DEFAULT_EMPTY_TEXT, x as DETAIL_MODES, y as DeltaDirection, z as DeltaSentiment, E as DetailCell, F as DetailColumn, d as DetailData, H as DetailMode, I as DetailPage, J as DetailProvider, c as DetailProviderOptions, M as DetailProviders, e as DetailQuery, O as DetailSort, P as EMPTY_LAYOUT, Q as EmptyWidget, S as EnforceLocksOptions, U as Err, V as ErrorWidget, X as FormatOptions, g as GaugeWidgetData, Y as GraphPoint, Z as GraphSeries, G as GraphWidgetData, _ as KpiDelta, $ as KpiDeltaOptions, K as KpiWidgetData, a0 as LoadingWidget, L as Locale, a1 as MAX_DETAIL_PAGE_SIZE, a2 as MAX_GRAPH_SERIES, a3 as MAX_PAGE_ROWS, a4 as MAX_PAGE_TITLE_LENGTH, a5 as MAX_PARSED_PAGES, N as NiceDomain, a6 as Ok, a7 as OkWidget, a8 as ProviderOptions, a9 as ResolvedDetailOptions, R as ResolvedTableControls, aa as ResolvedWidget, ab as ResolvedWidgetLock, ac as SortDirection, ad as TableCell, ae as TableColumn, T as TableWidgetData, h as TextWidgetData, af as VALUE_FORMATS, ag as ValueFormat, ah as WIDGET_FILLS, ai as WIDGET_KINDS, aj as WIDGET_SIZES, ak as WidgetCache, i as WidgetData, al as WidgetDataOf, am as WidgetDetailOptions, an as WidgetEmptyState, ao as WidgetLock, ap as WidgetProvider, aq as WidgetStatus, ar as WidgetTableControls, as as cacheKeyFor, at as defaultDetailQuery, au as defineWidget, av as deriveDetailData, aw as describeUnknownError, ax as emptyTextFor, ay as emptyWidget, az as enforceLocks, aA as err, aB as failedWidget, aC as formatCount, aD as formatPercentChange, aE as formatValue, aF as hiddenWidgets, aG as hideWidget, aH as isHidden, aI as isMinimized, aJ as isWidgetEmptyState, aK as isWidgetKind, aL as isWidgetVisibleTo, aM as kpiDelta, aN as labelStride, aO as loadingWidgets, aP as minimizeWidget, aQ as moveWidget, aR as moveWidgetBy, aS as moveWidgetDown, aT as moveWidgetUp, aU as niceDomain, aV as niceStep, aW as ok, aX as parseDetailQuery, aY as parseLayout, aZ as percentChange, a_ as pruneLayout, a$ as queryRows, b0 as resolveDetailOptions, b1 as resolvePayload, b2 as resolveTableControls, b3 as resolveWidget, b4 as resolveWidgetLock, b5 as resolveWidgets, b6 as restoreWidget, b7 as serializeDetailQuery, b8 as serializeLayout, b9 as shareOf, ba as showWidget, bb as sortDefinitions, bc as tableDetailData, bd as toggleHidden, be as toggleMinimized, bf as validateDetailData, bg as visibleWidgets, bh as widgetsFor } from './scale-N69bo7wo.js';
+import { b as WidgetDefinition, D as DashboardWidget, n as WidgetContext, m as ResolveOptions, o as WidgetProviders, p as WidgetKind, q as Result, r as WidgetPayload } from './storage-VaaysVnZ.js';
+export { s as AddPageOptions, t as AlertListItem, A as AlertListWidgetData, u as BarListItem, B as BarListWidgetData, v as BooleanOption, C as CachedPayload, w as ChoiceOption, x as ColorOption, y as ColumnsOption, z as ConflictPolicy, E as DATE_RANGE_PRESETS, F as DEFAULT_COMPARISON_LABEL, H as DEFAULT_CURRENCY, I as DEFAULT_DETAIL_PAGE_SIZE, J as DEFAULT_EMPTY_TEXT, M as DEFAULT_MAX_LAYOUT_BYTES, Q as DEFAULT_PAGE_KEY, U as DEFAULT_PAGE_ROWS, V as DETAIL_MODES, f as DashboardLayout, X as DateRangeOption, Y as DateRangePreset, Z as DeltaDirection, _ as DeltaSentiment, $ as DetailCell, a0 as DetailColumn, d as DetailData, a1 as DetailMode, a2 as DetailPage, a3 as DetailProvider, c as DetailProviderOptions, a4 as DetailProviders, e as DetailQuery, h as DetailSort, a5 as EMPTY_LAYOUT, a6 as EmptyWidget, a7 as EncodingOptions, a8 as EnforceLocksOptions, a9 as Err, aa as ErrorWidget, ab as FormatOptions, g as GaugeWidgetData, ac as GraphPoint, ad as GraphSeries, G as GraphWidgetData, ae as GridItem, af as KpiDelta, ag as KpiDeltaOptions, K as KpiWidgetData, ah as LAYOUT_ENVELOPE_VERSION, ai as LayoutItem, aj as LayoutPage, k as LayoutPersistence, ak as LayoutPersistenceOptions, al as LoadedLayout, am as LoadingWidget, L as Locale, an as MAX_DETAIL_PAGE_SIZE, ao as MAX_GRAPH_SERIES, ap as MAX_PAGE_ROWS, aq as MAX_PAGE_TITLE_LENGTH, ar as MAX_PARSED_PAGES, as as MAX_TEXT_OPTION_LENGTH, at as MAX_WIDGET_OPTIONS, au as MAX_WIDGET_WIDTH, av as MIN_WIDGET_WIDTH, N as NiceDomain, l as NormalizeOptions, aw as NumberOption, ax as OPTION_KEY_PATTERN, ay as Ok, az as OkWidget, aA as OptionContext, aB as OptionValue, O as OptionValues, P as PageItem, aC as PageOptions, aD as PageRoom, aE as PlacedRow, aF as ProviderOptions, aG as ResolvedDetailOptions, R as ResolvedTableControls, aH as ResolvedWidget, aI as ResolvedWidgetLock, aJ as RetryOptions, aK as SaveOptions, aL as SavedLayout, aM as SortDirection, aN as SortOption, aO as StorageAdapter, aP as StorageLogEvent, aQ as StoreErrorCode, aR as StoreResult, S as StoreScope, aS as StoredValue, aT as TableCell, aU as TableColumn, T as TableWidgetData, aV as TextOption, i as TextWidgetData, aW as VALUE_FORMATS, aX as ValueFormat, aY as WIDGET_FILLS, aZ as WIDGET_KINDS, a_ as WIDGET_OPTION_TYPES, a$ as WIDGET_SIZES, b0 as WIDTH_COLUMNS, b1 as WidgetCache, j as WidgetData, b2 as WidgetDataOf, b3 as WidgetDetailOptions, b4 as WidgetEmptyState, a as WidgetFill, b5 as WidgetLock, b6 as WidgetOption, b7 as WidgetProvider, W as WidgetSize, b8 as WidgetStatus, b9 as WidgetTableControls, ba as addPage, bb as applyClientOptions, bc as assignPages, bd as baseColumnSpan, be as cacheKeyFor, bf as coerceOptionValue, bg as createLayoutPersistence, bh as defaultDetailQuery, bi as defaultOptionValue, bj as defineWidget, bk as deriveDetailData, bl as describeUnknownError, bm as emptyTextFor, bn as emptyWidget, bo as enforceLocks, bp as err, bq as failedWidget, br as fillColumnSpans, bs as fillWidthSpans, bt as fillsHeight, bu as fillsWidth, bv as finalizeWidget, bw as fitCount, bx as formatCount, by as formatPercentChange, bz as formatValue, bA as hasPages, bB as hiddenWidgets, bC as hideWidget, bD as isClientApplied, bE as isColumnKeyFor, bF as isHidden, bG as isIsoInterval, bH as isMinimized, bI as isWidgetEmptyState, bJ as isWidgetKind, bK as isWidgetVisibleTo, bL as isWidgetWidth, bM as itemWidth, bN as kpiDelta, bO as labelStride, bP as loadingWidgets, bQ as memoryAdapter, bR as minimizeWidget, bS as movePage, bT as moveWidget, bU as moveWidgetBy, bV as moveWidgetDown, bW as moveWidgetToPage, bX as moveWidgetUp, bY as nextPageKey, bZ as niceDomain, b_ as niceStep, b$ as normalizeLayout, c0 as ok, c1 as optionValuesFor, c2 as optionsCacheSuffix, c3 as pageLayout, c4 as pageList, c5 as pageOf, c6 as pageRoom, c7 as pageWidgets, c8 as parseDetailQuery, c9 as parseLayout, ca as parseSortValue, cb as percentChange, cc as placeRows, cd as pruneLayout, ce as queryRows, cf as readOnly, cg as removePage, ch as renamePage, ci as resolveDateRange, cj as resolveDetailOptions, ck as resolveOptionValues, cl as resolvePageKey, cm as resolvePayload, cn as resolveTableControls, co as resolveWidget, cp as resolveWidgetLock, cq as resolveWidgetUnapplied, cr as resolveWidgets, cs as restoreWidget, ct as sameOptionValues, cu as serializeDetailQuery, cv as serializeLayout, cw as shareOf, cx as showWidget, cy as sortDefinitions, cz as sortFromOptions, cA as tableDetailData, cB as toggleHidden, cC as toggleMinimized, cD as usesWidthColumns, cE as utf8Length, cF as validateDetailData, cG as visibleWidgets, cH as widgetsFor, cI as widthForSize, cJ as withEncoding, cK as withFallback, cL as withLogging, cM as withPageLayout, cN as withPrefix, cO as withReadCache, cP as withRetry } from './storage-VaaysVnZ.js';
 
 /**
  * Maker Toolkit compatibility. Its API (`apps/api/src/widgets`) serves
@@ -33,71 +33,6 @@ interface LegacyWidgetDefinition {
  */
 declare function fromLegacyDefinition(legacy: LegacyWidgetDefinition): WidgetDefinition | null;
 
-/** 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;
-
 /**
  * Loads widgets one by one, after the first render, and reports each result
  * as it arrives. It is the logic behind the React `useWidgets` hook, kept
@@ -137,122 +72,21 @@ interface WidgetLoader {
      * than the interval would otherwise be restarted forever and never finish).
      */
     refresh(key?: string, options?: RefreshOptions): void;
+    /**
+     * Sets the values chosen for a widget's options (all of them: keys left out
+     * go back to their defaults). A choice only the toolkit applies (`sort` or
+     * `columns` with `apply: 'client'`) re-derives the payload it already has.
+     * A choice your provider sees reloads that widget alone: what is shown stays
+     * (marked `stale`) until the new data arrives, and an earlier answer for the
+     * same choices comes back from the cache. Does nothing when the resolved
+     * values don't change.
+     */
+    setOptions(key: string, chosen: Readonly<Record<string, unknown>>): void;
     /** Aborts everything in flight and ignores any later result. */
     dispose(): void;
 }
 declare function createWidgetLoader<C extends WidgetContext>(options: WidgetLoaderOptions<C>): WidgetLoader;
 
-/**
- * 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;
-
 /**
  * Link and image URL checks. Payloads often come from an API, so a link is
  * only rendered when it can't run script: http(s), mailto, or a relative
@@ -290,4 +124,4 @@ declare function validateWidgetData(value: unknown, options?: ValidateWidgetData
  */
 declare function validateWidgetDefinition(value: unknown): Result<WidgetDefinition>;
 
-export { type AddPageOptions, DEFAULT_PAGE_KEY, DEFAULT_PAGE_ROWS, DashboardLayout, DashboardWidget, type GridItem, LayoutItem, LayoutPage, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, MAX_WIDGET_WIDTH, MIN_WIDGET_WIDTH, type NormalizeOptions, type PageItem, type PageOptions, type PageRoom, type PlacedRow, type RefreshOptions, ResolveOptions, Result, type ValidateWidgetDataOptions, WIDTH_COLUMNS, WidgetContext, WidgetDefinition, WidgetFill, WidgetKind, type WidgetLoader, type WidgetLoaderOptions, WidgetPayload, WidgetProviders, WidgetSize, addPage, assignPages, baseColumnSpan, createWidgetLoader, fillColumnSpans, fillWidthSpans, fillsHeight, fillsWidth, fitCount, fromLegacyDefinition, hasPages, isSafeHref, isSafeImageUrl, isWidgetWidth, itemWidth, movePage, moveWidgetToPage, nextPageKey, normalizeLayout, pageLayout, pageList, pageOf, pageRoom, pageWidgets, placeRows, removePage, renamePage, resolvePageKey, upgradeLegacyWidgetData, usesWidthColumns, validateWidgetData, validateWidgetDefinition, widthForSize, withPageLayout };
+export { DashboardWidget, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, type RefreshOptions, ResolveOptions, Result, type ValidateWidgetDataOptions, WidgetContext, WidgetDefinition, WidgetKind, type WidgetLoader, type WidgetLoaderOptions, WidgetPayload, WidgetProviders, createWidgetLoader, fromLegacyDefinition, isSafeHref, isSafeImageUrl, upgradeLegacyWidgetData, validateWidgetData, validateWidgetDefinition };