@umituz/web-dashboard 6.0.0 → 6.2.0

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

@@ -0,0 +1,49 @@
+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;
+    trackFunnel: (event: OnboardingAnalyticsEvent) => void;
+  enabled: boolean;
+}
+
+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],
+  );
+}

package/src/domains/onboarding/hooks/useOnboardingProgress.test.tsx

@@ -0,0 +1,150 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useOnboardingProgress } from './useOnboardingProgress';
+import { defaultStorageKey } from '../utils/default-storage-key';
+import type { OnboardingScreen } from '../types/screens';
+
+function makeScreens(count: number): OnboardingScreen[] {
+  return Array.from({ length: count }, (_, i) => ({
+    id: `s${i}`,
+    type: 'welcome',
+    title: `Step ${i}`,
+  }));
+}
+
+beforeEach(() => {
+  window.localStorage.clear();
+});
+
+describe('useOnboardingProgress — state machine (§1.1, §1.2)', () => {
+  it('starts on the first screen', () => {
+    const { result } = renderHook(() =>
+      useOnboardingProgress({ screens: makeScreens(3) }),
+    );
+    expect(result.current.currentStep).toBe(0);
+    expect(result.current.isFirst).toBe(true);
+    expect(result.current.isLast).toBe(false);
+    expect(result.current.isFinished).toBe(false);
+    expect(result.current.totalSteps).toBe(3);
+  });
+
+  it('advances, records completion, and collects data', () => {
+    const { result } = renderHook(() =>
+      useOnboardingProgress({ screens: makeScreens(3), ephemeral: true }),
+    );
+    act(() => result.current.next({ selected: ['x'] }));
+    expect(result.current.currentStep).toBe(1);
+    expect(result.current.completedSteps).toEqual(['s0']);
+    expect(result.current.collected).toEqual({ s0: { selected: ['x'] } });
+    expect(result.current.isFirst).toBe(false);
+  });
+
+  it('retreats with prev and stops at the first screen', () => {
+    const { result } = renderHook(() =>
+      useOnboardingProgress({ screens: makeScreens(3), ephemeral: true }),
+    );
+    act(() => result.current.next());
+    act(() => result.current.next());
+    act(() => result.current.prev());
+    expect(result.current.currentStep).toBe(1);
+    act(() => result.current.prev());
+    act(() => result.current.prev()); // below zero — must clamp
+    expect(result.current.currentStep).toBe(0);
+  });
+
+  it('finish() marks the flow finished and returns a result', () => {
+    const { result } = renderHook(() =>
+      useOnboardingProgress({ screens: makeScreens(2), ephemeral: true }),
+    );
+    act(() => result.current.next());
+    let returned: ReturnType<typeof result.current.finish> | undefined;
+    act(() => {
+      returned = result.current.finish({ final: true });
+    });
+    expect(result.current.isFinished).toBe(true);
+    expect(result.current.result).not.toBeNull();
+    expect(result.current.result?.durationMs).toBeGreaterThanOrEqual(0);
+    expect(returned?.collected).toEqual({ s1: { final: true } });
+  });
+
+  it('next() on the last screen finishes the flow', () => {
+    const { result } = renderHook(() =>
+      useOnboardingProgress({ screens: makeScreens(2), ephemeral: true }),
+    );
+    act(() => result.current.next());
+    act(() => result.current.next()); // last screen -> finish
+    expect(result.current.isFinished).toBe(true);
+    expect(result.current.completedSteps).toEqual(['s0', 's1']);
+  });
+
+  it('reset() rewinds and clears stored progress (§16.1)', () => {
+    const { result } = renderHook(() =>
+      useOnboardingProgress({ screens: makeScreens(3), storageKey: 'k' }),
+    );
+    act(() => result.current.next({ selected: ['x'] }));
+    expect(JSON.parse(localStorage.getItem('k') ?? '{}').currentStep).toBe(1);
+    act(() => result.current.reset());
+    expect(result.current.currentStep).toBe(0);
+    expect(result.current.completedSteps).toEqual([]);
+    expect(result.current.collected).toEqual({});
+    // The stale checkpoint is gone; the persist effect re-saves a fresh one.
+    const stored = JSON.parse(localStorage.getItem('k') ?? 'null');
+    expect(stored).not.toBeNull();
+    expect(stored.currentStep).toBe(0);
+    expect(stored.completedSteps).toEqual([]);
+  });
+
+  it('goTo() clamps out-of-range indices', () => {
+    const { result } = renderHook(() =>
+      useOnboardingProgress({ screens: makeScreens(3), ephemeral: true }),
+    );
+    act(() => result.current.goTo(99));
+    expect(result.current.currentStep).toBe(2);
+    act(() => result.current.goTo(-5));
+    expect(result.current.currentStep).toBe(0);
+  });
+});
+
+describe('useOnboardingProgress — persistence (§1.4, §1.5, §1.6)', () => {
+  it('persists after each transition and rehydrates on a fresh mount', () => {
+    const screens = makeScreens(4);
+    const first = renderHook(() => useOnboardingProgress({ screens, storageKey: 'resume' }));
+    act(() => first.result.current.next({ selected: ['a'] }));
+    act(() => first.result.current.next());
+    first.unmount();
+    expect(JSON.parse(localStorage.getItem('resume') ?? '{}').currentStep).toBe(2);
+
+    const second = renderHook(() => useOnboardingProgress({ screens, storageKey: 'resume' }));
+    expect(second.result.current.currentStep).toBe(2);
+    expect(second.result.current.collected).toEqual({ s0: { selected: ['a'] } });
+    second.unmount();
+  });
+
+  it('never touches storage in ephemeral mode', () => {
+    const { result } = renderHook(() =>
+      useOnboardingProgress({ screens: makeScreens(2), ephemeral: true }),
+    );
+    act(() => result.current.next());
+    expect(localStorage.getItem(defaultStorageKey)).toBeNull();
+  });
+
+  it('rehydration past the end of a shortened flow starts fresh', () => {
+    // Progress stored for 4 screens; the app now ships 2. currentStep=3 is
+    // out of bounds and must not be restored.
+    localStorage.setItem(
+      'short',
+      JSON.stringify({
+        version: 1,
+        currentStep: 3,
+        completedSteps: ['s0', 's1', 's2'],
+        collected: {},
+        startedAt: new Date().toISOString(),
+        lastUpdated: new Date().toISOString(),
+      }),
+    );
+    const { result } = renderHook(() =>
+      useOnboardingProgress({ screens: makeScreens(2), storageKey: 'short' }),
+    );
+    expect(result.current.currentStep).toBe(0);
+  });
+});

package/src/domains/onboarding/hooks/useOnboardingProgress.ts

@@ -0,0 +1,249 @@
+import { useCallback, useEffect, useMemo, useReducer } from 'react';
+import type { OnboardingScreen } from '../types/screens';
+import type { OnboardingResult } from '../types/config';
+import {
+  advanceStepIndex,
+  clampStepIndex,
+  retreatStepIndex,
+} from '../calc/step-index-clamp';
+import {
+  computeProgressFraction,
+  computeRemainingSteps,
+} from '../calc/progress-percentage';
+import {
+  buildOnboardingResult,
+  clearOnboardingProgress,
+  loadOnboardingProgress,
+  saveOnboardingProgress,
+} from '../utils/local-storage-bridge';
+
+interface ProgressState {
+  currentStep: number;
+  totalSteps: number;
+  completedSteps: ReadonlyArray<string>;
+  collected: Record<string, unknown>;
+  startedAt: Date;
+  lastUpdated: Date;
+  finishedAt: Date | null;
+}
+
+type ProgressAction =
+  | { type: 'next'; currentScreen: OnboardingScreen; data?: unknown }
+  | { type: 'previous' }
+  | { type: 'goto'; index: number }
+  | { type: 'reset' }
+  | { type: 'finish'; currentScreen: OnboardingScreen; data?: unknown }
+  | { type: 'hydrate'; state: ProgressState };
+
+function reducer(state: ProgressState, action: ProgressAction): ProgressState {
+  switch (action.type) {
+    case 'next': {
+      const completed = state.completedSteps.includes(action.currentScreen.id)
+        ? state.completedSteps
+        : [...state.completedSteps, action.currentScreen.id];
+      const collected =
+        action.data !== undefined
+          ? { ...state.collected, [action.currentScreen.id]: action.data }
+          : state.collected;
+      return {
+        ...state,
+        currentStep: advanceStepIndex(state.currentStep, state.totalSteps),
+        completedSteps: completed,
+        collected,
+        lastUpdated: new Date(),
+      };
+    }
+    case 'previous':
+      return { ...state, currentStep: retreatStepIndex(state.currentStep), lastUpdated: new Date() };
+    case 'goto':
+      return {
+        ...state,
+        currentStep: clampStepIndex(action.index, state.totalSteps),
+        lastUpdated: new Date(),
+      };
+    case 'finish': {
+      const completed = state.completedSteps.includes(action.currentScreen.id)
+        ? state.completedSteps
+        : [...state.completedSteps, action.currentScreen.id];
+      const collected =
+        action.data !== undefined
+          ? { ...state.collected, [action.currentScreen.id]: action.data }
+          : state.collected;
+      return {
+        ...state,
+        completedSteps: completed,
+        collected,
+        finishedAt: new Date(),
+        lastUpdated: new Date(),
+      };
+    }
+    case 'reset':
+      return {
+        ...state,
+        currentStep: 0,
+        completedSteps: [],
+        collected: {},
+        finishedAt: null,
+        lastUpdated: new Date(),
+        startedAt: new Date(),
+      };
+    case 'hydrate':
+      return action.state;
+    default:
+      return state;
+  }
+}
+
+interface UseOnboardingProgressOptions {
+  screens: ReadonlyArray<OnboardingScreen>;
+  storageKey?: string;
+    ephemeral?: boolean;
+}
+
+export interface UseOnboardingProgressReturn {
+  currentStep: number;
+  totalSteps: number;
+  progress: number;   completedSteps: ReadonlyArray<string>;
+  collected: Record<string, unknown>;
+  remainingSteps: number;
+  isFirst: boolean;
+  isLast: boolean;
+  isFinished: boolean;
+    startedAt: Date;
+  next: (data?: unknown) => void;
+  prev: () => void;
+  goTo: (index: number) => void;
+  reset: () => void;
+  finish: (data?: unknown) => OnboardingResult;
+  result: OnboardingResult | null;
+}
+
+export function useOnboardingProgress(
+  options: UseOnboardingProgressOptions,
+): UseOnboardingProgressReturn {
+  const { screens, storageKey, ephemeral = false } = options;
+  const totalSteps = screens.length;
+
+  const initialState = useMemo<ProgressState>(() => {
+    const now = new Date();
+    if (!ephemeral) {
+      const restored = loadOnboardingProgress(storageKey);
+      if (restored && restored.currentStep < totalSteps) {
+        return {
+          currentStep: restored.currentStep,
+          totalSteps,
+          completedSteps: restored.completedSteps,
+          collected: restored.collected,
+          startedAt: restored.startedAt,
+          lastUpdated: restored.lastUpdated,
+          finishedAt: null,
+        };
+      }
+    }
+    return {
+      currentStep: 0,
+      totalSteps,
+      completedSteps: [],
+      collected: {},
+      startedAt: now,
+      lastUpdated: now,
+      finishedAt: null,
+    };
+          }, [totalSteps, storageKey, ephemeral]);
+
+  const [state, dispatch] = useReducer(reducer, initialState);
+
+    useEffect(() => {
+    if (ephemeral) return;
+    saveOnboardingProgress(storageKey, {
+      currentStep: state.currentStep,
+      completedSteps: state.completedSteps,
+      collected: state.collected,
+      startedAt: state.startedAt,
+      lastUpdated: state.lastUpdated,
+    });
+  }, [
+    ephemeral,
+    storageKey,
+    state.currentStep,
+    state.completedSteps,
+    state.collected,
+    state.startedAt,
+    state.lastUpdated,
+  ]);
+
+  const next = useCallback(
+    (data?: unknown) => {
+      const currentScreen = screens[state.currentStep];
+      if (!currentScreen) return;
+      if (state.currentStep === state.totalSteps - 1) {
+        dispatch({ type: 'finish', currentScreen, data });
+      } else {
+        dispatch({ type: 'next', currentScreen, data });
+      }
+    },
+    [screens, state.currentStep, state.totalSteps],
+  );
+
+  const prev = useCallback(() => dispatch({ type: 'previous' }), []);
+  const goTo = useCallback((index: number) => dispatch({ type: 'goto', index }), []);
+  const reset = useCallback(() => {
+    if (!ephemeral) clearOnboardingProgress(storageKey);
+    dispatch({ type: 'reset' });
+  }, [ephemeral, storageKey]);
+
+  const finish = useCallback(
+    (data?: unknown) => {
+      const currentScreen = screens[state.currentStep];
+      if (currentScreen) dispatch({ type: 'finish', currentScreen, data });
+      const finishedAt = new Date();
+      return buildOnboardingResult({
+        completedSteps:
+          currentScreen && !state.completedSteps.includes(currentScreen.id)
+            ? [...state.completedSteps, currentScreen.id]
+            : state.completedSteps,
+        collected:
+          currentScreen && data !== undefined
+            ? { ...state.collected, [currentScreen.id]: data }
+            : state.collected,
+        startedAt: state.startedAt,
+        finishedAt,
+      });
+    },
+    [screens, state.currentStep, state.completedSteps, state.collected, state.startedAt],
+  );
+
+  const progress = computeProgressFraction(state.currentStep, state.totalSteps);
+  const remainingSteps = computeRemainingSteps(state.currentStep, state.totalSteps);
+  const isFirst = state.currentStep === 0;
+  const isLast = state.currentStep === state.totalSteps - 1;
+  const isFinished = state.finishedAt !== null;
+  const result =
+    state.finishedAt !== null
+      ? buildOnboardingResult({
+          completedSteps: state.completedSteps,
+          collected: state.collected,
+          startedAt: state.startedAt,
+          finishedAt: state.finishedAt,
+        })
+      : null;
+
+  return {
+    currentStep: state.currentStep,
+    totalSteps,
+    progress,
+    completedSteps: state.completedSteps,
+    collected: state.collected,
+    remainingSteps,
+    isFirst,
+    isLast,
+    isFinished,
+    startedAt: state.startedAt,
+    next,
+    prev,
+    goTo,
+    reset,
+    finish,
+    result,
+  };
+}

package/src/domains/onboarding/hooks/usePermissionPriming.ts

@@ -0,0 +1,45 @@
+import { useCallback, useEffect, useState } from 'react';
+import type { PermissionStatus, PermissionType } from '../types/screens';
+import {
+  isPermissionDecided,
+  isPermissionUnsupported,
+} from '../predicates/permission-granted';
+import { queryPermissionStatus, requestPermission } from '../utils/permission-bridge';
+
+export interface UsePermissionPrimingReturn {
+  status: PermissionStatus;
+  isRequesting: boolean;
+  requestPermission: () => Promise<PermissionStatus>;
+  reset: () => void;
+}
+
+export function usePermissionPriming(permission: PermissionType): UsePermissionPrimingReturn {
+  const [status, setStatus] = useState<PermissionStatus>('prompt');
+  const [isRequesting, setIsRequesting] = useState(false);
+
+  useEffect(() => {
+    let cancelled = false;
+    queryPermissionStatus(permission).then((initial) => {
+      if (!cancelled) setStatus(initial);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [permission]);
+
+  const request = useCallback(async (): Promise<PermissionStatus> => {
+    if (isPermissionDecided(status) || isPermissionUnsupported(status)) return status;
+    setIsRequesting(true);
+    try {
+      const next = await requestPermission(permission);
+      setStatus(next);
+      return next;
+    } finally {
+      setIsRequesting(false);
+    }
+  }, [permission, status]);
+
+  const reset = useCallback(() => setStatus('prompt'), []);
+
+  return { status, isRequesting, requestPermission: request, reset };
+}

package/src/domains/onboarding/hooks/useReducedMotion.ts

@@ -0,0 +1,19 @@
+import { useEffect, useState } from 'react';
+
+export function useReducedMotion(): boolean {
+  const getInitial = (): boolean => {
+    if (typeof window === 'undefined' || !window.matchMedia) return false;
+    return window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  };
+  const [reduced, setReduced] = useState<boolean>(getInitial);
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || !window.matchMedia) return;
+    const mql = window.matchMedia('(prefers-reduced-motion: reduce)');
+    const handler = (e: MediaQueryListEvent) => setReduced(e.matches);
+    mql.addEventListener('change', handler);
+    return () => mql.removeEventListener('change', handler);
+  }, []);
+
+  return reduced;
+}

package/src/domains/onboarding/index.ts

@@ -0,0 +1,153 @@
+export { OnboardingFlow } from './components/OnboardingFlow';
+export type { OnboardingFlowProps } from './components/OnboardingFlow';
+
+export {
+  OnboardingIntlProvider,
+  OnboardingIntlContext,
+  useOnboardingIntl,
+  defaultOnboardingLabels,
+  formatLabel,
+} from './components/OnboardingIntl';
+export type { OnboardingIntl, OnboardingIntlProviderProps } from './components/OnboardingIntl';
+
+export {
+  WelcomeScreen,
+  GoalQuestionScreen,
+  PainPointsScreen,
+  SocialProofScreen,
+  TinderCardsScreen,
+  PersonalizedSolutionScreen,
+  ComparisonScreen,
+  PreferencesScreen,
+  PermissionPrimingScreen,
+  ProcessingScreen,
+  AppDemoScreen,
+  ValueDeliveryScreen,
+  AccountGateScreen,
+  PaywallScreen,
+} from './components/screens';
+
+export { ProgressBar } from './components/ProgressBar';
+export type { ProgressBarProps } from './components/ProgressBar';
+export { QuestionWrapper } from './components/QuestionWrapper';
+export type { QuestionWrapperProps } from './components/QuestionWrapper';
+export { SwipeCard } from './components/SwipeCard';
+export type { SwipeCardProps } from './components/SwipeCard';
+export { AnimationWrapper } from './components/AnimationWrapper';
+export type { AnimationWrapperProps, ScreenTransition } from './components/AnimationWrapper';
+export { ScreenContainer } from './components/ScreenContainer';
+export type { ScreenContainerProps } from './components/ScreenContainer';
+export { PrimaryButton } from './components/PrimaryButton';
+export type { PrimaryButtonProps } from './components/PrimaryButton';
+export { OnboardingErrorBoundary } from './components/OnboardingErrorBoundary';
+export type { OnboardingErrorBoundaryProps } from './components/OnboardingErrorBoundary';
+
+export {
+  useOnboardingProgress,
+  usePermissionPriming,
+  useOnboardingAnalytics,
+  useReducedMotion,
+} from './hooks';
+export type {
+  UseOnboardingProgressReturn,
+  UsePermissionPrimingReturn,
+  UseOnboardingAnalyticsReturn,
+} from './hooks';
+
+export {
+  healthOnboardingTemplate,
+  artOnboardingTemplate,
+  videoOnboardingTemplate,
+  platformOnboardingTemplate,
+  withDefaultDemo,
+  defaultDemoResult,
+  TemplateDemoFallback,
+} from './templates';
+export type { TemplateDemoResult } from './templates';
+
+export {
+  computeProgressFraction,
+  computeProgressPercentage,
+  computeRemainingSteps,
+  clampStepIndex,
+  advanceStepIndex,
+  retreatStepIndex,
+  SWIPE_DECISION_THRESHOLD_PX,
+  SWIPE_ROTATION_RANGE,
+  SWIPE_ROTATION_VALUES,
+  SWIPE_LEFT_OPACITY_INPUT,
+  SWIPE_LEFT_OPACITY_VALUES,
+  SWIPE_RIGHT_OPACITY_INPUT,
+  SWIPE_RIGHT_OPACITY_VALUES,
+  didCrossRightSwipeThreshold,
+  didCrossLeftSwipeThreshold,
+  getCardEnterInitial,
+  getCardEnterAnimate,
+  getCardEnterExit,
+  getCardTransitionDurationMs,
+  resolveSliderBounds,
+  areSliderBoundsValid,
+  clampValueToBounds,
+  splitTotalDuration,
+  getDefaultStepDurationMs,
+  formatCountWithLocale,
+  elapsedMillis,
+} from './calc';
+export type { CardMotionState } from './calc';
+
+export {
+  checkFlowStructure,
+  checkScreenConfig,
+  checkStoredProgress,
+  getRecognizedScreenTypes,
+  isRecognizedPermissionStatus,
+  normalizePermissionStatus,
+} from './validation';
+export type { ValidationOutcome, StoredProgressShape, StoredProgressOutcome } from './validation';
+
+export {
+  isPermissionGranted,
+  isPermissionDenied,
+  isPermissionPrompt,
+  isPermissionUnsupported,
+  isPermissionDecided,
+  doesBrowserSupportNotifications,
+  doesBrowserSupportMediaCapture,
+  doesBrowserSupportGeolocation,
+  isRuntimeSupportMissing,
+  isLocalStorageAvailable,
+  doesIconNameResolve,
+  getRegisteredIconNames,
+  resolveIconByName,
+  hasOnRequest,
+  hasOnAccept,
+  hasOnSignIn,
+  accountGateAllowsSkip,
+  screenEmitsData,
+} from './predicates';
+
+export {
+  trackOnboardingEvent,
+  dispatchAnalyticsEvent,
+  saveOnboardingProgress,
+  loadOnboardingProgress,
+  clearOnboardingProgress,
+  buildOnboardingResult,
+  queryPermissionStatus,
+  requestPermission,
+  defaultStorageKey,
+} from './utils';
+export type { RehydratedProgress } from './utils';
+
+export type {
+  OnboardingScreen,
+  OnboardingScreenType,
+  OnboardingOption,
+  OnboardingConfig,
+  OnboardingCategory,
+  OnboardingLabels,
+  AnalyticsConfig,
+  AnalyticsProvider,
+  OnboardingAnalyticsEvent,
+  OnboardingResult,
+} from './types';

package/src/domains/onboarding/predicates/has-handler.ts

@@ -0,0 +1,21 @@
+import type {
+  AccountGateScreenConfig,
+  PaywallScreenConfig,
+  PermissionPrimingScreenConfig,
+} from '../types/screens';
+
+export function hasOnRequest(config: PermissionPrimingScreenConfig): boolean {
+  return typeof config.onRequest === 'function';
+}
+
+export function hasOnAccept(config: PaywallScreenConfig): boolean {
+  return typeof config.onAccept === 'function';
+}
+
+export function hasOnSignIn(config: AccountGateScreenConfig): boolean {
+  return typeof config.onSignIn === 'function';
+}
+
+export function accountGateAllowsSkip(config: AccountGateScreenConfig): boolean {
+  return config.optional === true;
+}