npm package: @ngx-zone/signature-pad
Description: A lightweight, reusable Angular signature pad component with canvas-based drawing
Author: ngx-zone
Latest version: 1.1.0

# @ngx-zone/signature-pad

A lightweight, reusable Angular signature pad component for capturing signatures using HTML5 Canvas.

## Features

- Canvas-based drawing with pointer events
- Pressure-sensitive drawing (where supported)
- Smooth drawing with quadratic curves
- Configurable pen size and smoothing
- Optional undo and clear buttons
- Flexible sizing (adapts to parent container)
- Responsive canvas that scales to parent container
- Touch, mouse, and stylus support
- Programmatic access to signature data
- Standalone component (no module required)

## Installation

```bash
npm install @ngx-zone/signature-pad
```

## Usage

### Basic Usage (No Buttons)

```typescript
import { Component } from '@angular/core';
import { SignaturePadComponent } from '@ngx-zone/signature-pad';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [SignaturePadComponent],
  template: `
    <div style="width: 500px;">
      <label>Signature</label>
      <ngx-signature-pad
        [showUndoButton]="false"
        [showClearButton]="false"
      ></ngx-signature-pad>
    </div>
  `
})
export class ExampleComponent {}
```

### With Buttons

```typescript
@Component({
  selector: 'app-example',
  standalone: true,
  imports: [SignaturePadComponent],
  template: `
    <ngx-signature-pad
      [showUndoButton]="true"
      [showClearButton]="true"
    ></ngx-signature-pad>
  `
})
export class ExampleComponent {}
```

### Custom Configuration

```typescript
@Component({
  selector: 'app-example',
  standalone: true,
  imports: [SignaturePadComponent],
  template: `
    <ngx-signature-pad
      [penColor]="'#0f172a'"
      [backgroundColor]="'#ffffff'"
      [penSize]="3"
      [smoothing]="true"
      [height]="300"
      [minWidth]="0.5"
      [maxWidth]="2.5"
      [showUndoButton]="true"
      [showClearButton]="true"
    ></ngx-signature-pad>
  `
})
export class ExampleComponent {}
```

### Accessing Signature Data

```typescript
import { Component, ViewChild } from '@angular/core';
import { SignaturePadComponent } from '@ngx-zone/signature-pad';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [SignaturePadComponent],
  template: `
    <ngx-signature-pad></ngx-signature-pad>
    <button (click)="getSignature()">Get Signature</button>
  `
})
export class ExampleComponent {
  @ViewChild(SignaturePadComponent) signaturePad!: SignaturePadComponent;

  async getSignature() {
    // Get as Data URL
    const dataUrl = this.signaturePad.getSignatureDataURL();
    console.log('Data URL:', dataUrl);

    // Get as Blob
    const blob = await this.signaturePad.getSignatureBlob();
    console.log('Blob:', blob);

    // Programmatically clear
    this.signaturePad.clear();

    // Programmatically undo
    this.signaturePad.undo();
  }
}
```

## Component API

### Inputs

| Input | Type | Default | Description |
|-------|------|---------|-------------|
| `penColor` | string | `'#000'` | The color of the pen stroke |
| `backgroundColor` | string | `'transparent'` | The background color of the canvas |
| `penSize` | number | `10` | Base pen size (affected by pressure) |
| `smoothing` | boolean | `true` | Enable smooth curves for drawing |
| `minWidth` | number | `0.5` | Minimum stroke width |
| `maxWidth` | number | `2.5` | Maximum stroke width |
| `height` | number | `400` | Canvas height in pixels |
| `showUndoButton` | boolean | `true` | Show/hide undo button |
| `showClearButton` | boolean | `true` | Show/hide clear button |
| `canvasBackgroundColor` | string | undefined | Canvas background color (overrides CSS variable) |
| `buttonBackgroundColor` | string | undefined | Button background color (overrides CSS variable) |
| `buttonTextColor` | string | undefined | Button text color (overrides CSS variable) |
| `buttonBorderColor` | string | undefined | Button border color (overrides CSS variable) |
| `buttonHoverColor` | string | undefined | Button hover background color (overrides CSS variable) |
| `buttonDisabledColor` | string | undefined | Button disabled text color (overrides CSS variable) |
| `buttonFocusColor` | string | undefined | Button focus outline color (overrides CSS variable) |
| `iconColor` | string | undefined | Icon color (overrides CSS variable) |

### Public Methods

| Method | Return Type | Description |
|--------|-------------|-------------|
| `undo()` | void | Removes the last stroke |
| `clear()` | void | Clears all strokes from the canvas |
| `savePNG()` | void | Downloads the signature as a PNG file |
| `getSignatureDataURL()` | string | Returns the signature as a base64 data URL |
| `getSignatureBlob()` | Promise<Blob \| null> | Returns the signature as a Blob |

## Theming

The component supports dynamic theming through two approaches:

### 1. CSS Variables (Recommended for global themes)

Define these CSS variables in your global styles (e.g., `styles.scss`) to theme all signature pads:

```scss
:root {
  --ngx-sig-canvas-bg: #ffffff;
  --ngx-sig-button-bg: #ffffff;
  --ngx-sig-button-text: #334155;
  --ngx-sig-button-border: #cbd5e1;
  --ngx-sig-button-hover: #f1f5f9;
  --ngx-sig-button-disabled: #94a3b8;
  --ngx-sig-button-focus: #334155;
  --ngx-sig-icon: #334155;
  --ngx-sig-shadow-rgb: 0, 0, 0;
}
```

**Example with Fuse Theme:**
```scss
:root {
  --ngx-sig-canvas-bg: var(--fuse-bg-card);
  --ngx-sig-button-bg: var(--fuse-bg-card);
  --ngx-sig-button-text: var(--fuse-text-default);
  --ngx-sig-button-border: var(--fuse-border);
  --ngx-sig-button-hover: var(--fuse-bg-hover);
  --ngx-sig-button-disabled: var(--fuse-text-disabled);
  --ngx-sig-button-focus: var(--fuse-primary);
  --ngx-sig-icon: var(--fuse-icon);
  --ngx-sig-shadow-rgb: var(--fuse-text-default-rgb);
}
```

**Example with Material Theme:**
```scss
:root {
  --ngx-sig-canvas-bg: var(--mat-app-surface);
  --ngx-sig-button-bg: var(--mat-app-surface);
  --ngx-sig-button-text: var(--mat-app-on-surface);
  --ngx-sig-button-border: var(--mat-app-outline);
  --ngx-sig-button-hover: var(--mat-app-surface-container);
  --ngx-sig-button-disabled: var(--mat-app-on-surface-variant);
  --ngx-sig-button-focus: var(--mat-app-primary);
  --ngx-sig-icon: var(--mat-app-on-surface-variant);
  --ngx-sig-shadow-rgb: 0, 0, 0;
}
```

### 2. Input Properties (For component-specific customization)

Use Input properties to override colors for specific instances:

```typescript
<ngx-signature-pad
  [canvasBackgroundColor]="'#f0f0f0'"
  [buttonBackgroundColor]="'#4f46e5'"
  [buttonTextColor]="'#ffffff'"
  [buttonBorderColor]="'#4338ca'"
  [buttonHoverColor]="'#4338ca'"
  [iconColor]="'#ffffff'">
</ngx-signature-pad>
```

**Priority:**
1. Input properties (highest priority)
2. CSS variables
3. No fallback - you must define the variables

## Use Cases

### 1. Simple Form Integration

```typescript
<div class="form-group" style="width: 600px;">
  <ngx-signature-pad
    [showUndoButton]="false"
    [showClearButton]="false"
    [height]="250"
  ></ngx-signature-pad>
  <button (click)="saveSignature()">Save</button>
</div>
```

### 2. Modal/Dialog Usage

```typescript
<div class="modal">
  <h3>Please sign below</h3>
  <ngx-signature-pad
    [height]="300"
    [showUndoButton]="true"
    [showClearButton]="true"
  ></ngx-signature-pad>
  <button (click)="submitSignature()">Submit</button>
</div>
```

### 3. Custom Size Container

```typescript
<div style="width: 800px; max-width: 100%;">
  <ngx-signature-pad
    [height]="500"
    [penSize]="4"
  ></ngx-signature-pad>
</div>
```

## Styling

The component adapts to its parent container width. Set a width on the parent element to control the signature pad size:

```html
<div style="width: 600px;">
  <ngx-signature-pad></ngx-signature-pad>
</div>
```

You can also customize the appearance using CSS variables or by overriding the component styles.

## Browser Support

- Modern browsers with Canvas API support
- Pointer Events API support
- ResizeObserver API support

## Notes

- The canvas automatically scales to fit its parent container
- The component maintains signature quality during resize
- Touch action is disabled to prevent scrolling while drawing
- The component is standalone and can be used without a module

## Building

To build the library, run:

```bash
ng build signature-pad
```

## Publishing

1. Build the library:
   ```bash
   ng build signature-pad
   ```

2. Navigate to the dist directory:
   ```bash
   cd dist/signature-pad
   ```

3. Publish to npm:
   ```bash
   npm publish
   ```

## License

MIT