@object-ui/react 17.5.0 → 17.6.0

package/dist/hooks/useExpression.d.ts

@@ -87,6 +87,25 @@ export { toPredicateInput } from '@object-ui/core';
  * and the four generic action renderers carried the same root-only binding
  * until objectui#4075.
  *
+ * ## The canon is `record.*` (objectui#5330, ruled 2026-08-20)
+ *
+ * All three spellings are bound here, and that is unchanged — but they are NOT
+ * peers. `record.*` is the CONTRACT; the bare shorthand and `data.*` are
+ * tolerances in a deprecation window, kept because stored metadata carries
+ * them, reported once by `warnNonCanonicalRowSpelling` from `useCondition`
+ * below, and removable only after a stored-metadata survey sizes the window
+ * (⛔ no removal before the survey — part of the same ruling).
+ *
+ * The canon states the SERVER's accept set, which is narrower than this bag:
+ * measured on `@objectstack/formula@17.1.0`, `buildScope({ record })` mounts
+ * exactly `['record']`, so of the three spellings this helper binds, only
+ * `record.*` evaluates server-side — a bare field faults `Unknown variable:
+ * status` and `data.*` faults `Unknown variable: data`. This three-way bag has
+ * no server counterpart at all, which is exactly why the warning belongs on
+ * this side. `@object-ui/core`'s `evaluator/rowPredicateCanon.ts` carries the
+ * full measurement and the layer scoping (`data` stays canonical one layer
+ * over, in a metadata-editing form — ADR-0089 D3).
+ *
  * `record` and `data` are written AFTER the spread deliberately: a row that
  * happens to carry a field literally named `record` or `data` must not shadow
  * the root every predicate is written against. Same precedence as
@@ -140,9 +159,11 @@ export declare function useCondition(condition: string | boolean | undefined | {
  * routes to `@object-ui/core`'s `evalRowPredicate`: a bare string is CEL (the
  * spec contract for `ActionSchema.visible`), a `{ dialect: 'cel', source }`
  * envelope is always CEL, and only a legacy-dialect string falls back to the
- * old engine (with a deprecation warning). The row is bound as `record.*` and
- * bare fields; the ambient predicate scope (`features` / `user` / …) is merged
- * alongside so deployment-level gates keep resolving.
+ * old engine (with a deprecation warning). The row is bound as `record.*` — the
+ * CANON (objectui#5330) — and, for stored metadata only, as bare fields and
+ * `data.*`, both of which now warn once; the ambient predicate scope
+ * (`features` / `user` / …) is merged alongside so deployment-level gates keep
+ * resolving.
  *
  * @param pred     The raw predicate: `boolean` (returned as-is), a CEL string,
  *                 an `{ dialect, source }` envelope, or `null`/`undefined`/`''`.

package/dist/hooks/useExpression.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { createContext, createElement, useContext, useMemo } from 'react';
-import { ExpressionEvaluator, evalRowPredicate } from '@object-ui/core';
+import { ExpressionEvaluator, evalRowPredicate, isLegacyDialectSource, warnNonCanonicalRowSpelling, } from '@object-ui/core';
 /**
  * Global predicate scope — populated by host shells (e.g. app-shell's
  * `ExpressionProvider`) so renderers like action buttons can resolve
@@ -101,6 +101,25 @@ export { toPredicateInput } from '@object-ui/core';
  * and the four generic action renderers carried the same root-only binding
  * until objectui#4075.
  *
+ * ## The canon is `record.*` (objectui#5330, ruled 2026-08-20)
+ *
+ * All three spellings are bound here, and that is unchanged — but they are NOT
+ * peers. `record.*` is the CONTRACT; the bare shorthand and `data.*` are
+ * tolerances in a deprecation window, kept because stored metadata carries
+ * them, reported once by `warnNonCanonicalRowSpelling` from `useCondition`
+ * below, and removable only after a stored-metadata survey sizes the window
+ * (⛔ no removal before the survey — part of the same ruling).
+ *
+ * The canon states the SERVER's accept set, which is narrower than this bag:
+ * measured on `@objectstack/formula@17.1.0`, `buildScope({ record })` mounts
+ * exactly `['record']`, so of the three spellings this helper binds, only
+ * `record.*` evaluates server-side — a bare field faults `Unknown variable:
+ * status` and `data.*` faults `Unknown variable: data`. This three-way bag has
+ * no server counterpart at all, which is exactly why the warning belongs on
+ * this side. `@object-ui/core`'s `evaluator/rowPredicateCanon.ts` carries the
+ * full measurement and the layer scoping (`data` stays canonical one layer
+ * over, in a metadata-editing form — ADR-0089 D3).
+ *
  * `record` and `data` are written AFTER the spread deliberately: a row that
  * happens to carry a field literally named `record` or `data` must not shadow
  * the root every predicate is written against. Same precedence as
@@ -169,6 +188,37 @@ export function useCondition(condition, context = {}, options) {
     const scope = usePredicateScope();
     // We evaluate directly without caching the evaluator to avoid issues with context changes
     return useMemo(() => {
+        // objectui#5330 Phase 1 — report a deprecated row-predicate spelling on
+        // the `useCondition` tier. This is the BINDING half's evaluation entry:
+        // `usePredicateRecordContext` sees the row but never the predicate text,
+        // so it structurally cannot detect a spelling, and this is the first
+        // point where the two meet.
+        //
+        // Two guards, both of which can only remove a report:
+        //  - the bag must carry the `usePredicateRecordContext` signature, `data`
+        //    and `record` being the SAME object by identity. A host scope that
+        //    merely happens to carry a `data` key cannot satisfy that, so a
+        //    non-row `useCondition` call is never judged as a row predicate.
+        //  - the source must be CEL. In this tier's legacy `${…}` dialect
+        //    (`'${data.status === "active"}'` — this hook's own doc example)
+        //    `data.*` is the NORMAL spelling, and reporting it would be a false
+        //    positive on every legacy predicate.
+        const bag = context;
+        const boundRow = bag.record != null && typeof bag.record === 'object' && bag.record === bag.data
+            ? bag.record
+            : undefined;
+        if (boundRow !== undefined) {
+            const celSource = typeof condition === 'string'
+                ? isLegacyDialectSource(condition)
+                    ? undefined
+                    : condition
+                : condition && typeof condition === 'object' && condition.dialect === 'cel'
+                    ? condition.source
+                    : undefined;
+            if (typeof celSource === 'string') {
+                warnNonCanonicalRowSpelling(celSource, boundRow, true, options?.label);
+            }
+        }
         const evaluator = new ExpressionEvaluator({ ...scope, ...context });
         if (options?.throwOnError) {
             // Fail-closed: a predicate that can't be evaluated hides/disables
@@ -206,9 +256,11 @@ export function useCondition(condition, context = {}, options) {
  * routes to `@object-ui/core`'s `evalRowPredicate`: a bare string is CEL (the
  * spec contract for `ActionSchema.visible`), a `{ dialect: 'cel', source }`
  * envelope is always CEL, and only a legacy-dialect string falls back to the
- * old engine (with a deprecation warning). The row is bound as `record.*` and
- * bare fields; the ambient predicate scope (`features` / `user` / …) is merged
- * alongside so deployment-level gates keep resolving.
+ * old engine (with a deprecation warning). The row is bound as `record.*` — the
+ * CANON (objectui#5330) — and, for stored metadata only, as bare fields and
+ * `data.*`, both of which now warn once; the ambient predicate scope
+ * (`features` / `user` / …) is merged alongside so deployment-level gates keep
+ * resolving.
  *
  * @param pred     The raw predicate: `boolean` (returned as-is), a CEL string,
  *                 an `{ dialect, source }` envelope, or `null`/`undefined`/`''`.

package/dist/hooks/useNavigationOverlay.d.ts

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { NavigationConfigSchema, NavigationMode as SpecNavigationMode } from '@objectstack/spec/ui';
-import type { SpecAuthoredInput } from '../spec-input';
+import type { SpecAuthoredInput } from '../spec-input.js';
 /**
  * The spec's `NavigationConfigSchema`, authoring side — by reference, with no
  * divergence of its own.

package/dist/hooks/usePageAssignment.js

@@ -24,7 +24,7 @@
  * when no record Page is authored.
  */
 import { useEffect, useMemo, useState } from 'react';
-import { useMetadata } from '../context/AppShellContext';
+import { useMetadata } from '../context/AppShellContext.js';
 function matchesAssignment(_page, _opts) {
     // Placeholder — every page matches until rules-based assignment lands.
     return true;

package/dist/hooks/usePageTransition.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useMemo } from 'react';
-import { useReducedMotion } from './useReducedMotion';
+import { useReducedMotion } from './useReducedMotion.js';
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------

package/dist/hooks/usePageVariableActionBridge.js

@@ -6,8 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import * as React from 'react';
-import { usePageVariables } from './usePageVariables';
-import { useAction } from '../context';
+import { usePageVariables } from './usePageVariables.js';
+import { useAction } from '../context/index.js';
 /**
  * PageVariableActionBridge — publishes the live page-variable snapshot into the
  * shared ActionRunner context as `pageVariables`, so a submit action (`api` /

package/dist/hooks/useViewData.js

@@ -10,7 +10,7 @@
  */
 import { useState, useEffect, useCallback, useMemo, useContext } from 'react';
 import { resolveDataSource } from '@object-ui/core';
-import { SchemaRendererContext } from '../context/SchemaRendererContext';
+import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
 // ---------------------------------------------------------------------------
 // Hook
 // ---------------------------------------------------------------------------

package/dist/hooks/useViewTransition.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useState, useCallback, useMemo } from 'react';
-import { useReducedMotion } from './useReducedMotion';
+import { useReducedMotion } from './useReducedMotion.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------

package/dist/index.d.ts

@@ -5,15 +5,15 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export * from './SchemaRenderer';
-export * from './schema-input';
-export * from './hooks';
-export * from './context';
-export * from './LazyPluginLoader';
-export * from './spec-bridge';
-export * from './data-invalidation';
-export * from './element-data-source/ElementDataSourceGate';
-export { resolveKeyedI18nLabel } from './utils/i18n';
-export { extractWriteErrorMessage, isPermissionError, extractFieldErrors } from './utils/error-message';
-export type { WriteFieldError } from './utils/error-message';
+export * from './SchemaRenderer.js';
+export * from './schema-input.js';
+export * from './hooks/index.js';
+export * from './context/index.js';
+export * from './LazyPluginLoader.js';
+export * from './spec-bridge/index.js';
+export * from './data-invalidation.js';
+export * from './element-data-source/ElementDataSourceGate.js';
+export { resolveKeyedI18nLabel } from './utils/i18n.js';
+export { extractWriteErrorMessage, isPermissionError, extractFieldErrors, classifyLoadError, declaredUserMessage } from './utils/error-message.js';
+export type { WriteFieldError, LoadErrorKind } from './utils/error-message.js';
 export { I18nProvider, useObjectTranslation, useSafeTranslate, useObjectLabel, useSafeFieldLabel, useI18nContext, createI18n, getDirection, getAvailableLanguages, formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type I18nConfig, type I18nProviderProps, type TranslationKeys, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from '@object-ui/i18n';

package/dist/index.js

@@ -5,20 +5,20 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export * from './SchemaRenderer';
-export * from './schema-input';
-export * from './hooks'; // will be empty for now
-export * from './context'; // will be empty for now
-export * from './LazyPluginLoader';
-export * from './spec-bridge';
-export * from './data-invalidation';
+export * from './SchemaRenderer.js';
+export * from './schema-input.js';
+export * from './hooks/index.js'; // will be empty for now
+export * from './context/index.js'; // will be empty for now
+export * from './LazyPluginLoader.js';
+export * from './spec-bridge/index.js';
+export * from './data-invalidation.js';
 // PageComponentSchema.dataSource — mapping the spec's per-element data binding
 // onto the schema keys each object-bound block reads (objectstack#6953).
-export * from './element-data-source/ElementDataSourceGate';
+export * from './element-data-source/ElementDataSourceGate.js';
 // i18n utilities
-export { resolveKeyedI18nLabel } from './utils/i18n';
+export { resolveKeyedI18nLabel } from './utils/i18n.js';
 // Write-error surfacing utilities (shared by drag-write plugins so a failed
 // PATCH — e.g. an RLS 403 — is never silently swallowed).
-export { extractWriteErrorMessage, isPermissionError, extractFieldErrors } from './utils/error-message';
+export { extractWriteErrorMessage, isPermissionError, extractFieldErrors, classifyLoadError, declaredUserMessage } from './utils/error-message.js';
 // Built-in i18n support
 export { I18nProvider, useObjectTranslation, useSafeTranslate, useObjectLabel, useSafeFieldLabel, useI18nContext, createI18n, getDirection, getAvailableLanguages, formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, } from '@object-ui/i18n';

package/dist/schema-input.d.ts

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { BaseSchema } from '@object-ui/types';
-import type { SchemaRendererProps } from './SchemaRenderer';
+import type { SchemaRendererProps } from './SchemaRenderer.js';
 /**
  * Narrow a loosely-typed metadata node onto {@link SchemaRendererProps.schema}.
  *
@@ -23,9 +23,20 @@ import type { SchemaRendererProps } from './SchemaRenderer';
  * tells no lie — the value a caller forwards renders identically whether or not
  * it passes through here.
  *
- * It exists because the two competing repo-wide `SchemaNode` spellings
- * (`@object-ui/core`'s interface vs `@object-ui/types`' union) have not been
- * reconciled; that reconciliation is tracked separately. When it lands, the
- * call sites using this can go back to forwarding directly.
+ * The bridge is PERMANENT — not scaffolding awaiting a merge. The two competing
+ * repo-wide `SchemaNode` spellings ARE reconciled (objectui#4580, PR #4608):
+ * `@object-ui/core` stopped hand-declaring its own interface and now re-exports
+ * `@object-ui/types`' union, so one declaration is left to disagree with. That
+ * reconciliation resolved in favour of the UNION, while `SchemaRenderer`'s prop
+ * stays deliberately narrow (objectui#4548 ruling Q2 — it declares no `number`
+ * or `boolean`), so a `SchemaNode` is now LESS assignable to that prop than it
+ * was, not more. This step therefore bridges two intentionally different types,
+ * and it stays. ⛔ Do not "tidy" a call site back into a direct forward: the
+ * five `apps/site` sites that were forwarding directly when PR #4608 landed are
+ * what kept `Build Docs` red on `main` for ~5 hours — each one a TS2322 naming
+ * `number` against this function's return type, spelled
+ * `string | BaseSchema | null | undefined` in objectui#4617's logs — until
+ * PR #4621 routed all five through here. An earlier revision of this paragraph
+ * said the reconciliation was still pending and invited exactly that edit.
  */
 export declare function toRenderableSchema(node: BaseSchema | string | number | boolean | null | undefined): SchemaRendererProps['schema'];

package/dist/schema-input.js

@@ -21,10 +21,21 @@
  * tells no lie — the value a caller forwards renders identically whether or not
  * it passes through here.
  *
- * It exists because the two competing repo-wide `SchemaNode` spellings
- * (`@object-ui/core`'s interface vs `@object-ui/types`' union) have not been
- * reconciled; that reconciliation is tracked separately. When it lands, the
- * call sites using this can go back to forwarding directly.
+ * The bridge is PERMANENT — not scaffolding awaiting a merge. The two competing
+ * repo-wide `SchemaNode` spellings ARE reconciled (objectui#4580, PR #4608):
+ * `@object-ui/core` stopped hand-declaring its own interface and now re-exports
+ * `@object-ui/types`' union, so one declaration is left to disagree with. That
+ * reconciliation resolved in favour of the UNION, while `SchemaRenderer`'s prop
+ * stays deliberately narrow (objectui#4548 ruling Q2 — it declares no `number`
+ * or `boolean`), so a `SchemaNode` is now LESS assignable to that prop than it
+ * was, not more. This step therefore bridges two intentionally different types,
+ * and it stays. ⛔ Do not "tidy" a call site back into a direct forward: the
+ * five `apps/site` sites that were forwarding directly when PR #4608 landed are
+ * what kept `Build Docs` red on `main` for ~5 hours — each one a TS2322 naming
+ * `number` against this function's return type, spelled
+ * `string | BaseSchema | null | undefined` in objectui#4617's logs — until
+ * PR #4621 routed all five through here. An earlier revision of this paragraph
+ * said the reconciliation was still pending and invited exactly that edit.
  */
 export function toRenderableSchema(node) {
     return typeof node === 'number' || typeof node === 'boolean' ? String(node) : node;

package/dist/spec-bridge/SpecBridge.d.ts

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { BaseSchema } from '@object-ui/types';
-import type { BridgeContext, BridgeFn } from './types';
+import type { BridgeContext, BridgeFn } from './types.js';
 export declare class SpecBridge {
     private bridges;
     private context;

package/dist/spec-bridge/SpecBridge.js

@@ -5,8 +5,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { bridgeListView } from './bridges/list-view';
-import { bridgeFormView } from './bridges/form-view';
+import { bridgeListView } from './bridges/list-view.js';
+import { bridgeFormView } from './bridges/form-view.js';
 export class SpecBridge {
     constructor(context = {}) {
         Object.defineProperty(this, "bridges", {

package/dist/spec-bridge/bridges/form-view.d.ts

@@ -5,8 +5,68 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { BridgeFn } from '../types';
-interface FormField {
+/**
+ * Form-view bridge input — the documented SUBSET of `@objectstack/spec`'s
+ * FormViewSchema this bridge consumes, with every drift-prone key's TYPE bound
+ * to the contract instead of restated (objectui#5652).
+ *
+ * The subset stays hand-listed on purpose: this declaration is load-bearing
+ * documentation, and its NON-declarations are a retirement ledger
+ * (`defaultSort` / `aria`, objectui#3901 / #3974) that a blanket
+ * `Omit<FormView, ...>` would erase. What was never deliberate is the TYPE each
+ * declared key was given. Three of them had drifted from what the contract
+ * accepts, and nothing ever compared the two descriptions — the mirror shape
+ * `scripts/check-spec-symbol-derivation.mjs` exists to catch. The sibling
+ * bridge in this directory (`list-view.ts`) was converted the same way and for
+ * the same reason (objectui#2231): the shape derives, so it cannot drift.
+ *
+ * ## What the contract actually answers
+ *
+ * Measured with `safeParse` against the installed `@objectstack/spec` while
+ * fixing this, NOT copied from the finding — two of its three rows were wrong,
+ * in ways that change the repair:
+ *
+ *   FormSection.columns    `1 | 2 | 3 | 4 | '1' | '2' | '3' | '4'`. The string
+ *                          arm IS admitted, and the section schema's own pipe
+ *                          folds it to a number. The bridge declared `number`
+ *                          and refused it.
+ *   FormView.columns       `number`, with NO string arm: `FormViewSchema`
+ *                          rejects `columns: '3'` at the FORM level while
+ *                          `FormSectionSchema` accepts it at the SECTION level.
+ *                          The bridge's `number` was already right here — it is
+ *                          bound to the contract so the asymmetry cannot rot,
+ *                          and the two answers are pinned side by side.
+ *   FormField.dependsOn    a BARE parent-field name. The array arm is rejected
+ *                          by the contract outright. The bridge declared
+ *                          `string[]`, so it admitted only the arm the contract
+ *                          refuses and refused the only arm it admits — the one
+ *                          configuration that makes `field-selector` and
+ *                          `dynamic-config` work (objectui#5040).
+ *   *.visibleWhen          `string | { dialect, source?, ast?, meta? }`, with
+ *                          `dialect` REQUIRED and enum-typed. `{ dialect?,
+ *                          source }` is a DIFFERENT layer's type — the
+ *                          evaluator's `FieldRulePredicate` (`@object-ui/core`,
+ *                          ADR-0089) — and the contract does not accept it: an
+ *                          object arm without `dialect` is refused. The bridge
+ *                          declared `string` and refused the object arm
+ *                          entirely.
+ *
+ * ## Declaring an arm is not consuming it
+ *
+ * A key that is declarable but dropped on the way out is the same defect one
+ * layer over (objectui#5542 / #5594), so each widened arm is followed all the
+ * way onto the `object-form` node by `FormViewWidenedArms.test.ts`, and the one
+ * arm that needs a translation to get there gets it — see `normalizeColumns`.
+ */
+import type { DependsOnInput } from '@object-ui/types';
+import type { FormFieldInput, FormSection, FormView } from '@objectstack/spec/ui';
+import type { BridgeFn } from '../types.js';
+/**
+ * A form field as authored. Exported so the derivation pins in
+ * `__tests__/FormViewWidenedArms.test.ts` can name the declared types; NOT
+ * re-exported by `spec-bridge/index.ts`, so the package surface is unchanged.
+ */
+export interface FormFieldSpec {
     field: string;
     /** Field type (spec FormFieldSchema reuses Data.FieldType; auto-infers widget). */
     type?: string;
@@ -22,23 +82,45 @@ interface FormField {
     hidden?: boolean;
     colSpan?: number;
     widget?: string;
-    dependsOn?: string[];
-    /** Canonical conditional-visibility predicate (ADR-0089). */
-    visibleWhen?: string;
-    /** @deprecated ADR-0089 → `visibleWhen`. */
-    visibleOn?: string;
+    /**
+     * Sibling field name whose value this field's widget reads (objectui#5040).
+     *
+     * The contract admits a BARE NAME and refuses an array. This is the wider
+     * {@link DependsOnInput} rather than the contract's `string` alone because
+     * the value is FORWARDED, unread, into the node slot that is declared with
+     * exactly this type (`FormField.dependsOn`, `@object-ui/types`) and read by
+     * `resolveCascadingOptions` / `resolveDependsOnFields` (`@object-ui/core`),
+     * whose parameter is also exactly this type (framework#4074). Narrowing to
+     * the contract's `string` would refuse array-authored layouts that the
+     * runtime has always honoured, on the same never-parsed inputs `groups` and
+     * `visibleOn` below are still read for. The contract's arm is a subset of
+     * this one, which is what the derivation pin asserts — so a spec that widens
+     * `dependsOn` fails the pin instead of silently outgrowing the declaration.
+     */
+    dependsOn?: DependsOnInput;
+    /** Canonical conditional-visibility predicate (ADR-0089), bound to the contract. */
+    visibleWhen?: FormFieldInput['visibleWhen'];
+    /** @deprecated ADR-0089 -> `visibleWhen`. */
+    visibleOn?: FormFieldInput['visibleOn'];
 }
-interface FormSection {
+/** One section of a form layout, as authored. */
+export interface FormSectionSpec {
     /** Stable section identifier for i18n lookup (spec FormSectionSchema.name). */
     name?: string;
     label?: string;
     description?: string;
     collapsible?: boolean;
     collapsed?: boolean;
-    columns?: number;
-    /** Section-level conditional-visibility predicate (ADR-0089). */
-    visibleWhen?: string;
-    fields?: FormField[];
+    /** Bound to the contract: the string spelling of a column count is admitted. */
+    columns?: FormSection['columns'];
+    /** Section-level conditional-visibility predicate (ADR-0089), bound to the contract. */
+    visibleWhen?: FormSection['visibleWhen'];
+    /**
+     * The authored field list. A bare string is the spec's shorthand for "this
+     * object's own field, rendered with its defaults" — the same shorthand
+     * `mapColumn` already honours on the list bridge.
+     */
+    fields?: Array<string | FormFieldSpec>;
 }
 /**
  * The subset of `@objectstack/spec` FormViewSchema the bridge consumes.
@@ -46,10 +128,11 @@ interface FormSection {
  * or listed here with an explicit reason for being ignored — the bridge must
  * never silently drop spec configuration (#2545).
  */
-interface FormViewSpec {
+export interface FormViewSpec {
     type?: string;
     layout?: string;
-    columns?: number;
+    /** Bound to the contract, which admits NO string arm here — unlike a section. */
+    columns?: FormView['columns'];
     title?: string;
     description?: string;
     defaultTab?: string;
@@ -63,20 +146,13 @@ interface FormViewSpec {
     drawerWidth?: string;
     modalSize?: string;
     data?: any;
-    sections?: FormSection[];
+    sections?: FormSectionSpec[];
     /** Legacy alias of `sections` (spec: "Legacy support → alias to sections"). */
-    groups?: FormSection[];
+    groups?: FormSectionSpec[];
     /** Inline master-detail child collections. */
     subforms?: any[];
-    defaultSort?: any;
     sharing?: any;
-    aria?: {
-        ariaLabel?: string;
-        ariaDescribedBy?: string;
-        role?: string;
-    };
     submitBehavior?: any;
 }
 /** Transforms a FormView spec into a Form SchemaNode */
 export declare const bridgeFormView: BridgeFn<FormViewSpec>;
-export {};

package/dist/spec-bridge/bridges/form-view.js

@@ -5,6 +5,21 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * Fold the contract's string spelling of a column count onto the number the
+ * node carries.
+ *
+ * `FormSectionSchema` accepts `'2'` and `2` and normalises the string away in
+ * its own pipe; the `object-form` node's section declares `columns?: 1|2|3|4`
+ * and `FormSectionContainer` indexes its grid-class map by that number. Its
+ * header states where the fold belongs: "The normalisation belongs at the seam
+ * that parses authored metadata, not in the container's props." This bridge is
+ * that seam. Forwarding `'2'` verbatim hands every downstream renderer a value
+ * outside the type it declares.
+ */
+function normalizeColumns(columns) {
+    return typeof columns === 'string' ? Number(columns) : columns;
+}
 function mapField(field) {
     const mapped = {
         name: field.field,
@@ -30,12 +45,23 @@ function mapField(field) {
         mapped.colSpan = field.colSpan;
     if (field.widget)
         mapped.widget = field.widget;
+    // Forwarded unread into the node's `dependsOn`, which is declared with the
+    // same type and read by `@object-ui/core`'s cascading-option resolver.
     if (field.dependsOn)
         mapped.dependsOn = field.dependsOn;
     // ADR-0089: `visibleWhen` is the canonical view-form-field visibility predicate
     // (the spec folds the deprecated `visibleOn` into it at parse). Prefer it and
     // fall back to `visibleOn` for raw / un-normalized metadata. The ObjectForm
     // renderer reads this view-level predicate from the node's `visibleOn` slot.
+    //
+    // Both contract arms travel whole: the bare CEL string, and the expression
+    // object. `evalFieldPredicate` reads `{ dialect, source }` back out of the
+    // object arm, which is how a spec-authored `{ dialect: 'cel', source: ... }`
+    // now drives visibility instead of being refused by this declaration. An
+    // `ast`-only expression (legal metadata: the contract requires `dialect` plus
+    // one of `source` / `ast`) is forwarded whole rather than dropped, but no
+    // evaluator in this repo reads an `ast` today — that gap is the evaluator's,
+    // and the bridge must not hide it by discarding the key.
     const visiblePredicate = field.visibleWhen ?? field.visibleOn;
     if (visiblePredicate)
         mapped.visibleOn = visiblePredicate;
@@ -43,7 +69,12 @@ function mapField(field) {
 }
 function mapSection(section) {
     const mapped = {
-        fields: (section.fields ?? []).map(mapField),
+        // A bare field name is the spec's shorthand and is forwarded verbatim: the
+        // node's `fields` slot admits it and `normalizeSectionField`
+        // (@object-ui/plugin-form) resolves it against the object schema. Running
+        // it through `mapField` instead produced `{ name: undefined }` — a field
+        // with no identity — for the most ordinary section a form can declare.
+        fields: (section.fields ?? []).map((field) => typeof field === 'string' ? field : mapField(field)),
     };
     if (section.name)
         mapped.name = section.name;
@@ -56,7 +87,8 @@ function mapSection(section) {
     if (section.collapsed != null)
         mapped.collapsed = section.collapsed;
     if (section.columns != null)
-        mapped.columns = section.columns;
+        mapped.columns = normalizeColumns(section.columns);
+    // Whole, both arms — same predicate contract as the field above.
     if (section.visibleWhen)
         mapped.visibleWhen = section.visibleWhen;
     return mapped;
@@ -113,14 +145,26 @@ export const bridgeFormView = (spec, _context) => {
         if (spec[key] != null)
             node[key] = spec[key];
     }
-    if (spec.defaultSort)
-        node.defaultSort = spec.defaultSort;
     if (spec.submitBehavior)
         node.submitBehavior = spec.submitBehavior;
-    // P1.6 — i18n & ARIA
+    // P1.6 — sharing
     if (spec.sharing)
         node.sharing = spec.sharing;
-    if (spec.aria)
-        node.aria = spec.aria;
+    // `defaultSort` (#3974) and `aria` (#3901) USED to be copied here. Both are
+    // `retiredKey()` tombstones on spec 17's FormViewSchema, so a FormView that
+    // parsed can never carry either — the guards were unreachable, and their
+    // shape invited the next reader to copy a dead pattern. Removed under the
+    // maintainer's 2026-08-11 enforce-or-remove ruling; measured dormant at BOTH
+    // ends before removal:
+    //   - producer: `FormViewSchema.safeParse` rejects both keys by name
+    //     (`form.defaultSort` / `form.aria` removed in the #3896 close-out).
+    //   - consumer: no form renderer reads either off the node — plugin-form
+    //     reads neither, and `SchemaRenderer`'s generic ARIA injection resolves
+    //     FLAT `ariaLabel`/`ariaDescribedBy`/`role` (SchemaRenderer.tsx:109-119),
+    //     never a nested `aria` object.
+    // The nested `aria` copy is still correct on the LIST bridge
+    // (`list-view.ts:214`), whose carrier stayed live and IS consumed at
+    // `plugin-list/src/ListView.tsx:2389-2392` — do not "align" the two.
+    // Pinned by `__tests__/FormViewRetiredKeys.test.ts`.
     return node;
 };

package/dist/spec-bridge/bridges/list-view.d.ts

@@ -5,7 +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 type { BridgeFn } from '../types';
+import type { BridgeFn } from '../types.js';
 import type { ListView } from '@objectstack/spec/ui';
 /**
  * Bridge input: the spec-canonical ListView (#2231 — the former hand-written