@servicetitan/dte-pdf-editor 1.94.0 → 1.96.0

package/src/utils/formula/evaluate-formula.utils.ts

@@ -1,10 +1,50 @@
 import {
+    type BusinessCalendar,
     type DataModelValues,
+    type FieldScheduleBinding,
     type FormulaOperator,
     type FormulaToken,
     type StructuredFormula,
 } from '../../interface/types';
 import { resolvePdfDataValues } from '../data-model';
+import {
+    addBusinessDays,
+    addCalendarDays,
+    countBusinessDays,
+    countCalendarDays,
+    defaultBusinessCalendar,
+} from './business-days.utils';
+
+/**
+ * Which calendar a date formula uses. `enabled` is the field's custom business-day exclusion
+ * toggle (DTE's schedule binding): off uses plain calendar-day arithmetic (no weekend/holiday
+ * skipping, the pre-DTE-4695 behavior); on uses the field's own calendar (`calendar`, a field
+ * bound to a schedule) or the default one, Saturday and Sunday plus `holidays`.
+ */
+export interface DateCalcOptions {
+    enabled?: boolean;
+    calendar?: BusinessCalendar;
+    holidays?: string[];
+}
+
+/**
+ * A field's options: disabled (plain calendar-day math) unless it has a binding in
+ * `scheduleBindings` (DTE's `fieldKey` = `PdfField.id`), in which case it uses its own calendar
+ * when the host passed one for its id, else the default calendar.
+ */
+export function getFieldDateCalcOptions(
+    fieldId: string | undefined,
+    scheduleBindings: FieldScheduleBinding[] | undefined,
+    holidays: string[] | undefined,
+    fieldCalendars: Record<string, BusinessCalendar> | undefined,
+): DateCalcOptions {
+    const enabled = !!fieldId && !!scheduleBindings?.some(b => b.fieldKey === fieldId);
+    if (!enabled) {
+        return { enabled: false };
+    }
+    const calendar = fieldCalendars?.[fieldId!];
+    return calendar ? { enabled: true, calendar } : { enabled: true, holidays };
+}
 
 /**
  * Convert formula operand to number. Merge tags and fillable only ever give:
@@ -199,94 +239,9 @@ function parseDateValue(raw: string): number {
     return isNaN(d.getTime()) ? NaN : d.getTime();
 }
 
-function toDateOnly(ms: number): Date {
-    const d = new Date(ms);
-    d.setUTCHours(0, 0, 0, 0);
-    return d;
-}
-
-function toDateKey(d: Date): string {
-    const y = d.getUTCFullYear();
-    const m = String(d.getUTCMonth() + 1).padStart(2, '0');
-    const day = String(d.getUTCDate()).padStart(2, '0');
-    return `${y}-${m}-${day}`;
-}
-
-function isWeekend(d: Date): boolean {
-    const day = d.getUTCDay();
-    return day === 0 || day === 6;
-}
-
-function buildHolidaySet(holidays?: string[]): Set<string> {
-    if (!holidays?.length) {
-        return new Set();
-    }
-    const set = new Set<string>();
-    for (const h of holidays) {
-        const d = toDateOnly(new Date(h).getTime());
-        if (!isNaN(d.getTime())) {
-            set.add(toDateKey(d));
-        }
-    }
-    return set;
-}
-
-function isNonBusinessDay(d: Date, holidaySet: Set<string>): boolean {
-    return isWeekend(d) || (holidaySet.size > 0 && holidaySet.has(toDateKey(d)));
-}
-
-/**
- * Add business days to a date (epoch ms), skipping weekends and holidays.
- * Returns the resulting date as epoch ms.
- */
-function addBusinessDays(startMs: number, days: number, holidaySet: Set<string>): number {
-    const result = toDateOnly(startMs);
-    if (!isFinite(result.getTime())) {
-        return result.getTime();
-    }
-
-    const intDays = Math.trunc(days);
-    if (intDays === 0) {
-        return result.getTime();
-    }
-
-    const direction = intDays > 0 ? 1 : -1;
-    let remaining = Math.abs(intDays);
-
-    while (remaining > 0) {
-        result.setUTCDate(result.getUTCDate() + direction);
-        if (!isNonBusinessDay(result, holidaySet)) {
-            remaining--;
-        }
-    }
-
-    return result.getTime();
-}
-
-/**
- * Count business days between two dates (epoch ms), skipping weekends and holidays.
- * Positive when `toMs` is after `fromMs`, negative otherwise.
- */
-function businessDayDiff(fromMs: number, toMs: number, holidaySet: Set<string>): number {
-    const start = toDateOnly(fromMs);
-    const end = toDateOnly(toMs);
-
-    if (!isFinite(start.getTime()) || !isFinite(end.getTime())) {
-        return 0;
-    }
-
-    const direction = end.getTime() >= start.getTime() ? 1 : -1;
-    const cursor = new Date(start.getTime());
-    let count = 0;
-
-    while (toDateKey(cursor) !== toDateKey(end)) {
-        cursor.setUTCDate(cursor.getUTCDate() + direction);
-        if (!isNonBusinessDay(cursor, holidaySet)) {
-            count++;
-        }
-    }
-
-    return count * direction;
+/** Blank date arithmetic is NaN, so it carries through to a null result like other invalid values. */
+function orNaN(value: number | null): number {
+    return value ?? NaN;
 }
 
 function resolveDateAwareTokens(
@@ -297,8 +252,7 @@ function resolveDateAwareTokens(
         if (t.type === 'field') {
             const raw = resolvePdfDataValues(data, t.path);
             if (t.fieldType === 'date') {
-                const ms = parseDateValue(raw);
-                return { kind: 'date', value: isNaN(ms) ? 0 : ms };
+                return { kind: 'date', value: parseDateValue(raw) };
             }
             return { kind: 'number', value: valueToNumber(raw) };
         }
@@ -309,38 +263,60 @@ function resolveDateAwareTokens(
     });
 }
 
+/** Date add/diff behind the field's exclusion toggle: business-day-aware when on, plain when off. */
+interface DateMath {
+    add(ms: number, days: number): number | null;
+    diff(fromMs: number, toMs: number): number | null;
+}
+
+function businessDayMath(calendar: BusinessCalendar): DateMath {
+    return {
+        add: (ms, days) => addBusinessDays(ms, days, calendar),
+        diff: (fromMs, toMs) => countBusinessDays(fromMs, toMs, calendar),
+    };
+}
+
+function calendarDayMath(): DateMath {
+    return {
+        add: (ms, days) => addCalendarDays(ms, days),
+        diff: (fromMs, toMs) => countCalendarDays(fromMs, toMs),
+    };
+}
+
 /**
- * Apply an operator to two typed values with date-aware, business-day semantics:
- *   date + number → add business days  → date
- *   number + date → add business days  → date
- *   date - number → sub business days  → date
- *   date - date   → business day diff  → number
- *   number ± number → normal           → number
+ * Apply an operator to two typed values with date-aware semantics:
+ *   date + number → add days  → date
+ *   number + date → add days  → date
+ *   date - number → sub days  → date
+ *   date - date   → day diff  → number (`D1 - D2` counts from D2 to D1, as DTE does)
+ *   number ± number → normal  → number
+ *
+ * Steps are applied one at a time, left to right, as DTE's `ByodFormulaEvaluator` does.
  */
 function applyDateOp(
     a: TypedValue,
     op: FormulaOperator,
     b: TypedValue,
-    holidaySet: Set<string>,
+    dateMath: DateMath,
 ): TypedValue {
     if (a.kind === 'date' && b.kind === 'number') {
         if (op === '+') {
-            return { kind: 'date', value: addBusinessDays(a.value, b.value, holidaySet) };
+            return { kind: 'date', value: orNaN(dateMath.add(a.value, b.value)) };
         }
         if (op === '-') {
-            return { kind: 'date', value: addBusinessDays(a.value, -b.value, holidaySet) };
+            return { kind: 'date', value: orNaN(dateMath.add(a.value, -b.value)) };
         }
     }
     if (a.kind === 'number' && b.kind === 'date' && op === '+') {
-        return { kind: 'date', value: addBusinessDays(b.value, a.value, holidaySet) };
+        return { kind: 'date', value: orNaN(dateMath.add(b.value, a.value)) };
     }
     if (a.kind === 'date' && b.kind === 'date' && op === '-') {
-        return { kind: 'number', value: businessDayDiff(a.value, b.value, holidaySet) };
+        return { kind: 'number', value: orNaN(dateMath.diff(b.value, a.value)) };
     }
     return { kind: 'number', value: applyOp(a.value, op, b.value) };
 }
 
-function evalDateFlat(tokens: DateAwareToken[], holidaySet: Set<string>): TypedValue {
+function evalDateFlat(tokens: DateAwareToken[], dateMath: DateMath): TypedValue {
     const list = [...tokens];
 
     for (let i = 1; i < list.length - 1; ) {
@@ -349,7 +325,7 @@ function evalDateFlat(tokens: DateAwareToken[], holidaySet: Set<string>): TypedV
             const left = list[i - 1];
             const right = list[i + 1];
             if (isTypedValue(left) && isTypedValue(right)) {
-                const result = applyDateOp(left, t.value, right, holidaySet);
+                const result = applyDateOp(left, t.value, right, dateMath);
                 list.splice(i - 1, 3, result);
                 continue;
             }
@@ -361,7 +337,7 @@ function evalDateFlat(tokens: DateAwareToken[], holidaySet: Set<string>): TypedV
     return isTypedValue(single) ? single : { kind: 'number', value: 0 };
 }
 
-function evalDateAwareTokens(tokens: DateAwareToken[], holidaySet: Set<string>): TypedValue {
+function evalDateAwareTokens(tokens: DateAwareToken[], dateMath: DateMath): TypedValue {
     if (tokens.length === 0) {
         return { kind: 'number', value: 0 };
     }
@@ -379,14 +355,14 @@ function evalDateAwareTokens(tokens: DateAwareToken[], holidaySet: Set<string>):
                 break;
             }
             const inner = list.slice(idx + 1, close);
-            const result = evalDateAwareTokens(inner as DateAwareToken[], holidaySet);
+            const result = evalDateAwareTokens(inner as DateAwareToken[], dateMath);
             list.splice(idx, close - idx + 1, result);
             continue;
         }
         idx++;
     }
 
-    return evalDateFlat(list as DateAwareToken[], holidaySet);
+    return evalDateFlat(list as DateAwareToken[], dateMath);
 }
 
 /*
@@ -406,14 +382,16 @@ function evalDateAwareTokens(tokens: DateAwareToken[], holidaySet: Set<string>):
  * field is omitted rather than showing 0.
  *
  * Date fields are identified by `fieldType: 'date'` on field tokens. When date
- * fields are present, arithmetic follows business-day semantics — weekends and
- * holidays are skipped when adding/subtracting days, and date diffs count only
- * business days.
+ * fields are present and `options.enabled` is on, arithmetic follows business-day
+ * semantics — the calendar's weekend days and holidays are skipped when adding/subtracting
+ * days, and date diffs count only business days, with a result outside the calendar's years
+ * blank. Otherwise (the field's exclusion toggle is off) it's plain calendar-day arithmetic.
+ * Either way, as in DTE, a fractional offset or a difference over 365 days is `null` (blank).
  */
 export function evaluateFormula(
     formula: StructuredFormula | undefined | null,
     data: DataModelValues | undefined,
-    holidays?: string[],
+    options?: DateCalcOptions,
 ): number | null {
     if (!formula?.tokens?.length) {
         return null;
@@ -427,8 +405,10 @@ export function evaluateFormula(
 
     if (dateFieldPaths.size) {
         const resolved = resolveDateAwareTokens(formula, data);
-        const holidaySet = buildHolidaySet(holidays);
-        const result = evalDateAwareTokens(resolved, holidaySet);
+        const dateMath = options?.enabled
+            ? businessDayMath(options.calendar ?? defaultBusinessCalendar(options.holidays))
+            : calendarDayMath();
+        const result = evalDateAwareTokens(resolved, dateMath);
         const n = result.value;
         return Number.isFinite(n) ? n : null;
     }
@@ -445,7 +425,7 @@ export function evaluateFormula(
 export function hasDivisionByZero(
     formula: StructuredFormula | undefined | null,
     data?: DataModelValues,
-    holidays?: string[],
+    options?: DateCalcOptions,
 ) {
     if (!formula?.tokens?.length) {
         return false;
@@ -458,5 +438,5 @@ export function hasDivisionByZero(
     if (!hasAllFieldValues(formula, data, dateFieldPaths)) {
         return false;
     }
-    return evaluateFormula(formula, data, holidays) === null;
+    return evaluateFormula(formula, data, options) === null;
 }

package/src/utils/formula/index.ts

@@ -5,5 +5,6 @@ export * from './expression.utils';
 export * from './format-calculated-result.utils';
 export * from './formula-types';
 export * from './render-formula.utils';
+export * from './schedule-bindings.utils';
 export * from './validate-formula.utils';
 export * from './form-fields.utils';

package/src/utils/formula/schedule-bindings.utils.ts

@@ -0,0 +1,27 @@
+import { type FieldScheduleBinding } from '../../interface/types';
+
+/**
+ * Replaces `fieldKey`'s binding: enabling adds it (default schedule, `scheduleId` undefined);
+ * disabling removes it. Every other field's binding is returned unchanged.
+ */
+export function setFieldScheduleEnabled(
+    bindings: FieldScheduleBinding[],
+    fieldKey: string,
+    enabled: boolean,
+): FieldScheduleBinding[] {
+    const withoutField = bindings.filter(b => b.fieldKey !== fieldKey);
+    return enabled ? [...withoutField, { fieldKey }] : withoutField;
+}
+
+/**
+ * Sets `fieldKey`'s selected schedule (`scheduleId` undefined for the default schedule),
+ * enabling its toggle if it wasn't already on. Every other field's binding is returned unchanged.
+ */
+export function setFieldSchedule(
+    bindings: FieldScheduleBinding[],
+    fieldKey: string,
+    scheduleId: number | undefined,
+): FieldScheduleBinding[] {
+    const withoutField = bindings.filter(b => b.fieldKey !== fieldKey);
+    return [...withoutField, { fieldKey, scheduleId }];
+}