@object-ui/core 17.6.0 → 17.7.0

package/dist/evaluator/ExpressionEvaluator.js

@@ -18,6 +18,77 @@ import { ExpressionContext } from './ExpressionContext.js';
 import { ExpressionCache } from './ExpressionCache.js';
 import { FormulaFunctions } from './FormulaFunctions.js';
 import { evalFieldPredicate } from './fieldRules.js';
+import { isBlankPredicateText } from './declaredPredicate.js';
+import { isUnevaluablePredicate, UNEVALUABLE_PREDICATE_REASON } from './unevaluablePredicate.js';
+/**
+ * Authored sources already reported by {@link reportEvaluationFault}, keyed on
+ * `[site, source]`.
+ *
+ * ## Why a rate limit at all (objectui#6444)
+ *
+ * `evaluate` is the hottest of the three predicate paths in this area:
+ * `SchemaRenderer` calls it for every `properties.*` value, every `props.*`
+ * value and `content`, for every node, on every render — and both sites below
+ * used to log on EVERY evaluation. Measured on the built evaluator at
+ * `830ed5803`: three identical faulting `evaluateCondition` calls produced
+ * **3** console lines where the `{ dialect: 'cel' }` envelope produced **1**,
+ * and one broken `${…}` prop rendered across a 200-row list produced **200**
+ * lines — then 200 more on the next render.
+ *
+ * This is the one-per-source ceiling both sibling reporters already carry, not
+ * a third mechanism: `warnPredicateFailure` in `./fieldRules.js` (keyed on
+ * dialect + source) and `visibilityDiagnostic.ts` in `@object-ui/react` (keyed
+ * on type + key + source).
+ *
+ * ## Why the key is the source TEXT, and never the scope
+ *
+ * Both siblings key on the AUTHORING identity of the predicate, and neither
+ * keys on the data it was evaluated against: "a broken predicate is
+ * re-evaluated on every render/keystroke, and the point is one loud line, not
+ * a scrolling wall". Here that precedent is also the defect itself — the
+ * 200-row flood is ONE authored source evaluated against 200 DIFFERENT scopes,
+ * so a scope-sensitive key reproduces all 200 lines and fixes nothing.
+ *
+ * The key is JSON-encoded, never joined with a control character — that is
+ * what made a sibling of this file binary to grep (objectstack#5450).
+ *
+ * Unbounded, exactly like both siblings: entries are distinct AUTHORED
+ * expressions, a count an app's metadata bounds; a row count does not.
+ */
+const warnedEvaluationFaults = new Set();
+/**
+ * One fault, one report: hand the reason to the caller's {@link
+ * EvaluationOptions.onFault} when it supplied one, otherwise fall back to this
+ * class's historical `console.warn` — now at most once per authored source.
+ *
+ * Kept as a module-local function rather than repeating the ternary at each
+ * catch, so the "supplying `onFault` suppresses the built-in line" rule is
+ * stated once and cannot drift between the three sites that implement it. The
+ * two message texts moved in here for the same reason: the dedupe key and the
+ * line a reader sees are now built from the same `source`, so the stated
+ * ceiling cannot drift from what the console actually prints.
+ *
+ * The rate limit governs the built-in line ONLY. `onFault` still fires on
+ * every fault, matching the passback contract `./fieldRules.js` already
+ * documents for the canonical engine — "independent of … the one-time-warning
+ * dedupe: it fires on every fault, so a caller doing its own warn-once
+ * bookkeeping keeps control of it". A caller that reports per node must not
+ * have its faults swallowed by this module's bookkeeping.
+ */
+function reportEvaluationFault(onFault, site, source, error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    if (onFault) {
+        onFault(reason);
+        return;
+    }
+    const key = JSON.stringify([site, source]);
+    if (warnedEvaluationFaults.has(key))
+        return;
+    warnedEvaluationFaults.add(key);
+    console.warn(site === 'template-part'
+        ? `Expression evaluation failed for: ${source}`
+        : `Failed to evaluate expression: ${source}`, error);
+}
 /**
  * Expression evaluator for dynamic UI expressions
  */
@@ -73,7 +144,7 @@ export class ExpressionEvaluator {
         if (typeof expression !== 'string') {
             return expression;
         }
-        const { defaultValue, throwOnError = false, sanitize = true } = options;
+        const { defaultValue, throwOnError = false, sanitize = true, onFault } = options;
         try {
             // Check if string contains template expressions
             const hasTemplates = expression.includes('${');
@@ -96,7 +167,7 @@ export class ExpressionEvaluator {
                     if (throwOnError) {
                         throw error;
                     }
-                    console.warn(`Expression evaluation failed for: ${expr}`, error);
+                    reportEvaluationFault(onFault, 'template-part', expr, error);
                     return match; // Return original if evaluation fails
                 }
             });
@@ -105,7 +176,7 @@ export class ExpressionEvaluator {
             if (throwOnError) {
                 throw error;
             }
-            console.warn(`Failed to evaluate expression: ${expression}`, error);
+            reportEvaluationFault(onFault, 'whole-expression', expression, error);
             return defaultValue ?? expression;
         }
     }
@@ -182,6 +253,18 @@ export class ExpressionEvaluator {
         if (typeof condition === 'boolean') {
             return condition;
         }
+        // objectui#11358 — a gate that is DECLARED but has nothing to evaluate: an
+        // envelope with no string `source` (`{ dialect: 'cel', ast }`, or the
+        // `{ dialect: 'cel' }` the normalizer now returns for every such value), a
+        // number, `{}`, an array. It is a FAULT, answered on the same terms as a
+        // predicate that faults with text in it: thrown to a `throwOnError` caller,
+        // whose catch is its fail-closed answer and its report, and otherwise
+        // reported once and answered with the fail-soft `true`. Before, these fell
+        // through to `if (!condition)` / `Boolean(condition)` below and came back
+        // `true` in silence — the "silent `true`" ADR-0137 D4 forbids.
+        if (isUnevaluablePredicate(condition)) {
+            return this.answerUnevaluableGate(condition, options);
+        }
         // #2661 — a CEL-dialect envelope routes to the canonical `@objectstack/formula`
         // engine (the one `fieldRules` / list conditionals already use), NOT the legacy
         // JS evaluator below. This makes a component / action `visible` / `disabled`
@@ -198,17 +281,30 @@ export class ExpressionEvaluator {
         if (condition && typeof condition === 'object' && typeof condition.source === 'string') {
             condition = condition.source;
         }
-        // No condition → default to visible/enabled (undefined, null, '').
+        // A BLANK gate — `''`, whitespace-only text, or an envelope whose `source`
+        // is either (unwrapped just above) — is "no gate": visible/enabled, as it
+        // always was here. It is answered by the SAME diagnosed guard the
+        // `{ dialect: 'cel' }` route above uses (objectui#11262, ADR-0137 D4: a
+        // blank gate predicate is "diagnosed, never a silent `true`"), so a bare
+        // blank, a dialect-less blank envelope and a blank CEL envelope are one
+        // report on one dedupe key. This used to be two silent returns — an
+        // `if (!condition)` and a whitespace-only `trim()` — on the path
+        // `SchemaRenderer`'s visibility legs reach with the raw authored value.
+        if (isBlankPredicateText(condition)) {
+            return this.answerBlankGate(condition, options);
+        }
+        // No condition at all → default to visible/enabled (`undefined`, `null`).
+        // Not blank TEXT, so nothing was declared here to report. Every other
+        // non-string value was answered above, as unevaluable (objectui#11358).
         if (!condition) {
             return true;
         }
         if (typeof condition !== 'string') {
+            // Unreachable since objectui#11358 — kept so a future shape that slips
+            // past `isUnevaluablePredicate` cannot reach the string code below.
             return Boolean(condition);
         }
         const trimmed = condition.trim();
-        if (!trimmed) {
-            return true; // Whitespace-only → treat as "no condition".
-        }
         // A condition is semantically a single boolean expression. When it's a
         // `${...}` template, evaluate via the template path. Otherwise treat the
         // ENTIRE string as one expression (bare CEL like `record.status == "x"`):
@@ -229,6 +325,17 @@ export class ExpressionEvaluator {
             if (options.throwOnError) {
                 throw error;
             }
+            // objectui#6038 — the dialect that reported NOTHING. Measured on the
+            // built evaluator against the other two: a `{ dialect: 'cel' }` envelope
+            // already warns here in production (`evalFieldPredicate`, deduped per
+            // source) and a `${…}` template already warns (the generic line above),
+            // while a BARE-STRING predicate that faults returned its fail-soft `true`
+            // in complete silence. That is the dialect objectstack#11254 measured a
+            // real gate breaking on, and the reason a node gate could stop biting
+            // with nothing on the console to say so. `onFault` is the only new
+            // channel: absent it this catch behaves exactly as it always has, so no
+            // existing caller's console output moves.
+            options.onFault?.(error instanceof Error ? error.message : String(error));
             return true;
         }
     }
@@ -242,22 +349,30 @@ export class ExpressionEvaluator {
      * syntax) throws; a genuine `false` never throws.
      */
     evaluateCelCondition(source, options) {
-        if (!source.trim())
-            return true; // no predicate → visible/enabled
+        if (isBlankPredicateText(source))
+            return this.answerBlankGate(source, options);
         const bag = this.context.toObject();
         const rec = bag.record;
         const record = (rec && typeof rec === 'object' && !Array.isArray(rec))
             ? rec
             : bag;
         if (!options.throwOnError) {
-            // Fast path: one evaluation, fail-soft to visible/enabled (legacy parity).
-            return evalFieldPredicate(source, record, true, undefined, bag);
+            // Fast path: ONE evaluation, fail-soft to visible/enabled (legacy parity).
+            //
+            // objectui#6038: when the caller passes `onFault`, forward it to the seam
+            // `evalFieldPredicate` already exposes for exactly this — `warn: false`
+            // plus the reason passback — rather than adding a second reporter. The
+            // caller then emits one line that can name the node; without `onFault`
+            // the built-in warning fires exactly as before. Either way this stays a
+            // SINGLE engine call: the `throwOnError` double-evaluation below is what
+            // this branch exists to avoid paying in production.
+            return evalFieldPredicate(source, record, true, undefined, bag, options.onFault ? { warn: false, onFault: options.onFault } : undefined);
         }
         // 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.
         // `warn: false`: the throw below IS this path's diagnostic; without it one
-        // broken predicate would log AND throw (#5149).
+        // broken predicate would log AND throw (objectstack-ai/objectstack#5149).
         const asTrue = evalFieldPredicate(source, record, true, undefined, bag, { warn: false });
         const asFalse = evalFieldPredicate(source, record, false, undefined, bag, { warn: false });
         if (asTrue !== asFalse) {
@@ -265,6 +380,63 @@ export class ExpressionEvaluator {
         }
         return asTrue;
     }
+    /**
+     * 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.
+     */
+    answerBlankGate(text, options) {
+        evalFieldPredicate(text, {}, true, undefined, undefined, options.onFault
+            ? { warn: false, onFault: options.onFault }
+            : { context: 'a CEL gate predicate, read as no gate' });
+        return true;
+    }
+    /**
+     * 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.
+     */
+    answerUnevaluableGate(condition, options) {
+        if (options.throwOnError) {
+            throw new Error(`Gate predicate cannot be evaluated: ${UNEVALUABLE_PREDICATE_REASON}`);
+        }
+        return evalFieldPredicate(condition, {}, true, undefined, undefined, options.onFault
+            ? { warn: false, onFault: options.onFault }
+            : { context: 'a declared gate with nothing to evaluate' });
+    }
     /**
      * Update the context with new data
      */

package/dist/evaluator/FormulaFunctions.d.ts

@@ -5,16 +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 - Formula Functions
- *
- * Built-in formula functions for the expression engine.
- * Provides aggregation, date, logic, and string functions
- * compatible with low-code platform expression evaluation.
- *
- * @module evaluator
- * @packageDocumentation
- */
 /**
  * A formula function that can be registered with the expression evaluator
  */

package/dist/evaluator/FormulaFunctions.js

@@ -5,6 +5,99 @@
  * 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 - Formula Functions
+ *
+ * Built-in formula functions for the expression engine.
+ * Provides aggregation, date, logic, and string functions
+ * compatible with low-code platform expression evaluation.
+ *
+ * @module evaluator
+ * @packageDocumentation
+ */
+import { isRealCalendarDate } from '../utils/date-display.js';
+/** Read one date argument, or throw the function's named error. */
+function readFormulaDate(fn, value) {
+    const date = new Date(value);
+    if (isNaN(date.getTime())) {
+        throw new Error(`${fn}: Invalid date "${value}"`);
+    }
+    return { date, day: typeof value === 'string' && isRealCalendarDate(value) };
+}
+/**
+ * The calendar fields of one argument. A day's are read with UTC getters,
+ * which read back the day it names in every zone; an instant's are read with
+ * local getters, in the zone the formula runs in, as they always were.
+ */
+function calendarFields({ date, day }) {
+    return day
+        ? {
+            year: date.getUTCFullYear(),
+            month: date.getUTCMonth(),
+            date: date.getUTCDate(),
+            hours: date.getUTCHours(),
+            minutes: date.getUTCMinutes(),
+            seconds: date.getUTCSeconds(),
+        }
+        : {
+            year: date.getFullYear(),
+            month: date.getMonth(),
+            date: date.getDate(),
+            hours: date.getHours(),
+            minutes: date.getMinutes(),
+            seconds: date.getSeconds(),
+        };
+}
+/**
+ * Move `date` by `months` calendar months on the UTC calendar, clamping the
+ * day to the target month's last day: January 31st plus one month is February
+ * 28th (29th in a leap year), never an overflow into March.
+ *
+ * This is the server's rule, objectstack `@objectstack/formula`'s stdlib
+ * `addMonthsUtc` behind CEL `addMonths(d, n)`, written the same way: step to
+ * the 1st, move the month, then clamp the day. Only a calendar day is moved
+ * with it; an instant keeps `setMonth`, which it always had.
+ */
+function addMonthsUtc(date, months) {
+    const day = date.getUTCDate();
+    date.setUTCDate(1);
+    date.setUTCMonth(date.getUTCMonth() + months);
+    const lastDay = new Date(date.getTime());
+    lastDay.setUTCMonth(lastDay.getUTCMonth() + 1, 0);
+    date.setUTCDate(Math.min(day, lastDay.getUTCDate()));
+}
+/**
+ * `DATEADD` on a calendar day, on the UTC calendar: days, months and years
+ * hand the day back as `YYYY-MM-DD`; hours and minutes give an instant, UTC
+ * midnight of the day moved. `undefined` for a unit `DATEADD` does not know.
+ */
+function addToDay(date, amount, normalizedUnit) {
+    switch (normalizedUnit) {
+        case 'day':
+        case 'days':
+            date.setUTCDate(date.getUTCDate() + amount);
+            break;
+        case 'month':
+        case 'months':
+            addMonthsUtc(date, amount);
+            break;
+        case 'year':
+        case 'years':
+            addMonthsUtc(date, amount * 12);
+            break;
+        case 'hour':
+        case 'hours':
+            date.setUTCHours(date.getUTCHours() + amount);
+            return date.toISOString();
+        case 'minute':
+        case 'minutes':
+            date.setUTCMinutes(date.getUTCMinutes() + amount);
+            return date.toISOString();
+        default:
+            return undefined;
+    }
+    return date.toISOString().slice(0, 10);
+}
 /**
  * Registry of built-in formula functions
  */
@@ -98,6 +191,24 @@ export class FormulaFunctions {
     // Date Functions
     // ==========================================================================
     registerDateFunctions() {
+        /**
+         * `TODAY()` — the current calendar day, as a date-only `YYYY-MM-DD` string.
+         *
+         * Which day that is, is ruled (objectui#10903, ruling A): a client-evaluated
+         * `TODAY()` names the same reference day the server resolves for that
+         * user, on the compute-tz axis of objectstack ADR-0053
+         * (`docs/adr/0053-date-and-datetime-semantics.md`, Phase 2 items 5 and 6),
+         * and the UTC day while no reference timezone reaches the client. The aim
+         * is one "today" per execution context: a client preview and the server's
+         * `today()` naming the same day.
+         *
+         * This implementation reads no timezone, so it answers the UTC day
+         * (`toISOString()`), which is the ruled fallback. It is deliberately not
+         * the viewer's local day. Until the reference timezone reaches the client
+         * (a later card), a server that resolves a reference timezone other than
+         * UTC can name a different day for part of every day. Once the timezone
+         * reaches the client, `TODAY()` names that timezone's calendar day instead.
+         */
         this.register('TODAY', () => {
             const now = new Date();
             return now.toISOString().split('T')[0];
@@ -105,12 +216,46 @@ export class FormulaFunctions {
         this.register('NOW', () => {
             return new Date().toISOString();
         });
+        /**
+         * `DATEADD`, `DATEDIFF` and `DATEFORMAT` do a calendar DAY's arithmetic on
+         * the UTC calendar, the server's (objectstack ADR-0053 D1: a calendar day
+         * is UTC midnight of that day), with UTC setters and getters, so what they
+         * answer for a day does not depend on the zone the formula runs in
+         * (objectui#10866, slice 3). A day is a date-only argument naming a day
+         * its month has.
+         *
+         * - A day is read as UTC midnight of that day. `DATEADD` hands a day moved
+         *   by days, months or years back as `YYYY-MM-DD`; hours and minutes on a
+         *   day give an instant, UTC midnight of the day moved.
+         * - A day's months clamp to the target month's last day, as the server's
+         *   `addMonths` does; a year is twelve months on the same rule, so
+         *   February 29th plus a year is February 28th.
+         * - `DATEFORMAT` prints a day as itself, and `DATEDIFF` counts months and
+         *   years between two days' own months and years.
+         * - A mixed `DATEDIFF`, one day and one instant, reads each argument by its
+         *   own kind when it counts months or years: the day on the UTC calendar,
+         *   the instant in the zone the formula runs in (in a browser, the viewer's).
+         * - Anything else, a value with a time part included, is unchanged: it is
+         *   moved and read with local setters and getters, in the zone the formula
+         *   runs in, and `DATEADD` hands it back as an instant (`toISOString()`).
+         *
+         * A day used to take that same local path: west of UTC `DATEFORMAT`
+         * printed a date-only value as the day before, `DATEDIFF` in months from
+         * August 31st to September 1st read 0, and a `DATEADD` of a day across a
+         * DST change moved an hour off midnight; and a month from January 31st
+         * overflowed into March in every zone. Pinned in both directions by
+         * `__tests__/FormulaFunctions.dateOnlyZone-10866.test.ts`.
+         */
         this.register('DATEADD', (dateStr, amount, unit) => {
-            const date = new Date(dateStr);
-            if (isNaN(date.getTime())) {
-                throw new Error(`DATEADD: Invalid date "${dateStr}"`);
-            }
+            const { date, day } = readFormulaDate('DATEADD', dateStr);
             const normalizedUnit = String(unit).toLowerCase();
+            if (day) {
+                const moved = addToDay(date, amount, normalizedUnit);
+                if (moved === undefined) {
+                    throw new Error(`DATEADD: Unsupported unit "${unit}"`);
+                }
+                return moved;
+            }
             switch (normalizedUnit) {
                 case 'day':
                 case 'days':
@@ -138,26 +283,23 @@ export class FormulaFunctions {
             return date.toISOString();
         });
         this.register('DATEDIFF', (dateStr1, dateStr2, unit) => {
-            const date1 = new Date(dateStr1);
-            const date2 = new Date(dateStr2);
-            if (isNaN(date1.getTime())) {
-                throw new Error(`DATEDIFF: Invalid date "${dateStr1}"`);
-            }
-            if (isNaN(date2.getTime())) {
-                throw new Error(`DATEDIFF: Invalid date "${dateStr2}"`);
-            }
-            const diffMs = date2.getTime() - date1.getTime();
+            const first = readFormulaDate('DATEDIFF', dateStr1);
+            const second = readFormulaDate('DATEDIFF', dateStr2);
+            const diffMs = second.date.getTime() - first.date.getTime();
             const normalizedUnit = String(unit).toLowerCase();
             switch (normalizedUnit) {
                 case 'day':
                 case 'days':
                     return Math.floor(diffMs / (1000 * 60 * 60 * 24));
                 case 'month':
-                case 'months':
-                    return (date2.getFullYear() - date1.getFullYear()) * 12 + (date2.getMonth() - date1.getMonth());
+                case 'months': {
+                    const a = calendarFields(first);
+                    const b = calendarFields(second);
+                    return (b.year - a.year) * 12 + (b.month - a.month);
+                }
                 case 'year':
                 case 'years':
-                    return date2.getFullYear() - date1.getFullYear();
+                    return calendarFields(second).year - calendarFields(first).year;
                 case 'hour':
                 case 'hours':
                     return Math.floor(diffMs / (1000 * 60 * 60));
@@ -169,19 +311,16 @@ export class FormulaFunctions {
             }
         });
         this.register('DATEFORMAT', (dateStr, format) => {
-            const date = new Date(dateStr);
-            if (isNaN(date.getTime())) {
-                throw new Error(`DATEFORMAT: Invalid date "${dateStr}"`);
-            }
+            const fields = calendarFields(readFormulaDate('DATEFORMAT', dateStr));
             const pad = (n, len = 2) => String(n).padStart(len, '0');
             return format
-                .replace('YYYY', String(date.getFullYear()))
-                .replace('YY', String(date.getFullYear()).slice(-2))
-                .replace('MM', pad(date.getMonth() + 1))
-                .replace('DD', pad(date.getDate()))
-                .replace('HH', pad(date.getHours()))
-                .replace('mm', pad(date.getMinutes()))
-                .replace('ss', pad(date.getSeconds()));
+                .replace('YYYY', String(fields.year))
+                .replace('YY', String(fields.year).slice(-2))
+                .replace('MM', pad(fields.month + 1))
+                .replace('DD', pad(fields.date))
+                .replace('HH', pad(fields.hours))
+                .replace('mm', pad(fields.minutes))
+                .replace('ss', pad(fields.seconds));
         });
     }
     // ==========================================================================

package/dist/evaluator/declaredPredicate.d.ts

@@ -5,6 +5,34 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+/**
+ * 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` on both of its
+ * routes (which ask THIS function: the CEL route since objectui#8069, the
+ * legacy path since objectui#11262), `evalRowPredicate` (`listConditional.ts`,
+ * whose blank reaches `evalFieldPredicate`, which asks it too) — brought to the
+ * one place that answers "is there a condition at all?", so the two halves
+ * cannot disagree about the same blank.
+ *
+ * Exported since objectui#8069 for its second consumer, `evalFieldPredicate`
+ * (`evaluator/fieldRules.ts`), which is the entry this docblock's list did NOT
+ * name because it did not apply the rule: it trimmed the STRING spelling only,
+ * so `{ dialect: 'cel', source: '   ' }` went to the engine and came back as a
+ * parse fault while `'   '` returned the caller's fallback in silence. Reusing
+ * this definition rather than writing a fourth `trim()` is the whole point of
+ * the paragraph above.
+ */
+export declare function isBlankPredicateText(value: unknown): boolean;
 /**
  * Is a predicate gate DECLARED on this value — i.e. after normalization, is
  * there still a CONDITION for {@link ExpressionEvaluator.evaluateCondition} to
@@ -38,18 +66,55 @@
  *     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())`).
+ *     `evaluateCondition` (`isBlankPredicateText`, then `true` — diagnosed on
+ *     the CEL route since objectui#8069 and on the legacy path since
+ *     objectui#11262) and `evalRowPredicate` (`evaluator/listConditional.ts`,
+ *     the caller's fallback, through `evalFieldPredicate`'s `[blank]` report
+ *     since objectui#11262).
  *   - `{ 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 }`).
+ *
+ * The three BLANK shapes above (`''`, whitespace-only text, and an envelope
+ * whose `source` is blank) are still folded to "not declared" — that is the
+ * verdict — but no longer in silence: each is reported once (objectui#8069,
+ * ADR-0137 D4), see {@link reportBlankGate}. `null` / `undefined` (no key) is
+ * not blank TEXT and stays silent: nothing was declared there to report.
+ *
+ * ## What is DECLARED although nothing in it can be evaluated (objectui#11358)
+ *
+ * A value that is present but is not a predicate the client can evaluate — an
+ * envelope with no string `source` (the `ast`-only `{ dialect: 'cel', ast }` an
+ * unmirrored authoring door admits), a number (`0`), an object with no `source`
+ * (`{}`), an array — IS a declared gate. Triage's ruling on objectui#11358:
+ * "declared and faulting", "reported once per predicate", and the action
+ * "hides". It used to be the fifth "nothing to evaluate" shape here, answered
+ * "not declared" in silence, so a bulk action gated that way ran over every
+ * selected record and the toolbars and row menu showed it to everyone.
+ *
+ * This function's CODE did not change for it: the normalizer did.
+ * {@link toPredicateInput} no longer folds such a value into `undefined`; it
+ * returns a `cel` envelope with no `source`, so `toPredicateInput(x) !==
+ * undefined` — the line below — answers "declared", and the derivation this
+ * definition rests on still holds with no second list. The state is told apart
+ * in one place, `isUnevaluablePredicate` (`./unevaluablePredicate.ts`).
+ *
+ * What a reader then DOES with it is the evaluation step's, not this
+ * function's: `ExpressionEvaluator.evaluateCondition` and `evalFieldPredicate`
+ * treat it as a FAULT, so each reader answers with the fail direction its key
+ * already has for a predicate that cannot be evaluated, and reports it there,
+ * once — through `evalFieldPredicate`'s report with the `[unevaluable]` reason,
+ * or through the caller's own fault report. That is why this function reports
+ * nothing for it: a declared gate always goes on to an evaluation, and two
+ * reports for one fault is the noise objectstack-ai/objectstack#5149 removed.
+ * On every action `visible` leg that direction is CLOSED (objectui#11212), on
+ * every `disabled` leg too (objectui#11242), and the hide-polarity `hidden` /
+ * `hiddenOn` legs of `SchemaRenderer` answer "hidden". The keys whose fault
+ * direction is OPEN keep it — a `condition` still lets the action run, a
+ * legacy `enabled` leaves the control enabled, an action param's `visible`
+ * still shows the param — now diagnosed rather than silent.
  *
  * A declared-and-`false` gate is DECLARED (`toPredicateInput` returns the
  * boolean unchanged): `disabled: false` / `visible: false` are verdicts, and
@@ -113,7 +178,26 @@
  * 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.
+ * `visible: 0` hid an action the renderers showed (objectui#3957).
+ *
+ * The last one joined with objectui#11322: plugin-grid's `hasVisibilityGate`,
+ * on the grid's selection bar, asks it through the renderer-side name
+ * `hasDeclaredVisibilityGate`. It decides whether a bulk button whose `visible`
+ * admits no record is hidden, and `partitionBulkRows` asks it before handing a
+ * bulk def's `visible` to `partitionRowsByPredicate`. It had kept the old
+ * `!= null && !== ''` scope after every other member of the family moved here,
+ * so a whitespace-only `visible` counted as declared on that bar, failed closed
+ * for every record, and hid an action the row menu and toolbars showed.
+ *
+ * Nothing in the repo now asks "is a gate declared?" anywhere but here for
+ * the keys this definition serves. What stays outside is a different family,
+ * not a twin: the field-rule `*When` keys (ADR-0137) decide it by rules of
+ * their own. Examples are the built-in Edit / Delete row item's
+ * `visibleWhen != null` (`isBuiltinRowActionVisible`), and the opening test of
+ * the shared partitioner `partitionRowsByPredicate` (`null` / `undefined` /
+ * `''`), which is the answer its built-in Delete `visibleWhen` callers get. The
+ * action family asks here before it calls that partitioner.
+ * ⚠️ Nothing re-derives this paragraph: it was read off a source search when
+ * objectui#11322 landed, and no test or gate repeats that search.
  */
 export declare function hasDeclaredPredicate(value: unknown): boolean;