@ai-matrx/records-ui 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # Changelog — @ai-matrx/records-ui
 
+## 0.63.0
+
+**A relation cell finally SHOWS what its column was configured to show, and the
+six hand-rolled copies of "what is this id called" are gone — all six, by moving
+the code, none by allowlisting.** (lane RELATION-DISPLAY-2.)
+
+* **The display spec reached the store in 0.62.0 and no screen could read it.**
+  REL-DISP gave a relation column a `display` — which of the target's columns it
+  shows, in what order, joined by what — and shipped `ReferenceBuilder` to
+  configure it. But `labels.tsx`, which every grid, board, gallery, calendar and
+  peek cell reads through, resolved names ITSELF: 200 rows of the target Table
+  plus `tableList()` for its `title_field`. So a person could set Rincon
+  Plumbing's `jobs.customer` to read "first name + last name", press Save, and
+  the board would go on drawing "Maria Chen" for both of the Maria Chens. The
+  builder wrote a setting that nothing displayed.
+  `labels.tsx` now fetches NOTHING up front and asks `relation_words_many` for
+  the ids the page actually draws — one call per Field per tick, the store's one
+  resolver, this column's own spec, the visibility ladder asked BEFORE the name
+  is read, and no 200-row prefetch ceiling. Its own comment recorded the batch
+  door as missing ("there is still no batch door on the store"); REL-DISP built
+  it, so the per-id `record_read` lane is gone entirely.
+* **`RelationPicker` offers the same words the cell shows.** It had the third
+  copy of the derivation, which is why a column configured to read "Maria Chen —
+  Rincon" still asked a person to choose between two identical "Maria Chen"s.
+  One `relation_words_many` now covers the offered rows AND the already-picked
+  ids, so what you pick from and what you read back can never disagree.
+* **`recordNameIn` / `rowNameIn` — the one naming call for a record whose Table
+  you already hold.** `Grid` (the Talk action), `Peek` (the peek title),
+  `PortalsPanel`'s client picker and the host test bench were each writing
+  `recordName(row.document, table.title_field)` out by hand. That is not the
+  store's question — there is no id to resolve — but it is the same question
+  answered five times in four files, which is how a Table titled by `cname` read
+  "Untitled" on one screen and correctly on the next. It lives once now.
+  NOT a second resolver: hold an id, and the answer is still the store's.
+* **`check:one-reference-builder` goes from a baseline of SIX to ZERO.** The
+  guard shipped saying out loud that allowlisting the six "would be the same lie
+  with extra steps". None was allowlisted. Proven red on a planted copy at
+  baseline 0, then green.
+
+**Consumer action:** none for a host that only mounts these components — the
+change is behind them. A host resolving a relation label itself should delete
+that code and call `client.relationWordsMany`; one holding a Table and a
+document should call `recordNameIn` / `rowNameIn`.
+
+## 0.62.0
+
+**THE ONE REFERENCE BUILDER.** (lane RELATION-DISPLAY.)
+
+*Written after the fact by lane RELATION-DISPLAY-2 — 0.62.0 published with no
+entry here, and a released version with no changelog row is a version nobody
+downstream can read. Sourced from that lane's own progress note, not invented.*
+
+* **`ReferenceBuilder` + `previewWords`** — the one place a reference to another
+  table is built. It asks, in the order a person thinks of it: which table →
+  what a record of it is called TODAY (its own reference column, SHOWN rather
+  than hidden) → only if they want it, which columns instead, in order, with a
+  separator → a preview on that table's REAL first rows. `FieldEditor`'s private
+  `TableToPointAt` is deleted and this stands in its place.
+* **A relation is asked its questions when EDITING too.** That branch skipped
+  every existing column that was not a choice list, so there was nowhere to say
+  which columns a link should show — the one thing about an existing relation a
+  person most wants to change. The target stays locked there, because the panel
+  sends no `relation_target` in a patch and a picker that changed it would be a
+  control that silently does nothing.
+* **`looksLikeId` and `WITHHELD_RECORD_LABEL` are exported at last** — they were
+  defined and unreachable, so a host could not agree with the package about what
+  a name is.
+
+**Consumer action:** a surface that lets a person choose a column's target table
+mounts `ReferenceBuilder` instead of building its own dropdown.
+
 ## 0.61.0
 
 **A link to a board opens a board, and a cell that is still resolving says what

package/dist/index.cjs

@@ -223,12 +223,14 @@ __export(src_exports, {
   previewWords: () => previewWords,
   publiclyAnswerable: () => publiclyAnswerable,
   recordName: () => recordName,
+  recordNameIn: () => recordNameIn,
   recordsDataSource: () => recordsDataSource,
   refusalForAPerson: () => refusalForAPerson,
   refusalLineForAPerson: () => refusalLineForAPerson,
   renderValue: () => renderValue,
   revokeConsequence: () => revokeConsequence,
   rowName: () => rowName,
+  rowNameIn: () => rowNameIn,
   scalarText: () => scalarText,
   shareUnavailableReason: () => shareUnavailableReason,
   specFromBlock: () => specFromBlock,
@@ -541,6 +543,12 @@ function looksLikeId(value) {
 function rowName(row, titleKey, fallback = "Untitled") {
   return recordName(row?.document, titleKey, fallback);
 }
+function recordNameIn(table, document2, fallback = "Untitled") {
+  return recordName(document2, table?.title_field ?? null, fallback);
+}
+function rowNameIn(table, row, fallback = "Untitled") {
+  return recordName(row?.document, table?.title_field ?? null, fallback);
+}
 var WITHHELD_RECORD_LABEL = "A record you have not been given access to";
 
 // src/ReferenceBuilder.tsx
@@ -886,8 +894,7 @@ var import_jsx_runtime3 = require("react/jsx-runtime");
 function RelationPicker({ field, value, onChange, disabled, id, className }) {
   const client = (0, import_react6.useRecordsClient)();
   const [rows, setRows] = (0, import_react5.useState)(null);
-  const [titleKey, setTitleKey] = (0, import_react5.useState)(null);
-  const [elsewhere, setElsewhere] = (0, import_react5.useState)({});
+  const [words, setWords] = (0, import_react5.useState)({});
   const [refusal, setRefusal] = (0, import_react5.useState)(null);
   const [search, setSearch] = (0, import_react5.useState)("");
   const [open, setOpen] = (0, import_react5.useState)(false);
@@ -904,47 +911,37 @@ function RelationPicker({ field, value, onChange, disabled, id, className }) {
       if (result.ok) setRows(result.data.rows);
       else setRefusal(refusalLineForAPerson(result.error));
     });
-    void client.tableList().then((result) => {
-      if (cancelled || !result.ok) return;
-      setTitleKey(result.data.find((table) => table.id === target)?.title_field ?? null);
-    });
     return () => {
       cancelled = true;
     };
   }, [client, field.relation_target]);
   (0, import_react5.useEffect)(() => {
     if (!rows) return;
-    const known = new Set(rows.map((row) => row.id));
-    const missing = picked.filter((id2) => !known.has(id2) && elsewhere[id2] === void 0);
-    if (missing.length === 0) return;
+    const wanted = [.../* @__PURE__ */ new Set([...rows.map((row) => row.id), ...picked])].filter(
+      (id2) => words[id2] === void 0
+    );
+    if (wanted.length === 0) return;
     let cancelled = false;
-    void Promise.all(
-      missing.map(async (id2) => {
-        const result = await client.recordRead({ record_id: id2 });
-        return [id2, result.ok ? rowName({ document: result.data.document }, titleKey) : WITHHELD_RECORD_LABEL];
-      })
-    ).then((pairs) => {
+    void client.relationWordsMany({ field_id: field.id, record_ids: wanted }).then((result) => {
       if (cancelled) return;
-      setElsewhere((current) => ({ ...current, ...Object.fromEntries(pairs) }));
+      const learned = {};
+      for (const id2 of wanted) {
+        const said = result.ok ? result.data[id2] : void 0;
+        learned[id2] = typeof said === "string" && said !== "" ? said : WITHHELD_RECORD_LABEL;
+      }
+      setWords((current) => ({ ...current, ...learned }));
     });
     return () => {
       cancelled = true;
     };
-  }, [client, rows, picked, elsewhere, titleKey]);
+  }, [client, field.id, rows, picked, words]);
   if (!field.relation_target) {
     return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("p", { className: "text-xs text-muted-foreground", children: [
       fieldName(field),
       " points at records, but it does not say which Table yet, so there is nothing to pick from. A table admin sets its target in the field editor."
     ] });
   }
-  const byId = new Map((rows ?? []).map((row) => [row.id, row]));
-  const titleOf = (recordId) => {
-    const row = byId.get(recordId);
-    if (row) return rowName(row, titleKey, "Untitled");
-    const away = elsewhere[recordId];
-    if (away !== void 0) return away;
-    return "Loading\u2026";
-  };
+  const titleOf = (recordId) => words[recordId] ?? "Loading\u2026";
   const full = field.multi && field.relation_max !== null && picked.length >= field.relation_max;
   const toggle = (recordId) => {
     if (!field.multi) {
@@ -1688,28 +1685,12 @@ function RecordLabelProvider({ children }) {
           stopWaitClock(field.id);
           return;
         }
-        const target = field.relation_target;
-        if (!target) {
+        if (!field.relation_target) {
           setSettled((current) => ({ ...current, [field.id]: true }));
           stopWaitClock(field.id);
           return;
         }
-        const [rows, tables] = await Promise.all([
-          client.list({ table_id: target, limit: 200 }),
-          client.tableList()
-        ]);
-        const titleKey = tables.ok ? tables.data.find((table) => table.id === target)?.title_field ?? null : null;
-        if (rows.ok) {
-          setNames((current) => {
-            const next = { ...current };
-            for (const row of rows.data.rows) {
-              next[row.id] = recordName(row.document, titleKey, "Untitled");
-            }
-            return next;
-          });
-        }
         setSettled((current) => ({ ...current, [field.id]: true }));
-        stopWaitClock(field.id);
       })();
     },
     [client, startWaitClock, stopWaitClock]
@@ -1718,27 +1699,26 @@ function RecordLabelProvider({ children }) {
   const flushing = (0, import_react13.useRef)(null);
   const flush = (0, import_react13.useCallback)(() => {
     flushing.current = null;
-    const batch = [...queued.current.entries()];
+    const batch = [...queued.current.values()];
     queued.current.clear();
     if (batch.length === 0) return;
     void (async () => {
       const learned = {};
-      const LANES = 6;
-      let at = 0;
       await Promise.all(
-        Array.from({ length: Math.min(LANES, batch.length) }, async () => {
-          for (; ; ) {
-            const next = batch[at];
-            at += 1;
-            if (!next) return;
-            const [id] = next;
-            const result = await client.recordRead({ record_id: id });
-            learned[id] = result.ok ? recordName(result.data.document, null, "Untitled") : WITHHELD_RECORD_LABEL;
+        batch.map(async ({ field, ids }) => {
+          const wanted = [...ids];
+          const result = await client.relationWordsMany({
+            field_id: field.id,
+            record_ids: wanted
+          });
+          for (const id of wanted) {
+            const words = result.ok ? result.data[id] : void 0;
+            learned[id] = typeof words === "string" && words !== "" ? words : WITHHELD_RECORD_LABEL;
           }
         })
       );
       setNames((current) => ({ ...current, ...learned }));
-      for (const [, field] of batch) stopWaitClock(field.id);
+      for (const { field } of batch) stopWaitClock(field.id);
     })();
   }, [client, stopWaitClock]);
   const chase = (0, import_react13.useCallback)(
@@ -1746,7 +1726,9 @@ function RecordLabelProvider({ children }) {
       const key = `${field.id}:${id}`;
       if (chased.current.has(key)) return;
       chased.current.add(key);
-      queued.current.set(id, field);
+      const pending = queued.current.get(field.id);
+      if (pending) pending.ids.add(id);
+      else queued.current.set(field.id, { field, ids: /* @__PURE__ */ new Set([id]) });
       startWaitClock(field, null);
       if (flushing.current === null) flushing.current = setTimeout(flush, 0);
     },
@@ -3868,9 +3850,11 @@ function Grid({
                   onClick: () => host.talkToRecord?.({
                     tableId,
                     recordId: row.id,
-                    title: recordName(
-                      row.document ?? {},
-                      table.data?.title_field
+                    // ONE NAMING CALL (`names.ts`), not this file's own join
+                    // of a Table's title column to a document.
+                    title: recordNameIn(
+                      table.data,
+                      row.document ?? {}
                     )
                   }),
                   children: "Talk"
@@ -6528,7 +6512,7 @@ function Peek({ tableId, recordId, onClose, className }) {
   if (record.error) return /* @__PURE__ */ (0, import_jsx_runtime24.jsx)(RefusalNotice, { error: record.error, className });
   if (fields.error) return /* @__PURE__ */ (0, import_jsx_runtime24.jsx)(RefusalNotice, { error: fields.error, className });
   const document2 = record.data?.document;
-  const title = document2 ? recordName(document2, table.data?.title_field) : "";
+  const title = document2 ? recordNameIn(table.data, document2) : "";
   const href = host.hrefForRecord && table.data ? host.hrefForRecord({ table: table.data, recordId }) : void 0;
   return /* @__PURE__ */ (0, import_jsx_runtime24.jsxs)("div", { className: (0, import_design_system21.cn)("flex min-w-0 flex-col gap-2 text-xs", className), children: [
     /* @__PURE__ */ (0, import_jsx_runtime24.jsxs)("div", { className: "flex items-center gap-2", children: [
@@ -10198,7 +10182,7 @@ function Preview({
 function Invite({ card, onInvited }) {
   const client = (0, import_react69.useRecordsClient)();
   const [rows, setRows] = (0, import_react68.useState)(null);
-  const [titleKey, setTitleKey] = (0, import_react68.useState)(null);
+  const [clientTable, setClientTable] = (0, import_react68.useState)(null);
   const [search, setSearch] = (0, import_react68.useState)("");
   const [picked, setPicked] = (0, import_react68.useState)(null);
   const [email, setEmail] = (0, import_react68.useState)("");
@@ -10217,17 +10201,17 @@ function Invite({ card, onInvited }) {
     });
     void client.tableList().then((answered) => {
       if (cancelled || !answered.ok) return;
-      setTitleKey(answered.data.find((t) => t.id === card.client_table_id)?.title_field ?? null);
+      setClientTable(answered.data.find((t) => t.id === card.client_table_id) ?? null);
     });
     return () => {
       cancelled = true;
     };
   }, [client, card.client_table_id]);
   const options = (0, import_react68.useMemo)(() => {
-    const all = (rows ?? []).map((row) => ({ id: row.id, name: rowName(row, titleKey) }));
+    const all = (rows ?? []).map((row) => ({ id: row.id, name: rowNameIn(clientTable, row) }));
     const needle = search.trim().toLowerCase();
     return needle === "" ? all.slice(0, 25) : all.filter((o) => o.name.toLowerCase().includes(needle)).slice(0, 25);
-  }, [rows, titleKey, search]);
+  }, [rows, clientTable, search]);
   const send = (0, import_react68.useCallback)(async () => {
     if (!picked) return;
     setBusy(true);