@object-ui/core 3.0.2 → 3.1.0

package/.turbo/turbo-build.log

@@ -1,4 +1,4 @@
 
-> @object-ui/core@3.0.2 build /home/runner/work/objectui/objectui/packages/core
+> @object-ui/core@3.1.0 build /home/runner/work/objectui/objectui/packages/core
 > tsc
 

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @object-ui/core
 
+## 3.0.3
+
+### Patch Changes
+
+- @object-ui/types@3.0.3
+
 ## 3.0.2
 
 ### Patch Changes

package/dist/actions/ActionEngine.d.ts

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+/**
+ * @object-ui/core - Action Engine
+ *
+ * Declarative action dispatch engine. Manages action registration,
+ * event-to-action mapping, location-based filtering, keyboard shortcuts,
+ * and bulk operation support.
+ *
+ * Replaces callback-based patterns with a schema-driven pipeline:
+ *   ActionSchema[] → ActionEngine → ActionRunner → ActionResult
+ */
+import { ActionRunner, type ActionDef, type ActionContext, type ActionResult } from './ActionRunner';
+/** Action location types (from @objectstack/spec) */
+export type ActionLocation = 'list_toolbar' | 'list_item' | 'record_header' | 'record_more' | 'record_related' | 'global_nav';
+/** Registered action with metadata */
+export interface RegisteredAction {
+    action: ActionDef;
+    locations: ActionLocation[];
+    /** Keyboard shortcut (e.g., 'ctrl+s', 'meta+k') */
+    shortcut?: string;
+    /** Whether this action supports bulk operations */
+    bulkEnabled?: boolean;
+    /** Priority for ordering (lower = first) */
+    priority?: number;
+}
+/** Event-to-action mapping */
+export interface ActionMapping {
+    /** Event name (e.g., 'row:click', 'toolbar:save', 'keyboard:ctrl+s') */
+    event: string;
+    /** Action name to execute */
+    actionName: string;
+    /** Optional condition expression */
+    condition?: string;
+}
+/** Keyboard shortcut handler */
+export interface ShortcutBinding {
+    /** Key combination (e.g., 'ctrl+s', 'meta+k', 'shift+n') */
+    keys: string;
+    /** Action name to trigger */
+    actionName: string;
+}
+export declare class ActionEngine {
+    private actions;
+    private mappings;
+    private shortcuts;
+    private normalizedShortcutMap;
+    private runner;
+    constructor(context?: ActionContext);
+    /** Get the underlying ActionRunner for handler configuration */
+    getRunner(): ActionRunner;
+    /** Register a single action */
+    registerAction(action: ActionDef, options?: {
+        locations?: ActionLocation[];
+        shortcut?: string;
+        bulkEnabled?: boolean;
+        priority?: number;
+    }): void;
+    /** Register multiple actions from an ActionSchema array */
+    registerActions(actions: ActionDef[]): void;
+    /** Unregister an action by name */
+    unregisterAction(name: string): void;
+    /** Add an event-to-action mapping */
+    addMapping(mapping: ActionMapping): void;
+    /** Get actions available at a specific location, sorted by priority */
+    getActionsForLocation(location: ActionLocation): ActionDef[];
+    /** Get actions that support bulk operations */
+    getBulkActions(): ActionDef[];
+    /** Get all registered keyboard shortcuts */
+    getShortcuts(): ShortcutBinding[];
+    /** Get a registered action by name */
+    getAction(name: string): ActionDef | undefined;
+    /** Execute an action by name */
+    executeAction(name: string, contextOverride?: Partial<ActionContext>): Promise<ActionResult>;
+    /** Dispatch an event — finds mapped actions and executes them */
+    dispatch(event: string, contextOverride?: Partial<ActionContext>): Promise<ActionResult[]>;
+    /** Handle a keyboard shortcut event — returns true if handled */
+    handleShortcut(keys: string, contextOverride?: Partial<ActionContext>): Promise<ActionResult | null>;
+    /** Execute a bulk operation on multiple records */
+    executeBulk(actionName: string, records: Record<string, any>[], options?: {
+        parallel?: boolean;
+        continueOnError?: boolean;
+    }): Promise<{
+        total: number;
+        succeeded: number;
+        failed: number;
+        results: ActionResult[];
+    }>;
+    /** Update the action context */
+    updateContext(context: Partial<ActionContext>): void;
+    /** Clear all registered actions and mappings */
+    clear(): void;
+}

package/dist/actions/ActionEngine.js

@@ -0,0 +1,222 @@
+/**
+ * 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.
+ */
+/**
+ * @object-ui/core - Action Engine
+ *
+ * Declarative action dispatch engine. Manages action registration,
+ * event-to-action mapping, location-based filtering, keyboard shortcuts,
+ * and bulk operation support.
+ *
+ * Replaces callback-based patterns with a schema-driven pipeline:
+ *   ActionSchema[] → ActionEngine → ActionRunner → ActionResult
+ */
+import { ActionRunner } from './ActionRunner';
+/** Normalize a shortcut string for comparison (lowercase, trimmed, sorted parts) */
+function normalizeShortcut(keys) {
+    return keys.toLowerCase().split('+').map(k => k.trim()).sort().join('+');
+}
+export class ActionEngine {
+    constructor(context = {}) {
+        Object.defineProperty(this, "actions", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "mappings", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "shortcuts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "normalizedShortcutMap", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "runner", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.runner = new ActionRunner(context);
+    }
+    /** Get the underlying ActionRunner for handler configuration */
+    getRunner() {
+        return this.runner;
+    }
+    /** Register a single action */
+    registerAction(action, options) {
+        const name = action.name || action.type || '';
+        if (!name)
+            throw new Error('Action must have a name or type');
+        this.actions.set(name, {
+            action,
+            locations: options?.locations || [],
+            shortcut: options?.shortcut,
+            bulkEnabled: options?.bulkEnabled ?? false,
+            priority: options?.priority ?? 100,
+        });
+        // Auto-register keyboard shortcut
+        if (options?.shortcut) {
+            this.shortcuts.push({ keys: options.shortcut, actionName: name });
+            this.normalizedShortcutMap.set(normalizeShortcut(options.shortcut), name);
+        }
+    }
+    /** Register multiple actions from an ActionSchema array */
+    registerActions(actions) {
+        for (const action of actions) {
+            this.registerAction(action, {
+                locations: action.locations,
+                shortcut: action.shortcut,
+                bulkEnabled: action.bulkEnabled,
+            });
+        }
+    }
+    /** Unregister an action by name */
+    unregisterAction(name) {
+        const registered = this.actions.get(name);
+        if (registered?.shortcut) {
+            this.normalizedShortcutMap.delete(normalizeShortcut(registered.shortcut));
+        }
+        this.actions.delete(name);
+        this.shortcuts = this.shortcuts.filter(s => s.actionName !== name);
+        this.mappings = this.mappings.filter(m => m.actionName !== name);
+    }
+    /** Add an event-to-action mapping */
+    addMapping(mapping) {
+        this.mappings.push(mapping);
+    }
+    /** Get actions available at a specific location, sorted by priority */
+    getActionsForLocation(location) {
+        return Array.from(this.actions.values())
+            .filter(ra => ra.locations.includes(location))
+            .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100))
+            .map(ra => ra.action);
+    }
+    /** Get actions that support bulk operations */
+    getBulkActions() {
+        return Array.from(this.actions.values())
+            .filter(ra => ra.bulkEnabled)
+            .sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100))
+            .map(ra => ra.action);
+    }
+    /** Get all registered keyboard shortcuts */
+    getShortcuts() {
+        return [...this.shortcuts];
+    }
+    /** Get a registered action by name */
+    getAction(name) {
+        return this.actions.get(name)?.action;
+    }
+    /** Execute an action by name */
+    async executeAction(name, contextOverride) {
+        const registered = this.actions.get(name);
+        if (!registered) {
+            return { success: false, error: `Action not found: ${name}` };
+        }
+        if (contextOverride) {
+            this.runner.updateContext(contextOverride);
+        }
+        return this.runner.execute(registered.action);
+    }
+    /** Dispatch an event — finds mapped actions and executes them */
+    async dispatch(event, contextOverride) {
+        const matchingMappings = this.mappings.filter(m => m.event === event);
+        if (matchingMappings.length === 0) {
+            return [];
+        }
+        const results = [];
+        for (const mapping of matchingMappings) {
+            // Check condition if present
+            if (mapping.condition) {
+                const evaluator = this.runner.getEvaluator();
+                const shouldRun = evaluator.evaluateCondition(mapping.condition);
+                if (!shouldRun)
+                    continue;
+            }
+            const result = await this.executeAction(mapping.actionName, contextOverride);
+            results.push(result);
+        }
+        return results;
+    }
+    /** Handle a keyboard shortcut event — returns true if handled */
+    async handleShortcut(keys, contextOverride) {
+        const actionName = this.normalizedShortcutMap.get(normalizeShortcut(keys));
+        if (!actionName)
+            return null;
+        return this.executeAction(actionName, contextOverride);
+    }
+    /** Execute a bulk operation on multiple records */
+    async executeBulk(actionName, records, options) {
+        const registered = this.actions.get(actionName);
+        if (!registered) {
+            return { total: 0, succeeded: 0, failed: 0, results: [{ success: false, error: `Action not found: ${actionName}` }] };
+        }
+        if (!registered.bulkEnabled) {
+            return { total: 0, succeeded: 0, failed: 0, results: [{ success: false, error: `Action ${actionName} does not support bulk operations` }] };
+        }
+        const results = [];
+        let succeeded = 0;
+        let failed = 0;
+        if (options?.parallel) {
+            const promises = records.map(record => {
+                this.runner.updateContext({ record, selectedRecords: records });
+                return this.runner.execute(registered.action);
+            });
+            const settled = await Promise.allSettled(promises);
+            for (const r of settled) {
+                if (r.status === 'fulfilled') {
+                    results.push(r.value);
+                    if (r.value.success)
+                        succeeded++;
+                    else
+                        failed++;
+                }
+                else {
+                    results.push({ success: false, error: r.reason?.message || 'Unknown error' });
+                    failed++;
+                }
+            }
+        }
+        else {
+            for (const record of records) {
+                this.runner.updateContext({ record, selectedRecords: records });
+                const result = await this.runner.execute(registered.action);
+                results.push(result);
+                if (result.success)
+                    succeeded++;
+                else {
+                    failed++;
+                    if (!options?.continueOnError)
+                        break;
+                }
+            }
+        }
+        return { total: records.length, succeeded, failed, results };
+    }
+    /** Update the action context */
+    updateContext(context) {
+        this.runner.updateContext(context);
+    }
+    /** Clear all registered actions and mappings */
+    clear() {
+        this.actions.clear();
+        this.mappings = [];
+        this.shortcuts = [];
+        this.normalizedShortcutMap.clear();
+    }
+}

package/dist/actions/UndoManager.d.ts

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+/**
+ * @object-ui/core - Undo Manager
+ *
+ * Global undo/redo system for CRUD operations. Class-based singleton
+ * pattern for use from ActionRunner, React hooks, and standalone contexts.
+ * Maintains bounded history stacks with subscriber notifications.
+ */
+/** Represents a single undoable CRUD operation. */
+export interface UndoableOperation {
+    id: string;
+    type: 'create' | 'update' | 'delete';
+    objectName: string;
+    recordId: string;
+    timestamp: number;
+    description: string;
+    /** Data needed to undo: for create=recordId, for update=previousData, for delete=fullRecord */
+    undoData: Record<string, unknown>;
+    /** Data needed to redo: for create=newData, for update=newData, for delete=recordId */
+    redoData: Record<string, unknown>;
+}
+export interface UndoManagerOptions {
+    /** Maximum number of operations to retain in history. @default 50 */
+    maxHistory?: number;
+}
+/**
+ * Manages undo/redo stacks for CRUD operations.
+ *
+ * Designed as a framework-agnostic class so it can be used from
+ * ActionRunner, React hooks, or any other consumer.
+ */
+export declare class UndoManager {
+    private undoStack;
+    private redoStack;
+    private readonly maxHistory;
+    private listeners;
+    constructor(options?: UndoManagerOptions);
+    /** Record an undoable operation. Clears the redo stack. */
+    push(operation: UndoableOperation): void;
+    /** Peek at the next undoable operation without removing it. */
+    peekUndo(): UndoableOperation | undefined;
+    /** Peek at the next redoable operation without removing it. */
+    peekRedo(): UndoableOperation | undefined;
+    /** Pop the last operation from the undo stack and move it to redo. */
+    popUndo(): UndoableOperation | undefined;
+    /** Pop the last operation from the redo stack and move it to undo. */
+    popRedo(): UndoableOperation | undefined;
+    /** Clear all undo and redo history. */
+    clear(): void;
+    get canUndo(): boolean;
+    get canRedo(): boolean;
+    get undoCount(): number;
+    get redoCount(): number;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe(listener: () => void): () => void;
+    /** Get a shallow copy of the undo history (for developer tools). */
+    getHistory(): UndoableOperation[];
+    /** Get a shallow copy of the redo history (for developer tools). */
+    getRedoHistory(): UndoableOperation[];
+    /** Push multiple operations as one atomic unit. Clears the redo stack. */
+    pushBatch(operations: UndoableOperation[]): void;
+    /** Pop `count` operations from the undo stack and move them to redo (LIFO order). */
+    popUndoBatch(count: number): UndoableOperation[];
+    /** Pop `count` operations from the redo stack and move them to undo (LIFO order). */
+    popRedoBatch(count: number): UndoableOperation[];
+    private static readonly STORAGE_KEY;
+    /** Persist the current undo/redo stacks to localStorage. */
+    saveToStorage(): void;
+    /** Restore undo/redo stacks from localStorage (no-op when unavailable). */
+    loadFromStorage(): void;
+    private notify;
+}
+/** Global singleton instance. */
+export declare const globalUndoManager: UndoManager;

package/dist/actions/UndoManager.js

@@ -0,0 +1,193 @@
+/**
+ * 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.
+ */
+/** Type guard validating the required shape of a persisted UndoableOperation. */
+function isValidOperation(op) {
+    if (typeof op !== 'object' || op === null)
+        return false;
+    const o = op;
+    return (typeof o.id === 'string' &&
+        typeof o.type === 'string' &&
+        typeof o.objectName === 'string' &&
+        typeof o.recordId === 'string' &&
+        typeof o.timestamp === 'number');
+}
+/**
+ * Manages undo/redo stacks for CRUD operations.
+ *
+ * Designed as a framework-agnostic class so it can be used from
+ * ActionRunner, React hooks, or any other consumer.
+ */
+export class UndoManager {
+    constructor(options) {
+        Object.defineProperty(this, "undoStack", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "redoStack", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "maxHistory", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "listeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        this.maxHistory = options?.maxHistory ?? 50;
+    }
+    /** Record an undoable operation. Clears the redo stack. */
+    push(operation) {
+        this.undoStack.push(operation);
+        if (this.undoStack.length > this.maxHistory) {
+            this.undoStack.shift();
+        }
+        this.redoStack = [];
+        this.notify();
+    }
+    /** Peek at the next undoable operation without removing it. */
+    peekUndo() {
+        return this.undoStack[this.undoStack.length - 1];
+    }
+    /** Peek at the next redoable operation without removing it. */
+    peekRedo() {
+        return this.redoStack[this.redoStack.length - 1];
+    }
+    /** Pop the last operation from the undo stack and move it to redo. */
+    popUndo() {
+        const op = this.undoStack.pop();
+        if (op) {
+            this.redoStack.push(op);
+            this.notify();
+        }
+        return op;
+    }
+    /** Pop the last operation from the redo stack and move it to undo. */
+    popRedo() {
+        const op = this.redoStack.pop();
+        if (op) {
+            this.undoStack.push(op);
+            this.notify();
+        }
+        return op;
+    }
+    /** Clear all undo and redo history. */
+    clear() {
+        this.undoStack = [];
+        this.redoStack = [];
+        this.notify();
+    }
+    get canUndo() { return this.undoStack.length > 0; }
+    get canRedo() { return this.redoStack.length > 0; }
+    get undoCount() { return this.undoStack.length; }
+    get redoCount() { return this.redoStack.length; }
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    /** Get a shallow copy of the undo history (for developer tools). */
+    getHistory() { return [...this.undoStack]; }
+    /** Get a shallow copy of the redo history (for developer tools). */
+    getRedoHistory() { return [...this.redoStack]; }
+    // ---------------------------------------------------------------------------
+    // Batch operations
+    // ---------------------------------------------------------------------------
+    /** Push multiple operations as one atomic unit. Clears the redo stack. */
+    pushBatch(operations) {
+        if (operations.length === 0)
+            return;
+        this.undoStack.push(...operations);
+        // Trim from the front if we exceed maxHistory
+        if (this.undoStack.length > this.maxHistory) {
+            this.undoStack.splice(0, this.undoStack.length - this.maxHistory);
+        }
+        this.redoStack = [];
+        this.notify();
+    }
+    /** Pop `count` operations from the undo stack and move them to redo (LIFO order). */
+    popUndoBatch(count) {
+        const actual = Math.min(count, this.undoStack.length);
+        if (actual === 0)
+            return [];
+        const ops = this.undoStack.splice(this.undoStack.length - actual, actual);
+        // Preserve LIFO order on the redo stack (last undone goes on top)
+        this.redoStack.push(...ops);
+        this.notify();
+        return ops;
+    }
+    /** Pop `count` operations from the redo stack and move them to undo (LIFO order). */
+    popRedoBatch(count) {
+        const actual = Math.min(count, this.redoStack.length);
+        if (actual === 0)
+            return [];
+        const ops = this.redoStack.splice(this.redoStack.length - actual, actual);
+        this.undoStack.push(...ops);
+        this.notify();
+        return ops;
+    }
+    /** Persist the current undo/redo stacks to localStorage. */
+    saveToStorage() {
+        try {
+            const payload = JSON.stringify({
+                undoStack: this.undoStack,
+                redoStack: this.redoStack,
+            });
+            localStorage.setItem(UndoManager.STORAGE_KEY, payload);
+        }
+        catch {
+            // localStorage may be unavailable (SSR, quota exceeded, etc.)
+        }
+    }
+    /** Restore undo/redo stacks from localStorage (no-op when unavailable). */
+    loadFromStorage() {
+        try {
+            if (typeof localStorage === 'undefined')
+                return;
+            const raw = localStorage.getItem(UndoManager.STORAGE_KEY);
+            if (!raw)
+                return;
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed.undoStack)) {
+                this.undoStack = parsed.undoStack.filter(isValidOperation);
+            }
+            if (Array.isArray(parsed.redoStack)) {
+                this.redoStack = parsed.redoStack.filter(isValidOperation);
+            }
+            // Enforce maxHistory in case persisted state used a different limit
+            if (this.undoStack.length > this.maxHistory) {
+                this.undoStack.splice(0, this.undoStack.length - this.maxHistory);
+            }
+            this.notify();
+        }
+        catch {
+            // Silently ignore parse errors or missing storage
+        }
+    }
+    notify() { this.listeners.forEach((fn) => fn()); }
+}
+// ---------------------------------------------------------------------------
+// Persistence (localStorage)
+// ---------------------------------------------------------------------------
+Object.defineProperty(UndoManager, "STORAGE_KEY", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: 'objectui:undo-history'
+});
+/** Global singleton instance. */
+export const globalUndoManager = new UndoManager();

package/dist/actions/index.d.ts

@@ -6,4 +6,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 export * from './ActionRunner.js';
+export * from './ActionEngine.js';
 export * from './TransactionManager.js';
+export * from './UndoManager.js';

package/dist/actions/index.js

@@ -6,4 +6,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 export * from './ActionRunner.js';
+export * from './ActionEngine.js';
 export * from './TransactionManager.js';
+export * from './UndoManager.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 } from '@object-ui/types';
+import type { DataSource, QueryParams, QueryResult, HttpRequest, AggregateParams, AggregateResult } from '@object-ui/types';
 export interface ApiDataSourceConfig {
     /** HttpRequest config for read operations (find, findOne) */
     read?: HttpRequest;
@@ -53,6 +53,7 @@ export declare class ApiDataSource<T = any> implements DataSource<T> {
     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[]>;
     /**
      * Normalize various API response shapes into a QueryResult.
      *

package/dist/adapters/ApiDataSource.js

@@ -246,6 +246,31 @@ export class ApiDataSource {
     async getApp(_appId) {
         return null;
     }
+    async aggregate(_resource, params) {
+        const queryParams = {
+            field: params.field,
+            function: params.function,
+            groupBy: params.groupBy,
+        };
+        if (params.filter) {
+            queryParams.filter = typeof params.filter === 'string'
+                ? params.filter
+                : JSON.stringify(params.filter);
+        }
+        const raw = await this.request(this.readConfig, {
+            pathSuffix: 'aggregate',
+            method: 'GET',
+            queryParams,
+        });
+        // Normalize: the API might return an array or an object with data/results
+        if (Array.isArray(raw))
+            return raw;
+        if (raw?.data && Array.isArray(raw.data))
+            return raw.data;
+        if (raw?.results && Array.isArray(raw.results))
+            return raw.results;
+        return [];
+    }
     // -----------------------------------------------------------------------
     // Helpers
     // -----------------------------------------------------------------------