@object-ui/core 17.6.0 → 18.0.0

package/dist/utils/record-source.js

@@ -0,0 +1,331 @@
+/**
+ * ObjectUI — the shared record-source readers: the ruled three-rung ladder
+ * (`resolveRecordSourceConfig`) and the object-name it resolves to
+ * (`resolveRecordSourceObjectName`)
+ * 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.
+ */
+/**
+ * The object a view block is bound to, resolved ONCE for the whole renderer
+ * (`b041b9c0c`).
+ *
+ * ## The question this answers, and the one it does not
+ *
+ * There are TWO separately-ruled precedence questions about `objectName`, and
+ * they only look like one question when a single reader is asked to answer
+ * both:
+ *
+ *  1. **Which object does this block RESOLVE, at render time, when it carries
+ *     more than one binding?** — the published three-rung record-source ladder
+ *     (`data`, then `staticData`, then `objectName`), declared on both faces of
+ *     the contract (`ObjectMapSchema.objectName` / `ObjectGanttSchema.objectName`
+ *     in `@object-ui/types`, and the `.describe` on their zod twins — the map
+ *     twin's reads *"objectName — the THIRD record source `getDataConfig`
+ *     resolves, after `data` and `staticData`"*, naming `ObjectMap.tsx`'s local
+ *     wrapper; the gantt twin names `resolveRecordSourceConfig` itself), ruled
+ *     2026-09-02 (landed as `77cb489b4`) and pinned by
+ *     `objectql-record-source-refinement-6939.test.ts`. **That is this
+ *     function.**
+ *  2. **How does `objectName` get POPULATED when it is absent?** — the
+ *     authoring-time gap-fill in `normalizeListViewSchema` (objectui#7477,
+ *     ruling B, landed as `00d2fa682`), where an `objectName` already on the schema WINS
+ *     and the `data` block only fills a gap: *"it can never re-point a binding
+ *     that already resolves."*
+ *
+ * The two are NOT merged and neither is re-pointed at the other. Merging them
+ * would override a standing maintainer ruling in whichever direction the merged
+ * reader happened to pick: at the sites below the binding that already resolves
+ * IS `data.object`, so ruling B's own words argue for keeping rung 1 as it is.
+ *
+ * ## Why `staticData` does not appear here
+ *
+ * The ladder's second rung wraps inline rows as `{ provider: 'value', items }`,
+ * which names no object at all. So for the object-NAME question the three-rung
+ * ladder reduces to two rungs — the resolved config's object when it names one,
+ * else the schema's own `objectName`, which is what a `value`-backed block
+ * still needs for metadata reads, i18n field labels and permission verdicts.
+ * Callers pass the ALREADY-RESOLVED config (their
+ * {@link resolveRecordSourceConfig} output, direct or through a local wrapper),
+ * so rung ordering is settled before this function is reached.
+ *
+ * ## No lenient rung was added (AGENTS.md #0.1)
+ *
+ * `ViewDataSchema`'s `object` provider is a `strictObject` carrying exactly
+ * `{ provider, object }` with `object` REQUIRED, so `{ provider: 'object' }`
+ * without an `object` is off-contract. This reader does not coerce that shape
+ * back to `objectName`; the two call sites that used to (`ObjectGrid`'s
+ * `'object' in dataConfig` test and `ObjectTree`'s header `?? schema.objectName`
+ * tail) keep their own tail at the site, so the collapse changes nothing they
+ * resolve today while the shared rung stays contract-strict.
+ *
+ * @param schema - The block's schema; only `objectName` is read.
+ * @param dataConfig - The RESOLVED data config — the caller's own
+ *   {@link resolveRecordSourceConfig} output, `null` when nothing is bound.
+ * @returns The bound object's name, or `undefined` when neither the resolved
+ *   config nor the schema names one.
+ *
+ * @example
+ * ```ts
+ * const dataConfig = useMemo(() => resolveRecordSourceConfig(schema, 'view-data'), [schema]);
+ * const objectName = resolveRecordSourceObjectName(schema, dataConfig);
+ * ```
+ */
+export function resolveRecordSourceObjectName(schema, dataConfig) {
+    return dataConfig?.provider === 'object' ? dataConfig.object : schema?.objectName;
+}
+/**
+ * Does the authored `data` match the arm this block's published row declares?
+ *
+ * Falsy `data` is never a record source — the pre-8348 `if (schema.data)`
+ * truthiness test, kept, so `data: null` and `data: undefined` still fall
+ * through to `staticData`.
+ */
+function authoredDataIsOnTheDeclaredArm(authored, arm) {
+    if (!authored)
+        return false;
+    if (arm === 'array')
+        return Array.isArray(authored);
+    if (arm === 'view-data')
+        return !Array.isArray(authored);
+    return true;
+}
+/**
+ * The block's record source, resolved from the ruled three-rung ladder
+ * (`ce2aaefe1`), with rung 1 judged against the block's own published `data`
+ * row (objectui#8348).
+ *
+ * ## The ruled contract this is the ONE implementation of
+ *
+ * `data`, then `staticData`, then `objectName` — declared on both faces of the
+ * published contract and pinned by
+ * `objectql-record-source-refinement-6939.test.ts`. Quoted here from the
+ * `ObjectMapSchema` faces, whose `getDataConfig` is `ObjectMap.tsx`'s local
+ * wrapper around this function; the gantt and calendar faces name
+ * `resolveRecordSourceConfig` instead (objectui#9618):
+ *
+ *  1. **`data`** — *"Data source configuration. Read FIRST by `getDataConfig`"*,
+ *     honoured ONLY on the arm `dataArm` names. Returned verbatim, so a config
+ *     on the declared arm reaches the caller exactly as the author wrote it.
+ *  2. **`staticData`** — *"Inline records — read SECOND by `getDataConfig`,
+ *     wrapped into a `{ provider: value }` config"*.
+ *  3. **`objectName`** — *"the THIRD record source `getDataConfig` resolves,
+ *     after `data` and `staticData`"*, folded to `{ provider: 'object' }`.
+ *
+ * `null` when none of the three is present — the same "nothing is drawn" signal
+ * the zod `requireRecordSource` refinement is written against.
+ *
+ * This is the PRODUCER whose output {@link resolveRecordSourceObjectName} (the
+ * reader `b041b9c0c` published) consumes; that function's docblock describes the same
+ * ladder from the consuming end. Five plugins — calendar, gantt, grid, map and
+ * tree — each carried a hand-copy of this ladder with no gate holding them
+ * together, which is the AGENTS.md #0.1 drift class: a change to the ruled
+ * order had five edit sites and nothing noticed a missed one.
+ *
+ * ## Rung 1 is judged against the block's own row (objectui#8348)
+ *
+ * ⛔ This docblock used to state, as a fact about the whole ladder, that *"an
+ * array under `data` cannot be published"*. That is true of the blocks whose row
+ * is `ViewData` and FALSE of `object-calendar`, whose published row
+ * (`ComponentPropsMap['object-calendar'].data` on `@objectstack/spec` 17.4.0) is
+ * `z.array(z.unknown()).optional()` — *"Pre-fetched records — skips the internal
+ * fetch"*. Both directions of that disagreement were live at once: the renderers
+ * honoured the `{ provider, items }` object on a block whose row refuses it by
+ * kind, and `ObjectGrid` / `ObjectMap` lifted a bare array on blocks whose row
+ * refuses THAT by kind. Decision batch #83 settled it — the row decides — and
+ * `dataArm` is where each block says which row it has.
+ *
+ * JUDGED, per block, against that block's `ComponentPropsMap` row in the
+ * INSTALLED `@objectstack/spec` — and ⛔ the verdicts are not written down here
+ * as facts, because a spec release can move a row (AGENTS.md #9). Each pin
+ * below derives the arm from the row at test time and compares it with what the
+ * block passes, so a moved row turns it red:
+ *
+ *  - `object-grid` — `'view-data'`; `gridBareArrayDataRefused-8348.test.tsx`,
+ *    its "the spec row is what all of the above is judged against" test. The
+ *    row's own description names the refusal: *"the bare-array shortcut is
+ *    refused — see migration `object-grid-data-view-data-converged`"*.
+ *  - `object-calendar` — `'array'`; the test of the same name in
+ *    `ObjectCalendar.dataObjectArmRefused-8348.test.tsx`. The registration
+ *    publishes the same arm (`{ name: 'data', type: 'array' }`).
+ *  - `object-map`, `object-gantt`, `object-tree` — `'view-data'`; one
+ *    `dataArmSpecRow-8348` pin per block, in each plugin's own tests. These
+ *    three rows are what ruling batch #136 item 3 (Q1-C) had the protocol
+ *    gain; until they were installable, map and gantt were judged through this
+ *    repo's own `ObjectMapSchema.data` / `ObjectGanttSchema.data` and tree
+ *    passed `'undeclared'`. The tree's row declares `data`, so the ruling's
+ *    「协议没有的能力删」 clause did not fire for it: it keeps the object arm and
+ *    loses only the bare-array spelling. Its `staticData` rung is declared by
+ *    the same row and is unchanged.
+ *
+ * ## The DECLARATION follows the arm too (`ab856ed30`)
+ *
+ * The `data` member below is {@link AuthoredRecordSourceData}`<Arm>`, not a flat
+ * `ViewData`: the arm decides what a site may DECLARE exactly as it decides
+ * what rung 1 HONOURS. Read that type's docblock for why it is arm-indexed
+ * rather than a union of the arms, and for the reading that says nothing at
+ * runtime moved.
+ *
+ * ## No lenient rung was added (AGENTS.md #0.1)
+ *
+ * **Null tolerance** stays out: all five copies dereference `schema` unguarded
+ * and would throw on `null`; no site passes one, so no `?.` was added.
+ *
+ * `ObjectCalendar`'s copy guarded with `'data' in schema && schema.data`. That
+ * `in` test was a TYPESCRIPT narrowing device, not a behavioural one: when the
+ * property is absent the read yields `undefined`, which is falsy either way, so
+ * the guard could never change which rung is taken. The optional-property
+ * parameter below admits a schema that declares neither key directly, which is
+ * why the guard is gone rather than flattened away. The equivalence itself is
+ * pinned, not argued, by `CALENDAR_IN_GUARD` in
+ * `record-source-config.behaviourNeutrality-7632.test.ts`.
+ *
+ * ⛔ This passage used to explain that guard by the PROPS UNION the calendar
+ * plugin once carried — `ObjectGridSchema | CalendarSchema`, whose second
+ * member declared neither `data` nor `staticData`. objectui#8651 RETIRED that
+ * union (`ObjectCalendarComponentProps.schema` is the published
+ * `ObjectCalendarSchema` today), so the sentence explained the guard by a type
+ * no reader could look up. Rewritten rather than deleted: the guard's history
+ * is still why this parameter's members are optional.
+ *
+ * @param schema - The block's schema; only `data`, `staticData` and
+ *   `objectName` are read. Its `data` member is typed by the arm — see
+ *   {@link AuthoredRecordSourceData}.
+ * @param dataArm - The arm the CALLING BLOCK's published `data` row declares.
+ *   Required: there is no repo-wide default, because the answer differs per
+ *   block and a default is how the second de-facto contract got in.
+ * @returns The resolved data config, or `null` when nothing is bound.
+ *
+ * @example
+ * ```ts
+ * const dataConfig = useMemo(() => resolveRecordSourceConfig(schema, 'view-data'), [schema]);
+ * const objectName = resolveRecordSourceObjectName(schema, dataConfig);
+ * ```
+ */
+export function resolveRecordSourceConfig(schema, dataArm) {
+    if (authoredDataIsOnTheDeclaredArm(schema.data, dataArm)) {
+        return schema.data;
+    }
+    if (schema.staticData) {
+        return {
+            provider: 'value',
+            items: schema.staticData,
+        };
+    }
+    if (schema.objectName) {
+        return {
+            provider: 'object',
+            object: schema.objectName,
+        };
+    }
+    return null;
+}
+/**
+ * The arm each REGISTERED BLOCK TYPE declares — the one reading available to a
+ * caller that cannot be handed the arm as a parameter (objectui#9571).
+ *
+ * ## Why a type-keyed table exists beside the REQUIRED parameter
+ *
+ * {@link RecordSourceDataArm}'s docblock states, correctly, why
+ * {@link resolveRecordSourceConfig} takes the arm as a required PARAMETER: most
+ * of these renderers are registered under two spellings, a node reaches the same
+ * component under either, and a table keyed by `type` would answer for one tag
+ * and silently miss the other. That argument is about a call site that already
+ * has one block in front of it — there a parameter is strictly better, and it
+ * stays exactly as it is.
+ *
+ * `SchemaRenderer` is the one reader that has no such site. It is generic over
+ * every registered type and holds nothing but `schema.type`, and ruling
+ * objectui#8348 Q2-C (decision batch #136 item 3, maintainer 「同意」) makes it a
+ * reader anyway: it must stop spreading an authored `data` key as a React prop
+ * for blocks whose published row is the OBJECT arm, because that prop is the
+ * carrier the 「8348 以协议为准」 ruling did not otherwise reach. So "which arm
+ * does this TYPE declare" has to be askable, and this is the ONE place that
+ * answers it.
+ *
+ * ## The alias hazard is closed by ENUMERATION plus a registry-derived pin
+ *
+ * Every registered spelling is listed, and the listing is pinned per plugin
+ * AGAINST THE REGISTRY rather than against itself: each affected plugin's pin
+ * walks the keys its own `index.tsx` actually produced, groups them by the
+ * renderer they resolve to, and requires every member of a group to get the
+ * same answer here. An alias added without a row goes red there instead of
+ * quietly answering `'undeclared'` and keeping the prop seat.
+ *
+ * ⚠️ ONE `register()` CALL PRODUCES SEVERAL KEYS, and a row must be written for
+ * each of them — `SchemaRenderer` looks this table up with the raw
+ * `schema.type`, which is whatever spelling the author wrote. A registration
+ * with `namespace: 'view'` is reachable as `view:calendar` AND as bare `calendar`; one
+ * with `skipFallback` is reachable ONLY under its namespaced key. MEASURED via
+ * `ComponentRegistry.getAllTypes()` with the five plugins loaded, grouped by
+ * the renderer each key resolves to.
+ *
+ * ⛔ `grid` IS NOT A GRID KEY, and this is the trap the registry-derived pin
+ * caught on its first run. `plugin-grid` registers its `view` alias with
+ * `skipFallback: true` precisely so the bare key stays with
+ * `@object-ui/components`' LAYOUT grid container (`ui:grid`) — so `object-grid`
+ * resolves to `view:grid`, never to `grid`. A row for `grid` here would strip
+ * `data` from a layout container, which declares no `data` row at all.
+ *
+ * ## The rows are the call sites' literals — ⛔ not a second measurement
+ *
+ * Each value below is the literal its block already passes to
+ * {@link resolveRecordSourceConfig}, and each of those literals carries its own
+ * per-block measurement in a comment at that call site. ⛔ Do not re-derive the
+ * arm here and ⛔ do not let the two disagree: this table transports an answer,
+ * it does not compute one.
+ *
+ *  - `ObjectGrid.tsx`'s `getDataConfig` — `'view-data'`.
+ *  - `ObjectMap.tsx`'s `getDataConfig` — `'view-data'`. One block spelling
+ *    only: the bare `map` key (and with it `view:map`) is retired
+ *    (objectui#10393).
+ *  - `ObjectGantt.tsx`'s `rawDataConfig` — `'view-data'`. One block spelling
+ *    only: the bare `gantt` key is retired (objectui#8008).
+ *  - `ObjectCalendar.tsx`'s `dataConfig` — `'array'`.
+ *  - `ObjectTree.tsx`'s `dataConfig` — `'view-data'`. One block spelling only
+ *    (`object-tree` under the `plugin-tree` namespace): the bare `tree` key
+ *    (and with it `view:tree`) is retired (objectui#10859 batch 8). These rows
+ *    used to read `'undeclared'` and were only
+ *    documentary, because no published face declared a `data` row for the
+ *    block; `ComponentPropsMap['object-tree']` now does (objectui#8348, ruling
+ *    batch #136 item 3, Q1-C), so they DECIDE: an authored `data` on a tree
+ *    node no longer takes a prop seat either. The registry-derived pin is
+ *    `ObjectTree.dataArmSpecRow-8348.test.tsx`.
+ */
+const RECORD_SOURCE_DATA_ARM_BY_TYPE = Object.freeze({
+    // — object arm: `ViewData`, a bare array under `data` is off the row —
+    'object-grid': 'view-data',
+    'plugin-grid:object-grid': 'view-data',
+    'view:grid': 'view-data',
+    'object-map': 'view-data',
+    'plugin-map:object-map': 'view-data',
+    'object-gantt': 'view-data',
+    'plugin-gantt:object-gantt': 'view-data',
+    'object-tree': 'view-data',
+    'plugin-tree:object-tree': 'view-data',
+    // — array arm: `z.array(...)`, pre-fetched records —
+    'object-calendar': 'array',
+    'plugin-calendar:object-calendar': 'array',
+    'view:calendar': 'array',
+    calendar: 'array',
+});
+/**
+ * Which `data` arm the block registered under `type` declares.
+ *
+ * `'undeclared'` for every type not listed above — the same verdict the ladder
+ * gives a block no published face declares a `data` row for, and the same
+ * behaviour those types have today. That default is deliberately the
+ * NO-CHANGE direction: a caller acting on this reading (today:
+ * `SchemaRenderer`'s props spread) leaves an unlisted type exactly as it was,
+ * so a block that has never been measured is never silently re-decided by this
+ * table's mere existence.
+ *
+ * @param type - The node's registry key, either spelling.
+ * @returns The arm that type's published `data` row declares.
+ */
+export function recordSourceDataArmForType(type) {
+    if (typeof type !== 'string')
+        return 'undeclared';
+    return RECORD_SOURCE_DATA_ARM_BY_TYPE[type] ?? 'undeclared';
+}

package/dist/utils/record-title.d.ts

@@ -15,10 +15,20 @@
  * supported. Dotted paths (`{account.name}`) walk `$expanded` lookup objects; a
  * placeholder that resolves to a whole object is reduced to its display name.
  *
- * Empty placeholders (missing / null / empty fields) are stripped along with
- * any orphan separator they leave behind, so `"{full_name} - {company}"`
- * evaluated against `{ company: "Acme" }` yields `"Acme"`, not `" - Acme"`.
- * Returns an empty string when no placeholder resolved.
+ * Empty placeholders (missing / null / empty / whitespace-only fields) are
+ * stripped along with any orphan separator they leave behind, so
+ * `"{full_name} - {company}"` evaluated against `{ company: "Acme" }` yields
+ * `"Acme"`, not `" - Acme"`. Returns an empty string when no placeholder
+ * resolved.
+ *
+ * What counts as "empty" is not decided here (objectui#10446). Each
+ * placeholder's value goes through {@link displayValueOf}, the body of
+ * {@link recordDisplayValueAt}: trim, then empty. This function used to test
+ * the raw value against `null` / `undefined` / `''` on its own, so a
+ * whitespace-only value counted as RESOLVED. The later whitespace collapse
+ * then left its separator dangling: `{contract_no} - {name}` with a blank
+ * `name` rendered `HT-2026-003 -`, while every value-keyed rung of
+ * {@link getRecordDisplayName} judged the same value empty.
  */
 export declare function formatTitleTemplate(titleFormat: string | {
     source?: string;
@@ -49,6 +59,135 @@ export declare function isTitleEligibleField(def: any): boolean;
  * when `objectDef` is a non-null object (the WeakMap key requirement).
  */
 export declare function deriveTitleField(objectDef: any): string | undefined;
+/**
+ * The declared name-field pointer, read exactly as {@link getRecordDisplayName}
+ * reads it: the canonical `nameField` (ADR-0079 Phase 2), then its deprecated
+ * `displayNameField` / `NAME_FIELD_KEY` aliases.
+ *
+ * One spelling, every reader. Inside this module that is the value-space
+ * resolver and the name-space {@link resolveNameField}. Re-typing the `??`
+ * chain at another reader is how two readers drift into disagreeing about
+ * which field titles an object. No new alias is read here; this is the
+ * existing ladder, extracted.
+ *
+ * Exported (objectui#9436) for callers that must rank the DECLARED pointer on
+ * its own, apart from the type-aware derivation that {@link resolveNameField}
+ * folds in after it. The record-page H1 needs exactly that: ADR-0079 puts the
+ * declared pointer (steps 1+2) above the legacy `titleFormat` (step 3), and the
+ * derivation (step 4) below it, so a caller that interleaves its own
+ * `titleFormat` rendering has to read the two halves separately. Read the value
+ * as `recordDisplayValueAt(record, declaredNameField(objectDef))`, which is how
+ * {@link getRecordDisplayName} reads steps 1+2.
+ *
+ * Returns the pointer exactly as declared, or `undefined` when none is. It
+ * never derives: an object that declares nothing answers `undefined` even when
+ * its `fields` would derive a title field.
+ */
+export declare function declaredNameField(objectDef: any): any;
+/**
+ * WHICH FIELD titles this object — the name-space twin of
+ * {@link getRecordDisplayName}, which answers what that field SAYS on one
+ * record. Same ladder, minus the rungs that only exist per record:
+ *
+ *   1+2. the declared pointer ({@link declaredNameField});
+ *   4.   else the type-aware derivation ({@link deriveTitleField}).
+ *
+ * The two omissions are deliberate, not oversights. `options.titleField`
+ * (step 0) belongs to one view, not to the object. `titleFormat` (step 3) is a
+ * render-only template, not a field name — there is no column, no sort key and
+ * no `$select` entry to be had from it, which is the same reason ADR-0079
+ * demoted it. A caller that wants a title for a `titleFormat`-only object wants
+ * {@link getRecordDisplayName}, per record.
+ *
+ * Deliberately does NOT require the answer to exist in `objectDef.fields`: in
+ * value-space the declared pointer is read off the RECORD, so demanding a field
+ * def here would make the two resolvers disagree. A caller that needs a
+ * RENDERABLE column checks presence itself — see {@link leadWithNameField}.
+ *
+ * Returns `undefined` when nothing declares or derives a name field.
+ */
+export declare function resolveNameField(objectDef: any): string | undefined;
+/**
+ * Put the object's name field at the FRONT of a **synthesized** default column
+ * list, so a list no author ever configured still lets you tell its rows apart.
+ *
+ * Why this exists (objectui#7245): the three faces that synthesize default list
+ * columns each took a declared `highlightFields` verbatim. `highlightFields` is
+ * the ADR-0085 "most important fields" role, and its canonical consumer — the
+ * detail-page highlight strip — deliberately *excludes* the title field,
+ * because the strip sits directly under the page H1 that already shows it. So
+ * well-authored metadata routinely omits the name from `highlightFields`: the
+ * showcase `showcase_account` declares `["status", "industry", "annual_revenue"]`
+ * against `nameField: "name"`, and its default grid rendered 14 rows with no
+ * name column and nothing to distinguish them.
+ *
+ * A list has no H1 to lean on, so the same role needs the opposite treatment
+ * here. This is not a new convention: `deriveLookupColumns` in `@object-ui/fields`
+ * already leads its picker columns with the display field and filters it out of
+ * the declared list — the record-picker equivalent of this problem, solved the
+ * same way. This makes the list faces agree with it.
+ *
+ * MOVES the name field rather than only prepending a missing one: an author who
+ * lists it third still gets it first, which is what "the column that identifies
+ * the row" means. Order among the remaining columns is untouched.
+ *
+ * NOT for author-declared column lists. A view that declares `columns` said what
+ * it wants; overriding that would be exactly the renderer-side second-guessing
+ * AGENTS.md Commandment #0.1 rules out. Every caller passes a list it
+ * synthesized itself.
+ *
+ * Three cases return `columns` untouched, each guarding a rule that already
+ * governs these column lists:
+ *
+ *  - **No field def** (nothing resolved, or the pointer names a field the object
+ *    does not carry) — a synthesized list must never fabricate a column the
+ *    object cannot render.
+ *  - **`hidden: true`** — the author said don't show this field. That outranks
+ *    the fact that it also titles the record; every one of these faces already
+ *    drops hidden fields from its own walk.
+ *  - **DERIVED onto a system-managed field.** {@link deriveTitleField} filters
+ *    by TYPE only, so on an object with no name-ish business field it can land
+ *    on a framework-injected column — and leading a default list with a raw id
+ *    is precisely the regression objectui#2702 / #2777 fixed. A *declared*
+ *    `nameField` is exempt: `sys_migration` really does point at `id`, and an
+ *    author's explicit designation is not a heuristic misfire.
+ */
+export declare function leadWithNameField(objectDef: any, columns: string[]): string[];
+/**
+ * Read a non-empty string-ish display value off a record at `field`, else
+ * `undefined`.
+ *
+ * THE definition of "this record has a value here" — the question every
+ * value-keyed rung of {@link getRecordDisplayName} asks, and the reason a
+ * whitespace-only field is not a title.
+ *
+ * ## Why this is exported (objectui#8350)
+ *
+ * A second reader existed. `record:details`' dedupe ladder in
+ * `@object-ui/plugin-detail` asks the same question about the same record for
+ * the same field, to decide which body-grid row duplicates the page H1 — and it
+ * asked it with a hand-written raw `undefined` / `null` / `''` test, which a
+ * whitespace-only value passes and this one does not. So for a record whose
+ * title field held only spaces the two halves disagreed about whether that
+ * field had a value at all: the H1 walked on to the next rung, while the grid
+ * hid the row anyway — a field vanished to deduplicate against a heading that
+ * never showed it. The ladder now calls THIS. One authority, not two
+ * implementations that agree today.
+ *
+ * ⛔ Do not re-spell this test at a call site, and do not "just add a trim"
+ * there: three things beyond the trim are part of the definition, and a second
+ * implementation drifts on each of them independently —
+ *   - an expanded/embedded reference object resolves through its Salesforce-
+ *     style display chain and is EMPTY when that yields nothing (a bare
+ *     `{ id }` lookup payload is not a title);
+ *   - non-strings are stringified, so `0` and `false` ARE values, not blanks;
+ *   - `null` and `undefined` are empty, and only those two.
+ *
+ * The rule itself is {@link displayValueOf}, which {@link formatTitleTemplate}
+ * applies to each placeholder value (objectui#10446). So a `titleFormat`
+ * placeholder is empty exactly when this function would call its field empty.
+ */
+export declare function recordDisplayValueAt(record: any, field: string | undefined): string | undefined;
 export interface RecordDisplayNameOptions {
     /**
      * Optional explicit title field (e.g. a view's `titleField` / gallery
@@ -61,7 +200,7 @@ export interface RecordDisplayNameOptions {
     fallback?: string;
     /**
      * Whether to probe standard name-ish keys (`name`/`title`/…) directly on the
-     * record when `objectDef.fields` is absent (precedence step 3b). Defaults to
+     * record when `objectDef.fields` is absent (precedence step 4b). Defaults to
      * `true`. Callers that have a better generic fallback to interleave (e.g. the
      * detail header prefers `schema.title`, the object label, over a guessed
      * record key) pass `false` so this step is skipped and the resolver returns
@@ -74,9 +213,10 @@ export interface RecordDisplayNameOptions {
  *
  * Precedence (ADR-0079 Phase 2 makes the object's declared field canonical and
  * de-prioritizes the legacy `titleFormat` template):
- *   0. `options.titleField`, then `objectDef.titleField` (when provided &
- *      non-empty on the record) — lets a view / object keep its author-chosen
- *      title field.
+ *   0. `options.titleField` (when provided & non-empty on the record) — lets
+ *      a view keep its author-chosen title field. The object-level
+ *      `objectDef.titleField` leg was removed in objectui#6531: the spec's
+ *      object schema rejects that key, so nothing could produce it.
  *   1. `objectDef.nameField` — the NEW canonical record-title pointer
  *      (ADR-0079). A field name the server can return and query.
  *   2. `objectDef.displayNameField` / `objectDef.NAME_FIELD_KEY` — the