@object-ui/fields 17.3.0 → 17.5.0

package/dist/widgets/toHostGroupProps.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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.
+ */
+/**
+ * The props that make a group-labelled widget's rendered surface the thing its
+ * host label actually NAMES, on the surfaces that are not controls
+ * (objectui#3990).
+ *
+ * ## What it is for
+ *
+ * A widget declared `labelling: 'group'` (objectui#3961) is told by the form
+ * renderer: your label publishes an `id` and drops its `for`, so name yourself
+ * by IDREF. The renderer hands down exactly two facts that address the field as
+ * a WHOLE:
+ *
+ *  - `id` — the host's control id (`…-form-item`), the id the label's `for`
+ *    used to point at;
+ *  - `aria-labelledby` — the IDREF of that visible label.
+ *
+ * Every editable branch already consumes them inside its wider `toDomProps`
+ * spread. The branches that returned EARLY did not — a field-level
+ * `readonly: true`, or an option list with zero offered options — so the label
+ * published an id that no element in the document referenced. Measured on
+ * `origin/main`, one field per row, reading the host label against the DOM:
+ *
+ * ```
+ * multiselect  readonly+value   consumers=0  byLabelText=0  namedByRole=[]
+ * multiselect  readonly+empty   consumers=0  byLabelText=0  namedByRole=[]
+ * multiselect  zeroOptions      consumers=0  byLabelText=0  namedByRole=[]
+ * multiselect  editable         consumers=1  byLabelText=1  namedByRole=[group:1]
+ * ```
+ *
+ * All seven group-labelled types measured the same, in every readonly state.
+ * This is quieter than the dangling `for` #3961 replaced: a `for` that resolves
+ * to nothing can at least be swept for, while "a label published an id and
+ * nobody consumed it" looks like healthy markup.
+ *
+ * ## Why this narrow pair, and not the whole `toDomProps` result
+ *
+ * Everything else in the DOM pass-through addresses a CONTROL, and a readonly
+ * display has none: `aria-describedby` / `aria-required` are announced when
+ * focus lands on something focusable, `disabled` / `tabIndex` / the focus
+ * handlers only mean something on an interactive element, and `name` is
+ * DOM-legal on form controls only — on a `div` it is exactly the leak
+ * objectui#3291 sweeps for. Spreading the full result would also put the host's
+ * `className` on top of the widget's own, because the widgets whose readonly
+ * surface is a placeholder or a plain container (`EmptyValue`, `FileField`,
+ * `AddressField`) keep `className` inside `props`.
+ *
+ * ## Why `role` travels with the two keys
+ *
+ * `aria-labelledby` on a role-less `div` / `span` names NOTHING — `generic`
+ * prohibits an author name — so the pair is inert without a role that supports
+ * naming. `group` is the one that fits a readonly surface: it names a set of
+ * values (chips, checked labels, stars, file names, a formatted address)
+ * without promising the interactivity `textbox` or `radiogroup` would. It is
+ * deliberately NOT the role the same widget answers with while editable:
+ * `RadioField`'s readonly branch renders the chosen label as text with no radios
+ * left in it, and `FileField`'s renders file names with no dropzone button.
+ *
+ * The role is emitted ONLY when a host actually named the field, mirroring
+ * every editable branch's `isLabelledGroup` test: standalone rendering (the
+ * grid's inline cell editor, a bare SDUI node) hands down neither key, so every
+ * value here is `undefined`, React emits no attribute, and that markup stays
+ * byte-identical to what it was.
+ */
+export interface HostGroupProps {
+    /** The host's control id — the id its label would have pointed `for` at. */
+    id?: string;
+    /** IDREF of the host's visible label. */
+    'aria-labelledby'?: string;
+    /** `'group'` when — and only when — a host named this surface. */
+    role?: 'group';
+}
+/**
+ * Read the two whole-field keys out of a widget's leftover props, plus the role
+ * that makes them mean something. See {@link HostGroupProps}.
+ *
+ * Routed through {@link toDomProps} rather than reading `props` directly so the
+ * pair keeps ONE gate: those keys reach an element only if the DOM pass-through
+ * whitelist still forwards them, and its two compile-time assertions bind that
+ * whitelist to the props contract in both directions.
+ */
+export declare function toHostGroupProps(props: {
+    id?: string;
+    'aria-labelledby'?: string;
+}): HostGroupProps;

package/dist/widgets/useRecordQuery.d.ts

@@ -46,8 +46,14 @@ export interface UseRecordQueryOptions {
      * `$filter` — already merged by the caller (base `lookup_filters`, dependent
      * lookup chain, candidate hygiene like `banned != true`, …). Compared by
      * value, so a referentially-new-but-equal object each render will not loop.
+     *
+     * Either the `QueryParams.$filter` record form or a lowered ObjectQL AST node
+     * (an array), since the picker's merge now produces both (#3831). Typed
+     * `unknown` rather than `Record< string, any >` so an array cannot slip
+     * through a type that silently accepts it; emptiness is decided by
+     * {@link hasFilter}, not by `Object.keys`.
      */
-    filter?: Record<string, any>;
+    filter?: unknown;
     /** `$expand` — related entities to include (e.g. `['primary_business_unit_id']`). */
     expand?: string[];
     /** `$searchFields` — narrow the server searchable set (ADR-0061). */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/fields",
-  "version": "17.3.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.2",
+    "@objectstack/spec": "^17.0.0-rc.6",
     "clsx": "^2.1.1",
-    "lucide-react": "^1.28.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.3.0",
-    "@object-ui/core": "17.3.0",
-    "@object-ui/i18n": "17.3.0",
-    "@object-ui/providers": "17.3.0",
-    "@object-ui/react": "17.3.0",
-    "@object-ui/types": "17.3.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": {
+    "@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.2.0",
-    "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);
+  });
+});