@servicetitan/dte-pdf-editor 1.0.0

package/src/components/field-type.tsx

@@ -0,0 +1,28 @@
+import { Icon, Text } from '@servicetitan/anvil2';
+import IconDragIndicator from '@servicetitan/anvil2/assets/icons/material/round/drag_indicator.svg';
+import { FC } from 'react';
+
+interface FieldTypeProps {
+    label: string;
+    onDragEnd(): void;
+    onDragStart(): void;
+}
+
+export const FieldType: FC<FieldTypeProps> = ({ label, onDragEnd, onDragStart }) => {
+    return (
+        <div
+            draggable
+            onDragStart={e => {
+                onDragStart();
+                // Mark that we're dragging a new field type, not an existing field
+                e.dataTransfer.effectAllowed = 'copy';
+                e.dataTransfer.setData('text/plain', 'new-field-type');
+            }}
+            onDragEnd={onDragEnd}
+            className="dte-field-type-item border m-t-1"
+        >
+            <Icon svg={IconDragIndicator} size="medium" />
+            <Text size="small">{label}</Text>
+        </div>
+    );
+};

package/src/components/fillable-field-type-list.tsx

@@ -0,0 +1,42 @@
+import { FC, Fragment, useMemo } from 'react';
+import { FILLABLE_FIELD_TYPES } from '../constants';
+import { FieldTypeOption } from '../interface/pdf-editor';
+import { FieldType } from './field-type';
+
+interface FillableFieldTypeListProps {
+    searchText?: string;
+    onDragStart(fieldOption: FieldTypeOption): void;
+    onDragEnd(): void;
+}
+
+export const FillableFieldTypeList: FC<FillableFieldTypeListProps> = ({
+    onDragEnd,
+    onDragStart,
+    searchText,
+}) => {
+    const searchedFieldTypes = useMemo(() => {
+        if (!searchText) {
+            return FILLABLE_FIELD_TYPES;
+        }
+
+        const searchLower = searchText.toLowerCase();
+        return FILLABLE_FIELD_TYPES.filter(({ label }) =>
+            label.toLowerCase().includes(searchLower),
+        );
+    }, [searchText]);
+
+    return (
+        <Fragment>
+            {searchedFieldTypes.map(fieldOption => {
+                return (
+                    <FieldType
+                        key={fieldOption.subType}
+                        label={fieldOption.label}
+                        onDragEnd={onDragEnd}
+                        onDragStart={() => onDragStart(fieldOption)}
+                    />
+                );
+            })}
+        </Fragment>
+    );
+};

package/src/components/pdf-canvas.tsx

@@ -0,0 +1,81 @@
+import { Flex } from '@servicetitan/anvil2';
+import { DragEvent, FC, MouseEvent, ReactNode, RefObject, useState } from 'react';
+import { BASE_PAGE_WIDTH } from '../constants';
+import { PdfField } from '../interface/pdf-editor';
+import { PdfDocumentRenderer } from './pdf-document-renderer';
+import { PdfFieldOverlay } from './pdf-field-overlay';
+
+interface PdfCanvasProps {
+    pdfUrl: string;
+    errorPlaceholder?: ReactNode;
+    loadingPlaceholder?: ReactNode;
+    fields: PdfField[];
+    loading: boolean;
+    selectedField: string | null;
+    pdfContainerRef: RefObject<HTMLDivElement>;
+    pdfWrapperRef: RefObject<HTMLDivElement>;
+    recipientsColors: Record<string, string>;
+    onDragOver(e: DragEvent<HTMLDivElement>): void;
+    onDrop(e: DragEvent<HTMLDivElement>, pageNumber: number): void;
+    onFieldClick(fieldId: string, e: MouseEvent): void;
+    onFieldMove(fieldId: string, newX: number, newY: number, pageNumber: number): void;
+    onFieldResize(fieldId: string, newWidth: number, newHeight: number, pageNumber: number): void;
+    onDeselectField(): void;
+}
+
+export const PdfCanvas: FC<PdfCanvasProps> = ({
+    errorPlaceholder,
+    fields,
+    loading,
+    loadingPlaceholder,
+    onDeselectField,
+    onDragOver,
+    onDrop,
+    onFieldClick,
+    onFieldMove,
+    onFieldResize,
+    pdfContainerRef,
+    pdfUrl,
+    pdfWrapperRef,
+    recipientsColors,
+    selectedField,
+}) => {
+    const [isPdfLoaded, setIsPdfLoaded] = useState<boolean>(false);
+
+    const onDocumentLoadSuccess = (_: number) => {
+        setIsPdfLoaded(true);
+    };
+
+    return (
+        <Flex
+            flex={1}
+            ref={pdfContainerRef}
+            className="dte-pdf-canvas-container"
+            onClick={onDeselectField}
+        >
+            <div ref={pdfWrapperRef} className="dte-pdf-wrapper">
+                <PdfDocumentRenderer
+                    pdfUrl={pdfUrl}
+                    onDrop={onDrop}
+                    loading={loading}
+                    onDragOver={onDragOver}
+                    pageWidth={BASE_PAGE_WIDTH}
+                    errorPlaceholder={errorPlaceholder}
+                    loadingPlaceholder={loadingPlaceholder}
+                    onDocumentLoadSuccess={onDocumentLoadSuccess}
+                />
+                {isPdfLoaded && fields && (
+                    <PdfFieldOverlay
+                        fields={fields}
+                        pdfWrapperRef={pdfWrapperRef}
+                        recipientsColors={recipientsColors}
+                        selectedField={selectedField ?? null}
+                        onFieldClick={onFieldClick ?? (() => {})}
+                        onFieldMove={onFieldMove ?? (() => {})}
+                        onFieldResize={onFieldResize ?? (() => {})}
+                    />
+                )}
+            </div>
+        </Flex>
+    );
+};

package/src/components/pdf-document-renderer.tsx

@@ -0,0 +1,78 @@
+import { DragEvent, FC, ReactNode } from 'react';
+import { Document, Page } from 'react-pdf';
+import 'react-pdf/dist/Page/AnnotationLayer.css';
+import 'react-pdf/dist/Page/TextLayer.css';
+import { usePdfDocumentRenderer } from '../hooks';
+import { initializePdfJsWorker } from '../utils';
+
+initializePdfJsWorker();
+
+interface PdfDocumentRendererProps {
+    pdfUrl: string;
+    pageWidth?: number;
+    loading: boolean;
+    errorPlaceholder?: ReactNode;
+    loadingPlaceholder?: ReactNode;
+    onDocumentLoadSuccess?: (numPages: number) => void;
+    onDragOver?(e: DragEvent<HTMLDivElement>): void;
+    onDrop?(e: DragEvent<HTMLDivElement>, pageNumber: number): void;
+}
+
+export const PdfDocumentRenderer: FC<PdfDocumentRendererProps> = ({
+    errorPlaceholder,
+    loading,
+    loadingPlaceholder,
+    onDocumentLoadSuccess,
+    onDragOver,
+    onDrop,
+    pageWidth,
+    pdfUrl,
+}) => {
+    const { handleDocumentLoadSuccess: handleLoadSuccess, pages } = usePdfDocumentRenderer();
+
+    const handleDocumentLoadSuccess = ({ numPages }: { numPages: number }) => {
+        handleLoadSuccess({ numPages });
+        onDocumentLoadSuccess?.(numPages);
+    };
+
+    const handlePageDrop = (e: DragEvent<HTMLDivElement>, pageNumber: number) => {
+        e.preventDefault();
+        e.stopPropagation();
+        onDrop?.(e, pageNumber);
+    };
+
+    const handlePageDragOver = (e: DragEvent<HTMLDivElement>) => {
+        e.preventDefault();
+        e.stopPropagation();
+        onDragOver?.(e);
+    };
+
+    return (
+        <Document
+            file={pdfUrl}
+            error={errorPlaceholder}
+            loading={loadingPlaceholder}
+            onLoadSuccess={handleDocumentLoadSuccess}
+            noData={loading ? loadingPlaceholder : undefined}
+        >
+            {pages.map(pageNumber => {
+                return (
+                    <div
+                        key={`page_${pageNumber}`}
+                        data-page-number={pageNumber}
+                        className="dte-pdf-document-renderer-page"
+                        onDragOver={handlePageDragOver}
+                        onDrop={e => handlePageDrop(e, pageNumber)}
+                    >
+                        <Page
+                            pageNumber={pageNumber}
+                            width={pageWidth}
+                            renderTextLayer={false}
+                            renderAnnotationLayer={false}
+                        />
+                    </div>
+                );
+            })}
+        </Document>
+    );
+};

package/src/components/pdf-editor.tsx

@@ -0,0 +1,216 @@
+import { Flex } from '@servicetitan/anvil2';
+import { DragEvent, FC, MouseEvent, ReactNode, useMemo, useRef, useState } from 'react';
+import { v4 as uuidv4 } from 'uuid';
+import { FIELD_CONSTANTS } from '../constants';
+
+import {
+    ESignFieldType,
+    FieldTypeEnum,
+    FieldTypeOption,
+    PdfField,
+    SchemaObject,
+} from '../interface/pdf-editor';
+import '../styles/index.css';
+import {
+    calculateDropCoordinates,
+    extractGroupedFieldsFromDataModel,
+    generateESignPath,
+    initializePdfJsWorker,
+    isDragOverCanvas,
+    mapColorsToRecipients,
+} from '../utils';
+import { FieldConfigPanelOverlay } from './field-config-panel-overlay';
+import { FieldSidebar } from './field-sidebar';
+import { PdfCanvas } from './pdf-canvas';
+
+initializePdfJsWorker();
+
+export interface RecipientInfo {
+    id: number;
+    name: string;
+    displayName: string;
+}
+
+interface PdfEditorProps {
+    pdfUrl: string;
+    loading?: boolean;
+    loadingPlaceholder?: ReactNode;
+    errorPlaceholder?: ReactNode;
+    dataModel?: SchemaObject;
+    recipients?: RecipientInfo[];
+    fields?: PdfField[];
+    onFieldsChange(fields: PdfField[]): void;
+}
+
+export const PdfEditor: FC<PdfEditorProps> = ({
+    dataModel,
+    errorPlaceholder,
+    fields = [],
+    loading = false,
+    loadingPlaceholder,
+    onFieldsChange,
+    pdfUrl,
+    recipients = [],
+}) => {
+    const dataModelGroups = useMemo(() => {
+        return dataModel ? extractGroupedFieldsFromDataModel(dataModel) : [];
+    }, [dataModel]);
+    const [draggedFieldOption, setDraggedFieldOption] = useState<FieldTypeOption | null>(null);
+    const [selectedField, setSelectedField] = useState<string | null>(null);
+    const pdfContainerRef = useRef<HTMLDivElement>(null);
+    const pdfWrapperRef = useRef<HTMLDivElement>(null);
+
+    const handleDragStart = (fieldOption: FieldTypeOption) => {
+        setDraggedFieldOption(fieldOption);
+    };
+
+    const handleDragEnd = () => {
+        setDraggedFieldOption(null);
+    };
+
+    const handleDrop = (e: DragEvent<HTMLDivElement>, pageNumber: number) => {
+        e.preventDefault();
+        e.stopPropagation();
+
+        const isExistingField = e.dataTransfer.getData('text/plain') === 'existing-field';
+        if (isExistingField || !draggedFieldOption) {
+            return;
+        }
+
+        const coordinates = calculateDropCoordinates(e, pageNumber, pdfWrapperRef);
+        if (!coordinates) {
+            setDraggedFieldOption(null);
+            return;
+        }
+
+        const newField: PdfField = {
+            id: uuidv4(),
+            type: draggedFieldOption.type,
+            subType: draggedFieldOption.subType,
+            x: coordinates.x,
+            y: coordinates.y,
+            page: pageNumber,
+            label: draggedFieldOption.label,
+            width: FIELD_CONSTANTS.defaultWidth,
+            height: FIELD_CONSTANTS.defaultHeight,
+            path: draggedFieldOption.path,
+        };
+
+        if (draggedFieldOption.type === FieldTypeEnum.eSign) {
+            newField.recipient = recipients[0]?.name ?? '';
+            newField.path = generateESignPath(
+                recipients[0].name!,
+                draggedFieldOption.subType as ESignFieldType,
+            );
+        }
+        if (draggedFieldOption.type === FieldTypeEnum.fillable) {
+            newField.recipient = recipients[0]?.name ?? '';
+            newField.required = false;
+        }
+
+        onFieldsChange([...fields, newField]);
+        setSelectedField(newField.id);
+        setDraggedFieldOption(null);
+    };
+
+    const handleDragOver = (e: DragEvent<HTMLDivElement>) => {
+        if (!draggedFieldOption) {
+            e.dataTransfer.dropEffect = 'none';
+            return;
+        }
+
+        const isOverCanvas = isDragOverCanvas(e, pdfWrapperRef);
+
+        // Only allow a drop if we're over the actual PDF canvas
+        if (isOverCanvas) {
+            e.preventDefault();
+            e.stopPropagation();
+            e.dataTransfer.dropEffect = 'copy';
+        } else {
+            e.dataTransfer.dropEffect = 'none';
+        }
+    };
+
+    const handleFieldClick = (fieldId: string, e: MouseEvent) => {
+        e.stopPropagation();
+        setSelectedField(fieldId);
+    };
+
+    const handleFieldMove = (fieldId: string, newX: number, newY: number, pageNumber: number) => {
+        onFieldsChange(
+            fields.map(f => (f.id === fieldId ? { ...f, x: newX, y: newY, page: pageNumber } : f)),
+        );
+    };
+
+    const handleFieldResize = (
+        fieldId: string,
+        newWidth: number,
+        newHeight: number,
+        pageNumber: number,
+    ) => {
+        onFieldsChange(
+            fields.map(f =>
+                f.id === fieldId
+                    ? { ...f, width: newWidth, height: newHeight, page: pageNumber }
+                    : f,
+            ),
+        );
+    };
+
+    const handleDeleteField = () => {
+        if (selectedField) {
+            onFieldsChange(fields.filter(f => f.id !== selectedField));
+            setSelectedField(null);
+        }
+    };
+
+    const handleFieldConfigChange = (updates: Partial<PdfField>) => {
+        if (selectedField) {
+            onFieldsChange(fields.map(f => (f.id === selectedField ? { ...f, ...updates } : f)));
+        }
+    };
+
+    const selectedFieldData = fields.find(f => f.id === selectedField) ?? null;
+
+    const recipientsColors = mapColorsToRecipients(recipients);
+
+    return (
+        <Flex flex={1} className={`dte-pdf-editor ${loading ? 'skeleton' : ''}`}>
+            <Flex className="dte-pdf-editor-sidebar-container ">
+                <FieldSidebar
+                    dataModelGroups={dataModelGroups}
+                    onDragEnd={handleDragEnd}
+                    onDragStart={handleDragStart}
+                />
+                {selectedFieldData && (
+                    <FieldConfigPanelOverlay
+                        selectedField={selectedFieldData}
+                        onFieldConfigChange={handleFieldConfigChange}
+                        onDeleteField={handleDeleteField}
+                        recipients={recipients}
+                        onDeselectField={() => setSelectedField(null)}
+                    />
+                )}
+            </Flex>
+            <Flex gap={12} flex={1} className="dte-pdf-editor-content-container skeleton-item">
+                <PdfCanvas
+                    pdfUrl={pdfUrl}
+                    fields={fields}
+                    loading={loading}
+                    recipientsColors={recipientsColors}
+                    selectedField={selectedField}
+                    pdfContainerRef={pdfContainerRef}
+                    pdfWrapperRef={pdfWrapperRef}
+                    errorPlaceholder={errorPlaceholder}
+                    loadingPlaceholder={loadingPlaceholder}
+                    onDrop={handleDrop}
+                    onDragOver={handleDragOver}
+                    onFieldClick={handleFieldClick}
+                    onFieldMove={handleFieldMove}
+                    onFieldResize={handleFieldResize}
+                    onDeselectField={() => setSelectedField(null)}
+                />
+            </Flex>
+        </Flex>
+    );
+};

package/src/components/pdf-field-overlay.tsx

@@ -0,0 +1,83 @@
+import { FC, MouseEvent, RefObject } from 'react';
+import { useFieldDrag, useFieldResize } from '../hooks';
+import { FieldTypeEnum, PdfField } from '../interface/pdf-editor';
+import { getPagePosition } from '../utils';
+
+interface PdfFieldOverlayProps {
+    fields: PdfField[];
+    selectedField: string | null;
+    pdfWrapperRef: RefObject<HTMLDivElement>;
+    recipientsColors: Record<string, string>;
+    onFieldClick(fieldId: string, e: MouseEvent): void;
+    onFieldMove(fieldId: string, newX: number, newY: number, pageNumber: number): void;
+    onFieldResize(fieldId: string, newWidth: number, newHeight: number, pageNumber: number): void;
+}
+
+export const PdfFieldOverlay: FC<PdfFieldOverlayProps> = ({
+    fields,
+    onFieldClick,
+    onFieldMove,
+    onFieldResize,
+    pdfWrapperRef,
+    recipientsColors,
+    selectedField,
+}) => {
+    const { draggingFieldIdRef, handleDrag, handleDragEnd, handleDragStart } = useFieldDrag({
+        pdfWrapperRef,
+        onFieldMove,
+    });
+
+    const { handleResizeStart } = useFieldResize({
+        pdfWrapperRef,
+        onFieldResize,
+    });
+
+    return (
+        <div className="dte-pdf-field-overlay skeleton-item">
+            {fields.map(field => {
+                const isSelected = selectedField === field.id;
+                const isDragging = draggingFieldIdRef.current === field.id;
+                const pagePos = getPagePosition(field.page, pdfWrapperRef);
+                const bgColor =
+                    field.recipient && recipientsColors[field.recipient]
+                        ? recipientsColors[field.recipient]
+                        : 'rgba(255, 255, 255, 0.8)';
+
+                return (
+                    <div
+                        key={field.id}
+                        onClick={e => onFieldClick(field.id, e)}
+                        draggable
+                        onDragStart={e => handleDragStart(e, field)}
+                        onDrag={e => handleDrag(e, field)}
+                        onDragEnd={handleDragEnd}
+                        className={`dte-pdf-field ${isSelected ? 'dte-pdf-field-selected' : 'dte-pdf-field-unselected'} ${isDragging ? 'dte-pdf-field-dragging' : ''}`}
+                        style={{
+                            left: `${pagePos.left + field.x}px`,
+                            top: `${pagePos.top + field.y}px`,
+                            width: `${field.width}px`,
+                            height: `${field.height}px`,
+                            backgroundColor: bgColor,
+                        }}
+                    >
+                        <span>
+                            {(field.type === FieldTypeEnum.eSign ||
+                                field.type === FieldTypeEnum.fillable) &&
+                                `${field.label} ${field.required ? '*' : ''}`}
+
+                            {field.path && (
+                                <div className="dte-pdf-field-path">{`{{${field.path}}}`}</div>
+                            )}
+                        </span>
+                        {isSelected && (
+                            <div
+                                className="dte-pdf-field-resize-handle"
+                                onMouseDown={e => handleResizeStart(e, field)}
+                            />
+                        )}
+                    </div>
+                );
+            })}
+        </div>
+    );
+};

package/src/constants/field.constants.ts

@@ -0,0 +1,31 @@
+import { ESignFieldType, FieldTypeEnum, FieldTypeOption } from '../interface/pdf-editor';
+
+export const FIELD_CONSTANTS = {
+    defaultWidth: 200,
+    defaultHeight: 30,
+    minWidth: 50,
+    minHeight: 20,
+    dropOffsetX: 75,
+    dropOffsetY: 15,
+} as const;
+
+export const E_SIGN_FIELD_TYPE_OPTIONS: { name: string; id: ESignFieldType }[] = [
+    { name: 'Signature', id: ESignFieldType.signature },
+    { name: 'Initials', id: ESignFieldType.initials },
+    { name: 'Date Signed', id: ESignFieldType.dateSigned },
+    { name: 'Full Name', id: ESignFieldType.fullName },
+];
+
+export const FILLABLE_FIELD_TYPES: FieldTypeOption[] = [
+    { label: 'Text Field', type: FieldTypeEnum.fillable, subType: 'text' },
+    { label: 'Date Field', type: FieldTypeEnum.fillable, subType: 'date' },
+    { label: 'Checkbox', type: FieldTypeEnum.fillable, subType: 'checkbox' },
+];
+
+export const E_SIGN_FIELD_TYPES: FieldTypeOption[] = [
+    {
+        label: 'E-Sign',
+        type: FieldTypeEnum.eSign,
+        subType: ESignFieldType.signature,
+    },
+];

package/src/constants/index.ts

@@ -0,0 +1,2 @@
+export * from './field.constants';
+export * from './pdf-editor.constants';

package/src/constants/pdf-editor.constants.ts

@@ -0,0 +1 @@
+export const BASE_PAGE_WIDTH = 980;

package/src/hooks/index.ts

@@ -0,0 +1,3 @@
+export * from './useFieldDrag';
+export * from './useFieldResize';
+export * from './usePdfDocumentRenderer';

package/src/hooks/useFieldDrag.ts

@@ -0,0 +1,56 @@
+import { DragEvent, MutableRefObject, RefObject, useRef } from 'react';
+import { PdfField } from '../interface/pdf-editor';
+import { handleFieldDrag, handleFieldDragStart } from '../utils';
+
+interface UseFieldDragOptions {
+    pdfWrapperRef: RefObject<HTMLDivElement>;
+    onFieldMove: (fieldId: string, newX: number, newY: number, pageNumber: number) => void;
+}
+
+interface UseFieldDragReturn {
+    dragOffsetRef: MutableRefObject<{ x: number; y: number; page: number } | null>;
+    draggingFieldIdRef: MutableRefObject<string | null>;
+    handleDragStart: (e: DragEvent<HTMLDivElement>, field: PdfField) => void;
+    handleDrag: (e: DragEvent<HTMLDivElement>, field: PdfField) => void;
+    handleDragEnd: () => void;
+}
+
+/**
+ * Custom hook for handling field drag operations
+ * Manages drag state and coordinates field movement
+ */
+export const useFieldDrag = ({
+    onFieldMove,
+    pdfWrapperRef,
+}: UseFieldDragOptions): UseFieldDragReturn => {
+    const dragOffsetRef = useRef<{ x: number; y: number; page: number } | null>(null);
+    const draggingFieldIdRef = useRef<string | null>(null);
+
+    const handleDragStart = (e: DragEvent<HTMLDivElement>, field: PdfField) => {
+        draggingFieldIdRef.current = field.id;
+
+        const dragOffset = handleFieldDragStart(e, field, pdfWrapperRef);
+        if (dragOffset) {
+            dragOffsetRef.current = dragOffset;
+        }
+    };
+
+    const handleDrag = (e: DragEvent<HTMLDivElement>, field: PdfField) => {
+        if (dragOffsetRef.current) {
+            handleFieldDrag(e, field, dragOffsetRef.current, pdfWrapperRef, onFieldMove);
+        }
+    };
+
+    const handleDragEnd = () => {
+        dragOffsetRef.current = null;
+        draggingFieldIdRef.current = null;
+    };
+
+    return {
+        dragOffsetRef,
+        draggingFieldIdRef,
+        handleDragStart,
+        handleDrag,
+        handleDragEnd,
+    };
+};