Production-ready animations, transitions, backgrounds, and scenes for Remotion
TypeScript ai-agentsclaude-codedemo-videomcpmcp-servermodel-context-protocolmotion-designproduct-demoreactremotionshadcnvideo
feat: added progress component
dev_wandrycb07d9770a99
diff --git a/components/docs/examples/index.tsx b/components/docs/examples/index.tsxindex 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.tsxnew file mode 100644index 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.tsxindex c54cd943..5adac5b4 100644--- a/components/docs/examples/tooltip-example.tsx+++ b/components/docs/examples/tooltip-example.tsx@@ -120,7 +120,7 @@ export const Scene = () => {<divstyle={{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.jsonindex 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.mdxnew file mode 100644index 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__.tsxindex 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.mdnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.jsonindex 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"+ }+ ]}]}