Stepper

- `Stepper` maps its children and wraps each in an index context (`index`,
  `last`), so `Step` knows its status without props: `index < value`
  complete, `=== value` current, else upcoming; `error` overrides the look but
  keeps `aria-current`.
- Indicator: 28 px circle; tones per status (lit key recipe for complete,
  `ring-2 ring-accent` raised card for current, recessed muted well for
  upcoming, `bg-danger/12` for error), colours transition 200 ms.
- Number→check morph: `AnimatePresence mode="popLayout" initial={false}`;
  number exits with blur 2 px + 4 px rise; the check scales in from 0.6 and its
  path draws via `pathLength 0→1` (320 ms, 60 ms delay, enter curve).
- Connector: a 2 px `bg-border` track with an ink fill that scales from
  `origin-left` (`origin-top` vertical) 0→1 over 320 ms `ease-move` once the
  step before it completes.
- Clickable steps wrap indicator + text in a button with `-m-1 p-1` so the hit
  area grows without moving layout.

<!-- PEBBLE-LICENSE -->

registry/nav/stepper/stepper.tsx

"use client";

/* PEBBLE-LICENSE
Built by Pebble. Component: stepper.

First-party license: MIT

The following first-party terms apply only to original Pebble material.

MIT License

Copyright (c) 2026 Praxys Solutions LLC (Pebble)

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.
END PEBBLE-LICENSE */

import * as React from "react";
import { AnimatePresence, MotionConfig, motion } from "motion/react";

import { cn } from "@/lib/utils";

// Pebble: done steps are lit keys holding a drawn check, the current step is a
// raised card chip with an ember ring, upcoming steps are quiet wells. The
// connector after a finished step fills with ink along the slow move curve,
// so progress reads as one line being drawn.
const enter = [0.22, 1, 0.36, 1] as const;

export type StepStatus = "complete" | "current" | "upcoming" | "error";

type StepperContextValue = {
  value: number;
  setValue: (index: number) => void;
  orientation: "horizontal" | "vertical";
  clickable: "completed" | "all" | "none";
};

const StepperContext = React.createContext<StepperContextValue | null>(null);
const StepIndexContext = React.createContext<{ index: number; last: boolean } | null>(null);

function useStepper() {
  const context = React.useContext(StepperContext);
  if (!context) throw new Error("Step must be used within a Stepper.");
  return context;
}

export type StepperProps = Omit<React.ComponentProps<"ol">, "onChange"> & {
  /** Current step index (controlled). */
  value?: number;
  /** Initial step index (uncontrolled). */
  defaultValue?: number;
  onValueChange?: (index: number) => void;
  orientation?: "horizontal" | "vertical";
  /** Which steps can be clicked to jump to them. */
  clickable?: "completed" | "all" | "none";
  /** Accessible name for the list. */
  label?: string;
};

export function Stepper({
  value: valueProp,
  defaultValue = 0,
  onValueChange,
  orientation = "horizontal",
  clickable = "completed",
  label = "Progress",
  className,
  children,
  onKeyDown,
  ...props
}: StepperProps) {
  const [inner, setInner] = React.useState(defaultValue);
  const value = valueProp ?? inner;
  const setValue = React.useCallback(
    (index: number) => {
      if (valueProp === undefined) setInner(index);
      onValueChange?.(index);
    },
    [valueProp, onValueChange],
  );
  const context = React.useMemo(
    () => ({ value, setValue, orientation, clickable }),
    [value, setValue, orientation, clickable],
  );
  const steps = React.Children.toArray(children).filter(React.isValidElement);

  return (
    <StepperContext.Provider value={context}>
      <MotionConfig reducedMotion="user">
        <ol
          aria-label={label}
          data-slot="stepper"
          data-orientation={orientation}
          // Arrow keys move between the step buttons that can be focused.
          onKeyDown={(event) => {
            onKeyDown?.(event);
            if (event.defaultPrevented) return;
            const next = orientation === "horizontal" ? "ArrowRight" : "ArrowDown";
            const prev = orientation === "horizontal" ? "ArrowLeft" : "ArrowUp";
            if (![next, prev, "Home", "End"].includes(event.key)) return;
            const buttons = Array.from(
              event.currentTarget.querySelectorAll<HTMLButtonElement>(
                '[data-slot="step-trigger"]:not(:disabled)',
              ),
            );
            const i = buttons.indexOf(document.activeElement as HTMLButtonElement);
            if (i === -1) return;
            event.preventDefault();
            const target =
              event.key === "Home"
                ? 0
                : event.key === "End"
                  ? buttons.length - 1
                  : Math.min(Math.max(i + (event.key === next ? 1 : -1), 0), buttons.length - 1);
            buttons[target]?.focus();
          }}
          className={cn(
            "group/stepper flex w-full",
            orientation === "horizontal" ? "flex-row items-start" : "flex-col",
            className,
          )}
          {...props}
        >
          {steps.map((child, index) => (
            <StepIndexContext.Provider
              key={child.key ?? index}
              value={{ index, last: index === steps.length - 1 }}
            >
              {child}
            </StepIndexContext.Provider>
          ))}
        </ol>
      </MotionConfig>
    </StepperContext.Provider>
  );
}

function Check() {
  return (
    <motion.svg
      key="check"
      viewBox="0 0 16 16"
      fill="none"
      stroke="currentColor"
      strokeWidth="2"
      strokeLinecap="round"
      strokeLinejoin="round"
      aria-hidden
      className="size-3.5"
      initial={{ opacity: 0, scale: 0.6 }}
      animate={{ opacity: 1, scale: 1 }}
      exit={{ opacity: 0, scale: 0.6 }}
      transition={{ duration: 0.2, ease: enter }}
    >
      <motion.path
        d="m3.5 8.5 3 3 6-7"
        initial={{ pathLength: 0 }}
        animate={{ pathLength: 1 }}
        transition={{ duration: 0.32, delay: 0.06, ease: enter }}
      />
    </motion.svg>
  );
}

const indicatorTone: Record<StepStatus, string> = {
  complete:
    "bg-linear-to-b from-key-top to-key-bottom text-primary-foreground ring-1 ring-key-edge shadow-[var(--key-shine),var(--elevation-xs)]",
  current:
    "bg-card text-foreground shadow-raised-sm inset-shadow-highlight ring-2 ring-accent dark:bg-muted",
  upcoming: "bg-muted text-muted-foreground ring-1 ring-hairline inset-shadow-xs",
  error: "bg-danger/12 text-danger-strong ring-1 ring-danger/40",
};

export type StepProps = Omit<React.ComponentProps<"li">, "title"> & {
  title: React.ReactNode;
  description?: React.ReactNode;
  /** Shows "Optional" under the title. */
  optional?: boolean;
  /** Marks the step as failed. Overrides complete/current styling. */
  error?: boolean;
  /** Cannot be clicked even when the stepper allows it. */
  disabled?: boolean;
  /** Vertical only: content shown under the current step. */
  children?: React.ReactNode;
};

export function Step({
  title,
  description,
  optional = false,
  error = false,
  disabled = false,
  className,
  children,
  ...props
}: StepProps) {
  const { value, setValue, orientation, clickable } = useStepper();
  const position = React.useContext(StepIndexContext);
  if (!position) throw new Error("Step must be a direct child of a Stepper.");
  const { index, last } = position;
  const base: StepStatus = index < value ? "complete" : index === value ? "current" : "upcoming";
  const status: StepStatus = error ? "error" : base;
  const canClick =
    !disabled &&
    index !== value &&
    (clickable === "all" || (clickable === "completed" && base === "complete"));
  const vertical = orientation === "vertical";

  const indicator = (
    <span
      data-slot="step-indicator"
      className={cn(
        "relative flex size-7 shrink-0 items-center justify-center rounded-full text-xs font-semibold tabular-nums",
        "transition-[background-color,color,box-shadow] duration-(--motion-base) ease-enter motion-reduce:transition-none",
        indicatorTone[status],
      )}
    >
      <AnimatePresence mode="popLayout" initial={false}>
        {status === "complete" ? (
          <Check />
        ) : status === "error" ? (
          <motion.span key="error" aria-hidden initial={{ opacity: 0 }} animate={{ opacity: 1 }}>
            !
          </motion.span>
        ) : (
          <motion.span
            key="number"
            aria-hidden
            initial={{ opacity: 0, y: 4, filter: "blur(2px)" }}
            animate={{ opacity: 1, y: 0, filter: "blur(0px)" }}
            exit={{ opacity: 0, y: -4, filter: "blur(2px)" }}
            transition={{ duration: 0.2, ease: enter }}
          >
            {index + 1}
          </motion.span>
        )}
      </AnimatePresence>
    </span>
  );

  const statusText = {
    complete: "completed",
    current: "current",
    upcoming: "not started",
    error: "has an error",
  }[status];

  const text = (
    <span
      className={cn(
        "flex min-w-0 flex-col",
        vertical ? "pt-1" : "",
        // Narrow screens: a horizontal stepper keeps only its markers in view
        // (labels stay for assistive tech), so it never overflows.
        !vertical && "max-sm:sr-only",
      )}
    >
      <span
        className={cn(
          "text-[13px] leading-tight font-medium transition-colors duration-(--motion-base)",
          status === "upcoming" ? "text-muted-foreground" : "text-foreground",
          status === "error" && "text-danger-strong",
        )}
      >
        {title}
      </span>
      {(description || optional) && (
        <span className="mt-0.5 text-xs leading-snug text-muted-foreground">
          {description}
          {description && optional ? " · " : null}
          {optional ? "Optional" : null}
        </span>
      )}
      <span className="sr-only">, {statusText}</span>
    </span>
  );

  const connectorFilled = index < value;
  const connector = !last && (
    <span
      aria-hidden
      data-slot="step-connector"
      className={cn(
        "relative overflow-hidden rounded-full bg-border",
        vertical
          ? "my-1.5 w-0.5 flex-1"
          : "mx-3 mt-3.5 h-0.5 min-w-6 flex-1 max-sm:mx-1.5 max-sm:min-w-3",
      )}
    >
      <span
        className={cn(
          "absolute inset-0 bg-foreground transition-transform duration-(--motion-slow) ease-move motion-reduce:transition-none",
          vertical ? "origin-top" : "origin-left",
          connectorFilled ? "scale-100" : vertical ? "scale-y-0" : "scale-x-0",
        )}
      />
    </span>
  );

  return (
    <li
      data-slot="step"
      data-status={status}
      aria-current={base === "current" ? "step" : undefined}
      className={cn(
        vertical ? "grid grid-cols-[1.75rem_1fr] gap-x-3" : "flex items-start",
        !last && !vertical && "flex-1",
        className,
      )}
      {...props}
    >
      {vertical ? (
        <>
          <span className="flex flex-col items-center">
            {indicator}
            {connector}
          </span>
          <div className={cn("min-w-0", last ? "pb-0" : "pb-5")}>
            <StepTrigger canClick={canClick} onSelect={() => setValue(index)}>
              {text}
            </StepTrigger>
            {base === "current" && children ? (
              <motion.div
                data-slot="step-content"
                initial={{ opacity: 0, y: 4 }}
                animate={{ opacity: 1, y: 0 }}
                transition={{ duration: 0.2, ease: enter }}
                className="mt-3"
              >
                {children}
              </motion.div>
            ) : null}
          </div>
        </>
      ) : (
        <>
          <StepTrigger canClick={canClick} onSelect={() => setValue(index)} className="gap-2.5">
            {indicator}
            <span className="pt-1">{text}</span>
          </StepTrigger>
          {connector}
        </>
      )}
    </li>
  );
}

function StepTrigger({
  canClick,
  onSelect,
  className,
  children,
}: {
  canClick: boolean;
  onSelect: () => void;
  className?: string;
  children: React.ReactNode;
}) {
  if (!canClick) {
    return <div className={cn("flex min-w-0 items-start text-left", className)}>{children}</div>;
  }
  return (
    <button
      type="button"
      data-slot="step-trigger"
      onClick={onSelect}
      className={cn(
        "-m-1 flex min-w-0 cursor-pointer items-start rounded-lg p-1 text-left outline-none",
        "transition-colors duration-(--motion-fast) hover:bg-foreground/[0.04] focus-visible:ring-2 focus-visible:ring-ring",
        className,
      )}
    >
      {children}
    </button>
  );
}