@umituz/web-dashboard 6.0.0 → 6.2.0

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

@@ -0,0 +1,313 @@
+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 './ProgressBar';
+import { ScreenContainer } from './ScreenContainer';
+import { AnimationWrapper, type ScreenTransition } from './AnimationWrapper';
+import { OnboardingErrorBoundary } from './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;
+  ephemeral?: boolean;
+  showProgress?: boolean;
+  allowBack?: boolean;
+  allowSkip?: boolean;
+  skipLabel?: string;
+  transition?: ScreenTransition;
+  renderError?: (error: Error, retry: () => void) => React.ReactNode;
+}
+
+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': {
+      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: {
+      const _exhaustive: never = screen;
+      return _exhaustive;
+    }
+  }
+}
+
+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="udb-onb-nav">
+      {allowBack && !isFirst ? (
+        <button type="button" onClick={onBack} className="udb-onb-link">
+          {labels.back}
+        </button>
+      ) : (
+        <span />
+      )}
+      {allowSkip ? (
+        <button type="button" onClick={onSkip} className="udb-onb-link">
+          {skipLabel ?? labels.skip}
+        </button>
+      ) : (
+        <span />
+      )}
+    </div>
+  );
+}
+
+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);
+
+  const validation = useMemo(() => checkFlowStructure(config.screens), [config.screens]);
+  useEffect(() => {
+    if (!validation.ok) {
+      throw new Error(`[onboarding] invalid flow: ${validation.reason}`);
+    }
+  }, [validation]);
+
+  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]);
+
+  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: unmount without finishing AND after engaging at least one step.
+  // StrictMode dev double-mounts happen before engagement, so no 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(),
+      });
+    };
+  }, []);
+
+  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="udb-onb">
+          <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,98 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import type { OnboardingLabels } from '../types/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',
+};
+
+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,
+  );
+}
+
+export interface OnboardingIntl {
+  labels: Readonly<OnboardingLabels>;
+    locale: string | undefined;
+}
+
+export const OnboardingIntlContext = createContext<OnboardingIntl>({
+  labels: defaultOnboardingLabels,
+  locale: undefined,
+});
+
+export interface OnboardingIntlProviderProps {
+  labels?: Partial<OnboardingLabels>;
+  locale?: string;
+  children: ReactNode;
+}
+
+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>
+  );
+}
+
+export function useOnboardingIntl(): OnboardingIntl {
+  return useContext(OnboardingIntlContext);
+}

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

@@ -0,0 +1,40 @@
+import type { ReactNode } from 'react';
+import { Button, Spinner, type ButtonProps } from '@umituz/web-design-system/atoms';
+import { useOnboardingIntl } from './OnboardingIntl';
+
+export interface PrimaryButtonProps extends ButtonProps {
+  children: ReactNode;
+  loading?: boolean;
+  fullWidth?: boolean;
+}
+
+export function PrimaryButton({
+  children,
+  loading = false,
+  fullWidth = true,
+  disabled,
+  type,
+  block,
+  ...rest
+}: PrimaryButtonProps) {
+  const { labels } = useOnboardingIntl();
+  return (
+    <Button
+      {...rest}
+      type={type ?? 'button'}
+      variant="primary"
+      size="lg"
+      block={block ?? fullWidth}
+      disabled={disabled || loading}
+    >
+      {loading ? (
+        <>
+          <Spinner size="sm" />
+          <span>{labels.loading}</span>
+        </>
+      ) : (
+        children
+      )}
+    </Button>
+  );
+}

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

@@ -0,0 +1,32 @@
+import { Progress } from '@umituz/web-design-system/atoms';
+import { cn } from '@umituz/web-design-system/utils/cn';
+import { computeProgressPercentage } from '../calc/progress-percentage';
+import { formatLabel, useOnboardingIntl } from './OnboardingIntl';
+
+export interface ProgressBarProps {
+  current: number;
+  total: number;
+  className?: string;
+  showLabel?: boolean;
+}
+
+export function ProgressBar({ current, total, className, showLabel = false }: ProgressBarProps) {
+  const { labels } = useOnboardingIntl();
+  const safeTotal = Math.max(1, total);
+  const safeCurrent = Math.max(0, Math.min(current, safeTotal));
+  const percentage = Math.round(computeProgressPercentage(safeCurrent, safeTotal));
+
+  return (
+    <div className={cn('udb-onb-progress', className)}>
+      {showLabel && (
+        <div className="udb-onb-progress__meta">
+          <span aria-live="polite">
+            {formatLabel(labels.stepOfPattern, { current: safeCurrent, total: safeTotal })}
+          </span>
+          <span aria-hidden="true">{percentage}%</span>
+        </div>
+      )}
+      <Progress value={percentage} label="Onboarding progress" />
+    </div>
+  );
+}

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

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react';
+import { motion } from 'framer-motion';
+import { cn } from '@umituz/web-design-system/utils/cn';
+
+export interface QuestionWrapperProps {
+  title: string;
+  subtitle?: string;
+  children: ReactNode;
+  className?: string;
+}
+
+export function QuestionWrapper({ title, subtitle, children, className }: QuestionWrapperProps) {
+  return (
+    <motion.div
+      initial={{ opacity: 0, y: 8 }}
+      animate={{ opacity: 1, y: 0 }}
+      exit={{ opacity: 0, y: -8 }}
+      transition={{ duration: 0.25, ease: 'easeOut' }}
+      className={cn('udb-onb-question', className)}
+    >
+      <header className="udb-onb-question__head">
+        <h2 className="udb-onb-title">{title}</h2>
+        {subtitle && <p className="udb-onb-lead">{subtitle}</p>}
+      </header>
+      <div className="udb-onb-question__body">{children}</div>
+    </motion.div>
+  );
+}

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

@@ -0,0 +1,19 @@
+import type { ReactNode } from 'react';
+import { cn } from '@umituz/web-design-system/utils/cn';
+
+export interface ScreenContainerProps {
+  children: ReactNode;
+  header?: ReactNode;
+  footer?: ReactNode;
+  className?: string;
+}
+
+export function ScreenContainer({ children, header, footer, className }: ScreenContainerProps) {
+  return (
+    <div className={cn('udb-onb-screen', className)}>
+      {header && <div className="udb-onb-screen__header">{header}</div>}
+      <main className="udb-onb-screen__main">{children}</main>
+      {footer && <div className="udb-onb-screen__footer">{footer}</div>}
+    </div>
+  );
+}

package/src/domains/onboarding/components/SwipeCard.test.tsx

@@ -0,0 +1,49 @@
+import { describe, it, expect, vi } from 'vitest';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { SwipeCard } from './SwipeCard';
+import { OnboardingIntlProvider } from './OnboardingIntl';
+
+function renderCard(props: Partial<React.ComponentProps<typeof SwipeCard>> = {}) {
+  return render(
+    <OnboardingIntlProvider>
+      <SwipeCard
+        text="I want to feel better"
+        category="Mood"
+        onSwipeLeft={vi.fn()}
+        onSwipeRight={vi.fn()}
+        {...props}
+      />
+    </OnboardingIntlProvider>,
+  );
+}
+
+describe('SwipeCard', () => {
+  it('triggers onSwipeRight on ArrowRight and onSwipeLeft on ArrowLeft', () => {
+    const onSwipeLeft = vi.fn();
+    const onSwipeRight = vi.fn();
+    renderCard({ onSwipeLeft, onSwipeRight });
+    const card = screen.getByRole('group');
+    card.focus();
+    fireEvent.keyDown(card, { key: 'ArrowRight' });
+    expect(onSwipeRight).toHaveBeenCalledTimes(1);
+    expect(onSwipeLeft).not.toHaveBeenCalled();
+    fireEvent.keyDown(card, { key: 'ArrowLeft' });
+    expect(onSwipeLeft).toHaveBeenCalledTimes(1);
+  });
+
+  it('renders the AGREE / DISAGREE badges and the swipe hint', () => {
+    renderCard();
+    expect(screen.getByText('Agree')).toBeTruthy();
+    expect(screen.getByText('Disagree')).toBeTruthy();
+    expect(screen.getByText(/arrow keys/)).toBeTruthy();
+  });
+
+  it('ignores unrelated keys', () => {
+    const onSwipeLeft = vi.fn();
+    const onSwipeRight = vi.fn();
+    renderCard({ onSwipeLeft, onSwipeRight });
+    fireEvent.keyDown(screen.getByRole('group'), { key: 'Enter' });
+    expect(onSwipeLeft).not.toHaveBeenCalled();
+    expect(onSwipeRight).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,88 @@
+import { useEffect, useRef } from 'react';
+import { motion, useMotionValue, useTransform, type PanInfo } from 'framer-motion';
+import {
+  didCrossLeftSwipeThreshold,
+  didCrossRightSwipeThreshold,
+  SWIPE_LEFT_OPACITY_INPUT,
+  SWIPE_LEFT_OPACITY_VALUES,
+  SWIPE_RIGHT_OPACITY_INPUT,
+  SWIPE_RIGHT_OPACITY_VALUES,
+  SWIPE_ROTATION_RANGE,
+  SWIPE_ROTATION_VALUES,
+} from '../calc/swipe-gesture-curve';
+import { useOnboardingIntl } from './OnboardingIntl';
+
+export interface SwipeCardProps {
+  text: string;
+  category?: string;
+  onSwipeLeft: () => void;
+  onSwipeRight: () => void;
+  className?: string;
+}
+
+function useSwipeGestures({ onSwipeLeft, onSwipeRight }: { onSwipeLeft: () => void; onSwipeRight: () => void }) {
+  const leftRef = useRef(onSwipeLeft);
+  const rightRef = useRef(onSwipeRight);
+  useEffect(() => {
+    leftRef.current = onSwipeLeft;
+    rightRef.current = onSwipeRight;
+  }, [onSwipeLeft, onSwipeRight]);
+
+  return {
+    onDragEnd(_: unknown, info: PanInfo) {
+      if (didCrossRightSwipeThreshold(info.offset.x)) rightRef.current();
+      else if (didCrossLeftSwipeThreshold(info.offset.x)) leftRef.current();
+    },
+  };
+}
+
+export function SwipeCard({ text, category, onSwipeLeft, onSwipeRight, className }: SwipeCardProps) {
+  const { labels } = useOnboardingIntl();
+  const x = useMotionValue(0);
+  const rotate = useTransform(x, SWIPE_ROTATION_RANGE, SWIPE_ROTATION_VALUES);
+  const leftOpacity = useTransform(x, SWIPE_LEFT_OPACITY_INPUT, SWIPE_LEFT_OPACITY_VALUES);
+  const rightOpacity = useTransform(x, SWIPE_RIGHT_OPACITY_INPUT, SWIPE_RIGHT_OPACITY_VALUES);
+  const { onDragEnd } = useSwipeGestures({ onSwipeLeft, onSwipeRight });
+
+  return (
+    <div
+      className={className ? `udb-onb-swipe ${className}` : 'udb-onb-swipe'}
+      role="group"
+      aria-label={`${text} — ${labels.swipeHint}`}
+      tabIndex={0}
+      onKeyDown={(e) => {
+        if (e.key === 'ArrowLeft') {
+          e.preventDefault();
+          onSwipeLeft();
+        } else if (e.key === 'ArrowRight') {
+          e.preventDefault();
+          onSwipeRight();
+        }
+      }}
+    >
+      <motion.div
+        style={{ x, rotate }}
+        drag="x"
+        dragConstraints={{ left: 0, right: 0 }}
+        onDragEnd={onDragEnd}
+        className="udb-onb-swipe__card"
+      >
+        {category && <span className="udb-onb-swipe__category">{category}</span>}
+        <p className="udb-onb-swipe__text">{text}</p>
+        <p className="udb-onb-swipe__hint">{labels.swipeHint}</p>
+      </motion.div>
+      <motion.div
+        style={{ opacity: leftOpacity }}
+        className="udb-onb-swipe__stamp udb-onb-swipe__stamp--no"
+      >
+        {labels.disagree}
+      </motion.div>
+      <motion.div
+        style={{ opacity: rightOpacity }}
+        className="udb-onb-swipe__stamp udb-onb-swipe__stamp--yes"
+      >
+        {labels.agree}
+      </motion.div>
+    </div>
+  );
+}

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

@@ -0,0 +1,7 @@
+import { resolveIconByName } from '../predicates/icon-name-resolves';
+
+export function renderBundledIcon(name: string | undefined, className?: string) {
+  const Icon = resolveIconByName(name);
+  if (!Icon) return null;
+  return <Icon className={className} aria-hidden="true" />;
+}