Skip to content

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

feat: added command pallette

dev_wandrya9dae6bc9708
diff --git a/components/docs/examples/command-menu-example.tsx b/components/docs/examples/command-menu-example.tsx
new file mode 100644
index 00000000..839192b2
--- /dev/null
+++ b/components/docs/examples/command-menu-example.tsx
@@ -0,0 +1,99 @@
+"use client";
+
+import { useCurrentFrame } from "remotion";
+import { revealCount } from "@/lib/remocn-ui";
+import { CommandMenu, filterCommandItems } from "@/registry/remocn-ui/command-menu";
+import { useCommandMenuTransition } from "@/registry/remocn-ui/command-menu/use-command-menu-transition";
+import { useCommandMenuItemTransition } from "@/registry/remocn-ui/command-menu-item/use-command-menu-item-transition";
+
+// Full query that gets typed out character by character.
+const QUERY = "settings";
+// Typing starts at this frame; 8 chars at 4 cps @ 30fps = 60 frames.
+const TYPE_START = 20;
+const FPS = 30;
+const CPS = 4;
+
+export const CommandMenuExampleScene = () => {
+ const frame = useCurrentFrame();
+
+ // Panel: closed → opened at frame 16, then closed again at frame 108.
+ const panelStyle = useCommandMenuTransition([
+ { at: 16, state: "opened", duration: 16 },
+ { at: 108, state: "closed", duration: 12 },
+ ]);
+
+ // Reveal query characters from TYPE_START onward.
+ const revealed = revealCount(
+ Math.max(0, frame - TYPE_START),
+ FPS,
+ QUERY.length,
+ CPS,
+ );
+
+ // The filtered list shrinks as more characters are revealed. We animate the
+ // first row of the filtered list (which becomes "Settings" once "set" is typed).
+ const itemStyle = useCommandMenuItemTransition([
+ { at: 84, state: "hover", duration: 8 },
+ { at: 92, state: "press", duration: 6 },
+ { at: 100, state: "selected", duration: 8 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <CommandMenu
+ style={panelStyle}
+ query={QUERY}
+ revealCount={revealed}
+ itemStyles={[itemStyle]}
+ />
+ </div>
+ );
+};
+
+export const commandMenuExampleCode = `import { useCurrentFrame } from "remotion";
+import { revealCount } from "@/lib/remocn-ui";
+import { CommandMenu } from "@/components/remocn/command-menu";
+import { useCommandMenuTransition } from "@/components/remocn/use-command-menu-transition";
+import { useCommandMenuItemTransition } from "@/components/remocn/use-command-menu-item-transition";
+
+const QUERY = "settings";
+const TYPE_START = 20;
+const FPS = 30;
+const CPS = 4;
+
+export const Scene = () => {
+ const frame = useCurrentFrame();
+
+ // Panel zooms in, holds while query is typed and a row is selected, then closes.
+ const panelStyle = useCommandMenuTransition([
+ { at: 16, state: "opened", duration: 16 },
+ { at: 108, state: "closed", duration: 12 },
+ ]);
+
+ // revealCount drives how many characters of QUERY are visible — the component
+ // filters the list as more characters appear.
+ const revealed = revealCount(
+ Math.max(0, frame - TYPE_START),
+ FPS,
+ QUERY.length,
+ CPS,
+ );
+
+ // Animate the first row of the filtered list: idle → hover → press → selected.
+ const itemStyle = useCommandMenuItemTransition([
+ { at: 84, state: "hover", duration: 8 },
+ { at: 92, state: "press", duration: 6 },
+ { at: 100, state: "selected", duration: 8 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <CommandMenu
+ style={panelStyle}
+ query={QUERY}
+ revealCount={revealed}
+ itemStyles={[itemStyle]}
+ />
+ </div>
+ );
+};`;
diff --git a/components/docs/examples/index.tsx b/components/docs/examples/index.tsx
index 77f14846..809eb246 100644
--- a/components/docs/examples/index.tsx
+++ b/components/docs/examples/index.tsx
@@ -27,6 +27,10 @@ import {
import { TabsExampleScene, tabsExampleCode } from "./tabs-example";
import { CursorExampleScene, cursorExampleCode } from "./cursor-example";
import { ToastExampleScene, toastExampleCode } from "./toast-example";
+import {
+ CommandMenuExampleScene,
+ commandMenuExampleCode,
+} from "./command-menu-example";
export interface ExampleEntry {
Component: ComponentType;
@@ -168,4 +172,13 @@ export const examples: Record<string, ExampleEntry> = {
width: W,
height: H,
},
+ "command-menu-example": {
+ Component: CommandMenuExampleScene,
+ code: commandMenuExampleCode,
+ // Panel closes at 108 + dur 12 = 120; a short settle then loop.
+ durationInFrames: 130,
+ fps: FPS,
+ width: W,
+ height: H,
+ },
};
diff --git a/content/docs/ui/components/command-menu.mdx b/content/docs/ui/components/command-menu.mdx
new file mode 100644
index 00000000..410d66bb
--- /dev/null
+++ b/content/docs/ui/components/command-menu.mdx
@@ -0,0 +1,250 @@
+---
+title: Command Menu
+description: A keyboard-driven command palette with backdrop, typing animation, and row selection
+---
+
+<ComponentPreview name="command-menu" />
+
+A state atom representing a command palette 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. The panel zooms in from 0.96 scale with a backdrop dim and fades fully in on open; reverses on close.
+
+## Installation
+
+<InstallBlock name="command-menu" />
+
+<Note>
+Installing `command-menu` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) and the `command-menu-item` atom via `registryDependencies` (`["remocn-ui", "command-menu-item"]`). You do not need to install either separately.
+</Note>
+
+## Example
+
+<LiveExample name="command-menu-example" />
+
+## States
+
+`CommandMenuState` is:
+
+```ts
+type CommandMenuState =
+ | "opened" // backdrop opaque, panel opacity 1, scale 1, translateY 0
+ | "closed" // backdrop transparent, panel opacity 0, scale 0.96, translateY 8px
+```
+
+`opened` reveals the full panel with backdrop dim. `closed` hides the panel and clears the backdrop.
+
+## 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 { CommandMenu } from "@/components/remocn/command-menu";
+
+export const Scene = () => (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <CommandMenu state="opened" query="set" />
+ </div>
+);
+```
+
+To drive state from the timeline, use `useCurrentState`:
+
+```tsx
+import { useCurrentState } from "@/lib/remocn-ui";
+import { CommandMenu } from "@/components/remocn/command-menu";
+
+export const Scene = () => {
+ const state = useCurrentState(
+ [
+ { at: 16, state: "opened" },
+ { at: 96, state: "closed" },
+ ],
+ "closed",
+ );
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <CommandMenu state={state} />
+ </div>
+ );
+};
+```
+
+Each `at` is a **Sequence-local authored frame**. State persists between steps: `opened` at frame 16 keeps the panel visible until `closed` fires at frame 96. 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 `useCommandMenuTransition` from the copied `use-command-menu-transition.ts` file. It reads the frame, interpolates between state presets, and returns a resolved `CommandMenuStyle` — pass it to the `style` prop:
+
+```tsx
+import { CommandMenu } from "@/components/remocn/command-menu";
+import { useCommandMenuTransition } from "@/components/remocn/use-command-menu-transition";
+
+export const Scene = () => {
+ const style = useCommandMenuTransition([
+ { at: 16, state: "opened", duration: 16 },
+ { at: 96, state: "closed", duration: 12 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <CommandMenu style={style} />
+ </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-command-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.
+
+## Typing and filtering
+
+The `query` prop holds the full search string. The `revealCount` prop controls how many characters of `query` are currently shown — the panel filters the item list against the visible prefix and shows an empty state when nothing matches.
+
+Use `revealCount` from `@/lib/remocn-ui` to compute the reveal from the timeline frame:
+
+```tsx
+import { useCurrentFrame } from "remotion";
+import { revealCount } from "@/lib/remocn-ui";
+import { CommandMenu } from "@/components/remocn/command-menu";
+import { useCommandMenuTransition } from "@/components/remocn/use-command-menu-transition";
+
+const QUERY = "settings";
+
+export const Scene = () => {
+ const frame = useCurrentFrame();
+
+ const panelStyle = useCommandMenuTransition([
+ { at: 16, state: "opened", duration: 16 },
+ { at: 108, state: "closed", duration: 12 },
+ ]);
+
+ // 8 chars at 4 chars/sec @ 30 fps = 60 frames total typing window.
+ const revealed = revealCount(
+ Math.max(0, frame - 20), // typing starts at frame 20
+ 30, // fps
+ QUERY.length, // total characters
+ 4, // chars per second
+ );
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <CommandMenu style={panelStyle} query={QUERY} revealCount={revealed} />
+ </div>
+ );
+};
+```
+
+`revealCount(localFrame, fps, len, cps)` is a pure function — it returns the number of characters to show given the elapsed local frame, fps, total query length, and typing speed in chars per second. Import it from `@/lib/remocn-ui`.
+
+When `revealCount` is omitted, the full `query` is shown immediately. When the visible prefix is empty, all items are shown. The pure filter is exported as `filterCommandItems(items, query, revealCount)` if you need it in your own logic.
+
+## Items
+
+The panel renders a column of **CommandMenuItem** rows — one per filtered entry. Each row has four states reflecting the user's interaction:
+
+`CommandMenuItemState` is:
+
+```ts
+type CommandMenuItemState =
+ | "idle" // popover background, muted icon, normal label
+ | "hover" // accent background, foreground icon, normal label
+ | "press" // darker accent background, foreground icon, scale 0.98
+ | "selected" // accent background, accent-foreground label, foreground icon
+```
+
+`idle` rests on the popover background. `hover` brightens to the accent color. `press` darkens slightly and shrinks to 0.98 scale. `selected` locks the accent background with an accent-foreground label.
+
+Preview a single CommandMenuItem:
+
+<ComponentPreview name="command-menu-item" />
+
+When you install `command-menu`, the `command-menu-item` atom is automatically pulled in via `registryDependencies` — no separate install needed. The `CommandMenu` container derives each row's state from the `selectedIndex`, `highlightedIndex`, and `pressedIndex` props (indexed into the **filtered** list), or you can override a row's visual with `itemStyles`.
+
+To animate a row's state transition, drive it with `useCommandMenuItemTransition`:
+
+```tsx
+import { useCommandMenuItemTransition } from "@/components/remocn/use-command-menu-item-transition";
+
+const itemStyle = useCommandMenuItemTransition([
+ { at: 84, state: "hover", duration: 8 },
+ { at: 92, state: "press", duration: 6 },
+ { at: 100, state: "selected", duration: 8 },
+]);
+
+// Pass to CommandMenu via itemStyles (indexed into the filtered list):
+<CommandMenu style={panelStyle} itemStyles={[itemStyle]} />
+```
+
+## 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: "CommandMenuStyle",
+ description: "Resolved animated visual (smooth path). Pass an interpolated CommandMenuStyle from useCommandMenuTransition. Takes precedence over state when provided.",
+ },
+ {
+ name: "query",
+ type: "string",
+ default: "\"\"",
+ description: "Full search query text. The visible prefix is query.slice(0, revealCount). The item list is filtered against this prefix.",
+ },
+ {
+ name: "revealCount",
+ type: "number",
+ description: "Number of query characters revealed so far. Omitted means the whole query is shown immediately. Use the revealCount() helper from @/lib/remocn-ui to compute this from the frame.",
+ },
+ {
+ name: "items",
+ type: "CommandMenuEntry[]",
+ default: "[Profile, Settings, New File, Search docs]",
+ description: "The full list of command rows before filtering. Each entry has label (required), optional icon (search/settings/user/file), and optional shortcut string.",
+ },
+ {
+ name: "selectedIndex",
+ type: "number",
+ default: "-1",
+ description: "Index into the FILTERED list of the persisted selection. -1 for none.",
+ },
+ {
+ name: "highlightedIndex",
+ type: "number",
+ default: "-1",
+ description: "Index into the FILTERED list of the hovered row. -1 for none.",
+ },
+ {
+ name: "pressedIndex",
+ type: "number",
+ default: "-1",
+ description: "Index into the FILTERED list of the pressed row. -1 for none.",
+ },
+ {
+ name: "itemStyles",
+ type: "(CommandMenuItemStyle | undefined)[]",
+ description: "Per-row resolved visual override (smooth path), indexed into the FILTERED list. When present it wins over the index-to-state derivation. Used by the live example to animate a single row.",
+ },
+ {
+ 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 element.",
+ },
+ ]}
+/>
diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.json
index 2c5cead1..8625d338 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", "toast"]
+ "pages": ["accordion", "alert-dialog", "button", "checkbox", "command-menu", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "radio", "select", "spinner", "switch", "tabs", "toast"]
}
diff --git a/registry/__index__.tsx b/registry/__index__.tsx
index 850e59fd..3a3dc85a 100644
--- a/registry/__index__.tsx
+++ b/registry/__index__.tsx
@@ -141,6 +141,10 @@ 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 { CommandMenuItem } from "@/registry/remocn-ui/command-menu-item";
+import { commandMenuItemConfig } from "@/registry/remocn-ui/command-menu-item/config";
+import { CommandMenu } from "@/registry/remocn-ui/command-menu";
+import { commandMenuConfig } from "@/registry/remocn-ui/command-menu/config";
import { ZoomThroughTransition } from "@/registry/remocn/zoom-through-transition";
import { zoomThroughTransitionConfig } from "@/registry/remocn/zoom-through-transition/config";
@@ -339,6 +343,13 @@ const registry: Record<string, RegistryEntry> = {
// centers the toast on a theme-background stage); the shipped Toast is a
// placement-agnostic card the caller positions.
"toast": { Component: ToastPreview, config: toastConfig },
+ "command-menu-item": {
+ Component: CommandMenuItem,
+ config: commandMenuItemConfig,
+ },
+ // command-menu needs NO preview wrapper: like dialog it renders an intrinsic
+ // inset:0 backdrop + centered panel, so the customizer mounts it directly.
+ "command-menu": { Component: CommandMenu, config: commandMenuConfig },
"spinner": { Component: Spinner, config: spinnerConfig },
};
diff --git a/registry/remocn-ui/command-menu-item/__tests__/README.md b/registry/remocn-ui/command-menu-item/__tests__/README.md
new file mode 100644
index 00000000..ba24bb88
--- /dev/null
+++ b/registry/remocn-ui/command-menu-item/__tests__/README.md
@@ -0,0 +1,110 @@
+# `command-menu-item` — verification tests
+
+Pure / deterministic verification for the `command-menu-item` component
+(`registry/remocn-ui/command-menu-item/`). The render path (`index.tsx`) imports
+`useRemocnTheme` which requires React context and cannot run headlessly — it is
+NOT exercised here. This suite covers the pure-testable surface:
+`commandMenuItemStyleContext`, `commandMenuItemStyle` presets,
+`tweenCommandMenuItemStyle` interpolation, and `commandMenuItemConfig` controls
+wiring + snippet codegen.
+
+## Animation model — state atom with smooth opt-in
+
+`command-menu-item` follows the standard state-atom pattern (STYLE-GUIDE §1):
+
+**Snap path** (`state?: CommandMenuItemState` prop):
+`<CommandMenuItem>` is a frame-free pure renderer. The `state` prop drives all
+visuals. Each state maps to a complete resting keyframe via
+`commandMenuItemStyle(state, ctx) => CommandMenuItemStyle`. State changes snap.
+
+**Smooth path** (`style?: CommandMenuItemStyle` prop):
+Callers opt in to smooth transitions by passing a pre-interpolated
+`CommandMenuItemStyle` to the `style` prop. The caller — typically
+`useCommandMenuItemTransition` — reads `useCurrentFrame()` via
+`useStateTransition`, applies `easings.out` to linear progress, and blends the
+two state presets via `tweenCommandMenuItemStyle(from, to, t)`. The component
+remains frame-free.
+
+**Color fields** (`background`, `labelColor`, `iconColor`) go through
+`mixOklch` in the tween — tested as non-empty strings at all `t`. The numeric
+field (`scale`) is tested with exact midpoint values.
+
+## How to run
+
+```bash
+bun install
+bun test registry/remocn-ui/command-menu-item/__tests__
+```
+
+## What is covered
+
+- **`DEFAULT_DURATION`** — asserts the constant is 8 frames (shorter than
+ the container's 12).
+
+- **`commandMenuItemStyleContext(theme)`** — pure token derivation. Asserts
+ all 10 fields map to the correct theme tokens: `idleBg→popover`,
+ `hoverBg→accent`, `selectedBg→accent`, `idleFg→popoverForeground`,
+ `selectedFg→accentForeground`, `idleIcon→mutedForeground`,
+ `selectedIcon→foreground`, `kbdBg→muted`, `kbdFg→mutedForeground`,
+ `kbdBorder→border`. Also asserts `pressBg` is a non-empty derived string
+ differing from `hoverBg` (the `mixOklch` tint). Confirms all fields are
+ non-empty strings. Light/dark themes produce different values.
+
+- **`commandMenuItemStyle(state, ctx)` presets** — every field for every
+ state (4 states × 4 fields = 16 assertions):
+ - `idle`: background=idleBg, labelColor=idleFg, iconColor=idleIcon, scale=1
+ - `hover`: background=hoverBg, labelColor=idleFg, iconColor=selectedIcon, scale=1
+ - `press`: background=pressBg, labelColor=idleFg, iconColor=selectedIcon, scale=0.98
+ - `selected`: background=selectedBg, labelColor=selectedFg, iconColor=selectedIcon, scale=1
+ - Scale invariant: only `press` has scale < 1; all others are exactly 1.
+ - All states produce a complete `CommandMenuItemStyle` (all fields defined).
+
+- **`tweenCommandMenuItemStyle(a, b, t)`** — at t=0 all fields equal `a`; at
+ t=1 all equal `b`; at t=0.5 numeric field `scale` is the exact midpoint
+ (idle→press gives 0.99); color fields are non-empty strings at all t;
+ identity case preserves all fields; result has all four fields present.
+
+- **`commandMenuItemConfig.controls`** — state/icon/label/shortcut/mode wiring:
+ state is a `select` with options `["idle","hover","press","selected"]` and
+ default `"selected"`; icon is a `select` with options
+ `["search","settings","user","file"]` and default `"settings"`; label and
+ shortcut are `text` controls; mode has default `"light"`.
+
+- **`commandMenuItemConfig.snippet`** — import line, structural shape, state
+ always emitted; default label `"Settings"`, icon `"settings"`, mode `"light"`,
+ and empty shortcut are omitted; non-default values are emitted; all state
+ options round-trip.
+
+## Import strategy
+
+- `../index` — `commandMenuItemStyle`, `commandMenuItemStyleContext`,
+ `CommandMenuItemState`
+- `../use-command-menu-item-transition` — `tweenCommandMenuItemStyle`,
+ `DEFAULT_DURATION`
+- `../config` — `commandMenuItemConfig`
+- `@/lib/remocn-ui` — `defaultLightTheme`, `defaultDarkTheme`
+
+`useCommandMenuItemTransition` is NOT imported (it reads `useCurrentFrame()`).
+Its pure resolver logic is covered in `core/__tests__/timeline.test.ts`; the
+additional easing + tween contract is covered by the tween tests above.
+
+## Determinism grep checklist (run manually; must print NOTHING)
+
+`command-menu-item/index.tsx` is a pure renderer — must contain none of:
+
+```bash
+grep -nE "useState|useEffect|useCurrentFrame|onClick|onChange|addEventListener|Date\.now|Math\.random|requestAnimationFrame" \
+ registry/remocn-ui/command-menu-item/index.tsx
+```
+
+Expected: **no output**. Any match is a determinism violation.
+
+`use-command-menu-item-transition.ts` intentionally reads `useCurrentFrame()`
+via `useStateTransition` — this is correct and expected for the hook file.
+
+Tier-wide sweep:
+
+```bash
+grep -nE "useState|useEffect|onClick|onChange|addEventListener|Date\.now|Math\.random" \
+ registry/remocn-ui/command-menu-item/index.tsx registry/remocn-ui/core/*.ts
+```
diff --git a/registry/remocn-ui/command-menu-item/__tests__/command-menu-item.test.ts b/registry/remocn-ui/command-menu-item/__tests__/command-menu-item.test.ts
new file mode 100644
index 00000000..2b949d0a
--- /dev/null
+++ b/registry/remocn-ui/command-menu-item/__tests__/command-menu-item.test.ts
@@ -0,0 +1,562 @@
+/**
+ * Verification tests for the PURE / DETERMINISTIC parts of `command-menu-item`.
+ *
+ * Scope:
+ * - registry/remocn-ui/command-menu-item/index.tsx
+ * commandMenuItemStyleContext(theme) — pure color derivation
+ * commandMenuItemStyle(state, ctx) — complete state→visual preset map
+ * - registry/remocn-ui/command-menu-item/use-command-menu-item-transition.ts
+ * tweenCommandMenuItemStyle(a, b, t) — pure lerp/mix across every field
+ * DEFAULT_DURATION constant
+ *
+ * - registry/remocn-ui/command-menu-item/config.ts
+ * commandMenuItemConfig.controls wiring + commandMenuItemConfig.snippet codegen
+ *
+ * The render path (index.tsx) imports `useRemocnTheme` which requires React
+ * context and cannot run headlessly — it is NOT exercised here.
+ * `useCommandMenuItemTransition` calls `useStateTransition` → `useCurrentFrame`
+ * and is NOT imported; its pure resolver logic is already tested in
+ * core/__tests__/timeline.test.ts, and the additional easing + tween contract is
+ * covered by the tweenCommandMenuItemStyle tests below.
+ *
+ * Runner: Bun's built-in test runner (TypeScript-native, no framework dep).
+ * bun test registry/remocn-ui/command-menu-item/__tests__
+ *
+ * --------------------------------------------------------------------------
+ * IMPORT STRATEGY
+ * --------------------------------------------------------------------------
+ * Relative imports for component source; `@/lib/remocn-ui` alias for core.
+ * None of the imported functions call `useCurrentFrame()` at import or call time.
+ * --------------------------------------------------------------------------
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+ commandMenuItemStyle,
+ commandMenuItemStyleContext,
+ type CommandMenuItemState,
+} from "../index";
+import {
+ tweenCommandMenuItemStyle,
+ DEFAULT_DURATION,
+} from "../use-command-menu-item-transition";
+import { commandMenuItemConfig } from "../config";
+import { defaultLightTheme, defaultDarkTheme } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Shared fixtures
+// ===========================================================================
+
+const VALID_STATES: readonly CommandMenuItemState[] = [
+ "idle",
+ "hover",
+ "press",
+ "selected",
+];
+
+/** A context built from the default light theme — reused across all preset tests. */
+const ctx = commandMenuItemStyleContext(defaultLightTheme);
+
+/** Convenience wrapper for snippet(). */
+type SnippetValues = {
+ state?: string;
+ label?: string;
+ icon?: string;
+ shortcut?: string;
+ mode?: string;
+};
+const snippet = (values: SnippetValues): string =>
+ commandMenuItemConfig.snippet(values as Record<string, unknown>);
+
+// ===========================================================================
+// 1. DEFAULT_DURATION constant
+// ===========================================================================
+
+describe("DEFAULT_DURATION", () => {
+ it("is 8 frames (item default — shorter than container's 12)", () => {
+ expect(DEFAULT_DURATION).toBe(8);
+ });
+});
+
+// ===========================================================================
+// 2. commandMenuItemStyleContext — pure theme → context derivation
+// MIRROR of index.tsx lines 75-91
+// ===========================================================================
+
+describe("commandMenuItemStyleContext: maps theme tokens correctly", () => {
+ it("idleBg equals theme.popover", () => {
+ expect(ctx.idleBg).toBe(defaultLightTheme.popover);
+ });
+
+ it("hoverBg equals theme.accent", () => {
+ expect(ctx.hoverBg).toBe(defaultLightTheme.accent);
+ });
+
+ it("selectedBg equals theme.accent", () => {
+ expect(ctx.selectedBg).toBe(defaultLightTheme.accent);
+ });
+
+ it("idleFg equals theme.popoverForeground", () => {
+ expect(ctx.idleFg).toBe(defaultLightTheme.popoverForeground);
+ });
+
+ it("selectedFg equals theme.accentForeground", () => {
+ expect(ctx.selectedFg).toBe(defaultLightTheme.accentForeground);
+ });
+
+ it("idleIcon equals theme.mutedForeground", () => {
+ expect(ctx.idleIcon).toBe(defaultLightTheme.mutedForeground);
+ });
+
+ it("selectedIcon equals theme.foreground", () => {
+ expect(ctx.selectedIcon).toBe(defaultLightTheme.foreground);
+ });
+
+ it("kbdBg equals theme.muted", () => {
+ expect(ctx.kbdBg).toBe(defaultLightTheme.muted);
+ });
+
+ it("kbdFg equals theme.mutedForeground", () => {
+ expect(ctx.kbdFg).toBe(defaultLightTheme.mutedForeground);
+ });
+
+ it("kbdBorder equals theme.border", () => {
+ expect(ctx.kbdBorder).toBe(defaultLightTheme.border);
+ });
+});
+
+describe("commandMenuItemStyleContext: pressBg is a derived (non-empty) color string", () => {
+ it("pressBg is a non-empty string", () => {
+ expect(typeof ctx.pressBg).toBe("string");
+ expect(ctx.pressBg.length).toBeGreaterThan(0);
+ });
+
+ it("pressBg differs from hoverBg (mixOklch adds a tint)", () => {
+ expect(ctx.pressBg).not.toBe(ctx.hoverBg);
+ });
+});
+
+describe("commandMenuItemStyleContext: all fields are non-empty strings", () => {
+ it("every field is a non-empty string", () => {
+ for (const [key, value] of Object.entries(ctx)) {
+ expect(typeof value).toBe("string");
+ expect((value as string).length).toBeGreaterThan(0);
+ }
+ });
+});
+
+describe("commandMenuItemStyleContext: theme independence — different themes produce different values", () => {
+ const ctxDark = commandMenuItemStyleContext(defaultDarkTheme);
+
+ it("idleBg differs between light and dark themes", () => {
+ expect(ctx.idleBg).not.toBe(ctxDark.idleBg);
+ });
+
+ it("idleIcon differs between light and dark themes", () => {
+ expect(ctx.idleIcon).not.toBe(ctxDark.idleIcon);
+ });
+});
+
+// ===========================================================================
+// 3. commandMenuItemStyle — pure (state, ctx) => CommandMenuItemStyle presets
+// MIRROR of index.tsx lines 97-131
+// Every field is asserted for every state.
+// ===========================================================================
+
+describe("commandMenuItemStyle: idle state", () => {
+ const s = commandMenuItemStyle("idle", ctx);
+
+ it("background is ctx.idleBg", () => {
+ expect(s.background).toBe(ctx.idleBg);
+ });
+
+ it("labelColor is ctx.idleFg", () => {
+ expect(s.labelColor).toBe(ctx.idleFg);
+ });
+
+ it("iconColor is ctx.idleIcon", () => {
+ expect(s.iconColor).toBe(ctx.idleIcon);
+ });
+
+ it("scale is 1 (full size, at rest)", () => {
+ expect(s.scale).toBe(1);
+ });
+});
+
+describe("commandMenuItemStyle: hover state", () => {
+ const s = commandMenuItemStyle("hover", ctx);
+
+ it("background is ctx.hoverBg", () => {
+ expect(s.background).toBe(ctx.hoverBg);
+ });
+
+ it("labelColor is ctx.idleFg", () => {
+ expect(s.labelColor).toBe(ctx.idleFg);
+ });
+
+ it("iconColor is ctx.selectedIcon (icon brightens on hover)", () => {
+ expect(s.iconColor).toBe(ctx.selectedIcon);
+ });
+
+ it("scale is 1", () => {
+ expect(s.scale).toBe(1);
+ });
+});
+
+describe("commandMenuItemStyle: press state", () => {
+ const s = commandMenuItemStyle("press", ctx);
+
+ it("background is ctx.pressBg", () => {
+ expect(s.background).toBe(ctx.pressBg);
+ });
+
+ it("labelColor is ctx.idleFg", () => {
+ expect(s.labelColor).toBe(ctx.idleFg);
+ });
+
+ it("iconColor is ctx.selectedIcon", () => {
+ expect(s.iconColor).toBe(ctx.selectedIcon);
+ });
+
+ it("scale is 0.98 (slight shrink on press)", () => {
+ expect(s.scale).toBeCloseTo(0.98, 10);
+ });
+});
+
+describe("commandMenuItemStyle: selected state", () => {
+ const s = commandMenuItemStyle("selected", ctx);
+
+ it("background is ctx.selectedBg", () => {
+ expect(s.background).toBe(ctx.selectedBg);
+ });
+
+ it("labelColor is ctx.selectedFg", () => {
+ expect(s.labelColor).toBe(ctx.selectedFg);
+ });
+
+ it("iconColor is ctx.selectedIcon", () => {
+ expect(s.iconColor).toBe(ctx.selectedIcon);
+ });
+
+ it("scale is 1 (full size when selected)", () => {
+ expect(s.scale).toBe(1);
+ });
+});
+
+describe("commandMenuItemStyle: scale invariants across all states", () => {
+ it("idle: scale=1", () => {
+ expect(commandMenuItemStyle("idle", ctx).scale).toBe(1);
+ });
+
+ it("hover: scale=1", () => {
+ expect(commandMenuItemStyle("hover", ctx).scale).toBe(1);
+ });
+
+ it("press: scale=0.98", () => {
+ expect(commandMenuItemStyle("press", ctx).scale).toBeCloseTo(0.98, 10);
+ });
+
+ it("selected: scale=1", () => {
+ expect(commandMenuItemStyle("selected", ctx).scale).toBe(1);
+ });
+
+ it("only press has scale < 1", () => {
+ for (const state of VALID_STATES) {
+ const s = commandMenuItemStyle(state, ctx);
+ if (state === "press") {
+ expect(s.scale).toBeLessThan(1);
+ } else {
+ expect(s.scale).toBe(1);
+ }
+ }
+ });
+});
+
+describe("commandMenuItemStyle: every state produces complete CommandMenuItemStyle", () => {
+ it("all fields are defined for every state", () => {
+ for (const state of VALID_STATES) {
+ const s = commandMenuItemStyle(state, ctx);
+ expect(typeof s.background).toBe("string");
+ expect(s.background.length).toBeGreaterThan(0);
+ expect(typeof s.labelColor).toBe("string");
+ expect(s.labelColor.length).toBeGreaterThan(0);
+ expect(typeof s.iconColor).toBe("string");
+ expect(s.iconColor.length).toBeGreaterThan(0);
+ expect(typeof s.scale).toBe("number");
+ }
+ });
+});
+
+// ===========================================================================
+// 4. tweenCommandMenuItemStyle — pure lerp/mix across every field
+// MIRROR of use-command-menu-item-transition.ts lines 23-34
+// Numbers lerp; colors go through mixOklch (tested as non-empty strings).
+// ===========================================================================
+
+describe("tweenCommandMenuItemStyle: t=0 returns values equal to `a`", () => {
+ const a = commandMenuItemStyle("idle", ctx);
+ const b = commandMenuItemStyle("selected", ctx);
+ const r = tweenCommandMenuItemStyle(a, b, 0);
+
+ it("scale equals a.scale at t=0", () => {
+ expect(r.scale).toBeCloseTo(a.scale, 10);
+ });
+
+ it("background is a non-empty string at t=0", () => {
+ expect(typeof r.background).toBe("string");
+ expect(r.background.length).toBeGreaterThan(0);
+ });
+
+ it("labelColor is a non-empty string at t=0", () => {
+ expect(typeof r.labelColor).toBe("string");
+ expect(r.labelColor.length).toBeGreaterThan(0);
+ });
+
+ it("iconColor is a non-empty string at t=0", () => {
+ expect(typeof r.iconColor).toBe("string");
+ expect(r.iconColor.length).toBeGreaterThan(0);
+ });
+});
+
+describe("tweenCommandMenuItemStyle: t=1 returns values equal to `b`", () => {
+ const a = commandMenuItemStyle("idle", ctx);
+ const b = commandMenuItemStyle("selected", ctx);
+ const r = tweenCommandMenuItemStyle(a, b, 1);
+
+ it("scale equals b.scale at t=1", () => {
+ expect(r.scale).toBeCloseTo(b.scale, 10);
+ });
+
+ it("background is a non-empty string at t=1", () => {
+ expect(typeof r.background).toBe("string");
+ expect(r.background.length).toBeGreaterThan(0);
+ });
+
+ it("labelColor is a non-empty string at t=1", () => {
+ expect(typeof r.labelColor).toBe("string");
+ expect(r.labelColor.length).toBeGreaterThan(0);
+ });
+
+ it("iconColor is a non-empty string at t=1", () => {
+ expect(typeof r.iconColor).toBe("string");
+ expect(r.iconColor.length).toBeGreaterThan(0);
+ });
+});
+
+describe("tweenCommandMenuItemStyle: t=0.5 midpoint — numeric field (idle → press)", () => {
+ // idle: scale=1, press: scale=0.98 → midpoint: 0.99
+ const a = commandMenuItemStyle("idle", ctx);
+ const b = commandMenuItemStyle("press", ctx);
+ const r = tweenCommandMenuItemStyle(a, b, 0.5);
+
+ it("scale midpoint: 1 → 0.98 gives 0.99", () => {
+ expect(r.scale).toBeCloseTo(0.99, 10);
+ });
+
+ it("background is a non-empty string at midpoint", () => {
+ expect(typeof r.background).toBe("string");
+ expect(r.background.length).toBeGreaterThan(0);
+ });
+});
+
+describe("tweenCommandMenuItemStyle: t=0.5 midpoint — numeric field (idle → hover)", () => {
+ // idle: scale=1, hover: scale=1 → midpoint: 1 (same, test that it holds)
+ const a = commandMenuItemStyle("idle", ctx);
+ const b = commandMenuItemStyle("hover", ctx);
+ const r = tweenCommandMenuItemStyle(a, b, 0.5);
+
+ it("scale midpoint: 1 → 1 gives 1 (identity)", () => {
+ expect(r.scale).toBeCloseTo(1, 10);
+ });
+});
+
+describe("tweenCommandMenuItemStyle: identity (a === b, any t)", () => {
+ const s = commandMenuItemStyle("selected", ctx);
+
+ it("scale is unchanged when both endpoints are the same", () => {
+ expect(tweenCommandMenuItemStyle(s, s, 0.5).scale).toBeCloseTo(s.scale, 10);
+ });
+
+ it("background is a non-empty string for identity case", () => {
+ expect(typeof tweenCommandMenuItemStyle(s, s, 0.5).background).toBe("string");
+ expect(tweenCommandMenuItemStyle(s, s, 0.5).background.length).toBeGreaterThan(0);
+ });
+});
+
+describe("tweenCommandMenuItemStyle: all four fields are present in the result", () => {
+ const a = commandMenuItemStyle("idle", ctx);
+ const b = commandMenuItemStyle("hover", ctx);
+ const r = tweenCommandMenuItemStyle(a, b, 0.5);
+
+ it("result has background field", () => {
+ expect(r).toHaveProperty("background");
+ });
+
+ it("result has labelColor field", () => {
+ expect(r).toHaveProperty("labelColor");
+ });
+
+ it("result has iconColor field", () => {
+ expect(r).toHaveProperty("iconColor");
+ });
+
+ it("result has scale field", () => {
+ expect(r).toHaveProperty("scale");
+ });
+});
+
+// ===========================================================================
+// 5. commandMenuItemConfig.controls — customizer control wiring
+// ===========================================================================
+
+describe("commandMenuItemConfig.controls: state", () => {
+ it("state is a select control", () => {
+ expect(commandMenuItemConfig.controls.state.type).toBe("select");
+ });
+
+ it("state options are ['idle','hover','press','selected']", () => {
+ const ctrl = commandMenuItemConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["idle", "hover", "press", "selected"]);
+ });
+
+ it("state default is 'selected'", () => {
+ expect(commandMenuItemConfig.controls.state.default).toBe("selected");
+ });
+
+ it("every state option is a valid CommandMenuItemState", () => {
+ const ctrl = commandMenuItemConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const opt of ctrl.options) {
+ expect(VALID_STATES).toContain(opt as CommandMenuItemState);
+ }
+ });
+});
+
+describe("commandMenuItemConfig.controls: icon", () => {
+ it("icon is a select control", () => {
+ expect(commandMenuItemConfig.controls.icon.type).toBe("select");
+ });
+
+ it("icon options are ['search','settings','user','file']", () => {
+ const ctrl = commandMenuItemConfig.controls.icon;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["search", "settings", "user", "file"]);
+ });
+
+ it("icon default is 'settings'", () => {
+ expect(commandMenuItemConfig.controls.icon.default).toBe("settings");
+ });
+});
+
+describe("commandMenuItemConfig.controls: label and shortcut", () => {
+ it("label is a text control", () => {
+ expect(commandMenuItemConfig.controls.label.type).toBe("text");
+ });
+
+ it("label default is 'Settings'", () => {
+ expect(commandMenuItemConfig.controls.label.default).toBe("Settings");
+ });
+
+ it("shortcut is a text control", () => {
+ expect(commandMenuItemConfig.controls.shortcut.type).toBe("text");
+ });
+});
+
+describe("commandMenuItemConfig.controls: mode", () => {
+ it("mode is a select control", () => {
+ expect(commandMenuItemConfig.controls.mode.type).toBe("select");
+ });
+
+ it("mode options are ['light','dark']", () => {
+ const ctrl = commandMenuItemConfig.controls.mode;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["light", "dark"]);
+ });
+
+ it("mode default is 'light'", () => {
+ expect(commandMenuItemConfig.controls.mode.default).toBe("light");
+ });
+});
+
+// ===========================================================================
+// 6. commandMenuItemConfig.snippet — pure JSX string builder
+// ===========================================================================
+
+describe("commandMenuItemConfig.snippet: import line", () => {
+ it("includes 'import { CommandMenuItem }' from the correct path", () => {
+ const out = snippet({ state: "selected" });
+ expect(out).toContain("import { CommandMenuItem }");
+ expect(out).toContain('from "@/components/remocn/command-menu-item"');
+ });
+});
+
+describe("commandMenuItemConfig.snippet: structural invariants", () => {
+ it("contains a <CommandMenuItem JSX element", () => {
+ expect(snippet({ state: "selected" })).toContain("<CommandMenuItem");
+ });
+
+ it("ends with a self-closing />", () => {
+ expect(snippet({ state: "selected" }).trimEnd().endsWith("/>")).toBe(true);
+ });
+
+ it("state is always emitted", () => {
+ for (const state of VALID_STATES) {
+ expect(snippet({ state })).toContain(`state="${state}"`);
+ }
+ });
+});
+
+describe("commandMenuItemConfig.snippet: default props are omitted", () => {
+ it("omits label when it equals the default 'Settings'", () => {
+ expect(snippet({ state: "selected", label: "Settings" })).not.toContain("label=");
+ });
+
+ it("omits icon when it equals the default 'settings'", () => {
+ expect(snippet({ state: "selected", icon: "settings" })).not.toContain("icon=");
+ });
+
+ it("omits mode when it equals the default 'light'", () => {
+ expect(snippet({ state: "selected", mode: "light" })).not.toContain("mode=");
+ });
+
+ it("omits shortcut when it is an empty string", () => {
+ expect(snippet({ state: "selected", shortcut: "" })).not.toContain("shortcut=");
+ });
+});
+
+describe("commandMenuItemConfig.snippet: non-default props are emitted", () => {
+ it("emits a non-default label", () => {
+ expect(snippet({ state: "selected", label: "Profile" })).toContain('label="Profile"');
+ });
+
+ it("emits icon='search' when non-default", () => {
+ expect(snippet({ state: "selected", icon: "search" })).toContain('icon="search"');
+ });
+
+ it("emits icon='user' when non-default", () => {
+ expect(snippet({ state: "selected", icon: "user" })).toContain('icon="user"');
+ });
+
+ it("emits icon='file' when non-default", () => {
+ expect(snippet({ state: "selected", icon: "file" })).toContain('icon="file"');
+ });
+
+ it("emits mode='dark' when non-default", () => {
+ expect(snippet({ state: "selected", mode: "dark" })).toContain('mode="dark"');
+ });
+
+ it("emits shortcut when non-empty", () => {
+ expect(snippet({ state: "selected", shortcut: "⌘ S" })).toContain('shortcut="⌘ S"');
+ });
+});
+
+describe("commandMenuItemConfig.snippet: state options round-trip", () => {
+ it("emits the correct state for every control option", () => {
+ const ctrl = commandMenuItemConfig.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/command-menu-item/config.ts b/registry/remocn-ui/command-menu-item/config.ts
new file mode 100644
index 00000000..4dfcb1d0
--- /dev/null
+++ b/registry/remocn-ui/command-menu-item/config.ts
@@ -0,0 +1,57 @@
+import { type ComponentConfig, FPS, H, W } from "@/lib/customizer-config";
+import type { CommandMenuItemState } from "@/registry/remocn-ui/command-menu-item";
+
+export const commandMenuItemConfig: ComponentConfig = {
+ componentName: "CommandMenuItem",
+ importPath: "@/components/remocn/command-menu-item",
+ controls: {
+ label: { type: "text", default: "Settings", label: "Label" },
+ icon: {
+ type: "select",
+ default: "settings",
+ options: ["search", "settings", "user", "file"],
+ label: "Icon",
+ },
+ shortcut: { type: "text", default: "⌘ S", label: "Shortcut" },
+ state: {
+ type: "select",
+ // Default to `selected` so the preview shows the highlighted row.
+ default: "selected",
+ options: ["idle", "hover", "press", "selected"],
+ 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 CommandMenuItemState) ?? "selected";
+ const label = values.label as string | undefined;
+ const icon = values.icon as string | undefined;
+ const shortcut = values.shortcut as string | undefined;
+ const mode = values.mode as string | undefined;
+
+ const props: string[] = [` state="${state}"`];
+ if (label !== undefined && label !== "Settings")
+ props.push(` label="${label}"`);
+ if (icon !== undefined && icon !== "settings")
+ props.push(` icon="${icon}"`);
+ if (shortcut !== undefined && shortcut !== "")
+ props.push(` shortcut="${shortcut}"`);
+ if (mode !== undefined && mode !== "light")
+ props.push(` mode="${mode}"`);
+
+ return `import { CommandMenuItem } from "@/components/remocn/command-menu-item";
+
+<CommandMenuItem
+${props.join("\n")}
+/>`;
+ },
+};
diff --git a/registry/remocn-ui/command-menu-item/index.tsx b/registry/remocn-ui/command-menu-item/index.tsx
new file mode 100644
index 00000000..f8b516ab
--- /dev/null
+++ b/registry/remocn-ui/command-menu-item/index.tsx
@@ -0,0 +1,307 @@
+"use client";
+
+import { mixOklch, type RemocnTheme, useRemocnTheme } from "@/lib/remocn-ui";
+
+export type CommandMenuItemState = "idle" | "hover" | "press" | "selected";
+
+export interface CommandMenuItemProps {
+ /** Current visual state (snap path). State changes snap (no enter-tweens). */
+ state?: CommandMenuItemState;
+ /**
+ * Resolved animated visual (smooth path). When provided, takes precedence over
+ * `state` — feed it an interpolated `CommandMenuItemStyle` from
+ * `useCommandMenuItemTransition`.
+ */
+ style?: CommandMenuItemStyle;
+ /** Row label. */
+ label?: string;
+ /** Optional leading icon name from the built-in set (search/settings/user/file). */
+ icon?: CommandMenuIcon;
+ /** Optional trailing keyboard shortcut, e.g. "⌘K" or "⌘ S". */
+ shortcut?: string;
+ /** Row width (px). Matches the panel content width when composed in CommandMenu. */
+ width?: number;
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ className?: string;
+}
+
+/** The built-in leading icons. Hand-drawn so nothing is imported from a kit. */
+export type CommandMenuIcon = "search" | "settings" | "user" | "file";
+
+/** Standalone row width (px) when the atom is mounted on its own. */
+const ROW_WIDTH = 360;
+
+// ===========================================================================
+// Command-menu-item visual — the COMPLETE animated look for a moment in time. A
+// `state` is a named preset of this visual (`commandMenuItemStyle`); the smooth
+// path feeds an interpolated `CommandMenuItemStyle` straight through. The
+// component is a pure renderer of whichever style it receives. This atom is NOT
+// a copy of select-item: its row is icon + label + trailing shortcut kbd, not
+// label + check icon.
+// ===========================================================================
+
+export interface CommandMenuItemStyle {
+ /** Animated row background (a concrete color, never "transparent"). */
+ background: string;
+ /** Animated label color. */
+ labelColor: string;
+ /** Animated icon color. */
+ iconColor: string;
+ /** Row zoom: 1 default, 0.98 on press. */
+ scale: number;
+}
+
+/** Concrete colors for the active theme, resolved once per render. */
+export interface CommandMenuItemStyleContext {
+ idleBg: string;
+ hoverBg: string;
+ pressBg: string;
+ selectedBg: string;
+ idleFg: string;
+ selectedFg: string;
+ idleIcon: string;
+ selectedIcon: string;
+ /** Static shortcut-kbd colors (never animated). */
+ kbdBg: string;
+ kbdFg: string;
+ kbdBorder: string;
+}
+
+/**
+ * Derive the concrete colors for a theme. Pure — call it once and reuse the
+ * result for every `commandMenuItemStyle(state, ctx)` preset.
+ */
+export function commandMenuItemStyleContext(
+ theme: RemocnTheme,
+): CommandMenuItemStyleContext {
+ return {
+ idleBg: theme.popover,
+ hoverBg: theme.accent,
+ pressBg: mixOklch(theme.accent, theme.foreground, 0.08),
+ selectedBg: theme.accent,
+ idleFg: theme.popoverForeground,
+ selectedFg: theme.accentForeground,
+ idleIcon: theme.mutedForeground,
+ selectedIcon: theme.foreground,
+ kbdBg: theme.muted,
+ kbdFg: theme.mutedForeground,
+ kbdBorder: theme.border,
+ };
+}
+
+/**
+ * The COMPLETE resting visual for a state — a pure `(state, ctx) =>
+ * CommandMenuItemStyle` map. To change how a state looks, edit one entry.
+ */
+export function commandMenuItemStyle(
+ state: CommandMenuItemState,
+ ctx: CommandMenuItemStyleContext,
+): CommandMenuItemStyle {
+ switch (state) {
+ case "hover":
+ return {
+ background: ctx.hoverBg,
+ labelColor: ctx.idleFg,
+ iconColor: ctx.selectedIcon,
+ scale: 1,
+ };
+ case "press":
+ return {
+ background: ctx.pressBg,
+ labelColor: ctx.idleFg,
+ iconColor: ctx.selectedIcon,
+ scale: 0.98,
+ };
+ case "selected":
+ return {
+ background: ctx.selectedBg,
+ labelColor: ctx.selectedFg,
+ iconColor: ctx.selectedIcon,
+ scale: 1,
+ };
+ default:
+ return {
+ background: ctx.idleBg,
+ labelColor: ctx.idleFg,
+ iconColor: ctx.idleIcon,
+ scale: 1,
+ };
+ }
+}
+
+/** Hand-drawn leading icon paths on a 24×24 grid (stroke-driven). */
+const ICON_PATHS: Record<CommandMenuIcon, string> = {
+ search: "M11 4a7 7 0 1 0 0 14 7 7 0 0 0 0-14ZM20 20l-3.5-3.5",
+ settings:
+ "M12 9a3 3 0 1 0 0 6 3 3 0 0 0 0-6ZM12 2v3 M12 19v3 M4.2 4.2l2.1 2.1 M17.7 17.7l2.1 2.1 M2 12h3 M19 12h3 M4.2 19.8l2.1-2.1 M17.7 6.3l2.1-2.1",
+ user: "M12 12a4 4 0 1 0 0-8 4 4 0 0 0 0 8ZM5 20a7 7 0 0 1 14 0",
+ file: "M7 3h7l4 4v14H7ZM14 3v4h4",
+};
+
+function CommandMenuItemIcon({
+ icon,
+ color,
+}: {
+ icon: CommandMenuIcon;
+ color: string;
+}) {
+ return (
+ <svg width={16} height={16} viewBox="0 0 24 24" fill="none">
+ <path
+ d={ICON_PATHS[icon]}
+ stroke={color}
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </svg>
+ );
+}
+
+/** Props for the inline row — the shared visual that `CommandMenu` reuses. */
+export interface CommandMenuItemRowProps {
+ /** Resolved animated visual (smooth path); wins over `state` when present. */
+ style?: CommandMenuItemStyle;
+ /** Current visual state (snap path) when no `style` is supplied. */
+ state?: CommandMenuItemState;
+ /** Pre-derived ctx (the container passes its shared one to avoid re-resolving). */
+ ctx: CommandMenuItemStyleContext;
+ label: string;
+ icon?: CommandMenuIcon;
+ shortcut?: string;
+ width: number;
+ /** Row corner radius (px). */
+ radius: number;
+}
+
+/**
+ * INLINE command row — no full-frame wrapper. One row of a command palette:
+ * leading icon (optional) + label on the left, trailing shortcut kbd on the
+ * right. The `CommandMenu` container renders a column of these; the standalone
+ * `CommandMenuItem` wraps one in a centering frame.
+ */
+export function CommandMenuItemRow({
+ style,
+ state = "idle",
+ ctx,
+ label,
+ icon,
+ shortcut,
+ width,
+ radius,
+}: CommandMenuItemRowProps) {
+ const v = style ?? commandMenuItemStyle(state, ctx);
+ return (
+ <div
+ style={{
+ width,
+ boxSizing: "border-box",
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "space-between",
+ gap: 12,
+ padding: "8px 12px",
+ borderRadius: radius,
+ transform: `scale(${v.scale})`,
+ background: v.background,
+ color: v.labelColor,
+ fontSize: 14,
+ letterSpacing: "-0.01em",
+ }}
+ >
+ <span
+ style={{
+ display: "flex",
+ alignItems: "center",
+ gap: 10,
+ minWidth: 0,
+ }}
+ >
+ {icon !== undefined && (
+ <span style={{ display: "flex", flexShrink: 0 }}>
+ <CommandMenuItemIcon icon={icon} color={v.iconColor} />
+ </span>
+ )}
+ <span
+ style={{
+ overflow: "hidden",
+ textOverflow: "ellipsis",
+ whiteSpace: "nowrap",
+ }}
+ >
+ {label}
+ </span>
+ </span>
+ {shortcut !== undefined && (
+ <kbd
+ style={{
+ flexShrink: 0,
+ display: "inline-flex",
+ alignItems: "center",
+ gap: 2,
+ height: 20,
+ padding: "0 6px",
+ fontSize: 12,
+ fontFamily: "inherit",
+ letterSpacing: "0.05em",
+ color: ctx.kbdFg,
+ background: ctx.kbdBg,
+ border: `1px solid ${ctx.kbdBorder}`,
+ borderRadius: Math.max(4, radius - 4),
+ }}
+ >
+ {shortcut}
+ </kbd>
+ )}
+ </div>
+ );
+}
+
+/**
+ * Standalone command-row atom — resolves theme/ctx/style then wraps a single
+ * `<CommandMenuItemRow>` in the standard full-frame centering wrapper. THIS is
+ * what the registry registers and the customizer mounts. The `CommandMenu`
+ * container does NOT use this — it reuses `CommandMenuItemRow` directly.
+ */
+export function CommandMenuItem({
+ state = "idle",
+ style,
+ label = "Settings",
+ icon = "settings",
+ shortcut,
+ width = ROW_WIDTH,
+ theme: themeOverride,
+ mode,
+ className,
+}: CommandMenuItemProps) {
+ const theme = useRemocnTheme(themeOverride, mode);
+ const ctx = commandMenuItemStyleContext(theme);
+
+ return (
+ <div
+ className={className}
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ background: theme.background,
+ fontFamily:
+ "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif",
+ }}
+ >
+ <CommandMenuItemRow
+ style={style}
+ state={state}
+ ctx={ctx}
+ label={label}
+ icon={icon}
+ shortcut={shortcut}
+ width={width}
+ radius={theme.radius}
+ />
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/command-menu-item/use-command-menu-item-transition.ts b/registry/remocn-ui/command-menu-item/use-command-menu-item-transition.ts
new file mode 100644
index 00000000..c22cbfce
--- /dev/null
+++ b/registry/remocn-ui/command-menu-item/use-command-menu-item-transition.ts
@@ -0,0 +1,72 @@
+"use client";
+
+import {
+ easings,
+ mixOklch,
+ type RemocnTheme,
+ type Step,
+ useRemocnTheme,
+ useStateTransition,
+} from "@/lib/remocn-ui";
+import {
+ commandMenuItemStyle,
+ commandMenuItemStyleContext,
+ type CommandMenuItemState,
+ type CommandMenuItemStyle,
+} from "@/components/remocn/command-menu-item";
+// ^ 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 = 8;
+
+/** Blend two command-menu-item visuals: numbers lerp, colors via oklch mix. */
+export function tweenCommandMenuItemStyle(
+ a: CommandMenuItemStyle,
+ b: CommandMenuItemStyle,
+ t: number,
+): CommandMenuItemStyle {
+ return {
+ background: mixOklch(a.background, b.background, t),
+ labelColor: mixOklch(a.labelColor, b.labelColor, t),
+ iconColor: mixOklch(a.iconColor, b.iconColor, t),
+ scale: a.scale + (b.scale - a.scale) * t,
+ };
+}
+
+export interface CommandMenuItemTransitionOptions {
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ speed?: number;
+ defaultDuration?: number;
+}
+
+/**
+ * Timeline → resolved (eased, tweened) CommandMenuItemStyle. The CALLER invokes
+ * this; it reads the frame, the `<CommandMenuItem>` component does not. Feed the
+ * result to `<CommandMenuItem style={...} />` (or a `CommandMenuItemRow`).
+ */
+export function useCommandMenuItemTransition(
+ steps: Step<CommandMenuItemState>[],
+ opts: CommandMenuItemTransitionOptions = {},
+): CommandMenuItemStyle {
+ const {
+ theme: themeOverride,
+ mode,
+ speed = 1,
+ defaultDuration = DEFAULT_DURATION,
+ } = opts;
+ const theme = useRemocnTheme(themeOverride, mode);
+ const ctx = commandMenuItemStyleContext(theme);
+ const { from, to, progress } = useStateTransition(
+ steps,
+ "idle",
+ speed,
+ defaultDuration,
+ );
+ const t = easings.out(progress);
+ return tweenCommandMenuItemStyle(
+ commandMenuItemStyle(from, ctx),
+ commandMenuItemStyle(to, ctx),
+ t,
+ );
+}
diff --git a/registry/remocn-ui/command-menu/__tests__/README.md b/registry/remocn-ui/command-menu/__tests__/README.md
new file mode 100644
index 00000000..d398d354
--- /dev/null
+++ b/registry/remocn-ui/command-menu/__tests__/README.md
@@ -0,0 +1,130 @@
+# `command-menu` — verification tests
+
+Pure / deterministic verification for the `command-menu` component
+(`registry/remocn-ui/command-menu/`). The render path (`index.tsx`) imports
+`useRemocnTheme` which requires React context and cannot run headlessly — it is
+NOT exercised here. This suite covers the pure-testable surface:
+`filterCommandItems`, `commandMenuStyleContext`, `commandMenuStyle` presets,
+`tweenCommandMenuStyle` interpolation, the `useCommandMenuTransition` pure
+resolver mirror, and `commandMenuConfig` controls wiring + snippet codegen.
+
+## Animation model — state atom with smooth opt-in
+
+`command-menu` follows the standard state-atom pattern (STYLE-GUIDE §1):
+
+**Snap path** (`state?: CommandMenuState` prop):
+`<CommandMenu>` is a frame-free pure renderer. The `state` prop drives all panel
+visuals. Each state maps to a complete resting keyframe via
+`commandMenuStyle(state, ctx) => CommandMenuStyle`. State changes snap.
+
+**Smooth path** (`style?: CommandMenuStyle` prop):
+Callers opt in to smooth open/close by passing a pre-interpolated
+`CommandMenuStyle` to the `style` prop. The caller — typically
+`useCommandMenuTransition` — reads `useCurrentFrame()` via `useStateTransition`,
+applies `easings.out` to linear progress, and blends the two presets via
+`tweenCommandMenuStyle(from, to, t)`. The component remains frame-free.
+
+**All fields are numeric** (`backdropOpacity`, `panelOpacity`, `panelScale`,
+`panelTranslateY`) — `tweenCommandMenuStyle` is a straight four-field lerp with
+no `mixOklch` call. All midpoint values are tested exactly.
+
+**Filter function** (`filterCommandItems`) is a pure exported utility —
+case-insensitive substring match on the visible query prefix — and is tested
+directly here.
+
+## How to run
+
+```bash
+bun install
+bun test registry/remocn-ui/command-menu/__tests__
+```
+
+## What is covered
+
+- **`DEFAULT_DURATION`** — asserts the constant is 12 frames (longer than the
+ item's 8; the container transitions more slowly).
+
+- **`filterCommandItems(items, query, revealCount)`** — exported pure filter.
+ Asserts: empty query/whitespace-only → all items returned; `revealCount=0`
+ → all items (visible prefix is empty); empty items list → empty result;
+ prefix narrows: `"profile"` → 1 match, `"se"` → 2 matches (Settings +
+ Search docs), `"file"` → New File, `"new"` → New File; no-match returns
+ empty array; case-insensitivity (uppercase/mixed queries match lowercase
+ labels); `revealCount` slices the query (revealCount=2 on `"settings"` uses
+ `"se"` → 2 matches; revealCount=8 uses full `"settings"` → 1 match);
+ result items are the same object references (no cloning).
+
+- **`commandMenuStyleContext(theme)`** — pure token derivation. Asserts all
+ 8 scalar fields plus `itemCtx`: `panelBg→popover`, `panelBorder→border`,
+ `inputFg→popoverForeground`, `placeholderFg→mutedForeground`,
+ `mutedFg→mutedForeground`, `divider→border`, `caret→foreground`,
+ `radius→radius`. `itemCtx` is a nested `CommandMenuItemStyleContext` with
+ `idleBg→popover`. Light/dark themes produce different `panelBg`.
+
+- **`commandMenuStyle(state, ctx)` presets** — every field for every state
+ (2 states × 4 fields = 8 assertions):
+ - `closed`: backdropOpacity=0, panelOpacity=0, panelScale=0.96, panelTranslateY=8
+ - `opened`: backdropOpacity=1, panelOpacity=1, panelScale=1, panelTranslateY=0
+ - All fields distinct between states; all fields numeric for every state.
+
+- **`tweenCommandMenuStyle(a, b, t)`** — at t=0 all four fields equal `a`; at
+ t=1 all equal `b`; at t=0.5 exact midpoints: backdropOpacity=0.5,
+ panelOpacity=0.5, panelScale=0.98, panelTranslateY=4; at t=0.25:
+ backdropOpacity=0.25, panelOpacity=0.25, panelScale=0.97,
+ panelTranslateY=6; identity case; reverse direction (opened→closed same
+ midpoints by symmetry).
+
+- **`resolveCommandMenuTransition`** — pure mirror of
+ `useCommandMenuTransition` lines 49–73 with `raw` injected. Key additional
+ contract: `easings.out` is applied to linear progress before the tween, so
+ mid-window at raw=6/dur=12 gives t=out(0.5)=0.875 → backdropOpacity=0.875
+ (not 0.5); panelTranslateY=8×(1−0.875)=1; panelScale=0.96+(1−0.96)×0.875.
+ Also asserts: before any step → closed style with both endpoints `closed`;
+ at boundary progress=0 → t=out(0)=0 → closed style; past window → fully
+ opened; speed contract (speed=2 halves the raw frame to reach a step).
+
+- **`commandMenuConfig.controls`** — state/query/revealCount/selectedIndex/
+ highlightedIndex/mode wiring: state is a `select` with options
+ `["opened","closed"]` and default `"opened"`; query is a `text` with default
+ `""`; revealCount is a `number` with default 0 and min 0; selectedIndex
+ defaults to −1; highlightedIndex defaults to 0; mode defaults to `"light"`.
+
+- **`commandMenuConfig.snippet`** — import line, structural shape, state always
+ emitted; default omissions (empty query, revealCount=0, selectedIndex=−1,
+ highlightedIndex=−1, mode=light); non-default emissions; all state options
+ round-trip.
+
+## Import strategy
+
+- `../index` — `filterCommandItems`, `commandMenuStyle`,
+ `commandMenuStyleContext`, `CommandMenuState`, `CommandMenuEntry`
+- `../use-command-menu-transition` — `tweenCommandMenuStyle`, `DEFAULT_DURATION`
+- `../config` — `commandMenuConfig`
+- `@/lib/remocn-ui` — `defaultLightTheme`, `defaultDarkTheme`, `easings`,
+ `Step` type
+
+`useCommandMenuTransition` is NOT imported (it reads `useCurrentFrame()`). Its
+pure body is mirrored as `resolveCommandMenuTransition` with the frame injected
+as `raw`. `bun test` resolves tsconfig `paths`, so the `@/lib/remocn-ui` alias
+works without additional config.
+
+## Determinism grep checklist (run manually; must print NOTHING)
+
+`command-menu/index.tsx` is a pure renderer — must contain none of:
+
+```bash
+grep -nE "useState|useEffect|useCurrentFrame|onClick|onChange|addEventListener|Date\.now|Math\.random|requestAnimationFrame" \
+ registry/remocn-ui/command-menu/index.tsx
+```
+
+Expected: **no output**. Any match is a determinism violation.
+
+`use-command-menu-transition.ts` intentionally reads `useCurrentFrame()` via
+`useStateTransition` — correct and expected for the hook file.
+
+Tier-wide sweep:
+
+```bash
+grep -nE "useState|useEffect|onClick|onChange|addEventListener|Date\.now|Math\.random" \
+ registry/remocn-ui/command-menu/index.tsx registry/remocn-ui/core/*.ts
+```
diff --git a/registry/remocn-ui/command-menu/__tests__/command-menu.test.ts b/registry/remocn-ui/command-menu/__tests__/command-menu.test.ts
new file mode 100644
index 00000000..a83e1935
--- /dev/null
+++ b/registry/remocn-ui/command-menu/__tests__/command-menu.test.ts
@@ -0,0 +1,812 @@
+/**
+ * Verification tests for the PURE / DETERMINISTIC parts of `command-menu`.
+ *
+ * Scope:
+ * - registry/remocn-ui/command-menu/index.tsx
+ * filterCommandItems(items, query, revealCount) — exported pure filter
+ * commandMenuStyleContext(theme) — pure color derivation
+ * commandMenuStyle(state, ctx) — complete state→visual map
+ * - registry/remocn-ui/command-menu/use-command-menu-transition.ts
+ * tweenCommandMenuStyle(a, b, t) — pure lerp across every field
+ * DEFAULT_DURATION constant
+ * useCommandMenuTransition resolver — mirrored as resolveCommandMenuTransition
+ * with frame injected as `raw` (annotated source lines)
+ * - registry/remocn-ui/command-menu/config.ts
+ * commandMenuConfig.controls wiring + commandMenuConfig.snippet codegen
+ *
+ * The render path (index.tsx) imports `useRemocnTheme` which requires React
+ * context and cannot run headlessly — it is NOT exercised here.
+ *
+ * Runner: Bun's built-in test runner (TypeScript-native, no framework dep).
+ * bun test registry/remocn-ui/command-menu/__tests__
+ *
+ * --------------------------------------------------------------------------
+ * IMPORT STRATEGY
+ * --------------------------------------------------------------------------
+ * Relative imports for component source; `@/lib/remocn-ui` alias for core.
+ * `useCommandMenuTransition` is NOT imported — it reads `useCurrentFrame()`.
+ * Its pure body is mirrored as `resolveCommandMenuTransition` with frame injected.
+ * --------------------------------------------------------------------------
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+ filterCommandItems,
+ commandMenuStyle,
+ commandMenuStyleContext,
+ type CommandMenuState,
+ type CommandMenuEntry,
+} from "../index";
+import {
+ tweenCommandMenuStyle,
+ DEFAULT_DURATION,
+} from "../use-command-menu-transition";
+import { commandMenuConfig } from "../config";
+import { defaultLightTheme, defaultDarkTheme, easings } from "@/lib/remocn-ui";
+import type { Step } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Shared fixtures
+// ===========================================================================
+
+const VALID_STATES: readonly CommandMenuState[] = ["opened", "closed"];
+
+const SAMPLE_ITEMS: CommandMenuEntry[] = [
+ { icon: "user", label: "Profile", shortcut: "⌘ P" },
+ { icon: "settings", label: "Settings", shortcut: "⌘ S" },
+ { icon: "file", label: "New File", shortcut: "⌘ N" },
+ { icon: "search", label: "Search docs" },
+];
+
+/** Build a shared ctx for style assertions. */
+const ctx = commandMenuStyleContext(defaultLightTheme);
+
+/** Convenience wrapper for snippet(). */
+type SnippetValues = {
+ state?: string;
+ query?: string;
+ revealCount?: number;
+ selectedIndex?: number;
+ highlightedIndex?: number;
+ mode?: string;
+};
+const snippet = (values: SnippetValues): string =>
+ commandMenuConfig.snippet(values as Record<string, unknown>);
+
+// ===========================================================================
+// 1. DEFAULT_DURATION constant
+// ===========================================================================
+
+describe("DEFAULT_DURATION", () => {
+ it("is 12 frames (container default — longer than item's 8)", () => {
+ expect(DEFAULT_DURATION).toBe(12);
+ });
+});
+
+// ===========================================================================
+// 2. filterCommandItems — exported pure filter
+// MIRROR of index.tsx lines 69-81
+// Case-insensitive substring on query.slice(0, revealCount).
+// ===========================================================================
+
+describe("filterCommandItems: empty visible prefix → all items returned", () => {
+ it("returns all items when query is empty string", () => {
+ expect(filterCommandItems(SAMPLE_ITEMS, "", undefined)).toHaveLength(4);
+ });
+
+ it("returns all items when query is empty and revealCount is undefined", () => {
+ const result = filterCommandItems(SAMPLE_ITEMS, "", undefined);
+ expect(result).toEqual(SAMPLE_ITEMS);
+ });
+
+ it("returns all items when revealCount=0 (visible prefix is empty)", () => {
+ expect(filterCommandItems(SAMPLE_ITEMS, "settings", 0)).toHaveLength(4);
+ });
+
+ it("returns all items when query is whitespace only", () => {
+ expect(filterCommandItems(SAMPLE_ITEMS, " ", undefined)).toHaveLength(4);
+ });
+
+ it("returns empty array when items list is empty", () => {
+ expect(filterCommandItems([], "profile", undefined)).toHaveLength(0);
+ });
+});
+
+describe("filterCommandItems: prefix narrows results", () => {
+ it("'profile' matches exactly one item (Profile)", () => {
+ const result = filterCommandItems(SAMPLE_ITEMS, "profile", undefined);
+ expect(result).toHaveLength(1);
+ expect(result[0].label).toBe("Profile");
+ });
+
+ it("'se' matches Settings and Search docs (substring in label)", () => {
+ const result = filterCommandItems(SAMPLE_ITEMS, "se", undefined);
+ expect(result).toHaveLength(2);
+ const labels = result.map((i) => i.label);
+ expect(labels).toContain("Settings");
+ expect(labels).toContain("Search docs");
+ });
+
+ it("'file' matches New File (substring in middle of label)", () => {
+ const result = filterCommandItems(SAMPLE_ITEMS, "file", undefined);
+ expect(result).toHaveLength(1);
+ expect(result[0].label).toBe("New File");
+ });
+
+ it("'new' matches New File", () => {
+ const result = filterCommandItems(SAMPLE_ITEMS, "new", undefined);
+ expect(result).toHaveLength(1);
+ expect(result[0].label).toBe("New File");
+ });
+});
+
+describe("filterCommandItems: no-match → empty array", () => {
+ it("returns empty array when query matches nothing", () => {
+ expect(filterCommandItems(SAMPLE_ITEMS, "xyz", undefined)).toHaveLength(0);
+ });
+
+ it("returns empty array for a long non-matching query", () => {
+ expect(filterCommandItems(SAMPLE_ITEMS, "zzzzzzz", undefined)).toHaveLength(0);
+ });
+});
+
+describe("filterCommandItems: case-insensitivity", () => {
+ it("uppercase query matches lowercase label", () => {
+ expect(filterCommandItems(SAMPLE_ITEMS, "PROFILE", undefined)).toHaveLength(1);
+ });
+
+ it("mixed case query matches label", () => {
+ expect(filterCommandItems(SAMPLE_ITEMS, "SeTtInGs", undefined)).toHaveLength(1);
+ });
+
+ it("lowercase query matches mixed-case label ('new file')", () => {
+ const result = filterCommandItems(SAMPLE_ITEMS, "new file", undefined);
+ expect(result).toHaveLength(1);
+ expect(result[0].label).toBe("New File");
+ });
+});
+
+describe("filterCommandItems: revealCount slices the query", () => {
+ it("revealCount=2 on 'settings' uses only 'se' → 2 matches", () => {
+ const result = filterCommandItems(SAMPLE_ITEMS, "settings", 2);
+ expect(result).toHaveLength(2);
+ const labels = result.map((i) => i.label);
+ expect(labels).toContain("Settings");
+ expect(labels).toContain("Search docs");
+ });
+
+ it("revealCount=8 on 'settings' uses full 'settings' → 1 match", () => {
+ const result = filterCommandItems(SAMPLE_ITEMS, "settings", 8);
+ expect(result).toHaveLength(1);
+ expect(result[0].label).toBe("Settings");
+ });
+
+ it("revealCount=1 on 'profile' uses only 'p' → Profile matches", () => {
+ const result = filterCommandItems(SAMPLE_ITEMS, "profile", 1);
+ // 'p' should match Profile
+ const labels = result.map((i) => i.label);
+ expect(labels).toContain("Profile");
+ });
+
+ it("revealCount > query length uses full query (no index error)", () => {
+ // query='se' (2 chars), revealCount=100 → uses full 'se'
+ const result = filterCommandItems(SAMPLE_ITEMS, "se", 100);
+ expect(result).toHaveLength(2);
+ });
+});
+
+describe("filterCommandItems: result preserves original item objects", () => {
+ it("filtered items are the same object references (no cloning)", () => {
+ const result = filterCommandItems(SAMPLE_ITEMS, "profile", undefined);
+ expect(result[0]).toBe(SAMPLE_ITEMS[0]);
+ });
+});
+
+// ===========================================================================
+// 3. commandMenuStyleContext — pure theme → context derivation
+// MIRROR of index.tsx lines 119-133
+// ===========================================================================
+
+describe("commandMenuStyleContext: 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("inputFg equals theme.popoverForeground", () => {
+ expect(ctx.inputFg).toBe(defaultLightTheme.popoverForeground);
+ });
+
+ it("placeholderFg equals theme.mutedForeground", () => {
+ expect(ctx.placeholderFg).toBe(defaultLightTheme.mutedForeground);
+ });
+
+ it("mutedFg equals theme.mutedForeground", () => {
+ expect(ctx.mutedFg).toBe(defaultLightTheme.mutedForeground);
+ });
+
+ it("divider equals theme.border", () => {
+ expect(ctx.divider).toBe(defaultLightTheme.border);
+ });
+
+ it("caret equals theme.foreground", () => {
+ expect(ctx.caret).toBe(defaultLightTheme.foreground);
+ });
+
+ it("radius equals theme.radius", () => {
+ expect(ctx.radius).toBe(defaultLightTheme.radius);
+ });
+});
+
+describe("commandMenuStyleContext: itemCtx is a nested CommandMenuItemStyleContext", () => {
+ it("itemCtx is an object", () => {
+ expect(typeof ctx.itemCtx).toBe("object");
+ expect(ctx.itemCtx).not.toBeNull();
+ });
+
+ it("itemCtx.idleBg equals theme.popover (delegated to commandMenuItemStyleContext)", () => {
+ expect(ctx.itemCtx.idleBg).toBe(defaultLightTheme.popover);
+ });
+});
+
+describe("commandMenuStyleContext: theme independence", () => {
+ const ctxDark = commandMenuStyleContext(defaultDarkTheme);
+
+ it("panelBg differs between light and dark themes", () => {
+ expect(ctx.panelBg).not.toBe(ctxDark.panelBg);
+ });
+});
+
+// ===========================================================================
+// 4. commandMenuStyle — pure (state, ctx) => CommandMenuStyle presets
+// MIRROR of index.tsx lines 139-159
+// Every field is asserted for every state.
+// ===========================================================================
+
+describe("commandMenuStyle: closed state — off-screen keyframe", () => {
+ const s = commandMenuStyle("closed", ctx);
+
+ it("backdropOpacity is 0 (backdrop hidden)", () => {
+ expect(s.backdropOpacity).toBe(0);
+ });
+
+ it("panelOpacity is 0 (panel invisible)", () => {
+ expect(s.panelOpacity).toBe(0);
+ });
+
+ it("panelScale is 0.96 (slightly shrunken)", () => {
+ expect(s.panelScale).toBeCloseTo(0.96, 10);
+ });
+
+ it("panelTranslateY is 8 (enters from 8px above rest)", () => {
+ expect(s.panelTranslateY).toBe(8);
+ });
+});
+
+describe("commandMenuStyle: opened state — resting keyframe", () => {
+ const s = commandMenuStyle("opened", ctx);
+
+ it("backdropOpacity is 1 (backdrop fully visible)", () => {
+ expect(s.backdropOpacity).toBe(1);
+ });
+
+ it("panelOpacity is 1 (panel fully visible)", () => {
+ expect(s.panelOpacity).toBe(1);
+ });
+
+ it("panelScale is 1 (full size)", () => {
+ expect(s.panelScale).toBe(1);
+ });
+
+ it("panelTranslateY is 0 (at rest position)", () => {
+ expect(s.panelTranslateY).toBe(0);
+ });
+});
+
+describe("commandMenuStyle: closed and opened have distinct values on every field", () => {
+ const closed = commandMenuStyle("closed", ctx);
+ const opened = commandMenuStyle("opened", ctx);
+
+ it("backdropOpacity: 0 vs 1", () => {
+ expect(closed.backdropOpacity).not.toBe(opened.backdropOpacity);
+ });
+
+ it("panelOpacity: 0 vs 1", () => {
+ expect(closed.panelOpacity).not.toBe(opened.panelOpacity);
+ });
+
+ it("panelScale: 0.96 vs 1", () => {
+ expect(closed.panelScale).not.toBe(opened.panelScale);
+ });
+
+ it("panelTranslateY: 8 vs 0", () => {
+ expect(closed.panelTranslateY).not.toBe(opened.panelTranslateY);
+ });
+});
+
+describe("commandMenuStyle: every state produces complete CommandMenuStyle", () => {
+ it("all four fields are numeric for every state", () => {
+ for (const state of VALID_STATES) {
+ const s = commandMenuStyle(state, ctx);
+ expect(typeof s.backdropOpacity).toBe("number");
+ expect(typeof s.panelOpacity).toBe("number");
+ expect(typeof s.panelScale).toBe("number");
+ expect(typeof s.panelTranslateY).toBe("number");
+ }
+ });
+});
+
+// ===========================================================================
+// 5. tweenCommandMenuStyle — pure lerp across all four numeric fields
+// MIRROR of use-command-menu-transition.ts lines 22-35
+// All fields are numbers — no color mixing; straight lerp on everything.
+// ===========================================================================
+
+describe("tweenCommandMenuStyle: t=0 returns values equal to `a`", () => {
+ const a = commandMenuStyle("closed", ctx);
+ const b = commandMenuStyle("opened", ctx);
+ const r = tweenCommandMenuStyle(a, b, 0);
+
+ it("backdropOpacity equals a.backdropOpacity at t=0", () => {
+ expect(r.backdropOpacity).toBeCloseTo(a.backdropOpacity, 10);
+ });
+
+ it("panelOpacity equals a.panelOpacity at t=0", () => {
+ expect(r.panelOpacity).toBeCloseTo(a.panelOpacity, 10);
+ });
+
+ it("panelScale equals a.panelScale at t=0", () => {
+ expect(r.panelScale).toBeCloseTo(a.panelScale, 10);
+ });
+
+ it("panelTranslateY equals a.panelTranslateY at t=0", () => {
+ expect(r.panelTranslateY).toBeCloseTo(a.panelTranslateY, 10);
+ });
+});
+
+describe("tweenCommandMenuStyle: t=1 returns values equal to `b`", () => {
+ const a = commandMenuStyle("closed", ctx);
+ const b = commandMenuStyle("opened", ctx);
+ const r = tweenCommandMenuStyle(a, b, 1);
+
+ it("backdropOpacity equals b.backdropOpacity at t=1", () => {
+ expect(r.backdropOpacity).toBeCloseTo(b.backdropOpacity, 10);
+ });
+
+ it("panelOpacity equals b.panelOpacity at t=1", () => {
+ expect(r.panelOpacity).toBeCloseTo(b.panelOpacity, 10);
+ });
+
+ it("panelScale equals b.panelScale at t=1", () => {
+ expect(r.panelScale).toBeCloseTo(b.panelScale, 10);
+ });
+
+ it("panelTranslateY equals b.panelTranslateY at t=1", () => {
+ expect(r.panelTranslateY).toBeCloseTo(b.panelTranslateY, 10);
+ });
+});
+
+describe("tweenCommandMenuStyle: t=0.5 midpoint (closed → opened)", () => {
+ // closed: backdropOpacity=0, panelOpacity=0, panelScale=0.96, panelTranslateY=8
+ // opened: backdropOpacity=1, panelOpacity=1, panelScale=1, panelTranslateY=0
+ // midpoint: 0.5, 0.5, 0.98, 4
+ const a = commandMenuStyle("closed", ctx);
+ const b = commandMenuStyle("opened", ctx);
+ const r = tweenCommandMenuStyle(a, b, 0.5);
+
+ it("backdropOpacity midpoint: 0 → 1 gives 0.5", () => {
+ expect(r.backdropOpacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("panelOpacity midpoint: 0 → 1 gives 0.5", () => {
+ expect(r.panelOpacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("panelScale midpoint: 0.96 → 1 gives 0.98", () => {
+ expect(r.panelScale).toBeCloseTo(0.98, 10);
+ });
+
+ it("panelTranslateY midpoint: 8 → 0 gives 4", () => {
+ expect(r.panelTranslateY).toBeCloseTo(4, 10);
+ });
+});
+
+describe("tweenCommandMenuStyle: t=0.25 quarter-point (closed → opened)", () => {
+ // backdropOpacity: 0.25, panelOpacity: 0.25, panelScale: 0.97, panelTranslateY: 6
+ const a = commandMenuStyle("closed", ctx);
+ const b = commandMenuStyle("opened", ctx);
+ const r = tweenCommandMenuStyle(a, b, 0.25);
+
+ it("backdropOpacity at t=0.25 is 0.25", () => {
+ expect(r.backdropOpacity).toBeCloseTo(0.25, 10);
+ });
+
+ it("panelOpacity at t=0.25 is 0.25", () => {
+ expect(r.panelOpacity).toBeCloseTo(0.25, 10);
+ });
+
+ it("panelScale at t=0.25 is 0.97", () => {
+ expect(r.panelScale).toBeCloseTo(0.97, 10);
+ });
+
+ it("panelTranslateY at t=0.25 is 6", () => {
+ expect(r.panelTranslateY).toBeCloseTo(6, 10);
+ });
+});
+
+describe("tweenCommandMenuStyle: identity (a === b)", () => {
+ const s = commandMenuStyle("opened", ctx);
+
+ it("all fields unchanged when both endpoints are identical", () => {
+ const r = tweenCommandMenuStyle(s, s, 0.5);
+ expect(r.backdropOpacity).toBeCloseTo(s.backdropOpacity, 10);
+ expect(r.panelOpacity).toBeCloseTo(s.panelOpacity, 10);
+ expect(r.panelScale).toBeCloseTo(s.panelScale, 10);
+ expect(r.panelTranslateY).toBeCloseTo(s.panelTranslateY, 10);
+ });
+});
+
+describe("tweenCommandMenuStyle: reverse direction (opened → closed)", () => {
+ // Same midpoints by symmetry
+ const a = commandMenuStyle("opened", ctx);
+ const b = commandMenuStyle("closed", ctx);
+ const r = tweenCommandMenuStyle(a, b, 0.5);
+
+ it("backdropOpacity midpoint: 1 → 0 gives 0.5", () => {
+ expect(r.backdropOpacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("panelTranslateY midpoint: 0 → 8 gives 4", () => {
+ expect(r.panelTranslateY).toBeCloseTo(4, 10);
+ });
+});
+
+// ===========================================================================
+// 6. useCommandMenuTransition resolver replica
+// MIRRORS use-command-menu-transition.ts lines 49-73.
+// `useCommandMenuTransition` calls `useStateTransition` (reads useCurrentFrame())
+// then applies `easings.out(progress)` and `tweenCommandMenuStyle`.
+// We inject `raw` in place of useCurrentFrame().
+//
+// The key additional contract beyond core timeline.test.ts: progress is
+// eased with `easings.out` before the tween, making the result non-linear.
+//
+// MAINTENANCE CONTRACT: if use-command-menu-transition.ts lines 49-73 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 (lines 55-73).
+ * `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-command-menu-transition.ts:useCommandMenuTransition (lines 49-73).
+ * `raw` is injected in place of useCurrentFrame().
+ * Annotated source lines:
+ * line 57: destructure speed + defaultDuration from opts
+ * lines 61-66: useStateTransition (mirrored as resolveStateTransition)
+ * line 67: t = easings.out(progress) ← MIRROR line 67
+ * lines 68-72: tweenCommandMenuStyle(from, to, t) ← MIRROR lines 68-72
+ */
+function resolveCommandMenuTransition(
+ raw: number, // injected useCurrentFrame() — MIRROR line 61
+ steps: Step<CommandMenuState>[],
+ speed = 1,
+ defaultDuration = DEFAULT_DURATION,
+): ReturnType<typeof tweenCommandMenuStyle> & { from: CommandMenuState; to: CommandMenuState; progress: number } {
+ const { from, to, progress } = resolveStateTransition( // MIRROR lines 61-66
+ raw,
+ steps,
+ "closed",
+ speed,
+ defaultDuration,
+ );
+ const t = easings.out(progress); // MIRROR line 67
+ const style = tweenCommandMenuStyle( // MIRROR lines 68-72
+ commandMenuStyle(from as CommandMenuState, ctx),
+ commandMenuStyle(to as CommandMenuState, ctx),
+ t,
+ );
+ return { ...style, from: from as CommandMenuState, to: to as CommandMenuState, progress };
+}
+
+// ---------------------------------------------------------------------------
+// Before any step: holds at closed (progress=1, tween(closed,closed,out(1)))
+// ---------------------------------------------------------------------------
+
+describe("resolveCommandMenuTransition: before any step — holds at closed", () => {
+ it("returns the closed style when no steps have started", () => {
+ const r = resolveCommandMenuTransition(0, []);
+ const closed = commandMenuStyle("closed", ctx);
+ expect(r.backdropOpacity).toBeCloseTo(closed.backdropOpacity, 10);
+ expect(r.panelOpacity).toBeCloseTo(closed.panelOpacity, 10);
+ expect(r.panelScale).toBeCloseTo(closed.panelScale, 10);
+ expect(r.panelTranslateY).toBeCloseTo(closed.panelTranslateY, 10);
+ });
+
+ it("from and to are both 'closed' before any step", () => {
+ const { from, to } = resolveCommandMenuTransition(0, []);
+ expect(from).toBe("closed");
+ expect(to).toBe("closed");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Exactly at a step boundary: progress=0, t=out(0)=0 → closed style
+// ---------------------------------------------------------------------------
+
+describe("resolveCommandMenuTransition: exactly at closed→opened step boundary", () => {
+ const steps: Step<CommandMenuState>[] = [{ at: 10, state: "opened" }];
+
+ it("at raw=10, progress=0, t=out(0)=0 → style equals closed (from)", () => {
+ const r = resolveCommandMenuTransition(10, steps);
+ const closed = commandMenuStyle("closed", ctx);
+ expect(r.progress).toBe(0);
+ expect(r.backdropOpacity).toBeCloseTo(closed.backdropOpacity, 10);
+ expect(r.panelOpacity).toBeCloseTo(closed.panelOpacity, 10);
+ });
+
+ it("from='closed', to='opened' at the step boundary", () => {
+ const { from, to } = resolveCommandMenuTransition(10, steps);
+ expect(from).toBe("closed");
+ expect(to).toBe("opened");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Mid-window: easings.out applied — non-linear (not raw 0.5)
+// ---------------------------------------------------------------------------
+
+describe("resolveCommandMenuTransition: mid-window uses easings.out (not linear)", () => {
+ // step at=0, defaultDuration=12. At raw=6: linear progress=0.5, out(0.5)=0.875
+ // backdropOpacity: tween(0, 1, 0.875) = 0.875 (not linear 0.5)
+ const steps: Step<CommandMenuState>[] = [{ at: 0, state: "opened" }];
+
+ it("backdropOpacity at raw=6 is out(0.5) ≈ 0.875 (not linear 0.5)", () => {
+ const r = resolveCommandMenuTransition(6, steps, 1, 12);
+ const t = easings.out(0.5); // 0.875
+ expect(r.backdropOpacity).toBeCloseTo(t, 8);
+ });
+
+ it("panelTranslateY at raw=6 is 8*(1-out(0.5)): 8*0.125=1", () => {
+ const r = resolveCommandMenuTransition(6, steps, 1, 12);
+ const t = easings.out(0.5); // 0.875
+ const expected = 8 * (1 - t); // lerp(8, 0, t)
+ expect(r.panelTranslateY).toBeCloseTo(expected, 8);
+ });
+
+ it("panelScale at raw=6 is 0.96 + (1-0.96)*out(0.5)", () => {
+ const r = resolveCommandMenuTransition(6, steps, 1, 12);
+ const t = easings.out(0.5);
+ const expected = 0.96 + (1 - 0.96) * t;
+ expect(r.panelScale).toBeCloseTo(expected, 8);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Past the window: fully opened
+// ---------------------------------------------------------------------------
+
+describe("resolveCommandMenuTransition: past the window → fully opened", () => {
+ const steps: Step<CommandMenuState>[] = [{ at: 0, state: "opened" }];
+
+ it("backdropOpacity is 1 after DEFAULT_DURATION frames", () => {
+ expect(resolveCommandMenuTransition(DEFAULT_DURATION, steps).backdropOpacity).toBeCloseTo(1, 10);
+ });
+
+ it("panelOpacity is 1 after DEFAULT_DURATION frames", () => {
+ expect(resolveCommandMenuTransition(DEFAULT_DURATION, steps).panelOpacity).toBeCloseTo(1, 10);
+ });
+
+ it("panelScale is 1 after DEFAULT_DURATION frames", () => {
+ expect(resolveCommandMenuTransition(DEFAULT_DURATION, steps).panelScale).toBeCloseTo(1, 10);
+ });
+
+ it("panelTranslateY is 0 after DEFAULT_DURATION frames", () => {
+ expect(resolveCommandMenuTransition(DEFAULT_DURATION, steps).panelTranslateY).toBeCloseTo(0, 10);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Speed contract
+// ---------------------------------------------------------------------------
+
+describe("resolveCommandMenuTransition: speed contract", () => {
+ const steps: Step<CommandMenuState>[] = [{ at: 12, state: "opened" }];
+
+ it("speed=2: step at=12 fires at raw=6 (eff=12)", () => {
+ expect(resolveCommandMenuTransition(6, steps, 2).to).toBe("opened");
+ });
+
+ it("speed=2: step at=12 has NOT fired at raw=5 (eff=10 < 12)", () => {
+ expect(resolveCommandMenuTransition(5, steps, 2).to).toBe("closed");
+ });
+});
+
+// ===========================================================================
+// 7. commandMenuConfig.controls — customizer control wiring
+// ===========================================================================
+
+describe("commandMenuConfig.controls: state", () => {
+ it("state is a select control", () => {
+ expect(commandMenuConfig.controls.state.type).toBe("select");
+ });
+
+ it("state options are ['opened','closed']", () => {
+ const ctrl = commandMenuConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["opened", "closed"]);
+ });
+
+ it("state default is 'opened'", () => {
+ expect(commandMenuConfig.controls.state.default).toBe("opened");
+ });
+
+ it("every state option is a valid CommandMenuState", () => {
+ const ctrl = commandMenuConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const opt of ctrl.options) {
+ expect(VALID_STATES).toContain(opt as CommandMenuState);
+ }
+ });
+});
+
+describe("commandMenuConfig.controls: query", () => {
+ it("query is a text control", () => {
+ expect(commandMenuConfig.controls.query.type).toBe("text");
+ });
+
+ it("query default is empty string", () => {
+ expect(commandMenuConfig.controls.query.default).toBe("");
+ });
+});
+
+describe("commandMenuConfig.controls: revealCount", () => {
+ it("revealCount is a number control", () => {
+ expect(commandMenuConfig.controls.revealCount.type).toBe("number");
+ });
+
+ it("revealCount default is 0", () => {
+ expect(commandMenuConfig.controls.revealCount.default).toBe(0);
+ });
+
+ it("revealCount min is 0", () => {
+ const ctrl = commandMenuConfig.controls.revealCount;
+ if (ctrl.type !== "number") throw new Error("expected number");
+ expect(ctrl.min).toBe(0);
+ });
+});
+
+describe("commandMenuConfig.controls: selectedIndex and highlightedIndex", () => {
+ it("selectedIndex is a number control with default -1", () => {
+ expect(commandMenuConfig.controls.selectedIndex.type).toBe("number");
+ expect(commandMenuConfig.controls.selectedIndex.default).toBe(-1);
+ });
+
+ it("highlightedIndex is a number control with default 0", () => {
+ expect(commandMenuConfig.controls.highlightedIndex.type).toBe("number");
+ expect(commandMenuConfig.controls.highlightedIndex.default).toBe(0);
+ });
+});
+
+describe("commandMenuConfig.controls: mode", () => {
+ it("mode is a select control", () => {
+ expect(commandMenuConfig.controls.mode.type).toBe("select");
+ });
+
+ it("mode default is 'light'", () => {
+ expect(commandMenuConfig.controls.mode.default).toBe("light");
+ });
+});
+
+// ===========================================================================
+// 8. commandMenuConfig.snippet — pure JSX string builder
+// ===========================================================================
+
+describe("commandMenuConfig.snippet: import line", () => {
+ it("includes 'import { CommandMenu }' from the correct path", () => {
+ const out = snippet({ state: "opened" });
+ expect(out).toContain("import { CommandMenu }");
+ expect(out).toContain('from "@/components/remocn/command-menu"');
+ });
+});
+
+describe("commandMenuConfig.snippet: structural invariants", () => {
+ it("contains a <CommandMenu JSX element", () => {
+ expect(snippet({ state: "opened" })).toContain("<CommandMenu");
+ });
+
+ 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}"`);
+ }
+ });
+});
+
+describe("commandMenuConfig.snippet: default props are omitted", () => {
+ it("omits query when it is empty string (the default)", () => {
+ expect(snippet({ state: "opened", query: "" })).not.toContain("query=");
+ });
+
+ it("omits revealCount when it equals 0 (default)", () => {
+ expect(snippet({ state: "opened", revealCount: 0 })).not.toContain("revealCount=");
+ });
+
+ it("omits selectedIndex when it equals -1 (default)", () => {
+ expect(snippet({ state: "opened", selectedIndex: -1 })).not.toContain("selectedIndex=");
+ });
+
+ it("omits highlightedIndex when it equals -1 (no highlight)", () => {
+ // highlightedIndex default in snippet omission is -1 (not highlighted)
+ 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("commandMenuConfig.snippet: non-default props are emitted", () => {
+ it("emits query when non-empty", () => {
+ expect(snippet({ state: "opened", query: "settings" })).toContain('query="settings"');
+ });
+
+ it("emits revealCount when non-zero", () => {
+ expect(snippet({ state: "opened", revealCount: 3 })).toContain("revealCount={3}");
+ });
+
+ it("emits selectedIndex when not -1", () => {
+ expect(snippet({ state: "opened", selectedIndex: 1 })).toContain("selectedIndex={1}");
+ });
+
+ it("emits highlightedIndex when not -1", () => {
+ 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("commandMenuConfig.snippet: state options round-trip", () => {
+ it("emits the correct state for every control option", () => {
+ const ctrl = commandMenuConfig.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/command-menu/config.ts b/registry/remocn-ui/command-menu/config.ts
new file mode 100644
index 00000000..50b2501e
--- /dev/null
+++ b/registry/remocn-ui/command-menu/config.ts
@@ -0,0 +1,79 @@
+import { type ComponentConfig, FPS, H, W } from "@/lib/customizer-config";
+import type { CommandMenuState } from "@/registry/remocn-ui/command-menu";
+
+const DEFAULT_QUERY = "";
+
+export const commandMenuConfig: ComponentConfig = {
+ componentName: "CommandMenu",
+ importPath: "@/components/remocn/command-menu",
+ controls: {
+ state: {
+ type: "select",
+ // Default to `opened` so the preview shows the revealed palette.
+ default: "opened",
+ options: ["opened", "closed"],
+ label: "State",
+ },
+ query: { type: "text", default: DEFAULT_QUERY, label: "Query" },
+ revealCount: {
+ type: "number",
+ default: 0,
+ min: 0,
+ max: 20,
+ step: 1,
+ label: "Reveal Count",
+ },
+ selectedIndex: {
+ type: "number",
+ default: -1,
+ min: -1,
+ max: 5,
+ step: 1,
+ label: "Selected Index",
+ },
+ highlightedIndex: {
+ type: "number",
+ default: 0,
+ 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 CommandMenuState) ?? "opened";
+ const query = values.query as string | undefined;
+ const revealCount = values.revealCount as number | undefined;
+ const selectedIndex = values.selectedIndex as number | undefined;
+ const highlightedIndex = values.highlightedIndex as number | undefined;
+ const mode = values.mode as string | undefined;
+
+ const props: string[] = [` state="${state}"`];
+ if (query !== undefined && query !== DEFAULT_QUERY)
+ props.push(` query="${query}"`);
+ if (revealCount !== undefined && revealCount !== 0)
+ props.push(` revealCount={${revealCount}}`);
+ if (selectedIndex !== undefined && selectedIndex !== -1)
+ props.push(` selectedIndex={${selectedIndex}}`);
+ if (highlightedIndex !== undefined && highlightedIndex !== -1)
+ props.push(` highlightedIndex={${highlightedIndex}}`);
+ if (mode !== undefined && mode !== "light")
+ props.push(` mode="${mode}"`);
+
+ return `import { CommandMenu } from "@/components/remocn/command-menu";
+
+<CommandMenu
+${props.join("\n")}
+/>`;
+ },
+};
diff --git a/registry/remocn-ui/command-menu/index.tsx b/registry/remocn-ui/command-menu/index.tsx
new file mode 100644
index 00000000..623b6695
--- /dev/null
+++ b/registry/remocn-ui/command-menu/index.tsx
@@ -0,0 +1,344 @@
+"use client";
+
+import { type RemocnTheme, useRemocnTheme } from "@/lib/remocn-ui";
+import {
+ CommandMenuItemRow,
+ commandMenuItemStyle,
+ commandMenuItemStyleContext,
+ type CommandMenuIcon,
+ type CommandMenuItemState,
+ type CommandMenuItemStyle,
+ type CommandMenuItemStyleContext,
+} from "@/components/remocn/command-menu-item";
+
+export type CommandMenuState = "opened" | "closed";
+
+/** One command row's data. */
+export interface CommandMenuEntry {
+ icon?: CommandMenuIcon;
+ label: string;
+ shortcut?: string;
+}
+
+export interface CommandMenuProps {
+ /** Current visual state (snap path). State changes snap (no enter-tweens). */
+ state?: CommandMenuState;
+ /**
+ * Resolved animated visual (smooth path). When provided, takes precedence over
+ * `state` — feed it an interpolated `CommandMenuStyle` from `useCommandMenuTransition`.
+ */
+ style?: CommandMenuStyle;
+ /** Full search query text (the visible prefix is `query.slice(0, revealCount)`). */
+ query?: string;
+ /**
+ * Number of query characters revealed so far (the caller computes this with
+ * core `revealCount`). Omitted → the whole `query` is shown.
+ */
+ revealCount?: number;
+ /** The rows to show before filtering. */
+ items?: CommandMenuEntry[];
+ /** Index (into the FILTERED list) of the persisted selection. `-1` for none. */
+ selectedIndex?: number;
+ /** Index (into the FILTERED list) of the row under the pointer. `-1` for none. */
+ highlightedIndex?: number;
+ /** Index (into the FILTERED list) of the row being pressed. `-1` for none. */
+ pressedIndex?: number;
+ /**
+ * Per-item resolved visual override (smooth path), indexed into the FILTERED
+ * list. When an entry is present it wins over the index→state derivation.
+ */
+ itemStyles?: (CommandMenuItemStyle | undefined)[];
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ className?: string;
+}
+
+/** Panel width (px). */
+const PANEL_WIDTH = 440;
+/** Inner content width (panel minus padding). */
+const CONTENT_WIDTH = PANEL_WIDTH - 16;
+/** Backdrop dim at full reveal — the overlay opacity scales up to this alpha. */
+const MAX_OVERLAY_ALPHA = 0.5;
+
+/**
+ * Filter command entries by the visible query prefix. PURE — a case-insensitive
+ * substring match on `query.slice(0, revealCount)`. An empty visible prefix
+ * matches everything. Exported so tests can mirror it and the example can keep
+ * its filtered indices in sync.
+ */
+export function filterCommandItems(
+ items: CommandMenuEntry[],
+ query: string,
+ revealCount?: number,
+): CommandMenuEntry[] {
+ const visible = (
+ revealCount === undefined ? query : query.slice(0, revealCount)
+ )
+ .trim()
+ .toLowerCase();
+ if (visible === "") return items;
+ return items.filter((item) => item.label.toLowerCase().includes(visible));
+}
+
+// ===========================================================================
+// Command-menu visual — the COMPLETE animated look for a moment in time. A
+// `state` is a named preset of this visual (`commandMenuStyle`); the smooth path
+// feeds an interpolated `CommandMenuStyle` straight through. The component is a
+// pure renderer of whichever style it receives. Per-row visuals are derived from
+// the index props (or `itemStyles`), independent of this container reveal.
+// ===========================================================================
+
+export interface CommandMenuStyle {
+ /** Backdrop dim reveal 0→1 (scales `MAX_OVERLAY_ALPHA`). */
+ backdropOpacity: number;
+ /** Panel fade 0→1. */
+ panelOpacity: number;
+ /** Panel zoom 0.96→1. */
+ panelScale: number;
+ /** Panel lift 8→0 (px). */
+ panelTranslateY: number;
+}
+
+/** Concrete colors for the active theme, resolved once per render. */
+export interface CommandMenuStyleContext {
+ panelBg: string;
+ panelBorder: string;
+ inputFg: string;
+ placeholderFg: string;
+ mutedFg: string;
+ divider: string;
+ caret: string;
+ radius: number;
+ itemCtx: CommandMenuItemStyleContext;
+}
+
+/**
+ * Derive the concrete colors for a theme. Pure — call it once and reuse the
+ * result for every `commandMenuStyle(state, ctx)` preset.
+ */
+export function commandMenuStyleContext(
+ theme: RemocnTheme,
+): CommandMenuStyleContext {
+ return {
+ panelBg: theme.popover,
+ panelBorder: theme.border,
+ inputFg: theme.popoverForeground,
+ placeholderFg: theme.mutedForeground,
+ mutedFg: theme.mutedForeground,
+ divider: theme.border,
+ caret: theme.foreground,
+ radius: theme.radius,
+ itemCtx: commandMenuItemStyleContext(theme),
+ };
+}
+
+/**
+ * The COMPLETE resting visual for a state — a pure `(state, ctx) =>
+ * CommandMenuStyle` map. To change how a state looks, edit one entry.
+ */
+export function commandMenuStyle(
+ state: CommandMenuState,
+ _ctx: CommandMenuStyleContext,
+): CommandMenuStyle {
+ switch (state) {
+ case "opened":
+ return {
+ backdropOpacity: 1,
+ panelOpacity: 1,
+ panelScale: 1,
+ panelTranslateY: 0,
+ };
+ default:
+ return {
+ backdropOpacity: 0,
+ panelOpacity: 0,
+ panelScale: 0.96,
+ panelTranslateY: 8,
+ };
+ }
+}
+
+/** Resolve one row's state from the index props (used when no itemStyle override). */
+function rowState(
+ i: number,
+ selectedIndex: number,
+ highlightedIndex: number,
+ pressedIndex: number,
+): CommandMenuItemState {
+ if (i === pressedIndex) return "press";
+ if (i === selectedIndex) return "selected";
+ if (i === highlightedIndex) return "hover";
+ return "idle";
+}
+
+export function CommandMenu({
+ state = "closed",
+ style,
+ query = "",
+ revealCount,
+ items = [
+ { icon: "user", label: "Profile", shortcut: "⌘ P" },
+ { icon: "settings", label: "Settings", shortcut: "⌘ S" },
+ { icon: "file", label: "New File", shortcut: "⌘ N" },
+ { icon: "search", label: "Search docs" },
+ ],
+ selectedIndex = -1,
+ highlightedIndex = -1,
+ pressedIndex = -1,
+ itemStyles,
+ theme: themeOverride,
+ mode,
+ className,
+}: CommandMenuProps) {
+ const theme = useRemocnTheme(themeOverride, mode);
+ const ctx = commandMenuStyleContext(theme);
+ const v = style ?? commandMenuStyle(state, ctx);
+
+ const visibleQuery =
+ revealCount === undefined ? query : query.slice(0, revealCount);
+ const filtered = filterCommandItems(items, query, revealCount);
+
+ return (
+ // TRANSPARENT modal wrapper — like dialog, this composes OVER another scene,
+ // so it paints no opaque background. Its intrinsic inset:0 backdrop is why no
+ // preview wrapper is needed (the customizer mounts this directly).
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ // Command palettes sit in the upper third, not dead-center.
+ alignItems: "flex-start",
+ justifyContent: "center",
+ paddingTop: "18%",
+ fontFamily:
+ "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif",
+ }}
+ >
+ {/* Backdrop dim — fades in as the palette opens. */}
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ background: `rgba(0, 0, 0, ${MAX_OVERLAY_ALPHA * v.backdropOpacity})`,
+ }}
+ />
+ <div
+ className={className}
+ style={{
+ position: "relative",
+ width: PANEL_WIDTH,
+ boxSizing: "border-box",
+ transformOrigin: "top",
+ transform: `translateY(${v.panelTranslateY}px) scale(${v.panelScale})`,
+ opacity: v.panelOpacity,
+ background: ctx.panelBg,
+ border: `1px solid ${ctx.panelBorder}`,
+ borderRadius: ctx.radius + 6,
+ padding: 8,
+ display: "flex",
+ flexDirection: "column",
+ boxShadow: "0 24px 48px -12px rgba(0,0,0,0.25)",
+ }}
+ >
+ {/* Search row — magnifier + typed query + caret. */}
+ <div
+ style={{
+ display: "flex",
+ alignItems: "center",
+ gap: 10,
+ padding: "8px 10px",
+ }}
+ >
+ <svg width={18} height={18} viewBox="0 0 24 24" fill="none">
+ <path
+ d="M11 4a7 7 0 1 0 0 14 7 7 0 0 0 0-14ZM20 20l-3.5-3.5"
+ stroke={ctx.mutedFg}
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </svg>
+ <span
+ style={{
+ display: "flex",
+ alignItems: "center",
+ fontSize: 15,
+ letterSpacing: "-0.01em",
+ color: visibleQuery ? ctx.inputFg : ctx.placeholderFg,
+ }}
+ >
+ {visibleQuery || "Type a command or search…"}
+ {/* Caret sits after the revealed text. */}
+ <span
+ style={{
+ display: "inline-block",
+ width: 1.5,
+ height: 18,
+ marginLeft: 1,
+ background: ctx.caret,
+ }}
+ />
+ </span>
+ </div>
+ {/* Divider. */}
+ <div
+ style={{
+ height: 1,
+ background: ctx.divider,
+ margin: "4px 0",
+ }}
+ />
+ {/* List of rows, or the empty state. */}
+ <div
+ style={{
+ display: "flex",
+ flexDirection: "column",
+ gap: 2,
+ padding: "4px 0",
+ }}
+ >
+ {filtered.length === 0 ? (
+ <div
+ style={{
+ padding: "20px 12px",
+ textAlign: "center",
+ fontSize: 14,
+ color: ctx.mutedFg,
+ }}
+ >
+ No results found.
+ </div>
+ ) : (
+ filtered.map((item, i) => {
+ const override = itemStyles?.[i];
+ return (
+ <CommandMenuItemRow
+ key={item.label}
+ style={
+ override ??
+ commandMenuItemStyle(
+ rowState(
+ i,
+ selectedIndex,
+ highlightedIndex,
+ pressedIndex,
+ ),
+ ctx.itemCtx,
+ )
+ }
+ ctx={ctx.itemCtx}
+ label={item.label}
+ icon={item.icon}
+ shortcut={item.shortcut}
+ width={CONTENT_WIDTH}
+ radius={theme.radius}
+ />
+ );
+ })
+ )}
+ </div>
+ </div>
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/command-menu/use-command-menu-transition.ts b/registry/remocn-ui/command-menu/use-command-menu-transition.ts
new file mode 100644
index 00000000..c5008410
--- /dev/null
+++ b/registry/remocn-ui/command-menu/use-command-menu-transition.ts
@@ -0,0 +1,73 @@
+"use client";
+
+import {
+ easings,
+ type RemocnTheme,
+ type Step,
+ useRemocnTheme,
+ useStateTransition,
+} from "@/lib/remocn-ui";
+import {
+ commandMenuStyle,
+ commandMenuStyleContext,
+ type CommandMenuState,
+ type CommandMenuStyle,
+} from "@/components/remocn/command-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 = 12;
+
+/** Blend two command-menu visuals: all fields are numbers, so a straight lerp. */
+export function tweenCommandMenuStyle(
+ a: CommandMenuStyle,
+ b: CommandMenuStyle,
+ t: number,
+): CommandMenuStyle {
+ return {
+ backdropOpacity:
+ a.backdropOpacity + (b.backdropOpacity - a.backdropOpacity) * t,
+ panelOpacity: a.panelOpacity + (b.panelOpacity - a.panelOpacity) * t,
+ panelScale: a.panelScale + (b.panelScale - a.panelScale) * t,
+ panelTranslateY:
+ a.panelTranslateY + (b.panelTranslateY - a.panelTranslateY) * t,
+ };
+}
+
+export interface CommandMenuTransitionOptions {
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ speed?: number;
+ defaultDuration?: number;
+}
+
+/**
+ * Timeline → resolved (eased, tweened) CommandMenuStyle. The CALLER invokes
+ * this; it reads the frame, the `<CommandMenu>` component does not. Feed the
+ * result to `<CommandMenu style={...} />` for a smooth open/close.
+ */
+export function useCommandMenuTransition(
+ steps: Step<CommandMenuState>[],
+ opts: CommandMenuTransitionOptions = {},
+): CommandMenuStyle {
+ const {
+ theme: themeOverride,
+ mode,
+ speed = 1,
+ defaultDuration = DEFAULT_DURATION,
+ } = opts;
+ const theme = useRemocnTheme(themeOverride, mode);
+ const ctx = commandMenuStyleContext(theme);
+ const { from, to, progress } = useStateTransition(
+ steps,
+ "closed",
+ speed,
+ defaultDuration,
+ );
+ const t = easings.out(progress);
+ return tweenCommandMenuStyle(
+ commandMenuStyle(from, ctx),
+ commandMenuStyle(to, ctx),
+ t,
+ );
+}
diff --git a/registry/remocn-ui/registry.json b/registry/remocn-ui/registry.json
index 2865f660..e8c06047 100644
--- a/registry/remocn-ui/registry.json
+++ b/registry/remocn-ui/registry.json
@@ -396,6 +396,46 @@
"target": "components/remocn/use-toast-transition.ts"
}
]
+ },
+ {
+ "name": "command-menu-item",
+ "type": "registry:component",
+ "title": "UI Command Menu Item",
+ "description": "A command-palette row whose idle/hover/press/selected state is a pure function of the timeline. Leading icon + label + trailing shortcut kbd. Exports an inline CommandMenuItemRow (reused by CommandMenu) and a standalone CommandMenuItem atom; the row background, label color, and icon color are keyframed presets.",
+ "dependencies": ["remotion"],
+ "registryDependencies": ["remocn-ui"],
+ "files": [
+ {
+ "path": "command-menu-item/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/command-menu-item.tsx"
+ },
+ {
+ "path": "command-menu-item/use-command-menu-item-transition.ts",
+ "type": "registry:component",
+ "target": "components/remocn/use-command-menu-item-transition.ts"
+ }
+ ]
+ },
+ {
+ "name": "command-menu",
+ "type": "registry:component",
+ "title": "UI Command Menu",
+ "description": "A ⌘K command palette whose opened/closed state is a pure function of the timeline; the panel zoom + backdrop dim are dialog-like keyframed presets. The search row reveals the typed query, the list is filtered by a pure case-insensitive substring on the visible query prefix, and rows reuse the CommandMenuItem row.",
+ "dependencies": ["remotion"],
+ "registryDependencies": ["remocn-ui", "command-menu-item"],
+ "files": [
+ {
+ "path": "command-menu/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/command-menu.tsx"
+ },
+ {
+ "path": "command-menu/use-command-menu-transition.ts",
+ "type": "registry:component",
+ "target": "components/remocn/use-command-menu-transition.ts"
+ }
+ ]
}
]
}