@object-ui/core 17.3.0 → 17.6.0

package/README.md

@@ -4,7 +4,8 @@ Core logic, types, and validation for Object UI. Zero React dependencies.
 
 ## Features
 
-- 🎯 **Type Definitions** - Complete TypeScript schemas for all components
+- 🎯 **Type Definitions** - Re-exported runtime types; the component schema
+  vocabulary itself is `@object-ui/types`
 - 🔍 **Component Registry** - Framework-agnostic component registration system
 - 📊 **Data Scope** - Data scope management and expression evaluation
 - ✅ **Validation** - Zod-based schema validation
@@ -20,15 +21,20 @@ npm install @object-ui/core
 
 ### Type Definitions
 
+The component schema vocabulary lives in `@object-ui/types`. Core depends on
+that package and does not re-export it, so import the types from there. The
+page node type is `PageNodeSchema` — the SDUI node, as distinct from the
+authored page document.
+
 ```typescript
-import type { 
-  PageSchema, 
-  FormSchema, 
+import type {
+  PageNodeSchema,
+  FormSchema,
   InputSchema,
-  BaseSchema 
-} from '@object-ui/core'
+  BaseSchema
+} from '@object-ui/types'
 
-const mySchema: PageSchema = {
+const mySchema: PageNodeSchema = {
   type: 'page',
   title: 'My Page',
   body: []
@@ -40,22 +46,30 @@ const mySchema: PageSchema = {
 ```typescript
 import { ComponentRegistry } from '@object-ui/core'
 
-const registry = new ComponentRegistry()
-registry.register('button', buttonMetadata)
-const metadata = registry.get('button')
+ComponentRegistry.register('button', buttonMetadata)
+const metadata = ComponentRegistry.get('button')
 ```
 
+`ComponentRegistry` is a process-level singleton exported by `@object-ui/core`;
+`SchemaRenderer` resolves every `type` against it, so a component registered
+here is renderable from schema anywhere in the app.
+
 ### Data Scope
 
+`DataScopeManager` owns the named scopes a component tree reads from, and
+`evaluateExpression` evaluates a `${...}` expression against a context. They
+are separate exports: a scope holds data, it does not evaluate.
+
 ```typescript
-import { DataScope } from '@object-ui/core'
+import { DataScopeManager, evaluateExpression } from '@object-ui/core'
 
-const scope = new DataScope({ 
-  user: { name: 'John', role: 'admin' } 
-})
+const manager = new DataScopeManager()
+manager.registerScope('user', { data: { name: 'John', role: 'admin' } })
 
-const userName = scope.get('user.name') // 'John'
-const isAdmin = scope.evaluate('${user.role === "admin"}') // true
+const userName = manager.getScope('user')?.data.name // 'John'
+const isAdmin = evaluateExpression('${user.role === "admin"}', {
+  user: { name: 'John', role: 'admin' },
+}) // true
 ```
 
 ### Server Action Dispatch (`createServerActionHandler`)
@@ -87,16 +101,16 @@ action identity (ADR-0110), the record-id resolution dance (`_rowRecord`,
 guard, and the `/actions` response-envelope rule (`interpretActionResponse` /
 `readActionPayload`, also exported).
 
-### System Views (`defineView`)
+### System Views (`defineSystemView`)
 
 Schemas authored in source code are part of the product contract and must
-not be mutated at runtime. Wrap them with `defineView()` to deep-freeze the
-graph and tag it as a *System View*.
+not be mutated at runtime. Wrap them with `defineSystemView()` to deep-freeze
+the graph and tag it as a *System View*.
 
 ```typescript
-import { defineView, cloneAsOverride, isSystemView } from '@object-ui/core'
+import { defineSystemView, cloneAsOverride, isSystemView } from '@object-ui/core'
 
-export const userListView = defineView({
+export const userListView = defineSystemView({
   type: 'list',
   data: { object: 'User' },
   columns: [{ name: 'email' }],
@@ -115,7 +129,7 @@ isSystemView(draft)                          // false — clone is no longer Sys
 
 | Tier        | Source                | Mutable? | API                         |
 | ----------- | --------------------- | -------- | --------------------------- |
-| System View | code (`import` / `as const`) | ❌ frozen | `defineView()`              |
+| System View | code (`import` / `as const`) | ❌ frozen | `defineSystemView()`        |
 | Tenant View | backend / DB          | ⚠️ admin only | `cloneAsOverride()` + persist |
 | User View   | localStorage / API    | ✅ user-editable | `cloneAsOverride()` + persist |
 
@@ -141,21 +155,11 @@ This allows the core types and logic to be used in:
 
 ## API Reference
 
-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)
+See [full documentation](https://objectui.org/docs/api) for detailed API reference.
 
 ## Links
 
-- 📚 [Documentation](https://www.objectui.org/docs/core)
+- 📚 [Documentation](https://www.objectui.org/docs/guide/architecture)
 - 📦 [npm package](https://www.npmjs.com/package/@object-ui/core)
 - 📝 [Changelog](./CHANGELOG.md)
 - 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)

package/dist/actions/ActionEngine.d.ts

@@ -8,14 +8,13 @@
 /**
  * @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.
+ * Declarative action engine. Manages action registration, 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';
+import { ActionRunner, type ActionDef, type ActionContext, type ActionResult } from './ActionRunner.js';
 /**
  * Action location types — re-exported from `@objectstack/spec/ui` so the
  * platform has one source of truth (`ACTION_LOCATIONS`). Do NOT redeclare
@@ -37,15 +36,6 @@ export interface RegisteredAction {
     /** 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') */
@@ -53,9 +43,35 @@ export interface ShortcutBinding {
     /** Action name to trigger */
     actionName: string;
 }
+/**
+ * Registration + filtering + execution for declared actions.
+ *
+ * Entry points are by NAME (`executeAction`), by LOCATION
+ * (`getActionsForLocation`), by SHORTCUT (`handleShortcut`) and in BULK
+ * (`executeBulk`). There is deliberately no entry point by arbitrary EVENT
+ * name: this class used to carry a second, parallel one — `addMapping()`
+ * registered `{ event, actionName, condition }` triples into a private
+ * `mappings` array and `dispatch(event)` ran every triple matching an event
+ * string. It was retired under enforce-or-remove (objectui#3368) because it
+ * was a public export of `@object-ui/core` with zero production callers: in
+ * its whole lifetime nothing ever registered a mapping, so `dispatch()` had
+ * no reachable caller either, and its four call sites were all in this
+ * class's own test file.
+ *
+ * Its condition gate had drifted three ways from the `visible` contract
+ * `getActionsForLocation` below implements — it entered on a raw truthy check
+ * (so `condition: false` dispatched anyway), typed `condition` as `string`
+ * only (so a `{ dialect: 'cel', source }` envelope could not reach the
+ * canonical engine), and evaluated without `throwOnError` (so a throwing
+ * predicate failed OPEN, the opposite of `visible`'s fail-closed posture).
+ * All three were retired WITH the path rather than fixed on it: aligning the
+ * contract of an API nobody calls only widens behaviour nobody uses. If an
+ * event-keyed entry point is ever genuinely needed, it must be built on the
+ * shared predicate definitions (`hasDeclaredPredicate` + `toPredicateInput`)
+ * that the surviving gate below already uses, not on a fourth spelling.
+ */
 export declare class ActionEngine {
     private actions;
-    private mappings;
     private shortcuts;
     private normalizedShortcutMap;
     private runner;
@@ -92,21 +108,24 @@ export declare class ActionEngine {
     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.
      *
      * Filtering applied (in order):
      *   1. `locations.includes(location)` — location/region match
      *   2. `action.visible` — evaluated against the runner's current context
-     *      ({ record, recordId, objectName, user, … }). Missing or `true`
-     *      passes; any other value is coerced to boolean. Evaluator errors
-     *      hide the action (fail-closed) rather than throwing — this matches
-     *      the contract used by every individual action renderer
-     *      (`action-button`, `action-menu`, `action-bar`, …) so the same
-     *      action behaves identically whether surfaced via the engine or
-     *      consumed standalone.
+     *      ({ record, recordId, objectName, user, … }) whenever a gate is
+     *      DECLARED, which is asked through core's one definition
+     *      `hasDeclaredPredicate` (objectui#3850's ruling, adopted here by
+     *      objectui#3957). No gate — absent, `''`, blank predicate text in either
+     *      spelling, an envelope with no evaluable `source`, or a value that is
+     *      not a predicate at all — means visible. Evaluator errors hide the
+     *      action (fail-closed) rather than throwing — this matches the contract
+     *      used by every individual action renderer (`action-button`,
+     *      `action-menu`, `action-bar`, …) so the same action behaves identically
+     *      whether surfaced via the engine or consumed standalone, which is now
+     *      true of the gate in front of the verdict as well as the verdict
+     *      (objectui#3314: one value, one answer, whichever entry reads it).
      *
      *   Predicate normalization goes through the shared `toPredicateInput`
      *   (`@object-ui/core`'s canonical helper — semantically identical to
@@ -130,8 +149,6 @@ export declare class ActionEngine {
     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 */
@@ -146,6 +163,6 @@ export declare class ActionEngine {
     }>;
     /** Update the action context */
     updateContext(context: Partial<ActionContext>): void;
-    /** Clear all registered actions and mappings */
+    /** Clear all registered actions and shortcuts */
     clear(): void;
 }

package/dist/actions/ActionEngine.js

@@ -8,15 +8,15 @@
 /**
  * @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.
+ * Declarative action engine. Manages action registration, 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';
+import { ActionRunner } from './ActionRunner.js';
 import { toPredicateInput } from '../evaluator/predicateInput.js';
+import { hasDeclaredPredicate } from '../evaluator/declaredPredicate.js';
 export { ACTION_LOCATIONS } from '@object-ui/types';
 /** Normalize a shortcut string for comparison (lowercase, trimmed, sorted parts) */
 function normalizeShortcut(keys) {
@@ -38,11 +38,37 @@ function warnHiddenPredicate(name, raw, err) {
         return;
     _warnedPredicates.add(key);
     const msg = err instanceof Error ? err.message : String(err);
-    // eslint-disable-next-line no-console
     console.warn(`[ActionEngine] action "${String(name)}" hidden: its \`visible\` predicate threw — ${msg}. ` +
         `Predicate: ${src}. Action predicates evaluate against { record, recordId, objectName, user, os.user, … }; ` +
         `use \`record.<field>\` (not a bare field).`);
 }
+/**
+ * Registration + filtering + execution for declared actions.
+ *
+ * Entry points are by NAME (`executeAction`), by LOCATION
+ * (`getActionsForLocation`), by SHORTCUT (`handleShortcut`) and in BULK
+ * (`executeBulk`). There is deliberately no entry point by arbitrary EVENT
+ * name: this class used to carry a second, parallel one — `addMapping()`
+ * registered `{ event, actionName, condition }` triples into a private
+ * `mappings` array and `dispatch(event)` ran every triple matching an event
+ * string. It was retired under enforce-or-remove (objectui#3368) because it
+ * was a public export of `@object-ui/core` with zero production callers: in
+ * its whole lifetime nothing ever registered a mapping, so `dispatch()` had
+ * no reachable caller either, and its four call sites were all in this
+ * class's own test file.
+ *
+ * Its condition gate had drifted three ways from the `visible` contract
+ * `getActionsForLocation` below implements — it entered on a raw truthy check
+ * (so `condition: false` dispatched anyway), typed `condition` as `string`
+ * only (so a `{ dialect: 'cel', source }` envelope could not reach the
+ * canonical engine), and evaluated without `throwOnError` (so a throwing
+ * predicate failed OPEN, the opposite of `visible`'s fail-closed posture).
+ * All three were retired WITH the path rather than fixed on it: aligning the
+ * contract of an API nobody calls only widens behaviour nobody uses. If an
+ * event-keyed entry point is ever genuinely needed, it must be built on the
+ * shared predicate definitions (`hasDeclaredPredicate` + `toPredicateInput`)
+ * that the surviving gate below already uses, not on a fourth spelling.
+ */
 export class ActionEngine {
     /**
      * @param contextOrRunner Either an initial `ActionContext` (constructs a
@@ -60,12 +86,6 @@ export class ActionEngine {
             writable: true,
             value: new Map()
         });
-        Object.defineProperty(this, "mappings", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: []
-        });
         Object.defineProperty(this, "shortcuts", {
             enumerable: true,
             configurable: true,
@@ -140,11 +160,6 @@ export class ActionEngine {
         }
         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.
@@ -152,13 +167,18 @@ export class ActionEngine {
      * Filtering applied (in order):
      *   1. `locations.includes(location)` — location/region match
      *   2. `action.visible` — evaluated against the runner's current context
-     *      ({ record, recordId, objectName, user, … }). Missing or `true`
-     *      passes; any other value is coerced to boolean. Evaluator errors
-     *      hide the action (fail-closed) rather than throwing — this matches
-     *      the contract used by every individual action renderer
-     *      (`action-button`, `action-menu`, `action-bar`, …) so the same
-     *      action behaves identically whether surfaced via the engine or
-     *      consumed standalone.
+     *      ({ record, recordId, objectName, user, … }) whenever a gate is
+     *      DECLARED, which is asked through core's one definition
+     *      `hasDeclaredPredicate` (objectui#3850's ruling, adopted here by
+     *      objectui#3957). No gate — absent, `''`, blank predicate text in either
+     *      spelling, an envelope with no evaluable `source`, or a value that is
+     *      not a predicate at all — means visible. Evaluator errors hide the
+     *      action (fail-closed) rather than throwing — this matches the contract
+     *      used by every individual action renderer (`action-button`,
+     *      `action-menu`, `action-bar`, …) so the same action behaves identically
+     *      whether surfaced via the engine or consumed standalone, which is now
+     *      true of the gate in front of the verdict as well as the verdict
+     *      (objectui#3314: one value, one answer, whichever entry reads it).
      *
      *   Predicate normalization goes through the shared `toPredicateInput`
      *   (`@object-ui/core`'s canonical helper — semantically identical to
@@ -194,22 +214,36 @@ export class ActionEngine {
         })
             .filter(ra => {
             const raw = ra.action.visible;
-            if (raw == null || raw === '' || raw === true)
+            // Ask "is a `visible` gate DECLARED?" through the repo's ONE definition
+            // (`evaluator/declaredPredicate.ts`, objectui#3850's ruling), which is
+            // what the renderers, `SchemaRenderer` and `ActionRunner`'s execution
+            // gates ask. This filter used to answer it with a range of its own —
+            // three empty spellings folded by hand (`null` / `''` / an envelope with
+            // an empty `source`) and everything else coerced with `Boolean(raw)` —
+            // and it was the LAST consumer to do so, so the same value got two
+            // answers depending on which entry read it: `visible: 0` / `NaN` hid the
+            // action here and showed it on the renderer face, and `visible: '   '`
+            // hid it here because the normalizer wraps a blank string into `'${   }'`
+            // whose verdict is falsy. That is the shape objectui#3314's invariant
+            // forbids, and it is fixed by deleting a range, not by adding one
+            // (objectui#3957). A value that is not a predicate, or a predicate that
+            // says nothing, must not be the reason an action is hidden from
+            // everyone — the same fail-open posture `ActionRunner` already committed
+            // to for `disabled` (`catch { isDisabled = false }`).
+            //
+            // Booleans need no branch of their own: they are DECLARED (`visible:
+            // false` is a verdict, objectui#3812) and `evaluateCondition`
+            // short-circuits them.
+            if (!hasDeclaredPredicate(raw))
                 return true;
-            if (raw === false)
-                return false;
             // #3314 — one shared normalization, not two. Hand-rolling the envelope
             // unwrap here is what dropped `dialect: 'cel'` and demoted the
             // predicate to the legacy JS engine; `toPredicateInput` keeps the
             // envelope so `evaluateCondition` can route it to `@objectstack/formula`
             // (the engine the server enforces with), exactly as the renderers do.
+            // Declared ⇒ the normalizer left something to evaluate, so there is no
+            // `undefined` case left to handle here.
             const expr = toPredicateInput(raw);
-            if (expr === undefined) {
-                // Not an evaluable predicate: an envelope with an empty `source`
-                // (→ nothing declared → visible), or a stray non-predicate value,
-                // which keeps the historical `Boolean(raw)` coercion.
-                return typeof raw === 'object' ? true : Boolean(raw);
-            }
             try {
                 // `throwOnError: true` is required for fail-closed semantics: the
                 // evaluator's default behavior swallows expression errors and
@@ -262,26 +296,6 @@ export class ActionEngine {
         }
         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));
@@ -341,10 +355,9 @@ export class ActionEngine {
     updateContext(context) {
         this.runner.updateContext(context);
     }
-    /** Clear all registered actions and mappings */
+    /** Clear all registered actions and shortcuts */
     clear() {
         this.actions.clear();
-        this.mappings = [];
         this.shortcuts = [];
         this.normalizedShortcutMap.clear();
     }