@servicetitan/dte-pdf-editor 1.90.0 → 1.92.0

package/src/components/pdf-view/pdf-view.tsx

@@ -1,7 +1,7 @@
-import { Flex } from '@servicetitan/anvil2';
-import { FC, ReactNode, useMemo, useRef, useState } from 'react';
+import { Flex, Text } from '@servicetitan/anvil2';
+import { FC, ReactNode, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { BASE_PAGE_WIDTH } from '../../constants';
-import { useZoom } from '../../hooks';
+import { usePinchZoom, useZoom } from '../../hooks';
 import {
     type DataChangePayload,
     type DataModelValues,
@@ -15,7 +15,11 @@ import {
     mapColorsToRecipients,
     sortFieldsByReadingOrder,
 } from '../../utils';
-import { CanvasControls } from '../pdf-canvas/canvas-controls';
+import {
+    FieldNavigationControls,
+    ZoomControls,
+    ZoomControlsProps,
+} from '../pdf-canvas/canvas-controls';
 import { PdfDocumentRenderer } from '../pdf-canvas/pdf-document-renderer';
 import { PdfViewCalculated } from './pdf-view-calculated';
 import { PdfViewDataModel } from './pdf-view-data-model';
@@ -30,6 +34,10 @@ export interface PdfViewProps {
     viewMode?: PdfViewMode;
     data?: DataModelValues;
     zoomable?: boolean;
+    zoomProps?: {
+        vertical: ZoomControlsProps['vertical'];
+        position: ZoomControlsProps['position'];
+    };
     enableInputNavigation?: boolean;
     pdfUrl: string;
     loading?: boolean;
@@ -74,14 +82,23 @@ export const PdfView: FC<PdfViewProps> = ({
     pdfUrl,
     recipients,
     viewMode,
+    zoomProps,
     zoomable = true,
 }) => {
     const [isPdfLoaded, setIsPdfLoaded] = useState<boolean>(false);
     const [previewData, setPreviewData] = useState<DataModelValues>(data ?? {});
-    const { resetZoom, zoom, zoomIn, zoomOut } = useZoom();
+    const { resetZoom, setZoomValue, zoom, zoomByFactor, zoomIn, zoomOut } = useZoom();
     const activeData = viewMode === 'preview' ? previewData : data;
 
     const pdfWrapperRef = useRef<HTMLDivElement>(null);
+    const navControlsRef = useRef<HTMLDivElement>(null);
+    const contentContainerRef = useRef<HTMLDivElement>(null);
+    usePinchZoom(contentContainerRef, {
+        enabled: zoomable,
+        setZoomValue,
+        zoom,
+        zoomByFactor,
+    });
 
     const onDocumentLoadSuccess = (pageNum: number) => {
         setIsPdfLoaded(true);
@@ -111,7 +128,6 @@ export const PdfView: FC<PdfViewProps> = ({
         [navigableFields],
     );
 
-    // -1 means no field has been navigated to yet, so the first "next" lands on index 0.
     const [currentFieldIndex, setCurrentFieldIndex] = useState(-1);
 
     const handleFieldOverlayFocus = (fieldId: string) => {
@@ -120,115 +136,160 @@ export const PdfView: FC<PdfViewProps> = ({
         }
     };
 
-    const handleFocusField = (fieldId: string) => {
+    const getFieldElement = (fieldId: string) => {
         const root = pdfWrapperRef.current?.getRootNode() as Document | ShadowRoot | undefined;
-        const fieldEl = root?.querySelector<HTMLElement>(`[id="dte-pdf-field-${fieldId}"]`);
-        fieldEl?.scrollIntoView({ behavior: 'smooth', block: 'center' });
-        const focusableElement = fieldEl?.querySelector<HTMLElement>('input, textarea') ?? fieldEl;
-        focusableElement?.focus();
+        return root?.querySelector<HTMLElement>(`[id="dte-pdf-field-${fieldId}"]`) ?? undefined;
+    };
+
+    useLayoutEffect(() => {
+        const field = navigableFields[currentFieldIndex];
+        const navControlsEl = navControlsRef.current;
+        if (!field || !navControlsEl) {
+            return;
+        }
+
+        const fieldEl = getFieldElement(field.id);
+        if (!fieldEl) {
+            return;
+        }
+
+        const containerTop = contentContainerRef.current?.getBoundingClientRect().top ?? 0;
+        navControlsEl.style.top = `${fieldEl.getBoundingClientRect().top - containerTop}px`;
+    }, [currentFieldIndex, navigableFields]);
+
+    const handleFocusField = (fieldId: string) => {
+        const fieldEl = getFieldElement(fieldId);
+        if (fieldEl) {
+            fieldEl.scrollIntoView({ behavior: 'smooth', block: 'center' });
+            const focusableChild = fieldEl.querySelector<HTMLElement>('input, textarea');
+            (focusableChild ?? fieldEl)?.focus();
+        }
     };
 
     const goToField = (index: number) => {
-        let i = index;
-        if (i < 0) {
-            i = 0;
-        } else if (i >= navigableFields.length) {
-            i = navigableFields.length - 1;
+        const fieldIndex = index < 0 || index >= navigableFields.length ? -1 : index;
+        const field = navigableFields[fieldIndex];
+
+        setCurrentFieldIndex(fieldIndex);
+        if (field) {
+            handleFocusField(field.id);
         }
-        const field = navigableFields[i];
+    };
 
-        setCurrentFieldIndex(i);
-        handleFocusField(field.id);
+    const handleNextField = () => {
+        goToField(currentFieldIndex + 1);
     };
 
     const recipientsColors = mapColorsToRecipients(recipients);
-    const hasNavigableFields = navigableFields.length === 0;
+    const hasNavigableFields = navigableFields.length !== 0;
+    const shouldShowFieldNavigation = enableInputNavigation && hasNavigableFields;
+
     return (
         <Flex
-            flex={1}
-            className="dte-pdf-editor-theme dte-pdf-editor-content-container --view-mode"
             direction="column"
+            style={{ position: 'relative', minWidth: 0 }}
+            className="dte-pdf-editor-theme"
+            ref={contentContainerRef}
         >
-            {isPdfLoaded && (
-                <CanvasControls
+            {isPdfLoaded && shouldShowFieldNavigation && (
+                <div ref={navControlsRef} className="dte-pdf-movable-next-button-wrapper">
+                    <FieldNavigationControls
+                        isStarted={currentFieldIndex !== -1}
+                        onNextField={handleNextField}
+                    />
+                </div>
+            )}
+            {isPdfLoaded && zoomable && (
+                <ZoomControls
+                    {...zoomProps}
                     zoom={zoom}
                     onZoomIn={zoomIn}
                     onZoomOut={zoomOut}
-                    zoomable={zoomable}
                     onResetZoom={resetZoom}
-                    enableInputNavigation={enableInputNavigation}
-                    disabledPrev={hasNavigableFields}
-                    disabledNext={hasNavigableFields}
-                    disabledOnFirstField={hasNavigableFields}
-                    disabledOnLastField={hasNavigableFields}
-                    onPrevField={() => goToField(currentFieldIndex - 1)}
-                    onNextField={() => goToField(currentFieldIndex + 1)}
-                    onFirstField={() => goToField(0)}
-                    onLastField={() => goToField(navigableFields.length - 1)}
                 />
             )}
-            <div
-                ref={pdfWrapperRef}
-                className="dte-pdf-wrapper"
-                style={{ width: BASE_PAGE_WIDTH * zoom }}
+            {shouldShowFieldNavigation && (
+                <Flex
+                    justifyContent="space-between"
+                    alignItems="center"
+                    gap={2}
+                    className="dte-pdf-canvas-controls"
+                >
+                    <Text style={{ color: '#ffffff' }}>Review and complete</Text>
+                    <FieldNavigationControls
+                        isStarted={currentFieldIndex !== -1}
+                        onNextField={handleNextField}
+                    />
+                </Flex>
+            )}
+            <Flex
+                flex={1}
+                className="dte-pdf-editor-content-container --view-mode"
+                direction="column"
             >
-                <PdfDocumentRenderer
-                    pdfUrl={pdfUrl}
-                    loading={loading}
-                    pageWidth={BASE_PAGE_WIDTH * zoom}
-                    errorPlaceholder={errorPlaceholder}
-                    loadingPlaceholder={loadingPlaceholder}
-                    onDocumentLoadSuccess={onDocumentLoadSuccess}
-                />
-                {isPdfLoaded && (
-                    <div className="dte-pdf-field-overlay --view-mode">
-                        {fields.map(field => (
-                            <PdfViewFieldContainer
-                                key={field.id}
-                                field={field}
-                                data={viewMode === 'preview' ? previewData : data}
-                                error={errors[field.path!] || ''}
-                                recipientsColors={recipientsColors}
-                                pdfWrapperRef={pdfWrapperRef}
-                                zoom={zoom}
-                                onFocus={handleFieldOverlayFocus}
-                            >
-                                {(field.type === FieldTypeEnum.dataModel ||
-                                    field.type === FieldTypeEnum.forms) && (
-                                    <PdfViewDataModel
-                                        field={field}
-                                        data={viewMode === 'preview' ? previewData : data}
-                                    />
-                                )}
-                                {field.type === FieldTypeEnum.eSign && (
-                                    <PdfViewESign field={field} />
-                                )}
-                                {field.type === FieldTypeEnum.calculated && (
-                                    <PdfViewCalculated
-                                        field={field}
-                                        data={viewMode === 'preview' ? previewData : data}
-                                        holidays={holidays}
-                                        viewMode={viewMode}
-                                    />
-                                )}
-                                {field.type === FieldTypeEnum.fillable && (
-                                    <PdfViewFillable
-                                        data={viewMode === 'preview' ? previewData : data}
-                                        field={field}
-                                        readOnly={makeFillableFieldsReadonly}
-                                        fillingBy={fillingBy}
-                                        viewMode={viewMode}
-                                        onDataChange={handleDataChange}
-                                    />
-                                )}
-                                {field.type === FieldTypeEnum.generic && (
-                                    <PdfViewGeneric field={field} />
-                                )}
-                            </PdfViewFieldContainer>
-                        ))}
-                    </div>
-                )}
-            </div>
+                <div
+                    ref={pdfWrapperRef}
+                    className="dte-pdf-wrapper"
+                    style={{ width: BASE_PAGE_WIDTH * zoom }}
+                >
+                    <PdfDocumentRenderer
+                        pdfUrl={pdfUrl}
+                        loading={loading}
+                        pageWidth={BASE_PAGE_WIDTH * zoom}
+                        errorPlaceholder={errorPlaceholder}
+                        loadingPlaceholder={loadingPlaceholder}
+                        onDocumentLoadSuccess={onDocumentLoadSuccess}
+                    />
+                    {isPdfLoaded && (
+                        <div className="dte-pdf-field-overlay --view-mode">
+                            {fields.map(field => (
+                                <PdfViewFieldContainer
+                                    key={field.id}
+                                    field={field}
+                                    data={viewMode === 'preview' ? previewData : data}
+                                    error={errors[field.path!] || ''}
+                                    recipientsColors={recipientsColors}
+                                    pdfWrapperRef={pdfWrapperRef}
+                                    zoom={zoom}
+                                    onFocus={handleFieldOverlayFocus}
+                                >
+                                    {(field.type === FieldTypeEnum.dataModel ||
+                                        field.type === FieldTypeEnum.forms) && (
+                                        <PdfViewDataModel
+                                            field={field}
+                                            data={viewMode === 'preview' ? previewData : data}
+                                        />
+                                    )}
+                                    {field.type === FieldTypeEnum.eSign && (
+                                        <PdfViewESign field={field} />
+                                    )}
+                                    {field.type === FieldTypeEnum.calculated && (
+                                        <PdfViewCalculated
+                                            field={field}
+                                            data={viewMode === 'preview' ? previewData : data}
+                                            holidays={holidays}
+                                            viewMode={viewMode}
+                                        />
+                                    )}
+                                    {field.type === FieldTypeEnum.fillable && (
+                                        <PdfViewFillable
+                                            data={viewMode === 'preview' ? previewData : data}
+                                            field={field}
+                                            readOnly={makeFillableFieldsReadonly}
+                                            fillingBy={fillingBy}
+                                            viewMode={viewMode}
+                                            onDataChange={handleDataChange}
+                                        />
+                                    )}
+                                    {field.type === FieldTypeEnum.generic && (
+                                        <PdfViewGeneric field={field} />
+                                    )}
+                                </PdfViewFieldContainer>
+                            ))}
+                        </div>
+                    )}
+                </div>
+            </Flex>
         </Flex>
     );
 };

package/src/constants/field.constants.ts

@@ -1,3 +1,17 @@
+import NumbersIcon from '@servicetitan/anvil2/assets/icons/material/round/123.svg';
+import AbcIcon from '@servicetitan/anvil2/assets/icons/material/round/abc.svg';
+import BadgeIcon from '@servicetitan/anvil2/assets/icons/material/round/badge.svg';
+import CalculateIcon from '@servicetitan/anvil2/assets/icons/material/round/calculate.svg';
+import CalendarMonthIcon from '@servicetitan/anvil2/assets/icons/material/round/calendar_month.svg';
+import CheckboxIcon from '@servicetitan/anvil2/assets/icons/material/round/check_box.svg';
+import EventAvailableIcon from '@servicetitan/anvil2/assets/icons/material/round/event_available.svg';
+import GestureIcon from '@servicetitan/anvil2/assets/icons/material/round/gesture.svg';
+import RadioIcon from '@servicetitan/anvil2/assets/icons/material/round/radio_button_checked.svg';
+import ShortTextIcon from '@servicetitan/anvil2/assets/icons/material/round/short_text.svg';
+import TableChartIcon from '@servicetitan/anvil2/assets/icons/material/round/table_chart.svg';
+import TextIcon from '@servicetitan/anvil2/assets/icons/material/round/text_fields.svg';
+import IconAppointmentsIcon from '@servicetitan/anvil2/assets/icons/st/appointments.svg';
+
 import {
     type CalculatedFormatForDate,
     type CalculatedFormatForNumber,
@@ -44,11 +58,11 @@ export const GENERIC_FIELD_DEFAULT_SIZES = {
 } as Record<PdfFieldSubType, { width: number; height: number }>;
 
 export const FILLABLE_FIELD_TYPES: FieldTypeOption[] = [
-    { label: 'Text Field', type: FieldTypeEnum.fillable, subType: 'text' },
-    { label: 'Number Field', type: FieldTypeEnum.fillable, subType: 'number' },
-    { label: 'Date Field', type: FieldTypeEnum.fillable, subType: 'date' },
-    { label: 'Checkbox', type: FieldTypeEnum.fillable, subType: 'checkbox' },
-    { label: 'Radio', type: FieldTypeEnum.fillable, subType: 'radio' },
+    { label: 'Text Field', type: FieldTypeEnum.fillable, subType: 'text', icon: ShortTextIcon },
+    { label: 'Number Field', type: FieldTypeEnum.fillable, subType: 'number', icon: NumbersIcon },
+    { label: 'Date Field', type: FieldTypeEnum.fillable, subType: 'date', icon: CalendarMonthIcon },
+    { label: 'Checkbox', type: FieldTypeEnum.fillable, subType: 'checkbox', icon: CheckboxIcon },
+    { label: 'Radio', type: FieldTypeEnum.fillable, subType: 'radio', icon: RadioIcon },
 ];
 
 export const E_SIGN_FIELD_TYPES: FieldTypeOption[] = [
@@ -56,26 +70,31 @@ export const E_SIGN_FIELD_TYPES: FieldTypeOption[] = [
         label: 'Signature',
         type: FieldTypeEnum.eSign,
         subType: ESignFieldType.signature,
+        icon: GestureIcon,
     },
     {
         label: 'Initials',
         type: FieldTypeEnum.eSign,
         subType: ESignFieldType.initials,
+        icon: AbcIcon,
     },
     {
         label: 'Date Signed',
         type: FieldTypeEnum.eSign,
         subType: ESignFieldType.dateSigned,
+        icon: EventAvailableIcon,
     },
     {
-        label: 'Date Signed Offset',
+        label: 'Calculated Singing Date',
         type: FieldTypeEnum.eSign,
         subType: ESignFieldType.dateSignedOffset,
+        icon: IconAppointmentsIcon,
     },
     {
         label: 'Full Name',
         type: FieldTypeEnum.eSign,
         subType: ESignFieldType.fullName,
+        icon: BadgeIcon,
     },
 ];
 
@@ -83,6 +102,7 @@ export const CALCULATED_FIELD_TYPES: FieldTypeOption[] = [
     {
         label: 'Calculated Field',
         type: FieldTypeEnum.calculated,
+        icon: CalculateIcon,
     },
 ];
 
@@ -91,11 +111,13 @@ export const GENERIC_FIELD_TYPES: FieldTypeOption[] = [
         label: 'Text',
         type: FieldTypeEnum.generic,
         subType: 'text',
+        icon: TextIcon,
     },
     {
         label: 'Table',
         type: FieldTypeEnum.generic,
         subType: 'table',
+        icon: TableChartIcon,
     },
 ];
 

package/src/hooks/index.ts

@@ -6,5 +6,6 @@ export * from './useFormulaEditor';
 export * from './usePdfDocumentRenderer';
 export * from './usePdfFieldDnD';
 export * from './usePdfFieldSelection';
+export * from './usePinchZoom';
 export * from './useToggle';
 export * from './useZoom';

package/src/hooks/usePinchZoom.ts

@@ -0,0 +1,86 @@
+import { RefObject, useEffect, useRef } from 'react';
+import {
+    clampZoom,
+    getPinchZoomValue,
+    getTouchDistance,
+    getWheelZoomFactor,
+} from '../utils';
+
+interface UsePinchZoomOptions {
+    enabled: boolean;
+    zoom: number;
+    setZoomValue(value: number): void;
+    zoomByFactor(factor: number): void;
+}
+
+/**
+ * Trackpad pinch (wheel + ctrlKey) and two-finger mobile pinch on `containerRef`.
+ * Regular two-finger trackpad scroll is left alone so the page can still pan.
+ */
+export const usePinchZoom = (
+    containerRef: RefObject<HTMLElement | null>,
+    { enabled, setZoomValue, zoom, zoomByFactor }: UsePinchZoomOptions,
+) => {
+    const zoomRef = useRef(zoom);
+    zoomRef.current = zoom;
+
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container || !enabled) {
+            return;
+        }
+
+        let pinchStartDistance = 0;
+        let pinchStartZoom = zoomRef.current;
+
+        const handleWheel = (event: WheelEvent) => {
+            if (!event.ctrlKey) {
+                return;
+            }
+
+            event.preventDefault();
+            zoomByFactor(getWheelZoomFactor(event.deltaY));
+        };
+
+        const handleTouchStart = (event: TouchEvent) => {
+            if (event.touches.length !== 2) {
+                return;
+            }
+
+            pinchStartDistance = getTouchDistance(event.touches[0], event.touches[1]);
+            pinchStartZoom = zoomRef.current;
+        };
+
+        const handleTouchMove = (event: TouchEvent) => {
+            if (event.touches.length !== 2 || pinchStartDistance <= 0) {
+                return;
+            }
+
+            event.preventDefault();
+            const currentDistance = getTouchDistance(event.touches[0], event.touches[1]);
+            setZoomValue(
+                clampZoom(getPinchZoomValue(pinchStartZoom, pinchStartDistance, currentDistance)),
+            );
+        };
+
+        const handleTouchEnd = (event: TouchEvent) => {
+            if (event.touches.length < 2) {
+                pinchStartDistance = 0;
+            }
+        };
+
+        container.addEventListener('wheel', handleWheel, { passive: false });
+        container.addEventListener('touchstart', handleTouchStart, { passive: true });
+        container.addEventListener('touchmove', handleTouchMove, { passive: false });
+        container.addEventListener('touchend', handleTouchEnd);
+        container.addEventListener('touchcancel', handleTouchEnd);
+
+        return () => {
+            container.removeEventListener('wheel', handleWheel);
+            container.removeEventListener('touchstart', handleTouchStart);
+            container.removeEventListener('touchmove', handleTouchMove);
+            container.removeEventListener('touchend', handleTouchEnd);
+            container.removeEventListener('touchcancel', handleTouchEnd);
+        };
+    }, [containerRef, enabled, setZoomValue, zoomByFactor]);
+};

package/src/hooks/useZoom.ts

@@ -1,25 +1,37 @@
 import { useCallback, useState } from 'react';
-import { ZOOM_DEFAULT, ZOOM_MAX, ZOOM_MIN, ZOOM_STEP } from '../constants';
+import { ZOOM_DEFAULT, ZOOM_STEP } from '../constants';
+import { clampZoom } from '../utils';
 
 export interface UseZoomReturn {
     zoom: number;
     zoomIn(): void;
     zoomOut(): void;
     resetZoom(): void;
+    setZoomValue(value: number): void;
+    zoomByFactor(factor: number): void;
 }
 
-const clampZoom = (value: number) =>
-    Math.min(ZOOM_MAX, Math.max(ZOOM_MIN, Math.round(value * 100) / 100));
-
 /**
  * Manages a page zoom factor (1 = 100%), clamped to [ZOOM_MIN, ZOOM_MAX] in ZOOM_STEP increments.
  */
 export const useZoom = (initialZoom: number = ZOOM_DEFAULT): UseZoomReturn => {
     const [zoom, setZoom] = useState<number>(initialZoom);
 
-    const zoomIn = useCallback(() => setZoom(prev => clampZoom(prev + ZOOM_STEP)), []);
-    const zoomOut = useCallback(() => setZoom(prev => clampZoom(prev - ZOOM_STEP)), []);
-    const resetZoom = useCallback(() => setZoom(ZOOM_DEFAULT), []);
+    const zoomIn = useCallback(() => {
+        setZoom(prev => clampZoom(prev + ZOOM_STEP));
+    }, []);
+    const zoomOut = useCallback(() => {
+        setZoom(prev => clampZoom(prev - ZOOM_STEP));
+    }, []);
+    const resetZoom = useCallback(() => {
+        setZoom(ZOOM_DEFAULT);
+    }, []);
+    const setZoomValue = useCallback((value: number) => {
+        setZoom(clampZoom(value));
+    }, []);
+    const zoomByFactor = useCallback((factor: number) => {
+        setZoom(prev => clampZoom(prev * factor));
+    }, []);
 
-    return { zoom, zoomIn, zoomOut, resetZoom };
+    return { resetZoom, setZoomValue, zoom, zoomByFactor, zoomIn, zoomOut };
 };

package/src/interface/types.ts

@@ -1,3 +1,5 @@
+import { Svg } from '@servicetitan/anvil2';
+
 export enum FieldTypeEnum {
     dataModel = 'dataModel',
     forms = 'forms',
@@ -164,6 +166,7 @@ export interface FieldTypeOption {
     fieldType?: SchemaFieldType;
     formSnapshot?: FormulaFieldFormSnapshot;
     sampleData?: unknown;
+    icon?: Svg;
 }
 
 export interface DataModelFieldGroup {