@object-ui/fields 17.2.0 → 17.3.0

package/src/widgets/__tests__/TextAreaField.mobileFullscreen.test.tsx

@@ -0,0 +1,175 @@
+/**
+ * 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.
+ */
+
+/**
+ * `TextAreaField`'s fullscreen affordance has ONE source (objectui#3232).
+ *
+ * It used to be read from four places with a `??` chain — a `mobileFullscreen`
+ * (camelCase) prop, `field.mobile_fullscreen`, a `mobile_fullscreen` prop, and
+ * `schema.mobile_fullscreen`. Only the field-metadata flag was ever produced:
+ * `ObjectForm` stamps it on long-text fields from
+ * `ObjectFormSchema.mobile.fullscreenLongText`. The camelCase prop had no
+ * producer anywhere in the repo, and the snake_case prop could not arrive
+ * because `stripRegisteredFieldProps` (components/src/renderers/form/form.tsx)
+ * removes it from what registered widgets are forwarded.
+ *
+ * So this file pins both halves of that convergence:
+ *
+ *  1. **The live path still works.** The metadata flag drives the affordance
+ *     end to end — button, dialog, and the committed edit. Deleting the dead
+ *     reads must not have cost the working behaviour, and this is the test
+ *     that fails if a future refactor drops the real read too.
+ *  2. **The retired prop spellings are gone**, at compile time (they are not
+ *     on the closed `FieldWidgetComponentProps`, objectui#3221) and at runtime
+ *     (a host that passes one anyway gets no affordance). Convergence means a
+ *     misspelled flag is now inert and loud, not silently absorbed.
+ *
+ * Note the built-in (unregistered) `textarea` branch in `form.tsx` reads
+ * `mobile_fullscreen || fullscreen` off the form-field props and renders its
+ * own `FullscreenTextarea`. That is a separate, live path and is untouched
+ * here — this file is about the registered `field:textarea` widget only.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import '@testing-library/jest-dom';
+
+import { TextAreaField } from '../TextAreaField';
+import type { FieldWidgetComponentProps } from '../types';
+import type { FieldMetadata } from '@object-ui/types';
+
+const fieldMeta = (extra: Record<string, unknown> = {}) =>
+  ({
+    name: 'description',
+    label: 'Description',
+    type: 'textarea',
+    ...extra,
+  }) as unknown as FieldMetadata;
+
+describe('TextAreaField mobile fullscreen — the metadata flag is the only source', () => {
+  it('renders the expand affordance when the field metadata sets mobile_fullscreen', () => {
+    render(
+      <TextAreaField
+        value="hello"
+        onChange={() => {}}
+        field={fieldMeta({ mobile_fullscreen: true })}
+      />,
+    );
+
+    expect(screen.getByTestId('textarea-fullscreen-toggle')).toBeInTheDocument();
+  });
+
+  it('opens the fullscreen dialog and commits the edited draft', () => {
+    const onChange = vi.fn();
+    render(
+      <TextAreaField
+        value="hello"
+        onChange={onChange}
+        field={fieldMeta({ mobile_fullscreen: true })}
+      />,
+    );
+
+    // Closed until the affordance is used — the dialog is not just mounted.
+    expect(screen.queryByTestId('textarea-fullscreen-dialog')).not.toBeInTheDocument();
+
+    fireEvent.click(screen.getByTestId('textarea-fullscreen-toggle'));
+    expect(screen.getByTestId('textarea-fullscreen-dialog')).toBeInTheDocument();
+
+    const dialogInput = screen.getByTestId('textarea-fullscreen-input');
+    expect(dialogInput).toHaveValue('hello');
+
+    fireEvent.change(dialogInput, { target: { value: 'hello from fullscreen' } });
+    // The draft is local until "Done" — the host is not notified per keystroke.
+    expect(onChange).not.toHaveBeenCalled();
+
+    fireEvent.click(screen.getByTestId('textarea-fullscreen-save'));
+    expect(onChange).toHaveBeenCalledWith('hello from fullscreen');
+  });
+
+  it('no longer reads the flag off a `schema` prop (objectui#3233)', () => {
+    // This used to be the second carrier: `SchemaRenderer` passed the authored
+    // node as `schema` and the widget resolved `field || schema`. v17 converged
+    // that at the producer — the registry adapter (`withFieldCarrier`) maps the
+    // SDUI node onto `field` before any widget sees it, so the widget has one
+    // read. A host that still passes `schema` is now inert AND loud: a compile
+    // error on the closed props type, and no affordance at runtime.
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      const legacyHostProps = {
+        schema: fieldMeta({ mobile_fullscreen: true }),
+      } as unknown as Partial<FieldWidgetComponentProps<string>>;
+
+      render(
+        <TextAreaField
+          value=""
+          onChange={() => {}}
+          field={fieldMeta()}
+          {...legacyHostProps}
+        />,
+      );
+
+      expect(screen.queryByTestId('textarea-fullscreen-toggle')).not.toBeInTheDocument();
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+
+  it('renders no affordance when the metadata does not opt in', () => {
+    render(<TextAreaField value="hello" onChange={() => {}} field={fieldMeta()} />);
+
+    expect(screen.queryByTestId('textarea-fullscreen-toggle')).not.toBeInTheDocument();
+    expect(screen.queryByTestId('textarea-fullscreen-dialog')).not.toBeInTheDocument();
+  });
+});
+
+describe('TextAreaField mobile fullscreen — the retired prop spellings', () => {
+  it('does not declare them on the widget contract', () => {
+    const props = {} as FieldWidgetComponentProps<string>;
+
+    // Both were read by the widget and written by no host. With the closed
+    // props type (objectui#3221) they are now compile errors, so a future
+    // author reaches for the metadata flag instead of a silently ignored prop.
+    // @ts-expect-error `mobileFullscreen` is not part of this contract
+    void props.mobileFullscreen;
+    // @ts-expect-error `mobile_fullscreen` is a metadata key, not a widget prop
+    void props.mobile_fullscreen;
+    // …and the retired second METADATA carrier (objectui#3233). The flag has
+    // one source and that source now has one carrier.
+    // @ts-expect-error `schema` was retired from the widget contract in v17
+    void props.schema;
+
+    expect(true).toBe(true);
+  });
+
+  it('ignores them at runtime when a host passes them anyway', () => {
+    // Untyped hosts (plain JS, `as any` spreads) can still get these onto the
+    // element. They must not resurrect the affordance: the metadata flag is
+    // the contract. Unknown props land on the DOM spread, so React's unknown
+    // -attribute warnings are expected noise here and are suppressed.
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => {});
+    try {
+      const hostProps = {
+        mobileFullscreen: true,
+        mobile_fullscreen: true,
+      } as unknown as Partial<FieldWidgetComponentProps<string>>;
+
+      render(
+        <TextAreaField
+          value="hello"
+          onChange={() => {}}
+          field={fieldMeta()}
+          {...hostProps}
+        />,
+      );
+
+      expect(screen.queryByTestId('textarea-fullscreen-toggle')).not.toBeInTheDocument();
+    } finally {
+      consoleError.mockRestore();
+    }
+  });
+});

package/src/widgets/toDomProps.ts

@@ -0,0 +1,175 @@
+/**
+ * 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 type { FieldWidgetComponentProps, FieldWidgetDomProps } from './types';
+
+/**
+ * The RUNTIME EXECUTOR of the "DOM pass-through" section of
+ * {@link FieldWidgetComponentProps} (objectui#3291).
+ *
+ * ## The defect
+ *
+ * Field widgets forwarded their leftover props to a control with a bare
+ * spread — `const { inputType, ...domProps } = props as any; <Input
+ * {...domProps} />`. Whatever a host handed the widget therefore became a DOM
+ * attribute. Measured on `origin/main`, a real form + a real widget:
+ *
+ * ```
+ * <input placeholder="PH-f" zzcanary="CANARY-STR" zzcanaryobj="[object Object]"
+ *        zzcanarynum="42" id="…" type="text" value="" name="f">
+ * ```
+ *
+ * The `[object Object]` this issue is named for is an authored field-config
+ * key being `String()`-ed onto an attribute. React 19 does not warn: an
+ * all-lowercase unknown attribute is passed through in complete silence, which
+ * is why this survived so long.
+ *
+ * ## Why a whitelist, and not a list of keys to drop
+ *
+ * The biggest leak source is not any NAMED renderer prop — it is the open tail
+ * of author-supplied keys. The form renderer destructures a fixed set of known
+ * keys and forwards `...fieldProps` verbatim
+ * (`components/src/renderers/form/form.tsx`), and `SchemaRenderer` is wider
+ * still: it spreads the whole authored node as props and has no strip layer at
+ * all, so on the SDUI path a widget's own spread is the ONLY line of defence.
+ *
+ * A blacklist enumerating today's renderer-only keys (`error`, `emptyHint`,
+ * `dataSource`, `dependentValues`, `dependsOn`, `options`, `inputType`, …)
+ * would pass every one of the canaries above and would not stop the next
+ * authored key either. Only "keep the known-safe set, drop the rest" closes
+ * it, which is what this function does.
+ *
+ * ## Declared = enforced
+ *
+ * {@link FieldWidgetComponentProps} already DECLARES the closed set of keys a
+ * widget may receive, and {@link FieldWidgetDomProps} names the subset that may
+ * legitimately reach a DOM element (objectui#3221). Until now that was a
+ * type-level claim a widget could violate at runtime simply by spreading. This
+ * function is that declaration's executable form, and TWO compile-time
+ * assertions below bind them in both directions — forwarding an undeclared key
+ * and declaring an unforwarded DOM key are each a compile error. Neither
+ * direction can drift silently.
+ *
+ * ## Deliberately NOT forwarded
+ *
+ * `role` and other HTML global attributes are absent because the contract does
+ * not declare them. They reached the DOM before this change only through the
+ * open spread. If a field node should be able to author one, DECLARE it on
+ * `FieldWidgetComponentProps` first and add it here — do not reopen the spread
+ * (AGENTS.md #0.1: fix the contract, never widen the consumer).
+ */
+const DOM_PASS_THROUGH_KEYS = [
+  /* ── The contract's own "DOM pass-through" block, verbatim ─────────────── */
+  'id',
+  'name',
+  'autoFocus',
+  'tabIndex',
+  'onBlur',
+  'onFocus',
+  'onClick',
+
+  /* ── Two more declared keys that ARE valid DOM attributes ──────────────── */
+  //
+  // Both are declared on `FieldWidgetComponentProps` under the
+  // controlled-input contract rather than the DOM block, because widgets also
+  // INTERPRET them (`className` gets composed with the widget's own classes;
+  // `disabled` is OR-ed with `readonly`). They are still `class` and
+  // `disabled` on the element, and every widget here already forwards them.
+  //
+  // Withholding them would make this helper a silent styling- and
+  // interactivity-dropper: `<Input {...toDomProps(props)} />` — the shape this
+  // change teaches every future widget author to write — would quietly lose
+  // the host's className and disabled state. That is a NEW silent failure of
+  // exactly the kind the whitelist exists to prevent, so they are forwarded.
+  'className',
+  'disabled',
+] as const;
+
+type DomPassThroughKey = (typeof DOM_PASS_THROUGH_KEYS)[number];
+
+/**
+ * Compile-time link to the declaration, direction 1 of 2: every key forwarded
+ * at runtime must exist on {@link FieldWidgetComponentProps}. Deleting a key
+ * from the contract without deleting it here is a compile error.
+ *
+ * Catches: helper forwards something the contract no longer declares.
+ */
+type EveryForwardedKeyIsDeclared =
+  DomPassThroughKey extends keyof FieldWidgetComponentProps ? true : never;
+const _everyForwardedKeyIsDeclared: EveryForwardedKeyIsDeclared = true;
+void _everyForwardedKeyIsDeclared;
+
+/**
+ * Direction 2 of 2: every key of {@link FieldWidgetDomProps} — the contract's
+ * DOM pass-through block — must be one this helper actually forwards. Adding a
+ * DOM key to the contract without adding it to `DOM_PASS_THROUGH_KEYS` is a
+ * compile error.
+ *
+ * Catches: DECLARED BUT NOT DELIVERED — a key that type-checks, reads as
+ * supported, and silently never reaches the element. That is the failure this
+ * repo treats as first-class (objectui#3290's `aria-required` that never
+ * reached a control; objectui#3222's validation slot nobody produced), and it
+ * is the one direction the leak test structurally CANNOT see: that test looks
+ * for attributes that arrive, not for ones that go missing.
+ *
+ * `className` / `disabled` are not part of `FieldWidgetDomProps` (they are
+ * controlled-input keys this helper also forwards — see above), so they are
+ * bound by direction 1 only. That is deliberate, not an oversight.
+ */
+type EveryDeclaredDomKeyIsForwarded =
+  keyof FieldWidgetDomProps extends DomPassThroughKey ? true : never;
+const _everyDeclaredDomKeyIsForwarded: EveryDeclaredDomKeyIsForwarded = true;
+void _everyDeclaredDomKeyIsForwarded;
+
+const DOM_PASS_THROUGH: ReadonlySet<string> = new Set<string>(DOM_PASS_THROUGH_KEYS);
+
+/**
+ * `aria-*` is declared on the contract as React's `AriaAttributes`; `data-*`
+ * is declared as an open template-literal family (open in HTML too, and the
+ * only open family the contract has). Both are matched by prefix so the helper
+ * needs no per-attribute list.
+ */
+function isOpenDomFamily(key: string): boolean {
+  return key.startsWith('data-') || key.startsWith('aria-');
+}
+
+/** The subset of `P` this helper forwards, with each key's declared type. */
+export type DomProps<P> = Pick<P, Extract<keyof P, DomPassThroughKey>> & {
+  [K in Extract<keyof P, `data-${string}` | `aria-${string}`>]: P[K];
+};
+
+/**
+ * Keep only what may legitimately become a DOM attribute, and drop everything
+ * else — renderer plumbing, and any extra key an author put on the field
+ * config or SDUI node.
+ *
+ * Replaces the bare `{...props}` spread in every field widget that renders a
+ * host element:
+ *
+ * ```tsx
+ * // before — forwards whatever it was handed
+ * const { inputType, ...domProps } = props as any;
+ * return <Input {...domProps} … />;
+ *
+ * // after
+ * return <Input {...toDomProps(props)} … />;
+ * ```
+ *
+ * Semantic props a widget INTERPRETS (`value`, `onChange`, `field`,
+ * `readonly`, `error`, …) are read from `props` as before; this function only
+ * governs what gets spread.
+ */
+export function toDomProps<P extends object>(props: P): DomProps<P> {
+  const domProps: Record<string, unknown> = {};
+  for (const key of Object.keys(props)) {
+    if (DOM_PASS_THROUGH.has(key) || isOpenDomFamily(key)) {
+      domProps[key] = (props as Record<string, unknown>)[key];
+    }
+  }
+  return domProps as DomProps<P>;
+}

package/src/widgets/types.ts

@@ -1,6 +1,49 @@
 import type { AriaAttributes, FocusEventHandler, MouseEventHandler } from 'react';
 import type { DependsOnInput, FieldMetadata } from '@object-ui/types';
 
+/**
+ * DOM pass-through: what a widget's `...props` spread may legitimately put on
+ * the element it renders.
+ *
+ * A NAMED type rather than an inline block of {@link FieldWidgetComponentProps}
+ * so the compiler can bind it to its runtime executor in BOTH directions
+ * (objectui#3291). `toDomProps` asserts:
+ *
+ *  - every key it forwards is declared on the widget contract — deleting one
+ *    here without deleting it there is a compile error;
+ *  - every key of THIS type is one it forwards — adding one here without
+ *    adding it to `DOM_PASS_THROUGH_KEYS` is a compile error too.
+ *
+ * The second direction is the one that matters for the failure mode this repo
+ * treats as first-class: DECLARED BUT NOT DELIVERED (objectui#3290's
+ * `aria-required` that never reached a control, objectui#3222's validation slot
+ * nobody produced). Without it, a key added here would type-check, read as
+ * supported, and silently never reach the DOM — and the leak test cannot see
+ * that class of bug, because it looks for attributes that ARRIVE, not for ones
+ * that go missing.
+ *
+ * `className` and `disabled` are deliberately NOT here. They are DOM-legal and
+ * `toDomProps` does forward them, but they are declared on the controlled-input
+ * block of {@link FieldWidgetComponentProps} because widgets also INTERPRET
+ * them (className is composed with the widget's own classes; disabled is OR-ed
+ * with readonly). They are therefore bound in the forward direction only.
+ *
+ * `AriaAttributes` and the `data-${string}` family are matched by prefix at
+ * runtime rather than key-by-key, so they are intersected in separately.
+ *
+ * Adding a key here is a contract change: say who produces it and who reads it.
+ */
+export type FieldWidgetDomProps = {
+  id?: string;
+  /** react-hook-form's field name, spread in by the form renderer. */
+  name?: string;
+  autoFocus?: boolean;
+  tabIndex?: number;
+  onBlur?: FocusEventHandler<HTMLElement>;
+  onFocus?: FocusEventHandler<HTMLElement>;
+  onClick?: MouseEventHandler<HTMLElement>;
+};
+
 /**
  * Props every field widget in this package receives at RUNTIME.
  *
@@ -14,13 +57,27 @@ import type { DependsOnInput, FieldMetadata } from '@object-ui/types';
  * the widgets in this directory actually implement, against
  * `@object-ui/types`'s much richer `FieldMetadata`.
  *
- * The two are NOT interchangeable, and the divergence is not cosmetic: the
- * spec's contract names the error slot `error`, this one names it
- * `errorMessage`, so a widget written to the spec's declared props renders no
- * validation message here. That divergence is tracked in objectui#3222 and is
- * deliberately NOT resolved here — but it is now *visible*: reading
- * `props.error` or `props.required` off this type is a compile error rather
- * than a silent `any`.
+ * The two are NOT interchangeable, but they no longer disagree on the
+ * validation slot: this type used to call it `errorMessage` while the spec
+ * calls it `error`, so a widget written to the published contract read
+ * `undefined` forever. objectui#3222 resolved that in the direction the
+ * contract points — the slot below IS the spec's `error`, and the form
+ * renderer now produces it (see `error`'s own doc comment). Reading
+ * `props.required` off this type is still a compile error rather than a
+ * silent `any`; that key is deliberately NOT lowered here (see below).
+ *
+ * ## Why `required` is still absent, though the spec declares it
+ *
+ * The required MARKER is drawn exactly once, by the form renderer's
+ * `<FormLabel>` (the `*` with `aria-label="required"`, which the label
+ * association folds into the control's accessible name). Handing `required`
+ * to widgets would give that marker a second possible author, and the very
+ * next AI-written widget draws its own asterisk — the same double-display
+ * failure that keeps the validation TEXT out of the widget below. The a11y
+ * state a widget genuinely could carry is `aria-required` on the input, and
+ * that needs no new key at all: `AriaAttributes` is already part of this type
+ * and every widget already forwards it to its control. Tracked separately;
+ * do not add `required` here to "align" without that decision.
  *
  * ## Why there is no `[key: string]: any` (objectui#3221)
  *
@@ -40,6 +97,22 @@ import type { DependsOnInput, FieldMetadata } from '@object-ui/types';
  * is expressed as a template-literal index signature, which — unlike
  * `[key: string]` — leaves `keyof` finite, so an undeclared prop still fails.
  *
+ * ## Why there is no `schema` (objectui#3233)
+ *
+ * `schema` used to be declared here as a SECOND carrier for what `field`
+ * already means — `SchemaRenderer` handed the SDUI node down as `schema`, the
+ * form renderer forwarded `schema={props.field || props.schema || props}`
+ * *alongside* `field`, and ~30 widgets resolved their config as
+ * `field || schema`. One concept, two keys, two producers: exactly the
+ * consumer-side tolerance AGENTS.md #0.1 forbids, and exactly the shape that
+ * lets an AI-written widget pick the wrong spelling and still "work" under one
+ * host while reading `undefined` under another.
+ *
+ * v17 converged it at the PRODUCERS. `field` is the only carrier a widget ever
+ * sees; the SDUI node → `field` translation happens once, in this package's
+ * registry adapter (`withFieldCarrier`), not ~30 times in the widgets. Reading
+ * `props.schema` is now a compile error rather than a silent second contract.
+ *
  * Adding a key here is a contract change: say who produces it and who reads it.
  */
 export type FieldWidgetComponentProps<T = any> = {
@@ -48,14 +121,38 @@ export type FieldWidgetComponentProps<T = any> = {
   value: T;
   onChange: (val: T) => void;
   /**
-   * The field's metadata. Deliberately the looser `@object-ui/types` shape
-   * rather than the spec's, to avoid a circular dependency for now.
+   * The field's metadata, and the SINGLE carrier for it (objectui#3233).
+   *
+   * Deliberately the looser `@object-ui/types` shape rather than the spec's,
+   * to avoid a circular dependency for now.
+   *
+   * Every host produces it: the form renderer's `renderFieldComponent`, the
+   * inline-edit hosts (`FieldEditWidget`), `ActionParamDialog` /
+   * `BulkActionDialog`, and — since #3233 — the registry adapter that adapts
+   * `SchemaRenderer`'s SDUI node onto this contract (`withFieldCarrier` in
+   * `packages/fields/src/withFieldCarrier.tsx`). A widget reads `props.field`
+   * and nothing else; there is no second key to check.
    */
   field: FieldMetadata;
   readonly?: boolean;
   disabled?: boolean;
   className?: string;
-  errorMessage?: string;
+  /**
+   * The active validation message for this field, named as
+   * `@objectstack/spec/ui`'s `FieldWidgetPropsSchema` names it (objectui#3222).
+   *
+   * **Producer**: the form renderer, from react-hook-form's
+   * `fieldState.error?.message` (`packages/components/src/renderers/form/
+   * form.tsx`). Before #3222 nothing in the repo produced it under EITHER
+   * spelling, so the seven widgets computing `aria-invalid={!!errorMessage}`
+   * were computing it from a permanent `undefined` — `aria-invalid` was never
+   * once set and a screen reader was never told the field had failed.
+   *
+   * **Consumer**: a widget reads this ONLY to drive `aria-invalid` on the
+   * control it renders. The message TEXT stays with the form renderer's
+   * `<FormMessage/>`; a widget that also renders it double-displays it.
+   */
+  error?: string;
   /**
    * Upload widgets (`file`/`image`) fire this when their in-progress state
    * flips, so a host can block submit until a presigned upload settles. Other
@@ -65,17 +162,6 @@ export type FieldWidgetComponentProps<T = any> = {
 
   /* ── Host plumbing: what a rendering host actually forwards ─────────────── */
 
-  /**
-   * The raw authored node the widget was rendered from. Two hosts supply it:
-   * `SchemaRenderer` (`<Component schema={schema} {...schema} />`) and the
-   * form renderer's `renderFieldComponent` (`schema={props.field || ...}`),
-   * which is why ~25 widgets read `field || schema` for their config.
-   *
-   * This is a second carrier for what `field` already means, i.e. a de-facto
-   * second contract (AGENTS.md #0.1) — declared here so it is at least
-   * visible; converging the two is tracked separately.
-   */
-  schema?: FieldMetadata | Record<string, unknown>;
   /**
    * DataSource for widgets that query records (lookup / user / object-ref /
    * recipient-picker / grid). Injected by the form renderer for the field
@@ -99,9 +185,27 @@ export type FieldWidgetComponentProps<T = any> = {
    */
   dependsOn?: DependsOnInput;
   /**
-   * Hint shown when a dependency-gated option list is still waiting on its
-   * controlling field. Forwarded by the form renderer; the option widgets in
-   * this package currently discard it and render their own message instead.
+   * Controlling-field name → its human LABEL, for widgets that have to NAME a
+   * sibling field in user-visible copy (the dependent-lookup gate hint).
+   *
+   * Only the form renderer knows a field's label — the widget sees its own
+   * metadata and a `depends_on` list of API names. Without this map the gate
+   * sentence interpolated the raw API name into every locale, `en` included
+   * ("Select crm_account first"), which is an internal identifier leaking into
+   * the UI, not merely an untranslated word (objectstack#5407). This is the
+   * lookup-side counterpart of `emptyHint`, which the form already resolves to
+   * labels for the fixed-option widgets. A name with no entry falls back to
+   * itself, so a host that passes nothing renders exactly what it did before.
+   */
+  dependsOnLabels?: Record<string, string>;
+  /**
+   * Hint shown when an option list cannot be filled — typically a
+   * dependency-gated list still waiting on its controlling field (#2284).
+   * Forwarded by the form renderer, which resolves the controlling fields to
+   * their human LABELS. **When supplied it wins**; the option widgets fall back
+   * to their own translated copy only when a host computed none (objectui#3231
+   * — they used to discard this prop and always render their own hardcoded
+   * English). See `OptionsEmptyState`, the single consumer.
    */
   emptyHint?: string;
   /**
@@ -121,17 +225,13 @@ export type FieldWidgetComponentProps<T = any> = {
    */
   onCreateNew?: (searchQuery: string) => void;
 
-  /* ── DOM pass-through: what `...props` may legitimately reach an input ──── */
-
-  id?: string;
-  /** react-hook-form's field name, spread in by the form renderer. */
-  name?: string;
-  autoFocus?: boolean;
-  tabIndex?: number;
-  onBlur?: FocusEventHandler<HTMLElement>;
-  onFocus?: FocusEventHandler<HTMLElement>;
-  onClick?: MouseEventHandler<HTMLElement>;
-} & AriaAttributes & {
+  /* ── DOM pass-through ───────────────────────────────────────────────────── */
+  //
+  // Lives in the named {@link FieldWidgetDomProps} above, because that is what
+  // lets the compiler bind the declaration to `toDomProps` — its runtime
+  // executor — in BOTH directions (objectui#3291). Add a DOM key THERE, not
+  // here, and the compiler will make you add it to the whitelist too.
+} & FieldWidgetDomProps & AriaAttributes & {
   /**
    * Arbitrary `data-*` attributes (test ids, analytics hooks). Open by design,
    * but a template-literal key — `keyof` stays finite, so this does NOT

package/src/widgets/useFieldTranslation.ts

@@ -39,6 +39,12 @@ const FIELD_DEFAULTS: Record<string, string> = {
   'lookup.nextPage': 'Next page',
   'lookup.jumpToPage': 'Jump to page',
   'lookup.retry': 'Retry',
+  // objectui#3231 — the empty / dependency-gated state of the fixed-option
+  // widgets (select, multiselect, radio, checkboxes). Only used when the host
+  // supplies no `emptyHint`; the gate sentence shares its key with the form
+  // renderer so both cannot drift apart in a locale.
+  'fields.options.empty': 'No options available',
+  'fields.options.selectFirst': 'Select {{fields}} first',
   // objectstack#3821 — sharing-rule authoring widgets (object-ref /
   // recipient-picker / filter-condition). The recipient placeholder is keyed
   // PER TYPE rather than interpolating the enum value into an English
@@ -69,6 +75,60 @@ const FIELD_DEFAULTS: Record<string, string> = {
   'fields.filterCondition.jsonOnly': 'This criteria can only be edited as JSON',
   'fields.filterCondition.editAsJson': 'Edit as JSON',
   'fields.filterCondition.useVisualBuilder': 'Use visual builder',
+  // objectui#3342 — the tags widget's input hint. Used only when the field
+  // author declared no `placeholder` of their own (author declaration wins).
+  'fields.tags.placeholder': 'Type and press Enter to add…',
+  // objectui#3406 — the accessible name of `TextAreaField`'s character
+  // counter, rendered only when the field declares `maxLength`. The visible
+  // `{n}/{max}` is digits; this sentence is what a screen reader speaks, and
+  // the element is `aria-live`, so before the key existed a non-English
+  // session heard English on every keystroke. Byte-identical to the literal
+  // it replaces, so a no-provider render is unchanged.
+  'fields.textarea.characterCount': 'Character count: {{count}} of {{max}}',
+  // objectui#3408 — the NEAR-LIMIT warning, spoken by the counter's status
+  // region after the typist pauses and only once they are inside the last 10%
+  // (or last 20 characters) of the cap. The sentence above became the field's
+  // `aria-describedby` description in the same change; this one is the only
+  // thing that is ever announced mid-typing, which is why it says what is
+  // LEFT rather than repeating the whole count.
+  //
+  // Colon form, not "You have {{count}} characters remaining": `count` makes
+  // i18next attempt plural lookup (`_one` / `_few` / …) before the base key,
+  // and these packs declare the base key only — the same base-key fallback
+  // `characterCount` already relies on. A sentence whose grammar does not
+  // depend on the number stays correct at 1 without ten plural entries per
+  // pack, and matches the sibling key's shape.
+  'fields.textarea.charactersRemaining': 'Characters remaining: {{count}}',
+  // objectui#3404 — the shared fullscreen long-text dialog
+  // (`FullscreenFieldEditor`, reached from `TextAreaField` and
+  // `RichTextField` when `mobile_fullscreen` is set).
+  //
+  // Deliberately the SAME `form.fullscreen.*` / `common.cancel` keys the
+  // built-in branch consumes (`FullscreenTextarea` in
+  // `components/src/renderers/form/form.tsx`, objectui#3272) rather than
+  // `fields.fullscreen.*` twins. One form-level setting
+  // (`ObjectFormSchema.mobile.fullscreenLongText`) projects onto BOTH render
+  // paths inside a single form, so a second copy of this copy is guaranteed
+  // drift — the shape #3231/#3263 had to undo — and would mean editing ten
+  // locale packs to say what they already say. `common.cancel` is already
+  // declared above and is reused here for exactly that reason.
+  //
+  // The values are byte-identical to the English literals they replaced, so
+  // a widget rendered with no I18nProvider (standalone/embedded hosts, and
+  // every bare-render test in this package) shows what it always did instead
+  // of a raw key. Measured before the change: with no provider mounted, bare
+  // `useObjectTranslation().t` returns the key itself
+  // (`common.cancel` → "common.cancel"), which is why this goes through
+  // `createSafeTranslation` like the built-in branch does.
+  'form.fullscreen.title': 'Edit text',
+  'form.fullscreen.description': 'Edit the full text value, then save or cancel your changes.',
+  'form.fullscreen.done': 'Done',
+  // Kept as ONE interpolated sentence with a translated generic noun standing
+  // in for a missing label — the literal's own shape
+  // (`Edit ${label ?? 'text'} fullscreen`). A second, label-less sentence key
+  // would need ten new pack entries to say the same thing.
+  'form.fullscreen.toggle': 'Edit {{label}} fullscreen',
+  'form.fullscreen.textFallback': 'text',
   // objectui#2600 B5 — capability picker scope group headers.
   'capability.group.platform': 'Platform',
   'capability.group.org': 'Organization',