@signosoft/signpad-js 0.3.1 β†’ 0.3.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 +144 -68
  2. package/dist/index.d.ts +55 -18
  3. package/dist/signosoft-signpad.js +977 -799
  4. package/dist/signosoft-signpad.umd.cjs +47 -39
  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
 
@@ -40,11 +42,11 @@ It expertly handles the complexities of **WebHID device connections**, signature
40
42
 
41
43
  ## πŸ” Lease Setup
42
44
 
43
- To use the Signosoft Signpad component and its hardware drivers, a valid `lease` is **required**.
45
+ To use the Signosoft Signpad component with physical signature hardware, a valid `lease` is **required**.
44
46
 
45
47
  #### πŸ›‘ CRITICAL: Mandatory Initialization
46
48
 
47
- Without a valid lease, the component <b>WILL NOT INITIALIZE</b> and hardware communication features will be <b>disabled</b>.
49
+ Without a valid lease, the component can still render, but driver initialization and hardware communication features will be <b>disabled</b>.
48
50
 
49
51
  ### 1. Lease flow
50
52
 
@@ -129,7 +131,7 @@ To ensure proper communication via the **WebHID API**:
129
131
  First, install the core package:
130
132
 
131
133
  ```bash
132
- npm install your-library-name
134
+ npm install @signosoft/signpad-js
133
135
  ```
134
136
 
135
137
  ### 🧰 Framework Integration Guide
@@ -604,17 +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. |
611
- | `bottomBarVisible` | `boolean` | Shows/hides the entire bottom action bar. |
612
- | `okButtonVisible` | `boolean` | Shows the **OK** button in the bottom bar. |
613
- | `clearButtonVisible` | `boolean` | Shows the **Clear** button in the bottom bar. |
614
- | `cancelButtonVisible` | `boolean` | Shows the **Cancel** button in the bottom bar. |
615
- | `canvasLineVisible` | `boolean` | Shows the horizontal signature guide line on the canvas. |
616
- | `deviceStatusTextVisible` | `boolean` | Shows the name of the connected device (e.g., "Wacom STU-540"). |
617
- | `additionalTextVisible` | `boolean` | Shows helper status messages (e.g., "Ready to sign"). |
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. |
613
+ | `topBarConnectButtonVisible` | `boolean` | Shows the connect/disconnect button area in the top-right corner. |
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"). |
618
621
 
619
622
  ### πŸ–‹οΈ canvasAndDrawingOptions
620
623
 
@@ -632,11 +635,54 @@ Adjusts the visual appearance of the digital ink.
632
635
 
633
636
  Handles component localization. It can load external files or use inline definitions.
634
637
 
635
- | Field | Type | Description |
636
- | :------------- | :------- | :---------------------------------------------------------------------------------------------------- |
637
- | `lang` | `string` | The active language code (supported languages - `'en'`, `'cs'`, `'pt'`). |
638
- | `langPath` | `string` | URL path to fetch translation files. Expects files in `[path]/[lang].json` format. |
639
- | `translations` | `object` | An inline object containing key-value pairs (e.g., `{ "OK": "Confirm signature" }`). Overrides files. |
638
+ | Field | Type | Description |
639
+ | :------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- |
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`. |
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
+ | `NOT_CONNECTED` | Not Connected |
664
+ | `MOUSE` | Mouse |
665
+ | `CONNECTED_UNKNOWN_DEVICE` | Connected (Unknown Device) |
666
+ | `AUTO_CONNECTING` | Auto-connecting to device... |
667
+ | `CONNECTING_TO_DEVICE` | Connecting to your device... |
668
+ | `REVERTING_TO_DEFAULT` | Reverting to default input... |
669
+ | `DISCONNECTING_DEVICE` | Disconnecting device... |
670
+ | `COMPONENT_INITIALIZED` | Component initialized. |
671
+ | `TEXT_START_SIGNING` | Connect your device. |
672
+ | `TEXT_SIGN_WITH_PHYSICAL` | Please sign using the device pen. |
673
+ | `TEXT_SIGN_WITH_MOUSE` | Please sign using your mouse. |
674
+ | `TEXT_SIGN_GENERIC` | Sign in the area above using mouse or pen. |
675
+ | `TEXT_SIGNING_WITH_DEVICE` | Signing with {device} |
676
+ | `NO_DEVICE_FOUND` | No device found. |
677
+ | `CONNECTION_ERROR` | Connection error. |
678
+ | `ERROR_DISCONNECTION` | Error during disconnection. |
679
+ | `ERROR_INSTANTIATING_DRIVER` | Error instantiating driver. |
680
+ | `SIGNPAD_DISCONNECTED` | Signpad disconnected. |
681
+ | `INVALID_LICENSE_KEY` | Invalid license key. |
682
+ | `READY_TO_CONNECT` | Ready to connect. |
683
+ | `SIGNPAD_DETECTED` | Signpad detected. Click 'Connect Signpad' to begin. |
684
+
685
+ If you add any new keys, mirror them in every language file you provide to guarantee they fall back gracefully to English.
640
686
 
641
687
  ### βš™οΈ Logic & Events
642
688
 
@@ -658,13 +704,13 @@ Standard event listeners triggered _after_ specific actions. Useful for observin
658
704
 
659
705
  | Callback | Payload | Description |
660
706
  | :------------- | :----------------------------------------------- | :------------------------------------------------------------------------------------------------- |
661
- | `onPen` | `event: CustomEvent<IPenData> ` | Dispatched when a device or mouse fallback are in contact with component or signature pad display. |
662
- | `onConnect` | `event: CustomEvent` | Dispatched when a device or mouse fallback connects. |
663
- | `onDisconnect` | β€” | Dispatched when the hardware connection is closed. |
707
+ | `onPen` | `event: CustomEvent<IPenData>` | Dispatched when a device or mouse fallback are in contact with component or signature pad display. |
708
+ | `onConnect` | `event: CustomEvent<{ deviceInfo: any }>` | Dispatched when a device or mouse fallback connects. |
709
+ | `onDisconnect` | `event: CustomEvent<void>` | Dispatched when the hardware connection is closed. |
664
710
  | `onOk` | `event: CustomEvent<ISignatureConfirmationData>` | Dispatched when signature is confirmed. |
665
- | `onClear` | β€” | Dispatched when the canvas has been cleared. |
666
- | `onCancel` | β€” | Dispatched when the user aborts the session. |
667
- | `onError` | `error: Error` | Dispatched on critical failures (Lease, Driver, etc.). |
711
+ | `onClear` | `event: CustomEvent<void>` | Dispatched when the canvas has been cleared. |
712
+ | `onCancel` | `event: CustomEvent<void>` | Dispatched when the user aborts the session. |
713
+ | `onError` | `event: CustomEvent<Error>` | Dispatched on critical failures (lease, driver, connection, etc.). |
668
714
 
669
715
  > `actionHandlers` and `eventCallbacks` are separate hooks and can both be configured.
670
716
 
@@ -689,7 +735,7 @@ this.config = {
689
735
  eventCallbacks: {
690
736
  onConnect: (e) =>
691
737
  console.log("Pad connected:", e.detail.deviceInfo.deviceName),
692
- onError: (err) => console.error("Signpad Error:", err.message),
738
+ onError: (event) => console.error("Signpad Error:", event.detail.message),
693
739
  },
694
740
  };
695
741
  ```
@@ -703,7 +749,7 @@ The following methods are available on the component instance to control the sig
703
749
  | `connect()` | `Promise<boolean>` | Connects device to component |
704
750
  | `disconnect()` | `Promise<void>` | Disconnects device from component |
705
751
  | `startSigning()` | `Promise<void>` | Initializes a new signing session on the canvas and hardware. |
706
- | `stopSigning()` | `Promise<any>` | Immediately ends the session and returns the captured signature data. |
752
+ | `stopSigning()` | `Promise<any>` | Low-level session stop that returns the raw driver payload. |
707
753
  | `ok()` | `Promise<ISignatureConfirmationData \| undefined>` | Finalizes the session, cleans the device screen, and returns the signature data. |
708
754
  | `clear()` | `Promise<void>` | Wipes the signature from the UI and hardware without ending the session. |
709
755
  | `cancel()` | `Promise<void>` | Aborts the current session and resets the component state. |
@@ -848,7 +894,9 @@ This is the standard way to confirm a signature. It:
848
894
 
849
895
  #### πŸ“œ `stopSigning()`
850
896
 
851
- A low-level method that forces the driver to stop capturing data and returns the raw signature object. Unlike `ok()`, it does not trigger the full "Finalization" flow (UI transitions or device screen clearing).
897
+ A low-level method that forces the driver to stop capturing data and returns the raw driver payload. Unlike `ok()`, it does not trigger the full "Finalization" flow (UI transitions or device screen clearing).
898
+
899
+ > Note: `stopSigning()` intentionally exposes the unnormalized raw result, which is why it is documented as `Promise<any>`.
852
900
 
853
901
  #### πŸ“œ `clear()`
854
902
 
@@ -890,15 +938,24 @@ signosoft-signpad {
890
938
 
891
939
  /* CSS Variables */
892
940
  --sign-font-family: Arial, Helvetica, sans-serif;
941
+ --sign-common-border-radius: 8px;
893
942
 
894
943
  /* Top Bar */
895
944
  --sign-top-bar-bg-base: var(--background-color-10);
896
945
  --sign-top-bar-text-base: var(--primary-color-0);
897
946
  --sign-top-bar-padding: var(--spacing-constraints);
898
947
  --sign-top-bar-min-height: var(--min-height);
948
+ --sign-top-bar-border-top-left-radius: var(--sign-common-border-radius);
949
+ --sign-top-bar-border-top-right-radius: var(--sign-common-border-radius);
950
+ --sign-top-bar-border-bottom-left-radius: 0;
951
+ --sign-top-bar-border-bottom-right-radius: 0;
899
952
 
900
953
  /* Canvas Area */
901
954
  --sign-canvas-bg-base: var(--background-color-0);
955
+ --sign-canvas-wrapper-border-top-left-radius: 0;
956
+ --sign-canvas-wrapper-border-top-right-radius: 0;
957
+ --sign-canvas-wrapper-border-bottom-left-radius: 0;
958
+ --sign-canvas-wrapper-border-bottom-right-radius: 0;
902
959
 
903
960
  /* Line */
904
961
  --sign-line-height: 22px;
@@ -914,6 +971,12 @@ signosoft-signpad {
914
971
  --sign-bottom-bar-padding: var(--spacing-constraints);
915
972
  --sign-bottom-bar-min-height: var(--min-height);
916
973
  --sign-bottom-bar-gap: 12px;
974
+ --sign-bottom-bar-border-top-left-radius: 0;
975
+ --sign-bottom-bar-border-top-right-radius: 0;
976
+ --sign-bottom-bar-border-bottom-left-radius: var(--sign-common-border-radius);
977
+ --sign-bottom-bar-border-bottom-right-radius: var(
978
+ --sign-common-border-radius
979
+ );
917
980
 
918
981
  /* Button general settings */
919
982
  --sign-button-font-size: 16px;
@@ -958,16 +1021,17 @@ signosoft-signpad {
958
1021
 
959
1022
  #### Base Colors & General
960
1023
 
961
- | Variable | Default | Description |
962
- | :---------------------- | :------------------ | :-------------------------- |
963
- | `--primary-color-0` | `#4e56ea` | Primary brand color. |
964
- | `--primary-color-10` | `#7178ee` | Primary hover/accent color. |
965
- | `--background-color-0` | `#f1f2fd` | Secondary background color. |
966
- | `--background-color-10` | `#e3e4fc` | Main bar background color. |
967
- | `--text-color-0` | `#333e4a` | Main text color. |
968
- | `--white-color` | `#ffffff` | Pure white color. |
969
- | `--grey-color` | `#b5b9be` | Disabled state color. |
970
- | `--sign-font-family` | `Arial, sans-serif` | Global font family. |
1024
+ | Variable | Default | Description |
1025
+ | :---------------------------- | :------------------ | :---------------------------------------------- |
1026
+ | `--primary-color-0` | `#4e56ea` | Primary brand color. |
1027
+ | `--primary-color-10` | `#7178ee` | Primary hover/accent color. |
1028
+ | `--background-color-0` | `#f1f2fd` | Secondary background color. |
1029
+ | `--background-color-10` | `#e3e4fc` | Main bar background color. |
1030
+ | `--text-color-0` | `#333e4a` | Main text color. |
1031
+ | `--white-color` | `#ffffff` | Pure white color. |
1032
+ | `--grey-color` | `#b5b9be` | Disabled state color. |
1033
+ | `--sign-font-family` | `Arial, sans-serif` | Global font family. |
1034
+ | `--sign-common-border-radius` | `8px` | Shared radius token reused by bars and buttons. |
971
1035
 
972
1036
  #### Layout & Constraints
973
1037
 
@@ -978,34 +1042,46 @@ signosoft-signpad {
978
1042
 
979
1043
  #### Top Bar
980
1044
 
981
- | Variable | Default | Description |
982
- | :-------------------------- | :--------------------------- | :------------------------------- |
983
- | `--sign-top-bar-bg-base` | `var(--background-color-10)` | Background color of the top bar. |
984
- | `--sign-top-bar-text-base` | `var(--primary-color-0)` | Text color in the top bar. |
985
- | `--sign-top-bar-padding` | `var(--spacing-constraints)` | Inner padding of the top bar. |
986
- | `--sign-top-bar-min-height` | `var(--min-height)` | Minimum height of the top bar. |
1045
+ | Variable | Default | Description |
1046
+ | :------------------------------------------ | :--------------------------------- | :---------------------------------- |
1047
+ | `--sign-top-bar-bg-base` | `var(--background-color-10)` | Background color of the top bar. |
1048
+ | `--sign-top-bar-text-base` | `var(--primary-color-0)` | Text color in the top bar. |
1049
+ | `--sign-top-bar-padding` | `var(--spacing-constraints)` | Inner padding of the top bar. |
1050
+ | `--sign-top-bar-min-height` | `var(--min-height)` | Minimum height of the top bar. |
1051
+ | `--sign-top-bar-border-top-left-radius` | `var(--sign-common-border-radius)` | Top-left radius of the top bar. |
1052
+ | `--sign-top-bar-border-top-right-radius` | `var(--sign-common-border-radius)` | Top-right radius of the top bar. |
1053
+ | `--sign-top-bar-border-bottom-left-radius` | `0` | Bottom-left radius of the top bar. |
1054
+ | `--sign-top-bar-border-bottom-right-radius` | `0` | Bottom-right radius of the top bar. |
987
1055
 
988
1056
  #### Canvas & Signature Line
989
1057
 
990
- | Variable | Default | Description |
991
- | :---------------------------------- | :--------------------------------------------- | :-------------------------------------------- |
992
- | `--sign-canvas-bg-base` | `var(--background-color-0)` | Background color of the drawing area. |
993
- | `--sign-line-height` | `22px` | Vertical offset/height for the guide line. |
994
- | `--sign-line-margin-bottom` | `16px` | Bottom spacing used in canvas line layout. |
995
- | `--sign-line-border-base` | `var(--primary-color-10)` | Color of the signature guide line. |
996
- | `--sign-line-additional-text-color` | `var(--text-color-0)` | Color of the helper text below the line. |
997
- | `--sign-line-margin` | `0px 24px var(--sign-line-margin-bottom) 24px` | Spacing around the guide line. |
998
- | `--sign-canvas-line-text-font-size` | `12px` | Font size for guide line labels. |
999
- | `--sign-canvas-height-offset` | `var(--sign-line-height)` | Canvas offset calculation for the guide line. |
1058
+ | Variable | Default | Description |
1059
+ | :------------------------------------------------- | :--------------------------------------------- | :--------------------------------------------------------------------------- |
1060
+ | `--sign-canvas-bg-base` | `var(--background-color-0)` | Background color of the drawing area. |
1061
+ | `--sign-canvas-wrapper-border-top-left-radius` | `0` | Top-left canvas radius, typically rounded when the top bar is hidden. |
1062
+ | `--sign-canvas-wrapper-border-top-right-radius` | `0` | Top-right canvas radius, typically rounded when the top bar is hidden. |
1063
+ | `--sign-canvas-wrapper-border-bottom-left-radius` | `0` | Bottom-left canvas radius, typically rounded when the bottom bar is hidden. |
1064
+ | `--sign-canvas-wrapper-border-bottom-right-radius` | `0` | Bottom-right canvas radius, typically rounded when the bottom bar is hidden. |
1065
+ | `--sign-line-height` | `22px` | Vertical offset/height for the guide line. |
1066
+ | `--sign-line-margin-bottom` | `16px` | Bottom spacing used in canvas line layout. |
1067
+ | `--sign-line-border-base` | `var(--primary-color-10)` | Color of the signature guide line. |
1068
+ | `--sign-line-additional-text-color` | `var(--text-color-0)` | Color of the helper text below the line. |
1069
+ | `--sign-line-margin` | `0px 24px var(--sign-line-margin-bottom) 24px` | Spacing around the guide line. |
1070
+ | `--sign-canvas-line-text-font-size` | `12px` | Font size for guide line labels. |
1071
+ | `--sign-canvas-height-offset` | `var(--sign-line-height)` | Canvas offset calculation for the guide line. |
1000
1072
 
1001
1073
  #### Bottom Bar
1002
1074
 
1003
- | Variable | Default | Description |
1004
- | :----------------------------- | :--------------------------- | :--------------------------------------- |
1005
- | `--sign-bottom-bar-bg-base` | `var(--background-color-10)` | Background color of the bottom bar. |
1006
- | `--sign-bottom-bar-padding` | `var(--spacing-constraints)` | Inner padding of the bottom bar. |
1007
- | `--sign-bottom-bar-min-height` | `var(--min-height)` | Minimum height of the bottom bar. |
1008
- | `--sign-bottom-bar-gap` | `12px` | Space between buttons in the bottom bar. |
1075
+ | Variable | Default | Description |
1076
+ | :--------------------------------------------- | :--------------------------------- | :--------------------------------------- |
1077
+ | `--sign-bottom-bar-bg-base` | `var(--background-color-10)` | Background color of the bottom bar. |
1078
+ | `--sign-bottom-bar-padding` | `var(--spacing-constraints)` | Inner padding of the bottom bar. |
1079
+ | `--sign-bottom-bar-min-height` | `var(--min-height)` | Minimum height of the bottom bar. |
1080
+ | `--sign-bottom-bar-gap` | `12px` | Space between buttons in the bottom bar. |
1081
+ | `--sign-bottom-bar-border-top-left-radius` | `0` | Top-left radius of the bottom bar. |
1082
+ | `--sign-bottom-bar-border-top-right-radius` | `0` | Top-right radius of the bottom bar. |
1083
+ | `--sign-bottom-bar-border-bottom-left-radius` | `var(--sign-common-border-radius)` | Bottom-left radius of the bottom bar. |
1084
+ | `--sign-bottom-bar-border-bottom-right-radius` | `var(--sign-common-border-radius)` | Bottom-right radius of the bottom bar. |
1009
1085
 
1010
1086
  #### Buttons (General)
1011
1087
 
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
  /**
@@ -270,8 +267,6 @@ declare class ConnectionManager {
270
267
 
271
268
  export declare enum DeviceStatusText {
272
269
  NOT_CONNECTED = "NOT_CONNECTED",
273
- CONNECTED = "CONNECTED",
274
- CONNECTING = "CONNECTING",
275
270
  MOUSE = "MOUSE",
276
271
  CONNECTED_UNKNOWN = "CONNECTED_UNKNOWN_DEVICE"
277
272
  }
@@ -648,6 +643,11 @@ export declare class SignosoftSignpad extends LitElement {
648
643
  * @returns void
649
644
  */
650
645
  resetDrawingState(): void;
646
+ /**
647
+ * Enables or disables browser pointer interaction on the drawing canvas.
648
+ * Physical tablet mode disables browser pointer input to prevent mouse drawing.
649
+ */
650
+ setCanvasPointerInputEnabled(enabled: boolean): void;
651
651
  /**
652
652
  * Lit lifecycle: Invoked when the component is removed from the document's DOM.
653
653
  * Performs necessary cleanup of listeners and connections.
@@ -660,6 +660,19 @@ export declare class SignosoftSignpad extends LitElement {
660
660
  * @returns void
661
661
  */
662
662
  private handleWindowResize;
663
+ /**
664
+ * Connect button workflow:
665
+ * - if currently in mouse fallback, disconnect it first
666
+ * - then try physical device connect
667
+ * - if physical is not available, allow fallback as a secondary attempt
668
+ */
669
+ private handleConnectClick;
670
+ /**
671
+ * UI disconnect action:
672
+ * when physical device is active, switch seamlessly to mouse fallback.
673
+ * For other states, perform regular disconnect.
674
+ */
675
+ private handleDisconnectClick;
663
676
  /**
664
677
  * Attaches WebHID API event listeners for device connection and disconnection.
665
678
  * @private
@@ -684,6 +697,9 @@ export declare class SignosoftSignpad extends LitElement {
684
697
  * @returns void
685
698
  */
686
699
  private handleHIDDisconnect;
700
+ private shouldPromoteMouseFallback;
701
+ private shouldAutoConnectOnPlugIn;
702
+ private showSignpadDetectedState;
687
703
  /**
688
704
  * Initializes the CanvasManager for rendering signature strokes.
689
705
  * @private
@@ -708,8 +724,28 @@ export declare class SignosoftSignpad extends LitElement {
708
724
  private initializeFromConfigLeaseIfNeeded;
709
725
  private shouldAutoConnect;
710
726
  private autoConnectIfConfigured;
727
+ private canAttemptAutoConnect;
728
+ private ensureSignatureLayerReady;
729
+ private deferAutoConnectForState;
730
+ private clearPendingAutoConnectTimeout;
731
+ private performAutoConnectSequence;
732
+ private shouldScheduleImmediateRetry;
711
733
  private scheduleAutoConnectRetry;
712
734
  private clearAutoConnectQueue;
735
+ private delay;
736
+ /**
737
+ * Disconnects current session without transitioning through DISCONNECTED UI.
738
+ * Used for smooth mode switching (mouse <-> physical).
739
+ */
740
+ private disconnectForSeamlessSwitch;
741
+ /**
742
+ * Switches from physical tablet mode to mouse fallback after disconnect.
743
+ */
744
+ recoverToMouseFallback(messageKey?: string, minLoadingMs?: number): Promise<void>;
745
+ /**
746
+ * Promotes active mouse fallback session to a physical tablet when one is plugged in.
747
+ */
748
+ private promoteMouseFallbackToPhysical;
713
749
  /**
714
750
  * Renders the HTML template for the component.
715
751
  * Uses Lit's html template literal.
@@ -751,6 +787,7 @@ export declare enum SignpadEventType {
751
787
  export declare enum SignpadMessage {
752
788
  AUTO_CONNECTING = "AUTO_CONNECTING",
753
789
  CONNECTING_TO_DEVICE = "CONNECTING_TO_DEVICE",
790
+ REVERTING_TO_DEFAULT = "REVERTING_TO_DEFAULT",
754
791
  DISCONNECTING_DEVICE = "DISCONNECTING_DEVICE",
755
792
  COMPONENT_INITIALIZED = "COMPONENT_INITIALIZED",
756
793
  TEXT_START_SIGNING = "TEXT_START_SIGNING",
@@ -763,20 +800,14 @@ export declare enum SignpadMessage {
763
800
  ERROR_DISCONNECTION = "ERROR_DISCONNECTION",
764
801
  ERROR_INSTANTIATING_DRIVER = "ERROR_INSTANTIATING_DRIVER",
765
802
  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",
803
+ INVALID_LICENSE_KEY = "INVALID_LICENSE_KEY",
771
804
  READY_TO_CONNECT = "READY_TO_CONNECT",
772
- SIGNPAD_DETECTED = "SIGNPAD_DETECTED",
773
- NO_LICENSE_KEY = "NO_LICENSE_KEY"
805
+ SIGNPAD_DETECTED = "SIGNPAD_DETECTED"
774
806
  }
775
807
 
776
808
  export declare enum SignpadState {
777
809
  INITIAL = "initial",
778
810
  DISCONNECTED = "disconnected",
779
- FINISHED = "finished",
780
811
  CONNECTING = "connecting",
781
812
  WAITING_FOR_DEVICE_SELECTION = "waiting_for_device_selection",
782
813
  CONNECTED_PHYSICAL = "connected_physical",
@@ -834,6 +865,12 @@ declare class StateManager {
834
865
  * @returns True when connected or signing.
835
866
  */
836
867
  get isConnected(): boolean;
868
+ /**
869
+ * Returns true only for a physical device connection lifecycle.
870
+ * Mouse fallback is intentionally excluded.
871
+ * @returns True when a physical device is connected/signing/processing.
872
+ */
873
+ get isPhysicalConnected(): boolean;
837
874
  /**
838
875
  * Returns true if the component is performing an asynchronous operation.
839
876
  * @returns True when busy.