@nodii/onboarding 0.0.1 → 0.1.0-dev.0

package/dist/widget/index.d.ts

@@ -0,0 +1,219 @@
+import { a as OnboardingSpec } from '../model-IEyDI54w.js';
+import { OnboardingSpecCache } from '../spec/index.js';
+import { c as SignupSubmitResult } from '../signup-client-Bl6eUrxR.js';
+import 'zod/v3';
+import '../schema-TfyBU6JW.js';
+
+/**
+ * Default vanilla-TS contact form widget.
+ *
+ * Renders a form into a host element and handles the full lifecycle:
+ *   1. Render fields (name, email, phone, message)
+ *   2. Client-side validation on submit
+ *   3. reCAPTCHA token acquisition (D537)
+ *   4. POST to /api/v1/public/onboarding/leads via submit client
+ *   5. Retry on 5xx with SAME idempotency key
+ *   6. Show success or error state
+ *
+ * No React or framework required. CSS via injectWidgetStyles().
+ */
+interface ContactFormMountOptions {
+    /**
+     * The onboarder identifier (slug or UUID).
+     *
+     * NOT transmitted on the wire — by design. Per LOCKED D536, onboarder
+     * trust/scoping is derived server-side from the request Host at the edge
+     * ("onboarder derived from the bundle, never client-supplied", D540 §1);
+     * a client-supplied identifier is never trusted and therefore never sent.
+     *
+     * This option is reserved for Phase 2, where it becomes the client-side
+     * cache key for the spec-fetch (`(onboarder, specVersion)` per D540 §3).
+     * In Phase 1 it has no runtime effect.
+     */
+    onboarder: string;
+    /**
+     * Base URL for the intake service.
+     * e.g. "https://api.acme.nucleus-cloud.in"
+     */
+    baseUrl: string;
+    /**
+     * reCAPTCHA v3 site key. Obtained from the spec endpoint (D540 §1)
+     * or passed directly in Phase 1 before spec-fetch is wired.
+     */
+    siteKey: string;
+    /**
+     * Which form to render. Phase 1 supports "contact" only.
+     * Phase 2 will add "signup" (dynamic stepper from spec).
+     */
+    form: "contact";
+    /** Called after a successful lead submission. */
+    onSuccess?: () => void;
+    /** Called on non-retryable errors (bot challenge, rate limit). */
+    onError?: (error: unknown) => void;
+    /** Custom fetch implementation (defaults to globalThis.fetch). */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Per-request timeout in ms (default 15s), applied to BOTH the reCAPTCHA
+     * execute() and the submit POST so a hung dependency re-enables the form.
+     */
+    timeoutMs?: number;
+    /** Success message override. */
+    successMessage?: string;
+    /** Submit button label override. */
+    submitLabel?: string;
+}
+interface MountedWidget {
+    /** Unmount and clean up the widget from the host element. */
+    unmount(): void;
+    /** Reset the form to its initial state. */
+    reset(): void;
+}
+/**
+ * Mount the contact form widget into a host element.
+ *
+ * @example
+ * ```ts
+ * import { OnboardingWidget } from "@nodii/onboarding/widget";
+ * const widget = OnboardingWidget.mount(document.getElementById("signup"), {
+ *   onboarder: "acme-corp",
+ *   form: "contact",
+ *   baseUrl: "https://api.acme.nucleus-cloud.in",
+ *   siteKey: "6Lc...",
+ * });
+ * ```
+ */
+declare function mountContactForm(host: HTMLElement, options: ContactFormMountOptions): MountedWidget;
+
+/**
+ * Default vanilla-TS dynamic signup stepper widget (D540 Phase 2).
+ *
+ * Mount flow:
+ *   1. Fetch + validate the spec (GET /api/v1/public/onboarding/spec);
+ *      the reCAPTCHA siteKey comes FROM THE SPEC (botChallenge.siteKey) —
+ *      the mount-option siteKey is only an override/fallback.
+ *   2. Build the headless stepper from spec.forms.signup.steps.
+ *   3. Render the current step's fields per descriptor type; Back/Next
+ *      navigate with per-step validation.
+ *   4. The FINAL step carries the account section (credentials + consent
+ *      clickwrap) and the submit button.
+ *   5. Submit: validateAll → payload-fingerprint key management (same
+ *      D538 discipline as the contact widget) → reCAPTCHA token →
+ *      submitSignup.
+ *   6. 409 spec_stale: refetch the spec, applyNewSpec (drops removed
+ *      fields, re-validates), show a "form updated — please review"
+ *      banner. The SDK NEVER auto-resubmits a stale submission.
+ */
+
+interface SignupFormMountOptions {
+    /**
+     * The onboarder identifier — the CLIENT-side spec-cache key
+     * (D540 §3 `(onboarder, specVersion)`). NOT transmitted: per LOCKED
+     * D536, onboarder trust/scoping is host-derived at the edge.
+     */
+    onboarder: string;
+    baseUrl: string;
+    /**
+     * OPTIONAL siteKey override. Normally the widget uses the siteKey the
+     * spec serves (botChallenge.siteKey, D537/D540); pass this only for
+     * environments where the spec cannot carry it yet.
+     */
+    siteKey?: string;
+    form: "signup";
+    onSuccess?: (result: SignupSubmitResult) => void;
+    onError?: (error: unknown) => void;
+    /** Called after the spec loads and the stepper renders. */
+    onReady?: (spec: OnboardingSpec) => void;
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Per-request timeout in ms (default 15s), applied to the boot spec fetch,
+     * the reCAPTCHA execute(), the submit POST, and the 409 refetch — so a hung
+     * dependency never leaves "Loading signup form…"/"Sending…" stuck.
+     */
+    timeoutMs?: number;
+    submitLabel?: string;
+    tosUrl?: string;
+    privacyUrl?: string;
+    /** Spec cache override (defaults to the module-level cache). */
+    cache?: OnboardingSpecCache;
+}
+/**
+ * Mount the dynamic signup stepper into a host element.
+ * Returns synchronously; the spec loads in the background (loading state
+ * rendered meanwhile; onReady fires when interactive).
+ */
+declare function mountSignupForm(host: HTMLElement, options: SignupFormMountOptions): MountedWidget;
+
+/**
+ * Default CSS for the onboarding contact form widget.
+ *
+ * Uses CSS custom properties (variables) for theming. Consumers override
+ * these on the host element or globally:
+ *
+ *   --nodii-onboarding-font-family
+ *   --nodii-onboarding-primary-color
+ *   --nodii-onboarding-primary-hover
+ *   --nodii-onboarding-error-color
+ *   --nodii-onboarding-border-color
+ *   --nodii-onboarding-input-bg
+ *   --nodii-onboarding-label-color
+ *   --nodii-onboarding-radius
+ *   --nodii-onboarding-spacing
+ *
+ * The widget scopes all styles under `.nodii-onboarding-widget` to avoid
+ * leaking into the host page.
+ */
+declare const DEFAULT_WIDGET_CSS = "\n.nodii-onboarding-widget {\n  --_font: var(--nodii-onboarding-font-family, system-ui, -apple-system, sans-serif);\n  --_primary: var(--nodii-onboarding-primary-color, #2563eb);\n  --_primary-hover: var(--nodii-onboarding-primary-hover, #1d4ed8);\n  --_error: var(--nodii-onboarding-error-color, #dc2626);\n  --_border: var(--nodii-onboarding-border-color, #d1d5db);\n  --_input-bg: var(--nodii-onboarding-input-bg, #fff);\n  --_label: var(--nodii-onboarding-label-color, #374151);\n  --_radius: var(--nodii-onboarding-radius, 6px);\n  --_spacing: var(--nodii-onboarding-spacing, 16px);\n\n  font-family: var(--_font);\n  box-sizing: border-box;\n}\n\n.nodii-onboarding-widget *,\n.nodii-onboarding-widget *::before,\n.nodii-onboarding-widget *::after {\n  box-sizing: inherit;\n}\n\n.nodii-onboarding-field {\n  display: flex;\n  flex-direction: column;\n  gap: calc(var(--_spacing) * 0.25);\n  margin-bottom: var(--_spacing);\n}\n\n.nodii-onboarding-label {\n  font-size: 0.875rem;\n  font-weight: 500;\n  color: var(--_label);\n}\n\n.nodii-onboarding-label.required::after {\n  content: \" *\";\n  color: var(--_error);\n}\n\n.nodii-onboarding-input,\n.nodii-onboarding-textarea {\n  width: 100%;\n  padding: calc(var(--_spacing) * 0.5) calc(var(--_spacing) * 0.75);\n  border: 1px solid var(--_border);\n  border-radius: var(--_radius);\n  background: var(--_input-bg);\n  font-family: var(--_font);\n  font-size: 1rem;\n  line-height: 1.5;\n  outline: none;\n  transition: border-color 0.15s ease;\n}\n\n.nodii-onboarding-input:focus,\n.nodii-onboarding-textarea:focus {\n  border-color: var(--_primary);\n  box-shadow: 0 0 0 3px color-mix(in srgb, var(--_primary) 20%, transparent);\n}\n\n.nodii-onboarding-input.has-error,\n.nodii-onboarding-textarea.has-error {\n  border-color: var(--_error);\n}\n\n.nodii-onboarding-textarea {\n  min-height: 100px;\n  resize: vertical;\n}\n\n.nodii-onboarding-field-error {\n  font-size: 0.75rem;\n  color: var(--_error);\n  margin-top: 2px;\n}\n\n.nodii-onboarding-server-error {\n  padding: calc(var(--_spacing) * 0.75);\n  border-radius: var(--_radius);\n  background: color-mix(in srgb, var(--_error) 8%, transparent);\n  border: 1px solid color-mix(in srgb, var(--_error) 30%, transparent);\n  color: var(--_error);\n  font-size: 0.875rem;\n  margin-bottom: var(--_spacing);\n}\n\n.nodii-onboarding-success {\n  padding: var(--_spacing);\n  border-radius: var(--_radius);\n  background: #f0fdf4;\n  border: 1px solid #bbf7d0;\n  color: #15803d;\n  font-size: 0.9375rem;\n  text-align: center;\n}\n\n.nodii-onboarding-submit-btn {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 100%;\n  padding: calc(var(--_spacing) * 0.625) var(--_spacing);\n  background: var(--_primary);\n  color: #fff;\n  border: none;\n  border-radius: var(--_radius);\n  font-family: var(--_font);\n  font-size: 1rem;\n  font-weight: 500;\n  cursor: pointer;\n  transition: background 0.15s ease;\n}\n\n.nodii-onboarding-submit-btn:hover:not(:disabled) {\n  background: var(--_primary-hover);\n}\n\n.nodii-onboarding-submit-btn:disabled {\n  opacity: 0.6;\n  cursor: not-allowed;\n}\n\n.nodii-onboarding-spinner {\n  display: inline-block;\n  width: 1em;\n  height: 1em;\n  border: 2px solid rgba(255,255,255,0.4);\n  border-top-color: #fff;\n  border-radius: 50%;\n  animation: nodii-spin 0.6s linear infinite;\n  margin-right: 0.5em;\n}\n\n@keyframes nodii-spin {\n  to { transform: rotate(360deg); }\n}\n\n.nodii-onboarding-recaptcha-notice {\n  font-size: 0.7rem;\n  color: #6b7280;\n  margin-top: calc(var(--_spacing) * 0.5);\n  text-align: center;\n}\n\n.nodii-onboarding-recaptcha-notice a {\n  color: inherit;\n}\n\n/* \u2500\u2500 dynamic stepper (signup form) \u2500\u2500 */\n\n.nodii-onboarding-steps {\n  display: flex;\n  gap: calc(var(--_spacing) * 0.5);\n  margin-bottom: var(--_spacing);\n}\n\n.nodii-onboarding-step-dot {\n  flex: 1;\n  height: 4px;\n  border-radius: 2px;\n  background: var(--_border);\n}\n\n.nodii-onboarding-step-dot.active {\n  background: var(--_primary);\n}\n\n.nodii-onboarding-stage-title {\n  font-size: 1.0625rem;\n  font-weight: 600;\n  color: var(--_label);\n  margin: 0 0 var(--_spacing) 0;\n}\n\n.nodii-onboarding-nav {\n  display: flex;\n  gap: calc(var(--_spacing) * 0.5);\n  margin-top: var(--_spacing);\n}\n\n.nodii-onboarding-back-btn {\n  padding: calc(var(--_spacing) * 0.625) var(--_spacing);\n  background: transparent;\n  color: var(--_label);\n  border: 1px solid var(--_border);\n  border-radius: var(--_radius);\n  font-family: var(--_font);\n  font-size: 1rem;\n  cursor: pointer;\n}\n\n.nodii-onboarding-stale-banner {\n  padding: calc(var(--_spacing) * 0.75);\n  border-radius: var(--_radius);\n  background: #fffbeb;\n  border: 1px solid #fcd34d;\n  color: #92400e;\n  font-size: 0.875rem;\n  margin-bottom: var(--_spacing);\n}\n\n.nodii-onboarding-consent-row {\n  display: flex;\n  align-items: flex-start;\n  gap: calc(var(--_spacing) * 0.5);\n  margin-bottom: calc(var(--_spacing) * 0.5);\n  font-size: 0.875rem;\n  color: var(--_label);\n}\n\n.nodii-onboarding-consent-row input[type=\"checkbox\"] {\n  margin-top: 3px;\n}\n\n.nodii-onboarding-account-section {\n  border-top: 1px solid var(--_border);\n  margin-top: var(--_spacing);\n  padding-top: var(--_spacing);\n}\n\n.nodii-onboarding-loading {\n  padding: var(--_spacing);\n  text-align: center;\n  color: var(--_label);\n}\n";
+/**
+ * Inject the default widget CSS once into the document head.
+ * Idempotent — will not add a duplicate style tag.
+ */
+declare function injectWidgetStyles(): void;
+
+/**
+ * Shared DOM helpers for the widget layer.
+ *
+ * `idSelector` builds a `#id` CSS selector with the id CSS-escaped, so a field
+ * key (which originates in the fetched onboarder spec) can never break out of
+ * the selector or match unintended nodes. This is defense-in-depth: the spec
+ * model already constrains field keys to `[A-Za-z0-9_-]+` (FIELD_KEY_PATTERN),
+ * but the escaping guarantees selector safety even for the widget's own
+ * internally-composed ids and for any future relaxation of that alphabet.
+ */
+/**
+ * CSS-escape a string for safe use as an identifier in a selector.
+ * Uses the standard `CSS.escape` when available (all modern browsers), with a
+ * spec-compliant-enough fallback for non-DOM/test runtimes: escape everything
+ * that is not an ASCII identifier char.
+ */
+declare function cssEscape(value: string): string;
+/** Build a safe `#id` selector with the id CSS-escaped. */
+declare function idSelector(id: string): string;
+
+type WidgetMountOptions = ContactFormMountOptions | SignupFormMountOptions;
+declare const OnboardingWidget: {
+    /**
+     * Mount the onboarding widget into a host element.
+     *
+     * @param el - The DOM element to render into.
+     * @param options - Widget configuration. `form: "contact"` renders the
+     *   fixed contact form (Phase 1); `form: "signup"` fetches the D540 spec
+     *   and renders the dynamic stepper (Phase 2 — siteKey comes from the
+     *   spec's botChallenge unless overridden).
+     * @returns A mounted widget control (unmount / reset).
+     *
+     * @example
+     * ```ts
+     * import { OnboardingWidget } from "@nodii/onboarding/widget";
+     *
+     * OnboardingWidget.mount(document.getElementById("signup-form")!, {
+     *   onboarder: "acme-corp",
+     *   form: "signup",
+     *   baseUrl: "https://api.acme.nucleus-cloud.in",
+     *   onSuccess: (r) => console.log("landed at", r.terminalStage),
+     * });
+     * ```
+     */
+    readonly mount: (el: HTMLElement, options: WidgetMountOptions) => MountedWidget;
+};
+
+export { type ContactFormMountOptions, DEFAULT_WIDGET_CSS, type MountedWidget, OnboardingWidget, type SignupFormMountOptions, type WidgetMountOptions, cssEscape, idSelector, injectWidgetStyles, mountContactForm, mountSignupForm };

package/dist/widget/index.js

@@ -0,0 +1,10 @@
+export { DEFAULT_WIDGET_CSS, OnboardingWidget, cssEscape, idSelector, injectWidgetStyles, mountContactForm, mountSignupForm } from '../chunk-SWMIIUXR.js';
+import '../chunk-AFCJLUPK.js';
+import '../chunk-34BQX2KR.js';
+import '../chunk-4SWOVHZ2.js';
+import '../chunk-BQCTDU5V.js';
+import '../chunk-BIFANV7M.js';
+import '../chunk-AW7W3HAC.js';
+import '../chunk-7NS7ENJV.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/widget/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -1,24 +1,95 @@
 {
   "name": "@nodii/onboarding",
-  "version": "0.0.1",
-  "description": "Placeholder for @nodii/onboarding — implementation lands at v0.1.0",
+  "version": "0.1.0-dev.0",
+  "description": "Browser SDK for the Nodii self-signup onboarding flow. Headless form state, reCAPTCHA integration, and a default themeable vanilla-TS widget. D540/D537 contract client.",
   "license": "MIT",
   "type": "module",
+  "browser": true,
   "main": "./dist/index.js",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./form": {
+      "import": {
+        "types": "./dist/form/index.d.ts",
+        "default": "./dist/form/index.js"
+      }
+    },
+    "./spec": {
+      "import": {
+        "types": "./dist/spec/index.d.ts",
+        "default": "./dist/spec/index.js"
+      }
+    },
+    "./dynamic": {
+      "import": {
+        "types": "./dist/dynamic/index.d.ts",
+        "default": "./dist/dynamic/index.js"
+      }
+    },
+    "./submit": {
+      "import": {
+        "types": "./dist/submit/index.d.ts",
+        "default": "./dist/submit/index.js"
+      }
+    },
+    "./recaptcha": {
+      "import": {
+        "types": "./dist/recaptcha/index.d.ts",
+        "default": "./dist/recaptcha/index.js"
+      }
+    },
+    "./widget": {
+      "import": {
+        "types": "./dist/widget/index.d.ts",
+        "default": "./dist/widget/index.js"
+      }
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.10.6",
+    "tsup": "^8.3.5",
+    "typescript": "^5.9.3"
+  },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/cognion-nucleus/nodii-libs.git",
     "directory": "ts/onboarding"
+  },
+  "keywords": [
+    "onboarding",
+    "self-signup",
+    "recaptcha",
+    "browser",
+    "sdk",
+    "nodii"
+  ],
+  "engines": {
+    "node": ">=20"
   }
 }

package/README.md

@@ -1,5 +0,0 @@
-# @nodii/onboarding
-
-Placeholder package at v0.0.1. Real implementation ships at v0.1.0 per the locked feature_doc.
-
-**Spec**: `https://planning.dev.nucleus-cloud.in/api/v1/feature-docs?serviceId=nodii-libs&docKey=onboarding`