@object-ui/core 16.0.0 → 17.1.0

package/dist/actions/actionKeys.js

@@ -0,0 +1,243 @@
+/**
+ * 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, i.e. step 2's worklist ─────────────────────────
+ * `ActionDef` declares 34 keys, the spec's `ActionSchema` declares 36, and they
+ * overlap on 17. The two halves of the difference are different problems:
+ *
+ * 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 reach readers through the index signature.
+ * `ActionEngine` reads two of them (`visible` at the location filter, `locations`
+ * at registration) through an `as any` cast — a cast that exists ONLY because the
+ * field is undeclared, and that goes away when step 2 promotes them.
+ *
+ * 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`. Several are already marked legacy at their declaration. These
+ * are objectui's own dialect and need the #4115 treatment: kept and documented as
+ * deliberate, or retired — but not silently carried.
+ */
+/**
+ * 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 const ACTION_DEF_KEYS = [
+    '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',
+];
+/**
+ * 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 const SPEC_ACTION_KEYS = [
+    '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 const NAVIGATION_ALIAS_KEYS = ['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 const RETIRED_ACTION_KEYS = {
+    execute: '`execute` was removed in @objectstack/spec 17 (#3855) — rename the key to `target`. ' +
+        'The value (a script name or expression) is unchanged. ' +
+        'Run `os migrate meta --from 16` to rewrite it automatically.',
+};
+/** Every key an action may legitimately carry today. */
+export const KNOWN_ACTION_KEYS = new Set([
+    ...ACTION_DEF_KEYS,
+    ...SPEC_ACTION_KEYS,
+    ...NAVIGATION_ALIAS_KEYS,
+].filter((key) => !(key in RETIRED_ACTION_KEYS)));
+/** Split an action's own keys into the two things worth saying out loud. */
+export function classifyActionKeys(action) {
+    const unknown = [];
+    const retired = [];
+    if (!action || typeof action !== 'object')
+        return { unknown, retired };
+    for (const key of Object.keys(action)) {
+        if (key in RETIRED_ACTION_KEYS)
+            retired.push(key);
+        else if (!KNOWN_ACTION_KEYS.has(key))
+            unknown.push(key);
+    }
+    return { unknown, retired };
+}
+// Warn once per (action, problem), not once per execution: an unrecognized key
+// usually sits in metadata driving a button that gets clicked repeatedly, and a
+// warning that floods the console is a warning that gets muted.
+//
+// Keyed by action name as well as by the keys, deliberately. Keying on the keys
+// alone would report the FIRST action carrying `targt` and stay silent about
+// every other one — sending the author to fix a button that was only the first
+// symptom. The memo is bounded by the number of authored actions either way.
+const warned = new Set();
+/** Reset the warn-once memo. Exported for tests. */
+export function resetActionKeyWarnings() {
+    warned.clear();
+}
+const isDev = () => globalThis.process?.env?.NODE_ENV !==
+    'production';
+/**
+ * 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 function warnOnUnknownActionKeys(action, where = 'ActionRunner') {
+    if (!isDev())
+        return;
+    const { unknown, retired } = classifyActionKeys(action);
+    const name = action?.name ?? action?.type ?? '(unnamed)';
+    for (const key of retired) {
+        const memo = `retired:${String(name)}:${key}`;
+        if (warned.has(memo))
+            continue;
+        warned.add(memo);
+        console.warn(`[${where}] action "${String(name)}" carries the retired key \`${key}\`. ${RETIRED_ACTION_KEYS[key]}`);
+    }
+    if (unknown.length === 0)
+        return;
+    const memo = `unknown:${String(name)}:${unknown.slice().sort().join(',')}`;
+    if (warned.has(memo))
+        return;
+    warned.add(memo);
+    console.warn(`[${where}] action "${String(name)}" carries ${unknown.length === 1 ? 'a key' : 'keys'} no reader ` +
+        `recognizes: \`${unknown.join('`, `')}\`. Nothing will read ${unknown.length === 1 ? 'it' : 'them'} — ` +
+        'check for a typo, or promote the key to an explicit field on `ActionDef` ' +
+        '(packages/core/src/actions/actionKeys.ts). Warned rather than rejected because `ActionDef` ' +
+        'still carries `[key: string]: any`, so the compiler cannot see this (objectstack#4075).');
+}

package/dist/actions/index.d.ts

@@ -7,6 +7,7 @@
  */
 export * from './ActionRunner.js';
 export * from './ActionEngine.js';
+export * from './actionKeys.js';
 export * from './TransactionManager.js';
 export * from './UndoManager.js';
 export * from './bulkFastPath.js';

package/dist/actions/index.js

@@ -7,6 +7,7 @@
  */
 export * from './ActionRunner.js';
 export * from './ActionEngine.js';
+export * from './actionKeys.js';
 export * from './TransactionManager.js';
 export * from './UndoManager.js';
 export * from './bulkFastPath.js';

package/dist/adapters/ApiDataSource.d.ts

@@ -8,7 +8,7 @@
  * A DataSource adapter for the `provider: 'api'` ViewData mode.
  * Makes raw HTTP requests using the HttpRequest configs from ViewData.
  */
-import type { DataSource, QueryParams, QueryResult, HttpRequest, AggregateParams, AggregateResult } from '@object-ui/types';
+import type { DataSource, BatchTransactionOperation, QueryParams, QueryResult, HttpRequest, AggregateParams, AggregateResult } from '@object-ui/types';
 export interface ApiDataSourceConfig {
     /** HttpRequest config for read operations (find, findOne) */
     read?: HttpRequest;
@@ -54,6 +54,16 @@ export declare class ApiDataSource<T = any> implements DataSource<T> {
     delete(_resource: string, id: string | number, opts?: {
         ifMatch?: string;
     }): Promise<boolean>;
+    /**
+     * Client-side (non-atomic) cross-object batch — a generic REST endpoint has
+     * no transactional batch primitive, so this delegates to the shared
+     * emulation (sequential writes + `$ref` resolution + best-effort
+     * compensation). Adapters fronting a server that DOES offer an atomic batch
+     * should override this to issue a single request.
+     */
+    batchTransaction(operations: BatchTransactionOperation[]): Promise<{
+        results: any[];
+    }>;
     getObjectSchema(_objectName: string): Promise<any>;
     getView(_objectName: string, _viewId: string): Promise<any | null>;
     getApp(_appId: string): Promise<any | null>;

package/dist/adapters/ApiDataSource.js

@@ -8,6 +8,7 @@
  * A DataSource adapter for the `provider: 'api'` ViewData mode.
  * Makes raw HTTP requests using the HttpRequest configs from ViewData.
  */
+import { emulateBatchTransaction } from './batchTransaction.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -43,7 +44,16 @@ function queryParamsToRecord(params) {
         out.$filter = JSON.stringify(params.$filter);
     }
     if (params.$orderby) {
-        if (Array.isArray(params.$orderby)) {
+        if (typeof params.$orderby === 'string') {
+            // Already an OData order clause ('name asc', 'a asc,b desc'). It MUST be
+            // passed through verbatim: the `Object.entries` branch below would walk a
+            // string index-by-index and emit `0 n,1 a,2 m,…`, which the server dutifully
+            // sorts by — columns that don't exist — and the whole page comes back empty
+            // (objectstack#3821). Callers that build the clause by hand (ObjectGrid's
+            // schema `sort`, RecipientPickerField) hit exactly that.
+            out.$orderby = params.$orderby;
+        }
+        else if (Array.isArray(params.$orderby)) {
             if (typeof params.$orderby[0] === 'string') {
                 out.$orderby = params.$orderby.join(',');
             }
@@ -241,6 +251,16 @@ export class ApiDataSource {
             return false;
         }
     }
+    /**
+     * Client-side (non-atomic) cross-object batch — a generic REST endpoint has
+     * no transactional batch primitive, so this delegates to the shared
+     * emulation (sequential writes + `$ref` resolution + best-effort
+     * compensation). Adapters fronting a server that DOES offer an atomic batch
+     * should override this to issue a single request.
+     */
+    batchTransaction(operations) {
+        return emulateBatchTransaction(this, operations);
+    }
     async getObjectSchema(_objectName) {
         // Generic API endpoints typically don't expose schema metadata.
         // Return a minimal stub so schema-dependent components don't crash.

package/dist/adapters/ValueDataSource.d.ts

@@ -8,7 +8,7 @@
  * A DataSource adapter for the `provider: 'value'` ViewData mode.
  * Operates entirely on an in-memory array — no network requests.
  */
-import type { DataSource, MutationEvent, QueryParams, QueryResult, AggregateParams, AggregateResult } from '@object-ui/types';
+import type { DataSource, BatchTransactionOperation, DataSourceMutationEvent, QueryParams, QueryResult, AggregateParams, AggregateResult } from '@object-ui/types';
 export interface ValueDataSourceConfig<T = any> {
     /** The static data array */
     items: T[];
@@ -48,11 +48,19 @@ export declare class ValueDataSource<T = any> implements DataSource<T> {
     update(_resource: string, id: string | number, data: Partial<T>): Promise<T>;
     delete(_resource: string, id: string | number): Promise<boolean>;
     bulk(_resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]>;
+    /**
+     * Client-side (non-atomic) cross-object batch — this in-memory adapter has
+     * no server transaction, so it delegates to the shared emulation. Per-op
+     * MutationEvents come from the `create`/`update`/`delete` primitives above.
+     */
+    batchTransaction(operations: BatchTransactionOperation[]): Promise<{
+        results: any[];
+    }>;
     getObjectSchema(_objectName: string): Promise<any>;
     getView(_objectName: string, _viewId: string): Promise<any | null>;
     getApp(_appId: string): Promise<any | null>;
     aggregate(_resource: string, params: AggregateParams): Promise<AggregateResult[]>;
-    onMutation(callback: (event: MutationEvent<T>) => void): () => void;
+    onMutation(callback: (event: DataSourceMutationEvent<T>) => void): () => void;
     /** Get the current number of items */
     get count(): number;
     /** Get a snapshot of all items (cloned) */

package/dist/adapters/ValueDataSource.js

@@ -8,6 +8,7 @@
  * A DataSource adapter for the `provider: 'value'` ViewData mode.
  * Operates entirely on an in-memory array — no network requests.
  */
+import { emulateBatchTransaction } from './batchTransaction.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -341,6 +342,14 @@ export class ValueDataSource {
         }
         return results;
     }
+    /**
+     * Client-side (non-atomic) cross-object batch — this in-memory adapter has
+     * no server transaction, so it delegates to the shared emulation. Per-op
+     * MutationEvents come from the `create`/`update`/`delete` primitives above.
+     */
+    batchTransaction(operations) {
+        return emulateBatchTransaction(this, operations);
+    }
     async getObjectSchema(_objectName) {
         // Infer a minimal schema from the first item
         if (this.items.length === 0)

package/dist/adapters/batchTransaction.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ObjectUI — batchTransaction emulation
+ * 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.
+ *
+ * Client-side emulation of {@link DataSource.batchTransaction} for adapters
+ * that lack a server-side transactional batch endpoint. This is the single,
+ * tested home for the non-atomic fallback (ObjectStack objectui #2679 /
+ * framework #1604 / ADR-0034 item 4): components call `runBatchTransaction`
+ * unconditionally and never orchestrate cross-object writes themselves.
+ *
+ * The emulation runs operations sequentially — NOT the old `bulk('create')`
+ * grouping — because sequential execution is what makes `{ $ref: i }`
+ * resolution and ordered semantics correct (a child create must observe the
+ * parent's freshly-minted id). Line-item counts are small, so the extra
+ * round-trips are acceptable.
+ */
+import type { BatchTransactionOperation, DataSource } from '@object-ui/types';
+/**
+ * Emulate an atomic batch over a plain DataSource by executing its `create`/
+ * `update`/`delete` primitives in order.
+ *
+ * NOT atomic: on failure it best-effort compensates by deleting the records
+ * it created (reverse order — children before parent), then rethrows the
+ * original error. Updates and deletes that already ran cannot be undone; a
+ * compensation delete that itself fails is swallowed (`Promise.allSettled`).
+ * This is the documented reason a server-backed `batchTransaction` is
+ * strictly better — a true transaction simply never commits.
+ *
+ * MutationEvents are deliberately NOT emitted here: the underlying
+ * `create`/`update`/`delete` primitives already emit per-op on adapters that
+ * support `onMutation`, so emitting here too would double-fire.
+ */
+export declare function emulateBatchTransaction<T = any>(dataSource: DataSource<T>, operations: BatchTransactionOperation[]): Promise<{
+    results: any[];
+}>;
+/**
+ * Persist an ordered cross-object batch, preferring the adapter's native
+ * (potentially atomic) `batchTransaction` and falling back to
+ * {@link emulateBatchTransaction} when the adapter does not implement it.
+ *
+ * This is the single entry point UI components should call — they stay
+ * ignorant of whether the underlying save is truly atomic.
+ */
+export declare function runBatchTransaction<T = any>(dataSource: DataSource<T>, operations: BatchTransactionOperation[]): Promise<{
+    results: any[];
+}>;

package/dist/adapters/batchTransaction.js

@@ -0,0 +1,118 @@
+/**
+ * ObjectUI — batchTransaction emulation
+ * 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.
+ *
+ * Client-side emulation of {@link DataSource.batchTransaction} for adapters
+ * that lack a server-side transactional batch endpoint. This is the single,
+ * tested home for the non-atomic fallback (ObjectStack objectui #2679 /
+ * framework #1604 / ADR-0034 item 4): components call `runBatchTransaction`
+ * unconditionally and never orchestrate cross-object writes themselves.
+ *
+ * The emulation runs operations sequentially — NOT the old `bulk('create')`
+ * grouping — because sequential execution is what makes `{ $ref: i }`
+ * resolution and ordered semantics correct (a child create must observe the
+ * parent's freshly-minted id). Line-item counts are small, so the extra
+ * round-trips are acceptable.
+ */
+/** Best-effort id extraction across the record shapes adapters return. */
+function idOf(rec) {
+    if (rec == null)
+        return undefined;
+    return rec.id ?? rec._id ?? rec.recordId;
+}
+/**
+ * Replace top-level `{ $ref: i }` values in an op payload with the id produced
+ * by operation `i`. Only backward references are valid — a forward or
+ * unresolved ref throws (the builders only ever emit `{ $ref: 0 }` pointing at
+ * an already-executed parent, so this is a guard, not a normal path).
+ */
+function resolveRefs(data, results) {
+    const out = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (value &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            typeof value.$ref === 'number') {
+            const refIndex = value.$ref;
+            const id = idOf(results[refIndex]);
+            if (id === undefined) {
+                throw new Error(`batchTransaction: field "${key}" references operation ${refIndex}, ` +
+                    `which has not produced an id (forward or invalid $ref)`);
+            }
+            out[key] = id;
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * Emulate an atomic batch over a plain DataSource by executing its `create`/
+ * `update`/`delete` primitives in order.
+ *
+ * NOT atomic: on failure it best-effort compensates by deleting the records
+ * it created (reverse order — children before parent), then rethrows the
+ * original error. Updates and deletes that already ran cannot be undone; a
+ * compensation delete that itself fails is swallowed (`Promise.allSettled`).
+ * This is the documented reason a server-backed `batchTransaction` is
+ * strictly better — a true transaction simply never commits.
+ *
+ * MutationEvents are deliberately NOT emitted here: the underlying
+ * `create`/`update`/`delete` primitives already emit per-op on adapters that
+ * support `onMutation`, so emitting here too would double-fire.
+ */
+export async function emulateBatchTransaction(dataSource, operations) {
+    const results = [];
+    const created = [];
+    try {
+        for (const op of operations) {
+            const action = op.action ?? 'create';
+            if (action === 'create') {
+                const record = await dataSource.create(op.object, resolveRefs(op.data ?? {}, results));
+                results.push(record);
+                const id = idOf(record);
+                if (id)
+                    created.push({ object: op.object, id });
+            }
+            else if (action === 'update') {
+                if (op.id == null) {
+                    throw new Error(`batchTransaction: update on "${op.object}" requires an id`);
+                }
+                results.push(await dataSource.update(op.object, op.id, resolveRefs(op.data ?? {}, results)));
+            }
+            else {
+                if (op.id == null) {
+                    throw new Error(`batchTransaction: delete on "${op.object}" requires an id`);
+                }
+                results.push(await dataSource.delete(op.object, op.id));
+            }
+        }
+        return { results };
+    }
+    catch (err) {
+        // Best-effort compensation: undo the creates we made, newest first, so a
+        // child is removed before the parent it points at. Failures are ignored —
+        // there is nothing more we can do client-side.
+        if (created.length > 0) {
+            await Promise.allSettled([...created].reverse().map((c) => dataSource.delete(c.object, c.id)));
+        }
+        throw err;
+    }
+}
+/**
+ * Persist an ordered cross-object batch, preferring the adapter's native
+ * (potentially atomic) `batchTransaction` and falling back to
+ * {@link emulateBatchTransaction} when the adapter does not implement it.
+ *
+ * This is the single entry point UI components should call — they stay
+ * ignorant of whether the underlying save is truly atomic.
+ */
+export function runBatchTransaction(dataSource, operations) {
+    return typeof dataSource.batchTransaction === 'function'
+        ? dataSource.batchTransaction(operations)
+        : emulateBatchTransaction(dataSource, operations);
+}

package/dist/adapters/index.d.ts

@@ -8,3 +8,4 @@
 export { ApiDataSource, type ApiDataSourceConfig } from './ApiDataSource.js';
 export { ValueDataSource, type ValueDataSourceConfig } from './ValueDataSource.js';
 export { resolveDataSource, type ResolveDataSourceOptions } from './resolveDataSource.js';
+export { emulateBatchTransaction, runBatchTransaction } from './batchTransaction.js';

package/dist/adapters/index.js

@@ -11,3 +11,4 @@
 export { ApiDataSource } from './ApiDataSource.js';
 export { ValueDataSource } from './ValueDataSource.js';
 export { resolveDataSource } from './resolveDataSource.js';
+export { emulateBatchTransaction, runBatchTransaction } from './batchTransaction.js';

package/dist/evaluator/ExpressionEvaluator.d.ts

@@ -86,6 +86,16 @@ export declare class ExpressionEvaluator {
         dialect?: string;
         source?: string;
     }, options?: EvaluationOptions): boolean;
+    /**
+     * Evaluate a `{ dialect: 'cel' }` predicate on the canonical `@objectstack/formula`
+     * engine (via `evalFieldPredicate`), binding this evaluator's context: the
+     * `record` key as the `record` namespace and the whole context bag as top-level
+     * scope so `record.*`, `features.*`, `user.*`, `app.*` all resolve. Fail-soft to
+     * `true` (visible/enabled — the legacy default) unless the caller opted into
+     * `throwOnError`, in which case a *faulting* predicate (bad field / non-CEL
+     * syntax) throws; a genuine `false` never throws.
+     */
+    private evaluateCelCondition;
     /**
      * Update the context with new data
      */

package/dist/evaluator/ExpressionEvaluator.js

@@ -17,6 +17,7 @@
 import { ExpressionContext } from './ExpressionContext.js';
 import { ExpressionCache } from './ExpressionCache.js';
 import { FormulaFunctions } from './FormulaFunctions.js';
+import { evalFieldPredicate } from './fieldRules.js';
 /**
  * Expression evaluator for dynamic UI expressions
  */
@@ -141,6 +142,10 @@ export class ExpressionEvaluator {
             return compiled.fn(...varValues);
         }
         catch (error) {
+            // The original error's message is inlined below. We can't pass it as the
+            // `Error` `cause` option because this package targets ES2020, whose lib
+            // types the 1-arg `Error` constructor only; hence the scoped disable.
+            // eslint-disable-next-line preserve-caught-error
             throw new Error(`Failed to evaluate expression "${expression}": ${error.message}`);
         }
     }
@@ -177,6 +182,18 @@ export class ExpressionEvaluator {
         if (typeof condition === 'boolean') {
             return condition;
         }
+        // #2661 — a CEL-dialect envelope routes to the canonical `@objectstack/formula`
+        // engine (the one `fieldRules` / list conditionals already use), NOT the legacy
+        // JS evaluator below. This makes a component / action `visible` / `disabled`
+        // predicate reach the SAME verdict as server enforcement — including CEL-only
+        // behavior like `record.due_date == today()` (framework#3205). Bare strings and
+        // `${…}` templates stay on the legacy path (back-compat deprecation window);
+        // only an explicit `{ dialect: 'cel' }` envelope is rerouted.
+        if (condition && typeof condition === 'object'
+            && condition.dialect === 'cel'
+            && typeof condition.source === 'string') {
+            return this.evaluateCelCondition(condition.source, options);
+        }
         // Unwrap Expression envelope (see `evaluate` for rationale).
         if (condition && typeof condition === 'object' && typeof condition.source === 'string') {
             condition = condition.source;
@@ -215,6 +232,37 @@ export class ExpressionEvaluator {
             return true;
         }
     }
+    /**
+     * Evaluate a `{ dialect: 'cel' }` predicate on the canonical `@objectstack/formula`
+     * engine (via `evalFieldPredicate`), binding this evaluator's context: the
+     * `record` key as the `record` namespace and the whole context bag as top-level
+     * scope so `record.*`, `features.*`, `user.*`, `app.*` all resolve. Fail-soft to
+     * `true` (visible/enabled — the legacy default) unless the caller opted into
+     * `throwOnError`, in which case a *faulting* predicate (bad field / non-CEL
+     * syntax) throws; a genuine `false` never throws.
+     */
+    evaluateCelCondition(source, options) {
+        if (!source.trim())
+            return true; // no predicate → visible/enabled
+        const bag = this.context.toObject();
+        const rec = bag.record;
+        const record = (rec && typeof rec === 'object' && !Array.isArray(rec))
+            ? rec
+            : bag;
+        if (!options.throwOnError) {
+            // Fast path: one evaluation, fail-soft to visible/enabled (legacy parity).
+            return evalFieldPredicate(source, record, true, undefined, bag);
+        }
+        // Fail-closed callers need to tell a genuine `false` from a fault. The
+        // canonical helper fails soft to the fallback, so a value that tracks the
+        // fallback in BOTH runs means the predicate faulted — then we throw.
+        const asTrue = evalFieldPredicate(source, record, true, undefined, bag);
+        const asFalse = evalFieldPredicate(source, record, false, undefined, bag);
+        if (asTrue !== asFalse) {
+            throw new Error(`CEL predicate failed to evaluate: ${source}`);
+        }
+        return asTrue;
+    }
     /**
      * Update the context with new data
      */