@richardmcquiston01/dashboard-widgets-toolkit 0.14.0 → 0.15.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-_Eb8Y98-.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-DwJ-vGJg.cjs';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -225,6 +225,10 @@ interface DashboardLabels {
     /** e.g. "6 of 12 (1/2)". */
     readonly widthOption: (width: number, share: string) => string;
     readonly optionsFlexible: string;
+    /** Label of the View field in the Options dialog. */
+    readonly optionsViewField: string;
+    /** A view's name when it is the one shown until the viewer picks, e.g. "Table (default)". */
+    readonly viewDefault: (viewLabel: string) => string;
     readonly optionsDeclared: string;
     readonly apply: string;
     readonly cancel: string;

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-_Eb8Y98-.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-DwJ-vGJg.js';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -225,6 +225,10 @@ interface DashboardLabels {
     /** e.g. "6 of 12 (1/2)". */
     readonly widthOption: (width: number, share: string) => string;
     readonly optionsFlexible: string;
+    /** Label of the View field in the Options dialog. */
+    readonly optionsViewField: string;
+    /** A view's name when it is the one shown until the viewer picks, e.g. "Table (default)". */
+    readonly viewDefault: (viewLabel: string) => string;
     readonly optionsDeclared: string;
     readonly apply: string;
     readonly cancel: string;

package/dist/react.js

@@ -835,6 +835,8 @@ var DEFAULT_LABELS = {
   widthDefault: "Default",
   widthOption: (width, share) => `${width} of 12 (${share})`,
   optionsFlexible: "Grow to fill empty space in the row",
+  optionsViewField: "View",
+  viewDefault: (viewLabel) => `${viewLabel} (default)`,
   optionsDeclared: "Data",
   apply: "Apply",
   cancel: "Cancel",
@@ -1972,6 +1974,282 @@ function isWidgetVisibleTo(definition, roles) {
   return definition.roles.some((role) => roles.includes(role));
 }
 
+// src/core/payload.ts
+var WIDGET_KINDS = [
+  "TEXT",
+  "KPI",
+  "GAUGE",
+  "TABLE",
+  "BAR_LIST",
+  "ALERT_LIST",
+  "GRAPH"
+];
+function isWidgetKind(value) {
+  return typeof value === "string" && WIDGET_KINDS.includes(value);
+}
+var VALUE_FORMATS = ["number", "currency", "percent"];
+var MAX_GRAPH_SERIES = 8;
+var DEFAULT_EMPTY_TEXT = "Nothing to show yet.";
+function isWidgetEmptyState(payload) {
+  return "empty" in payload && payload.empty === true;
+}
+function emptyTextFor(payload) {
+  if (isWidgetEmptyState(payload)) {
+    return payload.text;
+  }
+  switch (payload.kind) {
+    case "TABLE":
+      return payload.rows.length === 0 ? DEFAULT_EMPTY_TEXT : null;
+    case "BAR_LIST":
+      return payload.items.length === 0 ? DEFAULT_EMPTY_TEXT : null;
+    case "ALERT_LIST":
+      return payload.items.length === 0 ? payload.emptyText : null;
+    case "GRAPH":
+      return payload.series.every((series) => series.points.length === 0) ? DEFAULT_EMPTY_TEXT : null;
+    case "TEXT":
+    case "KPI":
+    case "GAUGE":
+      return null;
+  }
+}
+
+// src/core/views.ts
+var BASE_VIEW_KEY = "base";
+var VIEW_CONVERSIONS = {
+  tableToBarList: { from: "TABLE", to: "BAR_LIST" },
+  tableToGraph: { from: "TABLE", to: "GRAPH" },
+  barListToTable: { from: "BAR_LIST", to: "TABLE" },
+  graphToTable: { from: "GRAPH", to: "TABLE" },
+  barListToGraph: { from: "BAR_LIST", to: "GRAPH" }
+};
+var KIND_LABELS = {
+  TEXT: "Text",
+  KPI: "Number",
+  GAUGE: "Gauge",
+  TABLE: "Table",
+  BAR_LIST: "Bars",
+  ALERT_LIST: "List",
+  GRAPH: "Chart"
+};
+function kindLabel(kind) {
+  return KIND_LABELS[kind];
+}
+function hasViews(item) {
+  return item.views !== void 0 && item.views.length > 0;
+}
+function findView(item, key) {
+  return item.views?.find((view) => view.key === key);
+}
+function viewChoices(item) {
+  if (!hasViews(item)) return [];
+  return [
+    {
+      key: BASE_VIEW_KEY,
+      label: item.baseViewLabel ?? kindLabel(item.kind),
+      kind: item.kind
+    },
+    ...(item.views ?? []).map(({ key, label, kind }) => ({
+      key,
+      label,
+      kind
+    }))
+  ];
+}
+function isKnownView(item, key) {
+  return key !== void 0 && (key === BASE_VIEW_KEY || findView(item, key) !== void 0);
+}
+function effectiveViewKey(item, chosen) {
+  if (!hasViews(item)) return BASE_VIEW_KEY;
+  if (isKnownView(item, chosen)) return chosen;
+  if (isKnownView(item, item.defaultView)) return item.defaultView;
+  return BASE_VIEW_KEY;
+}
+function cellValue2(cell) {
+  const value = cell?.value;
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function columnName(table, index) {
+  return table.columns[index]?.label ?? `#${index + 1}`;
+}
+function checkColumn(table, index, field, context) {
+  if (!Number.isInteger(index) || index < 0 || index >= table.columns.length) {
+    return `${context.where}: ${field} column ${index} does not exist (the table has ${table.columns.length} columns, numbered from 0).`;
+  }
+  return void 0;
+}
+function numericColumn(table, index, context) {
+  const numbers = [];
+  for (const [rowIndex, row] of table.rows.entries()) {
+    const value = cellValue2(row[index]);
+    if (value === void 0) {
+      return err(
+        `${context.where}: row ${rowIndex + 1}, column ${index + 1} ("${columnName(table, index)}") has no numeric value. Add value to the cells.`
+      );
+    }
+    numbers.push(value);
+  }
+  return ok(numbers);
+}
+function tableToBarList(table, conversion, context) {
+  const bad = checkColumn(table, conversion.label, "label", context) ?? checkColumn(table, conversion.value, "value", context);
+  if (bad !== void 0) return err(bad);
+  const numbers = numericColumn(table, conversion.value, context);
+  if (!numbers.ok) return numbers;
+  const items = table.rows.map((row, index) => ({
+    label: row[conversion.label]?.text ?? "",
+    value: numbers.value[index],
+    display: row[conversion.value]?.text ?? String(numbers.value[index])
+  }));
+  return ok({ kind: "BAR_LIST", items });
+}
+function tableToGraph(table, conversion, context) {
+  if (conversion.values.length === 0 || conversion.values.length > MAX_GRAPH_SERIES) {
+    return err(
+      `${context.where}: a chart needs 1 to ${MAX_GRAPH_SERIES} series columns, got ${conversion.values.length}.`
+    );
+  }
+  let bad = checkColumn(
+    table,
+    conversion.label,
+    "label",
+    context
+  );
+  for (const index of conversion.values) {
+    bad ??= checkColumn(table, index, "series", context);
+  }
+  if (bad !== void 0) return err(bad);
+  const series = [];
+  for (const index of conversion.values) {
+    const numbers = numericColumn(table, index, context);
+    if (!numbers.ok) return numbers;
+    series.push({
+      name: columnName(table, index),
+      points: table.rows.map((row, rowIndex) => ({
+        label: row[conversion.label]?.text ?? "",
+        value: numbers.value[rowIndex]
+      }))
+    });
+  }
+  return ok({
+    kind: "GRAPH",
+    series,
+    chartType: conversion.chartType,
+    valueFormat: conversion.valueFormat ?? "number",
+    ...conversion.currency === void 0 ? {} : { currency: conversion.currency },
+    xLabel: columnName(table, conversion.label)
+  });
+}
+function barListToTable(list, conversion) {
+  return ok({
+    kind: "TABLE",
+    columns: [
+      { label: conversion.labelHeading ?? "Name" },
+      { label: conversion.valueHeading ?? "Value", numeric: true }
+    ],
+    rows: list.items.map((item) => [
+      { text: item.label },
+      { text: item.display ?? String(item.value), value: item.value }
+    ])
+  });
+}
+function graphToTable(graph, context) {
+  const first = graph.series[0];
+  if (first === void 0)
+    return err(`${context.where}: the chart has no series.`);
+  const format = {
+    ...graph.currency === void 0 ? {} : { currency: graph.currency },
+    ...context.locale === void 0 ? {} : { locale: context.locale }
+  };
+  return ok({
+    kind: "TABLE",
+    columns: [
+      { label: graph.xLabel ?? "Label" },
+      ...graph.series.map((series) => ({ label: series.name, numeric: true }))
+    ],
+    rows: first.points.map((point, index) => [
+      { text: point.label },
+      ...graph.series.map((series) => {
+        const value = series.points[index]?.value;
+        return value === void 0 ? { text: "\u2014" } : { text: formatValue(value, graph.valueFormat, format), value };
+      })
+    ])
+  });
+}
+function barListToGraph(list, conversion) {
+  return ok({
+    kind: "GRAPH",
+    series: [
+      {
+        name: conversion.seriesName ?? "Value",
+        points: list.items.map((item) => ({
+          label: item.label,
+          value: item.value
+        }))
+      }
+    ],
+    chartType: conversion.chartType,
+    valueFormat: conversion.valueFormat ?? "number",
+    ...conversion.currency === void 0 ? {} : { currency: conversion.currency }
+  });
+}
+function convertView(widgetKey, view, data, options = {}) {
+  const conversion = view.convert;
+  const context = {
+    where: `Widget ${JSON.stringify(widgetKey)} view ${JSON.stringify(view.key)}`,
+    ...options.locale === void 0 ? {} : { locale: options.locale }
+  };
+  const expected = VIEW_CONVERSIONS[conversion.type]?.from;
+  if (expected === void 0) {
+    return err(
+      `${context.where}: unknown conversion type ${JSON.stringify(conversion.type)}.`
+    );
+  }
+  if (data.kind !== expected) {
+    return err(
+      `${context.where}: ${conversion.type} reads a ${expected} payload, but the widget returned ${data.kind}.`
+    );
+  }
+  switch (conversion.type) {
+    case "tableToBarList":
+      return tableToBarList(data, conversion, context);
+    case "tableToGraph":
+      return tableToGraph(data, conversion, context);
+    case "barListToTable":
+      return barListToTable(data, conversion);
+    case "graphToTable":
+      return graphToTable(data, context);
+    case "barListToGraph":
+      return barListToGraph(data, conversion);
+  }
+}
+function applyView(widget, chosen, options = {}) {
+  const key = effectiveViewKey(widget.definition, chosen);
+  const view = findView(widget.definition, key);
+  if (view === void 0) return 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 };
+  const converted = convertView(
+    widget.definition.key,
+    view,
+    widget.data,
+    options
+  );
+  if (!converted.ok) {
+    return {
+      definition,
+      status: "error",
+      error: converted.error,
+      ...widget.options === void 0 ? {} : { options: widget.options }
+    };
+  }
+  return { ...widget, definition, data: converted.value };
+}
+
 // src/core/settings.ts
 var MAX_WIDGET_TITLE_LENGTH = 80;
 var MAX_COLUMN_LIST = 100;
@@ -1999,6 +2277,7 @@ function parseOne(raw) {
   const width = raw["width"];
   const flexible = raw["flexible"];
   const options = raw["options"];
+  const view = raw["view"];
   const cleanTitle = typeof title === "string" ? title.trim().slice(0, MAX_WIDGET_TITLE_LENGTH) : "";
   const chosen = {};
   if (isRecord(options)) {
@@ -2011,7 +2290,8 @@ function parseOne(raw) {
     ...cleanTitle === "" ? {} : { title: cleanTitle },
     ...isWidgetWidth(width) ? { width } : {},
     ...typeof flexible === "boolean" ? { flexible } : {},
-    ...Object.keys(chosen).length === 0 ? {} : { options: chosen }
+    ...Object.keys(chosen).length === 0 ? {} : { options: chosen },
+    ...typeof view === "string" && view !== "" && view.length <= 80 ? { view } : {}
   };
   return Object.keys(settings).length === 0 ? void 0 : settings;
 }
@@ -2079,12 +2359,18 @@ function effectiveDefinitions(definitions, layout, options = {}) {
 }
 function sameSettings(a, b) {
   if (a === b) return true;
-  return a?.title === b?.title && a?.width === b?.width && a?.flexible === b?.flexible && sameOptionValues(a?.options ?? {}, b?.options ?? {});
+  return a?.title === b?.title && a?.width === b?.width && a?.flexible === b?.flexible && a?.view === b?.view && sameOptionValues(a?.options ?? {}, b?.options ?? {});
 }
 function setWidgetSettings(layout, key, patch) {
   const before = layout.settings?.[key];
   const draft = { ...before };
-  for (const field of ["title", "width", "flexible", "options"]) {
+  for (const field of [
+    "title",
+    "width",
+    "flexible",
+    "options",
+    "view"
+  ]) {
     if (!(field in patch)) continue;
     const value = patch[field];
     if (value === void 0) {
@@ -2788,7 +3074,8 @@ function draftFrom(settings) {
     title: settings?.title ?? "",
     width: settings?.width,
     flexible: settings?.flexible,
-    options: settings?.options ?? {}
+    options: settings?.options ?? {},
+    view: settings?.view
   };
 }
 function storedDefault(option) {
@@ -2813,7 +3100,9 @@ function patchFrom(definition, draft) {
     title: title === "" ? void 0 : title,
     width: draft.width,
     flexible: draft.flexible === void 0 || draft.flexible === isFlexible(definition) ? void 0 : draft.flexible,
-    options: Object.keys(options).length === 0 ? void 0 : options
+    options: Object.keys(options).length === 0 ? void 0 : options,
+    // Choosing the author's own default view again clears the setting.
+    view: draft.view === void 0 || draft.view === effectiveViewKey(definition, void 0) ? void 0 : draft.view
   };
 }
 function patchKey(patch) {
@@ -2821,13 +3110,20 @@ function patchKey(patch) {
   for (const key of Object.keys(patch.options ?? {}).sort()) {
     options[key] = patch.options[key];
   }
-  return JSON.stringify([patch.title, patch.width, patch.flexible, options]);
+  return JSON.stringify([
+    patch.title,
+    patch.width,
+    patch.flexible,
+    options,
+    patch.view
+  ]);
 }
 var EMPTY_PATCH = {
   title: void 0,
   width: void 0,
   flexible: void 0,
-  options: void 0
+  options: void 0,
+  view: void 0
 };
 function WidgetOptionsDialog({
   definition,
@@ -2865,6 +3161,7 @@ function WidgetOptionsDialog({
   const canRevert = baselineKey !== void 0 && baselineKey !== savedKey;
   const canReset = savedKey !== patchKey(EMPTY_PATCH);
   const range = widthRange(definition);
+  const views = viewChoices(definition);
   const effectiveFlexible = draft.flexible ?? isFlexible(definition);
   function requestClose() {
     if (confirming !== void 0) {
@@ -2990,6 +3287,21 @@ function WidgetOptionsDialog({
               ),
               labels.optionsFlexible
             ] }),
+            views.length > 0 && /* @__PURE__ */ jsxs("div", { className: "dwt-options-field", children: [
+              /* @__PURE__ */ jsx("label", { htmlFor: `${baseId}-view`, children: labels.optionsViewField }),
+              /* @__PURE__ */ jsx(
+                "select",
+                {
+                  id: `${baseId}-view`,
+                  value: effectiveViewKey(definition, draft.view),
+                  onChange: (event) => {
+                    const value = event.target.value;
+                    setDraft((current) => ({ ...current, view: value }));
+                  },
+                  children: views.map((view) => /* @__PURE__ */ jsx("option", { value: view.key, children: view.key === effectiveViewKey(definition, void 0) ? labels.viewDefault(view.label) : view.label }, view.key))
+                }
+              )
+            ] }),
             (definition.options?.length ?? 0) > 0 && /* @__PURE__ */ jsxs("fieldset", { className: "dwt-options-group", children: [
               /* @__PURE__ */ jsx("legend", { children: labels.optionsDeclared }),
               (definition.options ?? []).map((option) => /* @__PURE__ */ jsx(
@@ -3969,10 +4281,13 @@ function DashboardInner({
   className
 }) {
   const slot = useSlotClassName();
-  const { labels } = useWidgetSettings();
+  const { labels, locale } = useWidgetSettings();
   const effectiveWidgets = widgets.map((w) => {
-    const settings = savedLayout.settings?.[w.definition.key];
-    return settings === void 0 || !overrideLocks && isOptionsLocked(w.definition) ? w : { ...w, definition: applySettings(w.definition, settings) };
+    const settings = !overrideLocks && isOptionsLocked(w.definition) ? void 0 : savedLayout.settings?.[w.definition.key];
+    const styled = settings === void 0 ? w : { ...w, definition: applySettings(w.definition, settings) };
+    return applyView(styled, settings?.view, {
+      ...locale === void 0 ? {} : { locale }
+    });
   });
   const definitions = effectiveWidgets.map(
     (w) => overrideLocks ? withoutLock(w.definition) : w.definition
@@ -4817,45 +5132,6 @@ function useStoredLayout(options) {
   };
 }
 
-// src/core/payload.ts
-var WIDGET_KINDS = [
-  "TEXT",
-  "KPI",
-  "GAUGE",
-  "TABLE",
-  "BAR_LIST",
-  "ALERT_LIST",
-  "GRAPH"
-];
-function isWidgetKind(value) {
-  return typeof value === "string" && WIDGET_KINDS.includes(value);
-}
-var VALUE_FORMATS = ["number", "currency", "percent"];
-var MAX_GRAPH_SERIES = 8;
-var DEFAULT_EMPTY_TEXT = "Nothing to show yet.";
-function isWidgetEmptyState(payload) {
-  return "empty" in payload && payload.empty === true;
-}
-function emptyTextFor(payload) {
-  if (isWidgetEmptyState(payload)) {
-    return payload.text;
-  }
-  switch (payload.kind) {
-    case "TABLE":
-      return payload.rows.length === 0 ? DEFAULT_EMPTY_TEXT : null;
-    case "BAR_LIST":
-      return payload.items.length === 0 ? DEFAULT_EMPTY_TEXT : null;
-    case "ALERT_LIST":
-      return payload.items.length === 0 ? payload.emptyText : null;
-    case "GRAPH":
-      return payload.series.every((series) => series.points.length === 0) ? DEFAULT_EMPTY_TEXT : null;
-    case "TEXT":
-    case "KPI":
-    case "GAUGE":
-      return null;
-  }
-}
-
 // src/core/validate.ts
 var MAX_REPORTED_PROBLEMS = 10;
 function describeType2(value) {