@object-ui/fields 17.5.0 → 17.7.0

package/dist/widgets/richTextDisplay.d.ts

@@ -0,0 +1,116 @@
+import { default as React } from 'react';
+import { CellRendererProps } from '../index.js';
+/**
+ * Renders `markdown` values as formatted GFM markdown (lazy-loaded, sanitized)
+ * instead of the raw markup string.
+ *
+ * Markdown ONLY. `MarkdownContent` runs react-markdown with no `rehype-raw`, so
+ * raw HTML in the string is not parsed and never reaches the DOM — that is this
+ * renderer's trust boundary, not an oversight, and it must stay that way
+ * (objectui#5452). `richtext` used to be routed here too and rendered as a
+ * COMPLETELY EMPTY cell, because a richtext value is entirely HTML and this
+ * 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;
+/**
+ * Renders an `html` value as sanitized, formatted HTML instead of raw markup.
+ *
+ * Also the renderer for `richtext` (objectui#5452). Both types store an HTML
+ * string: the spec's `Field.richtext` is documented as "Formatted content with
+ * HTML/WYSIWYG", the showcase seed's own specimen is
+ * `<p>Rich <strong>text</strong></p>`, and this repo's designer bridge already
+ * maps `richtext` onto its `html` type. {@link sanitizeHtml} above removes
+ * script/style/iframe/object/embed blocks, inline event handlers and
+ * `javascript:` URLs, and touches nothing a rich-text editor legitimately
+ * 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;
+/**
+ * Field type → display pipeline, for the three types `RichTextField` serves.
+ *
+ * THE table, singular. `getCellRenderer`'s standard map spreads it (so the
+ * grid, kanban, gallery, related list, dashboard panel and detail read mode
+ * resolve through these entries) and `RichTextField`'s readonly branch indexes
+ * it (so a readonly form field renders through the very same component). A
+ * change here moves every read surface at once; there is no second copy left
+ * to forget.
+ *
+ * `richtext` reads through the HTML renderer — NOT the markdown one, which
+ * drops raw HTML and therefore rendered every populated richtext value as a
+ * blank cell (objectui#5452).
+ */
+export declare const RICH_TEXT_CELL_RENDERERS: {
+    readonly markdown: typeof MarkdownCellRenderer;
+    readonly html: typeof HtmlCellRenderer;
+    readonly richtext: typeof HtmlCellRenderer;
+};
+/** 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 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
+ *
+ * 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.
+ *
+ * ⚠️ 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 const RICH_TEXT_FIELD_TYPES: readonly RichTextFieldType[];
+/**
+ * The SYNTAX a rich-content type stores, derived from the renderer that type
+ * resolves to rather than declared a second time.
+ *
+ * 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.
+ *
+ * `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.
+ */
+export declare function richTextSyntax(fieldType: string): 'markdown' | 'html' | undefined;
+/**
+ * The display pipeline a field type reads through, or `undefined` when the
+ * type is not one of the three rich-content types.
+ *
+ * The lookup is a function rather than a raw index so the "not a rich-content
+ * type" answer is in the RETURN TYPE. Indexing {@link RICH_TEXT_CELL_RENDERERS}
+ * directly hands back a non-optional component for any key the caller casts,
+ * so the miss becomes a runtime `undefined` the compiler has been told cannot
+ * happen — and a caller that checks for it reads as dead code.
+ */
+export declare function richTextCellRenderer(fieldType: string): React.FC<CellRendererProps> | undefined;

package/dist/widgets/toDomProps.d.ts

@@ -83,7 +83,16 @@ 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 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. */
 export type DomProps<P> = CoreDomProps<P, DomPassThroughKey>;
 /**

package/dist/widgets/toHostGroupProps.d.ts

@@ -7,19 +7,21 @@
  */
 /**
  * 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).
+ * host label actually NAMES — and, where nothing else can carry it, DESCRIBES
+ * (objectui#3990, objectui#4005).
  *
  * ## 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:
+ * by IDREF. The renderer hands down 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.
+ *  - `aria-labelledby` — the IDREF of that visible label;
+ *  - `aria-describedby` — the IDREF of `<FormDescription>`, the field's visible
+ *    help text. Which surface may consume it is the one thing that is NOT
+ *    uniform, so it is decided per call site — see {@link HostGroupSurface}.
  *
  * Every editable branch already consumes them inside its wider `toDomProps`
  * spread. The branches that returned EARLY did not — a field-level
@@ -39,19 +41,66 @@
  * 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
+ * ## The description was the other half of the same defect (objectui#4005)
  *
- * 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`.
+ * #3990 landed the `id` + `aria-labelledby` pair above and deliberately stopped
+ * there. The reasoning it recorded — a readonly display has no focusable
+ * control, and `aria-describedby` is announced when focus lands on something
+ * focusable — was the right call for the surface as it stood THEN: before this
+ * helper existed, a readonly branch had no role at all, and on a role-less
+ * `div` / `span` an `aria-describedby` is as inert as the `aria-labelledby`
+ * was. That premise expired the moment #3990 gave those surfaces
+ * `role="group"`. A group IS a description carrier under ARIA 1.2: assistive
+ * technology announces a group's name and description on entering it, with no
+ * focusable control required. So the help text stayed measurably unreachable
+ * for exactly as long as it took to have somewhere to put it. Measured on
+ * `origin/main` at `c25222758`, a real form, one field per row, counting the
+ * elements whose `aria-describedby` names the rendered `<FormDescription>`:
  *
- * ## Why `role` travels with the two keys
+ * ```
+ *                                    descEl  consumers  consumerTags
+ * address      editable   desc=YES   SET         1      [input]
+ * address      readonly   desc=YES   SET         0      []
+ * geolocation  editable   desc=YES   SET         1      [input]
+ * geolocation  readonly   desc=YES   SET         0      []
+ * checkboxes   editable   desc=YES   SET         1      [div[group]]
+ * checkboxes   readonly   desc=YES   SET         0      []
+ * radio        editable   desc=YES   SET         1      [div[radiogroup]]
+ * radio        readonly   desc=YES   SET         0      []
+ * rating       editable   desc=YES   SET         1      [div[group]]
+ * rating       readonly   desc=YES   SET         0      []
+ * file         editable   desc=YES   SET         1      [div[button]]
+ * file         readonly   desc=YES   SET         0      []
+ * multiselect  editable   desc=YES   SET         1      [div[group]]
+ * multiselect  readonly   desc=YES   SET         0      []
+ * ```
+ *
+ * All seven render the `<FormDescription>` in the readonly state — none is
+ * exempt for want of one — and all seven left it referenced by nothing.
+ *
+ * ## What still does NOT come along, and why that is a boundary and not an oversight
+ *
+ * `aria-invalid` and `aria-required` are CONTROL-channel state: they report
+ * what a user's own editing may do wrong, to the element they would edit. A
+ * readonly display cannot be edited and cannot be made invalid by the person
+ * reading it, so putting either on it announces a state that has no action
+ * behind it. Spreading the whole `toDomProps` result would drag both back —
+ * along with `disabled` / `tabIndex` / the focus handlers, which only mean
+ * something on an interactive element, and `name`, which is DOM-legal on form
+ * controls only and on a `div` is exactly the leak objectui#3291 sweeps for.
+ * That is what objectui#3291 and objectui#3318 drew the line against, and
+ * adding the description does not move it: the description is what the FIELD
+ * is, the other two are what the CONTROL is doing. The line is pinned from both
+ * sides in `composite-group-label-readonly-e2e.test.tsx` — the description must
+ * be there, `aria-invalid` / `aria-required` must not — so neither a later
+ * "spread it all" nor a later "take it all back out" can pass quietly.
+ *
+ * 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 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
@@ -73,19 +122,121 @@ export interface HostGroupProps {
     id?: string;
     /** IDREF of the host's visible label. */
     'aria-labelledby'?: string;
+    /**
+     * IDREF of the host's visible help text — present only on a surface that
+     * renders no input of the field's own. See {@link HostGroupSurface}.
+     */
+    'aria-describedby'?: 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}.
+ * WHERE the surface being named sits relative to the field's own inputs. The
+ * name is uniform; the DESCRIPTION is not, so every call site has to say which
+ * of the two shapes it is, and the compiler makes the next widget author say it
+ * too rather than inherit whichever default happened to be there.
+ *
+ *  - `'above-the-inputs'` — a composite's EDITABLE container (`address`,
+ *    `geolocation`): the field's real inputs are inside it and each already
+ *    receives `aria-describedby` in its own `toDomProps` spread, straight from
+ *    `<FormControl>`'s Slot. This surface therefore takes the NAME only.
+ *    objectui#3318 chose that split deliberately and
+ *    `composite-group-label-e2e.test.tsx` pins it: the help text is announced
+ *    when focus reaches the box the user types into, and announcing it a second
+ *    time on the container that merely wraps those boxes is a double channel of
+ *    exactly the kind objectui#3290 removed from the required marker.
+ *
+ *  - `'instead-of-the-inputs'` — every readonly branch, and the zero-option box
+ *    (`OptionsEmptyState`). The field renders no input at all here, so no
+ *    element inside can carry the description and this surface is the only
+ *    candidate there is. It takes the name AND the description.
+ *
+ * Note what the discriminator is NOT about: whether the surface contains
+ * anything focusable. `geolocation`'s readonly row holds a "View on map" link
+ * — focusable, and correctly announced as itself. It is not an input OF THE
+ * FIELD and never receives the field's `aria-describedby`, so that row is still
+ * `'instead-of-the-inputs'`.
+ */
+export type HostGroupSurface = 'above-the-inputs' | 'instead-of-the-inputs';
+/**
+ * Read the whole-field keys out of a widget's leftover props, plus the role
+ * that makes them mean something. See {@link HostGroupProps} and
+ * {@link HostGroupSurface}.
  *
  * 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
+ * keys keep ONE gate: they reach an element only if the DOM pass-through
+ * whitelist still forwards them, and its compile-time assertions bind that
  * whitelist to the props contract in both directions.
+ *
+ * `aria-describedby` is forwarded exactly as the host handed it down, with no
+ * check that it resolves — a widget cannot see whether `<FormDescription>`
+ * rendered, and a DOM probe for it would be a layout-effect hack around the
+ * renderer's own knowledge. That is not a new gap: `<FormControl>`'s Slot emits
+ * the IDREF unconditionally, so a field with NO description already hands every
+ * editable control an `aria-describedby` pointing at an element that does not
+ * exist. Measured on `origin/main` at `c25222758`, `desc=NO`: all seven
+ * group-labelled widgets plus the builtin `input` and the single-control
+ * `email` carry exactly one such reference, on the same element that would
+ * carry a resolving one. A readonly surface answering identically is parity
+ * with the editable branch, not a class of its own — and an IDREF that resolves
+ * to nothing is inert for assistive technology, where an unconsumed
+ * description is simply lost.
  */
 export declare function toHostGroupProps(props: {
     id?: string;
     'aria-labelledby'?: string;
-}): HostGroupProps;
+    '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,16 +150,21 @@ 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.
      */
     onUploadingChange?: (uploading: boolean) => void;
     /**
      * DataSource for widgets that query records (lookup / user / object-ref /
-     * recipient-picker / grid). Injected by the form renderer for the field
-     * types that need it, and passed directly by inline-edit hosts. Option
-     * widgets destructure it purely to keep it off their DOM spread.
+     * recipient-picker). Injected by the form renderer for the field types that
+     * need it, and passed directly by inline-edit hosts. Option widgets
+     * destructure it purely to keep it off their DOM spread.
+     *
+     * `grid` was listed here with zero consumers (objectui#4814): `GridField.tsx`
+     * never reads `dataSource`, and no data-source table has ever contained the
+     * key, so the claim described a wiring that did not exist. `owner` is absent
+     * for a different reason — the spelling itself is retired (same card).
      *
      * Left structural (`unknown`): `@object-ui/fields` must not depend on a
      * concrete adapter — every consumer narrows it itself.
@@ -168,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>;
     /**
@@ -182,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;