From a02ad8567e8607965652569b3c0ffffea4de674c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 19:33:00 +0000
Subject: [PATCH] fix(fields,components): name composite field groups by IDREF
 instead of an inert `for` (#3961)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Six widgets rendered a visible group label that was the accessible name of
NOTHING. Two shapes, one outcome: `address` / `geolocation` replaced the
host's id with their own sub-input ids (#3343), so the label's `for` named an
id no element carried; `checkboxes` / `radio` / `rating` / `file` kept the id
but on a `div`, where `label for` is inert HTML (`HTMLLabelElement.control` is
null — it activates nothing and contributes no name).

The WAI-ARIA group pattern, driven by a declaration rather than by the host
guessing at widget DOM:

- core: `ComponentMeta.labelling?: 'control' | 'group'`. Optional and
  additive; absent means `'control'`.
- components: the form renderer branches on it. A `'group'` field's
  `FormLabel` publishes an `id` and drops its `for`; the widget receives
  `aria-labelledby`. The single-control path emits not one changed attribute
  (conditional spreads), so no field gains a second naming channel.
  `ui/form.tsx` is untouched — `FormLabel` spreads props after its own
  `htmlFor`, so both halves travel as ordinary props.
- fields: the six audited widgets declare `labelling: 'group'`. address /
  geolocation move only the host id to the group container; checkboxes /
  rating answer with `role="group"`; radio keeps Radix's more specific
  `radiogroup`; file takes the name on its dropzone with no invented group
  layer (one control, merely not a labelable element).

No new key in the widget props contract: `aria-*` is already declared on it
and forwarded by `toDomProps`, the channel `aria-required` (#3290) uses.

Unchanged on purpose: sub-labels keep naming their own inputs (an
`aria-labelledby` on the first sub-input would OVERRIDE its own label),
`aria-describedby` stays on the first focusable sub-input (#3318), the
sub-input ids of #3343 do not move, and standalone rendering emits no role
and no IDREF.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt
---
 .../composite-group-label-association-3961.md |  32 ++
 .../form-group-label-association.test.tsx     | 253 +++++++++++
 .../components/src/renderers/form/form.tsx    |  80 +++-
 packages/core/src/registry/Registry.ts        |  24 ++
 .../composite-group-label-e2e.test.tsx        | 392 ++++++++++++++++++
 .../group-labelling-declaration.test.ts       | 100 +++++
 packages/fields/src/index.tsx                 |  39 ++
 packages/fields/src/widgets/AddressField.tsx  |  34 +-
 .../fields/src/widgets/CheckboxesField.tsx    |   9 +
 packages/fields/src/widgets/FileField.tsx     |  12 +-
 .../fields/src/widgets/GeolocationField.tsx   |  23 +-
 packages/fields/src/widgets/RadioField.tsx    |  10 +-
 packages/fields/src/widgets/RatingField.tsx   |  11 +-
 13 files changed, 1011 insertions(+), 8 deletions(-)
 create mode 100644 .changeset/composite-group-label-association-3961.md
 create mode 100644 packages/components/src/renderers/form/__tests__/form-group-label-association.test.tsx
 create mode 100644 packages/fields/src/__tests__/composite-group-label-e2e.test.tsx
 create mode 100644 packages/fields/src/__tests__/group-labelling-declaration.test.ts

diff --git a/.changeset/composite-group-label-association-3961.md b/.changeset/composite-group-label-association-3961.md
new file mode 100644
index 0000000000..ec4a38c110
--- /dev/null
+++ b/.changeset/composite-group-label-association-3961.md
@@ -0,0 +1,32 @@
+---
+'@object-ui/core': minor
+'@object-ui/components': patch
+'@object-ui/fields': patch
+---
+
+Give composite and grouped field widgets a real accessible name: the form renderer now associates its label by IDREF for widgets that declare `labelling: 'group'`, instead of emitting a `<label for>` that nothing labelable answers (objectui#3961).
+
+Six widgets rendered a visible group label that named **nothing** in the accessibility tree. Measured in a real form, one field per row, reading each label's `for` against the DOM:
+
+```
+address      for=…-form-item -> MISSING            byLabelText=0   role+name=0
+geolocation  for=…-form-item -> MISSING            byLabelText=0   role+name=0
+checkboxes   for=…-form-item -> div                byLabelText=0   role+name=0
+radio        for=…-form-item -> div[radiogroup]    byLabelText=0   role+name=0
+rating       for=…-form-item -> div                byLabelText=0   role+name=0
+file         for=…-form-item -> div[role=button]   byLabelText=0   role+name=0
+```
+
+Two shapes, one outcome. `address` / `geolocation` spread the host's id onto their first sub-input and then replaced it with that input's own unique id (objectui#3343, correct in itself), so the `for` named an id no element carried — clicking "Shipping Address" did nothing and the group label was absent from the accessibility tree entirely. `checkboxes` / `radio` / `rating` / `file` kept the id, but on a `div`: a `<label for>` on a non-labelable element is inert HTML — `HTMLLabelElement.control` is `null`, so it activates nothing and contributes no name. A screen reader heard "Street Address", "City", "Alpha", "Beta" — never which group they belonged to.
+
+The fix is the WAI-ARIA group pattern, driven by a DECLARATION rather than by the host guessing at widget DOM:
+
+- `@object-ui/core` — `ComponentMeta` gains `labelling?: 'control' | 'group'`. Additive and optional; absent means `'control'`, which is every existing component's behaviour.
+- `@object-ui/components` — the form renderer reads it. For a `'group'` field the `<FormLabel>` publishes an `id` and drops its `for`, and the widget receives `aria-labelledby`. The single-control path is unchanged down to the attribute: no id on the label, no `aria-labelledby` key on the widget, so no field acquires a second naming channel. `ui/form.tsx` is untouched (Shadcn no-touch) — both halves travel as ordinary props, since `<FormLabel>` spreads props after its own `htmlFor`.
+- `@object-ui/fields` — the six audited widgets declare `labelling: 'group'`. `address` / `geolocation` move the host id (and only the id) from their first sub-input to the group container; `checkboxes` / `rating` answer a host-supplied `aria-labelledby` with `role="group"`; `radio` keeps Radix's more specific `radiogroup`; `file` takes the name on its dropzone with no invented group layer, because it has exactly one control that merely happens not to be labelable.
+
+No new key in the widget props contract: `aria-*` is already declared on it and forwarded by `toDomProps`, the same channel `aria-required` (objectui#3290) travels.
+
+Deliberately unchanged: sub-labels keep naming their own inputs (`aria-labelledby` overrides `<label for>`, so putting the group name on the first sub-input would have replaced "Street Address" with the field name — the concatenated-name outcome this issue rejected), `aria-describedby` stays on the first focusable sub-input where focus can reach it (objectui#3318), the sub-input ids of objectui#3343 do not move, and standalone rendering — the inline grid editor, a bare SDUI node, where nobody hands down an id and there is no host label to point at — emits no role and no IDREF at all.
+
+A widget that does not declare itself keeps the old `for`, which the label-association tests report as an association resolving to a non-labelable element. Silence was the failure mode being fixed; the default path stays loud.
diff --git a/packages/components/src/renderers/form/__tests__/form-group-label-association.test.tsx b/packages/components/src/renderers/form/__tests__/form-group-label-association.test.tsx
new file mode 100644
index 0000000000..8081d3f8c1
--- /dev/null
+++ b/packages/components/src/renderers/form/__tests__/form-group-label-association.test.tsx
@@ -0,0 +1,253 @@
+/**
+ * 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.
+ */
+
+/**
+ * A field whose widget is NOT a labelable element gets its label associated by
+ * IDREF instead of `for` (objectui#3961) — the host half of the fix.
+ *
+ * The defect: `<FormLabel>` emits `htmlFor={formItemId}` unconditionally. For a
+ * single `<input>` that is correct and complete. For a composite widget it is
+ * inert HTML: `address` / `geolocation` overwrote the handed-down id with their
+ * sub-input ids, so the `for` named an id NOTHING carried; `checkboxes` / `radio`
+ * / `rating` / `file` kept it, but on a `div`, and `<label for>` pointing at a
+ * non-labelable element activates nothing and contributes no accessible name
+ * (`HTMLLabelElement.control` is `null`). Measured on `origin/main`, all six
+ * visible group labels were the accessible name of NOTHING.
+ *
+ * The host cannot infer which case it is from the DOM the widget renders, so the
+ * widget DECLARES it (`ComponentMeta.labelling`) and this renderer branches:
+ *
+ *   • `'group'` → the label publishes an `id` and drops its `for`; the widget
+ *     receives `aria-labelledby` pointing at it (IDREF works on any element).
+ *   • anything else, including undeclared → unchanged, byte for byte.
+ *
+ * That second bullet is why the tests below assert on KEY PRESENCE as well as on
+ * values: the single-control path must not acquire a second naming channel. One
+ * fact, one author — the same rule that kept `required` out of the widget
+ * contract (#3290), the message text out of it (#3222), and the duplicate label
+ * out of `BooleanField` (#3952).
+ *
+ * No `ui/form.tsx` change is involved (AGENTS.md #7 Shadcn no-touch):
+ * `<FormLabel>` spreads its props onto `Label` AFTER its own `htmlFor`, so both
+ * halves travel as ordinary props.
+ */
+
+import { describe, it, expect, beforeAll, afterEach, vi } from 'vitest';
+import { render, screen, 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';
+
+/**
+ * Stands in for a real composite widget (`@object-ui/components` tests never load
+ * `@object-ui/fields`) and mirrors the mechanism the fix relies on: spread the
+ * leftover props onto the container it renders, and answer a host-supplied
+ * `aria-labelledby` with the matching role.
+ *
+ * `data-labelledby-key` distinguishes "the renderer computed nothing" from "a
+ * strip function ate the prop" — the failure mode #3231's `emptyHint` had, and
+ * the only thing that tells the two apart.
+ */
+function GroupProbe(props: any) {
+  const { name, value, onChange, field: _field, error: _error, ...rest } = props;
+  return (
+    <div
+      data-testid={`group-${name}`}
+      data-labelledby-key={'aria-labelledby' in props ? 'yes' : 'no'}
+      role={props['aria-labelledby'] ? 'group' : undefined}
+      {...rest}
+    >
+      <label htmlFor={`${name}-part-a`}>Part A</label>
+      <input id={`${name}-part-a`} value={(value as string) ?? ''} onChange={(e) => onChange?.(e.target.value)} />
+    </div>
+  );
+}
+
+/** Same widget, registered WITHOUT the declaration — the control path. */
+function ControlProbe(props: any) {
+  const { name, value, onChange, field: _field, error: _error, ...rest } = props;
+  return (
+    <input
+      data-testid={`control-${name}`}
+      data-labelledby-key={'aria-labelledby' in props ? 'yes' : 'no'}
+      value={(value as string) ?? ''}
+      onChange={(e) => onChange?.(e.target.value)}
+      {...rest}
+    />
+  );
+}
+
+beforeAll(() => {
+  ComponentRegistry.register('groupprobe', GroupProbe, { namespace: 'field', labelling: 'group' });
+  ComponentRegistry.register('controlprobe', ControlProbe, { namespace: 'field' });
+  // Declared `group` under a name the renderer treats as BUILTIN. Nothing should
+  // read this declaration: `renderFieldComponent` never consults the registry for
+  // a builtin type, so honouring it here would re-address the label of a control
+  // this widget does not render. Pinned by the last test in this file.
+  ComponentRegistry.register('select', GroupProbe, { namespace: 'field', labelling: 'group' });
+}, 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: false,
+        showCancel: false,
+        defaultValues,
+        fields,
+      }}
+    />,
+  );
+}
+
+/** The visible label of `name`'s form item. */
+function hostLabel(name: string): HTMLLabelElement {
+  const el = document.querySelector(`[data-field="${name}"] label`);
+  if (!el) throw new Error(`no label rendered for field "${name}"`);
+  return el as HTMLLabelElement;
+}
+
+describe('form renderer — a declared GROUP widget is labelled by IDREF (objectui#3961)', () => {
+  it('names the group container, which a `for` could not do', () => {
+    renderForm([{ name: 'shipping', label: 'Shipping Address', type: 'groupprobe' }]);
+
+    // The one assertion that was 0 before the fix and is 1 after: an element in
+    // the accessibility tree whose NAME is the visible group label.
+    const group = screen.getByRole('group', { name: 'Shipping Address' });
+    expect(group).toBe(screen.getByTestId('group-shipping'));
+  });
+
+  it('gives the label an id and takes its `for` away', () => {
+    renderForm([{ name: 'shipping', label: 'Shipping Address', type: 'groupprobe' }]);
+
+    const label = hostLabel('shipping');
+    // `htmlFor: undefined` through the props spread is not a no-op — `<FormLabel>`
+    // sets `htmlFor` BEFORE spreading, so this is what removes the attribute. A
+    // `for` left in place beside the `aria-labelledby` would give one label two
+    // association channels, one of them inert.
+    expect(label).not.toHaveAttribute('for');
+    expect(label.id).not.toBe('');
+    expect(screen.getByTestId('group-shipping')).toHaveAttribute('aria-labelledby', label.id);
+  });
+
+  it('the IDREF resolves to an element that exists', () => {
+    // `aria-labelledby` pointing at a missing id fails SILENTLY — no warning, no
+    // name, nothing to notice. Measured while writing this fix: a dangling IDREF
+    // and a correct one are indistinguishable in the markup.
+    renderForm([{ name: 'shipping', label: 'Shipping Address', type: 'groupprobe' }]);
+
+    const idref = screen.getByTestId('group-shipping').getAttribute('aria-labelledby')!;
+    expect(document.getElementById(idref)).toBe(hostLabel('shipping'));
+  });
+
+  it('two group fields in one form get distinct label ids', () => {
+    renderForm([
+      { name: 'shipping', label: 'Shipping Address', type: 'groupprobe' },
+      { name: 'billing', label: 'Billing Address', type: 'groupprobe' },
+    ]);
+
+    const shipping = hostLabel('shipping').id;
+    const billing = hostLabel('billing').id;
+    expect(shipping).not.toBe(billing);
+    // A shared id would make BOTH groups announce the first label.
+    expect(screen.getByRole('group', { name: 'Shipping Address' })).toBe(screen.getByTestId('group-shipping'));
+    expect(screen.getByRole('group', { name: 'Billing Address' })).toBe(screen.getByTestId('group-billing'));
+  });
+
+  it('emits an id with no whitespace, because IDREFs are space-separated', () => {
+    // `aria-labelledby` is a LIST attribute. An id containing a space silently
+    // resolves to two ids, neither of which exists — the dangling-IDREF failure
+    // above, arrived at from a field name rather than from a bug.
+    renderForm([{ name: 'ship to', label: 'Ship To', type: 'groupprobe' }]);
+
+    const id = hostLabel('ship to').id;
+    expect(id).not.toMatch(/\s/);
+    expect(document.getElementById(id)).not.toBeNull();
+    expect(screen.getByRole('group', { name: 'Ship To' })).toHaveAttribute('aria-labelledby', id);
+  });
+
+  it('passes no label id when the field renders no label at all', () => {
+    // Compact layouts and inline grid editing render a field with no `<FormLabel>`.
+    // There is then no element to point at, and an `aria-labelledby` naming a
+    // missing id is worse than none: it suppresses nothing but resolves to
+    // nothing either.
+    renderForm([{ name: 'shipping', type: 'groupprobe' }]);
+
+    const probe = screen.getByTestId('group-shipping');
+    expect(probe).toHaveAttribute('data-labelledby-key', 'no');
+    expect(probe).not.toHaveAttribute('aria-labelledby');
+    expect(probe).not.toHaveAttribute('role');
+  });
+});
+
+describe('form renderer — the single-control path is untouched (objectui#3961)', () => {
+  it('keeps `for` → id and hands the widget no second naming channel', () => {
+    renderForm([{ name: 'title', label: 'Title', type: 'controlprobe' }]);
+
+    const input = screen.getByTestId('control-title');
+    const label = hostLabel('title');
+    // Unchanged association: `for` names the id `<FormControl>`'s Slot injected.
+    expect(label.getAttribute('for')).toBe(input.getAttribute('id'));
+    expect(label.id).toBe('');
+    // Not merely "no attribute" — the KEY never reaches the widget. An
+    // `aria-labelledby` alongside the working `for` would give one label two
+    // authors, and `aria-labelledby` WINS over `<label for>`, so a future
+    // divergence between them would silently rename every field.
+    expect(input).toHaveAttribute('data-labelledby-key', 'no');
+    expect(input).not.toHaveAttribute('aria-labelledby');
+    expect(screen.getByLabelText('Title')).toBe(input);
+  });
+
+  it('an UNDECLARED composite still takes the control path — and stays detectable', () => {
+    // The safe default, and the reason the declaration is worth its cost: a new
+    // composite widget that forgets to declare itself does not silently emit an
+    // `aria-labelledby` onto a role-less container. It keeps the `for`, which the
+    // label-association pins (objectui#3952 / this issue's fields e2e) report as
+    // an association that resolves to a non-labelable element.
+    ComponentRegistry.register('undeclaredgroup', GroupProbe, { namespace: 'field' });
+    renderForm([{ name: 'shipping', label: 'Shipping Address', type: 'undeclaredgroup' }]);
+
+    const label = hostLabel('shipping');
+    expect(label).toHaveAttribute('for');
+    const target = document.getElementById(label.getAttribute('for')!);
+    expect(target).toBe(screen.getByTestId('group-shipping'));
+    // …and that target is a `div`: the inert association this issue is about.
+    expect(target!.tagName.toLowerCase()).toBe('div');
+    expect(screen.queryAllByLabelText('Shipping Address')).toHaveLength(0);
+  });
+
+  it('a BUILTIN type ignores a registry declaration under the same name', () => {
+    // `renderFieldComponent` resolves a bare `select` to the builtin `<Select>`
+    // branch and never consults the registry, so `resolveFieldLabelling` must not
+    // either — reading `field:select`'s declaration would strip the `for` off a
+    // label whose control is the builtin trigger, breaking a working field on
+    // behalf of a widget that is not rendering.
+    renderForm([
+      {
+        name: 'status',
+        label: 'Status',
+        type: 'select',
+        options: [{ label: 'Draft', value: 'draft' }],
+      },
+    ]);
+
+    const label = hostLabel('status');
+    expect(label).toHaveAttribute('for');
+    expect(label.id).toBe('');
+    expect(document.querySelector('[data-testid="group-status"]')).toBeNull();
+  });
+});
diff --git a/packages/components/src/renderers/form/form.tsx b/packages/components/src/renderers/form/form.tsx
index 55298b2de3..271bed5eb9 100644
--- a/packages/components/src/renderers/form/form.tsx
+++ b/packages/components/src/renderers/form/form.tsx
@@ -323,6 +323,35 @@ function normalizeFieldType(type: string): string {
   return type.startsWith('field:') ? type.slice('field:'.length) : type;
 }
 
+/**
+ * How this field's label must be associated with what the widget renders
+ * (`ComponentMeta.labelling`, objectui#3961) — `'control'` for a labelable
+ * element (plain `<label for>`), `'group'` for a composite container or another
+ * non-labelable control (`aria-labelledby` by IDREF).
+ *
+ * The DECLARATION is authoritative; this function only resolves WHOSE
+ * declaration applies, and it mirrors `renderFieldComponent`'s resolution
+ * exactly so producer and consumer cannot disagree about which component will
+ * actually render:
+ *
+ *  - the builtin test is on the RAW type, exactly as there: a bare `select`
+ *    renders the builtin `<Select>` branch and the registry is never consulted,
+ *    while a `field:`-qualified `field:select` DOES resolve to the registered
+ *    widget. Normalizing before this test would let a widget's declaration
+ *    re-address the label of a builtin that renders in its place;
+ *  - only then is the `field:` prefix stripped, to the key `getMeta` stores.
+ *
+ * Anything undeclared — third-party widgets, bare-name SDUI components, an
+ * unregistered type — resolves to `'control'`: the single-control path, byte for
+ * byte what this renderer emitted before the declaration existed.
+ */
+function resolveFieldLabelling(type: string): 'control' | 'group' {
+  if (BUILTIN_FIELD_TYPES.has(type)) return 'control';
+  return ComponentRegistry.getMeta(normalizeFieldType(type), 'field')?.labelling === 'group'
+    ? 'group'
+    : 'control';
+}
+
 function stripRegisteredFieldProps(type: string, props: RenderFieldProps): RenderFieldProps {
   const {
     dataSource,
@@ -508,6 +537,15 @@ function FullscreenTextarea({
 ComponentRegistry.register('form',
   ({ schema, className, onAction, ...props }: { schema: FormSchema; className?: string; onAction?: (action: any) => void; [key: string]: any }) => {
     const { t } = useSafeFormTranslation();
+    // Prefix for the label ids the GROUP-labelled fields need (objectui#3961).
+    // Owned here, not derived from `<FormItem>`'s own `useId()`: that id lives in
+    // a context published INSIDE `FormItem`, and this renderer builds the label
+    // element as a child of it — one render too early to read it. It is also the
+    // reason the fix needs no change to `ui/form.tsx` (AGENTS.md #7 no-touch):
+    // `<FormLabel>` spreads its props onto `Label` AFTER its own `htmlFor`, so
+    // both halves — give the label an `id`, take its `for` away — travel as
+    // ordinary props.
+    const labelIdPrefix = React.useId();
     const {
       defaultValues: authoredDefaultValues = {},
       // The persisted record being edited (absent ⇒ this is an insert). Binds
@@ -1576,6 +1614,22 @@ ComponentRegistry.register('form',
       // the form schema has no owning object.
       const fieldTestId = `field:${schema.objectName ? `${schema.objectName}.` : ''}${name}`;
 
+      // Group-labelled widget (objectui#3961)? Then the visible label is
+      // associated by IDREF instead of `for`: it gets an `id`, the widget gets
+      // `aria-labelledby`. `undefined` on the single-control path, and every use
+      // below is a conditional spread, so that path emits not one changed
+      // attribute — no second naming channel for the widgets that never needed
+      // one (the #3290 / #3222 / #3952 rule: one fact, one author).
+      //
+      // Whitespace is squeezed out of the field name because this id is consumed
+      // as an `aria-labelledby` IDREF, and that attribute is a SPACE-SEPARATED
+      // list: an id containing a space would silently resolve to two ids,
+      // neither of which exists.
+      const groupLabelId =
+        label && resolveFieldLabelling(resolvedType) === 'group'
+          ? `${labelIdPrefix}${String(name).replace(/\s+/g, '_')}-group-label`
+          : undefined;
+
       return (
         <FormField
           key={fieldKey}
@@ -1589,7 +1643,18 @@ ComponentRegistry.register('form',
               data-field={name}
             >
               {label && (
-                <FormLabel className="text-xs font-normal text-muted-foreground">
+                <FormLabel
+                  className="text-xs font-normal text-muted-foreground"
+                  // A group-labelled widget (objectui#3961) is named by IDREF:
+                  // publish the label's own `id` and drop the `for`. `htmlFor:
+                  // undefined` is not a no-op — `<FormLabel>` sets
+                  // `htmlFor={formItemId}` BEFORE spreading its props, so this
+                  // key removes the attribute. It has to go: a `for` naming a
+                  // `div` (or nothing at all) is inert HTML, and leaving it
+                  // beside the `aria-labelledby` would give one label two
+                  // association channels, one of which is broken.
+                  {...(groupLabelId ? { id: groupLabelId, htmlFor: undefined } : null)}
+                >
                   {label}
                   {required && (
                     // Purely visual redundancy now that `aria-required` rides
@@ -1716,6 +1781,19 @@ ComponentRegistry.register('form',
                   // UIs, one field. `aria-required` reports the state without
                   // triggering native validation.
                   'aria-required': required || undefined,
+                  // The IDREF half of the group-labelled association
+                  // (objectui#3961). Like `aria-required` this needs no new key
+                  // in the widget contract — `aria-*` is declared on it as
+                  // React's `AriaAttributes`, neither strip touches the prefix,
+                  // and `toDomProps` forwards the whole `aria-` family — so the
+                  // widget's existing spread carries it to the element it puts
+                  // the host's `id` on. The widgets that render a real composite
+                  // additionally answer with `role="group"`; `file`, whose single
+                  // control is a `div[role="button"]`, just takes the name.
+                  //
+                  // Spread conditionally so the single-control path receives no
+                  // such key at all: absent, not `undefined`.
+                  ...(groupLabelId ? { 'aria-labelledby': groupLabelId } : null),
                 })}
               </FormControl>
               {description && (
diff --git a/packages/core/src/registry/Registry.ts b/packages/core/src/registry/Registry.ts
index 3f4db2ab62..5934ced76d 100644
--- a/packages/core/src/registry/Registry.ts
+++ b/packages/core/src/registry/Registry.ts
@@ -45,6 +45,30 @@ export type ComponentMeta = {
    * registry.register('form', FormView, { namespace: 'view', skipFallback: true });
    */
   skipFallback?: boolean;
+  /**
+   * How a HOST must associate its own visible label with what this component
+   * renders (objectui#3961). Read by the form renderer; absent ⇒ `'control'`.
+   *
+   * - `'control'` — the component's outermost rendered element is a LABELABLE
+   *   HTML element (`input` / `textarea` / `select` / `button` / …), so the host
+   *   associates its label the plain way: `<label for>` → the id the host handed
+   *   down. This is the default and covers every single-control widget.
+   * - `'group'` — it is NOT labelable: either a real composite (several inputs
+   *   under one container, e.g. `address`) or a single control that is not a
+   *   labelable element (a `div[role="button"]` dropzone, e.g. `file`). A
+   *   `<label for>` pointing at such an element is inert in HTML — it activates
+   *   nothing and contributes no accessible name (`HTMLLabelElement.control` is
+   *   `null`) — so the host must instead give its label an `id` and hand the
+   *   component `aria-labelledby`, which associates by IDREF and works on any
+   *   element.
+   *
+   * This is a DECLARATION, not a guess: the host cannot infer it from the DOM a
+   * widget happens to render, and a widget that fails to declare it falls back
+   * to the `'control'` path where the dangling/inert `for` is caught by the
+   * label-association tests (objectui#3952) instead of silently producing an
+   * unlabelled group.
+   */
+  labelling?: 'control' | 'group';
   inputs?: ComponentInput[];
   defaultProps?: Record<string, any>; // Default props when dropped
   defaultChildren?: SchemaNode[]; // Default children when dropped
diff --git a/packages/fields/src/__tests__/composite-group-label-e2e.test.tsx b/packages/fields/src/__tests__/composite-group-label-e2e.test.tsx
new file mode 100644
index 0000000000..d516aa23da
--- /dev/null
+++ b/packages/fields/src/__tests__/composite-group-label-e2e.test.tsx
@@ -0,0 +1,392 @@
+/**
+ * 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 composite / grouped field's VISIBLE label is the accessible name
+ * of the thing the widget renders (objectui#3961).
+ *
+ * The sibling case of #3952 (`BooleanField`, a single control that renamed the
+ * host's id). Here the widget has no single labelable control to hand the label
+ * to, and the failure came in two shapes — measured in a real form on
+ * `origin/main`, one field per row, reading each `<label for>` against the DOM:
+ *
+ * ```
+ * address      for=_r_0_-form-item -> MISSING          byLabelText=0   role+name=0
+ * geolocation  for=_r_2_-form-item -> MISSING          byLabelText=0   role+name=0
+ * checkboxes   for=_r_4_-form-item -> div              byLabelText=0   role+name=0
+ * radio        for=_r_6_-form-item -> div[radiogroup]   byLabelText=0   role+name=0
+ * rating       for=_r_a_-form-item -> div              byLabelText=0   role+name=0
+ * file         for=_r_b_-form-item -> div[role=button] byLabelText=0   role+name=0
+ * ```
+ *
+ *  - **id overwritten** (`address` / `geolocation`): the host id was spread onto
+ *    the first sub-input and then replaced by that input's own `subId(...)`
+ *    (objectui#3343 — correctly, sub-inputs need unique ids), so the `for` named
+ *    an id NOTHING carried. Clicking "Shipping Address" did nothing and the group
+ *    label was absent from the accessibility tree entirely.
+ *  - **id kept, on a `div`** (`checkboxes` / `radio` / `rating` / `file`): the
+ *    `for` "resolved", but `<label for>` on a non-labelable element is inert —
+ *    `HTMLLabelElement.control` is `null`, so it activates nothing and
+ *    contributes no name. Both columns on the right show it: zero elements named
+ *    by that label, in either query.
+ *
+ * So all six ended in the same place — a visible label that names NOTHING — and
+ * the fix is the WAI-ARIA group pattern: the widget declares that it must be
+ * named by IDREF (`ComponentMeta.labelling: 'group'`), the form renderer
+ * publishes its label's `id` and drops the `for`, and the widget's group
+ * container answers with `role="group"` + the handed-down `aria-labelledby`.
+ *
+ * Two directions per widget, because a one-directional pin here is nearly free to
+ * pass by accident: the name must be present when hosted, and STANDALONE
+ * rendering (the inline grid editor, a bare SDUI node — nobody hands an id, and
+ * there is no host label to point at) must stay exactly as it was.
+ *
+ * The widgets are 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 components, no Suspense boundary. The
+ * DECLARATION that ships with the real registration is pinned separately, in
+ * `group-labelling-declaration.test.ts`.
+ */
+
+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 { TextField } from '../widgets/TextField';
+
+/**
+ * The role each widget's named surface answers with. Not uniform, and
+ * deliberately so:
+ *
+ *  - `radio` keeps `radiogroup` — already a member of the group role family, more
+ *    specific than `group`, and the correct carrier of `aria-invalid` for a set
+ *    of radios (#3318). Overriding it with `group` would be a regression.
+ *  - `file` is `button`: it is NOT a composite — it has exactly one control, the
+ *    dropzone, which is a `div[role="button"]` (the keyboard path to the hidden
+ *    file input). It needs IDREF labelling because a `div` cannot be
+ *    `for`-labelled, not because it is a group, so no `role="group"` wrapper is
+ *    invented for it.
+ */
+const HOSTED: Array<[type: string, role: string]> = [
+  ['address', 'group'],
+  ['geolocation', 'group'],
+  ['checkboxes', 'group'],
+  ['radio', 'radiogroup'],
+  ['rating', 'group'],
+  ['file', 'button'],
+];
+
+const OPTIONS = [
+  { label: 'Alpha', value: 'a' },
+  { label: 'Beta', value: 'b' },
+];
+
+const WIDGETS: Record<string, any> = {
+  address: AddressField,
+  geolocation: GeolocationField,
+  checkboxes: CheckboxesField,
+  radio: RadioField,
+  rating: RatingField,
+  file: FileField,
+};
+
+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',
+    });
+  }
+  // Positive control: an ordinary single-control widget, undeclared.
+  ComponentRegistry.register('text', TextField as any, { namespace: 'field', skipFallback: true });
+}, 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']);
+
+/**
+ * Every `<label for=…>` in the document, with what it resolves to and whether
+ * that target can legally be labelled. Both failure shapes of this issue appear
+ * here: `resolves: false` is the overwritten-id case, `labelable: false` the
+ * inert-`div` case.
+ */
+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 !== '');
+}
+
+function fieldConfig(type: string) {
+  const config: any = { name: `f_${type}`, label: `Group Label ${type}`, type };
+  if (type === 'checkboxes' || type === 'radio') config.options = OPTIONS;
+  return config;
+}
+
+/** The real form renderer hosting one field — the #3961 reproduction. */
+function renderForm(fields: any[]) {
+  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 form-hosted composite field is NAMED by its host label (objectui#3961)', () => {
+  it.each(HOSTED)('%s: the host label is the accessible name of the %s', (type, role) => {
+    renderForm([fieldConfig(type)]);
+
+    // The assertion that was 0 before this fix and is 1 after, for all six.
+    const named = screen.getAllByRole(role, { name: `Group Label ${type}` });
+    expect(named).toHaveLength(1);
+    // `getByLabelText` resolves the same association from the other side.
+    expect(screen.getAllByLabelText(`Group Label ${type}`)).toEqual(named);
+  });
+
+  it.each(HOSTED)('%s: the named element is the one the host handed its id to', (type, role) => {
+    // The host id and the host name must land on the SAME element. They came
+    // apart in both directions before: `address` dropped the id (overwritten by a
+    // sub-input's), `checkboxes` kept it on a container the label could not name.
+    renderForm([fieldConfig(type)]);
+
+    const named = screen.getByRole(role, { name: `Group Label ${type}` });
+    expect(named.getAttribute('id')).toMatch(/-form-item$/);
+  });
+
+  it.each(HOSTED)('%s: the host label emits an id and no `for`', (type) => {
+    renderForm([fieldConfig(type)]);
+
+    const label = hostLabelOf(`f_${type}`);
+    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.
+    expect(document.getElementById(label.id)).toBe(label);
+  });
+
+  it.each(HOSTED)('%s: no label in the field is left with an inert or dangling `for`', (type) => {
+    // The class-wide invariant this issue is an instance of, and the one that 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.
+    renderForm([fieldConfig(type)]);
+
+    expect(labelTargets().filter((l) => !l.resolves)).toEqual([]);
+    expect(labelTargets().filter((l) => !l.labelable)).toEqual([]);
+  });
+
+  it('all six in ONE form: every group is named, every `for` still resolves', () => {
+    renderForm(HOSTED.map(([type]) => fieldConfig(type)));
+
+    for (const [type, role] of HOSTED) {
+      expect(screen.getAllByRole(role, { name: `Group Label ${type}` })).toHaveLength(1);
+    }
+    expect(labelTargets().filter((l) => !l.resolves || !l.labelable)).toEqual([]);
+  });
+});
+
+describe('the group name does not swallow the sub-controls\' own names (objectui#3961)', () => {
+  it('address sub-inputs keep their own labels', () => {
+    // Why `aria-labelledby` is held back from the first sub-input rather than
+    // riding along with the rest of the DOM pass-through: `aria-labelledby`
+    // OVERRIDES a control's `<label for>`. Spread onto the street box, the group
+    // name would REPLACE "Street Address" — the "one input, two labels,
+    // concatenated name" outcome the issue rejected option 2 for.
+    renderForm([fieldConfig('address')]);
+
+    expect(screen.getByLabelText('Street Address')).toHaveAccessibleName('Street Address');
+    expect(screen.getByLabelText('City')).toHaveAccessibleName('City');
+    expect(screen.getByLabelText('Street Address')).not.toHaveAttribute('aria-labelledby');
+  });
+
+  it('the description stays on the first focusable sub-input, not on the container', () => {
+    // #3318's deliberate choice, preserved: only the `id` moved out to the
+    // container. A description or error must be announced when focus lands on
+    // something focusable, and a group container is not focusable — so
+    // `aria-describedby` stays where a screen reader will actually reach it.
+    renderForm([{ ...fieldConfig('address'), description: 'Where we ship it' }]);
+
+    const street = screen.getByLabelText('Street Address');
+    expect(street.getAttribute('aria-describedby')).toContain('-form-item-description');
+    const group = screen.getByRole('group', { name: 'Group Label address' });
+    expect(group).not.toHaveAttribute('aria-describedby');
+  });
+
+  it('checkboxes options keep their per-option labels', () => {
+    renderForm([fieldConfig('checkboxes')]);
+
+    expect(screen.getByLabelText('Alpha')).toHaveAttribute('role', 'checkbox');
+    expect(screen.getByLabelText('Beta')).toHaveAttribute('role', 'checkbox');
+  });
+});
+
+describe('an undeclared single-control field keeps the plain `for` association (objectui#3961)', () => {
+  it('text: the label still points at the input, with no second naming channel', () => {
+    // The positive control for the DECLARATION. `text` is not in
+    // `FIELD_TYPES_GROUP_LABELLED`, so it must travel the unchanged path: a
+    // working `for`, and NO `aria-labelledby` — two channels naming one control
+    // is what #3290 / #3222 / #3952 each refused.
+    renderForm([{ name: 'f_text', label: 'Plain Text', type: 'text' }]);
+
+    const input = screen.getByLabelText('Plain Text');
+    expect(input.tagName.toLowerCase()).toBe('input');
+    expect(input).not.toHaveAttribute('aria-labelledby');
+    const label = hostLabelOf('f_text');
+    expect(label.getAttribute('for')).toBe(input.getAttribute('id'));
+    expect(label.id).toBe('');
+    expect(screen.queryAllByRole('group')).toHaveLength(0);
+  });
+
+  it('a group field and a control field in one form each get their own treatment', () => {
+    renderForm([{ name: 'f_text', label: 'Plain Text', type: 'text' }, fieldConfig('rating')]);
+
+    expect(hostLabelOf('f_text')).toHaveAttribute('for');
+    expect(hostLabelOf('f_rating')).not.toHaveAttribute('for');
+    expect(screen.getByRole('group', { name: 'Group Label rating' })).toBeTruthy();
+    expect(screen.getByLabelText('Plain Text').tagName.toLowerCase()).toBe('input');
+  });
+});
+
+describe('STANDALONE composite widgets are unchanged (objectui#3961)', () => {
+  // `FieldEditWidget` (the grid's inline cell editor) and bare SDUI nodes render
+  // these widgets with no id and no host label. There is nothing to associate, so
+  // nothing may be emitted: an unnamed `role="group"` adds no information and
+  // announces a container that has no name to give.
+
+  it('address: no group role, and every sub-label still resolves to its input', () => {
+    render(
+      <AddressField
+        value={{ street: '1 Main St' }}
+        onChange={() => {}}
+        field={{ name: 'shipping', label: 'Shipping Address', type: 'address' } as any}
+      />,
+    );
+
+    expect(screen.queryAllByRole('group')).toHaveLength(0);
+    expect(document.querySelector('[aria-labelledby]')).toBeNull();
+    expect(labelTargets().filter((l) => !l.resolves || !l.labelable)).toEqual([]);
+    // The sub-input ids of objectui#3343 are untouched: only the (absent) HOST id
+    // changed place.
+    expect(screen.getByLabelText('Street Address')).toHaveValue('1 Main St');
+  });
+
+  it('geolocation: no group role, sub-labels intact', () => {
+    render(
+      <GeolocationField
+        value={{ latitude: 1, longitude: 2 }}
+        onChange={() => {}}
+        field={{ name: 'where', label: 'Where', type: 'geolocation' } as any}
+      />,
+    );
+
+    expect(screen.queryAllByRole('group')).toHaveLength(0);
+    expect(document.querySelector('[aria-labelledby]')).toBeNull();
+    expect(labelTargets().filter((l) => !l.resolves || !l.labelable)).toEqual([]);
+    expect(screen.getByLabelText('Latitude')).toHaveValue(1);
+  });
+
+  it('checkboxes: the container stays a plain div', () => {
+    render(
+      <CheckboxesField
+        value={[]}
+        onChange={() => {}}
+        field={{ name: 'tags', label: 'Tags', type: 'checkboxes', options: OPTIONS } as any}
+      />,
+    );
+
+    expect(screen.queryAllByRole('group')).toHaveLength(0);
+    expect(screen.getByTestId('checkboxes-tags')).not.toHaveAttribute('role');
+  });
+
+  it('rating: the container stays a plain div', () => {
+    const { container } = render(
+      <RatingField
+        value={3}
+        onChange={() => {}}
+        field={{ name: 'score', label: 'Score', type: 'rating' } as any}
+      />,
+    );
+
+    expect(screen.queryAllByRole('group')).toHaveLength(0);
+    expect(container.firstElementChild).not.toHaveAttribute('role');
+  });
+
+  it('radio: the radiogroup survives without a name', () => {
+    render(
+      <RadioField
+        value={undefined as any}
+        onChange={() => {}}
+        field={{ name: 'plan', label: 'Plan', type: 'radio', options: OPTIONS } as any}
+      />,
+    );
+
+    // Radix owns this role; nothing in this change may take it away.
+    const group = screen.getByRole('radiogroup');
+    expect(group).not.toHaveAttribute('aria-labelledby');
+    expect(labelTargets().filter((l) => !l.resolves || !l.labelable)).toEqual([]);
+  });
+
+  it('file: the dropzone keeps role=button and gains no name it was not given', () => {
+    render(
+      <FileField
+        value={null}
+        onChange={() => {}}
+        field={{ name: 'attachment', label: 'Attachment', type: 'file' } as any}
+      />,
+    );
+
+    const dropzone = screen.getByRole('button');
+    expect(dropzone).not.toHaveAttribute('aria-labelledby');
+    expect(screen.queryAllByRole('group')).toHaveLength(0);
+  });
+});
diff --git a/packages/fields/src/__tests__/group-labelling-declaration.test.ts b/packages/fields/src/__tests__/group-labelling-declaration.test.ts
new file mode 100644
index 0000000000..401a98b6d7
--- /dev/null
+++ b/packages/fields/src/__tests__/group-labelling-declaration.test.ts
@@ -0,0 +1,100 @@
+/**
+ * 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 group-labelling DECLARATION, at the registration boundary (objectui#3961).
+ *
+ * A widget whose labelled surface is not a labelable HTML element cannot be
+ * reached by a host's `<label for>` — the association has to go by IDREF
+ * (`aria-labelledby`). Which widgets those are is a fact only the widget package
+ * knows, so it is DECLARED (`ComponentMeta.labelling`) rather than guessed by the
+ * form renderer from whatever DOM a widget happens to render.
+ *
+ * This file pins the declaration itself, separately from the rendered outcome
+ * (`composite-group-label-e2e.test.tsx`), because the two can fail apart:
+ *
+ *   • declared but not rendered → the widget's container never answers with a
+ *     role, so the name lands on a bare `div` (the e2e file catches that);
+ *   • rendered but not declared → the host keeps emitting `for`, the widget never
+ *     receives an `aria-labelledby`, and the group semantics are dead code. THIS
+ *     file is what fails then — an omission from the set is otherwise invisible,
+ *     since a missing declaration degrades silently to the single-control path.
+ *
+ * Nothing renders here, so `registerField`'s `React.lazy` wrapper is never
+ * resolved: this reads metadata only.
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { ComponentRegistry } from '@object-ui/core';
+import { registerAllFields } from '../index';
+
+/**
+ * Every field type whose host label must be associated by IDREF. Two shapes, one
+ * declaration — see `FIELD_TYPES_GROUP_LABELLED` in `../index`:
+ * real composites, plus `file`, whose single control is a `div[role="button"]`.
+ */
+const GROUP_LABELLED = ['address', 'geolocation', 'checkboxes', 'radio', 'rating', 'file'] as const;
+
+/**
+ * Single-control widgets: the host's `<label for>` reaches a real labelable
+ * element, so they must NOT be declared — that is the default path, and a stray
+ * `labelling: 'group'` here would take a working `for` association away from a
+ * control that needs it and hand it an `aria-labelledby` its markup ignores.
+ */
+const CONTROL_LABELLED = [
+  'text',
+  'textarea',
+  'number',
+  'boolean',
+  'date',
+  'datetime',
+  'email',
+  'phone',
+  'url',
+  'currency',
+  'percent',
+  'password',
+  'tags',
+  'color',
+  'code',
+  'user',
+  'lookup',
+  'select',
+] as const;
+
+beforeAll(() => {
+  registerAllFields();
+});
+
+describe('field widgets declare how their label must be associated (objectui#3961)', () => {
+  it.each(GROUP_LABELLED)('%s declares labelling: "group"', (type) => {
+    expect(ComponentRegistry.getMeta(type, 'field')?.labelling).toBe('group');
+  });
+
+  it.each(CONTROL_LABELLED)('%s leaves labelling undeclared (⇒ "control")', (type) => {
+    // Absent, not `'control'`: one spelling of the default, and the form
+    // renderer reads any non-`'group'` value as the single-control path.
+    expect(ComponentRegistry.getMeta(type, 'field')?.labelling).toBeUndefined();
+  });
+
+  it('declares group labelling for exactly the audited set — no more', () => {
+    // A widget added to `fieldWidgetMap` later inherits the single-control path,
+    // which is the safe default; if it is in fact a composite, the e2e pins
+    // (objectui#3952's "every label resolves to a real control") go red rather
+    // than this list quietly growing. This assertion is the other direction: it
+    // fails if someone declares a widget `group` without an audited group
+    // container to carry the name.
+    const declared = ComponentRegistry.getKnownTypes()
+      .filter((key) => key.startsWith('field:'))
+      .filter((key) => ComponentRegistry.getMeta(key.slice('field:'.length), 'field')?.labelling === 'group')
+      .map((key) => key.slice('field:'.length))
+      .sort();
+
+    expect(declared).toEqual([...GROUP_LABELLED].sort());
+  });
+});
diff --git a/packages/fields/src/index.tsx b/packages/fields/src/index.tsx
index 90204a9d2a..4606fb5e7e 100644
--- a/packages/fields/src/index.tsx
+++ b/packages/fields/src/index.tsx
@@ -2228,6 +2228,41 @@ const FIELD_TYPES_SKIP_FALLBACK = new Set([
   'recipient-picker',
 ]);
 
+/**
+ * Widgets whose labelled surface is NOT a labelable HTML element, so a host's
+ * `<label for>` cannot reach it and the association has to go by IDREF instead
+ * (`ComponentMeta.labelling`, objectui#3961). Two shapes, one declaration:
+ *
+ *  - real composites — `address` / `geolocation` render several inputs under one
+ *    container, and `checkboxes` / `radio` / `rating` a set of choice controls;
+ *    the host's label names the GROUP, each sub-control keeps its own sub-label.
+ *  - `file` is not composite at all: it has exactly ONE control, the dropzone,
+ *    which is a `div[role="button"]` (it is the keyboard path to the hidden file
+ *    input). It is here because a `div` cannot be `for`-labelled, not because it
+ *    is a group, and it renders NO `role="group"` — the dropzone itself takes the
+ *    `aria-labelledby`.
+ *
+ * Measured, not assumed: every entry was verified in a real form to be a widget
+ * whose host label either resolved to nothing (`address` / `geolocation`, whose
+ * sub-input ids overwrote the host id — objectui#3343) or resolved to an element
+ * that cannot carry it (`checkboxes` / `radio` / `rating` / `file`). In both
+ * shapes the visible group label was, before this declaration, the accessible
+ * name of NOTHING.
+ *
+ * A widget NOT listed here takes the single-control path unchanged. That is the
+ * safe default: the host keeps emitting `for`, and a composite that forgot to
+ * declare itself is caught by the label-association tests (objectui#3952) rather
+ * than silently emitting an `aria-labelledby` onto a container with no role.
+ */
+const FIELD_TYPES_GROUP_LABELLED = new Set([
+  'address',
+  'geolocation',
+  'checkboxes',
+  'radio',
+  'rating',
+  'file',
+]);
+
 export function registerField(fieldType: string): void {
   const loader = fieldWidgetMap[fieldType];
   if (!loader) {
@@ -2245,6 +2280,10 @@ export function registerField(fieldType: string): void {
   ComponentRegistry.register(fieldType, withFieldCarrier(LazyFieldWidget), {
     namespace: 'field',
     skipFallback: FIELD_TYPES_SKIP_FALLBACK.has(fieldType),
+    // Only the group-labelled widgets carry the key; everything else leaves it
+    // absent, which the form renderer reads as `'control'` (objectui#3961). One
+    // spelling of the default, in one place.
+    ...(FIELD_TYPES_GROUP_LABELLED.has(fieldType) ? { labelling: 'group' as const } : null),
   });
 }
 
diff --git a/packages/fields/src/widgets/AddressField.tsx b/packages/fields/src/widgets/AddressField.tsx
index f3a6308cd8..f0a376f8ea 100644
--- a/packages/fields/src/widgets/AddressField.tsx
+++ b/packages/fields/src/widgets/AddressField.tsx
@@ -54,7 +54,28 @@ export function AddressField({ value, onChange, field, readonly, error, ...props
   // the composite's validation state goes onto EVERY focusable sub-input via
   // `aria-invalid={!!error}` (a form-level failure means the whole address is
   // missing/invalid, and whichever sub-input the user reaches must announce it).
-  const domProps = toDomProps(props);
+  //
+  // Two keys are held back from that spread and land on the group CONTAINER
+  // instead (objectui#3961), because they address the field as a WHOLE:
+  //
+  //  - `id` — the host's control id. It never reached the DOM at all: it was
+  //    spread here and then overwritten one line later by `id={subId('street')}`
+  //    (objectui#3343), which is why the form's "Shipping Address" label pointed
+  //    at an id no element carried. The sub-input ids stay exactly as they are;
+  //    only the host id moves out to the element it was always meant to name.
+  //  - `aria-labelledby` — the host's label, associated by IDREF. On the street
+  //    input it would be actively wrong: `aria-labelledby` OVERRIDES a control's
+  //    `<label for>`, so the first sub-input would be announced as "Shipping
+  //    Address" and its own "Street Address" label would vanish.
+  //
+  // Everything else (`aria-describedby`, `name`, focus handlers …) deliberately
+  // 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,
+    ...domProps
+  } = toDomProps(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
@@ -96,7 +117,16 @@ export function AddressField({ value, onChange, field, readonly, error, ...props
   }
 
   return (
-    <div className="space-y-3">
+    // `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}
+    >
       <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 ce0a48e681..f7e52eec63 100644
--- a/packages/fields/src/widgets/CheckboxesField.tsx
+++ b/packages/fields/src/widgets/CheckboxesField.tsx
@@ -105,10 +105,19 @@ export function CheckboxesField({
     name: _domName,
     ...groupDomProps
   } = toDomProps(props);
+  // When the host associated its visible label with this container by IDREF
+  // (`aria-labelledby`, objectui#3961) the container IS the labelled group, so it
+  // answers with the matching role — without one, the name sits on a generic
+  // `div` and contributes nothing: `label for` pointing here was already inert
+  // (`HTMLLabelElement.control` is null for a div), which is the whole defect.
+  // Absent (standalone: the inline grid editor, a bare SDUI node) nothing is
+  // emitted and the markup is unchanged.
+  const isLabelledGroup = groupDomProps['aria-labelledby'] != null;
 
   return (
     <div
       {...groupDomProps}
+      role={isLabelledGroup ? 'group' : undefined}
       className={className}
       data-testid={fieldName ? `checkboxes-${fieldName}` : undefined}
     >
diff --git a/packages/fields/src/widgets/FileField.tsx b/packages/fields/src/widgets/FileField.tsx
index b68e879cac..2606e595df 100644
--- a/packages/fields/src/widgets/FileField.tsx
+++ b/packages/fields/src/widgets/FileField.tsx
@@ -240,7 +240,17 @@ export function FileField({ value, onChange, field, readonly, onUploadingChange,
             keyboard path to the hidden file input), so the DOM pass-through
             and the validation state land here (objectui#3318). `name` is
             withheld: only DOM-legal on form controls, and on this div it is
-            exactly the leak #3291 sweeps for. */}
+            exactly the leak #3291 sweeps for.
+
+            It also carries the host's label. This widget is declared
+            `labelling: 'group'` (objectui#3961) NOT because it is composite — it
+            has exactly one control — but because that one control is a
+            `div[role="button"]`, which no `<label for>` can reach. So the form
+            renderer names it by IDREF instead, and `aria-labelledby` arrives in
+            the same whitelist spread (`toDomProps` forwards the whole `aria-`
+            family). Deliberately no extra `role="group"` wrapper: there is no
+            group here, and adding one would announce a container that holds a
+            single button. */}
         <div
           {...dropzoneDomProps}
           onDragOver={handleDragOver}
diff --git a/packages/fields/src/widgets/GeolocationField.tsx b/packages/fields/src/widgets/GeolocationField.tsx
index 1e778b23a6..b0da6b1f60 100644
--- a/packages/fields/src/widgets/GeolocationField.tsx
+++ b/packages/fields/src/widgets/GeolocationField.tsx
@@ -23,7 +23,19 @@ export function GeolocationField({ value, onChange, field, readonly, error, ...p
   // DOM pass-through (objectui#3318): the whitelist spread goes onto the FIRST
   // sub-input (latitude); the composite's validation state goes onto BOTH
   // focusable sub-inputs via `aria-invalid={!!error}`.
-  const domProps = toDomProps(props);
+  //
+  // `id` and `aria-labelledby` are held back and land on the group CONTAINER
+  // instead (objectui#3961) — they address the whole field, not the latitude box.
+  // The host `id` never reached the DOM before: it was overwritten one line later
+  // by `id={subId('latitude')}` (objectui#3343), leaving the form's group label
+  // pointing at nothing. And `aria-labelledby` on the latitude input would
+  // 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,
+    ...domProps
+  } = toDomProps(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
@@ -100,7 +112,14 @@ export function GeolocationField({ value, onChange, field, readonly, error, ...p
   }
 
   return (
-    <div className="space-y-3">
+    // `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}
+    >
       <div className="flex items-center gap-2">
         <Button
           type="button"
diff --git a/packages/fields/src/widgets/RadioField.tsx b/packages/fields/src/widgets/RadioField.tsx
index faf8d8deb7..6129cb0cff 100644
--- a/packages/fields/src/widgets/RadioField.tsx
+++ b/packages/fields/src/widgets/RadioField.tsx
@@ -79,7 +79,15 @@ export function RadioField({
   }
 
   return (
-    // DOM pass-through onto the radiogroup (objectui#3318). Unlike Radix
+    // DOM pass-through onto the radiogroup (objectui#3318). It also carries the
+    // host's group label: when the form renderer associates its `<FormLabel>` by
+    // IDREF (`aria-labelledby`, objectui#3961) that key rides in this same
+    // whitelist spread — `toDomProps` forwards the whole `aria-` family — so this
+    // widget needs no branch of its own. `radiogroup` is already a member of the
+    // group role family, so nothing here overrides it with `role="group"`: it is
+    // the more specific role AND the correct carrier of `aria-invalid` below.
+    //
+    // Unlike Radix
     // `Select.Root` (#3306) this Root IS a real DOM element — a
     // `<div role="radiogroup">` — and `radiogroup` is exactly the role
     // WAI-ARIA designates to carry `aria-invalid` for a set of radios
diff --git a/packages/fields/src/widgets/RatingField.tsx b/packages/fields/src/widgets/RatingField.tsx
index 9e542ba14f..e46c6854fe 100644
--- a/packages/fields/src/widgets/RatingField.tsx
+++ b/packages/fields/src/widgets/RatingField.tsx
@@ -50,9 +50,18 @@ export function RatingField({ value, onChange, field, readonly, className, error
     name: _domName,
     ...groupDomProps
   } = toDomProps(props);
+  // When the host named this container by IDREF (`aria-labelledby`,
+  // objectui#3961) it IS the labelled group of stars, so it answers with the
+  // matching role; a `label for` pointing at this `div` was inert. Standalone
+  // (no host label) the markup is unchanged.
+  const isLabelledGroup = groupDomProps['aria-labelledby'] != null;
 
   return (
-    <div {...groupDomProps} className={cn("flex items-center gap-1", className)}>
+    <div
+      {...groupDomProps}
+      role={isLabelledGroup ? 'group' : undefined}
+      className={cn("flex items-center gap-1", className)}
+    >
       {Array.from({ length: max }, (_, i) => (
         <button
           key={i}