Skip to content

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

feat: added checkbox component

dev_wandry6fbcb75ff526
diff --git a/components/docs/examples/checkbox-example.tsx b/components/docs/examples/checkbox-example.tsx
new file mode 100644
index 00000000..9389c3e3
--- /dev/null
+++ b/components/docs/examples/checkbox-example.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import { Checkbox } from "@/registry/remocn-ui/checkbox";
+import { useCheckboxTransition } from "@/registry/remocn-ui/checkbox/use-checkbox-transition";
+
+export const CheckboxExampleScene = () => {
+ const style = useCheckboxTransition([
+ { at: 18, state: "checked", duration: 14 },
+ { at: 78, state: "unchecked", duration: 12 },
+ ]);
+ return <Checkbox label="Accept terms and conditions" style={style} />;
+};
+
+export const checkboxExampleCode = `import { Checkbox } from "@/components/remocn/checkbox";
+import { useCheckboxTransition } from "@/components/remocn/use-checkbox-transition";
+
+export const Scene = () => {
+ const style = useCheckboxTransition([
+ { at: 18, state: "checked", duration: 14 },
+ { at: 78, state: "unchecked", duration: 12 },
+ ]);
+
+ return <Checkbox label="Accept terms and conditions" style={style} />;
+};`;
diff --git a/components/docs/examples/index.tsx b/components/docs/examples/index.tsx
index 2503ca77..74f4105b 100644
--- a/components/docs/examples/index.tsx
+++ b/components/docs/examples/index.tsx
@@ -9,6 +9,10 @@ import {
alertDialogExampleCode,
} from "./alert-dialog-example";
import { ButtonExampleScene, buttonExampleCode } from "./button-example";
+import {
+ CheckboxExampleScene,
+ checkboxExampleCode,
+} from "./checkbox-example";
export interface ExampleEntry {
Component: ComponentType;
@@ -46,4 +50,12 @@ export const examples: Record<string, ExampleEntry> = {
width: W,
height: H,
},
+ "checkbox-example": {
+ Component: CheckboxExampleScene,
+ code: checkboxExampleCode,
+ durationInFrames: 100,
+ fps: FPS,
+ width: W,
+ height: H,
+ },
};
diff --git a/content/docs/ui/components/checkbox.mdx b/content/docs/ui/components/checkbox.mdx
new file mode 100644
index 00000000..7fee937e
--- /dev/null
+++ b/content/docs/ui/components/checkbox.mdx
@@ -0,0 +1,136 @@
+---
+title: Checkbox
+description: A checkbox whose checked/unchecked state is a pure function of the timeline
+---
+
+<ComponentPreview name="checkbox" />
+
+A state atom whose appearance (checked, unchecked) is a pure function of the `state` prop. Pass a state directly or drive it from the Remotion timeline via `useCurrentState`. The component reads no frame — only the state value you give it.
+
+## Installation
+
+<InstallBlock name="checkbox" />
+
+<Note>
+Installing `checkbox` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) via `registryDependencies`. You do not need to install it separately.
+</Note>
+
+## States
+
+`CheckboxState` is:
+
+```ts
+type CheckboxState =
+ | "unchecked" // empty box, border = theme.border, no checkmark
+ | "checked" // box fills with primary, border = primary, checkmark draws on
+```
+
+`checked` fills the box background with `primary`, sets the border to `primary`, and draws the checkmark with opacity, scale, and stroke animations. `unchecked` renders an empty box with the theme border color.
+
+## Snap usage
+
+Pass `state` directly — the component snaps instantly to that visual. Useful for static previews or when you drive state from your own logic:
+
+```tsx
+import { Checkbox } from "@/components/remocn/checkbox";
+
+export const Scene = () => <Checkbox state="checked" />;
+```
+
+To drive state from the timeline, use `useCurrentState`:
+
+```tsx
+import { useCurrentState } from "@/lib/remocn-ui";
+import { Checkbox } from "@/components/remocn/checkbox";
+
+export const Scene = () => {
+ const state = useCurrentState(
+ [
+ { at: 18, state: "checked" },
+ { at: 78, state: "unchecked" },
+ ],
+ "unchecked",
+ );
+
+ return <Checkbox label="Accept terms" state={state} />;
+};
+```
+
+Each `at` is a **Sequence-local authored frame**. State persists between steps: `checked` at frame 18 keeps the box checked until `unchecked` fires at frame 78. See [Concepts](/docs/ui/concepts) for the full `useCurrentState` API.
+
+## Smooth transitions
+
+State changes via `state` snap with no cross-fade. For animated transitions, use `useCheckboxTransition` from the copied `use-checkbox-transition.ts` file. It reads the frame, interpolates between state presets, and returns a resolved `CheckboxStyle` — pass it to the `style` prop:
+
+```tsx
+import { Checkbox } from "@/components/remocn/checkbox";
+import { useCheckboxTransition } from "@/components/remocn/use-checkbox-transition";
+
+export const Scene = () => {
+ const style = useCheckboxTransition([
+ { at: 18, state: "checked", duration: 14 },
+ { at: 78, state: "unchecked", duration: 12 },
+ ]);
+ return <Checkbox label="Accept terms" style={style} />;
+};
+```
+
+The `duration` field on each step overrides the file's `DEFAULT_DURATION` for that specific transition. To globally tune timing and easing, edit `use-checkbox-transition.ts` directly in your project — that file is yours (shadcn "own your code" philosophy).
+
+`style` takes precedence over `state` when both are provided.
+
+## Full lifecycle
+
+A complete unchecked → checked → unchecked run using the smooth transition path. Copy the code to drop it into your own composition.
+
+<LiveExample name="checkbox-example" />
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "state",
+ type: "\"unchecked\" | \"checked\"",
+ default: "\"unchecked\"",
+ description: "Current visual state (snap path). State changes snap — no automatic cross-fade.",
+ },
+ {
+ name: "style",
+ type: "CheckboxStyle",
+ description: "Resolved animated visual (smooth path). Pass an interpolated CheckboxStyle from useCheckboxTransition. Takes precedence over state when provided.",
+ },
+ {
+ name: "label",
+ type: "string",
+ description: "Optional text label rendered next to the box. Omit for a bare checkbox.",
+ },
+ {
+ name: "size",
+ type: "\"sm\" | \"default\" | \"lg\"",
+ default: "\"default\"",
+ description: "Box and label size preset.",
+ },
+ {
+ 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: "primary",
+ type: "string",
+ description: "Convenience override for the primary theme token — merged into theme.",
+ },
+ {
+ 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 passed to the checkbox element.",
+ },
+ ]}
+/>
diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.json
index b438b18a..0ee20f66 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", "spinner"]
+ "pages": ["accordion", "alert-dialog", "button", "checkbox", "spinner"]
}
diff --git a/registry/__index__.tsx b/registry/__index__.tsx
index d73d1e18..42be79fd 100644
--- a/registry/__index__.tsx
+++ b/registry/__index__.tsx
@@ -111,6 +111,8 @@ import { AlertDialog } from "@/registry/remocn-ui/alert-dialog";
import { alertDialogConfig } from "@/registry/remocn-ui/alert-dialog/config";
import { Button } from "@/registry/remocn-ui/button";
import { buttonConfig } from "@/registry/remocn-ui/button/config";
+import { Checkbox } from "@/registry/remocn-ui/checkbox";
+import { checkboxConfig } from "@/registry/remocn-ui/checkbox/config";
import { Spinner } from "@/registry/remocn-ui/spinner";
import { spinnerConfig } from "@/registry/remocn-ui/spinner/config";
import { ZoomThroughTransition } from "@/registry/remocn/zoom-through-transition";
@@ -289,6 +291,7 @@ const registry: Record<string, RegistryEntry> = {
"button": { Component: Button, config: buttonConfig },
"accordion": { Component: Accordion, config: accordionConfig },
"alert-dialog": { Component: AlertDialog, config: alertDialogConfig },
+ "checkbox": { Component: Checkbox, config: checkboxConfig },
"spinner": { Component: Spinner, config: spinnerConfig },
};
diff --git a/registry/remocn-ui/checkbox/__tests__/README.md b/registry/remocn-ui/checkbox/__tests__/README.md
new file mode 100644
index 00000000..8d297ecb
--- /dev/null
+++ b/registry/remocn-ui/checkbox/__tests__/README.md
@@ -0,0 +1,120 @@
+# `checkbox` — verification tests
+
+Pure / deterministic verification for the `checkbox` component
+(`registry/remocn-ui/checkbox/`). The RENDER path needs Remotion's
+`useCurrentFrame()` and cannot run headless, so the render is NOT exercised
+here. This suite covers the pieces that ARE pure: `CheckboxState` union
+membership, `checkboxConfig.controls.state` wiring, `checkboxConfig.snippet`
+codegen, `checkboxStyle` presets, and `tweenCheckboxStyle` interpolation.
+
+## Animation model — pure snap + opt-in smooth path
+
+Checkbox ships two complementary paths:
+
+**Snap path** (`state?: CheckboxState` prop):
+`Checkbox` is a frame-free pure renderer. The `state` prop drives all visuals.
+Each state maps to a complete resting visual via the exported pure function
+`checkboxStyle(state, ctx) => CheckboxStyle`. State changes snap instantly — no
+tweening inside the component.
+
+**Smooth path** (`style?: CheckboxStyle` prop):
+Callers opt in to smooth transitions by passing a pre-interpolated `CheckboxStyle`
+to the `style` prop. The caller — typically `useCheckboxTransition` — reads
+`useCurrentFrame()` and calls `useStateTransition` from `core/timeline.ts` to
+compute `{ from, to, progress }`, then blends the two presets via
+`tweenCheckboxStyle(from, to, t)`. The `Checkbox` component itself remains
+frame-free; it simply renders whatever `CheckboxStyle` it receives.
+
+This design keeps `Checkbox` pure-testable (no Remotion render context needed)
+while still supporting smooth check/uncheck transitions for production use.
+
+## 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/checkbox/__tests__
+```
+
+`checkbox.test.ts` imports `bun:test` (not `vitest`/`jest`), so no test script
+or framework dep is added to `package.json`.
+
+## What is covered
+
+- **`CheckboxState` union** — asserts the two states `["unchecked","checked"]`
+ are the complete set (via the real `controls.state.options` list from
+ `config.ts`).
+- **`checkboxConfig.controls.state`** — the customizer control wiring. Asserts a
+ `select` control exists with exactly those two options, default `"checked"`
+ (so the preview shows the filled box and checkmark), and that every option is
+ a member of the `CheckboxState` union.
+- **`checkboxConfig.snippet`** — REAL pure string builder (high value).
+ Asserts: emits `state="<state>"` as a bare JSX prop for every option; NEVER
+ emits `steps` or `action`; includes `import { Checkbox }` from
+ `@/components/remocn/checkbox`; omits default-equal props (`label=""`,
+ `size=default`, `mode=light`, `primary=#171717`); EMITS non-default
+ `label`/`size`/`mode`/`primary`; structural round-trip (starts with import,
+ contains `<Checkbox`, ends `/>`).
+- **`checkboxStyle` presets** — exported pure `(state, ctx) => CheckboxStyle` map.
+ A `CheckboxStyleContext` is built from `checkboxStyleContext(defaultLightTheme)`
+ — the same call the component makes internally. Asserts per-state numeric
+ invariants (checkOpacity, checkScale, checkDraw) and that `boxBackground` /
+ `boxBorderColor` are always non-empty strings. Also asserts the key invariant:
+ unchecked has checkOpacity 0 & checkDraw 0; checked has checkOpacity 1 &
+ checkDraw 1.
+- **`tweenCheckboxStyle`** — exported pure `(a, b, t) => CheckboxStyle`. Asserts:
+ at t=0 all numeric fields equal `a`; at t=1 all equal `b`; at t=0.5 each
+ numeric field is the exact midpoint (checkOpacity 0→1 gives 0.5, checkScale
+ 0.6→1 gives 0.8, checkDraw 0→1 gives 0.5). `boxBackground` and
+ `boxBorderColor` at all t are non-empty strings (the oklch mix value is not
+ hardcoded).
+
+**Checkbox render** is a pure `(style | state) => visual` observable only via
+Remotion render, not unit-tested here.
+
+**`useCheckboxTransition`** reads `useCurrentFrame()` via `useStateTransition`
+inside the hook — that is correct and expected. It is not a render component;
+the smooth-path design isolates all frame-reading to the hook, keeping
+`Checkbox` pure.
+
+## Import strategy
+
+`checkbox.test.ts` imports via **relative paths** and the
+**`@/lib/remocn-ui` tsconfig alias**:
+
+- `../index` — relative, for `CheckboxState`, `checkboxStyle`, `checkboxStyleContext`
+- `../use-checkbox-transition` — relative, for `tweenCheckboxStyle`
+- `../config` — relative, for `checkboxConfig`
+- `@/lib/remocn-ui` — alias (resolves to `registry/remocn-ui/core/index.ts`),
+ for `defaultLightTheme`
+
+Importing `index.tsx` and `use-checkbox-transition.ts` pulls the `remotion`
+module (and React), but neither `checkboxStyle`, `checkboxStyleContext`, nor
+`tweenCheckboxStyle` call `useCurrentFrame()` at import time or at call time —
+they are pure value functions. `bun test` resolves tsconfig `paths`, so the
+alias works without additional config.
+
+## Determinism grep checklist (run manually; must print NOTHING)
+
+Checkbox is frame-free. The component must contain **none** of the following:
+
+```bash
+grep -nE "useCurrentFrame|useState|useEffect|onClick|onChange|addEventListener|Date\.now|Math\.random" \
+ registry/remocn-ui/checkbox/index.tsx
+```
+
+Expected: no output. Any match is a determinism violation.
+
+`use-checkbox-transition.ts` is the CALLER hook that intentionally reads
+`useCurrentFrame()` (via `useStateTransition`). It is not a render component;
+the smooth-path design isolates all frame-reading to the hook, keeping
+`Checkbox` pure.
+
+Tier-wide sweep:
+
+```bash
+grep -nE "useState|useEffect|onClick|onChange|addEventListener|Date\.now|Math\.random" \
+ registry/remocn-ui/checkbox/index.tsx registry/remocn-ui/core/*.ts
+```
diff --git a/registry/remocn-ui/checkbox/__tests__/checkbox.test.ts b/registry/remocn-ui/checkbox/__tests__/checkbox.test.ts
new file mode 100644
index 00000000..f87bb4be
--- /dev/null
+++ b/registry/remocn-ui/checkbox/__tests__/checkbox.test.ts
@@ -0,0 +1,396 @@
+/**
+ * Verification tests for the PURE / DETERMINISTIC parts of `checkbox`.
+ *
+ * Scope:
+ * - registry/remocn-ui/checkbox/index.tsx — CheckboxState union membership,
+ * checkboxStyleContext, checkboxStyle presets
+ * - registry/remocn-ui/checkbox/use-checkbox-transition.ts — tweenCheckboxStyle
+ * - registry/remocn-ui/checkbox/config.ts — checkboxConfig.controls.state
+ * wiring + checkboxConfig.snippet output (the state → JSX codegen)
+ *
+ * The render path (index.tsx) is a PURE-STATE model: `(state) => visual`.
+ * State changes snap (no tweening inside the component). The smooth-path hook
+ * `useCheckboxTransition` reads `useCurrentFrame()` via `useStateTransition`
+ * internally; it cannot run outside a Remotion render tree. So Checkbox render
+ * is NOT exercised here. The pure-testable surface is the customizer wiring,
+ * snippet codegen, style presets, and tween interpolation (below).
+ *
+ * Runner: Bun's built-in test runner (TypeScript-native, no framework dep).
+ * bun test registry/remocn-ui/checkbox/__tests__
+ *
+ * --------------------------------------------------------------------------
+ * IMPORT STRATEGY
+ * --------------------------------------------------------------------------
+ * `config.ts` imports `CheckboxState` from `@/registry/remocn-ui/checkbox`
+ * and the pieces under test never CALL a Remotion runtime API at import time —
+ * `checkboxConfig` is a plain object; `.snippet` is a pure string builder;
+ * `checkboxStyle` and `tweenCheckboxStyle` are pure value functions.
+ * We import via RELATIVE paths (matching the existing test suite pattern),
+ * annotating each import with the source it corresponds to.
+ * --------------------------------------------------------------------------
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+ type CheckboxState,
+ checkboxStyle,
+ checkboxStyleContext,
+} from "../index";
+import { tweenCheckboxStyle } from "../use-checkbox-transition";
+import { checkboxConfig } from "../config";
+import { defaultLightTheme } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Shared fixtures
+// ===========================================================================
+
+/**
+ * The CheckboxState union, enumerated as a runtime list for membership checks.
+ * Must stay in sync with `export type CheckboxState` in index.tsx.
+ */
+const VALID_STATES: readonly CheckboxState[] = ["unchecked", "checked"];
+
+/** Minimal shape mirroring the customizer's value bag passed to snippet(). */
+type SnippetValues = {
+ state?: string;
+ label?: string;
+ size?: string;
+ mode?: string;
+ primary?: string;
+};
+
+const snippet = (values: SnippetValues): string =>
+ checkboxConfig.snippet(values as Record<string, unknown>);
+
+// ===========================================================================
+// 1. CheckboxState union membership
+// ===========================================================================
+
+describe("CheckboxState union", () => {
+ it("contains exactly the two documented states", () => {
+ // We can't enumerate a TS type at runtime, but we can assert the REAL
+ // controls.state options match and that all known states are members.
+ const control = checkboxConfig.controls.state;
+ if (control.type !== "select") throw new Error("state control must be a select");
+ expect(control.options).toEqual(["unchecked", "checked"]);
+ });
+
+ it("every VALID_STATES entry is assignable (no typos in the fixture)", () => {
+ // Belt-and-suspenders: the fixture array must have exactly 2 entries and
+ // match the options list from the real config.
+ const control = checkboxConfig.controls.state;
+ if (control.type !== "select") throw new Error("state control must be a select");
+ expect(VALID_STATES).toHaveLength(2);
+ for (const s of VALID_STATES) {
+ expect(control.options).toContain(s);
+ }
+ });
+});
+
+// ===========================================================================
+// 2. checkboxConfig.controls.state — customizer control wiring
+// ===========================================================================
+
+describe("checkboxConfig.controls.state", () => {
+ it("is a select control", () => {
+ expect(checkboxConfig.controls.state.type).toBe("select");
+ });
+
+ it("has exactly the two CheckboxState options in order", () => {
+ const control = checkboxConfig.controls.state;
+ if (control.type !== "select") throw new Error("state control must be a select");
+ expect(control.options).toEqual(["unchecked", "checked"]);
+ });
+
+ it("defaults to 'checked' so the preview shows the filled box and checkmark", () => {
+ const control = checkboxConfig.controls.state;
+ expect(control.default).toBe("checked");
+ });
+
+ it("every option is a member of the CheckboxState union", () => {
+ const control = checkboxConfig.controls.state;
+ if (control.type !== "select") throw new Error("state control must be a select");
+ for (const option of control.options) {
+ expect(VALID_STATES).toContain(option as CheckboxState);
+ }
+ });
+});
+
+// ===========================================================================
+// 3. checkboxConfig.snippet — pure string builder
+// State model: snippet emits `state="<state>"` as a bare JSX prop.
+// It NEVER emits `steps` or `action`.
+// ===========================================================================
+
+describe("checkboxConfig.snippet: state prop emission", () => {
+ it("emits state=\"unchecked\" for the unchecked option", () => {
+ expect(snippet({ state: "unchecked" })).toContain('state="unchecked"');
+ });
+
+ it("emits state=\"checked\" for the checked option", () => {
+ expect(snippet({ state: "checked" })).toContain('state="checked"');
+ });
+
+ it("emits the correct state for every control option", () => {
+ const control = checkboxConfig.controls.state;
+ if (control.type !== "select") throw new Error("state control must be a select");
+ for (const state of control.options) {
+ const out = snippet({ state });
+ expect(out).toContain(`state="${state}"`);
+ }
+ });
+});
+
+describe("checkboxConfig.snippet: NEVER emits steps or action", () => {
+ it("never emits `steps` in any state", () => {
+ for (const state of VALID_STATES) {
+ expect(snippet({ state })).not.toContain("steps");
+ }
+ });
+
+ it("never emits `action` in any state", () => {
+ for (const state of VALID_STATES) {
+ expect(snippet({ state })).not.toContain("action");
+ }
+ });
+});
+
+describe("checkboxConfig.snippet: import line", () => {
+ it("includes `import { Checkbox }` from the correct path", () => {
+ const out = snippet({ state: "checked" });
+ expect(out).toContain('import { Checkbox }');
+ expect(out).toContain('from "@/components/remocn/checkbox"');
+ });
+});
+
+describe("checkboxConfig.snippet: default props are omitted", () => {
+ // Defaults: label="", size=default, mode=light, primary=#171717
+ const allDefaults = snippet({
+ state: "checked",
+ label: "",
+ size: "default",
+ mode: "light",
+ primary: "#171717",
+ });
+
+ it("omits label when it equals the default (empty string)", () => {
+ expect(allDefaults).not.toContain("label=");
+ });
+
+ it("omits size when it equals the default 'default'", () => {
+ expect(allDefaults).not.toContain("size=");
+ });
+
+ it("omits mode when it equals the default 'light'", () => {
+ expect(allDefaults).not.toContain("mode=");
+ });
+
+ it("omits primary when it equals the default '#171717'", () => {
+ expect(allDefaults).not.toContain("primary=");
+ });
+});
+
+describe("checkboxConfig.snippet: non-default props are emitted", () => {
+ it("emits a non-default label", () => {
+ expect(snippet({ state: "checked", label: "Accept terms" })).toContain('label="Accept terms"');
+ });
+
+ it("emits a non-default size", () => {
+ expect(snippet({ state: "checked", size: "lg" })).toContain('size="lg"');
+ });
+
+ it("emits a non-default mode", () => {
+ expect(snippet({ state: "checked", mode: "dark" })).toContain('mode="dark"');
+ });
+
+ it("emits a non-default primary color", () => {
+ expect(snippet({ state: "checked", primary: "#6366f1" })).toContain('primary="#6366f1"');
+ });
+});
+
+describe("checkboxConfig.snippet: structural round-trip", () => {
+ const out = snippet({ state: "checked" });
+
+ it("starts with the import line", () => {
+ expect(out.startsWith('import { Checkbox }')).toBe(true);
+ });
+
+ it("contains a <Checkbox JSX opening", () => {
+ expect(out).toContain("<Checkbox");
+ });
+
+ it("ends with a self-closing />", () => {
+ expect(out.trimEnd().endsWith("/>")).toBe(true);
+ });
+});
+
+// ===========================================================================
+// 4. checkboxStyle presets — pure (state, ctx) => CheckboxStyle
+// checkboxStyleContext and checkboxStyle are now exported and frame-free.
+// Build one ctx from the default light theme, then assert the
+// numeric/opacity invariants for both states.
+// boxBackground and boxBorderColor are derived oklch strings — asserted
+// non-empty only (exact value is an implementation detail of the theme).
+// ===========================================================================
+
+const ctx = checkboxStyleContext(defaultLightTheme);
+
+describe("checkboxStyle: unchecked state", () => {
+ const s = checkboxStyle("unchecked", ctx);
+
+ it("checkOpacity is 0 (check hidden)", () => {
+ expect(s.checkOpacity).toBe(0);
+ });
+
+ it("checkScale is 0.6 (slight shrink, pre-pop position)", () => {
+ expect(s.checkScale).toBeCloseTo(0.6, 10);
+ });
+
+ it("checkDraw is 0 (stroke not drawn)", () => {
+ expect(s.checkDraw).toBe(0);
+ });
+
+ it("boxBackground is a non-empty string", () => {
+ expect(typeof s.boxBackground).toBe("string");
+ expect(s.boxBackground.length).toBeGreaterThan(0);
+ });
+
+ it("boxBorderColor is a non-empty string", () => {
+ expect(typeof s.boxBorderColor).toBe("string");
+ expect(s.boxBorderColor.length).toBeGreaterThan(0);
+ });
+});
+
+describe("checkboxStyle: checked state", () => {
+ const s = checkboxStyle("checked", ctx);
+
+ it("checkOpacity is 1 (check fully visible)", () => {
+ expect(s.checkOpacity).toBe(1);
+ });
+
+ it("checkScale is 1 (full size, post-pop)", () => {
+ expect(s.checkScale).toBe(1);
+ });
+
+ it("checkDraw is 1 (stroke fully drawn)", () => {
+ expect(s.checkDraw).toBe(1);
+ });
+
+ it("boxBackground is a non-empty string", () => {
+ expect(typeof s.boxBackground).toBe("string");
+ expect(s.boxBackground.length).toBeGreaterThan(0);
+ });
+
+ it("boxBorderColor is a non-empty string", () => {
+ expect(typeof s.boxBorderColor).toBe("string");
+ expect(s.boxBorderColor.length).toBeGreaterThan(0);
+ });
+});
+
+describe("checkboxStyle: invariants — unchecked hides mark, checked shows mark", () => {
+ it("unchecked has checkOpacity 0 and checkDraw 0", () => {
+ const s = checkboxStyle("unchecked", ctx);
+ expect(s.checkOpacity).toBe(0);
+ expect(s.checkDraw).toBe(0);
+ });
+
+ it("checked has checkOpacity 1 and checkDraw 1", () => {
+ const s = checkboxStyle("checked", ctx);
+ expect(s.checkOpacity).toBe(1);
+ expect(s.checkDraw).toBe(1);
+ });
+});
+
+// ===========================================================================
+// 5. tweenCheckboxStyle — pure linear interpolation between two CheckboxStyles.
+// Numbers lerp linearly; colors via oklch mix → non-empty string at all t.
+// Concrete expectations: unchecked→checked for midpoint math.
+// unchecked: checkOpacity=0, checkScale=0.6, checkDraw=0
+// checked: checkOpacity=1, checkScale=1, checkDraw=1
+// ===========================================================================
+
+describe("tweenCheckboxStyle: t=0 returns values equal to `a`", () => {
+ const a = checkboxStyle("unchecked", ctx);
+ const b = checkboxStyle("checked", ctx);
+ const r = tweenCheckboxStyle(a, b, 0);
+
+ it("checkOpacity equals a.checkOpacity at t=0", () => {
+ expect(r.checkOpacity).toBeCloseTo(a.checkOpacity, 10);
+ });
+
+ it("checkScale equals a.checkScale at t=0", () => {
+ expect(r.checkScale).toBeCloseTo(a.checkScale, 10);
+ });
+
+ it("checkDraw equals a.checkDraw at t=0", () => {
+ expect(r.checkDraw).toBeCloseTo(a.checkDraw, 10);
+ });
+
+ it("boxBackground is a non-empty string at t=0", () => {
+ expect(typeof r.boxBackground).toBe("string");
+ expect(r.boxBackground.length).toBeGreaterThan(0);
+ });
+
+ it("boxBorderColor is a non-empty string at t=0", () => {
+ expect(typeof r.boxBorderColor).toBe("string");
+ expect(r.boxBorderColor.length).toBeGreaterThan(0);
+ });
+});
+
+describe("tweenCheckboxStyle: t=1 returns values equal to `b`", () => {
+ const a = checkboxStyle("unchecked", ctx);
+ const b = checkboxStyle("checked", ctx);
+ const r = tweenCheckboxStyle(a, b, 1);
+
+ it("checkOpacity equals b.checkOpacity at t=1", () => {
+ expect(r.checkOpacity).toBeCloseTo(b.checkOpacity, 10);
+ });
+
+ it("checkScale equals b.checkScale at t=1", () => {
+ expect(r.checkScale).toBeCloseTo(b.checkScale, 10);
+ });
+
+ it("checkDraw equals b.checkDraw at t=1", () => {
+ expect(r.checkDraw).toBeCloseTo(b.checkDraw, 10);
+ });
+
+ it("boxBackground is a non-empty string at t=1", () => {
+ expect(typeof r.boxBackground).toBe("string");
+ expect(r.boxBackground.length).toBeGreaterThan(0);
+ });
+
+ it("boxBorderColor is a non-empty string at t=1", () => {
+ expect(typeof r.boxBorderColor).toBe("string");
+ expect(r.boxBorderColor.length).toBeGreaterThan(0);
+ });
+});
+
+describe("tweenCheckboxStyle: t=0.5 midpoint numeric lerp (unchecked → checked)", () => {
+ // unchecked: checkOpacity=0, checkScale=0.6, checkDraw=0
+ // checked: checkOpacity=1, checkScale=1, checkDraw=1
+ const a = checkboxStyle("unchecked", ctx);
+ const b = checkboxStyle("checked", ctx);
+ const r = tweenCheckboxStyle(a, b, 0.5);
+
+ it("checkOpacity midpoint: 0 → 1 gives 0.5", () => {
+ expect(r.checkOpacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("checkScale midpoint: 0.6 → 1 gives 0.8", () => {
+ expect(r.checkScale).toBeCloseTo(0.8, 10);
+ });
+
+ it("checkDraw midpoint: 0 → 1 gives 0.5", () => {
+ expect(r.checkDraw).toBeCloseTo(0.5, 10);
+ });
+
+ it("boxBackground is a non-empty string at t=0.5", () => {
+ expect(typeof r.boxBackground).toBe("string");
+ expect(r.boxBackground.length).toBeGreaterThan(0);
+ });
+
+ it("boxBorderColor is a non-empty string at t=0.5", () => {
+ expect(typeof r.boxBorderColor).toBe("string");
+ expect(r.boxBorderColor.length).toBeGreaterThan(0);
+ });
+});
diff --git a/registry/remocn-ui/checkbox/config.ts b/registry/remocn-ui/checkbox/config.ts
new file mode 100644
index 00000000..ca6b2c4a
--- /dev/null
+++ b/registry/remocn-ui/checkbox/config.ts
@@ -0,0 +1,57 @@
+import { type ComponentConfig, FPS, H, W } from "@/lib/customizer-config";
+import type { CheckboxState } from "@/registry/remocn-ui/checkbox";
+
+export const checkboxConfig: ComponentConfig = {
+ componentName: "Checkbox",
+ importPath: "@/components/remocn/checkbox",
+ controls: {
+ label: { type: "text", default: "", label: "Label" },
+ size: {
+ type: "select",
+ default: "default",
+ options: ["sm", "default", "lg"],
+ label: "Size",
+ },
+ state: {
+ type: "select",
+ // Default to `checked` so the preview shows the filled box + checkmark.
+ default: "checked",
+ options: ["unchecked", "checked"],
+ label: "State",
+ },
+ mode: {
+ type: "select",
+ default: "light",
+ options: ["light", "dark"],
+ label: "Mode",
+ },
+ primary: { type: "color", default: "#171717", label: "Primary" },
+ },
+ durationInFrames: 120,
+ fps: FPS,
+ compositionWidth: W,
+ compositionHeight: H,
+ snippet: (values) => {
+ const state = (values.state as CheckboxState) ?? "checked";
+ const label = values.label as string | undefined;
+ const size = values.size as string | undefined;
+ const mode = values.mode as string | undefined;
+ const primary = values.primary as string | undefined;
+
+ const props: string[] = [` state="${state}"`];
+ if (label !== undefined && label !== "")
+ props.push(` label="${label}"`);
+ if (size !== undefined && size !== "default")
+ props.push(` size="${size}"`);
+ if (mode !== undefined && mode !== "light")
+ props.push(` mode="${mode}"`);
+ if (primary !== undefined && primary !== "#171717")
+ props.push(` primary="${primary}"`);
+
+ return `import { Checkbox } from "@/components/remocn/checkbox";
+
+<Checkbox
+${props.join("\n")}
+/>`;
+ },
+};
diff --git a/registry/remocn-ui/checkbox/index.tsx b/registry/remocn-ui/checkbox/index.tsx
new file mode 100644
index 00000000..924b43b6
--- /dev/null
+++ b/registry/remocn-ui/checkbox/index.tsx
@@ -0,0 +1,202 @@
+"use client";
+
+import { type RemocnTheme, useRemocnTheme } from "@/lib/remocn-ui";
+
+export type CheckboxState = "unchecked" | "checked";
+
+type CheckboxSize = "sm" | "default" | "lg";
+
+export interface CheckboxProps {
+ /** Current visual state (snap path). State changes snap (no enter-tweens). */
+ state?: CheckboxState;
+ /**
+ * Resolved animated visual (smooth path). When provided, takes precedence over
+ * `state` — feed it an interpolated `CheckboxStyle` from `useCheckboxTransition`.
+ */
+ style?: CheckboxStyle;
+ /** Optional text label rendered next to the box. */
+ label?: string;
+ size?: CheckboxSize;
+ theme?: Partial<RemocnTheme>;
+ /** Convenience override for the `primary` theme token — merged into `theme`. */
+ primary?: string;
+ mode?: "light" | "dark";
+ className?: string;
+}
+
+/** Checkmark stroke length (svg path units), drives the draw-on animation. */
+const CHECK_PATH_LENGTH = 14;
+
+const SIZE_STYLES: Record<
+ CheckboxSize,
+ { box: number; fontSize: number; gap: number }
+> = {
+ sm: { box: 16, fontSize: 13, gap: 8 },
+ default: { box: 20, fontSize: 15, gap: 10 },
+ lg: { box: 24, fontSize: 17, gap: 12 },
+};
+
+// ===========================================================================
+// Checkbox visual — the COMPLETE animated look for a moment in time. A `state`
+// is a named preset of this visual (`checkboxStyle`); the smooth path feeds an
+// interpolated `CheckboxStyle` straight through. The component is a pure
+// renderer of whichever `CheckboxStyle` it receives.
+// ===========================================================================
+
+export interface CheckboxStyle {
+ /** Animated box fill color (a concrete color, never "transparent"). */
+ boxBackground: string;
+ /** Animated box border color. */
+ boxBorderColor: string;
+ /** Checkmark opacity 0→1. */
+ checkOpacity: number;
+ /** Checkmark scale 0.6→1 (a slight pop on check). */
+ checkScale: number;
+ /** Checkmark draw fraction 0→1; drives the strokeDashoffset of the path. */
+ checkDraw: number;
+}
+
+/** Concrete colors for the active theme, resolved once per render. */
+export interface CheckboxStyleContext {
+ uncheckedBg: string;
+ checkedBg: string;
+ uncheckedBorder: string;
+ checkedBorder: string;
+ /** Static checkmark stroke color (never animated). */
+ checkColor: string;
+}
+
+/**
+ * Derive the concrete colors for a theme. Pure — call it once and reuse the
+ * result for every `checkboxStyle(state, ctx)` preset.
+ */
+export function checkboxStyleContext(theme: RemocnTheme): CheckboxStyleContext {
+ return {
+ uncheckedBg: theme.background,
+ checkedBg: theme.primary,
+ uncheckedBorder: theme.border,
+ checkedBorder: theme.primary,
+ checkColor: theme.primaryForeground,
+ };
+}
+
+/**
+ * The COMPLETE resting visual for a state — a pure `(state, ctx) => CheckboxStyle`
+ * map. To change how a state looks, edit one entry.
+ */
+export function checkboxStyle(
+ state: CheckboxState,
+ ctx: CheckboxStyleContext,
+): CheckboxStyle {
+ switch (state) {
+ case "checked":
+ return {
+ boxBackground: ctx.checkedBg,
+ boxBorderColor: ctx.checkedBorder,
+ checkOpacity: 1,
+ checkScale: 1,
+ checkDraw: 1,
+ };
+ default:
+ return {
+ boxBackground: ctx.uncheckedBg,
+ boxBorderColor: ctx.uncheckedBorder,
+ checkOpacity: 0,
+ checkScale: 0.6,
+ checkDraw: 0,
+ };
+ }
+}
+
+export function Checkbox({
+ state = "unchecked",
+ style,
+ label,
+ size = "default",
+ theme: themeOverride,
+ primary,
+ mode,
+ className,
+}: CheckboxProps) {
+ const theme = useRemocnTheme(
+ { ...themeOverride, ...(primary ? { primary } : {}) },
+ mode,
+ );
+
+ const sizeStyle = SIZE_STYLES[size];
+ const ctx = checkboxStyleContext(theme);
+ const v = style ?? checkboxStyle(state, ctx);
+ const boxSize = sizeStyle.box;
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ background: theme.background,
+ fontFamily:
+ "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif",
+ }}
+ >
+ <span
+ className={className}
+ style={{
+ display: "inline-flex",
+ alignItems: "center",
+ gap: sizeStyle.gap,
+ }}
+ >
+ {/* The box — animated fill + border; the checkmark draws on inside it. */}
+ <span
+ style={{
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ width: boxSize,
+ height: boxSize,
+ borderRadius: Math.round(boxSize * 0.28),
+ border: `1px solid ${v.boxBorderColor}`,
+ background: v.boxBackground,
+ }}
+ >
+ <svg
+ width={boxSize}
+ height={boxSize}
+ viewBox="0 0 24 24"
+ fill="none"
+ style={{
+ opacity: v.checkOpacity,
+ transform: `scale(${v.checkScale})`,
+ }}
+ >
+ <path
+ d="M5 12.5l4.5 4.5L19 7"
+ stroke={ctx.checkColor}
+ strokeWidth="2.6"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ pathLength={CHECK_PATH_LENGTH}
+ strokeDasharray={CHECK_PATH_LENGTH}
+ strokeDashoffset={CHECK_PATH_LENGTH * (1 - v.checkDraw)}
+ />
+ </svg>
+ </span>
+ {label !== undefined && (
+ <span
+ style={{
+ fontSize: sizeStyle.fontSize,
+ fontWeight: 500,
+ letterSpacing: "-0.01em",
+ color: theme.foreground,
+ }}
+ >
+ {label}
+ </span>
+ )}
+ </span>
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/checkbox/use-checkbox-transition.ts b/registry/remocn-ui/checkbox/use-checkbox-transition.ts
new file mode 100644
index 00000000..afec9996
--- /dev/null
+++ b/registry/remocn-ui/checkbox/use-checkbox-transition.ts
@@ -0,0 +1,74 @@
+"use client";
+
+import {
+ easings,
+ mixOklch,
+ type RemocnTheme,
+ type Step,
+ useRemocnTheme,
+ useStateTransition,
+} from "@/lib/remocn-ui";
+import {
+ checkboxStyle,
+ checkboxStyleContext,
+ type CheckboxState,
+ type CheckboxStyle,
+} from "@/components/remocn/checkbox";
+// ^ install path; resolves in-repo via the @/components/remocn/* tsconfig alias.
+
+/** Default transition length (frames) when a step omits `duration`. Tune to taste. */
+export const DEFAULT_DURATION = 10;
+
+/** Blend two checkbox visuals: numbers lerp, colors via oklch mix. */
+export function tweenCheckboxStyle(
+ a: CheckboxStyle,
+ b: CheckboxStyle,
+ t: number,
+): CheckboxStyle {
+ return {
+ boxBackground: mixOklch(a.boxBackground, b.boxBackground, t),
+ boxBorderColor: mixOklch(a.boxBorderColor, b.boxBorderColor, t),
+ checkOpacity: a.checkOpacity + (b.checkOpacity - a.checkOpacity) * t,
+ checkScale: a.checkScale + (b.checkScale - a.checkScale) * t,
+ checkDraw: a.checkDraw + (b.checkDraw - a.checkDraw) * t,
+ };
+}
+
+export interface CheckboxTransitionOptions {
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ primary?: string;
+ speed?: number;
+ defaultDuration?: number;
+}
+
+/**
+ * Timeline → resolved (eased, tweened) CheckboxStyle. The CALLER invokes this;
+ * it reads the frame, the `<Checkbox>` component does not. Feed the result to
+ * `<Checkbox style={...} />` for smooth check/uncheck transitions.
+ */
+export function useCheckboxTransition(
+ steps: Step<CheckboxState>[],
+ opts: CheckboxTransitionOptions = {},
+): CheckboxStyle {
+ const {
+ theme: themeOverride,
+ mode,
+ primary,
+ speed = 1,
+ defaultDuration = DEFAULT_DURATION,
+ } = opts;
+ const theme = useRemocnTheme(
+ { ...themeOverride, ...(primary ? { primary } : {}) },
+ mode,
+ );
+ const ctx = checkboxStyleContext(theme);
+ const { from, to, progress } = useStateTransition(
+ steps,
+ "unchecked",
+ speed,
+ defaultDuration,
+ );
+ const t = easings.out(progress);
+ return tweenCheckboxStyle(checkboxStyle(from, ctx), checkboxStyle(to, ctx), t);
+}
diff --git a/registry/remocn-ui/registry.json b/registry/remocn-ui/registry.json
index a963dd8f..2b96ad07 100644
--- a/registry/remocn-ui/registry.json
+++ b/registry/remocn-ui/registry.json
@@ -116,6 +116,26 @@
"target": "components/remocn/use-alert-dialog-transition.ts"
}
]
+ },
+ {
+ "name": "checkbox",
+ "type": "registry:component",
+ "title": "UI Checkbox",
+ "description": "A checkbox whose checked/unchecked state is a pure function of the timeline; the box fill, border, and checkmark draw are keyframed presets.",
+ "dependencies": ["remotion"],
+ "registryDependencies": ["remocn-ui"],
+ "files": [
+ {
+ "path": "checkbox/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/checkbox.tsx"
+ },
+ {
+ "path": "checkbox/use-checkbox-transition.ts",
+ "type": "registry:component",
+ "target": "components/remocn/use-checkbox-transition.ts"
+ }
+ ]
}
]
}