@object-ui/fields 17.2.0 → 17.5.0

package/src/__tests__/widget-dom-leak-e2e.test.tsx

@@ -0,0 +1,357 @@
+/**
+ * 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.
+ */
+
+/**
+ * GATE: no field widget may leak a non-DOM prop onto a DOM element
+ * (objectui#3291).
+ *
+ * Every registered field widget is rendered through BOTH hosts, and every
+ * attribute of every element it produced is checked against what HTML actually
+ * defines. An attribute nobody can explain is a leak.
+ *
+ * ## What this catches that a unit test cannot
+ *
+ * The leak was never in one widget. It was structural: a widget spread
+ * `{...props}` onto its control, and the hosts hand a widget more than the DOM
+ * can take. Measured on `origin/main`, a real form, a real widget:
+ *
+ * ```
+ * <input placeholder="PH-f" zzcanary="CANARY-STR" zzcanaryobj="[object Object]"
+ *        zzcanarynum="42" id="…" type="text" value="" name="f">
+ * ```
+ *
+ * `zzcanaryobj="[object Object]"` is an ordinary key an author wrote on the
+ * field config. That is why the fix is a WHITELIST (`toDomProps`) and why this
+ * test plants canaries rather than checking a list of known-bad names: a
+ * blacklist of today's renderer props would pass all three canaries above.
+ *
+ * ## Four things that silently defeat a test like this
+ *
+ * 1. **React warnings prove nothing.** React 19 passes an all-lowercase
+ *    unknown attribute through in COMPLETE silence. In the audit sweep the
+ *    only warning came from a camelCase canary — which was written to the DOM
+ *    anyway. So this walks real DOM attributes and never listens for console
+ *    output.
+ * 2. **Both hosts, or the result is a false pass.** The form renderer strips a
+ *    known set before forwarding; `SchemaRenderer` spreads the whole authored
+ *    node with NO strip layer, so it leaks strictly more (`label` is only
+ *    visible there). On that path the widget's own spread is the only defence.
+ * 3. **An error variant that produces no error tests nothing.** `required` +
+ *    a `false` boolean does NOT fail here — this repo made `required` a
+ *    presence check, so `false` is a value (cloud#972). The audit's first pass
+ *    under-reported the `error` leak by one widget for exactly this reason.
+ *    Every error variant therefore ASSERTS the message rendered before it
+ *    scans; a variant that silently produces no error fails the test.
+ * 4. **This repo runs happy-dom, not jsdom** (`vitest.config.mts`), whose IDL
+ *    coverage has real gaps — `select[size]`, `option[label]`, `textarea[wrap]`
+ *    and `col[span]` are all standard HTML that happy-dom does not reflect.
+ *    See `@object-ui/test-support`'s `dom-leak-judge` for how the judge is
+ *    built, and its `HAPPY_DOM_IDL_GAPS` for each measured exception and its
+ *    reason. Every one of those four was found BY a calibration fixture, not
+ *    by guesswork.
+ *
+ * ## The judge proves itself — next to the judge, not here
+ *
+ * `isKnownAttribute` / `findLeaks` / `leakReport` are imported from
+ * `@object-ui/test-support`, which is where they now live for BOTH DOM-leak
+ * gates (objectui#4434). They used to be defined in this file and copied into
+ * `packages/app-shell/src/__tests__/widget-dom-leak-sweep.test.tsx`, and the
+ * two copies had already drifted.
+ *
+ * The calibration fixtures moved with them: standard markup that must yield
+ * ZERO findings, and markup with planted fake attributes that must ALL be
+ * found, now unioned from both gates' fixtures and run once in
+ * `packages/test-support/src/__tests__/dom-leak-judge.test.tsx`. When a
+ * happy-dom upgrade changes IDL coverage, that fails loudly instead of this
+ * sweep going quietly blind — and it now fails in ONE place instead of needing
+ * to be discovered twice.
+ *
+ * ## Deliberate coverage boundary
+ *
+ * Popovers are NOT opened. Radix needs pointer-capture APIs happy-dom does not
+ * implement. Every widget's props spread lands on its inline control (the
+ * trigger for a picker), which always renders — so the spread site IS covered,
+ * but content that exists only inside an open dropdown is NOT scanned by this
+ * test.
+ *
+ * Widgets are registered from STATIC imports wrapped in `withFieldCarrier`,
+ * never via `registerAllFields()`, which wraps every loader in `React.lazy` —
+ * an unbounded module load inside a bounded `waitFor` is this repo's known
+ * flake generator (AGENTS.md 测试纪律 / objectui#3010).
+ */
+
+import type { ComponentType } from 'react';
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor, cleanup } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { ComponentRegistry } from '@object-ui/core';
+// Module scope: pulls in the form renderer's registration side effect.
+import '@object-ui/components';
+import { SchemaRenderer } from '@object-ui/react';
+// The attribute judge, shared with `packages/app-shell`'s sweep gate
+// (objectui#4434). It used to be defined in this file and copied into that one;
+// its calibration fixtures now live next to it and prove it for both gates.
+// `@object-ui/test-support` is private and never published — see its README.
+import { findLeaks, leakReport } from '@object-ui/test-support';
+
+import { withFieldCarrier } from '../withFieldCarrier';
+import { FORM_FIELD_TYPES } from '../index';
+
+import { TextField } from '../widgets/TextField';
+import { TextAreaField } from '../widgets/TextAreaField';
+import { NumberField } from '../widgets/NumberField';
+import { BooleanField } from '../widgets/BooleanField';
+import { SelectField } from '../widgets/SelectField';
+import { DateField } from '../widgets/DateField';
+import { DateTimeField } from '../widgets/DateTimeField';
+import { TimeField } from '../widgets/TimeField';
+import { EmailField } from '../widgets/EmailField';
+import { PhoneField } from '../widgets/PhoneField';
+import { UrlField } from '../widgets/UrlField';
+import { MultiSelectField } from '../widgets/MultiSelectField';
+import { RadioField } from '../widgets/RadioField';
+import { CheckboxesField } from '../widgets/CheckboxesField';
+import { TagsField } from '../widgets/TagsField';
+import { CurrencyField } from '../widgets/CurrencyField';
+import { PercentField } from '../widgets/PercentField';
+import { PasswordField } from '../widgets/PasswordField';
+import { RichTextField } from '../widgets/RichTextField';
+import { LookupField } from '../widgets/LookupField';
+import { FileField } from '../widgets/FileField';
+import { ImageField } from '../widgets/ImageField';
+import { LocationField } from '../widgets/LocationField';
+import { FormulaField } from '../widgets/FormulaField';
+import { SummaryField } from '../widgets/SummaryField';
+import { AutoNumberField } from '../widgets/AutoNumberField';
+import { UserField } from '../widgets/UserField';
+import { ObjectField } from '../widgets/ObjectField';
+import { VectorField } from '../widgets/VectorField';
+import { GridField } from '../widgets/GridField';
+import { ColorField } from '../widgets/ColorField';
+import { SliderField } from '../widgets/SliderField';
+import { RatingField } from '../widgets/RatingField';
+import { CodeField } from '../widgets/CodeField';
+import { AvatarField } from '../widgets/AvatarField';
+import { AddressField } from '../widgets/AddressField';
+import { GeolocationField } from '../widgets/GeolocationField';
+import { SignatureField } from '../widgets/SignatureField';
+import { QRCodeField } from '../widgets/QRCodeField';
+import { ObjectRefField } from '../widgets/ObjectRefField';
+import { FilterConditionField } from '../widgets/FilterConditionField';
+import { RecipientPickerField } from '../widgets/RecipientPickerField';
+
+/* ════════════════════════════════════════════════════════════════════════════
+ * Every registered field widget, both hosts
+ * ══════════════════════════════════════════════════════════════════════════ */
+
+/**
+ * Static components for the widget map's keys. Kept as one object so the
+ * parity assertion below can prove it covers the whole registry: a NEW field
+ * type added to `fieldWidgetMap` without a line here fails loudly rather than
+ * quietly going unscanned.
+ */
+const WIDGETS: Record<string, ComponentType<any>> = {
+  text: TextField,
+  textarea: TextAreaField,
+  number: NumberField,
+  boolean: BooleanField,
+  select: SelectField,
+  date: DateField,
+  datetime: DateTimeField,
+  time: TimeField,
+  email: EmailField,
+  phone: PhoneField,
+  url: UrlField,
+  multiselect: MultiSelectField,
+  radio: RadioField,
+  checkboxes: CheckboxesField,
+  tags: TagsField,
+  currency: CurrencyField,
+  percent: PercentField,
+  password: PasswordField,
+  markdown: RichTextField,
+  html: RichTextField,
+  richtext: RichTextField,
+  lookup: LookupField,
+  master_detail: LookupField,
+  file: FileField,
+  image: ImageField,
+  location: LocationField,
+  formula: FormulaField,
+  summary: SummaryField,
+  auto_number: AutoNumberField,
+  user: UserField,
+  owner: UserField,
+  object: ObjectField,
+  vector: VectorField,
+  grid: GridField,
+  color: ColorField,
+  slider: SliderField,
+  rating: RatingField,
+  code: CodeField,
+  avatar: AvatarField,
+  address: AddressField,
+  geolocation: GeolocationField,
+  signature: SignatureField,
+  qrcode: QRCodeField,
+  'object-ref': ObjectRefField,
+  'filter-condition': FilterConditionField,
+  'recipient-picker': RecipientPickerField,
+};
+
+/** Option widgets render an "unfillable" placeholder unless offered a list. */
+const OPTION_TYPES = new Set(['select', 'multiselect', 'radio', 'checkboxes', 'tags']);
+const OPTIONS = [
+  { label: 'Alpha', value: 'alpha' },
+  { label: 'Beta', value: 'beta' },
+];
+
+/**
+ * The value each variant starts from: `null` is MISSING for the required check
+ * this repo implements (presence, not truthiness — `false` and `0` are values,
+ * cloud#972), so one value drives a real validation failure for every type,
+ * including `boolean`. Trap 3 above is why that matters, and why every error
+ * variant asserts the message before it scans.
+ */
+const MISSING_VALUE = null;
+
+/** Author-written extras — the open tail that a blacklist cannot close. */
+const AUTHORED_EXTRAS = {
+  zzcanary: 'CANARY-STR',
+  zzcanaryobj: { nested: true },
+  zzcanarynum: 42,
+  zzcanaryCamel: 'CANARY-CAMEL',
+  reference_to: 'contacts',
+};
+
+function fieldConfig(type: string, extras: Record<string, unknown> = {}) {
+  return {
+    name: 'f',
+    label: 'F',
+    type: `field:${type}`,
+    ...(OPTION_TYPES.has(type) ? { options: OPTIONS } : {}),
+    ...extras,
+  };
+}
+
+function renderForm(field: Record<string, unknown>, required: boolean) {
+  const Form = ComponentRegistry.get('form')!;
+  return render(
+    <Form
+      schema={{
+        type: 'form',
+        mode: 'create',
+        showSubmit: true,
+        showCancel: false,
+        submitLabel: 'Create',
+        defaultValues: { f: MISSING_VALUE },
+        fields: [{ ...field, required }],
+        onSubmit: () => {},
+      }}
+    />,
+  );
+}
+
+/**
+ * The form row. Waiting on `[data-field]` (emitted by `FormItem` for EVERY
+ * field) rather than widget-specific copy keeps the wait condition identical
+ * for all 46 widgets and independent of what any one of them renders.
+ */
+async function formRow(): Promise<Element> {
+  return waitFor(() => {
+    const row = document.querySelector('[data-field="f"]');
+    if (!row) throw new Error('field row never rendered');
+    return row;
+  });
+}
+
+beforeAll(() => {
+  for (const [type, Widget] of Object.entries(WIDGETS)) {
+    // `withFieldCarrier` is the real registration seam (objectui#3233) — going
+    // around it would test a widget in a shape no host ever produces.
+    ComponentRegistry.register(type, withFieldCarrier(Widget) as any, {
+      namespace: 'field',
+      skipFallback: true,
+    });
+  }
+}, 60000);
+
+beforeEach(() => {
+  if (!(Element.prototype as any).scrollIntoView) {
+    (Element.prototype as any).scrollIntoView = () => {};
+  }
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+describe('no field widget leaks non-DOM props to the DOM (objectui#3291)', () => {
+  it('covers every field type the form can render', () => {
+    // The gate's reach. Without this, adding a widget adds an unscanned widget.
+    expect(Object.keys(WIDGETS).sort()).toEqual([...FORM_FIELD_TYPES].sort());
+  });
+
+  const types = Object.keys(WIDGETS);
+
+  it.each(types)('field:%s — form path, plain field', async (type) => {
+    renderForm(fieldConfig(type), false);
+    const row = await formRow();
+    expect(leakReport(`field:${type} [form/plain]`, findLeaks(row))).toBe('');
+  });
+
+  it.each(types)('field:%s — form path, author-written extra keys', async (type) => {
+    // The largest measured leak source: the form renderer destructures a fixed set
+    // of known keys and forwards the rest verbatim, so anything else an author
+    // put on the field config arrives at the widget as a prop.
+    renderForm(fieldConfig(type, AUTHORED_EXTRAS), false);
+    const row = await formRow();
+    expect(leakReport(`field:${type} [form/authored-extras]`, findLeaks(row))).toBe('');
+  });
+
+  it.each(types)('field:%s — form path, after a real validation failure', async (type) => {
+    renderForm(fieldConfig(type), true);
+    const row = await formRow();
+
+    fireEvent.click(screen.getByRole('button', { name: /create/i }));
+
+    // Trap 3: scan only once the error is PROVEN to exist. A variant that
+    // silently produced none would otherwise pass while testing nothing.
+    await waitFor(() => {
+      expect(document.querySelector('[data-field="f"]')?.textContent ?? '').toContain(
+        'is required',
+      );
+    });
+
+    expect(
+      leakReport(`field:${type} [form/validation-error]`, findLeaks(await formRow())),
+    ).toBe('');
+  });
+
+  it.each(types)('field:%s — SDUI path, plain node', async (type) => {
+    // Strictly wider than the form path: `SchemaRenderer` spreads the whole
+    // authored node as props with no strip layer, so the widget's own spread
+    // is the only defence here.
+    const { container } = render(
+      <SchemaRenderer schema={{ ...fieldConfig(type), type: `field:${type}` } as any} />,
+    );
+    await waitFor(() => expect(container.firstElementChild).toBeTruthy());
+    expect(leakReport(`field:${type} [sdui/plain]`, findLeaks(container))).toBe('');
+  });
+
+  it.each(types)('field:%s — SDUI path, author-written extra keys', async (type) => {
+    const { container } = render(
+      <SchemaRenderer
+        schema={{ ...fieldConfig(type, AUTHORED_EXTRAS), type: `field:${type}` } as any}
+      />,
+    );
+    await waitFor(() => expect(container.firstElementChild).toBeTruthy());
+    expect(leakReport(`field:${type} [sdui/authored-extras]`, findLeaks(container))).toBe('');
+  });
+});

package/src/__tests__/widget-props-contract.test.tsx

@@ -14,8 +14,9 @@
  * one (objectstack#4075). Three consequences, one test each below:
  *
  *  1. a key the type does not declare is a compile error, not a silent `any`
- *     — which is what makes the `error` / `errorMessage` divergence
- *     (objectui#3222) decidable by the compiler at all;
+ *     — which is what let objectui#3222 rename the validation slot to the
+ *     spec's `error` with the compiler, not grep, proving no call site was
+ *     missed;
  *  2. a MISSPELLED prop (`readOnly` for `readonly`) is rejected;
  *  3. the pass-through keys hosts genuinely forward still type-check, and
  *     still reach the rendered control at runtime — closing the type must not
@@ -52,13 +53,15 @@ describe('FieldWidgetComponentProps is closed (objectui#3221)', () => {
   it('rejects keys it does not declare', () => {
     const props = {} as FieldWidgetComponentProps<string>;
 
-    // The spec's `FieldWidgetPropsSchema` declares both; this type declares
-    // neither. Reading them used to give `any` and `undefined` forever.
-    // Whether to ADD them is objectui#3222 — deliberately not decided here.
+    // `required` stays out on purpose (objectui#3222): the required marker has
+    // exactly one author, the form renderer's `<FormLabel>`, and handing the
+    // flag to widgets invites a second one. Its sibling `error` went the other
+    // way — the spec declares it, so the slot below adopted the spec's name and
+    // the form renderer now produces it.
     // @ts-expect-error `required` is not part of this contract
     void props.required;
-    // @ts-expect-error `error` is not part of this contract — this type's slot is `errorMessage`
-    void props.error;
+    const message: string | undefined = props.error;
+    void message;
 
     // …and the class of bug the index signature hid best: a typo.
     // @ts-expect-error the prop is `readonly`, not React's DOM `readOnly`
@@ -66,6 +69,14 @@ describe('FieldWidgetComponentProps is closed (objectui#3221)', () => {
     // @ts-expect-error the prop is `onChange`
     void props.onchange;
 
+    // The second metadata carrier is gone (objectui#3233). `schema` was a
+    // DECLARED key here through #3221 — one concept under two spellings, which
+    // is how ~30 widgets ended up resolving `field || schema`. v17 converged it
+    // at the producers, so reading it is now a compile error rather than a
+    // silent second contract for the next widget author to discover.
+    // @ts-expect-error `schema` was retired from the widget contract in v17
+    void props.schema;
+
     expect(true).toBe(true);
   });
 
@@ -76,9 +87,11 @@ describe('FieldWidgetComponentProps is closed (objectui#3221)', () => {
     const passThrough: FieldWidgetComponentProps<string> = {
       value: '',
       onChange: () => {},
+      // The single metadata carrier (objectui#3233) — every host produces this
+      // one key: the form renderer (`renderFieldComponent`), the inline-edit
+      // hosts, and the registry adapter that maps `SchemaRenderer`'s SDUI node
+      // onto it.
       field,
-      // form renderer (`renderFieldComponent`)
-      schema: field,
       dataSource: {},
       dependentValues: { country: 'cn' },
       dependsOn: ['country'],

package/src/complex-widgets.test.tsx

@@ -191,9 +191,18 @@ describe('Complex & Relationship Widgets', () => {
                 expect(mockDataSource.find).toHaveBeenCalledTimes(1);
             });
 
-            // Type in search
+            // Type in search. U+2026 now, and it comes from a PACK VALUE:
+            // objectui#4375 retired the `common.search` + '...' concatenation
+            // this used to pin, so the placeholder is `table.search`
+            // — read through `useFieldTranslation`, whose no-provider defaults map
+            // serves the `en` byte `Search…` in this test. It therefore moves with
+            // the pack from here on, and is covered by objectui#3878's glyph pin.
+            // `common.search` itself is retired from the ten packs and from this
+            // package's defaults map (objectui#4392); naming it bare rather than
+            // spelling a t() call around it is what keeps that retirement's
+            // revival pin readable — see common-search-retired-4392.test.ts.
             await act(async () => {
-                fireEvent.change(screen.getByPlaceholderText('Search...'), {
+                fireEvent.change(screen.getByPlaceholderText('Search…'), {
                     target: { value: 'acme' },
                 });
             });
@@ -462,7 +471,9 @@ describe('Complex & Relationship Widgets', () => {
                 expect(screen.getByText('Alpha')).toBeInTheDocument();
             });
 
-            const searchInput = screen.getByPlaceholderText('Search...');
+            // U+2026 from the `table.search` pack value — see the note on the
+            // `$search` test above (objectui#4375).
+            const searchInput = screen.getByPlaceholderText('Search…');
 
             // Arrow down twice: -1 → 0 (Alpha) → 1 (Beta)
             await act(async () => {
@@ -480,9 +491,14 @@ describe('Complex & Relationship Widgets', () => {
             expect(onChange).toHaveBeenCalledWith('2');
         });
 
-        it('resolves reference_to from nested field.field (createFieldRenderer wrapper)', async () => {
-            // Simulates how createFieldRenderer wraps the field: the real metadata
-            // (reference_to, reference_field, etc.) is nested inside field.field.
+        it('resolves reference_to from nested field.field (form metadata slot)', async () => {
+            // Simulates the `field.field` nesting the FORM renderer hands widgets:
+            // `renderFieldComponent` passes `field: field.field || field`, where
+            // `.field` is the declared metadata slot (objectui#3090) holding the
+            // real metadata (reference_to, reference_field, …). The test used to
+            // credit this shape to the docs-demo `createFieldRenderer` wrapper,
+            // which never produced it and no longer exists (objectui#3910); the
+            // live producer is the form path, so the coverage stands.
             const onChange = vi.fn();
             mockDataSource.find.mockResolvedValue({
                 data: [

package/src/currency.ts

@@ -12,3 +12,133 @@
  * every field/cell renderer that already depends on it.
  */
 export { resolveFieldCurrency } from '@object-ui/i18n';
+
+/**
+ * Fallback width for a currency whose digit count cannot be resolved: the
+ * literal both call sites used unconditionally before objectui#4361. It is
+ * reached only when there is no ISO code to ask about (an invalid code, or a
+ * runtime with no currency data at all), never as a policy.
+ */
+const DEFAULT_FRACTION_DIGITS = 2;
+
+/**
+ * ISO 4217 minor-unit width, memoized per currency code.
+ *
+ * The probe is deliberately made with NO locale. Measured across
+ * en-US / de-DE / ja-JP / ar-KW / zh-CN / fr-FR / pl-PL / es-ES and the runtime
+ * default, every locale answers the same digit count for the same code (USD 2,
+ * JPY 0, KWD 3, BHD 3, CLP 0, ISK 0) — the count comes from CLDR's
+ * `currencyData`, which is keyed by the currency, not by who is reading it.
+ * Dropping the locale from the probe therefore loses nothing and removes a
+ * failure mode: a malformed locale tag makes `Intl.NumberFormat` throw
+ * `RangeError: Incorrect locale information provided`, which would turn a bad
+ * LOCALE into a wrong CURRENCY width. It also makes the code the whole cache
+ * key.
+ */
+const fractionDigitsByCurrency = new Map<string, number>();
+
+/**
+ * The number of fraction digits ISO 4217 gives `currency` — 0 for JPY/KRW/CLP,
+ * 2 for USD/EUR/CNY, 3 for KWD/BHD/OMR/TND — as ICU reports it.
+ *
+ * Returns {@link DEFAULT_FRACTION_DIGITS} when the code is not a currency code
+ * at all: `Intl` throws `RangeError: Invalid currency code` for those, and the
+ * throw must not escape, or a bad code would change the width used by the
+ * callers' own bad-currency fallbacks (objectui#4332 pinned those strings). A
+ * code that is well-formed but unknown to CLDR (e.g. `ZZZ`) does not throw —
+ * ICU answers 2 for anything outside its table, which is the same default.
+ *
+ * Memoized because the currency cell renderer runs once per grid cell: measured
+ * at 24.3us per uncached probe against 0.02us cached (200k iterations, node 22),
+ * so a 500-row grid pays ~12ms per render pass for a value that cannot change.
+ */
+export function currencyFractionDigits(currency: string): number {
+  const cached = fractionDigitsByCurrency.get(currency);
+  if (cached !== undefined) return cached;
+  let digits = DEFAULT_FRACTION_DIGITS;
+  try {
+    // `maximumFractionDigits` is typed `number | undefined` on
+    // `ResolvedNumberFormatOptions` — it is absent when a format resolves with
+    // significant-digit rounding instead of fraction-digit rounding, which a
+    // bare `style: 'currency'` never does. Coalesced rather than asserted so
+    // the value is a number by construction and not by claim.
+    digits =
+      new Intl.NumberFormat(undefined, { style: 'currency', currency }).resolvedOptions()
+        .maximumFractionDigits ?? DEFAULT_FRACTION_DIGITS;
+  } catch {
+    // Not a currency code — keep the historical width and let the caller's own
+    // formatting attempt surface the bad code.
+  }
+  fractionDigitsByCurrency.set(currency, digits);
+  return digits;
+}
+
+/**
+ * Display symbols, memoized per **(locale, currency)** pair.
+ *
+ * The pair, not the code — and this is the one place this helper deliberately
+ * parts company with {@link currencyFractionDigits} above. The digit count is
+ * locale-independent (measured across eight locales, see that map's note), so
+ * its probe drops the locale and keys the cache on the code alone. The SYMBOL
+ * is genuinely locale-dependent, measured on the same runtime:
+ *
+ *   - `USD` → `$` at `en` / `en-US` / `de-DE` / `ja-JP`, `US$` at `en-GB` and
+ *     `zh-CN`, `$US` at `fr-FR`;
+ *   - `JPY` → U+00A5 at `en`, the FULLWIDTH U+FFE5 at `ja-JP`, `JP¥` at
+ *     `en-GB`, and the bare code `JPY` at `fr-FR`.
+ *
+ * Copying the code-only cache key would therefore let whichever locale asked
+ * first answer for every locale after it, for the life of the process — a
+ * silent wrong answer rather than a crash, so it is pinned by test.
+ *
+ * `|` is safe as the key separator: it appears in neither a BCP-47 tag nor an
+ * ISO 4217 code, so no two distinct pairs can collide on one key.
+ */
+const symbolByLocaleAndCurrency = new Map<string, string>();
+
+/**
+ * The string ICU renders in place of `currency` for a reader in `locale` — `$`
+ * for USD at `en`, `€` for EUR, U+00A5 for JPY — taken from the `currency` part
+ * of the very format the display path already uses.
+ *
+ * This is the ONE channel for the symbol (objectui#4414). It is not an
+ * independent opinion about how a currency should look: it is the same
+ * `Intl.NumberFormat(locale, { style: 'currency', currency })` that
+ * `formatDisplayNumber` formats amounts with, read one part at a time. So a
+ * widget that renders an amount in one mode and a bare symbol in another cannot
+ * disagree with itself — which is exactly what the hand-written
+ * `currency === 'USD' ? '$' : currency` ternary did, showing `JPY` beside a
+ * readonly `¥1,235`.
+ *
+ * Falls back to `currency` itself — the code as given — in the three cases
+ * where ICU cannot answer, because a bare code is a legitimate adornment (it is
+ * what ICU itself returns for KWD/BHD/CHF/ISK, and what
+ * `formatAmount`'s own bad-code branch renders beside it):
+ *
+ *  1. an invalid currency code — `Intl` throws `RangeError: Invalid currency
+ *     code`;
+ *  2. a malformed locale tag (`en_US` with an underscore, say) — `Intl` throws
+ *     `RangeError: Incorrect locale information provided`. `currencyFractionDigits`
+ *     dodged this failure mode by dropping the locale from its probe; this
+ *     helper needs the locale, so it catches instead. Neither throw may escape:
+ *     this runs during render, so an escaped `RangeError` is a blank widget.
+ *  3. no `currency` part in the output at all — not observed for
+ *     `style: 'currency'`, but coalesced rather than asserted.
+ */
+export function currencySymbol(currency: string, locale: string): string {
+  const key = `${locale}|${currency}`;
+  const cached = symbolByLocaleAndCurrency.get(key);
+  if (cached !== undefined) return cached;
+  let symbol = currency;
+  try {
+    // The formatted value is irrelevant — only the `currency` part is read — so
+    // the cheapest deterministic input is used.
+    const parts = new Intl.NumberFormat(locale, { style: 'currency', currency }).formatToParts(0);
+    symbol = parts.find((part) => part.type === 'currency')?.value ?? currency;
+  } catch {
+    // Bad code or bad locale — keep the code, and let the caller's own
+    // formatting attempt surface the real problem.
+  }
+  symbolByLocaleAndCurrency.set(key, symbol);
+  return symbol;
+}