@object-ui/core 17.5.0 → 17.7.0

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

@@ -5,6 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import type { ViewType } from '@object-ui/types';
 import type { RowHeight } from '@objectstack/spec/ui';
 /** ListView's toolbar density vocabulary — three steps, not the spec's five. */
 export type DensityMode = 'compact' | 'comfortable' | 'spacious';
@@ -62,6 +63,101 @@ export declare const ROW_HEIGHT_TO_DENSITY_MODE: Record<RowHeight, DensityMode>;
  * something typed `DensityMode`.
  */
 export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode | undefined;
+/**
+ * A visualization `ListView` actually draws — one member per `case` in its
+ * `viewComponentSchema` switch (`packages/plugin-list/src/ListView.tsx`).
+ *
+ * DERIVED from {@link ViewType} (`ca3942729`), which is itself derived from
+ * `@objectstack/spec/ui` `ListView['type']`. Spelled as an `Exclude` of the
+ * members this renderer does not draw rather than as the spec's own
+ * `VisualizationType`, deliberately: `Exclude` leaves the SPEC's list as the
+ * thing being subtracted from, so ANY member the spec adds — visualization or
+ * not — lands here as a required key and fails the build, which is what the
+ * promise below actually says. Keying on `VisualizationType` instead would let
+ * a future non-visualization list type (another `page`) pass this site in
+ * silence, which is the exact failure being fixed.
+ *
+ * ⭐ What it subtracts is {@link UndrawableViewKind} — the keys of
+ * {@link UNDRAWABLE_VIEW_KINDS} the current `ViewType` still carries — and
+ * never a literal list of kinds (objectui#9880). A literal list is a second
+ * hand-written copy of the vocabulary, the failure class `ca3942729` removed
+ * from `ViewType` itself, and it rots in the direction the spec actually moved:
+ * `Exclude<ViewType, 'list' | 'detail' | 'page'>` kept subtracting `'page'`
+ * after objectstack RETIRED it, where `Exclude` of a non-member is a silent
+ * no-op no compiler reads. The sibling record's excess `page:` key is what went
+ * red; this line stayed green while saying something that had stopped being
+ * true.
+ *
+ * It happens to equal `@objectstack/spec/ui`'s `VisualizationType` today. That
+ * is a fact about the resolved spec, not the definition.
+ */
+export type ListViewVisualization = Exclude<ViewType, UndrawableViewKind>;
+/**
+ * Every member of {@link ViewType} that {@link LIST_VIEW_KINDS} does NOT carry,
+ * with the reason — and, where the answer is "the author authored something
+ * valid and will get a grid", the sentence to say out loud.
+ *
+ * The two tables together still partition the derived union — a member the spec
+ * ADDS must be classed as drawable or explained HERE, and until it is the build
+ * is red — but the red lands on {@link LIST_VIEW_KINDS} alone, because a kind
+ * neither table classes is not extracted into {@link UndrawableViewKind} and so
+ * stays inside {@link ListViewVisualization}, whose record is total. A key
+ * MISSPELLED here fails the same way, for the same reason: the kind it was
+ * meant to class is not extracted either. Both directions are pinned in
+ * `__tests__/normalize-list-view.undrawableBothLegs-9880.test.ts` rather than
+ * asserted in this sentence.
+ *
+ * ⛔ NOT annotated `Record<Exclude<ViewType, ListViewVisualization>, …>`, and
+ * the `satisfies` is not a style choice (objectui#9880). An annotation makes
+ * the literal EXACT in BOTH directions: a kind the spec adds is a missing key
+ * (wanted) and a kind the spec RETIRES is an EXCESS PROPERTY — a TS2353 that
+ * demands a deletion this repository cannot make while it resolves a published
+ * spec which still carries the kind (as it did with `page` through 17.4.0).
+ * `satisfies` keeps the value constraint
+ * (every reason is a `string` or `null`) and drops the exactness, which is what
+ * lets one spelling compile against both the pinned published spec and one
+ * built from objectstack `main`.
+ *
+ * `null` means silence is correct — these are objectui view CATEGORIES, never
+ * authored as a list-view kind:
+ *  - `list` is the view CATEGORY, not a kind — it already folds to `grid`.
+ *  - `detail` is a different renderer (`plugin-detail`), never a ListView case.
+ *
+ * `page` had a row here until objectui#11073. objectstack#17063 removed
+ * `type: 'page'` from the list-view enum, and the row answered for it while this
+ * repository still resolved a spec that published the kind. `@objectstack/spec`
+ * 17.5.0 carries the removal: both published `@object-ui/types` faces refuse
+ * `page`, `Extract` no longer extracted the row, and the residual pins that held
+ * it (`normalize-list-view.pageResidual-8429.test.ts`) were converted, so it was
+ * deleted as it said it would be. A stored `page` view now degrades like any
+ * kind outside the vocabulary.
+ */
+declare const UNDRAWABLE_VIEW_KINDS: {
+    list: null;
+    detail: null;
+};
+/**
+ * The members of the current {@link ViewType} that {@link UNDRAWABLE_VIEW_KINDS}
+ * classes — the other half of the partition, derived rather than written out.
+ *
+ * `Extract` over the table's keys, not the table's raw `keyof`, is the load-
+ * bearing operator (objectui#9880): the table may carry a row for a kind the
+ * spec has since RETIRED, and `Extract` drops that row from the TYPE without
+ * the table having to lose it at runtime. That is what made one spelling
+ * correct against both the published spec (which published `page` through
+ * 17.4.0) and a spec built from objectstack `main` (which retired it), and what
+ * made the row's deletion at 17.5.0 a plain deletion (objectui#11073).
+ */
+type UndrawableViewKind = Extract<ViewType, keyof typeof UNDRAWABLE_VIEW_KINDS>;
+/**
+ * Whether `value` names a visualization `ListView` draws.
+ *
+ * Exported so a read site cannot restate the membership question as its own
+ * literal array: the gate and the seam must answer one question, which is the
+ * rule this file's own `availableViews` notes already argue for (objectui#5042,
+ * objectui#7544, and now `ca3942729`).
+ */
+export declare function isListViewVisualization(value: unknown): value is ListViewVisualization;
 /**
  * ObjectUI's `list-view` node historically used a different vocabulary from
  * `@objectstack/spec` for the same concepts (`fields` where the spec says
@@ -114,10 +210,34 @@ export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode
  *    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.
+ *  - `data: { provider: 'object', object }` → `objectName` (#7477, step 6 of
+ *    #2890). This is the spelling the published `react-blocks` contract
+ *    recommends and the one `@objectstack/spec`'s `ViewDataSchema` declares;
+ *    ListView read it at ZERO sites, so a page bound that way validated green
+ *    upstream and rendered an empty list here with no diagnostic. The `object`
+ *    provider is a `strictObject` carrying exactly `{ provider, object }`, so
+ *    `objectName` captures all of it. Two deliberate departures from the folds
+ *    above, both narrowing:
+ *      · an already-present `objectName` WINS — this fold only fills a gap, it
+ *        never re-points a binding that already resolves;
+ *      · `data` is NOT deleted. Every other fold deletes because the legacy key
+ *        has one meaning and one home; `data` has four providers, `api`/`value`
+ *        are read live in `ListView`, and the whole block is FORWARDED to child
+ *        views (the gantt branch), whose own `getDataConfig` reads `data` before
+ *        `objectName`. Deleting it for one provider would rewrite what a child
+ *        resolves. Nothing in `ListView` reads `data.provider === 'object'`, so
+ *        keeping it cannot create a second de-facto contract inside the renderer.
  *  - `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.
+ *    a red "Unknown component type" box. Before that default applies, the
+ *    AUTHOR's kind is read (#7477): `specType` — the slot
+ *    `components/renderers/layout/react-page.tsx` parks a react-tier `type` in
+ *    when the SDUI envelope claims the `type` key (ADR-0078) — and then a bare
+ *    `type` when it names a kind ListView draws, which the component
+ *    discriminator (`'list-view'`) never does. Same two legs, same order, as
+ *    `normalizeChartSchema`'s chart-family read. An explicit `viewType` still
+ *    wins: this leg only fills the gap that used to resolve to `'grid'`.
  *  - 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
@@ -125,5 +245,15 @@ export declare function rowHeightToDensityMode(rowHeight: unknown): DensityMode
  *    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.
+ *  - the four PER-VIEW-TYPE config aliases phase 3 carried over
+ *    ({@link PER_VIEW_CONFIG_ALIASES}): `kanban.groupField` → `groupByField`,
+ *    `kanban.cardFields` → `columns`, `gallery.imageField` → `coverField`,
+ *    `timeline.dateField` → `startDateField`. One read-site changes behaviour
+ *    as a result, and it is a CORRECTION of the same inverted precedence A2
+ *    fixed for `densityMode`: `ListView`'s kanban adapter resolves
+ *    `cardFields || columns`, i.e. legacy over canonical, so a config carrying
+ *    BOTH used to render the legacy value. After the fold the canonical
+ *    `columns` reaches it. Every other reader of these four was already
+ *    canonical-first and is unaffected.
  */
 export declare function normalizeListViewSchema<T>(schema: T): T;

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

@@ -73,8 +73,16 @@ const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
  * 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.
+ * they gate (`grouping`, `hiddenFields`, `rowColor`).
+ *
+ * That promotion has LANDED (objectui#5435, ruled Option A 2026-08-22):
+ * `UserActionsConfigSchema` declares all three from `@objectstack/spec@17.3.0`,
+ * and the spec's declaring docblock names this card. Every key this table emits
+ * is therefore authorable, which
+ * `__tests__/normalize-list-view.foldOutputAuthorable-5435.test.ts` pins with a
+ * firing control. ⛔ Do not read the three as legacy-only spellings awaiting
+ * retirement — the protocol declares them, so removing them here would leave
+ * objectui narrower than the protocol.
  */
 const SHOW_FLAG_TO_USER_ACTION = {
     showSearch: 'search',
@@ -101,6 +109,163 @@ const ARIA_KEY_ALIASES = {
     label: 'ariaLabel',
     describedBy: 'ariaDescribedBy',
 };
+/**
+ * The view kinds `ListView` actually draws.
+ *
+ * A total `Record<…, true>` over {@link ListViewVisualization}, for the same
+ * reason the density maps above are `Record<RowHeight, …>`: a kind added to the
+ * union fails the build HERE instead of silently staying unreadable authored
+ * input.
+ *
+ * ⚠️ That promise was FALSE between `@objectstack/spec@17.3.0` and `ca3942729`.
+ * `ViewType` was a hand-written copy of the spec's list, so this map was total
+ * over the copy and compiled green while the spec's `page` had nowhere to land.
+ * Both faces are derived now, and the two totality structures below close the
+ * other half of the union, so every member of the spec's list is accounted for
+ * by a structure that fails the build rather than by a reader's memory.
+ *
+ * `hasOwnProperty`, not `in` — same trap as {@link rowHeightToDensityMode}:
+ * `in` walks the prototype chain, so `'toString'` would read as a view kind.
+ */
+const LIST_VIEW_KINDS = {
+    grid: true,
+    kanban: true,
+    gallery: true,
+    calendar: true,
+    timeline: true,
+    gantt: true,
+    map: true,
+    chart: true,
+    tree: true,
+};
+/**
+ * Every member of {@link ViewType} that {@link LIST_VIEW_KINDS} does NOT carry,
+ * with the reason — and, where the answer is "the author authored something
+ * valid and will get a grid", the sentence to say out loud.
+ *
+ * The two tables together still partition the derived union — a member the spec
+ * ADDS must be classed as drawable or explained HERE, and until it is the build
+ * is red — but the red lands on {@link LIST_VIEW_KINDS} alone, because a kind
+ * neither table classes is not extracted into {@link UndrawableViewKind} and so
+ * stays inside {@link ListViewVisualization}, whose record is total. A key
+ * MISSPELLED here fails the same way, for the same reason: the kind it was
+ * meant to class is not extracted either. Both directions are pinned in
+ * `__tests__/normalize-list-view.undrawableBothLegs-9880.test.ts` rather than
+ * asserted in this sentence.
+ *
+ * ⛔ NOT annotated `Record<Exclude<ViewType, ListViewVisualization>, …>`, and
+ * the `satisfies` is not a style choice (objectui#9880). An annotation makes
+ * the literal EXACT in BOTH directions: a kind the spec adds is a missing key
+ * (wanted) and a kind the spec RETIRES is an EXCESS PROPERTY — a TS2353 that
+ * demands a deletion this repository cannot make while it resolves a published
+ * spec which still carries the kind (as it did with `page` through 17.4.0).
+ * `satisfies` keeps the value constraint
+ * (every reason is a `string` or `null`) and drops the exactness, which is what
+ * lets one spelling compile against both the pinned published spec and one
+ * built from objectstack `main`.
+ *
+ * `null` means silence is correct — these are objectui view CATEGORIES, never
+ * authored as a list-view kind:
+ *  - `list` is the view CATEGORY, not a kind — it already folds to `grid`.
+ *  - `detail` is a different renderer (`plugin-detail`), never a ListView case.
+ *
+ * `page` had a row here until objectui#11073. objectstack#17063 removed
+ * `type: 'page'` from the list-view enum, and the row answered for it while this
+ * repository still resolved a spec that published the kind. `@objectstack/spec`
+ * 17.5.0 carries the removal: both published `@object-ui/types` faces refuse
+ * `page`, `Extract` no longer extracted the row, and the residual pins that held
+ * it (`normalize-list-view.pageResidual-8429.test.ts`) were converted, so it was
+ * deleted as it said it would be. A stored `page` view now degrades like any
+ * kind outside the vocabulary.
+ */
+const UNDRAWABLE_VIEW_KINDS = {
+    list: null,
+    detail: null,
+};
+/** One warning per undrawable kind per process — see {@link warnUndrawableViewKind}. */
+const warnedUndrawableKinds = new Set();
+/**
+ * Fail-open is **loud**, not silent — the convention this repo already applies
+ * to unevaluable predicates (`../evaluator/fieldRules.ts`, objectstack#5149).
+ *
+ * The bug `ca3942729` records is not only that `type: 'page'` degrades to a
+ * grid; it is that it degrades IDENTICALLY to a typo. Measured on `5505aec`,
+ * `specType: 'page'` and `specType: 'nonsense'` both left `viewType: 'grid'`
+ * with no error, no warning and no console line — and `@object-ui/types`'
+ * published validator ACCEPTS `viewType: 'page'` while refusing the typo. An
+ * author who writes a spec-valid view and is silently handed a different one
+ * has no way to tell that from a working grid, so the degrade says so once.
+ *
+ * Once per kind per process, and never for the two objectui categories: this
+ * runs inside a normalizer that a render can call on every keystroke, and the
+ * point is one line, not a scrolling wall.
+ */
+function warnUndrawableViewKind(kind) {
+    const reason = Object.prototype.hasOwnProperty.call(UNDRAWABLE_VIEW_KINDS, kind)
+        ? UNDRAWABLE_VIEW_KINDS[kind]
+        : null;
+    if (reason === null || warnedUndrawableKinds.has(kind))
+        return;
+    warnedUndrawableKinds.add(kind);
+    console.warn(`[object-ui] This build accepts a ${JSON.stringify(kind)} list view but cannot draw one: ` +
+        `${reason}. The view falls back to a grid. ` +
+        'Author a visualization this renderer draws, or render the page through the surface that owns it.');
+}
+/**
+ * Whether `value` names a visualization `ListView` draws.
+ *
+ * Exported so a read site cannot restate the membership question as its own
+ * literal array: the gate and the seam must answer one question, which is the
+ * rule this file's own `availableViews` notes already argue for (objectui#5042,
+ * objectui#7544, and now `ca3942729`).
+ */
+export function isListViewVisualization(value) {
+    return typeof value === 'string' && Object.prototype.hasOwnProperty.call(LIST_VIEW_KINDS, value);
+}
+/**
+ * The author's view kind, or `undefined` when the value names no kind ListView
+ * draws. An unrecognized kind is deliberately left unresolved rather than
+ * written through to `viewType`: the caller's own `'grid'` default is a more
+ * honest answer than a `viewType` no branch matches (the same call
+ * `normalizeChartSchema` makes for a chart family it cannot draw).
+ *
+ * A kind the SPEC allows but this renderer cannot draw takes the same fallback
+ * and additionally warns — see {@link warnUndrawableViewKind}.
+ */
+function readListViewKind(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    if (isListViewVisualization(value))
+        return value;
+    warnUndrawableViewKind(value);
+    return undefined;
+}
+/**
+ * Per-view-type config aliases → the spec key each one aliases (#2890, the
+ * phase-3 carry-over).
+ *
+ * Phase 3 derived `kanban` / `gallery` / `timeline` from the spec configs but
+ * kept the pre-#2231 objectui spellings declared alongside the spec keys so
+ * stored view metadata would keep validating
+ * (`packages/types/src/zod/objectql.zod.ts`, each marked `@deprecated legacy
+ * alias for the spec's X`). Folding them here is what lets a read-site stop
+ * carrying its own `canonical || legacy` pair — the same move A1–A5 made for
+ * the top-level vocabulary.
+ *
+ * `calendar` is deliberately absent: its one local key, `defaultView`, is not
+ * an alias of anything. It has no spec counterpart at all, so it wants
+ * PROMOTION upstream, not a rename — folding it would delete an authored value
+ * with nowhere to put it.
+ *
+ * Note `kanban.columns` is the spec's "fields shown on each card", NOT the
+ * table columns that the same word names at the ListView top level. The fold
+ * is scoped to the nested config, so the two never meet.
+ */
+const PER_VIEW_CONFIG_ALIASES = {
+    kanban: { groupField: 'groupByField', cardFields: 'columns' },
+    gallery: { imageField: 'coverField' },
+    timeline: { dateField: 'startDateField' },
+};
 /**
  * ObjectUI's `list-view` node historically used a different vocabulary from
  * `@objectstack/spec` for the same concepts (`fields` where the spec says
@@ -153,10 +318,34 @@ const ARIA_KEY_ALIASES = {
  *    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.
+ *  - `data: { provider: 'object', object }` → `objectName` (#7477, step 6 of
+ *    #2890). This is the spelling the published `react-blocks` contract
+ *    recommends and the one `@objectstack/spec`'s `ViewDataSchema` declares;
+ *    ListView read it at ZERO sites, so a page bound that way validated green
+ *    upstream and rendered an empty list here with no diagnostic. The `object`
+ *    provider is a `strictObject` carrying exactly `{ provider, object }`, so
+ *    `objectName` captures all of it. Two deliberate departures from the folds
+ *    above, both narrowing:
+ *      · an already-present `objectName` WINS — this fold only fills a gap, it
+ *        never re-points a binding that already resolves;
+ *      · `data` is NOT deleted. Every other fold deletes because the legacy key
+ *        has one meaning and one home; `data` has four providers, `api`/`value`
+ *        are read live in `ListView`, and the whole block is FORWARDED to child
+ *        views (the gantt branch), whose own `getDataConfig` reads `data` before
+ *        `objectName`. Deleting it for one provider would rewrite what a child
+ *        resolves. Nothing in `ListView` reads `data.provider === 'object'`, so
+ *        keeping it cannot create a second de-facto contract inside the renderer.
  *  - `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.
+ *    a red "Unknown component type" box. Before that default applies, the
+ *    AUTHOR's kind is read (#7477): `specType` — the slot
+ *    `components/renderers/layout/react-page.tsx` parks a react-tier `type` in
+ *    when the SDUI envelope claims the `type` key (ADR-0078) — and then a bare
+ *    `type` when it names a kind ListView draws, which the component
+ *    discriminator (`'list-view'`) never does. Same two legs, same order, as
+ *    `normalizeChartSchema`'s chart-family read. An explicit `viewType` still
+ *    wins: this leg only fills the gap that used to resolve to `'grid'`.
  *  - 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
@@ -164,6 +353,16 @@ const ARIA_KEY_ALIASES = {
  *    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.
+ *  - the four PER-VIEW-TYPE config aliases phase 3 carried over
+ *    ({@link PER_VIEW_CONFIG_ALIASES}): `kanban.groupField` → `groupByField`,
+ *    `kanban.cardFields` → `columns`, `gallery.imageField` → `coverField`,
+ *    `timeline.dateField` → `startDateField`. One read-site changes behaviour
+ *    as a result, and it is a CORRECTION of the same inverted precedence A2
+ *    fixed for `densityMode`: `ListView`'s kanban adapter resolves
+ *    `cardFields || columns`, i.e. legacy over canonical, so a config carrying
+ *    BOTH used to render the legacy value. After the fold the canonical
+ *    `columns` reaches it. Every other reader of these four was already
+ *    canonical-first and is unaffected.
  */
 export function normalizeListViewSchema(schema) {
     if (!schema || typeof schema !== 'object')
@@ -172,7 +371,12 @@ export function normalizeListViewSchema(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;
+    // `hasOwnProperty`, not `in` — same trap as {@link rowHeightToDensityMode},
+    // in the fold direction: `in` walks the prototype chain, so `'toString'` used
+    // to fold into `rowHeight` as `Object.prototype.toString`, a FUNCTION, and
+    // drop the key (objectui#10868). An inherited key is an unrecognized density.
+    const foldRowHeight = typeof legacyDensity === 'string' &&
+        Object.prototype.hasOwnProperty.call(DENSITY_MODE_TO_ROW_HEIGHT, legacyDensity);
     const legacyFilters = s.filters;
     const foldFilter = Array.isArray(legacyFilters);
     const legacyFlags = Object.keys(SHOW_FLAG_TO_USER_ACTION).filter((k) => typeof s[k] === 'boolean');
@@ -181,7 +385,17 @@ export function normalizeListViewSchema(schema) {
     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);
+    // `data: { provider: 'object', object }` → `objectName` (#7477). Gap-fill
+    // only: a non-empty `objectName` already on the schema wins, so this can
+    // never re-point a binding that resolves today.
+    const dataConfig = isRecord(s.data) ? s.data : undefined;
+    const dataObjectName = dataConfig?.provider === 'object' && typeof dataConfig.object === 'string' && dataConfig.object
+        ? dataConfig.object
+        : undefined;
+    const foldObjectName = dataObjectName !== undefined && !(typeof s.objectName === 'string' && s.objectName);
     const viewType = s.viewType;
+    // The author's kind, read before the `'grid'` default applies (#7477).
+    const authoredViewKind = readListViewKind(s.specType) ?? readListViewKind(s.type);
     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`
@@ -195,9 +409,22 @@ export function normalizeListViewSchema(schema) {
             : undefined;
     const foldedColumns = normalizeColumnIdentities(columnsSource);
     const foldColumnIdentity = foldedColumns !== columnsSource;
+    // Per-view-type config aliases (#2890 phase-3 carry-over). Collected before
+    // the early return so an otherwise-canonical view carrying only a nested
+    // legacy key still folds — and so a view carrying none still returns by
+    // reference.
+    const perViewFolds = Object.entries(PER_VIEW_CONFIG_ALIASES)
+        .map(([viewKey, aliases]) => {
+        const cfg = isRecord(s[viewKey]) ? s[viewKey] : undefined;
+        if (!cfg)
+            return undefined;
+        const legacyKeys = Object.keys(aliases).filter((legacy) => cfg[legacy] !== undefined);
+        return legacyKeys.length ? { viewKey, aliases, cfg, legacyKeys } : undefined;
+    })
+        .filter((entry) => entry !== undefined);
     if (!foldColumns && !foldRowHeight && !foldFilter && !legacyFlags.length &&
         !foldDescription && !foldAria && !foldSharing && !defaultViewKind &&
-        !foldColumnIdentity) {
+        !foldColumnIdentity && !perViewFolds.length && !foldObjectName) {
         return schema;
     }
     const next = { ...s };
@@ -271,7 +498,22 @@ export function normalizeListViewSchema(schema) {
         delete nextSharing.enabled;
         next.sharing = nextSharing;
     }
+    for (const { viewKey, aliases, cfg, legacyKeys } of perViewFolds) {
+        const nextCfg = { ...cfg };
+        for (const legacy of legacyKeys) {
+            const canonical = aliases[legacy];
+            // Same one-directional shape as every fold above: the canonical key wins
+            // when both are present, and the legacy key is REMOVED so a missed
+            // read-site fails loudly instead of quietly taking the legacy path.
+            if (nextCfg[canonical] === undefined)
+                nextCfg[canonical] = cfg[legacy];
+            delete nextCfg[legacy];
+        }
+        next[viewKey] = nextCfg;
+    }
+    if (foldObjectName)
+        next.objectName = dataObjectName;
     if (defaultViewKind)
-        next.viewType = 'grid';
+        next.viewType = authoredViewKind ?? 'grid';
     return next;
 }

package/dist/utils/number-display.d.ts

@@ -20,11 +20,12 @@
  *     grouped and pointed decimals the US way; and
  *  2. `useGrouping` was never set, so a four-digit YEAR stored as
  *     `Field.number({ scale: 0 })` rendered as `2,026` — in every locale, with
- *     no field property able to turn it off.
+ *     no field property able to turn it off. (That property now exists: the
+ *     spec's `FieldSchema.useGrouping`, read here since objectui#11026.)
  *
- * Both policies now live here and nowhere else. Call sites bring the value and
- * the display width; they do not bring a locale default and they do not decide
- * grouping.
+ * Both policies now live here and nowhere else. Call sites bring the value, the
+ * display width and whatever the FIELD declared (`scale`, `useGrouping`); they
+ * do not bring a locale default and they do not decide grouping.
  *
  * ── Why this module lives in `@object-ui/core` (objectui#4576) ──
  * It used to live in `@object-ui/i18n`, and that home cost the repo a real
@@ -57,6 +58,22 @@ export interface DisplayNumberFormatOptions {
      * for a non-React caller that has no locale in hand. It never means `en-US`:
      * assuming US conventions for the whole world is the defect this module was
      * created to remove.
+     *
+     * ── The caller this rule governs (objectui#10098) ──
+     * The `undefined` rule above is written for a NON-REACT display caller with
+     * no tag in hand: a plain formatter, an exporter, engine code — anything that
+     * cannot call a hook. For that caller the runtime default is the viewer's
+     * own environment, and the viewer's own environment is the honest locale for
+     * a user-facing display. A malformed tag ends in the same place, whoever the
+     * caller: {@link formatDisplayNumber} retries without it rather than
+     * throwing, so the number renders in the runtime default instead of taking
+     * the cell down.
+     *
+     * A React renderer is governed by a different rule, and the two do not
+     * contradict each other. It passes what `useDisplayLocale` returns, and that
+     * hook — `@object-ui/i18n`, `packages/i18n/src/useDisplayLocale.ts` — ends
+     * its provider chain on the concrete `'en'`, for determinism, when the chain
+     * yields no tag at all. That hook's docblock names this one in return.
      */
     locale?: string;
     /**
@@ -88,14 +105,40 @@ export interface DisplayNumberFormatOptions {
      *
      * ⚠️ INTERIM DEFAULT (objectui#4033, PM ruling 2026-08-11). Suppressing
      * grouping for every scale-0 number is a transitional policy with a known,
-     * accepted cost: a large scale-0 COUNT loses its separators too. It is the
-     * better trade only until the spec gains an authorable presentation hint
-     * (`useGrouping` / `displayFormat` — being specified separately, contract-first,
-     * in the objectstack repo). When that hint lands it OVERRIDES this default,
-     * and this heuristic should be reduced to the fallback for fields that
-     * declare nothing.
+     * accepted cost: a large scale-0 COUNT loses its separators too. The
+     * authorable hint it was waiting for has landed as
+     * {@link DisplayNumberFormatOptions.useGrouping} (objectui#11026): an
+     * authored boolean OVERRIDES this default, and the heuristic is now only the
+     * fallback for a field that declares nothing.
      */
     scale?: number;
+    /**
+     * The FIELD's authored `useGrouping` — `FieldSchema.useGrouping` in
+     * `@objectstack/spec`, the author's digit-grouping hint — and nothing else.
+     * Like `scale` it is a POLICY input: pass it only when a field declaration
+     * actually said so (objectui#11026).
+     *
+     * Three-valued, and the spec's own reading of each value is the one this
+     * option implements:
+     *
+     *   - `undefined` — the author made no judgement, so the renderer decides:
+     *     the `scale`/`currency` heuristic in {@link shouldGroupDisplayNumber},
+     *     unchanged.
+     *   - `false` — the author's explicit opt-out (a year, an ID, a zip code).
+     *     Never grouped, whatever `scale` or `currency` would have suggested.
+     *   - `true` — the author pins grouping ON, overriding the heuristic the
+     *     other way (a scale-0 count that should read `2,026`).
+     *
+     * The spec maps the key 1:1 onto `Intl.NumberFormat`'s `useGrouping`, so an
+     * authored `true` reaches `Intl` as `true`, which means "always". That is
+     * deliberately NOT what the heuristic's own "group" answer does: it omits
+     * the key and keeps the locale's "auto" (see the `Intl` note inside
+     * {@link formatDisplayNumber}). The two differ where a locale leaves a
+     * four-digit number alone under "auto" (es-ES and pl-PL render `1234`); an
+     * author who pinned grouping on gets `1.234` / `1 234` there, because that
+     * is what they declared.
+     */
+    useGrouping?: boolean;
     /**
      * How the number relates to a percentage — the ONE place that distinction is
      * expressed, because getting it wrong is the whole of objectui#4576.
@@ -111,9 +154,13 @@ export interface DisplayNumberFormatOptions {
      * repo's runner, `80.175` percentage points formatted to 2 decimals renders
      * `80.18%` when formatted directly and `80.17%` after the divide-and-remultiply
      * — 27,581 of 1,200,013 ordinary-magnitude en-US forms move, plus every
-     * value at the top of the double range (`MAX_SAFE_INTEGER`, `1e23`). A caller
-     * holding percentage points must therefore NOT reach for `'percent'`; that is
-     * exactly the trap this option removes.
+     * value at the top of the double range (`MAX_SAFE_INTEGER`, `1e23`). That
+     * count is objectui#4576's tie-dense grid — 0.005 steps to 2,000, precisions
+     * 0/1/2 — measured on `formatDisplayNumber` / `formatMeasure`'s call shape.
+     * objectui#4590 re-measured the same route through `formatPercent` and
+     * reports 27,577 of 1,200,003: a different form set, not a correction of this
+     * one. A caller holding percentage points must therefore NOT reach for
+     * `'percent'`; that is exactly the trap this option removes.
      *
      * `'percentPoints'` is implemented with `Intl`'s `style: 'unit'` /
      * `unit: 'percent'`, which was measured to produce a BYTE-IDENTICAL percent
@@ -133,11 +180,17 @@ export interface DisplayNumberFormatOptions {
  * The grouping policy, alone and testable: does this number get thousands
  * separators?
  *
- * @param scale    the field's declared `scale`, or `undefined` when the caller
- *                 has no field declaration behind it
- * @param currency ISO 4217 code when the number is money
+ * This is the ONE place the decision is made. An authored `useGrouping`
+ * answers it outright; only when the field declared nothing does the
+ * `scale`/`currency` heuristic below get a say (objectui#11026).
+ *
+ * @param scale       the field's declared `scale`, or `undefined` when the
+ *                    caller has no field declaration behind it
+ * @param currency    ISO 4217 code when the number is money
+ * @param useGrouping the field's authored `useGrouping`, or `undefined` when
+ *                    the author declared none
  */
-export declare function shouldGroupDisplayNumber(scale?: number, currency?: string): boolean;
+export declare function shouldGroupDisplayNumber(scale?: number, currency?: string, useGrouping?: boolean): boolean;
 /**
  * Format a number for DISPLAY, in the active locale, under the grouping policy
  * above.