The Open Source DocuSign Alternative.
TypeScript digital-signaturedocument-signingdocusign-alternativee-signatureesignesignaturenext-authnextjsopen-sourcepades-standardpdfpdf-signpdf-signaturepostgresqlprismaself-hostedsigningtypescript
fix: show warning on overlapping fields (#3017)
Lucas Smithb37529a1cf37
diff --git a/apps/remix/app/components/dialogs/envelope-distribute-dialog.tsx b/apps/remix/app/components/dialogs/envelope-distribute-dialog.tsxindex 211746faf..ed495f83a 100644--- a/apps/remix/app/components/dialogs/envelope-distribute-dialog.tsx+++ b/apps/remix/app/components/dialogs/envelope-distribute-dialog.tsx@@ -3,12 +3,13 @@ import { useCurrentOrganisation } from '@documenso/lib/client-only/providers/orgimport { DO_NOT_INVALIDATE_QUERY_ON_MUTATION } from '@documenso/lib/constants/trpc';import { AppError } from '@documenso/lib/errors/app-error';import { extractDocumentAuthMethods } from '@documenso/lib/utils/document-auth';+import { hasOverlappingFields } from '@documenso/lib/utils/fields-overlap';import { getRecipientsWithMissingFields } from '@documenso/lib/utils/recipients';import { zEmail } from '@documenso/lib/utils/zod';import { trpc, trpc as trpcReact } from '@documenso/trpc/react';import { DocumentSendEmailMessageHelper } from '@documenso/ui/components/document/document-send-email-message-helper';import { cn } from '@documenso/ui/lib/utils';-import { Alert, AlertDescription } from '@documenso/ui/primitives/alert';+import { Alert, AlertDescription, AlertTitle } from '@documenso/ui/primitives/alert';import { Button } from '@documenso/ui/primitives/button';import {Dialog,@@ -32,7 +33,7 @@ import { zodResolver } from '@hookform/resolvers/zod';import { Trans, useLingui } from '@lingui/react/macro';import { DocumentDistributionMethod, DocumentStatus, EnvelopeType } from '@prisma/client';import { AnimatePresence, motion } from 'framer-motion';-import { InfoIcon } from 'lucide-react';+import { AlertTriangleIcon, InfoIcon } from 'lucide-react';import { useEffect, useMemo, useState } from 'react';import { useForm } from 'react-hook-form';import { useNavigate } from 'react-router';@@ -138,6 +139,27 @@ export const EnvelopeDistributeDialog = ({});}, [recipientsWithIndex, envelope.authOptions]);+ /**+ * Whether any fields significantly overlap each other. This is surfaced as a+ * non-blocking warning since overlapping fields still allow sending, but can+ * complicate the signing process or cause fields to behave unexpectedly.+ */+ const hasOverlappingEnvelopeFields = useMemo(+ () =>+ hasOverlappingFields(+ envelope.fields.map((field) => ({+ id: field.id,+ envelopeItemId: field.envelopeItemId,+ page: field.page,+ positionX: Number(field.positionX),+ positionY: Number(field.positionY),+ width: Number(field.width),+ height: Number(field.height),+ })),+ ),+ [envelope.fields],+ );+const invalidEnvelopeCode = useMemo(() => {if (recipientsMissingSignatureFields.length > 0) {return 'MISSING_SIGNATURES';@@ -240,6 +262,24 @@ export const EnvelopeDistributeDialog = ({<Form {...form}><form onSubmit={handleSubmit(onFormSubmit)}><fieldset disabled={isSubmitting}>+ {hasOverlappingEnvelopeFields && (+ <Alert variant="warning" className="mb-4 flex flex-row items-start gap-3">+ <AlertTriangleIcon className="mt-0.5 h-5 w-5 flex-shrink-0" />++ <div className="flex flex-col gap-1">+ <AlertTitle>+ <Trans>Overlapping fields detected</Trans>+ </AlertTitle>+ <AlertDescription>+ <Trans>+ Some fields are placed on top of each other. This may complicate the signing process or cause+ fields to not work as expected.+ </Trans>+ </AlertDescription>+ </div>+ </Alert>+ )}+<TabsonValueChange={(value) =>// eslint-disable-next-line @typescript-eslint/consistent-type-assertionsdiff --git a/apps/remix/app/components/general/envelope-editor/envelope-editor-fields-page-renderer.tsx b/apps/remix/app/components/general/envelope-editor/envelope-editor-fields-page-renderer.tsxindex a5676dc60..db8f6ffbb 100644--- a/apps/remix/app/components/general/envelope-editor/envelope-editor-fields-page-renderer.tsx+++ b/apps/remix/app/components/general/envelope-editor/envelope-editor-fields-page-renderer.tsx@@ -1,3 +1,4 @@+import { useDebouncedValue } from '@documenso/lib/client-only/hooks/use-debounced-value';import type { TLocalField } from '@documenso/lib/client-only/hooks/use-editor-fields';import { usePageRenderer } from '@documenso/lib/client-only/hooks/use-page-renderer';import { useCurrentEnvelopeEditor } from '@documenso/lib/client-only/providers/envelope-editor-provider';@@ -13,6 +14,7 @@ import {} from '@documenso/lib/universal/field-renderer/field-renderer';import { renderField } from '@documenso/lib/universal/field-renderer/render-field';import { getClientSideFieldTranslations } from '@documenso/lib/utils/fields';+import { getOverlappingFieldPairs } from '@documenso/lib/utils/fields-overlap';import { canRecipientFieldsBeModified } from '@documenso/lib/utils/recipients';import {Command,@@ -62,6 +64,36 @@ export const EnvelopeEditorFieldsPageRenderer = ({ pageData }: { pageData: PageR[editorFields.localFields, pageNumber, currentEnvelopeItem?.id],);+ /**+ * Debounce the fields used for overlap highlighting so we don't recompute on every+ * small drag/resize tick. Overlaps only occur within the same page and envelope+ * item, so computing from this page's fields alone is sufficient.+ */+ const debouncedPageFields = useDebouncedValue(localPageFields, 300);++ const overlappingFieldFormIds = useMemo(() => {+ const formIds = new Set<string>();++ const pairs = getOverlappingFieldPairs(+ debouncedPageFields.map((field) => ({+ id: field.formId,+ envelopeItemId: field.envelopeItemId,+ page: field.page,+ positionX: field.positionX,+ positionY: field.positionY,+ width: field.width,+ height: field.height,+ })),+ );++ for (const pair of pairs) {+ formIds.add(pair.fieldA.id);+ formIds.add(pair.fieldB.id);+ }++ return formIds;+ }, [debouncedPageFields]);+const handleResizeOrMove = (event: KonvaEventObject<Event>) => {const isDragEvent = event.type === 'dragend';@@ -113,6 +145,62 @@ export const EnvelopeEditorFieldsPageRenderer = ({ pageData }: { pageData: PageRpageLayer.current?.batchDraw();};+ /**+ * Draws (or removes) a dashed warning outline over a field that significantly+ * overlaps another field. The highlight is a child of the field group so it moves+ * and resizes with the field, and sits on top of the field's own rect (which is+ * re-styled on every render and would otherwise clobber a direct stroke change).+ */+ const syncOverlapHighlight = (fieldGroup: Konva.Group, isOverlapping: boolean) => {+ const existingHighlight = fieldGroup.findOne('.field-overlap-highlight');++ // Skip while a field is actively being dragged/resized. The highlight is driven+ // by debounced field data, so it would lag behind and distort during the gesture.+ // It is repainted once the gesture settles (the effect re-runs on isFieldChanging).+ if (isFieldChanging) {+ existingHighlight?.destroy();+ return;+ }++ if (!isOverlapping) {+ existingHighlight?.destroy();+ return;+ }++ const fieldRect = fieldGroup.findOne('.field-rect');++ if (!fieldRect) {+ return;+ }++ const highlightAttrs = {+ x: 0,+ y: 0,+ width: fieldRect.width(),+ height: fieldRect.height(),+ stroke: '#f59e0b',+ strokeWidth: 2,+ dash: [6, 4],+ cornerRadius: 2,+ strokeScaleEnabled: false,+ listening: false,+ } satisfies Partial<Konva.RectConfig>;++ if (existingHighlight instanceof Konva.Rect) {+ existingHighlight.setAttrs(highlightAttrs);+ existingHighlight.moveToTop();+ return;+ }++ const highlight = new Konva.Rect({+ name: 'field-overlap-highlight',+ ...highlightAttrs,+ });++ fieldGroup.add(highlight);+ highlight.moveToTop();+ };+const unsafeRenderFieldOnLayer = (field: TLocalField) => {if (!pageLayer.current) {return;@@ -139,6 +227,8 @@ export const EnvelopeEditorFieldsPageRenderer = ({ pageData }: { pageData: PageRmode: 'edit',});+ syncOverlapHighlight(fieldGroup, overlappingFieldFormIds.has(field.formId));+if (!isFieldEditable) {return;}@@ -435,7 +525,7 @@ export const EnvelopeEditorFieldsPageRenderer = ({ pageData }: { pageData: PageRinteractiveTransformer.current?.forceUpdate();pageLayer.current.batchDraw();- }, [localPageFields, selectedKonvaFieldGroups]);+ }, [localPageFields, selectedKonvaFieldGroups, overlappingFieldFormIds, isFieldChanging]);const setSelectedFields = (nodes: Konva.Node[]) => {// eslint-disable-next-line @typescript-eslint/consistent-type-assertionsdiff --git a/apps/remix/app/components/general/envelope-editor/envelope-editor-fields-page.tsx b/apps/remix/app/components/general/envelope-editor/envelope-editor-fields-page.tsxindex a5ec4ed16..945d3c308 100644--- a/apps/remix/app/components/general/envelope-editor/envelope-editor-fields-page.tsx+++ b/apps/remix/app/components/general/envelope-editor/envelope-editor-fields-page.tsx@@ -1,3 +1,4 @@+import { useDebouncedValue } from '@documenso/lib/client-only/hooks/use-debounced-value';import { useCurrentEnvelopeEditor } from '@documenso/lib/client-only/providers/envelope-editor-provider';import { useCurrentEnvelopeRender } from '@documenso/lib/client-only/providers/envelope-render-provider';import { PDF_VIEWER_ERROR_MESSAGES } from '@documenso/lib/constants/pdf-viewer-i18n';@@ -17,6 +18,7 @@ import {type TTextFieldMeta,} from '@documenso/lib/types/field-meta';import { getEnvelopeItemPermissions } from '@documenso/lib/utils/envelope';+import { getOverlappingFieldPairs } from '@documenso/lib/utils/fields-overlap';import { canRecipientFieldsBeModified } from '@documenso/lib/utils/recipients';import { AnimateGenericFadeInOut } from '@documenso/ui/components/animate/animate-generic-fade-in-out';import { cn } from '@documenso/ui/lib/utils';@@ -28,7 +30,7 @@ import { msg } from '@lingui/core/macro';import { useLingui } from '@lingui/react';import { Trans } from '@lingui/react/macro';import { DocumentStatus, FieldType, RecipientRole } from '@prisma/client';-import { FileTextIcon, PencilIcon, SparklesIcon } from 'lucide-react';+import { AlertTriangleIcon, FileTextIcon, PencilIcon, SparklesIcon } from 'lucide-react';import { useEffect, useMemo, useRef, useState } from 'react';import { useRevalidator, useSearchParams } from 'react-router';import { isDeepEqual } from 'remeda';@@ -78,7 +80,7 @@ export const EnvelopeEditorFieldsPage = () => {const { envelope, editorFields, navigateToStep, editorConfig } = useCurrentEnvelopeEditor();- const { currentEnvelopeItem } = useCurrentEnvelopeRender();+ const { currentEnvelopeItem, setCurrentEnvelopeItem } = useCurrentEnvelopeRender();const { _ } = useLingui();@@ -93,6 +95,53 @@ export const EnvelopeEditorFieldsPage = () => {const selectedField = useMemo(() => structuredClone(editorFields.selectedField), [editorFields.selectedField]);+ /**+ * Debounce the fields used for overlap detection so we don't recompute on every+ * small drag/resize movement, which is expensive on large field counts and can+ * bog down lower-end devices.+ */+ const debouncedLocalFields = useDebouncedValue(editorFields.localFields, 300);++ /**+ * Fields that significantly overlap each other. Overlapping fields render poorly in+ * the editor and can behave unexpectedly during signing, so we warn the author here.+ */+ const overlappingFieldPairs = useMemo(+ () =>+ getOverlappingFieldPairs(+ debouncedLocalFields.map((field) => ({+ id: field.formId,+ envelopeItemId: field.envelopeItemId,+ page: field.page,+ positionX: field.positionX,+ positionY: field.positionY,+ width: field.width,+ height: field.height,+ })),+ ),+ [debouncedLocalFields],+ );++ const handleReviewOverlappingField = () => {+ const firstPair = overlappingFieldPairs[0];++ if (!firstPair) {+ return;+ }++ const targetField = editorFields.localFields.find((field) => field.formId === firstPair.fieldA.id);++ if (!targetField) {+ return;+ }++ if (targetField.envelopeItemId !== currentEnvelopeItem?.id) {+ setCurrentEnvelopeItem(targetField.envelopeItemId);+ }++ editorFields.setSelectedField(targetField.formId);+ };+const updateSelectedFieldMeta = (fieldMeta: TFieldMetaSchema) => {if (!selectedField) {return;@@ -211,6 +260,29 @@ export const EnvelopeEditorFieldsPage = () => {</Alert>)}+ {overlappingFieldPairs.length > 0 && (+ <Alert+ variant="warning"+ className="mt-20 mb-4 flex w-full max-w-[800px] flex-row items-center justify-between space-y-0 rounded-sm"+ >+ <div className="flex flex-row items-start gap-3">+ <AlertTriangleIcon className="mt-0.5 h-5 w-5 flex-shrink-0" />++ <div className="flex flex-col gap-1">+ <AlertTitle>+ <Trans>Overlapping fields detected</Trans>+ </AlertTitle>+ <AlertDescription>+ <Trans>+ Some fields are placed on top of each other. This may complicate the signing process or cause+ fields to not work as expected.+ </Trans>+ </AlertDescription>+ </div>+ </div>+ </Alert>+ )}+{currentEnvelopeItem !== null ? (<EnvelopePdfViewercustomPageRenderer={EnvelopeEditorFieldsPageRenderer}diff --git a/packages/lib/utils/fields-overlap.ts b/packages/lib/utils/fields-overlap.tsnew file mode 100644index 000000000..9b753594b--- /dev/null+++ b/packages/lib/utils/fields-overlap.ts@@ -0,0 +1,123 @@+/**+ * Utilities for detecting overlapping fields in the envelope editor.+ *+ * Fields can be unintentionally placed on top of each other during the authoring+ * process. This does not render well in the editor and behaves unpredictably during+ * signing (fields can sit on top of one another depending on their state), so we warn+ * the user when a significant overlap is detected.+ *+ * All positional values are expected as percentages (0-100) of the page dimensions,+ * matching how fields are stored in the editor and database.+ */++/**+ * The minimum proportion (0-1) of the smaller field's area that must be covered by+ * another field for the pair to be considered an "overlap" worth warning about.+ *+ * A small amount of overlap (e.g. touching edges) is common and harmless, so we only+ * flag pairs where one field covers at least this fraction of the other.+ */+export const FIELD_OVERLAP_THRESHOLD = 0.4;++type OverlapFieldInput = {+ /**+ * A stable identifier used to reference the field in the returned pairs.+ * Use the client-side `formId` in the editor, or the database `id` elsewhere.+ */+ id: string | number;+ envelopeItemId: string;+ page: number;+ positionX: number;+ positionY: number;+ width: number;+ height: number;+};++export type TFieldOverlapPair<T extends OverlapFieldInput> = {+ fieldA: T;+ fieldB: T;+ /**+ * The proportion (0-1) of the smaller field's area covered by the intersection.+ */+ overlapRatio: number;+};++/**+ * Returns the area of the intersection between two fields, in squared percentage units.+ *+ * Returns 0 when the fields do not intersect.+ */+const getIntersectionArea = (fieldA: OverlapFieldInput, fieldB: OverlapFieldInput): number => {+ const overlapX = Math.max(+ 0,+ Math.min(fieldA.positionX + fieldA.width, fieldB.positionX + fieldB.width) -+ Math.max(fieldA.positionX, fieldB.positionX),+ );++ const overlapY = Math.max(+ 0,+ Math.min(fieldA.positionY + fieldA.height, fieldB.positionY + fieldB.height) -+ Math.max(fieldA.positionY, fieldB.positionY),+ );++ return overlapX * overlapY;+};++/**+ * Detects pairs of fields that overlap by at least the given threshold.+ *+ * Two fields are only compared when they share the same envelope item and page.+ * The overlap ratio is measured against the smaller of the two fields, so a small+ * field that is mostly covered by a large field is still flagged.+ *+ * @param fields The fields to check. Positional values must be percentages (0-100).+ * @param threshold The minimum overlap ratio (0-1) to flag. Defaults to {@link FIELD_OVERLAP_THRESHOLD}.+ */+export const getOverlappingFieldPairs = <T extends OverlapFieldInput>(+ fields: T[],+ threshold: number = FIELD_OVERLAP_THRESHOLD,+): TFieldOverlapPair<T>[] => {+ const pairs: TFieldOverlapPair<T>[] = [];++ for (let i = 0; i < fields.length; i++) {+ for (let j = i + 1; j < fields.length; j++) {+ const fieldA = fields[i];+ const fieldB = fields[j];++ if (fieldA.envelopeItemId !== fieldB.envelopeItemId || fieldA.page !== fieldB.page) {+ continue;+ }++ const fieldAArea = fieldA.width * fieldA.height;+ const fieldBArea = fieldB.width * fieldB.height;++ if (fieldAArea <= 0 || fieldBArea <= 0) {+ continue;+ }++ const intersectionArea = getIntersectionArea(fieldA, fieldB);++ if (intersectionArea <= 0) {+ continue;+ }++ const overlapRatio = intersectionArea / Math.min(fieldAArea, fieldBArea);++ if (overlapRatio >= threshold) {+ pairs.push({ fieldA, fieldB, overlapRatio });+ }+ }+ }++ return pairs;+};++/**+ * Returns true if any pair of fields overlaps by at least the given threshold.+ */+export const hasOverlappingFields = <T extends OverlapFieldInput>(+ fields: T[],+ threshold: number = FIELD_OVERLAP_THRESHOLD,+): boolean => {+ return getOverlappingFieldPairs(fields, threshold).length > 0;+};