@object-ui/core 11.0.0 → 11.3.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @object-ui/core
 
+## 11.3.0
+
+### Minor Changes
+
+- d23d6eb: Three-tier AI page authoring: `kind:'html'` and a trusted `kind:'react'` tier.
+
+  - **`@object-ui/react-runtime`** (new) — the trusted runtime-React tier for
+    `kind:'react'` pages (vendored react-runner: Sucrase transpile + scope-eval,
+    no sandbox). Renders real JSX/TSX (any HTML + JS + hooks/useState/map/onClick)
+    in the main React tree with an injected scope (React, the public data blocks,
+    page data) and a built-in error boundary.
+  - **`@object-ui/core`** — new runtime capability gate (`enableCapability` /
+    `disableCapability` / `isCapabilityEnabled`, `CAP_REACT_PAGES`). `react-pages`
+    defaults **ON** (the platform trusts reviewed, draft-gated authors); a
+    deployment turns it OFF server-side (the runtime injects the disable global
+    when `OS_DISABLE_REACT_PAGES` is set). Never controlled from authored metadata.
+  - **`@object-ui/components`** — PageRenderer now routes `kind:'react'`
+    (capability-gated, lazy-loads the runtime) and renders `kind:'html'` (the
+    former `kind:'jsx'`, still accepted as a deprecated alias). The `html` tier
+    now resolves the full safe native HTML tag set (h1–h6, p, a, ul/ol/li, img,
+    blockquote, pre, strong/em, …) so authored HTML lives up to its name.
+
+### Patch Changes
+
+- @object-ui/types@11.3.0
+
+## 11.2.0
+
+### Minor Changes
+
+- 9e7a986: ADR-0080: AI-authored UI pages. New `@object-ui/sdui-parser` compiles a constrained JSX/HTML+Tailwind source into the SchemaNode tree (parse, never execute) with whitelist sanitization, manifest validation, and `.d.ts` codegen for the JSX type surface. `PageRenderer` renders `kind:'jsx'` pages; `ComponentRegistry` gains `tier` + `getPublicConfigs()` (capability vs contract).
+- 1311749: ADR-0080 M5: curated PUBLIC block contract (capability ≠ contract). Adds `PUBLIC_BLOCKS` — the single, reviewable list of ~36 object-aware + layout/content blocks that form the AI/contract surface (Salesforce-App-Builder-shaped). `getPublicConfigs()` now returns the curated set (plus any `tier:'public'` opt-in), keyed by bare tag and deduped across the registry's dual-key registrations. The full ~244 registered types remain a rendering capability.
+
+### Patch Changes
+
+- @object-ui/types@11.2.0
+
+## 11.1.0
+
+### Patch Changes
+
+- @object-ui/types@11.1.0
+
 ## 7.3.0
 
 ### Patch Changes

package/dist/actions/ActionRunner.d.ts

@@ -135,6 +135,12 @@ export interface ActionDef {
     execute?: string;
     /** Target URL or identifier (for type: 'url', 'modal', 'flow') */
     target?: string;
+    /** For type: 'url' — where to open `target`. `'new-tab'` forces a new
+     *  browser tab/window, `'self'` forces same-page navigation. When omitted,
+     *  external URLs open in a new tab and relative URLs navigate in place.
+     *  This is the public, static "open in new tab" switch (ActionSchema.openIn),
+     *  distinct from the async-handler `opensInNewTab` pre-open dance. */
+    openIn?: 'self' | 'new-tab';
     /** Modal schema to open (for type: 'modal') */
     modal?: any;
     /** Chained actions to execute after this one */

package/dist/actions/ActionRunner.js

@@ -468,7 +468,12 @@ export class ActionRunner {
             window.location.href = url;
             return { success: true };
         }
-        const newTab = action.params?.newTab ?? isExternal;
+        // `openIn` is the first-class, declarative switch (ActionSchema.openIn);
+        // it wins over the legacy `params.newTab` escape hatch and the
+        // external-URL heuristic.
+        const newTab = action.openIn === 'new-tab' ? true
+            : action.openIn === 'self' ? false
+                : (action.params?.newTab ?? isExternal);
         if (this.navigationHandler) {
             this.navigationHandler(url, { external: isExternal, newTab });
             return { success: true };

package/dist/index.d.ts

@@ -7,6 +7,7 @@
  */
 export type { SchemaNode, ComponentRendererProps } from './types/index.js';
 export * from './registry/Registry.js';
+export * from './registry/public-blocks.js';
 export * from './registry/PluginSystem.js';
 export * from './registry/PluginScopeImpl.js';
 export * from './registry/WidgetRegistry.js';
@@ -28,6 +29,7 @@ export * from './utils/merge-views-into-objects.js';
 export * from './utils/freeze-schema.js';
 export * from './protocols/index.js';
 export * from './styling/scoped-styles.js';
+export * from './runtime/capabilities.js';
 /**
  * @deprecated Import `composeStacks` from `@objectstack/spec` instead.
  *
@@ -40,3 +42,4 @@ export * from './utils/date-macros.js';
 export * from './utils/compare-to.js';
 export * from './utils/chart-series.js';
 export * from './utils/dataset-format.js';
+export * from './utils/record-title.js';

package/dist/index.js

@@ -6,6 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 export * from './registry/Registry.js';
+export * from './registry/public-blocks.js';
 export * from './registry/PluginSystem.js';
 export * from './registry/PluginScopeImpl.js';
 export * from './registry/WidgetRegistry.js';
@@ -27,6 +28,7 @@ export * from './utils/merge-views-into-objects.js';
 export * from './utils/freeze-schema.js';
 export * from './protocols/index.js';
 export * from './styling/scoped-styles.js';
+export * from './runtime/capabilities.js';
 /**
  * @deprecated Import `composeStacks` from `@objectstack/spec` instead.
  *
@@ -39,3 +41,4 @@ export * from './utils/date-macros.js';
 export * from './utils/compare-to.js';
 export * from './utils/chart-series.js';
 export * from './utils/dataset-format.js';
+export * from './utils/record-title.js';

package/dist/registry/Registry.d.ts

@@ -25,6 +25,13 @@ export type ComponentMeta = {
     label?: string;
     icon?: string;
     category?: string;
+    /**
+     * Public contract tier (ADR-0080). `'public'` = part of the curated,
+     * type-checked, AI-facing block set (gets a strengthened contract, the
+     * JSX type surface, the api-surface ratchet, and customer docs). Undefined
+     * or `'internal'` = rendering capability only, not part of the contract.
+     */
+    tier?: 'public' | 'internal';
     namespace?: string;
     /**
      * When true, prevents the component from being registered with a non-namespaced fallback.
@@ -182,6 +189,12 @@ export declare class Registry<T = any> {
      * @returns Array of all component configurations
      */
     getAllConfigs(): ComponentConfig<T>[];
+    /**
+     * Get the curated PUBLIC-tier component configs (ADR-0080) — those registered
+     * with `tier: 'public'`. This is the contract/AI-vocabulary surface, a subset
+     * of the full rendering capability returned by {@link getAllConfigs}.
+     */
+    getPublicConfigs(): ComponentConfig<T>[];
     /**
      * Get all components in a specific namespace.
      *

package/dist/registry/Registry.js

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { PUBLIC_BLOCKS } from './public-blocks.js';
 export class Registry {
     constructor() {
         Object.defineProperty(this, "components", {
@@ -270,6 +271,35 @@ export class Registry {
     getAllConfigs() {
         return Array.from(this.components.values());
     }
+    /**
+     * Get the curated PUBLIC-tier component configs (ADR-0080) — those registered
+     * with `tier: 'public'`. This is the contract/AI-vocabulary surface, a subset
+     * of the full rendering capability returned by {@link getAllConfigs}.
+     */
+    getPublicConfigs() {
+        // Dedupe by the config's canonical (namespaced) `type` — a component is
+        // registered under both a bare and a namespaced key pointing at the same
+        // canonical type, and we want one contract entry per component.
+        const seenCanonical = new Set();
+        const out = [];
+        const add = (tag, cfg) => {
+            if (!cfg || seenCanonical.has(cfg.type))
+                return;
+            seenCanonical.add(cfg.type);
+            // The contract surface is keyed by the bare/curated tag authors write,
+            // not the namespaced canonical stored on the config.
+            out.push({ ...cfg, type: tag });
+        };
+        // Curated contract list first (stable, reviewable order) …
+        for (const tag of PUBLIC_BLOCKS)
+            add(tag, this.getConfig(tag));
+        // … plus any bare registration that opted in explicitly via `tier: 'public'`.
+        for (const [key, cfg] of this.components.entries()) {
+            if (cfg.tier === 'public' && !key.includes(':'))
+                add(key, cfg);
+        }
+        return out;
+    }
     /**
      * Get all components in a specific namespace.
      *

package/dist/registry/public-blocks.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+/**
+ * ADR-0080 — the curated PUBLIC block contract (capability ≠ contract).
+ *
+ * The subset of registered components that form the platform's *contract* and
+ * AI-authoring vocabulary: type-checked, api-surface-ratcheted, documented, and
+ * offered to the JSX-source authoring surface. The full ~244 registered types
+ * remain a rendering *capability* (`getAllConfigs`); only these are the
+ * contract (`getPublicConfigs`).
+ *
+ * Shaped like Salesforce App Builder standard components — small, object-centric
+ * — plus a thin layout/content layer and one escape hatch. A component not yet
+ * registered is simply skipped (the list is aspirational-safe). Registrations
+ * may also opt in individually via `tier: 'public'`.
+ *
+ * This is a single, reviewable source of truth for the public surface — prefer
+ * editing this list over scattering `tier` flags across registration sites.
+ */
+export declare const PUBLIC_BLOCKS: readonly string[];
+/** Fast membership set built from {@link PUBLIC_BLOCKS}. */
+export declare const PUBLIC_BLOCK_SET: ReadonlySet<string>;

package/dist/registry/public-blocks.js

@@ -0,0 +1,67 @@
+/**
+ * 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.
+ */
+/**
+ * ADR-0080 — the curated PUBLIC block contract (capability ≠ contract).
+ *
+ * The subset of registered components that form the platform's *contract* and
+ * AI-authoring vocabulary: type-checked, api-surface-ratcheted, documented, and
+ * offered to the JSX-source authoring surface. The full ~244 registered types
+ * remain a rendering *capability* (`getAllConfigs`); only these are the
+ * contract (`getPublicConfigs`).
+ *
+ * Shaped like Salesforce App Builder standard components — small, object-centric
+ * — plus a thin layout/content layer and one escape hatch. A component not yet
+ * registered is simply skipped (the list is aspirational-safe). Registrations
+ * may also opt in individually via `tier: 'public'`.
+ *
+ * This is a single, reviewable source of truth for the public surface — prefer
+ * editing this list over scattering `tier` flags across registration sites.
+ */
+export const PUBLIC_BLOCKS = [
+    // ── Tier A — object-aware blocks (the contract core) ──────────────────────
+    'object-grid',
+    'list-view',
+    'object-form',
+    'embeddable-form',
+    'object-master-detail-form',
+    'object-kanban',
+    'object-calendar',
+    'object-gantt',
+    'object-timeline',
+    'object-map',
+    'object-metric',
+    'object-chart',
+    'dashboard',
+    'object-pivot',
+    'record:details',
+    'record:highlights',
+    'record:related_list',
+    'record:path',
+    'line_items',
+    // ── Tier B — layout / content primitives ──────────────────────────────────
+    'flex',
+    'grid',
+    'stack',
+    'card',
+    'tabs',
+    'accordion',
+    'container',
+    'page:header',
+    'text',
+    'image',
+    'icon',
+    'markdown',
+    'element:divider',
+    'badge',
+    'alert',
+    'button',
+    // ── Tier C — escape hatch (flagged, second-class) ─────────────────────────
+    'html',
+];
+/** Fast membership set built from {@link PUBLIC_BLOCKS}. */
+export const PUBLIC_BLOCK_SET = new Set(PUBLIC_BLOCKS);

package/dist/runtime/capabilities.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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.
+ *
+ * Runtime capability gates — switches a *host* controls, never authored
+ * metadata. Each capability has a default; a host can flip it explicitly
+ * (`enableCapability`/`disableCapability`) or seed it from globals before any
+ * bundle code runs.
+ *
+ * {@link CAP_REACT_PAGES} (`kind:'react'` — execute author JavaScript in the
+ * main React tree) defaults **ON**: ObjectStack pages are authored by trusted
+ * authors and pass human review (draft-gating, ADR-0033), so the platform
+ * trusts them by default. A deployment that does NOT trust its page authors
+ * turns it off server-side — the ObjectStack runtime injects the disable global
+ * when `OS_PAGE_REACT=off` (see framework cli/utils/console.ts).
+ *
+ * Globals a host/server can set in the page before the bundle runs:
+ *   - `globalThis.__OBJECTUI_CAPABILITIES__`          — string[] to force ON
+ *   - `globalThis.__OBJECTUI_CAPABILITIES_DISABLED__` — string[] to force OFF
+ */
+/** Turn a capability on. Call from the host process only (not from metadata). */
+export declare function enableCapability(name: string): void;
+/** Turn a capability off. */
+export declare function disableCapability(name: string): void;
+/** Whether a capability is enabled. Host/global override wins over the default. */
+export declare function isCapabilityEnabled(name: string): boolean;
+/**
+ * `kind:'react'` — execute trusted author JavaScript (full React: hooks, event
+ * handlers, arbitrary JS) directly in the main React tree. Default ON; a
+ * deployment disables it server-side with `OS_PAGE_REACT=off`.
+ */
+export declare const CAP_REACT_PAGES = "react-pages";

package/dist/runtime/capabilities.js

@@ -0,0 +1,72 @@
+/**
+ * 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.
+ *
+ * Runtime capability gates — switches a *host* controls, never authored
+ * metadata. Each capability has a default; a host can flip it explicitly
+ * (`enableCapability`/`disableCapability`) or seed it from globals before any
+ * bundle code runs.
+ *
+ * {@link CAP_REACT_PAGES} (`kind:'react'` — execute author JavaScript in the
+ * main React tree) defaults **ON**: ObjectStack pages are authored by trusted
+ * authors and pass human review (draft-gating, ADR-0033), so the platform
+ * trusts them by default. A deployment that does NOT trust its page authors
+ * turns it off server-side — the ObjectStack runtime injects the disable global
+ * when `OS_PAGE_REACT=off` (see framework cli/utils/console.ts).
+ *
+ * Globals a host/server can set in the page before the bundle runs:
+ *   - `globalThis.__OBJECTUI_CAPABILITIES__`          — string[] to force ON
+ *   - `globalThis.__OBJECTUI_CAPABILITIES_DISABLED__` — string[] to force OFF
+ */
+/** Default state per capability when neither the host nor a global overrides it. */
+const DEFAULTS = {
+    'react-pages': true,
+};
+// Explicit host overrides (enable/disable) — win over defaults and globals.
+const overrides = new Map();
+let _seeded = false;
+function seedFromGlobals() {
+    if (_seeded)
+        return;
+    _seeded = true;
+    const g = globalThis;
+    if (Array.isArray(g.__OBJECTUI_CAPABILITIES__)) {
+        for (const c of g.__OBJECTUI_CAPABILITIES__)
+            if (typeof c === 'string' && !overrides.has(c))
+                overrides.set(c, true);
+    }
+    if (Array.isArray(g.__OBJECTUI_CAPABILITIES_DISABLED__)) {
+        // Disable wins: a server that turned something off must not be overridden
+        // by a stale enable-list left in the same page.
+        for (const c of g.__OBJECTUI_CAPABILITIES_DISABLED__)
+            if (typeof c === 'string')
+                overrides.set(c, false);
+    }
+}
+/** Turn a capability on. Call from the host process only (not from metadata). */
+export function enableCapability(name) {
+    seedFromGlobals();
+    overrides.set(name, true);
+}
+/** Turn a capability off. */
+export function disableCapability(name) {
+    seedFromGlobals();
+    overrides.set(name, false);
+}
+/** Whether a capability is enabled. Host/global override wins over the default. */
+export function isCapabilityEnabled(name) {
+    seedFromGlobals();
+    const o = overrides.get(name);
+    if (o !== undefined)
+        return o;
+    return DEFAULTS[name] ?? false;
+}
+/**
+ * `kind:'react'` — execute trusted author JavaScript (full React: hooks, event
+ * handlers, arbitrary JS) directly in the main React tree. Default ON; a
+ * deployment disables it server-side with `OS_PAGE_REACT=off`.
+ */
+export const CAP_REACT_PAGES = 'react-pages';

package/dist/utils/chart-series.d.ts

@@ -36,6 +36,31 @@ export interface ChartSeriesResult {
     series: ChartSeries[];
 }
 export declare function buildChartSeries(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, fields?: ChartResultField[] | null): ChartSeriesResult;
+/**
+ * Resolve select/enum dimension VALUES to display LABELS in chart rows.
+ *
+ * Analytics groups by a select field's stored `value` (e.g. `active`), but a
+ * chart axis should read the option `label` (e.g. `合作中`). The server SHOULD
+ * resolve this (ADR-0021), but when it can't — an AI-built select whose
+ * `options` the analytics layer never sees, so its `resolveDimensionLabels`
+ * silently no-ops — the rows arrive value-keyed. The axis then shows raw enum
+ * values, and (worse) option-keyed colour / category wiring built from the
+ * field `label`s no longer lines up with the value-keyed rows, so categories
+ * read empty. This is the chart-layer safety net the legacy aggregate path
+ * already gets from `resolveGroupByLabels`.
+ *
+ * Each row is rewritten by replacing `row[dim]` with `labelMaps[dim][value]`
+ * when a mapping exists. Measure columns are untouched, so the grouped count
+ * stays attached to its (now label-keyed) category — `value` is the matching
+ * key, `label` is only the display. Values with no mapping (already a label
+ * because the server resolved it, a lookup id, free text) pass through, so this
+ * is safe to run unconditionally and is idempotent.
+ *
+ * Returns a NEW array; a row that needs no change keeps its identity, and the
+ * input rows are never mutated, so the server's raw rows survive for
+ * index-aligned drill-through (`drillRawRows`).
+ */
+export declare function relabelDimensions(rows: Array<Record<string, unknown>> | null | undefined, labelMaps: Record<string, Record<string, string>> | null | undefined): Array<Record<string, unknown>>;
 /**
  * Inverse of {@link buildChartSeries}: map a clicked chart segment back to the
  * index of its source dataset row, so a chart click can drill through to the
@@ -64,3 +89,14 @@ export declare function findChartSeriesRow(rows: Array<Record<string, unknown>>
  * paint identically across the chart view and dashboard widgets.
  */
 export declare function buildOptionColorMap(options: unknown): Record<string, string> | null;
+/**
+ * Build a `{ value → label }` map from a select/enum field's `options`, for
+ * resolving a grouped dimension's stored value to its display label (fed to
+ * {@link relabelDimensions}). Mirrors {@link buildOptionColorMap}.
+ *
+ * Options may be `{ value, label }` objects or bare strings (value == label —
+ * nothing to relabel). Only entries whose `label` actually differs from the
+ * `value` are kept, so the map is empty (→ `null`) when relabeling would be a
+ * no-op and the caller can skip it entirely.
+ */
+export declare function buildDimensionLabelMap(options: unknown): Record<string, string> | null;

package/dist/utils/chart-series.js

@@ -42,6 +42,53 @@ export function buildChartSeries(rows, dimensions, values, fields) {
         series: vals.map((v) => ({ dataKey: v, label: labelOf(v) })),
     };
 }
+/**
+ * Resolve select/enum dimension VALUES to display LABELS in chart rows.
+ *
+ * Analytics groups by a select field's stored `value` (e.g. `active`), but a
+ * chart axis should read the option `label` (e.g. `合作中`). The server SHOULD
+ * resolve this (ADR-0021), but when it can't — an AI-built select whose
+ * `options` the analytics layer never sees, so its `resolveDimensionLabels`
+ * silently no-ops — the rows arrive value-keyed. The axis then shows raw enum
+ * values, and (worse) option-keyed colour / category wiring built from the
+ * field `label`s no longer lines up with the value-keyed rows, so categories
+ * read empty. This is the chart-layer safety net the legacy aggregate path
+ * already gets from `resolveGroupByLabels`.
+ *
+ * Each row is rewritten by replacing `row[dim]` with `labelMaps[dim][value]`
+ * when a mapping exists. Measure columns are untouched, so the grouped count
+ * stays attached to its (now label-keyed) category — `value` is the matching
+ * key, `label` is only the display. Values with no mapping (already a label
+ * because the server resolved it, a lookup id, free text) pass through, so this
+ * is safe to run unconditionally and is idempotent.
+ *
+ * Returns a NEW array; a row that needs no change keeps its identity, and the
+ * input rows are never mutated, so the server's raw rows survive for
+ * index-aligned drill-through (`drillRawRows`).
+ */
+export function relabelDimensions(rows, labelMaps) {
+    const safeRows = Array.isArray(rows) ? rows : [];
+    if (!labelMaps)
+        return safeRows;
+    const dims = Object.keys(labelMaps).filter((d) => labelMaps[d] && Object.keys(labelMaps[d]).length > 0);
+    if (dims.length === 0)
+        return safeRows;
+    return safeRows.map((row) => {
+        let next = null;
+        for (const dim of dims) {
+            const raw = row[dim];
+            if (raw == null)
+                continue;
+            const label = labelMaps[dim][String(raw)];
+            if (label != null && label !== raw) {
+                if (!next)
+                    next = { ...row };
+                next[dim] = label;
+            }
+        }
+        return next ?? row;
+    });
+}
 /**
  * Inverse of {@link buildChartSeries}: map a clicked chart segment back to the
  * index of its source dataset row, so a chart click can drill through to the
@@ -100,3 +147,30 @@ export function buildOptionColorMap(options) {
     }
     return Object.keys(map).length > 0 ? map : null;
 }
+/**
+ * Build a `{ value → label }` map from a select/enum field's `options`, for
+ * resolving a grouped dimension's stored value to its display label (fed to
+ * {@link relabelDimensions}). Mirrors {@link buildOptionColorMap}.
+ *
+ * Options may be `{ value, label }` objects or bare strings (value == label —
+ * nothing to relabel). Only entries whose `label` actually differs from the
+ * `value` are kept, so the map is empty (→ `null`) when relabeling would be a
+ * no-op and the caller can skip it entirely.
+ */
+export function buildDimensionLabelMap(options) {
+    if (!Array.isArray(options) || options.length === 0)
+        return null;
+    const map = {};
+    for (const opt of options) {
+        if (opt && typeof opt === 'object') {
+            const o = opt;
+            if (o.value != null && o.label != null) {
+                const v = String(o.value);
+                const l = String(o.label);
+                if (l !== v)
+                    map[v] = l;
+            }
+        }
+    }
+    return Object.keys(map).length > 0 ? map : null;
+}

package/dist/utils/expand-fields.d.ts

@@ -5,32 +5,62 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * Relational ("reference-bearing") field types whose stored value is a foreign
+ * key into another object — and which therefore benefit from `$expand` so a
+ * list / grid / detail cell can render the related record's display name
+ * instead of a bare id placeholder ("—").
+ *
+ * This mirrors the form layer's `DATA_SOURCE_FIELD_TYPES`
+ * (`lookup` / `master_detail` / `tree`) and additionally covers `user` — a
+ * lookup specialised to `sys_user`. The server resolves `user` through the
+ * same expand path as `lookup` / `master_detail` (it carries the same
+ * `reference` + id storage), so a `user` column that is NOT requested for
+ * expansion comes back as a raw user id and renders as "—". Keeping the set
+ * here as the single source of truth is what closes that gap.
+ *
+ * Note on `tree`: a self-referencing hierarchy field is a reference too, so it
+ * belongs in this set; whether the backend materialises the expanded object
+ * for it is a server concern — requesting it is harmless and forward-compatible.
+ */
+export declare const EXPANDABLE_FIELD_TYPES: ReadonlySet<string>;
+/**
+ * Whether a field definition is a reference-bearing type that can be `$expand`-ed.
+ * Only the field's `type` matters here — the `reference` / `reference_to` target
+ * is irrelevant to the decision, so this works regardless of which canonical key
+ * the schema uses to name the related object.
+ */
+export declare function isExpandableFieldType(fieldDef: unknown): boolean;
 /**
  * Build an array of field names that should be included in `$expand`
  * when fetching data. This scans the given object schema fields
- * (and optional column configuration) for `lookup` and `master_detail`
- * field types, so the backend (e.g. objectql) returns expanded objects
- * instead of raw foreign-key IDs.
+ * (and optional column configuration) for reference-bearing field types
+ * (see {@link EXPANDABLE_FIELD_TYPES}: `lookup` / `master_detail` / `tree` /
+ * `user`), so the backend (e.g. objectql) returns expanded objects instead of
+ * raw foreign-key IDs.
  *
  * @param schemaFields - Object map of field metadata from `getObjectSchema()`,
- *   e.g. `{ account: { type: 'lookup', reference_to: 'accounts' }, ... }`.
+ *   e.g. `{ account: { type: 'lookup', reference: 'accounts' }, ... }`.
  * @param columns - Optional explicit column list. When provided, only
- *   lookup/master_detail fields that appear in `columns` are expanded.
- *   Accepts `string[]` or `ListColumn[]` (objects with a `field` property).
- * @returns Array of field names to pass as `$expand`.
+ *   reference fields that appear in `columns` are expanded — list/grid/kanban
+ *   views pass their VISIBLE columns here so wide objects don't pay to expand
+ *   relations no cell will show. Accepts `string[]` or `ListColumn[]` (objects
+ *   with a `field` property).
+ * @returns Array of field names to pass as `$expand` (empty → omit `$expand`).
  *
  * @example
  * ```ts
  * const fields = {
  *   name: { type: 'text' },
- *   account: { type: 'lookup', reference_to: 'accounts' },
- *   parent: { type: 'master_detail', reference_to: 'contacts' },
+ *   account: { type: 'lookup', reference: 'accounts' },
+ *   parent: { type: 'master_detail', reference: 'contacts' },
+ *   assignee: { type: 'user', reference: 'sys_user' },
  * };
  * buildExpandFields(fields);
- * // → ['account', 'parent']
+ * // → ['account', 'parent', 'assignee']
  *
  * buildExpandFields(fields, ['name', 'account']);
- * // → ['account']
+ * // → ['account']   (only the visible reference columns)
  * ```
  */
 export declare function buildExpandFields(schemaFields?: Record<string, any> | null, columns?: (string | {

package/dist/utils/expand-fields.js

@@ -5,51 +5,88 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * Relational ("reference-bearing") field types whose stored value is a foreign
+ * key into another object — and which therefore benefit from `$expand` so a
+ * list / grid / detail cell can render the related record's display name
+ * instead of a bare id placeholder ("—").
+ *
+ * This mirrors the form layer's `DATA_SOURCE_FIELD_TYPES`
+ * (`lookup` / `master_detail` / `tree`) and additionally covers `user` — a
+ * lookup specialised to `sys_user`. The server resolves `user` through the
+ * same expand path as `lookup` / `master_detail` (it carries the same
+ * `reference` + id storage), so a `user` column that is NOT requested for
+ * expansion comes back as a raw user id and renders as "—". Keeping the set
+ * here as the single source of truth is what closes that gap.
+ *
+ * Note on `tree`: a self-referencing hierarchy field is a reference too, so it
+ * belongs in this set; whether the backend materialises the expanded object
+ * for it is a server concern — requesting it is harmless and forward-compatible.
+ */
+export const EXPANDABLE_FIELD_TYPES = new Set([
+    'lookup',
+    'master_detail',
+    'tree',
+    'user',
+]);
+/**
+ * Whether a field definition is a reference-bearing type that can be `$expand`-ed.
+ * Only the field's `type` matters here — the `reference` / `reference_to` target
+ * is irrelevant to the decision, so this works regardless of which canonical key
+ * the schema uses to name the related object.
+ */
+export function isExpandableFieldType(fieldDef) {
+    return (!!fieldDef &&
+        typeof fieldDef === 'object' &&
+        EXPANDABLE_FIELD_TYPES.has(fieldDef.type));
+}
 /**
  * Build an array of field names that should be included in `$expand`
  * when fetching data. This scans the given object schema fields
- * (and optional column configuration) for `lookup` and `master_detail`
- * field types, so the backend (e.g. objectql) returns expanded objects
- * instead of raw foreign-key IDs.
+ * (and optional column configuration) for reference-bearing field types
+ * (see {@link EXPANDABLE_FIELD_TYPES}: `lookup` / `master_detail` / `tree` /
+ * `user`), so the backend (e.g. objectql) returns expanded objects instead of
+ * raw foreign-key IDs.
  *
  * @param schemaFields - Object map of field metadata from `getObjectSchema()`,
- *   e.g. `{ account: { type: 'lookup', reference_to: 'accounts' }, ... }`.
+ *   e.g. `{ account: { type: 'lookup', reference: 'accounts' }, ... }`.
  * @param columns - Optional explicit column list. When provided, only
- *   lookup/master_detail fields that appear in `columns` are expanded.
- *   Accepts `string[]` or `ListColumn[]` (objects with a `field` property).
- * @returns Array of field names to pass as `$expand`.
+ *   reference fields that appear in `columns` are expanded — list/grid/kanban
+ *   views pass their VISIBLE columns here so wide objects don't pay to expand
+ *   relations no cell will show. Accepts `string[]` or `ListColumn[]` (objects
+ *   with a `field` property).
+ * @returns Array of field names to pass as `$expand` (empty → omit `$expand`).
  *
  * @example
  * ```ts
  * const fields = {
  *   name: { type: 'text' },
- *   account: { type: 'lookup', reference_to: 'accounts' },
- *   parent: { type: 'master_detail', reference_to: 'contacts' },
+ *   account: { type: 'lookup', reference: 'accounts' },
+ *   parent: { type: 'master_detail', reference: 'contacts' },
+ *   assignee: { type: 'user', reference: 'sys_user' },
  * };
  * buildExpandFields(fields);
- * // → ['account', 'parent']
+ * // → ['account', 'parent', 'assignee']
  *
  * buildExpandFields(fields, ['name', 'account']);
- * // → ['account']
+ * // → ['account']   (only the visible reference columns)
  * ```
  */
 export function buildExpandFields(schemaFields, columns) {
     if (!schemaFields || typeof schemaFields !== 'object') {
         return [];
     }
-    // Collect all lookup / master_detail field names from the schema
-    const lookupFieldNames = [];
+    // Collect every reference-bearing field name from the schema.
+    const referenceFieldNames = [];
     for (const [fieldName, fieldDef] of Object.entries(schemaFields)) {
-        if (fieldDef &&
-            typeof fieldDef === 'object' &&
-            (fieldDef.type === 'lookup' || fieldDef.type === 'master_detail')) {
-            lookupFieldNames.push(fieldName);
+        if (isExpandableFieldType(fieldDef)) {
+            referenceFieldNames.push(fieldName);
         }
     }
-    if (lookupFieldNames.length === 0) {
+    if (referenceFieldNames.length === 0) {
         return [];
     }
-    // When columns are provided, restrict expansion to visible columns only
+    // When columns are provided, restrict expansion to visible columns only.
     if (columns && Array.isArray(columns) && columns.length > 0) {
         const columnFieldNames = new Set();
         for (const col of columns) {
@@ -62,7 +99,7 @@ export function buildExpandFields(schemaFields, columns) {
                     columnFieldNames.add(name);
             }
         }
-        return lookupFieldNames.filter((f) => columnFieldNames.has(f));
+        return referenceFieldNames.filter((f) => columnFieldNames.has(f));
     }
-    return lookupFieldNames;
+    return referenceFieldNames;
 }

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

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+/**
+ * Render a record title from a `titleFormat` pattern.
+ *
+ * Accepts either a legacy string template or an Expression envelope
+ * (`{ dialect: 'template', source: string }`) emitted by `@objectstack/spec`'s
+ * normalized templates. Both single-brace (`{field}`) and double-brace
+ * (`{{field}}`, the handlebars-style some authoring paths emit) placeholders are
+ * 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.
+ */
+export declare function formatTitleTemplate(titleFormat: string | {
+    source?: string;
+} | undefined | null, record: any): string;
+/**
+ * Decide whether a field definition can serve as a record title. Excludes the
+ * {@link NON_TITLE_TYPES} (dates, numbers, pickers, lookups, binary, …); a
+ * `formula` is eligible only when it returns text. A field with no declared
+ * type is treated as eligible (text-by-default), so loosely-typed metadata
+ * still produces a name rather than falling through to `Record #…`.
+ */
+export declare function isTitleEligibleField(def: any): boolean;
+/**
+ * Type-aware derivation (precedence step 4): pick the best title-eligible field
+ * name from `objectDef.fields`, ranked:
+ *
+ *   1. name-ish exact   — `name`,`title`,`subject`,`label`,`full_name`,
+ *                         `display_name` (case-insensitive)
+ *   2. name-ish affix   — `*_name`, `*_title`, `name_*` (case-insensitive)
+ *   3. declaration order — first remaining title-eligible field
+ *
+ * Returns the field name, or undefined when `fields` is absent/empty or holds
+ * no title-eligible field.
+ *
+ * Memoized per `objectDef` identity (see {@link deriveTitleFieldCache}): the
+ * field scan runs once per object definition, not once per record. The result is
+ * byte-identical to the uncached computation — only the scan is cached, and only
+ * when `objectDef` is a non-null object (the WeakMap key requirement).
+ */
+export declare function deriveTitleField(objectDef: any): string | undefined;
+export interface RecordDisplayNameOptions {
+    /**
+     * Optional explicit title field (e.g. a view's `titleField` / gallery
+     * `titleField` / kanban `cardTitle`). When set and it yields a non-empty
+     * value on the record, it wins over everything — preserving each view's
+     * author-chosen field. Pass nothing to use the object-level precedence only.
+     */
+    titleField?: string;
+    /** Floor when the record has no id at all. Defaults to `'Untitled'`. */
+    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
+     * `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
+     * its `Record #<id>` floor instead — letting the caller decide.
+     */
+    deriveFromRecordKeys?: boolean;
+}
+/**
+ * THE unified record display-name resolver (ADR-0079).
+ *
+ * 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.
+ *   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
+ *      deprecated alias of `nameField`, kept for back-compat.
+ *   3. `objectDef.titleFormat` (rendered template) — LEGACY, render-only, kept
+ *      for back-compat only; an explicitly-declared field (1/2) now wins over
+ *      it. See the deprecation note on the branch below.
+ *   4. type-aware derivation from `objectDef.fields` ({@link deriveTitleField}).
+ *   4b. standard name-ish keys probed directly on the record
+ *      ({@link NAME_ISH_RECORD_KEYS}) — the safety net for when `fields` is
+ *      absent so derivation can't run.
+ *   5. `Record #<id>` (using `record.id ?? record._id`), else `options.fallback`
+ *      (default `'Untitled'`) for a truly id-less record.
+ *
+ * @param objectDef Object definition (may be `any`/partial — every field is
+ *                  read defensively).
+ * @param record    The record data.
+ */
+export declare function getRecordDisplayName(objectDef: any, record: any, options?: RecordDisplayNameOptions): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/core",
-  "version": "11.0.0",
+  "version": "11.3.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -25,11 +25,11 @@
     }
   },
   "dependencies": {
-    "@objectstack/formula": "^11.0.0",
-    "@objectstack/spec": "^11.0.0",
+    "@objectstack/formula": "^11.2.0",
+    "@objectstack/spec": "^11.2.0",
     "lodash": "^4.18.1",
     "zod": "^4.4.3",
-    "@object-ui/types": "11.0.0"
+    "@object-ui/types": "11.3.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",