@signosoft/signpad-js 0.4.10 → 0.5.1

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.
@@ -679,7 +679,6 @@ The complete list of keys that can be translated is maintained in `src/i18n/en.j
 | `CONNECTION_ERROR`           | Connection error.                                   |
 | `ERROR_DISCONNECTION`        | Error during disconnection.                         |
 | `ERROR_INSTANTIATING_DRIVER` | Error instantiating driver.                         |
-| `SIGNPAD_DISCONNECTED`       | Signpad disconnected.                               |
 | `INVALID_LICENSE_KEY`        | Invalid license key.                                |
 | `READY_TO_CONNECT`           | Ready to connect.                                   |
 | `SIGNPAD_DETECTED`           | Signpad detected. Click 'Connect Signpad' to begin. |
@@ -751,7 +750,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 +817,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 +871,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 +884,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 +922,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 +1018,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 +1132,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 */
@@ -66,8 +66,6 @@ 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.
@@ -84,11 +82,6 @@ declare class CanvasManager {
      * @param options - The new drawing configuration.
      */
     updateDrawingOptions(options: IDrawingOptions): void;
-    /**
-     * Draws a stroke segment for mouse/touch fallback input.
-     * Physical tablet strokes are rendered by SignatureLayer/SignatureCapture.
-     */
-    drawSegment(penData: IPenData): void;
     /**
      * Wipes the canvas clean and resets the drawing state.
      */
@@ -157,12 +150,6 @@ declare class ConfigManager {
     private clearConfigEventHandlers;
 }
 
-export declare interface ConnectAttempt {
-    connected: boolean;
-    deviceInfo: any | null;
-    isPointerFallback: boolean;
-}
-
 /**
  * `ConnectionManager` handles the lifecycle of the signature pad connection.
  * It manages driver initialization, license authentication, device handshaking,
@@ -173,8 +160,6 @@ declare class ConnectionManager {
     private component;
     /** @private The low-level driver instance */
     private sigLayer;
-    /** @private Debug counter for callback registrations */
-    private debugCallbackRegistrationCount;
     /** @private Cached device info from the last successful connect */
     private cachedDeviceInfo;
     /** @private Timestamp of the last pen event dispatch */
@@ -183,7 +168,8 @@ declare class ConnectionManager {
     private penDataToDispatch;
     /** @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.
@@ -217,11 +203,6 @@ declare class ConnectionManager {
      * @returns True if a device is connected.
      */
     isDeviceConnected(): boolean;
-    /**
-     * Returns true if the SignatureLayer is in signing mode.
-     * @returns True if a signing session is active.
-     */
-    isSigningActive(): boolean;
     /**
      * Starts a signing session on the provided canvas.
      * @param canvasElement - Optional canvas reference.
@@ -229,8 +210,11 @@ 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;
+    /**
+     * Calculates the seconds elapsed since the start of the signing session.
+     * @private
+     */
+    private timestampToSeconds;
     /**
      * Stops the current signing session if active.
      * @returns Signature data if available.
@@ -280,15 +264,6 @@ declare class ConnectionManager {
      * This step only decides state; it does not trigger HID dialog itself.
      */
     private resolveConnectionTarget;
-    /**
-     * Starts a fresh signing session for whichever target mode was selected.
-     */
-    private prepareSigningSession;
-}
-
-export declare interface ConnectionTarget {
-    targetState: SignpadState;
-    statusMessageKey: string;
 }
 
 export declare enum DeviceStatusText {
@@ -308,14 +283,6 @@ export declare interface IDrawingOptions {
     color?: string;
 }
 
-export declare interface IDriverInfo {
-    name: string;
-    ready: boolean;
-    aspectRatio: number;
-    isCanvasStyleTablet: boolean;
-    supportedCommands: string[];
-}
-
 export declare interface IEventCallbacks {
     onConnect?: (event: CustomEvent<{
         deviceInfo: any;
@@ -335,119 +302,24 @@ export declare interface ILanguageOptions {
     translations?: ITranslationSet | Record<string, ITranslationSet>;
 }
 
-/**
- * `IosTouchManager` handles touch interactions on iOS devices and converts them
- * into standardized `IPenData`. Uses the Touch Events API and reads `Touch.force`
- * for real pressure data on devices that support 3D Touch / Haptic Touch.
- * Falls back to 0.5 pressure on hardware without force sensing.
- */
-declare class IosTouchManager {
-    /** @private */
-    private canvas;
-    /** @private */
-    private onPenData;
-    /** @private */
-    private isDrawing;
-    /** @private */
-    private sequenceCounter;
-    /** @private */
-    private sessionStartTime;
-    /** @private Debug counter for listener registrations */
-    private debugListenerRegistrationCount;
-    /** @private */
-    private listenersAttached;
-    private boundHandleTouchStart;
-    private boundHandleTouchMove;
-    private boundHandleTouchEnd;
-    private boundHandleTouchCancel;
-    /**
-     * Creates an instance of IosTouchManager.
-     * @param canvas - The HTMLCanvasElement to attach touch listeners to.
-     * @param onPenDataCallback - The callback function that receives generated IPenData.
-     */
-    constructor(canvas: HTMLCanvasElement, onPenDataCallback: IPenDataCallback);
-    /**
-     * Returns whether the user is currently in the middle of a drawing stroke.
-     */
-    get isCurrentlyDrawing(): boolean;
-    /**
-     * Attaches touch event listeners to the canvas to enable signature capture.
-     */
-    addListeners(): void;
-    /**
-     * Removes touch event listeners from the canvas and stops active drawing.
-     */
-    removeListeners(): void;
-    /**
-     * Returns true if touch listeners are currently attached.
-     */
-    areListenersAttached(): boolean;
-    /**
-     * Resets the internal session state, including sequence counters and start time.
-     */
-    resetSession(): void;
-    /**
-     * Handles the 'touchstart' event: starts a stroke and initializes the session time.
-     * @private
-     */
-    private handleTouchStart;
-    /**
-     * Handles the 'touchmove' event: continues the stroke.
-     * @private
-     */
-    private handleTouchMove;
-    /**
-     * Handles the 'touchend' event: ends the stroke.
-     * @private
-     */
-    private handleTouchEnd;
-    /**
-     * Handles the 'touchcancel' event: terminates a stroke interrupted by the OS.
-     * @private
-     */
-    private handleTouchCancel;
-    /**
-     * Core logic to transform a Touch into IPenData.
-     * @param touch - The raw browser Touch object.
-     * @param inContact - Whether the finger is actively drawing on the surface.
-     * @private
-     */
-    private processTouchEvent;
-    /**
-     * Returns the pressure value from a Touch event.
-     * Reads Touch.force (0–1) on devices with 3D Touch / Haptic Touch.
-     * Falls back to 0.5 when force is unavailable or zero (non-force hardware).
-     * @private
-     */
-    private getPressure;
-    /**
-     * Converts absolute touch coordinates into a normalized 0-1 range relative to canvas size.
-     * @private
-     */
-    private getNormalizedCoordinates;
-    /**
-     * Calculates the seconds elapsed since the start of the signature session.
-     * @private
-     */
-    private timestampToSeconds;
-}
-
 export declare interface IPenData {
     relativeX: number;
     relativeY: number;
-    absoluteX?: number;
-    absoluteY?: number;
     pressure?: number;
-    ready?: boolean;
-    sequence?: number;
     timestamp?: number;
     timestampInSeconds?: number;
     inContact: boolean;
     [key: string]: any;
 }
 
-export declare interface IPenDataCallback {
-    (penData: IPenData): void;
+export declare interface IPenDataPoint {
+    relativeX: number;
+    relativeY: number;
+    absoluteX?: number;
+    absoluteY?: number;
+    pressure: number;
+    timestamp: number;
+    inContact: boolean;
 }
 
 export declare interface ISignatureCanvasMeta {
@@ -464,7 +336,7 @@ export declare interface ISignatureCanvasMeta {
 }
 
 export declare type ISignatureConfirmationData = [
-points: IPenData[],
+points: IPenDataPoint[],
 imageBase64: string,
 metadata: ISignatureResultMeta
 ];
@@ -583,110 +455,6 @@ declare class LocalizationManager {
     private constructUrl;
 }
 
-/**
- * `PointerManager` handles pointer interactions on a canvas element and converts them
- * into standardized `IPenData`. This serves as a fallback mechanism for
- * signature capture when a physical signature tablet is not available.
- * Uses the Pointer Events API to support mouse, touch, and Apple Pencil uniformly.
- */
-declare class PointerManager {
-    /** @private */
-    private canvas;
-    /** @private */
-    private onPenData;
-    /** @private */
-    private isDrawing;
-    /** @private */
-    private sequenceCounter;
-    /** @private */
-    private sessionStartTime;
-    /** @private Debug counter for listener registrations */
-    private debugListenerRegistrationCount;
-    /** @private */
-    private listenersAttached;
-    private boundHandlePointerDown;
-    private boundHandlePointerMove;
-    private boundHandlePointerUp;
-    private boundHandlePointerLeave;
-    private boundHandlePointerCancel;
-    /**
-     * Creates an instance of PointerManager.
-     * @param canvas - The HTMLCanvasElement to attach pointer listeners to.
-     * @param onPenDataCallback - The callback function that receives generated IPenData.
-     */
-    constructor(canvas: HTMLCanvasElement, onPenDataCallback: IPenDataCallback);
-    /**
-     * Returns whether the user is currently in the middle of a drawing stroke.
-     */
-    get isCurrentlyDrawing(): boolean;
-    /**
-     * Attaches pointer event listeners to the canvas to enable signature capture.
-     */
-    addListeners(): void;
-    /**
-     * Removes pointer event listeners from the canvas and stops active drawing.
-     */
-    removeListeners(): void;
-    /**
-     * Returns true if pointer listeners are currently attached.
-     */
-    areListenersAttached(): boolean;
-    /**
-     * Resets the internal session state, including sequence counters and start time.
-     */
-    resetSession(): void;
-    /**
-     * Handles the 'pointerdown' event: starts a stroke and initializes the session time.
-     * @private
-     */
-    private handlePointerDown;
-    /**
-     * Handles the 'pointermove' event: continues the stroke if pointer is down.
-     * @private
-     */
-    private handlePointerMove;
-    /**
-     * Handles the 'pointerup' event: ends the stroke.
-     * @private
-     */
-    private handlePointerUp;
-    /**
-     * Handles the 'pointerleave' event: ends the stroke if the pointer leaves the canvas area.
-     * @private
-     */
-    private handlePointerLeave;
-    /**
-     * Handles the 'pointercancel' event: terminates a stroke interrupted by the browser
-     * (e.g. iOS scroll taking over, incoming call, screen lock).
-     * @private
-     */
-    private handlePointerCancel;
-    /**
-     * Core logic to transform a PointerEvent into IPenData.
-     * @param event - The raw browser PointerEvent.
-     * @param inContact - Whether the pointer is actively drawing on the surface.
-     * @private
-     */
-    private processPointerEvent;
-    /**
-     * Returns the pressure value for a pointer event.
-     * Pen devices (Apple Pencil, stylus) report real pressure in the 0–1 range.
-     * Mouse and touch devices fall back to 0.5 (in contact) / 0 (not in contact).
-     * @private
-     */
-    private getPressure;
-    /**
-     * Converts absolute pointer coordinates into a normalized 0-1 range relative to canvas size.
-     * @private
-     */
-    private getNormalizedCoordinates;
-    /**
-     * Calculates the seconds elapsed since the start of the signature session.
-     * @private
-     */
-    private timestampToSeconds;
-}
-
 /**
  * SignosoftSignpad Web Component.
  * A professional signature capture component supporting physical tablets and mouse fallback.
@@ -716,7 +484,6 @@ export declare class SignosoftSignpad extends LitElement {
     setHasStartedDrawing(value: boolean): void;
     setDeviceStatusText(value: string): void;
     canvasManager: CanvasManager | null;
-    pointerManager: PointerManager | IosTouchManager | null;
     connectionManager: ConnectionManager;
     stateManager: StateManager;
     buttonManager: ButtonManager;
@@ -839,24 +606,12 @@ export declare class SignosoftSignpad extends LitElement {
      * @returns void
      */
     private initializeCanvasManager;
-    /**
-     * Initializes the PointerManager for pointer/touch fallback.
-     * @private
-     * @returns void
-     */
-    private initializePointerManager;
-    /**
-     * Throttles pen event dispatch to avoid excessive callback pressure.
-     * Drawing is still processed for every sample; only event emission is throttled.
-     */
-    private dispatchPenEventThrottled;
     /**
      * Initializes the driver once a lease is provided via config.
      * Safe to call repeatedly; initialization is performed at most once.
      */
     private initializeFromConfigLeaseIfNeeded;
     private autoConnectIfConfigured;
-    private canAttemptAutoConnect;
     private ensureSignatureLayerReady;
     private deferAutoConnectForState;
     private clearPendingAutoConnectTimeout;
@@ -936,7 +691,6 @@ export declare enum SignpadMessage {
     CONNECTION_ERROR = "CONNECTION_ERROR",
     ERROR_DISCONNECTION = "ERROR_DISCONNECTION",
     ERROR_INSTANTIATING_DRIVER = "ERROR_INSTANTIATING_DRIVER",
-    SIGNPAD_DISCONNECTED = "SIGNPAD_DISCONNECTED",
     INVALID_LICENSE_KEY = "INVALID_LICENSE_KEY",
     READY_TO_CONNECT = "READY_TO_CONNECT",
     SIGNPAD_DETECTED = "SIGNPAD_DETECTED",
@@ -959,15 +713,6 @@ export declare enum SignpadState {
     ERROR = "error"
 }
 
-export declare enum SignpadUI {
-    OK = "OK",
-    CLEAR = "CLEAR",
-    CANCEL = "CANCEL",
-    CLEAR_SIGNATURE = "CLEAR_SIGNATURE",
-    DISCONNECT = "DISCONNECT",
-    CONNECT_SIGNPAD = "CONNECT_SIGNPAD"
-}
-
 /**
  * Manages the finite state machine and UI logic for the Signpad component.
  * It handles state transitions, side effects (like adding/removing listeners),