@object-ui/core 17.5.0 → 17.7.0

package/README.md

@@ -4,9 +4,10 @@ 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
+- 🧮 **Expressions** - `${...}` expression evaluation against a context
 - ✅ **Validation** - Zod-based schema validation
 - 🚀 **Zero React** - Can run in Node.js or any JavaScript environment
 
@@ -20,18 +21,24 @@ 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',
+  pageType: 'app',
   title: 'My Page',
-  body: []
+  children: []
 }
 ```
 
@@ -39,23 +46,31 @@ const mySchema: PageSchema = {
 
 ```typescript
 import { ComponentRegistry } from '@object-ui/core'
+import type { ComponentRenderer } from '@object-ui/core'
+
+// Your component, in whatever renderer shape the host framework uses.
+declare const buttonRenderer: ComponentRenderer
 
-const registry = new ComponentRegistry()
-registry.register('button', buttonMetadata)
-const metadata = registry.get('button')
+ComponentRegistry.register('button', buttonRenderer)
+const renderer = ComponentRegistry.get('button')
 ```
 
-### Data Scope
+`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. `register()`'s second
+argument is the component itself; registration metadata is its optional third
+argument, and `getMeta()` — not `get()` — reads that metadata back.
 
-```typescript
-import { DataScope } from '@object-ui/core'
+### Expressions
 
-const scope = new DataScope({ 
-  user: { name: 'John', role: 'admin' } 
-})
+`evaluateExpression` evaluates a `${...}` expression against a context.
 
-const userName = scope.get('user.name') // 'John'
-const isAdmin = scope.evaluate('${user.role === "admin"}') // true
+```typescript
+import { evaluateExpression } from '@object-ui/core'
+
+const isAdmin = evaluateExpression('${user.role === "admin"}', {
+  user: { name: 'John', role: 'admin' },
+}) // true
 ```
 
 ### Server Action Dispatch (`createServerActionHandler`)
@@ -68,6 +83,14 @@ object scope, which are injected:
 
 ```typescript
 import { createServerActionHandler } from '@object-ui/core'
+import type { ActionRunner, ServerActionFetch } from '@object-ui/core'
+
+// Injected by the host. Each stand-in is typed from the shipped surface, so
+// this example is checked against the factory's own config rather than a copy.
+declare const myAuthenticatedFetch: ServerActionFetch
+declare const currentObject: string | undefined
+declare const refetchData: () => void
+declare const runner: ActionRunner
 
 const script = createServerActionHandler({
   fetch: myAuthenticatedFetch,          // your auth wrapper (Bearer/cookies/...)
@@ -87,21 +110,22 @@ 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' }],
 })
 
+// @ts-expect-error readonly by defineSystemView — refused at compile time, not just at run time
 userListView.columns.push({ name: 'name' }) // ❌ TypeError (strict mode)
 isSystemView(userListView)                   // ✅ true
 
@@ -115,13 +139,90 @@ 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 |
 
 `Date`, `RegExp`, `Map`, `Set`, and class instances passed via `props` are
 intentionally **not** frozen so infrastructure objects keep working.
 
+### Field-level read gate (`withoutDeniedFields`)
+
+Field-level security gates what the renderer DRAWS (objectui#7215 /
+objectui#7230): a value the loaded permission policy denies is not shown, even
+when a backend serves it. `withoutDeniedFields` is that rule for one record —
+call it on a row before building a display value from the whole row (a record
+title, a lookup label, a search-hit label), so a denied field reads exactly as
+an absent one.
+
+```typescript
+import { withoutDeniedFields } from '@object-ui/core'
+
+// `policy` is structural: `usePermissions()` from `@object-ui/permissions`
+// satisfies it, as does any `{ isLoaded, checkField }` object.
+const policy = {
+  isLoaded: true,
+  checkField: (object: string, field: string) => !(object === 'account' && field === 'salary'),
+}
+
+withoutDeniedFields({ id: 'a1', name: 'Acme', salary: 100 }, policy, 'account')
+// { id: 'a1', name: 'Acme' }
+
+// A declared id field is kept without asking the policy, like `id` and `_id`:
+withoutDeniedFields({ account_code: 'A-1', salary: 100 }, policy, 'account', ['account_code'])
+// { account_code: 'A-1' }
+```
+
+- `id`, `_id` and every key in the optional fourth argument are never judged.
+- Before the policy loads, with no policy, with no object name, or for a value
+  that is not an object, the record comes back as it is.
+- When nothing is withheld the SAME object comes back, so callers can tell the
+  two cases apart by identity.
+
+### Undo snapshot for an update (`captureUpdateUndoData`)
+
+An `undoable` update restores exactly the fields it wrote, from their values
+before the write. `captureUpdateUndoData` is the one rule for reading those
+values off a record. `ActionRunner` uses it, and so should any surface that
+builds its own `update` Undo operation.
+
+```typescript
+import { captureUpdateUndoData, type FieldContainerLike } from '@object-ui/core'
+
+// The written object's field definitions, as its schema serves them
+// (`objectSchema.fields`). Below, `status` is a text field, `account` a
+// lookup and `config` a json field.
+declare const fields: FieldContainerLike
+
+captureUpdateUndoData(['status'], { id: 't1', status: 'open' }, fields) // { status: 'open' }
+captureUpdateUndoData(['status'], { id: 't1', status: null }, fields)   // { status: null }
+captureUpdateUndoData(['status'], { id: 't1' }, fields)                 // undefined
+
+// A relation read with `$expand` is captured as its stored id.
+captureUpdateUndoData(['account'], { id: 't1', account: { id: 'a1', name: 'Acme' } }, fields)
+// { account: 'a1' }
+
+// Any other field is captured as the record carries it, whatever its shape.
+captureUpdateUndoData(['config'], { id: 't1', config: { id: 'c1', mode: 'strict' } }, fields)
+// { config: { id: 'c1', mode: 'strict' } }
+```
+
+- A field counts as carried when it is an own key whose value is not
+  `undefined`. A carried `null` is a real empty value and is captured.
+- When any written field is not carried, the answer is `undefined` and the
+  caller offers no Undo at all. A record projected by `$select`, or one the
+  server stripped of fields the reader may not read, can lack a written field
+  while the server holds a real value for it; a partial or `null` snapshot
+  would overwrite that value on Undo.
+- A field the object declares as a relation (`lookup`, `master_detail`,
+  `user`, `tree`) is captured as the id it stores, and a `multiple` one as the
+  array of ids. `$expand` puts the related record where the id was, and
+  writing that record back into the reference is what Undo must never do.
+  Which fields are relations is read from `fields`, never from the value's
+  shape: a `json` field may hold an object with an `id`.
+- `fields` is required. Pass `undefined` only when the caller has no field
+  definitions for the object; nothing is then treated as a relation.
+
 ## Philosophy
 
 This package is designed to be **framework-agnostic**. It contains:

package/dist/actions/ActionEngine.d.ts

@@ -14,7 +14,7 @@
  * 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
@@ -118,8 +118,10 @@ export declare class ActionEngine {
      *      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
+     *      spelling, or an envelope whose `source` is `''` — means visible. A
+     *      value that is present but has no evaluable `source` (`0`, `{}`, an
+     *      array, an `ast`-only envelope) is a declared gate that faults
+     *      (objectui#11358), so it hides like any other. 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

package/dist/actions/ActionEngine.js

@@ -14,7 +14,7 @@
  * 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';
@@ -38,7 +38,6 @@ 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).`);
@@ -172,8 +171,10 @@ export class ActionEngine {
      *      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
+     *      spelling, or an envelope whose `source` is `''` — means visible. A
+     *      value that is present but has no evaluable `source` (`0`, `{}`, an
+     *      array, an `ast`-only envelope) is a declared gate that faults
+     *      (objectui#11358), so it hides like any other. 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
@@ -227,10 +228,12 @@ export class ActionEngine {
             // 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 }`).
+            // (objectui#3957). A predicate that says nothing (blank) must not be
+            // the reason an action is hidden from everyone. A value that is not a
+            // predicate at all is no longer "nothing" (objectui#11358): it is a
+            // declared gate the client cannot evaluate, the normalizer keeps it
+            // as such, and the `throwOnError` evaluation below hides it and
+            // reports it, as every action renderer's `visible` leg does.
             //
             // Booleans need no branch of their own: they are DECLARED (`visible:
             // false` is a verdict, objectui#3812) and `evaluateCondition`
@@ -242,7 +245,8 @@ export class ActionEngine {
             // 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
+            // Declared ⇒ the normalizer left something (possibly the declared-but-
+            // unevaluable `cel` envelope, which throws below), so there is no
             // `undefined` case left to handle here.
             const expr = toPredicateInput(raw);
             try {
@@ -262,7 +266,7 @@ export class ActionEngine {
                 // BARE field reference (`done` instead of `record.done`), which is
                 // an undeclared variable in the `{ record, recordId, objectName,
                 // user }` eval scope. Silently hiding it makes that bug invisible
-                // (the #2183 hunt). Warn once per predicate so it is diagnosable
+                // (the objectstack-ai/objectstack#2183 hunt). Warn once per predicate so it is diagnosable
                 // without spamming re-renders.
                 warnHiddenPredicate(ra.action.name, raw, err);
                 return false;