@object-ui/fields 17.6.0 → 18.0.0

package/dist/widgets/LocationField.d.ts

@@ -1,7 +1,34 @@
 import { default as React } from 'react';
+import { LocationValue } from '@objectstack/spec/data';
 import { FieldWidgetComponentProps } from './types.js';
 /**
- * LocationField - Geographic coordinate input for latitude and longitude
- * Stores location as { latitude, longitude } object and displays as comma-separated pair
+ * The stored shape of a `type: 'location'` value — RE-EXPORTED from
+ * `@objectstack/spec/data`, never re-declared here (objectui#6272).
+ *
+ * `LocationValue` is `z.input` of the spec's `LocationValueSchema`
+ * (`{ lat, lng, altitude?, accuracy? }`), which is what `valueSchemaFor({ type:
+ * 'location' })` validates a stored location against. A second local
+ * declaration under the spec's own name is objectstack#4115's failure class and
+ * is refused by `scripts/check-spec-symbol-derivation.mjs` — it was refused on
+ * the closed PR #6418, which is why this is a bare re-export.
  */
-export declare function LocationField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<any>): React.JSX.Element;
+export type { LocationValue } from '@objectstack/spec/data';
+/**
+ * LocationField - Geographic coordinate input for a `type: 'location'` value.
+ *
+ * Reads and writes `@objectstack/spec`'s `LocationValue` (`{ lat, lng }`) and
+ * displays it as the comma-separated pair a user types. The coordinates are
+ * still called latitude and longitude to a human — only the STORED key names
+ * are the spec's (objectui#6272), which is why the placeholder names the two
+ * coordinates rather than the `lat`/`lng` keys. That is a statement about KEY
+ * NAMES, not about language: the placeholder's words are the reader's, from
+ * the locale packs (objectui#8149, {@link placeholderPair}).
+ *
+ * ⚠️ BREAKING (objectui#6272): a record stored in the deprecated
+ * `{ latitude, longitude }` spelling — including one this widget itself wrote
+ * before the flip — now renders EMPTY here until it is re-saved or fixed at the
+ * data layer. It keeps rendering correctly in detail views and on the map,
+ * which read the spec spelling first. That cost was presented and accepted as
+ * part of the A1 ruling; it is not an oversight to route around with a shim.
+ */
+export declare function LocationField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<LocationValue | null>): React.JSX.Element;

package/dist/widgets/LookupField.d.ts

@@ -3,6 +3,14 @@ import { FieldWidgetComponentProps } from './types.js';
 export interface LookupOption {
     value: string | number;
     label: string;
+    /**
+     * Secondary text: searched by the popover typeahead alongside the label, and
+     * rendered as supporting text. For AUTHORED static options this is the
+     * declared `SelectOptionMetadata.description` (objectui#6153 — declared
+     * there, and on `@objectstack/spec`'s `SelectOptionSchema`, precisely
+     * because this widget consumes it); for fetched records `recordToOption`
+     * derives it from `descriptionField`.
+     */
     description?: string;
     [key: string]: any;
 }

package/dist/widgets/NumberField.d.ts

@@ -4,4 +4,4 @@ import { FieldWidgetComponentProps } from './types.js';
  * NumberField - Numeric input with optional decimal precision
  * Supports min/max/step constraints and configurable decimal precision
  */
-export declare function NumberField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<number>): React.JSX.Element;
+export declare function NumberField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<number>): React.JSX.Element;

package/dist/widgets/ObjectField.d.ts

@@ -1,7 +1,14 @@
 import { default as React } from 'react';
 import { FieldWidgetComponentProps } from './types.js';
 /**
- * ObjectField - JSON object editor
- * Allows editing structured JSON data
+ * ObjectField - JSON editor for a structured value.
+ *
+ * The form face of the free-form JSON types: `object`, `composite`, `record`, and
+ * since objectui#11448 `json`, which used to alias the raw-text code editor and
+ * so showed a stored object as `[object Object]` and saved an edit as a string.
+ * A json value need not be an object — an array, a number, a string, a boolean
+ * and `null` are all JSON — and this editor shows and parses each of them as
+ * itself: the box holds `JSON.stringify(value, null, 2)` and an edit emits
+ * `JSON.parse(text)`.
  */
 export declare function ObjectField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<any>): React.JSX.Element;

package/dist/widgets/OptionsEmptyState.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { HostGroupProps } from './toHostGroupProps.js';
+import { HostControlProps, HostGroupProps } from './toHostGroupProps.js';
 /**
  * The "this option list cannot be filled" state shared by every fixed-option
  * widget (`SelectField` single, `MultiSelectField`, `RadioField`,
@@ -56,10 +56,34 @@ export interface OptionsEmptyStateProps {
      * `aria-describedby` and the `role` that makes them meaningful may reach this
      * element, and reopening a spread is what objectui#3291 exists to prevent —
      * `aria-invalid` / `aria-required` are control-channel state and stay off this
-     * surface. Absent for the single `SelectField` — it is not group-labelled, its
-     * label still uses a plain `for`, and it must keep emitting no such
-     * attributes.
+     * surface. Absent for the single `SelectField`, which is not group-labelled
+     * and fills {@link OptionsEmptyStateProps.hostControlProps} instead.
      */
     hostGroupProps?: HostGroupProps;
+    /**
+     * The host label's PLAIN-`for` plumbing, for the one caller that is NOT
+     * group-labelled — the single `SelectField` (objectui#8803).
+     *
+     * Supplying this switches the rendered element from a `div` to an `<output>`,
+     * and that is the entire repair. `select` declares `labelling: 'control'`,
+     * which the registry defines as "the component's outermost rendered element
+     * is a LABELABLE HTML element" — true of the Radix
+     * `button[role="combobox"]` it renders with options, and FALSE of the `div`
+     * this box used to be. So the host's `for` pointed at an id no element
+     * carried, and `HTMLLabelElement.control` was null. Landing the id on the
+     * `div` instead was measured and rejected: `for` may only reference a
+     * labelable element, so it stayed null and the label stayed unusable.
+     *
+     * `<output>` is labelable, and its implicit `status` role claims no
+     * interactivity — it is the result of a computation, which is what this box
+     * reports. Declaring `select` as `'group'` was the alternative and it
+     * measurably moved the LIVE path: a select WITH options lost the working
+     * `<label for>` to its combobox (objectui#3306).
+     *
+     * Mutually exclusive with `hostGroupProps` — one host, one naming channel
+     * (objectui#3978). A caller that supplies neither renders the box with no
+     * host plumbing at all, which is what standalone rendering has always done.
+     */
+    hostControlProps?: HostControlProps;
 }
-export declare function OptionsEmptyState({ emptyHint, gated, dependsOnFields, testId, className, hostGroupProps, }: OptionsEmptyStateProps): React.JSX.Element;
+export declare function OptionsEmptyState({ emptyHint, gated, dependsOnFields, testId, className, hostGroupProps, hostControlProps, }: OptionsEmptyStateProps): React.JSX.Element;

package/dist/widgets/PasswordField.d.ts

@@ -3,5 +3,19 @@ import { FieldWidgetComponentProps } from './types.js';
 /**
  * PasswordField - Secure password input with visibility toggle
  * Includes show/hide toggle button and masks value in readonly mode
+ *
+ * Readonly draws the mask for a credential that is SET, and the shared
+ * `EmptyValue` affordance for one that is NOT (objectui#10639). The platform's
+ * read contract is presence-preserving: `@objectstack/spec`'s `SECRET_MASK`
+ * docblock says an unset credential "reads back `null` instead, never this
+ * mask", which is what lets a reader tell "configured" from "not configured".
+ *
+ * "Empty" is the password CELL's predicate (`MaskedCellRenderer` in this
+ * package's barrel, objectui#8678), called on the same two helpers, so `{}`
+ * and a whitespace-only string stay values and keep the mask. The helpers are
+ * imported from their own modules, never from the barrel, which lazy-loads
+ * this widget. ⛔ The value is never printed, and a set value keeps exactly
+ * the mask it drew before. `__tests__/PasswordField.readonlyEmpty-10639`
+ * pins the widget's "empty" to the cell's.
  */
 export declare function PasswordField({ value, onChange, field, readonly, className, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;

package/dist/widgets/PeoplePicker.d.ts

@@ -27,12 +27,27 @@ export interface PeoplePickerProps {
     dataSource: DataSource;
     /** Object to query — `sys_user` for user fields. */
     objectName: string;
+    /**
+     * The person's name field (default `name`), read first of the name ladder
+     * (then `name`, `username`, `label`). Once the permission policy has loaded,
+     * a rung the user may not read on `objectName` is skipped.
+     */
     displayField?: string;
     idField?: string;
-    /** Dotted field paths for the row subtitle, e.g. `['primary_business_unit_id.name','email']`. */
+    /**
+     * Dotted field paths for the row subtitle, e.g. `['primary_business_unit_id.name','email']`.
+     * Once the permission policy has loaded, a path whose field on `objectName`
+     * the user may not read is not drawn.
+     */
     subtitleFields?: string[];
+    /** Avatar image field; not drawn once the loaded policy denies it on `objectName`. */
     avatarField?: string;
-    /** Related entities to expand (e.g. `['primary_business_unit_id']` for the department name). */
+    /**
+     * Related entities to expand (e.g. `['primary_business_unit_id']` for the
+     * department name). Once the permission policy has loaded, a relation the
+     * user may not read on `objectName` is left out, as it is from the list
+     * derived from `subtitleFields` when this is not passed.
+     */
     expand?: string[];
     /** Narrow the server searchable set (ADR-0061). */
     searchFields?: string[];

package/dist/widgets/PercentField.d.ts

@@ -1,7 +1,8 @@
 import { default as React } from 'react';
 import { FieldWidgetComponentProps } from './types.js';
 /**
- * PercentField - Percentage input with configurable decimal precision
+ * PercentField - Percentage input whose decimal places follow the field's
+ * `scale` as the protocol resolves it (see the read below)
  * Stores values as decimals (0-1) and displays as percentages (0-100%)
  * Includes a slider for interactive control.
  */

package/dist/widgets/PersonRow.d.ts

@@ -10,8 +10,19 @@ import { default as React } from 'react';
 export interface PersonRowProps {
     record: any;
     displayField?: string;
+    /**
+     * The fields the name is read from, in order; defaults to the ladder of
+     * `displayField` (`getPersonNameFields`). PeoplePicker passes the fields of
+     * that ladder the loaded policy lets the viewer read (objectui#10535).
+     */
+    nameFields?: string[];
     subtitleFields?: string[];
-    avatarField?: string;
+    /**
+     * Avatar image field (default `image`). `null` draws no image, only the
+     * initials: what PeoplePicker passes when field-level security withholds the
+     * field (objectui#10433).
+     */
+    avatarField?: string | null;
     selected?: boolean;
     /** Keyboard cursor is on this row — highlight + scroll into view. */
     active?: boolean;
@@ -20,4 +31,4 @@ export interface PersonRowProps {
     onSelect?: (record: any) => void;
     className?: string;
 }
-export declare function PersonRow({ record, displayField, subtitleFields, avatarField, selected, active, highlightQuery, onSelect, className, }: PersonRowProps): React.JSX.Element;
+export declare function PersonRow({ record, displayField, nameFields, subtitleFields, avatarField, selected, active, highlightQuery, onSelect, className, }: PersonRowProps): React.JSX.Element;

package/dist/widgets/RecipientPickerField.d.ts

@@ -1,4 +1,79 @@
 import { default as React } from 'react';
 import { FieldWidgetComponentProps } from './types.js';
+/**
+ * RecipientPickerField — dependent record picker for a polymorphic recipient
+ * reference (e.g. `sys_sharing_rule.recipient_id`), whose target object is
+ * decided by a sibling `recipient_type` select.
+ *
+ * Reached via the field `widget: 'recipient-picker'` hint (resolves as
+ * `field:recipient-picker`). Reads the live `recipient_type` from
+ * `dependentValues` (the form record), loads candidate records of the mapped
+ * object via `dataSource.find(...)`, and stores the value the sharing evaluator
+ * expects for that type:
+ *
+ *   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`
+ *
+ * One kind lists CATALOG ITEMS instead of records (objectui#7611, ADR-0131
+ * D3/D7): its candidates are the `position` items of the environment registry,
+ * read through the console's metadata store, and the picker stores the item's
+ * `name` (matched against `sys_user_position.position` at evaluation time):
+ *
+ *   position              → the `position` registry, store `name`
+ *
+ * One kind is NOT a record picker and therefore has no row above:
+ *
+ *   field                 → a user-valued COLUMN of the shared object, store
+ *                           the column's `name` (see FIELD_RECIPIENT_TYPE)
+ *
+ * When `recipient_type` changes after mount the stored id is reset (an id valid
+ * for one type is meaningless for another). Unknown types degrade to a plain
+ * text input so nothing breaks.
+ */
+/** A user-valued column offered by the `field` recipient mode. */
+interface UserFieldDef {
+    /** The machine name — this is what gets stored in `recipient_id`. */
+    name: string;
+    label: string;
+}
+/**
+ * Does this declared field hold USERS?
+ *
+ * ⭐ This predicate is the picker's half of a two-sided agreement with the
+ * sharing evaluator, which asks the same question of the same two spellings:
+ * the `user` type (whose target is fixed to `sys_user` by the type itself —
+ * `Field.user()` takes no target), and a `lookup` / `master_detail` whose
+ * `reference` is `sys_user`.
+ *
+ * ⛔ The two must not drift apart. The evaluator treats a column that is not
+ * user-typed as "grants nobody" and warns once per rule, so a picker that
+ * OFFERED a wider set would let an admin save a rule that looks configured and
+ * authorises nobody — worse than the hand-typed name this mode replaces,
+ * because it has a credible appearance.
+ *
+ * `reference` is the only spelling the protocol declares (objectui#6837):
+ * `FieldSchema` refuses `reference_to` by name, and the evaluator reads
+ * `reference` as well.
+ *
+ * @internal exported for tests
+ */
+export declare function fieldHoldsUsers(def: unknown): boolean;
+/**
+ * The user-valued columns of an object schema, in declaration order.
+ *
+ * Accepts both shapes an object schema spells `fields` in — a name-keyed map
+ * and an array of definitions carrying their own `name`.
+ *
+ * ⛔ `hidden` is deliberately NOT filtered here, unlike the filter builder's
+ * own field derivation: the evaluator honours a hidden user column exactly
+ * like a visible one, and withholding it would break the agreement above in
+ * the other direction — an authorable, working configuration the picker
+ * refuses to offer.
+ *
+ * @internal exported for tests
+ */
+export declare function deriveUserFields(schema: any): UserFieldDef[];
 export declare function RecipientPickerField({ value, onChange, readonly, className, error, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;
 export default RecipientPickerField;

package/dist/widgets/RecordPickerDialog.d.ts

@@ -41,7 +41,12 @@ export interface RecordPickerFilterBarProps {
  * Allows plugging in ObjectGrid or any compatible table component.
  */
 export interface RecordPickerGridSlotProps {
-    /** Resolved column definitions */
+    /**
+     * Resolved column definitions, less the ones field-level security denies
+     * once the permission policy has loaded, the display column included — the
+     * columns the built-in table draws (objectui#10373). When none survives,
+     * this is the id column alone.
+     */
     columns: LookupColumnDef[];
     /** Current page of records */
     records: any[];
@@ -93,16 +98,30 @@ export interface RecordPickerDialogProps {
     objectName: string;
     /** Columns to display. Defaults to [displayField, descriptionField]. */
     columns?: Array<string | LookupColumnDef>;
-    /** Primary display field (default: 'name') */
+    /**
+     * The display field as the lookup DECLARES it. The display column is keyed on
+     * it, or on `'name'` when it is omitted. With `objectSchema` given, a declared
+     * value is also the first rung of the column's title (the resolver's
+     * `titleField`); the `'name'` default never is, because it is a guess and a
+     * guess never outranks the referenced object's own declarations. So pass
+     * `undefined` when the field declares none, never a pre-filled `'name'`.
+     */
     displayField?: string;
     /**
-     * Optional `titleFormat` template (e.g. `"{full_name}"` or
-     * `"{case_number} - {subject}"`). When set and the displayField column is
-     * auto-inferred, the column renders via the template instead of reading
-     * a possibly-missing field. Mirrors how DetailView/ObjectCalendar resolve
-     * record titles.
+     * The referenced object's schema (objectui#10486). When given, the display
+     * column renders each record's title through `@object-ui/core`'s
+     * `getRecordDisplayName`, the call LookupField's dropdown option label and
+     * the read cell make: the declared `displayField`, then the object's
+     * `nameField`, then its deprecated `titleFormat` template, then type-aware
+     * derivation (ADR-0079). The title reads the row with its relations
+     * collapsed to ids and the fields the loaded policy denies removed, exactly
+     * as the dropdown's option label does.
+     *
+     * Replaces the retired `titleFormat` prop: a bare template cut out of the
+     * schema ranked above the `nameField` beside it, so the picker and the
+     * dropdown labelled one record two ways.
      */
-    titleFormat?: string | null;
+    objectSchema?: Record<string, unknown> | null;
     /** Record id field (default: 'id') */
     idField?: string;
     /** Page size (default: 10) */
@@ -119,7 +138,7 @@ export interface RecordPickerDialogProps {
     onSelectRecords?: (records: any[]) => void;
     /**
      * Base filters applied to every query.
-     * Converted from LookupFieldMetadata.lookup_filters.
+     * Converted from LookupFieldMetadata.lookupFilters.
      * Restricts which records are selectable (e.g. only active records).
      */
     lookupFilters?: LookupFilterDef[];
@@ -145,7 +164,7 @@ export interface RecordPickerDialogProps {
      *   (`before`, `after`, `is_empty`, `is_not_empty`) the record form has no
      *   `$op` for. No second operator vocabulary is introduced here: two already
      *   exist (the spec's `AST_OPERATOR_MAP`, data-objectstack's
-     *   `FILTER_OPERATOR_ALIASES`) and #3948 is what a third costs.
+     *   `FILTER_OPERATOR_ALIASES`) and objectstack-ai/objectstack#3948 is what a third costs.
      *
      * The discriminator is exact rather than heuristic — every AST node is an
      * ARRAY and a rule is a plain OBJECT, the same predicate `toFilterNode` uses.
@@ -168,7 +187,7 @@ export interface RecordPickerDialogProps {
      * The referenced object's schema `fields` map (field name → field
      * definition). When provided, cell renderers receive the FULL field
      * metadata — `options`, `currency`, `scale`, `precision`, `format`,
-     * `reference_to`, … — exactly like the list view enriches its columns from
+     * `reference`, … — exactly like the list view enriches its columns from
      * the object schema. Without it a `select` column falls back to
      * title-casing the raw stored value instead of resolving the option label
      * (#3333: `manufacturing` rendered as "Manufacturing" instead of the
@@ -225,4 +244,4 @@ export interface RecordPickerDialogProps {
  * states, and single/multi-select.  Responsive: mobile-friendly width
  * via Tailwind breakpoints.
  */
-export declare function RecordPickerDialog({ open, onOpenChange, title, multiple, dataSource, objectName, columns: columnsProp, displayField, titleFormat, idField, pageSize, value, onSelect, onSelectRecords, lookupFilters, baseFilter, cellRenderer, fieldsMeta, filterColumns, renderFilterBar, renderGrid, }: RecordPickerDialogProps): React.JSX.Element;
+export declare function RecordPickerDialog({ open, onOpenChange, title, multiple, dataSource, objectName, columns: columnsProp, displayField: declaredDisplayField, objectSchema, idField, pageSize, value, onSelect, onSelectRecords, lookupFilters, baseFilter, cellRenderer, fieldsMeta, filterColumns, renderFilterBar, renderGrid, }: RecordPickerDialogProps): React.JSX.Element;

package/dist/widgets/RegistryRefField.d.ts

@@ -0,0 +1,77 @@
+import { default as React } from 'react';
+import { FieldWidgetComponentProps } from './types.js';
+/**
+ * RegistryRefField — a record-form field that names ONE item of ONE metadata
+ * registry type by its machine name (objectui#7611, ruling B2 on
+ * objectstack#22865).
+ *
+ * The record-form face of the mechanism the metadata forms already have
+ * (`ref-multi:permission`, objectui#12126): the registry's items are listed by
+ * name, with the author's label beside the name, and the value written is the
+ * NAME — one string, never an id, never a row. A grant names its position or
+ * its permission set that way (ADR-0131 D4), and the server refuses a name the
+ * registry does not hold, so this widget only has to make the right name easy
+ * to pick.
+ *
+ * Reached through a field's `widget:` hint, which the form renderer looks up as
+ * `field:<widget>` (the spec's `FieldSchema.widget`). One registration per
+ * registry type, with the type in the key, as `object-ref` carries `object`:
+ *
+ *   position-ref    → `GET /api/v1/meta/position`
+ *   permission-ref  → `GET /api/v1/meta/permission`
+ *
+ * The catalog comes from `DataSource.listMetadataItems`, which rejects on a
+ * failure rather than answering `[]`, so its four arms are told apart the way
+ * the metadata forms' `ref:dataset` / `ref-multi:<type>` pickers tell them
+ * apart:
+ *
+ *  - IDLE — no data source, or one that cannot enumerate a registry: a text
+ *    box that writes the typed name;
+ *  - LOADING — the stored name in a disabled box;
+ *  - FAILED — a notice naming the failure and its cause, beside a text box that
+ *    stays enabled, so a failed catalog does not also block the edit;
+ *  - LOADED — nothing a grant can name: the same text box as IDLE; otherwise
+ *    a searchable picker. A stored name the catalog does not list stays
+ *    selectable as its own option, flagged "not found", so it is neither
+ *    dropped nor read as a listed item. The flag is a claim about the
+ *    registry's answer, so it is made only once the catalog has answered.
+ *
+ * The picker OFFERS only what a grant can name (objectui#12200). A position
+ * grant cannot name an audience anchor — `everyone` or `guest` (ADR-0090
+ * D5/D9), held implicitly by every authenticated or anonymous principal — and
+ * the server refuses a `sys_user_position` row that does. So `position-ref`
+ * leaves the anchors out of its options ({@link nonGrantableNames}). A stored
+ * anchor is still the row's value: it stays on screen as its own option, by its
+ * label beside its name, and it is not flagged "not found", because the
+ * registry does list it.
+ *
+ * ⛔ No arm writes anything but a name the person picked or typed: no label,
+ * no id, no first-item default.
+ */
+/** One listed item of a registry: the name stored, the label shown beside it. */
+export interface RegistryItemHeader {
+    name: string;
+    label?: string;
+}
+/** The catalog, in whichever of its four states the load is actually in. */
+export type RegistryCatalogState = {
+    status: 'idle';
+} | {
+    status: 'loading';
+} | {
+    status: 'error';
+    message: string;
+} | {
+    status: 'loaded';
+    items: RegistryItemHeader[];
+};
+export interface RegistryRefFieldProps extends FieldWidgetComponentProps<string> {
+    /** The registry type whose items this field names (`position`, `permission`). */
+    registryType: string;
+}
+export declare function RegistryRefField({ registryType, value, onChange, readonly, className, error, ...props }: RegistryRefFieldProps): React.JSX.Element;
+/** `position-ref`: names one position of the position registry. */
+export declare function PositionRefField(props: FieldWidgetComponentProps<string>): React.JSX.Element;
+/** `permission-ref`: names one permission set of the `permission` registry. */
+export declare function PermissionRefField(props: FieldWidgetComponentProps<string>): React.JSX.Element;
+export default RegistryRefField;

package/dist/widgets/RichTextField.d.ts

@@ -23,7 +23,7 @@ import { FieldWidgetComponentProps } from './types.js';
  * from the shared `FullscreenFieldEditor`, so one form-level setting keeps
  * producing one behaviour across both widgets.
  *
- * ## Readonly display (objectui#5498)
+ * ## Readonly display (`4bb940b6e`)
  *
  * The readonly early return used to render `{value}` as a React TEXT CHILD,
  * so a readonly field of any of the three types showed the user the markup

package/dist/widgets/SelectionTray.d.ts

@@ -12,7 +12,18 @@ export interface SelectionTrayProps {
     /** Remove a selected record by its id. */
     onRemove: (id: any) => void;
     displayField?: string;
-    avatarField?: string;
+    /**
+     * The fields each chip's name is read from, in order; defaults to the ladder
+     * of `displayField` (`getPersonNameFields`). PeoplePicker passes the fields
+     * of that ladder the loaded policy lets the viewer read (objectui#10535).
+     */
+    nameFields?: string[];
+    /**
+     * Avatar image field (default `image`). `null` draws no image, only the
+     * initials: what PeoplePicker passes when field-level security withholds the
+     * field (objectui#10433).
+     */
+    avatarField?: string | null;
     idField?: string;
     /** Header label, e.g. "Selected (3)" — omit to hide the header. */
     label?: string;
@@ -24,4 +35,4 @@ export interface SelectionTrayProps {
     emptyText?: string;
     className?: string;
 }
-export declare function SelectionTray({ records, onRemove, displayField, avatarField, idField, label, onClear, clearLabel, emptyText, className, }: SelectionTrayProps): React.JSX.Element;
+export declare function SelectionTray({ records, onRemove, displayField, nameFields, avatarField, idField, label, onClear, clearLabel, emptyText, className, }: SelectionTrayProps): React.JSX.Element;

package/dist/widgets/SummaryField.d.ts

@@ -3,5 +3,35 @@ import { FieldWidgetComponentProps } from './types.js';
 /**
  * SummaryField - Read-only aggregation field
  * Values are aggregated from related records and cannot be edited
+ *
+ * ## One value, one reading (objectui#11752)
+ *
+ * This is the read-only FORM face of a roll-up; its TABLE face is the formula
+ * cell, `FormulaCellRenderer` in this package's barrel, which `summary` is
+ * registered to. The two used to format the value each by itself, so one
+ * stored value read two ways: this face picked a format by the roll-up's
+ * aggregation `function` (`count` as it arrived, the other four at two fixed
+ * decimals), so a `sum` over `15750.5` read `15750.50`, ungrouped and in every
+ * locale, beside the cell's `15,750.5`.
+ *
+ * This face now reads the value the way the cell reads a summary's value,
+ * whatever the function:
+ *
+ *   - the emptiness FLOOR (`isEmptyValue`) on the coerced value, as the cell
+ *     takes it, so `''` and `[]` read the shared affordance in both faces;
+ *   - a JS number: `formatNumberFieldValue`, the one call every number face
+ *     makes (the display locale's grouping, the width `resolveFieldScale`
+ *     answers for a declared `scale`, the value's natural precision when none
+ *     is declared). A `count` is a whole number, so it reads whole; an author
+ *     who wants a fixed width on a `sum` or an `avg` declares `scale`, and both
+ *     faces honour it.
+ *   - anything else: the coerced value as text, as the cell prints it. A
+ *     summary declares no `returnType`, so a string of digits is not a number.
+ *
+ * The rule is spelled here and in the cell, because the barrel and this lazily
+ * loaded widget may not import each other (the reason `number-format.ts`
+ * gives). `__tests__/summaryFaces.numberFace-11752.test.tsx` draws every
+ * aggregation function in both faces and compares the two texts, so neither
+ * can move alone.
  */
 export declare function SummaryField({ value, field, ...props }: FieldWidgetComponentProps<any>): React.JSX.Element;

package/dist/widgets/TextField.d.ts

@@ -4,4 +4,4 @@ import { FieldWidgetComponentProps } from './types.js';
  * TextField - Standard single-line or multi-line text input
  * Automatically renders as a textarea when rows are configured in field metadata
  */
-export declare function TextField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;
+export declare function TextField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;

package/dist/widgets/TimeField.d.ts

@@ -4,4 +4,4 @@ import { FieldWidgetComponentProps } from './types.js';
  * TimeField - Time picker input widget
  * Uses native time input for hour and minute selection
  */
-export declare function TimeField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;
+export declare function TimeField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;

package/dist/widgets/booleanValueLabel.d.ts

@@ -0,0 +1,18 @@
+import { default as React } from 'react';
+/** Draws a boolean value as the current locale's word for it. */
+export type BooleanValueLabel = (value: boolean) => string;
+/**
+ * The current locale's word for a boolean value: `common.yes` for `true`,
+ * `common.no` for `false`.
+ *
+ * The caller decides WHICH values are booleans; this only names them. Call it
+ * once at the top of a component and use the returned function in the render.
+ */
+export declare function useBooleanValueLabel(): BooleanValueLabel;
+/**
+ * The same word as a node, for a caller that is a plain function and cannot
+ * call a hook itself (`renderLookupColumnValue`).
+ */
+export declare function BooleanValueText({ value }: {
+    value: boolean;
+}): React.ReactElement;

package/dist/widgets/date-picker/DatePickerField.d.ts

@@ -0,0 +1,40 @@
+import { default as React } from 'react';
+import { FieldWidgetComponentProps } from '../types.js';
+/**
+ * The `date` and date-time controls of the form field widgets
+ * (objectui#12622, objectui#12642).
+ *
+ * `fieldWidgetMap`'s `date` / `datetime` widgets — what a record form resolves
+ * `field:date` / `field:datetime` to, and what `getLazyFieldWidget` hands the
+ * action-param and bulk-action dialogs — draw the platform picker instead of
+ * the browser's native input: a text box in the display locale's format (keyboard
+ * entry), a calendar popover (the same `Calendar` the calendar view's date
+ * popover opens, localized by the same resolver), a clear button, and
+ * today / tomorrow shortcuts.
+ *
+ * ## The value written is unchanged
+ *
+ * Both faces go through the native adapters `DateField` / `DateTimeField` use
+ * (`toDateInputValue`, `toDateTimeInputValue`, `fromDateTimeInputValue`), so a
+ * `date` field writes `YYYY-MM-DD` and a `datetime` field writes an ISO
+ * instant, exactly as the native inputs did; clearing writes `''` as the
+ * native inputs did.
+ *
+ * ## Where the native input stays
+ *
+ * - The read-only face is `DateField` / `DateTimeField`'s own, rendered as is.
+ * - `FieldEditWidget` (the grid's inline cell editor and the kanban
+ *   required-fields dialog) draws THIS picker since objectui#12664, loaded
+ *   lazily so it stays in its own chunk; the grid's cell seam blurs the
+ *   control before Enter or a click outside commits, and that blur is where
+ *   the typed text is read. plugin-detail's `InlineFieldInput` (the record
+ *   page's details and highlights) delegates `date` and `datetime` to
+ *   `FieldEditWidget` too since objectui#12759. The list filter rows are
+ *   objectui#12743.
+ * - A form whose `field:date` widget is not registered (no
+ *   `@object-ui/fields` loaded) falls back to the form renderer's own
+ *   `<input type={inputType}>`, with the `inputType` `ObjectForm` maps.
+ */
+export declare function DatePickerField(props: FieldWidgetComponentProps<string>): React.JSX.Element;
+/** The `datetime` face of {@link DatePickerField}. */
+export declare function DateTimePickerField(props: FieldWidgetComponentProps<string>): React.JSX.Element;