@richardmcquiston01/dashboard-widgets-toolkit 0.6.0 → 0.8.0

package/dist/react.d.cts

@@ -1,5 +1,5 @@
 import { ReactNode, 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, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, h as TextWidgetData, i as WidgetData, j as ResolveOptions, k as WidgetContext, l as WidgetProviders } from './scale-D51ZGIF4.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, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, h as TextWidgetData, i as WidgetData, j as ResolveOptions, k as WidgetContext, l as WidgetProviders } from './scale-CrXxawQn.cjs';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -230,6 +230,13 @@ interface DashboardProps extends WidgetSettings {
      * restore; persist it. Without it the layout is read-only (no controls).
      */
     readonly onLayoutChange?: (layout: DashboardLayout) => void;
+    /**
+     * Ignore widget `locked` settings, so locked widgets can be moved, hidden
+     * and minimized. For administrators editing the default layout: pass it
+     * only for roles you trust, and enforce locks again on the server for
+     * everyone else (`enforceLocks`). It never changes the locks themselves.
+     */
+    readonly overrideLocks?: boolean;
     readonly onRetry?: (key: string) => void;
     /**
      * Loads the full data for a widget's detail view (widgets whose definition

package/dist/react.d.ts

@@ -1,5 +1,5 @@
 import { ReactNode, 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, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, h as TextWidgetData, i as WidgetData, j as ResolveOptions, k as WidgetContext, l as WidgetProviders } from './scale-D51ZGIF4.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, L as Locale, f as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, g as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, R as ResolvedTableControls, h as TextWidgetData, i as WidgetData, j as ResolveOptions, k as WidgetContext, l as WidgetProviders } from './scale-CrXxawQn.js';
 
 interface WidgetCardProps {
     readonly title: string;
@@ -230,6 +230,13 @@ interface DashboardProps extends WidgetSettings {
      * restore; persist it. Without it the layout is read-only (no controls).
      */
     readonly onLayoutChange?: (layout: DashboardLayout) => void;
+    /**
+     * Ignore widget `locked` settings, so locked widgets can be moved, hidden
+     * and minimized. For administrators editing the default layout: pass it
+     * only for roles you trust, and enforce locks again on the server for
+     * everyone else (`enforceLocks`). It never changes the locks themselves.
+     */
+    readonly overrideLocks?: boolean;
     readonly onRetry?: (key: string) => void;
     /**
      * Loads the full data for a widget's detail view (widgets whose definition

package/dist/react.js

@@ -1568,6 +1568,45 @@ function ResolvedWidgetCard({
   );
 }
 
+// src/core/definition.ts
+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 sortDefinitions(definitions) {
+  return definitions.map((definition, index) => ({ definition, index })).sort(
+    (a, b) => (a.definition.sortOrder ?? 0) - (b.definition.sortOrder ?? 0) || a.index - b.index
+  ).map(({ definition }) => definition);
+}
+function isWidgetVisibleTo(definition, roles) {
+  if (definition.active === false) {
+    return false;
+  }
+  if (definition.roles === void 0 || definition.roles.length === 0) {
+    return true;
+  }
+  if (roles === void 0) {
+    return false;
+  }
+  return definition.roles.some((role) => roles.includes(role));
+}
+
 // src/core/layout.ts
 var EMPTY_LAYOUT = Object.freeze({
   order: Object.freeze([]),
@@ -1579,9 +1618,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) {
@@ -1596,34 +1636,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 isHidden(layout, key) {
   return layout.hidden.includes(key);
@@ -1654,6 +1722,23 @@ function restoreWidget(layout, key) {
 function toggleMinimized(layout, key) {
   return isMinimized(layout, key) ? restoreWidget(layout, key) : minimizeWidget(layout, key);
 }
+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 };
+}
 function nextSort(current, column) {
   if (current?.column !== column) return { column, direction: "asc" };
   return current.direction === "asc" ? { column, direction: "desc" } : void 0;
@@ -2052,10 +2137,17 @@ function DetailHost({
     }
   ) });
 }
+function withoutLock(definition) {
+  if (definition.locked === void 0) return definition;
+  const copy = { ...definition };
+  delete copy.locked;
+  return copy;
+}
 function DashboardInner({
   widgets,
-  layout = EMPTY_LAYOUT,
+  layout: savedLayout = EMPTY_LAYOUT,
   onLayoutChange,
+  overrideLocks = false,
   onRetry,
   loadDetail,
   onOpenDetail,
@@ -2064,7 +2156,10 @@ function DashboardInner({
 }) {
   const slot = useSlotClassName();
   const { labels } = useWidgetSettings();
-  const definitions = widgets.map((w) => w.definition);
+  const definitions = widgets.map(
+    (w) => overrideLocks ? withoutLock(w.definition) : w.definition
+  );
+  const layout = enforceLocks(definitions, savedLayout);
   const byKey = new Map(
     widgets.map((w) => [w.definition.key, w])
   );
@@ -2137,32 +2232,45 @@ function DashboardInner({
           if (widget === void 0) return null;
           const key = definition.key;
           const title = definition.title;
+          const lock = resolveWidgetLock(definition);
+          const canMoveEarlier = !lock.move && moveWidgetBy(definitions, layout, key, -1) !== layout;
+          const canMoveLater = !lock.move && moveWidgetBy(definitions, layout, key, 1) !== layout;
           const actions = editable ? /* @__PURE__ */ jsxs(Fragment, { children: [
-            /* @__PURE__ */ jsx(
-              "button",
-              {
-                type: "button",
-                className: slot("button", "dwt-button", "dwt-icon-button"),
-                "aria-label": labels.moveEarlier(title),
-                title: labels.moveEarlier(title),
-                disabled: index === 0,
-                onClick: () => change(moveWidgetBy(definitions, layout, key, -1)),
-                children: /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\u2191" })
-              }
-            ),
-            /* @__PURE__ */ jsx(
-              "button",
-              {
-                type: "button",
-                className: slot("button", "dwt-button", "dwt-icon-button"),
-                "aria-label": labels.moveLater(title),
-                title: labels.moveLater(title),
-                disabled: index === shown.length - 1,
-                onClick: () => change(moveWidgetBy(definitions, layout, key, 1)),
-                children: /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\u2193" })
-              }
-            ),
-            /* @__PURE__ */ jsx(
+            !lock.move && /* @__PURE__ */ jsxs(Fragment, { children: [
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  className: slot(
+                    "button",
+                    "dwt-button",
+                    "dwt-icon-button"
+                  ),
+                  "aria-label": labels.moveEarlier(title),
+                  title: labels.moveEarlier(title),
+                  disabled: index === 0 || !canMoveEarlier,
+                  onClick: () => change(moveWidgetBy(definitions, layout, key, -1)),
+                  children: /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\u2191" })
+                }
+              ),
+              /* @__PURE__ */ jsx(
+                "button",
+                {
+                  type: "button",
+                  className: slot(
+                    "button",
+                    "dwt-button",
+                    "dwt-icon-button"
+                  ),
+                  "aria-label": labels.moveLater(title),
+                  title: labels.moveLater(title),
+                  disabled: index === shown.length - 1 || !canMoveLater,
+                  onClick: () => change(moveWidgetBy(definitions, layout, key, 1)),
+                  children: /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\u2193" })
+                }
+              )
+            ] }),
+            !lock.hide && /* @__PURE__ */ jsx(
               "button",
               {
                 type: "button",
@@ -2186,7 +2294,7 @@ function DashboardInner({
               ...widthProps(twelve, definition),
               minimized: isMinimized(layout, key),
               ...actions === void 0 ? {} : { actions },
-              ...editable ? {
+              ...editable && !lock.minimize ? {
                 onToggleMinimized: () => change(toggleMinimized(layout, key))
               } : {},
               ...headingLevel === void 0 ? {} : { headingLevel },
@@ -2230,25 +2338,6 @@ function Dashboard({
   );
 }
 
-// src/core/definition.ts
-function sortDefinitions(definitions) {
-  return definitions.map((definition, index) => ({ definition, index })).sort(
-    (a, b) => (a.definition.sortOrder ?? 0) - (b.definition.sortOrder ?? 0) || a.index - b.index
-  ).map(({ definition }) => definition);
-}
-function isWidgetVisibleTo(definition, roles) {
-  if (definition.active === false) {
-    return false;
-  }
-  if (definition.roles === void 0 || definition.roles.length === 0) {
-    return true;
-  }
-  if (roles === void 0) {
-    return false;
-  }
-  return definition.roles.some((role) => roles.includes(role));
-}
-
 // src/core/payload.ts
 var WIDGET_KINDS = [
   "TEXT",
@@ -2330,6 +2419,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") {
@@ -2433,6 +2530,7 @@ function checkPayloadFields(kind, data, problems) {
           }
           eachRecord(row, rowPath, problems, (cell, cellPath) => {
             requireString(cell, "text", cellPath, problems);
+            optionalSortValue(cell, cellPath, problems);
             optionalUrl(
               cell,
               "href",