@ai-matrx/records-ui 0.60.0 → 0.61.0

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog — @ai-matrx/records-ui
 
+## 0.61.0
+
+**A link to a board opens a board, and a cell that is still resolving says what
+it is waiting for.** (lane FRONT-DOOR; VERIFIER-8 HIGH-2 and MEDIUM-1.)
+
+* **`?view=` was read by nobody.**
+  `/data-v2/<table>?view=kanban` returned 200 and rendered the grid — 40 rows,
+  grid headers — and nothing on the screen said the view had been dropped. So a
+  bookmarked board was a grid and the link an office manager sent every morning
+  had never once opened the board. `TablePage` takes `activeView` (the raw
+  `?view=` string) and `onViewChanged`, and the five views — grid, kanban,
+  calendar, gallery, dashboards — all deep-link. The ADDRESS OUTRANKS the saved
+  view's layout until the person picks another, and then it FOLLOWS them: half a
+  deep link is a link that works when you arrive and lies when you copy it out of
+  the bar afterwards. `pageViewFromParam` also takes the words people actually
+  type (`board`, `cards`, `table`, `dashboard`), and a `?view=` this build has no
+  view for is SAID (`unknownViewLine`) rather than silently turned into a grid.
+  New: `PAGE_VIEWS`, `PAGE_VIEW_LABEL`, `pageViewFromParam`, `unknownViewLine`,
+  `openingView`, type `PageView`.
+* **The relation resolver's per-cell fetch is batched, and it was latent.**
+  Measured on the real Rincon Plumbing Jobs grid on 2026-09-21: rows at 2,184 ms,
+  the CUSTOMER column resolved at 3,017 ms to real names, about 100 ms of
+  "Loading…" and ZERO `record_read` calls — so the 10-13 second column VERIFIER-8
+  recorded on 0.57 is already gone. What was still there was the shape behind it:
+  the chase for an id the bulk read did not cover fired per cell and committed its
+  own `setNames`, so forty uncovered cells cost forty round trips AND forty
+  re-renders of the whole grid. Ids now gather and the page asks ONCE A TICK, six
+  lanes at a time, with ONE commit for every name it learned.
+* **A cell still resolving after one second says what it went to read.**
+  "Loading…" is honest for a moment and a lie with a spinner on it after that.
+  New: `useLabelWait`, `SAY_WHAT_YOU_ARE_WAITING_FOR_AFTER_MS`; `scalarText` and
+  `renderValue` take the sentence as a last argument (optional — every existing
+  call site is unchanged).
+
+**Consumer action:** a host route that serves a table page should read `?view=`
+and pass `activeView` + `onViewChanged` to `TablePage`, or its view links stay
+dead. `matrx-frontend`'s `/data-v2/[tableId]` does this as of the same session.
+
 ## 0.59.0
 
 **Three things the browser walks found by using the builders on real businesses.**

package/dist/index.cjs

@@ -110,6 +110,8 @@ __export(src_exports, {
   NO_SHARE_REASON: () => NO_SHARE_REASON,
   NO_UPLOAD_REASON: () => NO_UPLOAD_REASON,
   NotifyRuleEditor: () => NotifyRuleEditor,
+  PAGE_VIEWS: () => PAGE_VIEWS,
+  PAGE_VIEW_LABEL: () => PAGE_VIEW_LABEL,
   PARITY_LABEL: () => PARITY_LABEL,
   PARITY_MADE_OF: () => PARITY_MADE_OF,
   Peek: () => Peek,
@@ -133,6 +135,7 @@ __export(src_exports, {
   RefusalNotice: () => RefusalNotice,
   RelationPicker: () => RelationPicker,
   SAVED_VIEWS_UNAVAILABLE: () => SAVED_VIEWS_UNAVAILABLE,
+  SAY_WHAT_YOU_ARE_WAITING_FOR_AFTER_MS: () => SAY_WHAT_YOU_ARE_WAITING_FOR_AFTER_MS,
   SERIES_COLORS: () => SERIES_COLORS,
   SOMEBODY: () => SOMEBODY,
   STORE_ANSWERS_THESE: () => STORE_ANSWERS_THESE,
@@ -203,6 +206,9 @@ __export(src_exports, {
   machineIdentityIn: () => machineIdentityIn,
   memberName: () => memberName,
   nextInWords: () => nextInWords,
+  openingRail: () => openingRail,
+  openingView: () => openingView,
+  pageViewFromParam: () => pageViewFromParam,
   parityTypesWithNoExplanation: () => parityTypesWithNoExplanation,
   parseGridPresentation: () => parseGridPresentation,
   personActor: () => personActor,
@@ -228,10 +234,12 @@ __export(src_exports, {
   tableName: () => tableName,
   tableRightsAt: () => tableRightsAt,
   tokenFor: () => tokenFor,
+  unknownViewLine: () => unknownViewLine,
   useCanShare: () => useCanShare,
   useEmbedHandshake: () => useEmbedHandshake,
   useEnrichCells: () => useEnrichCells,
   useGridEditing: () => useGridEditing,
+  useLabelWait: () => useLabelWait,
   useMeasuredWidth: () => useMeasuredWidth,
   useMyChecklistSteps: () => useMyChecklistSteps,
   useRecordLabels: () => useRecordLabels,
@@ -1399,8 +1407,13 @@ var LabelContext = (0, import_react11.createContext)({
   // provides one, so this is only ever a bare unit test.
   lookup: () => null,
   want: () => {
-  }
+  },
+  waiting: () => null
 });
+var SAY_WHAT_YOU_ARE_WAITING_FOR_AFTER_MS = 1e3;
+function waitingLineFor(field, target) {
+  return field.type === "list" ? "Reading this column\u2019s list of choices\u2026" : `Reading the ${target ?? "records"} this column points at\u2026`;
+}
 function idsOf(value) {
   if (Array.isArray(value)) return value.map(String).filter(isId);
   if (typeof value === "string" && isId(value)) return [value];
@@ -1417,13 +1430,48 @@ function RecordLabelProvider({ children }) {
   const client = (0, import_react12.useRecordsClient)();
   const [names, setNames] = (0, import_react11.useState)({});
   const [settled, setSettled] = (0, import_react11.useState)({});
+  const [waitingLines, setWaitingLines] = (0, import_react11.useState)({});
   const asked = (0, import_react11.useRef)(/* @__PURE__ */ new Set());
   const chased = (0, import_react11.useRef)(/* @__PURE__ */ new Set());
+  const timers = (0, import_react11.useRef)(/* @__PURE__ */ new Map());
+  const startWaitClock = (0, import_react11.useCallback)((field, target) => {
+    if (timers.current.has(field.id)) return;
+    timers.current.set(
+      field.id,
+      setTimeout(() => {
+        timers.current.delete(field.id);
+        setWaitingLines(
+          (current) => current[field.id] ? current : { ...current, [field.id]: waitingLineFor(field, target) }
+        );
+      }, SAY_WHAT_YOU_ARE_WAITING_FOR_AFTER_MS)
+    );
+  }, []);
+  const stopWaitClock = (0, import_react11.useCallback)((fieldId) => {
+    const timer = timers.current.get(fieldId);
+    if (timer) {
+      clearTimeout(timer);
+      timers.current.delete(fieldId);
+    }
+    setWaitingLines((current) => {
+      if (!current[fieldId]) return current;
+      const next = { ...current };
+      delete next[fieldId];
+      return next;
+    });
+  }, []);
+  (0, import_react11.useEffect)(
+    () => () => {
+      for (const timer of timers.current.values()) clearTimeout(timer);
+      timers.current.clear();
+    },
+    []
+  );
   const want = (0, import_react11.useCallback)(
     (field) => {
       if (!pointsAtRecords(field)) return;
       if (asked.current.has(field.id)) return;
       asked.current.add(field.id);
+      startWaitClock(field, null);
       void (async () => {
         if (field.type === "list") {
           const result = await client.fieldOptions({ field_id: field.id });
@@ -1437,11 +1485,13 @@ function RecordLabelProvider({ children }) {
             });
           }
           setSettled((current) => ({ ...current, [field.id]: true }));
+          stopWaitClock(field.id);
           return;
         }
         const target = field.relation_target;
         if (!target) {
           setSettled((current) => ({ ...current, [field.id]: true }));
+          stopWaitClock(field.id);
           return;
         }
         const [rows, tables] = await Promise.all([
@@ -1459,24 +1509,54 @@ function RecordLabelProvider({ children }) {
           });
         }
         setSettled((current) => ({ ...current, [field.id]: true }));
+        stopWaitClock(field.id);
       })();
     },
-    [client]
+    [client, startWaitClock, stopWaitClock]
   );
+  const queued = (0, import_react11.useRef)(/* @__PURE__ */ new Map());
+  const flushing = (0, import_react11.useRef)(null);
+  const flush = (0, import_react11.useCallback)(() => {
+    flushing.current = null;
+    const batch = [...queued.current.entries()];
+    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;
+          }
+        })
+      );
+      setNames((current) => ({ ...current, ...learned }));
+      for (const [, field] of batch) stopWaitClock(field.id);
+    })();
+  }, [client, stopWaitClock]);
   const chase = (0, import_react11.useCallback)(
     (field, id) => {
       const key = `${field.id}:${id}`;
       if (chased.current.has(key)) return;
       chased.current.add(key);
-      void (async () => {
-        const result = await client.recordRead({ record_id: id });
-        setNames((current) => ({
-          ...current,
-          [id]: result.ok ? recordName(result.data.document, null, "Untitled") : WITHHELD_RECORD_LABEL
-        }));
-      })();
+      queued.current.set(id, field);
+      startWaitClock(field, null);
+      if (flushing.current === null) flushing.current = setTimeout(flush, 0);
     },
-    [client]
+    [flush, startWaitClock]
+  );
+  (0, import_react11.useEffect)(
+    () => () => {
+      if (flushing.current !== null) clearTimeout(flushing.current);
+    },
+    []
   );
   const lookup = (0, import_react11.useCallback)(
     (field, id) => {
@@ -1487,7 +1567,8 @@ function RecordLabelProvider({ children }) {
     },
     [names, settled, chase]
   );
-  const value = (0, import_react11.useMemo)(() => ({ lookup, want }), [lookup, want]);
+  const waiting = (0, import_react11.useCallback)((field) => waitingLines[field.id] ?? null, [waitingLines]);
+  const value = (0, import_react11.useMemo)(() => ({ lookup, want, waiting }), [lookup, want, waiting]);
   return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(LabelContext.Provider, { value, children });
 }
 function useRecordLabels(fields) {
@@ -1497,6 +1578,10 @@ function useRecordLabels(fields) {
   }, [fields, want]);
   return lookup;
 }
+function useLabelWait(field) {
+  const { waiting } = (0, import_react11.useContext)(LabelContext);
+  return field ? waiting(field) : null;
+}
 
 // src/values.tsx
 var import_jsx_runtime8 = require("react/jsx-runtime");
@@ -1510,7 +1595,7 @@ var ABSENCE_WORDS = {
   refused: "refused",
   conflicting: "conflicting"
 };
-function renderValue(field, value, document2, labels) {
+function renderValue(field, value, document2, labels, stillWaitingFor) {
   const envelope = envelopeFor(document2, field.key);
   if (envelope?.absent) {
     return /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("span", { className: "text-xs italic text-muted-foreground", title: `VAL-2: ${envelope.absent}`, children: ABSENCE_WORDS[String(envelope.absent)] ?? String(envelope.absent) });
@@ -1531,13 +1616,13 @@ function renderValue(field, value, document2, labels) {
   if (typeof value === "boolean") {
     return /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("span", { className: kind === "checkbox" ? "text-sm" : "", title: value ? "Yes" : "No", children: value ? "\u2713" : "\u2014" });
   }
-  return /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("span", { className: (0, import_design_system5.cn)("truncate", kind === "number" || kind === "currency" || kind === "percent" ? "tabular-nums" : ""), children: scalarText(field, value, labels) });
+  return /* @__PURE__ */ (0, import_jsx_runtime8.jsx)("span", { className: (0, import_design_system5.cn)("truncate", kind === "number" || kind === "currency" || kind === "percent" ? "tabular-nums" : ""), children: scalarText(field, value, labels, stillWaitingFor) });
 }
-function scalarText(field, value, labels) {
+function scalarText(field, value, labels, stillWaitingFor) {
   if (value === null || value === void 0) return "\u2014";
   const kind = editorKindFor(field);
   if (isId(value) && (field.type === "list" || field.type === "relation")) {
-    return labels?.(field, String(value)) ?? "Loading\u2026";
+    return labels?.(field, String(value)) ?? stillWaitingFor ?? "Loading\u2026";
   }
   if (typeof value === "number") {
     if (kind === "percent") return `${value}%`;
@@ -1569,9 +1654,10 @@ function RecordValue({
   format
 }) {
   const labels = useRecordLabels(ONE_FIELD_ARRAY_CACHE(field));
+  const stillWaitingFor = useLabelWait(field);
   const formatted = format ? (0, import_data_table.formatColumnValue)({ format }, value) : null;
   if (formatted) return /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(import_data_table.FormattedCell, { result: formatted });
-  return /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(import_jsx_runtime8.Fragment, { children: renderValue(field, value, document2, labels) });
+  return /* @__PURE__ */ (0, import_jsx_runtime8.jsx)(import_jsx_runtime8.Fragment, { children: renderValue(field, value, document2, labels, stillWaitingFor) });
 }
 var ONE_FIELD_ARRAYS = /* @__PURE__ */ new WeakMap();
 function ONE_FIELD_ARRAY_CACHE(field) {
@@ -6380,6 +6466,37 @@ var LAYOUT_FIELD_KIND = {
   calendar: "date",
   gallery: null
 };
+var PAGE_VIEWS = [...VIEW_LAYOUTS, "dashboards"];
+var PAGE_VIEW_LABEL = {
+  ...LAYOUT_LABEL,
+  dashboards: "Dashboards"
+};
+var PAGE_VIEW_SPELLINGS = {
+  grid: "grid",
+  table: "grid",
+  rows: "grid",
+  list: "grid",
+  kanban: "kanban",
+  board: "kanban",
+  pipeline: "kanban",
+  calendar: "calendar",
+  month: "calendar",
+  schedule: "calendar",
+  gallery: "gallery",
+  cards: "gallery",
+  dashboards: "dashboards",
+  dashboard: "dashboards",
+  charts: "dashboards"
+};
+function pageViewFromParam(raw) {
+  if (typeof raw !== "string") return null;
+  const token = raw.trim().toLowerCase();
+  if (token === "") return null;
+  return PAGE_VIEW_SPELLINGS[token] ?? null;
+}
+function unknownViewLine(raw) {
+  return `The link asked for a view called \u201C${raw}\u201D, which this table has no view for, so you are looking at ${PAGE_VIEW_LABEL.grid}. The views this table has are ${PAGE_VIEWS.map((v) => PAGE_VIEW_LABEL[v]).join(", ")} \u2014 pick one above and the address follows it.`;
+}
 var LAYOUT_NO_FIELD = {
   grid: "",
   kanban: "This table has no choice field yet, so there is nothing to make columns from. Add a field that holds one of a set of choices \u2014 Add field, then Select \u2014 and it appears here.",
@@ -14517,6 +14634,19 @@ function surfaceChosen(current, asking) {
 function openingRail(activeRecordId) {
   return activeRecordId ? { rail: "record", record: activeRecordId } : { rail: "none", record: null };
 }
+function openingView(activeView, activeDashboardId) {
+  const named = pageViewFromParam(activeView);
+  if (named === null) {
+    const asked = typeof activeView === "string" ? activeView.trim() : "";
+    return {
+      main: activeDashboardId ? "dashboards" : "records",
+      layout: null,
+      unknown: asked === "" ? null : asked
+    };
+  }
+  if (named === "dashboards") return { main: "dashboards", layout: null, unknown: null };
+  return { main: "records", layout: named, unknown: null };
+}
 function TablePage({
   tableId,
   pageSize = 100,
@@ -14525,6 +14655,8 @@ function TablePage({
   leaveLabel = "Back to your tables",
   activeDashboardId,
   activeRecordId,
+  activeView,
+  onViewChanged,
   className
 }) {
   const client = (0, import_react110.useRecordsClient)();
@@ -14533,22 +14665,37 @@ function TablePage({
   const organizationId = (0, import_react110.useRecordsClient)().config.organizationId;
   const [view, setView] = (0, import_react109.useState)(null);
   const opening = openingRail(activeRecordId);
+  const opened = openingView(activeView, activeDashboardId);
   const [asking, setAsking] = (0, import_react109.useState)(null);
+  const [layoutFromLink, setLayoutFromLink] = (0, import_react109.useState)(opened.layout);
   const [surface, setSurface] = (0, import_react109.useState)({
-    main: activeDashboardId ? "dashboards" : "records",
+    main: opened.main,
     rail: opening.rail
   });
   const { main, rail } = surface;
   const setRail = (next) => setSurface((now) => ({ ...now, rail: next }));
   const [openRecord, setOpenRecord] = (0, import_react109.useState)(opening.record);
   const viewVersion = useRecordVersion(view?.id ?? null);
-  const press = (pressed) => setSurface((now) => chooseSurface(now, pressed));
+  const shownLayout = layoutFromLink ?? view?.layout ?? "grid";
+  const press = (pressed) => {
+    const next = chooseSurface(surface, pressed);
+    setSurface(next);
+    if (next.main !== surface.main) {
+      onViewChanged?.(next.main === "dashboards" ? "dashboards" : shownLayout);
+    }
+  };
   const show = (next) => press({ rail: next });
   (0, import_react109.useEffect)(() => {
     if (!activeRecordId) return;
     setOpenRecord(activeRecordId);
     setSurface((now) => ({ ...now, rail: "record" }));
   }, [activeRecordId]);
+  (0, import_react109.useEffect)(() => {
+    const named = pageViewFromParam(activeView);
+    if (named === null) return;
+    setLayoutFromLink(named === "dashboards" ? null : named);
+    setSurface((now) => ({ ...now, main: named === "dashboards" ? "dashboards" : "records" }));
+  }, [activeView]);
   const patchView = (0, import_react109.useCallback)(
     async (patch) => {
       const current = view;
@@ -14702,11 +14849,16 @@ function TablePage({
         /* @__PURE__ */ (0, import_jsx_runtime57.jsx)(ExportMenu, { tableId })
       ] }),
       main === "dashboards" ? /* @__PURE__ */ (0, import_jsx_runtime57.jsx)(DashboardCanvas, { tableId, activeDashboardId: activeDashboardId ?? null }) : /* @__PURE__ */ (0, import_jsx_runtime57.jsxs)(import_jsx_runtime57.Fragment, { children: [
+        opened.unknown ? /* @__PURE__ */ (0, import_jsx_runtime57.jsx)("p", { className: "rounded-md border border-amber-600/40 bg-amber-500/5 px-3 py-2 text-xs leading-relaxed text-amber-700 dark:border-amber-400/40 dark:text-amber-300", children: unknownViewLine(opened.unknown) }) : null,
         /* @__PURE__ */ (0, import_jsx_runtime57.jsx)(
           ViewSwitcher,
           {
-            view: view ?? defaultView(tableId),
+            view: { ...view ?? defaultView(tableId), layout: shownLayout },
             pageSize,
+            onLayoutChange: (layout) => {
+              setLayoutFromLink(layout);
+              onViewChanged?.(layout);
+            },
             ...view ? { onViewChange: (patch) => void patchView(patch) } : {},
             ...rights.write ? { onNewRecordForm: () => setRail("new-record") } : {},
             onOpenRecord: (recordId) => {