@object-ui/fields 17.3.0 → 17.5.0

package/src/standard-widgets.test.tsx

@@ -61,7 +61,14 @@ describe('Standard Field Widgets', () => {
           field={{ ...fieldMock, currency: 'EUR' } as any}
         />
       );
-      expect(screen.getByText('EUR')).toBeInTheDocument();
+      // Was `EUR`, the bare code: the adornment came from a hand-written
+      // `currency === 'USD' ? '$' : currency` ternary, so every currency but one
+      // fell through to its code. objectui#4414 converged the symbol on the
+      // single `Intl` channel the readonly branch of this same widget already
+      // formatted through, which answers `€` here — a DOCUMENTED change, pinned
+      // in full (with the locale-dependence it brings) in
+      // `__tests__/CurrencyField.symbol.test.tsx`.
+      expect(screen.getByText('€')).toBeInTheDocument();
     });
   });
 

package/src/widgets/AddressField.postalCode.test.tsx

@@ -0,0 +1,257 @@
+/**
+ * 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.
+ */
+
+/**
+ * Postal-code round trip of the composite `address` widget (objectstack#5143).
+ *
+ * The widget used to read and write the part name `zipCode`. The platform
+ * stores — and `/api/v1/data/**` serves back — `postalCode`, the name
+ * `@objectstack/spec`'s `AddressValueSchema` declares. The two never met:
+ *
+ *  - opening a stored address showed an EMPTY ZIP box (the stored
+ *    `postalCode` had no input reading it), and
+ *  - anything typed into that box was written back as `zipCode`, which the
+ *    enforced value schema strips (`$strip`) — destroying it at the contract
+ *    boundary: lost outright on a new record, and on an existing one silently
+ *    discarded while the stale stored code survived.
+ *
+ * Four of five parts round-tripped, which is what made it survive review.
+ *
+ * These tests pin BOTH directions, plus the read-time compatibility limb for
+ * data the broken build already wrote:
+ *
+ *  1. stored `postalCode` reaches the ZIP input;
+ *  2. every edit writes the postal code back under `postalCode` and never
+ *     under `zipCode` — verified against `AddressValueSchema.parse`, i.e. the
+ *     platform's own contract, not a local restatement of it;
+ *  3. a legacy `zipCode`-shaped value still DISPLAYS, and the first edit of
+ *     any part migrates it onto `postalCode` instead of writing the split
+ *     shape back out.
+ *
+ * Reverse verification (measured, not presumed — `git show origin/main` of the
+ * widget, this file unchanged): 9 of 12 go red — 1, 2, 5, 6, 7, 8, 9, 10, 12.
+ * The three that stay GREEN are worth naming, because one of them refines the
+ * issue's stated mechanism:
+ *
+ *  - 3 stays green. The old widget spread the WHOLE stored object through on
+ *    every write (`{...address, [part]: v}`), so an untouched `postalCode`
+ *    survived an edit of an unrelated part. The issue's "saving drops the
+ *    postal code" therefore does NOT reproduce for a value nobody touched;
+ *    the loss the old code really caused is test 6's: a postal code the user
+ *    TYPES is written under a key `AddressValueSchema` strips, so the typed
+ *    correction is silently discarded and the stale stored code stays — and on
+ *    a new record (test 12) it is lost outright. 3 is kept as a contract pin
+ *    for the pass-through, not as evidence of the fix.
+ *  - 4 stays green: it pins the legacy READ, and the old code read that key
+ *    natively. It is meaningful as a pair with 5, which no revert satisfies.
+ *  - 11 stays green: it reads the spec, not the widget. That is the point —
+ *    it fails only if the CONTRACT moves under us.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { AddressValueSchema } from '@objectstack/spec/data';
+import { AddressField, type AddressValue } from './AddressField';
+
+const field = { name: 'billing_address', type: 'address' } as any;
+
+const ZIP_LABEL = 'ZIP / Postal Code';
+
+/** The document the REST API served back in the issue's evidence. */
+const STORED: AddressValue = {
+  street: '中策路 1 号',
+  city: '杭州',
+  state: '浙江',
+  postalCode: '310018',
+  country: 'CN',
+};
+
+/** The same address as written by builds up to 17.0.0-rc.1 (the broken key). */
+const LEGACY = {
+  street: '中策路 1 号',
+  city: '杭州',
+  state: '浙江',
+  zipCode: '310018',
+  country: 'CN',
+} as AddressValue;
+
+/** Resolve a sub-input exactly as a browser does on label activation. */
+function subInput(labelText: string): HTMLInputElement {
+  const label = screen.getByText(labelText);
+  const forId = label.getAttribute('for');
+  expect(forId, `label "${labelText}" must carry htmlFor`).toBeTruthy();
+  const control = document.getElementById(forId!);
+  expect(control, `htmlFor of "${labelText}" must resolve`).not.toBeNull();
+  return control as HTMLInputElement;
+}
+
+/** The most recent object the widget handed to `onChange`. */
+function lastWrite(written: AddressValue[]): AddressValue {
+  expect(written.length, 'the widget must have written at least once').toBeGreaterThan(0);
+  return written[written.length - 1];
+}
+
+/**
+ * Controlled harness — the widget is controlled, so a round trip needs a
+ * parent that stores what the widget writes and feeds it straight back.
+ */
+function Harness({ initial, onWrite }: { initial: AddressValue; onWrite: (v: AddressValue) => void }) {
+  const [value, setValue] = React.useState<AddressValue>(initial);
+  return (
+    <AddressField
+      value={value}
+      onChange={(next) => {
+        onWrite(next);
+        setValue(next);
+      }}
+      field={field}
+    />
+  );
+}
+
+describe('AddressField — postal code round trip (objectstack#5143)', () => {
+  it('1. loads the stored `postalCode` into the ZIP input', () => {
+    render(<AddressField value={STORED} onChange={vi.fn()} field={field} />);
+
+    expect(subInput(ZIP_LABEL).value).toBe('310018');
+    // The four parts that always worked must keep working.
+    expect(subInput('Street Address').value).toBe('中策路 1 号');
+    expect(subInput('City').value).toBe('杭州');
+    expect(subInput('State / Province').value).toBe('浙江');
+    expect(subInput('Country').value).toBe('CN');
+  });
+
+  it('2. keeps the postal code when an UNRELATED part is edited, under `postalCode`', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={STORED} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput('City'), { target: { value: '宁波' } });
+
+    const last = lastWrite(written);
+    expect(last.city).toBe('宁波');
+    expect(last.postalCode).toBe('310018');
+    expect(Object.keys(last)).not.toContain('zipCode');
+    // …and it is still on screen after the write is fed back in.
+    expect(subInput(ZIP_LABEL).value).toBe('310018');
+  });
+
+  it('3. the written address survives the enforced platform value contract', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={STORED} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput('City'), { target: { value: '宁波' } });
+
+    // `AddressValueSchema` is `$strip`: an unknown part name is DROPPED, which
+    // is how a `zipCode`-shaped write lost the postal code on the way to
+    // storage. Parsing the widget's own output is the end-to-end pin.
+    const parsed = AddressValueSchema.parse(lastWrite(written));
+    expect(parsed.postalCode).toBe('310018');
+  });
+
+  it('4. still DISPLAYS a legacy `zipCode`-shaped value written by earlier builds', () => {
+    render(<AddressField value={LEGACY} onChange={vi.fn()} field={field} />);
+
+    expect(subInput(ZIP_LABEL).value).toBe('310018');
+  });
+
+  it('5. migrates a legacy value onto `postalCode` on the first edit of any part', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={LEGACY} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput('Street Address'), { target: { value: '中策路 2 号' } });
+
+    const last = lastWrite(written);
+    expect(last.street).toBe('中策路 2 号');
+    expect(last.postalCode).toBe('310018');
+    expect(Object.keys(last)).not.toContain('zipCode');
+    expect(AddressValueSchema.parse(last).postalCode).toBe('310018');
+  });
+
+  it('6. writes an edit of the ZIP box itself under `postalCode`', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={STORED} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput(ZIP_LABEL), { target: { value: '310019' } });
+
+    const last = lastWrite(written);
+    expect(last.postalCode).toBe('310019');
+    expect(Object.keys(last)).not.toContain('zipCode');
+    expect(subInput(ZIP_LABEL).value).toBe('310019');
+    // The sharpest statement of the bug: under the old key the CORRECTION was
+    // stripped by the contract and the stale stored code survived, with no
+    // error anywhere — the user saw 310019 in the box and 310018 in the record.
+    expect(AddressValueSchema.parse(last).postalCode).toBe('310019');
+  });
+
+  it('7. prefers the canonical key when a record carries both', () => {
+    const both = { ...STORED, zipCode: '999999' } as AddressValue;
+    const written: AddressValue[] = [];
+    render(<Harness initial={both} onWrite={(v) => written.push(v)} />);
+
+    expect(subInput(ZIP_LABEL).value).toBe('310018');
+
+    fireEvent.change(subInput('City'), { target: { value: '宁波' } });
+
+    const last = lastWrite(written);
+    expect(last.postalCode).toBe('310018');
+    expect(Object.keys(last)).not.toContain('zipCode');
+  });
+
+  it('8. clearing the ZIP box clears the postal code instead of resurrecting the legacy value', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={LEGACY} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput(ZIP_LABEL), { target: { value: '' } });
+
+    const last = lastWrite(written);
+    expect(last.postalCode).toBe('');
+    expect(Object.keys(last)).not.toContain('zipCode');
+    expect(subInput(ZIP_LABEL).value).toBe('');
+  });
+
+  it('9. formats the postal code in read-only mode, canonical and legacy alike', () => {
+    const canonical = render(
+      <AddressField value={STORED} onChange={vi.fn()} field={field} readonly />,
+    );
+    expect(canonical.container.textContent).toContain('浙江 310018');
+    canonical.unmount();
+
+    const legacy = render(
+      <AddressField value={LEGACY} onChange={vi.fn()} field={field} readonly />,
+    );
+    expect(legacy.container.textContent).toContain('浙江 310018');
+  });
+
+  it('10. binds the ZIP sub-input to the canonical part name, and nothing to the legacy one', () => {
+    const { baseElement } = render(
+      <AddressField value={STORED} onChange={vi.fn()} field={field} />,
+    );
+
+    expect(subInput(ZIP_LABEL).id).toMatch(/-postalCode$/);
+    const ids = Array.from(baseElement.querySelectorAll('[id]')).map((el) => el.id);
+    expect(ids.filter((id) => id.endsWith('-zipCode'))).toEqual([]);
+  });
+
+  it('11. spells the part the way the spec spells it (direction guard)', () => {
+    const specParts = Object.keys(AddressValueSchema.shape);
+    expect(specParts).toContain('postalCode');
+    expect(specParts).not.toContain('zipCode');
+  });
+
+  it('12. a postal code entered on a NEW record reaches storage instead of being stripped', () => {
+    const written: AddressValue[] = [];
+    render(<Harness initial={{}} onWrite={(v) => written.push(v)} />);
+
+    fireEvent.change(subInput(ZIP_LABEL), { target: { value: '310018' } });
+
+    // Nothing stored to mask the loss: under the old key the parse produced an
+    // address with no postal code at all.
+    expect(AddressValueSchema.parse(lastWrite(written)).postalCode).toBe('310018');
+  });
+});

package/src/widgets/AddressField.tsx

@@ -2,21 +2,28 @@ 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';
+// The value shape and the single-line formatting rule now live in a pure module
+// so the display (read) cell renderer formats a stored address exactly the way
+// this widget's readonly branch does — one rule, not two copies that drift
+// (objectui#4037). Behaviour here is unchanged; only the definition moved.
+import {
+  formatAddress,
+  readPostalCode,
+  type AddressValue,
+  type LegacyAddressValue,
+} from './address-format';
 
-/**
- * Address data structure
- */
-export interface AddressValue {
-  street?: string;
-  city?: string;
-  state?: string;
-  zipCode?: string;
-  country?: string;
-}
+// Re-exported through its declaring module rather than bare, so the spec-symbol
+// guard resolves the name to where it is actually defined: `address-format`
+// imports `AddressValue` from `@objectstack/spec/data` (objectui#4167), and a
+// bare `export type { AddressValue }` here would read to that guard as a second,
+// local declaration of a name the spec owns.
+export type { AddressValue } from './address-format';
 
 /**
  * Address field widget - provides a structured address input
- * Supports street, city, state, zip code, and country
+ * Supports street, city, state, postal code, and country
  */
 export function AddressField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<AddressValue>) {
   const address = value || {};
@@ -25,7 +32,33 @@ 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);
+  // 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
@@ -33,30 +66,47 @@ export function AddressField({ value, onChange, field, readonly, error, ...props
   const groupId = useId();
   const subId = (name: keyof AddressValue) => `${groupId}-${name}`;
 
+  // Read through the legacy key, write only the canonical one (objectstack#5143).
+  const postalCode = readPostalCode(address);
+
   const handleFieldChange = (fieldName: keyof AddressValue, fieldValue: string) => {
+    // Normalize while we are here: the object we write back never carries
+    // `zipCode`, and a legacy postal code is carried forward under
+    // `postalCode`. Without the carry, editing an unrelated part of a
+    // legacy-shaped address would write the postal code straight back out of
+    // the record — the very data loss this fixes, one build later.
+    const canonical: LegacyAddressValue = { ...address };
+    delete canonical.zipCode;
     onChange({
-      ...address,
+      ...canonical,
+      ...(postalCode ? { postalCode } : null),
       [fieldName]: fieldValue,
     });
   };
 
-  const formatAddress = (addr: AddressValue): string => {
-    const parts = [
-      addr.street,
-      addr.city,
-      [addr.state, addr.zipCode].filter(Boolean).join(' '),
-      addr.country,
-    ].filter(Boolean);
-    return parts.join(', ');
-  };
-
   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 (
-    <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. 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
@@ -102,12 +152,12 @@ export function AddressField({ value, onChange, field, readonly, error, ...props
       
       <div className="grid grid-cols-2 gap-3">
         <div>
-          <Label htmlFor={subId('zipCode')} className="text-xs">ZIP / Postal Code</Label>
+          <Label htmlFor={subId('postalCode')} className="text-xs">ZIP / Postal Code</Label>
           <Input
-            id={subId('zipCode')}
+            id={subId('postalCode')}
             type="text"
-            value={address.zipCode || ''}
-            onChange={(e) => handleFieldChange('zipCode', e.target.value)}
+            value={postalCode || ''}
+            onChange={(e) => handleFieldChange('postalCode', e.target.value)}
             placeholder="94102"
             disabled={readonly || props.disabled}
             aria-invalid={!!error}

package/src/widgets/AddressField.uniqueIds.test.tsx

@@ -10,7 +10,8 @@
  * Unique sub-input ids for the composite `address` widget (objectui#3343).
  *
  * The widget used to hardcode literal ids ("street", "city", "state",
- * "zipCode", "country") on its sub-inputs. Two address fields in one form —
+ * "postalCode" — spelled "zipCode" until objectstack#5143 —, "country") on its
+ * sub-inputs. Two address fields in one form —
  * e.g. billing + shipping — then produced duplicate DOM ids, and every
  * `Label htmlFor` resolved to the FIRST match in the document: each sub-label
  * of the second field clicked/announced the first field's input.

package/src/widgets/BooleanField.tsx

@@ -13,8 +13,42 @@ export function BooleanField({ value, onChange, field, readonly, ...props }: Fie
   const widget = config?.widget;
   // Generate unique ID using React's useId hook - must be before early returns (rules of hooks)
   const generatedId = useId();
-  const id = config?.name || generatedId;
+  /**
+   * The HOST owns the control's id (objectui#3952).
+   *
+   * `<FormControl>` is a Radix `Slot` that hands its child the id its
+   * `<FormLabel htmlFor>` already points at (`_r_N_-form-item`). This widget
+   * used to REPLACE it with the field name, so the form's visible label
+   * referenced an id no element carried: `label for="_r_3_-form-item"` against
+   * `all ids in form = ["notifications"]`. Clicking the label — the normal
+   * affordance for a switch/checkbox row — toggled nothing, on every generated
+   * form in every app.
+   *
+   * `id` is a DECLARED key of the widget contract (`FieldWidgetDomProps`) and
+   * `toDomProps` forwards it, so honouring it here is the contract's own
+   * direction: the fix belongs at the consumer that discarded a delivered
+   * value, not in the form renderer (AGENTS.md #0.1).
+   *
+   * The fallback chain stays for the STANDALONE hosts that hand down no id —
+   * `FieldEditWidget` (the grid's inline cell editor) and a bare SDUI node.
+   */
+  const hostId = props.id;
+  const id = hostId || config?.name || generatedId;
   const label = config?.label || 'Checkbox';
+  /**
+   * A host that supplies the id is a host that renders its own label for it
+   * (that is what the id is FOR), so the widget's `sr-only` label would be the
+   * second copy of one name — the other half of #3952, and why a naive
+   * `getByText(label)` on a boolean field returned two nodes.
+   *
+   * Standalone it is the control's ONLY accessible name (`FieldEditWidget`
+   * renders no label of its own), so there it stays. Deliberately keyed on the
+   * host id rather than on `config.label`: inside a form the naming is the
+   * host's job for EVERY widget — a text field in a label-less form row is
+   * equally unnamed — and the generic `'Checkbox'` fallback emitted there was
+   * an actively WRONG accessible name, not a safety net.
+   */
+  const emitOwnLabel = !hostId;
 
   if (readonly) {
     return <span className="text-sm">{value ? 'Yes' : 'No'}</span>;
@@ -25,28 +59,28 @@ export function BooleanField({ value, onChange, field, readonly, ...props }: Fie
   if (widget === 'checkbox') {
      return (
         <div className="flex items-center space-x-2">
-            <Checkbox 
+            <Checkbox
                 {...domProps}
                 id={id}
                 checked={!!value}
                 onCheckedChange={(checked) => onChange(!!checked)}
                 disabled={readonly || domProps.disabled}
             />
-            <Label htmlFor={id} className="sr-only">{label}</Label>
+            {emitOwnLabel && <Label htmlFor={id} className="sr-only">{label}</Label>}
         </div>
      )
   }
 
   return (
     <div className="flex items-center space-x-2">
-        <Switch 
+        <Switch
             {...domProps}
-            id={id} 
-            checked={!!value} 
+            id={id}
+            checked={!!value}
             onCheckedChange={onChange}
             disabled={readonly || domProps.disabled}
         />
-        <Label htmlFor={id} className="sr-only">{label}</Label>
+        {emitOwnLabel && <Label htmlFor={id} className="sr-only">{label}</Label>}
     </div>
   );
 }

package/src/widgets/CapabilityMultiSelectField.tsx

@@ -18,9 +18,18 @@ import { useFieldTranslation } from './useFieldTranslation';
  * labelled, with the capability description on hover — while round-tripping the
  * stored value **byte-for-byte** as a JSON string of names.
  *
- * Reached via the field `widget: 'capability-multiselect'` hint (stamped onto
- * the object metadata in MetadataProvider), registered in the field registry as
- * `field:capability-multiselect`.
+ * ## Not a registry field widget (objectui#3308)
+ *
+ * This is a plain component, imported directly by its host — Studio's
+ * `PermissionMatrixEditor` (`packages/app-shell`), which is where ADR-0056 P2
+ * put the capability editor. It is deliberately NOT reachable through the field
+ * registry, and `widget: 'capability-multiselect'` is a **retired** hint: the
+ * key only ever existed on the docs-site-only `registerFields()` path, nothing
+ * ever stamped the hint (ADR-0056 P1 stamps `permission-facet-link` on all six
+ * `sys_permission_set` facets), and it was removed under ADR-0049
+ * enforce-or-remove. Do not re-register it without re-deciding ADR-0056 P2 —
+ * a field carrying that hint now degrades to its declared `type` renderer,
+ * which is the defined behavior for an unregistered widget.
  */
 
 interface Capability {
@@ -98,8 +107,11 @@ export function CapabilityMultiSelectField({
   const selected = React.useMemo(() => parseCapabilityNames(value), [value]);
 
   // Load the live capability registry (active only). Mirrors LookupField's
-  // context-dataSource access — createFieldRenderer does not forward the
-  // dataSource prop, so the SchemaRenderer context is the reliable source.
+  // context-dataSource access: no registration path forwards a `dataSource`
+  // prop to a field widget, so the SchemaRenderer context is the reliable
+  // source. (The absent forwarder named here used to be the docs-demo
+  // `createFieldRenderer`, removed in objectui#3910 — the conclusion is
+  // unchanged and now holds for the only remaining path.)
   React.useEffect(() => {
     if (!dataSource || typeof (dataSource as any).find !== 'function') return;
     let cancelled = false;

package/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';
 
@@ -51,16 +52,36 @@ export function CheckboxesField({
   // per-element clear the multi-value case needs (cf. the scalar select/radio).
   useEffect(() => {
     if (readonly) return;
+    // Never configured → nothing to prune against; see `MultiSelectField`'s
+    // copy of this guard for the measured failure (objectui#4220).
+    if (rawOptions.length === 0) return;
+    // Gated → the authored list is withheld until the `dependsOn` parent is
+    // chosen, so the empty offered set is missing information, not a verdict on
+    // the stored value; clearing here fired on mount (objectui#4247). Same
+    // reasoning, at length, in `MultiSelectField`.
+    if (gated) return;
     if (selected.length === 0) return;
     const stillOffered = selected.filter((v) => options.some((o) => o.value === v));
     if (stillOffered.length !== selected.length) onChange(stillOffered);
     // 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 +104,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}
       />
     );
   }
@@ -105,10 +129,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}
     >