@ai-matrx/records-ui 0.65.0 → 0.66.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog — @ai-matrx/records-ui
 
+## 0.66.0
+
+**A screen stops talking to a developer.** (lane TAILS-6.)
+
+Two sightings on ONE table's rail, watched from the admin seat by the GUIDE lane on 2026-09-21:
+
+> Checklists — "Something went wrong at our end" ·
+> `@ai-matrx/records did not recognise SQLSTATE from checklistTemplates`
+>
+> Dashboards — "… bind `openRecords` on `<RecordsUiProvider>` …"
+
+Both are the same defect in two coats: a sentence written for whoever maintains the code,
+printed to the person who owns the business.
+
+* **`refusalForAPerson` no longer promotes an engineer's hint to the person's remedy.** It
+  prefers the door's own hint over its table, which is right — but it assumed every hint came
+  from the store, and the machine-identity filter only catches a five-character SQLSTATE.
+  New `isEngineerText` / `ENGINEER_TEXT` judge a sentence by SHAPE — a package name, the word
+  SQLSTATE, a `<Component>`, a camelCase identifier, a backticked token, "bind X on …" — and
+  send it to `forEngineers` wherever it came from. `error.diagnostic` from
+  `@ai-matrx/records` 0.47.0 joins the same line.
+* **Titles and remedies for `unreachable`, `needs_approval`, `stale_read` and `timed_out`,**
+  which had none and fell through to "Something went wrong at our end". A call that never
+  reached the store now says so and says nothing was changed.
+* **Every unbound-port sentence rewritten for the person it is shown to** — the nine of them,
+  not the two that were caught: `NO_OPEN_RECORDS_REASON`, `NO_REASK_REASON`,
+  `NO_SAVED_VIEWS_REASON`, `NO_MEMBERS_REASON`, `NO_SHARE_REASON`, `NO_UPLOAD_REASON`,
+  `NO_CHAT_REASON`, `NO_ENRICH_REASON`, `IN_MEMORY_QUEUE_REASON`. Each still says what is
+  missing and now says what to do instead; the instruction for whoever maintains the app moved
+  into the TSDoc above it, where it always belonged.
+* **`TablePage` gains `activeGroupField` and `cameFrom`,** so a host CAN bind `openRecords`.
+  The store has no door that returns the rows behind an aggregate filter, so a click cannot
+  promise a narrowed list — what it can do is open this table's board with its columns set to
+  the field the chart grouped by, and `cameFromLine` says plainly that this is every record
+  grouped that way rather than only the ones the number counted.
+* **Guard:** `src/no-developer-sentences.test.tsx` — shown failing on the pre-fix bytes with
+  the exact sentence the GUIDE lane read, then passing. It needs no server.
+
+**Consumer action:** bind `openRecords` on your `RecordsUiProvider` and pass `activeGroupField`
+/ `cameFrom` through from the address, or leave it unbound and the canvas says so in plain
+English. `matrx-frontend`'s `/data-v2/[tableId]` route is the worked example.
+
 ## 0.65.0
 
 **A condition about a relation column stops asking a person to type a uuid.**
@@ -37,6 +79,16 @@ version somebody else's tag already names.*
 
 ## 0.64.0
 
+> 🚨 **0.64.0 NEVER PUBLISHED, AND EVERYTHING IN IT SHIPPED INSIDE 0.65.0.** Its publish run
+> (35638062219) was **cancelled — not failed** — because `npm/records/*` and `npm/records-ui/*`
+> share ONE concurrency slot that keeps only the newest pending run, and `npm/records-ui/v0.65.0`
+> displaced it. Nothing was lost: 0.65.0 is built from `origin/main`, which contains this
+> commit, and the tarball carries `fieldKindFor`, `coerceTypedAnswer`, `valueFromPastedText`
+> and `enumLabels` — verified by `npm pack`, not by version number. `npm view` goes
+> 0.63.0 → 0.65.0 with no 0.64.0 in between. The entry is kept as written so the work is
+> still findable by what it did. *(Recorded by lane RELATION-DISPLAY-2, whose tag did the
+> displacing.)*
+
 **The paste and the editor stop owning their own opinion of a column, and the capture sheet
 stops minting NaN.**
 

package/dist/index.cjs

@@ -69,6 +69,7 @@ __export(src_exports, {
   DocRender: () => DocRender,
   DocTemplate: () => DocTemplate,
   EMPTY_PRESENTATION: () => EMPTY_PRESENTATION,
+  ENGINEER_TEXT: () => ENGINEER_TEXT,
   EmbedFrame: () => EmbedFrame,
   EnrichBadge: () => EnrichBadge,
   EnrichPanel: () => EnrichPanel,
@@ -192,6 +193,7 @@ __export(src_exports, {
   blockFromSpec: () => blockFromSpec,
   bodyForReading: () => bodyForReading,
   bodyFromKeys: () => bodyFromKeys,
+  cameFromLine: () => cameFromLine,
   cellState: () => cellState,
   chooseSurface: () => chooseSurface,
   colorFromTheValue: () => colorFromTheValue,
@@ -223,6 +225,7 @@ __export(src_exports, {
   hintIsMachineIdentity: () => hintIsMachineIdentity,
   humanize: () => humanize,
   idsOf: () => idsOf,
+  isEngineerText: () => isEngineerText,
   isId: () => isId,
   isMachineIdentity: () => isMachineIdentity,
   isPlainFieldType: () => isPlainFieldType,
@@ -373,12 +376,12 @@ var NO_RIGHTS = tableRights(NOT_ANSWERED_YET);
 function tableRightsAt(level) {
   return tableRights(whatYouMayDo(level, true));
 }
-var NO_SAVED_VIEWS_REASON = "No saved-view port is bound, so there is nothing here to subscribe to. A subscription points at a `platform.saved_view`, which the record store has no door onto \u2014 bind `savedViews` on <RecordsUiProvider> with your host's own list and the picker appears.";
-var NO_MEMBERS_REASON = "No membership port is bound, so this question cannot offer anybody. A person field points at the kernel Person Table, and who is in this organization is the platform's answer rather than the record store's \u2014 bind `members` on <RecordsUiProvider> with your host's own roster and the picker appears.";
-var NO_SHARE_REASON = "No share dialog is bound, so this screen offers no Share button rather than one that opens nothing. Bind `share` on <RecordsUiProvider> with the app's own sharing dialog \u2014 AI Matrx has exactly one (features/sharing), and this package deliberately does not ship a second.";
-var NO_OPEN_RECORDS_REASON = "These numbers do not click through yet. Every one of them is a count of real records, and where this app puts its grid is the host's routing rather than this package's \u2014 bind `openRecords` on <RecordsUiProvider> and a bar, a slice or a row opens the records it counted.";
-var NO_REASK_REASON = "Asking for a change in words needs an agent, and this package deliberately reaches one through the host rather than calling a model itself. Bind `onReask` on <RecordsUiProvider> \u2014 it drives `dashboard_propose` on the server's `records` tool with this dashboard's id \u2014 and this box works.";
-var NO_UPLOAD_REASON = "No file store is bound, so this question cannot take a file. Bind `upload` on <RecordsUiProvider> with your host's file service and the chooser appears.";
+var NO_SAVED_VIEWS_REASON = "There are no saved views here yet, so there is nothing to be told about. Save a view of this table first and it will be offered here.";
+var NO_MEMBERS_REASON = "This app cannot offer the people in your organization on this screen yet, so there is nobody to pick. Type the person's name into a text field for now, and tell us \u2014 it is on our list, not yours.";
+var NO_SHARE_REASON = "Sharing is not available on this screen, so there is no Share button here rather than one that opens nothing. Share this table from the tables list instead.";
+var NO_OPEN_RECORDS_REASON = "These numbers do not click through yet. Every one of them is a count of real records \u2014 open the records view and group it by the same field to see them. It is on our list, not yours.";
+var NO_REASK_REASON = "Changing this dashboard by describing it is not switched on here yet, so this box is off rather than one that goes nowhere. Add and remove the blocks by hand above. It is on our list, not yours.";
+var NO_UPLOAD_REASON = "This screen cannot take a file yet, so there is no chooser here rather than one that loses what you pick. Put a link to the file in a text field for now. It is on our list, not yours.";
 var HostContext = (0, import_react.createContext)(null);
 function RecordsUiProvider({ value, children }) {
   const bound = (0, import_react.useMemo)(() => value, [value]);
@@ -453,6 +456,10 @@ var TITLE = {
   not_supported: "That cannot be done here",
   store_limit: "This has got as big as it can",
   store_not_served: "This organization does not keep its data here",
+  unreachable: "We could not reach your data",
+  needs_approval: "This is waiting on someone's approval",
+  stale_read: "Your view of this is a moment behind",
+  timed_out: "That took too long to answer",
   internal: "Something went wrong at our end"
 };
 var REMEDY = {
@@ -467,8 +474,35 @@ var REMEDY = {
   not_supported: "There is another way to do this \u2014 ask, and we will point you at it.",
   store_limit: "Split it up, or ask us to raise the ceiling for your organization.",
   store_not_served: "An administrator of this organization turns the record store on from the data settings screen.",
+  // 🚨 NOTHING WAS WRITTEN AND NOTHING WAS REFUSED (lane TAILS-6). The call
+  // never arrived, so "try again" is the honest instruction rather than a
+  // consolation — and saying nothing changed is the half a person actually
+  // worries about.
+  unreachable: "Nothing was changed. Check your connection and open this again.",
+  needs_approval: "Nothing was changed yet. The people who can approve it have been asked.",
+  stale_read: "Open this again in a moment and it will be up to date.",
+  timed_out: "Nothing was changed. Try a smaller page, or try again in a moment.",
   internal: "Nothing you did caused this. Try again, and tell us if it keeps happening."
 };
+var ENGINEER_TEXT = [
+  /@ai-matrx\//,
+  /\bSQLSTATE\b/i,
+  /\bPostgREST\b/i,
+  /\bIndexedDB\b/i,
+  // `<RecordsUiProvider>` — a component, on a screen.
+  /<\/?[A-Z][A-Za-z0-9]*\s*\/?>/,
+  // `savedViews`, `openRecords`, `onReask` — an identifier, however it is
+  // quoted. English does not write camelCase; code does.
+  /\b[a-z][a-z0-9]*[A-Z][A-Za-z0-9]*\b/,
+  // A backticked token is a thing you type into an editor, not a thing you do.
+  /`[A-Za-z_][A-Za-z0-9_.]*`/,
+  // "bind X on Y", "pass X", "import X" — an instruction to whoever maintains
+  // the app, arriving on the screen of somebody who cannot act on it.
+  /\bbind\s+[`'"A-Za-z]/i
+];
+function isEngineerText(text) {
+  return ENGINEER_TEXT.some((shape) => shape.test(text));
+}
 function withoutMachineClauses(sentence2) {
   const dropped = [];
   const footnotes = [];
@@ -506,11 +540,17 @@ function refusalForAPerson(error) {
   const message = plainSentence(String(error.message ?? ""));
   const hint = plainSentence(String(error.hint ?? ""));
   const title = TITLE[code] ?? "The store refused this";
-  const remedy = hint.kept ?? REMEDY[code] ?? REMEDY["internal"];
-  const said = (message.kept ?? "").trim();
+  const hintIsForEngineers = isEngineerText(String(error.hint ?? ""));
+  const remedy = (hintIsForEngineers ? null : hint.kept) ?? REMEDY[code] ?? REMEDY["internal"];
+  const messageIsForEngineers = isEngineerText(String(error.message ?? ""));
+  const said = (messageIsForEngineers ? "" : message.kept ?? "").trim();
   const forEngineers = [
     error.sqlstate ? `SQLSTATE ${error.sqlstate}.` : null,
-    error.hint && hint.kept !== error.hint ? `Hint: ${error.hint}` : null,
+    // The client's own note about a class it did not recognise, or a call that
+    // never reached the store. It is rendered out of sight, never as a sentence.
+    error.diagnostic ? error.diagnostic : null,
+    messageIsForEngineers ? `Message: ${error.message}` : null,
+    error.hint && (hintIsForEngineers || hint.kept !== error.hint) ? `Hint: ${error.hint}` : null,
     message.dropped.length > 0 || hint.dropped.length > 0 ? `Dropped from the person's view: ${[...message.dropped, ...hint.dropped].join(" | ")}` : null
   ].filter(Boolean).join(" ");
   return {
@@ -2704,7 +2744,7 @@ var import_react17 = require("react");
 var import_react18 = require("@ai-matrx/records/react");
 var import_design_system8 = require("@ai-matrx/design-system");
 var import_jsx_runtime11 = require("react/jsx-runtime");
-var NO_ENRICH_REASON = "No enrich port is bound, so this panel does not offer to fill a column it cannot fill. The value has to be written by the SERVER with actor `agent` on behalf of you \u2014 a browser that stamped itself `agent` would be a browser claiming to be one \u2014 so bind `enrich` on <RecordsUiProvider> with a call to the server's own `records` tool (action `enrich_propose`). Everything else on this panel works without it.";
+var NO_ENRICH_REASON = "Having an agent fill this column is not switched on here yet, so this panel does not offer it rather than offering something that cannot happen. Everything else on this panel works. It is on our list, not yours.";
 function cellState(cell) {
   if (!cell || !cell.agent_owned) return "none";
   if (cell.pinned) return "yours";
@@ -6011,7 +6051,7 @@ var import_react36 = require("react");
 var import_react37 = require("@ai-matrx/records/react");
 var import_design_system18 = require("@ai-matrx/design-system");
 var import_jsx_runtime21 = require("react/jsx-runtime");
-var NO_CHAT_REASON = "No chat port is bound, so this panel is absent rather than showing a composer that goes nowhere. Bind `chat` on <RecordsUiProvider> with your host's own chat surface \u2014 in AI Matrx that is `AgentConversationColumn`, launched through a Mandate \u2014 and this panel becomes that surface with this record as its context. This package deliberately ships no second chat UI.";
+var NO_CHAT_REASON = "Chatting about this record is not switched on here yet, so this panel is empty rather than showing a box that goes nowhere. It is on our list, not yours.";
 function RecordChat({ tableId, recordId, className }) {
   const client = (0, import_react37.useRecordsClient)();
   const host = useRecordsUi();
@@ -13949,7 +13989,7 @@ function CaptureRun({ sheetId, face: given, className }) {
 // src/CaptureSheet.tsx
 var import_jsx_runtime52 = require("react/jsx-runtime");
 var CAPTURE_MODES = ["reading", "photo", "voice"];
-var IN_MEMORY_QUEUE_REASON = "No capture queue is bound, so anything that cannot be sent right now is held in this page's memory and is lost if the page closes. Bind `captureQueue` on <RecordsUiProvider> with your host's own durable store (IndexedDB in a browser) and a queued capture survives the tab, the reload and the flight. It is said here rather than discovered later.";
+var IN_MEMORY_QUEUE_REASON = "Anything you capture while offline is held only in this page until it can be sent, and it is lost if you close the tab. Keep this page open until you are back on a connection. It is said here rather than discovered later.";
 function mintClientKey() {
   const c = globalThis.crypto;
   if (typeof c?.randomUUID === "function") return `capture:${c.randomUUID()}`;
@@ -14825,6 +14865,10 @@ var import_react111 = require("react");
 var import_react112 = require("@ai-matrx/records/react");
 var import_design_system54 = require("@ai-matrx/design-system");
 var import_jsx_runtime58 = require("react/jsx-runtime");
+function cameFromLine(label, groupField) {
+  const grouped = groupField ? `grouped into the same columns the chart used` : `for this table`;
+  return `You came here from \u201C${label}\u201D. This is every record ${grouped} \u2014 not only the ones that number counted \u2014 so the column you clicked is here with the rest beside it.`;
+}
 var TABLE_NOT_REACHABLE = "This table is not in the organization you are working in, so there is nothing here to show. Switch to the organization that owns it and open it again \u2014 or it may have been deleted.";
 var DEFAULT_VIEW_NAME = "All records";
 var VIEW_NOT_SAVED_YET = "This table has no saved view yet, so the layout you pick here is not being kept. Save one from the bar above and it is remembered.";
@@ -14868,6 +14912,8 @@ function TablePage({
   activeRecordId,
   activeView,
   onViewChanged,
+  activeGroupField,
+  cameFrom,
   className
 }) {
   const client = (0, import_react112.useRecordsClient)();
@@ -15061,10 +15107,24 @@ function TablePage({
       ] }),
       main === "dashboards" ? /* @__PURE__ */ (0, import_jsx_runtime58.jsx)(DashboardCanvas, { tableId, activeDashboardId: activeDashboardId ?? null }) : /* @__PURE__ */ (0, import_jsx_runtime58.jsxs)(import_jsx_runtime58.Fragment, { children: [
         opened.unknown ? /* @__PURE__ */ (0, import_jsx_runtime58.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,
+        cameFrom ? /* @__PURE__ */ (0, import_jsx_runtime58.jsx)(
+          "p",
+          {
+            "data-testid": "came-from-a-number",
+            className: "rounded-md border px-3 py-2 text-xs leading-relaxed text-muted-foreground",
+            children: cameFromLine(cameFrom, activeGroupField ?? null)
+          }
+        ) : null,
         /* @__PURE__ */ (0, import_jsx_runtime58.jsx)(
           ViewSwitcher,
           {
-            view: { ...view ?? defaultView(tableId), layout: shownLayout },
+            view: {
+              ...view ?? defaultView(tableId),
+              layout: shownLayout,
+              // The address's field wins for this visit; silence keeps the
+              // saved view's own choice, exactly as it always did.
+              ...activeGroupField ? { groupField: activeGroupField } : {}
+            },
             pageSize,
             onLayoutChange: (layout) => {
               setLayoutFromLink(layout);