signature.digital/catalog
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(catalog): add ContractEditor and many editor subcomponents; implement SignPad and SignBox; update README and bump dependencies

Browse Source
This commit is contained in:
Jürgen Kunz
2025-12-18 15:27:22 +00:00
parent 6d53259b75
commit 56c087bc3a
35 changed files with 10914 additions and 1959 deletions
Download Patch File Download Diff File Expand all files Collapse all files

250
readme.md
View File

@@ -1,164 +1,176 @@
# @signature.digital/catalog
A catalog containing components for e-signing, built using modern web technologies for seamless integration and functionality.
A comprehensive catalog of customizable web components designed for building and managing e-signature applications. Built with modern web technologies using LitElement and TypeScript.
## Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
## Install
To add `@signature.digital/catalog` to your project, run the following command in your terminal:
```shell
npm install @signature.digital/catalog
# or
pnpm 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).
## 🎯 Overview
## Usage
This package provides three main components for e-signature workflows:
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`.
| Component | Tag | Description |
|-----------|-----|-------------|
| **SignPad** | `<sdig-signpad>` | Canvas-based signature capture pad |
| **SignBox** | `<sdig-signbox>` | Complete signing interface with controls |
| **ContractEditor** | `<sdig-contracteditor>` | Contract document management component |
### Setting Up the Environment
## 📦 Usage
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:
### Basic Import
```typescript
import '@signature.digital/catalog/element';
class MySignatureComponent extends HTMLElement {
connectedCallback() {
this.innerHTML = '<sdig-signpad></sdig-signpad>';
}
}
customElements.define('my-signature-component', MySignatureComponent);
import '@signature.digital/catalog';
```
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.
This registers all custom elements and makes them available for use in your HTML.
### Advanced Usage with `SignBox`
### SignPad Component
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.
The `<sdig-signpad>` is a canvas-based signature capture component that allows users to draw their signatures directly in the browser.
```typescript
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);
```html
<sdig-signpad></sdig-signpad>
```
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.
**API Methods:**
```typescript
import '@signature.digital/catalog/element';
import { IPortableContract } from '@signature.digital/tools/interfaces';
const signpad = document.querySelector('sdig-signpad');
class MyContractEditor extends HTMLElement {
editContract(contract: IPortableContract) {
const editor = this.querySelector('sdig-contracteditor');
editor.contract = contract;
}
connectedCallback() {
this.innerHTML = `<sdig-contracteditor></sdig-contracteditor>`;
}
}
// Get signature data as point arrays
const data = await signpad.toData();
customElements.define('my-contract-editor', MyContractEditor);
// Load signature from data
await signpad.fromData(data);
// Export signature as SVG string
const svg = await signpad.toSVG();
// Undo last stroke
await signpad.undo();
// Clear the signature pad
await signpad.clear();
```
`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.
### SignBox Component
### Example Application
The `<sdig-signbox>` wraps `SignPad` with a complete UI including Clear, Undo, and Submit buttons.
Below is an integrated example showing how all of these components can be put together to form a basic signature application.
```typescript
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);
```html
<sdig-signbox></sdig-signbox>
```
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:
**Events:**
```typescript
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
const signbox = document.querySelector('sdig-signbox');
await signaturePad.undo(); // Undo last action
await signaturePad.clear(); // Clear the signature pad
signbox.addEventListener('signature', (event) => {
const signatureData = event.detail.signature;
console.log('Signature captured:', signatureData);
});
```
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.
### ContractEditor Component
### 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:
The `<sdig-contracteditor>` provides contract viewing and editing capabilities using the `IPortableContract` interface from `@signature.digital/tools`.
```typescript
const style = document.createElement('style');
style.textContent = `
sdig-signpad, sdig-signbox {
--main-background-color: #fff;
--line-color: #000;
--button-color: #007bff;
}
`;
import '@signature.digital/catalog';
import { IPortableContract } from '@signature.digital/tools/interfaces';
import { demoContract } from '@signature.digital/tools/demodata';
document.head.appendChild(style);
const editor = document.querySelector('sdig-contracteditor');
editor.contract = demoContract;
```
These CSS custom properties modify component styles, from appearance to behavior, creating a cohesive look with the rest of your site's aesthetics.
## 🔧 Integration Example
### Conclusion
Here's a complete example showing all components working together:
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
```typescript
import '@signature.digital/catalog';
import { LitElement, html, css } from 'lit';
import { customElement } from 'lit/decorators.js';
@customElement('my-signature-app')
class MySignatureApp extends LitElement {
static styles = css`
:host {
display: block;
max-width: 800px;
margin: 0 auto;
}
`;
render() {
return html`
<h2>Please sign below</h2>
<sdig-signbox @signature=${this.handleSignature}></sdig-signbox>
`;
}
private handleSignature(e: CustomEvent) {
console.log('Signature submitted:', e.detail.signature);
// Process or store the signature
}
}
```
## 🎨 Theming
Components support automatic light/dark theme detection and can be customized using CSS custom properties:
```css
sdig-signpad, sdig-signbox {
--main-background-color: #ffffff;
--line-color: #000000;
--button-color: #007bff;
}
```
The components use `cssManager.bdTheme()` for automatic theme switching based on system preferences.
## 📋 Requirements
- Modern browser with Custom Elements V1 support
- ECMAScript Modules (ESM) compatible environment
- TypeScript 5.0+ (for development)
## 🔗 Dependencies
- `@design.estate/dees-element` - LitElement-based component framework
- `@signature.digital/tools` - Contract interfaces and demo data
- `signature_pad` - Canvas signature capture library
## License and Legal Information
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
### Trademarks
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
### Company Information
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
For any legal inquiries or further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.