@ai-matrx/design-system 0.21.14 → 0.25.0

package/dist/data-table/grouping.cjs

@@ -0,0 +1,302 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/data-table/grouping.ts
+var grouping_exports = {};
+__export(grouping_exports, {
+  EMPTY_GROUP_KEY: () => EMPTY_GROUP_KEY,
+  coerceGroupNumber: () => coerceGroupNumber,
+  flattenGroups: () => flattenGroups,
+  formatGroupNumber: () => formatGroupNumber,
+  groupKeyOf: () => groupKeyOf,
+  groupRows: () => groupRows,
+  groupSummary: () => groupSummary,
+  isBlankGroupValue: () => isBlankGroupValue,
+  isGroupCollapsed: () => isGroupCollapsed,
+  toggleGroupCollapsed: () => toggleGroupCollapsed
+});
+module.exports = __toCommonJS(grouping_exports);
+var EMPTY_GROUP_KEY = "empty";
+var DEFAULT_EMPTY_LABEL = "(empty)";
+function isBlankGroupValue(value) {
+  return value === null || value === void 0 || value === "";
+}
+function groupKeyOf(value) {
+  if (isBlankGroupValue(value)) return EMPTY_GROUP_KEY;
+  switch (typeof value) {
+    case "string":
+      return `s:${value}`;
+    case "number":
+      return `n:${String(value)}`;
+    case "boolean":
+      return `b:${value ? "true" : "false"}`;
+    case "bigint":
+      return `i:${String(value)}`;
+    case "symbol":
+      return `y:${String(value)}`;
+    case "function":
+      return `f:${safeString(value)}`;
+    default:
+      break;
+  }
+  if (value instanceof Date) {
+    const time = value.getTime();
+    return `d:${Number.isFinite(time) ? value.toISOString() : "invalid"}`;
+  }
+  return `o:${safeJson(value)}`;
+}
+function safeString(value) {
+  try {
+    return String(value);
+  } catch {
+    return "[unreadable]";
+  }
+}
+function safeJson(value) {
+  try {
+    const json = JSON.stringify(value);
+    return typeof json === "string" ? json : safeString(value);
+  } catch {
+    return safeString(value);
+  }
+}
+var CURRENCY_AND_SPACE = /[\s,$£€¥]/g;
+function coerceGroupNumber(value) {
+  if (isBlankGroupValue(value)) return null;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "boolean") return value ? 1 : 0;
+  if (typeof value === "bigint") {
+    const asNumber = Number(value);
+    return Number.isFinite(asNumber) ? asNumber : null;
+  }
+  if (typeof value !== "string") return null;
+  const cleaned = value.replace(CURRENCY_AND_SPACE, "");
+  if (cleaned === "" || cleaned === "-" || cleaned === "+") return null;
+  const parsed = Number(cleaned);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+var NUMBER_FORMAT = new Intl.NumberFormat("en-US", { maximumFractionDigits: 2 });
+function formatGroupNumber(value) {
+  if (!Number.isFinite(value)) return "\u2014";
+  try {
+    return NUMBER_FORMAT.format(value);
+  } catch {
+    return String(value);
+  }
+}
+function defaultLabelOf(value, emptyLabel) {
+  if (isBlankGroupValue(value)) return emptyLabel;
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return formatGroupNumber(value);
+  if (typeof value === "boolean") return value ? "true" : "false";
+  if (value instanceof Date) {
+    const time = value.getTime();
+    return Number.isFinite(time) ? value.toISOString() : "Invalid Date";
+  }
+  if (typeof value === "object") return safeJson(value);
+  return safeString(value);
+}
+var AGGREGATE_NAMES = {
+  count: { name: "Count", position: "before" },
+  sum: { name: "Sum", position: "before" },
+  average: { name: "Average", position: "before" },
+  min: { name: "Min", position: "before" },
+  max: { name: "Max", position: "before" },
+  empty: { name: "empty", position: "after" },
+  filled: { name: "filled", position: "after" },
+  unique: { name: "unique", position: "after" },
+  checked: { name: "checked", position: "after" },
+  unchecked: { name: "unchecked", position: "after" },
+  percentFilled: { name: "filled", position: "after" }
+};
+function aggregateLabel(kind, value, override) {
+  const naming = AGGREGATE_NAMES[kind] ?? { name: kind, position: "before" };
+  const name = override && override.trim() !== "" ? override : naming.name;
+  const shown = value === null ? "\u2014" : kind === "percentFilled" ? `${formatGroupNumber(value)}%` : formatGroupNumber(value);
+  return naming.position === "before" ? `${name} ${shown}` : `${shown} ${name}`;
+}
+function readValue(row, reader) {
+  try {
+    return reader(row);
+  } catch {
+    return null;
+  }
+}
+function computeAggregate(rows, column) {
+  const kind = column.spec.kind;
+  const raw = rows.map((row) => readValue(row, column.readCell));
+  const total = raw.length;
+  const filled = raw.filter((value2) => !isBlankGroupValue(value2));
+  const numbers = filled.map((value2) => coerceGroupNumber(value2)).filter((value2) => value2 !== null);
+  let value;
+  switch (kind) {
+    case "count":
+      value = total;
+      break;
+    case "sum":
+      value = numbers.length === 0 ? null : numbers.reduce((acc, n) => acc + n, 0);
+      break;
+    case "average":
+      value = numbers.length === 0 ? null : numbers.reduce((acc, n) => acc + n, 0) / numbers.length;
+      break;
+    case "min":
+      value = numbers.length === 0 ? null : numbers.reduce((acc, n) => n < acc ? n : acc);
+      break;
+    case "max":
+      value = numbers.length === 0 ? null : numbers.reduce((acc, n) => n > acc ? n : acc);
+      break;
+    case "empty":
+      value = total - filled.length;
+      break;
+    case "filled":
+      value = filled.length;
+      break;
+    case "unique": {
+      const seen = /* @__PURE__ */ new Set();
+      for (const entry of filled) seen.add(groupKeyOf(entry));
+      value = seen.size;
+      break;
+    }
+    case "checked":
+      value = filled.filter((entry) => entry === true).length;
+      break;
+    case "unchecked":
+      value = filled.filter((entry) => entry === false).length;
+      break;
+    case "percentFilled":
+      value = total === 0 ? null : filled.length / total * 100;
+      break;
+    default:
+      value = null;
+      break;
+  }
+  return { kind, value, label: aggregateLabel(kind, value, column.spec.label) };
+}
+function compareLabels(a, b) {
+  if (a === b) return 0;
+  return a < b ? -1 : 1;
+}
+function compareValues(a, b) {
+  const aNumber = typeof a.value === "number" ? a.value : null;
+  const bNumber = typeof b.value === "number" ? b.value : null;
+  if (aNumber !== null && bNumber !== null && aNumber !== bNumber) return aNumber < bNumber ? -1 : 1;
+  if (typeof a.value === "boolean" && typeof b.value === "boolean" && a.value !== b.value) {
+    return a.value ? 1 : -1;
+  }
+  return compareLabels(a.label, b.label);
+}
+function groupRows(options) {
+  const rows = Array.isArray(options.rows) ? options.rows : [];
+  const emptyLabel = options.emptyLabel ?? DEFAULT_EMPTY_LABEL;
+  const order = options.order ?? "value-asc";
+  const aggregates = options.aggregates ?? {};
+  const labelFor = (value) => {
+    if (!options.labelOf) return defaultLabelOf(value, emptyLabel);
+    if (isBlankGroupValue(value)) {
+      try {
+        const custom = options.labelOf(value);
+        return typeof custom === "string" && custom !== "" ? custom : emptyLabel;
+      } catch {
+        return emptyLabel;
+      }
+    }
+    try {
+      const custom = options.labelOf(value);
+      return typeof custom === "string" ? custom : defaultLabelOf(value, emptyLabel);
+    } catch {
+      return defaultLabelOf(value, emptyLabel);
+    }
+  };
+  const buckets = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const raw = readValue(row, options.readCell);
+    const blank = isBlankGroupValue(raw);
+    const value = blank ? null : raw;
+    const key = groupKeyOf(value);
+    let bucket = buckets.get(key);
+    if (!bucket) {
+      bucket = { key, value, label: labelFor(value), rows: [], seen: buckets.size };
+      buckets.set(key, bucket);
+    }
+    bucket.rows.push(row);
+  }
+  const ordered = [...buckets.values()].sort((a, b) => {
+    const aBlank = a.key === EMPTY_GROUP_KEY;
+    const bBlank = b.key === EMPTY_GROUP_KEY;
+    if (aBlank !== bBlank) return aBlank ? 1 : -1;
+    if (aBlank && bBlank) return 0;
+    switch (order) {
+      case "value-asc":
+        return compareValues(a, b) || a.seen - b.seen;
+      case "value-desc":
+        return -compareValues(a, b) || a.seen - b.seen;
+      case "count-desc":
+        return b.rows.length - a.rows.length || a.seen - b.seen;
+      case "first-seen":
+      default:
+        return a.seen - b.seen;
+    }
+  });
+  const aggregateEntries = Object.entries(aggregates);
+  return ordered.map((bucket, index) => {
+    const results = {};
+    for (const [columnId, column] of aggregateEntries) {
+      if (!column || typeof column.readCell !== "function" || !column.spec) continue;
+      results[columnId] = computeAggregate(bucket.rows, column);
+    }
+    return {
+      key: bucket.key,
+      value: bucket.value,
+      label: bucket.label,
+      rows: bucket.rows,
+      aggregates: results,
+      index
+    };
+  });
+}
+function toggleGroupCollapsed(collapsed, key) {
+  const list = Array.isArray(collapsed) ? collapsed : [];
+  return list.includes(key) ? list.filter((entry) => entry !== key) : [...list, key];
+}
+function isGroupCollapsed(collapsed, key) {
+  return Array.isArray(collapsed) ? collapsed.includes(key) : false;
+}
+function flattenGroups(groups, collapsed) {
+  const out = [];
+  let dataIndex = 0;
+  for (const group of Array.isArray(groups) ? groups : []) {
+    out.push({ kind: "group", group });
+    if (isGroupCollapsed(collapsed, group.key)) continue;
+    for (const row of group.rows) {
+      out.push({ kind: "row", group, row, dataIndex });
+      dataIndex += 1;
+    }
+  }
+  return out;
+}
+function groupSummary(group, rowNoun = "row") {
+  const count = group?.rows?.length ?? 0;
+  const noun = count === 1 ? rowNoun : `${rowNoun}s`;
+  const parts = [`${formatGroupNumber(count)} ${noun}`];
+  for (const result of Object.values(group?.aggregates ?? {})) {
+    if (result?.label) parts.push(result.label);
+  }
+  return parts.join(" \xB7 ");
+}
+//# sourceMappingURL=grouping.cjs.map

package/dist/data-table/grouping.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/data-table/grouping.ts"],"sourcesContent":["/**\n * data-table/grouping.ts — THE grouping model for the canonical data table.\n *\n * \"Group these rows by Status and get collapsible sections with a count and a\n * subtotal on each.\" Champions: Airtable's group-by, Google Sheets' grouped\n * pivot rows, Notion's board/table groups.\n *\n * THE FOUR RULES THIS FILE OBEYS\n *\n * 1. **Pure.** No React, no DOM, no clock, no globals. Rows in, groups out.\n *    That is what makes every clause below testable without a renderer.\n * 2. **Nothing throws.** A `readCell` written by a caller is hostile input: if\n *    it throws, the row is treated as BLANK, never as a crashed table.\n * 3. **Nothing lies.** An aggregate with no values to speak about reports\n *    `value: null` and a label that SAYS so (\"Sum —\"). It never reports `0`,\n *    because \"the sum of nothing\" and \"the sum is zero\" are different facts\n *    and a person reading a group header must be able to tell them apart.\n * 4. **Order is the caller's.** Grouping is stable: within a group the rows\n *    keep the exact order they arrived in. The table already sorted them;\n *    re-sorting here would silently override the user's sort.\n *\n * THE COERCION RULES (the same spirit as the formula engine in\n * `features/data-tables/formulas.ts`, implemented locally so this module stays\n * dependency-free)\n *\n * - **BLANK** is `null`, `undefined` and `\"\"` — all three, because a cleared\n *   text cell holds `\"\"` and a cleared number cell holds `null`, and a person\n *   does not distinguish them. All three land in ONE group, labelled\n *   `(empty)`, and that group sorts LAST in every ordering: a section of\n *   unanswered rows is not the first thing anyone wants to read.\n * - **Numeric strings coerce.** `\"1,234\"`, `\" 42 \"`, `\"$5\"` and `\"3.5\"` are\n *   numbers to an aggregate; `\"n/a\"` is simply not a number and is skipped.\n * - **Booleans are 1 and 0**, so a sum over a checkbox column counts ticks.\n * - **Aggregates skip blanks and non-numbers.** `average` divides by the count\n *   of values that were actually numeric.\n */\n\n// ─── Public types ────────────────────────────────────────────────────────────\n\nexport type GroupAggregateKind =\n    | \"count\"\n    | \"sum\"\n    | \"average\"\n    | \"min\"\n    | \"max\"\n    | \"empty\"\n    | \"filled\"\n    | \"unique\"\n    | \"checked\"\n    | \"unchecked\"\n    | \"percentFilled\";\n\nexport interface GroupAggregateSpec {\n    kind: GroupAggregateKind;\n    label?: string;\n}\n\nexport interface GroupAggregateResult {\n    kind: GroupAggregateKind;\n    /** null when the aggregate has nothing to say (no numeric values at all). */\n    value: number | null;\n    /** A short human sentence fragment for the group row, e.g. \"Sum 4,812.5\". Never a bare number with no name. */\n    label: string;\n}\n\nexport interface TableGroup<T> {\n    /** Stable key for collapse state and React keys. Derived from the raw value, never the display text. */\n    key: string;\n    /** The raw grouping value. */\n    value: unknown;\n    /** What the group header shows. Empty values group together under one explicit label. */\n    label: string;\n    rows: T[];\n    /** Per-column aggregate results, keyed by column id. */\n    aggregates: Record<string, GroupAggregateResult>;\n    /** Group order index. */\n    index: number;\n}\n\nexport type GroupOrder = \"value-asc\" | \"value-desc\" | \"count-desc\" | \"first-seen\";\n\nexport interface GroupAggregateColumn<T> {\n    spec: GroupAggregateSpec;\n    readCell: (row: T) => unknown;\n}\n\nexport interface GroupRowsOptions<T> {\n    rows: T[];\n    /** Column id to group by. */\n    columnId: string;\n    /** Reads the grouping value off a row. */\n    readCell: (row: T) => unknown;\n    /** Turns a raw value into its display label. Defaults to a sensible string rendering. */\n    labelOf?: (value: unknown) => string;\n    /** Per-column aggregates and how to read that column's value. */\n    aggregates?: Record<string, GroupAggregateColumn<T>>;\n    /** Group ordering. Default \"value-asc\". \"count-desc\" is the Airtable default for a status column. */\n    order?: GroupOrder;\n    /** Label for rows whose grouping value is blank. Default \"(empty)\". */\n    emptyLabel?: string;\n}\n\nexport interface GroupedRenderRow<T> {\n    kind: \"group\" | \"row\";\n    group: TableGroup<T>;\n    /** Present only when kind === \"row\". */\n    row?: T;\n    /** Index within the flat list of DATA rows only (group headers do not consume one). */\n    dataIndex?: number;\n}\n\n// ─── Blank, keys, coercion ───────────────────────────────────────────────────\n\nexport const EMPTY_GROUP_KEY = \"empty\";\nconst DEFAULT_EMPTY_LABEL = \"(empty)\";\n\n/** BLANK is `null`, `undefined` and `\"\"` — nothing else. */\nexport function isBlankGroupValue(value: unknown): boolean {\n    return value === null || value === undefined || value === \"\";\n}\n\n/**\n * A key that is stable across renders and collision-free across values that\n * happen to render the same text: the number `3` is `n:3` and the string `\"3\"`\n * is `s:3`, so both are addressable and neither swallows the other.\n */\nexport function groupKeyOf(value: unknown): string {\n    if (isBlankGroupValue(value)) return EMPTY_GROUP_KEY;\n    switch (typeof value) {\n        case \"string\":\n            return `s:${value}`;\n        case \"number\":\n            return `n:${String(value)}`;\n        case \"boolean\":\n            return `b:${value ? \"true\" : \"false\"}`;\n        case \"bigint\":\n            return `i:${String(value)}`;\n        case \"symbol\":\n            return `y:${String(value)}`;\n        case \"function\":\n            return `f:${safeString(value)}`;\n        default:\n            break;\n    }\n    if (value instanceof Date) {\n        const time = value.getTime();\n        return `d:${Number.isFinite(time) ? value.toISOString() : \"invalid\"}`;\n    }\n    return `o:${safeJson(value)}`;\n}\n\nfunction safeString(value: unknown): string {\n    try {\n        return String(value);\n    } catch {\n        return \"[unreadable]\";\n    }\n}\n\nfunction safeJson(value: unknown): string {\n    try {\n        const json = JSON.stringify(value);\n        return typeof json === \"string\" ? json : safeString(value);\n    } catch {\n        return safeString(value);\n    }\n}\n\nconst CURRENCY_AND_SPACE = /[\\s,$£€¥]/g;\n\n/**\n * The local coercion. Blanks and anything that is not a number are `null`\n * (an aggregate skips them); booleans are 1 and 0; a numeric string survives\n * thousands separators, padding and a currency symbol.\n */\nexport function coerceGroupNumber(value: unknown): number | null {\n    if (isBlankGroupValue(value)) return null;\n    if (typeof value === \"number\") return Number.isFinite(value) ? value : null;\n    if (typeof value === \"boolean\") return value ? 1 : 0;\n    if (typeof value === \"bigint\") {\n        const asNumber = Number(value);\n        return Number.isFinite(asNumber) ? asNumber : null;\n    }\n    if (typeof value !== \"string\") return null;\n    const cleaned = value.replace(CURRENCY_AND_SPACE, \"\");\n    if (cleaned === \"\" || cleaned === \"-\" || cleaned === \"+\") return null;\n    const parsed = Number(cleaned);\n    return Number.isFinite(parsed) ? parsed : null;\n}\n\n// ─── Labels ──────────────────────────────────────────────────────────────────\n\nconst NUMBER_FORMAT = new Intl.NumberFormat(\"en-US\", { maximumFractionDigits: 2 });\n\nexport function formatGroupNumber(value: number): string {\n    if (!Number.isFinite(value)) return \"—\";\n    try {\n        return NUMBER_FORMAT.format(value);\n    } catch {\n        return String(value);\n    }\n}\n\nfunction defaultLabelOf(value: unknown, emptyLabel: string): string {\n    if (isBlankGroupValue(value)) return emptyLabel;\n    if (typeof value === \"string\") return value;\n    if (typeof value === \"number\") return formatGroupNumber(value);\n    if (typeof value === \"boolean\") return value ? \"true\" : \"false\";\n    if (value instanceof Date) {\n        const time = value.getTime();\n        return Number.isFinite(time) ? value.toISOString() : \"Invalid Date\";\n    }\n    if (typeof value === \"object\") return safeJson(value);\n    return safeString(value);\n}\n\n/** The aggregate's own name, and which side of the number it sits on. */\nconst AGGREGATE_NAMES: Record<GroupAggregateKind, { name: string; position: \"before\" | \"after\" }> = {\n    count: { name: \"Count\", position: \"before\" },\n    sum: { name: \"Sum\", position: \"before\" },\n    average: { name: \"Average\", position: \"before\" },\n    min: { name: \"Min\", position: \"before\" },\n    max: { name: \"Max\", position: \"before\" },\n    empty: { name: \"empty\", position: \"after\" },\n    filled: { name: \"filled\", position: \"after\" },\n    unique: { name: \"unique\", position: \"after\" },\n    checked: { name: \"checked\", position: \"after\" },\n    unchecked: { name: \"unchecked\", position: \"after\" },\n    percentFilled: { name: \"filled\", position: \"after\" },\n};\n\nfunction aggregateLabel(kind: GroupAggregateKind, value: number | null, override?: string): string {\n    const naming = AGGREGATE_NAMES[kind] ?? { name: kind, position: \"before\" as const };\n    const name = override && override.trim() !== \"\" ? override : naming.name;\n    const shown = value === null ? \"—\" : kind === \"percentFilled\" ? `${formatGroupNumber(value)}%` : formatGroupNumber(value);\n    return naming.position === \"before\" ? `${name} ${shown}` : `${shown} ${name}`;\n}\n\n// ─── Aggregates ──────────────────────────────────────────────────────────────\n\nfunction readValue<T>(row: T, reader: (row: T) => unknown): unknown {\n    try {\n        return reader(row);\n    } catch {\n        return null;\n    }\n}\n\nfunction computeAggregate<T>(rows: T[], column: GroupAggregateColumn<T>): GroupAggregateResult {\n    const kind = column.spec.kind;\n    const raw = rows.map((row) => readValue(row, column.readCell));\n    const total = raw.length;\n    const filled = raw.filter((value) => !isBlankGroupValue(value));\n    const numbers = filled\n        .map((value) => coerceGroupNumber(value))\n        .filter((value): value is number => value !== null);\n\n    let value: number | null;\n    switch (kind) {\n        case \"count\":\n            value = total;\n            break;\n        case \"sum\":\n            value = numbers.length === 0 ? null : numbers.reduce((acc, n) => acc + n, 0);\n            break;\n        case \"average\":\n            value = numbers.length === 0 ? null : numbers.reduce((acc, n) => acc + n, 0) / numbers.length;\n            break;\n        case \"min\":\n            value = numbers.length === 0 ? null : numbers.reduce((acc, n) => (n < acc ? n : acc));\n            break;\n        case \"max\":\n            value = numbers.length === 0 ? null : numbers.reduce((acc, n) => (n > acc ? n : acc));\n            break;\n        case \"empty\":\n            value = total - filled.length;\n            break;\n        case \"filled\":\n            value = filled.length;\n            break;\n        case \"unique\": {\n            const seen = new Set<string>();\n            for (const entry of filled) seen.add(groupKeyOf(entry));\n            value = seen.size;\n            break;\n        }\n        case \"checked\":\n            value = filled.filter((entry) => entry === true).length;\n            break;\n        case \"unchecked\":\n            value = filled.filter((entry) => entry === false).length;\n            break;\n        case \"percentFilled\":\n            value = total === 0 ? null : (filled.length / total) * 100;\n            break;\n        default:\n            value = null;\n            break;\n    }\n\n    return { kind, value, label: aggregateLabel(kind, value, column.spec.label) };\n}\n\n// ─── Grouping ────────────────────────────────────────────────────────────────\n\ninterface Bucket<T> {\n    key: string;\n    value: unknown;\n    label: string;\n    rows: T[];\n    seen: number;\n}\n\nfunction compareLabels(a: string, b: string): number {\n    if (a === b) return 0;\n    return a < b ? -1 : 1;\n}\n\nfunction compareValues<T>(a: Bucket<T>, b: Bucket<T>): number {\n    const aNumber = typeof a.value === \"number\" ? a.value : null;\n    const bNumber = typeof b.value === \"number\" ? b.value : null;\n    if (aNumber !== null && bNumber !== null && aNumber !== bNumber) return aNumber < bNumber ? -1 : 1;\n    if (typeof a.value === \"boolean\" && typeof b.value === \"boolean\" && a.value !== b.value) {\n        return a.value ? 1 : -1;\n    }\n    return compareLabels(a.label, b.label);\n}\n\n/**\n * Groups rows by one column. Row order inside a group is the order they\n * arrived in; the blank group is always last.\n */\nexport function groupRows<T>(options: GroupRowsOptions<T>): TableGroup<T>[] {\n    const rows = Array.isArray(options.rows) ? options.rows : [];\n    const emptyLabel = options.emptyLabel ?? DEFAULT_EMPTY_LABEL;\n    const order: GroupOrder = options.order ?? \"value-asc\";\n    const aggregates = options.aggregates ?? {};\n\n    const labelFor = (value: unknown): string => {\n        if (!options.labelOf) return defaultLabelOf(value, emptyLabel);\n        if (isBlankGroupValue(value)) {\n            // The blank group's label is the caller's `emptyLabel` unless their\n            // own `labelOf` answers with something non-empty for a blank.\n            try {\n                const custom = options.labelOf(value);\n                return typeof custom === \"string\" && custom !== \"\" ? custom : emptyLabel;\n            } catch {\n                return emptyLabel;\n            }\n        }\n        try {\n            const custom = options.labelOf(value);\n            return typeof custom === \"string\" ? custom : defaultLabelOf(value, emptyLabel);\n        } catch {\n            return defaultLabelOf(value, emptyLabel);\n        }\n    };\n\n    const buckets = new Map<string, Bucket<T>>();\n    for (const row of rows) {\n        const raw = readValue(row, options.readCell);\n        const blank = isBlankGroupValue(raw);\n        const value = blank ? null : raw;\n        const key = groupKeyOf(value);\n        let bucket = buckets.get(key);\n        if (!bucket) {\n            bucket = { key, value, label: labelFor(value), rows: [], seen: buckets.size };\n            buckets.set(key, bucket);\n        }\n        bucket.rows.push(row);\n    }\n\n    const ordered = [...buckets.values()].sort((a, b) => {\n        // The blank group is last in EVERY ordering.\n        const aBlank = a.key === EMPTY_GROUP_KEY;\n        const bBlank = b.key === EMPTY_GROUP_KEY;\n        if (aBlank !== bBlank) return aBlank ? 1 : -1;\n        if (aBlank && bBlank) return 0;\n\n        switch (order) {\n            case \"value-asc\":\n                return compareValues(a, b) || a.seen - b.seen;\n            case \"value-desc\":\n                return -compareValues(a, b) || a.seen - b.seen;\n            case \"count-desc\":\n                return b.rows.length - a.rows.length || a.seen - b.seen;\n            case \"first-seen\":\n            default:\n                return a.seen - b.seen;\n        }\n    });\n\n    const aggregateEntries = Object.entries(aggregates);\n    return ordered.map((bucket, index) => {\n        const results: Record<string, GroupAggregateResult> = {};\n        for (const [columnId, column] of aggregateEntries) {\n            if (!column || typeof column.readCell !== \"function\" || !column.spec) continue;\n            results[columnId] = computeAggregate(bucket.rows, column);\n        }\n        return {\n            key: bucket.key,\n            value: bucket.value,\n            label: bucket.label,\n            rows: bucket.rows,\n            aggregates: results,\n            index,\n        };\n    });\n}\n\n// ─── Collapse state ──────────────────────────────────────────────────────────\n\n/** Collapse state as a pure set operation, so the consumer can persist it. */\nexport function toggleGroupCollapsed(collapsed: readonly string[], key: string): string[] {\n    const list = Array.isArray(collapsed) ? collapsed : [];\n    return list.includes(key) ? list.filter((entry) => entry !== key) : [...list, key];\n}\n\nexport function isGroupCollapsed(collapsed: readonly string[], key: string): boolean {\n    return Array.isArray(collapsed) ? collapsed.includes(key) : false;\n}\n\n// ─── Flattening ──────────────────────────────────────────────────────────────\n\n/** Flattens groups into the exact sequence the table renders, honouring collapse. */\nexport function flattenGroups<T>(groups: TableGroup<T>[], collapsed: readonly string[]): GroupedRenderRow<T>[] {\n    const out: GroupedRenderRow<T>[] = [];\n    let dataIndex = 0;\n    for (const group of Array.isArray(groups) ? groups : []) {\n        out.push({ kind: \"group\", group });\n        if (isGroupCollapsed(collapsed, group.key)) continue;\n        for (const row of group.rows) {\n            out.push({ kind: \"row\", group, row, dataIndex });\n            dataIndex += 1;\n        }\n    }\n    return out;\n}\n\n// ─── Header summary ──────────────────────────────────────────────────────────\n\n/** The one-line summary a group header shows after its label, e.g. \"12 rows · Sum 4,812.5\". */\nexport function groupSummary<T>(group: TableGroup<T>, rowNoun = \"row\"): string {\n    const count = group?.rows?.length ?? 0;\n    const noun = count === 1 ? rowNoun : `${rowNoun}s`;\n    const parts = [`${formatGroupNumber(count)} ${noun}`];\n    for (const result of Object.values(group?.aggregates ?? {})) {\n        if (result?.label) parts.push(result.label);\n    }\n    return parts.join(\" · \");\n}\n"],"mappings":"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","names":["value"]}

package/dist/data-table/grouping.d.cts

@@ -0,0 +1,119 @@
+/**
+ * data-table/grouping.ts — THE grouping model for the canonical data table.
+ *
+ * "Group these rows by Status and get collapsible sections with a count and a
+ * subtotal on each." Champions: Airtable's group-by, Google Sheets' grouped
+ * pivot rows, Notion's board/table groups.
+ *
+ * THE FOUR RULES THIS FILE OBEYS
+ *
+ * 1. **Pure.** No React, no DOM, no clock, no globals. Rows in, groups out.
+ *    That is what makes every clause below testable without a renderer.
+ * 2. **Nothing throws.** A `readCell` written by a caller is hostile input: if
+ *    it throws, the row is treated as BLANK, never as a crashed table.
+ * 3. **Nothing lies.** An aggregate with no values to speak about reports
+ *    `value: null` and a label that SAYS so ("Sum —"). It never reports `0`,
+ *    because "the sum of nothing" and "the sum is zero" are different facts
+ *    and a person reading a group header must be able to tell them apart.
+ * 4. **Order is the caller's.** Grouping is stable: within a group the rows
+ *    keep the exact order they arrived in. The table already sorted them;
+ *    re-sorting here would silently override the user's sort.
+ *
+ * THE COERCION RULES (the same spirit as the formula engine in
+ * `features/data-tables/formulas.ts`, implemented locally so this module stays
+ * dependency-free)
+ *
+ * - **BLANK** is `null`, `undefined` and `""` — all three, because a cleared
+ *   text cell holds `""` and a cleared number cell holds `null`, and a person
+ *   does not distinguish them. All three land in ONE group, labelled
+ *   `(empty)`, and that group sorts LAST in every ordering: a section of
+ *   unanswered rows is not the first thing anyone wants to read.
+ * - **Numeric strings coerce.** `"1,234"`, `" 42 "`, `"$5"` and `"3.5"` are
+ *   numbers to an aggregate; `"n/a"` is simply not a number and is skipped.
+ * - **Booleans are 1 and 0**, so a sum over a checkbox column counts ticks.
+ * - **Aggregates skip blanks and non-numbers.** `average` divides by the count
+ *   of values that were actually numeric.
+ */
+type GroupAggregateKind = "count" | "sum" | "average" | "min" | "max" | "empty" | "filled" | "unique" | "checked" | "unchecked" | "percentFilled";
+interface GroupAggregateSpec {
+    kind: GroupAggregateKind;
+    label?: string;
+}
+interface GroupAggregateResult {
+    kind: GroupAggregateKind;
+    /** null when the aggregate has nothing to say (no numeric values at all). */
+    value: number | null;
+    /** A short human sentence fragment for the group row, e.g. "Sum 4,812.5". Never a bare number with no name. */
+    label: string;
+}
+interface TableGroup<T> {
+    /** Stable key for collapse state and React keys. Derived from the raw value, never the display text. */
+    key: string;
+    /** The raw grouping value. */
+    value: unknown;
+    /** What the group header shows. Empty values group together under one explicit label. */
+    label: string;
+    rows: T[];
+    /** Per-column aggregate results, keyed by column id. */
+    aggregates: Record<string, GroupAggregateResult>;
+    /** Group order index. */
+    index: number;
+}
+type GroupOrder = "value-asc" | "value-desc" | "count-desc" | "first-seen";
+interface GroupAggregateColumn<T> {
+    spec: GroupAggregateSpec;
+    readCell: (row: T) => unknown;
+}
+interface GroupRowsOptions<T> {
+    rows: T[];
+    /** Column id to group by. */
+    columnId: string;
+    /** Reads the grouping value off a row. */
+    readCell: (row: T) => unknown;
+    /** Turns a raw value into its display label. Defaults to a sensible string rendering. */
+    labelOf?: (value: unknown) => string;
+    /** Per-column aggregates and how to read that column's value. */
+    aggregates?: Record<string, GroupAggregateColumn<T>>;
+    /** Group ordering. Default "value-asc". "count-desc" is the Airtable default for a status column. */
+    order?: GroupOrder;
+    /** Label for rows whose grouping value is blank. Default "(empty)". */
+    emptyLabel?: string;
+}
+interface GroupedRenderRow<T> {
+    kind: "group" | "row";
+    group: TableGroup<T>;
+    /** Present only when kind === "row". */
+    row?: T;
+    /** Index within the flat list of DATA rows only (group headers do not consume one). */
+    dataIndex?: number;
+}
+declare const EMPTY_GROUP_KEY = "empty";
+/** BLANK is `null`, `undefined` and `""` — nothing else. */
+declare function isBlankGroupValue(value: unknown): boolean;
+/**
+ * A key that is stable across renders and collision-free across values that
+ * happen to render the same text: the number `3` is `n:3` and the string `"3"`
+ * is `s:3`, so both are addressable and neither swallows the other.
+ */
+declare function groupKeyOf(value: unknown): string;
+/**
+ * The local coercion. Blanks and anything that is not a number are `null`
+ * (an aggregate skips them); booleans are 1 and 0; a numeric string survives
+ * thousands separators, padding and a currency symbol.
+ */
+declare function coerceGroupNumber(value: unknown): number | null;
+declare function formatGroupNumber(value: number): string;
+/**
+ * Groups rows by one column. Row order inside a group is the order they
+ * arrived in; the blank group is always last.
+ */
+declare function groupRows<T>(options: GroupRowsOptions<T>): TableGroup<T>[];
+/** Collapse state as a pure set operation, so the consumer can persist it. */
+declare function toggleGroupCollapsed(collapsed: readonly string[], key: string): string[];
+declare function isGroupCollapsed(collapsed: readonly string[], key: string): boolean;
+/** Flattens groups into the exact sequence the table renders, honouring collapse. */
+declare function flattenGroups<T>(groups: TableGroup<T>[], collapsed: readonly string[]): GroupedRenderRow<T>[];
+/** The one-line summary a group header shows after its label, e.g. "12 rows · Sum 4,812.5". */
+declare function groupSummary<T>(group: TableGroup<T>, rowNoun?: string): string;
+
+export { EMPTY_GROUP_KEY, type GroupAggregateColumn, type GroupAggregateKind, type GroupAggregateResult, type GroupAggregateSpec, type GroupOrder, type GroupRowsOptions, type GroupedRenderRow, type TableGroup, coerceGroupNumber, flattenGroups, formatGroupNumber, groupKeyOf, groupRows, groupSummary, isBlankGroupValue, isGroupCollapsed, toggleGroupCollapsed };

package/dist/data-table/grouping.d.ts

@@ -0,0 +1,119 @@
+/**
+ * data-table/grouping.ts — THE grouping model for the canonical data table.
+ *
+ * "Group these rows by Status and get collapsible sections with a count and a
+ * subtotal on each." Champions: Airtable's group-by, Google Sheets' grouped
+ * pivot rows, Notion's board/table groups.
+ *
+ * THE FOUR RULES THIS FILE OBEYS
+ *
+ * 1. **Pure.** No React, no DOM, no clock, no globals. Rows in, groups out.
+ *    That is what makes every clause below testable without a renderer.
+ * 2. **Nothing throws.** A `readCell` written by a caller is hostile input: if
+ *    it throws, the row is treated as BLANK, never as a crashed table.
+ * 3. **Nothing lies.** An aggregate with no values to speak about reports
+ *    `value: null` and a label that SAYS so ("Sum —"). It never reports `0`,
+ *    because "the sum of nothing" and "the sum is zero" are different facts
+ *    and a person reading a group header must be able to tell them apart.
+ * 4. **Order is the caller's.** Grouping is stable: within a group the rows
+ *    keep the exact order they arrived in. The table already sorted them;
+ *    re-sorting here would silently override the user's sort.
+ *
+ * THE COERCION RULES (the same spirit as the formula engine in
+ * `features/data-tables/formulas.ts`, implemented locally so this module stays
+ * dependency-free)
+ *
+ * - **BLANK** is `null`, `undefined` and `""` — all three, because a cleared
+ *   text cell holds `""` and a cleared number cell holds `null`, and a person
+ *   does not distinguish them. All three land in ONE group, labelled
+ *   `(empty)`, and that group sorts LAST in every ordering: a section of
+ *   unanswered rows is not the first thing anyone wants to read.
+ * - **Numeric strings coerce.** `"1,234"`, `" 42 "`, `"$5"` and `"3.5"` are
+ *   numbers to an aggregate; `"n/a"` is simply not a number and is skipped.
+ * - **Booleans are 1 and 0**, so a sum over a checkbox column counts ticks.
+ * - **Aggregates skip blanks and non-numbers.** `average` divides by the count
+ *   of values that were actually numeric.
+ */
+type GroupAggregateKind = "count" | "sum" | "average" | "min" | "max" | "empty" | "filled" | "unique" | "checked" | "unchecked" | "percentFilled";
+interface GroupAggregateSpec {
+    kind: GroupAggregateKind;
+    label?: string;
+}
+interface GroupAggregateResult {
+    kind: GroupAggregateKind;
+    /** null when the aggregate has nothing to say (no numeric values at all). */
+    value: number | null;
+    /** A short human sentence fragment for the group row, e.g. "Sum 4,812.5". Never a bare number with no name. */
+    label: string;
+}
+interface TableGroup<T> {
+    /** Stable key for collapse state and React keys. Derived from the raw value, never the display text. */
+    key: string;
+    /** The raw grouping value. */
+    value: unknown;
+    /** What the group header shows. Empty values group together under one explicit label. */
+    label: string;
+    rows: T[];
+    /** Per-column aggregate results, keyed by column id. */
+    aggregates: Record<string, GroupAggregateResult>;
+    /** Group order index. */
+    index: number;
+}
+type GroupOrder = "value-asc" | "value-desc" | "count-desc" | "first-seen";
+interface GroupAggregateColumn<T> {
+    spec: GroupAggregateSpec;
+    readCell: (row: T) => unknown;
+}
+interface GroupRowsOptions<T> {
+    rows: T[];
+    /** Column id to group by. */
+    columnId: string;
+    /** Reads the grouping value off a row. */
+    readCell: (row: T) => unknown;
+    /** Turns a raw value into its display label. Defaults to a sensible string rendering. */
+    labelOf?: (value: unknown) => string;
+    /** Per-column aggregates and how to read that column's value. */
+    aggregates?: Record<string, GroupAggregateColumn<T>>;
+    /** Group ordering. Default "value-asc". "count-desc" is the Airtable default for a status column. */
+    order?: GroupOrder;
+    /** Label for rows whose grouping value is blank. Default "(empty)". */
+    emptyLabel?: string;
+}
+interface GroupedRenderRow<T> {
+    kind: "group" | "row";
+    group: TableGroup<T>;
+    /** Present only when kind === "row". */
+    row?: T;
+    /** Index within the flat list of DATA rows only (group headers do not consume one). */
+    dataIndex?: number;
+}
+declare const EMPTY_GROUP_KEY = "empty";
+/** BLANK is `null`, `undefined` and `""` — nothing else. */
+declare function isBlankGroupValue(value: unknown): boolean;
+/**
+ * A key that is stable across renders and collision-free across values that
+ * happen to render the same text: the number `3` is `n:3` and the string `"3"`
+ * is `s:3`, so both are addressable and neither swallows the other.
+ */
+declare function groupKeyOf(value: unknown): string;
+/**
+ * The local coercion. Blanks and anything that is not a number are `null`
+ * (an aggregate skips them); booleans are 1 and 0; a numeric string survives
+ * thousands separators, padding and a currency symbol.
+ */
+declare function coerceGroupNumber(value: unknown): number | null;
+declare function formatGroupNumber(value: number): string;
+/**
+ * Groups rows by one column. Row order inside a group is the order they
+ * arrived in; the blank group is always last.
+ */
+declare function groupRows<T>(options: GroupRowsOptions<T>): TableGroup<T>[];
+/** Collapse state as a pure set operation, so the consumer can persist it. */
+declare function toggleGroupCollapsed(collapsed: readonly string[], key: string): string[];
+declare function isGroupCollapsed(collapsed: readonly string[], key: string): boolean;
+/** Flattens groups into the exact sequence the table renders, honouring collapse. */
+declare function flattenGroups<T>(groups: TableGroup<T>[], collapsed: readonly string[]): GroupedRenderRow<T>[];
+/** The one-line summary a group header shows after its label, e.g. "12 rows · Sum 4,812.5". */
+declare function groupSummary<T>(group: TableGroup<T>, rowNoun?: string): string;
+
+export { EMPTY_GROUP_KEY, type GroupAggregateColumn, type GroupAggregateKind, type GroupAggregateResult, type GroupAggregateSpec, type GroupOrder, type GroupRowsOptions, type GroupedRenderRow, type TableGroup, coerceGroupNumber, flattenGroups, formatGroupNumber, groupKeyOf, groupRows, groupSummary, isBlankGroupValue, isGroupCollapsed, toggleGroupCollapsed };