@unlev/exeq 0.5.0 → 0.5.1

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 */
@@ -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 */
@@ -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,
@@ -2160,39 +2161,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 +2239,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,10 +2270,10 @@ 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;
   });
 }
@@ -2450,7 +2480,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,
@@ -3173,6 +3203,7 @@ function SignerRoleSelector({
   isRedactField,
   isSignatureField,
   isTextLikeField,
+  parseDate,
   postPdfToCallback,
   preserveFieldValues,
   renderPdfPages,