feat: assistant role (#1588)

## Description

Introduces the ability for users with the **Assistant** role to prefill
fields on behalf of other signers. Assistants can fill in various field
types such as text, checkboxes, dates, and more, streamlining the
document preparation process before it reaches the final signers.

https://github.com/user-attachments/assets/c1321578-47ec-405b-a70a-7d9578385895

apps/web/src/app/(signing)/sign/[token]/signing-page-view.tsx

@@ -1,3 +1,7 @@
+'use client';
+
+import { useState } from 'react';
+
 import { Trans } from '@lingui/macro';
 import { match } from 'ts-pattern';
 
@@ -13,9 +17,10 @@ import {
   ZTextFieldMeta,
 } from '@documenso/lib/types/field-meta';
 import type { CompletedField } from '@documenso/lib/types/fields';
-import type { Field, Recipient } from '@documenso/prisma/client';
+import type { Field } from '@documenso/prisma/client';
 import { FieldType, RecipientRole } from '@documenso/prisma/client';
 import type { FieldWithSignatureAndFieldMeta } from '@documenso/prisma/types/field-with-signature-and-fieldmeta';
+import type { RecipientWithFields } from '@documenso/prisma/types/recipient-with-fields';
 import { Card, CardContent } from '@documenso/ui/primitives/card';
 import { ElementVisible } from '@documenso/ui/primitives/element-visible';
 import { LazyPDFViewer } from '@documenso/ui/primitives/lazy-pdf-viewer';
@@ -32,16 +37,18 @@ import { InitialsField } from './initials-field';
 import { NameField } from './name-field';
 import { NumberField } from './number-field';
 import { RadioField } from './radio-field';
+import { RecipientProvider } from './recipient-context';
 import { RejectDocumentDialog } from './reject-document-dialog';
 import { SignatureField } from './signature-field';
 import { TextField } from './text-field';
 
 export type SigningPageViewProps = {
   document: DocumentAndSender;
-  recipient: Recipient;
+  recipient: RecipientWithFields;
   fields: Field[];
   completedFields: CompletedField[];
   isRecipientsTurn: boolean;
+  allRecipients?: RecipientWithFields[];
 };
 
 export const SigningPageView = ({
@@ -50,9 +57,12 @@ export const SigningPageView = ({
   fields,
   completedFields,
   isRecipientsTurn,
+  allRecipients = [],
 }: SigningPageViewProps) => {
   const { documentData, documentMeta } = document;
 
+  const [selectedSignerId, setSelectedSignerId] = useState<number | null>(allRecipients?.[0]?.id);
+
   const shouldUseTeamDetails =
     document.teamId && document.team?.teamGlobalSettings?.includeSenderDetails === false;
 
@@ -64,153 +74,162 @@ export const SigningPageView = ({
     senderEmail = document.team?.teamEmail?.email ? `(${document.team.teamEmail.email})` : '';
   }
 
+  const selectedSigner = allRecipients?.find((r) => r.id === selectedSignerId);
+
   return (
-    <div className="mx-auto w-full max-w-screen-xl">
-      <h1
-        className="mt-4 block max-w-[20rem] truncate text-2xl font-semibold md:max-w-[30rem] md:text-3xl"
-        title={document.title}
-      >
-        {document.title}
-      </h1>
-
-      <div className="mt-2.5 flex flex-wrap items-center justify-between gap-x-6">
-        <div className="max-w-[50ch]">
-          <span className="text-muted-foreground truncate" title={senderName}>
-            {senderName} {senderEmail}
-          </span>{' '}
-          <span className="text-muted-foreground">
-            {match(recipient.role)
-              .with(RecipientRole.VIEWER, () =>
-                document.teamId && !shouldUseTeamDetails ? (
-                  <Trans>
-                    on behalf of "{document.team?.name}" has invited you to view this document
-                  </Trans>
-                ) : (
-                  <Trans>has invited you to view this document</Trans>
-                ),
-              )
-              .with(RecipientRole.SIGNER, () =>
-                document.teamId && !shouldUseTeamDetails ? (
-                  <Trans>
-                    on behalf of "{document.team?.name}" has invited you to sign this document
-                  </Trans>
-                ) : (
-                  <Trans>has invited you to sign this document</Trans>
-                ),
-              )
-              .with(RecipientRole.APPROVER, () =>
-                document.teamId && !shouldUseTeamDetails ? (
-                  <Trans>
-                    on behalf of "{document.team?.name}" has invited you to approve this document
-                  </Trans>
-                ) : (
-                  <Trans>has invited you to approve this document</Trans>
-                ),
-              )
-              .otherwise(() => null)}
-          </span>
-        </div>
-
-        <RejectDocumentDialog document={document} token={recipient.token} />
-      </div>
-
-      <div className="mt-8 grid grid-cols-12 gap-y-8 lg:gap-x-8 lg:gap-y-0">
-        <Card
-          className="col-span-12 rounded-xl before:rounded-xl lg:col-span-7 xl:col-span-8"
-          gradient
+    <RecipientProvider recipient={recipient} targetSigner={selectedSigner ?? null}>
+      <div className="mx-auto w-full max-w-screen-xl">
+        <h1
+          className="mt-4 block max-w-[20rem] truncate text-2xl font-semibold md:max-w-[30rem] md:text-3xl"
+          title={document.title}
         >
-          <CardContent className="p-2">
-            <LazyPDFViewer
-              key={documentData.id}
-              documentData={documentData}
-              document={document}
-              password={documentMeta?.password}
-            />
-          </CardContent>
-        </Card>
+          {document.title}
+        </h1>
 
-        <div className="col-span-12 lg:col-span-5 xl:col-span-4">
-          <SigningForm
-            document={document}
-            recipient={recipient}
-            fields={fields}
-            redirectUrl={documentMeta?.redirectUrl}
-            isRecipientsTurn={isRecipientsTurn}
-          />
+        <div className="mt-2.5 flex flex-wrap items-center justify-between gap-x-6">
+          <div className="max-w-[50ch]">
+            <span className="text-muted-foreground truncate" title={senderName}>
+              {senderName} {senderEmail}
+            </span>{' '}
+            <span className="text-muted-foreground">
+              {match(recipient.role)
+                .with(RecipientRole.VIEWER, () =>
+                  document.teamId && !shouldUseTeamDetails ? (
+                    <Trans>
+                      on behalf of "{document.team?.name}" has invited you to view this document
+                    </Trans>
+                  ) : (
+                    <Trans>has invited you to view this document</Trans>
+                  ),
+                )
+                .with(RecipientRole.SIGNER, () =>
+                  document.teamId && !shouldUseTeamDetails ? (
+                    <Trans>
+                      on behalf of "{document.team?.name}" has invited you to sign this document
+                    </Trans>
+                  ) : (
+                    <Trans>has invited you to sign this document</Trans>
+                  ),
+                )
+                .with(RecipientRole.APPROVER, () =>
+                  document.teamId && !shouldUseTeamDetails ? (
+                    <Trans>
+                      on behalf of "{document.team?.name}" has invited you to approve this document
+                    </Trans>
+                  ) : (
+                    <Trans>has invited you to approve this document</Trans>
+                  ),
+                )
+                .with(RecipientRole.ASSISTANT, () =>
+                  document.teamId && !shouldUseTeamDetails ? (
+                    <Trans>
+                      on behalf of "{document.team?.name}" has invited you to assist this document
+                    </Trans>
+                  ) : (
+                    <Trans>has invited you to assist this document</Trans>
+                  ),
+                )
+                .otherwise(() => null)}
+            </span>
+          </div>
+
+          <RejectDocumentDialog document={document} token={recipient.token} />
         </div>
-      </div>
 
-      <DocumentReadOnlyFields fields={completedFields} />
-
-      <AutoSign recipient={recipient} fields={fields} />
-
-      <ElementVisible target={PDF_VIEWER_PAGE_SELECTOR}>
-        {fields.map((field) =>
-          match(field.type)
-            .with(FieldType.SIGNATURE, () => (
-              <SignatureField
-                key={field.id}
-                field={field}
-                recipient={recipient}
-                typedSignatureEnabled={documentMeta?.typedSignatureEnabled}
+        <div className="mt-8 grid grid-cols-12 gap-y-8 lg:gap-x-8 lg:gap-y-0">
+          <Card
+            className="col-span-12 rounded-xl before:rounded-xl lg:col-span-7 xl:col-span-8"
+            gradient
+          >
+            <CardContent className="p-2">
+              <LazyPDFViewer
+                key={documentData.id}
+                documentData={documentData}
+                document={document}
+                password={documentMeta?.password}
               />
-            ))
-            .with(FieldType.INITIALS, () => (
-              <InitialsField key={field.id} field={field} recipient={recipient} />
-            ))
-            .with(FieldType.NAME, () => (
-              <NameField key={field.id} field={field} recipient={recipient} />
-            ))
-            .with(FieldType.DATE, () => (
-              <DateField
-                key={field.id}
-                field={field}
-                recipient={recipient}
-                dateFormat={documentMeta?.dateFormat ?? DEFAULT_DOCUMENT_DATE_FORMAT}
-                timezone={documentMeta?.timezone ?? DEFAULT_DOCUMENT_TIME_ZONE}
-              />
-            ))
-            .with(FieldType.EMAIL, () => (
-              <EmailField key={field.id} field={field} recipient={recipient} />
-            ))
-            .with(FieldType.TEXT, () => {
-              const fieldWithMeta: FieldWithSignatureAndFieldMeta = {
-                ...field,
-                fieldMeta: field.fieldMeta ? ZTextFieldMeta.parse(field.fieldMeta) : null,
-              };
-              return <TextField key={field.id} field={fieldWithMeta} recipient={recipient} />;
-            })
-            .with(FieldType.NUMBER, () => {
-              const fieldWithMeta: FieldWithSignatureAndFieldMeta = {
-                ...field,
-                fieldMeta: field.fieldMeta ? ZNumberFieldMeta.parse(field.fieldMeta) : null,
-              };
-              return <NumberField key={field.id} field={fieldWithMeta} recipient={recipient} />;
-            })
-            .with(FieldType.RADIO, () => {
-              const fieldWithMeta: FieldWithSignatureAndFieldMeta = {
-                ...field,
-                fieldMeta: field.fieldMeta ? ZRadioFieldMeta.parse(field.fieldMeta) : null,
-              };
-              return <RadioField key={field.id} field={fieldWithMeta} recipient={recipient} />;
-            })
-            .with(FieldType.CHECKBOX, () => {
-              const fieldWithMeta: FieldWithSignatureAndFieldMeta = {
-                ...field,
-                fieldMeta: field.fieldMeta ? ZCheckboxFieldMeta.parse(field.fieldMeta) : null,
-              };
-              return <CheckboxField key={field.id} field={fieldWithMeta} recipient={recipient} />;
-            })
-            .with(FieldType.DROPDOWN, () => {
-              const fieldWithMeta: FieldWithSignatureAndFieldMeta = {
-                ...field,
-                fieldMeta: field.fieldMeta ? ZDropdownFieldMeta.parse(field.fieldMeta) : null,
-              };
-              return <DropdownField key={field.id} field={fieldWithMeta} recipient={recipient} />;
-            })
-            .otherwise(() => null),
+            </CardContent>
+          </Card>
+
+          <div className="col-span-12 lg:col-span-5 xl:col-span-4">
+            <SigningForm
+              document={document}
+              recipient={recipient}
+              fields={fields}
+              redirectUrl={documentMeta?.redirectUrl}
+              isRecipientsTurn={isRecipientsTurn}
+              allRecipients={allRecipients}
+              setSelectedSignerId={setSelectedSignerId}
+            />
+          </div>
+        </div>
+
+        <DocumentReadOnlyFields fields={completedFields} />
+
+        {recipient.role !== RecipientRole.ASSISTANT && (
+          <AutoSign recipient={recipient} fields={fields} />
         )}
-      </ElementVisible>
-    </div>
+
+        <ElementVisible target={PDF_VIEWER_PAGE_SELECTOR}>
+          {fields
+            .filter(
+              (field) =>
+                recipient.role !== RecipientRole.ASSISTANT ||
+                field.recipientId === selectedSigner?.id,
+            )
+            .map((field) =>
+              match(field.type)
+                .with(FieldType.SIGNATURE, () => <SignatureField key={field.id} field={field} />)
+                .with(FieldType.INITIALS, () => <InitialsField key={field.id} field={field} />)
+                .with(FieldType.NAME, () => <NameField key={field.id} field={field} />)
+                .with(FieldType.DATE, () => (
+                  <DateField
+                    key={field.id}
+                    field={field}
+                    dateFormat={documentMeta?.dateFormat ?? DEFAULT_DOCUMENT_DATE_FORMAT}
+                    timezone={documentMeta?.timezone ?? DEFAULT_DOCUMENT_TIME_ZONE}
+                  />
+                ))
+                .with(FieldType.EMAIL, () => <EmailField key={field.id} field={field} />)
+                .with(FieldType.TEXT, () => {
+                  const fieldWithMeta: FieldWithSignatureAndFieldMeta = {
+                    ...field,
+                    fieldMeta: field.fieldMeta ? ZTextFieldMeta.parse(field.fieldMeta) : null,
+                  };
+                  return <TextField key={field.id} field={fieldWithMeta} />;
+                })
+                .with(FieldType.NUMBER, () => {
+                  const fieldWithMeta: FieldWithSignatureAndFieldMeta = {
+                    ...field,
+                    fieldMeta: field.fieldMeta ? ZNumberFieldMeta.parse(field.fieldMeta) : null,
+                  };
+                  return <NumberField key={field.id} field={fieldWithMeta} />;
+                })
+                .with(FieldType.RADIO, () => {
+                  const fieldWithMeta: FieldWithSignatureAndFieldMeta = {
+                    ...field,
+                    fieldMeta: field.fieldMeta ? ZRadioFieldMeta.parse(field.fieldMeta) : null,
+                  };
+                  return <RadioField key={field.id} field={fieldWithMeta} />;
+                })
+                .with(FieldType.CHECKBOX, () => {
+                  const fieldWithMeta: FieldWithSignatureAndFieldMeta = {
+                    ...field,
+                    fieldMeta: field.fieldMeta ? ZCheckboxFieldMeta.parse(field.fieldMeta) : null,
+                  };
+                  return <CheckboxField key={field.id} field={fieldWithMeta} />;
+                })
+                .with(FieldType.DROPDOWN, () => {
+                  const fieldWithMeta: FieldWithSignatureAndFieldMeta = {
+                    ...field,
+                    fieldMeta: field.fieldMeta ? ZDropdownFieldMeta.parse(field.fieldMeta) : null,
+                  };
+                  return <DropdownField key={field.id} field={fieldWithMeta} />;
+                })
+                .otherwise(() => null),
+            )}
+        </ElementVisible>
+      </div>
+    </RecipientProvider>
   );
 };