@signosoft/signpad-js 0.3.2 β†’ 0.3.4

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 +116 -71
  2. package/dist/index.d.ts +109 -27
  3. package/dist/signosoft-signpad.js +1058 -817
  4. package/dist/signosoft-signpad.umd.cjs +45 -45
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -2,14 +2,16 @@
2
2
 
3
3
  ## πŸ“ Table of Contents
4
4
 
5
- | Core Concepts & Overview | Getting Started & Usage | Advanced & Support |
6
- | :---------------------------------------- | :-------------------------------- | :--------------------------------- |
7
- | πŸ“œ [Description](#-description) | πŸ“¦ [Installation](#-installation) | πŸ’¬ [Feedback](#-feedback--support) |
8
- | 🎬 [Demo](#-demo) | πŸ” [Licensing](#-lease-setup) | πŸ› οΈ [Contributing](#-contributing) |
9
- | βš™οΈ [Tech stack](#-tech-stack--built-with) | πŸš€ [Quick Start](#-quick-start) | πŸ“„ [License](#-license) |
10
- | | πŸ“‹ [Properties](#-properties) | |
11
- | | 🧩 [Methods](#-methods) | |
12
- | | 🎨 [Styling](#-styling--theming) | |
5
+ | Core Concepts & Overview | Getting Started & Usage | Advanced & Support |
6
+ | :---------------------------------------- | :-------------------------------------------------- | :--------------------------------- |
7
+ | πŸ“œ [Description](#-description) | πŸ“¦ [Installation](#-installation) | πŸ’¬ [Feedback](#-feedback--support) |
8
+ | 🎬 [Demo](#-demo) | πŸ” [Licensing](#-lease-setup) | πŸ› οΈ [Contributing](#-contributing) |
9
+ | βš™οΈ [Tech stack](#-tech-stack--built-with) | πŸš€ [Quick Start](#-quick-start) | πŸ“„ [License](#-license) |
10
+ | | πŸ“‹ [Properties](#-properties) | |
11
+ | | 🧩 [Methods](#-methods) | |
12
+ | | 🎨 [Styling](#-styling--theming) | |
13
+ | | 🌐 [Localization](#-localization--translation-keys) |
14
+ | | |
13
15
 
14
16
  ## πŸ“œ Description
15
17
 
@@ -604,18 +606,18 @@ Controls how the component handles hardware connections and session flow.
604
606
 
605
607
  Toggles the visibility of specific User Interface elements.
606
608
 
607
- | Field | Type | Description |
608
- | :------------------------- | :-------- | :-------------------------------------------------------------- |
609
- | `topBarVisible` | `boolean` | Shows/hides the entire top navigation bar. |
610
- | `topBarClearButtonVisible` | `boolean` | Shows a "Clear" button in the top-left corner. |
609
+ | Field | Type | Description |
610
+ | :--------------------------- | :-------- | :---------------------------------------------------------------- |
611
+ | `topBarVisible` | `boolean` | Shows/hides the entire top navigation bar. |
612
+ | `topBarClearButtonVisible` | `boolean` | Shows a "Clear" button in the top-left corner. |
611
613
  | `topBarConnectButtonVisible` | `boolean` | Shows the connect/disconnect button area in the top-right corner. |
612
- | `bottomBarVisible` | `boolean` | Shows/hides the entire bottom action bar. |
613
- | `okButtonVisible` | `boolean` | Shows the **OK** button in the bottom bar. |
614
- | `clearButtonVisible` | `boolean` | Shows the **Clear** button in the bottom bar. |
615
- | `cancelButtonVisible` | `boolean` | Shows the **Cancel** button in the bottom bar. |
616
- | `canvasLineVisible` | `boolean` | Shows the horizontal signature guide line on the canvas. |
617
- | `deviceStatusTextVisible` | `boolean` | Shows the name of the connected device (e.g., "Wacom STU-540"). |
618
- | `additionalTextVisible` | `boolean` | Shows helper status messages (e.g., "Ready to sign"). |
614
+ | `bottomBarVisible` | `boolean` | Shows/hides the entire bottom action bar. |
615
+ | `okButtonVisible` | `boolean` | Shows the **OK** button in the bottom bar. |
616
+ | `clearButtonVisible` | `boolean` | Shows the **Clear** button in the bottom bar. |
617
+ | `cancelButtonVisible` | `boolean` | Shows the **Cancel** button in the bottom bar. |
618
+ | `canvasLineVisible` | `boolean` | Shows the horizontal signature guide line on the canvas. |
619
+ | `deviceStatusTextVisible` | `boolean` | Shows the name of the connected device (e.g., "Wacom STU-540"). |
620
+ | `additionalTextVisible` | `boolean` | Shows helper status messages (e.g., "Ready to sign"). |
619
621
 
620
622
  ### πŸ–‹οΈ canvasAndDrawingOptions
621
623
 
@@ -633,11 +635,53 @@ Adjusts the visual appearance of the digital ink.
633
635
 
634
636
  Handles component localization. It can load external files or use inline definitions.
635
637
 
636
- | Field | Type | Description |
637
- | :------------- | :------- | :---------------------------------------------------------------------------------------------------- |
638
+ | Field | Type | Description |
639
+ | :------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
638
640
  | `lang` | `string` | The active language code. Built-in translations are bundled for `'en'` and `'cs'`; other languages can be supplied via `langPath` or `translations`. |
639
- | `langPath` | `string` | URL path to fetch translation files. Expects files in `[path]/[lang].json` format. |
640
- | `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. |
643
+
644
+ ## 🌐 Localization & Translation Keys
645
+
646
+ Localization is driven from `languageOptions`, but you can also provide overrides at runtime:
647
+
648
+ 1. **Set the language code** in `config.languageOptions.lang`. English (`en`) is the fallback and Czech (`cs`) is shipped alongside it.
649
+ 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).
650
+ 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.
651
+ 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.
652
+
653
+ The complete list of keys that can be translated is maintained in `src/i18n/en.json`. You can copy the structure when creating new language files or inline overrides. The defaults are:
654
+
655
+ | Key | Default (English) |
656
+ | :--------------------------- | :-------------------------------------------------- |
657
+ | `OK` | OK |
658
+ | `CLEAR` | Clear |
659
+ | `CANCEL` | Cancel |
660
+ | `CLEAR_SIGNATURE` | Clear signature |
661
+ | `DISCONNECT` | Disconnect |
662
+ | `CONNECT_SIGNPAD` | Connect Signpad |
663
+ | `MOUSE` | Mouse |
664
+ | `CONNECTED_UNKNOWN_DEVICE` | Connected (Unknown Device) |
665
+ | `AUTO_CONNECTING` | Auto-connecting to device... |
666
+ | `CONNECTING_TO_DEVICE` | Connecting to your device... |
667
+ | `REVERTING_TO_DEFAULT` | Reverting to default input... |
668
+ | `DISCONNECTING_DEVICE` | Disconnecting device... |
669
+ | `COMPONENT_INITIALIZED` | Component initialized. |
670
+ | `TEXT_START_SIGNING` | Connect your device. |
671
+ | `TEXT_SIGN_WITH_PHYSICAL` | Please sign using the device pen. |
672
+ | `TEXT_SIGN_WITH_MOUSE` | Please sign using your mouse. |
673
+ | `TEXT_SIGN_GENERIC` | Sign in the area above using mouse or pen. |
674
+ | `TEXT_SIGNING_WITH_DEVICE` | Signing with {device} |
675
+ | `NO_DEVICE_FOUND` | No device found. |
676
+ | `CONNECTION_ERROR` | Connection error. |
677
+ | `ERROR_DISCONNECTION` | Error during disconnection. |
678
+ | `ERROR_INSTANTIATING_DRIVER` | Error instantiating driver. |
679
+ | `SIGNPAD_DISCONNECTED` | Signpad disconnected. |
680
+ | `INVALID_LICENSE_KEY` | Invalid license key. |
681
+ | `READY_TO_CONNECT` | Ready to connect. |
682
+ | `SIGNPAD_DETECTED` | Signpad detected. Click 'Connect Signpad' to begin. |
683
+
684
+ If you add any new keys, mirror them in every language file you provide to guarantee they fall back gracefully to English.
641
685
 
642
686
  ### βš™οΈ Logic & Events
643
687
 
@@ -690,8 +734,7 @@ this.config = {
690
734
  eventCallbacks: {
691
735
  onConnect: (e) =>
692
736
  console.log("Pad connected:", e.detail.deviceInfo.deviceName),
693
- onError: (event) =>
694
- console.error("Signpad Error:", event.detail.message),
737
+ onError: (event) => console.error("Signpad Error:", event.detail.message),
695
738
  },
696
739
  };
697
740
  ```
@@ -930,7 +973,9 @@ signosoft-signpad {
930
973
  --sign-bottom-bar-border-top-left-radius: 0;
931
974
  --sign-bottom-bar-border-top-right-radius: 0;
932
975
  --sign-bottom-bar-border-bottom-left-radius: var(--sign-common-border-radius);
933
- --sign-bottom-bar-border-bottom-right-radius: var(--sign-common-border-radius);
976
+ --sign-bottom-bar-border-bottom-right-radius: var(
977
+ --sign-common-border-radius
978
+ );
934
979
 
935
980
  /* Button general settings */
936
981
  --sign-button-font-size: 16px;
@@ -975,17 +1020,17 @@ signosoft-signpad {
975
1020
 
976
1021
  #### Base Colors & General
977
1022
 
978
- | Variable | Default | Description |
979
- | :---------------------- | :------------------ | :-------------------------- |
980
- | `--primary-color-0` | `#4e56ea` | Primary brand color. |
981
- | `--primary-color-10` | `#7178ee` | Primary hover/accent color. |
982
- | `--background-color-0` | `#f1f2fd` | Secondary background color. |
983
- | `--background-color-10` | `#e3e4fc` | Main bar background color. |
984
- | `--text-color-0` | `#333e4a` | Main text color. |
985
- | `--white-color` | `#ffffff` | Pure white color. |
986
- | `--grey-color` | `#b5b9be` | Disabled state color. |
987
- | `--sign-font-family` | `Arial, sans-serif` | Global font family. |
988
- | `--sign-common-border-radius` | `8px` | Shared radius token reused by bars and buttons. |
1023
+ | Variable | Default | Description |
1024
+ | :---------------------------- | :------------------ | :---------------------------------------------- |
1025
+ | `--primary-color-0` | `#4e56ea` | Primary brand color. |
1026
+ | `--primary-color-10` | `#7178ee` | Primary hover/accent color. |
1027
+ | `--background-color-0` | `#f1f2fd` | Secondary background color. |
1028
+ | `--background-color-10` | `#e3e4fc` | Main bar background color. |
1029
+ | `--text-color-0` | `#333e4a` | Main text color. |
1030
+ | `--white-color` | `#ffffff` | Pure white color. |
1031
+ | `--grey-color` | `#b5b9be` | Disabled state color. |
1032
+ | `--sign-font-family` | `Arial, sans-serif` | Global font family. |
1033
+ | `--sign-common-border-radius` | `8px` | Shared radius token reused by bars and buttons. |
989
1034
 
990
1035
  #### Layout & Constraints
991
1036
 
@@ -996,46 +1041,46 @@ signosoft-signpad {
996
1041
 
997
1042
  #### Top Bar
998
1043
 
999
- | Variable | Default | Description |
1000
- | :-------------------------- | :--------------------------- | :------------------------------- |
1001
- | `--sign-top-bar-bg-base` | `var(--background-color-10)` | Background color of the top bar. |
1002
- | `--sign-top-bar-text-base` | `var(--primary-color-0)` | Text color in the top bar. |
1003
- | `--sign-top-bar-padding` | `var(--spacing-constraints)` | Inner padding of the top bar. |
1004
- | `--sign-top-bar-min-height` | `var(--min-height)` | Minimum height of the top bar. |
1005
- | `--sign-top-bar-border-top-left-radius` | `var(--sign-common-border-radius)` | Top-left radius of the top bar. |
1006
- | `--sign-top-bar-border-top-right-radius` | `var(--sign-common-border-radius)` | Top-right radius of the top bar. |
1007
- | `--sign-top-bar-border-bottom-left-radius` | `0` | Bottom-left radius of the top bar. |
1008
- | `--sign-top-bar-border-bottom-right-radius` | `0` | Bottom-right radius of the top bar. |
1044
+ | Variable | Default | Description |
1045
+ | :------------------------------------------ | :--------------------------------- | :---------------------------------- |
1046
+ | `--sign-top-bar-bg-base` | `var(--background-color-10)` | Background color of the top bar. |
1047
+ | `--sign-top-bar-text-base` | `var(--primary-color-0)` | Text color in the top bar. |
1048
+ | `--sign-top-bar-padding` | `var(--spacing-constraints)` | Inner padding of the top bar. |
1049
+ | `--sign-top-bar-min-height` | `var(--min-height)` | Minimum height of the top bar. |
1050
+ | `--sign-top-bar-border-top-left-radius` | `var(--sign-common-border-radius)` | Top-left radius of the top bar. |
1051
+ | `--sign-top-bar-border-top-right-radius` | `var(--sign-common-border-radius)` | Top-right radius of the top bar. |
1052
+ | `--sign-top-bar-border-bottom-left-radius` | `0` | Bottom-left radius of the top bar. |
1053
+ | `--sign-top-bar-border-bottom-right-radius` | `0` | Bottom-right radius of the top bar. |
1009
1054
 
1010
1055
  #### Canvas & Signature Line
1011
1056
 
1012
- | Variable | Default | Description |
1013
- | :---------------------------------- | :--------------------------------------------- | :-------------------------------------------- |
1014
- | `--sign-canvas-bg-base` | `var(--background-color-0)` | Background color of the drawing area. |
1015
- | `--sign-canvas-wrapper-border-top-left-radius` | `0` | Top-left canvas radius, typically rounded when the top bar is hidden. |
1016
- | `--sign-canvas-wrapper-border-top-right-radius` | `0` | Top-right canvas radius, typically rounded when the top bar is hidden. |
1017
- | `--sign-canvas-wrapper-border-bottom-left-radius` | `0` | Bottom-left canvas radius, typically rounded when the bottom bar is hidden. |
1018
- | `--sign-canvas-wrapper-border-bottom-right-radius` | `0` | Bottom-right canvas radius, typically rounded when the bottom bar is hidden. |
1019
- | `--sign-line-height` | `22px` | Vertical offset/height for the guide line. |
1020
- | `--sign-line-margin-bottom` | `16px` | Bottom spacing used in canvas line layout. |
1021
- | `--sign-line-border-base` | `var(--primary-color-10)` | Color of the signature guide line. |
1022
- | `--sign-line-additional-text-color` | `var(--text-color-0)` | Color of the helper text below the line. |
1023
- | `--sign-line-margin` | `0px 24px var(--sign-line-margin-bottom) 24px` | Spacing around the guide line. |
1024
- | `--sign-canvas-line-text-font-size` | `12px` | Font size for guide line labels. |
1025
- | `--sign-canvas-height-offset` | `var(--sign-line-height)` | Canvas offset calculation for the guide line. |
1057
+ | Variable | Default | Description |
1058
+ | :------------------------------------------------- | :--------------------------------------------- | :--------------------------------------------------------------------------- |
1059
+ | `--sign-canvas-bg-base` | `var(--background-color-0)` | Background color of the drawing area. |
1060
+ | `--sign-canvas-wrapper-border-top-left-radius` | `0` | Top-left canvas radius, typically rounded when the top bar is hidden. |
1061
+ | `--sign-canvas-wrapper-border-top-right-radius` | `0` | Top-right canvas radius, typically rounded when the top bar is hidden. |
1062
+ | `--sign-canvas-wrapper-border-bottom-left-radius` | `0` | Bottom-left canvas radius, typically rounded when the bottom bar is hidden. |
1063
+ | `--sign-canvas-wrapper-border-bottom-right-radius` | `0` | Bottom-right canvas radius, typically rounded when the bottom bar is hidden. |
1064
+ | `--sign-line-height` | `22px` | Vertical offset/height for the guide line. |
1065
+ | `--sign-line-margin-bottom` | `16px` | Bottom spacing used in canvas line layout. |
1066
+ | `--sign-line-border-base` | `var(--primary-color-10)` | Color of the signature guide line. |
1067
+ | `--sign-line-additional-text-color` | `var(--text-color-0)` | Color of the helper text below the line. |
1068
+ | `--sign-line-margin` | `0px 24px var(--sign-line-margin-bottom) 24px` | Spacing around the guide line. |
1069
+ | `--sign-canvas-line-text-font-size` | `12px` | Font size for guide line labels. |
1070
+ | `--sign-canvas-height-offset` | `var(--sign-line-height)` | Canvas offset calculation for the guide line. |
1026
1071
 
1027
1072
  #### Bottom Bar
1028
1073
 
1029
- | Variable | Default | Description |
1030
- | :----------------------------- | :--------------------------- | :--------------------------------------- |
1031
- | `--sign-bottom-bar-bg-base` | `var(--background-color-10)` | Background color of the bottom bar. |
1032
- | `--sign-bottom-bar-padding` | `var(--spacing-constraints)` | Inner padding of the bottom bar. |
1033
- | `--sign-bottom-bar-min-height` | `var(--min-height)` | Minimum height of the bottom bar. |
1034
- | `--sign-bottom-bar-gap` | `12px` | Space between buttons in the bottom bar. |
1035
- | `--sign-bottom-bar-border-top-left-radius` | `0` | Top-left radius of the bottom bar. |
1036
- | `--sign-bottom-bar-border-top-right-radius` | `0` | Top-right radius of the bottom bar. |
1037
- | `--sign-bottom-bar-border-bottom-left-radius` | `var(--sign-common-border-radius)` | Bottom-left radius of the bottom bar. |
1038
- | `--sign-bottom-bar-border-bottom-right-radius` | `var(--sign-common-border-radius)` | Bottom-right radius of the bottom bar. |
1074
+ | Variable | Default | Description |
1075
+ | :--------------------------------------------- | :--------------------------------- | :--------------------------------------- |
1076
+ | `--sign-bottom-bar-bg-base` | `var(--background-color-10)` | Background color of the bottom bar. |
1077
+ | `--sign-bottom-bar-padding` | `var(--spacing-constraints)` | Inner padding of the bottom bar. |
1078
+ | `--sign-bottom-bar-min-height` | `var(--min-height)` | Minimum height of the bottom bar. |
1079
+ | `--sign-bottom-bar-gap` | `12px` | Space between buttons in the bottom bar. |
1080
+ | `--sign-bottom-bar-border-top-left-radius` | `0` | Top-left radius of the bottom bar. |
1081
+ | `--sign-bottom-bar-border-top-right-radius` | `0` | Top-right radius of the bottom bar. |
1082
+ | `--sign-bottom-bar-border-bottom-left-radius` | `var(--sign-common-border-radius)` | Bottom-left radius of the bottom bar. |
1083
+ | `--sign-bottom-bar-border-bottom-right-radius` | `var(--sign-common-border-radius)` | Bottom-right radius of the bottom bar. |
1039
1084
 
1040
1085
  #### Buttons (General)
1041
1086
 
package/dist/index.d.ts CHANGED
@@ -61,17 +61,14 @@ declare class ButtonManager {
61
61
  }
62
62
 
63
63
  /**
64
- * `CanvasManager` handles all low-level drawing operations on the HTMLCanvasElement.
65
- * It manages DPI scaling for high-resolution displays, stroke interpolation,
66
- * pressure-sensitive line thickness, and canvas state.
64
+ * `CanvasManager` is a lightweight canvas utility.
65
+ * Drawing is handled by SignatureLayer/SignatureCapture in `src/lib`.
67
66
  */
68
67
  declare class CanvasManager {
69
68
  /** @private The target canvas element */
70
69
  private canvas;
71
70
  /** @private The 2D rendering context */
72
71
  private ctx;
73
- /** @private The last point processed in the current stroke */
74
- private lastDrawPoint;
75
72
  /** @private The active configuration for line styles */
76
73
  private currentDrawingOptions;
77
74
  /**
@@ -91,9 +88,9 @@ declare class CanvasManager {
91
88
  */
92
89
  updateDrawingOptions(options: IDrawingOptions): void;
93
90
  /**
94
- * Draws a line segment between the previous point and the current pen data.
95
- * Handles coordinate normalization and pressure-based thickness.
96
- * @param penData - Data containing coordinates (0-1), pressure, and contact status.
91
+ * Kept for backward compatibility with callers that may still invoke it.
92
+ * The actual stroke rendering is done in `src/lib/SignatureCapture.js`.
93
+ * @param penData - Ignored.
97
94
  */
98
95
  drawSegment(penData: IPenData_2): void;
99
96
  /**
@@ -164,6 +161,12 @@ declare class ConfigManager {
164
161
  private clearConfigEventHandlers;
165
162
  }
166
163
 
164
+ export declare interface ConnectAttempt {
165
+ connected: boolean;
166
+ deviceInfo: any | null;
167
+ isPointerFallback: boolean;
168
+ }
169
+
167
170
  /**
168
171
  * `ConnectionManager` handles the lifecycle of the signature pad connection.
169
172
  * It manages driver initialization, license authentication, device handshaking,
@@ -184,6 +187,7 @@ declare class ConnectionManager {
184
187
  private penDataToDispatch;
185
188
  /** @private Minimum delay between pen events (approx 60fps) */
186
189
  private throttleDelayMs;
190
+ private static readonly POINTER_FALLBACK_DEVICE_NAME;
187
191
  /**
188
192
  * @param component - The host SignosoftSignpad instance.
189
193
  */
@@ -266,12 +270,29 @@ declare class ConnectionManager {
266
270
  * @returns Normalized device info or null.
267
271
  */
268
272
  private normalizeDeviceInfo;
273
+ /**
274
+ * Driver connect step (this is where interactive vs silent HID behavior happens).
275
+ * `autoConnect = false` may open the browser HID picker.
276
+ * `autoConnect = true` tries reconnecting already-authorized devices silently.
277
+ */
278
+ private runDriverConnectAttempt;
279
+ /**
280
+ * Chooses whether the component should finish in physical mode or mouse fallback.
281
+ * This step only decides state; it does not trigger HID dialog itself.
282
+ */
283
+ private resolveConnectionTarget;
284
+ /**
285
+ * Starts a fresh signing session for whichever target mode was selected.
286
+ */
287
+ private prepareSigningSession;
288
+ }
289
+
290
+ export declare interface ConnectionTarget {
291
+ targetState: SignpadState;
292
+ statusMessageKey: string;
269
293
  }
270
294
 
271
295
  export declare enum DeviceStatusText {
272
- NOT_CONNECTED = "NOT_CONNECTED",
273
- CONNECTED = "CONNECTED",
274
- CONNECTING = "CONNECTING",
275
296
  MOUSE = "MOUSE",
276
297
  CONNECTED_UNKNOWN = "CONNECTED_UNKNOWN_DEVICE"
277
298
  }
@@ -283,8 +304,19 @@ export declare interface IActionHandlers {
283
304
  }
284
305
 
285
306
  export declare interface IAutoconnectOptions {
307
+ /**
308
+ * Enables silent reconnect attempts to already-authorized devices
309
+ * during component startup/config updates.
310
+ */
286
311
  autoConnect?: boolean;
312
+ /**
313
+ * Triggers auto-connect flow when WebHID reports a plug-in event.
314
+ * If used without `autoConnect`, connection is attempted only after plug-in.
315
+ */
287
316
  autoConnectOnPlugIn?: boolean;
317
+ /**
318
+ * Starts a fresh signing session automatically after OK/Clear/Cancel actions.
319
+ */
288
320
  autoRestartSigningAfterAction?: boolean;
289
321
  }
290
322
 
@@ -320,7 +352,7 @@ export declare interface ILanguageOptions {
320
352
  translations?: ITranslationSet | Record<string, ITranslationSet>;
321
353
  }
322
354
 
323
- declare type IPenData_2 = {
355
+ declare interface IPenData_2 {
324
356
  relativeX: number;
325
357
  relativeY: number;
326
358
  absoluteX?: number;
@@ -331,7 +363,7 @@ declare type IPenData_2 = {
331
363
  timestamp?: number | bigint;
332
364
  inContact: boolean;
333
365
  [key: string]: any;
334
- };
366
+ }
335
367
  export { IPenData_2 as IPenData }
336
368
 
337
369
  export declare interface IPenDataCallback {
@@ -648,6 +680,11 @@ export declare class SignosoftSignpad extends LitElement {
648
680
  * @returns void
649
681
  */
650
682
  resetDrawingState(): void;
683
+ /**
684
+ * Enables or disables browser pointer interaction on the drawing canvas.
685
+ * Physical tablet mode disables browser pointer input to prevent mouse drawing.
686
+ */
687
+ setCanvasPointerInputEnabled(enabled: boolean): void;
651
688
  /**
652
689
  * Lit lifecycle: Invoked when the component is removed from the document's DOM.
653
690
  * Performs necessary cleanup of listeners and connections.
@@ -660,6 +697,22 @@ export declare class SignosoftSignpad extends LitElement {
660
697
  * @returns void
661
698
  */
662
699
  private handleWindowResize;
700
+ /**
701
+ * Connect button workflow:
702
+ * - if currently in mouse fallback, disconnect it first
703
+ * - then silently reconnect already-authorized HID devices that are plugged in
704
+ * - otherwise run the interactive physical-device connect flow
705
+ * - if physical is not available, allow fallback as a secondary attempt
706
+ */
707
+ private connectFromUserAction;
708
+ private prepareForManualConnect;
709
+ private tryAuthorizedManualConnect;
710
+ private tryInteractiveManualConnectFallback;
711
+ /**
712
+ * UI disconnect action:
713
+ * switches from physical device to mouse fallback without reconnecting the tablet.
714
+ */
715
+ private handleDisconnectClick;
663
716
  /**
664
717
  * Attaches WebHID API event listeners for device connection and disconnection.
665
718
  * @private
@@ -677,19 +730,22 @@ export declare class SignosoftSignpad extends LitElement {
677
730
  * @private
678
731
  * @returns void
679
732
  */
680
- private handleHIDConnect;
733
+ private onHidDeviceConnected;
681
734
  /**
682
735
  * Handler for HID device disconnection.
683
736
  * @private
684
737
  * @returns void
685
738
  */
686
- private handleHIDDisconnect;
739
+ private onHidDeviceDisconnected;
740
+ private isMouseFallbackActive;
741
+ private shouldAutoConnectOnPlugIn;
742
+ private showDeviceDetectedState;
687
743
  /**
688
744
  * Initializes the CanvasManager for rendering signature strokes.
689
745
  * @private
690
746
  * @returns void
691
747
  */
692
- private initializeCanvasManger;
748
+ private initializeCanvasManager;
693
749
  /**
694
750
  * Initializes the MouseManager for mouse and touch fallback.
695
751
  * @private
@@ -708,13 +764,38 @@ export declare class SignosoftSignpad extends LitElement {
708
764
  private initializeFromConfigLeaseIfNeeded;
709
765
  private shouldAutoConnect;
710
766
  private autoConnectIfConfigured;
767
+ private canAttemptAutoConnect;
768
+ private ensureSignatureLayerReady;
769
+ private deferAutoConnectForState;
770
+ private clearPendingAutoConnectTimeout;
771
+ private performAutoConnectSequence;
772
+ private shouldScheduleImmediateRetry;
711
773
  private scheduleAutoConnectRetry;
712
774
  private clearAutoConnectQueue;
775
+ private delay;
776
+ /**
777
+ * Disconnects current session without transitioning through DISCONNECTED UI.
778
+ * Used for smooth mode switching (mouse <-> physical).
779
+ */
780
+ private disconnectForSeamlessSwitch;
713
781
  /**
714
- * Renders the HTML template for the component.
715
- * Uses Lit's html template literal.
716
- * @returns Rendered template.
782
+ * Forces the component into mouse fallback mode without re-attempting physical reconnection.
717
783
  */
784
+ private activateMouseFallbackMode;
785
+ /**
786
+ * Starts fallback signing without running device connect flow.
787
+ * This keeps mouse drawing active after manual disconnect, even if a tablet
788
+ * stays physically plugged in.
789
+ */
790
+ private startMouseFallbackSigningSession;
791
+ /**
792
+ * Switches from physical tablet mode to mouse fallback after disconnect.
793
+ */
794
+ recoverToMouseFallback(messageKey?: string, minLoadingMs?: number): Promise<void>;
795
+ /**
796
+ * Promotes active mouse fallback session to a physical tablet when one is plugged in.
797
+ */
798
+ private promoteMouseFallbackToPhysical;
718
799
  render(): TemplateResult<1>;
719
800
  }
720
801
 
@@ -751,6 +832,7 @@ export declare enum SignpadEventType {
751
832
  export declare enum SignpadMessage {
752
833
  AUTO_CONNECTING = "AUTO_CONNECTING",
753
834
  CONNECTING_TO_DEVICE = "CONNECTING_TO_DEVICE",
835
+ REVERTING_TO_DEFAULT = "REVERTING_TO_DEFAULT",
754
836
  DISCONNECTING_DEVICE = "DISCONNECTING_DEVICE",
755
837
  COMPONENT_INITIALIZED = "COMPONENT_INITIALIZED",
756
838
  TEXT_START_SIGNING = "TEXT_START_SIGNING",
@@ -763,20 +845,14 @@ export declare enum SignpadMessage {
763
845
  ERROR_DISCONNECTION = "ERROR_DISCONNECTION",
764
846
  ERROR_INSTANTIATING_DRIVER = "ERROR_INSTANTIATING_DRIVER",
765
847
  SIGNPAD_DISCONNECTED = "SIGNPAD_DISCONNECTED",
766
- DEVICE_UNEXPECTEDLY_DISCONNECTED = "DEVICE_UNEXPECTEDLY_DISCONNECTED",
767
- SIGN_SUCCESSFUL = "SIGN_SUCCESSFUL",
768
- SIGN_CANCELLED = "SIGN_CANCELLED",
769
- SIGN_CLEARED = "SIGN_CLEARED",
770
- MISSING_LICENSE_KEY = "MISSING_LICENSE_KEY",
848
+ INVALID_LICENSE_KEY = "INVALID_LICENSE_KEY",
771
849
  READY_TO_CONNECT = "READY_TO_CONNECT",
772
- SIGNPAD_DETECTED = "SIGNPAD_DETECTED",
773
- NO_LICENSE_KEY = "NO_LICENSE_KEY"
850
+ SIGNPAD_DETECTED = "SIGNPAD_DETECTED"
774
851
  }
775
852
 
776
853
  export declare enum SignpadState {
777
854
  INITIAL = "initial",
778
855
  DISCONNECTED = "disconnected",
779
- FINISHED = "finished",
780
856
  CONNECTING = "connecting",
781
857
  WAITING_FOR_DEVICE_SELECTION = "waiting_for_device_selection",
782
858
  CONNECTED_PHYSICAL = "connected_physical",
@@ -834,6 +910,12 @@ declare class StateManager {
834
910
  * @returns True when connected or signing.
835
911
  */
836
912
  get isConnected(): boolean;
913
+ /**
914
+ * Returns true only for a physical device connection lifecycle.
915
+ * Mouse fallback is intentionally excluded.
916
+ * @returns True when a physical device is connected/signing/processing.
917
+ */
918
+ get isPhysicalConnected(): boolean;
837
919
  /**
838
920
  * Returns true if the component is performing an asynchronous operation.
839
921
  * @returns True when busy.