From deb3a63fb8ff6e5b7326cd5b2fd1a07a37c80df4 Mon Sep 17 00:00:00 2001
From: Catalin Pit <me+github@catalins.tech>
Date: Tue, 12 Aug 2025 13:41:23 +0300
Subject: [PATCH] feat: allow empty placeholder emails on templates (#1930)

Allow users to create template placeholders without the placeholder
emails.
---
 .../dialogs/template-use-dialog.tsx           |  7 +-
 .../template-page-view-recipients.tsx         | 16 ++++-
 packages/lib/constants/template.ts            |  4 ++
 .../trpc/server/recipient-router/schema.ts    | 21 +++++-
 .../document/document-read-only-fields.tsx    | 17 ++++-
 .../template-flow/add-template-fields.tsx     | 42 ++++++++----
 .../add-template-placeholder-recipients.tsx   | 64 ++-----------------
 ...d-template-placeholder-recipients.types.ts | 20 +++++-
 8 files changed, 108 insertions(+), 83 deletions(-)

diff --git a/apps/remix/app/components/dialogs/template-use-dialog.tsx b/apps/remix/app/components/dialogs/template-use-dialog.tsx
index 242d146b9..3d4e7ba61 100644
--- a/apps/remix/app/components/dialogs/template-use-dialog.tsx
+++ b/apps/remix/app/components/dialogs/template-use-dialog.tsx
@@ -15,6 +15,7 @@ import { APP_DOCUMENT_UPLOAD_SIZE_LIMIT } from '@documenso/lib/constants/app';
 import {
   TEMPLATE_RECIPIENT_EMAIL_PLACEHOLDER_REGEX,
   TEMPLATE_RECIPIENT_NAME_PLACEHOLDER_REGEX,
+  isTemplateRecipientEmailPlaceholder,
 } from '@documenso/lib/constants/template';
 import { AppError } from '@documenso/lib/errors/app-error';
 import { putPdfFile } from '@documenso/lib/universal/upload/put-file';
@@ -279,7 +280,11 @@ export function TemplateUseDialog({
                           <FormControl>
                             <Input
                               {...field}
-                              placeholder={recipients[index].email || _(msg`Email`)}
+                              placeholder={
+                                isTemplateRecipientEmailPlaceholder(field.value)
+                                  ? ''
+                                  : _(msg`Email`)
+                              }
                             />
                           </FormControl>
                           <FormMessage />
diff --git a/apps/remix/app/components/general/template/template-page-view-recipients.tsx b/apps/remix/app/components/general/template/template-page-view-recipients.tsx
index 0a65b3a09..3896baf11 100644
--- a/apps/remix/app/components/general/template/template-page-view-recipients.tsx
+++ b/apps/remix/app/components/general/template/template-page-view-recipients.tsx
@@ -6,6 +6,8 @@ import { PenIcon, PlusIcon } from 'lucide-react';
 import { Link } from 'react-router';
 
 import { RECIPIENT_ROLES_DESCRIPTION } from '@documenso/lib/constants/recipient-roles';
+import { isTemplateRecipientEmailPlaceholder } from '@documenso/lib/constants/template';
+import { extractInitials } from '@documenso/lib/utils/recipient-formatter';
 import { AvatarWithText } from '@documenso/ui/primitives/avatar';
 
 export type TemplatePageViewRecipientsProps = {
@@ -53,8 +55,18 @@ export const TemplatePageViewRecipients = ({
         {recipients.map((recipient) => (
           <li key={recipient.id} className="flex items-center justify-between px-4 py-2.5 text-sm">
             <AvatarWithText
-              avatarFallback={recipient.email.slice(0, 1).toUpperCase()}
-              primaryText={<p className="text-muted-foreground text-sm">{recipient.email}</p>}
+              avatarFallback={
+                isTemplateRecipientEmailPlaceholder(recipient.email)
+                  ? extractInitials(recipient.name)
+                  : recipient.email.slice(0, 1).toUpperCase()
+              }
+              primaryText={
+                isTemplateRecipientEmailPlaceholder(recipient.email) ? (
+                  <p className="text-muted-foreground text-sm">{recipient.name}</p>
+                ) : (
+                  <p className="text-muted-foreground text-sm">{recipient.email}</p>
+                )
+              }
               secondaryText={
                 <p className="text-muted-foreground/70 text-xs">
                   {_(RECIPIENT_ROLES_DESCRIPTION[recipient.role].roleName)}
diff --git a/packages/lib/constants/template.ts b/packages/lib/constants/template.ts
index 7b6848a6b..05b9795c0 100644
--- a/packages/lib/constants/template.ts
+++ b/packages/lib/constants/template.ts
@@ -3,6 +3,10 @@ import { msg } from '@lingui/core/macro';
 export const TEMPLATE_RECIPIENT_EMAIL_PLACEHOLDER_REGEX = /recipient\.\d+@documenso\.com/i;
 export const TEMPLATE_RECIPIENT_NAME_PLACEHOLDER_REGEX = /Recipient \d+/i;
 
+export const isTemplateRecipientEmailPlaceholder = (email: string) => {
+  return TEMPLATE_RECIPIENT_EMAIL_PLACEHOLDER_REGEX.test(email);
+};
+
 export const DIRECT_TEMPLATE_DOCUMENTATION = [
   {
     title: msg`Enable Direct Link Signing`,
diff --git a/packages/trpc/server/recipient-router/schema.ts b/packages/trpc/server/recipient-router/schema.ts
index 060b3a031..e7344a9da 100644
--- a/packages/trpc/server/recipient-router/schema.ts
+++ b/packages/trpc/server/recipient-router/schema.ts
@@ -1,6 +1,7 @@
 import { RecipientRole } from '@prisma/client';
 import { z } from 'zod';
 
+import { isTemplateRecipientEmailPlaceholder } from '@documenso/lib/constants/template';
 import {
   ZRecipientAccessAuthTypesSchema,
   ZRecipientActionAuthSchema,
@@ -186,7 +187,18 @@ export const ZSetTemplateRecipientsRequestSchema = z
     recipients: z.array(
       z.object({
         nativeId: z.number().optional(),
-        email: z.string().toLowerCase().email().min(1),
+        email: z
+          .string()
+          .toLowerCase()
+          .refine(
+            (email) => {
+              return (
+                isTemplateRecipientEmailPlaceholder(email) ||
+                z.string().email().safeParse(email).success
+              );
+            },
+            { message: 'Please enter a valid email address' },
+          ),
         name: z.string(),
         role: z.nativeEnum(RecipientRole),
         signingOrder: z.number().optional(),
@@ -196,9 +208,12 @@ export const ZSetTemplateRecipientsRequestSchema = z
   })
   .refine(
     (schema) => {
-      const emails = schema.recipients.map((recipient) => recipient.email);
+      // Filter out placeholder emails and only check uniqueness for actual emails
+      const nonPlaceholderEmails = schema.recipients
+        .map((recipient) => recipient.email)
+        .filter((email) => !isTemplateRecipientEmailPlaceholder(email));
 
-      return new Set(emails).size === emails.length;
+      return new Set(nonPlaceholderEmails).size === nonPlaceholderEmails.length;
     },
     // Dirty hack to handle errors when .root is populated for an array type
     { message: 'Recipients must have unique emails', path: ['recipients__root'] },
diff --git a/packages/ui/components/document/document-read-only-fields.tsx b/packages/ui/components/document/document-read-only-fields.tsx
index 80e998c26..0786357d1 100644
--- a/packages/ui/components/document/document-read-only-fields.tsx
+++ b/packages/ui/components/document/document-read-only-fields.tsx
@@ -7,6 +7,7 @@ import { SigningStatus } from '@prisma/client';
 import { Clock, EyeOffIcon } from 'lucide-react';
 
 import { PDF_VIEWER_PAGE_SELECTOR } from '@documenso/lib/constants/pdf-viewer';
+import { isTemplateRecipientEmailPlaceholder } from '@documenso/lib/constants/template';
 import type { DocumentField } from '@documenso/lib/server-only/field/get-fields-for-document';
 import { parseMessageDescriptor } from '@documenso/lib/utils/i18n';
 import { extractInitials } from '@documenso/lib/utils/recipient-formatter';
@@ -21,6 +22,18 @@ import { PopoverHover } from '@documenso/ui/primitives/popover';
 import { getRecipientColorStyles } from '../../lib/recipient-colors';
 import { FieldContent } from '../../primitives/document-flow/field-content';
 
+const getRecipientDisplayText = (recipient: { name: string; email: string }) => {
+  if (recipient.name && !isTemplateRecipientEmailPlaceholder(recipient.email)) {
+    return `${recipient.name} (${recipient.email})`;
+  }
+
+  if (recipient.name && isTemplateRecipientEmailPlaceholder(recipient.email)) {
+    return recipient.name;
+  }
+
+  return recipient.email;
+};
+
 export type DocumentReadOnlyFieldsProps = {
   fields: DocumentField[];
   documentMeta?: Pick<DocumentMeta | TemplateMeta, 'dateFormat'>;
@@ -145,9 +158,7 @@ export const DocumentReadOnlyFields = ({
                     </p>
 
                     <p className="text-muted-foreground mt-1 text-center text-xs">
-                      {field.recipient.name
-                        ? `${field.recipient.name} (${field.recipient.email})`
-                        : field.recipient.email}{' '}
+                      {getRecipientDisplayText(field.recipient)}
                     </p>
 
                     <button
diff --git a/packages/ui/primitives/template-flow/add-template-fields.tsx b/packages/ui/primitives/template-flow/add-template-fields.tsx
index 152f764aa..9dbf12ecc 100644
--- a/packages/ui/primitives/template-flow/add-template-fields.tsx
+++ b/packages/ui/primitives/template-flow/add-template-fields.tsx
@@ -24,6 +24,7 @@ import { getBoundingClientRect } from '@documenso/lib/client-only/get-bounding-c
 import { useDocumentElement } from '@documenso/lib/client-only/hooks/use-document-element';
 import { PDF_VIEWER_PAGE_SELECTOR } from '@documenso/lib/constants/pdf-viewer';
 import { RECIPIENT_ROLES_DESCRIPTION } from '@documenso/lib/constants/recipient-roles';
+import { isTemplateRecipientEmailPlaceholder } from '@documenso/lib/constants/template';
 import {
   type TFieldMetaSchema as FieldMeta,
   ZFieldMetaSchema,
@@ -593,15 +594,21 @@ export const AddTemplateFieldsFormPartial = ({
                       selectedSignerStyles?.comboxBoxTrigger,
                     )}
                   >
-                    {selectedSigner?.email && (
-                      <span className="flex-1 truncate text-left">
-                        {selectedSigner?.name} ({selectedSigner?.email})
-                      </span>
-                    )}
+                    {selectedSigner?.email &&
+                      !isTemplateRecipientEmailPlaceholder(selectedSigner.email) && (
+                        <span className="flex-1 truncate text-left">
+                          {selectedSigner?.name} ({selectedSigner?.email})
+                        </span>
+                      )}
+
+                    {selectedSigner?.email &&
+                      isTemplateRecipientEmailPlaceholder(selectedSigner.email) && (
+                        <span className="flex-1 truncate text-left">{selectedSigner?.name}</span>
+                      )}
 
                     {!selectedSigner?.email && (
                       <span className="gradie flex-1 truncate text-left">
-                        {selectedSigner?.email}
+                        No recipient selected
                       </span>
                     )}
 
@@ -657,15 +664,22 @@ export const AddTemplateFieldsFormPartial = ({
                                 'text-foreground/80': recipient === selectedSigner,
                               })}
                             >
-                              {recipient.name && (
-                                <span title={`${recipient.name} (${recipient.email})`}>
-                                  {recipient.name} ({recipient.email})
-                                </span>
-                              )}
+                              {recipient.name &&
+                                !isTemplateRecipientEmailPlaceholder(recipient.email) && (
+                                  <span title={`${recipient.name} (${recipient.email})`}>
+                                    {recipient.name} ({recipient.email})
+                                  </span>
+                                )}
 
-                              {!recipient.name && (
-                                <span title={recipient.email}>{recipient.email}</span>
-                              )}
+                              {recipient.name &&
+                                isTemplateRecipientEmailPlaceholder(recipient.email) && (
+                                  <span title={recipient.name}>{recipient.name}</span>
+                                )}
+
+                              {!recipient.name &&
+                                !isTemplateRecipientEmailPlaceholder(recipient.email) && (
+                                  <span title={recipient.email}>{recipient.email}</span>
+                                )}
                             </span>
                           </CommandItem>
                         ))}
diff --git a/packages/ui/primitives/template-flow/add-template-placeholder-recipients.tsx b/packages/ui/primitives/template-flow/add-template-placeholder-recipients.tsx
index 5016199e9..4bb66198b 100644
--- a/packages/ui/primitives/template-flow/add-template-placeholder-recipients.tsx
+++ b/packages/ui/primitives/template-flow/add-template-placeholder-recipients.tsx
@@ -14,6 +14,7 @@ import { useFieldArray, useForm } from 'react-hook-form';
 
 import { useCurrentOrganisation } from '@documenso/lib/client-only/providers/organisation';
 import { useSession } from '@documenso/lib/client-only/providers/session';
+import { isTemplateRecipientEmailPlaceholder } from '@documenso/lib/constants/template';
 import { ZRecipientAuthOptionsSchema } from '@documenso/lib/types/document-auth';
 import { nanoid } from '@documenso/lib/universal/id';
 import { generateRecipientPlaceholder } from '@documenso/lib/utils/templates';
@@ -247,62 +248,6 @@ export const AddTemplatePlaceholderRecipientsFormPartial = ({
     [form, watchedSigners, toast],
   );
 
-  const triggerDragAndDrop = useCallback(
-    (fromIndex: number, toIndex: number) => {
-      if (!$sensorApi.current) {
-        return;
-      }
-
-      const draggableId = signers[fromIndex].id;
-
-      const preDrag = $sensorApi.current.tryGetLock(draggableId);
-
-      if (!preDrag) {
-        return;
-      }
-
-      const drag = preDrag.snapLift();
-
-      setTimeout(() => {
-        // Move directly to the target index
-        if (fromIndex < toIndex) {
-          for (let i = fromIndex; i < toIndex; i++) {
-            drag.moveDown();
-          }
-        } else {
-          for (let i = fromIndex; i > toIndex; i--) {
-            drag.moveUp();
-          }
-        }
-
-        setTimeout(() => {
-          drag.drop();
-        }, 500);
-      }, 0);
-    },
-    [signers],
-  );
-
-  const updateSigningOrders = useCallback(
-    (newIndex: number, oldIndex: number) => {
-      const updatedSigners = form.getValues('signers').map((signer, index) => {
-        if (index === oldIndex) {
-          return { ...signer, signingOrder: newIndex + 1 };
-        } else if (index >= newIndex && index < oldIndex) {
-          return { ...signer, signingOrder: (signer.signingOrder ?? index + 1) + 1 };
-        } else if (index <= newIndex && index > oldIndex) {
-          return { ...signer, signingOrder: Math.max(1, (signer.signingOrder ?? index + 1) - 1) };
-        }
-        return signer;
-      });
-
-      updatedSigners.forEach((signer, index) => {
-        form.setValue(`signers.${index}.signingOrder`, signer.signingOrder);
-      });
-    },
-    [form],
-  );
-
   const handleSigningOrderChange = useCallback(
     (index: number, newOrderString: string) => {
       const trimmedOrderString = newOrderString.trim();
@@ -592,7 +537,7 @@ export const AddTemplatePlaceholderRecipientsFormPartial = ({
                                     })}
                                   >
                                     {!showAdvancedSettings && index === 0 && (
-                                      <FormLabel required>
+                                      <FormLabel>
                                         <Trans>Email</Trans>
                                       </FormLabel>
                                     )}
@@ -602,6 +547,11 @@ export const AddTemplatePlaceholderRecipientsFormPartial = ({
                                         type="email"
                                         placeholder={_(msg`Email`)}
                                         {...field}
+                                        value={
+                                          isTemplateRecipientEmailPlaceholder(field.value)
+                                            ? ''
+                                            : field.value
+                                        }
                                         disabled={
                                           field.disabled ||
                                           isSubmitting ||
diff --git a/packages/ui/primitives/template-flow/add-template-placeholder-recipients.types.ts b/packages/ui/primitives/template-flow/add-template-placeholder-recipients.types.ts
index 03b6eb240..187f99e57 100644
--- a/packages/ui/primitives/template-flow/add-template-placeholder-recipients.types.ts
+++ b/packages/ui/primitives/template-flow/add-template-placeholder-recipients.types.ts
@@ -1,6 +1,7 @@
 import { DocumentSigningOrder, RecipientRole } from '@prisma/client';
 import { z } from 'zod';
 
+import { TEMPLATE_RECIPIENT_EMAIL_PLACEHOLDER_REGEX } from '@documenso/lib/constants/template';
 import { ZRecipientActionAuthTypesSchema } from '@documenso/lib/types/document-auth';
 
 export const ZAddTemplatePlacholderRecipientsFormSchema = z
@@ -10,7 +11,7 @@ export const ZAddTemplatePlacholderRecipientsFormSchema = z
         formId: z.string().min(1),
         nativeId: z.number().optional(),
         email: z.string().min(1).email(),
-        name: z.string(),
+        name: z.string().min(1, { message: 'Name is required' }),
         role: z.nativeEnum(RecipientRole),
         signingOrder: z.number().optional(),
         actionAuth: z.array(ZRecipientActionAuthTypesSchema).optional().default([]),
@@ -21,12 +22,25 @@ export const ZAddTemplatePlacholderRecipientsFormSchema = z
   })
   .refine(
     (schema) => {
-      const emails = schema.signers.map((signer) => signer.email.toLowerCase());
+      const nonPlaceholderEmails = schema.signers
+        .map((signer) => signer.email.toLowerCase())
+        .filter((email) => !TEMPLATE_RECIPIENT_EMAIL_PLACEHOLDER_REGEX.test(email));
 
-      return new Set(emails).size === emails.length;
+      return new Set(nonPlaceholderEmails).size === nonPlaceholderEmails.length;
     },
     // Dirty hack to handle errors when .root is populated for an array type
     { message: 'Signers must have unique emails', path: ['signers__root'] },
+  )
+  .refine(
+    /*
+      Since placeholder emails are empty, we need to check that the names are unique.
+      If we don't do this, the app will add duplicate signers and merge them in the next step, where you add fields.
+    */
+    (schema) => {
+      const names = schema.signers.map((signer) => signer.name.trim());
+      return new Set(names).size === names.length;
+    },
+    { message: 'Signers must have unique names', path: ['signers__root'] },
   );
 
 export type TAddTemplatePlacholderRecipientsFormSchema = z.infer<