@object-ui/plugin-detail 17.6.0 → 18.0.0

package/README.md

@@ -7,7 +7,9 @@ DetailView plugin for ObjectUI - A comprehensive detail page component with fiel
 - **Field Grouping/Sections**: Organize fields into logical sections with titles
 - **Collapsible Sections**: Make sections collapsible to save space
 - **Tab Navigation**: Organize content into tabs for better UX
-- **Related Lists**: Display related records (e.g., contacts for an account)
+- **Related Lists**: Display related records (e.g., contacts for an account) —
+  authored as a `record:related_list` block, ⛔ not as a `detail-view` `related`
+  array, which is retired (objectui#7997; see **RelatedList** below)
 - **Action Buttons**: Edit, Delete, and custom action buttons
 - **Readonly/Edit Mode**: Toggle between view and edit modes
 - **Back Navigation**: Built-in back button with customizable behavior
@@ -30,16 +32,20 @@ present:
 
 ```tsx
 import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';
+import { DetailView } from '@object-ui/plugin-detail';
+import type { DataSource } from '@object-ui/types';
+
+declare const dataSource: DataSource;
 
 // 1. Injected by an ancestor — the pattern the rest of the family uses, and the
 //    one to reach for when a page renders several data-bound blocks.
-<SchemaRendererProvider dataSource={dataSource}>
+const viaProvider = <SchemaRendererProvider dataSource={dataSource}>
   <SchemaRenderer schema={{ type: 'detail-view', objectName: 'account', resourceId: '42' }} />
-</SchemaRendererProvider>
+</SchemaRendererProvider>;
 
 // 2. Handed to one placement — what `<DetailView dataSource={…} />` has always
 //    taken, and what the examples below use.
-<DetailView schema={{ type: 'detail-view', objectName: 'account', resourceId: '42' }} dataSource={dataSource} />
+const viaProp = <DetailView schema={{ type: 'detail-view', objectName: 'account', resourceId: '42' }} dataSource={dataSource} />;
 ```
 
 Route 1 is new as of objectui#5378: this block used to read the adapter from its
@@ -52,6 +58,131 @@ and the object it was about to read, instead of an empty shell.
 Note the record id is `resourceId` here. `object-form`'s is `recordId`; the two
 blocks do not share that key.
 
+### The provenance footer belongs to the record page
+
+`RecordMetaFooter` is the one-line "Created … Updated …" summary of a record's
+audit fields. A standalone `DetailView` draws it under its body. On a
+`type: 'record'` page the footer is the PAGE's: the page host draws it once for
+the record, whatever the number of `record:details` nodes the page carries, and a
+`record:details` node that reads the page's record draws none of its own. So a
+page with two nodes shows the line once, and a node whose sections are all
+hidden draws nothing. The console's record page (`RecordDetailView` in
+`@object-ui/app-shell`) draws it at the page foot.
+
+A host that mounts `RecordContextProvider` itself renders `RecordMetaFooter`
+once, where its page ends, with the record as `data` and the object definition
+as `objectSchema`. A `record:details` node with a `dataSource` binding (below)
+shows a record the page does not, so it keeps its own footer.
+
+### Record blocks without a record page (`dataSource`)
+
+`record:details`, `record:highlights` and `record:quick_actions` show the record
+their record context carries: on a `type: 'record'` page, the page's record. On
+any other page, the spec's per-element `dataSource` binding supplies it — the
+block reads the FIRST row of the bound set by the binding's `sort`, under the
+caller's own identity:
+
+```json
+{
+  "type": "record:highlights",
+  "properties": { "fields": ["name", "environment_type"] },
+  "dataSource": { "object": "sys_environment", "sort": [{ "field": "created_at", "order": "desc" }], "limit": 1 }
+}
+```
+
+No row draws the block's authored `emptyState` when it declares one, and its
+no-record state when it does not. `record:quick_actions` runs the object's
+declared actions against the bound row's id. The binding resolves as on
+every bound block (a named `view`, an AND-combined `filter`, its `sort`), and the
+row is re-read when a write to its object is announced. Declare `limit: 1`:
+`objectui validate` warns on a record block whose binding does not. See
+**Per-element data binding on a page** in the data-source guide
+(`content/docs/guide/data-source.md`). `record:related_list`'s `dataSource` is
+different: it binds the rows the list shows.
+
+`emptyState` is the spec's empty-state shape, the one `object-grid` takes:
+`{ title, message, icon, link }`. It goes in `properties`, beside the block's
+other keys:
+
+```json
+{
+  "type": "record:details",
+  "properties": {
+    "fields": ["region"],
+    "emptyState": {
+      "title": "No production environment",
+      "message": "Create one from the environments page.",
+      "icon": "server",
+      "link": { "label": "Open environments", "url": "/environments" }
+    }
+  },
+  "dataSource": { "object": "sys_environment", "limit": 1 }
+}
+```
+
+It is drawn in the block's place only when the binding's read settles with no
+row. A read the server refuses as forbidden counts as no row. It is not drawn
+while the read loads, in place of the error a failed read shows, when a row is
+there, or on a block with no `dataSource`. `icon` is a Lucide name. `title` and
+`message` are plain strings or inline locale maps, resolved against the display
+locale. `link` is followed as a `url` action. Leave `title` out and the heading
+reads "Record not found". Leave `emptyState` out and the block keeps its own
+no-record state: "Record not found" on `record:details`, nothing on
+`record:highlights`, and the empty bar on `record:quick_actions`.
+
+A related list's PARENT record has a binding of its own, `parentDataSource` in
+its `properties` (the spec row's member). It is read by the same one-record
+rule — the first row by `sort`, re-read when its object is written — and the
+list draws that record's children:
+
+```json
+{
+  "type": "record:related_list",
+  "properties": {
+    "objectName": "sys_member",
+    "relationshipField": "environment_id",
+    "parentDataSource": { "object": "sys_environment", "sort": [{ "field": "created_at", "order": "desc" }], "limit": 1 }
+  }
+}
+```
+
+No row draws a notice in the block's place, never an empty list. Without the
+key, the parent is the record page's record.
+
+### A section heading that counts a field's values (`count`)
+
+A `record:details` section can show how many values a multi-value field holds
+on the current record. `count.field` names the field, and the heading writes the
+`{{ count }}` hole where the number goes (`@objectstack/spec` 18,
+`RecordDetailsProps.sections[].count`):
+
+```json
+{
+  "type": "record:details",
+  "properties": {
+    "sections": [
+      {
+        "name": "tagging",
+        "label": "{{ count }} tags",
+        "count": { "field": "tags" },
+        "fields": ["tags"],
+        "collapsible": true,
+        "defaultCollapsed": true
+      }
+    ]
+  }
+}
+```
+
+With three tags selected the heading reads `3 tags`, collapsed or not. An absent
+or empty value counts 0, and a field the viewer may not read counts as absent.
+The hole is filled after the heading is translated, so each locale of an inline
+label map and a translated `objects.<object>._sections.<name>.label` write the
+same `{{ count }}`. `count` changes the heading only: with `hideEmpty` on (the
+default), a section whose fields are all empty is still absent. The spec refuses
+`count` beside `group`, on a section without `label`, and on a label with no
+hole. A section without `count` prints its heading as written.
+
 ### Basic Example
 
 ```tsx
@@ -87,7 +218,11 @@ function ContactDetail() {
 ### With Sections
 
 ```tsx
-<DetailView
+import { DetailView } from '@object-ui/plugin-detail';
+
+declare const accountData: Record<string, unknown>;
+
+const accountDetail = <DetailView
   schema={{
     type: 'detail-view',
     title: 'Account Details',
@@ -117,13 +252,18 @@ function ContactDetail() {
     ],
     data: accountData,
   }}
-/>
+/>;
 ```
 
-### With Tabs and Related Lists
+### With Tabs
 
 ```tsx
-<DetailView
+import { DetailView } from '@object-ui/plugin-detail';
+
+declare const navigate: (url: string) => void;
+declare const deleteAccount: (id: string) => void;
+
+const accountDetail = <DetailView
   schema={{
     type: 'detail-view',
     title: 'Account: Acme Corp',
@@ -150,66 +290,229 @@ function ContactDetail() {
         key: 'activity',
         label: 'Activity',
         badge: '12',
+        // `record:activity` — the registered Activity Timeline block. Reachable
+        // under that exact key and no other; see the note below the block.
+        // Its inputs go in `properties`, as the spec declares them.
         content: {
-          type: 'activity-timeline',
-          data: activityData,
+          type: 'record:activity',
+          properties: { limit: 20, showCompleted: false },
         },
       },
     ],
-    related: [
-      {
-        title: 'Contacts',
-        type: 'table',
-        api: '/api/accounts/12345/contacts',
-        columns: ['name', 'email', 'phone', 'title'],
-      },
-      {
-        title: 'Opportunities',
-        type: 'table',
-        api: '/api/accounts/12345/opportunities',
-        columns: ['name', 'amount', 'stage', 'close_date'],
-      },
-    ],
     showEdit: true,
     showDelete: true,
   }}
   onEdit={() => navigate('/accounts/12345/edit')}
   onDelete={() => deleteAccount('12345')}
   onBack={() => navigate('/accounts')}
-/>
+/>;
 ```
 
+A tab's `content` is an **SDUI node**, not a private vocabulary: `DetailTabs`
+renders it with `<SchemaRenderer schema={toRenderableSchema(tab.content)} />`,
+so `content.type` is resolved by the component registry and an unregistered
+name paints the `Unknown component type` panel (**OBJUI-001**) instead of a
+component. Author only types this repository registers.
+
+Two things about the Activity tab above are worth copying rather than guessing
+(objectui#8114 — it previously taught `type: 'activity-timeline'`, which
+nothing registers):
+
+- **The key is `record:activity`, with the namespace spelled out.** The
+  registration in `src/index.tsx` passes the bare name under
+  `{ namespace: 'record', skipFallback: true }`, and `skipFallback` is what
+  stops the bare name from also being claimed globally — so `record:activity`
+  resolves and `activity` resolves to nothing. `activity` is additionally a tab
+  **key** in the example above; the two are unrelated.
+- **The node declares the feed's filters, not the feed.** Its inputs (`limit`,
+  `showCompleted`, `types`, `filterMode`, …) go in its `properties` bag, and
+  the block finds its own feed: a mounted discussion context, or a self-fetch
+  from `sys_activity` scoped to the record `useRecordContext` binds. Both need
+  a record host; a bare `<DetailView>` like the one above mounts neither, so
+  there the tab draws the block's empty state ("No activity recorded"). Under
+  a record host, such as the console's record page, the same node draws that
+  record's activity. `items` (with its `loading` flag) is the host's feed
+  slot, not a key of this node: `@object-ui/types` refuses it by name, and
+  `data` is not a key this block reads.
+
+See **The `record:activity` block** in the plugin-detail guide for its declared
+inputs (`types`, `limit`, `filterMode`, `showCompleted`, …).
+
 ## Schema
 
-The DetailView component accepts a `DetailViewSchema`:
+The DetailView component accepts a `DetailViewSchema`, declared in
+`@object-ui/types`. Import it rather than re-typing it — every key below is
+checked against that declaration, so this example cannot drift from the package:
 
 ```typescript
-interface DetailViewSchema {
-  type: 'detail-view';
-  title?: string;
-  objectName?: string;
-  resourceId?: string | number;
-  api?: string;
-  data?: any;
-  sections?: DetailViewSection[];
-  fields?: DetailViewField[];
-  tabs?: DetailViewTab[];
-  related?: RelatedList[];
-  actions?: ActionSchema[];
-  showBack?: boolean;
-  showEdit?: boolean;
-  showDelete?: boolean;
-  backUrl?: string;
-  editUrl?: string;
-  deleteConfirmation?: string;
-  loading?: boolean;
-  header?: SchemaNode;
-  footer?: SchemaNode;
-}
+import type { DetailViewSchema } from '@object-ui/types';
+
+const schema: DetailViewSchema = {
+  type: 'detail-view',
+  title: 'Account Details',
+  objectName: 'accounts',
+  resourceId: '12345',
+  api: '/api/accounts/12345',
+  data: undefined,
+  // Field name whose value becomes the header title; `title` is the fallback.
+  primaryField: 'name',
+  // Field values rendered as badges beside the header title.
+  summaryFields: ['industry', 'website'],
+  layout: 'vertical',
+  columns: 2,
+  // See the examples above for the shapes these three carry.
+  sections: [],
+  fields: [],
+  tabs: [],
+  actions: [],
+  // The view's own heading (title, follow-star, copy-id chip); drawn unless
+  // `false`. `record:details` sets it from its own `showHeader`.
+  showHeader: true,
+  showBack: true,
+  backUrl: '/accounts',
+  showEdit: true,
+  editUrl: '/accounts/12345/edit',
+  showDelete: true,
+  deleteConfirmation: 'Delete this account?',
+  loading: false,
+  header: { type: 'text', label: 'Custom header' },
+  footer: { type: 'text', label: 'Custom footer' },
+};
 ```
 
+### `summaryFields` and non-scalar values
+
+A summary chip is a single-line pill, and it formats `currency`, `date`,
+`datetime`, `percent` and the option families itself. Any other value it can
+render as text it renders as text.
+
+A **`percent`** chip is formatted by `@object-ui/fields`' `formatPercent` — the
+same call the list cell makes — so one stored value reads the same beside the H1
+as it does in a list: scaled at the storage the field declares (the spec's
+`percentScaleOf`: a fraction unless the field declares a `max` above 1, read
+through `percentCellScale` in `@object-ui/fields`, never guessed from the
+value), rounded to the width `resolveFieldScale` (`@objectstack/spec/data`)
+resolves for the field — its declared `scale`, or the protocol's own width for
+a percent that declares none, which every percent face reads (objectui#9843) —
+and rendered through the display locale's own percent affix rather than an
+appended sign. A stored `1234.5` on a field declaring `max: 100` therefore
+reads `1,235%` in an `en` session, and a stored `1` on a field declaring no
+`max` reads `100%`; both carry the locale's own affix and marks elsewhere. Which stored values that convention moves, and
+what each reads in both places, is re-derived by
+`src/__tests__/summaryChip.percentConvention-9167.test.tsx` rather than listed
+here. The chip's bar keeps the unrounded magnitude, as the list cell's bar does.
+
+An **object** value — an expanded lookup payload, an address, a location, a
+file — is drawn by that field's own cell renderer, so the chip shows what the
+same value shows everywhere else on the page: the referenced record's name, the
+formatted postal line, the coordinates, the file name.
+
+Fifteen field kinds are the exception, because their renderer does not fit a
+pill: the option families draw a badge (which would nest inside the chip's own),
+`user` draws an avatar, `image` / `avatar` / `signature` draw an image and no
+text at all, and `boolean` / `toggle` / `date` / `datetime` / `repeater` draw a
+"No value" face for a value the chip only exists because the page called
+filled. Those keep a text chip, carrying `@object-ui/fields`' shared value
+coercion — the record's name where the object has one, and `[Object]` where it
+does not. The set and the measurement behind it are
+`src/summaryChipRenderers.ts`.
+
 ## Components
 
+### RecordDetailPanel
+
+The record overlay's **payload**, with no shell of its own: one
+`InlineEditProvider` session wrapping `DetailView` plus the record-level
+`InlineEditSaveBar`, and the `objectSchema` → typed-field derivation that feeds
+them.
+
+All five list-type renderers (`ObjectGrid`, `ObjectTree`, `ObjectGantt`,
+`ObjectKanban`, `ObjectCalendar`) mount this component through
+`NavigationOverlay` from `@object-ui/components`, so an authored
+`navigation.mode` of `drawer` / `modal` / `split` / `popover` means the same
+thing on every view type (objectui#9299). ⛔ Do not re-wrap it in a shell of
+your own — that is exactly the fork this component exists to remove.
+
+```tsx
+import type { ReactNode } from 'react';
+import { NavigationOverlay, useOverlayAnchor } from '@object-ui/components';
+import { RecordDetailPanel } from '@object-ui/plugin-detail';
+import { useNavigationOverlay } from '@object-ui/react';
+import type { DataSource } from '@object-ui/types';
+
+declare const dataSource: DataSource;
+declare const objectSchema: { fields?: Record<string, unknown> };
+declare const myView: ReactNode;
+declare function saveField(field: string, value: unknown): Promise<void>;
+declare function deleteRecord(): Promise<void>;
+
+function ContactsOverlay() {
+  const navigation = useNavigationOverlay({
+    navigation: { mode: 'drawer' },
+    objectName: 'contacts',
+  });
+  // `popover` anchors to the element the click landed on; spread
+  // `anchorCaptureProps` on your own container, or call `captureAnchor(event)`
+  // at a click site that already has one.
+  const { anchorRef } = useOverlayAnchor();
+
+  return (
+    <NavigationOverlay
+      {...navigation}
+      title="Record Detail"
+      mainContent={myView}
+      popoverAnchorRef={anchorRef}
+    >
+      {(record) => (
+        <RecordDetailPanel
+          record={record}
+          objectName="contacts"
+          recordId={String(record.id)}
+          dataSource={dataSource}
+          objectSchema={objectSchema}
+          onFieldSave={saveField}
+          onDelete={deleteRecord}
+          onClose={navigation.close}
+        />
+      )}
+    </NavigationOverlay>
+  );
+}
+```
+
+Omit `onFieldSave` for a strictly read-only panel; omit `onDelete` for no
+delete action.
+
+**Capability is handler presence, not a boolean.** A caller that omits
+`onFieldSave` gets a read-only panel and one that omits `onDelete` gets no
+delete action — which is what lets a row locked through a renderer's `lockField`
+open read-only without the panel knowing what a lock is.
+
+**…and a handler is a wiring, not a grant.** The inline edit is the `recordEdit`
+row of the affordance-to-grant map in `@object-ui/core` (objectui#12082), the row
+the record page reads for the same in-place edit: the object's policy (read off
+the `objectSchema` you pass), the effective API operation set and the caller's
+**update** grant. When it is closed the panel opens no inline-edit session, as if
+`onFieldSave` were absent; each field still asks its own field question. The
+delete action is `DetailView`'s own `recordDelete` read. With no permission
+provider mounted both read open.
+
+`RECORD_OVERLAY_DEFAULT_WIDTH` is exported alongside it and is the single code
+home of the default overlay width repo-wide. ⛔ Do not re-spell the literal at a
+call site.
+
+### RecordDetailDrawer
+
+The same payload in the drawer shell — a published convenience wrapper that
+delegates to `NavigationOverlay` in `mode="drawer"`. It no longer owns a
+`Sheet`, a drag-resize implementation, or a chrome header of its own
+(objectui#9299).
+
+A width a user had already dragged is persisted by the shell under
+`ov:drawer-width:<objectName>`; a width left by the retired implementation under
+`objectui.drawerWidth.<objectName>` is read once, moved forward and removed, so
+existing widths carry over rather than reset.
+
 ### DetailSection
 
 Renders a group of fields with optional collapsing.
@@ -222,6 +525,54 @@ Tab navigation for organizing content into different views.
 
 Displays related records in list, grid, or table format.
 
+> **Retired: `DetailViewSchema.related`** (objectui#7997, ADR-0049
+> enforce-or-remove). Author a `record:related_list` block instead.
+>
+> Until objectui#7997 a `detail-view` node could carry its own `related` array,
+> and this README taught it. That array is retired under ADR-0049
+> enforce-or-remove (maintainer ruling 2026-09-10). It was a second entry to a
+> capability `@objectstack/spec` already governs — the protocol declares no
+> `DetailView` schema at all — so it mirrored nothing and drifted from the
+> renderer it fed: it typed `columns` as `TableColumn` objects while the
+> renderer also accepted bare field names. Authoring it is now **refused by
+> name** on both the TypeScript and the JSON face, ⛔ not silently ignored.
+>
+> Nothing about the rendered result changed: both entries always went through
+> the `RelatedList` component documented here. Only the second door closed.
+>
+> ```tsx
+> import { SchemaRenderer } from '@object-ui/react';
+>
+> const contacts = (
+>   <SchemaRenderer
+>     schema={{
+>       type: 'record:related_list',
+>       properties: {
+>         objectName: 'contact',
+>         relationshipField: 'account_id',
+>         title: 'Contacts',
+>         columns: ['name', 'email', 'phone'],
+>       },
+>     }}
+>   />
+> );
+> ```
+>
+> ⚠️ `columns` is an array of **field-name strings**, which is what the protocol
+> declares (`RecordRelatedListProps.columns`). The header comes from the related
+> object's field `label` and the cell from the field's type, so a label rename
+> reaches the list for free — the hand-spelled `{ accessorKey, header }` form the
+> retired array taught froze both. `relationshipField` names the field on the
+> related object pointing back at this record, and replaces the retired form's
+> `api` endpoint.
+>
+> ⚠️ The block reads the parent record from the record page's `RecordContext`,
+> so author it on a record page. Placed anywhere it cannot resolve a parent id
+> it scopes to nothing and renders an empty list — which is also what the
+> retired `related` form did whenever it declared `api` without a
+> `referenceField`.
+
+
 Related lists are **paged by default**: the `record:related_list` renderer
 applies the spec default `limit` of **5** when the node doesn't declare one
 (`@objectstack/spec` `RecordRelatedListProps.limit`, "Number of records to
@@ -245,18 +596,92 @@ value the cell shows — the label this list already resolved, the formula resul
 the server hydrated — so the affordance stays and orders by that.
 Passing `data` directly keeps the historical client-side slicing, and typing
 in the opt-in filter box temporarily falls back to the full-fetch client
-pipeline (the contains-filter sweeps every field, which no generic server
-filter can express).
+pipeline (the contains-filter sweeps the columns the list shows, which no
+generic server filter can express).
+
+A `password` / `secret` column draws `••••••`, and the list flags it
+`masked` on the table it renders (objectui#10657), so the table never copies it
+on Ctrl+C / Cmd+C, shows it as a tooltip, sorts by it from its header, or sizes
+it by its value. The rule is `isMaskedFieldType()` from `@object-ui/fields`,
+read over the column's authored `type` and the object's field type, so an
+authored `type: 'text'` over a `secret` field keeps the flag. While the object
+definition is still loading, or after its read failed, the list cannot tell
+which columns are masked, so it flags every one and draws every cell it would
+draw from that definition as the mask, never as text; it keeps doing so when
+the read failed (objectui#10657). A column with a `cell` of your own draws what
+your `cell` returns.
+
+The list's own filter box and sort read the same flag (objectui#10728). The
+opt-in filter box matches a term against the columns the list shows that are
+not masked, so a masked value, and a field no column shows, never keeps a row.
+A masked column gets no sort button on a `list` card, and a sort by it is
+refused (including one the embedded table asks for, which a server-paged list
+would send as `$orderby`). In a list that sorts in the browser, a sort set on a
+column before it was flagged also stops ordering the rows. While the definition
+is loading, or after its read failed, every column is flagged: the filter box
+keeps no row and no sort button is offered. Not covered: on a server-paged
+list, an authored `sort` naming a masked field is still sent to the server as
+`$orderby`, and so is a sort the user set on a column before that column was
+flagged, with each page the list fetches, until the user sorts by another
+column. The column is flagged after the sort only when the `columns` or the
+object of a list already on screen change; `record:related_list` sets both
+once per block.
+
+A list that authors `columns` sends a **`$select` projection** on its
+auto-fetch (`objectui#10186`), the one `ListView` and `ObjectGrid` already send
+(`objectui#6898`). It asks for the authored columns that pass the same gates the
+column layer draws through (redaction, the parent key, field-level security),
+plus `id`, the `$expand` roots, and, once the child schema has loaded, the
+fields the row predicates read (the child object's `userActions` Edit/Delete
+overrides, its actions, and the host's row actions), plus the mobile card
+gallery's cover field when declared and readable. A column the principal
+cannot read is dropped once the permission answer has loaded; a request sent
+before that answer can still carry it, the same deferral `ObjectGrid` has.
+If every authored column is denied, the list asks for `id` and its predicate
+operands, not for everything. On a backend that honours `$select`, rows then
+carry only the projected fields, so the opt-in filter box above sweeps those.
+A list **without** authored `columns` derives them from `highlightFields` or
+the field walk, and both choose by the emptiness of the rows fetched. That list sends no projection, and its column layer alone keeps a
+denied field off screen. Against ObjectStack's server the projection is defence
+in depth, because the server already strips denied fields from every row.
 
 The node's `filter` (spec `RecordRelatedListProps.filter`, "additional filter
 criteria") narrows the list beyond the parent relationship: it is
-**AND-combined** with `{ [relationshipField]: parentId }`, never substituted for
+**AND-combined** with the parent-relationship condition, never substituted for
 it, so a related list stays scoped to the record it appears on and an additional
-criterion can only ever narrow that set. Authors write it in the spec's own
+criterion can only ever narrow that set. That condition is **not one fixed
+spelling** — it is compiled to match the relationship field's ARITY on the
+child object (`objectui#7299`). A single-valued relationship gets the equality
+form `{ [relationshipField]: parentId }`; a multi-valued one gets the membership
+form `{ [relationshipField]: { $contains: parentId } }`, because the stored
+value is an array of ids and equality would ask whether the whole array *is* one
+id. The arity verdict is `@objectstack/spec/data`'s own `isMultiValueField`,
+never a rule this package keeps locally. Authors write `filter` in the spec's own
 vocabulary (`[{ field, operator, value }]`); a `dataSource` binding's composed
 filter (component AND saved view AND binding) lands on the same key. Both are
 lowered to ObjectQL through the repo's single filter sink, so no second dialect
-appears. On the legacy raw-URL fallback path (no `dataSource` adapter, where the
+appears.
+
+**A third producer writes that same key: the relationship itself.** A `lookup` /
+`master_detail` field may declare `relatedListFilter` (added to `@objectstack/spec`
+in objectstack#8704 / PR #8955 — see this package's own `@objectstack/spec`
+dependency in `package.json` for the version in use), a canonical Query-DSL
+`FilterCondition` such as
+`{ status: { $ne: 'deleted' } }`. `RecordDetailView` derives the record page's
+related lists from the relationship graph and carries that value onto this node's
+`filter`, so an auto-derived page honours it without anyone authoring a page
+(objectui#4664). It is an authored constraint, not a user-editable suggestion —
+it never becomes a filter-bar row — and it lands on the existing key rather than
+a new one, so all three producers share one read site and one lowering.
+
+The **tab badge honours the same composed filter**. `page:tabs` auto-derives a
+Related tab's count from the `record:related_list` nodes underneath it, and that
+probe reads this node's `filter` and composes it with the parent scope through
+the same `mergeFilterNodes` sink the row query uses — one value, sent twice. That
+is what keeps the badge from saying 7 above a list showing 3; it is normative in
+the spec key's own contract text, not a nicety. Counts are cached per
+(object, relationship, parent, **scope**), so a filtered and an unfiltered probe
+over the same relationship never badge each other. On the legacy raw-URL fallback path (no `dataSource` adapter, where the
 query language is `filter[<field>]=<value>` and cannot carry an operator) a
 declared filter is refused with a console explanation rather than dropped —
 answering with more rows than the metadata asked for is the failure this key's
@@ -268,6 +693,16 @@ add callback both required the adapter already, so without it the button used to
 render and do nothing at all when clicked — visible in hosts that supply no
 `RecordContext` (Studio designer previews, context-free embeds).
 
+…and only where the caller may make the write it ends in (objectui#12082). With
+a `linkField` the picked records become link rows of the list's own object: the
+**create** grant there, the `relatedNew` row of the affordance-to-grant map in
+`@object-ui/core`. Without one the picked record is re-parented: the **update**
+grant on `add.picker.object`, the `relatedRowEdit` row. The remove that the
+`record:related_list` renderer falls back to when an `add` config is present and
+no host handed over a delete reads the list object's `relatedRowDelete` row, the
+row the host's own delete reads, so it never puts back a delete the host
+withheld. With no permission provider mounted these read open.
+
 The `record:related_list` renderer is automatically gated on the current
 user's object-level `read` permission for the child object: when the
 permission system (`@object-ui/permissions`) is loaded and denies read,
@@ -294,6 +729,25 @@ shared draft (`InlineEditProvider` from `@object-ui/react`), committed by
 - **Approval lock**: hosts pass `locked` / `lockedHint` to the save bar and
   gate `InlineEditProvider.canEdit` when the record is approval-locked, so a
   locked record hides its edit affordances instead of rejecting at Save.
+- **Approval band & recall** (#6464): the band reads `approvalPending` /
+  `approvalProgress` from the same provider, and offers its **Recall** button
+  only where the click can succeed. Recall is the submitter's lever — the
+  server authorizes it on submitter identity and refuses everyone else — so
+  hosts that resolve approvals pass `InlineEditProvider.approvalIsSubmitter`.
+  It is tri-state on purpose: `false` withdraws the button from a resolved
+  non-submitter, `true` keeps it, and **omitting it leaves the button exactly
+  as it was** — a host that resolves no approval identity is unchanged rather
+  than losing its submitter's only unlock lever. It gates the affordance only;
+  the recall endpoint remains the authority on who may actually recall.
+- **Answered approvals read** (#12220): a host whose approvals read answered
+  (a 2xx) passes `InlineEditProvider.approvalReadAnswered`. Its `locked` /
+  `approvalPending` are then the whole answer, and the band stops falling back
+  to the record's `approval_status` column: a composition without the
+  approvals service answers the read with an empty list and enforces no lock,
+  so a stale `pending` in the column no longer shows a lock with nothing to
+  recall. Omitting it keeps the column fallback exactly as before. Hosts and
+  the band decide through one rule, `resolveApprovalLock` from
+  `@object-ui/react`.
 
 ## Links
 
@@ -309,32 +763,63 @@ shared draft (`InlineEditProvider` from `@object-ui/react`), committed by
 The "Reference Rail" is the right-hand column on the record detail page
 that surfaces summary cards for related collections (similar to
 Salesforce's **Related** rail and HubSpot's **About this record**
-sidebar). It is rendered by the `record:reference_rail` component and
-emits automatically when:
+sidebar). It is rendered by the `record:reference_rail` component. The
+rail is **off by default** — it fans out a collection query per related
+list — so the synth emits it only when the `buildDefaultPageSchema` call
+opts in with `showReferenceRail: true`, and then only when:
 
 1. The page is generated by the synth (`buildDefaultPageSchema`) — i.e.
    no explicit `Page` overrides the object's detail view.
-2. The objectDef declares **≥2 related collections** (lookup/master-detail
-   inbound fields).
+2. That same synth call passes **≥2 entries** in its `related` option —
+   the count is read off the caller's option, **not** off the objectDef.
 3. The viewport is **≥ xl (1280 px)** — below that the rail collapses and
    the **Related** tab keeps full coverage.
-4. The objectDef does **not** opt out via `detail.hideReferenceRail`.
+4. The synth call does **not** opt out via `hideReferenceRail`.
+
+Conditions 1, 2 and 4 are one conjunction inside `buildDefaultPageSchema`,
+quoted here verbatim so that a later change to it shows up as a diff
+against this page: `options.showReferenceRail === true`,
+`!options.hideReferenceRail`, `Array.isArray(options.related)`,
+`options.related.length >= 2`. Condition 3 is not part of that
+expression — it is the `hidden xl:flex` class the synth puts on the
+`aside` region.
+
+### Opting in
+
+The opt-in flag and the ≥2 count are both `buildDefaultPageSchema`
+**options**, never objectDef keys:
+
+```ts
+import { buildDefaultPageSchema } from '@object-ui/plugin-detail';
+import type { ObjectDefLike } from '@object-ui/plugin-detail';
+
+declare const opportunityDef: ObjectDefLike;
+
+const page = buildDefaultPageSchema(opportunityDef, {
+  showReferenceRail: true, // required — omit it and no rail is emitted
+  related: [
+    { objectName: 'quote', relationshipField: 'opportunity' },
+    { objectName: 'task', relationshipField: 'related_to_opportunity' },
+  ],
+});
+```
 
 When the rail emits, the synth automatically suppresses the **Related**
 tab so the same information isn't shown twice.
 
-### Per-object opt-out
+### Opting out
 
-Add a `detail` block to the objectDef:
+The opt-out is a `buildDefaultPageSchema` **option**, not an objectDef key:
 
 ```ts
-ObjectSchema.create({
-  name: 'product',
-  // …
-  detail: {
-    hideReferenceRail: true,  // hide the rail; restore the Related tab
-    hideRelatedTab: true,     // (optional) force-hide the Related tab too
-  },
+import { buildDefaultPageSchema } from '@object-ui/plugin-detail';
+import type { ObjectDefLike } from '@object-ui/plugin-detail';
+
+declare const productDef: ObjectDefLike;
+
+const page = buildDefaultPageSchema(productDef, {
+  hideReferenceRail: true,  // hide the rail; restore the Related tab
+  hideRelatedTab: true,     // (optional) force-hide the Related tab too
 });
 ```
 
@@ -355,7 +840,7 @@ For explicit (non-synth) Pages, add an `aside` region after the `main`
 region:
 
 ```ts
-{
+const asideRegion = {
   name: 'aside',
   width: 'small',
   className: 'hidden xl:flex flex-col gap-4',
@@ -372,11 +857,12 @@ region:
       },
     },
   ],
-},
+};
 ```
 
-The renderer reads `entries` from both `schema.entries` and
-`schema.properties.entries` so either spec-style or flat authoring works.
+The `entries` go in the node's `properties` bag, as the example shows: that
+bag is the contract, and `objectui validate` refuses a flat `entries` written
+on the node itself, naming `properties.entries`.
 
 ## License