@servicetitan/dte-pdf-editor 1.16.0 → 1.18.0

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

@@ -0,0 +1,159 @@
+import {
+    DataModelValues,
+    FormulaOperator,
+    FormulaToken,
+    StructuredFormula,
+} from '../../interface/types';
+import { resolvePdfDataValues } from '../data-model';
+
+/**
+ * Convert formula operand to number. Merge tags and fillable only ever give:
+ * empty '', a number, or a string number (e.g. '1.2'). Only those are converted to number for calculation.
+ */
+export function valueToNumber(raw: unknown): number {
+    if (raw === null || raw === undefined) {
+        return 0;
+    }
+    if (typeof raw === 'number' && !Number.isNaN(raw)) {
+        return raw;
+    }
+    if (typeof raw !== 'string') {
+        return 0;
+    }
+    const s = raw.trim();
+    if (s === '') {
+        return 0;
+    }
+    const n = Number(s);
+    return Number.isNaN(n) ? 0 : n;
+}
+
+type ResolvedToken =
+    | { type: 'number'; value: number }
+    | { type: 'operator'; value: FormulaOperator }
+    | { type: 'lparen'; value: '(' }
+    | { type: 'rparen'; value: ')' };
+
+function resolveTokens(
+    formula: StructuredFormula,
+    data: DataModelValues | undefined,
+): ResolvedToken[] {
+    return formula.tokens.map((t: FormulaToken): ResolvedToken => {
+        if (t.type === 'field') {
+            const raw = resolvePdfDataValues(data, t.path);
+            return { type: 'number', value: valueToNumber(raw) };
+        }
+        if (t.type === 'number') {
+            return { type: 'number', value: valueToNumber(t.value) };
+        }
+        return t as ResolvedToken;
+    });
+}
+
+function applyOp(a: number, op: FormulaOperator, b: number): number {
+    switch (op) {
+        case '+':
+            return a + b;
+        case '-':
+            return a - b;
+        case '*':
+            return a * b;
+        case '/':
+            return b === 0 ? 0 : a / b;
+        default:
+            return 0;
+    }
+}
+
+/** Find the index of the matching closing paren for an open paren at openIndex. */
+function findMatchingParen(tokens: ResolvedToken[], openIndex: number): number {
+    let balance = 1;
+    for (let i = openIndex + 1; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t.type === 'lparen') {
+            balance++;
+        } else if (t.type === 'rparen') {
+            balance--;
+            if (balance === 0) {
+                return i;
+            }
+        }
+    }
+    return -1;
+}
+
+/** Evaluate a flat list of numbers and * / + - (no parentheses). */
+function evalFlat(tokens: ResolvedToken[]): number {
+    const list = [...tokens];
+    // First pass: * and /
+    for (let i = 1; i < list.length - 1; ) {
+        const t = list[i];
+        if (t.type === 'operator' && (t.value === '*' || t.value === '/')) {
+            const a = (list[i - 1] as { type: 'number'; value: number }).value;
+            const b = (list[i + 1] as { type: 'number'; value: number }).value;
+            const result = applyOp(a, t.value, b);
+            list.splice(i - 1, 3, { type: 'number', value: result });
+            continue;
+        }
+        i += 2;
+    }
+    // Second pass: + and -
+    for (let i = 1; i < list.length - 1; ) {
+        const t = list[i];
+        if (t.type === 'operator' && (t.value === '+' || t.value === '-')) {
+            const a = (list[i - 1] as { type: 'number'; value: number }).value;
+            const b = (list[i + 1] as { type: 'number'; value: number }).value;
+            const result = applyOp(a, t.value, b);
+            list.splice(i - 1, 3, { type: 'number', value: result });
+            continue;
+        }
+        i += 2;
+    }
+    const single = list[0];
+    return single?.type === 'number' ? single.value : 0;
+}
+
+function evalResolvedTokens(tokens: ResolvedToken[]): number {
+    if (tokens.length === 0) {
+        return 0;
+    }
+    if (tokens.length === 1 && tokens[0].type === 'number') {
+        return tokens[0].value;
+    }
+
+    const list = [...tokens];
+
+    // Resolve innermost parentheses first
+    let idx = 0;
+    while (idx < list.length) {
+        if (list[idx].type === 'lparen') {
+            const close = findMatchingParen(list, idx);
+            if (close === -1) {
+                break;
+            }
+            const inner = list.slice(idx + 1, close);
+            const value = evalResolvedTokens(inner);
+            list.splice(idx, close - idx + 1, { type: 'number', value });
+            continue;
+        }
+        idx++;
+    }
+
+    return evalFlat(list);
+}
+
+/**
+ * Evaluate a structured formula with the given data.
+ * Field tokens are resolved via resolvePdfDataValues; string values are converted to number.
+ * Supports +, -, *, / and parentheses. Returns 0 when formula is empty or invalid.
+ */
+export function evaluateFormula(
+    formula: StructuredFormula | undefined | null,
+    data: DataModelValues | undefined,
+): number {
+    if (!formula?.tokens?.length) {
+        return 0;
+    }
+    const resolved = resolveTokens(formula, data);
+    return evalResolvedTokens(resolved);
+}

package/src/utils/formula/expression.utils.ts

@@ -0,0 +1,99 @@
+import { FormulaToken, StructuredFormula } from '../../interface/types';
+
+/**
+ * Convert StructuredFormula tokens to an editable expression string.
+ * Uses field path as the identifier so parsing is unambiguous.
+ */
+export function tokensToExpression(formula: StructuredFormula | undefined): string {
+    if (!formula?.tokens?.length) {
+        return '';
+    }
+    return formula.tokens
+        .map(t => {
+            if (t.type === 'field') {
+                return t.path;
+            }
+            return (t as { value: string }).value;
+        })
+        .join(' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+
+/** Token from tokenizing an expression string (before resolving to FormulaToken) */
+export interface ExpressionPart {
+    type: 'field' | 'number' | 'operator' | 'paren' | 'text';
+    value: string;
+}
+
+// Field paths may contain hyphens (e.g. fillable_recipient_uuid with UUIDs)
+const EXPRESSION_REGEX = /[A-Za-z_][A-Za-z0-9_.-]*|\d+(?:\.\d+)?|[()+\-*/]|\s+|./g;
+
+export function tokenizeExpression(expression: string): ExpressionPart[] {
+    const tokens: ExpressionPart[] = [];
+    let match: RegExpExecArray | null;
+    while ((match = EXPRESSION_REGEX.exec(expression)) !== null) {
+        const value = match[0];
+        if (/^[A-Za-z_]/.test(value)) {
+            tokens.push({ type: 'field', value });
+        } else if (/^\d/.test(value)) {
+            tokens.push({ type: 'number', value });
+        } else if (/^[()+\-*/]$/.test(value)) {
+            tokens.push({ type: value === '(' || value === ')' ? 'paren' : 'operator', value });
+        } else {
+            tokens.push({ type: 'text', value });
+        }
+    }
+    return tokens;
+}
+
+/**
+ * Parse an expression string into FormulaToken[] using valid paths and path->label map.
+ * Invalid or unknown identifiers are skipped (or could be left as placeholder); only known paths become field tokens.
+ */
+export function parseExpression(
+    expression: string,
+    validPaths: Set<string>,
+    pathToLabel: Map<string, string>,
+): FormulaToken[] {
+    const parts = tokenizeExpression(expression).filter(
+        p => p.type !== 'text' || p.value.trim() !== '',
+    );
+    const tokens: FormulaToken[] = [];
+
+    for (const part of parts) {
+        if (part.type === 'text') {
+            continue;
+        }
+        if (part.type === 'field') {
+            if (validPaths.has(part.value)) {
+                tokens.push({
+                    type: 'field',
+                    path: part.value,
+                    label: pathToLabel.get(part.value) ?? part.value,
+                });
+            }
+            continue;
+        }
+        if (part.type === 'number') {
+            tokens.push({ type: 'number', value: part.value });
+            continue;
+        }
+        if (part.type === 'operator') {
+            tokens.push({
+                type: 'operator',
+                value: part.value as '+' | '-' | '*' | '/',
+            });
+            continue;
+        }
+        if (part.type === 'paren') {
+            tokens.push(
+                part.value === '('
+                    ? { type: 'lparen', value: '(' }
+                    : { type: 'rparen', value: ')' },
+            );
+        }
+    }
+
+    return tokens;
+}

package/src/utils/formula/format-calculated-result.utils.ts

@@ -0,0 +1,79 @@
+import { CalculatedFieldFormat } from '../../interface/types';
+
+function roundValue(
+    value: number,
+    decimals: number,
+    mode: CalculatedFieldFormat['roundingMode'],
+): number {
+    const factor = 10 ** decimals;
+    const scaled = value * factor;
+    switch (mode) {
+        case 'floor':
+            return Math.floor(scaled) / factor;
+        case 'ceil':
+            return Math.ceil(scaled) / factor;
+        default:
+            return Math.round(scaled) / factor;
+    }
+}
+
+function formatIntegerPart(
+    s: string,
+    thousandsSeparator: boolean,
+    decimalSeparator: '.' | ',',
+): string {
+    if (!thousandsSeparator) {
+        return s;
+    }
+    const sep = decimalSeparator === ',' ? '.' : ','; // opposite for thousands
+    const parts: string[] = [];
+    let i = s.length;
+    while (i > 0) {
+        const start = Math.max(0, i - 3);
+        parts.unshift(s.slice(start, i));
+        i = start;
+    }
+    return parts.join(sep);
+}
+
+/**
+ * Format a calculated formula result for display using advanced settings.
+ * Applies rounding, decimal places, thousands/decimal separators, result type (number/currency/percent), and prefix/postfix.
+ */
+export function formatCalculatedResult(
+    value: number,
+    format: CalculatedFieldFormat | undefined,
+): string {
+    if (format == null) {
+        return String(value);
+    }
+
+    const {
+        decimalSeparator,
+        decimalSeparatorEnabled,
+        decimals,
+        postfixText,
+        prefixText,
+        resultType,
+        roundingMode,
+        thousandsSeparator,
+    } = format;
+
+    let num = value;
+    if (resultType === 'percent') {
+        num = value * 100;
+    }
+
+    const rounded = roundValue(num, decimals, roundingMode);
+    const fixed = rounded.toFixed(decimals);
+    const [intPart, decPart] = fixed.split('.');
+
+    const decimalSep = decimalSeparatorEnabled ? decimalSeparator : '.';
+    const intFormatted = formatIntegerPart(intPart, thousandsSeparator, decimalSep);
+    const decSuffix = decimals > 0 ? decimalSep + (decPart ?? '') : '';
+
+    const numberStr = intFormatted + decSuffix;
+    const suffix = resultType === 'percent' ? '%' : '';
+
+    return `${prefixText}${numberStr}${suffix}${postfixText}`;
+}

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

@@ -0,0 +1,2 @@
+export type { FormulaOperator, FormulaToken, StructuredFormula } from '../../interface/types';
+export { FORMULA_OPERATORS } from '../../interface/types';

package/src/utils/formula/index.ts

@@ -0,0 +1,10 @@
+export * from './caret.utils';
+export * from './dom.utils';
+export * from './evaluate-formula.utils';
+export * from './expression.utils';
+export * from './format-calculated-result.utils';
+export * from './formula-types';
+export * from './referenced-paths.utils';
+export * from './render-formula.utils';
+export * from './serialize-formula.utils';
+export * from './validate-formula.utils';

package/src/utils/formula/referenced-paths.utils.ts

@@ -0,0 +1,18 @@
+import { StructuredFormula } from '../../interface/types';
+
+/**
+ * Returns the set of data model field paths referenced in the formula.
+ * Used for recalculation scope: only these fields should trigger formula updates.
+ */
+export function getReferencedPaths(formula: StructuredFormula | undefined | null): string[] {
+    if (!formula?.tokens?.length) {
+        return [];
+    }
+    const paths: string[] = [];
+    for (const token of formula.tokens) {
+        if (token.type === 'field') {
+            paths.push(token.path);
+        }
+    }
+    return paths;
+}

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

@@ -0,0 +1,40 @@
+import { FormulaToken } from '../../interface/types';
+import { escapeHtml } from './dom.utils';
+import { tokenizeExpression } from './expression.utils';
+
+/**
+ * Renders formula tokens to HTML for the read-only preview (e.g. formula box).
+ * Uses the same token classes as the modal (dte-formula-token, dte-formula-token-field, etc.).
+ */
+export function renderFormulaPreviewHtml(tokens: FormulaToken[]): string {
+    if (!tokens?.length) {
+        return '';
+    }
+    return tokens
+        .map(token => {
+            const type = token.type;
+            const text = type === 'field' ? token.label : (token as { value: string }).value;
+            const escaped = escapeHtml(text).replace(/ /g, ' ');
+            return `<span class="dte-formula-token dte-formula-token-${type}">${escaped}</span>`;
+        })
+        .join('');
+}
+
+export function renderFormulaHtml(expression: string, labelMap: Map<string, string>): string {
+    if (!expression.trim()) {
+        return '';
+    }
+    const parts = tokenizeExpression(expression);
+    let fieldIndex = 0;
+    return parts
+        .map(part => {
+            if (part.type === 'field') {
+                const displayValue = labelMap.get(part.value) ?? part.value;
+                const currentIndex = fieldIndex;
+                fieldIndex += 1;
+                return `<span class="dte-formula-chip" contenteditable="false" data-field="${escapeHtml(part.value)}" data-field-index="${currentIndex}" draggable="true"><span class="dte-formula-chip-label">${escapeHtml(displayValue)}</span><span class="dte-formula-chip-remove" data-field-remove="true" role="button" aria-label="Remove field">&times;</span></span>`;
+            }
+            return `<span>${escapeHtml(part.value).replace(/ /g, '&nbsp;')}</span>`;
+        })
+        .join('');
+}

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

@@ -0,0 +1,40 @@
+import { StructuredFormula } from '../../interface/types';
+
+const SERIALIZATION_VERSION = 1;
+
+export interface SerializedFormula {
+    v: number;
+    tokens: StructuredFormula['tokens'];
+}
+
+/**
+ * Serialize structured formula for persistence (e.g. to JSON in store).
+ */
+export function serializeFormula(formula: StructuredFormula): string {
+    const payload: SerializedFormula = {
+        v: SERIALIZATION_VERSION,
+        tokens: formula.tokens,
+    };
+    return JSON.stringify(payload);
+}
+
+/**
+ * Deserialize formula from persisted string. Returns null if invalid.
+ */
+export function deserializeFormula(json: string): StructuredFormula | null {
+    if (!json || typeof json !== 'string') {
+        return null;
+    }
+    try {
+        const payload = JSON.parse(json) as SerializedFormula;
+        if (payload?.v !== SERIALIZATION_VERSION || !Array.isArray(payload.tokens)) {
+            return null;
+        }
+        if (payload.tokens.length === 0) {
+            return { tokens: [] };
+        }
+        return { tokens: payload.tokens };
+    } catch {
+        return null;
+    }
+}

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

@@ -0,0 +1,94 @@
+import {
+    FormulaToken,
+    FORMULA_OPERATORS,
+    StructuredFormula,
+} from '../../interface/types';
+
+export interface FormulaValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+
+const OPERATOR_SET = new Set<string>(FORMULA_OPERATORS);
+
+function isOperatorToken(t: FormulaToken): t is FormulaToken & { type: 'operator' } {
+    return t.type === 'operator';
+}
+
+function isOperandToken(t: FormulaToken): boolean {
+    return t.type === 'number' || t.type === 'field';
+}
+
+/**
+ * Validates a structured formula.
+ * Rules: not empty, valid operator placement, balanced parentheses, supported operators only, all field paths exist.
+ */
+export function validateFormula(
+    formula: StructuredFormula | undefined | null,
+    validPaths: Set<string>,
+): FormulaValidationResult {
+    const errors: string[] = [];
+
+    if (!formula?.tokens?.length) {
+        return { valid: false, errors: ['Formula cannot be empty'] };
+    }
+
+    const tokens = formula.tokens;
+    let parenBalance = 0;
+
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        const prev = tokens[i - 1];
+        const next = tokens[i + 1];
+
+        if (t.type === 'lparen') {
+            parenBalance++;
+            if (prev != null && isOperandToken(prev)) {
+                errors.push('Operator required before opening parenthesis');
+            }
+        } else if (t.type === 'rparen') {
+            parenBalance--;
+            if (parenBalance < 0) {
+                errors.push('Unbalanced parentheses');
+            }
+            if (prev != null && isOperatorToken(prev)) {
+                errors.push('Operand required before closing parenthesis');
+            }
+        } else if (t.type === 'operator') {
+            if (prev == null || next == null) {
+                errors.push('Operator must be between two operands or expressions');
+            } else if (prev.type === 'operator' || prev.type === 'lparen') {
+                errors.push('Operand required before operator');
+            } else if (next.type === 'operator' || next.type === 'rparen') {
+                errors.push('Operand required after operator');
+            }
+        } else if (t.type === 'field') {
+            if (!validPaths.has(t.path)) {
+                errors.push(`Unknown field: "${t.label}" (path: ${t.path})`);
+            }
+        } else if (t.type === 'number') {
+            const num = parseFloat(t.value);
+            if (Number.isNaN(num)) {
+                errors.push(`Invalid number: "${t.value}"`);
+            }
+        }
+    }
+
+    if (parenBalance !== 0) {
+        errors.push('Unbalanced parentheses');
+    }
+
+    const first = tokens[0];
+    const last = tokens[tokens.length - 1];
+    if (first && (first.type === 'operator' || first.type === 'rparen')) {
+        errors.push('Formula must start with an operand or opening parenthesis');
+    }
+    if (last && (last.type === 'operator' || last.type === 'lparen')) {
+        errors.push('Formula must end with an operand or closing parenthesis');
+    }
+
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/src/utils/index.ts

@@ -1,5 +1,6 @@
 export * from './field';
 export * from './pdf';
 export * from './data-model';
+export * from './formula';
 export * from './path';
 export * from './recipients';