From 21794f2ca0f7a8c2d3f79bb3d49f223b069b1d93 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 22:40:02 +0000
Subject: [PATCH] =?UTF-8?q?fix(fields):=20group-labelled=20widget=20?=
 =?UTF-8?q?=E7=9A=84=E5=8F=AA=E8=AF=BB/=E9=9B=B6=E9=80=89=E9=A1=B9?=
 =?UTF-8?q?=E5=88=86=E6=94=AF=E4=B9=9F=E6=B6=88=E8=B4=B9=20host=20label=20?=
 =?UTF-8?q?=E7=9A=84=20IDREF=20(#3990)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

七个 `labelling: 'group'` widget 只在可编辑分支消费 host 递下来的
`aria-labelledby` + host id;字段级 `readonly: true` 与零可选项两种状态走的是
提前 return,渲染在那个容器之前,于是 label 发布了 id 却没有任何元素引用它。

实测(改前的 main,真 form renderer + 裸注册,逐字段数引用该 id 的元素):

    multiselect  readonly+value   consumers=0  byLabelText=0  named=0
    multiselect  readonly+empty   consumers=0  byLabelText=0  named=0
    multiselect  zeroOptions      consumers=0  byLabelText=0  named=0
    multiselect  editable         consumers=1  byLabelText=1  named=1

七类在每个只读态上都是同一读数,改后都是 1。不是 #3961/#3975 的回归:那之前
同样这些状态发的是指向无人携带 id 的 `for`,一样什么都不命名 —— 形状从悬空
`for` 变成无人消费的 IDREF,严重程度未变。

每个只读面现在只带两个「整字段」键(host `id` 与 `aria-labelledby`)加上让它们
生效的 `role="group"`,统一走新的 `toHostGroupProps`。窄化是刻意的:只读面没有
可聚焦控件,`aria-describedby` / `aria-required` / `disabled` / 焦点回调在那里
无人宣读,而 `div` 上的 `name` 正是 #3291 扫的泄漏。

`radio`(可编辑 `radiogroup`)与 `file`(可编辑 `button`,即 dropzone)在只读态
答的是 `group`,因为那两个面里一个 radio、一个 dropzone 都不剩;共享的
「无可选项」框对 checkboxes / radio / multiselect 同样答 `group`,单选 `select`
不属于 group-labelled,继续什么都不发。

standalone(网格内联编辑器、裸 SDUI 节点)不递这两个键,输出保持逐字节不变,
包括 `EmptyValue` 占位符本身。
---
 .../fields-readonly-group-label-idref-3990.md |  57 +++
 ...omposite-group-label-readonly-e2e.test.tsx | 403 ++++++++++++++++++
 packages/fields/src/widgets/AddressField.tsx  |  33 +-
 .../fields/src/widgets/CheckboxesField.tsx    |  20 +-
 packages/fields/src/widgets/FileField.tsx     |  13 +-
 .../fields/src/widgets/GeolocationField.tsx   |  27 +-
 .../fields/src/widgets/MultiSelectField.tsx   |  21 +-
 .../fields/src/widgets/OptionsEmptyState.tsx  |  16 +
 packages/fields/src/widgets/RadioField.tsx    |  20 +-
 packages/fields/src/widgets/RatingField.tsx   |   6 +-
 .../fields/src/widgets/toHostGroupProps.ts    | 102 +++++
 11 files changed, 689 insertions(+), 29 deletions(-)
 create mode 100644 .changeset/fields-readonly-group-label-idref-3990.md
 create mode 100644 packages/fields/src/__tests__/composite-group-label-readonly-e2e.test.tsx
 create mode 100644 packages/fields/src/widgets/toHostGroupProps.ts

diff --git a/.changeset/fields-readonly-group-label-idref-3990.md b/.changeset/fields-readonly-group-label-idref-3990.md
new file mode 100644
index 0000000000..25bff04cf5
--- /dev/null
+++ b/.changeset/fields-readonly-group-label-idref-3990.md
@@ -0,0 +1,57 @@
+---
+"@object-ui/fields": patch
+---
+
+Group-labelled field widgets now consume the host label's IDREF in their readonly and zero-option states, so the visible label names something there too
+
+A field declared `labelling: 'group'` (objectui#3961) is named by IDREF: the form
+renderer publishes its `<FormLabel>`'s own `id`, drops the inert `for`, and hands
+the widget `aria-labelledby` plus the host control `id`. All seven such widgets
+consumed that pair on their editable surface only. A field-level
+`readonly: true`, and an option list that resolved to zero offered options, take
+early returns that render before the container doing the consuming — so the label
+published an id that no element in the document referenced.
+
+Measured on the previous `main`, one field per row in a real form, counting the
+elements that reference the host label's published id:
+
+```
+                             consumers  byLabelText  named group
+multiselect  readonly+value      0           0           0
+multiselect  readonly+empty      0           0           0
+multiselect  zeroOptions         0           0           0
+multiselect  editable            1           1           1
+```
+
+All seven measured identically in every readonly state; each is 1 now. The
+user-visible effect is the one objectui#3961 fixed for editable fields: the
+visible label was the accessible name of NOTHING, so a readonly "Tags" or
+"Shipping Address" was announced as loose text next to unattributed values. It is
+not a regression of #3961 or objectui#3975 — before them these same states
+emitted a `for` pointing at an id no element carried, which named nothing either.
+The shape changed from a dangling `for` to an unconsumed IDREF; the defect did
+not.
+
+Each readonly surface now carries exactly two keys — the host `id` and
+`aria-labelledby` — plus the `role="group"` that makes them meaningful, in one
+shared spelling (`toHostGroupProps`). The narrow pair is deliberate: a readonly
+display has no focusable control, so `aria-describedby` / `aria-required` /
+`disabled` / the focus handlers have nothing to announce on, and `name` on a
+`div` is exactly the DOM leak objectui#3291 sweeps for.
+
+Two widgets answer with a different role than they do while editable, because
+they render a different surface: `radio` (editable `radiogroup`) shows the chosen
+option's label as text with no radios in it, and `file` (editable `button`, the
+dropzone) shows file names with no dropzone. `role="group"` is also what the
+shared "no options available" box now answers with for `checkboxes` / `radio` /
+`multiselect`; the single `select` is not group-labelled, keeps its working
+`for`, and that box emits nothing new for it.
+
+Standalone rendering is untouched. The grid's inline cell editor and bare SDUI
+nodes hand down neither key, so nothing is emitted and the markup stays
+byte-identical — including the `EmptyValue` placeholder, which keeps its own
+`aria-label` and gains no role. Hosted-and-empty, that placeholder is the whole
+readonly surface, so it carries the group props: its `aria-label` ("No value") is
+then outranked by `aria-labelledby` per accname, which is the intended outcome —
+on the `generic` role that span carries, an author name is prohibited and was
+never exposed, so the choice was between the field's name and no name.
diff --git a/packages/fields/src/__tests__/composite-group-label-readonly-e2e.test.tsx b/packages/fields/src/__tests__/composite-group-label-readonly-e2e.test.tsx
new file mode 100644
index 0000000000..1febff6e85
--- /dev/null
+++ b/packages/fields/src/__tests__/composite-group-label-readonly-e2e.test.tsx
@@ -0,0 +1,403 @@
+/**
+ * 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 group-labelled field's visible label names the widget's surface
+ * in EVERY state it renders — not only the editable one (objectui#3990).
+ *
+ * The residual of objectui#3961 / #3975. Those two moved the association from an
+ * inert `<label for>` to the WAI-ARIA group pattern (the label publishes its own
+ * `id`, the widget answers with `aria-labelledby` + a role that can carry a
+ * name), and pinned it in `composite-group-label-e2e.test.tsx` — entirely on
+ * EDITABLE samples. Every one of these widgets also returns EARLY, before the
+ * container that consumes that IDREF, for a field-level `readonly: true` and for
+ * an option list that resolved to zero offered options. Measured on
+ * `origin/main` with a real form + the same bare registration this file uses,
+ * counting the elements that reference the host label's published id:
+ *
+ * ```
+ *                              consumers  byLabelText  namedByRole
+ * multiselect  readonly+value      0           0          []
+ * multiselect  readonly+empty      0           0          []
+ * multiselect  zeroOptions         0           0          []
+ * multiselect  editable            1           1          [group:1]     ← #3975
+ * ```
+ *
+ * All seven types measured identically, in every readonly state. Both `for`-less
+ * halves of the association were dropped by those returns, so the visible label
+ * was the accessible name of NOTHING — the same user-visible outcome #3961
+ * fixed, in the states its probe never sampled. It is not a regression of either
+ * PR: before #3961 the same states rendered a `for` pointing at an id no element
+ * carried, which named nothing either. The shape changed; the defect did not.
+ *
+ * ## Why the role is `group` here even where the editable branch says otherwise
+ *
+ * `aria-labelledby` on a role-less `div` / `span` names nothing (`generic`
+ * prohibits an author name), so the readonly surface needs a role that supports
+ * naming, and `group` is the only one that does not lie about interactivity:
+ *
+ *  - `radio` answers `radiogroup` while editable, but its readonly branch renders
+ *    the CHOSEN option's label as text — there is not one radio left in it;
+ *  - `file` answers `button` while editable (the dropzone is its single control),
+ *    but readonly there is no dropzone, only the file names.
+ *
+ * So the roles this file expects deliberately differ from `HOSTED` in the
+ * editable e2e for exactly those two, and the last describe block pins that the
+ * editable answers are untouched.
+ *
+ * The widgets are registered raw rather than through `registerAllFields()`, whose
+ * `React.lazy` loaders put an unbounded module load inside a bounded `findBy`
+ * window — this repo's known flake generator (AGENTS.md 测试纪律, objectui#3010).
+ */
+
+import { describe, it, expect, beforeAll, beforeEach, afterEach, vi } from 'vitest';
+import { render, screen, 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 { AddressField } from '../widgets/AddressField';
+import { GeolocationField } from '../widgets/GeolocationField';
+import { CheckboxesField } from '../widgets/CheckboxesField';
+import { RadioField } from '../widgets/RadioField';
+import { RatingField } from '../widgets/RatingField';
+import { FileField } from '../widgets/FileField';
+import { MultiSelectField } from '../widgets/MultiSelectField';
+import { SelectField } from '../widgets/SelectField';
+
+const WIDGETS: Record<string, any> = {
+  address: AddressField,
+  geolocation: GeolocationField,
+  checkboxes: CheckboxesField,
+  radio: RadioField,
+  rating: RatingField,
+  file: FileField,
+  multiselect: MultiSelectField,
+};
+
+/** The option widgets — the only ones with a zero-option state to measure. */
+const OPTION_TYPES = ['checkboxes', 'radio', 'multiselect'] as const;
+
+/**
+ * Where the placeholder sits when a readonly field has no value. Three real
+ * shapes, so the assertion is per-widget rather than one presumed form:
+ *
+ *  - `'is-placeholder'`: the whole surface IS `EmptyValue`, which therefore
+ *    carries the group props itself;
+ *  - `'contains-placeholder'`: `geolocation` keeps its icon row and renders the
+ *    placeholder inside it, so the row is the named group;
+ *  - `'no-placeholder'`: `rating` has no empty state at all — an unset rating
+ *    renders the same "0 / max" star row.
+ */
+const EMPTY_SHAPE: Record<string, 'is-placeholder' | 'contains-placeholder' | 'no-placeholder'> = {
+  address: 'is-placeholder',
+  checkboxes: 'is-placeholder',
+  radio: 'is-placeholder',
+  file: 'is-placeholder',
+  multiselect: 'is-placeholder',
+  geolocation: 'contains-placeholder',
+  rating: 'no-placeholder',
+};
+
+const OPTIONS = [
+  { label: 'Alpha', value: 'a' },
+  { label: 'Beta', value: 'b' },
+];
+
+/** A stored value per type, so the readonly branch renders its filled shape. */
+const VALUES: Record<string, unknown> = {
+  address: { street: '1 Main St', city: 'Springfield' },
+  geolocation: { latitude: 1.5, longitude: 2.5 },
+  checkboxes: ['a'],
+  radio: 'a',
+  rating: 3,
+  file: { id: 'f1', name: 'report.pdf' },
+  multiselect: ['a'],
+};
+
+/** The role the EDITABLE branch answers with — unchanged by this issue. */
+const EDITABLE_ROLE: Record<string, string> = {
+  address: 'group',
+  geolocation: 'group',
+  checkboxes: 'group',
+  radio: 'radiogroup',
+  rating: 'group',
+  file: 'button',
+  multiselect: 'group',
+};
+
+const TYPES = Object.keys(WIDGETS);
+
+beforeAll(() => {
+  for (const [type, Component] of Object.entries(WIDGETS)) {
+    ComponentRegistry.register(type, Component as any, {
+      namespace: 'field',
+      skipFallback: true,
+      // The declaration under test, mirroring `FIELD_TYPES_GROUP_LABELLED`.
+      labelling: 'group',
+    });
+  }
+}, 30000);
+
+beforeEach(() => {
+  if (!(Element.prototype as any).scrollIntoView) {
+    (Element.prototype as any).scrollIntoView = () => {};
+  }
+});
+
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+/** HTML's labelable elements — the only ones a `<label for>` can address. */
+const LABELABLE = new Set(['button', 'input', 'meter', 'output', 'progress', 'select', 'textarea']);
+
+function labelTargets(): Array<{ 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 {
+        forId,
+        resolves: !!target,
+        labelable: !!target && LABELABLE.has(target.tagName.toLowerCase()),
+      };
+    })
+    .filter((l) => l.forId !== '');
+}
+
+function fieldConfig(
+  type: string,
+  opts: { readonly?: boolean; zeroOptions?: boolean } = {},
+): Record<string, unknown> {
+  const config: any = { name: `f_${type}`, label: `Group Label ${type}`, type };
+  if ((OPTION_TYPES as readonly string[]).includes(type)) {
+    config.options = opts.zeroOptions ? [] : OPTIONS;
+  }
+  // Field-level readonly — the state this issue is about. NOT the form-level
+  // `mode: 'view'`, which renders a different (detail) path and was already
+  // naming its group correctly.
+  if (opts.readonly) config.readonly = true;
+  return config;
+}
+
+/** The real form renderer hosting one field — the #3990 reproduction. */
+function renderForm(fields: any[], defaultValues: Record<string, unknown> = {}) {
+  const Form = ComponentRegistry.get('form')!;
+  return render(
+    <Form
+      schema={{
+        type: 'form',
+        mode: 'create',
+        showSubmit: false,
+        showCancel: false,
+        defaultValues,
+        fields,
+      }}
+    />,
+  );
+}
+
+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('a READONLY group-labelled field is named by its host label (objectui#3990)', () => {
+  it.each(TYPES)('%s: the host label names the readonly surface', (type) => {
+    renderForm([fieldConfig(type, { readonly: true })], { [`f_${type}`]: VALUES[type] });
+
+    // 0 before this fix, 1 after — for all seven, whatever their readonly shape.
+    const named = screen.getAllByRole('group', { name: `Group Label ${type}` });
+    expect(named).toHaveLength(1);
+    // The same association read from the other side.
+    expect(screen.getAllByLabelText(`Group Label ${type}`)).toEqual(named);
+  });
+
+  it.each(TYPES)('%s: the readonly surface is the element the host handed its id to', (type) => {
+    // The name and the host id must land on the SAME element, as in the editable
+    // path: the readonly branches dropped BOTH, so the `…-form-item` id existed
+    // on no element in the document.
+    renderForm([fieldConfig(type, { readonly: true })], { [`f_${type}`]: VALUES[type] });
+
+    const named = screen.getByRole('group', { name: `Group Label ${type}` });
+    expect(named.getAttribute('id')).toMatch(/-form-item$/);
+  });
+
+  it.each(TYPES)('%s: readonly with NO value names the placeholder surface', (type) => {
+    renderForm([fieldConfig(type, { readonly: true })]);
+
+    const named = screen.getByRole('group', { name: `Group Label ${type}` });
+    const shape = EMPTY_SHAPE[type];
+    if (shape === 'is-placeholder') {
+      // `EmptyValue` itself is the field's whole surface here. Its own
+      // `aria-label` ("No value") stays in the markup and is outranked by
+      // `aria-labelledby` per accname — on the `generic` role it carried before
+      // this change, that author name was not exposed at all.
+      expect(named).toHaveAttribute('data-slot', 'empty-value');
+      expect(named).toHaveAccessibleName(`Group Label ${type}`);
+    } else if (shape === 'contains-placeholder') {
+      expect(named.querySelector('[data-slot="empty-value"]')).not.toBeNull();
+    } else {
+      // `rating` has no empty state: an unset rating is the same star row.
+      expect(named.querySelector('[data-slot="empty-value"]')).toBeNull();
+      expect(named.textContent).toContain('0 / 5');
+    }
+  });
+
+  it.each(TYPES)('%s: the host label still emits an id and no `for` when readonly', (type) => {
+    renderForm([fieldConfig(type, { readonly: true })], { [`f_${type}`]: VALUES[type] });
+
+    const label = hostLabelOf(`f_${type}`);
+    expect(label).not.toHaveAttribute('for');
+    expect(label.id).not.toBe('');
+    // A dangling IDREF fails silently, which reads exactly like success.
+    expect(document.getElementById(label.id)).toBe(label);
+    // And no OTHER label in the field is left with an inert/dangling `for`.
+    expect(labelTargets().filter((l) => !l.resolves || !l.labelable)).toEqual([]);
+  });
+
+  it.each(TYPES)('%s: the readonly surface takes the two whole-field keys ONLY', (type) => {
+    // The narrow pair is deliberate (`toHostGroupProps`): a readonly display has
+    // no focusable control, so control-only plumbing must not ride along. `name`
+    // is the one that would be a DOM leak of the objectui#3291 class — it is
+    // legal on form controls only, and these surfaces are `div` / `span`.
+    renderForm([{ ...fieldConfig(type, { readonly: true }), description: 'Some help' }], {
+      [`f_${type}`]: VALUES[type],
+    });
+
+    const named = screen.getByRole('group', { name: `Group Label ${type}` });
+    expect(named).not.toHaveAttribute('name');
+    expect(named).not.toHaveAttribute('aria-invalid');
+  });
+
+  it('all seven readonly in ONE form: each is named exactly once', () => {
+    const fields = TYPES.map((type) => fieldConfig(type, { readonly: true }));
+    const values = Object.fromEntries(TYPES.map((type) => [`f_${type}`, VALUES[type]]));
+    renderForm(fields, values);
+
+    for (const type of TYPES) {
+      expect(screen.getAllByRole('group', { name: `Group Label ${type}` })).toHaveLength(1);
+    }
+    expect(labelTargets().filter((l) => !l.resolves || !l.labelable)).toEqual([]);
+  });
+});
+
+describe('a ZERO-OPTION group-labelled field is named by its host label (objectui#3990)', () => {
+  it.each(OPTION_TYPES)('%s: the unfillable-options box is the named group', (type) => {
+    renderForm([fieldConfig(type, { zeroOptions: true })]);
+
+    const named = screen.getAllByRole('group', { name: `Group Label ${type}` });
+    expect(named).toHaveLength(1);
+    // The named element is the shared `OptionsEmptyState` box, not some ancestor:
+    // in this state it is the only thing the widget renders.
+    expect(named[0]).toBe(screen.getByTestId(`${type}-empty-f_${type}`));
+    expect(named[0].getAttribute('id')).toMatch(/-form-item$/);
+    expect(screen.getAllByLabelText(`Group Label ${type}`)).toEqual(named);
+  });
+
+  it.each(OPTION_TYPES)('%s: readonly wins over zero options, and is still named', (type) => {
+    // Both early returns at once. The readonly branch comes first, so the
+    // measured surface is the readonly one — and it must still be named.
+    renderForm([fieldConfig(type, { readonly: true, zeroOptions: true })], {
+      [`f_${type}`]: VALUES[type],
+    });
+
+    expect(screen.getAllByRole('group', { name: `Group Label ${type}` })).toHaveLength(1);
+    expect(screen.queryByTestId(`${type}-empty-f_${type}`)).toBeNull();
+  });
+});
+
+describe('the editable answers are untouched (objectui#3961 / #3975 regression)', () => {
+  it.each(TYPES)('%s: editable keeps its own role, readonly answers `group`', (type) => {
+    // The drift pin: one widget, two surfaces, both named. `radio` and `file`
+    // deliberately answer with DIFFERENT roles in the two states, so a future
+    // "unify the roles" edit has to come here and say which it broke.
+    renderForm([fieldConfig(type)], { [`f_${type}`]: VALUES[type] });
+    expect(
+      screen.getAllByRole(EDITABLE_ROLE[type], { name: `Group Label ${type}` }),
+    ).toHaveLength(1);
+    cleanup();
+
+    renderForm([fieldConfig(type, { readonly: true })], { [`f_${type}`]: VALUES[type] });
+    expect(screen.getAllByRole('group', { name: `Group Label ${type}` })).toHaveLength(1);
+  });
+});
+
+describe('STANDALONE readonly widgets are unchanged (objectui#3990)', () => {
+  // `FieldEditWidget` (the grid's inline cell editor) and bare SDUI nodes hand
+  // down no id and no host label, so there is nothing to associate and nothing
+  // may be emitted: an unnamed `role="group"` announces a container with no name
+  // to give, and an id nobody asked for can collide with the page's own.
+
+  it.each(TYPES)('%s: no role, no IDREF, no id', (type) => {
+    const Widget = WIDGETS[type];
+    render(
+      <Widget
+        value={VALUES[type]}
+        onChange={() => {}}
+        readonly
+        field={{
+          name: type,
+          label: `Group Label ${type}`,
+          type,
+          ...((OPTION_TYPES as readonly string[]).includes(type) ? { options: OPTIONS } : null),
+        }}
+      />,
+    );
+
+    expect(screen.queryAllByRole('group')).toHaveLength(0);
+    expect(document.querySelector('[aria-labelledby]')).toBeNull();
+    expect(document.querySelector('[id]')).toBeNull();
+  });
+
+  it.each(TYPES)('%s: no value, still nothing emitted', (type) => {
+    const Widget = WIDGETS[type];
+    render(
+      <Widget
+        value={undefined}
+        onChange={() => {}}
+        readonly
+        field={{
+          name: type,
+          label: `Group Label ${type}`,
+          type,
+          ...((OPTION_TYPES as readonly string[]).includes(type) ? { options: OPTIONS } : null),
+        }}
+      />,
+    );
+
+    expect(screen.queryAllByRole('group')).toHaveLength(0);
+    expect(document.querySelector('[aria-labelledby]')).toBeNull();
+    // The placeholder keeps its own name and gains no role it was not given.
+    const placeholder = document.querySelector('[data-slot="empty-value"]');
+    if (placeholder) expect(placeholder).not.toHaveAttribute('role');
+  });
+
+  it('the shared options-empty box emits nothing for a widget that is not group-labelled', () => {
+    // The positive control for `OptionsEmptyState`'s new prop. The single
+    // `SelectField` is NOT in `FIELD_TYPES_GROUP_LABELLED` — its label keeps a
+    // plain, working `for` — so the shared box must stay attribute-for-attribute
+    // what it was: no `role`, no IDREF, no host id.
+    render(
+      <SelectField
+        value={undefined}
+        onChange={() => {}}
+        field={{ name: 'stage', label: 'Stage', type: 'select', options: [] } as any}
+      />,
+    );
+
+    const box = screen.getByTestId('select-empty-stage');
+    expect(box).not.toHaveAttribute('role');
+    expect(box).not.toHaveAttribute('aria-labelledby');
+    expect(box).not.toHaveAttribute('id');
+  });
+});
diff --git a/packages/fields/src/widgets/AddressField.tsx b/packages/fields/src/widgets/AddressField.tsx
index f0a376f8ea..b847e371f8 100644
--- a/packages/fields/src/widgets/AddressField.tsx
+++ b/packages/fields/src/widgets/AddressField.tsx
@@ -2,6 +2,7 @@ import React, { useId } from 'react';
 import { Input, Label, EmptyValue } from '@object-ui/components';
 import { FieldWidgetComponentProps } from './types';
 import { toDomProps } from './toDomProps';
+import { toHostGroupProps } from './toHostGroupProps';
 
 /**
  * Address data structure — the part names of `@objectstack/spec`'s
@@ -72,10 +73,15 @@ export function AddressField({ value, onChange, field, readonly, error, ...props
   // stays on the first sub-input: a description or error must be announced when
   // focus lands on something focusable, and a container is not.
   const {
-    id: hostId,
-    'aria-labelledby': hostLabelledBy,
+    id: _hostId,
+    'aria-labelledby': _hostLabelledBy,
     ...domProps
   } = toDomProps(props);
+  // The pair held back above, in the one spelling every group-labelled widget
+  // uses for it — and computed HERE, before the readonly early return below,
+  // because that return used to drop both keys on the floor: a published label
+  // id with no consumer in the document (objectui#3990). See `toHostGroupProps`.
+  const hostGroupProps = toHostGroupProps(props);
   // Sub-input ids (objectui#3343): `useId()` prefix + sub-field name — the
   // `groupId` paradigm of RadioField / CheckboxesField. Hardcoded literals
   // ("street", "city", …) collide as soon as a form renders two address
@@ -112,21 +118,28 @@ export function AddressField({ value, onChange, field, readonly, error, ...props
   };
 
   if (readonly) {
+    // Readonly the composite collapses to ONE formatted line — no sub-inputs and
+    // no sub-labels — so that line is the surface the host label names, and
+    // `EmptyValue` is the same surface with nothing in it (objectui#3990). The
+    // placeholder's own `aria-label` ("No value") is outranked by
+    // `aria-labelledby` per accname, and on its `generic` role an author name was
+    // never exposed anyway.
     const formatted = formatAddress(address);
-    return formatted ? <span className="text-sm">{formatted}</span> : <EmptyValue />;
+    return formatted ? (
+      <span {...hostGroupProps} className="text-sm">{formatted}</span>
+    ) : (
+      <EmptyValue {...hostGroupProps} />
+    );
   }
 
   return (
     // `role="group"` only when a host actually named this container
     // (objectui#3961): an unnamed group adds nothing for assistive tech, and
     // standalone rendering — the inline grid editor, a bare SDUI node — must stay
-    // byte-identical to what it was before.
-    <div
-      className="space-y-3"
-      id={hostId}
-      role={hostLabelledBy ? 'group' : undefined}
-      aria-labelledby={hostLabelledBy}
-    >
+    // byte-identical to what it was before. That condition now lives in
+    // `toHostGroupProps` so this container and the readonly line above cannot
+    // answer differently (objectui#3990).
+    <div className="space-y-3" {...hostGroupProps}>
       <div>
         <Label htmlFor={subId('street')} className="text-xs">Street Address</Label>
         <Input
diff --git a/packages/fields/src/widgets/CheckboxesField.tsx b/packages/fields/src/widgets/CheckboxesField.tsx
index f7e52eec63..f315e36598 100644
--- a/packages/fields/src/widgets/CheckboxesField.tsx
+++ b/packages/fields/src/widgets/CheckboxesField.tsx
@@ -3,6 +3,7 @@ import { Checkbox, Label, EmptyValue, Badge } from '@object-ui/components';
 import type { OptionLike } from '@object-ui/core';
 import { FieldWidgetComponentProps } from './types';
 import { toDomProps } from './toDomProps';
+import { toHostGroupProps } from './toHostGroupProps';
 import { OptionsEmptyState } from './OptionsEmptyState';
 import { useCascadingOptions } from './useCascadingOptions';
 
@@ -57,10 +58,22 @@ export function CheckboxesField({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [options, gated]);
 
+  // The host's group label has to be consumed on EVERY surface this widget can
+  // render, not only the editable one (objectui#3990): both branches below
+  // return before the editable container's `groupDomProps` spread, which is how
+  // a field-level `readonly: true` and a zero-option list ended up with a
+  // published label id and no consumer at all. See `toHostGroupProps`.
+  const hostGroupProps = toHostGroupProps(props);
+
   if (readonly) {
-    if (selected.length === 0) return <EmptyValue />;
+    // The readonly display of a checkbox set is the set of CHECKED labels — a
+    // set of values, so the same `group` answer as the editable list.
+    // `EmptyValue` is that surface with nothing in it; its own `aria-label`
+    // ("No value") is outranked by `aria-labelledby` per accname, and on the
+    // `generic` role that span carries it was never exposed anyway.
+    if (selected.length === 0) return <EmptyValue {...hostGroupProps} />;
     return (
-      <div className="flex flex-wrap gap-1">
+      <div {...hostGroupProps} className="flex flex-wrap gap-1">
         {selected.map((v) => {
           // Label from the raw set so a stored value hidden by `visibleWhen`
           // still renders its label rather than a bare id.
@@ -83,6 +96,9 @@ export function CheckboxesField({
         dependsOnFields={dependsOnFields}
         testId={fieldName ? `checkboxes-empty-${fieldName}` : undefined}
         className="min-h-9"
+        // This box IS the field in this state, so it is what the host label
+        // names (objectui#3990).
+        hostGroupProps={hostGroupProps}
       />
     );
   }
diff --git a/packages/fields/src/widgets/FileField.tsx b/packages/fields/src/widgets/FileField.tsx
index 2606e595df..c298a186a2 100644
--- a/packages/fields/src/widgets/FileField.tsx
+++ b/packages/fields/src/widgets/FileField.tsx
@@ -5,6 +5,7 @@ import { useObjectTranslation } from '@object-ui/i18n';
 import { Upload, X, File as FileIcon, ImageIcon, Camera, Loader2 } from 'lucide-react';
 import { FieldWidgetComponentProps } from './types';
 import { toDomProps } from './toDomProps';
+import { toHostGroupProps } from './toHostGroupProps';
 import { useUploadingSignal } from './useUploadingSignal';
 import {
   fileValueForSubmit,
@@ -184,10 +185,18 @@ export function FileField({ value, onChange, field, readonly, onUploadingChange,
   }, [accept, processFiles]);
 
   if (readonly) {
-    if (!value) return <EmptyValue />;
+    // Readonly there is no dropzone: the field's whole rendered surface is the
+    // list of file names, so THAT is what the host's group label names
+    // (objectui#3990). The role is therefore `group` here and `button` (the
+    // dropzone) while editable — the same widget, two different surfaces. See
+    // `toHostGroupProps`; `EmptyValue`'s own `aria-label` ("No value") is
+    // outranked by `aria-labelledby` per accname, and on the `generic` role that
+    // placeholder span carries it was never exposed as a name anyway.
+    const hostGroupProps = toHostGroupProps(props);
+    if (!value) return <EmptyValue {...hostGroupProps} />;
 
     return (
-      <div className="flex flex-wrap gap-2">
+      <div {...hostGroupProps} className="flex flex-wrap gap-2">
         {views.map((file, idx) => (
           <span key={idx} className="text-sm truncate max-w-xs">
             {file.name}
diff --git a/packages/fields/src/widgets/GeolocationField.tsx b/packages/fields/src/widgets/GeolocationField.tsx
index b0da6b1f60..a9af53f43d 100644
--- a/packages/fields/src/widgets/GeolocationField.tsx
+++ b/packages/fields/src/widgets/GeolocationField.tsx
@@ -3,6 +3,7 @@ import { Input, Button, Label, EmptyValue } from '@object-ui/components';
 import { MapPin, Crosshair } from 'lucide-react';
 import { FieldWidgetComponentProps } from './types';
 import { toDomProps } from './toDomProps';
+import { toHostGroupProps } from './toHostGroupProps';
 
 /**
  * Geolocation data structure
@@ -32,10 +33,15 @@ export function GeolocationField({ value, onChange, field, readonly, error, ...p
   // OVERRIDE its own "Latitude" label with the field name. `aria-describedby` and
   // the rest stay on the first sub-input, where focus can reach them.
   const {
-    id: hostId,
-    'aria-labelledby': hostLabelledBy,
+    id: _hostId,
+    'aria-labelledby': _hostLabelledBy,
     ...domProps
   } = toDomProps(props);
+  // The pair held back above, in the one spelling every group-labelled widget
+  // uses for it — and computed HERE, before the readonly early return below,
+  // because that return used to drop both keys on the floor: a published label
+  // id with no consumer in the document (objectui#3990). See `toHostGroupProps`.
+  const hostGroupProps = toHostGroupProps(props);
   // Sub-input ids (objectui#3343): `useId()` prefix + sub-field name — the
   // `groupId` paradigm of RadioField / CheckboxesField. Hardcoded literals
   // ("latitude" / "longitude") collide as soon as a form renders two
@@ -91,9 +97,13 @@ export function GeolocationField({ value, onChange, field, readonly, error, ...p
   };
 
   if (readonly) {
+    // Readonly the composite collapses to the formatted coordinates (plus the
+    // "View on map" link), so THAT row is the surface the host label names
+    // (objectui#3990). The `EmptyValue` placeholder sits inside it, so it needs
+    // nothing of its own.
     const formatted = formatLocation(location);
     return (
-      <div className="flex items-center gap-2">
+      <div {...hostGroupProps} className="flex items-center gap-2">
         <MapPin className="w-4 h-4 text-muted-foreground" />
         {formatted ? <span className="text-sm">{formatted}</span> : <EmptyValue />}
         {location.latitude && location.longitude && (
@@ -113,13 +123,10 @@ export function GeolocationField({ value, onChange, field, readonly, error, ...p
 
   return (
     // `role="group"` only when a host actually named this container
-    // (objectui#3961); standalone rendering stays exactly as it was.
-    <div
-      className="space-y-3"
-      id={hostId}
-      role={hostLabelledBy ? 'group' : undefined}
-      aria-labelledby={hostLabelledBy}
-    >
+    // (objectui#3961); standalone rendering stays exactly as it was. That
+    // condition now lives in `toHostGroupProps` so this container and the
+    // readonly row above cannot answer differently (objectui#3990).
+    <div className="space-y-3" {...hostGroupProps}>
       <div className="flex items-center gap-2">
         <Button
           type="button"
diff --git a/packages/fields/src/widgets/MultiSelectField.tsx b/packages/fields/src/widgets/MultiSelectField.tsx
index b8e3c5079c..bccb032a3f 100644
--- a/packages/fields/src/widgets/MultiSelectField.tsx
+++ b/packages/fields/src/widgets/MultiSelectField.tsx
@@ -3,6 +3,7 @@ import { Badge, EmptyValue, cn } from '@object-ui/components';
 import type { OptionLike } from '@object-ui/core';
 import { FieldWidgetComponentProps } from './types';
 import { toDomProps } from './toDomProps';
+import { toHostGroupProps } from './toHostGroupProps';
 import { OptionsEmptyState } from './OptionsEmptyState';
 import { useCascadingOptions } from './useCascadingOptions';
 
@@ -58,10 +59,23 @@ export function MultiSelectField({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [options, gated]);
 
+  // The host's group label has to be consumed on EVERY surface this widget can
+  // render, not only the editable one (objectui#3990): both branches below
+  // return before the editable container's `groupDomProps` spread, which is how
+  // a field-level `readonly: true` and a zero-option list ended up with a
+  // published label id and no consumer at all. See `toHostGroupProps`.
+  const hostGroupProps = toHostGroupProps(props);
+
   if (readonly) {
-    if (selected.length === 0) return <EmptyValue />;
+    // A readonly set of values is still a set, so it takes the same `group`
+    // answer the editable chip row gives. `EmptyValue` is that surface with
+    // nothing in it: it publishes an `aria-label` ("No value") of its own, and
+    // `aria-labelledby` outranks that per accname — correctly, because on the
+    // `generic` role that placeholder span carries, an author name is prohibited
+    // and never exposed, so the real choice is the field's name or no name.
+    if (selected.length === 0) return <EmptyValue {...hostGroupProps} />;
     return (
-      <div className="flex flex-wrap gap-1">
+      <div {...hostGroupProps} className="flex flex-wrap gap-1">
         {selected.map((v) => {
           // Label from the raw set so a stored value hidden by `visibleWhen`
           // still renders its label rather than a bare id.
@@ -84,6 +98,9 @@ export function MultiSelectField({
         dependsOnFields={dependsOnFields}
         testId={fieldName ? `multiselect-empty-${fieldName}` : undefined}
         className="min-h-9"
+        // This box IS the field in this state, so it is what the host label
+        // names (objectui#3990).
+        hostGroupProps={hostGroupProps}
       />
     );
   }
diff --git a/packages/fields/src/widgets/OptionsEmptyState.tsx b/packages/fields/src/widgets/OptionsEmptyState.tsx
index 555b2c0e5b..42df3d4397 100644
--- a/packages/fields/src/widgets/OptionsEmptyState.tsx
+++ b/packages/fields/src/widgets/OptionsEmptyState.tsx
@@ -9,6 +9,7 @@
 import React from 'react';
 import { cn } from '@object-ui/components';
 import { useFieldTranslation } from './useFieldTranslation';
+import type { HostGroupProps } from './toHostGroupProps';
 
 /**
  * The "this option list cannot be filled" state shared by every fixed-option
@@ -52,6 +53,19 @@ export interface OptionsEmptyStateProps {
   testId?: string;
   /** Widget-specific sizing (the dropdown is a fixed `h-9`, lists grow). */
   className?: string;
+  /**
+   * The host label's IDREF plumbing, when this box is the whole rendered surface
+   * of a group-labelled field (objectui#3990) — a `checkboxes` / `radio` /
+   * `multiselect` whose option list came back empty renders NOTHING but this
+   * box, so the visible label named zero elements until it landed here.
+   *
+   * A closed three-key type rather than an open props tail: only `id`,
+   * `aria-labelledby` and the `role` that makes them meaningful may reach this
+   * element, and reopening a spread is what objectui#3291 exists to prevent.
+   * Absent for the single `SelectField` — it is not group-labelled, its label
+   * still uses a plain `for`, and it must keep emitting no such attributes.
+   */
+  hostGroupProps?: HostGroupProps;
 }
 
 export function OptionsEmptyState({
@@ -60,6 +74,7 @@ export function OptionsEmptyState({
   dependsOnFields,
   testId,
   className,
+  hostGroupProps,
 }: OptionsEmptyStateProps) {
   const { t } = useFieldTranslation();
   // The host's hint when it computed one; otherwise this widget's own copy,
@@ -71,6 +86,7 @@ export function OptionsEmptyState({
       : t('fields.options.empty'));
   return (
     <div
+      {...hostGroupProps}
       data-testid={testId}
       className={cn(
         'flex w-full items-center rounded-md border border-input bg-muted/30 px-3 py-2 text-sm text-muted-foreground',
diff --git a/packages/fields/src/widgets/RadioField.tsx b/packages/fields/src/widgets/RadioField.tsx
index 6129cb0cff..a1130da3a2 100644
--- a/packages/fields/src/widgets/RadioField.tsx
+++ b/packages/fields/src/widgets/RadioField.tsx
@@ -3,6 +3,7 @@ import { RadioGroup, RadioGroupItem, Label, EmptyValue } from '@object-ui/compon
 import { isValueStillOffered, type OptionLike } from '@object-ui/core';
 import { FieldWidgetComponentProps } from './types';
 import { toDomProps } from './toDomProps';
+import { toHostGroupProps } from './toHostGroupProps';
 import { OptionsEmptyState } from './OptionsEmptyState';
 import { useCascadingOptions } from './useCascadingOptions';
 
@@ -54,12 +55,24 @@ export function RadioField({
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [options, gated]);
 
+  // The host's group label has to be consumed on EVERY surface this widget can
+  // render, not only the `RadioGroup` (objectui#3990): both branches below return
+  // before that spread, which is how a field-level `readonly: true` and a
+  // zero-option list ended up with a published label id and no consumer at all.
+  // See `toHostGroupProps` — note the role it emits is `group`, not the
+  // `radiogroup` the editable branch keeps: there is not one radio left in
+  // either of these surfaces.
+  const hostGroupProps = toHostGroupProps(props);
+
   if (readonly) {
-    if (value == null || value === '') return <EmptyValue />;
+    // `EmptyValue`'s own `aria-label` ("No value") is outranked by
+    // `aria-labelledby` per accname, and on the `generic` role that placeholder
+    // span carries it was never exposed as a name anyway.
+    if (value == null || value === '') return <EmptyValue {...hostGroupProps} />;
     // Label from the raw set so a stored value hidden by `visibleWhen` still
     // renders its label rather than a bare id.
     const opt = rawOptions.find((o) => o.value === value);
-    return <span className="text-sm">{opt?.label || String(value)}</span>;
+    return <span {...hostGroupProps} className="text-sm">{opt?.label || String(value)}</span>;
   }
 
   // No offered options is unfillable — surface a legible state instead of an
@@ -74,6 +87,9 @@ export function RadioField({
         dependsOnFields={dependsOnFields}
         testId={fieldName ? `radio-empty-${fieldName}` : undefined}
         className="min-h-9"
+        // This box IS the field in this state, so it is what the host label
+        // names (objectui#3990).
+        hostGroupProps={hostGroupProps}
       />
     );
   }
diff --git a/packages/fields/src/widgets/RatingField.tsx b/packages/fields/src/widgets/RatingField.tsx
index e46c6854fe..6d1fb0082e 100644
--- a/packages/fields/src/widgets/RatingField.tsx
+++ b/packages/fields/src/widgets/RatingField.tsx
@@ -3,6 +3,7 @@ import { Star } from 'lucide-react';
 import { cn } from '@object-ui/components';
 import { FieldWidgetComponentProps } from './types';
 import { toDomProps } from './toDomProps';
+import { toHostGroupProps } from './toHostGroupProps';
 
 /**
  * Rating field widget - provides a star rating input
@@ -19,8 +20,11 @@ export function RatingField({ value, onChange, field, readonly, className, error
   const displayValue = hoverValue !== null ? hoverValue : currentValue;
 
   if (readonly) {
+    // The readonly star row is the field's whole rendered surface, so it — not
+    // only the editable row below — consumes the host's group label
+    // (objectui#3990). See `toHostGroupProps`.
     return (
-      <div className={cn("flex items-center gap-1", className)}>
+      <div {...toHostGroupProps(props)} className={cn("flex items-center gap-1", className)}>
         {Array.from({ length: max }, (_, i) => (
           <Star
             key={i}
diff --git a/packages/fields/src/widgets/toHostGroupProps.ts b/packages/fields/src/widgets/toHostGroupProps.ts
new file mode 100644
index 0000000000..faafbce861
--- /dev/null
+++ b/packages/fields/src/widgets/toHostGroupProps.ts
@@ -0,0 +1,102 @@
+/**
+ * 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.
+ */
+
+import { toDomProps } from './toDomProps';
+
+/**
+ * The props that make a group-labelled widget's rendered surface the thing its
+ * host label actually NAMES, on the surfaces that are not controls
+ * (objectui#3990).
+ *
+ * ## What it is for
+ *
+ * A widget declared `labelling: 'group'` (objectui#3961) is told by the form
+ * renderer: your label publishes an `id` and drops its `for`, so name yourself
+ * by IDREF. The renderer hands down exactly two facts that address the field as
+ * a WHOLE:
+ *
+ *  - `id` — the host's control id (`…-form-item`), the id the label's `for`
+ *    used to point at;
+ *  - `aria-labelledby` — the IDREF of that visible label.
+ *
+ * Every editable branch already consumes them inside its wider `toDomProps`
+ * spread. The branches that returned EARLY did not — a field-level
+ * `readonly: true`, or an option list with zero offered options — so the label
+ * published an id that no element in the document referenced. Measured on
+ * `origin/main`, one field per row, reading the host label against the DOM:
+ *
+ * ```
+ * multiselect  readonly+value   consumers=0  byLabelText=0  namedByRole=[]
+ * multiselect  readonly+empty   consumers=0  byLabelText=0  namedByRole=[]
+ * multiselect  zeroOptions      consumers=0  byLabelText=0  namedByRole=[]
+ * multiselect  editable         consumers=1  byLabelText=1  namedByRole=[group:1]
+ * ```
+ *
+ * All seven group-labelled types measured the same, in every readonly state.
+ * This is quieter than the dangling `for` #3961 replaced: a `for` that resolves
+ * to nothing can at least be swept for, while "a label published an id and
+ * nobody consumed it" looks like healthy markup.
+ *
+ * ## Why this narrow pair, and not the whole `toDomProps` result
+ *
+ * Everything else in the DOM pass-through addresses a CONTROL, and a readonly
+ * display has none: `aria-describedby` / `aria-required` are announced when
+ * focus lands on something focusable, `disabled` / `tabIndex` / the focus
+ * handlers only mean something on an interactive element, and `name` is
+ * DOM-legal on form controls only — on a `div` it is exactly the leak
+ * objectui#3291 sweeps for. Spreading the full result would also put the host's
+ * `className` on top of the widget's own, because the widgets whose readonly
+ * surface is a placeholder or a plain container (`EmptyValue`, `FileField`,
+ * `AddressField`) keep `className` inside `props`.
+ *
+ * ## Why `role` travels with the two keys
+ *
+ * `aria-labelledby` on a role-less `div` / `span` names NOTHING — `generic`
+ * prohibits an author name — so the pair is inert without a role that supports
+ * naming. `group` is the one that fits a readonly surface: it names a set of
+ * values (chips, checked labels, stars, file names, a formatted address)
+ * without promising the interactivity `textbox` or `radiogroup` would. It is
+ * deliberately NOT the role the same widget answers with while editable:
+ * `RadioField`'s readonly branch renders the chosen label as text with no radios
+ * left in it, and `FileField`'s renders file names with no dropzone button.
+ *
+ * The role is emitted ONLY when a host actually named the field, mirroring
+ * every editable branch's `isLabelledGroup` test: standalone rendering (the
+ * grid's inline cell editor, a bare SDUI node) hands down neither key, so every
+ * value here is `undefined`, React emits no attribute, and that markup stays
+ * byte-identical to what it was.
+ */
+export interface HostGroupProps {
+  /** The host's control id — the id its label would have pointed `for` at. */
+  id?: string;
+  /** IDREF of the host's visible label. */
+  'aria-labelledby'?: string;
+  /** `'group'` when — and only when — a host named this surface. */
+  role?: 'group';
+}
+
+/**
+ * Read the two whole-field keys out of a widget's leftover props, plus the role
+ * that makes them mean something. See {@link HostGroupProps}.
+ *
+ * Routed through {@link toDomProps} rather than reading `props` directly so the
+ * pair keeps ONE gate: those keys reach an element only if the DOM pass-through
+ * whitelist still forwards them, and its two compile-time assertions bind that
+ * whitelist to the props contract in both directions.
+ */
+export function toHostGroupProps(props: {
+  id?: string;
+  'aria-labelledby'?: string;
+}): HostGroupProps {
+  const { id, 'aria-labelledby': labelledBy } = toDomProps(props);
+  return {
+    id,
+    'aria-labelledby': labelledBy,
+    ...(labelledBy != null ? { role: 'group' as const } : null),
+  };
+}