From bd29672faf5c8aea2c8a2e6143bbd2e78038fd99 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Mon, 10 Aug 2026 00:15:48 +0000
Subject: [PATCH] fix(fields): resolve select + multiple to field:multiselect
 so its host label names the chip group

`mapFieldTypeToFormType` keyed the widget id on the field `type` string alone,
so an object-schema `{ type: 'select', multiple: true }` picklist became
`field:select`. `SelectField` then delegated to `MultiSelectField` on
`config.multiple`: the component that RENDERED was the chip picker, while
everything keyed on the widget id still answered for the single-value combobox
-- above all the label-association declaration (`ComponentMeta.labelling`,
objectui#3961), which the form renderer resolves per widget id. The host emitted
`label for` at the chip row's wrapper div, where a `for` is inert
(`HTMLLabelElement.control` is null): a visible label naming nothing.

Declaring `select` itself `labelling: 'group'` was not available -- a
single-value select's trigger is a labelable `button[role=combobox]` whose `for`
works, and a bare `select` is a builtin the renderer resolves without the
registry. So the producer names the widget that renders: the id now carries the
arity, and declaration and render can no longer diverge.

- `mapFieldTypeToFormType(fieldType, config?)` gains an optional second
  argument; only `multiple` is read. Single-argument calls are unchanged. The
  override is table-driven and `select` is its only member: the spec's
  multi-capable set is larger (select / lookup / file / image, `radio` on the
  select branch, `user` storing like `lookup`), but LookupField, FileField and
  ImageField each render both arities themselves, so their id -- and their
  labelling declaration -- is already right either way.
- The four object-form producers pass the pair: ObjectForm, DrawerForm,
  ModalForm, sectionFields. In sectionFields the id is computed once from the
  EFFECTIVE pair after view-level overrides merge, because `multiple` is itself
  a spec FormField key: a view restating only `multiple: true` moves the widget
  too, and `multiple: false` moves it back.
- SelectField's delegation is KEPT, not retired. Measured, three entrances
  still reach it with `multiple` set, none of which consult the alias map: the
  inline grid editor (FieldEditWidget finds `select` in its own table first),
  ActionParamDialog (resolveFormWidgetType returns `select` from
  fieldWidgetMap first), and hand-written SDUI naming `field:select`.

Read-only rendering is untouched (objectui#4005); so is the built-in `Select`
branch (objectui#3976).

Fixes #3986

Co-authored-by: Claude <noreply@anthropic.com>
---
 .../select-multiple-widget-mapping-3986.md    |  16 +
 .../group-labelling-declaration.test.ts       |  37 ++-
 .../src/field-type-alias.multiple.test.ts     |  81 +++++
 packages/fields/src/field-type-alias.ts       |  60 +++-
 packages/fields/src/widgets/SelectField.tsx   |  30 +-
 packages/plugin-form/src/DrawerForm.tsx       |   3 +-
 packages/plugin-form/src/ModalForm.tsx        |   3 +-
 packages/plugin-form/src/ObjectForm.tsx       |   6 +-
 .../selectMultipleGroupLabel.test.tsx         | 282 ++++++++++++++++++
 packages/plugin-form/src/sectionFields.ts     |  20 +-
 10 files changed, 525 insertions(+), 13 deletions(-)
 create mode 100644 .changeset/select-multiple-widget-mapping-3986.md
 create mode 100644 packages/fields/src/field-type-alias.multiple.test.ts
 create mode 100644 packages/plugin-form/src/__tests__/selectMultipleGroupLabel.test.tsx

diff --git a/.changeset/select-multiple-widget-mapping-3986.md b/.changeset/select-multiple-widget-mapping-3986.md
new file mode 100644
index 0000000000..b3b5681dd2
--- /dev/null
+++ b/.changeset/select-multiple-widget-mapping-3986.md
@@ -0,0 +1,16 @@
+---
+'@object-ui/fields': patch
+'@object-ui/plugin-form': patch
+---
+
+Resolve a `select` field declared `multiple: true` to the `field:multiselect` widget, so the object form's visible label actually names the chip picker it renders (objectui#3986).
+
+`mapFieldTypeToFormType` keyed the widget id on the field's `type` string alone, so an object-schema `{ type: 'select', multiple: true }` picklist — a spec-legal, entirely ordinary shape — became `field:select`. `SelectField` then delegated to `MultiSelectField` on `config.multiple`, so the component that RENDERED was the chip picker while everything keyed on the widget id still answered for the single-value combobox. Above all the label-association declaration (`ComponentMeta.labelling`, objectui#3961), which the form renderer resolves per widget id: the host emitted `<label for>` at the chip row's wrapper `div`, where a `for` is inert — `HTMLLabelElement.control` returns `null`. Visually the field had a label; in the accessibility tree that label named nothing. Measured on the object-form path, `role=group` + accessible name went from 1 for a `multiselect`-typed field (fixed in objectui#3975) to 0 for this one.
+
+Declaring `select` itself `labelling: 'group'` was not available: a single-value select's trigger is a labelable `button[role=combobox]` whose `for` association works, and a bare `select` is a builtin the renderer resolves without consulting the registry at all. The fix is therefore at the producer — the widget id now carries the arity, so one place decides which widget renders and the declaration can no longer be addressed to a widget that is not rendering.
+
+- `mapFieldTypeToFormType(fieldType, config?)` takes an optional second argument — the rest of the field definition, of which only `multiple` is read. Existing single-argument calls are unchanged, and so is every type outside the new table: `select` is the only one whose `multiple` form is a different WIDGET. The spec's multi-capable set is larger (select / lookup / file / image, with `radio` on the select branch and `user` storing like `lookup`), but `LookupField`, `FileField` and `ImageField` each render both arities themselves, so their id — and their labelling declaration — is already right for either.
+- The four object-form producers pass the pair: `ObjectForm`, `DrawerForm`, `ModalForm`, and `sectionFields` (Tabbed / Wizard / Split / Drawer / Modal). In `sectionFields` the id is now computed once from the EFFECTIVE pair, after view-level overrides have merged, because `multiple` is itself a spec `FormField` key: a view restating only `multiple: true` over a single-value object field moves the widget too, and `multiple: false` moves it back.
+- `SelectField`'s `multiple` delegation is KEPT, not retired. Measured, it stays reachable from three entrances that never consult the alias map: the inline grid editor (`FieldEditWidget` finds `select` in its own table first), `ActionParamDialog` (`resolveFormWidgetType` returns `select` from `fieldWidgetMap` first), and hand-written SDUI addressing `field:select` by name with `multiple` on its metadata.
+
+Read-only rendering of these widgets is untouched (objectui#4005), as is the built-in `Select` branch (objectui#3976).
diff --git a/packages/fields/src/__tests__/group-labelling-declaration.test.ts b/packages/fields/src/__tests__/group-labelling-declaration.test.ts
index 1c3c9f87d5..5269986428 100644
--- a/packages/fields/src/__tests__/group-labelling-declaration.test.ts
+++ b/packages/fields/src/__tests__/group-labelling-declaration.test.ts
@@ -31,7 +31,7 @@
 
 import { describe, it, expect, beforeAll } from 'vitest';
 import { ComponentRegistry } from '@object-ui/core';
-import { registerAllFields } from '../index';
+import { registerAllFields, mapFieldTypeToFormType } from '../index';
 
 /**
  * Every field type whose host label must be associated by IDREF. Two shapes, one
@@ -111,3 +111,38 @@ describe('field widgets declare how their label must be associated (objectui#396
     expect(declared).toEqual([...GROUP_LABELLED].sort());
   });
 });
+
+/**
+ * The join between the two halves (objectui#3986). The declaration above is
+ * per-WIDGET; a form asks for a widget by the id its producer emitted. So the
+ * declaration only reaches the right widget if the producer names the widget that
+ * will actually render — and for `select` that depends on `multiple`, not on the
+ * type string alone.
+ *
+ * Asserting the pair here, rather than in either half alone, is what makes the
+ * failure visible: `mapFieldTypeToFormType`'s own test cannot know what
+ * `labelling` the id it returns carries, and the declaration test cannot know
+ * which id a `multiple: true` select resolves to. The gap between those two blind
+ * spots is exactly where this bug lived.
+ */
+describe('the widget id the object form emits carries the right declaration (objectui#3986)', () => {
+  const labellingOf = (formType: string) =>
+    ComponentRegistry.getMeta(formType.replace(/^field:/, ''), 'field')?.labelling;
+
+  it('select + multiple resolves to a widget declared `group`', () => {
+    // Before the producer fix this resolved to `field:select`, whose declaration
+    // is (correctly) absent — so the host kept emitting a `for` at the chip row's
+    // wrapper `div`, and the visible label named nothing.
+    const formType = mapFieldTypeToFormType('select', { multiple: true });
+    expect(formType).toBe('field:multiselect');
+    expect(labellingOf(formType)).toBe('group');
+  });
+
+  it('a single-value select still resolves to an UNDECLARED widget', () => {
+    // The guard direction. `select`'s trigger is a labelable
+    // `button[role=combobox]`; declaring it `group` would strip a working `for`.
+    const formType = mapFieldTypeToFormType('select');
+    expect(formType).toBe('field:select');
+    expect(labellingOf(formType)).toBeUndefined();
+  });
+});
diff --git a/packages/fields/src/field-type-alias.multiple.test.ts b/packages/fields/src/field-type-alias.multiple.test.ts
new file mode 100644
index 0000000000..cdddc55dcb
--- /dev/null
+++ b/packages/fields/src/field-type-alias.multiple.test.ts
@@ -0,0 +1,81 @@
+/**
+ * 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 widget id is a function of the (type, `multiple`) PAIR, not of the type
+ * string alone (objectui#3986).
+ *
+ * `mapFieldTypeToFormType` mapped `select` to `field:select` unconditionally,
+ * while `SelectField` delegated to `MultiSelectField` whenever the metadata said
+ * `multiple`. Three correct pieces, one gap between them: the component that
+ * RENDERED was `MultiSelectField`, but everything keyed on the widget id — above
+ * all the label-association declaration (`ComponentMeta.labelling`, resolved via
+ * `getMeta('select')`) — was still answering for the single-value combobox. The
+ * host label of a normal `{ type: 'select', multiple: true }` picklist therefore
+ * emitted a `for` at the chip row's wrapper `div`, where a `for` is inert.
+ *
+ * `select` cannot simply be declared `labelling: 'group'` instead: the
+ * single-value trigger IS labelable, and a bare `select` is a builtin the form
+ * renderer resolves without the registry at all (pinned in
+ * `form-group-label-association.test.ts`). The producer has to name the widget
+ * that renders, which is what this file pins.
+ *
+ * Metadata only — nothing renders here, so no widget module is loaded.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { mapFieldTypeToFormType } from './field-type-alias';
+
+describe('select carries its arity in the widget id (objectui#3986)', () => {
+  it('maps select + multiple to the multi-value widget', () => {
+    // The one assertion that was `field:select` before this change.
+    expect(mapFieldTypeToFormType('select', { multiple: true })).toBe('field:multiselect');
+  });
+
+  it('keeps the single-value widget without multiple, and for multiple: false', () => {
+    // The guard direction: single-select must not move. Its trigger is a
+    // labelable `button[role=combobox]` and its `for` association works — taking
+    // that away would break a field that is fine to fix one that is not.
+    expect(mapFieldTypeToFormType('select')).toBe('field:select');
+    expect(mapFieldTypeToFormType('select', {})).toBe('field:select');
+    expect(mapFieldTypeToFormType('select', { multiple: false })).toBe('field:select');
+    expect(mapFieldTypeToFormType('select', { multiple: null })).toBe('field:select');
+  });
+
+  it('is idempotent for the type that is already inherently multi', () => {
+    // `multiselect` is a type in its own right; the arity override must not turn
+    // it into something else, whichever way the flag is set.
+    expect(mapFieldTypeToFormType('multiselect')).toBe('field:multiselect');
+    expect(mapFieldTypeToFormType('multiselect', { multiple: true })).toBe('field:multiselect');
+  });
+
+  /**
+   * The spec's multi-capable set is larger than the widget-moving set, and the
+   * difference is the whole reason this override is table-driven rather than a
+   * `config.multiple` branch sprinkled per type:
+   *
+   *   `MULTI_CAPABLE_TYPES` = select / lookup / file / image (+ `radio` on the
+   *   select branch, `user` storing like `lookup`)
+   *
+   * Every member except `select` renders BOTH arities inside one widget —
+   * `LookupField`, `FileField`, `ImageField` each read `multiple` themselves — so
+   * their widget id, and with it their `labelling` declaration, is correct for
+   * either arity. Moving them would point at widgets that do not exist.
+   */
+  const UNMOVED_MULTI_CAPABLE = ['lookup', 'master_detail', 'user', 'owner', 'file', 'image', 'radio'] as const;
+
+  it.each(UNMOVED_MULTI_CAPABLE)('%s resolves identically with and without multiple', (type) => {
+    expect(mapFieldTypeToFormType(type, { multiple: true })).toBe(mapFieldTypeToFormType(type));
+  });
+
+  it('does not invent a widget for an unknown type flagged multiple', () => {
+    // The fallback is unchanged: an unknown type is `field:text` at either arity,
+    // never `field:text-multiple`-anything.
+    expect(mapFieldTypeToFormType('something-unknown', { multiple: true })).toBe('field:text');
+  });
+});
diff --git a/packages/fields/src/field-type-alias.ts b/packages/fields/src/field-type-alias.ts
index aae9e88035..2387660637 100644
--- a/packages/fields/src/field-type-alias.ts
+++ b/packages/fields/src/field-type-alias.ts
@@ -6,15 +6,63 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/**
+ * The slice of a field definition the widget decision reads beyond `type`.
+ *
+ * Structural (not the spec `Field`) for the same reason the spec's own
+ * `ValueShapeFieldDef` is: every caller — object-schema metadata, a spec
+ * `FormFieldSchema` override, an action param def — can pass its own trimmed
+ * shape verbatim. `multiple` is the only key read; nothing else here is
+ * consulted, so a caller that has the whole metadata object may hand it over
+ * as-is.
+ */
+export interface FieldTypeMappingConfig {
+  /** `FieldSchema.multiple` — the field holds zero-or-more values. */
+  multiple?: boolean | null;
+}
+
+/**
+ * Field types whose `multiple: true` form is a DIFFERENT registered widget,
+ * rather than the same widget in another mode (objectui#3986).
+ *
+ * `select` is the only member, and the narrowness is measured, not assumed. The
+ * spec's `MULTI_CAPABLE_TYPES` is larger — select / lookup / file / image, with
+ * `radio` on the select branch and `user` storing like `lookup` — but every
+ * other member renders both arities INSIDE one widget: `LookupField`,
+ * `FileField` and `ImageField` each branch on `multiple` themselves, so their
+ * registry id, and with it their `labelling` declaration, is the same either
+ * way. A `select` declared `multiple: true` renders `MultiSelectField` instead:
+ * a different component, whose labelled surface is a chip row's container that
+ * a `<label for>` cannot address (it must be named by IDREF, which is what
+ * `field:multiselect`'s `labelling: 'group'` declares — objectui#3975/#3961).
+ *
+ * So the widget id has to carry the arity. When it did not, the host label was
+ * associated by the declaration registered under `select` — a single-value
+ * combobox that was NOT rendering — and the visible label of a normal
+ * `{ type: 'select', multiple: true }` picklist named nothing at all. One place
+ * decides which widget renders, so the declaration and the render cannot
+ * disagree again.
+ */
+const MULTI_VALUE_FORM_TYPES: Record<string, string> = {
+  select: 'field:multiselect',
+};
+
 /**
  * Map field type to form component type
- * 
+ *
  * @param fieldType - The ObjectQL field type identifier to convert
  * (for example: `"text"`, `"number"`, `"date"`, `"lookup"`).
+ * @param config - The rest of the field definition, for the types whose widget
+ * identity depends on more than the type string. Only `multiple` is read; see
+ * {@link MULTI_VALUE_FORM_TYPES}. Omitting it maps the single-value form, which
+ * is what every non-multi-capable type resolves to anyway.
  * @returns The normalized form field type string used in the form schema
  * (for example: `"input"`, `"textarea"`, `"date-picker"`, `"select"`).
  */
-export function mapFieldTypeToFormType(fieldType: string): string {
+export function mapFieldTypeToFormType(
+  fieldType: string,
+  config?: FieldTypeMappingConfig,
+): string {
   const typeMap: Record<string, string> = {
     // Text-based fields
     text: 'field:text',
@@ -96,5 +144,13 @@ export function mapFieldTypeToFormType(fieldType: string): string {
     auto_number: 'field:auto_number',
   };
 
+  // The arity override comes FIRST and is table-driven: only a type listed in
+  // `MULTI_VALUE_FORM_TYPES` has a second widget to move to, so `multiple` on
+  // any other type (a multi `lookup`, a multi `file`) resolves exactly as
+  // before and keeps reaching the widget that handles both arities itself.
+  if (config?.multiple && MULTI_VALUE_FORM_TYPES[fieldType]) {
+    return MULTI_VALUE_FORM_TYPES[fieldType];
+  }
+
   return typeMap[fieldType] || 'field:text';
 }
diff --git a/packages/fields/src/widgets/SelectField.tsx b/packages/fields/src/widgets/SelectField.tsx
index ef0dc4300e..b5c06832eb 100644
--- a/packages/fields/src/widgets/SelectField.tsx
+++ b/packages/fields/src/widgets/SelectField.tsx
@@ -21,11 +21,31 @@ import { useCascadingOptions } from './useCascadingOptions';
  *
  * A field declared `multiple: true` selects zero-or-more values (spec:
  * `multiple` is valid on `select`), so it renders the multi-value chip picker
- * — the same widget the `multiselect` type uses. Delegating here (rather than
- * only at a type-resolution layer) means every surface that renders the
- * `select` widget — the object form, the inline grid editor, and
- * `ActionParamDialog` — inherits multi-select identically, with no drift
- * between them. Single-value selects keep the cascading dropdown below.
+ * — the same widget the `multiselect` type uses. Single-value selects keep the
+ * cascading dropdown below.
+ *
+ * The FORM no longer arrives here with `multiple` (objectui#3986):
+ * `mapFieldTypeToFormType` now resolves a `select` + `multiple: true` field to
+ * `field:multiselect`, so the object-form path renders `MultiSelectField`
+ * directly under its own registry id — which is what carries the
+ * `labelling: 'group'` declaration the host label needs. Deciding the widget at
+ * the type-resolution layer is what keeps the declaration and the render from
+ * disagreeing; a delegation invisible to the resolver could not.
+ *
+ * The branch below stays because it is NOT dead — measured entrances that reach
+ * it with `multiple` set, none of which consult that resolver:
+ *
+ *  - **the inline grid editor** — `FieldEditWidget` looks `select` up in its own
+ *    `EDIT_WIDGETS` table, which SHORT-CIRCUITS before the alias map is
+ *    consulted, and forwards the whole metadata object as `field`;
+ *  - **`ActionParamDialog`** — `paramToField` resolves through
+ *    `resolveFormWidgetType`, which likewise returns `select` from
+ *    `fieldWidgetMap` before reaching the alias map, and carries
+ *    `multiple: param.multiple` on the field it builds;
+ *  - **hand-written SDUI** — a `{ type: 'field:select' }` node whose metadata
+ *    declares `multiple`, which addresses this widget by name.
+ *
+ * All three then inherit multi-select from here identically, with no drift.
  *
  * Both branches resolve per-option `visibleWhen` cascading / role-gating through
  * the shared {@link useCascadingOptions} hook (#2715), so single and multi stay
diff --git a/packages/plugin-form/src/DrawerForm.tsx b/packages/plugin-form/src/DrawerForm.tsx
index a94f1e8224..b41f225a3a 100644
--- a/packages/plugin-form/src/DrawerForm.tsx
+++ b/packages/plugin-form/src/DrawerForm.tsx
@@ -322,7 +322,8 @@ export const DrawerForm: React.FC<DrawerFormProps> = ({
       generated.push({
         name,
         label: fieldLabel(schema.objectName, name, field.label || name),
-        type: mapFieldTypeToFormType(field.type),
+        // (type, multiple) decides the widget (objectui#3986) — see `sectionFields`.
+        type: mapFieldTypeToFormType(field.type, { multiple: field.multiple }),
         required: field.required || false,
         disabled: schema.readOnly || schema.mode === 'view' || field.readonly,
         placeholder: field.placeholder,
diff --git a/packages/plugin-form/src/ModalForm.tsx b/packages/plugin-form/src/ModalForm.tsx
index 0e9f23a38f..6a43a9f316 100644
--- a/packages/plugin-form/src/ModalForm.tsx
+++ b/packages/plugin-form/src/ModalForm.tsx
@@ -395,7 +395,8 @@ export const ModalForm: React.FC<ModalFormProps> = ({
       generated.push({
         name,
         label: fieldLabel(schema.objectName, name, field.label || name),
-        type: mapFieldTypeToFormType(field.type),
+        // (type, multiple) decides the widget (objectui#3986) — see `sectionFields`.
+        type: mapFieldTypeToFormType(field.type, { multiple: field.multiple }),
         required: field.required || false,
         disabled: schema.readOnly || schema.mode === 'view' || field.readonly,
         placeholder: field.placeholder,
diff --git a/packages/plugin-form/src/ObjectForm.tsx b/packages/plugin-form/src/ObjectForm.tsx
index aad1433e43..80e5a9104b 100644
--- a/packages/plugin-form/src/ObjectForm.tsx
+++ b/packages/plugin-form/src/ObjectForm.tsx
@@ -564,7 +564,11 @@ const SimpleObjectForm: React.FC<ObjectFormProps> = ({
         const formField: FormField = {
           name: name,
           label: fieldLabel(schema.objectName, name, field.label || fieldName),
-          type: mapFieldTypeToFormType(field.type),
+          // (type, multiple) decides the widget, not the type alone: a `select`
+          // declared `multiple: true` renders the multi-value chip picker, whose
+          // label must be associated by IDREF — a fact declared per WIDGET, so
+          // the widget id has to carry the arity (objectui#3986).
+          type: mapFieldTypeToFormType(field.type, { multiple: field.multiple }),
           required: field.required || false,
           disabled: schema.readOnly || schema.mode === 'view' || field.readonly || managedBlanketLock,
           placeholder: field.placeholder,
diff --git a/packages/plugin-form/src/__tests__/selectMultipleGroupLabel.test.tsx b/packages/plugin-form/src/__tests__/selectMultipleGroupLabel.test.tsx
new file mode 100644
index 0000000000..b047a74aab
--- /dev/null
+++ b/packages/plugin-form/src/__tests__/selectMultipleGroupLabel.test.tsx
@@ -0,0 +1,282 @@
+/**
+ * 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: a `{ type: 'select', multiple: true }` field in a real object form
+ * is NAMED by its visible label (objectui#3986).
+ *
+ * Everything below is real — the real `ObjectForm` (the producer that emits the
+ * widget id), the real `mapFieldTypeToFormType`, the real form renderer in
+ * `@object-ui/components`, the real registry, and the real widgets from
+ * `@object-ui/fields`. Only the data source is stubbed. That is deliberate: the
+ * bug lived in the SEAM between four independently-correct pieces, so a unit test
+ * on any one of them stays green through it. Measured on the tree that already
+ * had #3975's fix live, one field per row:
+ *
+ * ```
+ * type: 'multiselect'                   → byRoleGroupNamed=1  role=group   ← #3975
+ * type: 'select', multiple: true        → for=…-form-item resolves to div
+ *                                         byRoleGroupNamed=0  byLabelText=0  ← #3986
+ * ```
+ *
+ * The mechanism: the producer keyed the widget id on the type string only, so it
+ * emitted `field:select`; `SelectField` then delegated to `MultiSelectField` on
+ * `config.multiple`. The component that rendered was the chip picker, but the
+ * label-association declaration the renderer consulted was the one registered
+ * under `select` — which must stay undeclared, because a single-value select's
+ * trigger is labelable and stripping its `for` would break a working field
+ * (pinned in `form-group-label-association.test.ts`: "a BUILTIN type ignores a
+ * registry declaration under the same name"). So the host emitted a `for` at the
+ * chip row's wrapper `div`, where `<label for>` is inert —
+ * `HTMLLabelElement.control` is `null`: a visible label, and no accessible name.
+ *
+ * `registerAllFields` registers each widget as a `React.lazy`, so the assertions
+ * sit behind a dynamic-import boundary — warmed at MODULE SCOPE, never in a
+ * `beforeAll` (AGENTS.md 测试纪律, objectui#3010). The `@object-ui/fields` barrel
+ * import below IS the warm-up: it statically re-exports `./widgets/SelectField`
+ * and `./widgets/MultiSelectField`, the very specifiers the lazy loaders use, so
+ * `React.lazy` resolves off the ESM cache instead of racing RTL's 1000ms budget
+ * against a cold Vite transform.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { registerAllFields, mapFieldTypeToFormType } from '@object-ui/fields';
+import type { ObjectFormSchema } from '@object-ui/types';
+import { ObjectForm } from '../ObjectForm';
+import { normalizeSectionField } from '../sectionFields';
+
+registerAllFields();
+
+const OPTIONS = [
+  { label: 'Alpha', value: 'a' },
+  { label: 'Beta', value: 'b' },
+];
+
+/**
+ * One object, three option fields — the subject, the already-fixed sibling, and
+ * the guard direction — so a change that "fixes" the first by breaking the third
+ * cannot pass.
+ */
+const objectSchema = {
+  name: 'crm_account',
+  label: 'Account',
+  fields: {
+    // The subject: spec-legal `multiple` on a `select` (#3986).
+    regions: { type: 'select', multiple: true, label: 'Regions', options: OPTIONS },
+    // The sibling that #3975 already fixed — a positive control for the whole
+    // group-labelling chain, on a DIFFERENT type.
+    tags: { type: 'multiselect', label: 'Tags', options: OPTIONS },
+    // The guard: a single-value select, whose `for`→trigger association works
+    // today and must survive untouched.
+    stage: { type: 'select', label: 'Stage', options: OPTIONS },
+  },
+};
+
+function makeDataSource(schema: object = objectSchema) {
+  return {
+    getObjectSchema: vi.fn().mockResolvedValue(schema),
+    findOne: vi.fn(),
+    insert: vi.fn(),
+    update: vi.fn(),
+    find: vi.fn().mockResolvedValue([]),
+  } as any;
+}
+
+function renderObjectForm(fields?: string[]) {
+  return render(
+    <ObjectForm
+      schema={
+        {
+          type: 'object-form',
+          objectName: objectSchema.name,
+          mode: 'create',
+          ...(fields ? { fields } : {}),
+        } as ObjectFormSchema
+      }
+      dataSource={makeDataSource()}
+    />,
+  );
+}
+
+/** HTML's labelable elements — the only ones a `<label for>` can address. */
+const LABELABLE = new Set(['button', 'input', 'meter', 'output', 'progress', 'select', 'textarea']);
+
+/**
+ * Every `<label for=…>` in the document, with what it resolves to and whether that
+ * target can legally be labelled. This issue's shape is `resolves: true` +
+ * `labelable: false` — the association that looks fine in the markup and names
+ * nothing in the accessibility tree.
+ */
+function labelTargets(): Array<{ text: string; forId: string; resolves: boolean; labelable: boolean }> {
+  return Array.from(document.querySelectorAll('label'))
+    .map((el) => {
+      const forId = el.getAttribute('for') ?? '';
+      const target = forId ? document.getElementById(forId) : null;
+      return {
+        text: (el.textContent ?? '').trim(),
+        forId,
+        resolves: !!target,
+        labelable: !!target && LABELABLE.has(target.tagName.toLowerCase()),
+      };
+    })
+    .filter((l) => l.forId !== '');
+}
+
+/** The host label of `name`'s form item (not a widget's own sub-label). */
+const hostLabelOf = (name: string): HTMLLabelElement => {
+  const el = document.querySelector(`[data-field="${name}"] > label`);
+  if (!el) throw new Error(`no host label rendered for field "${name}"`);
+  return el as HTMLLabelElement;
+};
+
+describe('ObjectForm: select + multiple is labelled as a group (objectui#3986)', () => {
+  it('the visible label is the accessible name of the chip group', async () => {
+    renderObjectForm(['regions']);
+
+    // The assertion that was 0 before this fix and is 1 after — the issue's
+    // `byRoleGroupNamed` column, on the object-form path.
+    await waitFor(() => {
+      expect(screen.getAllByRole('group', { name: 'Regions' })).toHaveLength(1);
+    });
+    // The same association read from the other side. Queried as `getAllBy…`
+    // deliberately: `getAllByLabelText` de-duplicates into a Set, so a length
+    // assertion states "exactly one element is named this", which a `getBy…`
+    // would only state accidentally.
+    expect(screen.getAllByLabelText('Regions')).toEqual(screen.getAllByRole('group', { name: 'Regions' }));
+  });
+
+  it('the host label drops its `for` and publishes an id the widget points back at', async () => {
+    renderObjectForm(['regions']);
+
+    await screen.findByRole('group', { name: 'Regions' });
+
+    const label = hostLabelOf('regions');
+    // A `for` left in place beside the `aria-labelledby` would give one label two
+    // association channels, and the `for` one is the inert half.
+    expect(label).not.toHaveAttribute('for');
+    expect(label.id).not.toBe('');
+    // The IDREF is not dangling — `aria-labelledby` naming a missing id fails
+    // SILENTLY, which is indistinguishable from success in the markup.
+    const group = screen.getByRole('group', { name: 'Regions' });
+    expect(group).toHaveAttribute('aria-labelledby', label.id);
+    expect(document.getElementById(label.id)).toBe(label);
+  });
+
+  it('renders the SAME shape as the `multiselect` type it now shares an id with', async () => {
+    // #3975 fixed `multiselect`; this issue is the residual path to the same
+    // widget. Both must now be indistinguishable from the host's point of view —
+    // that equality is the whole point of deciding the widget at the producer.
+    renderObjectForm(['regions', 'tags']);
+
+    await waitFor(() => {
+      expect(screen.getAllByRole('group', { name: 'Regions' })).toHaveLength(1);
+    });
+    expect(screen.getAllByRole('group', { name: 'Tags' })).toHaveLength(1);
+    for (const name of ['regions', 'tags']) {
+      expect(hostLabelOf(name)).not.toHaveAttribute('for');
+      expect(hostLabelOf(name).id).not.toBe('');
+    }
+  });
+
+  it('leaves a single-value select `for`-labelled to its trigger button', async () => {
+    // The guard direction, and the reason `select` could not simply be declared
+    // `labelling: 'group'`: this association ALREADY works, on a labelable
+    // element, and taking it away would trade one broken field for another.
+    renderObjectForm(['stage']);
+
+    const trigger = await waitFor(() => {
+      const el = document.querySelector('[data-field="stage"] [role="combobox"]');
+      if (!el) throw new Error('no select trigger rendered for "stage"');
+      return el;
+    });
+
+    const label = hostLabelOf('stage');
+    expect(label).toHaveAttribute('for', trigger.getAttribute('id'));
+    expect(label.id).toBe('');
+    expect(screen.getAllByLabelText('Stage')).toEqual([trigger]);
+    expect(trigger.tagName).toBe('BUTTON');
+    expect(screen.queryAllByRole('group', { name: 'Stage' })).toHaveLength(0);
+  });
+
+  it('all three in ONE form: no label is left with an inert or dangling `for`', async () => {
+    // The class-wide invariant this issue is an instance of. It can only be
+    // stated once the group labels stop emitting `for` at all: EVERY remaining
+    // `for` (the widgets' own sub-labels) must resolve to a real labelable
+    // control.
+    renderObjectForm();
+
+    await waitFor(() => {
+      expect(screen.getAllByRole('group', { name: 'Regions' })).toHaveLength(1);
+    });
+    expect(screen.getAllByRole('group', { name: 'Tags' })).toHaveLength(1);
+
+    const broken = labelTargets().filter((l) => !l.resolves || !l.labelable);
+    expect(broken).toEqual([]);
+  });
+});
+
+/**
+ * The producer decision itself, at the normalizer the sectioned form variants
+ * share (`sectionFields`). Both halves of the (type, `multiple`) pair are
+ * overridable at the VIEW level, and either one alone moves the widget — so the
+ * id is decided once, from the merged pair, not from `fd.type` in isolation.
+ */
+describe('normalizeSectionField decides the widget from the effective pair (objectui#3986)', () => {
+  const ctx = {
+    objectSchema,
+    objectName: objectSchema.name,
+    fieldLabel: (_obj: string, _name: string, fallback: string) => fallback || _name,
+  };
+
+  it('a string shorthand for a multi select resolves to the multi widget', () => {
+    expect(normalizeSectionField('regions', ctx).type).toBe('field:multiselect');
+  });
+
+  it('a spec field def naming a multi select resolves to the multi widget', () => {
+    expect(normalizeSectionField({ field: 'regions' }, ctx).type).toBe('field:multiselect');
+  });
+
+  it('a view that restates only `multiple: true` moves the widget too', () => {
+    // The second door onto the same defect: `multiple` is a spec FormField key,
+    // so a view can turn a single-value object field into a multi one without
+    // restating `type`. Resolving the id from `fd.type` before `multiple` had
+    // been merged would have left this on the single-value widget.
+    expect(normalizeSectionField({ field: 'stage', multiple: true }, ctx).type).toBe('field:multiselect');
+  });
+
+  it('a view that restates only `multiple: false` moves it BACK', () => {
+    // The inverse, which the same single computation buys: an object-level multi
+    // field narrowed by the view must land on the single-value widget, whose
+    // label association is the `for` one.
+    const f = normalizeSectionField({ field: 'regions', multiple: false }, ctx);
+    expect(f.type).toBe('field:select');
+    expect(f.multiple).toBe(false);
+  });
+
+  it('a view restating both keys agrees with the mapper', () => {
+    expect(normalizeSectionField({ field: 'stage', type: 'select', multiple: true }, ctx).type).toBe(
+      mapFieldTypeToFormType('select', { multiple: true }),
+    );
+  });
+
+  it('a single-value select is untouched', () => {
+    expect(normalizeSectionField({ field: 'stage' }, ctx).type).toBe('field:select');
+    expect(normalizeSectionField('stage', ctx).type).toBe('field:select');
+  });
+
+  it('a spec field naming nothing in the object schema keeps its fallback type', () => {
+    // `fromObjectSchema`'s `input` fallback, unchanged: with no type on either
+    // side there is nothing to decide, and `multiple` alone must not conjure a
+    // widget id.
+    const f = normalizeSectionField({ field: 'ghost', multiple: true }, ctx);
+    expect(f.type).toBe('input');
+    expect(f.multiple).toBe(true);
+  });
+});
diff --git a/packages/plugin-form/src/sectionFields.ts b/packages/plugin-form/src/sectionFields.ts
index 88df707d04..89d267b7ce 100644
--- a/packages/plugin-form/src/sectionFields.ts
+++ b/packages/plugin-form/src/sectionFields.ts
@@ -98,7 +98,11 @@ function fromObjectSchema(fieldName: string, ctx: SectionFieldsContext): FormFie
   return {
     name: fieldName,
     label: ctx.fieldLabel(ctx.objectName, fieldName, field.label || fieldName),
-    type: mapFieldTypeToFormType(field.type),
+    // The widget id is a function of the (type, multiple) PAIR, not of the type
+    // alone: a `select` declared `multiple: true` renders the multi-value chip
+    // picker, and the label-association declaration is keyed on the widget that
+    // actually renders (objectui#3986).
+    type: mapFieldTypeToFormType(field.type, { multiple: field.multiple }),
     required: field.required || false,
     disabled: ctx.readOnly || ctx.mode === 'view' || field.readonly,
     placeholder: field.placeholder,
@@ -145,7 +149,6 @@ export function normalizeSectionField(
   const fieldName = fd.field;
   const base = fromObjectSchema(fieldName, ctx) as any;
 
-  if (fd.type != null) base.type = mapFieldTypeToFormType(fd.type);
   if (fd.widget != null) base.widget = fd.widget;
   if (fd.label != null) base.label = fd.label;
   if (fd.placeholder != null) base.placeholder = fd.placeholder;
@@ -158,6 +161,19 @@ export function normalizeSectionField(
   if (fd.span != null) base.span = fd.span;
   if (fd.options != null) base.options = fd.options;
   if (fd.multiple != null) base.multiple = fd.multiple;
+  // The widget id is decided ONCE, here, from the EFFECTIVE (type, multiple)
+  // pair — because both halves are overridable at the view level and either one
+  // alone moves the widget (objectui#3986). A view restating only `multiple:
+  // true` over an object-schema `select` must land on the multi-value picker
+  // just as a view restating `type: 'select'` alongside it does; resolving from
+  // `fd.type` before `multiple` had been merged could see only one half.
+  //
+  // `rawType` is the PRE-alias spelling, kept because `base.type` is already the
+  // mapped id (`field:…`) and re-deciding from it would need an inverse mapping.
+  // Absent on both sides (a spec field naming nothing in the object schema and
+  // declaring no type) it stays untouched — `fromObjectSchema`'s `input`.
+  const rawType = fd.type ?? ctx.objectSchema?.fields?.[fieldName]?.type;
+  if (rawType != null) base.type = mapFieldTypeToFormType(rawType, { multiple: base.multiple });
   // Spec canon for the lookup target is `reference_to` (views.zod.ts); accept
   // both spellings and stamp both keys so dual-key readers see the override.
   const refOverride = fd.reference ?? fd.reference_to;