feat: add template enhancements (#1154)

## Description

General enhancements for templates.

## Changes Made

Added the following changes to the template flow:
- Allow adding document meta settings
- Allow adding email settings
- Allow adding document access & action authentication
- Allow adding recipient action authentication
- Save the state between template steps similar to how it works for
documents

Other changes:
- Extract common fields between document and template flows
- Remove the title field from "Use template" since we now have it as
part of the template flow
- Add new API endpoint for generating templates

## Testing Performed

Added E2E tests for templates and creating documents from templates

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

@@ -7,16 +7,18 @@ import { InfoIcon } from 'lucide-react';
 import { useForm } from 'react-hook-form';
 
 import { DATE_FORMATS, DEFAULT_DOCUMENT_DATE_FORMAT } from '@documenso/lib/constants/date-formats';
-import { DOCUMENT_AUTH_TYPES } from '@documenso/lib/constants/document-auth';
 import { DEFAULT_DOCUMENT_TIME_ZONE, TIME_ZONES } from '@documenso/lib/constants/time-zones';
-import {
-  DocumentAccessAuth,
-  DocumentActionAuth,
-  DocumentAuth,
-} from '@documenso/lib/types/document-auth';
 import { extractDocumentAuthMethods } from '@documenso/lib/utils/document-auth';
 import { DocumentStatus, type Field, type Recipient, SendStatus } from '@documenso/prisma/client';
 import type { DocumentWithData } from '@documenso/prisma/types/document-with-data';
+import {
+  DocumentGlobalAuthAccessSelect,
+  DocumentGlobalAuthAccessTooltip,
+} from '@documenso/ui/components/document/document-global-auth-access-select';
+import {
+  DocumentGlobalAuthActionSelect,
+  DocumentGlobalAuthActionTooltip,
+} from '@documenso/ui/components/document/document-global-auth-action-select';
 import {
   Accordion,
   AccordionContent,
@@ -144,49 +146,11 @@ export const AddSettingsFormPartial = ({
                 <FormItem>
                   <FormLabel className="flex flex-row items-center">
                     Document access
-                    <Tooltip>
-                      <TooltipTrigger>
-                        <InfoIcon className="mx-2 h-4 w-4" />
-                      </TooltipTrigger>
-
-                      <TooltipContent className="text-foreground max-w-md space-y-2 p-4">
-                        <h2>
-                          <strong>Document access</strong>
-                        </h2>
-
-                        <p>The authentication required for recipients to view the document.</p>
-
-                        <ul className="ml-3.5 list-outside list-disc space-y-0.5 py-2">
-                          <li>
-                            <strong>Require account</strong> - The recipient must be signed in to
-                            view the document
-                          </li>
-                          <li>
-                            <strong>None</strong> - The document can be accessed directly by the URL
-                            sent to the recipient
-                          </li>
-                        </ul>
-                      </TooltipContent>
-                    </Tooltip>
+                    <DocumentGlobalAuthAccessTooltip />
                   </FormLabel>
 
                   <FormControl>
-                    <Select {...field} onValueChange={field.onChange}>
-                      <SelectTrigger className="bg-background text-muted-foreground">
-                        <SelectValue data-testid="documentAccessSelectValue" placeholder="None" />
-                      </SelectTrigger>
-
-                      <SelectContent position="popper">
-                        {Object.values(DocumentAccessAuth).map((authType) => (
-                          <SelectItem key={authType} value={authType}>
-                            {DOCUMENT_AUTH_TYPES[authType].value}
-                          </SelectItem>
-                        ))}
-
-                        {/* Note: -1 is remapped in the Zod schema to the required value. */}
-                        <SelectItem value={'-1'}>None</SelectItem>
-                      </SelectContent>
-                    </Select>
+                    <DocumentGlobalAuthAccessSelect {...field} onValueChange={field.onChange} />
                   </FormControl>
                 </FormItem>
               )}
@@ -200,64 +164,11 @@ export const AddSettingsFormPartial = ({
                   <FormItem>
                     <FormLabel className="flex flex-row items-center">
                       Recipient action authentication
-                      <Tooltip>
-                        <TooltipTrigger>
-                          <InfoIcon className="mx-2 h-4 w-4" />
-                        </TooltipTrigger>
-
-                        <TooltipContent className="text-foreground max-w-md space-y-2 p-4">
-                          <h2>
-                            <strong>Global recipient action authentication</strong>
-                          </h2>
-
-                          <p>
-                            The authentication required for recipients to sign the signature field.
-                          </p>
-
-                          <p>
-                            This can be overriden by setting the authentication requirements
-                            directly on each recipient in the next step.
-                          </p>
-
-                          <ul className="ml-3.5 list-outside list-disc space-y-0.5 py-2">
-                            {/* <li>
-                              <strong>Require account</strong> - The recipient must be signed in
-                            </li> */}
-                            <li>
-                              <strong>Require passkey</strong> - The recipient must have an account
-                              and passkey configured via their settings
-                            </li>
-                            <li>
-                              <strong>Require 2FA</strong> - The recipient must have an account and
-                              2FA enabled via their settings
-                            </li>
-                            <li>
-                              <strong>None</strong> - No authentication required
-                            </li>
-                          </ul>
-                        </TooltipContent>
-                      </Tooltip>
+                      <DocumentGlobalAuthActionTooltip />
                     </FormLabel>
 
                     <FormControl>
-                      <Select {...field} onValueChange={field.onChange}>
-                        <SelectTrigger className="bg-background text-muted-foreground">
-                          <SelectValue data-testid="documentActionSelectValue" placeholder="None" />
-                        </SelectTrigger>
-
-                        <SelectContent position="popper">
-                          {Object.values(DocumentActionAuth)
-                            .filter((auth) => auth !== DocumentAuth.ACCOUNT)
-                            .map((authType) => (
-                              <SelectItem key={authType} value={authType}>
-                                {DOCUMENT_AUTH_TYPES[authType].value}
-                              </SelectItem>
-                            ))}
-
-                          {/* Note: -1 is remapped in the Zod schema to the required value. */}
-                          <SelectItem value={'-1'}>None</SelectItem>
-                        </SelectContent>
-                      </Select>
+                      <DocumentGlobalAuthActionSelect {...field} onValueChange={field.onChange} />
                     </FormControl>
                   </FormItem>
                 )}

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

@@ -6,6 +6,7 @@ import { useForm } from 'react-hook-form';
 import type { Field, Recipient } from '@documenso/prisma/client';
 import { DocumentStatus } from '@documenso/prisma/client';
 import type { DocumentWithData } from '@documenso/prisma/types/document-with-data';
+import { DocumentSendEmailMessageHelper } from '@documenso/ui/components/document/document-send-email-message-helper';
 
 import { FormErrorMessage } from '../form/form-error-message';
 import { Input } from '../input';
@@ -104,32 +105,7 @@ export const AddSubjectFormPartial = ({
               />
             </div>
 
-            <div>
-              <p className="text-muted-foreground text-sm">
-                You can use the following variables in your message:
-              </p>
-
-              <ul className="mt-2 flex list-inside list-disc flex-col gap-y-2 text-sm">
-                <li className="text-muted-foreground">
-                  <code className="text-muted-foreground bg-muted-foreground/20 rounded p-1 text-sm">
-                    {'{signer.name}'}
-                  </code>{' '}
-                  - The signer's name
-                </li>
-                <li className="text-muted-foreground">
-                  <code className="text-muted-foreground bg-muted-foreground/20 rounded p-1 text-sm">
-                    {'{signer.email}'}
-                  </code>{' '}
-                  - The signer's email
-                </li>
-                <li className="text-muted-foreground">
-                  <code className="text-muted-foreground bg-muted-foreground/20 rounded p-1 text-sm">
-                    {'{document.name}'}
-                  </code>{' '}
-                  - The document's name
-                </li>
-              </ul>
-            </div>
+            <DocumentSendEmailMessageHelper />
           </div>
         </div>
       </DocumentFlowFormContainerContent>

packages/ui/primitives/template-flow/add-template-placeholder-recipients.tsx

@@ -26,6 +26,7 @@ import {
   DocumentFlowFormContainerFooter,
   DocumentFlowFormContainerStep,
 } from '../document-flow/document-flow-root';
+import { ShowFieldItem } from '../document-flow/show-field-item';
 import type { DocumentFlowStep } from '../document-flow/types';
 import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '../form/form';
 import { useStep } from '../stepper';
@@ -36,15 +37,17 @@ export type AddTemplatePlaceholderRecipientsFormProps = {
   documentFlow: DocumentFlowStep;
   recipients: Recipient[];
   fields: Field[];
-  isTemplateOwnerEnterprise: boolean;
+  isEnterprise: boolean;
+  isDocumentPdfLoaded: boolean;
   onSubmit: (_data: TAddTemplatePlacholderRecipientsFormSchema) => void;
 };
 
 export const AddTemplatePlaceholderRecipientsFormPartial = ({
   documentFlow,
-  isTemplateOwnerEnterprise,
+  isEnterprise,
   recipients,
-  fields: _fields,
+  fields,
+  isDocumentPdfLoaded,
   onSubmit,
 }: AddTemplatePlaceholderRecipientsFormProps) => {
   const initialId = useId();
@@ -144,6 +147,11 @@ export const AddTemplatePlaceholderRecipientsFormPartial = ({
   return (
     <>
       <DocumentFlowFormContainerContent>
+        {isDocumentPdfLoaded &&
+          fields.map((field, index) => (
+            <ShowFieldItem key={index} field={field} recipients={recipients} />
+          ))}
+
         <AnimateGenericFadeInOut motionKey={showAdvancedSettings ? 'Show' : 'Hide'}>
           <Form {...form}>
             <div className="flex w-full flex-col gap-y-2">
@@ -209,7 +217,7 @@ export const AddTemplatePlaceholderRecipientsFormPartial = ({
                     )}
                   />
 
-                  {showAdvancedSettings && isTemplateOwnerEnterprise && (
+                  {showAdvancedSettings && isEnterprise && (
                     <FormField
                       control={form.control}
                       name={`signers.${index}.actionAuth`}
@@ -294,7 +302,7 @@ export const AddTemplatePlaceholderRecipientsFormPartial = ({
               </Button>
             </div>
 
-            {!alwaysShowAdvancedSettings && isTemplateOwnerEnterprise && (
+            {!alwaysShowAdvancedSettings && isEnterprise && (
               <div className="mt-4 flex flex-row items-center">
                 <Checkbox
                   id="showAdvancedRecipientSettings"

packages/ui/primitives/template-flow/add-template-settings.tsx

@@ -0,0 +1,326 @@
+'use client';
+
+import { useEffect } from 'react';
+
+import { zodResolver } from '@hookform/resolvers/zod';
+import { InfoIcon } from 'lucide-react';
+import { useForm } from 'react-hook-form';
+
+import { DATE_FORMATS, DEFAULT_DOCUMENT_DATE_FORMAT } from '@documenso/lib/constants/date-formats';
+import { DEFAULT_DOCUMENT_TIME_ZONE, TIME_ZONES } from '@documenso/lib/constants/time-zones';
+import { extractDocumentAuthMethods } from '@documenso/lib/utils/document-auth';
+import { type Field, type Recipient } from '@documenso/prisma/client';
+import type { TemplateWithData } from '@documenso/prisma/types/template';
+import {
+  DocumentGlobalAuthAccessSelect,
+  DocumentGlobalAuthAccessTooltip,
+} from '@documenso/ui/components/document/document-global-auth-access-select';
+import {
+  DocumentGlobalAuthActionSelect,
+  DocumentGlobalAuthActionTooltip,
+} from '@documenso/ui/components/document/document-global-auth-action-select';
+import { DocumentSendEmailMessageHelper } from '@documenso/ui/components/document/document-send-email-message-helper';
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from '@documenso/ui/primitives/accordion';
+import {
+  Form,
+  FormControl,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from '@documenso/ui/primitives/form/form';
+
+import { Combobox } from '../combobox';
+import {
+  DocumentFlowFormContainerActions,
+  DocumentFlowFormContainerContent,
+  DocumentFlowFormContainerFooter,
+  DocumentFlowFormContainerStep,
+} from '../document-flow/document-flow-root';
+import { ShowFieldItem } from '../document-flow/show-field-item';
+import type { DocumentFlowStep } from '../document-flow/types';
+import { Input } from '../input';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '../select';
+import { useStep } from '../stepper';
+import { Textarea } from '../textarea';
+import { Tooltip, TooltipContent, TooltipTrigger } from '../tooltip';
+import type { TAddTemplateSettingsFormSchema } from './add-template-settings.types';
+import { ZAddTemplateSettingsFormSchema } from './add-template-settings.types';
+
+export type AddTemplateSettingsFormProps = {
+  documentFlow: DocumentFlowStep;
+  recipients: Recipient[];
+  fields: Field[];
+  isEnterprise: boolean;
+  isDocumentPdfLoaded: boolean;
+  template: TemplateWithData;
+  onSubmit: (_data: TAddTemplateSettingsFormSchema) => void;
+};
+
+export const AddTemplateSettingsFormPartial = ({
+  documentFlow,
+  recipients,
+  fields,
+  isEnterprise,
+  isDocumentPdfLoaded,
+  template,
+  onSubmit,
+}: AddTemplateSettingsFormProps) => {
+  const { documentAuthOption } = extractDocumentAuthMethods({
+    documentAuth: template.authOptions,
+  });
+
+  const form = useForm<TAddTemplateSettingsFormSchema>({
+    resolver: zodResolver(ZAddTemplateSettingsFormSchema),
+    defaultValues: {
+      title: template.title,
+      globalAccessAuth: documentAuthOption?.globalAccessAuth || undefined,
+      globalActionAuth: documentAuthOption?.globalActionAuth || undefined,
+      meta: {
+        subject: template.templateMeta?.subject ?? '',
+        message: template.templateMeta?.message ?? '',
+        timezone: template.templateMeta?.timezone ?? DEFAULT_DOCUMENT_TIME_ZONE,
+        dateFormat: template.templateMeta?.dateFormat ?? DEFAULT_DOCUMENT_DATE_FORMAT,
+        redirectUrl: template.templateMeta?.redirectUrl ?? '',
+      },
+    },
+  });
+
+  const { stepIndex, currentStep, totalSteps, previousStep } = useStep();
+
+  // We almost always want to set the timezone to the user's local timezone to avoid confusion
+  // when the document is signed.
+  useEffect(() => {
+    if (!form.formState.touchedFields.meta?.timezone) {
+      form.setValue('meta.timezone', Intl.DateTimeFormat().resolvedOptions().timeZone);
+    }
+  }, [form, form.setValue, form.formState.touchedFields.meta?.timezone]);
+
+  return (
+    <>
+      <DocumentFlowFormContainerContent>
+        {isDocumentPdfLoaded &&
+          fields.map((field, index) => (
+            <ShowFieldItem key={index} field={field} recipients={recipients} />
+          ))}
+
+        <Form {...form}>
+          <fieldset
+            className="flex h-full flex-col space-y-6"
+            disabled={form.formState.isSubmitting}
+          >
+            <FormField
+              control={form.control}
+              name="title"
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel required>Template title</FormLabel>
+
+                  <FormControl>
+                    <Input className="bg-background" {...field} />
+                  </FormControl>
+                  <FormMessage />
+                </FormItem>
+              )}
+            />
+
+            <FormField
+              control={form.control}
+              name="globalAccessAuth"
+              render={({ field }) => (
+                <FormItem>
+                  <FormLabel className="flex flex-row items-center">
+                    Document access
+                    <DocumentGlobalAuthAccessTooltip />
+                  </FormLabel>
+
+                  <FormControl>
+                    <DocumentGlobalAuthAccessSelect {...field} onValueChange={field.onChange} />
+                  </FormControl>
+                </FormItem>
+              )}
+            />
+
+            {isEnterprise && (
+              <FormField
+                control={form.control}
+                name="globalActionAuth"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel className="flex flex-row items-center">
+                      Recipient action authentication
+                      <DocumentGlobalAuthActionTooltip />
+                    </FormLabel>
+
+                    <FormControl>
+                      <DocumentGlobalAuthActionSelect {...field} onValueChange={field.onChange} />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+            )}
+
+            <Accordion type="multiple">
+              <AccordionItem value="email-options" className="border-none">
+                <AccordionTrigger className="text-foreground rounded border px-3 py-2 text-left hover:bg-neutral-200/30 hover:no-underline">
+                  Email Options
+                </AccordionTrigger>
+
+                <AccordionContent className="text-muted-foreground -mx-1 px-1 pt-4 text-sm leading-relaxed [&>div]:pb-0">
+                  <div className="flex flex-col space-y-6">
+                    <FormField
+                      control={form.control}
+                      name="meta.subject"
+                      render={({ field }) => (
+                        <FormItem>
+                          <FormLabel>
+                            Subject <span className="text-muted-foreground">(Optional)</span>
+                          </FormLabel>
+
+                          <FormControl>
+                            <Input {...field} />
+                          </FormControl>
+
+                          <FormMessage />
+                        </FormItem>
+                      )}
+                    />
+
+                    <FormField
+                      control={form.control}
+                      name="meta.message"
+                      render={({ field }) => (
+                        <FormItem>
+                          <FormLabel>
+                            Message <span className="text-muted-foreground">(Optional)</span>
+                          </FormLabel>
+
+                          <FormControl>
+                            <Textarea className="bg-background h-32 resize-none" {...field} />
+                          </FormControl>
+
+                          <FormMessage />
+                        </FormItem>
+                      )}
+                    />
+
+                    <DocumentSendEmailMessageHelper />
+                  </div>
+                </AccordionContent>
+              </AccordionItem>
+            </Accordion>
+
+            <Accordion type="multiple">
+              <AccordionItem value="advanced-options" className="border-none">
+                <AccordionTrigger className="text-foreground rounded border px-3 py-2 text-left hover:bg-neutral-200/30 hover:no-underline">
+                  Advanced Options
+                </AccordionTrigger>
+
+                <AccordionContent className="text-muted-foreground -mx-1 px-1 pt-4 text-sm leading-relaxed">
+                  <div className="flex flex-col space-y-6">
+                    <FormField
+                      control={form.control}
+                      name="meta.dateFormat"
+                      render={({ field }) => (
+                        <FormItem>
+                          <FormLabel>Date Format</FormLabel>
+
+                          <FormControl>
+                            <Select {...field} onValueChange={field.onChange}>
+                              <SelectTrigger className="bg-background">
+                                <SelectValue />
+                              </SelectTrigger>
+
+                              <SelectContent>
+                                {DATE_FORMATS.map((format) => (
+                                  <SelectItem key={format.key} value={format.value}>
+                                    {format.label}
+                                  </SelectItem>
+                                ))}
+                              </SelectContent>
+                            </Select>
+                          </FormControl>
+
+                          <FormMessage />
+                        </FormItem>
+                      )}
+                    />
+
+                    <FormField
+                      control={form.control}
+                      name="meta.timezone"
+                      render={({ field }) => (
+                        <FormItem>
+                          <FormLabel>Time Zone</FormLabel>
+
+                          <FormControl>
+                            <Combobox
+                              className="bg-background time-zone-field"
+                              options={TIME_ZONES}
+                              {...field}
+                              onChange={(value) => value && field.onChange(value)}
+                            />
+                          </FormControl>
+
+                          <FormMessage />
+                        </FormItem>
+                      )}
+                    />
+
+                    <FormField
+                      control={form.control}
+                      name="meta.redirectUrl"
+                      render={({ field }) => (
+                        <FormItem>
+                          <FormLabel className="flex flex-row items-center">
+                            Redirect URL{' '}
+                            <Tooltip>
+                              <TooltipTrigger>
+                                <InfoIcon className="mx-2 h-4 w-4" />
+                              </TooltipTrigger>
+
+                              <TooltipContent className="text-muted-foreground max-w-xs">
+                                Add a URL to redirect the user to once the document is signed
+                              </TooltipContent>
+                            </Tooltip>
+                          </FormLabel>
+
+                          <FormControl>
+                            <Input className="bg-background" {...field} />
+                          </FormControl>
+
+                          <FormMessage />
+                        </FormItem>
+                      )}
+                    />
+                  </div>
+                </AccordionContent>
+              </AccordionItem>
+            </Accordion>
+          </fieldset>
+        </Form>
+      </DocumentFlowFormContainerContent>
+
+      <DocumentFlowFormContainerFooter>
+        <DocumentFlowFormContainerStep
+          title={documentFlow.title}
+          step={currentStep}
+          maxStep={totalSteps}
+        />
+
+        <DocumentFlowFormContainerActions
+          loading={form.formState.isSubmitting}
+          disabled={form.formState.isSubmitting}
+          canGoBack={stepIndex !== 0}
+          onGoBackClick={previousStep}
+          onGoNextClick={form.handleSubmit(onSubmit)}
+        />
+      </DocumentFlowFormContainerFooter>
+    </>
+  );
+};

packages/ui/primitives/template-flow/add-template-settings.types.tsx

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+
+import { DEFAULT_DOCUMENT_DATE_FORMAT } from '@documenso/lib/constants/date-formats';
+import { DEFAULT_DOCUMENT_TIME_ZONE } from '@documenso/lib/constants/time-zones';
+import { URL_REGEX } from '@documenso/lib/constants/url-regex';
+import {
+  ZDocumentAccessAuthTypesSchema,
+  ZDocumentActionAuthTypesSchema,
+} from '@documenso/lib/types/document-auth';
+
+import { ZMapNegativeOneToUndefinedSchema } from '../document-flow/add-settings.types';
+
+export const ZAddTemplateSettingsFormSchema = z.object({
+  title: z.string().trim().min(1, { message: "Title can't be empty" }),
+  globalAccessAuth: ZMapNegativeOneToUndefinedSchema.pipe(
+    ZDocumentAccessAuthTypesSchema.optional(),
+  ),
+  globalActionAuth: ZMapNegativeOneToUndefinedSchema.pipe(
+    ZDocumentActionAuthTypesSchema.optional(),
+  ),
+  meta: z.object({
+    subject: z.string(),
+    message: z.string(),
+    timezone: z.string().optional().default(DEFAULT_DOCUMENT_TIME_ZONE),
+    dateFormat: z.string().optional().default(DEFAULT_DOCUMENT_DATE_FORMAT),
+    redirectUrl: z
+      .string()
+      .optional()
+      .refine((value) => value === undefined || value === '' || URL_REGEX.test(value), {
+        message: 'Please enter a valid URL',
+      }),
+  }),
+});
+
+export type TAddTemplateSettingsFormSchema = z.infer<typeof ZAddTemplateSettingsFormSchema>;