Skip to content

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

feat: added toast notification

dev_wandry38673e206e4d
diff --git a/components/docs/examples/cursor-example.tsx b/components/docs/examples/cursor-example.tsx
index ef7a0d69..7dbe6598 100644
--- a/components/docs/examples/cursor-example.tsx
+++ b/components/docs/examples/cursor-example.tsx
@@ -5,8 +5,8 @@ import { useCursorPath } from "@/registry/remocn-ui/cursor/use-cursor-path";
import { Button } from "@/registry/remocn-ui/button";
import { useButtonTransition } from "@/registry/remocn-ui/button/use-button-transition";
-const BTN_X = 620; // button tip X (center of button, cursor arrives here)
-const BTN_Y = 360; // button tip Y
+const BTN_X = 620; // cursor tip target X (the pointer hotspot lands here)
+const BTN_Y = 360; // cursor tip target Y
export const CursorExampleScene = () => {
const cursorStyle = useCursorPath([
@@ -16,10 +16,10 @@ export const CursorExampleScene = () => {
]);
const buttonStyle = useButtonTransition([
- { at: 45, state: "hover", duration: 16 },
- { at: 73, state: "press", duration: 8 },
- { at: 81, state: "loading", duration: 6 },
- { at: 113, state: "success", duration: 16 },
+ { at: 40, state: "hover", duration: 16 },
+ { at: 68, state: "press", duration: 8 },
+ { at: 76, state: "loading", duration: 6 },
+ { at: 108, state: "success", duration: 16 },
]);
return (
diff --git a/components/docs/examples/index.tsx b/components/docs/examples/index.tsx
index c989b555..77f14846 100644
--- a/components/docs/examples/index.tsx
+++ b/components/docs/examples/index.tsx
@@ -26,6 +26,7 @@ import {
} from "./dropdown-menu-example";
import { TabsExampleScene, tabsExampleCode } from "./tabs-example";
import { CursorExampleScene, cursorExampleCode } from "./cursor-example";
+import { ToastExampleScene, toastExampleCode } from "./toast-example";
export interface ExampleEntry {
Component: ComponentType;
@@ -158,4 +159,13 @@ export const examples: Record<string, ExampleEntry> = {
width: W,
height: H,
},
+ "toast-example": {
+ Component: ToastExampleScene,
+ code: toastExampleCode,
+ // Toast dismiss completes at 144 + dur 12 = 156; a short settle then loop.
+ durationInFrames: 170,
+ fps: FPS,
+ width: W,
+ height: H,
+ },
};
diff --git a/components/docs/examples/toast-example.tsx b/components/docs/examples/toast-example.tsx
new file mode 100644
index 00000000..fbbd092b
--- /dev/null
+++ b/components/docs/examples/toast-example.tsx
@@ -0,0 +1,129 @@
+"use client";
+
+import { Cursor } from "@/registry/remocn-ui/cursor";
+import { useCursorPath } from "@/registry/remocn-ui/cursor/use-cursor-path";
+import { Button } from "@/registry/remocn-ui/button";
+import { useButtonTransition } from "@/registry/remocn-ui/button/use-button-transition";
+import { Toast } from "@/registry/remocn-ui/toast";
+import { useToastTransition } from "@/registry/remocn-ui/toast/use-toast-transition";
+
+// Button is centered in the preview canvas; cursor starts top-left and clicks it.
+const BTN_X = 620; // cursor tip target X (the pointer hotspot lands here)
+const BTN_Y = 360; // cursor tip target Y
+
+export const ToastExampleScene = () => {
+ // Cursor: park top-left → ease onto button (arrives 40) → click at 68.
+ const cursorStyle = useCursorPath([
+ { at: 0, x: 80, y: 60 },
+ { at: 40, x: BTN_X, y: BTN_Y, duration: 28 },
+ { at: 68, x: BTN_X, y: BTN_Y, click: true, duration: 0 },
+ ]);
+
+ // Button: idle → hover (cursor on button) → press → idle after click.
+ // The click lands at 68; press starts just before so the dip is visible.
+ const buttonStyle = useButtonTransition([
+ { at: 40, state: "hover", duration: 16 },
+ { at: 62, state: "press", duration: 8 },
+ { at: 76, state: "idle", duration: 10 },
+ ]);
+
+ // Toast: slides in from below right after the click, holds ~60 frames, then
+ // auto-dismisses. DEFAULT_DURATION is 12; explicit durations here are clear.
+ const toastStyle = useToastTransition([
+ { at: 84, state: "visible", duration: 12 },
+ { at: 144, state: "hidden", duration: 12 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ {/* Button centered in canvas */}
+ <div
+ style={{
+ width: "100%",
+ position: "absolute",
+ left: "50%",
+ top: "50%",
+ transform: "translate(-50%, -50%)",
+ }}
+ >
+ <Button label="Show toast" style={buttonStyle} />
+ </div>
+
+ {/* Toast anchored bottom-right, 24px from edges */}
+ <div
+ style={{
+ position: "absolute",
+ right: 24,
+ bottom: 24,
+ }}
+ >
+ <Toast
+ title="Changes saved"
+ description="Your preferences have been updated."
+ variant="success"
+ style={toastStyle}
+ />
+ </div>
+
+ <Cursor style={cursorStyle} variant="pointer" />
+ </div>
+ );
+};
+
+export const toastExampleCode = `import { Cursor } from "@/components/remocn/cursor";
+import { useCursorPath } from "@/components/remocn/use-cursor-path";
+import { Button } from "@/components/remocn/button";
+import { useButtonTransition } from "@/components/remocn/use-button-transition";
+import { Toast } from "@/components/remocn/toast";
+import { useToastTransition } from "@/components/remocn/use-toast-transition";
+
+const BTN_X = 320;
+const BTN_Y = 180;
+
+export const Scene = () => {
+ // Cursor moves to the button and clicks it at frame 68.
+ const cursorStyle = useCursorPath([
+ { at: 0, x: 80, y: 60 },
+ { at: 40, x: BTN_X, y: BTN_Y, duration: 28 },
+ { at: 68, x: BTN_X, y: BTN_Y, click: true, duration: 0 },
+ ]);
+
+ // Button responds to the cursor: hover → press → back to idle.
+ const buttonStyle = useButtonTransition([
+ { at: 40, state: "hover", duration: 16 },
+ { at: 62, state: "press", duration: 8 },
+ { at: 76, state: "idle", duration: 10 },
+ ]);
+
+ // Toast slides in after the click, holds ~60 frames, then auto-dismisses.
+ const toastStyle = useToastTransition([
+ { at: 84, state: "visible", duration: 12 },
+ { at: 144, state: "hidden", duration: 12 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <div
+ style={{
+ position: "absolute",
+ left: "50%",
+ top: "50%",
+ transform: "translate(-50%, -50%)",
+ }}
+ >
+ <Button label="Show toast" style={buttonStyle} />
+ </div>
+
+ <div style={{ position: "absolute", right: 24, bottom: 24 }}>
+ <Toast
+ title="Changes saved"
+ description="Your preferences have been updated."
+ variant="success"
+ style={toastStyle}
+ />
+ </div>
+
+ <Cursor style={cursorStyle} variant="pointer" />
+ </div>
+ );
+};`;
diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.json
index e7024c1d..2c5cead1 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", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "radio", "select", "spinner", "switch", "tabs"]
+ "pages": ["accordion", "alert-dialog", "button", "checkbox", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "radio", "select", "spinner", "switch", "tabs", "toast"]
}
diff --git a/content/docs/ui/components/toast.mdx b/content/docs/ui/components/toast.mdx
new file mode 100644
index 00000000..7672adff
--- /dev/null
+++ b/content/docs/ui/components/toast.mdx
@@ -0,0 +1,170 @@
+---
+title: Toast
+description: A notification that slides in from below, holds, then auto-dismisses
+---
+
+<ComponentPreview name="toast" />
+
+A state atom whose appearance (`hidden`, `visible`) 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. The toast enters from 16 px below at 0.97 scale, fades and scales up to rest, then reverses on dismiss.
+
+## Installation
+
+<InstallBlock name="toast" />
+
+<Note>
+Installing `toast` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) via `registryDependencies` (`["remocn-ui"]`). You do not need to install it separately. Both `toast` (the renderer) and `use-toast-transition` (the hook) are copied into your project.
+</Note>
+
+## Example
+
+<LiveExample name="toast-example" />
+
+## States
+
+`ToastState` is:
+
+```ts
+type ToastState =
+ | "hidden" // opacity 0, translateY 16px, scale 0.97 — off-screen resting position
+ | "visible" // opacity 1, translateY 0, scale 1 — fully on-screen
+```
+
+`hidden` is the default. The toast enters from 16 px below the rest position so it appears to slide up from the bottom of the canvas. `visible` brings it to full opacity and 1:1 scale.
+
+## 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 { Toast } from "@/components/remocn/toast";
+
+export const Scene = () => (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <div style={{ position: "absolute", right: 24, bottom: 24 }}>
+ <Toast state="visible" title="Changes saved" variant="success" />
+ </div>
+ </div>
+);
+```
+
+To drive state from the timeline, use `useCurrentState`:
+
+```tsx
+import { useCurrentState } from "@/lib/remocn-ui";
+import { Toast } from "@/components/remocn/toast";
+
+export const Scene = () => {
+ const state = useCurrentState(
+ [
+ { at: 30, state: "visible" },
+ { at: 90, state: "hidden" },
+ ],
+ "hidden",
+ );
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <div style={{ position: "absolute", right: 24, bottom: 24 }}>
+ <Toast state={state} title="Changes saved" variant="success" />
+ </div>
+ </div>
+ );
+};
+```
+
+Each `at` is a **Sequence-local authored frame**. State persists between steps: `visible` at frame 30 keeps the toast on-screen until `hidden` fires at frame 90. See [Concepts](/docs/ui/concepts) for the full `useCurrentState` API.
+
+## Smooth transitions
+
+State changes via `state` snap with no cross-fade. For animated enter and dismiss, use `useToastTransition` from the copied `use-toast-transition.ts` file. It reads the frame, interpolates between state presets, and returns a resolved `ToastStyle` — pass it to the `style` prop:
+
+```tsx
+import { Toast } from "@/components/remocn/toast";
+import { useToastTransition } from "@/components/remocn/use-toast-transition";
+
+export const Scene = () => {
+ const style = useToastTransition([
+ { at: 30, state: "visible", duration: 12 },
+ { at: 90, state: "hidden", duration: 12 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <div style={{ position: "absolute", right: 24, bottom: 24 }}>
+ <Toast style={style} title="Changes saved" variant="success" />
+ </div>
+ </div>
+ );
+};
+```
+
+The `duration` field on each step overrides the file's `DEFAULT_DURATION` (= `12`) for that specific transition. To globally tune timing and easing, edit `use-toast-transition.ts` directly in your project — that file is yours (shadcn "own your code" philosophy).
+
+`style` takes precedence over `state` when both are provided.
+
+## Variants
+
+The `variant` prop changes the leading icon and its color. The body layout (title, optional description) is the same across all variants.
+
+```ts
+type ToastVariant =
+ | "default" // neutral info dot — muted-foreground color
+ | "success" // circled checkmark — green (oklch 0.6 0.17 150)
+ | "error" // circled exclamation — theme.destructive color
+```
+
+```tsx
+<Toast state="visible" title="All good" variant="success" />
+<Toast state="visible" title="Something failed" variant="error" />
+<Toast state="visible" title="Heads up" variant="default" />
+```
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "title",
+ type: "string",
+ description: "Primary message text. Always visible.",
+ },
+ {
+ name: "description",
+ type: "string",
+ description: "Secondary detail text rendered below the title. When omitted the icon and title are vertically centered.",
+ },
+ {
+ name: "variant",
+ type: "\"default\" | \"success\" | \"error\"",
+ default: "\"default\"",
+ description: "Changes the leading icon and its color. default shows a neutral info dot.",
+ },
+ {
+ name: "state",
+ type: "\"hidden\" | \"visible\"",
+ default: "\"hidden\"",
+ description: "Current visual state (snap path). State changes snap — no automatic cross-fade.",
+ },
+ {
+ name: "style",
+ type: "ToastStyle",
+ description: "Resolved animated visual (smooth path). Pass an interpolated ToastStyle from useToastTransition. Takes precedence over state when provided.",
+ },
+ {
+ 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 toast wrapper element.",
+ },
+ ]}
+/>
diff --git a/registry/__index__.tsx b/registry/__index__.tsx
index f889db4b..850e59fd 100644
--- a/registry/__index__.tsx
+++ b/registry/__index__.tsx
@@ -139,6 +139,8 @@ import { Tabs } from "@/registry/remocn-ui/tabs";
import { tabsConfig } from "@/registry/remocn-ui/tabs/config";
import { CursorPreview } from "@/registry/remocn-ui/cursor/preview";
import { cursorConfig } from "@/registry/remocn-ui/cursor/config";
+import { ToastPreview } from "@/registry/remocn-ui/toast/preview";
+import { toastConfig } from "@/registry/remocn-ui/toast/config";
import { ZoomThroughTransition } from "@/registry/remocn/zoom-through-transition";
import { zoomThroughTransitionConfig } from "@/registry/remocn/zoom-through-transition/config";
@@ -333,6 +335,10 @@ const registry: Record<string, RegistryEntry> = {
// cursor's customizer Component is the preview-only CursorPreview wrapper (it
// runs a fixed demo path through useCursorPath); the shipped Cursor is pure.
"cursor": { Component: CursorPreview, config: cursorConfig },
+ // toast's customizer Component is the preview-only ToastPreview wrapper (it
+ // centers the toast on a theme-background stage); the shipped Toast is a
+ // placement-agnostic card the caller positions.
+ "toast": { Component: ToastPreview, config: toastConfig },
"spinner": { Component: Spinner, config: spinnerConfig },
};
diff --git a/registry/remocn-ui/registry.json b/registry/remocn-ui/registry.json
index 97342847..2865f660 100644
--- a/registry/remocn-ui/registry.json
+++ b/registry/remocn-ui/registry.json
@@ -376,6 +376,26 @@
"target": "components/remocn/use-cursor-path.ts"
}
]
+ },
+ {
+ "name": "toast",
+ "type": "registry:component",
+ "title": "UI Toast",
+ "description": "A toast notification whose hidden/visible state is a pure function of the timeline. The Toast renderer is a pure function of a ToastStyle (opacity, translateY, scale); useToastTransition eases both the slide-in enter and the auto-dismiss exit. Variants default/success/error change the leading icon and its color.",
+ "dependencies": ["remotion"],
+ "registryDependencies": ["remocn-ui"],
+ "files": [
+ {
+ "path": "toast/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/toast.tsx"
+ },
+ {
+ "path": "toast/use-toast-transition.ts",
+ "type": "registry:component",
+ "target": "components/remocn/use-toast-transition.ts"
+ }
+ ]
}
]
}
diff --git a/registry/remocn-ui/toast/__tests__/README.md b/registry/remocn-ui/toast/__tests__/README.md
new file mode 100644
index 00000000..456fe636
--- /dev/null
+++ b/registry/remocn-ui/toast/__tests__/README.md
@@ -0,0 +1,143 @@
+# `toast` — verification tests
+
+Pure / deterministic verification for the `toast` component
+(`registry/remocn-ui/toast/`). 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:
+`toastStyle` presets, `toastStyleContext` icon-color derivation,
+`tweenToastStyle` interpolation, the `useToastTransition` pure resolver
+mirror, and `toastConfig` controls wiring + snippet codegen.
+
+## Animation model — state atom with smooth opt-in
+
+Toast follows the standard state-atom pattern (see STYLE-GUIDE §1):
+
+**Snap path** (`state?: ToastState` prop):
+`<Toast>` is a frame-free pure renderer. The `state` prop drives all visuals.
+Each state maps to a complete resting keyframe via the exported pure function
+`toastStyle(state) => ToastStyle`. State changes snap — no tweening inside
+the component.
+
+**Smooth path** (`style?: ToastStyle` prop):
+Callers opt in to smooth enter/dismiss by passing a pre-interpolated
+`ToastStyle` to the `style` prop. The caller — typically `useToastTransition`
+— reads `useCurrentFrame()` via `useStateTransition`, applies `easings.out`
+to the raw linear progress, and blends the two state presets via
+`tweenToastStyle(from, to, t)`. The `<Toast>` component remains frame-free;
+it renders whatever `ToastStyle` it receives.
+
+**No color tween:** `ToastStyle` carries only `opacity`, `translateY`, and
+`scale` — all numeric. There are no animated color channels, so
+`tweenToastStyle` is a simple three-field lerp with no `mixOklch` call.
+
+**Icon color** is a static-per-render derived from variant + theme via
+`toastStyleContext` — it does not animate.
+
+## 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/toast/__tests__
+```
+
+`toast.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 12 frames.
+
+- **`toastStyle` presets** — exported pure `(state) => ToastStyle`. Asserts
+ every field for every state: `hidden` gives `{opacity:0, translateY:16,
+ scale:0.97}`; `visible` gives `{opacity:1, translateY:0, scale:1}`. Also
+ asserts all fields are numeric for every state, and that the two states
+ have distinct values on every field (no silent identity).
+
+- **`toastStyleContext`** — exported pure `(variant, theme) => { iconColor }`.
+ Asserts: `default` variant returns `theme.mutedForeground`; `success`
+ returns the hardcoded `"oklch(0.6 0.17 150)"` regardless of theme; `error`
+ returns `theme.destructive` (varies between light/dark themes). Asserts
+ all variants produce a non-empty string iconColor.
+
+- **`tweenToastStyle`** — exported pure `(a, b, t) => ToastStyle`. Asserts:
+ at t=0 all three fields equal `a`; at t=1 all equal `b`; at t=0.5 each
+ field is the exact midpoint (`opacity` 0→1 gives 0.5, `translateY` 16→0
+ gives 8, `scale` 0.97→1 gives 0.985); at t=0.25 gives 0.25/12/0.9775;
+ identity case (a===b, any t) preserves all fields. Also covers the reverse
+ direction (visible→hidden dismiss).
+
+- **`useToastTransition` resolver replica** — `resolveToastTransition` mirrors
+ `use-toast-transition.ts` lines 47-60 with `raw` injected in place of
+ `useCurrentFrame()`. The replica re-derives only the logic BEYOND the core
+ `useStateTransition` (already tested in `core/__tests__/timeline.test.ts`);
+ the key additional contract is that `progress` is eased with `easings.out`
+ before the tween. Asserts: before any step → hidden style with both
+ endpoints `hidden`; exactly at a step boundary → progress=0 → t=out(0)=0
+ → style equals `hidden` keyframe; mid-window at raw=6/dur=12 (linear
+ progress=0.5) → t=out(0.5)=0.875 → opacity=0.875 (not linear 0.5);
+ translateY=2 (=16×(1−0.875)); scale=0.99625; past the window → fully
+ visible style; speed contract (speed=2 halves the raw frame to reach a
+ step).
+
+- **`toastConfig.controls`** — control wiring assertions: `state` is a
+ `select` with options `["hidden","visible"]` and default `"visible"`;
+ `variant` is a `select` with options `["default","success","error"]` and
+ default `"success"`; `mode` is a `select` with options `["light","dark"]`
+ and default `"light"`; `title` and `description` are `text` controls;
+ `title` default is `"Changes saved"`.
+
+- **`toastConfig.snippet`** — pure JSX string builder. Asserts: `import {
+ Toast }` from the correct path; `<Toast` element and closing `/>` always
+ present; `state` is always emitted; `title` is always emitted (it is a
+ required prop, including when equal to the default); non-default title
+ emits the provided string; default `variant="success"`, `mode="light"`, and
+ default description are omitted; non-default variant/mode/description are
+ emitted; all state options round-trip correctly.
+
+**Toast render** is a pure `(style | state) => visual` observable only via
+Remotion render; it is not unit-tested here.
+
+## Import strategy
+
+`toast.test.ts` imports via **relative paths** and the `@/lib/remocn-ui`
+alias:
+
+- `../index` — relative, for `toastStyle`, `toastStyleContext`, `ToastState`,
+ `ToastVariant`
+- `../use-toast-transition` — relative, for `tweenToastStyle`,
+ `DEFAULT_DURATION`
+- `../config` — relative, for `toastConfig`
+- `@/lib/remocn-ui` — alias, for `defaultLightTheme`, `defaultDarkTheme`,
+ `easings`, `clamp01`, and `Step` type
+
+`useToastTransition` is NOT imported — it calls `useStateTransition` which
+reads `useCurrentFrame()`. Its pure logic is mirrored as `resolveToastTransition`
+with the frame injected as `raw`. `bun test` resolves tsconfig `paths`, so
+the alias works without additional config.
+
+## Determinism grep checklist (run manually; must print NOTHING)
+
+`toast/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/toast/index.tsx
+```
+
+Expected: **no output**. Any match is a determinism violation.
+
+`use-toast-transition.ts` is the caller hook that intentionally reads
+`useCurrentFrame()` (via `useStateTransition`). That is correct and expected;
+the smooth-path design isolates all frame-reading to the hook, keeping
+`<Toast>` pure.
+
+Tier-wide sweep for `index.tsx`:
+
+```bash
+grep -nE "useState|useEffect|onClick|onChange|addEventListener|Date\.now|Math\.random" \
+ registry/remocn-ui/toast/index.tsx registry/remocn-ui/core/*.ts
+```
diff --git a/registry/remocn-ui/toast/__tests__/toast.test.ts b/registry/remocn-ui/toast/__tests__/toast.test.ts
new file mode 100644
index 00000000..3822b103
--- /dev/null
+++ b/registry/remocn-ui/toast/__tests__/toast.test.ts
@@ -0,0 +1,697 @@
+/**
+ * Verification tests for the PURE / DETERMINISTIC parts of `toast`.
+ *
+ * Scope:
+ * - registry/remocn-ui/toast/index.tsx
+ * toastStyleContext(variant, theme) — pure icon-color derivation
+ * toastStyle(state) — complete state→visual preset map
+ * - registry/remocn-ui/toast/use-toast-transition.ts
+ * tweenToastStyle(a, b, t) — pure lerp across every field
+ * DEFAULT_DURATION constant
+ * useToastTransition resolver — mirrored as resolveToastTransition
+ * with frame injected as `raw` (annotated source lines)
+ * - registry/remocn-ui/toast/config.ts
+ * toastConfig.controls wiring + toastConfig.snippet codegen
+ *
+ * The render path (index.tsx) imports `useRemocnTheme` which requires React
+ * context — it is NOT exercised here. The pure-testable surface is everything
+ * above.
+ *
+ * Runner: Bun's built-in test runner (TypeScript-native, no framework dep).
+ * bun test registry/remocn-ui/toast/__tests__
+ *
+ * --------------------------------------------------------------------------
+ * IMPORT STRATEGY
+ * --------------------------------------------------------------------------
+ * Relative imports from component source; `@/lib/remocn-ui` alias for core.
+ * Neither `toastStyle`, `toastStyleContext`, nor `tweenToastStyle` call
+ * `useCurrentFrame()` at import or call time — they are pure value functions.
+ * `useToastTransition` IS a hook (calls `useStateTransition` → `useCurrentFrame`)
+ * and is NOT imported; we mirror its pure resolver body below.
+ * --------------------------------------------------------------------------
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+ toastStyle,
+ toastStyleContext,
+ type ToastState,
+ type ToastVariant,
+} from "../index";
+import {
+ tweenToastStyle,
+ DEFAULT_DURATION,
+} from "../use-toast-transition";
+import { toastConfig } from "../config";
+import { defaultLightTheme, defaultDarkTheme, easings, clamp01 } from "@/lib/remocn-ui";
+import type { Step } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Shared fixtures
+// ===========================================================================
+
+const VALID_STATES: readonly ToastState[] = ["hidden", "visible"];
+const VALID_VARIANTS: readonly ToastVariant[] = ["default", "success", "error"];
+
+/** Convenience wrapper for snippet(). */
+type SnippetValues = {
+ state?: string;
+ title?: string;
+ description?: string;
+ variant?: string;
+ mode?: string;
+};
+const snippet = (values: SnippetValues): string =>
+ toastConfig.snippet(values as Record<string, unknown>);
+
+// ===========================================================================
+// 1. DEFAULT_DURATION constant
+// ===========================================================================
+
+describe("DEFAULT_DURATION", () => {
+ it("is 12 frames", () => {
+ expect(DEFAULT_DURATION).toBe(12);
+ });
+});
+
+// ===========================================================================
+// 2. toastStyle — pure (state) => ToastStyle map
+// MIRROR of index.tsx lines 69-76
+// ===========================================================================
+
+describe("toastStyle: hidden state — off-screen keyframe", () => {
+ const s = toastStyle("hidden");
+
+ it("opacity is 0 (invisible)", () => {
+ expect(s.opacity).toBe(0);
+ });
+
+ it("translateY is 16 (enters from 16px below)", () => {
+ expect(s.translateY).toBe(16);
+ });
+
+ it("scale is 0.97 (slightly shrunken at rest-hidden)", () => {
+ expect(s.scale).toBeCloseTo(0.97, 10);
+ });
+});
+
+describe("toastStyle: visible state — resting keyframe", () => {
+ const s = toastStyle("visible");
+
+ it("opacity is 1 (fully visible)", () => {
+ expect(s.opacity).toBe(1);
+ });
+
+ it("translateY is 0 (at rest position)", () => {
+ expect(s.translateY).toBe(0);
+ });
+
+ it("scale is 1 (full size)", () => {
+ expect(s.scale).toBe(1);
+ });
+});
+
+describe("toastStyle: both states are complete keyframes", () => {
+ it("every ToastStyle field is defined and numeric for every state", () => {
+ for (const state of VALID_STATES) {
+ const s = toastStyle(state);
+ expect(typeof s.opacity).toBe("number");
+ expect(typeof s.translateY).toBe("number");
+ expect(typeof s.scale).toBe("number");
+ }
+ });
+
+ it("hidden and visible have distinct opacity (0 vs 1)", () => {
+ expect(toastStyle("hidden").opacity).toBe(0);
+ expect(toastStyle("visible").opacity).toBe(1);
+ });
+
+ it("hidden and visible have distinct translateY (16 vs 0)", () => {
+ expect(toastStyle("hidden").translateY).toBe(16);
+ expect(toastStyle("visible").translateY).toBe(0);
+ });
+
+ it("hidden and visible have distinct scale (0.97 vs 1)", () => {
+ expect(toastStyle("hidden").scale).toBeCloseTo(0.97, 10);
+ expect(toastStyle("visible").scale).toBe(1);
+ });
+});
+
+// ===========================================================================
+// 3. toastStyleContext — pure variant × theme → { iconColor }
+// MIRROR of index.tsx lines 55-62
+// ===========================================================================
+
+describe("toastStyleContext: default variant", () => {
+ const ctx = toastStyleContext("default", defaultLightTheme);
+
+ it("iconColor equals theme.mutedForeground", () => {
+ expect(ctx.iconColor).toBe(defaultLightTheme.mutedForeground);
+ });
+
+ it("iconColor is a non-empty string", () => {
+ expect(typeof ctx.iconColor).toBe("string");
+ expect(ctx.iconColor.length).toBeGreaterThan(0);
+ });
+});
+
+describe("toastStyleContext: success variant", () => {
+ const ctx = toastStyleContext("success", defaultLightTheme);
+
+ it("iconColor is the hardcoded green oklch string", () => {
+ expect(ctx.iconColor).toBe("oklch(0.6 0.17 150)");
+ });
+
+ it("iconColor does NOT depend on the theme", () => {
+ const ctxDark = toastStyleContext("success", defaultDarkTheme);
+ expect(ctxDark.iconColor).toBe("oklch(0.6 0.17 150)");
+ });
+});
+
+describe("toastStyleContext: error variant", () => {
+ const ctxLight = toastStyleContext("error", defaultLightTheme);
+ const ctxDark = toastStyleContext("error", defaultDarkTheme);
+
+ it("iconColor equals theme.destructive for light theme", () => {
+ expect(ctxLight.iconColor).toBe(defaultLightTheme.destructive);
+ });
+
+ it("iconColor equals theme.destructive for dark theme", () => {
+ expect(ctxDark.iconColor).toBe(defaultDarkTheme.destructive);
+ });
+
+ it("light and dark destructive colors are different", () => {
+ expect(ctxLight.iconColor).not.toBe(ctxDark.iconColor);
+ });
+});
+
+describe("toastStyleContext: all variants return an object with only iconColor", () => {
+ it("every variant produces a non-empty iconColor", () => {
+ for (const variant of VALID_VARIANTS) {
+ const ctx = toastStyleContext(variant, defaultLightTheme);
+ expect(typeof ctx.iconColor).toBe("string");
+ expect(ctx.iconColor.length).toBeGreaterThan(0);
+ }
+ });
+});
+
+// ===========================================================================
+// 4. tweenToastStyle — pure lerp across all three fields
+// MIRROR of use-toast-transition.ts lines 23-33
+// ===========================================================================
+
+describe("tweenToastStyle: t=0 returns values equal to `a`", () => {
+ const a = toastStyle("hidden");
+ const b = toastStyle("visible");
+ const r = tweenToastStyle(a, b, 0);
+
+ it("opacity equals a.opacity at t=0", () => {
+ expect(r.opacity).toBeCloseTo(a.opacity, 10);
+ });
+
+ it("translateY equals a.translateY at t=0", () => {
+ expect(r.translateY).toBeCloseTo(a.translateY, 10);
+ });
+
+ it("scale equals a.scale at t=0", () => {
+ expect(r.scale).toBeCloseTo(a.scale, 10);
+ });
+});
+
+describe("tweenToastStyle: t=1 returns values equal to `b`", () => {
+ const a = toastStyle("hidden");
+ const b = toastStyle("visible");
+ const r = tweenToastStyle(a, b, 1);
+
+ it("opacity equals b.opacity at t=1", () => {
+ expect(r.opacity).toBeCloseTo(b.opacity, 10);
+ });
+
+ it("translateY equals b.translateY at t=1", () => {
+ expect(r.translateY).toBeCloseTo(b.translateY, 10);
+ });
+
+ it("scale equals b.scale at t=1", () => {
+ expect(r.scale).toBeCloseTo(b.scale, 10);
+ });
+});
+
+describe("tweenToastStyle: t=0.5 midpoint (hidden → visible)", () => {
+ // hidden: opacity=0, translateY=16, scale=0.97
+ // visible: opacity=1, translateY=0, scale=1
+ // midpoint: opacity=0.5, translateY=8, scale=0.985
+ const a = toastStyle("hidden");
+ const b = toastStyle("visible");
+ const r = tweenToastStyle(a, b, 0.5);
+
+ it("opacity midpoint: 0 → 1 gives 0.5", () => {
+ expect(r.opacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("translateY midpoint: 16 → 0 gives 8", () => {
+ expect(r.translateY).toBeCloseTo(8, 10);
+ });
+
+ it("scale midpoint: 0.97 → 1 gives 0.985", () => {
+ expect(r.scale).toBeCloseTo(0.985, 10);
+ });
+});
+
+describe("tweenToastStyle: t=0.5 midpoint (visible → hidden, dismiss direction)", () => {
+ // Reverse direction: visible→hidden
+ // midpoint: opacity=0.5, translateY=8, scale=0.985
+ const a = toastStyle("visible");
+ const b = toastStyle("hidden");
+ const r = tweenToastStyle(a, b, 0.5);
+
+ it("opacity midpoint: 1 → 0 gives 0.5", () => {
+ expect(r.opacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("translateY midpoint: 0 → 16 gives 8", () => {
+ expect(r.translateY).toBeCloseTo(8, 10);
+ });
+
+ it("scale midpoint: 1 → 0.97 gives 0.985", () => {
+ expect(r.scale).toBeCloseTo(0.985, 10);
+ });
+});
+
+describe("tweenToastStyle: identity (a === b, any t)", () => {
+ const s = toastStyle("visible");
+
+ it("opacity is unchanged when both endpoints are the same", () => {
+ expect(tweenToastStyle(s, s, 0.5).opacity).toBeCloseTo(s.opacity, 10);
+ });
+
+ it("translateY is unchanged when both endpoints are the same", () => {
+ expect(tweenToastStyle(s, s, 0.5).translateY).toBeCloseTo(s.translateY, 10);
+ });
+
+ it("scale is unchanged when both endpoints are the same", () => {
+ expect(tweenToastStyle(s, s, 0.5).scale).toBeCloseTo(s.scale, 10);
+ });
+});
+
+describe("tweenToastStyle: t=0.25 quarter-point (hidden → visible)", () => {
+ // opacity: 0 + 0.25*(1-0) = 0.25
+ // translateY: 16 + 0.25*(0-16) = 12
+ // scale: 0.97 + 0.25*(1-0.97) = 0.97+0.0075 = 0.9775
+ const a = toastStyle("hidden");
+ const b = toastStyle("visible");
+ const r = tweenToastStyle(a, b, 0.25);
+
+ it("opacity at t=0.25 is 0.25", () => {
+ expect(r.opacity).toBeCloseTo(0.25, 10);
+ });
+
+ it("translateY at t=0.25 is 12", () => {
+ expect(r.translateY).toBeCloseTo(12, 10);
+ });
+
+ it("scale at t=0.25 is 0.9775", () => {
+ expect(r.scale).toBeCloseTo(0.9775, 10);
+ });
+});
+
+// ===========================================================================
+// 5. useToastTransition resolver replica
+// MIRRORS use-toast-transition.ts lines 47-60.
+// `useToastTransition` calls `useStateTransition` (which reads
+// `useCurrentFrame()`) then applies `easings.out(progress)` and
+// `tweenToastStyle`. We inject `raw` in place of `useCurrentFrame()`.
+//
+// This replica re-derives only the logic BEYOND the core
+// `useStateTransition` (already tested in core/__tests__/timeline.test.ts).
+// The key additional contract: progress is eased with `easings.out` before
+// the tween, so the visible field values are out-eased, not linear.
+//
+// MAINTENANCE CONTRACT: if use-toast-transition.ts lines 47-60 change,
+// update this replica in lockstep. Annotated source lines below.
+// ===========================================================================
+
+/** MIRROR of core/timeline.ts:clamp01. */
+function clamp01Mirror(t: number): number {
+ return Math.max(0, Math.min(1, t));
+}
+
+/** MIRROR of core/motion.ts:easings.out (cubic ease-out). */
+function easingOut(t: number): number {
+ return 1 - (1 - t) ** 3;
+}
+
+/**
+ * MIRROR of timeline.ts:useStateTransition pure resolver body
+ * (lines 55-73 of core/timeline.ts), with `raw` injected.
+ */
+function resolveStateTransition<S extends string>(
+ raw: number,
+ steps: Step<S>[],
+ defaultState: S,
+ speed = 1,
+ defaultDuration = 8,
+): { from: S; to: S; progress: number } {
+ const effectiveFrame = raw * speed;
+ const started = steps
+ .map((step, index) => ({ step, index }))
+ .sort((a, b) => a.step.at - b.step.at || a.index - b.index)
+ .filter((e) => e.step.at <= effectiveFrame);
+ if (started.length === 0)
+ return { from: defaultState, to: defaultState, progress: 1 };
+ const to = started[started.length - 1].step;
+ const from = started.length >= 2 ? started[started.length - 2].step : null;
+ const dur = to.duration ?? defaultDuration;
+ const progress = dur > 0 ? clamp01Mirror((effectiveFrame - to.at) / dur) : 1;
+ return { from: from ? from.state : defaultState, to: to.state, progress };
+}
+
+/**
+ * MIRROR of use-toast-transition.ts:useToastTransition (lines 47-60).
+ * `raw` is injected in place of useCurrentFrame().
+ * Annotated source lines:
+ * line 51: destructure speed + defaultDuration from opts
+ * line 52-57: call useStateTransition (mirrored as resolveStateTransition)
+ * line 58: t = easings.out(progress) ← MIRROR line 58
+ * line 59: tweenToastStyle(from, to, t) ← MIRROR line 59
+ */
+function resolveToastTransition(
+ raw: number, // injected useCurrentFrame() — MIRROR line 52
+ steps: Step<ToastState>[],
+ speed = 1,
+ defaultDuration = DEFAULT_DURATION,
+): { style: ReturnType<typeof tweenToastStyle>; progress: number; from: ToastState; to: ToastState } {
+ const { from, to, progress } = resolveStateTransition( // MIRROR lines 52-57
+ raw,
+ steps,
+ "hidden",
+ speed,
+ defaultDuration,
+ );
+ const t = easingOut(progress); // MIRROR line 58
+ const style = tweenToastStyle(toastStyle(from as ToastState), toastStyle(to as ToastState), t); // MIRROR line 59
+ return { style, progress, from: from as ToastState, to: to as ToastState };
+}
+
+// ---------------------------------------------------------------------------
+// Before any step: holds at hidden (progress=1, tween(hidden,hidden,out(1)))
+// ---------------------------------------------------------------------------
+
+describe("resolveToastTransition: before any step — holds at hidden", () => {
+ it("returns the hidden style when no steps have started", () => {
+ const { style } = resolveToastTransition(0, []);
+ const hidden = toastStyle("hidden");
+ // out(1)=1, so tween(hidden,hidden,1) = hidden
+ expect(style.opacity).toBeCloseTo(hidden.opacity, 10);
+ expect(style.translateY).toBeCloseTo(hidden.translateY, 10);
+ expect(style.scale).toBeCloseTo(hidden.scale, 10);
+ });
+
+ it("from and to are both 'hidden' before any step", () => {
+ const { from, to } = resolveToastTransition(0, []);
+ expect(from).toBe("hidden");
+ expect(to).toBe("hidden");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Exactly at a step boundary: progress=0, t=easings.out(0)=0
+// ---------------------------------------------------------------------------
+
+describe("resolveToastTransition: exactly at hidden→visible step boundary", () => {
+ const steps: Step<ToastState>[] = [{ at: 10, state: "visible" }];
+
+ it("at raw=10 exactly, progress=0, t=out(0)=0 → style equals hidden (from)", () => {
+ const { style, progress } = resolveToastTransition(10, steps);
+ expect(progress).toBe(0);
+ // t = out(0) = 0, so style = tween(hidden, visible, 0) = hidden
+ const hidden = toastStyle("hidden");
+ expect(style.opacity).toBeCloseTo(hidden.opacity, 10);
+ expect(style.translateY).toBeCloseTo(hidden.translateY, 10);
+ expect(style.scale).toBeCloseTo(hidden.scale, 10);
+ });
+
+ it("from='hidden', to='visible' at the step boundary", () => {
+ const { from, to } = resolveToastTransition(10, steps);
+ expect(from).toBe("hidden");
+ expect(to).toBe("visible");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Mid-window: easings.out applied to progress (non-linear)
+// ---------------------------------------------------------------------------
+
+describe("resolveToastTransition: mid-window uses easings.out (not linear)", () => {
+ // step at=0, defaultDuration=12. At raw=6: linear progress=0.5, out(0.5)≈0.875
+ // opacity: tween(0, 1, 0.875) = 0.875
+ const steps: Step<ToastState>[] = [{ at: 0, state: "visible" }];
+
+ it("opacity at raw=6 is tween(0,1,out(0.5)) ≈ 0.875 (not linear 0.5)", () => {
+ const { style } = resolveToastTransition(6, steps, 1, 12);
+ const expectedT = easingOut(0.5); // ≈ 0.875
+ expect(style.opacity).toBeCloseTo(expectedT, 8);
+ });
+
+ it("translateY at raw=6 is tween(16,0,out(0.5)): 16*(1-out(0.5))", () => {
+ const { style } = resolveToastTransition(6, steps, 1, 12);
+ const t = easingOut(0.5);
+ const expected = 16 * (1 - t); // lerp(16, 0, t)
+ expect(style.translateY).toBeCloseTo(expected, 8);
+ });
+
+ it("scale at raw=6 is tween(0.97,1,out(0.5))", () => {
+ const { style } = resolveToastTransition(6, steps, 1, 12);
+ const t = easingOut(0.5);
+ const expected = 0.97 + (1 - 0.97) * t;
+ expect(style.scale).toBeCloseTo(expected, 8);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Past the window: progress=1, t=out(1)=1 → fully visible
+// ---------------------------------------------------------------------------
+
+describe("resolveToastTransition: past the transition window → fully visible", () => {
+ const steps: Step<ToastState>[] = [{ at: 0, state: "visible" }];
+
+ it("opacity is 1 after DEFAULT_DURATION frames", () => {
+ const { style } = resolveToastTransition(DEFAULT_DURATION, steps);
+ expect(style.opacity).toBeCloseTo(1, 10);
+ });
+
+ it("translateY is 0 after DEFAULT_DURATION frames", () => {
+ const { style } = resolveToastTransition(DEFAULT_DURATION, steps);
+ expect(style.translateY).toBeCloseTo(0, 10);
+ });
+
+ it("scale is 1 after DEFAULT_DURATION frames", () => {
+ const { style } = resolveToastTransition(DEFAULT_DURATION, steps);
+ expect(style.scale).toBeCloseTo(1, 10);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Speed contract
+// ---------------------------------------------------------------------------
+
+describe("resolveToastTransition: speed contract", () => {
+ // step at=12. speed=2: effectiveFrame = raw*2 → fires at raw=6.
+ const steps: Step<ToastState>[] = [{ at: 12, state: "visible" }];
+
+ it("speed=2: step at=12 fires at raw=6 (eff=12)", () => {
+ const { to } = resolveToastTransition(6, steps, 2);
+ expect(to).toBe("visible");
+ });
+
+ it("speed=2: step at=12 has NOT fired at raw=5 (eff=10 < 12)", () => {
+ const { to } = resolveToastTransition(5, steps, 2);
+ expect(to).toBe("hidden");
+ });
+});
+
+// ===========================================================================
+// 6. toastConfig.controls — customizer control wiring
+// ===========================================================================
+
+describe("toastConfig.controls: state", () => {
+ it("state is a select control", () => {
+ expect(toastConfig.controls.state.type).toBe("select");
+ });
+
+ it("state options are ['hidden', 'visible']", () => {
+ const ctrl = toastConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["hidden", "visible"]);
+ });
+
+ it("state default is 'visible' (shows the resting toast in the preview)", () => {
+ expect(toastConfig.controls.state.default).toBe("visible");
+ });
+
+ it("every state option is a valid ToastState", () => {
+ const ctrl = toastConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const opt of ctrl.options) {
+ expect(VALID_STATES).toContain(opt as ToastState);
+ }
+ });
+});
+
+describe("toastConfig.controls: variant", () => {
+ it("variant is a select control", () => {
+ expect(toastConfig.controls.variant.type).toBe("select");
+ });
+
+ it("variant options are ['default', 'success', 'error']", () => {
+ const ctrl = toastConfig.controls.variant;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["default", "success", "error"]);
+ });
+
+ it("variant default is 'success'", () => {
+ expect(toastConfig.controls.variant.default).toBe("success");
+ });
+
+ it("every variant option is a valid ToastVariant", () => {
+ const ctrl = toastConfig.controls.variant;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const opt of ctrl.options) {
+ expect(VALID_VARIANTS).toContain(opt as ToastVariant);
+ }
+ });
+});
+
+describe("toastConfig.controls: mode", () => {
+ it("mode is a select control", () => {
+ expect(toastConfig.controls.mode.type).toBe("select");
+ });
+
+ it("mode options are ['light', 'dark']", () => {
+ const ctrl = toastConfig.controls.mode;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["light", "dark"]);
+ });
+
+ it("mode default is 'light'", () => {
+ expect(toastConfig.controls.mode.default).toBe("light");
+ });
+});
+
+describe("toastConfig.controls: title and description", () => {
+ it("title is a text control", () => {
+ expect(toastConfig.controls.title.type).toBe("text");
+ });
+
+ it("description is a text control", () => {
+ expect(toastConfig.controls.description.type).toBe("text");
+ });
+
+ it("title default is 'Changes saved'", () => {
+ expect(toastConfig.controls.title.default).toBe("Changes saved");
+ });
+});
+
+// ===========================================================================
+// 7. toastConfig.snippet — pure JSX string builder
+// ===========================================================================
+
+describe("toastConfig.snippet: import line", () => {
+ it("includes 'import { Toast }' from the correct path", () => {
+ const out = snippet({ state: "visible" });
+ expect(out).toContain("import { Toast }");
+ expect(out).toContain('from "@/components/remocn/toast"');
+ });
+});
+
+describe("toastConfig.snippet: structural invariants", () => {
+ it("contains a <Toast JSX element", () => {
+ expect(snippet({ state: "visible" })).toContain("<Toast");
+ });
+
+ it("ends with a self-closing />", () => {
+ expect(snippet({ state: "visible" }).trimEnd().endsWith("/>")).toBe(true);
+ });
+
+ it("state prop is always emitted", () => {
+ expect(snippet({ state: "visible" })).toContain('state="visible"');
+ expect(snippet({ state: "hidden" })).toContain('state="hidden"');
+ });
+});
+
+describe("toastConfig.snippet: title is always emitted", () => {
+ // title is required on <Toast> so the snippet always includes it — even for
+ // the default value (unlike optional props in other components).
+ it("emits title='Changes saved' when title is the default", () => {
+ const out = snippet({ state: "visible", title: "Changes saved" });
+ expect(out).toContain('title="Changes saved"');
+ });
+
+ it("emits title prop when title is omitted from values (falls back to default)", () => {
+ const out = snippet({ state: "visible" });
+ expect(out).toContain('title="Changes saved"');
+ });
+
+ it("emits a non-default title when provided", () => {
+ const out = snippet({ state: "visible", title: "Upload complete" });
+ expect(out).toContain('title="Upload complete"');
+ });
+});
+
+describe("toastConfig.snippet: default props are omitted", () => {
+ // Defaults: variant=success (the config default), mode=light
+ // description is omitted when equal to the default string
+
+ it("omits variant when it equals the default 'success'", () => {
+ const out = snippet({ state: "visible", variant: "success" });
+ expect(out).not.toContain("variant=");
+ });
+
+ it("omits mode when it equals the default 'light'", () => {
+ const out = snippet({ state: "visible", mode: "light" });
+ expect(out).not.toContain("mode=");
+ });
+
+ it("omits description when it equals the default description", () => {
+ const out = snippet({
+ state: "visible",
+ description: "Your profile has been updated.",
+ });
+ expect(out).not.toContain("description=");
+ });
+});
+
+describe("toastConfig.snippet: non-default props are emitted", () => {
+ it("emits variant='default' when non-default (not success)", () => {
+ expect(snippet({ state: "visible", variant: "default" })).toContain(
+ 'variant="default"',
+ );
+ });
+
+ it("emits variant='error' when non-default", () => {
+ expect(snippet({ state: "visible", variant: "error" })).toContain(
+ 'variant="error"',
+ );
+ });
+
+ it("emits mode='dark' when non-default", () => {
+ expect(snippet({ state: "visible", mode: "dark" })).toContain(
+ 'mode="dark"',
+ );
+ });
+
+ it("emits description when non-default", () => {
+ expect(
+ snippet({ state: "visible", description: "File uploaded." }),
+ ).toContain('description="File uploaded."');
+ });
+});
+
+describe("toastConfig.snippet: state options round-trip", () => {
+ it("emits the correct state for every control option", () => {
+ const ctrl = toastConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const state of ctrl.options) {
+ expect(snippet({ state })).toContain(`state="${state}"`);
+ }
+ });
+});
diff --git a/registry/remocn-ui/toast/config.ts b/registry/remocn-ui/toast/config.ts
new file mode 100644
index 00000000..438fdc5e
--- /dev/null
+++ b/registry/remocn-ui/toast/config.ts
@@ -0,0 +1,66 @@
+import { type ComponentConfig, FPS, H, W } from "@/lib/customizer-config";
+import type { ToastState } from "@/registry/remocn-ui/toast";
+
+const DEFAULT_TITLE = "Changes saved";
+const DEFAULT_DESCRIPTION = "Your profile has been updated.";
+
+export const toastConfig: ComponentConfig = {
+ componentName: "Toast",
+ importPath: "@/components/remocn/toast",
+ controls: {
+ title: { type: "text", default: DEFAULT_TITLE, label: "Title" },
+ description: {
+ type: "text",
+ default: DEFAULT_DESCRIPTION,
+ label: "Description",
+ },
+ variant: {
+ type: "select",
+ default: "success",
+ options: ["default", "success", "error"],
+ label: "Variant",
+ },
+ state: {
+ type: "select",
+ // Default to `visible` so the preview shows the resting toast.
+ default: "visible",
+ options: ["hidden", "visible"],
+ label: "State",
+ },
+ mode: {
+ type: "select",
+ default: "light",
+ options: ["light", "dark"],
+ label: "Mode",
+ },
+ },
+ durationInFrames: 120,
+ fps: FPS,
+ compositionWidth: W,
+ compositionHeight: H,
+ snippet: (values) => {
+ const state = (values.state as ToastState) ?? "visible";
+ const title = values.title as string | undefined;
+ const description = values.description as string | undefined;
+ const variant = values.variant as string | undefined;
+ const mode = values.mode as string | undefined;
+
+ // `title` is required, so it is always emitted.
+ const props: string[] = [
+ ` state="${state}"`,
+ ` title="${title ?? DEFAULT_TITLE}"`,
+ ];
+ if (description !== undefined && description !== DEFAULT_DESCRIPTION)
+ props.push(` description="${description}"`);
+ if (variant !== undefined && variant !== "default")
+ props.push(` variant="${variant}"`);
+ if (mode !== undefined && mode !== "light")
+ props.push(` mode="${mode}"`);
+
+ return `import { Toast } from "@/components/remocn/toast";
+
+<Toast
+${props.join("\n")}
+/>`;
+ },
+};
diff --git a/registry/remocn-ui/toast/index.tsx b/registry/remocn-ui/toast/index.tsx
new file mode 100644
index 00000000..96804b82
--- /dev/null
+++ b/registry/remocn-ui/toast/index.tsx
@@ -0,0 +1,202 @@
+"use client";
+
+import { type RemocnTheme, useRemocnTheme } from "@/lib/remocn-ui";
+
+export type ToastState = "hidden" | "visible";
+
+export type ToastVariant = "default" | "success" | "error";
+
+export interface ToastProps {
+ /** Current visual state (snap path). State changes snap (no enter-tweens). */
+ state?: ToastState;
+ /**
+ * Resolved animated visual (smooth path). When provided, takes precedence over
+ * `state` — feed it an interpolated `ToastStyle` from `useToastTransition`.
+ */
+ style?: ToastStyle;
+ title: string;
+ description?: string;
+ /** Changes the leading icon and its color. `default` shows a neutral info dot. */
+ variant?: ToastVariant;
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ className?: string;
+}
+
+const TOAST_WIDTH = 356;
+
+export interface ToastStyle {
+ /** Whole-toast opacity 0→1. */
+ opacity: number;
+ /** Enter offset in px (+16 below rest → 0 at rest). */
+ translateY: number;
+ /** Enter scale (0.97 → 1). */
+ scale: number;
+}
+
+/** Concrete per-variant visuals, resolved once per render. */
+export interface ToastStyleContext {
+ /** Leading icon color for the active variant (a concrete color). */
+ iconColor: string;
+}
+
+/**
+ * Derive the concrete per-variant colors for a theme. Pure — `success`/`error`
+ * tint the icon; `default` uses the muted foreground.
+ */
+export function toastStyleContext(
+ variant: ToastVariant,
+ theme: RemocnTheme,
+): ToastStyleContext {
+ if (variant === "success") return { iconColor: "oklch(0.6 0.17 150)" };
+ if (variant === "error") return { iconColor: theme.destructive };
+ return { iconColor: theme.mutedForeground };
+}
+
+/**
+ * The COMPLETE resting visual for a state — a pure `(state) => ToastStyle` map.
+ * Both presets are full keyframes; the toast enters from 16px below at 0.97
+ * scale and rests at 0/1. To change how a state looks, edit one entry.
+ */
+export function toastStyle(state: ToastState): ToastStyle {
+ switch (state) {
+ case "visible":
+ return { opacity: 1, translateY: 0, scale: 1 };
+ default:
+ return { opacity: 0, translateY: 16, scale: 0.97 };
+ }
+}
+
+function ToastIcon({
+ variant,
+ color,
+}: {
+ variant: ToastVariant;
+ color: string;
+}) {
+ if (variant === "success") {
+ return (
+ <svg width={18} height={18} viewBox="0 0 24 24" fill="none">
+ <circle cx="12" cy="12" r="9" stroke={color} strokeWidth="2" />
+ <path
+ d="M8 12.5l2.6 2.6L16 9"
+ stroke={color}
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </svg>
+ );
+ }
+ if (variant === "error") {
+ return (
+ <svg width={18} height={18} viewBox="0 0 24 24" fill="none">
+ <circle cx="12" cy="12" r="9" stroke={color} strokeWidth="2" />
+ <path
+ d="M12 7.5v5"
+ stroke={color}
+ strokeWidth="2"
+ strokeLinecap="round"
+ />
+ <circle cx="12" cy="16" r="1.1" fill={color} />
+ </svg>
+ );
+ }
+ // default — neutral info circle.
+ return (
+ <svg width={18} height={18} viewBox="0 0 24 24" fill="none">
+ <circle cx="12" cy="12" r="9" stroke={color} strokeWidth="2" />
+ <path d="M12 11v5" stroke={color} strokeWidth="2" strokeLinecap="round" />
+ <circle cx="12" cy="8" r="1.1" fill={color} />
+ </svg>
+ );
+}
+
+/**
+ * A deterministic toast. Pure renderer of whatever `ToastStyle` it receives — it
+ * reads no frame, holds no state, runs no effects. Snap (`state`) and smooth
+ * (`style`) share one render path. Placement (e.g. bottom-right) is the caller's
+ * job; the toast renders inside a transparent wrapper.
+ */
+export function Toast({
+ state = "hidden",
+ style,
+ title,
+ description,
+ variant = "default",
+ theme: themeOverride,
+ mode,
+ className,
+}: ToastProps) {
+ const theme = useRemocnTheme(themeOverride, mode);
+ const ctx = toastStyleContext(variant, theme);
+ const v = style ?? toastStyle(state);
+
+ return (
+ <div
+ className={className}
+ style={{
+ display: "flex",
+
+ alignItems: description ? "flex-start" : "center",
+ gap: 12,
+ width: TOAST_WIDTH,
+ padding: "16px",
+ background: theme.popover,
+ color: theme.popoverForeground,
+ border: `1px solid ${theme.border}`,
+ borderRadius: theme.radius,
+ boxShadow:
+ "0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.1)",
+ opacity: v.opacity,
+ transform: `translateY(${v.translateY}px) scale(${v.scale})`,
+ transformOrigin: "bottom center",
+ fontFamily:
+ "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif",
+ }}
+ >
+ <span
+ style={{
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ // flexShrink: 0,
+ // Nudge the icon onto the title's optical line when stacked.
+ marginTop: description ? 1 : 0,
+ }}
+ >
+ <ToastIcon variant={variant} color={ctx.iconColor} />
+ </span>
+ <div
+ style={{
+ display: "flex",
+ flexDirection: "column",
+ gap: 4,
+ minWidth: 0,
+ }}
+ >
+ <span
+ style={{
+ fontSize: 14,
+ fontWeight: 500,
+ lineHeight: 1.3,
+ letterSpacing: "-0.01em",
+ }}
+ >
+ {title}
+ </span>
+ {description !== undefined && (
+ <span
+ style={{
+ fontSize: 13,
+ lineHeight: 1.4,
+ color: theme.mutedForeground,
+ }}
+ >
+ {description}
+ </span>
+ )}
+ </div>
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/toast/preview.tsx b/registry/remocn-ui/toast/preview.tsx
new file mode 100644
index 00000000..2389f93c
--- /dev/null
+++ b/registry/remocn-ui/toast/preview.tsx
@@ -0,0 +1,56 @@
+"use client";
+
+import { useRemocnTheme } from "@/lib/remocn-ui";
+import {
+ Toast,
+ type ToastState,
+ type ToastVariant,
+} from "@/registry/remocn-ui/toast";
+
+export interface ToastPreviewProps {
+ title?: string;
+ description?: string;
+ variant?: ToastVariant;
+ state?: ToastState;
+ mode?: "light" | "dark";
+}
+
+/**
+ * Preview-only wrapper for the customizer. The shipped `Toast` is a
+ * placement-agnostic card — it renders inside a transparent wrapper and the
+ * caller positions it (e.g. bottom-right, see the example). The customizer
+ * Player renders its `component` as the composition root, so a bare `Toast`
+ * would sit in normal flow and stretch; this thin wrapper centers it on a
+ * theme-background stage just for the preview. NOT shipped: not listed in
+ * registry.json files; users position the toast themselves.
+ */
+export function ToastPreview({
+ title = "Changes saved",
+ description = "Your profile has been updated.",
+ variant = "success",
+ state = "visible",
+ mode,
+}: ToastPreviewProps) {
+ const theme = useRemocnTheme(undefined, mode);
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ background: theme.background,
+ }}
+ >
+ <Toast
+ title={title}
+ description={description}
+ variant={variant}
+ state={state}
+ mode={mode}
+ />
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/toast/use-toast-transition.ts b/registry/remocn-ui/toast/use-toast-transition.ts
new file mode 100644
index 00000000..e0321b7b
--- /dev/null
+++ b/registry/remocn-ui/toast/use-toast-transition.ts
@@ -0,0 +1,60 @@
+"use client";
+
+import {
+ easings,
+ type Step,
+ useStateTransition,
+} from "@/lib/remocn-ui";
+import {
+ toastStyle,
+ type ToastState,
+ type ToastStyle,
+} from "@/components/remocn/toast";
+// ^ 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 = 12;
+
+/**
+ * Blend two toast visuals: every field lerps. `ToastStyle` carries no animated
+ * colors (only transform + opacity), so there is no `mixOklch` here — but every
+ * field is covered so neither enter nor dismiss freezes a channel.
+ */
+export function tweenToastStyle(
+ a: ToastStyle,
+ b: ToastStyle,
+ t: number,
+): ToastStyle {
+ return {
+ opacity: a.opacity + (b.opacity - a.opacity) * t,
+ translateY: a.translateY + (b.translateY - a.translateY) * t,
+ scale: a.scale + (b.scale - a.scale) * t,
+ };
+}
+
+export interface ToastTransitionOptions {
+ mode?: "light" | "dark";
+ speed?: number;
+ defaultDuration?: number;
+}
+
+/**
+ * Timeline → resolved (eased, tweened) ToastStyle. The CALLER invokes this; it
+ * reads the frame, the `<Toast>` component does not. Feed the result to
+ * `<Toast style={...} />`. Both the enter (hidden→visible) and the auto-dismiss
+ * (visible→hidden) read from the same eased tween, so both look smooth.
+ */
+export function useToastTransition(
+ steps: Step<ToastState>[],
+ opts: ToastTransitionOptions = {},
+): ToastStyle {
+ const { speed = 1, defaultDuration = DEFAULT_DURATION } = opts;
+ const { from, to, progress } = useStateTransition(
+ steps,
+ "hidden",
+ speed,
+ defaultDuration,
+ );
+ const t = easings.out(progress);
+ return tweenToastStyle(toastStyle(from), toastStyle(to), t);
+}