@umituz/web-dashboard 3.2.2 → 4.0.0

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

@@ -0,0 +1,62 @@
+/**
+ * Onboarding - Step Progress Indicator
+ *
+ * Renders the wizard's progress as a row of numbered nodes connected
+ * by lines. Stateless: receives all data via props.
+ */
+
+import { Check } from "lucide-react";
+import { cn } from "../../../primitives";
+
+interface StepProgressProps {
+  currentStep: number;
+  totalSteps: number;
+  completedSteps?: number[];
+}
+
+export const StepProgress = ({
+  currentStep,
+  totalSteps,
+  completedSteps = [],
+}: StepProgressProps) => {
+  return (
+    <div
+      className="udb-progress"
+      role="progressbar"
+      aria-valuemin={1}
+      aria-valuemax={totalSteps}
+      aria-valuenow={currentStep}
+    >
+      {Array.from({ length: totalSteps }, (_, i) => i + 1).map((step) => {
+        const isCompleted = completedSteps.includes(step) || step < currentStep;
+        const isCurrent = step === currentStep;
+
+        return (
+          <div key={step} className="udb-progress__segment">
+            <div
+              className={cn(
+                "udb-progress__node",
+                (isCompleted || isCurrent) && "udb-progress__node--on",
+              )}
+              aria-current={isCurrent ? "step" : undefined}
+            >
+              {isCompleted ? (
+                <Check className="udb-progress__check" aria-hidden="true" />
+              ) : (
+                step
+              )}
+            </div>
+            {step < totalSteps && (
+              <div
+                className={cn(
+                  "udb-progress__connector",
+                  step < currentStep && "udb-progress__connector--on",
+                )}
+              />
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+};

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

@@ -1,128 +1,107 @@
+/**
+ * User Type Step
+ *
+ * First step of the onboarding wizard: select user type.
+ * String props are expected to be already-translated by the consumer
+ * (so the consumer can localize each option via i18n).
+ */
+
 import { Check } from "lucide-react";
-import { cn } from "@umituz/web-design-system/utils";
-import type { OnboardingState } from "../types/onboarding";
+import { useT } from "../../../i18n";
+import { cn } from "../../../primitives";
+import type { OnboardingState, UserTypeOption } from "../types/onboarding";
 import type { ComponentType } from "react";
+import { ONBOARDING_KEYS } from "../utils/i18nKeys";
 
-interface UserTypeOption {
-  id: string;
-  label: string;
-  description: string;
-  icon?: ComponentType<{ className?: string }>;
-  badge?: string;
-}
-
-interface UserTypeStepProps {
+export interface UserTypeStepProps {
   /** Current onboarding state */
   state: OnboardingState;
   /** Update state function */
   updateState: (updates: Partial<OnboardingState>) => void;
-  /** User type options */
+  /** User type options — labels/desc are translated by the consumer */
   options?: UserTypeOption[];
+  /** Custom icon component type (avoids `React.ComponentType` import here) */
+  iconComponent?: ComponentType<{ className?: string }>;
 }
 
 /**
- * User Type Selection Step
- *
- * First step of onboarding - select user type/category
+ * Default options — every string is an i18n key. The consumer
+ * supplies translations; nothing in this file is hardcoded copy.
  */
+const DEFAULT_OPTIONS: UserTypeOption[] = [
+  { id: "founder", labelKey: ONBOARDING_KEYS.defaults.founder, descriptionKey: ONBOARDING_KEYS.defaults.founderDescription },
+  { id: "creator", labelKey: ONBOARDING_KEYS.defaults.contentCreator, descriptionKey: ONBOARDING_KEYS.defaults.contentCreatorDescription },
+  { id: "agency", labelKey: ONBOARDING_KEYS.defaults.agency, descriptionKey: ONBOARDING_KEYS.defaults.agencyDescription },
+  { id: "enterprise", labelKey: ONBOARDING_KEYS.defaults.enterprise, descriptionKey: ONBOARDING_KEYS.defaults.enterpriseDescription },
+  { id: "small-business", labelKey: ONBOARDING_KEYS.defaults.smallBusiness, descriptionKey: ONBOARDING_KEYS.defaults.smallBusinessDescription },
+  { id: "personal", labelKey: ONBOARDING_KEYS.defaults.personal, descriptionKey: ONBOARDING_KEYS.defaults.personalDescription },
+];
+
 export const UserTypeStep = ({
   state,
   updateState,
   options = [],
 }: UserTypeStepProps) => {
-  // Default options if not provided
-  const defaultOptions: UserTypeOption[] = [
-    {
-      id: "founder",
-      label: "Founder",
-      description: "Building your own startup or business",
-    },
-    {
-      id: "creator",
-      label: "Content Creator",
-      description: "Creating content for social media and platforms",
-    },
-    {
-      id: "agency",
-      label: "Agency",
-      description: "Managing multiple client accounts",
-    },
-    {
-      id: "enterprise",
-      label: "Enterprise",
-      description: "Large scale organization with teams",
-    },
-    {
-      id: "small-business",
-      label: "Small Business",
-      description: "Local or niche business owner",
-    },
-    {
-      id: "personal",
-      label: "Personal",
-      description: "Individual looking to grow personal brand",
-    },
-  ];
-
-  const userTypeOptions = options.length > 0 ? options : defaultOptions;
+  const t = useT();
+  const userTypeOptions = options.length > 0 ? options : DEFAULT_OPTIONS;
 
   return (
-    <div className="w-full max-w-xl">
-      <div className="text-center mb-10">
-        <h1 className="text-3xl md:text-4xl font-extrabold text-foreground mb-3">
-          What describes you best?
+    <div className="udb-step">
+      <div className="udb-step__header">
+        <h1 className="udb-step__title">
+          {t(ONBOARDING_KEYS.userType.title)}
         </h1>
-        <p className="text-muted-foreground">
-          Select the option that best describes your situation
+        <p className="udb-step__description">
+          {t(ONBOARDING_KEYS.userType.description)}
         </p>
       </div>
 
-      <div className="grid grid-cols-1 gap-3">
+      <div className="udb-step__options udb-step__options--list" role="radiogroup" aria-label={t(ONBOARDING_KEYS.userType.title)}>
         {userTypeOptions.map((option) => {
           const isSelected = state.selectedUserType === option.id;
           const hasBadge = option.badge != null;
           const hasIcon = option.icon != null;
+          const label = option.label ?? (option.labelKey ? t(option.labelKey) : '');
+          const description = option.description ?? (option.descriptionKey ? t(option.descriptionKey) : '');
 
           return (
             <button
               key={option.id}
+              type="button"
+              role="radio"
+              aria-checked={isSelected}
               onClick={() => updateState({ selectedUserType: option.id })}
               className={cn(
-                "w-full flex items-center gap-4 p-5 rounded-2xl border bg-background text-left transition-all group",
-                isSelected
-                  ? "border-primary ring-2 ring-primary/20 bg-primary/5"
-                  : "border-border hover:border-primary/40 hover:bg-muted/50"
+                "udb-choice",
+                isSelected && "udb-choice--selected",
               )}
             >
-              <div
+              <span
                 className={cn(
-                  "w-6 h-6 rounded-full border-2 flex items-center justify-center shrink-0 transition-colors",
-                  isSelected
-                    ? "border-primary bg-primary text-white"
-                    : "border-muted-foreground/30"
+                  "udb-choice__check",
+                  isSelected && "udb-choice__check--on",
                 )}
+                aria-hidden="true"
               >
-                {isSelected && <Check className="h-4 w-4" />}
-              </div>
+                {isSelected && <Check className="udb-choice__check-icon" />}
+              </span>
 
-              <div className="flex-1">
-                <div className="flex items-center gap-2">
-                  <p className="font-bold text-foreground">{option.label}</p>
+              <span className="udb-choice__body">
+                <span className="udb-choice__label-row">
+                  <span className="udb-choice__label">{label}</span>
                   {hasBadge && (
-                    <span className="text-[10px] font-bold uppercase tracking-wider px-2 py-0.5 rounded-full bg-primary/10 text-primary">
+                    <span className="udb-choice__badge">
                       {option.badge}
                     </span>
                   )}
-                </div>
-                <p className="text-sm text-muted-foreground mt-0.5">
-                  {option.description}
-                </p>
-              </div>
+                </span>
+                <span className="udb-choice__description">{description}</span>
+              </span>
 
               {hasIcon && option.icon && (
-                <div className="w-10 h-10 rounded-xl bg-muted flex items-center justify-center shrink-0">
-                  <option.icon className="h-5 w-5 text-muted-foreground" />
-                </div>
+                <span className="udb-choice__icon-box">
+                  <option.icon className="udb-choice__icon" aria-hidden="true" />
+                </span>
               )}
             </button>
           );

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

@@ -7,3 +7,7 @@ export { UserTypeStep } from './UserTypeStep';
 export { AppFocusStep } from './AppFocusStep';
 export { PlatformsStep } from './PlatformsStep';
 export { PlanStep } from './PlanStep';
+export { StepProgress } from './StepProgress';
+export { StepNavigation } from './StepNavigation';
+export { STEP_NAVIGATION_KEYS } from './StepNavigation';
+export type { StepNavigationKey, Translate } from './StepNavigation';

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

@@ -1,102 +1,108 @@
 /**
  * Onboarding Hooks
  *
- * Custom React hooks for onboarding functionality
+ * Custom React hooks for onboarding functionality. Navigation callbacks
+ * read the current render's state so their boolean return values are
+ * truthful; state updaters themselves stay pure.
  */
 
-import { useState, useCallback } from "react";
+import { useState, useCallback, useMemo, useRef } from "react";
 import type { OnboardingState, OnboardingConfig } from "../types/onboarding";
 
+/**
+ * Initial onboarding state — single source of truth.
+ */
+const buildInitialState = (
+  initialState?: Partial<OnboardingState>,
+): OnboardingState => ({
+  currentStep: 1,
+  connectedPlatforms: [],
+  billingCycle: "monthly",
+  stepData: {},
+  ...initialState,
+});
+
 /**
  * Use Onboarding Hook
  *
- * Manages onboarding state and actions
+ * Manages onboarding state and actions.
  *
  * @param config - Onboarding configuration
- * @param initialState - Initial state
+ * @param initialState - Initial state overrides
  * @returns Onboarding state and actions
  */
 export function useOnboarding(
   config: OnboardingConfig,
-  initialState?: Partial<OnboardingState>
+  initialState?: Partial<OnboardingState>,
 ) {
-  const [state, setState] = useState<OnboardingState>({
-    currentStep: 1,
-    connectedPlatforms: [],
-    billingCycle: "monthly",
-    stepData: {},
-    ...initialState,
-  });
+  const [state, setState] = useState<OnboardingState>(() => buildInitialState(initialState));
 
   const totalSteps = config.steps.length;
 
-  // Navigation actions
-  const goToNext = useCallback(() => {
+  // Validation and the boolean return value are computed against the
+  // current render's state (always fresh — these callbacks are
+  // recreated when state changes); the setState updater stays pure and
+  // bounds-checked. The previous version flipped a closure variable
+  // inside the updater, which returned false before React had run it.
+  const goToNext = useCallback((): boolean => {
     const currentStepConfig = config.steps[state.currentStep - 1];
-
-    // Validate if needed
-    if (currentStepConfig?.validate) {
-      const isValid = currentStepConfig.validate(state);
-      if (!isValid) return false;
+    if (currentStepConfig?.validate && !currentStepConfig.validate(state)) {
+      return false;
     }
-
-    if (state.currentStep < totalSteps) {
-      setState((prev) => ({ ...prev, currentStep: prev.currentStep + 1 }));
-      return true;
-    }
-
-    return false;
+    if (state.currentStep >= totalSteps) return false;
+    setState((prev) =>
+      prev.currentStep < totalSteps
+        ? { ...prev, currentStep: prev.currentStep + 1 }
+        : prev,
+    );
+    return true;
   }, [config.steps, state, totalSteps]);
 
-  const goToPrev = useCallback(() => {
-    if (state.currentStep > 1) {
-      setState((prev) => ({ ...prev, currentStep: prev.currentStep - 1 }));
-      return true;
-    }
-    return false;
-  }, [state.currentStep]);
+  const goToPrev = useCallback((): boolean => {
+    if (state.currentStep <= 1) return false;
+    setState((prev) =>
+      prev.currentStep > 1
+        ? { ...prev, currentStep: prev.currentStep - 1 }
+        : prev,
+    );
+    return true;
+  }, [state]);
 
   const goToStep = useCallback((step: number) => {
-    if (step >= 1 && step <= totalSteps) {
-      setState((prev) => ({ ...prev, currentStep: step }));
-    }
+    setState((prev) => {
+      if (step >= 1 && step <= totalSteps && step !== prev.currentStep) {
+        return { ...prev, currentStep: step };
+      }
+      return prev;
+    });
   }, [totalSteps]);
 
-  // State update action
   const updateState = useCallback((updates: Partial<OnboardingState>) => {
     setState((prev) => ({ ...prev, ...updates }));
   }, []);
 
-  // Validation helper
-  const canGoNext = useCallback(() => {
+  // Whether the current step passes its configured validator.
+  const canGoNext = useCallback((): boolean => {
     const currentStepConfig = config.steps[state.currentStep - 1];
-    if (currentStepConfig?.validate) {
-      return currentStepConfig.validate(state);
-    }
-    return true;
+    return currentStepConfig?.validate ? currentStepConfig.validate(state) : true;
   }, [config.steps, state]);
 
-  // Progress calculation
-  const getProgress = useCallback(() => {
-    return (state.currentStep / totalSteps) * 100;
+  // The `isFirstStep` / `isLastStep` derivations are cheap, but
+  // memoizing them avoids re-creating the object on every render.
+  const derived = useMemo(() => {
+    const isFirstStep = state.currentStep === 1;
+    const isLastStep = state.currentStep === totalSteps;
+    const progress = totalSteps === 0 ? 0 : (state.currentStep / totalSteps) * 100;
+    return { isFirstStep, isLastStep, progress };
   }, [state.currentStep, totalSteps]);
 
-  // Is first step
-  const isFirstStep = state.currentStep === 1;
-
-  // Is last step
-  const isLastStep = state.currentStep === totalSteps;
-
   return {
-    // State
     state,
     currentStep: state.currentStep,
     totalSteps,
-    isFirstStep,
-    isLastStep,
-    progress: getProgress(),
-
-    // Actions
+    isFirstStep: derived.isFirstStep,
+    isLastStep: derived.isLastStep,
+    progress: derived.progress,
     goToNext,
     goToPrev,
     goToStep,
@@ -108,34 +114,38 @@ export function useOnboarding(
 /**
  * Use Onboarding Step Hook
  *
- * Hook for managing individual step state
- *
- * @param stepId - Step identifier
- * @returns Step state and actions
+ * Hook for managing individual step state.
  */
 export function useOnboardingStep(stepId: string) {
   const [data, setData] = useState<Record<string, unknown>>({});
   const [isValid, setIsValid] = useState(false);
   const [isTouched, setIsTouched] = useState(false);
 
+  // Latest-ref mirror of `data` so `validate` can read the most recent
+  // value synchronously. State updaters must stay pure — the previous
+  // version called setIsValid inside the setData updater.
+  const dataRef = useRef<Record<string, unknown>>({});
+
   const updateData = useCallback((updates: Record<string, unknown>) => {
-    setData((prev) => ({ ...prev, ...updates }));
+    const next = { ...dataRef.current, ...updates };
+    dataRef.current = next;
+    setData(next);
     setIsTouched(true);
   }, []);
 
   const validate = useCallback((validator: (data: Record<string, unknown>) => boolean) => {
-    const valid = validator(data);
-    setIsValid(valid);
-    return valid;
+    setIsValid(validator(dataRef.current));
   }, []);
 
   const reset = useCallback(() => {
+    dataRef.current = {};
     setData({});
     setIsValid(false);
     setIsTouched(false);
   }, []);
 
   return {
+    stepId,
     data,
     isValid,
     isTouched,

package/src/domains/onboarding/index.ts

@@ -20,6 +20,7 @@ export {
   generateOnboardingEvent,
   isValidEmail,
   isValidPassword,
+  ONBOARDING_KEYS,
 } from './utils';
 export type {
   UserTypeOption,

package/src/domains/onboarding/types/onboarding.ts

@@ -5,52 +5,88 @@
  */
 
 import type { LucideIcon } from "lucide-react";
-import type { ComponentType, ReactElement, ReactNode } from "react";
+import type { ComponentType, ReactElement } from "react";
 
 /**
- * User type option for first step
+ * Onboarding error — the message is an i18n key.
+ */
+export interface OnboardingError {
+  /** Step where the error occurred */
+  step: number;
+  /** i18n key for the localized error message */
+  message: string;
+}
+
+/**
+ * User type option for first step.
+ * Either supply `label`/`description` directly (already translated) or
+ * supply `labelKey`/`descriptionKey` to be resolved by the consumer's i18n.
  */
 export interface UserTypeOption {
   /** Unique identifier */
   id: string;
-  /** Display label */
-  label: string;
-  /** Description text */
-  description: string;
-  /** Icon component */
+  /** Display label (already-translated string) */
+  label?: string;
+  /** Description text (already-translated) */
+  description?: string;
+  /** i18n key for the label */
+  labelKey?: string;
+  /** i18n key for the description */
+  descriptionKey?: string;
+  /** Icon component (Lucide) */
   icon?: LucideIcon;
   /** Badge text */
   badge?: string;
 }
 
 /**
- * Platform connection option
+ * Platform connection option.
+ * Icons must be Lucide components — emoji is not allowed.
  */
 export interface PlatformOption {
   /** Unique identifier */
   id: string;
   /** Display name */
   name: string;
-  /** Icon/emoji */
-  icon: string;
-  /** Color theme */
+  /** Lucide icon component */
+  icon: LucideIcon;
+  /** Brand color as a plain CSS color string (e.g. "#c026d3") */
   color?: string;
   /** Connection status */
   connected?: boolean;
 }
 
+/**
+ * App type option for the AppFocusStep.
+ * Same shape as PlatformOption (icon as component, not emoji).
+ */
+export interface AppTypeOption {
+  id: string;
+  name: string;
+  description: string;
+  icon: LucideIcon;
+  /**
+   * State field toggled by this option. When omitted, the field is
+   * derived from the id ("mobile" → hasMobileApp, "web" → hasWebApp);
+   * options that resolve to neither render inert.
+   */
+  stateField?: "hasMobileApp" | "hasWebApp";
+}
+
 /**
  * Plan option for billing step
  */
 export interface PlanOption {
   /** Unique identifier */
   id: string;
-  /** Plan name */
+  /** Plan name (already translated) */
   name: string;
-  /** Badge text */
+  /** Badge text (already translated) — preferred for static labels */
   badge?: string;
-  /** Badge color class */
-  badgeColor?: string;
+  /** i18n key for the badge — resolved via `translate` in the consumer */
+  badgeKey?: string;
+  /** Semantic badge tone rendered by the stylesheet */
+  badgeTone?: "muted" | "primary" | "accent";
   /** Description text */
   description: string;
   /** Monthly price */
@@ -115,6 +151,8 @@ export interface OnboardingConfig {
   cancelRoute?: string;
   /** Allow skipping steps */
   allowSkip?: boolean;
+  /** Allow canceling the wizard from the header */
+  allowCancel?: boolean;
   /** Show progress indicator */
   showProgress?: boolean;
   /** Enable user menu in header */
@@ -199,9 +237,9 @@ export interface StepNavigationProps {
   canGoNext: boolean;
   /** Is saving/completing */
   isSaving?: boolean;
-  /** Next button label */
+  /** Next button label (overrides the i18n key) */
   nextLabel?: string;
-  /** Previous button label */
+  /** Previous button label (overrides the i18n key) */
   prevLabel?: string;
   /** On next */
   onNext: () => void;
@@ -211,4 +249,6 @@ export interface StepNavigationProps {
   allowSkip?: boolean;
   /** On skip */
   onSkip?: () => void;
+  /** Translation function */
+  translate: (key: string) => string;
 }