@signosoft/signpad-js 0.4.9 → 0.5.0

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:
@@ -589,7 +603,7 @@ The component is primarily configured through a single `config` property. This o
 
 | Option      | Type     | Required | Description                                                                   |
 | :---------- | :------- | :------- | :---------------------------------------------------------------------------- |
-| **`lease`** | `object` | **Yes**  | Lease payload returned from the lease API call. Mandatory for initialization. |
+| **`lease`** | `object` | Required for hardware mode | Lease payload returned from the lease API call. The component still renders without it, but driver initialization and hardware communication are disabled (see [Lease Setup](#-lease-setup)). |
 
 ### 👁️ uiVisibilityOptions
 
@@ -626,7 +640,7 @@ Handles component localization. It can load external files or use inline definit
 
 | Field          | Type     | Description                                                                                                                                              |
 | :------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lang`         | `string` | The active language code. Built-in translations are bundled for `'en'`, `'cs'`, and `'pt'`; other languages can be supplied via `langPath` or `translations`. |
+| `lang`         | `string` | The active language code. Built-in translations are bundled for `'en'` and `'cs'`; other languages (including `'pt'`) require `langPath` or `translations`. |
 | `langPath`     | `string` | URL path to fetch translation files. Expects files in `[path]/[lang].json` format.                                                                       |
 | `translations` | `object` | An inline object containing key-value pairs (e.g., `{ "OK": "Confirm signature" }`). Overrides files.                                                    |
 
@@ -634,7 +648,7 @@ Handles component localization. It can load external files or use inline definit
 
 Localization is driven from `languageOptions`, but you can also provide overrides at runtime:
 
-1. **Set the language code** in `config.languageOptions.lang`. English (`en`) is the fallback, Czech (`cs`) and Portuguese (`pt`) are shipped alongside it.
+1. **Set the language code** in `config.languageOptions.lang`. English (`en`) is the fallback, and Czech (`cs`) is bundled alongside it. Other languages, including Portuguese (`pt`), must be supplied via `langPath` or `translations` — they are not bundled.
 2. **Load a hosted file** by pointing `languageOptions.langPath` to the directory that contains `[lang].json`. The loader will fetch `${langPath}/${lang}.json` (or the exact file if you include the `.json` suffix).
 3. **Override only specific phrases** by passing a `translations` object—either a flat key map or a per-language map (`{ en: {...}, cs: {...} }`). Inline values take precedence over both built-in and fetched files.
 4. **Dynamic placeholders** (for example, `{device}` in `TEXT_SIGNING_WITH_DEVICE`) are replaced using the `LocalizationManager.t` helper. Keep the braces intact if you expect runtime interpolation.
@@ -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 signature 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.                       |
@@ -804,39 +818,50 @@ This is the standard way to confirm a signature. It:
 ```
 
 ```js
-// [0] Points structure
+// [0] Points structure — same IPenData shape documented under onPen below
 {
-  absoluteX: number,
-  absoluteY: number,
-  inContact: boolean,
-  pressure: number,
-  ready: boolean,
   relativeX: number, // normalized 0..1
   relativeY: number, // normalized 0..1
-  sequence: number,
-  timestamp: number | bigint
+  pressure: number,
+  inContact: boolean,
+  timestamp: number,          // Unix ms (Date.now()) at the time of capture
+  timestampInSeconds: number  // seconds elapsed since the start of the signing session
 }
 ```
 
 ```js
-// [1] imageBase64 — plain base64 PNG string
+// [1] imageBase64 — base64 PNG data URL, or null if no image could be captured
 "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
 ```
 
 ```js
 // [2] Metadata structure
+// The exact shape depends on whether a physical tablet or the mouse/touch
+// fallback produced the signature — the two paths report different fields.
+
+// Mouse / touch fallback:
 {
   canvas: {
-    top: number,
-    left: number,
-    right: number,
-    bottom: number,
     width: number,
     height: number,
     cssWidth: number,
     cssHeight: number,
     dpr: number
   },
+  tablet: undefined,
+  duration: number  // seconds elapsed between the first and last recorded pen sample
+}
+
+// Physical tablet (driver-reported):
+{
+  canvas: {
+    top?: number,
+    left?: number,
+    right?: number,
+    bottom?: number,
+    width: number,
+    height: number
+  },
   tablet: {
     name: string,
     aspectRatio: number,
@@ -848,6 +873,7 @@ This is the standard way to confirm a signature. It:
     vendorId: number | null,
     productId: number | null
   }
+  // no `duration` field is reported for the physical-tablet path
 }
 ```
 
@@ -859,23 +885,24 @@ This is the standard way to confirm a signature. It:
 
 ```js
 {
-  absoluteX: number,
-  absoluteY: number,
-  inContact: boolean,
-  pressure: number,
-  ready: boolean,
   relativeX: number, // normalized 0..1
   relativeY: number, // normalized 0..1
-  sequence: number,
-  timestamp: number | bigint
+  pressure: number,
+  inContact: boolean,
+  timestamp: number,          // Unix ms (Date.now()) at the time of capture
+  timestampInSeconds: number  // seconds elapsed since the start of the signing session
 }
 ```
 
+> The `IPenData` type also allows optional `absoluteX`, `absoluteY`, `ready`, and `sequence` fields for forward compatibility with the underlying driver, but the component does not currently populate them.
+
 #### 📜 `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 signature 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 +912,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"`             | Defined for future use; the component does not currently transition to this state — drawing happens while still in `CONNECTED_PHYSICAL`/`CONNECTED_MOUSE_FALLBACK`. |
+| `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:
@@ -971,6 +1019,9 @@ signosoft-signpad {
   --sign-button-primary-text-base: var(--white-color);
   --sign-button-primary-text-hover: var(--white-color);
   --sign-button-primary-text-disabled: var(--white-color);
+  --sign-button-primary-border-base: 1px solid var(--primary-color-0);
+  --sign-button-primary-border-hover: 1px solid var(--primary-color-10);
+  --sign-button-primary-border-disabled: 1px solid var(--grey-color);
 
   /* Link Buttons (Connect signpad) */
   --sign-button-link-bg-base: transparent;
@@ -1082,6 +1133,9 @@ signosoft-signpad {
 | `--sign-button-primary-text-base`     | Text color for primary buttons.      |
 | `--sign-button-primary-text-hover`    | Hover text color.                    |
 | `--sign-button-primary-text-disabled` | Disabled text color.                 |
+| `--sign-button-primary-border-base`     | Border of primary buttons.           |
+| `--sign-button-primary-border-hover`    | Hover border color.                  |
+| `--sign-button-primary-border-disabled` | Disabled border color.               |
 
 #### Link/Connect Buttons
 

package/dist/index.d.ts

@@ -57,7 +57,7 @@ declare class ButtonManager {
 
 /**
  * `CanvasManager` is a lightweight canvas utility.
- * Drawing is handled by SignatureLayer/SignatureCapture in `src/lib`.
+ * Drawing is handled by SignatureLayer from `@signosoft/tablet-driver`.
  */
 declare class CanvasManager {
     /** @private The target canvas element */
@@ -86,9 +86,9 @@ declare class CanvasManager {
     updateDrawingOptions(options: IDrawingOptions): void;
     /**
      * Draws a stroke segment for mouse/touch fallback input.
-     * Physical tablet strokes are rendered by SignatureLayer/SignatureCapture.
+     * Physical tablet strokes are rendered by SignatureLayer.
      */
-    drawSegment(penData: IPenData_2): void;
+    drawSegment(penData: IPenData): void;
     /**
      * Wipes the canvas clean and resets the drawing state.
      */
@@ -183,8 +183,9 @@ declare class ConnectionManager {
     private penDataToDispatch;
     /** @private Minimum delay between pen events (approx 60fps) */
     private throttleDelayMs;
-    /** @private Pen data accumulated during a mouse-fallback signing session */
-    private mouseFallbackPenLog;
+    private penDataLog;
+    /** @private Wall-clock time when the current signing session started, for timestampInSeconds */
+    private sessionStartTime;
     private static readonly POINTER_FALLBACK_DEVICE_NAME;
     /**
      * @param component - The host SignosoftSignpad instance.
@@ -230,7 +231,13 @@ declare class ConnectionManager {
      * @returns A promise resolving to true if the session started successfully.
      */
     startSigning(canvas: HTMLCanvasElement, drawingOptions?: IDrawingOptions): Promise<boolean>;
-    logMouseFallbackPenData(data: IPenData_2): void;
+    logPenData(data: IPenData): void;
+    /**
+     * Calculates the seconds elapsed since the start of the signing session.
+     * @private
+     */
+    private timestampToSeconds;
+    private buildConfirmationData;
     /**
      * Stops the current signing session if active.
      * @returns Signature data if available.
@@ -322,7 +329,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;
@@ -432,7 +439,7 @@ declare class IosTouchManager {
     private timestampToSeconds;
 }
 
-declare interface IPenData_2 {
+export declare interface IPenData {
     relativeX: number;
     relativeY: number;
     absoluteX?: number;
@@ -440,14 +447,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 {
@@ -464,7 +471,7 @@ export declare interface ISignatureCanvasMeta {
 }
 
 export declare type ISignatureConfirmationData = [
-points: IPenData_2[],
+points: IPenData[],
 imageBase64: string,
 metadata: ISignatureResultMeta
 ];
@@ -472,6 +479,7 @@ metadata: ISignatureResultMeta
 export declare interface ISignatureResultMeta {
     canvas?: ISignatureCanvasMeta;
     tablet?: ISignatureTabletMeta;
+    duration?: number;
     [key: string]: any;
 }