@umituz/web-dashboard 6.0.0 → 6.2.0

package/src/domains/onboarding/components/screens/PreferencesScreen.tsx

@@ -0,0 +1,180 @@
+import { useId, useState } from 'react';
+import { PrimaryButton } from '../PrimaryButton';
+import { QuestionWrapper } from '../QuestionWrapper';
+import { useOnboardingIntl } from '../OnboardingIntl';
+import { cn } from '@umituz/web-design-system/utils/cn';
+import {
+  clampValueToBounds,
+  resolveSliderBounds,
+} from '../../calc/slider-value-bounds';
+import type {
+  OnboardingOption,
+  PreferenceItem,
+  PreferencesScreenConfig,
+} from '../../types/screens';
+
+type PrefValue = string | number | string[] | boolean;
+
+function defaultFor(item: PreferenceItem): PrefValue {
+  if (item.defaultValue !== undefined) {
+    if (item.type === 'slider' && typeof item.defaultValue === 'number') {
+      return clampValueToBounds(item.defaultValue, item.min ?? 0, item.max ?? 0, item.id);
+    }
+    return item.defaultValue;
+  }
+  switch (item.type) {
+    case 'multi-select':
+      return [];
+    case 'toggle':
+      return false;
+    case 'slider':
+      return resolveSliderBounds(item.min, item.max).min;
+    case 'select':
+    default:
+      return item.options?.[0]?.id ?? '';
+  }
+}
+
+function toggleMulti(values: string[], id: string): string[] {
+  return values.includes(id) ? values.filter((v) => v !== id) : [...values, id];
+}
+
+export interface PreferencesScreenProps {
+  config: PreferencesScreenConfig;
+  onNext: (data: { values: Record<string, PrefValue> }) => void;
+}
+
+export function PreferencesScreen({ config, onNext }: PreferencesScreenProps) {
+  const { labels } = useOnboardingIntl();
+  const [values, setValues] = useState<Record<string, PrefValue>>(() => {
+    const initial: Record<string, PrefValue> = {};
+    for (const item of config.preferences) initial[item.id] = defaultFor(item);
+    return initial;
+  });
+
+  function update(id: string, value: PrefValue) {
+    setValues((prev) => ({ ...prev, [id]: value }));
+  }
+
+  const canContinue = config.preferences.every((item) => {
+    const v = values[item.id];
+    if (item.type === 'select') return typeof v === 'string' && v.length > 0;
+    if (item.type === 'multi-select') return Array.isArray(v);
+    return true;
+  });
+
+  return (
+    <QuestionWrapper title={config.title} subtitle={labels.tailorExperience}>
+      <div className="udb-onb-prefs">
+        {config.preferences.map((item) => (
+          <PreferenceRow key={item.id} item={item} value={values[item.id]} onChange={(v) => update(item.id, v)} />
+        ))}
+      </div>
+      <PrimaryButton onClick={() => onNext({ values })} disabled={!canContinue}>
+        {config.cta ?? labels.continueAction}
+      </PrimaryButton>
+    </QuestionWrapper>
+  );
+}
+
+interface PreferenceRowProps {
+  item: PreferenceItem;
+  value: PrefValue;
+  onChange: (value: PrefValue) => void;
+}
+
+function PreferenceRow({ item, value, onChange }: PreferenceRowProps) {
+  const fieldId = useId();
+  return (
+    <div className="udb-onb-field">
+      <label className="udb-onb-field__label" htmlFor={fieldId}>
+        {item.label}
+      </label>
+      <PreferenceControl item={item} value={value} onChange={onChange} fieldId={fieldId} />
+    </div>
+  );
+}
+
+interface PreferenceControlProps extends PreferenceRowProps {
+  fieldId: string;
+}
+
+function PreferenceControl({ item, value, onChange, fieldId }: PreferenceControlProps) {
+  switch (item.type) {
+    case 'select':
+      return (
+        <select
+          id={fieldId}
+          className="udb-onb-select"
+          value={typeof value === 'string' ? value : ''}
+          onChange={(e) => onChange(e.target.value)}
+        >
+          {item.options?.map((opt: OnboardingOption) => (
+            <option key={opt.id} value={opt.id}>
+              {opt.label}
+            </option>
+          ))}
+        </select>
+      );
+    case 'multi-select': {
+      const list = Array.isArray(value) ? value : [];
+      return (
+        <div className="udb-onb-chips" role="group" aria-label={item.label}>
+          {item.options?.map((opt) => {
+            const isOn = list.includes(opt.id);
+            return (
+              <button
+                key={opt.id}
+                type="button"
+                aria-pressed={isOn}
+                onClick={() => onChange(toggleMulti(list, opt.id))}
+                className={cn('udb-onb-chip', isOn && 'udb-onb-chip--on')}
+              >
+                {opt.label}
+              </button>
+            );
+          })}
+        </div>
+      );
+    }
+    case 'toggle':
+      return (
+        <button
+          type="button"
+          id={fieldId}
+          role="switch"
+          aria-checked={value === true}
+          onClick={() => onChange(!value)}
+          className={cn('udb-onb-switch', value === true && 'udb-onb-switch--on')}
+        >
+          <span className="udb-onb-switch__thumb" />
+        </button>
+      );
+    case 'slider': {
+      const { min, max } = resolveSliderBounds(item.min, item.max);
+      const numeric = typeof value === 'number' ? value : min;
+      return (
+        <div className="udb-onb-slider">
+          <input
+            type="range"
+            id={fieldId}
+            min={min}
+            max={max}
+            value={numeric}
+            onChange={(e) => onChange(Number(e.target.value))}
+            aria-valuemin={min}
+            aria-valuemax={max}
+            aria-valuenow={numeric}
+          />
+          <div className="udb-onb-slider__scale">
+            <span>{min}</span>
+            <span>{numeric}</span>
+            <span>{max}</span>
+          </div>
+        </div>
+      );
+    }
+    default:
+      return null;
+  }
+}

package/src/domains/onboarding/components/screens/ProcessingScreen.tsx

@@ -0,0 +1,63 @@
+import { useEffect, useState } from 'react';
+import { motion, AnimatePresence } from 'framer-motion';
+import { Check } from 'lucide-react';
+import { cn } from '@umituz/web-design-system/utils/cn';
+import { splitTotalDuration } from '../../calc/duration-equal-split';
+import type { ProcessingScreenConfig } from '../../types/screens';
+
+export interface ProcessingScreenProps {
+  config: ProcessingScreenConfig;
+  onComplete: (data: { completed: true }) => void;
+}
+
+export function ProcessingScreen({ config, onComplete }: ProcessingScreenProps) {
+  const stepDuration = splitTotalDuration(config.durationMs, config.steps.length);
+  const [currentStep, setCurrentStep] = useState(0);
+
+  useEffect(() => {
+    if (currentStep >= config.steps.length) {
+      onComplete({ completed: true });
+      return;
+    }
+    const timer = window.setTimeout(() => setCurrentStep((s) => s + 1), stepDuration);
+    return () => window.clearTimeout(timer);
+  }, [currentStep, config.steps.length, stepDuration, onComplete]);
+
+  return (
+    <div className="udb-onb-stage">
+      {config.title && <h2 className="udb-onb-title">{config.title}</h2>}
+      <ul className="udb-onb-steps" aria-live="polite">
+        {config.steps.map((step, i) => {
+          const isDone = i < currentStep;
+          const isActive = i === currentStep;
+          return (
+            <li
+              key={`${step}-${i}`}
+              className={cn(
+                'udb-onb-step',
+                isDone && 'udb-onb-step--done',
+                isActive && 'udb-onb-step--active',
+              )}
+            >
+              <span className="udb-onb-step__badge">
+                {isDone ? <Check className="udb-onb-icon--sm" /> : <span>{i + 1}</span>}
+              </span>
+              <span>{step}</span>
+              <AnimatePresence>
+                {isActive && (
+                  <motion.span
+                    initial={{ opacity: 0 }}
+                    animate={{ opacity: 1 }}
+                    exit={{ opacity: 0 }}
+                    className="udb-onb-step__pulse"
+                    aria-hidden="true"
+                  />
+                )}
+              </AnimatePresence>
+            </li>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}

package/src/domains/onboarding/components/screens/SocialProofScreen.tsx

@@ -0,0 +1,87 @@
+import { useState } from 'react';
+import { motion, AnimatePresence } from 'framer-motion';
+import { Star } from 'lucide-react';
+import { PrimaryButton } from '../PrimaryButton';
+import { Button } from '@umituz/web-design-system/atoms';
+import { cn } from '@umituz/web-design-system/utils/cn';
+import { useOnboardingIntl } from '../OnboardingIntl';
+import type { SocialProofScreenConfig } from '../../types/screens';
+
+export interface SocialProofScreenProps {
+  config: SocialProofScreenConfig;
+  onNext: () => void;
+}
+
+export function SocialProofScreen({ config, onNext }: SocialProofScreenProps) {
+  const { labels } = useOnboardingIntl();
+  const [index, setIndex] = useState(0);
+  const total = config.testimonials.length;
+  const current = config.testimonials[index];
+
+  function go(delta: number) {
+    setIndex((i) => (i + delta + total) % total);
+  }
+
+  return (
+    <div className="udb-onb-proof">
+      {config.title && <h2 className="udb-onb-title">{config.title}</h2>}
+      <div className="udb-onb-proof__stage">
+        <AnimatePresence mode="wait">
+          <motion.blockquote
+            key={`${current.name}-${index}`}
+            initial={{ opacity: 0, y: 12 }}
+            animate={{ opacity: 1, y: 0 }}
+            exit={{ opacity: 0, y: -12 }}
+            transition={{ duration: 0.3 }}
+            className="udb-onb-quote"
+          >
+            {current.rating !== undefined && (
+              <div className="udb-onb-quote__stars" aria-label={`Rated ${current.rating} out of 5`}>
+                {Array.from({ length: 5 }).map((_, i) => (
+                  <Star
+                    key={i}
+                    className={cn('udb-onb-quote__star', i < current.rating! && 'udb-onb-quote__star--filled')}
+                  />
+                ))}
+              </div>
+            )}
+            <p className="udb-onb-quote__content">“{current.content}”</p>
+            <footer className="udb-onb-quote__footer">
+              {current.avatar && <img src={current.avatar} alt="" className="udb-onb-quote__avatar" />}
+              <cite className="udb-onb-quote__cite">{current.name}</cite>
+              <span className="udb-onb-quote__role">{current.role}</span>
+            </footer>
+          </motion.blockquote>
+        </AnimatePresence>
+      </div>
+      <div className="udb-onb-proof__bar">
+        <div className="udb-onb-dots" role="tablist" aria-label="Testimonials">
+          {config.testimonials.map((t, i) => (
+            <button
+              key={`${t.name}-${i}`}
+              type="button"
+              role="tab"
+              aria-selected={i === index}
+              aria-label={`${t.name}: ${t.content}`}
+              onClick={() => setIndex(i)}
+              className={cn('udb-onb-dot', i === index && 'udb-onb-dot--active')}
+            />
+          ))}
+        </div>
+        <div className="udb-onb-proof__nav">
+          {total > 1 && (
+            <>
+              <Button variant="outline" size="sm" onClick={() => go(-1)}>
+                {labels.previous}
+              </Button>
+              <Button variant="outline" size="sm" onClick={() => go(1)}>
+                {labels.nextAction}
+              </Button>
+            </>
+          )}
+        </div>
+      </div>
+      <PrimaryButton onClick={onNext}>{config.cta ?? labels.continueAction}</PrimaryButton>
+    </div>
+  );
+}

package/src/domains/onboarding/components/screens/TinderCardsScreen.tsx

@@ -0,0 +1,91 @@
+import { useState, useRef, useEffect, useCallback } from 'react';
+import { AnimatePresence, motion } from 'framer-motion';
+import { SwipeCard } from '../SwipeCard';
+import { PrimaryButton } from '../PrimaryButton';
+import {
+  getCardEnterAnimate,
+  getCardEnterExit,
+  getCardEnterInitial,
+  getCardTransitionDurationMs,
+} from '../../calc/card-stack-motion-curve';
+import { formatLabel, useOnboardingIntl } from '../OnboardingIntl';
+import type { TinderCardsScreenConfig } from '../../types/screens';
+
+export interface TinderCardsScreenProps {
+  config: TinderCardsScreenConfig;
+  onNext: (data: { liked: string[] }) => void;
+}
+
+export function TinderCardsScreen({ config, onNext }: TinderCardsScreenProps) {
+  const { labels } = useOnboardingIntl();
+  const [index, setIndex] = useState(0);
+  const [liked, setLiked] = useState<string[]>([]);
+  const total = config.statements.length;
+  const current = config.statements[index];
+      const indexRef = useRef(index);
+  const likedRef = useRef(liked);
+  useEffect(() => {
+    indexRef.current = index;
+    likedRef.current = liked;
+  }, [index, liked]);
+
+  const handleDecision = useCallback(
+    (likedStatement: boolean) => {
+      if (likedStatement) {
+        setLiked((prev) => [...prev, config.statements[indexRef.current].id]);
+      }
+      setIndex((i) => i + 1);
+    },
+    [config.statements],
+  );
+
+  const onSwipeLeft = useCallback(() => handleDecision(false), [handleDecision]);
+  const onSwipeRight = useCallback(() => handleDecision(true), [handleDecision]);
+
+  if (!current) {
+    return (
+      <div className="udb-onb-stage">
+        <p className="udb-onb-lead">{labels.allDone}</p>
+        <PrimaryButton onClick={() => onNext({ liked: likedRef.current })}>
+          {config.cta ?? labels.continueAction}
+        </PrimaryButton>
+      </div>
+    );
+  }
+
+  return (
+    <div className="udb-onb-proof">
+      {config.title && <h2 className="udb-onb-title">{config.title}</h2>}
+      <div className="udb-onb-proof__stage">
+        <AnimatePresence mode="wait">
+          <motion.div
+            key={current.id}
+            initial={{ opacity: getCardEnterInitial().opacity, scale: getCardEnterInitial().scale }}
+            animate={{ opacity: getCardEnterAnimate().opacity, scale: getCardEnterAnimate().scale }}
+            exit={{ opacity: getCardEnterExit().opacity, scale: getCardEnterExit().scale }}
+            transition={{ duration: getCardTransitionDurationMs() / 1000 }}
+            className="udb-onb-stage"
+          >
+            <SwipeCard
+              text={current.text}
+              category={current.category}
+              onSwipeLeft={onSwipeLeft}
+              onSwipeRight={onSwipeRight}
+            />
+          </motion.div>
+        </AnimatePresence>
+      </div>
+      <div className="udb-onb-proof__nav">
+        <button type="button" onClick={onSwipeLeft} className="udb-onb-choice udb-onb-choice--no">
+          {labels.disagree}
+        </button>
+        <button type="button" onClick={onSwipeRight} className="udb-onb-choice udb-onb-choice--yes">
+          {labels.agree}
+        </button>
+      </div>
+      <p className="udb-onb-note" aria-live="polite">
+        {formatLabel(labels.countOfPattern, { current: index + 1, total })}
+      </p>
+    </div>
+  );
+}

package/src/domains/onboarding/components/screens/ValueDeliveryScreen.tsx

@@ -0,0 +1,69 @@
+import { useEffect, useRef, useState } from 'react';
+import { Button } from '@umituz/web-design-system/atoms';
+import { Sparkles } from 'lucide-react';
+import { PrimaryButton } from '../PrimaryButton';
+import { useOnboardingIntl } from '../OnboardingIntl';
+import type { ValueDeliveryScreenConfig } from '../../types/screens';
+
+export interface ValueDeliveryScreenProps<TResult = unknown> {
+  config: ValueDeliveryScreenConfig<TResult>;
+  onNext: () => void;
+}
+
+export function ValueDeliveryScreen<TResult = unknown>({
+  config,
+  onNext,
+}: ValueDeliveryScreenProps<TResult>) {
+  const { labels } = useOnboardingIntl();
+  const [copied, setCopied] = useState(false);
+  const copiedTimer = useRef<number | null>(null);
+
+  useEffect(
+    () => () => {
+      if (copiedTimer.current !== null) window.clearTimeout(copiedTimer.current);
+    },
+    [],
+  );
+
+  async function handleShare() {
+    if (!config.shareConfig) return;
+    const { text, url } = config.shareConfig;
+    try {
+      if (typeof navigator !== 'undefined' && typeof navigator.share === 'function') {
+        await navigator.share({ text, url });
+        return;
+      }
+      if (typeof navigator !== 'undefined' && navigator.clipboard?.writeText) {
+        await navigator.clipboard.writeText(url ?? text);
+        setCopied(true);
+        if (copiedTimer.current !== null) window.clearTimeout(copiedTimer.current);
+        copiedTimer.current = window.setTimeout(() => setCopied(false), 2000);
+      }
+    } catch (error) {
+            if (!(error instanceof DOMException && error.name === 'AbortError')) {
+        console.error('[onboarding] share failed', error);
+      }
+    }
+  }
+
+  return (
+    <div className="udb-onb-stage">
+      <div className="udb-onb-hero udb-onb-hero--lg" aria-hidden="true">
+        <Sparkles className="udb-onb-icon--lg" />
+      </div>
+      <h2 className="udb-onb-title udb-onb-title--display">{config.title}</h2>
+      <div className="udb-onb-result">
+        <pre className="udb-onb-result__pre">{JSON.stringify(config.result, null, 2)}</pre>
+      </div>
+      {config.shareConfig && (
+        <div className="udb-onb-share">
+          <Button variant="outline" size="sm" onClick={handleShare}>
+            {copied ? labels.copied : labels.share}
+          </Button>
+          <span>{config.shareConfig.text}</span>
+        </div>
+      )}
+      <PrimaryButton onClick={onNext}>{config.cta ?? labels.continueAction}</PrimaryButton>
+    </div>
+  );
+}

package/src/domains/onboarding/components/screens/WelcomeScreen.tsx

@@ -0,0 +1,32 @@
+import { PrimaryButton } from '../PrimaryButton';
+import { renderBundledIcon } from '../renderBundledIcon';
+import { doesIconNameResolve } from '../../predicates/icon-name-resolves';
+import { useOnboardingIntl } from '../OnboardingIntl';
+import type { WelcomeScreenConfig } from '../../types/screens';
+
+export interface WelcomeScreenProps {
+  config: WelcomeScreenConfig;
+  onNext: () => void;
+  isLoading?: boolean;
+}
+
+export function WelcomeScreen({ config, onNext, isLoading }: WelcomeScreenProps) {
+  const { labels } = useOnboardingIntl();
+  return (
+    <div className="udb-onb-stage udb-onb-stage--wide">
+      {doesIconNameResolve(config.heroIconName) && (
+        <div className="udb-onb-hero udb-onb-hero--xl" aria-hidden="true">
+          {renderBundledIcon(config.heroIconName, 'udb-onb-icon--xl')}
+        </div>
+      )}
+      <div className="udb-onb-welcome__group">
+        {config.title && <h1 className="udb-onb-welcome__title">{config.title}</h1>}
+        {config.subtitle && <p className="udb-onb-welcome__subtitle">{config.subtitle}</p>}
+        {config.highlight && <p className="udb-onb-welcome__highlight">{config.highlight}</p>}
+      </div>
+      <PrimaryButton onClick={config.onCta ?? onNext} loading={isLoading}>
+        {config.cta ?? labels.continueAction}
+      </PrimaryButton>
+    </div>
+  );
+}

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

@@ -0,0 +1,28 @@
+export { WelcomeScreen } from './WelcomeScreen';
+export type { WelcomeScreenProps } from './WelcomeScreen';
+export { GoalQuestionScreen } from './GoalQuestionScreen';
+export type { GoalQuestionScreenProps } from './GoalQuestionScreen';
+export { PainPointsScreen } from './PainPointsScreen';
+export type { PainPointsScreenProps } from './PainPointsScreen';
+export { SocialProofScreen } from './SocialProofScreen';
+export type { SocialProofScreenProps } from './SocialProofScreen';
+export { TinderCardsScreen } from './TinderCardsScreen';
+export type { TinderCardsScreenProps } from './TinderCardsScreen';
+export { PersonalizedSolutionScreen } from './PersonalizedSolutionScreen';
+export type { PersonalizedSolutionScreenProps } from './PersonalizedSolutionScreen';
+export { ComparisonScreen } from './ComparisonScreen';
+export type { ComparisonScreenProps } from './ComparisonScreen';
+export { PreferencesScreen } from './PreferencesScreen';
+export type { PreferencesScreenProps } from './PreferencesScreen';
+export { PermissionPrimingScreen } from './PermissionPrimingScreen';
+export type { PermissionPrimingScreenProps } from './PermissionPrimingScreen';
+export { ProcessingScreen } from './ProcessingScreen';
+export type { ProcessingScreenProps } from './ProcessingScreen';
+export { AppDemoScreen } from './AppDemoScreen';
+export type { AppDemoScreenProps } from './AppDemoScreen';
+export { ValueDeliveryScreen } from './ValueDeliveryScreen';
+export type { ValueDeliveryScreenProps } from './ValueDeliveryScreen';
+export { AccountGateScreen } from './AccountGateScreen';
+export type { AccountGateScreenProps } from './AccountGateScreen';
+export { PaywallScreen } from './PaywallScreen';
+export type { PaywallScreenProps } from './PaywallScreen';

package/src/domains/onboarding/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/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();
+  });
+});