@signosoft/signpad-js 0.5.1 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/README.md +33 -38
  2. package/dist/index.d.ts +22 -11
  3. package/dist/signosoft-signpad.js +261 -253
  4. package/dist/signosoft-signpad.umd.cjs +4 -4
  5. package/package.json +2 -2
package/README.md CHANGED
@@ -7,7 +7,7 @@
7
7
  | 📜 [Description](#-description) | 📦 [Installation](#-installation) | 💬 [Feedback](#-feedback--support) |
8
8
  | 🎬 [Demo](#-demo) | 🔐 [Licensing](#-lease-setup) | 🛠️ [Contributing](#-contributing) |
9
9
  | ⚙️ [Tech stack](#-tech-stack--built-with) | 🚀 [Quick Start](#-quick-start) | 📄 [License](#-license) |
10
- | 🖊️ [Devices](#️-device-compatibility) | 📋 [Properties](#-properties) | |
10
+ | 🖊️ [Devices](#️-device-compatibility) | 📋 [Properties](#-properties) | |
11
11
  | | 🧩 [Methods](#-methods) | |
12
12
  | | 🔄 [States](#-component-states) | |
13
13
  | | 🎨 [Styling](#-styling--theming) | |
@@ -23,9 +23,6 @@ This component **works effortlessly** with any modern stack:
23
23
  |:-:|:-:|:-:|:-:|
24
24
  | <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/javascript/javascript-original.svg" alt="JS" width="35" height="35"> | <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React" width="35" height="35"> | <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angularjs/angularjs-original.svg" alt="Angular" width="35" height="35"> | <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vuejs/vuejs-original.svg" alt="Vue" width="35" height="35"> ||
25
25
 
26
-
27
-
28
-
29
26
  It expertly handles the complexities of **WebHID device connections**, signature session lifecycles, and high-fidelity stroke rendering.
30
27
  <br/>
31
28
 
@@ -103,8 +100,8 @@ async function applyLeaseToConfig(currentConfig) {
103
100
 
104
101
  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.
105
102
 
106
- | Manufacturer | Models | Notes |
107
- | :----------- | :---------------------------------- | :----------------------------------------- |
103
+ | Manufacturer | Models | Notes |
104
+ | :----------- | :---------------------------------- | :---------------------------------------------------------------------------------------- |
108
105
  | **Wacom** | STU series (STU-520, STU-530, etc.) | Fully supported; STU-520/530 require a pre-clear screen wipe before each signing session. |
109
106
  | **Ugee** | UG05 and compatible models | Supported via device config; firmware variations may affect button behavior. |
110
107
  | **XP-Pen** | Canvas-style tablets | Supported; uses canvas-area coordinate mapping. |
@@ -601,8 +598,8 @@ The component is primarily configured through a single `config` property. This o
601
598
 
602
599
  ### 🔑 Core Options
603
600
 
604
- | Option | Type | Required | Description |
605
- | :---------- | :------- | :------- | :---------------------------------------------------------------------------- |
601
+ | Option | Type | Required | Description |
602
+ | :---------- | :------- | :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
606
603
  | **`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)). |
607
604
 
608
605
  ### 👁️ uiVisibilityOptions
@@ -638,11 +635,11 @@ Adjusts the visual appearance of the digital ink.
638
635
 
639
636
  Handles component localization. It can load external files or use inline definitions.
640
637
 
641
- | Field | Type | Description |
642
- | :------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
638
+ | Field | Type | Description |
639
+ | :------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
643
640
  | `lang` | `string` | The active language code. Built-in translations are bundled for `'en'` and `'cs'`; other languages (including `'pt'`) require `langPath` or `translations`. |
644
- | `langPath` | `string` | URL path to fetch translation files. Expects files in `[path]/[lang].json` format. |
645
- | `translations` | `object` | An inline object containing key-value pairs (e.g., `{ "OK": "Confirm signature" }`). Overrides files. |
641
+ | `langPath` | `string` | URL path to fetch translation files. Expects files in `[path]/[lang].json` format. |
642
+ | `translations` | `object` | An inline object containing key-value pairs (e.g., `{ "OK": "Confirm signature" }`). Overrides files. |
646
643
 
647
644
  ## 🌐 Localization & Translation Keys
648
645
 
@@ -750,7 +747,7 @@ The following methods are available on the component instance to control the sig
750
747
  | `connect()` | `Promise<void>` | Connects device to component |
751
748
  | `disconnect()` | `Promise<void>` | Disconnects device from component |
752
749
  | `startSigning()` | `Promise<void>` | Initializes a new signing session on the canvas and hardware. |
753
- | `stopSigning()` | `Promise<any>` | Low-level session stop that returns the signature payload. |
750
+ | `stopSigning()` | `Promise<any>` | Low-level session stop that returns the signature payload. |
754
751
  | `ok()` | `Promise<ISignatureConfirmationData \| undefined>` | Finalizes the session, cleans the device screen, and returns the signature data. |
755
752
  | `clear()` | `Promise<void>` | Wipes the signature from the UI and hardware without ending the session. |
756
753
  | `cancel()` | `Promise<void>` | Aborts the current session and resets the component state. |
@@ -824,13 +821,12 @@ This is the standard way to confirm a signature. It:
824
821
  pressure: number,
825
822
  inContact: boolean,
826
823
  timestamp: number, // Unix ms (Date.now()) at the time of capture
827
- timestampInSeconds: number // seconds elapsed since the start of the signing session
828
824
  }
829
825
  ```
830
826
 
831
827
  ```js
832
828
  // [1] imageBase64 — base64 PNG data URL, or null if no image could be captured
833
- "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA..."
829
+ "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...";
834
830
  ```
835
831
 
836
832
  ```js
@@ -889,7 +885,6 @@ This is the standard way to confirm a signature. It:
889
885
  pressure: number,
890
886
  inContact: boolean,
891
887
  timestamp: number, // Unix ms (Date.now()) at the time of capture
892
- timestampInSeconds: number // seconds elapsed since the start of the signing session
893
888
  }
894
889
  ```
895
890
 
@@ -915,20 +910,20 @@ Stops the session immediately. It does not collect any signature data and resets
915
910
 
916
911
  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.
917
912
 
918
- | State | Value | Description |
919
- | :--------------------------- | :----------------------------- | :------------------------------------------------------------- |
920
- | `INITIAL` | `"initial"` | Component just mounted, no initialization yet. |
921
- | `CONNECTING` | `"connecting"` | Connection attempt in progress. |
922
- | `WAITING_FOR_DEVICE_SELECTION` | `"waiting_for_device_selection"` | Browser HID picker is open, waiting for user selection. |
923
- | `CONNECTED_PHYSICAL` | `"connected_physical"` | Physical tablet connected and ready. |
924
- | `CONNECTED_MOUSE_FALLBACK` | `"connected_mouse_fallback"` | No tablet found; mouse/touch fallback is active. |
925
- | `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`. |
926
- | `PROCESSING_OK` | `"processing_ok"` | OK action is being processed (finalizing signature). |
927
- | `PROCESSING_CLEAR` | `"processing_clear"` | Clear action is being processed. |
928
- | `PROCESSING_CANCEL` | `"processing_cancel"` | Cancel action is being processed. |
929
- | `DISCONNECTING` | `"disconnecting"` | Disconnect in progress. |
930
- | `DISCONNECTED` | `"disconnected"` | Component is idle and disconnected. |
931
- | `ERROR` | `"error"` | An unrecoverable error occurred (see `onError` callback). |
913
+ | State | Value | Description |
914
+ | :----------------------------- | :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
915
+ | `INITIAL` | `"initial"` | Component just mounted, no initialization yet. |
916
+ | `CONNECTING` | `"connecting"` | Connection attempt in progress. |
917
+ | `WAITING_FOR_DEVICE_SELECTION` | `"waiting_for_device_selection"` | Browser HID picker is open, waiting for user selection. |
918
+ | `CONNECTED_PHYSICAL` | `"connected_physical"` | Physical tablet connected and ready. |
919
+ | `CONNECTED_MOUSE_FALLBACK` | `"connected_mouse_fallback"` | No tablet found; mouse/touch fallback is active. |
920
+ | `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`. |
921
+ | `PROCESSING_OK` | `"processing_ok"` | OK action is being processed (finalizing signature). |
922
+ | `PROCESSING_CLEAR` | `"processing_clear"` | Clear action is being processed. |
923
+ | `PROCESSING_CANCEL` | `"processing_cancel"` | Cancel action is being processed. |
924
+ | `DISCONNECTING` | `"disconnecting"` | Disconnect in progress. |
925
+ | `DISCONNECTED` | `"disconnected"` | Component is idle and disconnected. |
926
+ | `ERROR` | `"error"` | An unrecoverable error occurred (see `onError` callback). |
932
927
 
933
928
  ---
934
929
 
@@ -1124,14 +1119,14 @@ signosoft-signpad {
1124
1119
 
1125
1120
  #### Primary Buttons (OK, Clear, Cancel)
1126
1121
 
1127
- | Variable | Description |
1128
- | :------------------------------------ | :----------------------------------- |
1129
- | `--sign-button-primary-bg-base` | Background color of primary buttons. |
1130
- | `--sign-button-primary-bg-hover` | Hover background color. |
1131
- | `--sign-button-primary-bg-disabled` | Disabled background color. |
1132
- | `--sign-button-primary-text-base` | Text color for primary buttons. |
1133
- | `--sign-button-primary-text-hover` | Hover text color. |
1134
- | `--sign-button-primary-text-disabled` | Disabled text color. |
1122
+ | Variable | Description |
1123
+ | :-------------------------------------- | :----------------------------------- |
1124
+ | `--sign-button-primary-bg-base` | Background color of primary buttons. |
1125
+ | `--sign-button-primary-bg-hover` | Hover background color. |
1126
+ | `--sign-button-primary-bg-disabled` | Disabled background color. |
1127
+ | `--sign-button-primary-text-base` | Text color for primary buttons. |
1128
+ | `--sign-button-primary-text-hover` | Hover text color. |
1129
+ | `--sign-button-primary-text-disabled` | Disabled text color. |
1135
1130
  | `--sign-button-primary-border-base` | Border of primary buttons. |
1136
1131
  | `--sign-button-primary-border-hover` | Hover border color. |
1137
1132
  | `--sign-button-primary-border-disabled` | Disabled border color. |
package/dist/index.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { ConnectionMode } from '@signosoft/tablet-driver';
1
2
  import { CSSResult } from 'lit';
2
3
  import { LitElement } from 'lit';
3
4
  import { TemplateResult } from 'lit-html';
@@ -168,8 +169,6 @@ declare class ConnectionManager {
168
169
  private penDataToDispatch;
169
170
  /** @private Minimum delay between pen events (approx 60fps) */
170
171
  private throttleDelayMs;
171
- /** @private Wall-clock time when the current signing session started, for timestampInSeconds */
172
- private sessionStartTime;
173
172
  private static readonly POINTER_FALLBACK_DEVICE_NAME;
174
173
  /**
175
174
  * @param component - The host SignosoftSignpad instance.
@@ -178,11 +177,12 @@ declare class ConnectionManager {
178
177
  /**
179
178
  * Initiates the connection process to a physical device or a mouse fallback.
180
179
  *
181
- * @param autoConnect - If true, attempts to connect without showing a device selection dialog.
180
+ * @param autoConnect - Connect mode: "manual" opens the browser device selection
181
+ * dialog; "auto"/"hotplug" attempt already-authorized devices silently.
182
182
  * @param allowFallback - If true, enables mouse/pointer input if no physical device is found.
183
183
  * @returns A promise resolving to true if connection (or fallback) was successful.
184
184
  */
185
- connect(autoConnect?: boolean, allowFallback?: boolean): Promise<boolean>;
185
+ connect(autoConnect?: ConnectionMode, allowFallback?: boolean): Promise<boolean>;
186
186
  /**
187
187
  * Terminates the connection with the device and cleans up the driver instance.
188
188
  * @returns Resolves when disconnection completes.
@@ -210,11 +210,6 @@ declare class ConnectionManager {
210
210
  * @returns A promise resolving to true if the session started successfully.
211
211
  */
212
212
  startSigning(canvas: HTMLCanvasElement, drawingOptions?: IDrawingOptions): Promise<boolean>;
213
- /**
214
- * Calculates the seconds elapsed since the start of the signing session.
215
- * @private
216
- */
217
- private timestampToSeconds;
218
213
  /**
219
214
  * Stops the current signing session if active.
220
215
  * @returns Signature data if available.
@@ -307,7 +302,6 @@ export declare interface IPenData {
307
302
  relativeY: number;
308
303
  pressure?: number;
309
304
  timestamp?: number;
310
- timestampInSeconds?: number;
311
305
  inContact: boolean;
312
306
  [key: string]: any;
313
307
  }
@@ -528,7 +522,8 @@ export declare class SignosoftSignpad extends LitElement {
528
522
  dispatch(name: string, detail?: any): void;
529
523
  /**
530
524
  * Attempts to establish a connection with a signature tablet.
531
- * @param autoConnect - If true, tries to connect without showing a device picker.
525
+ * @param autoConnect - Connect mode: "manual" opens the browser HID picker;
526
+ * "auto"/"hotplug" silently try already-authorized devices (see `ConnectionMode`).
532
527
  * @param allowFallback - If true, enables mouse/touch signing if no device is found.
533
528
  * @returns A promise resolving to true if connection (or fallback) succeeded.
534
529
  */
@@ -568,8 +563,24 @@ export declare class SignosoftSignpad extends LitElement {
568
563
  * - if physical is not available, allow fallback as a secondary attempt
569
564
  */
570
565
  connect: () => Promise<void>;
566
+ /**
567
+ * If currently in mouse fallback, tears that session down seamlessly
568
+ * (no DISCONNECTED UI flash) so a physical-device connect attempt can
569
+ * proceed cleanly.
570
+ */
571
571
  private prepareForManualConnect;
572
+ /**
573
+ * First step of the manual `connect()` flow: silently retries an
574
+ * already-authorized device (no HID picker) using "auto" mode.
575
+ * `allowFallback=false` ensures we only treat a real physical reconnect as success.
576
+ */
572
577
  private tryAuthorizedManualConnect;
578
+ /**
579
+ * Second step of the manual `connect()` flow, run only when the silent
580
+ * attempt above fails: opens the browser HID picker ("manual" mode) so
581
+ * the user can grant access to a new device. If the user cancels or no
582
+ * device is selected, falls back to one more silent "auto" attempt.
583
+ */
573
584
  private tryInteractiveManualConnectFallback;
574
585
  /**
575
586
  * UI disconnect action: delegates to the public disconnect method.