@richardmcquiston01/dashboard-widgets-toolkit 0.2.0 → 0.4.0

package/dist/react.cjs

@@ -6,6 +6,30 @@ var jsxRuntime = require('react/jsx-runtime');
 // src/react/card.tsx
 
 // src/core/grid.ts
+var WIDTH_COLUMNS = 12;
+var MIN_WIDGET_WIDTH = 2;
+var MAX_WIDGET_WIDTH = 12;
+function isWidgetWidth(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= MIN_WIDGET_WIDTH && value <= MAX_WIDGET_WIDTH;
+}
+function widthForSize(size) {
+  switch (size) {
+    case "small":
+      return 3;
+    case "large":
+      return 6;
+    case "full":
+      return 12;
+    default:
+      return 4;
+  }
+}
+function itemWidth(item) {
+  return isWidgetWidth(item.width) ? item.width : widthForSize(item.defaultSize);
+}
+function usesWidthColumns(items) {
+  return items.some((item) => item.width !== void 0);
+}
 function fillsWidth(fill) {
   return fill === "width" || fill === "both";
 }
@@ -18,6 +42,16 @@ function baseColumnSpan(size, columns, largeSpan = 2) {
   return 1;
 }
 function fillColumnSpans(items, columns, largeSpan = 2) {
+  return placeAndFill(
+    items,
+    columns,
+    (item, trackCount) => baseColumnSpan(item.defaultSize, trackCount, largeSpan)
+  );
+}
+function fillWidthSpans(items) {
+  return placeAndFill(items, WIDTH_COLUMNS, itemWidth);
+}
+function placeAndFill(items, columns, spanOf) {
   const trackCount = Math.max(1, Math.floor(columns));
   const spans = /* @__PURE__ */ new Map();
   let row = [];
@@ -36,11 +70,7 @@ function fillColumnSpans(items, columns, largeSpan = 2) {
     used = 0;
   }
   for (const item of items) {
-    const span = baseColumnSpan(
-      item.defaultSize,
-      trackCount,
-      largeSpan
-    );
+    const span = Math.min(spanOf(item, trackCount), trackCount);
     if (used + span > trackCount && row.length > 0) closeRow();
     row.push({ item, span });
     used += span;
@@ -192,11 +222,24 @@ var DEFAULT_LABELS = {
   viewAsTable: "View as table",
   hide: (title) => `Hide ${title}`,
   show: (title) => `Show ${title}`,
-  minimize: (title) => `Minimise ${title}`,
+  minimize: (title) => `Minimize ${title}`,
   expand: (title) => `Expand ${title}`,
   moveEarlier: (title) => `Move ${title} earlier`,
   moveLater: (title) => `Move ${title} later`,
   hiddenWidgets: "Hidden:",
+  minimizedWidgets: "Minimized:",
+  opensInNewTab: "(opens in a new tab)",
+  view: (title) => `View ${title}`,
+  close: "Close",
+  search: "Search",
+  filterBy: (column) => `Filter ${column}`,
+  sortBy: (column) => `Sort by ${column}`,
+  noResults: "No matching results.",
+  showingRows: (from, to, total) => `Showing ${from}\u2013${to} of ${total} results`,
+  previousPage: "Previous",
+  nextPage: "Next",
+  pageOf: (page, pageCount) => `Page ${page} of ${pageCount}`,
+  pagination: "Pagination",
   allHidden: "Every widget is hidden. Show one from the list above.",
   noWidgets: "No widgets to show.",
   andMore: (count) => `and ${count} more`,
@@ -711,16 +754,50 @@ function isSafeImageUrl(url) {
   const scheme = schemeOf(url);
   return scheme === null || scheme === "http" || scheme === "https";
 }
+function isNewTabTarget(target) {
+  return target !== void 0 && target !== "" && target !== "_self";
+}
 function WidgetLink({
   href,
   className,
   children
 }) {
-  const { linkTarget } = useWidgetSettings();
+  const { linkTarget, labels } = useWidgetSettings();
   if (href === void 0 || !isSafeHref(href)) {
     return /* @__PURE__ */ jsxRuntime.jsx("span", { className, children });
   }
-  return /* @__PURE__ */ jsxRuntime.jsx("a", { href, target: linkTarget, rel: "noreferrer", className, children });
+  const opensNewTab = isNewTabTarget(linkTarget);
+  return /* @__PURE__ */ jsxRuntime.jsxs("a", { href, target: linkTarget, rel: "noreferrer", className, children: [
+    children,
+    opensNewTab && /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+      /* @__PURE__ */ jsxRuntime.jsx(
+        "svg",
+        {
+          className: "dwt-external-icon",
+          viewBox: "0 0 12 12",
+          width: "1em",
+          height: "1em",
+          "aria-hidden": "true",
+          focusable: "false",
+          children: /* @__PURE__ */ jsxRuntime.jsx(
+            "path",
+            {
+              d: "M7 1h4v4M11 1 5.5 6.5M9 7.5V10a1 1 0 0 1-1 1H2a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h2.5",
+              fill: "none",
+              stroke: "currentColor",
+              strokeWidth: "1.4",
+              strokeLinecap: "round",
+              strokeLinejoin: "round"
+            }
+          )
+        }
+      ),
+      /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "dwt-visually-hidden", children: [
+        " ",
+        labels.opensInNewTab
+      ] })
+    ] })
+  ] });
 }
 function Thumbnail({
   url
@@ -942,6 +1019,7 @@ function WidgetCard({
   actions,
   minimized = false,
   onToggleMinimized,
+  onView,
   status = "ok",
   emptyText,
   error,
@@ -950,6 +1028,8 @@ function WidgetCard({
   size,
   fill,
   columnSpan,
+  width,
+  widgetKey,
   headingLevel = 2,
   className,
   children
@@ -999,7 +1079,13 @@ function WidgetCard({
         fillsWidth(fill) && "dwt-card--fill-width",
         className
       ),
-      ...columnSpan === void 0 ? {} : { style: { gridColumn: `span ${columnSpan}` } },
+      ...widgetKey === void 0 ? {} : { "data-widget-key": widgetKey },
+      ...columnSpan === void 0 && width === void 0 ? {} : {
+        style: {
+          ...width === void 0 ? {} : { "--dwt-width": width },
+          ...columnSpan === void 0 ? {} : { gridColumn: `span ${columnSpan}` }
+        }
+      },
       children: [
         /* @__PURE__ */ jsxRuntime.jsxs("header", { className: slot("cardHeader", "dwt-card-header"), children: [
           /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "dwt-card-heading", children: [
@@ -1008,12 +1094,54 @@ function WidgetCard({
               {
                 id: `${id}-title`,
                 className: slot("cardTitle", "dwt-card-title"),
-                children: title
+                children: onView === void 0 ? title : /* @__PURE__ */ jsxRuntime.jsx(
+                  "button",
+                  {
+                    type: "button",
+                    tabIndex: -1,
+                    className: "dwt-card-title-button",
+                    onClick: onView,
+                    children: title
+                  }
+                )
               }
             ),
             description !== void 0 && !minimized && /* @__PURE__ */ jsxRuntime.jsx("p", { className: slot("cardDescription", "dwt-card-description"), children: description })
           ] }),
-          (actions !== void 0 || onToggleMinimized !== void 0) && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: slot("cardActions", "dwt-card-actions"), children: [
+          (actions !== void 0 || onToggleMinimized !== void 0 || onView !== void 0) && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: slot("cardActions", "dwt-card-actions"), children: [
+            onView !== void 0 && /* @__PURE__ */ jsxRuntime.jsx(
+              "button",
+              {
+                type: "button",
+                className: slot("button", "dwt-button", "dwt-icon-button"),
+                "aria-label": labels.view(title),
+                title: labels.view(title),
+                onClick: onView,
+                children: /* @__PURE__ */ jsxRuntime.jsxs(
+                  "svg",
+                  {
+                    viewBox: "0 0 16 16",
+                    width: "16",
+                    height: "16",
+                    "aria-hidden": "true",
+                    focusable: "false",
+                    children: [
+                      /* @__PURE__ */ jsxRuntime.jsx(
+                        "path",
+                        {
+                          d: "M1 8s2.6-4.5 7-4.5S15 8 15 8s-2.6 4.5-7 4.5S1 8 1 8Z",
+                          fill: "none",
+                          stroke: "currentColor",
+                          strokeWidth: "1.4",
+                          strokeLinejoin: "round"
+                        }
+                      ),
+                      /* @__PURE__ */ jsxRuntime.jsx("circle", { cx: "8", cy: "8", r: "2.1", fill: "currentColor" })
+                    ]
+                  }
+                )
+              }
+            ),
             actions,
             onToggleMinimized !== void 0 && /* @__PURE__ */ jsxRuntime.jsx(
               "button",
@@ -1059,6 +1187,7 @@ function ResolvedWidgetCard({
     WidgetCard,
     {
       ...props,
+      widgetKey: definition.key,
       title: widgetTitle(widget),
       status: widget.status,
       ...definition.description === void 0 ? {} : { description: definition.description },
@@ -1157,8 +1286,540 @@ function restoreWidget(layout, key) {
 function toggleMinimized(layout, key) {
   return isMinimized(layout, key) ? restoreWidget(layout, key) : minimizeWidget(layout, key);
 }
+
+// src/core/result.ts
+function ok(value) {
+  return { ok: true, value };
+}
+function err(error) {
+  return { ok: false, error };
+}
+function describeUnknownError(cause) {
+  if (cause instanceof Error) {
+    return cause.message === "" ? cause.name : cause.message;
+  }
+  if (typeof cause === "string") {
+    return cause;
+  }
+  try {
+    const json = JSON.stringify(cause);
+    return json ?? String(cause);
+  } catch {
+    return String(cause);
+  }
+}
+
+// src/core/detail.ts
+var DEFAULT_DETAIL_PAGE_SIZE = 25;
+function resolveDetailOptions(definition) {
+  const detail = definition.detail;
+  if (detail === void 0 || detail === false) return void 0;
+  const options = detail === true ? {} : detail;
+  return {
+    title: options.title ?? definition.title,
+    pageSize: options.pageSize ?? DEFAULT_DETAIL_PAGE_SIZE,
+    mode: options.mode ?? "client"
+  };
+}
+function defaultDetailQuery(pageSize = DEFAULT_DETAIL_PAGE_SIZE) {
+  return { page: 1, pageSize };
+}
+function fold(text) {
+  return text.normalize("NFD").replace(/\p{M}/gu, "").toLowerCase();
+}
+function cellValue(cell) {
+  return cell.value ?? cell.text;
+}
+function cellMatches(cell, needle) {
+  return fold(String(cellValue(cell))).includes(needle);
+}
+function compareCells(a, b, collator) {
+  const left = cellValue(a);
+  const right = cellValue(b);
+  if (typeof left === "number" && typeof right === "number") {
+    return left - right;
+  }
+  if (typeof left === "number") return -1;
+  if (typeof right === "number") return 1;
+  return collator.compare(left, right);
+}
+function queryRows(data, query, locale) {
+  const indexOf = new Map(
+    data.columns.map((column, index) => [column.key, index])
+  );
+  const filterEntries = [];
+  for (const [key, text] of Object.entries(query.filters ?? {})) {
+    const index = indexOf.get(key);
+    if (index === void 0) {
+      return err(
+        `Detail query: filter column "${key}" does not exist. Columns: ${listKeys(data)}.`
+      );
+    }
+    const needle = fold(text.trim());
+    if (needle !== "") filterEntries.push({ index, needle });
+  }
+  let sortIndex = -1;
+  if (query.sort !== void 0) {
+    const found = indexOf.get(query.sort.column);
+    const column = found === void 0 ? void 0 : data.columns[found];
+    if (found === void 0 || column === void 0) {
+      return err(
+        `Detail query: sort column "${query.sort.column}" does not exist. Columns: ${listKeys(data)}.`
+      );
+    }
+    if (column.sortable === false) {
+      return err(
+        `Detail query: column "${column.key}" is not sortable (sortable: false).`
+      );
+    }
+    sortIndex = found;
+  }
+  const search = fold((query.search ?? "").trim());
+  let rows = data.rows.filter(
+    (row) => filterEntries.every(({ index, needle }) => {
+      const cell = row[index];
+      return cell !== void 0 && cellMatches(cell, needle);
+    }) && (search === "" || row.some((cell) => cellMatches(cell, search)))
+  );
+  if (query.sort !== void 0 && sortIndex >= 0) {
+    const collator = new Intl.Collator(locale, {
+      numeric: true,
+      sensitivity: "base"
+    });
+    const sign = query.sort.direction === "desc" ? -1 : 1;
+    rows = rows.map((row, position) => ({ row, position })).sort((a, b) => {
+      const left = a.row[sortIndex];
+      const right = b.row[sortIndex];
+      const order = left === void 0 || right === void 0 ? 0 : sign * compareCells(left, right, collator);
+      return order || a.position - b.position;
+    }).map(({ row }) => row);
+  }
+  const pageSize = Math.max(1, Math.floor(query.pageSize));
+  const pageCount = Math.max(1, Math.ceil(rows.length / pageSize));
+  const page = Math.min(Math.max(1, Math.floor(query.page)), pageCount);
+  return ok({
+    rows: rows.slice((page - 1) * pageSize, page * pageSize),
+    totalRows: rows.length,
+    page,
+    pageCount
+  });
+}
+function listKeys(data) {
+  return data.columns.map((column) => `"${column.key}"`).join(", ");
+}
+function describeType(value) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  return typeof value;
+}
+function validateDetailData(data, subject = "Detail data") {
+  const problems = [];
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return err(`${subject}: must be an object, got ${describeType(data)}.`);
+  }
+  const record = data;
+  const columns = record["columns"];
+  const rows = record["rows"];
+  const keys = /* @__PURE__ */ new Set();
+  let columnCount = 0;
+  if (!Array.isArray(columns) || columns.length === 0) {
+    problems.push(
+      `columns must be a non-empty array, got ${describeType(columns)}.`
+    );
+  } else {
+    columnCount = columns.length;
+    columns.forEach((column, index) => {
+      const at = `columns[${index}]`;
+      if (typeof column !== "object" || column === null) {
+        problems.push(`${at} must be an object, got ${describeType(column)}.`);
+        return;
+      }
+      const fields = column;
+      const key = fields["key"];
+      if (typeof key !== "string" || key === "") {
+        problems.push(`${at}.key must be a non-empty string.`);
+      } else if (keys.has(key)) {
+        problems.push(`${at}.key "${key}" is used by an earlier column.`);
+      } else {
+        keys.add(key);
+      }
+      if (typeof fields["label"] !== "string") {
+        problems.push(
+          `${at}.label must be a string, got ${describeType(fields["label"])}.`
+        );
+      }
+      for (const flag of ["numeric", "sortable", "filterable"]) {
+        const flagValue = fields[flag];
+        if (flagValue !== void 0 && typeof flagValue !== "boolean") {
+          problems.push(
+            `${at}.${flag} must be a boolean, got ${describeType(flagValue)}.`
+          );
+        }
+      }
+    });
+  }
+  if (!Array.isArray(rows)) {
+    problems.push(`rows must be an array, got ${describeType(rows)}.`);
+  } else {
+    rows.forEach((row, rowIndex) => {
+      if (!Array.isArray(row)) {
+        problems.push(
+          `rows[${rowIndex}] must be an array of cells, got ${describeType(row)}.`
+        );
+        return;
+      }
+      if (columnCount > 0 && row.length !== columnCount) {
+        problems.push(
+          `rows[${rowIndex}] has ${row.length} cells but there are ${columnCount} columns.`
+        );
+      }
+      row.forEach((cell, cellIndex) => {
+        const at = `rows[${rowIndex}][${cellIndex}]`;
+        if (typeof cell !== "object" || cell === null) {
+          problems.push(`${at} must be an object, got ${describeType(cell)}.`);
+          return;
+        }
+        const fields = cell;
+        if (typeof fields["text"] !== "string") {
+          problems.push(
+            `${at}.text must be a string, got ${describeType(fields["text"])}.`
+          );
+        }
+        const value = fields["value"];
+        if (value !== void 0 && typeof value !== "string" && !(typeof value === "number" && Number.isFinite(value))) {
+          problems.push(
+            `${at}.value must be a string or a finite number, got ${describeType(value)}.`
+          );
+        }
+        const href = fields["href"];
+        if (href !== void 0) {
+          if (typeof href !== "string") {
+            problems.push(
+              `${at}.href must be a string, got ${describeType(href)}.`
+            );
+          } else if (!isSafeHref(href)) {
+            problems.push(
+              `${at}.href "${href}" is not allowed (only http, https, mailto and relative URLs).`
+            );
+          }
+        }
+      });
+    });
+  }
+  const totalRows = record["totalRows"];
+  if (totalRows !== void 0 && !(typeof totalRows === "number" && Number.isInteger(totalRows) && totalRows >= 0)) {
+    problems.push(
+      `totalRows must be a non-negative whole number, got ${describeType(totalRows)}.`
+    );
+  }
+  if (problems.length > 0) {
+    return err(`${subject}: ${problems.join(" ")}`);
+  }
+  return ok(data);
+}
+function deriveDetailData(data, locale) {
+  if (data.kind === "TABLE") {
+    if (data.footer !== void 0) return void 0;
+    return {
+      columns: data.columns.map((column, index) => ({
+        key: `c${index}`,
+        label: column.label,
+        ...column.numeric === void 0 ? {} : { numeric: column.numeric }
+      })),
+      rows: data.rows
+    };
+  }
+  if (data.kind === "BAR_LIST") {
+    return {
+      columns: [
+        { key: "label", label: "Name" },
+        { key: "value", label: "Value", numeric: true }
+      ],
+      rows: data.items.map((item) => [
+        { text: item.label },
+        {
+          text: item.display ?? formatValue(item.value, "number", { locale }),
+          value: item.value
+        }
+      ])
+    };
+  }
+  return void 0;
+}
+function nextSort(current, column) {
+  if (current?.column !== column) return { column, direction: "asc" };
+  return current.direction === "asc" ? { column, direction: "desc" } : void 0;
+}
+function withSort(query, sort) {
+  const { sort: _previous, ...rest } = query;
+  return sort === void 0 ? { ...rest, page: 1 } : { ...rest, sort, page: 1 };
+}
+function SortGlyph({
+  sort,
+  column
+}) {
+  if (sort?.column !== column) return /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: " \u2195" });
+  return /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: sort.direction === "asc" ? " \u2191" : " \u2193" });
+}
+function Cell({
+  cell,
+  column
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsx("td", { className: column?.numeric === true ? "dwt-numeric" : void 0, children: cell.href === void 0 ? cell.text : /* @__PURE__ */ jsxRuntime.jsx(WidgetLink, { href: cell.href, className: "dwt-link", children: cell.text }) });
+}
+function WidgetDetail({
+  title,
+  data,
+  query,
+  onQueryChange,
+  status = "ok",
+  error,
+  onRetry,
+  headingLevel = 2,
+  headingId,
+  className
+}) {
+  const slot = useSlotClassName();
+  const { labels, locale } = useWidgetSettings();
+  const id = react.useId();
+  const Heading = `h${headingLevel}`;
+  const localeTag = typeof locale === "string" ? locale : locale?.[0];
+  let page;
+  let problem;
+  if (status === "ok" && data !== void 0) {
+    const result = queryRows(data, query, localeTag);
+    if (result.ok) page = result.value;
+    else problem = result.error;
+  }
+  function change(patch) {
+    onQueryChange({ ...query, ...patch, page: patch.page ?? 1 });
+  }
+  let body;
+  if (status === "loading") {
+    body = /* @__PURE__ */ jsxRuntime.jsx("p", { role: "status", className: slot("status", "dwt-status"), children: labels.loading });
+  } else if (status === "error" || problem !== void 0) {
+    body = /* @__PURE__ */ jsxRuntime.jsxs("div", { role: "alert", className: slot("error", "dwt-error"), children: [
+      /* @__PURE__ */ jsxRuntime.jsx("p", { className: "dwt-error-message", children: error ?? problem ?? "" }),
+      onRetry !== void 0 && /* @__PURE__ */ jsxRuntime.jsx(
+        "button",
+        {
+          type: "button",
+          className: slot("button", "dwt-button"),
+          onClick: onRetry,
+          children: labels.retry
+        }
+      )
+    ] });
+  } else if (data !== void 0 && page !== void 0) {
+    const columns = data.columns;
+    const from = (page.page - 1) * query.pageSize + 1;
+    const to = from + page.rows.length - 1;
+    body = /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "dwt-detail-controls", children: [
+        /* @__PURE__ */ jsxRuntime.jsxs("label", { className: "dwt-detail-field", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("span", { children: labels.search }),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "input",
+            {
+              type: "search",
+              value: query.search ?? "",
+              onChange: (event) => change({ search: event.target.value })
+            }
+          )
+        ] }),
+        columns.filter((column) => column.filterable === true).map((column) => /* @__PURE__ */ jsxRuntime.jsxs("label", { className: "dwt-detail-field", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("span", { children: labels.filterBy(column.label) }),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            "input",
+            {
+              type: "search",
+              value: query.filters?.[column.key] ?? "",
+              onChange: (event) => change({
+                filters: {
+                  ...query.filters,
+                  [column.key]: event.target.value
+                }
+              })
+            }
+          )
+        ] }, column.key))
+      ] }),
+      /* @__PURE__ */ jsxRuntime.jsx(
+        "p",
+        {
+          className: "dwt-detail-summary",
+          role: "status",
+          "aria-live": "polite",
+          "aria-atomic": "true",
+          children: page.totalRows === 0 ? labels.noResults : labels.showingRows(from, to, page.totalRows)
+        }
+      ),
+      /* @__PURE__ */ jsxRuntime.jsx("div", { className: "dwt-table-wrap", children: /* @__PURE__ */ jsxRuntime.jsxs("table", { className: slot("table", "dwt-table", "dwt-detail-table"), children: [
+        /* @__PURE__ */ jsxRuntime.jsx("caption", { className: "dwt-visually-hidden", children: title }),
+        /* @__PURE__ */ jsxRuntime.jsx("thead", { children: /* @__PURE__ */ jsxRuntime.jsx("tr", { children: columns.map((column) => {
+          const sorted = query.sort?.column === column.key;
+          return /* @__PURE__ */ jsxRuntime.jsx(
+            "th",
+            {
+              scope: "col",
+              className: column.numeric === true ? "dwt-numeric" : void 0,
+              "aria-sort": sorted ? query.sort?.direction === "asc" ? "ascending" : "descending" : void 0,
+              children: column.sortable === false ? column.label : /* @__PURE__ */ jsxRuntime.jsxs(
+                "button",
+                {
+                  type: "button",
+                  className: "dwt-detail-sort",
+                  "aria-label": labels.sortBy(column.label),
+                  onClick: () => onQueryChange(
+                    withSort(query, nextSort(query.sort, column.key))
+                  ),
+                  children: [
+                    column.label,
+                    /* @__PURE__ */ jsxRuntime.jsx(SortGlyph, { sort: query.sort, column: column.key })
+                  ]
+                }
+              )
+            },
+            column.key
+          );
+        }) }) }),
+        /* @__PURE__ */ jsxRuntime.jsx("tbody", { children: page.rows.map((row, rowIndex) => /* @__PURE__ */ jsxRuntime.jsx("tr", { children: row.map((cell, cellIndex) => /* @__PURE__ */ jsxRuntime.jsx(
+          Cell,
+          {
+            cell,
+            column: columns[cellIndex]
+          },
+          cellIndex
+        )) }, rowIndex)) })
+      ] }) }),
+      page.pageCount > 1 && /* @__PURE__ */ jsxRuntime.jsxs("nav", { className: "dwt-detail-pager", "aria-label": labels.pagination, children: [
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "button",
+          {
+            type: "button",
+            className: slot("button", "dwt-button"),
+            disabled: page.page <= 1,
+            onClick: () => onQueryChange({ ...query, page: page.page - 1 }),
+            children: labels.previousPage
+          }
+        ),
+        /* @__PURE__ */ jsxRuntime.jsx("span", { children: labels.pageOf(page.page, page.pageCount) }),
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "button",
+          {
+            type: "button",
+            className: slot("button", "dwt-button"),
+            disabled: page.page >= page.pageCount,
+            onClick: () => onQueryChange({ ...query, page: page.page + 1 }),
+            children: labels.nextPage
+          }
+        )
+      ] })
+    ] });
+  }
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "section",
+    {
+      "aria-labelledby": headingId ?? `${id}-title`,
+      className: slot("detail", "dwt-detail", className),
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx(
+          Heading,
+          {
+            id: headingId ?? `${id}-title`,
+            className: slot("cardTitle", "dwt-card-title", "dwt-detail-title"),
+            children: title
+          }
+        ),
+        body
+      ]
+    }
+  );
+}
+function WidgetDetailDialog({
+  title,
+  open,
+  onClose,
+  children
+}) {
+  const slot = useSlotClassName();
+  const { labels } = useWidgetSettings();
+  const dialogRef = react.useRef(null);
+  const titleId = react.useId();
+  react.useEffect(() => {
+    const dialog = dialogRef.current;
+    if (dialog === null || !open) return void 0;
+    const opener = document.activeElement;
+    if (!dialog.open) dialog.showModal();
+    return () => {
+      if (dialog.open) dialog.close();
+      if (opener instanceof HTMLElement) opener.focus();
+    };
+  }, [open]);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "dialog",
+    {
+      ref: dialogRef,
+      className: "dwt-detail-dialog",
+      "aria-labelledby": titleId,
+      onCancel: (event) => {
+        event.preventDefault();
+        onClose();
+      },
+      onClick: (event) => {
+        if (event.target === dialogRef.current) onClose();
+      },
+      children: open && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "dwt-detail-dialog-body", children: [
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "button",
+          {
+            type: "button",
+            className: slot("button", "dwt-button", "dwt-detail-close"),
+            onClick: onClose,
+            children: labels.close
+          }
+        ),
+        /* @__PURE__ */ jsxRuntime.jsx("span", { id: titleId, className: "dwt-visually-hidden", children: title }),
+        children
+      ] })
+    }
+  );
+}
+function useDetailData(definition, load, enabled) {
+  const [state, setState] = react.useState({ status: "loading" });
+  const [attempt, setAttempt] = react.useState(0);
+  react.useEffect(() => {
+    if (!enabled || load === void 0) return void 0;
+    const controller = new AbortController();
+    setState({ status: "loading" });
+    Promise.resolve().then(
+      () => load(definition, {
+        signal: controller.signal,
+        query: defaultDetailQuery()
+      })
+    ).then((raw) => {
+      if (controller.signal.aborted) return;
+      const checked = validateDetailData(
+        raw,
+        `Widget "${definition.key}" detail`
+      );
+      setState(
+        checked.ok ? { status: "ok", data: checked.value } : { status: "error", error: checked.error }
+      );
+    }).catch((cause) => {
+      if (controller.signal.aborted) return;
+      setState({
+        status: "error",
+        error: `Widget "${definition.key}" detail: ${cause instanceof Error ? cause.message : String(cause)}`
+      });
+    });
+    return () => controller.abort();
+  }, [enabled, load, definition, attempt]);
+  return { state, reload: () => setAttempt((count) => count + 1) };
+}
 var NARROW_VIEWPORT_QUERY = "(max-width: 640px)";
-function useFillSpans(definitions, gridRef) {
+var WIDE_GRID_PX = 900;
+function useFillSpans(definitions, gridRef, twelve) {
   const [metrics, setMetrics] = react.useState(void 0);
   const needsSpans = definitions.some(
     (definition) => fillsWidth(definition.fill)
@@ -1171,6 +1832,13 @@ function useFillSpans(definitions, gridRef) {
     }
     function measure() {
       if (grid === null) return;
+      if (twelve) {
+        const wide = grid.clientWidth > WIDE_GRID_PX;
+        setMetrics(
+          (previous) => !wide ? void 0 : previous?.columns === WIDTH_COLUMNS ? previous : { columns: WIDTH_COLUMNS, largeSpan: 2 }
+        );
+        return;
+      }
       const tracks = getComputedStyle(grid).gridTemplateColumns;
       const columns = tracks === "" || tracks === "none" ? 0 : tracks.trim().split(/\s+/).length;
       const largeSpan = window.matchMedia(NARROW_VIEWPORT_QUERY).matches ? 1 : 2;
@@ -1182,12 +1850,15 @@ function useFillSpans(definitions, gridRef) {
     const observer = new ResizeObserver(measure);
     observer.observe(grid);
     return () => observer.disconnect();
-  }, [needsSpans, gridRef]);
+  }, [needsSpans, gridRef, twelve]);
   return react.useMemo(
-    () => metrics === void 0 ? /* @__PURE__ */ new Map() : fillColumnSpans(definitions, metrics.columns, metrics.largeSpan),
-    [definitions, metrics]
+    () => metrics === void 0 ? /* @__PURE__ */ new Map() : twelve ? fillWidthSpans(definitions) : fillColumnSpans(definitions, metrics.columns, metrics.largeSpan),
+    [definitions, metrics, twelve]
   );
 }
+function widthProps(twelve, definition) {
+  return twelve ? { width: itemWidth(definition) } : {};
+}
 function spanProps(spans, key) {
   const columnSpan = spans.get(key);
   return columnSpan === void 0 ? {} : { columnSpan };
@@ -1201,23 +1872,76 @@ function WidgetGrid({
   const slot = useSlotClassName();
   const gridRef = react.useRef(null);
   const definitions = widgets.map((w) => w.definition);
-  const spans = useFillSpans(definitions, gridRef);
-  return /* @__PURE__ */ jsxRuntime.jsx("div", { ref: gridRef, className: slot("grid", "dwt-grid", className), children: widgets.map((widget) => /* @__PURE__ */ jsxRuntime.jsx(
-    ResolvedWidgetCard,
+  const twelve = usesWidthColumns(definitions);
+  const spans = useFillSpans(
+    definitions,
+    gridRef,
+    twelve
+  );
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      ref: gridRef,
+      className: slot(
+        "grid",
+        "dwt-grid",
+        twelve && "dwt-grid--twelve",
+        className
+      ),
+      children: widgets.map((widget) => /* @__PURE__ */ jsxRuntime.jsx(
+        ResolvedWidgetCard,
+        {
+          widget,
+          ...spanProps(spans, widget.definition.key),
+          ...widthProps(twelve, widget.definition),
+          ...headingLevel === void 0 ? {} : { headingLevel },
+          ...onRetry === void 0 || widget.status !== "error" ? {} : { onRetry: () => onRetry(widget.definition.key) }
+        },
+        widget.definition.key
+      ))
+    }
+  );
+}
+function DetailHost({
+  widget,
+  loadDetail,
+  onClose
+}) {
+  const { locale } = useWidgetSettings();
+  const { definition } = widget;
+  const options = resolveDetailOptions(definition);
+  const pageSize = options?.pageSize ?? 25;
+  const [query, setQuery] = react.useState(defaultDetailQuery(pageSize));
+  const derived = widget.status === "ok" ? deriveDetailData(widget.data, locale) : void 0;
+  const load = react.useMemo(
+    () => loadDetail ?? (derived === void 0 ? void 0 : () => derived),
+    [loadDetail, derived]
+  );
+  const { state, reload } = useDetailData(definition, load, true);
+  const title = options?.title ?? definition.title;
+  return /* @__PURE__ */ jsxRuntime.jsx(WidgetDetailDialog, { title, open: true, onClose, children: /* @__PURE__ */ jsxRuntime.jsx(
+    WidgetDetail,
     {
-      widget,
-      ...spanProps(spans, widget.definition.key),
-      ...headingLevel === void 0 ? {} : { headingLevel },
-      ...onRetry === void 0 || widget.status !== "error" ? {} : { onRetry: () => onRetry(widget.definition.key) }
-    },
-    widget.definition.key
-  )) });
+      title,
+      query,
+      onQueryChange: setQuery,
+      status: load === void 0 ? "error" : state.status,
+      ...load === void 0 ? {
+        error: `Widget "${definition.key}" has no detail data: pass loadDetail, or use a TABLE without a footer or a BAR_LIST.`
+      } : {},
+      ...state.data === void 0 ? {} : { data: state.data },
+      ...state.error === void 0 ? {} : { error: state.error },
+      onRetry: reload
+    }
+  ) });
 }
 function DashboardInner({
   widgets,
   layout = EMPTY_LAYOUT,
   onLayoutChange,
   onRetry,
+  loadDetail,
+  onOpenDetail,
   headingLevel,
   className
 }) {
@@ -1230,8 +1954,16 @@ function DashboardInner({
   const visible = visibleWidgets(definitions, layout);
   const hidden = hiddenWidgets(definitions, layout);
   const editable = onLayoutChange !== void 0;
+  const minimized = editable ? visible.filter((definition) => isMinimized(layout, definition.key)) : [];
+  const shown = editable ? visible.filter((definition) => !isMinimized(layout, definition.key)) : visible;
+  const [detailKey, setDetailKey] = react.useState(void 0);
   const gridRef = react.useRef(null);
-  const spans = useFillSpans(visible, gridRef);
+  const twelve = usesWidthColumns(shown);
+  const spans = useFillSpans(
+    shown,
+    gridRef,
+    twelve
+  );
   function change(next) {
     if (next !== layout) onLayoutChange?.(next);
   }
@@ -1253,66 +1985,110 @@ function DashboardInner({
         definition.key
       ))
     ] }),
-    visible.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("p", { className: slot("empty", "dwt-empty", "dwt-dashboard-empty"), children: definitions.length === 0 ? labels.noWidgets : labels.allHidden }) : /* @__PURE__ */ jsxRuntime.jsx("div", { ref: gridRef, className: slot("grid", "dwt-grid"), children: visible.map((definition, index) => {
-      const widget = byKey.get(
-        definition.key
-      );
-      if (widget === void 0) return null;
-      const key = definition.key;
-      const title = definition.title;
-      const actions = editable ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-        /* @__PURE__ */ jsxRuntime.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__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2191" })
-          }
-        ),
-        /* @__PURE__ */ jsxRuntime.jsx(
-          "button",
-          {
-            type: "button",
-            className: slot("button", "dwt-button", "dwt-icon-button"),
-            "aria-label": labels.moveLater(title),
-            title: labels.moveLater(title),
-            disabled: index === visible.length - 1,
-            onClick: () => change(moveWidgetBy(definitions, layout, key, 1)),
-            children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2193" })
-          }
-        ),
-        /* @__PURE__ */ jsxRuntime.jsx(
-          "button",
-          {
-            type: "button",
-            className: slot("button", "dwt-button", "dwt-icon-button"),
-            "aria-label": labels.hide(title),
-            title: labels.hide(title),
-            onClick: () => change(hideWidget(layout, key)),
-            children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\xD7" })
-          }
-        )
-      ] }) : void 0;
-      return /* @__PURE__ */ jsxRuntime.jsx(
-        ResolvedWidgetCard,
-        {
-          widget,
-          ...spanProps(spans, key),
-          minimized: isMinimized(layout, key),
-          ...actions === void 0 ? {} : { actions },
-          ...editable ? {
-            onToggleMinimized: () => change(toggleMinimized(layout, key))
-          } : {},
-          ...headingLevel === void 0 ? {} : { headingLevel },
-          ...onRetry === void 0 || widget.status !== "error" ? {} : { onRetry: () => onRetry(key) }
-        },
-        key
-      );
-    }) })
+    minimized.length > 0 && /* @__PURE__ */ jsxRuntime.jsxs(
+      "div",
+      {
+        className: slot("hiddenBar", "dwt-hidden-bar", "dwt-minimized-bar"),
+        children: [
+          /* @__PURE__ */ jsxRuntime.jsx("span", { className: "dwt-hidden-label", children: labels.minimizedWidgets }),
+          minimized.map((definition) => /* @__PURE__ */ jsxRuntime.jsxs(
+            "button",
+            {
+              type: "button",
+              className: slot("button", "dwt-button", "dwt-show-button"),
+              "aria-label": labels.expand(definition.title),
+              onClick: () => change(toggleMinimized(layout, definition.key)),
+              children: [
+                /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u25B8 " }),
+                definition.title
+              ]
+            },
+            definition.key
+          ))
+        ]
+      }
+    ),
+    visible.length === 0 ? /* @__PURE__ */ jsxRuntime.jsx("p", { className: slot("empty", "dwt-empty", "dwt-dashboard-empty"), children: definitions.length === 0 ? labels.noWidgets : labels.allHidden }) : shown.length === 0 ? null : /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        ref: gridRef,
+        className: slot("grid", "dwt-grid", twelve && "dwt-grid--twelve"),
+        children: shown.map((definition, index) => {
+          const widget = byKey.get(
+            definition.key
+          );
+          if (widget === void 0) return null;
+          const key = definition.key;
+          const title = definition.title;
+          const actions = editable ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+            /* @__PURE__ */ jsxRuntime.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__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2191" })
+              }
+            ),
+            /* @__PURE__ */ jsxRuntime.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__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\u2193" })
+              }
+            ),
+            /* @__PURE__ */ jsxRuntime.jsx(
+              "button",
+              {
+                type: "button",
+                className: slot("button", "dwt-button", "dwt-icon-button"),
+                "aria-label": labels.hide(title),
+                title: labels.hide(title),
+                onClick: () => change(hideWidget(layout, key)),
+                children: /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: "\xD7" })
+              }
+            )
+          ] }) : void 0;
+          const viewable = resolveDetailOptions(definition) !== void 0 && (onOpenDetail !== void 0 || loadDetail !== void 0 || widget.status === "ok" && deriveDetailData(widget.data) !== void 0);
+          return /* @__PURE__ */ jsxRuntime.jsx(
+            ResolvedWidgetCard,
+            {
+              widget,
+              ...viewable ? {
+                onView: () => onOpenDetail === void 0 ? setDetailKey(key) : onOpenDetail(key)
+              } : {},
+              ...spanProps(spans, key),
+              ...widthProps(twelve, definition),
+              minimized: isMinimized(layout, key),
+              ...actions === void 0 ? {} : { actions },
+              ...editable ? {
+                onToggleMinimized: () => change(toggleMinimized(layout, key))
+              } : {},
+              ...headingLevel === void 0 ? {} : { headingLevel },
+              ...onRetry === void 0 || widget.status !== "error" ? {} : { onRetry: () => onRetry(key) }
+            },
+            key
+          );
+        })
+      }
+    ),
+    detailKey !== void 0 && byKey.get(detailKey) !== void 0 && /* @__PURE__ */ jsxRuntime.jsx(
+      DetailHost,
+      {
+        widget: byKey.get(detailKey),
+        loadDetail,
+        onClose: () => setDetailKey(void 0)
+      },
+      detailKey
+    )
   ] });
 }
 function Dashboard({
@@ -1337,6 +2113,656 @@ 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",
+  "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) {
+  if (value === null) return "null";
+  if (Array.isArray(value)) return "array";
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    return String(value);
+  }
+  return typeof value;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function join(path, field) {
+  return path === "" ? field : `${path}.${field}`;
+}
+function requireString(record, field, path, problems) {
+  const value = record[field];
+  if (typeof value !== "string") {
+    problems.push(
+      `${join(path, field)} must be a string, got ${describeType2(value)}.`
+    );
+  }
+}
+function optionalString(record, field, path, problems) {
+  if (record[field] !== void 0) {
+    requireString(record, field, path, problems);
+  }
+}
+function requireNumber(record, field, path, problems) {
+  const value = record[field];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    problems.push(
+      `${join(path, field)} must be a finite number, got ${describeType2(value)}.`
+    );
+  }
+}
+function optionalNumber(record, field, path, problems) {
+  if (record[field] !== void 0) {
+    requireNumber(record, field, path, problems);
+  }
+}
+function optionalBoolean(record, field, path, problems) {
+  const value = record[field];
+  if (value !== void 0 && typeof value !== "boolean") {
+    problems.push(
+      `${join(path, field)} must be a boolean, got ${describeType2(value)}.`
+    );
+  }
+}
+function optionalUrl(record, field, path, problems, isSafe, allowed) {
+  const value = record[field];
+  if (value === void 0) return;
+  if (typeof value !== "string") {
+    problems.push(
+      `${join(path, field)} must be a string, got ${describeType2(value)}.`
+    );
+  } else if (!isSafe(value)) {
+    problems.push(
+      `${join(path, field)} must be ${allowed}, got ${JSON.stringify(value.slice(0, 80))}.`
+    );
+  }
+}
+function requireArray(record, field, path, problems) {
+  const value = record[field];
+  if (!Array.isArray(value)) {
+    problems.push(
+      `${join(path, field)} must be an array, got ${describeType2(value)}.`
+    );
+    return null;
+  }
+  return value;
+}
+function requireOneOf(record, field, options, path, problems) {
+  const value = record[field];
+  if (typeof value !== "string" || !options.includes(value)) {
+    problems.push(
+      `${join(path, field)} must be one of ${options.map((o) => `"${o}"`).join(", ")}, got ${typeof value === "string" ? JSON.stringify(value) : describeType2(value)}.`
+    );
+  }
+}
+function eachRecord(items, path, problems, check) {
+  items.forEach((item, index) => {
+    const itemPath = `${path}[${index}]`;
+    if (isRecord(item)) {
+      check(item, itemPath);
+    } else {
+      problems.push(
+        `${itemPath} must be an object, got ${describeType2(item)}.`
+      );
+    }
+  });
+}
+var HREF_RULE = "an http(s), mailto or relative URL";
+var IMAGE_RULE = "an http(s) or relative URL";
+function checkPayloadFields(kind, data, problems) {
+  switch (kind) {
+    case "TEXT":
+      requireString(data, "value", "", problems);
+      requireString(data, "label", "", problems);
+      return;
+    case "KPI":
+      requireNumber(data, "value", "", problems);
+      if (data["previous"] !== null) {
+        optionalNumber(data, "previous", "", problems);
+      }
+      requireOneOf(data, "format", VALUE_FORMATS, "", problems);
+      optionalString(data, "currency", "", problems);
+      requireString(data, "label", "", problems);
+      optionalString(data, "hint", "", problems);
+      optionalBoolean(data, "higherIsBetter", "", problems);
+      return;
+    case "GAUGE":
+      requireNumber(data, "value", "", problems);
+      requireNumber(data, "max", "", problems);
+      requireString(data, "label", "", problems);
+      if (typeof data["max"] === "number" && data["max"] <= 0) {
+        problems.push(`max must be greater than 0, got ${data["max"]}.`);
+      }
+      return;
+    case "TABLE": {
+      const columns = requireArray(data, "columns", "", problems);
+      if (columns !== null) {
+        eachRecord(columns, "columns", problems, (column, path) => {
+          requireString(column, "label", path, problems);
+          optionalBoolean(column, "numeric", path, problems);
+        });
+      }
+      const rows = requireArray(data, "rows", "", problems);
+      if (rows !== null) {
+        rows.forEach((row, rowIndex) => {
+          const rowPath = `rows[${rowIndex}]`;
+          if (!Array.isArray(row)) {
+            problems.push(
+              `${rowPath} must be an array of cells, got ${describeType2(row)}.`
+            );
+            return;
+          }
+          if (columns !== null && row.length !== columns.length) {
+            problems.push(
+              `${rowPath} has ${row.length} cell(s) but there are ${columns.length} column(s).`
+            );
+          }
+          eachRecord(row, rowPath, problems, (cell, cellPath) => {
+            requireString(cell, "text", cellPath, problems);
+            optionalUrl(
+              cell,
+              "href",
+              cellPath,
+              problems,
+              isSafeHref,
+              HREF_RULE
+            );
+          });
+        });
+      }
+      optionalString(data, "footer", "", problems);
+      return;
+    }
+    case "BAR_LIST": {
+      const items = requireArray(data, "items", "", problems);
+      if (items !== null) {
+        eachRecord(items, "items", problems, (item, path) => {
+          requireString(item, "label", path, problems);
+          requireNumber(item, "value", path, problems);
+          optionalString(item, "display", path, problems);
+        });
+      }
+      optionalNumber(data, "total", "", problems);
+      return;
+    }
+    case "ALERT_LIST": {
+      const items = requireArray(data, "items", "", problems);
+      if (items !== null) {
+        eachRecord(items, "items", problems, (item, path) => {
+          requireString(item, "title", path, problems);
+          optionalUrl(item, "href", path, problems, isSafeHref, HREF_RULE);
+          optionalUrl(
+            item,
+            "thumbnailUrl",
+            path,
+            problems,
+            isSafeImageUrl,
+            IMAGE_RULE
+          );
+          requireString(item, "valueLabel", path, problems);
+          optionalString(item, "detail", path, problems);
+        });
+      }
+      requireNumber(data, "total", "", problems);
+      requireString(data, "emptyText", "", problems);
+      if (items !== null && typeof data["total"] === "number" && data["total"] < items.length) {
+        problems.push(
+          `total (${data["total"]}) must be at least the number of items (${items.length}).`
+        );
+      }
+      return;
+    }
+    case "GRAPH": {
+      const series = requireArray(data, "series", "", problems);
+      if (series !== null) {
+        if (series.length > MAX_GRAPH_SERIES) {
+          problems.push(
+            `series has ${series.length} entries; at most ${MAX_GRAPH_SERIES} are allowed (fold the rest into "Other").`
+          );
+        }
+        eachRecord(series, "series", problems, (entry, path) => {
+          requireString(entry, "name", path, problems);
+          const points = requireArray(entry, "points", path, problems);
+          if (points !== null) {
+            eachRecord(
+              points,
+              `${path}.points`,
+              problems,
+              (point, pointPath) => {
+                requireString(point, "label", pointPath, problems);
+                requireNumber(point, "value", pointPath, problems);
+              }
+            );
+          }
+        });
+      }
+      requireOneOf(data, "chartType", ["bar", "line"], "", problems);
+      requireOneOf(data, "valueFormat", VALUE_FORMATS, "", problems);
+      optionalString(data, "currency", "", problems);
+      optionalString(data, "xLabel", "", problems);
+      return;
+    }
+  }
+}
+function formatProblems(prefix, problems) {
+  const shown = problems.slice(0, MAX_REPORTED_PROBLEMS);
+  const more = problems.length - shown.length;
+  return `${prefix}: ${shown.join(" ")}${more > 0 ? ` (and ${more} more problem(s))` : ""}`;
+}
+function validateWidgetData(value, options = {}) {
+  const subject = options.widgetKey === void 0 ? "Widget data" : `Widget ${JSON.stringify(options.widgetKey)}`;
+  if (!isRecord(value)) {
+    return err(`${subject}: must be an object, got ${describeType2(value)}.`);
+  }
+  if (value["empty"] === true) {
+    if (typeof value["text"] !== "string") {
+      return err(
+        `${subject} (empty): text must be a string, got ${describeType2(value["text"])}.`
+      );
+    }
+    return ok(value);
+  }
+  const kind = value["kind"];
+  if (!isWidgetKind(kind)) {
+    return err(
+      `${subject}: kind must be one of ${WIDGET_KINDS.join(", ")} (or the payload must be {"empty": true, "text": ...}), got ${typeof kind === "string" ? JSON.stringify(kind) : describeType2(kind)}.`
+    );
+  }
+  if (options.expectedKind !== void 0 && kind !== options.expectedKind) {
+    return err(
+      `${subject}: expected kind ${options.expectedKind} from its definition, got ${kind}.`
+    );
+  }
+  const problems = [];
+  checkPayloadFields(kind, value, problems);
+  if (problems.length > 0) {
+    return err(formatProblems(`${subject} (${kind})`, problems));
+  }
+  return ok(value);
+}
+
+// src/core/resolve.ts
+function resolvePayload(definition, payload, options = {}) {
+  let checked;
+  if (options.validate === false) {
+    checked = payload;
+  } else {
+    const result = validateWidgetData(payload, {
+      widgetKey: definition.key,
+      expectedKind: definition.kind
+    });
+    if (!result.ok) {
+      return { definition, status: "error", error: result.error };
+    }
+    checked = result.value;
+  }
+  const emptyText = emptyTextFor(checked);
+  if (emptyText !== null) {
+    return { definition, status: "empty", emptyText };
+  }
+  return { definition, status: "ok", data: checked };
+}
+function failedWidget(definition, error) {
+  return { definition, status: "error", error };
+}
+function loadingWidgets(definitions) {
+  return definitions.map((definition) => ({ definition, status: "loading" }));
+}
+function cacheKeyFor(definition, options) {
+  return options.cacheKey === void 0 ? definition.key : options.cacheKey(definition);
+}
+var LoadInterruption = class extends Error {
+};
+async function resolveWidget(definition, provider, context, options = {}) {
+  const quotedKey = JSON.stringify(definition.key);
+  if (provider === void 0) {
+    return failedWidget(
+      definition,
+      `Widget ${quotedKey}: no provider is registered for this key.`
+    );
+  }
+  if (options.signal?.aborted === true) {
+    return failedWidget(
+      definition,
+      `Widget ${quotedKey}: loading was canceled before it started.`
+    );
+  }
+  const controller = new AbortController();
+  const onExternalAbort = () => controller.abort(options.signal?.reason);
+  options.signal?.addEventListener("abort", onExternalAbort, { once: true });
+  let timedOut = false;
+  const timeoutMs = options.timeoutMs !== void 0 && options.timeoutMs > 0 ? options.timeoutMs : void 0;
+  const timer = timeoutMs === void 0 ? void 0 : setTimeout(() => {
+    timedOut = true;
+    controller.abort(new Error(`Timed out after ${timeoutMs} ms.`));
+  }, timeoutMs);
+  const interrupted = new Promise((_resolve, reject) => {
+    controller.signal.addEventListener(
+      "abort",
+      () => reject(new LoadInterruption()),
+      { once: true }
+    );
+  });
+  let payload;
+  try {
+    payload = await Promise.race([
+      Promise.resolve().then(() => {
+        if (controller.signal.aborted) throw new LoadInterruption();
+        return provider(context, definition, { signal: controller.signal });
+      }),
+      interrupted
+    ]);
+  } catch (cause) {
+    if (cause instanceof LoadInterruption) {
+      return failedWidget(
+        definition,
+        timedOut ? `Widget ${quotedKey}: provider timed out after ${timeoutMs} ms.` : `Widget ${quotedKey}: loading was canceled.`
+      );
+    }
+    return failedWidget(
+      definition,
+      `Widget ${quotedKey}: provider failed: ${describeUnknownError(cause)}`
+    );
+  } finally {
+    if (timer !== void 0) clearTimeout(timer);
+    options.signal?.removeEventListener("abort", onExternalAbort);
+  }
+  const resolved = resolvePayload(definition, payload, options);
+  if (resolved.status !== "ok") return resolved;
+  const storedAt = Date.now();
+  if (options.cache !== void 0) {
+    try {
+      await options.cache.set(cacheKeyFor(definition, options), {
+        payload: resolved.data,
+        storedAt
+      });
+    } catch {
+    }
+  }
+  return { ...resolved, updatedAt: storedAt };
+}
+function widgetsFor(definitions, roles) {
+  return sortDefinitions(
+    definitions.filter((definition) => isWidgetVisibleTo(definition, roles))
+  );
+}
+
+// src/core/loader.ts
+function createWidgetLoader(options) {
+  const { definitions, providers, context, ...resolveOptions } = options;
+  const visible = widgetsFor(definitions, context.roles);
+  let snapshot = loadingWidgets(visible);
+  const listeners = /* @__PURE__ */ new Set();
+  const started = /* @__PURE__ */ new Set();
+  const generations = /* @__PURE__ */ new Map();
+  const inFlight = /* @__PURE__ */ new Map();
+  let disposed = false;
+  function publish(next) {
+    snapshot = next;
+    for (const listener of [...listeners]) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  }
+  function replace(key, widget) {
+    publish(
+      snapshot.map(
+        (current) => current.definition.key === key ? widget : current
+      )
+    );
+  }
+  function abortAll(reason) {
+    for (const controller of inFlight.values()) controller.abort(reason);
+    inFlight.clear();
+  }
+  resolveOptions.signal?.addEventListener(
+    "abort",
+    () => abortAll(resolveOptions.signal?.reason),
+    { once: true }
+  );
+  async function run(definition, readCache) {
+    const key = definition.key;
+    const generation = (generations.get(key) ?? 0) + 1;
+    generations.set(key, generation);
+    inFlight.get(key)?.abort(new Error("Superseded by a newer load."));
+    const controller = new AbortController();
+    inFlight.set(key, controller);
+    const isCurrent = () => !disposed && generations.get(key) === generation;
+    if (readCache && resolveOptions.cache !== void 0) {
+      try {
+        const entry = await resolveOptions.cache.get(
+          cacheKeyFor(definition, resolveOptions)
+        );
+        if (entry !== void 0 && isCurrent()) {
+          const cached = resolvePayload(
+            definition,
+            entry.payload,
+            resolveOptions
+          );
+          if (cached.status === "ok") {
+            replace(key, { ...cached, updatedAt: entry.storedAt, stale: true });
+          }
+        }
+      } catch {
+      }
+    }
+    if (!isCurrent()) return;
+    const provider = Object.prototype.hasOwnProperty.call(providers, key) ? providers[key] : void 0;
+    const result = await resolveWidget(definition, provider, context, {
+      ...resolveOptions,
+      signal: controller.signal
+    });
+    if (!isCurrent()) return;
+    inFlight.delete(key);
+    replace(key, result);
+  }
+  function start(definition, readCache) {
+    started.add(definition.key);
+    void run(definition, readCache);
+  }
+  function definitionFor(key) {
+    return visible.find((definition) => definition.key === key);
+  }
+  function load(key) {
+    if (disposed || started.has(key)) return;
+    const definition = definitionFor(key);
+    if (definition !== void 0) start(definition, true);
+  }
+  function loadAll() {
+    for (const definition of visible) load(definition.key);
+  }
+  function refresh(key, refreshOptions) {
+    if (disposed) return;
+    const keys = key === void 0 ? [...started] : [key];
+    for (const target of keys) {
+      const definition = definitionFor(target);
+      if (definition === void 0) continue;
+      if (refreshOptions?.skipInFlight === true && inFlight.has(target)) {
+        continue;
+      }
+      const current = snapshot.find(
+        (widget) => widget.definition.key === target
+      );
+      if (current?.status === "error") {
+        replace(target, { definition, status: "loading" });
+      }
+      start(definition, false);
+    }
+  }
+  function dispose() {
+    disposed = true;
+    abortAll(new Error("The widget loader was disposed."));
+    listeners.clear();
+  }
+  function subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+  return {
+    getSnapshot: () => snapshot,
+    subscribe,
+    load,
+    loadAll,
+    refresh,
+    dispose
+  };
+}
+
+// src/react/use-widgets.ts
+function useWidgets(definitions, providers, context, options = {}) {
+  const {
+    loadWhen = "mount",
+    rootMargin = "200px",
+    refreshMs = 0,
+    validate,
+    timeoutMs,
+    signal,
+    cache,
+    cacheKey
+  } = options;
+  const placeholders = react.useMemo(
+    () => loadingWidgets(widgetsFor(definitions, context.roles)),
+    [definitions, context.roles]
+  );
+  const [widgets, setWidgets] = react.useState(placeholders);
+  const [loader, setLoader] = react.useState(null);
+  const loaderRef = react.useRef(null);
+  const gridRef = react.useRef(null);
+  react.useEffect(() => {
+    const created = createWidgetLoader({
+      definitions,
+      providers,
+      context,
+      ...validate === void 0 ? {} : { validate },
+      ...timeoutMs === void 0 ? {} : { timeoutMs },
+      ...signal === void 0 ? {} : { signal },
+      ...cache === void 0 ? {} : { cache },
+      ...cacheKey === void 0 ? {} : { cacheKey }
+    });
+    loaderRef.current = created;
+    setWidgets(created.getSnapshot());
+    const unsubscribe = created.subscribe(
+      () => setWidgets(created.getSnapshot())
+    );
+    setLoader(created);
+    if (loadWhen === "mount" || typeof IntersectionObserver === "undefined") {
+      created.loadAll();
+    }
+    return () => {
+      unsubscribe();
+      created.dispose();
+      loaderRef.current = null;
+      setLoader(null);
+    };
+  }, [
+    definitions,
+    providers,
+    context,
+    validate,
+    timeoutMs,
+    signal,
+    cache,
+    cacheKey,
+    loadWhen
+  ]);
+  const cardKeys = widgets.map((widget) => widget.definition.key).join("\0");
+  react.useEffect(() => {
+    const grid = gridRef.current;
+    if (loader === null || grid === null || loadWhen !== "visible" || typeof IntersectionObserver === "undefined") {
+      return void 0;
+    }
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          const key = entry.target.dataset["widgetKey"];
+          if (entry.isIntersecting && key !== void 0) {
+            loader.load(key);
+            observer.unobserve(entry.target);
+          }
+        }
+      },
+      { rootMargin }
+    );
+    grid.querySelectorAll("[data-widget-key]").forEach((card) => observer.observe(card));
+    return () => observer.disconnect();
+  }, [loader, loadWhen, rootMargin, cardKeys]);
+  react.useEffect(() => {
+    if (loader === null || !(refreshMs > 0)) return void 0;
+    const timer = setInterval(() => {
+      if (typeof document !== "undefined" && document.visibilityState === "hidden") {
+        return;
+      }
+      loader.refresh(void 0, { skipInFlight: true });
+    }, refreshMs);
+    return () => clearInterval(timer);
+  }, [loader, refreshMs]);
+  const refresh = react.useCallback((key) => {
+    loaderRef.current?.refresh(key);
+  }, []);
+  return { widgets, refresh, gridRef };
+}
+
 exports.AlertListWidget = AlertListWidget;
 exports.BarListWidget = BarListWidget;
 exports.DEFAULT_LABELS = DEFAULT_LABELS;
@@ -1351,6 +2777,8 @@ exports.TextWidget = TextWidget;
 exports.Thumbnail = Thumbnail;
 exports.WidgetCard = WidgetCard;
 exports.WidgetContent = WidgetContent;
+exports.WidgetDetail = WidgetDetail;
+exports.WidgetDetailDialog = WidgetDetailDialog;
 exports.WidgetGrid = WidgetGrid;
 exports.WidgetLink = WidgetLink;
 exports.WidgetSettingsProvider = WidgetSettingsProvider;
@@ -1359,7 +2787,9 @@ exports.buildChartModel = buildChartModel;
 exports.describeChart = describeChart;
 exports.joinClassNames = joinClassNames;
 exports.seriesColor = seriesColor;
+exports.useDetailData = useDetailData;
 exports.useWidgetSettings = useWidgetSettings;
+exports.useWidgets = useWidgets;
 exports.widgetTitle = widgetTitle;
 //# sourceMappingURL=react.cjs.map
 //# sourceMappingURL=react.cjs.map