@ai-matrx/design-system 0.25.0 → 0.26.0

package/dist/data-table/index.cjs

@@ -5227,10 +5227,10 @@ function passesColumnFilter(value, filter) {
         if (raw === "") return false;
         const normalized = raw.replace(/[^0-9.-]/g, "");
         if (normalized === "") return false;
-        const n = typeof value === "number" ? value : Number(normalized);
-        if (!Number.isFinite(n)) return false;
-        if (filter.min !== void 0 && n < filter.min) return false;
-        if (filter.max !== void 0 && n > filter.max) return false;
+        const n2 = typeof value === "number" ? value : Number(normalized);
+        if (!Number.isFinite(n2)) return false;
+        if (filter.min !== void 0 && n2 < filter.min) return false;
+        if (filter.max !== void 0 && n2 > filter.max) return false;
         return true;
       }
     }
@@ -5293,26 +5293,26 @@ function filterAndSortRows(rows, columns, columnFilters, sort, globalSearch, any
   return result;
 }
 function countActiveColumnFilters(filters) {
-  let n = 0;
+  let n2 = 0;
   for (const f of Object.values(filters)) {
     if (!f) continue;
     switch (f.kind) {
       case "text":
-        if (f.value.trim() || f.mode && f.mode !== "contains") n += 1;
+        if (f.value.trim() || f.mode && f.mode !== "contains") n2 += 1;
         break;
       case "select":
         if (f.values !== void 0 || f.value && f.value !== "__all__")
-          n += 1;
+          n2 += 1;
         break;
       case "boolean":
-        n += 1;
+        n2 += 1;
         break;
       case "number":
-        if (f.min !== void 0 || f.max !== void 0) n += 1;
+        if (f.min !== void 0 || f.max !== void 0) n2 += 1;
         break;
     }
   }
-  return n;
+  return n2;
 }
 function isColumnFilterActive(filter) {
   if (!filter) return false;
@@ -5591,8 +5591,8 @@ function parseLayeredFilters(raw) {
   }
 }
 function positiveInt(raw, fallback) {
-  const n = raw ? Number.parseInt(raw, 10) : Number.NaN;
-  return Number.isFinite(n) && n > 0 ? n : fallback;
+  const n2 = raw ? Number.parseInt(raw, 10) : Number.NaN;
+  return Number.isFinite(n2) && n2 > 0 ? n2 : fallback;
 }
 function tableUrlParamPrefix(tableId) {
   if (!/^[a-z][a-z0-9-]{0,63}$/.test(tableId)) {
@@ -5931,6 +5931,95 @@ var CommandShortcut = ({
 };
 CommandShortcut.displayName = "CommandShortcut";
 
+// src/data-table/facets.ts
+var MAX_LISTABLE_FACET_LENGTH = 300;
+var DEFAULT_FACET_LIMIT = 200;
+var MAX_FACET_LIMIT = 500;
+function facetText(raw) {
+  if (raw === null || raw === void 0) return "";
+  if (typeof raw === "object") {
+    try {
+      return JSON.stringify(raw);
+    } catch {
+      return String(raw);
+    }
+  }
+  return String(raw);
+}
+function computeColumnFacets(args) {
+  const { columnId: columnId2, rows, readValue: readValue2 } = args;
+  const limit = Math.min(Math.max(args.limit ?? DEFAULT_FACET_LIMIT, 1), MAX_FACET_LIMIT);
+  const counts = /* @__PURE__ */ new Map();
+  const longValues = /* @__PURE__ */ new Set();
+  let blank = 0;
+  let maxLength = 0;
+  for (const row of rows) {
+    let raw;
+    try {
+      raw = readValue2(row, columnId2);
+    } catch {
+      raw = void 0;
+    }
+    const trimmed = facetText(raw).trim();
+    if (trimmed === "") {
+      blank += 1;
+      continue;
+    }
+    if (trimmed.length > maxLength) maxLength = trimmed.length;
+    if (trimmed.length > MAX_LISTABLE_FACET_LENGTH) {
+      longValues.add(trimmed);
+      continue;
+    }
+    counts.set(trimmed, (counts.get(trimmed) ?? 0) + 1);
+  }
+  const values = [...counts.entries()].map(([value, count]) => ({ value, count })).sort((a, b) => b.count - a.count || a.value.localeCompare(b.value)).slice(0, limit);
+  return {
+    columnId: columnId2,
+    totalRows: rows.length,
+    filled: rows.length - blank,
+    blank,
+    distinctCount: counts.size + longValues.size,
+    maxLength,
+    unlistable: longValues.size,
+    limit,
+    truncated: counts.size > limit,
+    values,
+    answeredBy: "local",
+    complete: args.complete ?? true
+  };
+}
+function localFacetsAreComplete(loadedRowCount, total) {
+  if (total === void 0 || !Number.isFinite(total) || total < 0) return false;
+  return loadedRowCount >= total;
+}
+var NUMBERS = new Intl.NumberFormat("en-US");
+function n(value) {
+  try {
+    return NUMBERS.format(value);
+  } catch {
+    return String(value);
+  }
+}
+function describeFacetSource(facets, noun = "row") {
+  if (!facets) return "";
+  const plural2 = `${noun}s`;
+  if (!facets.complete) {
+    return `These counts cover the ${n(facets.totalRows)} ${plural2} loaded here, not the whole table.`;
+  }
+  if (facets.truncated) {
+    return `Showing the ${n(facets.values.length)} most common of ${n(facets.distinctCount)} values.`;
+  }
+  if (facets.unlistable > 0) {
+    return `${n(facets.unlistable)} ${facets.unlistable === 1 ? "value is" : "values are"} too long to list. Match text instead to reach ${facets.unlistable === 1 ? "it" : "them"}.`;
+  }
+  return "";
+}
+var FACETS_LOADING_NOTICE = "Counting values\u2026";
+function describeFacetFailure(error) {
+  const detail = error instanceof Error ? error.message : String(error ?? "");
+  return detail ? `The values in this column could not be counted: ${detail} Match text instead.` : "The values in this column could not be counted. Match text instead.";
+}
+
 // src/data-table/column-marker.ts
 var MARKER_ACCESSORS = {
   favorite: "favorite",
@@ -5998,6 +6087,10 @@ function ColumnHeaderCell({
   filterFooterHint,
   allowNegation = false,
   allowNullModes = false,
+  facets,
+  facetsLoading = false,
+  facetsError,
+  onFilterOpen,
   reorderColumn
 }) {
   const reorderEnabled = reorderColumn !== void 0;
@@ -6032,6 +6125,11 @@ function ColumnHeaderCell({
       setPendingNegation(filterValue?.negated ?? false);
     }
   }, [filterOpen, filterValue]);
+  const notifyOpen = (0, import_react13.useRef)(onFilterOpen);
+  notifyOpen.current = onFilterOpen;
+  (0, import_react13.useEffect)(() => {
+    if (filterOpen) notifyOpen.current?.();
+  }, [filterOpen]);
   const applyFilter = () => {
     onFilterChange(draftFilter);
     setFilterOpen(false);
@@ -6126,6 +6224,9 @@ function ColumnHeaderCell({
             selectOptions,
             selectSingle,
             selectAllowCustom,
+            facets: facets ?? null,
+            facetsLoading,
+            ...facetsError === void 0 ? {} : { facetsError },
             ...markerLabels ? {
               booleanLabels: {
                 all: "All",
@@ -6350,8 +6451,43 @@ function FilterBody({
   selectSingle = false,
   selectAllowCustom = false,
   allowNullModes = false,
-  booleanLabels
+  booleanLabels,
+  facets = null,
+  facetsLoading = false,
+  facetsError
 }) {
+  const checklist = facetsLoading || facetsError || facets && (facets.values.length > 0 || facets.blank > 0) ? /* @__PURE__ */ (0, import_jsx_runtime31.jsx)(
+    FacetChecklist,
+    {
+      facets,
+      loading: facetsLoading,
+      ...facetsError === void 0 ? {} : { error: facetsError },
+      value,
+      onChange
+    }
+  ) : null;
+  if (checklist && kind === "select" && facets && facets.values.length > 0) {
+    return /* @__PURE__ */ (0, import_jsx_runtime31.jsx)("div", { className: "space-y-2", children: checklist });
+  }
+  if (checklist) {
+    return /* @__PURE__ */ (0, import_jsx_runtime31.jsxs)("div", { className: "space-y-2", children: [
+      checklist,
+      /* @__PURE__ */ (0, import_jsx_runtime31.jsx)("div", { className: "h-px bg-border" }),
+      /* @__PURE__ */ (0, import_jsx_runtime31.jsx)(
+        FilterBody,
+        {
+          kind,
+          value,
+          onChange,
+          selectOptions,
+          selectSingle,
+          selectAllowCustom,
+          allowNullModes,
+          ...booleanLabels === void 0 ? {} : { booleanLabels }
+        }
+      )
+    ] });
+  }
   if (kind === "text") {
     const text = value?.kind === "text" ? value.value : "";
     const mode = (value?.kind === "text" ? value.mode : void 0) ?? "contains";
@@ -6462,6 +6598,112 @@ function FilterBody({
   }
   return /* @__PURE__ */ (0, import_jsx_runtime31.jsx)(NumberFilterBody, { value, onChange });
 }
+function FacetChecklist({
+  facets,
+  loading,
+  error,
+  value,
+  onChange
+}) {
+  const [query, setQuery] = (0, import_react13.useState)("");
+  const selected = value?.kind === "select" ? value.values ?? (value.value && value.value !== "__all__" ? [value.value] : []) : [];
+  const selectedSet = new Set(selected);
+  const rows = (0, import_react13.useMemo)(() => {
+    if (!facets) return [];
+    const listed = facets.values.map((entry) => ({
+      value: entry.value,
+      label: entry.value,
+      count: entry.count
+    }));
+    const withBlank = facets.blank > 0 ? [{ value: "", label: "(empty)", count: facets.blank }, ...listed] : listed;
+    const q = query.trim().toLowerCase();
+    if (!q) return withBlank;
+    return withBlank.filter((row) => row.label.toLowerCase().includes(q));
+  }, [facets, query]);
+  const toggle = (candidate) => {
+    const next = new Set(selectedSet);
+    if (next.has(candidate)) next.delete(candidate);
+    else next.add(candidate);
+    const values = [...next];
+    onChange(
+      values.length === 0 ? void 0 : { kind: "select", value: values[0] ?? "", values }
+    );
+  };
+  const notice = error ?? (loading ? FACETS_LOADING_NOTICE : describeFacetSource(facets));
+  return /* @__PURE__ */ (0, import_jsx_runtime31.jsxs)("div", { className: "space-y-1.5", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime31.jsx)("p", { className: "px-1 text-[11px] font-medium uppercase tracking-wider text-muted-foreground", children: "Values" }),
+    facets && facets.values.length + (facets.blank > 0 ? 1 : 0) > 8 ? /* @__PURE__ */ (0, import_jsx_runtime31.jsx)(
+      Input,
+      {
+        "data-matrx-filter-autofocus": true,
+        value: query,
+        onChange: (event) => setQuery(event.target.value),
+        placeholder: "Find a value\u2026",
+        className: "h-7 text-sm",
+        style: { fontSize: "16px" }
+      }
+    ) : null,
+    rows.length > 0 ? /* @__PURE__ */ (0, import_jsx_runtime31.jsx)("ul", { className: "max-h-56 space-y-0.5 overflow-y-auto", "data-matrx-facet-list": "true", children: rows.map((row) => {
+      const checked = selectedSet.has(row.value);
+      return /* @__PURE__ */ (0, import_jsx_runtime31.jsx)("li", { children: /* @__PURE__ */ (0, import_jsx_runtime31.jsxs)(
+        "button",
+        {
+          type: "button",
+          role: "checkbox",
+          "aria-checked": checked,
+          "data-matrx-facet-value": row.value === "" ? "__blank__" : row.value,
+          onClick: () => toggle(row.value),
+          className: cn(
+            "flex w-full items-center gap-2 rounded px-1.5 py-1 text-left text-xs hover:bg-muted",
+            checked && "bg-primary/10"
+          ),
+          children: [
+            /* @__PURE__ */ (0, import_jsx_runtime31.jsx)(
+              "span",
+              {
+                "aria-hidden": true,
+                className: cn(
+                  "flex h-3.5 w-3.5 shrink-0 items-center justify-center rounded-[3px] border",
+                  checked ? "border-primary bg-primary text-primary-foreground" : "border-border"
+                ),
+                children: checked ? /* @__PURE__ */ (0, import_jsx_runtime31.jsx)(Check, { className: "h-2.5 w-2.5" }) : null
+              }
+            ),
+            /* @__PURE__ */ (0, import_jsx_runtime31.jsx)("span", { className: cn("min-w-0 flex-1 truncate", row.value === "" && "italic text-muted-foreground"), children: row.label }),
+            /* @__PURE__ */ (0, import_jsx_runtime31.jsx)(
+              "span",
+              {
+                "data-matrx-facet-count": String(row.count),
+                className: "shrink-0 tabular-nums text-[11px] text-muted-foreground",
+                children: row.count.toLocaleString("en-US")
+              }
+            )
+          ]
+        }
+      ) }, row.value === "" ? "__blank__" : row.value);
+    }) }) : loading ? null : /* @__PURE__ */ (0, import_jsx_runtime31.jsx)("p", { className: "px-1 text-[11px] text-muted-foreground", children: query.trim() ? "No value matches that." : "This column has no values yet." }),
+    notice ? /* @__PURE__ */ (0, import_jsx_runtime31.jsx)(
+      "p",
+      {
+        "data-matrx-facet-notice": "true",
+        className: cn(
+          "px-1 text-[11px] leading-snug",
+          error ? "text-amber-700 dark:text-amber-400" : "text-muted-foreground"
+        ),
+        children: notice
+      }
+    ) : null,
+    selected.length > 0 ? /* @__PURE__ */ (0, import_jsx_runtime31.jsx)(
+      "button",
+      {
+        type: "button",
+        onClick: () => onChange(void 0),
+        className: "px-1 text-[11px] text-muted-foreground underline-offset-2 hover:underline",
+        children: "Clear selection"
+      }
+    ) : null
+  ] });
+}
 function SearchableSelectFilter({
   selected,
   options,
@@ -6648,8 +6890,8 @@ function NumberFilterBody({
 }
 function parseOptionalNumber(raw) {
   if (raw.trim() === "") return void 0;
-  const n = Number(raw.replace(/[^0-9.-]/g, ""));
-  return Number.isFinite(n) ? n : void 0;
+  const n2 = Number(raw.replace(/[^0-9.-]/g, ""));
+  return Number.isFinite(n2) ? n2 : void 0;
 }
 
 // src/data-table/ColumnResizeHandle.tsx
@@ -6961,16 +7203,16 @@ function computeAggregate(rows, column) {
       value = total;
       break;
     case "sum":
-      value = numbers.length === 0 ? null : numbers.reduce((acc, n) => acc + n, 0);
+      value = numbers.length === 0 ? null : numbers.reduce((acc, n2) => acc + n2, 0);
       break;
     case "average":
-      value = numbers.length === 0 ? null : numbers.reduce((acc, n) => acc + n, 0) / numbers.length;
+      value = numbers.length === 0 ? null : numbers.reduce((acc, n2) => acc + n2, 0) / numbers.length;
       break;
     case "min":
-      value = numbers.length === 0 ? null : numbers.reduce((acc, n) => n < acc ? n : acc);
+      value = numbers.length === 0 ? null : numbers.reduce((acc, n2) => n2 < acc ? n2 : acc);
       break;
     case "max":
-      value = numbers.length === 0 ? null : numbers.reduce((acc, n) => n > acc ? n : acc);
+      value = numbers.length === 0 ? null : numbers.reduce((acc, n2) => n2 > acc ? n2 : acc);
       break;
     case "empty":
       value = total - filled.length;
@@ -7394,7 +7636,7 @@ function moveSelection(current, move, rowIds, fieldNames) {
   if (r === -1 || c === -1) return first;
   const lastRow = rowIds.length - 1;
   const lastCol = fieldNames.length - 1;
-  const clamp = (n, max) => Math.min(Math.max(n, 0), max);
+  const clamp = (n2, max) => Math.min(Math.max(n2, 0), max);
   switch (move) {
     case "up":
       r = clamp(r - 1, lastRow);
@@ -7526,14 +7768,14 @@ function parseClipboardGrid(text) {
   let row = [];
   let cell = "";
   let i = 0;
-  const n = text.length;
-  while (i < n) {
+  const n2 = text.length;
+  while (i < n2) {
     const ch = text[i];
     if (cell === "" && ch === '"') {
       let j = i + 1;
       let out = "";
       let closed = false;
-      while (j < n) {
+      while (j < n2) {
         const c = text[j];
         if (c === '"') {
           if (text[j + 1] === '"') {
@@ -7548,10 +7790,10 @@ function parseClipboardGrid(text) {
         out += c;
         j += 1;
       }
-      if (closed && (j >= n || text[j] === "	" || text[j] === "\n" || text[j] === "\r")) {
+      if (closed && (j >= n2 || text[j] === "	" || text[j] === "\n" || text[j] === "\r")) {
         cell = out;
         i = j;
-        if (i >= n) break;
+        if (i >= n2) break;
         const d = text[i];
         if (d === "	") {
           row.push(cell);
@@ -7587,7 +7829,7 @@ function parseClipboardGrid(text) {
     cell += ch;
     i += 1;
   }
-  const endedOnBreak = n > 0 && (text[n - 1] === "\n" || text[n - 1] === "\r");
+  const endedOnBreak = n2 > 0 && (text[n2 - 1] === "\n" || text[n2 - 1] === "\r");
   if (!endedOnBreak) {
     row.push(cell);
     rows.push(row);
@@ -7666,11 +7908,11 @@ function directionOf(source, target) {
   return null;
 }
 function tileIndex(i, a, b) {
-  const n = b - a + 1;
-  if (n <= 0) return a;
+  const n2 = b - a + 1;
+  if (n2 <= 0) return a;
   if (i >= a && i <= b) return i;
-  if (i > b) return a + (i - a) % n;
-  return b - (a - 1 - i) % n;
+  if (i > b) return a + (i - a) % n2;
+  return b - (a - 1 - i) % n2;
 }
 function isFiniteNumber(v) {
   return typeof v === "number" && Number.isFinite(v);
@@ -8015,6 +8257,26 @@ function useSpreadsheetGrid(options) {
     for (let i = 0; i < columnIds.length; i += 1) map.set(columnIds[i], i);
     return map;
   }, [columnIds]);
+  const screenPatches = (0, import_react15.useCallback)(
+    (patches) => {
+      const validate = optionsRef.current?.validateCell;
+      if (!validate) return { accepted: patches, refusals: [] };
+      const accepted = [];
+      const refusals = [];
+      for (const patch of patches) {
+        let reason;
+        try {
+          reason = validate({ rowId: patch.rowId, columnId: patch.columnId, value: patch.value });
+        } catch {
+          reason = void 0;
+        }
+        if (reason) refusals.push({ columnId: patch.columnId, reason });
+        else accepted.push(patch);
+      }
+      return { accepted, refusals };
+    },
+    []
+  );
   const applyPatches = (0, import_react15.useCallback)(
     async (patches, intent, label) => {
       const current = optionsRef.current;
@@ -8071,9 +8333,10 @@ function useSpreadsheetGrid(options) {
       ...base,
       range: { top: bounds.r0, left: bounds.c0, bottom: bounds.r1, right: bounds.c1 }
     });
-    await applyPatches(result.patches, "fill-down", "Filled down");
-    announceSkips(result.skipped, result.summary);
-  }, [fillRequestBase, bounds, applyPatches, announceSkips]);
+    const screened = screenPatches(result.patches);
+    await applyPatches(screened.accepted, "fill-down", "Filled down");
+    announceSkips([...result.skipped, ...screened.refusals], result.summary);
+  }, [fillRequestBase, bounds, applyPatches, announceSkips, screenPatches]);
   const doClear = (0, import_react15.useCallback)(async () => {
     const current = optionsRef.current;
     if (!current || !bounds) return;
@@ -8094,9 +8357,13 @@ function useSpreadsheetGrid(options) {
         patches.push({ rowId, columnId: columnId2, value: null });
       }
     }
-    await applyPatches(patches, "clear", "Cleared");
-    announceSkips(skipped, `Cleared ${patches.length} cells.`);
-  }, [bounds, applyPatches, announceSkips]);
+    const screened = screenPatches(patches);
+    await applyPatches(screened.accepted, "clear", "Cleared");
+    announceSkips(
+      [...skipped, ...screened.refusals],
+      `Cleared ${screened.accepted.length} cells.`
+    );
+  }, [bounds, applyPatches, announceSkips, screenPatches]);
   const doUndo = (0, import_react15.useCallback)(async () => {
     const taken = popUndo(stack);
     if (!taken.entry) return;
@@ -8181,6 +8448,14 @@ function useSpreadsheetGrid(options) {
         case "escape":
           setRange(null);
           return;
+        case "edit":
+        case "editSeeded": {
+          const focused = range?.focus;
+          if (!focused || !current.onEditRequest) return;
+          const seed = action.kind === "editSeeded" ? action.seed : null;
+          if (current.onEditRequest(focused, seed)) event.preventDefault();
+          return;
+        }
         default:
           return;
       }
@@ -8195,6 +8470,13 @@ function useSpreadsheetGrid(options) {
     );
     return gridToTsv(grid);
   }, [range, rowIds, columnIds]);
+  const selectionAddresses = (0, import_react15.useCallback)(() => {
+    if (!range || !bounds) return { rowIds: [], columnIds: [] };
+    return {
+      rowIds: rowIds.slice(bounds.r0, bounds.r1 + 1),
+      columnIds: columnIds.slice(bounds.c0, bounds.c1 + 1)
+    };
+  }, [range, bounds, rowIds, columnIds]);
   const onCopy = (0, import_react15.useCallback)(
     (event) => {
       if (!optionsRef.current || !range || targetsAnEditor(event.target)) return;
@@ -8250,11 +8532,12 @@ function useSpreadsheetGrid(options) {
           patches.push({ rowId, columnId: columnId2, value: line[c] ?? null });
         }
       }
-      void applyPatches(patches, "paste", "Pasted");
+      const screened = screenPatches(patches);
+      void applyPatches(screened.accepted, "paste", "Pasted");
       const tail = outside > 0 ? ` ${outside} landed past the edge of the table and were ignored.` : "";
-      announceSkips(skipped, `Pasted ${patches.length} cells.${tail}`);
+      announceSkips([...skipped, ...screened.refusals], `Pasted ${screened.accepted.length} cells.${tail}`);
     },
-    [range, rowIds, columnIds, applyPatches, announceSkips]
+    [range, rowIds, columnIds, applyPatches, announceSkips, screenPatches]
   );
   const cellProps = (0, import_react15.useCallback)(
     (rowId, columnId2) => {
@@ -8273,6 +8556,10 @@ function useSpreadsheetGrid(options) {
         onMouseDown: (event) => {
           if (event.button !== 0) return;
           event.preventDefault();
+          const origin = event.currentTarget;
+          if (typeof HTMLElement !== "undefined" && origin instanceof HTMLElement) {
+            origin.closest('[data-matrx-table-spreadsheet="true"]')?.focus({ preventScroll: true });
+          }
           setRange(
             (previous) => event.shiftKey && previous ? { anchor: previous.anchor, focus: address } : { anchor: address, focus: address }
           );
@@ -8334,12 +8621,13 @@ function useSpreadsheetGrid(options) {
         source: { top: source.r0, left: source.c0, bottom: source.r1, right: source.c1 },
         target
       });
-      void applyPatches(result.patches, "fill", "Filled");
-      announceSkips(result.skipped, result.summary);
+      const screened = screenPatches(result.patches);
+      void applyPatches(screened.accepted, "fill", "Filled");
+      announceSkips([...result.skipped, ...screened.refusals], result.summary);
     };
     window.addEventListener("mouseup", commit);
     return () => window.removeEventListener("mouseup", commit);
-  }, [options, fillRequestBase, applyPatches, announceSkips]);
+  }, [options, fillRequestBase, applyPatches, announceSkips, screenPatches]);
   return {
     range,
     bounds,
@@ -8355,17 +8643,19 @@ function useSpreadsheetGrid(options) {
     isFillHandleCell,
     startFillDrag,
     canUndo: stack.past.length > 0,
-    canRedo: stack.future.length > 0
+    canRedo: stack.future.length > 0,
+    selectionTsv: selectionAsTsv,
+    selectionAddresses
   };
 }
 
 // src/data-table/coverage.ts
 var PARTIAL_BADGE = "Partial";
 var UNKNOWN_TOTAL_BADGE = "Unknown total";
-var NUMBERS = new Intl.NumberFormat("en-US");
+var NUMBERS2 = new Intl.NumberFormat("en-US");
 function formatNumber(value) {
   try {
-    return NUMBERS.format(value);
+    return NUMBERS2.format(value);
   } catch {
     return String(value);
   }
@@ -9563,8 +9853,8 @@ function toNumber(value) {
   if (typeof value === "string") {
     const cleaned = value.replace(/[,\s$€£¥%]/g, "");
     if (cleaned === "") return null;
-    const n = Number(cleaned);
-    return Number.isFinite(n) ? n : null;
+    const n2 = Number(cleaned);
+    return Number.isFinite(n2) ? n2 : null;
   }
   return null;
 }
@@ -9602,14 +9892,14 @@ function toList(value) {
   }
   return null;
 }
-function groupedNumber(n, options) {
+function groupedNumber(n2, options) {
   return new Intl.NumberFormat(void 0, {
     useGrouping: options.useGrouping !== false,
     ...options.precision != null ? {
       minimumFractionDigits: options.precision,
       maximumFractionDigits: options.precision
     } : { maximumFractionDigits: 10 }
-  }).format(n);
+  }).format(n2);
 }
 function affix(text, options) {
   return `${options.prefix ?? ""}${text}${options.suffix ?? ""}`;
@@ -9743,8 +10033,8 @@ var DEFS = [
     numericAlign: true,
     optionKeys: ["useGrouping", "precision", "prefix", "suffix"],
     format: (v, o) => {
-      const n = toNumber(v);
-      return n === null ? null : affix(groupedNumber(n, o), o);
+      const n2 = toNumber(v);
+      return n2 === null ? null : affix(groupedNumber(n2, o), o);
     },
     parse: (raw) => toNumber(raw)
   },
@@ -9759,9 +10049,9 @@ var DEFS = [
     numericAlign: true,
     optionKeys: ["precision", "useGrouping", "prefix", "suffix"],
     format: (v, o) => {
-      const n = toNumber(v);
-      if (n === null) return null;
-      return affix(groupedNumber(n, { ...o, precision: o.precision ?? 2 }), o);
+      const n2 = toNumber(v);
+      if (n2 === null) return null;
+      return affix(groupedNumber(n2, { ...o, precision: o.precision ?? 2 }), o);
     },
     parse: (raw) => toNumber(raw)
   },
@@ -9776,8 +10066,8 @@ var DEFS = [
     numericAlign: true,
     optionKeys: ["currency", "precision"],
     format: (v, o) => {
-      const n = toNumber(v);
-      if (n === null) return null;
+      const n2 = toNumber(v);
+      if (n2 === null) return null;
       const currency = (o.currency || "USD").toUpperCase();
       try {
         return new Intl.NumberFormat(void 0, {
@@ -9787,9 +10077,9 @@ var DEFS = [
             minimumFractionDigits: o.precision,
             maximumFractionDigits: o.precision
           } : {}
-        }).format(n);
+        }).format(n2);
       } catch {
-        return `${groupedNumber(n, { precision: o.precision ?? 2 })} ${currency}`;
+        return `${groupedNumber(n2, { precision: o.precision ?? 2 })} ${currency}`;
       }
     },
     parse: (raw) => toNumber(raw)
@@ -9805,9 +10095,9 @@ var DEFS = [
     numericAlign: true,
     optionKeys: ["percentScale", "precision"],
     format: (v, o) => {
-      const n = toNumber(v);
-      if (n === null) return null;
-      const shown = o.percentScale === "fraction" ? n * 100 : n;
+      const n2 = toNumber(v);
+      if (n2 === null) return null;
+      const shown = o.percentScale === "fraction" ? n2 * 100 : n2;
       return `${groupedNumber(shown, o.precision === void 0 ? {} : { precision: o.precision })}%`;
     },
     parse: (raw) => toNumber(raw)
@@ -9823,9 +10113,9 @@ var DEFS = [
     numericAlign: true,
     optionKeys: ["durationUnit"],
     format: (v, o) => {
-      const n = toNumber(v);
-      if (n === null) return null;
-      return formatSignedDuration(n * DURATION_TO_SECONDS[o.durationUnit ?? "seconds"]);
+      const n2 = toNumber(v);
+      if (n2 === null) return null;
+      return formatSignedDuration(n2 * DURATION_TO_SECONDS[o.durationUnit ?? "seconds"]);
     },
     parse: (raw) => toNumber(raw)
   },
@@ -9840,13 +10130,13 @@ var DEFS = [
     numericAlign: true,
     optionKeys: ["useGrouping", "prefix", "suffix"],
     format: (v, o) => {
-      const n = toNumber(v);
-      if (n === null) return null;
-      return affix(groupedNumber(Math.trunc(n), { ...o, precision: 0 }), o);
+      const n2 = toNumber(v);
+      if (n2 === null) return null;
+      return affix(groupedNumber(Math.trunc(n2), { ...o, precision: 0 }), o);
     },
     parse: (raw) => {
-      const n = toNumber(raw);
-      return n === null ? null : Math.trunc(n);
+      const n2 = toNumber(raw);
+      return n2 === null ? null : Math.trunc(n2);
     }
   },
   {
@@ -9860,15 +10150,15 @@ var DEFS = [
     rich: true,
     optionKeys: ["ratingMax"],
     format: (v, o) => {
-      const n = toNumber(v);
-      if (n === null) return null;
+      const n2 = toNumber(v);
+      if (n2 === null) return null;
       const max = o.ratingMax ?? 5;
-      if (n < 0 || n > max) return null;
-      return `${n} / ${max}`;
+      if (n2 < 0 || n2 > max) return null;
+      return `${n2} / ${max}`;
     },
     parse: (raw) => {
-      const n = toNumber(raw);
-      return n === null ? null : Math.round(n);
+      const n2 = toNumber(raw);
+      return n2 === null ? null : Math.round(n2);
     }
   },
   {
@@ -9881,12 +10171,12 @@ var DEFS = [
     editor: "number",
     numericAlign: true,
     format: (v) => {
-      const n = toNumber(v);
-      return n === null ? null : (0, import_format3.formatFileSize)(n);
+      const n2 = toNumber(v);
+      return n2 === null ? null : (0, import_format3.formatFileSize)(n2);
     },
     parse: (raw) => {
-      const n = toNumber(raw);
-      return n === null ? null : Math.trunc(n);
+      const n2 = toNumber(raw);
+      return n2 === null ? null : Math.trunc(n2);
     }
   },
   // ── Choice ────────────────────────────────────────────────────────────────
@@ -10298,6 +10588,17 @@ function DirtySavePill({
 // src/data-table/EditableTableCell.tsx
 var import_react19 = require("react");
 var import_jsx_runtime39 = require("react/jsx-runtime");
+function CellRefusal({ reason }) {
+  return /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(
+    "p",
+    {
+      role: "alert",
+      "data-matrx-cell-refusal": "true",
+      className: "mt-1 text-[11px] leading-snug text-amber-700 dark:text-amber-400",
+      children: reason
+    }
+  );
+}
 function CellEditShell({
   href,
   display,
@@ -10344,12 +10645,17 @@ function EditableTableCell({
   className,
   href,
   editTrigger = "click",
-  editRequest
+  editRequest,
+  editSeed
 }) {
   const [open, setOpen] = (0, import_react19.useState)(false);
+  const [refusal, setRefusal] = (0, import_react19.useState)(null);
   (0, import_react19.useEffect)(() => {
     if (editRequest !== void 0) setOpen(true);
   }, [editRequest]);
+  (0, import_react19.useEffect)(() => {
+    if (!open) setRefusal(null);
+  }, [open]);
   const usePencil = Boolean(href) || editTrigger === "pencil";
   if (editType === "string") {
     return /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(
@@ -10362,7 +10668,8 @@ function EditableTableCell({
         ...className === void 0 ? {} : { className },
         ...href === void 0 ? {} : { href },
         usePencil,
-        ...editRequest === void 0 ? {} : { editRequest }
+        ...editRequest === void 0 ? {} : { editRequest },
+        ...editSeed === void 0 || editSeed === null ? {} : { editSeed }
       }
     );
   }
@@ -10407,25 +10714,33 @@ function EditableTableCell({
       ) }) }),
       /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(TooltipContent, { children: "Edit value" })
     ] }),
-    /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(
+    /* @__PURE__ */ (0, import_jsx_runtime39.jsxs)(
       PopoverContent,
       {
         align: "start",
         className: "w-56 p-2",
         onClick: (e) => e.stopPropagation(),
-        children: /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(
-          TypedEditor,
-          {
-            editType,
-            value,
-            editOptions,
-            onCommit: (next) => {
-              onCommit(next);
-              setOpen(false);
-            },
-            onCancel: () => setOpen(false)
-          }
-        )
+        children: [
+          /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(
+            TypedEditor,
+            {
+              editType,
+              value,
+              editOptions,
+              onCommit: (next) => {
+                const refused = onCommit(next);
+                if (typeof refused === "string" && refused) {
+                  setRefusal(refused);
+                  return;
+                }
+                setRefusal(null);
+                setOpen(false);
+              },
+              onCancel: () => setOpen(false)
+            }
+          ),
+          refusal ? /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(CellRefusal, { reason: refusal }) : null
+        ]
       }
     )
   ] });
@@ -10438,17 +10753,31 @@ function InlineStringEditor({
   className,
   href,
   usePencil,
-  editRequest
+  editRequest,
+  editSeed
 }) {
   const [editing, setEditing] = (0, import_react19.useState)(false);
   const [draft, setDraft] = (0, import_react19.useState)(value);
+  const [refusal, setRefusal] = (0, import_react19.useState)(null);
   const handledEditRequest = (0, import_react19.useRef)(void 0);
+  const seedRef = (0, import_react19.useRef)(editSeed);
+  seedRef.current = editSeed;
   (0, import_react19.useEffect)(() => {
     if (editRequest === void 0 || handledEditRequest.current === editRequest) return;
     handledEditRequest.current = editRequest;
-    setDraft(value);
+    setDraft(seedRef.current ?? value);
+    setRefusal(null);
     setEditing(true);
   }, [editRequest, value]);
+  const commit = (next) => {
+    const refused = onCommit(next);
+    if (typeof refused === "string" && refused) {
+      setRefusal(refused);
+      return false;
+    }
+    setRefusal(null);
+    return true;
+  };
   if (!editing) {
     if (usePencil) {
       return /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(
@@ -10499,32 +10828,38 @@ function InlineStringEditor({
       /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(TooltipContent, { children: "Click to edit" })
     ] });
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(
-    Input,
-    {
-      autoFocus: true,
-      value: draft,
-      onClick: (e) => e.stopPropagation(),
-      onChange: (e) => setDraft(e.target.value),
-      onBlur: () => {
-        onCommit(draft);
-        setEditing(false);
-      },
-      onKeyDown: (e) => {
-        if (e.key === "Enter") {
-          e.preventDefault();
-          onCommit(draft);
-          setEditing(false);
-        }
-        if (e.key === "Escape") {
-          e.preventDefault();
-          setEditing(false);
-        }
-      },
-      className: "h-7 text-sm",
-      style: { fontSize: "16px" }
-    }
-  );
+  return /* @__PURE__ */ (0, import_jsx_runtime39.jsxs)("span", { className: "block w-full", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(
+      Input,
+      {
+        autoFocus: true,
+        value: draft,
+        onClick: (e) => e.stopPropagation(),
+        onChange: (e) => {
+          setDraft(e.target.value);
+          if (refusal) setRefusal(null);
+        },
+        onBlur: () => {
+          if (commit(draft)) setEditing(false);
+        },
+        onKeyDown: (e) => {
+          if (e.key === "Enter") {
+            e.preventDefault();
+            if (commit(draft)) setEditing(false);
+          }
+          if (e.key === "Escape") {
+            e.preventDefault();
+            setRefusal(null);
+            setEditing(false);
+          }
+        },
+        "aria-invalid": refusal ? true : void 0,
+        className: cn("h-7 text-sm", refusal && "border-amber-500 focus-visible:ring-amber-500"),
+        style: { fontSize: "16px" }
+      }
+    ),
+    refusal ? /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(CellRefusal, { reason: refusal }) : null
+  ] });
 }
 function TypedEditor({
   editType,
@@ -10709,8 +11044,8 @@ function NumberEditor({
         style: { fontSize: "16px" },
         onKeyDown: (e) => {
           if (e.key === "Enter") {
-            const n = Number(draft);
-            if (Number.isFinite(n)) onCommit(n);
+            const n2 = Number(draft);
+            if (Number.isFinite(n2)) onCommit(n2);
           }
           if (e.key === "Escape") onCancel();
         }
@@ -10737,8 +11072,8 @@ function NumberEditor({
           className: "h-7",
           "aria-label": "Apply value",
           onClick: () => {
-            const n = Number(draft);
-            if (Number.isFinite(n)) onCommit(n);
+            const n2 = Number(draft);
+            if (Number.isFinite(n2)) onCommit(n2);
           },
           children: /* @__PURE__ */ (0, import_jsx_runtime39.jsx)(Check, { className: "h-3.5 w-3.5" })
         }
@@ -11546,6 +11881,7 @@ function MatrxDataTableCore({
   virtualize,
   coverage,
   spreadsheet,
+  facets,
   rowHeight: explicitRowHeight
 }) {
   const appendQuery = query?.mode === "controlled-append" ? query : null;
@@ -12603,9 +12939,92 @@ function MatrxDataTableCore({
       ...spreadsheet.undoDepth === void 0 ? {} : { undoDepth: spreadsheet.undoDepth },
       ...spreadsheet.fillHandle === void 0 ? {} : { fillHandle: spreadsheet.fillHandle },
       ...spreadsheet.paste === void 0 ? {} : { paste: spreadsheet.paste },
-      notify: spreadsheet.notify ?? ((message) => toast.success(message))
+      notify: spreadsheet.notify ?? ((message) => toast.success(message)),
+      onEditRequest: (address, seed) => requestCellEditRef.current(address, seed),
+      ...spreadsheet.validateCell ? { validateCell: spreadsheet.validateCell } : {}
     } : null
   );
+  const sheetRef = (0, import_react21.useRef)(sheet);
+  sheetRef.current = sheet;
+  const searchValueRef = (0, import_react21.useRef)(searchValue);
+  searchValueRef.current = searchValue;
+  const facetsEnabled = Boolean(facets && facets.enabled !== false);
+  const [facetState, setFacetState] = (0, import_react21.useState)({});
+  const facetReadCell = (0, import_react21.useCallback)(
+    (row, colId) => {
+      if (facets?.readCell) return facets.readCell(row, colId);
+      const col = visibleColumns.find((candidate) => columnId(candidate) === colId);
+      return col ? getFilterValue(row, col) : void 0;
+    },
+    [facets, visibleColumns]
+  );
+  const facetInputsRef = (0, import_react21.useRef)({ data, facets, facetReadCell });
+  facetInputsRef.current = { data, facets, facetReadCell };
+  const facetRequestRef = (0, import_react21.useRef)(/* @__PURE__ */ new Map());
+  const requestFacets = (0, import_react21.useCallback)((colId) => {
+    const { data: rows, facets: config, facetReadCell: readCell } = facetInputsRef.current;
+    if (!config || config.enabled === false) return;
+    const complete = localFacetsAreComplete(rows.length, config.totalRows);
+    const limit = config.limit;
+    if (complete || !config.source) {
+      setFacetState((current) => ({
+        ...current,
+        [colId]: {
+          loading: false,
+          data: computeColumnFacets({
+            columnId: colId,
+            rows,
+            readValue: readCell,
+            ...limit === void 0 ? {} : { limit },
+            complete
+          })
+        }
+      }));
+      return;
+    }
+    const ticket = (facetRequestRef.current.get(colId) ?? 0) + 1;
+    facetRequestRef.current.set(colId, ticket);
+    setFacetState((current) => ({
+      ...current,
+      [colId]: { loading: true, data: current[colId]?.data ?? null }
+    }));
+    void Promise.resolve().then(
+      () => config.source?.({ columnId: colId, search: searchValueRef.current, limit: limit ?? 200 })
+    ).then((answer) => {
+      if (facetRequestRef.current.get(colId) !== ticket) return;
+      if (!answer) {
+        setFacetState((current) => ({
+          ...current,
+          [colId]: {
+            loading: false,
+            data: computeColumnFacets({
+              columnId: colId,
+              rows: facetInputsRef.current.data,
+              readValue: facetInputsRef.current.facetReadCell,
+              ...limit === void 0 ? {} : { limit },
+              complete: false
+            })
+          }
+        }));
+        return;
+      }
+      setFacetState((current) => ({
+        ...current,
+        [colId]: { loading: false, data: { ...answer, answeredBy: "source", complete: true } }
+      }));
+    }).catch((error) => {
+      if (facetRequestRef.current.get(colId) !== ticket) return;
+      setFacetState((current) => ({
+        ...current,
+        [colId]: { loading: false, data: null, error: describeFacetFailure(error) }
+      }));
+    });
+  }, []);
+  (0, import_react21.useEffect)(() => {
+    if (!facetsEnabled) return;
+    setFacetState({});
+    facetRequestRef.current = /* @__PURE__ */ new Map();
+  }, [facetsEnabled, data, searchValue]);
   (0, import_react21.useEffect)(() => {
     if (!controlledQuery || controlledQuery.state.page === safePage) return;
     emitControlledQueryChange({ page: safePage });
@@ -12650,11 +13069,11 @@ function MatrxDataTableCore({
   });
   const hasActiveFilters = activeFilterCount > 0 || Boolean(searchValue.trim()) || intelligentSearchEnabled && searchScope !== "all" || Boolean(anyOfValue.trim()) || completeLayeredFilterRules(layeredFilters).length > 0 || facetActive;
   const changeCount = (0, import_react21.useMemo)(() => {
-    let n = 0;
+    let n2 = 0;
     for (const fields of Object.values(edits)) {
-      n += Object.keys(fields).length;
+      n2 += Object.keys(fields).length;
     }
-    return n;
+    return n2;
   }, [edits]);
   const showSearch = toolbar?.search !== false;
   const openDetail = (row) => {
@@ -12733,6 +13152,23 @@ function MatrxDataTableCore({
     icon: void 0
   } : emptyState;
   const commitCell = (rowId, field, next) => {
+    if (edit?.validate) {
+      const row = data.find((candidate) => getRowId(candidate) === rowId);
+      if (row) {
+        let refusal;
+        try {
+          refusal = edit.validate({
+            row: applyRowEdits(row, edits[rowId]),
+            rowId,
+            columnId: field,
+            value: next
+          });
+        } catch {
+          refusal = void 0;
+        }
+        if (refusal) return refusal;
+      }
+    }
     const scope = editScopeKey;
     const nextEdits = { [rowId]: { [field]: next } };
     const revision = setCellEdit(rowId, field, next);
@@ -12777,9 +13213,29 @@ function MatrxDataTableCore({
     setEditRequest((current) => ({
       rowId: getRowId(row),
       field,
-      nonce: (current?.nonce ?? 0) + 1
+      nonce: (current?.nonce ?? 0) + 1,
+      seed: null
     }));
   };
+  const requestCellEdit = (address, seed) => {
+    if (!editEnabled) return false;
+    const row = data.find((candidate) => getRowId(candidate) === address.rowId);
+    if (!row) return false;
+    const column = visibleColumns.find(
+      (candidate) => columnId(candidate) === address.fieldName
+    );
+    if (!column?.editable || !(column.editableIf?.(row) ?? true)) return false;
+    const field = column.accessorKey ? String(column.accessorKey) : columnId(column);
+    setEditRequest((current) => ({
+      rowId: address.rowId,
+      field,
+      nonce: (current?.nonce ?? 0) + 1,
+      seed
+    }));
+    return true;
+  };
+  const requestCellEditRef = (0, import_react21.useRef)(requestCellEdit);
+  requestCellEditRef.current = requestCellEdit;
   const buildRecordControls = (row) => {
     const rowId = getRowId(row);
     const pending = edits[rowId];
@@ -13020,17 +13476,78 @@ function MatrxDataTableCore({
     setEdits({});
     edit?.onCancel?.();
   };
-  (0, import_react21.useEffect)(() => {
-    if (!host.rowContextRegistry || !contextMenu && !host.createDefaultRowContext) return;
-    return host.rowContextRegistry.register(tableContextMenuInstanceId, (rowId) => {
+  const resolveMenuLevel = (target) => {
+    const rowFor = (rowId) => {
       const row = data.find((candidate) => getRowId(candidate) === rowId);
       if (!row) return null;
-      const pending = edits[rowId];
-      const displayRow = applyRowEdits(row, pending);
-      const controls = buildRecordControls(displayRow);
-      return contextMenu?.resolveRowContext(displayRow, controls) ?? host.createDefaultRowContext?.(displayRow, controls) ?? null;
-    });
-  }, [buildRecordControls, contextMenu, data, getRowId, host.createDefaultRowContext, host.rowContextRegistry, tableContextMenuInstanceId]);
+      return applyRowEdits(row, edits[rowId]);
+    };
+    const columnFor = (id) => visibleColumns.find((col) => columnId(col) === id);
+    const labelFor = (col, id) => col?.label ?? (typeof col?.header === "string" ? col.header : id);
+    const fromHost = (payload) => host.createDefaultMenuContext?.(payload) ?? null;
+    switch (target.level) {
+      case "row": {
+        if (!target.rowId) return null;
+        const displayRow = rowFor(target.rowId);
+        if (!displayRow) return null;
+        const controls = buildRecordControls(displayRow);
+        return contextMenu?.resolveRowContext?.(displayRow, controls) ?? fromHost({ level: "row", row: displayRow, rowId: target.rowId, controls });
+      }
+      case "cell": {
+        if (!target.rowId || !target.columnId) return null;
+        const displayRow = rowFor(target.rowId);
+        const col = columnFor(target.columnId);
+        if (!displayRow || !col) return null;
+        const controls = buildRecordControls(displayRow);
+        const value = spreadsheet?.readCell ? spreadsheet.readCell(displayRow, target.columnId) : getCellValue(displayRow, col);
+        const args = {
+          row: displayRow,
+          rowId: target.rowId,
+          columnId: target.columnId,
+          columnLabel: labelFor(col, target.columnId),
+          value,
+          text: stringifyCellValue(value),
+          controls
+        };
+        return contextMenu?.resolveCellContext?.(args) ?? fromHost({ level: "cell", ...args });
+      }
+      case "column": {
+        if (!target.columnId) return null;
+        const col = columnFor(target.columnId);
+        if (!col) return null;
+        const args = {
+          columnId: target.columnId,
+          columnLabel: labelFor(col, target.columnId),
+          values: paginated.map(
+            (row) => getCellValue(applyRowEdits(row, edits[getRowId(row)]), col)
+          )
+        };
+        return contextMenu?.resolveColumnContext?.(args) ?? fromHost({ level: "column", ...args });
+      }
+      case "selection": {
+        const addresses = sheetRef.current.selectionAddresses();
+        const cellCount = addresses.rowIds.length * addresses.columnIds.length;
+        if (cellCount <= 1) {
+          return resolveMenuLevel({ ...target, level: "cell" });
+        }
+        const args = { ...addresses, tsv: sheetRef.current.selectionTsv(), cellCount };
+        return contextMenu?.resolveSelectionContext?.(args) ?? fromHost({ level: "selection", ...args });
+      }
+      case "table": {
+        const args = { rowCount: data.length, columnIds: visibleColumns.map((col) => columnId(col)) };
+        return contextMenu?.resolveTableContext?.(args) ?? fromHost({ level: "table", ...args });
+      }
+    }
+  };
+  const resolveMenuLevelRef = (0, import_react21.useRef)(resolveMenuLevel);
+  resolveMenuLevelRef.current = resolveMenuLevel;
+  (0, import_react21.useEffect)(() => {
+    if (!host.rowContextRegistry) return;
+    return host.rowContextRegistry.register(
+      tableContextMenuInstanceId,
+      (target) => resolveMenuLevelRef.current(target)
+    );
+  }, [host.rowContextRegistry, tableContextMenuInstanceId]);
   const showActionsCol = windowEnabled || Boolean(rowActions) || showInlineRowCopy;
   const selectedIdSet = (0, import_react21.useMemo)(
     () => new Set(selection?.selectedIds ?? []),
@@ -13112,8 +13629,19 @@ function MatrxDataTableCore({
           dirty: Boolean(rowEdits && field in rowEdits),
           onCommit: (next) => commitCell(id, field, next),
           ...href === void 0 ? {} : { href },
-          ...col.editTrigger === void 0 ? {} : { editTrigger: col.editTrigger },
-          ...editRequest?.rowId === id && editRequest.field === field ? { editRequest: editRequest.nonce } : {}
+          ...spreadsheetEnabled ? {
+            // 🚨 THE CLICK LAW, enforced where the two paths meet. In a grid
+            // with spreadsheet gestures a single click SELECTS a cell — it
+            // may never drop a person into a free-text buffer, because the
+            // same click is how they start a range, and an editor that opens
+            // under the pointer eats the drag and the next keystroke. So the
+            // editor opens the way it does in Excel: Enter, F2, the hover
+            // pencil, or simply typing. An explicit `editTrigger: "click"`
+            // does not override this; the law is the table's, not the
+            // column's.
+            editTrigger: "pencil"
+          } : col.editTrigger === void 0 ? {} : { editTrigger: col.editTrigger },
+          ...editRequest?.rowId === id && editRequest.field === field ? { editRequest: editRequest.nonce, editSeed: editRequest.seed } : {}
         }
       );
     }
@@ -13871,6 +14399,7 @@ function MatrxDataTableCore({
                                         "th",
                                         {
                                           "data-matrx-table-column-id": id,
+                                          "data-matrx-header-column-id": id,
                                           "data-matrx-column-drag-shadow": isColumnDragShadow ? "true" : void 0,
                                           "aria-sort": isSorted ? sort?.direction === "asc" ? "ascending" : "descending" : void 0,
                                           className: cn(
@@ -13907,6 +14436,12 @@ function MatrxDataTableCore({
                                               {
                                                 label: col.header,
                                                 labelText: headerLabel,
+                                                ...facetsEnabled ? {
+                                                  facets: facetState[id]?.data ?? null,
+                                                  facetsLoading: facetState[id]?.loading ?? false,
+                                                  ...facetState[id]?.error === void 0 ? {} : { facetsError: facetState[id]?.error },
+                                                  onFilterOpen: () => requestFacets(id)
+                                                } : {},
                                                 sortable: col.sortable !== false,
                                                 isSorted: Boolean(isSorted),
                                                 sortDirection: sort?.direction ?? defaultSortDirection,
@@ -14581,8 +15116,8 @@ function MatrxDataTableCore({
                     itemsPerPage: pageSize === 0 && allRowsAreLoaded ? 0 : effectivePageSize,
                     currentPage: safePage,
                     onPageChange: setPage,
-                    onItemsPerPageChange: (n) => {
-                      setPageSize(n);
+                    onItemsPerPageChange: (n2) => {
+                      setPageSize(n2);
                       if (!controlledQuery) setPage(1);
                     },
                     pageSizeOptions: pageSizeOptions.filter((size) => size > 0),