@object-ui/core 3.3.0 → 3.3.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @object-ui/core
 
+## 3.3.2
+
+### Patch Changes
+
+- @object-ui/types@3.3.2
+
+## 3.3.1
+
+### Patch Changes
+
+- @object-ui/types@3.3.1
+
 ## 3.3.0
 
 ### Patch Changes

package/README.md

@@ -79,6 +79,25 @@ This allows the core types and logic to be used in:
 
 See [full documentation](https://objectui.org/api/core) for detailed API reference.
 
+<!-- release-metadata:v3.3.0 -->
+
+## Compatibility
+
+- **Node.js:** ≥ 18
+- **TypeScript:** ≥ 5.0 (strict mode)
+- **`@objectstack/spec`:** ^3.3.0
+- **`@objectstack/client`:** ^3.3.0
+- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
+
+## Links
+
+- 📚 [Documentation](https://www.objectui.org/docs/core)
+- 📦 [npm package](https://www.npmjs.com/package/@object-ui/core)
+- 📝 [Changelog](./CHANGELOG.md)
+- 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)
+- 🤝 [Contributing Guide](https://github.com/objectstack-ai/objectui/blob/main/CONTRIBUTING.md)
+- 🗺️ [Roadmap](https://github.com/objectstack-ai/objectui/blob/main/ROADMAP.md)
+
 ## License
 
-MIT
+MIT — see [LICENSE](./LICENSE).

package/dist/actions/ActionRunner.d.ts

@@ -178,6 +178,7 @@ export interface ActionParamDef {
 }
 export declare class ActionRunner {
     private handlers;
+    private scripts;
     private evaluator;
     private context;
     private confirmHandler;
@@ -209,6 +210,14 @@ export declare class ActionRunner {
     setParamCollectionHandler(handler: ParamCollectionHandler): void;
     registerHandler(actionName: string, handler: ActionHandler): void;
     unregisterHandler(actionName: string): void;
+    /**
+     * Register a named script handler. When a `script` action's
+     * `target`/`execute` matches the registered name, the handler runs
+     * 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;
+    unregisterScript(scriptName: string): void;
     execute(action: ActionDef): Promise<ActionResult>;
     /**
      * Execute multiple actions in sequence or parallel.

package/dist/actions/ActionRunner.js

@@ -22,6 +22,12 @@ export class ActionRunner {
             writable: true,
             value: new Map()
         });
+        Object.defineProperty(this, "scripts", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
         Object.defineProperty(this, "evaluator", {
             enumerable: true,
             configurable: true,
@@ -110,6 +116,18 @@ export class ActionRunner {
     unregisterHandler(actionName) {
         this.handlers.delete(actionName);
     }
+    /**
+     * Register a named script handler. When a `script` action's
+     * `target`/`execute` matches the registered name, the handler runs
+     * instead of the expression evaluator. Lets dashboards/views wire
+     * symbolic action names (e.g. 'export_dashboard_pdf') to JS callbacks.
+     */
+    registerScript(scriptName, handler) {
+        this.scripts.set(scriptName, handler);
+    }
+    unregisterScript(scriptName) {
+        this.scripts.delete(scriptName);
+    }
     async execute(action) {
         try {
             // Resolve the action type
@@ -143,14 +161,21 @@ export class ActionRunner {
             }
             // Param collection: if the action defines ActionParam[] to collect,
             // show a dialog to gather user input before executing.
-            if (action.actionParams && Array.isArray(action.actionParams) && action.actionParams.length > 0) {
+            // Spec defines this as `params: ActionParam[]`; ActionRunner historically
+            // used `actionParams` to disambiguate from the static-params object that
+            // some custom handlers consume. Accept both — when `params` is an array,
+            // treat it as the input-collection definition.
+            const paramDefs = action.actionParams && Array.isArray(action.actionParams) ? action.actionParams
+                : (Array.isArray(action.params) ? action.params : undefined);
+            if (paramDefs && paramDefs.length > 0) {
                 if (this.paramCollectionHandler) {
-                    const collected = await this.paramCollectionHandler(action.actionParams);
+                    const collected = await this.paramCollectionHandler(paramDefs);
                     if (collected === null) {
                         return { success: false, error: 'Action cancelled by user (params)' };
                     }
-                    // Merge collected params into action.params
-                    action.params = { ...(action.params || {}), ...collected };
+                    // Merge collected params into action.params as a values map for downstream consumers.
+                    // (Replace the array form with a values object once collected.)
+                    action.params = { ...(Array.isArray(action.params) ? {} : (action.params || {})), ...collected };
                 }
             }
             // Check for a registered custom handler first
@@ -293,6 +318,18 @@ export class ActionRunner {
         if (!script) {
             return { success: false, error: 'No script provided for script action' };
         }
+        // Named script registry wins over the expression evaluator. This lets
+        // dashboards/views bind a symbolic action name (e.g. 'export_dashboard_pdf')
+        // to a JS callback without piping the literal through ExpressionEvaluator.
+        const named = this.scripts.get(script);
+        if (named) {
+            try {
+                return await named(action, this.context);
+            }
+            catch (error) {
+                return { success: false, error: `Script execution failed: ${error.message}` };
+            }
+        }
         try {
             const result = this.evaluator.evaluate(`\${${script}}`);
             return { success: true, data: result };

package/dist/adapters/ValueDataSource.js

@@ -53,7 +53,9 @@ function matchesASTFilter(record, filterNode) {
             case 'in':
                 return Array.isArray(target) && target.includes(value);
             case 'not in':
-            case 'notin': // alias used by convertFiltersToAST
+            case 'not_in':
+            case 'nin': // canonical (per spec)
+            case 'notin': // legacy alias
                 return Array.isArray(target) && !target.includes(value);
             case 'contains': {
                 const lv = typeof value === 'string' ? value.toLowerCase() : '';

package/dist/registry/Registry.d.ts

@@ -55,8 +55,23 @@ export type ComponentConfig<T = any> = ComponentMeta & {
     type: string;
     component: ComponentRenderer<T>;
 };
+/**
+ * Lazy loader function used by `Registry.registerLazy`. The loader is invoked
+ * the first time a missing component type is requested through `getAsync`/the
+ * SchemaRenderer fallback path, and is expected to perform a dynamic
+ * `import()` of a plugin module whose top-level side-effects call
+ * `register()` for that type.
+ */
+export type LazyComponentLoader = () => Promise<unknown>;
 export declare class Registry<T = any> {
     private components;
+    private lazyEntries;
+    /**
+     * Notifies subscribers that the registry has changed (new components
+     * registered). Used by SchemaRenderer to re-render after a lazy plugin
+     * load completes.
+     */
+    private listeners;
     /**
      * Register a component with optional namespace support.
      * If namespace is provided in meta, the component will be registered as "namespace:type".
@@ -76,6 +91,38 @@ export declare class Registry<T = any> {
      * // Accessible as 'button'
      */
     register(type: string, component: ComponentRenderer<T>, meta?: ComponentMeta): void;
+    /**
+     * Register a lazy-loaded component. The `loader` is a function returning a
+     * dynamic `import()` whose target module performs `register()` calls for
+     * the given `type` as a top-level side effect.
+     *
+     * The loader will be invoked the first time `loadLazy(type)` is called (or
+     * the first time the SchemaRenderer encounters an unknown component that
+     * matches a registered lazy type). Subsequent registrations are idempotent.
+     *
+     * @example
+     * ComponentRegistry.registerLazy('object-map', () => import('@object-ui/plugin-map'), { namespace: 'plugin-map' });
+     */
+    registerLazy(type: string, loader: LazyComponentLoader, meta?: ComponentMeta): void;
+    /**
+     * Returns true if `type` (or its namespaced form) has a registered lazy
+     * loader awaiting first use.
+     */
+    hasLazy(type: string, namespace?: string): boolean;
+    /**
+     * Trigger the lazy loader for `type`, if any. Resolves once the loader
+     * completes (whether or not the loaded module actually registered the
+     * expected type — caller should re-check the registry afterwards).
+     * Returns `undefined` if no lazy entry matches.
+     */
+    loadLazy(type: string, namespace?: string): Promise<unknown> | undefined;
+    /**
+     * Subscribe to registry changes (component registrations). Returns an
+     * unsubscribe function. Used by React renderers to re-render when a
+     * lazy-loaded plugin finishes registering its components.
+     */
+    subscribe(listener: () => void): () => void;
+    private notify;
     /**
      * Get a component by type. Supports both namespaced and non-namespaced lookups.
      *

package/dist/registry/Registry.js

@@ -13,6 +13,23 @@ export class Registry {
             writable: true,
             value: new Map()
         });
+        Object.defineProperty(this, "lazyEntries", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /**
+         * Notifies subscribers that the registry has changed (new components
+         * registered). Used by SchemaRenderer to re-render after a lazy plugin
+         * load completes.
+         */
+        Object.defineProperty(this, "listeners", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
     }
     /**
      * Register a component with optional namespace support.
@@ -65,6 +82,81 @@ export class Registry {
                 ...meta
             });
         }
+        // A real component is now available — clear any matching lazy stub so we
+        // don't keep holding the loader reference, and notify subscribers.
+        this.lazyEntries.delete(fullType);
+        this.lazyEntries.delete(type);
+        this.notify();
+    }
+    /**
+     * Register a lazy-loaded component. The `loader` is a function returning a
+     * dynamic `import()` whose target module performs `register()` calls for
+     * the given `type` as a top-level side effect.
+     *
+     * The loader will be invoked the first time `loadLazy(type)` is called (or
+     * the first time the SchemaRenderer encounters an unknown component that
+     * matches a registered lazy type). Subsequent registrations are idempotent.
+     *
+     * @example
+     * ComponentRegistry.registerLazy('object-map', () => import('@object-ui/plugin-map'), { namespace: 'plugin-map' });
+     */
+    registerLazy(type, loader, meta) {
+        const fullType = meta?.namespace ? `${meta.namespace}:${type}` : type;
+        const entry = { loader, meta };
+        this.lazyEntries.set(fullType, entry);
+        if (meta?.namespace && !meta?.skipFallback) {
+            this.lazyEntries.set(type, entry);
+        }
+    }
+    /**
+     * Returns true if `type` (or its namespaced form) has a registered lazy
+     * loader awaiting first use.
+     */
+    hasLazy(type, namespace) {
+        if (namespace)
+            return this.lazyEntries.has(`${namespace}:${type}`);
+        return this.lazyEntries.has(type);
+    }
+    /**
+     * Trigger the lazy loader for `type`, if any. Resolves once the loader
+     * completes (whether or not the loaded module actually registered the
+     * expected type — caller should re-check the registry afterwards).
+     * Returns `undefined` if no lazy entry matches.
+     */
+    loadLazy(type, namespace) {
+        const key = namespace ? `${namespace}:${type}` : type;
+        const entry = this.lazyEntries.get(key);
+        if (!entry)
+            return undefined;
+        if (!entry.pending) {
+            entry.pending = entry.loader().catch((err) => {
+                // Allow retries on failure by clearing the cached promise.
+                entry.pending = undefined;
+                throw err;
+            });
+        }
+        return entry.pending;
+    }
+    /**
+     * Subscribe to registry changes (component registrations). Returns an
+     * unsubscribe function. Used by React renderers to re-render when a
+     * lazy-loaded plugin finishes registering its components.
+     */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    notify() {
+        for (const listener of this.listeners) {
+            try {
+                listener();
+            }
+            catch (err) {
+                console.error('[Registry] listener error', err);
+            }
+        }
     }
     /**
      * Get a component by type. Supports both namespaced and non-namespaced lookups.

package/dist/utils/filter-converter.js

@@ -12,6 +12,9 @@
  * @returns ObjectStack operator or null if not recognized
  */
 export function convertOperatorToAST(operator) {
+    // Spec reference: framework/packages/spec/src/data/filter.zod.ts
+    // Canonical MongoDB-style keys are camelCase ($startsWith, $endsWith, $notContains).
+    // Lowercase aliases are accepted for tolerance.
     const operatorMap = {
         '$eq': '=',
         '$ne': '!=',
@@ -20,11 +23,16 @@ export function convertOperatorToAST(operator) {
         '$lt': '<',
         '$lte': '<=',
         '$in': 'in',
-        '$nin': 'notin',
-        '$notin': 'notin',
+        '$nin': 'nin',
+        '$notin': 'nin',
+        '$between': 'between',
         '$contains': 'contains',
+        '$notContains': 'notcontains',
+        '$notcontains': 'notcontains',
+        '$startsWith': 'startswith',
         '$startswith': 'startswith',
-        '$between': 'between',
+        '$endsWith': 'endswith',
+        '$endswith': 'endswith',
     };
     return operatorMap[operator] || null;
 }
@@ -66,10 +74,21 @@ export function convertFiltersToAST(filter) {
                     console.warn(`[ObjectUI] Warning: $regex operator is not fully supported. ` +
                         `Converting to 'contains' which only supports substring matching, not regex patterns. ` +
                         `Field: '${field}', Value: ${JSON.stringify(operatorValue)}. ` +
-                        `Consider using $contains or $startswith instead.`);
+                        `Consider using $contains or $startsWith instead.`);
                     conditions.push([field, 'contains', operatorValue]);
                     continue;
                 }
+                // $null / $exists translate based on their boolean value (per spec semantics).
+                // $null: true  → IS NULL    | $null: false  → IS NOT NULL
+                // $exists: true → IS NOT NULL | $exists: false → IS NULL
+                if (operator === '$null') {
+                    conditions.push([field, operatorValue ? 'is_null' : 'is_not_null', true]);
+                    continue;
+                }
+                if (operator === '$exists') {
+                    conditions.push([field, operatorValue ? 'is_not_null' : 'is_null', true]);
+                    continue;
+                }
                 const astOperator = convertOperatorToAST(operator);
                 if (astOperator) {
                     conditions.push([field, astOperator, operatorValue]);
@@ -77,7 +96,8 @@ export function convertFiltersToAST(filter) {
                 else {
                     // Unknown operator - throw error to avoid silent failure
                     throw new Error(`[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. ` +
-                        `Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $contains, $startswith, $between. ` +
+                        `Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $between, ` +
+                        `$contains, $notContains, $startsWith, $endsWith, $null, $exists. ` +
                         `If you need exact object matching, use the value directly without an operator.`);
                 }
             }

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@object-ui/core",
-  "version": "3.3.0",
+  "version": "3.3.2",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
   "description": "Core logic, types, and validation for Object UI. Zero React dependencies.",
-  "homepage": "https://www.objectui.org",
+  "homepage": "https://www.objectui.org/docs/core",
   "repository": {
     "type": "git",
-    "url": "https://github.com/objectstack-ai/objectui.git",
+    "url": "git+https://github.com/objectstack-ai/objectui.git",
     "directory": "packages/core"
   },
   "bugs": {
@@ -25,15 +25,39 @@
     }
   },
   "dependencies": {
-    "@objectstack/spec": "^4.0.3",
+    "@objectstack/spec": "^4.0.4",
     "lodash": "^4.18.1",
-    "zod": "^4.3.6",
-    "@object-ui/types": "3.3.0"
+    "zod": "^4.4.3",
+    "@object-ui/types": "3.3.2"
   },
   "devDependencies": {
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.4"
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.5"
   },
+  "keywords": [
+    "objectui",
+    "sdui",
+    "schema-driven-ui",
+    "react",
+    "tailwind",
+    "shadcn",
+    "objectstack",
+    "core",
+    "engine",
+    "expression-engine",
+    "action-engine",
+    "registry"
+  ],
+  "author": "ObjectStack Team <team@objectstack.ai>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "scripts": {
     "build": "tsc",
     "test": "vitest run",

package/.turbo/turbo-build.log

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

package/src/__benchmarks__/core.bench.ts

@@ -1,64 +0,0 @@
-/**
- * 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.
- */
-
-/**
- * Performance benchmark suite for @object-ui/core.
- *
- * Part of Q1 2026 roadmap §1.4 Test Coverage Improvement.
- *
- * Run with: npx vitest bench packages/core/src/__benchmarks__/
- */
-
-import { bench, describe } from 'vitest';
-import { ExpressionEvaluator } from '@object-ui/core';
-import { ComponentRegistry } from '@object-ui/core';
-import { contrastRatio, meetsContrastLevel, hexToHSL } from '@object-ui/core';
-
-describe('ExpressionEvaluator performance', () => {
-  const evaluator = new ExpressionEvaluator({ data: { name: 'Alice', age: 30, active: true } });
-
-  bench('evaluate simple string', () => {
-    evaluator.evaluate('Hello ${data.name}');
-  });
-
-  bench('evaluate 100 expressions', () => {
-    for (let i = 0; i < 100; i++) {
-      evaluator.evaluate('Hello ${data.name}');
-    }
-  });
-});
-
-describe('ComponentRegistry performance', () => {
-  bench('get registered component', () => {
-    ComponentRegistry.get('button');
-  });
-
-  bench('has check', () => {
-    ComponentRegistry.has('button');
-  });
-});
-
-describe('Theme utilities performance', () => {
-  bench('hexToHSL conversion', () => {
-    hexToHSL('#336699');
-  });
-
-  bench('contrastRatio calculation', () => {
-    contrastRatio('#000000', '#ffffff');
-  });
-
-  bench('meetsContrastLevel check', () => {
-    meetsContrastLevel('#000000', '#ffffff', 'AA');
-  });
-
-  bench('100 contrast checks', () => {
-    for (let i = 0; i < 100; i++) {
-      meetsContrastLevel('#336699', '#ffffff', 'AA');
-    }
-  });
-});