@zentauri-ui/zentauri-components 1.5.22 → 1.6.0

package/src/ui/dropdown/variants.ts

@@ -5,41 +5,49 @@ export const triggerVariants = cva(
   {
     variants: {
       variant: {
-        default: "bg-gray-900 text-white",
-        outline: "border border-gray-300",
-        ghost: "bg-transparent",
+        default: "bg-gray-200 dark:bg-gray-900 text-slate-900 dark:text-white",
+        outline:
+          "border border-gray-700 dark:border-gray-300 text-gray-900 dark:text-gray-100",
+        ghost: "bg-transparent text-gray-900 dark:text-gray-100",
         white: "bg-white text-gray-900",
         black: "bg-black text-white",
-        sky: "border border-sky-600 text-sky-600",
-        rose: "border border-rose-600 text-rose-600",
-        purple: "border border-purple-600 text-purple-600",
-        pink: "border border-pink-600 text-pink-600",
-        orange: "border border-orange-600 text-orange-600",
-        yellow: "border border-yellow-600 text-yellow-600",
-        teal: "border border-teal-600 text-teal-600",
-        indigo: "border border-indigo-600 text-indigo-600",
-        emerald: "border border-emerald-600 text-emerald-600",
-        gray: "border border-gray-600 text-gray-600",
-        amber: "border border-amber-600 text-amber-600",
-        violet: "border border-violet-600 text-violet-600",
+        sky: "border border-sky-800 dark:border-sky-600 text-sky-800 dark:text-sky-600",
+        rose: "border border-rose-800 dark:border-rose-600 text-rose-800 dark:text-rose-600",
+        purple:
+          "border border-purple-800 dark:border-purple-600 text-purple-800 dark:text-purple-600",
+        pink: "border border-pink-800 dark:border-pink-600 text-pink-800 dark:text-pink-600",
+        orange:
+          "border border-orange-800 dark:border-orange-600 text-orange-800 dark:text-orange-600",
+        yellow:
+          "border border-yellow-800 dark:border-yellow-600 text-yellow-800 dark:text-yellow-600",
+        teal: "border border-teal-800 dark:border-teal-600 text-teal-800 dark:text-teal-600",
+        indigo:
+          "border border-indigo-800 dark:border-indigo-600 text-indigo-800 dark:text-indigo-600",
+        emerald:
+          "border border-emerald-800 dark:border-emerald-600 text-emerald-800 dark:text-emerald-600",
+        gray: "border border-gray-800 dark:border-gray-600 text-gray-800 dark:text-gray-600",
+        amber:
+          "border border-amber-800 dark:border-amber-600 text-amber-800 dark:text-amber-600",
+        violet:
+          "border border-violet-800 dark:border-violet-600 text-violet-800 dark:text-violet-600",
         "gradient-blue":
-          "bg-linear-to-r from-blue-600 to-purple-600 text-blue-200",
+          "bg-linear-to-r from-blue-800 dark:from-blue-600 to-purple-800 dark:to-purple-600 text-blue-200",
         "gradient-green":
-          "bg-linear-to-r from-green-600 to-lime-600 text-green-200",
+          "bg-linear-to-r from-green-800 dark:from-green-600 to-lime-800 dark:to-lime-600 text-green-200",
         "gradient-red":
-          "bg-linear-to-r from-red-600 to-pink-600 text-red-200",
+          "bg-linear-to-r from-red-800 dark:from-red-600 to-pink-800 dark:to-pink-600 text-red-200",
         "gradient-yellow":
-          "bg-linear-to-r from-yellow-600 to-orange-600 text-yellow-200",
+          "bg-linear-to-r from-yellow-800 dark:from-yellow-600 to-orange-800 dark:to-orange-600 text-yellow-200",
         "gradient-purple":
-          "bg-linear-to-r from-purple-600 to-pink-600 text-purple-200",
+          "bg-linear-to-r from-purple-800 dark:from-purple-600 to-pink-800 dark:to-pink-600 text-purple-200",
         "gradient-teal":
-          "bg-linear-to-r from-teal-600 to-cyan-600 text-teal-200",
+          "bg-linear-to-r from-teal-800 dark:from-teal-600 to-cyan-800 dark:to-cyan-600 text-teal-200",
         "gradient-indigo":
-          "bg-linear-to-r from-indigo-600 to-purple-600 text-indigo-200",
+          "bg-linear-to-r from-indigo-800 dark:from-indigo-600 to-purple-800 dark:to-purple-600 text-indigo-200",
         "gradient-pink":
-          "bg-linear-to-r from-pink-600 to-rose-600 text-pink-200",
+          "bg-linear-to-r from-pink-800 dark:from-pink-600 to-rose-800 dark:to-rose-600 text-pink-200",
         "gradient-orange":
-          "bg-linear-to-r from-orange-600 to-red-600 text-orange-200",
+          "bg-linear-to-r from-orange-800 dark:from-orange-600 to-red-800 dark:to-red-600 text-orange-200",
       },
       size: {
         sm: "px-2 py-1 text-sm",
@@ -55,7 +63,7 @@ export const triggerVariants = cva(
 );
 
 export const contentVariants = cva(
-  "absolute min-w-[200px] rounded-md p-2 shadow-md z-50 border",
+  "absolute min-w-[200px] rounded-md p-2 shadow-md z-50 border border-slate-900/10 dark:border-white/10 bg-slate-100 dark:bg-slate-900 text-slate-900 dark:text-slate-100 shadow-lg rounded-lg",
   {
     variants: {
       placement: {
@@ -81,54 +89,57 @@ export const contentVariants = cva(
 );
 
 export const itemVariants = cva(
-  "flex items-center justify-between px-3 py-2 text-sm cursor-pointer rounded-md transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-500/60",
+  "flex items-center justify-between px-3 py-2 text-sm cursor-pointer rounded-md transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-gray-500/60 font-semibold",
   {
     variants: {
       variant: {
-        default: "hover:bg-gray-100 hover:text-gray-900 text-gray-100",
+        default:
+          "hover:bg-gray-100 hover:text-gray-500 dark:hover:text-gray-900 text-gray-900 dark:text-gray-100",
         outline:
-          "hover:bg-gray-100 hover:text-gray-900 border border-white text-gray-100",
+          "hover:bg-gray-100 hover:text-gray-500 dark:hover:text-gray-900 border border-black dark:border-white text-gray-900 dark:text-gray-100",
         ghost:
-          "hover:bg-gray-100 hover:text-gray-900 bg-transparent text-gray-100",
-        white: "hover:bg-gray-100 hover:text-gray-900 bg-white text-gray-900",
-        black: "hover:bg-gray-100 hover:text-gray-900 bg-black text-white",
-        sky: "hover:bg-sky-100 hover:text-sky-600 bg-sky-200 text-sky-800",
-        rose: "hover:bg-rose-100 hover:text-rose-600 bg-rose-200 text-rose-800",
+          "hover:bg-gray-100 hover:text-gray-500 dark:hover:text-gray-900 bg-transparent text-gray-900 dark:text-gray-100",
+        white:
+          "hover:bg-gray-100 hover:text-gray-500 dark:hover:text-gray-900 bg-white dark:bg-black text-gray-900 dark:text-white",
+        black:
+          "hover:bg-gray-100 hover:text-gray-500 dark:hover:text-gray-900 bg-black dark:bg-white text-white dark:text-gray-900",
+        sky: "hover:bg-sky-100 hover:text-sky-800 dark:hover:text-sky-600 bg-sky-200 text-sky-900 dark:text-sky-800",
+        rose: "hover:bg-rose-100 hover:text-rose-800 dark:hover:text-rose-600 bg-rose-200 text-rose-900 dark:text-rose-800",
         purple:
-          "hover:bg-purple-100 hover:text-purple-600 bg-purple-200 text-purple-800",
-        pink: "hover:bg-pink-100 hover:text-pink-600 bg-pink-200 text-pink-800",
+          "hover:bg-purple-100 hover:text-purple-800 dark:hover:text-purple-600 bg-purple-200 text-purple-900 dark:text-purple-800",
+        pink: "hover:bg-pink-100 hover:text-pink-800 dark:hover:text-pink-600 bg-pink-200 text-pink-900 dark:text-pink-800",
         orange:
-          "hover:bg-orange-100 hover:text-orange-600 bg-orange-200 text-orange-800",
+          "hover:bg-orange-100 hover:text-orange-800 dark:hover:text-orange-600 bg-orange-200 text-orange-900 dark:text-orange-800",
         yellow:
-          "hover:bg-yellow-100 hover:text-yellow-600 bg-yellow-200 text-yellow-800",
-        teal: "hover:bg-teal-100 hover:text-teal-600 bg-teal-200 text-teal-800",
+          "hover:bg-yellow-100 hover:text-yellow-800 dark:hover:text-yellow-600 bg-yellow-200 text-yellow-900 dark:text-yellow-800",
+        teal: "hover:bg-teal-100 hover:text-teal-800 dark:hover:text-teal-600 bg-teal-200 text-teal-900 dark:text-teal-800",
         indigo:
-          "hover:bg-indigo-100 hover:text-indigo-600 bg-indigo-200 text-indigo-800",
+          "hover:bg-indigo-100 hover:text-indigo-800 dark:hover:text-indigo-600 bg-indigo-200 text-indigo-900 dark:text-indigo-800",
         emerald:
-          "hover:bg-emerald-100 hover:text-emerald-600 bg-emerald-200 text-emerald-800",
-        gray: "hover:bg-gray-100 hover:text-gray-900 bg-gray-200 text-gray-800",
+          "hover:bg-emerald-100 hover:text-emerald-800 dark:hover:text-emerald-600 bg-emerald-200 text-emerald-900 dark:text-emerald-800",
+        gray: "hover:bg-gray-100 hover:text-gray-500 dark:hover:text-gray-900 bg-gray-200 text-gray-500 dark:text-gray-800",
         amber:
-          "hover:bg-amber-100 hover:text-amber-600 bg-amber-200 text-amber-800",
+          "hover:bg-amber-100 hover:text-amber-800 dark:hover:text-amber-600 bg-amber-200 text-amber-900 dark:text-amber-800",
         violet:
-          "hover:bg-violet-100 hover:text-violet-600 bg-violet-200 text-violet-800",
+          "hover:bg-violet-100 hover:text-violet-800 dark:hover:text-violet-600 bg-violet-200 text-violet-900 dark:text-violet-800",
         "gradient-blue":
-          "hover:bg-linear-to-r from-blue-600 to-purple-600 hover:text-blue-900 bg-linear-to-r from-blue-200 to-purple-200 text-blue-800",
+          "hover:bg-linear-to-r from-blue-800 dark:from-blue-600 to-purple-800 dark:to-purple-600 hover:text-blue-500 dark:hover:text-blue-900 bg-linear-to-r from-blue-200 to-purple-200 text-blue-900 dark:text-blue-200",
         "gradient-green":
-          "hover:bg-linear-to-r from-green-600 to-lime-600 hover:text-green-900 bg-linear-to-r from-green-200 to-lime-200 text-green-800",
+          "hover:bg-linear-to-r from-green-800 dark:from-green-600 to-lime-800 dark:to-lime-600 hover:text-green-500 dark:hover:text-green-900 bg-linear-to-r from-green-200 to-lime-200 text-green-900 dark:text-green-200",
         "gradient-red":
-          "hover:bg-linear-to-r from-red-600 to-pink-600 hover:text-red-900 bg-linear-to-r from-red-200 to-pink-200 text-red-800",
+          "hover:bg-linear-to-r from-red-800 dark:from-red-600 to-pink-800 dark:to-pink-600 hover:text-red-500 dark:hover:text-red-900 bg-linear-to-r from-red-200 to-pink-200 text-red-900 dark:text-red-200",
         "gradient-yellow":
-          "hover:bg-linear-to-r from-yellow-600 to-orange-600 hover:text-yellow-900 bg-linear-to-r from-yellow-200 to-orange-200 text-yellow-800",
+          "hover:bg-linear-to-r from-yellow-800 dark:from-yellow-600 to-orange-800 dark:to-orange-600 hover:text-yellow-500 dark:hover:text-yellow-900 bg-linear-to-r from-yellow-200 to-orange-200 text-yellow-900 dark:text-yellow-200",
         "gradient-purple":
-          "hover:bg-linear-to-r from-purple-600 to-pink-600 hover:text-purple-900 bg-linear-to-r from-purple-200 to-pink-200 text-purple-800",
+          "hover:bg-linear-to-r from-purple-800 dark:from-purple-600 to-pink-800 dark:to-pink-600 hover:text-purple-500 dark:hover:text-purple-900 bg-linear-to-r from-purple-200 to-pink-200 text-purple-900 dark:text-purple-200",
         "gradient-teal":
-          "hover:bg-linear-to-r from-teal-600 to-cyan-600 hover:text-teal-900 bg-linear-to-r from-teal-200 to-cyan-200 text-teal-800",
+          "hover:bg-linear-to-r from-teal-800 dark:from-teal-600 to-cyan-800 dark:to-cyan-600 hover:text-teal-500 dark:hover:text-teal-900 bg-linear-to-r from-teal-200 to-cyan-200 text-teal-900 dark:text-teal-200",
         "gradient-indigo":
-          "hover:bg-linear-to-r from-indigo-600 to-purple-600 hover:text-indigo-900 bg-linear-to-r from-indigo-200 to-purple-200 text-indigo-800",
+          "hover:bg-linear-to-r from-indigo-800 dark:from-indigo-600 to-purple-800 dark:to-purple-600 hover:text-indigo-500 dark:hover:text-indigo-900 bg-linear-to-r from-indigo-200 to-purple-200 text-indigo-900 dark:text-indigo-200",
         "gradient-pink":
-          "hover:bg-linear-to-r from-pink-600 to-rose-600 hover:text-pink-900 bg-linear-to-r from-pink-200 to-rose-200 text-pink-800",
+          "hover:bg-linear-to-r from-pink-800 dark:from-pink-600 to-rose-800 dark:to-rose-600 hover:text-pink-500 dark:hover:text-pink-900 bg-linear-to-r from-pink-200 to-rose-200 text-pink-900 dark:text-pink-200",
         "gradient-orange":
-          "hover:bg-linear-to-r from-orange-600 to-red-600 hover:text-orange-900 bg-linear-to-r from-orange-200 to-red-200 text-orange-800",
+          "hover:bg-linear-to-r from-orange-800 dark:from-orange-600 to-red-800 dark:to-red-600 hover:text-orange-500 dark:hover:text-orange-900 bg-linear-to-r from-orange-200 to-red-200 text-orange-900 dark:text-orange-200",
       },
     },
     defaultVariants: {

package/src/ui/dynamic-stepper/dynamic-stepper.test.tsx

@@ -0,0 +1,113 @@
+import { createRef } from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { DynamicStepper } from "./dynamic-stepper";
+
+const sampleSteps = [
+  { id: "a", title: "One", description: "First" },
+  { id: "b", title: "Two", description: "Second" },
+  { id: "c", title: "Three", description: "Third" },
+];
+
+describe("DynamicStepper", () => {
+  it("should expose displayName", () => {
+    expect(DynamicStepper.displayName).toBe("DynamicStepper");
+  });
+
+  it("should render null when steps is empty", () => {
+    const { container } = render(<DynamicStepper steps={[]} />);
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("should stamp mapper ol and button ids with suffixes", () => {
+    render(<DynamicStepper steps={sampleSteps} />);
+    const mapper = document.querySelector(
+      '[data-slot="dynamic-stepper-mapper"]',
+    );
+    expect(mapper?.tagName).toBe("OL");
+    expect(mapper?.id.endsWith("-mapper")).toBe(true);
+
+    const prev = document.querySelector(
+      '[data-slot="dynamic-stepper-previous"]',
+    );
+    const next = document.querySelector('[data-slot="dynamic-stepper-next"]');
+    expect(prev?.id.endsWith("-previous")).toBe(true);
+    expect(next?.id.endsWith("-next")).toBe(true);
+  });
+
+  it("should navigate uncontrolled with next and previous", async () => {
+    const user = userEvent.setup();
+    render(<DynamicStepper steps={sampleSteps} defaultActiveStep={0} />);
+
+    expect(screen.getByText("One")).toBeInTheDocument();
+    const indicators = document.querySelectorAll(
+      '[data-slot="dynamic-stepper-indicator"]',
+    );
+    expect(indicators[0]?.className).toMatch(/violet/);
+
+    await user.click(screen.getByRole("button", { name: "Next" }));
+    expect(indicators[1]?.className).toMatch(/violet/);
+
+    await user.click(screen.getByRole("button", { name: "Previous" }));
+    expect(indicators[0]?.className).toMatch(/violet/);
+  });
+
+  it("should disable previous on first step and next on last step", () => {
+    render(<DynamicStepper steps={sampleSteps} defaultActiveStep={0} />);
+    expect(screen.getByRole("button", { name: "Previous" })).toBeDisabled();
+    expect(screen.getByRole("button", { name: "Next" })).not.toBeDisabled();
+  });
+
+  it("should respect controlled activeStep", async () => {
+    const user = userEvent.setup();
+    const onActiveStepChange = vi.fn();
+    const { rerender } = render(
+      <DynamicStepper
+        steps={sampleSteps}
+        activeStep={0}
+        onActiveStepChange={onActiveStepChange}
+      />,
+    );
+
+    await user.click(screen.getByRole("button", { name: "Next" }));
+    expect(onActiveStepChange).toHaveBeenCalledWith(1);
+
+    rerender(
+      <DynamicStepper
+        steps={sampleSteps}
+        activeStep={1}
+        onActiveStepChange={onActiveStepChange}
+      />,
+    );
+    const indicators = document.querySelectorAll(
+      '[data-slot="dynamic-stepper-indicator"]',
+    );
+    expect(indicators[1]?.className).toMatch(/violet/);
+  });
+
+  it("should forward ref to root", () => {
+    const ref = createRef<HTMLDivElement>();
+    render(<DynamicStepper ref={ref} steps={sampleSteps} />);
+    expect(ref.current?.getAttribute("data-slot")).toBe("dynamic-stepper");
+  });
+
+  it("should apply indicator tone props to semantic states", () => {
+    const { container } = render(
+      <DynamicStepper
+        steps={sampleSteps}
+        defaultActiveStep={1}
+        indicatorCompleteAppearance="sky"
+        indicatorCurrentAppearance="rose"
+        indicatorUpcomingAppearance="amber"
+      />,
+    );
+    const indicators = container.querySelectorAll(
+      '[data-slot="dynamic-stepper-indicator"]',
+    );
+    expect(indicators[0]?.className).toMatch(/sky-/);
+    expect(indicators[1]?.className).toMatch(/rose-/);
+    expect(indicators[2]?.className).toMatch(/amber-/);
+  });
+});

package/src/ui/dynamic-stepper/dynamic-stepper.tsx

@@ -0,0 +1,173 @@
+"use client";
+
+import { useId } from "react";
+
+import { useDynamicStepper } from "../../hooks/useDynamicStepper/useDynamicStepper";
+import { cn } from "../../lib/utils";
+import { Button } from "../buttons/button";
+
+import type { DynamicStepperProps } from "./types";
+import {
+  dynamicStepperIndicatorToneClass,
+  dynamicStepperIndicatorVariants,
+  dynamicStepperItemVariants,
+  dynamicStepperMapperVariants,
+  dynamicStepperRootVariants,
+} from "./variants";
+
+export const DynamicStepper = ({
+  steps,
+  orientation = "horizontal",
+  buttonAppearance = "outline",
+  buttonSize = "md",
+  indicatorSize = "md",
+  indicatorCompleteAppearance = "emerald",
+  indicatorCurrentAppearance = "violet",
+  indicatorUpcomingAppearance = "outline",
+  activeStep: activeStepProp,
+  defaultActiveStep,
+  onActiveStepChange,
+  onPrevious,
+  onNext,
+  prevLabel = "Previous",
+  nextLabel = "Next",
+  className,
+  ref,
+  ...rest
+}: DynamicStepperProps) => {
+  const baseId = useId();
+  const previousId = `${baseId}-previous`;
+  const nextId = `${baseId}-next`;
+  const mapperId = `${baseId}-mapper`;
+
+  const { activeStep, goPrevious, goNext, canGoPrevious, canGoNext } =
+    useDynamicStepper({
+      stepCount: steps.length,
+      activeStep: activeStepProp,
+      defaultActiveStep,
+      onActiveStepChange,
+      onPrevious,
+      onNext,
+    });
+
+  if (steps.length === 0) {
+    return null;
+  }
+
+  const itemOrientation =
+    orientation === "vertical" ? "vertical" : "horizontal";
+
+  return (
+    <div
+      ref={ref}
+      role="navigation"
+      data-slot="dynamic-stepper"
+      className={cn(dynamicStepperRootVariants({ orientation }), className)}
+      {...rest}
+    >
+      <Button
+        id={previousId}
+        data-slot="dynamic-stepper-previous"
+        type="button"
+        appearance={buttonAppearance}
+        size={buttonSize}
+        disabled={!canGoPrevious}
+        onClick={goPrevious}
+        className={
+          orientation === "vertical" ? "shrink-0 self-start" : "shrink-0"
+        }
+      >
+        {prevLabel}
+      </Button>
+
+      <ol
+        id={mapperId}
+        aria-label="Steps"
+        data-slot="dynamic-stepper-mapper"
+        className={dynamicStepperMapperVariants({ orientation })}
+      >
+        {steps.map((step, index) => {
+          const key = step.id ?? `dynamic-stepper-step-${index}`;
+          const isCurrent = index === activeStep;
+          const semanticState =
+            index < activeStep
+              ? "complete"
+              : isCurrent
+                ? "current"
+                : "upcoming";
+          const indicatorTone =
+            semanticState === "complete"
+              ? indicatorCompleteAppearance
+              : semanticState === "current"
+                ? indicatorCurrentAppearance
+                : indicatorUpcomingAppearance;
+
+          const isVertical = orientation === "vertical";
+
+          return (
+            <li
+              key={key}
+              data-slot="dynamic-stepper-item"
+              aria-current={isCurrent ? "step" : undefined}
+              className={dynamicStepperItemVariants({
+                orientation: itemOrientation,
+              })}
+            >
+              <div
+                data-slot="dynamic-stepper-indicator"
+                className={cn(
+                  dynamicStepperIndicatorVariants({ size: indicatorSize }),
+                  dynamicStepperIndicatorToneClass(
+                    semanticState,
+                    indicatorTone,
+                  ),
+                )}
+              >
+                {step.indicator ?? index + 1}
+              </div>
+              <div
+                className={cn(
+                  "min-w-0",
+                  !isVertical && "flex flex-col items-center",
+                )}
+              >
+                {step.title != null && (
+                  <div
+                    className={cn(
+                      "text-sm font-semibold dark:text-white text-slate-900",
+                      !isVertical && "mt-3",
+                    )}
+                  >
+                    {step.title}
+                  </div>
+                )}
+                {step.description != null && (
+                  <p className="mt-1 text-xs text-slate-900 dark:text-slate-400">
+                    {step.description}
+                  </p>
+                )}
+              </div>
+            </li>
+          );
+        })}
+      </ol>
+
+      <Button
+        id={nextId}
+        data-slot="dynamic-stepper-next"
+        type="button"
+        appearance={buttonAppearance}
+        size={buttonSize}
+        disabled={!canGoNext}
+        onClick={goNext}
+        className={
+          orientation === "vertical" ? "shrink-0 self-start" : "shrink-0"
+        }
+      >
+        {nextLabel}
+      </Button>
+    </div>
+  );
+};
+
+DynamicStepper.displayName = "DynamicStepper";

package/src/ui/dynamic-stepper/index.ts

@@ -0,0 +1,22 @@
+"use client";
+
+export { DynamicStepper } from "./dynamic-stepper";
+export type {
+  DynamicStepperButtonAppearance,
+  DynamicStepperButtonSize,
+  DynamicStepperIndicatorSize,
+  DynamicStepperIndicatorToneAppearance,
+  DynamicStepperOrientation,
+  DynamicStepperProps,
+  DynamicStepperStep,
+  UseDynamicStepperParams,
+  UseDynamicStepperResult,
+} from "./types";
+export {
+  dynamicStepperIndicatorToneClass,
+  dynamicStepperIndicatorVariants,
+  dynamicStepperItemVariants,
+  dynamicStepperMapperVariants,
+  dynamicStepperRootVariants,
+} from "./variants";
+export type { DynamicStepperIndicatorSemanticState } from "./variants";

package/src/ui/dynamic-stepper/types.ts

@@ -0,0 +1,85 @@
+import type { VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef, ReactNode } from "react";
+
+import type { buttonVariants } from "../buttons/variants";
+import type {
+  DynamicStepperIndicatorToneAppearance,
+  dynamicStepperIndicatorVariants,
+  dynamicStepperRootVariants,
+} from "./variants";
+
+export type DynamicStepperOrientation = NonNullable<
+  VariantProps<typeof dynamicStepperRootVariants>["orientation"]
+>;
+
+export type DynamicStepperIndicatorSize = NonNullable<
+  VariantProps<typeof dynamicStepperIndicatorVariants>["size"]
+>;
+
+export type { DynamicStepperIndicatorToneAppearance };
+
+export type DynamicStepperStep = {
+  id?: string;
+  title?: ReactNode;
+  description?: ReactNode;
+  indicator?: ReactNode;
+};
+
+export type DynamicStepperButtonAppearance = NonNullable<
+  VariantProps<typeof buttonVariants>["appearance"]
+>;
+
+export type DynamicStepperButtonSize = NonNullable<
+  VariantProps<typeof buttonVariants>["size"]
+>;
+
+export type UseDynamicStepperParams = {
+  stepCount: number;
+  /** Controlled active step index (0-based). */
+  activeStep?: number;
+  /** Initial step when uncontrolled. Clamped to `[0, stepCount - 1]`. */
+  defaultActiveStep?: number;
+  onActiveStepChange?: (step: number) => void;
+  /** Fires after a successful move from the previous button with the new index. */
+  onPrevious?: (nextStep: number) => void;
+  /** Fires after a successful move from the next button with the new index. */
+  onNext?: (nextStep: number) => void;
+};
+
+export type UseDynamicStepperResult = {
+  /** Active step index (0-based), clamped to valid range. */
+  activeStep: number;
+  setActiveStep: (next: number | ((prev: number) => number)) => void;
+  goPrevious: () => void;
+  goNext: () => void;
+  canGoPrevious: boolean;
+  canGoNext: boolean;
+  stepCount: number;
+};
+
+export type DynamicStepperProps = Omit<
+  ComponentPropsWithRef<"div">,
+  "children"
+> & {
+  steps: DynamicStepperStep[];
+  orientation?: DynamicStepperOrientation;
+  /** Passed to Previous / Next `Button` components. */
+  buttonAppearance?: DynamicStepperButtonAppearance;
+  /** Passed to Previous / Next `Button` components. */
+  buttonSize?: DynamicStepperButtonSize;
+  /** Indicator + text scale inside the mapper. */
+  indicatorSize?: DynamicStepperIndicatorSize;
+  /** Tone for completed steps (non-gradient button palette). @defaultValue emerald */
+  indicatorCompleteAppearance?: DynamicStepperIndicatorToneAppearance;
+  /** Tone for the active step. @defaultValue violet */
+  indicatorCurrentAppearance?: DynamicStepperIndicatorToneAppearance;
+  /** Tone for upcoming steps. @defaultValue outline */
+  indicatorUpcomingAppearance?: DynamicStepperIndicatorToneAppearance;
+  activeStep?: number;
+  defaultActiveStep?: number;
+  onActiveStepChange?: (step: number) => void;
+  onPrevious?: (nextStep: number) => void;
+  onNext?: (nextStep: number) => void;
+  prevLabel?: ReactNode;
+  nextLabel?: ReactNode;
+};