@igamingcareer/igaming-components 1.0.95 → 1.0.97

package/Readme.md

@@ -336,6 +336,156 @@ export function CompanyDetailWithRouter({ data }: { data: CompanyDetailData }) {
 }
 ```
 
+## Onboarding flow (Dashboard + OnboardingPopup)
+
+The new `Onboarding` folder includes components and helpers for managing the full onboarding lifecycle:
+
+- **Dashboard onboarding preview** (inside `DashboardOverview`)
+  - Uses `DashboardOnboardingSection` to show a compact, actionable checklist.
+  - Data is driven by `OnboardingStep[]`, `emailVerified`, `profileComplete`, and `onboardingProgress`.
+- **Full onboarding modal**
+  - `OnboardingPopup` renders `OnboardingModal` + `OnboardingDashboard` and manages state via `OnboardingProvider`.
+  - Use it for a blocking or reminder-style onboarding flow.
+
+### Key backend flags
+
+Fetch the flags from your backend (for example `/api/auth/me`) and map them into steps using `mapBackendFlagsToSteps`:
+
+```ts
+export interface OnboardingBackendFlags {
+  email_verified: boolean;
+  email_verified_at?: string | null;
+  profile_complete: boolean;
+  onboarding_steps: OnboardingStepId[];
+}
+```
+
+These flags define the onboarding state:
+
+1. **Registration started** → `email_verified = false`, `profile_complete = false`.
+2. **Email verified** → `email_verified = true`, `profile_complete = false` (profile step becomes `pending`).
+3. **Onboarding completed** → `email_verified = true`, `profile_complete = true` (all steps `complete`).
+
+### Dashboard integration (Next.js)
+
+Pass onboarding data into `Dashboard` so the overview can render the compact onboarding section. Use the helper
+functions to keep the UI in sync with your backend.
+
+```tsx
+import {
+  Dashboard,
+  type OnboardingBackendFlags,
+  mapBackendFlagsToSteps,
+  calculateOnboardingProgress,
+} from "@igamingcareer/igaming-components";
+
+export function DashboardPage({ data }: { data: DashboardData }) {
+  const flags: OnboardingBackendFlags = data.onboardingFlags;
+  const steps = mapBackendFlagsToSteps(flags);
+  const progress = calculateOnboardingProgress(steps);
+
+  const handleOnboardingAction = (actionId: string, stepId: string) => {
+    // actionId values: "resend_verification" | "edit_profile" | custom
+    // Your routing or API calls here (Next.js router, toast, etc.)
+    console.log("onboarding action", actionId, stepId);
+  };
+
+  return (
+    <Dashboard
+      user={data.user}
+      profileData={data.profile}
+      alerts={data.alerts}
+      snapshot={data.snapshot}
+      feedItems={data.feedItems}
+      onUpdateProfile={data.onUpdateProfile}
+      onboardingSteps={steps}
+      emailVerified={flags.email_verified}
+      profileComplete={flags.profile_complete}
+      onboardingProgress={progress}
+      onOnboardingAction={handleOnboardingAction}
+      onOpenOnboarding={() => console.log("open full onboarding modal")}
+    />
+  );
+}
+```
+
+### Onboarding popup (full flow)
+
+Wrap your app (or the page that needs onboarding) with `OnboardingProvider`. Trigger the modal via the context
+API (`openModal`) when registration starts or when the user returns and still has pending steps.
+
+```tsx
+import { useEffect } from "react";
+import {
+  OnboardingProvider,
+  OnboardingPopup,
+  useOnboardingContext,
+  type OnboardingBackendFlags,
+} from "@igamingcareer/igaming-components";
+
+function OnboardingGate({ flags }: { flags: OnboardingBackendFlags }) {
+  const {
+    openModal,
+    updateFromBackend,
+    isComplete,
+    isDismissed,
+  } = useOnboardingContext();
+
+  useEffect(() => {
+    updateFromBackend(flags);
+
+    // Registration started or incomplete onboarding: prompt the user.
+    if (!isComplete && !isDismissed) {
+      openModal();
+    }
+  }, [flags, isComplete, isDismissed, openModal, updateFromBackend]);
+
+  return (
+    <OnboardingPopup
+      onComplete={() => console.log("onboarding finished")}
+      onClose={() => console.log("onboarding dismissed/closed")}
+    />
+  );
+}
+
+export function AppRoot({ flags }: { flags: OnboardingBackendFlags }) {
+  return (
+    <OnboardingProvider>
+      <OnboardingGate flags={flags} />
+      {/* rest of your app */}
+    </OnboardingProvider>
+  );
+}
+```
+
+### Action handling checklist
+
+Use these hooks to connect the onboarding UI to your Next.js app:
+
+- **Registration started**
+  - Load backend flags and call `updateFromBackend(flags)`.
+  - Call `openModal()` to show `OnboardingPopup`.
+- **Email verified**
+  - Update backend flags (or re-fetch `/api/auth/me`) and call `updateFromBackend(flags)`.
+  - The profile step changes from `blocked` to `pending`.
+- **Onboarding completed**
+  - When the profile is complete, update flags so all steps are `complete`.
+  - `OnboardingPopup` will show the completion state and invoke `onComplete` when closed.
+
+### Component options
+
+- `DashboardOnboardingSection`
+  - `steps`, `progress`, `emailVerified`, `profileComplete`, `onActionClick`, `onOpenFullOnboarding`
+- `OnboardingDashboard`
+  - `steps`, `progress`, `variant` (`"compact"` or `"full"`), `onActionClick`
+- `OnboardingChecklist`
+  - `steps`, `variant` (`"compact"` or `"full"`), `onActionClick`
+- `OnboardingModal`
+  - `open`, `onOpenChange`, `steps`, `emailVerified`, `profileComplete`, `onActionClick`, `onResendVerification`,
+    `onChangeEmail`, `onDismiss`, `dismissLabel`, `title`, `description`
+- `OnboardingPopup`
+  - `onComplete`, `onClose` (state is sourced from `OnboardingProvider`)
+
 
 ## Dashboard tab routing events