@object-ui/i18n 17.6.0 → 18.0.0

package/README.md

@@ -1,15 +1,16 @@
 # @object-ui/i18n
 
-Internationalization for Object UI — 11 built-in locales, RTL support, and date/currency formatting.
+Internationalization for Object UI — 10 built-in locales, RTL support, and date/currency formatting.
 
 ## Features
 
-- 🌍 **11 Built-in Locales** - English, Chinese, Japanese, Korean, German, French, Spanish, Portuguese, Russian, Arabic, and more
+- 🌍 **10 Built-in Locales** - English, Chinese, Japanese, Korean, German, French, Spanish, Portuguese, Russian, Arabic
 - 🔄 **RTL Support** - Automatic right-to-left layout for Arabic and other RTL languages
 - 📅 **Date Formatting** - Locale-aware date, datetime, and relative time formatting
 - 💰 **Currency & Number Formatting** - Locale-aware currency and number formatting
 - 🎣 **React Hooks** - `useObjectTranslation` for translations, language switching, and direction
 - 🏗️ **I18nProvider** - Context provider for internationalized applications
+- 🪶 **Lazy catalogues** - only the active locale's catalogue is fetched; the other nine are separate chunks
 - 🔌 **Extensible** - Add custom locales and translation keys
 - 🎯 **Type-Safe** - Full TypeScript support with exported types
 
@@ -55,9 +56,15 @@ function MyComponent() {
 Wraps your application with i18n context:
 
 ```tsx
+import type { ReactNode } from 'react';
+import { I18nProvider } from '@object-ui/i18n';
+
+// Your app supplies the tree being wrapped.
+declare const App: () => ReactNode;
+
 <I18nProvider config={{ defaultLanguage: 'en', fallbackLanguage: 'en' }}>
   <App />
-</I18nProvider>
+</I18nProvider>;
 ```
 
 #### Language persistence
@@ -72,14 +79,21 @@ An explicit choice outranks browser detection — otherwise a user who picked
 on a `ja` browser would be handed `ja` back on every reload. A stored value the
 app no longer offers (not a built-in pack, not in `config.resources`) is ignored
 *and purged*, so a stale entry can never lock the UI to a locale with no
-translations.
+translations. A region-tagged choice such as `zh-CN` is served by its base
+language's built-in pack (`zh`), so it is kept, and kept as written: the
+provider's `language`, `<html lang>` and the stored value all stay `zh-CN`.
 
 ```tsx
+import type { ReactNode } from 'react';
+import { I18nProvider } from '@object-ui/i18n';
+
+declare const Preview: () => ReactNode;
+
 // Fixed-language surfaces (previews, demos, screenshot harnesses) opt out —
 // they neither restore nor write the preference.
 <I18nProvider config={{ defaultLanguage: 'en' }} persistLanguage={false}>
   <Preview />
-</I18nProvider>
+</I18nProvider>;
 ```
 
 Bringing your own `instance`? Then its bootstrap language is yours to choose —
@@ -91,9 +105,47 @@ Switching through such an instance is still persisted.
 Hook for translations and language management:
 
 ```tsx
-const { t, language, changeLanguage, direction } = useObjectTranslation();
+import { useObjectTranslation } from '@object-ui/i18n';
+
+function LanguageBar() {
+  const { t, language, changeLanguage, direction } = useObjectTranslation();
+
+  return (
+    <div dir={direction}>
+      {t('common.save')} — {language}
+      <button onClick={() => changeLanguage('zh')}>中文</button>
+    </div>
+  );
+}
 ```
 
+#### Count labels are i18next count families
+
+A label a word must agree with — `3 replies`, `Approve 3 requests?` — is one
+i18next count family: pass the number as `count` and let i18next pick the slot
+`Intl.PluralRules` selects for the language. Every pack spells out each
+category its language has (`en` `_one`/`_other`; `ru` adds `_few`/`_many`; `ar`
+has all six), plus a count-invariant base key for a call made without a count.
+
+```tsx
+import { useObjectTranslation } from '@object-ui/i18n';
+
+function ReplyCount({ replies }: { replies: readonly string[] }) {
+  const { t } = useObjectTranslation();
+
+  // "1 reply", "3 replies"; Russian «3 ответа», «5 ответов»
+  return <span>{t('detail.replyCount', { count: replies.length })}</span>;
+}
+```
+
+Pass `count` as a **number** — i18next selects a slot for nothing else — and
+never choose the key yourself (`count === 1 ? 'xOne' : 'x'`): two keys give a
+language two forms, and Russian needs three, Arabic five. A
+`createSafeTranslation` defaults table answers the same way on a provider-less
+host: it reads a family's `_one` / `_other` row for a numeric `count`, then the
+base row. `count-families-11445.test.ts` holds every `{{count}}` value in the
+ten packs to this rule.
+
 ### createI18n
 
 Factory for creating an i18n instance outside React:
@@ -105,27 +157,191 @@ const i18n = createI18n({ defaultLanguage: 'de' });
 i18n.t('common.cancel'); // "Abbrechen"
 ```
 
+### TranslateFn — typing a `t` you are handed
+
+A helper that receives `t` from its caller, rather than calling a hook itself,
+types that parameter with `TranslateFn`: i18next's `t` narrowed to
+`(key: string, options?: Record<string, unknown>) => string`. This package is
+the one authority for that type — import it rather than declaring a local
+copy:
+
+```ts
+import type { TranslateFn } from '@object-ui/i18n';
+
+export function saveLabel(t: TranslateFn): string {
+  return t('common.save');
+}
+```
+
 ### Formatting Utilities
 
 Locale-aware formatting functions:
 
+Each formatter takes the value first and an **options object** second; the
+locale is a field on that object (`DateFormatOptions`, `CurrencyFormatOptions`,
+`NumberFormatOptions`), never a positional argument. `formatRelativeTime` is the
+one exception: it takes the locale directly, and derives the unit from how far
+the date is from now.
+
 ```tsx
 import { formatDate, formatCurrency, formatNumber, formatRelativeTime } from '@object-ui/i18n';
 
-formatDate(new Date(), 'en');            // "Jan 1, 2025"
-formatCurrency(99.99, 'USD', 'en');      // "$99.99"
-formatNumber(1234567, 'de');             // "1.234.567"
-formatRelativeTime(-3, 'days', 'en');    // "3 days ago"
+formatDate(new Date(2025, 0, 1), { locale: 'en' });              // "Jan 1, 2025"
+formatCurrency(99.99, { currency: 'USD', locale: 'en' });        // "$99.99"
+formatNumber(1234567, { locale: 'de' });                         // "1.234.567"
+formatRelativeTime(Date.now() - 3 * 86_400_000, 'en');           // "3 days ago"
+```
+
+A date-only string such as `'2026-09-01'` names a calendar day: every date
+helper reads it as that day in every viewer's time zone (`formatDateTime` shows
+its midnight, and `formatRelativeTime` counts to the start of it). A string
+with a time part is an instant, read in the viewer's zone. `formatDateSpec`
+applies its `timeZone` to an instant only. These helpers do not read the
+display zone below; the field cells and measures format through
+`@object-ui/core`'s date faces, which do.
+
+### Regional defaults (`LocalizationProvider`)
+
+`LocalizationProvider` carries the workspace's resolved regional defaults to
+every renderer below it, and `useLocalization()` reads them (`{}` outside a
+provider). The console fills it from `GET /api/v1/auth/me/localization`.
+
+```tsx
+import type { ReactNode } from 'react';
+import { LocalizationProvider, useLocalization } from '@object-ui/i18n';
+
+export function Regional({ children }: { children: ReactNode }) {
+  return (
+    <LocalizationProvider value={{ currency: 'EUR', locale: 'de-DE', timezone: 'Europe/Berlin' }}>
+      {children}
+    </LocalizationProvider>
+  );
+}
+
+export function ZoneLabel() {
+  const { timezone } = useLocalization();
+  return <span>{timezone ?? 'viewer zone'}</span>;
+}
+```
+
+- `currency` (ISO 4217) is the default a currency field without its own code
+  renders in.
+- `locale` (BCP-47) outranks the UI language for number and date formatting;
+  read the effective tag with `useDisplayLocale()`.
+- `timezone` (IANA) is the zone instants render in. The provider hands it to
+  `setDisplayTimeZone` in `@object-ui/core`, so every date and datetime face
+  takes it without any renderer passing a zone, and `useLocalization().timezone`
+  reads back the zone those faces use (`undefined` for a name the runtime does
+  not know). Without one, instants render in the viewer's zone. There is one
+  display zone per page, and unmounting the provider clears it.
+
+#### The first day of the week
+
+`firstDayOfWeek(locale)` answers the first day of the week for a BCP-47 tag,
+numbered as `Date.prototype.getDay` numbers weekdays (0 is Sunday), which is
+also what react-day-picker's `weekStartsOn` takes. It reads the engine's
+`Intl.Locale` week info, and CLDR's region table where the engine has none, so
+a week grid or a "this week" bound starts where the user's locale says rather
+than on a fixed day. There is no separate week-start setting: the tag is the
+one the caller already formats its dates with, such as `useDisplayLocale()`.
+
+```tsx
+import { firstDayOfWeek, useDisplayLocale } from '@object-ui/i18n';
+
+firstDayOfWeek('en-US'); // 0, Sunday
+firstDayOfWeek('en-GB'); // 1, Monday
+firstDayOfWeek('zh-CN'); // 1, Monday
+
+function WeekHeader() {
+  const weekStart = firstDayOfWeek(useDisplayLocale());
+  // ...lay the week out from `weekStart`
+}
 ```
 
-### Built-in Locales
+A tag `Intl` refuses (`en_US`) throws the same `RangeError` that formatting a
+date with it would.
 
-Import individual locale packs:
+### Built-in locales — one is resident, nine are fetched on demand
+
+The package entry re-exports **`en` only**. It is `fallbackLng`, it is the
+source of the `TranslationKeys` type, and it is the synchronous dictionary the
+app-shell splash renders from before i18n is usable, so it has to be there
+without awaiting anything. The other nine catalogues are separate chunks your
+bundler emits once each and the browser fetches only when that locale is
+actually used — roughly 400 KB gzipped that a page load no longer pays
+(objectui#7479).
 
 ```tsx
-import { en, zh, ja, ko, de, fr, es, pt, ru, ar } from '@object-ui/i18n';
+import {
+  en,                        // resident
+  BUILT_IN_LANGUAGE_CODES,   // all ten codes, no catalogue payload
+  isBuiltInLanguage,
+  loadBuiltInLocale,         // fetch one: Promise<catalogue | null>
+  getLoadedBuiltInLocales,   // synchronous snapshot of what is resident
+} from '@object-ui/i18n';
+
+BUILT_IN_LANGUAGE_CODES;            // ['en','zh','ja','ko','de','fr','es','pt','ru','ar']
+await loadBuiltInLocale('zh');      // the zh catalogue, fetched once and memoised
+await loadBuiltInLocale('zh-CN');   // the same zh catalogue — a region tag is served by its base
+await loadBuiltInLocale('tlh');     // null — not a code this package ships
+isBuiltInLanguage('zh-CN');         // true
+isBuiltInLanguage('xx-YY');         // false — no catalogue for the tag or its base
 ```
 
+A code is looked up **exact tag first, then its base language**: `zh-CN` is
+served by the `zh` catalogue, while a catalogue keyed by a full tag would win
+over its base. `isBuiltInLanguage` and `isBuiltInLocaleLoaded` answer by the same
+rule as `loadBuiltInLocale`, and a catalogue is memoised under its own code, so
+`zh` and `zh-CN` share one fetch.
+
+`I18nProvider` does this for you: it fetches the catalogue for whatever language
+it boots into, and `changeLanguage()` awaits the new catalogue before switching,
+so a switcher needs no extra wiring.
+
+#### Resolving before the first render
+
+Without a resolve, a provider booting into `zh` paints once through the `en`
+fallback — correct strings, never a raw key — and re-renders in Chinese when the
+catalogue lands. If your app already awaits something before mounting, spend
+that await here instead and the first paint is already right:
+
+```tsx
+import { I18nProvider, preloadBootstrapLocale, resolveBootstrapLanguage } from '@object-ui/i18n';
+import { createRoot } from 'react-dom/client';
+import type { FC } from 'react';
+
+declare const App: FC;
+declare const container: HTMLElement;
+declare const loadLanguage: (lang: string) => Promise<Record<string, unknown>>;
+
+// Pass the SAME options you will pass to <I18nProvider>, or the two will
+// disagree about which language this boot is in.
+await preloadBootstrapLocale({ hasLoader: true });
+createRoot(container).render(
+  <I18nProvider loadLanguage={loadLanguage}>
+    <App />
+  </I18nProvider>,
+);
+
+resolveBootstrapLanguage({ hasLoader: true }); // 'zh' — the same answer, no fetch
+```
+
+`preloadBootstrapLocale` never rejects: a catalogue that will not download must
+not take the boot down, and the provider retries on mount.
+`apps/console/src/main.tsx` is the worked example.
+
+#### When you really do want all ten
+
+The parity suites do, and so does an app that ships every language resident. The
+door is a separate specifier, so the cost is visible at the import site:
+
+```tsx
+import { builtInLocales, zh, ru } from '@object-ui/i18n/locales';
+```
+
+⚠️ That module statically imports every catalogue. Never reach for it on a
+page-load path — that is exactly the eager payload the split removed.
+
 ### RTL Helpers
 
 ```tsx
@@ -135,6 +351,32 @@ isRTL('ar'); // true
 isRTL('en'); // false
 ```
 
+### Localized value helpers — reading and editing an `I18nLabel`
+
+Server-driven metadata types a label as a plain string **or** an inline
+per-locale map (`{ en: 'Pricing', 'zh-CN': '定价' }`). An authoring surface that
+shows one locale in one text input has to answer three separate questions, so
+there are three functions and each answers exactly one:
+
+```tsx
+import { pickLocalized, setLocalized, clearLocalized } from '@object-ui/i18n';
+
+const stored = { en: 'Pricing', 'zh-CN': '定价' };
+
+pickLocalized(stored, 'en-US');          // 'Pricing'   — which entry to DISPLAY
+setLocalized(stored, 'en-US', 'Plans');  // { en: 'Plans', 'zh-CN': '定价' }
+clearLocalized(stored, 'en-US');         // { 'zh-CN': '定价' }
+```
+
+⛔ Never write the input's string back as the whole value — that replaces the
+map and every locale the author was not looking at is gone, silently, on the
+first keystroke. `setLocalized` replaces **one** entry (adding it when the
+active locale has none) and `clearLocalized` removes **one** entry (returning
+`undefined` once nothing localized is left). Both choose that entry with the
+same limbs, and deliberately stop short of `pickLocalized`'s display-only
+fallbacks, so an author editing in `fr` while shown the `en` string can neither
+overwrite nor delete English.
+
 ## Scope — the `engine.*` carve-out (metadata-admin / Studio)
 
 Not every user-facing string in this repository resolves through these packs.

package/dist/LocalizationContext.d.ts

@@ -7,18 +7,20 @@
  */
 /**
  * LocalizationContext — the tenant's resolved REGIONAL defaults (currency,
- * locale) for the current request, surfaced to every renderer.
+ * locale, time zone) for the current request, surfaced to every renderer.
  *
  * This is the client half of ADR-0053: the framework resolves a workspace
- * `localization.currency` / `locale` onto each request's ExecutionContext and
- * exposes them at `GET /api/v1/auth/me/localization`. A fetching wrapper (in
- * app-shell) loads them once and feeds this PURE context, so low-level field /
- * measure renderers can resolve a currency code down to the org default —
- * instead of hard-coding `$`/`¥`/`USD` or degrading to a bare number — without
- * any of them depending on app-shell or making their own fetch.
+ * `localization.currency` / `locale` / `timezone` onto each request's
+ * ExecutionContext and exposes them at `GET /api/v1/auth/me/localization`. A
+ * fetching wrapper (in app-shell) loads them once and feeds this PURE context,
+ * so low-level field / measure renderers can resolve a currency code down to
+ * the org default — instead of hard-coding `$`/`¥`/`USD` or degrading to a
+ * bare number — without any of them depending on app-shell or making their own
+ * fetch.
  *
  * Undefined values mean "no tenant default known" → consumers render a plain
- * number (the existing safe behavior).
+ * number (the existing safe behavior), and instants render in the viewer's
+ * own zone.
  */
 import * as React from 'react';
 export interface LocalizationValue {
@@ -26,8 +28,29 @@ export interface LocalizationValue {
     currency?: string;
     /** Tenant/display locale (BCP-47) for Intl formatting, or undefined. */
     locale?: string;
+    /**
+     * The zone instants render in (an IANA name), or undefined for the viewer's
+     * own (objectui#11693). The provider hands it to the central date faces in
+     * `@object-ui/core`; read back from {@link useLocalization}, it is the zone
+     * those faces render in, so a name the runtime does not know reads back
+     * `undefined`.
+     */
+    timezone?: string;
 }
-/** Pure provider — the fetching/loading concern lives in the app shell. */
+/**
+ * Pure provider — the fetching/loading concern lives in the app shell.
+ *
+ * It is also the ONE place the display zone enters the date faces
+ * (objectui#11693): `value.timezone` is handed to `setDisplayTimeZone` in
+ * `@object-ui/core`, which every date and datetime face reads, so no renderer
+ * threads a zone of its own. The hand-off runs in a layout effect, and the
+ * zone the context carries is read back from core through
+ * `useSyncExternalStore`, so the context changes only AFTER the faces have the
+ * new zone: every consumer then re-renders in it, before the browser paints.
+ *
+ * The display zone is one per page, as the date faces are: a second provider
+ * with a different zone would race this one for it, and unmounting clears it.
+ */
 export declare function LocalizationProvider({ value, children, }: {
     value: LocalizationValue;
     children: React.ReactNode;

package/dist/LocalizationContext.js

@@ -8,25 +8,47 @@ import { jsx as _jsx } from "react/jsx-runtime";
  */
 /**
  * LocalizationContext — the tenant's resolved REGIONAL defaults (currency,
- * locale) for the current request, surfaced to every renderer.
+ * locale, time zone) for the current request, surfaced to every renderer.
  *
  * This is the client half of ADR-0053: the framework resolves a workspace
- * `localization.currency` / `locale` onto each request's ExecutionContext and
- * exposes them at `GET /api/v1/auth/me/localization`. A fetching wrapper (in
- * app-shell) loads them once and feeds this PURE context, so low-level field /
- * measure renderers can resolve a currency code down to the org default —
- * instead of hard-coding `$`/`¥`/`USD` or degrading to a bare number — without
- * any of them depending on app-shell or making their own fetch.
+ * `localization.currency` / `locale` / `timezone` onto each request's
+ * ExecutionContext and exposes them at `GET /api/v1/auth/me/localization`. A
+ * fetching wrapper (in app-shell) loads them once and feeds this PURE context,
+ * so low-level field / measure renderers can resolve a currency code down to
+ * the org default — instead of hard-coding `$`/`¥`/`USD` or degrading to a
+ * bare number — without any of them depending on app-shell or making their own
+ * fetch.
  *
  * Undefined values mean "no tenant default known" → consumers render a plain
- * number (the existing safe behavior).
+ * number (the existing safe behavior), and instants render in the viewer's
+ * own zone.
  */
 import * as React from 'react';
+import { getDisplayTimeZone, setDisplayTimeZone, subscribeDisplayTimeZone } from '@object-ui/core';
 const LocalizationCtx = React.createContext({});
-/** Pure provider — the fetching/loading concern lives in the app shell. */
+/**
+ * Pure provider — the fetching/loading concern lives in the app shell.
+ *
+ * It is also the ONE place the display zone enters the date faces
+ * (objectui#11693): `value.timezone` is handed to `setDisplayTimeZone` in
+ * `@object-ui/core`, which every date and datetime face reads, so no renderer
+ * threads a zone of its own. The hand-off runs in a layout effect, and the
+ * zone the context carries is read back from core through
+ * `useSyncExternalStore`, so the context changes only AFTER the faces have the
+ * new zone: every consumer then re-renders in it, before the browser paints.
+ *
+ * The display zone is one per page, as the date faces are: a second provider
+ * with a different zone would race this one for it, and unmounting clears it.
+ */
 export function LocalizationProvider({ value, children, }) {
+    const { timezone } = value;
+    React.useLayoutEffect(() => {
+        setDisplayTimeZone(timezone);
+        return () => setDisplayTimeZone(undefined);
+    }, [timezone]);
+    const appliedZone = React.useSyncExternalStore(subscribeDisplayTimeZone, getDisplayTimeZone, getDisplayTimeZone);
     // Stable identity unless the resolved values actually change.
-    const memo = React.useMemo(() => ({ currency: value.currency, locale: value.locale }), [value.currency, value.locale]);
+    const memo = React.useMemo(() => ({ currency: value.currency, locale: value.locale, timezone: appliedZone }), [value.currency, value.locale, appliedZone]);
     return _jsx(LocalizationCtx.Provider, { value: memo, children: children });
 }
 /**

package/dist/builtinAggregateLabels.d.ts

@@ -0,0 +1,40 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * objectui#7258 — the locale labels for the analytics service's BUILT-IN
+ * default measures, keyed by the wire discriminator a result field carries as
+ * `builtinAggregate` (producer half: objectstack#14492).
+ *
+ * `@object-ui/core`'s `buildChartSeries` cannot read the locale bundle (that
+ * package is React-free and i18n-free by design), so this is the seam: the
+ * renderer that holds the provider resolves the six strings ONCE through its
+ * `useSafeTranslate()` and hands the map to core as
+ * `ChartSeriesOptions.builtinAggregateLabels` — the same division of labour
+ * `chart.nullCategory` already makes for the null bucket's label.
+ *
+ * The keys are the `report.aggregate.*` family the matrix report and the
+ * dashboard's aggregate charts already read, not a second namespace: the
+ * vocabulary (Count / Sum / Average / …) is the same on every surface, so ten
+ * packs already carry it and a new key would only add drift surface. The only
+ * mapping done here is spelling — the wire enum says `count_distinct`, the
+ * bundle key says `countDistinct`.
+ *
+ * The English fallbacks are byte-equal to the `en` pack's values, so a
+ * provider-less host renders exactly what an `en` session renders (pinned in
+ * `__tests__/builtinAggregateLabels-locale-parity-7258.test.ts`).
+ */
+import type { BuiltinAggregate } from '@object-ui/core';
+/** The per-call translate shape `useSafeTranslate()` returns: first real translation, else the English fallback. */
+export type SafeTranslate = (key: string, fallback: string) => string;
+/**
+ * Resolve the display label of every built-in aggregate through the locale
+ * bundle. Typed as the FULL record on purpose: a member added to core's
+ * `BUILTIN_AGGREGATES` without a line here is a compile error, not a legend
+ * that silently falls back to the server's English.
+ */
+export declare function builtinAggregateLabels(tt: SafeTranslate): Record<BuiltinAggregate, string>;

package/dist/builtinAggregateLabels.js

@@ -0,0 +1,23 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Resolve the display label of every built-in aggregate through the locale
+ * bundle. Typed as the FULL record on purpose: a member added to core's
+ * `BUILTIN_AGGREGATES` without a line here is a compile error, not a legend
+ * that silently falls back to the server's English.
+ */
+export function builtinAggregateLabels(tt) {
+    return {
+        count: tt('report.aggregate.count', 'Count'),
+        count_distinct: tt('report.aggregate.countDistinct', 'Distinct Count'),
+        sum: tt('report.aggregate.sum', 'Sum'),
+        avg: tt('report.aggregate.avg', 'Average'),
+        min: tt('report.aggregate.min', 'Min'),
+        max: tt('report.aggregate.max', 'Max'),
+    };
+}

package/dist/currency.d.ts

@@ -7,12 +7,35 @@
  */
 /**
  * Resolve the display currency code for a currency-typed field, in precedence
- * order: the field's explicit `currency` -> its `currencyConfig.defaultCurrency`
- * (fixed mode) -> a legacy top-level `defaultCurrency` -> the tenant default
- * (`localization.currency`, ADR-0053, surfaced via {@link useLocalization}).
+ * order:
+ *
+ *  1. the field's explicit `currency` — a per-node display code. The spec
+ *     declares it on presentation surfaces (the metric widget's `currency`, a
+ *     dataset measure's `currency`) and looser grid/column configs carry it;
+ *     `FieldSchema` itself refuses it as a field key;
+ *  2. `currencyConfig.defaultCurrency`, ONLY when `currencyConfig.currencyMode`
+ *     is `'fixed'` — the spec's one fixed-currency declaration;
+ *  3. a legacy top-level `defaultCurrency` — a pre-spec spelling that
+ *     `FieldSchema` refuses as an unrecognized key, kept in place so configs
+ *     written against it still read their code;
+ *  4. the tenant default (`localization.currency`, ADR-0053, surfaced via
+ *     {@link useLocalization}).
+ *
  * Returns `undefined` when none is known, so the renderer shows a plain number
  * rather than guessing a symbol.
  *
+ * `currencyMode: 'dynamic'` — and a `currencyConfig` with no `currencyMode` at
+ * all, which `@objectstack/spec` defaults to `'dynamic'` — skips step 2
+ * (objectui#10422). The spec describes that mode as "user selectable", and its
+ * `FieldSchema` guidance says a field without a fixed currency "uses the tenant
+ * default at runtime". No value carries a user-selected code today (a currency
+ * value is a bare number), so a dynamic field reads the tenant default, never
+ * its `defaultCurrency`. That matters beyond authored dynamic configs: the
+ * spec parses an EMPTY `currencyConfig` to
+ * `{ currencyMode: 'dynamic', defaultCurrency: 'CNY' }`, which must not render
+ * as yuan. If a value ever carries its own selected code, that code is the one
+ * to win, ahead of the tenant default.
+ *
  * This is the single resolution every field / measure / cell renderer shares -
  * ending the per-renderer drift where some read only `currency`, others only
  * `defaultCurrency`, and others `currencyConfig`. It lives in `@object-ui/i18n`
@@ -23,6 +46,7 @@ export declare function resolveFieldCurrency(field: {
     currency?: string;
     defaultCurrency?: string;
     currencyConfig?: {
+        currencyMode?: 'dynamic' | 'fixed';
         defaultCurrency?: string;
     };
 } | null | undefined, tenantDefault?: string): string | undefined;

package/dist/currency.js

@@ -7,12 +7,35 @@
  */
 /**
  * Resolve the display currency code for a currency-typed field, in precedence
- * order: the field's explicit `currency` -> its `currencyConfig.defaultCurrency`
- * (fixed mode) -> a legacy top-level `defaultCurrency` -> the tenant default
- * (`localization.currency`, ADR-0053, surfaced via {@link useLocalization}).
+ * order:
+ *
+ *  1. the field's explicit `currency` — a per-node display code. The spec
+ *     declares it on presentation surfaces (the metric widget's `currency`, a
+ *     dataset measure's `currency`) and looser grid/column configs carry it;
+ *     `FieldSchema` itself refuses it as a field key;
+ *  2. `currencyConfig.defaultCurrency`, ONLY when `currencyConfig.currencyMode`
+ *     is `'fixed'` — the spec's one fixed-currency declaration;
+ *  3. a legacy top-level `defaultCurrency` — a pre-spec spelling that
+ *     `FieldSchema` refuses as an unrecognized key, kept in place so configs
+ *     written against it still read their code;
+ *  4. the tenant default (`localization.currency`, ADR-0053, surfaced via
+ *     {@link useLocalization}).
+ *
  * Returns `undefined` when none is known, so the renderer shows a plain number
  * rather than guessing a symbol.
  *
+ * `currencyMode: 'dynamic'` — and a `currencyConfig` with no `currencyMode` at
+ * all, which `@objectstack/spec` defaults to `'dynamic'` — skips step 2
+ * (objectui#10422). The spec describes that mode as "user selectable", and its
+ * `FieldSchema` guidance says a field without a fixed currency "uses the tenant
+ * default at runtime". No value carries a user-selected code today (a currency
+ * value is a bare number), so a dynamic field reads the tenant default, never
+ * its `defaultCurrency`. That matters beyond authored dynamic configs: the
+ * spec parses an EMPTY `currencyConfig` to
+ * `{ currencyMode: 'dynamic', defaultCurrency: 'CNY' }`, which must not render
+ * as yuan. If a value ever carries its own selected code, that code is the one
+ * to win, ahead of the tenant default.
+ *
  * This is the single resolution every field / measure / cell renderer shares -
  * ending the per-renderer drift where some read only `currency`, others only
  * `defaultCurrency`, and others `currencyConfig`. It lives in `@object-ui/i18n`
@@ -20,8 +43,9 @@
  * concern; `@object-ui/fields` re-exports it for backward compatibility.
  */
 export function resolveFieldCurrency(field, tenantDefault) {
+    const config = field?.currencyConfig;
     return (field?.currency ||
-        field?.currencyConfig?.defaultCurrency ||
+        (config?.currencyMode === 'fixed' ? config.defaultCurrency : undefined) ||
         field?.defaultCurrency ||
         tenantDefault ||
         undefined);