aw-wizard-forms 3.0.0

package/README.md

@@ -0,0 +1,189 @@
+# aw-wizard-forms
+
+A lightweight, Typeform-style multi-step form wizard built with Lit Web Components.
+
+## Features
+
+- **Lightweight**: ~15KB (Brotli) / ~18KB (gzip) including Lit
+- **Single Script Tag**: Easy embedding with `WizardForm.init()`
+- **Declarative Components**: HTML-based composition with custom elements
+- **Keyboard Navigation**: A-Z badges, Enter/Escape, arrow keys
+- **Validation**: Debounced validation with custom validators
+- **Theming**: CSS Custom Properties (`--wf-*` prefix)
+- **Adapters**: HubSpot, Webhook, RevenueHero integrations
+
+## Installation
+
+### CDN (Recommended)
+
+```html
+<script src="https://unpkg.com/aw-wizard-forms@3/dist/wizard-form.min.js"></script>
+```
+
+### Yarn / NPM
+
+```bash
+yarn add aw-wizard-forms
+```
+
+## Quick Start
+
+```html
+<wizard-form id="demo-form">
+  <wf-step data-step="1">
+    <wf-input name="fullName" label="Full Name" required></wf-input>
+    <wf-email name="email" label="Email" work-email required></wf-email>
+  </wf-step>
+
+  <wf-step data-step="2">
+    <wf-options name="companySize" required>
+      <wf-option value="1-10">1-10 employees</wf-option>
+      <wf-option value="11-50">11-50 employees</wf-option>
+      <wf-option value="51+">51+ employees</wf-option>
+    </wf-options>
+  </wf-step>
+
+  <div slot="success">
+    <h2>Thank you!</h2>
+    <p>We'll be in touch soon.</p>
+  </div>
+</wizard-form>
+
+<script>
+  WizardForm.init({
+    container: '#demo-form',
+    adapter: 'hubspot',
+    hubspot: {
+      portalId: '12345',
+      formId: 'abc-123',
+    },
+    onSubmit: (data) => console.log('Submitted:', data),
+    onSuccess: () => console.log('Success!'),
+    onError: (err) => console.error('Error:', err),
+  });
+</script>
+```
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `<wizard-form>` | Main container/orchestrator |
+| `<wf-step>` | Step container (use `data-step="N"`) |
+| `<wf-input>` | Text input with validation |
+| `<wf-number>` | Number input with min/max/step |
+| `<wf-email>` | Email input with work-email validation |
+| `<wf-textarea>` | Multiline text input |
+| `<wf-options>` | Radio/checkbox option group |
+| `<wf-option>` | Individual option card |
+
+## Adapters
+
+### HubSpot
+
+```javascript
+WizardForm.init({
+  container: '#form',
+  adapter: 'hubspot',
+  hubspot: {
+    portalId: '12345',
+    formId: 'abc-123',
+    fieldMapping: {
+      fullName: 'firstname', // Map form fields to HubSpot fields
+    },
+  },
+});
+```
+
+### Webhook
+
+```javascript
+WizardForm.init({
+  container: '#form',
+  adapter: 'webhook',
+  webhook: {
+    url: 'https://api.example.com/submit',
+    method: 'POST',
+    headers: {
+      'X-API-Key': 'your-key',
+    },
+  },
+});
+```
+
+### RevenueHero
+
+```javascript
+WizardForm.init({
+  container: '#form',
+  adapter: 'revenuehero',
+  revenuehero: {
+    routerId: 'your-router-id',
+  },
+});
+```
+
+## Theming
+
+Customize with CSS Custom Properties:
+
+```css
+wizard-form {
+  --wf-color-primary: #8b5cf6;
+  --wf-color-surface: #f8f9fa;
+  --wf-color-text: #212529;
+  --wf-color-error: #dc3545;
+  --wf-radius-lg: 12px;
+  --wf-font-size-base: 16px;
+}
+```
+
+## Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| A-Z | Select option by badge |
+| Enter | Next step / Submit |
+| Escape | Previous step |
+| ↑/↓ | Navigate options |
+| Tab | Navigate fields |
+
+## Development
+
+```bash
+# Install dependencies
+yarn
+
+# Development server
+yarn dev
+
+# Run tests
+yarn test          # Unit tests (Vitest)
+yarn test:e2e      # E2E tests (Playwright)
+
+# Build
+yarn build
+
+# Check bundle size
+yarn size
+```
+
+## Bundle Size
+
+| Compression | Size |
+|-------------|------|
+| Raw | 78KB |
+| Gzip | 17.7KB |
+| **Brotli** | **15.5KB** |
+
+## Browser Support
+
+Modern browsers (ES2020+):
+- Chrome 80+
+- Firefox 78+
+- Safari 14+
+- Edge 80+
+
+## License
+
+MIT © [Atomicwork](https://atomicwork.com)