@object-ui/fields 17.6.0 → 18.0.0

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 import { default as React } from 'react';
 import { FieldMetadata } from '@object-ui/types';
-import { humanizeLabel, ComponentMeta } from '@object-ui/core';
+import { PercentScale, humanizeLabel, formatDate, formatDateTime, formatDateTimeCompactParts, formatRelativeDate, RegistryComponentMeta, DateDisplayOptions } from '@object-ui/core';
+import { formatCurrency, percentCellScale } from './widgets/number-format.js';
+import { coerceToSafeValue } from './coerceToSafeValue.js';
 import { resolveFieldCurrency } from './currency.js';
 /**
  * Pick the most reasonable display name from an arbitrary record object.
@@ -9,8 +11,18 @@ import { resolveFieldCurrency } from './currency.js';
 export declare function pickRecordDisplayName(record: Record<string, unknown> | null | undefined, preferredField?: string): string | undefined;
 /**
  * Heuristic: detect strings that look like opaque foreign-key IDs (e.g. nanoid
- * or BSON ObjectId). Used so we don't display random gibberish to users when
- * a lookup wasn't expanded.
+ * or BSON ObjectId).
+ *
+ * ⛔ Nothing in this repo calls it any more, and re-introducing a caller that
+ * decides PRESENTATION from it would re-open objectui#8695. It used to gate
+ * `LookupCellRenderer`'s muted `—`, i.e. it decided how an unresolved
+ * reference was drawn from the SHAPE of the string rather than from whether
+ * anything resolved — so `'Ada Lovelace'` printed as a confident name and an
+ * opaque id lost its value, two opposite answers to one epistemic state. The
+ * export is kept because it is part of this package's published surface and
+ * retiring it is a breaking change no display card is entitled to make; the
+ * shape question itself is legitimate (a picker filter, an id-vs-name guess),
+ * it is only an answer to "what did this screen resolve?" that it can never be.
  */
 export declare function isLikelyOpaqueId(v: unknown): boolean;
 /**
@@ -21,16 +33,42 @@ export interface CellRendererProps {
     field: FieldMetadata;
     isEditing?: boolean;
     onChange?: (value: any) => void;
+    /**
+     * The row's values, for a renderer whose value only means something next to
+     * a sibling column — the cell-side counterpart of the edit widget's
+     * `FieldWidgetComponentProps.dependentValues` (objectui#12613). The console's
+     * `recipient-picker` face reads the row's `recipient_type` from it, as the
+     * picker reads the form record's.
+     *
+     * A call site that holds the row passes it; a renderer that needs a sibling
+     * and gets none draws the stored value as the text cell does, so a call site
+     * that does not pass it changes nothing.
+     */
+    dependentValues?: Record<string, unknown>;
+    /**
+     * The host's answer to "is this declared deadline settled for this row?"
+     * (objectui#11815) — `isDeadlineSettled` from `@object-ui/core`, which
+     * evaluates the field's `settledWhen` against the row the host holds. A cell
+     * cannot evaluate a predicate, so the host hands it the verdict.
+     *
+     * While it is `true` the `date` and `datetime` cells paint no overdue wording
+     * and no overdue colour: the relative wording falls back to the neutral
+     * phrase a non-deadline reads. Absent or `false` changes nothing.
+     */
+    deadlineSettled?: boolean;
 }
+export { coerceToSafeValue };
+export { resolveFieldCurrency };
 /**
- * Coerce a value to a safe primitive for rendering.
- * Handles MongoDB wrapper types ($numberDecimal, $oid, $date), expanded
- * reference objects, and arrays so that no raw object is ever passed as
- * a React child — preventing React error #310.
+ * `formatCurrency` lives beside `formatNumberFieldValue` in
+ * `./widgets/number-format.ts`, re-exported here under its long-standing
+ * `@object-ui/fields` name: `CurrencyField`'s read-only branch calls the same
+ * function `CurrencyCellRenderer` below calls, and the lazily loaded widget
+ * cannot import this barrel (objectui#11444). The width (the currency's ISO
+ * 4217 minor-unit count, every amount, no whole-amount trimming) and its
+ * history are documented there.
  */
-export declare function coerceToSafeValue(value: unknown): string | number | boolean | null | undefined;
-export { resolveFieldCurrency };
-export declare function formatCurrency(value: number, currency?: string, locale?: string): string;
+export { formatCurrency };
 /**
  * Format currency value in compact form for mobile display.
  * E.g., $150,000 → $150K, $1,200,000 → $1.2M
@@ -38,18 +76,36 @@ export declare function formatCurrency(value: number, currency?: string, locale?
  */
 export declare function formatCompactCurrency(value: number, currency?: string, locale?: string): string;
 /**
- * Format a plain number with thousands separators, no currency symbol.
- * Used as a safe fallback when a currency-typed field has no `currency`
- * configured — we'd rather render `1,234.50` than silently assume USD.
+ * Format a plain number with thousands separators at a fixed display width, no
+ * currency symbol. `formatCurrency` renders an amount with no currency resolved
+ * through the same call shape (`./widgets/number-format.ts`): we'd rather
+ * render `1,234.50` than silently assume USD.
  */
 export declare function formatNumber(value: number, decimals?: number, locale?: string): string;
 /**
- * Format percent value.
- * Handles both decimal (0.8 = 80%) and whole number (80 = 80%) inputs.
+ * `percentCellScale` lives beside `formatPercentPoints` in
+ * `./widgets/number-format.ts` and is re-exported here: the storage scale the
+ * percent cell reads a field at, so every face rendering the cell's number for
+ * the same field reads the same answer by reference (objectui#11475).
+ */
+export { percentCellScale };
+/**
+ * Format a stored percentage at the storage the caller STATES.
  *
- * `locale` is the third positional parameter, matching {@link formatNumber} and
- * {@link formatCurrency} — the shape the sibling formatters already use.
- * Callers should pass the tag from `useDisplayLocale()`.
+ * `percentScale` is REQUIRED (objectui#11475): `'fraction'` (0.8 means 80%) or
+ * `'whole'` (80 means 80%), the spec's `PercentScale`. A face holding a field
+ * reads it with {@link percentCellScale} (the spec's `percentScaleOf`, a
+ * fraction unless the field declares a `max` above 1); a face without one
+ * states what it knows. A value outside the union throws. This used to guess
+ * from the value's magnitude (`percentDisplayValue`'s old body), so a
+ * fraction-stored `1` read `1%` here and `100%` in the read-only form.
+ *
+ * FROM `formatPercent(value, precision, locale)` TO
+ * `formatPercent(value, percentScale, precision, locale)`.
+ *
+ * `locale` is the last positional parameter, matching {@link formatNumber} and
+ * {@link formatCurrency}. Callers should pass the tag from
+ * `useDisplayLocale()`.
  *
  * Before objectui#4553 this function took no locale and never touched `Intl`:
  * its whole body was `${percentDisplayValue(value).toFixed(precision)}%`, so it
@@ -59,7 +115,7 @@ export declare function formatNumber(value: number, decimals?: number, locale?:
  * so the grouping and the locale are fixed together: en output MOVES from
  * `1235%` to `1,235%` at four digits and up, and that move is the fix.
  */
-export declare function formatPercent(value: number, precision?: number, locale?: string): string;
+export declare function formatPercent(value: number, percentScale: PercentScale, precision?: number, locale?: string): string;
 /**
  * Humanize a snake_case or kebab-case string into Title Case — the fallback
  * label when no explicit `option.label` exists.
@@ -76,41 +132,20 @@ export declare function formatPercent(value: number, precision?: number, locale?
  * `humanizeFieldKey`'s camelCase-splitting KEY convention.
  */
 export { humanizeLabel };
-/** Options shared by {@link formatDate} / {@link formatRelativeDate}. */
-export interface DateDisplayOptions {
-    dueLike?: boolean;
-    /** BCP-47 display locale (ADR-0053 tenant default); falls back to the runtime locale. */
-    locale?: string;
-    /** i18n translate fn for phrases `Intl` can't produce (the "Overdue Nd" wording). */
-    t?: (key: string, params?: Record<string, unknown>) => string;
-}
 /**
- * Format date as relative time (e.g., "3 days ago", "Today", "Overdue 3d"),
- * localized via `Intl.RelativeTimeFormat` (objectstack-ai/objectstack#3040).
+ * The date/datetime display path - `@object-ui/core`'s `utils/date-display.ts`
+ * (objectui#7178), re-exported here under its original names so every existing
+ * consumer of `@object-ui/fields` is unchanged.
  *
- * `dueLike` gates the "Overdue" wording — a past `start_date`/`created_at`
- * isn't overdue, only a past due/deadline-semantic field is. Non-due-like
- * past dates render as plain "N days ago" instead. The overdue phrase has no
- * `Intl` equivalent, so it resolves through `options.t` (key
- * `fields.relativeDate.overdue`) with an English fallback.
+ * It moved for the reason `formatDisplayNumber` moved in objectui#4576: this
+ * barrel is a React package, and the React-free engine could not import from
+ * it. `core`'s `formatMeasure` needed this exact path - a dataset measure over
+ * a date field was rendering its raw ISO string - and the alternative to
+ * moving was a second date convention in `dataset-format.ts`, which is the
+ * drift #4576 already paid for once with percent.
  */
-export declare function formatRelativeDate(value: string | Date | number, options?: DateDisplayOptions): string;
-/**
- * Format date value
- */
-export declare function formatDate(value: string | Date | number, style?: string, options?: DateDisplayOptions): string;
-/**
- * Format datetime value.
- *
- * `options` mirrors {@link formatDate}'s and is optional, so an existing
- * caller that passes nothing keeps the exact runtime-default behavior it had.
- * Before objectui#4272 the parameter did not exist at all, which meant no
- * caller could localize this function however hard it tried — it always handed
- * `Intl` an `undefined` tag, i.e. the MACHINE's locale, which is neither of
- * the repo's two locale channels. Callers should pass the tag from
- * `useDisplayLocale()`.
- */
-export declare function formatDateTime(value: string | Date | number, options?: DateDisplayOptions): string;
+export { formatDate, formatDateTime, formatDateTimeCompactParts, formatRelativeDate };
+export type { DateDisplayOptions };
 /**
  * Text field cell renderer
  */
@@ -136,11 +171,11 @@ export declare function BooleanCellRenderer({ value, field }: CellRendererProps)
 /**
  * Date field cell renderer
  */
-export declare function DateCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+export declare function DateCellRenderer({ value, field, deadlineSettled }: CellRendererProps): React.ReactElement;
 /**
  * DateTime field cell renderer (Airtable-style with date and time visually separated)
  */
-export declare function DateTimeCellRenderer({ value }: CellRendererProps): React.ReactElement;
+export declare function DateTimeCellRenderer({ value, field, deadlineSettled }: CellRendererProps): React.ReactElement;
 /** The six pill colors plus the two dot colors derived from one declared hex. */
 export interface HexBadgePalette {
     bg: string;
@@ -245,44 +280,201 @@ export declare function ImageCellRenderer({ value }: CellRendererProps): React.R
  * Display order:
  * 1. Embedded record object (`{ id, name, ... }` from `$expand`) → use its name
  * 2. Static `field.options[]` (e.g. when the lookup is a closed enum) → look up label
- * 3. Fetch-on-demand: when the value is a primitive ID and `field.reference_to`
+ * 3. Fetch-on-demand: when the value is a primitive ID and `field.reference`
  *    is known, resolve via dataSource and show the related record's display name.
- *    Falls back to a muted placeholder while pending and on failure.
+ * 4. Nothing named it → the unresolved-reference affordance (objectui#8695):
+ *    the raw value, kept visible, beside a stated epistemic marker. This arm
+ *    used to be two — a muted `—` for opaque-LOOKING strings and confident
+ *    bare text for everything else — which answered one state two ways.
  *
  * Record → name resolution (1 and 3) goes through the referenced object's
  * schema when the data source exposes it (`displayField` → nameField/titleFormat
  * → derivation, see {@link resolveLookupRecordName}), so the chip and the
- * picker agree (issue #2357).
+ * picker agree (issue #2357) — and, like the picker's option label, it reads
+ * only the fields the viewer may read on the referenced object
+ * (objectui#10501).
  */
 export declare function LookupCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
 /**
- * Formula field cell renderer (read-only)
+ * Formula field cell renderer (read-only). `summary` is registered to it too.
+ *
+ * The TABLE face of a formula; `FormulaField`'s read-only branch is its FORM
+ * face, and the two read one rule (objectui#11748): the declared `returnType`,
+ * or, with none, a JS number as a number and anything else as text. Each type
+ * is then drawn through the calls the matching field type's faces make, so
+ * one stored value reads the same in the form and in the table. The rule is
+ * spelled in both modules because this barrel and the lazily loaded widget may
+ * not import each other; `__tests__/formulaFaces.returnType-11748.test.tsx`
+ * compares the two faces' text for every declared type.
+ */
+export declare function FormulaCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
+/**
+ * The shipped PRESENTATION of an unresolved reference, shared by the two
+ * renderers that state one (objectui#8434 for `user`, objectui#8695 for
+ * `lookup` / `master_detail` / `tree`), and published for the host faces of the
+ * widget-hinted reference keys (objectui#12613), which draw the same state.
+ *
+ * Only the drawing is shared. Each caller keeps its own literal i18n key and
+ * its own English fallback, because a key reaching this component as a prop
+ * would be a key `check:i18n-keys` can no longer judge — and because the two
+ * sentences are genuinely different claims: one is about a person, the other
+ * about a record of whatever object the lookup points at.
+ *
+ * ⚠️ No `pointer-events-none` here, unlike `EmptyValue`: that utility stops the
+ * span being a hit target, so a `title` on it never renders a tooltip
+ * (objectui#8506). The stated sentence has to be reachable by hovering.
+ *
+ * ⚠️ `truncate` on the inner span rather than the outer one, and the outer is
+ * `inline-flex`: `overflow: hidden` gives a flex item an automatic minimum
+ * size of zero, so the text shrinks and ellipsises instead of forcing the row
+ * wider. The full value stays reachable through the `title` sentence, which
+ * names it — that is how this shape meets objectui#3466's truncation contract
+ * (a single-line value must never expand its column and must expose its full
+ * text) with an icon in front of the text.
  */
-export declare function FormulaCellRenderer({ value }: CellRendererProps): React.ReactElement;
+export declare function UnresolvedReferenceMark({ raw, hint, className, }: {
+    raw: string;
+    hint: string;
+    className?: string;
+}): React.ReactElement;
 /**
  * User/Owner field cell renderer (with avatars)
+ *
+ * The name and the avatar are DISPLAY values, so each person row is drawn as
+ * the viewer may read it (objectui#10535): with a loaded policy, the fields it
+ * denies on the person's object are removed first ({@link withoutDeniedFields},
+ * `id` kept), and everything below reads that row — exactly as it reads the
+ * row a stripping backend serves. The person's object is the field's
+ * `reference`, and `sys_user` when it names none: the object `UserField`
+ * points the picker at.
  */
-export declare function UserCellRenderer({ value }: CellRendererProps): React.ReactElement;
+export declare function UserCellRenderer({ value, field }: CellRendererProps): React.ReactElement;
 /**
  * Register a custom field renderer
  * @param type Field type (e.g. 'text', 'location', 'my-custom-type')
  * @param renderer React component to render the field
  */
 export declare function registerFieldRenderer(type: string, renderer: React.FC<CellRendererProps>): void;
+/**
+ * ## Polymorphic pointer pairs: `referenceVia` (objectui#12045)
+ *
+ * `@objectstack/spec`'s `FieldSchema.referenceVia` declares a `text` field as
+ * the ID HALF of a two-column pointer pair (ADR-0052 §5): its value is a
+ * record id of the object that the SIBLING column names, on the same row.
+ * `sys_approval_request.record_id` with `referenceVia: 'object_name'` is one;
+ * `sys_activity.source_id` with `referenceVia: 'source_object'` is another.
+ *
+ * The target object varies per ROW, so the pair is resolved where the row is
+ * in hand, at the call site. {@link CellRendererProps} carries one value and no
+ * row, which is why this is a function a call site asks and not a branch inside
+ * {@link getCellRenderer}, whose dispatch stays on the field type alone.
+ *
+ * ⭐ This is the one place the rule lives. A call site that holds the row asks
+ * `resolveRecordPointer(field, row, optionsOf)`, and draws a pair it gets back
+ * with the renderer registered under {@link RECORD_POINTER_CARD_TYPE}, passing
+ * the pair as that renderer's `value`. The same call answers whether the
+ * platform asserted the target deleted on this row (`referenceDeletedWhen`,
+ * objectui#12489), so no face and no call site evaluates that predicate. This package registers a default under that key
+ * which draws the record id as text, exactly as the field drew before its pair
+ * was read, so a host with nothing better changes nothing. A host that can read
+ * records registers a richer face under the same key with
+ * {@link registerFieldRenderer}: `@object-ui/app-shell` registers its record
+ * preview card there.
+ *
+ * Two call sites ask it. The record details grid (`DetailSection` in
+ * `@object-ui/plugin-detail`) draws the pair with the renderer registered under
+ * {@link RECORD_POINTER_CARD_TYPE}. The list grid (`ObjectGrid` in
+ * `@object-ui/plugin-grid`, objectui#12608) draws it with its own cell face,
+ * not with that renderer: a face that reads its target one record at a time
+ * costs one request per row in a list, so the list face batches the page's
+ * targets into one read per object.
+ */
+export declare const RECORD_POINTER_CARD_TYPE = "record_pointer_card";
+/** One resolved pointer pair: the record a `referenceVia` field points at. */
+export interface RecordPointer {
+    /** The target's object machine name: the sibling column's value. */
+    objectName: string;
+    /** The target's record id: the pointer field's own value. */
+    recordId: string;
+    /**
+     * Present only when the platform asserted, on this row, that the target was
+     * deleted (the field's `referenceDeletedWhen` predicate holds, objectui#12489):
+     * the label of the declared option that says so, as the call site's option
+     * labels spell it. A face that receives it draws the tombstone in this text,
+     * reads nothing and links nothing. Absent on every other row, and a face
+     * then draws the pair as before.
+     */
+    deletedLabel?: string;
+}
+/**
+ * `@objectstack/spec`'s `FieldSchema.referenceDeletedWhen`: the sibling
+ * `select` field, and the one option of it, that the platform writes on a row
+ * whose pointed-at record it deleted. The spec refuses it at parse unless the
+ * field declares `referenceVia`, `field` is a single-value `select` of the same
+ * object declaring inline `options`, and `value` is one of those options.
+ */
+type ReferenceDeletedWhen = {
+    readonly field: string;
+    readonly value: string;
+};
+/** The call site's option list for one field: what `select` cells draw with. */
+type OptionsOf = (fieldName: string) => ReadonlyArray<{
+    readonly value?: unknown;
+    readonly label?: unknown;
+}> | null | undefined;
+/**
+ * Resolve the record a `referenceVia` pointer field points at on one row, or
+ * `null` when the field is not a pointer or the row does not address a record.
+ *
+ * - `field` must be a `text` field declaring a non-empty `referenceVia`; the
+ *   spec refuses the key on every other type, so nothing else qualifies here.
+ * - The pair is read from `row`: the id under the field's own name, the object
+ *   name under the sibling column the field names.
+ * - Both halves must be non-blank strings. A half-addressed row is not a
+ *   pointer this can draw, and the caller falls back to the field's ordinary
+ *   face (the stored text).
+ *
+ * ## A deletion the platform asserts: `referenceDeletedWhen` (objectui#12489)
+ *
+ * When the field also declares `referenceDeletedWhen: { field, value }` and
+ * this row's sibling `field` holds exactly `value`, the pair comes back with
+ * `deletedLabel`: the label of that declared option, looked up in
+ * `optionsOf(field)`. The call site supplies `optionsOf` because it holds the
+ * object definition and the option labels the rest of its grid draws with
+ * (localized ones included), so the tombstone and the sibling `select`'s own
+ * cell say the same thing.
+ *
+ * - Only the declared assertion marks a target deleted. A target read that
+ *   fails or answers no record says nothing about why: the platform answers a
+ *   deleted record and one outside the reader's row set alike, on purpose.
+ * - No `optionsOf`, or no option with that value among the sibling's options,
+ *   means no label to draw, and the pair comes back without `deletedLabel`.
+ *   The spec refuses a predicate whose value is not a declared option, so the
+ *   second case is not reachable from spec-valid metadata. ⛔ Never the raw
+ *   option value as the text: the tombstone is the option's own label.
+ */
+export declare function resolveRecordPointer(field: {
+    readonly name: string;
+    readonly type?: string | null;
+    readonly referenceVia?: string | null;
+    readonly referenceDeletedWhen?: ReferenceDeletedWhen | null;
+} | null | undefined, row: Readonly<Record<string, unknown>> | null | undefined, optionsOf?: OptionsOf): RecordPointer | null;
 /**
  * Resolve the canonical cell-renderer key for a field. Accepts either a
  * raw type string (back-compat) or a field-metadata object so that
  * format hints (`format: 'phone'` etc.) can promote a plain `text`
- * field to its richer renderer counterpart.
+ * field to its richer renderer counterpart, and a declared `widget` with
+ * a read cell of its own (`WIDGET_CELL_RENDERER_TYPES`) to that cell.
  */
 export declare function resolveCellRendererType(fieldOrType: string | {
     type?: string;
     format?: string;
+    widget?: string;
 } | null | undefined): string;
 /**
- * Renders structured/embedded values (json, object, composite, record,
- * address, geolocation) as compact, readable JSON. Objects and arrays are
- * stringified; primitives fall through to their string form.
+ * Renders a free-form JSON value (`json`, `object`) as compact, readable JSON,
+ * and is the fallback face for a shape a structured renderer cannot recognize
+ * (`location` / `geolocation`, `address`, `composite` / `record`).
  */
 export declare function JsonCellRenderer({ value }: CellRendererProps): React.ReactElement;
 /**
@@ -293,12 +485,13 @@ export declare function ColorSwatchCellRenderer({ value }: CellRendererProps): R
  * The rich-content display pipelines — `markdown` through the GFM renderer,
  * `html`/`richtext` through the sanitizing HTML renderer — live in
  * `./widgets/richTextDisplay.js` rather than here, so `RichTextField` can
- * import them without importing this barrel back (objectui#5498). Re-exported
+ * import them without importing this barrel back (`4bb940b6e`). Re-exported
  * unchanged: they are part of this package's published surface, and
  * `RICH_TEXT_CELL_RENDERERS` below is the one table both the cell resolver and
  * the widget's readonly branch read.
  */
 export { MarkdownCellRenderer, HtmlCellRenderer } from './widgets/richTextDisplay.js';
+export { RICH_TEXT_FIELD_TYPES, type RichTextFieldType } from './widgets/richTextDisplay.js';
 /**
  * Renders a `location`/`geolocation` value as readable coordinates with a pin.
  * Accepts `{ lat, lng }` / `{ latitude, longitude }`, a `"lat,lng"` string,
@@ -325,6 +518,136 @@ export declare function LocationCellRenderer({ value }: CellRendererProps): Reac
  * is never silently swallowed by the fix.
  */
 export declare function AddressCellRenderer({ value }: CellRendererProps): React.ReactElement;
+/**
+ * `password` / `secret` cell renderer: the mask for a credential that is SET,
+ * and the shared affordance for one that is NOT (objectui#8678).
+ *
+ * The entry this replaces was an argument-less arrow that drew the mask for
+ * every input, `null` included. On screen, a credential that was never set was
+ * then drawn exactly like one that is set. The platform's read contract is
+ * presence-preserving on purpose: `@objectstack/spec`'s `SECRET_MASK` docblock
+ * says an unset credential "reads back `null` instead, never this mask", which
+ * is what lets a console render "configured" vs "not configured" at all. This
+ * cell threw that distinction away one step before the reader saw it.
+ *
+ * ⛔ The value is NEVER printed and never reaches the DOM. Only its presence is
+ * read. A populated value keeps the exact mask it drew before this card, and
+ * nothing here is a weaker mask.
+ *
+ * "Empty" is the string class's answer, since both types are
+ * `STRING_VALUE_TYPES` members in the spec: `TextCellRenderer`'s predicate
+ * exactly, the floor on the coerced text. `{}` therefore stays a VALUE and
+ * keeps the mask, per objectui#8596's string-class ruling ("the record IS
+ * storing something"). A whitespace-only string also keeps it, because `text`
+ * keeps its spaces and a blank credential is still a set one.
+ * `cellRenderers.valueIndependent-8678` pins this byte-equal to `text` for
+ * every empty input.
+ *
+ * ⭐ A NAMED module-level component, for the reason {@link RepeaterCellRenderer}
+ * states: `EmptyValue` holds a hook, and an inline arrow in the table below
+ * is a new component type on every resolution, so it would tear that hook down
+ * per render.
+ *
+ * Exported (objectui#10657) for the cell a producer cannot type yet. While an
+ * object-bound table is still waiting for its object's field types, or after
+ * that read failed, a column with no type of its own could be a credential,
+ * so `ObjectGrid`, `RelatedList` and `ObjectDataTable` draw it WITHHELD: as
+ * this mask, never as text. It is this component and not the live registry
+ * entry for `password`, so a host override of a masked type cannot change what
+ * a withheld cell draws. Registering it for a type
+ * (`registerFieldRenderer('api_token', MaskedCellRenderer)`) masks that type,
+ * as {@link isMaskedFieldType} describes. `field` is optional: the mask reads
+ * only whether the value is present, so a withheld cell has no field metadata
+ * to invent.
+ */
+export declare function MaskedCellRenderer({ value, }: Omit<CellRendererProps, 'field'> & {
+    field?: CellRendererProps['field'];
+}): React.ReactElement;
+/**
+ * The field types this package DECLARES masked: their standard cell is
+ * {@link MaskedCellRenderer}, which draws `••••••` in place of the value
+ * (objectui#8686). The read-side twin of the credential entry in
+ * `INLINE_EXCLUDED_FIELD_TYPES`, which lives in `FieldEditWidget`.
+ *
+ * ⭐ This set BUILDS the table's masked entries — `buildStandardCellRendererMap`
+ * spreads one {@link MaskedCellRenderer} entry per member — so adding a type
+ * here masks its cell AND makes {@link isMaskedFieldType} answer `true` for it,
+ * in one edit. There is no second list to keep in step.
+ *
+ * ⚠️ Membership answers "what ships masked", ⛔ not "what is masked right now":
+ * `registerFieldRenderer` can add or replace a masked type at runtime, and a
+ * set cannot see that. Consumers deciding what to do with a cell's value ask
+ * {@link isMaskedFieldType}.
+ *
+ * RAW spellings, deliberately: the cell path does not resolve form aliases
+ * (`getCellRenderer` is an exact-key lookup), so `field:password` renders in
+ * the clear and is not a member.
+ *
+ * Owned here for now. The objectui#8686 ruling made the protocol the first
+ * place to look: if `@objectstack/spec` comes to declare which field types are
+ * credentials, this set derives from that declaration instead of listing types.
+ */
+export declare const MASKED_FIELD_TYPES: ReadonlySet<string>;
+/**
+ * Is a cell of this field type drawn as a mask instead of as its value? The
+ * one authority for that question (objectui#8686): ask it rather than keep a
+ * list of types. The read-side twin of `isInlineExcludedFieldType()`.
+ *
+ * A LIVE reading of the cell registry, taken at call time, in the order
+ * {@link getCellRenderer} resolves: the runtime registry first, then the
+ * standard table.
+ *
+ *  1. The type resolves to THE mask ({@link MaskedCellRenderer}) → `true`,
+ *     declared or not. That is how a host adds a masked type:
+ *     `registerFieldRenderer('api_token', getCellRenderer('password'))`.
+ *  2. Otherwise, a type outside {@link MASKED_FIELD_TYPES} → `false`.
+ *  3. A declared type whose mask a host REPLACED at runtime
+ *     (`registerFieldRenderer('password', X)`) → the override is read:
+ *     - X is one of this package's own cell renderers → `false`. None of them
+ *       is the mask, so the predicate answers `false` and the cell draws what
+ *       X draws (for `TextCellRenderer`, the value).
+ *     - X is the host's own component → `true`, the declared answer. Nothing
+ *       here can tell whether an opaque component masks. Answering `false`
+ *       would offer a credential to anything that trusts this predicate
+ *       (the detail page's copy affordance, objectui#8440) while a custom mask
+ *       hides it on screen. So an unreadable override falls back to the
+ *       declared set, on the side that withholds.
+ *
+ * RAW spelling, no alias resolution, for the reason {@link MASKED_FIELD_TYPES}
+ * states. Side-effect free, like `isInlineExcludedFieldType()`: unlike
+ * {@link getCellRenderer}, it never reports a retired spelling.
+ */
+export declare function isMaskedFieldType(fieldType: string | undefined): boolean;
+/**
+ * Every field type that resolves to a cell renderer OF ITS OWN — a LIVE
+ * reading of the registry, taken when you call it (objectui#8734).
+ *
+ * ## Why this exists
+ *
+ * Two censuses — `cellRenderers.objectLiteral-8596` in this package and
+ * `summaryChip.badgeFitCensus-8464` in `@object-ui/plugin-detail` — declare in
+ * prose that they measure "every type `getCellRenderer` resolves to a renderer
+ * of its own", and each enforced that declaration with a hard-coded population
+ * size. A newly registered type is absent from such a table, so every row in it
+ * still passes: the census goes on measuring a snapshot while claiming to
+ * measure the registry. This function is what those censuses reconcile against,
+ * so a new type turns a silent pass into a red row that NAMES the type.
+ *
+ * ## ⭐ A function, ⛔ not a frozen constant
+ *
+ * `FORM_FIELD_TYPES` next door may be `Object.freeze(Object.keys(...))` because
+ * `fieldWidgetMap` is a module literal that never changes. This registry DOES
+ * change: {@link registerFieldRenderer} is published, and a host may add or
+ * override a type after this module is evaluated. A frozen constant here would
+ * be a snapshot taken at import time — the very defect the censuses are being
+ * repaired for, one level down. Every call re-reads.
+ *
+ * The answer is the UNION of the runtime registry and the standard table,
+ * because {@link getCellRenderer} dispatches on both; it is sorted so callers
+ * get a stable order, and `TextCellRenderer` is the TOTAL fallback for
+ * everything else, which is exactly why "everything else" is not listed here.
+ */
+export declare function listCellRendererTypes(): readonly string[];
 /**
  * Get the appropriate cell renderer for a field type
  */
@@ -341,6 +664,14 @@ export declare function formatFileSize(bytes: number): string;
  * Build validation rules from field metadata
  * @param field - Field metadata from ObjectStack
  * @returns Validation rule object compatible with react-hook-form
+ *
+ * ⛔ No field-level `pattern` / `pattern_message` / `validate` (objectui#12242,
+ * maintainer ruling A). `@objectstack/spec`'s `FieldSchema` refuses all three
+ * by name, so no published object carries them, and the field metadata types
+ * retire them as `never`. A regex check is the OBJECT's `format` validation
+ * rule (`validations[]`), which the server runs on every write that touches
+ * the field and refuses with the rule's message; this function adds no client
+ * pre-check of it.
  */
 export declare function buildValidationRules(field: any): any;
 /**
@@ -379,12 +710,12 @@ declare const fieldWidgetMap: {
     date: () => Promise<{
         default: React.ComponentType<any>;
     } | {
-        default: typeof import('./widgets/DateField.js').DateField;
+        default: typeof import('./widgets/date-picker/DatePickerField.js').DatePickerField;
     }>;
     datetime: () => Promise<{
         default: React.ComponentType<any>;
     } | {
-        default: typeof import('./widgets/DateTimeField.js').DateTimeField;
+        default: typeof import('./widgets/date-picker/DatePickerField.js').DateTimePickerField;
     }>;
     time: () => Promise<{
         default: React.ComponentType<any>;
@@ -576,6 +907,16 @@ declare const fieldWidgetMap: {
     } | {
         default: typeof import('./widgets/RecipientPickerField.js').RecipientPickerField;
     }>;
+    'position-ref': () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/RegistryRefField.js').PositionRefField;
+    }>;
+    'permission-ref': () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/RegistryRefField.js').PermissionRefField;
+    }>;
 };
 /** The registered field widget keys, as a literal union (objectui#4857). */
 export type RegisteredFieldWidgetType = keyof typeof fieldWidgetMap;
@@ -610,6 +951,23 @@ export declare function resolveFormWidgetType(fieldType: string): string;
  * which converged the three private copies that preceded it).
  */
 export { CASCADE_OPTION_WIDGET_TYPES } from '@object-ui/core';
+/**
+ * The ONE action-param resolver (objectui#12105): a declared action param —
+ * inline, or field-backed via `{ field, objectOverride }` — resolved against
+ * the object's field definitions into the `ActionParamDef` a param dialog
+ * renders. Exported from here because this is the package both of its callers
+ * depend on: app-shell's single-record `ActionParamDialog` and plugin-grid's
+ * selection-bar bulk dialog (a promoted action's params). See the module.
+ */
+export { resolveActionParam, resolveActionParams, resolveParamWidgetType, withKnownObjects, RESOLVED_ONLY_PARAM_KEYS, } from './resolveActionParams.js';
+export type { RawActionParam, RawActionParamOption, ResolveActionParamsContext, } from './resolveActionParams.js';
+/**
+ * The ONE read of a field definition's help line (objectui#12213):
+ * `inlineHelpText`, else `description`. Exported from here because both of its
+ * readers can reach this package: `@object-ui/plugin-form`'s record form and
+ * this package's own `resolveActionParam`. See the module.
+ */
+export { fieldHelpText } from './fieldHelpText.js';
 /**
  * Lazily-loaded form field widget for a field type. Shares the exact loaders
  * of {@link fieldWidgetMap} (the same components `registerField` registers for
@@ -621,7 +979,7 @@ export { CASCADE_OPTION_WIDGET_TYPES } from '@object-ui/core';
 export declare function getLazyFieldWidget(fieldType: string): React.ComponentType<any>;
 /**
  * The labelling declaration of EVERY registered field widget
- * (`ComponentMeta.labelling` — the closed `'control' | 'group' | 'display'`
+ * (`RegistryComponentMeta.labelling` — the closed `'control' | 'group' | 'display'`
  * vocabulary, objectui#3961 extended by objectui#4857). This `Record` is keyed
  * by the widget map's own literal key union, so it is exhaustive BY
  * CONSTRUCTION: registering a widget without deciding how a host's label
@@ -671,7 +1029,7 @@ export declare function getLazyFieldWidget(fieldType: string): React.ComponentTy
  * out-of-registry widgets alike; the entry here is still mandatory, because
  * "defaulted by omission" and "decided to be the default" are different facts.
  */
-export declare const FIELD_WIDGET_LABELLING: Record<RegisteredFieldWidgetType, NonNullable<ComponentMeta['labelling']>>;
+export declare const FIELD_WIDGET_LABELLING: Record<RegisteredFieldWidgetType, NonNullable<RegistryComponentMeta['labelling']>>;
 export declare function registerField(fieldType: string): void;
 /**
  * Register all field types (for backward compatibility)
@@ -694,6 +1052,17 @@ export declare function registerField(fieldType: string): void;
  * nothing is silently substituted either, which is the whole point: the author
  * sees a refusal where they expected an input, not a text box that looks like
  * it worked.
+ *
+ * The spelling it names is `retiredFieldType` — the key the RESOLVER answered
+ * with this tombstone — and is re-derived from the field only when a host
+ * renders the tombstone directly without one (objectui#10471). The field is
+ * the wrong witness whenever the retired spelling arrived through a different
+ * key than `field.type`: an authored `widget` wins over `type` in both form
+ * hosts, so `{ type: 'user', widget: 'owner' }` reaches the `owner` tombstone
+ * carrying a `user` field, and deriving from it named the LIVE type as
+ * retired, lost the prescription, and logged nothing. The two resolvers fill
+ * the prop by binding it ({@link retiredFieldTombstoneFor}); a host whose key
+ * IS `field.type` (plugin-detail's inline editor) may keep omitting it.
  */
 export declare const RetiredFieldTombstone: React.FC<Record<string, any>>;
 export declare function registerAllFields(): void;
@@ -703,6 +1072,7 @@ export * from './FieldEditWidget.js';
 export * from './widgets/TextField.js';
 export * from './widgets/NumberField.js';
 export * from './widgets/BooleanField.js';
+export { useBooleanValueLabel, type BooleanValueLabel } from './widgets/booleanValueLabel.js';
 export * from './widgets/SelectField.js';
 export * from './widgets/DateField.js';
 export * from './widgets/DateTimeField.js';
@@ -720,6 +1090,8 @@ export * from './widgets/CapabilityMultiSelectField.js';
 export * from './widgets/ObjectRefField.js';
 export * from './widgets/FilterConditionField.js';
 export * from './widgets/RecipientPickerField.js';
+export { objectRefOptionLabel } from './widgets/objectRefLabel.js';
+export { RECIPIENT_RECORD_KINDS, RECIPIENT_REGISTRY_KINDS, FIELD_RECIPIENT_TYPE, recipientCandidateLabel, } from './widgets/recipientKinds.js';
 export * from './widgets/RecordPickerDialog.js';
 export * from './widgets/deriveLookupColumns.js';
 export * from './widgets/FileField.js';
@@ -750,5 +1122,10 @@ export * from './widgets/CheckboxesField.js';
 export * from './widgets/TagsField.js';
 export { withFieldCarrier } from './withFieldCarrier.js';
 export { toDomProps } from './widgets/toDomProps.js';
-export type { DomProps } from './widgets/toDomProps.js';
+export type { FieldDomProps } from './widgets/toDomProps.js';
+export { toHostProps } from './widgets/toHostProps.js';
+export type { HostProps } from './widgets/toHostProps.js';
 export { toDateInputValue, toDateTimeInputValue, fromDateTimeInputValue, } from './widgets/nativeDateValue.js';
+export { useUploadingScope, UploadingScopeProvider } from './widgets/uploadingScope.js';
+export { useUploadingSignal } from './widgets/useUploadingSignal.js';
+export type { UploadingScope } from './widgets/uploadingScope.js';