@etus/ui 0.1.0

package/src/components/workflow/Wizard/Wizard.test.tsx

@@ -0,0 +1,432 @@
+import type { WizardStep } from "./Wizard.types"
+
+import { render, screen, waitFor } from "@testing-library/react"
+import userEvent from "@testing-library/user-event"
+import { describe, expect, it, vi } from "vitest"
+
+import { Wizard } from "./Wizard"
+
+describe("Wizard", () => {
+  const createSteps = (): WizardStep[] => [
+    { content: <div>Content 1</div>, id: "1", title: "Step 1" },
+    { content: <div>Content 2</div>, id: "2", title: "Step 2" },
+    { content: <div>Content 3</div>, id: "3", title: "Step 3" },
+  ]
+
+  describe("Rendering", () => {
+    it("renders current step content", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} steps={steps} />)
+      expect(screen.getByText("Content 1")).toBeInTheDocument()
+      expect(screen.queryByText("Content 2")).not.toBeInTheDocument()
+    })
+
+    it("renders step title", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} steps={steps} />)
+      expect(screen.getByRole("heading", { name: "Step 1" })).toBeInTheDocument()
+    })
+
+    it("renders stepper with all steps", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} steps={steps} />)
+      // Step 1 appears in both stepper and content, so use getAllByText
+      expect(screen.getAllByText("Step 1").length).toBeGreaterThanOrEqual(1)
+      expect(screen.getByText("Step 2")).toBeInTheDocument()
+      expect(screen.getByText("Step 3")).toBeInTheDocument()
+    })
+
+    it("hides stepper when showSteps is false", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} showSteps={false} steps={steps} />)
+      expect(screen.queryByRole("progressbar")).not.toBeInTheDocument()
+    })
+
+    it("hides actions when showActions is false", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} showActions={false} steps={steps} />)
+      expect(screen.queryByText("Próximo")).not.toBeInTheDocument()
+    })
+
+    it("applies custom className", () => {
+      const steps = createSteps()
+      const { container } = render(
+        <Wizard className="custom-class" currentStep={0} steps={steps} />
+      )
+      expect(container.firstChild).toHaveClass("custom-class")
+    })
+
+    it("has correct data-slot attribute", () => {
+      const steps = createSteps()
+      const { container } = render(<Wizard currentStep={0} steps={steps} />)
+      expect(container.firstChild).toHaveAttribute("data-slot", "wizard")
+    })
+
+    it("has correct aria-label", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} steps={steps} />)
+      expect(screen.getByRole("region")).toHaveAttribute(
+        "aria-label",
+        "Wizard: Step 1 of 3"
+      )
+    })
+  })
+
+  describe("Navigation - Next", () => {
+    it("calls onStepChange when clicking next", async () => {
+      const user = userEvent.setup()
+      const onStepChange = vi.fn()
+      const steps = createSteps()
+
+      render(
+        <Wizard currentStep={0} steps={steps} onStepChange={onStepChange} />
+      )
+
+      await user.click(screen.getByText("Próximo"))
+      expect(onStepChange).toHaveBeenCalledWith(1)
+    })
+
+    it("shows complete button on last step", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={2} steps={steps} />)
+      expect(screen.getByText("Completar")).toBeInTheDocument()
+      expect(screen.queryByText("Próximo")).not.toBeInTheDocument()
+    })
+
+    it("calls onComplete when clicking complete on last step", async () => {
+      const user = userEvent.setup()
+      const onComplete = vi.fn()
+      const steps = createSteps()
+
+      render(<Wizard currentStep={2} steps={steps} onComplete={onComplete} />)
+
+      await user.click(screen.getByText("Completar"))
+      expect(onComplete).toHaveBeenCalled()
+    })
+
+    it("uses custom next label", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} nextLabel="Continue" steps={steps} />)
+      expect(screen.getByText("Continue")).toBeInTheDocument()
+    })
+
+    it("uses custom complete label", () => {
+      const steps = createSteps()
+      render(<Wizard completeLabel="Finish" currentStep={2} steps={steps} />)
+      expect(screen.getByText("Finish")).toBeInTheDocument()
+    })
+  })
+
+  describe("Navigation - Back", () => {
+    it("calls onStepChange when clicking back", async () => {
+      const user = userEvent.setup()
+      const onStepChange = vi.fn()
+      const steps = createSteps()
+
+      render(
+        <Wizard currentStep={1} steps={steps} onStepChange={onStepChange} />
+      )
+
+      await user.click(screen.getByText("Voltar"))
+      expect(onStepChange).toHaveBeenCalledWith(0)
+    })
+
+    it("hides back button on first step", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} steps={steps} />)
+      expect(screen.queryByText("Voltar")).not.toBeInTheDocument()
+    })
+
+    it("hides back button when canGoBack is false", () => {
+      const steps = createSteps()
+      render(<Wizard canGoBack={false} currentStep={1} steps={steps} />)
+      expect(screen.queryByText("Voltar")).not.toBeInTheDocument()
+    })
+
+    it("uses custom back label", () => {
+      const steps = createSteps()
+      render(<Wizard backLabel="Previous" currentStep={1} steps={steps} />)
+      expect(screen.getByText("Previous")).toBeInTheDocument()
+    })
+  })
+
+  describe("Navigation - Skip", () => {
+    it("shows skip button for optional steps when canSkip is true", () => {
+      const steps: WizardStep[] = [
+        { content: <div>Content 1</div>, id: "1", optional: true, title: "Step 1" },
+        { content: <div>Content 2</div>, id: "2", title: "Step 2" },
+      ]
+      render(<Wizard canSkip currentStep={0} steps={steps} />)
+      expect(screen.getByText("Pular")).toBeInTheDocument()
+    })
+
+    it("hides skip button for non-optional steps", () => {
+      const steps = createSteps()
+      render(<Wizard canSkip currentStep={0} steps={steps} />)
+      expect(screen.queryByText("Pular")).not.toBeInTheDocument()
+    })
+
+    it("hides skip button when canSkip is false", () => {
+      const steps: WizardStep[] = [
+        { content: <div>Content 1</div>, id: "1", optional: true, title: "Step 1" },
+        { content: <div>Content 2</div>, id: "2", title: "Step 2" },
+      ]
+      render(<Wizard canSkip={false} currentStep={0} steps={steps} />)
+      expect(screen.queryByText("Pular")).not.toBeInTheDocument()
+    })
+
+    it("calls onStepChange when clicking skip", async () => {
+      const user = userEvent.setup()
+      const onStepChange = vi.fn()
+      const steps: WizardStep[] = [
+        { content: <div>Content 1</div>, id: "1", optional: true, title: "Step 1" },
+        { content: <div>Content 2</div>, id: "2", title: "Step 2" },
+      ]
+
+      render(
+        <Wizard canSkip currentStep={0} steps={steps} onStepChange={onStepChange} />
+      )
+
+      await user.click(screen.getByText("Pular"))
+      expect(onStepChange).toHaveBeenCalledWith(1)
+    })
+
+    it("uses custom skip label", () => {
+      const steps: WizardStep[] = [
+        { content: <div>Content 1</div>, id: "1", optional: true, title: "Step 1" },
+        { content: <div>Content 2</div>, id: "2", title: "Step 2" },
+      ]
+      render(<Wizard canSkip currentStep={0} skipLabel="Skip this" steps={steps} />)
+      expect(screen.getByText("Skip this")).toBeInTheDocument()
+    })
+  })
+
+  describe("Loading State", () => {
+    it("shows loading text when isLoading is true", () => {
+      const steps = createSteps()
+      render(<Wizard isLoading currentStep={0} steps={steps} />)
+      expect(screen.getByText("Carregando...")).toBeInTheDocument()
+    })
+
+    it("disables buttons when isLoading is true", () => {
+      const steps = createSteps()
+      render(<Wizard isLoading currentStep={1} steps={steps} />)
+      expect(screen.getByText("Carregando...")).toBeDisabled()
+      expect(screen.getByText("Voltar")).toBeDisabled()
+    })
+
+    it("applies loading styles", () => {
+      const steps = createSteps()
+      const { container } = render(<Wizard isLoading currentStep={0} steps={steps} />)
+      expect(container.firstChild).toHaveClass("opacity-50")
+      expect(container.firstChild).toHaveClass("pointer-events-none")
+    })
+  })
+
+  describe("Validation", () => {
+    it("runs step validation before advancing", async () => {
+      const user = userEvent.setup()
+      const validate = vi.fn().mockResolvedValue(true)
+      const onStepChange = vi.fn()
+      const steps: WizardStep[] = [
+        { content: <div>Content 1</div>, id: "1", title: "Step 1", validate },
+        { content: <div>Content 2</div>, id: "2", title: "Step 2" },
+      ]
+
+      render(
+        <Wizard currentStep={0} steps={steps} onStepChange={onStepChange} />
+      )
+
+      await user.click(screen.getByText("Próximo"))
+
+      await waitFor(() => {
+        expect(validate).toHaveBeenCalled()
+      })
+
+      await waitFor(() => {
+        expect(onStepChange).toHaveBeenCalledWith(1)
+      })
+    })
+
+    it("does not advance when validation fails", async () => {
+      const user = userEvent.setup()
+      const validate = vi.fn().mockResolvedValue(false)
+      const onStepChange = vi.fn()
+      const steps: WizardStep[] = [
+        { content: <div>Content 1</div>, id: "1", title: "Step 1", validate },
+        { content: <div>Content 2</div>, id: "2", title: "Step 2" },
+      ]
+
+      render(
+        <Wizard currentStep={0} steps={steps} onStepChange={onStepChange} />
+      )
+
+      await user.click(screen.getByText("Próximo"))
+
+      await waitFor(() => {
+        expect(validate).toHaveBeenCalled()
+      })
+
+      expect(onStepChange).not.toHaveBeenCalled()
+    })
+
+    it("runs onValidate callback", async () => {
+      const user = userEvent.setup()
+      const onValidate = vi.fn().mockReturnValue(true)
+      const onStepChange = vi.fn()
+      const steps = createSteps()
+
+      render(
+        <Wizard
+          currentStep={0}
+          steps={steps}
+          onStepChange={onStepChange}
+          onValidate={onValidate}
+        />
+      )
+
+      await user.click(screen.getByText("Próximo"))
+
+      await waitFor(() => {
+        expect(onValidate).toHaveBeenCalledWith(0)
+      })
+
+      await waitFor(() => {
+        expect(onStepChange).toHaveBeenCalledWith(1)
+      })
+    })
+  })
+
+  describe("Variants", () => {
+    it("renders default variant", () => {
+      const steps = createSteps()
+      const { container } = render(<Wizard currentStep={0} steps={steps} />)
+      expect(container.firstChild).toHaveClass("flex-col")
+    })
+
+    it("renders vertical variant", () => {
+      const steps = createSteps()
+      const { container } = render(
+        <Wizard currentStep={0} steps={steps} variant="vertical" />
+      )
+      expect(container.firstChild).toHaveClass("flex-row")
+    })
+
+    it("renders card variant", () => {
+      const steps = createSteps()
+      const { container } = render(
+        <Wizard currentStep={0} steps={steps} variant="card" />
+      )
+      expect(container.firstChild).toHaveClass("rounded-lg")
+      expect(container.firstChild).toHaveClass("border")
+    })
+  })
+
+  describe("Sizes", () => {
+    it("applies sm size", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} size="sm" steps={steps} />)
+      const content = document.querySelector('[data-slot="wizard-content"]')
+      expect(content).toHaveClass("p-4")
+    })
+
+    it("applies default size", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} size="default" steps={steps} />)
+      const content = document.querySelector('[data-slot="wizard-content"]')
+      expect(content).toHaveClass("p-6")
+    })
+
+    it("applies lg size", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} size="lg" steps={steps} />)
+      const content = document.querySelector('[data-slot="wizard-content"]')
+      expect(content).toHaveClass("p-8")
+    })
+  })
+
+  describe("Keyboard Navigation", () => {
+    it("advances on Enter key", async () => {
+      const user = userEvent.setup()
+      const onStepChange = vi.fn()
+      const steps = createSteps()
+
+      render(
+        <Wizard currentStep={0} steps={steps} onStepChange={onStepChange} />
+      )
+
+      const wizard = screen.getByRole("region")
+      wizard.focus()
+      await user.keyboard("{Enter}")
+
+      expect(onStepChange).toHaveBeenCalledWith(1)
+    })
+  })
+
+  describe("Step Click", () => {
+    it("allows clicking completed steps", async () => {
+      const user = userEvent.setup()
+      const onStepChange = vi.fn()
+      const steps = createSteps()
+
+      render(
+        <Wizard currentStep={2} steps={steps} onStepChange={onStepChange} />
+      )
+
+      // Click on first step (completed)
+      await user.click(screen.getByText("Step 1"))
+      expect(onStepChange).toHaveBeenCalledWith(0)
+    })
+  })
+
+  describe("Step Descriptions", () => {
+    it("renders step descriptions", () => {
+      const steps: WizardStep[] = [
+        {
+          content: <div>Content 1</div>,
+          description: "Description 1",
+          id: "1",
+          title: "Step 1",
+        },
+        { content: <div>Content 2</div>, id: "2", title: "Step 2" },
+      ]
+      render(<Wizard currentStep={0} steps={steps} />)
+      expect(screen.getByText("Description 1")).toBeInTheDocument()
+    })
+  })
+
+  describe("Accessibility", () => {
+    it("has region role", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={0} steps={steps} />)
+      expect(screen.getByRole("region")).toBeInTheDocument()
+    })
+
+    it("has correct aria attributes", () => {
+      const steps = createSteps()
+      render(<Wizard currentStep={1} steps={steps} />)
+      expect(screen.getByRole("region")).toHaveAttribute(
+        "aria-label",
+        "Wizard: Step 2 of 3"
+      )
+    })
+
+    it("disabled buttons have aria-disabled", () => {
+      const steps = createSteps()
+      render(<Wizard isLoading currentStep={1} steps={steps} />)
+      expect(screen.getByText("Carregando...")).toHaveAttribute(
+        "aria-disabled",
+        "true"
+      )
+    })
+  })
+
+  describe("Ref", () => {
+    it("forwards ref to container element", () => {
+      const ref = vi.fn()
+      const steps = createSteps()
+      render(<Wizard ref={ref} currentStep={0} steps={steps} />)
+      expect(ref).toHaveBeenCalled()
+    })
+  })
+})

package/src/components/workflow/Wizard/Wizard.tsx

@@ -0,0 +1,279 @@
+import type { StepItem } from "../Stepper"
+import type { WizardProps, WizardStep } from "./Wizard.types"
+
+import { useCallback, useEffect, useRef, useState } from "react"
+
+import { cn } from "../../../lib/utils"
+import { Button } from "../../primitives/Button"
+import { Stepper } from "../Stepper"
+import {
+  wizardActionsVariants,
+  wizardContentVariants,
+  wizardStepperVariants,
+  wizardVariants,
+} from "./Wizard.variants"
+
+/**
+ * Convert WizardStep to StepItem for the Stepper component
+ */
+function convertToStepItem(step: WizardStep, index: number, currentStep: number): StepItem {
+  return {
+    description: step.description,
+    icon: step.icon,
+    id: step.id,
+    label: step.title,
+    status: index < currentStep ? "complete" : index === currentStep ? "active" : "pending",
+  }
+}
+
+/**
+ * Wizard component guides users through a multi-step process.
+ *
+ * @example
+ * ```tsx
+ * const steps = [
+ *   { id: "1", title: "Dados Pessoais", content: <PersonalForm /> },
+ *   { id: "2", title: "Endereço", content: <AddressForm /> },
+ *   { id: "3", title: "Conclusão", content: <Summary /> },
+ * ]
+ *
+ * <Wizard
+ *   steps={steps}
+ *   currentStep={0}
+ *   onStepChange={setStep}
+ *   onComplete={handleComplete}
+ * />
+ * ```
+ */
+function Wizard({
+  backLabel = "Voltar",
+  canGoBack = true,
+  canSkip = false,
+  className,
+  completeLabel = "Completar",
+  currentStep = 0,
+  isLoading = false,
+  nextLabel = "Próximo",
+  onComplete,
+  onStepChange,
+  onValidate,
+  ref,
+  showActions = true,
+  showSteps = true,
+  size = "default",
+  skipLabel = "Pular",
+  steps,
+  variant = "default",
+  ...props
+}: WizardProps) {
+  const [isValidating, setIsValidating] = useState(false)
+  const contentRef = useRef<HTMLDivElement>(null)
+  const isLastStep = currentStep >= steps.length - 1
+  const isFirstStep = currentStep === 0
+  const currentStepData = steps[currentStep]
+
+  // Convert steps for the Stepper component
+  const stepperSteps: StepItem[] = steps.map((step, index) =>
+    convertToStepItem(step, index, currentStep)
+  )
+
+  // Focus management - move focus to content when step changes
+  useEffect(() => {
+    if (contentRef.current) {
+      contentRef.current.focus()
+    }
+  }, [currentStep])
+
+  // Handle next step
+  const handleNext = useCallback(async () => {
+    if (isLoading || isValidating) return
+
+    // Run step validation if provided
+    if (currentStepData?.validate) {
+      setIsValidating(true)
+      try {
+        const isValid = await currentStepData.validate()
+        if (!isValid) {
+          setIsValidating(false)
+          return
+        }
+      } catch {
+        setIsValidating(false)
+        return
+      }
+      setIsValidating(false)
+    }
+
+    // Run onValidate callback if provided
+    if (onValidate) {
+      setIsValidating(true)
+      try {
+        const isValid = await Promise.resolve(onValidate(currentStep))
+        if (!isValid) {
+          setIsValidating(false)
+          return
+        }
+      } catch {
+        setIsValidating(false)
+        return
+      }
+      setIsValidating(false)
+    }
+
+    if (isLastStep) {
+      onComplete?.()
+    } else {
+      onStepChange?.(currentStep + 1)
+    }
+  }, [currentStep, currentStepData, isLastStep, isLoading, isValidating, onComplete, onStepChange, onValidate])
+
+  // Handle back step
+  const handleBack = useCallback(() => {
+    if (isLoading || isValidating || !canGoBack || isFirstStep) return
+    onStepChange?.(currentStep - 1)
+  }, [canGoBack, currentStep, isFirstStep, isLoading, isValidating, onStepChange])
+
+  // Handle skip step
+  const handleSkip = useCallback(() => {
+    if (isLoading || isValidating || !canSkip || isLastStep) return
+    if (currentStepData?.optional) {
+      onStepChange?.(currentStep + 1)
+    }
+  }, [canSkip, currentStep, currentStepData?.optional, isLastStep, isLoading, isValidating, onStepChange])
+
+  // Handle step click from stepper
+  const handleStepClick = useCallback(
+    (stepIndex: number) => {
+      if (isLoading || isValidating) return
+      // Only allow clicking on completed steps or the next step
+      if (stepIndex <= currentStep) {
+        onStepChange?.(stepIndex)
+      }
+    },
+    [currentStep, isLoading, isValidating, onStepChange]
+  )
+
+  // Handle keyboard navigation
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (event.key === "Enter" && !event.shiftKey) {
+        event.preventDefault()
+        void handleNext()
+      } else if (event.key === "Escape") {
+        // Could implement cancel confirmation here
+      }
+    },
+    [handleNext]
+  )
+
+  const isVertical = variant === "vertical"
+
+  return (
+    <div
+      ref={ref}
+      className={cn(
+        wizardVariants({ size, variant }),
+        isLoading && "pointer-events-none opacity-50",
+        className
+      )}
+      aria-label={`Wizard: Step ${String(currentStep + 1)} of ${String(steps.length)}`}
+      data-slot="wizard"
+      role="region"
+      onKeyDown={handleKeyDown}
+      {...props}
+    >
+      {/* Stepper */}
+      {showSteps && (
+        <div
+          className={wizardStepperVariants({ size, variant })}
+          data-slot="wizard-stepper"
+        >
+          <Stepper
+            clickable
+            currentStep={currentStep}
+            size={size === "lg" ? "lg" : size === "sm" ? "sm" : "default"}
+            steps={stepperSteps}
+            variant={isVertical ? "vertical" : "default"}
+            onStepClick={handleStepClick}
+          />
+        </div>
+      )}
+
+      {/* Content */}
+      <div
+        ref={contentRef}
+        className={wizardContentVariants({ size, variant })}
+        data-slot="wizard-content"
+        tabIndex={-1}
+      >
+        {/* Step content */}
+        <div
+          aria-label={currentStepData?.title}
+          data-slot="wizard-step"
+          data-step={currentStep + 1}
+        >
+          {currentStepData?.title && (
+            <h2
+              className="mb-4 text-lg font-semibold"
+              data-slot="wizard-step-title"
+            >
+              {currentStepData.title}
+            </h2>
+          )}
+          <div data-slot="wizard-step-form">{currentStepData?.content}</div>
+        </div>
+
+        {/* Actions */}
+        {showActions && (
+          <div
+            className={cn(wizardActionsVariants({ size, variant }), "mt-6")}
+            data-slot="wizard-actions"
+          >
+            <div className="flex gap-3">
+              {/* Back button */}
+              {canGoBack && !isFirstStep && (
+                <Button
+                  aria-disabled={isLoading || isValidating}
+                  data-slot="wizard-back"
+                  disabled={isLoading || isValidating}
+                  type="button"
+                  variant="outline"
+                  onClick={handleBack}
+                >
+                  {backLabel}
+                </Button>
+              )}
+
+              {/* Skip button */}
+              {canSkip && currentStepData?.optional && !isLastStep && (
+                <Button
+                  aria-disabled={isLoading || isValidating}
+                  data-slot="wizard-skip"
+                  disabled={isLoading || isValidating}
+                  type="button"
+                  variant="ghost"
+                  onClick={handleSkip}
+                >
+                  {skipLabel}
+                </Button>
+              )}
+            </div>
+
+            {/* Next/Complete button */}
+            <Button
+              aria-disabled={isLoading || isValidating}
+              data-slot="wizard-next"
+              disabled={isLoading || isValidating}
+              type="button"
+              onClick={() => void handleNext()}
+            >
+              {isLoading || isValidating ? "Carregando..." : isLastStep ? completeLabel : nextLabel}
+            </Button>
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+export { Wizard }