@signosoft/signpad-js 0.3.4 → 0.3.6

package/README.md

@@ -680,6 +680,8 @@ The complete list of keys that can be translated is maintained in `src/i18n/en.j
 | `INVALID_LICENSE_KEY`        | Invalid license key.                                |
 | `READY_TO_CONNECT`           | Ready to connect.                                   |
 | `SIGNPAD_DETECTED`           | Signpad detected. Click 'Connect Signpad' to begin. |
+| `READY_TO_SIGN_MOUSE`        | Ready to sign. Use your mouse.                      |
+| `READY_TO_SIGN_PHYSICAL`     | Ready to sign. Use the device pen.                  |
 
 If you add any new keys, mirror them in every language file you provide to guarantee they fall back gracefully to English.
 
@@ -704,6 +706,7 @@ Standard event listeners triggered _after_ specific actions. Useful for observin
 | Callback       | Payload                                          | Description                                                                                        |
 | :------------- | :----------------------------------------------- | :------------------------------------------------------------------------------------------------- |
 | `onPen`        | `event: CustomEvent<IPenData>`                   | Dispatched when a device or mouse fallback are in contact with component or signature pad display. |
+| `onConnecting` | `event: CustomEvent<void>`                       | Dispatched when a device is in loading state.                                                      |
 | `onConnect`    | `event: CustomEvent<{ deviceInfo: any }>`        | Dispatched when a device or mouse fallback connects.                                               |
 | `onDisconnect` | `event: CustomEvent<void>`                       | Dispatched when the hardware connection is closed.                                                 |
 | `onOk`         | `event: CustomEvent<ISignatureConfirmationData>` | Dispatched when signature is confirmed.                                                            |
@@ -745,7 +748,7 @@ The following methods are available on the component instance to control the sig
 
 | Method           | Returns                                            | Description                                                                      |
 | :--------------- | :------------------------------------------------- | :------------------------------------------------------------------------------- |
-| `connect()`      | `Promise<boolean>`                                 | Connects device to component                                                     |
+| `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.                      |
@@ -755,18 +758,15 @@ The following methods are available on the component instance to control the sig
 
 ---
 
-#### 📜 `connect(autoConnect = false, allowFallback = false)`
+#### 📜 `connect()`
 
-This is the primary method to start using the Signpad. Because it uses the **WebHID API**, the first time this is called (without `autoConnect`), it must be triggered by a **user gesture** (like a button click) to satisfy browser security requirements.
+This is the primary method to start using the Signpad. Because it uses the **WebHID API**, this must be triggered by a **user gesture** (like a button click) to satisfy browser security requirements.
 
-**Parameters:**
-
-- **`autoConnect`** (`boolean`): If set to `true`, the browser will attempt to reconnect to a previously paired and authorized device without opening the device selection dialog from WebHID.
-- **`allowFallback`** (`boolean`): If `true` and no physical device is found or connected, the component will automatically transition to **Mouse/Touch mode**, allowing the user to sign using their cursor.
+The method first attempts to silently reconnect to a previously authorized device. If that fails, it opens the browser's device selection dialog and, if no physical device is selected, falls back to mouse/touch mode automatically.
 
 **Returns:**
 
-- A `Promise<boolean>` that resolves to `true` if either a physical device or a fallback mode was successfully initialized.
+- A `Promise<void>` that resolves once the connection attempt (or fallback) is complete.
 
 #### 📜 `disconnect()`
 
@@ -782,8 +782,8 @@ Safely terminates the communication channel with the signature tablet.
 
 #### 💡 Best Practices
 
-- **Initial Connection:** Always call `connect(false, true)` from a click handler the very first time so the user can select their device from the browser list.
-- **Auto-Reconnect:** In many workflows, you can call `connect(true, true)`. If the user has already authorized the device in a previous session, it will connect silently.
+- **Initial Connection:** Always call `connect()` from a click handler so the user can select their device from the browser list.
+- **Auto-Reconnect:** Use `autoconnectOptions.autoConnect: true` in the config to silently reconnect to a previously authorized device on startup without a user gesture.
 - **Cleanup:** It is good practice to call `disconnect()` when the component is being destroyed or the user navigates away from the signing page to free up the USB port.
 
 #### 📜 `startSigning(options?: IDrawingOptions)`

package/dist/index.d.ts

@@ -338,6 +338,7 @@ export declare interface IEventCallbacks {
     onConnect?: (event: CustomEvent<{
         deviceInfo: any;
     }>) => void;
+    onConnecting?: (event: CustomEvent<void>) => void;
     onDisconnect?: (event: CustomEvent<void>) => void;
     onPen?: (event: CustomEvent<IPenData_2>) => void;
     onOk?: (event: CustomEvent<ISignatureConfirmationData>) => void;
@@ -669,9 +670,9 @@ export declare class SignosoftSignpad extends LitElement {
      * @param allowFallback - If true, enables mouse/touch signing if no device is found.
      * @returns A promise resolving to true if connection (or fallback) succeeded.
      */
-    connect(autoConnect?: boolean, allowFallback?: boolean): Promise<boolean>;
+    private connectWith;
     /**
-     * Closes the active tablet connection and cleans up the state.
+     * Closes the active tablet connection and switches to mouse fallback mode.
      * @returns A promise that resolves when disconnection is complete.
      */
     disconnect(): Promise<void>;
@@ -698,19 +699,18 @@ export declare class SignosoftSignpad extends LitElement {
      */
     private handleWindowResize;
     /**
-     * Connect button workflow:
+     * Runs the full connect flow:
      * - if currently in mouse fallback, disconnect it first
      * - then silently reconnect already-authorized HID devices that are plugged in
      * - otherwise run the interactive physical-device connect flow
      * - if physical is not available, allow fallback as a secondary attempt
      */
-    private connectFromUserAction;
+    connect: () => Promise<void>;
     private prepareForManualConnect;
     private tryAuthorizedManualConnect;
     private tryInteractiveManualConnectFallback;
     /**
-     * UI disconnect action:
-     * switches from physical device to mouse fallback without reconnecting the tablet.
+     * UI disconnect action: delegates to the public disconnect method.
      */
     private handleDisconnectClick;
     /**
@@ -826,7 +826,8 @@ export declare enum SignpadEventType {
     SIGN_CANCEL = "sign-cancel",
     SIGN_ERROR = "sign-error",
     SIGN_CONNECT = "sign-connect",
-    SIGN_DISCONNECT = "sign-disconnect"
+    SIGN_DISCONNECT = "sign-disconnect",
+    SIGN_CONNECTING = "sign-connecting"
 }
 
 export declare enum SignpadMessage {
@@ -847,7 +848,9 @@ export declare enum SignpadMessage {
     SIGNPAD_DISCONNECTED = "SIGNPAD_DISCONNECTED",
     INVALID_LICENSE_KEY = "INVALID_LICENSE_KEY",
     READY_TO_CONNECT = "READY_TO_CONNECT",
-    SIGNPAD_DETECTED = "SIGNPAD_DETECTED"
+    SIGNPAD_DETECTED = "SIGNPAD_DETECTED",
+    READY_TO_SIGN_MOUSE = "READY_TO_SIGN_MOUSE",
+    READY_TO_SIGN_PHYSICAL = "READY_TO_SIGN_PHYSICAL"
 }
 
 export declare enum SignpadState {