@object-ui/core 17.6.0 → 17.7.0

package/README.md

@@ -7,7 +7,7 @@ Core logic, types, and validation for Object UI. Zero React dependencies.
 - 🎯 **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
 
@@ -36,8 +36,9 @@ import type {
 
 const mySchema: PageNodeSchema = {
   type: 'page',
+  pageType: 'app',
   title: 'My Page',
-  body: []
+  children: []
 }
 ```
 
@@ -45,28 +46,28 @@ const mySchema: PageNodeSchema = {
 
 ```typescript
 import { ComponentRegistry } from '@object-ui/core'
+import type { ComponentRenderer } from '@object-ui/core'
 
-ComponentRegistry.register('button', buttonMetadata)
-const metadata = ComponentRegistry.get('button')
+// Your component, in whatever renderer shape the host framework uses.
+declare const buttonRenderer: ComponentRenderer
+
+ComponentRegistry.register('button', buttonRenderer)
+const renderer = 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.
+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.
 
-### Data Scope
+### Expressions
 
-`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.
+`evaluateExpression` evaluates a `${...}` expression against a context.
 
 ```typescript
-import { DataScopeManager, evaluateExpression } from '@object-ui/core'
-
-const manager = new DataScopeManager()
-manager.registerScope('user', { data: { name: 'John', role: 'admin' } })
+import { evaluateExpression } from '@object-ui/core'
 
-const userName = manager.getScope('user')?.data.name // 'John'
 const isAdmin = evaluateExpression('${user.role === "admin"}', {
   user: { name: 'John', role: 'admin' },
 }) // true
@@ -82,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/...)
@@ -116,6 +125,7 @@ export const userListView = defineSystemView({
   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
 
@@ -136,6 +146,83 @@ isSystemView(draft)                          // false — clone is no longer Sys
 `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

@@ -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

@@ -171,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
@@ -226,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`
@@ -241,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 {
@@ -261,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;