@ai-matrx/records-ui 0.9.0 → 0.10.3

package/dist/index.js

@@ -710,7 +710,7 @@ function PersonPicker({ field, value: value2, onChange, disabled, id, className
 }
 
 // src/gridEditing.tsx
-import { useCallback as useCallback3, useMemo as useMemo5, useRef as useRef2, useState as useState5 } from "react";
+import { useCallback as useCallback3, useEffect as useEffect5, useMemo as useMemo5, useRef as useRef2, useState as useState5 } from "react";
 import { asWriteConflict } from "@ai-matrx/records/core";
 import { useRecordsClient as useRecordsClient5 } from "@ai-matrx/records/react";
 import { Button as Button4, cn as cn6 } from "@ai-matrx/design-system";
@@ -732,27 +732,49 @@ var TITLE = {
   store_not_served: "The store is not being served",
   internal: "The store said something this package does not recognise"
 };
+var MACHINE_IDENTITY = [
+  /\b[A-Z]{2,4}-\d{1,3}\b/,
+  // FLD-11, REC-29, AGT-7
+  /\b(?:custom|platform|iam|history|public)\.[a-z_]+/,
+  // a database object
+  /\b(?:config|data|document|spec)\.[a-z_]+/,
+  // a path inside a document
+  /\b[a-z]+(?:_[a-z]+)+\b/,
+  // any snake_case identifier
+  // A SQLSTATE: five characters of digits and capitals, at least one a digit —
+  // so `23514` and `PT409` match and an emphatic `NEVER` does not.
+  /\b(?=[0-9A-Z]{5}\b)(?=[0-9A-Z]*\d)[0-9A-Z]{5}\b/
+];
+function hintIsMachineIdentity(hint) {
+  return MACHINE_IDENTITY.some((shape) => shape.test(hint));
+}
+function hintForAPerson(hint) {
+  const said = (hint ?? "").trim();
+  if (said === "") return null;
+  return hintIsMachineIdentity(said) ? null : said;
+}
 function RefusalNotice({
   error,
   className,
   actions
 }) {
+  const hint = hintForAPerson(error.hint);
+  const forEngineers = [
+    error.sqlstate ? `The store's code for this was ${error.sqlstate}.` : null,
+    hint === null && error.hint ? error.hint : null
+  ].filter(Boolean).join(" ");
   return /* @__PURE__ */ jsxs4(
     Alert,
     {
       variant: "destructive",
       className: cn4("text-xs", className),
-      ...error.sqlstate ? { title: `The store's code for this was ${error.sqlstate}` } : {},
+      ...forEngineers ? { title: forEngineers } : {},
       children: [
         /* @__PURE__ */ jsx5(AlertTitle, { className: "text-xs font-medium", children: TITLE[error.code] ?? "The store refused this" }),
         /* @__PURE__ */ jsxs4(AlertDescription, { className: "space-y-1 text-xs", children: [
           /* @__PURE__ */ jsx5("p", { children: error.message }),
-          error.hint ? /* @__PURE__ */ jsx5("p", { className: "opacity-80", children: error.hint }) : null,
-          error.sqlstate ? /* @__PURE__ */ jsxs4("p", { className: "sr-only", "data-sqlstate": error.sqlstate, children: [
-            "The store's code for this was ",
-            error.sqlstate,
-            "."
-          ] }) : null,
+          hint ? /* @__PURE__ */ jsx5("p", { className: "opacity-80", children: hint }) : null,
+          forEngineers ? /* @__PURE__ */ jsx5("p", { className: "sr-only", ...error.sqlstate ? { "data-sqlstate": error.sqlstate } : {}, children: forEngineers }) : null,
           actions
         ] })
       ]
@@ -760,7 +782,14 @@ function RefusalNotice({
   );
 }
 function RefusalLine({ error, className }) {
-  return /* @__PURE__ */ jsx5("p", { className: cn4("text-xs text-destructive", className), title: error.hint ?? void 0, children: error.message });
+  const hint = hintForAPerson(error.hint);
+  return /* @__PURE__ */ jsxs4("p", { className: cn4("text-xs text-destructive", className), title: error.hint ?? void 0, children: [
+    error.message,
+    hint ? /* @__PURE__ */ jsxs4("span", { className: "opacity-80", children: [
+      " ",
+      hint
+    ] }) : null
+  ] });
 }
 
 // src/values.tsx
@@ -940,6 +969,8 @@ async function versionOf(client, cache, recordId) {
 function useGridEditing({ tableId, fields, rows, reload, canWrite }) {
   const client = useRecordsClient5();
   const [editing, setEditing] = useState5(null);
+  const [draft, setDraft] = useState5(null);
+  const startedFrom = useRef2(null);
   const [optimistic, setOptimistic] = useState5({});
   const [saving, setSaving] = useState5({});
   const [refusals, setRefusals] = useState5({});
@@ -971,15 +1002,31 @@ function useGridEditing({ tableId, fields, rows, reload, canWrite }) {
     (rowId, key) => refusals[cellKey(rowId, key)] ?? null,
     [refusals]
   );
+  const shownValue = useCallback3(
+    (rowId, key) => {
+      const held = optimistic[cellKey(rowId, key)];
+      if (held !== void 0) return held;
+      return rows.find((r) => r.id === rowId)?.document?.[key];
+    },
+    [optimistic, rows]
+  );
   const begin = useCallback3(
     (address) => {
       if (!canWrite) return;
+      if (editing && editing.rowId === address.rowId && editing.key === address.key) return;
+      const current = shownValue(address.rowId, address.key);
+      startedFrom.current = current;
+      setDraft(current);
       setEditing(address);
       void versionOf(client, versions.current, address.rowId);
     },
-    [canWrite, client]
+    [canWrite, client, editing, shownValue]
   );
-  const cancel = useCallback3(() => setEditing(null), []);
+  const cancel = useCallback3(() => {
+    setEditing(null);
+    setDraft(null);
+    startedFrom.current = null;
+  }, []);
   const writeCellNow = useCallback3(
     async (rowId, key, value2) => {
       const id = cellKey(rowId, key);
@@ -1041,21 +1088,31 @@ function useGridEditing({ tableId, fields, rows, reload, canWrite }) {
     [client, reload]
   );
   const commit = useCallback3(
-    (value2, move = null) => {
+    (move = null) => {
       const open = editing;
       if (!open) return;
-      const row = rows.find((r) => r.id === open.rowId);
-      const unchanged = row !== void 0 && sameValue(row.document?.[open.key], value2);
-      if (!unchanged) void writeCell(open.rowId, open.key, value2);
+      const value2 = draft;
+      if (!sameValue(startedFrom.current, value2)) void writeCell(open.rowId, open.key, value2);
       if (!move) {
         setEditing(null);
+        setDraft(null);
+        startedFrom.current = null;
         return;
       }
       const next = step(open, order, rowIds, move);
+      if (!next) {
+        setEditing(null);
+        setDraft(null);
+        startedFrom.current = null;
+        return;
+      }
+      const starting = shownValue(next.rowId, next.key);
+      startedFrom.current = starting;
+      setDraft(starting);
       setEditing(next);
-      if (next) void versionOf(client, versions.current, next.rowId);
+      void versionOf(client, versions.current, next.rowId);
     },
-    [editing, rows, writeCell, order, rowIds, client]
+    [editing, draft, writeCell, order, rowIds, client, shownValue]
   );
   const retry = useCallback3(
     (rowId, key) => {
@@ -1110,12 +1167,18 @@ function useGridEditing({ tableId, fields, rows, reload, canWrite }) {
     }
     reload();
     const first = order[0];
-    if (first) setEditing({ rowId: written.data, key: first });
+    if (first) {
+      startedFrom.current = void 0;
+      setDraft(void 0);
+      setEditing({ rowId: written.data, key: first });
+    }
     return null;
   }, [client, tableId, reload, order]);
   return {
     valueFor,
     editing,
+    draft,
+    type: setDraft,
     stateOf,
     refusalOf,
     begin,
@@ -1178,27 +1241,40 @@ function GridCell({
       OpenCell,
       {
         field,
-        value: value2,
-        onCommit: (next, move) => editing.commit(next, move),
+        draft: editing.draft,
+        onType: editing.type,
+        onCommit: (move) => editing.commit(move),
         onCancel: editing.cancel
       }
     );
   }
-  return /* @__PURE__ */ jsxs5("span", { "data-matrx-cell-control": "", className: "flex min-w-0 flex-col gap-0.5", children: [
+  const openThisCell = (event) => {
+    event.preventDefault();
+    event.stopPropagation();
+    editing.begin({ rowId: row.id, key: field.key });
+  };
+  return /* @__PURE__ */ jsxs5("span", { "data-matrx-cell-control": "", className: "flex w-full min-w-0 flex-col gap-0.5", children: [
     /* @__PURE__ */ jsx8(
       "span",
       {
         role: editable ? "button" : void 0,
         tabIndex: editable ? 0 : void 0,
         "aria-label": editable ? `Edit ${fieldName(field)}` : void 0,
-        title: editable ? `${fieldName(field)} \u2014 press Enter to edit` : void 0,
+        title: editable ? `${fieldName(field)} \u2014 click or press Enter to edit` : `${fieldName(field)} is worked out by the system, so it cannot be typed in`,
         className: cn6(
-          "block min-w-0 truncate rounded px-1 py-0.5",
+          // `w-full` so the whole cell is the control. A gap beside it is bare
+          // table cell, and a click there is a row click.
+          "block w-full min-w-0 truncate rounded px-1 py-0.5",
           editable ? "cursor-text hover:bg-muted focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring" : "",
           state === "saving" ? "opacity-60" : "",
           state === "refused" ? "ring-1 ring-destructive" : ""
         ),
-        onClick: editable ? () => editing.begin({ rowId: row.id, key: field.key }) : void 0,
+        onClick: editable ? openThisCell : void 0,
+        onDoubleClick: (event) => {
+          event.preventDefault();
+          event.stopPropagation();
+          if (editable) editing.begin({ rowId: row.id, key: field.key });
+        },
         onKeyDown: editable ? (event) => {
           if (event.key === "Enter" || event.key === "F2") {
             event.preventDefault();
@@ -1241,11 +1317,11 @@ function closesOnBlur(field) {
 }
 function OpenCell({
   field,
-  value: value2,
+  draft,
+  onType,
   onCommit,
   onCancel
 }) {
-  const [draft, setDraft] = useState5(value2);
   const multiline = editorKindFor(field) === "long_text";
   const blurCommits = closesOnBlur(field);
   const done = useRef2(false);
@@ -1254,22 +1330,24 @@ function OpenCell({
     done.current = true;
     run();
   };
+  const host = useRef2(null);
+  useEffect5(() => {
+    const control = host.current?.querySelector("input, textarea, [role='combobox'], button");
+    if (control && document.activeElement !== control) control.focus();
+  }, [field.id]);
   const blur = blurCommits ? {
     onBlur: (event) => {
       if (event.currentTarget.contains(event.relatedTarget)) return;
-      once(() => onCommit(draft, null));
+      once(() => onCommit(null));
     }
   } : {};
   return /* @__PURE__ */ jsxs5(
     "span",
     {
+      ref: host,
       "data-matrx-cell-control": "",
-      className: "flex min-w-[10rem] flex-col gap-1",
-      ref: (node) => {
-        if (!node) return;
-        const control = node.querySelector("input, textarea, [role='combobox'], button");
-        if (control && document.activeElement !== control) control.focus();
-      },
+      className: "flex w-full min-w-[10rem] flex-col gap-1",
+      onDoubleClick: (event) => event.stopPropagation(),
       onKeyDown: (event) => {
         if (event.key === "Escape") {
           event.preventDefault();
@@ -1280,20 +1358,20 @@ function OpenCell({
         if (event.key === "Tab") {
           event.preventDefault();
           event.stopPropagation();
-          once(() => onCommit(draft, event.shiftKey ? "previous" : "next"));
+          once(() => onCommit(event.shiftKey ? "previous" : "next"));
           return;
         }
         if (event.key === "Enter" && (!multiline || event.metaKey || event.ctrlKey)) {
           event.preventDefault();
           event.stopPropagation();
-          once(() => onCommit(draft, null));
+          once(() => onCommit(null));
         }
       },
       ...blur,
       children: [
-        /* @__PURE__ */ jsx8(FieldControl, { field, value: draft, onChange: setDraft, id: `cell-${field.id}` }),
+        /* @__PURE__ */ jsx8(FieldControl, { field, value: draft, onChange: onType, id: `cell-${field.id}` }),
         blurCommits ? /* @__PURE__ */ jsx8("span", { className: "text-[10px] text-muted-foreground", children: multiline ? "\u2318\u23CE saves \xB7 Esc cancels \xB7 Tab next" : "\u23CE saves \xB7 Esc cancels \xB7 Tab next" }) : /* @__PURE__ */ jsxs5("span", { className: "flex items-center gap-1", children: [
-          /* @__PURE__ */ jsx8(Button4, { size: "sm", onClick: () => once(() => onCommit(draft, null)), children: "Save" }),
+          /* @__PURE__ */ jsx8(Button4, { size: "sm", onClick: () => once(() => onCommit(null)), children: "Save" }),
           /* @__PURE__ */ jsx8(Button4, { size: "sm", variant: "ghost", onClick: () => once(onCancel), children: "Cancel" })
         ] })
       ]
@@ -1386,6 +1464,8 @@ function Grid({
         tableId: `records-grid-${tableId}`,
         stickyHeader: true,
         pageSize,
+        detail: { enabled: false },
+        window: { enabled: false },
         ...onOpenRecord ? { onRowOpen: (row) => onOpenRecord(row.id) } : {},
         ...canWrite ? {
           rowActions: (row) => /* @__PURE__ */ jsx9(
@@ -1727,7 +1807,7 @@ import { useFields as useFields5, useRecord as useRecord2, useTable as useTable3
 import { Button as Button9, Separator as Separator3, cn as cn11 } from "@ai-matrx/design-system";
 
 // src/RecordForm.tsx
-import { useEffect as useEffect6, useMemo as useMemo8, useState as useState10 } from "react";
+import { useEffect as useEffect7, useMemo as useMemo8, useState as useState10 } from "react";
 import {
   useFields as useFields4,
   useRecord,
@@ -1737,7 +1817,7 @@ import { predictWriteRefusals } from "@ai-matrx/records/core";
 import { Button as Button8, Separator as Separator2, cn as cn10 } from "@ai-matrx/design-system";
 
 // src/systemTable.ts
-import { useEffect as useEffect5, useMemo as useMemo7, useState as useState9 } from "react";
+import { useEffect as useEffect6, useMemo as useMemo7, useState as useState9 } from "react";
 import { useRecordsClient as useRecordsClient6 } from "@ai-matrx/records/react";
 var inFlight = /* @__PURE__ */ new Map();
 async function ensureSystemTable(client, spec) {
@@ -1878,7 +1958,7 @@ function useSystemTable(spec) {
   const [state, setState] = useState9({ tableId: null, loading: true, error: null });
   const slug = spec.slug;
   const stable = useMemo7(() => spec, [slug]);
-  useEffect5(() => {
+  useEffect6(() => {
     let cancelled = false;
     setState({ tableId: null, loading: true, error: null });
     void ensureSystemTable(client, stable).then((result) => {
@@ -1896,7 +1976,7 @@ function useSystemTable(spec) {
 function useRecordVersion(recordId) {
   const client = useRecordsClient6();
   const [version, setVersion] = useState9(null);
-  useEffect5(() => {
+  useEffect6(() => {
     let cancelled = false;
     setVersion(null);
     if (!recordId) return;
@@ -1933,7 +2013,7 @@ function RecordForm({
   const [touched, setTouched] = useState10(false);
   const loaded = useRecordVersion(recordId ?? null);
   const loadedVersion = loaded.version;
-  useEffect6(() => {
+  useEffect7(() => {
     const document3 = existing.data?.document;
     if (document3) setDraft({ ...document3 });
   }, [existing.data?.record_id, loadedVersion]);
@@ -2208,7 +2288,6 @@ function FieldEditor({ tableId, field, onSaved, onCancel, onRemoved, className }
     [fields.data, field?.id]
   );
   const relations = useMemo10(() => others.filter((f) => f.type === "relation"), [others]);
-  const manyRelations = useMemo10(() => relations.filter((f) => f.multi), [relations]);
   const choice = fieldTypeChoice(type);
   const editing = Boolean(field);
   const derivedKey = field?.key ?? keyFor(label);
@@ -2216,7 +2295,9 @@ function FieldEditor({ tableId, field, onSaved, onCancel, onRemoved, className }
     return /* @__PURE__ */ jsx14("p", { className: cn12("text-xs text-muted-foreground", className), children: rights.reason });
   }
   const options = optionText.split("\n").map((word) => word.trim()).filter((word) => word !== "");
+  const missing = editing ? null : whatIsMissing({ type, label, options, via, pick, agg, of, relations, formulaFields });
   const save = async () => {
+    if (missing) return;
     if (editing && field) {
       const patch = {
         label,
@@ -2322,7 +2403,6 @@ function FieldEditor({ tableId, field, onSaved, onCancel, onRemoved, className }
         formulaFields,
         setFormulaFields,
         relations,
-        manyRelations,
         others,
         existingOptionsTable: Boolean(field?.options_table_id ?? field?.config?.["options_table_id"])
       }
@@ -2437,8 +2517,17 @@ function FieldEditor({ tableId, field, onSaved, onCancel, onRemoved, className }
       ] }, `${rule.kind}-${index}`))
     ] }),
     mutation.error ? /* @__PURE__ */ jsx14(RefusalNotice, { error: mutation.error }) : null,
+    missing ? /* @__PURE__ */ jsx14("p", { className: "text-[11px] text-destructive", children: missing }) : null,
     /* @__PURE__ */ jsxs11("div", { className: "flex flex-wrap items-center gap-2", children: [
-      /* @__PURE__ */ jsx14(Button10, { size: "sm", disabled: mutation.saving || label.trim() === "", onClick: () => void save(), children: mutation.saving ? "Saving\u2026" : field ? "Save field" : "Add field" }),
+      /* @__PURE__ */ jsx14(
+        Button10,
+        {
+          size: "sm",
+          disabled: mutation.saving || missing !== null,
+          onClick: () => void save(),
+          children: mutation.saving ? "Saving\u2026" : field ? "Save field" : "Add field"
+        }
+      ),
       onCancel ? /* @__PURE__ */ jsx14(Button10, { size: "sm", variant: "ghost", onClick: onCancel, children: "Cancel" }) : null,
       field ? /* @__PURE__ */ jsx14("div", { className: "ml-auto flex items-center gap-2", children: askingToRemove ? /* @__PURE__ */ jsxs11(Fragment4, { children: [
         /* @__PURE__ */ jsxs11("span", { className: "text-destructive", children: [
@@ -2452,6 +2541,34 @@ function FieldEditor({ tableId, field, onSaved, onCancel, onRemoved, className }
     ] })
   ] });
 }
+function whatIsMissing(state) {
+  const { type, label, options, via, pick, agg, of, relations, formulaFields } = state;
+  if (label.trim() === "") return "Give the column a name.";
+  if (type === "select" || type === "multi_select") {
+    if (options.length === 0) return "Type the choices this column offers, one per line.";
+    return null;
+  }
+  if (type === "lookup" || type === "rollup") {
+    if (relations.length === 0) {
+      return type === "rollup" ? "A total is worked out across the records a column points at, and this table has no column that points at records yet. Add a Person or File column that can hold more than one, then come back." : "A borrowed value is read from a record a column points at, and this table has no column that points at another record yet. Add a Person or File column, then come back.";
+    }
+    const chosen = relations.find((relation) => relation.key === via);
+    if (!chosen) {
+      return type === "rollup" ? "Choose the column whose records this one adds up." : "Choose the column whose record this one reads from.";
+    }
+    if (type === "rollup" && !chosen.multi) {
+      return `${fieldName(chosen)} points at one record at a time, so there is nothing to total. Tick "Can hold more than one" on ${fieldName(chosen)}, or use Borrowed value to read its one value.`;
+    }
+    if (type === "lookup" && pick.trim() === "") {
+      return `Say which value to read from the record ${fieldName(chosen)} points at.`;
+    }
+    if (type === "rollup" && agg !== "count" && of.trim() === "") {
+      return "Say which value of those records to work out.";
+    }
+    return null;
+  }
+  return null;
+}
 function multiApplies(type) {
   return type === "member" || type === "attachment" || type === "text";
 }
@@ -2517,16 +2634,19 @@ function TypeQuestions(props) {
     ] });
   }
   if (type === "lookup" || type === "rollup") {
-    const usable = type === "rollup" ? props.manyRelations : props.relations;
+    const usable = props.relations;
     if (usable.length === 0) {
-      return /* @__PURE__ */ jsx14("p", { className: "text-[11px] text-muted-foreground", children: type === "rollup" ? "This kind of column works something out from records this one points at, and this table has no column yet that points at several records. Add a Person or File column that can hold more than one first." : "This kind of column reads a value from a record this one points at, and this table has no column yet that points at another record. Add a Person or File column first." });
+      return /* @__PURE__ */ jsx14("p", { className: "text-[11px] text-muted-foreground", children: type === "rollup" ? "This kind of column works something out from the records another column points at, and this table has no column that points at records yet. Add a Person or File column that can hold more than one first." : "This kind of column reads a value from a record another column points at, and this table has no column that points at another record yet. Add a Person or File column first." });
     }
     return /* @__PURE__ */ jsxs11("div", { className: "grid gap-3 sm:grid-cols-2", children: [
       /* @__PURE__ */ jsxs11("div", { className: "flex flex-col gap-1", children: [
         /* @__PURE__ */ jsx14(Label2, { className: "text-xs", children: type === "rollup" ? "Across the records in" : "Read it from" }),
         /* @__PURE__ */ jsxs11(Select2, { value: props.via, onValueChange: props.setVia, children: [
           /* @__PURE__ */ jsx14(SelectTrigger2, { size: "sm", "aria-label": type === "rollup" ? "Across the records in" : "Read it from", children: /* @__PURE__ */ jsx14(SelectValue2, { placeholder: "Choose a column" }) }),
-          /* @__PURE__ */ jsx14(SelectContent2, { children: usable.map((f) => /* @__PURE__ */ jsx14(SelectItem2, { value: f.key, children: fieldName(f) }, f.id)) })
+          /* @__PURE__ */ jsx14(SelectContent2, { children: usable.map((f) => /* @__PURE__ */ jsxs11(SelectItem2, { value: f.key, children: [
+            fieldName(f),
+            type === "rollup" && !f.multi ? " \u2014 holds one" : ""
+          ] }, f.id)) })
         ] })
       ] }),
       type === "lookup" ? /* @__PURE__ */ jsxs11("label", { className: "flex flex-col gap-1", children: [
@@ -2978,7 +3098,7 @@ function parseSorts(raw) {
 }
 
 // src/ViewSwitcher.tsx
-import { useEffect as useEffect7, useMemo as useMemo11, useState as useState16 } from "react";
+import { useEffect as useEffect8, useMemo as useMemo11, useState as useState16 } from "react";
 import { useFields as useFields9, useRecords as useRecords3, useRecordsClient as useRecordsClient8 } from "@ai-matrx/records/react";
 import { Button as Button14, Skeleton as Skeleton3, cn as cn15 } from "@ai-matrx/design-system";
 import { jsx as jsx18, jsxs as jsxs15 } from "react/jsx-runtime";
@@ -2991,7 +3111,7 @@ function useViewRecords(view, pageSize = 200) {
     error: null
   });
   const ruleId = view.ruleId ?? null;
-  useEffect7(() => {
+  useEffect8(() => {
     if (!ruleId) return;
     let cancelled = false;
     setRuled({ rows: [], loading: true, error: null });
@@ -3041,7 +3161,7 @@ function ViewSwitcher({
 }) {
   const [layout, setLayout] = useState16(view.layout);
   const [local, setLocal] = useState16({});
-  useEffect7(() => {
+  useEffect8(() => {
     setLayout(view.layout);
     setLocal({});
   }, [view.layout, view.name, view.subject]);
@@ -3318,7 +3438,7 @@ function Card({
 }
 
 // src/ViewBar.tsx
-import { useCallback as useCallback5, useEffect as useEffect8, useState as useState17 } from "react";
+import { useCallback as useCallback5, useEffect as useEffect9, useState as useState17 } from "react";
 import { useRecordsClient as useRecordsClient9 } from "@ai-matrx/records/react";
 import { Button as Button15, Input, Skeleton as Skeleton4, cn as cn16 } from "@ai-matrx/design-system";
 
@@ -3380,10 +3500,10 @@ function ViewBar({ tableId, activeViewId, onActiveView, seed, className }) {
     setError(null);
     setViews(mine);
   }, [client, viewTableId, tableId, seed]);
-  useEffect8(() => {
+  useEffect9(() => {
     void load();
   }, [load]);
-  useEffect8(() => {
+  useEffect9(() => {
     if (!views || views.length === 0) return;
     const chosen = views.find((v) => v.id === (activeViewId ?? active)) ?? views.find((v) => v.isDefault) ?? views[0];
     if (chosen.id !== active) setActive(chosen.id);
@@ -3561,7 +3681,7 @@ function ProposalRow({
 }
 
 // src/ActionInbox.tsx
-import { useCallback as useCallback6, useEffect as useEffect9, useMemo as useMemo12, useState as useState19 } from "react";
+import { useCallback as useCallback6, useEffect as useEffect10, useMemo as useMemo12, useState as useState19 } from "react";
 import { useRecordsClient as useRecordsClient11 } from "@ai-matrx/records/react";
 import { Badge as Badge6, Button as Button17, Skeleton as Skeleton5, cn as cn18 } from "@ai-matrx/design-system";
 import { jsx as jsx21, jsxs as jsxs18 } from "react/jsx-runtime";
@@ -3640,7 +3760,7 @@ function ActionInbox({ tableId, includeSettled = false, seed, onOpenRecord, clas
     setError(null);
     setActions(held);
   }, [client, queueTableId, seed]);
-  useEffect9(() => {
+  useEffect10(() => {
     void load();
   }, [load]);
   const shown = useMemo12(() => {
@@ -3755,7 +3875,7 @@ function parseChanges(raw) {
 }
 
 // src/HistoryPanel.tsx
-import { useCallback as useCallback7, useEffect as useEffect10, useState as useState20 } from "react";
+import { useCallback as useCallback7, useEffect as useEffect11, useState as useState20 } from "react";
 import {
   useFields as useFields10,
   useRecordsClient as useRecordsClient12,
@@ -3802,7 +3922,7 @@ function HistoryPanel({ tableId, recordId, className }) {
     );
     setRead(read2.ok ? read2.data : { record_id: recordId, document: {}, hidden: {}, computed: [] });
   }, [client, recordId]);
-  useEffect10(() => {
+  useEffect11(() => {
     void load();
   }, [load]);
   if (error) return /* @__PURE__ */ jsx22(RefusalNotice, { error, className });
@@ -3862,7 +3982,7 @@ function HistoryPanel({ tableId, recordId, className }) {
 }
 
 // src/CommentThread.tsx
-import { useCallback as useCallback8, useEffect as useEffect11, useState as useState21 } from "react";
+import { useCallback as useCallback8, useEffect as useEffect12, useState as useState21 } from "react";
 import { useRecordsClient as useRecordsClient13, useTable as useTable9 } from "@ai-matrx/records/react";
 import { Button as Button19, Skeleton as Skeleton7, Textarea, cn as cn20 } from "@ai-matrx/design-system";
 import { jsx as jsx23, jsxs as jsxs20 } from "react/jsx-runtime";
@@ -3907,7 +4027,7 @@ function CommentThread({ tableId, recordId, className }) {
       result.data.rows.filter((row) => row.document?.["subject"] === recordId).map(toComment).sort((a, b) => a.at.localeCompare(b.at))
     );
   }, [client, commentTableId, recordId]);
-  useEffect11(() => {
+  useEffect12(() => {
     void load();
   }, [load]);
   async function post() {
@@ -4077,7 +4197,7 @@ function submissionStamp(args) {
 }
 
 // src/FormBuilder.tsx
-import { useCallback as useCallback10, useEffect as useEffect13, useMemo as useMemo14, useState as useState23 } from "react";
+import { useCallback as useCallback10, useEffect as useEffect14, useMemo as useMemo14, useState as useState23 } from "react";
 import { useFields as useFields12, useRecordsClient as useRecordsClient15, useTable as useTable10 } from "@ai-matrx/records/react";
 import {
   BasicInput as BasicInput5,
@@ -4090,7 +4210,7 @@ import {
 } from "@ai-matrx/design-system";
 
 // src/FormRunner.tsx
-import { useCallback as useCallback9, useEffect as useEffect12, useMemo as useMemo13, useRef as useRef4, useState as useState22 } from "react";
+import { useCallback as useCallback9, useEffect as useEffect13, useMemo as useMemo13, useRef as useRef4, useState as useState22 } from "react";
 import { useFields as useFields11, useRecordsClient as useRecordsClient14 } from "@ai-matrx/records/react";
 import { doorExists, DOORS } from "@ai-matrx/records/core";
 import { Button as Button20, Progress, Skeleton as Skeleton8, cn as cn21 } from "@ai-matrx/design-system";
@@ -4120,7 +4240,7 @@ function FormRunner({ form, preview = false, onSubmitted, className }) {
       };
     });
   }, [fields.data, form.questions]);
-  useEffect12(() => {
+  useEffect13(() => {
     let cancelled = false;
     const conditional = questions.filter((q) => q.showIf);
     if (conditional.length === 0) return;
@@ -4195,7 +4315,7 @@ function FormRunner({ form, preview = false, onSubmitted, className }) {
     if (event.shiftKey) retreat();
     else advance();
   }
-  useEffect12(() => {
+  useEffect13(() => {
     const input = stage.current?.querySelector("input, textarea, select, [role='combobox']");
     input?.focus();
   }, [index, done]);
@@ -4361,10 +4481,10 @@ function FormBuilder({ tableId, seed, activeFormId, onActiveForm, className }) {
     setError(null);
     setForms(mine);
   }, [client, formTableId, tableId, seed]);
-  useEffect13(() => {
+  useEffect14(() => {
     void load();
   }, [load]);
-  useEffect13(() => {
+  useEffect14(() => {
     if (!forms || forms.length === 0) return;
     const chosen = forms.find((f) => f.id === (activeFormId ?? activeId)) ?? forms[0];
     if (chosen.id !== activeId) setActiveId(chosen.id);
@@ -4736,7 +4856,7 @@ function isSignatureField(field) {
 }
 
 // src/DocTemplate.tsx
-import { useCallback as useCallback11, useEffect as useEffect14, useState as useState24 } from "react";
+import { useCallback as useCallback11, useEffect as useEffect15, useState as useState24 } from "react";
 import { useFields as useFields13, useRecordsClient as useRecordsClient16, useTable as useTable11 } from "@ai-matrx/records/react";
 import { BasicInput as BasicInput6, BasicTextarea as BasicTextarea4, Button as Button22, Label as Label4, Skeleton as Skeleton10, cn as cn23 } from "@ai-matrx/design-system";
 import { jsx as jsx26, jsxs as jsxs23 } from "react/jsx-runtime";
@@ -4784,10 +4904,10 @@ function DocTemplate({ tableId, seed, activeTemplateId, onActiveTemplate, classN
     setError(null);
     setTemplates(rows);
   }, [client, tableId, seed, fields.data]);
-  useEffect14(() => {
+  useEffect15(() => {
     void load();
   }, [load]);
-  useEffect14(() => {
+  useEffect15(() => {
     if (!templates || templates.length === 0) return;
     const chosen = templates.find((t) => t.id === (activeTemplateId ?? activeId)) ?? templates[0];
     if (chosen.id !== activeId) setActiveId(chosen.id);
@@ -4795,7 +4915,7 @@ function DocTemplate({ tableId, seed, activeTemplateId, onActiveTemplate, classN
     setDraftBody(chosen.body);
     onActiveTemplate?.(chosen);
   }, [templates, activeTemplateId]);
-  useEffect14(() => {
+  useEffect15(() => {
     let cancelled = false;
     if (draftBody.trim() === "") {
       setUnresolved([]);
@@ -4915,7 +5035,7 @@ function DocTemplate({ tableId, seed, activeTemplateId, onActiveTemplate, classN
 }
 
 // src/DocRender.tsx
-import { useCallback as useCallback12, useEffect as useEffect15, useRef as useRef5, useState as useState25 } from "react";
+import { useCallback as useCallback12, useEffect as useEffect16, useRef as useRef5, useState as useState25 } from "react";
 import { useRecordsClient as useRecordsClient17 } from "@ai-matrx/records/react";
 import { Button as Button23, Skeleton as Skeleton11, cn as cn24 } from "@ai-matrx/design-system";
 import { jsx as jsx27, jsxs as jsxs24 } from "react/jsx-runtime";
@@ -4944,7 +5064,7 @@ function DocRender({ templateId, recordId, filename, onRendered, className }) {
     setPreview(body.data);
     setRenders(held.data.filter((r) => r.template_id === templateId));
   }, [client, templateId, recordId]);
-  useEffect15(() => {
+  useEffect16(() => {
     void load();
   }, [load]);
   async function freeze() {
@@ -5028,7 +5148,7 @@ function DocRender({ templateId, recordId, filename, onRendered, className }) {
 }
 
 // src/SignBlock.tsx
-import { useCallback as useCallback13, useEffect as useEffect16, useState as useState26 } from "react";
+import { useCallback as useCallback13, useEffect as useEffect17, useState as useState26 } from "react";
 import { useFields as useFields14, useRecordsClient as useRecordsClient18 } from "@ai-matrx/records/react";
 import { BasicInput as BasicInput7, Button as Button24, Skeleton as Skeleton12, cn as cn25 } from "@ai-matrx/design-system";
 import { useTable as useTable12 } from "@ai-matrx/records/react";
@@ -5058,7 +5178,7 @@ function SignBlock({ tableId, recordId, render, className }) {
     }
     setVerdicts(answers);
   }, [client, recordId]);
-  useEffect16(() => {
+  useEffect17(() => {
     void load();
   }, [load]);
   async function sign(field) {
@@ -5165,7 +5285,7 @@ function SignBlock({ tableId, recordId, render, className }) {
 }
 
 // src/NotifyRuleEditor.tsx
-import { useCallback as useCallback14, useEffect as useEffect17, useState as useState27 } from "react";
+import { useCallback as useCallback14, useEffect as useEffect18, useState as useState27 } from "react";
 import { useRecordsClient as useRecordsClient19, useTable as useTable13 } from "@ai-matrx/records/react";
 import { Button as Button25, Skeleton as Skeleton13, cn as cn26 } from "@ai-matrx/design-system";
 import { jsx as jsx29, jsxs as jsxs26 } from "react/jsx-runtime";
@@ -5196,7 +5316,7 @@ function NotifyRuleEditor({ tableId, seed, className }) {
     if (host.savedViews) setViews(await host.savedViews());
     else setViews(null);
   }, [client, host]);
-  useEffect17(() => {
+  useEffect18(() => {
     void load();
   }, [load]);
   const write = useCallback14(
@@ -5231,7 +5351,7 @@ function NotifyRuleEditor({ tableId, seed, className }) {
     },
     [client, tableId]
   );
-  useEffect17(() => {
+  useEffect18(() => {
     if (!subscriptions || !seed || seed.length === 0) return;
     const missing = seed.filter((s) => !subscriptions.some((held) => held.name === s.name));
     if (missing.length === 0) return;
@@ -5320,7 +5440,7 @@ function NotifyRuleEditor({ tableId, seed, className }) {
 }
 
 // src/ChartBlock.tsx
-import { useEffect as useEffect18, useState as useState28 } from "react";
+import { useEffect as useEffect19, useState as useState28 } from "react";
 import { useRecordsClient as useRecordsClient20 } from "@ai-matrx/records/react";
 import { measureKey } from "@ai-matrx/records";
 import { Skeleton as Skeleton14, cn as cn27 } from "@ai-matrx/design-system";
@@ -5341,7 +5461,7 @@ function ChartBlock({ spec, className }) {
     f: spec.filter ?? {},
     l: spec.limit ?? 50
   });
-  useEffect18(() => {
+  useEffect19(() => {
     if (needs) return;
     let cancelled = false;
     setRows(null);
@@ -5488,7 +5608,7 @@ function Drawing({ kind, rows, measure }) {
 }
 
 // src/DashboardCanvas.tsx
-import { useCallback as useCallback15, useEffect as useEffect19, useState as useState29 } from "react";
+import { useCallback as useCallback15, useEffect as useEffect20, useState as useState29 } from "react";
 import { useFields as useFields15, useRecordsClient as useRecordsClient21, useTable as useTable14 } from "@ai-matrx/records/react";
 import { Button as Button26, Skeleton as Skeleton15, cn as cn28 } from "@ai-matrx/design-system";
 import { jsx as jsx31, jsxs as jsxs28 } from "react/jsx-runtime";
@@ -5535,10 +5655,10 @@ function DashboardCanvas({ tableId, seed, activeDashboardId, className }) {
     setError(null);
     setBoards(mine);
   }, [client, boardTableId, tableId, seed]);
-  useEffect19(() => {
+  useEffect20(() => {
     void load();
   }, [load]);
-  useEffect19(() => {
+  useEffect20(() => {
     if (!boards || boards.length === 0) return;
     const chosen = boards.find((d) => d.id === (activeDashboardId ?? activeId)) ?? boards[0];
     if (chosen.id !== activeId) setActiveId(chosen.id);
@@ -5675,7 +5795,7 @@ function DashboardCanvas({ tableId, seed, activeDashboardId, className }) {
 }
 
 // src/RecordChat.tsx
-import { useEffect as useEffect20, useMemo as useMemo15, useState as useState30 } from "react";
+import { useEffect as useEffect21, useMemo as useMemo15, useState as useState30 } from "react";
 import { useFields as useFields16, useRecordsClient as useRecordsClient22, useTable as useTable15 } from "@ai-matrx/records/react";
 import { Skeleton as Skeleton16, cn as cn29 } from "@ai-matrx/design-system";
 import { jsx as jsx32, jsxs as jsxs29 } from "react/jsx-runtime";
@@ -5687,7 +5807,7 @@ function RecordChat({ tableId, recordId, className }) {
   const fields = useFields16(tableId);
   const [read, setRead] = useState30(null);
   const [error, setError] = useState30(null);
-  useEffect20(() => {
+  useEffect21(() => {
     let cancelled = false;
     setRead(null);
     setError(null);
@@ -5808,7 +5928,7 @@ function noticeText(notice) {
 }
 
 // src/EnrichPanel.tsx
-import { useCallback as useCallback16, useEffect as useEffect21, useMemo as useMemo16, useState as useState31 } from "react";
+import { useCallback as useCallback16, useEffect as useEffect22, useMemo as useMemo16, useState as useState31 } from "react";
 import { useFields as useFields17, useRecordsClient as useRecordsClient23, useTable as useTable16 } from "@ai-matrx/records/react";
 import { Badge as Badge8, Button as Button27, Skeleton as Skeleton17, cn as cn30 } from "@ai-matrx/design-system";
 import { jsx as jsx33, jsxs as jsxs30 } from "react/jsx-runtime";
@@ -5832,7 +5952,7 @@ function EnrichPanel({ tableId, recordId, className }) {
     setError(null);
     setDocument(answered.data.document);
   }, [client, recordId]);
-  useEffect21(() => {
+  useEffect22(() => {
     void load();
   }, [load]);
   const agentFields = useMemo16(() => {
@@ -5971,7 +6091,7 @@ function describe(field, document2) {
 }
 
 // src/ChecklistRunner.tsx
-import { useCallback as useCallback17, useEffect as useEffect22, useMemo as useMemo17, useState as useState32 } from "react";
+import { useCallback as useCallback17, useEffect as useEffect23, useMemo as useMemo17, useState as useState32 } from "react";
 import { useRecordsClient as useRecordsClient24, useTable as useTable17 } from "@ai-matrx/records/react";
 import { Badge as Badge9, Button as Button28, Skeleton as Skeleton18, cn as cn31 } from "@ai-matrx/design-system";
 import { jsx as jsx34, jsxs as jsxs31 } from "react/jsx-runtime";
@@ -6003,7 +6123,7 @@ function ChecklistRunner({ tableId, seed, className }) {
   const [busy, setBusy] = useState32(false);
   const [note, setNote] = useState32(null);
   const runTableId = home.tableId;
-  useEffect22(() => {
+  useEffect23(() => {
     let cancelled = false;
     void client.workStates().then((answered) => {
       if (cancelled || !answered.ok) return;
@@ -6025,10 +6145,10 @@ function ChecklistRunner({ tableId, seed, className }) {
     setRuns(held);
     return held;
   }, [client, runTableId, tableId]);
-  useEffect22(() => {
+  useEffect23(() => {
     void loadRuns();
   }, [loadRuns]);
-  useEffect22(() => {
+  useEffect23(() => {
     let cancelled = false;
     if (!runTableId || !seed || seed.length === 0 || runs === null) return;
     const missing = seed.filter((spec) => !runs.some((run) => run.name === spec.name));
@@ -6060,7 +6180,7 @@ function ChecklistRunner({ tableId, seed, className }) {
     }
     setTurns(answered.data);
   }, [client, tableId]);
-  useEffect22(() => {
+  useEffect23(() => {
     void loadTurns();
   }, [loadTurns, active?.id, active?.stepIds.length]);
   async function move(step2, to) {
@@ -6209,7 +6329,7 @@ function toRun(row) {
 }
 
 // src/BookingSlots.tsx
-import { useCallback as useCallback18, useEffect as useEffect23, useMemo as useMemo18, useState as useState33 } from "react";
+import { useCallback as useCallback18, useEffect as useEffect24, useMemo as useMemo18, useState as useState33 } from "react";
 import { useRecordsClient as useRecordsClient25, useTable as useTable18 } from "@ai-matrx/records/react";
 import { Button as Button29, Skeleton as Skeleton19, cn as cn32 } from "@ai-matrx/design-system";
 import { jsx as jsx35, jsxs as jsxs32 } from "react/jsx-runtime";
@@ -6231,7 +6351,7 @@ function BookingSlots({
   const [refused, setRefused] = useState33(null);
   const me = client.config.actor.user_id ?? "anonymous";
   const slug = `records_ui_slots_${tableId.replace(/-/g, "").slice(0, 16)}`;
-  useEffect23(() => {
+  useEffect24(() => {
     let cancelled = false;
     void (async () => {
       const tables = await client.tableList();
@@ -6284,7 +6404,7 @@ function BookingSlots({
     setError(null);
     setHolds(answered.data);
   }, [client, slotTableId]);
-  useEffect23(() => {
+  useEffect24(() => {
     void loadHolds();
   }, [loadHolds]);
   const slots = useMemo18(() => {
@@ -6416,7 +6536,7 @@ function whenText(at) {
 }
 
 // src/CaptureSheet.tsx
-import { useCallback as useCallback19, useEffect as useEffect24, useRef as useRef6, useState as useState34 } from "react";
+import { useCallback as useCallback19, useEffect as useEffect25, useRef as useRef6, useState as useState34 } from "react";
 import { useFields as useFields18, useRecordsClient as useRecordsClient26, useTable as useTable19 } from "@ai-matrx/records/react";
 import { Button as Button30, Input as Input2, Skeleton as Skeleton20, Textarea as Textarea2, cn as cn33 } from "@ai-matrx/design-system";
 import { Fragment as Fragment10, jsx as jsx36, jsxs as jsxs33 } from "react/jsx-runtime";
@@ -6460,7 +6580,7 @@ function CaptureSheet({
     },
     [host]
   );
-  useEffect24(() => {
+  useEffect25(() => {
     let cancelled = false;
     void (async () => {
       const held = host.captureQueue ? await host.captureQueue.load() : [];
@@ -6639,7 +6759,7 @@ function CaptureSheet({
 }
 
 // src/PortalShell.tsx
-import { useCallback as useCallback20, useEffect as useEffect25, useState as useState35 } from "react";
+import { useCallback as useCallback20, useEffect as useEffect26, useState as useState35 } from "react";
 import { useRecordsClient as useRecordsClient27 } from "@ai-matrx/records/react";
 import { Button as Button31, Skeleton as Skeleton21, cn as cn34 } from "@ai-matrx/design-system";
 import { jsx as jsx37, jsxs as jsxs34 } from "react/jsx-runtime";
@@ -6665,7 +6785,7 @@ function PortalShell({ tableId, form, resourceType = "record", className }) {
     }
     setReach(reached.data.map((row) => row.resource_id));
   }, [client, resourceType]);
-  useEffect25(() => {
+  useEffect26(() => {
     void load();
   }, [load]);
   if (error) {
@@ -6725,7 +6845,7 @@ function PortalShell({ tableId, form, resourceType = "record", className }) {
 function PortalRow({ tableId, recordId }) {
   const client = useRecordsClient27();
   const [title, setTitle] = useState35(null);
-  useEffect25(() => {
+  useEffect26(() => {
     let cancelled = false;
     void client.recordRead({ record_id: recordId }).then((answered) => {
       if (cancelled) return;
@@ -6745,7 +6865,7 @@ function PortalRow({ tableId, recordId }) {
 }
 
 // src/PublicViewPage.tsx
-import { useCallback as useCallback21, useEffect as useEffect26, useState as useState36 } from "react";
+import { useCallback as useCallback21, useEffect as useEffect27, useState as useState36 } from "react";
 import { useRecordsClient as useRecordsClient28 } from "@ai-matrx/records/react";
 import { Skeleton as Skeleton22, cn as cn35 } from "@ai-matrx/design-system";
 import { jsx as jsx38, jsxs as jsxs35 } from "react/jsx-runtime";
@@ -6789,7 +6909,7 @@ function PublicViewPage({ slug, className }) {
     }
     setRows([{ id: found.resource_id, document: read.data.document, level: "viewer", hidden: read.data.hidden }]);
   }, [client, slug]);
-  useEffect26(() => {
+  useEffect27(() => {
     void load();
   }, [load]);
   if (error) return /* @__PURE__ */ jsx38(RefusalNotice, { error, className });
@@ -6826,7 +6946,7 @@ function PublicRow({ row, fields }) {
 }
 
 // src/EmbedFrame.tsx
-import { useCallback as useCallback22, useEffect as useEffect27, useState as useState37 } from "react";
+import { useCallback as useCallback22, useEffect as useEffect28, useState as useState37 } from "react";
 import { useRecordsClient as useRecordsClient29 } from "@ai-matrx/records/react";
 import { Button as Button32, Input as Input3, Skeleton as Skeleton23, Textarea as Textarea3, cn as cn36 } from "@ai-matrx/design-system";
 import { useTable as useTable20 } from "@ai-matrx/records/react";
@@ -6939,7 +7059,7 @@ function useEmbedHandshake(args) {
   const [loading, setLoading] = useState37(true);
   const origin = args.origin ?? (typeof location === "undefined" ? "" : location.origin);
   const { secret, requiredMode } = args;
-  useEffect27(() => {
+  useEffect28(() => {
     let cancelled = false;
     setLoading(true);
     setError(null);
@@ -7447,6 +7567,8 @@ export {
   formDocument,
   formFromRecord,
   groupLabel,
+  hintForAPerson,
+  hintIsMachineIdentity,
   humanize,
   idsOf,
   isId,
@@ -7479,6 +7601,7 @@ export {
   useViewRecords,
   viewDocument,
   viewFromRecord,
-  viewPatchDocument
+  viewPatchDocument,
+  whatIsMissing
 };
 //# sourceMappingURL=index.js.map