@object-ui/core 17.5.0 → 17.7.0

package/dist/utils/record-title.js

@@ -22,8 +22,12 @@
  * (`nameField`) to canonical and de-prioritizes the legacy render-only
  * `titleFormat` template:
  *
+ *   0. `options.titleField` — the caller's own DECLARED view-level pointer
+ *      (gallery / calendar / gantt / map / kanban / timeline config).
  *   1. `objectDef.nameField` — the canonical record-title pointer (ADR-0079);
- *      a field the server can return and query, if present & non-empty.
+ *      a field the server can return and query, if present & non-empty. With
+ *      the undeclared `objectDef.titleField` read gone (objectui#6531) this is
+ *      the top of the OBJECT-level ladder, exactly as ADR-0079 states.
  *   2. `objectDef.displayNameField` (alias `NAME_FIELD_KEY`) — deprecated alias
  *      of `nameField`, kept for back-compat.
  *   3. `objectDef.titleFormat` — LEGACY render-only template, rendered via
@@ -38,6 +42,7 @@
  * app-shell, the field widgets, and every view plugin — exactly like
  * `percentDisplayValue` / `formatMeasure`.
  */
+import { isSystemManagedField } from '@object-ui/types';
 // Sentinel marking an empty-placeholder position inside a titleFormat render,
 // so adjacent separators can be stripped in a second pass.
 //
@@ -138,10 +143,20 @@ function displayNameOfEmbeddedObject(o) {
  * 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 function formatTitleTemplate(titleFormat, record) {
     let template = typeof titleFormat === 'string'
@@ -163,14 +178,11 @@ export function formatTitleTemplate(titleFormat, record) {
                 break;
             value = value[p];
         }
-        if (value && typeof value === 'object') {
-            value = displayNameOfEmbeddedObject(value);
-        }
-        if (value === null || value === undefined || value === '') {
+        const shown = displayValueOf(value);
+        if (shown === undefined)
             return EMPTY_TOKEN;
-        }
         anyResolved = true;
-        return String(value);
+        return shown;
     });
     if (!anyResolved)
         return '';
@@ -283,13 +295,132 @@ export function deriveTitleField(objectDef) {
     deriveTitleFieldCache.set(objectDef, derived);
     return derived;
 }
+/**
+ * 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 function declaredNameField(objectDef) {
+    return objectDef?.nameField ?? objectDef?.displayNameField ?? objectDef?.NAME_FIELD_KEY;
+}
+/**
+ * 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 function resolveNameField(objectDef) {
+    const declared = declaredNameField(objectDef);
+    if (typeof declared === 'string' && declared.length > 0)
+        return declared;
+    return deriveTitleField(objectDef);
+}
+/**
+ * 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 function leadWithNameField(objectDef, columns) {
+    const declared = declaredNameField(objectDef);
+    const isDeclared = typeof declared === 'string' && declared.length > 0;
+    const lead = isDeclared ? declared : deriveTitleField(objectDef);
+    const def = lead ? objectDef?.fields?.[lead] : undefined;
+    if (!lead || !def)
+        return columns;
+    if (def.hidden)
+        return columns;
+    if (!isDeclared && isSystemManagedField(lead, def))
+        return columns;
+    return [lead, ...columns.filter((c) => c !== lead)];
+}
 /**
  * Standard name-ish keys probed directly on a *record* as a last resort before
  * the `Record #<id>` floor — used when `objectDef.fields` is absent so
- * {@link deriveTitleField} can't run (loosely-typed metadata, lightweight search
- * candidates that carry only `name`/`titleField`, etc.). Mirrors the historical
+ * {@link deriveTitleField} can't run (loosely-typed metadata, the lightweight
+ * object stub `useRecordSearch` synthesizes for a hit whose object is not in
+ * the app's metadata — `{ name: objectName }` — etc.). Mirrors the historical
  * hard-coded fallback chain the divergent resolvers used, so removing them is
  * non-regressive. Ordered by priority.
+ *
+ * objectui#6531 rewrote the parenthetical above: it used to say those search
+ * candidates "carry only `name`/`titleField`", which read as evidence that some
+ * producer puts `titleField` on an object-shaped payload. The census found
+ * none, and the spec's object schema rejects the key outright.
  */
 const NAME_ISH_RECORD_KEYS = [
     'name',
@@ -301,11 +432,57 @@ const NAME_ISH_RECORD_KEYS = [
     'subject',
     'label',
 ];
-/** Read a non-empty string-ish value off a record at `field`, else undefined. */
-function valueAt(record, field) {
+/**
+ * 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 function recordDisplayValueAt(record, field) {
     if (!field || !record || typeof record !== 'object')
         return undefined;
-    let v = record[field];
+    return displayValueOf(record[field]);
+}
+/**
+ * The value half of {@link recordDisplayValueAt}: one already-read value in,
+ * its display string or `undefined` (empty) out. Trim, then empty.
+ *
+ * Module-private on purpose. It exists so the two readers in this file that
+ * judge a single value, `recordDisplayValueAt` and each placeholder of
+ * {@link formatTitleTemplate}, run ONE implementation of that judgement rather
+ * than two that agree today (objectui#10446). Read its full definition on
+ * {@link recordDisplayValueAt}.
+ */
+function displayValueOf(value) {
+    let v = value;
     if (v && typeof v === 'object')
         v = displayNameOfEmbeddedObject(v);
     if (v === null || v === undefined)
@@ -318,9 +495,10 @@ function valueAt(record, field) {
  *
  * 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
@@ -340,9 +518,23 @@ function valueAt(record, field) {
  * @param record    The record data.
  */
 export function getRecordDisplayName(objectDef, record, options) {
-    // 0. Explicit title field — caller option first, then the object's own
-    //    `titleField` hint — if it actually resolves on the record.
-    const explicit = valueAt(record, options?.titleField) ?? valueAt(record, objectDef?.titleField);
+    // 0. Explicit title field — the caller's option, if it actually resolves on
+    //    the record. This is a DECLARED key: every view config that offers a
+    //    title pointer (`ui/CalendarConfig`, `ui/GalleryConfig`, `ui/GanttConfig`,
+    //    `ui/ListMapConfig`, `ui/ObjectKanbanProps`, `ui/TimelineConfig`) declares
+    //    `titleField`, and its author chose it for THIS view, so it outranks the
+    //    object's own pointer by design.
+    //
+    //    An object-level `objectDef.titleField` used to be consulted here too, as
+    //    a second `??` leg. Removed in objectui#6531: `@objectstack/spec`'s object
+    //    schema is a `strictObject` that REJECTS `titleField` with
+    //    `unrecognized_keys` — the same code a nonsense key gets — so no
+    //    spec-compliant producer can ship it, and a census across both repos
+    //    (metadata, every `getObjectSchema` implementation, the lookup-chip and
+    //    search-candidate paths) found none that does. Reading it was a
+    //    consumer-side alias for an undeclared key (AGENTS.md Commandment #0.1),
+    //    ranked ABOVE the `nameField` ADR-0079 Phase 2 made canonical.
+    const explicit = recordDisplayValueAt(record, options?.titleField);
     if (explicit)
         return explicit;
     // 1+2. Declared name field — the canonical `nameField` (ADR-0079 Phase 2),
@@ -350,7 +542,9 @@ export function getRecordDisplayName(objectDef, record, options) {
     //      explicitly-declared field now wins over the legacy `titleFormat`
     //      template (step 3): an object that sets `nameField` resolves via it even
     //      if it also carries a stale `titleFormat`.
-    const declared = valueAt(record, objectDef?.nameField ?? objectDef?.displayNameField ?? objectDef?.NAME_FIELD_KEY);
+    //      The `??` chain itself lives in {@link declaredNameField} so the
+    //      name-space {@link resolveNameField} reads the identical ladder.
+    const declared = recordDisplayValueAt(record, declaredNameField(objectDef));
     if (declared)
         return declared;
     // 3. titleFormat (LEGACY, render-only template). DEPRECATED by ADR-0079: the
@@ -366,7 +560,7 @@ export function getRecordDisplayName(objectDef, record, options) {
     }
     // 4. Type-aware derivation from the object's fields.
     const derivedField = deriveTitleField(objectDef);
-    const derived = valueAt(record, derivedField);
+    const derived = recordDisplayValueAt(record, derivedField);
     if (derived)
         return derived;
     // 4b. Name-ish keys on the record itself — the safety net for when the
@@ -377,7 +571,7 @@ export function getRecordDisplayName(objectDef, record, options) {
     if (options?.deriveFromRecordKeys !== false && record && typeof record === 'object') {
         // (i) exact standard keys (name, full_name, title, …).
         for (const key of NAME_ISH_RECORD_KEYS) {
-            const v = valueAt(record, key);
+            const v = recordDisplayValueAt(record, key);
             if (v)
                 return v;
         }
@@ -392,7 +586,7 @@ export function getRecordDisplayName(objectDef, record, options) {
             if (k === 'id' || k === '_id' || k.endsWith('_id') || k.startsWith('_'))
                 continue;
             if (k.endsWith('_name') || k.endsWith('_title') || k.startsWith('name_')) {
-                const v = valueAt(record, key);
+                const v = recordDisplayValueAt(record, key);
                 if (v)
                     return v;
             }

package/dist/utils/reference-keys.d.ts

@@ -1,36 +1,35 @@
 /**
- * ObjectUI — reference-key canonicalization
+ * ObjectUI — object-schema key canonicalization at ingestion
  * 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.
- */
-/**
- * Backend object schemas follow the ObjectStack convention and name a
- * relational field's target object `reference`
- * (e.g. `{ type: 'lookup', reference: 'showcase_account' }`), while ObjectUI's
- * types — and most in-repo consumers — historically read `reference_to`
- * (some legacy configs also carry camelCase `referenceTo`). A consumer that
- * reads only one key silently loses the relation under the other convention:
- * the exact bug HeaderHighlight had (#2407 / PR #2587), where a served
- * `reference`-keyed lookup rendered a raw id.
  *
- * `normalizeFieldReferenceKeys` stamps BOTH snake_case keys onto the field
- * definition whenever any of the three spellings is present, so downstream
- * reads work regardless of which single key they check. It mutates the field
- * in place — the ObjectStack adapter caches the schema object and re-serves
- * it, so the one pass must stick — and is idempotent. Keys that are already
- * set are never overwritten.
+ * ⚠️ The FILE and its exports still say `reference`; the pass no longer does
+ * only that. The `reference` / `reference_to` pair was the first tenant, and
+ * objectui#7650 added the retired-dialect arm below, which folds ANY undeclared
+ * snake twin of a declared `FieldSchema` key. Renaming the exports would be a
+ * published-export change across ~20 in-repo citations and belongs to its own
+ * card; the two arms are marked so the name cannot mislead a reader who got
+ * here from a grep.
  */
-export declare function normalizeFieldReferenceKeys<T>(fieldDef: T): T;
+/** Reset the warn-once memos. Exported for tests. */
+export declare function resetReferenceKeyWarnings(): void;
+export declare function normalizeFieldReferenceKeys<T>(fieldDef: T, fieldName?: string, objectName?: string): T;
 /**
  * Apply {@link normalizeFieldReferenceKeys} to every field of an object
- * schema. Accepts both field-container shapes the metadata API serves —
- * a `name → def` map or an array of defs — and tolerates anything else by
- * returning the input untouched. Mutates in place; idempotent.
+ * schema — BOTH arms: the `reference` fold and the retired dialect. Accepts
+ * both field-container shapes the metadata API serves — a `name → def` map or
+ * an array of defs — and tolerates anything else by returning the input
+ * untouched. Mutates in place; idempotent.
  *
  * This is meant to run at the choke point where object schemas enter the
  * client (`ObjectStackAdapter.getObjectSchema`, the app-shell metadata
- * provider) so per-consumer dual-key fallbacks can't drift.
+ * provider), so no consumer needs a dual-key fallback of its own.
+ *
+ * Field NAMES and the OBJECT name are forwarded so the dev-mode warning above
+ * can name the whole producer site rather than half of it: the map form keys
+ * the def by name, the array form carries it as `def.name`, and the object name
+ * comes off `schema.name`.
  */
 export declare function normalizeSchemaReferenceKeys<T>(schema: T): T;