Push Sign Up Form

A web component library providing a customisable, multi-step newsletter sign-up form for progressive data collection. Built with Lit and standard Web APIs, this library offers a fast, reusable, and framework-agnostic solution for newsletter subscriptions with support for multiple CRM systems (IFB and ViceVersa) and communication channels (Email and SMS).

Overview

The Push Sign Up Form library provides a single web component (pu-multistep-form) that orchestrates a multi-step form flow:

• Primary Form: Collects contact information (email/phone), country, and primary artist opt-in with channel selection (Email, SMS, or Both)
• Opt-ins Form: Allows users to subscribe to additional artist mailing lists with granular channel selection
• Supplementary Form: Collects optional profile data (name, date of birth, address)

The component supports progressive submission, session management, validation, and integration with reCAPTCHA for security. It's designed to work seamlessly with IFB and ViceVersa CRM systems and can be fully customised through a JSON configuration schema.

Who is this for?

• Frontend developers building newsletter sign-up experiences
• CMS/WordPress developers integrating subscription forms
• Designers who need customisable, accessible form components
• Teams requiring CRM integration (IFB or ViceVersa) with multi-step progressive data collection

Technologies

This library is built using modern web standards and technologies:

• Lit 3 - A lightweight framework for building fast, reactive web components
• TypeScript - Type-safe development with decorators and modern JavaScript features
• Push Web Components - Base component library for form inputs, buttons, and UI primitives
• Storybook - Component development environment and documentation
• Rollup - Module bundling for ESM and standalone builds
• Vite - Development server and build tooling

The library leverages standard Web APIs (Custom Elements, Shadow DOM, ES Modules) and requires no proprietary frameworks, making it compatible with any modern web application.

Installation

Prerequisites

• Node.js v20.0 or higher
• PNPM package manager

Install Node.js

Choose one of the following methods:

• Mac: NVM
• Windows: NVM for Windows
• Direct download: Node.js

Install PNPM

• Mac: brew install pnpm
• Windows PowerShell: iwr https://get.pnpm.io/install.ps1 -useb | iex

For more details, see the PNPM documentation.

Clone and Setup

1. Clone the repository:

   git clone [email protected]:Push-Entertainment/push-sign-up-form.git

2. Install dependencies:

   pnpm install

Local Development

Development Scripts

The project uses a pnpm workspace structure. Run these commands from the root directory:

Storybook Development:

• pnpm core:serve - Start Storybook dev server (port 6009)
• pnpm core:serve:https - Start Storybook with HTTPS (required for reCAPTCHA testing)

Config Builder Tool:

• The config builder runs on a separate Vite dev server (port 5174) via pnpm -F ./packages/sign-up-form-components run serve:config-builder

Build Scripts:

• pnpm core:build:esm - Build ESM module output
• pnpm core:build:standalone - Build standalone bundle
• pnpm core:build:all - Build both ESM and standalone
• pnpm core:build:docs - Build Storybook static site

IDE Setup

This project is optimized for VSCode with the following recommended extensions:

1. ESLint
2. lit-plugin
3. lit-html
4. MDX

Importing for Use in Applications

The library is published as ES modules and can be imported directly into your application.

Package Import

import '@pushengineering/push-sign-up-form';

HTML Usage

<script type="module">
  import '@pushengineering/push-sign-up-form';
</script>

<pu-multistep-form .config="${formConfig}"></pu-multistep-form>

Component Tag

The main component is registered as <pu-multistep-form>. It accepts a config property containing the form configuration object.

Configuration

The component requires a SignUpFormConfig object that defines:

• CRM System: "ifb" or "viceversa"
• Territory: "us", "uk", "nz", "au", or "jp"
• Form Steps: Configuration for primary, opt-ins, and supplementary forms
• Appearance: Color scheme, styling, header/footer, background images
• Copy/Labels: All user-facing text
• Security: reCAPTCHA configuration
• Legal Terms: Email/SMS terms and CASL compliance

See the JSON Schema for the complete configuration structure, or use the Config Builder tool to generate configurations visually.

Example

import '@pushengineering/push-sign-up-form';
import type { SignUpFormConfig } from '@pushengineering/push-sign-up-form';

const config: SignUpFormConfig = {
  id: 'my-form',
  name: 'Newsletter Sign Up',
  crm: 'ifb',
  territory: 'us',
  primaryForm: {
    enabled: true,
    primaryOptins: {
      email: { id: 'email-optin', name: 'Email', code: 'MAIN-LIST' },
      sms: { id: 'sms-optin', name: 'SMS', code: 'MAIN-LIST-SMS' }
    },
    deliveryChannels: 'email,sms,both',
    channelPriority: 'email',
    showAdditionalChannelLink: true
  },
  // ... additional configuration
};

document.querySelector('pu-multistep-form').config = config;

Storybook Documentation

Storybook provides interactive component previews, documentation, and examples. Access it by running:

pnpm core:serve

Then open http://localhost:6009 in your browser.

Storybook includes:

• Component Stories: Live, interactive previews with different configurations
• Documentation: Usage examples and API reference
• Design Tokens: Visual documentation of available CSS custom properties
• Test Configurations: Pre-built configs for different CRM systems and territories

Learn More

• MDN Web Components Guide - Learn about web component standards
• Lit Documentation - Framework documentation for Lit 3
• Project Documentation - Technical architecture and implementation details

Theme Styling

Design Tokens

Components use CSS custom properties (design tokens) for theming. Override these tokens in your application's stylesheet to customize the appearance:

pu-multistep-form {
  --color-primary-text: #000000;
  --color-primary-background: #ffffff;
  --color-accent: #0066cc;
  /* ... additional tokens */
}

See the Storybook Design Tokens documentation for a complete list of available tokens.

Shadow DOM Styling

Components use Shadow DOM for encapsulation. To style internal elements:

• Light DOM elements: Use standard CSS selectors
• Shadow DOM elements: Use ::part() pseudo-selector if the element exposes a part attribute
• Scoped styling: Target specific instances using parent selectors: #my-form pu-button::part(button)

If you need styling access to an element that doesn't expose a part, please open a GitHub issue with details.

License

ISC