feat: add uninserted field validation

apps/web/src/app/(signing)/sign/[token]/form.tsx

@@ -1,12 +1,15 @@
 'use client';
 
+import { useMemo, useState } from 'react';
+
 import { useRouter } from 'next/navigation';
 
-import { Loader } from 'lucide-react';
 import { useForm } from 'react-hook-form';
 
 import { completeDocumentWithToken } from '@documenso/lib/server-only/document/complete-document-with-token';
+import { sortFieldsByPosition, validateFieldsInserted } from '@documenso/lib/utils/fields';
 import { Document, Field, Recipient } from '@documenso/prisma/client';
+import { FieldToolTip } from '@documenso/ui/components/field/field-tooltip';
 import { cn } from '@documenso/ui/lib/utils';
 import { Button } from '@documenso/ui/primitives/button';
 import { Card, CardContent } from '@documenso/ui/primitives/card';
@@ -27,15 +30,22 @@ export const SigningForm = ({ document, recipient, fields }: SigningFormProps) =
 
   const { fullName, signature, setFullName, setSignature } = useRequiredSigningContext();
 
+  const [validateUninsertedFields, setValidateUninsertedFields] = useState(false);
+
   const {
     handleSubmit,
     formState: { isSubmitting },
   } = useForm();
 
-  const isComplete = fields.every((f) => f.inserted);
+  const uninsertedFields = useMemo(() => {
+    return sortFieldsByPosition(fields.filter((field) => !field.inserted));
+  }, [fields]);
 
   const onFormSubmit = async () => {
-    if (!isComplete) {
+    setValidateUninsertedFields(true);
+    const isFieldsValid = validateFieldsInserted(fields);
+
+    if (!isFieldsValid) {
       return;
     }
 
@@ -54,7 +64,16 @@ export const SigningForm = ({ document, recipient, fields }: SigningFormProps) =
       )}
       onSubmit={handleSubmit(onFormSubmit)}
     >
-      <div className={cn('-mx-2 flex flex-1 flex-col overflow-hidden px-2')}>
+      {validateUninsertedFields && uninsertedFields[0] && (
+        <FieldToolTip key={uninsertedFields[0].id} field={uninsertedFields[0]} color="warning">
+          Click to insert field
+        </FieldToolTip>
+      )}
+
+      <fieldset
+        disabled={isSubmitting}
+        className={cn('-mx-2 flex flex-1 flex-col overflow-hidden px-2')}
+      >
         <div className={cn('flex flex-1 flex-col')}>
           <h3 className="text-foreground text-2xl font-semibold">Sign Document</h3>
 
@@ -106,19 +125,13 @@ export const SigningForm = ({ document, recipient, fields }: SigningFormProps) =
                 Cancel
               </Button>
 
-              <Button
+              <Button className="w-full" type="submit" size="lg" loading={isSubmitting}>
-                className="w-full"
-                type="submit"
-                size="lg"
-                disabled={!isComplete || isSubmitting}
-              >
-                {isSubmitting && <Loader className="mr-2 h-5 w-5 animate-spin" />}
                 Complete
               </Button>
             </div>
           </div>
         </div>
-      </div>
+      </fieldset>
     </form>
   );
 };

apps/web/src/app/(signing)/sign/[token]/signing-field-container.tsx

@@ -2,10 +2,8 @@
 
 import React from 'react';
 
-import { useFieldPageCoords } from '@documenso/lib/client-only/hooks/use-field-page-coords';
 import { FieldWithSignature } from '@documenso/prisma/types/field-with-signature';
-import { cn } from '@documenso/ui/lib/utils';
+import { FieldRootContainer } from '@documenso/ui/components/field/field';
-import { Card, CardContent } from '@documenso/ui/primitives/card';
 
 export type SignatureFieldProps = {
   field: FieldWithSignature;
@@ -22,8 +20,6 @@ export const SigningFieldContainer = ({
   onRemove,
   children,
 }: SignatureFieldProps) => {
-  const coords = useFieldPageCoords(field);
-
   const onSignFieldClick = async () => {
     if (field.inserted) {
       return;
@@ -41,40 +37,21 @@ export const SigningFieldContainer = ({
   };
 
   return (
-    <div
+    <FieldRootContainer field={field}>
-      className="absolute"
+      {!field.inserted && !loading && (
-      style={{
+        <button type="submit" className="absolute inset-0 z-10" onClick={onSignFieldClick} />
-        top: `${coords.y}px`,
+      )}
-        left: `${coords.x}px`,
+
-        height: `${coords.height}px`,
+      {field.inserted && !loading && (
-        width: `${coords.width}px`,
+        <button
-      }}
+          className="text-destructive bg-background/40 absolute inset-0 z-10 flex items-center justify-center rounded-md text-sm opacity-0 backdrop-blur-sm duration-200 group-hover:opacity-100"
-    >
+          onClick={onRemoveSignedFieldClick}
-      <Card
-        className="bg-background relative h-full w-full"
-        data-inserted={field.inserted ? 'true' : 'false'}
-      >
-        <CardContent
-          className={cn(
-            'text-foreground hover:shadow-primary-foreground group flex h-full w-full flex-col items-center justify-center p-2',
-          )}
         >
-          {!field.inserted && !loading && (
+          Remove
-            <button type="submit" className="absolute inset-0 z-10" onClick={onSignFieldClick} />
+        </button>
-          )}
+      )}
 
-          {field.inserted && !loading && (
+      {children}
-            <button
+    </FieldRootContainer>
-              className="text-destructive bg-background/40 absolute inset-0 z-10 flex items-center justify-center rounded-md text-sm opacity-0 backdrop-blur-sm duration-200 group-hover:opacity-100"
-              onClick={onRemoveSignedFieldClick}
-            >
-              Remove
-            </button>
-          )}
-
-          {children}
-        </CardContent>
-      </Card>
-    </div>
   );
 };

packages/lib/utils/fields.ts

@@ -0,0 +1,41 @@
+import { Field } from '@documenso/prisma/client';
+
+/**
+ * Sort the fields by the Y position on the document.
+ */
+export const sortFieldsByPosition = (fields: Field[]): Field[] => {
+  const clonedFields: Field[] = JSON.parse(JSON.stringify(fields));
+
+  // Sort by page first, then position on page second.
+  return clonedFields.sort((a, b) => a.page - b.page || Number(a.positionY) - Number(b.positionY));
+};
+
+/**
+ * Validate whether all the provided fields are inserted.
+ *
+ * If there are any non-inserted fields it will be highlighted and scrolled into view.
+ *
+ * @returns `true` if all fields are inserted, `false` otherwise.
+ */
+export const validateFieldsInserted = (fields: Field[]): boolean => {
+  const fieldCardElements = document.getElementsByClassName('field-card-container');
+
+  // Attach validate attribute on all fields.
+  Array.from(fieldCardElements).forEach((element) => {
+    element.setAttribute('data-validate', 'true');
+  });
+
+  const uninsertedFields = sortFieldsByPosition(fields.filter((field) => !field.inserted));
+
+  const firstUninsertedField = uninsertedFields[0];
+
+  const firstUninsertedFieldElement =
+    firstUninsertedField && document.getElementById(`field-${firstUninsertedField.id}`);
+
+  if (firstUninsertedFieldElement) {
+    firstUninsertedFieldElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    return false;
+  }
+
+  return uninsertedFields.length === 0;
+};

packages/ui/components/field/field-tooltip.tsx

@@ -39,7 +39,7 @@ export function FieldToolTip({ children, color, className = '', field }: FieldTo
 
   return createPortal(
     <div
-      className={cn('absolute', className)}
+      className={cn('absolute')}
       style={{
         top: `${coords.y}px`,
         left: `${coords.x}px`,
@@ -49,7 +49,7 @@ export function FieldToolTip({ children, color, className = '', field }: FieldTo
     >
       <TooltipProvider>
         <Tooltip delayDuration={0} open={!field.inserted}>
-          <TooltipTrigger className="absolute top-0 w-full"></TooltipTrigger>
+          <TooltipTrigger className="absolute inset-0 w-full"></TooltipTrigger>
 
           <TooltipContent className={tooltipVariants({ color, className })} sideOffset={2}>
             {children}

packages/ui/components/field/field.tsx

@@ -0,0 +1,90 @@
+'use client';
+
+import React, { useEffect, useState } from 'react';
+
+import { createPortal } from 'react-dom';
+
+import { useFieldPageCoords } from '@documenso/lib/client-only/hooks/use-field-page-coords';
+import { Field } from '@documenso/prisma/client';
+import { cn } from '@documenso/ui/lib/utils';
+import { Card, CardContent } from '@documenso/ui/primitives/card';
+
+export type FieldRootContainerProps = {
+  field: Field;
+  children: React.ReactNode;
+};
+
+export type FieldContainerPortalProps = {
+  field: Field;
+  className?: string;
+  children: React.ReactNode;
+};
+
+export function FieldContainerPortal({
+  field,
+  children,
+  className = '',
+}: FieldContainerPortalProps) {
+  const coords = useFieldPageCoords(field);
+
+  return createPortal(
+    <div
+      className={cn('absolute', className)}
+      style={{
+        top: `${coords.y}px`,
+        left: `${coords.x}px`,
+        height: `${coords.height}px`,
+        width: `${coords.width}px`,
+      }}
+    >
+      {children}
+    </div>,
+    document.body,
+  );
+}
+
+export function FieldRootContainer({ field, children }: FieldContainerPortalProps) {
+  const [isValidating, setIsValidating] = useState(false);
+
+  const ref = React.useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!ref.current) {
+      return;
+    }
+
+    const observer = new MutationObserver((_mutations) => {
+      if (ref.current) {
+        setIsValidating(ref.current.getAttribute('data-validate') === 'true');
+      }
+    });
+
+    observer.observe(ref.current, {
+      attributes: true,
+    });
+
+    return () => {
+      observer.disconnect();
+    };
+  }, []);
+
+  return (
+    <FieldContainerPortal field={field}>
+      <Card
+        id={`field-${field.id}`}
+        className={cn(
+          'field-card-container bg-background relative z-20 h-full w-full transition-all',
+          {
+            'border-orange-300 ring-1 ring-orange-300': !field.inserted && isValidating,
+          },
+        )}
+        ref={ref}
+        data-inserted={field.inserted ? 'true' : 'false'}
+      >
+        <CardContent className="text-foreground hover:shadow-primary-foreground group flex h-full w-full flex-col items-center justify-center p-2">
+          {children}
+        </CardContent>
+      </Card>
+    </FieldContainerPortal>
+  );
+}

packages/ui/primitives/document-flow/add-signature.tsx

@@ -8,8 +8,10 @@ import { useForm } from 'react-hook-form';
 import { match } from 'ts-pattern';
 
 import { PDF_VIEWER_PAGE_SELECTOR } from '@documenso/lib/constants/pdf-viewer';
+import { sortFieldsByPosition, validateFieldsInserted } from '@documenso/lib/utils/fields';
 import { Field, FieldType } from '@documenso/prisma/client';
 import { FieldWithSignature } from '@documenso/prisma/types/field-with-signature';
+import { FieldToolTip } from '@documenso/ui/components/field/field-tooltip';
 import { cn } from '@documenso/ui/lib/utils';
 import { Card, CardContent } from '@documenso/ui/primitives/card';
 import { TAddSignatureFormSchema } from '@documenso/ui/primitives/document-flow/add-signature.types';
@@ -24,7 +26,6 @@ import { ElementVisible } from '@documenso/ui/primitives/element-visible';
 import { Input } from '@documenso/ui/primitives/input';
 import { SignaturePad } from '@documenso/ui/primitives/signature-pad';
 
-import { FieldToolTip } from '../field/field-tooltip';
 import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '../form/form';
 import { ZAddSignatureFormSchema } from './add-signature.types';
 import {
@@ -89,40 +90,14 @@ export const AddSignatureFormPartial = ({
   const uninsertedFields = useMemo(() => {
     const fields = localFields.filter((field) => !field.inserted);
 
-    return fields.sort((a, b) => {
+    return sortFieldsByPosition(fields);
-      if (a.page < b.page) {
-        return -1;
-      }
-
-      if (a.page > b.page) {
-        return 1;
-      }
-
-      const aTop = a.positionY;
-      const bTop = b.positionY;
-
-      if (aTop < bTop) {
-        return -1;
-      }
-
-      if (aTop > bTop) {
-        return 1;
-      }
-
-      return 0;
-    });
   }, [localFields]);
 
   const onValidateFields = async (values: TAddSignatureFormSchema) => {
     setValidateUninsertedFields(true);
+    const isFieldsValid = validateFieldsInserted(localFields);
 
-    const firstUninsertedField = uninsertedFields[0];
+    if (!isFieldsValid) {
-
-    const firstUninsertedFieldElement =
-      firstUninsertedField && document.getElementById(`field-${firstUninsertedField.id}`);
-
-    if (firstUninsertedFieldElement) {
-      firstUninsertedFieldElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
       return;
     }
 
@@ -212,6 +187,24 @@ export const AddSignatureFormPartial = ({
     );
   };
 
+  /**
+   * When a form value changes, reset all the corresponding fields to be uninserted.
+   */
+  const onFormValueChange = (fieldType: FieldType) => {
+    setLocalFields((fields) =>
+      fields.map((field) => {
+        if (field.type !== fieldType) {
+          return field;
+        }
+
+        return {
+          ...field,
+          inserted: false,
+        };
+      }),
+    );
+  };
+
   return (
     <Form {...form}>
       <fieldset className="flex h-full flex-col" disabled={form.formState.isSubmitting}>
@@ -224,7 +217,16 @@ export const AddSignatureFormPartial = ({
                 <FormItem>
                   <FormLabel required>Email</FormLabel>
                   <FormControl>
-                    <Input className="bg-background" type="email" autoComplete="email" {...field} />
+                    <Input
+                      className="bg-background"
+                      type="email"
+                      autoComplete="email"
+                      {...field}
+                      onChange={(value) => {
+                        onFormValueChange(FieldType.EMAIL);
+                        field.onChange(value);
+                      }}
+                    />
                   </FormControl>
                   <FormMessage />
                 </FormItem>
@@ -239,7 +241,14 @@ export const AddSignatureFormPartial = ({
                   <FormItem>
                     <FormLabel required={requireName}>Name</FormLabel>
                     <FormControl>
-                      <Input className="bg-background" {...field} />
+                      <Input
+                        className="bg-background"
+                        {...field}
+                        onChange={(value) => {
+                          onFormValueChange(FieldType.NAME);
+                          field.onChange(value);
+                        }}
+                      />
                     </FormControl>
                     <FormMessage />
                   </FormItem>
@@ -267,7 +276,11 @@ export const AddSignatureFormPartial = ({
                           <SignaturePad
                             className="h-44 w-full"
                             defaultValue={field.value}
-                            {...field}
+                            onBlur={field.onBlur}
+                            onChange={(value) => {
+                              onFormValueChange(FieldType.SIGNATURE);
+                              field.onChange(value);
+                            }}
                           />
                         </CardContent>
                       </Card>
@@ -309,7 +322,6 @@ export const AddSignatureFormPartial = ({
               return (
                 <SinglePlayerModeCustomTextField
                   onClick={insertField(field)}
-                  validateUninsertedField={validateUninsertedFields}
                   key={field.id}
                   field={field}
                 />
@@ -318,7 +330,6 @@ export const AddSignatureFormPartial = ({
             .with(FieldType.SIGNATURE, () => (
               <SinglePlayerModeSignatureField
                 onClick={insertField(field)}
-                validateUninsertedField={validateUninsertedFields}
                 key={field.id}
                 field={field}
               />

packages/ui/primitives/document-flow/single-player-mode-fields.tsx

@@ -3,7 +3,6 @@
 import React, { useRef } from 'react';
 
 import { AnimatePresence, motion } from 'framer-motion';
-import { createPortal } from 'react-dom';
 import { match } from 'ts-pattern';
 
 import { useElementScaleSize } from '@documenso/lib/client-only/hooks/use-element-scale-size';
@@ -16,92 +15,46 @@ import {
 } from '@documenso/lib/constants/pdf';
 import { Field, FieldType } from '@documenso/prisma/client';
 import { FieldWithSignature } from '@documenso/prisma/types/field-with-signature';
-import { cn } from '@documenso/ui/lib/utils';
+import { FieldRootContainer } from '@documenso/ui/components/field/field';
-import { Card, CardContent } from '@documenso/ui/primitives/card';
-
-export type FieldContainerPortalProps = {
-  field: FieldWithSignature;
-  className?: string;
-  children: React.ReactNode;
-};
 
 export type SinglePlayerModeFieldContainerProps = {
   field: FieldWithSignature;
   children: React.ReactNode;
-  validateUninsertedField?: boolean;
 };
 
 export type SinglePlayerModeFieldProps<T> = {
   field: T;
   onClick?: () => void;
-  validateUninsertedField?: boolean;
 };
 
-export function FieldContainerPortal({
-  field,
-  children,
-  className = '',
-}: FieldContainerPortalProps) {
-  const coords = useFieldPageCoords(field);
-
-  return createPortal(
-    <div
-      className={cn('absolute', className)}
-      style={{
-        top: `${coords.y}px`,
-        left: `${coords.x}px`,
-        height: `${coords.height}px`,
-        width: `${coords.width}px`,
-      }}
-    >
-      {children}
-    </div>,
-    document.body,
-  );
-}
-
 export function SinglePlayerModeFieldCardContainer({
   field,
   children,
-  validateUninsertedField = false,
 }: SinglePlayerModeFieldContainerProps) {
   return (
-    <FieldContainerPortal field={field}>
+    <FieldRootContainer field={field}>
-      <motion.div className="h-full w-full" animate={{ opacity: 1 }} exit={{ opacity: 0 }}>
+      <AnimatePresence mode="wait" initial={false}>
-        <Card
+        <motion.div
-          id={`field-${field.id}`}
+          key={field.inserted ? 'inserted' : 'not-inserted'}
-          className={cn('bg-background relative z-20 h-full w-full transition-all', {
+          initial={{ opacity: 0 }}
-            'border-orange-300 ring-1 ring-orange-300': !field.inserted && validateUninsertedField,
+          animate={{
-          })}
+            opacity: 1,
-          data-inserted={field.inserted ? 'true' : 'false'}
+          }}
+          exit={{ opacity: 0 }}
+          transition={{
+            duration: 0.2,
+            ease: 'easeIn',
+          }}
         >
-          <CardContent className="text-foreground hover:shadow-primary-foreground group flex h-full w-full flex-col items-center justify-center p-2">
+          {children}
-            <AnimatePresence mode="wait" initial={false}>
+        </motion.div>
-              <motion.div
+      </AnimatePresence>
-                key={field.inserted ? 'inserted' : 'not-inserted'}
+    </FieldRootContainer>
-                initial={{ opacity: 0 }}
-                animate={{
-                  opacity: 1,
-                }}
-                exit={{ opacity: 0 }}
-                transition={{
-                  duration: 0.2,
-                  ease: 'easeIn',
-                }}
-              >
-                {children}
-              </motion.div>
-            </AnimatePresence>
-          </CardContent>
-        </Card>
-      </motion.div>
-    </FieldContainerPortal>
   );
 }
 
 export function SinglePlayerModeSignatureField({
   field,
-  validateUninsertedField,
   onClick,
 }: SinglePlayerModeFieldProps<FieldWithSignature>) {
   const fontVariable = '--font-signature';
@@ -136,10 +89,7 @@ export function SinglePlayerModeSignatureField({
   const insertedTypeSignature = field.inserted && field.Signature?.typedSignature;
 
   return (
-    <SinglePlayerModeFieldCardContainer
+    <SinglePlayerModeFieldCardContainer field={field}>
-      validateUninsertedField={validateUninsertedField}
-      field={field}
-    >
       {insertedBase64Signature ? (
         <img
           src={insertedBase64Signature}
@@ -171,7 +121,6 @@ export function SinglePlayerModeSignatureField({
 
 export function SinglePlayerModeCustomTextField({
   field,
-  validateUninsertedField,
   onClick,
 }: SinglePlayerModeFieldProps<Field>) {
   const fontVariable = '--font-sans';
@@ -203,10 +152,7 @@ export function SinglePlayerModeCustomTextField({
   const fontSize = maxFontSize * scalingFactor;
 
   return (
-    <SinglePlayerModeFieldCardContainer
+    <SinglePlayerModeFieldCardContainer field={field}>
-      validateUninsertedField={validateUninsertedField}
-      field={field}
-    >
       {field.inserted ? (
         <p
           ref={$paragraphEl}