@object-ui/fields 17.2.0 → 17.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/fields",
-  "version": "17.2.0",
+  "version": "17.5.0",
   "description": "Field renderers and registry for Object UI",
   "license": "MIT",
   "type": "module",
@@ -24,31 +24,35 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/spec": "^17.0.0-rc.1",
+    "@objectstack/spec": "^17.0.0-rc.6",
     "clsx": "^2.1.1",
-    "lucide-react": "^1.25.0",
+    "lucide-react": "^1.29.0",
     "react-markdown": "^10.1.0",
     "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1",
     "tailwind-merge": "^3.6.0",
-    "@object-ui/components": "17.2.0",
-    "@object-ui/core": "17.2.0",
-    "@object-ui/i18n": "17.2.0",
-    "@object-ui/providers": "17.2.0",
-    "@object-ui/react": "17.2.0",
-    "@object-ui/types": "17.2.0"
+    "@object-ui/components": "17.5.0",
+    "@object-ui/core": "17.5.0",
+    "@object-ui/i18n": "17.5.0",
+    "@object-ui/providers": "17.5.0",
+    "@object-ui/react": "17.5.0",
+    "@object-ui/types": "17.5.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@types/react": "19.2.17",
-    "@types/react-dom": "19.2.3",
-    "@vitejs/plugin-react": "^6.0.4",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "@vitejs/plugin-react": "^6.0.5",
+    "postcss": "^8.5.26",
+    "tailwindcss": "^4.3.3",
     "typescript": "^6.0.3",
-    "vite": "^8.1.5",
-    "vite-plugin-dts": "^5.0.3"
+    "vite": "^8.2.1",
+    "vite-plugin-dts": "^5.0.3",
+    "@object-ui/test-support": "17.4.0"
   },
   "publishConfig": {
     "access": "public"
@@ -77,9 +81,9 @@
   },
   "homepage": "https://www.objectui.org/docs/fields",
   "scripts": {
-    "build": "tsc && vite build",
+    "build": "tsc && vite build && node scripts/build-css.mjs",
     "clean": "rm -rf dist",
-    "type-check": "tsc --noEmit",
+    "type-check": "tsc --noEmit && tsc -p tsconfig.test.json",
     "test": "vitest run",
     "lint": "eslint ."
   }

package/src/FieldEditWidget.tsx

@@ -174,12 +174,19 @@ const COMPACT_EDIT_TYPES = new Set<string>(['lookup', 'master_detail', 'user', '
  * form uses — as a controlled `{ value, onChange, field }` input. Returns
  * `null` for types without a registered widget so the caller can fall back to
  * a plain editor.
+ *
+ * `autoFocus` is forwarded because an inline-edit host enters edit mode ON a
+ * field and expects the caret to land there (objectui#4220 — the detail page's
+ * delegation): each widget's own `toDomProps` whitelist already carries it onto
+ * the real focusable control, so nothing here needs to know which element that
+ * is. A host that passes nothing is unaffected.
  */
 export function FieldEditWidget({
   field,
   value,
   onChange,
   readonly,
+  autoFocus,
 }: FieldWidgetComponentProps<any>): React.ReactElement | null {
   const resolved = field?.type ? resolveInlineEditType(field.type) : undefined;
   const Widget = resolved ? EDIT_WIDGETS[resolved] : undefined;
@@ -187,5 +194,14 @@ export function FieldEditWidget({
   // `compact` is a declared widget prop (objectui#3221 closed this type), so
   // the spread no longer needs an `any` escape hatch to get past it.
   const compactProps = resolved && COMPACT_EDIT_TYPES.has(resolved) ? { compact: true } : {};
-  return <Widget field={field} value={value} onChange={onChange} readonly={readonly} {...compactProps} />;
+  return (
+    <Widget
+      field={field}
+      value={value}
+      onChange={onChange}
+      readonly={readonly}
+      autoFocus={autoFocus}
+      {...compactProps}
+    />
+  );
 }

package/src/__tests__/AddressCellRenderer.test.tsx

@@ -0,0 +1,166 @@
+/**
+ * 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#4037 (migrated from objectstack#5019): a `Field.address` value read
+ * as stringified JSON on the record detail page — `{"street":"中策路 1 号",…}` —
+ * because the DISPLAY registry mapped `address` to `JsonCellRenderer`, while
+ * `location` next to it in the same field group had a real formatter. The
+ * create/edit dialog rendered the same field correctly, so the gap was
+ * display-side only.
+ *
+ * Every case below resolves its renderer through `getCellRenderer` — the
+ * display resolver the detail page itself calls — rather than importing
+ * `AddressCellRenderer` directly, so these tests fail on the JSON signature if
+ * the registry entry ever regresses, not merely if the formatter changes.
+ */
+
+import { describe, it, expect } from 'vitest';
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { getCellRenderer, resolveCellRendererType } from '../index';
+
+/** Resolve + render exactly the way `DetailSection` builds a read-mode value. */
+function renderThroughDisplayRegistry(type: string, value: unknown) {
+  const Renderer = getCellRenderer(resolveCellRendererType({ type }) || type);
+  return render(<Renderer value={value as any} field={{ type } as any} />);
+}
+
+/** The stringified-object signature this issue is about. */
+function expectNoJsonSignature(text: string | null) {
+  expect(text).not.toMatch(/[{}]/);
+  expect(text).not.toMatch(/"(street|city|state|postalCode|country)"/);
+  expect(text).not.toMatch(/undefined/);
+}
+
+/** The record from the issue's evidence table. */
+const ISSUE_ADDRESS = {
+  street: '中策路 1 号',
+  city: '杭州',
+  state: '浙江',
+  postalCode: '310000',
+  country: '中国',
+};
+
+describe('address display renderer (objectui#4037)', () => {
+  it('renders a populated address as a formatted line, not stringified JSON', () => {
+    const { container } = renderThroughDisplayRegistry('address', ISSUE_ADDRESS);
+    expectNoJsonSignature(container.textContent);
+    expect(
+      screen.getByText('中策路 1 号, 杭州, 浙江 310000, 中国'),
+    ).toBeInTheDocument();
+  });
+
+  it('resolves `address` through the display registry the way it resolves `location`', () => {
+    // The issue's decisive comparison: one address field beside one location
+    // field, same record, same page. Both must be formatted; neither may fall
+    // through to object stringification.
+    const address = renderThroughDisplayRegistry('address', ISSUE_ADDRESS);
+    const location = renderThroughDisplayRegistry('location', { lat: 30.2741, lng: 120.1551 });
+    expectNoJsonSignature(address.container.textContent);
+    expectNoJsonSignature(location.container.textContent);
+    expect(location.container.textContent).toContain('30.2741');
+  });
+
+  it('carries the full value: every authored sub-field appears', () => {
+    const { container } = renderThroughDisplayRegistry('address', ISSUE_ADDRESS);
+    for (const part of Object.values(ISSUE_ADDRESS)) {
+      expect(container.textContent).toContain(part);
+    }
+  });
+});
+
+describe('address display renderer — partial values render gracefully', () => {
+  it('drops missing parts instead of leaving dangling separators', () => {
+    const { container } = renderThroughDisplayRegistry('address', {
+      street: '中策路 1 号',
+      city: '杭州',
+    });
+    expect(screen.getByText('中策路 1 号, 杭州')).toBeInTheDocument();
+    expectNoJsonSignature(container.textContent);
+    expect(container.textContent).not.toMatch(/,\s*$/);
+    expect(container.textContent).not.toMatch(/,\s*,/);
+  });
+
+  it('renders a street-only address as just the street', () => {
+    renderThroughDisplayRegistry('address', { street: '中策路 1 号' });
+    expect(screen.getByText('中策路 1 号')).toBeInTheDocument();
+  });
+
+  it('keeps state and postal code in one group, either alone', () => {
+    const stateOnly = renderThroughDisplayRegistry('address', { city: 'SF', state: 'CA' });
+    expect(stateOnly.container.textContent).toBe('SF, CA');
+    const postalOnly = renderThroughDisplayRegistry('address', { city: 'SF', postalCode: '94102' });
+    expect(postalOnly.container.textContent).toBe('SF, 94102');
+    const both = renderThroughDisplayRegistry('address', {
+      city: 'SF',
+      state: 'CA',
+      postalCode: '94102',
+    });
+    expect(both.container.textContent).toBe('SF, CA 94102');
+  });
+
+  it('ignores whitespace-only parts rather than spacing over them', () => {
+    const { container } = renderThroughDisplayRegistry('address', {
+      street: '  ',
+      city: '杭州',
+      country: '',
+    });
+    expect(container.textContent).toBe('杭州');
+  });
+
+  it('reads a legacy `zipCode` postal code (objectstack#5143 data)', () => {
+    // Records written by builds up to 17.0.0-rc.1 stored the postal code under
+    // `zipCode`. The input widget reads it; the detail page must not drop it.
+    const { container } = renderThroughDisplayRegistry('address', {
+      city: 'San Francisco',
+      state: 'CA',
+      zipCode: '94102',
+    });
+    expect(container.textContent).toBe('San Francisco, CA 94102');
+  });
+});
+
+describe('address display renderer — nothing is silently swallowed', () => {
+  it('shows the empty placeholder for a null value and for `{}`', () => {
+    const nullValue = renderThroughDisplayRegistry('address', null);
+    expect(nullValue.container.querySelector('[data-slot="empty-value"]')).not.toBeNull();
+    const emptyObject = renderThroughDisplayRegistry('address', {});
+    expect(emptyObject.container.querySelector('[data-slot="empty-value"]')).not.toBeNull();
+  });
+
+  it('keeps an unrecognized shape visible as JSON rather than blanking it', () => {
+    // Strictly better than today, never worse: a value the formatter cannot
+    // read retains the current compact-JSON rendering instead of disappearing.
+    const { container } = renderThroughDisplayRegistry('address', { unexpected: 'data' });
+    expect(container.textContent).toContain('unexpected');
+  });
+
+  it('passes a plain string address straight through', () => {
+    renderThroughDisplayRegistry('address', '中策路 1 号, 杭州');
+    expect(screen.getByText('中策路 1 号, 杭州')).toBeInTheDocument();
+  });
+});
+
+describe('address display renderer — controls (unchanged surfaces)', () => {
+  it('leaves `location` and `geolocation` formatting untouched', () => {
+    const location = renderThroughDisplayRegistry('location', { lat: 30.2741, lng: 120.1551 });
+    expect(location.container.textContent).toBe('30.2741, 120.1551');
+    const geo = renderThroughDisplayRegistry('geolocation', { latitude: 30.2741, longitude: 120.1551 });
+    expect(geo.container.textContent).toBe('30.2741, 120.1551');
+  });
+
+  it('leaves genuinely structural types stringifying as JSON', () => {
+    // `address` moved out of the JSON bucket; `json` / `object` stay in it.
+    for (const type of ['json', 'object', 'composite', 'record']) {
+      const { container } = renderThroughDisplayRegistry(type, { a: 1 });
+      expect(container.textContent).toBe('{"a":1}');
+    }
+  });
+});

package/src/__tests__/CurrencyField.minorUnits.test.tsx

@@ -0,0 +1,191 @@
+/**
+ * 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#4361, second path — `CurrencyField`'s `precision`.
+ *
+ * `formatAmount` passes the field's `precision` to BOTH `Intl` bounds, and the
+ * widget defaulted that precision to a literal `2`. So a JPY field that
+ * declared no precision rendered `¥1,234.50` for the same reason
+ * `formatCurrency` did, one layer up.
+ *
+ * The PM ruling on this card (issue #4361, claim comment) splits it in two,
+ * and both halves are pinned here:
+ *
+ *  1. **An explicitly authored `precision` WINS.** It is authored metadata and
+ *     this repo's convention is that authored metadata keeps priority. A JPY
+ *     field declaring `precision: 2` still renders `¥1,234.50` — whether that
+ *     combination should be REJECTED at publish time is a spec question filed
+ *     upstream (contract-first), not something the renderer decides by
+ *     overriding the author.
+ *  2. **An ABSENT `precision` derives from the currency** instead of falling
+ *     back to 2.
+ *
+ * MEASURED, per the ruling's stop condition — is "absent" distinguishable from
+ * "authored 2" by the time the renderer sees it? Yes:
+ *
+ *   - `CurrencyFieldMetadata.precision` is `precision?: number` in
+ *     `packages/types/src/field-types.ts` — optional, no default;
+ *   - the field-level key is `z.ZodOptional<z.ZodNumber>` in
+ *     `@objectstack/spec` (no `.default()`), so a parsed field metadata object
+ *     does NOT carry a materialized 2;
+ *   - the only `.default(2)` in the spec's currency surface is on
+ *     `CurrencyConfigSchema.precision` — a DIFFERENT key on a different object
+ *     (the `currencyConfig` block), which this widget never reads; and
+ *   - the `?? 2` itself lived in the widget, at `CurrencyField.tsx`.
+ *
+ * So the renderer holds an `undefined` it can act on, and this half lands.
+ *
+ * The derived precision is the widget's ONE precision, so it reaches the edit
+ * affordances too (`step`, and the blur rounding) — pinned below. Leaving
+ * those at 2 would have produced a JPY field that displays whole yen but
+ * offers a 0.01 spinner step and rounds typed input to 1234.56 yen.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { LocalizationProvider } from '@object-ui/i18n';
+import { CurrencyField } from '../widgets/CurrencyField';
+
+/**
+ * ICU separates a currency CODE from the amount with U+00A0 (`KWD` + NBSP +
+ * `1.500`), while a SYMBOL is flush against it (`¥1,235`). `textContent` is
+ * raw, so normalizing keeps these pins about the DIGIT COUNT this card is
+ * about rather than about ICU's spacing. Written as an escape, never a pasted
+ * byte — a raw NBSP in source is invisible to readers and unfindable by grep.
+ */
+const normalizeNbsp = (s: string | null) => (s ?? '').replace(/\u00a0/g, ' ');
+
+const renderField = (
+  value: number | null,
+  field: Record<string, unknown>,
+  opts: { readonly?: boolean; locale?: string; tenantCurrency?: string; onChange?: (v: any) => void } = {},
+) =>
+  render(
+    <LocalizationProvider value={{ locale: opts.locale ?? 'en-US', currency: opts.tenantCurrency }}>
+      <CurrencyField
+        value={value as any}
+        onChange={opts.onChange ?? vi.fn()}
+        field={{ type: 'currency', ...field } as any}
+        readonly={opts.readonly}
+      />
+    </LocalizationProvider>,
+  );
+
+describe('CurrencyField — an ABSENT precision derives from the currency (objectui#4361)', () => {
+  it('a JPY field that declares no precision shows no cents', () => {
+    const { container } = renderField(1234.5, { currency: 'JPY' }, { readonly: true });
+    expect(normalizeNbsp(container.textContent)).toBe('¥1,235');
+  });
+
+  it('a KWD field that declares no precision shows all three digits', () => {
+    const { container } = renderField(1.5, { currency: 'KWD' }, { readonly: true });
+    expect(normalizeNbsp(container.textContent)).toBe('KWD 1.500');
+  });
+
+  it('the tenant default currency reaches the derivation too (ADR-0053)', () => {
+    const { container } = renderField(1234.5, {}, { readonly: true, tenantCurrency: 'JPY' });
+    expect(normalizeNbsp(container.textContent)).toBe('¥1,235');
+  });
+
+  it('`currencyConfig.defaultCurrency` reaches it as well', () => {
+    const { container } = renderField(
+      1.5,
+      { currencyConfig: { defaultCurrency: 'KWD' } },
+      { readonly: true },
+    );
+    expect(normalizeNbsp(container.textContent)).toBe('KWD 1.500');
+  });
+});
+
+describe('CurrencyField — an AUTHORED precision still wins (authored metadata keeps priority)', () => {
+  it('a JPY field declaring `precision: 2` keeps its two digits', () => {
+    // The renderer does not overrule the author. Whether publish-time
+    // validation should reject this combination is the upstream spec question
+    // filed alongside this card — deliberately NOT decided here.
+    const { container } = renderField(1234.5, { currency: 'JPY', precision: 2 }, { readonly: true });
+    expect(normalizeNbsp(container.textContent)).toBe('¥1,234.50');
+  });
+
+  it('an authored `precision: 0` on a 2-digit currency still wins', () => {
+    // The other direction, so the pin cannot be satisfied by "authored wins
+    // only when it asks for MORE digits".
+    const { container } = renderField(1234.5, { currency: 'USD', precision: 0 }, { readonly: true });
+    expect(normalizeNbsp(container.textContent)).toBe('$1,235');
+  });
+
+  it('an authored `precision: 3` on JPY wins', () => {
+    const { container } = renderField(1234.5, { currency: 'JPY', precision: 3 }, { readonly: true });
+    expect(normalizeNbsp(container.textContent)).toBe('¥1,234.500');
+  });
+});
+
+describe('CurrencyField — CONTROL: the 2-digit and no-currency cases are unchanged', () => {
+  it('a USD field with no declared precision renders exactly as before', () => {
+    // Derivation and the old literal agree at 2, which is the whole point of
+    // "byte-identical for USD".
+    const { container } = renderField(1234.5, { currency: 'USD' }, { readonly: true });
+    expect(normalizeNbsp(container.textContent)).toBe('$1,234.50');
+  });
+
+  it('a USD field declaring `precision: 2` renders exactly as before', () => {
+    const { container } = renderField(1234.56, { currency: 'USD', precision: 2 }, { readonly: true });
+    expect(normalizeNbsp(container.textContent)).toBe('$1,234.56');
+  });
+
+  it('a field with NO currency keeps the literal 2 — nothing to derive from', () => {
+    const { container } = renderField(1234.5, {}, { readonly: true });
+    expect(normalizeNbsp(container.textContent)).toBe('1,234.50');
+  });
+
+  it('a null value is still the empty marker, not a formatted zero', () => {
+    const { container } = renderField(null, { currency: 'JPY' }, { readonly: true });
+    expect(container.textContent).not.toContain('¥');
+  });
+});
+
+describe('CurrencyField — the derived precision is the widget\'s ONE precision', () => {
+  it('a JPY field with no declared precision offers a whole-unit spinner step', () => {
+    renderField(1234, { currency: 'JPY' });
+    expect(screen.getByRole('spinbutton')).toHaveAttribute('step', '1');
+  });
+
+  it('a KWD field with no declared precision offers a three-digit step', () => {
+    renderField(1, { currency: 'KWD' });
+    expect(screen.getByRole('spinbutton')).toHaveAttribute('step', '0.001');
+  });
+
+  it('CONTROL: USD is still 0.01, authored or derived', () => {
+    const { unmount } = renderField(1, { currency: 'USD' });
+    expect(screen.getByRole('spinbutton')).toHaveAttribute('step', '0.01');
+    unmount();
+    renderField(1, { currency: 'JPY', precision: 2 });
+    expect(screen.getByRole('spinbutton')).toHaveAttribute('step', '0.01');
+  });
+
+  it('blur rounds a typed amount to the currency\'s own unit', () => {
+    const onChange = vi.fn();
+    renderField(null, { currency: 'JPY' }, { onChange });
+    const input = screen.getByRole('spinbutton');
+    fireEvent.change(input, { target: { value: '1234.56' } });
+    fireEvent.blur(input, { target: { value: '1234.56' } });
+    // Before: 1234.56 yen — a sub-unit amount the currency cannot express.
+    expect(onChange).toHaveBeenLastCalledWith(1235);
+  });
+
+  it('CONTROL: blur on a USD field still rounds to cents', () => {
+    const onChange = vi.fn();
+    renderField(null, { currency: 'USD' }, { onChange });
+    const input = screen.getByRole('spinbutton');
+    fireEvent.change(input, { target: { value: '1234.567' } });
+    fireEvent.blur(input, { target: { value: '1234.567' } });
+    expect(onChange).toHaveBeenLastCalledWith(1234.57);
+  });
+});

package/src/__tests__/CurrencyField.symbol.test.tsx

@@ -0,0 +1,198 @@
+/**
+ * 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#4414 — the edit-mode currency adornment has ONE channel.
+ *
+ * Before this card `CurrencyField.tsx` carried the same one-entry fact twice: a
+ * `CURRENCY_SYMBOLS` map that nothing read, and, two lines below it, the live
+ * `currency === 'USD' ? '$' : currency` ternary. The PM ruling (issue #4414,
+ * claim comment) says one channel survives, and that `Intl` — which already
+ * carries this knowledge — is the candidate to MEASURE first.
+ *
+ * Measured, and it fits: `Intl.NumberFormat(locale, { style: 'currency',
+ * currency }).formatToParts()` has a `currency` part, and that part is exactly
+ * the string the widget's OWN readonly branch already renders, because the
+ * readonly branch formats through `formatDisplayNumber(value, { locale,
+ * currency })` — the same `Intl` call. So the adornment was the last hand copy,
+ * and the widget disagreed with itself: at `en`, readonly JPY rendered
+ * `¥1,235` while the edit adornment beside it said `JPY`.
+ *
+ * The one place this helper deliberately DIVERGES from its sibling
+ * `currencyFractionDigits()`: the digit count is locale-independent (measured
+ * across eight locales in `currency.ts`), so that probe drops the locale. The
+ * SYMBOL is not — measured on node 22 / full-ICU:
+ *
+ *     USD -> "$" (en, en-US, de-DE, ja-JP) | "US$" (en-GB, zh-CN) | "$US" (fr-FR)
+ *     JPY -> "¥" (en, de-DE) | "￥" (ja-JP) | "JP¥" (en-GB, zh-CN) | "JPY" (fr-FR)
+ *
+ * so `currencySymbol()` takes the display locale as a parameter and caches on
+ * the PAIR. Keying the cache on the code alone would let whichever locale asked
+ * first answer for every locale after it — pinned below, because that is a
+ * silent wrong-answer bug and not a hypothetical.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { LocalizationProvider } from '@object-ui/i18n';
+import { CurrencyField } from '../widgets/CurrencyField';
+import { currencySymbol } from '../currency';
+
+/**
+ * ICU separates a currency CODE from the amount with U+00A0 and sets a SYMBOL
+ * flush against it; normalizing keeps the readonly-agreement pins about the
+ * SYMBOL rather than about ICU's spacing. Written as an escape, never a pasted
+ * byte.
+ */
+const normalizeNbsp = (s: string | null) => (s ?? '').replace(/\u00a0/g, ' ');
+
+const renderField = (
+  field: Record<string, unknown>,
+  opts: { readonly?: boolean; locale?: string; tenantCurrency?: string } = {},
+) =>
+  render(
+    <LocalizationProvider value={{ locale: opts.locale ?? 'en', currency: opts.tenantCurrency }}>
+      <CurrencyField
+        value={1234.5}
+        onChange={vi.fn()}
+        field={{ type: 'currency', ...field } as any}
+        readonly={opts.readonly}
+      />
+    </LocalizationProvider>,
+  );
+
+/** The edit-mode prefix adornment: the only `span` inside the wrapper. */
+const adornment = (container: HTMLElement) =>
+  container.querySelector('div.relative > span')?.textContent ?? null;
+
+describe('CurrencyField adornment — USD is byte-identical at the display-locale default (objectui#4414)', () => {
+  it("`en` — useDisplayLocale()'s own last resort — still renders exactly `$`", () => {
+    const { container } = renderField({ currency: 'USD' });
+    expect(adornment(container)).toBe('$');
+  });
+
+  it('`en-US` still renders exactly `$`', () => {
+    const { container } = renderField({ currency: 'USD' }, { locale: 'en-US' });
+    expect(adornment(container)).toBe('$');
+  });
+
+  it('the tenant default currency reaches the adornment too (ADR-0053)', () => {
+    const { container } = renderField({}, { tenantCurrency: 'USD' });
+    expect(adornment(container)).toBe('$');
+  });
+
+  it('a field with NO currency still renders no adornment and no left padding', () => {
+    const { container } = renderField({});
+    expect(adornment(container)).toBeNull();
+    expect(container.querySelector('input')).not.toHaveClass('pl-8');
+  });
+
+  it('a field WITH a currency still gets the left padding that clears the adornment', () => {
+    const { container } = renderField({ currency: 'USD' });
+    expect(container.querySelector('input')).toHaveClass('pl-8');
+  });
+});
+
+describe('CurrencyField adornment — the DOCUMENTED non-USD change: a real symbol replaces the bare code', () => {
+  // Before #4414 every one of these rendered the three-letter ISO code, because
+  // the ternary had exactly one entry. This is the deliberate improvement the
+  // ruling allowed for, not a side effect — and it is what the widget's own
+  // readonly branch has been rendering all along.
+  it.each([
+    ['EUR', '€'],
+    ['JPY', '¥'],
+    ['GBP', '£'],
+    ['INR', '₹'],
+    ['KRW', '₩'],
+  ])('%s now renders %s instead of the code', (currency, symbol) => {
+    const { container } = renderField({ currency });
+    expect(adornment(container)).toBe(symbol);
+  });
+});
+
+describe('CurrencyField adornment — currencies CLDR has no symbol for keep the code, byte-identical', () => {
+  // ICU answers with the code itself for these, which is exactly what the
+  // ternary produced. Nothing changes, and that is worth pinning: it is the
+  // half of the ruling's "symbol-vs-code nuance" that survives the change.
+  it.each(['KWD', 'BHD', 'CHF', 'ISK', 'CLP'])('%s still renders its bare code', (currency) => {
+    const { container } = renderField({ currency });
+    expect(adornment(container)).toBe(currency);
+  });
+});
+
+describe('CurrencyField adornment — it agrees with the SAME widget\'s readonly rendering', () => {
+  // The real invariant behind this card. The readonly branch already formats
+  // through the display locale, so before #4414 the widget contradicted itself
+  // for every currency with a symbol.
+  it.each([
+    ['en', 'JPY'],
+    ['en', 'EUR'],
+    ['en-GB', 'USD'],
+    ['fr-FR', 'USD'],
+    ['ja-JP', 'JPY'],
+    ['de-DE', 'USD'],
+    ['en', 'KWD'],
+  ])('%s / %s — the readonly text contains the adornment string', (locale, currency) => {
+    const edit = renderField({ currency }, { locale });
+    const symbol = adornment(edit.container);
+    expect(symbol).toBeTruthy();
+    const view = renderField({ currency }, { locale, readonly: true });
+    expect(normalizeNbsp(view.container.textContent)).toContain(symbol as string);
+  });
+});
+
+describe('currencySymbol() — the symbol is locale-dependent, so the locale is a parameter', () => {
+  it('USD is not one string across locales', () => {
+    expect(currencySymbol('USD', 'en')).toBe('$');
+    expect(currencySymbol('USD', 'fr-FR')).toBe('$US');
+    expect(currencySymbol('USD', 'en-GB')).toBe('US$');
+  });
+
+  it('JPY at ja-JP is the FULLWIDTH yen sign, a different codepoint from `en`', () => {
+    // U+FFE5 vs U+00A5 — visually near-identical, so written as escapes.
+    expect(currencySymbol('JPY', 'en')).toBe('\u00a5');
+    expect(currencySymbol('JPY', 'ja-JP')).toBe('\uffe5');
+    expect(currencySymbol('JPY', 'ja-JP')).not.toBe(currencySymbol('JPY', 'en'));
+  });
+
+  it('the cache is keyed on the PAIR — the first locale to ask must not answer for the rest', () => {
+    // The bug this pin exists for: copying `currencyFractionDigits`' code-only
+    // cache key would make these two calls return the same string, whichever
+    // ran first, for the rest of the process.
+    const first = currencySymbol('GBP', 'en-GB');
+    const second = currencySymbol('GBP', 'ar-KW');
+    expect(first).toBe('£');
+    expect(second).toBe('UK£');
+    // …and re-asking returns the cached value, not the other locale's.
+    expect(currencySymbol('GBP', 'en-GB')).toBe('£');
+  });
+});
+
+describe('currencySymbol() — neither a bad code nor a bad locale may escape as a throw', () => {
+  it('an invalid currency code falls back to the code as given', () => {
+    // `Intl` throws `RangeError: Invalid currency code` for these. The fallback
+    // is the code itself, which is both what the ternary produced and what
+    // `formatAmount`'s own bad-code branch renders beside it.
+    expect(currencySymbol('not-a-code', 'en')).toBe('not-a-code');
+    expect(currencySymbol('USDD', 'en')).toBe('USDD');
+  });
+
+  it('a malformed locale tag falls back to the code rather than crashing the widget', () => {
+    // `Intl` throws `RangeError: Incorrect locale information provided` for
+    // `en_US` (underscore) — the failure mode `currencyFractionDigits` dodged
+    // by dropping the locale entirely, which this helper cannot do.
+    expect(currencySymbol('USD', 'en_US')).toBe('USD');
+  });
+
+  it('the widget renders the code instead of throwing when the code is junk', () => {
+    const { container } = renderField({ currency: 'not-a-code' });
+    expect(adornment(container)).toBe('not-a-code');
+  });
+});