@object-ui/core 3.3.0 → 3.3.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @object-ui/core
 
+## 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/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.1",
   "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.1"
   },
   "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');
-    }
-  });
-});

package/src/__tests__/protocols/DndProtocol.test.ts

@@ -1,186 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import type { DndConfig, DragItem, DropZone, DragConstraint } from '@object-ui/types';
-import {
-  resolveDndConfig,
-  createDragItemProps,
-  createDropZoneProps,
-  resolveDragConstraints,
-} from '../../protocols/DndProtocol';
-
-describe('DndProtocol', () => {
-  // ==========================================================================
-  // resolveDndConfig
-  // ==========================================================================
-  describe('resolveDndConfig', () => {
-    it('should apply all defaults for minimal config', () => {
-      const config = {} as DndConfig;
-      const resolved = resolveDndConfig(config);
-
-      expect(resolved.enabled).toBe(false);
-      expect(resolved.sortable).toBe(false);
-      expect(resolved.autoScroll).toBe(true);
-      expect(resolved.touchDelay).toBe(200);
-      expect(resolved.dragItem).toBeUndefined();
-      expect(resolved.dropZone).toBeUndefined();
-    });
-
-    it('should preserve explicit values', () => {
-      const config = {
-        enabled: true,
-        sortable: true,
-        autoScroll: false,
-        touchDelay: 500,
-      } as DndConfig;
-      const resolved = resolveDndConfig(config);
-
-      expect(resolved.enabled).toBe(true);
-      expect(resolved.sortable).toBe(true);
-      expect(resolved.autoScroll).toBe(false);
-      expect(resolved.touchDelay).toBe(500);
-    });
-
-    it('should pass through dragItem and dropZone', () => {
-      const dragItem = { type: 'card' } as DragItem;
-      const dropZone = { accept: ['card'] } as DropZone;
-      const config = { dragItem, dropZone } as DndConfig;
-      const resolved = resolveDndConfig(config);
-
-      expect(resolved.dragItem).toBe(dragItem);
-      expect(resolved.dropZone).toBe(dropZone);
-    });
-  });
-
-  // ==========================================================================
-  // createDragItemProps
-  // ==========================================================================
-  describe('createDragItemProps', () => {
-    it('should return correct props for a basic drag item', () => {
-      const item = { type: 'card', label: 'Task card' } as DragItem;
-      const props = createDragItemProps(item);
-
-      expect(props.draggable).toBe(true);
-      expect(props['aria-roledescription']).toBe('draggable');
-      expect(props['aria-label']).toBe('Task card');
-      expect(props.role).toBe('listitem');
-      expect(props['data-drag-type']).toBe('card');
-      expect(props['data-drag-handle']).toBe('element');
-      expect(props['data-drag-disabled']).toBe('false');
-    });
-
-    it('should set draggable false when disabled', () => {
-      const item = { type: 'card', disabled: true } as DragItem;
-      const props = createDragItemProps(item);
-
-      expect(props.draggable).toBe(false);
-      expect(props['data-drag-disabled']).toBe('true');
-    });
-
-    it('should use ariaLabel over label when both provided', () => {
-      const item = { type: 'card', label: 'Label', ariaLabel: 'Aria Label' } as DragItem;
-      const props = createDragItemProps(item);
-
-      expect(props['aria-label']).toBe('Aria Label');
-    });
-
-    it('should use ariaLabel when provided as string', () => {
-      const item = {
-        type: 'card',
-        ariaLabel: 'Translated label',
-      } as unknown as DragItem;
-      const props = createDragItemProps(item);
-
-      expect(props['aria-label']).toBe('Translated label');
-    });
-
-    it('should use custom role and handle when provided', () => {
-      const item = { type: 'row', role: 'option', handle: 'grip' } as DragItem;
-      const props = createDragItemProps(item);
-
-      expect(props.role).toBe('option');
-      expect(props['data-drag-handle']).toBe('grip');
-    });
-  });
-
-  // ==========================================================================
-  // createDropZoneProps
-  // ==========================================================================
-  describe('createDropZoneProps', () => {
-    it('should return correct props for a basic drop zone', () => {
-      const zone = { accept: ['card', 'task'], label: 'Column' } as unknown as DropZone;
-      const props = createDropZoneProps(zone);
-
-      expect(props['aria-dropeffect']).toBe('move');
-      expect(props['aria-label']).toBe('Column');
-      expect(props.role).toBe('list');
-      expect(props['data-drop-accept']).toBe('card,task');
-      expect(props['data-drop-highlight']).toBe('true');
-    });
-
-    it('should use explicit dropEffect and role', () => {
-      const zone = { accept: ['item'], dropEffect: 'copy', role: 'region' } as unknown as DropZone;
-      const props = createDropZoneProps(zone);
-
-      expect(props['aria-dropeffect']).toBe('copy');
-      expect(props.role).toBe('region');
-    });
-
-    it('should set maxItems when provided', () => {
-      const zone = { accept: ['card'], maxItems: 10 } as unknown as DropZone;
-      const props = createDropZoneProps(zone);
-
-      expect(props['data-drop-max-items']).toBe(10);
-    });
-
-    it('should use ariaLabel string when provided', () => {
-      const zone = {
-        accept: ['card'],
-        ariaLabel: 'Drop here',
-      } as unknown as DropZone;
-      const props = createDropZoneProps(zone);
-
-      expect(props['aria-label']).toBe('Drop here');
-    });
-  });
-
-  // ==========================================================================
-  // resolveDragConstraints
-  // ==========================================================================
-  describe('resolveDragConstraints', () => {
-    it('should return base styles for default axis (both)', () => {
-      const constraint = {} as DragConstraint;
-      const styles = resolveDragConstraints(constraint);
-
-      expect(styles.position).toBe('relative');
-      expect(styles.touchAction).toBe('none');
-    });
-
-    it('should set touchAction to pan-y for x axis', () => {
-      const constraint = { axis: 'x' } as DragConstraint;
-      const styles = resolveDragConstraints(constraint);
-
-      expect(styles.touchAction).toBe('pan-y');
-    });
-
-    it('should set touchAction to pan-x for y axis', () => {
-      const constraint = { axis: 'y' } as DragConstraint;
-      const styles = resolveDragConstraints(constraint);
-
-      expect(styles.touchAction).toBe('pan-x');
-    });
-
-    it('should set overflow hidden for parent bounds', () => {
-      const constraint = { bounds: 'parent' } as DragConstraint;
-      const styles = resolveDragConstraints(constraint);
-
-      expect(styles.overflow).toBe('hidden');
-    });
-
-    it('should set grid CSS custom properties', () => {
-      const constraint = { grid: [20, 30] } as unknown as DragConstraint;
-      const styles = resolveDragConstraints(constraint);
-
-      expect(styles['--drag-grid-x']).toBe('20px');
-      expect(styles['--drag-grid-y']).toBe('30px');
-    });
-  });
-});