From 433d4f3d864cfbee8443182a5549dffe2ca6d711 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 21:17:45 +0000
Subject: [PATCH] =?UTF-8?q?fix(components):=20=E5=86=85=E5=BB=BA=20select?=
 =?UTF-8?q?=20=E5=88=86=E6=94=AF=E6=8A=8A=20host=20id/aria-*=20=E8=90=BD?=
 =?UTF-8?q?=E5=88=B0=E7=9C=9F=E5=AE=9E=20trigger,label=20for=20=E4=B8=8D?=
 =?UTF-8?q?=E5=86=8D=E6=82=AC=E7=A9=BA=20(#3976)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

手写 form schema 里的 `{ name: 'status', label: 'Status', type: 'select', options: [...] }`,
可见的「Status」标签指向一个没有任何元素携带的 id。修前实测(probe,未提交):
`label for="_r_1_-form-item"` 在文档里找不到宿主,`getByLabelText(/status/i)` 0 命中,
trigger 按钮上没有 id、没有 aria-describedby、没有 aria-invalid,连 `required: true`
的 aria-required 也没有 —— 点标签什么都不会发生,屏幕阅读器读到的是一个匿名 combobox:
没有字段名、没有错误消息关联、没有必填状态。

成因是内建 select 分支把整个 DOM pass-through 展开到 Radix `Select.Root`。Root 自己不渲染
任何 DOM 元素,不认识的 prop 被静默丢弃 —— 而 `FormControl`(Radix Slot)下发的
id / aria-describedby / aria-invalid 与调用点下发的 aria-required 全都走这个展开点。
这正是 #3306 在 widget 侧修掉的同一机制(`SelectField` 把 pass-through 落到 `SelectTrigger`);
两条路径分叉是因为 `BUILTIN_FIELD_TYPES` 含 'select':对象驱动的 field:select 解析到注册
widget,而手写的裸 type: 'select' 根本不查注册表,内建分支的同形缺陷一直留着。

修法是抽出 `BuiltinSelectControl`。组件边界不是风格选择而是必要条件:Slot 注入的是分支
返回的那个元素,只有组件才能接住这些 prop 并重新落位(与同文件 `BuiltinSelectEmptyState`
成为组件是同一理由)。pass-through 落到 `SelectTrigger` 渲染的 button[role=combobox],
并保留 #3306 的两个白名单例外:`name` 留在 Root(Root 真正消费的唯一 key,转发给参与表单
提交的隐藏 select),`disabled` 留在 Root(单一权威,同时禁用 trigger / items / 隐藏 select)。
`ref` 随 pass-through 走,内建 select 不再是唯一一个 react-hook-form 无法聚焦的内建控件;
作者写的 className 现在也能到达 trigger(修前它到不了任何元素),与分支自己的触控高度用
cn() 合并而非互相覆盖。渲染哪个组件没有变,只变了 host props 的落点。

双路径各自钉住,互不干扰:

- `packages/components/.../form-builtin-select-host-id.test.tsx`(12 条):内建路径的
  for 解析到 trigger、可访问名、aria-required(必填有/可选无)、aria-invalid 修前 false
  修后 true、aria-describedby 闭合到消息元素 id、name 仍只在 Root(trigger 上没有)、
  disabled 仍由 Root 单一权威、只有 for 没有第二条 aria-labelledby 通道、两个 select
  各自命名;外加分叉钉——注册表里确实存在 field:select 时裸 select 仍走内建分支——
  以及注册 widget 路径拿到 host props 的阳性对照。
- `packages/fields/.../select-label-association-e2e.test.tsx`(13 条):用真
  `SelectField` 把 field:select 与裸 select 并排跑同一组保证(describe.each),
  注册路径是必须保持绿的阳性对照,分叉钉断言 SelectField 的 trigger locator 不出现
  在裸 select 的 DOM 里。

反向验证按预判成立(先写预判再跑,变异未提交):把 pass-through 还原展开到 `Select.Root`
后 13 红 12 绿,与预判逐条一致 —— 红的全是两个文件里内建路径的命名与状态钉,绿的是
name/disabled 留在 Root、两条分叉钉,以及整条 field:select 注册路径(#3306 那半从未
经过 Root)。

同文件的 group labelling 分支(PR #3978)未触碰,diff 不相交;内建 select 的
`resolveFieldLabelling` 仍是 'control',因为 trigger 是可 label 的 button,测试里把
「只有 for、没有 aria-labelledby」钉住了。
---
 .changeset/builtin-select-host-id-3976.md     |  35 +++
 .../form-builtin-select-host-id.test.tsx      | 272 ++++++++++++++++++
 .../components/src/renderers/form/form.tsx    | 133 +++++++--
 .../select-label-association-e2e.test.tsx     | 199 +++++++++++++
 4 files changed, 613 insertions(+), 26 deletions(-)
 create mode 100644 .changeset/builtin-select-host-id-3976.md
 create mode 100644 packages/components/src/renderers/form/__tests__/form-builtin-select-host-id.test.tsx
 create mode 100644 packages/fields/src/__tests__/select-label-association-e2e.test.tsx

diff --git a/.changeset/builtin-select-host-id-3976.md b/.changeset/builtin-select-host-id-3976.md
new file mode 100644
index 0000000000..7c223640c6
--- /dev/null
+++ b/.changeset/builtin-select-host-id-3976.md
@@ -0,0 +1,35 @@
+---
+"@object-ui/components": patch
+---
+
+Built-in `select` fields: the form's label, validation message and required state now reach the control
+
+A hand-written form field `{ name: 'status', label: 'Status', type: 'select', options: [...] }`
+rendered a visible "Status" label that pointed at nothing. Measured before the fix:
+`<label for="…-form-item">` resolved to no element at all, `getByLabelText(/status/i)`
+found zero matches, and the trigger button carried no `id`, no `aria-describedby`, no
+`aria-invalid` and no `aria-required`. Clicking the label did nothing and a screen reader
+announced an anonymous combobox with no field name, no error link and no required state.
+
+Cause: the built-in `select` branch spread its whole DOM pass-through onto Radix's
+`Select.Root`. Root renders no DOM element of its own, so everything it does not
+recognise is silently dropped — and that is exactly where `<FormControl>`'s Slot puts the
+field's `id` / `aria-describedby` / `aria-invalid` and the renderer puts `aria-required`.
+The pass-through now lands on `SelectTrigger`, the focusable `button[role=combobox]` the
+user and their assistive tech actually operate, with the same two keys deliberately kept
+on Root as in the widget-side fix: `name` (the one key Root consumes — it forwards it to
+the hidden native `select` that takes part in form submission) and `disabled` (Root
+disables trigger, items and hidden select together, so the raw prop must not gain a second
+author). `ref` rides the pass-through too, so react-hook-form can finally focus a built-in
+select.
+
+This is the built-in half of the same mechanism objectui#3306 fixed on the widget side.
+The two halves diverged because `'select'` is a `BUILTIN_FIELD_TYPES` member: an
+object-driven `field:select` resolves to the registered `SelectField` (fixed since #3306),
+while a hand-written bare `type: 'select'` never consults the registry and kept the
+defect. Both paths are now pinned side by side — the registered path as a positive control
+— so they cannot drift apart again. Which component renders a bare `select` is unchanged;
+only where its host props land.
+
+Authored `className` on a built-in `select` now reaches the trigger (it previously reached
+no element), composed with the branch's touch-target height rather than replacing it.
diff --git a/packages/components/src/renderers/form/__tests__/form-builtin-select-host-id.test.tsx b/packages/components/src/renderers/form/__tests__/form-builtin-select-host-id.test.tsx
new file mode 100644
index 0000000000..06245ddff0
--- /dev/null
+++ b/packages/components/src/renderers/form/__tests__/form-builtin-select-host-id.test.tsx
@@ -0,0 +1,272 @@
+/**
+ * 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 BUILT-IN `select` branch hands the host's control props to the control it
+ * actually renders — objectui#3976.
+ *
+ * Radix's `Select.Root` renders no DOM element of its own, so every prop it does
+ * not recognise is silently DROPPED instead of reaching an element. The branch
+ * used to spread its whole DOM pass-through onto that Root, which is where
+ * `<FormControl>`'s Slot puts the field's `id` / `aria-describedby` /
+ * `aria-invalid` and the call site puts `aria-required`. Measured before the
+ * fix, for a plain `{ name: 'status', label: 'Status', type: 'select' }`:
+ *
+ *     label for="_r_1_-form-item"   ->  no element carries that id
+ *     getByLabelText(/status/i)     ->  0 matches
+ *     trigger button                ->  no id, no aria-describedby,
+ *                                       no aria-invalid, no aria-required
+ *
+ * i.e. the visible "Status" label pointed at nothing (clicking it did nothing),
+ * the field had no accessible name, and neither the validation message nor the
+ * required state was announced.
+ *
+ * This is the same mechanism objectui#3306 fixed on the WIDGET side, where
+ * `SelectField` now routes its pass-through to `SelectTrigger`. The two `select`
+ * paths diverge because `BUILTIN_FIELD_TYPES` contains `'select'`: a bare
+ * `type: 'select'` renders the built-in branch and never consults the registry,
+ * while an object-driven `field:select` (`mapFieldTypeToFormType`) resolves to
+ * the widget. Only the built-in half was broken, which is why the fork itself is
+ * pinned below — both halves have to keep working independently, and a "fix"
+ * that quietly rerouted bare `select` to the registry would change which
+ * component renders for every hand-written form schema in existence.
+ *
+ * Reverse verification (run before writing the fix, direction predicted first):
+ * restoring the spread onto `<Select>` turns the built-in describe RED — the
+ * label-resolution, accessible-name, aria-required, aria-invalid and
+ * aria-describedby cases all fail — while the registry describe stays GREEN,
+ * because that path never went through Root.
+ */
+
+import { describe, it, expect, beforeAll, afterEach, vi } from 'vitest';
+import { render, screen, fireEvent, waitFor, cleanup } from '@testing-library/react';
+import { ComponentRegistry } from '@object-ui/core';
+// Module scope, not `beforeAll` — the cold transform must not be billed to
+// `hookTimeout`. See object-ui/no-dynamic-import-in-test-hook (objectui#3010).
+import '../../../renderers';
+
+const OPTIONS = [
+  { label: 'Open', value: 'open' },
+  { label: 'Closed', value: 'closed' },
+];
+
+/**
+ * Stands in for a registered option widget (`@object-ui/components` tests never
+ * load `@object-ui/fields`) and mirrors the one mechanism the registry path
+ * relies on: spread the leftover props onto the control it renders. Registered
+ * under the REAL `field:select` key so the fork below is measured, not assumed —
+ * the issue's finding was that the built-in branch wins even when that key
+ * resolves.
+ */
+function SelectWidgetProbe(props: any) {
+  const { name, value: _value, onChange: _onChange, field: _field, error: _error, options: _options, ...rest } = props;
+  return (
+    <button type="button" role="combobox" data-testid={`probe-${name}`} {...rest} />
+  );
+}
+
+beforeAll(() => {
+  ComponentRegistry.register('select', SelectWidgetProbe, { namespace: 'field' });
+}, 30000);
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function renderForm(fields: any[], defaultValues: Record<string, unknown> = {}) {
+  const Form = ComponentRegistry.get('form')!;
+  return render(
+    <Form
+      schema={{
+        type: 'form',
+        mode: 'create',
+        showSubmit: true,
+        showCancel: false,
+        submitLabel: 'Create',
+        defaultValues,
+        fields,
+        onSubmit: () => {},
+      }}
+    />,
+  );
+}
+
+const STATUS_FIELD = { name: 'status', label: 'Status', type: 'select', options: OPTIONS };
+
+/** The trigger button, by role — fails loudly if it stops being a combobox. */
+function triggerOf(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;
+}
+
+/** 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 !== '');
+}
+
+const submit = () => fireEvent.click(screen.getByRole('button', { name: /create/i }));
+
+describe('built-in select — the host id reaches the trigger (objectui#3976)', () => {
+  it('emits no label pointing at an id nothing carries', () => {
+    renderForm([STATUS_FIELD], { status: undefined });
+
+    const labels = labelTargets();
+    expect(labels.length).toBeGreaterThan(0);
+    // The defect verbatim: `for="_r_N_-form-item"` with no owner in the document.
+    expect(labels.filter((l) => !l.resolves)).toEqual([]);
+  });
+
+  it('resolves the visible label to the trigger, not to a wrapper', () => {
+    renderForm([STATUS_FIELD], { status: undefined });
+
+    // `getAllByLabelText` walks `for`→id, so it guards the association itself:
+    // before the fix it returned 0 matches (the id had no owner at all).
+    const labelled = screen.getAllByLabelText('Status');
+    expect(labelled).toHaveLength(1);
+    expect(labelled[0]).toBe(triggerOf('status'));
+    // …and the element carrying the id is the focusable control, not the row.
+    expect(labelled[0].tagName).toBe('BUTTON');
+  });
+
+  it('gives the combobox the label as its accessible name', () => {
+    renderForm([STATUS_FIELD], { status: undefined });
+
+    // The user-visible consequence, asserted on the computed name rather than on
+    // markup: pre-fix the control was reachable by role but ANONYMOUS, so a
+    // screen reader announced "combobox" with no field name.
+    const combobox = screen.getByRole('combobox', { name: 'Status' });
+    expect(combobox).toHaveAccessibleName('Status');
+    expect(combobox).toBe(triggerOf('status'));
+  });
+
+  it('keeps `for` as the association channel — no second naming channel', () => {
+    // The built-in `select` renders a labelable `<button>`, so `resolveFieldLabelling`
+    // correctly classifies it as `'control'` (objectui#3961/#3978): plain `for`,
+    // and NO `aria-labelledby`. Two channels for one label is the failure the
+    // group-labelling work exists to avoid, and this fix must not introduce it.
+    renderForm([STATUS_FIELD], { status: undefined });
+
+    expect(screen.getByText('Status').getAttribute('for')).toBe(
+      triggerOf('status').getAttribute('id'),
+    );
+    expect(triggerOf('status')).not.toHaveAttribute('aria-labelledby');
+  });
+
+  it('carries aria-required on the trigger, and nothing when optional', () => {
+    renderForm([{ ...STATUS_FIELD, required: true }], { status: undefined });
+    expect(triggerOf('status')).toHaveAttribute('aria-required', 'true');
+
+    cleanup();
+    renderForm([STATUS_FIELD], { status: undefined });
+    expect(triggerOf('status')).not.toHaveAttribute('aria-required');
+  });
+
+  it('announces invalid on the trigger only AFTER validation fails', async () => {
+    renderForm([{ ...STATUS_FIELD, required: true }], { status: undefined });
+
+    // The explicit "false" half is load-bearing (#3222/#3306): a valid field
+    // SAYS it is valid rather than staying mute.
+    expect(triggerOf('status')).toHaveAttribute('aria-invalid', 'false');
+
+    submit();
+
+    // Prove the failure actually rendered before reading aria off it.
+    await waitFor(() => expect(screen.getAllByText('Status is required')).toHaveLength(1));
+    expect(triggerOf('status')).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  it('links aria-describedby to the rendered error message', async () => {
+    renderForm([{ ...STATUS_FIELD, required: true }], { status: undefined });
+
+    submit();
+
+    const message = await screen.findByText('Status is required');
+    // The association is only real if the id chain closes: the trigger must
+    // point at the exact element carrying the message text.
+    expect(message.id).not.toBe('');
+    const describedBy = triggerOf('status').getAttribute('aria-describedby') ?? '';
+    expect(describedBy.split(/\s+/)).toContain(message.id);
+  });
+
+  it('leaves `name` on Root, where the submitted hidden select is', () => {
+    // The whitelist half of the fix, and a regression fence against "move
+    // everything to the trigger": `name` is the ONE key Root genuinely 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
+    // `<button>`.
+    renderForm([STATUS_FIELD], { status: undefined });
+
+    const hidden = document.querySelector('[data-field="status"] select[aria-hidden="true"]');
+    expect(hidden).toHaveAttribute('name', 'status');
+    expect(triggerOf('status')).not.toHaveAttribute('name');
+  });
+
+  it('still keeps `disabled` a single-authority prop on Root', () => {
+    // Root disables the trigger, the items and the hidden select together, so
+    // the raw prop must not gain a second author on the trigger.
+    renderForm([{ ...STATUS_FIELD, disabled: true }], { status: undefined });
+
+    expect(triggerOf('status')).toBeDisabled();
+  });
+
+  it('two selects in one form each name their own trigger', () => {
+    renderForm(
+      [STATUS_FIELD, { name: 'stage', label: 'Stage', type: 'select', options: OPTIONS }],
+      { status: undefined, stage: undefined },
+    );
+
+    expect(labelTargets().filter((l) => !l.resolves)).toEqual([]);
+    // A shared/colliding id would make both labels resolve to the same control.
+    expect(screen.getByRole('combobox', { name: 'Status' })).toBe(triggerOf('status'));
+    expect(screen.getByRole('combobox', { name: 'Stage' })).toBe(triggerOf('stage'));
+  });
+});
+
+describe('the two select paths stay separate (objectui#3976 / #3231)', () => {
+  it('a bare `type: select` renders the BUILT-IN branch even though field:select resolves', () => {
+    // Measured, not inferred: `renderFieldComponent` skips the registry entirely
+    // for a `BUILTIN_FIELD_TYPES` member, so the probe registered above under
+    // the real `field:select` key does NOT win. That is why #3976 had to be
+    // fixed in the built-in branch — rerouting bare `select` to the registry is
+    // a design change (it swaps the rendered component for every hand-written
+    // form schema), not a bug fix.
+    expect(ComponentRegistry.get('field:select')).toBe(SelectWidgetProbe);
+
+    renderForm([STATUS_FIELD], { status: undefined });
+
+    expect(screen.queryByTestId('probe-status')).toBeNull();
+    // The Radix trigger + its hidden native select — the built-in branch's DOM.
+    expect(triggerOf('status')).toHaveAttribute('aria-autocomplete', 'none');
+    expect(document.querySelector('[data-field="status"] select[aria-hidden="true"]')).not.toBeNull();
+  });
+
+  it('a registered `field:select` widget still receives the host props (positive control)', () => {
+    // The path #3306 already fixed. It must be untouched by this change: the
+    // widget gets the id / aria-* as PROPS (the Slot clones the element it
+    // returns) and puts them on the control it renders.
+    renderForm(
+      [{ name: 'choice', label: 'Choice', type: 'field:select', required: true, options: OPTIONS }],
+      { choice: undefined },
+    );
+
+    const probe = screen.getByTestId('probe-choice');
+    expect(labelTargets().filter((l) => !l.resolves)).toEqual([]);
+    expect(screen.getByRole('combobox', { name: 'Choice' })).toBe(probe);
+    expect(probe).toHaveAttribute('aria-required', 'true');
+    expect(probe).toHaveAttribute('aria-invalid', 'false');
+    expect(probe.getAttribute('id')).toMatch(/-form-item$/);
+  });
+});
diff --git a/packages/components/src/renderers/form/form.tsx b/packages/components/src/renderers/form/form.tsx
index 271bed5eb9..0adb1f0aa6 100644
--- a/packages/components/src/renderers/form/form.tsx
+++ b/packages/components/src/renderers/form/form.tsx
@@ -23,7 +23,7 @@ import {
   SelectItem 
 } from '../../ui/select';
 import { renderChildren } from '../../lib/utils';
-import { toControlValue, matchOptionValue } from './option-value';
+import { toControlValue, matchOptionValue, type OptionValue } from './option-value';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '../../ui/tabs';
 import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '../../custom/resizable';
 import { Alert, AlertDescription } from '../../ui/alert';
@@ -2198,6 +2198,101 @@ function BuiltinSelectEmptyState({
   );
 }
 
+/**
+ * The built-in (unregistered) `select` branch's control — objectui#3976.
+ *
+ * Radix's `Select.Root` renders NO DOM element of its own, so every prop it does
+ * not recognise is silently DROPPED instead of reaching an element. The branch
+ * used to spread its whole DOM pass-through onto that Root, which is where
+ * `<FormControl>`'s Slot puts the field's `id` / `aria-describedby` /
+ * `aria-invalid` and the call site puts `aria-required` — so a bare
+ * `{ type: 'select' }` rendered a visible `<FormLabel for="…-form-item">`
+ * pointing at an id NO element carried: the label was inert (clicking it did
+ * nothing) and the field had no accessible name, no error link and no required
+ * state at all.
+ *
+ * This is the exact mechanism objectui#3306 fixed on the WIDGET side
+ * (`SelectField` routes its pass-through to `SelectTrigger`); the built-in
+ * branch never followed, and the two `select` paths diverge because
+ * `BUILTIN_FIELD_TYPES` contains `'select'` — so a bare `type: 'select'` never
+ * consults the registry while an object-driven `field:select` does.
+ *
+ * A component (rather than inline JSX in the branch) is what makes the fix
+ * possible at all: the Slot injects into whatever ELEMENT the branch returns, so
+ * only a component boundary can receive those props and re-address them. Same
+ * reason `BuiltinSelectEmptyState` above is a component.
+ *
+ * The pass-through lands on `SelectTrigger` — the focusable
+ * `<button role="combobox">` the user and their screen reader actually interact
+ * with — with the same two deliberate exceptions #3306 kept on Root:
+ *
+ *  - `name`: the one key Root genuinely 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 `<button>`.
+ *  - `disabled`: Root is the single authority (it disables trigger, items and
+ *    the hidden select together), so the raw prop must not get a second author.
+ *
+ * `ref` rides the pass-through for the same reason the `aria-*` do: react-hook-form
+ * hands every field a `ref` and this branch dropped it on Root, so the built-in
+ * select was the one built-in control RHF could not focus. Forwarded here to the
+ * trigger, exactly like `input`/`textarea` hand theirs to a real element.
+ */
+type BuiltinSelectControlProps = {
+  options: SelectOption[];
+  placeholder?: string;
+  /** The AUTHORED value — stringified for Radix on the way in (#3090). */
+  value?: OptionValue | null;
+  /** Receives the AUTHORED option value, not Radix's string (#3090). */
+  onValueChange?: (next: OptionValue) => void;
+  disabled?: boolean;
+} & Omit<
+  React.ComponentPropsWithoutRef<typeof SelectTrigger>,
+  'value' | 'onValueChange' | 'disabled' | 'children'
+>;
+
+const BuiltinSelectControl = React.forwardRef<HTMLButtonElement, BuiltinSelectControlProps>(
+  function BuiltinSelectControl(
+    { options, placeholder, value, onValueChange, disabled, name, className, ...triggerDomProps },
+    ref,
+  ) {
+    return (
+      // Radix speaks strings: stringify going in, map the selection back to
+      // the AUTHORED option value coming out, so a numeric/boolean option
+      // round-trips typed instead of morphing to "2" in the payload (#3090).
+      <Select
+        name={name}
+        value={toControlValue(value)}
+        onValueChange={(v) => onValueChange?.(matchOptionValue(options, v))}
+        disabled={disabled}
+      >
+        <SelectTrigger
+          ref={ref}
+          {...triggerDomProps}
+          // `cn`-merged rather than spread-ordered: an authored `className` must
+          // be able to override the touch-target height without deleting it by
+          // accident, and this prop reached no element before the fix.
+          className={cn('min-h-[44px] sm:min-h-0', className)}
+        >
+          {/* No `|| 'Select an option'` — objectui#3272. The single call site
+              already supplies `t('common.selectOption')` for `select`, so the
+              literal was all but unreachable; the ONE stack that did reach it
+              was an authored `placeholder: ''` (the call site's `??` keeps an
+              empty string), where a second fallback overrode the author's
+              explicit blank with an untranslated English word. */}
+          <SelectValue placeholder={placeholder} />
+        </SelectTrigger>
+        <SelectContent>
+          {options.map((opt: SelectOption) => (
+            <SelectItem key={String(opt.value)} value={String(opt.value)}>
+              {opt.label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    );
+  },
+);
+
 function renderFieldComponent(type: string, props: RenderFieldProps) {
   // 1. Try to resolve specialized field widget from registry first.
   //    Form fields should always prefer the `field:<type>` namespace when
@@ -2372,33 +2467,19 @@ function renderFieldComponent(type: string, props: RenderFieldProps) {
         return <BuiltinSelectEmptyState emptyHint={emptyHint} />;
       }
 
+      // The DOM pass-through goes to the CONTROL, not to Radix's element-less
+      // Root (objectui#3976) — see `BuiltinSelectControl`. Spread first so the
+      // branch's own computations below win over anything the host forwarded,
+      // the #3222 discipline.
       return (
-        // Radix speaks strings: stringify going in, map the selection back to
-        // the AUTHORED option value coming out, so a numeric/boolean option
-        // round-trips typed instead of morphing to "2" in the payload (#3090).
-        <Select
-          value={toControlValue(selectValue)}
-          onValueChange={(v) => selectOnChange?.(matchOptionValue(options, v))}
-          disabled={selDisabled || readonly}
+        <BuiltinSelectControl
           {...selectProps}
-        >
-          <SelectTrigger className="min-h-[44px] sm:min-h-0">
-            {/* No `|| 'Select an option'` — objectui#3272. The single call site
-                already supplies `t('common.selectOption')` for `select`, so the
-                literal was all but unreachable; the ONE stack that did reach it
-                was an authored `placeholder: ''` (the call site's `??` keeps an
-                empty string), where a second fallback overrode the author's
-                explicit blank with an untranslated English word. */}
-            <SelectValue placeholder={placeholder} />
-          </SelectTrigger>
-          <SelectContent>
-            {options.map((opt: SelectOption) => (
-              <SelectItem key={String(opt.value)} value={String(opt.value)}>
-                {opt.label}
-              </SelectItem>
-            ))}
-          </SelectContent>
-        </Select>
+          options={options}
+          placeholder={placeholder}
+          value={selectValue}
+          onValueChange={selectOnChange}
+          disabled={selDisabled || readonly}
+        />
       );
     }
 
diff --git a/packages/fields/src/__tests__/select-label-association-e2e.test.tsx b/packages/fields/src/__tests__/select-label-association-e2e.test.tsx
new file mode 100644
index 0000000000..269d5d2a1f
--- /dev/null
+++ b/packages/fields/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();
+  });
+});