@richardmcquiston01/dashboard-widgets-toolkit 0.9.0 → 0.11.0

package/dist/react.cjs

@@ -429,21 +429,36 @@ function fillColumnSpans(items, columns, largeSpan = 2) {
 function fillWidthSpans(items) {
   return placeAndFill(items, WIDTH_COLUMNS, itemWidth);
 }
+function placeRows(items) {
+  return placeAndFillRows(items, WIDTH_COLUMNS, itemWidth).rows;
+}
 function placeAndFill(items, columns, spanOf) {
+  return placeAndFillRows(items, columns, spanOf).spans;
+}
+function placeAndFillRows(items, columns, spanOf) {
   const trackCount = Math.max(1, Math.floor(columns));
   const spans = /* @__PURE__ */ new Map();
+  const rows = [];
   let row = [];
   let used = 0;
   function closeRow() {
+    if (row.length === 0) return;
     const fillers = row.filter(({ item }) => fillsWidth(item.fill));
     const leftover = trackCount - used;
+    const finalSpans = /* @__PURE__ */ new Map();
     if (fillers.length > 0) {
       const share = Math.floor(leftover / fillers.length);
       const remainder = leftover % fillers.length;
       fillers.forEach(({ item, span }, index) => {
-        spans.set(item.key, span + share + (index < remainder ? 1 : 0));
+        const grown = span + share + (index < remainder ? 1 : 0);
+        spans.set(item.key, grown);
+        finalSpans.set(item.key, grown);
       });
     }
+    rows.push({
+      keys: row.map(({ item }) => item.key),
+      spans: row.map(({ item, span }) => finalSpans.get(item.key) ?? span)
+    });
     row = [];
     used = 0;
   }
@@ -454,7 +469,266 @@ function placeAndFill(items, columns, spanOf) {
     used += span;
   }
   closeRow();
-  return spans;
+  return { spans, rows };
+}
+
+// src/core/options.ts
+var DATE_RANGE_PRESETS = [
+  "today",
+  "yesterday",
+  "last7",
+  "last30",
+  "last90",
+  "thisMonth",
+  "lastMonth",
+  "thisYear",
+  "lastYear"
+];
+var COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
+var INTERVAL_PATTERN = /^(\d{4}-\d{2}-\d{2})\/(\d{4}-\d{2}-\d{2})$/;
+var CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+function isClientApplied(option) {
+  return (option.type === "sort" || option.type === "columns") && option.apply === "client";
+}
+function civilToday(context) {
+  const now = context.now ?? Date.now();
+  let timeZone = context.timeZone ?? "UTC";
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone });
+  } catch {
+    timeZone = "UTC";
+  }
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit"
+  }).formatToParts(new Date(now));
+  const pick = (type) => Number(parts.find((part) => part.type === type)?.value ?? "0");
+  return { year: pick("year"), month: pick("month"), day: pick("day") };
+}
+function toIso(epochMs) {
+  return new Date(epochMs).toISOString().slice(0, 10);
+}
+var DAY_MS = 864e5;
+function parseIsoDay(text) {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(text);
+  if (match === null) return void 0;
+  const epoch = Date.UTC(
+    Number(match[1]),
+    Number(match[2]) - 1,
+    Number(match[3])
+  );
+  return toIso(epoch) === text ? epoch : void 0;
+}
+function isIsoInterval(value) {
+  const match = INTERVAL_PATTERN.exec(value);
+  if (match === null) return false;
+  const start = parseIsoDay(match[1]);
+  const end = parseIsoDay(match[2]);
+  return start !== void 0 && end !== void 0 && start <= end;
+}
+function isPreset(value) {
+  return DATE_RANGE_PRESETS.includes(value);
+}
+function resolveDateRange(value, context = {}) {
+  if (isIsoInterval(value)) return value;
+  if (!isPreset(value)) return void 0;
+  const today = civilToday(context);
+  const todayMs = Date.UTC(today.year, today.month - 1, today.day);
+  const range = (startMs, endMs) => `${toIso(startMs)}/${toIso(endMs)}`;
+  switch (value) {
+    case "today":
+      return range(todayMs, todayMs);
+    case "yesterday":
+      return range(todayMs - DAY_MS, todayMs - DAY_MS);
+    case "last7":
+      return range(todayMs - 6 * DAY_MS, todayMs);
+    case "last30":
+      return range(todayMs - 29 * DAY_MS, todayMs);
+    case "last90":
+      return range(todayMs - 89 * DAY_MS, todayMs);
+    case "thisMonth":
+      return range(Date.UTC(today.year, today.month - 1, 1), todayMs);
+    case "lastMonth":
+      return range(
+        Date.UTC(today.year, today.month - 2, 1),
+        Date.UTC(today.year, today.month - 1, 1) - DAY_MS
+      );
+    case "thisYear":
+      return range(Date.UTC(today.year, 0, 1), todayMs);
+    case "lastYear":
+      return range(
+        Date.UTC(today.year - 1, 0, 1),
+        Date.UTC(today.year, 0, 1) - DAY_MS
+      );
+  }
+}
+function onStepGrid(option, value) {
+  if (option.step === void 0) return true;
+  const steps = (value - option.min) / option.step;
+  return Math.abs(steps - Math.round(steps)) < 1e-9;
+}
+function parseSortValue(value) {
+  const separator = value.lastIndexOf(":");
+  if (separator <= 0) return void 0;
+  const column = value.slice(0, separator);
+  const direction = value.slice(separator + 1);
+  if (direction !== "asc" && direction !== "desc") return void 0;
+  return { column, direction };
+}
+function sortFromOptions(definition, values) {
+  if (values === void 0) return void 0;
+  const sortOption = definition.options?.find(
+    (option) => option.type === "sort"
+  );
+  if (sortOption === void 0) return void 0;
+  const chosen = values[sortOption.key];
+  return typeof chosen === "string" ? parseSortValue(chosen) : void 0;
+}
+function coerceOptionValue(option, value, context = {}) {
+  switch (option.type) {
+    case "choice":
+      return typeof value === "string" && option.choices.some((choice) => choice.value === value) ? value : void 0;
+    case "number":
+      return typeof value === "number" && Number.isFinite(value) && value >= option.min && value <= option.max && onStepGrid(option, value) ? value : void 0;
+    case "boolean":
+      return typeof value === "boolean" ? value : void 0;
+    case "text": {
+      if (typeof value !== "string") return void 0;
+      const trimmed = value.trim();
+      return trimmed.length <= option.maxLength && !CONTROL_CHARACTERS.test(trimmed) ? trimmed : void 0;
+    }
+    case "dateRange": {
+      if (typeof value !== "string") return void 0;
+      if (isPreset(value) && option.presets !== void 0 && !option.presets.some((preset) => preset.value === value)) {
+        return void 0;
+      }
+      return resolveDateRange(value, context);
+    }
+    case "color":
+      return typeof value === "string" && COLOR_PATTERN.test(value) ? value.toLowerCase() : void 0;
+    case "sort": {
+      if (typeof value !== "string") return void 0;
+      const sort = parseSortValue(value);
+      return sort !== void 0 && option.columns.some((column) => column.key === sort.column) ? value : void 0;
+    }
+    case "columns": {
+      if (!Array.isArray(value) || value.length === 0) return void 0;
+      const keys = value;
+      const allowed = new Set(option.columns.map((c) => c.key));
+      const seen = /* @__PURE__ */ new Set();
+      for (const key of keys) {
+        if (typeof key !== "string" || !allowed.has(key) || seen.has(key)) {
+          return void 0;
+        }
+        seen.add(key);
+      }
+      return [...seen];
+    }
+  }
+}
+function defaultOptionValue(option, context = {}) {
+  switch (option.type) {
+    case "dateRange":
+      return resolveDateRange(option.default, context);
+    case "sort":
+      return option.default;
+    case "columns":
+      return [...option.default];
+    default:
+      return option.default;
+  }
+}
+var NO_VALUES = Object.freeze({});
+function resolveOptionValues(definition, chosen, context = {}) {
+  const options = definition.options;
+  if (options === void 0 || options.length === 0) return NO_VALUES;
+  const values = {};
+  for (const option of options) {
+    const picked = chosen?.[option.key];
+    const value = (picked === void 0 ? void 0 : coerceOptionValue(option, picked, context)) ?? defaultOptionValue(option, context);
+    if (value !== void 0) values[option.key] = value;
+  }
+  return values;
+}
+function sameValue(a, b) {
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, i) => item === b[i]);
+  }
+  return a === b;
+}
+function sameOptionValues(a, b) {
+  const keys = Object.keys({ ...a, ...b });
+  return keys.every((key) => sameValue(a[key], b[key]));
+}
+function optionsCacheSuffix(definition, values, context = {}) {
+  const parts = [];
+  for (const option of definition.options ?? []) {
+    if (isClientApplied(option)) continue;
+    const value = values[option.key];
+    if (sameValue(value, defaultOptionValue(option, context))) continue;
+    parts.push(
+      `${option.key}=${encodeURIComponent(JSON.stringify(value ?? null))}`
+    );
+  }
+  parts.sort();
+  return parts.length === 0 ? "" : `?${parts.join("&")}`;
+}
+function tableColumnIndex(key) {
+  const match = /^c(\d+)$/.exec(key);
+  return match === null ? void 0 : Number(match[1]);
+}
+function sortBarItems(items, sort) {
+  const sign = sort.direction === "desc" ? -1 : 1;
+  return items.map((item, index) => ({ item, index })).sort((a, b) => {
+    const order = sort.column === "value" ? a.item.value - b.item.value : a.item.label.localeCompare(b.item.label);
+    return order * sign || a.index - b.index;
+  }).map(({ item }) => item);
+}
+function applyClientOptions(definition, data, values) {
+  const options = definition.options ?? [];
+  const sortOption = options.find(
+    (o) => o.type === "sort" && o.apply === "client"
+  );
+  const columnsOption = options.find(
+    (o) => o.type === "columns" && o.apply === "client"
+  );
+  const sortValue = sortOption === void 0 ? void 0 : values[sortOption.key];
+  const columnsValue = columnsOption === void 0 ? void 0 : values[columnsOption.key];
+  let next = data;
+  if (typeof sortValue === "string") {
+    const sort = parseSortValue(sortValue);
+    if (sort !== void 0 && next.kind === "BAR_LIST") {
+      if (sort.column === "label" || sort.column === "value") {
+        next = { ...next, items: sortBarItems(next.items, sort) };
+      }
+    } else if (sort !== void 0 && next.kind === "TABLE") {
+      const index = tableColumnIndex(sort.column);
+      if (index !== void 0 && index < next.columns.length) {
+        const sorted = queryRows(tableDetailData(next), {
+          page: 1,
+          pageSize: Math.max(1, next.rows.length),
+          sort
+        });
+        if (sorted.ok) next = { ...next, rows: sorted.value.rows };
+      }
+    }
+  }
+  if (Array.isArray(columnsValue) && next.kind === "TABLE") {
+    const table = next;
+    const indexes = columnsValue.map(tableColumnIndex).filter(
+      (index) => index !== void 0 && index < table.columns.length
+    );
+    if (indexes.length > 0) {
+      next = {
+        ...table,
+        columns: indexes.map((i) => table.columns[i]),
+        rows: table.rows.map((row) => indexes.map((i) => row[i]))
+      };
+    }
+  }
+  return next;
 }
 
 // src/core/scale.ts
@@ -537,6 +811,27 @@ var DEFAULT_LABELS = {
   dashboardControls: "Dashboard controls",
   locked: (title) => `${title} is locked`,
   lockedForViewers: (title) => `${title} is locked for viewers`,
+  pageBar: "Pages",
+  pageTabName: (index, count, title) => `Page ${index} of ${count}: ${title}`,
+  previousPageButton: "Previous page",
+  nextPageButton: "Next page",
+  managePages: "Manage pages",
+  addPage: "Add page",
+  renamePage: (title) => `Rename ${title}`,
+  pageTitle: "Page title",
+  savePageTitle: "Save page title",
+  cancelPageTitle: "Cancel renaming",
+  deletePage: (title) => `Delete ${title}`,
+  confirmDeletePage: (title) => `Delete the page "${title}" and move its widgets to another page?`,
+  movePageLeft: (title) => `Move ${title} page left`,
+  movePageRight: (title) => `Move ${title} page right`,
+  moveToPage: (title) => `Move ${title} to another page`,
+  moveToPagePlaceholder: "Move to page\u2026",
+  moveToPageOption: (title, rowsFree) => `${title} (${rowsFree} ${rowsFree === 1 ? "row" : "rows"} free)`,
+  newPageOption: "New page\u2026",
+  movedToPage: (title, pageTitle) => `${title} moved to ${pageTitle}`,
+  pageFull: (pageTitle, maxRows) => `Page "${pageTitle}" is full (${maxRows} rows). Move or hide a widget first.`,
+  emptyPage: "This page has no widgets. Move one here from another page.",
   opensInNewTab: "(opens in a new tab)",
   view: (title) => `View ${title}`,
   close: "Close",
@@ -1202,7 +1497,8 @@ function GaugeWidget({
 }
 function TableWidget({
   data,
-  controls
+  controls,
+  initialSort
 }) {
   if (controls === void 0) {
     return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "dwt-table-wrap", children: [
@@ -1210,7 +1506,14 @@ function TableWidget({
       data.footer !== void 0 && /* @__PURE__ */ jsxRuntime.jsx("p", { className: "dwt-note", children: data.footer })
     ] });
   }
-  return /* @__PURE__ */ jsxRuntime.jsx(InteractiveTable, { data, controls });
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    InteractiveTable,
+    {
+      data,
+      controls,
+      initialSort
+    }
+  );
 }
 function TableView({
   data,
@@ -1263,13 +1566,14 @@ function nextTableSort(current, column) {
 }
 function InteractiveTable({
   data,
-  controls
+  controls,
+  initialSort
 }) {
   const slot = useSlotClassName();
   const { labels, locale } = useWidgetSettings();
   const searchId = react.useId();
   const [search, setSearch] = react.useState("");
-  const [sort, setSort] = react.useState(void 0);
+  const [sort, setSort] = react.useState(initialSort);
   const localeTag = typeof locale === "string" ? locale : locale?.[0];
   const query = {
     page: 1,
@@ -1371,7 +1675,8 @@ function AlertListWidget({
 }
 function WidgetContent({
   data,
-  tableControls
+  tableControls,
+  initialSort
 }) {
   switch (data.kind) {
     case "TEXT":
@@ -1381,7 +1686,14 @@ function WidgetContent({
     case "GAUGE":
       return /* @__PURE__ */ jsxRuntime.jsx(GaugeWidget, { data });
     case "TABLE":
-      return /* @__PURE__ */ jsxRuntime.jsx(TableWidget, { data, controls: tableControls });
+      return /* @__PURE__ */ jsxRuntime.jsx(
+        TableWidget,
+        {
+          data,
+          controls: tableControls,
+          initialSort
+        }
+      );
     case "BAR_LIST":
       return /* @__PURE__ */ jsxRuntime.jsx(BarListWidget, { data });
     case "ALERT_LIST":
@@ -1578,7 +1890,8 @@ function ResolvedWidgetCard({
         WidgetContent,
         {
           data: widget.data,
-          tableControls: resolveTableControls(definition)
+          tableControls: resolveTableControls(definition),
+          initialSort: sortFromOptions(definition, widget.options)
         }
       ) : null
     }
@@ -1625,6 +1938,9 @@ function isWidgetVisibleTo(definition, roles) {
 }
 
 // src/core/layout.ts
+var MAX_PAGE_TITLE_LENGTH = 30;
+var MAX_PARSED_PAGES = 50;
+var MAX_PAGE_ROWS = 20;
 var EMPTY_LAYOUT = Object.freeze({
   order: Object.freeze([]),
   hidden: Object.freeze([]),
@@ -1739,6 +2055,22 @@ function restoreWidget(layout, key) {
 function toggleMinimized(layout, key) {
   return isMinimized(layout, key) ? restoreWidget(layout, key) : minimizeWidget(layout, key);
 }
+function mapLayoutLists(layout, change) {
+  const top = change(layout);
+  const pages = layout.pages?.map((page) => {
+    const next = change(page);
+    return next.order === page.order && next.hidden === page.hidden && next.minimized === page.minimized ? page : { ...page, ...next };
+  });
+  const pagesChanged = pages !== void 0 && pages.some((page, i) => page !== layout.pages?.[i]);
+  if (top.order === layout.order && top.hidden === layout.hidden && top.minimized === layout.minimized && !pagesChanged) {
+    return layout;
+  }
+  return {
+    ...layout,
+    ...top,
+    ...pages === void 0 ? {} : { pages }
+  };
+}
 function enforceLocks(definitions, layout, options = {}) {
   if (options.overrideLocks === true) return layout;
   const noMove = /* @__PURE__ */ new Set();
@@ -1750,11 +2082,337 @@ function enforceLocks(definitions, layout, options = {}) {
     if (lock.hide) noHide.add(definition.key);
     if (lock.minimize) noMinimize.add(definition.key);
   }
-  const without = (keys, drop) => keys.some((key) => drop.has(key)) ? keys.filter((key) => !drop.has(key)) : keys;
-  const order = without(layout.order, noMove);
-  const hidden = without(layout.hidden, noHide);
-  const minimized = without(layout.minimized, noMinimize);
-  return order === layout.order && hidden === layout.hidden && minimized === layout.minimized ? layout : { ...layout, order, hidden, minimized };
+  const without2 = (keys, drop) => keys.some((key) => drop.has(key)) ? keys.filter((key) => !drop.has(key)) : keys;
+  return mapLayoutLists(layout, (lists) => ({
+    order: without2(lists.order, noMove),
+    hidden: without2(lists.hidden, noHide),
+    minimized: without2(lists.minimized, noMinimize)
+  }));
+}
+
+// src/core/pages.ts
+var DEFAULT_PAGE_KEY = "default";
+var DEFAULT_PAGE_ROWS = 4;
+function rowsAllowed(page, options) {
+  const rows = page.maxRows ?? options.maxRows ?? DEFAULT_PAGE_ROWS;
+  return Math.max(1, Math.min(MAX_PAGE_ROWS, Math.floor(rows)));
+}
+function hasPages(layout) {
+  return layout.pages !== void 0 && layout.pages.length > 0;
+}
+function pageList(layout) {
+  if (layout.pages !== void 0 && layout.pages.length > 0) {
+    return layout.pages;
+  }
+  return [
+    {
+      key: DEFAULT_PAGE_KEY,
+      title: "Page 1",
+      order: layout.order,
+      hidden: layout.hidden,
+      minimized: layout.minimized
+    }
+  ];
+}
+function withExplicitPages(layout) {
+  if (hasPages(layout)) return layout;
+  return {
+    ...layout,
+    order: [],
+    hidden: [],
+    minimized: [],
+    pages: pageList(layout)
+  };
+}
+function sameKeys(a, b) {
+  return a === b || a.length === b.length && a.every((k, i) => k === b[i]);
+}
+function pageLayout(layout, pageKey) {
+  if (!hasPages(layout))
+    return pageKey === DEFAULT_PAGE_KEY ? layout : void 0;
+  const page = layout.pages?.find(
+    (p) => p.key === pageKey
+  );
+  if (page === void 0) return void 0;
+  const { pages, ...rest } = layout;
+  return {
+    ...rest,
+    order: page.order,
+    hidden: page.hidden,
+    minimized: page.minimized
+  };
+}
+function withPageLayout(layout, pageKey, next) {
+  const current = pageLayout(layout, pageKey);
+  if (current === void 0 || sameKeys(current.order, next.order) && sameKeys(current.hidden, next.hidden) && sameKeys(current.minimized, next.minimized)) {
+    return layout;
+  }
+  if (!hasPages(layout)) {
+    return {
+      ...layout,
+      order: next.order,
+      hidden: next.hidden,
+      minimized: next.minimized
+    };
+  }
+  return {
+    ...layout,
+    pages: (layout.pages ?? []).map(
+      (page) => page.key === pageKey ? {
+        ...page,
+        order: next.order,
+        hidden: next.hidden,
+        minimized: next.minimized
+      } : page
+    )
+  };
+}
+function normalizedTitle(title) {
+  return title.trim().normalize("NFKC").toLowerCase();
+}
+function resolvePageKey(layout, reference) {
+  if (reference === void 0 || reference === "") return void 0;
+  const pages = pageList(layout);
+  const byKey = pages.find((p) => p.key === reference);
+  if (byKey !== void 0) return byKey.key;
+  const wanted = normalizedTitle(reference);
+  return pages.find((p) => normalizedTitle(p.title) === wanted)?.key;
+}
+function homePageKey(layout, item) {
+  return resolvePageKey(layout, item.page) ?? pageList(layout)[0].key;
+}
+function assignPages(definitions, layout) {
+  const pages = pageList(layout);
+  const assigned = new Map(pages.map((p) => [p.key, []]));
+  for (const definition of definitions) {
+    let pageKey;
+    if (!resolveWidgetLock(definition).move) {
+      pageKey = pages.find(
+        (p) => p.order.includes(definition.key) || p.hidden.includes(definition.key)
+      )?.key;
+    }
+    assigned.get(pageKey ?? homePageKey(layout, definition))?.push(definition);
+  }
+  return assigned;
+}
+function pageOf(definitions, layout, key) {
+  for (const [pageKey, widgets] of assignPages(definitions, layout)) {
+    if (widgets.some((w) => w.key === key)) return pageKey;
+  }
+  return void 0;
+}
+function pageWidgets(definitions, layout, pageKey) {
+  const onPage = assignPages(definitions, layout).get(pageKey) ?? [];
+  const view = pageLayout(layout, pageKey);
+  return view === void 0 ? [] : visibleWidgets(onPage, view);
+}
+function pageRoom(definitions, layout, pageKey, options = {}) {
+  const page = pageList(layout).find(
+    (p) => p.key === pageKey
+  );
+  if (page === void 0) return void 0;
+  const maxRows = rowsAllowed(page, options);
+  const rowsUsed = placeRows(
+    pageWidgets(definitions, layout, pageKey)
+  ).length;
+  return { maxRows, rowsUsed, rowsFree: Math.max(0, maxRows - rowsUsed) };
+}
+function describePage(page) {
+  return `Page "${page.title}"`;
+}
+function titleOf(item) {
+  return item.title ?? item.key;
+}
+function checkTitle(layout, title, exceptKey) {
+  const trimmed = title.trim();
+  if (trimmed === "") return err("A page title must not be empty.");
+  if (trimmed.length > MAX_PAGE_TITLE_LENGTH) {
+    return err(
+      `Page title "${trimmed}" is ${trimmed.length} characters; the most is ${MAX_PAGE_TITLE_LENGTH}.`
+    );
+  }
+  const wanted = normalizedTitle(trimmed);
+  const clash = pageList(layout).find(
+    (p) => p.key !== exceptKey && normalizedTitle(p.title) === wanted
+  );
+  if (clash !== void 0) {
+    return err(`Another page is already called "${clash.title}".`);
+  }
+  return ok(trimmed);
+}
+function nextPageKey(layout) {
+  const keys = new Set(pageList(layout).map((p) => p.key));
+  let n = 1;
+  while (keys.has(`page-${n}`)) n += 1;
+  return `page-${n}`;
+}
+function nextPageTitle(layout) {
+  const used = new Set(
+    pageList(layout).map((p) => normalizedTitle(p.title))
+  );
+  let n = pageList(layout).length + 1;
+  while (used.has(normalizedTitle(`Page ${n}`))) n += 1;
+  return `Page ${n}`;
+}
+function addPage(layout, options = {}) {
+  if (pageList(layout).length >= MAX_PARSED_PAGES) {
+    return err(
+      `The layout already has ${MAX_PARSED_PAGES} pages, the most it can keep.`
+    );
+  }
+  const key = options.key ?? nextPageKey(layout);
+  if (pageList(layout).some((p) => p.key === key)) {
+    return err(`A page with the key "${key}" already exists.`);
+  }
+  const title = checkTitle(
+    layout,
+    options.title ?? nextPageTitle(layout)
+  );
+  if (!title.ok) return title;
+  const base = withExplicitPages(layout);
+  const page = {
+    key,
+    title: title.value,
+    order: [],
+    hidden: [],
+    minimized: []
+  };
+  return ok({ ...base, pages: [...base.pages ?? [], page] });
+}
+function renamePage(layout, pageKey, title) {
+  const page = pageList(layout).find(
+    (p) => p.key === pageKey
+  );
+  if (page === void 0) return err(`Page "${pageKey}" doesn't exist.`);
+  const checked = checkTitle(layout, title, pageKey);
+  if (!checked.ok) return checked;
+  if (checked.value === page.title) return ok(layout);
+  const base = withExplicitPages(layout);
+  return ok({
+    ...base,
+    pages: (base.pages ?? []).map(
+      (p) => p.key === pageKey ? { ...p, title: checked.value } : p
+    )
+  });
+}
+function movePage(layout, pageKey, offset) {
+  const pages = layout.pages ?? [];
+  const from = pages.findIndex((p) => p.key === pageKey);
+  if (from === -1) return layout;
+  const to = Math.max(
+    0,
+    Math.min(pages.length - 1, from + Math.trunc(offset))
+  );
+  if (to === from) return layout;
+  const next = [...pages];
+  const [moved] = next.splice(from, 1);
+  next.splice(to, 0, moved);
+  return { ...layout, pages: next };
+}
+function overflowing(definitions, layout, options) {
+  return pageList(layout).find(
+    (page) => placeRows(pageWidgets(definitions, layout, page.key)).length > rowsAllowed(page, options)
+  );
+}
+function removePage(definitions, layout, pageKey, options = {}) {
+  const pages = pageList(layout);
+  const index = pages.findIndex((p) => p.key === pageKey);
+  const page = pages[index];
+  if (page === void 0) return err(`Page "${pageKey}" doesn't exist.`);
+  if (pages.length === 1) {
+    return err(
+      `${describePage(page)} is the only page, so it can't be removed.`
+    );
+  }
+  const target = pages[index > 0 ? index - 1 : 1];
+  const merged = {
+    ...layout,
+    pages: pages.filter((p) => p.key !== pageKey).map(
+      (p) => p.key === target.key ? {
+        ...p,
+        order: index > 0 ? [...p.order, ...page.order] : [...page.order, ...p.order],
+        hidden: [...p.hidden, ...page.hidden],
+        minimized: [...p.minimized, ...page.minimized]
+      } : p
+    )
+  };
+  const full = overflowing(
+    definitions,
+    merged,
+    options
+  );
+  if (full !== void 0) {
+    return err(
+      `${describePage(page)} has widgets that don't fit on the other pages (${describePage(full)} would need more than ${rowsAllowed(full, options)} rows). Move or hide some first.`
+    );
+  }
+  return ok(merged);
+}
+function without(keys, key) {
+  return keys.includes(key) ? keys.filter((k) => k !== key) : keys;
+}
+function moveWidgetToPage(definitions, layout, widgetKey, targetKey, options = {}) {
+  const widget = definitions.find((d) => d.key === widgetKey);
+  if (widget === void 0) {
+    return err(
+      `Widget "${widgetKey}" isn't one of the widgets, so it can't be moved to a page.`
+    );
+  }
+  const pages = pageList(layout);
+  const target = pages.find((p) => p.key === targetKey);
+  if (target === void 0) return err(`Page "${targetKey}" doesn't exist.`);
+  const sourceKey = pageOf(definitions, layout, widgetKey);
+  if (sourceKey === targetKey) return ok(layout);
+  if (resolveWidgetLock(widget).move) {
+    return err(
+      `Widget "${titleOf(widget)}" is locked against moving, so it can't be moved to ${describePage(target)}.`
+    );
+  }
+  const base = withExplicitPages(layout);
+  const source = (base.pages ?? []).find(
+    (p) => p.key === sourceKey
+  );
+  const hidden = source.hidden.includes(widgetKey);
+  const minimized = source.minimized.includes(widgetKey);
+  const targetOrder = pageWidgets(
+    definitions,
+    base,
+    targetKey
+  ).map((d) => d.key);
+  const moved = {
+    ...base,
+    pages: (base.pages ?? []).map((p) => {
+      if (p.key === sourceKey) {
+        return {
+          ...p,
+          order: without(p.order, widgetKey),
+          hidden: without(p.hidden, widgetKey),
+          minimized: without(p.minimized, widgetKey)
+        };
+      }
+      if (p.key === targetKey) {
+        return {
+          ...p,
+          order: hidden ? p.order : [...targetOrder, widgetKey],
+          hidden: hidden ? [...p.hidden, widgetKey] : p.hidden,
+          minimized: minimized ? [...p.minimized, widgetKey] : p.minimized
+        };
+      }
+      return p;
+    })
+  };
+  if (!hidden) {
+    const allowed = rowsAllowed(target, options);
+    const needed = placeRows(
+      pageWidgets(definitions, moved, targetKey)
+    ).length;
+    if (needed > allowed) {
+      return err(
+        `${describePage(target)} has no room for "${titleOf(widget)}": it would need row ${needed}, and the page allows ${allowed}.`
+      );
+    }
+  }
+  return ok(moved);
 }
 function nextSort(current, column) {
   if (current?.column !== column) return { column, direction: "asc" };
@@ -1995,7 +2653,8 @@ function WidgetDetailDialog({
     }
   );
 }
-function useDetailData(definition, load, enabled, fallback) {
+var NO_OPTION_VALUES = Object.freeze({});
+function useDetailData(definition, load, enabled, fallback, optionValues = NO_OPTION_VALUES) {
   const [state, setState] = react.useState({ status: "loading" });
   const [attempt, setAttempt] = react.useState(0);
   react.useEffect(() => {
@@ -2005,6 +2664,7 @@ function useDetailData(definition, load, enabled, fallback) {
     Promise.resolve().then(
       () => load === void 0 ? void 0 : load(definition, {
         signal: controller.signal,
+        options: optionValues,
         query: defaultDetailQuery()
       })
     ).then((raw) => {
@@ -2032,9 +2692,28 @@ function useDetailData(definition, load, enabled, fallback) {
       });
     });
     return () => controller.abort();
-  }, [enabled, load, fallback, definition, attempt]);
+  }, [enabled, load, fallback, definition, optionValues, attempt]);
   return { state, reload: () => setAttempt((count) => count + 1) };
 }
+var NEW_PAGE_VALUE = "__new-page__";
+function PagePanel({
+  paged,
+  id,
+  labelledBy,
+  children
+}) {
+  if (!paged) return /* @__PURE__ */ jsxRuntime.jsx(jsxRuntime.Fragment, { children });
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      role: "tabpanel",
+      id,
+      "aria-labelledby": labelledBy,
+      className: "dwt-page-panel",
+      children
+    }
+  );
+}
 var NARROW_VIEWPORT_QUERY = "(max-width: 640px)";
 var WIDE_GRID_PX = 900;
 function useFillSpans(definitions, gridRef, twelve) {
@@ -2129,7 +2808,14 @@ function DetailHost({
   const { definition } = widget;
   const options = resolveDetailOptions(definition);
   const pageSize = options?.pageSize ?? 25;
-  const [query, setQuery] = react.useState(defaultDetailQuery(pageSize));
+  const optionSort = sortFromOptions(
+    definition,
+    widget.options
+  );
+  const [query, setQuery] = react.useState({
+    ...defaultDetailQuery(pageSize),
+    ...optionSort === void 0 ? {} : { sort: optionSort }
+  });
   const derived = react.useMemo(
     () => widget.status === "ok" ? deriveDetailData(widget.data, locale) : void 0,
     [widget, locale]
@@ -2138,7 +2824,8 @@ function DetailHost({
     definition,
     loadDetail,
     true,
-    derived
+    derived,
+    widget.options
   );
   const title = options?.title ?? definition.title;
   return /* @__PURE__ */ jsxRuntime.jsx(WidgetDetailDialog, { title, open: true, onClose, children: /* @__PURE__ */ jsxRuntime.jsx(
@@ -2205,6 +2892,181 @@ function InlineConfirm({
     }
   );
 }
+function PageTabs({
+  pages,
+  activeKey,
+  idPrefix,
+  panelId,
+  announcement,
+  onSelect
+}) {
+  const slot = useSlotClassName();
+  const { labels } = useWidgetSettings();
+  const tabs = react.useRef(/* @__PURE__ */ new Map());
+  const activeIndex = pages.findIndex((p) => p.key === activeKey);
+  function onKeyDown(event, index) {
+    const last = pages.length - 1;
+    let next;
+    switch (event.key) {
+      case "ArrowRight":
+      case "ArrowDown":
+        next = index === last ? 0 : index + 1;
+        break;
+      case "ArrowLeft":
+      case "ArrowUp":
+        next = index === 0 ? last : index - 1;
+        break;
+      case "Home":
+        next = 0;
+        break;
+      case "End":
+        next = last;
+        break;
+      default:
+        return;
+    }
+    event.preventDefault();
+    const target = pages[next];
+    if (target === void 0) return;
+    onSelect(target.key);
+    tabs.current.get(target.key)?.focus();
+  }
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: slot("pageBar", "dwt-pages"), children: [
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "button",
+      {
+        type: "button",
+        className: slot(
+          "button",
+          "dwt-button",
+          "dwt-icon-button",
+          "dwt-page-nav"
+        ),
+        "aria-label": labels.previousPageButton,
+        disabled: activeIndex <= 0,
+        onClick: () => onSelect(pages[activeIndex - 1].key),
+        children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2039" })
+      }
+    ),
+    /* @__PURE__ */ jsxRuntime.jsx("div", { role: "tablist", "aria-label": labels.pageBar, className: "dwt-page-tabs", children: pages.map((page, index) => {
+      const selected = page.key === activeKey;
+      return /* @__PURE__ */ jsxRuntime.jsxs(
+        "button",
+        {
+          ref: (element) => {
+            if (element === null) tabs.current.delete(page.key);
+            else tabs.current.set(page.key, element);
+          },
+          type: "button",
+          role: "tab",
+          id: `${idPrefix}-tab-${index}`,
+          "aria-selected": selected,
+          "aria-controls": panelId,
+          "aria-label": labels.pageTabName(
+            index + 1,
+            pages.length,
+            page.title
+          ),
+          title: page.title,
+          tabIndex: selected ? 0 : -1,
+          className: slot("button", "dwt-page-tab"),
+          onClick: () => onSelect(page.key),
+          onKeyDown: (event) => onKeyDown(event, index),
+          children: [
+            /* @__PURE__ */ jsxRuntime.jsx("span", { className: "dwt-page-tab-title", children: page.title }),
+            /* @__PURE__ */ jsxRuntime.jsx("span", { className: "dwt-page-dot", "aria-hidden": "true" })
+          ]
+        },
+        page.key
+      );
+    }) }),
+    /* @__PURE__ */ jsxRuntime.jsx(
+      "button",
+      {
+        type: "button",
+        className: slot(
+          "button",
+          "dwt-button",
+          "dwt-icon-button",
+          "dwt-page-nav"
+        ),
+        "aria-label": labels.nextPageButton,
+        disabled: activeIndex === pages.length - 1,
+        onClick: () => onSelect(pages[activeIndex + 1].key),
+        children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u203A" })
+      }
+    ),
+    /* @__PURE__ */ jsxRuntime.jsx("span", { className: "dwt-visually-hidden", "aria-live": "polite", children: announcement })
+  ] });
+}
+function PageRenameForm({
+  initial,
+  onSubmit,
+  onCancel
+}) {
+  const slot = useSlotClassName();
+  const { labels } = useWidgetSettings();
+  const [title, setTitle] = react.useState(initial);
+  const [error, setError] = react.useState(void 0);
+  const inputRef = react.useRef(null);
+  react.useEffect(() => {
+    inputRef.current?.focus();
+    inputRef.current?.select();
+  }, []);
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "form",
+    {
+      className: "dwt-page-rename",
+      onSubmit: (event) => {
+        event.preventDefault();
+        setError(onSubmit(title));
+      },
+      onKeyDown: (event) => {
+        if (event.key === "Escape") {
+          event.stopPropagation();
+          onCancel();
+        }
+      },
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "input",
+          {
+            ref: inputRef,
+            type: "text",
+            className: "dwt-page-title-input",
+            "aria-label": labels.pageTitle,
+            "aria-invalid": error !== void 0,
+            maxLength: MAX_PAGE_TITLE_LENGTH,
+            value: title,
+            onChange: (event) => setTitle(event.target.value)
+          }
+        ),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "button",
+          {
+            type: "submit",
+            className: slot("button", "dwt-button", "dwt-icon-button"),
+            "aria-label": labels.savePageTitle,
+            title: labels.savePageTitle,
+            children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2713" })
+          }
+        ),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "button",
+          {
+            type: "button",
+            className: slot("button", "dwt-button", "dwt-icon-button"),
+            "aria-label": labels.cancelPageTitle,
+            title: labels.cancelPageTitle,
+            onClick: onCancel,
+            children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2715" })
+          }
+        ),
+        error !== void 0 && /* @__PURE__ */ jsxRuntime.jsx("span", { role: "alert", className: "dwt-page-error", children: error })
+      ]
+    }
+  );
+}
 function withoutLock(definition) {
   if (definition.locked === void 0) return definition;
   const copy = { ...definition };
@@ -2222,6 +3084,11 @@ function DashboardInner({
   onEditingChange,
   defaultLayout,
   toolbar = true,
+  activePage: activePageProp,
+  defaultActivePage,
+  onActivePageChange,
+  maxRows,
+  maxPages,
   onRetry,
   loadDetail,
   onOpenDetail,
@@ -2237,8 +3104,19 @@ function DashboardInner({
   const byKey = new Map(
     widgets.map((w) => [w.definition.key, w])
   );
-  const visible = visibleWidgets(definitions, layout);
-  const hidden = hiddenWidgets(definitions, layout);
+  const pages = pageList(layout);
+  const paged = pages.length >= 2;
+  const [activeState, setActiveState] = react.useState(
+    defaultActivePage
+  );
+  const requested = activePageProp ?? activeState;
+  const activePage = pages.find((page) => page.key === requested) ?? pages[0];
+  const activeKey = activePage.key;
+  const pageDefs = assignPages(definitions, layout).get(activeKey) ?? [];
+  const view = pageLayout(layout, activeKey) ?? layout;
+  const roomOptions = maxRows === void 0 ? {} : { maxRows };
+  const visible = visibleWidgets(pageDefs, view);
+  const hidden = hiddenWidgets(pageDefs, view);
   const editable = onLayoutChange !== void 0;
   const toggleMode = editMode === "toggle";
   const [editingState, setEditingState] = react.useState(defaultEditing);
@@ -2257,10 +3135,16 @@ function DashboardInner({
   );
   const pending = editing ? confirming : void 0;
   const [announcement, setAnnouncement] = react.useState("");
+  const [pageAnnouncement, setPageAnnouncement] = react.useState("");
+  const [pageError, setPageError] = react.useState(void 0);
+  const [pageEditor, setPageEditor] = react.useState(void 0);
+  const editorMode = pageEditor?.key === activeKey ? pageEditor.mode : void 0;
+  const instanceId = react.useId();
+  const panelId = `${instanceId}-panel`;
   const toggleRef = react.useRef(null);
   const resetRef = react.useRef(null);
-  const minimized = editable ? visible.filter((definition) => isMinimized(layout, definition.key)) : [];
-  const shown = editable ? visible.filter((definition) => !isMinimized(layout, definition.key)) : visible;
+  const minimized = editable ? visible.filter((definition) => isMinimized(view, definition.key)) : [];
+  const shown = editable ? visible.filter((definition) => !isMinimized(view, definition.key)) : visible;
   const [detailKey, setDetailKey] = react.useState(void 0);
   const gridRef = react.useRef(null);
   const twelve = usesWidthColumns(shown);
@@ -2272,6 +3156,110 @@ function DashboardInner({
   function change(next) {
     if (next !== layout) onLayoutChange?.(next);
   }
+  function changePage(next) {
+    setPageError(void 0);
+    change(withPageLayout(layout, activeKey, next));
+  }
+  function selectPage(pageKey) {
+    const index = pages.findIndex((page) => page.key === pageKey);
+    if (index === -1) return;
+    if (activePageProp === void 0) setActiveState(pageKey);
+    onActivePageChange?.(pageKey);
+    setPageError(void 0);
+    setPageEditor(void 0);
+    setPageAnnouncement(
+      labels.pageTabName(
+        index + 1,
+        pages.length,
+        pages[index].title
+      )
+    );
+  }
+  function addPageAction() {
+    const added = addPage(layout);
+    if (!added.ok) {
+      setPageError(added.error);
+      return;
+    }
+    change(added.value);
+    const created = added.value.pages?.at(-1);
+    if (created !== void 0) {
+      if (activePageProp === void 0) setActiveState(created.key);
+      onActivePageChange?.(created.key);
+      setPageError(void 0);
+      setPageEditor({ mode: "rename", key: created.key });
+    }
+  }
+  function renamePageAction(title) {
+    const renamed = renamePage(layout, activeKey, title);
+    if (!renamed.ok) return renamed.error;
+    change(renamed.value);
+    setPageEditor(void 0);
+    return void 0;
+  }
+  function deletePageAction() {
+    const index = pages.findIndex((page) => page.key === activeKey);
+    const removed = removePage(definitions, layout, activeKey, roomOptions);
+    setPageEditor(void 0);
+    if (!removed.ok) {
+      setPageError(removed.error);
+      return;
+    }
+    const neighbor = pages[index > 0 ? index - 1 : 1];
+    change(removed.value);
+    if (neighbor !== void 0) selectPage(neighbor.key);
+  }
+  function moveWidgetAction(widgetKey, targetKey) {
+    let target = targetKey;
+    let base = layout;
+    if (targetKey === NEW_PAGE_VALUE) {
+      const added = addPage(layout);
+      if (!added.ok) {
+        setPageError(added.error);
+        return;
+      }
+      base = added.value;
+      target = (added.value.pages?.at(-1)).key;
+    }
+    const moved = moveWidgetToPage(
+      definitions,
+      base,
+      widgetKey,
+      target,
+      roomOptions
+    );
+    if (!moved.ok) {
+      setPageError(moved.error);
+      return;
+    }
+    setPageError(void 0);
+    change(moved.value);
+    const destination = moved.value.pages?.find(
+      (page) => page.key === target
+    );
+    setPageAnnouncement(
+      labels.movedToPage(
+        byKey.get(widgetKey)?.definition.title ?? widgetKey,
+        destination?.title ?? target
+      )
+    );
+  }
+  function showAction(widgetKey) {
+    const next = withPageLayout(
+      layout,
+      activeKey,
+      showWidget(view, widgetKey)
+    );
+    if (hasPages(next)) {
+      const room = pageRoom(definitions, next, activeKey, roomOptions);
+      if (room !== void 0 && room.rowsUsed > room.maxRows) {
+        setPageError(labels.pageFull(activePage.title, room.maxRows));
+        return;
+      }
+    }
+    setPageError(void 0);
+    change(next);
+  }
   function setEditing(next) {
     if (editingProp === void 0) setEditingState(next);
     onEditingChange?.(next);
@@ -2349,176 +3337,312 @@ function DashboardInner({
             ]
           }
         ),
-        controlsShown && hidden.length > 0 && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: slot("hiddenBar", "dwt-hidden-bar"), children: [
-          /* @__PURE__ */ jsxRuntime.jsx("span", { className: "dwt-hidden-label", children: labels.hiddenWidgets }),
-          hidden.map((definition) => /* @__PURE__ */ jsxRuntime.jsxs(
-            "button",
-            {
-              type: "button",
-              className: slot("button", "dwt-button", "dwt-show-button"),
-              "aria-label": labels.show(definition.title),
-              onClick: () => change(showWidget(layout, definition.key)),
-              children: [
-                /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "+ " }),
-                definition.title
-              ]
-            },
-            definition.key
-          ))
-        ] }),
-        minimized.length > 0 && /* @__PURE__ */ jsxRuntime.jsxs(
+        paged && /* @__PURE__ */ jsxRuntime.jsx(
+          PageTabs,
+          {
+            pages,
+            activeKey,
+            idPrefix: instanceId,
+            panelId,
+            announcement: pageAnnouncement,
+            onSelect: selectPage
+          }
+        ),
+        controlsShown && /* @__PURE__ */ jsxRuntime.jsxs(
           "div",
           {
-            className: slot("hiddenBar", "dwt-hidden-bar", "dwt-minimized-bar"),
+            role: "group",
+            "aria-label": labels.managePages,
+            className: "dwt-page-manage",
             children: [
-              /* @__PURE__ */ jsxRuntime.jsx("span", { className: "dwt-hidden-label", children: labels.minimizedWidgets }),
-              minimized.map((definition) => /* @__PURE__ */ jsxRuntime.jsxs(
+              /* @__PURE__ */ jsxRuntime.jsx(
                 "button",
                 {
                   type: "button",
-                  className: slot("button", "dwt-button", "dwt-show-button"),
-                  "aria-label": labels.expand(definition.title),
-                  onClick: () => change(toggleMinimized(layout, definition.key)),
-                  children: [
-                    /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u25B8 " }),
-                    definition.title
-                  ]
+                  className: slot("button", "dwt-button"),
+                  disabled: maxPages !== void 0 && pages.length >= maxPages,
+                  onClick: addPageAction,
+                  children: labels.addPage
+                }
+              ),
+              paged && editorMode === "rename" && /* @__PURE__ */ jsxRuntime.jsx(
+                PageRenameForm,
+                {
+                  initial: activePage.title,
+                  onSubmit: renamePageAction,
+                  onCancel: () => setPageEditor(void 0)
                 },
-                definition.key
-              ))
+                activeKey
+              ),
+              paged && editorMode !== "rename" && /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+                /* @__PURE__ */ jsxRuntime.jsx(
+                  "button",
+                  {
+                    type: "button",
+                    className: slot("button", "dwt-button", "dwt-icon-button"),
+                    "aria-label": labels.renamePage(activePage.title),
+                    title: labels.renamePage(activePage.title),
+                    onClick: () => setPageEditor({ mode: "rename", key: activeKey }),
+                    children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u270E" })
+                  }
+                ),
+                /* @__PURE__ */ jsxRuntime.jsx(
+                  "button",
+                  {
+                    type: "button",
+                    className: slot("button", "dwt-button", "dwt-icon-button"),
+                    "aria-label": labels.movePageLeft(activePage.title),
+                    title: labels.movePageLeft(activePage.title),
+                    disabled: pages[0]?.key === activeKey,
+                    onClick: () => change(movePage(layout, activeKey, -1)),
+                    children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2190" })
+                  }
+                ),
+                /* @__PURE__ */ jsxRuntime.jsx(
+                  "button",
+                  {
+                    type: "button",
+                    className: slot("button", "dwt-button", "dwt-icon-button"),
+                    "aria-label": labels.movePageRight(activePage.title),
+                    title: labels.movePageRight(activePage.title),
+                    disabled: pages.at(-1)?.key === activeKey,
+                    onClick: () => change(movePage(layout, activeKey, 1)),
+                    children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2192" })
+                  }
+                ),
+                /* @__PURE__ */ jsxRuntime.jsx(
+                  "button",
+                  {
+                    type: "button",
+                    className: slot("button", "dwt-button", "dwt-icon-button"),
+                    "aria-label": labels.deletePage(activePage.title),
+                    title: labels.deletePage(activePage.title),
+                    onClick: () => setPageEditor({ mode: "delete", key: activeKey }),
+                    children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\xD7" })
+                  }
+                )
+              ] }),
+              paged && editorMode === "delete" && /* @__PURE__ */ jsxRuntime.jsx(
+                InlineConfirm,
+                {
+                  message: labels.confirmDeletePage(activePage.title),
+                  onAnswer: (yes) => yes ? deletePageAction() : setPageEditor(void 0)
+                }
+              ),
+              pageError !== void 0 && /* @__PURE__ */ jsxRuntime.jsx("span", { role: "alert", className: "dwt-page-error", children: pageError })
             ]
           }
         ),
-        visible.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("p", { className: slot("empty", "dwt-empty", "dwt-dashboard-empty"), children: definitions.length === 0 ? labels.noWidgets : labels.allHidden }) : shown.length === 0 ? null : /* @__PURE__ */ jsxRuntime.jsx(
-          "div",
+        /* @__PURE__ */ jsxRuntime.jsxs(
+          PagePanel,
           {
-            ref: gridRef,
-            className: slot("grid", "dwt-grid", twelve && "dwt-grid--twelve"),
-            children: shown.map((definition, index) => {
-              const widget = byKey.get(
-                definition.key
-              );
-              if (widget === void 0) return null;
-              const key = definition.key;
-              const title = definition.title;
-              const lock = resolveWidgetLock(definition);
-              const ownLock = resolveWidgetLock(
-                widget.definition
-              );
-              const isLocked = ownLock.move || ownLock.hide || ownLock.minimize;
-              const lockLabel = overrideLocks ? labels.lockedForViewers(title) : labels.locked(title);
-              const canMoveEarlier = !lock.move && moveWidgetBy(definitions, layout, key, -1) !== layout;
-              const canMoveLater = !lock.move && moveWidgetBy(definitions, layout, key, 1) !== layout;
-              const actions = controlsShown ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-                isLocked && /* @__PURE__ */ jsxRuntime.jsx(
-                  "span",
+            paged,
+            id: panelId,
+            labelledBy: `${instanceId}-tab-${pages.findIndex((p) => p.key === activeKey)}`,
+            children: [
+              controlsShown && hidden.length > 0 && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: slot("hiddenBar", "dwt-hidden-bar"), children: [
+                /* @__PURE__ */ jsxRuntime.jsx("span", { className: "dwt-hidden-label", children: labels.hiddenWidgets }),
+                hidden.map((definition) => /* @__PURE__ */ jsxRuntime.jsxs(
+                  "button",
                   {
-                    role: "img",
-                    className: "dwt-lock",
-                    "aria-label": lockLabel,
-                    title: lockLabel,
-                    children: /* @__PURE__ */ jsxRuntime.jsxs(
-                      "svg",
+                    type: "button",
+                    className: slot("button", "dwt-button", "dwt-show-button"),
+                    "aria-label": labels.show(definition.title),
+                    onClick: () => showAction(definition.key),
+                    children: [
+                      /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "+ " }),
+                      definition.title
+                    ]
+                  },
+                  definition.key
+                ))
+              ] }),
+              minimized.length > 0 && /* @__PURE__ */ jsxRuntime.jsxs(
+                "div",
+                {
+                  className: slot("hiddenBar", "dwt-hidden-bar", "dwt-minimized-bar"),
+                  children: [
+                    /* @__PURE__ */ jsxRuntime.jsx("span", { className: "dwt-hidden-label", children: labels.minimizedWidgets }),
+                    minimized.map((definition) => /* @__PURE__ */ jsxRuntime.jsxs(
+                      "button",
                       {
-                        viewBox: "0 0 16 16",
-                        width: "14",
-                        height: "14",
-                        "aria-hidden": "true",
-                        focusable: "false",
+                        type: "button",
+                        className: slot("button", "dwt-button", "dwt-show-button"),
+                        "aria-label": labels.expand(definition.title),
+                        onClick: () => changePage(toggleMinimized(view, definition.key)),
                         children: [
-                          /* @__PURE__ */ jsxRuntime.jsx(
-                            "rect",
-                            {
-                              x: "3",
-                              y: "7",
-                              width: "10",
-                              height: "7",
-                              rx: "1.5",
-                              fill: "currentColor"
-                            }
-                          ),
-                          /* @__PURE__ */ jsxRuntime.jsx(
-                            "path",
+                          /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u25B8 " }),
+                          definition.title
+                        ]
+                      },
+                      definition.key
+                    ))
+                  ]
+                }
+              ),
+              visible.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("p", { className: slot("empty", "dwt-empty", "dwt-dashboard-empty"), children: paged && pageDefs.length === 0 ? labels.emptyPage : definitions.length === 0 ? labels.noWidgets : labels.allHidden }) : shown.length === 0 ? null : /* @__PURE__ */ jsxRuntime.jsx(
+                "div",
+                {
+                  ref: gridRef,
+                  className: slot("grid", "dwt-grid", twelve && "dwt-grid--twelve"),
+                  children: shown.map((definition, index) => {
+                    const widget = byKey.get(
+                      definition.key
+                    );
+                    if (widget === void 0) return null;
+                    const key = definition.key;
+                    const title = definition.title;
+                    const lock = resolveWidgetLock(definition);
+                    const ownLock = resolveWidgetLock(
+                      widget.definition
+                    );
+                    const isLocked = ownLock.move || ownLock.hide || ownLock.minimize;
+                    const lockLabel = overrideLocks ? labels.lockedForViewers(title) : labels.locked(title);
+                    const canMoveEarlier = !lock.move && moveWidgetBy(pageDefs, view, key, -1) !== view;
+                    const canMoveLater = !lock.move && moveWidgetBy(pageDefs, view, key, 1) !== view;
+                    const actions = controlsShown ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+                      isLocked && /* @__PURE__ */ jsxRuntime.jsx(
+                        "span",
+                        {
+                          role: "img",
+                          className: "dwt-lock",
+                          "aria-label": lockLabel,
+                          title: lockLabel,
+                          children: /* @__PURE__ */ jsxRuntime.jsxs(
+                            "svg",
                             {
-                              d: "M5.5 7V5a2.5 2.5 0 0 1 5 0v2",
-                              fill: "none",
-                              stroke: "currentColor",
-                              strokeWidth: "1.4"
+                              viewBox: "0 0 16 16",
+                              width: "14",
+                              height: "14",
+                              "aria-hidden": "true",
+                              focusable: "false",
+                              children: [
+                                /* @__PURE__ */ jsxRuntime.jsx(
+                                  "rect",
+                                  {
+                                    x: "3",
+                                    y: "7",
+                                    width: "10",
+                                    height: "7",
+                                    rx: "1.5",
+                                    fill: "currentColor"
+                                  }
+                                ),
+                                /* @__PURE__ */ jsxRuntime.jsx(
+                                  "path",
+                                  {
+                                    d: "M5.5 7V5a2.5 2.5 0 0 1 5 0v2",
+                                    fill: "none",
+                                    stroke: "currentColor",
+                                    strokeWidth: "1.4"
+                                  }
+                                )
+                              ]
                             }
                           )
-                        ]
-                      }
-                    )
-                  }
-                ),
-                !lock.move && /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-                  /* @__PURE__ */ jsxRuntime.jsx(
-                    "button",
-                    {
-                      type: "button",
-                      className: slot(
-                        "button",
-                        "dwt-button",
-                        "dwt-icon-button"
+                        }
                       ),
-                      "aria-label": labels.moveEarlier(title),
-                      title: labels.moveEarlier(title),
-                      disabled: index === 0 || !canMoveEarlier,
-                      onClick: () => change(moveWidgetBy(definitions, layout, key, -1)),
-                      children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2191" })
-                    }
-                  ),
-                  /* @__PURE__ */ jsxRuntime.jsx(
-                    "button",
-                    {
-                      type: "button",
-                      className: slot(
+                      !lock.move && /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+                        /* @__PURE__ */ jsxRuntime.jsx(
+                          "button",
+                          {
+                            type: "button",
+                            className: slot(
+                              "button",
+                              "dwt-button",
+                              "dwt-icon-button"
+                            ),
+                            "aria-label": labels.moveEarlier(title),
+                            title: labels.moveEarlier(title),
+                            disabled: index === 0 || !canMoveEarlier,
+                            onClick: () => changePage(moveWidgetBy(pageDefs, view, key, -1)),
+                            children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2191" })
+                          }
+                        ),
+                        /* @__PURE__ */ jsxRuntime.jsx(
+                          "button",
+                          {
+                            type: "button",
+                            className: slot(
+                              "button",
+                              "dwt-button",
+                              "dwt-icon-button"
+                            ),
+                            "aria-label": labels.moveLater(title),
+                            title: labels.moveLater(title),
+                            disabled: index === shown.length - 1 || !canMoveLater,
+                            onClick: () => changePage(moveWidgetBy(pageDefs, view, key, 1)),
+                            children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2193" })
+                          }
+                        ),
+                        paged && /* @__PURE__ */ jsxRuntime.jsxs(
+                          "select",
+                          {
+                            className: "dwt-move-select",
+                            "aria-label": labels.moveToPage(title),
+                            value: "",
+                            onChange: (event) => {
+                              if (event.target.value !== "") {
+                                moveWidgetAction(key, event.target.value);
+                              }
+                            },
+                            children: [
+                              /* @__PURE__ */ jsxRuntime.jsx("option", { value: "", children: labels.moveToPagePlaceholder }),
+                              pages.filter((page) => page.key !== activeKey).map((page) => /* @__PURE__ */ jsxRuntime.jsx("option", { value: page.key, children: labels.moveToPageOption(
+                                page.title,
+                                pageRoom(
+                                  definitions,
+                                  layout,
+                                  page.key,
+                                  roomOptions
+                                )?.rowsFree ?? 0
+                              ) }, page.key)),
+                              (maxPages === void 0 || pages.length < maxPages) && /* @__PURE__ */ jsxRuntime.jsx("option", { value: NEW_PAGE_VALUE, children: labels.newPageOption })
+                            ]
+                          }
+                        )
+                      ] }),
+                      !lock.hide && /* @__PURE__ */ jsxRuntime.jsx(
                         "button",
-                        "dwt-button",
-                        "dwt-icon-button"
-                      ),
-                      "aria-label": labels.moveLater(title),
-                      title: labels.moveLater(title),
-                      disabled: index === shown.length - 1 || !canMoveLater,
-                      onClick: () => change(moveWidgetBy(definitions, layout, key, 1)),
-                      children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2193" })
-                    }
-                  )
-                ] }),
-                !lock.hide && /* @__PURE__ */ jsxRuntime.jsx(
-                  "button",
-                  {
-                    type: "button",
-                    className: slot("button", "dwt-button", "dwt-icon-button"),
-                    "aria-label": labels.hide(title),
-                    title: labels.hide(title),
-                    onClick: () => change(hideWidget(layout, key)),
-                    children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\xD7" })
-                  }
-                )
-              ] }) : void 0;
-              const viewable = resolveDetailOptions(definition) !== void 0 && (onOpenDetail !== void 0 || loadDetail !== void 0 || widget.status === "ok" && deriveDetailData(widget.data) !== void 0);
-              return /* @__PURE__ */ jsxRuntime.jsx(
-                ResolvedWidgetCard,
-                {
-                  widget,
-                  ...viewable ? {
-                    onView: () => onOpenDetail === void 0 ? setDetailKey(key) : onOpenDetail(key)
-                  } : {},
-                  ...spanProps(spans, key),
-                  ...widthProps(twelve, definition),
-                  minimized: isMinimized(layout, key),
-                  editing: toggleMode && controlsShown,
-                  ...actions === void 0 ? {} : { actions },
-                  ...editable && !lock.minimize ? {
-                    onToggleMinimized: () => change(toggleMinimized(layout, key))
-                  } : {},
-                  ...headingLevel === void 0 ? {} : { headingLevel },
-                  ...onRetry === void 0 || widget.status !== "error" ? {} : { onRetry: () => onRetry(key) }
-                },
-                key
-              );
-            })
+                        {
+                          type: "button",
+                          className: slot(
+                            "button",
+                            "dwt-button",
+                            "dwt-icon-button"
+                          ),
+                          "aria-label": labels.hide(title),
+                          title: labels.hide(title),
+                          onClick: () => changePage(hideWidget(view, key)),
+                          children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\xD7" })
+                        }
+                      )
+                    ] }) : void 0;
+                    const viewable = resolveDetailOptions(definition) !== void 0 && (onOpenDetail !== void 0 || loadDetail !== void 0 || widget.status === "ok" && deriveDetailData(widget.data) !== void 0);
+                    return /* @__PURE__ */ jsxRuntime.jsx(
+                      ResolvedWidgetCard,
+                      {
+                        widget,
+                        ...viewable ? {
+                          onView: () => onOpenDetail === void 0 ? setDetailKey(key) : onOpenDetail(key)
+                        } : {},
+                        ...spanProps(spans, key),
+                        ...widthProps(twelve, definition),
+                        minimized: isMinimized(view, key),
+                        editing: toggleMode && controlsShown,
+                        ...actions === void 0 ? {} : { actions },
+                        ...editable && !lock.minimize ? {
+                          onToggleMinimized: () => changePage(toggleMinimized(view, key))
+                        } : {},
+                        ...headingLevel === void 0 ? {} : { headingLevel },
+                        ...onRetry === void 0 || widget.status !== "error" ? {} : { onRetry: () => onRetry(key) }
+                      },
+                      key
+                    );
+                  })
+                }
+              )
+            ]
           }
         ),
         detailKey !== void 0 && byKey.get(detailKey) !== void 0 && /* @__PURE__ */ jsxRuntime.jsx(
@@ -2555,6 +3679,196 @@ function Dashboard({
     }
   );
 }
+function useStoredLayout(options) {
+  const {
+    persistence,
+    scope,
+    definitions,
+    defaultLayout,
+    saveDelayMs = 500,
+    initialLayout,
+    normalizeOptions
+  } = options;
+  const scopeKey = persistence.keyFor(scope);
+  const [layout, setLayoutState] = react.useState(
+    initialLayout ?? defaultLayout
+  );
+  const [backup, setBackupState] = react.useState(null);
+  const [status, setStatus] = react.useState("loading");
+  const [error, setError] = react.useState(null);
+  const [conflict, setConflict] = react.useState(null);
+  const [remoteLayout, setRemoteLayout] = react.useState(
+    null
+  );
+  const latest = react.useRef(layout);
+  const scopeRef = react.useRef(scope);
+  scopeRef.current = scope;
+  const normalizeRef = react.useRef(normalizeOptions);
+  normalizeRef.current = normalizeOptions;
+  const timer = react.useRef(void 0);
+  const dirty = react.useRef(false);
+  const apply = react.useCallback((next) => {
+    latest.current = next;
+    setLayoutState(next);
+  }, []);
+  const finishSave = react.useCallback(
+    (result, mine) => {
+      if (!result.ok) {
+        setError(result.error);
+        setStatus("error");
+        return;
+      }
+      const saved = result.value;
+      if (saved.outcome === "saved") {
+        dirty.current = latest.current !== mine;
+        setError(null);
+        setStatus(dirty.current ? "saving" : "ready");
+        return;
+      }
+      if (saved.outcome === "kept-theirs") {
+        dirty.current = false;
+        apply(saved.layout);
+        setError(null);
+        setStatus("ready");
+        return;
+      }
+      setConflict({ mine, theirs: saved.layout });
+      setStatus("conflict");
+    },
+    [apply]
+  );
+  const flush = react.useCallback(() => {
+    if (timer.current !== void 0) {
+      clearTimeout(timer.current);
+      timer.current = void 0;
+    }
+    if (!dirty.current) return;
+    const mine = latest.current;
+    setStatus("saving");
+    void persistence.save(scopeRef.current, mine).then((result) => finishSave(result, mine));
+  }, [persistence, finishSave]);
+  react.useEffect(() => {
+    let current = true;
+    setStatus("loading");
+    setConflict(null);
+    setRemoteLayout(null);
+    void persistence.load(scopeRef.current, definitions, normalizeRef.current).then((result) => {
+      if (!current) return;
+      if (!result.ok) {
+        setError(result.error);
+        setStatus("error");
+        return;
+      }
+      setError(null);
+      if (!dirty.current && result.value.layout !== null) {
+        apply(result.value.layout);
+      }
+      setStatus(dirty.current ? "saving" : "ready");
+    });
+    void persistence.loadBackup(scopeRef.current).then((result) => {
+      if (current && result.ok) setBackupState(result.value);
+    });
+    return () => {
+      current = false;
+    };
+  }, [persistence, scopeKey, definitions, apply]);
+  react.useEffect(() => {
+    return persistence.watch(
+      scopeRef.current,
+      definitions,
+      (loaded) => {
+        if (loaded.layout === null) return;
+        if (dirty.current) {
+          setRemoteLayout(loaded.layout);
+          return;
+        }
+        apply(loaded.layout);
+      },
+      normalizeRef.current
+    );
+  }, [persistence, scopeKey, definitions, apply]);
+  react.useEffect(() => {
+    const onHide = () => {
+      if (typeof document === "undefined" || document.visibilityState !== "hidden") {
+        return;
+      }
+      flush();
+    };
+    if (typeof window !== "undefined") {
+      window.addEventListener("pagehide", flush);
+      document.addEventListener("visibilitychange", onHide);
+    }
+    return () => {
+      if (typeof window !== "undefined") {
+        window.removeEventListener("pagehide", flush);
+        document.removeEventListener("visibilitychange", onHide);
+      }
+      flush();
+    };
+  }, [flush]);
+  const setLayout = react.useCallback(
+    (next) => {
+      apply(next);
+      dirty.current = true;
+      if (timer.current !== void 0) clearTimeout(timer.current);
+      timer.current = setTimeout(flush, Math.max(0, saveDelayMs));
+    },
+    [apply, flush, saveDelayMs]
+  );
+  const setBackup = react.useCallback(
+    (next) => {
+      setBackupState(next);
+      if (next === null) return;
+      void persistence.saveBackup(scopeRef.current, next).then((result) => {
+        if (!result.ok) setError(result.error);
+      });
+    },
+    [persistence]
+  );
+  const resolveConflict = react.useCallback(
+    (choice) => {
+      const pending = conflict;
+      if (pending === null) return;
+      setConflict(null);
+      if (choice === "theirs") {
+        dirty.current = false;
+        apply(pending.theirs);
+        setStatus("ready");
+        return;
+      }
+      setStatus("saving");
+      void persistence.save(scopeRef.current, pending.mine, { force: true }).then((result) => finishSave(result, pending.mine));
+    },
+    [conflict, persistence, apply, finishSave]
+  );
+  const resolveRemote = react.useCallback(
+    (choice) => {
+      const remote = remoteLayout;
+      setRemoteLayout(null);
+      if (choice === "use" && remote !== null) {
+        if (timer.current !== void 0) {
+          clearTimeout(timer.current);
+          timer.current = void 0;
+        }
+        dirty.current = false;
+        apply(remote);
+      }
+    },
+    [remoteLayout, apply]
+  );
+  return {
+    layout,
+    setLayout,
+    backup,
+    setBackup,
+    status,
+    error,
+    conflict,
+    resolveConflict,
+    remoteLayout,
+    resolveRemote
+  };
+}
 
 // src/core/payload.ts
 var WIDGET_KINDS = [
@@ -2898,12 +4212,33 @@ function failedWidget(definition, error) {
 function loadingWidgets(definitions) {
   return definitions.map((definition) => ({ definition, status: "loading" }));
 }
-function cacheKeyFor(definition, options) {
-  return options.cacheKey === void 0 ? definition.key : options.cacheKey(definition);
+function cacheKeyFor(definition, options, values) {
+  const base = options.cacheKey === void 0 ? definition.key : options.cacheKey(definition);
+  return values === void 0 ? base : `${base}${optionsCacheSuffix(definition, values, options)}`;
+}
+function optionValuesFor(definition, options) {
+  return resolveOptionValues(
+    definition,
+    options.optionValues?.[definition.key],
+    options
+  );
+}
+function finalizeWidget(widget, values) {
+  if (Object.keys(values).length === 0) return widget;
+  if (widget.status === "ok") {
+    const data = applyClientOptions(
+      widget.definition,
+      widget.data,
+      values
+    );
+    return { ...widget, data, options: values };
+  }
+  return { ...widget, options: values };
 }
 var LoadInterruption = class extends Error {
 };
-async function resolveWidget(definition, provider, context, options = {}) {
+async function resolveWidgetUnapplied(definition, provider, context, options = {}) {
+  const values = optionValuesFor(definition, options);
   const quotedKey = JSON.stringify(definition.key);
   if (provider === void 0) {
     return failedWidget(
@@ -2938,7 +4273,10 @@ async function resolveWidget(definition, provider, context, options = {}) {
     payload = await Promise.race([
       Promise.resolve().then(() => {
         if (controller.signal.aborted) throw new LoadInterruption();
-        return provider(context, definition, { signal: controller.signal });
+        return provider(context, definition, {
+          signal: controller.signal,
+          options: values
+        });
       }),
       interrupted
     ]);
@@ -2962,7 +4300,7 @@ async function resolveWidget(definition, provider, context, options = {}) {
   const storedAt = Date.now();
   if (options.cache !== void 0) {
     try {
-      await options.cache.set(cacheKeyFor(definition, options), {
+      await options.cache.set(cacheKeyFor(definition, options, values), {
         payload: resolved.data,
         storedAt
       });
@@ -2979,7 +4317,17 @@ function widgetsFor(definitions, roles) {
 
 // src/core/loader.ts
 function createWidgetLoader(options) {
-  const { definitions, providers, context, ...resolveOptions } = options;
+  const { definitions, providers, context, ...baseOptions } = options;
+  const chosen = new Map(
+    Object.entries(baseOptions.optionValues ?? {}).flatMap(
+      ([key, values]) => values === void 0 ? [] : [[key, values]]
+    )
+  );
+  const resolveOptions = baseOptions;
+  function currentOptions() {
+    return { ...resolveOptions, optionValues: Object.fromEntries(chosen) };
+  }
+  const unapplied = /* @__PURE__ */ new Map();
   const visible = widgetsFor(definitions, context.roles);
   let snapshot = loadingWidgets(visible);
   const listeners = /* @__PURE__ */ new Set();
@@ -3020,19 +4368,19 @@ function createWidgetLoader(options) {
     const controller = new AbortController();
     inFlight.set(key, controller);
     const isCurrent = () => !disposed && generations.get(key) === generation;
-    if (readCache && resolveOptions.cache !== void 0) {
+    const runOptions = currentOptions();
+    const values = optionValuesFor(definition, runOptions);
+    if (readCache && runOptions.cache !== void 0) {
       try {
-        const entry = await resolveOptions.cache.get(
-          cacheKeyFor(definition, resolveOptions)
+        const entry = await runOptions.cache.get(
+          cacheKeyFor(definition, runOptions, values)
         );
         if (entry !== void 0 && isCurrent()) {
-          const cached = resolvePayload(
-            definition,
-            entry.payload,
-            resolveOptions
-          );
+          const cached = resolvePayload(definition, entry.payload, runOptions);
           if (cached.status === "ok") {
-            replace(key, { ...cached, updatedAt: entry.storedAt, stale: true });
+            const stale = { ...cached, updatedAt: entry.storedAt, stale: true };
+            unapplied.set(key, stale);
+            replace(key, finalizeWidget(stale, values));
           }
         }
       } catch {
@@ -3040,13 +4388,15 @@ function createWidgetLoader(options) {
     }
     if (!isCurrent()) return;
     const provider = Object.prototype.hasOwnProperty.call(providers, key) ? providers[key] : void 0;
-    const result = await resolveWidget(definition, provider, context, {
-      ...resolveOptions,
+    const result = await resolveWidgetUnapplied(definition, provider, context, {
+      ...runOptions,
       signal: controller.signal
     });
     if (!isCurrent()) return;
     inFlight.delete(key);
-    replace(key, result);
+    if (result.status === "ok") unapplied.set(key, result);
+    else unapplied.delete(key);
+    replace(key, finalizeWidget(result, values));
   }
   function start(definition, readCache) {
     started.add(definition.key);
@@ -3081,6 +4431,29 @@ function createWidgetLoader(options) {
       start(definition, false);
     }
   }
+  function setOptions(key, values) {
+    if (disposed) return;
+    const definition = definitionFor(key);
+    if (definition === void 0) return;
+    const before = optionValuesFor(definition, currentOptions());
+    chosen.set(key, { ...values });
+    const runOptions = currentOptions();
+    const after = optionValuesFor(definition, runOptions);
+    if (sameOptionValues(before, after) || !started.has(key)) return;
+    const kept = unapplied.get(key);
+    if (kept !== void 0 && optionsCacheSuffix(definition, before, runOptions) === optionsCacheSuffix(definition, after, runOptions)) {
+      replace(key, finalizeWidget(kept, after));
+      return;
+    }
+    const current = snapshot.find(
+      (widget) => widget.definition.key === key
+    );
+    if (current?.status === "ok") replace(key, { ...current, stale: true });
+    else if (current?.status === "error") {
+      replace(key, { definition, status: "loading" });
+    }
+    start(definition, true);
+  }
   function dispose() {
     disposed = true;
     abortAll(new Error("The widget loader was disposed."));
@@ -3098,6 +4471,7 @@ function createWidgetLoader(options) {
     load,
     loadAll,
     refresh,
+    setOptions,
     dispose
   };
 }
@@ -3112,7 +4486,8 @@ function useWidgets(definitions, providers, context, options = {}) {
     timeoutMs,
     signal,
     cache,
-    cacheKey
+    cacheKey,
+    optionValues
   } = options;
   const placeholders = react.useMemo(
     () => loadingWidgets(widgetsFor(definitions, context.roles)),
@@ -3122,6 +4497,8 @@ function useWidgets(definitions, providers, context, options = {}) {
   const [loader, setLoader] = react.useState(null);
   const loaderRef = react.useRef(null);
   const gridRef = react.useRef(null);
+  const optionValuesRef = react.useRef(optionValues);
+  optionValuesRef.current = optionValues;
   react.useEffect(() => {
     const created = createWidgetLoader({
       definitions,
@@ -3131,7 +4508,8 @@ function useWidgets(definitions, providers, context, options = {}) {
       ...timeoutMs === void 0 ? {} : { timeoutMs },
       ...signal === void 0 ? {} : { signal },
       ...cache === void 0 ? {} : { cache },
-      ...cacheKey === void 0 ? {} : { cacheKey }
+      ...cacheKey === void 0 ? {} : { cacheKey },
+      ...optionValuesRef.current === void 0 ? {} : { optionValues: optionValuesRef.current }
     });
     loaderRef.current = created;
     setWidgets(created.getSnapshot());
@@ -3177,8 +4555,21 @@ function useWidgets(definitions, providers, context, options = {}) {
       },
       { rootMargin }
     );
-    grid.querySelectorAll("[data-widget-key]").forEach((card) => observer.observe(card));
-    return () => observer.disconnect();
+    const observed = /* @__PURE__ */ new WeakSet();
+    const observeNewCards = () => {
+      grid.querySelectorAll("[data-widget-key]").forEach((card) => {
+        if (observed.has(card)) return;
+        observed.add(card);
+        observer.observe(card);
+      });
+    };
+    observeNewCards();
+    const mutations = typeof MutationObserver === "undefined" ? void 0 : new MutationObserver(observeNewCards);
+    mutations?.observe(grid, { childList: true, subtree: true });
+    return () => {
+      mutations?.disconnect();
+      observer.disconnect();
+    };
   }, [loader, loadWhen, rootMargin, cardKeys]);
   react.useEffect(() => {
     if (loader === null || !(refreshMs > 0)) return void 0;
@@ -3190,10 +4581,23 @@ function useWidgets(definitions, providers, context, options = {}) {
     }, refreshMs);
     return () => clearInterval(timer);
   }, [loader, refreshMs]);
+  const optionSignature = JSON.stringify(optionValues ?? {});
+  react.useEffect(() => {
+    if (loader === null) return;
+    for (const [key, chosen] of Object.entries(optionValuesRef.current ?? {})) {
+      if (chosen !== void 0) loader.setOptions(key, chosen);
+    }
+  }, [loader, optionSignature]);
+  const setOptions = react.useCallback(
+    (key, chosen) => {
+      loaderRef.current?.setOptions(key, chosen);
+    },
+    []
+  );
   const refresh = react.useCallback((key) => {
     loaderRef.current?.refresh(key);
   }, []);
-  return { widgets, refresh, gridRef };
+  return { widgets, refresh, setOptions, gridRef };
 }
 
 exports.AlertListWidget = AlertListWidget;
@@ -3221,6 +4625,7 @@ exports.describeChart = describeChart;
 exports.joinClassNames = joinClassNames;
 exports.seriesColor = seriesColor;
 exports.useDetailData = useDetailData;
+exports.useStoredLayout = useStoredLayout;
 exports.useWidgetSettings = useWidgetSettings;
 exports.useWidgets = useWidgets;
 exports.widgetTitle = widgetTitle;