Skip to content

Production-ready animations, transitions, backgrounds, and scenes for Remotion

feat: added stepper component

dev_wandryd1dcfa405a55
diff --git a/components/docs/component-preview.tsx b/components/docs/component-preview.tsx
index 4a5c83f1..de94a406 100644
--- a/components/docs/component-preview.tsx
+++ b/components/docs/component-preview.tsx
@@ -167,7 +167,7 @@ function Preview({
</TabsContent>
</Tabs>
- <div className="overflow-hidden rounded-2xl">
+ <div className="overflow-hidden ">
<div className="flex items-center justify-between pt-4 pb-2">
<span className="text-sm font-medium text-foreground">Customize</span>
<div className="flex items-center gap-1">
diff --git a/components/docs/examples/index.tsx b/components/docs/examples/index.tsx
index 62759688..4466bfef 100644
--- a/components/docs/examples/index.tsx
+++ b/components/docs/examples/index.tsx
@@ -60,6 +60,10 @@ import {
ToggleGroupExampleScene,
toggleGroupExampleCode,
} from "./toggle-group-example";
+import {
+ StepperExampleScene,
+ stepperExampleCode,
+} from "./stepper-example";
export interface ExampleEntry {
Component: ComponentType;
@@ -284,4 +288,13 @@ export const examples: Record<string, ExampleEntry> = {
width: W,
height: H,
},
+ "stepper-example": {
+ Component: StepperExampleScene,
+ code: stepperExampleCode,
+ // Final step (index 2) ease completes at 110 + 24 = 134; a short settle then loop.
+ durationInFrames: 150,
+ fps: FPS,
+ width: W,
+ height: H,
+ },
};
diff --git a/components/docs/examples/stepper-example.tsx b/components/docs/examples/stepper-example.tsx
new file mode 100644
index 00000000..15ceed54
--- /dev/null
+++ b/components/docs/examples/stepper-example.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import { Stepper } from "@/registry/remocn-ui/stepper";
+import { useStepperTransition } from "@/registry/remocn-ui/stepper/use-stepper-transition";
+
+export const StepperExampleScene = () => {
+ // Advance through 3 steps: "Account" (0) → "Plan" (1) → "Done" (2).
+ // Start explicitly at index 0 (else the timeline holds the first step's index
+ // before it fires); each step arrives at the end of a 24-frame ease.
+ const stepperStyle = useStepperTransition([
+ { at: 0, index: 0 },
+ { at: 50, index: 1, duration: 24 },
+ { at: 110, index: 2, duration: 24 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ {/* Stepper renders position:absolute;inset:0 — it fills and centers itself. */}
+ <Stepper style={stepperStyle} />
+ </div>
+ );
+};
+
+export const stepperExampleCode = `import { Stepper } from "@/components/remocn/stepper";
+import { useStepperTransition } from "@/components/remocn/use-stepper-transition";
+
+export const Scene = () => {
+ // Advance through 3 steps: "Account" → "Plan" → "Done".
+ // Start explicitly at index 0; each step arrives after a 24-frame ease.
+ const stepperStyle = useStepperTransition([
+ { at: 0, index: 0 },
+ { at: 50, index: 1, duration: 24 },
+ { at: 110, index: 2, duration: 24 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <Stepper style={stepperStyle} />
+ </div>
+ );
+};`;
diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.json
index 1cbb3273..ba02ce45 100644
--- a/content/docs/ui/components/meta.json
+++ b/content/docs/ui/components/meta.json
@@ -1,5 +1,5 @@
{
"title": "Components",
"collapsible": false,
- "pages": ["accordion", "alert-dialog", "button", "checkbox", "combobox", "command-menu", "context-menu", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "popover", "progress", "radio", "select", "skeleton", "slider", "spinner", "switch", "tabs", "toast", "toggle-group", "tooltip"]
+ "pages": ["accordion", "alert-dialog", "button", "checkbox", "combobox", "command-menu", "context-menu", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "popover", "progress", "radio", "select", "skeleton", "slider", "spinner", "stepper", "switch", "tabs", "toast", "toggle-group", "tooltip"]
}
diff --git a/content/docs/ui/components/stepper.mdx b/content/docs/ui/components/stepper.mdx
new file mode 100644
index 00000000..7b63d703
--- /dev/null
+++ b/content/docs/ui/components/stepper.mdx
@@ -0,0 +1,142 @@
+---
+title: Stepper
+description: A multi-step progress indicator that advances along a scripted numeric position timeline
+---
+
+<ComponentPreview name="stepper" />
+
+A value-channel atom whose active position (`0`–`n-1`) is a pure function of the `activeIndex` prop or an interpolated `StepperStyle` from `useStepperTransition`. The component reads no frame — only the position you give it. This is the **value-channel** variant of the primitive pattern: instead of a string-state timeline it drives a continuous numeric position channel, the same deviation used by the Progress primitive.
+
+As `position` advances, each circle fills from muted to primary, the checkmark draws in, and the connector between steps fills — all derived purely from the single float `position` value.
+
+## Installation
+
+<InstallBlock name="stepper" />
+
+<Note>
+Installing `stepper` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) via `registryDependencies` (`["remocn-ui"]`). You do not need to install it separately. Both `stepper` (the renderer) and `use-stepper-transition` (the hook) are copied into your project.
+</Note>
+
+## Example
+
+<LiveExample name="stepper-example" />
+
+## Step position
+
+Instead of a string-state timeline, `useStepperTransition` takes an array of `StepperStep` objects that describe a scripted index path:
+
+```ts
+interface StepperStep {
+ at: number; // LOCAL (Sequence-relative) authored frame the stepper finishes reaching index
+ index: number; // Target active-step index (0..n-1)
+ duration?: number; // Frames the move INTO this index takes. Omitted → DEFAULT_DURATION (24)
+ easing?: EasingName; // Override easing for the move into this index. Default "out"
+}
+```
+
+`at` is the **arrival frame** — the frame when the stepper finishes reaching `index`. The move itself runs over `[at - duration, at)`. Before the first arrival, the stepper holds at the first step's index.
+
+### Numeric-channel deviation
+
+`Stepper` differs from state atoms (Button, Tabs, etc.) in one key way: there is no string `state` union and no `useCurrentState` snap path. The stepper's visual is always numeric — a continuous float `position` — so `useStepperTransition` folds the index path directly into a `StepperStyle`. The snap equivalent is simply passing a fixed `activeIndex` prop.
+
+### Completed, active, and future derivation
+
+Every circle and connector is a pure function of `position`:
+
+- **Completed** step `i`: `position >= i + 1` — the circle fills to primary, the checkmark draws fully in.
+- **Active** step `i`: `Math.floor(position) === i` and not yet completed — the circle is transitioning, the check is drawing in.
+- **Future** step `i`: `position < i` — the circle stays muted, no check.
+- **Connector** between steps `i` and `i+1`: fills `clamp(position - i, 0, 1)` of primary color.
+
+A lerp of the single `position` value advances all circles and connectors smoothly without jumps.
+
+## Snap usage
+
+Pass `activeIndex` directly — the component snaps instantly to that step. Useful for static previews or when you drive state from your own logic:
+
+```tsx
+import { Stepper } from "@/components/remocn/stepper";
+
+export const Scene = () => (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <Stepper activeIndex={1} />
+ </div>
+);
+```
+
+## Smooth transitions
+
+Position changes via `activeIndex` snap with no tween. For animated step advances, use `useStepperTransition` from the copied `use-stepper-transition.ts` file. It reads the frame, interpolates between index steps, and returns a resolved `StepperStyle` — pass it to the `style` prop:
+
+```tsx
+import { Stepper } from "@/components/remocn/stepper";
+import { useStepperTransition } from "@/components/remocn/use-stepper-transition";
+
+export const Scene = () => {
+ const style = useStepperTransition([
+ { at: 50, index: 1, duration: 24 },
+ { at: 110, index: 2, duration: 24 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <Stepper style={style} />
+ </div>
+ );
+};
+```
+
+The `duration` field on each step overrides the file's `DEFAULT_DURATION` (= `24`) for that specific move. The default easing per step is `"out"` — the indicator decelerates as it nears the target index. To globally tune timing and easing, edit `use-stepper-transition.ts` directly in your project — that file is yours (shadcn "own your code" philosophy).
+
+`style` takes precedence over `activeIndex` when both are provided.
+
+## Orientation
+
+Only `"horizontal"` is implemented in this release. Passing `orientation="vertical"` is accepted but falls back to horizontal — vertical layout is planned for a future wave.
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "steps",
+ type: "string[]",
+ default: "[\"Account\", \"Plan\", \"Done\"]",
+ description: "Step labels. Their count determines the total number of steps.",
+ },
+ {
+ name: "activeIndex",
+ type: "number",
+ default: "0",
+ description: "Active step index 0..n-1 (snap path). May be a float but is typically an integer. Ignored when style is provided.",
+ },
+ {
+ name: "style",
+ type: "StepperStyle",
+ description: "Resolved animated visual (smooth path). Pass an interpolated StepperStyle from useStepperTransition. Takes precedence over activeIndex when provided.",
+ },
+ {
+ name: "orientation",
+ type: "\"horizontal\" | \"vertical\"",
+ default: "\"horizontal\"",
+ description: "Layout orientation. Only horizontal is implemented this release — vertical falls back to horizontal.",
+ },
+ {
+ name: "theme",
+ type: "Partial<RemocnTheme>",
+ description: "Per-component theme override. Merges with the active RemocnUIProvider theme and the mode defaults. Must be concrete oklch/hex/rgb values — not CSS custom properties.",
+ },
+ {
+ name: "mode",
+ type: "\"light\" | \"dark\"",
+ default: "\"light\"",
+ description: "Sets the base palette. Overrides the mode on RemocnUIProvider when both are present.",
+ },
+ {
+ name: "className",
+ type: "string",
+ description: "Optional className applied to the outer wrapper element.",
+ },
+ ]}
+/>
diff --git a/registry/__index__.tsx b/registry/__index__.tsx
index d86197d3..aa0763ac 100644
--- a/registry/__index__.tsx
+++ b/registry/__index__.tsx
@@ -163,6 +163,8 @@ import { ContextMenuPreview } from "@/registry/remocn-ui/context-menu/preview";
import { contextMenuConfig } from "@/registry/remocn-ui/context-menu/config";
import { ToggleGroup } from "@/registry/remocn-ui/toggle-group";
import { toggleGroupConfig } from "@/registry/remocn-ui/toggle-group/config";
+import { StepperPreview } from "@/registry/remocn-ui/stepper/preview";
+import { stepperConfig } from "@/registry/remocn-ui/stepper/config";
import { ZoomThroughTransition } from "@/registry/remocn/zoom-through-transition";
import { zoomThroughTransitionConfig } from "@/registry/remocn/zoom-through-transition/config";
@@ -398,6 +400,9 @@ const registry: Record<string, RegistryEntry> = {
// toggle-group registers RAW (no preview wrapper): like tabs it paints its own
// opaque inset:0 centered stage, so the customizer mounts it directly.
"toggle-group": { Component: ToggleGroup, config: toggleGroupConfig },
+ // stepper's customizer Component is the preview-only StepperPreview wrapper: a
+ // bare wide horizontal element would sit top-left, so the wrapper centers it.
+ "stepper": { Component: StepperPreview, config: stepperConfig },
"spinner": { Component: Spinner, config: spinnerConfig },
};
diff --git a/registry/remocn-ui/registry.json b/registry/remocn-ui/registry.json
index 6a7e6b0d..0b287915 100644
--- a/registry/remocn-ui/registry.json
+++ b/registry/remocn-ui/registry.json
@@ -611,6 +611,26 @@
"target": "components/remocn/use-toggle-group-transition.ts"
}
]
+ },
+ {
+ "name": "stepper",
+ "type": "registry:component",
+ "title": "UI Stepper",
+ "description": "A horizontal onboarding stepper whose progress is a pure function of a continuous step index (value-channel deviation). Every circle (fill, number, stroke-dash check) and connector (primary fill fraction) derives purely from the float position; useStepperTransition reads the frame and eases position between step indices.",
+ "dependencies": ["remotion"],
+ "registryDependencies": ["remocn-ui"],
+ "files": [
+ {
+ "path": "stepper/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/stepper.tsx"
+ },
+ {
+ "path": "stepper/use-stepper-transition.ts",
+ "type": "registry:component",
+ "target": "components/remocn/use-stepper-transition.ts"
+ }
+ ]
}
]
}
diff --git a/registry/remocn-ui/stepper/__tests__/README.md b/registry/remocn-ui/stepper/__tests__/README.md
new file mode 100644
index 00000000..f4153b33
--- /dev/null
+++ b/registry/remocn-ui/stepper/__tests__/README.md
@@ -0,0 +1,52 @@
+# stepper/__tests__
+
+Verification tests for the pure, deterministic surface of the `stepper` primitive.
+
+## What is tested
+
+| Section | Source | Coverage |
+|---------|--------|----------|
+| `DEFAULT_DURATION` | `use-stepper-transition.ts` | Constant equals 24 |
+| `stepperStyleContext` | `index.tsx` lines 76–85 | primary/primaryFg/mutedBg/border/mutedFg/foreground token mapping |
+| `stepperStyle` | `index.tsx` lines 91–93 | Identity map: `stepperStyle(n).position === n` for integers and floats |
+| `stepCircleAt` | `index.tsx` lines 108–123 | fill/checkDraw/active at positions 0, 0.5, 1, 1.5, 2; clamp at 0 and 1; fill===checkDraw invariant |
+| `connectorFillAt` | `index.tsx` lines 126–128 | Fill fraction 0/0.5/1 at key positions; clamp at 0 for past connector |
+| `tweenStepperStyle` | `use-stepper-transition.ts` lines 34–40 | t=0→a; t=1→b; t=0.5 midpoint; t=0.25 quarter; identity; reverse direction |
+| `stepperStyleAt` | `use-stepper-transition.ts` lines 66–102 | empty steps; before-first; past-last; mid-window eased (non-linear); at boundary; two-segment timeline; custom duration; single-step edge case |
+| `stepperConfig.controls` | `config.ts` | activeIndex (number, default 1, min 0, max 2, step 1); mode (select, default light) |
+| `stepperConfig.snippet` | `config.ts` | import line; structural round-trip; activeIndex always emitted; steps literal always emitted; mode omitted at default; mode emitted non-default; numeric round-trip |
+
+## What is NOT tested
+
+**Render path** — `Stepper` calls `useRemocnTheme` (React context) and renders JSX. Not exercised here.
+
+**`useStepperTransition`** — This hook calls `useCurrentFrame()` from Remotion and cannot run outside a render tree. Its pure body is the exported `stepperStyleAt` function, which is tested directly. The relationship is documented in `use-stepper-transition.ts`:
+> `useStepperTransition` is exactly `stepperStyleAt(steps, useCurrentFrame() * speed, opts)`
+
+**`StepperStep.easing` overrides** — The `easing` field on each step can override the default `"out"` easing per-transition. The default `"out"` path is covered by the mid-window tests. Custom easing names (`"in"`, `"inOut"`, etc.) delegate to `easings[name]` from `@/lib/remocn-ui` — their correctness is covered by the core timeline tests, not here.
+
+## Animation model
+
+`StepperStyle` has exactly one animated field: `position` — a continuous float (0..n-1) representing where the active step sits. Every visual in the render derives purely from this single value:
+
+| Derived quantity | Formula |
+|---|---|
+| `fill` for step i | `clamp01(position - i)` |
+| `checkDraw` for step i | same as `fill` |
+| `active` for step i | `Math.floor(position) === i && fill < 1` |
+| connector fill between i and i+1 | `clamp01(position - i)` |
+
+A lerp of `position` advances all steps and connectors simultaneously without jumps — the same single-value design as `indicatorOffset` in toggle-group and tabs.
+
+`stepperStyleAt` applies `easings.out` to the linear progress before interpolating, so `out(0.5) = 0.875` — the mid-window test at `raw=12` of a 24-frame window confirms `position=0.875`, not the linear `0.5`.
+
+## Determinism grep checklist
+
+Run this on `stepper/index.tsx` — it must print nothing:
+
+```bash
+grep -nE "useState|useEffect|useCurrentFrame|onClick|onChange|addEventListener|Date\.now|Math\.random|requestAnimationFrame" \
+ registry/remocn-ui/stepper/index.tsx
+```
+
+The `Stepper` component is a pure renderer: no frame reading, no local state, no side effects. Frame reading lives exclusively in `useStepperTransition` (`use-stepper-transition.ts`), which is not imported by `index.tsx`.
diff --git a/registry/remocn-ui/stepper/__tests__/stepper.test.ts b/registry/remocn-ui/stepper/__tests__/stepper.test.ts
new file mode 100644
index 00000000..ed02c9a7
--- /dev/null
+++ b/registry/remocn-ui/stepper/__tests__/stepper.test.ts
@@ -0,0 +1,657 @@
+/**
+ * Verification tests for the PURE / DETERMINISTIC parts of `stepper`.
+ *
+ * Scope:
+ * - registry/remocn-ui/stepper/index.tsx
+ * StepperStyle interface — position field semantics
+ * stepperStyle(activeIndex) — pure identity preset
+ * stepperStyleContext(theme) — token mapping
+ * stepCircleAt(i, position) — per-step fill/checkDraw/active thresholds
+ * connectorFillAt(i, position) — connector fill fraction
+ * - registry/remocn-ui/stepper/use-stepper-transition.ts
+ * tweenStepperStyle(a, b, t) — pure single-field lerp
+ * stepperStyleAt(steps, raw, opts) — pure exported core of useStepperTransition
+ * DEFAULT_DURATION constant
+ * StepperStep interface semantics
+ * - registry/remocn-ui/stepper/config.ts
+ * stepperConfig.controls wiring + stepperConfig.snippet codegen
+ *
+ * The render path (Stepper JSX) calls `useRemocnTheme` (React context) — NOT
+ * exercised here. `useStepperTransition` is exactly
+ * `stepperStyleAt(steps, useCurrentFrame() * speed, opts)` — we call
+ * `stepperStyleAt` directly (the exported pure core).
+ *
+ * Runner: Bun's built-in test runner (TypeScript-native, no framework dep).
+ * bun test registry/remocn-ui/stepper/__tests__
+ *
+ * --------------------------------------------------------------------------
+ * IMPORT STRATEGY
+ * --------------------------------------------------------------------------
+ * Relative imports for component source; `@/lib/remocn-ui` for core alias.
+ * `stepperStyleAt` and `tweenStepperStyle` are pure value functions — they
+ * call neither `useCurrentFrame()` nor `useRemocnTheme` at import or call time.
+ * `useStepperTransition` IS a hook and is NOT imported; we call `stepperStyleAt`
+ * directly (the exported pure core, documented as such in the source).
+ * --------------------------------------------------------------------------
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+ stepperStyle,
+ stepperStyleContext,
+ stepCircleAt,
+ connectorFillAt,
+} from "../index";
+import {
+ tweenStepperStyle,
+ stepperStyleAt,
+ DEFAULT_DURATION,
+ type StepperStep,
+} from "../use-stepper-transition";
+import { stepperConfig } from "../config";
+import { defaultLightTheme, easings } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Shared fixtures
+// ===========================================================================
+
+/** Convenience wrapper for snippet(). */
+type SnippetValues = {
+ activeIndex?: number;
+ mode?: string;
+};
+const snippet = (values: SnippetValues): string =>
+ stepperConfig.snippet(values as Record<string, unknown>);
+
+// ===========================================================================
+// 1. DEFAULT_DURATION constant
+// ===========================================================================
+
+describe("DEFAULT_DURATION", () => {
+ it("is a positive number", () => {
+ expect(typeof DEFAULT_DURATION).toBe("number");
+ expect(DEFAULT_DURATION).toBeGreaterThan(0);
+ });
+
+ it("equals 24 (the authored value)", () => {
+ expect(DEFAULT_DURATION).toBe(24);
+ });
+});
+
+// ===========================================================================
+// 2. stepperStyleContext — token mapping
+// MIRROR of index.tsx lines 76-85.
+// Maps: primary, primaryFg, mutedBg, border, mutedFg, foreground.
+// ===========================================================================
+
+describe("stepperStyleContext: token mapping (light theme)", () => {
+ const ctx = stepperStyleContext(defaultLightTheme);
+
+ it("primary equals theme.primary", () => {
+ expect(ctx.primary).toBe(defaultLightTheme.primary);
+ });
+
+ it("primaryFg equals theme.primaryForeground", () => {
+ expect(ctx.primaryFg).toBe(defaultLightTheme.primaryForeground);
+ });
+
+ it("mutedBg equals theme.muted", () => {
+ expect(ctx.mutedBg).toBe(defaultLightTheme.muted);
+ });
+
+ it("border equals theme.border", () => {
+ expect(ctx.border).toBe(defaultLightTheme.border);
+ });
+
+ it("mutedFg equals theme.mutedForeground", () => {
+ expect(ctx.mutedFg).toBe(defaultLightTheme.mutedForeground);
+ });
+
+ it("foreground equals theme.foreground", () => {
+ expect(ctx.foreground).toBe(defaultLightTheme.foreground);
+ });
+});
+
+// ===========================================================================
+// 3. stepperStyle preset — pure (activeIndex) => StepperStyle
+// MIRROR of index.tsx lines 91-93.
+// stepperStyle(activeIndex) = { position: activeIndex }
+// ===========================================================================
+
+describe("stepperStyle: identity map", () => {
+ it("stepperStyle(0) returns position=0", () => {
+ expect(stepperStyle(0).position).toBe(0);
+ });
+
+ it("stepperStyle(1) returns position=1", () => {
+ expect(stepperStyle(1).position).toBe(1);
+ });
+
+ it("stepperStyle(2) returns position=2", () => {
+ expect(stepperStyle(2).position).toBe(2);
+ });
+
+ it("stepperStyle(1.5) returns position=1.5 (float passthrough)", () => {
+ expect(stepperStyle(1.5).position).toBe(1.5);
+ });
+});
+
+// ===========================================================================
+// 4. stepCircleAt — per-step fill / checkDraw / active thresholds
+// MIRROR of index.tsx lines 108-123.
+// fill = clamp01(position - i)
+// checkDraw = fill
+// active = Math.floor(position) === i && fill < 1
+//
+// Key positions tested (3-step stepper, i in {0,1,2}):
+// position=0: step 0 active, steps 1/2 future
+// position=0.5: step 0 mid-fill (active), step 1 future
+// position=1: step 0 completed, step 1 active
+// position=1.5: step 0 completed, step 1 mid-fill (active), step 2 future
+// position=2: steps 0/1 completed, step 2 active (fill=0)
+// ===========================================================================
+
+describe("stepCircleAt: position=0 (first step active, rest future)", () => {
+ it("step 0: fill=0, checkDraw=0, active=true", () => {
+ const r = stepCircleAt(0, 0);
+ expect(r.fill).toBe(0);
+ expect(r.checkDraw).toBe(0);
+ expect(r.active).toBe(true);
+ });
+
+ it("step 1: fill=0, checkDraw=0, active=false (future)", () => {
+ const r = stepCircleAt(1, 0);
+ expect(r.fill).toBe(0);
+ expect(r.checkDraw).toBe(0);
+ expect(r.active).toBe(false);
+ });
+
+ it("step 2: fill=0, checkDraw=0, active=false (future)", () => {
+ const r = stepCircleAt(2, 0);
+ expect(r.fill).toBe(0);
+ expect(r.checkDraw).toBe(0);
+ expect(r.active).toBe(false);
+ });
+});
+
+describe("stepCircleAt: position=0.5 (step 0 mid-fill, still active)", () => {
+ it("step 0: fill=0.5, checkDraw=0.5, active=true", () => {
+ const r = stepCircleAt(0, 0.5);
+ expect(r.fill).toBeCloseTo(0.5, 10);
+ expect(r.checkDraw).toBeCloseTo(0.5, 10);
+ expect(r.active).toBe(true);
+ });
+
+ it("step 1: fill=0, checkDraw=0, active=false", () => {
+ const r = stepCircleAt(1, 0.5);
+ expect(r.fill).toBe(0);
+ expect(r.checkDraw).toBe(0);
+ expect(r.active).toBe(false);
+ });
+});
+
+describe("stepCircleAt: position=1 (step 0 completed, step 1 active)", () => {
+ it("step 0: fill=1, checkDraw=1, active=false (completed)", () => {
+ const r = stepCircleAt(0, 1);
+ expect(r.fill).toBe(1);
+ expect(r.checkDraw).toBe(1);
+ expect(r.active).toBe(false);
+ });
+
+ it("step 1: fill=0, checkDraw=0, active=true", () => {
+ const r = stepCircleAt(1, 1);
+ expect(r.fill).toBe(0);
+ expect(r.checkDraw).toBe(0);
+ expect(r.active).toBe(true);
+ });
+
+ it("step 2: fill=0, checkDraw=0, active=false (future)", () => {
+ const r = stepCircleAt(2, 1);
+ expect(r.fill).toBe(0);
+ expect(r.checkDraw).toBe(0);
+ expect(r.active).toBe(false);
+ });
+});
+
+describe("stepCircleAt: position=1.5 (step 0 completed, step 1 mid-fill)", () => {
+ it("step 0: fill=1, checkDraw=1, active=false (completed)", () => {
+ const r = stepCircleAt(0, 1.5);
+ expect(r.fill).toBe(1);
+ expect(r.checkDraw).toBe(1);
+ expect(r.active).toBe(false);
+ });
+
+ it("step 1: fill=0.5, checkDraw=0.5, active=true", () => {
+ const r = stepCircleAt(1, 1.5);
+ expect(r.fill).toBeCloseTo(0.5, 10);
+ expect(r.checkDraw).toBeCloseTo(0.5, 10);
+ expect(r.active).toBe(true);
+ });
+
+ it("step 2: fill=0, checkDraw=0, active=false (future)", () => {
+ const r = stepCircleAt(2, 1.5);
+ expect(r.fill).toBe(0);
+ expect(r.checkDraw).toBe(0);
+ expect(r.active).toBe(false);
+ });
+});
+
+describe("stepCircleAt: position=2 (steps 0/1 completed, step 2 active)", () => {
+ it("step 0: fill=1, checkDraw=1, active=false (completed)", () => {
+ const r = stepCircleAt(0, 2);
+ expect(r.fill).toBe(1);
+ expect(r.checkDraw).toBe(1);
+ expect(r.active).toBe(false);
+ });
+
+ it("step 1: fill=1, checkDraw=1, active=false (completed)", () => {
+ const r = stepCircleAt(1, 2);
+ expect(r.fill).toBe(1);
+ expect(r.checkDraw).toBe(1);
+ expect(r.active).toBe(false);
+ });
+
+ it("step 2: fill=0, checkDraw=0, active=true (last step reached)", () => {
+ // floor(2)=2, fill=clamp(2-2)=0 → active=true
+ const r = stepCircleAt(2, 2);
+ expect(r.fill).toBe(0);
+ expect(r.checkDraw).toBe(0);
+ expect(r.active).toBe(true);
+ });
+});
+
+describe("stepCircleAt: fill clamps at 1 for large position", () => {
+ it("step 0 at position=5 clamps fill to 1", () => {
+ const r = stepCircleAt(0, 5);
+ expect(r.fill).toBe(1);
+ expect(r.checkDraw).toBe(1);
+ expect(r.active).toBe(false);
+ });
+});
+
+describe("stepCircleAt: fill clamps at 0 for negative (position - i)", () => {
+ it("step 2 at position=0 clamps fill to 0 (no negative fill)", () => {
+ const r = stepCircleAt(2, 0);
+ expect(r.fill).toBe(0);
+ expect(r.checkDraw).toBe(0);
+ });
+});
+
+describe("stepCircleAt: fill and checkDraw are always equal", () => {
+ for (const [i, pos] of [[0, 0], [0, 0.5], [0, 1], [1, 1.5], [2, 2]] as [number, number][]) {
+ it(`i=${i} pos=${pos}: fill === checkDraw`, () => {
+ const r = stepCircleAt(i, pos);
+ expect(r.fill).toBeCloseTo(r.checkDraw, 10);
+ });
+ }
+});
+
+// ===========================================================================
+// 5. connectorFillAt — connector primary-fill fraction between steps
+// MIRROR of index.tsx lines 126-128.
+// connectorFillAt(i, position) = clamp01(position - i)
+// Same formula as stepCircleAt fill — tests confirm the identity.
+// ===========================================================================
+
+describe("connectorFillAt: connector between step 0 and 1", () => {
+ it("position=0: fill=0 (connector empty)", () => {
+ expect(connectorFillAt(0, 0)).toBe(0);
+ });
+
+ it("position=0.5: fill=0.5 (connector half full)", () => {
+ expect(connectorFillAt(0, 0.5)).toBeCloseTo(0.5, 10);
+ });
+
+ it("position=1: fill=1 (connector fully filled)", () => {
+ expect(connectorFillAt(0, 1)).toBe(1);
+ });
+
+ it("position=2: fill=1 (clamped, already passed)", () => {
+ expect(connectorFillAt(0, 2)).toBe(1);
+ });
+});
+
+describe("connectorFillAt: connector between step 1 and 2", () => {
+ it("position=1: fill=0 (second connector empty)", () => {
+ expect(connectorFillAt(1, 1)).toBe(0);
+ });
+
+ it("position=1.5: fill=0.5", () => {
+ expect(connectorFillAt(1, 1.5)).toBeCloseTo(0.5, 10);
+ });
+
+ it("position=2: fill=1 (second connector full)", () => {
+ expect(connectorFillAt(1, 2)).toBe(1);
+ });
+});
+
+describe("connectorFillAt: negative result is clamped to 0", () => {
+ it("connectorFillAt(2, 0) = 0 (not -2)", () => {
+ expect(connectorFillAt(2, 0)).toBe(0);
+ });
+});
+
+// ===========================================================================
+// 6. tweenStepperStyle — pure single-field lerp
+// MIRROR of use-stepper-transition.ts lines 34-40.
+// position lerps linearly: a.position + (b.position - a.position) * t
+// ===========================================================================
+
+describe("tweenStepperStyle: t=0 returns value equal to a", () => {
+ it("position equals a.position at t=0", () => {
+ const r = tweenStepperStyle({ position: 0 }, { position: 2 }, 0);
+ expect(r.position).toBeCloseTo(0, 10);
+ });
+});
+
+describe("tweenStepperStyle: t=1 returns value equal to b", () => {
+ it("position equals b.position at t=1", () => {
+ const r = tweenStepperStyle({ position: 0 }, { position: 2 }, 1);
+ expect(r.position).toBeCloseTo(2, 10);
+ });
+});
+
+describe("tweenStepperStyle: t=0.5 midpoint (0 → 2)", () => {
+ // 0 + (2-0)*0.5 = 1
+ it("0 → 2 at t=0.5 gives position=1", () => {
+ const r = tweenStepperStyle({ position: 0 }, { position: 2 }, 0.5);
+ expect(r.position).toBeCloseTo(1, 10);
+ });
+});
+
+describe("tweenStepperStyle: t=0.5 midpoint (1 → 0, reverse)", () => {
+ // 1 + (0-1)*0.5 = 0.5
+ it("1 → 0 at t=0.5 gives position=0.5", () => {
+ const r = tweenStepperStyle({ position: 1 }, { position: 0 }, 0.5);
+ expect(r.position).toBeCloseTo(0.5, 10);
+ });
+});
+
+describe("tweenStepperStyle: identity (a === b)", () => {
+ it("position is unchanged when both endpoints are the same", () => {
+ const r = tweenStepperStyle({ position: 1 }, { position: 1 }, 0.5);
+ expect(r.position).toBeCloseTo(1, 10);
+ });
+});
+
+describe("tweenStepperStyle: t=0.25 quarter-point", () => {
+ // 0 + (2-0)*0.25 = 0.5
+ it("0 → 2 at t=0.25 gives position=0.5", () => {
+ const r = tweenStepperStyle({ position: 0 }, { position: 2 }, 0.25);
+ expect(r.position).toBeCloseTo(0.5, 10);
+ });
+});
+
+// ===========================================================================
+// 7. stepperStyleAt — pure exported core of useStepperTransition
+// MIRROR of use-stepper-transition.ts lines 66-102.
+// useStepperTransition = stepperStyleAt(steps, useCurrentFrame() * speed, opts).
+// Call stepperStyleAt directly with frame injected as `raw`.
+//
+// MAINTENANCE CONTRACT: if use-stepper-transition.ts lines 66-102 change,
+// update these tests in lockstep. Annotated source lines below.
+// ===========================================================================
+
+describe("stepperStyleAt: empty steps → position=0", () => {
+ // source line 73: if (steps.length === 0) return { position: 0 }
+ it("returns {position:0} for any raw frame when steps is empty", () => {
+ expect(stepperStyleAt([], 0).position).toBe(0);
+ expect(stepperStyleAt([], 100).position).toBe(0);
+ });
+});
+
+describe("stepperStyleAt: before first step — holds at first.index", () => {
+ // source line 79: if (raw <= first.at) return { position: first.index }
+ const steps: StepperStep[] = [{ at: 30, index: 1 }];
+
+ it("raw=0 < first.at=30 → holds at first.index=1", () => {
+ expect(stepperStyleAt(steps, 0).position).toBe(1);
+ });
+
+ it("raw=30 = first.at=30 → still holds at first.index=1 (raw <= first.at)", () => {
+ expect(stepperStyleAt(steps, 30).position).toBe(1);
+ });
+
+ it("raw=29 → holds at first.index=1", () => {
+ expect(stepperStyleAt(steps, 29).position).toBe(1);
+ });
+});
+
+describe("stepperStyleAt: past last step — rests at last.index", () => {
+ // source lines 90-92: pastLast → to=from=last, t=1
+ const steps: StepperStep[] = [{ at: 0, index: 0 }, { at: 24, index: 1 }];
+
+ it("raw=50 past last.at=24 → position=1 (last index)", () => {
+ expect(stepperStyleAt(steps, 50).position).toBeCloseTo(1, 10);
+ });
+
+ it("raw=100 → position=1", () => {
+ expect(stepperStyleAt(steps, 100).position).toBeCloseTo(1, 10);
+ });
+});
+
+describe("stepperStyleAt: mid-window uses easings.out (non-linear)", () => {
+ // steps=[{at:0,index:0},{at:24,index:1}], raw=12
+ // pastLast: 12>=24? no. toIndex=1 (steps[1].at=24>12)
+ // to={at:24,index:1}, from={at:0,index:0}
+ // dur=24, start=0, t=out(clamp01((12-0)/24))=out(0.5)=0.875
+ // position = 0 + (1-0)*0.875 = 0.875
+ const steps: StepperStep[] = [{ at: 0, index: 0 }, { at: 24, index: 1 }];
+
+ it("raw=12 gives position=0.875 (out-eased, not linear 0.5)", () => {
+ expect(stepperStyleAt(steps, 12).position).toBeCloseTo(0.875, 8);
+ });
+
+ it("out(0.5) = 0.875 — confirms easing is non-linear at midpoint", () => {
+ expect(easings.out(0.5)).toBeCloseTo(0.875, 8);
+ });
+
+ it("value at raw=12 is 0.875, NOT 0.5 (rejects linear hypothesis)", () => {
+ const r = stepperStyleAt(steps, 12);
+ expect(r.position).not.toBeCloseTo(0.5, 1);
+ expect(r.position).toBeCloseTo(0.875, 8);
+ });
+});
+
+describe("stepperStyleAt: at last step boundary — pastLast → t=1", () => {
+ // raw=24: steps[1].at=24, pastLast = raw(24) >= 24 = true → t=1 → position=1
+ const steps: StepperStep[] = [{ at: 0, index: 0 }, { at: 24, index: 1 }];
+
+ it("raw=24 exactly at last step → position=1", () => {
+ expect(stepperStyleAt(steps, 24).position).toBeCloseTo(1, 10);
+ });
+});
+
+describe("stepperStyleAt: two-step multi-segment timeline", () => {
+ // steps=[{at:0,index:0},{at:24,index:1},{at:48,index:2}]
+ // raw=36 (mid of second segment [24→48], dur=24):
+ // toIndex search: steps[2].at=48>36 → toIndex=2
+ // pastLast: 36>=48? no. to={at:48,index:2}, from={at:24,index:1}
+ // dur=24, start=24, t=out((36-24)/24)=out(0.5)=0.875
+ // position = 1 + (2-1)*0.875 = 1.875
+ const steps: StepperStep[] = [
+ { at: 0, index: 0 },
+ { at: 24, index: 1 },
+ { at: 48, index: 2 },
+ ];
+
+ it("raw=36 mid-second segment gives position=1.875", () => {
+ expect(stepperStyleAt(steps, 36).position).toBeCloseTo(1.875, 8);
+ });
+
+ it("raw=24 (start of second segment boundary) → pastLast=false, t=out(0)=0 → position=1", () => {
+ // steps[2].at=48>24 → toIndex=2; start=48-24=24; t=out((24-24)/24)=out(0)=0
+ // position = 1 + (2-1)*0 = 1
+ expect(stepperStyleAt(steps, 24).position).toBeCloseTo(1, 10);
+ });
+});
+
+describe("stepperStyleAt: custom duration on a step", () => {
+ // steps=[{at:0,index:0},{at:12,index:1,duration:12}]
+ // raw=6: toIndex=1, dur=12, start=0, t=out(6/12)=out(0.5)=0.875
+ // position=0+(1-0)*0.875=0.875
+ const steps: StepperStep[] = [{ at: 0, index: 0 }, { at: 12, index: 1, duration: 12 }];
+
+ it("custom duration=12: raw=6 gives position=0.875", () => {
+ expect(stepperStyleAt(steps, 6).position).toBeCloseTo(0.875, 8);
+ });
+});
+
+describe("stepperStyleAt: past last with three steps", () => {
+ const steps: StepperStep[] = [
+ { at: 0, index: 0 },
+ { at: 24, index: 1 },
+ { at: 48, index: 2 },
+ ];
+
+ it("raw=100 past last → position=2 (last step index)", () => {
+ expect(stepperStyleAt(steps, 100).position).toBeCloseTo(2, 10);
+ });
+});
+
+describe("stepperStyleAt: single-step timeline (no from step)", () => {
+ // Only one step: hold at its index before and after
+ const steps: StepperStep[] = [{ at: 0, index: 1 }];
+
+ it("raw=0 (at first.at) → holds at position=1", () => {
+ expect(stepperStyleAt(steps, 0).position).toBe(1);
+ });
+
+ it("raw=50 past last → pastLast=true → position=1", () => {
+ expect(stepperStyleAt(steps, 50).position).toBeCloseTo(1, 10);
+ });
+});
+
+// ===========================================================================
+// 8. stepperConfig.controls — customizer control wiring
+// ===========================================================================
+
+describe("stepperConfig.controls.activeIndex", () => {
+ it("is a number control", () => {
+ expect(stepperConfig.controls.activeIndex.type).toBe("number");
+ });
+
+ it("defaults to 1 (middle step of the 3-step default)", () => {
+ expect(stepperConfig.controls.activeIndex.default).toBe(1);
+ });
+
+ it("min is 0", () => {
+ const ctrl = stepperConfig.controls.activeIndex;
+ if (ctrl.type !== "number") throw new Error("expected number");
+ expect(ctrl.min).toBe(0);
+ });
+
+ it("max is 2", () => {
+ const ctrl = stepperConfig.controls.activeIndex;
+ if (ctrl.type !== "number") throw new Error("expected number");
+ expect(ctrl.max).toBe(2);
+ });
+
+ it("step is 1 (integer steps only)", () => {
+ const ctrl = stepperConfig.controls.activeIndex;
+ if (ctrl.type !== "number") throw new Error("expected number");
+ expect(ctrl.step).toBe(1);
+ });
+});
+
+describe("stepperConfig.controls.mode", () => {
+ it("is a select control", () => {
+ expect(stepperConfig.controls.mode.type).toBe("select");
+ });
+
+ it("options are ['light', 'dark']", () => {
+ const ctrl = stepperConfig.controls.mode;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["light", "dark"]);
+ });
+
+ it("defaults to 'light'", () => {
+ expect(stepperConfig.controls.mode.default).toBe("light");
+ });
+});
+
+// ===========================================================================
+// 9. stepperConfig.snippet — pure JSX string builder
+// ===========================================================================
+
+describe("stepperConfig.snippet: import line", () => {
+ it("includes 'import { Stepper }' from the correct path", () => {
+ const out = snippet({ activeIndex: 1 });
+ expect(out).toContain("import { Stepper }");
+ expect(out).toContain('from "@/components/remocn/stepper"');
+ });
+});
+
+describe("stepperConfig.snippet: structural invariants", () => {
+ it("contains a <Stepper JSX element", () => {
+ expect(snippet({ activeIndex: 1 })).toContain("<Stepper");
+ });
+
+ it("ends with a self-closing />", () => {
+ expect(snippet({ activeIndex: 1 }).trimEnd().endsWith("/>")).toBe(true);
+ });
+
+ it("starts with the import line", () => {
+ expect(snippet({ activeIndex: 1 }).startsWith('import { Stepper }')).toBe(true);
+ });
+});
+
+describe("stepperConfig.snippet: activeIndex is always emitted", () => {
+ it("emits activeIndex={1} for the default value", () => {
+ expect(snippet({ activeIndex: 1 })).toContain("activeIndex={1}");
+ });
+
+ it("emits activeIndex={0} when activeIndex is 0", () => {
+ expect(snippet({ activeIndex: 0 })).toContain("activeIndex={0}");
+ });
+
+ it("emits activeIndex={2} when activeIndex is 2", () => {
+ expect(snippet({ activeIndex: 2 })).toContain("activeIndex={2}");
+ });
+
+ it("emits activeIndex={0} when activeIndex is omitted from values (falls back to 0)", () => {
+ // snippet uses `activeIndex ?? 0`
+ expect(snippet({})).toContain("activeIndex={0}");
+ });
+});
+
+describe("stepperConfig.snippet: steps inline literal always emitted", () => {
+ it("always emits steps={[...]} inline", () => {
+ const out = snippet({ activeIndex: 1 });
+ expect(out).toContain("steps={");
+ expect(out).toContain("Account");
+ expect(out).toContain("Plan");
+ expect(out).toContain("Done");
+ });
+
+ it("emits steps for every activeIndex value", () => {
+ for (const i of [0, 1, 2]) {
+ const out = snippet({ activeIndex: i });
+ expect(out).toContain("steps={");
+ }
+ });
+});
+
+describe("stepperConfig.snippet: default mode is omitted", () => {
+ it("omits mode when it equals the default 'light'", () => {
+ expect(snippet({ activeIndex: 1, mode: "light" })).not.toContain("mode=");
+ });
+
+ it("omits mode when not provided", () => {
+ expect(snippet({ activeIndex: 1 })).not.toContain("mode=");
+ });
+});
+
+describe("stepperConfig.snippet: non-default mode is emitted", () => {
+ it("emits mode=\"dark\" when non-default", () => {
+ expect(snippet({ activeIndex: 1, mode: "dark" })).toContain('mode="dark"');
+ });
+});
+
+describe("stepperConfig.snippet: activeIndex numeric round-trip", () => {
+ it("emits the correct activeIndex for 0, 1, 2", () => {
+ for (const i of [0, 1, 2]) {
+ expect(snippet({ activeIndex: i })).toContain(`activeIndex={${i}}`);
+ }
+ });
+});
diff --git a/registry/remocn-ui/stepper/config.ts b/registry/remocn-ui/stepper/config.ts
new file mode 100644
index 00000000..4afaa210
--- /dev/null
+++ b/registry/remocn-ui/stepper/config.ts
@@ -0,0 +1,43 @@
+import { type ComponentConfig, FPS, H, W } from "@/lib/customizer-config";
+
+const DEFAULT_STEPS = ["Account", "Plan", "Done"];
+
+export const stepperConfig: ComponentConfig = {
+ componentName: "Stepper",
+ importPath: "@/components/remocn/stepper",
+ controls: {
+ activeIndex: {
+ type: "number",
+ default: 1,
+ min: 0,
+ max: 2,
+ step: 1,
+ label: "Active Index",
+ },
+ mode: {
+ type: "select",
+ default: "light",
+ options: ["light", "dark"],
+ label: "Mode",
+ },
+ },
+ durationInFrames: 120,
+ fps: FPS,
+ compositionWidth: W,
+ compositionHeight: H,
+ snippet: (values) => {
+ const activeIndex = values.activeIndex as number | undefined;
+ const mode = values.mode as string | undefined;
+
+ const props: string[] = [` activeIndex={${activeIndex ?? 0}}`];
+ if (mode !== undefined && mode !== "light") props.push(` mode="${mode}"`);
+
+ const stepsLiteral = JSON.stringify(DEFAULT_STEPS);
+ return `import { Stepper } from "@/components/remocn/stepper";
+
+<Stepper
+ steps={${stepsLiteral}}
+${props.join("\n")}
+/>`;
+ },
+};
diff --git a/registry/remocn-ui/stepper/index.tsx b/registry/remocn-ui/stepper/index.tsx
new file mode 100644
index 00000000..29f9c964
--- /dev/null
+++ b/registry/remocn-ui/stepper/index.tsx
@@ -0,0 +1,266 @@
+"use client";
+
+import { clamp01, mixOklch, type RemocnTheme, useRemocnTheme } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Stepper visual — the COMPLETE animated look for a moment in time. The animated
+// channel is a single CONTINUOUS float `position` (the value-channel deviation
+// §0, like progress): every circle's fill/color/check and every connector's
+// primary fill derive PURELY from `position` in the render. `useStepperTransition`
+// feeds an interpolated `StepperStyle` through `style`; the component never reads
+// the frame.
+// ===========================================================================
+
+export interface StepperStyle {
+ /**
+ * Continuous active-step index (0..n-1, float). The ONLY animated field — each
+ * circle and connector is a pure function of it, so a lerp advances the stepper
+ * smoothly (checks draw, connectors fill) without jumps.
+ */
+ position: number;
+}
+
+export type StepperOrientation = "horizontal" | "vertical";
+
+export interface StepperProps {
+ /** Step labels. Their count is the step count. */
+ steps?: string[];
+ /**
+ * Active step index (snap path). Ignored when `style` is supplied. May be a
+ * float, but is typically an integer for the snap form.
+ */
+ activeIndex?: number;
+ /**
+ * Resolved animated visual (smooth path). When provided, takes precedence over
+ * `activeIndex` — feed it an interpolated `StepperStyle` from `useStepperTransition`.
+ */
+ style?: StepperStyle;
+ /**
+ * Layout. Only `"horizontal"` is implemented this wave; `"vertical"` is
+ * accepted but falls back to horizontal.
+ */
+ orientation?: StepperOrientation;
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ className?: string;
+}
+
+/** Default onboarding steps. */
+const DEFAULT_STEPS = ["Account", "Plan", "Done"];
+
+/** Circle diameter (px). */
+const CIRCLE = 36;
+/** Checkmark stroke length (svg path units), drives the draw-on animation. */
+const CHECK_PATH_LENGTH = 14;
+
+/** Concrete colors for the active theme, resolved once per render. */
+export interface StepperStyleContext {
+ /** Completed/active accent (circles, connector fill, ring). */
+ primary: string;
+ /** Check color on a completed circle. */
+ primaryFg: string;
+ /** Future circle fill. */
+ mutedBg: string;
+ /** Future circle border + empty connector. */
+ border: string;
+ /** Future step number color. */
+ mutedFg: string;
+ /** Active/completed number + label color. */
+ foreground: string;
+}
+
+/**
+ * Derive the concrete colors for a theme. Pure — call it once and reuse the
+ * result across every step's derivation.
+ */
+export function stepperStyleContext(theme: RemocnTheme): StepperStyleContext {
+ return {
+ primary: theme.primary,
+ primaryFg: theme.primaryForeground,
+ mutedBg: theme.muted,
+ border: theme.border,
+ mutedFg: theme.mutedForeground,
+ foreground: theme.foreground,
+ };
+}
+
+/**
+ * The COMPLETE resting visual for an active index — a pure `(activeIndex) =>
+ * StepperStyle` map. `position` IS the index (the smooth path feeds a float).
+ */
+export function stepperStyle(activeIndex: number): StepperStyle {
+ return { position: activeIndex };
+}
+
+/**
+ * The derived per-step visual at a given `position`. PURE — exported so tests can
+ * assert the completed/active/future thresholds and the check draw without a
+ * render.
+ *
+ * - completed: i + 1 <= position (fully reached the NEXT step) → filled primary
+ * circle + drawn check (checkDraw 0→1 as position crosses i→i+1).
+ * - active: the step `position` is currently sitting on/approaching.
+ * - future: i not yet reached.
+ *
+ * `fill` 0→1 is how "done" step i is: clamp01(position - i). At fill>=1 the step
+ * is completed (check drawn); below 1 it's the active/in-progress step.
+ */
+export function stepCircleAt(i: number, position: number): {
+ /** 0→1 completion of this step. */
+ fill: number;
+ /** Checkmark draw fraction 0→1 (only meaningful once fill reaches 1). */
+ checkDraw: number;
+ /** True when the step is the current/active one (the integer position sits here). */
+ active: boolean;
+} {
+ const fill = clamp01(position - i);
+ // The check draws as the step crosses from active (fill→1) into completed.
+ const checkDraw = fill;
+ // Active = the step the position currently rests on (its own integer slot),
+ // before it has fully completed into the next.
+ const active = Math.floor(position) === i && fill < 1;
+ return { fill, checkDraw, active };
+}
+
+/** Connector primary-fill fraction between step i and i+1. PURE; exported. */
+export function connectorFillAt(i: number, position: number): number {
+ return clamp01(position - i);
+}
+
+export function Stepper({
+ steps = DEFAULT_STEPS,
+ activeIndex = 0,
+ style,
+ orientation: _orientation = "horizontal",
+ theme: themeOverride,
+ mode,
+ className,
+}: StepperProps) {
+ const theme = useRemocnTheme(themeOverride, mode);
+ const ctx = stepperStyleContext(theme);
+ const v = style ?? stepperStyle(activeIndex);
+ const position = v.position;
+
+ return (
+ <div
+ className={className}
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ background: theme.background,
+ fontFamily:
+ "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif",
+ }}
+ >
+ <div style={{ display: "flex", alignItems: "flex-start" }}>
+ {steps.map((label, i) => {
+ const { fill, checkDraw, active } = stepCircleAt(i, position);
+ const completed = fill >= 1;
+ // Circle background interpolates muted → primary as the step fills.
+ const circleBg = mixOklch(ctx.mutedBg, ctx.primary, fill);
+ const circleBorder = mixOklch(ctx.border, ctx.primary, fill);
+ // Number fades out as the check fades in (completed shows the check).
+ const numberOpacity = 1 - checkDraw;
+ const numberColor = active || completed ? ctx.foreground : ctx.mutedFg;
+ const isLast = i === steps.length - 1;
+ return (
+ <div
+ key={label}
+ style={{ display: "flex", alignItems: "flex-start" }}
+ >
+ {/* Step circle + label below it. */}
+ <div
+ style={{
+ display: "flex",
+ flexDirection: "column",
+ alignItems: "center",
+ gap: 8,
+ width: CIRCLE + 24,
+ }}
+ >
+ <div
+ style={{
+ position: "relative",
+ width: CIRCLE,
+ height: CIRCLE,
+ borderRadius: "50%",
+ background: circleBg,
+ border: `2px solid ${active ? ctx.primary : circleBorder}`,
+ boxSizing: "border-box",
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ }}
+ >
+ {/* Step number — fades out as the check draws in. */}
+ <span
+ style={{
+ position: "absolute",
+ fontSize: 14,
+ fontWeight: 600,
+ color: numberColor,
+ opacity: numberOpacity,
+ }}
+ >
+ {i + 1}
+ </span>
+ {/* Checkmark — stroke-dash draw (checkbox technique). */}
+ <svg width={CIRCLE} height={CIRCLE} viewBox="0 0 24 24" fill="none">
+ <path
+ d="M5 12.5l4.5 4.5L19 7"
+ stroke={ctx.primaryFg}
+ strokeWidth="2.6"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ pathLength={CHECK_PATH_LENGTH}
+ strokeDasharray={CHECK_PATH_LENGTH}
+ strokeDashoffset={CHECK_PATH_LENGTH * (1 - checkDraw)}
+ />
+ </svg>
+ </div>
+ <span
+ style={{
+ fontSize: 13,
+ fontWeight: 500,
+ letterSpacing: "-0.01em",
+ color: active || completed ? ctx.foreground : ctx.mutedFg,
+ whiteSpace: "nowrap",
+ }}
+ >
+ {label}
+ </span>
+ </div>
+ {/* Connector to the next step — a muted rail with a primary fill. */}
+ {!isLast && (
+ <div
+ style={{
+ position: "relative",
+ width: 64,
+ height: 2,
+ marginTop: CIRCLE / 2 - 1,
+ background: ctx.border,
+ overflow: "hidden",
+ }}
+ >
+ <div
+ style={{
+ position: "absolute",
+ left: 0,
+ top: 0,
+ bottom: 0,
+ width: `${connectorFillAt(i, position) * 100}%`,
+ background: ctx.primary,
+ }}
+ />
+ </div>
+ )}
+ </div>
+ );
+ })}
+ </div>
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/stepper/preview.tsx b/registry/remocn-ui/stepper/preview.tsx
new file mode 100644
index 00000000..3c336416
--- /dev/null
+++ b/registry/remocn-ui/stepper/preview.tsx
@@ -0,0 +1,38 @@
+"use client";
+
+import { useRemocnTheme } from "@/lib/remocn-ui";
+import { Stepper } from "@/registry/remocn-ui/stepper";
+
+export interface StepperPreviewProps {
+ activeIndex?: number;
+ mode?: "light" | "dark";
+}
+
+/** Fixed demo steps for the customizer preview. */
+const DEMO_STEPS = ["Account", "Plan", "Done"];
+
+/**
+ * Preview-only wrapper for the customizer. The shipped `Stepper` is a wide,
+ * placement-agnostic horizontal element; the customizer Player renders its
+ * `component` as the composition root, so this thin wrapper centers it on a
+ * theme-background stage and supplies a fixed demo `steps` set. NOT shipped: not
+ * listed in registry.json files.
+ */
+export function StepperPreview({ activeIndex = 1, mode }: StepperPreviewProps) {
+ const theme = useRemocnTheme(undefined, mode);
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ background: theme.background,
+ }}
+ >
+ <Stepper steps={DEMO_STEPS} activeIndex={activeIndex} mode={mode} />
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/stepper/use-stepper-transition.ts b/registry/remocn-ui/stepper/use-stepper-transition.ts
new file mode 100644
index 00000000..d13f4509
--- /dev/null
+++ b/registry/remocn-ui/stepper/use-stepper-transition.ts
@@ -0,0 +1,102 @@
+"use client";
+
+import { useCurrentFrame } from "remotion";
+import { clamp01, type EasingName, easings } from "@/lib/remocn-ui";
+import type { StepperStyle } from "@/components/remocn/stepper";
+// ^ install path; resolves in-repo via the @/components/remocn/* tsconfig alias.
+
+/**
+ * A scripted active-step the stepper eases TO. The `position` tweens from the
+ * previous step's index to this one over `[at, at + (duration ?? DEFAULT_DURATION))`.
+ */
+export interface StepperStep {
+ /** LOCAL (Sequence-relative) authored frame the stepper finishes reaching `index`. */
+ at: number;
+ /** Target active-step index (0..n-1). */
+ index: number;
+ /** Frames the move INTO this index takes. Omitted → DEFAULT_DURATION. */
+ duration?: number;
+ /** Override the easing for the move into this index. Default `out`. */
+ easing?: EasingName;
+}
+
+/** Default frames for a move into a step when it omits `duration`. */
+export const DEFAULT_DURATION = 24;
+
+export interface StepperTransitionOptions {
+ /** Playhead scale (effectiveFrame = useCurrentFrame() * speed). */
+ speed?: number;
+ /** Move duration (frames) when a step omits `duration`. */
+ defaultDuration?: number;
+}
+
+/** Blend two stepper visuals: the single `position` field lerps. */
+export function tweenStepperStyle(
+ a: StepperStyle,
+ b: StepperStyle,
+ t: number,
+): StepperStyle {
+ return { position: a.position + (b.position - a.position) * t };
+}
+
+/**
+ * Resolve the stepper's `StepperStyle` for an index timeline. THIS is the only
+ * frame-reading file — `<Stepper>` itself stays pure. Mirrors the value-channel
+ * deviation (like progress's `useProgressTransition`): it folds a numeric index
+ * path into a continuous `position`.
+ *
+ * The fold is a pure function of `raw = useCurrentFrame() * speed`; tests
+ * replicate `stepperStyleAt(steps, raw, opts)` with the frame injected.
+ */
+export function useStepperTransition(
+ steps: StepperStep[],
+ opts: StepperTransitionOptions = {},
+): StepperStyle {
+ const { speed = 1 } = opts;
+ const raw = useCurrentFrame() * speed;
+ return stepperStyleAt(steps, raw, opts);
+}
+
+/**
+ * Pure core of `useStepperTransition` with the effective frame injected as `raw`.
+ * Kept separate so it can be unit-tested without a Remotion render.
+ * `useStepperTransition` is exactly `stepperStyleAt(steps, useCurrentFrame() *
+ * speed, opts)`.
+ */
+export function stepperStyleAt(
+ steps: StepperStep[],
+ raw: number,
+ opts: StepperTransitionOptions = {},
+): StepperStyle {
+ const { defaultDuration = DEFAULT_DURATION } = opts;
+
+ if (steps.length === 0) return { position: 0 };
+
+ // Authored order is the timeline order; `at` is the arrival frame of each step.
+ const first = steps[0];
+
+ // Before the first arrival, hold at the first step's index (no teleport).
+ if (raw <= first.at) return { position: first.index };
+
+ // Find the segment we're in: the move from step i-1 into step i, where i is
+ // the first step with at > raw. If none, we're resting at the last step.
+ let toIndex = steps.length - 1;
+ for (let i = 1; i < steps.length; i++) {
+ if (steps[i].at > raw) {
+ toIndex = i;
+ break;
+ }
+ }
+ const pastLast = raw >= steps[steps.length - 1].at;
+ const to = pastLast ? steps[steps.length - 1] : steps[toIndex];
+ const from = pastLast ? steps[steps.length - 1] : steps[toIndex - 1];
+
+ const dur = to.duration ?? defaultDuration;
+ const ease = easings[to.easing ?? "out"];
+ // The move runs over [start, to.at); start = to.at - dur.
+ const start = to.at - dur;
+ const t = pastLast || dur <= 0 ? 1 : ease(clamp01((raw - start) / dur));
+ const position = from.index + (to.index - from.index) * t;
+
+ return { position };
+}