@object-ui/fields 17.6.0 → 18.0.0

package/dist/widgets/numberBadInput.d.ts

@@ -0,0 +1,135 @@
+import { default as React } from 'react';
+import { TranslateFn } from './file-size-guard.js';
+/**
+ * ONE reading of "this box is showing text the browser cannot read", shared by
+ * every `type="number"` widget in this package (objectui#6780).
+ *
+ * ## The defect this closes
+ *
+ * A `type="number"` box can DISPLAY one thing and hold another, with nothing
+ * said. Measured on Chromium 141.0.7390.37 (Playwright 1.62.1), typing `1e`
+ * into an empty number input:
+ *
+ * ```
+ * .value            = ""            <- what every widget here reads
+ * validity.badInput = true          <- what the browser actually thinks
+ * pixels vs an untouched box: DIFFERENT   <- the box IS still showing `1e`
+ * ```
+ *
+ * So the widget emitted `null`, `aria-invalid` stayed `"false"`, and no
+ * diagnostic was drawn: objectui#6716's silent-refusal class, on a money field.
+ *
+ * ## Why `validity.badInput` and not a regex of our own
+ *
+ * It is the PLATFORM's own predicate — the browser stating, in its own words,
+ * whether it can read the text — rather than a second renderer-side dialect of
+ * "what a number is" (AGENTS.md #0.1).
+ *
+ * ⚠️ objectui#6765 recorded `badInput` as "the ONE signal happy-dom and Chromium
+ * agree on". objectui#6780 measured that and NARROWED it, because the
+ * difference decides which strings a unit test may drive: in Chromium
+ * `badInput` is never true for a programmatic `.value` write (it reports that
+ * the UA cannot read the USER's input), so on the only route a happy-dom test
+ * has, the two engines agree on nothing. The agreement this guard rests on is
+ * between happy-dom's programmatic verdict and Chromium's TYPED verdict, and it
+ * holds for a measured subset — four strings agree on "bad", seven agree on
+ * "fine", and eight disagree. The full matrix, and the lists the tests are
+ * allowed to use, are in `__tests__/numberInputBrowserReadings.ts`.
+ *
+ * ⭐ And it is NOT objectui#6715's anchored guard wearing a different hat.
+ * That one was measured to be a provable no-op here — it rejects only strings
+ * this test environment fabricates. This one fires on keyboard-reachable
+ * states, MEASURED in Chromium by typing each key by key into an empty box:
+ *
+ * ```
+ * typed "1e"  "1e-"  "1e+"  "-"  "."  "+"  "-."  "e"  "5e"   -> badInput TRUE
+ * typed "1."  "1e5"  "1.2.3"  "0x10"  "12abc"                -> badInput false
+ * ```
+ *
+ * and never on anything the browser can actually emit: `12`, `1.23`, `010`,
+ * `15`, `1`, `12.345` all read `badInput === false`.
+ *
+ * ## ⛔ What this deliberately does NOT do: change what is emitted
+ *
+ * objectui#6716's shape REFUSES (its `onChange` never fires and the prior value
+ * stands). Here that would destroy the very text the diagnostic points at, so
+ * these widgets keep emitting exactly what they emitted before and only stop
+ * being silent about it. MEASURED, in both halves:
+ *
+ *  - Chromium: after typing `1e`, a script write of `.value` clears the raw
+ *    display and flips `badInput` back to `false` — even writing `""`.
+ *  - React 19.2.8's own `updateInput` (`react-dom/cjs/react-dom-client.
+ *    development.js`) restores a number input with
+ *    `if ((0 === value && "" === element.value) || element.value != value)
+ *    element.value = "" + getToStringValue(value);`
+ *
+ * So for a box that already held `5`, refusing leaves `props.value` at `5`,
+ * `element.value` at `""`, and React writes `"5"` back — wiping the `5e` the
+ * user is looking at and the message is about. Emitting keeps `props.value` at
+ * `""`, the write is skipped, and the raw text survives, which is what
+ * objectui#6716 requires of a refusal ("keeps the refused text in the box, so
+ * the message has something to point at").
+ *
+ * ⚠️ The text itself is NOT quotable. The browser displays it but never exposes
+ * it — `.value` is `""` and there is no other channel — so unlike
+ * objectui#6715's residue message this one cannot name what was typed. It
+ * points at the box instead.
+ */
+/**
+ * The one sentence, in objectui#6716's `Not saved: …` shape, read from the
+ * package's locale channel (objectui#8148).
+ *
+ * objectui#6755 ruled that a widget's OWN refusal sentence goes through
+ * `useFieldTranslation` + `FIELD_DEFAULTS`; `320374d2a` applied it to
+ * `LocationField`'s residue arm. This was the FIFTH such sentence and the only
+ * SHARED one — the four already keyed are each one widget's, while this literal
+ * served `NumberField`, `CurrencyField`, `PercentField` and both of
+ * `GeolocationField`'s boxes through {@link useBadInputRefusal}. Its sharpest
+ * consequence: `GeolocationField` sits beside `LocationField`, whose refusals
+ * are all keyed, so two adjacent coordinate widgets refused bad input in two
+ * different languages on one form.
+ *
+ * ⭐ `example` stays a HOLE rather than being keyed per widget, and that is
+ * what keeps the decimal numerals out of every pack. Five different values
+ * reach this one sentence — `1234`, `1234.56`, `12.5`, `30.2741`, `120.1551` —
+ * so a per-widget key would need five keys times ten packs, and each pack would
+ * then hold a decimal numeral it could legitimately re-punctuate. A pack that
+ * wrote `1234,56` would read as the `latitude, longitude` PAIR the adjacent
+ * widget asks for; the hole is filled by the widget in ASCII and no pack ever
+ * spells a digit.
+ *
+ * The English value is byte-identical to the literal it replaces, so English
+ * and provider-less rendering are unchanged.
+ */
+export declare function badInputMessage(t: TranslateFn, example: string): string;
+/**
+ * The widget's OWN refusal state, and the reader that fills it.
+ *
+ * Named `refusal`, never `error`: `error` is the published validation slot on
+ * the widget contract (objectui#3222) with exactly one author, the form
+ * renderer. This is the widget's own reading, which no host can produce — the
+ * same two-name split `LocationField` uses (objectui#6716).
+ *
+ * `readBadInput` is called from BOTH arms, because neither alone sees every
+ * route (MEASURED in Chromium):
+ *
+ *  - TYPED `1e` into an empty box fires 2 `input` events — the `e` keystroke
+ *    moves `.value` from `"1"` to `""`, so React does deliver an `onChange`.
+ *  - PASTED `1e` into an empty box fires 1 `input` event, but `.value` never
+ *    leaves `""`; React's own input-value tracking suppresses the synthetic
+ *    `onChange`, so the CHANGE arm never runs. Blur fires, and `badInput` is
+ *    still `true` at blur time — which is the whole reason for the blur arm.
+ */
+export declare function useBadInputRefusal(example: string): {
+    refusal: string | null;
+    readBadInput: (target: HTMLInputElement | null | undefined) => boolean;
+};
+/**
+ * The drawn diagnostic — objectui#6716's exact markup, in one spelling so the
+ * four widgets of this class cannot drift apart.
+ */
+export declare function BadInputMessage({ refusal }: {
+    refusal: string | null;
+}): React.JSX.Element | null;
+/** The class that marks the refused control, in one spelling. */
+export declare const BAD_INPUT_BORDER = "border-red-500 focus-visible:ring-red-500";

package/dist/widgets/objectRefLabel.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+/**
+ * An object's name as the `object-ref` picker spells it, `Label (name)`, or the
+ * bare name when the object has no label (objectui#12613). `ObjectRefField`
+ * labels each option with it, and the console's read face for the field
+ * (`@object-ui/app-shell`'s widget reference cells) uses it for its tooltip, so
+ * the two faces spell an object one way. Published from the package barrel for
+ * that reader. No React here.
+ */
+export declare function objectRefOptionLabel(name: string, label: string | undefined): string;

package/dist/widgets/personDisplay.d.ts

@@ -13,8 +13,22 @@
  */
 /** Resolve a possibly-dotted path (e.g. `primary_business_unit_id.name`) against a record. */
 export declare function resolvePath(record: any, path: string): any;
-/** Best display name for a person record, tolerating expanded / raw shapes. */
-export declare function getPersonName(record: any, nameField?: string): string;
+/**
+ * The fields a person's display name is read from, in order: the configured
+ * display field, then `name`, `username`, `label`. A caller that gates the name
+ * by field-level security filters THIS list and hands the rest to
+ * {@link getPersonName} (objectui#10535): a denied rung is skipped, so the name
+ * falls through to the next readable one — the row a stripping backend serves
+ * reads the same.
+ */
+export declare function getPersonNameFields(nameField?: string): string[];
+/**
+ * Best display name for a person record, tolerating expanded / raw shapes: the
+ * first field of the name ladder the record holds a value for. `nameField` is
+ * the configured display field, whose ladder is {@link getPersonNameFields}, or
+ * the ladder itself, already filtered to the fields the viewer may read.
+ */
+export declare function getPersonName(record: any, nameField?: string | readonly string[]): string;
 /**
  * Up-to-2-char initials for the avatar fallback.
  * - "John Doe" → "JD"; "John" → "JO"
@@ -23,8 +37,12 @@ export declare function getPersonName(record: any, nameField?: string): string;
 export declare function getPersonInitials(name: string): string;
 /** Secondary line: resolve each field path, drop empties, join with " · ". */
 export declare function getPersonSubtitle(record: any, fields?: string[]): string;
-/** Avatar image URL (defaults to `sys_user.image`); undefined when absent. */
-export declare function getPersonAvatarUrl(record: any, avatarField?: string): string | undefined;
+/**
+ * Avatar image URL (defaults to `sys_user.image`); undefined when absent, and
+ * when `avatarField` is `null` — no avatar field to read, e.g. one field-level
+ * security withholds (objectui#10433).
+ */
+export declare function getPersonAvatarUrl(record: any, avatarField?: string | null): string | undefined;
 /** Record id, tolerating `id` / `_id` / a custom id field. */
 export declare function getPersonId(record: any, idField?: string): any;
 /**

package/dist/widgets/recipientKinds.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 recipient kinds a `recipient-picker` field stores, and where each kind's
+ * candidates and labels come from (objectui#12613).
+ *
+ * ONE table, two readers: `RecipientPickerField` (the edit widget) lists a
+ * kind's candidates from it, and the console's read face for the field
+ * (`@object-ui/app-shell`'s widget reference cells) names a stored recipient
+ * from it. They lived inside the widget until the face needed the same answer;
+ * a second copy beside the face is the drift this module exists to prevent, so
+ * a kind added here reaches both faces at once. Published from the package
+ * barrel for that reader. The picker's candidate query is not shared: it stops
+ * at 500 rows by name, and the face reads stored ids by exact id instead.
+ *
+ * No React here.
+ */
+export interface RecipientMapping {
+    object: string;
+    /** Which record field to persist into recipient_id. */
+    storeField: 'id' | 'name';
+    /** Candidate display-label fields, in preference order. */
+    labelFields: string[];
+    /**
+     * i18n key for the "choose one" placeholder. Keyed per type rather than
+     * interpolating the enum value into an English sentence — "Select a
+     * business unit" and "选择业务单元" share no structure (objectstack#3821).
+     */
+    placeholderKey: string;
+}
+/**
+ * The recipient kinds whose candidates are RECORDS of one directory object,
+ * stored by the record field the evaluator matches on:
+ *
+ *   user                  → sys_user, store `id`
+ *   team                  → sys_team, store `id`
+ *   business_unit         → sys_business_unit, store `id`
+ *   unit_and_subordinates → sys_business_unit, store `id`
+ */
+export declare const RECIPIENT_RECORD_KINDS: Readonly<Record<string, RecipientMapping>>;
+/** A recipient kind whose candidates are catalog items of one metadata type. */
+export interface RegistryRecipientMapping {
+    /** The metadata type listed — the registry's `GET /api/v1/meta/<type>`. */
+    type: string;
+    /** Catalog items are referenced by machine name (ADR-0131 D4). */
+    storeField: 'name';
+    /** Candidate display-label keys, in preference order. */
+    labelFields: string[];
+    /** i18n key for the "choose one" placeholder (see {@link RecipientMapping}). */
+    placeholderKey: string;
+}
+/**
+ * The recipient kinds whose candidates come from the registry (objectui#7611).
+ *
+ * ADR-0131 D3 gives positions one home, the environment registry, and D7 says
+ * a picker LISTS that registry: one source, with no second list of
+ * `sys_position` rows merged in. The read goes through the console's metadata
+ * store (`useMetadata().ensureType`), the same reader that serves apps and
+ * objects, so the list is fetched once per session and shared with every
+ * other registry consumer.
+ */
+export declare const RECIPIENT_REGISTRY_KINDS: Readonly<Record<string, RegistryRecipientMapping>>;
+/**
+ * The RECORD-RELATIVE recipient kind (maintainer ruling objectstack#14103,
+ * executor objectstack#15072). It is deliberately absent from
+ * `RECIPIENT_RECORD_KINDS`: there is no target object to query and no record id to
+ * store. `recipient_id` holds the NAME of a user-valued column on the SHARED
+ * object, and the recipients are whoever that column names on each matched
+ * record — so this mode reads the object chosen in the sibling `object_name`
+ * field (the same dependency the `filter-condition` widget already reads) and
+ * offers that object's user-valued fields.
+ */
+export declare const FIELD_RECIPIENT_TYPE = "field";
+/**
+ * The display label of one candidate: the first non-empty member of the
+ * kind's `labelFields`, then the record id. The picker labels its options with
+ * it and the read cell names a stored recipient with it, so a recipient reads
+ * the same in the list and in the open picker.
+ */
+export declare function recipientCandidateLabel(labelFields: readonly string[] | undefined, row: unknown): string;

package/dist/widgets/richTextDisplay.d.ts

@@ -12,6 +12,10 @@ import { CellRendererProps } from '../index.js';
  * pipeline drops all of it; see {@link HtmlCellRenderer}, which is where that
  * type belongs. Loosening this pipeline to pass raw HTML through would have
  * "fixed" one type by moving every `markdown` cell's trust boundary.
+ *
+ * What the cell holds is decided by {@link richTextSource} (objectui#8580):
+ * `[]` is the No-value affordance, never a childless container, and an
+ * object is the text the string class prints for it, never `[object Object]`.
  */
 export declare function MarkdownCellRenderer({ value }: CellRendererProps): React.ReactElement;
 /**
@@ -27,6 +31,14 @@ export declare function MarkdownCellRenderer({ value }: CellRendererProps): Reac
  * emits — headings, paragraphs, emphasis, lists, links, quotes all survive, so
  * routing `richtext` here restores the content rather than trading a blank cell
  * for a mangled one.
+ *
+ * What the cell holds is decided by {@link richTextSource} (objectui#8580):
+ * `[]` is the No-value affordance, never a childless `prose` container, and
+ * an object is the text the string class prints for it. The populated branch
+ * stays on {@link sanitizeHtml}: a stored string comes back from
+ * `richTextSource` verbatim, so the bytes that reach the sanitiser are the
+ * bytes that always did — pinned byte-for-byte in
+ * `__tests__/cellRenderers.childlessContainer-8580.test.tsx`.
  */
 export declare function HtmlCellRenderer({ value }: CellRendererProps): React.ReactElement;
 /**
@@ -51,22 +63,29 @@ export declare const RICH_TEXT_CELL_RENDERERS: {
 /** The rich-content field types, i.e. the keys of {@link RICH_TEXT_CELL_RENDERERS}. */
 export type RichTextFieldType = keyof typeof RICH_TEXT_CELL_RENDERERS;
 /**
- * The SYNTAX a rich-content type stores, derived from the renderer that type
- * resolves to rather than declared a second time.
+ * The same three types as a RUNTIME list, DERIVED from THE table rather than
+ * spelled a second time — the type-level {@link RichTextFieldType} cannot be
+ * enumerated at runtime, and a hand-written array beside it would be exactly
+ * the shape this export exists to retire.
+ *
+ * ## Why this export exists
  *
- * This is what `RichTextField`'s editor header names ("Format: markdown"), and
- * deriving it from {@link RICH_TEXT_CELL_RENDERERS} is the point: the header
- * used to be computed as `field.format || 'markdown'`, and since `format` is
- * declared on no rich-content field type (only on `date`/`datetime`/`time`/
- * `phone`/`auto_number`), it read `undefined` for every real field and labelled
- * an `html` field "Format: markdown" — a label pointing at a pipeline the value
- * does not go through. Derived, the label cannot disagree with the renderer.
+ * objectui#4831 asked, in its own body, whether the hand-written type lists
+ * that keep omitting the third of this widget's three registry keys should
+ * become "every type that resolves to the long-text widget". It was answered
+ * by adding one literal, and the omission recurred (objectui#4250,
+ * objectui#8438). This is that question answered in the other direction: a
+ * consumer that spreads this list cannot omit a key, because it never names
+ * one. Adding a fourth key to {@link RICH_TEXT_CELL_RENDERERS} extends every
+ * such consumer in the same commit that adds the key.
  *
- * `undefined` for a type with no pipeline, rather than a guessed default: the
- * caller has to say what it does with "not a rich-content type" instead of
- * silently getting the markdown answer, which is the bug this replaces.
+ * ⚠️ It is NOT a general "long text" list and must not be used as one:
+ * `textarea` renders a `<Textarea>` too and is deliberately absent, because it
+ * is a different widget with its own registry key and its own metadata face.
+ * The invariant this list states is narrower and exact — *these are the keys
+ * `RichTextField` serves*.
  */
-export declare function richTextSyntax(fieldType: string): 'markdown' | 'html' | undefined;
+export declare const RICH_TEXT_FIELD_TYPES: readonly RichTextFieldType[];
 /**
  * The display pipeline a field type reads through, or `undefined` when the
  * type is not one of the three rich-content types.

package/dist/widgets/searchOffer.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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 declare function objectResolvesSearch(objectSchema: unknown): boolean | undefined;

package/dist/widgets/toDomProps.d.ts

@@ -83,9 +83,31 @@ import { DomProps as CoreDomProps } from '@object-ui/core';
  * 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>;
+/**
+ * The keys this helper forwards.
+ *
+ * Exported so the SIBLING executor — `toHostProps`, which carries the declared
+ * NON-DOM keys (`f08bcd9af`) — can subtract this set from the contract and
+ * assert that the two together cover every declared key exactly once. Without
+ * that subtraction there is no way to state "these keys are handled elsewhere"
+ * as a compile-time fact rather than as a comment.
+ */
+export type DomPassThroughKey = (typeof DOM_PASS_THROUGH_KEYS)[number];
+/**
+ * The subset of `P` this helper forwards, with each key's declared type.
+ *
+ * Not {@link FieldWidgetDomProps}: that is the contract's DOM block, the
+ * non-generic set of keys a widget may receive; this is the generic RESULT
+ * type of {@link toDomProps}, whatever `P` it is handed narrowed to this
+ * helper's key set.
+ *
+ * Not `DomProps`: `@object-ui/core` publishes that name for the general
+ * mechanism, whose default key set forwards `role` where this one forwards
+ * `name` and `disabled`. One exported name stood for both key sets until this
+ * declaration was renamed, the way `@object-ui/components` names its own
+ * specialisation `FormControlDomProps` (objectui#6349, batch 11).
+ */
+export type FieldDomProps<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
@@ -107,5 +129,5 @@ export type DomProps<P> = CoreDomProps<P, DomPassThroughKey>;
  * `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 declare function toDomProps<P extends object>(props: P): FieldDomProps<P>;
 export {};

package/dist/widgets/toHostGroupProps.d.ts

@@ -187,3 +187,56 @@ export declare function toHostGroupProps(props: {
     'aria-labelledby'?: string;
     'aria-describedby'?: string;
 }, surface: HostGroupSurface): HostGroupProps;
+/**
+ * The host keys a LABELABLE surface may consume — the `labelling: 'control'`
+ * counterpart of {@link HostGroupProps} (objectui#8803).
+ *
+ * ## Why a second, smaller bag instead of reusing the group one
+ *
+ * A widget declared `'control'` is told nothing by the host: its label emits a
+ * plain `for` and expects to reach a labelable element on its own. Every
+ * editable branch answers that by spreading `toDomProps` onto the control it
+ * renders. The branches that return EARLY answer it with nothing — and for the
+ * single `SelectField` that is the zero-option box, where the `…-form-item` id
+ * reached no element at all and the label's `for` DANGLED.
+ *
+ * What such a surface needs is therefore the exact complement of the group
+ * bag:
+ *
+ *  - `id` — yes. It is the id the `for` points at, and landing it is the whole
+ *    repair;
+ *  - `aria-describedby` — yes, for the objectui#4005 reason, unchanged by the
+ *    surface being labelable: the field renders no input in this state, so
+ *    this box is the only element the visible help text can be announced on;
+ *  - `aria-labelledby` — ⛔ NO. The `for` already names this element. Adding an
+ *    IDREF beside it is the second naming channel objectui#3978 removed;
+ *  - `role` — ⛔ NO. A labelable element's own semantics are what make the name
+ *    land; a synthetic role on top is the category error objectui#3991 named.
+ *
+ * `aria-invalid` / `aria-required` / `name` stay off for the reasons spelled
+ * out at length on {@link HostGroupProps}: control-channel state on a surface
+ * nobody can edit, and the DOM leak objectui#3291 sweeps for. A closed type,
+ * not an open props tail, for that same reason.
+ */
+export interface HostControlProps {
+    /** The host's control id — the id its label's `for` points at. */
+    id?: string;
+    /** IDREF of the host's visible help text. */
+    'aria-describedby'?: string;
+}
+/**
+ * Read the two whole-field keys a labelable replacement surface may carry. See
+ * {@link HostControlProps}.
+ *
+ * Routed through {@link toDomProps} for the same reason {@link toHostGroupProps}
+ * is: the keys keep ONE gate, and its compile-time assertions bind that
+ * whitelist to the props contract in both directions.
+ *
+ * Standalone rendering (the grid's inline cell editor, an action param dialog,
+ * a bare SDUI node) hands down neither key, so both values are `undefined`,
+ * React emits no attribute, and that markup stays byte-identical.
+ */
+export declare function toHostControlProps(props: {
+    id?: string;
+    'aria-describedby'?: string;
+}): HostControlProps;

package/dist/widgets/toHostProps.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 RUNTIME EXECUTOR of the NON-DOM half of {@link FieldWidgetComponentProps}
+ * (`f08bcd9af`) — the sibling of `toDomProps`, and deliberately a SEPARATE
+ * function rather than more entries in that whitelist.
+ *
+ * ## The defect
+ *
+ * objectui#6909 / #7009 closed the DOM half at `FieldEditWidget`: the factory
+ * hands the widget `toDomProps(props)`, so `id` / `name` / `tabIndex` /
+ * `aria-*` / `data-*` and friends finally arrive. The contract also declares a
+ * "Host plumbing" block plus two controlled-input keys the factory neither owns
+ * nor routes to the DOM, and NOTHING carried those. A host could pass any of
+ * them with no type error and the widget never received it — this package's own
+ * first-class defect class, named in `toDomProps.ts`: "a key that type-checks,
+ * reads as supported, and silently never reaches the element" (objectui#3290's
+ * `aria-required`, objectui#3222's validation slot).
+ *
+ * Measured on `main` at `71d83a6b1`, the live victim was `error`:
+ * `InlineFieldInput` (`@object-ui/plugin-detail`, since PR #7109) already
+ * passes `error={error}` to `FieldEditWidget`, and the factory dropped it on
+ * the floor — so a control that had failed validation never reported
+ * `aria-invalid` and a screen-reader user was never told. The kanban
+ * `RequiredFieldsDialog` had the same hole from the other side: it computes the
+ * validation state, renders it in red text, and had no way to hand it over.
+ *
+ * ## Why NOT more keys in `DOM_PASS_THROUGH_KEYS`
+ *
+ * Because none of them is DOM-legal. That whitelist is deliberately closed and
+ * exists precisely to stop renderer plumbing reaching an element — its own
+ * header names `error`, `emptyHint`, `dataSource`, `dependentValues` and
+ * `dependsOn` as examples of what a blacklist would have failed to catch. Put
+ * them there and a `dataSource` adapter becomes `dataSource="[object Object]"`
+ * on an `<input>`. They travel as COMPONENT props, which is what they are.
+ *
+ * ## Declared = enforced, in both directions
+ *
+ * The three assertions below make the two executors PARTITION the contract:
+ * every declared key is DOM-handled, forwarded here, or named as one the
+ * factory itself owns. A key added to `FieldWidgetComponentProps` that is none
+ * of those is a compile error, so the next non-DOM key cannot repeat this bug.
+ *
+ * ## Precedence: this is a CONDUIT, and never a second authority
+ *
+ * Several of these keys have a context-based fallback inside the widget that
+ * reads them, so DELIVERING one can change behaviour where before it could not
+ * arrive at all. The rule is stated once, here, and this function implements it
+ * by doing nothing: it forwards what the host passed and resolves NOTHING.
+ * Each key's precedence stays where its single reader already implements and
+ * documents it —
+ *
+ *  - `dataSource`: **the explicit prop WINS** over `SchemaRendererContext`.
+ *    `LookupField` already resolves exactly that order and says so on the line
+ *    that does it: "explicit prop > field-level > wrapper field >
+ *    SchemaRendererContext > none". Hosts that pass nothing keep reading the
+ *    context, so the grid's inline editor is unaffected.
+ *  - `dependentValues`: the explicit prop is the ONLY channel that can carry a
+ *    record — the host supplies it, and there is NO context fallback. Both
+ *    readers (`useCascadingOptions`, and `LookupField`'s own resolver) used to
+ *    spell a `?? ctx.formValues ?? ctx.data` tail after it, but
+ *    `SchemaRendererContextType` declares exactly `dataSource` / `debug` /
+ *    `debugFlags` / `apiFetch` — neither member exists, so that tail was
+ *    unconditionally `{}` and no host could change it. It was retired under
+ *    ADR-0049 enforce-or-remove (objectui#7206). Unlike `dataSource` above,
+ *    DELIVERING this key cannot displace a context value, because there has
+ *    never been one to displace.
+ *  - `dependsOn`: the FIELD METADATA wins over the prop — the one documented
+ *    inversion, stated on the key's own doc comment and implemented as
+ *    `field?.dependsOn ?? dependsOnProp` in all four option widgets.
+ *  - `emptyHint`: the host's value wins when supplied (objectui#3231).
+ *  - `onCreateNew`: the prop wins over `field.onCreateNew`; `onSelectRecord`
+ *    has no metadata carrier at all, so the prop is its ONLY one.
+ *
+ * Resolving any of that HERE would give each key a second author — the
+ * `field || schema` shape objectui#3233 spent a release removing. One key, one
+ * resolver, in the widget that reads it.
+ */
+declare const HOST_PLUMBING_KEYS: readonly ["error", "onUploadingChange", "dataSource", "dependentValues", "dependsOn", "dependsOnLabels", "emptyHint", "onSelectRecord", "onCreateNew"];
+type HostPlumbingKey = (typeof HOST_PLUMBING_KEYS)[number];
+/** The subset of `P` this helper forwards, with each key's declared type. */
+export type HostProps<P> = Pick<P, Extract<keyof P, HostPlumbingKey>>;
+/**
+ * Keep only the declared NON-DOM keys — the host plumbing a widget interprets
+ * as component props — and drop everything else.
+ *
+ * The companion to `toDomProps`, and used the same way. A host that passes
+ * nothing gets an empty object, so the widget's prop set is unchanged:
+ *
+ * ```tsx
+ * <Widget {...toDomProps(props)} {...toHostProps(props)} field={field} … />
+ * ```
+ *
+ * Iterating the props (rather than the key list) mirrors `pickDomProps`, so a
+ * key the host did not mention stays ABSENT rather than arriving as
+ * `undefined` — which keeps the factory-boundary prop set readable as "what the
+ * host actually supplied".
+ */
+export declare function toHostProps<P extends object>(props: P): HostProps<P>;
+export {};

package/dist/widgets/types.d.ts

@@ -150,7 +150,7 @@ export type FieldWidgetComponentProps<T = any> = {
      */
     error?: string;
     /**
-     * Upload widgets (`file`/`image`) fire this when their in-progress state
+     * Upload widgets (`file`/`image`/`avatar`) fire this when their in-progress state
      * flips, so a host can block submit until a presigned upload settles. Other
      * widgets ignore it.
      */
@@ -173,7 +173,15 @@ export type FieldWidgetComponentProps<T = any> = {
     /**
      * 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`.
+     * in-progress record.
+     *
+     * ⚠️ This used to add "widgets fall back to `SchemaRendererContext`". They
+     * never could: they spelled such a fallback (`?? ctx.formValues ?? ctx.data`)
+     * while `SchemaRendererContextType` declares exactly `dataSource` / `debug` /
+     * `debugFlags` / `apiFetch`, so neither member could be supplied by any host
+     * and the fallback was unconditionally empty. Those reads were retired under
+     * ADR-0049 enforce-or-remove (objectui#7206) — this prop is the one channel
+     * that carries a record, and a widget reached without it gates.
      */
     dependentValues?: Record<string, unknown>;
     /**
@@ -187,7 +195,7 @@ export type FieldWidgetComponentProps<T = any> = {
      * 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
+     * metadata and a `dependsOn` 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

package/dist/widgets/upload-error-message.d.ts

@@ -0,0 +1,6 @@
+import { TranslateFn } from '@object-ui/i18n';
+/**
+ * The translated error row for a pick named `name` whose upload ended in
+ * `err`, either kind.
+ */
+export declare function uploadErrorMessage(t: TranslateFn, name: string, err: unknown): string;