@signosoft/signpad-js 0.2.0 → 0.2.2

package/README.md

@@ -2,14 +2,14 @@
 
 ## 📍 Table of Contents
 
-| Core Concepts & Overview                  | Getting Started & Usage            | Advanced & Support            |
-| :---------------------------------------- | :--------------------------------- | :---------------------------- |
-| 📜 [Description](#-description)           | 📦 [Installation](#-installation)  |  🤝 [Feedback](#-feedback--support)|
-| 🎬 [Demo](#-demo)                         | 🔐 [Licensing](#-get-your-license) | 📄 [License](#-license)        |
-| ⚙️ [Tech stack](#-tech-stack--built-with) | 🚀 [Quick Start](#-quick-start)    |                               |
-|                                           | 📋 [Properties](#-properties)      |                               |
-|                                           | 🧩 [Methods](#-methods)            |                               |
-|                                           |  🎨 [Styling](#-styling--theming)     |                               |                           
+| Core Concepts & Overview                  | Getting Started & Usage            | Advanced & Support                 |
+| :---------------------------------------- | :--------------------------------- | :--------------------------------- |
+| 📜 [Description](#-description)           | 📦 [Installation](#-installation)  | 🤝 [Feedback](#-feedback--support) |
+| 🎬 [Demo](#-demo)                         | 🔐 [Licensing](#-get-your-license) | 📄 [License](#-license)            |
+| ⚙️ [Tech stack](#-tech-stack--built-with) | 🚀 [Quick Start](#-quick-start)    |                                    |
+|                                           | 📋 [Properties](#-properties)      |                                    |
+|                                           | 🧩 [Methods](#-methods)            |                                    |
+|                                           | 🎨 [Styling](#-styling--theming)   |                                    |
 
 ## 📜 Description
 
@@ -29,7 +29,7 @@ It expertly handles the complexities of **WebHID device connections**, signature
 
 ## 🎬 Demo
 
-<img src="./docsVideo.gif" alt="Signosoft Demo" width="500" />
+<img src="https://unpkg.com/@signosoft/signpad-js@latest/docsVideo.gif" alt="Signosoft Demo" width="500" />
 
 ## ⚙️ Tech Stack / Built With
 
@@ -104,15 +104,312 @@ First, install the core package:
 npm install your-library-name
 ```
 
-### Framework Integration Guide
+### 🧰 Framework Integration Guide
 
-Choose your framework to see the full setup guide:
-| Framework | Setup Guide | Status |
-| :--- | :--- | :--- |
-| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angularjs/angularjs-original.svg" alt="Angular" width="15" height="15"> **Angular** | [Docs →](./framework-docs/integration-angular.md) | <font color="green">**Live**</font> |
-| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React" width="15" height="15"> **React** | [Docs →](./framework-docs/integration-react.md) | <font color="green">**Live**</font> |
-| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vuejs/vuejs-original.svg" alt="Vue" width="15" height="15"> **Vue.js** | [Docs →](./framework-docs/integration-vue.md) | <font color="green">**Live**</font> |
-| <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/javascript/javascript-original.svg" alt="JS" width="15" height="15"> **Vanilla JS** | [Docs →](./framework-docs/integration-vanilla.md) | <font color="green">**Live**</font> |
+<details>
+<summary>
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angularjs/angularjs-original.svg" alt="Angular" width="15" height="15">
+  <b>Angular</b> <font color="green"><b>(Live)</b></font>
+</summary>
+<br>
+
+# <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/angular/angular-original.svg" alt="Angular" width="30" height="30"> Angular Integration Guide
+
+This guide describes how to integrate the `@signosoft/signpad-js` web component into an Angular application.
+
+## 1. Installation
+
+Install the core package using npm:
+
+```bash
+npm install @signosoft/signpad-js
+```
+
+## 2. Create the Bridge Directive
+
+Since `signosoft-signpad` is a Web Component, Angular requires a Directive to properly sync configuration changes and provide typed access to the component instance.
+
+Create `signosoft-signpad.directive.ts`:
+
+```typescript
+import {
+  Directive,
+  ElementRef,
+  Input,
+  OnChanges,
+  SimpleChanges,
+} from "@angular/core";
+import type { SignosoftSignpad, SignpadConfig } from "@signosoft/signpad-js";
+
+@Directive({
+  selector: "signosoft-signpad",
+  standalone: true,
+})
+export class SignosoftSignpadDirective implements OnChanges {
+  @Input() config?: SignpadConfig;
+
+  constructor(private host: ElementRef<SignosoftSignpad>) {}
+
+  // Access the native Web Component instance
+  get signpadRef(): SignosoftSignpad {
+    return this.host.nativeElement;
+  }
+
+  ngOnChanges(changes: SimpleChanges) {
+    const el = this.host.nativeElement as any;
+    for (const key of Object.keys(changes)) {
+      el[key] = (this as any)[key];
+    }
+  }
+}
+```
+
+## 3. Implementation in Component
+
+Import the library, the directive, and add the **`CUSTOM_ELEMENTS_SCHEMA`**.
+
+```typescript
+import { Component, ViewChild, CUSTOM_ELEMENTS_SCHEMA } from "@angular/core";
+import "@signosoft/signpad-js"; // Import the Web Component registration
+import {
+  type SignosoftSignpad,
+  type SignpadConfig,
+} from "@signosoft/signpad-js";
+import { SignosoftSignpadDirective } from "./directives/signosoft-signpad.directive";
+
+@Component({
+  selector: "app-root",
+  standalone: true,
+  imports: [SignosoftSignpadDirective],
+  templateUrl: "./app.component.html",
+  schemas: [CUSTOM_ELEMENTS_SCHEMA], // Mandatory for custom HTML tags
+})
+export class AppComponent {
+  @ViewChild(SignosoftSignpadDirective)
+  signpadDirective!: SignosoftSignpadDirective;
+
+  config: SignpadConfig = {
+    licenseKey: "YOUR-LICENSE-KEY",
+    // More info in "properties" section
+  };
+
+  // Helper to access methods easily (ok, clear, cancel, etc.)
+  public get signpad(): SignosoftSignpad | undefined {
+    return this.signpadDirective?.signpadRef;
+  }
+}
+```
+
+## 4. Component Template
+
+Use the custom tag in your HTML and bind the configuration object.
+
+```html
+<div>
+  <div>
+    <signosoft-signpad [config]="config"></signosoft-signpad>
+  </div>
+</div>
+```
+
+</details>
+
+<details>
+<summary>
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React" width="15" height="15">
+  <b>React</b> <font color="green"><b>(Live)</b></font>
+</summary>
+<br>
+
+# <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/react/react-original.svg" alt="React" width="30" height="30"> React - Quick start
+
+This guide describes how to integrate the `@signosoft/signpad-js` web component into a React application (Functional Components with Hooks).
+
+## 1. Installation
+
+Install the core package using npm:
+
+```bash
+npm install @signosoft/signpad-js
+```
+
+## 2. Implementation
+
+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.
+
+```tsx
+import { useRef } from "react";
+import "@signosoft/signpad-js"; // Registers the web component
+import type { SignpadConfig } from "@signosoft/signpad-js";
+
+function App() {
+  // Use ref to access component methods (ok, clear, connect, etc. by signpadRef.current)
+  const signpadRef = useRef<any>(null);
+
+  const config: SignpadConfig = {
+    licenseKey: "YOUR-LICENSE-KEY",
+    // More info in "properties" section
+  };
+
+  return (
+    <div>
+      <h1>Signosoft Signpad React Example</h1>
+      <signosoft-signpad ref={signpadRef} config={config} />
+    </div>
+  );
+}
+
+export default App;
+```
+
+</details>
+
+<details>
+<summary>
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vuejs/vuejs-original.svg" alt="Vue" width="15" height="15">
+  <b>Vue.js</b> <font color="green"><b>(Live)</b></font>
+</summary>
+<br>
+
+# <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vuejs/vuejs-original.svg" alt="Vue" width="30" height="30"> Vue.js Integration Guide
+
+This guide describes how to integrate the `@signosoft/signpad-js` web component into a Vue 3 application using the Composition API (`<script setup>`).
+
+## 1. Installation
+
+Install the core package using npm:
+
+```bash
+npm install @signosoft/signpad-js
+```
+
+## 2. Configure Vue to recognize Custom Elements
+
+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.
+
+**If you are using Vite (`vite.config.ts`):**
+
+```typescript
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+
+export default defineConfig({
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          // Treat all tags starting with 'signosoft-' as custom elements
+          isCustomElement: (tag) => tag.startsWith("signosoft-"),
+        },
+      },
+    }),
+  ],
+});
+```
+
+## 3. Implementation
+
+In Vue 3, we use `ref` to hold the reference to the DOM element and pass the configuration via the `:config` attribute.
+
+```typescript
+<script setup lang="ts">
+import { ref } from "vue";
+import "@signosoft/signpad-js"; // Registers the Web Component
+import type { SignpadConfig, SignosoftSignpad, IPenData } from "@signosoft/signpad-js";
+
+// Use ref to access component methods (ok, clear, connect, etc. by signpadRef.value)
+const signpadRef = ref<SignosoftSignpad | null>(null);
+
+const signpadConfig: SignpadConfig = {
+  licenseKey: "YOUR-LICENSE-KEY",
+  // More info in "properties" section
+};
+
+</script>
+
+<template>
+  <div>
+    <signosoft-signpad
+      ref="signpadRef"
+      :config="signpadConfig"
+    ></signosoft-signpad>
+  </div>
+</template>
+```
+
+</details>
+
+<details>
+<summary>
+  <img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/javascript/javascript-original.svg" alt="JS" width="15" height="15">
+  <b>Vanilla JS</b> <font color="green"><b>(Live)</b></font>
+</summary>
+<br>
+
+# 🍦 Vanilla JS Integration Guide
+
+This guide describes how to integrate the `@signosoft/signpad-js` web component into a plain JavaScript project without any frameworks.
+
+## 1. Installation
+
+Install the package via npm:
+
+```bash
+npm install @signosoft/signpad-js
+```
+
+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).
+
+## 2. JavaScript Implementation
+
+In Vanilla JS, you interact with the component by selecting it from the DOM and assigning the configuration directly to its `config` property.
+
+```javascript
+import "@signosoft/signpad-js";
+
+/**
+ * INTELLISENSE SUPPORT (Optional)
+ * Helps VS Code provide autocomplete for methods and properties.
+ * @type {import('@signosoft/signpad-js').SignosoftSignpad}
+ */
+const pad = document.querySelector("signosoft-signpad");
+
+// 1. Initial Configuration
+pad.config = {
+  licenseKey: "YOUR-LICENSE-KEY",
+};
+```
+
+## 3. HTML Structure
+
+Add the custom element tag to your HTML and create the necessary control buttons.
+
+```html
+<!-- index.html -->
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <title>Signosoft Signpad - Vanilla JS</title>
+  </head>
+  <body>
+    <h1>Signosoft Signpad</h1>
+    <!-- The Web Component -->
+    <signosoft-signpad id="my-signpad"></signosoft-signpad>
+    <!-- Main logic script -->
+    <script type="module" src="main.js"></script>
+  </body>
+</html>
+```
+
+## 4. Key Concepts
+
+- **Direct Property Assignment:** Unlike some frameworks that use attributes, in Plain JS you should assign the configuration directly: `element.config = { ... }`.
+- **Module System:** Ensure your `<script>` tag has `type="module"` to use the `import` statement.
+- **Methods:** All methods like `.connect()`, `.ok()`, and `.clear()` are available directly on the DOM element object.
+- **DOM Events:** The component dispatches standard DOM events (like `sign-ok`, `sign-clear`) which you can listen to using `addEventListener`.
+
+</details>
 
 ## 📋 Properties
 

package/dist/index.d.ts

@@ -95,7 +95,7 @@ declare class CanvasManager {
      * Handles coordinate normalization and pressure-based thickness.
      * @param penData - Data containing coordinates (0-1), pressure, and contact status.
      */
-    drawSegment(penData: IPenData): void;
+    drawSegment(penData: IPenData_2): void;
     /**
      * Wipes the canvas clean and resets the drawing state.
      */
@@ -193,7 +193,6 @@ declare class ConnectionManager {
     private penDataToDispatch;
     /** @private Minimum delay between pen events (approx 60fps) */
     private throttleDelayMs;
-    private fetchShimInstalled;
     /**
      * @param component - The host SignosoftSignpad instance.
      */
@@ -269,10 +268,6 @@ declare class ConnectionManager {
      * @returns Resolves when the driver is initialized.
      */
     private initializeTabletWithLicense;
-    /**
-     * Installs a fetch shim to resolve lib assets when bundled.
-     */
-    private installLibAsset;
     isFallback(deviceInfo: any | null, isDeviceConnected: boolean, includeDisconnected: boolean): boolean;
     /**
      * Normalizes device info to always include deviceName.
@@ -321,8 +316,8 @@ export declare interface IEventCallbacks {
         deviceInfo: any;
     }>) => void;
     onDisconnect?: (event: CustomEvent<void>) => void;
-    onPen?: (event: CustomEvent<PenData>) => void;
-    onOk?: (event: CustomEvent<void>) => void;
+    onPen?: (event: CustomEvent<IPenData_2>) => void;
+    onOk?: (event: CustomEvent<any>) => void;
     onClear?: (event: CustomEvent<void>) => void;
     onCancel?: (event: CustomEvent<void>) => void;
     onError?: (event: CustomEvent<Error>) => void;
@@ -334,7 +329,7 @@ export declare interface ILanguageOptions {
     translations?: ITranslationSet | Record<string, ITranslationSet>;
 }
 
-export declare type IPenData = {
+declare type IPenData_2 = {
     relativeX: number;
     relativeY: number;
     absoluteX?: number;
@@ -344,9 +339,10 @@ export declare type IPenData = {
     inContact: boolean;
     [key: string]: any;
 };
+export { IPenData_2 as IPenData }
 
 export declare interface IPenDataCallback {
-    (penData: PenData): void;
+    (penData: IPenData_2): void;
 }
 
 export declare interface ITranslationSet {