@object-ui/core 15.0.0 → 16.1.0

package/CHANGELOG.md

@@ -1,5 +1,252 @@
 # @object-ui/core
 
+## 16.1.0
+
+### Minor Changes
+
+- 1c8935a: feat(app-shell): render ActionParamDialog params through the shared form field-widget renderer (ADR-0059, #2700)
+
+  `ActionParamDialog` no longer hand-rolls a per-type ternary chain (select /
+  lookup / textarea / number / boolean, everything else → text input). Every
+  declared action param now renders through the same `fieldWidgetMap` the object
+  form uses, so a param of ANY form-supported field type — `file`, `image`,
+  `richtext`, `markdown`, `color`, `address`, `code`, `date`, … — gets its real
+  widget, lazily loaded behind `Suspense`. Subsumes the single `file` branch ask
+  in #2698: `type: 'file'` params render the real `FileField` upload control via
+  the ambient `UploadProvider`, honoring `multiple`/`accept`/`maxSize`.
+
+  - `@object-ui/fields`: new exports `resolveFormWidgetType(type)` (widget-key
+    resolution incl. spec aliases, text fallback) and `getLazyFieldWidget(type)`
+    (per-type-cached `React.lazy` over the form's own widget loaders).
+  - `@object-ui/core`: `ActionParamDef` gains `accept`/`maxSize`; `multiple` is
+    now general widget config (was lookup-only).
+  - `@object-ui/app-shell`: new pure `paramToField()` adapter (param → field
+    shape) with a drift test pinning param support ⊇ form support (`FORM_FIELD_TYPES`),
+    mirroring the FieldEditWidget parity guard; `resolveActionParams()` inherits
+    `multiple`/`accept`/`maxSize` from the referenced field for every type.
+    `required` validation, `visible` CEL gating, helpText, error styling, and
+    value shapes for previously-supported types are unchanged.
+
+- 2e7d7f0: feat(evaluator): route `{ dialect: 'cel' }` component/action predicates to the canonical CEL engine (#2661)
+
+  Component and action `visible` / `disabled` / `hidden` predicates were evaluated
+  by the home-grown JS `ExpressionEvaluator`, while field rules
+  (`visibleWhen`/`readonlyWhen`/`requiredWhen`, via `fieldRules.ts`) and row/list
+  conditionals (via `evalRowPredicate`) already delegate to the canonical
+  `@objectstack/formula` engine. That split meant a `{ dialect: 'cel' }` predicate
+  in a renderer/action surface was executed as **JavaScript** — CEL-only forms
+  (`x in list`, `has()`, typed `==`, the `today()`/`daysFromNow()` catalog) behaved
+  differently from, or faulted against, the server's enforcement.
+
+  This converges the remaining tier onto the same engine:
+
+  - **`@object-ui/core`** — `ExpressionEvaluator.evaluateCondition` now detects a
+    `{ dialect: 'cel', source }` envelope and evaluates it on `@objectstack/formula`
+    (via `evalFieldPredicate`), binding the `record` namespace plus the whole
+    context bag as top-level scope (`record.*`, `features.*`, `user.*`, `app.*`).
+    Fail-soft to visible/enabled to match the legacy default; `throwOnError`
+    callers still fail closed on a _faulting_ predicate (a genuine `false` never
+    throws). This fixes every `SchemaRenderer` visibility/disabled read at once.
+  - **`@object-ui/react`** — `toPredicateInput` preserves a CEL envelope instead of
+    collapsing it to a `${source}` string, and `useCondition` accepts and forwards
+    the envelope (keyed on a stable `(dialect, source)` so it doesn't re-evaluate
+    each render). Action buttons (`action-icon`/`group`/`bar`/`button`) therefore
+    evaluate CEL `visible`/`enabled`/`disabled` on the canonical engine.
+
+  **Back-compat:** bare strings and `${…}` templates stay on the legacy JS path
+  (deprecation window); only an explicit `{ dialect: 'cel' }` envelope is rerouted.
+  `{ dialect: 'template' }` is unaffected.
+
+  Together with the `^15.1.1` alignment (#2662), a renderer CEL predicate now
+  reaches the identical verdict as the server — including the framework's
+  `dateField == today()` equality fix (objectstack-ai/framework#3205) once it
+  lands in a published 15.x. The broader home-grown-vs-canonical divergence
+  motivation is #2661.
+
+- 31b77d4: **Add the explicit `engine-owned` lifecycle bucket (tracks framework ADR-0103 addendum / #3343).** The framework split the overloaded `managedBy: 'system'` bucket by promoting the engine-owned case to its own enum value; this mirrors it in the UI type + runtime + badge.
+
+  - **`@object-ui/types`** — `ManagedByBucket` union and `MANAGED_BY_BUCKETS` gain `'engine-owned'` (canonical order: `platform, config, system, engine-owned, append-only, better-auth`). The union stays closed, so every consumer that missed the new value is a compile error.
+  - **`@object-ui/core`** — `resolveCrudAffordances` gains the `engine-owned` default row (identical all-locked matrix as `system`/`append-only`), so `isObjectInlineEditable` / the grid + form gates treat it as read-only automatically.
+  - **`@object-ui/app-shell`** — the `ManagedByBadge` renders `engine-owned` with the same read-only "System-managed" copy as a locked `system` object (reuses the existing `managedByBadge.system` i18n key — zero translation churn; the distinction is at the schema level, not the user-facing string), and `resolveManagedByEmptyState` reuses the `system` engine-owned empty state.
+
+  Behaviour-preserving: `engine-owned` resolves to the same locked affordances `system` did by default, so nothing about how a locked object renders changes — the value just makes the schema self-documenting. New unit coverage for the bucket in `resolveCrudAffordances` / `isObjectInlineEditable` / `MANAGED_BY_BUCKETS` / the empty-state helper.
+
+- 62b9ab5: feat(data): unify master-detail saves behind `DataSource.batchTransaction`, isolate the non-atomic fallback in the adapter (#2679)
+
+  Master-detail saves (`MasterDetailForm`, `LineItemsPanel`) now always persist
+  through `dataSource.batchTransaction(operations)` — one ordered cross-object
+  operation list, with `{ $ref: <op index> }` linking a child to a parent created
+  in the same batch. The form no longer contains any client-side orchestration or
+  best-effort compensation-delete; that atomicity anti-pattern is gone from the UI
+  layer (framework #1604 / framework ADR-0034 item 4).
+
+  - **`@object-ui/types`** — `batchTransaction?` is now a first-class (optional)
+    method on the `DataSource` contract, typed via `BatchTransactionOperation` /
+    `BatchRef`. Replaces the previous `(dataSource as any).batchTransaction`
+    method-sniffing.
+  - **`@object-ui/core`** — new `emulateBatchTransaction(dataSource, operations)`
+    (sequential writes, `$ref` resolution, best-effort reverse-order compensation)
+    and `runBatchTransaction(dataSource, operations)` (prefers the adapter's method,
+    emulates otherwise). `ApiDataSource` / `ValueDataSource` implement
+    `batchTransaction` via the emulation.
+  - **`@object-ui/data-objectstack`** — `ObjectStackAdapter.batchTransaction` uses
+    the server's atomic `POST /api/v1/batch`, prefers the typed
+    `client.data.batchTransaction` SDK method when the installed client exposes it,
+    and degrades to the client-side emulation ONLY when the endpoint is missing
+    (404/405) or the runtime can't do transactions (501). Real errors (400/401/403/
+    409/500) still surface. This is the isolated, tested home of the non-atomic
+    fallback.
+  - **`@object-ui/plugin-form`** — removed `applyDetail` / `createMany` /
+    `ApplyDetailResult` from `masterDetailTx.ts`; `MasterDetailForm` and
+    `LineItemsPanel` build ops and call `runBatchTransaction`. `LineItemsPanel`
+    saves are now atomic on a capable backend, with the rollup folded into the same
+    batch.
+
+  No behavior change on a current ObjectStack backend (it has `/api/v1/batch`);
+  older/limited backends keep a working — now clearly non-atomic — save path.
+
+- 1629313: feat(fields): RadioField per-option `visibleWhen` cascading + `dependsOn` gating; single-source the option resolver
+
+  Brings `RadioField` to parity with `SelectField` / `MultiSelectField` for ADR-0058
+  cascading & role-gated options, and collapses the three copies of the
+  gate-then-filter logic onto one shared resolver.
+
+  - **`@object-ui/core`**: new pure `resolveCascadingOptions(rawOptions, record, dependsOn, scope)`
+    → `{ options, gated, dependsOnFields }` — the single source of truth for
+    `dependsOn` gating + per-option `visibleWhen` filtering.
+  - **`@object-ui/fields`**: `RadioField` now narrows its offered radios against
+    the live record + `current_user`, gates behind a "select the parent first"
+    hint while a `dependsOn` field is empty, and clears a value no longer offered
+    (scalar cascade clear). The `useCascadingOptions` hook is refactored to a thin
+    React wrapper over `resolveCascadingOptions`.
+  - **`@object-ui/components`**: the form renderer's inline option pre-filter and
+    cross-field cascade-clear effect now call `resolveCascadingOptions` instead of
+    re-deriving gating/filtering, so they can't drift from the widgets (no
+    behavior change).
+  - Tests: `RadioField.cascade.test.tsx` mirrors the select cascade tests; core
+    gains `resolveCascadingOptions` unit coverage.
+
+- 2331ac9: feat(report): drill a date-bucket cell into its time range, not a superset (#1752)
+
+  Clicking a report/dashboard cell grouped by a `dateGranularity` date dimension
+  ("2026-Q2") used to drill into a **superset** — the date dimension was skipped,
+  so the record list spanned every time bucket. It now scopes to the clicked
+  bucket's half-open range, consuming the framework's new `drillRanges` sidecar.
+
+  - **`@object-ui/core`** — `buildDatasetDrillFilter` accepts the per-row
+    `drillRanges` and emits an ObjectQL range operator object
+    (`{ [field]: { $gte, $lt } }`) alongside the equality dims.
+  - **`@object-ui/plugin-report` / `@object-ui/plugin-dashboard`** — the report
+    renderer and dashboard widget forward `drillRanges`, and a **date-only**
+    report (no equality drill dim) is now drillable via the range alone.
+  - **`@object-ui/app-shell`** — the "Open in list →" escape hatch
+    (`useOpenRecordList`) now targets the ADR-0055 **bare data surface**
+    (`/:object/data`, "the URL is the view" — no baked-in view filter to
+    over-narrow the drill) and serializes a range to the
+    `filter[field][gte|lt]` operator contract. `ObjectDataPage` parses those
+    operators (equality shorthand unchanged), renders a range as a single chip,
+    and removes both bounds together. A new `drillUrlFilters` module owns the
+    write/read serialization so both sides can't drift (round-trip tested).
+
+  Companion to the framework analytics change (objectstack-ai/framework#3256).
+
+### Patch Changes
+
+- 8b8b744: chore(deps): align `@objectstack/formula` / `lint` / `client` to `^15.1.1`
+
+  These three were still pinned to `^14.6.0` while `@objectstack/spec` was already
+  `^15.1.1` — a version skew from the v15 upgrade (formula/lint/client publish in
+  lockstep with spec, and their own 15.0.0 entries are pure dependency bumps, so
+  this is alignment, not a behavioral migration).
+
+  Practical effect: the client-side field-rule evaluation
+  (`visibleWhen`/`readonlyWhen`/`requiredWhen` via `fieldRules.ts`, which delegates
+  to `@objectstack/formula`'s `ExpressionEngine`) now tracks the 15.x engine — and
+  will pick up the framework's `dateField == today()` equality fix
+  (objectstack-ai/framework#3205) automatically at the next 15.x release via the
+  caret range. Renderer/action `visible`/`disabled` predicates are unaffected (they
+  use the home-grown JS evaluator — tracked separately in #2661).
+
+- 7cf4051: chore(deps): align every `@objectstack/*` dependency to `^16.0.0-rc.0`
+
+  Bumps `@objectstack/spec` / `client` / `formula` / `lint` from `^15.1.1` to the
+  `16.0.0-rc.0` pre-release across the workspace (root + `apps/console` +
+  `apps/site` + all consuming packages). ObjectUI's own packages are already on
+  major 16, so this closes the 15↔16 skew between ObjectUI and the `@objectstack`
+  contract libraries (which publish in lockstep with `spec`).
+
+  This is a dependency alignment, not a behavioral migration: the full workspace
+  build (43/43) and the `@objectstack`-consuming package test suites
+  (`core` / `app-shell` / `data-objectstack` / `plugin-form` / `types`) are green
+  against `16.0.0-rc.0` with no source changes required.
+
+  Practical effect: `@objectstack/client@16.0.0-rc.0` now ships
+  `data.batchTransaction` (framework #3271), so `ObjectStackAdapter`'s feature
+  detect (`typeof client.data.batchTransaction === 'function'`) routes
+  master-detail cross-object saves through the typed SDK method instead of the
+  raw `fetch('/api/v1/batch')` fallback — realizing the "verify SDK path" half of
+  #2694. The raw-fetch branch stays as a defensive fallback (removal tracked in
+  #2694).
+
+- 6d4fbe6: **Consolidate the `managedBy` lifecycle-bucket logic into one shared source of truth (follows framework ADR-0103).** The bucket taxonomy was hand-mirrored in several places — `crudAffordances.ts`, `ManagedByBadge.tsx` (its own `Bucket` union + `isWriteOptedIn` + the writable-system derivation), and `plugin-detail`'s `record-details.tsx` (`NON_EDITABLE_BUCKETS`, duplicated because it can't depend on app-shell) — a drift risk, and the object-schema `managedBy` type was open-ended (`(string & {})`) so unknown buckets slipped through and silently defaulted to fully-editable.
+
+  - **`@object-ui/types`** now owns the closed `ManagedByBucket` union (+ `MANAGED_BY_BUCKETS`), and `ObjectSchema.managedBy` is tightened from `'platform' | 'better-auth' | (string & {})` to that union — unknown buckets are now a type error at authoring time.
+  - **`@object-ui/core`** now owns the React-free runtime logic — `resolveCrudAffordances`, `isWriteOptedIn`, `isSystemWritable`, `isObjectInlineEditable` — reachable by every UI package including `plugin-detail` (which could not import app-shell).
+  - **`app-shell/utils/crudAffordances.ts`** is now a thin re-export of `@object-ui/core` (existing imports keep working); `ManagedByBadge` consumes the shared `isSystemWritable`; `plugin-detail` `record-details.tsx` replaces its hand-mirrored `NON_EDITABLE_BUCKETS` with `isObjectInlineEditable`.
+
+  Behavior-preserving — all existing affordance/edit-gate tests stay green; the shared module adds direct unit coverage (including the previously-untested `isSystemWritable` derivation). Translated copy (badge variants, empty-state messages) stays in app-shell.
+
+- 0a3710b: **Finish the `managedBy` / `userActions` de-dup — one parser for the override shape (completes objectui#2712, framework#3343).** #2712 consolidated the bucket _union_ + affordance _set_ mirrors but left four surfaces still parsing the `userActions.{create,edit,delete}` override shape by hand. They now all route through the shared `@object-ui/core` policy, so no package re-implements the boolean / #2614-object-form parse locally.
+
+  - **`@object-ui/core`** promotes the internal `normalizeOverride` to the exported **`normalizeUserAction(v, base)`** (the one parser) and adds **`userActionPredicates(v)`** for per-record CEL predicate extraction.
+  - **`app-shell/utils/managedByEmptyState.ts`** — the writable-`system` create check and its local `EmptyStateUserActions` interface are replaced by `resolveCrudAffordances({ managedBy, userActions }).create`.
+  - **`plugin-grid/rowCrudAffordances.ts`** — the local `isOptedOut` / `predicatesOf` helpers (and duplicated `RowCrudUserAction` / `RowCrudPredicates` types) fold into `normalizeUserAction`; the historical type names stay re-exported for compat.
+  - **`plugin-detail/RelatedList.tsx`** — its inline `predicatesOf` fold into `userActionPredicates`.
+  - **`plugin-form/ObjectForm.tsx`** — the hand-rolled `managedBy !== 'platform'` blanket lock + `userActions` unlock is replaced by the resolved affordance for the current mode (`edit` / `create`), the **same** `resolveCrudAffordances` contract the detail (`isObjectInlineEditable`) and grid surfaces use.
+
+  Behavior-preserving for `platform` / `system` / `append-only` / `better-auth`, with one deliberate alignment: an admin-editable **`config`**-bucket object (e.g. `sys_webhook`, `sys_permission_set`) is now editable in `ObjectForm` — it was previously over-locked as "non-`platform`", while detail/grid already treated it as editable (`config` resolves `edit: true`). New unit coverage for the shared parser and the config / create-mode form gate; all existing affordance/edit-gate tests stay green.
+
+- eee4ded: feat(fields): render `select` + `multiple` through the multi-value chip picker; restore fields/core lint gates
+
+  - **Multi-value select** — a `select` field/param declared `multiple: true`
+    now renders the multi-value chip picker (the `multiselect` widget) and stores
+    a `string[]`, instead of collapsing to a single-value dropdown that could
+    hold only one value. The delegation lives inside `SelectField`, so the object
+    form, the inline grid editor, and the app-shell `ActionParamDialog` all
+    inherit it from the one `select` widget with no per-surface drift. Single
+    selects keep the cascading dropdown (multi + per-option `visibleWhen`
+    cascading is not a combination in use today).
+  - **`autonumber` mapping is unchanged** here; this change is orthogonal.
+  - **Lint gates restored** — fixed the pre-existing baseline lint errors that
+    had left the `@object-ui/fields` and `@object-ui/core` package lints red (so
+    the gate could not catch new violations): `react-hooks/rules-of-hooks` in
+    `ImageField` / `TextAreaField` / `index.tsx` (hooks hoisted above early
+    returns; the `useFieldTranslate` hook no longer wrapped in try/catch), plus
+    `no-useless-assignment` / `no-useless-escape` / `no-control-regex` /
+    `prefer-const` / `preserve-caught-error` in the core evaluator and utils. No
+    behavior change from the lint fixes.
+
+- Updated dependencies [7cf4051]
+- Updated dependencies [94d4876]
+- Updated dependencies [2b17339]
+- Updated dependencies [31b77d4]
+- Updated dependencies [6d4fbe6]
+- Updated dependencies [62b9ab5]
+- Updated dependencies [29c6040]
+- Updated dependencies [faebac3]
+- Updated dependencies [199fa83]
+  - @object-ui/types@16.1.0
+
+## 16.0.0
+
+### Patch Changes
+
+- Updated dependencies [210806a]
+- Updated dependencies [b4ef588]
+- Updated dependencies [5534535]
+- Updated dependencies [9b8f978]
+  - @object-ui/types@16.0.0
+
 ## 15.0.0
 
 ### Patch Changes

package/dist/actions/ActionRunner.d.ts

@@ -258,6 +258,12 @@ export interface ActionParamDef {
      * gated on `features.phoneNumber`). Absent = always visible.
      */
     visible?: string;
+    /** Accepted upload types (MIME types / extensions) for `file`/`image` params. */
+    accept?: string[];
+    /** Max upload size in bytes for `file`/`image` params. */
+    maxSize?: number;
+    /** Allow multiple values (file/image/lookup/user params → array value). */
+    multiple?: boolean;
     /** Object name the lookup picker queries (`reference_to` on the field). */
     referenceTo?: string;
     /** Field on the referenced record used as the human label (default `name`). */
@@ -266,8 +272,6 @@ export interface ActionParamDef {
     idField?: string;
     /** Optional secondary line shown under the label in the picker. */
     descriptionField?: string;
-    /** Allow multi-select (renders chip list). */
-    multiple?: boolean;
     /** Template (e.g. `{first_name} {last_name}`) used to build the label. */
     titleFormat?: string;
     /** Column definitions surfaced in the enterprise `RecordPickerDialog`. */

package/dist/adapters/ApiDataSource.d.ts

@@ -8,7 +8,7 @@
  * A DataSource adapter for the `provider: 'api'` ViewData mode.
  * Makes raw HTTP requests using the HttpRequest configs from ViewData.
  */
-import type { DataSource, QueryParams, QueryResult, HttpRequest, AggregateParams, AggregateResult } from '@object-ui/types';
+import type { DataSource, BatchTransactionOperation, QueryParams, QueryResult, HttpRequest, AggregateParams, AggregateResult } from '@object-ui/types';
 export interface ApiDataSourceConfig {
     /** HttpRequest config for read operations (find, findOne) */
     read?: HttpRequest;
@@ -54,6 +54,16 @@ export declare class ApiDataSource<T = any> implements DataSource<T> {
     delete(_resource: string, id: string | number, opts?: {
         ifMatch?: string;
     }): Promise<boolean>;
+    /**
+     * Client-side (non-atomic) cross-object batch — a generic REST endpoint has
+     * no transactional batch primitive, so this delegates to the shared
+     * emulation (sequential writes + `$ref` resolution + best-effort
+     * compensation). Adapters fronting a server that DOES offer an atomic batch
+     * should override this to issue a single request.
+     */
+    batchTransaction(operations: BatchTransactionOperation[]): Promise<{
+        results: any[];
+    }>;
     getObjectSchema(_objectName: string): Promise<any>;
     getView(_objectName: string, _viewId: string): Promise<any | null>;
     getApp(_appId: string): Promise<any | null>;

package/dist/adapters/ApiDataSource.js

@@ -8,6 +8,7 @@
  * A DataSource adapter for the `provider: 'api'` ViewData mode.
  * Makes raw HTTP requests using the HttpRequest configs from ViewData.
  */
+import { emulateBatchTransaction } from './batchTransaction.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -241,6 +242,16 @@ export class ApiDataSource {
             return false;
         }
     }
+    /**
+     * Client-side (non-atomic) cross-object batch — a generic REST endpoint has
+     * no transactional batch primitive, so this delegates to the shared
+     * emulation (sequential writes + `$ref` resolution + best-effort
+     * compensation). Adapters fronting a server that DOES offer an atomic batch
+     * should override this to issue a single request.
+     */
+    batchTransaction(operations) {
+        return emulateBatchTransaction(this, operations);
+    }
     async getObjectSchema(_objectName) {
         // Generic API endpoints typically don't expose schema metadata.
         // Return a minimal stub so schema-dependent components don't crash.

package/dist/adapters/ValueDataSource.d.ts

@@ -8,7 +8,7 @@
  * A DataSource adapter for the `provider: 'value'` ViewData mode.
  * Operates entirely on an in-memory array — no network requests.
  */
-import type { DataSource, MutationEvent, QueryParams, QueryResult, AggregateParams, AggregateResult } from '@object-ui/types';
+import type { DataSource, BatchTransactionOperation, MutationEvent, QueryParams, QueryResult, AggregateParams, AggregateResult } from '@object-ui/types';
 export interface ValueDataSourceConfig<T = any> {
     /** The static data array */
     items: T[];
@@ -48,6 +48,14 @@ export declare class ValueDataSource<T = any> implements DataSource<T> {
     update(_resource: string, id: string | number, data: Partial<T>): Promise<T>;
     delete(_resource: string, id: string | number): Promise<boolean>;
     bulk(_resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]>;
+    /**
+     * Client-side (non-atomic) cross-object batch — this in-memory adapter has
+     * no server transaction, so it delegates to the shared emulation. Per-op
+     * MutationEvents come from the `create`/`update`/`delete` primitives above.
+     */
+    batchTransaction(operations: BatchTransactionOperation[]): Promise<{
+        results: any[];
+    }>;
     getObjectSchema(_objectName: string): Promise<any>;
     getView(_objectName: string, _viewId: string): Promise<any | null>;
     getApp(_appId: string): Promise<any | null>;

package/dist/adapters/ValueDataSource.js

@@ -8,6 +8,7 @@
  * A DataSource adapter for the `provider: 'value'` ViewData mode.
  * Operates entirely on an in-memory array — no network requests.
  */
+import { emulateBatchTransaction } from './batchTransaction.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -341,6 +342,14 @@ export class ValueDataSource {
         }
         return results;
     }
+    /**
+     * Client-side (non-atomic) cross-object batch — this in-memory adapter has
+     * no server transaction, so it delegates to the shared emulation. Per-op
+     * MutationEvents come from the `create`/`update`/`delete` primitives above.
+     */
+    batchTransaction(operations) {
+        return emulateBatchTransaction(this, operations);
+    }
     async getObjectSchema(_objectName) {
         // Infer a minimal schema from the first item
         if (this.items.length === 0)

package/dist/adapters/batchTransaction.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ObjectUI — batchTransaction emulation
+ * 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.
+ *
+ * Client-side emulation of {@link DataSource.batchTransaction} for adapters
+ * that lack a server-side transactional batch endpoint. This is the single,
+ * tested home for the non-atomic fallback (ObjectStack objectui #2679 /
+ * framework #1604 / ADR-0034 item 4): components call `runBatchTransaction`
+ * unconditionally and never orchestrate cross-object writes themselves.
+ *
+ * The emulation runs operations sequentially — NOT the old `bulk('create')`
+ * grouping — because sequential execution is what makes `{ $ref: i }`
+ * resolution and ordered semantics correct (a child create must observe the
+ * parent's freshly-minted id). Line-item counts are small, so the extra
+ * round-trips are acceptable.
+ */
+import type { BatchTransactionOperation, DataSource } from '@object-ui/types';
+/**
+ * Emulate an atomic batch over a plain DataSource by executing its `create`/
+ * `update`/`delete` primitives in order.
+ *
+ * NOT atomic: on failure it best-effort compensates by deleting the records
+ * it created (reverse order — children before parent), then rethrows the
+ * original error. Updates and deletes that already ran cannot be undone; a
+ * compensation delete that itself fails is swallowed (`Promise.allSettled`).
+ * This is the documented reason a server-backed `batchTransaction` is
+ * strictly better — a true transaction simply never commits.
+ *
+ * MutationEvents are deliberately NOT emitted here: the underlying
+ * `create`/`update`/`delete` primitives already emit per-op on adapters that
+ * support `onMutation`, so emitting here too would double-fire.
+ */
+export declare function emulateBatchTransaction<T = any>(dataSource: DataSource<T>, operations: BatchTransactionOperation[]): Promise<{
+    results: any[];
+}>;
+/**
+ * Persist an ordered cross-object batch, preferring the adapter's native
+ * (potentially atomic) `batchTransaction` and falling back to
+ * {@link emulateBatchTransaction} when the adapter does not implement it.
+ *
+ * This is the single entry point UI components should call — they stay
+ * ignorant of whether the underlying save is truly atomic.
+ */
+export declare function runBatchTransaction<T = any>(dataSource: DataSource<T>, operations: BatchTransactionOperation[]): Promise<{
+    results: any[];
+}>;

package/dist/adapters/batchTransaction.js

@@ -0,0 +1,118 @@
+/**
+ * ObjectUI — batchTransaction emulation
+ * 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.
+ *
+ * Client-side emulation of {@link DataSource.batchTransaction} for adapters
+ * that lack a server-side transactional batch endpoint. This is the single,
+ * tested home for the non-atomic fallback (ObjectStack objectui #2679 /
+ * framework #1604 / ADR-0034 item 4): components call `runBatchTransaction`
+ * unconditionally and never orchestrate cross-object writes themselves.
+ *
+ * The emulation runs operations sequentially — NOT the old `bulk('create')`
+ * grouping — because sequential execution is what makes `{ $ref: i }`
+ * resolution and ordered semantics correct (a child create must observe the
+ * parent's freshly-minted id). Line-item counts are small, so the extra
+ * round-trips are acceptable.
+ */
+/** Best-effort id extraction across the record shapes adapters return. */
+function idOf(rec) {
+    if (rec == null)
+        return undefined;
+    return rec.id ?? rec._id ?? rec.recordId;
+}
+/**
+ * Replace top-level `{ $ref: i }` values in an op payload with the id produced
+ * by operation `i`. Only backward references are valid — a forward or
+ * unresolved ref throws (the builders only ever emit `{ $ref: 0 }` pointing at
+ * an already-executed parent, so this is a guard, not a normal path).
+ */
+function resolveRefs(data, results) {
+    const out = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (value &&
+            typeof value === 'object' &&
+            !Array.isArray(value) &&
+            typeof value.$ref === 'number') {
+            const refIndex = value.$ref;
+            const id = idOf(results[refIndex]);
+            if (id === undefined) {
+                throw new Error(`batchTransaction: field "${key}" references operation ${refIndex}, ` +
+                    `which has not produced an id (forward or invalid $ref)`);
+            }
+            out[key] = id;
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+/**
+ * Emulate an atomic batch over a plain DataSource by executing its `create`/
+ * `update`/`delete` primitives in order.
+ *
+ * NOT atomic: on failure it best-effort compensates by deleting the records
+ * it created (reverse order — children before parent), then rethrows the
+ * original error. Updates and deletes that already ran cannot be undone; a
+ * compensation delete that itself fails is swallowed (`Promise.allSettled`).
+ * This is the documented reason a server-backed `batchTransaction` is
+ * strictly better — a true transaction simply never commits.
+ *
+ * MutationEvents are deliberately NOT emitted here: the underlying
+ * `create`/`update`/`delete` primitives already emit per-op on adapters that
+ * support `onMutation`, so emitting here too would double-fire.
+ */
+export async function emulateBatchTransaction(dataSource, operations) {
+    const results = [];
+    const created = [];
+    try {
+        for (const op of operations) {
+            const action = op.action ?? 'create';
+            if (action === 'create') {
+                const record = await dataSource.create(op.object, resolveRefs(op.data ?? {}, results));
+                results.push(record);
+                const id = idOf(record);
+                if (id)
+                    created.push({ object: op.object, id });
+            }
+            else if (action === 'update') {
+                if (op.id == null) {
+                    throw new Error(`batchTransaction: update on "${op.object}" requires an id`);
+                }
+                results.push(await dataSource.update(op.object, op.id, resolveRefs(op.data ?? {}, results)));
+            }
+            else {
+                if (op.id == null) {
+                    throw new Error(`batchTransaction: delete on "${op.object}" requires an id`);
+                }
+                results.push(await dataSource.delete(op.object, op.id));
+            }
+        }
+        return { results };
+    }
+    catch (err) {
+        // Best-effort compensation: undo the creates we made, newest first, so a
+        // child is removed before the parent it points at. Failures are ignored —
+        // there is nothing more we can do client-side.
+        if (created.length > 0) {
+            await Promise.allSettled([...created].reverse().map((c) => dataSource.delete(c.object, c.id)));
+        }
+        throw err;
+    }
+}
+/**
+ * Persist an ordered cross-object batch, preferring the adapter's native
+ * (potentially atomic) `batchTransaction` and falling back to
+ * {@link emulateBatchTransaction} when the adapter does not implement it.
+ *
+ * This is the single entry point UI components should call — they stay
+ * ignorant of whether the underlying save is truly atomic.
+ */
+export function runBatchTransaction(dataSource, operations) {
+    return typeof dataSource.batchTransaction === 'function'
+        ? dataSource.batchTransaction(operations)
+        : emulateBatchTransaction(dataSource, operations);
+}

package/dist/adapters/index.d.ts

@@ -8,3 +8,4 @@
 export { ApiDataSource, type ApiDataSourceConfig } from './ApiDataSource.js';
 export { ValueDataSource, type ValueDataSourceConfig } from './ValueDataSource.js';
 export { resolveDataSource, type ResolveDataSourceOptions } from './resolveDataSource.js';
+export { emulateBatchTransaction, runBatchTransaction } from './batchTransaction.js';

package/dist/adapters/index.js

@@ -11,3 +11,4 @@
 export { ApiDataSource } from './ApiDataSource.js';
 export { ValueDataSource } from './ValueDataSource.js';
 export { resolveDataSource } from './resolveDataSource.js';
+export { emulateBatchTransaction, runBatchTransaction } from './batchTransaction.js';

package/dist/evaluator/ExpressionEvaluator.d.ts

@@ -86,6 +86,16 @@ export declare class ExpressionEvaluator {
         dialect?: string;
         source?: string;
     }, options?: EvaluationOptions): boolean;
+    /**
+     * Evaluate a `{ dialect: 'cel' }` predicate on the canonical `@objectstack/formula`
+     * engine (via `evalFieldPredicate`), binding this evaluator's context: the
+     * `record` key as the `record` namespace and the whole context bag as top-level
+     * scope so `record.*`, `features.*`, `user.*`, `app.*` all resolve. Fail-soft to
+     * `true` (visible/enabled — the legacy default) unless the caller opted into
+     * `throwOnError`, in which case a *faulting* predicate (bad field / non-CEL
+     * syntax) throws; a genuine `false` never throws.
+     */
+    private evaluateCelCondition;
     /**
      * Update the context with new data
      */

package/dist/evaluator/ExpressionEvaluator.js

@@ -17,6 +17,7 @@
 import { ExpressionContext } from './ExpressionContext.js';
 import { ExpressionCache } from './ExpressionCache.js';
 import { FormulaFunctions } from './FormulaFunctions.js';
+import { evalFieldPredicate } from './fieldRules.js';
 /**
  * Expression evaluator for dynamic UI expressions
  */
@@ -141,6 +142,10 @@ export class ExpressionEvaluator {
             return compiled.fn(...varValues);
         }
         catch (error) {
+            // The original error's message is inlined below. We can't pass it as the
+            // `Error` `cause` option because this package targets ES2020, whose lib
+            // types the 1-arg `Error` constructor only; hence the scoped disable.
+            // eslint-disable-next-line preserve-caught-error
             throw new Error(`Failed to evaluate expression "${expression}": ${error.message}`);
         }
     }
@@ -177,6 +182,18 @@ export class ExpressionEvaluator {
         if (typeof condition === 'boolean') {
             return condition;
         }
+        // #2661 — a CEL-dialect envelope routes to the canonical `@objectstack/formula`
+        // engine (the one `fieldRules` / list conditionals already use), NOT the legacy
+        // JS evaluator below. This makes a component / action `visible` / `disabled`
+        // predicate reach the SAME verdict as server enforcement — including CEL-only
+        // behavior like `record.due_date == today()` (framework#3205). Bare strings and
+        // `${…}` templates stay on the legacy path (back-compat deprecation window);
+        // only an explicit `{ dialect: 'cel' }` envelope is rerouted.
+        if (condition && typeof condition === 'object'
+            && condition.dialect === 'cel'
+            && typeof condition.source === 'string') {
+            return this.evaluateCelCondition(condition.source, options);
+        }
         // Unwrap Expression envelope (see `evaluate` for rationale).
         if (condition && typeof condition === 'object' && typeof condition.source === 'string') {
             condition = condition.source;
@@ -215,6 +232,37 @@ export class ExpressionEvaluator {
             return true;
         }
     }
+    /**
+     * Evaluate a `{ dialect: 'cel' }` predicate on the canonical `@objectstack/formula`
+     * engine (via `evalFieldPredicate`), binding this evaluator's context: the
+     * `record` key as the `record` namespace and the whole context bag as top-level
+     * scope so `record.*`, `features.*`, `user.*`, `app.*` all resolve. Fail-soft to
+     * `true` (visible/enabled — the legacy default) unless the caller opted into
+     * `throwOnError`, in which case a *faulting* predicate (bad field / non-CEL
+     * syntax) throws; a genuine `false` never throws.
+     */
+    evaluateCelCondition(source, options) {
+        if (!source.trim())
+            return true; // no predicate → visible/enabled
+        const bag = this.context.toObject();
+        const rec = bag.record;
+        const record = (rec && typeof rec === 'object' && !Array.isArray(rec))
+            ? rec
+            : bag;
+        if (!options.throwOnError) {
+            // Fast path: one evaluation, fail-soft to visible/enabled (legacy parity).
+            return evalFieldPredicate(source, record, true, undefined, bag);
+        }
+        // Fail-closed callers need to tell a genuine `false` from a fault. The
+        // canonical helper fails soft to the fallback, so a value that tracks the
+        // fallback in BOTH runs means the predicate faulted — then we throw.
+        const asTrue = evalFieldPredicate(source, record, true, undefined, bag);
+        const asFalse = evalFieldPredicate(source, record, false, undefined, bag);
+        if (asTrue !== asFalse) {
+            throw new Error(`CEL predicate failed to evaluate: ${source}`);
+        }
+        return asTrue;
+    }
     /**
      * Update the context with new data
      */

package/dist/evaluator/SafeExpressionParser.js

@@ -298,7 +298,10 @@ export class SafeExpressionParser {
         this.skipWhitespace();
         // eslint-disable-next-line no-constant-condition
         while (true) {
-            let op = null;
+            // Every branch below either assigns `op` or `break`s out of the loop, so
+            // `op` is always set by the time the switch reads it (no null initializer
+            // needed).
+            let op;
             if (this.peek() === '=' && this.peek(1) === '=' && this.peek(2) === '=') {
                 op = '===';
                 this.pos += 3;
@@ -648,7 +651,7 @@ export class SafeExpressionParser {
         // Optional exponent: e+5, E-3
         if (/[eE]/.test(this.source[this.pos] ?? '')) {
             this.pos++; // consume 'e' or 'E'
-            if (/[+\-]/.test(this.source[this.pos] ?? ''))
+            if (/[+-]/.test(this.source[this.pos] ?? ''))
                 this.pos++; // optional sign
             let expDigits = 0;
             while (this.pos < this.source.length && /\d/.test(this.source[this.pos])) {

package/dist/evaluator/optionRules.d.ts

@@ -68,3 +68,25 @@ export declare function resolveVisibleOptions<T extends OptionLike>(options: rea
  * no longer offered). An empty value is always "valid" (nothing to clear).
  */
 export declare function isValueStillOffered(value: unknown, visibleOptions: readonly OptionLike[]): boolean;
+/** The resolved state of a cascading / role-gated option list. */
+export interface CascadingOptions<T extends OptionLike> {
+    /** Offered options after `visibleWhen` filtering. Empty while gated. */
+    options: T[];
+    /** True when a declared `dependsOn` field is empty — the list is gated. */
+    gated: boolean;
+    /** Normalized `dependsOn` field names (drives the "select the parent first" hint). */
+    dependsOnFields: string[];
+}
+/**
+ * Resolve an option field's offered set in one shot: normalize `dependsOn`,
+ * decide whether the list is gated (a controlling field is still empty), and —
+ * unless gated — filter by each option's `visibleWhen`. The single source of
+ * truth behind the option widgets' `useCascadingOptions` hook and the form
+ * renderer's inline pre-filter / cascade-clear, so gating and filtering can
+ * never drift between them (#2715).
+ *
+ * `gated` is true only when there IS a `dependsOn` and one of its fields is
+ * empty; a field with no `dependsOn` is never gated (its options are filtered
+ * purely by `visibleWhen`). Callers format their own hint from `dependsOnFields`.
+ */
+export declare function resolveCascadingOptions<T extends OptionLike>(rawOptions: readonly T[] | undefined | null, record: Record<string, unknown>, dependsOn: DependsOnInput, scope?: Record<string, unknown>): CascadingOptions<T>;

package/dist/evaluator/optionRules.js

@@ -78,3 +78,21 @@ export function isValueStillOffered(value, visibleOptions) {
     }
     return visibleOptions.some((o) => o.value === value);
 }
+/**
+ * Resolve an option field's offered set in one shot: normalize `dependsOn`,
+ * decide whether the list is gated (a controlling field is still empty), and —
+ * unless gated — filter by each option's `visibleWhen`. The single source of
+ * truth behind the option widgets' `useCascadingOptions` hook and the form
+ * renderer's inline pre-filter / cascade-clear, so gating and filtering can
+ * never drift between them (#2715).
+ *
+ * `gated` is true only when there IS a `dependsOn` and one of its fields is
+ * empty; a field with no `dependsOn` is never gated (its options are filtered
+ * purely by `visibleWhen`). Callers format their own hint from `dependsOnFields`.
+ */
+export function resolveCascadingOptions(rawOptions, record, dependsOn, scope) {
+    const dependsOnFields = resolveDependsOnFields(dependsOn);
+    const gated = dependsOnFields.length > 0 && isOptionGroupGated(dependsOn, record);
+    const options = gated ? [] : resolveVisibleOptions(rawOptions, record, scope);
+    return { options, gated, dependsOnFields };
+}

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export * from './registry/WidgetRegistry.js';
 export * from './validation/index.js';
 export * from './builder/schema-builder.js';
 export * from './utils/filter-converter.js';
+export * from './utils/managedBy.js';
 export * from './utils/extract-records.js';
 export * from './utils/expand-fields.js';
 export * from './evaluator/index.js';

package/dist/index.js

@@ -13,6 +13,7 @@ export * from './registry/WidgetRegistry.js';
 export * from './validation/index.js';
 export * from './builder/schema-builder.js';
 export * from './utils/filter-converter.js';
+export * from './utils/managedBy.js';
 export * from './utils/extract-records.js';
 export * from './utils/expand-fields.js';
 export * from './evaluator/index.js';

package/dist/utils/dataset-format.d.ts

@@ -69,6 +69,16 @@ export declare function buildDatasetFieldHelpers(fields: DatasetResultField[] |
     measureField: (name: string) => DatasetResultField | undefined;
     headerLabel: (name: string) => string;
 };
+/**
+ * A half-open date-range drill scope for one time-bucketed dimension (#1752):
+ * the object FIELD to filter and its inclusive `gte` / exclusive `lt` bounds
+ * (the server's `drillRanges` sidecar entry).
+ */
+export interface DatasetDrillRange {
+    field: string;
+    gte: unknown;
+    lt: unknown;
+}
 /**
  * Build the record-list filter for a drilled dataset bucket (ADR-0021 D2).
  *
@@ -79,7 +89,14 @@ export declare function buildDatasetFieldHelpers(fields: DatasetResultField[] |
  * "is empty" filter). The render-time `runtimeFilter` is ANDed in so the drilled
  * list stays within the same slice the aggregate was computed over.
  *
+ * A time-bucketed date dimension (#1752) drills by RANGE, not equality — a
+ * humanized bucket ("2026-Q2") can't be exact-matched, so the server sends a
+ * half-open `[gte, lt)` per date dim in `rawRanges` instead of a raw value.
+ * Each becomes an ObjectQL range operator object (`{ $gte, $lt }`) so the drill
+ * scopes the list to the clicked time bucket instead of every bucket (which the
+ * old date-dim skip degraded to — a superset).
+ *
  * Shared by the dashboard `DatasetWidget` and the report renderer so a drill
  * filters identically (and correctly, including lookups) on both surfaces.
  */
-export declare function buildDatasetDrillFilter(rawRow: Record<string, unknown> | undefined, drillDims: string[], dimensionFields: Record<string, string>, runtimeFilter?: Record<string, unknown>): Record<string, unknown>;
+export declare function buildDatasetDrillFilter(rawRow: Record<string, unknown> | undefined, drillDims: string[], dimensionFields: Record<string, string>, runtimeFilter?: Record<string, unknown>, rawRanges?: Record<string, DatasetDrillRange>): Record<string, unknown>;

package/dist/utils/dataset-format.js

@@ -104,14 +104,27 @@ export function buildDatasetFieldHelpers(fields, object, fieldLabel) {
  * "is empty" filter). The render-time `runtimeFilter` is ANDed in so the drilled
  * list stays within the same slice the aggregate was computed over.
  *
+ * A time-bucketed date dimension (#1752) drills by RANGE, not equality — a
+ * humanized bucket ("2026-Q2") can't be exact-matched, so the server sends a
+ * half-open `[gte, lt)` per date dim in `rawRanges` instead of a raw value.
+ * Each becomes an ObjectQL range operator object (`{ $gte, $lt }`) so the drill
+ * scopes the list to the clicked time bucket instead of every bucket (which the
+ * old date-dim skip degraded to — a superset).
+ *
  * Shared by the dashboard `DatasetWidget` and the report renderer so a drill
  * filters identically (and correctly, including lookups) on both surfaces.
  */
-export function buildDatasetDrillFilter(rawRow, drillDims, dimensionFields, runtimeFilter) {
+export function buildDatasetDrillFilter(rawRow, drillDims, dimensionFields, runtimeFilter, rawRanges) {
     const drillFilter = {};
     for (const d of drillDims) {
         const raw = rawRow?.[d];
         drillFilter[dimensionFields[d]] = raw === '' || raw === undefined ? null : raw;
     }
+    if (rawRanges) {
+        for (const r of Object.values(rawRanges)) {
+            if (r && r.field)
+                drillFilter[r.field] = { $gte: r.gte, $lt: r.lt };
+        }
+    }
     return runtimeFilter ? { ...runtimeFilter, ...drillFilter } : drillFilter;
 }

package/dist/utils/export-filename.js

@@ -8,7 +8,10 @@
  * translated object label (e.g. 合同) → object API name → 'export'.
  */
 /** Windows-reserved + control characters that cannot appear in a filename. */
-const ILLEGAL_FILENAME_CHARS = /[\\\/:*?"<>|\u0000-\u001f]+/g;
+// The control-char range in the class is matched deliberately (illegal in
+// filenames, must be stripped), so no-control-regex is intentionally disabled.
+// eslint-disable-next-line no-control-regex
+const ILLEGAL_FILENAME_CHARS = /[\\/:*?"<>|\u0000-\u001f]+/g;
 /** Longest base we emit — keeps the full name comfortably under OS limits. */
 const MAX_BASE_LENGTH = 80;
 /**

package/dist/utils/managedBy.d.ts

@@ -0,0 +1,101 @@
+/**
+ * managedBy — the single source of truth for interpreting an object's
+ * lifecycle bucket (`ObjectSchema.managedBy`) into CRUD affordances.
+ *
+ * UI-side mirror of the framework's `resolveCrudAffordances()`
+ * (`@objectstack/spec/data/object.zod.ts`, ADR-0103). Lives in `@object-ui/core`
+ * — React-free and reachable by every UI package (app-shell, plugin-detail,
+ * plugin-form, plugin-grid) — so the bucket logic is defined ONCE instead of
+ * hand-mirrored in each. Components ask "should I show New / Import / Edit /
+ * Delete / Export?" and get an answer that tracks the object's lifecycle without
+ * special-casing `sys_*` names.
+ *
+ * The bucket UNION type lives in `@object-ui/types` (`ManagedByBucket`) so the
+ * schema field can reference it; this module re-exports it for convenience.
+ * Only the affordance BOOLEANS live here — all translated copy (badge variants,
+ * empty-state messages) stays in `@object-ui/app-shell`.
+ */
+export type { ManagedByBucket } from '@object-ui/types';
+export interface CrudAffordances {
+    /** Generic "New" button for single-record creation. */
+    create: boolean;
+    /** CSV bulk-import wizard. */
+    import: boolean;
+    /** Inline + form editing of existing rows. */
+    edit: boolean;
+    /** Row-level + bulk delete. */
+    delete: boolean;
+    /** CSV / clipboard export. */
+    exportCsv: boolean;
+    /**
+     * Per-record CEL predicates for the built-in row Edit/Delete actions,
+     * present only when `userActions.edit` / `delete` used the object form
+     * (objectui#2614). Carried through as authored for row renderers to evaluate;
+     * they never affect the object-level booleans above.
+     */
+    editPredicates?: RowCrudPredicates;
+    deletePredicates?: RowCrudPredicates;
+}
+/** Per-record predicates from the #2614 object form of a userActions flag. */
+export interface RowCrudPredicates {
+    visibleWhen?: unknown;
+    disabledWhen?: unknown;
+}
+/** `edit`/`delete` accept a bare boolean or the #2614 object form. */
+export type UserActionOverride = boolean | {
+    enabled?: boolean;
+    visibleWhen?: unknown;
+    disabledWhen?: unknown;
+};
+export interface UserActionsOverride {
+    create?: boolean;
+    import?: boolean;
+    edit?: UserActionOverride;
+    delete?: UserActionOverride;
+    exportCsv?: boolean;
+}
+export interface SchemaLike {
+    managedBy?: string | null;
+    userActions?: UserActionsOverride | null;
+}
+/**
+ * Collapse an `edit`/`delete` override (boolean or #2614 object form) onto
+ * the given bucket default, surfacing any per-record predicates alongside.
+ *
+ * THE single parser for the `userActions.{edit,delete}` override shape — every
+ * UI package (grid row affordances, related-list row predicates, this module's
+ * own `resolveCrudAffordances`) routes through here instead of re-implementing
+ * the boolean/object-form parse locally. `base` is the bucket default an
+ * omitted `enabled` falls back to (callers that only gate on an explicit
+ * opt-out pass `true`; predicate extraction is independent of `base`).
+ */
+export declare function normalizeUserAction(v: UserActionOverride | undefined | null, base: boolean): {
+    enabled: boolean;
+    predicates?: RowCrudPredicates;
+};
+/**
+ * Extract the per-record CEL predicates (#2614 object form) from a
+ * `userActions.edit` / `delete` flag, or `undefined` for a bare boolean /
+ * predicate-less flag. Independent of the object-level enabled verdict — row
+ * renderers use this to gate a built-in action per record. Thin wrapper over
+ * {@link normalizeUserAction} so the parse lives in exactly one place.
+ */
+export declare function userActionPredicates(v: UserActionOverride | undefined | null): RowCrudPredicates | undefined;
+/** Resolve the effective CRUD affordances for an object schema. */
+export declare function resolveCrudAffordances(obj: SchemaLike | null | undefined): CrudAffordances;
+/** True only when a `userActions` flag (bare boolean or #2614 object form) opts the write in. */
+export declare function isWriteOptedIn(v: UserActionOverride | undefined | null): boolean;
+/**
+ * ADR-0103 — a `system`-bucket object that opened ANY write via `userActions`
+ * is admin/user-writable DATA, not an engine-owned monitoring surface. Used to
+ * pick the writable-system badge/empty-state copy.
+ */
+export declare function isSystemWritable(obj: SchemaLike | null | undefined): boolean;
+/**
+ * Whether an object's rows may be edited in place (detail inline-edit / form
+ * fields) — the resolved `edit` affordance. Engine-owned `system` /
+ * `append-only` / `better-auth` objects resolve to `false` unless they opened
+ * `userActions.edit`. (Per-record predicates gate row action buttons, not
+ * object-level editability, so only the resolved boolean matters here.)
+ */
+export declare function isObjectInlineEditable(obj: SchemaLike | null | undefined): boolean;

package/dist/utils/managedBy.js

@@ -0,0 +1,106 @@
+/**
+ * managedBy — the single source of truth for interpreting an object's
+ * lifecycle bucket (`ObjectSchema.managedBy`) into CRUD affordances.
+ *
+ * UI-side mirror of the framework's `resolveCrudAffordances()`
+ * (`@objectstack/spec/data/object.zod.ts`, ADR-0103). Lives in `@object-ui/core`
+ * — React-free and reachable by every UI package (app-shell, plugin-detail,
+ * plugin-form, plugin-grid) — so the bucket logic is defined ONCE instead of
+ * hand-mirrored in each. Components ask "should I show New / Import / Edit /
+ * Delete / Export?" and get an answer that tracks the object's lifecycle without
+ * special-casing `sys_*` names.
+ *
+ * The bucket UNION type lives in `@object-ui/types` (`ManagedByBucket`) so the
+ * schema field can reference it; this module re-exports it for convenience.
+ * Only the affordance BOOLEANS live here — all translated copy (badge variants,
+ * empty-state messages) stays in `@object-ui/app-shell`.
+ */
+const DEFAULTS = {
+    platform: { create: true, import: true, edit: true, delete: true, exportCsv: true },
+    config: { create: true, import: false, edit: true, delete: true, exportCsv: true },
+    system: { create: false, import: false, edit: false, delete: false, exportCsv: true },
+    'engine-owned': { create: false, import: false, edit: false, delete: false, exportCsv: true },
+    'append-only': { create: false, import: false, edit: false, delete: false, exportCsv: true },
+    'better-auth': { create: false, import: false, edit: false, delete: false, exportCsv: true },
+};
+/**
+ * Collapse an `edit`/`delete` override (boolean or #2614 object form) onto
+ * the given bucket default, surfacing any per-record predicates alongside.
+ *
+ * THE single parser for the `userActions.{edit,delete}` override shape — every
+ * UI package (grid row affordances, related-list row predicates, this module's
+ * own `resolveCrudAffordances`) routes through here instead of re-implementing
+ * the boolean/object-form parse locally. `base` is the bucket default an
+ * omitted `enabled` falls back to (callers that only gate on an explicit
+ * opt-out pass `true`; predicate extraction is independent of `base`).
+ */
+export function normalizeUserAction(v, base) {
+    if (v == null)
+        return { enabled: base };
+    if (typeof v === 'boolean')
+        return { enabled: v };
+    const enabled = v.enabled ?? base;
+    if (v.visibleWhen == null && v.disabledWhen == null)
+        return { enabled };
+    const predicates = {};
+    if (v.visibleWhen != null)
+        predicates.visibleWhen = v.visibleWhen;
+    if (v.disabledWhen != null)
+        predicates.disabledWhen = v.disabledWhen;
+    return { enabled, predicates };
+}
+/**
+ * Extract the per-record CEL predicates (#2614 object form) from a
+ * `userActions.edit` / `delete` flag, or `undefined` for a bare boolean /
+ * predicate-less flag. Independent of the object-level enabled verdict — row
+ * renderers use this to gate a built-in action per record. Thin wrapper over
+ * {@link normalizeUserAction} so the parse lives in exactly one place.
+ */
+export function userActionPredicates(v) {
+    return normalizeUserAction(v, false).predicates;
+}
+/** Resolve the effective CRUD affordances for an object schema. */
+export function resolveCrudAffordances(obj) {
+    const bucket = obj?.managedBy ?? 'platform';
+    const base = DEFAULTS[bucket] ?? DEFAULTS.platform;
+    const o = obj?.userActions ?? {};
+    const edit = normalizeUserAction(o.edit, base.edit);
+    const del = normalizeUserAction(o.delete, base.delete);
+    const out = {
+        create: o.create ?? base.create,
+        import: o.import ?? base.import,
+        edit: edit.enabled,
+        delete: del.enabled,
+        exportCsv: o.exportCsv ?? base.exportCsv,
+    };
+    if (edit.predicates)
+        out.editPredicates = edit.predicates;
+    if (del.predicates)
+        out.deletePredicates = del.predicates;
+    return out;
+}
+/** True only when a `userActions` flag (bare boolean or #2614 object form) opts the write in. */
+export function isWriteOptedIn(v) {
+    return v === true || (typeof v === 'object' && v !== null && v.enabled === true);
+}
+/**
+ * ADR-0103 — a `system`-bucket object that opened ANY write via `userActions`
+ * is admin/user-writable DATA, not an engine-owned monitoring surface. Used to
+ * pick the writable-system badge/empty-state copy.
+ */
+export function isSystemWritable(obj) {
+    if (obj?.managedBy !== 'system')
+        return false;
+    const o = obj?.userActions ?? {};
+    return o.create === true || isWriteOptedIn(o.edit) || isWriteOptedIn(o.delete);
+}
+/**
+ * Whether an object's rows may be edited in place (detail inline-edit / form
+ * fields) — the resolved `edit` affordance. Engine-owned `system` /
+ * `append-only` / `better-auth` objects resolve to `false` unless they opened
+ * `userActions.edit`. (Per-record predicates gate row action buttons, not
+ * object-level editability, so only the resolved boolean matters here.)
+ */
+export function isObjectInlineEditable(obj) {
+    return resolveCrudAffordances(obj).edit;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/core",
-  "version": "15.0.0",
+  "version": "16.1.0",
   "type": "module",
   "sideEffects": false,
   "license": "MIT",
@@ -25,11 +25,11 @@
     }
   },
   "dependencies": {
-    "@objectstack/formula": "^14.6.0",
-    "@objectstack/spec": "^14.6.0",
+    "@objectstack/formula": "^16.0.0-rc.0",
+    "@objectstack/spec": "^16.0.0-rc.0",
     "lodash": "^4.18.1",
     "zod": "^4.4.3",
-    "@object-ui/types": "15.0.0"
+    "@object-ui/types": "16.1.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3",