@object-ui/fields 17.6.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/AvatarField.d.ts

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

package/dist/widgets/BooleanField.d.ts

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

package/dist/widgets/DateField.d.ts

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

package/dist/widgets/DateTimeField.d.ts

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

package/dist/widgets/FilterConditionField.d.ts

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

package/dist/widgets/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/GeolocationField.d.ts

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

package/dist/widgets/GridField.d.ts

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