@object-ui/core 16.1.0 → 17.1.0

package/dist/utils/filter-tokens.js

@@ -0,0 +1,173 @@
+/**
+ * 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.
+ */
+import { resolveDateMacros } from './date-macros.js';
+/**
+ * Session-scoped filter placeholders — the sibling vocabulary to
+ * `{date-macros}`.
+ *
+ * Filter values travel as JSON, so a user-scoped slice cannot call
+ * `currentUser().id` inline; it writes a placeholder that this module expands
+ * immediately before the filter reaches the data source:
+ *
+ *     { owner_id: '{current_user_id}' }
+ *
+ * ## Why this module exists (framework #3574)
+ *
+ * There used to be no shared resolver. Three ad-hoc implementations had grown
+ * up independently — one in `ObjectView` for list views, one in
+ * `ObjectDataPage` for URL filter triples, one in `NavigationRenderer` for
+ * hrefs — and each handled only the shape its own surface happened to use.
+ * Dashboard widgets never got one at all, so `{current_user_id}` in a widget
+ * filter reached SQL as a literal, matched no row, and the widget rendered
+ * `0` with no error in the console or the server log.
+ *
+ * The failure mode is the point: a metric reading `0` is indistinguishable
+ * from a metric that is legitimately zero, so the bug survived review and
+ * shipped. Any *new* surface that resolves placeholders itself will
+ * eventually reproduce it, which is why resolution lives here, once, and
+ * every surface calls {@link resolveFilterPlaceholders}.
+ *
+ * ## Presentation scope, NOT a security boundary
+ *
+ * These tokens scope what a surface *shows*. They do not decide what a caller
+ * is *allowed* to read — that is RLS, enforced server-side against a
+ * different vocabulary rooted at `current_user` (`owner_id = current_user.id`).
+ * Dropping a `{current_user_id}` filter widens a view; it must never widen
+ * access. Never use a context token as an access control.
+ *
+ * ## Contract source
+ *
+ * The canonical vocabulary is published as part of the platform contract at
+ * `@objectstack/spec` → `CONTEXT_TOKENS` / `classifyFilterToken`. It is
+ * mirrored here — exactly as `date-macros.ts` mirrors `DATE_MACRO_TOKENS` —
+ * because the installed `@objectstack/spec` predates that export. Keep the two
+ * in sync; the duplication is temporary until the next coordinated release.
+ */
+/** The complete set of session-scoped filter tokens. */
+export const CONTEXT_TOKENS = ['current_user_id', 'current_org_id'];
+/**
+ * Near-miss spellings → the token the author meant.
+ *
+ * Every entry is a real authoring mistake, and each is a correct spelling
+ * *somewhere else* in the platform, which is exactly why authors reach for it:
+ * `current_user` is the RLS expression root, `{user_id}` is valid
+ * `titleFormat` field interpolation, `organization_id` is a real column name.
+ *
+ * Mirrors `CONTEXT_TOKEN_SUGGESTIONS` in `@objectstack/spec`. Used only to
+ * make the runtime warning actionable; the authoring-time gate
+ * (`validateFilterTokens` in `@objectstack/lint`) is what actually prevents
+ * these from shipping.
+ */
+const CONTEXT_TOKEN_SUGGESTIONS = {
+    current_user: 'current_user_id',
+    current_user_email: 'current_user_id',
+    user_id: 'current_user_id',
+    userid: 'current_user_id',
+    me: 'current_user_id',
+    current_organization_id: 'current_org_id',
+    org_id: 'current_org_id',
+    organization_id: 'current_org_id',
+    current_tenant_id: 'current_org_id',
+};
+/** Whole-string placeholder: `{token}` or `${token}`, anchored. */
+const WHOLE_TOKEN_RE = /^\$?\{([a-zA-Z0-9_]+)\}$/;
+function isContextToken(token) {
+    return CONTEXT_TOKENS.includes(token);
+}
+/**
+ * Expand `{current_user_id}` / `{current_org_id}` inside a filter.
+ *
+ * Walks arrays and plain objects recursively, which is what makes one
+ * resolver cover both platform filter shapes: the MongoDB-style object a
+ * dashboard widget carries (`{ owner_id: '{current_user_id}' }`) and the
+ * condition/triple arrays a list view carries (`[{ field, operator, value }]`
+ * / `[['owner','=','…']]`). The predecessor helper in `ObjectView` bailed on
+ * non-arrays (`if (!Array.isArray(filter)) return filter`), which is why
+ * lifting it into the dashboard would have been a silent no-op.
+ *
+ * Only whole-string placeholders are substituted — an id is an opaque value,
+ * so embedding it in a larger string (`'user-{current_user_id}'`) is never
+ * what an author means, and substituting there would silently produce a value
+ * that matches nothing. Unknown tokens are passed through untouched so that
+ * date macros and nav-only `AppContextSelector` ids survive this pass.
+ *
+ * An unresolvable *known* token is deliberately left as-is rather than
+ * dropped: leaving it yields an empty result, whereas dropping the clause
+ * would widen the result set — and a filter that silently widens is far worse
+ * than one that silently narrows.
+ */
+export function resolveContextTokens(filter, scope = {}) {
+    if (filter == null)
+        return filter;
+    const { currentUserId, currentOrgId } = scope;
+    const warn = scope.onUnresolved === null
+        ? () => { }
+        : scope.onUnresolved ??
+            ((message) => {
+                // eslint-disable-next-line no-console
+                console.warn(`[object-ui] ${message}`);
+            });
+    const values = {
+        current_user_id: currentUserId,
+        current_org_id: currentOrgId,
+    };
+    const walk = (value) => {
+        if (value == null)
+            return value;
+        if (typeof value === 'string') {
+            const m = value.match(WHOLE_TOKEN_RE);
+            if (!m)
+                return value;
+            const token = m[1];
+            if (isContextToken(token)) {
+                const resolved = values[token];
+                if (resolved != null && resolved !== '')
+                    return resolved;
+                warn(`Filter placeholder "{${token}}" could not be resolved — no ${token === 'current_user_id' ? 'signed-in user' : 'active organization'} in scope. The filter will match no records.`);
+                return value;
+            }
+            // Not ours. Warn only for near-misses, which resolve in no vocabulary
+            // at all and would otherwise fail silently; genuine date macros and
+            // nav context-selector ids must pass through quietly.
+            const suggestion = CONTEXT_TOKEN_SUGGESTIONS[token.toLowerCase()];
+            if (suggestion) {
+                warn(`Filter placeholder "{${token}}" is not a recognised token — did you mean ` +
+                    `"{${suggestion}}"? It is sent to the server as a literal string and will ` +
+                    `match no records.`);
+            }
+            return value;
+        }
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (typeof value === 'object') {
+            const out = {};
+            for (const k of Object.keys(value))
+                out[k] = walk(value[k]);
+            return out;
+        }
+        return value;
+    };
+    return walk(filter);
+}
+/**
+ * Resolve **every** placeholder vocabulary a filter value understands — date
+ * macros and context tokens — in one call.
+ *
+ * This is the function surfaces should call. Calling only one of the two
+ * resolvers is the defect behind framework #3574: dashboard widgets called
+ * `resolveDateMacros` alone, so `{today}` worked and `{current_user_id}`
+ * silently did not.
+ *
+ * Order is irrelevant (the vocabularies are disjoint) but fixed here so
+ * behaviour is identical everywhere.
+ */
+export function resolveFilterPlaceholders(filter, scope = {}, now = new Date()) {
+    if (filter == null)
+        return filter;
+    return resolveContextTokens(resolveDateMacros(filter, now), scope);
+}

package/dist/utils/managedBy.d.ts

@@ -81,8 +81,19 @@ export declare function normalizeUserAction(v: UserActionOverride | undefined |
  * {@link normalizeUserAction} so the parse lives in exactly one place.
  */
 export declare function userActionPredicates(v: UserActionOverride | undefined | null): RowCrudPredicates | undefined;
-/** Resolve the effective CRUD affordances for an object schema. */
-export declare function resolveCrudAffordances(obj: SchemaLike | null | undefined): CrudAffordances;
+/**
+ * Resolve the effective CRUD affordances for an object schema.
+ *
+ * @param obj The object schema (managedBy bucket + userActions overrides).
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (from `/me/permissions` `apiOperations`, #3391). When
+ *   provided, each affordance bit is ANDed with the corresponding API operation
+ *   (create/import→create/import, edit→update, delete→delete, exportCsv→export),
+ *   so the UI never shows a button the server would 405. Passing `undefined`
+ *   (old backend / no effective set) leaves the affordances untouched —
+ *   backward-compatible. An empty array means "expose nothing" → all bits off.
+ */
+export declare function resolveCrudAffordances(obj: SchemaLike | null | undefined, effectiveApiOperations?: readonly string[] | null): CrudAffordances;
 /** True only when a `userActions` flag (bare boolean or #2614 object form) opts the write in. */
 export declare function isWriteOptedIn(v: UserActionOverride | undefined | null): boolean;
 /**
@@ -97,5 +108,12 @@ export declare function isSystemWritable(obj: SchemaLike | null | undefined): bo
  * `append-only` / `better-auth` objects resolve to `false` unless they opened
  * `userActions.edit`. (Per-record predicates gate row action buttons, not
  * object-level editability, so only the resolved boolean matters here.)
+ *
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (`/me/permissions` `apiOperations`, #3391/#3546). When
+ *   provided, inline-edit is additionally ANDed with the server allowing
+ *   `update`, so a record page never offers double-click/pencil editing the
+ *   server would 405. `undefined` (old backend / unrestricted) leaves the
+ *   bucket affordance untouched.
  */
-export declare function isObjectInlineEditable(obj: SchemaLike | null | undefined): boolean;
+export declare function isObjectInlineEditable(obj: SchemaLike | null | undefined, effectiveApiOperations?: readonly string[] | null): boolean;

package/dist/utils/managedBy.js

@@ -59,8 +59,32 @@ export function normalizeUserAction(v, base) {
 export function userActionPredicates(v) {
     return normalizeUserAction(v, false).predicates;
 }
-/** Resolve the effective CRUD affordances for an object schema. */
-export function resolveCrudAffordances(obj) {
+/**
+ * The affordance-bit → server API-operation mapping used to intersect the
+ * UI-intent affordances with the server's effective API operation set (#3391).
+ * This is the objectui end of the framework's `API_METHOD_DERIVATION` contract:
+ * the button predicate is `affordance(op) ∧ effective.api(op)`.
+ */
+const AFFORDANCE_TO_API_OPERATION = {
+    create: 'create',
+    import: 'import',
+    edit: 'update',
+    delete: 'delete',
+    exportCsv: 'export',
+};
+/**
+ * Resolve the effective CRUD affordances for an object schema.
+ *
+ * @param obj The object schema (managedBy bucket + userActions overrides).
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (from `/me/permissions` `apiOperations`, #3391). When
+ *   provided, each affordance bit is ANDed with the corresponding API operation
+ *   (create/import→create/import, edit→update, delete→delete, exportCsv→export),
+ *   so the UI never shows a button the server would 405. Passing `undefined`
+ *   (old backend / no effective set) leaves the affordances untouched —
+ *   backward-compatible. An empty array means "expose nothing" → all bits off.
+ */
+export function resolveCrudAffordances(obj, effectiveApiOperations) {
     const bucket = obj?.managedBy ?? 'platform';
     const base = DEFAULTS[bucket] ?? DEFAULTS.platform;
     const o = obj?.userActions ?? {};
@@ -77,6 +101,16 @@ export function resolveCrudAffordances(obj) {
         out.editPredicates = edit.predicates;
     if (del.predicates)
         out.deletePredicates = del.predicates;
+    // [#3391] Intersect with the server's effective API operations when present.
+    // The frontend consumes the effective set the server hands down; it never
+    // reads the raw `apiMethods` nor re-derives.
+    if (Array.isArray(effectiveApiOperations)) {
+        const eff = new Set(effectiveApiOperations);
+        for (const [bit, op] of Object.entries(AFFORDANCE_TO_API_OPERATION)) {
+            if (out[bit] && !eff.has(op))
+                out[bit] = false;
+        }
+    }
     return out;
 }
 /** True only when a `userActions` flag (bare boolean or #2614 object form) opts the write in. */
@@ -100,7 +134,14 @@ export function isSystemWritable(obj) {
  * `append-only` / `better-auth` objects resolve to `false` unless they opened
  * `userActions.edit`. (Per-record predicates gate row action buttons, not
  * object-level editability, so only the resolved boolean matters here.)
+ *
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (`/me/permissions` `apiOperations`, #3391/#3546). When
+ *   provided, inline-edit is additionally ANDed with the server allowing
+ *   `update`, so a record page never offers double-click/pencil editing the
+ *   server would 405. `undefined` (old backend / unrestricted) leaves the
+ *   bucket affordance untouched.
  */
-export function isObjectInlineEditable(obj) {
-    return resolveCrudAffordances(obj).edit;
+export function isObjectInlineEditable(obj, effectiveApiOperations) {
+    return resolveCrudAffordances(obj, effectiveApiOperations).edit;
 }

package/dist/utils/normalize-list-view.d.ts

@@ -0,0 +1,99 @@
+/**
+ * ObjectUI — list-view vocabulary canonicalization
+ * 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.
+ */
+/** ListView's toolbar density vocabulary — three steps, not the spec's five. */
+export type DensityMode = 'compact' | 'comfortable' | 'spacious';
+/** The spec's `RowHeightSchema` vocabulary. */
+export type RowHeight = 'compact' | 'short' | 'medium' | 'tall' | 'extra_tall';
+/**
+ * `densityMode` → `rowHeight`. The two vocabularies are not the same size: the
+ * spec has five row heights, ListView's toolbar offers three. Widening maps
+ * each density onto the spec value the renderer already resolves it back to
+ * (see {@link ROW_HEIGHT_TO_DENSITY_MODE}), so a fold followed by a read is a
+ * round trip — `spacious` → `tall` → `spacious`.
+ */
+export declare const DENSITY_MODE_TO_ROW_HEIGHT: Record<DensityMode, RowHeight>;
+/**
+ * `rowHeight` → `densityMode`, the read direction. Narrowing five values onto
+ * three is lossy by construction: `short` collapses into `compact` and
+ * `extra_tall` into `spacious`. Exported so the renderer and the persistence
+ * layer agree on the collapse instead of each hard-coding its own table.
+ */
+export declare const ROW_HEIGHT_TO_DENSITY_MODE: Record<RowHeight, DensityMode>;
+/**
+ * Tolerant reader for {@link ROW_HEIGHT_TO_DENSITY_MODE}. View metadata is
+ * user-authored, so `rowHeight` is not guaranteed to be one of the five spec
+ * values — an unknown one lands on `comfortable` rather than rendering an
+ * undefined density. Keeping the fallback here means every surface collapses
+ * the same way.
+ */
+export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode;
+/**
+ * ObjectUI's `list-view` node historically used a different vocabulary from
+ * `@objectstack/spec` for the same concepts (`fields` where the spec says
+ * `columns`, `viewType` where it says `type`, …). Issue #2231 closed the
+ * type-level fork; #2890 closes the vocabulary fork.
+ *
+ * Stored view metadata in user databases still carries the legacy keys, so the
+ * renderer cannot simply stop accepting them. Per AGENTS.md Commandment #0.1 the
+ * answer is NOT a per-read-site `??` fallback — those fossilize a second de-facto
+ * contract and drift apart (they already had: `ObjectGrid` preferred `columns`
+ * in one branch and `fields` in another). Instead legacy acceptance lives HERE,
+ * in one documented normalizer at the component boundary, mirroring
+ * `normalizeSchemaReferenceKeys` (object schemas) and the spec's own
+ * `normalizeVisibleWhen` / `normalizeFilterOperator` migration bridges.
+ *
+ * Note this cannot be a `z.preprocess` on `ListViewSchema`: nothing on the
+ * render path parses view metadata through zod (the zod schemas are used by the
+ * CLI validator, the VS Code extension and tests only), so a schema-level fold
+ * would never run. The guarantee comes from the call site instead — `ListView`
+ * normalizes before it reads anything.
+ *
+ * The fold is deliberately one-directional: the canonical key wins when both are
+ * present, and the legacy key is REMOVED from the result so a read-site that was
+ * missed fails loudly instead of quietly taking the legacy path. Like a spec
+ * migration bridge, this is expected to be dropped in a future major once stored
+ * metadata has been migrated.
+ *
+ * Non-mutating and allocation-frugal: returns the input by reference when there
+ * is nothing to fold, so `ListView`'s downstream `useMemo`s keep a stable
+ * dependency identity on the common (already-canonical) path.
+ *
+ * Currently folded:
+ *  - `fields` → `columns` (#2890 scope A step 1)
+ *  - `densityMode` → `rowHeight` (#2890 scope A step 2)
+ *  - the `show*` toolbar flags → `userActions` (#2890 scope A step 3), and
+ *    `showDescription` → `appearance.showDescription`. The canonical key wins
+ *    per-flag, so a view may carry `userActions` for some toggles and a legacy
+ *    flag for others. NOTE the fold does not apply any default: an absent flag
+ *    stays absent, because the defaults are per-toggle (search/sort/filter/
+ *    rowHeight/group default ON, hideFields/rowColor default OFF) and belong to
+ *    the renderer, not to the vocabulary bridge.
+ *  - `aria: { label, describedBy }` → the spec's `AriaProps`
+ *    (`{ ariaLabel, ariaDescribedBy }`), and `sharing: { visibility, enabled }`
+ *    → the spec's `ViewSharing` (`{ type }`) — #2890 scope A step 5. `aria.live`
+ *    survives untouched: it has no spec counterpart.
+ *  - `filters` → `filter` (#2890 scope A step 4). A key rename only: BOTH keys
+ *    carry an ObjectQL FilterNode array (`[['stage','=','won']]`) everywhere in
+ *    objectui — every consumer passes the value straight to `$filter`. The spec
+ *    types `filter` as `ViewFilterRule[]` (`{field, operator, value}` objects),
+ *    so objectui's field is typed from the spec but used as something else.
+ *    That mismatch is real and out of scope here; converting formats inside a
+ *    vocabulary fold would change what reaches the data source.
+ *  - `viewType`: a missing kind, or the view CATEGORY `'list'` that AI-authored
+ *    metadata stores and hosts forward verbatim, becomes the renderable `'grid'`
+ *    — otherwise it reaches the renderer's typeless default branch and shows as
+ *    a red "Unknown component type" box.
+ *  - each `columns` entry's IDENTITY — `name` / `fieldName` → the spec's `field`
+ *    (#3104). This one MIRRORS instead of deleting, for the reason given on
+ *    {@link normalizeColumnIdentities}: `columns` entries cross the package
+ *    boundary into host renderers, so dropping `name` from under them is a
+ *    breaking change with no inventory. Runs AFTER the `fields` → `columns` fold
+ *    above, so a view that spells its column list the legacy way still gets its
+ *    entries canonicalized.
+ */
+export declare function normalizeListViewSchema<T>(schema: T): T;

package/dist/utils/normalize-list-view.js

@@ -0,0 +1,255 @@
+/**
+ * ObjectUI — list-view vocabulary canonicalization
+ * 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.
+ */
+import { normalizeColumnIdentities } from './column-identity.js';
+/**
+ * `densityMode` → `rowHeight`. The two vocabularies are not the same size: the
+ * spec has five row heights, ListView's toolbar offers three. Widening maps
+ * each density onto the spec value the renderer already resolves it back to
+ * (see {@link ROW_HEIGHT_TO_DENSITY_MODE}), so a fold followed by a read is a
+ * round trip — `spacious` → `tall` → `spacious`.
+ */
+export const DENSITY_MODE_TO_ROW_HEIGHT = {
+    compact: 'compact',
+    comfortable: 'medium',
+    spacious: 'tall',
+};
+/**
+ * `rowHeight` → `densityMode`, the read direction. Narrowing five values onto
+ * three is lossy by construction: `short` collapses into `compact` and
+ * `extra_tall` into `spacious`. Exported so the renderer and the persistence
+ * layer agree on the collapse instead of each hard-coding its own table.
+ */
+export const ROW_HEIGHT_TO_DENSITY_MODE = {
+    compact: 'compact',
+    short: 'compact',
+    medium: 'comfortable',
+    tall: 'spacious',
+    extra_tall: 'spacious',
+};
+/**
+ * Tolerant reader for {@link ROW_HEIGHT_TO_DENSITY_MODE}. View metadata is
+ * user-authored, so `rowHeight` is not guaranteed to be one of the five spec
+ * values — an unknown one lands on `comfortable` rather than rendering an
+ * undefined density. Keeping the fallback here means every surface collapses
+ * the same way.
+ */
+export function rowHeightToDensityMode(rowHeight) {
+    if (typeof rowHeight === 'string' && rowHeight in ROW_HEIGHT_TO_DENSITY_MODE) {
+        return ROW_HEIGHT_TO_DENSITY_MODE[rowHeight];
+    }
+    return 'comfortable';
+}
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/**
+ * Legacy toolbar-visibility flags → their `userActions` key (#2890 scope A
+ * step 3). The spec documents `userActions` as "which interactive actions are
+ * available to users in the view toolbar", and already carries `rowHeight` —
+ * objectui's `showDensity` under its spec name. `group` / `hideFields` /
+ * `rowColor` are the same kind of toggle and are named after the config key
+ * they gate (`grouping`, `hiddenFields`, `rowColor`), pending promotion into
+ * `UserActionsConfigSchema` upstream.
+ */
+const SHOW_FLAG_TO_USER_ACTION = {
+    showSearch: 'search',
+    showSort: 'sort',
+    showFilters: 'filter',
+    showDensity: 'rowHeight',
+    showGroup: 'group',
+    showHideFields: 'hideFields',
+    showColor: 'rowColor',
+};
+/**
+ * Legacy `sharing.visibility` → the spec's `ViewSharing.type`. The spec models
+ * two ownership kinds; objectui's four-value audience enum collapses onto them:
+ * only `private` is personal, everything wider is collaborative.
+ */
+const VISIBILITY_TO_SHARING_TYPE = {
+    private: 'personal',
+    team: 'collaborative',
+    organization: 'collaborative',
+    public: 'collaborative',
+};
+/** Legacy ARIA spellings → the spec's `AriaProps` keys. */
+const ARIA_KEY_ALIASES = {
+    label: 'ariaLabel',
+    describedBy: 'ariaDescribedBy',
+};
+/**
+ * ObjectUI's `list-view` node historically used a different vocabulary from
+ * `@objectstack/spec` for the same concepts (`fields` where the spec says
+ * `columns`, `viewType` where it says `type`, …). Issue #2231 closed the
+ * type-level fork; #2890 closes the vocabulary fork.
+ *
+ * Stored view metadata in user databases still carries the legacy keys, so the
+ * renderer cannot simply stop accepting them. Per AGENTS.md Commandment #0.1 the
+ * answer is NOT a per-read-site `??` fallback — those fossilize a second de-facto
+ * contract and drift apart (they already had: `ObjectGrid` preferred `columns`
+ * in one branch and `fields` in another). Instead legacy acceptance lives HERE,
+ * in one documented normalizer at the component boundary, mirroring
+ * `normalizeSchemaReferenceKeys` (object schemas) and the spec's own
+ * `normalizeVisibleWhen` / `normalizeFilterOperator` migration bridges.
+ *
+ * Note this cannot be a `z.preprocess` on `ListViewSchema`: nothing on the
+ * render path parses view metadata through zod (the zod schemas are used by the
+ * CLI validator, the VS Code extension and tests only), so a schema-level fold
+ * would never run. The guarantee comes from the call site instead — `ListView`
+ * normalizes before it reads anything.
+ *
+ * The fold is deliberately one-directional: the canonical key wins when both are
+ * present, and the legacy key is REMOVED from the result so a read-site that was
+ * missed fails loudly instead of quietly taking the legacy path. Like a spec
+ * migration bridge, this is expected to be dropped in a future major once stored
+ * metadata has been migrated.
+ *
+ * Non-mutating and allocation-frugal: returns the input by reference when there
+ * is nothing to fold, so `ListView`'s downstream `useMemo`s keep a stable
+ * dependency identity on the common (already-canonical) path.
+ *
+ * Currently folded:
+ *  - `fields` → `columns` (#2890 scope A step 1)
+ *  - `densityMode` → `rowHeight` (#2890 scope A step 2)
+ *  - the `show*` toolbar flags → `userActions` (#2890 scope A step 3), and
+ *    `showDescription` → `appearance.showDescription`. The canonical key wins
+ *    per-flag, so a view may carry `userActions` for some toggles and a legacy
+ *    flag for others. NOTE the fold does not apply any default: an absent flag
+ *    stays absent, because the defaults are per-toggle (search/sort/filter/
+ *    rowHeight/group default ON, hideFields/rowColor default OFF) and belong to
+ *    the renderer, not to the vocabulary bridge.
+ *  - `aria: { label, describedBy }` → the spec's `AriaProps`
+ *    (`{ ariaLabel, ariaDescribedBy }`), and `sharing: { visibility, enabled }`
+ *    → the spec's `ViewSharing` (`{ type }`) — #2890 scope A step 5. `aria.live`
+ *    survives untouched: it has no spec counterpart.
+ *  - `filters` → `filter` (#2890 scope A step 4). A key rename only: BOTH keys
+ *    carry an ObjectQL FilterNode array (`[['stage','=','won']]`) everywhere in
+ *    objectui — every consumer passes the value straight to `$filter`. The spec
+ *    types `filter` as `ViewFilterRule[]` (`{field, operator, value}` objects),
+ *    so objectui's field is typed from the spec but used as something else.
+ *    That mismatch is real and out of scope here; converting formats inside a
+ *    vocabulary fold would change what reaches the data source.
+ *  - `viewType`: a missing kind, or the view CATEGORY `'list'` that AI-authored
+ *    metadata stores and hosts forward verbatim, becomes the renderable `'grid'`
+ *    — otherwise it reaches the renderer's typeless default branch and shows as
+ *    a red "Unknown component type" box.
+ *  - each `columns` entry's IDENTITY — `name` / `fieldName` → the spec's `field`
+ *    (#3104). This one MIRRORS instead of deleting, for the reason given on
+ *    {@link normalizeColumnIdentities}: `columns` entries cross the package
+ *    boundary into host renderers, so dropping `name` from under them is a
+ *    breaking change with no inventory. Runs AFTER the `fields` → `columns` fold
+ *    above, so a view that spells its column list the legacy way still gets its
+ *    entries canonicalized.
+ */
+export function normalizeListViewSchema(schema) {
+    if (!schema || typeof schema !== 'object')
+        return schema;
+    const s = schema;
+    const legacyFields = s.fields;
+    const foldColumns = Array.isArray(legacyFields);
+    const legacyDensity = s.densityMode;
+    const foldRowHeight = typeof legacyDensity === 'string' && legacyDensity in DENSITY_MODE_TO_ROW_HEIGHT;
+    const legacyFilters = s.filters;
+    const foldFilter = Array.isArray(legacyFilters);
+    const legacyFlags = Object.keys(SHOW_FLAG_TO_USER_ACTION).filter((k) => typeof s[k] === 'boolean');
+    const foldDescription = typeof s.showDescription === 'boolean';
+    const aria = isRecord(s.aria) ? s.aria : undefined;
+    const foldAria = !!aria && Object.keys(ARIA_KEY_ALIASES).some((k) => aria[k] !== undefined);
+    const sharing = isRecord(s.sharing) ? s.sharing : undefined;
+    const foldSharing = !!sharing && (sharing.visibility !== undefined || sharing.enabled !== undefined);
+    const viewType = s.viewType;
+    const defaultViewKind = !viewType || viewType === 'list';
+    // The columns array the identity fold will see — mirroring the `foldColumns`
+    // precedence below (canonical `columns` wins; otherwise the legacy `fields`
+    // that is about to become it). `normalizeColumnIdentities` returns its input
+    // by reference when every entry is already canonical, so this comparison is
+    // also the "is there anything to do" test.
+    const columnsSource = Array.isArray(s.columns)
+        ? s.columns
+        : foldColumns
+            ? legacyFields
+            : undefined;
+    const foldedColumns = normalizeColumnIdentities(columnsSource);
+    const foldColumnIdentity = foldedColumns !== columnsSource;
+    if (!foldColumns && !foldRowHeight && !foldFilter && !legacyFlags.length &&
+        !foldDescription && !foldAria && !foldSharing && !defaultViewKind &&
+        !foldColumnIdentity) {
+        return schema;
+    }
+    const next = { ...s };
+    if (foldColumns) {
+        if (!Array.isArray(next.columns))
+            next.columns = legacyFields;
+        delete next.fields;
+    }
+    // After the `fields` → `columns` rename, so a legacy-spelled column LIST gets
+    // its per-entry identities canonicalized in the same pass.
+    if (foldColumnIdentity)
+        next.columns = foldedColumns;
+    if (foldRowHeight) {
+        if (typeof next.rowHeight !== 'string') {
+            next.rowHeight = DENSITY_MODE_TO_ROW_HEIGHT[legacyDensity];
+        }
+        delete next.densityMode;
+    }
+    if (foldFilter) {
+        if (!Array.isArray(next.filter))
+            next.filter = legacyFilters;
+        delete next.filters;
+    }
+    if (legacyFlags.length) {
+        const ua = { ...(isRecord(next.userActions) ? next.userActions : {}) };
+        for (const flag of legacyFlags) {
+            const key = SHOW_FLAG_TO_USER_ACTION[flag];
+            if (typeof ua[key] !== 'boolean')
+                ua[key] = s[flag];
+            delete next[flag];
+        }
+        next.userActions = ua;
+    }
+    if (foldDescription) {
+        const appearance = {
+            ...(isRecord(next.appearance) ? next.appearance : {}),
+        };
+        if (typeof appearance.showDescription !== 'boolean') {
+            appearance.showDescription = s.showDescription;
+        }
+        delete next.showDescription;
+        next.appearance = appearance;
+    }
+    if (foldAria && aria) {
+        const nextAria = { ...aria };
+        for (const [legacy, canonical] of Object.entries(ARIA_KEY_ALIASES)) {
+            if (nextAria[canonical] === undefined && aria[legacy] !== undefined) {
+                nextAria[canonical] = aria[legacy];
+            }
+            delete nextAria[legacy];
+        }
+        next.aria = nextAria;
+    }
+    if (foldSharing && sharing) {
+        const nextSharing = { ...sharing };
+        if (nextSharing.type === undefined) {
+            const visibility = typeof sharing.visibility === 'string' ? sharing.visibility : undefined;
+            // `enabled: true` with no audience is under-specified legacy input. It
+            // used to render the share badge titled "private", so it maps to
+            // `personal` — preserving what the user saw rather than adopting the
+            // spec's `collaborative` default and silently relabeling the badge.
+            const resolved = visibility
+                ? VISIBILITY_TO_SHARING_TYPE[visibility]
+                : sharing.enabled === true
+                    ? 'personal'
+                    : undefined;
+            if (resolved)
+                nextSharing.type = resolved;
+        }
+        delete nextSharing.visibility;
+        delete nextSharing.enabled;
+        next.sharing = nextSharing;
+    }
+    if (defaultViewKind)
+        next.viewType = 'grid';
+    return next;
+}