@object-ui/fields 17.1.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/file-value.ts

@@ -29,6 +29,8 @@
  * onto the same contract.
  */
 
+import { isFileIdToken } from '@objectstack/spec/data';
+
 /** A file value normalised for rendering, whatever form it arrived in. */
 export interface FileValueView {
   /** `sys_file` id, when the value carries one. */
@@ -45,12 +47,26 @@ export interface FileValueView {
 
 /**
  * A minted file id: uuid/nanoid-shaped, and crucially not a URL — a URL always
- * carries `:`, `/` or `.`, so it can never match. Mirrors the platform's
- * `isFileIdToken`, which is the arbiter on the server side of the same question.
+ * carries `:`, `/` or `.`, so it can never match.
+ *
+ * This IS the platform's arbiter now, not a mirror of it (objectui#3161,
+ * objectstack#4115 ledger batch 7). The declaration that stood here said it
+ * "mirrors the platform's `isFileIdToken`" while being a character-for-character
+ * copy of that function's body under that function's own name — the shape
+ * objectui#3003 argued about and objectui#3169 caught again in
+ * `isAggregatedViewContainer`: every value test and every behaviour test passes
+ * against a faithful copy, so reference identity is the only check that can tell
+ * a re-export from a fork. It is asserted in
+ * `__tests__/spec-symbol-batch7.test.ts`.
+ *
+ * Why it matters that this one is shared rather than duplicated: the regex is a
+ * WIRE decision. Widening it server-side (say, ids grow past 64 chars) while a
+ * copy here keeps the old bound turns every new id into "not a reference", and
+ * the widget then submits the legacy inline blob against a backend that expects
+ * a reference. That failure surfaces as a broken thumbnail, nowhere near a
+ * regex.
  */
-export function isFileIdToken(value: unknown): value is string {
-  return typeof value === 'string' && /^[A-Za-z0-9_-]{1,64}$/.test(value);
-}
+export { isFileIdToken };
 
 /**
  * The `sys_file` id a value refers to, or `undefined`.

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,19 +1,242 @@
-import { FieldMetadata } from '@object-ui/types';
+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.
+ *
+ * Named `FieldWidgetComponentProps`, not `FieldWidgetProps` (objectui#3161,
+ * objectstack#4115 ledger batch 7), adopting the name `@object-ui/app-shell`
+ * settled on for the same split in objectui#3169: `@objectstack/spec/ui` owns
+ * `FieldWidgetProps` for the DECLARED widget-plugin contract — a zod object
+ * (`FieldWidgetPropsSchema`) a plugin manifest is validated against, with
+ * `field` narrowed to `{ name?, label?, type: <the FieldType enum> }` and
+ * `readonly` / `required` carrying `.default()`s. This is the React interface
+ * the widgets in this directory actually implement, against
+ * `@object-ui/types`'s much richer `FieldMetadata`.
+ *
+ * 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)
+ *
+ * This type used to end in an index signature, "load-bearing" for the widgets'
+ * `...props` spreads. It was also why every drift above was invisible: **a type
+ * that claims to have every key can never be reported as missing one** (the
+ * objectstack#4075 mechanism). `props.required` and `props.error` were legal
+ * reads typed `any` and always `undefined` at runtime; a misspelled prop
+ * (`readOnly` for `readonly`, `onchange` for `onChange`) compiled; and any
+ * structural/parity comparison against the type was useless *in principle*,
+ * which is why the batch-7 symbol guard was the only detector that could see
+ * the collision at all.
+ *
+ * It is replaced by the CLOSED set below: the controlled-input contract, the
+ * host plumbing the form renderer genuinely forwards, and a DOM pass-through
+ * allowance. `data-*` is an open family by design (it is open in HTML too) and
+ * 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> = {
+  /* ── The controlled-input contract every widget implements ─────────────── */
 
-export type FieldWidgetProps<T = any> = {
   value: T;
   onChange: (val: T) => void;
-  // Use a looser type for field to avoid complex circular dependencies for now
-  field: FieldMetadata; 
+  /**
+   * 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
    * widgets ignore it.
    */
   onUploadingChange?: (uploading: boolean) => void;
-  [key: string]: any;
-}
+
+  /* ── Host plumbing: what a rendering host actually forwards ─────────────── */
+
+  /**
+   * DataSource for widgets that query records (lookup / user / object-ref /
+   * recipient-picker / grid). Injected by the form renderer for the field
+   * types that need it, and passed directly by inline-edit hosts. Option
+   * widgets destructure it purely to keep it off their DOM spread.
+   *
+   * Left structural (`unknown`): `@object-ui/fields` must not depend on a
+   * concrete adapter — every consumer narrows it itself.
+   */
+  dataSource?: unknown;
+  /**
+   * Live sibling-field values driving cascading / role-gated options and
+   * dependent lookups (ADR-0058, #2215/#2284). The form renderer passes the
+   * in-progress record; widgets fall back to `SchemaRendererContext`.
+   */
+  dependentValues?: Record<string, unknown>;
+  /**
+   * Controlling field(s) that gate this field's option list. Normally declared
+   * on the field metadata; accepted as a prop so a host can drive the gate for
+   * a field it synthesised. Field metadata wins when both are present.
+   */
+  dependsOn?: DependsOnInput;
+  /**
+   * 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;
+  /**
+   * Render as a single-line, borderless control for a grid cell (the inline
+   * editor and the line-item grid set it) instead of the full form layout.
+   */
+  compact?: boolean;
+  /**
+   * Receive the FULL selected record rather than just its id, so a host can
+   * auto-fill sibling fields from it (a line-item grid copying a product's
+   * price). When provided, the host owns the resulting value change.
+   */
+  onSelectRecord?: (record: Record<string, any>) => void;
+  /**
+   * Offer a "create new" affordance in a record picker, carrying whatever the
+   * user had typed. Also declarable on the field metadata.
+   */
+  onCreateNew?: (searchQuery: string) => void;
+
+  /* ── 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
+   * reintroduce the index signature objectui#3221 removed: `props.required`
+   * is still an error, `props['data-testid']` is still fine.
+   */
+  [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+};