@richardmcquiston01/dashboard-widgets-toolkit 0.10.0 → 0.11.1

package/dist/react.js

@@ -1,4 +1,4 @@
-import { createContext, useContext, useId, useState, useRef, useEffect, useMemo, useCallback } from 'react';
+import { createContext, useContext, useId, useState, useRef, useEffect, useCallback, useMemo } from 'react';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
 
 // src/react/card.tsx
@@ -470,6 +470,265 @@ function placeAndFillRows(items, columns, spanOf) {
   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
 function niceStep(value) {
   if (!(value > 0) || !Number.isFinite(value)) return 1;
@@ -1236,7 +1495,8 @@ function GaugeWidget({
 }
 function TableWidget({
   data,
-  controls
+  controls,
+  initialSort
 }) {
   if (controls === void 0) {
     return /* @__PURE__ */ jsxs("div", { className: "dwt-table-wrap", children: [
@@ -1244,7 +1504,14 @@ function TableWidget({
       data.footer !== void 0 && /* @__PURE__ */ jsx("p", { className: "dwt-note", children: data.footer })
     ] });
   }
-  return /* @__PURE__ */ jsx(InteractiveTable, { data, controls });
+  return /* @__PURE__ */ jsx(
+    InteractiveTable,
+    {
+      data,
+      controls,
+      initialSort
+    }
+  );
 }
 function TableView({
   data,
@@ -1297,13 +1564,20 @@ function nextTableSort(current, column) {
 }
 function InteractiveTable({
   data,
-  controls
+  controls,
+  initialSort
 }) {
   const slot = useSlotClassName();
   const { labels, locale } = useWidgetSettings();
   const searchId = useId();
   const [search, setSearch] = useState("");
-  const [sort, setSort] = useState(void 0);
+  const [sort, setSort] = useState(initialSort);
+  const seed = initialSort === void 0 ? "" : `${initialSort.column}:${initialSort.direction}`;
+  const [seededWith, setSeededWith] = useState(seed);
+  if (seededWith !== seed) {
+    setSeededWith(seed);
+    setSort(initialSort);
+  }
   const localeTag = typeof locale === "string" ? locale : locale?.[0];
   const query = {
     page: 1,
@@ -1405,7 +1679,8 @@ function AlertListWidget({
 }
 function WidgetContent({
   data,
-  tableControls
+  tableControls,
+  initialSort
 }) {
   switch (data.kind) {
     case "TEXT":
@@ -1415,7 +1690,14 @@ function WidgetContent({
     case "GAUGE":
       return /* @__PURE__ */ jsx(GaugeWidget, { data });
     case "TABLE":
-      return /* @__PURE__ */ jsx(TableWidget, { data, controls: tableControls });
+      return /* @__PURE__ */ jsx(
+        TableWidget,
+        {
+          data,
+          controls: tableControls,
+          initialSort
+        }
+      );
     case "BAR_LIST":
       return /* @__PURE__ */ jsx(BarListWidget, { data });
     case "ALERT_LIST":
@@ -1612,7 +1894,8 @@ function ResolvedWidgetCard({
         WidgetContent,
         {
           data: widget.data,
-          tableControls: resolveTableControls(definition)
+          tableControls: resolveTableControls(definition),
+          initialSort: sortFromOptions(definition, widget.options)
         }
       ) : null
     }
@@ -2374,7 +2657,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] = useState({ status: "loading" });
   const [attempt, setAttempt] = useState(0);
   useEffect(() => {
@@ -2384,6 +2668,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) => {
@@ -2411,7 +2696,7 @@ 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__";
@@ -2527,7 +2812,14 @@ function DetailHost({
   const { definition } = widget;
   const options = resolveDetailOptions(definition);
   const pageSize = options?.pageSize ?? 25;
-  const [query, setQuery] = useState(defaultDetailQuery(pageSize));
+  const optionSort = sortFromOptions(
+    definition,
+    widget.options
+  );
+  const [query, setQuery] = useState({
+    ...defaultDetailQuery(pageSize),
+    ...optionSort === void 0 ? {} : { sort: optionSort }
+  });
   const derived = useMemo(
     () => widget.status === "ok" ? deriveDetailData(widget.data, locale) : void 0,
     [widget, locale]
@@ -2536,7 +2828,8 @@ function DetailHost({
     definition,
     loadDetail,
     true,
-    derived
+    derived,
+    widget.options
   );
   const title = options?.title ?? definition.title;
   return /* @__PURE__ */ jsx(WidgetDetailDialog, { title, open: true, onClose, children: /* @__PURE__ */ jsx(
@@ -3390,6 +3683,196 @@ function Dashboard({
     }
   );
 }
+function useStoredLayout(options) {
+  const {
+    persistence,
+    scope,
+    definitions,
+    defaultLayout,
+    saveDelayMs = 500,
+    initialLayout,
+    normalizeOptions
+  } = options;
+  const scopeKey = persistence.keyFor(scope);
+  const [layout, setLayoutState] = useState(
+    initialLayout ?? defaultLayout
+  );
+  const [backup, setBackupState] = useState(null);
+  const [status, setStatus] = useState("loading");
+  const [error, setError] = useState(null);
+  const [conflict, setConflict] = useState(null);
+  const [remoteLayout, setRemoteLayout] = useState(
+    null
+  );
+  const latest = useRef(layout);
+  const scopeRef = useRef(scope);
+  scopeRef.current = scope;
+  const normalizeRef = useRef(normalizeOptions);
+  normalizeRef.current = normalizeOptions;
+  const timer = useRef(void 0);
+  const dirty = useRef(false);
+  const apply = useCallback((next) => {
+    latest.current = next;
+    setLayoutState(next);
+  }, []);
+  const finishSave = 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 = 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]);
+  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]);
+  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]);
+  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 = 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 = 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 = 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 = 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 = [
@@ -3733,12 +4216,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(
@@ -3773,7 +4277,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
     ]);
@@ -3797,7 +4304,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
       });
@@ -3814,7 +4321,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();
@@ -3855,19 +4372,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 {
@@ -3875,13 +4392,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);
@@ -3916,6 +4435,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."));
@@ -3933,6 +4475,7 @@ function createWidgetLoader(options) {
     load,
     loadAll,
     refresh,
+    setOptions,
     dispose
   };
 }
@@ -3947,7 +4490,8 @@ function useWidgets(definitions, providers, context, options = {}) {
     timeoutMs,
     signal,
     cache,
-    cacheKey
+    cacheKey,
+    optionValues
   } = options;
   const placeholders = useMemo(
     () => loadingWidgets(widgetsFor(definitions, context.roles)),
@@ -3957,6 +4501,8 @@ function useWidgets(definitions, providers, context, options = {}) {
   const [loader, setLoader] = useState(null);
   const loaderRef = useRef(null);
   const gridRef = useRef(null);
+  const optionValuesRef = useRef(optionValues);
+  optionValuesRef.current = optionValues;
   useEffect(() => {
     const created = createWidgetLoader({
       definitions,
@@ -3966,7 +4512,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());
@@ -4038,12 +4585,25 @@ function useWidgets(definitions, providers, context, options = {}) {
     }, refreshMs);
     return () => clearInterval(timer);
   }, [loader, refreshMs]);
+  const optionSignature = JSON.stringify(optionValues ?? {});
+  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 = useCallback(
+    (key, chosen) => {
+      loaderRef.current?.setOptions(key, chosen);
+    },
+    []
+  );
   const refresh = useCallback((key) => {
     loaderRef.current?.refresh(key);
   }, []);
-  return { widgets, refresh, gridRef };
+  return { widgets, refresh, setOptions, gridRef };
 }
 
-export { AlertListWidget, BarListWidget, DEFAULT_LABELS, DEFAULT_SERIES_COLORS, Dashboard, GaugeWidget, GraphWidget, KpiWidget, ResolvedWidgetCard, TableWidget, TextWidget, Thumbnail, WidgetCard, WidgetContent, WidgetDetail, WidgetDetailDialog, WidgetGrid, WidgetLink, WidgetSettingsProvider, barPath, buildChartModel, describeChart, joinClassNames, seriesColor, useDetailData, useWidgetSettings, useWidgets, widgetTitle };
+export { AlertListWidget, BarListWidget, DEFAULT_LABELS, DEFAULT_SERIES_COLORS, Dashboard, GaugeWidget, GraphWidget, KpiWidget, ResolvedWidgetCard, TableWidget, TextWidget, Thumbnail, WidgetCard, WidgetContent, WidgetDetail, WidgetDetailDialog, WidgetGrid, WidgetLink, WidgetSettingsProvider, barPath, buildChartModel, describeChart, joinClassNames, seriesColor, useDetailData, useStoredLayout, useWidgetSettings, useWidgets, widgetTitle };
 //# sourceMappingURL=react.js.map
 //# sourceMappingURL=react.js.map