@object-ui/plugin-detail 17.6.0 → 18.0.0

package/dist/renderers/recordComponentAria.d.ts

@@ -0,0 +1,44 @@
+import { RecordComponentAriaProps } from '@object-ui/types';
+/**
+ * The authored `aria` bag as a renderer actually receives it: the declared
+ * face, plus the undeclared `label` spelling a stored document may still carry.
+ */
+export type AuthoredRecordAria = RecordComponentAriaProps & {
+    /**
+     * ⛔ Not a member of the contract. It is the shared ARIA shape's alias entry
+     * and is refused on parse. Declared on this type ONLY so the diagnostic can
+     * see it without an `as any` cast (a cast is how `record:path` once came to
+     * read this spelling and no other).
+     *
+     * ⚠️ It is never read as a name. objectui#9945 retired the fold that did;
+     * a served value is reported, and only for a caller that names its `block`.
+     * See this module's header.
+     */
+    label?: string;
+};
+/** What {@link useRecordAriaProps} spreads onto a block's container element. */
+export interface RecordAriaDomProps {
+    'aria-label'?: string;
+    'aria-describedby'?: string;
+    role?: string;
+}
+/**
+ * The ARIA DOM props for a `record:*` block's own container.
+ *
+ * @param aria - the authored bag, straight off the node's `aria` key.
+ * @param defaultRole - the role this block renders when the author declares
+ *   none. Omit it and the container stays role-less until an author declares a
+ *   name, a description or a role — at which point `'region'` carries the name,
+ *   because an attribute on a `generic` element carries nothing.
+ * @param defaultLabel - the block's built-in accessible name, used when the
+ *   author declared none (or declared an empty one).
+ * @param block - the block's registered type (`record:path`), named in the
+ *   report of a served `aria.label`. Omit it and that spelling is still not
+ *   read, just not reported. See this module's header for which blocks pass it.
+ */
+export declare function useRecordAriaProps(aria: AuthoredRecordAria | undefined, { defaultRole, defaultLabel, block, }?: {
+    defaultRole?: string;
+    defaultLabel?: string;
+    block?: string;
+}): RecordAriaDomProps;
+//# sourceMappingURL=recordComponentAria.d.ts.map

package/dist/renderers/recordComponentAria.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recordComponentAria.d.ts","sourceRoot":"","sources":["../../src/renderers/recordComponentAria.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AAKH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAEjE;;;GAGG;AACH,MAAM,MAAM,kBAAkB,GAAG,wBAAwB,GAAG;IAC1D;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,gFAAgF;AAChF,MAAM,WAAW,kBAAkB;IACjC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAwCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,kBAAkB,GAAG,SAAS,EACpC,EACE,WAAW,EACX,YAAY,EACZ,KAAK,GACN,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACtE,kBAAkB,CAapB"}

package/dist/renderers/relatedListActions.d.ts

@@ -0,0 +1,102 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * `record:related_list.actions` — where an authored action id lands on the list,
+ * or why it is refused (objectui#11163; the maintainer's ENFORCE ruling on
+ * objectstack-ai/objectstack#20665).
+ *
+ * The contract declares the key as `z.array(z.string())`, "Action IDs available
+ * for related records". This module is the whole of its meaning, kept apart
+ * from the renderer so the file that draws the block keeps exporting
+ * components only:
+ *
+ *   - RESOLUTION is `resolveDeclaredActionIds` — the one function
+ *     `page:header`, `record:quick_actions` and `record:alert` resolve an
+ *     authored action id through (objectui#7182, objectui#7382) — against the
+ *     RELATED object's registered `actions`. ⛔ No second lookup: the caller
+ *     reads that registry through `useMetadataItem('object', …)`, the same
+ *     entry `record:quick_actions.actionNames` uses.
+ *   - Only the IDS arm is this key's. The inline-object arm of the shared
+ *     rule is `page:header`'s transition tolerance (objectstack#11592) and is
+ *     not inherited here, the choice `record:alert` made for its CTA: an
+ *     object in this array would widen what a related list can run past what
+ *     the object declares.
+ *   - PLACEMENT is each action's own `locations`, read by `actionRendersAt`
+ *     — the platform's one placement rule, and the rule the host bridge
+ *     (`RelatedRecordActionsBridge.deriveActions`) already applies to this
+ *     list: `list_toolbar` draws a header button; `list_item` and
+ *     `record_related` draw a row-menu item (objectui#11270). This block only
+ *     ever renders inside a parent record, which is the scope `record_related`
+ *     names (objectstack-ai/objectstack#20937, triage `5919625056`: row
+ *     placement, inside a record only). Naming an action here does not bypass
+ *     location filtering (only a list view's selection bar is placed by
+ *     naming), so an id whose action declares none of the three is REFUSED
+ *     rather than drawn somewhere or dropped.
+ *   - ORDER is the author's, within each surface.
+ */
+/**
+ * An action definition as the registry holds it — the two members read here,
+ * typed `unknown` because the definitions arrive straight off the metadata
+ * wire (the reason `actionRendersAt` gives for its own parameter).
+ */
+export interface RegisteredRelatedAction {
+    readonly name?: unknown;
+    readonly locations?: unknown;
+}
+/** One reason an authored entry does not render, stated for the author. */
+export type RelatedListActionRefusal = 
+/** The array itself is refused: not an array, or not all action ids. */
+{
+    readonly kind: 'array';
+    readonly message: string;
+}
+/** An id that names no registered action of the related object. */
+ | {
+    readonly kind: 'unresolved';
+    readonly id: string;
+}
+/** An id that resolves, to an action declaring no location this list renders. */
+ | {
+    readonly kind: 'unplaced';
+    readonly id: string;
+};
+export interface PlacedRelatedListActions<T> {
+    /** `list_toolbar` actions, in authored order — the list's header buttons. */
+    readonly toolbar: T[];
+    /** `list_item` and `record_related` actions, in authored order — each row's menu. */
+    readonly row: T[];
+    /** Every authored entry that renders nowhere, and why. */
+    readonly refused: RelatedListActionRefusal[];
+}
+/**
+ * Whether an authored value has any id to look up — the registry-independent
+ * half of the shared rule, so the caller requests the metadata read only when
+ * it can change the answer (a `[]`, an object array or a refused array is
+ * decided without it).
+ */
+export declare function relatedListActionsNeedLookup(authored: unknown): boolean;
+/**
+ * Resolve and place an authored `record:related_list.actions` value.
+ *
+ * `registered` is the related object's `actions` once the metadata lookup has
+ * ANSWERED. The caller does not call this while the lookup is in flight: every
+ * id would come back unresolved and the list would refuse an id it is about to
+ * resolve.
+ *
+ * An id authored twice renders once, at its first position — it is drawn, so
+ * nothing the author asked for is dropped.
+ */
+export declare function placeAuthoredRelatedListActions<T extends RegisteredRelatedAction>(authored: unknown, registered: readonly T[] | null | undefined): PlacedRelatedListActions<T>;
+/**
+ * The refusal notice's text — one sentence per refused entry, naming it and
+ * the related object, so the fix is a one-entry edit.
+ *
+ * `objectKnown` is whether the lookup found the related object at all: an id
+ * cannot be "not an action of" an object whose metadata never arrived.
+ */
+export declare function describeRelatedListActionRefusals(refused: readonly RelatedListActionRefusal[], objectName: string, objectKnown: boolean): string;
+//# sourceMappingURL=relatedListActions.d.ts.map

package/dist/renderers/relatedListActions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relatedListActions.d.ts","sourceRoot":"","sources":["../../src/renderers/relatedListActions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAIH;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,2EAA2E;AAC3E,MAAM,MAAM,wBAAwB;AAClC,wEAAwE;AACtE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACtD,mEAAmE;GACjE;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE;AACtD,iFAAiF;GAC/E;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,MAAM,WAAW,wBAAwB,CAAC,CAAC;IACzC,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC;IACtB,qFAAqF;IACrF,QAAQ,CAAC,GAAG,EAAE,CAAC,EAAE,CAAC;IAClB,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,wBAAwB,EAAE,CAAC;CAC9C;AAQD;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAIvE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,+BAA+B,CAAC,CAAC,SAAS,uBAAuB,EAC/E,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,SAAS,CAAC,EAAE,GAAG,IAAI,GAAG,SAAS,GAC1C,wBAAwB,CAAC,CAAC,CAAC,CA6C7B;AAED;;;;;;GAMG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,SAAS,wBAAwB,EAAE,EAC5C,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,OAAO,GACnB,MAAM,CAeR"}

package/dist/summaryChipPercent.d.ts

@@ -0,0 +1,83 @@
+import { PercentScale } from '@object-ui/core';
+/**
+ * The ONE rule the `summaryFields` chip scales a stored `percent` by — and it
+ * is the repo's, not this file's (objectui#9071).
+ *
+ * ⭐ Since objectui#9167 this is the chip's BAR path only. The chip's TEXT goes
+ * straight to `formatPercent` in `@object-ui/fields` — the list cell's own
+ * body, which applies {@link percentDisplayValue} itself and then the locale's
+ * percent affix at the field's precision. See "The half objectui#9071 did NOT
+ * take" below, which objectui#9167 closed.
+ *
+ * ## Why this function exists at all (objectui#8728)
+ *
+ * The chip beside the record H1 draws a percent TWICE — as its text and as a
+ * small bar — and the two halves scaled the same stored number by two
+ * different rules:
+ *
+ *     display = `${num}%`;                            // the text: no scaling
+ *     const normalized = num <= 1 ? num * 100 : num;  // the bar: ratio, scaled
+ *
+ * so a stored `0.123` labelled itself `0.123%` beside a bar filled to 12.3%.
+ * One control, two percentages, and neither half told the reader which one was
+ * right. Both halves read this function — which is why it is a named function
+ * and not the same ternary written twice. The next reader cannot
+ * re-desynchronise them without deleting a call site.
+ *
+ * ## What objectui#9071 DELETED, and why aligning it would not have done
+ *
+ * objectui#8728 converged the chip's two halves onto the BAR's rule and
+ * recorded, rather than decided, that the rule was the chip's own. The census
+ * it asked for answered the question: the predicate that stood here —
+ * a pass-through spelled `if (raw > 1) return raw;`, i.e. the bar's original
+ * `num <= 1` written the other way round — was the only spelling of its kind on
+ * this side of the tree, and it disagreed with the declared single source of
+ * truth at EXACTLY 1 and at every value AT OR BELOW -1:
+ *
+ * | stored | the deleted local rule | `percentDisplayValue`, and every other band |
+ * |--------|------------------------|---------------------------------------------|
+ * | `0.25` | `25%`                  | `25%`   (the band they always agreed on)     |
+ * | `1`    | `100%`                 | `1%`                                         |
+ * | `-1`   | `-100%`                | `-1%`                                        |
+ * | `-5`   | `-500%`                | `-5%`                                        |
+ *
+ * ⛔ The repair is NOT to move the local predicate's boundary onto the shared
+ * one. That would leave two rules agreeing by coincidence — the same shape
+ * objectui#5607 removed one package over, and the shape that produced this
+ * drift in the first place. The predicate is gone; the authority is
+ * {@link percentDisplayValue} in `@object-ui/core`, whose own doc comment
+ * requires exactly this of a third surface, and which the list cell
+ * (`formatPercent` / `PercentCellRenderer`), the dashboard measure
+ * (`formatMeasure`) and the grid column summary already read.
+ *
+ * ## The half objectui#9071 did NOT take — closed by objectui#9167
+ *
+ * That doc comment asks a third surface for BOTH halves — the scaling AND the
+ * convention. objectui#9071 moved the SCALING only: the chip stated the full
+ * JavaScript number with a bare `%` while the list cell rendered through the
+ * locale's percent affix at the field's precision (`0` by default), so a stored
+ * `12.3` read `12.3%` beside the H1 and `12%` in the list — two spellings of
+ * one magnitude, with the two bars proving the magnitude was one. That card
+ * stopped because its acceptance forbade moving values the chip rendered
+ * correctly today, and the convention half moves several.
+ *
+ * objectui#9167 took it, value by value rather than by inspection: both
+ * surfaces were driven in the same run, on the same field, for every stored
+ * value below, and every row that MOVED moved onto the reading the list cell
+ * was already giving. The chip's text is now the cell's own `formatPercent`
+ * call, byte for byte, and this function is left
+ * holding the BAR alone. The table and its `de-DE` leg are pinned in
+ * `__tests__/summaryChip.percentConvention-9167.test.tsx`.
+ *
+ * ## The storage is the field's, stated by the caller (objectui#11475)
+ *
+ * `percentScale` is the storage the chip's field declares, which `DetailView`
+ * reads with `percentCellScale` (`@object-ui/fields`): the spec's
+ * `percentScaleOf`, the answer the list cell reads too. Until objectui#11475
+ * the shared source guessed the storage from the value's magnitude, so the
+ * table above, whose every row is that guess, no longer describes this
+ * function: a fraction-stored `1` now fills the bar to 100%, and a
+ * whole-stored `0.5` to half a percent.
+ */
+export declare function summaryChipPercentPoints(raw: number, percentScale: PercentScale): number;
+//# sourceMappingURL=summaryChipPercent.d.ts.map

package/dist/summaryChipPercent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summaryChipPercent.d.ts","sourceRoot":"","sources":["../src/summaryChipPercent.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEzE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+EG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,MAAM,CAyBxF"}

package/dist/summaryChipRenderers.d.ts

@@ -0,0 +1,83 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Which field kinds the `summaryFields` chip beside the record H1 may draw
+ * with the field's OWN cell renderer, and which it may not (objectui#8464).
+ *
+ * ## Why this set exists at all
+ *
+ * The chip's display was `String(val)` with four families special-cased, so an
+ * object-valued summary field printed the literal `[object Object]` beside the
+ * H1 — and, because the chip's accessible name is built from that same string,
+ * in its accessible name too. The fix routes such a value through
+ * `getCellRenderer`, the way `HeaderHighlight` one band below already does.
+ *
+ * ⚠️ That route is NOT free, and this set is the measurement that says so. A
+ * Badge is a `whitespace-nowrap rounded-full` pill — a much smaller surface
+ * than a cell — and some registered types draw something a pill cannot host.
+ * Measured, not assumed: every registered type was rendered through
+ * `getCellRenderer` INSIDE the real chip Badge against the object value
+ * `{ id: 'acct-1', name: 'Acme Corp' }`, and the DOM inside the pill counted.
+ * The instrument is `__tests__/summaryChip.badgeFitCensus-8464.test.tsx`,
+ * which re-derives the whole table and fails if this set stops matching it.
+ *
+ * ⛔ The size of that population is deliberately NOT written down here
+ * (objectui#8734, AGENTS.md #9). It used to read "18 of the 53 registered
+ * types" — a figure derived once, re-derived never, and still true on the day
+ * it went stale. The census now takes its population from
+ * `listCellRendererTypes()`, `@object-ui/fields`' live reading of the registry,
+ * so the count lives in the instrument that re-derives it and nowhere else.
+ *
+ * ## The five measured refusals
+ *
+ * | class                         | types                                                  | what the pill got                                     |
+ * |-------------------------------|--------------------------------------------------------|-------------------------------------------------------|
+ * | a pill inside a pill          | `select` `status` `multiselect` `radio` `checkboxes` `tags` | `SelectCellRenderer`'s own `Badge` — one `rounded-full` node nested in the chip's own |
+ * | an avatar composite           | `user`                                                  | TWO `rounded-full` nodes (Radix `Avatar.Root` + `AvatarFallback`) and the initials glued onto the name: `ACAcme Corp` |
+ * | an image and no text          | `image` `avatar` `signature`                            | an `<img>` and `textContent === ''` — a pill with nothing to say, and nothing for the accessible name |
+ * | a "No value" face             | `boolean` `toggle` `datetime` `repeater` (`EmptyValue`), `date` (`formatDate`'s own em-dash, objectui#8581) | the chip is drawn only AFTER `hasCellValue` called the value FILLED; a renderer answering "empty" one band later re-opens exactly the cross-band contradiction objectui#8394 closed |
+ * | an interactive control        | `file` `video` `audio` (objectui#9161)                  | an `<a href>` view/download link per file — a control, and the page-title row hosts text |
+ *
+ * Every other registered type draws plain inline text inside the pill —
+ * `Acme Corp` for
+ * the nameable families, the JSON literal for `location` / `geolocation` /
+ * `address` / `json` / `object` / `composite` / `record` behind objectui#8481's
+ * declared json-literal fence, and the value-independent faces (`password`,
+ * `secret`, `vector`, `grid`).
+ *
+ * ## What the refused kinds get instead — NOT a stringifier written here
+ *
+ * They fall to `coerceToSafeValue`, `@object-ui/fields`' single documented
+ * answer to "what text does a cell draw for a value that is not a string".
+ * objectui#8596 ruled `select` / `status` / `multiselect` / `radio` /
+ * `checkboxes` / `tags` / `user` onto exactly that text for an object value, so
+ * for 7 of these 18 the chip is BYTE-EQUAL to its own cell. ⛔ Nothing here
+ * invents a renderer-side format (AGENTS.md #0.1): every kind lands either on
+ * its own renderer or on the one coercion this repo already had.
+ */
+export declare const CHIP_UNFIT_RENDERER_TYPES: ReadonlySet<string>;
+/**
+ * May the chip draw `rendererType` with the field's own cell renderer?
+ *
+ * Takes the type ALREADY resolved through `resolveCellRendererType`, because
+ * that is the key `getCellRenderer` dispatches on — asking this question of the
+ * authored spelling would answer for a renderer the chip is not about to use.
+ *
+ * ⚠️ **The default is PERMISSIVE, and what makes that safe is the census, not
+ * this function** (objectui#8734). A type absent from
+ * {@link CHIP_UNFIT_RENDERER_TYPES} is admitted, so an UNMEASURED type is
+ * admitted too. Inverting that — unknown ⇒ refused — is not the free repair it
+ * looks like: it would silently downgrade a legitimately-fitting new type to
+ * `coerceToSafeValue`, which is a product decision about the chip and not a
+ * defect. What objectui#8734 closed instead is the way an unknown type used to
+ * arrive: unnoticed. The census reconciles its table against
+ * `listCellRendererTypes()`, so a newly registered type turns CI red and names
+ * itself before it can reach this predicate in a release.
+ */
+export declare function chipTakesCellRenderer(rendererType: string): boolean;
+//# sourceMappingURL=summaryChipRenderers.d.ts.map

package/dist/summaryChipRenderers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"summaryChipRenderers.d.ts","sourceRoot":"","sources":["../src/summaryChipRenderers.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,eAAO,MAAM,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAgCxD,CAAC;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAEnE"}

package/dist/synth/buildDefaultPageSchema.d.ts

@@ -1,4 +1,4 @@
-import { ServiceObject } from '@objectstack/spec/data';
+import { SelectOptionKind, ServiceObject } from '@objectstack/spec/data';
 import { detectStatusField } from '@object-ui/types';
 /** Minimal shape of an object definition we read here. We deliberately
  *  duck-type so this helper has zero hard dependency on a specific
@@ -18,13 +18,30 @@ export interface ObjectDefLike {
     /** Semantic role (ADR-0085): the object's most important fields —
      *  drives the highlight strip (first 4). */
     highlightFields?: string[];
-    /** Name of the field that holds the record's display title (e.g. `name`,
-     *  `subject`). When present we exclude it from the auto-derived highlight
-     *  list to avoid duplicating the page H1. */
+    /**
+     * ACCEPTED BUT NEVER READ — do not "tidy" this away (objectui#7287).
+     *
+     * `primaryField` is a `DetailViewSchema` key (`@object-ui/types` `views.ts`),
+     * and reading it off an OBJECT def is the defect objectui#7287 removed:
+     * `resolveTitleField` now delegates to `@object-ui/core`'s `resolveNameField`
+     * and no code in this module consults this member. No producer can populate
+     * it either — `@objectstack/spec`'s object schema is a `strictObject` that
+     * answers `unrecognized_keys: ['primaryField']`.
+     *
+     * It stays declared because this interface is REACHABLE, which is a
+     * different question from what it describes: `ObjectDefLike` is re-exported
+     * from this package's index and `@object-ui/plugin-detail` is published, so
+     * the member is part of a shipped `.d.ts`. Deleting it narrows a published
+     * type — an external `const d: ObjectDefLike = { primaryField: 'x' }`
+     * compiles today and would stop compiling — and that is a contract change
+     * owed its own card, not a rider on a behaviour fix. Retiring it is a
+     * deliberate act for someone to take on purpose.
+     */
     primaryField?: string;
-    /** Optional section grouping for the details region. */
+    /** Optional section grouping for the details region. The heading rides
+     *  `label` — the one slot `@object-ui/types` declares (objectui#6190). */
     sections?: Array<{
-        title?: string;
+        label?: string;
         columns?: number;
         fields?: any[];
     }>;
@@ -55,7 +72,7 @@ export interface ObjectDefLike {
     fieldGroups?: Array<Partial<NonNullable<ServiceObject['fieldGroups']>[number]>>;
     /**
      * Spec `enable` capability toggles. Only `files` is read here:
-     * `enable.files === true` (opt-in, #2727) makes the synthesizer emit an
+     * `enable.files === true` (opt-in, objectstack-ai/objectstack#2727) makes the synthesizer emit an
      * Attachments tab beside Details/Related (objectstack#4358).
      */
     enable?: {
@@ -82,9 +99,17 @@ export interface ObjectDefFieldLike {
     name?: string;
     label?: string;
     type?: string;
+    /**
+     * The picklist. `kind` is the option's declared lifecycle category
+     * (`SelectOption.kind` in `@objectstack/spec/data`, objectstack#23809):
+     * {@link deriveStages} carries a `won` / `lost` kind onto the derived stage
+     * as its `terminal`, and `record:path` lets any declared kind (`open`
+     * included) win over its spelling heuristic (objectui#12907).
+     */
     options?: Array<{
         value: any;
         label: string;
+        kind?: SelectOptionKind;
     }>;
     /** Declared group membership — matches a `fieldGroups[].key`. */
     group?: string;
@@ -100,9 +125,10 @@ export interface BuildPageOptions {
         value: any;
         label: string;
     }>;
-    /** Override the auto-derived section grouping. */
+    /** Override the auto-derived section grouping. The heading rides `label` —
+     *  the one slot `@object-ui/types` declares (objectui#6190). */
     sections?: Array<{
-        title?: string;
+        label?: string;
         columns?: number;
         fields?: any[];
     }>;
@@ -118,9 +144,13 @@ export interface BuildPageOptions {
      * Opt in to the Reference Rail (aside region with
      * `record:reference_rail`). The rail is OFF by default — it fans out a
      * collection query per related list, which is wasteful on records the
-     * author never intended to summarize. Set `showReferenceRail: true`
-     * (per object via `detail.showReferenceRail`) to surface it; it then
+     * author never intended to summarize. Set `showReferenceRail: true` on
+     * this options object to surface it — that is the only route: ADR-0085
+     * removed the per-object `detail` hints block, so no object definition
+     * can switch the rail on, and a per-page rail is an authored
+     * `record:reference_rail` node in an assigned Page schema. It then
      * emits only when `related` has at least 2 entries.
+     * Pinned by `__tests__/referenceRailRoute-9816.test.ts`.
      */
     showReferenceRail?: boolean;
     /**
@@ -150,7 +180,7 @@ export interface BuildPageOptions {
      *
      * - `objectName` and `relationshipField` are required.
      * - `title` overrides the default child-object label.
-     * - `columns` / `limit` / `icon` are forwarded to the renderer.
+     * - `columns` / `limit` / `icon` / `sort` are forwarded to the renderer.
      */
     related?: Array<{
         title?: string;
@@ -159,6 +189,40 @@ export interface BuildPageOptions {
         columns?: any[];
         limit?: number;
         icon?: string;
+        /**
+         * Row order for this list — the spec `record:related_list.sort` union,
+         * forwarded verbatim onto the synthesized node.
+         *
+         * The host supplies it; this synthesizer neither derives nor overrides it.
+         * `RecordDetailView` fills it from the child object's DEFAULT LIST VIEW
+         * sort (objectui#5795 — ruled direction 1 on objectstack#11345,
+         * maintainer 2026-08-23: inherit the child list view's sort, NO new spec
+         * key), already lowered to the array arm. Omitted → the node carries no
+         * `sort` and the related list falls back to the server's PK order, exactly
+         * as before this key had a producer.
+         */
+        sort?: string | Array<{
+            field: string;
+            order: 'asc' | 'desc';
+        }>;
+        /**
+         * This list's own declared SCOPE — forwarded verbatim onto the synthesized
+         * node's `filter`, the key `record:related_list` has read since
+         * objectstack#7118 (`RelatedList` ANDs it with `{ [relationshipField]:
+         * parentId }`, never substituting for it).
+         *
+         * The host supplies it; this synthesizer neither derives nor merges it.
+         * `RecordDetailView` fills it from the FK field's `relatedListFilter`
+         * (objectui#4664 — the spec key from objectstack#8704 / PR objectstack-ai/objectstack#8955), already
+         * in the canonical Query-DSL `FilterCondition` shape that key declares. The
+         * component-level authored `filter` and this derived one are therefore the
+         * same vocabulary arriving at the same prop, which is the point: one read
+         * site, one lowering, no per-producer dialect.
+         *
+         * Omitted → the node carries no `filter` and the list sends the parent
+         * scope alone, exactly as before this key had a producer.
+         */
+        filter?: Record<string, any> | any[];
         /**
          * `relatedList: 'primary'` — a CORE relationship. Under the default
          * layout this list is promoted to its OWN tab; non-primary lists collapse
@@ -268,24 +332,78 @@ export interface BuildPageOptions {
  * long-standing plugin-detail import path.
  */
 export { detectStatusField };
+/**
+ * The `record:path` terminal a declared option `kind` stands for: `won` and
+ * `lost` are the spec's `stages[].terminal` values verbatim (the vocabulary
+ * objectstack#23809 chose to match), and `open` is no terminal.
+ */
+export declare function stageTerminalOfKind(kind: SelectOptionKind | undefined): 'won' | 'lost' | undefined;
 /**
  * Derive stage values from an object field's `options` (picklist).
+ *
+ * A stage carries `terminal` from its option's declared `kind`
+ * ({@link stageTerminalOfKind}, objectui#12907), so a `won` option is the
+ * path's forward terminus and a `lost` one sits in the separated group
+ * whatever it is called. An option that declares no kind, or `open`, gets no
+ * `terminal` key: the stage shape is the spec's strict `stages[]` row, which
+ * has no way to say "declared open" — `record:path` reads that off the field
+ * itself ({@link declaredStageKinds}).
  */
 export declare function deriveStages(def: ObjectDefLike | undefined, statusField: string | null): Array<{
     value: any;
     label: string;
+    terminal?: 'won' | 'lost';
 }> | null;
 /**
- * Resolve the record's title field — the value the page renders as its H1.
- * Declared role first (`primaryField` / `nameField` / deprecated
- * `displayNameField`), else the first conventional display-field name present
- * on the object. Mirrors `record-details`' titleCandidates so "what the H1
- * shows" and "what the strip skips" can never disagree.
+ * The lifecycle `kind` each option of `statusField` declares, keyed by option
+ * value — only the options that declare one (objectui#12907).
+ *
+ * ⚠️ Package-internal: exported for `renderers/record-path.tsx`, NOT
+ * re-exported from the package entry. `record:path` consults it after a
+ * stage's explicit `terminal` and before its spelling heuristic, because the
+ * spec's strict `stages[]` row can carry `won` / `lost` but not `open`: a
+ * declared `open` on a value spelled `closed_won` has to beat the heuristic
+ * from here. Returns `null` when there is nothing to consult.
+ */
+export declare function declaredStageKinds(def: ObjectDefLike | undefined, statusField: string | null): Map<unknown, SelectOptionKind> | null;
+/**
+ * WHICH FIELD titles this record — the field whose value the page renders as
+ * its H1, in NAME space.
+ *
+ * DELEGATES to `@object-ui/core`'s `resolveNameField`: the ONE shared ADR-0079
+ * ladder (`nameField` -> deprecated `displayNameField` / `NAME_FIELD_KEY` ->
+ * type-aware derivation), the same spelling `getRecordDisplayName` reads to
+ * produce the H1's VALUE and `leadWithNameField` reads to lead a list. It does
+ * not re-implement that ladder. ADR-0079 collapsed ~6 divergent title
+ * resolvers and this module grew one back (objectui#7287); a second ladder
+ * that agrees today diverges again on the next change, which is the whole
+ * history of this defect.
+ *
+ * Two rungs went away with the delegation:
+ *
+ *  - `def.primaryField` — a `DetailViewSchema` key (`@object-ui/types`
+ *    `views.ts`), read here off an OBJECT def and ranked ABOVE the canonical
+ *    `nameField` ADR-0079 Phase 2 made the pointer. No producer can put it
+ *    there: `@objectstack/spec`'s object schema is a `strictObject` that
+ *    answers `unrecognized_keys: ['primaryField']`, and `ObjectSchema.create()`
+ *    throws — which is why objectstack#6326 deleted the identical read from
+ *    two lint rules. A census across both repos found zero object payloads
+ *    carrying it. Same shape as the undeclared `objectDef.titleField` read
+ *    objectui#6531 measured and #6557 removed.
+ *  - the literal `['name','full_name','title','subject','display_name']` walk
+ *    — a NAME match with no type check. `deriveTitleField` ranks those same
+ *    name-ish names first AND rejects non-title types, so a `select` named
+ *    `title` stops being named as the H1 field that the H1 never shows.
+ *
+ * Returns `null` rather than `undefined` for this module's `!== titleField`
+ * filters and app-shell's `?? 'name'` call site.
  */
 export declare function resolveTitleField(def: ObjectDefLike | undefined): string | null;
 /**
  * Pick up to N "highlight" fields by name. Skips the status field
  * (already shown in `record:path`) and obvious junk like id / created_at.
+ * Members of a group gated by `visibleWhen` are never picked
+ * ({@link membersOfGatedFieldGroups}, objectui#12720).
  */
 export declare function deriveHighlightFields(def: ObjectDefLike | undefined, statusField: string | null, max?: number): string[];
 /**
@@ -313,6 +431,40 @@ export declare function buildDefaultActions(_def: ObjectDefLike | undefined, hea
  * two adjacent nodes.
  */
 export declare function buildDefaultHighlights(def: ObjectDefLike | undefined, options?: Pick<BuildPageOptions, 'highlightFields' | 'statusField' | 'stages' | 'hideHighlights' | 'hidePath'>): any[];
+/**
+ * One field group, resolved — the section a `record:details` `{ group }`
+ * reference stands for — plus the group's own ADR-0089 `visibleWhen`
+ * (objectui#11630).
+ *
+ * ⚠️ Package-internal. It is exported from this module for
+ * `renderers/record-details.tsx` and is NOT re-exported from the package entry.
+ * The predicate travels BESIDE the section, never on it: `section` is exactly
+ * what the public {@link deriveFieldGroupDetailSections} returns, so no caller
+ * of the public function can copy a `visibleWhen` onto an enumerated
+ * `record:details` section. `@objectstack/spec`'s `RecordDetailsProps.sections[]`
+ * is strict and refuses that key on parse; the spec's way to gate a section is
+ * to reference the gated group with `{ group }`, which inherits its predicate.
+ */
+export interface FieldGroupDetailEntry {
+    /** The group key. Absent on the trailing ungrouped bucket. */
+    key?: string;
+    /**
+     * The group's `visibleWhen`, verbatim and unevaluated — a bare CEL string or
+     * an Expression envelope, as `deriveFieldGroupLayout` passes it through.
+     * Never present on the ungrouped bucket.
+     */
+    visibleWhen?: unknown;
+    /** The resolved section, in DetailSection's shape. */
+    section: Record<string, any>;
+}
+/**
+ * The derivation behind both {@link deriveFieldGroupDetailSections} and the
+ * `{ group }` references {@link resolveDetailSections} emits — one code path,
+ * so a reference and the section it resolves to cannot disagree.
+ *
+ * Package-internal; see {@link FieldGroupDetailEntry}.
+ */
+export declare function deriveFieldGroupDetailEntries(def: ObjectDefLike | undefined): FieldGroupDetailEntry[] | null;
 /**
  * Derive detail sections from the object's declared `fieldGroups` plus each
  * field's `group` membership. The grouping SEMANTICS (declared order, empty
@@ -328,14 +480,29 @@ export declare function buildDefaultHighlights(def: ObjectDefLike | undefined, o
  * Section fields are emitted as rich descriptors (`{ name, label, type,
  * options }`) so DetailSection renders typed values without re-resolving
  * the object definition.
+ *
+ * ⚠️ This is the RESOLVED form of a group — what `record:details` renders for
+ * a `{ group }` reference — and not a page section to write into a
+ * `record:details` node: the rich `fields` descriptors are refused by
+ * `@objectstack/spec`'s `RecordDetailsProps.sections[].fields` (bare names), and
+ * a group's `visibleWhen` is deliberately not on it. A page references the group
+ * instead, which is what {@link resolveDetailSections} emits (objectui#11630).
  */
 export declare function deriveFieldGroupDetailSections(def: ObjectDefLike | undefined): Array<Record<string, any>> | null;
 /**
  * Resolve the sections for the Details tab body:
  *   1) explicit `options.sections` from the caller (programmatic API —
  *      Studio preview / metadata-admin anchors);
- *   2) else sections derived from the object's `fieldGroups` semantic role;
- *   3) else `undefined` — record:details falls back to its flat layout.
+ *   2) else the object's `fieldGroups` semantic role, as `{ group }`
+ *      references plus the ungrouped bucket's field names
+ *      (`fieldGroupSectionReferences`, objectui#11630);
+ *   3) else `undefined` — a bare `record:details`, which draws the object's
+ *      `highlightFields` (the spec's declared fallback for a node with
+ *      neither `sections` nor `fields`, objectui#12433), and an empty body
+ *      when the object declares none. It does NOT draw every field: a caller
+ *      that wants the running app's default body passes that body's sections
+ *      in (1) — app-shell's `RecordDetailView`, and Studio's page-create seed
+ *      and slotted preview, take them from one derivation (objectui#12442).
  */
 export declare function resolveDetailSections(def: ObjectDefLike | undefined, sections?: BuildPageOptions['sections']): BuildPageOptions['sections'] | undefined;
 /**
@@ -356,7 +523,7 @@ export declare function buildDefaultTabs(def: ObjectDefLike | undefined, options
  */
 export declare function buildDefaultDiscussion(): any;
 /**
- * Sub-builder: the `record:attachments` panel (#2727). Emitted only when the
+ * Sub-builder: the `record:attachments` panel (objectstack-ai/objectstack#2727). Emitted only when the
  * object opts in via `enable.files: true` — the same gate the server enforces
  * on `sys_attachment` rows (403 FILES_DISABLED otherwise).
  */
@@ -366,7 +533,7 @@ export declare function buildDefaultAttachments(): any;
  * page.
  *
  * Shape:
- *   { type:'record', template:'full-width', regions:[ { name:'main',
+ *   { type:'record', template:'default', regions:[ { name:'main',
  *     components: [page:header, record:highlights?, record:path?,
  *     page:tabs, record:discussion?] } ] }
  *   For `enable.files: true` objects the tabs node carries a peer