@object-ui/fields 17.2.0 → 17.5.0

package/src/widgets/toHostGroupProps.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 { toDomProps } from './toDomProps';
+
+/**
+ * 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 function toHostGroupProps(props: {
+  id?: string;
+  'aria-labelledby'?: string;
+}): HostGroupProps {
+  const { id, 'aria-labelledby': labelledBy } = toDomProps(props);
+  return {
+    id,
+    'aria-labelledby': labelledBy,
+    ...(labelledBy != null ? { role: 'group' as const } : null),
+  };
+}

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

@@ -6,14 +6,13 @@ import { createSafeTranslation } from '@object-ui/i18n';
 
 const FIELD_DEFAULTS: Record<string, string> = {
   'common.selectOption': 'Select an option',
-  'common.select': 'Select...',
-  'common.search': 'Search',
-  'common.loading': 'Loading...',
+  'common.select': 'Select…',
+  'common.loading': 'Loading…',
   'common.noResults': 'No results found',
   'common.cancel': 'Cancel',
   'common.confirm': 'Confirm',
   'table.selected': '{{count}} selected',
-  'table.search': 'Search...',
+  'table.search': 'Search…',
   'lookup.loading': 'Loading…',
   'lookup.noOptions': 'No options found',
   'lookup.noRecords': 'No records found',
@@ -39,6 +38,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 +74,43 @@ 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}}',
+  // The fullscreen long-text dialog's copy (objectui#3404) is NOT declared
+  // here any more. It moved with the implementation: `FullscreenFieldEditor` is
+  // a thin wrapper over `FullscreenEditor` in `@object-ui/components`
+  // (objectui#3398), and that primitive carries its own `createSafeTranslation`
+  // defaults for the same `form.fullscreen.*` / `common.cancel` keys — still
+  // the built-in branch's keys, still byte-identical English, so provider-less
+  // rendering is unchanged and the ten locale packs need no edit. Leaving the
+  // entries here would have re-created in the defaults map exactly the
+  // duplication #3398 removed from the components, and this map's own
+  // discipline is that a default is declared where it is read.
+  //
+  // `common.cancel` stays above: `RecordPickerDialog` and `PeoplePicker` read
+  // it independently of anything fullscreen.
   // objectui#2600 B5 — capability picker scope group headers.
   'capability.group.platform': 'Platform',
   'capability.group.org': 'Organization',

package/src/widgets/useRecordQuery.ts

@@ -56,8 +56,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). */
@@ -97,6 +103,22 @@ export interface UseRecordQueryResult {
   refetch: () => void;
 }
 
+/**
+ * Is this filter source worth sending as `$filter` at all?
+ *
+ * Array-aware on purpose. The picker's merge yields either the
+ * `QueryParams.$filter` record form or a lowered ObjectQL AST node (#3831), and
+ * `Object.keys` on an array returns its INDICES — so the record-only test read
+ * `['0','1','2']` for an AST node and was right only by accident. An empty array
+ * is "no filter" for the same reason an empty object is.
+ */
+function hasFilter(filter: unknown): boolean {
+  if (filter === null || filter === undefined) return false;
+  if (Array.isArray(filter)) return filter.length > 0;
+  if (typeof filter !== 'object') return false;
+  return Object.keys(filter as object).length > 0;
+}
+
 export function useRecordQuery(options: UseRecordQueryOptions): UseRecordQueryResult {
   const {
     dataSource,
@@ -123,7 +145,7 @@ export function useRecordQuery(options: UseRecordQueryOptions): UseRecordQueryRe
   // Stable signatures for object/array inputs so the fetch effect keys on their
   // *value*, not a fresh reference every render.
   const filterSignature = useMemo(
-    () => (filter && Object.keys(filter).length ? JSON.stringify(filter) : ''),
+    () => (hasFilter(filter) ? JSON.stringify(filter) : ''),
     [filter],
   );
   const expandSignature = useMemo(() => (expand?.length ? expand.join(',') : ''), [expand]);
@@ -150,7 +172,12 @@ export function useRecordQuery(options: UseRecordQueryOptions): UseRecordQueryRe
         if (searchTerm && searchTerm.trim()) params.$search = searchTerm.trim();
         if (searchFields && searchFields.length > 0) params.$searchFields = searchFields;
         if (sortArg) params.$orderby = { [sortArg.field]: sortArg.direction };
-        if (filter && Object.keys(filter).length > 0) params.$filter = filter;
+        // `QueryParams.$filter` is declared `Record< string, any >`, which the
+        // AST-array form does not describe — the cast is at this ONE assignment
+        // rather than widening a shared type that several other producers
+        // (plugin-list's `buildEffectiveFilter`, plugin-view's ObjectView)
+        // already feed arrays through.
+        if (hasFilter(filter)) params.$filter = filter as Record<string, any>;
         if (expand && expand.length > 0) params.$expand = expand;
 
         const result = await dataSource.find(objectName, params);

package/src/withFieldCarrier.tsx

@@ -0,0 +1,75 @@
+/**
+ * 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 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 function withFieldCarrier<P extends object>(
+  FieldWidget: React.ComponentType<P>,
+): React.FC<Record<string, any>> {
+  const FieldCarrierAdapter: React.FC<Record<string, any>> = ({ schema, field, ...props }) => (
+    <FieldWidget {...(props as unknown as P)} field={field ?? schema} />
+  );
+  FieldCarrierAdapter.displayName = `FieldCarrier(${
+    (FieldWidget as any).displayName || (FieldWidget as any).name || 'Component'
+  })`;
+  return FieldCarrierAdapter;
+}

package/dist/FieldEditWidget.test.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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.
- */
-export {};

package/dist/__tests__/resolveFieldCurrency.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/__tests__/spec-symbol-batch7.test.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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.
- */
-export {};

package/dist/__tests__/widget-props-contract.test.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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.
- */
-export {};

package/dist/coerce-safe-value.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/complex-widgets.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/datetime-widgets.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/field-type-coverage.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/widgets/GridField.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/widgets/ImageLightbox.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/widgets/LookupField.dependsOn.test.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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.
- */
-export {};

package/dist/widgets/LookupField.hydration.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/widgets/LookupField.idField.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/widgets/PeoplePicker.test.d.ts

@@ -1,8 +0,0 @@
-/**
- * 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.
- */
-export {};