{"$schema":"https:\/\/ui.particle.academy\/schema\/registry-item.json","name":"stepper","type":"registry:ui","title":"Stepper","description":"Stepper from react-fancy","package":"react-fancy","dependencies":["lucide-react","tailwind-merge"],"registryDependencies":[],"files":[{"path":"components\/fancy\/stepper\/Stepper.tsx","content":"import {\n  Children,\n  forwardRef,\n  isValidElement,\n  type KeyboardEvent,\n  type ReactNode,\n} from \"react\";\nimport { Check } from \"lucide-react\";\nimport { cn } from \"..\/lib\/utils\/cn\";\nimport { isRtl } from \"..\/lib\/utils\/direction\";\nimport { useControllableState } from \"..\/lib\/hooks\/use-controllable-state\";\nimport type {\n  StepperProps,\n  StepperStep as StepperStepData,\n  StepperStepProps,\n  StepperStepState,\n} from \".\/Stepper.types\";\n\nconst DEFAULT_STATE_LABELS: Record<StepperStepState, string> = {\n  upcoming: \"Not started\",\n  current: \"Current\",\n  complete: \"Completed\",\n  error: \"Error\",\n};\n\n\/**\n * Declarative step. Renders nothing itself: `Stepper` reads its props as data\n * and renders it through the same path as an entry in `steps`, so the two forms\n * cannot drift apart in markup, states or handles. Its children are the step's\n * content. It must be a DIRECT child of `Stepper` (not wrapped in another\n * component) for the same reason `Breadcrumbs.Item` must.\n *\/\nfunction StepperStep(_props: StepperStepProps): null {\n  return null;\n}\nStepperStep.displayName = \"StepperStep\";\n\nfunction stepsFromChildren(children: ReactNode): StepperStepData[] {\n  const out: StepperStepData[] = [];\n  for (const child of Children.toArray(children)) {\n    if (!isValidElement<StepperStepProps>(child) || child.type !== StepperStep) continue;\n    const { children: content, ...rest } = child.props;\n    out.push({ ...rest, content });\n  }\n  return out;\n}\n\nconst indicatorClass: Record<StepperStepState, string> = {\n  complete:\n    \"border-transparent bg-zinc-900 text-white dark:bg-white dark:text-zinc-900\",\n  current:\n    \"border-2 border-zinc-900 bg-[color:var(--fancy-surface,var(--color-white))] text-zinc-900 ring-4 ring-zinc-900\/10 dark:border-white dark:bg-[color:var(--fancy-surface-dark,var(--color-zinc-900))] dark:text-white dark:ring-white\/15\",\n  upcoming:\n    \"border-[color:var(--fancy-border,var(--color-zinc-200))] bg-[color:var(--fancy-surface,var(--color-white))] text-[color:var(--fancy-text-muted,var(--color-zinc-500))] dark:border-[color:var(--fancy-border-dark,var(--color-zinc-700))] dark:bg-[color:var(--fancy-surface-dark,var(--color-zinc-900))] dark:text-[color:var(--fancy-text-muted-dark,var(--color-zinc-400))]\",\n  \/\/ red-600 in both modes: white on red-500 is 3.81:1.\n  error: \"border-transparent bg-red-600 text-white\",\n};\n\nconst titleClass: Record<StepperStepState, string> = {\n  complete: \"font-medium text-zinc-900 dark:text-white\",\n  current: \"font-semibold text-zinc-900 dark:text-white\",\n  upcoming:\n    \"font-medium text-[color:var(--fancy-text-muted,var(--color-zinc-500))] dark:text-[color:var(--fancy-text-muted-dark,var(--color-zinc-400))]\",\n  error: \"font-semibold text-red-700 dark:text-red-400\",\n};\n\n\/** The glyph differs per state, so state reads without colour: number, tick, \"!\". *\/\nfunction Indicator({ state, index }: { state: StepperStepState; index: number }) {\n  return (\n    <span\n      aria-hidden=\"true\"\n      data-react-fancy-stepper-indicator=\"\"\n      className={cn(\n        \"relative z-10 flex h-8 w-8 shrink-0 items-center justify-center rounded-full border text-sm font-semibold\",\n        indicatorClass[state],\n      )}\n    >\n      {state === \"complete\" ? <Check size={16} strokeWidth={3} \/> : state === \"error\" ? \"!\" : index + 1}\n    <\/span>\n  );\n}\n\nconst StepperRoot = forwardRef<HTMLOListElement, StepperProps>(\n  (\n    {\n      steps: stepsProp,\n      children,\n      current: currentProp,\n      defaultCurrent = 0,\n      onChange,\n      orientation = \"vertical\",\n      clickable = false,\n      showContent = \"all\",\n      stateLabels,\n      className,\n      onKeyDown,\n      ...rest\n    },\n    ref,\n  ) => {\n    const [current, setCurrent] = useControllableState(currentProp, defaultCurrent, onChange);\n    const steps = stepsProp ?? stepsFromChildren(children);\n    const labels = { ...DEFAULT_STATE_LABELS, ...stateLabels };\n    const horizontal = orientation === \"horizontal\";\n\n    \/\/ Arrow keys move focus between step buttons; Enter \/ Space activate them\n    \/\/ natively. Focus only -- the current step changes on activation, never on\n    \/\/ arrowing past it. DOM is read in the handler, never during render.\n    const handleKeyDown = (e: KeyboardEvent<HTMLOListElement>) => {\n      onKeyDown?.(e);\n      if (!clickable || e.defaultPrevented) return;\n\n      \/\/ Horizontal steps run right-to-left in RTL, so the arrows swap there.\n      const rtl = horizontal && isRtl(e.currentTarget);\n      const prevKey = horizontal ? (rtl ? \"ArrowRight\" : \"ArrowLeft\") : \"ArrowUp\";\n      const nextKey = horizontal ? (rtl ? \"ArrowLeft\" : \"ArrowRight\") : \"ArrowDown\";\n      if (![prevKey, nextKey, \"Home\", \"End\"].includes(e.key)) return;\n\n      const list = e.currentTarget;\n      const target = (e.target as HTMLElement).closest<HTMLButtonElement>(\"[data-react-fancy-stepper-trigger]\");\n      if (!target || target.closest(\"[data-react-fancy-stepper]\") !== list) return;\n\n      \/\/ Only this stepper's own buttons: a stepper nested in step content is\n      \/\/ its own list.\n      const buttons = Array.from(\n        list.querySelectorAll<HTMLButtonElement>(\"[data-react-fancy-stepper-trigger]\"),\n      ).filter((b) => b.closest(\"[data-react-fancy-stepper]\") === list && !b.disabled);\n      const at = buttons.indexOf(target);\n\n      let next: HTMLButtonElement | undefined;\n      if (e.key === \"Home\") next = buttons[0];\n      else if (e.key === \"End\") next = buttons[buttons.length - 1];\n      else if (e.key === nextKey) next = buttons[at + 1] ?? target;\n      else next = at > 0 ? buttons[at - 1] : target;\n\n      e.preventDefault();\n      next?.focus();\n    };\n\n    return (\n      <ol\n        ref={ref}\n        data-react-fancy-stepper=\"\"\n        data-orientation={orientation}\n        data-current={current}\n        className={cn(horizontal ? \"flex items-start\" : \"flex flex-col\", className)}\n        onKeyDown={handleKeyDown}\n        {...rest}\n      >\n        {steps.map((step, index) => {\n          const derived: StepperStepState =\n            index < current ? \"complete\" : index === current ? \"current\" : \"upcoming\";\n          const state = step.state ?? derived;\n          const isCurrent = index === current;\n          const isLast = index === steps.length - 1;\n          const showBody = step.content != null && (showContent === \"all\" || isCurrent);\n\n          const headerInner = (\n            <>\n              <Indicator state={state} index={index} \/>\n              {\/* State in words, before the title so it is read first. A\n                  sibling of the title, so the title handle reads the title. *\/}\n              <span className=\"sr-only\" data-react-fancy-stepper-state=\"\">\n                {labels[state]}:{\" \"}\n              <\/span>\n              <span data-react-fancy-stepper-title=\"\" className={cn(\"text-sm\", titleClass[state])}>\n                {step.title}\n              <\/span>\n            <\/>\n          );\n\n          const headerClass = horizontal\n            ? \"flex flex-col items-center gap-2 text-center\"\n            : \"flex items-center gap-x-4 text-start\";\n\n          const header = clickable ? (\n            <button\n              type=\"button\"\n              data-react-fancy-stepper-trigger=\"\"\n              disabled={step.disabled}\n              onClick={() => {\n                if (index !== current) setCurrent(index);\n              }}\n              className={cn(\n                headerClass,\n                \"cursor-pointer rounded-md border-0 bg-transparent p-0\",\n                \"focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2\",\n                \"focus-visible:ring-[color:var(--fancy-focus,var(--color-blue-500))] focus-visible:ring-offset-[color:var(--fancy-surface,var(--color-white))]\",\n                \"dark:focus-visible:ring-[color:var(--fancy-focus-dark,var(--color-blue-400))] dark:focus-visible:ring-offset-[color:var(--fancy-surface-dark,var(--color-zinc-900))]\",\n                \"disabled:cursor-not-allowed disabled:opacity-50\",\n              )}\n            >\n              {headerInner}\n            <\/button>\n          ) : (\n            <div className={headerClass}>{headerInner}<\/div>\n          );\n\n          return (\n            <li\n              key={step.id ?? index}\n              data-react-fancy-stepper-step=\"\"\n              data-state={state}\n              data-index={index}\n              data-step-id={step.id}\n              data-disabled={step.disabled ? \"true\" : undefined}\n              aria-current={isCurrent ? \"step\" : undefined}\n              className={cn(\"relative\", horizontal ? \"min-w-0 flex-1\" : !isLast && \"pb-8\")}\n            >\n              {!isLast && (\n                <span\n                  aria-hidden=\"true\"\n                  data-react-fancy-stepper-connector=\"\"\n                  className={cn(\n                    \"absolute\",\n                    horizontal\n                      ? \"top-4 start-[calc(50%+1.5rem)] h-px w-[calc(100%-3rem)]\"\n                      : \"top-10 bottom-2 start-4 w-px -translate-x-1\/2 rtl:translate-x-1\/2\",\n                    index < current\n                      ? \"bg-zinc-900 dark:bg-white\"\n                      : \"bg-[color:var(--fancy-border,var(--color-zinc-200))] dark:bg-[color:var(--fancy-border-dark,var(--color-zinc-700))]\",\n                  )}\n                \/>\n              )}\n              {header}\n              {(step.description != null || showBody) && (\n                <div className={horizontal ? \"mt-1 px-2 text-center\" : \"ps-12\"}>\n                  {step.description != null && (\n                    <div\n                      data-react-fancy-stepper-description=\"\"\n                      className=\"text-sm text-[color:var(--fancy-text-muted,var(--color-zinc-500))] dark:text-[color:var(--fancy-text-muted-dark,var(--color-zinc-400))]\"\n                    >\n                      {step.description}\n                    <\/div>\n                  )}\n                  {showBody && (\n                    <div\n                      data-react-fancy-stepper-content=\"\"\n                      className=\"mt-2 text-sm text-[color:var(--fancy-text-subtle,var(--color-zinc-600))] dark:text-[color:var(--fancy-text-subtle-dark,var(--color-zinc-400))]\"\n                    >\n                      {step.content}\n                    <\/div>\n                  )}\n                <\/div>\n              )}\n            <\/li>\n          );\n        })}\n      <\/ol>\n    );\n  },\n);\n\nStepperRoot.displayName = \"Stepper\";\n\nexport const Stepper = Object.assign(StepperRoot, { Step: StepperStep });\n","type":"registry:ui","target":"components\/fancy\/stepper\/Stepper.tsx"},{"path":"components\/fancy\/stepper\/Stepper.types.ts","content":"import type { OlHTMLAttributes, ReactNode } from \"react\";\n\n\/**\n * Where a step stands. `upcoming`, `current` and `complete` are derived from\n * the step's position against `current`; `error` is only ever declared, on the\n * step itself, and overrides the derived state.\n *\/\nexport type StepperStepState = \"upcoming\" | \"current\" | \"complete\" | \"error\";\n\nexport type StepperOrientation = \"vertical\" | \"horizontal\";\n\n\/** One step, as data. Everything an agent needs to emit a stepper is JSON. *\/\nexport interface StepperStep {\n  \/** Stable identity, rendered as `data-step-id`. Recommended for agent handles. *\/\n  id?: string;\n  \/** Step heading. *\/\n  title: ReactNode;\n  \/** Short supporting line under the title. *\/\n  description?: ReactNode;\n  \/** The step's body: instructions, a code sample, a screenshot. *\/\n  content?: ReactNode;\n  \/**\n   * Override the derived state. Usually `\"error\"`; the others are accepted so\n   * a caller can mark a skipped step complete without moving `current`.\n   *\/\n  state?: StepperStepState;\n  \/** With `clickable`, renders this step's button disabled. *\/\n  disabled?: boolean;\n}\n\nexport interface StepperProps\n  extends Omit<OlHTMLAttributes<HTMLOListElement>, \"onChange\" | \"children\" | \"defaultValue\"> {\n  \/** The steps as data. Wins over `children` when both are given. *\/\n  steps?: StepperStep[];\n  \/** `Stepper.Step` elements, read as data. Ignored when `steps` is given. *\/\n  children?: ReactNode;\n  \/** Controlled index of the current step. `steps.length` means all complete. *\/\n  current?: number;\n  \/** Uncontrolled starting index. Default `0`. *\/\n  defaultCurrent?: number;\n  \/** Called with the chosen step's index. Only fires when `clickable`. *\/\n  onChange?: (index: number) => void;\n  \/** Default `\"vertical\"`. Horizontal suits short content. *\/\n  orientation?: StepperOrientation;\n  \/**\n   * Render each step's header as a button that makes it current. Off by\n   * default: a Stepper is content, with no interactive elements at all.\n   *\/\n  clickable?: boolean;\n  \/** Show every step's content (default), or only the current step's. *\/\n  showContent?: \"all\" | \"current\";\n  \/** Words for each state, read by screen readers. English by default. *\/\n  stateLabels?: Partial<Record<StepperStepState, string>>;\n}\n\n\/** Declarative form of a `StepperStep`; its children are the step's content. *\/\nexport interface StepperStepProps extends Omit<StepperStep, \"content\"> {\n  children?: ReactNode;\n}\n","type":"registry:ui","target":"components\/fancy\/stepper\/Stepper.types.ts"},{"path":"components\/fancy\/stepper\/index.ts","content":"export { Stepper } from \".\/Stepper\";\nexport type {\n  StepperProps,\n  StepperStep,\n  StepperStepProps,\n  StepperStepState,\n  StepperOrientation,\n} from \".\/Stepper.types\";\n","type":"registry:ui","target":"components\/fancy\/stepper\/index.ts"},{"path":"components\/fancy\/lib\/utils\/cn.ts","content":"import { twMerge } from \"tailwind-merge\";\n\n\/**\n * A class value: a string, a number, a conditional map, an array of any of\n * those, or nothing. Mirrors what `clsx` accepted, because every component in\n * this package already passes these shapes.\n *\/\nexport type ClassValue =\n  | string\n  | number\n  | bigint\n  | null\n  | undefined\n  | false\n  | ClassDictionary\n  | ClassValue[];\n\ntype ClassDictionary = Record<string, unknown>;\n\n\/**\n * Flatten class values into a space-separated string.\n *\n * This was `clsx` until 2026-08-19. It is roughly twenty lines of logic, it\n * shipped as a RUNTIME dependency to every consumer of this package, and its\n * last commit was 801 days old \u2014 so it fell to the rule that third-party code\n * must be both approved and actively maintained. Owning it costs less than\n * carrying it.\n *\n * `tailwind-merge` deliberately stays: deciding which of two conflicting\n * Tailwind utilities wins requires modelling the entire utility space, which is\n * emphatically not twenty lines, and it is actively maintained.\n *\n * Falsy values are dropped \u2014 including `0` and `\"\"`, which is what `clsx` did\n * and what `tests\/cn.test.ts` pins. A truthy number is kept, because digits are\n * legal class names. `bigint` is admitted because clsx's signature did and\n * the compiler proved it reachable from two call sites here.\n *\/\nfunction flatten(value: ClassValue): string {\n  if (!value) return \"\";\n\n  if (typeof value === \"string\" || typeof value === \"number\" || typeof value === \"bigint\") {\n    return String(value);\n  }\n\n  if (Array.isArray(value)) {\n    let out = \"\";\n    for (const item of value) {\n      const part = flatten(item);\n      if (part) out = out ? `${out} ${part}` : part;\n    }\n    return out;\n  }\n\n  let out = \"\";\n  for (const key in value) {\n    if (value[key]) out = out ? `${out} ${key}` : key;\n  }\n  return out;\n}\n\nexport function cn(...inputs: ClassValue[]): string {\n  return twMerge(flatten(inputs));\n}\n","type":"registry:lib","target":"components\/fancy\/lib\/utils\/cn.ts"},{"path":"components\/fancy\/lib\/utils\/direction.ts","content":"\/**\n * Writing direction, read from the DOM rather than passed as a prop.\n *\n * Components follow the `dir` the browser already resolved for them, inherited\n * from the nearest ancestor that sets one (usually `<html dir=\"rtl\">`). Reading\n * the computed `direction` means a `dir` on any wrapper works, with nothing to\n * thread through props or context, and SSR renders the same markup for both\n * directions: layout is logical CSS, and only code that measures or maps keys\n * asks this question, always in an effect or an event handler.\n *\/\nexport type Direction = \"ltr\" | \"rtl\";\n\nexport function directionOf(el: Element | null | undefined): Direction {\n  if (!el || typeof window === \"undefined\" || typeof getComputedStyle !== \"function\") return \"ltr\";\n  return getComputedStyle(el).direction === \"rtl\" ? \"rtl\" : \"ltr\";\n}\n\nexport function isRtl(el: Element | null | undefined): boolean {\n  return directionOf(el) === \"rtl\";\n}\n\n\/**\n * The LOGICAL step a horizontal arrow key means: +1 toward the inline end\n * (\"next\"), -1 toward the inline start (\"previous\"), 0 for any other key.\n *\n * ArrowRight moves visually right in both directions, and visually right is\n * the inline END in LTR but the inline START in RTL.\n *\/\nexport function inlineStep(key: string, el: Element | null | undefined): -1 | 0 | 1 {\n  if (key !== \"ArrowRight\" && key !== \"ArrowLeft\") return 0;\n  const forward = key === \"ArrowRight\" ? 1 : -1;\n  return (isRtl(el) ? -forward : forward) as -1 | 1;\n}\n","type":"registry:lib","target":"components\/fancy\/lib\/utils\/direction.ts"},{"path":"components\/fancy\/lib\/hooks\/use-controllable-state.ts","content":"import { useCallback, useRef, useState } from \"react\";\n\n\/**\n * One state slot that works controlled or uncontrolled.\n *\n * ---------------------------------------------------------------------------\n * Why the value is tracked in a ref (fixed 5.32.0)\n * ---------------------------------------------------------------------------\n *\n * This resolved a functional update against the RENDER CLOSURE's `value` and then\n * handed React an already-computed value:\n *\n *     const nextValue = typeof next === \"function\" ? next(value) : next;\n *     setUncontrolledValue(nextValue);\n *\n * So `setValue(fn)` twice in one batch had both calls compute from the same stale\n * `value`, and **the first update was silently lost.** React's own `setState`\n * updater form does not have that problem precisely because React resolves it\n * against the latest state; passing a pre-computed value gives that up.\n *\n * Found by a hook test that paste-held two items inside one `act()` and got one.\n * It is not an exotic case \u2014 any caller that loops, or handles two events in a\n * batch, hits it, and the symptom is a dropped update with nothing to indicate one\n * happened.\n *\n * The fix cannot be \"pass the updater to React\", because `onChange` has to be\n * called with the resulting value and an updater must stay pure \u2014 React may invoke\n * it twice (StrictMode), which would fire `onChange` twice. So the previous value\n * comes from a ref that is re-synced from the authoritative `value` on every render\n * and advanced on every set. Within a batch the ref carries intent; after a render\n * the real value wins.\n *\n * A side effect worth having: `setValue` no longer depends on `value`, so it is\n * stable for the life of the component.\n *\/\nexport function useControllableState<T>(\n  controlledValue: T | undefined,\n  defaultValue: T,\n  onChange?: (value: T) => void,\n): [T, (value: T | ((prev: T) => T)) => void] {\n  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);\n  const isControlled = controlledValue !== undefined;\n  const value = isControlled ? controlledValue : uncontrolledValue;\n\n  const onChangeRef = useRef(onChange);\n  onChangeRef.current = onChange;\n\n  \/\/ Re-synced every render from whichever side owns the value. A controlled parent\n  \/\/ that ignores `onChange` therefore wins on the next render rather than being\n  \/\/ overridden by what this hook optimistically recorded.\n  const valueRef = useRef(value);\n  valueRef.current = value;\n\n  const isControlledRef = useRef(isControlled);\n  isControlledRef.current = isControlled;\n\n  const setValue = useCallback((next: T | ((prev: T) => T)) => {\n    const nextValue =\n      typeof next === \"function\"\n        ? (next as (prev: T) => T)(valueRef.current)\n        : next;\n\n    \/\/ Advance the ref BEFORE notifying, so a second call in the same batch builds\n    \/\/ on this one instead of on what the last render saw.\n    valueRef.current = nextValue;\n\n    if (!isControlledRef.current) {\n      setUncontrolledValue(nextValue);\n    }\n\n    onChangeRef.current?.(nextValue);\n  }, []);\n\n  return [value, setValue];\n}\n","type":"registry:lib","target":"components\/fancy\/lib\/hooks\/use-controllable-state.ts"}]}