@object-ui/core 17.3.0 → 17.5.0

package/dist/utils/dashboard-filters.d.ts

@@ -18,7 +18,8 @@
  * Everything in this module is pure and synchronous so the binding rules
  * are unit-testable in isolation from React and the data layer.
  */
-import type { DashboardComponentSchema, DashboardWidgetSchema, PageVariable } from '@object-ui/types';
+import type { DashboardComponentSchema, DashboardWidgetSchema, I18nLabel, PageVariable } from '@object-ui/types';
+import { DATE_RANGE_PRESETS } from '@objectstack/spec/ui';
 /** Reserved filter name for the dashboard's built-in date range. */
 export declare const DATE_RANGE_FILTER_NAME = "dateRange";
 export interface DashboardFilterDef {
@@ -26,17 +27,41 @@ export interface DashboardFilterDef {
     name: string;
     /** Default target field when a widget declares no explicit binding. */
     field: string;
-    label?: string;
+    /**
+     * Display label, in @objectstack/spec's `I18nLabel` vocabulary — a plain
+     * string, or an inline per-locale map (`{ en: 'Owner', 'zh-CN': '负责人' }`).
+     *
+     * Widened from `string` under the objectstack#5428 ruling of 2026-08-06
+     * (option A): `GlobalFilterSchema.label` has been `I18nLabel` on the spec
+     * side since 17.0.0-rc.6, so declaring it `string` here made this module
+     * NARROWER than the contract it implements — which is exactly why the filter
+     * bar's map reads were invisible to `tsc` (objectui#4163).
+     *
+     * This module is locale-free BY DESIGN (`@object-ui/core` is logic-only), so
+     * it carries the authored vocabulary through unresolved and the RENDER side
+     * collapses it to the active language. Resolving here would need a locale
+     * this layer has no business knowing.
+     */
+    label?: string | I18nLabel;
     type: 'text' | 'select' | 'date' | 'number' | 'lookup' | 'dateRange';
     /**
      * Static options, NORMALIZED to `{ value, label }` pairs by
-     * `resolveDashboardFilterDefs` — authors may write either the
-     * @objectstack/spec object form (`{ value, label }`) or the bare-string
-     * shorthand; consumers always see the object form.
+     * `resolveDashboardFilterDefs` — consumers always see the object form.
+     *
+     * The canonical authoring form is @objectstack/spec's `{ value, label }`
+     * pair, and it is the ONLY one the platform accepts at publish. A bare-string
+     * shorthand in a STORED document is still lifted here, with a deprecation
+     * warning, on the objectstack#7917 retirement schedule — see
+     * `normalizeFilterOptions`. Do not author a new one.
+     *
+     * The PAIR SHAPE is normalized; the label's own vocabulary is not. `label`
+     * is `I18nLabel` in `GlobalFilterSchema.options[]` too, and it reaches the
+     * renderer as authored — see `normalizeFilterOptions` for why collapsing it
+     * here was data loss rather than normalization.
      */
     options?: Array<{
         value: string;
-        label: string;
+        label: string | I18nLabel;
     }>;
     optionsFrom?: {
         object: string;
@@ -58,8 +83,29 @@ export interface DateRangeValue {
     from?: string;
     to?: string;
 }
-/** Preset keys the filter bar offers, in display order. */
-export declare const DATE_RANGE_PRESETS: string[];
+/**
+ * Preset keys the filter bar offers, in display order — the spec's list,
+ * RE-EXPORTED since objectui#4167 rather than derived from the local bounds
+ * table (objectstack#4115).
+ *
+ * `@objectstack/spec` 17.0.0-rc.6 publishes `DATE_RANGE_PRESETS`, and its own
+ * doc comment names this module as one of the three copies the extraction
+ * (objectstack#4614) existed to collapse: "it used to exist three times —
+ * inline in `dateRange.defaultRange`, as `PRESET_RANGES` in objectui's
+ * `dashboard-filters`, and as a hand-written table in
+ * `content/docs/ui/dashboards.mdx`". So the burn-down direction here is not a
+ * judgement call, it is upstream's stated intent, and the two lists were
+ * already identical in content AND display order — the copy had nothing to
+ * protect.
+ *
+ * What stays local is the BOUNDS table above, which is the other half of
+ * #4614's design ("the two vocabularies live one import apart and neither
+ * restates the other's grammar"): the spec owns which presets exist, this
+ * module owns what each one resolves to in date-macro tokens.
+ */
+export { DATE_RANGE_PRESETS };
+/** Reset the shorthand-options warn-once memo. Exported for tests. */
+export declare function resetDashboardFilterWarnings(): void;
 /**
  * Normalize a dashboard schema's filter declarations into a flat list of
  * filter definitions. The built-in `dateRange` (when declared) comes first

package/dist/utils/dashboard-filters.js

@@ -5,6 +5,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import { liftLegacyGlobalFilterDefault } from '@object-ui/types';
+import { DATE_RANGE_PRESETS } from '@objectstack/spec/ui';
 import { resolveDateMacros } from './date-macros.js';
 /** Reserved filter name for the dashboard's built-in date range. */
 export const DATE_RANGE_FILTER_NAME = 'dateRange';
@@ -14,6 +16,18 @@ const DATE_RANGE_DEFAULT_FIELD = 'created_at';
  * Date-range presets → date-macro token bounds. Tokens stay symbolic in the
  * generated condition; every widget renderer resolves them at query time via
  * `resolveDateMacros`, exactly like hand-authored widget filters.
+ *
+ * `satisfies Record<DateRangePreset, …>` is the load-bearing half of
+ * objectui#4167, not decoration. `DATE_RANGE_PRESETS` below is now the spec's
+ * list rather than `Object.keys` of this table, so the two could otherwise
+ * drift in the one direction the spec's own comment on that const names as the
+ * failure mode: a preset the SCHEMA knows and this table has no bounds for
+ * "validates clean and then resolves to nothing" — it would reach the filter
+ * bar's dropdown, be selected, and produce no range. The `satisfies` makes that
+ * a compile error at the moment the spec adds a preset (missing key), and makes
+ * a local invention a compile error too (excess key). The annotation form
+ * `const PRESET_RANGES: Record<DateRangePreset, …>` would NOT do this: a string
+ * index signature satisfies every literal key, so the check passes vacuously.
  */
 const PRESET_RANGES = {
     today: { from: '{today}', to: '{today}' },
@@ -30,8 +44,39 @@ const PRESET_RANGES = {
     last_30_days: { from: '{30_days_ago}', to: '{today}' },
     last_90_days: { from: '{90_days_ago}', to: '{today}' },
 };
-/** Preset keys the filter bar offers, in display order. */
-export const DATE_RANGE_PRESETS = Object.keys(PRESET_RANGES);
+/**
+ * Bounds for a preset NAME that may not be one.
+ *
+ * The runtime receives whatever a stored dashboard carries, so an unrecognised
+ * name must warn (see `buildFilterCondition`) rather than fail to compile. That
+ * read is confined here so the `satisfies` pin above stays the single place
+ * deciding which names exist — an unguarded `PRESET_RANGES[someString]` would
+ * have forced the table back to a `Record<string, …>` and taken the pin with it.
+ */
+function presetBounds(preset) {
+    return PRESET_RANGES[preset];
+}
+/**
+ * Preset keys the filter bar offers, in display order — the spec's list,
+ * RE-EXPORTED since objectui#4167 rather than derived from the local bounds
+ * table (objectstack#4115).
+ *
+ * `@objectstack/spec` 17.0.0-rc.6 publishes `DATE_RANGE_PRESETS`, and its own
+ * doc comment names this module as one of the three copies the extraction
+ * (objectstack#4614) existed to collapse: "it used to exist three times —
+ * inline in `dateRange.defaultRange`, as `PRESET_RANGES` in objectui's
+ * `dashboard-filters`, and as a hand-written table in
+ * `content/docs/ui/dashboards.mdx`". So the burn-down direction here is not a
+ * judgement call, it is upstream's stated intent, and the two lists were
+ * already identical in content AND display order — the copy had nothing to
+ * protect.
+ *
+ * What stays local is the BOUNDS table above, which is the other half of
+ * #4614's design ("the two vocabularies live one import apart and neither
+ * restates the other's grammar"): the spec owns which presets exist, this
+ * module owns what each one resolves to in date-macro tokens.
+ */
+export { DATE_RANGE_PRESETS };
 /**
  * ISO calendar date, optionally carrying a time part — `2026-01-15`,
  * `2026-01-15T08:30:00Z`. Deliberately narrower than `Date.parse`, which
@@ -65,10 +110,117 @@ function warnDateFilter(message) {
     if (typeof console !== 'undefined')
         console.warn(`[dashboard-filters] ${message}`);
 }
+/**
+ * Dev-mode gate, matching `actions/actionKeys.ts` — a deprecation warning that
+ * floods a production console is a warning that gets muted.
+ */
+const isDev = () => globalThis.process?.env?.NODE_ENV !==
+    'production';
+/**
+ * Warn-once memo for the bare-string `options` shorthand (objectui#4356).
+ *
+ * Keyed by filter NAME **and** the offending values, deliberately — the same
+ * reasoning `warnOnUnknownActionKeys` records for its own memo. Keying on the
+ * name alone would report the first dashboard carrying a shorthand `status`
+ * filter and stay silent about every other one, sending the author to fix one
+ * symptom; keying on the values alone would collapse two genuinely different
+ * filters that happen to share an option list. The memo is bounded by the
+ * number of authored filters either way.
+ *
+ * This lives at module scope because `resolveDashboardFilterDefs` runs on every
+ * dashboard render — per-call state would warn once per frame, which is the
+ * flood the dedupe exists to prevent.
+ */
+const warnedShorthandOptions = new Set();
+/** Reset the shorthand-options warn-once memo. Exported for tests. */
+export function resetDashboardFilterWarnings() {
+    warnedShorthandOptions.clear();
+}
+/**
+ * Apply the ADR-0089 legacy-alias lift to ONE stored `globalFilters` entry, and
+ * say so out loud when it fires (objectui#4165).
+ *
+ * ## The alias, at this read site
+ *
+ * **What it is.** `defaultValue: { preset: 'last_7_days' }` on a `type: 'date'`
+ * filter. The canonical spelling is the bare preset NAME,
+ * `defaultValue: 'last_7_days'` — one of the three the spec's rc.6 refinement
+ * accepts (preset name / ISO date / date-macro token).
+ *
+ * **Why it is lifted here rather than tolerated.** Maintainer ruling on
+ * objectui#4165 (2026-08-11): 「spec stays strict — no widening」. objectui's
+ * `GlobalFilterSchema` now carries that refinement, so a document holding the
+ * object form fails validation; lifting it BEFORE anything reads the entry
+ * makes the declaration canonical by construction. The lift itself lives in
+ * `@object-ui/types`' `dashboard-filter-alias.ts` (one implementation, shared
+ * with the designer's rewrite-on-save path); this is one of its two call sites.
+ *
+ * **What it does NOT buy, measured.** It does not rescue rendering. A legacy
+ * declaration already resolved correctly before #4165 and still does with this
+ * call deleted — reverse-verified, only the warning below changes. The reason
+ * is a coincidence worth knowing: `{ preset }` is also the runtime VALUE shape
+ * `normalizeDateDefault` produces for the canonical name, and that function
+ * passes non-strings through untouched. That coincidence is why the object form
+ * looked harmless for so long, and how the schema's own prose drifted into
+ * calling it "the on-disk form". Read this call as canonicalization plus
+ * observability, not as a repair — claiming more would be claiming coverage the
+ * tests in `__tests__/dashboard-filters.test.ts` do not have.
+ *
+ * **When it may be removed.** At the next MAJOR of `@object-ui/types` (18.0.0).
+ * By then every dashboard opened in the designer has been rewritten to the bare
+ * name, because `DashboardDesignPage` lifts into the editable draft and the
+ * next save persists it. Delete this function and its call below together with
+ * the lift itself; a document still carrying the object form then gets the
+ * spec's named rejection, which is the intended end state.
+ *
+ * The warning is not decoration: a silent lift can never be retired, because
+ * nothing would ever show that the last legacy document is gone (ADR-0078 —
+ * nothing silently inert).
+ */
+function liftLegacyFilterDeclaration(filter) {
+    const lifted = liftLegacyGlobalFilterDefault(filter);
+    if (lifted === filter)
+        return filter;
+    const name = filter?.name
+        ?? filter?.field
+        ?? '?';
+    const preset = lifted?.defaultValue;
+    warnDateFilter(`filter "${name}": \`defaultValue: { preset: ${JSON.stringify(preset)} }\` is a LEGACY ` +
+        `spelling (objectui#4165) and was lifted to the canonical bare preset name ` +
+        `${JSON.stringify(preset)}. Rewrite the stored dashboard — the object form is ` +
+        `refused by @objectstack/spec and its acceptance here ends with @object-ui/types 18.`);
+    return lifted;
+}
 /**
  * Normalize a date filter's DECLARED default into the `DateRangeValue` shape
  * every date consumer in this module reads (framework#4475).
  *
+ * ## Declaration space vs value space — the distinction objectui#4165 turned on
+ *
+ * These are two different things that share the name `defaultValue`, and
+ * conflating them is what produced #4165:
+ *
+ *  - the **declaration** is `globalFilters[].defaultValue` in a stored
+ *    dashboard. `@objectstack/spec` owns it, it is `string | number | boolean`,
+ *    and since rc.6 a refinement holds a `type: 'date'` one to a preset NAME,
+ *    an ISO date or a date-macro token. A bare preset name is the canonical
+ *    spelling and the object form is a retiring alias (see
+ *    `liftLegacyFilterDeclaration` above);
+ *  - the **value** is what this function RETURNS: `DashboardFilterDef
+ *    .defaultValue`, which seeds the filter variable and is read by
+ *    `DateRangeFilter` (`.preset`/`.from`/`.to`) and `buildFilterCondition`.
+ *    That shape is `DateRangeValue`, it is objectui-internal, the spec has no
+ *    opinion about it, and for a preset it is `{ preset }`.
+ *
+ * So this function converts declaration → value. It is NOT a producer of stored
+ * metadata: nothing writes a resolved `DashboardFilterDef` back into a
+ * dashboard document (measured in #4165 — `resolveDashboardFilterDefs`' only
+ * callers are `DashboardRenderer` and `DashboardWidgetInspector`, both read
+ * side). Making it emit the bare name instead would therefore not change one
+ * byte on disk; it would only hand `DateRangeFilter` a string it cannot read
+ * and `buildFilterCondition` a value it warns-and-skips — i.e. re-open
+ * framework#4475 exactly, which is why it keeps emitting `{ preset }`.
+ *
  * The built-in `dateRange` declaration has always been normalized this way —
  * `schema.dateRange.defaultRange` is a preset NAME and
  * `resolveDashboardFilterDefs` lifts it to `{ preset }`. A `globalFilters`
@@ -101,15 +253,67 @@ function normalizeDateDefault(type, defaultValue) {
 /**
  * Normalize a filter's static `options` declaration to `{ value, label }`
  * pairs. The @objectstack/spec `GlobalFilterSchema.options` form is
- * `{ value, label }` objects (label possibly an i18n record); the bare-string
- * shorthand (`options: ['EMEA', …]`) is also accepted. Rendering an
- * un-normalized object child crashes React — this is the single place both
- * shapes converge.
+ * `{ value, label }` objects; the bare-string shorthand (`options: ['EMEA', …]`)
+ * is still lifted, but is DEPRECATED and now says so out loud. Rendering an
+ * un-normalized option crashes React — this is the single place both shapes
+ * converge.
+ *
+ * ## The shorthand's deprecation (objectui#4356, objectstack#7917)
+ *
+ * Maintainer ruling of 2026-08-12 on objectstack#7917, verbatim 「7917 ②」:
+ * option ② — **the spec stays strict; the runtime bare-string lift retires
+ * behind a deprecation window sized by a stored-dashboard survey.** So a
+ * document spelling `options: ['EMEA']` renders here and is refused the moment
+ * it reaches the platform's validation — the "one strict contract beats N
+ * dialects" divergence AGENTS.md #0.1 names, with the renderer's tolerance
+ * acting as a second de-facto contract.
+ *
+ * This is the WARN half of that window (Phase 1). The lift itself is unchanged
+ * and remains mechanically lossless (`'EMEA'` → `{ value: 'EMEA', label:
+ * 'EMEA' }`), because stored dashboards carry the shorthand and dropping it
+ * silently would turn a rendering filter into an empty one. Removal (Phase 2)
+ * is scheduled on objectstack#7917, earliest one minor release after this ships
+ * and not before the live-tenant channel has actually been queried.
+ *
+ * The warning is not decoration: a silent lift can never be retired, because
+ * nothing would ever show that the last shorthand document is gone (ADR-0078 —
+ * nothing silently inert). It is the same reasoning `liftLegacyFilterDeclaration`
+ * records above, for the sibling alias.
+ *
+ * Phase 0 shipped in the same PR: objectui's own docs, its `plugin-dashboard`
+ * README and its schema-catalog corpus stopped TEACHING the shorthand, so the
+ * stored population is no longer growing while this warning asks authors to
+ * migrate. Warning authors while the docs still taught the form would have been
+ * a contradiction users report as a bug.
+ *
+ * ## What is normalized, and what is deliberately NOT (objectui#4032 / #4163)
+ *
+ * The PAIR SHAPE is normalized (`value` stringified, a bare string lifted to a
+ * pair). The LABEL's authoring vocabulary is carried through untouched, because
+ * `label` is `I18nLabel` — a string OR an inline per-locale map.
+ *
+ * This line used to read:
+ *
+ * ```ts
+ * label: typeof label === 'string' && label ? label : String(value),
+ * ```
+ *
+ * which looks like defensive normalization and is data loss. An option authored
+ * `{ value: 'domestic', label: { en: 'Domestic', 'zh-CN': '国内' } }` normalized
+ * to `label: 'domestic'` — the raw STORED VALUE — so the control lost the
+ * authored text in *every* locale, English included. Nothing downstream could
+ * recover it: by the time a renderer saw the def, the map was gone.
+ *
+ * A map is therefore preserved and the render side resolves it against the
+ * active language. Anything that is neither a string nor an object is not a
+ * label in any vocabulary the spec admits, and still falls back to the value.
  */
-function normalizeFilterOptions(options) {
+function normalizeFilterOptions(options, filterName) {
     if (!Array.isArray(options) || options.length === 0)
         return undefined;
     const normalized = [];
+    /** Every bare-string member, in authored order — one warning names them all. */
+    const shorthand = [];
     for (const o of options) {
         if (o === null || o === undefined)
             continue;
@@ -118,17 +322,47 @@ function normalizeFilterOptions(options) {
             if (value === undefined || value === null)
                 continue;
             const label = o.label;
+            const isMap = label !== null && typeof label === 'object' && !Array.isArray(label);
             normalized.push({
                 value: String(value),
-                label: typeof label === 'string' && label ? label : String(value),
+                label: (typeof label === 'string' && label) || isMap ? label : String(value),
             });
         }
         else {
+            shorthand.push(String(o));
             normalized.push({ value: String(o), label: String(o) });
         }
     }
+    if (shorthand.length > 0)
+        warnShorthandOptions(filterName, shorthand);
     return normalized.length > 0 ? normalized : undefined;
 }
+/**
+ * Say the deprecated shorthand out loud — once per offending filter per
+ * session, naming the filter and printing the canonical replacement.
+ *
+ * Collected per FILTER rather than per option: a filter declaring
+ * `['EMEA', 'APAC', 'AMER']` is one authoring mistake in one place, so it earns
+ * one warning carrying all three values, not three warnings the author has to
+ * reassemble. A MIXED array (`[{ value: 'won', … }, 'lost']`) names only the
+ * bare members, which are the ones that need rewriting — partial migrations
+ * happen and a warning that re-reports the already-canonical members is noise.
+ */
+function warnShorthandOptions(filterName, shorthand) {
+    if (!isDev())
+        return;
+    const memo = `${filterName}:${shorthand.join(',')}`;
+    if (warnedShorthandOptions.has(memo))
+        return;
+    warnedShorthandOptions.add(memo);
+    const canonical = shorthand.map((v) => `{ value: ${JSON.stringify(v)}, label: ${JSON.stringify(v)} }`).join(', ');
+    warnDateFilter(`filter "${filterName}": \`options\` carries the bare-string shorthand ` +
+        `(${shorthand.map((v) => JSON.stringify(v)).join(', ')}), which @objectstack/spec's ` +
+        `\`GlobalFilterSchema\` REFUSES at publish — a dashboard authored this way renders here ` +
+        `and is rejected the moment it reaches the platform (objectui#4356). Rewrite the stored ` +
+        `dashboard to the canonical pair form: [${canonical}]. Still lifted here for already-` +
+        `persisted dashboards; the lift is removed on the objectstack#7917 schedule.`);
+}
 /**
  * Normalize a dashboard schema's filter declarations into a flat list of
  * filter definitions. The built-in `dateRange` (when declared) comes first
@@ -148,9 +382,14 @@ export function resolveDashboardFilterDefs(schema) {
             allowCustomRange: schema.dateRange.allowCustomRange,
         });
     }
-    for (const f of schema.globalFilters ?? []) {
-        if (!f?.field)
+    for (const raw of schema.globalFilters ?? []) {
+        if (!raw?.field)
             continue;
+        // ADR-0089 legacy-alias lift (#4165) — a stored `defaultValue: { preset }`
+        // becomes the canonical bare name BEFORE anything else reads the entry, so
+        // a legacy dashboard resolves to byte-identical defs. See
+        // `liftLegacyFilterDeclaration` for the retirement window.
+        const f = liftLegacyFilterDeclaration(raw);
         const name = f.name || f.field;
         if (byName.has(name) && typeof console !== 'undefined') {
             console.warn(`[dashboard-filters] duplicate filter name "${name}" — the later definition wins`);
@@ -161,7 +400,17 @@ export function resolveDashboardFilterDefs(schema) {
             field: f.field,
             label: f.label,
             type,
-            options: normalizeFilterOptions(f.options),
+            // `name` is the identifying context the deprecation warning needs, and
+            // the local above already resolved it — nothing new is threaded through a
+            // public signature for it. `normalizeFilterOptions` is module-private, so
+            // widening ITS parameter list is not a contract move.
+            //
+            // (Deliberately not restating that local's expression here: the
+            // column-identity ratchet in `__tests__/column-identity.ratchet.test.ts`
+            // is a LINE-LEVEL scanner, so a comment quoting it reads as a second
+            // dual read and fails the count — a false positive worth avoiding rather
+            // than absorbing into the inventory, which would mask a future real one.)
+            options: normalizeFilterOptions(f.options, name),
             optionsFrom: f.optionsFrom,
             // framework#4475 — same preset-name lifting the built-in `dateRange`
             // above already does; see normalizeDateDefault for why a bare string is
@@ -222,7 +471,7 @@ export function buildFilterCondition(def, value) {
         const v = value;
         if (typeof v === 'object') {
             const preset = typeof v.preset === 'string' && v.preset ? v.preset : undefined;
-            const range = preset ? PRESET_RANGES[preset] : undefined;
+            const range = preset ? presetBounds(preset) : undefined;
             const from = range?.from ?? v.from;
             const to = range?.to ?? v.to;
             if (preset && !range) {

package/dist/utils/dataset-format.d.ts

@@ -15,21 +15,34 @@
  * Pure (no React / i18n) so it can live in `@object-ui/core` and be imported
  * by both `@object-ui/plugin-dashboard` and `@object-ui/plugin-report`.
  */
+import type { AnalyticsResult } from '@objectstack/spec/contracts';
 import type { PercentScale } from '@objectstack/spec/data';
 /**
- * Column metadata the analytics server returns alongside the rows: a display
- * `label` for both dimensions and measures, plus a measure's numeral `format`
- * and declared `currency`. A superset of {@link ChartResultField} (which only
- * needs name/label/format).
+ * Column metadata the analytics server returns alongside the rows — the spec's
+ * `AnalyticsResult.fields[]` element BY REFERENCE, never a local restatement of
+ * it (objectui#3815). Read `@objectstack/spec` for what a column carries; this
+ * comment deliberately does not re-list the keys, because the enumeration it
+ * replaced was the latent bug: a hand-written interface stops at the contract
+ * of the day it was written and cannot grow with the spec, and here it would
+ * not even fail to compile — three surfaces (`plugin-dashboard`'s
+ * `DatasetWidget`, `plugin-report`'s `DatasetReportRenderer`, app-shell's
+ * `DatasetPreview`) consume this name AS the real thing, so a spec column key
+ * they never learn about is one they can never render. The same derive-don't-
+ * restate fix as the parameter side (#3613/#3753) and the adapter return side
+ * (#3752); this was the last surviving restatement of the family.
+ *
+ * `type` is REQUIRED, as the contract has it. The restatement had relaxed it to
+ * optional, which was a promise the server never asked for: nothing in this repo
+ * constructs a result column (every value originates in
+ * `ObjectStackAdapter.queryDataset`, which already declares the spec element),
+ * and nothing reads `.type` — so the widening bought no caller anything and only
+ * offered future readers a `string | undefined` the wire never produces.
+ *
+ * Still a superset of {@link ChartResultField} (which needs only
+ * name/label/format) — pinned, not merely asserted, in
+ * `__tests__/dataset-result-field-spec-parity.test.ts`.
  */
-export interface DatasetResultField {
-    name: string;
-    type?: string;
-    label?: string;
-    format?: string;
-    currency?: string;
-    percentScale?: PercentScale;
-}
+export type DatasetResultField = AnalyticsResult['fields'][number];
 /**
  * How a percentage column's stored number relates to its displayed percentage —
  * the server's answer to a question a `%` format string cannot express:
@@ -56,6 +69,16 @@ export type { PercentScale } from '@objectstack/spec/data';
  * percent cell renderer (`formatPercent` in `@object-ui/fields`) and the dataset
  * measure formatter ({@link formatMeasure}) so a percent renders identically as
  * a row value and as an aggregated metric — the two surfaces can never drift.
+ *
+ * ⚠️ That last sentence was briefly FALSE, and objectui#4576 is what made it
+ * true again. Sharing the SCALING was never enough on its own: between #4553
+ * and #4576 the cell renderer got the locale's percent CONVENTION from `Intl`
+ * while {@link formatMeasure} appended a literal '%', so a German session read
+ * `1.234,5 %` in a list cell and `1.234,5%` in a dashboard measure — the same
+ * number, scaled identically, rendered under two conventions. Both ends now go
+ * through the locale's own percent affix. If a third surface ever needs percent
+ * display, it takes BOTH halves from here — the scaling AND the convention —
+ * or this promise breaks again in the same place.
  */
 export declare function percentDisplayValue(value: number): number;
 /**
@@ -65,13 +88,49 @@ export declare function percentDisplayValue(value: number): number;
  * never a misleading "$". The numeral `format` hint (e.g. "0,0", "0.0%")
  * controls grouping / decimals / percent; it can't be baked into the row value
  * server-side (the same number feeds charts), so it is applied here.
+ *
+ * `locale` is the BCP-47 tag of the active display locale — in React, whatever
+ * `useDisplayLocale()` returns. It is optional and LAST so every existing call
+ * keeps compiling, and omitting it reproduces the previous output byte for
+ * byte (the old code passed a literal `undefined` to `Intl`, which is exactly
+ * what an omitted argument passes now).
+ *
+ * Before objectui#4566 there was no way to pass one: all three formatting sites
+ * here hard-coded `undefined`, which is neither of the repo's two locale
+ * channels — it is the MACHINE's locale. A German session read a KPI as
+ * `1,234.5` beside a grid cell rendering the same number as `1.234,5`, and
+ * inverted separators read as a different number, not an unstyled one.
+ *
+ * ── This routes through `formatDisplayNumber` (objectui#4576) ──
+ * It did not always. #4566 measured the option mapping across 32,760
+ * value × format × currency × percentScale × locale combinations and found it
+ * LOSSLESS — routing changes no byte of output, because the policy layer
+ * `formatDisplayNumber` adds over plain `Intl` is grouping suppression keyed on
+ * a field's declared `scale`, and a measure has no `scale` to feed it (decimals
+ * here come from a numeral format PATTERN, so grouping stays on and the two
+ * agree everywhere). What blocked it was the PACKAGE BOUNDARY: the formatter
+ * lived in `@object-ui/i18n`, which depends on `i18next`/`react-i18next` and
+ * peer-depends on React, while this package is the React-free engine (AGENTS.md
+ * §3: "No UI-lib deps. Logic only.") and a runtime dependency of React-FREE
+ * consumers — the `object-ui` VS Code extension and `@object-ui/data-objectstack`.
+ *
+ * #4576 removed the boundary rather than working around it: `formatDisplayNumber`
+ * is pure, so it moved DOWN into this package (`./number-display.ts`) and
+ * `@object-ui/i18n` re-exports it. The duplicate implementation this file used
+ * to carry is gone, and with it the drift that duplicate produced — see the
+ * percent note in the body, and {@link percentDisplayValue}'s promise, which
+ * is true again.
  */
-export declare function formatMeasure(v: unknown, format?: string, currency?: string, percentScale?: PercentScale): string;
+export declare function formatMeasure(v: unknown, format?: string, currency?: string, percentScale?: PercentScale, locale?: string): string;
 /**
  * Format a non-measure (dimension / label) value — the server already resolves
  * dimension display labels, so this only tidies numbers and nulls.
+ *
+ * `locale` follows {@link formatMeasure}: optional, last, and omitting it
+ * reproduces the previous machine-locale output byte for byte. Integers stay
+ * verbatim here for the same measured reason as there.
  */
-export declare function formatDimensionValue(v: unknown): string;
+export declare function formatDimensionValue(v: unknown, locale?: string): string;
 /**
  * Resolve a column header / measure helper pair for one result set.
  * `headerLabel` maps a dimension/measure NAME to its display label — the