@object-ui/fields 17.7.0 → 18.0.0

package/dist/resolveActionParams.d.ts

@@ -0,0 +1,259 @@
+import { ActionParamDef, ActionParamOption } from '@object-ui/core';
+import { I18nLabel } from '@objectstack/spec/ui';
+/**
+ * Resolve a param `type` to the form widget key that renders it — the fold from
+ * a PARAM type spelling to its widget, the one alias table, read rather than
+ * restated (see `isLookupResolvedType` below, and app-shell's `paramToField`,
+ * which asks the same question one step later). Any type in `FORM_FIELD_TYPES`
+ * resolves to itself (identity — asserted by app-shell's drift test); aliases
+ * and unknown types resolve through the same fallback chain the form applies
+ * (unknown → `text`).
+ */
+export declare function resolveParamWidgetType(paramType: string): string;
+/**
+ * Resolved params keep raw `FieldType` values (`text` / `email` / `select` /
+ * `file` / …), matching the `FieldType` enum in `@objectstack/spec`. **Do
+ * not** translate into the FormField widget vocabulary (`field:select`, …)
+ * here — `ActionParamDialog` owns that translation via its `paramToField()`
+ * adapter (ADR-0059).
+ */
+/**
+ * One option as AUTHORED on an action param — {@link ActionParamOption} with
+ * the label on the authoring side of rc.6's `I18nLabel` widening.
+ *
+ * The distinction is the whole point of the authored/resolved split: an author
+ * may write `{ value: 'high', label: { en: 'High', 'zh-CN': '高' } }`, and
+ * `ActionParamDialog` reads `ActionParamOption.label` as a plain `string`. Left
+ * un-narrowed, the map would ride an INLINE option list straight through to the
+ * select widget (inline options pass through verbatim — see `resolvedOptions`),
+ * and render as `[object Object]` with no diagnostic anywhere. So the two types
+ * are kept apart and {@link resolveOptionLabels} is the one crossing point.
+ *
+ * Spelled out rather than `Omit<ActionParamOption, 'label'> & { … }`: `Omit`
+ * over a type carrying `[key: string]: unknown` resolves `Exclude<keyof T,
+ * 'label'>` back to `string | number`, so it drops `value`'s type AND keeps
+ * `label` as `unknown` — the derivation silently erases exactly the two keys it
+ * is supposed to be about.
+ */
+export type RawActionParamOption = {
+    /** Authored label — a plain string, or rc.6's inline per-locale map. */
+    label?: I18nLabel;
+    value: string;
+    /**
+     * Everything else an option declares (`visibleWhen` / `color` / `icon` /
+     * `disabled`), preserved verbatim — `fbc23e094`.
+     */
+    [key: string]: unknown;
+};
+/** Raw param as authored on a schema action (post-zod). */
+export interface RawActionParam {
+    name?: string;
+    field?: string;
+    objectOverride?: string;
+    /**
+     * Display label, as authored. `@objectstack/spec` 17.0.0-rc.6 widened
+     * `I18nLabel` from `string` to `string | Record<string, string>`, so an
+     * author may inline a per-locale map here
+     * (`label: { en: 'Reason', 'zh-CN': '原因' }`) — the same widening the spec's
+     * `ActionParamSchema.label` carries.
+     *
+     * This restatement is the load-bearing half (objectui#3174): when it drifts
+     * from what `@object-ui/types`' `ActionParam` says an author may write, this
+     * resolver stops accepting the public authoring type. That drift is exactly
+     * what a widened `I18nLabel` produced, and it is why the fix belongs on this
+     * DECLARATION rather than on the test that surfaced it.
+     *
+     * `resolveActionParams` emits `ActionParamDef.label`, which is a plain
+     * `string` — so the map is resolved on the way out (see {@link
+     * ResolveActionParamsContext.locale}), never forwarded.
+     */
+    label?: I18nLabel;
+    type?: string;
+    required?: boolean;
+    /**
+     * Option list authored inline on the param. Speaks the same vocabulary as the
+     * resolved side ({@link ActionParamOption}): the two keys this resolver reads
+     * plus a catch-all for whatever else an option declares (`visibleWhen`,
+     * `color`, `icon`, `disabled`) — `fbc23e094`.
+     *
+     * One key differs, and it is the same rc.6 widening as {@link
+     * RawActionParam.label} one level down: an option's `label` is authored as
+     * `I18nLabel` and RESOLVED to a `string` before it reaches
+     * `ActionParamOption`. See {@link RawActionParamOption}.
+     */
+    options?: RawActionParamOption[];
+    placeholder?: string;
+    helpText?: string;
+    defaultValue?: unknown;
+    /** When true, seed defaultValue from the row record using the field name. */
+    defaultFromRow?: boolean;
+    /**
+     * Carry-over declaration — the spec's `ActionParamSchema.carryOver`
+     * (objectui#6246): seeded from the row, rendered read-only, submitted
+     * verbatim. Copied onto `ActionParamDef.carryOver` unchanged on every branch
+     * below; `ActionParamDialog` is what honours it.
+     */
+    carryOver?: boolean;
+    /** Allow multiple values (file/image/lookup/user params → array value). */
+    multiple?: boolean;
+    /** Accepted upload types (MIME types / extensions) for `file`/`image` params. */
+    accept?: string[];
+    /** Max upload size in bytes for `file`/`image` params. */
+    maxSize?: number;
+    /**
+     * Reference target for an INLINE `lookup`/`master_detail` param (objectstack-ai/objectstack#3405) —
+     * the object whose records the picker searches. Field-backed params inherit
+     * it from the referenced field instead (see `lookupExtras` below). Spelled
+     * `reference` to match `FieldSchema.reference` / `ActionParamSchema.reference`.
+     */
+    reference?: string;
+    /**
+     * Visibility predicate (CEL) — mirrors the spec `ActionParamSchema.visible`.
+     * The server serialises it through `ExpressionInputSchema` as an
+     * `{ dialect, source }` envelope, so accept both the raw string and the
+     * envelope. Propagated to `ActionParamDef.visible` so `ActionParamDialog`
+     * can gate the param (e.g. hide `phoneNumber` unless `features.phoneNumber`).
+     * Absent = always visible.
+     */
+    visible?: string | {
+        dialect?: string;
+        source?: string;
+    };
+}
+/**
+ * Keys of the RESOLVED `ActionParamDef` that are not authorable on a raw param,
+ * mapped to the prescription an author needs (objectui#3174).
+ *
+ * They are deliberately ABSENT from `RawActionParam` above rather than declared
+ * and ignored: the whole defect this table exists for is that
+ * `@object-ui/types`' public `ActionParam` declared them "for parity with the
+ * resolved shape", so `{ name: 'account_id', type: 'lookup', referenceTo:
+ * 'account' }` type-checked, lost its picker target here, and rendered as a
+ * plain record-id text box. `ActionParamSchema` in `@objectstack/spec` is
+ * `.strict()` and rejects every one of them at parse time — `referenceTo` by
+ * name, with `reference` as the suggestion — so resolving them here would make
+ * objectui accept metadata the platform itself refuses to store. That is a
+ * second de-facto contract, not a kindness (AGENTS.md "contract-first"): such a
+ * param would work in a locally-authored TS action and fail at publish.
+ *
+ * So the disposition is: recognise, name, and refuse — never silently drop, and
+ * never quietly honour.
+ */
+export declare const RESOLVED_ONLY_PARAM_KEYS: Readonly<Record<string, string>>;
+/** Field metadata as exposed by `useMetadata().objects[].fields`. */
+interface RuntimeField {
+    type?: string;
+    label?: string;
+    required?: boolean;
+    placeholder?: string;
+    /**
+     * `@objectstack/spec`'s `FieldSchema.inlineHelpText`, the help line drawn
+     * under the field's control (objectui#12213). Read first for a field-backed
+     * param's `helpText`, through `fieldHelpText`, the read the record form
+     * shares.
+     */
+    inlineHelpText?: string;
+    /**
+     * The help line's fallback, read second through `fieldHelpText`. An
+     * objectstack server on `@objectstack/spec` 17.7.0 or later serves a field's
+     * translated help text here.
+     */
+    description?: string;
+    /**
+     * The field's own option list — `select` / `radio` / `checkboxes` metadata as
+     * `@objectstack/spec`'s `SelectOptionSchema` declares it, so entries may carry
+     * `visibleWhen` / `color` / `icon` / `disabled` alongside label and value. A
+     * bare string is shorthand for `{ label: s, value: s }`.
+     */
+    options?: Array<ActionParamOption | string>;
+    multiple?: boolean;
+    defaultValue?: unknown;
+    accept?: string[];
+    maxSize?: number;
+    reference?: string;
+    displayField?: string;
+    reference_field?: string;
+    id_field?: string;
+    descriptionField?: string;
+    description_field?: string;
+    title_format?: string;
+    lookupColumns?: unknown[];
+    lookupFilters?: unknown[];
+    lookup_filters?: unknown[];
+    lookupPageSize?: number;
+    dependsOn?: unknown[];
+}
+interface RuntimeObject {
+    name?: string;
+    fields?: Record<string, RuntimeField>;
+}
+export interface ResolveActionParamsContext {
+    /** Default object name when a param's `objectOverride` is absent. */
+    objectName: string;
+    /** All known runtime objects (`useMetadata().objects`). */
+    objects: RuntimeObject[];
+    /** i18n resolver — `useObjectLabel().fieldLabel`. */
+    fieldLabel: (objectName: string, fieldName: string, fallback: string) => string;
+    /** Optional option-label translator — `useObjectLabel().fieldOptionLabel`. */
+    fieldOptionLabel?: (objectName: string, fieldName: string, optionValue: string, fallback: string) => string;
+    /**
+     * Row record providing default values for params with `defaultFromRow` set.
+     * Used by list_item actions (edit/delete dialogs) so the dialog opens with
+     * the row's current values pre-filled.
+     */
+    row?: Record<string, unknown>;
+    /**
+     * Active UI language (BCP-47) used to resolve an inline per-locale
+     * {@link RawActionParam.label} down to the one string `ActionParamDef.label`
+     * can carry. Both callers thread `useObjectTranslation().language`.
+     *
+     * Optional and nullish-tolerant: omitted means "no locale known", which the
+     * spec's resolver documents as resolving to `en`. It is a context field
+     * rather than a hook read because this is a pure function — the caller is
+     * the component that already knows the language.
+     */
+    locale?: string;
+}
+/**
+ * Resolve a single raw param against object metadata. Inline params pass
+ * through (with safe defaults); field-backed params inherit from the
+ * referenced field and accept inline overrides on top.
+ */
+export declare function resolveActionParam(param: RawActionParam, ctx: ResolveActionParamsContext): ActionParamDef;
+/**
+ * Union the objects a CALLER holds with the ones the console's metadata store
+ * holds, caller first — the object list `resolveActionParams()` should be given.
+ *
+ * ## Why a union and not simply the store (`6cc910b6d`)
+ *
+ * The two lists answer different questions and neither contains the other.
+ * The caller's list is the world that caller is rendering: `ObjectView` passes
+ * the full published set, `DeclaredActionsBar` passes the ONE object it is
+ * drawing a toolbar for, `ConsoleShell`'s root runtime passes none, and a
+ * preview/draft host passes an overlaid world whose defs deliberately differ
+ * from the published ones. The store's list is every object the session has
+ * loaded. A caller that carries a def must keep it — replacing it would make a
+ * draft overlay render its published twin — so the caller is ranked FIRST and
+ * `resolveActionParam`'s `find()` takes the first match by name.
+ *
+ * What the store adds is the objects the caller never had: the owner of a
+ * `{ field }` param dispatched from a surface that is not scoped to that object
+ * at all, and the `objectOverride` target of a cross-object param. Before this,
+ * such a param resolved against a list that could not contain its owner and
+ * degraded — for a field-backed param, which carries no inline `type`, into a
+ * bare `text` param: an empty box, no dropdown, no request for the referenced
+ * object on the wire, while the identical field rendered a real picker on a
+ * record form off this very store.
+ *
+ * ⛔ Not a lenient fallback in the AGENTS.md #0.1 sense: no dialect is being
+ * tolerated and no shape coerced. The metadata is spec-compliant and already in
+ * the client; this is the seam that was not handing it over.
+ *
+ * Pure, and deduplicated by object `name` so a def cannot be resolved twice.
+ * Entries with no usable `name` are carried through from the caller's list
+ * (they are that caller's business) and skipped from the store's.
+ */
+export declare function withKnownObjects<T>(supplied: readonly T[] | undefined, stored: readonly T[] | undefined): T[];
+/** Resolve an array of raw action params. */
+export declare function resolveActionParams(params: RawActionParam[] | undefined, ctx: ResolveActionParamsContext): ActionParamDef[];
+export {};

package/dist/widgets/FormulaField.d.ts

@@ -3,5 +3,46 @@ import { FieldWidgetComponentProps } from './types.js';
 /**
  * FormulaField - Read-only computed field
  * Values are computed on the backend and cannot be edited
+ *
+ * ## One value, one reading (objectui#11748)
+ *
+ * This is the read-only FORM face of a formula; `FormulaCellRenderer` in this
+ * package's barrel is its TABLE face. The two used to format the value each by
+ * itself, so one stored value read two ways: a number here was `200000` (no
+ * `returnType`) or `200000.00` (a `toFixed(2)`), in monospace, beside the
+ * cell's `200,000`; a declared boolean or date read `Yes` / `Jul 4` here and
+ * `true` / `2026-07-04` in the cell.
+ *
+ * Both faces now read the SAME rule and draw each type through the calls the
+ * matching field type's faces make, so they agree on every value:
+ *
+ *   - which type: the declared `returnType`; with none, a JS number is a
+ *     number and anything else is text. ⛔ Nothing is inferred from the
+ *     expression: the spec's own field form says consumers read `returnType`
+ *     "instead of re-parsing the expression".
+ *   - number: `formatNumberFieldValue`, the one call every number face makes
+ *     (the locale's grouping, the width `resolveFieldScale` answers for a
+ *     declared `scale`). The value is read the way the formula cell reads it
+ *     (objectui#11683): blank is empty, and a declared number held as a
+ *     numeric string is a number.
+ *   - currency: money, through the currency field's own faces (`CurrencyField`
+ *     read-only here, `CurrencyCellRenderer` in the cell), reading the
+ *     formula's own `currencyConfig` as they read a currency field's
+ *     (objectui#12111).
+ *   - boolean: the locale's word, as `BooleanField`'s read-only branch draws
+ *     it; only a JS boolean is a boolean, as there (objectui#8593).
+ *   - date: `formatDate`'s DEFAULT face, as `DateField`'s read-only branch
+ *     draws it (objectui#8194).
+ *   - text: the value as the cell prints it, in the font `TextField`'s
+ *     read-only branch draws (objectui#12357), declared `text` or not.
+ *
+ * Both faces also share the emptiness floor (`isEmptyValue` on the coerced
+ * value), so an empty value reads the shared affordance in both.
+ *
+ * The rule is spelled here and in the cell, because the barrel and this lazily
+ * loaded widget may not import each other (the reason `number-format.ts`
+ * gives). `__tests__/formulaFaces.returnType-11748.test.tsx` draws every
+ * declared type in both faces and compares the two texts, so neither can move
+ * alone.
  */
 export declare function FormulaField({ value, field, ...props }: FieldWidgetComponentProps<any>): React.JSX.Element;

package/dist/widgets/GridField.d.ts

@@ -52,8 +52,10 @@ import { InlineGridColumn } from '@objectstack/spec/data';
  *
  * 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).
+ * no other key: `sortField`, the last key read before any face declared it,
+ * is declared there too (objectui#11070 round 9). objectui#11610 renamed all
+ * eight from snake_case to camelCase; a field still carrying a snake_case
+ * spelling is refused by name instead of drawn (`RetiredGridFieldKeys`).
  */
 /**
  * One grid column — `@objectstack/spec`'s inline grid column
@@ -130,7 +132,7 @@ export declare function lookupAutofillPatch(columns: GridColumn[], col: GridColu
 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[]> & {
+type GridFieldProps = FieldWidgetComponentProps<Row[]> & {
     /** When provided, each row shows an "expand" button that opens the row in a
      *  full form (the host — e.g. MasterDetailForm — renders the drawer/modal and
      *  writes the edited values back). Lets a "fat" child be edited in a real form
@@ -147,7 +149,13 @@ export declare function GridField({ value, onChange, field, readonly, disabled,
      *  `readonlyWhen` / `requiredWhen` CEL predicate — so a line cell can react to
      *  the header (`parent.status == 'paid'`). Supplied by MasterDetailForm. */
     contextRecord?: Record<string, unknown>;
-}): React.JSX.Element;
+};
+/**
+ * The `grid` field widget. A field whose metadata carries one of the retired
+ * snake_case keys is refused by name ({@link RetiredGridFieldKeys}); any other
+ * field draws the grid.
+ */
+export declare function GridField(props: GridFieldProps): React.JSX.Element;
 /** Semantic alias — the master-detail subform's child grid. */
 export declare const LineItemsField: typeof GridField;
 export {};

package/dist/widgets/RecipientPickerField.d.ts

@@ -1,5 +1,37 @@
 import { default as React } from 'react';
 import { FieldWidgetComponentProps } from './types.js';
+/**
+ * RecipientPickerField — dependent record picker for a polymorphic recipient
+ * reference (e.g. `sys_sharing_rule.recipient_id`), whose target object is
+ * decided by a sibling `recipient_type` select.
+ *
+ * Reached via the field `widget: 'recipient-picker'` hint (resolves as
+ * `field:recipient-picker`). Reads the live `recipient_type` from
+ * `dependentValues` (the form record), loads candidate records of the mapped
+ * object via `dataSource.find(...)`, and stores the value the sharing evaluator
+ * expects for that type:
+ *
+ *   user                  → sys_user, store `id`
+ *   team                  → sys_team, store `id`
+ *   business_unit         → sys_business_unit, store `id`
+ *   unit_and_subordinates → sys_business_unit, store `id`
+ *
+ * One kind lists CATALOG ITEMS instead of records (objectui#7611, ADR-0131
+ * D3/D7): its candidates are the `position` items of the environment registry,
+ * read through the console's metadata store, and the picker stores the item's
+ * `name` (matched against `sys_user_position.position` at evaluation time):
+ *
+ *   position              → the `position` registry, store `name`
+ *
+ * One kind is NOT a record picker and therefore has no row above:
+ *
+ *   field                 → a user-valued COLUMN of the shared object, store
+ *                           the column's `name` (see FIELD_RECIPIENT_TYPE)
+ *
+ * When `recipient_type` changes after mount the stored id is reset (an id valid
+ * for one type is meaningless for another). Unknown types degrade to a plain
+ * text input so nothing breaks.
+ */
 /** A user-valued column offered by the `field` recipient mode. */
 interface UserFieldDef {
     /** The machine name — this is what gets stored in `recipient_id`. */

package/dist/widgets/RegistryRefField.d.ts

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

package/dist/widgets/SummaryField.d.ts

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

package/dist/widgets/booleanValueLabel.d.ts

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

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

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

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

@@ -0,0 +1,39 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The display text for a native-shaped value (`YYYY-MM-DD`, or
+ * `YYYY-MM-DDTHH:mm` when `withTime`). `''` for an empty or unreadable value.
+ */
+export declare function formatLocaleDateText(value: string, locale: string, withTime: boolean): string;
+/**
+ * The pattern the text box expects, for its placeholder: the locale's own
+ * order and separators with `YYYY` / `MM` / `DD` (and `HH` / `mm`) in place of
+ * the digits.
+ */
+export declare function localeDatePattern(locale: string, withTime: boolean): string;
+/**
+ * Reads what was typed into the text box.
+ *
+ * Returns `''` for blank text, the native-shaped value for a real day (and a
+ * real clock time when `withTime`), and `null` for text that names no real
+ * date. Accepted:
+ *
+ *   - the locale's own digit order, with any separators (`10/16/2026` in `en`,
+ *     `2026/10/16` in `zh`, `16.10.2026` in `de`);
+ *   - an ISO date `2026-10-16`, in every locale (a four-digit first group is
+ *     read as the year);
+ *   - a two-digit year, read in this century;
+ *   - with `withTime`: an hour and minute after the date, 24-hour, or 12-hour
+ *     with `AM` / `PM` or the locale's own afternoon marker. With no time, the
+ *     time is midnight.
+ */
+export declare function parseLocaleDateText(text: string, locale: string, withTime: boolean): string | null;
+/** The local calendar day of `d` as `YYYY-MM-DD`. */
+export declare function toLocalDay(d: Date): string;
+/** Local midnight of a `YYYY-MM-DD` day, for the calendar to select. */
+export declare function fromLocalDay(day: string): Date | undefined;

package/dist/widgets/deriveLookupColumns.d.ts

@@ -24,7 +24,7 @@ interface ObjectSchemaLike {
 }
 /**
  * Derive sensible Record Picker columns from a referenced object's schema when
- * a lookup field declares no explicit `lookup_columns`.
+ * a lookup field declares no explicit `lookupColumns`.
  *
  * Priority:
  *   1. The referenced object's ADR-0085 `highlightFields` — the canonical

package/dist/widgets/file-affordance.d.ts

@@ -1,5 +1,35 @@
 import { default as React } from 'react';
 import { FileValueView } from './file-value.js';
+/**
+ * The translated label and hint for a file the reader may not open
+ * (objectui#12339): a value that arrived as the refused marker
+ * `{ id, metadataRefused: true }` carries no name of its own, and drawing the
+ * generic `fields.file.fileFallback` for it would read as an ordinary file.
+ */
+export declare function useRestrictedFileText(): {
+    label: string;
+    hint: string;
+};
+/**
+ * The restricted state of one file value (`view.metadataRefused`): a lock
+ * and the translated "Restricted file" label instead of a name, and ⛔ no
+ * thumbnail — no MIME type was served, so there is nothing to decide one on.
+ *
+ * It stays an anchor to the view's id-derived URL: whether this reader may
+ * download the file is the download endpoint's own decision, and it may
+ * answer `403 FILE_DOWNLOAD_DENIED`. The accessible name is the visible
+ * label; the hint rides on `title`.
+ *
+ * `compact` draws the lock alone, for a cell or tile that has no room for
+ * the label — the label then becomes the anchor's `aria-label`.
+ */
+export declare function RestrictedFileAffordance({ view, className, compact, icon, }: {
+    view: FileValueView;
+    className?: string;
+    compact?: boolean;
+    /** Suppressed where the row already draws its own icon to the left. */
+    icon?: boolean;
+}): React.ReactElement;
 /**
  * One file: a keyboard-reachable view/download link when it resolves, and the
  * caller's own `fallback` text when it does not.

package/dist/widgets/file-refused.d.ts

@@ -0,0 +1,17 @@
+import { FileRefusedValue } from '@objectstack/spec/data';
+/**
+ * Is this value the platform's refused marker `{ id, metadataRefused: true }`?
+ *
+ * Judged by the spec's own closed `FileRefusedValueSchema`, not by a second
+ * hand-written shape here: an object with any other key is not the marker,
+ * and reads through `readFileValue`'s ordinary object arm.
+ */
+export declare function isFileRefusedValue(value: unknown): value is FileRefusedValue;
+/**
+ * One element of a field value as an editable widget re-submits it beside or
+ * after an edit (append, remove, crop): the refused marker is reduced to its
+ * bare `sys_file` id — the stored form — and ⛔ never sent back as the marker
+ * object, which is a read form no record write accepts. Every other element
+ * passes through untouched, as before.
+ */
+export declare function fileValueForResubmit(value: unknown): unknown;