@object-ui/core 16.0.0 → 17.1.0

package/dist/utils/filter-converter.js

@@ -11,6 +11,32 @@
  * @param operator - MongoDB-style operator (e.g., '$gte', '$in')
  * @returns ObjectStack operator or null if not recognized
  */
+/**
+ * A filter operator this layer will not translate.
+ *
+ * Carries the data API's own code and status for the same refusal so a failed
+ * list renders "the filter is malformed" rather than "check your connection" —
+ * `classifyLoadError` reads these, and a bare `Error` classifies as a network
+ * fault, which is the one thing this is definitely not.
+ */
+export class FilterOperatorError extends Error {
+    constructor(message) {
+        super(message);
+        Object.defineProperty(this, "code", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 'INVALID_FILTER'
+        });
+        Object.defineProperty(this, "httpStatus", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 400
+        });
+        this.name = 'FilterOperatorError';
+    }
+}
 export function convertOperatorToAST(operator) {
     // Spec reference: framework/packages/spec/src/data/filter.zod.ts
     // Canonical MongoDB-style keys are camelCase ($startsWith, $endsWith, $notContains).
@@ -69,14 +95,22 @@ export function convertFiltersToAST(filter) {
         if (typeof value === 'object' && !Array.isArray(value)) {
             // Handle operator-based filters
             for (const [operator, operatorValue] of Object.entries(value)) {
-                // Special handling for $regex - warn users about limited support
+                // `$regex` is refused, not downgraded. It used to become `contains`
+                // behind a `console.warn` — but substring matching is a DIFFERENT
+                // QUESTION, not a weaker version of the same one: `$regex: 'a.c'`
+                // matches "abc", `contains 'a.c'` does not, and neither result looks
+                // wrong on screen. A warning is not an error channel; nobody reads the
+                // console of a deployed app.
+                //
+                // The spec has no `$regex` (`FILTER_OPERATORS`, data/filter.zod.ts), so
+                // there is nothing to translate it INTO. Same treatment the unknown
+                // operator below already gets, and for the same stated reason.
                 if (operator === '$regex') {
-                    console.warn(`[ObjectUI] Warning: $regex operator is not fully supported. ` +
-                        `Converting to 'contains' which only supports substring matching, not regex patterns. ` +
+                    throw new FilterOperatorError(`[ObjectUI] The '$regex' filter operator is not supported. It used to be ` +
+                        `converted to 'contains', which matches a literal substring rather than a ` +
+                        `pattern — a different result, not a degraded one. ` +
                         `Field: '${field}', Value: ${JSON.stringify(operatorValue)}. ` +
-                        `Consider using $contains or $startsWith instead.`);
-                    conditions.push([field, 'contains', operatorValue]);
-                    continue;
+                        `Use $contains, $startsWith or $endsWith.`);
                 }
                 // $null / $exists translate based on their boolean value (per spec semantics).
                 // $null: true  → IS NULL    | $null: false  → IS NOT NULL
@@ -95,7 +129,7 @@ export function convertFiltersToAST(filter) {
                 }
                 else {
                     // Unknown operator - throw error to avoid silent failure
-                    throw new Error(`[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. ` +
+                    throw new FilterOperatorError(`[ObjectUI] Unknown filter operator '${operator}' for field '${field}'. ` +
                         `Supported operators: $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $between, ` +
                         `$contains, $notContains, $startsWith, $endsWith, $null, $exists. ` +
                         `If you need exact object matching, use the value directly without an operator.`);
@@ -118,3 +152,56 @@ export function convertFiltersToAST(filter) {
     // Multiple conditions: combine with 'and'
     return ['and', ...conditions];
 }
+/**
+ * Normalize ONE filter source into a single filter node.
+ *
+ * A "source" is whatever a view hands a renderer, and there are three shapes in
+ * circulation, all legitimate:
+ *
+ *   - `[{ field, operator, value }, ...]`  a spec `ViewFilterRule[]`
+ *   - `[['stage', '=', 'won'], ...]`       an AST node / legacy flat array
+ *   - `{ status: 'active' }`               a MongoDB-style object
+ *
+ * The third is the one that kept getting lost. Renderers tested `source.length
+ * > 0` before using it, which is `undefined > 0` for an object — so a
+ * `table.defaultFilters` (declared `Record<string, any>`) was DROPPED and the
+ * view returned every record. Silently: no error, just a wider answer.
+ *
+ * Returns `undefined` for an absent or empty source, so callers can skip
+ * `$filter` rather than sending an empty array.
+ */
+export function toFilterNode(source) {
+    if (source === null || source === undefined)
+        return undefined;
+    if (Array.isArray(source))
+        return source.length > 0 ? source : undefined;
+    if (typeof source !== 'object')
+        return undefined;
+    const obj = source;
+    if (Object.keys(obj).length === 0)
+        return undefined;
+    // MongoDB-style → AST, so it can sit beside the other shapes under one `and`.
+    return convertFiltersToAST(obj);
+}
+/**
+ * Combine filter sources under a single `and`, each as its OWN child.
+ *
+ * Wrapping rather than spreading, on purpose. `['and', ...rules]` looks
+ * equivalent and is not: spreading a `ViewFilterRule[]` puts bare rule OBJECTS
+ * where the AST expects nodes, and the server neither understands nor rejects
+ * that cleanly — `isFilterAST` says no (a 400 since objectstack#4121), while
+ * `parseFilterAST` reads the rule as a Mongo condition and filters on columns
+ * literally named `field` / `operator` / `value`. Spreading is only correct
+ * when the source happens to be an array of nodes, which is why it survived.
+ *
+ * Sources that normalize to nothing are skipped; one surviving source is
+ * returned as-is rather than wrapped in a pointless `and`.
+ */
+export function mergeFilterNodes(...sources) {
+    const nodes = sources.map(toFilterNode).filter((n) => n !== undefined);
+    if (nodes.length === 0)
+        return undefined;
+    if (nodes.length === 1)
+        return nodes[0];
+    return ['and', ...nodes];
+}

package/dist/utils/filter-tokens.d.ts

@@ -0,0 +1,101 @@
+/**
+ * ObjectUI
+ * 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.
+ */
+/**
+ * Session-scoped filter placeholders — the sibling vocabulary to
+ * `{date-macros}`.
+ *
+ * Filter values travel as JSON, so a user-scoped slice cannot call
+ * `currentUser().id` inline; it writes a placeholder that this module expands
+ * immediately before the filter reaches the data source:
+ *
+ *     { owner_id: '{current_user_id}' }
+ *
+ * ## Why this module exists (framework #3574)
+ *
+ * There used to be no shared resolver. Three ad-hoc implementations had grown
+ * up independently — one in `ObjectView` for list views, one in
+ * `ObjectDataPage` for URL filter triples, one in `NavigationRenderer` for
+ * hrefs — and each handled only the shape its own surface happened to use.
+ * Dashboard widgets never got one at all, so `{current_user_id}` in a widget
+ * filter reached SQL as a literal, matched no row, and the widget rendered
+ * `0` with no error in the console or the server log.
+ *
+ * The failure mode is the point: a metric reading `0` is indistinguishable
+ * from a metric that is legitimately zero, so the bug survived review and
+ * shipped. Any *new* surface that resolves placeholders itself will
+ * eventually reproduce it, which is why resolution lives here, once, and
+ * every surface calls {@link resolveFilterPlaceholders}.
+ *
+ * ## Presentation scope, NOT a security boundary
+ *
+ * These tokens scope what a surface *shows*. They do not decide what a caller
+ * is *allowed* to read — that is RLS, enforced server-side against a
+ * different vocabulary rooted at `current_user` (`owner_id = current_user.id`).
+ * Dropping a `{current_user_id}` filter widens a view; it must never widen
+ * access. Never use a context token as an access control.
+ *
+ * ## Contract source
+ *
+ * The canonical vocabulary is published as part of the platform contract at
+ * `@objectstack/spec` → `CONTEXT_TOKENS` / `classifyFilterToken`. It is
+ * mirrored here — exactly as `date-macros.ts` mirrors `DATE_MACRO_TOKENS` —
+ * because the installed `@objectstack/spec` predates that export. Keep the two
+ * in sync; the duplication is temporary until the next coordinated release.
+ */
+/** The complete set of session-scoped filter tokens. */
+export declare const CONTEXT_TOKENS: readonly ["current_user_id", "current_org_id"];
+export type ContextTokenName = (typeof CONTEXT_TOKENS)[number];
+/** Session values a filter placeholder can resolve against. */
+export interface FilterTokenScope {
+    /** The signed-in user's id. */
+    currentUserId?: string | null;
+    /** The active organization id. */
+    currentOrgId?: string | null;
+    /**
+     * Called when a placeholder cannot be resolved — either a recognised token
+     * with no value in scope (signed out), or a near-miss spelling that resolves
+     * in no vocabulary. Defaults to a `console.warn`; pass `null` to silence.
+     */
+    onUnresolved?: ((message: string) => void) | null;
+}
+/**
+ * Expand `{current_user_id}` / `{current_org_id}` inside a filter.
+ *
+ * Walks arrays and plain objects recursively, which is what makes one
+ * resolver cover both platform filter shapes: the MongoDB-style object a
+ * dashboard widget carries (`{ owner_id: '{current_user_id}' }`) and the
+ * condition/triple arrays a list view carries (`[{ field, operator, value }]`
+ * / `[['owner','=','…']]`). The predecessor helper in `ObjectView` bailed on
+ * non-arrays (`if (!Array.isArray(filter)) return filter`), which is why
+ * lifting it into the dashboard would have been a silent no-op.
+ *
+ * Only whole-string placeholders are substituted — an id is an opaque value,
+ * so embedding it in a larger string (`'user-{current_user_id}'`) is never
+ * what an author means, and substituting there would silently produce a value
+ * that matches nothing. Unknown tokens are passed through untouched so that
+ * date macros and nav-only `AppContextSelector` ids survive this pass.
+ *
+ * An unresolvable *known* token is deliberately left as-is rather than
+ * dropped: leaving it yields an empty result, whereas dropping the clause
+ * would widen the result set — and a filter that silently widens is far worse
+ * than one that silently narrows.
+ */
+export declare function resolveContextTokens<T = any>(filter: T, scope?: FilterTokenScope): T;
+/**
+ * Resolve **every** placeholder vocabulary a filter value understands — date
+ * macros and context tokens — in one call.
+ *
+ * This is the function surfaces should call. Calling only one of the two
+ * resolvers is the defect behind framework #3574: dashboard widgets called
+ * `resolveDateMacros` alone, so `{today}` worked and `{current_user_id}`
+ * silently did not.
+ *
+ * Order is irrelevant (the vocabularies are disjoint) but fixed here so
+ * behaviour is identical everywhere.
+ */
+export declare function resolveFilterPlaceholders<T = any>(filter: T, scope?: FilterTokenScope, now?: Date): T;

package/dist/utils/filter-tokens.js

@@ -0,0 +1,173 @@
+/**
+ * ObjectUI
+ * 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.
+ */
+import { resolveDateMacros } from './date-macros.js';
+/**
+ * Session-scoped filter placeholders — the sibling vocabulary to
+ * `{date-macros}`.
+ *
+ * Filter values travel as JSON, so a user-scoped slice cannot call
+ * `currentUser().id` inline; it writes a placeholder that this module expands
+ * immediately before the filter reaches the data source:
+ *
+ *     { owner_id: '{current_user_id}' }
+ *
+ * ## Why this module exists (framework #3574)
+ *
+ * There used to be no shared resolver. Three ad-hoc implementations had grown
+ * up independently — one in `ObjectView` for list views, one in
+ * `ObjectDataPage` for URL filter triples, one in `NavigationRenderer` for
+ * hrefs — and each handled only the shape its own surface happened to use.
+ * Dashboard widgets never got one at all, so `{current_user_id}` in a widget
+ * filter reached SQL as a literal, matched no row, and the widget rendered
+ * `0` with no error in the console or the server log.
+ *
+ * The failure mode is the point: a metric reading `0` is indistinguishable
+ * from a metric that is legitimately zero, so the bug survived review and
+ * shipped. Any *new* surface that resolves placeholders itself will
+ * eventually reproduce it, which is why resolution lives here, once, and
+ * every surface calls {@link resolveFilterPlaceholders}.
+ *
+ * ## Presentation scope, NOT a security boundary
+ *
+ * These tokens scope what a surface *shows*. They do not decide what a caller
+ * is *allowed* to read — that is RLS, enforced server-side against a
+ * different vocabulary rooted at `current_user` (`owner_id = current_user.id`).
+ * Dropping a `{current_user_id}` filter widens a view; it must never widen
+ * access. Never use a context token as an access control.
+ *
+ * ## Contract source
+ *
+ * The canonical vocabulary is published as part of the platform contract at
+ * `@objectstack/spec` → `CONTEXT_TOKENS` / `classifyFilterToken`. It is
+ * mirrored here — exactly as `date-macros.ts` mirrors `DATE_MACRO_TOKENS` —
+ * because the installed `@objectstack/spec` predates that export. Keep the two
+ * in sync; the duplication is temporary until the next coordinated release.
+ */
+/** The complete set of session-scoped filter tokens. */
+export const CONTEXT_TOKENS = ['current_user_id', 'current_org_id'];
+/**
+ * Near-miss spellings → the token the author meant.
+ *
+ * Every entry is a real authoring mistake, and each is a correct spelling
+ * *somewhere else* in the platform, which is exactly why authors reach for it:
+ * `current_user` is the RLS expression root, `{user_id}` is valid
+ * `titleFormat` field interpolation, `organization_id` is a real column name.
+ *
+ * Mirrors `CONTEXT_TOKEN_SUGGESTIONS` in `@objectstack/spec`. Used only to
+ * make the runtime warning actionable; the authoring-time gate
+ * (`validateFilterTokens` in `@objectstack/lint`) is what actually prevents
+ * these from shipping.
+ */
+const CONTEXT_TOKEN_SUGGESTIONS = {
+    current_user: 'current_user_id',
+    current_user_email: 'current_user_id',
+    user_id: 'current_user_id',
+    userid: 'current_user_id',
+    me: 'current_user_id',
+    current_organization_id: 'current_org_id',
+    org_id: 'current_org_id',
+    organization_id: 'current_org_id',
+    current_tenant_id: 'current_org_id',
+};
+/** Whole-string placeholder: `{token}` or `${token}`, anchored. */
+const WHOLE_TOKEN_RE = /^\$?\{([a-zA-Z0-9_]+)\}$/;
+function isContextToken(token) {
+    return CONTEXT_TOKENS.includes(token);
+}
+/**
+ * Expand `{current_user_id}` / `{current_org_id}` inside a filter.
+ *
+ * Walks arrays and plain objects recursively, which is what makes one
+ * resolver cover both platform filter shapes: the MongoDB-style object a
+ * dashboard widget carries (`{ owner_id: '{current_user_id}' }`) and the
+ * condition/triple arrays a list view carries (`[{ field, operator, value }]`
+ * / `[['owner','=','…']]`). The predecessor helper in `ObjectView` bailed on
+ * non-arrays (`if (!Array.isArray(filter)) return filter`), which is why
+ * lifting it into the dashboard would have been a silent no-op.
+ *
+ * Only whole-string placeholders are substituted — an id is an opaque value,
+ * so embedding it in a larger string (`'user-{current_user_id}'`) is never
+ * what an author means, and substituting there would silently produce a value
+ * that matches nothing. Unknown tokens are passed through untouched so that
+ * date macros and nav-only `AppContextSelector` ids survive this pass.
+ *
+ * An unresolvable *known* token is deliberately left as-is rather than
+ * dropped: leaving it yields an empty result, whereas dropping the clause
+ * would widen the result set — and a filter that silently widens is far worse
+ * than one that silently narrows.
+ */
+export function resolveContextTokens(filter, scope = {}) {
+    if (filter == null)
+        return filter;
+    const { currentUserId, currentOrgId } = scope;
+    const warn = scope.onUnresolved === null
+        ? () => { }
+        : scope.onUnresolved ??
+            ((message) => {
+                // eslint-disable-next-line no-console
+                console.warn(`[object-ui] ${message}`);
+            });
+    const values = {
+        current_user_id: currentUserId,
+        current_org_id: currentOrgId,
+    };
+    const walk = (value) => {
+        if (value == null)
+            return value;
+        if (typeof value === 'string') {
+            const m = value.match(WHOLE_TOKEN_RE);
+            if (!m)
+                return value;
+            const token = m[1];
+            if (isContextToken(token)) {
+                const resolved = values[token];
+                if (resolved != null && resolved !== '')
+                    return resolved;
+                warn(`Filter placeholder "{${token}}" could not be resolved — no ${token === 'current_user_id' ? 'signed-in user' : 'active organization'} in scope. The filter will match no records.`);
+                return value;
+            }
+            // Not ours. Warn only for near-misses, which resolve in no vocabulary
+            // at all and would otherwise fail silently; genuine date macros and
+            // nav context-selector ids must pass through quietly.
+            const suggestion = CONTEXT_TOKEN_SUGGESTIONS[token.toLowerCase()];
+            if (suggestion) {
+                warn(`Filter placeholder "{${token}}" is not a recognised token — did you mean ` +
+                    `"{${suggestion}}"? It is sent to the server as a literal string and will ` +
+                    `match no records.`);
+            }
+            return value;
+        }
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (typeof value === 'object') {
+            const out = {};
+            for (const k of Object.keys(value))
+                out[k] = walk(value[k]);
+            return out;
+        }
+        return value;
+    };
+    return walk(filter);
+}
+/**
+ * Resolve **every** placeholder vocabulary a filter value understands — date
+ * macros and context tokens — in one call.
+ *
+ * This is the function surfaces should call. Calling only one of the two
+ * resolvers is the defect behind framework #3574: dashboard widgets called
+ * `resolveDateMacros` alone, so `{today}` worked and `{current_user_id}`
+ * silently did not.
+ *
+ * Order is irrelevant (the vocabularies are disjoint) but fixed here so
+ * behaviour is identical everywhere.
+ */
+export function resolveFilterPlaceholders(filter, scope = {}, now = new Date()) {
+    if (filter == null)
+        return filter;
+    return resolveContextTokens(resolveDateMacros(filter, now), scope);
+}

package/dist/utils/managedBy.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ *
+ * @param obj The object schema (managedBy bucket + userActions overrides).
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (from `/me/permissions` `apiOperations`, #3391). When
+ *   provided, each affordance bit is ANDed with the corresponding API operation
+ *   (create/import→create/import, edit→update, delete→delete, exportCsv→export),
+ *   so the UI never shows a button the server would 405. Passing `undefined`
+ *   (old backend / no effective set) leaves the affordances untouched —
+ *   backward-compatible. An empty array means "expose nothing" → all bits off.
+ */
+export declare function resolveCrudAffordances(obj: SchemaLike | null | undefined, effectiveApiOperations?: readonly string[] | null): 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.)
+ *
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (`/me/permissions` `apiOperations`, #3391/#3546). When
+ *   provided, inline-edit is additionally ANDed with the server allowing
+ *   `update`, so a record page never offers double-click/pencil editing the
+ *   server would 405. `undefined` (old backend / unrestricted) leaves the
+ *   bucket affordance untouched.
+ */
+export declare function isObjectInlineEditable(obj: SchemaLike | null | undefined, effectiveApiOperations?: readonly string[] | null): boolean;

package/dist/utils/managedBy.js

@@ -0,0 +1,147 @@
+/**
+ * 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;
+}
+/**
+ * The affordance-bit → server API-operation mapping used to intersect the
+ * UI-intent affordances with the server's effective API operation set (#3391).
+ * This is the objectui end of the framework's `API_METHOD_DERIVATION` contract:
+ * the button predicate is `affordance(op) ∧ effective.api(op)`.
+ */
+const AFFORDANCE_TO_API_OPERATION = {
+    create: 'create',
+    import: 'import',
+    edit: 'update',
+    delete: 'delete',
+    exportCsv: 'export',
+};
+/**
+ * Resolve the effective CRUD affordances for an object schema.
+ *
+ * @param obj The object schema (managedBy bucket + userActions overrides).
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (from `/me/permissions` `apiOperations`, #3391). When
+ *   provided, each affordance bit is ANDed with the corresponding API operation
+ *   (create/import→create/import, edit→update, delete→delete, exportCsv→export),
+ *   so the UI never shows a button the server would 405. Passing `undefined`
+ *   (old backend / no effective set) leaves the affordances untouched —
+ *   backward-compatible. An empty array means "expose nothing" → all bits off.
+ */
+export function resolveCrudAffordances(obj, effectiveApiOperations) {
+    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;
+    // [#3391] Intersect with the server's effective API operations when present.
+    // The frontend consumes the effective set the server hands down; it never
+    // reads the raw `apiMethods` nor re-derives.
+    if (Array.isArray(effectiveApiOperations)) {
+        const eff = new Set(effectiveApiOperations);
+        for (const [bit, op] of Object.entries(AFFORDANCE_TO_API_OPERATION)) {
+            if (out[bit] && !eff.has(op))
+                out[bit] = false;
+        }
+    }
+    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.)
+ *
+ * @param effectiveApiOperations OPTIONAL server-resolved effective API operation
+ *   set for this object (`/me/permissions` `apiOperations`, #3391/#3546). When
+ *   provided, inline-edit is additionally ANDed with the server allowing
+ *   `update`, so a record page never offers double-click/pencil editing the
+ *   server would 405. `undefined` (old backend / unrestricted) leaves the
+ *   bucket affordance untouched.
+ */
+export function isObjectInlineEditable(obj, effectiveApiOperations) {
+    return resolveCrudAffordances(obj, effectiveApiOperations).edit;
+}