@umituz/web-dashboard 6.0.0 → 6.1.0

package/src/domains/onboarding/components/OnboardingFlow.tsx

@@ -0,0 +1,361 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import type { OnboardingScreen } from '../types/screens';
+import type { OnboardingConfig } from '../types/config';
+import { useOnboardingProgress } from './hooks/useOnboardingProgress';
+import { useOnboardingAnalytics } from './hooks/useOnboardingAnalytics';
+import { OnboardingIntlProvider } from './OnboardingIntl';
+import { ProgressBar } from './shared/ProgressBar';
+import { ScreenContainer } from './shared/ScreenContainer';
+import { AnimationWrapper, type ScreenTransition } from './shared/AnimationWrapper';
+import { OnboardingErrorBoundary } from './shared/OnboardingErrorBoundary';
+import { useOnboardingIntl } from './OnboardingIntl';
+import { checkFlowStructure } from '../validation/flow-structure-check';
+import {
+  WelcomeScreen,
+  GoalQuestionScreen,
+  PainPointsScreen,
+  SocialProofScreen,
+  TinderCardsScreen,
+  PersonalizedSolutionScreen,
+  ComparisonScreen,
+  PreferencesScreen,
+  PermissionPrimingScreen,
+  ProcessingScreen,
+  AppDemoScreen,
+  ValueDeliveryScreen,
+  AccountGateScreen,
+  PaywallScreen,
+} from './screens';
+
+export interface OnboardingFlowProps {
+  config: OnboardingConfig;
+  /** Test/Storybook hook: skip persistence. */
+  ephemeral?: boolean;
+  /** Show progress bar — defaults to true. */
+  showProgress?: boolean;
+  /** Show back button on non-first screens — defaults to true. */
+  allowBack?: boolean;
+  /** Show skip button — defaults to true. Calls config.onSkip on click. */
+  allowSkip?: boolean;
+  /** Custom label for the skip button (overrides `labels.skip`). */
+  skipLabel?: string;
+  /** Transition style between screens — defaults to 'slide'. */
+  transition?: ScreenTransition;
+  /** Override the default error UI from inside the boundary. */
+  renderError?: (error: Error, retry: () => void) => React.ReactNode;
+}
+
+/**
+ * Factory + dispatch table: maps a screen type to its component.
+ * Each screen is responsible for emitting its own data shape via onNext.
+ */
+type ProgressReturn = ReturnType<typeof useOnboardingProgress>;
+
+function renderScreen(
+  screen: OnboardingScreen,
+  progress: ProgressReturn,
+  config: OnboardingConfig,
+  onStepCompleted: (data: unknown) => void,
+) {
+  switch (screen.type) {
+    case 'welcome':
+      return <WelcomeScreen config={screen} onNext={() => onStepCompleted(undefined)} />;
+    case 'goal-question':
+      return (
+        <GoalQuestionScreen
+          config={screen}
+          onNext={(data) => onStepCompleted(data)}
+          initialSelected={
+            (progress.collected[screen.id] as { selected?: string[] } | undefined)?.selected
+          }
+        />
+      );
+    case 'pain-points':
+      return (
+        <PainPointsScreen
+          config={screen}
+          onNext={(data) => onStepCompleted(data)}
+          initialSelected={
+            (progress.collected[screen.id] as { selected?: string[] } | undefined)?.selected
+          }
+        />
+      );
+    case 'social-proof':
+      return <SocialProofScreen config={screen} onNext={() => onStepCompleted(undefined)} />;
+    case 'tinder-cards':
+      return <TinderCardsScreen config={screen} onNext={(data) => onStepCompleted(data)} />;
+    case 'personalized-solution': {
+      // Deterministic: personalization is driven by the pain-points screen's
+      // collected selections — never by "whichever screen happens to have a
+      // `selected` field".
+      const painScreen = config.screens.find((s) => s.type === 'pain-points');
+      const painIds = painScreen
+        ? ((progress.collected[painScreen.id] as { selected?: string[] } | undefined)
+            ?.selected ?? [])
+        : [];
+      return (
+        <PersonalizedSolutionScreen
+          config={{ ...screen, selectedPainPointIds: painIds }}
+          onNext={() => onStepCompleted(undefined)}
+        />
+      );
+    }
+    case 'comparison':
+      return <ComparisonScreen config={screen} onNext={() => onStepCompleted(undefined)} />;
+    case 'preferences':
+      return <PreferencesScreen config={screen} onNext={(data) => onStepCompleted(data)} />;
+    case 'permission-priming':
+      return (
+        <PermissionPrimingScreen
+          config={screen}
+          onNext={(data) => onStepCompleted({ status: data.status })}
+          analytics={config.analytics}
+        />
+      );
+    case 'processing':
+      return <ProcessingScreen config={screen} onComplete={(data) => onStepCompleted(data)} />;
+    case 'app-demo':
+      return <AppDemoScreen config={screen} onNext={(data) => onStepCompleted(data)} />;
+    case 'value-delivery':
+      return <ValueDeliveryScreen config={screen} onNext={() => onStepCompleted(undefined)} />;
+    case 'account-gate':
+      return <AccountGateScreen config={screen} onNext={(data) => onStepCompleted(data)} />;
+    case 'paywall':
+      return (
+        <PaywallScreen
+          config={screen}
+          onNext={(data) => onStepCompleted(data)}
+          analytics={config.analytics}
+        />
+      );
+    default: {
+      // Exhaustive check — TypeScript will flag missing cases at compile time.
+      const _exhaustive: never = screen;
+      return _exhaustive;
+    }
+  }
+}
+
+/** Back/skip affordances. Rendered inside the intl provider so label overrides apply. */
+function FlowFooterNavigation({
+  allowBack,
+  allowSkip,
+  skipLabel,
+  isFirst,
+  onBack,
+  onSkip,
+  visible,
+}: {
+  allowBack: boolean;
+  allowSkip: boolean;
+  skipLabel?: string;
+  isFirst: boolean;
+  onBack: () => void;
+  onSkip: () => void;
+  visible: boolean;
+}) {
+  const { labels } = useOnboardingIntl();
+  if (!visible) return null;
+  return (
+    <div className="flex items-center justify-between">
+      {allowBack && !isFirst ? (
+        <button
+          type="button"
+          onClick={onBack}
+          className="text-sm font-semibold text-[rgb(var(--uob-text-muted))] underline-offset-4 hover:underline"
+        >
+          {labels.back}
+        </button>
+      ) : (
+        <span />
+      )}
+      {allowSkip ? (
+        <button
+          type="button"
+          onClick={onSkip}
+          className="text-sm font-semibold text-[rgb(var(--uob-text-muted))] underline-offset-4 hover:underline"
+        >
+          {skipLabel ?? labels.skip}
+        </button>
+      ) : (
+        <span />
+      )}
+    </div>
+  );
+}
+
+/**
+ * OnboardingFlow — the orchestrator.
+ * Responsibilities (SRP):
+ *  1. Validate the configured flow at mount (fail fast on bad config).
+ *  2. Own the progress state machine via useOnboardingProgress.
+ *  3. Dispatch the active screen via the factory above.
+ *  4. Emit lifecycle analytics (started / step / completed / abandoned — each exactly once).
+ *  5. Provide skip/back affordances and progress.
+ *  6. Wrap everything in an Error Boundary so a single broken screen never breaks the flow.
+ *
+ * Does NOT own:
+ *  - Styling tokens (theme/cn)
+ *  - Analytics provider internals (useOnboardingAnalytics)
+ *  - Storage (useOnboardingProgress)
+ *  - Screen-specific UI (rendered components)
+ */
+export function OnboardingFlow({
+  config,
+  ephemeral = false,
+  showProgress = true,
+  allowBack = true,
+  allowSkip = true,
+  skipLabel,
+  transition = 'slide',
+  renderError,
+}: OnboardingFlowProps) {
+  const progress = useOnboardingProgress({
+    screens: config.screens,
+    storageKey: config.storageKey,
+    ephemeral,
+  });
+  const analytics = useOnboardingAnalytics(config.analytics);
+
+  // Validate configuration once at mount. Surface errors rather than render broken UI.
+  const validation = useMemo(() => checkFlowStructure(config.screens), [config.screens]);
+  useEffect(() => {
+    if (!validation.ok) {
+      throw new Error(`[web-onboarding] invalid flow: ${validation.reason}`);
+    }
+  }, [validation]);
+
+  // Lifecycle analytics — started fires exactly once, even if the consumer
+  // recreates the config object on every render.
+  const startedRef = useRef(false);
+  useEffect(() => {
+    if (startedRef.current) return;
+    startedRef.current = true;
+    analytics.trackEvent({
+      name: 'onboarding_started',
+      category: config.category,
+      timestamp: Date.now(),
+    });
+  }, [analytics, config.category]);
+
+  // Completion — fires exactly once per finished run.
+  const completedRef = useRef(false);
+  useEffect(() => {
+    if (!progress.isFinished || !progress.result) return;
+    if (completedRef.current) return;
+    completedRef.current = true;
+    analytics.trackEvent({
+      name: 'onboarding_completed',
+      durationMs: progress.result.durationMs,
+      timestamp: Date.now(),
+    });
+    config.onComplete?.(progress.result);
+  }, [progress.isFinished, progress.result, analytics, config]);
+
+  // Abandonment — when the flow unmounts without finishing AND the user had
+  // engaged (advanced at least one step), report where they dropped off.
+  // React StrictMode dev double-mounts happen before engagement, so they do not
+  // produce spurious events.
+  const abandonSnapshotRef = useRef({ engaged: false, finished: false, currentStep: 0, startedAt: new Date() });
+  useEffect(() => {
+    abandonSnapshotRef.current = {
+      engaged: progress.completedSteps.length > 0,
+      finished: progress.isFinished,
+      currentStep: progress.currentStep,
+      startedAt: progress.startedAt,
+    };
+  }, [progress.completedSteps.length, progress.isFinished, progress.currentStep, progress.startedAt]);
+  useEffect(() => {
+    return () => {
+      const snapshot = abandonSnapshotRef.current;
+      if (snapshot.finished || !snapshot.engaged) return;
+      analytics.trackEvent({
+        name: 'onboarding_abandoned',
+        lastStepId: config.screens[Math.min(snapshot.currentStep, config.screens.length - 1)]?.id ?? '',
+        durationMs: Math.max(0, Date.now() - snapshot.startedAt.getTime()),
+        timestamp: Date.now(),
+      });
+    };
+    // Config/analytics are read via closure on unmount; the effect intentionally
+    // installs once for the lifetime of the flow.
+  }, []);
+
+  const handleStepCompleted = useCallback(
+    (data: unknown) => {
+      const current = config.screens[progress.currentStep];
+      if (!current) return;
+      analytics.trackEvent({
+        name: 'onboarding_step_completed',
+        stepId: current.id,
+        stepType: current.type,
+        index: progress.currentStep,
+        timestamp: Date.now(),
+      });
+      progress.next(data);
+    },
+    [analytics, config.screens, progress],
+  );
+
+  const handleBack = useCallback(() => {
+    if (progress.isFirst) return;
+    progress.prev();
+  }, [progress]);
+
+  const handleSkip = useCallback(() => {
+    const current = config.screens[progress.currentStep];
+    if (!current) return;
+    analytics.trackEvent({
+      name: 'onboarding_step_skipped',
+      stepId: current.id,
+      index: progress.currentStep,
+      timestamp: Date.now(),
+    });
+    config.onSkip?.();
+  }, [analytics, config, progress.currentStep]);
+
+  const active = config.screens[progress.currentStep];
+  if (!active) {
+    return null;
+  }
+
+  return (
+    <OnboardingIntlProvider labels={config.labels} locale={config.locale}>
+      <OnboardingErrorBoundary {...(renderError ? { renderError } : {})}>
+        <div className="uob-flow">
+          <ScreenContainer
+            header={
+              <>
+                {config.headerSlot}
+                {showProgress && (
+                  <ProgressBar
+                    current={progress.currentStep + 1}
+                    total={progress.totalSteps}
+                    showLabel
+                  />
+                )}
+              </>
+            }
+            footer={
+              <>
+                <FlowFooterNavigation
+                  allowBack={allowBack}
+                  allowSkip={allowSkip && Boolean(config.onSkip)}
+                  skipLabel={skipLabel}
+                  isFirst={progress.isFirst}
+                  onBack={handleBack}
+                  onSkip={handleSkip}
+                  visible={allowBack || allowSkip}
+                />
+                {config.footerSlot}
+              </>
+            }
+          >
+            <AnimationWrapper stepKey={active.id} transition={transition}>
+              {renderScreen(active, progress, config, handleStepCompleted)}
+            </AnimationWrapper>
+          </ScreenContainer>
+        </div>
+      </OnboardingErrorBoundary>
+    </OnboardingIntlProvider>
+  );
+}

package/src/domains/onboarding/components/OnboardingIntl.tsx

@@ -0,0 +1,108 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import type { OnboardingLabels } from '../types/labels';
+
+/** English source strings. Override any subset via `OnboardingConfig.labels`. */
+export const defaultOnboardingLabels: Readonly<OnboardingLabels> = {
+  continueAction: 'Continue',
+  back: 'Back',
+  skip: 'Skip',
+  loading: 'Loading…',
+  stepOfPattern: 'Step {current} of {total}',
+  countOfPattern: '{current} of {total}',
+
+  selectAllThatApply: 'Select all that apply',
+  selectOne: 'Select one',
+  pickUpToPattern: 'Pick up to {max}',
+  pickTheOne: 'Pick the one that bothers you most',
+  tailorExperience: 'Tailor the experience to your needs',
+
+  agree: 'Agree',
+  disagree: 'Disagree',
+  swipeHint: 'Swipe right if you agree, left if you don’t. Or use the arrow keys.',
+  allDone: 'All done — that was easy.',
+
+  withoutUs: 'Without us',
+  withUs: 'With us',
+
+  previous: 'Previous',
+  nextAction: 'Next',
+
+  continueWithResult: 'Continue with my result',
+
+  allowAccess: 'Allow access',
+  permissionRequestFailed: 'Permission request failed',
+
+  continueWithEmail: 'Continue with email',
+  continueWithGoogle: 'Continue with Google',
+  continueWithApple: 'Continue with Apple',
+  continueWithGitHub: 'Continue with GitHub',
+  skipForNow: 'Skip for now',
+  signInFailed: 'Sign-in failed',
+
+  couldNotStartTrial: 'Could not start trial',
+  trialDaysPattern: '{count}-day free trial',
+  trialIntroPattern: '{price} for the first {days} days',
+  cancelAnytimeNote: 'Cancel anytime. No hidden fees.',
+
+  share: 'Share',
+  copied: 'Copied!',
+
+  somethingWentWrong: 'Something went wrong',
+  unexpectedError: 'An unexpected error occurred during onboarding.',
+  tryAgain: 'Try again',
+};
+
+/** Replace `{placeholder}` tokens in a pattern label. */
+export function formatLabel(
+  pattern: string,
+  vars: Record<string, string | number>,
+): string {
+  return pattern.replace(/\{(\w+)\}/g, (match, key: string) =>
+    key in vars ? String(vars[key]) : match,
+  );
+}
+
+/** Labels + locale bundled for React context. */
+export interface OnboardingIntl {
+  labels: Readonly<OnboardingLabels>;
+  /** BCP-47 tag used for locale-aware formatting (e.g. large counts). */
+  locale: string | undefined;
+}
+
+/** Exported for class-based consumers (error boundaries) that cannot call hooks. */
+export const OnboardingIntlContext = createContext<OnboardingIntl>({
+  labels: defaultOnboardingLabels,
+  locale: undefined,
+});
+
+export interface OnboardingIntlProviderProps {
+  labels?: Partial<OnboardingLabels>;
+  locale?: string;
+  children: ReactNode;
+}
+
+/**
+ * Provides label/locale overrides to every screen in the flow. Screens used
+ * standalone (outside `OnboardingFlow`) fall back to the English defaults.
+ */
+export function OnboardingIntlProvider({
+  labels,
+  locale,
+  children,
+}: OnboardingIntlProviderProps) {
+  const value = useMemo<OnboardingIntl>(
+    () => ({
+      labels: labels ? { ...defaultOnboardingLabels, ...labels } : defaultOnboardingLabels,
+      locale,
+    }),
+    [labels, locale],
+  );
+  return (
+    <OnboardingIntlContext.Provider value={value}>{children}</OnboardingIntlContext.Provider>
+  );
+}
+
+/** Access the active labels and locale. English defaults when no provider. */
+export function useOnboardingIntl(): OnboardingIntl {
+  return useContext(OnboardingIntlContext);
+}

package/src/domains/onboarding/components/hooks/index.ts

@@ -0,0 +1,7 @@
+export { useOnboardingProgress } from './useOnboardingProgress';
+export type { UseOnboardingProgressReturn } from './useOnboardingProgress';
+export { usePermissionPriming } from './usePermissionPriming';
+export type { UsePermissionPrimingReturn } from './usePermissionPriming';
+export { useOnboardingAnalytics } from './useOnboardingAnalytics';
+export type { UseOnboardingAnalyticsReturn } from './useOnboardingAnalytics';
+export { useReducedMotion } from './useReducedMotion';

package/src/domains/onboarding/components/hooks/useOnboardingAnalytics.test.tsx

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useOnboardingAnalytics } from './useOnboardingAnalytics';
+import type { OnboardingAnalyticsEvent } from '../../types/config';
+
+const event: OnboardingAnalyticsEvent = {
+  name: 'onboarding_step_completed',
+  stepId: 'goal',
+  stepType: 'goal-question',
+  index: 1,
+  timestamp: 0,
+};
+
+describe('useOnboardingAnalytics', () => {
+  it('fires events through the custom tracker when enabled', () => {
+    const tracker = vi.fn();
+    const { result } = renderHook(() =>
+      useOnboardingAnalytics({ trackEvents: true, provider: 'custom', customTracker: tracker }),
+    );
+    result.current.trackEvent(event);
+    expect(tracker).toHaveBeenCalledExactlyOnceWith(event);
+  });
+
+  it('trackFunnel is an alias of trackEvent (same dispatch)', () => {
+    const tracker = vi.fn();
+    const { result } = renderHook(() =>
+      useOnboardingAnalytics({ trackEvents: true, provider: 'custom', customTracker: tracker }),
+    );
+    result.current.trackFunnel(event);
+    expect(tracker).toHaveBeenCalledExactlyOnceWith(event);
+  });
+
+  it('never dispatches when trackEvents is false', () => {
+    const tracker = vi.fn();
+    const { result } = renderHook(() =>
+      useOnboardingAnalytics({ trackEvents: false, provider: 'custom', customTracker: tracker }),
+    );
+    result.current.trackEvent(event);
+    expect(tracker).not.toHaveBeenCalled();
+    expect(result.current.enabled).toBe(false);
+  });
+
+  it('never dispatches without a config at all', () => {
+    const { result } = renderHook(() => useOnboardingAnalytics(undefined));
+    expect(() => result.current.trackEvent(event)).not.toThrow();
+    expect(result.current.enabled).toBe(false);
+  });
+
+  it('keeps callback identity stable across re-renders', () => {
+    const tracker = vi.fn();
+    const { result, rerender } = renderHook(() =>
+      useOnboardingAnalytics({ trackEvents: true, provider: 'custom', customTracker: tracker }),
+    );
+    const first = result.current.trackEvent;
+    rerender();
+    expect(result.current.trackEvent).toBe(first);
+  });
+
+  it('survives a throwing tracker (analytics is an observation channel)', () => {
+    const error = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    const { result } = renderHook(() =>
+      useOnboardingAnalytics({
+        trackEvents: true,
+        provider: 'custom',
+        customTracker: () => {
+          throw new Error('boom');
+        },
+      }),
+    );
+    expect(() => result.current.trackEvent(event)).not.toThrow();
+    expect(error).toHaveBeenCalled();
+    error.mockRestore();
+  });
+});

package/src/domains/onboarding/components/hooks/useOnboardingAnalytics.ts

@@ -0,0 +1,62 @@
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+import type {
+  AnalyticsConfig,
+  OnboardingAnalyticsEvent,
+} from '../../types/config';
+import { trackOnboardingEvent } from '../../utils/analytics-dispatch';
+
+export interface UseOnboardingAnalyticsReturn {
+  trackEvent: (event: OnboardingAnalyticsEvent) => void;
+  /** Alias of `trackEvent` kept for call-site readability on funnel events. */
+  trackFunnel: (event: OnboardingAnalyticsEvent) => void;
+  enabled: boolean;
+}
+
+/**
+ * Hook façade for analytics dispatch.
+ * Single responsibility: provide a stable callback that honors the analytics config.
+ *
+ * The returned callbacks are identity-stable across re-renders even when the
+ * consumer recreates the `config` object every render — event handlers and
+ * effects that depend on them do not re-fire spuriously. The latest config is
+ * read through a ref synchronized after each commit.
+ *
+ * Dispatch never throws: analytics failures are logged by the dispatcher and
+ * dropped (see `utils/analytics-dispatch`).
+ */
+export function useOnboardingAnalytics(config: AnalyticsConfig | undefined): UseOnboardingAnalyticsReturn {
+  const configRef = useRef(config);
+  useEffect(() => {
+    configRef.current = config;
+  }, [config]);
+
+  const enabled = config?.trackEvents === true;
+
+  const dispatch = useCallback(
+    (event: OnboardingAnalyticsEvent) => {
+      if (!enabled) return;
+      const current = configRef.current;
+      if (!current) return;
+      trackOnboardingEvent(event, {
+        provider: current.provider,
+        customTracker: current.customTracker,
+      });
+    },
+    [enabled],
+  );
+
+  const trackEvent = useCallback(
+    (event: OnboardingAnalyticsEvent) => dispatch(event),
+    [dispatch],
+  );
+
+  const trackFunnel = useCallback(
+    (event: OnboardingAnalyticsEvent) => dispatch(event),
+    [dispatch],
+  );
+
+  return useMemo(
+    () => ({ trackEvent, trackFunnel, enabled }),
+    [trackEvent, trackFunnel, enabled],
+  );
+}