@ai-matrx/detail 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog — @ai-matrx/detail
+
+## Unreleased
+
+Not published: 0.1.0 is still not on npm, so matrx-frontend's `lib/detail/**` remains the LIVE
+code and this `src/` remains what it must say (README → "Adoption status"). These fixes were made
+in BOTH copies in the same session, and the frontend now carries a drift guard that fails by name
+when they diverge.
+
+- **`Consumer action`: none for an installer** — nothing here changes an installed API's shape
+  except the two ADDITIONS below, both optional. A host already on 0.1.0's source copy must take
+  all of it, because the copies are diffed byte for byte.
+- **Fix — the page presentation's list query opened a DIFFERENT record** (VERIFY-U-P1-R5, N4).
+  `encodeRefPart` escaped `.` `:` `,` to `%2E` `%3A` `%2C`, and an ordinary query parse
+  (`new URL(...).searchParams`, which is where the page route's `searchParams` come from)
+  percent-decodes those back to bare separators BEFORE `decodeListItems` splits, so a dotted type
+  token resolved to `{type: <before the dot>}` and an id containing a comma was truncated. The
+  `?panels=` token survived only because it has three escaping layers. The grammar now carries no
+  `%` at all — percent-encoding spelled with `~` over `A-Za-z0-9-_~` — so it is invariant under
+  any number of percent-decodes. New test leg: the round trip THROUGH a query parse.
+- **Fix — an uncached `resolveType` looped forever** (N8). `useDetailHealth` and
+  `useDetailRecord` keyed their effects on the registration's FUNCTION identity, so a host whose
+  map builds the registration per call re-ran them every render (their own `setState` causing the
+  next) — "Maximum update depth exceeded" out of the package, and an endless reload of the same
+  record at the server. Both now key on the record type plus the id and read the closure through
+  a ref. `the-health-effect-does-not-loop.test.tsx` does not terminate against the old deps.
+- **Fix — a comment contradicted the line beneath it** (N9). `DetailPagePresentation` was headed
+  "It takes no `onBack`" directly above `onBack={core.leave}`; the behaviour is right (the one
+  guarded exit) and the sentence now says what it means: no `onBack` from its CALLER.
+- **New grant word `blocked`** (chair, 2026-09-18). `DetailSourceHealth.grant` gains a sixth
+  value for "the source refuses and nothing the person can click repairs it" — a provider outage,
+  a quota, a platform-configuration fault, a connection a server reports as unavailable. `unknown`
+  was carrying that meaning and it means "we could not check", so those records were offered a
+  consent window that repairs none of them. The strip says BLOCKED, states the reason, and
+  `reconnectFor` returns `null` for the word whatever the producer or the host supplies — the
+  refusal is structural, not a promise. The strip now shows the state word for every non-`ok`
+  grant.
+- **New optional `DetailRecordType.labelForRow`** (chair, 2026-09-18). `label` is per TYPE and a
+  registered type is regularly a family: `crm.party` holds 1,432 companies and 460 persons under
+  one type labelled "Person", so the header chip and every stand-in title called a company a
+  Person, twice on screen, above a field reading `organization` (VERIFY-U-P1-R5, N6). A
+  registration that can tell from the row answers here, and `DetailCore` gains `recordLabel`
+  beside `typeLabel`. Only the chip and the stand-in titles use it: the presentation pane keeps
+  the TYPE's label, because "Every contact record now opens as a window" is a statement about the
+  type's setting.
+- **`DetailField.ref` may carry a `name`, and the `doors.RefCell` port receives it.** The body
+  rendered the door from `ref.id` alone and threw `field.text` away, so a field whose value was
+  "Acme Robotics" printed a truncated uuid — a door nobody can read is half a dead end. The ref's
+  `name` wins; otherwise the field's text, unless that text IS the id.
+- **New optional port `history.ActorName`** (NEW-23, round 5). Every history row printed a bare
+  36-character uuid under "Changed by", because no host registry gives `actor_id` a door: an
+  identity the UI names that opens nothing. A host binds its ONE existing identity resolver here
+  and the row names the person; unbound, the id stays under a title that says we could not find
+  them.
+
+## 0.1.0
+
+The Detail primitive becomes a package. Extracted from matrx-frontend's `lib/detail` (the
+folder four verification rounds called "still not a PACKAGE" — VERIFY-U-P1-R4's first
+disqualifier), behaviour ported VERBATIM: the record-type contract, the presentation setting
+shape and its per-type override, the list-context trim with the final-URL byte budget
+(NEW-19 / NEW-20), the deep-link spelling with the escaped ref parts (NEW-25), the keyboard
+model bound on every slot (NEW-22), the honest absent states (NEW-9 / NEW-17), the history row
+that never drops who (NEW-23), the one guarded page exit (D1), and the source health strip
+with its async producer. 126 tests ride along, ported from jest to vitest, plus a mechanical
+boundary guard that had never existed (the README stated the boundary in prose).
+
+What changed on the way in, and why:
+
+- **The page presentation's list-context query spelling (`encodeListQuery` /
+  `decodeListQuery`) moved INTO the package** beside the panel-token spelling. It lived in the
+  host's overlay-payload module while every other spelling was already here; the Redux payload
+  shape stays in the host.
+- **The seventeen icons are inlined SVGs** (C19: no icon-library dependency). A record type's
+  own icon is unchanged host data.
+- **Host-shaped strings left the package.** The console remedy for an unregistered or
+  sourceless type named a matrx-frontend file; it now names the host's `remedy.typeMap` port
+  (default: the `resolveType` port), and the throw messages point at the README instead of a
+  host path.
+- **Module-level state moved to `globalThis` `Symbol.for` slots** (the host context and the
+  once-per-tab remedy set), per the dual-bundle rule — the ESM and CJS builds, and the `/react`
+  and `/testing` entries, share one context.
+- **Fix (Bugbot round 18 on frontend PR 228, comment 4041985944): `onReconnect: null` means
+  "offer nothing".** `useDetailHealth` filled the host's Reconnect back in with `??`, which
+  reads a producer's explicit `null` as "unset", so a synced record whose refusal a reconnect
+  cannot repair (a share the owner must grant, a record we own, an unclassified failure) still
+  showed Reconnect — a control that does nothing. The contract is now three-valued and
+  documented on `DetailSourceHealth.onReconnect` (a function → that action; `null` → none;
+  omitted → the host's), resolved by `reconnectFor`. Proven red (2 of 4 failing with the `??`
+  body) then green in `the-strip-honours-a-producers-refusal.test.tsx`.
+- **A `/testing` entry ships the stub-port seat** (`makePortsWith(fn)` takes the runner's mock
+  factory), so a host tests its binding against the same seat the package proves itself with —
+  one harness, no twin in the consumer.
+
+### Consumer action — matrx-frontend
+
+1. `package.json`: add `"@ai-matrx/detail": "latest"` beside the other `@ai-matrx/*` entries,
+   then `pnpm install` and `pnpm check:matrx-packages`.
+2. `app/globals.css`: add `@source "../node_modules/@ai-matrx/detail/dist";` (the components are
+   Tailwind-utility styled; the consumer's scan must see the built package).
+3. Import from the package: types, spelling helpers, `trimListContext`, `encodeListQuery` /
+   `decodeListQuery`, `fieldsFromRow` from `@ai-matrx/detail`; `DetailHostProvider`,
+   `useDetailHost`, `useDetailCore`, `useOpenDetail`, the presentations, header/body/pane
+   and the geometry constants from `@ai-matrx/detail/react`; the test seat from
+   `@ai-matrx/detail/testing` with `makePortsWith(jest.fn)`.
+4. Delete `lib/detail/**` source and tests (they are here now); keep its `FEATURE.md` as the
+   host-wiring pointer.
+5. Bind the new optional port `remedy: { typeMap: "…" }` in the host binding so the console
+   remedy names the item registry.
+6. Any health producer that decides a reconnect would not help must answer
+   `onReconnect: null` (not omit the key) — omitting it now means "defer to the host".

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,153 @@
+# @ai-matrx/detail — the Detail primitive
+
+> Arman, 2026-09-17: *"a core component that then shows up as a Page, a flexible drawer, and a
+> window panel. The default is the window. … you just make a core component with some core
+> rules, then wrap it in this reusable thing from the package, which then instantly gives you
+> all 3 for free."*
+
+ONE registration per record type → three presentations for free, with the same content in all
+three. Keyboard: Escape closes, the arrows move between records (`[` / `]` are aliases), and
+Cmd/Ctrl+Enter saves.
+
+| Presentation | What it is | What the host binds |
+|---|---|---|
+| `window` (**the default**) | Floating, draggable, minimizable; a bottom sheet on phones | `shells.Window` — the host's window manager |
+| `docked` | A resizable side panel docked to the right edge, no backdrop; a bottom sheet on phones | `shells.Docked` — the host's side-panel surface |
+| `page` | A full route body under the app header — the only presentation that changes the URL; offers the window back | `shells.Page` — the host's route header + scroll body |
+
+Champions: Notion (side peek / center peek / full page, per-database "open pages in") and Linear
+(peek, keyboard-first). Bones matched, skin ours.
+
+```
+pnpm add @ai-matrx/detail        # every Matrx repo declares it "latest" (THE LATEST LAW)
+```
+
+## 🚨 Adoption status — nothing installs this yet, and matrx-frontend carries a COPY
+
+The `mv` has been performed and the three gates pass here, but **0.1.0 is not on npm**. The
+frontend adopted it (`ec7ce701`) and the adoption was **reverted** (`32ce9170`, ruling R21)
+because a `"latest"` spec for a package the registry does not have kills the ONE
+`pnpm install --frozen-lockfile` every workspace project shares. The publish is a human step.
+
+So until it lands: **matrx-frontend's `lib/detail/**` is the LIVE code and this `src/` is the
+source of truth for what it should say.** A fix goes in BOTH, in the same session. What keeps
+them honest is the frontend's own drift guard,
+`lib/detail/__tests__/the-in-repo-copy-matches-the-package.test.ts`, which diffs all fifteen
+module pairs against this `src/` and fails by name on any difference outside the module header
+and relative import specifiers. It FAILS AS UNMEASURED when this checkout is absent, never
+passes quietly. The fifteen days when nobody had that guard are exactly when the copies
+diverged: this package fixed a reviewed defect (`onReconnect: null` still got a Reconnect
+button) and the revert un-fixed it in the frontend, where a person could feel it
+(VERIFY-U-P1-R5, N1 / N2). One file is deliberately different and says so: `react/icons.tsx`
+inlines its glyphs here (no icon-library dependency), and the host's `core/icons.ts` re-exports
+Lucide's `*Icon` aliases under the same names.
+
+| Entry | Ships | `"use client"` |
+|---|---|---|
+| `@ai-matrx/detail` | the record-type contract, the presentation setting shape and its per-type override, the list-context trim with the final-URL byte budget, the deep-link spelling of every presentation, the row → fields formatter | no — pure, legal in a Server Component |
+| `@ai-matrx/detail/react` | the ports and provider, the core, the keyboard model, the loader and the health resolver, the one opener, the header halves, the body, the setting pane, the three presentations, the header geometry constants | yes |
+| `@ai-matrx/detail/testing` | the stub-port seat: `makePortsWith(fn)`, `mount`, `instance`, `clickByLabel`, three stub shells, `FILE_TYPE` — the seat the package proves itself with, for a host to prove its binding with | yes |
+
+## The contract — one registration per record type
+
+```ts
+import type { DetailRecordType } from "@ai-matrx/detail";
+
+const task: DetailRecordType = {
+  type: "task", label: "Task", icon: TaskIcon, accent: null,
+  entityToken: "task",          // doors · associations · history key off this; null = none
+  load: (id, signal) => …,      // null = no single source → renders from the seed, and says so
+  title: (row, seed) => …,
+  fields: (row) => […],
+  health?: (row, ctx) => …,     // the source health strip for a SYNCED record (sync or async)
+  associationTokens?: […],      // null hides the section; omitted → the host default minus self
+  history?: true,               // default: when entityToken is set
+  extraSections?: (row, ctx) => […],
+  Frame?: ({ ctx, children }) => …,   // wraps the body: surface runtime, right-click menu, …
+};
+```
+
+Fixed sections, in order: **source health strip** (synced records only) · about · **fields** ·
+**associations** (`AssociationCardGrid` under a `PrimaryEntityProvider`, from
+`@ai-matrx/associations`) · **history** (row versions) · extras · the "how details open" pane.
+A section that does not apply is absent, never an empty box.
+
+**The one opener:** `useOpenDetail()({ type, id, presentation?, seed?, list? })`. Without
+`presentation` it asks the host's `resolvePresentation(type)` — the person's
+`ui.detail.default_presentation`, with `ui.detail.presentation_by_type` read first for that
+type. A resolver that raises is announced (the host's `notify.error`, naming the key) and the
+window opens. Nothing navigates away except `page`.
+
+## Binding the ports
+
+Everything app-shaped arrives through `DetailHostPorts` (`@ai-matrx/detail/react`). Providers
+nest and merge: bind the light ports ONCE at boot so `useOpenDetail` works everywhere, and let
+each presentation's lazily loaded entry add its own shell and the record-type map right above
+the presentation, so the window shell never reaches a boot bundle. A missing port throws,
+naming itself.
+
+| Port | What the host injects | Required |
+|---|---|---|
+| `resolveType(type)` | THE record-type map — one registry, never a second | per presentation entry |
+| `usePresentationSetting(type)` · `resolvePresentation(type)` · `warmPresentation(type)` | the settings ladder's answer for `ui.detail.default_presentation` and `ui.detail.presentation_by_type` (React face, awaited face, cache warmer) | yes |
+| `reReadPresentation(type)` | a FRESH ladder read after a write, naming the rung that answers now | optional |
+| `savePresentation({ presentation, forType, clear? })` | the ONE writer of the setting and its per-type map entry; a refusal comes back as `{ ok: false, reason }` | optional — absent ⇒ the pane is absent |
+| `open` · `close` | the in-place presentations (window / docked) on the host's overlay system | yes |
+| `navigate.pageHref` · `toPage` · `back` · `canGoBack` · `toRecordHome` | the page route; `canGoBack` answers "did THIS tab push the page" and `toRecordHome` replaces the page with the record's home — never a raw `back()` into an empty history | yes |
+| `shells.Window` · `Docked` · `Page` | the chrome; the package fills `title`, `titleNode`, `actions`, `children`, `onClose` (+ `onBack` for the page, + `list` for the window's deep link) | per presentation entry |
+| `doors.RecordDoors` · `RefCell` · `tokenFromColumnName` · `isUuidValue` · `hasDoor` | the host's entity doors (open / new tab / peek); `hasDoor` decides whether the absent state may claim "the controls above still open it" | yes |
+| `associations.defaultTokens` · `canAnchor` | which tokens the associations section shows and which may anchor one | yes |
+| `history.list(token, id, signal)` | row versions | yes |
+| `notify.error` · `success` · `copyText` | the host's toast and clipboard | yes |
+| `reconnectSource(ref, source)` | the same Reconnect the connector rows offer, for a synced record's strip | optional |
+| `remedy.typeMap` | where the developer goes to register a type — the console remedy names it | optional |
+
+The knobs the package READS THROUGH PORTS and never resolves itself: `ui.detail.default_presentation`
+(enum `window|docked|page`, organization → user), `ui.detail.presentation_by_type` (json map,
+same ladder), `ui.detail.list_context_max_ids` (organization; the host resolves it and passes
+the number into `encodeListQuery` / `detailListToUrlArgs`, which clamp it to
+`DETAIL_LIST_CONTEXT_MAX_IDS_CEILING`). Their rows are seeded by matrx-frontend's migrations.
+
+## Deep links
+
+Window and docked deep links ride the host's ONE panel-URL mechanism under the type key
+`detail`, instance `type.id`, arg `as`: `?panels=detail:task.<uuid>:as-window` / `:as-docked`,
+carrying the list the record was opened from (`l` / `i` / `lt`). The page is the host's route
+(`/detail/<type>/<id>` in matrx-frontend) with `?l=type.id,…&i=<n>&lt=<total>`. Both spellings
+are cut by ONE trim (`trimListContext`) against ONE budget — 8,000 characters of the FINAL
+serialized URL, with what the rest of the address costs reserved — and the record says when the
+list was trimmed. `.` `:` `,` inside a type token or an id are escaped, so an external id such
+as `sc-domain:example.com` round-trips as the same record.
+
+## Keyboard
+
+`useDetailKeyboard`, bound on every slot the presentation fills (header and body): Escape closes
+from any control except an open menu / select / combobox and a text field with uncommitted
+edits; ArrowUp/Down/Left/Right move between records only when the body is not the scroll target,
+`[` / `]` always move; Cmd/Ctrl+Enter saves what a section registered — and says there is nothing
+to save when nothing did.
+
+## Testing a host binding
+
+```ts
+import { makePortsWith, mount, instance, StubPageShell } from "@ai-matrx/detail/testing";
+const makePorts = makePortsWith(jest.fn);   // or vi.fn — the seat takes the runner's factory
+const ports = makePorts({ shells: { Page: StubPageShell } });
+const m = mount(<DetailPagePresentation data={instance()} />, ports);
+```
+
+Every port is a mock, so a test asserts what the core ASKED THE HOST TO DO — which is where every
+recorded defect of this primitive lived.
+
+## What is deliberately NOT here
+
+- The host's window manager, side panel and route header — they are shells, bound as ports.
+- The settings ladder, the toast, the clipboard, the router, the entity registry — ports.
+- An icon library: the seventeen glyphs the primitive draws are inlined SVGs (Lucide-derived,
+  ISC). A record type's own icon is host data on its registration.
+- Tailwind CSS generation: the components are styled with utility classes. Register the built
+  package with the consumer's Tailwind scan (`@source "../node_modules/@ai-matrx/detail/dist";`
+  in matrx-frontend's `globals.css`, the design-system precedent).
+
+Implementation truth, file map and change history: `FEATURE.md` beside this file. Packaging
+law: `common-docs/policies/typescript-package-standard.md`.