{"$schema":"https://ui.shadcn.com/schema/registry-item.json","name":"stepper","type":"registry:ui","title":"Stepper","description":"A multi-step progress indicator on light rails: each completed step sends a single sweep of light down the rail to the next, the current bullet breathes a soft halo, and each check draws itself.","author":"fancy-ui ","categories":["navigation"],"registryDependencies":["https://fancy-ui.rama.app/r/internals.json","https://fancy-ui.rama.app/r/internals-dom.json","https://fancy-ui.rama.app/r/internals-motion.json","https://fancy-ui.rama.app/r/sound.json","https://fancy-ui.rama.app/r/utils.json"],"files":[{"path":"react/src/components/stepper/Step.tsx","content":"\"use client\";\n\nimport { forwardRef, useContext } from \"react\";\nimport type { CSSProperties, ReactNode } from \"react\";\nimport { cn } from \"../../utils\";\nimport { useFancyId } from \"../../internals/use-id\";\nimport { useIsomorphicLayoutEffect } from \"../../internals/dom/ssr\";\nimport { STEPPER_KEY } from \"./types\";\nimport \"./step.css\";\n\nexport interface StepProps {\n\t/**\n\t * The step's primary label. Required: with `children` also omitted, a\n\t * clickable step's only accessible text is its `sr-only` status span —\n\t * every upcoming step in the same `Stepper` would then read as the\n\t * identical \"not started, button\" with nothing to tell them apart.\n\t */\n\tlabel: string;\n\t/** Optional secondary line shown under the label. */\n\tdescription?: string;\n\t/** Overrides the bullet's default content (checkmark / number / outline). */\n\tchildren?: ReactNode;\n\t/** Additional CSS classes */\n\tclassName?: string;\n}\n\ntype StepStatus = \"done\" | \"current\" | \"upcoming\";\n\nconst STATUS_TEXT: Record = {\n\tdone: \"completed\",\n\tcurrent: \"current step\",\n\tupcoming: \"not started\",\n};\n\n/**\n * One stop on a `Stepper`'s rail. Its number and status come from its\n * position among its registered siblings, never from a prop.\n *\n * The root element arrives through the ref channel rather than a `ref`\n * prop, per PORTING.md — the Svelte source declares `ref = $bindable(null)`.\n */\nexport const Step = forwardRef(function Step(\n\t{ label, description, children, className },\n\tref\n) {\n\t// Undefined outside a Stepper: the step then has no shared index or\n\t// status to derive, and renders as a plain, always-\"upcoming\",\n\t// never-clickable item rather than throwing.\n\tconst stepper = useContext(STEPPER_KEY);\n\n\t// `useFancyId()` rather than `_internals/id.ts`'s `uid()`: this needs to\n\t// be stable and available immediately, including during SSR, and\n\t// `uid()` is client-only by design (see its own doc comment).\n\tconst id = useFancyId();\n\n\t// Registers on mount, unregisters on unmount. The effect depends on the\n\t// `register` function alone, never on the whole context object: the\n\t// context is rebuilt every time the registry changes, so depending on it\n\t// would re-run this effect as a result of this effect's own call — see\n\t// `Stepper.tsx` for the fuller account of the loop that guards against.\n\t//\n\t// A layout effect, not a passive one: every number, status colour,\n\t// connector and `aria-current` on the rail is derived from the index this\n\t// call settles, so a passive registration would let the browser paint one\n\t// frame in which every step still reads -1 — bullets numbered \"0\", a\n\t// leading connector on the first step, and no current step at all.\n\tconst register = stepper?.register;\n\tuseIsomorphicLayoutEffect(() => {\n\t\tif (!register) return;\n\t\treturn register(id);\n\t}, [register, id]);\n\n\tconst index = stepper ? stepper.indexOf(id) : -1;\n\n\tconst status: StepStatus = (() => {\n\t\tif (!stepper || index === -1) return \"upcoming\";\n\t\tif (index < stepper.current) return \"done\";\n\t\tif (index === stepper.current) return \"current\";\n\t\treturn \"upcoming\";\n\t})();\n\n\tconst orientation = stepper?.orientation ?? \"horizontal\";\n\tconst clickable = stepper?.clickable ?? false;\n\tconst isFirst = index === 0;\n\tconst isLast = stepper ? index === stepper.count - 1 : true;\n\n\t// A rail is the segment between two neighbouring steps, identified by the\n\t// index of the step it leaves. Horizontally a step draws the rail that\n\t// arrives at it (so the first step has none); vertically it draws the one\n\t// that leaves it (so the last step has none). Either way the rail is lit\n\t// exactly when the step it leaves is done.\n\tconst railFrom = orientation === \"vertical\" ? index : index - 1;\n\tconst connectorDone = stepper && index !== -1 ? railFrom < stepper.current : false;\n\n\tconst animate = stepper?.animate ?? false;\n\n\t// Order within one run of light, in beats. Moving forward from `origin`\n\t// (the previous active step), rail k lights `k - origin` beats after the\n\t// first one; moving back, rails retract from the far end first. Clamped at\n\t// 0: anything outside the run moves (if at all) immediately.\n\tconst origin = stepper?.origin ?? 0;\n\tconst forward = stepper ? stepper.current >= origin : true;\n\tconst railOrder = Math.max(0, forward ? railFrom - origin : origin - 1 - railFrom);\n\n\t// A step the light is travelling *to* (past the origin, up to and\n\t// including the new current one) settles when the light reaches it:\n\t// its incoming rail's beat, plus the part of a sweep it takes the head to\n\t// arrive. `undefined` leaves the CSS fallback (no delay) in charge.\n\tconst arrival =\n\t\tstepper && forward && index > origin && index <= stepper.current\n\t\t\t? index - origin - 1 + 0.6\n\t\t\t: undefined;\n\n\t// Custom properties are written as inline styles, the counterpart of the\n\t// Svelte source's `style:--ft-step-*` directives. An `undefined` arrival\n\t// leaves the attribute off entirely, as the directive does.\n\tconst railStyle = { \"--ft-step-order\": railOrder } as CSSProperties;\n\tconst bulletStyle =\n\t\tarrival === undefined ? undefined : ({ \"--ft-step-arrival\": arrival } as CSSProperties);\n\n\tfunction handleClick() {\n\t\tif (!stepper || !clickable || index === -1) return;\n\t\tstepper.select(index);\n\t}\n\n\tconst bulletClasses = cn(\n\t\t\"ft-step-bullet relative inline-flex size-7 shrink-0 items-center justify-center rounded-full text-[12px] font-semibold tabular-nums\",\n\t\tstatus === \"done\" && \"ft-step-bullet-done\",\n\t\tstatus === \"current\" && \"ft-step-bullet-current ft-step-bullet-halo\",\n\t\tstatus === \"upcoming\" && \"ft-step-bullet-upcoming text-muted-foreground\"\n\t);\n\n\t// `children ?? …` rather than a truthiness test: the Svelte side branches\n\t// on whether the snippet exists, and `null`/`undefined` are the only\n\t// React values that mean \"nothing was passed\".\n\tconst defaultBullet =\n\t\tstatus === \"done\" ? (\n\t\t\t\n\t\t\t\t\n\t\t\t\n\t\t) : (\n\t\t\t\n\t\t\t\t{index + 1}\n\t\t\t\n\t\t);\n\n\tconst bulletContent = (\n\t\t\n\t\t\t{children ?? defaultBullet}\n\t\t\t {STATUS_TEXT[status]}\n\t\t\n\t);\n\n\tconst textContent = (\n\t\t\n\t\t\t{label ? (\n\t\t\t\t\n\t\t\t\t\t{label}\n\t\t\t\t\n\t\t\t) : null}\n\t\t\t{description ? (\n\t\t\t\t\n\t\t\t\t\t{description}\n\t\t\t\t\n\t\t\t) : null}\n\t\t\n\t);\n\n\treturn (\n\t\t\n\t\t\t{orientation === \"horizontal\" ? (\n\t\t\t\t
\n\t\t\t\t\t{!isFirst && (\n\t\t\t\t\t\t\n\t\t\t\t\t)}\n\t\t\t\t\t{clickable ? (\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t{bulletContent}\n\t\t\t\t\t\t\t{textContent}\n\t\t\t\t\t\t\n\t\t\t\t\t) : (\n\t\t\t\t\t\t
\n\t\t\t\t\t\t\t{bulletContent}\n\t\t\t\t\t\t\t{textContent}\n\t\t\t\t\t\t
\n\t\t\t\t\t)}\n\t\t\t\t
\n\t\t\t) : (\n\t\t\t\t<>\n\t\t\t\t\t{/*\n\t\t\t\t\t\t`-mb-7` mirrors the li's own `pb-7`: without it the bullet column\n\t\t\t\t\t\tstretches only to the li's content box, which is barely taller than\n\t\t\t\t\t\tthe bullet, so the rail's `flex-1` resolved to ~0px and the vertical\n\t\t\t\t\t\trail never showed. Reaching into the padding gives it the gap to span.\n\t\t\t\t\t*/}\n\t\t\t\t\t
\n\t\t\t\t\t\t{bulletContent}\n\t\t\t\t\t\t{!isLast && (\n\t\t\t\t\t\t\t\n\t\t\t\t\t\t)}\n\t\t\t\t\t
\n\t\t\t\t\t{clickable ? (\n\t\t\t\t\t\t\n\t\t\t\t\t\t\t{textContent}\n\t\t\t\t\t\t\n\t\t\t\t\t) : (\n\t\t\t\t\t\t
\n\t\t\t\t\t\t\t{textContent}\n\t\t\t\t\t\t
\n\t\t\t\t\t)}\n\t\t\t\t\n\t\t\t)}\n\t\t\n\t);\n});\n\nStep.displayName = \"Step\";\n","type":"registry:ui","target":"@ui/fancy/components/stepper/Step.tsx"},{"path":"react/src/components/stepper/Stepper.tsx","content":"\"use client\";\n\nimport { forwardRef, useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport type { ReactNode } from \"react\";\nimport { cn } from \"../../utils\";\nimport { useSoundCue } from \"../../sound/use-sound\";\nimport { useReducedMotion } from \"../../internals/motion/media-query\";\nimport { STEPPER_KEY } from \"./types\";\nimport type { StepperContext } from \"./types\";\n\nexport interface StepperProps {\n\t/**\n\t * The active step's 0-based index. Controlled when supplied: pair it\n\t * with `onCurrentChange`, the React counterpart of the Svelte source's\n\t * `bind:current`. Left out, the stepper keeps the index itself and\n\t * starts at 0.\n\t */\n\tcurrent?: number;\n\t/** Called with the new index whenever it changes, however the change happened. */\n\tonCurrentChange?: (current: number) => void;\n\t/** The rail's stacking axis. Defaults to `\"horizontal\"`. */\n\torientation?: \"horizontal\" | \"vertical\";\n\t/** Whether steps render as buttons a reader can click to jump between them. Defaults to `false`. */\n\tclickable?: boolean;\n\t/** Called with a step's index when it's activated by a click. Only fires when `clickable`. */\n\tonStepClick?: (index: number) => void;\n\t/** The `Step`s. */\n\tchildren?: ReactNode;\n\t/** Additional CSS classes */\n\tclassName?: string;\n\t/**\n\t * Plays the select cue through the sound controller. Off by default;\n\t * only audible once the user has enabled sound.\n\t */\n\tsound?: boolean;\n}\n\n/**\n * The rail a set of `Step`s reads its shared state from.\n *\n * The root element arrives through the ref channel rather than a `ref`\n * prop, per PORTING.md — the Svelte source declares `ref = $bindable(null)`.\n *\n * Rest props are not spread: the Svelte source reads only these props off\n * `$props()` and has no `...restProps`, so the port carries no wider\n * attribute surface than the component it mirrors.\n */\nexport const Stepper = forwardRef(function Stepper(\n\t{\n\t\tcurrent,\n\t\tonCurrentChange,\n\t\torientation = \"horizontal\",\n\t\tclickable = false,\n\t\tonStepClick,\n\t\tchildren,\n\t\tclassName,\n\t\tsound = false,\n\t},\n\tref\n) {\n\t// `current = $bindable(0)` on the Svelte side. A supplied prop wins and\n\t// the consumer owns the value; with nothing supplied the component owns\n\t// it, starting at the same 0 the Svelte default uses.\n\tconst [uncontrolledCurrent, setUncontrolledCurrent] = useState(0);\n\tconst isControlled = current !== undefined;\n\tconst activeIndex = isControlled ? current : uncontrolledCurrent;\n\n\t// Ids, not elements: a `Step` can register the instant its own effect\n\t// runs, with no need to wait on a ref to have landed first.\n\t//\n\t// The live registry is a ref, and the state array is the render-visible\n\t// copy of it. Both are needed: a `Step` registers from its own mount\n\t// effect, and React runs sibling effects back to back before it\n\t// re-renders anything, so the second sibling has to see the first\n\t// sibling's write immediately — a `setState` updater alone would work,\n\t// but `register` also has to *read* the current list synchronously to\n\t// refuse a duplicate and to hand back an unregister that splices the\n\t// right entry.\n\t//\n\t// `register` is wrapped in a `useCallback` with an empty dependency\n\t// list, and that is load-bearing rather than tidy: a `Step`'s\n\t// registration effect depends on it, so a `register` rebuilt whenever\n\t// the registry changes would make every step's effect re-run the\n\t// instant its own call mutated the registry — unregister, register,\n\t// re-render, unregister, forever. This is the React shape of the exact\n\t// bug the Svelte source's `untrack` calls guard against.\n\tconst registryRef = useRef([]);\n\tconst [registered, setRegistered] = useState([]);\n\n\tconst register = useCallback((id: string): (() => void) => {\n\t\tif (!registryRef.current.includes(id)) {\n\t\t\tregistryRef.current = [...registryRef.current, id];\n\t\t\tsetRegistered(registryRef.current);\n\t\t}\n\t\treturn () => {\n\t\t\tconst index = registryRef.current.indexOf(id);\n\t\t\tif (index !== -1) {\n\t\t\t\tconst next = [...registryRef.current];\n\t\t\t\tnext.splice(index, 1);\n\t\t\t\tregistryRef.current = next;\n\t\t\t\tsetRegistered(next);\n\t\t\t}\n\t\t};\n\t}, []);\n\n\t// Reads the rendered copy, not the ref: a `Step` calls this during its\n\t// own render, and the answer has to be the one this render pass was\n\t// scheduled for.\n\tconst indexOf = useCallback((id: string): number => registered.indexOf(id), [registered]);\n\n\t// Motion is opt-in on the client only: the server render (and the\n\t// hydration pass) paints the still composition, and the animated classes\n\t// arrive once the browser has actually been asked about\n\t// `prefers-reduced-motion` — `asked` flips in a mount effect, the\n\t// counterpart of the Svelte source's `reduced.start()` + `asked = true`.\n\t// Under reduce they never arrive, so the rails fill by colour alone.\n\tconst reduced = useReducedMotion();\n\tconst [asked, setAsked] = useState(false);\n\tuseEffect(() => {\n\t\tsetAsked(true);\n\t}, []);\n\tconst animate = asked && !reduced;\n\n\t// Where the light set off from: the active index *before* the latest\n\t// change. Steps read it to order the rail sweeps (and the arrival of the\n\t// bullets behind them) as one continuous run from the old step to the new\n\t// one, instead of every rail lighting in the same frame. It starts at 0 —\n\t// not at `current` — so the first paint plays the same run from the first\n\t// step, a one-time arrival over rails that are already filled.\n\t//\n\t// The Svelte source writes it from an `$effect.pre`, i.e. before the DOM\n\t// update that shows the new index. The React counterpart is the \"adjust\n\t// state while rendering\" pattern: when the index differs from the one last\n\t// settled, the pair is updated during this render, React re-renders before\n\t// committing, and no frame ever shows the new index with a stale origin.\n\tconst [run, setRun] = useState(() => ({ settled: activeIndex, origin: 0 }));\n\tlet origin = run.origin;\n\tif (run.settled !== activeIndex) {\n\t\torigin = run.settled;\n\t\tsetRun({ settled: activeIndex, origin: run.settled });\n\t}\n\n\tconst playCue = useSoundCue(sound);\n\n\tconst select = useCallback(\n\t\t(index: number) => {\n\t\t\tif (!clickable) return;\n\t\t\t// Changed-only, and ahead of every callback: re-picking the step that\n\t\t\t// is already current still reports through `onStepClick` and\n\t\t\t// `onCurrentChange`, but makes no sound — the rail did not move.\n\t\t\tif (activeIndex !== index) playCue(\"select\");\n\t\t\tonStepClick?.(index);\n\t\t\tif (!isControlled) setUncontrolledCurrent(index);\n\t\t\tonCurrentChange?.(index);\n\t\t},\n\t\t[clickable, isControlled, onStepClick, onCurrentChange, activeIndex, playCue]\n\t);\n\n\t// Rebuilt when any of its inputs actually changes — that rebuild is what\n\t// re-renders the steps reading it, and it is the React counterpart of the\n\t// Svelte context's live getters.\n\tconst context = useMemo(\n\t\t() => ({\n\t\t\torientation,\n\t\t\tclickable,\n\t\t\tcurrent: activeIndex,\n\t\t\tcount: registered.length,\n\t\t\torigin,\n\t\t\tanimate,\n\t\t\tregister,\n\t\t\tindexOf,\n\t\t\tselect,\n\t\t}),\n\t\t[orientation, clickable, activeIndex, registered, origin, animate, register, indexOf, select]\n\t);\n\n\treturn (\n\t\t\n\t\t\t{/*\n\t\t\t\t`role=\"list\"` is stated rather than left implicit: `list-style: none`\n\t\t\t\tstrips list semantics in Safari, and a step's position in the count is\n\t\t\t\tthe only thing telling a reader it is \"2 of 5\" — the visible number is\n\t\t\t\t`aria-hidden`.\n\t\t\t*/}\n\t\t\t\n\t\t\t\t{children}\n\t\t\t\n\t\t\n\t);\n});\n\nStepper.displayName = \"Stepper\";\n\n/*\n No colocated stylesheet here: the root `
    ` itself never paints the brand\n purple — only a `Step`'s current bullet, halo, and lit rail do — so\n `--ft-nav-accent` is declared in `step.css` instead, the same split a toggle\n group (no purple of its own) and its items (declaring their focus-ring accent\n locally) already use.\n*/\n","type":"registry:ui","target":"@ui/fancy/components/stepper/Stepper.tsx"},{"path":"react/src/components/stepper/index.ts","content":"\"use client\";\n\nexport { Stepper } from \"./Stepper\";\nexport type { StepperProps } from \"./Stepper\";\nexport { Step } from \"./Step\";\nexport type { StepProps } from \"./Step\";\nexport { STEPPER_KEY } from \"./types\";\nexport type { StepperContext } from \"./types\";\n","type":"registry:ui","target":"@ui/fancy/components/stepper/index.ts"},{"path":"react/src/components/stepper/step.css","content":"/*\n * Port note: Svelte scoped these rules; plain CSS is global, so every\n * selector below is anchored on a class this component owns and puts on its\n * own elements (`.ft-step`, `.ft-step-bullet*`, `.ft-step-connector*`,\n * `.ft-step-glyph`, `.ft-step-check`, `.ft-step-trigger`, `.ft-step-animate`\n * — all of them the Svelte source's own names, already on the elements'\n * class lists). No anchor had to be added. Everything below is copied\n * verbatim from the Svelte source's