@object-ui/fields 17.2.0 → 17.5.0

package/dist/widgets/address-format.d.ts

@@ -0,0 +1,68 @@
+import { AddressValue } from '@objectstack/spec/data';
+/**
+ * Address data structure — `z.input` of `@objectstack/spec`'s
+ * `AddressValueSchema`, which is what the platform stores and what
+ * `/api/v1/data/**` serves back.
+ *
+ * The postal code is spelled `postalCode` (objectstack#5143). `AddressField`
+ * used to read and write `zipCode`, a key that appears nowhere in the spec, so
+ * the stored postal code never reached the input — and whatever the user then
+ * typed into that apparently-empty box was written under a key
+ * `AddressValueSchema` strips: lost outright on a new record, and on an
+ * existing one silently discarded while the stale stored value survived. (A
+ * postal code nobody touched did survive an unrelated edit, because the write
+ * spread the whole stored object through; the issue's account of that half is
+ * corrected in `AddressField.postalCode.test.tsx`.) One name, on both sides:
+ * the contract's.
+ *
+ * IMPORTED rather than declared since objectui#4167. rc.6 publishes
+ * `AddressValue` under this exact name, and the local copy — whose own comment
+ * already claimed to be "the part names of `AddressSchema`" — declared five of
+ * the seven parts. `countryCode` and `formatted` were missing, which is
+ * objectstack#4115's failure class precisely: a canonical CLAIM over a narrower
+ * shape, believed by the next reader. The claim is now the code.
+ *
+ * `AddressField` still renders five inputs and {@link formatAddress} still
+ * composes five parts, and that is a deliberate split rather than an omission:
+ * `formatted` is a derived one-line rendering of the parts (what this module
+ * computes) and `countryCode` is the ISO pair for `country`, neither of which a
+ * human types into a part box. Binding the type does not publish them as
+ * inputs — it stops the type from asserting the platform cannot store them, and
+ * it means a write from the widget no longer looks type-clean while dropping a
+ * key the contract carries: the `{ ...address }` spread in `handleFieldChange`
+ * preserves both, and now says so.
+ *
+ * The declaration moved here (objectui#4037) so the display cell renderer and
+ * the widget share one definition; the SOURCE of that definition is the spec.
+ */
+export type { AddressValue };
+/**
+ * The shape written by builds up to and including 17.0.0-rc.1, whose postal
+ * code landed under `zipCode` (objectstack#5143). Read-time compatibility ONLY,
+ * and deliberately not part of {@link AddressValue}: authoring code must not be
+ * able to spell `zipCode`, and nothing here ever writes it back — the first
+ * edit of any part normalizes the record onto `postalCode` (see
+ * `AddressField`'s `handleFieldChange`). This is not a producer alias to be
+ * honoured forever; it exists to carry data THIS widget mis-wrote, and can go
+ * once no such data remains.
+ */
+export type LegacyAddressValue = AddressValue & {
+    zipCode?: string;
+};
+/** Postal code of a stored address, preferring the canonical key. */
+export declare function readPostalCode(addr: AddressValue): string | undefined;
+/**
+ * Formats a stored address as a single line: `Street, City, State ZIP, Country`.
+ *
+ * Ordering and separators are NOT invented here — they are the rule
+ * `AddressField` already applied in its readonly branch, and the sub-field set
+ * its inputs expose (street / city / state / postalCode / country). Missing
+ * parts are dropped rather than spaced over, so a street-only address is
+ * `"中策路 1 号"` and never `", , ,"`.
+ *
+ * Returns `''` when no part is usable — callers decide what an empty address
+ * looks like (an `EmptyValue` placeholder for the cell renderer), and a value
+ * carrying no recognized part at all is NOT silently blanked: see
+ * `AddressCellRenderer`, which falls back to JSON so unknown data stays visible.
+ */
+export declare function formatAddress(addr: AddressValue): string;

package/dist/widgets/file-size-guard.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The client-side `maxSize` guard shared by the file and image widgets
+ * (objectui#4141).
+ *
+ * Why this is shared rather than mirrored per widget: the guard is the only
+ * thing standing between a declared `maxSize` and a real `presigned → PUT →
+ * complete` round trip, and `paramToField` copies `maxSize` onto the field
+ * config for **every** param type regardless of which widget ends up rendering
+ * it. So a widget that re-derives the check drifts silently — the image param
+ * shipped receiving the constraint and never reading it, while the file param
+ * rejected the identical pick, and nothing failed until QA drove the two side by
+ * side. One exported function makes the difference visible: a widget either
+ * calls it or conspicuously does not.
+ *
+ * Both widgets deliberately share the `fields.file.exceedsMaxSize` key too. The
+ * sentence names a file and a limit and says nothing file-widget-specific, it is
+ * already translated in all 11 built-in locales, and a parallel `fields.image.*`
+ * twin would be the same sentence maintained twice — drifting the moment one
+ * translator rewords one of them.
+ */
+/**
+ * Minimal shape of the i18next `t` this module needs, matching the established
+ * `TranslateFn` pattern in `app-shell/src/providers/writeWarningToast`.
+ */
+export type TranslateFn = (key: string, options?: Record<string, unknown>) => string;
+/**
+ * The rejection message for a pick that exceeds `maxSize`, or `null` when the
+ * pick is within the limit — so a caller reads it as `if (err) reject`.
+ *
+ * A falsy `maxSize` (undeclared, or an explicit `0`) means **unrestricted**,
+ * preserving the `if (maxSize && …)` semantics the file widget has always
+ * applied: an undeclared limit must never turn into a 0-byte one.
+ *
+ * Takes `name` and `size` separately instead of a `File` because the image
+ * widget's crop path validates a re-encoded `Blob`, which carries no name of its
+ * own — that name comes from the cropper's output.
+ */
+export declare function maxSizeError(t: TranslateFn, pick: {
+    name: string;
+    size: number;
+}, maxSize: number | undefined): string | null;

package/dist/widgets/nativeDateValue.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+/**
+ * Stored value → `<input type="date">` value (`YYYY-MM-DD`).
+ *
+ * A leading `YYYY-MM-DD` is passed through VERBATIM rather than re-parsed: a
+ * date-only string is parsed as UTC midnight by `new Date()`, so reading local
+ * calendar components back out of it shifts the day by one everywhere west of
+ * Greenwich. `2026-06-17` must stay June 17th in every zone.
+ */
+export declare function toDateInputValue(value: unknown): string;
+/**
+ * Stored value → `<input type="datetime-local">` value (`YYYY-MM-DDTHH:mm`),
+ * expressed in the viewer's local wall clock — the same instant the detail
+ * page shows, so opening the editor never appears to move the time.
+ *
+ * A value that is ALREADY a zone-less local datetime is truncated to minutes
+ * in place instead of being round-tripped through `Date`, which would
+ * reinterpret it and then re-render it, twice risking an off-by-a-zone shift.
+ */
+export declare function toDateTimeInputValue(value: unknown): string;
+/**
+ * `<input type="datetime-local">` value → stored value (ISO-8601, UTC).
+ *
+ * The control hands us a zone-less local wall clock; `new Date()` reads that
+ * form as local time, which is the inverse of what `toDateTimeInputValue`
+ * wrote — the pair is what keeps read and write on one basis.
+ *
+ * An unparseable string is returned untouched rather than blanked: dropping a
+ * value the user can see in the box would be a data loss dressed up as a fix.
+ */
+export declare function fromDateTimeInputValue(value: string): string;

package/dist/widgets/toDomProps.d.ts

@@ -0,0 +1,111 @@
+import { DomProps as CoreDomProps } from '@object-ui/core';
+/**
+ * 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).
+ *
+ * ## Where the mechanism lives now, and why the key list stayed here
+ *
+ * objectui#4425 phase 2 promoted this whitelist to the SDUI widget contract
+ * generally, so the MECHANISM — filter by a declared key list plus the `aria-*`
+ * / `data-*` open families — moved to `@object-ui/core`
+ * (`utils/dom-props.ts`, `pickDomProps`), where every plugin package can reach
+ * it without depending on `@object-ui/fields` (the objectui#4409
+ * dependency-direction method: `plugin-chatbot` declares `@object-ui/core` and
+ * does not declare this package).
+ *
+ * The KEY LIST did not move, because it is not the same list. Measured on
+ * objectui#4431:
+ *
+ *  - `name` and `disabled` are here and NOT in the SDUI set: both are legal
+ *    only on form controls, which is what every widget in this package renders
+ *    and what `FieldWidgetComponentProps` declares. `name` on the `<div>` an
+ *    SDUI container widget renders is a leak — one of the 14 attributes #4431
+ *    closed — and two widgets here already hand-strip it when they spread onto
+ *    something that is not a control (`ObjectRefField`'s trigger,
+ *    `FileField`'s dropzone).
+ *  - `role` is in the SDUI set and NOT here: `SchemaRenderer` resolves it for
+ *    every node from `@objectstack/spec`'s `AriaPropsSchema`, while this
+ *    contract deliberately does not declare it (see "Deliberately NOT
+ *    forwarded" above).
+ *
+ * So: one mechanism, two declarations, each bound by the assertions below to
+ * the contract it executes. Not two judges.
+ */
+declare const DOM_PASS_THROUGH_KEYS: readonly ["id", "name", "autoFocus", "tabIndex", "onBlur", "onFocus", "onClick", "className", "disabled"];
+type DomPassThroughKey = (typeof DOM_PASS_THROUGH_KEYS)[number];
+/** The subset of `P` this helper forwards, with each key's declared type. */
+export type DomProps<P> = CoreDomProps<P, DomPassThroughKey>;
+/**
+ * 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 declare function toDomProps<P extends object>(props: P): DomProps<P>;
+export {};

package/dist/widgets/toHostGroupProps.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 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 props that make a group-labelled widget's rendered surface the thing its
+ * host label actually NAMES, on the surfaces that are not controls
+ * (objectui#3990).
+ *
+ * ## What it is for
+ *
+ * A widget declared `labelling: 'group'` (objectui#3961) is told by the form
+ * renderer: your label publishes an `id` and drops its `for`, so name yourself
+ * by IDREF. The renderer hands down exactly two facts that address the field as
+ * a WHOLE:
+ *
+ *  - `id` — the host's control id (`…-form-item`), the id the label's `for`
+ *    used to point at;
+ *  - `aria-labelledby` — the IDREF of that visible label.
+ *
+ * Every editable branch already consumes them inside its wider `toDomProps`
+ * spread. The branches that returned EARLY did not — a field-level
+ * `readonly: true`, or an option list with zero offered options — so the label
+ * published an id that no element in the document referenced. Measured on
+ * `origin/main`, one field per row, reading the host label against the DOM:
+ *
+ * ```
+ * multiselect  readonly+value   consumers=0  byLabelText=0  namedByRole=[]
+ * multiselect  readonly+empty   consumers=0  byLabelText=0  namedByRole=[]
+ * multiselect  zeroOptions      consumers=0  byLabelText=0  namedByRole=[]
+ * multiselect  editable         consumers=1  byLabelText=1  namedByRole=[group:1]
+ * ```
+ *
+ * All seven group-labelled types measured the same, in every readonly state.
+ * This is quieter than the dangling `for` #3961 replaced: a `for` that resolves
+ * to nothing can at least be swept for, while "a label published an id and
+ * nobody consumed it" looks like healthy markup.
+ *
+ * ## Why this narrow pair, and not the whole `toDomProps` result
+ *
+ * Everything else in the DOM pass-through addresses a CONTROL, and a readonly
+ * display has none: `aria-describedby` / `aria-required` are announced when
+ * focus lands on something focusable, `disabled` / `tabIndex` / the focus
+ * handlers only mean something on an interactive element, and `name` is
+ * DOM-legal on form controls only — on a `div` it is exactly the leak
+ * objectui#3291 sweeps for. Spreading the full result would also put the host's
+ * `className` on top of the widget's own, because the widgets whose readonly
+ * surface is a placeholder or a plain container (`EmptyValue`, `FileField`,
+ * `AddressField`) keep `className` inside `props`.
+ *
+ * ## Why `role` travels with the two keys
+ *
+ * `aria-labelledby` on a role-less `div` / `span` names NOTHING — `generic`
+ * prohibits an author name — so the pair is inert without a role that supports
+ * naming. `group` is the one that fits a readonly surface: it names a set of
+ * values (chips, checked labels, stars, file names, a formatted address)
+ * without promising the interactivity `textbox` or `radiogroup` would. It is
+ * deliberately NOT the role the same widget answers with while editable:
+ * `RadioField`'s readonly branch renders the chosen label as text with no radios
+ * left in it, and `FileField`'s renders file names with no dropzone button.
+ *
+ * The role is emitted ONLY when a host actually named the field, mirroring
+ * every editable branch's `isLabelledGroup` test: standalone rendering (the
+ * grid's inline cell editor, a bare SDUI node) hands down neither key, so every
+ * value here is `undefined`, React emits no attribute, and that markup stays
+ * byte-identical to what it was.
+ */
+export interface HostGroupProps {
+    /** The host's control id — the id its label would have pointed `for` at. */
+    id?: string;
+    /** IDREF of the host's visible label. */
+    'aria-labelledby'?: string;
+    /** `'group'` when — and only when — a host named this surface. */
+    role?: 'group';
+}
+/**
+ * Read the two whole-field keys out of a widget's leftover props, plus the role
+ * that makes them mean something. See {@link HostGroupProps}.
+ *
+ * Routed through {@link toDomProps} rather than reading `props` directly so the
+ * pair keeps ONE gate: those keys reach an element only if the DOM pass-through
+ * whitelist still forwards them, and its two compile-time assertions bind that
+ * whitelist to the props contract in both directions.
+ */
+export declare function toHostGroupProps(props: {
+    id?: string;
+    'aria-labelledby'?: string;
+}): HostGroupProps;

package/dist/widgets/types.d.ts

@@ -1,5 +1,47 @@
 import { AriaAttributes, FocusEventHandler, MouseEventHandler } from 'react';
 import { 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.
  *
@@ -13,13 +55,27 @@ import { 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)
  *
@@ -39,37 +95,66 @@ import { 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> = {
     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
      * widgets ignore it.
      */
     onUploadingChange?: (uploading: boolean) => void;
-    /**
-     * 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
@@ -93,9 +178,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;
     /**
@@ -114,15 +217,7 @@ export type FieldWidgetComponentProps<T = any> = {
      * user had typed. Also declarable on the field metadata.
      */
     onCreateNew?: (searchQuery: string) => void;
-    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 & {
+} & 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/dist/widgets/useRecordQuery.d.ts

@@ -46,8 +46,14 @@ export interface UseRecordQueryOptions {
      * `$filter` — already merged by the caller (base `lookup_filters`, dependent
      * lookup chain, candidate hygiene like `banned != true`, …). Compared by
      * value, so a referentially-new-but-equal object each render will not loop.
+     *
+     * Either the `QueryParams.$filter` record form or a lowered ObjectQL AST node
+     * (an array), since the picker's merge now produces both (#3831). Typed
+     * `unknown` rather than `Record< string, any >` so an array cannot slip
+     * through a type that silently accepts it; emptiness is decided by
+     * {@link hasFilter}, not by `Object.keys`.
      */
-    filter?: Record<string, any>;
+    filter?: unknown;
     /** `$expand` — related entities to include (e.g. `['primary_business_unit_id']`). */
     expand?: string[];
     /** `$searchFields` — narrow the server searchable set (ADR-0061). */

package/dist/withFieldCarrier.d.ts

@@ -0,0 +1,56 @@
+import { default as React } from 'react';
+/**
+ * Adapt `SchemaRenderer`'s SDUI carrier onto the field-widget contract —
+ * objectui#3233, the producer-side half of retiring `schema` from
+ * {@link import('./widgets/types').FieldWidgetComponentProps}.
+ *
+ * ## Why this exists
+ *
+ * Two kinds of host render a registered field widget, and they name the
+ * metadata differently *for good reason*:
+ *
+ *  - the **form renderer** (`renderFieldComponent` in
+ *    `@object-ui/components`), the inline-edit hosts (`FieldEditWidget`) and
+ *    the action dialogs pass **`field`** — the field metadata they already
+ *    hold;
+ *  - **`SchemaRenderer`** (`@object-ui/react`) passes **`schema`** — the
+ *    authored node. That key is the UNIVERSAL SDUI contract *every* registered
+ *    component receives (`element:*`, `page:*`, `object-grid`,
+ *    `ReportRenderer` …). It is not being retired and must not be: it is what
+ *    the renderer means by "the node you were rendered from".
+ *
+ * What WAS wrong is that both keys reached the widget, so ~30 widgets resolved
+ * their config as `field || schema` — one concept under two spellings, a second
+ * de-facto contract on the widget side (AGENTS.md #0.1) and precisely the shape
+ * that lets an AI-written widget pick one spelling and appear to work under one
+ * host while reading `undefined` under the other.
+ *
+ * The translation belongs at the seam, exactly once: here. Downstream `field`
+ * is the only carrier, and a widget reading `props.schema` no longer compiles.
+ *
+ * ## Guarantee
+ *
+ * Payload-preserving by construction: the node is forwarded **by reference**,
+ * so a widget's `field` is the very object it used to read through `schema`.
+ * `field` wins when a host supplies both (the form path always does, and it
+ * holds the resolved metadata rather than the raw node).
+ *
+ * `schema` is *consumed* here rather than forwarded — with the key gone from
+ * the contract, passing it on would only reach the DOM as a stray attribute
+ * through a widget's `...props` spread.
+ *
+ * ## For widget authors outside this repo
+ *
+ * Registering a widget raw means `SchemaRenderer` hands it `schema` and no
+ * `field`. Wrap it once at registration and the widget only ever implements
+ * `FieldWidgetComponentProps`:
+ *
+ * ```tsx
+ * import { withFieldCarrier } from '@object-ui/fields';
+ *
+ * ComponentRegistry.register('color', withFieldCarrier(ColorPickerField), {
+ *   namespace: 'field',
+ * });
+ * ```
+ */
+export declare function withFieldCarrier<P extends object>(FieldWidget: React.ComponentType<P>): React.FC<Record<string, any>>;