@richardmcquiston01/dashboard-widgets-toolkit 0.9.0 → 0.10.0

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 WidgetKind, n as Result, o as WidgetPayload } from './scale-CrXxawQn.cjs';
-export { p as AlertListItem, A as AlertListWidgetData, q as BarListItem, B as BarListWidgetData, C as CachedPayload, r as DEFAULT_COMPARISON_LABEL, s as DEFAULT_CURRENCY, t as DEFAULT_DETAIL_PAGE_SIZE, u as DEFAULT_EMPTY_TEXT, v as DETAIL_MODES, f as DashboardLayout, w as DeltaDirection, x as DeltaSentiment, y as DetailCell, z as DetailColumn, d as DetailData, E as DetailMode, F as DetailPage, H as DetailProvider, c as DetailProviderOptions, I as DetailProviders, e as DetailQuery, J as DetailSort, M as EMPTY_LAYOUT, O as EmptyWidget, P as EnforceLocksOptions, Q as Err, S as ErrorWidget, U as FormatOptions, g as GaugeWidgetData, V as GraphPoint, X as GraphSeries, G as GraphWidgetData, Y as KpiDelta, Z as KpiDeltaOptions, K as KpiWidgetData, _ as LayoutItem, $ as LoadingWidget, L as Locale, a0 as MAX_DETAIL_PAGE_SIZE, a1 as MAX_GRAPH_SERIES, N as NiceDomain, a2 as Ok, a3 as OkWidget, a4 as ProviderOptions, a5 as ResolvedDetailOptions, R as ResolvedTableControls, a6 as ResolvedWidget, a7 as ResolvedWidgetLock, a8 as SortDirection, a9 as TableCell, aa as TableColumn, T as TableWidgetData, h as TextWidgetData, ab as VALUE_FORMATS, ac as ValueFormat, ad as WIDGET_FILLS, ae as WIDGET_KINDS, af as WIDGET_SIZES, ag as WidgetCache, i as WidgetData, ah as WidgetDataOf, ai as WidgetDetailOptions, aj as WidgetEmptyState, ak as WidgetLock, al as WidgetProvider, am as WidgetStatus, an as WidgetTableControls, ao as cacheKeyFor, ap as defaultDetailQuery, aq as defineWidget, ar as deriveDetailData, as as describeUnknownError, at as emptyTextFor, au as emptyWidget, av as enforceLocks, aw as err, ax as failedWidget, ay as formatCount, az as formatPercentChange, aA as formatValue, aB as hiddenWidgets, aC as hideWidget, aD as isHidden, aE as isMinimized, aF as isWidgetEmptyState, aG as isWidgetKind, aH as isWidgetVisibleTo, aI as kpiDelta, aJ as labelStride, aK as loadingWidgets, aL as minimizeWidget, aM as moveWidget, aN as moveWidgetBy, aO as moveWidgetDown, aP as moveWidgetUp, aQ as niceDomain, aR as niceStep, aS as ok, aT as parseDetailQuery, aU as parseLayout, aV as percentChange, aW as pruneLayout, aX as queryRows, aY as resolveDetailOptions, aZ as resolvePayload, a_ as resolveTableControls, a$ as resolveWidget, b0 as resolveWidgetLock, b1 as resolveWidgets, b2 as restoreWidget, b3 as serializeDetailQuery, b4 as serializeLayout, b5 as shareOf, b6 as showWidget, b7 as sortDefinitions, b8 as tableDetailData, b9 as toggleHidden, ba as toggleMinimized, bb as validateDetailData, bc as visibleWidgets, bd as widgetsFor } from './scale-CrXxawQn.cjs';
+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';
 
 /**
  * Maker Toolkit compatibility. Its API (`apps/api/src/widgets`) serves
@@ -77,6 +77,26 @@ declare function fillColumnSpans(items: readonly GridItem[], columns: number, la
  * `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
@@ -122,6 +142,117 @@ interface WidgetLoader {
 }
 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
@@ -159,4 +290,4 @@ declare function validateWidgetData(value: unknown, options?: ValidateWidgetData
  */
 declare function validateWidgetDefinition(value: unknown): Result<WidgetDefinition>;
 
-export { DashboardWidget, type GridItem, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, MAX_WIDGET_WIDTH, MIN_WIDGET_WIDTH, type RefreshOptions, ResolveOptions, Result, type ValidateWidgetDataOptions, WIDTH_COLUMNS, WidgetContext, WidgetDefinition, WidgetFill, WidgetKind, type WidgetLoader, type WidgetLoaderOptions, WidgetPayload, WidgetProviders, WidgetSize, baseColumnSpan, createWidgetLoader, fillColumnSpans, fillWidthSpans, fillsHeight, fillsWidth, fromLegacyDefinition, isSafeHref, isSafeImageUrl, isWidgetWidth, itemWidth, upgradeLegacyWidgetData, usesWidthColumns, validateWidgetData, validateWidgetDefinition, widthForSize };
+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 };

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 WidgetKind, n as Result, o as WidgetPayload } from './scale-CrXxawQn.js';
-export { p as AlertListItem, A as AlertListWidgetData, q as BarListItem, B as BarListWidgetData, C as CachedPayload, r as DEFAULT_COMPARISON_LABEL, s as DEFAULT_CURRENCY, t as DEFAULT_DETAIL_PAGE_SIZE, u as DEFAULT_EMPTY_TEXT, v as DETAIL_MODES, f as DashboardLayout, w as DeltaDirection, x as DeltaSentiment, y as DetailCell, z as DetailColumn, d as DetailData, E as DetailMode, F as DetailPage, H as DetailProvider, c as DetailProviderOptions, I as DetailProviders, e as DetailQuery, J as DetailSort, M as EMPTY_LAYOUT, O as EmptyWidget, P as EnforceLocksOptions, Q as Err, S as ErrorWidget, U as FormatOptions, g as GaugeWidgetData, V as GraphPoint, X as GraphSeries, G as GraphWidgetData, Y as KpiDelta, Z as KpiDeltaOptions, K as KpiWidgetData, _ as LayoutItem, $ as LoadingWidget, L as Locale, a0 as MAX_DETAIL_PAGE_SIZE, a1 as MAX_GRAPH_SERIES, N as NiceDomain, a2 as Ok, a3 as OkWidget, a4 as ProviderOptions, a5 as ResolvedDetailOptions, R as ResolvedTableControls, a6 as ResolvedWidget, a7 as ResolvedWidgetLock, a8 as SortDirection, a9 as TableCell, aa as TableColumn, T as TableWidgetData, h as TextWidgetData, ab as VALUE_FORMATS, ac as ValueFormat, ad as WIDGET_FILLS, ae as WIDGET_KINDS, af as WIDGET_SIZES, ag as WidgetCache, i as WidgetData, ah as WidgetDataOf, ai as WidgetDetailOptions, aj as WidgetEmptyState, ak as WidgetLock, al as WidgetProvider, am as WidgetStatus, an as WidgetTableControls, ao as cacheKeyFor, ap as defaultDetailQuery, aq as defineWidget, ar as deriveDetailData, as as describeUnknownError, at as emptyTextFor, au as emptyWidget, av as enforceLocks, aw as err, ax as failedWidget, ay as formatCount, az as formatPercentChange, aA as formatValue, aB as hiddenWidgets, aC as hideWidget, aD as isHidden, aE as isMinimized, aF as isWidgetEmptyState, aG as isWidgetKind, aH as isWidgetVisibleTo, aI as kpiDelta, aJ as labelStride, aK as loadingWidgets, aL as minimizeWidget, aM as moveWidget, aN as moveWidgetBy, aO as moveWidgetDown, aP as moveWidgetUp, aQ as niceDomain, aR as niceStep, aS as ok, aT as parseDetailQuery, aU as parseLayout, aV as percentChange, aW as pruneLayout, aX as queryRows, aY as resolveDetailOptions, aZ as resolvePayload, a_ as resolveTableControls, a$ as resolveWidget, b0 as resolveWidgetLock, b1 as resolveWidgets, b2 as restoreWidget, b3 as serializeDetailQuery, b4 as serializeLayout, b5 as shareOf, b6 as showWidget, b7 as sortDefinitions, b8 as tableDetailData, b9 as toggleHidden, ba as toggleMinimized, bb as validateDetailData, bc as visibleWidgets, bd as widgetsFor } from './scale-CrXxawQn.js';
+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';
 
 /**
  * Maker Toolkit compatibility. Its API (`apps/api/src/widgets`) serves
@@ -77,6 +77,26 @@ declare function fillColumnSpans(items: readonly GridItem[], columns: number, la
  * `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
@@ -122,6 +142,117 @@ interface WidgetLoader {
 }
 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
@@ -159,4 +290,4 @@ declare function validateWidgetData(value: unknown, options?: ValidateWidgetData
  */
 declare function validateWidgetDefinition(value: unknown): Result<WidgetDefinition>;
 
-export { DashboardWidget, type GridItem, type LegacyWidgetDefinition, MAX_REPORTED_PROBLEMS, MAX_WIDGET_WIDTH, MIN_WIDGET_WIDTH, type RefreshOptions, ResolveOptions, Result, type ValidateWidgetDataOptions, WIDTH_COLUMNS, WidgetContext, WidgetDefinition, WidgetFill, WidgetKind, type WidgetLoader, type WidgetLoaderOptions, WidgetPayload, WidgetProviders, WidgetSize, baseColumnSpan, createWidgetLoader, fillColumnSpans, fillWidthSpans, fillsHeight, fillsWidth, fromLegacyDefinition, isSafeHref, isSafeImageUrl, isWidgetWidth, itemWidth, upgradeLegacyWidgetData, usesWidthColumns, validateWidgetData, validateWidgetDefinition, widthForSize };
+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 };