@object-ui/fields 17.2.0 → 17.5.0

package/src/widgets/MultiSelectField.tsx

@@ -2,6 +2,9 @@ import React, { useEffect } from 'react';
 import { Badge, EmptyValue, cn } from '@object-ui/components';
 import type { OptionLike } from '@object-ui/core';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
+import { toHostGroupProps } from './toHostGroupProps';
+import { OptionsEmptyState } from './OptionsEmptyState';
 import { useCascadingOptions } from './useCascadingOptions';
 
 interface Option extends OptionLike { color?: string }
@@ -26,14 +29,14 @@ export function MultiSelectField({
   field,
   readonly,
   className,
-  schema,
   dependentValues,
   dependsOn: dependsOnProp,
-  emptyHint: _emptyHint,
+  emptyHint,
   dataSource: _dataSource,
+  error,
   ...props
 }: FieldWidgetComponentProps<string[]>) {
-  const config = (field || schema) as any;
+  const config = field as any;
   const rawOptions: Option[] = config?.options || [];
   const selected: string[] = Array.isArray(value) ? value : value == null ? [] : [value as unknown as string];
   const fieldName = props.name || config?.name || props.id || '';
@@ -50,16 +53,56 @@ export function MultiSelectField({
   // the scalar case we prune per-element rather than clearing the whole field.
   useEffect(() => {
     if (readonly) return;
+    // An empty offered set has THREE very different causes, and only one of them
+    // is a decision to prune against. This is the canonical copy of the guards;
+    // the other three option widgets carry the same pair.
+    //
+    // 1. Nothing was ever CONFIGURED (objectui#4220) — a field authored with no
+    //    `options` at all. No decision was made anywhere, and the widget renders
+    //    its "unfillable" state below. Pruning here is not a cascade, it is
+    //    deleting the stored value of a field the user was only ever shown a
+    //    hint for — measured on the detail page's inline editor, which stages
+    //    that empty array into the record draft the moment the row enters edit
+    //    mode, and on the grid's inline cell editor, which has always taken this
+    //    path.
+    if (rawOptions.length === 0) return;
+    // 2. The list is GATED (objectui#4247) — an authored list withheld because a
+    //    declared `dependsOn` parent is still empty, so `resolveCascadingOptions`
+    //    returns nothing at all. Gated means UNKNOWN, not invalid: the widget has
+    //    no information about which stored values are valid, which is exactly
+    //    what the `OptionsEmptyState` below tells the user ("select Country
+    //    first"). Clearing here fired on MOUNT with no interaction — a record
+    //    that merely ARRIVES with the parent empty (a later-cleared parent, an
+    //    import, a partially-migrated row) had its picklist silently staged for
+    //    deletion. Read from the resolver's own `gated` flag rather than
+    //    re-derived from `options.length === 0`, which would collide with case 1.
+    if (gated) return;
+    // 3. The list RESOLVED and genuinely excludes the value — a real cascade
+    //    (the parent changed, a predicate flipped). That is the ADR-0058
+    //    contract and it still prunes, below.
     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 />;
+    // A readonly set of values is still a set, so it takes the same `group`
+    // answer the editable chip row gives. `EmptyValue` is that surface with
+    // nothing in it: it publishes an `aria-label` ("No value") of its own, and
+    // `aria-labelledby` outranks that per accname — correctly, because on the
+    // `generic` role that placeholder span carries, an author name is prohibited
+    // and never exposed, so the real choice is the field's name or no name.
+    if (selected.length === 0) return <EmptyValue {...hostGroupProps} />;
     return (
-      <div className="flex flex-wrap gap-1">
+      <div {...hostGroupProps} className="flex flex-wrap gap-1">
         {selected.map((v) => {
           // Label from the raw set so a stored value hidden by `visibleWhen`
           // still renders its label rather than a bare id.
@@ -71,19 +114,21 @@ export function MultiSelectField({
   }
 
   // No offered options is unfillable — surface a legible state instead of an
-  // empty chip row: a dependency-gated list prompts for its controlling field;
-  // an unconfigured / fully-filtered list says so. Mirrors the single select.
+  // empty chip row: the host's `emptyHint` when it computed one, else this
+  // widget's own translated copy. Shared with the single select / radio /
+  // checkboxes so the four cannot drift again (objectui#3231).
   if (options.length === 0) {
-    const hint = gated
-      ? `Select ${dependsOnFields.join(' / ')} first`
-      : 'No options available';
     return (
-      <div
-        data-testid={fieldName ? `multiselect-empty-${fieldName}` : undefined}
-        className="flex min-h-9 w-full items-center rounded-md border border-input bg-muted/30 px-3 py-2 text-sm text-muted-foreground"
-      >
-        {hint}
-      </div>
+      <OptionsEmptyState
+        emptyHint={emptyHint}
+        gated={gated}
+        dependsOnFields={dependsOnFields}
+        testId={fieldName ? `multiselect-empty-${fieldName}` : undefined}
+        className="min-h-9"
+        // This box IS the field in this state, so it is what the host label
+        // names (objectui#3990).
+        hostGroupProps={hostGroupProps}
+      />
     );
   }
 
@@ -92,8 +137,32 @@ export function MultiSelectField({
     onChange(next);
   };
 
+  // DOM pass-through (objectui#3318): the container carries the form
+  // renderer's id / aria-describedby, but NOT its `aria-invalid` — a plain
+  // wrapper div is not where assistive tech reads the invalid state. That
+  // state goes onto every focusable chip button below, computed from the
+  // published `error` slot (#3222), so whichever chip the user tabs to
+  // announces the failure. `name` is withheld too: it is only DOM-legal on
+  // form controls, and on this div it is exactly the leak #3291 sweeps for.
+  const {
+    'aria-invalid': _hostAriaInvalid,
+    name: _domName,
+    ...groupDomProps
+  } = toDomProps(props);
+  // When the host associated its visible label with this container by IDREF
+  // (`aria-labelledby`, objectui#3961 / #3975) 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. Each chip keeps its own accessible name from its text content,
+  // which the group name does not override. 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={cn('flex flex-wrap gap-1.5', className)}
       data-testid={fieldName ? `multiselect-${fieldName}` : undefined}
     >
@@ -109,6 +178,7 @@ export function MultiSelectField({
             onClick={() => toggle(value)}
             disabled={props.disabled}
             aria-pressed={active}
+            aria-invalid={!!error}
             data-testid={`multiselect-option-${opt.value}`}
             className={cn(
               'rounded-full border px-3 py-1 text-sm transition-colors',

package/src/widgets/NumberField.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import { Input, EmptyValue } from '@object-ui/components';
 import { NumberFieldMetadata } from '@object-ui/types';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 
 /**
  * NumberField - Numeric input with optional decimal precision
@@ -12,7 +13,7 @@ export function NumberField({ value, onChange, field, readonly, ...props }: Fiel
     return value == null ? <EmptyValue /> : <span className="text-sm">{value}</span>;
   }
 
-  const numberField = (field || (props as any).schema) as NumberFieldMetadata;
+  const numberField = field as NumberFieldMetadata;
   // Step follows `scale` (decimal places), not `precision` (total digit count):
   // a decimal(10, 0) column has 0 decimal places, so the input should step by 1
   // (`scale: 0` is a valid declaration — hence the typeof check, not truthiness).
@@ -25,8 +26,7 @@ export function NumberField({ value, onChange, field, readonly, ...props }: Fiel
         ? Math.pow(10, -scale)
         : 'any';
 
-  // Filter out non-DOM props
-  const { inputType, ...domProps } = props as any;
+  const domProps = toDomProps(props);
 
   return (
     <Input

package/src/widgets/ObjectField.tsx

@@ -1,13 +1,14 @@
 import React, { useState, useEffect } from 'react';
 import { Textarea, cn, EmptyValue } from '@object-ui/components';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 
 /**
  * ObjectField - JSON object editor
  * Allows editing structured JSON data
  */
-export function ObjectField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<any>) {
-  const config = field || (props as any).schema;
+export function ObjectField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<any>) {
+  const config = field;
   
   // Initialize string state based on value
   const getInitialJsonString = () => {
@@ -16,7 +17,9 @@ export function ObjectField({ value, onChange, field, readonly, ...props }: Fiel
   };
   
   const [jsonString, setJsonString] = useState(getInitialJsonString);
-  const [error, setError] = useState<string | null>(null);
+  // Named `parseError`, NOT `error`: `error` is the published validation slot
+  // on the widget contract (#3222) and is destructured above.
+  const [parseError, setParseError] = useState<string | null>(null);
 
   // Sync internal string state when value changes externally
   // This is a controlled component pattern where we need to sync external changes
@@ -53,33 +56,39 @@ export function ObjectField({ value, onChange, field, readonly, ...props }: Fiel
   const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
     const str = e.target.value;
     setJsonString(str);
-    setError(null);
+    setParseError(null);
 
     if (!str.trim()) {
       onChange(null);
       return;
     }
-    
+
     try {
       const parsed = JSON.parse(str);
       onChange(parsed);
     } catch (e) {
       // Invalid JSON - don't propagate change to parent, but keep local state
-      setError("Invalid JSON");
+      setParseError("Invalid JSON");
     }
   };
 
   return (
     <div className="space-y-1">
       <Textarea
+        // DOM pass-through onto the real focusable control (objectui#3318).
+        {...toDomProps(props)}
         value={jsonString}
         onChange={handleChange}
         placeholder={config?.placeholder || '{\n  "key": "value"\n}'}
         disabled={readonly || props.disabled}
-        className={cn("font-mono text-xs", error ? "border-red-500 focus-visible:ring-red-500" : "", props.className)}
+        className={cn("font-mono text-xs", parseError ? "border-red-500 focus-visible:ring-red-500" : "", props.className)}
         rows={6}
+        // AFTER the spread so this widget's own computation wins (#3222).
+        // Invalid = the form's validation slot OR this widget's own unparsable
+        // draft (which already draws the red border above).
+        aria-invalid={!!error || !!parseError}
       />
-      {error && <p className="text-xs text-red-500">{error}</p>}
+      {parseError && <p className="text-xs text-red-500">{parseError}</p>}
     </div>
   );
 }

package/src/widgets/ObjectRefField.tsx

@@ -2,6 +2,7 @@ import React from 'react';
 import { Combobox, EmptyValue, cn } from '@object-ui/components';
 import { SchemaRendererContext } from '@object-ui/react';
 import type { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 import { useFieldTranslation } from './useFieldTranslation';
 
 /**
@@ -31,6 +32,7 @@ export function ObjectRefField({
   onChange,
   readonly,
   className,
+  error,
   ...props
 }: FieldWidgetComponentProps<string>) {
   const ctx = React.useContext(SchemaRendererContext);
@@ -91,8 +93,14 @@ export function ObjectRefField({
     return <span className={className}>{label}</span>;
   }
 
+  // DOM pass-through onto the combobox trigger — the widget's real focusable
+  // control (objectui#3318). `name` is withheld: the trigger is a button, not
+  // a submission control (same reasoning as #3306's SelectTrigger).
+  const { name: _domName, ...triggerDomProps } = toDomProps(props);
+
   return (
     <Combobox
+      {...triggerDomProps}
       options={options}
       value={value ?? ''}
       onValueChange={(v) => onChange(v as any)}
@@ -104,6 +112,8 @@ export function ObjectRefField({
       // `w-[200px]` is a component default that left this control stranded at
       // a third of the row while `名称` beside it ran full width.
       className={cn('w-full', className)}
+      // AFTER the spread so this widget's own computation wins (#3222).
+      aria-invalid={!!error}
     />
   );
 }

package/src/widgets/OptionsEmptyState.no-provider.test.tsx

@@ -0,0 +1,88 @@
+/**
+ * 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 option widgets' empty/gate copy with NO `I18nProvider` mounted
+ * (objectui#3231) — standalone/embedded usage, and every test in the repo that
+ * renders a field widget bare.
+ *
+ * Routing the copy through `useFieldTranslation()` must not turn it into a raw
+ * i18n key when nothing is configured: `createSafeTranslation` probes the
+ * instance and falls back to its English defaults map. That is the behaviour
+ * the removed literals used to provide unconditionally, so it gets its own pin.
+ *
+ * Why a separate FILE rather than another case in `OptionsEmptyState.test.tsx`:
+ * mounting `I18nProvider` calls `initReactI18next`, which installs that
+ * instance as react-i18next's GLOBAL default. Once any sibling test has done
+ * so there is no "no provider" state left to observe in that module graph, and
+ * the assertion would silently read the last locale mounted instead. Vitest's
+ * per-file isolation (`isolate: true` on the `dom` project) is what makes this
+ * file's observation honest.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { SelectField } from './SelectField';
+import { MultiSelectField } from './MultiSelectField';
+import { RadioField } from './RadioField';
+import { CheckboxesField } from './CheckboxesField';
+
+const WIDGETS = [
+  { label: 'SelectField', Widget: SelectField, type: 'select', testId: 'select-empty-province' },
+  {
+    label: 'MultiSelectField',
+    Widget: MultiSelectField,
+    type: 'multiselect',
+    testId: 'multiselect-empty-province',
+  },
+  { label: 'RadioField', Widget: RadioField, type: 'radio', testId: 'radio-empty-province' },
+  {
+    label: 'CheckboxesField',
+    Widget: CheckboxesField,
+    type: 'checkboxes',
+    testId: 'checkboxes-empty-province',
+  },
+] as const;
+
+const gatedField = (type: string) =>
+  ({
+    name: 'province',
+    type,
+    dependsOn: 'country',
+    options: [{ label: 'Zhejiang', value: 'zj', visibleWhen: "record.country == 'cn'" }],
+  }) as any;
+
+const unconfiguredField = (type: string) => ({ name: 'province', type, options: [] }) as any;
+
+function renderWidget(Widget: React.ComponentType<any>, field: any) {
+  return render(
+    <Widget
+      value={undefined}
+      onChange={vi.fn()}
+      field={field}
+      {...({ name: 'province', dependentValues: {} } as any)}
+    />,
+  );
+}
+
+describe('option widgets — English fallback survives with no i18n configured', () => {
+  it.each(WIDGETS)('$label renders the gate sentence, not a raw key', ({ Widget, type, testId }) => {
+    renderWidget(Widget, gatedField(type));
+    const box = screen.getByTestId(testId);
+    expect(box).toHaveTextContent('Select country first');
+    expect(box.textContent).not.toContain('fields.options');
+  });
+
+  it.each(WIDGETS)('$label renders the empty sentence, not a raw key', ({ Widget, type, testId }) => {
+    renderWidget(Widget, unconfiguredField(type));
+    const box = screen.getByTestId(testId);
+    expect(box).toHaveTextContent('No options available');
+    expect(box.textContent).not.toContain('fields.options');
+  });
+});

package/src/widgets/OptionsEmptyState.test.tsx

@@ -0,0 +1,169 @@
+/**
+ * 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 empty / dependency-gated state of the fixed-option widgets (objectui#3231).
+ *
+ * Two invariants, pinned for ALL FOUR widgets — they are what regressed:
+ *
+ *  1. **declared ⇒ delivered.** `emptyHint` is declared on
+ *     `FieldWidgetComponentProps` and computed by the form renderer. Every one
+ *     of the four widgets used to destructure it into `_emptyHint` and drop it
+ *     on the floor, so the host's hint could never reach a user once the field
+ *     went through the `field:` registry (i.e. always, in the real console).
+ *  2. **the fallback is translated.** With no host hint the widget renders its
+ *     own copy — which used to be a hardcoded English literal
+ *     (`'No options available'`, `` `Select ${…} first` ``) even though
+ *     `useFieldTranslation()` was already imported in one of the same files.
+ *
+ * All four are covered deliberately: they were four independent copies of the
+ * same block, which is exactly why they drifted together and why one widget's
+ * test would have proven nothing about the other three. They now share
+ * `OptionsEmptyState`; these tests keep that true from the outside, so the
+ * guarantee survives someone re-inlining the block.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { I18nProvider } from '@object-ui/i18n';
+import { SelectField } from './SelectField';
+import { MultiSelectField } from './MultiSelectField';
+import { RadioField } from './RadioField';
+import { CheckboxesField } from './CheckboxesField';
+
+interface WidgetCase {
+  label: string;
+  Widget: React.ComponentType<any>;
+  type: string;
+  testId: string;
+}
+
+const WIDGETS: WidgetCase[] = [
+  { label: 'SelectField', Widget: SelectField, type: 'select', testId: 'select-empty-province' },
+  {
+    label: 'MultiSelectField',
+    Widget: MultiSelectField,
+    type: 'multiselect',
+    testId: 'multiselect-empty-province',
+  },
+  { label: 'RadioField', Widget: RadioField, type: 'radio', testId: 'radio-empty-province' },
+  {
+    label: 'CheckboxesField',
+    Widget: CheckboxesField,
+    type: 'checkboxes',
+    testId: 'checkboxes-empty-province',
+  },
+];
+
+/** Gated: `country` is empty, so no option is offered yet (#2284). */
+const gatedField = (type: string) =>
+  ({
+    name: 'province',
+    type,
+    dependsOn: 'country',
+    options: [
+      { label: 'Zhejiang', value: 'zj', visibleWhen: "record.country == 'cn'" },
+      { label: 'California', value: 'ca', visibleWhen: "record.country == 'us'" },
+    ],
+  }) as any;
+
+/** Not gated, simply nothing to offer — the other way a list ends up empty. */
+const unconfiguredField = (type: string) => ({ name: 'province', type, options: [] }) as any;
+
+function renderWidget(
+  { Widget }: WidgetCase,
+  field: any,
+  extra: Record<string, unknown> = {},
+  language?: string,
+) {
+  const element = (
+    <Widget
+      value={undefined}
+      onChange={vi.fn()}
+      field={field}
+      {...({ name: 'province', dependentValues: {}, ...extra } as any)}
+    />
+  );
+  return render(
+    language ? (
+      <I18nProvider config={{ defaultLanguage: language, detectBrowserLanguage: false }}>
+        {element}
+      </I18nProvider>
+    ) : (
+      element
+    ),
+  );
+}
+
+describe('option widgets — the host-supplied `emptyHint` reaches the user (objectui#3231)', () => {
+  it.each(WIDGETS)(
+    '$label renders the host hint instead of its own gate copy',
+    (widget) => {
+      // What the form renderer actually computes: a sentence built from the
+      // controlling field's human LABEL, which the widget cannot know (its
+      // metadata only carries the name `country`).
+      renderWidget(widget, gatedField(widget.type), {
+        emptyHint: 'Choose the Country field first',
+      });
+
+      const box = screen.getByTestId(widget.testId);
+      expect(box).toHaveTextContent('Choose the Country field first');
+      // …and NOT the widget's own copy, which is what used to render.
+      expect(box.textContent).not.toMatch(/select country first/i);
+    },
+  );
+
+  it.each(WIDGETS)(
+    '$label renders the host hint for an unconfigured (ungated) list too',
+    (widget) => {
+      // `emptyHint` is a declared prop of the widget contract, not a private
+      // channel of one form-renderer branch: supplied ⇒ used, always.
+      renderWidget(widget, unconfiguredField(widget.type), {
+        emptyHint: 'Options come from the price book',
+      });
+
+      expect(screen.getByTestId(widget.testId)).toHaveTextContent(
+        'Options come from the price book',
+      );
+    },
+  );
+
+  it.each(WIDGETS)('$label prefers a host hint over its translated fallback', (widget) => {
+    // Even under a non-English locale the HOST wins — it is the single source.
+    renderWidget(widget, gatedField(widget.type), { emptyHint: 'Pick a Country first' }, 'zh');
+
+    const box = screen.getByTestId(widget.testId);
+    expect(box).toHaveTextContent('Pick a Country first');
+    expect(box.textContent).not.toContain('请先选择');
+  });
+});
+
+describe('option widgets — the fallback copy is translated, never a hardcoded literal', () => {
+  it.each(WIDGETS)('$label translates the gate copy when no host hint is given', (widget) => {
+    renderWidget(widget, gatedField(widget.type), {}, 'zh');
+
+    const box = screen.getByTestId(widget.testId);
+    expect(box).toHaveTextContent('请先选择country');
+    expect(box.textContent).not.toMatch(/select .* first/i);
+  });
+
+  it.each(WIDGETS)('$label translates the empty copy when no host hint is given', (widget) => {
+    renderWidget(widget, unconfiguredField(widget.type), {}, 'zh');
+
+    const box = screen.getByTestId(widget.testId);
+    expect(box).toHaveTextContent('暂无可选项');
+    expect(box.textContent).not.toMatch(/no options available/i);
+  });
+});
+
+// The no-provider fallback lives in `OptionsEmptyState.no-provider.test.tsx`:
+// mounting `I18nProvider` here installs its instance as react-i18next's global
+// default (`initReactI18next`), so after any test above there is no longer a
+// "no provider" state to observe within this module graph.
+

package/src/widgets/OptionsEmptyState.tsx

@@ -0,0 +1,99 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import React from 'react';
+import { cn } from '@object-ui/components';
+import { useFieldTranslation } from './useFieldTranslation';
+import type { HostGroupProps } from './toHostGroupProps';
+
+/**
+ * The "this option list cannot be filled" state shared by every fixed-option
+ * widget (`SelectField` single, `MultiSelectField`, `RadioField`,
+ * `CheckboxesField`) — objectui#3231.
+ *
+ * ## One producer, one consumer
+ *
+ * `emptyHint` is a declared prop on `FieldWidgetComponentProps`, computed by
+ * the form renderer (`form.tsx`, the `#2284` dependency gate) and forwarded to
+ * these widgets. **When the host supplies it, it wins**: the host resolves the
+ * controlling fields to their human LABELS ("Select Country first"), where a
+ * widget on its own only knows the raw metadata names ("Select country first").
+ * Absent a host hint — a standalone widget, the inline grid editor, an action
+ * param dialog — the widget falls back to its own copy.
+ *
+ * Each of the four widgets used to inline this box, destructure `emptyHint`
+ * into `_emptyHint` and throw it away, then render a hardcoded English literal.
+ * Four independent copies is precisely why they drifted together, so the box
+ * AND the copy live here only: adding a fifth option widget cannot re-introduce
+ * the gap without deliberately re-implementing it.
+ *
+ * ## Fallback copy is translated
+ *
+ * The fallback goes through `useFieldTranslation()` (`fields.options.*`,
+ * present in all ten locale packs) rather than an English string literal — the
+ * gate sentence is the SAME i18n key the form renderer uses, so the two can
+ * never say different things in the same locale.
+ */
+export interface OptionsEmptyStateProps {
+  /**
+   * Host-computed hint. Wins over the widget's own copy whenever it is a
+   * non-empty string — this is the whole point of the prop.
+   */
+  emptyHint?: string;
+  /** The list is waiting on a `dependsOn` controlling field (vs. unconfigured). */
+  gated: boolean;
+  /** Controlling field names, used by the fallback gate sentence. */
+  dependsOnFields: readonly string[];
+  /** Widget-specific stable locator, e.g. `select-empty-${fieldName}`. */
+  testId?: string;
+  /** Widget-specific sizing (the dropdown is a fixed `h-9`, lists grow). */
+  className?: string;
+  /**
+   * The host label's IDREF plumbing, when this box is the whole rendered surface
+   * of a group-labelled field (objectui#3990) — a `checkboxes` / `radio` /
+   * `multiselect` whose option list came back empty renders NOTHING but this
+   * box, so the visible label named zero elements until it landed here.
+   *
+   * A closed three-key type rather than an open props tail: only `id`,
+   * `aria-labelledby` and the `role` that makes them meaningful may reach this
+   * element, and reopening a spread is what objectui#3291 exists to prevent.
+   * Absent for the single `SelectField` — it is not group-labelled, its label
+   * still uses a plain `for`, and it must keep emitting no such attributes.
+   */
+  hostGroupProps?: HostGroupProps;
+}
+
+export function OptionsEmptyState({
+  emptyHint,
+  gated,
+  dependsOnFields,
+  testId,
+  className,
+  hostGroupProps,
+}: OptionsEmptyStateProps) {
+  const { t } = useFieldTranslation();
+  // The host's hint when it computed one; otherwise this widget's own copy,
+  // translated. Never an English literal — that was the reported defect.
+  const hint =
+    emptyHint ||
+    (gated
+      ? t('fields.options.selectFirst', { fields: dependsOnFields.join(' / ') })
+      : t('fields.options.empty'));
+  return (
+    <div
+      {...hostGroupProps}
+      data-testid={testId}
+      className={cn(
+        'flex w-full items-center rounded-md border border-input bg-muted/30 px-3 py-2 text-sm text-muted-foreground',
+        className,
+      )}
+    >
+      {hint}
+    </div>
+  );
+}