@object-ui/fields 17.6.0 → 17.7.0

package/dist/widgets/AvatarField.d.ts

@@ -1,7 +1,23 @@
 import { default as React } from 'react';
 import { FieldWidgetComponentProps } from './types.js';
 /**
- * Avatar field widget - provides an avatar/profile picture uploader
- * Supports image URLs or file uploads
+ * Avatar field widget - provides an avatar/profile picture uploader.
+ *
+ * `avatar` is a member of the file-reference family, so its stored value is
+ * the bare `sys_file` id, exactly as for `file` and `image` (see
+ * `file-value`'s "Submitting"). A pick uploads through the ambient
+ * `UploadProvider` (`useUpload()`), and the id the adapter surfaced in
+ * `meta.fileId` is what `onChange` receives, through `fileValueForSubmit` —
+ * the one submit rule the file and image widgets use. A pick whose adapter
+ * surfaced no id (the object-URL default `useUpload()` falls back to when no
+ * provider is mounted, an S3/Azure-style adapter that mints no `sys_file`
+ * row) is refused with the same translated "did not complete" row, and the
+ * field is not changed. ⛔ The widget used to read the pick into a `data:` URL
+ * and store that string, inlining the whole image into the record row as a
+ * value the stored contract refuses (objectui#10785).
+ *
+ * Reading is `readFileValue`'s: a bare id renders from the storage endpoint,
+ * and a legacy `data:` or http(s) URL already on a record still renders as
+ * itself — ADR-0104's dual-read window is a read rule.
  */
-export declare function AvatarField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;
+export declare function AvatarField({ value, onChange, field, readonly, onUploadingChange, error, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;

package/dist/widgets/BooleanField.d.ts

@@ -4,4 +4,4 @@ import { FieldWidgetComponentProps } from './types.js';
  * BooleanField - Toggle input supporting switch and checkbox variants
  * Renders as Switch or Checkbox based on field widget configuration
  */
-export declare function BooleanField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<boolean>): React.JSX.Element;
+export declare function BooleanField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<boolean>): React.JSX.Element;

package/dist/widgets/DateField.d.ts

@@ -4,4 +4,4 @@ import { FieldWidgetComponentProps } from './types.js';
  * DateField - Date picker input widget
  * Uses native date input and displays locale-formatted date in readonly mode
  */
-export declare function DateField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;
+export declare function DateField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;

package/dist/widgets/DateTimeField.d.ts

@@ -4,4 +4,4 @@ import { FieldWidgetComponentProps } from './types.js';
  * DateTimeField - Combined date and time picker widget
  * Displays both date and time in locale format when readonly
  */
-export declare function DateTimeField({ value, onChange, field, readonly, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;
+export declare function DateTimeField({ value, onChange, field, readonly, error, ...props }: FieldWidgetComponentProps<string>): React.JSX.Element;

package/dist/widgets/FilterConditionField.d.ts

@@ -7,8 +7,7 @@ interface BuilderCondition {
     value: any;
 }
 /**
- * Opt-in FilterBuilder operators this widget offers (objectui#4023,
- * objectui#4736).
+ * Opt-in FilterBuilder operators this widget offers (objectui#4736).
  *
  * The shared dropdown withholds these because two of its three consumers
  * persist into dialects that cannot carry them (see `OPT_IN_OPERATORS` in
@@ -18,14 +17,19 @@ interface BuilderCondition {
  * folded into a `ViewFilterRule` — so the spec's `FILTER_OPERATORS` is the only
  * vocabulary it has to satisfy.
  *
- *   - `containsCaseInsensitive` authors `$icontains`, executable on every
- *     driver and evaluation face the platform ships (objectstack#5702 +
- *     objectstack#6520).
  *   - `exists` / `notExists` author `$exists`, which `condToMongo` has emitted
  *     and `kvToCondition` has read back since objectui#2942. Naming them here
  *     is what KEEPS them reachable now that the shared dropdown no longer
  *     offers them to the list and view surfaces, whose dialects have no
- *     existence operator at all (objectui#4736).
+ *     existence operator at all (objectui#4736). They are NOT folded onto
+ *     `is_not_null` / `is_null` (objectui#9559 ruling B, objectui#9306): on the
+ *     key-presence drivers that would change which records a stored sharing
+ *     rule matches.
+ *
+ * The case-insensitive contains used to be named here too, as
+ * `containsCaseInsensitive`. Since objectui#9306 it is the protocol's own
+ * `icontains` and an ordinary operator every consumer is offered, so there is
+ * nothing to opt into; it still authors `$icontains`, exactly as before.
  *
  * Module scope, not an inline literal: a fresh array each render would reset
  * `FilterBuilder`'s memo inputs on every keystroke.
@@ -38,12 +42,22 @@ export declare const FILTER_CONDITION_EXTRA_OPERATORS: readonly string[];
  * chokepoint where a builder token becomes a spec `FieldOperatorsSchema` key,
  * and a wrong spelling here is rejected downstream by `convertFiltersToAST`
  * rather than at authoring time. @internal
+ *
+ * ⚠️ The arms are keyed on the builder's PROTOCOL ids (objectui#9306), and the
+ * `default` arm stores an EQUALITY. So an operator id with no arm here is not
+ * refused — it silently becomes `{ [field]: value }`, which for a
+ * `greater_than_or_equal` row would share a different set of records than the
+ * one on screen. Every id the dropdown can draw has its own arm, and
+ * `filter-builder-protocol-ids-census-9306.test.ts` (app-shell) pins each one's
+ * stored predicate, so a missing arm is a red test rather than a quiet `$eq`.
  */
 export declare function condToMongo(c: BuilderCondition, typeOf: (f: string) => string | undefined): Record<string, any> | null;
 /**
  * Criteria → builder condition (the reverse of {@link condToMongo}). Returning
  * `null` makes the builder refuse to load the rule ("criteria can't be
  * represented"), so this must keep accepting spellings previously written.
+ * The rows it produces carry the builder's protocol ids (objectui#9306); the
+ * stored criteria are `$`-tokens, which that change did not touch.
  * @internal
  */
 export declare function kvToCondition(field: string, v: any, idx: number): BuilderCondition | null;
@@ -51,7 +65,7 @@ export declare function kvToCondition(field: string, v: any, idx: number): Build
  * Would this criteria select EVERY record of the object?
  *
  * Mirrors the server's `isMatchAllCriteria` (objectstack `plugin-sharing`,
- * #3896) closely enough to warn before the round-trip: blank, `{}`, `[]`, and
+ * objectstack-ai/objectstack#3896) closely enough to warn before the round-trip: blank, `{}`, `[]`, and
  * the vacuous combinators. Deliberately conservative in the same direction —
  * the cost of a false positive is one extra hint, the cost of a false negative
  * is a save that fails with a toast. The server stays authoritative.

package/dist/widgets/GeolocationField.d.ts

@@ -4,9 +4,15 @@ import { FieldWidgetComponentProps } from './types.js';
  * Geolocation data structure
  */
 export interface GeolocationValue {
-    latitude?: number;
-    longitude?: number;
-    accuracy?: number;
+    /**
+     * `number | null` since objectui#6848. `null` is what an emptied box emits —
+     * the spelling `CurrencyField` / `PercentField` / `NumberField` already used
+     * for the same user action — so the type has to admit it. `undefined` stays
+     * admissible because an untouched coordinate is genuinely absent.
+     */
+    latitude?: number | null;
+    longitude?: number | null;
+    accuracy?: number | null;
 }
 /**
  * Geolocation field widget - provides a location picker with coordinates

package/dist/widgets/GridField.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { FieldWidgetComponentProps } from './types.js';
+import { InlineGridColumn } from '@objectstack/spec/data';
 /**
  * GridField / LineItemsField — editable child-grid ("line items") widget.
  *
@@ -46,106 +47,64 @@ import { FieldWidgetComponentProps } from './types.js';
  * column. This is the renderer for the `field:grid` widget and the cell
  * engine behind the master-detail subform (see ADR-0001).
  *
- * Column config (a subset of `GridColumnDefinition`):
- *   { name, label?, type?, options?, width?, required?, prefix?, step? }
- *   type ∈ 'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time'
- *        | 'select' | 'lookup' | 'file'
+ * Column config: `@objectstack/spec`'s inline grid column, by reference —
+ * see {@link GridColumn}.
  *
- * Field-level config (from `GridFieldMetadata`):
- *   columns, min_rows, max_rows, allow_add, allow_delete, total_field
+ * Field-level config: the keys `GridFieldMetadata` (`@object-ui/types`)
+ * declares, each read under that one spelling (objectui#11070 round 8), and
+ * no other key: `sort_field`, the last key read before any face declared it,
+ * is declared there too (objectui#11070 round 9).
  */
-export interface GridColumn {
-    /**
-     * The column's field name — the key it reads and writes on each row object.
-     *
-     * Spelled `name`, exactly as the declared `GridColumnDefinition`
-     * (`@object-ui/types`) and the grid docs page say (objectui#3951). This
-     * widget used to read a divergent `field` key, so metadata authored against
-     * the published type rendered every cell empty plus a React key warning.
-     * There is deliberately no tolerant alias bridging the retired spelling to
-     * this one: a single spelling, enforced at the producer — AGENTS.md #0.1.
-     *
-     * (Wording note: do not restate that rule as an alternation expression over
-     * the two key names. `column-identity.ratchet.test.ts` (objectui#3104) scans
-     * these files line by line and cannot tell prose from code, so spelling the
-     * shape out here registers as a new dual read and fails the gate.)
-     */
-    name: string;
-    label?: string;
-    /**
-     * Cell control + read/write adapter for the column.
-     *
-     * `date` / `datetime` / `time` are three DISTINCT controls, not one
-     * (objectui#3569). Collapsing `datetime` onto the `date` control did not
-     * merely under-render it — `<input type="date">` hands back a bare
-     * `YYYY-MM-DD` on change, so touching the day of a `datetime` cell silently
-     * DELETED its time component from the record.
-     */
-    type?: 'text' | 'number' | 'currency' | 'date' | 'datetime' | 'time' | 'select' | 'lookup' | 'file';
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
-    width?: number;
-    required?: boolean;
-    prefix?: string;
-    step?: number;
-    /** For `type: 'lookup'` — the referenced object and label/id fields. */
-    reference?: string;
-    displayField?: string;
-    idField?: string;
-    /** Multi-value column: multi-record lookup, or multi-file upload cell. */
-    multiple?: boolean;
-    /** For `type: 'file'` — accepted MIME types / extensions for the picker
-     *  (e.g. `['image/*', '.pdf']`). Omit to accept anything. */
-    accept?: string[];
-    /**
-     * Hidden from the grid by default but revealable via the column chooser.
-     * Set by `deriveColumns` for fields beyond the default-visible budget — the
-     * data is NOT dropped (it's just collapsed, like Odoo's `optional` columns /
-     * Salesforce column personalization), so business-critical fields stay
-     * reachable. Required columns are never default-hidden.
-     */
-    defaultHidden?: boolean;
-    /**
-     * A computed (read-only) column whose value is derived live from sibling
-     * cells via {@link expr} — e.g. an invoice line's `amount = quantity *
-     * unit_price`. The grid renders it read-only, recomputes it as the row's
-     * inputs change, and writes the result back into the row so it persists
-     * (and any running total reflects it). The classic spreadsheet pattern used
-     * by QuickBooks / Stripe / NetSuite line grids — nobody types the amount.
-     */
-    computed?: boolean;
-    /** Arithmetic expression for a {@link computed} column. Supports `+ - * / %`,
-     *  parentheses, numeric literals and field refs (`record.qty` or bare `qty`). */
-    expr?: string;
-    /** Decimal places to round a computed numeric/currency result to. */
-    scale?: number;
-    /** For `type: 'lookup'` — when a record is picked, copy its fields into any
-     *  sibling columns of the same name (e.g. a product's unit_price/description).
-     *  On by default for lookup columns; set `false` to disable the auto-fill. */
-    autofill?: boolean;
-    /**
-     * CEL predicate: when TRUE for this row, the cell is **read-only** (B2 field
-     * rules, generalized to grid cells). Evaluated per row against the row as
-     * `record` plus the header as `parent` (so a line locks when
-     * `parent.status == 'paid'` *or* on an intra-row condition like
-     * `record.kind == 'auto'`). Client-side UX; fails open (stays editable).
-     */
-    readonlyWhen?: string | {
-        dialect?: string;
-        source: string;
-    };
-    /**
-     * CEL predicate: when TRUE for this row, the cell is **required** (flagged
-     * inline-invalid while empty). Same `record` + `parent` scope as
-     * {@link readonlyWhen}.
-     */
-    requiredWhen?: string | {
-        dialect?: string;
-        source: string;
-    };
-}
+/**
+ * One grid column — `@objectstack/spec`'s inline grid column
+ * (`InlineGridColumn`, the element of `FieldSchema.inlineColumns`), BY
+ * REFERENCE (objectui#11070). The spec declares that shape as the strict
+ * mirror of this widget's column, so the widget's type IS the spec's: one
+ * declaration, the same one `GridFieldMetadata.columns` and
+ * `FormField.columns` (`@object-ui/types`) carry. This widget reads each
+ * column by exactly the spec's keys — every key below is one the spec
+ * declares, and there is no second spelling of any of them.
+ *
+ * How the widget reads the keys (the spec's own descriptions say what each
+ * MEANS; these are the renderer's notes):
+ *
+ *  - `name` — the key a column reads and writes on each row object. There is
+ *    deliberately no tolerant alias bridging the spelling objectui#3951
+ *    retired to this one: a single spelling, enforced at the producer —
+ *    AGENTS.md #0.1 (the spec refuses the retired spelling by name).
+ *    (Wording note: do not restate that rule as an alternation expression over
+ *    the two key names. `column-identity.ratchet.test.ts` (objectui#3104) scans
+ *    these files line by line and cannot tell prose from code, so spelling the
+ *    shape out here registers as a new dual read and fails the gate.)
+ *  - `type` — the cell control and its read/write adapter. `date` /
+ *    `datetime` / `time` are three DISTINCT controls, not one
+ *    (objectui#3569): `<input type="date">` hands back a bare `YYYY-MM-DD` on
+ *    change, so collapsing `datetime` onto it silently DELETED the time
+ *    component from the record.
+ *  - `prefix` — a symbol shown in a `currency` cell IN PLACE OF the resolved
+ *    currency's own symbol. When absent, the cell shows the symbol of the
+ *    currency it resolves (objectui#10355); there is no default symbol.
+ *  - `defaultHidden` — collapsed into the column chooser, not dropped
+ *    (`deriveColumns` sets it beyond the default-visible budget). Required
+ *    columns are never default-hidden.
+ *  - `computed` + `expr` — a read-only column recomputed live from sibling
+ *    cells by this file's own safe arithmetic evaluator (`+ - * / %`,
+ *    parentheses, numeric literals, `record.qty` or bare `qty`), and written
+ *    back into the row so it persists and any running total reflects it.
+ *  - `scale` — decimal places for a computed `number` result. ⛔ Not read on
+ *    a `currency` column (objectui#10783): the resolved currency's ISO 4217
+ *    minor unit decides both the stored and the shown width
+ *    (`currencyWidth`), and the spec refuses `scale` on a column declaring
+ *    `type: 'currency'`. A column that takes `currency` from its child field
+ *    at render time is reported by `hydrateColumns` in
+ *    `@object-ui/plugin-form` instead of being read in silence.
+ *  - `autofill` — for a `lookup` column: picking a record copies its fields
+ *    into sibling columns of the same name. On unless set `false`.
+ *  - `readonlyWhen` / `requiredWhen` — CEL predicates evaluated per row
+ *    against the row as `record` plus the header as `parent`. Client-side UX;
+ *    a predicate that faults fails open.
+ */
+export type GridColumn = InlineGridColumn;
 type Row = Record<string, any>;
 /** Evaluate an arithmetic `expr` against `row`. null when blank/unparseable. */
 export declare function evalArith(expr: string, row: Row): number | null;
@@ -163,7 +122,12 @@ export declare function evalArith(expr: string, row: Row): number | null;
  * it is unit-testable independent of the picker UI.
  */
 export declare function lookupAutofillPatch(columns: GridColumn[], col: GridColumn, record: any): Row;
-export declare function computeRow(columns: GridColumn[], row: Row): Row;
+/**
+ * @param tenantCurrency the tenant's default currency (`useLocalization()`),
+ *   the resolver's last step for a `currency` column — see
+ *   {@link storedFractionScale}.
+ */
+export declare function computeRow(columns: GridColumn[], row: Row, tenantCurrency?: string): Row;
 /** Sum a numeric column across rows (ignoring blanks/NaN). */
 export declare function sumColumn(rows: Row[], field: string): number;
 export declare function GridField({ value, onChange, field, readonly, disabled, className, error, onRowExpand, displayMode, onAdd, ...props }: FieldWidgetComponentProps<Row[]> & {

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,47 @@
 import { default as React } from 'react';
 import { FieldWidgetComponentProps } from './types.js';
+/** 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;