@object-ui/core 17.6.0 → 18.0.0

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

@@ -73,8 +73,21 @@ 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.
+ *
+ * ⛔ `inlineEdit` → `editInline` is NOT a row here, although it lands in the same
+ * block (objectui#5144). Every row of this table is deleted after it folds;
+ * `inlineEdit` must survive its fold, because it is also the MODE `ListView`
+ * opens the grid in. See {@link foldsInlineEditIntoEditInline}.
  */
 const SHOW_FLAG_TO_USER_ACTION = {
     showSearch: 'search',
@@ -85,6 +98,43 @@ const SHOW_FLAG_TO_USER_ACTION = {
     showHideFields: 'hideFields',
     showColor: 'rowColor',
 };
+/**
+ * Whether a view's `inlineEdit` folds into `userActions.editInline`
+ * (objectui#5144, the maintainer's B-fold).
+ *
+ * The spec declares `userActions.editInline` with `.default(true)` since the
+ * maintainer's v18 ruling (objectstack#22605): a list is editable in place by
+ * default, and `editInline: false` is the opt-out. It declares the view's
+ * `inlineEdit` as the same kind of permission ("allow inline editing"). Stored
+ * views carry `inlineEdit`, not `editInline`: authored views declare it, and
+ * the console's list toolbar used to write it. Folding it here puts both keys
+ * on one vocabulary, so `ListView` can read `editInline` with the spec default
+ * and a view's own `inlineEdit` still decides it when `editInline` is absent.
+ *
+ * The console's toolbar no longer writes `inlineEdit` (objectui#5144, ruling
+ * E). It persisted a user's edit mode into this permission key, so switching
+ * the toggle off stored `inlineEdit: false` and the fold then read the view as
+ * not offering inline editing. The toggle is session state now.
+ *
+ * Two rules, each the same as a fold above:
+ *  - The value carries over: `inlineEdit: true` folds to `editInline: true`,
+ *    and `inlineEdit: false` to `editInline: false`.
+ *  - An explicit `userActions.editInline` wins. It is the spec key, so a
+ *    stored `inlineEdit` only fills the gap.
+ *
+ * One departure, the `data` → `objectName` one: `inlineEdit` is KEPT. The other
+ * folds delete because the legacy key has one meaning and one home.
+ * `inlineEdit` has a second use. It is the spec's own `ListView.inlineEdit`,
+ * and `ListView` seeds the grid's edit MODE from it on each load. The toolbar
+ * toggle then flips that mode for the session. `editInline` decides whether
+ * the toggle is offered at all. Deleting `inlineEdit` would open every such
+ * view out of edit mode.
+ */
+function foldsInlineEditIntoEditInline(s) {
+    if (typeof s.inlineEdit !== 'boolean')
+        return false;
+    return !(isRecord(s.userActions) && typeof s.userActions.editInline === 'boolean');
+}
 /**
  * Legacy `sharing.visibility` → the spec's `ViewSharing.type`. The spec models
  * two ownership kinds; objectui's four-value audience enum collapses onto them:
@@ -102,31 +152,136 @@ const ARIA_KEY_ALIASES = {
     describedBy: 'ariaDescribedBy',
 };
 /**
- * Per-view-type config aliases → the spec key each one aliases (#2890, the
- * phase-3 carry-over).
+ * The view kinds `ListView` actually draws.
  *
- * 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.
+ * 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.
  *
- * `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.
+ * ⚠️ 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.
  *
- * 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.
+ * `hasOwnProperty`, not `in` — same trap as {@link rowHeightToDensityMode}:
+ * `in` walks the prototype chain, so `'toString'` would read as a view kind.
  */
-const PER_VIEW_CONFIG_ALIASES = {
-    kanban: { groupField: 'groupByField', cardFields: 'columns' },
-    gallery: { imageField: 'coverField' },
-    timeline: { dateField: 'startDateField' },
+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;
+}
 /**
  * ObjectUI's `list-view` node historically used a different vocabulary from
  * `@objectstack/spec` for the same concepts (`fields` where the spec says
@@ -168,6 +323,12 @@ const PER_VIEW_CONFIG_ALIASES = {
  *    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.
+ *  - the view's `inlineEdit` → `userActions.editInline` (objectui#5144), with
+ *    the value carried over and an explicit `editInline` winning. `inlineEdit`
+ *    stays on the result, because `ListView` seeds the grid's edit mode from
+ *    it. See {@link foldsInlineEditIntoEditInline}. An absent pair stays
+ *    absent here as well; `ListView` reads that as on, the spec's default
+ *    (objectstack#22605).
  *  - `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`
@@ -179,10 +340,34 @@ const PER_VIEW_CONFIG_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 more providers than
+ *        `object`, `value` is 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
@@ -190,16 +375,14 @@ const PER_VIEW_CONFIG_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.
+ *
+ * No longer folded: the four PER-VIEW-TYPE config aliases phase 3 carried over
+ * (`kanban.groupField` → `groupByField`, `kanban.cardFields` → `columns`,
+ * `gallery.imageField` → `coverField`, `timeline.dateField` →
+ * `startDateField`). objectui#6152 round 14 retired that fold with every
+ * renderer-side reader of the four: each list-view door refuses them by name
+ * (rounds 11 and 12), and a stored block that still carries one passes through
+ * here untouched and binds nothing downstream.
  */
 export function normalizeListViewSchema(schema) {
     if (!schema || typeof schema !== 'object')
@@ -208,16 +391,32 @@ 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');
+    const foldInlineEdit = foldsInlineEditIntoEditInline(s);
     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);
+    // `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`
@@ -231,22 +430,9 @@ 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 &&
+    if (!foldColumns && !foldRowHeight && !foldFilter && !legacyFlags.length && !foldInlineEdit &&
         !foldDescription && !foldAria && !foldSharing && !defaultViewKind &&
-        !foldColumnIdentity && !perViewFolds.length) {
+        !foldColumnIdentity && !foldObjectName) {
         return schema;
     }
     const next = { ...s };
@@ -270,7 +456,7 @@ export function normalizeListViewSchema(schema) {
             next.filter = legacyFilters;
         delete next.filters;
     }
-    if (legacyFlags.length) {
+    if (legacyFlags.length || foldInlineEdit) {
         const ua = { ...(isRecord(next.userActions) ? next.userActions : {}) };
         for (const flag of legacyFlags) {
             const key = SHOW_FLAG_TO_USER_ACTION[flag];
@@ -278,6 +464,10 @@ export function normalizeListViewSchema(schema) {
                 ua[key] = s[flag];
             delete next[flag];
         }
+        // objectui#5144. Gap-fill only, and `inlineEdit` is not deleted: see
+        // `foldsInlineEditIntoEditInline`.
+        if (foldInlineEdit)
+            ua.editInline = s.inlineEdit;
         next.userActions = ua;
     }
     if (foldDescription) {
@@ -320,20 +510,9 @@ 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.
@@ -137,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.

package/dist/utils/number-display.js

@@ -9,11 +9,23 @@
  * 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 function shouldGroupDisplayNumber(scale, currency) {
+export function shouldGroupDisplayNumber(scale, currency, useGrouping) {
+    // The author's explicit declaration beats every guess below, money included:
+    // the spec reads `false` as "never grouped, regardless of what the
+    // renderer's heuristic would have guessed", and `true` as the same override
+    // in the other direction.
+    if (typeof useGrouping === 'boolean')
+        return useGrouping;
     // Money always groups — including money whose currency code could not be
     // resolved, which still renders as an amount (just without a symbol).
     if (currency)
@@ -32,7 +44,7 @@ export function shouldGroupDisplayNumber(scale, currency) {
  * malformed tag from a tenant config must never take a grid cell down.
  */
 export function formatDisplayNumber(value, options = {}) {
-    const { locale, currency, scale, style, ...passthrough } = options;
+    const { locale, currency, scale, useGrouping, style, ...passthrough } = options;
     const intlOptions = { ...passthrough };
     if (style === 'percentPoints') {
         // The locale's percent convention WITHOUT `style: 'percent'`'s ×100 — see
@@ -50,15 +62,25 @@ export function formatDisplayNumber(value, options = {}) {
         delete intlOptions.unit;
         delete intlOptions.unitDisplay;
     }
-    // ⚠️ Set `useGrouping` ONLY to suppress. `useGrouping: true` is NOT the same
-    // as omitting the key: `true` means "always", while omitting it means "auto"
-    // (and "min2" under compact notation), which is the locale's own preference.
-    // Measured — for 1234: es-ES "auto" → `1234` but "always" → `1.234`; pl-PL
-    // "auto" → `1234` but "always" → `1 234`. Writing `true` here would silently
-    // override those locales' conventions in the name of preserving en-US output.
-    if (!shouldGroupDisplayNumber(scale, currency)) {
+    // ⚠️ Never write `useGrouping: true` on the renderer's own behalf.
+    // `useGrouping: true` is NOT the same as omitting the key: `true` means
+    // "always", while omitting it means "auto" (and "min2" under compact
+    // notation), which is the locale's own preference. Measured — for 1234:
+    // es-ES "auto" → `1234` but "always" → `1.234`; pl-PL "auto" → `1234` but
+    // "always" → `1 234`. Writing `true` for a field that declared nothing would
+    // silently override those locales' conventions in the name of preserving
+    // en-US output.
+    //
+    // The ONE `true` this function writes is the author's own (objectui#11026):
+    // `FieldSchema.useGrouping` maps 1:1 onto this `Intl` option, and an author
+    // who pinned grouping on asked for "always". The decision itself is made
+    // once, above, by `shouldGroupDisplayNumber`; this only spells it for `Intl`.
+    if (!shouldGroupDisplayNumber(scale, currency, useGrouping)) {
         intlOptions.useGrouping = false;
     }
+    else if (useGrouping === true) {
+        intlOptions.useGrouping = true;
+    }
     try {
         return new Intl.NumberFormat(locale, intlOptions).format(value);
     }