@modernman00/shared-js-lib 1.2.87 → 1.2.88

package/DigitalSignaturePad.js

@@ -0,0 +1,545 @@
+/**
+ * DigitalSignaturePad.js
+ *
+ * Enterprise Responsive HTML5 Canvas E-Signature Pad with:
+ * - Touch, Stylus & Mouse Pointer Events support
+ * - High-DPI / Retina display crisp scaling (devicePixelRatio compensation)
+ * - Bezier curve & midpoint quadratic stroke smoothing
+ * - Touch-action isolation (prevents accidental scrolling on mobile)
+ * - Dynamic baseline guide & placeholder
+ * - Clean Base64 PNG, SVG, and Blob export (isolated from UI guide markers)
+ * - Form binding & minimum-stroke validation (accidental tap rejection)
+ * - Biometric coordinate & velocity telemetry capture
+ *
+ * Compliant with eIDAS AES & UK Electronic Communications Act 2000.
+ */
+export class DigitalSignaturePad {
+  /**
+   * @param {HTMLCanvasElement|string} canvas - Canvas element or selector
+   * @param {Object} [options={}] - Configuration options
+   */
+  constructor(canvas, options = {}) {
+    this.canvas = typeof canvas === 'string' ? document.querySelector(canvas) : canvas;
+    if (!this.canvas || !(this.canvas instanceof HTMLElement)) {
+      throw new Error(`[DigitalSignaturePad] Canvas element not found: ${canvas}`);
+    }
+
+    this.ctx = this.canvas.getContext('2d');
+    if (!this.ctx) {
+      throw new Error('[DigitalSignaturePad] Unable to get 2D rendering context from canvas.');
+    }
+
+    // Configuration options
+    this.options = {
+      strokeColor: options.strokeColor || '#0f172a',
+      strokeWidth: options.strokeWidth || 2.5,
+      minStrokeWidth: options.minStrokeWidth || 1.5,
+      maxStrokeWidth: options.maxStrokeWidth || 3.5,
+      velocityFilterWeight: options.velocityFilterWeight || 0.7,
+      backgroundColor: options.backgroundColor || 'rgba(0, 0, 0, 0)',
+      guide: options.guide !== false, // default true
+      guideText: options.guideText !== undefined ? options.guideText : 'Sign above the line ✍️',
+      guideColor: options.guideColor || '#94a3b8',
+      minPoints: options.minPoints || 8, // Minimum point samples required for valid signature
+      onBegin: typeof options.onBegin === 'function' ? options.onBegin : null,
+      onEnd: typeof options.onEnd === 'function' ? options.onEnd : null,
+      onChange: typeof options.onChange === 'function' ? options.onChange : null,
+      readOnly: !!options.readOnly
+    };
+
+    // State tracking
+    this.strokes = []; // Array of strokes, each stroke is an array of point objects
+    this.currentStroke = null;
+    this.isDrawing = false;
+    this.dpr = (typeof window !== 'undefined' && window.devicePixelRatio) ? window.devicePixelRatio : 1;
+
+    // Apply mobile touch isolation
+    this.canvas.style.touchAction = 'none';
+
+    // Bound listeners for clean destruction
+    this._handlePointerDown = this._onPointerDown.bind(this);
+    this._handlePointerMove = this._onPointerMove.bind(this);
+    this._handlePointerUp = this._onPointerUp.bind(this);
+    this._handleResize = this._onResize.bind(this);
+
+    this._initCanvas();
+    this._attachEvents();
+  }
+
+  /**
+   * Initializes high-DPI scaling and baseline guide.
+   * @private
+   */
+  _initCanvas() {
+    const rect = this.canvas.getBoundingClientRect();
+    const width = rect.width || this.canvas.width || 400;
+    const height = rect.height || this.canvas.height || 200;
+
+    this.width = width;
+    this.height = height;
+
+    this.canvas.width = Math.round(width * this.dpr);
+    this.canvas.height = Math.round(height * this.dpr);
+
+    if (this.ctx) {
+      this.ctx.scale(this.dpr, this.dpr);
+    }
+
+    this._redraw();
+  }
+
+  /**
+   * Attaches pointer and window events.
+   * @private
+   */
+  _attachEvents() {
+    if (this.options.readOnly) return;
+
+    this.canvas.addEventListener('pointerdown', this._handlePointerDown, { passive: false });
+    this.canvas.addEventListener('pointermove', this._handlePointerMove, { passive: false });
+    this.canvas.addEventListener('pointerup', this._handlePointerUp);
+    this.canvas.addEventListener('pointercancel', this._handlePointerUp);
+    this.canvas.addEventListener('pointerleave', this._handlePointerUp);
+
+    if (typeof window !== 'undefined') {
+      window.addEventListener('resize', this._handleResize);
+    }
+  }
+
+  /**
+   * Detaches event listeners.
+   */
+  destroy() {
+    this.canvas.removeEventListener('pointerdown', this._handlePointerDown);
+    this.canvas.removeEventListener('pointermove', this._handlePointerMove);
+    this.canvas.removeEventListener('pointerup', this._handlePointerUp);
+    this.canvas.removeEventListener('pointercancel', this._handlePointerUp);
+    this.canvas.removeEventListener('pointerleave', this._handlePointerUp);
+
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('resize', this._handleResize);
+    }
+  }
+
+  /**
+   * Handles window resize with high-DPI preservation.
+   * @private
+   */
+  _onResize() {
+    const rect = this.canvas.getBoundingClientRect();
+    if (!rect.width || !rect.height) return;
+
+    this.dpr = (typeof window !== 'undefined' && window.devicePixelRatio) ? window.devicePixelRatio : 1;
+    this.width = rect.width;
+    this.height = rect.height;
+
+    this.canvas.width = Math.round(this.width * this.dpr);
+    this.canvas.height = Math.round(this.height * this.dpr);
+
+    if (this.ctx) {
+      this.ctx.scale(this.dpr, this.dpr);
+    }
+
+    this._redraw();
+  }
+
+  /**
+   * Normalizes client coordinates into canvas coordinate space.
+   * @private
+   */
+  _getPoint(event) {
+    const rect = this.canvas.getBoundingClientRect();
+    const x = event.clientX - rect.left;
+    const y = event.clientY - rect.top;
+    const time = Date.now();
+    const pressure = event.pressure !== undefined && event.pressure > 0 ? event.pressure : 0.5;
+
+    return { x, y, time, pressure };
+  }
+
+  /**
+   * Pointer down handler.
+   * @private
+   */
+  _onPointerDown(event) {
+    if (this.options.readOnly || event.button !== 0) return;
+    event.preventDefault();
+
+    this.isDrawing = true;
+    const point = this._getPoint(event);
+    this.currentStroke = [point];
+    this.strokes.push(this.currentStroke);
+
+    if (this.options.onBegin) {
+      this.options.onBegin(point);
+    }
+
+    this._redraw();
+  }
+
+  /**
+   * Pointer move handler with midpoint curve smoothing.
+   * @private
+   */
+  _onPointerMove(event) {
+    if (!this.isDrawing || !this.currentStroke) return;
+    event.preventDefault();
+
+    const point = this._getPoint(event);
+    const stroke = this.currentStroke;
+    const prevPoint = stroke[stroke.length - 1];
+
+    // Ignore jitter/micro-movement (< 1.5px)
+    const dist = Math.hypot(point.x - prevPoint.x, point.y - prevPoint.y);
+    if (dist < 1.5) return;
+
+    stroke.push(point);
+
+    this._drawLastSegment(stroke);
+
+    if (this.options.onChange) {
+      this.options.onChange();
+    }
+  }
+
+  /**
+   * Pointer up / release handler.
+   * @private
+   */
+  _onPointerUp(event) {
+    if (!this.isDrawing) return;
+    this.isDrawing = false;
+    this.currentStroke = null;
+
+    if (this.options.onEnd) {
+      this.options.onEnd();
+    }
+    if (this.options.onChange) {
+      this.options.onChange();
+    }
+  }
+
+  /**
+   * Draws the latest curve segment for fluid 60fps rendering without redrawing the whole canvas.
+   * @private
+   */
+  _drawLastSegment(stroke) {
+    if (!this.ctx || stroke.length < 2) return;
+
+    const ctx = this.ctx;
+    const p1 = stroke[stroke.length - 2];
+    const p2 = stroke[stroke.length - 1];
+
+    ctx.save();
+    ctx.strokeStyle = this.options.strokeColor;
+    ctx.lineCap = 'round';
+    ctx.lineJoin = 'round';
+
+    // Calculate dynamic stroke width based on distance & velocity
+    const width = this._calculateStrokeWidth(p1, p2);
+    ctx.lineWidth = width;
+
+    ctx.beginPath();
+    if (stroke.length === 2) {
+      ctx.moveTo(p1.x, p1.y);
+      ctx.lineTo(p2.x, p2.y);
+    } else {
+      const p0 = stroke[stroke.length - 3];
+      const mid1 = { x: (p0.x + p1.x) / 2, y: (p0.y + p1.y) / 2 };
+      const mid2 = { x: (p1.x + p2.x) / 2, y: (p1.y + p2.y) / 2 };
+      ctx.moveTo(mid1.x, mid1.y);
+      ctx.quadraticCurveTo(p1.x, p1.y, mid2.x, mid2.y);
+    }
+    ctx.stroke();
+    ctx.restore();
+  }
+
+  /**
+   * Calculates velocity-based dynamic stroke width.
+   * @private
+   */
+  _calculateStrokeWidth(p1, p2) {
+    const timeDelta = Math.max(p2.time - p1.time, 1);
+    const distance = Math.hypot(p2.x - p1.x, p2.y - p1.y);
+    const velocity = distance / timeDelta;
+
+    const { minStrokeWidth, maxStrokeWidth, strokeWidth } = this.options;
+    // Faster velocity -> thinner line (fountain pen stroke dynamics)
+    const dynamicWidth = Math.max(
+      minStrokeWidth,
+      Math.min(maxStrokeWidth, strokeWidth / (velocity * 0.5 + 1))
+    );
+
+    return dynamicWidth;
+  }
+
+  /**
+   * Full canvas redraw: background, guide (if empty), and all strokes.
+   * @param {boolean} [includeGuide=true] - Whether to draw the baseline guide
+   * @private
+   */
+  _redraw(includeGuide = true) {
+    if (!this.ctx) return;
+    const ctx = this.ctx;
+
+    ctx.save();
+    ctx.clearRect(0, 0, this.width, this.height);
+
+    // 1. Draw background
+    if (this.options.backgroundColor && this.options.backgroundColor !== 'rgba(0, 0, 0, 0)') {
+      ctx.fillStyle = this.options.backgroundColor;
+      ctx.fillRect(0, 0, this.width, this.height);
+    }
+
+    // 2. Draw placeholder guide if empty and enabled
+    if (includeGuide && this.options.guide && this.isEmpty()) {
+      this._drawGuide();
+    }
+
+    // 3. Draw all recorded strokes with midpoint quadratic curves
+    for (const stroke of this.strokes) {
+      if (stroke.length === 0) continue;
+
+      ctx.save();
+      ctx.strokeStyle = this.options.strokeColor;
+      ctx.lineCap = 'round';
+      ctx.lineJoin = 'round';
+
+      if (stroke.length === 1) {
+        // Single tap dot
+        ctx.fillStyle = this.options.strokeColor;
+        ctx.beginPath();
+        ctx.arc(stroke[0].x, stroke[0].y, this.options.strokeWidth / 2, 0, Math.PI * 2);
+        ctx.fill();
+      } else {
+        for (let i = 1; i < stroke.length; i++) {
+          const p1 = stroke[i - 1];
+          const p2 = stroke[i];
+          ctx.lineWidth = this._calculateStrokeWidth(p1, p2);
+
+          ctx.beginPath();
+          if (i === 1) {
+            ctx.moveTo(p1.x, p1.y);
+            ctx.lineTo(p2.x, p2.y);
+          } else {
+            const p0 = stroke[i - 2];
+            const mid1 = { x: (p0.x + p1.x) / 2, y: (p0.y + p1.y) / 2 };
+            const mid2 = { x: (p1.x + p2.x) / 2, y: (p1.y + p2.y) / 2 };
+            ctx.moveTo(mid1.x, mid1.y);
+            ctx.quadraticCurveTo(p1.x, p1.y, mid2.x, mid2.y);
+          }
+          ctx.stroke();
+        }
+      }
+      ctx.restore();
+    }
+
+    ctx.restore();
+  }
+
+  /**
+   * Draws a subtle dashed baseline and prompt text for guidance.
+   * @private
+   */
+  _drawGuide() {
+    if (!this.ctx) return;
+    const ctx = this.ctx;
+    const guideY = Math.round(this.height * 0.75);
+
+    ctx.save();
+    ctx.strokeStyle = this.options.guideColor;
+    ctx.lineWidth = 1;
+    if (typeof ctx.setLineDash === 'function') {
+      ctx.setLineDash([4, 4]);
+    }
+
+    // Baseline
+    ctx.beginPath();
+    ctx.moveTo(20, guideY);
+    ctx.lineTo(this.width - 20, guideY);
+    ctx.stroke();
+
+    // Helper text
+    if (this.options.guideText) {
+      ctx.font = '12px -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif';
+      ctx.fillStyle = this.options.guideColor;
+      ctx.textAlign = 'center';
+      ctx.fillText(this.options.guideText, this.width / 2, guideY + 18);
+    }
+
+    ctx.restore();
+  }
+
+  /**
+   * Returns true if no valid strokes have been drawn or if points are under the minimum threshold.
+   * Rejects accidental 1-pixel taps to ensure genuine biometric intent.
+   *
+   * @returns {boolean}
+   */
+  isEmpty() {
+    let totalPoints = 0;
+    for (const stroke of this.strokes) {
+      totalPoints += stroke.length;
+    }
+    return totalPoints < this.options.minPoints;
+  }
+
+  /**
+   * Boolean check whether the signature satisfies minimum valid biometric threshold.
+   * @returns {boolean}
+   */
+  isValid() {
+    return !this.isEmpty();
+  }
+
+  /**
+   * Clears all strokes, resets canvas, and restores the guide placeholder.
+   */
+  clear() {
+    this.strokes = [];
+    this.currentStroke = null;
+    this.isDrawing = false;
+    this._redraw(true);
+
+    if (this.options.onChange) {
+      this.options.onChange();
+    }
+  }
+
+  /**
+   * Exports signature as Base64 Data URL (PNG by default).
+   * Guaranteed to isolate the pure signature from UI guide placeholders.
+   *
+   * @param {string} [type='image/png']
+   * @param {number} [quality=0.92]
+   * @returns {string}
+   */
+  toDataURL(type = 'image/png', quality = 0.92) {
+    if (this.isEmpty()) {
+      return '';
+    }
+
+    // Redraw without guide line for clean legal artifact export
+    this._redraw(false);
+    const dataUrl = this.canvas.toDataURL(type, quality);
+    // Restore guide line if needed
+    this._redraw(true);
+
+    return dataUrl;
+  }
+
+  /**
+   * Exports signature as a Blob.
+   *
+   * @param {Function} callback - (blob) => void
+   * @param {string} [type='image/png']
+   * @param {number} [quality=0.92]
+   */
+  toBlob(callback, type = 'image/png', quality = 0.92) {
+    if (this.isEmpty()) {
+      callback(null);
+      return;
+    }
+
+    this._redraw(false);
+    this.canvas.toBlob((blob) => {
+      this._redraw(true);
+      callback(blob);
+    }, type, quality);
+  }
+
+  /**
+   * Exports strokes as an SVG vector string.
+   * Ideal for high-resolution print agreements and PDF rendering.
+   *
+   * @returns {string}
+   */
+  toSVG() {
+    if (this.isEmpty()) {
+      return '';
+    }
+
+    let paths = '';
+    for (const stroke of this.strokes) {
+      if (stroke.length === 0) continue;
+      let d = `M ${stroke[0].x.toFixed(1)} ${stroke[0].y.toFixed(1)}`;
+      for (let i = 1; i < stroke.length; i++) {
+        const p1 = stroke[i - 1];
+        const p2 = stroke[i];
+        const midX = ((p1.x + p2.x) / 2).toFixed(1);
+        const midY = ((p1.y + p2.y) / 2).toFixed(1);
+        d += ` Q ${p1.x.toFixed(1)} ${p1.y.toFixed(1)} ${midX} ${midY}`;
+      }
+      paths += `<path d="${d}" fill="none" stroke="${this.options.strokeColor}" stroke-width="${this.options.strokeWidth}" stroke-linecap="round" stroke-linejoin="round" />\n`;
+    }
+
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${this.width} ${this.height}" width="${this.width}" height="${this.height}">\n${paths}</svg>`;
+  }
+
+  /**
+   * Returns biometric telemetry coordinates for audit records.
+   * @returns {Array<Array<{x: number, y: number, time: number, pressure: number}>>}
+   */
+  getStrokes() {
+    return JSON.parse(JSON.stringify(this.strokes));
+  }
+
+  /**
+   * Restores strokes from serialized biometric coordinates.
+   * @param {Array<Array<{x: number, y: number, time: number, pressure: number}>>} strokes
+   */
+  fromStrokes(strokes) {
+    if (!Array.isArray(strokes)) return;
+    this.strokes = JSON.parse(JSON.stringify(strokes));
+    this._redraw(true);
+    if (this.options.onChange) {
+      this.options.onChange();
+    }
+  }
+
+  /**
+   * Seamlessly binds the signature pad to an HTML form.
+   * On form submit:
+   * - Validates that a genuine signature is present (!isEmpty()).
+   * - Injects the Base64 signature into a hidden input.
+   * - Blocks submit and invokes onValidationError callback if empty.
+   *
+   * @param {HTMLFormElement|string} form - Form element or selector
+   * @param {Object} [bindOptions={}]
+   * @param {string} [bindOptions.inputName='signature_base64'] - Name/id of hidden input
+   * @param {Function} [bindOptions.onValidationError] - Invoked when user attempts submit without signing
+   * @returns {HTMLInputElement} The bound hidden input
+   */
+  bindToForm(form, bindOptions = {}) {
+    const formEl = typeof form === 'string' ? document.querySelector(form) : form;
+    if (!formEl || !(formEl instanceof HTMLFormElement)) {
+      throw new Error(`[DigitalSignaturePad] Target form element not found: ${form}`);
+    }
+
+    const inputName = bindOptions.inputName || 'signature_base64';
+    let hiddenInput = formEl.querySelector(`input[name="${inputName}"]`);
+    if (!hiddenInput) {
+      hiddenInput = document.createElement('input');
+      hiddenInput.type = 'hidden';
+      hiddenInput.name = inputName;
+      formEl.appendChild(hiddenInput);
+    }
+
+    formEl.addEventListener('submit', (e) => {
+      if (this.isEmpty()) {
+        e.preventDefault();
+        if (typeof bindOptions.onValidationError === 'function') {
+          bindOptions.onValidationError('Please sign the agreement above before proceeding.');
+        } else {
+          alert('Please provide your signature before submitting.');
+        }
+        return false;
+      }
+
+      hiddenInput.value = this.toDataURL();
+      return true;
+    });
+
+    return hiddenInput;
+  }
+}

package/config/version.php

@@ -1,3 +1,3 @@
 <?php
-define('APP_VERSION', 'v1.2.87');
+define('APP_VERSION', 'v1.2.88');
 

package/index.js

@@ -31,4 +31,5 @@ export * from './CardCanvasGenerator.js';
 export * from './ShareManager.js';
 export * from './WebAuthnClient.js';
 export * from './OtpInputManager.js';
-export * from './AddressAutocomplete.js';
+export * from './AddressAutocomplete.js';
+export * from './DigitalSignaturePad.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modernman00/shared-js-lib",
-  "version": "1.2.87",
+  "version": "1.2.88",
   "description": "Reusable JS utilities for numerous js problems",
   "homepage": "https://github.com/modernman00/shared-js-lib#readme",
   "keywords": [
@@ -64,6 +64,7 @@
     "ShareManager.js",
     "OtpInputManager.js",
     "AddressAutocomplete.js",
+    "DigitalSignaturePad.js",
     "templates/"
   ],
   "devDependencies": {

package/release-history.md

@@ -158,3 +158,8 @@
 - feat(pwa): harden PwaManager badging sync, support diverse envelopes, and dispatch pwa:badge-updated event _(by modernman00)_
 - 🔖 Release v1.2.84 _(by modernman00)_
 - 🧹 Auto-commit before release _(by modernman00)_
+
+## v1.2.88 — 2026-10-14 18:00
+### Changelog for v1.2.88
+
+- 🧹 Auto-commit before release _(by modernman00)_