@object-ui/core 17.6.0 → 18.0.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,210 @@ 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.
+
+### Affordance-to-grant map (`AFFORDANCE_GRANTS`, `resolveAffordance`)
+
+Every console affordance that offers a write — a create form's fields, the
+record header's Edit, a list's New and Import, a lookup's "Create new", a grid
+row's Delete, and the rest — reads the grant it exercises from ONE table,
+`AFFORDANCE_GRANTS` (objectui#12082). A row names the CRUD-affordance bit the
+affordance needs, the object grant it exercises (`create`, `update` or
+`delete`) and, for an affordance that offers fields, the field question it asks
+(`create` for an insert, `write` for an update). The fields of a form, of the
+record page's in-place edit (`recordEdit`) and of a list's in-cell edit
+(`listInlineEdit`) each ask that question, so a field the caller's permission
+set marks `editable: false` is offered read-only on every one of them
+(objectui#12103). The `write` question is the server's whole update rule for a
+field, so for the record's owner field it also needs the transfer grant
+(`allowTransfer`, or `modifyAllRecords`).
+
+`resolveAffordance` is the one verdict: the object's managed-object policy, the
+server's effective API operation set and the caller's grant must all allow it,
+and the row's `userActions` predicates are surfaced only then.
+
+```typescript
+import { resolveAffordance, resolveFieldAffordance } from '@object-ui/core'
+
+// `perms` is structural: `usePermissions()` from `@object-ui/permissions`
+// satisfies it. With no provider mounted every grant reads open.
+const perms = {
+  isLoaded: true,
+  can: (_object: string, grant: 'create' | 'update' | 'delete') => grant === 'create',
+  checkField: (_object: string, _field: string, action: 'create' | 'write') => action === 'create',
+  getObjectApiOperations: () => undefined,
+}
+
+resolveAffordance('listNew', { objectSchema: null, objectName: 'orders', perms })
+// { allowed: true }  — the create grant is held
+resolveAffordance('recordEdit', { objectSchema: null, objectName: 'orders', perms })
+// { allowed: false } — Edit reads the update grant, which is not
+
+resolveFieldAffordance('createFormFields', perms, 'orders', 'title') // true
+resolveFieldAffordance('editFormFields', perms, 'orders', 'title')   // false
+```
+
+An affordance added later gets a row here and reads it through these functions;
+it does not spell its own `can(object, verb)`. That includes an affordance that
+reads NO grant at all — the calendar's quick-create and drag-to-reschedule
+(`calendarQuickCreate`, `calendarReschedule`) and the kanban card move
+(`kanbanCardMove`) were such affordances until they gained their rows. An
+affordance that writes with the same verb on the same object reuses that row:
+the record overlay's inline edit reads `recordEdit`, a gantt's bar edits and a
+grid's bulk field update read `rowEdit`, a gantt row's Delete reads `rowDelete`,
+the AI build panel's spreadsheet import reads `listImport`, a related list's
+Add existing reads `relatedNew` (a link row) or `relatedRowEdit` (a re-parent),
+and Setup's permission-set and position holders read `relatedNew` (a holder
+added) and `relatedRowDelete` (a holder removed), each asked of its assignment
+object (`sys_user_permission_set`, `sys_user_position`). Reaching Setup is not
+that grant: the Setup app asks `setup.access`, which a caller can hold while the
+server refuses their write of an assignment row.
+The record feed's writes have rows of their own, each asked of the object it
+writes: `feedComment` (a comment or reply, `sys_comment`), `feedReactionAdd` and
+`feedReactionRemove` (the caller's own `sys_comment_reaction` row), and
+`feedReactionColumn` (a reaction on a deployment that stores them in a
+`sys_comment` column). The map's
+enumeration pin in `@object-ui/plugin-form` (`affordanceGrantMap-12082.test.tsx`)
+also counts every write call site in the console tree and holds each to the row
+it sits behind, or to the reason it has none — and, for a component whose write
+its host gates (the import wizard), holds every mount to reading the row. The
+sites it found with no row yet formed a frozen backlog, which the pin now holds
+empty: a new one cannot be added, so a write affordance gets its row when it
+lands.
+
+### 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.
+
+### Which fields an `operation: 'update'` Undo covers
+
+The platform action route writes the `patch` of the declared action the
+action's `name` names, under the collected params. So `ActionRunner`'s Undo
+snapshot covers that declaration's `patch` keys plus the collected params. The
+runner reads the declaration from its context: a host publishes the object's
+declared actions as `objectActions`, beside `objectName` and `objectFields`.
+
+```typescript
+import { ActionRunner } from '@object-ui/core'
+
+// The object definition the host already holds, as the metadata API serves it.
+declare const taskDef: { fields: Record<string, unknown>; actions: unknown[] }
+
+// The same context `ActionProvider` takes. `objectFields` and `objectActions`
+// are read for `objectName`'s object only.
+new ActionRunner({
+  objectName: 'task',
+  objectFields: taskDef.fields,
+  objectActions: taskDef.actions,
+})
+```
+
+- The list is read only for the context's own object. A dispatch to another
+  object, or a host that publishes no list, reads the dispatched action's own
+  `patch`: a host that dispatches an object's action whole hands it in.
+- A page action row's own `patch` is never covered, and no action renderer
+  forwards one: `@objectstack/spec` 18 retires the key on the row. A row that
+  names an action whose declaration has no `patch` snapshots the collected
+  params alone.
+
+### Display time zone (`setDisplayTimeZone`)
+
+The date and datetime faces this package exports (`formatDate`,
+`formatDateTime`, `formatDateTimeCompactParts`, `formatRelativeDate`) render
+an instant in one display zone. A host declares it once; no caller passes a
+zone, so every face on the page agrees.
+
+```typescript
+import { formatDateTime, setDisplayTimeZone } from '@object-ui/core'
+
+formatDateTime('2026-09-02T03:00:00Z', { locale: 'en-US' }) // the viewer's zone
+setDisplayTimeZone('America/Los_Angeles')
+formatDateTime('2026-09-02T03:00:00Z', { locale: 'en-US' }) // "Sep 1, 2026, 08:00 PM"
+formatDateTime('2026-09-01', { locale: 'en-US' })           // "Sep 1, 2026, 12:00 AM", in every zone
+setDisplayTimeZone(undefined)                               // back to the viewer's zone
+```
+
+- A date-only value names a calendar day and keeps it in every zone, including
+  the `Date` that `toDisplayDate` builds for one and a caller hands on.
+- "Today" for the relative face is the display zone's today.
+- An IANA name the runtime's `Intl` does not know clears the zone, with a
+  console warning.
+- `getDisplayTimeZone()` reads it back, and `subscribeDisplayTimeZone(listener)`
+  reports changes in React's `useSyncExternalStore` shape. In a React tree,
+  `LocalizationProvider` from `@object-ui/i18n` sets it from its `timezone`
+  value; a renderer never calls the setter.
+
 ## 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;