@object-ui/core 17.7.0 → 18.0.0

package/README.md

@@ -179,6 +179,75 @@ withoutDeniedFields({ account_code: 'A-1', salary: 100 }, policy, 'account', ['a
 - When nothing is withheld the SAME object comes back, so callers can tell the
   two cases apart by identity.
 
+### Affordance-to-grant map (`AFFORDANCE_GRANTS`, `resolveAffordance`)
+
+Every console affordance that offers a write — a create form's fields, the
+record header's Edit, a list's New and Import, a lookup's "Create new", a grid
+row's Delete, and the rest — reads the grant it exercises from ONE table,
+`AFFORDANCE_GRANTS` (objectui#12082). A row names the CRUD-affordance bit the
+affordance needs, the object grant it exercises (`create`, `update` or
+`delete`) and, for an affordance that offers fields, the field question it asks
+(`create` for an insert, `write` for an update). The fields of a form, of the
+record page's in-place edit (`recordEdit`) and of a list's in-cell edit
+(`listInlineEdit`) each ask that question, so a field the caller's permission
+set marks `editable: false` is offered read-only on every one of them
+(objectui#12103). The `write` question is the server's whole update rule for a
+field, so for the record's owner field it also needs the transfer grant
+(`allowTransfer`, or `modifyAllRecords`).
+
+`resolveAffordance` is the one verdict: the object's managed-object policy, the
+server's effective API operation set and the caller's grant must all allow it,
+and the row's `userActions` predicates are surfaced only then.
+
+```typescript
+import { resolveAffordance, resolveFieldAffordance } from '@object-ui/core'
+
+// `perms` is structural: `usePermissions()` from `@object-ui/permissions`
+// satisfies it. With no provider mounted every grant reads open.
+const perms = {
+  isLoaded: true,
+  can: (_object: string, grant: 'create' | 'update' | 'delete') => grant === 'create',
+  checkField: (_object: string, _field: string, action: 'create' | 'write') => action === 'create',
+  getObjectApiOperations: () => undefined,
+}
+
+resolveAffordance('listNew', { objectSchema: null, objectName: 'orders', perms })
+// { allowed: true }  — the create grant is held
+resolveAffordance('recordEdit', { objectSchema: null, objectName: 'orders', perms })
+// { allowed: false } — Edit reads the update grant, which is not
+
+resolveFieldAffordance('createFormFields', perms, 'orders', 'title') // true
+resolveFieldAffordance('editFormFields', perms, 'orders', 'title')   // false
+```
+
+An affordance added later gets a row here and reads it through these functions;
+it does not spell its own `can(object, verb)`. That includes an affordance that
+reads NO grant at all — the calendar's quick-create and drag-to-reschedule
+(`calendarQuickCreate`, `calendarReschedule`) and the kanban card move
+(`kanbanCardMove`) were such affordances until they gained their rows. An
+affordance that writes with the same verb on the same object reuses that row:
+the record overlay's inline edit reads `recordEdit`, a gantt's bar edits and a
+grid's bulk field update read `rowEdit`, a gantt row's Delete reads `rowDelete`,
+the AI build panel's spreadsheet import reads `listImport`, a related list's
+Add existing reads `relatedNew` (a link row) or `relatedRowEdit` (a re-parent),
+and Setup's permission-set and position holders read `relatedNew` (a holder
+added) and `relatedRowDelete` (a holder removed), each asked of its assignment
+object (`sys_user_permission_set`, `sys_user_position`). Reaching Setup is not
+that grant: the Setup app asks `setup.access`, which a caller can hold while the
+server refuses their write of an assignment row.
+The record feed's writes have rows of their own, each asked of the object it
+writes: `feedComment` (a comment or reply, `sys_comment`), `feedReactionAdd` and
+`feedReactionRemove` (the caller's own `sys_comment_reaction` row), and
+`feedReactionColumn` (a reaction on a deployment that stores them in a
+`sys_comment` column). The map's
+enumeration pin in `@object-ui/plugin-form` (`affordanceGrantMap-12082.test.tsx`)
+also counts every write call site in the console tree and holds each to the row
+it sits behind, or to the reason it has none — and, for a component whose write
+its host gates (the import wizard), holds every mount to reading the row. The
+sites it found with no row yet formed a frozen backlog, which the pin now holds
+empty: a new one cannot be added, so a write affordance gets its row when it
+lands.
+
 ### Undo snapshot for an update (`captureUpdateUndoData`)
 
 An `undoable` update restores exactly the fields it wrote, from their values
@@ -223,6 +292,64 @@ captureUpdateUndoData(['config'], { id: 't1', config: { id: 'c1', mode: 'strict'
 - `fields` is required. Pass `undefined` only when the caller has no field
   definitions for the object; nothing is then treated as a relation.
 
+### Which fields an `operation: 'update'` Undo covers
+
+The platform action route writes the `patch` of the declared action the
+action's `name` names, under the collected params. So `ActionRunner`'s Undo
+snapshot covers that declaration's `patch` keys plus the collected params. The
+runner reads the declaration from its context: a host publishes the object's
+declared actions as `objectActions`, beside `objectName` and `objectFields`.
+
+```typescript
+import { ActionRunner } from '@object-ui/core'
+
+// The object definition the host already holds, as the metadata API serves it.
+declare const taskDef: { fields: Record<string, unknown>; actions: unknown[] }
+
+// The same context `ActionProvider` takes. `objectFields` and `objectActions`
+// are read for `objectName`'s object only.
+new ActionRunner({
+  objectName: 'task',
+  objectFields: taskDef.fields,
+  objectActions: taskDef.actions,
+})
+```
+
+- The list is read only for the context's own object. A dispatch to another
+  object, or a host that publishes no list, reads the dispatched action's own
+  `patch`: a host that dispatches an object's action whole hands it in.
+- A page action row's own `patch` is never covered, and no action renderer
+  forwards one: `@objectstack/spec` 18 retires the key on the row. A row that
+  names an action whose declaration has no `patch` snapshots the collected
+  params alone.
+
+### Display time zone (`setDisplayTimeZone`)
+
+The date and datetime faces this package exports (`formatDate`,
+`formatDateTime`, `formatDateTimeCompactParts`, `formatRelativeDate`) render
+an instant in one display zone. A host declares it once; no caller passes a
+zone, so every face on the page agrees.
+
+```typescript
+import { formatDateTime, setDisplayTimeZone } from '@object-ui/core'
+
+formatDateTime('2026-09-02T03:00:00Z', { locale: 'en-US' }) // the viewer's zone
+setDisplayTimeZone('America/Los_Angeles')
+formatDateTime('2026-09-02T03:00:00Z', { locale: 'en-US' }) // "Sep 1, 2026, 08:00 PM"
+formatDateTime('2026-09-01', { locale: 'en-US' })           // "Sep 1, 2026, 12:00 AM", in every zone
+setDisplayTimeZone(undefined)                               // back to the viewer's zone
+```
+
+- A date-only value names a calendar day and keeps it in every zone, including
+  the `Date` that `toDisplayDate` builds for one and a caller hands on.
+- "Today" for the relative face is the display zone's today.
+- An IANA name the runtime's `Intl` does not know clears the zone, with a
+  console warning.
+- `getDisplayTimeZone()` reads it back, and `subscribeDisplayTimeZone(listener)`
+  reports changes in React's `useSyncExternalStore` shape. In a React tree,
+  `LocalizationProvider` from `@object-ui/i18n` sets it from its `timezone`
+  value; a renderer never calls the setter.
+
 ## Philosophy
 
 This package is designed to be **framework-agnostic**. It contains:

package/dist/actions/ActionRunner.d.ts

@@ -19,44 +19,37 @@
  * Features: conditional execution, confirmation, toast notifications,
  * redirect handling, action chaining, custom handler registration.
  */
-import type { UIActionSchema } from '@object-ui/types';
+import type { ActionContext, ActionResult, UIActionSchema } from '@object-ui/types';
 import type { Action as SpecActionInput } from '@objectstack/spec/ui';
 import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator.js';
-import { type UndoableOperation } from './UndoManager.js';
 import { type FieldContainerLike } from '../utils/predicate-record.js';
-export interface ActionResult {
-    success: boolean;
-    data?: any;
-    error?: string;
-    reload?: boolean;
-    close?: boolean;
-    redirect?: string;
-    /** Modal schema to render (for type: 'modal') */
-    modal?: any;
-    /**
-     * Suppress the automatic success toast for this result. A handler sets this
-     * when the action only HANDED OFF to a follow-up UI rather than completing —
-     * e.g. a `flow` action that paused at a screen and opened the flow-runner. The
-     * action hasn't "completed yet", so a "success" toast on open would be
-     * misleading; the follow-up surface owns its own completion messaging.
-     */
-    silent?: boolean;
-    /**
-     * An undoable operation captured by the handler (e.g. an `undoable` update
-     * action's prior field values). When present, the runner pushes it onto the
-     * global UndoManager and the success toast offers an "Undo" affordance.
-     */
-    undo?: UndoableOperation;
-}
-export interface ActionContext {
-    data?: Record<string, any>;
-    record?: any;
-    selectedRecords?: Record<string, any>[];
-    /** Live page-variable snapshot (ADR-0049), published by PageVariableActionBridge. */
-    pageVariables?: Record<string, any>;
-    user?: any;
-    [key: string]: any;
-}
+/**
+ * What an action handler returns and the runner reads — ONE authority, in
+ * `@object-ui/types` (objectui#6349, batch 4), re-exported here exactly as
+ * {@link ActionContext} is below. The members this module used to declare
+ * (`reload`, `redirect`, `modal`, `silent`, `undo`) moved down with it, and
+ * `UndoableOperation`, which types `undo`, moved down beside it
+ * (`./UndoManager.js` re-exports that one). The gate that counts authorities is
+ * `scripts/__tests__/one-authority-per-exported-name-6273.test.ts`; a re-export
+ * is not one.
+ */
+export type { ActionResult } from '@object-ui/types';
+/**
+ * The context a runner executes actions in — ONE authority, in
+ * `@object-ui/types` (objectui#6349, batch 4). This module RE-EXPORTS that
+ * declaration instead of declaring a second one, so an import of
+ * `ActionContext` from `@object-ui/core` and one from `@object-ui/types` are
+ * the same type. `@object-ui/types` is the dependency-legal side: it depends on
+ * no `@object-ui/*` package, and this package depends on it.
+ *
+ * A re-export is not a second authority —
+ * `scripts/__tests__/one-authority-per-exported-name-6273.test.ts` counts
+ * declarations and ALIASING re-exports, never `export type { X } from …` —
+ * which is why this convergence takes `ActionContext` off that gate's
+ * `KNOWN_COLLISIONS` baseline. The member drift it removed is recorded on the
+ * declaration itself.
+ */
+export type { ActionContext } from '@object-ui/types';
 /**
  * API configuration for complex requests.
  */
@@ -358,7 +351,8 @@ export interface ActionDef {
      * caller's permissions, the object's hooks and its validations all fire as
      * for a user edit. That is why {@link execute} reads this key BEFORE `type`:
      * by the time `type` is consulted an update action is indistinguishable from
-     * any other script action, and its `patch` would never reach the request.
+     * any other script action, and it would run without the update path's Undo
+     * capture and its no-route refusal.
      */
     operation?: SpecActionInput['operation'];
     /**
@@ -366,6 +360,16 @@ export interface ActionDef {
      * record, merged UNDER the collected `params` so a fixed value can be
      * declared without exposing it in the dialog. The spec refuses it on an
      * action without `operation: 'update'`, where it would be silently dropped.
+     *
+     * The ROUTE applies it, from the declaration it resolves by name; this
+     * runner never sends it (objectui#12941) and reads it only to know which
+     * fields an Undo must restore.
+     *
+     * It is a DECLARATION's key here: a host that dispatches an object's action
+     * whole hands it along. No action renderer forwards a page row's own `patch`
+     * (objectui#13022, following `@objectstack/spec` 18's retirement of the row
+     * key), and the runner reads the host-published declaration ahead of this
+     * one (`declaredUpdatePatch`).
      */
     patch?: SpecActionInput['patch'];
     /** Execution mode of the action. */
@@ -458,6 +462,11 @@ export type ActionRunnerHandler = (action: ActionDef, context: ActionContext) =>
  * `.cancel`), and `app-shell`'s `ActionConfirmDialog.tsx` renders them in
  * place of its generic `actionConfirm.*` fallbacks. Line numbers are left out
  * on purpose: #5205's pointer had already drifted by the time it was executed.
+ * The record delete is a second producer (objectui#11695): `app-shell`'s
+ * `useObjectActions` (the list's row and bulk Delete) and `RecordDetailView`
+ * (the record page's Delete) hand it `recordDelete.confirmCopy`'s title and
+ * confirm label with `destructive: true`, which paints the confirm button in
+ * the destructive button style.
  *
  * So re-measure across the repo, not this package: grep for two-argument
  * calls of `ConfirmationHandler`-typed values (`confirmHandler(`, `onConfirm(`)
@@ -471,6 +480,8 @@ export type ConfirmationHandler = (message: string, options?: {
     title?: string;
     confirmText?: string;
     cancelText?: string;
+    /** The confirmed action destroys data: paint the confirm button destructive. */
+    destructive?: boolean;
 }) => Promise<boolean>;
 /**
  * Toast handler — consumers can wire to Sonner or any toast library.
@@ -500,8 +511,35 @@ export type NavigationHandler = (url: string, options?: {
  * Param collection handler — consumers provide to show a dialog
  * for collecting ActionParam values before action execution.
  * Returns collected values, or null if cancelled.
+ *
+ * `interpolate` fills the `${...}` holes of the dialog's authored copy (the
+ * action's `description`, each param's `helpText`) in the same template scope
+ * the runner reads `confirmText` in — for a row dispatch, the row is `record`
+ * (see `templateEvaluatorFor`). The runner cannot fill them itself before the
+ * call: the handler localizes that copy AFTER it receives it (a translation
+ * bundle entry or an inline per-locale map), so the hole has to be filled on
+ * the text the user will actually read (objectui#12967).
+ *
+ * `run` lets the handler keep its dialog open until the run its values start
+ * has an outcome (objectui#13161). Called with the collected values, it
+ * dispatches the action with them and resolves with that run's
+ * {@link ActionResult} (a dispatch that throws resolves as a refused run, the
+ * way `execute` reports one). A refused run has already had its
+ * post-execution (the error toast, `onFailure`), so the handler can show the
+ * refusal beside the values the user typed and call `run` again with the
+ * edited values. A successful run's post-execution (success toast, result
+ * dialog, chain, `onSuccess`) waits until the handler settles its promise,
+ * so the dialog is closed before any of it shows. A call made while an
+ * earlier one is still in flight returns that earlier run, and dispatches
+ * nothing new.
+ *
+ * Once `run` has been called, the handler's own promise only ends the
+ * session: the runner never dispatches the values it resolves with. `null`
+ * after a refused run is a cancel, reported exactly as a cancel before any
+ * run. A handler that never calls `run` keeps the old contract: the runner
+ * dispatches once with the values it resolves.
  */
-export type ParamCollectionHandler = (params: ActionParamDef[], action?: ActionDef) => Promise<Record<string, any> | null>;
+export type ParamCollectionHandler = (params: ActionParamDef[], action?: ActionDef, interpolate?: (text: string) => string, run?: (values: Record<string, any>) => Promise<ActionResult>) => Promise<Record<string, any> | null>;
 /**
  * The contract's own result-dialog block, and one entry of its field list.
  *
@@ -819,7 +857,32 @@ export declare class ActionRunner {
      */
     registerScript(scriptName: string, handler: ActionRunnerHandler): void;
     unregisterScript(scriptName: string): void;
-    execute(action: ActionDef): Promise<ActionResult>;
+    /**
+     * Run `action`; with `callContext`, run it against that context for this
+     * one dispatch (objectui#13063).
+     *
+     * The runner's context names the PAGE: its `record` and its `objectName`.
+     * A dispatch that runs against some other record, such as a related-list
+     * row on a record page, which is a record of the CHILD object, hands that
+     * record here as `{ record, objectName }`. Every executor then reads it as
+     * the record the action runs against, the way a dispatch from that record's
+     * own page does: `executeForm` forwards its id and object, and its
+     * boundary check compares the target view against the child object instead
+     * of the page's.
+     *
+     * The runner's own context is not touched: the dispatch runs on a one-shot
+     * runner over the merged context that shares this runner's handlers (see
+     * {@link ActionRunner.scopedTo}).
+     */
+    execute(action: ActionDef, callContext?: Partial<ActionContext>): Promise<ActionResult>;
+    /**
+     * Dispatch an action whose params are collected, and answer what it
+     * returned — WITHOUT post-execution, which each caller runs itself:
+     * `execute` right after a lone run, and the param-collection session
+     * (`ParamCollectionHandler`'s `run`, objectui#13161) once per refused attempt
+     * and once for the successful one when the session ends.
+     */
+    private dispatchCollected;
     /**
      * Execute multiple actions in sequence or parallel.
      */
@@ -872,7 +935,9 @@ export declare class ActionRunner {
      * react-router's `navigate` — so `openIn: 'self'` is a real SPA route hop,
      * in place, immune to popup blocking. No `window.location` / `window.open`
      * mechanism is introduced here; the no-handler fallback is the same
-     * `result.redirect` hand-off `navigateTo` already uses.
+     * `result.redirect` hand-off `navigateTo` already uses. The one exception is
+     * shared with `navigateTo`: a `mailto:` target is not a route, so it is a
+     * full-page navigation in place (objectui#12191).
      *
      * **No default is written here.** `openIn` is a materialised
      * `.default('self')` in the spec, so parse output always carries a resolved
@@ -911,12 +976,34 @@ export declare class ActionRunner {
      * sent hunting for a field they were right not to write), and falling through
      * to `executeActionSchema` reports on an action that never ran.
      *
-     * ## `patch` rides UNDER the collected params
+     * ## `patch` is the route's: it never rides on the wire (objectui#12941)
+     *
+     * The request carries the values collected for the action's declared
+     * `params`, plus the transport keys the dispatch reads (`recordId`, and the
+     * `_rowRecord` stash it strips before POSTing) — and NOTHING from `patch`.
+     * The route applies the declared `patch` itself, from the declaration it
+     * resolves by the action's name (`@objectstack/runtime`'s
+     * `declarativeUpdateWrite`, which writes `{ ...patch, ...params }`). The
+     * patch keys are not params the action declares, so posting them makes every
+     * declarative-update button a request carrying undeclared params — the very
+     * request the ADR-0104 D2 param contract refuses (objectstack#24268). A
+     * client copy of `patch` on the wire also adds nothing: the server never
+     * reads it.
+     *
+     * The spec's words for the merge the route performs: static field values
+     * "merged UNDER the user-supplied `params` so a fixed value can be declared
+     * without exposing it in the dialog". So a collected param of the same name
+     * WINS — the author declared a default, and the user answered it. This
+     * runner still computes that same merge, but only to know what the route
+     * WROTE, which is what an Undo snapshot must cover; it is never sent.
      *
-     * The spec's words: static field values "merged UNDER the user-supplied
-     * `params` so a fixed value can be declared without exposing it in the
-     * dialog". So a collected param of the same name WINS — the author declared a
-     * default, and the user answered it.
+     * ## The `patch` in that merge is the DECLARATION's (objectui#13022)
+     *
+     * The route writes the `patch` of the declaration the action's `name` names,
+     * so that is the `patch` the snapshot covers: read by
+     * {@link declaredUpdatePatch} from the declarations the host published, else
+     * off a def that is the declaration itself. A page action row's own `patch`
+     * is never written (`@objectstack/spec` 18 retires it) and never covered.
      */
     private executeUpdateOperation;
     /**
@@ -929,6 +1016,24 @@ export declare class ActionRunner {
      * Uses navigationHandler for SPA routing, falls back to window.location.
      */
     private executeUrl;
+    /**
+     * A navigation announces nothing unless its action declares the copy
+     * (objectui#12755).
+     *
+     * `type: 'url'`, its `navigation` alias and `type: 'form'` only change the
+     * route: nothing was written, so there is nothing to confirm. Their
+     * `{ success: true }` used to reach `handlePostExecution` like a write's, and
+     * the generic `completedSuccessfully` toast ("操作已成功完成") told the user an
+     * operation had completed when a page had merely opened (objectstack-ai/cloud#2909:
+     * an "invite member" button that only navigated read as "invitation sent").
+     *
+     * The result keeps `success: true` (callers read it as "the navigation
+     * happened") and is marked `silent`, the flag that already means "no success
+     * toast for this result". An author who wants a toast after the navigation
+     * declares `successMessage`, and that copy still shows: the declaration is the
+     * only signal, so there is no separate switch to forget.
+     */
+    private announceNavigation;
     /**
      * The one navigator behind `type: 'url'` and its `navigation` alias.
      *
@@ -1053,10 +1158,6 @@ export declare class ActionRunner {
      * Execute API action — supports both simple string endpoint and complex ApiConfig.
      */
     private executeAPI;
-    /**
-     * Validate URL to prevent javascript: or data: protocol injection.
-     */
-    private isValidUrl;
     /**
      * Substitute `${param.X}` and `${ctx.X}` tokens in an action target.
      *
@@ -1091,8 +1192,51 @@ export declare class ActionRunner {
      * placed under context.ctx is merged on top.
      */
     private buildInterpolationContext;
+    /**
+     * The evaluator a dispatch's authored copy is read through: `confirmText`,
+     * and the param dialog's `description` / `helpText` via the handler's
+     * `interpolate` argument.
+     *
+     * One rule for every door (objectui#12967): the record the action runs
+     * against is `record`. The record header binds it in the runner's context
+     * (`RecordDetailView`'s `ActionProvider`). A row surface does not — it
+     * stashes the clicked row under `params._rowRecord` (ObjectGrid's row
+     * actions, a related list's row actions, `DeclaredActionsBar`, a page
+     * header, `action:button`'s update write) and fires through the shared
+     * runner, whose context names the page, not the row. So when the dispatch
+     * carries a row, the row is bound as `record` for this dispatch's templates,
+     * and it wins over a page-level `record` (a related-list row on a record page
+     * is the child, not the page's record). Nothing else in the scope changes,
+     * and the runner's own context is not touched.
+     *
+     * A hole naming a field the record does not carry degrades the way the
+     * header's always has: the evaluator reads `undefined` and the hole prints
+     * empty.
+     */
+    private templateEvaluatorFor;
     updateContext(newContext: Partial<ActionContext>): void;
     getContext(): ActionContext;
+    /**
+     * A one-shot runner for {@link ActionRunner.execute}'s `callContext`
+     * (objectui#13063): this runner's context with `callContext` merged over it,
+     * and this runner's handlers, translator and registries, shared rather than
+     * copied, so the dispatch confirms, collects params, toasts and navigates
+     * exactly as this runner does.
+     *
+     * Two keys follow the merge rather than the base:
+     *
+     *  - `ctx`, the `ctx.*` mirror `ActionProvider` publishes beside the flat
+     *    keys. A `${ctx.record.…}` hole has to read the same record as a
+     *    `${record.…}` one.
+     *  - `objectFields` / `objectActions`. A host publishes them BESIDE
+     *    `objectName`, so the pair names one object (objectui#11122,
+     *    objectui#13022). When `callContext` names another object and brings no
+     *    definitions of its own, the base's are dropped: the page object's field
+     *    types and declarations must not answer for the child's record. That is
+     *    what a dispatch with no `callContext` already gets for a retargeted
+     *    action, so the update path's capture sees the same input either way.
+     */
+    private scopedTo;
     /**
      * Get the expression evaluator (for components that need to evaluate visibility, etc.)
      */
@@ -1119,4 +1263,3 @@ export interface OnSuccessNavigation {
  * shape GUARD on unparsed data, not a discriminator between two meanings.
  */
 export declare function readOnSuccessNavigation(value: unknown): OnSuccessNavigation | null;
-export {};