@unlev/exeq 0.5.0 → 0.5.2

package/dist/index.d.mts

@@ -95,19 +95,39 @@ declare function DesignerView({ apiKey, initialPdfUrl, initialTemplate, onSave,
 
 type TransformFn = (value: string) => string;
 type TransformMap = Record<string, TransformFn>;
+/**
+ * Parse a date string robustly into a local Date (midnight, local TZ) so that
+ * getMonth/getDate/getFullYear are calendar-correct. Handles:
+ *  - ISO date-only "YYYY-MM-DD" → parsed as LOCAL (avoids the classic UTC
+ *    off-by-one where "2024-03-15" becomes the 14th in western timezones).
+ *  - Excel serial numbers (a bare integer, e.g. "45000") → converted.
+ *  - Anything else → native `new Date` (handles "M/D/YYYY", ISO datetimes, …).
+ * Returns null when unparseable.
+ */
+declare function parseDate(value: string): Date | null;
 /** Built-in transforms that ship with exeq. */
 declare const BUILTIN_TRANSFORMS: TransformMap;
 /**
  * Resolve a single formula string against a set of fields and transforms.
  * Formula format: "{{Source Field Label | transform}}" or "{{Source Field Label}}" (no transform = raw value).
  * Multiple expressions can appear in one formula: "{{First}} {{Last}}" → "Jane Smith"
+ *
+ * Source resolution order for "{{Name}}":
+ *   1. a placed field whose label (case-insensitive) or id matches Name
+ *   2. `values[Name]` — imported/contextual data not tied to a placed field
+ *   3. the built-in `today` / `now` source (current date)
+ *
+ * @param values Extra named values (e.g. imported CSV/form data) made available
+ *   to formula sources even when there is no placed field for them.
  */
-declare function resolveFormula(formula: string, fields: FormField[], customTransforms?: TransformMap): string;
+declare function resolveFormula(formula: string, fields: FormField[], customTransforms?: TransformMap, values?: Record<string, string>): string;
 /**
  * Resolve all formula fields in a fields array.
  * Returns a new array with computed values filled in.
+ *
+ * @param values Extra named values available to formula sources (see resolveFormula).
  */
-declare function resolveAllFormulas(fields: FormField[], customTransforms?: TransformMap): FormField[];
+declare function resolveAllFormulas(fields: FormField[], customTransforms?: TransformMap, values?: Record<string, string>): FormField[];
 
 interface SignerViewProps {
     /** API key for authentication */
@@ -168,7 +188,7 @@ interface PdfViewerProps {
     onMoveEnd?: () => void;
     mode: 'designer' | 'signer';
     currentSigner?: string;
-    renderFieldContent?: (field: FormField) => React.ReactNode;
+    renderFieldContent?: (field: FormField, pageWidthPt?: number, pageHeightPt?: number) => React.ReactNode;
     zoom?: number;
     /** Called with field IDs inside a drag-selection rectangle */
     onMarqueeSelect?: (ids: string[]) => void;
@@ -283,6 +303,10 @@ interface FillPdfOptions {
     /** Custom transforms merged with `BUILTIN_TRANSFORMS` during formula
      * resolution. Only meaningful when `resolveFormulas` is true. */
     customTransforms?: TransformMap;
+    /** Extra named values made available to formula sources (e.g. imported CSV/
+     * form data) even when there is no placed field for them. Only meaningful
+     * when `resolveFormulas` is true. */
+    formulaValues?: Record<string, string>;
     /** Linear calibration applied to field positions before rendering. */
     calibration?: Calibration;
 }
@@ -335,4 +359,4 @@ declare function createPdfBuilder(defaults?: CreatePdfBuilderOptions): Promise<P
 declare function downloadPdf(bytes: Uint8Array, filename: string): void;
 declare function postPdfToCallback(bytes: Uint8Array, callbackUrl: string, filename: string): Promise<void>;
 
-export { A4, BUILTIN_TRANSFORMS, type Calibration, type CreatePdfBuilderOptions, DEFAULT_CALIBRATION, DEFAULT_SIGNER_ROLES, DesignerView, type DesignerViewProps, FIELD_DEFAULTS, FONT_FAMILIES, FieldNavigator, FieldPropertyPanel, type FieldType, type FillPdfOptions, type FormField, type PdfBuilder, PdfViewer, type RenderedPage, SIGNER_ROLE_COLORS, SignatureCanvas, SignerRoleSelector, SignerView, type SignerViewProps, type Template, type TextSubtype, type TransformFn, type TransformMap, US_LEGAL, US_LETTER, applyCalibration, createField, createPdfBuilder, downloadPdf, generateFilledPdf, generateId, getCssFontFamily, getFieldValues, getInputType, getSignerColor, isRedactField, isSignatureField, isTextLikeField, postPdfToCallback, preserveFieldValues, renderPdfPages, resolveAllFormulas, resolveFormula, sortFieldsByPosition, uniqueLabel };
+export { A4, BUILTIN_TRANSFORMS, type Calibration, type CreatePdfBuilderOptions, DEFAULT_CALIBRATION, DEFAULT_SIGNER_ROLES, DesignerView, type DesignerViewProps, FIELD_DEFAULTS, FONT_FAMILIES, FieldNavigator, FieldPropertyPanel, type FieldType, type FillPdfOptions, type FormField, type PdfBuilder, PdfViewer, type RenderedPage, SIGNER_ROLE_COLORS, SignatureCanvas, SignerRoleSelector, SignerView, type SignerViewProps, type Template, type TextSubtype, type TransformFn, type TransformMap, US_LEGAL, US_LETTER, applyCalibration, createField, createPdfBuilder, downloadPdf, generateFilledPdf, generateId, getCssFontFamily, getFieldValues, getInputType, getSignerColor, isRedactField, isSignatureField, isTextLikeField, parseDate, postPdfToCallback, preserveFieldValues, renderPdfPages, resolveAllFormulas, resolveFormula, sortFieldsByPosition, uniqueLabel };

package/dist/index.d.ts

@@ -95,19 +95,39 @@ declare function DesignerView({ apiKey, initialPdfUrl, initialTemplate, onSave,
 
 type TransformFn = (value: string) => string;
 type TransformMap = Record<string, TransformFn>;
+/**
+ * Parse a date string robustly into a local Date (midnight, local TZ) so that
+ * getMonth/getDate/getFullYear are calendar-correct. Handles:
+ *  - ISO date-only "YYYY-MM-DD" → parsed as LOCAL (avoids the classic UTC
+ *    off-by-one where "2024-03-15" becomes the 14th in western timezones).
+ *  - Excel serial numbers (a bare integer, e.g. "45000") → converted.
+ *  - Anything else → native `new Date` (handles "M/D/YYYY", ISO datetimes, …).
+ * Returns null when unparseable.
+ */
+declare function parseDate(value: string): Date | null;
 /** Built-in transforms that ship with exeq. */
 declare const BUILTIN_TRANSFORMS: TransformMap;
 /**
  * Resolve a single formula string against a set of fields and transforms.
  * Formula format: "{{Source Field Label | transform}}" or "{{Source Field Label}}" (no transform = raw value).
  * Multiple expressions can appear in one formula: "{{First}} {{Last}}" → "Jane Smith"
+ *
+ * Source resolution order for "{{Name}}":
+ *   1. a placed field whose label (case-insensitive) or id matches Name
+ *   2. `values[Name]` — imported/contextual data not tied to a placed field
+ *   3. the built-in `today` / `now` source (current date)
+ *
+ * @param values Extra named values (e.g. imported CSV/form data) made available
+ *   to formula sources even when there is no placed field for them.
  */
-declare function resolveFormula(formula: string, fields: FormField[], customTransforms?: TransformMap): string;
+declare function resolveFormula(formula: string, fields: FormField[], customTransforms?: TransformMap, values?: Record<string, string>): string;
 /**
  * Resolve all formula fields in a fields array.
  * Returns a new array with computed values filled in.
+ *
+ * @param values Extra named values available to formula sources (see resolveFormula).
  */
-declare function resolveAllFormulas(fields: FormField[], customTransforms?: TransformMap): FormField[];
+declare function resolveAllFormulas(fields: FormField[], customTransforms?: TransformMap, values?: Record<string, string>): FormField[];
 
 interface SignerViewProps {
     /** API key for authentication */
@@ -168,7 +188,7 @@ interface PdfViewerProps {
     onMoveEnd?: () => void;
     mode: 'designer' | 'signer';
     currentSigner?: string;
-    renderFieldContent?: (field: FormField) => React.ReactNode;
+    renderFieldContent?: (field: FormField, pageWidthPt?: number, pageHeightPt?: number) => React.ReactNode;
     zoom?: number;
     /** Called with field IDs inside a drag-selection rectangle */
     onMarqueeSelect?: (ids: string[]) => void;
@@ -283,6 +303,10 @@ interface FillPdfOptions {
     /** Custom transforms merged with `BUILTIN_TRANSFORMS` during formula
      * resolution. Only meaningful when `resolveFormulas` is true. */
     customTransforms?: TransformMap;
+    /** Extra named values made available to formula sources (e.g. imported CSV/
+     * form data) even when there is no placed field for them. Only meaningful
+     * when `resolveFormulas` is true. */
+    formulaValues?: Record<string, string>;
     /** Linear calibration applied to field positions before rendering. */
     calibration?: Calibration;
 }
@@ -335,4 +359,4 @@ declare function createPdfBuilder(defaults?: CreatePdfBuilderOptions): Promise<P
 declare function downloadPdf(bytes: Uint8Array, filename: string): void;
 declare function postPdfToCallback(bytes: Uint8Array, callbackUrl: string, filename: string): Promise<void>;
 
-export { A4, BUILTIN_TRANSFORMS, type Calibration, type CreatePdfBuilderOptions, DEFAULT_CALIBRATION, DEFAULT_SIGNER_ROLES, DesignerView, type DesignerViewProps, FIELD_DEFAULTS, FONT_FAMILIES, FieldNavigator, FieldPropertyPanel, type FieldType, type FillPdfOptions, type FormField, type PdfBuilder, PdfViewer, type RenderedPage, SIGNER_ROLE_COLORS, SignatureCanvas, SignerRoleSelector, SignerView, type SignerViewProps, type Template, type TextSubtype, type TransformFn, type TransformMap, US_LEGAL, US_LETTER, applyCalibration, createField, createPdfBuilder, downloadPdf, generateFilledPdf, generateId, getCssFontFamily, getFieldValues, getInputType, getSignerColor, isRedactField, isSignatureField, isTextLikeField, postPdfToCallback, preserveFieldValues, renderPdfPages, resolveAllFormulas, resolveFormula, sortFieldsByPosition, uniqueLabel };
+export { A4, BUILTIN_TRANSFORMS, type Calibration, type CreatePdfBuilderOptions, DEFAULT_CALIBRATION, DEFAULT_SIGNER_ROLES, DesignerView, type DesignerViewProps, FIELD_DEFAULTS, FONT_FAMILIES, FieldNavigator, FieldPropertyPanel, type FieldType, type FillPdfOptions, type FormField, type PdfBuilder, PdfViewer, type RenderedPage, SIGNER_ROLE_COLORS, SignatureCanvas, SignerRoleSelector, SignerView, type SignerViewProps, type Template, type TextSubtype, type TransformFn, type TransformMap, US_LEGAL, US_LETTER, applyCalibration, createField, createPdfBuilder, downloadPdf, generateFilledPdf, generateId, getCssFontFamily, getFieldValues, getInputType, getSignerColor, isRedactField, isSignatureField, isTextLikeField, parseDate, postPdfToCallback, preserveFieldValues, renderPdfPages, resolveAllFormulas, resolveFormula, sortFieldsByPosition, uniqueLabel };

package/dist/index.js

@@ -59,6 +59,7 @@ __export(lib_exports, {
   isRedactField: () => isRedactField,
   isSignatureField: () => isSignatureField,
   isTextLikeField: () => isTextLikeField,
+  parseDate: () => parseDate,
   postPdfToCallback: () => postPdfToCallback,
   preserveFieldValues: () => preserveFieldValues,
   renderPdfPages: () => renderPdfPages,
@@ -415,6 +416,8 @@ function PdfViewer({
               selectedIds: selectedFieldIds,
               mode,
               currentSigner,
+              pageWidthPt: page.pdfWidth,
+              pageHeightPt: page.pdfHeight,
               renderContent: renderFieldContent
             },
             field.id
@@ -505,6 +508,8 @@ function FieldOverlayItem({
   selectedIds,
   mode,
   currentSigner,
+  pageWidthPt,
+  pageHeightPt,
   renderContent
 }) {
   const overlayRef = (0, import_react.useRef)(null);
@@ -631,7 +636,7 @@ function FieldOverlayItem({
       onMouseDown: handleMouseDown,
       children: [
         mode === "designer" && !isRedact && /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "field-overlay-label", style: { backgroundColor: color }, children: field.label }),
-        renderContent ? renderContent(field) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "field-overlay-placeholder", children: field.value || field.placeholder }),
+        renderContent ? renderContent(field, pageWidthPt, pageHeightPt) : /* @__PURE__ */ (0, import_jsx_runtime.jsx)("div", { className: "field-overlay-placeholder", children: field.value || field.placeholder }),
         mode === "designer" && isSelected && !field.locked && /* @__PURE__ */ (0, import_jsx_runtime.jsx)(
           "div",
           {
@@ -2160,39 +2165,56 @@ var import_react7 = require("react");
 var import_pdf_lib = require("pdf-lib");
 
 // src/utils/formulaResolver.ts
+function parseDate(value) {
+  const s = value.trim();
+  if (!s) return null;
+  if (/^\d+(\.\d+)?$/.test(s)) {
+    const serial = parseFloat(s);
+    if (serial > 59) {
+      const utc = new Date(Math.round((serial - 25569) * 864e5));
+      if (!isNaN(utc.getTime())) {
+        return new Date(utc.getUTCFullYear(), utc.getUTCMonth(), utc.getUTCDate());
+      }
+    }
+  }
+  const iso = s.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+  if (iso) return new Date(+iso[1], +iso[2] - 1, +iso[3]);
+  const d = new Date(s);
+  return isNaN(d.getTime()) ? null : d;
+}
 var BUILTIN_TRANSFORMS = {
   // Date transforms (expects a parseable date string)
   month: (v) => {
-    const d = new Date(v);
-    return isNaN(d.getTime()) ? "" : String(d.getMonth() + 1);
+    const d = parseDate(v);
+    return d ? String(d.getMonth() + 1) : "";
   },
   month2: (v) => {
-    const d = new Date(v);
-    return isNaN(d.getTime()) ? "" : String(d.getMonth() + 1).padStart(2, "0");
+    const d = parseDate(v);
+    return d ? String(d.getMonth() + 1).padStart(2, "0") : "";
   },
   monthname: (v) => {
-    const d = new Date(v);
-    return isNaN(d.getTime()) ? "" : d.toLocaleString("en", { month: "long" });
+    const d = parseDate(v);
+    return d ? d.toLocaleString("en", { month: "long" }) : "";
   },
   monthshort: (v) => {
-    const d = new Date(v);
-    return isNaN(d.getTime()) ? "" : d.toLocaleString("en", { month: "short" });
+    const d = parseDate(v);
+    return d ? d.toLocaleString("en", { month: "short" }) : "";
   },
   day: (v) => {
-    const d = new Date(v);
-    return isNaN(d.getTime()) ? "" : String(d.getDate());
+    const d = parseDate(v);
+    return d ? String(d.getDate()) : "";
   },
   day2: (v) => {
-    const d = new Date(v);
-    return isNaN(d.getTime()) ? "" : String(d.getDate()).padStart(2, "0");
+    const d = parseDate(v);
+    return d ? String(d.getDate()).padStart(2, "0") : "";
   },
   year: (v) => {
-    const d = new Date(v);
-    return isNaN(d.getTime()) ? "" : String(d.getFullYear());
+    const d = parseDate(v);
+    return d ? String(d.getFullYear()) : "";
   },
   year2: (v) => {
-    const d = new Date(v);
-    return isNaN(d.getTime()) ? "" : String(d.getFullYear()).slice(-2);
+    const d = parseDate(v);
+    return d ? String(d.getFullYear()).slice(-2) : "";
   },
   // String transforms
   upper: (v) => v.toUpperCase(),
@@ -2221,15 +2243,27 @@ var BUILTIN_TRANSFORMS = {
 };
 var FORMULA_RE = /\{\{(.+?)\}\}/g;
 var PIPE_RE = /^(.+?)\s*\|\s*(.+)$/;
-function resolveFormula(formula, fields, customTransforms) {
+function todayIso() {
+  const d = /* @__PURE__ */ new Date();
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+function resolveFormula(formula, fields, customTransforms, values) {
   const transforms = { ...BUILTIN_TRANSFORMS, ...customTransforms };
   return formula.replace(FORMULA_RE, (_match, expr) => {
     const pipeMatch = expr.match(PIPE_RE);
     const sourceLabel = (pipeMatch ? pipeMatch[1] : expr).trim();
     const transformName = pipeMatch ? pipeMatch[2].trim() : null;
-    const sourceField = fields.find((f) => f.label.toLowerCase() === sourceLabel.toLowerCase()) || fields.find((f) => f.id === sourceLabel);
-    if (!sourceField) return "";
-    const rawValue = sourceField.value || "";
+    const lowerLabel = sourceLabel.toLowerCase();
+    const sourceField = fields.find((f) => f.label.toLowerCase() === lowerLabel) || fields.find((f) => f.id === sourceLabel);
+    let rawValue = sourceField ? sourceField.value || "" : void 0;
+    if (rawValue === void 0 && values) {
+      const key = Object.keys(values).find((k) => k.toLowerCase() === lowerLabel);
+      if (key !== void 0) rawValue = values[key] || "";
+    }
+    if (rawValue === void 0 && (lowerLabel === "today" || lowerLabel === "now")) {
+      rawValue = todayIso();
+    }
+    if (rawValue === void 0) return "";
     if (!transformName) return rawValue;
     const fn = transforms[transformName];
     if (!fn) return rawValue;
@@ -2240,14 +2274,38 @@ function resolveFormula(formula, fields, customTransforms) {
     }
   });
 }
-function resolveAllFormulas(fields, customTransforms) {
+function resolveAllFormulas(fields, customTransforms, values) {
   return fields.map((f) => {
     if (!f.formula) return f;
-    const computed = resolveFormula(f.formula, fields, customTransforms);
+    const computed = resolveFormula(f.formula, fields, customTransforms, values);
     return computed !== f.value ? { ...f, value: computed } : f;
   });
 }
 
+// src/utils/fitText.ts
+function fitFontSize(o) {
+  let size = o.autoShrink ? Math.min(o.fontSize, o.fieldHeightPt * 0.7) : o.fontSize;
+  if (o.autoShrink && o.value) {
+    const padding = 4;
+    while (size > 4) {
+      if (o.measure(o.value, size) <= o.fieldWidthPt - padding) break;
+      size -= 0.5;
+    }
+  }
+  return size;
+}
+var measureCtx = null;
+function measureTextWidth(text, size, opts) {
+  if (typeof document === "undefined") return text.length * size * 0.5;
+  if (!measureCtx) measureCtx = document.createElement("canvas").getContext("2d");
+  if (!measureCtx) return text.length * size * 0.5;
+  const family = getCssFontFamily(opts?.fontFamily) || "Helvetica, Arial, sans-serif";
+  measureCtx.font = `${opts?.italic ? "italic " : ""}${opts?.bold ? "bold " : ""}${size}px ${family}`;
+  const base = measureCtx.measureText(text).width;
+  const spacing = opts?.letterSpacing ? opts.letterSpacing * Math.max(0, text.length - 1) : 0;
+  return base + spacing;
+}
+
 // src/utils/pdfFiller.ts
 var FONT_VARIANTS = {
   Helvetica: [import_pdf_lib.StandardFonts.Helvetica, import_pdf_lib.StandardFonts.HelveticaBold, import_pdf_lib.StandardFonts.HelveticaOblique, import_pdf_lib.StandardFonts.HelveticaBoldOblique],
@@ -2339,14 +2397,14 @@ async function renderFieldsOnPages(pages, fields, getFont, getSignature) {
       const font = await getFont(field.fontFamily || "Helvetica", field.bold, field.italic);
       const spacing = field.letterSpacing || 0;
       const textWidthAtSize = (text, size) => font.widthOfTextAtSize(text, size) + spacing * (text.length - 1);
-      let fontSize = field.autoShrink ? Math.min(field.fontSize, h * 0.7) : field.fontSize;
-      if (field.autoShrink) {
-        const padding = 4;
-        while (fontSize > 4) {
-          if (textWidthAtSize(field.value, fontSize) <= w - padding) break;
-          fontSize -= 0.5;
-        }
-      }
+      const fontSize = fitFontSize({
+        value: field.value,
+        fontSize: field.fontSize,
+        autoShrink: field.autoShrink,
+        fieldWidthPt: w,
+        fieldHeightPt: h,
+        measure: textWidthAtSize
+      });
       const textX = x + 2;
       const baselineY = y + h * 0.3;
       if (spacing > 0) {
@@ -2450,7 +2508,7 @@ async function createPdfBuilder(defaults = {}) {
     doc,
     async addRecord(opts) {
       const pageSize = opts.pageSize ?? defaults.pageSize;
-      let fields = opts.resolveFormulas ? resolveAllFormulas(opts.fields, opts.customTransforms) : opts.fields;
+      let fields = opts.resolveFormulas ? resolveAllFormulas(opts.fields, opts.customTransforms, opts.formulaValues) : opts.fields;
       if (opts.calibration) {
         fields = applyCalibration(
           fields,
@@ -2851,7 +2909,7 @@ ${row.join(",")}`, "csv");
       setSubmitting(false);
     }
   }, [pdfSource, fields, callbackUrl, allRequiredFilled, onComplete, isLastSigner, signer, onSignerComplete, includeAuditTrail, exportFormat, onExport, getValues, transforms]);
-  const renderFieldContent = (0, import_react7.useCallback)((field) => {
+  const renderFieldContent = (0, import_react7.useCallback)((field, pageWidthPt, pageHeightPt) => {
     if (isRedactField(field)) {
       return null;
     }
@@ -2890,8 +2948,23 @@ ${row.join(",")}`, "csv");
     if (field.type === "signed-date") {
       return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)("div", { className: "field-overlay-value", children: field.value || (/* @__PURE__ */ new Date()).toLocaleDateString() });
     }
+    const fieldWidthPt = pageWidthPt ? field.width / 100 * pageWidthPt : Infinity;
+    const fieldHeightPt = pageHeightPt ? field.height / 100 * pageHeightPt : 0;
+    const effectiveFontSize = pageWidthPt ? fitFontSize({
+      value: field.value || "",
+      fontSize: field.fontSize,
+      autoShrink: field.autoShrink,
+      fieldWidthPt,
+      fieldHeightPt,
+      measure: (t, s) => measureTextWidth(t, s, {
+        fontFamily: field.fontFamily,
+        bold: field.bold,
+        italic: field.italic,
+        letterSpacing: field.letterSpacing
+      })
+    }) : field.fontSize;
     const fontStyle = {
-      fontSize: `${field.fontSize}pt`,
+      fontSize: `${effectiveFontSize}pt`,
       letterSpacing: field.letterSpacing ? `${field.letterSpacing}pt` : void 0,
       lineHeight: field.lineHeight ? `${field.lineHeight}` : void 0,
       ...getCssTextStyle(field)
@@ -3173,6 +3246,7 @@ function SignerRoleSelector({
   isRedactField,
   isSignatureField,
   isTextLikeField,
+  parseDate,
   postPdfToCallback,
   preserveFieldValues,
   renderPdfPages,