@object-ui/core 17.3.0 → 17.5.0

package/dist/data-scope/element-data-source.js

@@ -0,0 +1,216 @@
+/**
+ * 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.
+ */
+/**
+ * `@object-ui/core` — ElementDataSource resolution (objectstack#5576).
+ *
+ * `PageComponentSchema.dataSource` (the spec's `ElementDataSourceSchema`) is the
+ * per-element data binding a page component uses to query a different object
+ * than the page's own context:
+ *
+ * ```json
+ * { "object": "account", "view": "hot", "filter": { … }, "sort": [ … ], "limit": 20 }
+ * ```
+ *
+ * This module owns the two pure halves of consuming it — telling the METADATA
+ * apart from a runtime data-source adapter, and composing a named saved view
+ * with the binding's own keys. Both are needed in two places (the render path in
+ * `@object-ui/plugin-list`, and `ViewDataProvider.resolveElementDataSource`), so
+ * they live here rather than being written twice.
+ *
+ * ## Composition semantics
+ *
+ * The spec's own `describe()` text settles the one case that could go either
+ * way. `filter` is documented as "**Additional** filter criteria" — additional
+ * to what the named view already restricts — so a view filter and a binding
+ * filter COMBINE under `and`; the binding can only narrow the view, never widen
+ * it. That is also the safe direction for AI-authored metadata: a typo in a
+ * per-element filter cannot silently expose rows the saved view excluded.
+ *
+ * Nothing else in the binding is described as additional, and the remaining keys
+ * are single-valued (one ordering, one cap), so for those the rule is **the view
+ * provides the baseline and an explicit key overrides it**:
+ *
+ * | key        | source                                  | rule                        |
+ * |------------|-----------------------------------------|-----------------------------|
+ * | `object`   | binding (required)                      | binding wins                |
+ * | `columns`  | view only — the binding has no such key | view                        |
+ * | `filter`   | view + binding                          | AND-combined ("additional") |
+ * | `sort`     | view or binding                         | binding overrides view      |
+ * | `limit`    | view (`pagination.pageSize`) or binding | binding overrides view      |
+ * | `viewType` | view only                               | view                        |
+ *
+ * A lone `filter` — only the view has one, or only the binding does — is passed
+ * through in the shape it was stored in; only the two-source case is lowered to
+ * an ObjectQL AST, because that is what combining requires.
+ *
+ * `viewType` rides along because `list-view` IS the multi-kind view container
+ * (its registry `inputs` enumerate grid/kanban/gallery/…): naming a saved kanban
+ * view and rendering a grid would be a silently wrong answer.
+ */
+import { mergeFilterNodes } from '../utils/filter-converter.js';
+import { resolveViewId } from '../utils/resolve-view-id.js';
+const isPlainObject = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/**
+ * Is this value the spec's `dataSource` METADATA, rather than a runtime
+ * data-source adapter?
+ *
+ * This guard exists because the two collide by name and the collision was live:
+ * `SchemaRenderer` spreads every non-metadata schema key onto the component as a
+ * React prop, so a spec-compliant `dataSource: { object, view }` on a page
+ * component landed on `ListView`'s `dataSource` PROP — which is the injected
+ * adapter — and shadowed it. The first `dataSource.find(…)` then threw
+ * `dataSource.find is not a function`, which the list reported as
+ * "Couldn't load records": writing the binding the spec documents BROKE the
+ * component (objectstack#5576).
+ *
+ * The test is positive on the metadata rather than negative on the adapter: a
+ * binding is a plain object with a non-empty string `object` and no `find`
+ * method. An adapter never has a string `object`; metadata never has `find`.
+ */
+export function isElementDataSourceConfig(value) {
+    if (!isPlainObject(value))
+        return false;
+    if (typeof value.find === 'function')
+        return false;
+    const object = value.object;
+    return typeof object === 'string' && object.length > 0;
+}
+/**
+ * Flatten every place saved views for one object can live into `id → config`.
+ *
+ * Two sources are real and both are read, in the order app-shell's `ObjectView`
+ * reads them: the object definition's embedded `listViews` / `list_views` map
+ * (metadata-defined) and the metadata overlay rows an adapter returns from
+ * `listViews()` (user-defined). Later sources win, so a saved view shadows a
+ * metadata view of the same id — the same precedence `ObjectView` applies when
+ * it dedups its tab list.
+ *
+ * Accepts a record keyed by view id or an array of view configs (overlay rows
+ * are an array and carry their identity in `name`, falling back to `id`).
+ */
+export function collectSavedViews(...sources) {
+    const out = {};
+    for (const source of sources) {
+        if (Array.isArray(source)) {
+            for (const entry of source) {
+                if (!isPlainObject(entry))
+                    continue;
+                const id = entry.name ?? entry.id;
+                if (typeof id === 'string' && id)
+                    out[id] = entry;
+            }
+        }
+        else if (isPlainObject(source)) {
+            for (const [id, entry] of Object.entries(source)) {
+                if (isPlainObject(entry))
+                    out[id] = entry;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Find the saved view a `dataSource.view` name refers to.
+ *
+ * Name matching is {@link resolveViewId}'s — the same short/qualified tolerance
+ * the object page applies to a URL-requested view — so a name that works in one
+ * surface works in the other. Returns `undefined` when nothing matches; the
+ * caller must REPORT that rather than fall back to the object's default view.
+ * Silently widening a named view to "all records" is the failure mode this whole
+ * binding exists to remove.
+ */
+export function resolveSavedView(views, requested, object) {
+    const id = resolveViewId(requested, Object.keys(views), object);
+    return id === undefined ? undefined : views[id];
+}
+/** Read a saved view's row cap — `pagination.pageSize`, or a flat `limit`. */
+function savedViewLimit(view) {
+    if (!view)
+        return undefined;
+    const pagination = view.pagination;
+    if (isPlainObject(pagination) && typeof pagination.pageSize === 'number') {
+        return pagination.pageSize;
+    }
+    return typeof view.limit === 'number' ? view.limit : undefined;
+}
+/**
+ * Read a saved view's render kind. `type` is the spec's key (and what
+ * `ObjectView` reads); `viewType` is objectui's legacy spelling, folded by
+ * `normalizeListViewSchema` downstream but accepted here so a view stored either
+ * way resolves to the same kind.
+ */
+function savedViewType(view) {
+    if (!view)
+        return undefined;
+    const kind = view.type ?? view.viewType;
+    return typeof kind === 'string' && kind ? kind : undefined;
+}
+/** Read a saved view's column list — canonical `columns`, legacy `fields`. */
+function savedViewColumns(view) {
+    if (!view)
+        return undefined;
+    if (Array.isArray(view.columns))
+        return view.columns;
+    if (Array.isArray(view.fields))
+        return view.fields;
+    return undefined;
+}
+/**
+ * Compose an `ElementDataSource` binding with the saved view it names.
+ *
+ * Pure — the caller resolves the view (see {@link resolveSavedView}) and owns
+ * the "named a view that does not exist" decision. Passing `undefined` /`null`
+ * for `view` composes a binding with no view, which is exactly the pre-#5576
+ * behaviour for the other four keys.
+ *
+ * See the module doc for the per-key rule table; `filter` is the only key that
+ * combines rather than overrides, because the spec describes the binding's
+ * filter as *additional*.
+ */
+export function composeElementDataSource(config, view) {
+    const composed = { object: config.object };
+    const columns = savedViewColumns(view);
+    if (columns !== undefined)
+        composed.columns = columns;
+    // "Additional filter criteria" (spec) — the view restricts, the binding
+    // restricts further, so two filters COMBINE under `and` via the repo's single
+    // combiner. A lone source passes through VERBATIM: lowering a stored filter to
+    // an ObjectQL AST belongs at the last hop before the wire and nowhere earlier
+    // (see `toFilterNode`'s doc on why), and every consumer of this result hands
+    // the value to that hop anyway. Combining is the one case that cannot preserve
+    // the input shape — putting two sources under one `and` requires AST — and
+    // `mergeFilterNodes` is the sanctioned place for it.
+    const viewFilter = view?.filter;
+    const filter = viewFilter !== undefined && config.filter !== undefined
+        ? mergeFilterNodes(viewFilter, config.filter)
+        : (config.filter ?? viewFilter);
+    if (filter !== undefined)
+        composed.filter = filter;
+    const sort = config.sort ?? view?.sort;
+    if (sort !== undefined)
+        composed.sort = sort;
+    const limit = config.limit ?? savedViewLimit(view);
+    if (limit !== undefined)
+        composed.limit = limit;
+    const viewType = savedViewType(view);
+    if (viewType !== undefined)
+        composed.viewType = viewType;
+    return composed;
+}
+/**
+ * The message shown when `dataSource.view` names a view the object does not
+ * have. Built here so the render path and `ViewDataProvider` report the same
+ * defect the same way, and so the known-view list (the thing that actually gets
+ * an author unstuck) is never omitted by one caller.
+ */
+export function elementDataSourceViewNotFoundMessage(object, view, knownViews) {
+    const known = knownViews.length
+        ? `Known views: ${[...knownViews].sort().join(', ')}.`
+        : 'This object has no saved views.';
+    return `dataSource.view "${view}" was not found on object "${object}". ${known}`;
+}

package/dist/data-scope/index.d.ts

@@ -8,4 +8,5 @@
  * @packageDocumentation
  */
 export { DataScopeManager, defaultDataScopeManager, type RowLevelFilter, type DataScopeConfig, } from './DataScopeManager.js';
-export { ViewDataProvider, type ViewDataConfig, type ElementDataSourceConfig, type DataFetcher, type ResolvedData, } from './ViewDataProvider.js';
+export { ViewDataProvider, type ViewDataConfig, type DataFetcher, type ResolvedData, } from './ViewDataProvider.js';
+export { collectSavedViews, composeElementDataSource, elementDataSourceViewNotFoundMessage, isElementDataSourceConfig, resolveSavedView, type ComposedElementDataSource, type ElementDataSourceConfig, type ElementDataSourceSort, type ElementSavedView, } from './element-data-source.js';

package/dist/data-scope/index.js

@@ -9,3 +9,4 @@
  */
 export { DataScopeManager, defaultDataScopeManager, } from './DataScopeManager.js';
 export { ViewDataProvider, } from './ViewDataProvider.js';
+export { collectSavedViews, composeElementDataSource, elementDataSourceViewNotFoundMessage, isElementDataSourceConfig, resolveSavedView, } from './element-data-source.js';

package/dist/evaluator/declaredPredicate.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 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.
+ */
+/**
+ * Is a predicate gate DECLARED on this value — i.e. after normalization, is
+ * there still a CONDITION for {@link ExpressionEvaluator.evaluateCondition} to
+ * reach a verdict on? (objectui#3850's ruling, key-neutral: `visible` /
+ * `hidden` / `enabled` / `disabled` / `condition` all ask it.)
+ *
+ * This is the ONE definition of that question in the repo, and it lives here —
+ * one layer under every consumer, beside {@link toPredicateInput}, whose answer
+ * it is derived from. It has to be asked separately from the verdict because
+ * `evaluateCondition` documents and implements exactly one default for "there
+ * is nothing here to evaluate": it returns `true`, meaning *visible/enabled*.
+ * That default is right on `visible` / `enabled` and INVERTED on `disabled`,
+ * where `true` means "greyed out" — so a gate that hands an empty predicate to
+ * the evaluator gets the strongest possible "yes, disable it" for a value the
+ * metadata never used to say anything. Truthiness cannot answer it either, and
+ * asking it that way was objectui#3812: `if (action.visible && !isVisible)`
+ * read `visible: false` — the most explicit "never show this" an author can
+ * write — as *ungated*, and rendered the action for everyone.
+ *
+ * ## What counts as "nothing to evaluate"
+ *
+ * Exactly the shapes {@link toPredicateInput} folds to `undefined`, plus the two
+ * BLANK spellings it wraps or passes through instead of folding:
+ *
+ *   - `null` / `undefined` — no key at all.
+ *   - `''` — an empty predicate (objectui#3492 / objectui#3842).
+ *   - blank predicate TEXT, in either spelling — a whitespace-only string
+ *     (`'   '`, which the normalizer wraps into `'${   }'`) and an envelope whose
+ *     `source` is whitespace-only (`{ dialect: 'cel', source: '   ' }`, which the
+ *     normalizer passes through because it only folds a `source` of `''`).
+ *     Neither can be read off the normalizer's answer, so both are named here —
+ *     see {@link isBlankPredicateText} for why this is the layer that says it.
+ *     Core's other predicate entries already treat both as blank:
+ *     `evaluateCondition` (`if (!trimmed) return true`), `evaluateCelCondition`
+ *     (`if (!source.trim()) return true`) and `evalRowPredicate`
+ *     (`evaluator/listConditional.ts`, `if (!source.trim())`).
+ *   - `{ dialect, source: '' }` — the empty ENVELOPE. This is not an exotic
+ *     spelling: `@objectstack/spec`'s `ExpressionInputSchema` normalizes every
+ *     authored predicate into an envelope, so "author left the predicate empty"
+ *     compiles to exactly this, which makes it the likeliest empty shape in real
+ *     metadata (objectui#3850).
+ *   - anything that is not a predicate at all (`0`, `{}`, an array): a value the
+ *     evaluator cannot read must not be the reason a control is disabled or an
+ *     action refuses to run. Fail-open on junk, which is the posture
+ *     `ActionRunner` already committed to (`catch { isDisabled = false }`).
+ *
+ * A declared-and-`false` gate is DECLARED (`toPredicateInput` returns the
+ * boolean unchanged): `disabled: false` / `visible: false` are verdicts, and
+ * routing them to the evaluator — which short-circuits booleans — is the point
+ * of asking "declared?" rather than "truthy?".
+ *
+ * ## Why blankness is decided HERE and not in the normalizer (objectui#3960)
+ *
+ * The blank-`source` envelope arrived one release late: objectui#3850's ruling
+ * enumerated three empty spellings, `toPredicateInput` folds a `source` of `''`
+ * and does not trim, so `{ dialect: 'cel', source: '   ' }` stayed "declared"
+ * while core's own CEL entry called that exact value "no predicate" — `disabled`
+ * greyed out and `ActionRunner` refused to execute for a predicate that says
+ * nothing (objectui#3960). The asymmetry was that this definition trimmed the
+ * STRING spelling of a blank predicate and not the ENVELOPE spelling of the same
+ * blank.
+ *
+ * Fixing it at the normalizer instead (`if (!src.trim()) return undefined`) would
+ * have aligned every `evaluateCondition(toPredicateInput(x))` consumer at once,
+ * and that is precisely why it is the wider, wrong lever: it changes what
+ * normalization MEANS, which is a shape question ("what does the evaluator
+ * accept"), to answer a declaredness question ("is there a condition"). Those are
+ * different concepts on purpose — a blank `source` is a shape the evaluator
+ * accepts and answers `true` for, by its own documented rule. The blast radius is
+ * the concrete difference: at the normalizer, a NON-cel blank envelope
+ * (`{ source: '   ' }` → `'${   }'` → falsy) flips verdict for every
+ * `useCondition(toPredicateInput(…))` call site including the container-level
+ * `visible` reads in `action-bar` / `action-group` / `action-menu` /
+ * `RelatedList` / `record-alert`, none of which ask this question at all; here it
+ * flips only for the consumers that DO ask it, and only on the inverted-polarity
+ * keys where "declared" is what turns a control off.
+ *
+ * ## Why the callers still evaluate the RAW value
+ *
+ * Every consumer normalizes to decide DECLAREDNESS and then evaluates whatever
+ * it was given, `evaluateCondition(raw)` or `evaluateCondition(toPredicateInput(
+ * raw))` as it did before. Both agree since objectui#3871 made the normalizer
+ * idempotent for an already-`${…}` string; before that they did not, and a
+ * template-spelled predicate normalized twice came back as a constant. Nothing
+ * here changes a verdict for a value that HAS one — this gate only decides
+ * whether there is one to reach.
+ *
+ * ## Scope history (objectui#3850)
+ *
+ * The question used to be answered three times with three different scopes: the
+ * renderer-side `hasDeclaredVisibilityGate` (`!= null && !== ''`, so every
+ * object counted — including the empty envelope), `SchemaRenderer`'s inline
+ * `!== undefined` (wider still: `disabled: null` greyed the control out,
+ * objectui#3862), and `ActionRunner`'s module-private helper (this scope, which
+ * arrived first with objectui#3848 and is what the ruling adopted). One
+ * definition with one scope replaces all three:
+ * `components/renderers/action/visibility-gate.ts` re-exports this function
+ * under its historic name `hasDeclaredVisibilityGate` (the five member-action
+ * renderer call sites are unchanged), `SchemaRenderer`'s `disabled` /
+ * `disabledOn` chain reads it, and `ActionRunner`'s two gates read it instead of
+ * a private twin.
+ *
+ * Two more consumers joined afterwards, and with them the last two places that
+ * answered this question with a range of their own:
+ * `SchemaRenderer`'s `hidden` / `hiddenOn` legs, whose verdict is NOT negated so
+ * an empty predicate made the node VANISH (objectui#3955), and
+ * `ActionEngine.getActionsForLocation`'s `visible` filter, which folded some
+ * empty spellings by hand and coerced the rest with `Boolean(raw)`, so
+ * `visible: 0` hid an action the renderers showed (objectui#3957). Nothing in the
+ * repo now asks "is a gate declared?" anywhere but here.
+ */
+export declare function hasDeclaredPredicate(value: unknown): boolean;

package/dist/evaluator/declaredPredicate.js

@@ -0,0 +1,152 @@
+/**
+ * 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 { toPredicateInput } from './predicateInput';
+/**
+ * Is the predicate TEXT blank — in EITHER spelling? (objectui#3960)
+ *
+ * `'   '` and `{ dialect: 'cel', source: '   ' }` are the same author mistake
+ * written two ways, and {@link toPredicateInput} folds neither: it wraps a
+ * whitespace-only string into `'${   }'`, and it only folds an envelope whose
+ * `source` is exactly `''`. So blankness cannot be derived from the normalizer's
+ * answer and has to be stated once, here, for both spellings — trimming one and
+ * not the other is the asymmetry objectui#3960 measured (`disabled` greyed out,
+ * `ActionRunner` refused to execute, for a predicate that says nothing).
+ *
+ * This is not a fourth dialect of "empty": it is the SAME rule core's evaluation
+ * entries already apply on the value side — `evaluateCondition`
+ * (`if (!trimmed) return true`), `evaluateCelCondition` (`if (!source.trim())
+ * return true`), `evalRowPredicate` (`listConditional.ts`) — brought to the one
+ * place that answers "is there a condition at all?", so the two halves cannot
+ * disagree about the same blank.
+ */
+function isBlankPredicateText(value) {
+    if (typeof value === 'string')
+        return value.trim() === '';
+    if (value !== null && typeof value === 'object') {
+        const source = value.source;
+        if (typeof source === 'string')
+            return source.trim() === '';
+    }
+    return false;
+}
+/**
+ * Is a predicate gate DECLARED on this value — i.e. after normalization, is
+ * there still a CONDITION for {@link ExpressionEvaluator.evaluateCondition} to
+ * reach a verdict on? (objectui#3850's ruling, key-neutral: `visible` /
+ * `hidden` / `enabled` / `disabled` / `condition` all ask it.)
+ *
+ * This is the ONE definition of that question in the repo, and it lives here —
+ * one layer under every consumer, beside {@link toPredicateInput}, whose answer
+ * it is derived from. It has to be asked separately from the verdict because
+ * `evaluateCondition` documents and implements exactly one default for "there
+ * is nothing here to evaluate": it returns `true`, meaning *visible/enabled*.
+ * That default is right on `visible` / `enabled` and INVERTED on `disabled`,
+ * where `true` means "greyed out" — so a gate that hands an empty predicate to
+ * the evaluator gets the strongest possible "yes, disable it" for a value the
+ * metadata never used to say anything. Truthiness cannot answer it either, and
+ * asking it that way was objectui#3812: `if (action.visible && !isVisible)`
+ * read `visible: false` — the most explicit "never show this" an author can
+ * write — as *ungated*, and rendered the action for everyone.
+ *
+ * ## What counts as "nothing to evaluate"
+ *
+ * Exactly the shapes {@link toPredicateInput} folds to `undefined`, plus the two
+ * BLANK spellings it wraps or passes through instead of folding:
+ *
+ *   - `null` / `undefined` — no key at all.
+ *   - `''` — an empty predicate (objectui#3492 / objectui#3842).
+ *   - blank predicate TEXT, in either spelling — a whitespace-only string
+ *     (`'   '`, which the normalizer wraps into `'${   }'`) and an envelope whose
+ *     `source` is whitespace-only (`{ dialect: 'cel', source: '   ' }`, which the
+ *     normalizer passes through because it only folds a `source` of `''`).
+ *     Neither can be read off the normalizer's answer, so both are named here —
+ *     see {@link isBlankPredicateText} for why this is the layer that says it.
+ *     Core's other predicate entries already treat both as blank:
+ *     `evaluateCondition` (`if (!trimmed) return true`), `evaluateCelCondition`
+ *     (`if (!source.trim()) return true`) and `evalRowPredicate`
+ *     (`evaluator/listConditional.ts`, `if (!source.trim())`).
+ *   - `{ dialect, source: '' }` — the empty ENVELOPE. This is not an exotic
+ *     spelling: `@objectstack/spec`'s `ExpressionInputSchema` normalizes every
+ *     authored predicate into an envelope, so "author left the predicate empty"
+ *     compiles to exactly this, which makes it the likeliest empty shape in real
+ *     metadata (objectui#3850).
+ *   - anything that is not a predicate at all (`0`, `{}`, an array): a value the
+ *     evaluator cannot read must not be the reason a control is disabled or an
+ *     action refuses to run. Fail-open on junk, which is the posture
+ *     `ActionRunner` already committed to (`catch { isDisabled = false }`).
+ *
+ * A declared-and-`false` gate is DECLARED (`toPredicateInput` returns the
+ * boolean unchanged): `disabled: false` / `visible: false` are verdicts, and
+ * routing them to the evaluator — which short-circuits booleans — is the point
+ * of asking "declared?" rather than "truthy?".
+ *
+ * ## Why blankness is decided HERE and not in the normalizer (objectui#3960)
+ *
+ * The blank-`source` envelope arrived one release late: objectui#3850's ruling
+ * enumerated three empty spellings, `toPredicateInput` folds a `source` of `''`
+ * and does not trim, so `{ dialect: 'cel', source: '   ' }` stayed "declared"
+ * while core's own CEL entry called that exact value "no predicate" — `disabled`
+ * greyed out and `ActionRunner` refused to execute for a predicate that says
+ * nothing (objectui#3960). The asymmetry was that this definition trimmed the
+ * STRING spelling of a blank predicate and not the ENVELOPE spelling of the same
+ * blank.
+ *
+ * Fixing it at the normalizer instead (`if (!src.trim()) return undefined`) would
+ * have aligned every `evaluateCondition(toPredicateInput(x))` consumer at once,
+ * and that is precisely why it is the wider, wrong lever: it changes what
+ * normalization MEANS, which is a shape question ("what does the evaluator
+ * accept"), to answer a declaredness question ("is there a condition"). Those are
+ * different concepts on purpose — a blank `source` is a shape the evaluator
+ * accepts and answers `true` for, by its own documented rule. The blast radius is
+ * the concrete difference: at the normalizer, a NON-cel blank envelope
+ * (`{ source: '   ' }` → `'${   }'` → falsy) flips verdict for every
+ * `useCondition(toPredicateInput(…))` call site including the container-level
+ * `visible` reads in `action-bar` / `action-group` / `action-menu` /
+ * `RelatedList` / `record-alert`, none of which ask this question at all; here it
+ * flips only for the consumers that DO ask it, and only on the inverted-polarity
+ * keys where "declared" is what turns a control off.
+ *
+ * ## Why the callers still evaluate the RAW value
+ *
+ * Every consumer normalizes to decide DECLAREDNESS and then evaluates whatever
+ * it was given, `evaluateCondition(raw)` or `evaluateCondition(toPredicateInput(
+ * raw))` as it did before. Both agree since objectui#3871 made the normalizer
+ * idempotent for an already-`${…}` string; before that they did not, and a
+ * template-spelled predicate normalized twice came back as a constant. Nothing
+ * here changes a verdict for a value that HAS one — this gate only decides
+ * whether there is one to reach.
+ *
+ * ## Scope history (objectui#3850)
+ *
+ * The question used to be answered three times with three different scopes: the
+ * renderer-side `hasDeclaredVisibilityGate` (`!= null && !== ''`, so every
+ * object counted — including the empty envelope), `SchemaRenderer`'s inline
+ * `!== undefined` (wider still: `disabled: null` greyed the control out,
+ * objectui#3862), and `ActionRunner`'s module-private helper (this scope, which
+ * arrived first with objectui#3848 and is what the ruling adopted). One
+ * definition with one scope replaces all three:
+ * `components/renderers/action/visibility-gate.ts` re-exports this function
+ * under its historic name `hasDeclaredVisibilityGate` (the five member-action
+ * renderer call sites are unchanged), `SchemaRenderer`'s `disabled` /
+ * `disabledOn` chain reads it, and `ActionRunner`'s two gates read it instead of
+ * a private twin.
+ *
+ * Two more consumers joined afterwards, and with them the last two places that
+ * answered this question with a range of their own:
+ * `SchemaRenderer`'s `hidden` / `hiddenOn` legs, whose verdict is NOT negated so
+ * an empty predicate made the node VANISH (objectui#3955), and
+ * `ActionEngine.getActionsForLocation`'s `visible` filter, which folded some
+ * empty spellings by hand and coerced the rest with `Boolean(raw)`, so
+ * `visible: 0` hid an action the renderers showed (objectui#3957). Nothing in the
+ * repo now asks "is a gate declared?" anywhere but here.
+ */
+export function hasDeclaredPredicate(value) {
+    if (isBlankPredicateText(value))
+        return false;
+    return toPredicateInput(value) !== undefined;
+}

package/dist/evaluator/fieldRules.d.ts

@@ -24,6 +24,22 @@ export interface FieldPredicateDiagnostic {
      * warnings for one broken predicate. Defaults to `true`.
      */
     warn?: boolean;
+    /**
+     * Called with the engine's failure reason (`"[kind] message"`, the exact text
+     * the built-in warning prints after `Reason:`) when the predicate cannot be
+     * evaluated. This is the passback for callers that set `warn: false` and
+     * report the fault themselves — without it, silencing the built-in warning
+     * also discards the only description of *why* the predicate failed, which is
+     * how the fail-closed row-predicate path ended up the least debuggable one
+     * (objectui#3792).
+     *
+     * Independent of `warn` and of the one-time-warning dedupe: it fires on every
+     * fault, so a caller doing its own warn-once bookkeeping keeps control of it.
+     * The returned verdict is unaffected. Must not throw — it is invoked outside
+     * the engine guard, so an exception here propagates to the caller rather than
+     * being reported as an engine fault.
+     */
+    onFault?: (reason: string) => void;
 }
 /**
  * Evaluate a field-rule CEL predicate against a record.

package/dist/evaluator/fieldRules.js

@@ -22,8 +22,33 @@
  * CEL (mirrors the server's `toExpression`). Evaluation is *fail-open* for
  * visibility/required (a broken predicate must not hide a field or wrongly
  * block submit) and *fail-open* for readonly (a broken predicate leaves the
- * field editable) — matching the server, which logs and allows the change
- * through.
+ * field editable).
+ *
+ * Fail-open agrees with the server for MOST faults — but not for all, and the
+ * exception is the half worth knowing. Since objectstack#4889 a `readonlyWhen`
+ * predicate that faults because it names a scope ROOT the write never bound —
+ * `parent.status == 'paid'` with no master-detail header in hand — is
+ * fail-CLOSED on the server: `isReadonlyWhenLocked` warns and then returns
+ * TRUE, i.e. LOCKED (a declared lock is not waived merely because it could not
+ * be evaluated), and `stripReadonlyWhenFields` — plus
+ * `stripReadonlyWhenFieldsMulti` on the bulk path — DELETES that key from the
+ * UPDATE payload. This file keeps the same fault fail-OPEN. For that one class
+ * the two ends therefore point in OPPOSITE directions, deliberately: the
+ * framework's ADR-0057 D10 — server enforces, client is courtesy (framework
+ * numbering; this repo's own ADR-0057 is an unrelated document) — makes the
+ * server the authority, so the courtesy layer does not get to guess "locked"
+ * and grey out a field the server might have accepted.
+ *
+ * The caller-visible consequence, spelled out because the symptom is silent:
+ * the form renders the field EDITABLE, the user edits it, the save reports
+ * SUCCESS, and the new value never lands — the server dropped the key and kept
+ * the persisted one. Debug that toward the SERVER-side lock (its `… treating
+ * the field as LOCKED` warning, and the write response's `droppedFields`), not
+ * toward the client predicate, which did exactly what it was asked to. The
+ * other two halves carry no such carve-out: `requiredWhen` binds the same
+ * `parent` scope but deliberately kept fail-open semantics (objectstack#4977),
+ * so an unevaluable requirement is skipped on BOTH ends, and field-level
+ * `visibleWhen` is not a server concept at all.
  *
  * Fail-open is **loud**, not silent (objectstack#5149): a predicate that
  * cannot be evaluated — parse error, unbound identifier, engine fault — logs
@@ -31,8 +56,10 @@
  * reason, then still returns the caller's fallback. Without the warning a
  * broken predicate is indistinguishable from an absent one, so
  * conditional-visibility bugs survive inspection indefinitely. This is the
- * client half of the server's "log and allow" convention (`readonlyWhen for
- * 'x' failed to evaluate — change allowed through`). The *default* stays
+ * client half of the server's "log and allow" convention for the faults where
+ * the two ends DO agree (`readonlyWhen for 'x' failed to evaluate — change
+ * allowed through` — the GENERIC-fault message; the unbound-root fault above
+ * logs `treating the field as LOCKED` instead). The *default* stays
  * fail-open on purpose — flipping it is a shipped-behavior change tracked
  * separately in objectstack#5149 (appeal 1, undecided).
  */
@@ -86,30 +113,38 @@ export function evalFieldPredicate(pred, record, fallback, previous, scope, diag
     if (pred == null || (typeof pred === 'string' && !pred.trim()))
         return fallback;
     const expr = toExpression(pred);
+    // The two fault sources — a not-ok verdict and a throw that slipped past the
+    // engine's "never throws" contract — converge on one reason string and one
+    // reporting site below, so the built-in warning and the `onFault` passback
+    // can never describe the failure differently.
+    let reason;
+    let value = fallback;
     try {
         const res = ExpressionEngine.evaluate(expr, {
             record,
             previous,
             ...(scope ? { extra: scope } : {}),
         });
-        if (!res.ok) {
-            // Parse error, type error, unbound identifier, engine fault … — every
-            // not-ok verdict resolves to the fallback, but never silently (#5149).
-            if (diagnostic?.warn !== false) {
-                warnPredicateFailure(expr, fallback, `[${res.error.kind}] ${res.error.message}`, diagnostic?.context);
-            }
-            return fallback;
-        }
-        return res.value === true;
+        // Parse error, type error, unbound identifier, engine fault … — every
+        // not-ok verdict resolves to the fallback, but never silently (#5149).
+        if (!res.ok)
+            reason = `[${res.error.kind}] ${res.error.message}`;
+        else
+            value = res.value === true;
     }
     catch (err) {
-        // The engine contract is "never throws"; this guard is for anything that
-        // slips past it. Same loud fail-open as the not-ok branch.
+        reason = `[throw] ${err instanceof Error ? err.message : String(err)}`;
+    }
+    if (reason !== undefined) {
         if (diagnostic?.warn !== false) {
-            warnPredicateFailure(expr, fallback, `[throw] ${err instanceof Error ? err.message : String(err)}`, diagnostic?.context);
+            warnPredicateFailure(expr, fallback, reason, diagnostic?.context);
         }
+        // Outside the try on purpose: a throwing callback is a caller bug and must
+        // surface as one, not be swallowed and re-reported as an engine fault.
+        diagnostic?.onFault?.(reason);
         return fallback;
     }
+    return value;
 }
 /**
  * Resolve the effective `{ visible, readonly, required }` state for a field

package/dist/evaluator/index.d.ts

@@ -8,6 +8,7 @@
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
 export * from './predicateInput.js';
+export * from './declaredPredicate.js';
 export * from './fieldRules.js';
 export * from './listConditional.js';
 export * from './optionRules.js';

package/dist/evaluator/index.js

@@ -8,6 +8,7 @@
 export * from './ExpressionContext.js';
 export * from './ExpressionEvaluator.js';
 export * from './predicateInput.js';
+export * from './declaredPredicate.js';
 export * from './fieldRules.js';
 export * from './listConditional.js';
 export * from './optionRules.js';