feat: add new field overflow methods (#2715)

packages/lib/types/field-meta.ts

@@ -16,6 +16,34 @@ export const FIELD_MAX_LETTER_SPACING = 100;
 
 export const DEFAULT_FIELD_FONT_SIZE = 12;
 
+export const DEFAULT_SIGNATURE_OVERFLOW_MODE = 'auto';
+export const DEFAULT_DATE_OVERFLOW_MODE = 'auto';
+export const DEFAULT_EMAIL_OVERFLOW_MODE = 'auto';
+
+/**
+ * The overflow mode for a field.
+ *
+ * - 'auto': Will overflow horizontally if no room to wrap vertically.
+ * - 'horizontal': Overflow horizontally, will not wrap at all.
+ * - 'vertical': Overflow vertically, will wrap at the field width.
+ * - 'crop': Crop the text to the field bounds, will not overflow at all.
+ *
+ * @default 'crop'
+ */
+export const ZFieldOverflowMode = z.enum(['auto', 'horizontal', 'vertical', 'crop']);
+export type TFieldOverflowMode = z.infer<typeof ZFieldOverflowMode>;
+
+/**
+ * Resolves the overflow mode for a field.
+ *
+ * Returns 'crop' when undefined (the default for most fields).
+ */
+export const resolveFieldOverflowMode = (
+  fieldMeta?: { overflow?: TFieldOverflowMode } | null,
+): TFieldOverflowMode => {
+  return fieldMeta?.overflow ?? 'crop';
+};
+
 /**
  * Grouped field types that use the same generic text rendering function.
  */
@@ -47,6 +75,7 @@ export const ZBaseFieldMeta = z.object({
   required: z.boolean().optional(),
   readOnly: z.boolean().optional(),
   fontSize: z.number().min(8).max(96).default(DEFAULT_FIELD_FONT_SIZE).optional(),
+  overflow: ZFieldOverflowMode.optional(),
 });
 
 export type TBaseFieldMeta = z.infer<typeof ZBaseFieldMeta>;
@@ -72,6 +101,7 @@ export type TNameFieldMeta = z.infer<typeof ZNameFieldMeta>;
 export const ZEmailFieldMeta = ZBaseFieldMeta.extend({
   type: z.literal('email'),
   textAlign: ZFieldTextAlignSchema.optional(),
+  overflow: ZFieldOverflowMode.optional().default(DEFAULT_EMAIL_OVERFLOW_MODE),
 });
 
 export type TEmailFieldMeta = z.infer<typeof ZEmailFieldMeta>;
@@ -79,6 +109,7 @@ export type TEmailFieldMeta = z.infer<typeof ZEmailFieldMeta>;
 export const ZDateFieldMeta = ZBaseFieldMeta.extend({
   type: z.literal('date'),
   textAlign: ZFieldTextAlignSchema.optional(),
+  overflow: ZFieldOverflowMode.optional().default(DEFAULT_DATE_OVERFLOW_MODE),
 });
 
 export type TDateFieldMeta = z.infer<typeof ZDateFieldMeta>;
@@ -156,6 +187,7 @@ export type TDropdownFieldMeta = z.infer<typeof ZDropdownFieldMeta>;
 
 export const ZSignatureFieldMeta = ZBaseFieldMeta.extend({
   type: z.literal('signature'),
+  overflow: ZFieldOverflowMode.optional().default(DEFAULT_SIGNATURE_OVERFLOW_MODE),
 });
 
 export type TSignatureFieldMeta = z.infer<typeof ZSignatureFieldMeta>;
@@ -283,6 +315,7 @@ export const FIELD_DATE_META_DEFAULT_VALUES: TDateFieldMeta = {
   type: 'date',
   fontSize: DEFAULT_FIELD_FONT_SIZE,
   textAlign: 'left',
+  overflow: DEFAULT_DATE_OVERFLOW_MODE,
 };
 
 export const FIELD_TEXT_META_DEFAULT_VALUES: TTextFieldMeta = {
@@ -322,6 +355,7 @@ export const FIELD_EMAIL_META_DEFAULT_VALUES: TEmailFieldMeta = {
   type: 'email',
   fontSize: DEFAULT_FIELD_FONT_SIZE,
   textAlign: 'left',
+  overflow: DEFAULT_EMAIL_OVERFLOW_MODE,
 };
 
 export const FIELD_RADIO_META_DEFAULT_VALUES: TRadioFieldMeta = {
@@ -356,6 +390,7 @@ export const FIELD_DROPDOWN_META_DEFAULT_VALUES: TDropdownFieldMeta = {
 export const FIELD_SIGNATURE_META_DEFAULT_VALUES: TSignatureFieldMeta = {
   type: 'signature',
   fontSize: DEFAULT_SIGNATURE_TEXT_FONT_SIZE,
+  overflow: DEFAULT_SIGNATURE_OVERFLOW_MODE,
 };
 
 export const FIELD_META_DEFAULT_VALUES: Record<FieldType, TFieldMetaSchema> = {