@signosoft/signpad-js 0.4.10 → 0.5.0

package/README.md

@@ -603,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
 
@@ -640,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.                                                    |
 
@@ -648,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.
@@ -751,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<any>`                                     | 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.                       |
@@ -818,40 +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,           // Unix ms (Date.now()) at the time of capture
-  timestampInSeconds: number   // seconds elapsed since the start of the signing session
+  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,
@@ -862,8 +872,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()
+  }
+  // no `duration` field is reported for the physical-tablet path
 }
 ```
 
@@ -875,22 +885,20 @@ 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,           // Unix ms (Date.now()) at the time of capture
-  timestampInSeconds: number   // seconds elapsed since the start of the signing session
+  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 as a 3-element tuple `[penDataBatch, imageBase64, metadata]`. 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).
 
 - `penDataBatch` — array of `IPenData` points collected during the session
 - `imageBase64` — PNG data URL of the signature drawn on canvas, or `null` if unavailable
@@ -915,7 +923,7 @@ The component progresses through a finite set of states, exposed via the `Signpa
 | `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.                            |
+| `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.                              |
@@ -1011,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;
@@ -1122,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,7 +86,7 @@ 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): void;
     /**
@@ -184,6 +184,8 @@ declare class ConnectionManager {
     /** @private Minimum delay between pen events (approx 60fps) */
     private throttleDelayMs;
     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,6 +232,11 @@ declare class ConnectionManager {
      */
     startSigning(canvas: HTMLCanvasElement, drawingOptions?: IDrawingOptions): Promise<boolean>;
     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.