@coding-blocks/vmc-web-components 0.1.0

package/README.md

@@ -0,0 +1,205 @@
+# @coding-blocks/vmc-web-components
+
+Embeddable HTML web components for Vidyamandir Classes forms. React on the
+inside, plain custom elements on the outside — a host page only needs one
+`<script>` tag and the element.
+
+Every component in this repo ships in **one bundle**: `dist/vmc-web-components.js`
+(React and the CSS are inlined, so there are no peer dependencies and no extra
+network requests).
+
+## Usage
+
+```html
+<script src="https://unpkg.com/@coding-blocks/vmc-web-components"></script>
+
+<vmc-online-lead></vmc-online-lead>
+```
+
+The API base URL is **compiled into the bundle** — embedding pages never pass
+it. See [Environments](#environments).
+
+Pin a version in production:
+
+```html
+<script src="https://unpkg.com/@coding-blocks/vmc-web-components@0.1.0/dist/vmc-web-components.js"></script>
+```
+
+The script can go anywhere — elements already in the DOM upgrade as soon as it
+loads. Each component renders inside a **shadow root**, so the host page's CSS
+can't leak in and the component's CSS can't leak out.
+
+## Components
+
+### `<vmc-online-lead>`
+
+The "Want a call back?" lead form. Fields posted to the backend:
+`name`, `email`, `dial_code`, `mobile`, `class_id`, `course_id`, `state_id`,
+`city_id`.
+
+Mobile verification is mandatory: **Submit stays disabled until the number is
+OTP-verified** and the consent box is ticked. Editing the number after
+verification drops it back to unverified, so a submission can never carry an OTP
+that belongs to a different number.
+
+| Attribute | Default | Purpose |
+| --- | --- | --- |
+| `api-base` | build-time `VITE_API_URL` | Override the compiled-in base (testing only) |
+| `heading` | `Want a call back ?` | Card heading |
+| `dial-code` | `+91` | Pre-selected dial code |
+| `consent-text` | VMC authorisation copy | Consent checkbox label |
+| `submit-label` | `Submit` | Submit button label |
+| `success-title` | `Thank you!` | Heading after a successful submit |
+| `success-message` | counsellor call-back copy | Body after a successful submit |
+| `source` | `website` | Sent through as `source` in the payload |
+| `extra-payload` | — | JSON object merged into the submit payload |
+
+Events (bubbling and composed, so they cross the shadow boundary):
+
+```js
+const el = document.querySelector('vmc-online-lead')
+el.addEventListener('vmc-lead-success', (e) => console.log(e.detail.response))
+el.addEventListener('vmc-lead-error', (e) => console.log(e.detail.error))
+```
+
+## Environments
+
+The base URL comes from `VITE_API_URL`, read at **build** time and inlined into
+`dist/vmc-web-components.js`:
+
+| File | Used by | Value |
+| --- | --- | --- |
+| `.env.development` | `npm run dev`, `npm run build:dev` | `http://localhost:3000/api` |
+| `.env.production` | `npm run build` (what gets published) | `https://vmcrm-api.codingblocks.com/api` |
+
+`npm run build` always builds in production mode, so `npm publish` can only ever
+ship the production base. The build refuses to start if `VITE_API_URL` is
+missing or isn't a URL, so a bundle pointing nowhere can't be produced.
+
+Changing the base means a rebuild and a republish — that's the point: embedding
+pages carry no configuration and can't drift.
+
+## Endpoints
+
+Defaults are relative to the compiled-in base. Each is overridable per element with the
+matching attribute, so a component can be repointed without a rebuild.
+
+| Purpose | Default path | Attribute |
+| --- | --- | --- |
+| Classes | `GET /lookups/form-classes` | `classes-path` |
+| Courses | `GET /lookups/form-courses` | `courses-path` |
+| States | `GET /lookups/states` | `states-path` |
+| Cities | `GET /lookups/cities` | `cities-path` |
+| Send OTP | `POST /auth/login/send-otp` | `otp-send-path` |
+| Verify OTP | `POST /auth/login/verify-otp` | `otp-verify-path` |
+| Submit form | `POST /forms/vmc-online-lead` | `submit-path` |
+
+**Dependent lookups** pass a Prisma-shaped `where` clause as the `filter` query
+param, matching the CRM's lookup controller:
+
+```
+GET /lookups/form-courses?filter={"form_class_id":6}
+GET /lookups/cities?filter={"state_id":2}
+```
+
+Lookup responses may be either a bare array or `{ data: [...] }`; both are
+accepted. Items are `{ id, name }`.
+
+**OTP flow** (same shape as the CRM login flow):
+
+```
+POST {otp-send-path}    { mobile_number, dial_code }        -> { otp_id }
+POST {otp-verify-path}  { mobile_number, dial_code, otp_id, otp }  -> 2xx
+```
+
+**Submit payload**:
+
+```json
+{
+  "name": "…",
+  "email": "…",
+  "dial_code": "+91",
+  "mobile": "9999999999",
+  "class_id": 6,
+  "course_id": 61,
+  "state_id": 2,
+  "city_id": 21,
+  "otp_id": "…",
+  "mobile_verified": true,
+  "consent": true,
+  "source": "website",
+  "page_url": "https://…"
+}
+```
+
+Errors are read from `{ error }` (falling back to `{ message }`) on any non-2xx
+response, so backend validation messages surface directly in the form.
+
+## Theming
+
+Override the CSS custom properties on the element — they pierce the shadow root:
+
+```html
+<style>
+  vmc-online-lead {
+    --vmc-primary: #3b3663;
+    --vmc-heading: #322c78;
+    --vmc-font: 'Poppins', sans-serif;
+    --vmc-max-width: 560px;
+    --vmc-card-radius: 24px;
+    --vmc-field-height: 56px;
+  }
+</style>
+```
+
+The component does not load webfonts. If the page wants Poppins (the VMC look),
+include it in the host page and it will be inherited.
+
+## Development
+
+```bash
+npm install
+npm run dev        # http://localhost:5173/playground/index.html (.env.development)
+npm run build      # production bundle + dist/types (.env.production)
+npm run build:dev  # same bundle, pointed at localhost — for testing dist/ locally
+npm run typecheck
+```
+
+`playground/index.html` mounts every component and logs every request plus the
+events it fires. Two controls at the top:
+
+- **API base override** — leave empty to use the compiled-in
+  `.env.development` base; fill it in to point the component elsewhere.
+- **Mode**:
+  - `hybrid` (default) — classes, courses and the real OTP flow hit the backend;
+    `/lookups/states`, `/lookups/cities` and `POST /forms/vmc-online-lead` are
+    stubbed, because the first two sit behind `requireAuth` and the third isn't
+    written yet.
+  - `live` — nothing is stubbed.
+  - `mock` — every endpoint is stubbed, no backend needed. OTP is `123456`.
+
+Both can be driven from the URL: `?api=…&mode=mock`.
+
+> The OTP defaults point at `/auth/login/send-otp` + `/auth/login/verify-otp`,
+> which only accept mobiles that already belong to a registered CRM user —
+> an unknown number gets `404 No account found for this mobile`. A public lead
+> form will eventually need its own pair; point `otp-send-path` /
+> `otp-verify-path` at them when they exist.
+
+## Adding a component
+
+1. Write the React component in `src/components/`, taking `{ props, ctx }`.
+2. Register it in `src/index.ts` via `defineElement('vmc-…', Component, attrs)`,
+   listing the attributes that should trigger a re-render.
+3. Mount it in `playground/index.html`.
+
+It lands in the same single bundle automatically.
+
+## Publishing
+
+```bash
+npm version patch
+npm publish            # runs the build via prepublishOnly
+```
+
+Published under the `@coding-blocks` scope with public access.

package/dist/types/components/OnlineLead.d.ts

@@ -0,0 +1,2 @@
+import type { WebComponentProps } from '../lib/defineElement';
+export declare const OnlineLead: ({ props, ctx }: WebComponentProps) => import("react").JSX.Element;

package/dist/types/components/ui.d.ts

@@ -0,0 +1,34 @@
+import type { LookupItem } from '../lib/lookups';
+type InputProps = {
+    name: string;
+    placeholder: string;
+    value: string;
+    onChange: (value: string) => void;
+    type?: string;
+    inputMode?: 'text' | 'numeric' | 'tel' | 'email';
+    maxLength?: number;
+    autoComplete?: string;
+    disabled?: boolean;
+    invalid?: boolean;
+};
+export declare const Input: ({ name, placeholder, value, onChange, type, inputMode, maxLength, autoComplete, disabled, invalid, }: InputProps) => import("react").JSX.Element;
+type SelectProps = {
+    name: string;
+    placeholder: string;
+    value: string;
+    onChange: (value: string) => void;
+    options: LookupItem[];
+    disabled?: boolean;
+    invalid?: boolean;
+    className?: string;
+};
+export declare const Select: ({ name, placeholder, value, onChange, options, disabled, invalid, className, }: SelectProps) => import("react").JSX.Element;
+type OtpInputProps = {
+    length: number;
+    value: string;
+    onChange: (value: string) => void;
+    disabled?: boolean;
+};
+/** Six single-character boxes that behave like one field (paste, arrows, backspace). */
+export declare const OtpInput: ({ length, value, onChange, disabled }: OtpInputProps) => import("react").JSX.Element;
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,2 @@
+export { defineElement } from './lib/defineElement';
+export { API_BASE, DEFAULT_ENDPOINTS } from './lib/config';

package/dist/types/lib/api.d.ts

@@ -0,0 +1,10 @@
+export declare class ApiError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+export type Api = {
+    get: <T>(path: string, params?: Record<string, string | undefined>) => Promise<T>;
+    post: <T>(path: string, body?: unknown) => Promise<T>;
+};
+export declare const createApi: (base: string) => Api;
+export declare const errorMessage: (err: unknown) => string;

package/dist/types/lib/config.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Base URL of the CRM API, compiled in from VITE_API_URL at build time
+ * (.env.development / .env.production). Embedding pages don't pass it; the
+ * optional `api-base` attribute exists only as an escape hatch for testing.
+ */
+export declare const API_BASE: string;
+export type Endpoints = {
+    classesPath: string;
+    coursesPath: string;
+    statesPath: string;
+    citiesPath: string;
+    otpSendPath: string;
+    otpVerifyPath: string;
+    submitPath: string;
+};
+export declare const DEFAULT_ENDPOINTS: Endpoints;
+export declare const OTP_LENGTH = 6;
+export declare const DIAL_CODES: string[];
+export declare const resolveEndpoints: (props: Record<string, string | undefined>) => Endpoints;

package/dist/types/lib/defineElement.d.ts

@@ -0,0 +1,18 @@
+import type { ComponentType } from 'react';
+export type ElementProps = Record<string, string | undefined>;
+export type HostContext = {
+    /** Fire a bubbling, composed DOM event on the host element. */
+    emit: (name: string, detail?: unknown) => void;
+    host: HTMLElement;
+};
+export type WebComponentProps = {
+    props: ElementProps;
+    ctx: HostContext;
+};
+/**
+ * Wraps a React component as a custom element. The UI renders inside a shadow
+ * root with the stylesheet inlined, so a host page's CSS can never leak in and
+ * ours can never leak out. Attributes arrive as camelCased props and re-render
+ * on change.
+ */
+export declare const defineElement: (tag: string, Component: ComponentType<WebComponentProps>, observedAttributes: string[]) => void;

package/dist/types/lib/lookups.d.ts

@@ -0,0 +1,13 @@
+import type { Api } from './api';
+export type LookupItem = {
+    id: number | string;
+    name: string | null;
+};
+/**
+ * Fetches a dropdown list once per (path, filter) pair. `filter` is passed
+ * through as the CRM's Prisma-shaped `filter` query param.
+ */
+export declare const useLookup: (api: Api, path: string, filter?: Record<string, unknown>, enabled?: boolean) => {
+    items: LookupItem[];
+    loading: boolean;
+};

package/dist/types/lib/useMobileVerification.d.ts

@@ -0,0 +1,32 @@
+import { type Api } from './api';
+export type VerificationStatus = 'idle' | 'sending' | 'sent' | 'verifying' | 'verified';
+type Options = {
+    api: Api;
+    sendPath: string;
+    verifyPath: string;
+    dialCode: string;
+    mobile: string;
+    resendSeconds?: number;
+};
+/**
+ * OTP mobile verification, following the CRM login flow:
+ *   POST sendPath   { mobile_number, dial_code }        -> { otp_id }
+ *   POST verifyPath { mobile_number, otp_id, otp, … }   -> 2xx
+ *
+ * Verification is bound to the exact number that was verified — editing the
+ * mobile field drops back to `idle` so a form can never be submitted with an
+ * OTP that belongs to a different number.
+ */
+export declare const useMobileVerification: ({ api, sendPath, verifyPath, dialCode, mobile, resendSeconds, }: Options) => {
+    status: VerificationStatus;
+    otp: string;
+    setOtp: import("react").Dispatch<import("react").SetStateAction<string>>;
+    otpId: string;
+    error: string | null;
+    resendIn: number;
+    sendOtp: () => Promise<boolean>;
+    verifyOtp: () => Promise<boolean>;
+    isVerified: boolean;
+    isPending: boolean;
+};
+export {};