@ttoss/react-wizard 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024, Terezinha Tech Operations (ttoss)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,399 @@
+# @ttoss/react-wizard
+
+A React wizard component for guiding users through multi-step flows with configurable step list layouts.
+
+## Installation
+
+```bash
+pnpm add @ttoss/react-wizard
+```
+
+## Usage
+
+```tsx
+import { Wizard } from '@ttoss/react-wizard';
+
+const steps = [
+  {
+    title: 'Personal Info',
+    description: 'Enter your details',
+    content: <PersonalInfoForm />,
+    onNext: () => validatePersonalInfo(),
+  },
+  {
+    title: 'Address',
+    content: <AddressForm />,
+  },
+  {
+    title: 'Review',
+    content: <ReviewStep />,
+  },
+];
+
+const MyWizard = () => {
+  return (
+    <Wizard
+      steps={steps}
+      layout="top"
+      onComplete={() => console.log('Done!')}
+      onCancel={() => console.log('Cancelled')}
+    />
+  );
+};
+```
+
+## Props
+
+| Prop             | Type                                      | Default | Description                                            |
+| ---------------- | ----------------------------------------- | ------- | ------------------------------------------------------ |
+| `steps`          | `WizardStep[]`                            | —       | Array of step definitions.                             |
+| `layout`         | `'top' \| 'right' \| 'bottom' \| 'left'`  | `'top'` | Position of the step list relative to content.         |
+| `onComplete`     | `() => void`                              | —       | Called when the user finishes the last step.           |
+| `onCancel`       | `() => void`                              | —       | Called on cancel. If omitted, cancel button is hidden. |
+| `onStepChange`   | `(params: { stepIndex: number }) => void` | —       | Called when the active step changes.                   |
+| `initialStep`    | `number`                                  | `0`     | The initially active step index.                       |
+| `allowStepClick` | `boolean`                                 | `true`  | Allow clicking completed steps to navigate back.       |
+
+## WizardStep
+
+| Property      | Type                                | Description                                               |
+| ------------- | ----------------------------------- | --------------------------------------------------------- |
+| `title`       | `string`                            | Title displayed in the step list.                         |
+| `description` | `string`                            | Optional description below the title.                     |
+| `content`     | `ReactNode`                         | Content rendered when the step is active.                 |
+| `onNext`      | `() => boolean \| Promise<boolean>` | Validation callback. Return `false` to prevent advancing. |
+
+## Layouts
+
+The `layout` prop controls where the step list appears:
+
+- **`top`** — Horizontal step list above the content (default).
+- **`bottom`** — Horizontal step list below the content.
+- **`left`** — Vertical step list on the left side.
+- **`right`** — Vertical step list on the right side.
+
+## useWizard Hook
+
+Access the wizard context from within step content:
+
+```tsx
+import { useWizard } from '@ttoss/react-wizard';
+
+const StepContent = () => {
+  const {
+    currentStep,
+    totalSteps,
+    goToNext,
+    goToPrevious,
+    isLastStep,
+    setStepValidation,
+  } = useWizard();
+
+  return (
+    <div>
+      Step {currentStep + 1} of {totalSteps}
+    </div>
+  );
+};
+```
+
+### useWizard Return Value
+
+| Property            | Type                                                    | Description                                                  |
+| ------------------- | ------------------------------------------------------- | ------------------------------------------------------------ |
+| `currentStep`       | `number`                                                | Current active step index.                                   |
+| `totalSteps`        | `number`                                                | Total number of steps.                                       |
+| `goToNext`          | `() => Promise<void>`                                   | Navigate to the next step.                                   |
+| `goToPrevious`      | `() => void`                                            | Navigate to the previous step.                               |
+| `goToStep`          | `(params: { stepIndex: number }) => void`               | Navigate to a specific step.                                 |
+| `isFirstStep`       | `boolean`                                               | Whether the wizard is on the first step.                     |
+| `isLastStep`        | `boolean`                                               | Whether the wizard is on the last step.                      |
+| `getStepStatus`     | `(params: { stepIndex: number }) => WizardStepStatus`   | Get the status of a step by index.                           |
+| `setStepValidation` | `(validate: () => boolean \| Promise<boolean>) => void` | Register a validation function for the current step content. |
+
+## Example: Form with Step-by-Step Validation
+
+This example demonstrates using a single form across all wizard steps, with each step validating only its relevant fields using Zod:
+
+```tsx
+import { Wizard } from '@ttoss/react-wizard';
+import {
+  Form,
+  FormFieldInput,
+  FormFieldSelect,
+  FormFieldTextarea,
+  useForm,
+  z,
+  zodResolver,
+} from '@ttoss/forms';
+import { Button, Box, Text } from '@ttoss/ui';
+
+// Define the complete Zod schema for all steps
+const schema = z.object({
+  // Step 1: Personal Information
+  firstName: z.string().min(1, 'First name is required'),
+  lastName: z.string().min(1, 'Last name is required'),
+  email: z.string().email('Invalid email address'),
+
+  // Step 2: Address
+  street: z.string().min(1, 'Street is required'),
+  city: z.string().min(1, 'City is required'),
+  country: z.string().min(1, 'Country is required'),
+
+  // Step 3: Additional Info
+  phone: z.string().min(10, 'Phone must be at least 10 digits'),
+  comments: z.string().optional(),
+});
+
+type FormData = z.infer<typeof schema>;
+
+const RegistrationWizard = () => {
+  const formMethods = useForm<FormData>({
+    mode: 'onChange',
+    resolver: zodResolver(schema),
+  });
+
+  const { trigger, handleSubmit } = formMethods;
+
+  const handleComplete = handleSubmit((data) => {
+    console.log('Form submitted:', data);
+    // Handle final submission
+  });
+
+  const steps = [
+    {
+      title: 'Personal Info',
+      description: 'Basic information',
+      content: (
+        <Box>
+          <FormFieldInput
+            name="firstName"
+            label="First Name"
+            placeholder="Enter your first name"
+          />
+          <FormFieldInput
+            name="lastName"
+            label="Last Name"
+            placeholder="Enter your last name"
+          />
+          <FormFieldInput
+            name="email"
+            label="Email"
+            type="email"
+            placeholder="Enter your email"
+          />
+        </Box>
+      ),
+      onNext: async () => {
+        // Validate only Step 1 fields
+        return await trigger(['firstName', 'lastName', 'email']);
+      },
+    },
+    {
+      title: 'Address',
+      description: 'Location details',
+      content: (
+        <Box>
+          <FormFieldInput
+            name="street"
+            label="Street"
+            placeholder="Enter your street"
+          />
+          <FormFieldInput
+            name="city"
+            label="City"
+            placeholder="Enter your city"
+          />
+          <FormFieldSelect
+            name="country"
+            label="Country"
+            placeholder="Select your country"
+            options={[
+              { value: 'us', label: 'United States' },
+              { value: 'br', label: 'Brazil' },
+              { value: 'uk', label: 'United Kingdom' },
+            ]}
+          />
+        </Box>
+      ),
+      onNext: async () => {
+        // Validate only Step 2 fields
+        return await trigger(['street', 'city', 'country']);
+      },
+    },
+    {
+      title: 'Additional Info',
+      description: 'Final details',
+      content: (
+        <Box>
+          <FormFieldInput
+            name="phone"
+            label="Phone"
+            placeholder="Enter your phone number"
+          />
+          <FormFieldTextarea
+            name="comments"
+            label="Comments (Optional)"
+            placeholder="Any additional comments"
+          />
+        </Box>
+      ),
+      onNext: async () => {
+        // Validate only Step 3 fields
+        return await trigger(['phone', 'comments']);
+      },
+    },
+    {
+      title: 'Review',
+      description: 'Confirm details',
+      content: (
+        <Box>
+          <Text variant="heading">Review Your Information</Text>
+          {/* Display summary of all form data */}
+        </Box>
+      ),
+    },
+  ];
+
+  return (
+    <Form {...formMethods} onSubmit={handleComplete}>
+      <Wizard
+        steps={steps}
+        layout="top"
+        onComplete={handleComplete}
+        onCancel={() => console.log('Wizard cancelled')}
+      />
+    </Form>
+  );
+};
+```
+
+**Key Points:**
+
+- **Single Form**: The `<Form>` component wraps the entire wizard, maintaining form state across all steps
+- **Step-by-Step Validation**: Each step's `onNext` callback uses `trigger()` to validate only the fields relevant to that step
+- **Zod Schema**: Define the complete schema upfront with all fields from all steps
+- **Form Methods**: Access `trigger` from `useForm` to programmatically validate specific fields
+- **Progressive Flow**: Users can only advance to the next step after passing validation for current step fields
+
+## Example: Complex Component with Internal Validation
+
+This example shows how a complex component can use `useWizard` to handle its own validation directly:
+
+```tsx
+import { Wizard, useWizard } from '@ttoss/react-wizard';
+import { Box, Text } from '@ttoss/ui';
+import { useState, useEffect } from 'react';
+
+// Complex component with internal validation using useWizard
+const ComplexForm = () => {
+  const { setStepValidation } = useWizard();
+
+  const [formData, setFormData] = useState({
+    username: '',
+    password: '',
+    confirmPassword: '',
+  });
+  const [errors, setErrors] = useState<Record<string, string>>({});
+
+  // Register validation function with the wizard
+  useEffect(() => {
+    const validate = async () => {
+      const newErrors: Record<string, string> = {};
+
+      // Complex validation logic
+      if (!formData.username || formData.username.length < 3) {
+        newErrors.username = 'Username must be at least 3 characters';
+      }
+
+      if (!formData.password || formData.password.length < 8) {
+        newErrors.password = 'Password must be at least 8 characters';
+      }
+
+      if (formData.password !== formData.confirmPassword) {
+        newErrors.confirmPassword = 'Passwords do not match';
+      }
+
+      setErrors(newErrors);
+      return Object.keys(newErrors).length === 0;
+    };
+
+    setStepValidation(validate);
+  }, [formData, setStepValidation]);
+
+  return (
+    <Box>
+      <Box>
+        <Text>Username</Text>
+        <input
+          value={formData.username}
+          onChange={(e) =>
+            setFormData({ ...formData, username: e.target.value })
+          }
+        />
+        {errors.username && <Text color="red">{errors.username}</Text>}
+      </Box>
+
+      <Box>
+        <Text>Password</Text>
+        <input
+          type="password"
+          value={formData.password}
+          onChange={(e) =>
+            setFormData({ ...formData, password: e.target.value })
+          }
+        />
+        {errors.password && <Text color="red">{errors.password}</Text>}
+      </Box>
+
+      <Box>
+        <Text>Confirm Password</Text>
+        <input
+          type="password"
+          value={formData.confirmPassword}
+          onChange={(e) =>
+            setFormData({ ...formData, confirmPassword: e.target.value })
+          }
+        />
+        {errors.confirmPassword && (
+          <Text color="red">{errors.confirmPassword}</Text>
+        )}
+      </Box>
+    </Box>
+  );
+};
+
+const WizardWithComplexComponent = () => {
+  const steps = [
+    {
+      title: 'Account Setup',
+      description: 'Create your account',
+      content: <ComplexForm />,
+    },
+    {
+      title: 'Profile',
+      content: <Box>Profile information...</Box>,
+    },
+    {
+      title: 'Complete',
+      content: <Box>Setup complete!</Box>,
+    },
+  ];
+
+  return (
+    <Wizard
+      steps={steps}
+      layout="top"
+      onComplete={() => console.log('Wizard complete!')}
+    />
+  );
+};
+```
+
+**Key Points:**
+
+- **useWizard Hook**: The complex component uses `setStepValidation` from `useWizard` to register its validation function
+- **Automatic Integration**: The wizard automatically calls the registered validation when the user tries to advance
+- **No Refs Needed**: Simpler than using refs and forwardRef patterns
+- **Self-Contained**: The component manages its own state and validation logic
+- **Dynamic Updates**: The validation function updates when formData changes

package/dist/esm/index.js

@@ -0,0 +1,295 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import * as React from 'react';
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", {
+  value,
+  configurable: true
+});
+
+// src/Wizard.tsx
+import { defineMessages, useI18n } from "@ttoss/react-i18n";
+import { Box as Box2, Button, Flex as Flex2 } from "@ttoss/ui";
+import * as React3 from "react";
+
+// src/WizardContext.ts
+import * as React2 from "react";
+var WizardContext = React2.createContext(null);
+var useWizard = /* @__PURE__ */__name(() => {
+  const context = React2.useContext(WizardContext);
+  if (!context) {
+    throw new Error("useWizard must be used within a Wizard component.");
+  }
+  return context;
+}, "useWizard");
+
+// src/WizardStepList.tsx
+import { Steps } from "@chakra-ui/react";
+import { Box, Flex } from "@ttoss/ui";
+var WizardStepList = /* @__PURE__ */__name(({
+  steps,
+  currentStep,
+  layout,
+  allowStepClick,
+  getStepStatus,
+  onStepClick
+}) => {
+  const isHorizontal = layout === "top" || layout === "bottom";
+  const orientation = isHorizontal ? "horizontal" : "vertical";
+  return /* @__PURE__ */React.createElement(Flex, {
+    role: "navigation",
+    "aria-label": "Wizard steps",
+    sx: {
+      padding: "6",
+      backgroundColor: "navigation.background.muted.default",
+      ...(isHorizontal ? {
+        width: "100%",
+        borderBottom: layout === "top" ? "1px solid" : void 0,
+        borderTop: layout === "bottom" ? "1px solid" : void 0,
+        borderColor: "display.border.muted.default"
+      } : {
+        minWidth: "200px",
+        borderRight: layout === "left" ? "1px solid" : void 0,
+        borderLeft: layout === "right" ? "1px solid" : void 0,
+        borderColor: "display.border.muted.default"
+      })
+    }
+  }, /* @__PURE__ */React.createElement(Steps.Root, {
+    step: currentStep,
+    count: steps.length,
+    orientation
+  }, /* @__PURE__ */React.createElement(Steps.List, null, steps.map((step, index) => {
+    const status = getStepStatus({
+      stepIndex: index
+    });
+    const isClickable = allowStepClick && status === "completed" && index !== currentStep;
+    return /* @__PURE__ */React.createElement(Steps.Item, {
+      key: index,
+      index
+    }, /* @__PURE__ */React.createElement(Flex, {
+      sx: {
+        flexDirection: isHorizontal ? "column" : "row",
+        alignItems: "center",
+        gap: "2"
+      }
+    }, /* @__PURE__ */React.createElement(Box, {
+      role: "button",
+      tabIndex: isClickable ? 0 : -1,
+      onClick: /* @__PURE__ */__name(() => {
+        if (isClickable) {
+          onStepClick({
+            stepIndex: index
+          });
+        }
+      }, "onClick"),
+      onKeyDown: /* @__PURE__ */__name(e => {
+        if (isClickable && (e.key === "Enter" || e.key === " ")) {
+          e.preventDefault();
+          onStepClick({
+            stepIndex: index
+          });
+        }
+      }, "onKeyDown"),
+      "aria-current": status === "active" ? "step" : void 0,
+      sx: {
+        cursor: isClickable ? "pointer" : "default"
+      }
+    }, /* @__PURE__ */React.createElement(Steps.Indicator, null, /* @__PURE__ */React.createElement(Steps.Status, {
+      complete: "\u2713",
+      incomplete: /* @__PURE__ */React.createElement(Steps.Number, null)
+    }))), (step.title || step.description) && /* @__PURE__ */React.createElement(Box, null, step.title && /* @__PURE__ */React.createElement(Steps.Title, null, step.title), step.description && /* @__PURE__ */React.createElement(Steps.Description, null, step.description))), index < steps.length - 1 && /* @__PURE__ */React.createElement(Steps.Separator, null));
+  }))));
+}, "WizardStepList");
+
+// src/Wizard.tsx
+var messages = defineMessages({
+  previous: {
+    id: "60eH0J",
+    defaultMessage: [{
+      "type": 0,
+      "value": "Previous"
+    }]
+  },
+  next: {
+    id: "FmaVut",
+    defaultMessage: [{
+      "type": 0,
+      "value": "Next"
+    }]
+  },
+  finish: {
+    id: "5lZ8VT",
+    defaultMessage: [{
+      "type": 0,
+      "value": "Finish"
+    }]
+  },
+  cancel: {
+    id: "6I9gjk",
+    defaultMessage: [{
+      "type": 0,
+      "value": "Cancel"
+    }]
+  }
+});
+var getFlexDirection = /* @__PURE__ */__name(layout => {
+  switch (layout) {
+    case "top":
+      return "column";
+    case "bottom":
+      return "column-reverse";
+    case "left":
+      return "row";
+    case "right":
+      return "row-reverse";
+  }
+}, "getFlexDirection");
+var Wizard = /* @__PURE__ */__name(({
+  steps,
+  layout = "top",
+  onComplete,
+  onCancel,
+  onStepChange,
+  initialStep = 0,
+  allowStepClick = true
+}) => {
+  const {
+    intl
+  } = useI18n();
+  const [currentStep, setCurrentStep] = React3.useState(initialStep);
+  const stepValidationRef = React3.useRef(null);
+  const totalSteps = steps.length;
+  const isFirstStep = currentStep === 0;
+  const isLastStep = currentStep === totalSteps - 1;
+  const getStepStatus = React3.useCallback(({
+    stepIndex
+  }) => {
+    if (stepIndex < currentStep) {
+      return "completed";
+    }
+    if (stepIndex === currentStep) {
+      return "active";
+    }
+    return "upcoming";
+  }, [currentStep]);
+  const goToNext = React3.useCallback(async () => {
+    const step = steps[currentStep];
+    if (stepValidationRef.current) {
+      const canProceed = await stepValidationRef.current();
+      if (!canProceed) {
+        return;
+      }
+    }
+    if (step.onNext) {
+      const canProceed = await step.onNext();
+      if (!canProceed) {
+        return;
+      }
+    }
+    if (isLastStep) {
+      onComplete?.();
+    } else {
+      const nextStep = currentStep + 1;
+      stepValidationRef.current = null;
+      setCurrentStep(nextStep);
+      onStepChange?.({
+        stepIndex: nextStep
+      });
+    }
+  }, [currentStep, steps, isLastStep, onComplete, onStepChange]);
+  const goToPrevious = React3.useCallback(() => {
+    if (!isFirstStep) {
+      const prevStep = currentStep - 1;
+      stepValidationRef.current = null;
+      setCurrentStep(prevStep);
+      onStepChange?.({
+        stepIndex: prevStep
+      });
+    }
+  }, [currentStep, isFirstStep, onStepChange]);
+  const goToStep = React3.useCallback(({
+    stepIndex
+  }) => {
+    if (stepIndex >= 0 && stepIndex < totalSteps && stepIndex <= currentStep) {
+      stepValidationRef.current = null;
+      setCurrentStep(stepIndex);
+      onStepChange?.({
+        stepIndex
+      });
+    }
+  }, [currentStep, totalSteps, onStepChange]);
+  const setStepValidation = React3.useCallback(validate => {
+    stepValidationRef.current = validate;
+  }, []);
+  const contextValue = React3.useMemo(() => {
+    return {
+      currentStep,
+      totalSteps,
+      goToNext,
+      goToPrevious,
+      goToStep,
+      isFirstStep,
+      isLastStep,
+      getStepStatus,
+      setStepValidation
+    };
+  }, [currentStep, totalSteps, goToNext, goToPrevious, goToStep, isFirstStep, isLastStep, getStepStatus, setStepValidation]);
+  return /* @__PURE__ */React3.createElement(WizardContext.Provider, {
+    value: contextValue
+  }, /* @__PURE__ */React3.createElement(Flex2, {
+    sx: {
+      flexDirection: getFlexDirection(layout),
+      width: "100%",
+      minHeight: "300px",
+      border: "1px solid",
+      borderColor: "display.border.muted.default",
+      borderRadius: "8px",
+      overflow: "hidden"
+    }
+  }, /* @__PURE__ */React3.createElement(WizardStepList, {
+    steps,
+    currentStep,
+    layout,
+    allowStepClick,
+    getStepStatus,
+    onStepClick: goToStep
+  }), /* @__PURE__ */React3.createElement(Flex2, {
+    sx: {
+      flexDirection: "column",
+      flex: 1,
+      padding: "6"
+    }
+  }, /* @__PURE__ */React3.createElement(Box2, {
+    sx: {
+      flex: 1,
+      marginBottom: "4"
+    }
+  }, steps[currentStep].content), /* @__PURE__ */React3.createElement(Flex2, {
+    sx: {
+      justifyContent: "space-between",
+      alignItems: "center",
+      gap: "3"
+    }
+  }, /* @__PURE__ */React3.createElement(Flex2, {
+    sx: {
+      gap: "3"
+    }
+  }, onCancel && /* @__PURE__ */React3.createElement(Button, {
+    variant: "secondary",
+    onClick: onCancel,
+    "aria-label": intl.formatMessage(messages.cancel)
+  }, intl.formatMessage(messages.cancel))), /* @__PURE__ */React3.createElement(Flex2, {
+    sx: {
+      gap: "3"
+    }
+  }, /* @__PURE__ */React3.createElement(Button, {
+    variant: "secondary",
+    onClick: goToPrevious,
+    disabled: isFirstStep,
+    "aria-label": intl.formatMessage(messages.previous)
+  }, intl.formatMessage(messages.previous)), /* @__PURE__ */React3.createElement(Button, {
+    onClick: goToNext,
+    "aria-label": isLastStep ? intl.formatMessage(messages.finish) : intl.formatMessage(messages.next)
+  }, isLastStep ? intl.formatMessage(messages.finish) : intl.formatMessage(messages.next)))))));
+}, "Wizard");
+Wizard.displayName = "Wizard";
+export { Wizard, useWizard };

package/dist/index.d.cts

@@ -0,0 +1,128 @@
+import * as React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Position of the step list relative to the wizard content.
+ */
+type WizardLayout = 'top' | 'right' | 'bottom' | 'left';
+/**
+ * Status of a wizard step.
+ */
+type WizardStepStatus = 'completed' | 'active' | 'upcoming';
+/**
+ * Definition of a single wizard step.
+ */
+interface WizardStep {
+    /**
+     * Title displayed in the step list.
+     */
+    title: string;
+    /**
+     * Optional description displayed below the title in the step list.
+     */
+    description?: string;
+    /**
+     * The content rendered when this step is active.
+     */
+    content: React.ReactNode;
+    /**
+     * Called when the user clicks "Next". If it returns false or
+     * a Promise that resolves to false, the wizard will not advance.
+     */
+    onNext?: () => boolean | Promise<boolean>;
+}
+/**
+ * Props for the Wizard component.
+ */
+interface WizardProps {
+    /**
+     * Array of steps to display in the wizard.
+     */
+    steps: WizardStep[];
+    /**
+     * Position of the step list. Defaults to 'top'.
+     */
+    layout?: WizardLayout;
+    /**
+     * Called when the wizard completes (user clicks "Finish" on the last step).
+     */
+    onComplete?: () => void;
+    /**
+     * Called when the user clicks "Cancel".
+     * If not provided, the Cancel button is not rendered.
+     */
+    onCancel?: () => void;
+    /**
+     * Called whenever the active step changes.
+     */
+    onStepChange?: (params: {
+        stepIndex: number;
+    }) => void;
+    /**
+     * The initially active step index. Defaults to 0.
+     */
+    initialStep?: number;
+    /**
+     * Allow clicking on completed steps to navigate back.
+     * Defaults to true.
+     */
+    allowStepClick?: boolean;
+}
+/**
+ * Context value exposed by WizardProvider.
+ */
+interface WizardContextValue {
+    /**
+     * Current active step index.
+     */
+    currentStep: number;
+    /**
+     * Total number of steps.
+     */
+    totalSteps: number;
+    /**
+     * Navigate to the next step.
+     */
+    goToNext: () => Promise<void>;
+    /**
+     * Navigate to the previous step.
+     */
+    goToPrevious: () => void;
+    /**
+     * Navigate to a specific step (only if it's completed or active).
+     */
+    goToStep: (params: {
+        stepIndex: number;
+    }) => void;
+    /**
+     * Whether the wizard is on the first step.
+     */
+    isFirstStep: boolean;
+    /**
+     * Whether the wizard is on the last step.
+     */
+    isLastStep: boolean;
+    /**
+     * Get the status of a step by index.
+     */
+    getStepStatus: (params: {
+        stepIndex: number;
+    }) => WizardStepStatus;
+    /**
+     * Register a validation function for the current step.
+     * This allows step content components to provide their own validation logic.
+     */
+    setStepValidation: (validate: () => boolean | Promise<boolean>) => void;
+}
+
+declare const Wizard: {
+    ({ steps, layout, onComplete, onCancel, onStepChange, initialStep, allowStepClick, }: WizardProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * Hook to access the wizard context from within step content.
+ */
+declare const useWizard: () => WizardContextValue;
+
+export { Wizard, type WizardContextValue, type WizardLayout, type WizardProps, type WizardStep, type WizardStepStatus, useWizard };

package/dist/index.d.ts

@@ -0,0 +1,128 @@
+import * as React from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Position of the step list relative to the wizard content.
+ */
+type WizardLayout = 'top' | 'right' | 'bottom' | 'left';
+/**
+ * Status of a wizard step.
+ */
+type WizardStepStatus = 'completed' | 'active' | 'upcoming';
+/**
+ * Definition of a single wizard step.
+ */
+interface WizardStep {
+    /**
+     * Title displayed in the step list.
+     */
+    title: string;
+    /**
+     * Optional description displayed below the title in the step list.
+     */
+    description?: string;
+    /**
+     * The content rendered when this step is active.
+     */
+    content: React.ReactNode;
+    /**
+     * Called when the user clicks "Next". If it returns false or
+     * a Promise that resolves to false, the wizard will not advance.
+     */
+    onNext?: () => boolean | Promise<boolean>;
+}
+/**
+ * Props for the Wizard component.
+ */
+interface WizardProps {
+    /**
+     * Array of steps to display in the wizard.
+     */
+    steps: WizardStep[];
+    /**
+     * Position of the step list. Defaults to 'top'.
+     */
+    layout?: WizardLayout;
+    /**
+     * Called when the wizard completes (user clicks "Finish" on the last step).
+     */
+    onComplete?: () => void;
+    /**
+     * Called when the user clicks "Cancel".
+     * If not provided, the Cancel button is not rendered.
+     */
+    onCancel?: () => void;
+    /**
+     * Called whenever the active step changes.
+     */
+    onStepChange?: (params: {
+        stepIndex: number;
+    }) => void;
+    /**
+     * The initially active step index. Defaults to 0.
+     */
+    initialStep?: number;
+    /**
+     * Allow clicking on completed steps to navigate back.
+     * Defaults to true.
+     */
+    allowStepClick?: boolean;
+}
+/**
+ * Context value exposed by WizardProvider.
+ */
+interface WizardContextValue {
+    /**
+     * Current active step index.
+     */
+    currentStep: number;
+    /**
+     * Total number of steps.
+     */
+    totalSteps: number;
+    /**
+     * Navigate to the next step.
+     */
+    goToNext: () => Promise<void>;
+    /**
+     * Navigate to the previous step.
+     */
+    goToPrevious: () => void;
+    /**
+     * Navigate to a specific step (only if it's completed or active).
+     */
+    goToStep: (params: {
+        stepIndex: number;
+    }) => void;
+    /**
+     * Whether the wizard is on the first step.
+     */
+    isFirstStep: boolean;
+    /**
+     * Whether the wizard is on the last step.
+     */
+    isLastStep: boolean;
+    /**
+     * Get the status of a step by index.
+     */
+    getStepStatus: (params: {
+        stepIndex: number;
+    }) => WizardStepStatus;
+    /**
+     * Register a validation function for the current step.
+     * This allows step content components to provide their own validation logic.
+     */
+    setStepValidation: (validate: () => boolean | Promise<boolean>) => void;
+}
+
+declare const Wizard: {
+    ({ steps, layout, onComplete, onCancel, onStepChange, initialStep, allowStepClick, }: WizardProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+/**
+ * Hook to access the wizard context from within step content.
+ */
+declare const useWizard: () => WizardContextValue;
+
+export { Wizard, type WizardContextValue, type WizardLayout, type WizardProps, type WizardStep, type WizardStepStatus, useWizard };

package/dist/index.js

@@ -0,0 +1,329 @@
+/** Powered by @ttoss/config. https://ttoss.dev/docs/modules/packages/config/ */
+import * as React from 'react';
+"use strict";
+
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", {
+  value,
+  configurable: true
+});
+var __export = (target, all) => {
+  for (var name in all) __defProp(target, name, {
+    get: all[name],
+    enumerable: true
+  });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+// If the importer is in node compatibility mode or this is not an ESM
+// file that has been converted to a CommonJS file using a Babel-
+// compatible transform (i.e. "__esModule" has not been set), then set
+// "default" to the CommonJS "module.exports" for node compatibility.
+isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+  value: mod,
+  enumerable: true
+}) : target, mod));
+var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
+  value: true
+}), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Wizard: () => Wizard,
+  useWizard: () => useWizard
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/Wizard.tsx
+var import_react_i18n = require("@ttoss/react-i18n");
+var import_ui2 = require("@ttoss/ui");
+var React3 = __toESM(require("react"), 1);
+
+// src/WizardContext.ts
+var React2 = __toESM(require("react"), 1);
+var WizardContext = React2.createContext(null);
+var useWizard = /* @__PURE__ */__name(() => {
+  const context = React2.useContext(WizardContext);
+  if (!context) {
+    throw new Error("useWizard must be used within a Wizard component.");
+  }
+  return context;
+}, "useWizard");
+
+// src/WizardStepList.tsx
+var import_react = require("@chakra-ui/react");
+var import_ui = require("@ttoss/ui");
+var WizardStepList = /* @__PURE__ */__name(({
+  steps,
+  currentStep,
+  layout,
+  allowStepClick,
+  getStepStatus,
+  onStepClick
+}) => {
+  const isHorizontal = layout === "top" || layout === "bottom";
+  const orientation = isHorizontal ? "horizontal" : "vertical";
+  return /* @__PURE__ */React.createElement(import_ui.Flex, {
+    role: "navigation",
+    "aria-label": "Wizard steps",
+    sx: {
+      padding: "6",
+      backgroundColor: "navigation.background.muted.default",
+      ...(isHorizontal ? {
+        width: "100%",
+        borderBottom: layout === "top" ? "1px solid" : void 0,
+        borderTop: layout === "bottom" ? "1px solid" : void 0,
+        borderColor: "display.border.muted.default"
+      } : {
+        minWidth: "200px",
+        borderRight: layout === "left" ? "1px solid" : void 0,
+        borderLeft: layout === "right" ? "1px solid" : void 0,
+        borderColor: "display.border.muted.default"
+      })
+    }
+  }, /* @__PURE__ */React.createElement(import_react.Steps.Root, {
+    step: currentStep,
+    count: steps.length,
+    orientation
+  }, /* @__PURE__ */React.createElement(import_react.Steps.List, null, steps.map((step, index) => {
+    const status = getStepStatus({
+      stepIndex: index
+    });
+    const isClickable = allowStepClick && status === "completed" && index !== currentStep;
+    return /* @__PURE__ */React.createElement(import_react.Steps.Item, {
+      key: index,
+      index
+    }, /* @__PURE__ */React.createElement(import_ui.Flex, {
+      sx: {
+        flexDirection: isHorizontal ? "column" : "row",
+        alignItems: "center",
+        gap: "2"
+      }
+    }, /* @__PURE__ */React.createElement(import_ui.Box, {
+      role: "button",
+      tabIndex: isClickable ? 0 : -1,
+      onClick: /* @__PURE__ */__name(() => {
+        if (isClickable) {
+          onStepClick({
+            stepIndex: index
+          });
+        }
+      }, "onClick"),
+      onKeyDown: /* @__PURE__ */__name(e => {
+        if (isClickable && (e.key === "Enter" || e.key === " ")) {
+          e.preventDefault();
+          onStepClick({
+            stepIndex: index
+          });
+        }
+      }, "onKeyDown"),
+      "aria-current": status === "active" ? "step" : void 0,
+      sx: {
+        cursor: isClickable ? "pointer" : "default"
+      }
+    }, /* @__PURE__ */React.createElement(import_react.Steps.Indicator, null, /* @__PURE__ */React.createElement(import_react.Steps.Status, {
+      complete: "\u2713",
+      incomplete: /* @__PURE__ */React.createElement(import_react.Steps.Number, null)
+    }))), (step.title || step.description) && /* @__PURE__ */React.createElement(import_ui.Box, null, step.title && /* @__PURE__ */React.createElement(import_react.Steps.Title, null, step.title), step.description && /* @__PURE__ */React.createElement(import_react.Steps.Description, null, step.description))), index < steps.length - 1 && /* @__PURE__ */React.createElement(import_react.Steps.Separator, null));
+  }))));
+}, "WizardStepList");
+
+// src/Wizard.tsx
+var messages = (0, import_react_i18n.defineMessages)({
+  previous: {
+    defaultMessage: "Previous",
+    description: "Label for the previous step button in the wizard."
+  },
+  next: {
+    defaultMessage: "Next",
+    description: "Label for the next step button in the wizard."
+  },
+  finish: {
+    defaultMessage: "Finish",
+    description: "Label for the finish button on the last wizard step."
+  },
+  cancel: {
+    defaultMessage: "Cancel",
+    description: "Label for the cancel button in the wizard."
+  }
+});
+var getFlexDirection = /* @__PURE__ */__name(layout => {
+  switch (layout) {
+    case "top":
+      return "column";
+    case "bottom":
+      return "column-reverse";
+    case "left":
+      return "row";
+    case "right":
+      return "row-reverse";
+  }
+}, "getFlexDirection");
+var Wizard = /* @__PURE__ */__name(({
+  steps,
+  layout = "top",
+  onComplete,
+  onCancel,
+  onStepChange,
+  initialStep = 0,
+  allowStepClick = true
+}) => {
+  const {
+    intl
+  } = (0, import_react_i18n.useI18n)();
+  const [currentStep, setCurrentStep] = React3.useState(initialStep);
+  const stepValidationRef = React3.useRef(null);
+  const totalSteps = steps.length;
+  const isFirstStep = currentStep === 0;
+  const isLastStep = currentStep === totalSteps - 1;
+  const getStepStatus = React3.useCallback(({
+    stepIndex
+  }) => {
+    if (stepIndex < currentStep) {
+      return "completed";
+    }
+    if (stepIndex === currentStep) {
+      return "active";
+    }
+    return "upcoming";
+  }, [currentStep]);
+  const goToNext = React3.useCallback(async () => {
+    const step = steps[currentStep];
+    if (stepValidationRef.current) {
+      const canProceed = await stepValidationRef.current();
+      if (!canProceed) {
+        return;
+      }
+    }
+    if (step.onNext) {
+      const canProceed = await step.onNext();
+      if (!canProceed) {
+        return;
+      }
+    }
+    if (isLastStep) {
+      onComplete?.();
+    } else {
+      const nextStep = currentStep + 1;
+      stepValidationRef.current = null;
+      setCurrentStep(nextStep);
+      onStepChange?.({
+        stepIndex: nextStep
+      });
+    }
+  }, [currentStep, steps, isLastStep, onComplete, onStepChange]);
+  const goToPrevious = React3.useCallback(() => {
+    if (!isFirstStep) {
+      const prevStep = currentStep - 1;
+      stepValidationRef.current = null;
+      setCurrentStep(prevStep);
+      onStepChange?.({
+        stepIndex: prevStep
+      });
+    }
+  }, [currentStep, isFirstStep, onStepChange]);
+  const goToStep = React3.useCallback(({
+    stepIndex
+  }) => {
+    if (stepIndex >= 0 && stepIndex < totalSteps && stepIndex <= currentStep) {
+      stepValidationRef.current = null;
+      setCurrentStep(stepIndex);
+      onStepChange?.({
+        stepIndex
+      });
+    }
+  }, [currentStep, totalSteps, onStepChange]);
+  const setStepValidation = React3.useCallback(validate => {
+    stepValidationRef.current = validate;
+  }, []);
+  const contextValue = React3.useMemo(() => {
+    return {
+      currentStep,
+      totalSteps,
+      goToNext,
+      goToPrevious,
+      goToStep,
+      isFirstStep,
+      isLastStep,
+      getStepStatus,
+      setStepValidation
+    };
+  }, [currentStep, totalSteps, goToNext, goToPrevious, goToStep, isFirstStep, isLastStep, getStepStatus, setStepValidation]);
+  return /* @__PURE__ */React3.createElement(WizardContext.Provider, {
+    value: contextValue
+  }, /* @__PURE__ */React3.createElement(import_ui2.Flex, {
+    sx: {
+      flexDirection: getFlexDirection(layout),
+      width: "100%",
+      minHeight: "300px",
+      border: "1px solid",
+      borderColor: "display.border.muted.default",
+      borderRadius: "8px",
+      overflow: "hidden"
+    }
+  }, /* @__PURE__ */React3.createElement(WizardStepList, {
+    steps,
+    currentStep,
+    layout,
+    allowStepClick,
+    getStepStatus,
+    onStepClick: goToStep
+  }), /* @__PURE__ */React3.createElement(import_ui2.Flex, {
+    sx: {
+      flexDirection: "column",
+      flex: 1,
+      padding: "6"
+    }
+  }, /* @__PURE__ */React3.createElement(import_ui2.Box, {
+    sx: {
+      flex: 1,
+      marginBottom: "4"
+    }
+  }, steps[currentStep].content), /* @__PURE__ */React3.createElement(import_ui2.Flex, {
+    sx: {
+      justifyContent: "space-between",
+      alignItems: "center",
+      gap: "3"
+    }
+  }, /* @__PURE__ */React3.createElement(import_ui2.Flex, {
+    sx: {
+      gap: "3"
+    }
+  }, onCancel && /* @__PURE__ */React3.createElement(import_ui2.Button, {
+    variant: "secondary",
+    onClick: onCancel,
+    "aria-label": intl.formatMessage(messages.cancel)
+  }, intl.formatMessage(messages.cancel))), /* @__PURE__ */React3.createElement(import_ui2.Flex, {
+    sx: {
+      gap: "3"
+    }
+  }, /* @__PURE__ */React3.createElement(import_ui2.Button, {
+    variant: "secondary",
+    onClick: goToPrevious,
+    disabled: isFirstStep,
+    "aria-label": intl.formatMessage(messages.previous)
+  }, intl.formatMessage(messages.previous)), /* @__PURE__ */React3.createElement(import_ui2.Button, {
+    onClick: goToNext,
+    "aria-label": isLastStep ? intl.formatMessage(messages.finish) : intl.formatMessage(messages.next)
+  }, isLastStep ? intl.formatMessage(messages.finish) : intl.formatMessage(messages.next)))))));
+}, "Wizard");
+Wizard.displayName = "Wizard";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Wizard,
+  useWizard
+});

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@ttoss/react-wizard",
+  "version": "0.2.0",
+  "description": "A React wizard component for guiding users through multi-step flows with configurable step list layouts.",
+  "license": "MIT",
+  "author": "ttoss",
+  "contributors": [
+    "Pedro Arantes <pedro@arantespp.com> (https://arantespp.com/contact)"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ttoss/ttoss.git",
+    "directory": "packages/react-wizard"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "peerDependencies": {
+    "@chakra-ui/react": "^3",
+    "react": ">=16.8.0",
+    "react-icons": "^5",
+    "@ttoss/react-i18n": "^2.1.0",
+    "@ttoss/ui": "^6.6.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/react": "^19.2.14",
+    "jest": "^30.2.0",
+    "react": "^19.2.4",
+    "tsup": "^8.5.1",
+    "@ttoss/i18n-cli": "^0.7.39",
+    "@ttoss/config": "^1.36.0",
+    "@ttoss/forms": "^0.41.0",
+    "@ttoss/test-utils": "^4.1.0",
+    "@ttoss/ui": "^6.6.0",
+    "@ttoss/react-i18n": "^2.1.0"
+  },
+  "keywords": [
+    "React",
+    "multi-step",
+    "stepper",
+    "ui",
+    "wizard"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup",
+    "i18n": "ttoss-i18n",
+    "test": "jest --projects tests/unit"
+  }
+}