docs(useWizard): document the hook with stories

packages/core/src/hooks/useWizard/__stories__/useWizard.mdx

@@ -0,0 +1,82 @@
+import { Meta } from "@storybook/blocks";
+import { FunctionArgument, FunctionArguments } from "vibe-storybook-components";
+import * as UseWizardStories from "./useWizard.stories";
+
+<Meta of={UseWizardStories} />
+
+# useWizard
+
+- [Overview](#overview)
+- [Variants](#variants)
+- [Arguments](#arguments)
+- [Returns](#returns)
+- [Feedback](#feedback)
+
+## Overview
+
+A custom hook for managing multi-step wizards. It provides state and functions to navigate between steps, along with directionality information.
+
+<Canvas of={UseWizardStories.Overview} />
+
+## Variants
+
+### With Initial Step
+
+Start the wizard from a custom initial step using the `initialStep` parameter.
+
+<Canvas of={UseWizardStories.WithInitialStep} />
+
+### With Completion Handler
+
+Execute a callback when the wizard reaches the final step using the `onComplete` parameter.
+
+<Canvas of={UseWizardStories.WithCompletion} />
+
+### With Steps component
+
+<Canvas of={UseWizardStories.WithStepsComponent} />
+
+## Arguments
+
+<FunctionArguments>
+  <FunctionArgument name="options" type="Object">
+    <FunctionArgument name="initialStep" type="number" description="The starting step of the wizard. Defaults to 0." />
+    <FunctionArgument name="stepCount" type="number" description="Total number of steps in the wizard." />
+    <FunctionArgument
+      name="onStepChange"
+      type="(newStep: number, oldStep: number) => void"
+      description="Callback invoked when the active step changes."
+    />
+    <FunctionArgument name="onComplete" type="() => void" description="Callback invoked when the wizard completes." />
+  </FunctionArgument>
+</FunctionArguments>
+
+## Returns
+
+<FunctionArguments>
+  <FunctionArgument name="result" type="Object">
+    <FunctionArgument name="activeStep" type="number" description="The current active step." />
+    <FunctionArgument
+      name="direction"
+      type='"forward" | "backward"'
+      description="The direction of the last step change."
+    />
+    <FunctionArgument name="next" type="() => void" description="Function to proceed to the next step." />
+    <FunctionArgument name="back" type="() => void" description="Function to go back to the previous step." />
+    <FunctionArgument
+      name="goToStep"
+      type="(newStep: number) => void"
+      description="Function to navigate to a specific step."
+    />
+    <FunctionArgument
+      name="canGoNext"
+      type="boolean"
+      description="Indicates if it's possible to go to the next step."
+    />
+    <FunctionArgument
+      name="canGoBack"
+      type="boolean"
+      description="Indicates if it's possible to go back to the previous step."
+    />
+  </FunctionArgument>
+</FunctionArguments>

packages/core/src/hooks/useWizard/__stories__/useWizard.stories.module.scss

@@ -0,0 +1,6 @@
+.stepper {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+}

packages/core/src/hooks/useWizard/__stories__/useWizard.stories.tsx

@@ -0,0 +1,129 @@
+import React from "react";
+import useWizard from "../useWizard";
+import { Button, Flex } from "../../../components";
+import Steps from "../../../components/Steps/Steps";
+import Heading from "../../../components/Heading/Heading";
+import { Decorator } from "@storybook/react";
+import styles from "./useWizard.stories.module.scss";
+
+const withUseWizardDecorator: Decorator = Story => (
+  <Flex direction={Flex.directions.COLUMN} gap={Flex.gaps.MEDIUM}>
+    <Story />
+  </Flex>
+);
+
+export default {
+  title: "Hooks/useWizard",
+  decorators: [withUseWizardDecorator]
+};
+
+export const Overview = {
+  render: () => {
+    const { activeStep, next, back, canGoNext, canGoBack } = useWizard({
+      stepCount: 5
+    });
+
+    return (
+      <>
+        <Heading weight={Heading.weights.MEDIUM} type={Heading.types.H3}>
+          Active Step: {activeStep}
+        </Heading>
+        <Flex gap={Flex.gaps.SMALL}>
+          <Button kind={Button.kinds.TERTIARY} onClick={back} disabled={!canGoBack}>
+            Back
+          </Button>
+          <Button onClick={next} disabled={!canGoNext}>
+            Next
+          </Button>
+        </Flex>
+      </>
+    );
+  }
+};
+
+export const WithInitialStep = {
+  render: () => {
+    const { activeStep, next, back, canGoNext, canGoBack } = useWizard({
+      initialStep: 2,
+      stepCount: 5
+    });
+
+    return (
+      <>
+        <Heading weight={Heading.weights.MEDIUM} type={Heading.types.H3}>
+          Active Step: {activeStep}
+        </Heading>
+        <Flex gap={Flex.gaps.SMALL}>
+          <Button kind={Button.kinds.TERTIARY} onClick={back} disabled={!canGoBack}>
+            Back
+          </Button>
+          <Button onClick={next} disabled={!canGoNext}>
+            Next
+          </Button>
+        </Flex>
+      </>
+    );
+  }
+};
+
+export const WithCompletion = {
+  render: () => {
+    const { activeStep, next, back, canGoNext, canGoBack } = useWizard({
+      stepCount: 3,
+      onComplete: () => alert("Wizard Completed!")
+    });
+
+    return (
+      <>
+        <Heading weight={Heading.weights.MEDIUM} type={Heading.types.H3}>
+          Active Step: {activeStep}
+        </Heading>
+        <Flex gap={Flex.gaps.SMALL}>
+          <Button kind={Button.kinds.TERTIARY} onClick={back} disabled={!canGoBack}>
+            Back
+          </Button>
+          <Button onClick={next} disabled={!canGoNext}>
+            Next
+          </Button>
+        </Flex>
+      </>
+    );
+  }
+};
+
+export const WithStepsComponent = {
+  render: () => {
+    const { activeStep, next, back, canGoNext, canGoBack, goToStep } = useWizard({
+      stepCount: 5
+    });
+
+    const stepsContent = [
+      <div>Step 1</div>,
+      <div>Step 2</div>,
+      <div>Step 3</div>,
+      <div>Step 4</div>,
+      <div>Step 5</div>
+    ];
+
+    return (
+      <>
+        <Steps
+          className={styles.stepper}
+          areNavigationButtonsHidden
+          isContentOnTop
+          steps={stepsContent}
+          activeStepIndex={activeStep}
+          onChangeActiveStep={(_e, stepIndex) => goToStep(stepIndex)}
+        />
+        <Flex gap={Flex.gaps.SMALL}>
+          <Button kind={Button.kinds.TERTIARY} onClick={back} disabled={!canGoBack}>
+            Back
+          </Button>
+          <Button onClick={next} disabled={!canGoNext}>
+            Next
+          </Button>
+        </Flex>
+      </>
+    );
+  }
+};