feat: add text align option to fields (#1610)

## Description

Adds the ability to align text to the left, center or right for relevant
fields.

Previously text was always centered which can be less desirable.

See attached debug document which has left, center and right text
alignments set for fields.

<img width="614" alt="image"
src="https://github.com/user-attachments/assets/361a030e-813d-458b-9c7a-ff4c9fa5e33c"
/>


## Related Issue

N/A

## Changes Made

- Added text align option
- Update the insert in pdf method to support different alignments
- Added a debug mode to field insertion

## Testing Performed

- Ran manual tests using the debug mode

packages/lib/server-only/pdf/insert-field-in-pdf.ts

@@ -1,7 +1,7 @@
 // https://github.com/Hopding/pdf-lib/issues/20#issuecomment-412852821
 import fontkit from '@pdf-lib/fontkit';
 import type { PDFDocument } from 'pdf-lib';
-import { RotationTypes, degrees, radiansToDegrees } from 'pdf-lib';
+import { RotationTypes, degrees, radiansToDegrees, rgb } from 'pdf-lib';
 import { P, match } from 'ts-pattern';
 
 import {
@@ -36,6 +36,9 @@ export const insertFieldInPDF = async (pdf: PDFDocument, field: FieldWithSignatu
   );
 
   const isSignatureField = isSignatureFieldType(field.type);
+  const isDebugMode =
+    // eslint-disable-next-line turbo/no-undeclared-env-vars
+    process.env.DEBUG_PDF_INSERT === '1' || process.env.DEBUG_PDF_INSERT === 'true';
 
   pdf.registerFontkit(fontkit);
 
@@ -83,6 +86,35 @@ export const insertFieldInPDF = async (pdf: PDFDocument, field: FieldWithSignatu
   const fieldX = pageWidth * (Number(field.positionX) / 100);
   const fieldY = pageHeight * (Number(field.positionY) / 100);
 
+  // Draw debug box if debug mode is enabled
+  if (isDebugMode) {
+    let debugX = fieldX;
+    let debugY = pageHeight - fieldY - fieldHeight; // Invert Y for PDF coordinates
+
+    if (pageRotationInDegrees !== 0) {
+      const adjustedPosition = adjustPositionForRotation(
+        pageWidth,
+        pageHeight,
+        debugX,
+        debugY,
+        pageRotationInDegrees,
+      );
+
+      debugX = adjustedPosition.xPos;
+      debugY = adjustedPosition.yPos;
+    }
+
+    page.drawRectangle({
+      x: debugX,
+      y: debugY,
+      width: fieldWidth,
+      height: fieldHeight,
+      borderColor: rgb(1, 0, 0), // Red
+      borderWidth: 1,
+      rotate: degrees(pageRotationInDegrees),
+    });
+  }
+
   const font = await pdf.embedFont(
     isSignatureField ? fontCaveat : fontNoto,
     isSignatureField ? { features: { calt: false } } : undefined,
@@ -278,6 +310,7 @@ export const insertFieldInPDF = async (pdf: PDFDocument, field: FieldWithSignatu
       const meta = Parser ? Parser.safeParse(field.fieldMeta) : null;
 
       const customFontSize = meta?.success && meta.data.fontSize ? meta.data.fontSize : null;
+      const textAlign = meta?.success && meta.data.textAlign ? meta.data.textAlign : 'center';
       const longestLineInTextForWidth = field.customText
         .split('\n')
         .sort((a, b) => b.length - a.length)[0];
@@ -293,7 +326,17 @@ export const insertFieldInPDF = async (pdf: PDFDocument, field: FieldWithSignatu
 
       textWidth = font.widthOfTextAtSize(longestLineInTextForWidth, fontSize);
 
-      let textX = fieldX + (fieldWidth - textWidth) / 2;
+      // Add padding similar to web display (roughly 0.5rem equivalent in PDF units)
+      const padding = 8; // PDF points, roughly equivalent to 0.5rem
+
+      // Calculate X position based on text alignment with padding
+      let textX = fieldX + padding; // Left alignment starts after padding
+      if (textAlign === 'center') {
+        textX = fieldX + (fieldWidth - textWidth) / 2; // Center alignment ignores padding
+      } else if (textAlign === 'right') {
+        textX = fieldX + fieldWidth - textWidth - padding; // Right alignment respects right padding
+      }
+
       let textY = fieldY + (fieldHeight - textHeight) / 2;
 
       // Invert the Y axis since PDFs use a bottom-left coordinate system

packages/lib/types/field-meta.ts

@@ -11,9 +11,14 @@ export const ZBaseFieldMeta = z.object({
 
 export type TBaseFieldMeta = z.infer<typeof ZBaseFieldMeta>;
 
+export const ZFieldTextAlignSchema = z.enum(['left', 'center', 'right']);
+
+export type TFieldTextAlignSchema = z.infer<typeof ZFieldTextAlignSchema>;
+
 export const ZInitialsFieldMeta = ZBaseFieldMeta.extend({
   type: z.literal('initials'),
   fontSize: z.number().min(8).max(96).optional(),
+  textAlign: ZFieldTextAlignSchema.optional(),
 });
 
 export type TInitialsFieldMeta = z.infer<typeof ZInitialsFieldMeta>;
@@ -21,6 +26,7 @@ export type TInitialsFieldMeta = z.infer<typeof ZInitialsFieldMeta>;
 export const ZNameFieldMeta = ZBaseFieldMeta.extend({
   type: z.literal('name'),
   fontSize: z.number().min(8).max(96).optional(),
+  textAlign: ZFieldTextAlignSchema.optional(),
 });
 
 export type TNameFieldMeta = z.infer<typeof ZNameFieldMeta>;
@@ -28,6 +34,7 @@ export type TNameFieldMeta = z.infer<typeof ZNameFieldMeta>;
 export const ZEmailFieldMeta = ZBaseFieldMeta.extend({
   type: z.literal('email'),
   fontSize: z.number().min(8).max(96).optional(),
+  textAlign: ZFieldTextAlignSchema.optional(),
 });
 
 export type TEmailFieldMeta = z.infer<typeof ZEmailFieldMeta>;
@@ -35,6 +42,7 @@ export type TEmailFieldMeta = z.infer<typeof ZEmailFieldMeta>;
 export const ZDateFieldMeta = ZBaseFieldMeta.extend({
   type: z.literal('date'),
   fontSize: z.number().min(8).max(96).optional(),
+  textAlign: ZFieldTextAlignSchema.optional(),
 });
 
 export type TDateFieldMeta = z.infer<typeof ZDateFieldMeta>;
@@ -44,6 +52,7 @@ export const ZTextFieldMeta = ZBaseFieldMeta.extend({
   text: z.string().optional(),
   characterLimit: z.number().optional(),
   fontSize: z.number().min(8).max(96).optional(),
+  textAlign: ZFieldTextAlignSchema.optional(),
 });
 
 export type TTextFieldMeta = z.infer<typeof ZTextFieldMeta>;
@@ -55,6 +64,7 @@ export const ZNumberFieldMeta = ZBaseFieldMeta.extend({
   minValue: z.number().optional(),
   maxValue: z.number().optional(),
   fontSize: z.number().min(8).max(96).optional(),
+  textAlign: ZFieldTextAlignSchema.optional(),
 });
 
 export type TNumberFieldMeta = z.infer<typeof ZNumberFieldMeta>;