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
2025-11-13 08:13:56 +10:00 · 2025-02-01 03:31:18 +00:00
parent 4017b250fb
commit 332e0657e0
53 changed files with 1638 additions and 700 deletions
--- a/packages/ui/components/recipient/recipient-role-select.tsx
+++ b/packages/ui/components/recipient/recipient-role-select.tsx
@ -1,6 +1,6 @@
 'use client';

-import React, { forwardRef } from 'react';
+import { forwardRef } from 'react';

 import { Trans } from '@lingui/macro';
 import type { SelectProps } from '@radix-ui/react-select';
@ -11,12 +11,15 @@ import { ROLE_ICONS } from '@documenso/ui/primitives/recipient-role-icons';
 import { Select, SelectContent, SelectItem, SelectTrigger } from '@documenso/ui/primitives/select';
 import { Tooltip, TooltipContent, TooltipTrigger } from '@documenso/ui/primitives/tooltip';

+import { cn } from '../../lib/utils';
+
 export type RecipientRoleSelectProps = SelectProps & {
  hideCCRecipients?: boolean;
+  isAssistantEnabled?: boolean;
 };

 export const RecipientRoleSelect = forwardRef<HTMLButtonElement, RecipientRoleSelectProps>(
-  ({ hideCCRecipients, ...props }, ref) => (
+  ({ hideCCRecipients, isAssistantEnabled = true, ...props }, ref) => (
    <Select {...props}>
      <SelectTrigger ref={ref} className="bg-background w-[50px] p-2">
        {/* eslint-disable-next-line @typescript-eslint/consistent-type-assertions */}
@ -110,6 +113,42 @@ export const RecipientRoleSelect = forwardRef<HTMLButtonElement, RecipientRoleSe
            </div>
          </SelectItem>
        )}
+
+        <SelectItem
+          value={RecipientRole.ASSISTANT}
+          disabled={!isAssistantEnabled}
+          className={cn(
+            !isAssistantEnabled &&
+              'cursor-not-allowed opacity-50 data-[disabled]:pointer-events-auto',
+          )}
+        >
+          <div className="flex items-center">
+            <div className="flex w-[150px] items-center">
+              <span className="mr-2">{ROLE_ICONS[RecipientRole.ASSISTANT]}</span>
+              <Trans>Can prepare</Trans>
+            </div>
+            <Tooltip>
+              <TooltipTrigger>
+                <InfoIcon className="h-4 w-4" />
+              </TooltipTrigger>
+              <TooltipContent className="text-foreground z-9999 max-w-md p-4">
+                <p>
+                  {isAssistantEnabled ? (
+                    <Trans>
+                      The recipient can prepare the document for later signers by pre-filling
+                      suggest values.
+                    </Trans>
+                  ) : (
+                    <Trans>
+                      Assistant role is only available when the document is in sequential signing
+                      mode.
+                    </Trans>
+                  )}
+                </p>
+              </TooltipContent>
+            </Tooltip>
+          </div>
+        </SelectItem>
      </SelectContent>
    </Select>
  ),
--- a/packages/ui/primitives/document-flow/add-fields.tsx
+++ b/packages/ui/primitives/document-flow/add-fields.tsx
@ -508,7 +508,15 @@ export const AddFieldsFormPartial = ({
  }, []);

  useEffect(() => {
-    setSelectedSigner(recipients.find((r) => r.sendStatus !== SendStatus.SENT) ?? recipients[0]);
+    const recipientsByRoleToDisplay = recipients.filter(
+      (recipient) =>
+        recipient.role !== RecipientRole.CC && recipient.role !== RecipientRole.ASSISTANT,
+    );
+
+    setSelectedSigner(
+      recipientsByRoleToDisplay.find((r) => r.sendStatus !== SendStatus.SENT) ??
+        recipientsByRoleToDisplay[0],
+    );
  }, [recipients]);

  const recipientsByRole = useMemo(() => {
@ -517,6 +525,7 @@ export const AddFieldsFormPartial = ({
      VIEWER: [],
      SIGNER: [],
      APPROVER: [],
+      ASSISTANT: [],
    };

    recipients.forEach((recipient) => {
@ -529,7 +538,12 @@ export const AddFieldsFormPartial = ({
  const recipientsByRoleToDisplay = useMemo(() => {
    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
    return (Object.entries(recipientsByRole) as [RecipientRole, Recipient[]][])
-      .filter(([role]) => role !== RecipientRole.CC && role !== RecipientRole.VIEWER)
+      .filter(
+        ([role]) =>
+          role !== RecipientRole.CC &&
+          role !== RecipientRole.VIEWER &&
+          role !== RecipientRole.ASSISTANT,
+      )
      .map(
        ([role, roleRecipients]) =>
          // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
@ -544,12 +558,6 @@ export const AddFieldsFormPartial = ({
      );
  }, [recipientsByRole]);

-  const isTypedSignatureEnabled = form.watch('typedSignatureEnabled');
-
-  const handleTypedSignatureChange = (value: boolean) => {
-    form.setValue('typedSignatureEnabled', value, { shouldDirty: true });
-  };
-
  const handleAdvancedSettings = () => {
    setShowAdvancedSettings((prev) => !prev);
  };
@ -687,9 +695,7 @@ export const AddFieldsFormPartial = ({
                      )}

                      {!selectedSigner?.email && (
-                        <span className="gradie flex-1 truncate text-left">
-                          {selectedSigner?.email}
-                        </span>
+                        <span className="flex-1 truncate text-left">{selectedSigner?.email}</span>
                      )}

                      <ChevronsUpDown className="ml-2 h-4 w-4" />
--- a/packages/ui/primitives/document-flow/add-signers.tsx
+++ b/packages/ui/primitives/document-flow/add-signers.tsx
@ -41,6 +41,7 @@ import {
  DocumentFlowFormContainerStep,
 } from './document-flow-root';
 import { ShowFieldItem } from './show-field-item';
+import { SigningOrderConfirmation } from './signing-order-confirmation';
 import type { DocumentFlowStep } from './types';

 export type AddSignersFormProps = {
@ -123,6 +124,7 @@ export const AddSignersFormPartial = ({
  }, [recipients, form]);

  const [showAdvancedSettings, setShowAdvancedSettings] = useState(alwaysShowAdvancedSettings);
+  const [showSigningOrderConfirmation, setShowSigningOrderConfirmation] = useState(false);

  const {
    setValue,
@ -134,6 +136,10 @@ export const AddSignersFormPartial = ({
  const watchedSigners = watch('signers');
  const isSigningOrderSequential = watch('signingOrder') === DocumentSigningOrder.SEQUENTIAL;

+  const hasAssistantRole = useMemo(() => {
+    return watchedSigners.some((signer) => signer.role === RecipientRole.ASSISTANT);
+  }, [watchedSigners]);
+
  const normalizeSigningOrders = (signers: typeof watchedSigners) => {
    return signers
      .sort((a, b) => (a.signingOrder ?? 0) - (b.signingOrder ?? 0))
@ -233,6 +239,7 @@ export const AddSignersFormPartial = ({
      const items = Array.from(watchedSigners);
      const [reorderedSigner] = items.splice(result.source.index, 1);

+      // Find next valid position
      let insertIndex = result.destination.index;
      while (insertIndex < items.length && !canRecipientBeModified(items[insertIndex].nativeId)) {
        insertIndex++;
@ -240,126 +247,116 @@ export const AddSignersFormPartial = ({

      items.splice(insertIndex, 0, reorderedSigner);

-      const updatedSigners = items.map((item, index) => ({
-        ...item,
-        signingOrder: !canRecipientBeModified(item.nativeId) ? item.signingOrder : index + 1,
+      const updatedSigners = items.map((signer, index) => ({
+        ...signer,
+        signingOrder: !canRecipientBeModified(signer.nativeId) ? signer.signingOrder : index + 1,
      }));

-      updatedSigners.forEach((item, index) => {
-        const keys: (keyof typeof item)[] = [
-          'formId',
-          'nativeId',
-          'email',
-          'name',
-          'role',
-          'signingOrder',
-          'actionAuth',
-        ];
-        keys.forEach((key) => {
-          form.setValue(`signers.${index}.${key}` as const, item[key]);
-        });
-      });
+      form.setValue('signers', updatedSigners);

-      const currentLength = form.getValues('signers').length;
-      if (currentLength > updatedSigners.length) {
-        for (let i = updatedSigners.length; i < currentLength; i++) {
-          form.unregister(`signers.${i}`);
-        }
+      const lastSigner = updatedSigners[updatedSigners.length - 1];
+      if (lastSigner.role === RecipientRole.ASSISTANT) {
+        toast({
+          title: _(msg`Warning: Assistant as last signer`),
+          description: _(
+            msg`Having an assistant as the last signer means they will be unable to take any action as there are no subsequent signers to assist.`,
+          ),
+        });
      }

      await form.trigger('signers');
    },
-    [form, canRecipientBeModified, watchedSigners],
+    [form, canRecipientBeModified, watchedSigners, toast],
  );

-  const triggerDragAndDrop = useCallback(
-    (fromIndex: number, toIndex: number) => {
-      if (!$sensorApi.current) {
+  const handleRoleChange = useCallback(
+    (index: number, role: RecipientRole) => {
+      const currentSigners = form.getValues('signers');
+      const signingOrder = form.getValues('signingOrder');
+
+      // Handle parallel to sequential conversion for assistants
+      if (role === RecipientRole.ASSISTANT && signingOrder === DocumentSigningOrder.PARALLEL) {
+        form.setValue('signingOrder', DocumentSigningOrder.SEQUENTIAL);
+        toast({
+          title: _(msg`Signing order is enabled.`),
+          description: _(msg`You cannot add assistants when signing order is disabled.`),
+          variant: 'destructive',
+        });
        return;
      }

-      const draggableId = signers[fromIndex].id;
+      const updatedSigners = currentSigners.map((signer, idx) => ({
+        ...signer,
+        role: idx === index ? role : signer.role,
+        signingOrder: !canRecipientBeModified(signer.nativeId) ? signer.signingOrder : idx + 1,
+      }));

-      const preDrag = $sensorApi.current.tryGetLock(draggableId);
+      form.setValue('signers', updatedSigners);

-      if (!preDrag) {
-        return;
+      if (role === RecipientRole.ASSISTANT && index === updatedSigners.length - 1) {
+        toast({
+          title: _(msg`Warning: Assistant as last signer`),
+          description: _(
+            msg`Having an assistant as the last signer means they will be unable to take any action as there are no subsequent signers to assist.`,
+          ),
+        });
      }
-
-      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: !canRecipientBeModified(signer.nativeId)
-              ? signer.signingOrder
-              : (signer.signingOrder ?? index + 1) + 1,
-          };
-        } else if (index <= newIndex && index > oldIndex) {
-          return {
-            ...signer,
-            signingOrder: !canRecipientBeModified(signer.nativeId)
-              ? signer.signingOrder
-              : Math.max(1, (signer.signingOrder ?? index + 1) - 1),
-          };
-        }
-        return signer;
-      });
-
-      updatedSigners.forEach((signer, index) => {
-        form.setValue(`signers.${index}.signingOrder`, signer.signingOrder);
-      });
-    },
-    [form, canRecipientBeModified],
+    [form, toast, canRecipientBeModified],
  );

  const handleSigningOrderChange = useCallback(
    (index: number, newOrderString: string) => {
-      const newOrder = parseInt(newOrderString, 10);
-
-      if (!newOrderString.trim()) {
+      const trimmedOrderString = newOrderString.trim();
+      if (!trimmedOrderString) {
        return;
      }

-      if (Number.isNaN(newOrder)) {
-        form.setValue(`signers.${index}.signingOrder`, index + 1);
+      const newOrder = Number(trimmedOrderString);
+      if (!Number.isInteger(newOrder) || newOrder < 1) {
        return;
      }

-      const newIndex = newOrder - 1;
-      if (index !== newIndex) {
-        updateSigningOrders(newIndex, index);
-        triggerDragAndDrop(index, newIndex);
+      const currentSigners = form.getValues('signers');
+      const signer = currentSigners[index];
+
+      // Remove signer from current position and insert at new position
+      const remainingSigners = currentSigners.filter((_, idx) => idx !== index);
+      const newPosition = Math.min(Math.max(0, newOrder - 1), currentSigners.length - 1);
+      remainingSigners.splice(newPosition, 0, signer);
+
+      const updatedSigners = remainingSigners.map((s, idx) => ({
+        ...s,
+        signingOrder: !canRecipientBeModified(s.nativeId) ? s.signingOrder : idx + 1,
+      }));
+
+      form.setValue('signers', updatedSigners);
+
+      if (signer.role === RecipientRole.ASSISTANT && newPosition === remainingSigners.length - 1) {
+        toast({
+          title: _(msg`Warning: Assistant as last signer`),
+          description: _(
+            msg`Having an assistant as the last signer means they will be unable to take any action as there are no subsequent signers to assist.`,
+          ),
+        });
      }
    },
-    [form, triggerDragAndDrop, updateSigningOrders],
+    [form, canRecipientBeModified, toast],
  );

+  const handleSigningOrderDisable = useCallback(() => {
+    setShowSigningOrderConfirmation(false);
+
+    const currentSigners = form.getValues('signers');
+    const updatedSigners = currentSigners.map((signer) => ({
+      ...signer,
+      role: signer.role === RecipientRole.ASSISTANT ? RecipientRole.SIGNER : signer.role,
+    }));
+
+    form.setValue('signers', updatedSigners);
+    form.setValue('signingOrder', DocumentSigningOrder.PARALLEL);
+  }, [form]);
+
  return (
    <>
      <DocumentFlowFormContainerHeader
@ -384,11 +381,16 @@ export const AddSignersFormPartial = ({
                      {...field}
                      id="signingOrder"
                      checked={field.value === DocumentSigningOrder.SEQUENTIAL}
-                      onCheckedChange={(checked) =>
+                      onCheckedChange={(checked) => {
+                        if (!checked && hasAssistantRole) {
+                          setShowSigningOrderConfirmation(true);
+                          return;
+                        }
+
                        field.onChange(
                          checked ? DocumentSigningOrder.SEQUENTIAL : DocumentSigningOrder.PARALLEL,
-                        )
-                      }
+                        );
+                      }}
                      disabled={isSubmitting || hasDocumentBeenSent}
                    />
                  </FormControl>
@ -613,7 +615,11 @@ export const AddSignersFormPartial = ({
                                      <FormControl>
                                        <RecipientRoleSelect
                                          {...field}
-                                          onValueChange={field.onChange}
+                                          isAssistantEnabled={isSigningOrderSequential}
+                                          onValueChange={(value) =>
+                                            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+                                            handleRoleChange(index, value as RecipientRole)
+                                          }
                                          disabled={
                                            snapshot.isDragging ||
                                            isSubmitting ||
@ -710,6 +716,12 @@ export const AddSignersFormPartial = ({
            )}
          </Form>
        </AnimateGenericFadeInOut>
+
+        <SigningOrderConfirmation
+          open={showSigningOrderConfirmation}
+          onOpenChange={setShowSigningOrderConfirmation}
+          onConfirm={handleSigningOrderDisable}
+        />
      </DocumentFlowFormContainerContent>

      <DocumentFlowFormContainerFooter>
--- a/packages/ui/primitives/document-flow/signing-order-confirmation.tsx
+++ b/packages/ui/primitives/document-flow/signing-order-confirmation.tsx
@ -0,0 +1,40 @@
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from '@documenso/ui/primitives/alert-dialog';
+
+export type SigningOrderConfirmationProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  onConfirm: () => void;
+};
+
+export function SigningOrderConfirmation({
+  open,
+  onOpenChange,
+  onConfirm,
+}: SigningOrderConfirmationProps) {
+  return (
+    <AlertDialog open={open} onOpenChange={onOpenChange}>
+      <AlertDialogContent>
+        <AlertDialogHeader>
+          <AlertDialogTitle>Warning</AlertDialogTitle>
+          <AlertDialogDescription>
+            You have an assistant role on the signers list, removing the signing order will change
+            the assistant role to signer.
+          </AlertDialogDescription>
+        </AlertDialogHeader>
+        <AlertDialogFooter>
+          <AlertDialogCancel>Cancel</AlertDialogCancel>
+          <AlertDialogAction onClick={onConfirm}>Proceed</AlertDialogAction>
+        </AlertDialogFooter>
+      </AlertDialogContent>
+    </AlertDialog>
+  );
+}
--- a/packages/ui/primitives/radio-group.tsx
+++ b/packages/ui/primitives/radio-group.tsx
@ -19,18 +19,18 @@ RadioGroup.displayName = RadioGroupPrimitive.Root.displayName;
 const RadioGroupItem = React.forwardRef<
  React.ElementRef<typeof RadioGroupPrimitive.Item>,
  React.ComponentPropsWithoutRef<typeof RadioGroupPrimitive.Item>
->(({ className, children: _children, ...props }, ref) => {
+>(({ className, ...props }, ref) => {
  return (
    <RadioGroupPrimitive.Item
      ref={ref}
      className={cn(
-        'border-input ring-offset-background focus:ring-ring h-4 w-4 rounded-full border focus:outline-none focus:ring-2 focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
+        'border-primary text-primary focus-visible:ring-ring aspect-square h-4 w-4 rounded-full border shadow focus:outline-none focus-visible:ring-1 disabled:cursor-not-allowed disabled:opacity-50',
        className,
      )}
      {...props}
    >
      <RadioGroupPrimitive.Indicator className="flex items-center justify-center">
-        <Circle className="fill-primary text-primary h-2.5 w-2.5" />
+        <Circle className="fill-primary h-2.5 w-2.5" />
      </RadioGroupPrimitive.Indicator>
    </RadioGroupPrimitive.Item>
  );
--- a/packages/ui/primitives/recipient-role-icons.tsx
+++ b/packages/ui/primitives/recipient-role-icons.tsx
@ -1,4 +1,4 @@
-import { BadgeCheck, Copy, Eye, PencilLine } from 'lucide-react';
+import { BadgeCheck, Copy, Eye, PencilLine, User } from 'lucide-react';

 import type { RecipientRole } from '.prisma/client';

@ -7,4 +7,5 @@ export const ROLE_ICONS: Record<RecipientRole, JSX.Element> = {
  APPROVER: <BadgeCheck className="h-4 w-4" />,
  CC: <Copy className="h-4 w-4" />,
  VIEWER: <Eye className="h-4 w-4" />,
+  ASSISTANT: <User className="h-4 w-4" />,
 };
--- a/packages/ui/primitives/template-flow/add-template-fields.tsx
+++ b/packages/ui/primitives/template-flow/add-template-fields.tsx
@ -32,7 +32,7 @@ import {
 import { nanoid } from '@documenso/lib/universal/id';
 import { parseMessageDescriptor } from '@documenso/lib/utils/i18n';
 import type { Field, Recipient } from '@documenso/prisma/client';
-import { FieldType, RecipientRole } from '@documenso/prisma/client';
+import { FieldType, RecipientRole, SendStatus } from '@documenso/prisma/client';
 import { cn } from '@documenso/ui/lib/utils';
 import { Button } from '@documenso/ui/primitives/button';
 import { Card, CardContent } from '@documenso/ui/primitives/card';
@ -438,6 +438,7 @@ export const AddTemplateFieldsFormPartial = ({
      VIEWER: [],
      SIGNER: [],
      APPROVER: [],
+      ASSISTANT: [],
    };

    recipients.forEach((recipient) => {
@ -447,10 +448,25 @@ export const AddTemplateFieldsFormPartial = ({
    return recipientsByRole;
  }, [recipients]);

+  useEffect(() => {
+    const recipientsByRoleToDisplay = recipients.filter(
+      (recipient) =>
+        recipient.role !== RecipientRole.CC && recipient.role !== RecipientRole.ASSISTANT,
+    );
+
+    setSelectedSigner(
+      recipientsByRoleToDisplay.find((r) => r.sendStatus !== SendStatus.SENT) ??
+        recipientsByRoleToDisplay[0],
+    );
+  }, [recipients]);
+
  const recipientsByRoleToDisplay = useMemo(() => {
    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
    return (Object.entries(recipientsByRole) as [RecipientRole, Recipient[]][]).filter(
-      ([role]) => role !== RecipientRole.CC && role !== RecipientRole.VIEWER,
+      ([role]) =>
+        role !== RecipientRole.CC &&
+        role !== RecipientRole.VIEWER &&
+        role !== RecipientRole.ASSISTANT,
    );
  }, [recipientsByRole]);

--- a/packages/ui/primitives/template-flow/add-template-placeholder-recipients.tsx
+++ b/packages/ui/primitives/template-flow/add-template-placeholder-recipients.tsx
@ -29,6 +29,7 @@ import { cn } from '@documenso/ui/lib/utils';
 import { Button } from '@documenso/ui/primitives/button';
 import { FormErrorMessage } from '@documenso/ui/primitives/form/form-error-message';
 import { Input } from '@documenso/ui/primitives/input';
+import { toast } from '@documenso/ui/primitives/use-toast';

 import { Checkbox } from '../checkbox';
 import {
@ -39,6 +40,7 @@ import {
  DocumentFlowFormContainerStep,
 } from '../document-flow/document-flow-root';
 import { ShowFieldItem } from '../document-flow/show-field-item';
+import { SigningOrderConfirmation } from '../document-flow/signing-order-confirmation';
 import type { DocumentFlowStep } from '../document-flow/types';
 import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '../form/form';
 import { useStep } from '../stepper';
@ -213,41 +215,30 @@ export const AddTemplatePlaceholderRecipientsFormPartial = ({

      const items = Array.from(watchedSigners);
      const [reorderedSigner] = items.splice(result.source.index, 1);
-
      const insertIndex = result.destination.index;

      items.splice(insertIndex, 0, reorderedSigner);

-      const updatedSigners = items.map((item, index) => ({
-        ...item,
+      const updatedSigners = items.map((signer, index) => ({
+        ...signer,
        signingOrder: index + 1,
      }));

-      updatedSigners.forEach((item, index) => {
-        const keys: (keyof typeof item)[] = [
-          'formId',
-          'nativeId',
-          'email',
-          'name',
-          'role',
-          'signingOrder',
-          'actionAuth',
-        ];
-        keys.forEach((key) => {
-          form.setValue(`signers.${index}.${key}` as const, item[key]);
-        });
-      });
+      form.setValue('signers', updatedSigners);

-      const currentLength = form.getValues('signers').length;
-      if (currentLength > updatedSigners.length) {
-        for (let i = updatedSigners.length; i < currentLength; i++) {
-          form.unregister(`signers.${i}`);
-        }
+      const lastSigner = updatedSigners[updatedSigners.length - 1];
+      if (lastSigner.role === RecipientRole.ASSISTANT) {
+        toast({
+          title: _(msg`Warning: Assistant as last signer`),
+          description: _(
+            msg`Having an assistant as the last signer means they will be unable to take any action as there are no subsequent signers to assist.`,
+          ),
+        });
      }

      await form.trigger('signers');
    },
-    [form, watchedSigners],
+    [form, watchedSigners, toast],
  );

  const triggerDragAndDrop = useCallback(
@ -308,26 +299,94 @@ export const AddTemplatePlaceholderRecipientsFormPartial = ({

  const handleSigningOrderChange = useCallback(
    (index: number, newOrderString: string) => {
-      const newOrder = parseInt(newOrderString, 10);
-
-      if (!newOrderString.trim()) {
+      const trimmedOrderString = newOrderString.trim();
+      if (!trimmedOrderString) {
        return;
      }

-      if (Number.isNaN(newOrder)) {
-        form.setValue(`signers.${index}.signingOrder`, index + 1);
+      const newOrder = Number(trimmedOrderString);
+      if (!Number.isInteger(newOrder) || newOrder < 1) {
        return;
      }

-      const newIndex = newOrder - 1;
-      if (index !== newIndex) {
-        updateSigningOrders(newIndex, index);
-        triggerDragAndDrop(index, newIndex);
+      const currentSigners = form.getValues('signers');
+      const signer = currentSigners[index];
+
+      // Remove signer from current position and insert at new position
+      const remainingSigners = currentSigners.filter((_, idx) => idx !== index);
+      const newPosition = Math.min(Math.max(0, newOrder - 1), currentSigners.length - 1);
+      remainingSigners.splice(newPosition, 0, signer);
+
+      const updatedSigners = remainingSigners.map((s, idx) => ({
+        ...s,
+        signingOrder: idx + 1,
+      }));
+
+      form.setValue('signers', updatedSigners);
+
+      if (signer.role === RecipientRole.ASSISTANT && newPosition === remainingSigners.length - 1) {
+        toast({
+          title: _(msg`Warning: Assistant as last signer`),
+          description: _(
+            msg`Having an assistant as the last signer means they will be unable to take any action as there are no subsequent signers to assist.`,
+          ),
+        });
      }
    },
-    [form, triggerDragAndDrop, updateSigningOrders],
+    [form, toast],
  );

+  const handleRoleChange = useCallback(
+    (index: number, role: RecipientRole) => {
+      const currentSigners = form.getValues('signers');
+      const signingOrder = form.getValues('signingOrder');
+
+      // Handle parallel to sequential conversion for assistants
+      if (role === RecipientRole.ASSISTANT && signingOrder === DocumentSigningOrder.PARALLEL) {
+        form.setValue('signingOrder', DocumentSigningOrder.SEQUENTIAL);
+        toast({
+          title: _(msg`Signing order is enabled.`),
+          description: _(msg`You cannot add assistants when signing order is disabled.`),
+          variant: 'destructive',
+        });
+        return;
+      }
+
+      const updatedSigners = currentSigners.map((signer, idx) => ({
+        ...signer,
+        role: idx === index ? role : signer.role,
+        signingOrder: idx + 1,
+      }));
+
+      form.setValue('signers', updatedSigners);
+
+      if (role === RecipientRole.ASSISTANT && index === updatedSigners.length - 1) {
+        toast({
+          title: _(msg`Warning: Assistant as last signer`),
+          description: _(
+            msg`Having an assistant as the last signer means they will be unable to take any action as there are no subsequent signers to assist.`,
+          ),
+        });
+      }
+    },
+    [form, toast],
+  );
+
+  const [showSigningOrderConfirmation, setShowSigningOrderConfirmation] = useState(false);
+
+  const handleSigningOrderDisable = useCallback(() => {
+    setShowSigningOrderConfirmation(false);
+
+    const currentSigners = form.getValues('signers');
+    const updatedSigners = currentSigners.map((signer) => ({
+      ...signer,
+      role: signer.role === RecipientRole.ASSISTANT ? RecipientRole.SIGNER : signer.role,
+    }));
+
+    form.setValue('signers', updatedSigners);
+    form.setValue('signingOrder', DocumentSigningOrder.PARALLEL);
+  }, [form]);
+
  return (
    <>
      <DocumentFlowFormContainerHeader
@ -353,11 +412,19 @@ export const AddTemplatePlaceholderRecipientsFormPartial = ({
                      {...field}
                      id="signingOrder"
                      checked={field.value === DocumentSigningOrder.SEQUENTIAL}
-                      onCheckedChange={(checked) =>
+                      onCheckedChange={(checked) => {
+                        if (
+                          !checked &&
+                          watchedSigners.some((s) => s.role === RecipientRole.ASSISTANT)
+                        ) {
+                          setShowSigningOrderConfirmation(true);
+                          return;
+                        }
+
                        field.onChange(
                          checked ? DocumentSigningOrder.SEQUENTIAL : DocumentSigningOrder.PARALLEL,
-                        )
-                      }
+                        );
+                      }}
                      disabled={isSubmitting}
                    />
                  </FormControl>
@ -556,7 +623,10 @@ export const AddTemplatePlaceholderRecipientsFormPartial = ({
                                      <FormControl>
                                        <RecipientRoleSelect
                                          {...field}
-                                          onValueChange={field.onChange}
+                                          onValueChange={(value) =>
+                                            // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
+                                            handleRoleChange(index, value as RecipientRole)
+                                          }
                                          disabled={isSubmitting}
                                          hideCCRecipients={isSignerDirectRecipient(signer)}
                                        />
@ -677,6 +747,12 @@ export const AddTemplatePlaceholderRecipientsFormPartial = ({
          onGoNextClick={() => void onFormSubmit()}
        />
      </DocumentFlowFormContainerFooter>
+
+      <SigningOrderConfirmation
+        open={showSigningOrderConfirmation}
+        onOpenChange={setShowSigningOrderConfirmation}
+        onConfirm={handleSigningOrderDisable}
+      />
    </>
  );
 };