@richardmcquiston01/dashboard-widgets-toolkit 0.14.0 → 0.15.0

package/dist/core.cjs

@@ -688,6 +688,263 @@ function placeAndFillRows(items, columns, spanOf) {
   return { spans, rows };
 }
 
+// src/core/views.ts
+var BASE_VIEW_KEY = "base";
+var MAX_WIDGET_VIEWS = 8;
+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 viewKind(item, chosen) {
+  return findView(item, effectiveViewKey(item, chosen))?.kind ?? item.kind;
+}
+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 viewNote(view, data) {
+  if (data?.kind !== "TABLE") return "";
+  const conversion = view.convert;
+  let indexes;
+  if (conversion.type === "tableToBarList") {
+    indexes = [conversion.label, conversion.value];
+  } else if (conversion.type === "tableToGraph") {
+    indexes = [conversion.label, ...conversion.values];
+  } else {
+    return "";
+  }
+  const names = indexes.map(
+    (index) => data.columns[index]?.label ?? `#${index + 1}`
+  );
+  return `Shows ${names.join(", ")} only.`;
+}
+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/options.ts
 var DATE_RANGE_PRESETS = [
   "today",
@@ -993,6 +1250,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)) {
@@ -1005,7 +1263,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;
 }
@@ -1032,7 +1291,8 @@ function serializeSettings(settings) {
       ...one.title === void 0 ? {} : { title: one.title },
       ...one.width === void 0 ? {} : { width: one.width },
       ...one.flexible === void 0 ? {} : { flexible: one.flexible },
-      ...one.options === void 0 || Object.keys(one.options).length === 0 ? {} : { options: { ...one.options } }
+      ...one.options === void 0 || Object.keys(one.options).length === 0 ? {} : { options: { ...one.options } },
+      ...one.view === void 0 ? {} : { view: one.view }
     };
     if (Object.keys(piece).length > 0) out[key] = piece;
   }
@@ -1124,12 +1384,18 @@ function optionValuesFromLayout(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) {
@@ -1155,7 +1421,8 @@ function clearWidgetSettings(layout, key) {
     title: void 0,
     width: void 0,
     flexible: void 0,
-    options: void 0
+    options: void 0,
+    view: void 0
   });
 }
 function normalizeTitle(title) {
@@ -1215,7 +1482,8 @@ function normalizeSettings(definitions, layout, options = {}) {
       ...title === void 0 ? {} : { title },
       ...one.width === void 0 ? {} : { width: Math.min(range.max, Math.max(range.min, one.width)) },
       ...one.flexible === void 0 ? {} : { flexible: one.flexible },
-      ...Object.keys(chosen).length === 0 ? {} : { options: chosen }
+      ...Object.keys(chosen).length === 0 ? {} : { options: chosen },
+      ...one.view !== void 0 && (one.view === BASE_VIEW_KEY || findView(definition, one.view) !== void 0) ? { view: one.view } : {}
     };
     if (Object.keys(next).length > 0) {
       cleaned[definition.key] = sameSettings(one, next) ? one : next;
@@ -2088,6 +2356,137 @@ function checkOptions(options, kind, problems) {
     );
   });
 }
+var MAX_VIEW_COLUMN = 1e3;
+function checkColumnIndex(value, path, problems) {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > MAX_VIEW_COLUMN) {
+    problems.push(
+      `${path} must be a column index (a whole number from 0), got ${typeof value === "number" ? String(value) : describeType2(value)}.`
+    );
+  }
+}
+function checkConversion(conversion, path, baseKind, viewKind2, problems) {
+  if (!isRecord2(conversion)) {
+    problems.push(
+      `${path} must be an object with a type, got ${describeType2(conversion)}.`
+    );
+    return;
+  }
+  const type = conversion["type"];
+  const known = typeof type === "string" && Object.hasOwn(VIEW_CONVERSIONS, type) ? VIEW_CONVERSIONS[type] : void 0;
+  if (known === void 0) {
+    problems.push(
+      `${path}.type must be one of ${Object.keys(VIEW_CONVERSIONS).map((name) => `"${name}"`).join(", ")}, got ${describeType2(type)}.`
+    );
+    return;
+  }
+  if (baseKind !== known.from) {
+    problems.push(
+      `${path}.type "${String(type)}" reads a ${known.from} widget, but this one is ${String(baseKind)}.`
+    );
+  }
+  if (viewKind2 !== known.to) {
+    problems.push(
+      `${path}.type "${String(type)}" produces ${known.to}, but the view's kind is ${String(viewKind2)}.`
+    );
+  }
+  switch (type) {
+    case "tableToBarList":
+      checkColumnIndex(conversion["label"], `${path}.label`, problems);
+      checkColumnIndex(conversion["value"], `${path}.value`, problems);
+      break;
+    case "tableToGraph": {
+      checkColumnIndex(conversion["label"], `${path}.label`, problems);
+      const values = conversion["values"];
+      if (!Array.isArray(values) || values.length === 0) {
+        problems.push(`${path}.values must list 1 or more column indexes.`);
+      } else if (values.length > MAX_GRAPH_SERIES) {
+        problems.push(
+          `${path}.values lists ${values.length} series; a chart carries at most ${MAX_GRAPH_SERIES}.`
+        );
+      } else {
+        values.forEach(
+          (index, at) => checkColumnIndex(index, `${path}.values[${at}]`, problems)
+        );
+      }
+      if (conversion["chartType"] !== "bar" && conversion["chartType"] !== "line") {
+        problems.push(`${path}.chartType must be "bar" or "line".`);
+      }
+      break;
+    }
+    case "barListToGraph":
+      if (conversion["chartType"] !== "bar" && conversion["chartType"] !== "line") {
+        problems.push(`${path}.chartType must be "bar" or "line".`);
+      }
+      break;
+  }
+  if (conversion["valueFormat"] !== void 0 && !VALUE_FORMATS.includes(conversion["valueFormat"])) {
+    problems.push(
+      `${path}.valueFormat must be one of ${VALUE_FORMATS.map((f) => `"${f}"`).join(", ")}.`
+    );
+  }
+}
+function checkViews(value, problems) {
+  const views = value["views"];
+  const defaultView = value["defaultView"];
+  optionalString(value, "baseViewLabel", "", problems);
+  if (value["baseViewLabel"] === "") {
+    problems.push("baseViewLabel must not be empty.");
+  }
+  const declared = /* @__PURE__ */ new Set([BASE_VIEW_KEY]);
+  if (views !== void 0) {
+    if (!Array.isArray(views)) {
+      problems.push(`views must be an array, got ${describeType2(views)}.`);
+    } else if (views.length > MAX_WIDGET_VIEWS) {
+      problems.push(
+        `views lists ${views.length} views; the most a widget may declare is ${MAX_WIDGET_VIEWS}.`
+      );
+    } else {
+      views.forEach((view, index) => {
+        const path = `views[${index}]`;
+        if (!isRecord2(view)) {
+          problems.push(
+            `${path} must be an object, got ${describeType2(view)}.`
+          );
+          return;
+        }
+        const key = view["key"];
+        if (typeof key !== "string" || key.trim() === "") {
+          problems.push(`${path}.key must be a non-empty string.`);
+        } else if (declared.has(key)) {
+          problems.push(
+            key === BASE_VIEW_KEY ? `${path}.key "${BASE_VIEW_KEY}" is reserved for the widget's own kind.` : `${path}.key "${key}" is used twice.`
+          );
+        } else {
+          declared.add(key);
+        }
+        if (typeof view["label"] !== "string" || view["label"].trim() === "") {
+          problems.push(`${path}.label must be a non-empty string.`);
+        }
+        requireOneOf(view, "kind", WIDGET_KINDS, path, problems);
+        if (view["convert"] === void 0) {
+          problems.push(
+            `${path}.convert is required: views supplied by a provider are not supported yet.`
+          );
+        } else {
+          checkConversion(
+            view["convert"],
+            `${path}.convert`,
+            value["kind"],
+            view["kind"],
+            problems
+          );
+        }
+      });
+    }
+  }
+  if (defaultView !== void 0) {
+    if (typeof defaultView !== "string" || !declared.has(defaultView)) {
+      problems.push(
+        `defaultView must be "${BASE_VIEW_KEY}" or the key of a declared view, got ${typeof defaultView === "string" ? JSON.stringify(defaultView) : describeType2(defaultView)}.`
+      );
+    }
+  }
+}
 function formatProblems(prefix, problems) {
   const shown = problems.slice(0, MAX_REPORTED_PROBLEMS);
   const more = problems.length - shown.length;
@@ -2164,6 +2563,7 @@ function validateWidgetDefinition(value) {
   checkTableControlsOption(value["tableControls"], value["kind"], problems);
   checkLockedOption(value["locked"], problems);
   checkOptions(value["options"], value["kind"], problems);
+  checkViews(value, problems);
   if (value["page"] !== void 0) {
     if (typeof value["page"] !== "string" || value["page"].trim() === "") {
       problems.push(
@@ -3798,6 +4198,7 @@ function indent(block) {
   return block.split("\n").map((line) => `  ${line}`).join("\n");
 }
 
+exports.BASE_VIEW_KEY = BASE_VIEW_KEY;
 exports.DATE_RANGE_PRESETS = DATE_RANGE_PRESETS;
 exports.DEFAULT_COMPARISON_LABEL = DEFAULT_COMPARISON_LABEL;
 exports.DEFAULT_CURRENCY = DEFAULT_CURRENCY;
@@ -3819,11 +4220,13 @@ exports.MAX_REPORTED_PROBLEMS = MAX_REPORTED_PROBLEMS;
 exports.MAX_TEXT_OPTION_LENGTH = MAX_TEXT_OPTION_LENGTH;
 exports.MAX_WIDGET_OPTIONS = MAX_WIDGET_OPTIONS;
 exports.MAX_WIDGET_TITLE_LENGTH = MAX_WIDGET_TITLE_LENGTH;
+exports.MAX_WIDGET_VIEWS = MAX_WIDGET_VIEWS;
 exports.MAX_WIDGET_WIDTH = MAX_WIDGET_WIDTH;
 exports.MIN_WIDGET_WIDTH = MIN_WIDGET_WIDTH;
 exports.OPTION_KEY_PATTERN = OPTION_KEY_PATTERN;
 exports.THEME_TOKEN_VARIABLES = THEME_TOKEN_VARIABLES;
 exports.VALUE_FORMATS = VALUE_FORMATS;
+exports.VIEW_CONVERSIONS = VIEW_CONVERSIONS;
 exports.WIDGET_FILLS = WIDGET_FILLS;
 exports.WIDGET_KINDS = WIDGET_KINDS;
 exports.WIDGET_OPTION_TYPES = WIDGET_OPTION_TYPES;
@@ -3832,11 +4235,13 @@ exports.WIDTH_COLUMNS = WIDTH_COLUMNS;
 exports.addPage = addPage;
 exports.applyClientOptions = applyClientOptions;
 exports.applySettings = applySettings;
+exports.applyView = applyView;
 exports.assignPages = assignPages;
 exports.baseColumnSpan = baseColumnSpan;
 exports.cacheKeyFor = cacheKeyFor;
 exports.clearWidgetSettings = clearWidgetSettings;
 exports.coerceOptionValue = coerceOptionValue;
+exports.convertView = convertView;
 exports.createLayoutPersistence = createLayoutPersistence;
 exports.createTheme = createTheme;
 exports.createWidgetLoader = createWidgetLoader;
@@ -3846,6 +4251,7 @@ exports.defineWidget = defineWidget;
 exports.deriveDetailData = deriveDetailData;
 exports.describeUnknownError = describeUnknownError;
 exports.effectiveDefinitions = effectiveDefinitions;
+exports.effectiveViewKey = effectiveViewKey;
 exports.emptyTextFor = emptyTextFor;
 exports.emptyWidget = emptyWidget;
 exports.enforceLocks = enforceLocks;
@@ -3856,12 +4262,14 @@ exports.fillWidthSpans = fillWidthSpans;
 exports.fillsHeight = fillsHeight;
 exports.fillsWidth = fillsWidth;
 exports.finalizeWidget = finalizeWidget;
+exports.findView = findView;
 exports.fitCount = fitCount;
 exports.formatCount = formatCount;
 exports.formatPercentChange = formatPercentChange;
 exports.formatValue = formatValue;
 exports.fromLegacyDefinition = fromLegacyDefinition;
 exports.hasPages = hasPages;
+exports.hasViews = hasViews;
 exports.hiddenWidgets = hiddenWidgets;
 exports.hideWidget = hideWidget;
 exports.isClientApplied = isClientApplied;
@@ -3879,6 +4287,7 @@ exports.isWidgetKind = isWidgetKind;
 exports.isWidgetVisibleTo = isWidgetVisibleTo;
 exports.isWidgetWidth = isWidgetWidth;
 exports.itemWidth = itemWidth;
+exports.kindLabel = kindLabel;
 exports.kpiDelta = kpiDelta;
 exports.labelStride = labelStride;
 exports.loadingWidgets = loadingWidgets;
@@ -3945,6 +4354,9 @@ exports.utf8Length = utf8Length;
 exports.validateDetailData = validateDetailData;
 exports.validateWidgetData = validateWidgetData;
 exports.validateWidgetDefinition = validateWidgetDefinition;
+exports.viewChoices = viewChoices;
+exports.viewKind = viewKind;
+exports.viewNote = viewNote;
 exports.visibleWidgets = visibleWidgets;
 exports.widgetOptionValues = widgetOptionValues;
 exports.widgetsFor = widgetsFor;