@richardmcquiston01/dashboard-widgets-toolkit 0.16.0 → 0.17.0

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import { ReactNode, ReactElement, RefObject } from 'react';
-import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, O as OptionValues, L as Locale, f as DashboardLayout, g as WidgetViewerSettings, h as WidgetSettingsPatch, A as AlertListWidgetData, B as BarListWidgetData, i as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, j as DetailSort, k as TextWidgetData, l as WidgetData, m as LayoutPersistence, S as StoreScope, P as PageItem, n as NormalizeOptions, o as ResolveOptions, p as WidgetContext, q as WidgetProviders } from './storage-oivwB7al.cjs';
+import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, O as OptionValues, L as Locale, f as DashboardLayout, g as WidgetViewerSettings, h as WidgetSettingsPatch, A as AlertListWidgetData, B as BarListWidgetData, i as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, j as DetailSort, k as TextWidgetData, l as WidgetData, m as LayoutPersistence, S as StoreScope, P as PageItem, n as NormalizeOptions, o as ResolveOptions, p as WidgetContext, q as WidgetProviders } from './storage-CRBfjiVZ.cjs';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -566,6 +566,13 @@ interface UseWidgetsOptions extends ResolveOptions {
      * fresh object each render.
      */
     readonly optionValues?: Readonly<Record<string, Readonly<Record<string, unknown>> | undefined>>;
+    /**
+     * The view each widget shows, by widget key (see `viewValuesFromLayout`).
+     * Only views the provider supplies matter: choosing one loads it (the
+     * provider is called with `options.view`), and the card shows loading until
+     * it arrives. It may be a fresh object each render.
+     */
+    readonly viewValues?: Readonly<Record<string, string | undefined>>;
 }
 interface UseWidgetsResult {
     /** Pass to `Dashboard` or `WidgetGrid`: placeholders first, then results. */
@@ -574,6 +581,8 @@ interface UseWidgetsResult {
     readonly refresh: (key?: string) => void;
     /** Choose option values for one widget; same effect as `optionValues`. */
     readonly setOptions: (key: string, chosen: Readonly<Record<string, unknown>>) => void;
+    /** Choose a widget's view; same effect as `viewValues`. */
+    readonly setView: (key: string, view: string | undefined) => void;
     /**
      * For `loadWhen: 'visible'`: attach to any element that contains the cards,
      * for example a wrapper `<div ref={gridRef}>` around `Dashboard`.

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode, ReactElement, RefObject } from 'react';
-import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, O as OptionValues, L as Locale, f as DashboardLayout, g as WidgetViewerSettings, h as WidgetSettingsPatch, A as AlertListWidgetData, B as BarListWidgetData, i as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, j as DetailSort, k as TextWidgetData, l as WidgetData, m as LayoutPersistence, S as StoreScope, P as PageItem, n as NormalizeOptions, o as ResolveOptions, p as WidgetContext, q as WidgetProviders } from './storage-oivwB7al.js';
+import { D as DashboardWidget, W as WidgetSize, a as WidgetFill, G as GraphWidgetData, N as NiceDomain, b as WidgetDefinition, c as DetailProviderOptions, d as DetailData, e as DetailQuery, O as OptionValues, L as Locale, f as DashboardLayout, g as WidgetViewerSettings, h as WidgetSettingsPatch, A as AlertListWidgetData, B as BarListWidgetData, i as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, j as DetailSort, k as TextWidgetData, l as WidgetData, m as LayoutPersistence, S as StoreScope, P as PageItem, n as NormalizeOptions, o as ResolveOptions, p as WidgetContext, q as WidgetProviders } from './storage-CRBfjiVZ.js';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -566,6 +566,13 @@ interface UseWidgetsOptions extends ResolveOptions {
      * fresh object each render.
      */
     readonly optionValues?: Readonly<Record<string, Readonly<Record<string, unknown>> | undefined>>;
+    /**
+     * The view each widget shows, by widget key (see `viewValuesFromLayout`).
+     * Only views the provider supplies matter: choosing one loads it (the
+     * provider is called with `options.view`), and the card shows loading until
+     * it arrives. It may be a fresh object each render.
+     */
+    readonly viewValues?: Readonly<Record<string, string | undefined>>;
 }
 interface UseWidgetsResult {
     /** Pass to `Dashboard` or `WidgetGrid`: placeholders first, then results. */
@@ -574,6 +581,8 @@ interface UseWidgetsResult {
     readonly refresh: (key?: string) => void;
     /** Choose option values for one widget; same effect as `optionValues`. */
     readonly setOptions: (key: string, chosen: Readonly<Record<string, unknown>>) => void;
+    /** Choose a widget's view; same effect as `viewValues`. */
+    readonly setView: (key: string, view: string | undefined) => void;
     /**
      * For `loadWhen: 'visible'`: attach to any element that contains the cards,
      * for example a wrapper `<div ref={gridRef}>` around `Dashboard`.

package/dist/react.js

@@ -2066,6 +2066,9 @@ function viewChoices(item) {
     }))
   ];
 }
+function isProviderView(view) {
+  return view.convert === void 0;
+}
 function isKnownView(item, key) {
   return key !== void 0 && (key === BASE_VIEW_KEY || findView(item, key) !== void 0);
 }
@@ -2075,6 +2078,14 @@ function effectiveViewKey(item, chosen) {
   if (isKnownView(item, item.defaultView)) return item.defaultView;
   return BASE_VIEW_KEY;
 }
+function loadViewKey(item, chosen) {
+  const key = effectiveViewKey(item, chosen);
+  const view = findView(item, key);
+  return view !== void 0 && isProviderView(view) ? key : BASE_VIEW_KEY;
+}
+function loadViewKind(item, chosen) {
+  return findView(item, loadViewKey(item, chosen))?.kind ?? item.kind;
+}
 function cellValue2(cell) {
   const value = cell?.value;
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
@@ -2209,6 +2220,11 @@ function convertView(widgetKey, view, data, options = {}) {
     where: `Widget ${JSON.stringify(widgetKey)} view ${JSON.stringify(view.key)}`,
     ...options.locale === void 0 ? {} : { locale: options.locale }
   };
+  if (conversion === void 0) {
+    return err(
+      `${context.where}: the provider supplies this view, so there is nothing to convert.`
+    );
+  }
   const expected = VIEW_CONVERSIONS[conversion.type]?.from;
   if (expected === void 0) {
     return err(
@@ -2236,14 +2252,29 @@ function convertView(widgetKey, view, data, options = {}) {
 function applyView(widget, chosen, options = {}) {
   const key = effectiveViewKey(widget.definition, chosen);
   const view = findView(widget.definition, key);
-  if (view === void 0) return widget;
+  const wanted = loadViewKey(widget.definition, chosen);
+  const loaded = widget.status === "ok" ? widget.view ?? BASE_VIEW_KEY : void 0;
+  const mismatched = loaded !== void 0 && loaded !== wanted;
+  if (view === void 0) {
+    return mismatched ? {
+      definition: widget.definition,
+      status: "loading",
+      ...widget.options === void 0 ? {} : { options: widget.options }
+    } : widget;
+  }
   const definition = {
     ...widget.definition,
     kind: view.kind
   };
-  if (widget.status === "loading") return { ...widget, definition };
-  if (widget.status === "empty") return { ...widget, definition };
-  if (widget.status === "error") return { ...widget, definition };
+  if (widget.status !== "ok") return { ...widget, definition };
+  if (mismatched) {
+    return {
+      definition,
+      status: "loading",
+      ...widget.options === void 0 ? {} : { options: widget.options }
+    };
+  }
+  if (isProviderView(view)) return { ...widget, definition };
   const converted = convertView(
     widget.definition.key,
     view,
@@ -5677,7 +5708,10 @@ function resolvePayload(definition, payload, options = {}) {
   } else {
     const result = validateWidgetData(payload, {
       widgetKey: definition.key,
-      expectedKind: definition.kind
+      expectedKind: loadViewKind(
+        definition,
+        options.viewValues?.[definition.key]
+      )
     });
     if (!result.ok) {
       return { definition, status: "error", error: result.error };
@@ -5688,7 +5722,14 @@ function resolvePayload(definition, payload, options = {}) {
   if (emptyText !== null) {
     return { definition, status: "empty", emptyText };
   }
-  return { definition, status: "ok", data: checked };
+  return {
+    definition,
+    status: "ok",
+    data: checked,
+    ...hasViews(definition) ? {
+      view: loadViewKey(definition, options.viewValues?.[definition.key])
+    } : {}
+  };
 }
 function failedWidget(definition, error) {
   return { definition, status: "error", error };
@@ -5698,7 +5739,14 @@ function loadingWidgets(definitions) {
 }
 function cacheKeyFor(definition, options, values) {
   const base = options.cacheKey === void 0 ? definition.sourceKey ?? definition.key : options.cacheKey(definition);
-  return values === void 0 ? base : `${base}${optionsCacheSuffix(definition, values, options)}`;
+  const view = loadViewKey(
+    definition,
+    options.viewValues?.[definition.key]
+  );
+  const viewPart = view === BASE_VIEW_KEY ? "" : `view=${encodeURIComponent(view)}`;
+  const optionPart = values === void 0 ? "" : optionsCacheSuffix(definition, values, options);
+  if (viewPart === "") return `${base}${optionPart}`;
+  return optionPart === "" ? `${base}?${viewPart}` : `${base}?${viewPart}&${optionPart.slice(1)}`;
 }
 function optionValuesFor(definition, options) {
   return resolveOptionValues(
@@ -5709,6 +5757,9 @@ function optionValuesFor(definition, options) {
 }
 function finalizeWidget(widget, values) {
   if (Object.keys(values).length === 0) return widget;
+  if (widget.status === "ok" && widget.view !== void 0 && widget.view !== BASE_VIEW_KEY) {
+    return { ...widget, options: values };
+  }
   if (widget.status === "ok") {
     const data = applyClientOptions(
       widget.definition,
@@ -5759,7 +5810,8 @@ async function resolveWidgetUnapplied(definition, provider, context, options = {
         if (controller.signal.aborted) throw new LoadInterruption();
         return provider(context, definition, {
           signal: controller.signal,
-          options: values
+          options: values,
+          view: loadViewKey(definition, options.viewValues?.[definition.key])
         });
       }),
       interrupted
@@ -5807,9 +5859,18 @@ function createWidgetLoader(options) {
       ([key, values]) => values === void 0 ? [] : [[key, values]]
     )
   );
+  const chosenViews = new Map(
+    Object.entries(baseOptions.viewValues ?? {}).flatMap(
+      ([key, view]) => view === void 0 ? [] : [[key, view]]
+    )
+  );
   const resolveOptions = baseOptions;
   function currentOptions() {
-    return { ...resolveOptions, optionValues: Object.fromEntries(chosen) };
+    return {
+      ...resolveOptions,
+      optionValues: Object.fromEntries(chosen),
+      viewValues: Object.fromEntries(chosenViews)
+    };
   }
   const unapplied = /* @__PURE__ */ new Map();
   const visible = widgetsFor(definitions, context.roles);
@@ -5942,6 +6003,23 @@ function createWidgetLoader(options) {
     }
     start(definition, true);
   }
+  function setView(key, view) {
+    if (disposed) return;
+    const definition = definitionFor(key);
+    if (definition === void 0) return;
+    const before = loadViewKey(definition, chosenViews.get(key));
+    if (view === void 0 || view === "") chosenViews.delete(key);
+    else chosenViews.set(key, view);
+    const after = loadViewKey(definition, chosenViews.get(key));
+    if (before === after || !started.has(key)) return;
+    const current = snapshot.find(
+      (widget) => widget.definition.key === key
+    );
+    if (current !== void 0 && current.status !== "loading") {
+      replace(key, { definition, status: "loading" });
+    }
+    start(definition, true);
+  }
   function dispose() {
     disposed = true;
     abortAll(new Error("The widget loader was disposed."));
@@ -5960,6 +6038,7 @@ function createWidgetLoader(options) {
     loadAll,
     refresh,
     setOptions,
+    setView,
     dispose
   };
 }
@@ -5975,7 +6054,8 @@ function useWidgets(definitions, providers, context, options = {}) {
     signal,
     cache,
     cacheKey,
-    optionValues
+    optionValues,
+    viewValues
   } = options;
   const placeholders = useMemo(
     () => loadingWidgets(widgetsFor(definitions, context.roles)),
@@ -5987,6 +6067,8 @@ function useWidgets(definitions, providers, context, options = {}) {
   const gridRef = useRef(null);
   const optionValuesRef = useRef(optionValues);
   optionValuesRef.current = optionValues;
+  const viewValuesRef = useRef(viewValues);
+  viewValuesRef.current = viewValues;
   useEffect(() => {
     const created = createWidgetLoader({
       definitions,
@@ -5997,7 +6079,8 @@ function useWidgets(definitions, providers, context, options = {}) {
       ...signal === void 0 ? {} : { signal },
       ...cache === void 0 ? {} : { cache },
       ...cacheKey === void 0 ? {} : { cacheKey },
-      ...optionValuesRef.current === void 0 ? {} : { optionValues: optionValuesRef.current }
+      ...optionValuesRef.current === void 0 ? {} : { optionValues: optionValuesRef.current },
+      ...viewValuesRef.current === void 0 ? {} : { viewValues: viewValuesRef.current }
     });
     loaderRef.current = created;
     setWidgets(created.getSnapshot());
@@ -6076,6 +6159,16 @@ function useWidgets(definitions, providers, context, options = {}) {
       if (chosen !== void 0) loader.setOptions(key, chosen);
     }
   }, [loader, optionSignature]);
+  const viewSignature = JSON.stringify(viewValues ?? {});
+  useEffect(() => {
+    if (loader === null) return;
+    for (const [key, view] of Object.entries(viewValuesRef.current ?? {})) {
+      loader.setView(key, view);
+    }
+  }, [loader, viewSignature]);
+  const setView = useCallback((key, view) => {
+    loaderRef.current?.setView(key, view);
+  }, []);
   const setOptions = useCallback(
     (key, chosen) => {
       loaderRef.current?.setOptions(key, chosen);
@@ -6085,7 +6178,7 @@ function useWidgets(definitions, providers, context, options = {}) {
   const refresh = useCallback((key) => {
     loaderRef.current?.refresh(key);
   }, []);
-  return { widgets, refresh, setOptions, gridRef };
+  return { widgets, refresh, setOptions, setView, gridRef };
 }
 
 export { AlertListWidget, BarListWidget, DEFAULT_LABELS, DEFAULT_SERIES_COLORS, Dashboard, GaugeWidget, GraphWidget, KpiWidget, ResolvedWidgetCard, TableWidget, TextWidget, Thumbnail, WidgetCard, WidgetContent, WidgetDetail, WidgetDetailDialog, WidgetGrid, WidgetLink, WidgetOptionsDialog, WidgetSettingsProvider, barPath, buildChartModel, describeChart, joinClassNames, seriesColor, useDetailData, useStoredLayout, useWidgetSettings, useWidgets, widgetTitle };