@object-ui/fields 17.1.0 → 17.3.0

package/src/widgets/LookupField.gateHintLabel.test.tsx

@@ -0,0 +1,135 @@
+/**
+ * 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 gated lookup names its controlling field by LABEL — objectstack#5407.
+ *
+ * The gate sentence (`lookup.selectFirst`) is translated in all ten packs, but
+ * its `{{fields}}` interpolation came straight off `depends_on`, which holds
+ * API names. So the rendered hint was localized around a raw identifier in
+ * every locale, English included:
+ *
+ *     en    Select crm_account first
+ *     zh-CN 请先选择crm_account
+ *
+ * The `en` row is why this is not merely an i18n bug: an English user was shown
+ * an internal identifier. The form renderer knows the label (it already
+ * resolves the same map for the fixed-option widgets' `emptyHint`) and now
+ * hands it over as `dependsOnLabels`.
+ *
+ * All three gated surfaces are asserted — the trigger's visible text, the
+ * trigger's `title`, and the "browse all" button's `title` — because they were
+ * three independent copies of the same expression and a fix applied to one of
+ * them looks identical from the outside.
+ */
+
+import { render, screen, cleanup } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { LookupField } from './LookupField';
+
+/** Mirrors the reported metadata: the parent field's API name IS an object-ish
+ *  name (`crm_account`), which is exactly what made the leak so legible. */
+const gatedField = {
+  name: 'contact',
+  label: 'Contact',
+  reference_to: 'crm_contact',
+  reference_field: 'name',
+  depends_on: ['crm_account'],
+} as any;
+
+const dataSource = { find: vi.fn(async () => ({ data: [], total: 0 })) } as any;
+
+function renderGated(extra: Record<string, unknown>) {
+  return render(
+    <LookupField
+      field={gatedField}
+      value={undefined}
+      onChange={vi.fn()}
+      readonly={false}
+      dataSource={dataSource}
+      {...({ dependentValues: { crm_account: null }, ...extra } as any)}
+    />,
+  );
+}
+
+beforeEach(() => {
+  Object.defineProperty(window, 'innerWidth', { writable: true, configurable: true, value: 1280 });
+  window.matchMedia = ((query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    addListener: () => {},
+    removeListener: () => {},
+    dispatchEvent: () => false,
+  })) as any;
+});
+
+afterEach(() => cleanup());
+
+describe('LookupField gate hint names the controlling field (objectstack#5407)', () => {
+  it('interpolates the label the host supplied, not the API name', () => {
+    renderGated({ dependsOnLabels: { crm_account: 'Account' } });
+
+    const trigger = screen.getByTestId('lookup-trigger-gated');
+    expect(trigger).toHaveTextContent('Select Account first');
+    // The identifier must be gone from the copy entirely, not merely
+    // accompanied by the label.
+    expect(trigger).not.toHaveTextContent('crm_account');
+    expect(trigger).toHaveAttribute('title', 'Select Account first');
+  });
+
+  it('labels the gated "browse all" button the same way', () => {
+    renderGated({ dependsOnLabels: { crm_account: 'Account' } });
+
+    const browse = screen.getByTestId('browse-all-records');
+    expect(browse).toBeDisabled();
+    expect(browse).toHaveAttribute('title', 'Select Account first');
+  });
+
+  it('joins several controlling fields by their labels', () => {
+    render(
+      <LookupField
+        field={{ ...gatedField, depends_on: ['crm_account', 'lead_source'] }}
+        value={undefined}
+        onChange={vi.fn()}
+        readonly={false}
+        dataSource={dataSource}
+        {...({
+          dependentValues: { crm_account: null, lead_source: null },
+          dependsOnLabels: { crm_account: 'Account', lead_source: 'Lead Source' },
+        } as any)}
+      />,
+    );
+
+    expect(screen.getByTestId('lookup-trigger-gated')).toHaveTextContent(
+      'Select Account, Lead Source first',
+    );
+  });
+
+  it('falls back to the API name for a field the host did not map', () => {
+    // Standalone use (no host form) has to keep rendering what it rendered
+    // before — the map is an enrichment, not a new requirement. This is also
+    // the assertion that would go red if `dependsOnLabels` were consulted for
+    // its VALUES rather than keyed by field name.
+    renderGated({ dependsOnLabels: { some_other_field: 'Irrelevant' } });
+
+    expect(screen.getByTestId('lookup-trigger-gated')).toHaveTextContent(
+      'Select crm_account first',
+    );
+  });
+
+  it('falls back to the API name when the host passes no map at all', () => {
+    renderGated({});
+
+    expect(screen.getByTestId('lookup-trigger-gated')).toHaveTextContent(
+      'Select crm_account first',
+    );
+  });
+});

package/src/widgets/LookupField.tsx

@@ -10,7 +10,8 @@ import { cn,
   PopoverTrigger,
   PopoverContent, EmptyValue } from '@object-ui/components';
 import { Search, X, Loader2, AlertCircle, Plus, TableProperties } from 'lucide-react';
-import { FieldWidgetProps } from './types';
+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 }: FieldWidgetProps<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,14 +280,31 @@ 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 as any).dependentValues as Record<string, any> | undefined;
+  const dependentValuesProp = props.dependentValues;
 
   // Resolve DataSource: explicit prop > field-level > wrapper field > SchemaRendererContext > none
   const ctx = useContext(SchemaRendererContext);
   const contextDataSource = ctx?.dataSource ?? null;
   const dataSource: DataSource | null =
-    (props as any).dataSource ?? lookupField?.dataSource ?? fieldMeta?.dataSource ?? contextDataSource;
+    (props.dataSource as DataSource | null | undefined) ?? lookupField?.dataSource ?? fieldMeta?.dataSource ?? contextDataSource;
 
   /** Resolve dependent values from the explicit prop (preferred), the form-data
    *  context provided by @object-ui/react, or finally `ctx.data` (record scope). */
@@ -369,7 +387,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
 
   // Optional create-new callback
   const onCreateNew: ((searchQuery: string) => void) | undefined =
-    (props as any).onCreateNew ?? lookupField?.onCreateNew;
+    props.onCreateNew ?? lookupField?.onCreateNew;
 
   // State for the full Record Picker dialog (Level 2)
   const [isPickerOpen, setIsPickerOpen] = useState(false);
@@ -657,7 +675,7 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   // auto-fill sibling fields from it — e.g. a line-item grid copying a product's
   // unit_price/description when the item is chosen. When provided (single
   // select), it drives the update and the host owns the resulting value change.
-  const onSelectRecord = (props as any).onSelectRecord as ((record: LookupOption) => void) | undefined;
+  const onSelectRecord = props.onSelectRecord;
 
   const handleSelect = useCallback(
     (option: LookupOption) => {
@@ -906,25 +924,41 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
   // Compact mode (e.g. inside a line-item grid cell): show the selected value
   // INSIDE a borderless trigger on a single line — no chip stacked above a
   // separate "Select…" button (which double-stacks and wastes the row height).
-  const compact = !!(props as any).compact;
+  const compact = !!props.compact;
   const singleSelectedLabel = selectedOptions[0]?.label || selectedOptions[0]?.[displayField];
 
   // 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 as any).disabled}
-      data-testid={dependenciesMissing ? 'lookup-trigger-gated' : (((props as any).name || lookupField?.name) ? `lookup-trigger-${(props as any).name || lookupField.name}` : 'lookup-trigger')}
+      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).
@@ -1214,11 +1248,11 @@ export function LookupField({ value, onChange, field, readonly, ...props }: Fiel
           type="button"
           // Gated exactly like the main trigger (#2215) — pre-fix this button
           // opened the full unscoped table while the dependency was missing.
-          disabled={dependenciesMissing || (props as any).disabled}
+          disabled={dependenciesMissing || props.disabled}
           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

@@ -1,7 +1,7 @@
 import React from 'react';
 import { Button, Badge, cn } from '@object-ui/components';
 import { Plus, X, ExternalLink } from 'lucide-react';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * Master-Detail relationship data structure
@@ -23,9 +23,9 @@ export function MasterDetailField({
   readonly,
   className,
   ...props 
-}: FieldWidgetProps<MasterDetailValue[]>) {
+}: 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

@@ -1,7 +1,9 @@
 import React, { useEffect } from 'react';
 import { Badge, EmptyValue, cn } from '@object-ui/components';
 import type { OptionLike } from '@object-ui/core';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
+import { OptionsEmptyState } from './OptionsEmptyState';
 import { useCascadingOptions } from './useCascadingOptions';
 
 interface Option extends OptionLike { color?: string }
@@ -26,17 +28,17 @@ export function MultiSelectField({
   field,
   readonly,
   className,
-  schema,
   dependentValues,
   dependsOn: dependsOnProp,
-  emptyHint: _emptyHint,
+  emptyHint,
   dataSource: _dataSource,
+  error,
   ...props
-}: FieldWidgetProps<string[]>) {
-  const config = (field || schema) as any;
+}: FieldWidgetComponentProps<string[]>) {
+  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 as any).name || config?.name || (props as any).id || '';
+  const fieldName = props.name || config?.name || props.id || '';
 
   const dependsOn = config?.dependsOn ?? dependsOnProp;
   const { options, gated, dependsOnFields } = useCascadingOptions<Option>(
@@ -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}
     >
@@ -107,8 +122,9 @@ export function MultiSelectField({
             type="button"
             key={value}
             onClick={() => toggle(value)}
-            disabled={(props as any).disabled}
+            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

@@ -1,18 +1,19 @@
 import React from 'react';
 import { Input, EmptyValue } from '@object-ui/components';
 import { NumberFieldMetadata } from '@object-ui/types';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 
 /**
  * NumberField - Numeric input with optional decimal precision
  * Supports min/max/step constraints and configurable decimal precision
  */
-export function NumberField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<number>) {
+export function NumberField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<number>) {
   if (readonly) {
     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 { FieldWidgetProps } from './types';
+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 }: FieldWidgetProps<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

@@ -1,7 +1,8 @@
 import React from 'react';
 import { Combobox, EmptyValue, cn } from '@object-ui/components';
 import { SchemaRendererContext } from '@object-ui/react';
-import type { FieldWidgetProps } from './types';
+import type { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 import { useFieldTranslation } from './useFieldTranslation';
 
 /**
@@ -31,12 +32,13 @@ export function ObjectRefField({
   onChange,
   readonly,
   className,
+  error,
   ...props
-}: FieldWidgetProps<string>) {
+}: FieldWidgetComponentProps<string>) {
   const ctx = React.useContext(SchemaRendererContext);
   const { t } = useFieldTranslation();
-  const dataSource: any = (props as any).dataSource ?? (ctx as any)?.dataSource ?? null;
-  const disabled = (props as any).disabled as boolean | undefined;
+  const dataSource: any = props.dataSource ?? (ctx as any)?.dataSource ?? null;
+  const disabled = props.disabled;
 
   const [objects, setObjects] = React.useState<ObjectHeader[] | null>(null);
 
@@ -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');
+  });
+});