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

fix(build): Update TypeScript config and build tooling; use accessor for Lit properties; bump deps and adjust package metadata

Browse Source
This commit is contained in:
Jürgen Kunz
2025-11-30 21:22:51 +00:00
parent 2184d8be18
commit 1e74560aca
9 changed files with 1508 additions and 987 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
readme.md
View File

@@ -1,138 +1,207 @@
# @consent.software_private/catalog
# @consent.software/catalog
Webcomponents for consent.software widget.
A sleek, modern library of web components for seamless consent management integration. Built with Lit and designed for GDPR/CCPA compliance out of the box.
## Install
## Issue Reporting and Security
To install this module, you need to have [Node.js](https://nodejs.org/) and [npm](https://www.npmjs.com/) installed on your machine. You can then run the following command in your terminal to add the module to your project:
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.
```shell
npm install @consent.software_private/catalog
## Features
🍪 **Cookie Consent Modal** - Beautiful, responsive consent dialog with light/dark theme support
🎛️ **Interactive Toggles** - Draggable toggle switches with smooth animations
📱 **Mobile-First Design** - Fully responsive across all device sizes
🎨 **Theme-Aware** - Automatically detects system light/dark mode preference
🔒 **Privacy-First** - Integrates with consent.software backend for compliant consent tracking
⚡ **Zero Config** - Drop-in components that just work
## Installation
```bash
npm install @consent.software/catalog
# or
pnpm add @consent.software/catalog
```
Ensure you have ESM support enabled in your TypeScript configuration, as this package uses ES module syntax.
## Quick Start
## Usage
The `@consent.software_private/catalog` module offers a set of web components to integrate consent management capabilities into your web application. These components leverage modern browser APIs and employ a system for cookie management that aligns with regulatory requirements.
### Initial Setup
First, import the necessary modules and set up your project to use the web components provided:
Import the components and add the consent banner to your page:
```typescript
import '@consent.software_private/catalog';
import '@consent.software/catalog';
// That's it! Add the component to your HTML
```
Ensure this import statement is included in your main JavaScript/TypeScript file where you want to utilize the consent management web components. It is vital to transpile with TypeScript compiler settings that support ES modules.
### Building a Consent Modal
A primary feature of this module is the `consentsoftware-cookieconsent` component. This component can be embedded into your application to allow users to select their preferred cookie levels.
#### Setting Up the Environment
Before creating instances of the components, make sure your project environment is ready. Setup the DOM tools and any associated dependencies:
```typescript
import { domtools } from '@design.estate/dees-domtools';
domtools.elementBasic.setup();
```html
<consentsoftware-cookieconsent></consentsoftware-cookieconsent>
```
#### Using the Consentsoftware-Cookieconsent Component
The consent banner automatically:
- Shows on first visit when no consent preferences are stored
- Hides after user makes a selection
- Respects system dark/light mode
- Stores preferences via the consent.software backend
Here's how you can include the `consentsoftware-cookieconsent` component in your application:
## Components
```typescript
import { html, render } from 'lit-html';
### `<consentsoftware-cookieconsent>`
const template = html`
<consentsoftware-cookieconsent></consentsoftware-cookieconsent>
`;
The main consent modal component. Provides a full-screen overlay with cookie preference options.
render(template, document.body);
```html
<consentsoftware-cookieconsent></consentsoftware-cookieconsent>
```
This will add the consent banner to the bottom of the page, providing users options to set their preferences.
**Features:**
- Three-button interface: Deny, Accept Selection, Accept All
- Four cookie categories: Required, Preferences, Statistics, Marketing
- Animated modal with backdrop blur
- Shake feedback when clicking outside the modal
- Automatic theme detection (light/dark)
#### Customizing the Component
### `<consentsoftware-toggle>`
The `consentsoftware-cookieconsent` component allows you to customize its design via CSS properties. Leverage light and dark themes through the CSS manager used in styling attributes:
A draggable toggle switch component with touch support.
```typescript
const styles = `
:host {
--cookieconsent-height: 70px;
--cookieconsent-background: #222;
--cookieconsent-text-color: #fff;
}
`;
```html
<consentsoftware-toggle>Label Text</consentsoftware-toggle>
<consentsoftware-toggle required>Required</consentsoftware-toggle>
```
Apply these custom styles to modify the appearance to match your site's design language.
**Properties:**
- `required` (boolean) - When true, toggle is locked in the "on" position
- `selected` (boolean) - Current toggle state
#### Handling User Interactions
**Events:**
- `toggle` - Fired when state changes, includes `{ selected: boolean }` in detail
The component is interactive, responding to user actions to set cookie levels. Here’s how the interaction flow works:
### `<consentsoftware-tabs>`
1. **User Interaction**: Users click one of the consent buttons (e.g., "Functional Cookies").
2. **Handling Consent Levels**: The component's `setLevel` method is invoked, updating the user's cookie preferences, e.g.:
Tab navigation component with animated indicator.
```html
<consentsoftware-tabs></consentsoftware-tabs>
```
Displays three tabs: Consent, Details, and Cookie Policy.
### `<consentsoftware-header>`
Simple header component for the consent modal.
```html
<consentsoftware-header></consentsoftware-header>
```
### `<consentsoftware-mainselection>`
Grid layout containing toggle switches for each cookie category.
```html
<consentsoftware-mainselection></consentsoftware-mainselection>
```
## Backend Integration
This catalog integrates with the `@consent.software/webclient` package for backend communication:
```typescript
private async setLevel(event: MouseEvent, levelsArg: Array<TCookieLevel>) {
await this.csWebclientInstance.setCookieLevels(levelsArg);
// Adjust styling and visibility
this.setAttribute('gotIt', 'true');
await delayFor(300);
this.setAttribute('show', 'false');
// Update other business logic based on consent levels
import { CsWebclient } from '@consent.software/webclient';
const client = new CsWebclient();
// Check current consent levels
const levels = await client.getCookieLevels();
if (!levels) {
// Show consent dialog
}
// Set consent levels programmatically
await client.setCookieLevels(['functional', 'analytics']);
// Run consent-dependent scripts
await client.getAndRunConsentTuples();
```
## Styling & Theming
The components use CSS custom properties for easy theming:
```css
consentsoftware-cookieconsent {
/* Text and colors */
--text-color: #333;
--background-color: #eeeeee;
--accent-color: #333333;
/* Buttons */
--button-bg: #ffffff;
--button-hover-bg: #f2f2f2;
/* Links */
--link-color: #333;
--icon-color: #4496f5;
/* Modal */
--modal-box-shadow: 0px 0px 8px rgba(0, 0, 0, 0.2);
--info-bg: rgba(0, 0, 0, 0.1);
--info-text: rgba(0, 0, 0, 0.5);
}
```
The system remembers user choices using a backend managed by the `consent.software` infrastructure.
The component automatically switches to dark theme variables when `theme="dark"` is set or when the system prefers dark mode.
### Integrating with Your Backend
## Cookie Levels
For full functionality, the component interacts with a backend to manage user consent states. Using `@consent.software/webclient`, you can query the user's current consent levels, perform updates, and verify whether consent has been previously granted:
The consent system uses three user-selectable levels plus a required baseline:
```typescript
const webclientInstance = new CsWebclient();
const cookieLevels = await webclientInstance.getCookieLevels();
| Level | Description |
|-------|-------------|
| `functional` | Required cookies for site operation (always enabled) |
| `preferences` | User preference cookies |
| `analytics` | Statistics and analytics tracking |
| `marketing` | Marketing and advertising cookies |
if (!cookieLevels) {
// Show consent dialog if no consent levels are set
document.querySelector('consentsoftware-cookieconsent').show = true;
} else {
// Apply the consent settings to your analytics, advertisements, etc.
applyConsentSettings(cookieLevels);
}
## Browser Support
- Chrome (last 2 versions)
- Firefox (last 2 versions)
- Safari (last 2 versions)
- Edge (last 2 versions)
Built with modern ES modules and requires browsers with native Custom Elements v1 support.
## Development
```bash
# Install dependencies
pnpm install
# Build the project
pnpm run build
# Watch mode for development
pnpm run watch
```
### Advanced Considerations
## License and Legal Information
#### Responsive Design
This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [LICENSE](./LICENSE) file.
The component is responsive, optimized for various screen sizes using a grid layout. Ensure your main HTML elements are responsive to accommodate the consent bar.
**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.
#### Accessibility and Compliance
### Trademarks
Ensure your application properly adheres to legal and accessibility standards by aligning with the consent management system's features. This often involves using correct semantics, polyfills for custom elements, and thorough testing on different devices and browsers.
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.
#### Managing State Across Sessions
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.
Store user's consent preferences beyond the session using either localStorage, cookies, or server-side sessions. Adjust the component’s connectedCallback and updated lifecycle methods to fetch and apply these stored settings.
### Company Information
Proper handling ensures a seamless user experience, helping companies comply with international privacy laws like GDPR.
Task Venture Capital GmbH
Registered at District Court Bremen HRB 35230 HB, Germany
### Integration and Testing
For any legal inquiries or further information, please contact us via email at hello@task.vc.
Test extensively in your development environment, ensure correct rendering, and simulate various user interactions to gain confidence in production-level functionality. Automated testing might include:
- Unit tests for lifecycle behavior using testing libraries such as Mocha or Jest.
- Integration trials ensuring the component plays well with surrounding UI elements.
### Conclusion
With these guidelines, developers can integrate, customize, and extend the consent management capabilities within their applications using `@consent.software_private/catalog`. Adapt the styling, maximize UX, and ensure regulatory compliance for a robust implementation. Mastery of the component enables seamless user consent handling and enhances your app's governance credentials.
undefined
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.