@object-ui/core 16.1.0 → 17.2.0

package/dist/actions/ActionEngine.d.ts

@@ -78,7 +78,17 @@ export declare class ActionEngine {
         bulkEnabled?: boolean;
         priority?: number;
     }): void;
-    /** Register multiple actions from an ActionSchema array */
+    /**
+     * Register multiple actions from an ActionSchema array.
+     *
+     * Only `locations` is harvested from the metadata. `shortcut` and
+     * `bulkEnabled` used to be read here too, but spec 17 retired both as
+     * `retiredKey()` tombstones — a declaration carrying either one no longer
+     * parses, so harvesting them read a key that cannot exist and made two dead
+     * options look load-bearing. Both remain accepted on the single-action
+     * `registerAction(action, options)` overload, where a HOST passes them
+     * explicitly; they are simply no longer sourced from authored metadata.
+     */
     registerActions(actions: ActionDef[]): void;
     /** Unregister an action by name */
     unregisterAction(name: string): void;

package/dist/actions/ActionEngine.js

@@ -110,13 +110,24 @@ export class ActionEngine {
             this.normalizedShortcutMap.set(normalizeShortcut(options.shortcut), name);
         }
     }
-    /** Register multiple actions from an ActionSchema array */
+    /**
+     * Register multiple actions from an ActionSchema array.
+     *
+     * Only `locations` is harvested from the metadata. `shortcut` and
+     * `bulkEnabled` used to be read here too, but spec 17 retired both as
+     * `retiredKey()` tombstones — a declaration carrying either one no longer
+     * parses, so harvesting them read a key that cannot exist and made two dead
+     * options look load-bearing. Both remain accepted on the single-action
+     * `registerAction(action, options)` overload, where a HOST passes them
+     * explicitly; they are simply no longer sourced from authored metadata.
+     */
     registerActions(actions) {
         for (const action of actions) {
             this.registerAction(action, {
+                // No cast: `locations` is a declared `ActionDef` field as of
+                // objectstack#4075 step 2. The `as any` it replaces existed only
+                // because the key reached this reader through the index signature.
                 locations: action.locations,
-                shortcut: action.shortcut,
-                bulkEnabled: action.bulkEnabled,
             });
         }
     }

package/dist/actions/ActionRunner.d.ts

@@ -5,14 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/**
- * @object-ui/core - Action Runner
- *
- * Executes actions defined in ActionSchema and EventHandler.
- * Supports all spec v2.0.1 action types: script, url, modal, flow, api.
- * Features: conditional execution, confirmation, toast notifications,
- * redirect handling, action chaining, custom handler registration.
- */
+import type { ActionInput as SpecActionInput } from '@objectstack/spec/ui';
 import { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
 import { type UndoableOperation } from './UndoManager';
 export interface ActionResult {
@@ -70,9 +63,15 @@ export interface ApiConfig {
  * Compatible with both UIActionSchema (spec v2.0.1) and legacy crud.ts ActionSchema.
  */
 export interface ActionDef {
-    /** Action type identifier: 'script' | 'url' | 'modal' | 'flow' | 'api' | 'navigation' | custom */
+    /** Action type identifier — a `RunnableActionType` (the spec's six plus the
+     *  `navigation` alias of `url`) or a custom type with a registered handler. */
     type?: string;
-    /** Legacy action type field */
+    /**
+     * Legacy action type field.
+     *
+     * @deprecated objectui dialect — use the spec spelling `type`. Both are read,
+     * `type` first (objectstack#4075 step 2).
+     */
     actionType?: string;
     /** Action name (from UIActionSchema) */
     name?: string;
@@ -91,13 +90,36 @@ export interface ActionDef {
     condition?: string;
     /** Disabled expression — if truthy, skip action */
     disabled?: string | boolean;
-    /** API endpoint (string URL or complex config) */
+    /**
+     * API endpoint (string URL or complex config).
+     *
+     * @deprecated objectui dialect — the spec spells an `api` action's endpoint
+     * `target` (with the verb in `method`). `executeAPI` resolves
+     * `api || endpoint || target`, so `target` alone is sufficient. The
+     * `ApiConfig` object form has no spec counterpart and is objectui-only
+     * (objectstack#4075 step 2).
+     */
     api?: string | ApiConfig;
-    /** API endpoint URL (spec v2.0.1 alias) */
+    /**
+     * API endpoint URL.
+     *
+     * @deprecated objectui dialect — this was the "spec v2.0.1 alias", but spec 17
+     * spells it `target`. `executeAPI` resolves `api || endpoint || target`
+     * (objectstack#4075 step 2).
+     */
     endpoint?: string;
     /** HTTP method */
     method?: string;
-    /** Navigation target */
+    /**
+     * Navigation target — a nested envelope carrying the `navigation` alias's own
+     * spelling (`to` / `external` / `newTab` / `replace`).
+     *
+     * @deprecated objectui dialect — the spec has no nested navigation envelope;
+     * it spells a navigation action `{ type: 'url', target, openIn }`.
+     * `executeNavigation` reads `navigate.to || navigate.target || navigate.redirect`,
+     * falling back to the same keys on the action itself, so a flat `target` works
+     * today (objectstack#4075 step 2).
+     */
     navigate?: any;
     /** onClick callback (legacy) */
     onClick?: () => void | Promise<void>;
@@ -131,10 +153,33 @@ export interface ActionDef {
      * reveal dialog rendering `result.data` (see ResultDialogSpec).
      */
     resultDialog?: ResultDialogSpec;
-    /** Script/expression to execute (for type: 'script') */
-    execute?: string;
-    /** Target URL or identifier (for type: 'url', 'modal', 'flow') */
+    /**
+     * The one handler slot: script name/expression for `type: 'script'`, URL for
+     * `'url'`, flow name for `'flow'`, modal/page for `'modal'`, endpoint for
+     * `'api'`, FormView name for `'form'`.
+     *
+     * The `execute` alias was REMOVED in @objectstack/spec 17 (#3855) and is not
+     * read here (#3856) — don't re-add it. Two handler slots is how one action ran
+     * one script server-side and a different one client-side (#3713).
+     */
     target?: string;
+    /**
+     * Action body (spec `ActionSchema.body` — `HookBodySchema`). Opaque here:
+     * bodies are a SERVER-side execution surface and this runner never
+     * interprets one.
+     *
+     * L2 (`language: 'js'`) is defined as a function body run inside an isolated
+     * VM enforcing declared capabilities, `timeoutMs` and `memoryMb`. A browser
+     * has no such isolate, so "enforcing" those client-side would be decoration.
+     * L1 (`language: 'expression'`) is formula-engine (CEL) source, a different
+     * dialect from this package's `${…}` ExpressionEvaluator — running it here
+     * would diverge silently rather than fail.
+     *
+     * Consumers dispatch bodies by registering a `script` handler that POSTs to
+     * `/api/v1/actions/{object}/{action}` (see app-shell's
+     * `useConsoleActionRuntime`); the server runs the body through its sandbox.
+     */
+    body?: unknown;
     /** For type: 'url' — where to open `target`. `'new-tab'` forces a new
      *  browser tab/window, `'self'` forces same-page navigation. When omitted,
      *  external URLs open in a new tab and relative URLs navigate in place.
@@ -161,10 +206,82 @@ export interface ActionDef {
      *  must perform all auth/authz itself (e.g. the cloud `/sso-open` endpoint,
      *  which re-runs every check the POST half would have done). */
     newTabUrl?: string;
+    /** Where this action renders (`record_header`, `list_toolbar`, …). Read by
+     *  `ActionEngine.registerActions` to seed the location filter. */
+    locations?: SpecActionInput['locations'];
+    /**
+     * Visibility predicate, evaluated against the runner's context.
+     *
+     * The `boolean` arm is objectui's own, deliberately wider than the spec:
+     * `ActionSchema.visible` admits only a CEL string or a `{ dialect, source }`
+     * envelope, while `ActionEngine.getActionsForLocation` also honours a literal
+     * `visible: true` / `false` (pinned by `ActionEngine.visibility.test.ts`).
+     * Declared rather than left to the index signature so the tolerance is
+     * auditable instead of invisible — but it IS a dialect, and objectstack#4075
+     * step 3 has to decide whether the spec adopts the boolean or objectui drops
+     * it. Do not widen this further.
+     */
+    visible?: SpecActionInput['visible'] | boolean;
+    /** System permissions the caller must ALL hold for the action to be offered
+     *  (ADR-0066 D4 UI half — the server enforces the source of truth). */
+    requiredPermissions?: SpecActionInput['requiredPermissions'];
+    /** Icon name for the rendered control. */
+    icon?: SpecActionInput['icon'];
+    /** Visual emphasis of the rendered control (`primary`, `danger`, …). */
+    variant?: SpecActionInput['variant'];
+    /** Sort weight among sibling actions. */
+    order?: SpecActionInput['order'];
+    /** Which renderer surfaces the action (`action:button`, `action:menu`, …). */
+    component?: SpecActionInput['component'];
+    /** Object this action is declared against. */
+    objectName?: SpecActionInput['objectName'];
+    /** AI affordance metadata (tool exposure, prompts). */
+    ai?: SpecActionInput['ai'];
+    /** Accessibility overrides for the rendered control. */
+    aria?: SpecActionInput['aria'];
+    /** Extra properties merged into the request body alongside the collected params. */
+    bodyExtra?: SpecActionInput['bodyExtra'];
+    /** How collected params are shaped into the request body (`flat` or nested). */
+    bodyShape?: SpecActionInput['bodyShape'];
+    /** Execution mode of the action. */
+    mode?: SpecActionInput['mode'];
+    /** Field on the record supplying the record id sent to the endpoint. */
+    recordIdField?: SpecActionInput['recordIdField'];
+    /** Request-parameter name carrying the record id. */
+    recordIdParam?: SpecActionInput['recordIdParam'];
+    /** Auth/tenancy feature the action requires before it is offered. */
+    requiresFeature?: SpecActionInput['requiresFeature'];
+    /**
+     * @deprecated Retired in `@objectstack/spec` 17 as a `retiredKey()` tombstone —
+     * authoring it is a hard parse rejection, so this resolves to `undefined` and
+     * assigning a value is a compile error. A HOST may still pass a shortcut
+     * explicitly via `ActionEngine.registerAction(action, { shortcut })`; it is
+     * only no longer sourced from authored metadata. No replacement key.
+     */
+    shortcut?: SpecActionInput['shortcut'];
+    /**
+     * @deprecated Retired in `@objectstack/spec` 17 as a `retiredKey()` tombstone —
+     * authoring it is a hard parse rejection, so this resolves to `undefined` and
+     * assigning a value is a compile error. Use the list view's `bulkActions` /
+     * `bulkActionDefs` instead; `ActionEngine.registerAction(action, { bulkEnabled })`
+     * remains available to a HOST passing it explicitly.
+     */
+    bulkEnabled?: SpecActionInput['bulkEnabled'];
     /** Any additional properties */
     [key: string]: any;
 }
-export type ActionHandler = (action: ActionDef, context: ActionContext) => Promise<ActionResult> | ActionResult;
+/**
+ * A handler registered with {@link ActionRunner} — the client-side action
+ * dispatch seam: given an authored `ActionDef` and the invocation context,
+ * produce an `ActionResult`.
+ *
+ * NOT the spec's `ActionHandler` (`@objectstack/spec/ui`), whose name this type
+ * carried until objectstack#4115. That one is the SERVER-side objectql action
+ * handler — a different calling convention entirely (`(ctx) => unknown`, with
+ * validated params and a trusted engine facade on `ctx`) and a different
+ * execution site.
+ */
+export type ActionRunnerHandler = (action: ActionDef, context: ActionContext) => Promise<ActionResult> | ActionResult;
 /**
  * Confirmation handler — replaces window.confirm.
  * Consumers can provide an async implementation (e.g., Shadcn AlertDialog).
@@ -294,6 +411,21 @@ export declare class ActionRunner {
     private navigationHandler;
     private paramCollectionHandler;
     private resultDialogHandler;
+    /**
+     * Built-in dispatch, one entry per runnable action type.
+     *
+     * A table rather than a `switch` because the type annotation is the guard:
+     * `Record<RunnableActionType, …>` stops compiling the moment
+     * `@objectstack/spec` adds an `ActionType` this runner has no executor for.
+     * That is the whole Tier-2 failure class for actions — a spec name that
+     * validates at save and then does nothing at run time (#2942) — converted
+     * into a build error. It also rejects the reverse: an executor keyed by a
+     * name that is neither in the spec nor a declared local alias.
+     *
+     * `navigation` is that declared alias (see `ObjectUiLocalActionType`); it
+     * shares `url`'s navigator.
+     */
+    private readonly builtinExecutors;
     constructor(context?: ActionContext);
     /**
      * Set a custom confirmation handler (e.g., Shadcn AlertDialog).
@@ -322,7 +454,7 @@ export declare class ActionRunner {
      * values the user must copy now (2FA codes, OAuth client_secret).
      */
     setResultDialogHandler(handler: ResultDialogHandler): void;
-    registerHandler(actionName: string, handler: ActionHandler): void;
+    registerHandler(actionName: string, handler: ActionRunnerHandler): void;
     unregisterHandler(actionName: string): void;
     /**
      * Register a named script handler. When a `script` action's
@@ -330,7 +462,7 @@ export declare class ActionRunner {
      * instead of the expression evaluator. Lets dashboards/views wire
      * symbolic action names (e.g. 'export_dashboard_pdf') to JS callbacks.
      */
-    registerScript(scriptName: string, handler: ActionHandler): void;
+    registerScript(scriptName: string, handler: ActionRunnerHandler): void;
     unregisterScript(scriptName: string): void;
     execute(action: ActionDef): Promise<ActionResult>;
     /**
@@ -351,6 +483,21 @@ export declare class ActionRunner {
      * Uses navigationHandler for SPA routing, falls back to window.location.
      */
     private executeUrl;
+    /**
+     * The one navigator behind `type: 'url'` and its `navigation` alias.
+     *
+     * Both names mean "go to a location", and they had two implementations that
+     * drifted: only this one interpolated `${param.X}`, promoted `/api/…` to the
+     * `apiBase`, short-circuited a redirect-dance URL to a full-page load, and
+     * honoured `openIn`. A `navigation` action was quietly the weaker of the two
+     * (#2944 item 3). Sharing the body is what keeps the alias honest.
+     *
+     * `action` supplies the interpolation context (`params`) and `openIn`;
+     * `source` supplies the navigation modifiers, which live on the nested
+     * `action.navigate` block for the legacy shape and on the action itself
+     * otherwise.
+     */
+    private navigateTo;
     /**
      * Execute modal action — open a dialog.
      * Delegates to the registered modalHandler; returns modal schema if no handler.
@@ -361,10 +508,22 @@ export declare class ActionRunner {
      * Delegates to a registered 'flow' handler; otherwise returns not-implemented.
      */
     private executeFlow;
-    private executeActionSchema;
     /**
-     * Execute navigation action
+     * Terminal fallback for a dispatch the switch above did not recognize: no
+     * known `type`, no registered handler, no `navigate` / `api` / `endpoint` /
+     * `onClick`. Some schema-only shapes are still runnable here — an action
+     * whose whole payload is a `redirect`, or an explicit `reload` / `close`
+     * directive — so this stays a real execution path.
+     *
+     * What it must never do is report success for an action it did not run. It
+     * used to return `{ success: true, reload: true, close: true }` for a
+     * COMPLETELY EMPTY schema, which is how a legacy string row action —
+     * dispatched as `{ type: '<action name>' }`, the name landing in the `type`
+     * slot — reached the user as a green "Action completed successfully" toast
+     * having issued zero requests (objectui#2960). An unresolvable dispatch is a
+     * wiring bug; surface it instead of laundering it into a success.
      */
+    private executeActionSchema;
     /**
      * `form` action — open a FormView as a routed page (`/forms/:name`, per the
      * spec). `target` is the FormView name. Without this case the action fell
@@ -373,6 +532,16 @@ export declare class ActionRunner {
      * hosts that support it; the form route ignores unknown query params.
      */
     private executeForm;
+    /**
+     * `navigation` — objectui's alias of the spec's `url` (`ObjectUiLocalActionType`).
+     *
+     * Kept because `{ type: 'navigation', to: … }` is authored today
+     * (`element:button` CTAs) and because deleting the case would not fail loudly:
+     * the action would land in `executeActionSchema` and report success while
+     * navigating nowhere. All it does now is resolve the alias's own spelling of
+     * the target and hand off to the shared navigator, so the two names cannot
+     * drift apart again. Prefer `type: 'url'` + `openIn` in new metadata.
+     */
     private executeNavigation;
     /**
      * Execute API action — supports both simple string endpoint and complex ApiConfig.
@@ -399,9 +568,15 @@ export declare class ActionRunner {
      * fragment.
      *
      * `ctx.origin`, `ctx.user.*`, `ctx.org.*`, `ctx.recordId` are surfaced
-     * implicitly from the runner's ActionContext + window. Consumers can
-     * extend by stuffing extra keys under `context.ctx = {...}` before
-     * calling `runner.execute()`.
+     * implicitly from the runner's ActionContext + window, and
+     * `ctx.selection.ids` / `ctx.selection.count` reflect the grid's current
+     * checkbox selection (`context.selectedRecords`) — `${ctx.selection.ids}`
+     * comma-joins the ids via the standard `String(array)` behaviour, so a
+     * list_toolbar url/api action can carry the selection without any bulk
+     * plumbing (objectui#3139). In an aggregate bulk dispatch,
+     * `${param._selectedIds}` interpolates the same ids from the injected
+     * param. Consumers can extend by stuffing extra keys under
+     * `context.ctx = {...}` before calling `runner.execute()`.
      */
     private interpolateTarget;
     /**