@codebards/ik-embeddable-form 0.0.2622736993-qa → 0.0.2664433215-qa

package/README.md

@@ -2,6 +2,8 @@
 
 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
@@ -36,8 +38,9 @@ src/
 │   └── Shared/           # Button · Input · Select · Textarea · Radio · Checkbox
 │
 ├── configs/
-│   ├── sample-webinar.config.ts   # Multi-step webinar registration
-│   └── sample-contact.config.ts  # Conditional contact form
+│   ├── 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
@@ -70,7 +73,7 @@ The form is mounted inside a **Shadow DOM** attached to a `<div id="ik-form-host
 ### Via CDN (Recommended)
 
 ```html
-<script src="https://cdn.example.com/forms/v1/embed.js"></script>
+<script src="https://cdn.example.com/forms/v1.0.11/embed.js" async></script>
 ```
 
 ### Self-hosted
@@ -85,15 +88,22 @@ npm run build:production
 ### npm (for framework integration)
 
 ```bash
-npm install ik-embeddable-form
+npm install @codebards/ik-embeddable-form
 ```
 
 ```ts
-import { IKForm } from 'ik-embeddable-form';
+import { IKForm } from '@codebards/ik-embeddable-form';
 
-IKForm.open({ eventName: 'my-webinar', webinarType: 'live', ... });
+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
@@ -101,64 +111,59 @@ IKForm.open({ eventName: 'my-webinar', webinarType: 'live', ... });
 ### Basic
 
 ```html
-<script src="https://cdn.example.com/forms/embed.js"></script>
+<script src="https://cdn.example.com/forms/v1.0.11/embed.js" async></script>
 <script>
   window.IKForm.open({
-    eventName:     'ai-summit-2026',
-    webinarType:   'live',
-    site:          'main',
-    variant:       'default',
+    eventName:   'How to Nail your next Technical Interview',
+    webinarType: 'REGULAR',
+    site:        'organic',   // or 'learn'
+    variant:     'default',   // 'default' | 'india' | 'event' | content variant name
   });
 </script>
 ```
 
-### With All Options
+### Common options
 
 ```ts
 window.IKForm.open({
   // Required
-  eventName:     'ai-summit-2026',   // Matches FormConfig.eventName
-  webinarType:   'live',             // Matches FormConfig.webinarType
-  site:          'main',             // Multi-site identifier (forwarded to API)
-  variant:       'compact',          // Must match a FormVariant.id (or 'default')
+  eventName:   'How to Nail your next Technical Interview',
+  webinarType: 'REGULAR',
+  site:        'learn',
+  variant:     'india',
 
   // Optional
-  preferredSlot:   'slot-morning',   // Pre-selects a slot field
-
-  prefilledValues: {                 // Pre-fills form fields by name
-    email:     'user@example.com',
-    firstName: 'Jane',
+  prefilledValues: {
+    email:    'user@example.com',
+    fullName: 'Jane Doe',
   },
 
-  configOverrides: {                 // Runtime overrides merged on top of config
-    theme: { modalMaxWidth: '600px' },
+  configOverrides: {
+    layout: {
+      leftPanel: { data: { headline: 'Campaign headline' } },
+    },
   },
 
-  // Callbacks
-  onSuccess: (result) => {
-    console.log('Form submitted:', result.data);
-    console.log('Ticket/Reg ID:', result.data.registrationId);
-  },
-  onClose: () => {
-    console.log('Modal closed');
-  },
-  onError: (err) => {
-    console.error('Form error:', err.code, err.message);
-  },
+  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
-// Close the modal
 window.IKForm.close();
-
-// Full cleanup (SPA route change)
-window.IKForm.destroy();
-
-// Get loaded version
-console.log(window.IKForm.getVersion()); // "1.0.0"
+window.IKForm.destroy();              // SPA route change
+console.log(window.IKForm.getVersion()); // "1.0.11"
 ```
 
 ---
@@ -352,53 +357,110 @@ The `__VERSION__` constant is automatically injected from `package.json` at buil
 
 ## Adding New Form Variants
 
-### Option A — New Variant on Existing Config
+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`).
 
-Add a `FormVariant` to the `variants` array of an existing `FormConfig`:
+### 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
-// src/configs/sample-webinar.config.ts
-variants: [
-  {
-    id: 'enterprise',
-    overrides: {
-      steps: [ /* override any step */ ],
-      theme: { modalMaxWidth: '680px' },
+import type { FormVariant } from '@/types';
+
+export const myVariant: FormVariant = {
+  id: 'my-variant',
+  overrides: {
+    steps: {
+      'profile-details': {
+        fields: { primaryGoal: { show: false } },
+      },
     },
   },
-],
+};
 ```
 
-Then call:
-```ts
-IKForm.open({ eventName: 'ai-summit-2026', webinarType: 'live', variant: 'enterprise' });
-```
+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
 
-1. Create `src/configs/my-new-form.config.ts`
-2. Export a `FormConfig` object with a unique `eventName` + `webinarType`
-3. Register it in `src/configs/index.ts`:
+For a fundamentally different product flow (not a variant of GQL webinar):
 
-```ts
-import { myNewFormConfig } from './my-new-form.config';
+1. Create `src/configs/my-new-form.base.ts`
+2. Export a `FormConfig` with a unique `webinarType`
+3. Register in `src/configs/index.ts`
 
-export const ALL_CONFIGS: FormConfig[] = [
-  webinarConfig,
-  contactConfig,
-  myNewFormConfig, // ← add here
-];
+```ts
+IKForm.open({ webinarType: 'MASTERCLASS', variant: 'default', ... });
 ```
 
-No other files need to change. The platform supports **25+ variants** this way.
-
 ---
 
 ## Analytics Integration
 
 ### GTM
 
-Events are pushed to `window.dataLayer` automatically. Configure your GTM triggers on:
+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
@@ -434,9 +496,9 @@ All API calls are defined in `ApiContract` objects inside your form config — *
 ### Dynamic URL Interpolation
 
 ```ts
-endpoint: 'slots/{slot}/reserve'
-// If form data has { slot: "slot-morning" }
-// → POST https://api.example.com/api/slots/slot-morning/reserve
+endpoint: 'webinar/{site}/add-info'
+// If form data has { site: "organic" }
+// → POST https://api.example.com/api/webinar/organic/add-info
 ```
 
 ### Body Mapping
@@ -464,7 +526,7 @@ responseMapping: {
 ### Auth Token
 
 ```ts
-import { apiClient } from 'ik-embeddable-form';
+import { apiClient } from '@codebards/ik-embeddable-form';
 
 apiClient.setAuthToken('Bearer your-token-here');
 ```
@@ -484,7 +546,7 @@ import type {
   OpenConfig,
   ConditionalRule,
   IKFormSDK,
-} from 'ik-embeddable-form';
+} from '@codebards/ik-embeddable-form';
 ```
 
 ---