@object-ui/core 17.5.0 → 17.6.0

package/dist/evaluator/listConditional.js

@@ -36,6 +36,7 @@
 import { evalFieldPredicate } from './fieldRules.js';
 import { ExpressionEvaluator } from './ExpressionEvaluator.js';
 import { toPredicateRecord } from '../utils/predicate-record.js';
+import { warnNonCanonicalRowSpelling } from './rowPredicateCanon.js';
 /**
  * Syntax that only the legacy JS-dialect evaluator understands and that is NOT
  * valid CEL: `${…}` templates, strict (in)equality, JS optional-chaining
@@ -62,7 +63,14 @@ function warnLegacyDialect(source) {
 }
 const warnedError = new Set();
 /**
- * One-time fail-closed report for a predicate that could not be evaluated.
+ * One-time report for a predicate that could not be evaluated.
+ *
+ * The message names the caller's `fallback` as "its safe default" without
+ * asserting a direction, because the direction is the caller's: row surfaces
+ * fail CLOSED (a faulting `visible` hides the action), while a param-collection
+ * dialog fails OPEN (objectui#4640 — a silently hidden required param is the
+ * undiagnosable failure). Both are loud; only silence was ever ruled out
+ * (2026-08-06 on objectui#4051 / objectstack#5149).
  *
  * `reason` is the engine's own description of the failure (`"[runtime] No such
  * key: owner_id"`) — the single most useful line for the author, and precisely
@@ -129,11 +137,34 @@ function evalCel(pred, record, scope) {
  * Evaluate a single boolean predicate against a row record on the canonical CEL
  * engine (with a legacy-dialect fallback — see the module note). The row's
  * fields are bound three ways so every authoring convention resolves:
- * `record.status` (spec/canonical), bare `status` (row-action shorthand), and
- * `data.status` (legacy). The optional `scope` (host predicate scope) is bound
+ * `record.status`, bare `status` (row-action shorthand), and `data.status`.
+ *
+ * ⚠️ Those three are NOT peers, and this doc comment used to read as though
+ * they were. **The canon is `record.*`** (maintainer ruling 2026-08-20 on
+ * objectui#5330, option B); the other two are client tolerances in a
+ * deprecation window, kept because stored metadata carries them and warned
+ * about — from the CEL path below — by `warnNonCanonicalRowSpelling`. The
+ * server accepts `record.*` and NOTHING else: measured on
+ * `@objectstack/formula@17.1.0`, `buildScope({ record })` mounts exactly
+ * `['record']`, so a bare field faults `Unknown variable: status` there and a
+ * `data.*` predicate faults `Unknown variable: data`. See
+ * {@link ./rowPredicateCanon.ts} for the full measurement, for why `data.*` is
+ * the dangerous one (it is silently ACCEPTED by the server's authoring oracle
+ * and still binds nothing at runtime), and for why the deprecation is scoped to
+ * this runtime layer rather than declared platform-wide (`data` is the
+ * canonical root of a metadata-editing form — ADR-0089 D3).
+ *
+ * ⛔ No spelling is removed from the binding, and none may be before a
+ * stored-metadata survey sizes the window — that is part of the same ruling.
+ *
+ * The optional `scope` (host predicate scope) is bound
  * alongside so `features.*` / `user.*` predicates keep working — but the row is
  * the subject: `record` and `data` always name THIS row, on both dialect paths,
  * even when the host scope carries keys of those names (objectui#3796).
+ *
+ * A caller with no row at all passes {@link RowPredicateOptions.rowless}, and
+ * then nothing is bound over the scope — see that option for why an absent row
+ * must not be spelled as an empty one.
  */
 export function evalRowPredicate(pred, row, opts = {}) {
     const fallback = opts.fallback ?? false;
@@ -145,7 +176,10 @@ export function evalRowPredicate(pred, row, opts = {}) {
     // Relations collapse to the foreign key the server stores, so `record.owner`
     // means one thing whether or not this surface expanded the column
     // (objectui#3501). Returned by reference when there is nothing to collapse.
-    const rowObj = toPredicateRecord(row && typeof row === 'object' ? row : {}, opts.fields);
+    // A `rowless` caller has no row to collapse, so `opts.fields` is moot there.
+    const rowObj = opts.rowless
+        ? {}
+        : toPredicateRecord(row && typeof row === 'object' ? row : {}, opts.fields);
     // Bare fields + `data.*` + `record.*` + the host scope, all top-level.
     //
     // `data` AND `record` are pinned AFTER the spread, so a host scope that
@@ -158,7 +192,28 @@ export function evalRowPredicate(pred, row, opts = {}) {
     // string happens to contain `===`/`${…}`, which no author is choosing
     // deliberately (objectui#3796). Pinning here fixes both paths at the merge,
     // independently of either engine's precedence.
-    const scope = { ...(opts.scope ?? {}), ...rowObj, data: rowObj, record: rowObj };
+    //
+    // …UNLESS the caller has no row (`rowless`), in which case there is nothing
+    // to pin and the host scope keeps its own `record` / `data` — see the option.
+    const scope = opts.rowless
+        ? { ...(opts.scope ?? {}) }
+        : { ...(opts.scope ?? {}), ...rowObj, data: rowObj, record: rowObj };
+    // The predicate TEXT for diagnostics: a bare string is itself, an envelope is
+    // its `source`. Reported separately from `source` above, which is `undefined`
+    // for an envelope *by design* (it drives the dialect routing, and an envelope
+    // is never routed to the legacy engine). Reusing it for the warning is what
+    // made every faulting envelope report as the literal `"(expression)"` — no
+    // predicate text for the author, and, because the one-time key is
+    // (label, source), the FIRST faulting envelope on a given label silenced every
+    // other one under it (objectui#4640: measured on `evalRowPredicate` — a second
+    // envelope with a different, also-broken source warned zero times). The
+    // envelope is not an exotic spelling: `@objectstack/spec`'s
+    // `ExpressionInputSchema` normalizes every authored predicate into one, so it
+    // is the likeliest shape in served metadata and was the least diagnosable.
+    const predicateText = source ??
+        (pred && typeof pred === 'object' && typeof pred.source === 'string'
+            ? pred.source
+            : '(expression)');
     // Legacy-dialect *strings* route to the legacy engine (back-compat). The
     // `{ dialect: 'cel', source }` envelope is never routed here — it is CEL.
     if (source !== undefined && isLegacyDialectSource(source)) {
@@ -176,6 +231,15 @@ export function evalRowPredicate(pred, row, opts = {}) {
             return fallback;
         }
     }
+    // CEL path — everything reaching here is CEL, which is what makes this the
+    // right place for the objectui#5330 spelling warning: in the legacy `${…}`
+    // dialect above, `data.*` is the NORMAL spelling, so reporting it there would
+    // be a false positive on every legacy predicate. `data` names THIS row unless
+    // the caller is `rowless` (then the host scope keeps its own — see the
+    // option), which is exactly the condition the detector needs.
+    if (predicateText !== '(expression)') {
+        warnNonCanonicalRowSpelling(predicateText, rowObj, !opts.rowless, opts.label);
+    }
     // CEL path. The fault-aware `evalCel` costs two evaluations (to tell a fault
     // from a genuine `false`), so only pay it when a caller wants the labelled
     // fail-closed warning — the formatting hot path takes the single-eval fast
@@ -187,7 +251,7 @@ export function evalRowPredicate(pred, row, opts = {}) {
     }
     const verdict = evalCel(pred, rowObj, scope);
     if (!verdict.ok) {
-        warnEvalError(source ?? '(expression)', opts.label, verdict.reason);
+        warnEvalError(predicateText, opts.label, verdict.reason);
         return fallback;
     }
     return verdict.value;

package/dist/evaluator/optionRules.d.ts

@@ -97,3 +97,58 @@ export interface CascadingOptions<T extends OptionLike> {
  * purely by `visibleWhen`). Callers format their own hint from `dependsOnFields`.
  */
 export declare function resolveCascadingOptions<T extends OptionLike>(rawOptions: readonly T[] | undefined | null, record: Record<string, unknown>, dependsOn: DependsOnInput, scope?: Record<string, unknown>): CascadingOptions<T>;
+/**
+ * Widget keys whose OFFERED option set is re-resolved against a live record by
+ * {@link resolveCascadingOptions} — i.e. the allow-list of widgets a surface
+ * must thread its live record to (`dependentValues`). Each of their options may
+ * carry a `visibleWhen` predicate read against `record.*`, and the field may
+ * declare a `dependsOn` gate (ADR-0058 / objectui#2284 / objectui#1583).
+ * Without the record a cascading select never sees its controlling field and
+ * stays permanently gated on the "select the parent first" hint.
+ *
+ * ## One definition, three surfaces (objectui#4770)
+ *
+ * Three surfaces feed this one evaluator, and each carried its own private copy
+ * of these four keys until this constant existed — with no gate able to notice
+ * them drifting apart on what "the record" means:
+ *
+ * - the object form — `CASCADE_OPTION_FIELD_TYPES` in
+ *   `components/src/renderers/form/form.tsx` (the original);
+ * - the single-record action dialog — `CASCADE_OPTION_WIDGET_TYPES` in
+ *   `app-shell/src/views/ActionParamDialog.tsx` (objectui#3765 / PR #4756);
+ * - the bulk action dialog — the same name in
+ *   `plugin-grid/src/components/BulkActionDialog.tsx` (objectui#4757 / PR #4763).
+ *
+ * The set lives in `@object-ui/core`, next to the evaluator it describes,
+ * because core is the one package all three already depend on — the form layer
+ * cannot reach `@object-ui/fields` (that dependency runs the other way). Same
+ * shape and same reason as `EXPANDABLE_FIELD_TYPES` in
+ * `core/src/utils/expand-fields.ts`, the in-repo precedent for a form-layer
+ * allow-table more than one surface reads. `@object-ui/fields` re-exports it
+ * next to `resolveFormWidgetType` for discoverability — a re-export, never a
+ * second definition.
+ *
+ * ## An ALLOW-LIST, not a blanket pass-through
+ *
+ * `dependentValues` is also the channel two widget-hint pickers read a specific
+ * SIBLING KEY from (`filter-condition` reads `object_name`, `recipient-picker`
+ * reads `recipient_type`), and the lookup family filters its query by it. All
+ * three surfaces above agree today in NOT feeding those from action / bulk
+ * dialog params, but that is a different wiring question from the one ruled
+ * here and it has never been decided either way. Stated here so the three
+ * copies of the statement become one — the boundary itself stays open:
+ * objectui#4771.
+ *
+ * ## Normalization stays with the consumer
+ *
+ * The members are WIDGET keys — `resolveFormWidgetType` output in the two
+ * dialogs, `normalizeFieldType` output (the `field:` prefix stripped) in the
+ * form — not authored `type` spellings. Each consumer keeps its own
+ * normalization; the two normalizations agree on these four members, which is
+ * what makes one shared set safe to read from both.
+ *
+ * `select` + `multiple: true` is not listed separately: `SelectField` delegates
+ * to `MultiSelectField` with the whole prop object, so the key it resolves
+ * under (`select`) is the one that must carry the record.
+ */
+export declare const CASCADE_OPTION_WIDGET_TYPES: ReadonlySet<string>;

package/dist/evaluator/optionRules.js

@@ -77,3 +77,63 @@ export function resolveCascadingOptions(rawOptions, record, dependsOn, scope) {
     const options = gated ? [] : resolveVisibleOptions(rawOptions, record, scope);
     return { options, gated, dependsOnFields };
 }
+/**
+ * Widget keys whose OFFERED option set is re-resolved against a live record by
+ * {@link resolveCascadingOptions} — i.e. the allow-list of widgets a surface
+ * must thread its live record to (`dependentValues`). Each of their options may
+ * carry a `visibleWhen` predicate read against `record.*`, and the field may
+ * declare a `dependsOn` gate (ADR-0058 / objectui#2284 / objectui#1583).
+ * Without the record a cascading select never sees its controlling field and
+ * stays permanently gated on the "select the parent first" hint.
+ *
+ * ## One definition, three surfaces (objectui#4770)
+ *
+ * Three surfaces feed this one evaluator, and each carried its own private copy
+ * of these four keys until this constant existed — with no gate able to notice
+ * them drifting apart on what "the record" means:
+ *
+ * - the object form — `CASCADE_OPTION_FIELD_TYPES` in
+ *   `components/src/renderers/form/form.tsx` (the original);
+ * - the single-record action dialog — `CASCADE_OPTION_WIDGET_TYPES` in
+ *   `app-shell/src/views/ActionParamDialog.tsx` (objectui#3765 / PR #4756);
+ * - the bulk action dialog — the same name in
+ *   `plugin-grid/src/components/BulkActionDialog.tsx` (objectui#4757 / PR #4763).
+ *
+ * The set lives in `@object-ui/core`, next to the evaluator it describes,
+ * because core is the one package all three already depend on — the form layer
+ * cannot reach `@object-ui/fields` (that dependency runs the other way). Same
+ * shape and same reason as `EXPANDABLE_FIELD_TYPES` in
+ * `core/src/utils/expand-fields.ts`, the in-repo precedent for a form-layer
+ * allow-table more than one surface reads. `@object-ui/fields` re-exports it
+ * next to `resolveFormWidgetType` for discoverability — a re-export, never a
+ * second definition.
+ *
+ * ## An ALLOW-LIST, not a blanket pass-through
+ *
+ * `dependentValues` is also the channel two widget-hint pickers read a specific
+ * SIBLING KEY from (`filter-condition` reads `object_name`, `recipient-picker`
+ * reads `recipient_type`), and the lookup family filters its query by it. All
+ * three surfaces above agree today in NOT feeding those from action / bulk
+ * dialog params, but that is a different wiring question from the one ruled
+ * here and it has never been decided either way. Stated here so the three
+ * copies of the statement become one — the boundary itself stays open:
+ * objectui#4771.
+ *
+ * ## Normalization stays with the consumer
+ *
+ * The members are WIDGET keys — `resolveFormWidgetType` output in the two
+ * dialogs, `normalizeFieldType` output (the `field:` prefix stripped) in the
+ * form — not authored `type` spellings. Each consumer keeps its own
+ * normalization; the two normalizations agree on these four members, which is
+ * what makes one shared set safe to read from both.
+ *
+ * `select` + `multiple: true` is not listed separately: `SelectField` delegates
+ * to `MultiSelectField` with the whole prop object, so the key it resolves
+ * under (`select`) is the one that must carry the record.
+ */
+export const CASCADE_OPTION_WIDGET_TYPES = new Set([
+    'select',
+    'multiselect',
+    'radio',
+    'checkboxes',
+]);

package/dist/evaluator/rowPredicateCanon.d.ts

@@ -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.
+ */
+/** The one canonical row-predicate root. */
+export declare const ROW_PREDICATE_CANONICAL_ROOT = "record";
+/** A non-canonical row-predicate spelling, and the edit that fixes it. */
+export type NonCanonicalRowSpelling = {
+    /** Bare shorthand: `status == 'active'` — a field of THIS row, unrooted. */
+    kind: 'bare-shorthand';
+    /** The offending identifier (`status`). */
+    identifier: string;
+    /** What the author should write instead (`record.status`). */
+    canonical: string;
+} | {
+    /** Wrong-layer root: `data.status == 'active'` on a runtime record surface. */
+    kind: 'metadata-layer-root';
+    identifier: string;
+    canonical: string;
+};
+/**
+ * Detect a non-canonical spelling in ONE row predicate, or `null` when the
+ * predicate is already canonical (or is not this module's verdict to give).
+ *
+ * Deliberately conservative in both arms — every condition below can only
+ * REMOVE a finding, never invent one, because a false deprecation warning sends
+ * an author to rewrite a predicate that was correct:
+ *
+ * - **Unparseable source** → `null`. Syntax is another gate's verdict.
+ * - **Bare shorthand** is reported only when the undeclared identifier is an own
+ *   key of THIS row. That is what makes it unambiguously the #4075 shorthand
+ *   rather than a host-scope global this module cannot see (a deployment key
+ *   that is simply not in `SCOPE_ROOTS` would otherwise read as a bare field).
+ * - **`data.*`** is reported only when the caller confirms `data` names the row
+ *   (`dataNamesRow`). A surface whose `data` is the host scope's own — a
+ *   `rowless` dialog, a metadata-editing form — is a legitimate `data.*` site
+ *   and is left alone.
+ *
+ * Only the FIRST finding is returned, and the bare-shorthand arm is checked
+ * first: it is the arm the server refuses outright (`visibility-bare-identifier`
+ * is an `error` there, while a mis-layered root is a `warning`), so when a
+ * predicate manages both it is the one the author must fix to have anything
+ * evaluate at all.
+ *
+ * @param source       The predicate's CEL text. Callers must have already
+ *                     routed legacy `${…}`-dialect strings elsewhere — in that
+ *                     dialect `data.*` is the NORMAL spelling, and reporting it
+ *                     here would be a false positive on every legacy predicate.
+ * @param row          The row the predicate is bound against.
+ * @param dataNamesRow Whether `data` is bound to that same row on this surface.
+ */
+export declare function detectNonCanonicalRowSpelling(source: string, row: Record<string, unknown> | null | undefined, dataNamesRow: boolean): NonCanonicalRowSpelling | null;
+/** Reset the row-predicate spelling warn-once memo. Exported for tests. */
+export declare function resetRowPredicateCanonWarnings(): void;
+/**
+ * Report a non-canonical row-predicate spelling once, in dev.
+ *
+ * Phase 1 of the objectui#5330 window: the binding is UNCHANGED and every
+ * spelling still resolves — this only says so out loud, so the stored
+ * population stops growing and a later survey has something to count. It is a
+ * warning and deliberately not a refusal: turning it into one would move the
+ * accept/reject set, which this card is explicitly not entitled to do.
+ */
+export declare function warnNonCanonicalRowSpelling(source: string, row: Record<string, unknown> | null | undefined, dataNamesRow: boolean, label?: string): void;

package/dist/evaluator/rowPredicateCanon.js

@@ -0,0 +1,208 @@
+/**
+ * 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.
+ */
+/**
+ * The row-predicate spelling CANON, and the Phase-1 deprecation warning for the
+ * two spellings that are not it (objectui#5330).
+ *
+ * ## The canon (maintainer ruling, 2026-08-20 — option B)
+ *
+ * A row predicate — `visible` / `disabled` / `enabled` on an action renderer, a
+ * row scope, a `record:alert` — binds the row THREE ways today: canonical
+ * `record.status`, bare shorthand `status`, and legacy `data.status`
+ * (objectui#4075 / PR #4079 bound all four action renderers all three ways to
+ * restore consistency, deliberately without deciding which of them is
+ * CONTRACT). This module is where that decision now lives:
+ *
+ * > **The canon is `record.*`.** The bare shorthand and `data.*` are
+ * > client-side tolerances in a deprecation window, kept because stored
+ * > metadata carries them, warned about here, and removable only after a
+ * > stored-metadata survey sizes the window (⛔ no removal before the survey).
+ *
+ * It mirrors the objectstack#7917 option-② precedent for the identical shape (a
+ * renderer tolerance quietly becoming a second de-facto contract — AGENTS.md
+ * #0.1), whose objectui half is `utils/dashboard-filters.ts`' bare-string
+ * `options` shorthand: same three phases, same reason the warning is not
+ * decoration (ADR-0078 — nothing silently inert; a tolerance nothing ever
+ * reports can never be retired, because nothing would ever show that the last
+ * document carrying it is gone).
+ *
+ * ## The canon states the SERVER's accept set, not this client's
+ *
+ * The ruling made that the dev's first measurement, because a canon that only
+ * describes the renderer would be the very thing it exists to end. Measured
+ * against `@objectstack/formula@17.1.0` — the engine the server evaluates with,
+ * and the one `fieldRules.ts` already delegates to:
+ *
+ * | spelling | server runtime (`buildScope` + `celEngine`) | server authoring oracle |
+ * |---|---|---|
+ * | `record.status` | ✅ `{ ok: true, value: true }` | ✅ accepted |
+ * | bare `status`   | ❌ `Unknown variable: status` | ❌ refused (`'status'`) |
+ * | `data.status`   | ❌ `Unknown variable: data`   | ⚠️ **silently accepted** |
+ *
+ * `buildScope({ record })` mounts exactly `['record']` — `data` is never bound
+ * and the row's fields are never flattened to top level. So **the server
+ * accepts `record.*` and nothing else**; both other spellings fault there. The
+ * three-way binding is a client tolerance with no server counterpart, which is
+ * precisely why it is the client's job to warn.
+ *
+ * ⚠️ The `data.*` row is the dangerous one and the reason this warning exists
+ * at all. `data` IS in `@objectstack/formula`'s `SCOPE_ROOTS`, so the server's
+ * bare-identifier oracle waves `data.status` through — that list is a
+ * deliberately generous "never faults" LINT BASELINE, not the runtime accept
+ * set. A `data.*` row predicate therefore passes every authoring gate the
+ * platform has and then binds nothing at runtime: it is not an error, it is a
+ * constant `false`, and a `visible` that is constantly false is a button that
+ * silently never appears. That is the #4075 fail-closed family's exact
+ * signature, and this client is the only layer positioned to catch it.
+ *
+ * ## `data.*` is DEPRECATED HERE, not everywhere — the canon is layer-scoped
+ *
+ * `data` is the CANONICAL root one layer over, in a metadata-editing form (the
+ * row under edit): objectstack's `CANONICAL_ROOT_BY_LAYER` reads
+ * `{ runtime: 'record', metadata: 'data' }` (ADR-0089 D3), and objectui's own
+ * `app-shell` metadata-admin `SchemaForm` binds `{ data: row }` on purpose. So
+ * `data.*` is not a legacy alias to be deprecated platform-wide — it is a
+ * WRONG-LAYER paste on a runtime record surface, and only that is what this
+ * module reports. Stating the deprecation unqualified would contradict
+ * ADR-0089 D3 and break the metadata-editing layer's own contract.
+ *
+ * ## Why the detection reuses the server's oracle instead of a regex
+ *
+ * `collectCelRootIdentifiers` and `firstUndeclaredReference` are
+ * `@objectstack/formula` exports — the same two oracles objectstack's
+ * `visibility-bare-identifier` gate uses. Reading roots off the canonical AST
+ * rather than pattern-matching the source is what keeps this from inventing a
+ * second dialect judgement client-side: a string this module cannot parse is
+ * NOT this module's verdict to give (syntax belongs to the gates that own it),
+ * and it stands down rather than guessing.
+ */
+import { collectCelRootIdentifiers, firstUndeclaredReference } from '@objectstack/formula';
+/** The one canonical row-predicate root. */
+export const ROW_PREDICATE_CANONICAL_ROOT = 'record';
+/**
+ * The metadata-editing-form root (ADR-0089 D3). Canonical on THAT layer, and a
+ * wrong-layer paste on a runtime record surface — see the module note.
+ */
+const METADATA_LAYER_ROOT = 'data';
+/**
+ * Detect a non-canonical spelling in ONE row predicate, or `null` when the
+ * predicate is already canonical (or is not this module's verdict to give).
+ *
+ * Deliberately conservative in both arms — every condition below can only
+ * REMOVE a finding, never invent one, because a false deprecation warning sends
+ * an author to rewrite a predicate that was correct:
+ *
+ * - **Unparseable source** → `null`. Syntax is another gate's verdict.
+ * - **Bare shorthand** is reported only when the undeclared identifier is an own
+ *   key of THIS row. That is what makes it unambiguously the #4075 shorthand
+ *   rather than a host-scope global this module cannot see (a deployment key
+ *   that is simply not in `SCOPE_ROOTS` would otherwise read as a bare field).
+ * - **`data.*`** is reported only when the caller confirms `data` names the row
+ *   (`dataNamesRow`). A surface whose `data` is the host scope's own — a
+ *   `rowless` dialog, a metadata-editing form — is a legitimate `data.*` site
+ *   and is left alone.
+ *
+ * Only the FIRST finding is returned, and the bare-shorthand arm is checked
+ * first: it is the arm the server refuses outright (`visibility-bare-identifier`
+ * is an `error` there, while a mis-layered root is a `warning`), so when a
+ * predicate manages both it is the one the author must fix to have anything
+ * evaluate at all.
+ *
+ * @param source       The predicate's CEL text. Callers must have already
+ *                     routed legacy `${…}`-dialect strings elsewhere — in that
+ *                     dialect `data.*` is the NORMAL spelling, and reporting it
+ *                     here would be a false positive on every legacy predicate.
+ * @param row          The row the predicate is bound against.
+ * @param dataNamesRow Whether `data` is bound to that same row on this surface.
+ */
+export function detectNonCanonicalRowSpelling(source, row, dataNamesRow) {
+    if (typeof source !== 'string' || !source.trim())
+        return null;
+    const roots = collectCelRootIdentifiers(source);
+    // Not parseable through the canonical front end — not our verdict.
+    if (!roots || roots.ok !== true)
+        return null;
+    // (1) Bare shorthand — the arm the server refuses outright.
+    const bare = firstUndeclaredReference(source);
+    if (typeof bare === 'string' &&
+        row != null &&
+        typeof row === 'object' &&
+        Object.prototype.hasOwnProperty.call(row, bare)) {
+        return {
+            kind: 'bare-shorthand',
+            identifier: bare,
+            canonical: `${ROW_PREDICATE_CANONICAL_ROOT}.${bare}`,
+        };
+    }
+    // (2) Wrong-layer `data.*` root — silent at runtime on the server.
+    if (dataNamesRow && Array.isArray(roots.roots) && roots.roots.includes(METADATA_LAYER_ROOT)) {
+        return {
+            kind: 'metadata-layer-root',
+            identifier: METADATA_LAYER_ROOT,
+            canonical: ROW_PREDICATE_CANONICAL_ROOT,
+        };
+    }
+    return null;
+}
+/**
+ * Dev-mode gate, matching `utils/dashboard-filters.ts` and `actions/actionKeys.ts`
+ * — a deprecation warning that floods a production console is a warning that
+ * gets muted.
+ */
+const isDev = () => globalThis.process?.env
+    ?.NODE_ENV !== 'production';
+/**
+ * Warn-once memo, keyed by the `(label, predicate source)` pair — the same
+ * identity `warnEvalError` uses, and JSON-encoded for the same reason: the
+ * separator that boundary once used was a raw U+0000, which made the file
+ * carrying it binary to grep (objectstack#5450). Keying on the source alone
+ * would report the first surface carrying a shorthand `status` predicate and
+ * stay silent about every other one; the label is what sends the author to the
+ * right screen.
+ *
+ * Module scope, not per-call: these predicates are re-evaluated on every row of
+ * every render, so per-call state would warn once per frame — the flood the
+ * dedupe exists to prevent.
+ */
+const warnedSpellings = new Set();
+/** Reset the row-predicate spelling warn-once memo. Exported for tests. */
+export function resetRowPredicateCanonWarnings() {
+    warnedSpellings.clear();
+}
+/**
+ * Report a non-canonical row-predicate spelling once, in dev.
+ *
+ * Phase 1 of the objectui#5330 window: the binding is UNCHANGED and every
+ * spelling still resolves — this only says so out loud, so the stored
+ * population stops growing and a later survey has something to count. It is a
+ * warning and deliberately not a refusal: turning it into one would move the
+ * accept/reject set, which this card is explicitly not entitled to do.
+ */
+export function warnNonCanonicalRowSpelling(source, row, dataNamesRow, label) {
+    if (!isDev())
+        return;
+    const finding = detectNonCanonicalRowSpelling(source, row, dataNamesRow);
+    if (!finding)
+        return;
+    const key = JSON.stringify([label ?? '', source, finding.kind]);
+    if (warnedSpellings.has(key))
+        return;
+    warnedSpellings.add(key);
+    const where = label ? ` (${label})` : '';
+    const detail = finding.kind === 'bare-shorthand'
+        ? `it references the bare field ${JSON.stringify(finding.identifier)}; ` +
+            `the server refuses that spelling outright ("Unknown variable: ${finding.identifier}")`
+        : 'it is rooted at `data.`, which is the metadata-editing-form root — on a ' +
+            'record surface the server binds no `data` at all, so the predicate is a ' +
+            'constant false there rather than an error';
+    console.warn(`[object-ui] A row predicate${where} uses a DEPRECATED spelling: ` +
+        `${JSON.stringify(source)} — ${detail}. The canon is \`record.*\` ` +
+        `(objectui#5330, ruled 2026-08-20): write \`${finding.canonical}\`. ` +
+        'This still evaluates here for now; the tolerance retires after a ' +
+        'stored-metadata survey.');
+}

package/dist/index.d.ts

@@ -18,6 +18,8 @@ export * from './utils/filter-converter.js';
 export * from './utils/managedBy.js';
 export * from './utils/extract-records.js';
 export * from './utils/expand-fields.js';
+export * from './utils/retired-field-types.js';
+export * from './utils/unmaterialized-fields.js';
 export * from './utils/column-identity.js';
 export * from './utils/sort-values.js';
 export * from './utils/sort-query.js';
@@ -49,6 +51,7 @@ export * from './utils/dashboard-filters.js';
 export * from './utils/merge-filters.js';
 export * from './utils/compare-to.js';
 export * from './utils/chart-series.js';
+export * from './utils/chart-presentation.js';
 export * from './utils/number-display.js';
 export * from './utils/dataset-format.js';
 export * from './utils/dataset-pivot.js';
@@ -58,3 +61,4 @@ export * from './utils/reference-keys.js';
 export * from './utils/predicate-record.js';
 export * from './utils/predicate-fields.js';
 export * from './utils/normalize-list-view.js';
+export * from './utils/humanize-label.js';

package/dist/index.js

@@ -22,6 +22,13 @@ export * from './utils/filter-converter.js';
 export * from './utils/managedBy.js';
 export * from './utils/extract-records.js';
 export * from './utils/expand-fields.js';
+// The RETIREMENT gate (objectui#4914, maintainer ruling B). Homed here rather
+// than in `@object-ui/fields` because `@object-ui/components` is one of its six
+// consumers and `fields` depends on `components` — see the module's docblock
+// for why a second copy was not an option. `@object-ui/fields` re-exports every
+// name, so its published surface is unchanged.
+export * from './utils/retired-field-types.js';
+export * from './utils/unmaterialized-fields.js';
 export * from './utils/column-identity.js';
 export * from './utils/sort-values.js';
 export * from './utils/sort-query.js';
@@ -56,6 +63,10 @@ export * from './utils/dashboard-filters.js';
 export * from './utils/merge-filters.js';
 export * from './utils/compare-to.js';
 export * from './utils/chart-series.js';
+// The AUTHORED half of a dataset-bound chart (objectui#4229's data/presentation
+// split), shared by the dashboard widget and the report's embedded chart so the
+// same spec keys are lowered identically on both (objectui#4877).
+export * from './utils/chart-presentation.js';
 // The ONE number-display formatter (objectui#4033) — grouping policy, display
 // locale and the percent convention. It lived in `@object-ui/i18n` until
 // objectui#4576; it is pure, and living above `core` was what kept
@@ -79,3 +90,9 @@ export * from './utils/predicate-record.js';
 // which the column-derived `$select` never asked the server for.
 export * from './utils/predicate-fields.js';
 export * from './utils/normalize-list-view.js';
+// The single home for the VALUE fallback prettifier (a stored value becomes a
+// display string when nothing resolves it). `@object-ui/fields` and
+// `@object-ui/plugin-charts` each carried a byte-identical private copy;
+// both now re-export this one (objectui#5444). Its docstring also records why
+// it stays distinct from `humanizeFieldKey`, the KEY fallback.
+export * from './utils/humanize-label.js';