@object-ui/core 17.6.0 → 18.0.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/deadlineSettled.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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.
+ */
+/**
+ * Whether a declared deadline is settled for one row (objectui#11815).
+ *
+ * `@objectstack/spec` declares the deadline semantic on a `date` / `datetime`
+ * field: `dueLike: true` makes it a deadline, and `settledWhen` is a per-record
+ * CEL predicate that, while it holds, settles that deadline for the record —
+ * no overdue wording, no overdue colour. The date cells paint from the field's
+ * declaration alone and cannot evaluate a predicate, so every host that draws
+ * one beside a row asks THIS function and hands the cell its answer as the
+ * `deadlineSettled` prop. One helper, so no host carries its own copy.
+ */
+import { type RowPredicateOptions } from './listConditional.js';
+import type { FieldRulePredicate } from './fieldRules.js';
+/** The two declared keys {@link isDeadlineSettled} reads off a field. */
+export interface DeadlineFieldLike {
+    name?: string;
+    dueLike?: boolean | null;
+    settledWhen?: FieldRulePredicate | null;
+}
+/**
+ * `true` only when the field declares `dueLike: true` AND a `settledWhen`, and
+ * that predicate holds for `row` (bound as `record`, through
+ * {@link evalRowPredicate} — the evaluator, scope and relation collapse the
+ * grid's conditional formatting uses).
+ *
+ * Every other answer is `false`:
+ *  - a field that is not a declared deadline, or declares no `settledWhen`, is
+ *    never settled;
+ *  - a predicate that fails to evaluate is NOT settled. It was judged when it
+ *    was authored, and a quiet "settled" would hide an overdue item; the
+ *    evaluator's own one-time warning names the fault.
+ */
+export declare function isDeadlineSettled(field: DeadlineFieldLike | null | undefined, row: Record<string, unknown> | null | undefined, opts?: Pick<RowPredicateOptions, 'scope' | 'fields'>): boolean;

package/dist/evaluator/deadlineSettled.js

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+/**
+ * Whether a declared deadline is settled for one row (objectui#11815).
+ *
+ * `@objectstack/spec` declares the deadline semantic on a `date` / `datetime`
+ * field: `dueLike: true` makes it a deadline, and `settledWhen` is a per-record
+ * CEL predicate that, while it holds, settles that deadline for the record —
+ * no overdue wording, no overdue colour. The date cells paint from the field's
+ * declaration alone and cannot evaluate a predicate, so every host that draws
+ * one beside a row asks THIS function and hands the cell its answer as the
+ * `deadlineSettled` prop. One helper, so no host carries its own copy.
+ */
+import { evalRowPredicate } from './listConditional.js';
+/**
+ * `true` only when the field declares `dueLike: true` AND a `settledWhen`, and
+ * that predicate holds for `row` (bound as `record`, through
+ * {@link evalRowPredicate} — the evaluator, scope and relation collapse the
+ * grid's conditional formatting uses).
+ *
+ * Every other answer is `false`:
+ *  - a field that is not a declared deadline, or declares no `settledWhen`, is
+ *    never settled;
+ *  - a predicate that fails to evaluate is NOT settled. It was judged when it
+ *    was authored, and a quiet "settled" would hide an overdue item; the
+ *    evaluator's own one-time warning names the fault.
+ */
+export function isDeadlineSettled(field, row, opts = {}) {
+    if (!field || field.dueLike !== true)
+        return false;
+    const settledWhen = field.settledWhen;
+    if (settledWhen == null)
+        return false;
+    return evalRowPredicate(settledWhen, row, {
+        fallback: false,
+        scope: opts.scope,
+        fields: opts.fields,
+        label: `${field.name ?? 'field'}.settledWhen`,
+    });
+}