@@ -24,8 +24,9 @@ type of `useColumnSummary` gains an optional `currencyConfig` member, typed as
 the spec's own `CurrencyConfig`. The footer reads `currencyConfig` from the
 field only: `ListColumnSchema` declares no such column key.
 
-**Behaviour change.** On those paths, a field that declares `currencyConfig`
-now shows `currencyConfig.defaultCurrency` in the cell and the footer where it
-used to show the tenant currency. That includes a field in `dynamic` mode,
-because `resolveFieldCurrency` does not read `currencyMode`. The grid's
-auto-generated columns already showed that currency.
+**Behaviour change.** On those paths, a field whose `currencyConfig` is in
+`fixed` mode now shows `currencyConfig.defaultCurrency` in the cell and the
+footer where it used to show the tenant currency. A field in `dynamic` mode
+still shows the tenant currency, because `resolveFieldCurrency` reads
+`currencyConfig.defaultCurrency` only in `fixed` mode (objectui#10422). The
+grid's auto-generated columns already showed a fixed field's currency.
@@ -0,0 +1,33 @@
+---
+'@object-ui/i18n': minor
+---
+
+A currency field in `dynamic` mode shows the tenant's currency, not its
+`currencyConfig.defaultCurrency` (objectui#10422).
+
+`@objectstack/spec` declares two currency modes: `fixed` (a single currency) and
+`dynamic` (user selectable). Its field guidance says a field without a fixed
+currency uses the tenant default at runtime. `resolveFieldCurrency` read
+`currencyConfig.defaultCurrency` in either mode, so in a USD tenant a field
+declaring `currencyConfig: { currencyMode: 'dynamic', defaultCurrency: 'EUR' }`
+showed `€3,456` where it should show `$3,456`. An empty `currencyConfig`, which
+the spec parses to a dynamic config with `defaultCurrency: 'CNY'`, showed
+`CN¥`.
+
+The resolver now reads `currencyConfig.defaultCurrency` only when
+`currencyMode` is `'fixed'`. Its precedence is: the explicit `currency`, then a
+fixed `currencyConfig.defaultCurrency`, then the legacy top-level
+`defaultCurrency`, then the tenant default. With none of these, it returns
+`undefined` and the amount shows as a plain number.
+
+**Behaviour change.** Every face that resolves a currency through
+`resolveFieldCurrency` changes together: the list cell, the field widget, the
+metric tile, the detail summary chip, the gantt tooltip, and the grid's
+configured cells and summary footer. On each of them, a field in `dynamic` mode
+now shows the tenant currency. So does a `currencyConfig` that names no
+`currencyMode`, because the spec's default mode is `dynamic`. To keep a field on
+one currency, declare `currencyMode: 'fixed'`. A fixed field renders as before.
+
+The parameter type of `resolveFieldCurrency` gains an optional
+`currencyConfig.currencyMode` member (`'dynamic' | 'fixed'`), which is the
+spec's enum.
@@ -86,10 +86,12 @@ describe('CurrencyField — fraction digits derive from the currency (objectui#4
     expect(normalizeNbsp(container.textContent)).toBe('¥1,235');
   });
 
-  it('`currencyConfig.defaultCurrency` reaches it as well', () => {
+  it('a fixed `currencyConfig.defaultCurrency` reaches it as well', () => {
+    // `fixed` mode, the spec's one fixed-currency declaration: a dynamic or
+    // mode-less config reads the tenant default instead (objectui#10422).
     const { container } = renderField(
       1.5,
-      { currencyConfig: { defaultCurrency: 'KWD' } },
+      { currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'KWD' } },
       { readonly: true },
     );
     expect(normalizeNbsp(container.textContent)).toBe('KWD 1.500');
 
@@ -0,0 +1,99 @@
+/**
+ * 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#10422, the two `@object-ui/fields` faces: the list cell
+ * (`CurrencyCellRenderer`) and the field widget (`CurrencyField`).
+ *
+ * Both hand the WHOLE field def to `resolveFieldCurrency`, whose truth table is
+ * pinned in `@object-ui/i18n` beside it. These rows hold each face to it:
+ * under a USD tenant, a `dynamic` field, and an empty config as the spec parses
+ * it, read exactly what a field with no `currencyConfig` reads (the tenant's
+ * `$`), while a `fixed` field keeps its own code.
+ *
+ * ── Directions on the base tree (predicted before the first run) ─────────
+ *   dynamic reads the tenant currency         RED   (read `€`)
+ *   parsed-empty reads the tenant currency    RED   (read `CN¥`)
+ *   control: fixed JPY reads `¥`              GREEN (untouched)
+ */
+
+import { describe, it, expect, afterEach } from 'vitest';
+import React from 'react';
+import { render, cleanup } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { CurrencyConfigSchema } from '@objectstack/spec/data';
+import { LocalizationProvider } from '@object-ui/i18n';
+import { CurrencyCellRenderer } from '../index';
+import { CurrencyField } from '../widgets/CurrencyField';
+
+afterEach(cleanup);
+
+/** A USD tenant: a field that names no currency of its own reads `$`. */
+const TENANT = { locale: 'en-US', currency: 'USD' };
+
+const FIELDS: Record<string, Record<string, unknown>> = {
+  fixed: { type: 'currency', currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'JPY' } },
+  dynamic: { type: 'currency', currencyConfig: { currencyMode: 'dynamic', defaultCurrency: 'EUR' } },
+  // What the spec makes of an authored `currencyConfig: {}`: a dynamic CNY config.
+  parsedEmpty: { type: 'currency', currencyConfig: CurrencyConfigSchema.parse({}) },
+  // The reference: no `currencyConfig`, so the tenant currency is right.
+  plain: { type: 'currency' },
+};
+
+const VALUE = 3456;
+
+/** ICU puts U+00A0 between a currency CODE and the amount; keep rows readable. */
+const text = (s: string | null) => (s ?? '').replace(/\u00a0/g, ' ');
+
+const FACES: Array<[string, (field: Record<string, unknown>, value: number) => string]> = [
+  [
+    'CurrencyCellRenderer (the list cell)',
+    (field, value) => {
+      const { container, unmount } = render(
+        <LocalizationProvider value={TENANT}>
+          <CurrencyCellRenderer value={value} field={{ name: 'amount', ...field } as any} />
+        </LocalizationProvider>,
+      );
+      const out = text(container.textContent);
+      unmount();
+      return out;
+    },
+  ],
+  [
+    'CurrencyField (the field widget, read-only)',
+    (field, value) => {
+      const { container, unmount } = render(
+        <LocalizationProvider value={TENANT}>
+          <CurrencyField value={value} onChange={() => {}} field={{ name: 'amount', ...field } as any} readonly />
+        </LocalizationProvider>,
+      );
+      const out = text(container.textContent);
+      unmount();
+      return out;
+    },
+  ],
+];
+
+describe.each(FACES)('%s agrees with the resolver on currencyMode (objectui#10422)', (_face, show) => {
+  it('dynamic: reads what a field with no currencyConfig reads, the tenant $', () => {
+    const reference = show(FIELDS.plain, VALUE);
+    expect(reference).toMatch(/^\$3,456/);
+    expect(show(FIELDS.dynamic, VALUE)).toBe(reference);
+  });
+
+  it('parsed-empty: an empty config, as the spec parses it, reads the tenant $, never CN¥', () => {
+    const reference = show(FIELDS.plain, VALUE);
+    const shown = show(FIELDS.parsedEmpty, VALUE);
+    expect(shown).not.toContain('CN¥');
+    expect(shown).toBe(reference);
+  });
+
+  it('control: a fixed JPY field keeps its own ¥', () => {
+    expect(show(FIELDS.fixed, 1234)).toBe('¥1,234');
+  });
+});
@@ -3,16 +3,21 @@ import { resolveFieldCurrency } from '../index';
 
 describe('resolveFieldCurrency', () => {
   it('prefers the field explicit currency over everything', () => {
-    expect(resolveFieldCurrency({ currency: 'JPY', currencyConfig: { defaultCurrency: 'EUR' } }, 'USD')).toBe('JPY');
+    expect(resolveFieldCurrency({ currency: 'JPY', currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'EUR' } }, 'USD')).toBe('JPY');
   });
-  it('falls back to currencyConfig.defaultCurrency, then legacy defaultCurrency', () => {
-    expect(resolveFieldCurrency({ currencyConfig: { defaultCurrency: 'EUR' } }, 'USD')).toBe('EUR');
+  it('falls back to a fixed currencyConfig.defaultCurrency, then legacy defaultCurrency', () => {
+    expect(resolveFieldCurrency({ currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'EUR' } }, 'USD')).toBe('EUR');
     expect(resolveFieldCurrency({ defaultCurrency: 'GBP' } as any, 'USD')).toBe('GBP');
   });
   it('falls back to the tenant default when the field omits its own', () => {
     expect(resolveFieldCurrency({}, 'CNY')).toBe('CNY');
     expect(resolveFieldCurrency(null, 'CNY')).toBe('CNY');
   });
+  it('a dynamic currencyConfig reads the tenant default, not its defaultCurrency (objectui#10422)', () => {
+    // The re-export is the same function: the full truth table is pinned in
+    // `@object-ui/i18n`, beside the resolver.
+    expect(resolveFieldCurrency({ currencyConfig: { currencyMode: 'dynamic', defaultCurrency: 'EUR' } }, 'USD')).toBe('USD');
+  });
   it('returns undefined when nothing is known (→ renderer shows a plain number)', () => {
     expect(resolveFieldCurrency({})).toBeUndefined();
     expect(resolveFieldCurrency(undefined, undefined)).toBeUndefined();
 
@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest';
+import { CurrencyConfigSchema } from '@objectstack/spec/data';
 import { resolveFieldCurrency } from '../index';
 
 /**
@@ -9,12 +10,12 @@ import { resolveFieldCurrency } from '../index';
 describe('resolveFieldCurrency (i18n canonical home)', () => {
   it('prefers the field explicit currency over everything', () => {
     expect(
-      resolveFieldCurrency({ currency: 'JPY', currencyConfig: { defaultCurrency: 'EUR' } }, 'USD'),
+      resolveFieldCurrency({ currency: 'JPY', currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'EUR' } }, 'USD'),
     ).toBe('JPY');
   });
 
-  it('falls back to currencyConfig.defaultCurrency, then legacy defaultCurrency', () => {
-    expect(resolveFieldCurrency({ currencyConfig: { defaultCurrency: 'EUR' } }, 'USD')).toBe('EUR');
+  it('falls back to a fixed currencyConfig.defaultCurrency, then legacy defaultCurrency', () => {
+    expect(resolveFieldCurrency({ currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'EUR' } }, 'USD')).toBe('EUR');
     expect(resolveFieldCurrency({ defaultCurrency: 'GBP' } as any, 'USD')).toBe('GBP');
   });
 
@@ -29,3 +30,113 @@ describe('resolveFieldCurrency (i18n canonical home)', () => {
     expect(resolveFieldCurrency(undefined, undefined)).toBeUndefined();
   });
 });
+
+/**
+ * objectui#10422: `currencyConfig.currencyMode` decides whether
+ * `currencyConfig.defaultCurrency` is the field's currency.
+ *
+ * `@objectstack/spec` names two modes: `fixed` (single currency) and `dynamic`
+ * (user selectable), and its `FieldSchema` guidance says a field without a
+ * fixed currency "uses the tenant default at runtime". The resolver used to
+ * read `defaultCurrency` in either mode, so a dynamic EUR field read `€` in a
+ * USD tenant, and an EMPTY config, which the spec parses to a dynamic CNY
+ * config, read `CN¥`.
+ *
+ * Every row runs under a USD tenant, so a row that reads anything but `USD`
+ * took its code from the field.
+ *
+ * ── Directions on the base tree (predicted before the first run, then observed) ──
+ *   fixed                                   GREEN (the base read it anyway)
+ *   dynamic                                 RED   (read EUR)
+ *   parsed-empty, both spellings            RED   (read CNY)
+ *   no mode (the spec defaults it dynamic)  RED   (read EUR)
+ *   dynamic with no tenant default          RED   (read EUR, not undefined)
+ *   explicit `currency`, none               GREEN (untouched legs)
+ *   legacy `defaultCurrency`                RED
+ * Predicted: the legacy row GREEN. Observed: RED. Its second assertion pairs
+ * the legacy key with a DYNAMIC config, whose EUR the base tree read first.
+ */
+describe('currencyMode decides whether currencyConfig.defaultCurrency is read (objectui#10422)', () => {
+  const TENANT = 'USD';
+
+  it('fixed: the config code is the field currency', () => {
+    expect(resolveFieldCurrency({ currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'JPY' } }, TENANT)).toBe('JPY');
+  });
+
+  it('dynamic: the tenant default, not the config code', () => {
+    expect(resolveFieldCurrency({ currencyConfig: { currencyMode: 'dynamic', defaultCurrency: 'EUR' } }, TENANT)).toBe(
+      'USD',
+    );
+  });
+
+  it('parsed-empty: an empty config, as the spec parses it, reads the tenant default, never CNY', () => {
+    // Parsed through the installed spec rather than restated, so this row keeps
+    // meaning "whatever the spec materializes for an empty config".
+    const parsed = CurrencyConfigSchema.parse({});
+    expect(parsed.currencyMode, 'the spec defaults an empty config to dynamic').toBe('dynamic');
+    expect(parsed.defaultCurrency, 'the spec fills in a code of its own').not.toBe(TENANT);
+    expect(resolveFieldCurrency({ currencyConfig: parsed }, TENANT)).toBe('USD');
+  });
+
+  it('parsed-empty: the materialized shape as a renderer receives it', () => {
+    expect(
+      resolveFieldCurrency({ currencyConfig: { currencyMode: 'dynamic', defaultCurrency: 'CNY' } }, TENANT),
+    ).toBe('USD');
+  });
+
+  it('no mode: an authored config without currencyMode reads as dynamic, the spec default', () => {
+    const authored = { defaultCurrency: 'EUR' };
+    expect(CurrencyConfigSchema.parse(authored).currencyMode, 'the spec defaults an absent mode to dynamic').toBe(
+      'dynamic',
+    );
+    expect(resolveFieldCurrency({ currencyConfig: authored }, TENANT)).toBe('USD');
+  });
+
+  it('dynamic with no tenant default: undefined (a plain number), never the config code', () => {
+    expect(resolveFieldCurrency({ currencyConfig: { currencyMode: 'dynamic', defaultCurrency: 'EUR' } })).toBeUndefined();
+  });
+
+  it('fixed with no code: falls through to the tenant default', () => {
+    expect(resolveFieldCurrency({ currencyConfig: { currencyMode: 'fixed' } }, TENANT)).toBe('USD');
+  });
+
+  it('explicit `currency`: wins over a fixed config and over a dynamic one', () => {
+    expect(
+      resolveFieldCurrency({ currency: 'KWD', currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'JPY' } }, TENANT),
+    ).toBe('KWD');
+    expect(
+      resolveFieldCurrency({ currency: 'KWD', currencyConfig: { currencyMode: 'dynamic', defaultCurrency: 'EUR' } }, TENANT),
+    ).toBe('KWD');
+  });
+
+  it('legacy top-level `defaultCurrency`: after a fixed config, ahead of the tenant default', () => {
+    expect(
+      resolveFieldCurrency(
+        { defaultCurrency: 'GBP', currencyConfig: { currencyMode: 'fixed', defaultCurrency: 'JPY' } },
+        TENANT,
+      ),
+    ).toBe('JPY');
+    expect(
+      resolveFieldCurrency(
+        { defaultCurrency: 'GBP', currencyConfig: { currencyMode: 'dynamic', defaultCurrency: 'EUR' } },
+        TENANT,
+      ),
+    ).toBe('GBP');
+  });
+
+  it('none: the tenant default, or undefined when there is none', () => {
+    expect(resolveFieldCurrency({}, TENANT)).toBe('USD');
+    expect(resolveFieldCurrency({})).toBeUndefined();
+  });
+
+  it('control: the objectstack showcase configs (all fixed USD) still read USD under a JPY tenant', () => {
+    // The three `currencyConfig` authors in objectstack's showcase example, as
+    // written there. Under a JPY tenant, reading USD proves the fixed leg.
+    for (const currencyConfig of [
+      { precision: 2, currencyMode: 'fixed', defaultCurrency: 'USD' },
+      { currencyMode: 'fixed', defaultCurrency: 'USD', precision: 2 },
+    ] as const) {
+      expect(resolveFieldCurrency({ currencyConfig }, 'JPY')).toBe('USD');
+    }
+  });
+});
@@ -8,12 +8,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`
@@ -22,14 +45,19 @@
  */
 export function resolveFieldCurrency(
   field:
-    | { currency?: string; defaultCurrency?: string; currencyConfig?: { defaultCurrency?: string } }
+    | {
+        currency?: string;
+        defaultCurrency?: string;
+        currencyConfig?: { currencyMode?: 'dynamic' | 'fixed'; defaultCurrency?: string };
+      }
     | null
     | undefined,
   tenantDefault?: string,
 ): string | undefined {
+  const config = field?.currencyConfig;
   return (
     field?.currency ||
-    field?.currencyConfig?.defaultCurrency ||
+    (config?.currencyMode === 'fixed' ? config.defaultCurrency : undefined) ||
     field?.defaultCurrency ||
     tenantDefault ||
     undefined