@richardmcquiston01/dashboard-widgets-toolkit 0.6.0 → 0.8.0

package/README.md

@@ -31,7 +31,7 @@ The widget kinds:
 | `TEXT`       | `value: string`, `label`                                                                                 | A count or status as text                  |
 | `KPI`        | `value: number`, `previous?: number \| null`, `format`, `currency?`, `label`, `hint?`, `higherIsBetter?` | Stat tile with a change vs previous period |
 | `GAUGE`      | `value`, `max`, `label`                                                                                  | A meter (unread of total, quota used)      |
-| `TABLE`      | `columns: {label, numeric?}[]`, `rows: {text, href?}[][]`, `footer?`                                     | Small data tables                          |
+| `TABLE`      | `columns: {label, numeric?}[]`, `rows: {text, href?, value?}[][]`, `footer?`                             | Small data tables                          |
 | `BAR_LIST`   | `items: {label, value, display?}[]`, `total?`                                                            | Ratings breakdown, purchases by country    |
 | `ALERT_LIST` | `items: {title, href?, thumbnailUrl?, valueLabel, detail?}[]`, `total`, `emptyText`                      | Low stock, stale listings, expiring soon   |
 | `GRAPH`      | `series: {name, points: {label, value}[]}[]`, `chartType: 'bar' \| 'line'`, `valueFormat`, `currency?`, `xLabel?` | Revenue by month, views per day |
@@ -41,6 +41,11 @@ in major units (12.5 is $12.50) and percents are fractions (0.25 is 25%). Any
 widget may instead return an empty state, `{ empty: true, text: 'No orders
 synced yet.' }`.
 
+A `TABLE` cell's optional `value` (a string or number) is what the card's
+table controls (`tableControls` on the definition) and the detail view sort
+and search on, when `text` is formatted for reading: a timestamp behind
+"3 days ago", a rating behind stars, an amount behind "$1,234.00".
+
 ## Getting Started
 
 See [GETTING_STARTED.md](./GETTING_STARTED.md)

package/dist/core.cjs

@@ -86,6 +86,26 @@ function fromLegacyDefinition(legacy) {
 // src/core/definition.ts
 var WIDGET_SIZES = ["small", "medium", "large", "full"];
 var WIDGET_FILLS = ["height", "width", "both"];
+var NOT_LOCKED = Object.freeze({
+  move: false,
+  hide: false,
+  minimize: false
+});
+var FULLY_LOCKED = Object.freeze({
+  move: true,
+  hide: true,
+  minimize: true
+});
+function resolveWidgetLock(definition) {
+  const setting = definition.locked;
+  if (setting === true) return FULLY_LOCKED;
+  if (setting === void 0 || setting === false) return NOT_LOCKED;
+  return {
+    move: setting.move === true,
+    hide: setting.hide === true,
+    minimize: setting.minimize === true
+  };
+}
 function defineWidget(definition) {
   return definition;
 }
@@ -689,9 +709,10 @@ function bySortOrder(items) {
     (a, b) => (a.item.sortOrder ?? 0) - (b.item.sortOrder ?? 0) || a.index - b.index
   ).map(({ item }) => item);
 }
-function visibleWidgets(definitions, layout) {
-  const hidden = new Set(layout.hidden);
-  const visible = definitions.filter((d) => !hidden.has(d.key));
+function isPinned(item) {
+  return resolveWidgetLock(item).move;
+}
+function viewerOrder(visible, layout) {
   const byKey = new Map(visible.map((d) => [d.key, d]));
   const ordered = [];
   for (const key of layout.order) {
@@ -706,34 +727,62 @@ function visibleWidgets(definitions, layout) {
   }
   return ordered;
 }
+function placeAroundPinned(visible, free) {
+  const slots = bySortOrder(visible).map(
+    (item) => isPinned(item) ? item : void 0
+  );
+  let next = 0;
+  return slots.map((pinned) => pinned ?? free[next++]);
+}
+function visibleWidgets(definitions, layout) {
+  const hidden = new Set(layout.hidden);
+  const visible = definitions.filter((d) => !hidden.has(d.key));
+  const ordered = viewerOrder(visible, layout);
+  if (!visible.some(isPinned)) return ordered;
+  return placeAroundPinned(
+    visible,
+    ordered.filter((item) => !isPinned(item))
+  );
+}
 function hiddenWidgets(definitions, layout) {
   const hidden = new Set(layout.hidden);
   return bySortOrder(definitions.filter((d) => hidden.has(d.key)));
 }
 function moveWidget(definitions, layout, key, toIndex) {
-  const current = visibleWidgets(definitions, layout).map(
-    (d) => d.key
-  );
-  const fromIndex = current.indexOf(key);
-  if (fromIndex === -1 || !Number.isInteger(toIndex) || toIndex < 0 || toIndex >= current.length || toIndex === fromIndex) {
+  const current = visibleWidgets(definitions, layout);
+  const fromIndex = current.findIndex((d) => d.key === key);
+  const mover = current[fromIndex];
+  if (mover === void 0 || !Number.isInteger(toIndex) || toIndex < 0 || toIndex >= current.length || toIndex === fromIndex || isPinned(mover) || isPinned(current[toIndex])) {
     return layout;
   }
-  const next = [...current];
-  next.splice(fromIndex, 1);
-  next.splice(toIndex, 0, key);
-  return { ...layout, order: next };
+  const freeSlots = freeSlotIndexes(current);
+  const free = current.filter((item) => !isPinned(item));
+  const fromFree = freeSlots.indexOf(fromIndex);
+  const toFree = freeSlots.indexOf(toIndex);
+  free.splice(fromFree, 1);
+  free.splice(toFree, 0, mover);
+  const next = placeAroundPinned(current, free);
+  return { ...layout, order: next.map((d) => d.key) };
+}
+function freeSlotIndexes(ordered) {
+  const slots = [];
+  ordered.forEach((item, index) => {
+    if (!isPinned(item)) slots.push(index);
+  });
+  return slots;
 }
 function moveWidgetBy(definitions, layout, key, offset) {
-  const current = visibleWidgets(definitions, layout).map(
-    (d) => d.key
-  );
-  const fromIndex = current.indexOf(key);
+  const current = visibleWidgets(definitions, layout);
+  const fromIndex = current.findIndex((d) => d.key === key);
   if (fromIndex === -1) return layout;
-  const toIndex = Math.max(
+  const freeSlots = freeSlotIndexes(current);
+  const fromFree = freeSlots.indexOf(fromIndex);
+  if (fromFree === -1) return layout;
+  const toFree = Math.max(
     0,
-    Math.min(current.length - 1, fromIndex + Math.trunc(offset))
+    Math.min(freeSlots.length - 1, fromFree + Math.trunc(offset))
   );
-  return moveWidget(definitions, layout, key, toIndex);
+  return moveWidget(definitions, layout, key, freeSlots[toFree]);
 }
 function moveWidgetUp(definitions, layout, key) {
   return moveWidgetBy(definitions, layout, key, -1);
@@ -783,6 +832,23 @@ function pruneLayout(definitions, layout) {
   };
   return next.order.length === layout.order.length && next.hidden.length === layout.hidden.length && next.minimized.length === layout.minimized.length ? layout : next;
 }
+function enforceLocks(definitions, layout, options = {}) {
+  if (options.overrideLocks === true) return layout;
+  const noMove = /* @__PURE__ */ new Set();
+  const noHide = /* @__PURE__ */ new Set();
+  const noMinimize = /* @__PURE__ */ new Set();
+  for (const definition of definitions) {
+    const lock = resolveWidgetLock(definition);
+    if (lock.move) noMove.add(definition.key);
+    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 };
+}
 
 // src/core/validate.ts
 var MAX_REPORTED_PROBLEMS = 10;
@@ -826,6 +892,14 @@ function optionalNumber(record, field, path, problems) {
     requireNumber(record, field, path, problems);
   }
 }
+function optionalSortValue(record, path, problems) {
+  const value = record["value"];
+  if (value !== void 0 && typeof value !== "string" && !(typeof value === "number" && Number.isFinite(value))) {
+    problems.push(
+      `${path}.value must be a string or a finite number, got ${describeType2(value)}.`
+    );
+  }
+}
 function optionalBoolean(record, field, path, problems) {
   const value = record[field];
   if (value !== void 0 && typeof value !== "boolean") {
@@ -929,6 +1003,7 @@ function checkPayloadFields(kind, data, problems) {
           }
           eachRecord(row, rowPath, problems, (cell, cellPath) => {
             requireString(cell, "text", cellPath, problems);
+            optionalSortValue(cell, cellPath, problems);
             optionalUrl(
               cell,
               "href",
@@ -1051,6 +1126,18 @@ function checkTableControlsOption(controls, kind, problems) {
     );
   }
 }
+function checkLockedOption(locked, problems) {
+  if (locked === void 0 || typeof locked === "boolean") return;
+  if (!isRecord(locked)) {
+    problems.push(
+      `locked must be true, false or an object, got ${describeType2(locked)}.`
+    );
+    return;
+  }
+  optionalBoolean(locked, "move", "locked", problems);
+  optionalBoolean(locked, "hide", "locked", problems);
+  optionalBoolean(locked, "minimize", "locked", problems);
+}
 function formatProblems(prefix, problems) {
   const shown = problems.slice(0, MAX_REPORTED_PROBLEMS);
   const more = problems.length - shown.length;
@@ -1124,6 +1211,7 @@ function validateWidgetDefinition(value) {
   }
   checkDetailOption(value["detail"], problems);
   checkTableControlsOption(value["tableControls"], value["kind"], problems);
+  checkLockedOption(value["locked"], problems);
   if (value["fill"] !== void 0) {
     requireOneOf(value, "fill", WIDGET_FILLS, "", problems);
   }
@@ -1432,6 +1520,7 @@ exports.deriveDetailData = deriveDetailData;
 exports.describeUnknownError = describeUnknownError;
 exports.emptyTextFor = emptyTextFor;
 exports.emptyWidget = emptyWidget;
+exports.enforceLocks = enforceLocks;
 exports.err = err;
 exports.failedWidget = failedWidget;
 exports.fillColumnSpans = fillColumnSpans;
@@ -1473,6 +1562,7 @@ exports.resolveDetailOptions = resolveDetailOptions;
 exports.resolvePayload = resolvePayload;
 exports.resolveTableControls = resolveTableControls;
 exports.resolveWidget = resolveWidget;
+exports.resolveWidgetLock = resolveWidgetLock;
 exports.resolveWidgets = resolveWidgets;
 exports.restoreWidget = restoreWidget;
 exports.serializeDetailQuery = serializeDetailQuery;