@servicetitan/dte-pdf-editor 1.95.0 → 1.96.0

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

@@ -1,5 +1,17 @@
-import { type DataModelValues, type StructuredFormula } from '../../../interface/types';
-import { evaluateFormula, hasDivisionByZero, valueToNumber } from '../evaluate-formula.utils';
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import {
+    type BusinessCalendar,
+    type DataModelValues,
+    type FieldScheduleBinding,
+    type StructuredFormula,
+} from '../../../interface/types';
+import {
+    evaluateFormula,
+    getFieldDateCalcOptions,
+    hasDivisionByZero,
+    valueToNumber,
+} from '../evaluate-formula.utils';
 
 const f = (tokens: StructuredFormula['tokens']): StructuredFormula => ({ tokens });
 
@@ -35,7 +47,7 @@ describe('evaluateFormula', () => {
         formula: StructuredFormula | undefined | null,
         data: DataModelValues | undefined,
         holidays?: string[],
-    ) => evaluateFormula(formula, data, holidays);
+    ) => evaluateFormula(formula, data, { enabled: true, holidays });
 
     describe('when formula is empty', () => {
         test.each([
@@ -180,6 +192,18 @@ describe('evaluateFormula', () => {
     });
 
     describe('with date fields', () => {
+        // The default calendar covers the current year ± 1.
+        beforeAll(() => {
+            jest.useFakeTimers({ now: new Date('2024-06-01T00:00:00Z') });
+        });
+
+        afterAll(() => {
+            jest.useRealTimers();
+        });
+
+        const dateKey = (result: number | null) =>
+            result === null ? null : new Date(result).toISOString().slice(0, 10);
+
         test('adds business days to a date field (skipping weekend)', () => {
             // Friday 2024-01-05 + 1 business day = Monday 2024-01-08
             const formula = f([
@@ -187,22 +211,18 @@ describe('evaluateFormula', () => {
                 { type: 'operator', value: '+' },
                 { type: 'number', value: '1' },
             ]);
-            const result = subject(formula, { d: '2024-01-05' });
-            expect(result).not.toBeNull();
-            const date = new Date(result as number);
-            expect(date.getUTCFullYear()).toBe(2024);
-            expect(date.getUTCMonth()).toBe(0);
-            expect(date.getUTCDate()).toBe(8);
+            expect(dateKey(subject(formula, { d: '2024-01-05' }))).toBe('2024-01-08');
         });
 
-        test('counts business days when subtracting later date from earlier date', () => {
-            // start - end traverses Mon 2024-01-01 → Fri 2024-01-05 = 4 business days
+        test('counts D1 - D2 from D2 to D1, positive when D1 is later', () => {
+            // end - start traverses Mon 2024-01-01 → Fri 2024-01-05 = 4 business days
             const formula = f([
-                { type: 'field', path: 'start', fieldType: 'date' },
-                { type: 'operator', value: '-' },
                 { type: 'field', path: 'end', fieldType: 'date' },
+                { type: 'operator', value: '-' },
+                { type: 'field', path: 'start', fieldType: 'date' },
             ]);
             expect(subject(formula, { start: '2024-01-01', end: '2024-01-05' })).toBe(4);
+            expect(subject(formula, { start: '2024-01-05', end: '2024-01-01' })).toBe(-4);
         });
 
         test('skips holidays when adding business days', () => {
@@ -212,9 +232,43 @@ describe('evaluateFormula', () => {
                 { type: 'operator', value: '+' },
                 { type: 'number', value: '1' },
             ]);
-            const result = subject(formula, { d: '2024-01-08' }, ['2024-01-09']);
-            expect(result).not.toBeNull();
-            expect(new Date(result as number).getUTCDate()).toBe(10);
+            expect(dateKey(subject(formula, { d: '2024-01-08' }, ['2024-01-09']))).toBe(
+                '2024-01-10',
+            );
+        });
+
+        test('applies chained offsets one step at a time', () => {
+            // D - 1 + 2 from Sat 2024-10-05: Fri 10-04, then Tue 10-08
+            const formula = f([
+                { type: 'field', path: 'd', fieldType: 'date' },
+                { type: 'operator', value: '-' },
+                { type: 'number', value: '1' },
+                { type: 'operator', value: '+' },
+                { type: 'number', value: '2' },
+            ]);
+            expect(dateKey(subject(formula, { d: '2024-10-05' }))).toBe('2024-10-08');
+        });
+
+        test.each([
+            ['a fractional offset', { d: '2024-09-30', n: '2.5' }],
+            ['a start outside the current year ± 1', { d: '2022-06-01', n: '1' }],
+            ['a result outside the current year ± 1', { d: '2025-12-31', n: '1' }],
+        ])('returns null for %s', (_, data) => {
+            const formula = f([
+                { type: 'field', path: 'd', fieldType: 'date' },
+                { type: 'operator', value: '+' },
+                { type: 'field', path: 'n', fieldType: 'number' },
+            ]);
+            expect(subject(formula, data)).toBeNull();
+        });
+
+        test('returns null for a difference over 365 days', () => {
+            const formula = f([
+                { type: 'field', path: 'end', fieldType: 'date' },
+                { type: 'operator', value: '-' },
+                { type: 'field', path: 'start', fieldType: 'date' },
+            ]);
+            expect(subject(formula, { start: '2024-01-02', end: '2025-01-05' })).toBeNull();
         });
 
         test('returns null when date field has invalid value', () => {
@@ -225,5 +279,133 @@ describe('evaluateFormula', () => {
             ]);
             expect(subject(formula, { d: 'not-a-date' })).toBeNull();
         });
+
+        test('uses only the field calendar when one is passed', () => {
+            // Fri 2026-07-10 + 1 = Sat 2026-07-11 with a Sunday-only calendar, outside today's years.
+            const formula = f([
+                { type: 'field', path: 'd', fieldType: 'date' },
+                { type: 'operator', value: '+' },
+                { type: 'number', value: '1' },
+            ]);
+            const calendar: BusinessCalendar = {
+                weekendDays: [0],
+                holidays: [],
+                firstYear: 2026,
+                lastYear: 2026,
+            };
+            const result = evaluateFormula(formula, { d: '2026-07-10' }, { enabled: true, calendar });
+            expect(dateKey(result)).toBe('2026-07-11');
+        });
+
+        test('uses plain calendar-day arithmetic (no skipping) when the toggle is disabled', () => {
+            // Friday 2024-01-05 + 1 day = Saturday 2024-01-06, unskipped, regardless of holidays passed.
+            const formula = f([
+                { type: 'field', path: 'd', fieldType: 'date' },
+                { type: 'operator', value: '+' },
+                { type: 'number', value: '1' },
+            ]);
+            const result = evaluateFormula(
+                formula,
+                { d: '2024-01-05' },
+                { enabled: false, holidays: ['2024-01-06'] },
+            );
+            expect(dateKey(result)).toBe('2024-01-06');
+        });
+
+        test('uses plain calendar-day diff (no skipping) when the toggle is disabled', () => {
+            // Plain calendar days between Mon 2024-01-01 and Fri 2024-01-05 is 4, same as business days
+            // here, so use a span that differs: Fri 2024-01-05 -> Mon 2024-01-08 is 3 calendar days but
+            // only 1 business day.
+            const formula = f([
+                { type: 'field', path: 'end', fieldType: 'date' },
+                { type: 'operator', value: '-' },
+                { type: 'field', path: 'start', fieldType: 'date' },
+            ]);
+            const result = evaluateFormula(
+                formula,
+                { start: '2024-01-05', end: '2024-01-08' },
+                { enabled: false },
+            );
+            expect(result).toBe(3);
+        });
+    });
+});
+
+describe('getFieldDateCalcOptions', () => {
+    const calendar: BusinessCalendar = {
+        weekendDays: [0],
+        holidays: [],
+        firstYear: 2026,
+        lastYear: 2027,
+    };
+    const scheduleBindings: FieldScheduleBinding[] = [{ fieldKey: 'a' }, { fieldKey: 'b' }];
+
+    test.each([
+        ['the field calendar for a bound, listed field', 'a', { enabled: true, calendar }],
+        [
+            'the default holidays for a bound field with no calendar entry',
+            'b',
+            { enabled: true, holidays: ['2026-07-03'] },
+        ],
+        ['disabled for an unbound field', 'c', { enabled: false }],
+        ['disabled without a field id', undefined, { enabled: false }],
+    ])('returns %s', (_, fieldId, expected) => {
+        expect(
+            getFieldDateCalcOptions(fieldId, scheduleBindings, ['2026-07-03'], { a: calendar }),
+        ).toEqual(expected);
+    });
+});
+
+describe('business-day parity fixture', () => {
+    // DTE's shared business-day cases; packages/unlayer's date-calc test checks the copy's hash.
+    const fixture: {
+        calendars: Record<string, BusinessCalendar>;
+        cases: {
+            name: string;
+            calendar: string;
+            start: string;
+            steps?: number[];
+            end?: string | null;
+            expected: string | number | null;
+        }[];
+    } = JSON.parse(
+        readFileSync(
+            resolve(__dirname, '../../../../../../tests/fixtures/business-day-cases.json'),
+            'utf-8',
+        ),
+    );
+
+    type FixtureCase = (typeof fixture.cases)[number];
+
+    // The case as a BYOD formula: `start ± step ± step …`, or `end - start`.
+    const toFormula = (testCase: FixtureCase): StructuredFormula => {
+        if ('end' in testCase) {
+            return f([
+                { type: 'field', path: 'end', fieldType: 'date' },
+                { type: 'operator', value: '-' },
+                { type: 'field', path: 'start', fieldType: 'date' },
+            ]);
+        }
+        return f([
+            { type: 'field', path: 'start', fieldType: 'date' },
+            ...(testCase.steps ?? []).flatMap((step): StructuredFormula['tokens'] => [
+                { type: 'operator', value: step < 0 ? '-' : '+' },
+                { type: 'number', value: String(Math.abs(step)) },
+            ]),
+        ]);
+    };
+
+    test.each(fixture.cases.map(c => [c.name, c] as const))('%s', (_, testCase) => {
+        const data = { start: testCase.start, end: testCase.end ?? '' };
+        const result = evaluateFormula(toFormula(testCase), data, {
+            enabled: true,
+            calendar: fixture.calendars[testCase.calendar],
+        });
+
+        const actual =
+            result === null || 'end' in testCase
+                ? result
+                : new Date(result).toISOString().slice(0, 10);
+        expect(actual).toBe(testCase.expected);
     });
 });

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

@@ -0,0 +1,73 @@
+import { type FieldScheduleBinding } from '../../../interface/types';
+import { setFieldSchedule, setFieldScheduleEnabled } from '../schedule-bindings.utils';
+
+describe('setFieldScheduleEnabled', () => {
+    test('adds a default-schedule binding when enabling a field with no existing binding', () => {
+        expect(setFieldScheduleEnabled([], 'field-a', true)).toEqual([{ fieldKey: 'field-a' }]);
+    });
+
+    test('removing a field with no binding is a no-op', () => {
+        const bindings: FieldScheduleBinding[] = [{ fieldKey: 'field-b', scheduleId: 7 }];
+        expect(setFieldScheduleEnabled(bindings, 'field-a', false)).toEqual(bindings);
+    });
+
+    test('disabling removes the field from the bindings', () => {
+        const bindings: FieldScheduleBinding[] = [
+            { fieldKey: 'field-a', scheduleId: 3 },
+            { fieldKey: 'field-b' },
+        ];
+        expect(setFieldScheduleEnabled(bindings, 'field-a', false)).toEqual([
+            { fieldKey: 'field-b' },
+        ]);
+    });
+
+    test('re-enabling after disabling resets to the default schedule, not the previous one', () => {
+        const bindings: FieldScheduleBinding[] = [{ fieldKey: 'field-a', scheduleId: 3 }];
+        const disabled = setFieldScheduleEnabled(bindings, 'field-a', false);
+        expect(setFieldScheduleEnabled(disabled, 'field-a', true)).toEqual([
+            { fieldKey: 'field-a' },
+        ]);
+    });
+
+    test('leaves other fields untouched (field identity isolation)', () => {
+        const bindings: FieldScheduleBinding[] = [
+            { fieldKey: 'field-a', scheduleId: 1 },
+            { fieldKey: 'field-b', scheduleId: 2 },
+        ];
+        const result = setFieldScheduleEnabled(bindings, 'field-a', false);
+        expect(result).toEqual([{ fieldKey: 'field-b', scheduleId: 2 }]);
+    });
+});
+
+describe('setFieldSchedule', () => {
+    test('sets the default schedule (scheduleId undefined) for a new field', () => {
+        expect(setFieldSchedule([], 'field-a', undefined)).toEqual([
+            { fieldKey: 'field-a', scheduleId: undefined },
+        ]);
+    });
+
+    test('sets a named schedule id for a new field', () => {
+        expect(setFieldSchedule([], 'field-a', 42)).toEqual([
+            { fieldKey: 'field-a', scheduleId: 42 },
+        ]);
+    });
+
+    test('replaces an existing binding for the same field', () => {
+        const bindings: FieldScheduleBinding[] = [{ fieldKey: 'field-a', scheduleId: 1 }];
+        expect(setFieldSchedule(bindings, 'field-a', 2)).toEqual([
+            { fieldKey: 'field-a', scheduleId: 2 },
+        ]);
+    });
+
+    test('leaves other fields untouched (field identity isolation)', () => {
+        const bindings: FieldScheduleBinding[] = [
+            { fieldKey: 'field-a', scheduleId: 1 },
+            { fieldKey: 'field-b', scheduleId: 2 },
+        ];
+        const result = setFieldSchedule(bindings, 'field-a', 9);
+        expect(result).toEqual([
+            { fieldKey: 'field-b', scheduleId: 2 },
+            { fieldKey: 'field-a', scheduleId: 9 },
+        ]);
+    });
+});

package/src/utils/formula/business-days.utils.ts

@@ -0,0 +1,188 @@
+import { DEFAULT_CALENDAR_YEARS, MAX_DATE_CALC_DAYS } from '../../constants';
+import { type BusinessCalendar } from '../../interface/types';
+
+/** Saturday and Sunday: the default calendar's weekend. */
+const DEFAULT_WEEKEND_DAYS = [0, 6];
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+interface PreparedCalendar {
+    weekendDays: Set<number>;
+    holidays: Set<string>;
+    firstYear: number;
+    lastYear: number;
+}
+
+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 buildHolidaySet(holidays: string[] | undefined): Set<string> {
+    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;
+}
+
+// Calendars are passed once and reused by every field, so each is prepared once.
+const preparedCalendars = new WeakMap<BusinessCalendar, PreparedCalendar>();
+
+function prepareCalendar(calendar: BusinessCalendar): PreparedCalendar {
+    const cached = preparedCalendars.get(calendar);
+    if (cached) {
+        return cached;
+    }
+    const prepared: PreparedCalendar = {
+        weekendDays: new Set(calendar.weekendDays ?? DEFAULT_WEEKEND_DAYS),
+        holidays: buildHolidaySet(calendar.holidays),
+        firstYear: calendar.firstYear,
+        lastYear: calendar.lastYear,
+    };
+    preparedCalendars.set(calendar, prepared);
+    return prepared;
+}
+
+/**
+ * The default calendar: Saturday and Sunday plus `holidays` (the host's, DTE's
+ * `GET api/holidays`), for the current year ± DEFAULT_CALENDAR_YEARS. Fields whose schedule toggle
+ * is off use it.
+ */
+export function defaultBusinessCalendar(holidays?: string[]): BusinessCalendar {
+    const year = new Date().getUTCFullYear();
+    return {
+        weekendDays: DEFAULT_WEEKEND_DAYS,
+        holidays: holidays ?? [],
+        firstYear: year - DEFAULT_CALENDAR_YEARS,
+        lastYear: year + DEFAULT_CALENDAR_YEARS,
+    };
+}
+
+function isBusinessDay(d: Date, calendar: PreparedCalendar): boolean {
+    return !calendar.weekendDays.has(d.getUTCDay()) && !calendar.holidays.has(toDateKey(d));
+}
+
+function isWithinYears(d: Date, calendar: PreparedCalendar): boolean {
+    const year = d.getUTCFullYear();
+    return year >= calendar.firstYear && year <= calendar.lastYear;
+}
+
+/**
+ * Walks `days` business days from a date (epoch ms; negative walks back), the start not counted.
+ * Mirrors DTE's `BusinessDayCalculator.AddBusinessDays`: null for a fractional offset, more than
+ * MAX_DATE_CALC_DAYS, an invalid start, or a start or walk outside the calendar's years.
+ */
+export function addBusinessDays(
+    startMs: number,
+    days: number,
+    calendar: BusinessCalendar,
+): number | null {
+    const prepared = prepareCalendar(calendar);
+    const start = toDateOnly(startMs);
+    if (
+        !Number.isInteger(days) ||
+        Math.abs(days) > MAX_DATE_CALC_DAYS ||
+        !isFinite(start.getTime()) ||
+        !isWithinYears(start, prepared)
+    ) {
+        return null;
+    }
+
+    const direction = days >= 0 ? 1 : -1;
+    let remaining = Math.abs(days);
+    const current = new Date(start.getTime());
+
+    while (remaining > 0) {
+        current.setUTCDate(current.getUTCDate() + direction);
+        if (!isWithinYears(current, prepared)) {
+            return null;
+        }
+        if (isBusinessDay(current, prepared)) {
+            remaining--;
+        }
+    }
+
+    return current.getTime();
+}
+
+/**
+ * Counts the business days from `fromMs` to `toMs`, negative when `toMs` is earlier; the start is
+ * not counted, the end is. Mirrors DTE's `BusinessDayCalculator.CountBusinessDays`: null for an
+ * invalid date, a span over MAX_DATE_CALC_DAYS, or a date outside the calendar's years.
+ */
+export function countBusinessDays(
+    fromMs: number,
+    toMs: number,
+    calendar: BusinessCalendar,
+): number | null {
+    const prepared = prepareCalendar(calendar);
+    const from = toDateOnly(fromMs);
+    const to = toDateOnly(toMs);
+    if (!isFinite(from.getTime()) || !isFinite(to.getTime())) {
+        return null;
+    }
+    if (
+        Math.abs(to.getTime() - from.getTime()) / DAY_MS > MAX_DATE_CALC_DAYS ||
+        !isWithinYears(from, prepared) ||
+        !isWithinYears(to, prepared)
+    ) {
+        return null;
+    }
+
+    const direction = to.getTime() >= from.getTime() ? 1 : -1;
+    const cursor = new Date(from.getTime());
+    let count = 0;
+
+    while (toDateKey(cursor) !== toDateKey(to)) {
+        cursor.setUTCDate(cursor.getUTCDate() + direction);
+        if (isBusinessDay(cursor, prepared)) {
+            count++;
+        }
+    }
+
+    return count * direction;
+}
+
+/**
+ * Adds `days` plain calendar days to a date (epoch ms; negative subtracts) — no weekend or holiday
+ * skipping. Used when a date calculated field's business-day exclusion toggle is off, matching the
+ * pre-DTE-4695 behavior. Null for a fractional offset, more than MAX_DATE_CALC_DAYS, or an invalid
+ * start.
+ */
+export function addCalendarDays(startMs: number, days: number): number | null {
+    const start = toDateOnly(startMs);
+    if (
+        !Number.isInteger(days) ||
+        Math.abs(days) > MAX_DATE_CALC_DAYS ||
+        !isFinite(start.getTime())
+    ) {
+        return null;
+    }
+    return start.getTime() + days * DAY_MS;
+}
+
+/**
+ * Counts the plain calendar days from `fromMs` to `toMs`, negative when `toMs` is earlier — no
+ * weekend or holiday skipping. Null for an invalid date or a span over MAX_DATE_CALC_DAYS.
+ */
+export function countCalendarDays(fromMs: number, toMs: number): number | null {
+    const from = toDateOnly(fromMs);
+    const to = toDateOnly(toMs);
+    if (!isFinite(from.getTime()) || !isFinite(to.getTime())) {
+        return null;
+    }
+    const diffDays = Math.round((to.getTime() - from.getTime()) / DAY_MS);
+    return Math.abs(diffDays) > MAX_DATE_CALC_DAYS ? null : diffDays;
+}

package/src/utils/formula/caret.utils.ts

@@ -27,7 +27,7 @@ function getExpressionBeforeCaret(element: HTMLElement): string {
         while (current && current.parentNode !== element) {
             current = current.parentNode;
         }
-        return current && current.parentNode === element ? (current as ChildNode) : null;
+        return current?.parentNode === element ? (current as ChildNode) : null;
     };
 
     if (endContainer === element) {