@ai-matrx/design-system 0.25.0 → 0.26.0

package/dist/data-table/index.js

@@ -10,7 +10,7 @@ import {
   useId as useId2,
   useLayoutEffect as useLayoutEffect2,
   useMemo as useMemo8,
-  useRef as useRef14,
+  useRef as useRef15,
   useState as useState22
 } from "react";
 import {
@@ -5139,10 +5139,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;
       }
     }
@@ -5205,26 +5205,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;
@@ -5506,8 +5506,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)) {
@@ -5708,6 +5708,7 @@ import {
   forwardRef as forwardRef12,
   useEffect as useEffect9,
   useMemo as useMemo5,
+  useRef as useRef10,
   useState as useState14
 } from "react";
 import { useDraggable } from "@dnd-kit/core";
@@ -5855,6 +5856,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",
@@ -5922,6 +6012,10 @@ function ColumnHeaderCell({
   filterFooterHint,
   allowNegation = false,
   allowNullModes = false,
+  facets,
+  facetsLoading = false,
+  facetsError,
+  onFilterOpen,
   reorderColumn
 }) {
   const reorderEnabled = reorderColumn !== void 0;
@@ -5956,6 +6050,11 @@ function ColumnHeaderCell({
       setPendingNegation(filterValue?.negated ?? false);
     }
   }, [filterOpen, filterValue]);
+  const notifyOpen = useRef10(onFilterOpen);
+  notifyOpen.current = onFilterOpen;
+  useEffect9(() => {
+    if (filterOpen) notifyOpen.current?.();
+  }, [filterOpen]);
   const applyFilter = () => {
     onFilterChange(draftFilter);
     setFilterOpen(false);
@@ -6050,6 +6149,9 @@ function ColumnHeaderCell({
             selectOptions,
             selectSingle,
             selectAllowCustom,
+            facets: facets ?? null,
+            facetsLoading,
+            ...facetsError === void 0 ? {} : { facetsError },
             ...markerLabels ? {
               booleanLabels: {
                 all: "All",
@@ -6274,8 +6376,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__ */ jsx31(
+    FacetChecklist,
+    {
+      facets,
+      loading: facetsLoading,
+      ...facetsError === void 0 ? {} : { error: facetsError },
+      value,
+      onChange
+    }
+  ) : null;
+  if (checklist && kind === "select" && facets && facets.values.length > 0) {
+    return /* @__PURE__ */ jsx31("div", { className: "space-y-2", children: checklist });
+  }
+  if (checklist) {
+    return /* @__PURE__ */ jsxs22("div", { className: "space-y-2", children: [
+      checklist,
+      /* @__PURE__ */ jsx31("div", { className: "h-px bg-border" }),
+      /* @__PURE__ */ jsx31(
+        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";
@@ -6386,6 +6523,112 @@ function FilterBody({
   }
   return /* @__PURE__ */ jsx31(NumberFilterBody, { value, onChange });
 }
+function FacetChecklist({
+  facets,
+  loading,
+  error,
+  value,
+  onChange
+}) {
+  const [query, setQuery] = useState14("");
+  const selected = value?.kind === "select" ? value.values ?? (value.value && value.value !== "__all__" ? [value.value] : []) : [];
+  const selectedSet = new Set(selected);
+  const rows = useMemo5(() => {
+    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__ */ jsxs22("div", { className: "space-y-1.5", children: [
+    /* @__PURE__ */ jsx31("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__ */ jsx31(
+      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__ */ jsx31("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__ */ jsx31("li", { children: /* @__PURE__ */ jsxs22(
+        "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__ */ jsx31(
+              "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__ */ jsx31(Check, { className: "h-2.5 w-2.5" }) : null
+              }
+            ),
+            /* @__PURE__ */ jsx31("span", { className: cn("min-w-0 flex-1 truncate", row.value === "" && "italic text-muted-foreground"), children: row.label }),
+            /* @__PURE__ */ jsx31(
+              "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__ */ jsx31("p", { className: "px-1 text-[11px] text-muted-foreground", children: query.trim() ? "No value matches that." : "This column has no values yet." }),
+    notice ? /* @__PURE__ */ jsx31(
+      "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__ */ jsx31(
+      "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,
@@ -6572,15 +6815,15 @@ 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
 import {
   useCallback as useCallback6,
   useEffect as useEffect10,
-  useRef as useRef10,
+  useRef as useRef11,
   useState as useState15
 } from "react";
 
@@ -6624,11 +6867,11 @@ function ColumnResizeHandle({
   onResizeCancel,
   onResizeCommit
 }) {
-  const handleRef = useRef10(null);
-  const activeResizeRef = useRef10(null);
-  const previewRafRef = useRef10(null);
-  const queuedWidthRef = useRef10(null);
-  const keyboardWidthRef = useRef10(null);
+  const handleRef = useRef11(null);
+  const activeResizeRef = useRef11(null);
+  const previewRafRef = useRef11(null);
+  const queuedWidthRef = useRef11(null);
+  const keyboardWidthRef = useRef11(null);
   const [announcedWidth, setAnnouncedWidth] = useState15(null);
   const bounds = resolveColumnResizeBounds(minWidth, maxWidth);
   const cssVar = columnResizeCssVar(columnId2);
@@ -6890,16 +7133,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;
@@ -7217,7 +7460,7 @@ function scrollOffsetForIndex(input) {
 }
 
 // src/data-table/useSpreadsheetGrid.ts
-import { useCallback as useCallback7, useEffect as useEffect11, useMemo as useMemo6, useRef as useRef11, useState as useState16 } from "react";
+import { useCallback as useCallback7, useEffect as useEffect11, useMemo as useMemo6, useRef as useRef12, useState as useState16 } from "react";
 
 // src/data-table/grid-selection.ts
 function rangeBounds(range, rowIds, fieldNames) {
@@ -7323,7 +7566,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);
@@ -7455,14 +7698,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] === '"') {
@@ -7477,10 +7720,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);
@@ -7516,7 +7759,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);
@@ -7595,11 +7838,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);
@@ -7915,8 +8158,8 @@ function useSpreadsheetGrid(options) {
   const [range, setRange] = useState16(null);
   const [fillTarget, setFillTarget] = useState16(null);
   const [stack, setStack] = useState16(() => createUndoStack(options?.undoDepth ?? 100));
-  const draggingRef = useRef11(null);
-  const optionsRef = useRef11(options);
+  const draggingRef = useRef12(null);
+  const optionsRef = useRef12(options);
   optionsRef.current = options;
   const rowIds = options?.rowIds ?? [];
   const columnIds = useMemo6(
@@ -7944,6 +8187,26 @@ function useSpreadsheetGrid(options) {
     for (let i = 0; i < columnIds.length; i += 1) map.set(columnIds[i], i);
     return map;
   }, [columnIds]);
+  const screenPatches = useCallback7(
+    (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 = useCallback7(
     async (patches, intent, label) => {
       const current = optionsRef.current;
@@ -8000,9 +8263,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 = useCallback7(async () => {
     const current = optionsRef.current;
     if (!current || !bounds) return;
@@ -8023,9 +8287,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 = useCallback7(async () => {
     const taken = popUndo(stack);
     if (!taken.entry) return;
@@ -8110,6 +8378,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;
       }
@@ -8124,6 +8400,13 @@ function useSpreadsheetGrid(options) {
     );
     return gridToTsv(grid);
   }, [range, rowIds, columnIds]);
+  const selectionAddresses = useCallback7(() => {
+    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 = useCallback7(
     (event) => {
       if (!optionsRef.current || !range || targetsAnEditor(event.target)) return;
@@ -8179,11 +8462,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 = useCallback7(
     (rowId, columnId2) => {
@@ -8202,6 +8486,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 }
           );
@@ -8242,9 +8530,9 @@ function useSpreadsheetGrid(options) {
     },
     []
   );
-  const fillTargetRef = useRef11(null);
+  const fillTargetRef = useRef12(null);
   fillTargetRef.current = fillTarget;
-  const boundsRef = useRef11(null);
+  const boundsRef = useRef12(null);
   boundsRef.current = bounds;
   useEffect11(() => {
     if (!options) return;
@@ -8263,12 +8551,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,
@@ -8284,17 +8573,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);
   }
@@ -8987,7 +9278,7 @@ function parseTableViewSnapshot(raw) {
 // src/data-table/MatrxUuidCell.tsx
 import {
   useEffect as useEffect13,
-  useRef as useRef12,
+  useRef as useRef13,
   useState as useState18
 } from "react";
 import { jsx as jsx34, jsxs as jsxs24 } from "react/jsx-runtime";
@@ -9032,7 +9323,7 @@ function MatrxUuidCell({
   const [copied, setCopied] = useState18(false);
   const [opening, setOpening] = useState18(false);
   const [peekOpen, setPeekOpen] = useState18(false);
-  const timer = useRef12(null);
+  const timer = useRef13(null);
   useEffect13(
     () => () => {
       if (timer.current) clearTimeout(timer.current);
@@ -9500,8 +9791,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;
 }
@@ -9539,14 +9830,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 ?? ""}`;
@@ -9680,8 +9971,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)
   },
@@ -9696,9 +9987,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)
   },
@@ -9713,8 +10004,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, {
@@ -9724,9 +10015,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)
@@ -9742,9 +10033,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)
@@ -9760,9 +10051,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)
   },
@@ -9777,13 +10068,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);
     }
   },
   {
@@ -9797,15 +10088,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);
     }
   },
   {
@@ -9818,12 +10109,12 @@ var DEFS = [
     editor: "number",
     numericAlign: true,
     format: (v) => {
-      const n = toNumber(v);
-      return n === null ? null : formatFileSize(n);
+      const n2 = toNumber(v);
+      return n2 === null ? null : 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 ────────────────────────────────────────────────────────────────
@@ -10233,8 +10524,19 @@ function DirtySavePill({
 }
 
 // src/data-table/EditableTableCell.tsx
-import { useEffect as useEffect15, useRef as useRef13, useState as useState20 } from "react";
+import { useEffect as useEffect15, useRef as useRef14, useState as useState20 } from "react";
 import { jsx as jsx39, jsxs as jsxs29 } from "react/jsx-runtime";
+function CellRefusal({ reason }) {
+  return /* @__PURE__ */ jsx39(
+    "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,
@@ -10281,12 +10583,17 @@ function EditableTableCell({
   className,
   href,
   editTrigger = "click",
-  editRequest
+  editRequest,
+  editSeed
 }) {
   const [open, setOpen] = useState20(false);
+  const [refusal, setRefusal] = useState20(null);
   useEffect15(() => {
     if (editRequest !== void 0) setOpen(true);
   }, [editRequest]);
+  useEffect15(() => {
+    if (!open) setRefusal(null);
+  }, [open]);
   const usePencil = Boolean(href) || editTrigger === "pencil";
   if (editType === "string") {
     return /* @__PURE__ */ jsx39(
@@ -10299,7 +10606,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 }
       }
     );
   }
@@ -10344,25 +10652,33 @@ function EditableTableCell({
       ) }) }),
       /* @__PURE__ */ jsx39(TooltipContent, { children: "Edit value" })
     ] }),
-    /* @__PURE__ */ jsx39(
+    /* @__PURE__ */ jsxs29(
       PopoverContent,
       {
         align: "start",
         className: "w-56 p-2",
         onClick: (e) => e.stopPropagation(),
-        children: /* @__PURE__ */ jsx39(
-          TypedEditor,
-          {
-            editType,
-            value,
-            editOptions,
-            onCommit: (next) => {
-              onCommit(next);
-              setOpen(false);
-            },
-            onCancel: () => setOpen(false)
-          }
-        )
+        children: [
+          /* @__PURE__ */ jsx39(
+            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__ */ jsx39(CellRefusal, { reason: refusal }) : null
+        ]
       }
     )
   ] });
@@ -10375,17 +10691,31 @@ function InlineStringEditor({
   className,
   href,
   usePencil,
-  editRequest
+  editRequest,
+  editSeed
 }) {
   const [editing, setEditing] = useState20(false);
   const [draft, setDraft] = useState20(value);
-  const handledEditRequest = useRef13(void 0);
+  const [refusal, setRefusal] = useState20(null);
+  const handledEditRequest = useRef14(void 0);
+  const seedRef = useRef14(editSeed);
+  seedRef.current = editSeed;
   useEffect15(() => {
     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__ */ jsx39(
@@ -10436,32 +10766,38 @@ function InlineStringEditor({
       /* @__PURE__ */ jsx39(TooltipContent, { children: "Click to edit" })
     ] });
   }
-  return /* @__PURE__ */ jsx39(
-    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__ */ jsxs29("span", { className: "block w-full", children: [
+    /* @__PURE__ */ jsx39(
+      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__ */ jsx39(CellRefusal, { reason: refusal }) : null
+  ] });
 }
 function TypedEditor({
   editType,
@@ -10646,8 +10982,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();
         }
@@ -10674,8 +11010,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__ */ jsx39(Check, { className: "h-3.5 w-3.5" })
         }
@@ -11483,11 +11819,12 @@ function MatrxDataTableCore({
   virtualize,
   coverage,
   spreadsheet,
+  facets,
   rowHeight: explicitRowHeight
 }) {
   const appendQuery = query?.mode === "controlled-append" ? query : null;
   const appendQueryKey = appendQuery?.pagination.queryKey ?? null;
-  const committedAppendQueryKey = useRef14(appendQueryKey);
+  const committedAppendQueryKey = useRef15(appendQueryKey);
   const appendSourceChanged = appendQuery !== null && committedAppendQueryKey.current !== appendQueryKey;
   const data = (appendQuery ? appendQuery.pagination.rows : suppliedData) ?? [];
   const isLoading = appendQuery ? appendQuery.pagination.loading : suppliedLoading;
@@ -11502,7 +11839,7 @@ function MatrxDataTableCore({
   const [savedViewError, setSavedViewError] = useState22(null);
   const [toolbarActionError, setToolbarActionError] = useState22(null);
   const [toolbarActionPending, setToolbarActionPending] = useState22({ refresh: false, add: false });
-  const toolbarActionPendingRef = useRef14({ refresh: false, add: false });
+  const toolbarActionPendingRef = useRef15({ refresh: false, add: false });
   const CHECKBOX_TAP_AREA = "h-4 w-4 touch-manipulation";
   const mobileCardsClass = mobileCardsBreakpoint === "lg" ? "lg:hidden" : "sm:hidden";
   const tableWithCardsClass = mobileCardsBreakpoint === "lg" ? "max-lg:hidden" : "max-sm:hidden";
@@ -11640,9 +11977,9 @@ function MatrxDataTableCore({
   const [windowRowSnapshot, setWindowRowSnapshot] = useState22(null);
   const editScopeKey = appendQueryKey === null ? "\0local" : `append:${appendQueryKey}`;
   const [editsByScope, setEditsByScope] = useState22({});
-  const editRevisionRef = useRef14({});
+  const editRevisionRef = useRef15({});
   const [savingByScope, setSavingByScope] = useState22({});
-  const savingScopesRef = useRef14(/* @__PURE__ */ new Set());
+  const savingScopesRef = useRef15(/* @__PURE__ */ new Set());
   const [editRequest, setEditRequest] = useState22(null);
   const [confirmForeignDraftDiscard, setConfirmForeignDraftDiscard] = useState22(false);
   const edits = editsByScope[editScopeKey]?.values ?? {};
@@ -11729,13 +12066,13 @@ function MatrxDataTableCore({
     onWindowRowIdChange,
     selectionConfig
   ]);
-  const scrollRef = useRef14(null);
-  const tableRef = useRef14(null);
-  const tableHeaderRef = useRef14(null);
-  const cardsScrollRef = useRef14(null);
+  const scrollRef = useRef15(null);
+  const tableRef = useRef15(null);
+  const tableHeaderRef = useRef15(null);
+  const cardsScrollRef = useRef15(null);
   const [documentStickyHeader, setDocumentStickyHeader] = useState22(false);
-  const documentStickyHeaderRef = useRef14(false);
-  const previousAppendKeyForScrollReset = useRef14(appendQueryKey);
+  const documentStickyHeaderRef = useRef15(false);
+  const previousAppendKeyForScrollReset = useRef15(appendQueryKey);
   useLayoutEffect2(() => {
     const previous = previousAppendKeyForScrollReset.current;
     previousAppendKeyForScrollReset.current = appendQueryKey;
@@ -11761,7 +12098,7 @@ function MatrxDataTableCore({
     ...appendScrollPolicy?.mode === "scroll" && appendScrollPolicy.thresholdPx !== void 0 ? { thresholdPx: appendScrollPolicy.thresholdPx } : {},
     ...appendScrollPolicy?.mode === "scroll" && appendScrollPolicy.intentTimeoutMs !== void 0 ? { intentTimeoutMs: appendScrollPolicy.intentTimeoutMs } : {}
   });
-  const rootRef = useRef14(null);
+  const rootRef = useRef15(null);
   useClippedContentGuard(rootRef, {
     label: typeof copy === "object" && copy.listLabel ? `Table: ${copy.listLabel}` : "MatrxDataTable"
   });
@@ -11863,11 +12200,11 @@ function MatrxDataTableCore({
     () => normalizeColumnWidthsForColumns(columnState?.widths, columns)
   );
   const [fixedTableGeometry, setFixedTableGeometry] = useState22(null);
-  const knownColumnIds = useRef14(new Set(columns.map(columnId)));
-  const draggedColumnId = useRef14(null);
-  const columnDragActive = useRef14(false);
-  const columnDragRaf = useRef14(null);
-  const columnDragScrollDirection = useRef14(0);
+  const knownColumnIds = useRef15(new Set(columns.map(columnId)));
+  const draggedColumnId = useRef15(null);
+  const columnDragActive = useRef15(false);
+  const columnDragRaf = useRef15(null);
+  const columnDragScrollDirection = useRef15(0);
   const [columnDragPreview, setColumnDragPreview] = useState22(null);
   const stopColumnDragScroll = useCallback8(() => {
     if (columnDragRaf.current !== null) cancelAnimationFrame(columnDragRaf.current);
@@ -11922,7 +12259,7 @@ function MatrxDataTableCore({
     () => normalizeColumnWidthsForColumns(columnState?.widths ?? columnWidths, columns),
     [columns, columnState?.widths, columnWidths]
   );
-  const resizeGestureSnapshotRef = useRef14(null);
+  const resizeGestureSnapshotRef = useRef15(null);
   const measureVisibleColumnWidths = useCallback8(() => {
     const measured = {};
     const headers = tableRef.current ? Array.from(tableRef.current.querySelectorAll(
@@ -12228,7 +12565,7 @@ function MatrxDataTableCore({
     intelligentSearchEnabled,
     searchScope
   ]);
-  const lastNotifiedViewRows = useRef14(null);
+  const lastNotifiedViewRows = useRef15(null);
   useEffect16(() => {
     if (!onViewChange) {
       lastNotifiedViewRows.current = null;
@@ -12348,7 +12685,7 @@ function MatrxDataTableCore({
   const columnVirtualizeActive = virtualizeConfig !== null && virtualizeConfig.enabled !== false && virtualizeConfig.columns === true && visibleColumns.length - frozenRunLength > 30 && !hierarchy && mobileCards === void 0;
   const [rowWindow, setRowWindow] = useState22(null);
   const [columnWindow, setColumnWindow] = useState22(null);
-  const windowInputs = useRef14({
+  const windowInputs = useRef15({
     virtualizeActive: false,
     bodyEntryCount: 0,
     virtualRowHeight: 40,
@@ -12498,7 +12835,7 @@ function MatrxDataTableCore({
       windowed.push({ kind: "spacer", height: effectiveRowWindow.padEnd, place: "end" });
     return windowed;
   }, [groupedRenderRows, collapsedGroups, paginated, effectiveRowWindow]);
-  const getRowIdRef = useRef14(getRowId);
+  const getRowIdRef = useRef15(getRowId);
   getRowIdRef.current = getRowId;
   const spreadsheetRowIds = useMemo8(
     () => paginated.map((row) => getRowIdRef.current(row)),
@@ -12540,9 +12877,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 = useRef15(sheet);
+  sheetRef.current = sheet;
+  const searchValueRef = useRef15(searchValue);
+  searchValueRef.current = searchValue;
+  const facetsEnabled = Boolean(facets && facets.enabled !== false);
+  const [facetState, setFacetState] = useState22({});
+  const facetReadCell = useCallback8(
+    (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 = useRef15({ data, facets, facetReadCell });
+  facetInputsRef.current = { data, facets, facetReadCell };
+  const facetRequestRef = useRef15(/* @__PURE__ */ new Map());
+  const requestFacets = useCallback8((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) }
+      }));
+    });
+  }, []);
+  useEffect16(() => {
+    if (!facetsEnabled) return;
+    setFacetState({});
+    facetRequestRef.current = /* @__PURE__ */ new Map();
+  }, [facetsEnabled, data, searchValue]);
   useEffect16(() => {
     if (!controlledQuery || controlledQuery.state.page === safePage) return;
     emitControlledQueryChange({ page: safePage });
@@ -12587,11 +13007,11 @@ function MatrxDataTableCore({
   });
   const hasActiveFilters = activeFilterCount > 0 || Boolean(searchValue.trim()) || intelligentSearchEnabled && searchScope !== "all" || Boolean(anyOfValue.trim()) || completeLayeredFilterRules(layeredFilters).length > 0 || facetActive;
   const changeCount = useMemo8(() => {
-    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) => {
@@ -12670,6 +13090,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);
@@ -12714,9 +13151,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 = useRef15(requestCellEdit);
+  requestCellEditRef.current = requestCellEdit;
   const buildRecordControls = (row) => {
     const rowId = getRowId(row);
     const pending = edits[rowId];
@@ -12957,17 +13414,78 @@ function MatrxDataTableCore({
     setEdits({});
     edit?.onCancel?.();
   };
-  useEffect16(() => {
-    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 = useRef15(resolveMenuLevel);
+  resolveMenuLevelRef.current = resolveMenuLevel;
+  useEffect16(() => {
+    if (!host.rowContextRegistry) return;
+    return host.rowContextRegistry.register(
+      tableContextMenuInstanceId,
+      (target) => resolveMenuLevelRef.current(target)
+    );
+  }, [host.rowContextRegistry, tableContextMenuInstanceId]);
   const showActionsCol = windowEnabled || Boolean(rowActions) || showInlineRowCopy;
   const selectedIdSet = useMemo8(
     () => new Set(selection?.selectedIds ?? []),
@@ -12985,7 +13503,7 @@ function MatrxDataTableCore({
     () => data.filter((row) => selectedIdSet.has(getRowId(row))),
     [data, selectedIdSet, getRowId]
   );
-  const lastToggledIndex = useRef14(null);
+  const lastToggledIndex = useRef15(null);
   const setSelectedIds = (next) => selection?.onSelectedIdsChange([...next]);
   const toggleRowSelected = (index, shiftKey) => {
     if (!selection) return;
@@ -13049,8 +13567,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 } : {}
         }
       );
     }
@@ -13808,6 +14337,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(
@@ -13844,6 +14374,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,
@@ -14518,8 +15054,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),