# 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
<!-- Pin to specific version (recommended) -->
<script src="https://cdn.jsdelivr.net/npm/aw-wizard-forms@4.9.3/dist/wizard-form.min.js"></script>

<!-- Or use latest (auto-updates) -->
<script src="https://cdn.jsdelivr.net/npm/aw-wizard-forms@latest/dist/wizard-form.min.js"></script>
```

Replace `4.9.3` with your desired version. See [npm](https://www.npmjs.com/package/aw-wizard-forms) for available versions.

## 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+

## Known Issues

### Step disappears intermittently with `submit-on-step` enabled

**Status:** Under investigation

When using the `submit-on-step` attribute for partial HubSpot submissions, the next step may occasionally disappear (blank content area while progress bar updates correctly). This is a rare, intermittent issue.

**Workaround:** If you encounter this, refresh the page. The issue does not affect final form submission.

**Debug:** Run this in console when it occurs to help diagnose:
```javascript
document.querySelectorAll('wf-step').forEach((step, i) => {
  console.log(`Step ${i + 1}:`, {
    active: step.hasAttribute('active'),
    display: getComputedStyle(step).display,
    height: step.offsetHeight
  });
});
```

Track progress: [GitHub Issue #31](https://github.com/atomicworkhq/aw-wizard-forms/issues/31)

## License

MIT © [Atomicwork](https://atomicwork.com)