Skip to content

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

feat: added progress component

dev_wandrycb07d9770a99
diff --git a/components/docs/examples/index.tsx b/components/docs/examples/index.tsx
index b5871b74..1319213c 100644
--- a/components/docs/examples/index.tsx
+++ b/components/docs/examples/index.tsx
@@ -32,6 +32,10 @@ import {
commandMenuExampleCode,
} from "./command-menu-example";
import { TooltipExampleScene, tooltipExampleCode } from "./tooltip-example";
+import {
+ ProgressExampleScene,
+ progressExampleCode,
+} from "./progress-example";
export interface ExampleEntry {
Component: ComponentType;
@@ -191,4 +195,13 @@ export const examples: Record<string, ExampleEntry> = {
width: W,
height: H,
},
+ "progress-example": {
+ Component: ProgressExampleScene,
+ code: progressExampleCode,
+ // Fill completes at 130 + dur 30 = 160; a short settle then loop.
+ durationInFrames: 160,
+ fps: FPS,
+ width: W,
+ height: H,
+ },
};
diff --git a/components/docs/examples/progress-example.tsx b/components/docs/examples/progress-example.tsx
new file mode 100644
index 00000000..9deee2a5
--- /dev/null
+++ b/components/docs/examples/progress-example.tsx
@@ -0,0 +1,55 @@
+"use client";
+
+import { Progress } from "@/registry/remocn-ui/progress";
+import { useProgressTransition } from "@/registry/remocn-ui/progress/use-progress-transition";
+
+export const ProgressExampleScene = () => {
+ // Bar fills from 0 → 62 (arrives at frame 40), stalls for ~60 frames as if
+ // waiting on a slow operation, then resumes to 100 (arrives at frame 130).
+ const progressStyle = useProgressTransition([
+ { at: 0, value: 0 },
+ { at: 40, value: 62, duration: 36 },
+ { at: 130, value: 100, duration: 30 },
+ ]);
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ }}
+ >
+ <Progress style={progressStyle} showLabel width={320} />
+ </div>
+ );
+};
+
+export const progressExampleCode = `import { Progress } from "@/components/remocn/progress";
+import { useProgressTransition } from "@/components/remocn/use-progress-transition";
+
+export const Scene = () => {
+ // Bar fills from 0 → 62 (arrives at frame 40), stalls for ~60 frames as if
+ // waiting on a slow operation, then resumes to 100 (arrives at frame 130).
+ const progressStyle = useProgressTransition([
+ { at: 0, value: 0 },
+ { at: 40, value: 62, duration: 36 },
+ { at: 130, value: 100, duration: 30 },
+ ]);
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ }}
+ >
+ <Progress style={progressStyle} showLabel width={320} />
+ </div>
+ );
+};`;
diff --git a/components/docs/examples/tooltip-example.tsx b/components/docs/examples/tooltip-example.tsx
index c54cd943..5adac5b4 100644
--- a/components/docs/examples/tooltip-example.tsx
+++ b/components/docs/examples/tooltip-example.tsx
@@ -120,7 +120,7 @@ export const Scene = () => {
<div
style={{
position: "absolute",
- bottom: "calc(100% + 24px)",
+ bottom: "calc(100% + 32px)",
left: "50%",
transform: "translateX(-50%)",
}}
diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.json
index 24550d4f..db11275b 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", "command-menu", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "radio", "select", "spinner", "switch", "tabs", "toast", "tooltip"]
+ "pages": ["accordion", "alert-dialog", "button", "checkbox", "command-menu", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "progress", "radio", "select", "spinner", "switch", "tabs", "toast", "tooltip"]
}
diff --git a/content/docs/ui/components/progress.mdx b/content/docs/ui/components/progress.mdx
new file mode 100644
index 00000000..6ceac5cc
--- /dev/null
+++ b/content/docs/ui/components/progress.mdx
@@ -0,0 +1,136 @@
+---
+title: Progress
+description: A progress bar that fills along a scripted numeric value timeline
+---
+
+<ComponentPreview name="progress" />
+
+A value-channel atom whose fill (`0`–`100`) is a pure function of the `value` prop or an interpolated `ProgressStyle` from `useProgressTransition`. The component reads no frame — only the value you give it. This is the **value-channel** variant of the primitive pattern: instead of a string-state timeline it drives a numeric fill channel directly, the same deviation used by the Cursor primitive.
+
+## Installation
+
+<InstallBlock name="progress" />
+
+<Note>
+Installing `progress` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) via `registryDependencies` (`["remocn-ui"]`). You do not need to install it separately. Both `progress` (the renderer) and `use-progress-transition` (the hook) are copied into your project.
+</Note>
+
+## Example
+
+<LiveExample name="progress-example" />
+
+## Value steps
+
+Instead of a string-state timeline, `useProgressTransition` takes an array of `ProgressStep` objects that describe a scripted fill path:
+
+```ts
+interface ProgressStep {
+ at: number; // LOCAL (Sequence-relative) authored frame the bar finishes reaching `value`
+ value: number; // Target fill percentage 0–100
+ duration?: number; // Frames the move INTO this value takes. Omitted → DEFAULT_DURATION (24)
+ easing?: EasingName; // Override easing for the move into this value. Default "out"
+}
+```
+
+`at` is the **arrival frame** — the frame when the bar finishes its fill. The move itself runs over `[at - duration, at)`. Before the first arrival, the bar holds at the first step's value.
+
+### Numeric-channel deviation
+
+`Progress` differs from state atoms (Button, Toast, etc.) in one key way: there is no string `state` union and no `useCurrentState` snap path. The bar's visual is always numeric — a fill percentage — so `useProgressTransition` folds the value path directly into a `ProgressStyle`. The snap equivalent is simply passing a fixed `value` prop.
+
+To model a pause or stall, add two steps at the same value with a gap between their `at` frames. The bar reaches the stall value and holds until the next step fires:
+
+```ts
+useProgressTransition([
+ { at: 0, value: 0 },
+ { at: 40, value: 62, duration: 36 }, // fills to 62, arrives frame 40
+ { at: 130, value: 100, duration: 30 }, // resumes after ~60-frame stall
+]);
+```
+
+## Snap usage
+
+Pass `value` directly — the component snaps instantly to that fill. Useful for static previews or when you drive value from your own logic:
+
+```tsx
+import { Progress } from "@/components/remocn/progress";
+
+export const Scene = () => (
+ <div style={{ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center" }}>
+ <Progress value={62} showLabel width={320} />
+ </div>
+);
+```
+
+## Smooth transitions
+
+Fill changes via `value` snap with no tween. For an animated fill, use `useProgressTransition` from the copied `use-progress-transition.ts` file. It reads the frame, interpolates between value steps, and returns a resolved `ProgressStyle` — pass it to the `style` prop:
+
+```tsx
+import { Progress } from "@/components/remocn/progress";
+import { useProgressTransition } from "@/components/remocn/use-progress-transition";
+
+export const Scene = () => {
+ const style = useProgressTransition([
+ { at: 0, value: 0 },
+ { at: 40, value: 62, duration: 36 },
+ { at: 130, value: 100, duration: 30 },
+ ]);
+
+ return (
+ <div style={{ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center" }}>
+ <Progress style={style} showLabel width={320} />
+ </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 bar decelerates as it nears the target value. To globally tune timing and easing, edit `use-progress-transition.ts` directly in your project — that file is yours (shadcn "own your code" philosophy).
+
+`style` takes precedence over `value` when both are provided.
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "value",
+ type: "number",
+ default: "0",
+ description: "Fill percentage 0–100 (snap path). Clamped to [0, 100]. Ignored when style is provided.",
+ },
+ {
+ name: "style",
+ type: "ProgressStyle",
+ description: "Resolved animated visual (smooth path). Pass an interpolated ProgressStyle from useProgressTransition. Takes precedence over value when provided.",
+ },
+ {
+ name: "width",
+ type: "number",
+ default: "320",
+ description: "Track width in px.",
+ },
+ {
+ name: "showLabel",
+ type: "boolean",
+ default: "false",
+ description: "When true, renders the floored fill percentage to the right of the track in tabular-nums.",
+ },
+ {
+ 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 982ecef3..f729e29c 100644
--- a/registry/__index__.tsx
+++ b/registry/__index__.tsx
@@ -147,6 +147,8 @@ import { CommandMenu } from "@/registry/remocn-ui/command-menu";
import { commandMenuConfig } from "@/registry/remocn-ui/command-menu/config";
import { TooltipPreview } from "@/registry/remocn-ui/tooltip/preview";
import { tooltipConfig } from "@/registry/remocn-ui/tooltip/config";
+import { ProgressPreview } from "@/registry/remocn-ui/progress/preview";
+import { progressConfig } from "@/registry/remocn-ui/progress/config";
import { ZoomThroughTransition } from "@/registry/remocn/zoom-through-transition";
import { zoomThroughTransitionConfig } from "@/registry/remocn/zoom-through-transition/config";
@@ -355,6 +357,9 @@ const registry: Record<string, RegistryEntry> = {
// tooltip's customizer Component is the preview-only TooltipPreview wrapper: a
// bare bubble has no backdrop and would not center as the composition root.
"tooltip": { Component: TooltipPreview, config: tooltipConfig },
+ // progress's customizer Component is the preview-only ProgressPreview wrapper:
+ // a bare inline bar would sit top-left, so the wrapper centers it on a stage.
+ "progress": { Component: ProgressPreview, config: progressConfig },
"spinner": { Component: Spinner, config: spinnerConfig },
};
diff --git a/registry/remocn-ui/progress/__tests__/README.md b/registry/remocn-ui/progress/__tests__/README.md
new file mode 100644
index 00000000..e336d059
--- /dev/null
+++ b/registry/remocn-ui/progress/__tests__/README.md
@@ -0,0 +1,153 @@
+# `progress` — verification tests
+
+Pure / deterministic verification for the `progress` component
+(`registry/remocn-ui/progress/`). The render path (`index.tsx`) imports
+`useRemocnTheme` which requires React context and cannot run headlessly — it
+is NOT exercised here. This suite covers everything that IS pure:
+`clampValue` semantics, `showLabel` floor rounding, `tweenProgressStyle`
+interpolation, the `progressValueAt` pure core (directly exported), and
+`progressConfig` controls wiring + snippet codegen.
+
+## Animation model — value-channel deviation
+
+Progress follows the **value-channel deviation** from the standard state-atom
+pattern (STYLE-GUIDE §0), like `cursor`:
+
+**Snap path** (`value?: number` prop):
+`<Progress>` is a frame-free pure renderer. The `value` prop (0–100, clamped)
+drives the fill width. Changes snap — no tweening inside the component.
+
+**Smooth path** (`style?: ProgressStyle` prop):
+Callers opt in to smooth fills by passing a pre-interpolated `ProgressStyle`
+(which has a single `value` field) to the `style` prop. The caller —
+typically `useProgressTransition` — reads `useCurrentFrame()` and delegates
+to the exported pure function `progressValueAt(steps, raw, opts)`.
+
+**Key deviation from state atoms:** instead of a string-state timeline, the
+hook folds a numeric value path (`ProgressStep[]`). Each step declares an
+arrival frame (`at`) and a target fill percentage (`value`). Between steps,
+the bar eases from the previous step's value to the current one using
+`easings.out` by default (or a per-step override via the `easing` field).
+
+**`progressValueAt` is directly exported** — unlike the `useToastTransition`
+or `useTooltipTransition` hooks, whose pure bodies had to be replicated, the
+progress hook exposes its pure core as a named export. The tests call it
+directly with `raw` injected.
+
+**No color tween:** `ProgressStyle` has a single field (`value: number`), so
+`tweenProgressStyle` is a trivial single-field lerp with no `mixOklch` call.
+
+## Segment fold logic
+
+`progressValueAt` folds the timeline into a segment:
+
+| Condition | Behaviour |
+|-----------|-----------|
+| `steps` is empty | returns `{ value: 0 }` |
+| `raw <= first.at` | holds at `first.value` (no teleport) |
+| `raw >= last.at` | rests at `last.value` (`t=1`, pastLast) |
+| in a segment `[from, to)` | `t = ease(clamp01((raw - start) / dur))` where `start = to.at - dur` |
+
+The default easing is `easings.out` (cubic ease-out: `1 - (1-t)³`), making
+mid-window values non-linear (e.g. linear progress 0.5 → `out(0.5) = 0.875`).
+
+## How to run
+
+The repo uses **Bun**, which has a built-in test runner — runs TypeScript
+natively, no test-framework dep.
+
+```bash
+bun install
+bun test registry/remocn-ui/progress/__tests__
+```
+
+`progress.test.ts` imports `bun:test` (not `vitest`/`jest`), so no test
+script or framework dep is added to `package.json`.
+
+## What is covered
+
+- **`DEFAULT_DURATION`** — asserts the constant is 24 frames.
+
+- **`clampValue` semantics** — mirrored from `index.tsx` lines 43-45
+ (`clamp01(value/100)*100`). Asserts: below-range values clamp to 0 (e.g.
+ -10→0, -0.001→0); above-range values clamp to 100 (e.g. 110→100,
+ 100.001→100); in-range values pass through unchanged (0, 50, 62, 99.9, 100).
+
+- **`showLabel` floor** — the label renders `Math.floor(v)%` (index.tsx line
+ 113). Asserts: 62.7→62, 99.9→99 (does NOT round up), 0→0, 100→100, 87.5→87.
+
+- **`tweenProgressStyle`** — exported pure `(a, b, t) => ProgressStyle`.
+ Single-field lerp (`value` only, no color channels). Asserts: t=0 equals a,
+ t=1 equals b, t=0.5 midpoints (0→100 gives 50, 25→75 gives 50), t=0.25
+ (0→100 gives 25), identity case (a===b preserves value), decreasing direction
+ (100→0 at t=0.5 gives 50).
+
+- **`progressValueAt`** — exported pure core of `useProgressTransition`.
+ `useProgressTransition` is exactly `progressValueAt(steps, useCurrentFrame() *
+ speed, opts)`. Asserts:
+ - Empty steps → `{value:0}` for any frame.
+ - Before first step (raw ≤ first.at) → holds at `first.value`.
+ - Past last step (raw ≥ last.at) → rests at `last.value`.
+ - Mid-window easing: `[{at:0,v:0},{at:24,v:100}]` at raw=12 → linear=0.5,
+ `out(0.5)=0.875` → `value=87.5` (not linear 50).
+ - Easing confirmed non-linear: value ≠ 50 at the linear midpoint.
+ - Step boundary at last step (raw=last.at → pastLast=true → t=1 → value=last).
+ - Two-step timeline mid-second segment: `raw=36` in `[24→48]` gives 93.75.
+ - Custom `duration` on a step overrides `DEFAULT_DURATION`.
+ - Past last with multiple steps → rests at the final step's value.
+
+- **`progressConfig.controls`** — control wiring: `value` is a `number`
+ control with default=62, min=0, max=100; `width` is a `number` control with
+ default=320, min=120, max=640; `showLabel` is a `boolean` control with
+ default=true; `mode` is a `select` with options `["light","dark"]` and
+ default `"light"`.
+
+- **`progressConfig.snippet`** — pure JSX string builder. Asserts: `import {
+ Progress }` from the correct path; `<Progress` element and closing `/>`;
+ `value` is always emitted (including 0 and when omitted from values);
+ default `width=320` and `mode="light"` are omitted; `showLabel` is omitted
+ when false/undefined; non-default width, mode, and showLabel (as a boolean
+ shorthand attribute, not `showLabel={true}`) are emitted; value numeric
+ round-trip for 0/25/50/75/100.
+
+**Progress render** is a pure `(value | style) => visual` observable only via
+Remotion render; it is not unit-tested here.
+
+## Import strategy
+
+`progress.test.ts` imports via **relative paths** and the `@/lib/remocn-ui`
+alias:
+
+- `../use-progress-transition` — relative, for `tweenProgressStyle`,
+ `progressValueAt`, `DEFAULT_DURATION`, `ProgressStep`
+- `../config` — relative, for `progressConfig`
+- `@/lib/remocn-ui` — alias, for `easings`, `clamp01`
+
+`useProgressTransition` is NOT imported — it calls `useCurrentFrame()`. Its
+pure body is the named export `progressValueAt`, which is called directly.
+`bun test` resolves tsconfig `paths`, so the alias works without additional
+config.
+
+## Determinism grep checklist (run manually; must print NOTHING)
+
+`progress/index.tsx` is a pure renderer — the component must contain **none**
+of the following:
+
+```bash
+grep -nE "useState|useEffect|useCurrentFrame|onClick|onChange|addEventListener|Date\.now|Math\.random|requestAnimationFrame" \
+ registry/remocn-ui/progress/index.tsx
+```
+
+Expected: **no output**. Any match is a determinism violation.
+
+`use-progress-transition.ts` intentionally reads `useCurrentFrame()` (in
+`useProgressTransition`). That is correct and expected; the smooth-path design
+isolates all frame-reading to the hook, keeping `<Progress>` pure. The
+exported `progressValueAt` is frame-free and testable directly.
+
+Tier-wide sweep for `index.tsx`:
+
+```bash
+grep -nE "useState|useEffect|onClick|onChange|addEventListener|Date\.now|Math\.random" \
+ registry/remocn-ui/progress/index.tsx registry/remocn-ui/core/*.ts
+```
diff --git a/registry/remocn-ui/progress/__tests__/progress.test.ts b/registry/remocn-ui/progress/__tests__/progress.test.ts
new file mode 100644
index 00000000..b84e1095
--- /dev/null
+++ b/registry/remocn-ui/progress/__tests__/progress.test.ts
@@ -0,0 +1,517 @@
+/**
+ * Verification tests for the PURE / DETERMINISTIC parts of `progress`.
+ *
+ * Scope:
+ * - registry/remocn-ui/progress/index.tsx
+ * clampValue (internal) — exercised via exported ProgressStyle + render logic
+ * ProgressStyle interface — value field semantics
+ * - registry/remocn-ui/progress/use-progress-transition.ts
+ * tweenProgressStyle(a, b, t) — pure single-field lerp
+ * progressValueAt(steps, raw, opts) — pure exported core of useProgressTransition
+ * DEFAULT_DURATION constant
+ * ProgressStep interface semantics
+ * - registry/remocn-ui/progress/config.ts
+ * progressConfig.controls wiring + progressConfig.snippet codegen
+ *
+ * The render path (index.tsx) imports `useRemocnTheme` which requires React
+ * context — it is NOT exercised here. `useProgressTransition` IS a hook (calls
+ * `useCurrentFrame()`) and is NOT imported; its pure body is the exported
+ * `progressValueAt` which we call directly.
+ *
+ * Runner: Bun's built-in test runner (TypeScript-native, no framework dep).
+ * bun test registry/remocn-ui/progress/__tests__
+ *
+ * --------------------------------------------------------------------------
+ * IMPORT STRATEGY
+ * --------------------------------------------------------------------------
+ * Relative imports from component source; `@/lib/remocn-ui` alias for core.
+ * `tweenProgressStyle` and `progressValueAt` are pure value functions — they
+ * call neither `useCurrentFrame()` nor `useRemocnTheme` at import or call time.
+ * `useProgressTransition` IS a hook and is NOT imported; we call `progressValueAt`
+ * directly (it is the exported pure core, annotated as such in the source).
+ * --------------------------------------------------------------------------
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+ tweenProgressStyle,
+ progressValueAt,
+ DEFAULT_DURATION,
+ type ProgressStep,
+} from "../use-progress-transition";
+import { progressConfig } from "../config";
+import { easings, clamp01 } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Shared fixtures
+// ===========================================================================
+
+/** Convenience wrapper for snippet(). */
+type SnippetValues = {
+ value?: number;
+ width?: number;
+ showLabel?: boolean;
+ mode?: string;
+};
+const snippet = (values: SnippetValues): string =>
+ progressConfig.snippet(values as Record<string, unknown>);
+
+// ===========================================================================
+// 1. DEFAULT_DURATION constant
+// ===========================================================================
+
+describe("DEFAULT_DURATION", () => {
+ it("is 24 frames", () => {
+ expect(DEFAULT_DURATION).toBe(24);
+ });
+});
+
+// ===========================================================================
+// 2. clampValue semantics — the component applies clamp01(value/100)*100
+// This is the value-channel equivalent of the state-atom clamp.
+// MIRROR of index.tsx lines 43-45 (clampValue function).
+// ===========================================================================
+
+/**
+ * MIRROR of index.tsx:clampValue (lines 43-45).
+ * clamp01 is `Math.max(0, Math.min(1, t))`.
+ */
+function clampValue(value: number): number {
+ return clamp01(value / 100) * 100;
+}
+
+describe("clampValue: below-range values clamp to 0", () => {
+ it("value=-10 clamps to 0", () => {
+ expect(clampValue(-10)).toBe(0);
+ });
+
+ it("value=-0.001 clamps to 0", () => {
+ expect(clampValue(-0.001)).toBe(0);
+ });
+});
+
+describe("clampValue: above-range values clamp to 100", () => {
+ it("value=110 clamps to 100", () => {
+ expect(clampValue(110)).toBe(100);
+ });
+
+ it("value=100.001 clamps to 100", () => {
+ expect(clampValue(100.001)).toBe(100);
+ });
+});
+
+describe("clampValue: in-range values pass through unchanged", () => {
+ it("value=0 returns 0", () => {
+ expect(clampValue(0)).toBe(0);
+ });
+
+ it("value=50 returns 50", () => {
+ expect(clampValue(50)).toBe(50);
+ });
+
+ it("value=100 returns 100", () => {
+ expect(clampValue(100)).toBe(100);
+ });
+
+ it("value=62 (the config default) returns 62", () => {
+ expect(clampValue(62)).toBe(62);
+ });
+
+ it("value=99.9 returns 99.9", () => {
+ expect(clampValue(99.9)).toBeCloseTo(99.9, 10);
+ });
+});
+
+// ===========================================================================
+// 3. showLabel floor — the label renders Math.floor(v)%
+// MIRROR of index.tsx line 113: {Math.floor(v)}%
+// ===========================================================================
+
+describe("showLabel floor: Math.floor applied to clamped value", () => {
+ it("Math.floor(62.7) = 62", () => {
+ expect(Math.floor(clampValue(62.7))).toBe(62);
+ });
+
+ it("Math.floor(99.9) = 99 (does NOT round up to 100)", () => {
+ expect(Math.floor(clampValue(99.9))).toBe(99);
+ });
+
+ it("Math.floor(0) = 0", () => {
+ expect(Math.floor(clampValue(0))).toBe(0);
+ });
+
+ it("Math.floor(100) = 100", () => {
+ expect(Math.floor(clampValue(100))).toBe(100);
+ });
+
+ it("Math.floor(87.5) = 87", () => {
+ expect(Math.floor(clampValue(87.5))).toBe(87);
+ });
+});
+
+// ===========================================================================
+// 4. tweenProgressStyle — pure single-field lerp
+// MIRROR of use-progress-transition.ts lines 34-40
+// ===========================================================================
+
+describe("tweenProgressStyle: t=0 returns value equal to `a`", () => {
+ it("value equals a.value at t=0", () => {
+ const r = tweenProgressStyle({ value: 0 }, { value: 100 }, 0);
+ expect(r.value).toBeCloseTo(0, 10);
+ });
+});
+
+describe("tweenProgressStyle: t=1 returns value equal to `b`", () => {
+ it("value equals b.value at t=1", () => {
+ const r = tweenProgressStyle({ value: 0 }, { value: 100 }, 1);
+ expect(r.value).toBeCloseTo(100, 10);
+ });
+});
+
+describe("tweenProgressStyle: t=0.5 midpoint", () => {
+ it("0→100 at t=0.5 gives 50", () => {
+ const r = tweenProgressStyle({ value: 0 }, { value: 100 }, 0.5);
+ expect(r.value).toBeCloseTo(50, 10);
+ });
+
+ it("25→75 at t=0.5 gives 50", () => {
+ const r = tweenProgressStyle({ value: 25 }, { value: 75 }, 0.5);
+ expect(r.value).toBeCloseTo(50, 10);
+ });
+});
+
+describe("tweenProgressStyle: identity (a === b, any t)", () => {
+ it("value is unchanged when both endpoints are the same", () => {
+ const r = tweenProgressStyle({ value: 62 }, { value: 62 }, 0.5);
+ expect(r.value).toBeCloseTo(62, 10);
+ });
+});
+
+describe("tweenProgressStyle: t=0.25 quarter-point", () => {
+ // 0→100 at t=0.25: 0 + 0.25*(100-0) = 25
+ it("0→100 at t=0.25 gives 25", () => {
+ const r = tweenProgressStyle({ value: 0 }, { value: 100 }, 0.25);
+ expect(r.value).toBeCloseTo(25, 10);
+ });
+});
+
+describe("tweenProgressStyle: decreasing direction (100→0)", () => {
+ it("100→0 at t=0.5 gives 50", () => {
+ const r = tweenProgressStyle({ value: 100 }, { value: 0 }, 0.5);
+ expect(r.value).toBeCloseTo(50, 10);
+ });
+});
+
+describe("tweenProgressStyle: result has only a `value` field", () => {
+ it("result object has exactly one key: value", () => {
+ const r = tweenProgressStyle({ value: 30 }, { value: 70 }, 0.5);
+ expect(typeof r.value).toBe("number");
+ });
+});
+
+// ===========================================================================
+// 5. progressValueAt — pure exported core of useProgressTransition
+// MIRROR of use-progress-transition.ts lines 66-102.
+// useProgressTransition is exactly progressValueAt(steps, useCurrentFrame()*speed, opts).
+// We call progressValueAt directly with the frame injected as `raw`.
+//
+// MAINTENANCE CONTRACT: if use-progress-transition.ts lines 66-102 change,
+// update these tests in lockstep. Annotated source lines below.
+// ===========================================================================
+
+describe("progressValueAt: empty steps → value=0", () => {
+ // source line 73: if (steps.length === 0) return { value: 0 }
+ it("returns {value:0} for any raw frame when steps is empty", () => {
+ expect(progressValueAt([], 0).value).toBe(0);
+ expect(progressValueAt([], 100).value).toBe(0);
+ });
+});
+
+describe("progressValueAt: before first step — holds at first.value", () => {
+ // source lines 78-79: if (raw <= first.at) return { value: first.value }
+ const steps: ProgressStep[] = [{ at: 10, value: 60 }];
+
+ it("raw=5 < first.at=10 → holds at first.value=60", () => {
+ expect(progressValueAt(steps, 5).value).toBe(60);
+ });
+
+ it("raw=10 = first.at=10 → still holds at first.value=60 (raw <= first.at)", () => {
+ expect(progressValueAt(steps, 10).value).toBe(60);
+ });
+
+ it("raw=0 → holds at first.value=60", () => {
+ expect(progressValueAt(steps, 0).value).toBe(60);
+ });
+});
+
+describe("progressValueAt: past last step — rests at last.value", () => {
+ // source lines 90-92: pastLast → to=from=last step, t=1
+ const steps: ProgressStep[] = [{ at: 20, value: 75 }];
+
+ it("raw=50 > last.at=20 → value=75 (rests at last)", () => {
+ expect(progressValueAt(steps, 50).value).toBeCloseTo(75, 10);
+ });
+
+ it("raw=100 → value=75", () => {
+ expect(progressValueAt(steps, 100).value).toBeCloseTo(75, 10);
+ });
+});
+
+describe("progressValueAt: mid-window uses easings.out (not linear)", () => {
+ // Two steps: [{at:0,value:0},{at:24,value:100}], default dur=24.
+ // At raw=12: start=24-24=0, linear=(12-0)/24=0.5, t=out(0.5)=0.875
+ // value = 0 + 100*0.875 = 87.5
+ const steps: ProgressStep[] = [{ at: 0, value: 0 }, { at: 24, value: 100 }];
+
+ it("raw=12 gives value=87.5 (out-eased, not linear 50)", () => {
+ const r = progressValueAt(steps, 12);
+ expect(r.value).toBeCloseTo(87.5, 8);
+ });
+
+ it("out(0.5)=0.875 — easing is non-linear at the midpoint", () => {
+ // This confirms the test above is not accidentally passing with linear math
+ expect(easings.out(0.5)).toBeCloseTo(0.875, 8);
+ });
+});
+
+describe("progressValueAt: exactly at a step boundary — progress=0", () => {
+ // At raw just past first.at, before dur expires:
+ // steps=[{at:0,value:0},{at:24,value:100}], raw=0.0001 (just after step[1].at=24? no)
+ // Actually raw=24: steps[1].at=24. pastLast = raw(24) >= steps[1].at(24) = true → t=1 → value=100
+ const steps: ProgressStep[] = [{ at: 0, value: 0 }, { at: 24, value: 100 }];
+
+ it("raw=24 exactly (at last step boundary) → pastLast=true → value=100", () => {
+ expect(progressValueAt(steps, 24).value).toBeCloseTo(100, 10);
+ });
+
+ it("raw=0 (at first step) → holds at first.value=0", () => {
+ expect(progressValueAt(steps, 0).value).toBe(0);
+ });
+});
+
+describe("progressValueAt: two-step timeline mid-second segment", () => {
+ // steps=[{at:0,value:0},{at:24,value:50},{at:48,value:100}]
+ // At raw=36 (mid of second segment [24→48], dur=24):
+ // toIndex search: steps[2].at=48 > 36 → toIndex=2
+ // pastLast = 36 >= 48 → false
+ // to=steps[2]={at:48,value:100}, from=steps[1]={at:24,value:50}
+ // dur=24, start=48-24=24, t=out(clamp01((36-24)/24))=out(0.5)=0.875
+ // value=50+(100-50)*0.875=50+43.75=93.75
+ const steps: ProgressStep[] = [
+ { at: 0, value: 0 },
+ { at: 24, value: 50 },
+ { at: 48, value: 100 },
+ ];
+
+ it("raw=36 mid-second segment gives value=93.75", () => {
+ expect(progressValueAt(steps, 36).value).toBeCloseTo(93.75, 8);
+ });
+
+ it("raw=24 (start of second segment, pastLast=false) is still in first segment end", () => {
+ // raw=24: steps[2].at=48 > 24 → toIndex=2 (not pastLast)
+ // Wait — steps[1].at=24 is NOT > raw(24), so we keep searching. steps[2].at=48 > 24 → toIndex=2
+ // to=steps[2], from=steps[1]. start=48-24=24, t=out((24-24)/24)=out(0)=0
+ // value=50+(100-50)*0=50
+ expect(progressValueAt(steps, 24).value).toBeCloseTo(50, 10);
+ });
+});
+
+describe("progressValueAt: custom duration on a step", () => {
+ // steps=[{at:0,value:0},{at:12,value:100,duration:12}]
+ // At raw=6: start=12-12=0, t=out(6/12)=out(0.5)=0.875, value=87.5
+ const steps: ProgressStep[] = [{ at: 0, value: 0 }, { at: 12, value: 100, duration: 12 }];
+
+ it("custom duration=12: raw=6 gives value=87.5", () => {
+ expect(progressValueAt(steps, 6).value).toBeCloseTo(87.5, 8);
+ });
+});
+
+describe("progressValueAt: easing applied before lerp (default 'out')", () => {
+ // Confirms t=easings.out(linear_progress), not raw linear_progress.
+ // steps=[{at:0,value:0},{at:24,value:100}], raw=12 → linear=0.5
+ // If linear: value=50. With out-easing: value=87.5.
+ const steps: ProgressStep[] = [{ at: 0, value: 0 }, { at: 24, value: 100 }];
+
+ it("value at raw=12 (linear 0.5) is 87.5, not 50", () => {
+ const r = progressValueAt(steps, 12);
+ expect(r.value).not.toBeCloseTo(50, 1);
+ expect(r.value).toBeCloseTo(87.5, 8);
+ });
+});
+
+describe("progressValueAt: past last with multiple steps", () => {
+ // When past last, to=from=last → t=1 → value=last.value (from.value + 0*t = last.value)
+ const steps: ProgressStep[] = [
+ { at: 0, value: 0 },
+ { at: 24, value: 50 },
+ { at: 48, value: 100 },
+ ];
+
+ it("raw=100 → value=100 (last step value)", () => {
+ expect(progressValueAt(steps, 100).value).toBeCloseTo(100, 10);
+ });
+});
+
+// ===========================================================================
+// 6. progressConfig.controls — customizer control wiring
+// ===========================================================================
+
+describe("progressConfig.controls: value", () => {
+ it("value is a number control", () => {
+ expect(progressConfig.controls.value.type).toBe("number");
+ });
+
+ it("value default is 62", () => {
+ expect(progressConfig.controls.value.default).toBe(62);
+ });
+
+ it("value min is 0, max is 100", () => {
+ const ctrl = progressConfig.controls.value;
+ if (ctrl.type !== "number") throw new Error("expected number");
+ expect(ctrl.min).toBe(0);
+ expect(ctrl.max).toBe(100);
+ });
+});
+
+describe("progressConfig.controls: width", () => {
+ it("width is a number control", () => {
+ expect(progressConfig.controls.width.type).toBe("number");
+ });
+
+ it("width default is 320", () => {
+ expect(progressConfig.controls.width.default).toBe(320);
+ });
+
+ it("width min is 120, max is 640", () => {
+ const ctrl = progressConfig.controls.width;
+ if (ctrl.type !== "number") throw new Error("expected number");
+ expect(ctrl.min).toBe(120);
+ expect(ctrl.max).toBe(640);
+ });
+});
+
+describe("progressConfig.controls: showLabel", () => {
+ it("showLabel is a boolean control", () => {
+ expect(progressConfig.controls.showLabel.type).toBe("boolean");
+ });
+
+ it("showLabel default is true", () => {
+ expect(progressConfig.controls.showLabel.default).toBe(true);
+ });
+});
+
+describe("progressConfig.controls: mode", () => {
+ it("mode is a select control", () => {
+ expect(progressConfig.controls.mode.type).toBe("select");
+ });
+
+ it("mode options are ['light', 'dark']", () => {
+ const ctrl = progressConfig.controls.mode;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["light", "dark"]);
+ });
+
+ it("mode default is 'light'", () => {
+ expect(progressConfig.controls.mode.default).toBe("light");
+ });
+});
+
+// ===========================================================================
+// 7. progressConfig.snippet — pure JSX string builder
+// ===========================================================================
+
+describe("progressConfig.snippet: import line", () => {
+ it("includes 'import { Progress }' from the correct path", () => {
+ const out = snippet({ value: 50 });
+ expect(out).toContain("import { Progress }");
+ expect(out).toContain('from "@/components/remocn/progress"');
+ });
+});
+
+describe("progressConfig.snippet: structural invariants", () => {
+ it("contains a <Progress JSX element", () => {
+ expect(snippet({ value: 50 })).toContain("<Progress");
+ });
+
+ it("ends with a self-closing />", () => {
+ expect(snippet({ value: 50 }).trimEnd().endsWith("/>")).toBe(true);
+ });
+});
+
+describe("progressConfig.snippet: value is always emitted", () => {
+ // value is always emitted (including 0)
+ it("emits value={62} for the default value", () => {
+ const out = snippet({ value: 62 });
+ expect(out).toContain("value={62}");
+ });
+
+ it("emits value={0} when value is 0", () => {
+ const out = snippet({ value: 0 });
+ expect(out).toContain("value={0}");
+ });
+
+ it("emits value={100} when value is 100", () => {
+ const out = snippet({ value: 100 });
+ expect(out).toContain("value={100}");
+ });
+
+ it("emits value={0} when value is omitted from values (falls back to 0)", () => {
+ // snippet uses `value ?? 0`
+ const out = snippet({});
+ expect(out).toContain("value={0}");
+ });
+});
+
+describe("progressConfig.snippet: default props are omitted", () => {
+ // Defaults: width=320, mode=light; showLabel is omitted when falsy
+
+ it("omits width when it equals the default 320", () => {
+ const out = snippet({ value: 50, width: 320 });
+ expect(out).not.toContain("width=");
+ });
+
+ it("omits mode when it equals the default 'light'", () => {
+ const out = snippet({ value: 50, mode: "light" });
+ expect(out).not.toContain("mode=");
+ });
+
+ it("omits showLabel when it is false", () => {
+ const out = snippet({ value: 50, showLabel: false });
+ expect(out).not.toContain("showLabel");
+ });
+
+ it("omits showLabel when it is undefined", () => {
+ const out = snippet({ value: 50 });
+ expect(out).not.toContain("showLabel");
+ });
+});
+
+describe("progressConfig.snippet: non-default props are emitted", () => {
+ it("emits width={480} when non-default", () => {
+ expect(snippet({ value: 50, width: 480 })).toContain("width={480}");
+ });
+
+ it("emits width={200} when non-default", () => {
+ expect(snippet({ value: 50, width: 200 })).toContain("width={200}");
+ });
+
+ it("emits mode='dark' when non-default", () => {
+ expect(snippet({ value: 50, mode: "dark" })).toContain('mode="dark"');
+ });
+
+ it("emits showLabel (boolean shorthand) when true", () => {
+ // snippet: if (showLabel) props.push(' showLabel') — no value, just the attribute
+ const out = snippet({ value: 50, showLabel: true });
+ expect(out).toContain("showLabel");
+ // Must NOT be showLabel={true} — it's a boolean shorthand prop
+ expect(out).not.toContain("showLabel={true}");
+ });
+});
+
+describe("progressConfig.snippet: value numeric round-trip", () => {
+ it("emits the correct value for various inputs", () => {
+ for (const v of [0, 25, 50, 75, 100]) {
+ expect(snippet({ value: v })).toContain(`value={${v}}`);
+ }
+ });
+});
diff --git a/registry/remocn-ui/progress/config.ts b/registry/remocn-ui/progress/config.ts
new file mode 100644
index 00000000..1b556f6f
--- /dev/null
+++ b/registry/remocn-ui/progress/config.ts
@@ -0,0 +1,45 @@
+import { type ComponentConfig, FPS, H, W } from "@/lib/customizer-config";
+
+export const progressConfig: ComponentConfig = {
+ componentName: "Progress",
+ importPath: "@/components/remocn/progress",
+ controls: {
+ value: { type: "number", default: 62, min: 0, max: 100, step: 1, label: "Value" },
+ width: {
+ type: "number",
+ default: 320,
+ min: 120,
+ max: 640,
+ step: 20,
+ label: "Width",
+ },
+ showLabel: { type: "boolean", default: true, label: "Show Label" },
+ mode: {
+ type: "select",
+ default: "light",
+ options: ["light", "dark"],
+ label: "Mode",
+ },
+ },
+ durationInFrames: 120,
+ fps: FPS,
+ compositionWidth: W,
+ compositionHeight: H,
+ snippet: (values) => {
+ const value = values.value as number | undefined;
+ const width = values.width as number | undefined;
+ const showLabel = values.showLabel as boolean | undefined;
+ const mode = values.mode as string | undefined;
+
+ const props: string[] = [` value={${value ?? 0}}`];
+ if (width !== undefined && width !== 320) props.push(` width={${width}}`);
+ if (showLabel) props.push(` showLabel`);
+ if (mode !== undefined && mode !== "light") props.push(` mode="${mode}"`);
+
+ return `import { Progress } from "@/components/remocn/progress";
+
+<Progress
+${props.join("\n")}
+/>`;
+ },
+};
diff --git a/registry/remocn-ui/progress/index.tsx b/registry/remocn-ui/progress/index.tsx
new file mode 100644
index 00000000..59e8e6ff
--- /dev/null
+++ b/registry/remocn-ui/progress/index.tsx
@@ -0,0 +1,118 @@
+"use client";
+
+import { clamp01, type RemocnTheme, useRemocnTheme } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Progress visual — the COMPLETE animated look for a moment in time. The animated
+// channel here is numeric (the fill value), the accepted value-channel deviation
+// from the string-`state` atoms (STYLE-GUIDE §0): `useProgressTransition` feeds an
+// interpolated `ProgressStyle` straight through, exactly like `style` on a state
+// atom, while the snap path is the `value` prop. The component never reads the
+// frame.
+// ===========================================================================
+
+export interface ProgressStyle {
+ /** Fill percentage 0–100 (clamped by the renderer). */
+ value: number;
+}
+
+export interface ProgressProps {
+ /**
+ * Fill percentage 0–100 (snap path). Clamped to [0,100]. Ignored when `style`
+ * is supplied.
+ */
+ value?: number;
+ /**
+ * Resolved animated visual (smooth path). When provided, takes precedence over
+ * `value` — feed it an interpolated `ProgressStyle` from `useProgressTransition`.
+ */
+ style?: ProgressStyle;
+ /** Track width in px. */
+ width?: number;
+ /** Show the floored percentage to the right of the track. */
+ showLabel?: boolean;
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ className?: string;
+}
+
+/** Track height (px) — shadcn `h-3`. */
+const TRACK_HEIGHT = 12;
+
+/** Clamp a 0–100 value to [0,100]. Reuses core clamp01 on the normalized value. */
+function clampValue(value: number): number {
+ return clamp01(value / 100) * 100;
+}
+
+/**
+ * A deterministic progress bar. Pure renderer of whatever value it receives — it
+ * reads no frame, holds no state, runs no effects. Snap (`value`) and smooth
+ * (`style`) share one render path. Placement is the caller's job; the bar renders
+ * inline.
+ */
+export function Progress({
+ value = 0,
+ style,
+ width = 320,
+ showLabel = false,
+ theme: themeOverride,
+ mode,
+ className,
+}: ProgressProps) {
+ const theme = useRemocnTheme(themeOverride, mode);
+ const v = clampValue(style ? style.value : value);
+
+ const track = theme.muted;
+ const indicator = theme.primary;
+
+ return (
+ <div
+ className={className}
+ style={{
+ display: "inline-flex",
+ alignItems: "center",
+ gap: 12,
+ fontFamily:
+ "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif",
+ }}
+ >
+ {/* Track — muted rail; the indicator fills it left-to-right by `value%`. */}
+ <div
+ style={{
+ position: "relative",
+ width,
+ height: TRACK_HEIGHT,
+ borderRadius: TRACK_HEIGHT / 2,
+ background: track,
+ overflow: "hidden",
+ }}
+ >
+ <div
+ style={{
+ position: "absolute",
+ left: 0,
+ top: 0,
+ bottom: 0,
+ width: `${v}%`,
+ borderRadius: TRACK_HEIGHT / 2,
+ background: indicator,
+ }}
+ />
+ </div>
+ {showLabel && (
+ <span
+ style={{
+ fontSize: 14,
+ fontWeight: 500,
+ fontVariantNumeric: "tabular-nums",
+ color: theme.mutedForeground,
+ minWidth: "3ch",
+ textAlign: "right",
+ }}
+ >
+ {Math.floor(v)}%
+ </span>
+ )}
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/progress/preview.tsx b/registry/remocn-ui/progress/preview.tsx
new file mode 100644
index 00000000..4c0c3511
--- /dev/null
+++ b/registry/remocn-ui/progress/preview.tsx
@@ -0,0 +1,42 @@
+"use client";
+
+import { useRemocnTheme } from "@/lib/remocn-ui";
+import { Progress } from "@/registry/remocn-ui/progress";
+
+export interface ProgressPreviewProps {
+ value?: number;
+ width?: number;
+ showLabel?: boolean;
+ mode?: "light" | "dark";
+}
+
+/**
+ * Preview-only wrapper for the customizer. The shipped `Progress` is a
+ * placement-agnostic inline bar — the caller positions it. The customizer Player
+ * renders its `component` as the composition root, so a bare `Progress` would sit
+ * top-left in normal flow; this thin wrapper centers it on a theme-background
+ * stage just for the preview. NOT shipped: not listed in registry.json files.
+ */
+export function ProgressPreview({
+ value = 62,
+ width = 320,
+ showLabel = true,
+ mode,
+}: ProgressPreviewProps) {
+ const theme = useRemocnTheme(undefined, mode);
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ background: theme.background,
+ }}
+ >
+ <Progress value={value} width={width} showLabel={showLabel} mode={mode} />
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/progress/use-progress-transition.ts b/registry/remocn-ui/progress/use-progress-transition.ts
new file mode 100644
index 00000000..b54abf88
--- /dev/null
+++ b/registry/remocn-ui/progress/use-progress-transition.ts
@@ -0,0 +1,102 @@
+"use client";
+
+import { useCurrentFrame } from "remotion";
+import { clamp01, type EasingName, easings } from "@/lib/remocn-ui";
+import type { ProgressStyle } from "@/components/remocn/progress";
+// ^ install path; resolves in-repo via the @/components/remocn/* tsconfig alias.
+
+/**
+ * A scripted progress value the bar eases TO. The fill tweens from the previous
+ * step's value to this one over `[at, at + (duration ?? DEFAULT_DURATION))`.
+ */
+export interface ProgressStep {
+ /** LOCAL (Sequence-relative) authored frame the bar finishes reaching `value`. */
+ at: number;
+ /** Target fill percentage 0–100. */
+ value: number;
+ /** Frames the move INTO this value takes. Omitted → DEFAULT_DURATION. */
+ duration?: number;
+ /** Override the easing for the move into this value. Default `out`. */
+ easing?: EasingName;
+}
+
+/** Default frames for a move into a step when it omits `duration`. */
+export const DEFAULT_DURATION = 24;
+
+export interface ProgressTransitionOptions {
+ /** Playhead scale (effectiveFrame = useCurrentFrame() * speed). */
+ speed?: number;
+ /** Move duration (frames) when a step omits `duration`. */
+ defaultDuration?: number;
+}
+
+/** Blend two progress visuals: the single numeric `value` field lerps. */
+export function tweenProgressStyle(
+ a: ProgressStyle,
+ b: ProgressStyle,
+ t: number,
+): ProgressStyle {
+ return { value: a.value + (b.value - a.value) * t };
+}
+
+/**
+ * Resolve the bar's `ProgressStyle` for a value timeline. THIS is the only
+ * frame-reading file in the component — `<Progress>` itself stays pure. Mirrors
+ * the value-channel deviation (like cursor's `useCursorPath`): instead of a
+ * string-state timeline it folds a numeric value path.
+ *
+ * The fold is a pure function of `raw = useCurrentFrame() * speed`; the tests
+ * replicate `progressValueAt(steps, raw, opts)` with the frame injected.
+ */
+export function useProgressTransition(
+ steps: ProgressStep[],
+ opts: ProgressTransitionOptions = {},
+): ProgressStyle {
+ const { speed = 1 } = opts;
+ const raw = useCurrentFrame() * speed;
+ return progressValueAt(steps, raw, opts);
+}
+
+/**
+ * Pure core of `useProgressTransition` with the effective frame injected as
+ * `raw`. Kept separate so it can be unit-tested without a Remotion render.
+ * `useProgressTransition` is exactly `progressValueAt(steps, useCurrentFrame() *
+ * speed, opts)`.
+ */
+export function progressValueAt(
+ steps: ProgressStep[],
+ raw: number,
+ opts: ProgressTransitionOptions = {},
+): ProgressStyle {
+ const { defaultDuration = DEFAULT_DURATION } = opts;
+
+ if (steps.length === 0) return { value: 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 value (no teleport).
+ if (raw <= first.at) return { value: first.value };
+
+ // 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 value = from.value + (to.value - from.value) * t;
+
+ return { value };
+}
diff --git a/registry/remocn-ui/registry.json b/registry/remocn-ui/registry.json
index 329055eb..e5effa1e 100644
--- a/registry/remocn-ui/registry.json
+++ b/registry/remocn-ui/registry.json
@@ -456,6 +456,26 @@
"target": "components/remocn/use-tooltip-transition.ts"
}
]
+ },
+ {
+ "name": "progress",
+ "type": "registry:component",
+ "title": "UI Progress",
+ "description": "A progress bar whose fill is a pure function of a numeric value channel (value-channel deviation). The Progress renderer takes a clamped 0–100 value; useProgressTransition reads the frame and eases the fill between value steps. Muted track + primary indicator, optional floored percentage label.",
+ "dependencies": ["remotion"],
+ "registryDependencies": ["remocn-ui"],
+ "files": [
+ {
+ "path": "progress/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/progress.tsx"
+ },
+ {
+ "path": "progress/use-progress-transition.ts",
+ "type": "registry:component",
+ "target": "components/remocn/use-progress-transition.ts"
+ }
+ ]
}
]
}