@servicetitan/dte-pdf-editor 1.16.0 → 1.18.0

package/src/hooks/useFormulaEditor.ts

@@ -0,0 +1,336 @@
+import {
+    KeyboardEvent as ReactKeyboardEvent,
+    useCallback,
+    useEffect,
+    useMemo,
+    useRef,
+    useState,
+} from 'react';
+import {
+    getCaretExpressionIndex,
+    placeCaretAtEnd,
+    readExpressionFromEditor,
+    renderFormulaHtml,
+    setCaretByExpressionIndex,
+    tokenizeExpression,
+} from '../utils';
+
+export const useFormulaEditor = (params: {
+    currentExpression: string;
+    opened: boolean;
+    pathToLabel: Map<string, string>;
+}) => {
+    const { currentExpression, opened, pathToLabel } = params;
+    const [draftExpression, setDraftExpression] = useState(currentExpression);
+    const [history, setHistory] = useState<string[]>([currentExpression]);
+    const [historyIndex, setHistoryIndex] = useState(0);
+    const [isDirty, setIsDirty] = useState(false);
+    const editorRef = useRef<HTMLDivElement | null>(null);
+    const updateSourceRef = useRef<'editor' | 'state' | null>(null);
+    const pendingCaretRef = useRef<number | null>(null);
+    const lastCaretRef = useRef(0);
+    const historyIndexRef = useRef(0);
+    const historyRef = useRef<string[]>([currentExpression]);
+
+    useEffect(() => {
+        if (opened) {
+            setDraftExpression(currentExpression);
+            setIsDirty(false);
+            setHistory([currentExpression]);
+            setHistoryIndex(0);
+            historyIndexRef.current = 0;
+            historyRef.current = [currentExpression];
+            const editor = editorRef.current;
+            if (editor) {
+                editor.innerHTML = renderFormulaHtml(currentExpression, pathToLabel);
+                placeCaretAtEnd(editor);
+            }
+        }
+    }, [opened, currentExpression, pathToLabel]);
+
+    useEffect(() => {
+        const editor = editorRef.current;
+        if (!editor) {
+            return;
+        }
+        if (updateSourceRef.current === 'editor') {
+            updateSourceRef.current = null;
+            return;
+        }
+        editor.innerHTML = renderFormulaHtml(draftExpression, pathToLabel);
+        if (pendingCaretRef.current !== null) {
+            setCaretByExpressionIndex(editor, pendingCaretRef.current);
+            pendingCaretRef.current = null;
+        } else {
+            placeCaretAtEnd(editor);
+        }
+    }, [draftExpression, pathToLabel]);
+
+    useEffect(() => {
+        historyIndexRef.current = historyIndex;
+        historyRef.current = history;
+    }, [historyIndex, history]);
+
+    const handleEditorInput = useCallback(() => {
+        const editor = editorRef.current;
+        if (!editor) {
+            return;
+        }
+        const nextValue = readExpressionFromEditor(editor);
+        const caretIndex = getCaretExpressionIndex(editor);
+        pendingCaretRef.current = caretIndex;
+        lastCaretRef.current = caretIndex;
+        updateSourceRef.current = 'editor';
+        setDraftExpression(nextValue);
+        setIsDirty(true);
+        const cur = historyIndexRef.current;
+        const hist = historyRef.current;
+        const base = hist.slice(0, cur + 1);
+        if (base[base.length - 1] !== nextValue) {
+            setHistory([...base, nextValue]);
+            setHistoryIndex(base.length);
+        }
+    }, []);
+
+    const getCaretIndexForInsert = useCallback((): number => {
+        const editor = editorRef.current;
+        if (!editor) {
+            return draftExpression.length;
+        }
+        const sel = window.getSelection();
+        if (sel?.rangeCount && editor.contains(sel.getRangeAt(0).startContainer)) {
+            const idx = getCaretExpressionIndex(editor);
+            lastCaretRef.current = idx;
+            return idx;
+        }
+        return lastCaretRef.current;
+    }, [draftExpression.length]);
+
+    const pushHistory = useCallback((nextValue: string, nextCaret: number) => {
+        pendingCaretRef.current = nextCaret;
+        lastCaretRef.current = nextCaret;
+        setDraftExpression(nextValue);
+        setIsDirty(true);
+        const cur = historyIndexRef.current;
+        const hist = historyRef.current;
+        const base = hist.slice(0, cur + 1);
+        if (base[base.length - 1] !== nextValue) {
+            setHistory([...base, nextValue]);
+            setHistoryIndex(base.length);
+        }
+        requestAnimationFrame(() => editorRef.current?.focus());
+    }, []);
+
+    const insertField = useCallback(
+        (path: string) => {
+            const editor = editorRef.current;
+            if (!editor) {
+                return;
+            }
+            const inserted = `${path} `;
+            const caretIndex = getCaretIndexForInsert();
+            const before = draftExpression.slice(0, caretIndex);
+            const after = draftExpression.slice(caretIndex);
+            const nextValue = `${before}${inserted}${after}`;
+            updateSourceRef.current = 'state';
+            pushHistory(nextValue, caretIndex + inserted.length);
+        },
+        [draftExpression, getCaretIndexForInsert, pushHistory],
+    );
+
+    const insertOperator = useCallback(
+        (op: string) => {
+            const editor = editorRef.current;
+            if (!editor) {
+                return;
+            }
+            const caretIndex = getCaretIndexForInsert();
+            const before = draftExpression.slice(0, caretIndex);
+            const after = draftExpression.slice(caretIndex);
+            const inserted = ` ${op} `;
+            const nextValue = `${before}${inserted}${after}`;
+            updateSourceRef.current = 'state';
+            pushHistory(nextValue, caretIndex + inserted.length);
+        },
+        [draftExpression, getCaretIndexForInsert, pushHistory],
+    );
+
+    const removeFieldAtIndex = useCallback(
+        (fieldIndex: number) => {
+            const parts = tokenizeExpression(draftExpression);
+            let currentFieldIndex = -1;
+            let index = 0;
+            let removed = false;
+            const nextValue = parts
+                .map(part => {
+                    if (part.type === 'field') {
+                        currentFieldIndex += 1;
+                        if (currentFieldIndex === fieldIndex) {
+                            removed = true;
+                            index += part.value.length;
+                            return '';
+                        }
+                    }
+                    index += part.value.length;
+                    return part.value;
+                })
+                .join('');
+            if (!removed) {
+                return;
+            }
+            updateSourceRef.current = 'state';
+            const nextCaret = Math.min(index, nextValue.length);
+            pendingCaretRef.current = nextCaret;
+            lastCaretRef.current = nextCaret;
+            setDraftExpression(nextValue);
+            setIsDirty(true);
+            const cur = historyIndexRef.current;
+            const hist = historyRef.current;
+            const base = hist.slice(0, cur + 1);
+            if (base[base.length - 1] !== nextValue) {
+                setHistory([...base, nextValue]);
+                setHistoryIndex(base.length);
+            }
+            requestAnimationFrame(() => editorRef.current?.focus());
+        },
+        [draftExpression],
+    );
+
+    const handleKeyDown = useCallback((e: ReactKeyboardEvent<HTMLDivElement>) => {
+        if (e.ctrlKey || e.metaKey) {
+            const key = e.key.toLowerCase();
+            if (key === 'z') {
+                e.preventDefault();
+                if (historyIndexRef.current > 0) {
+                    const next = historyRef.current[historyIndexRef.current - 1];
+                    updateSourceRef.current = 'state';
+                    pendingCaretRef.current = next.length;
+                    setDraftExpression(next);
+                    setHistoryIndex(historyIndexRef.current - 1);
+                    setIsDirty(true);
+                }
+                return;
+            }
+            if (key === 'y' || (e.shiftKey && key === 'z')) {
+                e.preventDefault();
+                const cur = historyIndexRef.current;
+                const hist = historyRef.current;
+                if (cur < hist.length - 1) {
+                    const next = hist[cur + 1];
+                    updateSourceRef.current = 'state';
+                    pendingCaretRef.current = next.length;
+                    setDraftExpression(next);
+                    setHistoryIndex(cur + 1);
+                    setIsDirty(true);
+                }
+                return;
+            }
+        }
+        const allowed = new Set([
+            '+',
+            '-',
+            '*',
+            '/',
+            '(',
+            ')',
+            '0',
+            '1',
+            '2',
+            '3',
+            '4',
+            '5',
+            '6',
+            '7',
+            '8',
+            '9',
+            '.',
+            'Backspace',
+            'Delete',
+            'ArrowLeft',
+            'ArrowRight',
+            'ArrowUp',
+            'ArrowDown',
+            'Home',
+            'End',
+            'Tab',
+            ' ',
+        ]);
+        if (!allowed.has(e.key)) {
+            e.preventDefault();
+        }
+    }, []);
+
+    const handlePaste = useCallback(
+        (text: string) => {
+            if (!text?.trim()) {
+                return;
+            }
+            const parts = tokenizeExpression(text).filter(
+                p => p.type !== 'text' || p.value.trim() !== '',
+            );
+            const sanitized = parts.map(p => p.value).join('');
+            if (!sanitized) {
+                return;
+            }
+            const editor = editorRef.current;
+            if (!editor) {
+                return;
+            }
+            const caretIndex = getCaretIndexForInsert();
+            const before = draftExpression.slice(0, caretIndex);
+            const after = draftExpression.slice(caretIndex);
+            const nextValue = `${before}${sanitized}${after}`;
+            updateSourceRef.current = 'state';
+            pushHistory(nextValue, caretIndex + sanitized.length);
+        },
+        [draftExpression, getCaretIndexForInsert, pushHistory],
+    );
+
+    const undo = useCallback(() => {
+        if (historyIndexRef.current > 0) {
+            const next = historyRef.current[historyIndexRef.current - 1];
+            updateSourceRef.current = 'state';
+            pendingCaretRef.current = next.length;
+            setDraftExpression(next);
+            setHistoryIndex(historyIndexRef.current - 1);
+            setIsDirty(true);
+            requestAnimationFrame(() => editorRef.current?.focus());
+        }
+    }, []);
+
+    const redo = useCallback(() => {
+        const cur = historyIndexRef.current;
+        const hist = historyRef.current;
+        if (cur < hist.length - 1) {
+            const next = hist[cur + 1];
+            updateSourceRef.current = 'state';
+            pendingCaretRef.current = next.length;
+            setDraftExpression(next);
+            setHistoryIndex(cur + 1);
+            setIsDirty(true);
+            requestAnimationFrame(() => editorRef.current?.focus());
+        }
+    }, []);
+
+    const selectedFieldPaths = useMemo(() => {
+        const parts = tokenizeExpression(draftExpression);
+        return new Set(parts.filter(p => p.type === 'field').map(p => p.value));
+    }, [draftExpression]);
+
+    return {
+        draftExpression,
+        editorRef,
+        isDirty,
+        canUndo: historyIndex > 0,
+        canRedo: historyIndex < history.length - 1,
+        undo,
+        redo,
+        handleEditorInput,
+        handleKeyDown,
+        handlePaste,
+        insertField,
+        insertOperator,
+        removeFieldAtIndex,
+        selectedFieldPaths,
+    };
+};

package/src/hooks/usePdfFieldDnD.ts

@@ -1,4 +1,4 @@
-import { DragEvent, RefObject, useState } from 'react';
+import { DragEvent, RefObject, useCallback, useRef, useState } from 'react';
 import { v4 as uuidv4 } from 'uuid';
 import { FIELD_CONSTANTS, FILLABLE_FIELD_DEFAULT_SIZES } from '../constants';
 import {
@@ -15,6 +15,8 @@ import {
     isDragOverCanvas,
 } from '../utils';
 
+const DRAG_OVER_THROTTLE_MS = 32; // ~30fps for drop effect updates
+
 interface UsePdfFieldDnDProps {
     fields: PdfField[];
     recipients: RecipientInfo[];
@@ -31,29 +33,45 @@ export const usePdfFieldDnD = ({
     recipients,
 }: UsePdfFieldDnDProps) => {
     const [draggedFieldOption, setDraggedFieldOption] = useState<FieldTypeOption | null>(null);
+    const lastDragOverTimeRef = useRef(0);
+    const lastDropEffectRef = useRef<'copy' | 'none'>('none');
 
     const handleDragStart = (fieldOption: FieldTypeOption) => {
         setDraggedFieldOption(fieldOption);
+        lastDragOverTimeRef.current = 0;
     };
 
     const handleDragEnd = () => {
         setDraggedFieldOption(null);
     };
 
-    const handleDragOver = (e: DragEvent<HTMLDivElement>) => {
-        if (!draggedFieldOption) {
-            e.dataTransfer.dropEffect = 'none';
-            return;
-        }
+    const handleDragOver = useCallback(
+        (e: DragEvent<HTMLDivElement>) => {
+            if (!draggedFieldOption) {
+                e.dataTransfer.dropEffect = 'none';
+                return;
+            }
 
-        if (isDragOverCanvas(e, pdfWrapperRef)) {
-            e.preventDefault();
-            e.stopPropagation();
-            e.dataTransfer.dropEffect = 'copy';
-        } else {
-            e.dataTransfer.dropEffect = 'none';
-        }
-    };
+            const now = Date.now();
+            if (now - lastDragOverTimeRef.current < DRAG_OVER_THROTTLE_MS) {
+                e.preventDefault();
+                e.dataTransfer.dropEffect = lastDropEffectRef.current;
+                return;
+            }
+            lastDragOverTimeRef.current = now;
+
+            if (isDragOverCanvas(e, pdfWrapperRef)) {
+                e.preventDefault();
+                e.stopPropagation();
+                e.dataTransfer.dropEffect = 'copy';
+                lastDropEffectRef.current = 'copy';
+            } else {
+                e.dataTransfer.dropEffect = 'none';
+                lastDropEffectRef.current = 'none';
+            }
+        },
+        [draggedFieldOption, pdfWrapperRef],
+    );
 
     const handleDrop = (e: DragEvent<HTMLDivElement>, pageNumber: number) => {
         e.preventDefault();
@@ -104,6 +122,10 @@ export const usePdfFieldDnD = ({
             }
         }
 
+        if (newField.type === FieldTypeEnum.calculated) {
+            newField.path = newField.id;
+        }
+
         onFieldsChange([...fields, newField]);
         onSelectField(newField.id);
         setDraggedFieldOption(null);

package/src/interface/types.ts

@@ -2,6 +2,7 @@ export enum FieldTypeEnum {
     dataModel = 'dataModel',
     eSign = 'eSign',
     fillable = 'fillable',
+    calculated = 'calculated',
 }
 
 export enum ESignFieldType {
@@ -13,10 +14,12 @@ export enum ESignFieldType {
 
 export type FillableFieldType = 'text' | 'date' | 'checkbox' | 'radio' | 'number';
 
+export type PdfFieldSubType = FillableFieldType | ESignFieldType;
+
 export interface PdfField {
     id: string;
     type: FieldTypeEnum;
-    subType?: FillableFieldType | ESignFieldType;
+    subType?: PdfFieldSubType;
     x: number;
     y: number;
     page: number;
@@ -27,12 +30,14 @@ export interface PdfField {
     path?: string;
     recipient?: string;
     description?: string;
+    formula?: StructuredFormula;
+    formulaFormat?: CalculatedFieldFormat;
 }
 
 export interface FieldTypeOption {
     label: string;
     type: FieldTypeEnum;
-    subType?: FillableFieldType | ESignFieldType;
+    subType?: PdfFieldSubType;
     path?: string;
 }
 
@@ -41,11 +46,42 @@ export interface DataModelFieldGroup {
     fields: FieldTypeOption[];
 }
 
+/** Supported formula operators */
+export const FORMULA_OPERATORS = ['+', '-', '*', '/'];
+export type FormulaOperator = (typeof FORMULA_OPERATORS)[number];
+
+/** Single token in a structured formula (number, operator, paren, or field reference) */
+export type FormulaToken =
+    | { type: 'number'; value: string }
+    | { type: 'operator'; value: FormulaOperator }
+    | { type: 'lparen'; value: '(' }
+    | { type: 'rparen'; value: ')' }
+    | { type: 'field'; path: string; label: string };
+
+/** Structured formula representation (AST-like token list) for validation and safe editing */
+export interface StructuredFormula {
+    tokens: FormulaToken[];
+}
+
+/** Format options for a calculated field result (display and rounding) */
+export interface CalculatedFieldFormat {
+    resultType: 'number' | 'currency' | 'percent';
+    thousandsSeparator: boolean;
+    decimals: number;
+    roundingMode: 'round' | 'floor' | 'ceil';
+    decimalSeparatorEnabled: boolean;
+    decimalSeparator: '.' | ',';
+    prefixText: string;
+    postfixText: string;
+}
+
 export interface SchemaFieldBaseOptions {
     placeholder?: any;
     description?: any;
     sampleData?: any;
     showInEditor?: boolean;
+    useInCalculatedFields?: boolean;
+    useInConditionals?: boolean;
     isHighlighted?: boolean;
 }