@signosoft/signpad-js 0.1.0 → 0.2.1

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 (9) hide show
  1. package/README.md +707 -308
  2. package/dist/index.d.ts +827 -119
  3. package/dist/signosoft-signpad.js +3929 -1954
  4. package/dist/signosoft-signpad.umd.cjs +79 -74
  5. package/docsVideo.gif +0 -0
  6. package/package.json +14 -3
  7. package/src/scripts/generate-theme.js +340 -0
  8. package/src/styles/signosoft-signpad.css +182 -0
  9. package/src/styles/styles-variables.css +76 -0
package/README.md CHANGED
@@ -1,376 +1,775 @@
1
+ # @signosoft/signpad-js
1
2
 
2
- ---
3
+ ## 📍 Table of Contents
3
4
 
4
- # @signosoft/signpad-js
5
+ | Core Concepts & Overview | Getting Started & Usage | Advanced & Support |
6
+ | :---------------------------------------- | :--------------------------------- | :--------------------------------- |
7
+ | 📜 [Description](#-description) | 📦 [Installation](#-installation) | 🤝 [Feedback](#-feedback--support) |
8
+ | 🎬 [Demo](#-demo) | 🔐 [Licensing](#-get-your-license) | 📄 [License](#-license) |
9
+ | ⚙️ [Tech stack](#-tech-stack--built-with) | 🚀 [Quick Start](#-quick-start) | |
10
+ | | 📋 [Properties](#-properties) | |
11
+ | | 🧩 [Methods](#-methods) | |
12
+ | | 🎨 [Styling](#-styling--theming) | |
13
+
14
+ ## 📜 Description
15
+
16
+ `signosoft-signpad` is a powerful and flexible web component built with LitElement, designed for seamless digital signature capture integration into modern web applications. It provides a **unified interface** for working with various signature devices like **Wacom or Ugee**, supporting both stylus and mouse-based signing.
17
+
18
+ This component **works effortlessly** with any modern stack:
19
+
20
+ <p align="center">
21
+ <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/javascript/javascript-original.svg" alt="JS" width="35" height="35">
22
+ <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React" width="35" height="35">
23
+ <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angularjs/angularjs-original.svg" alt="Angular" width="35" height="35">
24
+ <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vuejs/vuejs-original.svg" alt="Vue" width="35" height="35">
25
+ </p>
26
+
27
+ It expertly handles the complexities of **WebHID device connections**, signature session lifecycles, and high-fidelity stroke rendering.
28
+ <br/>
29
+
30
+ ## 🎬 Demo
31
+
32
+ <img src="https://unpkg.com/@signosoft/signpad-js@latest/docsVideo.gif" alt="Signosoft Demo" width="500" />
33
+
34
+ ## ⚙️ Tech Stack / Built With
35
+
36
+ - [![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=fff)](https://www.typescriptlang.org/)
37
+ - [![Lit](https://img.shields.io/badge/Lit-4C64FF?logo=Lit&logoColor=white)](https://lit.dev/)
38
+ - [![Vite](https://img.shields.io/badge/Vite-646CFF?logo=vite&logoColor=fff)](https://vitejs.dev/)
39
+ <br/>
40
+
41
+ ## 🔐 Get your license
42
+
43
+ To use the Signosoft Signpad component and its hardware drivers, a valid license key is **required**.
5
44
 
6
- [![npm version](https://badge.fury.io/js/%40signosoft%2Fsignpad-js.svg)](https://www.npmjs.com/package/@signosoft)
7
- [![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
45
+ #### 🛑 CRITICAL: Mandatory Initialization
8
46
 
9
- A LitElement web component for capturing signatures using a tablet (like Wacom) or mouse input, integrating seamlessly with the Signosoft signature driver powered by WebAssembly.
47
+ Without a valid license key, the component <b>WILL NOT INITIALIZE</b> and all hardware communication features will be <b>disabled</b>.
10
48
 
11
- ## Table of Contents
49
+ ### 1. How to obtain a license:
12
50
 
13
- - [Features](#features)
14
- - [Installation](#installation)
15
- - [Usage](#usage)
16
- - [Basic HTML Integration](#basic-html-integration)
17
- - [JavaScript Integration](#javascript-integration)
18
- - [Properties](#properties)
19
- - [Events](#events)
20
- - [Public Methods](#public-methods)
21
- - [Retrieving the Signature Image](#retrieving-the-signature-image)
22
- - [Styling](#styling)
51
+ 1. Go to [www.signosoft.com](https://www.signosoft.com)
52
+ 2. **Sign in** to your account.
53
+ 3. Navigate to **Settings** > **Get License**.
54
+ 4. Click **Generate API Key** (License Key).
55
+ 5. Copy your key and add it to your configuration.
23
56
 
24
- ## Features
57
+ ### 2. Implementation:
25
58
 
26
- - **Plug-and-Play Web Component:** Easily integrate into any web application or framework.
27
- - **Wacom Tablet Integration:** Connects with Signosoft's signature driver for high-fidelity pen input from supported tablets, utilizing WebAssembly for driver communication.
28
- - **Mouse Input Fallback:** Provides a seamless fallback to mouse input if a tablet is not connected or detected.
29
- - **Customizable UI:** Control visibility of top/bottom bars, action buttons (OK, Clear, Cancel), and text elements.
30
- - **Styling Flexibility:** Apply custom CSS variables to match your application's theme.
31
- - **Event-Driven:** Emits custom events for pen movements, signature actions (OK, Clear, Cancel), and connection status.
32
- - **TypeScript Support:** Fully typed for a robust development experience.
59
+ Add the key to the `licenseKey` field in your configuration object:
33
60
 
34
- ## Installation
61
+ ```typescript
62
+ const config: SignpadConfig = {
63
+ licenseKey: "YOUR-LICENSE-KEY-HERE", // Required
64
+ // ... other options
65
+
66
+ // For local development, ensure your license is valid for localhost.
67
+ };
68
+ ```
35
69
 
36
- You can install the component via npm:
70
+ <br/>
71
+
72
+ ## 📦 Installation
73
+
74
+ Install the library via npm:
37
75
 
38
76
  ```bash
39
77
  npm install @signosoft/signpad-js
40
78
  ```
41
79
 
42
- ## Usage
80
+ Or using your preferred manager:
81
+
82
+ ```bash
83
+ yarn add @signosoft/signpad-js
84
+ ```
85
+
86
+ ```bash
87
+ pnpm add @signosoft/signpad-js
88
+ ```
43
89
 
44
- ### Basic HTML Integration
90
+ ### 🌍 Environment Requirements
45
91
 
46
- Once installed, you can simply include the component in your HTML. Make sure your build process (e.g., Vite) correctly bundles the component for browser usage.
92
+ To ensure proper communication via the **WebHID API**:
47
93
 
48
- ```html
49
- <signosoft-signpad
50
- licenseKey="YOUR_BACKEND_LICENSE_KEY_HERE"
51
- .okButton="${async () => console.log("OK Button Pressed from outside!")}
52
- .clearButton=${async () => console.log("Clear Button Pressed from outside!")}
53
- .cancelButton=${async () => console.log("Cancel Button Pressed from outside!")}
54
-
55
- @sign-ok=${(e: CustomEvent<{ imageData: string | null }>) => { // Updated event detail type
56
- console.log("Signature OK event:", e.detail.imageData ? "Image data available." : "No image data.");
57
- // You can now access e.detail.imageData here
58
- }}
59
- @sign-clear=${() => console.log("Signature Clear event.")}
60
- @sign-cancel=${() => console.log("Signature Cancel event.")}
61
- @sign-pen=${(e: CustomEvent) => { /* console.log('Pen data:', e.detail) */ }}
62
- @sign-disconnect=${() => console.log("Device disconnected!")}
63
- @sign-error=${(e: CustomEvent) => console.error("Signpad error:", e.detail)}
64
- </signosoft-signpad>
65
- <button
66
- onclick="document.querySelector('signosoft-signpad').connectTablet(true)"
67
- >
68
- External Connect
69
- </button>
70
- <button
71
- onclick="document.querySelector('signosoft-signpad').disconnectTablet()"
72
- >
73
- External Disconnect
74
- </button>
75
- <button onclick="document.querySelector('signosoft-signpad').clear()">
76
- External Clear
77
- </button>
78
- <button onclick="document.querySelector('signosoft-signpad').ok()">
79
- External OK
80
- </button>
81
- <button onclick="document.querySelector('signosoft-signpad').cancel()">
82
- External Cancel
83
- </button>
94
+ - **HTTPS:** Required for all production environments (WebHID security policy).
95
+ - **Supported Browsers:** Chrome 89+, Edge 89+, Opera (Chromium-based).
96
+ - **TypeScript:** Built-in support; no extra `@types` needed.
97
+ <br/>
98
+
99
+ ## 🚀 Quick Start
100
+
101
+ First, install the core package:
102
+
103
+ ```bash
104
+ npm install your-library-name
84
105
  ```
85
106
 
86
- Note: Remember to replace `YOUR_BACKEND_LICENSE_KEY_HERE` with your actual backend license key for the Signosoft driver. The paths to the script might need adjustment based on your specific project setup and how you bundle the component.
107
+ ### 🧰 Framework Integration Guide
87
108
 
88
- ### JavaScript Integration
109
+ <details>
110
+ <summary>
111
+ <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angularjs/angularjs-original.svg" alt="Angular" width="15" height="15">
112
+ <b>Angular</b> <font color="green"><b>(Live)</b></font>
113
+ </summary>
114
+ <br>
89
115
 
90
- You can also interact with the component programmatically:
116
+ # <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angular/angular-original.svg" alt="Angular" width="30" height="30"> Angular Integration Guide
91
117
 
92
- ```typescript
93
- import { SignosoftSignpad } from "@signosoft/signpad-js";
118
+ This guide describes how to integrate the `@signosoft/signpad-js` web component into an Angular application.
94
119
 
95
- // If you're using a bundler (like Vite, Webpack), the component might be automatically registered.
96
- // If not, or for explicit registration, you can do:
97
- if (!customElements.get("signosoft-signpad")) {
98
- customElements.define("signosoft-signpad", SignosoftSignpad);
99
- }
120
+ ## 1. Installation
100
121
 
101
- const signpad = document.createElement("signosoft-signpad") as SignosoftSignpad;
102
- signpad.licenseKey = "YOUR_BACKEND_LICENSE_KEY_HERE";
103
- signpad.topBarVisible = true;
104
- signpad.bottomBarVisible = true;
105
- signpad.minThickness = 2;
106
- signpad.maxThickness = 8;
107
- signpad.penColor = "blue";
108
-
109
- // Assign callback functions for internal button actions
110
- signpad.OkButton = async () => {
111
- console.log("Custom OK action triggered!");
112
- // This callback runs *after* the sign-ok event is dispatched with imageData.
113
- // You might not need to retrieve the image here if you listen to the 'sign-ok' event.
114
- };
122
+ Install the core package using npm:
115
123
 
116
- signpad.ClearButton = async () => {
117
- console.log("Custom Clear action triggered!");
118
- };
124
+ ```bash
125
+ npm install @signosoft/signpad-js
126
+ ```
119
127
 
120
- signpad.CancelButton = async () => {
121
- console.log("Custom Cancel action triggered!");
122
- };
128
+ ## 2. Create the Bridge Directive
129
+
130
+ Since `signosoft-signpad` is a Web Component, Angular requires a Directive to properly sync configuration changes and provide typed access to the component instance.
131
+
132
+ Create `signosoft-signpad.directive.ts`:
133
+
134
+ ```typescript
135
+ import {
136
+ Directive,
137
+ ElementRef,
138
+ Input,
139
+ OnChanges,
140
+ SimpleChanges,
141
+ } from "@angular/core";
142
+ import type { SignosoftSignpad, SignpadConfig } from "@signosoft/signpad-js";
143
+
144
+ @Directive({
145
+ selector: "signosoft-signpad",
146
+ standalone: true,
147
+ })
148
+ export class SignosoftSignpadDirective implements OnChanges {
149
+ @Input() config?: SignpadConfig;
150
+
151
+ constructor(private host: ElementRef<SignosoftSignpad>) {}
152
+
153
+ // Access the native Web Component instance
154
+ get signpadRef(): SignosoftSignpad {
155
+ return this.host.nativeElement;
156
+ }
123
157
 
124
- // Listen for custom events
125
- signpad.addEventListener("sign-ok", (event: CustomEvent<{ imageData: string | null }>) => {
126
- console.log("Signature confirmed. Image data available:", !!event.detail.imageData);
127
- // event.detail.imageData now contains the Base64 image string
128
- if (event.detail.imageData) {
129
- const imgElement = document.getElementById('mySignatureDisplay') as HTMLImageElement;
130
- if (imgElement) {
131
- imgElement.src = event.detail.imageData;
132
- imgElement.style.display = 'block';
158
+ ngOnChanges(changes: SimpleChanges) {
159
+ const el = this.host.nativeElement as any;
160
+ for (const key of Object.keys(changes)) {
161
+ el[key] = (this as any)[key];
133
162
  }
134
163
  }
135
- });
136
- signpad.addEventListener("sign-error", (event) => {
137
- console.error("An error occurred:", event.detail);
138
- });
139
- signpad.addEventListener("sign-pen", (event) => {
140
- // console.log('Pen data:', event.detail);
141
- });
164
+ }
165
+ ```
142
166
 
143
- document.body.appendChild(signpad);
167
+ ## 3. Implementation in Component
144
168
 
145
- // Programmatically connect the tablet
146
- async function connectAndSign() {
147
- const connected = await signpad.connectTablet(true); // Attempt auto-connect
148
- if (connected) {
149
- console.log("Tablet connected and ready for signing!");
150
- } else {
151
- console.warn("Could not connect to tablet.");
169
+ Import the library, the directive, and add the **`CUSTOM_ELEMENTS_SCHEMA`**.
170
+
171
+ ```typescript
172
+ import { Component, ViewChild, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
173
+ import "@signosoft/signpad-js"; // Import the Web Component registration
174
+ import {
175
+ type SignosoftSignpad,
176
+ type SignpadConfig,
177
+ } from "@signosoft/signpad-js";
178
+ import { SignosoftSignpadDirective } from "./directives/signosoft-signpad.directive";
179
+
180
+ @Component({
181
+ selector: "app-root",
182
+ standalone: true,
183
+ imports: [SignosoftSignpadDirective],
184
+ templateUrl: "./app.component.html",
185
+ schemas: [CUSTOM_ELEMENTS_SCHEMA], // Mandatory for custom HTML tags
186
+ })
187
+ export class AppComponent {
188
+ @ViewChild(SignosoftSignpadDirective)
189
+ signpadDirective!: SignosoftSignpadDirective;
190
+
191
+ config: SignpadConfig = {
192
+ licenseKey: "YOUR-LICENSE-KEY",
193
+ // More info in "properties" section
194
+ };
195
+
196
+ // Helper to access methods easily (ok, clear, cancel, etc.)
197
+ public get signpad(): SignosoftSignpad | undefined {
198
+ return this.signpadDirective?.signpadRef;
152
199
  }
153
200
  }
201
+ ```
202
+
203
+ ## 4. Component Template
154
204
 
155
- connectAndSign();
205
+ Use the custom tag in your HTML and bind the configuration object.
156
206
 
157
- // To disconnect later:
158
- // await signpad.disconnectTablet();
207
+ ```html
208
+ <div>
209
+ <div>
210
+ <signosoft-signpad [config]="config"></signosoft-signpad>
211
+ </div>
212
+ </div>
159
213
  ```
160
214
 
161
- ## Properties
162
-
163
- You can customize the component's behavior and appearance using the following properties:
164
-
165
- | Property | Type | Default Value | Description |
166
- | :----------------------- | :--------------------------------- | :-------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
167
- | `licenseKey` | `string` | `"DEBUG-licence-backend-key-localhost"` | Backend license key for the signature driver. **Crucial for driver functionality.** |
168
- | `topBarVisible` | `boolean` | `true` | Controls the visibility of the top action bar (containing Clear, Disconnect/Connect buttons). |
169
- | `bottomBarVisible` | `boolean` | `true` | Controls the visibility of the bottom action bar (containing OK, Clear, Cancel buttons). |
170
- | `okButtonVisible` | `boolean` | `true` | Controls the visibility of the 'OK' button in the bottom bar. |
171
- | `clearButtonVisible` | `boolean` | `true` | Controls the visibility of the 'Clear' button in the bottom bar. |
172
- | `cancelButtonVisible` | `boolean` | `true` | Controls the visibility of the 'Cancel' button in the bottom bar. |
173
- | `canvasLineVisible` | `boolean` | `true` | Controls the visibility of the line on the canvas that separates device state/additional text. |
174
- | `deviceStateTextVisible` | `boolean` | `true` | Controls the visibility of the device state text in the canvas footer. |
175
- | `customDeviceStateText` | `string \| null` | `null` | Optional custom text to display for the device state, overriding the default. |
176
- | `minThickness` | `number` | `1` | Minimum pen stroke thickness in pixels. |
177
- | `maxThickness` | `number` | `5` | Maximum pen stroke thickness in pixels (at full pressure). |
178
- | `penColor` | `string` | `"#000000"` | Pen stroke color (CSS color, e.g., `'#000000'` or `'red'`). |
179
- | `customCssVariables` | `Record<string, string>` | `{}` | An object containing CSS custom property names as keys and their values as strings. These will be applied directly to the component's host element for styling customization. E.g., `{ "--signpad-canvas-bg": "#f9f9f9" }`. |
180
- | `OkButton` | `() => Promise<void> \| undefined` | `undefined` | Optional callback function (async or sync) to execute when the public `ok()` method is called, either internally or externally. It runs *after* the component's internal processing and `sign-ok` event dispatch. |
181
- | `ClearButton` | `() => Promise<void> \| undefined` | `undefined` | Optional callback function (async or sync) to execute when the public `clear()` method is called, either internally or externally. It runs after the component's internal processing. |
182
- | `CancelButton` | `() => Promise<void> \| undefined` | `undefined` | Optional callback function (async or sync) to execute when the public `cancel()` method is called, either internally or externally. It runs after the component's internal processing. |
183
- | `canvasAdditionalText` | `string \| null` | `null` | Optional additional text to display in the canvas footer. If `null` or empty, a default text will be shown. Default behavior is "Connect your device to start signing" when disconnected/error, and "Sign with [device name]" when connected. |
184
-
185
- ## Events
186
-
187
- The component dispatches several [custom events](https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent) that you can listen for:
188
-
189
- | Event Name | Detail Type (`event.detail`) | Description |
190
- | :---------------- | :--------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
191
- | `sign-pen` | `PenData` | Fired on every pen movement (Wacom or mouse) with `penData` (x, y, pressure, inContact, etc.). |
192
- | `sign-clear` | `void` | Fired when the signature is cleared (via internal UI button, tablet event, or `clear()` method). |
193
- | `sign-cancel` | `void` | Fired when the signature process is cancelled (via internal UI button, tablet event, or `cancel()` method). |
194
- | `sign-ok` | `{ imageData: string \| null }` | Fired when the 'OK' action is completed (via internal UI button, tablet event, or `ok()` method). The `event.detail` will contain an object with the key `imageData`, holding the Base64 encoded string of the signature from the canvas. This is dispatched *before* the component is disconnected and cleared. |
195
- | `sign-disconnect` | `void` | Fired if the tablet unexpectedly disconnects. |
196
- | `sign-error` | `Error` | Fired when an error occurs during connection or initialization, or any other critical issue. The `event.detail` will contain an `Error` object. |
197
-
198
- ## Public Methods
199
-
200
- You can programmatically control the component using its public methods:
201
-
202
- | Method | Arguments | Returns | Description |
203
- | :-------------------------- | :-------------------------------------------------------------------------------------- | :----------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
204
- | `connectTablet()` | `autoConnect?: boolean` (default: `false`), `allowFallback: boolean` (default: `false`) | `Promise<boolean>` | Connects to the signature tablet. This involves obtaining a license, initializing the signature layer, connecting to the device, and starting the signing process. If `autoConnect` is `true`, it attempts to select the first available device automatically. Returns `true` on success, `false` otherwise. |
205
- | `disconnectTablet()` | `void` | `Promise<void>` | Disconnects from the signature tablet and resets its state. |
206
- | `clear()` | `void` | `Promise<void>` | Clears the current signature from both the tablet's screen and the component's canvas. Invokes the optional `ClearButton` external callback (if provided) and then dispatches a `sign-clear` custom event. |
207
- | `ok()` | `void` | `Promise<void>` | Handles the 'OK' action, typically stopping the signing process. Retrieves the signature image data from the canvas, dispatches it via the `sign-ok` event, then executes the optional `OkButton` callback, and finally disconnects the component. |
208
- | `cancel()` | `void` | `Promise<void>` | Handles the 'Cancel' action, which typically clears any drawn signature and stops the signing process. If a `CancelButton` callback function is provided, it will be executed. Finally, a `sign-cancel` custom event is dispatched. |
209
- | `getSignatureImageBase64()` | `format?: string` (default: `'image/png'`), `quality?: number` | `string \| null` | Retrieves the current signature drawn on the canvas as a Base64 encoded image string. `format` specifies the image type (e.g., `'image/png'`, `'image/jpeg'`). `quality` (0-1) applies to `'image/jpeg'` or `'image/webp'`. Returns `null` if the canvas is not available or no drawing has started. |
210
- | `downloadSignatureImage()` | `filename?: string` (default: `'signature.png'`), `format?: string`, `quality?: number` | `void` | Triggers a download of the current signature drawn on the canvas as an image file. Uses `getSignatureImageBase64()` internally. |
211
-
212
- ## Retrieving the Signature Image
213
-
214
- There are two primary ways to retrieve the signature image from the `signosoft-signpad` component:
215
-
216
- ### 1. Using the `sign-ok` Event (Recommended for post-signing actions)
217
-
218
- When the user confirms their signature by pressing the "OK" button (either on the tablet or in the UI), the component dispatches a `sign-ok` custom event. This event's `detail` property now includes the Base64 encoded string of the signature image. This is the most common and robust way to get the final signature for submission or display.
215
+ </details>
219
216
 
220
- ```typescript
221
- import { SignosoftSignpad } from "@signosoft/signpad-js";
222
-
223
- const signpadElement = document.querySelector('signosoft-signpad') as SignosoftSignpad;
224
-
225
- if (signpadElement) {
226
- signpadElement.addEventListener('sign-ok', (event: CustomEvent<{ imageData: string | null }>) => {
227
- const signatureBase64 = event.detail.imageData;
228
-
229
- if (signatureBase64) {
230
- console.log("Signature captured successfully (Base64 string length:", signatureBase64.length, ")");
231
-
232
- // Example 1: Display the image in an <img> tag
233
- const imgElement = document.getElementById('signatureDisplay') as HTMLImageElement;
234
- if (imgElement) {
235
- imgElement.src = signatureBase64;
236
- imgElement.style.display = 'block';
237
- }
238
-
239
- // Example 2: Send the Base64 string to your backend server
240
- /*
241
- fetch('/api/save-signature', {
242
- method: 'POST',
243
- headers: { 'Content-Type': 'application/json' },
244
- body: JSON.stringify({ signature: signatureBase64 }),
245
- })
246
- .then(response => response.json())
247
- .then(data => console.log('Signature saved on server:', data))
248
- .catch(error => console.error('Error saving signature:', error));
249
- */
250
-
251
- } else {
252
- console.warn("No signature image data was available after 'OK' action.");
253
- }
254
- });
255
-
256
- // Remember to handle other events like 'sign-clear' to clear the displayed image
257
- signpadElement.addEventListener('sign-clear', () => {
258
- const imgElement = document.getElementById('signatureDisplay') as HTMLImageElement;
259
- if (imgElement) {
260
- imgElement.src = '';
261
- imgElement.style.display = 'none';
262
- }
263
- });
217
+ <details>
218
+ <summary>
219
+ <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React" width="15" height="15">
220
+ <b>React</b> <font color="green"><b>(Live)</b></font>
221
+ </summary>
222
+ <br>
223
+
224
+ # <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React" width="30" height="30"> React - Quick start
225
+
226
+ This guide describes how to integrate the `@signosoft/signpad-js` web component into a React application (Functional Components with Hooks).
227
+
228
+ ## 1. Installation
229
+
230
+ Install the core package using npm:
231
+
232
+ ```bash
233
+ npm install @signosoft/signpad-js
234
+ ```
235
+
236
+ ## 2. Implementation
237
+
238
+ In React, we use the `useRef` hook to interact with the component's methods (like `ok()` or `clear()`) and pass the configuration directly via props.
239
+
240
+ ```tsx
241
+ import { useRef } from "react";
242
+ import "@signosoft/signpad-js"; // Registers the web component
243
+ import type { SignpadConfig } from "@signosoft/signpad-js";
244
+
245
+ function App() {
246
+ // Use ref to access component methods (ok, clear, connect, etc. by signpadRef.current)
247
+ const signpadRef = useRef<any>(null);
248
+
249
+ const config: SignpadConfig = {
250
+ licenseKey: "YOUR-LICENSE-KEY",
251
+ // More info in "properties" section
252
+ };
253
+
254
+ return (
255
+ <div>
256
+ <h1>Signosoft Signpad React Example</h1>
257
+ <signosoft-signpad ref={signpadRef} config={config} />
258
+ </div>
259
+ );
264
260
  }
261
+
262
+ export default App;
265
263
  ```
266
264
 
267
- ### 2. Using Public Methods (`getSignatureImageBase64` and `downloadSignatureImage`)
265
+ </details>
268
266
 
269
- You can also programmatically request the signature image at any time while the component is connected and drawing.
267
+ <details>
268
+ <summary>
269
+ <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vuejs/vuejs-original.svg" alt="Vue" width="15" height="15">
270
+ <b>Vue.js</b> <font color="green"><b>(Live)</b></font>
271
+ </summary>
272
+ <br>
270
273
 
271
- #### `getSignatureImageBase64(format?: string, quality?: number)`
274
+ # <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vuejs/vuejs-original.svg" alt="Vue" width="30" height="30"> Vue.js Integration Guide
272
275
 
273
- This method returns the signature as a Base64 encoded string.
276
+ This guide describes how to integrate the `@signosoft/signpad-js` web component into a Vue 3 application using the Composition API (`<script setup>`).
274
277
 
275
- ```typescript
276
- import { SignosoftSignpad } from "@signosoft/signpad-js";
278
+ ## 1. Installation
277
279
 
278
- const signpadElement = document.querySelector('signosoft-signpad') as SignosoftSignpad;
280
+ Install the core package using npm:
279
281
 
280
- // ... (after connecting and some drawing has occurred) ...
282
+ ```bash
283
+ npm install @signosoft/signpad-js
284
+ ```
281
285
 
282
- if (signpadElement) {
283
- // Get as PNG (default)
284
- const pngBase64 = signpadElement.getSignatureImageBase64();
285
- if (pngBase64) {
286
- console.log("PNG Signature Base64:", pngBase64.substring(0, 50) + "...");
287
- }
286
+ ## 2. Configure Vue to recognize Custom Elements
288
287
 
289
- // Get as JPEG with 80% quality
290
- const jpegBase64 = signpadElement.getSignatureImageBase64('image/jpeg', 0.8);
291
- if (jpegBase64) {
292
- console.log("JPEG Signature Base64:", jpegBase64.substring(0, 50) + "...");
293
- }
294
- }
288
+ By default, Vue will try to resolve `signosoft-signpad` as a Vue component and will throw a warning. You need to tell Vue to ignore this tag.
289
+
290
+ **If you are using Vite (`vite.config.ts`):**
291
+
292
+ ```typescript
293
+ import { defineConfig } from "vite";
294
+ import vue from "@vitejs/plugin-vue";
295
+
296
+ export default defineConfig({
297
+ plugins: [
298
+ vue({
299
+ template: {
300
+ compilerOptions: {
301
+ // Treat all tags starting with 'signosoft-' as custom elements
302
+ isCustomElement: (tag) => tag.startsWith("signosoft-"),
303
+ },
304
+ },
305
+ }),
306
+ ],
307
+ });
295
308
  ```
296
309
 
297
- #### `downloadSignatureImage(filename?: string, format?: string, quality?: number)`
310
+ ## 3. Implementation
298
311
 
299
- This method triggers a download of the signature as an image file directly in the browser.
312
+ In Vue 3, we use `ref` to hold the reference to the DOM element and pass the configuration via the `:config` attribute.
300
313
 
301
314
  ```typescript
302
- import { SignosoftSignpad } from "@signosoft/signpad-js";
315
+ <script setup lang="ts">
316
+ import { ref } from "vue";
317
+ import "@signosoft/signpad-js"; // Registers the Web Component
318
+ import type { SignpadConfig, SignosoftSignpad, IPenData } from "@signosoft/signpad-js";
319
+
320
+ // Use ref to access component methods (ok, clear, connect, etc. by signpadRef.value)
321
+ const signpadRef = ref<SignosoftSignpad | null>(null);
303
322
 
304
- const signpadElement = document.querySelector('signosoft-signpad') as SignosoftSignpad;
323
+ const signpadConfig: SignpadConfig = {
324
+ licenseKey: "YOUR-LICENSE-KEY",
325
+ // More info in "properties" section
326
+ };
327
+
328
+ </script>
305
329
 
306
- // ... (after connecting and some drawing has occurred) ...
330
+ <template>
331
+ <div>
332
+ <signosoft-signpad
333
+ ref="signpadRef"
334
+ :config="signpadConfig"
335
+ ></signosoft-signpad>
336
+ </div>
337
+ </template>
338
+ ```
307
339
 
308
- if (signpadElement) {
309
- // Download as 'my-signature.png' (default)
310
- signpadElement.downloadSignatureImage('my-signature.png');
340
+ </details>
311
341
 
312
- // Download as 'document-signature.jpeg' with 90% quality
313
- signpadElement.downloadSignatureImage('document-signature.jpeg', 'image/jpeg', 0.9);
314
- }
342
+ <details>
343
+ <summary>
344
+ <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/javascript/javascript-original.svg" alt="JS" width="15" height="15">
345
+ <b>Vanilla JS</b> <font color="green"><b>(Live)</b></font>
346
+ </summary>
347
+ <br>
348
+
349
+ # 🍦 Vanilla JS Integration Guide
350
+
351
+ This guide describes how to integrate the `@signosoft/signpad-js` web component into a plain JavaScript project without any frameworks.
352
+
353
+ ## 1. Installation
354
+
355
+ Install the package via npm:
356
+
357
+ ```bash
358
+ npm install @signosoft/signpad-js
359
+ ```
360
+
361
+ Or, if you are not using a bundler, you can include the script directly in your HTML (ensure the path points to the compiled bundle in `node_modules` or a CDN).
362
+
363
+ ## 2. JavaScript Implementation
364
+
365
+ In Vanilla JS, you interact with the component by selecting it from the DOM and assigning the configuration directly to its `config` property.
366
+
367
+ ```javascript
368
+ import "@signosoft/signpad-js";
369
+
370
+ /**
371
+ * INTELLISENSE SUPPORT (Optional)
372
+ * Helps VS Code provide autocomplete for methods and properties.
373
+ * @type {import('@signosoft/signpad-js').SignosoftSignpad}
374
+ */
375
+ const pad = document.querySelector("signosoft-signpad");
376
+
377
+ // 1. Initial Configuration
378
+ pad.config = {
379
+ licenseKey: "YOUR-LICENSE-KEY",
380
+ };
381
+ ```
382
+
383
+ ## 3. HTML Structure
384
+
385
+ Add the custom element tag to your HTML and create the necessary control buttons.
386
+
387
+ ```html
388
+ <!-- index.html -->
389
+ <!DOCTYPE html>
390
+ <html lang="en">
391
+ <head>
392
+ <meta charset="UTF-8" />
393
+ <title>Signosoft Signpad - Vanilla JS</title>
394
+ </head>
395
+ <body>
396
+ <h1>Signosoft Signpad</h1>
397
+ <!-- The Web Component -->
398
+ <signosoft-signpad id="my-signpad"></signosoft-signpad>
399
+ <!-- Main logic script -->
400
+ <script type="module" src="main.js"></script>
401
+ </body>
402
+ </html>
403
+ ```
404
+
405
+ ## 4. Key Concepts
406
+
407
+ - **Direct Property Assignment:** Unlike some frameworks that use attributes, in Plain JS you should assign the configuration directly: `element.config = { ... }`.
408
+ - **Module System:** Ensure your `<script>` tag has `type="module"` to use the `import` statement.
409
+ - **Methods:** All methods like `.connect()`, `.ok()`, and `.clear()` are available directly on the DOM element object.
410
+ - **DOM Events:** The component dispatches standard DOM events (like `sign-ok`, `sign-clear`) which you can listen to using `addEventListener`.
411
+
412
+ </details>
413
+
414
+ ## 📋 Properties
415
+
416
+ The component is primarily configured through a single `config` property. This object controls everything from licensing and hardware behavior to UI visibility and localization.
417
+
418
+ | Property | Type | Default | Description |
419
+ | :------- | :-------------- | :---------- | :----------------------------------------------- |
420
+ | `config` | `SignpadConfig` | `undefined` | The main configuration object for the component. |
421
+
422
+ ### 🔑 Core Options
423
+
424
+ | Option | Type | Required | Description |
425
+ | :------------------- | :------- | :------- | :-------------------------------------------------------------------- |
426
+ | **`licenseKey`** | `string` | **Yes** | Your unique API key from signosoft.com. Mandatory for initialization. |
427
+ | `customCssVariables` | `object` | No | Custom theme object generated via the `getSignpadTheme` utility. |
428
+
429
+ ### 🔄 autoconnectOptions
430
+
431
+ Controls how the component handles hardware connections and session flow.
432
+
433
+ | Field | Type | Default | Description |
434
+ | :------------------------------ | :-------- | :------ | :---------------------------------------------------------------------------------------------------- |
435
+ | `autoConnect` | `boolean` | `false` | Attempts to connect to an authorized device on startup. Defaults to mouse mode if no device is found. |
436
+ | `autoConnectOnPlugIn` | `boolean` | `false` | Automatically initiates connection when a compatible and authorized device is plugged into USB. |
437
+ | `autoRestartSigningAfterAction` | `boolean` | `false` | Automatically calls `startSigning()` after a user completes an action (OK/Cancel). |
438
+
439
+ ### 👁️ uiVisibilityOptions
440
+
441
+ Toggles the visibility of specific User Interface elements.
442
+
443
+ | Field | Type | Description |
444
+ | :------------------------- | :-------- | :-------------------------------------------------------------- |
445
+ | `topBarVisible` | `boolean` | Shows/hides the entire top navigation bar. |
446
+ | `topBarClearButtonVisible` | `boolean` | Shows a "Clear" button in the top-left corner. |
447
+ | `bottomBarVisible` | `boolean` | Shows/hides the entire bottom action bar. |
448
+ | `okButtonVisible` | `boolean` | Shows the **OK** button in the bottom bar. |
449
+ | `clearButtonVisible` | `boolean` | Shows the **Clear** button in the bottom bar. |
450
+ | `cancelButtonVisible` | `boolean` | Shows the **Cancel** button in the bottom bar. |
451
+ | `canvasLineVisible` | `boolean` | Shows the horizontal signature guide line on the canvas. |
452
+ | `deviceStatusTextVisible` | `boolean` | Shows the name of the connected device (e.g., "Wacom STU-540"). |
453
+ | `additionalTextVisible` | `boolean` | Shows helper status messages (e.g., "Ready to sign"). |
454
+
455
+ ### 🖋️ canvasAndDrawingOptions
456
+
457
+ Adjusts the visual appearance of the digital ink.
458
+
459
+ | Field | Type | Default | Description |
460
+ | :--------- | :------- | :-------- | :------------------------------------------ |
461
+ | `color` | `string` | `#000000` | The HEX color of the signature stroke. |
462
+ | `minWidth` | `number` | `1` | The line thickness at minimum pen pressure. |
463
+ | `maxWidth` | `number` | `3` | The line thickness at maximum pen pressure. |
464
+
465
+ > Note: Since standard mice do not support physical pressure, the system emulates a normalized pressure of 0.5, ensuring consistent line rendering during fallback sessions.
466
+
467
+ ### 🌐 languageOptions
468
+
469
+ Handles component localization. It can load external files or use inline definitions.
470
+
471
+ | Field | Type | Description |
472
+ | :------------- | :------- | :---------------------------------------------------------------------------------------------------- |
473
+ | `lang` | `string` | The active language code (supported languages - `'en'`, `'cs'`, `'pt'`). |
474
+ | `langPath` | `string` | URL path to fetch translation files. Expects files in `[path]/[lang].json` format. |
475
+ | `translations` | `object` | An inline object containing key-value pairs (e.g., `{ "OK": "Confirm signature" }`). Overrides files. |
476
+
477
+ ### ⚙️ Logic & Events
478
+
479
+ The component provides two ways to interact with internal processes.
480
+
481
+ #### 🛠️ Action Handlers (`actionHandlers`)
482
+
483
+ These allow you to **inject custom logic** directly into the internal button flows. Your code runs alongside the component's internal logic.
484
+
485
+ | Handler | Arguments | Description |
486
+ | :------------- | :----------- | :---------------------------------------------------------------------- |
487
+ | `handleOk` | `data?: any` | Extends the internal OK button logic. Receives captured signature data. |
488
+ | `handleClear` | — | Extends the internal Clear button logic. |
489
+ | `handleCancel` | — | Extends the internal Cancel button logic. |
490
+
491
+ #### 🔔 Event Callbacks (`eventCallbacks`)
492
+
493
+ Standard event listeners triggered _after_ specific actions. Useful for observing the component from your application state.
494
+
495
+ | Callback | Payload | Description |
496
+ | :------------- | :------------------------------ | :------------------------------------------------------------------------------------------------- |
497
+ | `onPen` | `event: CustomEvent<IPenData> ` | Dispatched when a device or mouse fallback are in contact with component or signature pad display. |
498
+ | `onConnect` | `event: CustomEvent` | Dispatched when a device or mouse fallback connects. |
499
+ | `onDisconnect` | — | Dispatched when the hardware connection is closed. |
500
+ | `onOk` | `data: any` | Dispatched when signature is confirmed. |
501
+ | `onClear` | — | Dispatched when the canvas has been cleared. |
502
+ | `onCancel` | — | Dispatched when the user aborts the session. |
503
+ | `onError` | `error: Error` | Dispatched on critical failures (License, Driver, etc.). |
504
+
505
+ ---
506
+
507
+ ### 💡 Example Implementation
508
+
509
+ ```typescript
510
+ this.config = {
511
+ licenseKey: "your-signosoft-license-key",
512
+ autoconnectOptions: {
513
+ autoConnect: true,
514
+ },
515
+ canvasAndDrawingOptions: {
516
+ color: "#1a1a1a",
517
+ },
518
+ actionHandlers: {
519
+ handleOk: async (data) => {
520
+ console.log("Saving signature data...", data);
521
+ },
522
+ },
523
+ eventCallbacks: {
524
+ onConnect: (e) =>
525
+ console.log("Pad connected:", e.detail.deviceInfo.deviceName),
526
+ onError: (err) => console.error("Signpad Error:", err.message),
527
+ },
528
+ };
315
529
  ```
316
530
 
317
- **Note:** The `getSignatureImageBase64` method returns `null` if the canvas is not available or if no drawing has been started (`_hasStartedDrawing` is false). For `downloadSignatureImage`, if no image data is available, a console warning will be logged, and no download will occur.
531
+ ## 🧩 Methods
532
+
533
+ The following methods are available on the component instance to control the signing process programmatically.
534
+
535
+ | Method | Returns | Description |
536
+ | :--------------- | :----------------- | :------------------------------------------------------------------------------- |
537
+ | `connect()` | `Promise<boolean>` | Connects device to component |
538
+ | `disconnect()` | `Promise<void>` | Disconnects device from component |
539
+ | `startSigning()` | `Promise<void>` | Initializes a new signing session on the canvas and hardware. |
540
+ | `stopSigning()` | `Promise<any>` | Immediately ends the session and returns the captured signature data. |
541
+ | `ok()` | `Promise<any>` | Finalizes the session, cleans the device screen, and returns the signature data. |
542
+ | `clear()` | `Promise<void>` | Wipes the signature from the UI and hardware without ending the session. |
543
+ | `cancel()` | `Promise<void>` | Aborts the current session and resets the component state. |
318
544
 
319
545
  ---
320
546
 
321
- ## Styling
547
+ #### 📜 `connect(autoConnect = false, allowFallback = false)`
322
548
 
323
- The component can be styled using standard CSS and by overriding custom CSS variables on the host element (`<signosoft-signpad>`) or through the `customCssVariables` property.
549
+ 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.
324
550
 
325
- Example of custom CSS variables (check `signosoft-signpad.css` for a full list of available variables):
551
+ **Parameters:**
326
552
 
327
- ```css
328
- export const myCustomSignpadTheme = {
329
- // Font
330
- "--sign-font-family": "Arial, Helvetica, sans-serif",
331
- // Top Bar
332
- "--sign-top-bar-bg-base": "#e3e4fc",
333
- "--sign-top-bar-text-base": "#4e56ea",
334
-
335
- // Canvas Area
336
- "--sign-canvas-bg-base": "#f1f2fd",
337
-
338
- // Line
339
- "--sign-line-height-base": "22px",
340
- "--sign-line-border-base": "#7178ee",
341
- "--sign-line-additional-text-color": "#333E4A",
342
-
343
- // Bottom Bar
344
- "--sign-bottom-bar-bg-base": "#e3e4fc",
345
-
346
- // Primary Buttons (OK, Clear, Cancel)
347
- "--sign-button-primary-bg-base": "#4e56ea",
348
- "--sign-button-primary-bg-hover": "#7178ee",
349
- "--sign-button-primary-bg-disabled": "#b5b9be",
350
- "--sign-button-primary-text-base": "#ffffff",
351
- "--sign-button-primary-text-hover": "#ffffff",
352
- "--sign-button-primary-text-disabled": "white",
353
-
354
- // Link Buttons (Connect signpad)
355
- "--sign-button-link-bg-base": "transparent",
356
- "--sign-button-link-bg-hover": "#e3e4fc",
357
- "--sign-button-link-bg-disabled": "transparent",
358
- "--sign-button-link-text-base": "#4e56ea",
359
- "--sign-button-link-text-hover": "#7178ee",
360
- "--sign-button-link-text-disabled": "#b5b9be",
361
- "--sign-button-link-border-base": "1px solid #4e56ea",
362
- "--sign-button-link-border-hover": "1px solid #7178ee",
363
- "--sign-button-link-border-disabled": "1px solid #b5b9be",
364
-
365
- // Device State Text Colors
366
- "--sign-device-state-text-color-connected": "green",
367
- "--sign-device-state-text-color-disconnected": "red",
368
-
369
- // Loading Overlay
370
- "--sign-loading-overlay-bg-color": "rgba(255, 255, 255, 0.8);",
371
- "--sign-loading-overlay-text-color": "#333e4a",
372
- "--sign-loading-overlay-spinner-color": "#4e56ea",
373
- "--sign-loading-overlay-spinner-border-color": "rgba(78, 86, 234, 0.1)",
374
- "--sign-loading-overlay-spinner-size": "30px",
553
+ - **`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.
554
+ - **`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.
555
+
556
+ **Returns:**
557
+
558
+ - A `Promise<boolean>` that resolves to `true` if either a physical device or a fallback mode was successfully initialized.
559
+
560
+ #### 📜 `disconnect()`
561
+
562
+ Safely terminates the communication channel with the signature tablet.
563
+
564
+ **What happens during disconnect:**
565
+
566
+ 1. The hardware driver is stopped and released.
567
+ 2. The internal cache of device information is cleared.
568
+ 3. The component UI transitions back to the `DISCONNECTED` state.
569
+ 4. Any active mouse listeners are removed.
570
+ 5. A `SIGN_DISCONNECT` event is dispatched.
571
+
572
+ #### 💡 Best Practices
573
+
574
+ - **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.
575
+ - **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.
576
+ - **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.
577
+
578
+ #### 📜 `startSigning(options?: IDrawingOptions)`
579
+
580
+ Prepares the component for a new signature. It transitions the state to `CONNECTING`, resets any previous drawing data, and activates the pen input for either a physical device or mouse fallback.
581
+
582
+ ```typescript
583
+ // Example: Start a session with custom ink
584
+ await signpad.startSigning({
585
+ color: "#0000FF",
586
+ maxWidth: 4,
587
+ minWidth: 2,
588
+ });
589
+ ```
590
+
591
+ If you have `autoRestartSigningAfterAction` enabled in your config, the component will automatically call `startSigning()` again after an `ok` or `cancel` action is completed.
592
+
593
+ #### 📜 `ok()`
594
+
595
+ This is the standard way to confirm a signature. It:
596
+
597
+ 1. Stops the signing process.
598
+ 2. Clears the physical device's screen (if connected).
599
+ 3. Dispatches the `SIGN_OK` event.
600
+ 4. Returns the final signature payload (coordinates, pressure, metadata).
601
+
602
+ #### 📜 `stopSigning()`
603
+
604
+ 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).
605
+
606
+ #### 📜 `clear()`
607
+
608
+ Resets the drawing state on both the web canvas and the physical tablet's display. This allows the user to start their signature over without leaving the current session. It dispatches the `SIGN_CLEAR` event.
609
+
610
+ #### 📜 `cancel()`
611
+
612
+ Stops the session immediately. It does not collect any signature data and resets the component to its ready state. This method dispatches the `SIGN_CANCEL` event.
613
+
614
+ ## 🎨 Styling & Theming
615
+
616
+ The component is designed to be fully customizable to match your brand's identity. You can style it using **CSS Variables** or by using our built-in **Theme Generator**.
617
+
618
+ ### 🛠️ Built-in Theme Generator
619
+
620
+ The easiest way to create a consistent theme is to use our CLI utility. It generates a configuration object that you can pass directly to the component.
621
+
622
+ **1. Run the generator in your terminal:**
623
+
624
+ ```bash
625
+ npx getSignpadTheme
626
+ ```
627
+
628
+ The CLI will guide you through:
629
+
630
+ - **Output path:** Where to save the file.
631
+ - **Filename:** What to call the file.
632
+ - **Format:** Choose between `.js` or `.ts`.
633
+
634
+ **2. Import and apply the theme:**
635
+ Once generated, import the file and pass it to your configuration object:
636
+
637
+ ```typescript
638
+ import { myCustomTheme } from "./styles/myCustomTheme";
639
+
640
+ this.config = {
641
+ licenseKey: "...",
642
+ customCssVariables: myCustomTheme,
375
643
  };
376
- ```
644
+ ```
645
+
646
+ ### ✍️ Manual CSS Customization
647
+
648
+ You can override the CSS variables directly in your global stylesheet to fine-tune the appearance:
649
+
650
+ ```css
651
+ signosoft-signpad {
652
+ --primary-color-0: #0056b3;
653
+ --sign-canvas-bg-base: #ffffff;
654
+ }
655
+ ```
656
+
657
+ ### 📋 Full CSS Variable Reference
658
+
659
+ #### Base Colors & General
660
+
661
+ | Variable | Default | Description |
662
+ | :---------------------- | :------------------ | :-------------------------- |
663
+ | `--primary-color-0` | `#4e56ea` | Primary brand color. |
664
+ | `--primary-color-10` | `#7178ee` | Primary hover/accent color. |
665
+ | `--background-color-0` | `#f1f2fd` | Secondary background color. |
666
+ | `--background-color-10` | `#e3e4fc` | Main bar background color. |
667
+ | `--text-color-0` | `#333e4a` | Main text color. |
668
+ | `--white-color` | `#ffffff` | Pure white color. |
669
+ | `--grey-color` | `#b5b9be` | Disabled state color. |
670
+ | `--sign-font-family` | `Arial, sans-serif` | Global font family. |
671
+
672
+ #### Layout & Constraints
673
+
674
+ | Variable | Default | Description |
675
+ | :---------------------- | :---------- | :------------------------------------- |
676
+ | `--min-height` | `48px` | Minimum height for bars and buttons. |
677
+ | `--spacing-constraints` | `16px 24px` | Default padding/margin for containers. |
678
+
679
+ #### Top Bar
680
+
681
+ | Variable | Description |
682
+ | :-------------------------- | :------------------------------- |
683
+ | `--sign-top-bar-bg-base` | Background color of the top bar. |
684
+ | `--sign-top-bar-text-base` | Text color in the top bar. |
685
+ | `--sign-top-bar-padding` | Inner padding of the top bar. |
686
+ | `--sign-top-bar-min-height` | Minimum height of the top bar. |
687
+
688
+ #### Canvas & Signature Line
689
+
690
+ | Variable | Description |
691
+ | :---------------------------------- | :-------------------------------------------- |
692
+ | `--sign-canvas-bg-base` | Background color of the drawing area. |
693
+ | `--sign-line-height` | Vertical offset/height for the guide line. |
694
+ | `--sign-line-border-base` | Color of the signature guide line. |
695
+ | `--sign-line-additional-text-color` | Color of the helper text below the line. |
696
+ | `--sign-line-margin` | Spacing around the guide line. |
697
+ | `--sign-canvas-line-text-font-size` | Font size for guide line labels. |
698
+ | `--sign-canvas-height-offset` | Canvas offset calculation for the guide line. |
699
+
700
+ #### Bottom Bar
701
+
702
+ | Variable | Description |
703
+ | :----------------------------- | :--------------------------------------- |
704
+ | `--sign-bottom-bar-bg-base` | Background color of the bottom bar. |
705
+ | `--sign-bottom-bar-padding` | Inner padding of the bottom bar. |
706
+ | `--sign-bottom-bar-min-height` | Minimum height of the bottom bar. |
707
+ | `--sign-bottom-bar-gap` | Space between buttons in the bottom bar. |
708
+
709
+ #### Buttons (General)
710
+
711
+ | Variable | Default | Description |
712
+ | :------------------------- | :------------ | :------------------------------- |
713
+ | `--sign-button-font-size` | `12px - 16px` | Fluid font size for all buttons. |
714
+ | `--sign-button-padding` | `14px 16px` | Inner padding for all buttons. |
715
+ | `--sign-button-min-height` | `48px` | Minimum height for buttons. |
716
+
717
+ #### Primary Buttons (OK, Clear, Cancel)
718
+
719
+ | Variable | Description |
720
+ | :------------------------------------ | :----------------------------------- |
721
+ | `--sign-button-primary-bg-base` | Background color of primary buttons. |
722
+ | `--sign-button-primary-bg-hover` | Hover background color. |
723
+ | `--sign-button-primary-bg-disabled` | Disabled background color. |
724
+ | `--sign-button-primary-text-base` | Text color for primary buttons. |
725
+ | `--sign-button-primary-text-hover` | Hover text color. |
726
+ | `--sign-button-primary-text-disabled` | Disabled text color. |
727
+
728
+ #### Link/Connect Buttons
729
+
730
+ | Variable | Description |
731
+ | :-------------------------------- | :------------------------------------------- |
732
+ | `--sign-button-link-bg-base` | Background color for secondary/link buttons. |
733
+ | `--sign-button-link-text-base` | Text color for secondary/link buttons. |
734
+ | `--sign-button-link-border-base` | Border for secondary/link buttons. |
735
+ | `--sign-button-link-text-hover` | Hover text color. |
736
+ | `--sign-button-link-border-hover` | Hover border color. |
737
+
738
+ #### Status & Overlays
739
+
740
+ | Variable | Default | Description |
741
+ | :-------------------------------------------- | :---------- | :--------------------------------- |
742
+ | `--sign-device-state-text-color-connected` | `green` | Text color when device is ready. |
743
+ | `--sign-device-state-text-color-disconnected` | `red` | Text color when disconnected. |
744
+ | `--sign-loading-overlay-bg-color` | `rgba(...)` | Background of the loading spinner. |
745
+ | `--sign-loading-overlay-spinner-color` | `#4e56ea` | Color of the animated spinner. |
746
+ | `--sign-loading-overlay-spinner-size` | `30px` | Size of the spinner icon. |
747
+
748
+ ## 🤝 Feedback & Support
749
+
750
+ We are constantly working to improve our components and drivers. Your feedback is essential to us. Whether you found a bug, have a feature request, or need technical assistance, please reach out to us:
751
+
752
+ - 📧 **Support Email:** [esign@signosoft.com](mailto:esign@signosoft.com)
753
+ - 🌐 **Official Website:** [www.signosoft.com](https://www.signosoft.com)
754
+
755
+ ## 📄 License
756
+
757
+ **Proprietary Commercial License**
758
+
759
+ Copyright © 2026, Signosoft. All rights reserved.
760
+
761
+ This software is proprietary to Signosoft and is protected by copyright laws. It is **not open source**.
762
+
763
+ ### 🔐 Commercial Usage
764
+
765
+ A valid, paid, and active commercial license agreement with Signosoft is **strictly required** for the use, operation, reproduction, distribution, or deployment of this software in any environment (including development, testing, staging, and production).
766
+
767
+ ### 📜 Key Terms
768
+
769
+ - **Unauthorized Use:** Any use without a current, fully paid license is expressly prohibited and constitutes a violation of our intellectual property rights.
770
+ - **Legal Action:** Signosoft reserves the right to pursue legal action to enforce its rights and seek damages for unauthorized use.
771
+ - **Restrictions:** You may not reverse-engineer, decompile, or disassemble this software except as permitted by applicable law.
772
+
773
+ For information on how to obtain a valid commercial license, pricing, and support, please contact us at [esign@signosoft.com](mailto:esign@signosoft.com).
774
+
775
+ See the [LICENSE](LICENSE) file for the full legal text.