@object-ui/fields 17.1.0 → 17.3.0

package/src/widgets/SelectField.tsx

@@ -10,8 +10,10 @@ import {
 import { isValueStillOffered } from '@object-ui/core';
 import { SelectFieldMetadata } from '@object-ui/types';
 import { useFieldTranslation } from './useFieldTranslation';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
 import { MultiSelectField } from './MultiSelectField';
+import { OptionsEmptyState } from './OptionsEmptyState';
 import { useCascadingOptions } from './useCascadingOptions';
 
 /**
@@ -29,12 +31,16 @@ import { useCascadingOptions } from './useCascadingOptions';
  * the shared {@link useCascadingOptions} hook (#2715), so single and multi stay
  * in lockstep.
  */
-export function SelectField(props: FieldWidgetProps<any>) {
-  const config = (props.field || (props as any).schema) as SelectFieldMetadata | undefined;
+export function SelectField(props: FieldWidgetComponentProps<any>) {
+  const config = props.field as SelectFieldMetadata | undefined;
   if ((config as any)?.multiple) {
+    // NOT `toDomProps` — this is a widget-to-widget delegation, not a DOM
+    // spread. `MultiSelectField` implements the same contract and needs the
+    // whole of it (`value`, `onChange`, `field`, `dataSource`, …); narrowing
+    // here to the DOM whitelist would hand it an empty widget.
     return <MultiSelectField {...props} />;
   }
-  return <SingleSelectField {...(props as FieldWidgetProps<string>)} />;
+  return <SingleSelectField {...(props as FieldWidgetComponentProps<string>)} />;
 }
 
 /**
@@ -53,21 +59,21 @@ function SingleSelectField({
   onChange,
   field,
   readonly,
-  schema,
+  error,
   dependentValues,
   dependsOn: dependsOnProp,
-  emptyHint: _emptyHint,
+  emptyHint,
   dataSource: _dataSource,
   ...props
-}: FieldWidgetProps<string>) {
-  const config = (field || schema) as SelectFieldMetadata;
+}: FieldWidgetComponentProps<string>) {
+  const config = field as SelectFieldMetadata;
   const rawOptions = config?.options || [];
   const { t } = useFieldTranslation();
   // Stable hook for automation/e2e — react-hook-form + Radix Select cannot be
   // driven by synthetic DOM events, so e2e must target the trigger/options by a
   // deterministic testid keyed on the field name. `props.name` is the
   // react-hook-form field name spread in by the form renderer (FormField).
-  const fieldName = (props as any).name || (config as any)?.name || props.id || '';
+  const fieldName = props.name || (config as any)?.name || props.id || '';
 
   const dependsOn = (config as any)?.dependsOn ?? dependsOnProp;
   const { options, gated, dependsOnFields } = useCascadingOptions(
@@ -93,30 +99,55 @@ function SingleSelectField({
 
   // A select with no options is unfillable — a silently-empty Radix dropdown
   // reads as "broken widget" and hides the real cause. Surface a legible state:
-  // a dependency-gated list prompts for its controlling field; an unconfigured
-  // list says so. Mirrors the inline form renderer's behaviour.
+  // the host's `emptyHint` when it computed one (it knows the controlling
+  // fields' LABELS), else this widget's own translated copy. Shared with the
+  // other option widgets 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 ? `select-empty-${fieldName}` : undefined}
-        className="flex 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 ? `select-empty-${fieldName}` : undefined}
+        className="h-9"
+      />
     );
   }
 
+  // Radix `Select.Root` renders no DOM element of its own — anything it does
+  // not recognise (every `aria-*` / `data-*` a host hands this widget) is
+  // silently DROPPED, never reaching a real element. That is how a required
+  // select failed validation with the red message on screen while assistive
+  // tech was told nothing (objectui#3306): the form renderer's `aria-invalid`
+  // / `aria-describedby` / `aria-required` landed on Root and vanished. The
+  // DOM pass-through therefore goes to `SelectTrigger` — the focusable
+  // `<button role="combobox">` a user and their screen reader actually
+  // interact with — with two deliberate exceptions kept on Root:
+  //
+  // - `name`: the ONE whitelist key Root genuinely consumes — it forwards it
+  //   to the hidden native `<select>` that takes part in form submission.
+  //   On the trigger it would sit uselessly on a non-submitter `<button>`.
+  // - `disabled`: Root is the single authority (it disables trigger, item
+  //   interaction and the hidden select together); forwarding the raw prop to
+  //   the trigger as well would give the state a second, OR-merged author.
+  const { name: domName, disabled: _domDisabled, ...triggerDomProps } = toDomProps(props);
+
   return (
     <Select
-      {...props}
+      name={domName}
       value={value}
       onValueChange={onChange}
       disabled={readonly || props.disabled}
     >
-      <SelectTrigger className={props.className} id={props.id} data-testid={fieldName ? `select-trigger-${fieldName}` : undefined}>
+      <SelectTrigger
+        {...triggerDomProps}
+        data-testid={fieldName ? `select-trigger-${fieldName}` : undefined}
+        // AFTER the spread so this widget's own computation wins, the #3222
+        // discipline: `error` is the published validation slot
+        // (`FieldWidgetPropsSchema`), and `!!undefined` must yield an explicit
+        // `"false"` — a valid field SAYS it is valid rather than staying mute.
+        aria-invalid={!!error}
+      >
         <SelectValue placeholder={config?.placeholder || t('common.selectOption')} />
       </SelectTrigger>
       <SelectContent position="popper">

package/src/widgets/SignatureField.tsx

@@ -1,13 +1,13 @@
 import React, { useRef, useEffect } from 'react';
 import { Button } from '@object-ui/components';
 import { Eraser } from 'lucide-react';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * Signature field widget - provides a signature pad for capturing signatures
  * Outputs signature as a base64 PNG image
  */
-export function SignatureField({ value, onChange, readonly }: FieldWidgetProps<string>) {
+export function SignatureField({ value, onChange, readonly }: FieldWidgetComponentProps<string>) {
   const canvasRef = useRef<HTMLCanvasElement>(null);
   const [isDrawing, setIsDrawing] = React.useState(false);
   const [isEmpty, setIsEmpty] = React.useState(!value);

package/src/widgets/SliderField.tsx

@@ -1,14 +1,14 @@
 import React from 'react';
 import { Slider } from '@object-ui/components';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * Slider field widget - provides a range slider input
  * Supports numeric values with configurable min, max, and step
  */
-export function SliderField({ value, onChange, field, readonly, ...props }: FieldWidgetProps<number>) {
+export function SliderField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<number>) {
   // Get slider-specific configuration from field metadata
-  const sliderField = (field || (props as any).schema) as any;
+  const sliderField = field as any;
   const min = sliderField?.min ?? 0;
   const max = sliderField?.max ?? 100;
   const step = sliderField?.step ?? 1;

package/src/widgets/SummaryField.tsx

@@ -1,13 +1,13 @@
 import React from 'react';
 import { EmptyValue } from '@object-ui/components';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
 
 /**
  * SummaryField - Read-only aggregation field
  * Values are aggregated from related records and cannot be edited
  */
-export function SummaryField({ value, field, ...props }: FieldWidgetProps<any>) {
-  const summaryField = (field || (props as any).schema) as any;
+export function SummaryField({ value, field, ...props }: FieldWidgetComponentProps<any>) {
+  const summaryField = field as any;
   const summaryType = summaryField?.summary_type || 'count';
 
   if (value == null) {

package/src/widgets/TagsField.placeholder.no-provider.test.tsx

@@ -0,0 +1,68 @@
+/**
+ * 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 tags widget's placeholder with NO `I18nProvider` mounted
+ * (objectui#3342) — 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. This is also where the
+ * Commandment #-1 pin lives: the copy shipped FROM CODE (the no-provider
+ * default) carries no CJK — Chinese exists only in the zh locale pack and can
+ * only arrive through a provider.
+ *
+ * Why a separate FILE rather than another case in
+ * `TagsField.placeholder.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. Vitest's per-file isolation is what
+ * makes this file's observation honest (same split as
+ * `OptionsEmptyState.no-provider.test.tsx`).
+ */
+import { describe, it, expect, vi } from 'vitest';
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { TagsField } from './TagsField';
+
+function renderTags(field: Record<string, unknown>) {
+  return render(
+    <TagsField
+      value={[]}
+      onChange={vi.fn()}
+      field={field as any}
+      {...({ name: 'labels' } as any)}
+    />,
+  );
+}
+
+const input = () => screen.getByRole('textbox');
+
+describe('TagsField placeholder — English fallback survives with no i18n configured', () => {
+  it('renders the English default, not a raw key', () => {
+    renderTags({ name: 'labels', type: 'tags' });
+    expect(input()).toHaveAttribute('placeholder', 'Type and press Enter to add…');
+    expect(input().getAttribute('placeholder')).not.toContain('fields.tags');
+  });
+
+  it('the code-shipped default carries no CJK (Commandment #-1)', () => {
+    renderTags({ name: 'labels', type: 'tags' });
+    // With no provider mounted, whatever renders here came from CODE
+    // (FIELD_DEFAULTS) — the commandment pin: no Chinese in the codebase.
+    // Escaped ranges on purpose: a literal CJK class would itself violate
+    // the commandment this test enforces (same shape as objectui#3321's pin).
+    expect(input().getAttribute('placeholder')).not.toMatch(/[\u3000-\u30ff\u4e00-\u9fff]/);
+  });
+
+  it('the author-declared field.placeholder still wins without a provider', () => {
+    renderTags({ name: 'labels', type: 'tags', placeholder: 'Add product labels' });
+    expect(input()).toHaveAttribute('placeholder', 'Add product labels');
+  });
+});

package/src/widgets/TagsField.placeholder.test.tsx

@@ -0,0 +1,95 @@
+/**
+ * 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 tags widget's input placeholder (objectui#3342).
+ *
+ * It used to be a hardcoded Chinese literal in code — a double violation:
+ * Commandment #-1 (English-only codebase) AND a bypass of the i18n channel the
+ * sibling widgets already use. The pinned resolution chain is:
+ *
+ *   1. `field.placeholder` — the field author's declaration always wins;
+ *   2. `t('fields.tags.placeholder')` — the widget's own copy, from the
+ *      locale packs via `useFieldTranslation()`;
+ *   3. the English default in FIELD_DEFAULTS when no I18nProvider is mounted
+ *      (that leg lives in `TagsField.placeholder.no-provider.test.tsx` — see
+ *      its header for why it must be a separate file).
+ *
+ * Chinese now lives in the zh locale pack only, which is what the zh-locale
+ * case below observes end-to-end.
+ */
+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 { TagsField } from './TagsField';
+
+function renderTags(
+  field: Record<string, unknown>,
+  { value = [] as string[], language }: { value?: string[]; language?: string } = {},
+) {
+  const element = (
+    <TagsField
+      value={value}
+      onChange={vi.fn()}
+      field={field as any}
+      {...({ name: 'labels' } as any)}
+    />
+  );
+  return render(
+    language ? (
+      <I18nProvider config={{ defaultLanguage: language, detectBrowserLanguage: false }}>
+        {element}
+      </I18nProvider>
+    ) : (
+      element
+    ),
+  );
+}
+
+const input = () => screen.getByRole('textbox');
+
+describe('TagsField placeholder — author declaration beats the widget copy (objectui#3342)', () => {
+  it('renders the author-declared field.placeholder', () => {
+    renderTags({ name: 'labels', type: 'tags', placeholder: 'Add product labels' }, { language: 'en' });
+    expect(input()).toHaveAttribute('placeholder', 'Add product labels');
+  });
+
+  it('the author declaration wins even under a non-English locale', () => {
+    // The author's copy is theirs verbatim — a locale switch must not
+    // overwrite an explicit declaration with the widget's own translation.
+    renderTags({ name: 'labels', type: 'tags', placeholder: 'Add product labels' }, { language: 'zh' });
+    expect(input()).toHaveAttribute('placeholder', 'Add product labels');
+    expect(input().getAttribute('placeholder')).not.toContain('输入后回车添加');
+  });
+});
+
+describe('TagsField placeholder — undeclared falls back to the translated key', () => {
+  it('renders the en pack copy under the en locale', () => {
+    renderTags({ name: 'labels', type: 'tags' }, { language: 'en' });
+    expect(input()).toHaveAttribute('placeholder', 'Type and press Enter to add…');
+  });
+
+  it('renders the zh pack copy under the zh locale — Chinese comes from the pack, not code', () => {
+    renderTags({ name: 'labels', type: 'tags' }, { language: 'zh' });
+    expect(input()).toHaveAttribute('placeholder', '输入后回车添加…');
+    // …and never the raw key.
+    expect(input().getAttribute('placeholder')).not.toContain('fields.tags');
+  });
+});
+
+describe('TagsField placeholder — shown only while the tag list is empty', () => {
+  it('is empty once a tag exists (the input is a continuation strip)', () => {
+    renderTags({ name: 'labels', type: 'tags', placeholder: 'Add product labels' }, {
+      value: ['alpha'],
+      language: 'en',
+    });
+    expect(input()).toHaveAttribute('placeholder', '');
+  });
+});

package/src/widgets/TagsField.tsx

@@ -1,15 +1,19 @@
 import React from 'react';
 import { Badge, Input, EmptyValue, cn } from '@object-ui/components';
-import { FieldWidgetProps } from './types';
+import { FieldWidgetComponentProps } from './types';
+import { toDomProps } from './toDomProps';
+import { useFieldTranslation } from './useFieldTranslation';
 
 /**
  * TagsField - free-form list of string tags. Type a value and press Enter (or
  * comma) to add it; click a tag's × to remove it. The stored value is a
  * string[]. Used for the `tags` field type.
  */
-export function TagsField({ value, onChange, field, readonly, className, ...props }: FieldWidgetProps<string[]>) {
+export function TagsField({ value, onChange, field, readonly, className, error, ...props }: FieldWidgetComponentProps<string[]>) {
   const tags: string[] = Array.isArray(value) ? value : value == null ? [] : [value as unknown as string];
   const [draft, setDraft] = React.useState('');
+  // Unconditional hook call (rules-of-hooks): before the readonly early return.
+  const { t } = useFieldTranslation();
 
   if (readonly) {
     if (tags.length === 0) return <EmptyValue />;
@@ -54,13 +58,30 @@ export function TagsField({ value, onChange, field, readonly, className, ...prop
         </Badge>
       ))}
       <Input
+        // DOM pass-through onto the real focusable control (objectui#3318):
+        // the whitelist spread carries the form renderer's id /
+        // aria-describedby to the input the user actually types in.
+        {...toDomProps(props)}
         value={draft}
         onChange={(e) => setDraft(e.target.value)}
         onKeyDown={onKeyDown}
         onBlur={() => addTag(draft)}
-        disabled={(props as any).disabled}
-        placeholder={tags.length === 0 ? '输入后回车添加…' : ''}
+        disabled={props.disabled}
+        // Placeholder chain (objectui#3342): the author-declared
+        // `field.placeholder` wins; otherwise the widget's own copy arrives
+        // via `useFieldTranslation()` — `fields.tags.placeholder` in the
+        // locale packs, English default from FIELD_DEFAULTS when no
+        // I18nProvider is mounted. This used to be a hardcoded Chinese
+        // literal (Commandment #-1); Chinese now lives in the zh pack only.
+        // Shown only while the list is empty — once a tag exists the input is
+        // a small continuation strip and the hint would be noise.
+        placeholder={tags.length === 0 ? field?.placeholder || t('fields.tags.placeholder') : ''}
         className="h-7 flex-1 border-0 bg-transparent p-0 px-1 shadow-none focus-visible:ring-0 min-w-[8ch]"
+        // AFTER the spread so this widget's own computation wins (the #3222
+        // discipline): `error` is the published validation slot, and
+        // `!!undefined` yields an explicit "false" — a valid field SAYS it is
+        // valid rather than staying mute.
+        aria-invalid={!!error}
       />
     </div>
   );