@codebards/ik-embeddable-form 0.0.29-qa

package/README.md

@@ -0,0 +1,556 @@
+# IK Embeddable Form
+
+A production-ready, config-driven embeddable form platform built with **Preact**, **TypeScript**, **Vite**, **Tailwind CSS**, and **Shadow DOM** isolation.
+
+> **Integrating the form on your site?** See **[INTEGRATION.md](INTEGRATION.md)** for step-by-step guides (HTML, WordPress, React), variant usage, custom JSON variants, and fallback behavior.
+
+---
+
+## Table of Contents
+
+1. [Architecture Overview](#architecture-overview)
+2. [Installation](#installation)
+3. [Script Usage](#script-usage)
+4. [Config Schema](#config-schema)
+5. [Environment Setup](#environment-setup)
+6. [Build & Deployment](#build--deployment)
+7. [Versioning Strategy](#versioning-strategy)
+8. [Adding New Form Variants](#adding-new-form-variants)
+9. [Analytics Integration](#analytics-integration)
+10. [API Integration](#api-integration)
+
+---
+
+## Architecture Overview
+
+```
+src/
+├── core/
+│   ├── FormEngine/       # Orchestrates step transitions, state, API calls
+│   ├── StepResolver/     # Evaluates conditions, resolves next steps
+│   ├── ConfigResolver/   # Resolves FormConfig from OpenConfig + variants
+│   ├── ApiClient/        # HTTP client with retries, body/response mapping
+│   └── Analytics/        # GTM · Sentry · Clarity · Cookie facades
+│
+├── components/
+│   ├── Modal/            # Accessible modal with backdrop + progress bar
+│   ├── FormSteps/        # StepRenderer · AutoStep · SuccessStep · FieldRenderer
+│   └── Shared/           # Button · Input · Select · Textarea · Radio · Checkbox
+│
+├── configs/
+│   ├── gql-webinar.base.ts        # Full webinar form superset
+│   ├── gql-webinar.config.ts      # Base + bundled variants registry
+│   └── variants/                  # Structural overrides (default, india, event)
+│
+├── hooks/
+│   ├── useFormEngine.ts   # Subscribes to FormEngine state
+│   └── useAnalytics.ts    # Analytics action hooks
+│
+├── styles/
+│   └── base.css           # Tailwind directives + Shadow DOM resets
+│
+├── types/
+│   └── index.ts           # FormConfig · FormStep · ValidationRule · ApiContract · AnalyticsEvent
+│
+├── App.tsx                # Root Preact component
+└── sdk/
+    ├── index.ts           # window.IKForm global API
+    └── mount.ts           # Shadow DOM mount/unmount/destroy
+```
+
+### Shadow DOM Isolation
+
+The form is mounted inside a **Shadow DOM** attached to a `<div id="ik-form-host">` injected into `document.body`. This means:
+
+- Global CSS on the host page **cannot** bleed into the form
+- Form styles **cannot** leak out to the host page
+- No class name or selector conflicts
+
+---
+
+## Installation
+
+### Via CDN (Recommended)
+
+```html
+<script src="https://cdn.example.com/forms/v1.0.11/embed.js" async></script>
+```
+
+### Self-hosted
+
+```bash
+# Build for production
+npm run build:production
+
+# Upload dist/embed.js to your CDN / server
+```
+
+### npm (for framework integration)
+
+```bash
+npm install @codebards/ik-embeddable-form
+```
+
+```ts
+import { IKForm } from '@codebards/ik-embeddable-form';
+
+IKForm.open({
+  eventName:   'How to Nail your next Technical Interview',
+  webinarType: 'REGULAR',
+  site:        'organic',
+  variant:     'default',
+});
+```
+
+Full integration examples (HTML, WordPress, React, variants, custom JSON): **[INTEGRATION.md](INTEGRATION.md)**
+
+---
+
+## Script Usage
+
+### Basic
+
+```html
+<script src="https://cdn.example.com/forms/v1.0.11/embed.js" async></script>
+<script>
+  window.IKForm.open({
+    eventName:   'How to Nail your next Technical Interview',
+    webinarType: 'REGULAR',
+    site:        'organic',   // or 'learn'
+    variant:     'default',   // 'default' | 'india' | 'event' | content variant name
+  });
+</script>
+```
+
+### Common options
+
+```ts
+window.IKForm.open({
+  // Required
+  eventName:   'How to Nail your next Technical Interview',
+  webinarType: 'REGULAR',
+  site:        'learn',
+  variant:     'india',
+
+  // Optional
+  prefilledValues: {
+    email:    'user@example.com',
+    fullName: 'Jane Doe',
+  },
+
+  configOverrides: {
+    layout: {
+      leftPanel: { data: { headline: 'Campaign headline' } },
+    },
+  },
+
+  dataClickId: 'hero_cta',
+
+  // WordPress — theme already loads GTM
+  loadGtm:     false,
+  loadClarity: false,
+
+  onSuccess: (result) => console.log('Submitted:', result.data),
+  onClose:   () => console.log('Closed'),
+  onError:   (err) => console.error(err.code, err.message),
+});
+```
+
+See **[INTEGRATION.md](INTEGRATION.md)** for WordPress, React/SPA, variant JSON, and fallback details.
+
+### Programmatic Control
+
+```ts
+window.IKForm.close();
+window.IKForm.destroy();              // SPA route change
+console.log(window.IKForm.getVersion()); // "1.0.11"
+```
+
+---
+
+## Config Schema
+
+### `FormConfig` (root)
+
+| Property         | Type              | Required | Description                                      |
+|------------------|-------------------|----------|--------------------------------------------------|
+| `id`             | `string`          | ✅        | Unique config identifier                         |
+| `name`           | `string`          | ✅        | Human-readable form name                         |
+| `version`        | `string`          | ✅        | Semver (e.g. `"1.2.0"`)                          |
+| `eventName`      | `string`          | ✅        | Matches `OpenConfig.eventName`                   |
+| `webinarType`    | `string`          | –         | Matches `OpenConfig.webinarType`                 |
+| `defaultVariant` | `string`          | ✅        | Fallback variant ID                              |
+| `variants`       | `FormVariant[]`   | –         | Named overrides applied on top of base config    |
+| `steps`          | `FormStep[]`      | ✅        | Ordered step definitions                         |
+| `api`            | `ApiContract`     | ✅        | Default submission endpoint                      |
+| `analytics`      | `AnalyticsConfig` | –         | Open/close/submit event config                   |
+| `theme`          | `ThemeConfig`     | –         | Visual customisation                             |
+| `i18n`           | `Record<string, string>` | – | Localisation strings                             |
+| `metadata`       | `Record<string, string \| number \| boolean>` | – | Forwarded to analytics |
+
+### `FormStep`
+
+| Property         | Type                             | Description                                      |
+|------------------|----------------------------------|--------------------------------------------------|
+| `id`             | `string`                         | Unique step identifier                           |
+| `type`           | `"form" \| "auto" \| "success" \| "error" \| "info"` | Step type       |
+| `title`          | `string?`                        | Step heading                                     |
+| `subtitle`       | `string?`                        | Step sub-heading                                 |
+| `hidden`         | `boolean?`                       | Hide from progress indicator                     |
+| `condition`      | `ConditionalRule?`               | Step only reachable when condition passes         |
+| `autoExecute`    | `AutoExecuteConfig?`             | API call fired automatically on step entry       |
+| `fields`         | `FormField[]?`                   | Input fields rendered in this step               |
+| `api`            | `ApiContract?`                   | Per-step API call (fires on Next)                |
+| `nextStep`       | `string \| ConditionalNextStep[]?` | Fixed or conditional next step routing         |
+| `allowBack`      | `boolean?`                       | Show Back button (default: `true`)               |
+| `submitLabel`    | `string?`                        | Override CTA label                               |
+| `analyticsEvents`| `AnalyticsEvent[]?`              | Events fired when step becomes active            |
+
+### `FormField`
+
+| Property       | Type              | Description                                      |
+|----------------|-------------------|--------------------------------------------------|
+| `name`         | `string`          | Field name (key in form data)                    |
+| `type`         | `FieldType`       | `text \| email \| tel \| number \| textarea \| select \| radio \| checkbox \| date \| hidden \| slot-picker` |
+| `label`        | `string?`         | Label text                                       |
+| `placeholder`  | `string?`         | Placeholder text                                 |
+| `defaultValue` | `string \| number \| boolean?` | Initial value                   |
+| `options`      | `FieldOption[]?`  | Options for select/radio                         |
+| `validation`   | `ValidationRule[]?` | Array of validation rules                      |
+| `condition`    | `ConditionalRule?` | Show/hide field based on other field values      |
+| `colSpan`      | `number?`         | Grid column span (1 = half, 2 = full)            |
+
+### `ValidationRule`
+
+| Property     | Type             | Description                                       |
+|--------------|------------------|---------------------------------------------------|
+| `type`       | `ValidationType` | `required \| email \| phone \| min \| max \| minLength \| maxLength \| pattern \| custom \| async` |
+| `value`      | `number \| string?` | Threshold or pattern string                    |
+| `message`    | `string`         | Error message shown to user                       |
+| `condition`  | `ConditionalRule?` | Only apply this rule when condition is true     |
+
+### `ApiContract`
+
+| Property          | Type                  | Description                                      |
+|-------------------|-----------------------|--------------------------------------------------|
+| `endpoint`        | `string`              | Relative path or full URL. Supports `{fieldName}` interpolation |
+| `method`          | `HttpMethod`          | `GET \| POST \| PUT \| PATCH \| DELETE`          |
+| `bodyMapping`     | `Record<string,string> \| "$all"` | Map form fields → request body keys |
+| `responseMapping` | `Record<string,string>?` | Map response JSON paths → form field names   |
+| `queryParams`     | `Record<string,string>?` | Query params with `{fieldName}` interpolation|
+| `authenticated`   | `boolean?`            | Include `Authorization: Bearer` header           |
+| `retries`         | `number?`             | Retry count (default: 1)                         |
+| `timeoutMs`       | `number?`             | Request timeout (default: 10,000ms)              |
+| `mockResponse`    | `unknown?`            | Used in `local` env instead of real network call |
+
+### `ConditionalRule`
+
+```ts
+{
+  logical?: "AND" | "OR",  // default: "AND"
+  clauses: [
+    {
+      field:    "fieldName",        // dot notation supported: "address.city"
+      operator: "equals" | "not_equals" | "contains" | "not_contains" |
+                "starts_with" | "ends_with" | "greater_than" | "less_than" |
+                "is_empty" | "is_not_empty" | "matches_regex",
+      value?:   "some value"        // not needed for is_empty / is_not_empty
+    }
+  ]
+}
+```
+
+---
+
+## Environment Setup
+
+| File              | Used For               |
+|-------------------|------------------------|
+| `.env`            | Local development       |
+| `.env.staging`    | Staging builds          |
+| `.env.production` | Production builds       |
+
+### Required Variables
+
+```ini
+VITE_API_BASE_URL=https://api.example.com/api
+VITE_GTM_ID=GTM-XXXXXXX
+VITE_SENTRY_DSN=https://xxx@sentry.io/xxx
+VITE_CLARITY_ID=xxxxxxxxxx
+```
+
+---
+
+## Build & Deployment
+
+### Local Dev Server
+
+```bash
+npm install
+npm run dev
+# Opens http://localhost:3000 with a test page
+```
+
+### Build Commands
+
+```bash
+npm run build            # Builds with .env (local defaults)
+npm run build:staging    # Builds with .env.staging
+npm run build:production # Builds with .env.production (minified)
+```
+
+### Build Output
+
+```
+dist/
+├── embed.js        # Self-contained IIFE bundle (reference in <script>)
+└── embed.js.map    # Source map (only in staging/local builds)
+```
+
+### Deployment Checklist
+
+1. Run `npm run build:production`
+2. Upload `dist/embed.js` to your CDN with a versioned path:
+   ```
+   https://cdn.example.com/forms/v1.0.0/embed.js
+   ```
+3. Set cache headers:
+   - `embed.js` → `Cache-Control: public, max-age=31536000, immutable` (versioned path)
+   - Use a `latest` alias for convenience: `cdn.example.com/forms/latest/embed.js` with shorter TTL
+
+4. Reference on the host page:
+   ```html
+   <script src="https://cdn.example.com/forms/v1.0.0/embed.js" async></script>
+   ```
+
+---
+
+## Versioning Strategy
+
+This project follows **Semantic Versioning** (`MAJOR.MINOR.PATCH`):
+
+| Change Type          | Version Bump | Example |
+|----------------------|-------------|---------|
+| Breaking API change  | MAJOR       | `2.0.0` |
+| New form variant     | MINOR       | `1.1.0` |
+| Bug fix / patch      | PATCH       | `1.0.1` |
+
+### Release Process
+
+```bash
+# 1. Bump version in package.json
+npm version patch   # or minor / major
+
+# 2. Build production artefact
+npm run build:production
+
+# 3. Tag the release
+git tag v$(node -p "require('./package.json').version")
+git push --tags
+
+# 4. Upload dist/embed.js to CDN under versioned path
+```
+
+The `__VERSION__` constant is automatically injected from `package.json` at build time.
+
+---
+
+## Adding New Form Variants
+
+The form uses a **base config + variant overrides** merge pattern. See **[INTEGRATION.md](INTEGRATION.md)** for host-page usage, JSON schema, resolution order, and fallback behavior.
+
+| Tier | Examples | Where | Deploy needed? |
+|------|----------|-------|----------------|
+| **Structural** | `default`, `india`, `event` | `src/configs/variants/*.variant.ts` | Yes (code review) |
+| **Content** | `masterclass`, campaign names | CDN JSON at `{VITE_FORM_VARIANTS_BASE_URL}/{variant}.json` | No (upload JSON only) |
+
+**Resolution order:** bundled variant → remote JSON → fallback to `default` (console warning).
+
+Set `VITE_FORM_VARIANTS_BASE_URL` at build time. Local dev defaults to `/form-variants` (`public/form-variants/masterclass.json`).
+
+### Bundled variant files
+
+| File | Purpose |
+|------|---------|
+| `default.variant.ts` | Standard flow |
+| `india.variant.ts` | Hide `primaryGoal` on profile step |
+| `event.variant.ts` | Hide slot picker; event copy; auto-book slot |
+
+Base config (`gql-webinar.base.ts`) holds the full superset. Each variant file declares only what differs.
+
+### Adding a structural variant (engineering)
+
+1. Create `src/configs/variants/my-variant.variant.ts` with only the diff:
+
+```ts
+import type { FormVariant } from '@/types';
+
+export const myVariant: FormVariant = {
+  id: 'my-variant',
+  overrides: {
+    steps: {
+      'profile-details': {
+        fields: { primaryGoal: { show: false } },
+      },
+    },
+  },
+};
+```
+
+2. Register in `src/configs/variants/index.ts`
+3. Deploy embed
+
+---
+
+### Adding a content variant (no code deploy)
+
+1. Create `{variant}.json` — see [INTEGRATION.md → Create your own variant JSON](INTEGRATION.md#create-your-own-variant-json)
+2. Upload to `{VITE_FORM_VARIANTS_BASE_URL}/{variant}.json`
+3. Landing page: `IKForm.open({ ..., variant: 'masterclass' })`
+
+---
+
+### Option B — New FormConfig File
+
+For a fundamentally different product flow (not a variant of GQL webinar):
+
+1. Create `src/configs/my-new-form.base.ts`
+2. Export a `FormConfig` with a unique `webinarType`
+3. Register in `src/configs/index.ts`
+
+```ts
+IKForm.open({ webinarType: 'MASTERCLASS', variant: 'default', ... });
+```
+
+---
+
+## Analytics Integration
+
+### GTM
+
+The embed can **load its own GTM container** (per architecture doc) so form conversions work on Lovable / Framer / plain HTML without host-page GTM.
+
+| Setting | Default | Purpose |
+|---------|---------|---------|
+| `VITE_GTM_ID` | `GTM-P335R9N` (staging/prod) | Container injected when form opens |
+| `loadGtm` in `IKForm.open()` | `true` | Set `false` on WordPress if the theme already loads the same container |
+| `gtmContainerId` in `IKForm.open()` | build-time ID | Optional override (e.g. dedicated embed container) |
+
+```ts
+// Self-contained LP (embed loads GTM)
+IKForm.open({
+  eventName:   'How to Nail your next Technical Interview',
+  webinarType: 'REGULAR',
+  site:        'learn',
+  variant:     'default',
+});
+
+// WordPress page that already has GTM-P335R9N in the theme
+IKForm.open({ ..., loadGtm: false, loadClarity: false });
+```
+
+**dataLayer events** (WordPress parity + embed lifecycle):
+
+| When | Event |
+|------|--------|
+| Contact step success | `new_webinar_registration_form_submitted` |
+| Slot proceed | `wordpress_form_submitted` (`formName: "Webinar Slot Selection"`) |
+| Profile step | `pa_new_webinar_registration_form_submitted` (conversion — Meta / Google Ads / LinkedIn) |
+| Form open / step view | `form_open`, `form_step_view`, … |
+
+GTM fires **marketing pixels**. **Clickstream** (`ve2lt1a8il/qa` → BigQuery) is separate — see above.
+
+Events are pushed to `window.dataLayer`. Configure GTM triggers on:
+
+- `form_open` — fired when modal opens
+- `form_close` — fired when modal closes
+- `form_step_view` — fired on each step
+- `form_step_complete` — fired after Next/Submit per step
+- `form_submit_success` — fired on final submission
+- `form_submit_error` — fired on submission failure
+
+### Sentry
+
+Install `@sentry/browser` and uncomment the placeholder code in `src/core/Analytics/sentry.ts`. The DSN is injected from `VITE_SENTRY_DSN`.
+
+### Clarity
+
+Ensure the Clarity script is on the host page, or uncomment the injection block in `src/core/Analytics/clarity.ts`.
+
+### Custom Events
+
+Listen on the host page:
+
+```js
+window.addEventListener('ikform:analytics', (e) => {
+  console.log('IKForm event:', e.detail);
+});
+```
+
+---
+
+## API Integration
+
+All API calls are defined in `ApiContract` objects inside your form config — **no hardcoded fetch calls**.
+
+### Dynamic URL Interpolation
+
+```ts
+endpoint: 'webinar/{site}/add-info'
+// If form data has { site: "organic" }
+// → POST https://api.example.com/api/webinar/organic/add-info
+```
+
+### Body Mapping
+
+```ts
+bodyMapping: {
+  email:    'user.email',      // form field → nested request body key
+  slot:     'booking.slotId',
+}
+// → { user: { email: "..." }, booking: { slotId: "..." } }
+
+// OR forward all fields:
+bodyMapping: '$all'
+```
+
+### Response Mapping
+
+```ts
+responseMapping: {
+  'data.registrationId': 'registrationId',  // response path → form field
+}
+// Writes response.data.registrationId back into form state as "registrationId"
+```
+
+### Auth Token
+
+```ts
+import { apiClient } from '@codebards/ik-embeddable-form';
+
+apiClient.setAuthToken('Bearer your-token-here');
+```
+
+---
+
+## TypeScript Types Reference
+
+```ts
+import type {
+  FormConfig,
+  FormStep,
+  FormField,
+  ValidationRule,
+  ApiContract,
+  AnalyticsEvent,
+  OpenConfig,
+  ConditionalRule,
+  IKFormSDK,
+} from '@codebards/ik-embeddable-form';
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)