@object-ui/core 17.2.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/ExpressionEvaluator.js

@@ -256,8 +256,10 @@ export class ExpressionEvaluator {
         // 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);
+        // `warn: false`: the throw below IS this path's diagnostic; without it one
+        // broken predicate would log AND throw (#5149).
+        const asTrue = evalFieldPredicate(source, record, true, undefined, bag, { warn: false });
+        const asFalse = evalFieldPredicate(source, record, false, undefined, bag, { warn: false });
         if (asTrue !== asFalse) {
             throw new Error(`CEL predicate failed to evaluate: ${source}`);
         }

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

@@ -10,6 +10,37 @@ export type FieldRulePredicate = string | {
     dialect?: string;
     source: string;
 };
+/** Diagnostic options for {@link evalFieldPredicate} evaluation failures. */
+export interface FieldPredicateDiagnostic {
+    /**
+     * Human-readable locator included in the one-time failure warning — e.g.
+     * `"visibleWhen of field 'amount'"`. Pass whatever the call site knows; the
+     * predicate source text and failure reason are always included.
+     */
+    context?: string;
+    /**
+     * Set `false` when the caller deliberately probes for faults (evaluating
+     * twice with both fallbacks) and surfaces its own diagnostic — prevents two
+     * 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.
  *
@@ -24,14 +55,23 @@ export type FieldRulePredicate = string | {
  *                  e.g. `{ parent }` so an inline line-item cell can reference
  *                  its header (`parent.status == 'paid'`) as well as its own
  *                  row (`record.quantity`). Bound via the engine's `extra`.
+ * @param diagnostic  Failure-warning options: a `context` locator for the
+ *                  one-time warning, and `warn: false` for callers that probe
+ *                  for faults and report them themselves. The returned value
+ *                  is unaffected either way.
  */
-export declare function evalFieldPredicate(pred: FieldRulePredicate | undefined | null, record: Record<string, unknown>, fallback: boolean, previous?: Record<string, unknown>, scope?: Record<string, unknown>): boolean;
+export declare function evalFieldPredicate(pred: FieldRulePredicate | undefined | null, record: Record<string, unknown>, fallback: boolean, previous?: Record<string, unknown>, scope?: Record<string, unknown>, diagnostic?: FieldPredicateDiagnostic): boolean;
 /**
  * Resolve the effective `{ visible, readonly, required }` state for a field
  * given its conditional rules and the live record. Each `*When` rule, when
  * present, *overrides* the static flag. A static `true` is never weakened by a
  * `false` predicate result for required/readonly — but `visibleWhen` is
  * authoritative when present (so a field can be conditionally shown/hidden).
+ *
+ * @param fieldContext  Optional locator for failure warnings — e.g.
+ *                      `"field 'amount'"`. The warning then reads
+ *                      `visibleWhen of field 'amount' …`; without it, the rule
+ *                      kind alone is reported.
  */
 export declare function resolveFieldRuleState(rules: {
     visibleWhen?: FieldRulePredicate;
@@ -40,7 +80,7 @@ export declare function resolveFieldRuleState(rules: {
 }, record: Record<string, unknown>, statics: {
     required?: boolean;
     readonly?: boolean;
-}, previous?: Record<string, unknown>, scope?: Record<string, unknown>): {
+}, previous?: Record<string, unknown>, scope?: Record<string, unknown>, fieldContext?: string): {
     visible: boolean;
     readonly: boolean;
     required: boolean;