@object-ui/core 16.1.0 → 17.2.0

package/dist/actions/ActionRunner.js

@@ -5,16 +5,9 @@
  * 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 { ExpressionEvaluator } from '../evaluator/ExpressionEvaluator';
 import { globalUndoManager } from './UndoManager';
+import { warnOnUnknownActionKeys } from './actionKeys';
 /**
  * Bind the server-CEL-parity `os.user` identity alias into an action context
  * (#2358 trap 1). `@objectstack/spec` documents the canonical CEL identity
@@ -96,6 +89,34 @@ export class ActionRunner {
             writable: true,
             value: void 0
         });
+        /**
+         * 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.
+         */
+        Object.defineProperty(this, "builtinExecutors", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: {
+                script: (action) => this.executeScript(action),
+                url: (action) => this.executeUrl(action),
+                modal: (action) => this.executeModal(action),
+                flow: (action) => this.executeFlow(action),
+                api: (action) => this.executeAPI(action),
+                form: (action) => this.executeForm(action),
+                navigation: (action) => this.executeNavigation(action),
+            }
+        });
         this.context = withIdentityAlias(context);
         this.evaluator = new ExpressionEvaluator(this.context);
         // Default confirmation: window.confirm (can be overridden)
@@ -165,6 +186,11 @@ export class ActionRunner {
     }
     async execute(action) {
         try {
+            // `ActionDef` accepts any key of any type, so a typo (`targt`) and a
+            // retired key (`execute`) both reach here having type-checked. Neither
+            // binds a handler, and binding no handler silently is the #2169 "Mark Done
+            // does nothing" shape. Dev-only, warn-once, changes nothing (#4075 step 1).
+            warnOnUnknownActionKeys(action);
             // Resolve the action type
             const actionType = action.type || action.actionType || action.name || '';
             // Conditional execution
@@ -237,45 +263,27 @@ export class ActionRunner {
                 await this.handlePostExecution(action, result);
                 return result;
             }
-            // Built-in action execution by type
+            // Built-in action execution by type.
             let result;
-            switch (actionType) {
-                case 'script':
-                    result = await this.executeScript(action);
-                    break;
-                case 'url':
-                    result = await this.executeUrl(action);
-                    break;
-                case 'modal':
-                    result = await this.executeModal(action);
-                    break;
-                case 'flow':
-                    result = await this.executeFlow(action);
-                    break;
-                case 'api':
-                    result = await this.executeAPI(action);
-                    break;
-                case 'form':
-                    result = await this.executeForm(action);
-                    break;
-                case 'navigation':
-                    result = await this.executeNavigation(action);
-                    break;
-                default:
-                    // Legacy fallback: check for navigate, api, or onClick
-                    if (action.navigate) {
-                        result = await this.executeNavigation(action);
-                    }
-                    else if (action.api || action.endpoint) {
-                        result = await this.executeAPI(action);
-                    }
-                    else if (action.onClick) {
-                        await action.onClick();
-                        result = { success: true };
-                    }
-                    else {
-                        result = await this.executeActionSchema(action);
-                    }
+            const builtin = actionType
+                ? this.builtinExecutors[actionType]
+                : undefined;
+            if (builtin) {
+                result = await builtin(action);
+            }
+            else if (action.navigate) {
+                // Legacy fallback: check for navigate, api, or onClick
+                result = await this.executeNavigation(action);
+            }
+            else if (action.api || action.endpoint) {
+                result = await this.executeAPI(action);
+            }
+            else if (action.onClick) {
+                await action.onClick();
+                result = { success: true };
+            }
+            else {
+                result = await this.executeActionSchema(action);
             }
             await this.handlePostExecution(action, result);
             return result;
@@ -424,8 +432,38 @@ export class ActionRunner {
      * Supports ${} template expressions referencing data, record, user context.
      */
     async executeScript(action) {
-        const script = action.execute || action.target;
+        // `target` is the only handler slot. The `execute` alias was removed in
+        // @objectstack/spec 17 (#3855), which rejects an authored `execute` at parse
+        // with the rename prescription — so parsed metadata cannot carry it and a
+        // `target || execute` fallback could only ever evaluate to `target` (#3856).
+        const script = action.target;
         if (!script) {
+            // A spec `body` IS a script — this runner just cannot run one (see the
+            // `body` field docs). Saying "no script provided" would send the author
+            // hunting for a missing field they actually wrote, so name the real
+            // cause and the remedy instead. Checked before the retired `execute` key:
+            // a `body` action ignores `target`, so "rename it" would be wrong advice.
+            if (action.body != null) {
+                return {
+                    success: false,
+                    error: 'Action body must be executed server-side — this client runner does not interpret ' +
+                        '`body` (sandboxed JS needs an isolated VM; expression bodies use the formula engine). ' +
+                        'Register a `script` handler that POSTs to /api/v1/actions/{object}/{action}.',
+                };
+            }
+            // ActionDef is open-ended (`[key: string]: any`), so hand-authored
+            // metadata that never passed through the spec parser still compiles with
+            // the retired key. Carry the same prescription the spec's tombstone does,
+            // for the same reason: a bare "no script provided" reads as "you forgot a
+            // field" to an author who did write one.
+            if (typeof action.execute === 'string') {
+                return {
+                    success: false,
+                    error: '`execute` was removed in @objectstack/spec 17 — rename the key to `target`. ' +
+                        'The value (a script name or expression) is unchanged. ' +
+                        'Run `os migrate meta --from 16` to rewrite it automatically.',
+                };
+            }
             return { success: false, error: 'No script provided for script action' };
         }
         // Named script registry wins over the expression evaluator. This lets
@@ -464,6 +502,23 @@ export class ActionRunner {
         if (!rawUrl) {
             return { success: false, error: 'No URL provided for url action' };
         }
+        return this.navigateTo(action, rawUrl, action);
+    }
+    /**
+     * 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.
+     */
+    async navigateTo(action, rawUrl, source) {
         // Apply target ${param.X} / ${ctx.X} interpolation FIRST — the
         // ExpressionEvaluator that follows would otherwise see unresolved
         // `param.provider` and either error or substitute undefined. Doing it
@@ -487,7 +542,9 @@ export class ActionRunner {
         if (apiBase && /^\/(api|_auth|_account)\//.test(url)) {
             url = `${apiBase}${url}`;
         }
-        const isExternal = url.startsWith('http://') || url.startsWith('https://');
+        // `source.external` is the `navigation` shape's explicit override; the
+        // scheme heuristic covers every other case.
+        const isExternal = Boolean(source.external) || url.startsWith('http://') || url.startsWith('https://');
         // Same-origin API endpoints (most commonly the auth provider's
         // `/api/v1/auth/sign-in/social` redirect dance) issue server-side
         // 302s that must be followed by the *browser*, not the SPA router.
@@ -505,13 +562,22 @@ export class ActionRunner {
             return { success: true };
         }
         // `openIn` is the first-class, declarative switch (ActionSchema.openIn);
-        // it wins over the legacy `params.newTab` escape hatch and the
-        // external-URL heuristic.
-        const newTab = action.openIn === 'new-tab' ? true
-            : action.openIn === 'self' ? false
-                : (action.params?.newTab ?? isExternal);
+        // it wins over the legacy `navigate.newTab` / `params.newTab` escape
+        // hatches and the external-URL heuristic.
+        const openIn = source.openIn ?? action.openIn;
+        const newTab = openIn === 'new-tab' ? true
+            : openIn === 'self' ? false
+                : (source.newTab ?? action.params?.newTab ?? isExternal);
+        // History semantics, the one thing the `navigation` shape carries that
+        // `ActionSchema` has no field for. Omitted from the handler call when
+        // unset so hosts see the same options object they always did.
+        const replace = source.replace ?? action.replace;
         if (this.navigationHandler) {
-            this.navigationHandler(url, { external: isExternal, newTab });
+            this.navigationHandler(url, {
+                external: isExternal,
+                newTab,
+                ...(replace === undefined ? {} : { replace: Boolean(replace) }),
+            });
             return { success: true };
         }
         if (newTab) {
@@ -556,9 +622,37 @@ export class ActionRunner {
             error: `Flow handler not registered. Cannot execute flow: ${flowName}`,
         };
     }
+    /**
+     * 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.
+     */
     async executeActionSchema(action) {
+        const hasApi = !!(action.api || action.endpoint);
+        // `reload`/`close` default to true downstream, so only an EXPLICIT `true`
+        // counts as declared intent — otherwise every empty schema would look like
+        // it asked for a reload and slip back through this guard.
+        const declaresBehavior = hasApi || !!action.onClick || !!action.redirect
+            || action.reload === true || action.close === true;
+        if (!declaresBehavior) {
+            const label = action.name || action.type || action.actionType || 'action';
+            return {
+                success: false,
+                error: `Action "${label}" is not executable: no handler is registered under that name and it declares no api, endpoint, navigate, redirect or onClick.`,
+            };
+        }
         const result = { success: true };
-        if (action.api || action.endpoint) {
+        if (hasApi) {
             const apiResult = await this.executeAPI(action);
             if (!apiResult.success)
                 return apiResult;
@@ -574,9 +668,6 @@ export class ActionRunner {
         }
         return result;
     }
-    /**
-     * Execute navigation action
-     */
     /**
      * `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
@@ -599,31 +690,23 @@ export class ActionRunner {
         }
         return { success: true, redirect: to };
     }
+    /**
+     * `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.
+     */
     async executeNavigation(action) {
-        const nav = action.navigate || action;
-        const to = this.evaluator.evaluate(nav.to || nav.target);
-        if (!this.isValidUrl(to)) {
-            return {
-                success: false,
-                error: 'Invalid URL scheme. Only http://, https://, and relative URLs are allowed.',
-            };
-        }
-        const isExternal = nav.external || (typeof to === 'string' && (to.startsWith('http://') || to.startsWith('https://')));
-        if (this.navigationHandler) {
-            this.navigationHandler(to, {
-                external: isExternal,
-                newTab: nav.newTab ?? isExternal,
-                replace: nav.replace,
-            });
-            return { success: true };
-        }
-        if (isExternal) {
-            window.open(to, '_blank', 'noopener,noreferrer');
-        }
-        else {
-            return { success: true, redirect: to };
+        const nav = (action.navigate || action);
+        const rawUrl = nav.to || nav.target || nav.redirect;
+        if (!rawUrl) {
+            return { success: false, error: 'No URL provided for navigation action' };
         }
-        return { success: true };
+        return this.navigateTo(action, rawUrl, nav);
     }
     /**
      * Execute API action — supports both simple string endpoint and complex ApiConfig.
@@ -719,9 +802,15 @@ export 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()`.
      */
     interpolateTarget(target, action) {
         if (typeof target !== 'string' || target.indexOf('${') === -1)
@@ -756,6 +845,22 @@ export class ActionRunner {
             user: this.context.user ?? {},
             org: this.context.org ?? this.context.organization ?? {},
             recordId: this.context.record?.id ?? this.context.recordId,
+            // Current list selection (published by the grid as `selectedRecords`).
+            // `${ctx.selection.ids}` in a url/api target comma-joins the ids —
+            // String(array) — giving toolbar actions selection access without any
+            // bulk-executor involvement (objectui#3139). Empty when nothing is
+            // selected, so authors can treat "" as "no selection".
+            selection: {
+                ids: Array.isArray(this.context.selectedRecords)
+                    ? this.context.selectedRecords
+                        .map((r) => r?.id)
+                        .filter((v) => v != null)
+                        .map(String)
+                    : [],
+                count: Array.isArray(this.context.selectedRecords)
+                    ? this.context.selectedRecords.length
+                    : 0,
+            },
         };
         if (this.context.ctx && typeof this.context.ctx === 'object') {
             Object.assign(ctx, this.context.ctx);

package/dist/actions/actionKeys.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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.
+ */
+/**
+ * What an action is allowed to carry — objectstack#4075 step 1.
+ *
+ * `ActionDef` ends with `[key: string]: any`, so it accepts any key of any type.
+ * Concretely (objectui#2990): deleting `ActionDef.execute` produced ZERO compile
+ * errors even though the field had just been removed, and stale metadata still
+ * authoring `execute: 'markDone'` type-checks today. The same deletion against
+ * `@object-ui/types`' `ActionSchema` — which has no index signature — correctly
+ * produced `TS2353` at the authoring site. One of the two readers can catch a
+ * retired key; the other is structurally incapable.
+ *
+ * That asymmetry is the issue. An open key set on a DECLARED METADATA CONTRACT
+ * is what lets a typo (`targt`, `exectue`) and a tombstoned key (`execute`) both
+ * sail through to a runner that then silently does nothing — the #2169 "Mark
+ * Done does nothing" shape.
+ *
+ * This module is step 1 of the staged narrowing: it makes the key set VISIBLE
+ * and warns on anything outside it, without changing a single type. Nothing
+ * breaks, and an invisible failure becomes an audible one. Steps 2 and 3 —
+ * promoting the legitimate keys to explicit optional fields, then removing the
+ * index signature — are what finally let `tsc` catch typos and retired keys.
+ *
+ * The lists are pinned by `__tests__/actionKeys.pin.test.ts`, which re-derives
+ * each one from its actual source. A hand-maintained list that drifts from the
+ * interface it mirrors would be the same "declared ≠ enforced" trap this whole
+ * thread is about.
+ *
+ * ── What the inventory found, and what step 2 did with it ────────────────────
+ * Step 1 found `ActionDef` declaring 34 keys against the spec `ActionSchema`'s
+ * 36, overlapping on 17. The two halves of the difference were different
+ * problems, and step 2 (objectstack#4075) treated them differently:
+ *
+ * 18 keys the SPEC owns that `ActionDef` never declared — `ai`, `aria`,
+ * `bodyExtra`, `bodyShape`, `bulkEnabled`, `component`, `icon`, `locations`,
+ * `mode`, `objectName`, `order`, `recordIdField`, `recordIdParam`,
+ * `requiredPermissions`, `requiresFeature`, `shortcut`, `variant`, `visible`.
+ * These are authored today and used to reach readers through the index
+ * signature. **Step 2 promoted all 18 to explicit optional fields**, typed by
+ * DERIVATION from `@objectstack/spec`'s `ActionInput` rather than by hand-copied
+ * shapes. The `as any` casts `ActionEngine` needed to read `visible`,
+ * `locations` and `requiredPermissions` are gone with them — those casts existed
+ * only because the fields were undeclared.
+ *
+ * Two of the 18 landed as `undefined` rather than as usable types, which is the
+ * correct outcome: spec 17 retired `shortcut` and `bulkEnabled` as `retiredKey()`
+ * tombstones (`z.never()`), so deriving turns "authoring this is a parse
+ * rejection" into a compile error at no cost. Hand-copying would have quietly
+ * re-legitimized two dead keys — which is why the types are derived.
+ *
+ * 17 keys `ActionDef` declares that the spec does not own — `actionType`, `api`,
+ * `chain`, `chainMode`, `close`, `condition`, `confirm`, `endpoint`, `modal`,
+ * `navigate`, `onClick`, `onFailure`, `onSuccess`, `redirect`, `reload`, `toast`,
+ * `actionParams`. Step 2 marked `@deprecated`, with the spec spelling to use
+ * instead, ONLY the four the runner itself proves are aliases: `actionType` (→
+ * `type`), `api` and `endpoint` (→ `target`; `executeAPI` resolves
+ * `api || endpoint || target`), and `navigate` (→ flat `target`/`openIn`;
+ * `executeNavigation` already falls back to them). The rest are runner mechanics
+ * with no spec counterpart — chaining, toasts, post-execution reload/close — and
+ * deprecating them toward a spelling that does not exist would be worse than
+ * leaving them declared.
+ *
+ * Step 3 remains: remove the index signature, at which point `tsc` catches both
+ * typos and retired keys and the dev-mode warning below can retire with it.
+ */
+/**
+ * Every property `ActionDef` declares, in declaration order.
+ *
+ * Kept as data because TypeScript types do not survive to runtime — and
+ * `keyof ActionDef` cannot substitute for this list: the index signature widens
+ * it to `string | number`, which is precisely the problem being worked around.
+ */
+export declare const ACTION_DEF_KEYS: readonly ["type", "actionType", "name", "label", "confirmText", "confirm", "condition", "disabled", "api", "endpoint", "method", "navigate", "onClick", "reload", "close", "redirect", "toast", "successMessage", "errorMessage", "refreshAfter", "undoable", "params", "actionParams", "resultDialog", "target", "body", "openIn", "modal", "chain", "chainMode", "onSuccess", "onFailure", "opensInNewTab", "newTabUrl", "locations", "visible", "requiredPermissions", "icon", "variant", "order", "component", "objectName", "ai", "aria", "bodyExtra", "bodyShape", "mode", "recordIdField", "recordIdParam", "requiresFeature", "shortcut", "bulkEnabled"];
+/**
+ * Every property `@objectstack/spec`'s `ActionSchema` declares.
+ *
+ * `ActionDef` mirrors that schema, so a key the spec owns is legitimate even
+ * when `ActionDef` has not declared it yet — several are read today only through
+ * an `as any` cast (`visible` and `locations` in `ActionEngine`), which is the
+ * cast this list exists to eventually retire.
+ *
+ * Pinned rather than read off the schema at runtime: the spec exports
+ * `ActionSchema` as a lazy proxy that does not forward `.shape`, so resolving it
+ * means walking zod internals (`_def.in` / `_def.innerType`). That is fine in a
+ * test and wrong in shipped code — `@object-ui/types` made the same call for
+ * `ActionComponent`. The pin test does the walk and fails the day this drifts.
+ */
+export declare const SPEC_ACTION_KEYS: readonly ["ai", "aria", "body", "bodyExtra", "bodyShape", "bulkEnabled", "component", "confirmText", "disabled", "errorMessage", "execute", "icon", "label", "locations", "method", "mode", "name", "newTabUrl", "objectName", "openIn", "opensInNewTab", "order", "params", "recordIdField", "recordIdParam", "refreshAfter", "requiredPermissions", "requiresFeature", "resultDialog", "shortcut", "successMessage", "target", "type", "undoable", "variant", "visible"];
+/**
+ * The `navigation` alias's own spelling of a target, read off the action itself
+ * when no nested `navigate` object is present (`ActionRunner.executeNavigation`).
+ *
+ * A declared objectui-side dialect, not spec vocabulary: `replace` is documented
+ * at its read site as "the one thing the `navigation` shape carries that
+ * `ActionSchema` has no field for". Listing it here is what keeps it from being
+ * silent dialect — the alternative is a warning that cries wolf on a shape the
+ * runner itself supports.
+ */
+export declare const NAVIGATION_ALIAS_KEYS: readonly ["to", "external", "newTab", "replace"];
+/**
+ * Keys the spec has TOMBSTONED: still present in `ActionSchema` so the parser can
+ * reject them BY NAME with a rename prescription, rather than fail with a bare
+ * "unrecognized key".
+ *
+ * Warned about separately from unknown keys, and more loudly: an unknown key is
+ * probably a typo, while a retired key is metadata that used to work. That
+ * distinction is why `executeScript` carries a runtime branch returning the
+ * rename prescription — a branch that exists solely to compensate for the index
+ * signature, and that can retire with it in step 3.
+ */
+export declare const RETIRED_ACTION_KEYS: Readonly<Record<string, string>>;
+/** Every key an action may legitimately carry today. */
+export declare const KNOWN_ACTION_KEYS: ReadonlySet<string>;
+/** Split an action's own keys into the two things worth saying out loud. */
+export declare function classifyActionKeys(action: object | null | undefined): {
+    unknown: string[];
+    retired: string[];
+};
+/** Reset the warn-once memo. Exported for tests. */
+export declare function resetActionKeyWarnings(): void;
+/**
+ * Dev-mode only: name the keys an action carries that no reader will ever look
+ * at. Non-breaking by construction — it changes no types and rejects nothing.
+ *
+ * Silently binding no handler is the #2169 "Mark Done does nothing" shape, and
+ * the compiler cannot help while the index signature stands. Until it comes
+ * down, this is the audible half.
+ */
+export declare function warnOnUnknownActionKeys(action: object | null | undefined, where?: string): void;