Skip to content

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

feat: added context-menu component

dev_wandryccb122b8f754
diff --git a/components/docs/examples/context-menu-example.tsx b/components/docs/examples/context-menu-example.tsx
new file mode 100644
index 00000000..0b441205
--- /dev/null
+++ b/components/docs/examples/context-menu-example.tsx
@@ -0,0 +1,173 @@
+"use client";
+
+import { Cursor } from "@/registry/remocn-ui/cursor";
+import { useCursorPath } from "@/registry/remocn-ui/cursor/use-cursor-path";
+import { ContextMenu } from "@/registry/remocn-ui/context-menu";
+import { useContextMenuTransition } from "@/registry/remocn-ui/context-menu/use-context-menu-transition";
+import { useDropdownMenuItemTransition } from "@/registry/remocn-ui/dropdown-menu-item/use-dropdown-menu-item-transition";
+import { useCurrentState } from "@/lib/remocn-ui";
+
+// The cursor right-clicks near the center of the file card.
+// The context menu opens AT this point (its top-left corner = click position).
+const CLICK_X = 660;
+const CLICK_Y = 385;
+// Row 1 ("Reload") sits ~one row + paddings below the menu's top-left and
+// ~a third across the 200px panel — the cursor travels here to select it.
+const ROW1_X = CLICK_X + 70;
+const ROW1_Y = CLICK_Y + 60;
+
+export const ContextMenuExampleScene = () => {
+ // Cursor: park → ease to card → right-click → move DOWN onto row 1 → click it → leave.
+ const cursorStyle = useCursorPath([
+ { at: 0, x: 80, y: 60 },
+ { at: 30, x: CLICK_X, y: CLICK_Y, duration: 26 },
+ { at: 42, x: CLICK_X, y: CLICK_Y, click: true, duration: 0 },
+ { at: 58, x: ROW1_X, y: ROW1_Y, duration: 14 },
+ { at: 72, x: ROW1_X, y: ROW1_Y, click: true, duration: 0 },
+ { at: 104, x: ROW1_X + 180, y: ROW1_Y + 80, duration: 20 },
+ ]);
+
+ // Menu: opens just after the right-click, closes after the row interaction.
+ const menuStyle = useContextMenuTransition([
+ { at: 44, state: "opened", duration: 10 },
+ { at: 92, state: "closed", duration: 10 },
+ ]);
+
+ // Row 1 ("Reload"): idle → hover → press → idle.
+ const rowState = useCurrentState(
+ [
+ { at: 60, state: "hover" },
+ { at: 72, state: "press" },
+ { at: 82, state: "idle" },
+ ],
+ "idle",
+ );
+ const rowStyle = useDropdownMenuItemTransition([{ at: 0, state: rowState }]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ {/* File card — the target the cursor right-clicks on. */}
+ <div
+ style={{
+ position: "absolute",
+ left: "50%",
+ top: "50%",
+ transform: "translate(-50%, -50%)",
+ width: 200,
+ padding: "16px 20px",
+ background: "oklch(0.97 0 0)",
+ border: "1px solid oklch(0.9 0 0)",
+ borderRadius: 10,
+ display: "flex",
+ alignItems: "center",
+ gap: 12,
+ fontFamily: "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif",
+ }}
+ >
+ <svg width={20} height={20} viewBox="0 0 24 24" fill="none">
+ <path
+ d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8l-6-6z"
+ stroke="oklch(0.55 0 0)"
+ strokeWidth="1.5"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ <path d="M14 2v6h6" stroke="oklch(0.55 0 0)" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" />
+ </svg>
+ <span style={{ fontSize: 14, fontWeight: 500, color: "oklch(0.3 0 0)" }}>
+ report.pdf
+ </span>
+ </div>
+
+ {/* Context menu anchored at the cursor click point (top-left = click position). */}
+ <div
+ style={{
+ position: "absolute",
+ left: CLICK_X,
+ top: CLICK_Y,
+ }}
+ >
+ <ContextMenu
+ style={menuStyle}
+ itemStyles={[undefined, rowStyle, undefined, undefined]}
+ />
+ </div>
+
+ <Cursor style={cursorStyle} variant="pointer" />
+ </div>
+ );
+};
+
+export const contextMenuExampleCode = `import { Cursor } from "@/components/remocn/cursor";
+import { useCursorPath } from "@/components/remocn/use-cursor-path";
+import { ContextMenu } from "@/components/remocn/context-menu";
+import { useContextMenuTransition } from "@/components/remocn/use-context-menu-transition";
+import { useDropdownMenuItemTransition } from "@/components/remocn/use-dropdown-menu-item-transition";
+import { useCurrentState } from "@/lib/remocn-ui";
+
+// The context menu's top-left corner sits at the cursor click point.
+const CLICK_X = 340;
+const CLICK_Y = 200;
+// Row 1 ("Reload"): ~one row + paddings down, ~a third across the 200px panel.
+const ROW1_X = CLICK_X + 70;
+const ROW1_Y = CLICK_Y + 60;
+
+export const Scene = () => {
+ // Cursor eases to the card, right-clicks, then moves down onto row 1 and clicks it.
+ const cursorStyle = useCursorPath([
+ { at: 0, x: 80, y: 60 },
+ { at: 30, x: CLICK_X, y: CLICK_Y, duration: 26 },
+ { at: 42, x: CLICK_X, y: CLICK_Y, click: true, duration: 0 },
+ { at: 58, x: ROW1_X, y: ROW1_Y, duration: 14 },
+ { at: 72, x: ROW1_X, y: ROW1_Y, click: true, duration: 0 },
+ { at: 104, x: ROW1_X + 180, y: ROW1_Y + 80, duration: 20 },
+ ]);
+
+ // Menu opens at the click point, closes after the row interaction.
+ const menuStyle = useContextMenuTransition([
+ { at: 44, state: "opened", duration: 10 },
+ { at: 92, state: "closed", duration: 10 },
+ ]);
+
+ // Animate row 1 ("Reload"): idle → hover → press → idle.
+ const rowState = useCurrentState(
+ [
+ { at: 60, state: "hover" },
+ { at: 72, state: "press" },
+ { at: 82, state: "idle" },
+ ],
+ "idle",
+ );
+ const rowStyle = useDropdownMenuItemTransition([{ at: 0, state: rowState }]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ {/* File card — right-click target */}
+ <div
+ style={{
+ position: "absolute",
+ left: "50%",
+ top: "50%",
+ transform: "translate(-50%, -50%)",
+ width: 200,
+ padding: "16px 20px",
+ background: "oklch(0.97 0 0)",
+ border: "1px solid oklch(0.9 0 0)",
+ borderRadius: 10,
+ }}
+ >
+ report.pdf
+ </div>
+
+ {/* Context menu positioned at the click point — caller owns placement. */}
+ <div style={{ position: "absolute", left: CLICK_X, top: CLICK_Y }}>
+ <ContextMenu
+ style={menuStyle}
+ itemStyles={[undefined, rowStyle, undefined, undefined]}
+ />
+ </div>
+
+ <Cursor style={cursorStyle} variant="pointer" />
+ </div>
+ );
+};`;
diff --git a/components/docs/examples/index.tsx b/components/docs/examples/index.tsx
index 5e753395..45f19cac 100644
--- a/components/docs/examples/index.tsx
+++ b/components/docs/examples/index.tsx
@@ -52,6 +52,10 @@ import {
PopoverExampleScene,
popoverExampleCode,
} from "./popover-example";
+import {
+ ContextMenuExampleScene,
+ contextMenuExampleCode,
+} from "./context-menu-example";
export interface ExampleEntry {
Component: ComponentType;
@@ -257,4 +261,14 @@ export const examples: Record<string, ExampleEntry> = {
width: W,
height: H,
},
+ "context-menu-example": {
+ Component: ContextMenuExampleScene,
+ code: contextMenuExampleCode,
+ // Cursor selects row 1, menu closes at 102, cursor leaves (arrives 104+20=124);
+ // a short settle then loop.
+ durationInFrames: 135,
+ fps: FPS,
+ width: W,
+ height: H,
+ },
};
diff --git a/content/docs/ui/components/context-menu.mdx b/content/docs/ui/components/context-menu.mdx
new file mode 100644
index 00000000..1278e56b
--- /dev/null
+++ b/content/docs/ui/components/context-menu.mdx
@@ -0,0 +1,223 @@
+---
+title: Context Menu
+description: A right-click menu panel that opens at the cursor point with no built-in trigger
+---
+
+<ComponentPreview name="context-menu" />
+
+A state atom representing a context menu panel. Its appearance (`opened`, `closed`) 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. Unlike `DropdownMenu`, there is no built-in trigger — the context menu opens at the cursor click point and the **caller** positions it there. The panel grows from its top-left corner (the click point) with opacity, scale, and vertical lift.
+
+## Installation
+
+<InstallBlock name="context-menu" />
+
+<Note>
+Installing `context-menu` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) and the `dropdown-menu-item` atom via `registryDependencies` (`["remocn-ui", "dropdown-menu-item"]`). You do not need to install them separately. The panel rows reuse the DropdownMenuItem atom.
+</Note>
+
+## Example
+
+<LiveExample name="context-menu-example" />
+
+## States
+
+`ContextMenuState` is:
+
+```ts
+type ContextMenuState =
+ | "opened" // opacity 1, scale 1, translateY 0 — panel fully visible
+ | "closed" // opacity 0, scale 0.95, translateY -4px — panel hidden
+```
+
+`closed` is the default. The panel grows from its top-left corner (`transformOrigin: "top left"`), which corresponds to the cursor's right-click point. `opened` reveals the panel; `closed` hides it.
+
+## 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 { ContextMenu } from "@/components/remocn/context-menu";
+
+export const Scene = () => (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ {/* Position the menu at the right-click point */}
+ <div style={{ position: "absolute", left: 400, top: 280 }}>
+ <ContextMenu state="opened" />
+ </div>
+ </div>
+);
+```
+
+To drive state from the timeline, use `useCurrentState`:
+
+```tsx
+import { useCurrentState } from "@/lib/remocn-ui";
+import { ContextMenu } from "@/components/remocn/context-menu";
+
+export const Scene = () => {
+ const state = useCurrentState(
+ [
+ { at: 44, state: "opened" },
+ { at: 92, state: "closed" },
+ ],
+ "closed",
+ );
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <div style={{ position: "absolute", left: 400, top: 280 }}>
+ <ContextMenu state={state} />
+ </div>
+ </div>
+ );
+};
+```
+
+Each `at` is a **Sequence-local authored frame**. State persists between steps. See [Concepts](/docs/ui/concepts) for the full `useCurrentState` API.
+
+## Smooth transitions
+
+State changes via `state` snap with no cross-fade. For an animated open/close, use `useContextMenuTransition` from the copied `use-context-menu-transition.ts` file. It reads the frame, interpolates between state presets, and returns a resolved `ContextMenuStyle` — pass it to the `style` prop:
+
+```tsx
+import { ContextMenu } from "@/components/remocn/context-menu";
+import { useContextMenuTransition } from "@/components/remocn/use-context-menu-transition";
+
+export const Scene = () => {
+ const style = useContextMenuTransition([
+ { at: 44, state: "opened", duration: 10 },
+ { at: 92, state: "closed", duration: 10 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <div style={{ position: "absolute", left: 400, top: 280 }}>
+ <ContextMenu style={style} />
+ </div>
+ </div>
+ );
+};
+```
+
+The `duration` field on each step overrides the file's `DEFAULT_DURATION` (= `10`) for that specific transition. To globally tune timing and easing, edit `use-context-menu-transition.ts` directly in your project — that file is yours (shadcn "own your code" philosophy).
+
+`style` takes precedence over `state` when both are provided.
+
+## Positioning at the click point
+
+The context menu has no built-in trigger and no `x`/`y` props. It renders inside a transparent `div` whose `transformOrigin` is `"top left"` — so the panel grows from whatever corner the caller places it at. Use an absolute wrapper positioned at the cursor's right-click coordinates:
+
+```tsx
+import { Cursor } from "@/components/remocn/cursor";
+import { useCursorPath } from "@/components/remocn/use-cursor-path";
+import { ContextMenu } from "@/components/remocn/context-menu";
+import { useContextMenuTransition } from "@/components/remocn/use-context-menu-transition";
+
+const CLICK_X = 400;
+const CLICK_Y = 280;
+
+export const Scene = () => {
+ const cursorStyle = useCursorPath([
+ { at: 0, x: 80, y: 60 },
+ { at: 30, x: CLICK_X, y: CLICK_Y, duration: 26 },
+ { at: 42, x: CLICK_X, y: CLICK_Y, click: true, duration: 0 },
+ ]);
+
+ const menuStyle = useContextMenuTransition([
+ { at: 44, state: "opened", duration: 10 },
+ { at: 92, state: "closed", duration: 10 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ {/* Menu top-left corner = cursor click point */}
+ <div style={{ position: "absolute", left: CLICK_X, top: CLICK_Y }}>
+ <ContextMenu style={menuStyle} />
+ </div>
+ <Cursor style={cursorStyle} variant="pointer" />
+ </div>
+ );
+};
+```
+
+The `click: true` waypoint on the cursor fires a ripple at that frame — schedule the menu's `opened` step 1–2 frames after to let the ripple lead the reveal.
+
+## Items
+
+The panel renders a column of **DropdownMenuItem** rows — one per action. The row atom, its states (`idle`, `hover`, `press`), and the `useDropdownMenuItemTransition` hook are documented under [DropdownMenu](/docs/ui/components/dropdown-menu#items). When you install `context-menu`, the `dropdown-menu-item` atom is automatically pulled in via `registryDependencies` — no separate install needed.
+
+The `ContextMenu` container derives each row's state from `highlightedIndex` and `pressedIndex`, or you can override a row's visual with `itemStyles`:
+
+```tsx
+import { useDropdownMenuItemTransition } from "@/components/remocn/use-dropdown-menu-item-transition";
+import { useCurrentState } from "@/lib/remocn-ui";
+
+const rowState = useCurrentState(
+ [
+ { at: 60, state: "hover" },
+ { at: 72, state: "press" },
+ { at: 82, state: "idle" },
+ ],
+ "idle",
+);
+const rowStyle = useDropdownMenuItemTransition([{ at: 0, state: rowState }]);
+
+<ContextMenu style={menuStyle} itemStyles={[undefined, rowStyle, undefined, undefined]} />
+```
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "state",
+ type: "\"opened\" | \"closed\"",
+ default: "\"closed\"",
+ description: "Current visual state (snap path). State changes snap — no automatic cross-fade.",
+ },
+ {
+ name: "style",
+ type: "ContextMenuStyle",
+ description: "Resolved animated visual (smooth path). Pass an interpolated ContextMenuStyle from useContextMenuTransition. Takes precedence over state when provided.",
+ },
+ {
+ name: "items",
+ type: "string[]",
+ default: "[\"Back\", \"Reload\", \"Save As…\", \"Inspect\"]",
+ description: "Array of action labels rendered as DropdownMenuItem rows.",
+ },
+ {
+ name: "highlightedIndex",
+ type: "number",
+ default: "-1",
+ description: "Index of the row under the pointer (hover state). -1 for none.",
+ },
+ {
+ name: "pressedIndex",
+ type: "number",
+ default: "-1",
+ description: "Index of the row being pressed (press state). -1 for none.",
+ },
+ {
+ name: "itemStyles",
+ type: "(DropdownMenuItemStyle | undefined)[]",
+ description: "Per-row resolved visual override (smooth path). When present it wins over the index-to-state derivation. Drive individual rows with useDropdownMenuItemTransition.",
+ },
+ {
+ 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 panel wrapper element.",
+ },
+ ]}
+/>
diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.json
index faa72e01..9a722c9c 100644
--- a/content/docs/ui/components/meta.json
+++ b/content/docs/ui/components/meta.json
@@ -1,5 +1,5 @@
{
"title": "Components",
"collapsible": false,
- "pages": ["accordion", "alert-dialog", "button", "checkbox", "combobox", "command-menu", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "popover", "progress", "radio", "select", "skeleton", "slider", "spinner", "switch", "tabs", "toast", "tooltip"]
+ "pages": ["accordion", "alert-dialog", "button", "checkbox", "combobox", "command-menu", "context-menu", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "popover", "progress", "radio", "select", "skeleton", "slider", "spinner", "switch", "tabs", "toast", "tooltip"]
}
diff --git a/registry/__index__.tsx b/registry/__index__.tsx
index 15a0ad30..d2b81304 100644
--- a/registry/__index__.tsx
+++ b/registry/__index__.tsx
@@ -159,6 +159,8 @@ import { Combobox } from "@/registry/remocn-ui/combobox";
import { comboboxConfig } from "@/registry/remocn-ui/combobox/config";
import { PopoverPreview } from "@/registry/remocn-ui/popover/preview";
import { popoverConfig } from "@/registry/remocn-ui/popover/config";
+import { ContextMenuPreview } from "@/registry/remocn-ui/context-menu/preview";
+import { contextMenuConfig } from "@/registry/remocn-ui/context-menu/config";
import { ZoomThroughTransition } from "@/registry/remocn/zoom-through-transition";
import { zoomThroughTransitionConfig } from "@/registry/remocn/zoom-through-transition/config";
@@ -387,6 +389,10 @@ const registry: Record<string, RegistryEntry> = {
// popover's customizer Component is the preview-only PopoverPreview wrapper: a
// bare card has no backdrop and would not center as the composition root.
"popover": { Component: PopoverPreview, config: popoverConfig },
+ // context-menu's customizer Component is the preview-only ContextMenuPreview
+ // wrapper: a bare panel (transparent, caller-positioned) would sit top-left,
+ // so the wrapper centers it on a stage.
+ "context-menu": { Component: ContextMenuPreview, config: contextMenuConfig },
"spinner": { Component: Spinner, config: spinnerConfig },
};
diff --git a/registry/remocn-ui/context-menu/__tests__/README.md b/registry/remocn-ui/context-menu/__tests__/README.md
new file mode 100644
index 00000000..67e81851
--- /dev/null
+++ b/registry/remocn-ui/context-menu/__tests__/README.md
@@ -0,0 +1,57 @@
+# context-menu/__tests__
+
+Verification tests for the pure, deterministic surface of the `context-menu` primitive.
+
+## What is tested
+
+| Section | Source | Coverage |
+|---------|--------|----------|
+| `DEFAULT_DURATION` | `use-context-menu-transition.ts` | Constant equals 10 |
+| `contextMenuStyleContext` | `index.tsx` lines 73–82 | panelBg/panelBorder/radius token mapping; itemCtx is non-null object; light/dark independence |
+| `contextMenuStyle` | `index.tsx` lines 89–99 | closed keyframe full fields; opened keyframe full fields; distinct per state; all fields numeric; default arm |
+| `tweenContextMenuStyle` | `use-context-menu-transition.ts` lines 22–32 | t=0 → a; t=1 → b; t=0.5 midpoint; t=0.25 quarter; identity; reverse direction |
+| `resolveContextMenuTransition` | replica of `use-context-menu-transition.ts` lines 46–70 | before first step; at boundary (progress=0); mid-window eased (non-linear); past window; speed contract |
+| `contextMenuConfig.controls` | `config.ts` | state/highlightedIndex/mode types, defaults, options |
+| `contextMenuConfig.snippet` | `config.ts` | import line; structural invariants; items always emitted; default omission; non-default emission; state round-trip |
+
+## What is NOT tested
+
+**Render path** — `ContextMenu` calls `useRemocnTheme` (React context) and renders JSX. Not exercised here.
+
+**`rowState`** — This module-private function (not exported) maps `(i, highlightedIndex, pressedIndex)` to a `DropdownMenuItemState`. Its contract is:
+
+| Priority | Condition | Result |
+|----------|-----------|--------|
+| 1 (highest) | `i === pressedIndex` | `"press"` |
+| 2 | `i === highlightedIndex` | `"hover"` |
+| 3 (default) | otherwise | `"idle"` |
+
+Note: unlike `Select`/`Combobox` there is no `"selected"` state — context menus do not have a persistent selection; press is transient.
+
+**`contextMenuStyleContext` sub-delegation** — The `itemCtx` field is produced by `dropdownMenuItemStyleContext`; that function's correctness is covered by `dropdown-menu/__tests__`. Here it is called only to build the shared `ctx` fixture.
+
+## Animation model
+
+`contextMenuStyle` returns three numeric fields encoding the panel reveal. Unlike `DropdownMenu` (which has a trigger and anchors `transformOrigin` to the top), the context menu grows from the **top-left corner** (the click point) via `transformOrigin: "top left"`:
+
+| State | `opacity` | `scale` | `translateY` |
+|-------|-----------|---------|--------------|
+| `closed` | 0 | 0.95 | -4 |
+| `opened` | 1 | 1.00 | 0 |
+
+`useContextMenuTransition` folds a step list, applies `easings.out` to the linear `progress`, then lerps between the two endpoint presets with `tweenContextMenuStyle`. Because `out(t) = 1-(1-t)³`, the midpoint `t=0.5` eases to `0.875` — confirmed in the mid-window tests: at frame 5 of a 10-frame window, `opacity=0.875`, `scale≈0.99375`, `translateY=-0.5`.
+
+## Snippet items
+
+The snippet always emits `items={...}` with the default item array serialized via `JSON.stringify`. This ensures the preview shows real labels and is consistent regardless of customizer state.
+
+## Determinism grep checklist
+
+Run this on `context-menu/index.tsx` — it must print nothing:
+
+```bash
+grep -nE "useState|useEffect|useCurrentFrame|onClick|onChange|addEventListener|Date\.now|Math\.random|requestAnimationFrame" \
+ registry/remocn-ui/context-menu/index.tsx
+```
+
+The `ContextMenu` component is a pure renderer: no frame reading, no local state, no side effects. Frame reading lives exclusively in `useContextMenuTransition` (`use-context-menu-transition.ts`), which is not imported here.
diff --git a/registry/remocn-ui/context-menu/__tests__/context-menu.test.ts b/registry/remocn-ui/context-menu/__tests__/context-menu.test.ts
new file mode 100644
index 00000000..83bc1ee9
--- /dev/null
+++ b/registry/remocn-ui/context-menu/__tests__/context-menu.test.ts
@@ -0,0 +1,605 @@
+/**
+ * Verification tests for the PURE / DETERMINISTIC parts of `context-menu`.
+ *
+ * Scope:
+ * - registry/remocn-ui/context-menu/index.tsx
+ * contextMenuStyleContext(theme) — pure theme → context derivation
+ * contextMenuStyle(state, ctx) — complete state→visual map
+ * (rowState is module-private — not exported; documented in README)
+ * - registry/remocn-ui/context-menu/use-context-menu-transition.ts
+ * tweenContextMenuStyle(a, b, t) — pure lerp across all three fields
+ * DEFAULT_DURATION constant
+ * useContextMenuTransition resolver — mirrored as resolveContextMenuTransition
+ * with frame injected as `raw` (annotated source lines)
+ * - registry/remocn-ui/context-menu/config.ts
+ * contextMenuConfig.controls wiring + contextMenuConfig.snippet codegen
+ *
+ * The render path (index.tsx) imports `useRemocnTheme` which requires React
+ * context and cannot run headlessly — it is NOT exercised here.
+ * `contextMenuStyleContext` delegates to `dropdownMenuItemStyleContext` for
+ * the item context; that sub-function's correctness is covered by
+ * dropdown-menu/__tests__. Here it is called only to build the shared `ctx`
+ * fixture for `contextMenuStyle`.
+ *
+ * Runner: Bun's built-in test runner (TypeScript-native, no framework dep).
+ * bun test registry/remocn-ui/context-menu/__tests__
+ *
+ * --------------------------------------------------------------------------
+ * IMPORT STRATEGY
+ * --------------------------------------------------------------------------
+ * Relative imports for component source; `@/lib/remocn-ui` alias for core.
+ * `useContextMenuTransition` is NOT imported — it reads `useCurrentFrame()`.
+ * Its pure body is mirrored as `resolveContextMenuTransition` with frame injected.
+ * --------------------------------------------------------------------------
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+ contextMenuStyle,
+ contextMenuStyleContext,
+ type ContextMenuState,
+ type ContextMenuStyle,
+} from "../index";
+import {
+ tweenContextMenuStyle,
+ DEFAULT_DURATION,
+} from "../use-context-menu-transition";
+import { contextMenuConfig } from "../config";
+import { defaultLightTheme, defaultDarkTheme, easings } from "@/lib/remocn-ui";
+import type { Step } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Shared fixtures
+// ===========================================================================
+
+const VALID_STATES: readonly ContextMenuState[] = ["opened", "closed"];
+
+/** Build a shared ctx for style assertions (no React needed — pure function). */
+const ctx = contextMenuStyleContext(defaultLightTheme);
+
+/** Convenience wrapper for snippet(). */
+type SnippetValues = {
+ state?: string;
+ highlightedIndex?: number;
+ mode?: string;
+};
+const snippet = (values: SnippetValues): string =>
+ contextMenuConfig.snippet(values as Record<string, unknown>);
+
+// ===========================================================================
+// 1. DEFAULT_DURATION constant
+// ===========================================================================
+
+describe("DEFAULT_DURATION", () => {
+ it("is 10 frames", () => {
+ expect(DEFAULT_DURATION).toBe(10);
+ });
+});
+
+// ===========================================================================
+// 2. contextMenuStyleContext — pure theme → context derivation
+// MIRROR of index.tsx lines 73-82
+// ===========================================================================
+
+describe("contextMenuStyleContext: maps theme tokens correctly", () => {
+ it("panelBg equals theme.popover", () => {
+ expect(ctx.panelBg).toBe(defaultLightTheme.popover);
+ });
+
+ it("panelBorder equals theme.border", () => {
+ expect(ctx.panelBorder).toBe(defaultLightTheme.border);
+ });
+
+ it("radius equals theme.radius", () => {
+ expect(ctx.radius).toBe(defaultLightTheme.radius);
+ });
+
+ it("itemCtx is a non-null object (delegated to dropdownMenuItemStyleContext)", () => {
+ expect(typeof ctx.itemCtx).toBe("object");
+ expect(ctx.itemCtx).not.toBeNull();
+ });
+});
+
+describe("contextMenuStyleContext: theme independence", () => {
+ const ctxDark = contextMenuStyleContext(defaultDarkTheme);
+
+ it("panelBg differs between light and dark themes", () => {
+ expect(ctx.panelBg).not.toBe(ctxDark.panelBg);
+ });
+
+ it("panelBorder differs between light and dark themes", () => {
+ expect(ctx.panelBorder).not.toBe(ctxDark.panelBorder);
+ });
+});
+
+// ===========================================================================
+// 3. contextMenuStyle — pure (state, ctx) => ContextMenuStyle map
+// MIRROR of index.tsx lines 89-99
+// Every field asserted for both states.
+// ===========================================================================
+
+describe("contextMenuStyle: closed state — off-screen keyframe", () => {
+ const s = contextMenuStyle("closed", ctx);
+
+ it("opacity is 0 (panel invisible)", () => {
+ expect(s.opacity).toBe(0);
+ });
+
+ it("scale is 0.95 (slightly shrunken, grows from top-left)", () => {
+ expect(s.scale).toBeCloseTo(0.95, 10);
+ });
+
+ it("translateY is -4 (lifted 4px above rest position)", () => {
+ expect(s.translateY).toBe(-4);
+ });
+});
+
+describe("contextMenuStyle: opened state — resting keyframe", () => {
+ const s = contextMenuStyle("opened", ctx);
+
+ it("opacity is 1 (panel fully visible)", () => {
+ expect(s.opacity).toBe(1);
+ });
+
+ it("scale is 1 (full size)", () => {
+ expect(s.scale).toBe(1);
+ });
+
+ it("translateY is 0 (at rest position)", () => {
+ expect(s.translateY).toBe(0);
+ });
+});
+
+describe("contextMenuStyle: closed and opened have distinct values on every field", () => {
+ const closed = contextMenuStyle("closed", ctx);
+ const opened = contextMenuStyle("opened", ctx);
+
+ it("opacity: 0 vs 1", () => {
+ expect(closed.opacity).not.toBe(opened.opacity);
+ });
+
+ it("scale: 0.95 vs 1", () => {
+ expect(closed.scale).not.toBe(opened.scale);
+ });
+
+ it("translateY: -4 vs 0", () => {
+ expect(closed.translateY).not.toBe(opened.translateY);
+ });
+});
+
+describe("contextMenuStyle: every state produces a complete ContextMenuStyle", () => {
+ it("all three fields are numeric for every state", () => {
+ for (const state of VALID_STATES) {
+ const s = contextMenuStyle(state, ctx);
+ expect(typeof s.opacity).toBe("number");
+ expect(typeof s.scale).toBe("number");
+ expect(typeof s.translateY).toBe("number");
+ }
+ });
+});
+
+describe("contextMenuStyle: unknown state falls through to closed preset", () => {
+ // The switch has only an explicit 'opened' arm; default → closed
+ it("'closed' returns opacity=0 (via default arm)", () => {
+ expect(contextMenuStyle("closed", ctx).opacity).toBe(0);
+ });
+});
+
+// ===========================================================================
+// 4. tweenContextMenuStyle — pure lerp across all three numeric fields
+// MIRROR of use-context-menu-transition.ts lines 22-32
+// All fields are numbers — straight lerp on everything.
+// ===========================================================================
+
+describe("tweenContextMenuStyle: t=0 returns values equal to `a`", () => {
+ const a = contextMenuStyle("closed", ctx);
+ const b = contextMenuStyle("opened", ctx);
+ const r = tweenContextMenuStyle(a, b, 0);
+
+ it("opacity equals a.opacity at t=0", () => {
+ expect(r.opacity).toBeCloseTo(a.opacity, 10);
+ });
+
+ it("scale equals a.scale at t=0", () => {
+ expect(r.scale).toBeCloseTo(a.scale, 10);
+ });
+
+ it("translateY equals a.translateY at t=0", () => {
+ expect(r.translateY).toBeCloseTo(a.translateY, 10);
+ });
+});
+
+describe("tweenContextMenuStyle: t=1 returns values equal to `b`", () => {
+ const a = contextMenuStyle("closed", ctx);
+ const b = contextMenuStyle("opened", ctx);
+ const r = tweenContextMenuStyle(a, b, 1);
+
+ it("opacity equals b.opacity at t=1", () => {
+ expect(r.opacity).toBeCloseTo(b.opacity, 10);
+ });
+
+ it("scale equals b.scale at t=1", () => {
+ expect(r.scale).toBeCloseTo(b.scale, 10);
+ });
+
+ it("translateY equals b.translateY at t=1", () => {
+ expect(r.translateY).toBeCloseTo(b.translateY, 10);
+ });
+});
+
+describe("tweenContextMenuStyle: t=0.5 midpoint (closed → opened)", () => {
+ // closed: opacity=0, scale=0.95, translateY=-4
+ // opened: opacity=1, scale=1, translateY=0
+ // midpoint: opacity=0.5, scale=0.975, translateY=-2
+ const a = contextMenuStyle("closed", ctx);
+ const b = contextMenuStyle("opened", ctx);
+ const r = tweenContextMenuStyle(a, b, 0.5);
+
+ it("opacity midpoint: 0 → 1 gives 0.5", () => {
+ expect(r.opacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("scale midpoint: 0.95 → 1 gives 0.975", () => {
+ expect(r.scale).toBeCloseTo(0.975, 10);
+ });
+
+ it("translateY midpoint: -4 → 0 gives -2", () => {
+ expect(r.translateY).toBeCloseTo(-2, 10);
+ });
+});
+
+describe("tweenContextMenuStyle: t=0.25 quarter-point (closed → opened)", () => {
+ // opacity: 0.25, scale: 0.95+0.05*0.25=0.9625, translateY: -4+4*0.25=-3
+ const a = contextMenuStyle("closed", ctx);
+ const b = contextMenuStyle("opened", ctx);
+ const r = tweenContextMenuStyle(a, b, 0.25);
+
+ it("opacity at t=0.25 is 0.25", () => {
+ expect(r.opacity).toBeCloseTo(0.25, 10);
+ });
+
+ it("scale at t=0.25 is 0.9625", () => {
+ expect(r.scale).toBeCloseTo(0.9625, 10);
+ });
+
+ it("translateY at t=0.25 is -3", () => {
+ expect(r.translateY).toBeCloseTo(-3, 10);
+ });
+});
+
+describe("tweenContextMenuStyle: identity (a === b)", () => {
+ const s = contextMenuStyle("opened", ctx);
+
+ it("all fields unchanged when both endpoints are the same", () => {
+ const r = tweenContextMenuStyle(s, s, 0.5);
+ expect(r.opacity).toBeCloseTo(s.opacity, 10);
+ expect(r.scale).toBeCloseTo(s.scale, 10);
+ expect(r.translateY).toBeCloseTo(s.translateY, 10);
+ });
+});
+
+describe("tweenContextMenuStyle: reverse direction (opened → closed)", () => {
+ const a = contextMenuStyle("opened", ctx);
+ const b = contextMenuStyle("closed", ctx);
+ const r = tweenContextMenuStyle(a, b, 0.5);
+
+ it("opacity midpoint: 1 → 0 gives 0.5", () => {
+ expect(r.opacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("translateY midpoint: 0 → -4 gives -2", () => {
+ expect(r.translateY).toBeCloseTo(-2, 10);
+ });
+});
+
+// ===========================================================================
+// 5. useContextMenuTransition resolver replica
+// MIRRORS use-context-menu-transition.ts lines 46-70.
+// `useContextMenuTransition` calls `useStateTransition` (reads useCurrentFrame())
+// then applies `easings.out(progress)` and `tweenContextMenuStyle`.
+// We inject `raw` in place of useCurrentFrame().
+//
+// Key additional contract: progress is eased with `easings.out` before the
+// tween, making the result non-linear. out(0.5) = 0.875.
+//
+// MAINTENANCE CONTRACT: if use-context-menu-transition.ts lines 46-70 change,
+// update this replica in lockstep. Annotated source lines below.
+// ===========================================================================
+
+/** MIRROR of core/timeline.ts:clamp01. */
+function clamp01(t: number): number {
+ return Math.max(0, Math.min(1, t));
+}
+
+/**
+ * MIRROR of timeline.ts:useStateTransition pure resolver body.
+ * `raw` is injected in place of useCurrentFrame().
+ */
+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 ? clamp01((effectiveFrame - to.at) / dur) : 1;
+ return { from: from ? from.state : defaultState, to: to.state, progress };
+}
+
+/**
+ * MIRROR of use-context-menu-transition.ts:useContextMenuTransition (lines 46-70).
+ * `raw` is injected in place of useCurrentFrame().
+ * Annotated source lines:
+ * lines 51-55: destructure opts (speed, defaultDuration)
+ * lines 58-63: useStateTransition (mirrored as resolveStateTransition)
+ * line 64: t = easings.out(progress) ← MIRROR line 64
+ * lines 65-69: tweenContextMenuStyle(from, to, t) ← MIRROR lines 65-69
+ */
+function resolveContextMenuTransition(
+ raw: number, // injected useCurrentFrame() — MIRROR line 58
+ steps: Step<ContextMenuState>[],
+ speed = 1,
+ defaultDuration = DEFAULT_DURATION,
+): ContextMenuStyle & { from: ContextMenuState; to: ContextMenuState; progress: number } {
+ const { from, to, progress } = resolveStateTransition( // MIRROR lines 58-63
+ raw,
+ steps,
+ "closed",
+ speed,
+ defaultDuration,
+ );
+ const t = easings.out(progress); // MIRROR line 64
+ const style = tweenContextMenuStyle( // MIRROR lines 65-69
+ contextMenuStyle(from as ContextMenuState, ctx),
+ contextMenuStyle(to as ContextMenuState, ctx),
+ t,
+ );
+ return { ...style, from: from as ContextMenuState, to: to as ContextMenuState, progress };
+}
+
+// ---------------------------------------------------------------------------
+// Before any step: holds at closed (progress=1, tween(closed,closed,out(1)))
+// ---------------------------------------------------------------------------
+
+describe("resolveContextMenuTransition: before any step — holds at closed", () => {
+ it("returns the closed style when no steps have started", () => {
+ const r = resolveContextMenuTransition(0, []);
+ const closed = contextMenuStyle("closed", ctx);
+ expect(r.opacity).toBeCloseTo(closed.opacity, 10);
+ expect(r.scale).toBeCloseTo(closed.scale, 10);
+ expect(r.translateY).toBeCloseTo(closed.translateY, 10);
+ });
+
+ it("from and to are both 'closed' before any step", () => {
+ const r = resolveContextMenuTransition(0, []);
+ expect(r.from).toBe("closed");
+ expect(r.to).toBe("closed");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Exactly at a step boundary: progress=0, t=out(0)=0 → closed style
+// ---------------------------------------------------------------------------
+
+describe("resolveContextMenuTransition: exactly at closed→opened step boundary", () => {
+ const steps: Step<ContextMenuState>[] = [{ at: 10, state: "opened" }];
+
+ it("at raw=10, progress=0, t=out(0)=0 → style equals closed (from)", () => {
+ const r = resolveContextMenuTransition(10, steps);
+ const closed = contextMenuStyle("closed", ctx);
+ expect(r.progress).toBe(0);
+ expect(r.opacity).toBeCloseTo(closed.opacity, 10);
+ expect(r.scale).toBeCloseTo(closed.scale, 10);
+ expect(r.translateY).toBeCloseTo(closed.translateY, 10);
+ });
+
+ it("from='closed', to='opened' at the step boundary", () => {
+ const r = resolveContextMenuTransition(10, steps);
+ expect(r.from).toBe("closed");
+ expect(r.to).toBe("opened");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Mid-window: easings.out applied — non-linear (not raw 0.5)
+// step at=0, duration=10, raw=5: progress=0.5, out(0.5)=0.875
+// opacity: 0.875, scale: 0.95+0.05*0.875=0.99375, translateY: -4+4*0.875=-0.5
+// ---------------------------------------------------------------------------
+
+describe("resolveContextMenuTransition: mid-window uses easings.out (not linear)", () => {
+ const steps: Step<ContextMenuState>[] = [{ at: 0, state: "opened" }];
+
+ it("opacity at raw=5 is out(0.5)=0.875 (not linear 0.5)", () => {
+ const r = resolveContextMenuTransition(5, steps, 1, 10);
+ const t = easings.out(0.5); // 0.875
+ expect(r.opacity).toBeCloseTo(t, 8);
+ });
+
+ it("scale at raw=5 is 0.95 + 0.05*out(0.5) = 0.99375", () => {
+ const r = resolveContextMenuTransition(5, steps, 1, 10);
+ const t = easings.out(0.5);
+ const expected = 0.95 + (1 - 0.95) * t; // 0.99375
+ expect(r.scale).toBeCloseTo(expected, 8);
+ });
+
+ it("translateY at raw=5 is -4*(1-out(0.5)) = -0.5", () => {
+ const r = resolveContextMenuTransition(5, steps, 1, 10);
+ const t = easings.out(0.5);
+ const expected = -4 + (0 - (-4)) * t; // -4 + 3.5 = -0.5
+ expect(r.translateY).toBeCloseTo(expected, 8);
+ });
+
+ it("easing confirmed non-linear: opacity at raw=5 is not 0.5", () => {
+ const r = resolveContextMenuTransition(5, steps, 1, 10);
+ expect(r.opacity).not.toBeCloseTo(0.5, 2);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Past the window: fully opened
+// ---------------------------------------------------------------------------
+
+describe("resolveContextMenuTransition: past the window → fully opened", () => {
+ const steps: Step<ContextMenuState>[] = [{ at: 0, state: "opened" }];
+
+ it("opacity is 1 after DEFAULT_DURATION frames", () => {
+ expect(resolveContextMenuTransition(DEFAULT_DURATION, steps).opacity).toBeCloseTo(1, 10);
+ });
+
+ it("scale is 1 after DEFAULT_DURATION frames", () => {
+ expect(resolveContextMenuTransition(DEFAULT_DURATION, steps).scale).toBeCloseTo(1, 10);
+ });
+
+ it("translateY is 0 after DEFAULT_DURATION frames", () => {
+ expect(resolveContextMenuTransition(DEFAULT_DURATION, steps).translateY).toBeCloseTo(0, 10);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Speed contract
+// ---------------------------------------------------------------------------
+
+describe("resolveContextMenuTransition: speed contract", () => {
+ const steps: Step<ContextMenuState>[] = [{ at: 10, state: "opened" }];
+
+ it("speed=2: step at=10 fires at raw=5 (effectiveFrame=10)", () => {
+ expect(resolveContextMenuTransition(5, steps, 2).to).toBe("opened");
+ });
+
+ it("speed=2: step at=10 has NOT fired at raw=4 (effectiveFrame=8 < 10)", () => {
+ expect(resolveContextMenuTransition(4, steps, 2).to).toBe("closed");
+ });
+});
+
+// ===========================================================================
+// 6. contextMenuConfig.controls — customizer control wiring
+// ===========================================================================
+
+describe("contextMenuConfig.controls: state", () => {
+ it("state is a select control", () => {
+ expect(contextMenuConfig.controls.state.type).toBe("select");
+ });
+
+ it("state options are ['opened','closed']", () => {
+ const ctrl = contextMenuConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["opened", "closed"]);
+ });
+
+ it("state default is 'opened' (shows the revealed menu in preview)", () => {
+ expect(contextMenuConfig.controls.state.default).toBe("opened");
+ });
+
+ it("every state option is a valid ContextMenuState", () => {
+ const ctrl = contextMenuConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const opt of ctrl.options) {
+ expect(VALID_STATES).toContain(opt as ContextMenuState);
+ }
+ });
+});
+
+describe("contextMenuConfig.controls: highlightedIndex", () => {
+ it("highlightedIndex is a number control", () => {
+ expect(contextMenuConfig.controls.highlightedIndex.type).toBe("number");
+ });
+
+ it("highlightedIndex default is 1 (second row pre-highlighted)", () => {
+ expect(contextMenuConfig.controls.highlightedIndex.default).toBe(1);
+ });
+
+ it("highlightedIndex min is -1", () => {
+ const ctrl = contextMenuConfig.controls.highlightedIndex;
+ if (ctrl.type !== "number") throw new Error("expected number");
+ expect(ctrl.min).toBe(-1);
+ });
+});
+
+describe("contextMenuConfig.controls: mode", () => {
+ it("mode is a select control", () => {
+ expect(contextMenuConfig.controls.mode.type).toBe("select");
+ });
+
+ it("mode default is 'light'", () => {
+ expect(contextMenuConfig.controls.mode.default).toBe("light");
+ });
+});
+
+// ===========================================================================
+// 7. contextMenuConfig.snippet — pure JSX string builder
+// ===========================================================================
+
+describe("contextMenuConfig.snippet: import line", () => {
+ it("includes 'import { ContextMenu }' from the correct path", () => {
+ const out = snippet({ state: "opened" });
+ expect(out).toContain("import { ContextMenu }");
+ expect(out).toContain('from "@/components/remocn/context-menu"');
+ });
+});
+
+describe("contextMenuConfig.snippet: structural invariants", () => {
+ it("contains a <ContextMenu JSX element", () => {
+ expect(snippet({ state: "opened" })).toContain("<ContextMenu");
+ });
+
+ it("ends with a self-closing />", () => {
+ expect(snippet({ state: "opened" }).trimEnd().endsWith("/>")).toBe(true);
+ });
+
+ it("state is always emitted", () => {
+ for (const state of VALID_STATES) {
+ expect(snippet({ state })).toContain(`state="${state}"`);
+ }
+ });
+
+ it("items array is always emitted (shows default items)", () => {
+ const out = snippet({ state: "opened" });
+ expect(out).toContain("items={");
+ expect(out).toContain("Back");
+ expect(out).toContain("Reload");
+ });
+});
+
+describe("contextMenuConfig.snippet: default props are omitted", () => {
+ it("omits highlightedIndex when it equals -1 (no highlight)", () => {
+ expect(snippet({ state: "opened", highlightedIndex: -1 })).not.toContain("highlightedIndex=");
+ });
+
+ it("omits mode when it equals 'light'", () => {
+ expect(snippet({ state: "opened", mode: "light" })).not.toContain("mode=");
+ });
+});
+
+describe("contextMenuConfig.snippet: non-default props are emitted", () => {
+ it("emits highlightedIndex when not -1 (e.g. 1 = second row)", () => {
+ expect(snippet({ state: "opened", highlightedIndex: 1 })).toContain("highlightedIndex={1}");
+ });
+
+ it("emits highlightedIndex=0 when first row is highlighted", () => {
+ expect(snippet({ state: "opened", highlightedIndex: 0 })).toContain("highlightedIndex={0}");
+ });
+
+ it("emits mode='dark' when non-default", () => {
+ expect(snippet({ state: "opened", mode: "dark" })).toContain('mode="dark"');
+ });
+});
+
+describe("contextMenuConfig.snippet: state options round-trip", () => {
+ it("emits the correct state for every control option", () => {
+ const ctrl = contextMenuConfig.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/context-menu/config.ts b/registry/remocn-ui/context-menu/config.ts
new file mode 100644
index 00000000..2730234d
--- /dev/null
+++ b/registry/remocn-ui/context-menu/config.ts
@@ -0,0 +1,55 @@
+import { type ComponentConfig, FPS, H, W } from "@/lib/customizer-config";
+import type { ContextMenuState } from "@/registry/remocn-ui/context-menu";
+
+const DEFAULT_ITEMS = ["Back", "Reload", "Save As…", "Inspect"];
+
+export const contextMenuConfig: ComponentConfig = {
+ componentName: "ContextMenu",
+ importPath: "@/components/remocn/context-menu",
+ controls: {
+ state: {
+ type: "select",
+ // Default to `opened` so the preview shows the revealed menu.
+ default: "opened",
+ options: ["opened", "closed"],
+ label: "State",
+ },
+ highlightedIndex: {
+ type: "number",
+ default: 1,
+ min: -1,
+ max: 5,
+ step: 1,
+ label: "Highlighted Index",
+ },
+ 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 ContextMenuState) ?? "opened";
+ const highlightedIndex = values.highlightedIndex as number | undefined;
+ const mode = values.mode as string | undefined;
+
+ const props: string[] = [` state="${state}"`];
+ if (highlightedIndex !== undefined && highlightedIndex !== -1)
+ props.push(` highlightedIndex={${highlightedIndex}}`);
+ if (mode !== undefined && mode !== "light")
+ props.push(` mode="${mode}"`);
+
+ const itemsLiteral = JSON.stringify(DEFAULT_ITEMS);
+ return `import { ContextMenu } from "@/components/remocn/context-menu";
+
+<ContextMenu
+${props.join("\n")}
+ items={${itemsLiteral}}
+/>`;
+ },
+};
diff --git a/registry/remocn-ui/context-menu/index.tsx b/registry/remocn-ui/context-menu/index.tsx
new file mode 100644
index 00000000..d53b88f0
--- /dev/null
+++ b/registry/remocn-ui/context-menu/index.tsx
@@ -0,0 +1,173 @@
+"use client";
+
+import { type RemocnTheme, useRemocnTheme } from "@/lib/remocn-ui";
+import {
+ DropdownMenuItemRow,
+ dropdownMenuItemStyle,
+ dropdownMenuItemStyleContext,
+ type DropdownMenuItemState,
+ type DropdownMenuItemStyle,
+ type DropdownMenuItemStyleContext,
+} from "@/components/remocn/dropdown-menu-item";
+
+export type ContextMenuState = "opened" | "closed";
+
+export interface ContextMenuProps {
+ /** Current visual state (snap path). State changes snap (no enter-tweens). */
+ state?: ContextMenuState;
+ /**
+ * Resolved animated visual (smooth path). When provided, takes precedence over
+ * `state` — feed it an interpolated `ContextMenuStyle` from `useContextMenuTransition`.
+ */
+ style?: ContextMenuStyle;
+ /** Menu rows — plain string labels (same format as DropdownMenu). */
+ items?: string[];
+ /** Row currently highlighted (hover); `-1` for none. */
+ highlightedIndex?: number;
+ /** Row currently pressed; `-1` for none. */
+ pressedIndex?: number;
+ /**
+ * Smooth per-row override. When an entry is present it wins over the
+ * index→state derivation, letting the example tween a single row.
+ */
+ itemStyles?: (DropdownMenuItemStyle | undefined)[];
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ className?: string;
+}
+
+/** Panel width (px). */
+const WIDTH = 200;
+
+// ===========================================================================
+// Context-menu visual — the COMPLETE animated look for a moment in time. A
+// `state` is a named preset of this visual (`contextMenuStyle`); the smooth path
+// feeds an interpolated `ContextMenuStyle` straight through. The component is a
+// pure renderer of whichever style it receives. Unlike DropdownMenu there is NO
+// trigger — a context menu opens AT the click point, so it scales from its
+// top-left corner and the CALLER positions it (transparent placement).
+// ===========================================================================
+
+export interface ContextMenuStyle {
+ /** Panel fade 0 (closed) → 1 (opened). */
+ opacity: number;
+ /** Panel zoom 0.95 (closed) → 1 (opened), growing from the top-left corner. */
+ scale: number;
+ /** Panel lift -4 (closed) → 0 (opened) px. */
+ translateY: number;
+}
+
+/** Concrete colors for the active theme, resolved once per render. */
+export interface ContextMenuStyleContext {
+ panelBg: string;
+ panelBorder: string;
+ radius: number;
+ /** Row presets for the panel items. */
+ itemCtx: DropdownMenuItemStyleContext;
+}
+
+/**
+ * Derive the concrete colors for a theme. Pure — call it once and reuse the
+ * result for every `contextMenuStyle(state, ctx)` preset.
+ */
+export function contextMenuStyleContext(
+ theme: RemocnTheme,
+): ContextMenuStyleContext {
+ return {
+ panelBg: theme.popover,
+ panelBorder: theme.border,
+ radius: theme.radius,
+ itemCtx: dropdownMenuItemStyleContext(theme),
+ };
+}
+
+/**
+ * The COMPLETE resting visual for a state — a pure
+ * `(state, ctx) => ContextMenuStyle` map. To change how a state looks, edit one
+ * entry.
+ */
+export function contextMenuStyle(
+ state: ContextMenuState,
+ _ctx: ContextMenuStyleContext,
+): ContextMenuStyle {
+ switch (state) {
+ case "opened":
+ return { opacity: 1, scale: 1, translateY: 0 };
+ default:
+ return { opacity: 0, scale: 0.95, translateY: -4 };
+ }
+}
+
+/** Resolve one row's state from the index props. */
+function rowState(
+ i: number,
+ highlightedIndex: number,
+ pressedIndex: number,
+): DropdownMenuItemState {
+ if (i === pressedIndex) return "press";
+ if (i === highlightedIndex) return "hover";
+ return "idle";
+}
+
+export function ContextMenu({
+ state = "closed",
+ style,
+ items = ["Back", "Reload", "Save As…", "Inspect"],
+ highlightedIndex = -1,
+ pressedIndex = -1,
+ itemStyles,
+ theme: themeOverride,
+ mode,
+ className,
+}: ContextMenuProps) {
+ const theme = useRemocnTheme(themeOverride, mode);
+ const ctx = contextMenuStyleContext(theme);
+ const v = style ?? contextMenuStyle(state, ctx);
+
+ return (
+ // TRANSPARENT wrapper — a context menu opens AT the click point; the caller
+ // positions this with an absolute wrapper (no x/y props here). It paints no
+ // opaque background and does not center the panel itself.
+ <div
+ className={className}
+ style={{
+ width: WIDTH,
+ opacity: v.opacity,
+ // Grows from the top-left corner — where the cursor "clicked".
+ transformOrigin: "top left",
+ transform: `translateY(${v.translateY}px) scale(${v.scale})`,
+ background: ctx.panelBg,
+ border: `1px solid ${ctx.panelBorder}`,
+ borderRadius: ctx.radius + 2,
+ padding: 4,
+ display: "flex",
+ flexDirection: "column",
+ gap: 2,
+ boxShadow: "0 12px 32px -8px rgba(0,0,0,0.18)",
+ boxSizing: "border-box",
+ fontFamily:
+ "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif",
+ }}
+ >
+ {items.map((item, i) => {
+ const override = itemStyles?.[i];
+ const rowStyle =
+ override ??
+ dropdownMenuItemStyle(
+ rowState(i, highlightedIndex, pressedIndex),
+ ctx.itemCtx,
+ );
+ return (
+ <DropdownMenuItemRow
+ key={item}
+ style={rowStyle}
+ label={item}
+ width={WIDTH - 8}
+ theme={themeOverride}
+ mode={mode}
+ />
+ );
+ })}
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/context-menu/preview.tsx b/registry/remocn-ui/context-menu/preview.tsx
new file mode 100644
index 00000000..2f52dadf
--- /dev/null
+++ b/registry/remocn-ui/context-menu/preview.tsx
@@ -0,0 +1,41 @@
+"use client";
+
+import { useRemocnTheme } from "@/lib/remocn-ui";
+import { ContextMenu, type ContextMenuState } from "@/registry/remocn-ui/context-menu";
+
+export interface ContextMenuPreviewProps {
+ state?: ContextMenuState;
+ highlightedIndex?: number;
+ mode?: "light" | "dark";
+}
+
+/**
+ * Preview-only wrapper for the customizer. The shipped `ContextMenu` is a
+ * placement-agnostic panel that opens at the click point — the caller positions
+ * it with an absolute wrapper. The customizer Player renders its `component` as
+ * the composition root, so a bare panel would sit top-left; this thin wrapper
+ * centers it on a theme-background stage just for the preview. NOT shipped: not
+ * listed in registry.json files.
+ */
+export function ContextMenuPreview({
+ state = "opened",
+ highlightedIndex = 1,
+ mode,
+}: ContextMenuPreviewProps) {
+ const theme = useRemocnTheme(undefined, mode);
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ background: theme.background,
+ }}
+ >
+ <ContextMenu state={state} highlightedIndex={highlightedIndex} mode={mode} />
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/context-menu/use-context-menu-transition.ts b/registry/remocn-ui/context-menu/use-context-menu-transition.ts
new file mode 100644
index 00000000..fc141d33
--- /dev/null
+++ b/registry/remocn-ui/context-menu/use-context-menu-transition.ts
@@ -0,0 +1,70 @@
+"use client";
+
+import {
+ easings,
+ type RemocnTheme,
+ type Step,
+ useRemocnTheme,
+ useStateTransition,
+} from "@/lib/remocn-ui";
+import {
+ contextMenuStyle,
+ contextMenuStyleContext,
+ type ContextMenuState,
+ type ContextMenuStyle,
+} from "@/components/remocn/context-menu";
+// ^ 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 context-menu visuals: all fields are numbers, so a straight lerp. */
+export function tweenContextMenuStyle(
+ a: ContextMenuStyle,
+ b: ContextMenuStyle,
+ t: number,
+): ContextMenuStyle {
+ return {
+ opacity: a.opacity + (b.opacity - a.opacity) * t,
+ scale: a.scale + (b.scale - a.scale) * t,
+ translateY: a.translateY + (b.translateY - a.translateY) * t,
+ };
+}
+
+export interface ContextMenuTransitionOptions {
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ speed?: number;
+ defaultDuration?: number;
+}
+
+/**
+ * Timeline → resolved (eased, tweened) ContextMenuStyle. The CALLER invokes
+ * this; it reads the frame, the `<ContextMenu>` component does not. Feed the
+ * result to `<ContextMenu style={...} />` for a smooth open/close.
+ */
+export function useContextMenuTransition(
+ steps: Step<ContextMenuState>[],
+ opts: ContextMenuTransitionOptions = {},
+): ContextMenuStyle {
+ const {
+ theme: themeOverride,
+ mode,
+ speed = 1,
+ defaultDuration = DEFAULT_DURATION,
+ } = opts;
+ const theme = useRemocnTheme(themeOverride, mode);
+ const ctx = contextMenuStyleContext(theme);
+ const { from, to, progress } = useStateTransition(
+ steps,
+ "closed",
+ speed,
+ defaultDuration,
+ );
+ const t = easings.out(progress);
+ return tweenContextMenuStyle(
+ contextMenuStyle(from, ctx),
+ contextMenuStyle(to, ctx),
+ t,
+ );
+}
diff --git a/registry/remocn-ui/registry.json b/registry/remocn-ui/registry.json
index 4af5eae7..07d415e7 100644
--- a/registry/remocn-ui/registry.json
+++ b/registry/remocn-ui/registry.json
@@ -571,6 +571,26 @@
"target": "components/remocn/use-popover-transition.ts"
}
]
+ },
+ {
+ "name": "context-menu",
+ "type": "registry:component",
+ "title": "UI Context Menu",
+ "description": "A right-click context menu whose opened/closed state is a pure function of the timeline; the panel scales from its top-left corner (the click point) with a fade + lift. No trigger — the caller positions it. Rows reuse the DropdownMenuItem row; items are plain string labels.",
+ "dependencies": ["remotion"],
+ "registryDependencies": ["remocn-ui", "dropdown-menu-item"],
+ "files": [
+ {
+ "path": "context-menu/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/context-menu.tsx"
+ },
+ {
+ "path": "context-menu/use-context-menu-transition.ts",
+ "type": "registry:component",
+ "target": "components/remocn/use-context-menu-transition.ts"
+ }
+ ]
}
]
}