catalog/readme.md

@signature.digital/catalog

A catalog containing components for e-signing, built using modern web technologies for seamless integration and functionality.

Install

To add @signature.digital/catalog to your project, run the following command in your terminal:

npm install @signature.digital/catalog

This command will install @signature.digital/catalog along with its required peer dependencies. Ensure that your project is set up for ECMAScript Modules (ESM).

Usage

The @signature.digital/catalog package provides a set of web components specifically designed for building e-signature applications. These components can be used for capturing, displaying, and managing electronic signatures. The primary components offered in this package include SignPad, SignBox, and ContractEditor.

Setting Up the Environment

To make the most of @signature.digital/catalog, you'll want to ensure you have your environment ready to use web components. If you're using a standard web setup with a module bundler like Webpack, Rollup, or Vite, make sure your build process supports ECMAScript modules.

Basic Example of SignPad

The SignPad component is a customizable signature pad that can be used to capture user signatures. Here's how to implement it in your HTML:

import '@signature.digital/catalog/element';

class MySignatureComponent extends HTMLElement {
  connectedCallback() {
    this.innerHTML = '<sdig-signpad></sdig-signpad>';
  }
}

customElements.define('my-signature-component', MySignatureComponent);

In this example, a simple HTML element is constructed that includes the sdig-signpad custom element. This signature pad allows users to draw their signatures directly in the browser.

Advanced Usage with SignBox

The SignBox component wraps SignPad with additional controls for signing actions like clear and undo. This provides a complete signing interface out of the box.

import '@signature.digital/catalog/element';

class MyCompleteSignatureBox extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `<sdig-signbox></sdig-signbox>`;
    this.querySelector('sdig-signbox').addEventListener('signature', (e) => {
      const signatureData = e.detail.signature;
      console.log('Signature data:', signatureData);
    });
  }
}

customElements.define('my-complete-signature-box', MyCompleteSignatureBox);

In this setup, SignBox also manages the signature data and emits a custom event once the signature is submitted. You can listen for this event to gather the signature data for storage or further processing.

Integrating ContractEditor

ContractEditor allows for manipulating contract details and integrating signature capabilities directly into documents. This component communicates with its state using Smartstate, an inbuilt state management system.

import '@signature.digital/catalog/element';
import { IPortableContract } from '@signature.digital/tools/interfaces';

class MyContractEditor extends HTMLElement {
  editContract(contract: IPortableContract) {
    const editor = this.querySelector('sdig-contracteditor');
    editor.contract = contract;
  }
  
  connectedCallback() {
    this.innerHTML = `<sdig-contracteditor></sdig-contracteditor>`;
  }
}

customElements.define('my-contract-editor', MyContractEditor);

ContractEditor can be dynamically updated by changing the contract property. This component expects contract definitions compatible with the IPortableContract interface, offering an adaptable and customizable editing solution.

Example Application

Below is an integrated example showing how all of these components can be put together to form a basic signature application.

import '@signature.digital/catalog/element';
import { IPortableContract } from '@signature.digital/tools/interfaces';
import { demoContract } from '@signature.digital/tools/demodata';

class CombinedSignatureApp extends HTMLElement {

  private contract: IPortableContract = demoContract;

  constructor() {
    super();
  }

  render() {
    this.innerHTML = `
      <my-complete-signature-box></my-complete-signature-box>
      <my-contract-editor></my-contract-editor>
    `;
    this.querySelector('my-contract-editor').editContract(this.contract);
  }
  
  connectedCallback() {
    this.render();
  }
}

customElements.define('combined-signature-app', CombinedSignatureApp);

In a real-world scenario, CombinedSignatureApp could be binding multiple processes around collecting and displaying signatures, including validation logic, storage mechanisms, and user feedback systems.

Handling Signatures

Once you have a user signature, you can convert it between different formats like Data, SVG or simply clear or undo modifications. Here is how you can handle these activities within your JavaScript:

document.querySelector('sdig-signpad').addEventListener('signature', async (event) => {
  const signaturePad = event.target as SignPad;
  
  console.log(await signaturePad.toData()); // Get signature data
  console.log(await signaturePad.toSVG());  // Convert to SVG

  await signaturePad.undo(); // Undo last action
  await signaturePad.clear(); // Clear the signature pad
});

This versatile use of sdig-signpad demonstrates how diverse use case scenarios for signatures can be developed, be it collecting, transforming, or editing current user inputs.

Responsive Design Considerations

When building applications that include e-signature capabilities, you must ensure your components respond well to different screen sizes. Components in @signature.digital/catalog are designed with CSS variables and flexible dimensions, but specific implementations can benefit from additional CSS media queries.

Custom Styling

Each component is styled using Light DOM scoped styles. Components like sdig-signpad come with default styles, but they are capable of overriding these styles for consistent design alignment within your project. For example:

const style = document.createElement('style');
style.textContent = `
  sdig-signpad, sdig-signbox {
    --main-background-color: #fff;
    --line-color: #000;
    --button-color: #007bff;
  }
`;

document.head.appendChild(style);

These CSS custom properties modify component styles, from appearance to behavior, creating a cohesive look with the rest of your site's aesthetics.

Conclusion

With @signature.digital/catalog, developers have a comprehensive toolkit for integrating sophisticated e-signature functionalities into their web applications. Its wide array of customizable components, flexibility, and ease of use out of the box makes it an indispensable inclusion for building modern digital signature workflows. Whether for simple signature capture or complex contract management, this package has you covered. Explore more advanced topics and extend the capabilities to fit unique business needs in your applications. undefined