@object-ui/fields 17.2.0 → 17.3.0

package/src/widgets/LookupField.tsx

@@ -11,6 +11,7 @@ import { cn,
   PopoverContent, EmptyValue } from '@object-ui/components';
 import { Search, X, Loader2, AlertCircle, Plus, TableProperties } from 'lucide-react';
 import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 import type { DataSource, QueryParams, LookupColumnDef } from '@object-ui/types';
 import { RecordPickerDialog, lookupFiltersToRecord } from './RecordPickerDialog';
 import type { RecordPickerFilterColumn } from './RecordPickerDialog';
@@ -191,7 +192,7 @@ function mapFieldTypeToFilterType(
  * from the referenced object using `DataSource.find()`.
  * Falls back to static `options` when no DataSource is available.
  */
-export function LookupField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<any>) {
+export function LookupField({ value, onChange, field, readonly, error: fieldError, ...props }: FieldWidgetComponentProps<any>) {
   const [isOpen, setIsOpen] = useState(false);
   const { t } = useFieldTranslation();
   const listboxId = React.useId();
@@ -215,7 +216,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   const [activeIndex, setActiveIndex] = useState(-1);
   const listRef = useRef<HTMLDivElement>(null);
 
-  const lookupField = (field || (props as any).schema) as any;
+  const lookupField = field as any;
 
   // When rendered via createFieldRenderer wrapper the actual objectSchema field
   // metadata (reference_to, display_field, etc.) lives at lookupField.field.
@@ -279,6 +280,23 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
     return [];
   }, [fieldMeta?.depends_on, fieldMeta?.dependsOn]);
 
+  /**
+   * The gate sentence's `{{fields}}` — the controlling fields named the way the
+   * user sees them on the form, not the way the metadata spells them.
+   *
+   * `depends_on` holds API names, and this used to interpolate them straight
+   * into the sentence, so every locale — `en` included — read "Select
+   * crm_account first" (objectstack#5407): an internal identifier in the UI,
+   * not merely an untranslated word. The host form supplies the name→label map
+   * (`dependsOnLabels`); a name it doesn't cover falls back to itself, so a
+   * standalone widget with no host renders exactly what it did before.
+   */
+  const dependsOnLabelsProp = props.dependsOnLabels;
+  const dependsOnFieldsText = useMemo(
+    () => dependsOn.map((d) => dependsOnLabelsProp?.[d.field] || d.field).join(', '),
+    [dependsOn, dependsOnLabelsProp],
+  );
+
   // Resolve dependent field values from explicit prop or SchemaRendererContext.data
   const dependentValuesProp = props.dependentValues;
 
@@ -912,19 +930,35 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   // Shared field trigger — the anchor for either the inline PeoplePicker
   // (search fields) or the classic quick-select popover. No onClick: the Radix
   // trigger it is slotted into (PopoverTrigger / SheetTrigger) owns open/close.
+  //
+  // DOM pass-through onto this button — the widget's real focusable control —
+  // per objectui#3318. `name` is withheld: no native control here takes part
+  // in form submission, and a stray `name` on a button invites exactly the
+  // accidental-submitter semantics #3306 kept it off the SelectTrigger for.
+  const { name: _domName, ...triggerDomProps } = toDomProps(props);
   const triggerButton = (
     <Button
+      {...triggerDomProps}
       variant="outline"
       className={cn(
-        'min-w-0 flex-1 justify-start text-left font-normal',
+        // max-w-full: in a BLOCK parent (detail-section inline edit) the
+        // inline-flex button is content-sized — a long selected label pushed
+        // it past the card edge; bounding it lets the inner `truncate` span
+        // clip instead (objectui#3466). flex-1/min-w-0 keep handling the
+        // flex-parent (form row) case.
+        'min-w-0 max-w-full flex-1 justify-start text-left font-normal',
         compact && 'h-8 rounded-none border-0 bg-transparent px-2 shadow-none focus-visible:ring-1 focus-visible:ring-ring/60',
       )}
       type="button"
       disabled={dependenciesMissing || props.disabled}
       data-testid={dependenciesMissing ? 'lookup-trigger-gated' : ((props.name || lookupField?.name) ? `lookup-trigger-${props.name || lookupField.name}` : 'lookup-trigger')}
       title={dependenciesMissing
-        ? t('lookup.selectFirst', { fields: dependsOn.map(d => d.field).join(', ') })
+        ? t('lookup.selectFirst', { fields: dependsOnFieldsText })
         : undefined}
+      // AFTER the spread so this widget's own computation wins (#3222):
+      // `fieldError` is the published validation slot — NOT the popover's
+      // fetch error, which is a widget-internal state named `error` below.
+      aria-invalid={!!fieldError}
     >
       {hydrating ? (
         <Loader2
@@ -936,7 +970,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
       )}
       <span className={cn('truncate', compact && selectedOptions.length === 0 && 'text-muted-foreground')}>
         {dependenciesMissing
-          ? t('lookup.selectFirst', { fields: dependsOn.map(d => d.field).join(', ') })
+          ? t('lookup.selectFirst', { fields: dependsOnFieldsText })
           : hydrating
             // The value EXISTS but its labels are still loading — say so
             // instead of the empty placeholder (#3108).
@@ -1218,7 +1252,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
           onClick={() => setIsPickerOpen(true)}
           aria-label={t('lookup.browseAll')}
           title={dependenciesMissing
-            ? t('lookup.selectFirst', { fields: dependsOn.map(d => d.field).join(', ') })
+            ? t('lookup.selectFirst', { fields: dependsOnFieldsText })
             : t('lookup.browseAll')}
           data-testid="browse-all-records"
         >
@@ -1248,6 +1282,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
           lookupFilters={lookupFilters}
           baseFilter={dependentFilter}
           cellRenderer={getCellRendererResolver()}
+          fieldsMeta={refObjectSchema?.fields}
           filterColumns={filterColumns}
         />
       )}

package/src/widgets/MasterDetailField.tsx

@@ -25,7 +25,7 @@ export function MasterDetailField({
   ...props 
 }: FieldWidgetComponentProps<MasterDetailValue[]>) {
   const items = value || [];
-  const config = field || (props as any).schema;
+  const config = field;
 
   const handleAdd = () => {
     // This would typically open a dialog to select/create related records

package/src/widgets/MultiSelectField.tsx

@@ -2,6 +2,8 @@ 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 { OptionsEmptyState } from './OptionsEmptyState';
 import { useCascadingOptions } from './useCascadingOptions';
 
 interface Option extends OptionLike { color?: string }
@@ -26,14 +28,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 || '';
@@ -71,19 +73,18 @@ 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"
+      />
     );
   }
 
@@ -92,8 +93,22 @@ 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);
+
   return (
     <div
+      {...groupDomProps}
       className={cn('flex flex-wrap gap-1.5', className)}
       data-testid={fieldName ? `multiselect-${fieldName}` : undefined}
     >
@@ -109,6 +124,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.
+