@object-ui/plugin-detail 17.5.0 → 17.7.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
@@ -22,6 +24,40 @@ pnpm add @object-ui/plugin-detail
 
 ## Usage
 
+### Two ways to reach a data source
+
+`detail-view` needs a data source to load a record, and there are two ways to
+give it one. They are equivalent, and an explicit prop wins when both are
+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.
+const viaProvider = <SchemaRendererProvider dataSource={dataSource}>
+  <SchemaRenderer schema={{ type: 'detail-view', objectName: 'account', resourceId: '42' }} />
+</SchemaRendererProvider>;
+
+// 2. Handed to one placement — what `<DetailView dataSource={…} />` has always
+//    taken, and what the examples below use.
+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
+prop ONLY, while its siblings `object-grid` and `object-form` read it from
+context only, so a page could satisfy one of them or the other and never both.
+Nothing that worked before changed — route 2 is unaffected — and a block that
+resolves neither now renders a **No data source resolved** panel naming itself
+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.
+
 ### Basic Example
 
 ```tsx
@@ -57,7 +93,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',
@@ -87,13 +127,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',
@@ -120,66 +165,220 @@ 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.
+
+`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.
@@ -192,6 +391,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
@@ -202,26 +449,105 @@ reads the collection size from `QueryResult.total` (falling back to a
 `hasMore` estimate), so large child tables never ship wholesale to the
 browser. A user column sort becomes a server `$orderby` (ordering stays
 global across pages), and the node's `sort` prop seeds the initial order.
-Because that `$orderby` names a flat field, a **relational column**
-(`lookup` / `master_detail` / `user` / `tree`) would order the collection by the
-stored foreign-key id while its cells show related-record names — so on the
-windowed path those columns offer no sort button at all. In client mode the
-sort key is the label this list already resolved for the cell, so the button
-stays and orders by that name.
+Because that `$orderby` names a flat field, two kinds of column cannot survive
+the trip. A **relational column** (`lookup` / `master_detail` / `user` / `tree`)
+would order the collection by the stored foreign-key id while its cells show
+related-record names (`objectui#3096`); a **`formula` column** has no
+materialized column to order by at all — silently unordered rows under a `200`
+before `objectstack#6994`, a `400 INVALID_SORT` after it (`objectui#3950`). So on
+the windowed path neither offers a sort affordance, at either of this card's two
+sort entry points: the embedded table's column headers, and the button row a
+`list` card keeps because it has no headers. In client mode the sort key is the
+value the cell shows — the label this list already resolved, the formula result
+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
@@ -259,6 +585,16 @@ 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.
 
 ## Links
 
@@ -274,32 +610,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
 });
 ```
 
@@ -320,7 +687,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',
@@ -337,11 +704,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
 

package/dist/ActivityTimeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActivityTimeline.d.ts","sourceRoot":"","sources":["../src/ActivityTimeline.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;AAE/D,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,8CAA8C;IAC9C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yCAAyC;IACzC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAkED,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CA6F5D,CAAC"}
+{"version":3,"file":"ActivityTimeline.d.ts","sourceRoot":"","sources":["../src/ActivityTimeline.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD,MAAM,MAAM,kBAAkB,GAAG,aAAa,CAAC,MAAM,CAAC,GAAG,KAAK,CAAC;AAE/D,MAAM,WAAW,qBAAqB;IACpC,UAAU,EAAE,aAAa,EAAE,CAAC;IAC5B,8CAA8C;IAC9C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,yCAAyC;IACzC,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAuHD,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,qBAAqB,CAmG5D,CAAC"}

package/dist/CommentAttachment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CommentAttachment.d.ts","sourceRoot":"","sources":["../src/CommentAttachment.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,QAAQ,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAqBD,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CAgJ9D,CAAC"}
+{"version":3,"file":"CommentAttachment.d.ts","sourceRoot":"","sources":["../src/CommentAttachment.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAK/B,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,QAAQ,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAqBD,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CAkJ9D,CAAC"}