@object-ui/fields 17.5.0 → 17.7.0

package/dist/index.d.ts

@@ -1,6 +1,9 @@
 import { default as React } from 'react';
 import { FieldMetadata } from '@object-ui/types';
-import { resolveFieldCurrency } from './currency';
+import { PercentScale, humanizeLabel, formatDate, formatDateTime, formatDateTimeCompactParts, formatRelativeDate, ComponentMeta, 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.
  * Tries common name-like keys in priority order, then falls back to undefined.
@@ -8,8 +11,18 @@ import { resolveFieldCurrency } from './currency';
 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,15 +34,18 @@ export interface CellRendererProps {
     isEditing?: boolean;
     onChange?: (value: any) => void;
 }
+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
@@ -37,18 +53,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
@@ -58,52 +92,37 @@ 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.
- * Used as fallback label when no explicit option.label exists.
+ * Humanize a snake_case or kebab-case string into Title Case — the fallback
+ * label when no explicit `option.label` exists.
  *
- * Examples:
- *   "in_progress" → "In Progress"
- *   "high-priority" → "High Priority"
- *   "active" → "Active"
- */
-export declare function humanizeLabel(value: string): string;
-/** 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).
- *
- * `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.
- */
-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.
+ * Defined in `@object-ui/core` (`utils/humanize-label.ts`) and re-exported here
+ * because this package is one of its two doorways: `plugin-grid`,
+ * `plugin-gantt` and `plugin-detail` read it from `@object-ui/fields`, while
+ * `plugin-charts` reads the same function straight from core. Until
+ * objectui#5444 this file and `plugin-charts`' `ObjectChart.tsx` each held a
+ * byte-identical private copy; core is the shared ancestor both packages
+ * already depend on, so the convention has one home and no new dependency edge
+ * (objectui#4389: core-canonical logic, plugins consume). The core docstring
+ * carries the convention itself, and the reason it stays distinct from
+ * `humanizeFieldKey`'s camelCase-splitting KEY convention.
+ */
+export { humanizeLabel };
+/**
+ * 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.
  *
- * `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()`.
+ * 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 formatDateTime(value: string | Date | number, options?: DateDisplayOptions): string;
+export { formatDate, formatDateTime, formatDateTimeCompactParts, formatRelativeDate };
+export type { DateDisplayOptions };
 /**
  * Text field cell renderer
  */
@@ -133,7 +152,44 @@ export declare function DateCellRenderer({ value, field }: CellRendererProps): R
 /**
  * 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 }: CellRendererProps): React.ReactElement;
+/** The six pill colors plus the two dot colors derived from one declared hex. */
+export interface HexBadgePalette {
+    bg: string;
+    fg: string;
+    border: string;
+    bgDark: string;
+    fgDark: string;
+    borderDark: string;
+    dot: string;
+    dotDark: string;
+}
+/**
+ * Derive a full soft-pill palette from an author-declared hex.
+ *
+ * The declared LIGHTNESS is what separates two same-hue tiers (`#2ecc71` is
+ * l=0.49, `#1e8449` is l=0.32 — their hues differ by 0.1°), so it has to
+ * survive into the *surface*. A fixed pale tint — the obvious reading of
+ * "compute a soft pill from the hex" — does not carry it: measured, that
+ * leaves the reported pair ΔE 2.3 apart in Lab, at the ~2.3 just-noticeable
+ * threshold, which would close this issue on paper while the user still cannot
+ * tell the two badges apart. Letting the tint depth track the declared
+ * lightness puts them ΔE 8.0 apart instead.
+ */
+export declare function deriveHexBadgePalette(color: string): HexBadgePalette | undefined;
+/** A className plus the custom properties it reads. */
+export interface HexColorAppearance {
+    className: string;
+    style: React.CSSProperties;
+}
+/**
+ * Soft-pill appearance for an explicitly declared hex, or `undefined` for
+ * every other kind of declaration (family name, no colour at all) so the
+ * caller falls back to `getBadgeColorClasses`.
+ */
+export declare function getBadgeHexAppearance(color?: string): HexColorAppearance | undefined;
+/** Dot appearance for an explicitly declared hex (see `getBadgeHexAppearance`). */
+export declare function getDotHexAppearance(color?: string): HexColorAppearance | undefined;
 export declare function getBadgeColorClasses(color?: string, val?: unknown): string;
 /**
  * Resolve a semantic color name (e.g. "red", "green") for a value, suitable
@@ -201,14 +257,19 @@ 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;
 /**
@@ -217,8 +278,16 @@ export declare function LookupCellRenderer({ value, field }: CellRendererProps):
 export declare function FormulaCellRenderer({ value }: CellRendererProps): 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')
@@ -246,14 +315,16 @@ export declare function JsonCellRenderer({ value }: CellRendererProps): React.Re
  */
 export declare function ColorSwatchCellRenderer({ value }: CellRendererProps): React.ReactElement;
 /**
- * Renders `markdown` / `richtext` values as formatted GFM markdown (lazy-loaded,
- * sanitized) instead of the raw markup string.
- */
-export declare function MarkdownCellRenderer({ value }: CellRendererProps): React.ReactElement;
-/**
- * Renders an `html` value as sanitized, formatted HTML instead of raw markup.
+ * 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 (`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 declare function HtmlCellRenderer({ value }: CellRendererProps): React.ReactElement;
+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,
@@ -280,11 +351,142 @@ 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
  */
 export declare function getCellRenderer(fieldType: string): React.FC<CellRendererProps>;
-export { mapFieldTypeToFormType } from './field-type-alias';
+export { mapFieldTypeToFormType } from './field-type-alias.js';
+export { RETIRED_FIELD_TYPES, isRetiredFieldType, reportRetiredFieldType, resetRetiredFieldTypeReports, } from './field-type-alias.js';
 /**
  * Formats file size in bytes to human-readable string
  * @param bytes - File size in bytes (must be non-negative)
@@ -304,6 +506,235 @@ export declare function buildValidationRules(field: any): any;
  * @returns Whether the condition is met
  */
 export declare function evaluateCondition(condition: any, formData: any): boolean;
+declare const fieldWidgetMap: {
+    text: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/TextField.js').TextField;
+    }>;
+    textarea: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/TextAreaField.js').TextAreaField;
+    }>;
+    number: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/NumberField.js').NumberField;
+    }>;
+    boolean: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/BooleanField.js').BooleanField;
+    }>;
+    select: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/SelectField.js').SelectField;
+    }>;
+    date: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/DateField.js').DateField;
+    }>;
+    datetime: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/DateTimeField.js').DateTimeField;
+    }>;
+    time: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/TimeField.js').TimeField;
+    }>;
+    email: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/EmailField.js').EmailField;
+    }>;
+    phone: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/PhoneField.js').PhoneField;
+    }>;
+    url: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/UrlField.js').UrlField;
+    }>;
+    multiselect: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/MultiSelectField.js').MultiSelectField;
+    }>;
+    radio: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/RadioField.js').RadioField;
+    }>;
+    checkboxes: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/CheckboxesField.js').CheckboxesField;
+    }>;
+    tags: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/TagsField.js').TagsField;
+    }>;
+    currency: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/CurrencyField.js').CurrencyField;
+    }>;
+    percent: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/PercentField.js').PercentField;
+    }>;
+    password: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/PasswordField.js').PasswordField;
+    }>;
+    markdown: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/RichTextField.js').RichTextField;
+    }>;
+    html: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/RichTextField.js').RichTextField;
+    }>;
+    richtext: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/RichTextField.js').RichTextField;
+    }>;
+    lookup: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/LookupField.js').LookupField;
+    }>;
+    master_detail: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/LookupField.js').LookupField;
+    }>;
+    file: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/FileField.js').FileField;
+    }>;
+    image: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/ImageField.js').ImageField;
+    }>;
+    location: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/LocationField.js').LocationField;
+    }>;
+    formula: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/FormulaField.js').FormulaField;
+    }>;
+    summary: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/SummaryField.js').SummaryField;
+    }>;
+    auto_number: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/AutoNumberField.js').AutoNumberField;
+    }>;
+    user: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/UserField.js').UserField;
+    }>;
+    object: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/ObjectField.js').ObjectField;
+    }>;
+    vector: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/VectorField.js').VectorField;
+    }>;
+    grid: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/GridField.js').GridField;
+    }>;
+    color: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/ColorField.js').ColorField;
+    }>;
+    slider: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/SliderField.js').SliderField;
+    }>;
+    rating: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/RatingField.js').RatingField;
+    }>;
+    code: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/CodeField.js').CodeField;
+    }>;
+    avatar: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/AvatarField.js').AvatarField;
+    }>;
+    address: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/AddressField.js').AddressField;
+    }>;
+    geolocation: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/GeolocationField.js').GeolocationField;
+    }>;
+    signature: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/SignatureField.js').SignatureField;
+    }>;
+    qrcode: () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/QRCodeField.js').QRCodeField;
+    }>;
+    'object-ref': () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/ObjectRefField.js').ObjectRefField;
+    }>;
+    'filter-condition': () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/FilterConditionField.js').FilterConditionField;
+    }>;
+    'recipient-picker': () => Promise<{
+        default: React.ComponentType<any>;
+    } | {
+        default: typeof import('./widgets/RecipientPickerField.js').RecipientPickerField;
+    }>;
+};
+/** The registered field widget keys, as a literal union (objectui#4857). */
+export type RegisteredFieldWidgetType = keyof typeof fieldWidgetMap;
 /**
  * Every field type the form can render (the canonical list of supported types).
  * Exported so inline editing can be checked against it — a form type must
@@ -323,6 +754,18 @@ export declare const FORM_FIELD_TYPES: readonly string[];
  * support can never drift behind the form surface (ADR-0059).
  */
 export declare function resolveFormWidgetType(fieldType: string): string;
+/**
+ * The widget keys that must be fed the live record (`dependentValues`) so their
+ * offered option set can be re-resolved per option `visibleWhen` / `dependsOn`.
+ *
+ * Defined in `@object-ui/core`, next to `resolveCascadingOptions` — the
+ * evaluator that reads the record — and re-exported here because this is the
+ * package whose {@link resolveFormWidgetType} produces the keys the set is
+ * keyed on: a consumer resolving a widget key finds the allow-table in the
+ * same place. One definition, two doorways; never a second copy (objectui#4770,
+ * which converged the three private copies that preceded it).
+ */
+export { CASCADE_OPTION_WIDGET_TYPES } from '@object-ui/core';
 /**
  * Lazily-loaded form field widget for a field type. Shares the exact loaders
  * of {@link fieldWidgetMap} (the same components `registerField` registers for
@@ -332,6 +775,59 @@ export declare function resolveFormWidgetType(fieldType: string): string;
  * widget via {@link resolveFormWidgetType}.
  */
 export declare function getLazyFieldWidget(fieldType: string): React.ComponentType<any>;
+/**
+ * The labelling declaration of EVERY registered field widget
+ * (`ComponentMeta.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
+ * reaches it is a COMPILE error here, not a silent fall-through to the
+ * `'control'` path — the omitted-declaration degradation is exactly the trap
+ * the #4857 ruling named, and it is what turned the display-only four into
+ * fields with no accessible name.
+ *
+ * ## `'group'` — a surface no `<label for>` can reach; the WIDGET consumes the IDREF
+ *
+ * Two shapes, one declaration:
+ *
+ *  - real composites — `address` / `geolocation` render several inputs under one
+ *    container, `checkboxes` / `radio` / `rating` / `multiselect` a set of
+ *    choice controls, and `grid` a whole table of cell inputs plus row actions;
+ *    the host's label names the GROUP, each sub-control keeps its own name (a
+ *    sub-label, the chip's text content, or a cell's own `aria-label`).
+ *  - single non-labelable controls — `file`'s one control is a
+ *    `div[role="button"]` dropzone, `slider`'s is Radix's `span[role="slider"]`
+ *    thumb (objectui#3318), `signature`'s drawing surface is a `<canvas>`
+ *    (objectui#3318). A `div`/`span`/`canvas` cannot be `for`-labelled, so the
+ *    name goes by IDREF to the control (or, for `signature`, its container).
+ *
+ * Measured, not assumed: every `'group'` entry was verified in a real form —
+ * the #3961/#3975 probes for the first seven, the #3318 delivery for
+ * `slider`/`signature`, and the #4857 re-measurement for `grid` (bare config:
+ * one focusable, the auxiliary "Add line" BUTTON — routing `for` there would
+ * have label clicks INSERT A ROW; realistic config: 8 focusables across cell
+ * inputs and row actions — a composite, not a single control).
+ *
+ * ## `'display'` — a pure display in EVERY state; the HOST wraps (objectui#4857)
+ *
+ * `formula` / `summary` / `auto_number` / `vector` have no editable branch at
+ * all: the whole widget is a replacement display with no focusable control, in
+ * the editable state as much as the readonly one (on the real object-form path
+ * they arrive `disabled`, never `readonly`, so the #4788 readonly gate could
+ * not cover them). The form renderer answers the declaration with its own
+ * wrapper — id + `aria-labelledby` + `aria-describedby` + `role="group"`, the
+ * #4788 container — and the label emits no `for`. The widgets spread nothing,
+ * by design; the host is the named surface.
+ *
+ * ## `'control'` — everything else
+ *
+ * The host's `<label for>` reaches a real labelable element. At registration
+ * this is deliberately spelled as ABSENCE of the meta key (one spelling of the
+ * default, objectui#3961), so hosts keep one rule for these and for
+ * 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 function registerField(fieldType: string): void;
 /**
  * Register all field types (for backward compatibility)
@@ -343,59 +839,88 @@ export declare function registerField(fieldType: string): void;
  * // Register all fields at once
  * registerAllFields();
  */
+/**
+ * The widget a RETIRED field-type spelling renders (objectui#4814).
+ *
+ * Shape borrowed from the form renderer's spec-vocabulary boundary (#3090),
+ * which is this repo's settled answer to "an authored entry this renderer
+ * cannot honour": an inline alert that NAMES the offending entry, plus a
+ * `console.error` whose text doubles as the fix instruction. Nothing is thrown
+ * — one retired field must not take down the rest of a record form — but
+ * 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;
-export * from './widgets/types';
-export * from './widgets/file-value';
-export * from './FieldEditWidget';
-export * from './widgets/TextField';
-export * from './widgets/NumberField';
-export * from './widgets/BooleanField';
-export * from './widgets/SelectField';
-export * from './widgets/DateField';
-export * from './widgets/DateTimeField';
-export * from './widgets/TimeField';
-export * from './widgets/EmailField';
-export * from './widgets/PhoneField';
-export * from './widgets/UrlField';
-export * from './widgets/CurrencyField';
-export * from './widgets/PercentField';
-export * from './widgets/PasswordField';
-export * from './widgets/TextAreaField';
-export * from './widgets/RichTextField';
-export * from './widgets/LookupField';
-export * from './widgets/CapabilityMultiSelectField';
-export * from './widgets/ObjectRefField';
-export * from './widgets/FilterConditionField';
-export * from './widgets/RecipientPickerField';
-export * from './widgets/RecordPickerDialog';
-export * from './widgets/deriveLookupColumns';
-export * from './widgets/FileField';
-export * from './widgets/ImageField';
-export { ImageCropperDialog } from './widgets/ImageCropperDialog';
-export type { ImageCropperDialogProps } from './widgets/ImageCropperDialog';
-export * from './widgets/LocationField';
-export * from './widgets/FormulaField';
-export * from './widgets/SummaryField';
-export * from './widgets/AutoNumberField';
-export * from './widgets/UserField';
-export * from './widgets/ObjectField';
-export * from './widgets/VectorField';
-export * from './widgets/GridField';
-export * from './widgets/ColorField';
-export * from './widgets/SliderField';
-export * from './widgets/RatingField';
-export * from './widgets/CodeField';
-export * from './widgets/AvatarField';
-export * from './widgets/AddressField';
-export * from './widgets/GeolocationField';
-export * from './widgets/SignatureField';
-export * from './widgets/QRCodeField';
-export * from './widgets/MasterDetailField';
-export * from './widgets/MultiSelectField';
-export * from './widgets/RadioField';
-export * from './widgets/CheckboxesField';
-export * from './widgets/TagsField';
-export { withFieldCarrier } from './withFieldCarrier';
-export { toDomProps } from './widgets/toDomProps';
-export type { DomProps } from './widgets/toDomProps';
-export { toDateInputValue, toDateTimeInputValue, fromDateTimeInputValue, } from './widgets/nativeDateValue';
+export * from './widgets/types.js';
+export * from './widgets/file-value.js';
+export * from './FieldEditWidget.js';
+export * from './widgets/TextField.js';
+export * from './widgets/NumberField.js';
+export * from './widgets/BooleanField.js';
+export * from './widgets/SelectField.js';
+export * from './widgets/DateField.js';
+export * from './widgets/DateTimeField.js';
+export * from './widgets/TimeField.js';
+export * from './widgets/EmailField.js';
+export * from './widgets/PhoneField.js';
+export * from './widgets/UrlField.js';
+export * from './widgets/CurrencyField.js';
+export * from './widgets/PercentField.js';
+export * from './widgets/PasswordField.js';
+export * from './widgets/TextAreaField.js';
+export * from './widgets/RichTextField.js';
+export * from './widgets/LookupField.js';
+export * from './widgets/CapabilityMultiSelectField.js';
+export * from './widgets/ObjectRefField.js';
+export * from './widgets/FilterConditionField.js';
+export * from './widgets/RecipientPickerField.js';
+export * from './widgets/RecordPickerDialog.js';
+export * from './widgets/deriveLookupColumns.js';
+export * from './widgets/FileField.js';
+export * from './widgets/ImageField.js';
+export { ImageCropperDialog } from './widgets/ImageCropperDialog.js';
+export type { ImageCropperDialogProps } from './widgets/ImageCropperDialog.js';
+export * from './widgets/LocationField.js';
+export * from './widgets/FormulaField.js';
+export * from './widgets/SummaryField.js';
+export * from './widgets/AutoNumberField.js';
+export * from './widgets/UserField.js';
+export * from './widgets/ObjectField.js';
+export * from './widgets/VectorField.js';
+export * from './widgets/GridField.js';
+export * from './widgets/ColorField.js';
+export * from './widgets/SliderField.js';
+export * from './widgets/RatingField.js';
+export * from './widgets/CodeField.js';
+export * from './widgets/AvatarField.js';
+export * from './widgets/AddressField.js';
+export * from './widgets/GeolocationField.js';
+export * from './widgets/SignatureField.js';
+export * from './widgets/QRCodeField.js';
+export * from './widgets/MasterDetailField.js';
+export * from './widgets/MultiSelectField.js';
+export * from './widgets/RadioField.js';
+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 { 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';