@object-ui/fields 17.3.0 → 17.5.0

package/src/__tests__/percent-formatter-locale-4553.test.ts

@@ -0,0 +1,147 @@
+/**
+ * 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#4553 phase 2 — `formatPercent` was the last formatter outside the
+ * display-locale channel, and it was outside it in a different way from its
+ * siblings.
+ *
+ * PR #4557 threaded the gantt tooltip's number and currency rows and measured
+ * that percent could not follow: `formatPercent(value, precision)` took no
+ * locale parameter, and its whole body was
+ * `${percentDisplayValue(value).toFixed(precision)}%`. It built no
+ * `Intl.NumberFormat` and never reached `formatDisplayNumber`, so its output
+ * was not the MACHINE's locale (the defect its siblings had) but NO locale at
+ * all: an ASCII decimal mark, never a grouping separator, byte-identical on
+ * every machine on earth.
+ *
+ * That is why grouping and locale land together here. `1235%` is not merely
+ * un-German — it is wrong in en-US too, where the number is `1,235%`. So the
+ * English output MOVES, and that move is the fix, not a regression.
+ *
+ * ── Directions, predicted in writing BEFORE the run, then measured ───────
+ * Runner: node v22.22.2 / ICU 78.2 / machine locale en-US.
+ *
+ *   en 1234.5 p0   `1235%`   → `1,235%`      RED — the grouping move
+ *   de 1234.5 p0   `1235%`   → `1.235 %`     RED — separators inverted + NBSP
+ *   de 80     p0   `80%`     → `80 %`        RED — de writes a no-break space
+ *                                             before the sign; en does not
+ *   de 12.5   p1   `12.5%`   → `12,5 %`      RED — the ruling's named form
+ *   en 80     p0   `80%`     → `80%`         PIN, green both sides
+ *   en 12.5   p1   `12.5%`   → `12.5%`       PIN, green both sides
+ *   fraction scaling (0.8 → 80%)             PIN, green both sides
+ *
+ * The `en` pins are byte-identical because `en` and the runner's `en-US` agree
+ * and because grouping only shows from four digits up — they are NOT evidence
+ * the fix works; the `de` cases and the en GROUPING case carry that.
+ *
+ * Provider-less by construction (objectui#4514): these are pure-function cases
+ * that touch no hook. The provider-mounted half of this card lives in
+ * `PercentCellRenderer.locale.test.tsx`.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { formatPercent } from '../index';
+
+/**
+ * German puts a NO-BREAK SPACE (U+00A0) between the number and the percent
+ * sign. Written as an escape rather than pasted, so the expectation is
+ * readable and greppable in both spellings.
+ */
+const NBSP = '\u00a0';
+
+describe('formatPercent groups its output (objectui#4553)', () => {
+  /**
+   * THE en RED CASE, and the one that justifies calling this a defect rather
+   * than a localization nicety: four digits went out ungrouped in English too.
+   */
+  it('en groups from four digits up — the output MOVES, and that is the fix', () => {
+    expect(formatPercent(1234.5, 0, 'en')).toBe('1,235%');
+    expect(formatPercent(1000000, 0, 'en')).toBe('1,000,000%');
+  });
+
+  /** PIN, green both sides: below the grouping threshold nothing changes. */
+  it('en output below the grouping threshold is byte-identical (must-not-change)', () => {
+    expect(formatPercent(80, 0, 'en')).toBe('80%');
+    expect(formatPercent(12.5, 1, 'en')).toBe('12.5%');
+    expect(formatPercent(33.33, 2, 'en')).toBe('33.33%');
+    expect(formatPercent(0, 0, 'en')).toBe('0%');
+  });
+});
+
+describe('formatPercent follows the display locale (objectui#4553)', () => {
+  /**
+   * The separators invert AND a no-break space appears before the sign, so the
+   * German form cannot coincide with the machine's on this runner.
+   */
+  it('de inverts the separators and spaces the percent sign', () => {
+    expect(formatPercent(1234.5, 0, 'de')).toBe(`1.235${NBSP}%`);
+    expect(formatPercent(12.5, 1, 'de')).toBe(`12,5${NBSP}%`);
+  });
+
+  /**
+   * Even with no separator in play, German still differs from English: the
+   * space before the sign is part of the locale's percent CONVENTION, which is
+   * what routing through `Intl` buys over appending a literal '%'.
+   */
+  it('de spaces the sign even for a value with no separators', () => {
+    expect(formatPercent(80, 0, 'de')).toBe(`80${NBSP}%`);
+  });
+
+  /** `Intl` accepts `'zh'` verbatim — no mapping table anywhere. */
+  it('zh renders its own convention', () => {
+    expect(formatPercent(1234.5, 0, 'zh')).toBe('1,235%');
+  });
+
+  /**
+   * A malformed tag from a tenant config must never take a cell down —
+   * `formatDisplayNumber` catches it and retries without the locale.
+   */
+  it('a malformed locale tag falls back instead of throwing', () => {
+    expect(() => formatPercent(80, 0, 'not a locale')).not.toThrow();
+    expect(formatPercent(80, 0, 'not a locale')).toContain('80');
+  });
+});
+
+describe('formatPercent keeps its existing contract (objectui#4553 must-not-change)', () => {
+  /**
+   * PIN: the fraction/whole disambiguation is `percentDisplayValue`'s, shared
+   * with the dashboard measure formatter. The locale parameter must not have
+   * moved it.
+   */
+  it('still scales a fraction-stored percent and passes a whole one through', () => {
+    expect(formatPercent(0.8, 0, 'en')).toBe('80%');
+    expect(formatPercent(0.5, 0, 'en')).toBe('50%');
+    expect(formatPercent(0.075, 1, 'en')).toBe('7.5%');
+    // >= 1 is already in display magnitude and is NOT scaled again.
+    expect(formatPercent(80, 0, 'en')).toBe('80%');
+    expect(formatPercent(100, 0, 'en')).toBe('100%');
+  });
+
+  it('still honors the precision it is given', () => {
+    expect(formatPercent(33.333, 0, 'en')).toBe('33%');
+    expect(formatPercent(33.333, 1, 'en')).toBe('33.3%');
+    expect(formatPercent(33.333, 2, 'en')).toBe('33.33%');
+  });
+
+  it('still handles negatives', () => {
+    expect(formatPercent(-45.5, 1, 'en')).toBe('-45.5%');
+  });
+
+  /**
+   * The parameter is OPTIONAL and third, matching `formatNumber(value,
+   * decimals, locale)` and `formatCurrency(value, currency, locale)`. An
+   * existing caller passing nothing still gets the runtime default locale —
+   * though it now also gets grouping, which is the deliberate output move.
+   */
+  it('is callable with no locale, and with no precision either', () => {
+    expect(() => formatPercent(80)).not.toThrow();
+    expect(formatPercent(80)).toBe('80%');
+    expect(formatPercent(80, 0)).toBe('80%');
+  });
+});

package/src/__tests__/percent-tie-halfup-4590.test.ts

@@ -0,0 +1,224 @@
+/**
+ * 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#4590 — `formatPercent` rounds a tie the wrong way, because it renders
+ * a value that is ALREADY in percentage points through `Intl`'s
+ * `style: 'percent'`, which wants a FRACTION.
+ *
+ * The old body divided by 100 so `Intl` could multiply straight back:
+ *
+ *     formatDisplayNumber(displayValue / 100, { style: 'percent', … })
+ *
+ * That round trip is not value-preserving. `Intl` formats from the SHORTEST
+ * decimal representation of the double it is handed, and `displayValue / 100`
+ * has a different shortest representation from `displayValue`: `1.005` is
+ * `1.005`, but `1.005 / 100` is `0.010049999999999999`, which percent-scales to
+ * `1.0049999999999999` and rounds DOWN. The DIVISION loses the digit, not the
+ * rounding. It is therefore a numeral defect and not a convention one — it
+ * reproduces identically in every locale, in Arabic-Indic digits too.
+ *
+ * The fix is the option #4576 / PR #4589 put in `@object-ui/core` for exactly
+ * this: `style: 'percentPoints'` formats the points DIRECTLY (`Intl`'s
+ * `style: 'unit'` / `unit: 'percent'` / `unitDisplay: 'narrow'`), which was
+ * measured to give a byte-identical percent affix to `style: 'percent'` across
+ * all 171 locale tags tested.
+ *
+ * ── PREDICTIONS, written before the run ─────────────────────────────────────
+ * Runner measured: node v22.22.2, ICU 78.2, machine locale en-US.
+ *
+ *   RED before the fix — the numerals:
+ *     formatPercent(1.005, 2, 'en-US')   `1.00%`  → `1.01%`
+ *     formatPercent(1.025, 2, 'en-US')   `1.02%`  → `1.03%`
+ *     formatPercent(1.45,  1, 'en-US')   `1.4%`   → `1.5%`
+ *     formatPercent(1.055, 2, 'en-US')   `1.05%`  → `1.06%`
+ *     formatPercent(99999.995, 2, 'en')  `99,999.99%` → `100,000.00%`
+ *     MAX_SAFE_INTEGER p0   `9,007,199,254,740,990%` → `…991%`
+ *     1e23            p0    `99,999,999,999,999,990,000,000%`
+ *                           → `100,000,000,000,000,000,000,000%`
+ *     the same four ties in de-DE / tr-TR / ar-EG — the locale-independence
+ *     claim, red in every one of them
+ *
+ *   GREEN ON BOTH SIDES — the must-not-change set, and the STOP condition if
+ *   any of it moves (this card is NUMERAL-only; a convention move is a defect
+ *   in the fix, not a pin to update):
+ *     the percent CONVENTION of all ten locales at 1234.5 p1 — de/fr/ru/sv's
+ *     no-break space, tr's PREFIX sign, ar's U+066A + U+061C, en/ja/zh's bare
+ *     suffix, fr's U+202F group separator, bn's Bengali digits
+ *     the sign position and glyph on negatives (sv-SE's U+2212 included)
+ *     the affix parity check against `Intl`'s own `style: 'percent'`
+ *     `percentDisplayValue`'s fraction/whole scaling — upstream of the render
+ *     and deliberately untouched by this card
+ *
+ * MEASURED, this call shape, old route vs new: 10 locales x 18 values x 4
+ * precisions = 720 combinations — 0 convention diffs, 130 numeral diffs (13 per
+ * locale, the SAME 13 in every locale). On the wide en-US grid the issue
+ * quantified (0.005 steps to 2000, precisions 0/1/2) 27,577 of 1,200,003 forms
+ * move. Every one is a last-digit-off-by-one.
+ *
+ * Every non-ASCII byte below is written as a `\u` escape, never pasted.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { formatPercent } from '../index';
+
+/** U+00A0 NO-BREAK SPACE — de/fr/ru/sv put one before the percent sign. */
+const NBSP = '\u00a0';
+/** U+202F NARROW NO-BREAK SPACE — fr's group separator. */
+const NNBSP = '\u202f';
+/** U+066A ARABIC PERCENT SIGN, U+061C ARABIC LETTER MARK. */
+const ARABIC_PERCENT = '\u066a';
+const ALM = '\u061c';
+
+describe('formatPercent rounds a tie half-up on the authored decimal (#4590)', () => {
+  /**
+   * MOVING PINS — the issue's measured table, verbatim. Each was the artefact
+   * of the `/ 100` round trip; the right-hand column is half-up on the decimal
+   * the author actually wrote.
+   */
+  it.each([
+    [1.005, 2, '1.01%', '1.00%'],
+    [1.025, 2, '1.03%', '1.02%'],
+    [1.45, 1, '1.5%', '1.4%'],
+    [1.055, 2, '1.06%', '1.05%'],
+  ])('formatPercent(%s, %s) is %s (was %s)', (value, precision, expected) => {
+    expect(formatPercent(value, precision, 'en-US')).toBe(expected);
+  });
+
+  /**
+   * A tie that carries into a new digit COLUMN rather than just flipping the
+   * last one — the round trip lost the carry as well as the digit.
+   */
+  it('carries across the grouping boundary: 99999.995 to 2 decimals', () => {
+    // was `99,999.99%`
+    expect(formatPercent(99999.995, 2, 'en-US')).toBe('100,000.00%');
+  });
+
+  /**
+   * The defect is in the VALUE, not the convention, so it must reproduce in
+   * every locale — including one that writes the sign in front and one that
+   * uses neither ASCII digits nor an ASCII sign.
+   */
+  it('the same ties move in every locale — this is a numeral defect', () => {
+    expect(formatPercent(1.005, 2, 'de-DE')).toBe(`1,01${NBSP}%`); // was `1,00 %`
+    expect(formatPercent(1.45, 1, 'de-DE')).toBe(`1,5${NBSP}%`); // was `1,4 %`
+    expect(formatPercent(1.005, 2, 'tr-TR')).toBe('%1,01'); // was `%1,00`
+    // U+0661 U+066B U+0660 U+0661 — Arabic-Indic `1`, decimal separator, `0`, `1`
+    expect(formatPercent(1.005, 2, 'ar-EG')).toBe(
+      `\u0661\u066b\u0660\u0661${ARABIC_PERCENT}${ALM}`,
+    ); // was `\u0661\u066b\u0660\u0660` + the same affix
+  });
+});
+
+describe('formatPercent keeps every digit at the top of the double range (#4590)', () => {
+  /**
+   * MOVING PINS, before/after verbatim. `Number.MAX_SAFE_INTEGER` percentage
+   * points used to render with its last digit replaced by a zero, and 1e23 used
+   * to render as a number that is not 1e23 at all. Both are the same artefact
+   * as the ties, at the other end of the range: divide by 100 and the shortest
+   * representation of the quotient no longer round-trips.
+   */
+  it('MAX_SAFE_INTEGER keeps its last digit', () => {
+    // was `9,007,199,254,740,990%` — a 1 turned into a 0
+    expect(formatPercent(Number.MAX_SAFE_INTEGER, 0, 'en-US')).toBe('9,007,199,254,740,991%');
+  });
+
+  it('1e23 renders as 1e23', () => {
+    // was `99,999,999,999,999,990,000,000%`
+    expect(formatPercent(1e23, 0, 'en-US')).toBe('100,000,000,000,000,000,000,000%');
+  });
+});
+
+describe('MUST NOT CHANGE: the locale percent CONVENTION (#4590 is numeral-only)', () => {
+  /**
+   * The affix is what `style: 'percentPoints'` promises to preserve, so this is
+   * the half that proves the fix did not become a convention change. Byte-exact
+   * strings, chosen at a magnitude and precision where no tie is in play — they
+   * are GREEN on both sides of the fix, and a diff here is a STOP condition.
+   */
+  it.each([
+    ['en-US', '1,234.5%'],
+    ['de-DE', `1.234,5${NBSP}%`],
+    ['fr-FR', `1${NNBSP}234,5${NBSP}%`],
+    ['tr-TR', '%1.234,5'], // sign in FRONT
+    ['ar-EG', `\u0661\u066c\u0662\u0663\u0664\u066b\u0665${ARABIC_PERCENT}${ALM}`],
+    ['ja-JP', '1,234.5%'],
+    ['zh-CN', '1,234.5%'],
+    ['ru-RU', `1${NBSP}234,5${NBSP}%`],
+    ['sv-SE', `1${NBSP}234,5${NBSP}%`],
+    ['bn-IN', `\u09e7,\u09e8\u09e9\u09ea.\u09eb%`],
+  ])('%s renders its own percent convention, unchanged', (locale, expected) => {
+    expect(formatPercent(1234.5, 1, locale)).toBe(expected);
+  });
+
+  /**
+   * Sign POSITION and sign GLYPH are convention too — Turkish puts the minus
+   * outside its prefixed percent sign, Arabic leads with U+061C, and Swedish
+   * uses U+2212 MINUS SIGN rather than ASCII hyphen-minus. None of it moves.
+   */
+  it.each([
+    ['en-US', '-45.5%'],
+    ['de-DE', `-45,5${NBSP}%`],
+    ['tr-TR', '-%45,5'],
+    ['ar-EG', `${ALM}-\u0664\u0665\u066b\u0665${ARABIC_PERCENT}${ALM}`],
+    ['sv-SE', `\u221245,5${NBSP}%`],
+  ])('%s keeps its negative-sign convention', (locale, expected) => {
+    expect(formatPercent(-45.5, 1, locale)).toBe(expected);
+  });
+
+  /**
+   * The parity claim asserted rather than trusted: the affix `formatPercent`
+   * now produces must be the one `Intl`'s OWN `style: 'percent'` produces for
+   * the same locale. Comparing the affix alone (digits stripped) is deliberate
+   * — the numerals are exactly what this card moves, so a whole-string compare
+   * would re-assert the defect.
+   */
+  it('the affix is byte-identical to Intl style:percent, for every locale here', () => {
+    const affix = (rendered: string) => rendered.replace(/[\p{Nd}]/gu, '');
+    for (const locale of ['en-US', 'de-DE', 'fr-FR', 'tr-TR', 'ar-EG', 'ja-JP',
+                          'zh-CN', 'ru-RU', 'sv-SE', 'bn-IN']) {
+      const cell = formatPercent(1234.5, 1, locale);
+      const intl = new Intl.NumberFormat(locale, {
+        style: 'percent',
+        minimumFractionDigits: 1,
+        maximumFractionDigits: 1,
+      }).format(12.345);
+      expect(affix(cell), `percent affix for ${locale}`).toBe(affix(intl));
+    }
+  });
+});
+
+describe('MUST NOT CHANGE: percent SCALING is upstream of the render (#4590)', () => {
+  /**
+   * `percentDisplayValue` (a stored fraction below 1 scales by 100, a value at
+   * or above 1 passes through) decides WHICH number gets rendered; this card
+   * changes only HOW that number is rendered. Pinned unmoved so a future reader
+   * cannot mistake the two halves for one.
+   */
+  it('a stored fraction still scales, a stored whole number still does not', () => {
+    expect(formatPercent(0.8, 0, 'en-US')).toBe('80%');
+    expect(formatPercent(0.5, 0, 'en-US')).toBe('50%');
+    expect(formatPercent(0.075, 1, 'en-US')).toBe('7.5%');
+    expect(formatPercent(80, 0, 'en-US')).toBe('80%');
+    expect(formatPercent(100, 0, 'en-US')).toBe('100%');
+    // The boundary itself: 1 is NOT a fraction, so it stays 1%.
+    expect(formatPercent(1, 0, 'en-US')).toBe('1%');
+    // …which is why the tie cases above are authored just above 1.
+    expect(formatPercent(0.9999, 0, 'en-US')).toBe('100%');
+  });
+
+  it('a malformed locale tag still falls back instead of throwing', () => {
+    expect(() => formatPercent(80, 0, 'not a locale')).not.toThrow();
+    expect(formatPercent(80, 0, 'not a locale')).toContain('80');
+  });
+
+  it('is still callable with no locale and no precision', () => {
+    expect(formatPercent(80)).toBe('80%');
+    expect(formatPercent(80, 0)).toBe('80%');
+  });
+});

package/src/__tests__/select-label-association-e2e.test.tsx

@@ -0,0 +1,199 @@
+/**
+ * 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.
+ */
+
+/**
+ * End-to-end: BOTH select paths associate the form's visible label with the
+ * control the user operates (objectui#3976, the built-in half of #3306).
+ *
+ * There are two `select` paths through the form renderer and they do not share
+ * an implementation:
+ *
+ *  - **registered widget** — `type: 'field:select'` (what `mapFieldTypeToFormType`
+ *    emits for object-driven forms) resolves to this package's `SelectField`.
+ *    objectui#3306 moved its DOM pass-through from Radix's `Select.Root` — which
+ *    renders no element and silently drops what it does not recognise — onto
+ *    `SelectTrigger`, the focusable `<button role="combobox">`.
+ *  - **built-in branch** — a hand-written `type: 'select'` never reaches the
+ *    registry at all (`'select'` is a `BUILTIN_FIELD_TYPES` member), so the form
+ *    renderer's own `Select` branch renders it. That branch kept spreading onto
+ *    Root until objectui#3976: the visible label pointed at an id no element
+ *    carried, `getByLabelText` found nothing, and `aria-describedby` /
+ *    `aria-invalid` / `aria-required` never reached the DOM either.
+ *
+ * The paths are pinned side by side, in one file, precisely because the fork is
+ * what caused the bug: #3306 fixed one half and the other silently kept the
+ * defect for as long as nobody wrote a bare `type: 'select'` into a test. The
+ * registered half here is a POSITIVE CONTROL — it must stay green through any
+ * change to the built-in branch.
+ *
+ * The widget is registered raw rather than through `registerAllFields()`, which
+ * wraps every loader in `React.lazy`: an unbounded module load inside a bounded
+ * `findBy`/`waitFor` window is the repo's known flake generator (AGENTS.md
+ * 测试纪律, objectui#3010). Same component, no Suspense boundary.
+ */
+
+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 { SelectField } from '../widgets/SelectField';
+
+const OPTIONS = [
+  { label: 'Alpha', value: 'alpha' },
+  { label: 'Beta', value: 'beta' },
+];
+
+beforeAll(() => {
+  ComponentRegistry.register('select', SelectField as any, {
+    namespace: 'field',
+    skipFallback: true,
+  });
+}, 30000);
+
+beforeEach(() => {
+  if (!(Element.prototype as any).scrollIntoView) {
+    (Element.prototype as any).scrollIntoView = () => {};
+  }
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+/** The real form renderer hosting one field. */
+function renderForm(field: any, defaultValue: unknown = undefined) {
+  const Form = ComponentRegistry.get('form')!;
+  return render(
+    <Form
+      schema={{
+        type: 'form',
+        mode: 'create',
+        showSubmit: true,
+        showCancel: false,
+        submitLabel: 'Create',
+        defaultValues: { [field.name]: defaultValue },
+        fields: [field],
+        onSubmit: () => {},
+      }}
+    />,
+  );
+}
+
+/** Every `<label for=…>` in the document, paired with its resolved target. */
+function labelTargets(): Array<{ text: string; forId: string; resolves: boolean }> {
+  return Array.from(document.querySelectorAll('label'))
+    .map((el) => ({
+      text: (el.textContent ?? '').trim(),
+      forId: el.getAttribute('for') ?? '',
+      resolves: !!el.getAttribute('for') && !!document.getElementById(el.getAttribute('for')!),
+    }))
+    .filter((l) => l.forId !== '');
+}
+
+/** The trigger button, by role — fails loudly if it stops being a combobox. */
+function trigger(name: string): Element {
+  const el = document.querySelector(`[data-field="${name}"] [role="combobox"]`);
+  if (!el) throw new Error(`no select trigger rendered for field "${name}"`);
+  return el;
+}
+
+const submit = () => fireEvent.click(screen.getByRole('button', { name: /create/i }));
+
+/**
+ * The guarantees a select must give whichever path rendered it. Run twice, so
+ * neither path can drift away from the other again.
+ */
+const PATHS = [
+  ['built-in branch (bare `type: select`, objectui#3976)', 'select'],
+  ['registered widget (`field:select`, objectui#3306 — positive control)', 'field:select'],
+] as const;
+
+describe.each(PATHS)('%s', (_label, type) => {
+  const field = { name: 'choice', label: 'Choice', type, options: OPTIONS };
+
+  it('emits no label pointing at an id nothing carries', () => {
+    renderForm(field);
+
+    const labels = labelTargets();
+    expect(labels.length).toBeGreaterThan(0);
+    expect(labels.filter((l) => !l.resolves)).toEqual([]);
+  });
+
+  it('resolves the visible label to the trigger button', () => {
+    renderForm(field);
+
+    // `getAllByLabelText` walks `for`→id, so it guards the association itself:
+    // on the built-in path this used to find NOTHING at all.
+    const labelled = screen.getAllByLabelText('Choice');
+    expect(labelled).toHaveLength(1);
+    expect(labelled[0]).toBe(trigger('choice'));
+    expect(labelled[0].tagName).toBe('BUTTON');
+  });
+
+  it('gives the combobox the label as its accessible name', () => {
+    renderForm(field);
+
+    expect(screen.getByRole('combobox', { name: 'Choice' })).toBe(trigger('choice'));
+  });
+
+  it('carries the required state on the trigger', () => {
+    renderForm({ ...field, required: true });
+
+    expect(trigger('choice')).toHaveAttribute('aria-required', 'true');
+  });
+
+  it('announces invalid on the trigger and links the message', async () => {
+    renderForm({ ...field, required: true }, null);
+
+    // A valid field SAYS it is valid rather than staying mute (#3222/#3306).
+    expect(trigger('choice')).toHaveAttribute('aria-invalid', 'false');
+
+    submit();
+
+    const message = await screen.findByText('Choice is required');
+    await waitFor(() => expect(trigger('choice')).toHaveAttribute('aria-invalid', 'true'));
+    expect(message.id).not.toBe('');
+    const describedBy = trigger('choice').getAttribute('aria-describedby') ?? '';
+    expect(describedBy.split(/\s+/)).toContain(message.id);
+  });
+
+  it('keeps `name` on Root, where the submitted hidden select is', () => {
+    // The whitelist both paths share: `name` is the ONE key Root consumes — it
+    // forwards it to the hidden native `<select>` that takes part in form
+    // submission. On the trigger it would sit uselessly on a non-submitter.
+    renderForm(field);
+
+    expect(document.querySelector('[data-field="choice"] select[aria-hidden="true"]')).toHaveAttribute(
+      'name',
+      'choice',
+    );
+    expect(trigger('choice')).not.toHaveAttribute('name');
+  });
+});
+
+describe('the fork itself (objectui#3976 / #3231)', () => {
+  it('a bare `type: select` renders the BUILT-IN branch even though field:select resolves', () => {
+    // Measured, not inferred — this is the fact that made #3976 a built-in-side
+    // bug rather than a duplicate of #3306: `renderFieldComponent` skips the
+    // registry entirely for a `BUILTIN_FIELD_TYPES` member, so `SelectField` is
+    // NOT what renders a hand-written `type: 'select'`, even here where the real
+    // widget is registered under `field:select`.
+    expect(ComponentRegistry.get('field:select')).toBe(SelectField);
+
+    renderForm({ name: 'choice', label: 'Choice', type: 'select', options: OPTIONS });
+
+    // `SelectField` stamps this locator on the trigger it renders; the built-in
+    // branch does not. Same role, different implementation.
+    expect(document.querySelector('[data-testid="select-trigger-choice"]')).toBeNull();
+    expect(trigger('choice')).toBeInTheDocument();
+  });
+});