@servicetitan/dte-pdf-editor 1.16.0 → 1.18.0

package/src/components/field-config-panel/result-type-selector.tsx

@@ -0,0 +1,34 @@
+import { Button, Flex, Text } from '@servicetitan/anvil2';
+import { FC, Fragment } from 'react';
+import { CalculatedFieldFormat } from '../../interface/types';
+
+interface ResultTypeSelectorProps {
+    format: CalculatedFieldFormat;
+    onChange: (nextType: CalculatedFieldFormat['resultType']) => void;
+}
+
+const RESULT_TYPE_OPTIONS: { label: string; value: CalculatedFieldFormat['resultType'] }[] = [
+    { label: 'Number', value: 'number' },
+    { label: 'Currency', value: 'currency' },
+    { label: 'Percent', value: 'percent' },
+];
+
+export const ResultTypeSelector: FC<ResultTypeSelectorProps> = ({ format, onChange }) => (
+    <Fragment>
+        <Text variant="body" size="small">
+            Result type
+        </Text>
+        <Flex gap={2}>
+            {RESULT_TYPE_OPTIONS.map(({ label, value }) => (
+                <Button
+                    key={value}
+                    appearance={format.resultType === value ? 'primary' : 'secondary'}
+                    size="small"
+                    onClick={() => onChange(value)}
+                >
+                    {label}
+                </Button>
+            ))}
+        </Flex>
+    </Fragment>
+);

package/src/components/field-sidebar/calculated-field-type-list.tsx

@@ -0,0 +1,29 @@
+import { FC, Fragment } from 'react';
+import { CALCULATED_FIELD_TYPES } from '../../constants';
+import { FieldTypeOption } from '../../interface/types';
+import { FieldType } from './field-type';
+
+interface CalculatedFieldTypeListProps {
+    onDragStart(fieldOption: FieldTypeOption): void;
+    onDragEnd(): void;
+}
+export const CalculatedFieldTypeList: FC<CalculatedFieldTypeListProps> = ({
+    onDragEnd,
+    onDragStart,
+}) => {
+    return (
+        <Fragment>
+            {CALCULATED_FIELD_TYPES.map(fieldOption => {
+                const key = `${fieldOption.type}-${fieldOption.path ?? fieldOption.label}`;
+                return (
+                    <FieldType
+                        key={key}
+                        label={fieldOption.label}
+                        onDragEnd={onDragEnd}
+                        onDragStart={() => onDragStart(fieldOption)}
+                    />
+                );
+            })}
+        </Fragment>
+    );
+};

package/src/components/field-sidebar/data-model-field-type-list.tsx

@@ -1,10 +1,9 @@
-import { Flex, Text } from '@servicetitan/anvil2';
-import { FC, Fragment, useMemo } from 'react';
+import { Flex, SearchField, Text } from '@servicetitan/anvil2';
+import { FC, Fragment, useMemo, useState } from 'react';
 import { DataModelFieldGroup, FieldTypeOption } from '../../interface/types';
 import { FieldType } from './field-type';
 
 interface DataModelFieldTypeListProps {
-    searchText?: string;
     dataModelGroups?: DataModelFieldGroup[];
     onDragStart(fieldOption: FieldTypeOption): void;
     onDragEnd(): void;
@@ -14,8 +13,9 @@ export const DataModelFieldTypeList: FC<DataModelFieldTypeListProps> = ({
     dataModelGroups = [],
     onDragEnd,
     onDragStart,
-    searchText,
 }) => {
+    const [searchText, setSearchText] = useState('');
+
     const searchedFieldGroups = useMemo(() => {
         if (!searchText) {
             return dataModelGroups;
@@ -33,6 +33,12 @@ export const DataModelFieldTypeList: FC<DataModelFieldTypeListProps> = ({
     }, [dataModelGroups, searchText]);
     return (
         <Fragment>
+            <SearchField
+                placeholder="Search"
+                size="small"
+                className="dte-field-sidebar-search"
+                onChange={e => setSearchText(e.target.value ?? '')}
+            />
             {searchedFieldGroups.map(group => (
                 <div key={group.groupName} className="dte-field-type-group">
                     <Flex alignItems="center" gap={1} className="dte-field-type-group-header">

package/src/components/field-sidebar/field-menu-group.tsx

@@ -0,0 +1,36 @@
+import { Flex, Icon, Text } from '@servicetitan/anvil2';
+import { FC } from 'react';
+import { MenuGroupModel } from '../../constants/menu-group';
+import { FieldTypeEnum } from '../../interface/types';
+
+interface FieldMenuGroupProps {
+    menuGroups: MenuGroupModel[];
+    activeFieldKey: FieldTypeEnum;
+    onClickMenu(key: FieldTypeEnum): void;
+}
+
+export const FieldMenuGroup: FC<FieldMenuGroupProps> = ({
+    activeFieldKey,
+    menuGroups,
+    onClickMenu,
+}) => {
+    return (
+        <Flex className="dte-field-sidebar-menu" shrink={0} direction="column" gap="3">
+            {menuGroups.map(({ key, label, svgIcon }) => (
+                <Flex
+                    key={key}
+                    alignItems="center"
+                    justifyContent="center"
+                    direction="column"
+                    className={`dte-field-sidebar-menu-item cursor-pointer ${key === activeFieldKey ? '--active' : ''}`}
+                    onClick={() => onClickMenu(key)}
+                >
+                    <Icon svg={svgIcon} size="large" className="dte-field-sidebar-menu-item-icon" />
+                    <Text variant="body" size="small" className="dte-field-sidebar-menu-item-text">
+                        {label}
+                    </Text>
+                </Flex>
+            ))}
+        </Flex>
+    );
+};

package/src/components/field-sidebar/field-sidebar.tsx

@@ -1,14 +1,14 @@
-import { Button, Flex, Icon, SearchField, Text } from '@servicetitan/anvil2';
-import IconBorderColor from '@servicetitan/anvil2/assets/icons/material/round/border_color.svg';
+import { Button, Flex, Icon, Text } from '@servicetitan/anvil2';
 import IconMenuOpen from '@servicetitan/anvil2/assets/icons/material/round/menu_open.svg';
-import IconPhotoSizeSelectSmall from '@servicetitan/anvil2/assets/icons/material/round/photo_size_select_small.svg';
-import IconEstimate from '@servicetitan/anvil2/assets/icons/st/estimate.svg';
 
 import { FC, useState } from 'react';
+import { menuGroups } from '../../constants/menu-group';
 import { useToggle } from '../../hooks';
 import { DataModelFieldGroup, FieldTypeEnum, FieldTypeOption } from '../../interface/types';
+import { CalculatedFieldTypeList } from './calculated-field-type-list';
 import { DataModelFieldTypeList } from './data-model-field-type-list';
 import { ESignFieldTypeList } from './e-sign-field-type-list';
+import { FieldMenuGroup } from './field-menu-group';
 import { FillableFieldTypeList } from './fillable-field-type-list';
 
 interface FieldSidebarProps {
@@ -17,23 +17,12 @@ interface FieldSidebarProps {
     onDragStart(fieldOption: FieldTypeOption): void;
 }
 
-const menuGroups: { svgIcon: any; label: string; key: FieldTypeEnum }[] = [
-    { svgIcon: IconEstimate, label: 'Merge Tags', key: FieldTypeEnum.dataModel },
-    { svgIcon: IconBorderColor, label: 'E-Sign', key: FieldTypeEnum.eSign },
-    {
-        svgIcon: IconPhotoSizeSelectSmall,
-        label: 'Fillable Fields',
-        key: FieldTypeEnum.fillable,
-    },
-];
-
 export const FieldSidebar: FC<FieldSidebarProps> = ({
     dataModelGroups = [],
     onDragEnd,
     onDragStart,
 }) => {
     const [activeFieldType, setActiveFieldType] = useState<FieldTypeEnum>(FieldTypeEnum.dataModel);
-    const [searchText, setSearchText] = useState('');
     const { isOpen, open, toggle } = useToggle(true);
 
     const handleActiveFieldTypeChange = (activeFieldType: FieldTypeEnum) => {
@@ -43,31 +32,11 @@ export const FieldSidebar: FC<FieldSidebarProps> = ({
 
     return (
         <Flex className="dte-field-sidebar-container skeleton-item">
-            <Flex className="dte-field-sidebar-menu" shrink={0} direction="column" gap="3">
-                {menuGroups.map(({ key, label, svgIcon }) => (
-                    <Flex
-                        key={key}
-                        alignItems="center"
-                        justifyContent="center"
-                        direction="column"
-                        className={`dte-field-sidebar-menu-item cursor-pointer ${key === activeFieldType ? '--active' : ''}`}
-                        onClick={() => handleActiveFieldTypeChange(key)}
-                    >
-                        <Icon
-                            svg={svgIcon}
-                            size="large"
-                            className="dte-field-sidebar-menu-item-icon"
-                        />
-                        <Text
-                            variant="body"
-                            size="small"
-                            className="dte-field-sidebar-menu-item-text"
-                        >
-                            {label}
-                        </Text>
-                    </Flex>
-                ))}
-            </Flex>
+            <FieldMenuGroup
+                menuGroups={menuGroups}
+                onClickMenu={handleActiveFieldTypeChange}
+                activeFieldKey={activeFieldType}
+            />
 
             <Flex
                 className={`dte-field-sidebar-content skeleton-item ${isOpen ? '--open' : ''}`}
@@ -75,35 +44,25 @@ export const FieldSidebar: FC<FieldSidebarProps> = ({
             >
                 <Flex className="dte-field-sidebar-content-inner">
                     <Text variant="headline" el="h1" size="medium">
-                        {menuGroups.find(group => group.key === activeFieldType)!.label}
+                        {menuGroups.find(group => group.key === activeFieldType)?.label}
                     </Text>
 
-                    {activeFieldType !== FieldTypeEnum.eSign && (
-                        <SearchField
-                            placeholder="Search"
-                            size="small"
-                            className="dte-field-sidebar-search"
-                            onChange={e => setSearchText(e.target.value ?? '')}
-                        />
-                    )}
                     {activeFieldType === FieldTypeEnum.fillable && (
-                        <FillableFieldTypeList
-                            searchText={searchText}
-                            onDragStart={onDragStart}
-                            onDragEnd={onDragEnd}
-                        />
+                        <FillableFieldTypeList onDragStart={onDragStart} onDragEnd={onDragEnd} />
                     )}
                     {activeFieldType === FieldTypeEnum.eSign && (
                         <ESignFieldTypeList onDragEnd={onDragEnd} onDragStart={onDragStart} />
                     )}
                     {activeFieldType === FieldTypeEnum.dataModel && (
                         <DataModelFieldTypeList
-                            searchText={searchText}
                             dataModelGroups={dataModelGroups}
                             onDragStart={onDragStart}
                             onDragEnd={onDragEnd}
                         />
                     )}
+                    {activeFieldType === FieldTypeEnum.calculated && (
+                        <CalculatedFieldTypeList onDragStart={onDragStart} onDragEnd={onDragEnd} />
+                    )}
                 </Flex>
             </Flex>
             <Button

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

@@ -1,10 +1,10 @@
-import { FC, Fragment, useMemo } from 'react';
+import { SearchField } from '@servicetitan/anvil2';
+import { FC, Fragment, useMemo, useState } from 'react';
 import { FILLABLE_FIELD_TYPES } from '../../constants';
 import { FieldTypeOption } from '../../interface/types';
 import { FieldType } from './field-type';
 
 interface FillableFieldTypeListProps {
-    searchText?: string;
     onDragStart(fieldOption: FieldTypeOption): void;
     onDragEnd(): void;
 }
@@ -12,8 +12,9 @@ interface FillableFieldTypeListProps {
 export const FillableFieldTypeList: FC<FillableFieldTypeListProps> = ({
     onDragEnd,
     onDragStart,
-    searchText,
 }) => {
+    const [searchText, setSearchText] = useState('');
+
     const searchedFieldTypes = useMemo(() => {
         if (!searchText) {
             return FILLABLE_FIELD_TYPES;
@@ -27,18 +28,19 @@ export const FillableFieldTypeList: FC<FillableFieldTypeListProps> = ({
 
     return (
         <Fragment>
+            <SearchField
+                placeholder="Search"
+                size="small"
+                className="dte-field-sidebar-search"
+                onChange={e => setSearchText(e.target.value ?? '')}
+            />
             {searchedFieldTypes.map(fieldOption => {
                 return (
                     <FieldType
                         key={fieldOption.subType}
                         label={fieldOption.label}
                         onDragEnd={onDragEnd}
-                        onDragStart={() =>
-                            onDragStart({
-                                ...fieldOption,
-                                label: '',
-                            })
-                        }
+                        onDragStart={() => onDragStart(fieldOption)}
                     />
                 );
             })}

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

@@ -69,6 +69,8 @@ export const PdfEditor: FC<PdfEditorProps> = ({
         <Flex flex={1} className={`dte-pdf-editor ${loading ? 'skeleton' : ''}`}>
             {selectedField && (
                 <FieldConfigPanelOverlay
+                    dataModel={dataModel}
+                    documentFields={fields}
                     selectedField={selectedField}
                     onFieldConfigChange={updateField}
                     onDeleteField={deleteSelectedField}

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

@@ -0,0 +1,15 @@
+import { FC } from 'react';
+import { PdfField } from '../../interface/types';
+
+interface PdfOverlayFieldCalculatedProps {
+    field: PdfField;
+}
+
+export const PdfOverlayFieldCalculated: FC<PdfOverlayFieldCalculatedProps> = ({ field }) => {
+    return (
+        <span>
+            {field.label ? field.label : field.path}
+            {field.required ? '*' : ''}
+        </span>
+    );
+};

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

@@ -2,6 +2,7 @@ import { FC, MouseEvent, RefObject } from 'react';
 import { useFieldDrag, useFieldResize } from '../../hooks';
 import { FieldTypeEnum, PdfField } from '../../interface/types';
 import { getFieldBackgroundColor, getPagePosition } from '../../utils';
+import { PdfOverlayFieldCalculated } from './pdf-overlay-field-calculated';
 import { PdfOverlayFieldDataModel } from './pdf-overlay-field-data-model';
 import { PdfOverlayFieldESign } from './pdf-overlay-field-e-sign';
 import { PdfOverlayFieldFillable } from './pdf-overlay-field-fillable';
@@ -30,22 +31,25 @@ export const PdfOverlayField: FC<PdfOverlayFieldProps> = ({
     pdfWrapperRef,
     recipientsColors,
 }) => {
-    const { draggingFieldIdRef, handleDrag, handleDragEnd, handleDragStart } = useFieldDrag({
+    const { dragVisualPosition, handleDrag, handleDragEnd, handleDragStart } = useFieldDrag({
         pdfWrapperRef,
         onFieldMove,
     });
-    const isDragging = draggingFieldIdRef.current === field.id;
+    const isDragging = dragVisualPosition !== null;
 
     const { handleResizeStart } = useFieldResize({
         pdfWrapperRef,
         onFieldResize,
     });
 
-    const pagePos = getPagePosition(field.page, pdfWrapperRef);
+    const page = dragVisualPosition?.page ?? field.page;
+    const x = dragVisualPosition?.x ?? field.x;
+    const y = dragVisualPosition?.y ?? field.y;
+    const pagePos = getPagePosition(page, pdfWrapperRef);
 
     const style = {
-        left: pagePos.left + field.x,
-        top: pagePos.top + field.y,
+        left: pagePos.left + x,
+        top: pagePos.top + y,
         width: field.width,
         height: field.height,
         backgroundColor: getFieldBackgroundColor(field.recipient, recipientsColors),
@@ -62,6 +66,7 @@ export const PdfOverlayField: FC<PdfOverlayFieldProps> = ({
             className={`dte-pdf-field ${isSelected ? '--selected' : '--unselected'} ${isDragging ? '--dragging' : ''} ${isSameGroup ? '--colored' : ''}`}
             style={style}
         >
+            {field.type === FieldTypeEnum.calculated && <PdfOverlayFieldCalculated field={field} />}
             {field.type === FieldTypeEnum.eSign && <PdfOverlayFieldESign field={field} />}
             {field.type === FieldTypeEnum.dataModel && <PdfOverlayFieldDataModel field={field} />}
             {field.type === FieldTypeEnum.fillable && (

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

@@ -0,0 +1,23 @@
+import { FC, useMemo } from 'react';
+import { DataModelValues, PdfField } from '../../interface/types';
+import { evaluateFormula, formatCalculatedResult, resolvePdfDataValues } from '../../utils';
+
+interface PdfViewCalculatedProps {
+    field: PdfField;
+    data?: DataModelValues;
+}
+
+export const PdfViewCalculated: FC<PdfViewCalculatedProps> = ({ data, field }) => {
+    const displayValue = useMemo(() => {
+        if (field.formula?.tokens?.length) {
+            const value = evaluateFormula(field.formula, data);
+            return formatCalculatedResult(value, field.formulaFormat);
+        }
+        if (field.path) {
+            return resolvePdfDataValues(data, field.path) ?? '';
+        }
+        return field.label ?? '';
+    }, [data, field.formula, field.formulaFormat, field.label, field.path]);
+
+    return <div className="dte-pdf-field-value">{displayValue}</div>;
+};

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

@@ -11,6 +11,7 @@ import {
 } from '../../interface/types';
 import { mapColorsToRecipients } from '../../utils';
 import { PdfDocumentRenderer } from '../pdf-canvas/pdf-document-renderer';
+import { PdfViewCalculated } from './pdf-view-calculated';
 import { PdfViewDataModel } from './pdf-view-data-model';
 import { PdfViewESign } from './pdf-view-e-sign';
 import { PdfViewFieldContainer } from './pdf-view-field-container';
@@ -94,6 +95,9 @@ export const PdfView: FC<PdfViewProps> = ({
                                 {field.type === FieldTypeEnum.dataModel && (
                                     <PdfViewDataModel field={field} data={data} />
                                 )}
+                                {field.type === FieldTypeEnum.calculated && (
+                                    <PdfViewCalculated field={field} data={data} />
+                                )}
                                 {field.type === FieldTypeEnum.eSign && (
                                     <PdfViewESign field={field} />
                                 )}

package/src/constants/field.constants.ts

@@ -2,7 +2,7 @@ import {
     ESignFieldType,
     FieldTypeEnum,
     FieldTypeOption,
-    FillableFieldType,
+    PdfFieldSubType,
 } from '../interface/types';
 
 export const FIELD_CONSTANTS = {
@@ -19,7 +19,7 @@ export const FILLABLE_FIELD_DEFAULT_SIZES = {
     date: { width: 200, height: 25 },
     radio: { width: 20, height: 20 },
     checkbox: { width: 20, height: 20 },
-} as Record<FillableFieldType | ESignFieldType, { width: number; height: number }>;
+} as Record<PdfFieldSubType, { width: number; height: number }>;
 
 export const E_SIGN_FIELD_TYPE_OPTIONS: { name: string; id: ESignFieldType }[] = [
     { name: 'Signature', id: ESignFieldType.signature },
@@ -43,3 +43,10 @@ export const E_SIGN_FIELD_TYPES: FieldTypeOption[] = [
         subType: ESignFieldType.signature,
     },
 ];
+
+export const CALCULATED_FIELD_TYPES: FieldTypeOption[] = [
+    {
+        label: 'Calculated Field',
+        type: FieldTypeEnum.calculated,
+    },
+];

package/src/constants/menu-group.ts

@@ -0,0 +1,26 @@
+import IconBorderColor from '@servicetitan/anvil2/assets/icons/material/round/border_color.svg';
+import IconCalculate from '@servicetitan/anvil2/assets/icons/material/round/calculate.svg';
+import IconPhotoSizeSelectSmall from '@servicetitan/anvil2/assets/icons/material/round/photo_size_select_small.svg';
+import IconEstimate from '@servicetitan/anvil2/assets/icons/st/estimate.svg';
+import { FieldTypeEnum } from '../interface/types';
+
+export interface MenuGroupModel {
+    svgIcon: any;
+    label: string;
+    key: FieldTypeEnum;
+}
+
+export const menuGroups: MenuGroupModel[] = [
+    { svgIcon: IconEstimate, label: 'Merge Tags', key: FieldTypeEnum.dataModel },
+    { svgIcon: IconBorderColor, label: 'E-Sign', key: FieldTypeEnum.eSign },
+    {
+        svgIcon: IconPhotoSizeSelectSmall,
+        label: 'Fillable Fields',
+        key: FieldTypeEnum.fillable,
+    },
+    {
+        svgIcon: IconCalculate,
+        label: 'Calculated Fields',
+        key: FieldTypeEnum.calculated,
+    },
+];

package/src/hooks/index.ts

@@ -1,5 +1,6 @@
 export * from './useFieldDrag';
 export * from './useFieldResize';
+export * from './useFormulaEditor';
 export * from './usePdfDocumentRenderer';
 export * from './usePdfFieldDnD';
 export * from './usePdfFieldSelection';

package/src/hooks/useFieldDrag.ts

@@ -1,6 +1,17 @@
-import { DragEvent, MutableRefObject, RefObject, useRef } from 'react';
+import { DragEvent, MutableRefObject, RefObject, useCallback, useRef, useState } from 'react';
 import { PdfField } from '../interface/types';
-import { handleFieldDrag, handleFieldDragStart } from '../utils';
+import {
+    getPageDimensions,
+    getPageNumberFromClientY,
+    getPagePosition,
+    handleFieldDragStart,
+} from '../utils';
+
+export interface DragVisualPosition {
+    x: number;
+    y: number;
+    page: number;
+}
 
 interface UseFieldDragOptions {
     pdfWrapperRef: RefObject<HTMLDivElement>;
@@ -10,14 +21,22 @@ interface UseFieldDragOptions {
 interface UseFieldDragReturn {
     dragOffsetRef: MutableRefObject<{ x: number; y: number; page: number } | null>;
     draggingFieldIdRef: MutableRefObject<string | null>;
+    dragVisualPosition: DragVisualPosition | null;
     handleDragStart: (e: DragEvent<HTMLDivElement>, field: PdfField) => void;
     handleDrag: (e: DragEvent<HTMLDivElement>, field: PdfField) => void;
     handleDragEnd: () => void;
 }
 
+interface PendingMove {
+    x: number;
+    y: number;
+    page: number;
+}
+
 /**
- * Custom hook for handling field drag operations
- * Manages drag state and coordinates field movement
+ * Custom hook for handling field drag operations.
+ * During drag, position is kept in local state (dragVisualPosition) so the rest of the tree
+ * (config panel, other fields) does not re-render. onFieldMove is called only once on drag end.
  */
 export const useFieldDrag = ({
     onFieldMove,
@@ -25,9 +44,29 @@ export const useFieldDrag = ({
 }: UseFieldDragOptions): UseFieldDragReturn => {
     const dragOffsetRef = useRef<{ x: number; y: number; page: number } | null>(null);
     const draggingFieldIdRef = useRef<string | null>(null);
+    const pendingMoveRef = useRef<PendingMove | null>(null);
+    const rafIdRef = useRef<number | null>(null);
+    const fieldIdRef = useRef<string | null>(null);
+
+    const [dragVisualPosition, setDragVisualPosition] = useState<DragVisualPosition | null>(null);
+
+    const flushPendingVisualUpdate = useCallback(() => {
+        if (pendingMoveRef.current) {
+            setDragVisualPosition({ ...pendingMoveRef.current });
+            pendingMoveRef.current = null;
+        }
+        rafIdRef.current = null;
+    }, []);
 
     const handleDragStart = (e: DragEvent<HTMLDivElement>, field: PdfField) => {
         draggingFieldIdRef.current = field.id;
+        fieldIdRef.current = field.id;
+        pendingMoveRef.current = null;
+        if (rafIdRef.current !== null) {
+            cancelAnimationFrame(rafIdRef.current);
+            rafIdRef.current = null;
+        }
+        setDragVisualPosition({ x: field.x, y: field.y, page: field.page });
 
         const dragOffset = handleFieldDragStart(e, field, pdfWrapperRef);
         if (dragOffset) {
@@ -36,19 +75,56 @@ export const useFieldDrag = ({
     };
 
     const handleDrag = (e: DragEvent<HTMLDivElement>, field: PdfField) => {
-        if (dragOffsetRef.current) {
-            handleFieldDrag(e, field, dragOffsetRef.current, pdfWrapperRef, onFieldMove);
+        if (!dragOffsetRef.current) {
+            return;
+        }
+        if (!pdfWrapperRef.current || e.clientX === 0 || e.clientY === 0) {
+            return;
         }
+
+        const currentPage = getPageNumberFromClientY(e.clientY, pdfWrapperRef);
+        const currentPagePos = getPagePosition(currentPage, pdfWrapperRef);
+        const wrapperRect = pdfWrapperRef.current.getBoundingClientRect();
+        const pageDimensions = getPageDimensions(currentPage, pdfWrapperRef);
+
+        const x = e.clientX - wrapperRect.left - currentPagePos.left - dragOffsetRef.current.x;
+        const y = e.clientY - wrapperRect.top - currentPagePos.top - dragOffsetRef.current.y;
+
+        const minX = 0;
+        const minY = 0;
+        const maxX = Math.max(0, pageDimensions.width - field.width);
+        const maxY = Math.max(0, pageDimensions.height - field.height);
+
+        const clampedX = Math.max(minX, Math.min(maxX, x));
+        const clampedY = Math.max(minY, Math.min(maxY, y));
+
+        pendingMoveRef.current = { x: clampedX, y: clampedY, page: currentPage };
+
+        rafIdRef.current ??= requestAnimationFrame(flushPendingVisualUpdate);
     };
 
-    const handleDragEnd = () => {
+    const handleDragEnd = useCallback(() => {
+        if (rafIdRef.current !== null) {
+            cancelAnimationFrame(rafIdRef.current);
+            rafIdRef.current = null;
+        }
+        // Prefer pending (latest) position; fallback to current visual state
+        const final = pendingMoveRef.current ?? dragVisualPosition;
+        const fid = fieldIdRef.current;
+        pendingMoveRef.current = null;
+        setDragVisualPosition(null);
         dragOffsetRef.current = null;
         draggingFieldIdRef.current = null;
-    };
+        fieldIdRef.current = null;
+        if (fid && final) {
+            onFieldMove(fid, final.x, final.y, final.page);
+        }
+    }, [onFieldMove, dragVisualPosition]);
 
     return {
         dragOffsetRef,
         draggingFieldIdRef,
+        dragVisualPosition,
         handleDragStart,
         handleDrag,
         handleDragEnd,