@object-ui/core 17.6.0 → 18.0.0

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

@@ -5,53 +5,6 @@
  * 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);
@@ -128,8 +81,42 @@ 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) {
+/**
+ * What the contract admits as a row cap.
+ *
+ * A deliberate LOCAL RESTATEMENT of the predicate the repaired read points
+ * spell as `isUsableRowLimit` / `isUsablePageSize`. It is ⛔ not imported and
+ * ⛔ not extracted to a shared helper: this family now spells the same rule at
+ * each site that enforces it, and `isUsableRowLimit` / `isUsablePageSize` is
+ * what enumerates them. Hoisting it into one module would be a cross-package
+ * move nobody has chartered, and it would take the rule out of the file whose
+ * reader needs to see it. The cost — one more copy that could drift — is
+ * written here rather than hidden.
+ *
+ * The destination is declared positive at both ends: the spec's element data
+ * source declares `limit` a positive integer, and a saved view's pagination
+ * declares `pageSize` a positive integer with a default. So `0` is not a
+ * spelling whose meaning this layer may choose — it is a value the contract
+ * already refuses.
+ */
+function isUsableRowLimit(value) {
+    return typeof value === 'number' && Number.isInteger(value) && value > 0;
+}
+/**
+ * The row cap a saved view CARRIES, before the contract is applied to it —
+ * `pagination.pageSize`, or a flat `limit`.
+ *
+ * Split out from {@link savedViewLimit} so the resolver and the diagnostic read
+ * the same carrier by construction. Two readers would be free to drift, and the
+ * drift would be invisible: a value one of them reports and the other keeps, or
+ * the reverse.
+ *
+ * ⚠️ Selection is still by `typeof === 'number'`, unchanged: a non-numeric
+ * `pagination.pageSize` falls through to the flat `limit` exactly as it did
+ * before. Only the POSITIVITY question is new, and it is asked once, by
+ * {@link isUsableRowLimit}, on whichever carrier won.
+ */
+function savedViewRawLimit(view) {
     if (!view)
         return undefined;
     const pagination = view.pagination;
@@ -138,6 +125,167 @@ function savedViewLimit(view) {
     }
     return typeof view.limit === 'number' ? view.limit : undefined;
 }
+/**
+ * Read a saved view's row cap — `pagination.pageSize`, or a flat `limit` —
+ * and hand back only a cap the contract admits.
+ *
+ * ## Why DROP, and not clamp or refuse
+ *
+ * Before this guard, `typeof … === 'number'` admitted `0`, negatives and
+ * fractions, and they lowered unchecked into the composed `limit`. Measured on
+ * both consumers of that key rather than inferred, and the two answers differ:
+ *
+ *  - through a RENDERER, the refused value reached a block that has its own
+ *    guard, so the block dropped it and drew its own default — the named view's
+ *    cap went missing and the read went WIDER than the view asked for;
+ *  - through `ViewDataProvider.resolveElementDataSource`, which forwards this
+ *    key to `DataFetcher.fetchRecords` with NO guard of its own, `0`, `-10` and
+ *    `25.5` reached the fetcher verbatim.
+ *
+ * ⛔ CLAMP is refused: this layer has no default to clamp to. Every consuming
+ * block owns its own default and `ViewDataProvider` owns none, so a number
+ * invented here would override a default the author never asked it to, and
+ * quietly substituting a number the author never wrote is the quieter half of
+ * this same defect.
+ *
+ * ⛔ THROWING is refused: this function is pure and sits under every block that
+ * can be bound to a view, so a throw would take out the page over one
+ * declaration — worse than the defect.
+ *
+ * ⇒ DROP. An absent `limit` is the honest statement that the view supplied no
+ * usable cap, and it is the one thing every consumer already handles.
+ *
+ * The loud half is {@link elementDataSourceRefusedLimitMessage}; see its doc for
+ * why the message is built here and reported by the caller.
+ */
+function savedViewLimit(view) {
+    const raw = savedViewRawLimit(view);
+    return isUsableRowLimit(raw) ? raw : undefined;
+}
+/**
+ * Read the binding's own row cap, and hand back only a cap the contract admits.
+ *
+ * The other operand of the `limit` chain gets the same positivity check as
+ * {@link savedViewLimit}, through the same predicate. Maintainer ruling on
+ * objectui#10016 (option A): a binding `limit` the contract refuses (`0`, a
+ * negative, a fraction, a value that is not a number at all) is NOT AUTHORED.
+ * It yields exactly as an absent one does, to the saved view's usable cap and,
+ * when that is absent too, to the consumer's own default.
+ *
+ * This is objectui#10009's precedent applied as a rule rather than re-decided:
+ * there, one layer up, a value the contract refuses was ruled not authored and
+ * the other source won. Here the same question is asked of the two operands of
+ * one resolver, and it gets the same answer. The repo therefore holds ONE
+ * precedence rule for "whose row cap is used", not one per pair of operands.
+ *
+ * The two answers the ruling refused, and why:
+ *
+ *  - ⛔ dropping the binding's cap AND skipping the view's: a bad value on the
+ *    binding would then discard the view's legitimate cap, which is the least
+ *    explicable outcome for an author;
+ *  - ⛔ refusing loudly and rendering nothing: a blank region at render time
+ *    makes an author's slip expensive without making it any harder to write.
+ *    The loud refusal belongs on the WRITE surface, not here.
+ *
+ * `null` stays what `??` always made it: absent.
+ */
+function bindingLimit(config) {
+    return isUsableRowLimit(config.limit) ? config.limit : undefined;
+}
+/**
+ * The binding operand's half of {@link elementDataSourceRefusedLimitMessage}.
+ * Module-private: callers reach it through that one exported builder, so there
+ * is still exactly one channel for a refused row cap, whichever operand it was.
+ *
+ * Unlike the view's message it needs no condition on the other operand. A
+ * usable binding cap is used whatever the view carries, so a refused one is
+ * ALWAYS a cap the consumer did not get, and saying so is always true.
+ */
+function refusedBindingLimitMessage(binding, viewName, object) {
+    const raw = binding?.limit;
+    if (raw === undefined || raw === null)
+        return null;
+    if (isUsableRowLimit(raw))
+        return null;
+    const where = viewName
+        ? `dataSource binding on ${object} (view "${viewName}")`
+        : `dataSource binding on ${object}`;
+    // `String('20')` would print a string exactly like the number it is not.
+    const shown = typeof raw === 'number' ? String(raw) : String(JSON.stringify(raw));
+    return (`[ObjectUI] ElementDataSource: the ${where} declares \`limit: ${shown}\`, `
+        + 'which is not a positive integer. A row cap must be a positive integer '
+        + '(the spec declares this binding’s `limit` positive), so the binding’s cap '
+        + 'was treated as not authored and ignored, exactly as if the binding declared '
+        + 'no `limit`: the cap comes from the next source that declares a usable one, '
+        + 'or else from the consumer’s own default.');
+}
+/**
+ * The diagnostic half of {@link savedViewLimit} and {@link bindingLimit}.
+ * `null` means "nothing to say".
+ *
+ * ## Which operand
+ *
+ * `operand` picks the refusal to describe; it defaults to `'view'`, the one
+ * this builder described before objectui#10016. Each operand gets its own
+ * sentence, and each names its operand, so the two refusals stay
+ * distinguishable when both fire. They do fire together when the binding AND
+ * the view each carry a refused cap: two declarations, one message each.
+ *
+ * `binding` is the binding as authored. The view's sentence needs it too: it
+ * says the consumer falls back to its own default, and that is only true when
+ * the binding supplied no usable cap. A usable binding cap is used whatever the
+ * view carries, so a refused view cap under one changed nothing and is not
+ * reported. That condition lives HERE, once, rather than at each caller,
+ * because every caller needs it and two copies could drift.
+ *
+ * ## Why a BUILDER here, and not a warning from the composer
+ *
+ * This is the shape {@link elementDataSourceViewNotFoundMessage} already
+ * established in this module, for the reason its doc gives: built here so every
+ * caller reports the same defect the same way. It is followed rather than
+ * re-decided because the alternative is ruled out mechanically —
+ * {@link composeElementDataSource} is PURE and the render path calls it from a
+ * `useMemo`, so a warning emitted inside it would fire during render and fire
+ * again on every re-render. The repaired relay one layer up emits from an
+ * effect for exactly that reason; a pure function has no effect to emit from,
+ * so it hands the caller the words instead.
+ *
+ * ## Why the message has to exist at all
+ *
+ * Dropping alone would be a SILENT change on the renderer path: today the
+ * refused value travels as far as a block whose own guard reports it once, and
+ * after this repair that block receives nothing and correctly says nothing —
+ * an absent key is not a mistake. So the repair would remove the only place the
+ * author was being told. The layer that makes the decision is the layer that
+ * reports it.
+ *
+ * ⛔ NOT a second guard: the predicate lives once, in {@link isUsableRowLimit},
+ * and the view's carrier is read once, by {@link savedViewRawLimit}; this reads
+ * both.
+ *
+ * ⚠️ It speaks only about a cap THIS layer dropped. A non-numeric
+ * `pagination.pageSize` never became a limit here, before or after, so there is
+ * nothing for this layer to report about it. A non-numeric binding `limit` is
+ * different: `??` used to pass it through, so this layer now drops it and says
+ * so.
+ */
+export function elementDataSourceRefusedLimitMessage(view, viewName, object, binding, operand = 'view') {
+    if (operand === 'binding')
+        return refusedBindingLimitMessage(binding, viewName, object);
+    if (isUsableRowLimit(binding?.limit))
+        return null;
+    const raw = savedViewRawLimit(view);
+    if (raw === undefined)
+        return null;
+    if (isUsableRowLimit(raw))
+        return null;
+    const where = viewName ? `saved view "${viewName}" on ${object}` : `saved view on ${object}`;
+    return (`[ObjectUI] ElementDataSource: ${where} declares a row cap of ${String(raw)}, `
+        + 'which is not a positive integer. A row cap must be a positive integer '
+        + '(the spec declares this binding’s `limit` positive, and refuses a zero '
+        + 'or negative `pagination.pageSize`), so the view’s cap was ignored and no '
+        + 'cap was lowered from it — the consuming block uses its own default.');
+}
 /**
  * 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
@@ -165,7 +313,7 @@ function savedViewColumns(view) {
  *
  * 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
+ * for `view` composes a binding with no view, which is exactly the pre-objectstack-ai/objectstack#5576
  * behaviour for the other four keys.
  *
  * See the module doc for the per-key rule table; `filter` is the only key that
@@ -194,7 +342,10 @@ export function composeElementDataSource(config, view) {
     const sort = config.sort ?? view?.sort;
     if (sort !== undefined)
         composed.sort = sort;
-    const limit = config.limit ?? savedViewLimit(view);
+    // One rule for both operands (objectui#10016): a refused cap is not
+    // authored, so a refused binding `limit` yields to the view's cap exactly as
+    // an absent one does.
+    const limit = bindingLimit(config) ?? savedViewLimit(view);
     if (limit !== undefined)
         composed.limit = limit;
     const viewType = savedViewType(view);
@@ -207,10 +358,149 @@ export function composeElementDataSource(config, view) {
  * 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.
+ *
+ * ## Why the empty case may not say "this object has no saved views"
+ *
+ * An EMPTY `knownViews` reaches this function from two different worlds, and
+ * this function cannot tell them apart:
+ *
+ *  1. the saved views were read and there are none;
+ *  2. the read never successfully happened.
+ *
+ * World 2 is not hypothetical and not a bug to be fixed upstream: the shipped
+ * `ObjectStackAdapter.listViews` contract degrades EVERY failure — refused,
+ * offline, malformed — to `[]` on the RESOLVED path (deliberate, and objectui#8151
+ * keeps it), so a broken read arrives at `useElementDataSource` as a successful
+ * empty answer. The hook's own discrimination catches a REJECTION, which is a
+ * shape that contract never produces, so nothing separates the two worlds by the
+ * time the count lands here.
+ *
+ * Framework decision objectstack#13906 decision 1 option A — *a thing that could
+ * not be READ is not a thing that is ABSENT* — therefore binds this branch: it
+ * may only assert what is true in BOTH worlds. It names the possibilities and
+ * commits to neither, because committing is exactly the claim nobody established.
+ *
+ * ⛔ Do not "restore" the shorter sentence by inferring failure from emptiness in
+ * either direction — emptiness is what both worlds produce, so it can never tell
+ * them apart. Saying more than this needs the failure FACT plumbed in from the
+ * adapter (objectui#8151's surface), not a better guess here.
  */
 export function elementDataSourceViewNotFoundMessage(object, view, knownViews) {
     const known = knownViews.length
         ? `Known views: ${[...knownViews].sort().join(', ')}.`
-        : 'This object has no saved views.';
+        : 'No saved views are known for this object. It may have none, or they could not be read.';
     return `dataSource.view "${view}" was not found on object "${object}". ${known}`;
 }
+/* ------------------------------------------------------------------ *
+ * The DECLARATION half — one copy, next to the semantics (objectui#6678)
+ * ------------------------------------------------------------------ */
+/**
+ * The spec key this module resolves, spelled once.
+ *
+ * Every consumer that needs the NAME (the registry injection, its gates, the
+ * pins) reads it from here rather than repeating the literal, so "which key is
+ * this?" has exactly one answer in the tree.
+ */
+export const ELEMENT_DATA_SOURCE_KEY = 'dataSource';
+/**
+ * The authoring-surface declaration of {@link ELEMENT_DATA_SOURCE_KEY} — the one
+ * copy, emitted into every registration that wraps the runtime gate.
+ *
+ * ## Why it lives here and is injected rather than written per block
+ *
+ * `PageComponentSchema.dataSource` is READ by `ElementDataSourceGate` in
+ * `@object-ui/react` on behalf of every object-bound block that wraps itself in
+ * it — nine of them at the time of writing. It was declared by NONE: `validateTree`
+ * skips `BASE_PROPS` and otherwise looks a prop up in the component's `inputs`,
+ * and `dataSource` was in neither. So the html tier reported the one spelling
+ * that resolves a saved view — the only one that works — with the identical
+ * `unknown-prop` warning it gives the spellings that do nothing, on the tier
+ * meant to accept AI-authored pages, where the diagnostic IS the contract
+ * (objectui#6678, the reporter of objectui#6598 gave up on exactly this).
+ *
+ * The maintainer ruling of 2026-08-29 took option B **in the injection form**:
+ * emitted mechanically at the wrapping seam, so a block declares the key from
+ * the same place that reads it. Nine hand-kept copies is the shape that ruling
+ * refused — they drift, and a tenth block would simply forget. Adding the key to
+ * `sdui-parser`'s `BASE_PROPS` (option A) was refused too: that set mirrors
+ * `BaseSchema`, and silencing `dataSource` on blocks that do NOT read it
+ * (`flex`, `card`) would make the diagnostic lie in the other direction.
+ *
+ * ## Why `object`, and not a bare `'object'` kind
+ *
+ * The `binding: 'object'` marker is what tells a consumer this input names an
+ * OBJECT — `validateTree` records it as a binding site, and the designer offers
+ * an object picker rather than a free-text blob. The `type` stays the coarse
+ * `'object'` kind because the value is a record; the two words are unrelated and
+ * both are correct here.
+ *
+ * ## Typed as the framework's injected input (`9e37d9b39`)
+ *
+ * `binding` is not a `ComponentInput` member. The maintainer ruling of
+ * 2026-09-07 answered the card's product question — may an ordinary
+ * registration declare a binding input? — with no, so the ONE writer of the
+ * key is this constant, typed by `InjectedComponentInput` from
+ * `@object-ui/types`: a `ComponentInput` plus the marker. The hand-written
+ * inline type literal that used to sit here was the tell that the key had no
+ * authored home, and the splice in `Registry.register` reached the `inputs`
+ * array through an `as ComponentMeta` cast. Both are gone: the shape is now
+ * checked here and at the splice, and a registration that writes `binding`
+ * itself is an excess-property `tsc` error.
+ */
+export const ELEMENT_DATA_SOURCE_INPUT = {
+    name: ELEMENT_DATA_SOURCE_KEY,
+    type: 'object',
+    binding: 'object',
+    description: 'Per-element data binding: { object, view, filter, sort, limit }. Overrides the ' +
+        'page-level object context for this block; `view` names a saved view of `object`, ' +
+        'and `filter` is ANDed with the view’s own rather than replacing it.',
+};
+/**
+ * The renderers that wrap the runtime gate.
+ *
+ * A `WeakSet` rather than a property on the component: marking must not mutate a
+ * `React.forwardRef` exotic object or show up when a test snapshots a
+ * registration, and an unregistered renderer must stay collectable.
+ */
+const elementDataSourceBlocks = new WeakSet();
+/**
+ * Declare that `renderer` wraps `ElementDataSourceGate`, so its registrations
+ * publish {@link ELEMENT_DATA_SOURCE_INPUT}.
+ *
+ * This is the SEAM, and it is deliberately the only way in: `Registry.register`
+ * injects the declaration for exactly the renderers marked here, so the key is
+ * published by whatever consumes the gate and by nothing else — which is what
+ * keeps the `flex` / `card` direction of the ruling true.
+ * `scripts/check-element-data-source-declaration.mjs` fails any source that
+ * consumes the gate without passing through it, so a new block cannot forget.
+ *
+ * ## Two import paths, ONE name and ONE function
+ *
+ * `@object-ui/react` re-exports this beside `ElementDataSourceGate` so the seam is
+ * findable next to the thing it is about. That export is for DISCOVERABILITY:
+ * every CALL SITE imports from here, and
+ * `scripts/check-element-data-source-declaration.mjs` enforces it.
+ *
+ * The rule is measured, not stylistic. A registration runs at MODULE SCOPE, and
+ * `element:record_picker`'s registration in `@object-ui/components` is the
+ * worked example. 101 suites in this repo partially
+ * mock `@object-ui/react` by hand-listing the exports they return, and a
+ * module-scope read of a name those lists do not carry throws at COLLECTION
+ * time — the importing test file fails before it runs a single assertion.
+ * Measured: 17 files, all four CI shards, zero failed assertions among them.
+ * Nothing mocks `@object-ui/core`, and `@object-ui/components` already imports
+ * `ComponentRegistry` from it at module scope, so this path adds no coupling
+ * that was not already there.
+ */
+export function elementDataSourceBlock(renderer) {
+    if (renderer && (typeof renderer === 'object' || typeof renderer === 'function')) {
+        elementDataSourceBlocks.add(renderer);
+    }
+    return renderer;
+}
+/** Whether `renderer` was marked by {@link elementDataSourceBlock}. */
+export function isElementDataSourceBlock(renderer) {
+    return (!!renderer
+        && (typeof renderer === 'object' || typeof renderer === 'function')
+        && elementDataSourceBlocks.has(renderer));
+}

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

@@ -1,12 +1,17 @@
 /**
  * @object-ui/core - DataScope Module
  *
- * Runtime data scope management for row-level security and
- * reactive data state within the UI component tree.
+ * Resolution of the data a view or a page element reads: the spec's
+ * `ViewData` union (`ViewDataProvider`) and the per-element
+ * `ElementDataSource` binding.
+ *
+ * Row-level security is not evaluated here. The platform declares it once, as
+ * the CEL predicate of a `@objectstack/spec` row-level security policy, and
+ * enforces it on the server; objectui#7750 retired the client-side row-level
+ * filter evaluator this module used to export.
  *
  * @module data-scope
  * @packageDocumentation
  */
-export { DataScopeManager, defaultDataScopeManager, type RowLevelFilter, type DataScopeConfig, } from './DataScopeManager.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';
+export { collectSavedViews, composeElementDataSource, ELEMENT_DATA_SOURCE_INPUT, ELEMENT_DATA_SOURCE_KEY, elementDataSourceBlock, elementDataSourceRefusedLimitMessage, elementDataSourceViewNotFoundMessage, isElementDataSourceBlock, isElementDataSourceConfig, resolveSavedView, type ComposedElementDataSource, type ElementDataSourceConfig, type ElementDataSourceSort, type ElementSavedView, } from './element-data-source.js';

package/dist/data-scope/index.js

@@ -1,12 +1,17 @@
 /**
  * @object-ui/core - DataScope Module
  *
- * Runtime data scope management for row-level security and
- * reactive data state within the UI component tree.
+ * Resolution of the data a view or a page element reads: the spec's
+ * `ViewData` union (`ViewDataProvider`) and the per-element
+ * `ElementDataSource` binding.
+ *
+ * Row-level security is not evaluated here. The platform declares it once, as
+ * the CEL predicate of a `@objectstack/spec` row-level security policy, and
+ * enforces it on the server; objectui#7750 retired the client-side row-level
+ * filter evaluator this module used to export.
  *
  * @module data-scope
  * @packageDocumentation
  */
-export { DataScopeManager, defaultDataScopeManager, } from './DataScopeManager.js';
 export { ViewDataProvider, } from './ViewDataProvider.js';
-export { collectSavedViews, composeElementDataSource, elementDataSourceViewNotFoundMessage, isElementDataSourceConfig, resolveSavedView, } from './element-data-source.js';
+export { collectSavedViews, composeElementDataSource, ELEMENT_DATA_SOURCE_INPUT, ELEMENT_DATA_SOURCE_KEY, elementDataSourceBlock, elementDataSourceRefusedLimitMessage, elementDataSourceViewNotFoundMessage, isElementDataSourceBlock, isElementDataSourceConfig, resolveSavedView, } from './element-data-source.js';

package/dist/evaluator/ExpressionEvaluator.d.ts

@@ -35,6 +35,47 @@ export interface EvaluationOptions {
      * @default true
      */
     sanitize?: boolean;
+    /**
+     * Fault passback: called with the failure reason when this evaluation could
+     * not be performed, at the moment the evaluator ALREADY knows it faulted.
+     *
+     * ## Why a passback and not a second evaluation (objectui#6038)
+     *
+     * The only fault-detection channel this class used to offer a fail-soft
+     * caller was `throwOnError`, and on the CEL branch `evaluateCelCondition`
+     * implements that by evaluating TWICE (once with each fallback — a value
+     * that tracks the fallback both times is a fault). A caller that wants to
+     * *observe* a fault while keeping the fail-soft verdict therefore had to pay
+     * for a second engine call per predicate per node per render. That price is
+     * exactly why the node gate in `SchemaRenderer` bought its diagnostic with a
+     * `__DEV__` gate and shipped production silent.
+     *
+     * This option costs nothing: every fault site below is already inside a
+     * `catch`, or already holds the engine's own failure reason. The verdict is
+     * untouched on every path — `onFault` is invoked for its side effect and its
+     * return value is ignored.
+     *
+     * ## Supplying it TRANSFERS reporting to the caller
+     *
+     * The built-in `console.warn`s on these paths are suppressed while it is
+     * set, so one fault stays one line — the caller's, which can name the node
+     * the predicate belongs to. This mirrors, one layer up, the contract
+     * `FieldPredicateDiagnostic` (`fieldRules.ts`) already documents for the
+     * canonical CEL engine: `warn: false` plus an `onFault` passback, so
+     * silencing the generic line never discards the description of *why* the
+     * predicate failed. On the CEL branch this option is forwarded to exactly
+     * that seam rather than reimplementing it.
+     *
+     * Independent of {@link throwOnError}, which converts a fault into a throw
+     * and is the fail-CLOSED contract; this one keeps the historical fail-soft
+     * answer and merely says so out loud. `throwOnError` still wins where both
+     * are set: the throw happens first and is the caller's own signal.
+     *
+     * Must not throw — it is invoked outside the evaluation guard, so an
+     * exception here propagates to the caller rather than being reported as an
+     * evaluation fault.
+     */
+    onFault?: (reason: string) => void;
 }
 /**
  * Expression evaluator for dynamic UI expressions
@@ -96,6 +137,51 @@ export declare class ExpressionEvaluator {
      * syntax) throws; a genuine `false` never throws.
      */
     private evaluateCelCondition;
+    /**
+     * Answer a BLANK gate predicate — the ONE diagnosed guard of
+     * {@link evaluateCondition}, on both of its routes (objectui#8069 put it on
+     * the `{ dialect: 'cel' }` route; objectui#11262 routes the legacy path's
+     * blank here too, so the two are one report rather than two).
+     *
+     * The verdict is `true` — no predicate → visible/enabled, exactly as before
+     * (objectui#3850 / #3960's verdict) — in EVERY mode, `throwOnError` included,
+     * since the author wrote nothing that could fault. What it is not is SILENT
+     * (ADR-0137 D4: a blank gate predicate is "diagnosed, never a silent
+     * `true`"). The report is `evalFieldPredicate`'s own `[blank]` one — the
+     * channel every other predicate fault already uses — so a caller that passed
+     * `onFault` receives it there (and prints its own, node-named line), and
+     * every other caller gets the deduped built-in warning. No engine call is
+     * made: a blank predicate never reaches the engine.
+     *
+     * The locator names a CEL gate on both routes: a blank has no syntax to put
+     * it in either dialect, and a bare-string predicate is CEL by the spec's
+     * contract. One locator is also what keeps `''` and `{ dialect: 'cel',
+     * source: '' }` on one dedupe key.
+     */
+    private answerBlankGate;
+    /**
+     * Answer a gate that is DECLARED but cannot be evaluated (objectui#11358) —
+     * see `isUnevaluablePredicate` (`./unevaluablePredicate.ts`) for the shapes.
+     *
+     * It is a fault, not a blank: {@link answerBlankGate} answers `true` in every
+     * mode because a blank says nothing, while this value says "there is a gate"
+     * and the client cannot read it. So the modes split exactly as they do for a
+     * predicate that faults with text in it:
+     *
+     *   - `throwOnError` → THROW. The caller opted into fail-closed semantics,
+     *     and its catch both hides / disables and reports, naming the control —
+     *     the same contract `evaluateCelCondition` keeps (no warning AND a throw
+     *     for one fault, objectstack-ai/objectstack#5149).
+     *   - otherwise → reported once through `evalFieldPredicate`'s own report
+     *     (the `[unevaluable]` reason, beside `[blank]`), or handed to the
+     *     caller's `onFault`, and answered with the fail-soft `true`. On a
+     *     `disabled` / `hidden` leg that `true` is the CLOSED side (greyed out /
+     *     hidden), on `visible` / `enabled` / `condition` the open one — each
+     *     key's existing fault direction, unchanged.
+     *
+     * No engine call is made: there is no `source` to hand it.
+     */
+    private answerUnevaluableGate;
     /**
      * Update the context with new data
      */