@richardmcquiston01/dashboard-widgets-toolkit 0.1.0 → 0.4.0

package/dist/index.cjs

@@ -85,6 +85,7 @@ function fromLegacyDefinition(legacy) {
 
 // src/core/definition.ts
 var WIDGET_SIZES = ["small", "medium", "large", "full"];
+var WIDGET_FILLS = ["height", "width", "both"];
 function defineWidget(definition) {
   return definition;
 }
@@ -191,6 +192,444 @@ function kpiDelta(current, previous, options = {}) {
   };
 }
 
+// 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/url.ts
+var SCHEME_PATTERN = /^([a-z][a-z0-9+.-]*):/i;
+var IGNORED_IN_SCHEME = /[\u0000- \u007f]/g;
+function schemeOf(url) {
+  const match = SCHEME_PATTERN.exec(
+    url.replace(IGNORED_IN_SCHEME, "")
+  );
+  return match === null ? null : (match[1] ?? "").toLowerCase();
+}
+function isSafeHref(url) {
+  if (url.trim() === "") {
+    return false;
+  }
+  const scheme = schemeOf(url);
+  return scheme === null || scheme === "http" || scheme === "https" || scheme === "mailto";
+}
+function isSafeImageUrl(url) {
+  if (url.trim() === "") {
+    return false;
+  }
+  const scheme = schemeOf(url);
+  return scheme === null || scheme === "http" || scheme === "https";
+}
+
+// src/core/detail.ts
+var DETAIL_MODES = ["client", "server"];
+var DEFAULT_DETAIL_PAGE_SIZE = 25;
+var MAX_DETAIL_PAGE_SIZE = 200;
+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(", ");
+}
+var FILTER_PREFIX = "f.";
+function serializeDetailQuery(query) {
+  const parts = [];
+  const add = (key, value) => {
+    parts.push(`${encodeURIComponent(key)}=${encodeURIComponent(value)}`);
+  };
+  if (query.search !== void 0 && query.search !== "") {
+    add("q", query.search);
+  }
+  if (query.sort !== void 0) {
+    add("sort", `${query.sort.column}:${query.sort.direction}`);
+  }
+  for (const [column, text] of Object.entries(query.filters ?? {})) {
+    if (text !== "") add(`${FILTER_PREFIX}${column}`, text);
+  }
+  if (query.page > 1) add("page", String(query.page));
+  return parts.join("&");
+}
+function parseDetailQuery(queryString, pageSize = DEFAULT_DETAIL_PAGE_SIZE, data) {
+  let search;
+  let sort;
+  let page = 1;
+  const filters = {};
+  const columnKeys = data === void 0 ? void 0 : new Set(data.columns.map((column) => column.key));
+  const text = queryString.startsWith("?") ? queryString.slice(1) : queryString;
+  for (const pair of text.split("&")) {
+    if (pair === "") continue;
+    const equals = pair.indexOf("=");
+    const rawKey = equals < 0 ? pair : pair.slice(0, equals);
+    const rawValue = equals < 0 ? "" : pair.slice(equals + 1);
+    let key;
+    let value;
+    try {
+      key = decodeURIComponent(rawKey.replace(/\+/g, " "));
+      value = decodeURIComponent(rawValue.replace(/\+/g, " "));
+    } catch {
+      return err(
+        `Detail query: "${pair}" is not valid percent-encoding in the URL.`
+      );
+    }
+    if (key === "q") {
+      search = value;
+    } else if (key === "page") {
+      if (!/^[1-9]\d*$/.test(value)) {
+        return err(
+          `Detail query: page must be a whole number from 1, got "${value}".`
+        );
+      }
+      page = Number(value);
+    } else if (key === "sort") {
+      const colon = value.lastIndexOf(":");
+      const column = colon < 0 ? value : value.slice(0, colon);
+      const direction = colon < 0 ? "asc" : value.slice(colon + 1);
+      if (column === "" || direction !== "asc" && direction !== "desc") {
+        return err(
+          `Detail query: sort must look like "column:asc" or "column:desc", got "${value}".`
+        );
+      }
+      if (columnKeys !== void 0 && !columnKeys.has(column)) {
+        return err(`Detail query: sort column "${column}" does not exist.`);
+      }
+      sort = { column, direction };
+    } else if (key.startsWith(FILTER_PREFIX)) {
+      const column = key.slice(FILTER_PREFIX.length);
+      if (columnKeys !== void 0 && !columnKeys.has(column)) {
+        return err(`Detail query: filter column "${column}" does not exist.`);
+      }
+      if (value !== "") filters[column] = value;
+    }
+  }
+  return ok({
+    ...search === void 0 || search === "" ? {} : { search },
+    ...Object.keys(filters).length === 0 ? {} : { filters },
+    ...sort === void 0 ? {} : { sort },
+    page,
+    pageSize
+  });
+}
+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;
+}
+
+// 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";
+}
+function fillsHeight(fill) {
+  return fill === "height" || fill === "both";
+}
+function baseColumnSpan(size, columns, largeSpan = 2) {
+  if (size === "full") return columns;
+  if (size === "large") return Math.min(largeSpan, columns);
+  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 = [];
+  let used = 0;
+  function closeRow() {
+    const fillers = row.filter(({ item }) => fillsWidth(item.fill));
+    const leftover = trackCount - used;
+    if (fillers.length > 0) {
+      const share = Math.floor(leftover / fillers.length);
+      const remainder = leftover % fillers.length;
+      fillers.forEach(({ item, span }, index) => {
+        spans.set(item.key, span + share + (index < remainder ? 1 : 0));
+      });
+    }
+    row = [];
+    used = 0;
+  }
+  for (const item of items) {
+    const span = Math.min(spanOf(item, trackCount), trackCount);
+    if (used + span > trackCount && row.length > 0) closeRow();
+    row.push({ item, span });
+    used += span;
+  }
+  closeRow();
+  return spans;
+}
+
 // src/core/layout.ts
 var EMPTY_LAYOUT = Object.freeze({
   order: Object.freeze([]),
@@ -333,55 +772,9 @@ 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;
 }
 
-// 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/url.ts
-var SCHEME_PATTERN = /^([a-z][a-z0-9+.-]*):/i;
-var IGNORED_IN_SCHEME = /[\u0000- \u007f]/g;
-function schemeOf(url) {
-  const match = SCHEME_PATTERN.exec(
-    url.replace(IGNORED_IN_SCHEME, "")
-  );
-  return match === null ? null : (match[1] ?? "").toLowerCase();
-}
-function isSafeHref(url) {
-  if (url.trim() === "") {
-    return false;
-  }
-  const scheme = schemeOf(url);
-  return scheme === null || scheme === "http" || scheme === "https" || scheme === "mailto";
-}
-function isSafeImageUrl(url) {
-  if (url.trim() === "") {
-    return false;
-  }
-  const scheme = schemeOf(url);
-  return scheme === null || scheme === "http" || scheme === "https";
-}
-
 // src/core/validate.ts
 var MAX_REPORTED_PROBLEMS = 10;
-function describeType(value) {
+function describeType2(value) {
   if (value === null) return "null";
   if (Array.isArray(value)) return "array";
   if (typeof value === "number" && !Number.isFinite(value)) {
@@ -399,7 +792,7 @@ function requireString(record, field, path, problems) {
   const value = record[field];
   if (typeof value !== "string") {
     problems.push(
-      `${join(path, field)} must be a string, got ${describeType(value)}.`
+      `${join(path, field)} must be a string, got ${describeType2(value)}.`
     );
   }
 }
@@ -412,7 +805,7 @@ 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 ${describeType(value)}.`
+      `${join(path, field)} must be a finite number, got ${describeType2(value)}.`
     );
   }
 }
@@ -425,7 +818,7 @@ 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 ${describeType(value)}.`
+      `${join(path, field)} must be a boolean, got ${describeType2(value)}.`
     );
   }
 }
@@ -434,7 +827,7 @@ function optionalUrl(record, field, path, problems, isSafe, allowed) {
   if (value === void 0) return;
   if (typeof value !== "string") {
     problems.push(
-      `${join(path, field)} must be a string, got ${describeType(value)}.`
+      `${join(path, field)} must be a string, got ${describeType2(value)}.`
     );
   } else if (!isSafe(value)) {
     problems.push(
@@ -446,7 +839,7 @@ function requireArray(record, field, path, problems) {
   const value = record[field];
   if (!Array.isArray(value)) {
     problems.push(
-      `${join(path, field)} must be an array, got ${describeType(value)}.`
+      `${join(path, field)} must be an array, got ${describeType2(value)}.`
     );
     return null;
   }
@@ -456,7 +849,7 @@ 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) : describeType(value)}.`
+      `${join(path, field)} must be one of ${options.map((o) => `"${o}"`).join(", ")}, got ${typeof value === "string" ? JSON.stringify(value) : describeType2(value)}.`
     );
   }
 }
@@ -467,7 +860,7 @@ function eachRecord(items, path, problems, check) {
       check(item, itemPath);
     } else {
       problems.push(
-        `${itemPath} must be an object, got ${describeType(item)}.`
+        `${itemPath} must be an object, got ${describeType2(item)}.`
       );
     }
   });
@@ -513,7 +906,7 @@ function checkPayloadFields(kind, data, problems) {
           const rowPath = `rows[${rowIndex}]`;
           if (!Array.isArray(row)) {
             problems.push(
-              `${rowPath} must be an array of cells, got ${describeType(row)}.`
+              `${rowPath} must be an array of cells, got ${describeType2(row)}.`
             );
             return;
           }
@@ -609,6 +1002,25 @@ function checkPayloadFields(kind, data, problems) {
     }
   }
 }
+function checkDetailOption(detail, problems) {
+  if (detail === void 0 || typeof detail === "boolean") return;
+  if (!isRecord(detail)) {
+    problems.push(
+      `detail must be true, false or an options object, got ${describeType2(detail)}.`
+    );
+    return;
+  }
+  optionalString(detail, "title", "detail", problems);
+  const pageSize = detail["pageSize"];
+  if (pageSize !== void 0 && !(typeof pageSize === "number" && Number.isInteger(pageSize) && pageSize >= 1 && pageSize <= MAX_DETAIL_PAGE_SIZE)) {
+    problems.push(
+      `detail.pageSize must be a whole number from 1 to ${MAX_DETAIL_PAGE_SIZE}, got ${typeof pageSize === "number" ? String(pageSize) : describeType2(pageSize)}.`
+    );
+  }
+  if (detail["mode"] !== void 0) {
+    requireOneOf(detail, "mode", DETAIL_MODES, "detail", problems);
+  }
+}
 function formatProblems(prefix, problems) {
   const shown = problems.slice(0, MAX_REPORTED_PROBLEMS);
   const more = problems.length - shown.length;
@@ -617,12 +1029,12 @@ function formatProblems(prefix, problems) {
 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 ${describeType(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 ${describeType(value["text"])}.`
+        `${subject} (empty): text must be a string, got ${describeType2(value["text"])}.`
       );
     }
     return ok(value);
@@ -630,7 +1042,7 @@ function validateWidgetData(value, options = {}) {
   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) : describeType(kind)}.`
+      `${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) {
@@ -648,7 +1060,7 @@ function validateWidgetData(value, options = {}) {
 function validateWidgetDefinition(value) {
   if (!isRecord(value)) {
     return err(
-      `Widget definition: must be an object, got ${describeType(value)}.`
+      `Widget definition: must be an object, got ${describeType2(value)}.`
     );
   }
   const subject = typeof value["key"] === "string" ? `Widget definition ${JSON.stringify(value["key"])}` : "Widget definition";
@@ -666,7 +1078,7 @@ function validateWidgetDefinition(value) {
     roles?.forEach((role, index) => {
       if (typeof role !== "string") {
         problems.push(
-          `roles[${index}] must be a string, got ${describeType(role)}.`
+          `roles[${index}] must be a string, got ${describeType2(role)}.`
         );
       }
     });
@@ -675,6 +1087,15 @@ function validateWidgetDefinition(value) {
   if (value["defaultSize"] !== void 0) {
     requireOneOf(value, "defaultSize", WIDGET_SIZES, "", problems);
   }
+  if (value["width"] !== void 0 && !isWidgetWidth(value["width"])) {
+    problems.push(
+      `width must be an integer from ${MIN_WIDGET_WIDTH} to ${MAX_WIDGET_WIDTH} (twelfths of the row), got ${typeof value["width"] === "number" ? String(value["width"]) : describeType2(value["width"])}.`
+    );
+  }
+  checkDetailOption(value["detail"], problems);
+  if (value["fill"] !== void 0) {
+    requireOneOf(value, "fill", WIDGET_FILLS, "", problems);
+  }
   if (problems.length > 0) {
     return err(formatProblems(subject, problems));
   }
@@ -708,23 +1129,78 @@ function failedWidget(definition, 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 ${JSON.stringify(definition.key)}: no provider is registered for this key.`
+      `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 provider(context, definition);
+    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 ${JSON.stringify(definition.key)}: provider failed: ${describeUnknownError(cause)}`
+      `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 resolvePayload(definition, payload, options);
+  return { ...resolved, updatedAt: storedAt };
 }
 function widgetsFor(definitions, roles) {
   return sortDefinitions(
@@ -745,6 +1221,131 @@ async function resolveWidgets(definitions, providers, context, options = {}) {
   );
 }
 
+// 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/core/scale.ts
 function niceStep(value) {
   if (!(value > 0) || !Number.isFinite(value)) return 1;
@@ -777,19 +1378,35 @@ function labelStride(count, maxLabels = 6) {
 
 exports.DEFAULT_COMPARISON_LABEL = DEFAULT_COMPARISON_LABEL;
 exports.DEFAULT_CURRENCY = DEFAULT_CURRENCY;
+exports.DEFAULT_DETAIL_PAGE_SIZE = DEFAULT_DETAIL_PAGE_SIZE;
 exports.DEFAULT_EMPTY_TEXT = DEFAULT_EMPTY_TEXT;
+exports.DETAIL_MODES = DETAIL_MODES;
 exports.EMPTY_LAYOUT = EMPTY_LAYOUT;
+exports.MAX_DETAIL_PAGE_SIZE = MAX_DETAIL_PAGE_SIZE;
 exports.MAX_GRAPH_SERIES = MAX_GRAPH_SERIES;
 exports.MAX_REPORTED_PROBLEMS = MAX_REPORTED_PROBLEMS;
+exports.MAX_WIDGET_WIDTH = MAX_WIDGET_WIDTH;
+exports.MIN_WIDGET_WIDTH = MIN_WIDGET_WIDTH;
 exports.VALUE_FORMATS = VALUE_FORMATS;
+exports.WIDGET_FILLS = WIDGET_FILLS;
 exports.WIDGET_KINDS = WIDGET_KINDS;
 exports.WIDGET_SIZES = WIDGET_SIZES;
+exports.WIDTH_COLUMNS = WIDTH_COLUMNS;
+exports.baseColumnSpan = baseColumnSpan;
+exports.cacheKeyFor = cacheKeyFor;
+exports.createWidgetLoader = createWidgetLoader;
+exports.defaultDetailQuery = defaultDetailQuery;
 exports.defineWidget = defineWidget;
+exports.deriveDetailData = deriveDetailData;
 exports.describeUnknownError = describeUnknownError;
 exports.emptyTextFor = emptyTextFor;
 exports.emptyWidget = emptyWidget;
 exports.err = err;
 exports.failedWidget = failedWidget;
+exports.fillColumnSpans = fillColumnSpans;
+exports.fillWidthSpans = fillWidthSpans;
+exports.fillsHeight = fillsHeight;
+exports.fillsWidth = fillsWidth;
 exports.formatCount = formatCount;
 exports.formatPercentChange = formatPercentChange;
 exports.formatValue = formatValue;
@@ -803,6 +1420,8 @@ exports.isSafeImageUrl = isSafeImageUrl;
 exports.isWidgetEmptyState = isWidgetEmptyState;
 exports.isWidgetKind = isWidgetKind;
 exports.isWidgetVisibleTo = isWidgetVisibleTo;
+exports.isWidgetWidth = isWidgetWidth;
+exports.itemWidth = itemWidth;
 exports.kpiDelta = kpiDelta;
 exports.labelStride = labelStride;
 exports.loadingWidgets = loadingWidgets;
@@ -814,13 +1433,17 @@ exports.moveWidgetUp = moveWidgetUp;
 exports.niceDomain = niceDomain;
 exports.niceStep = niceStep;
 exports.ok = ok;
+exports.parseDetailQuery = parseDetailQuery;
 exports.parseLayout = parseLayout;
 exports.percentChange = percentChange;
 exports.pruneLayout = pruneLayout;
+exports.queryRows = queryRows;
+exports.resolveDetailOptions = resolveDetailOptions;
 exports.resolvePayload = resolvePayload;
 exports.resolveWidget = resolveWidget;
 exports.resolveWidgets = resolveWidgets;
 exports.restoreWidget = restoreWidget;
+exports.serializeDetailQuery = serializeDetailQuery;
 exports.serializeLayout = serializeLayout;
 exports.shareOf = shareOf;
 exports.showWidget = showWidget;
@@ -828,9 +1451,12 @@ exports.sortDefinitions = sortDefinitions;
 exports.toggleHidden = toggleHidden;
 exports.toggleMinimized = toggleMinimized;
 exports.upgradeLegacyWidgetData = upgradeLegacyWidgetData;
+exports.usesWidthColumns = usesWidthColumns;
+exports.validateDetailData = validateDetailData;
 exports.validateWidgetData = validateWidgetData;
 exports.validateWidgetDefinition = validateWidgetDefinition;
 exports.visibleWidgets = visibleWidgets;
 exports.widgetsFor = widgetsFor;
+exports.widthForSize = widthForSize;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map