@ai-matrx/records-ui 0.52.0 → 0.56.0

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # Changelog — @ai-matrx/records-ui
 
+## 0.56.0
+
+**A condition the builder cannot draw is said in words, not blanked.**
+
+Found by a screenshot, which is what the screenshots were for. The Birchwood
+Avenue renovation's own rule demands "a second quote from a DIFFERENT
+contractor" — a `sibling_count`, which the one-clause builder cannot draw — and
+the editor rendered it as **"— pick a column —"**. That is the screen saying
+there is no condition when there is one, beside a live Save button, on a rule
+that is turning people's work away right now.
+
+It now reads: *"it cannot get here unless **how many others there are for the
+same Room from a different Contractor** — this part of the rule is not something
+this builder can draw yet, so it is shown as it reads"*, with a **Replace it**
+button. Replacing is a thing a person DID, never a thing that happened to them
+because a control looked empty — and until they press it, the clause they cannot
+draw is still the one that saves.
+
+`conditionIsSimple` and `conditionInWords` are exported, so every screen that
+mounts the builder gets the same honesty rather than each deciding for itself.
+
+## 0.55.0
+
+**Three things the bulk paste got wrong on its first real fifty rows.**
+
+Proved headlessly on **Rincon Plumbing Co's September billing run** — fifty real
+invoices, `INV-5100`…`INV-5149`, a `$1,250.50` and a `(285.00)` credit, two
+cells deliberately wrong. The paste itself worked end to end: the preview
+appeared with the store untouched, the money arrived as `1250.5` rather than the
+sheet's string, the bracketed credit as `-285`, and the outcome read *"All 198
+values are in the table — read back out of it, not just accepted"*, confirmed by
+an independent read as the same identity. These are the three things that were
+wrong with it anyway.
+
+* **Every refusal said "Row 0" and named a raw column key.** `validateCell` and
+  the planner ask the same question, and for a cell on a row that already exists
+  the primitive asks first — so the refusal arrived already decided, with a
+  column id and no line, and the planner's correct "Row 12, Amount Due" could
+  only ever fire for an overflow row. The refused cells are folded back into the
+  block with their own values (design-system 0.31.0 keeps them) and the planner
+  judges the whole thing: one place deciding, one set of words, a line number and
+  the column's own name on every refusal. With fifty rows on a clipboard that is
+  the difference between a fixable cell and a shrug.
+* **"This will change 28 Invoicess and create 22 new Invoicess."** The sentence
+  appended an "s" to `label_singular`, which for that table is already
+  "Invoices". A plural is a word a table knows (`label_plural`), never a rule
+  applied to another word.
+* **Every pasted date drew one day early**, systematically, across all fifty.
+  `2026-09-01` parsed as an INSTANT is midnight UTC, and a Ventura grid renders
+  that as 31 August. A date field holds a DAY — the day the invoice was issued is
+  the same day in Ventura and in Berlin — so a pasted day is kept as that day,
+  and only a field that actually declares a time becomes an instant. A
+  spreadsheet's own format ("9/1/2026") keeps the day the reader can see, not the
+  UTC one.
+
+**And the demo harness could not stand up in a fresh organization.** All four
+`ensure*Field` helpers updated the Table's `fields` list BEFORE inserting the
+Field definition, which `custom._claimed_column_guard` refuses outright — *"Records
+UI Demo says it has a column called \"signed_by\", and there is no such field."*
+The harness only worked in organizations provisioned before that guard landed.
+The order is the fix; the guard stays.
+
+Needs `@ai-matrx/design-system` 0.31.0.
+
+## 0.54.0
+
+**The grid shows a column the panel beside it just added, without a reload.**
+
+Measured on production 2026-09-21, Ridgeline Physical Therapy's patients table:
+"Add field" succeeded, the panel confirmed the column with its own read-back and
+closed — and the grid did not show it until the page was reloaded. The panel was
+telling the truth; the grid next to it was drawing a table that no longer
+existed.
+
+The cause is not in this package's screens, and that is the point: the grid and
+the field panel are siblings, each calling `useFields(tableId)`, each holding
+its own copy, with nothing joining them. Fixing the pair that surfaced it would
+have left the same staleness between every other pair — the rail and the grid,
+the filter and the form builder. So the signal is `@ai-matrx/records` 0.39.0's
+`tableShapeChanged`, which every shape-changing door announces and every reader
+subscribes to, and this package simply inherits it.
+
+`src/shape-changed.test.tsx` holds the five clauses at the pair a person
+actually sees, against the real client through the real doors: a column added in
+the panel appears in the grid beside it; every screen on that table re-reads,
+not one; a screen on a DIFFERENT table is left alone (a signal that woke the
+whole app would be a storm with a sensible name on it); the tick carries no data
+and the listener re-reads through the door; and a retired column disappears the
+same way. Four of the five are RED on 0.53.0's bytes.
+
+Needs `@ai-matrx/records` 0.39.0.
+
+## 0.53.0
+
+**Every card on every board said "Loading…", forever.**
+
+Birchwood Avenue Renovation is a whole-house remodel run out of a spare bedroom.
+Her quotes board, grouped by Quote stage, had the counts exactly right — Accepted
+6, Expired 1, Pending 6, Rejected 1, No value 1, off her real quotes — and all
+fifteen cards under those headings read "Loading…" and never resolved. No error,
+no refusal, no spinner that ever stopped. She could count her quotes and could
+not open one.
+
+The cause was one missing argument. `scalarText` draws "Loading…" for an id it
+has no resolver for, and `Card` called it with no resolver at all, so a title
+Field of type `list` or `relation` could never resolve on any card, ever — and
+Birchwood's title field is `room`, a relation to her rooms table. `Kanban` asks
+the resolver for the GROUPING field, which is precisely why the headings read
+"Accepted" while the cards beneath them read "Loading…": two halves of one board,
+one asking and one not.
+
+`Card` is the card of the **kanban, the calendar and the gallery**, so one
+argument broke three layouts and one fix closes all three. The component that
+draws the value now declares the Field it is about to draw, which is also what
+makes a future surface unable to reintroduce this by forgetting; `want` is keyed
+by Field id, so two hundred cards still ask once.
+
+**And a card that cannot load now says why.** Declaring the Field is what lets
+the resolver SETTLE it. Once settled, an id it did not return is chased one at a
+time and comes back either as the record's own name or as the store's own
+sentence for a record this reader may not open
+(`platform.relation_withheld_label()`). "Loading…" is now only ever true.
+
+`src/card-names-what-it-draws.test.tsx` — three clauses, two shown RED on
+0.52.0's bytes ("Loading…") and green on these.
+
 ## 0.52.0
 
 **Four things this package could make and no screen could reach: a form, a

package/dist/index.cjs

@@ -94,6 +94,7 @@ __export(src_exports, {
   MyChecklistSteps: () => MyChecklistSteps,
   NEEDS_A_SENTENCE: () => NEEDS_A_SENTENCE,
   NOT_ANSWERED_YET: () => NOT_ANSWERED_YET,
+  NOT_DRAWN_HERE: () => NOT_DRAWN_HERE,
   NO_AGENT_PORT: () => NO_AGENT_PORT,
   NO_CHAT_REASON: () => NO_CHAT_REASON,
   NO_COLUMNS_WHY: () => NO_COLUMNS_WHY,
@@ -162,6 +163,8 @@ __export(src_exports, {
   chooseSurface: () => chooseSurface,
   colorFromTheValue: () => colorFromTheValue,
   columnForField: () => columnForField,
+  conditionInWords: () => conditionInWords,
+  conditionIsSimple: () => conditionIsSimple,
   conditionValue: () => conditionValue,
   controlFor: () => controlFor,
   currencyCodeFor: () => currencyCodeFor,
@@ -2728,7 +2731,7 @@ function EnrichPanel({ tableId, fieldId, className }) {
 var import_react17 = require("react");
 var import_design_system8 = require("@ai-matrx/design-system");
 var import_jsx_runtime11 = require("react/jsx-runtime");
-function PastePreview({ plan, noun, onConfirm, onCancel }) {
+function PastePreview({ plan, noun, nounPlural, onConfirm, onCancel }) {
   const [busy, setBusy] = (0, import_react17.useState)(false);
   const [outcome, setOutcome] = (0, import_react17.useState)(null);
   const nothingToDo = plan.cells === 0;
@@ -2748,7 +2751,7 @@ function PastePreview({ plan, noun, onConfirm, onCancel }) {
         /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(import_design_system8.Separator, {}),
         outcome === null ? /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)(import_jsx_runtime11.Fragment, { children: [
           nothingToDo ? /* @__PURE__ */ (0, import_jsx_runtime11.jsx)("p", { className: "text-sm", children: "Nothing in what you pasted can be written to this table. Every cell is listed below with the reason." }) : /* @__PURE__ */ (0, import_jsx_runtime11.jsxs)("p", { className: "text-sm", children: [
-            sentence(plan, noun),
+            sentence(plan, noun, nounPlural),
             " The values below are exactly what will be stored."
           ] }),
           /* @__PURE__ */ (0, import_jsx_runtime11.jsx)(PlanTable, { plan }),
@@ -2788,7 +2791,7 @@ function PastePreview({ plan, noun, onConfirm, onCancel }) {
                   setBusy(true);
                   void onConfirm().then(setOutcome).finally(() => setBusy(false));
                 },
-                children: busy ? "Writing\u2026" : confirmLabel(plan, noun)
+                children: busy ? "Writing\u2026" : confirmLabel(plan, noun, nounPlural)
               }
             )
           ] })
@@ -2843,19 +2846,19 @@ function plural(n, one, many) {
 function summarize(plan) {
   return `${plural(plan.cells, "value", "values")} across ${plural(plan.rows.length, "row", "rows")}`;
 }
-function sentence(plan, noun) {
+function sentence(plan, noun, nounPlural) {
   const parts = [];
-  if (plan.updates > 0) parts.push(`change ${plural(plan.updates, noun, `${noun}s`)}`);
-  if (plan.creates > 0) parts.push(`create ${plural(plan.creates, `new ${noun}`, `new ${noun}s`)}`);
+  if (plan.updates > 0) parts.push(`change ${plural(plan.updates, noun, nounPlural)}`);
+  if (plan.creates > 0) parts.push(`create ${plural(plan.creates, `new ${noun}`, `new ${nounPlural}`)}`);
   const what = parts.length === 2 ? `${parts[0]} and ${parts[1]}` : parts[0] ?? "write nothing";
   return `This will ${what}.`;
 }
-function confirmLabel(plan, noun) {
+function confirmLabel(plan, noun, nounPlural) {
   if (plan.creates > 0 && plan.updates === 0) {
-    return `Create ${plural(plan.creates, noun, `${noun}s`)}`;
+    return `Create ${plural(plan.creates, noun, nounPlural)}`;
   }
   if (plan.creates > 0) return `Write ${plural(plan.rows.length, "row", "rows")}`;
-  return `Update ${plural(plan.updates, noun, `${noun}s`)}`;
+  return `Update ${plural(plan.updates, noun, nounPlural)}`;
 }
 
 // src/pasteValues.ts
@@ -2890,13 +2893,21 @@ function valueFromPastedText(field, raw) {
       return { value: negative ? -n : n };
     }
     case "datetime": {
+      const wantsTime = String(field.config?.["kind"] ?? "date") === "datetime";
+      const plainDay = /^\s*(\d{4})-(\d{2})-(\d{2})\s*$/.exec(raw);
+      if (!wantsTime && plainDay) return { value: `${plainDay[1]}-${plainDay[2]}-${plainDay[3]}` };
       const at = Date.parse(text);
       if (Number.isNaN(at)) {
         return {
           refusal: `${label} holds a date, and \u201C${raw}\u201D is not one this can read. Paste it as 2026-09-21, or as your spreadsheet's own date format.`
         };
       }
-      return { value: new Date(at).toISOString() };
+      const parsed = new Date(at);
+      if (wantsTime) return { value: parsed.toISOString() };
+      const y = parsed.getFullYear();
+      const m = String(parsed.getMonth() + 1).padStart(2, "0");
+      const d = String(parsed.getDate()).padStart(2, "0");
+      return { value: `${y}-${m}-${d}` };
     }
     case "json": {
       try {
@@ -3087,42 +3098,55 @@ function Grid({
       const fieldList = fields.data ?? [];
       const byRecord = /* @__PURE__ */ new Map();
       const order = [];
-      for (const patch of sheetPlan.accepted) {
-        let held = byRecord.get(patch.rowId);
+      const take = (rowId, columnId, value) => {
+        let held = byRecord.get(rowId);
         if (held === void 0) {
           held = {};
-          byRecord.set(patch.rowId, held);
-          order.push(patch.rowId);
+          byRecord.set(rowId, held);
+          order.push(rowId);
         }
-        held[patch.columnId] = patch.value === null ? "" : String(patch.value);
+        held[columnId] = value === null || value === void 0 ? "" : String(value);
+      };
+      for (const patch of sheetPlan.accepted) take(patch.rowId, patch.columnId, patch.value);
+      for (const refused of sheetPlan.refusals) {
+        if (refused.rowId === null) continue;
+        take(refused.rowId, refused.columnId, refused.value);
       }
+      const onScreen = rows.map((r) => r.id).filter((id) => byRecord.has(id));
+      const touched = [...onScreen, ...order.filter((id) => !onScreen.includes(id))];
       const columnKeys = Array.from(
         /* @__PURE__ */ new Set([
           ...sheetPlan.accepted.map((p) => p.columnId),
+          ...sheetPlan.refusals.map((r) => r.columnId),
           ...sheetPlan.overflow.flatMap((row) => Object.keys(row))
         ])
       );
       const built = planPastedBlock({
         fields: fieldList,
         columnKeys,
-        onExisting: order.map((recordId) => ({
+        onExisting: touched.map((recordId) => ({
           recordId,
           raw: columnKeys.map((key) => byRecord.get(recordId)?.[key])
         })),
         onNew: sheetPlan.overflow.map((row) => columnKeys.map((key) => row[key])),
         pastRightEdge: sheetPlan.pastRightEdge
       });
+      const notWritable = /* @__PURE__ */ new Map();
       for (const refused of sheetPlan.refusals) {
+        if (built.refusals.some((r) => r.column === columnLabel(fieldList, refused.columnId))) continue;
+        notWritable.set(refused.columnId, refused.reason);
+      }
+      for (const [columnId, why] of notWritable) {
         built.refusals.push({
           fromLine: 0,
-          column: refused.columnId,
+          column: columnLabel(fieldList, columnId),
           raw: "",
-          why: refused.reason
+          why
         });
       }
       setPastePlan({ plan: built });
     },
-    [fields.data]
+    [fields.data, rows]
   );
   const applyPaste = (0, import_react18.useCallback)(async () => {
     const held = pastePlan;
@@ -3433,6 +3457,7 @@ function Grid({
         {
           plan: pastePlan.plan,
           noun: table.data?.label_singular ?? "record",
+          nounPlural: table.data?.label_plural ?? `${table.data?.label_singular ?? "record"}s`,
           onConfirm: applyPaste,
           onCancel: () => setPastePlan(null)
         }
@@ -3450,6 +3475,10 @@ function Grid({
     ] })
   ] }) });
 }
+function columnLabel(fields, columnId) {
+  const field = fields.find((f) => f.key === columnId);
+  return field ? fieldName(field) : humanize(columnId);
+}
 function AddFieldButton({ onClick }) {
   return /* @__PURE__ */ (0, import_jsx_runtime12.jsx)(
     import_design_system9.Button,
@@ -4788,6 +4817,60 @@ var CONDITION_OPS = [
   { op: "gt", label: "is more than" },
   { op: "lt", label: "is less than" }
 ];
+function conditionIsSimple(expr) {
+  if (expr === null || expr === void 0) return true;
+  const node = expr;
+  if (typeof node.op !== "string" || !CONDITION_OPS.some((c) => c.op === node.op)) return false;
+  if (!Array.isArray(node.args)) return false;
+  const first = node.args[0];
+  if (!first || typeof first.field !== "string") return false;
+  if (node.op === "present") return node.args.length === 1;
+  const second = node.args[1];
+  return node.args.length === 2 && !!second && "const" in second;
+}
+function conditionInWords(expr, fields) {
+  const name = (id) => {
+    const f = fields.find((x) => x.id === id);
+    return f ? f.label || f.key : "a column";
+  };
+  const said = {
+    eq: "is",
+    ne: "is not",
+    gt: "is more than",
+    lt: "is less than",
+    gte: "is at least",
+    lte: "is at most",
+    and: "and",
+    or: "or",
+    matches: "matches"
+  };
+  const walk = (node) => {
+    if (node === null || node === void 0) return "nothing";
+    const n = node;
+    if ("const" in n) return JSON.stringify(n["const"]);
+    if (typeof n["field"] === "string" && !("op" in n)) return name(n["field"]);
+    const op = typeof n["op"] === "string" ? n["op"] : "";
+    if (op === "previous" && typeof n["field"] === "string") return `what ${name(n["field"])} used to say`;
+    if (op === "sibling_count") {
+      const same = n["same"] ?? [];
+      const differs = n["differs"] ?? [];
+      const sameWords = same.length > 0 ? ` for the same ${same.map(name).join(" and ")}` : "";
+      const diffWords = differs.length > 0 ? ` from a different ${differs.map(name).join(" and ")}` : "";
+      return `how many others there are${sameWords}${diffWords}`;
+    }
+    if (op === "stage_count") return "how many are in that column already";
+    if (op === "actor_at_least") return `whoever is moving it is at least ${String(n["level"] ?? "somebody")}`;
+    const args = Array.isArray(n["args"]) ? n["args"] : [];
+    if (op === "not") return `not ${walk(args[0])}`;
+    if (op === "present") return `${walk(args[0])} has been answered`;
+    const word = said[op] ?? op;
+    if (op === "and" || op === "or") return args.map(walk).join(` ${word} `);
+    if (args.length === 2) return `${walk(args[0])} ${word} ${walk(args[1])}`;
+    if (args.length === 1) return `${walk(args[0])} ${word}`;
+    return op;
+  };
+  return walk(expr);
+}
 function conditionValue(typed) {
   const trimmed = typed.trim();
   if (trimmed === "") return typed;
@@ -4859,6 +4942,7 @@ function ConditionRow({ lead, expr, fields, onChange, emptyLabel = "always", cla
 var import_jsx_runtime18 = require("react/jsx-runtime");
 var NO_RULES_YET = "Nothing has to be true to get here yet.";
 var NEEDS_A_SENTENCE = "Write the sentence somebody reads when this stops them, the way you would say it out loud.";
+var NOT_DRAWN_HERE = "This part of the rule is not something this builder can draw yet";
 var ON_FAIL = [
   { value: "refuse", label: "Turn it away", note: "The card stays where it is and the person is told why." },
   {
@@ -5039,7 +5123,7 @@ function StageRulesSection({ tableId, stage, className }) {
         }
       ),
       /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(
-        ConditionRow,
+        Clause,
         {
           lead: "When",
           emptyLabel: "every card",
@@ -5049,7 +5133,7 @@ function StageRulesSection({ tableId, stage, className }) {
         }
       ),
       /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(
-        ConditionRow,
+        Clause,
         {
           lead: "it cannot get here unless",
           emptyLabel: "\u2014 pick a column \u2014",
@@ -5093,6 +5177,50 @@ function StageRulesSection({ tableId, stage, className }) {
     /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(import_design_system15.Separator, {})
   ] });
 }
+function Clause({
+  lead,
+  emptyLabel,
+  expr,
+  fields,
+  onChange
+}) {
+  const [replacing, setReplacing] = (0, import_react29.useState)(false);
+  const drawable = conditionIsSimple(expr) || replacing;
+  if (drawable) {
+    return /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(
+      ConditionRow,
+      {
+        lead,
+        emptyLabel,
+        expr: replacing && !conditionIsSimple(expr) ? null : expr,
+        fields,
+        onChange
+      }
+    );
+  }
+  return /* @__PURE__ */ (0, import_jsx_runtime18.jsxs)("div", { className: "flex flex-wrap items-center gap-1 text-xs", "data-testid": "stage-rule-clause-in-words", children: [
+    /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("span", { className: "text-muted-foreground", children: lead }),
+    /* @__PURE__ */ (0, import_jsx_runtime18.jsx)("span", { className: "font-medium", children: conditionInWords(expr, fields) }),
+    /* @__PURE__ */ (0, import_jsx_runtime18.jsxs)("span", { className: "text-muted-foreground", children: [
+      "\u2014 ",
+      NOT_DRAWN_HERE,
+      ", so it is shown as it reads."
+    ] }),
+    /* @__PURE__ */ (0, import_jsx_runtime18.jsx)(
+      import_design_system15.Button,
+      {
+        size: "sm",
+        variant: "ghost",
+        className: "h-6",
+        onClick: () => {
+          setReplacing(true);
+          onChange(null);
+        },
+        children: "Replace it"
+      }
+    )
+  ] });
+}
 
 // src/TableSettings.tsx
 var import_react31 = require("react");
@@ -6404,6 +6532,7 @@ function Card({
 
 // src/ViewSwitcher.tsx
 var import_jsx_runtime25 = require("react/jsx-runtime");
+var NO_FIELDS = [];
 function useViewRecords(view, pageSize = 200) {
   const client = (0, import_react46.useRecordsClient)();
   const table = (0, import_react46.useRecords)(view.ruleId ? null : view.subject, { pageSize });
@@ -6773,7 +6902,12 @@ function Card2({
   onOpenRecord
 }) {
   const host = useRecordsUi();
-  const label = field ? scalarText(field, (record.document ?? {})[field.key]) : rowName(record, null, "Untitled");
+  const wanted = (0, import_react45.useMemo)(
+    () => field && pointsAtRecords(field) ? [field] : NO_FIELDS,
+    [field]
+  );
+  const labels = useRecordLabels(wanted);
+  const label = field ? scalarText(field, (record.document ?? {})[field.key], labels) : rowName(record, null, "Untitled");
   return /* @__PURE__ */ (0, import_jsx_runtime25.jsx)(
     "button",
     {