@signosoft/signpad-js 0.4.8 → 0.4.10

package/README.md

@@ -7,8 +7,9 @@
 | 📜 [Description](#-description)           | 📦 [Installation](#-installation)                   | 💬 [Feedback](#-feedback--support) |
 | 🎬 [Demo](#-demo)                         | 🔐 [Licensing](#-lease-setup)                       | 🛠️ [Contributing](#-contributing)  |
 | ⚙️ [Tech stack](#-tech-stack--built-with) | 🚀 [Quick Start](#-quick-start)                     | 📄 [License](#-license)            |
-|                                           | 📋 [Properties](#-properties)                       |                                    |
+| 🖊️ [Devices](#️-device-compatibility)    | 📋 [Properties](#-properties)                       |                                    |
 |                                           | 🧩 [Methods](#-methods)                             |                                    |
+|                                           | 🔄 [States](#-component-states)                     |                                    |
 |                                           | 🎨 [Styling](#-styling--theming)                    |                                    |
 |                                           | 🌐 [Localization](#-localization--translation-keys) |
 |                                           |                                                     |
@@ -98,6 +99,19 @@ async function applyLeaseToConfig(currentConfig) {
 
 <br/>
 
+## 🖊️ Device Compatibility
+
+The component communicates with signature tablets via the **WebHID API**. Devices are matched against a built-in configuration database; unrecognized devices fall back to a generic driver.
+
+| Manufacturer | Models                              | Notes                                      |
+| :----------- | :---------------------------------- | :----------------------------------------- |
+| **Wacom**    | STU series (STU-520, STU-530, etc.) | Fully supported; STU-520/530 require a pre-clear screen wipe before each signing session. |
+| **Ugee**     | UG05 and compatible models          | Supported via device config; firmware variations may affect button behavior.              |
+| **XP-Pen**   | Canvas-style tablets                | Supported; uses canvas-area coordinate mapping.                                           |
+| **Others**   | —                                   | Fall back to `DefaultDriver`; basic pen capture works, hotspot buttons may not.           |
+
+> **Mouse fallback:** If no supported device is connected (or the user dismisses the HID picker), the component automatically activates mouse/touch input so signing can still proceed in the browser.
+
 ## 📦 Installation
 
 Install the library via npm:
@@ -737,7 +751,7 @@ The following methods are available on the component instance to control the sig
 | `connect()`      | `Promise<void>`                                    | Connects device to component                                                     |
 | `disconnect()`   | `Promise<void>`                                    | Disconnects device from component                                                |
 | `startSigning()` | `Promise<void>`                                    | Initializes a new signing session on the canvas and hardware.                    |
-| `stopSigning()`  | `Promise<void>`                                    | Low-level session stop that returns the raw driver payload.                      |
+| `stopSigning()`  | `Promise<any>`                                     | Low-level session stop that returns the raw driver payload.                      |
 | `ok()`           | `Promise<ISignatureConfirmationData \| undefined>` | Finalizes the session, cleans the device screen, and returns the signature data. |
 | `clear()`        | `Promise<void>`                                    | Wipes the signature from the UI and hardware without ending the session.         |
 | `cancel()`       | `Promise<void>`                                    | Aborts the current session and resets the component state.                       |
@@ -814,7 +828,8 @@ This is the standard way to confirm a signature. It:
   relativeX: number, // normalized 0..1
   relativeY: number, // normalized 0..1
   sequence: number,
-  timestamp: number | bigint
+  timestamp: number,           // Unix ms (Date.now()) at the time of capture
+  timestampInSeconds: number   // seconds elapsed since the start of the signing session
 }
 ```
 
@@ -847,7 +862,8 @@ This is the standard way to confirm a signature. It:
     serialNumber: Promise<string> | string,
     vendorId: number | null,
     productId: number | null
-  }
+  },
+  duration: number  // seconds elapsed from startSigning() (or last clear) to stopSigning()
 }
 ```
 
@@ -867,15 +883,18 @@ This is the standard way to confirm a signature. It:
   relativeX: number, // normalized 0..1
   relativeY: number, // normalized 0..1
   sequence: number,
-  timestamp: number | bigint
+  timestamp: number,           // Unix ms (Date.now()) at the time of capture
+  timestampInSeconds: number   // seconds elapsed since the start of the signing session
 }
 ```
 
 #### 📜 `stopSigning()`
 
-A low-level method that forces the driver to stop capturing data and returns the raw driver payload. Unlike `ok()`, it does not trigger the full "Finalization" flow (UI transitions or device screen clearing).
+A low-level method that forces the driver to stop capturing data and returns the raw driver payload as a 3-element tuple `[penDataBatch, imageBase64, metadata]`. Unlike `ok()`, it does not trigger the full "Finalization" flow (UI transitions or device screen clearing).
 
-> Note: `stopSigning()` intentionally exposes the unnormalized raw result, which is why it is documented as `Promise<any>`.
+- `penDataBatch` — array of `IPenData` points collected during the session
+- `imageBase64` — PNG data URL of the signature drawn on canvas, or `null` if unavailable
+- `metadata` — object with `canvas` (dimensions, DPR) and `tablet` (device info) fields
 
 #### 📜 `clear()`
 
@@ -885,6 +904,27 @@ Resets the drawing state on both the web canvas and the physical tablet's displa
 
 Stops the session immediately. It does not collect any signature data and resets the component to its ready state. This method dispatches the `SIGN_CANCEL` event.
 
+## 🔄 Component States
+
+The component progresses through a finite set of states, exposed via the `SignpadState` enum (importable from `@signosoft/signpad-js`). Useful for observing the component lifecycle in your application.
+
+| State                        | Value                          | Description                                                    |
+| :--------------------------- | :----------------------------- | :------------------------------------------------------------- |
+| `INITIAL`                    | `"initial"`                    | Component just mounted, no initialization yet.                 |
+| `CONNECTING`                 | `"connecting"`                 | Connection attempt in progress.                                |
+| `WAITING_FOR_DEVICE_SELECTION` | `"waiting_for_device_selection"` | Browser HID picker is open, waiting for user selection.      |
+| `CONNECTED_PHYSICAL`         | `"connected_physical"`         | Physical tablet connected and ready.                           |
+| `CONNECTED_MOUSE_FALLBACK`   | `"connected_mouse_fallback"`   | No tablet found; mouse/touch fallback is active.               |
+| `SIGNING_ACTIVE`             | `"signing_active"`             | Pen input is live; user is drawing.                            |
+| `PROCESSING_OK`              | `"processing_ok"`              | OK action is being processed (finalizing signature).           |
+| `PROCESSING_CLEAR`           | `"processing_clear"`           | Clear action is being processed.                               |
+| `PROCESSING_CANCEL`          | `"processing_cancel"`          | Cancel action is being processed.                              |
+| `DISCONNECTING`              | `"disconnecting"`              | Disconnect in progress.                                        |
+| `DISCONNECTED`               | `"disconnected"`               | Component is idle and disconnected.                            |
+| `ERROR`                      | `"error"`                      | An unrecoverable error occurred (see `onError` callback).      |
+
+---
+
 ## 🎨 Styling & Theming
 
 The component uses a hybrid theming model:

package/dist/index.d.ts

@@ -66,6 +66,8 @@ declare class CanvasManager {
     private ctx;
     /** @private The active configuration for line styles */
     private currentDrawingOptions;
+    /** @private Last drawn point for mouse-fallback stroke continuity */
+    private lastDrawPoint;
     /**
      * Creates an instance of CanvasManager.
      * @param canvas - The HTMLCanvasElement to draw on.
@@ -83,11 +85,10 @@ declare class CanvasManager {
      */
     updateDrawingOptions(options: IDrawingOptions): void;
     /**
-     * Kept for backward compatibility with callers that may still invoke it.
-     * The actual stroke rendering is done in `src/lib/SignatureCapture.js`.
-     * @param penData - Ignored.
+     * Draws a stroke segment for mouse/touch fallback input.
+     * Physical tablet strokes are rendered by SignatureLayer/SignatureCapture.
      */
-    drawSegment(penData: IPenData_2): void;
+    drawSegment(penData: IPenData): void;
     /**
      * Wipes the canvas clean and resets the drawing state.
      */
@@ -182,6 +183,7 @@ declare class ConnectionManager {
     private penDataToDispatch;
     /** @private Minimum delay between pen events (approx 60fps) */
     private throttleDelayMs;
+    private penDataLog;
     private static readonly POINTER_FALLBACK_DEVICE_NAME;
     /**
      * @param component - The host SignosoftSignpad instance.
@@ -227,6 +229,8 @@ declare class ConnectionManager {
      * @returns A promise resolving to true if the session started successfully.
      */
     startSigning(canvas: HTMLCanvasElement, drawingOptions?: IDrawingOptions): Promise<boolean>;
+    logPenData(data: IPenData): void;
+    private buildConfirmationData;
     /**
      * Stops the current signing session if active.
      * @returns Signature data if available.
@@ -318,7 +322,7 @@ export declare interface IEventCallbacks {
     }>) => void;
     onConnecting?: (event: CustomEvent<void>) => void;
     onDisconnect?: (event: CustomEvent<void>) => void;
-    onPen?: (event: CustomEvent<IPenData_2>) => void;
+    onPen?: (event: CustomEvent<IPenData>) => void;
     onOk?: (event: CustomEvent<ISignatureConfirmationData>) => void;
     onClear?: (event: CustomEvent<void>) => void;
     onCancel?: (event: CustomEvent<void>) => void;
@@ -428,7 +432,7 @@ declare class IosTouchManager {
     private timestampToSeconds;
 }
 
-declare interface IPenData_2 {
+export declare interface IPenData {
     relativeX: number;
     relativeY: number;
     absoluteX?: number;
@@ -436,14 +440,14 @@ declare interface IPenData_2 {
     pressure?: number;
     ready?: boolean;
     sequence?: number;
-    timestamp?: number | bigint;
+    timestamp?: number;
+    timestampInSeconds?: number;
     inContact: boolean;
     [key: string]: any;
 }
-export { IPenData_2 as IPenData }
 
 export declare interface IPenDataCallback {
-    (penData: IPenData_2): void;
+    (penData: IPenData): void;
 }
 
 export declare interface ISignatureCanvasMeta {
@@ -460,7 +464,7 @@ export declare interface ISignatureCanvasMeta {
 }
 
 export declare type ISignatureConfirmationData = [
-points: IPenData_2[],
+points: IPenData[],
 imageBase64: string,
 metadata: ISignatureResultMeta
 ];
@@ -468,6 +472,7 @@ metadata: ISignatureResultMeta
 export declare interface ISignatureResultMeta {
     canvas?: ISignatureCanvasMeta;
     tablet?: ISignatureTabletMeta;
+    duration?: number;
     [key: string]: any;
 }