@zentauri-ui/zentauri-components 1.5.21 → 1.5.31

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 text-white",
+                      !isVertical && "mt-3",
+                    )}
+                  >
+                    {step.title}
+                  </div>
+                )}
+                {step.description != null && (
+                  <p className="mt-1 text-xs 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,24 @@
+"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;
+};

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

@@ -0,0 +1,238 @@
+import type { VariantProps } from "class-variance-authority";
+import { cva } from "class-variance-authority";
+
+import type { buttonVariants } from "../buttons/variants";
+
+type GradientButtonAppearance =
+  | "gradient-blue"
+  | "gradient-green"
+  | "gradient-red"
+  | "gradient-yellow"
+  | "gradient-purple"
+  | "gradient-teal"
+  | "gradient-indigo"
+  | "gradient-pink"
+  | "gradient-orange";
+
+/** Button `appearance` keys usable for indicator tones (gradients excluded). */
+export type DynamicStepperIndicatorToneAppearance = Exclude<
+  NonNullable<VariantProps<typeof buttonVariants>["appearance"]>,
+  GradientButtonAppearance
+>;
+
+export type DynamicStepperIndicatorSemanticState =
+  | "complete"
+  | "current"
+  | "upcoming";
+
+const INDICATOR_TONE_CLASSES: Record<
+  DynamicStepperIndicatorToneAppearance,
+  Record<DynamicStepperIndicatorSemanticState, string>
+> = {
+  default: {
+    complete:
+      "border-slate-400/55 bg-slate-500/25 text-slate-50 ring-2 ring-slate-400/25",
+    current:
+      "border-slate-300 bg-slate-500/35 text-white ring-2 ring-slate-300/45",
+    upcoming: "border-white/15 bg-white/5 text-slate-400",
+  },
+  secondary: {
+    complete:
+      "border-slate-600 bg-slate-800/70 text-slate-200 ring-2 ring-slate-600/35",
+    current:
+      "border-slate-500 bg-slate-700/55 text-white ring-2 ring-slate-500/45",
+    upcoming: "border-white/10 bg-slate-900/50 text-slate-500",
+  },
+  destructive: {
+    complete:
+      "border-rose-500/60 bg-rose-500/20 text-rose-100 ring-2 ring-rose-400/30",
+    current:
+      "border-rose-400 bg-rose-600/35 text-white ring-2 ring-rose-400/50",
+    upcoming: "border-white/15 bg-rose-950/25 text-slate-400",
+  },
+  outline: {
+    complete:
+      "border-emerald-500/55 bg-transparent text-emerald-200 ring-2 ring-emerald-500/25",
+    current:
+      "border-white/30 bg-white/10 text-white ring-2 ring-white/25",
+    upcoming: "border-white/15 bg-white/5 text-slate-400",
+  },
+  ghost: {
+    complete:
+      "border-transparent bg-emerald-500/15 text-emerald-200 ring-2 ring-emerald-400/20",
+    current:
+      "border-transparent bg-white/10 text-white ring-2 ring-white/15",
+    upcoming: "border-transparent bg-transparent text-slate-500",
+  },
+  link: {
+    complete:
+      "border-cyan-500/45 bg-cyan-950/35 text-cyan-200 ring-2 ring-cyan-400/25",
+    current:
+      "border-cyan-400 bg-cyan-900/45 text-cyan-50 ring-2 ring-cyan-400/45",
+    upcoming: "border-white/10 bg-transparent text-slate-500",
+  },
+  glass: {
+    complete:
+      "border-white/25 bg-white/10 text-emerald-100 shadow-[inset_0_1px_0_rgba(255,255,255,0.06)] backdrop-blur-md ring-2 ring-emerald-400/25",
+    current:
+      "border-white/35 bg-white/15 text-white shadow-[inset_0_1px_0_rgba(255,255,255,0.08)] backdrop-blur-md ring-2 ring-white/30",
+    upcoming:
+      "border-white/15 bg-white/5 text-slate-400 backdrop-blur-sm",
+  },
+  emerald: {
+    complete:
+      "border-emerald-500/60 bg-emerald-500/20 text-emerald-100 ring-2 ring-emerald-400/30",
+    current:
+      "border-emerald-400 bg-emerald-500/30 text-white ring-2 ring-emerald-400/50",
+    upcoming:
+      "border-white/15 bg-emerald-950/30 text-emerald-200/55",
+  },
+  indigo: {
+    complete:
+      "border-indigo-500/60 bg-indigo-500/20 text-indigo-100 ring-2 ring-indigo-400/30",
+    current:
+      "border-indigo-400 bg-indigo-500/30 text-white ring-2 ring-indigo-400/50",
+    upcoming:
+      "border-white/15 bg-indigo-950/30 text-indigo-200/55",
+  },
+  purple: {
+    complete:
+      "border-purple-500/60 bg-purple-500/20 text-purple-100 ring-2 ring-purple-400/30",
+    current:
+      "border-purple-400 bg-purple-500/30 text-white ring-2 ring-purple-400/50",
+    upcoming:
+      "border-white/15 bg-purple-950/30 text-purple-200/55",
+  },
+  pink: {
+    complete:
+      "border-pink-500/60 bg-pink-500/20 text-pink-100 ring-2 ring-pink-400/30",
+    current:
+      "border-pink-400 bg-pink-500/30 text-white ring-2 ring-pink-400/50",
+    upcoming:
+      "border-white/15 bg-pink-950/30 text-pink-200/55",
+  },
+  rose: {
+    complete:
+      "border-rose-500/60 bg-rose-500/20 text-rose-100 ring-2 ring-rose-400/30",
+    current:
+      "border-rose-400 bg-rose-500/30 text-white ring-2 ring-rose-400/50",
+    upcoming:
+      "border-white/15 bg-rose-950/30 text-rose-200/55",
+  },
+  sky: {
+    complete:
+      "border-sky-500/60 bg-sky-500/20 text-sky-100 ring-2 ring-sky-400/30",
+    current:
+      "border-sky-400 bg-sky-500/30 text-white ring-2 ring-sky-400/50",
+    upcoming:
+      "border-white/15 bg-sky-950/30 text-sky-200/55",
+  },
+  teal: {
+    complete:
+      "border-teal-500/60 bg-teal-500/20 text-teal-100 ring-2 ring-teal-400/30",
+    current:
+      "border-teal-400 bg-teal-500/30 text-white ring-2 ring-teal-400/50",
+    upcoming:
+      "border-white/15 bg-teal-950/30 text-teal-200/55",
+  },
+  yellow: {
+    complete:
+      "border-yellow-500/60 bg-yellow-500/20 text-yellow-100 ring-2 ring-yellow-400/30",
+    current:
+      "border-yellow-400 bg-yellow-600/35 text-white ring-2 ring-yellow-400/50",
+    upcoming:
+      "border-white/15 bg-yellow-950/35 text-yellow-200/55",
+  },
+  orange: {
+    complete:
+      "border-orange-500/60 bg-orange-500/20 text-orange-100 ring-2 ring-orange-400/30",
+    current:
+      "border-orange-400 bg-orange-600/35 text-white ring-2 ring-orange-400/50",
+    upcoming:
+      "border-white/15 bg-orange-950/30 text-orange-200/55",
+  },
+  gray: {
+    complete:
+      "border-gray-500/60 bg-gray-500/20 text-gray-100 ring-2 ring-gray-400/30",
+    current:
+      "border-gray-400 bg-gray-600/35 text-white ring-2 ring-gray-400/50",
+    upcoming:
+      "border-white/15 bg-gray-950/30 text-gray-300/70",
+  },
+  amber: {
+    complete:
+      "border-amber-500/60 bg-amber-500/20 text-amber-100 ring-2 ring-amber-400/30",
+    current:
+      "border-amber-400 bg-amber-600/35 text-white ring-2 ring-amber-400/50",
+    upcoming:
+      "border-white/15 bg-amber-950/35 text-amber-200/55",
+  },
+  violet: {
+    complete:
+      "border-violet-500/60 bg-violet-500/20 text-violet-100 ring-2 ring-violet-400/30",
+    current:
+      "border-violet-400 bg-violet-500/30 text-white ring-2 ring-violet-400/50",
+    upcoming:
+      "border-white/15 bg-violet-950/30 text-violet-200/55",
+  },
+};
+
+export function dynamicStepperIndicatorToneClass(
+  state: DynamicStepperIndicatorSemanticState,
+  tone: DynamicStepperIndicatorToneAppearance,
+): string {
+  return INDICATOR_TONE_CLASSES[tone][state];
+}
+
+export const dynamicStepperRootVariants = cva("flex w-full", {
+  variants: {
+    orientation: {
+      horizontal:
+        "flex-row flex-wrap items-start justify-between gap-4 md:flex-nowrap md:items-center",
+      vertical: "flex-col gap-6",
+    },
+  },
+  defaultVariants: {
+    orientation: "horizontal",
+  },
+});
+
+export const dynamicStepperMapperVariants = cva("m-0 min-w-0 flex-1 list-none p-0", {
+  variants: {
+    orientation: {
+      horizontal: "flex flex-row flex-wrap items-start justify-center gap-4",
+      vertical: "flex flex-col gap-6",
+    },
+  },
+  defaultVariants: {
+    orientation: "horizontal",
+  },
+});
+
+export const dynamicStepperItemVariants = cva("relative flex gap-3", {
+  variants: {
+    orientation: {
+      horizontal: "min-w-0 flex-col items-center text-center",
+      vertical: "flex-row items-start text-left",
+    },
+  },
+  defaultVariants: {
+    orientation: "horizontal",
+  },
+});
+
+export const dynamicStepperIndicatorVariants = cva(
+  "grid size-9 shrink-0 place-items-center rounded-full border text-sm font-semibold transition-colors",
+  {
+    variants: {
+      size: {
+        sm: "size-8 text-xs",
+        md: "size-9 text-sm",
+        lg: "size-10 text-base",
+      },
+    },
+    defaultVariants: {
+      size: "md",
+    },
+  },
+);