Skip to content

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

feat: added combobox component

dev_wandryf217e11c2e53
diff --git a/components/docs/examples/combobox-example.tsx b/components/docs/examples/combobox-example.tsx
new file mode 100644
index 00000000..8cc769ed
--- /dev/null
+++ b/components/docs/examples/combobox-example.tsx
@@ -0,0 +1,98 @@
+"use client";
+
+import { useCurrentFrame } from "remotion";
+import { revealCount } from "@/lib/remocn-ui";
+import { Combobox } from "@/registry/remocn-ui/combobox";
+import { useComboboxTransition } from "@/registry/remocn-ui/combobox/use-combobox-transition";
+import { useSelectItemTransition } from "@/registry/remocn-ui/select-item/use-select-item-transition";
+
+// Typing "ba" filters the default list ["Apple","Banana","Orange","Grape"] to ["Banana"].
+const QUERY = "ba";
+const TYPE_START = 32;
+const FPS = 30;
+const CPS = 4;
+
+export const ComboboxExampleScene = () => {
+ const frame = useCurrentFrame();
+
+ // Panel: opens at frame 16, closes at frame 100.
+ const panelStyle = useComboboxTransition([
+ { at: 16, state: "opened", duration: 12 },
+ { at: 100, state: "closed", duration: 12 },
+ ]);
+
+ // Reveal "ba" character by character starting at frame 32.
+ 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.
+ // Once "ba" is fully revealed, only Banana remains; row 0 of the filtered list.
+ const itemStyle = useSelectItemTransition([
+ { at: 60, state: "hover", duration: 8 },
+ { at: 72, state: "press", duration: 6 },
+ { at: 80, state: "selected", duration: 8 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <Combobox
+ style={panelStyle}
+ query={QUERY}
+ revealCount={revealed}
+ itemStyles={[itemStyle]}
+ />
+ </div>
+ );
+};
+
+export const comboboxExampleCode = `import { useCurrentFrame } from "remotion";
+import { revealCount } from "@/lib/remocn-ui";
+import { Combobox } from "@/components/remocn/combobox";
+import { useComboboxTransition } from "@/components/remocn/use-combobox-transition";
+import { useSelectItemTransition } from "@/components/remocn/use-select-item-transition";
+
+// Typing "ba" filters ["Apple","Banana","Orange","Grape"] to ["Banana"].
+const QUERY = "ba";
+const TYPE_START = 32;
+const FPS = 30;
+const CPS = 4;
+
+export const Scene = () => {
+ const frame = useCurrentFrame();
+
+ // Panel opens at frame 16, closes at frame 100.
+ const panelStyle = useComboboxTransition([
+ { at: 16, state: "opened", duration: 12 },
+ { at: 100, state: "closed", duration: 12 },
+ ]);
+
+ // revealCount drives how many characters of QUERY are visible.
+ const revealed = revealCount(
+ Math.max(0, frame - TYPE_START),
+ FPS,
+ QUERY.length,
+ CPS,
+ );
+
+ // Animate the first row of the filtered list once "ba" narrows it to Banana.
+ const itemStyle = useSelectItemTransition([
+ { at: 60, state: "hover", duration: 8 },
+ { at: 72, state: "press", duration: 6 },
+ { at: 80, state: "selected", duration: 8 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <Combobox
+ style={panelStyle}
+ query={QUERY}
+ revealCount={revealed}
+ itemStyles={[itemStyle]}
+ />
+ </div>
+ );
+};`;
diff --git a/components/docs/examples/index.tsx b/components/docs/examples/index.tsx
index 6f980d2e..23257e5e 100644
--- a/components/docs/examples/index.tsx
+++ b/components/docs/examples/index.tsx
@@ -44,6 +44,10 @@ import {
SliderExampleScene,
sliderExampleCode,
} from "./slider-example";
+import {
+ ComboboxExampleScene,
+ comboboxExampleCode,
+} from "./combobox-example";
export interface ExampleEntry {
Component: ComponentType;
@@ -231,4 +235,13 @@ export const examples: Record<string, ExampleEntry> = {
width: W,
height: H,
},
+ "combobox-example": {
+ Component: ComboboxExampleScene,
+ code: comboboxExampleCode,
+ // Panel closes at 100 + dur 12 = 112; a short settle then loop.
+ durationInFrames: 120,
+ fps: FPS,
+ width: W,
+ height: H,
+ },
};
diff --git a/content/docs/ui/components/combobox.mdx b/content/docs/ui/components/combobox.mdx
new file mode 100644
index 00000000..50edef44
--- /dev/null
+++ b/content/docs/ui/components/combobox.mdx
@@ -0,0 +1,246 @@
+---
+title: Combobox
+description: A searchable select with a typed-query input, filtered panel, and row selection
+---
+
+<ComponentPreview name="combobox" />
+
+A state atom representing a searchable select: a text-input trigger and a panel of filtered options. 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 reveals below the trigger with opacity, scale, and vertical lift animations. The trigger reuses the Input visual presets; the panel rows reuse the SelectItem atom.
+
+## Installation
+
+<InstallBlock name="combobox" />
+
+<Note>
+Installing `combobox` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`), the `input` primitive, and the `select-item` atom via `registryDependencies` (`["remocn-ui", "input", "select-item"]`). You do not need to install them separately. The trigger renders from Input's visual presets, and the panel renders a column of SelectItem rows.
+</Note>
+
+## Example
+
+<LiveExample name="combobox-example" />
+
+## States
+
+`ComboboxState` is:
+
+```ts
+type ComboboxState =
+ | "opened" // panel opacity 1, scale 1, translateY 0
+ | "closed" // panel opacity 0, scale 0.96, translateY -4px
+```
+
+`opened` reveals the dropdown panel below the trigger. `closed` hides it.
+
+## Snap usage
+
+Pass `state` directly — the component snaps instantly to that visual. Useful for static previews or when you drive state from your own logic:
+
+```tsx
+import { Combobox } from "@/components/remocn/combobox";
+
+export const Scene = () => (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <Combobox state="opened" query="ba" />
+ </div>
+);
+```
+
+To drive state from the timeline, use `useCurrentState`:
+
+```tsx
+import { useCurrentState } from "@/lib/remocn-ui";
+import { Combobox } from "@/components/remocn/combobox";
+
+export const Scene = () => {
+ const state = useCurrentState(
+ [
+ { at: 16, state: "opened" },
+ { at: 96, state: "closed" },
+ ],
+ "closed",
+ );
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <Combobox state={state} />
+ </div>
+ );
+};
+```
+
+Each `at` is a **Sequence-local authored frame**. State persists between steps. See [Concepts](/docs/ui/concepts) for the full `useCurrentState` API.
+
+## Smooth transitions
+
+State changes via `state` snap with no cross-fade. For an animated open/close, use `useComboboxTransition` from the copied `use-combobox-transition.ts` file. It reads the frame, interpolates between state presets, and returns a resolved `ComboboxStyle` — pass it to the `style` prop:
+
+```tsx
+import { Combobox } from "@/components/remocn/combobox";
+import { useComboboxTransition } from "@/components/remocn/use-combobox-transition";
+
+export const Scene = () => {
+ const style = useComboboxTransition([
+ { at: 16, state: "opened", duration: 12 },
+ { at: 96, state: "closed", duration: 12 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <Combobox 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-combobox-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 option list against the visible prefix and shows a "No results found." 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 { Combobox } from "@/components/remocn/combobox";
+import { useComboboxTransition } from "@/components/remocn/use-combobox-transition";
+
+const QUERY = "ba";
+const TYPE_START = 32;
+
+export const Scene = () => {
+ const frame = useCurrentFrame();
+
+ const style = useComboboxTransition([
+ { at: 16, state: "opened", duration: 12 },
+ { at: 96, state: "closed", duration: 12 },
+ ]);
+
+ // 2 chars at 4 chars/sec @ 30 fps = 15 frames total typing window.
+ const revealed = revealCount(
+ Math.max(0, frame - TYPE_START), // typing starts at frame 32
+ 30, // fps
+ QUERY.length, // total characters
+ 4, // chars per second
+ );
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <Combobox style={style} 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 `filterComboboxItems(items, query, revealCount)` if you need it in your own logic.
+
+## Items
+
+The panel renders a column of **SelectItem** rows — one per filtered option. The row visual is the same SelectItem atom used by the Select and Dropdown Menu components. See the [Select page](/docs/ui/components/select#items) for the full `SelectItemState` documentation (`idle`, `hover`, `press`, `selected`) and the `SelectItem` atom preview.
+
+When you install `combobox`, the `select-item` atom is automatically pulled in via `registryDependencies` — no separate install needed. The `Combobox` container derives each row's state from `selectedIndex`, `highlightedIndex`, and `pressedIndex` (all 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 `useSelectItemTransition`:
+
+```tsx
+import { useSelectItemTransition } from "@/components/remocn/use-select-item-transition";
+
+const itemStyle = useSelectItemTransition([
+ { at: 60, state: "hover", duration: 8 },
+ { at: 72, state: "press", duration: 6 },
+ { at: 80, state: "selected", duration: 8 },
+]);
+
+// Pass to Combobox via itemStyles (indexed into the FILTERED list):
+<Combobox 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: "ComboboxStyle",
+ description: "Resolved animated visual (smooth path). Pass an interpolated ComboboxStyle from useComboboxTransition. 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: "placeholder",
+ type: "string",
+ default: "\"Select a fruit…\"",
+ description: "Trigger placeholder shown before any query is typed.",
+ },
+ {
+ name: "items",
+ type: "string[]",
+ default: "[\"Apple\", \"Banana\", \"Orange\", \"Grape\"]",
+ description: "The full option list before filtering. Each entry is a plain 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: "(SelectItemStyle | undefined)[]",
+ description: "Per-row resolved visual override (smooth path), indexed into the FILTERED list. When present it wins over the index-to-state derivation. Drive individual rows with useSelectItemTransition.",
+ },
+ {
+ name: "inputStyle",
+ type: "InputStyle",
+ description: "Resolved Input visual for the trigger (smooth path). Drive it with useInputTransition for a focus-ring + typed-text reveal animation. Defaults to the typing look once a query is revealed, else idle.",
+ },
+ {
+ name: "theme",
+ type: "Partial<RemocnTheme>",
+ description: "Per-component theme override. Merges with the active RemocnUIProvider theme and the mode defaults. Must be concrete oklch/hex/rgb values — not CSS custom properties.",
+ },
+ {
+ name: "mode",
+ type: "\"light\" | \"dark\"",
+ default: "\"light\"",
+ description: "Sets the base palette. Overrides the mode on RemocnUIProvider when both are present.",
+ },
+ {
+ name: "className",
+ type: "string",
+ description: "Optional className applied to the outer wrapper element.",
+ },
+ ]}
+/>
diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.json
index 69fb0a9d..29903b0b 100644
--- a/content/docs/ui/components/meta.json
+++ b/content/docs/ui/components/meta.json
@@ -1,5 +1,5 @@
{
"title": "Components",
"collapsible": false,
- "pages": ["accordion", "alert-dialog", "button", "checkbox", "command-menu", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "progress", "radio", "select", "skeleton", "slider", "spinner", "switch", "tabs", "toast", "tooltip"]
+ "pages": ["accordion", "alert-dialog", "button", "checkbox", "combobox", "command-menu", "cursor", "dialog", "drawer", "sheet", "dropdown-menu", "input", "progress", "radio", "select", "skeleton", "slider", "spinner", "switch", "tabs", "toast", "tooltip"]
}
diff --git a/registry/__index__.tsx b/registry/__index__.tsx
index 20318f46..1e152806 100644
--- a/registry/__index__.tsx
+++ b/registry/__index__.tsx
@@ -155,6 +155,8 @@ import { SkeletonPreview } from "@/registry/remocn-ui/skeleton/preview";
import { skeletonConfig } from "@/registry/remocn-ui/skeleton/config";
import { SliderPreview } from "@/registry/remocn-ui/slider/preview";
import { sliderConfig } from "@/registry/remocn-ui/slider/config";
+import { Combobox } from "@/registry/remocn-ui/combobox";
+import { comboboxConfig } from "@/registry/remocn-ui/combobox/config";
import { ZoomThroughTransition } from "@/registry/remocn/zoom-through-transition";
import { zoomThroughTransitionConfig } from "@/registry/remocn/zoom-through-transition/config";
@@ -377,6 +379,9 @@ const registry: Record<string, RegistryEntry> = {
// slider's customizer Component is the preview-only SliderPreview wrapper: a
// bare inline bar would sit top-left, so the wrapper centers it on a stage.
"slider": { Component: SliderPreview, config: sliderConfig },
+ // combobox registers RAW (no preview wrapper): like select it paints its own
+ // opaque inset:0 wrapper, so the customizer mounts it directly and it centers.
+ "combobox": { Component: Combobox, config: comboboxConfig },
"spinner": { Component: Spinner, config: spinnerConfig },
};
diff --git a/registry/remocn-ui/combobox/__tests__/README.md b/registry/remocn-ui/combobox/__tests__/README.md
new file mode 100644
index 00000000..e116dd8b
--- /dev/null
+++ b/registry/remocn-ui/combobox/__tests__/README.md
@@ -0,0 +1,67 @@
+# combobox/__tests__
+
+Verification tests for the pure, deterministic surface of the `combobox` primitive.
+
+## What is tested
+
+| Section | Source | Coverage |
+|---------|--------|----------|
+| `DEFAULT_DURATION` | `use-combobox-transition.ts` | Constant equals 12 |
+| `filterComboboxItems` | `index.tsx` lines 77–89 | Empty prefix → all; prefix narrows; no-match → empty; case-insensitive; revealCount slicing; reference preservation |
+| `comboboxStyle` | `index.tsx` lines 138–148 | closed keyframe full fields; opened keyframe full fields; distinct per state; all fields numeric |
+| `tweenComboboxStyle` | `use-combobox-transition.ts` lines 22–33 | t=0 → a; t=1 → b; t=0.5 midpoint; t=0.25 quarter; identity; reverse direction |
+| `resolveComboboxTransition` | replica of `use-combobox-transition.ts` lines 47–71 | before first step; at boundary (progress=0); mid-window eased (non-linear); past window; speed contract |
+| `comboboxConfig.controls` | `config.ts` | state/query/revealCount/selectedIndex/highlightedIndex/mode types, defaults, options |
+| `comboboxConfig.snippet` | `config.ts` | import line; structural invariants; default omission; non-default emission; state round-trip |
+
+## What is NOT tested
+
+**Render path** — `Combobox` calls `useRemocnTheme` (React context) and renders JSX.
+Neither the component function nor its child `SelectItemRow` / `LayoutPlaceholder` trees
+are exercised here. Frame-reading belongs to `useComboboxTransition`, which is mirrored
+rather than called directly.
+
+**`comboboxStyleContext`** — The context derivation delegates internally to
+`inputStyleContext` and `selectItemStyleContext`. Those functions are covered by
+`input/__tests__` and `select/__tests__` respectively. Here `comboboxStyleContext` is
+called only to build the shared `ctx` fixture used by `comboboxStyle` and the resolver
+replica.
+
+## Filter contract
+
+`filterComboboxItems` performs a **case-insensitive substring match** on the
+**visible query prefix** (`query.slice(0, revealCount)`, or the whole query when
+`revealCount` is omitted). An empty visible prefix (including after `.trim()`) returns
+all items unchanged.
+
+This is intentionally parallel to `filterCommandItems` in the command-menu — the
+difference is item shape: combobox items are plain `string[]`, so the match is on the
+string itself rather than `.label`.
+
+## Animation model — combobox is a standard state atom
+
+`comboboxStyle` returns three numeric fields that encode the panel reveal:
+
+| State | `panelOpacity` | `panelScale` | `panelTranslateY` |
+|-------|---------------|--------------|-------------------|
+| `closed` | 0 | 0.96 | -4 |
+| `opened` | 1 | 1.00 | 0 |
+
+`useComboboxTransition` folds a step list, applies `easings.out` to the linear
+`progress`, then lerps between the two endpoint presets with `tweenComboboxStyle`.
+Because `out(t) = 1-(1-t)³`, the midpoint `t=0.5` eases to `0.875` — confirmed in
+the mid-window tests: `panelOpacity` at frame 6 of a 12-frame window is `0.875`, not
+`0.5`.
+
+## Determinism grep checklist
+
+Run this on `combobox/index.tsx` — it must print nothing:
+
+```bash
+grep -nE "useState|useEffect|useCurrentFrame|onClick|onChange|addEventListener|Date\.now|Math\.random|requestAnimationFrame" \
+ registry/remocn-ui/combobox/index.tsx
+```
+
+The `Combobox` component is a pure renderer: no frame reading, no local state, no
+side effects. Frame reading lives exclusively in `useComboboxTransition`
+(`use-combobox-transition.ts`), which is not imported here.
diff --git a/registry/remocn-ui/combobox/__tests__/combobox.test.ts b/registry/remocn-ui/combobox/__tests__/combobox.test.ts
new file mode 100644
index 00000000..a7820f1c
--- /dev/null
+++ b/registry/remocn-ui/combobox/__tests__/combobox.test.ts
@@ -0,0 +1,732 @@
+/**
+ * Verification tests for the PURE / DETERMINISTIC parts of `combobox`.
+ *
+ * Scope:
+ * - registry/remocn-ui/combobox/index.tsx
+ * filterComboboxItems(items, query, revealCount) — exported pure filter
+ * comboboxStyle(state, ctx) — complete state→visual map
+ * - registry/remocn-ui/combobox/use-combobox-transition.ts
+ * tweenComboboxStyle(a, b, t) — pure lerp across all three fields
+ * DEFAULT_DURATION constant
+ * useComboboxTransition resolver — mirrored as resolveComboboxTransition
+ * with frame injected as `raw` (annotated source lines)
+ * - registry/remocn-ui/combobox/config.ts
+ * comboboxConfig.controls wiring + comboboxConfig.snippet codegen
+ *
+ * The render path (index.tsx) imports `useRemocnTheme` / `useRemocnTheme` which
+ * requires React context and cannot run headlessly — it is NOT exercised here.
+ * `comboboxStyleContext` re-delegates to `inputStyleContext` and
+ * `selectItemStyleContext`, both of which also require no React; they ARE called
+ * here for fixture construction, but their internal correctness is covered by
+ * the select/__tests__ suite.
+ *
+ * Runner: Bun's built-in test runner (TypeScript-native, no framework dep).
+ * bun test registry/remocn-ui/combobox/__tests__
+ *
+ * --------------------------------------------------------------------------
+ * IMPORT STRATEGY
+ * --------------------------------------------------------------------------
+ * Relative imports for component source; `@/lib/remocn-ui` alias for core.
+ * `useComboboxTransition` is NOT imported — it reads `useCurrentFrame()`.
+ * Its pure body is mirrored as `resolveComboboxTransition` with frame injected.
+ * --------------------------------------------------------------------------
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+ filterComboboxItems,
+ comboboxStyle,
+ comboboxStyleContext,
+ type ComboboxState,
+ type ComboboxStyle,
+} from "../index";
+import {
+ tweenComboboxStyle,
+ DEFAULT_DURATION,
+} from "../use-combobox-transition";
+import { comboboxConfig } from "../config";
+import { defaultLightTheme, defaultDarkTheme, easings } from "@/lib/remocn-ui";
+import type { Step } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Shared fixtures
+// ===========================================================================
+
+const VALID_STATES: readonly ComboboxState[] = ["opened", "closed"];
+
+const SAMPLE_ITEMS = ["Apple", "Banana", "Orange", "Grape"];
+
+/** Build a shared ctx for style assertions (no React needed — pure function). */
+const ctx = comboboxStyleContext(defaultLightTheme);
+
+/** Convenience wrapper for snippet(). */
+type SnippetValues = {
+ state?: string;
+ query?: string;
+ revealCount?: number;
+ placeholder?: string;
+ selectedIndex?: number;
+ highlightedIndex?: number;
+ mode?: string;
+};
+const snippet = (values: SnippetValues): string =>
+ comboboxConfig.snippet(values as Record<string, unknown>);
+
+// ===========================================================================
+// 1. DEFAULT_DURATION constant
+// ===========================================================================
+
+describe("DEFAULT_DURATION", () => {
+ it("is 12 frames", () => {
+ expect(DEFAULT_DURATION).toBe(12);
+ });
+});
+
+// ===========================================================================
+// 2. filterComboboxItems — exported pure filter
+// MIRROR of index.tsx lines 77-89
+// Case-insensitive substring on query.slice(0, revealCount).
+// Items are plain strings (unlike command-menu's .label entries).
+// ===========================================================================
+
+describe("filterComboboxItems: empty visible prefix → all items returned", () => {
+ it("returns all items when query is empty string", () => {
+ expect(filterComboboxItems(SAMPLE_ITEMS, "", undefined)).toHaveLength(4);
+ });
+
+ it("returns the same array contents when query is empty", () => {
+ const result = filterComboboxItems(SAMPLE_ITEMS, "", undefined);
+ expect(result).toEqual(SAMPLE_ITEMS);
+ });
+
+ it("returns all items when revealCount=0 (visible prefix is empty)", () => {
+ expect(filterComboboxItems(SAMPLE_ITEMS, "apple", 0)).toHaveLength(4);
+ });
+
+ it("returns all items when query is whitespace only (trim collapses to empty)", () => {
+ expect(filterComboboxItems(SAMPLE_ITEMS, " ", undefined)).toHaveLength(4);
+ });
+
+ it("returns empty array when items list is empty", () => {
+ expect(filterComboboxItems([], "apple", undefined)).toHaveLength(0);
+ });
+});
+
+describe("filterComboboxItems: prefix narrows results", () => {
+ it("'Apple' matches exactly one item", () => {
+ const result = filterComboboxItems(SAMPLE_ITEMS, "Apple", undefined);
+ expect(result).toHaveLength(1);
+ expect(result[0]).toBe("Apple");
+ });
+
+ it("'an' matches Banana and Orange (substring in both)", () => {
+ const result = filterComboboxItems(SAMPLE_ITEMS, "an", undefined);
+ expect(result).toHaveLength(2);
+ expect(result).toContain("Banana");
+ expect(result).toContain("Orange");
+ });
+
+ it("'gra' matches Grape", () => {
+ const result = filterComboboxItems(SAMPLE_ITEMS, "gra", undefined);
+ expect(result).toHaveLength(1);
+ expect(result[0]).toBe("Grape");
+ });
+
+ it("'a' matches Apple, Banana, Orange, Grape (all contain 'a')", () => {
+ // Apple(a), Banana(a), Orange(a), Grape(a)
+ const result = filterComboboxItems(SAMPLE_ITEMS, "a", undefined);
+ expect(result).toHaveLength(4);
+ });
+});
+
+describe("filterComboboxItems: no-match → empty array", () => {
+ it("returns empty array when query matches nothing", () => {
+ expect(filterComboboxItems(SAMPLE_ITEMS, "xyz", undefined)).toHaveLength(0);
+ });
+
+ it("returns empty array for a long non-matching query", () => {
+ expect(filterComboboxItems(SAMPLE_ITEMS, "zzzzzzzz", undefined)).toHaveLength(0);
+ });
+});
+
+describe("filterComboboxItems: case-insensitivity", () => {
+ it("uppercase query matches lowercase item chars", () => {
+ expect(filterComboboxItems(SAMPLE_ITEMS, "APPLE", undefined)).toHaveLength(1);
+ expect(filterComboboxItems(SAMPLE_ITEMS, "APPLE", undefined)[0]).toBe("Apple");
+ });
+
+ it("mixed case query matches item", () => {
+ expect(filterComboboxItems(SAMPLE_ITEMS, "gRaPe", undefined)).toHaveLength(1);
+ });
+
+ it("lowercase query matches mixed-case item ('orange')", () => {
+ const result = filterComboboxItems(SAMPLE_ITEMS, "orange", undefined);
+ expect(result).toHaveLength(1);
+ expect(result[0]).toBe("Orange");
+ });
+});
+
+describe("filterComboboxItems: revealCount slices the query", () => {
+ it("revealCount=2 on 'apple' uses only 'ap' → matches Apple", () => {
+ const result = filterComboboxItems(SAMPLE_ITEMS, "apple", 2);
+ expect(result).toHaveLength(1);
+ expect(result[0]).toBe("Apple");
+ });
+
+ it("revealCount=1 on 'banana' uses only 'b' → matches Banana", () => {
+ const result = filterComboboxItems(SAMPLE_ITEMS, "banana", 1);
+ expect(result).toHaveLength(1);
+ expect(result[0]).toBe("Banana");
+ });
+
+ it("revealCount=2 on 'orange' uses only 'or' → matches Orange", () => {
+ const result = filterComboboxItems(SAMPLE_ITEMS, "orange", 2);
+ expect(result).toHaveLength(1);
+ expect(result[0]).toBe("Orange");
+ });
+
+ it("revealCount > query length uses full query (no index error)", () => {
+ // query='ap' (2 chars), revealCount=100 → uses full 'ap'
+ const result = filterComboboxItems(SAMPLE_ITEMS, "ap", 100);
+ expect(result).toHaveLength(1);
+ expect(result[0]).toBe("Apple");
+ });
+});
+
+describe("filterComboboxItems: result preserves original string references", () => {
+ it("filtered items are the same string references (no cloning)", () => {
+ const result = filterComboboxItems(SAMPLE_ITEMS, "apple", undefined);
+ // strings are primitives — identity check via toBe confirms no mutation
+ expect(result[0]).toBe(SAMPLE_ITEMS[0]);
+ });
+});
+
+// ===========================================================================
+// 3. comboboxStyle — pure (state, ctx) => ComboboxStyle presets
+// MIRROR of index.tsx lines 138-148
+// Every field is asserted for both states.
+// ===========================================================================
+
+describe("comboboxStyle: closed state — off-screen keyframe", () => {
+ const s = comboboxStyle("closed", ctx);
+
+ 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 -4 (lifted 4px above rest position)", () => {
+ expect(s.panelTranslateY).toBe(-4);
+ });
+});
+
+describe("comboboxStyle: opened state — resting keyframe", () => {
+ const s = comboboxStyle("opened", ctx);
+
+ 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("comboboxStyle: closed and opened have distinct values on every field", () => {
+ const closed = comboboxStyle("closed", ctx);
+ const opened = comboboxStyle("opened", ctx);
+
+ 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: -4 vs 0", () => {
+ expect(closed.panelTranslateY).not.toBe(opened.panelTranslateY);
+ });
+});
+
+describe("comboboxStyle: every state produces a complete ComboboxStyle", () => {
+ it("all three fields are numeric for every state", () => {
+ for (const state of VALID_STATES) {
+ const s = comboboxStyle(state, ctx);
+ expect(typeof s.panelOpacity).toBe("number");
+ expect(typeof s.panelScale).toBe("number");
+ expect(typeof s.panelTranslateY).toBe("number");
+ }
+ });
+});
+
+// ===========================================================================
+// 4. tweenComboboxStyle — pure lerp across all three numeric fields
+// MIRROR of use-combobox-transition.ts lines 22-33
+// All fields are numbers — straight lerp on everything.
+// ===========================================================================
+
+describe("tweenComboboxStyle: t=0 returns values equal to `a`", () => {
+ const a = comboboxStyle("closed", ctx);
+ const b = comboboxStyle("opened", ctx);
+ const r = tweenComboboxStyle(a, b, 0);
+
+ 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("tweenComboboxStyle: t=1 returns values equal to `b`", () => {
+ const a = comboboxStyle("closed", ctx);
+ const b = comboboxStyle("opened", ctx);
+ const r = tweenComboboxStyle(a, b, 1);
+
+ 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("tweenComboboxStyle: t=0.5 midpoint (closed → opened)", () => {
+ // closed: panelOpacity=0, panelScale=0.96, panelTranslateY=-4
+ // opened: panelOpacity=1, panelScale=1, panelTranslateY=0
+ // midpoint: 0.5, 0.98, -2
+ const a = comboboxStyle("closed", ctx);
+ const b = comboboxStyle("opened", ctx);
+ const r = tweenComboboxStyle(a, b, 0.5);
+
+ 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: -4 → 0 gives -2", () => {
+ expect(r.panelTranslateY).toBeCloseTo(-2, 10);
+ });
+});
+
+describe("tweenComboboxStyle: t=0.25 quarter-point (closed → opened)", () => {
+ // panelOpacity: 0.25, panelScale: 0.97, panelTranslateY: -3
+ const a = comboboxStyle("closed", ctx);
+ const b = comboboxStyle("opened", ctx);
+ const r = tweenComboboxStyle(a, b, 0.25);
+
+ 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 -3", () => {
+ expect(r.panelTranslateY).toBeCloseTo(-3, 10);
+ });
+});
+
+describe("tweenComboboxStyle: identity (a === b)", () => {
+ const s = comboboxStyle("opened", ctx);
+
+ it("all fields unchanged when both endpoints are identical", () => {
+ const r = tweenComboboxStyle(s, s, 0.5);
+ expect(r.panelOpacity).toBeCloseTo(s.panelOpacity, 10);
+ expect(r.panelScale).toBeCloseTo(s.panelScale, 10);
+ expect(r.panelTranslateY).toBeCloseTo(s.panelTranslateY, 10);
+ });
+});
+
+describe("tweenComboboxStyle: reverse direction (opened → closed)", () => {
+ const a = comboboxStyle("opened", ctx);
+ const b = comboboxStyle("closed", ctx);
+ const r = tweenComboboxStyle(a, b, 0.5);
+
+ it("panelOpacity midpoint: 1 → 0 gives 0.5", () => {
+ expect(r.panelOpacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("panelTranslateY midpoint: 0 → -4 gives -2", () => {
+ expect(r.panelTranslateY).toBeCloseTo(-2, 10);
+ });
+});
+
+// ===========================================================================
+// 5. useComboboxTransition resolver replica
+// MIRRORS use-combobox-transition.ts lines 47-71.
+// `useComboboxTransition` calls `useStateTransition` (reads useCurrentFrame())
+// then applies `easings.out(progress)` and `tweenComboboxStyle`.
+// We inject `raw` in place of useCurrentFrame().
+//
+// The key additional contract: progress is eased with `easings.out` before
+// the tween, making the result non-linear (confirmed: out(0.5) = 0.875).
+//
+// MAINTENANCE CONTRACT: if use-combobox-transition.ts lines 47-71 change,
+// update this replica in lockstep. Annotated source lines below.
+// ===========================================================================
+
+/** MIRROR of core/timeline.ts:clamp01. */
+function clamp01(t: number): number {
+ return Math.max(0, Math.min(1, t));
+}
+
+/**
+ * MIRROR of timeline.ts:useStateTransition pure resolver body.
+ * `raw` is injected in place of useCurrentFrame().
+ */
+function resolveStateTransition<S extends string>(
+ raw: number,
+ steps: Step<S>[],
+ defaultState: S,
+ speed = 1,
+ defaultDuration = 8,
+): { from: S; to: S; progress: number } {
+ const effectiveFrame = raw * speed;
+ const started = steps
+ .map((step, index) => ({ step, index }))
+ .sort((a, b) => a.step.at - b.step.at || a.index - b.index)
+ .filter((e) => e.step.at <= effectiveFrame);
+ if (started.length === 0)
+ return { from: defaultState, to: defaultState, progress: 1 };
+ const to = started[started.length - 1].step;
+ const from = started.length >= 2 ? started[started.length - 2].step : null;
+ const dur = to.duration ?? defaultDuration;
+ const progress = dur > 0 ? clamp01((effectiveFrame - to.at) / dur) : 1;
+ return { from: from ? from.state : defaultState, to: to.state, progress };
+}
+
+/**
+ * MIRROR of use-combobox-transition.ts:useComboboxTransition (lines 47-71).
+ * `raw` is injected in place of useCurrentFrame().
+ * Annotated source lines:
+ * line 54: destructure speed + defaultDuration from opts
+ * lines 59-64: useStateTransition (mirrored as resolveStateTransition)
+ * line 65: t = easings.out(progress) ← MIRROR line 65
+ * lines 66-70: tweenComboboxStyle(from, to, t) ← MIRROR lines 66-70
+ */
+function resolveComboboxTransition(
+ raw: number, // injected useCurrentFrame() — MIRROR line 59
+ steps: Step<ComboboxState>[],
+ speed = 1,
+ defaultDuration = DEFAULT_DURATION,
+): ComboboxStyle & { from: ComboboxState; to: ComboboxState; progress: number } {
+ const { from, to, progress } = resolveStateTransition( // MIRROR lines 59-64
+ raw,
+ steps,
+ "closed",
+ speed,
+ defaultDuration,
+ );
+ const t = easings.out(progress); // MIRROR line 65
+ const style = tweenComboboxStyle( // MIRROR lines 66-70
+ comboboxStyle(from as ComboboxState, ctx),
+ comboboxStyle(to as ComboboxState, ctx),
+ t,
+ );
+ return { ...style, from: from as ComboboxState, to: to as ComboboxState, progress };
+}
+
+// ---------------------------------------------------------------------------
+// Before any step: holds at closed (progress=1, tween(closed,closed,out(1)))
+// ---------------------------------------------------------------------------
+
+describe("resolveComboboxTransition: before any step — holds at closed", () => {
+ it("returns the closed style when no steps have started", () => {
+ const r = resolveComboboxTransition(0, []);
+ const closed = comboboxStyle("closed", ctx);
+ 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 } = resolveComboboxTransition(0, []);
+ expect(from).toBe("closed");
+ expect(to).toBe("closed");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Exactly at a step boundary: progress=0, t=out(0)=0 → closed style
+// ---------------------------------------------------------------------------
+
+describe("resolveComboboxTransition: exactly at closed→opened step boundary", () => {
+ const steps: Step<ComboboxState>[] = [{ at: 10, state: "opened" }];
+
+ it("at raw=10, progress=0, t=out(0)=0 → style equals closed (from)", () => {
+ const r = resolveComboboxTransition(10, steps);
+ const closed = comboboxStyle("closed", ctx);
+ expect(r.progress).toBe(0);
+ expect(r.panelOpacity).toBeCloseTo(closed.panelOpacity, 10);
+ expect(r.panelScale).toBeCloseTo(closed.panelScale, 10);
+ });
+
+ it("from='closed', to='opened' at the step boundary", () => {
+ const { from, to } = resolveComboboxTransition(10, steps);
+ expect(from).toBe("closed");
+ expect(to).toBe("opened");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Mid-window: easings.out applied — non-linear (not raw 0.5)
+// out(0.5) = 1-(1-0.5)^3 = 1-0.125 = 0.875
+// ---------------------------------------------------------------------------
+
+describe("resolveComboboxTransition: mid-window uses easings.out (not linear)", () => {
+ // step at=0, defaultDuration=12. At raw=6: linear progress=0.5, out(0.5)=0.875
+ const steps: Step<ComboboxState>[] = [{ at: 0, state: "opened" }];
+
+ it("panelOpacity at raw=6 is out(0.5)=0.875 (not linear 0.5)", () => {
+ const r = resolveComboboxTransition(6, steps, 1, 12);
+ const t = easings.out(0.5); // 0.875
+ // tween(0, 1, 0.875) = 0.875
+ expect(r.panelOpacity).toBeCloseTo(t, 8);
+ });
+
+ it("panelScale at raw=6 is 0.96 + 0.04*out(0.5) = 0.995", () => {
+ const r = resolveComboboxTransition(6, steps, 1, 12);
+ const t = easings.out(0.5); // 0.875
+ const expected = 0.96 + (1 - 0.96) * t; // 0.995
+ expect(r.panelScale).toBeCloseTo(expected, 8);
+ });
+
+ it("panelTranslateY at raw=6 is -4*(1-out(0.5)) = -0.5", () => {
+ const r = resolveComboboxTransition(6, steps, 1, 12);
+ const t = easings.out(0.5); // 0.875
+ const expected = -4 + (0 - (-4)) * t; // -4 + 4*0.875 = -0.5
+ expect(r.panelTranslateY).toBeCloseTo(expected, 8);
+ });
+
+ it("easing is confirmed non-linear: panelOpacity at raw=6 is not 0.5", () => {
+ const r = resolveComboboxTransition(6, steps, 1, 12);
+ expect(r.panelOpacity).not.toBeCloseTo(0.5, 2);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Past the window: fully opened
+// ---------------------------------------------------------------------------
+
+describe("resolveComboboxTransition: past the window → fully opened", () => {
+ const steps: Step<ComboboxState>[] = [{ at: 0, state: "opened" }];
+
+ it("panelOpacity is 1 after DEFAULT_DURATION frames", () => {
+ expect(resolveComboboxTransition(DEFAULT_DURATION, steps).panelOpacity).toBeCloseTo(1, 10);
+ });
+
+ it("panelScale is 1 after DEFAULT_DURATION frames", () => {
+ expect(resolveComboboxTransition(DEFAULT_DURATION, steps).panelScale).toBeCloseTo(1, 10);
+ });
+
+ it("panelTranslateY is 0 after DEFAULT_DURATION frames", () => {
+ expect(resolveComboboxTransition(DEFAULT_DURATION, steps).panelTranslateY).toBeCloseTo(0, 10);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Speed contract
+// ---------------------------------------------------------------------------
+
+describe("resolveComboboxTransition: speed contract", () => {
+ const steps: Step<ComboboxState>[] = [{ at: 12, state: "opened" }];
+
+ it("speed=2: step at=12 fires at raw=6 (effectiveFrame=12)", () => {
+ expect(resolveComboboxTransition(6, steps, 2).to).toBe("opened");
+ });
+
+ it("speed=2: step at=12 has NOT fired at raw=5 (effectiveFrame=10 < 12)", () => {
+ expect(resolveComboboxTransition(5, steps, 2).to).toBe("closed");
+ });
+});
+
+// ===========================================================================
+// 6. comboboxConfig.controls — customizer control wiring
+// ===========================================================================
+
+describe("comboboxConfig.controls: state", () => {
+ it("state is a select control", () => {
+ expect(comboboxConfig.controls.state.type).toBe("select");
+ });
+
+ it("state options are ['opened','closed']", () => {
+ const ctrl = comboboxConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["opened", "closed"]);
+ });
+
+ it("state default is 'opened' (panel visible in preview)", () => {
+ expect(comboboxConfig.controls.state.default).toBe("opened");
+ });
+
+ it("every state option is a valid ComboboxState", () => {
+ const ctrl = comboboxConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const opt of ctrl.options) {
+ expect(VALID_STATES).toContain(opt as ComboboxState);
+ }
+ });
+});
+
+describe("comboboxConfig.controls: query", () => {
+ it("query is a text control", () => {
+ expect(comboboxConfig.controls.query.type).toBe("text");
+ });
+
+ it("query default is empty string", () => {
+ expect(comboboxConfig.controls.query.default).toBe("");
+ });
+});
+
+describe("comboboxConfig.controls: revealCount", () => {
+ it("revealCount is a number control", () => {
+ expect(comboboxConfig.controls.revealCount.type).toBe("number");
+ });
+
+ it("revealCount default is 0", () => {
+ expect(comboboxConfig.controls.revealCount.default).toBe(0);
+ });
+
+ it("revealCount min is 0", () => {
+ const ctrl = comboboxConfig.controls.revealCount;
+ if (ctrl.type !== "number") throw new Error("expected number");
+ expect(ctrl.min).toBe(0);
+ });
+});
+
+describe("comboboxConfig.controls: selectedIndex and highlightedIndex", () => {
+ it("selectedIndex is a number control with default -1", () => {
+ expect(comboboxConfig.controls.selectedIndex.type).toBe("number");
+ expect(comboboxConfig.controls.selectedIndex.default).toBe(-1);
+ });
+
+ it("highlightedIndex is a number control with default 0 (first row pre-highlighted)", () => {
+ expect(comboboxConfig.controls.highlightedIndex.type).toBe("number");
+ expect(comboboxConfig.controls.highlightedIndex.default).toBe(0);
+ });
+});
+
+describe("comboboxConfig.controls: mode", () => {
+ it("mode is a select control", () => {
+ expect(comboboxConfig.controls.mode.type).toBe("select");
+ });
+
+ it("mode default is 'light'", () => {
+ expect(comboboxConfig.controls.mode.default).toBe("light");
+ });
+});
+
+// ===========================================================================
+// 7. comboboxConfig.snippet — pure JSX string builder
+// ===========================================================================
+
+describe("comboboxConfig.snippet: import line", () => {
+ it("includes 'import { Combobox }' from the correct path", () => {
+ const out = snippet({ state: "opened" });
+ expect(out).toContain("import { Combobox }");
+ expect(out).toContain('from "@/components/remocn/combobox"');
+ });
+});
+
+describe("comboboxConfig.snippet: structural invariants", () => {
+ it("contains a <Combobox JSX element", () => {
+ expect(snippet({ state: "opened" })).toContain("<Combobox");
+ });
+
+ 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("comboboxConfig.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 placeholder when it equals the default value", () => {
+ expect(
+ snippet({ state: "opened", placeholder: "Select a fruit…" })
+ ).not.toContain("placeholder=");
+ });
+
+ 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)", () => {
+ 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("comboboxConfig.snippet: non-default props are emitted", () => {
+ it("emits query when non-empty", () => {
+ expect(snippet({ state: "opened", query: "apple" })).toContain('query="apple"');
+ });
+
+ it("emits revealCount when non-zero", () => {
+ expect(snippet({ state: "opened", revealCount: 3 })).toContain("revealCount={3}");
+ });
+
+ it("emits placeholder when non-default", () => {
+ expect(snippet({ state: "opened", placeholder: "Search…" })).toContain('placeholder="Search…"');
+ });
+
+ it("emits selectedIndex when not -1", () => {
+ expect(snippet({ state: "opened", selectedIndex: 1 })).toContain("selectedIndex={1}");
+ });
+
+ it("emits highlightedIndex when not -1 (e.g. 0 means first row)", () => {
+ 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("comboboxConfig.snippet: state options round-trip", () => {
+ it("emits the correct state for every control option", () => {
+ const ctrl = comboboxConfig.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/combobox/config.ts b/registry/remocn-ui/combobox/config.ts
new file mode 100644
index 00000000..43cc8a86
--- /dev/null
+++ b/registry/remocn-ui/combobox/config.ts
@@ -0,0 +1,88 @@
+import { type ComponentConfig, FPS, H, W } from "@/lib/customizer-config";
+import type { ComboboxState } from "@/registry/remocn-ui/combobox";
+
+const DEFAULT_QUERY = "";
+const DEFAULT_PLACEHOLDER = "Select a fruit…";
+
+export const comboboxConfig: ComponentConfig = {
+ componentName: "Combobox",
+ importPath: "@/components/remocn/combobox",
+ controls: {
+ state: {
+ type: "select",
+ // Default to `opened` so the preview shows the revealed panel.
+ 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",
+ },
+ placeholder: {
+ type: "text",
+ default: DEFAULT_PLACEHOLDER,
+ label: "Placeholder",
+ },
+ 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 ComboboxState) ?? "opened";
+ const query = values.query as string | undefined;
+ const revealCount = values.revealCount as number | undefined;
+ const placeholder = values.placeholder as string | 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 (placeholder !== undefined && placeholder !== DEFAULT_PLACEHOLDER)
+ props.push(` placeholder="${placeholder}"`);
+ 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 { Combobox } from "@/components/remocn/combobox";
+
+<Combobox
+${props.join("\n")}
+/>`;
+ },
+};
diff --git a/registry/remocn-ui/combobox/index.tsx b/registry/remocn-ui/combobox/index.tsx
new file mode 100644
index 00000000..7fb4e066
--- /dev/null
+++ b/registry/remocn-ui/combobox/index.tsx
@@ -0,0 +1,332 @@
+"use client";
+
+import { type RemocnTheme, useRemocnTheme } from "@/lib/remocn-ui";
+import {
+ inputStyle,
+ inputStyleContext,
+ type InputStyle,
+ type InputStyleContext,
+} from "@/components/remocn/input";
+import {
+ SelectItemRow,
+ selectItemStyle,
+ selectItemStyleContext,
+ type SelectItemState,
+ type SelectItemStyle,
+ type SelectItemStyleContext,
+} from "@/components/remocn/select-item";
+
+export type ComboboxState = "opened" | "closed";
+
+export interface ComboboxProps {
+ /** Current visual state (snap path). State changes snap (no enter-tweens). */
+ state?: ComboboxState;
+ /**
+ * Resolved animated visual (smooth path). When provided, takes precedence over
+ * `state` — feed it an interpolated `ComboboxStyle` from `useComboboxTransition`.
+ */
+ style?: ComboboxStyle;
+ /** Full typed query (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;
+ /** Trigger placeholder shown before any query is typed. */
+ placeholder?: string;
+ /** The full option list (before filtering). */
+ items?: string[];
+ /** 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 present it wins over the index→state derivation.
+ */
+ itemStyles?: (SelectItemStyle | undefined)[];
+ /**
+ * Resolved Input visual for the trigger (smooth path). Drive it with
+ * `useInputTransition` for focus-ring + typed-text reveal. Defaults to the
+ * resting `idle` look (or `typing` once a query is revealed).
+ */
+ inputStyle?: InputStyle;
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ className?: string;
+}
+
+/** Trigger width = panel width (px). */
+const WIDTH = 280;
+
+/**
+ * Filter option strings 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.
+ *
+ * NOTE: this is intentionally the SAME logic as command-menu's
+ * `filterCommandItems` (deliberate duplication — the core is frozen, so the two
+ * filters are kept textually parallel rather than extracted). The only
+ * difference is the item shape: here `items` are plain strings, so the match is
+ * on the string itself rather than an entry `.label`.
+ */
+export function filterComboboxItems(
+ items: string[],
+ query: string,
+ revealCount?: number,
+): string[] {
+ const visible = (
+ revealCount === undefined ? query : query.slice(0, revealCount)
+ )
+ .trim()
+ .toLowerCase();
+ if (visible === "") return items;
+ return items.filter((item) => item.toLowerCase().includes(visible));
+}
+
+// ===========================================================================
+// Combobox visual — the COMPLETE animated look for a moment in time. A `state`
+// is a named preset of this visual (`comboboxStyle`); the smooth path feeds an
+// interpolated `ComboboxStyle` straight through. The component is a pure renderer
+// of whichever `ComboboxStyle` it receives. The trigger reuses the Input
+// presets and the panel rows reuse SelectItemRow — neither markup is duplicated.
+// ===========================================================================
+
+export interface ComboboxStyle {
+ /** Panel fade 0 (closed) → 1 (opened). */
+ panelOpacity: number;
+ /** Panel zoom 0.96 (closed) → 1 (opened). */
+ panelScale: number;
+ /** Panel lift -4 (closed) → 0 (opened) px. */
+ panelTranslateY: number;
+}
+
+/** Concrete colors for the active theme, resolved once per render. */
+export interface ComboboxStyleContext {
+ /** Input presets — reused so the trigger IS the Input look. */
+ triggerCtx: InputStyleContext;
+ panelBg: string;
+ panelBorder: string;
+ mutedFg: string;
+ radius: number;
+ itemCtx: SelectItemStyleContext;
+}
+
+/**
+ * Derive the concrete colors for a theme. Pure — call it once and reuse the
+ * result for every `comboboxStyle(state, ctx)` preset.
+ */
+export function comboboxStyleContext(theme: RemocnTheme): ComboboxStyleContext {
+ return {
+ triggerCtx: inputStyleContext(theme),
+ panelBg: theme.popover,
+ panelBorder: theme.border,
+ mutedFg: theme.mutedForeground,
+ radius: theme.radius,
+ itemCtx: selectItemStyleContext(theme),
+ };
+}
+
+/**
+ * The COMPLETE resting visual for a state — a pure `(state, ctx) =>
+ * ComboboxStyle` map. To change how a state looks, edit one entry.
+ */
+export function comboboxStyle(
+ state: ComboboxState,
+ _ctx: ComboboxStyleContext,
+): ComboboxStyle {
+ switch (state) {
+ case "opened":
+ return { panelOpacity: 1, panelScale: 1, panelTranslateY: 0 };
+ default:
+ return { panelOpacity: 0, panelScale: 0.96, panelTranslateY: -4 };
+ }
+}
+
+/** Resolve one row's state from the index props (used when no itemStyle override). */
+function rowState(
+ i: number,
+ selectedIndex: number,
+ highlightedIndex: number,
+ pressedIndex: number,
+): SelectItemState {
+ if (i === pressedIndex) return "press";
+ if (i === selectedIndex) return "selected";
+ if (i === highlightedIndex) return "hover";
+ return "idle";
+}
+
+export function Combobox({
+ state = "closed",
+ style,
+ query = "",
+ revealCount,
+ placeholder = "Select a fruit…",
+ items = ["Apple", "Banana", "Orange", "Grape"],
+ selectedIndex = -1,
+ highlightedIndex = -1,
+ pressedIndex = -1,
+ itemStyles,
+ inputStyle: inputStyleOverride,
+ theme: themeOverride,
+ mode,
+ className,
+}: ComboboxProps) {
+ const theme = useRemocnTheme(themeOverride, mode);
+ const ctx = comboboxStyleContext(theme);
+ const v = style ?? comboboxStyle(state, ctx);
+
+ const visibleQuery =
+ revealCount === undefined ? query : query.slice(0, revealCount);
+ const filtered = filterComboboxItems(items, query, revealCount);
+
+ // The trigger reuses the Input visual. Input itself is a full-frame scene
+ // (absolute inset:0) and can't nest inline, so — like Select reuses the Button
+ // presets for its trigger — the trigger is rendered inline from the Input
+ // presets. Defaults to `typing` once a query is revealed, else `idle`; the
+ // caller can pass a tweened `inputStyle` (from useInputTransition) instead.
+ const trigger: InputStyle =
+ inputStyleOverride ??
+ inputStyle(visibleQuery ? "typing" : "idle", ctx.triggerCtx);
+
+ // The reveal width tracks the visible query length so the caret sits at its
+ // end (headless render can't measure text; ~8px per char is a good monospace-
+ // ish estimate for the trigger value).
+ const valueWidth = visibleQuery.length * 8;
+
+ return (
+ <div
+ className={className}
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ // OPAQUE wrapper — a combobox is a self-contained widget, not a modal
+ // layer (mirrors Select).
+ background: theme.background,
+ fontFamily:
+ "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif",
+ }}
+ >
+ <div style={{ position: "relative", width: WIDTH }}>
+ {/* Trigger — the Input look, rendered inline. */}
+ <div
+ style={{
+ position: "relative",
+ display: "flex",
+ alignItems: "center",
+ width: WIDTH,
+ boxSizing: "border-box",
+ height: 40,
+ padding: "0 14px",
+ fontSize: 15,
+ letterSpacing: "-0.01em",
+ background: trigger.background,
+ border: `1px solid ${trigger.borderColor}`,
+ borderRadius: theme.radius,
+ boxShadow: `0 0 0 ${trigger.ringWidth}px ${trigger.ringColor}`,
+ }}
+ >
+ {/* Placeholder — hidden the instant the value starts revealing. */}
+ <span
+ style={{
+ position: "absolute",
+ left: 14,
+ color: ctx.triggerCtx.mutedForeground,
+ opacity: trigger.valueReveal > 0 ? 0 : trigger.placeholderOpacity,
+ pointerEvents: "none",
+ whiteSpace: "nowrap",
+ }}
+ >
+ {placeholder}
+ </span>
+ {/* Value + caret — the typed query. */}
+ <div style={{ display: "flex", alignItems: "center", minWidth: 0 }}>
+ <span
+ style={{
+ display: "inline-block",
+ width: valueWidth * trigger.valueReveal,
+ overflow: "hidden",
+ whiteSpace: "nowrap",
+ color: ctx.triggerCtx.foreground,
+ }}
+ >
+ {visibleQuery}
+ </span>
+ <span
+ style={{
+ flexShrink: 0,
+ width: 2,
+ height: 17,
+ borderRadius: 1,
+ background: ctx.triggerCtx.foreground,
+ opacity: trigger.caretOpacity,
+ }}
+ />
+ </div>
+ </div>
+ {/* Panel — opacity/scale/lift animate the reveal below the trigger. */}
+ <div
+ style={{
+ position: "absolute",
+ top: "calc(100% + 6px)",
+ left: 0,
+ width: 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,
+ padding: 4,
+ display: "flex",
+ flexDirection: "column",
+ gap: 2,
+ boxShadow: "0 16px 32px -12px rgba(0,0,0,0.25)",
+ }}
+ >
+ {filtered.length === 0 ? (
+ <div
+ style={{
+ padding: "12px",
+ textAlign: "center",
+ fontSize: 14,
+ color: ctx.mutedFg,
+ }}
+ >
+ No results found.
+ </div>
+ ) : (
+ filtered.map((item, i) => {
+ const override = itemStyles?.[i];
+ return (
+ <SelectItemRow
+ key={item}
+ style={
+ override ??
+ selectItemStyle(
+ rowState(i, selectedIndex, highlightedIndex, pressedIndex),
+ ctx.itemCtx,
+ )
+ }
+ ctx={ctx.itemCtx}
+ label={item}
+ width={WIDTH - 8}
+ radius={theme.radius}
+ check={ctx.itemCtx.check}
+ />
+ );
+ })
+ )}
+ </div>
+ </div>
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/combobox/use-combobox-transition.ts b/registry/remocn-ui/combobox/use-combobox-transition.ts
new file mode 100644
index 00000000..40193ad1
--- /dev/null
+++ b/registry/remocn-ui/combobox/use-combobox-transition.ts
@@ -0,0 +1,71 @@
+"use client";
+
+import {
+ easings,
+ type RemocnTheme,
+ type Step,
+ useRemocnTheme,
+ useStateTransition,
+} from "@/lib/remocn-ui";
+import {
+ comboboxStyle,
+ comboboxStyleContext,
+ type ComboboxState,
+ type ComboboxStyle,
+} from "@/components/remocn/combobox";
+// ^ 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 combobox visuals: all fields are numbers, so a straight lerp. */
+export function tweenComboboxStyle(
+ a: ComboboxStyle,
+ b: ComboboxStyle,
+ t: number,
+): ComboboxStyle {
+ return {
+ 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 ComboboxTransitionOptions {
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ speed?: number;
+ defaultDuration?: number;
+}
+
+/**
+ * Timeline → resolved (eased, tweened) ComboboxStyle. The CALLER invokes this;
+ * it reads the frame, the `<Combobox>` component does not. Feed the result to
+ * `<Combobox style={...} />` for a smooth open/close.
+ */
+export function useComboboxTransition(
+ steps: Step<ComboboxState>[],
+ opts: ComboboxTransitionOptions = {},
+): ComboboxStyle {
+ const {
+ theme: themeOverride,
+ mode,
+ speed = 1,
+ defaultDuration = DEFAULT_DURATION,
+ } = opts;
+ const theme = useRemocnTheme(themeOverride, mode);
+ const ctx = comboboxStyleContext(theme);
+ const { from, to, progress } = useStateTransition(
+ steps,
+ "closed",
+ speed,
+ defaultDuration,
+ );
+ const t = easings.out(progress);
+ return tweenComboboxStyle(
+ comboboxStyle(from, ctx),
+ comboboxStyle(to, ctx),
+ t,
+ );
+}
diff --git a/registry/remocn-ui/registry.json b/registry/remocn-ui/registry.json
index 0ffe958e..e76fd30b 100644
--- a/registry/remocn-ui/registry.json
+++ b/registry/remocn-ui/registry.json
@@ -531,6 +531,26 @@
"target": "components/remocn/use-slider-transition.ts"
}
]
+ },
+ {
+ "name": "combobox",
+ "type": "registry:component",
+ "title": "UI Combobox",
+ "description": "A combobox whose opened/closed state is a pure function of the timeline; the panel fade/scale/lift are keyframed presets like select. The trigger reuses the Input presets (typed query + caret reveal via an injected inputStyle), the list is filtered by a pure case-insensitive substring on the visible query prefix, and rows reuse the SelectItem row.",
+ "dependencies": ["remotion"],
+ "registryDependencies": ["remocn-ui", "input", "select-item"],
+ "files": [
+ {
+ "path": "combobox/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/combobox.tsx"
+ },
+ {
+ "path": "combobox/use-combobox-transition.ts",
+ "type": "registry:component",
+ "target": "components/remocn/use-combobox-transition.ts"
+ }
+ ]
}
]
}