Skip to content

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

feat: added tooltip component

dev_wandry4e0bbb2da3bb
diff --git a/components/docs/examples/index.tsx b/components/docs/examples/index.tsx
index 809eb246..b5871b74 100644
--- a/components/docs/examples/index.tsx
+++ b/components/docs/examples/index.tsx
@@ -31,6 +31,7 @@ import {
CommandMenuExampleScene,
commandMenuExampleCode,
} from "./command-menu-example";
+import { TooltipExampleScene, tooltipExampleCode } from "./tooltip-example";
export interface ExampleEntry {
Component: ComponentType;
@@ -181,4 +182,13 @@ export const examples: Record<string, ExampleEntry> = {
width: W,
height: H,
},
+ "tooltip-example": {
+ Component: TooltipExampleScene,
+ code: tooltipExampleCode,
+ // Tooltip hides at 100 + dur 8 = 108; cursor parks at 110; a short settle then loop.
+ durationInFrames: 120,
+ fps: FPS,
+ width: W,
+ height: H,
+ },
};
diff --git a/components/docs/examples/tooltip-example.tsx b/components/docs/examples/tooltip-example.tsx
new file mode 100644
index 00000000..c54cd943
--- /dev/null
+++ b/components/docs/examples/tooltip-example.tsx
@@ -0,0 +1,135 @@
+"use client";
+
+import { Cursor } from "@/registry/remocn-ui/cursor";
+import { useCursorPath } from "@/registry/remocn-ui/cursor/use-cursor-path";
+import { Button } from "@/registry/remocn-ui/button";
+import { useButtonTransition } from "@/registry/remocn-ui/button/use-button-transition";
+import { Tooltip } from "@/registry/remocn-ui/tooltip";
+import { useTooltipTransition } from "@/registry/remocn-ui/tooltip/use-tooltip-transition";
+
+// Cursor tip lands at the button center.
+const BTN_X = 620;
+const BTN_Y = 360;
+
+// Cursor parks away from button after tooltip dismisses.
+const AWAY_X = 200;
+const AWAY_Y = 200;
+
+export const TooltipExampleScene = () => {
+ // Cursor: park top-left → ease onto button (arrives 28) → hover →
+ // move away at frame 90 (arrives 110).
+ const cursorStyle = useCursorPath([
+ { at: 0, x: 80, y: 60 },
+ { at: 28, x: BTN_X, y: BTN_Y, duration: 24 },
+ { at: 110, x: AWAY_X, y: AWAY_Y, duration: 20 },
+ ]);
+
+ // Button: idle → hover as cursor arrives, back to idle as cursor leaves.
+ const buttonStyle = useButtonTransition([
+ { at: 28, state: "hover", duration: 8 },
+ { at: 100, state: "idle", duration: 8 },
+ ]);
+
+ // Tooltip: fades in shortly after cursor arrives, fades out as cursor leaves.
+ const tooltipStyle = useTooltipTransition([
+ { at: 36, state: "visible", duration: 8 },
+ { at: 100, state: "hidden", duration: 8 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ {/* Anchor — the button is centered in the canvas. */}
+ <div
+ style={{
+ width: "100%",
+ position: "absolute",
+ left: "50%",
+ top: "50%",
+ transform: "translate(-50%, -50%)",
+ }}
+ >
+ <Button label="Hover me" style={buttonStyle} />
+
+ {/* Tooltip is anchored relative to the button: centered above it. */}
+ <div
+ style={{
+ position: "absolute",
+ bottom: "calc(100% + 32px)",
+ left: "50%",
+ transform: "translateX(-50%)",
+ }}
+ >
+ <Tooltip
+ label="Keyboard shortcut ⌘K"
+ side="top"
+ style={tooltipStyle}
+ />
+ </div>
+ </div>
+
+ <Cursor style={cursorStyle} variant="pointer" />
+ </div>
+ );
+};
+
+export const tooltipExampleCode = `import { Cursor } from "@/components/remocn/cursor";
+import { useCursorPath } from "@/components/remocn/use-cursor-path";
+import { Button } from "@/components/remocn/button";
+import { useButtonTransition } from "@/components/remocn/use-button-transition";
+import { Tooltip } from "@/components/remocn/tooltip";
+import { useTooltipTransition } from "@/components/remocn/use-tooltip-transition";
+
+const BTN_X = 320;
+const BTN_Y = 180;
+const AWAY_X = 100;
+const AWAY_Y = 100;
+
+export const Scene = () => {
+ // Cursor eases onto the button, triggers a hover + tooltip, then leaves.
+ const cursorStyle = useCursorPath([
+ { at: 0, x: 80, y: 60 },
+ { at: 28, x: BTN_X, y: BTN_Y, duration: 24 },
+ { at: 110, x: AWAY_X, y: AWAY_Y, duration: 20 },
+ ]);
+
+ // Button responds to the cursor arriving and leaving.
+ const buttonStyle = useButtonTransition([
+ { at: 28, state: "hover", duration: 8 },
+ { at: 100, state: "idle", duration: 8 },
+ ]);
+
+ // Tooltip fades in shortly after hover, then fades out as cursor leaves.
+ const tooltipStyle = useTooltipTransition([
+ { at: 36, state: "visible", duration: 8 },
+ { at: 100, state: "hidden", duration: 8 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <div
+ style={{
+ position: "absolute",
+ left: "50%",
+ top: "50%",
+ transform: "translate(-50%, -50%)",
+ }}
+ >
+ <Button label="Hover me" style={buttonStyle} />
+
+ {/* Tooltip sits above the button; the caller owns the anchor position. */}
+ <div
+ style={{
+ position: "absolute",
+ bottom: "calc(100% + 24px)",
+ left: "50%",
+ transform: "translateX(-50%)",
+ }}
+ >
+ <Tooltip label="Keyboard shortcut ⌘K" side="top" style={tooltipStyle} />
+ </div>
+ </div>
+
+ <Cursor style={cursorStyle} variant="pointer" />
+ </div>
+ );
+};`;
diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.json
index 8625d338..24550d4f 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", "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", "tooltip"]
}
diff --git a/content/docs/ui/components/tooltip.mdx b/content/docs/ui/components/tooltip.mdx
new file mode 100644
index 00000000..3e24e316
--- /dev/null
+++ b/content/docs/ui/components/tooltip.mdx
@@ -0,0 +1,183 @@
+---
+title: Tooltip
+description: A small floating label that appears above an anchor on hover
+---
+
+<ComponentPreview name="tooltip" />
+
+A state atom whose appearance (`hidden`, `visible`) is a pure function of the `state` prop. Pass a state directly or drive it from the Remotion timeline via `useCurrentState`. The component reads no frame — only the state value you give it. The tooltip fades in at 0.96 scale, slides 4 px toward the anchor, and rests fully visible; `hidden` reverses the motion. Placement is the caller's responsibility — the tooltip renders inline and the caller wraps it in an absolutely-positioned anchor div.
+
+## Installation
+
+<InstallBlock name="tooltip" />
+
+<Note>
+Installing `tooltip` automatically installs the shared `remocn-ui` core (`lib/remocn-ui/`) via `registryDependencies` (`["remocn-ui"]`). You do not need to install it separately. Both `tooltip` (the renderer) and `use-tooltip-transition` (the hook) are copied into your project.
+</Note>
+
+## Example
+
+<LiveExample name="tooltip-example" />
+
+## States
+
+`TooltipState` is:
+
+```ts
+type TooltipState =
+ | "hidden" // opacity 0, scale 0.96, translate 4px away from anchor
+ | "visible" // opacity 1, scale 1, translate 0
+```
+
+`hidden` is the default. The `translate` magnitude (4 px when hidden, 0 when visible) is resolved by the component into an axis offset based on `side` — a `"top"` tooltip slides upward when hidden, a `"bottom"` tooltip slides downward, and so on.
+
+## 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 { Tooltip } from "@/components/remocn/tooltip";
+
+export const Scene = () => (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <div style={{ position: "absolute", left: "50%", top: "40%", transform: "translate(-50%, -100%)" }}>
+ <Tooltip state="visible" label="Keyboard shortcut ⌘K" side="top" />
+ </div>
+ </div>
+);
+```
+
+To drive state from the timeline, use `useCurrentState`:
+
+```tsx
+import { useCurrentState } from "@/lib/remocn-ui";
+import { Tooltip } from "@/components/remocn/tooltip";
+
+export const Scene = () => {
+ const state = useCurrentState(
+ [
+ { at: 30, state: "visible" },
+ { at: 90, state: "hidden" },
+ ],
+ "hidden",
+ );
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <div style={{ position: "absolute", left: "50%", top: "40%", transform: "translate(-50%, -100%)" }}>
+ <Tooltip state={state} label="Keyboard shortcut ⌘K" side="top" />
+ </div>
+ </div>
+ );
+};
+```
+
+Each `at` is a **Sequence-local authored frame**. State persists between steps: `visible` at frame 30 keeps the tooltip on-screen until `hidden` fires at frame 90. See [Concepts](/docs/ui/concepts) for the full `useCurrentState` API.
+
+## Smooth transitions
+
+State changes via `state` snap with no cross-fade. For an animated show/hide, use `useTooltipTransition` from the copied `use-tooltip-transition.ts` file. It reads the frame, interpolates between state presets, and returns a resolved `TooltipStyle` — pass it to the `style` prop:
+
+```tsx
+import { Tooltip } from "@/components/remocn/tooltip";
+import { useTooltipTransition } from "@/components/remocn/use-tooltip-transition";
+
+export const Scene = () => {
+ const style = useTooltipTransition([
+ { at: 30, state: "visible", duration: 8 },
+ { at: 90, state: "hidden", duration: 8 },
+ ]);
+
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ <div style={{ position: "absolute", left: "50%", top: "40%", transform: "translate(-50%, -100%)" }}>
+ <Tooltip style={style} label="Keyboard shortcut ⌘K" side="top" />
+ </div>
+ </div>
+ );
+};
+```
+
+The `duration` field on each step overrides the file's `DEFAULT_DURATION` (= `8`) for that specific transition. To globally tune timing and easing, edit `use-tooltip-transition.ts` directly in your project — that file is yours (shadcn "own your code" philosophy).
+
+`style` takes precedence over `state` when both are provided.
+
+## Sides
+
+The `side` prop controls two things: which direction the bubble slides in from when it appears, and which edge of the bubble the arrow points from. It is a static prop — it does not animate.
+
+```ts
+type TooltipSide =
+ | "top" // bubble above anchor, arrow on bottom edge, enters sliding up 4px
+ | "bottom" // bubble below anchor, arrow on top edge, enters sliding down 4px
+ | "left" // bubble left of anchor, arrow on right edge, enters sliding left 4px
+ | "right" // bubble right of anchor, arrow on left edge, enters sliding right 4px
+```
+
+Placement is the caller's responsibility. The tooltip renders inline — wrap it in an absolutely-positioned div that positions the bubble relative to its anchor. For a `"top"` tooltip:
+
+```tsx
+{/* Anchor element */}
+<div style={{ position: "relative", display: "inline-block" }}>
+ <Button label="Hover me" style={buttonStyle} />
+
+ {/* Tooltip positioned above the anchor, centered horizontally */}
+ <div
+ style={{
+ position: "absolute",
+ bottom: "calc(100% + 12px)",
+ left: "50%",
+ transform: "translateX(-50%)",
+ }}
+ >
+ <Tooltip style={tooltipStyle} label="Keyboard shortcut ⌘K" side="top" />
+ </div>
+</div>
+```
+
+For `"bottom"`, use `top: "calc(100% + 12px)"` instead. For `"left"` / `"right"`, use `right: "calc(100% + 12px)"` / `left: "calc(100% + 12px)"` and adjust vertical alignment to `top: "50%"` with `translateY(-50%)`.
+
+## Props
+
+<PropsTable
+ rows={[
+ {
+ name: "label",
+ type: "string",
+ description: "The tooltip text. Rendered as a single line (whitespace-nowrap).",
+ },
+ {
+ name: "side",
+ type: "\"top\" | \"bottom\" | \"left\" | \"right\"",
+ default: "\"top\"",
+ description: "Which side of the anchor the tooltip sits on. Sets the enter-slide direction and which edge the arrow points from. Static — not animated.",
+ },
+ {
+ name: "state",
+ type: "\"hidden\" | \"visible\"",
+ default: "\"hidden\"",
+ description: "Current visual state (snap path). State changes snap — no automatic cross-fade.",
+ },
+ {
+ name: "style",
+ type: "TooltipStyle",
+ description: "Resolved animated visual (smooth path). Pass an interpolated TooltipStyle from useTooltipTransition. Takes precedence over state when provided.",
+ },
+ {
+ name: "theme",
+ type: "Partial<RemocnTheme>",
+ description: "Per-component theme override. Merges with the active RemocnUIProvider theme and the mode defaults. Must be concrete oklch/hex/rgb values — not CSS custom properties.",
+ },
+ {
+ name: "mode",
+ type: "\"light\" | \"dark\"",
+ default: "\"light\"",
+ description: "Sets the base palette. Overrides the mode on RemocnUIProvider when both are present.",
+ },
+ {
+ name: "className",
+ type: "string",
+ description: "Optional className applied to the outer wrapper element.",
+ },
+ ]}
+/>
diff --git a/registry/__index__.tsx b/registry/__index__.tsx
index 3a3dc85a..982ecef3 100644
--- a/registry/__index__.tsx
+++ b/registry/__index__.tsx
@@ -145,6 +145,8 @@ 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 { TooltipPreview } from "@/registry/remocn-ui/tooltip/preview";
+import { tooltipConfig } from "@/registry/remocn-ui/tooltip/config";
import { ZoomThroughTransition } from "@/registry/remocn/zoom-through-transition";
import { zoomThroughTransitionConfig } from "@/registry/remocn/zoom-through-transition/config";
@@ -350,6 +352,9 @@ const registry: Record<string, RegistryEntry> = {
// 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 },
+ // tooltip's customizer Component is the preview-only TooltipPreview wrapper: a
+ // bare bubble has no backdrop and would not center as the composition root.
+ "tooltip": { Component: TooltipPreview, config: tooltipConfig },
"spinner": { Component: Spinner, config: spinnerConfig },
};
diff --git a/registry/remocn-ui/registry.json b/registry/remocn-ui/registry.json
index e8c06047..329055eb 100644
--- a/registry/remocn-ui/registry.json
+++ b/registry/remocn-ui/registry.json
@@ -436,6 +436,26 @@
"target": "components/remocn/use-command-menu-transition.ts"
}
]
+ },
+ {
+ "name": "tooltip",
+ "type": "registry:component",
+ "title": "UI Tooltip",
+ "description": "A tooltip whose hidden/visible state is a pure function of the timeline. The Tooltip renderer is a pure function of a TooltipStyle (opacity, scale, translate); useTooltipTransition eases both the show and the hide. The static `side` prop sets the enter translate axis and the arrow placement.",
+ "dependencies": ["remotion"],
+ "registryDependencies": ["remocn-ui"],
+ "files": [
+ {
+ "path": "tooltip/index.tsx",
+ "type": "registry:component",
+ "target": "components/remocn/tooltip.tsx"
+ },
+ {
+ "path": "tooltip/use-tooltip-transition.ts",
+ "type": "registry:component",
+ "target": "components/remocn/use-tooltip-transition.ts"
+ }
+ ]
}
]
}
diff --git a/registry/remocn-ui/tooltip/__tests__/README.md b/registry/remocn-ui/tooltip/__tests__/README.md
new file mode 100644
index 00000000..7eee97de
--- /dev/null
+++ b/registry/remocn-ui/tooltip/__tests__/README.md
@@ -0,0 +1,149 @@
+# `tooltip` — verification tests
+
+Pure / deterministic verification for the `tooltip` component
+(`registry/remocn-ui/tooltip/`). The render path (`index.tsx`) imports
+`useRemocnTheme` which requires React context and cannot run headlessly — it
+is NOT exercised here. This suite covers everything that IS pure:
+`tooltipStyle` presets, `tweenTooltipStyle` interpolation, the
+`useTooltipTransition` pure resolver mirror, and `tooltipConfig` controls
+wiring + snippet codegen.
+
+## Animation model — state atom with smooth opt-in
+
+Tooltip follows the standard state-atom pattern (see STYLE-GUIDE §1):
+
+**Snap path** (`state?: TooltipState` prop):
+`<Tooltip>` is a frame-free pure renderer. The `state` prop drives all
+visuals. Each state maps to a complete resting keyframe via the exported pure
+function `tooltipStyle(state) => TooltipStyle`. State changes snap — no
+tweening inside the component.
+
+**Smooth path** (`style?: TooltipStyle` prop):
+Callers opt in to smooth show/hide by passing a pre-interpolated `TooltipStyle`
+to the `style` prop. The caller — typically `useTooltipTransition` — reads
+`useCurrentFrame()` via `useStateTransition`, applies `easings.out` to the
+raw linear progress, and blends the two state presets via
+`tweenTooltipStyle(from, to, t)`. The `<Tooltip>` component remains
+frame-free; it renders whatever `TooltipStyle` it receives.
+
+**No color tween:** `TooltipStyle` carries only `opacity`, `scale`, and
+`translate` — all numeric. The bubble background/foreground are derived
+from `theme.primary`/`theme.primaryForeground` and do not animate, so
+`tweenTooltipStyle` is a simple three-field lerp with no `mixOklch` call.
+
+**`translate` is a magnitude, not a vector.** The `TooltipStyle.translate`
+field holds a single pixel magnitude (4 hidden → 0 visible). The private
+`offsetFor(side, translate)` function inside `index.tsx` converts this
+magnitude into a signed `(x, y)` offset so the bubble slides toward the
+anchor from its own side. `offsetFor` is not exported; its per-side contract
+is documented below and verified indirectly through the render path.
+
+**`offsetFor` contract (documented for grep-based verification):**
+
+| `side` | `x` | `y` | bubble enters from |
+|----------|-------------|-------------|------------------------|
+| `top` | 0 | +translate | above the anchor |
+| `bottom` | 0 | −translate | below the anchor |
+| `left` | +translate | 0 | left of the anchor |
+| `right` | −translate | 0 | right of the anchor |
+
+## How to run
+
+The repo uses **Bun**, which has a built-in test runner — runs TypeScript
+natively, no test-framework dep.
+
+```bash
+bun install
+bun test registry/remocn-ui/tooltip/__tests__
+```
+
+`tooltip.test.ts` imports `bun:test` (not `vitest`/`jest`), so no test script
+or framework dep is added to `package.json`.
+
+## What is covered
+
+- **`DEFAULT_DURATION`** — asserts the constant is 8 frames.
+
+- **`tooltipStyle` presets** — exported pure `(state) => TooltipStyle`.
+ Asserts every field for every state: `hidden` gives `{opacity:0, scale:0.96,
+ translate:4}`; `visible` gives `{opacity:1, scale:1, translate:0}`. Also
+ asserts all fields are numeric for every state, that the two states have
+ distinct values on every field (no silent identity), and that the unknown
+ state falls through to the `hidden` preset.
+
+- **`tweenTooltipStyle`** — exported pure `(a, b, t) => TooltipStyle`.
+ Asserts: at t=0 all three fields equal `a`; at t=1 all equal `b`; at t=0.5
+ each field is the exact midpoint (`opacity` 0→1 gives 0.5, `scale` 0.96→1
+ gives 0.98, `translate` 4→0 gives 2); at t=0.25 gives 0.25/0.97/3;
+ identity case (a===b, any t) preserves all fields. Also covers the reverse
+ direction (visible→hidden dismiss).
+
+- **`useTooltipTransition` resolver replica** — `resolveTooltipTransition`
+ mirrors `use-tooltip-transition.ts` lines 48-61 with `raw` injected in place
+ of `useCurrentFrame()`. The replica re-derives only the logic BEYOND the core
+ `useStateTransition` (already tested in `core/__tests__/timeline.test.ts`);
+ the key additional contract is that `progress` is eased with `easings.out`
+ before the tween. Asserts: before any step → hidden style with both endpoints
+ `hidden`; exactly at a step boundary → progress=0 → t=out(0)=0 → style
+ equals `hidden` keyframe; mid-window at raw=4/dur=8 (linear progress=0.5) →
+ t=out(0.5)=0.875 → opacity=0.875 (not linear 0.5), scale=0.995,
+ translate=0.5; past the window → fully visible style; speed contract (speed=2
+ halves the raw frame to reach a step).
+
+- **`tooltipConfig.controls`** — control wiring assertions: `state` is a
+ `select` with options `["hidden","visible"]` and default `"visible"`; `side`
+ is a `select` with options `["top","bottom","left","right"]` and default
+ `"top"`; `mode` is a `select` with options `["light","dark"]` and default
+ `"light"`; `label` is a `text` control with default `"Add to library"`.
+
+- **`tooltipConfig.snippet`** — pure JSX string builder. Asserts: `import {
+ Tooltip }` from the correct path; `<Tooltip` element and closing `/>` always
+ present; `state` is always emitted; `label` is always emitted (it is a
+ required prop, including when equal to the default); non-default label emits
+ the provided string; default `side="top"` and `mode="light"` are omitted;
+ non-default side and mode are emitted; all state options round-trip correctly;
+ all non-default side options round-trip correctly.
+
+**Tooltip render** is a pure `(style | state, side) => visual` observable only
+via Remotion render; it is not unit-tested here.
+
+## Import strategy
+
+`tooltip.test.ts` imports via **relative paths** and the `@/lib/remocn-ui`
+alias:
+
+- `../index` — relative, for `tooltipStyle`, `TooltipState`, `TooltipSide`
+- `../use-tooltip-transition` — relative, for `tweenTooltipStyle`,
+ `DEFAULT_DURATION`
+- `../config` — relative, for `tooltipConfig`
+- `@/lib/remocn-ui` — alias, for `defaultLightTheme`, `defaultDarkTheme`,
+ `easings`, and `Step` type
+
+`useTooltipTransition` is NOT imported — it calls `useStateTransition` which
+reads `useCurrentFrame()`. Its pure logic is mirrored as
+`resolveTooltipTransition` with the frame injected as `raw`. `bun test`
+resolves tsconfig `paths`, so the alias works without additional config.
+
+## Determinism grep checklist (run manually; must print NOTHING)
+
+`tooltip/index.tsx` is a pure renderer — the component must contain **none**
+of the following:
+
+```bash
+grep -nE "useState|useEffect|useCurrentFrame|onClick|onChange|addEventListener|Date\.now|Math\.random|requestAnimationFrame" \
+ registry/remocn-ui/tooltip/index.tsx
+```
+
+Expected: **no output**. Any match is a determinism violation.
+
+`use-tooltip-transition.ts` is the caller hook that intentionally reads
+`useCurrentFrame()` (via `useStateTransition`). That is correct and expected;
+the smooth-path design isolates all frame-reading to the hook, keeping
+`<Tooltip>` pure.
+
+Tier-wide sweep for `index.tsx`:
+
+```bash
+grep -nE "useState|useEffect|onClick|onChange|addEventListener|Date\.now|Math\.random" \
+ registry/remocn-ui/tooltip/index.tsx registry/remocn-ui/core/*.ts
+```
diff --git a/registry/remocn-ui/tooltip/__tests__/tooltip.test.ts b/registry/remocn-ui/tooltip/__tests__/tooltip.test.ts
new file mode 100644
index 00000000..9a84327a
--- /dev/null
+++ b/registry/remocn-ui/tooltip/__tests__/tooltip.test.ts
@@ -0,0 +1,651 @@
+/**
+ * Verification tests for the PURE / DETERMINISTIC parts of `tooltip`.
+ *
+ * Scope:
+ * - registry/remocn-ui/tooltip/index.tsx
+ * tooltipStyle(state) — complete state→visual preset map
+ * (no tooltipStyleContext — Tooltip uses theme.primary/primaryForeground
+ * directly; no pure style-context export on this component)
+ * - registry/remocn-ui/tooltip/use-tooltip-transition.ts
+ * tweenTooltipStyle(a, b, t) — pure lerp across every field
+ * DEFAULT_DURATION constant
+ * useTooltipTransition resolver — mirrored as resolveTooltipTransition
+ * with frame injected as `raw` (annotated source lines)
+ * - registry/remocn-ui/tooltip/config.ts
+ * tooltipConfig.controls wiring + tooltipConfig.snippet codegen
+ *
+ * The render path (index.tsx) imports `useRemocnTheme` which requires React
+ * context — it is NOT exercised here. `offsetFor` is a module-private function
+ * (not exported) — its logic is covered indirectly through the component render
+ * path and documented in the README; pure assertions on `tooltipStyle` cover the
+ * full pure surface.
+ *
+ * Runner: Bun's built-in test runner (TypeScript-native, no framework dep).
+ * bun test registry/remocn-ui/tooltip/__tests__
+ *
+ * --------------------------------------------------------------------------
+ * IMPORT STRATEGY
+ * --------------------------------------------------------------------------
+ * Relative imports from component source; `@/lib/remocn-ui` alias for core.
+ * `tooltipStyle` and `tweenTooltipStyle` are pure value functions — they call
+ * neither `useCurrentFrame()` nor `useRemocnTheme` at import or call time.
+ * `useTooltipTransition` IS a hook (calls `useStateTransition` → `useCurrentFrame`)
+ * and is NOT imported; we mirror its pure resolver body below.
+ * --------------------------------------------------------------------------
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+ tooltipStyle,
+ type TooltipState,
+ type TooltipSide,
+} from "../index";
+import {
+ tweenTooltipStyle,
+ DEFAULT_DURATION,
+} from "../use-tooltip-transition";
+import { tooltipConfig } from "../config";
+import { defaultLightTheme, defaultDarkTheme, easings } from "@/lib/remocn-ui";
+import type { Step } from "@/lib/remocn-ui";
+
+// ===========================================================================
+// Shared fixtures
+// ===========================================================================
+
+const VALID_STATES: readonly TooltipState[] = ["hidden", "visible"];
+const VALID_SIDES: readonly TooltipSide[] = ["top", "bottom", "left", "right"];
+
+/** Convenience wrapper for snippet(). */
+type SnippetValues = {
+ state?: string;
+ label?: string;
+ side?: string;
+ mode?: string;
+};
+const snippet = (values: SnippetValues): string =>
+ tooltipConfig.snippet(values as Record<string, unknown>);
+
+// ===========================================================================
+// 1. DEFAULT_DURATION constant
+// ===========================================================================
+
+describe("DEFAULT_DURATION", () => {
+ it("is 8 frames", () => {
+ expect(DEFAULT_DURATION).toBe(8);
+ });
+});
+
+// ===========================================================================
+// 2. tooltipStyle — pure (state) => TooltipStyle map
+// MIRROR of index.tsx lines 59-66
+// ===========================================================================
+
+describe("tooltipStyle: hidden state — off-screen keyframe", () => {
+ const s = tooltipStyle("hidden");
+
+ it("opacity is 0 (invisible)", () => {
+ expect(s.opacity).toBe(0);
+ });
+
+ it("scale is 0.96 (slightly shrunken at hidden)", () => {
+ expect(s.scale).toBeCloseTo(0.96, 10);
+ });
+
+ it("translate is 4 (enters from 4px offset)", () => {
+ expect(s.translate).toBe(4);
+ });
+});
+
+describe("tooltipStyle: visible state — resting keyframe", () => {
+ const s = tooltipStyle("visible");
+
+ it("opacity is 1 (fully visible)", () => {
+ expect(s.opacity).toBe(1);
+ });
+
+ it("scale is 1 (full size)", () => {
+ expect(s.scale).toBe(1);
+ });
+
+ it("translate is 0 (at rest position)", () => {
+ expect(s.translate).toBe(0);
+ });
+});
+
+describe("tooltipStyle: both states are complete keyframes", () => {
+ it("every TooltipStyle field is defined and numeric for every state", () => {
+ for (const state of VALID_STATES) {
+ const s = tooltipStyle(state);
+ expect(typeof s.opacity).toBe("number");
+ expect(typeof s.scale).toBe("number");
+ expect(typeof s.translate).toBe("number");
+ }
+ });
+
+ it("hidden and visible have distinct opacity (0 vs 1)", () => {
+ expect(tooltipStyle("hidden").opacity).toBe(0);
+ expect(tooltipStyle("visible").opacity).toBe(1);
+ });
+
+ it("hidden and visible have distinct scale (0.96 vs 1)", () => {
+ expect(tooltipStyle("hidden").scale).toBeCloseTo(0.96, 10);
+ expect(tooltipStyle("visible").scale).toBe(1);
+ });
+
+ it("hidden and visible have distinct translate (4 vs 0)", () => {
+ expect(tooltipStyle("hidden").translate).toBe(4);
+ expect(tooltipStyle("visible").translate).toBe(0);
+ });
+});
+
+describe("tooltipStyle: unknown state falls through to hidden preset", () => {
+ // The switch has no explicit 'hidden' arm — only 'visible'; default → hidden
+ it("'hidden' returns opacity=0 (via default arm)", () => {
+ expect(tooltipStyle("hidden").opacity).toBe(0);
+ });
+});
+
+// ===========================================================================
+// 3. tweenTooltipStyle — pure lerp across all three fields
+// MIRROR of use-tooltip-transition.ts lines 24-33
+// All fields are numeric (no animated colors); no mixOklch call.
+// ===========================================================================
+
+describe("tweenTooltipStyle: t=0 returns values equal to `a`", () => {
+ const a = tooltipStyle("hidden");
+ const b = tooltipStyle("visible");
+ const r = tweenTooltipStyle(a, b, 0);
+
+ it("opacity equals a.opacity at t=0", () => {
+ expect(r.opacity).toBeCloseTo(a.opacity, 10);
+ });
+
+ it("scale equals a.scale at t=0", () => {
+ expect(r.scale).toBeCloseTo(a.scale, 10);
+ });
+
+ it("translate equals a.translate at t=0", () => {
+ expect(r.translate).toBeCloseTo(a.translate, 10);
+ });
+});
+
+describe("tweenTooltipStyle: t=1 returns values equal to `b`", () => {
+ const a = tooltipStyle("hidden");
+ const b = tooltipStyle("visible");
+ const r = tweenTooltipStyle(a, b, 1);
+
+ it("opacity equals b.opacity at t=1", () => {
+ expect(r.opacity).toBeCloseTo(b.opacity, 10);
+ });
+
+ it("scale equals b.scale at t=1", () => {
+ expect(r.scale).toBeCloseTo(b.scale, 10);
+ });
+
+ it("translate equals b.translate at t=1", () => {
+ expect(r.translate).toBeCloseTo(b.translate, 10);
+ });
+});
+
+describe("tweenTooltipStyle: t=0.5 midpoint (hidden → visible)", () => {
+ // hidden: opacity=0, scale=0.96, translate=4
+ // visible: opacity=1, scale=1, translate=0
+ // midpoint: opacity=0.5, scale=0.98, translate=2
+ const a = tooltipStyle("hidden");
+ const b = tooltipStyle("visible");
+ const r = tweenTooltipStyle(a, b, 0.5);
+
+ it("opacity midpoint: 0 → 1 gives 0.5", () => {
+ expect(r.opacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("scale midpoint: 0.96 → 1 gives 0.98", () => {
+ expect(r.scale).toBeCloseTo(0.98, 10);
+ });
+
+ it("translate midpoint: 4 → 0 gives 2", () => {
+ expect(r.translate).toBeCloseTo(2, 10);
+ });
+});
+
+describe("tweenTooltipStyle: t=0.5 midpoint (visible → hidden, dismiss direction)", () => {
+ // Reverse direction: visible→hidden
+ // midpoint: opacity=0.5, scale=0.98, translate=2
+ const a = tooltipStyle("visible");
+ const b = tooltipStyle("hidden");
+ const r = tweenTooltipStyle(a, b, 0.5);
+
+ it("opacity midpoint: 1 → 0 gives 0.5", () => {
+ expect(r.opacity).toBeCloseTo(0.5, 10);
+ });
+
+ it("scale midpoint: 1 → 0.96 gives 0.98", () => {
+ expect(r.scale).toBeCloseTo(0.98, 10);
+ });
+
+ it("translate midpoint: 0 → 4 gives 2", () => {
+ expect(r.translate).toBeCloseTo(2, 10);
+ });
+});
+
+describe("tweenTooltipStyle: identity (a === b, any t)", () => {
+ const s = tooltipStyle("visible");
+
+ it("opacity is unchanged when both endpoints are the same", () => {
+ expect(tweenTooltipStyle(s, s, 0.5).opacity).toBeCloseTo(s.opacity, 10);
+ });
+
+ it("scale is unchanged when both endpoints are the same", () => {
+ expect(tweenTooltipStyle(s, s, 0.5).scale).toBeCloseTo(s.scale, 10);
+ });
+
+ it("translate is unchanged when both endpoints are the same", () => {
+ expect(tweenTooltipStyle(s, s, 0.5).translate).toBeCloseTo(s.translate, 10);
+ });
+});
+
+describe("tweenTooltipStyle: t=0.25 quarter-point (hidden → visible)", () => {
+ // opacity: 0 + 0.25*(1-0) = 0.25
+ // scale: 0.96 + 0.25*(1-0.96) = 0.96 + 0.01 = 0.97
+ // translate: 4 + 0.25*(0-4) = 4 - 1 = 3
+ const a = tooltipStyle("hidden");
+ const b = tooltipStyle("visible");
+ const r = tweenTooltipStyle(a, b, 0.25);
+
+ it("opacity at t=0.25 is 0.25", () => {
+ expect(r.opacity).toBeCloseTo(0.25, 10);
+ });
+
+ it("scale at t=0.25 is 0.97", () => {
+ expect(r.scale).toBeCloseTo(0.97, 10);
+ });
+
+ it("translate at t=0.25 is 3", () => {
+ expect(r.translate).toBeCloseTo(3, 10);
+ });
+});
+
+// ===========================================================================
+// 4. useTooltipTransition resolver replica
+// MIRRORS use-tooltip-transition.ts lines 48-61.
+// `useTooltipTransition` calls `useStateTransition` (which reads
+// `useCurrentFrame()`) then applies `easings.out(progress)` and
+// `tweenTooltipStyle`. We inject `raw` in place of `useCurrentFrame()`.
+//
+// This replica re-derives only the logic BEYOND the core
+// `useStateTransition` (already tested in core/__tests__/timeline.test.ts).
+// The key additional contract: progress is eased with `easings.out` before
+// the tween, so field values are out-eased, not linear.
+//
+// MAINTENANCE CONTRACT: if use-tooltip-transition.ts lines 48-61 change,
+// update this replica in lockstep. Annotated source lines below.
+// ===========================================================================
+
+/** MIRROR of core/timeline.ts:clamp01. */
+function clamp01Mirror(t: number): number {
+ return Math.max(0, Math.min(1, t));
+}
+
+/** MIRROR of core/motion.ts:easings.out (cubic ease-out). */
+function easingOut(t: number): number {
+ return 1 - (1 - t) ** 3;
+}
+
+/**
+ * MIRROR of timeline.ts:useStateTransition pure resolver body,
+ * with `raw` injected.
+ */
+function resolveStateTransition<S extends string>(
+ raw: number,
+ steps: Step<S>[],
+ defaultState: S,
+ speed = 1,
+ defaultDuration = 8,
+): { from: S; to: S; progress: number } {
+ const effectiveFrame = raw * speed;
+ const started = steps
+ .map((step, index) => ({ step, index }))
+ .sort((a, b) => a.step.at - b.step.at || a.index - b.index)
+ .filter((e) => e.step.at <= effectiveFrame);
+ if (started.length === 0)
+ return { from: defaultState, to: defaultState, progress: 1 };
+ const to = started[started.length - 1].step;
+ const from = started.length >= 2 ? started[started.length - 2].step : null;
+ const dur = to.duration ?? defaultDuration;
+ const progress = dur > 0 ? clamp01Mirror((effectiveFrame - to.at) / dur) : 1;
+ return { from: from ? from.state : defaultState, to: to.state, progress };
+}
+
+/**
+ * MIRROR of use-tooltip-transition.ts:useTooltipTransition (lines 48-61).
+ * `raw` is injected in place of useCurrentFrame().
+ * Annotated source lines:
+ * line 52: destructure speed + defaultDuration from opts
+ * line 53-58: call useStateTransition (mirrored as resolveStateTransition)
+ * line 59: t = easings.out(progress) ← MIRROR line 59
+ * line 60: tweenTooltipStyle(from, to, t) ← MIRROR line 60
+ */
+function resolveTooltipTransition(
+ raw: number, // injected useCurrentFrame() — MIRROR line 53
+ steps: Step<TooltipState>[],
+ speed = 1,
+ defaultDuration = DEFAULT_DURATION,
+): { style: ReturnType<typeof tweenTooltipStyle>; progress: number; from: TooltipState; to: TooltipState } {
+ const { from, to, progress } = resolveStateTransition( // MIRROR lines 53-58
+ raw,
+ steps,
+ "hidden",
+ speed,
+ defaultDuration,
+ );
+ const t = easingOut(progress); // MIRROR line 59
+ const style = tweenTooltipStyle(tooltipStyle(from as TooltipState), tooltipStyle(to as TooltipState), t); // MIRROR line 60
+ return { style, progress, from: from as TooltipState, to: to as TooltipState };
+}
+
+// ---------------------------------------------------------------------------
+// Before any step: holds at hidden (progress=1, tween(hidden,hidden,out(1)))
+// ---------------------------------------------------------------------------
+
+describe("resolveTooltipTransition: before any step — holds at hidden", () => {
+ it("returns the hidden style when no steps have started", () => {
+ const { style } = resolveTooltipTransition(0, []);
+ const hidden = tooltipStyle("hidden");
+ // out(1)=1, so tween(hidden,hidden,1) = hidden
+ expect(style.opacity).toBeCloseTo(hidden.opacity, 10);
+ expect(style.scale).toBeCloseTo(hidden.scale, 10);
+ expect(style.translate).toBeCloseTo(hidden.translate, 10);
+ });
+
+ it("from and to are both 'hidden' before any step", () => {
+ const { from, to } = resolveTooltipTransition(0, []);
+ expect(from).toBe("hidden");
+ expect(to).toBe("hidden");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Exactly at a step boundary: progress=0, t=easings.out(0)=0
+// ---------------------------------------------------------------------------
+
+describe("resolveTooltipTransition: exactly at hidden→visible step boundary", () => {
+ const steps: Step<TooltipState>[] = [{ at: 10, state: "visible" }];
+
+ it("at raw=10 exactly, progress=0, t=out(0)=0 → style equals hidden (from)", () => {
+ const { style, progress } = resolveTooltipTransition(10, steps);
+ expect(progress).toBe(0);
+ // t = out(0) = 0, so style = tween(hidden, visible, 0) = hidden
+ const hidden = tooltipStyle("hidden");
+ expect(style.opacity).toBeCloseTo(hidden.opacity, 10);
+ expect(style.scale).toBeCloseTo(hidden.scale, 10);
+ expect(style.translate).toBeCloseTo(hidden.translate, 10);
+ });
+
+ it("from='hidden', to='visible' at the step boundary", () => {
+ const { from, to } = resolveTooltipTransition(10, steps);
+ expect(from).toBe("hidden");
+ expect(to).toBe("visible");
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Mid-window: easings.out applied to progress (non-linear)
+// ---------------------------------------------------------------------------
+
+describe("resolveTooltipTransition: mid-window uses easings.out (not linear)", () => {
+ // step at=0, defaultDuration=8. At raw=4: linear progress=0.5, out(0.5)=0.875
+ // opacity: tween(0, 1, 0.875) = 0.875
+ // scale: tween(0.96, 1, 0.875) = 0.96 + 0.04*0.875 = 0.995
+ // translate: tween(4, 0, 0.875) = 4*(1-0.875) = 0.5
+ const steps: Step<TooltipState>[] = [{ at: 0, state: "visible" }];
+
+ it("opacity at raw=4 is tween(0,1,out(0.5)) ≈ 0.875 (not linear 0.5)", () => {
+ const { style } = resolveTooltipTransition(4, steps, 1, 8);
+ const expectedT = easingOut(0.5); // 0.875
+ expect(style.opacity).toBeCloseTo(expectedT, 8);
+ });
+
+ it("scale at raw=4 is tween(0.96,1,out(0.5)): 0.96 + 0.04*0.875 = 0.995", () => {
+ const { style } = resolveTooltipTransition(4, steps, 1, 8);
+ const t = easingOut(0.5);
+ const expected = 0.96 + (1 - 0.96) * t; // 0.995
+ expect(style.scale).toBeCloseTo(expected, 8);
+ });
+
+ it("translate at raw=4 is tween(4,0,out(0.5)): 4*(1-0.875) = 0.5", () => {
+ const { style } = resolveTooltipTransition(4, steps, 1, 8);
+ const t = easingOut(0.5);
+ const expected = 4 * (1 - t); // 0.5
+ expect(style.translate).toBeCloseTo(expected, 8);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Past the window: progress=1, t=out(1)=1 → fully visible
+// ---------------------------------------------------------------------------
+
+describe("resolveTooltipTransition: past the transition window → fully visible", () => {
+ const steps: Step<TooltipState>[] = [{ at: 0, state: "visible" }];
+
+ it("opacity is 1 after DEFAULT_DURATION frames", () => {
+ const { style } = resolveTooltipTransition(DEFAULT_DURATION, steps);
+ expect(style.opacity).toBeCloseTo(1, 10);
+ });
+
+ it("scale is 1 after DEFAULT_DURATION frames", () => {
+ const { style } = resolveTooltipTransition(DEFAULT_DURATION, steps);
+ expect(style.scale).toBeCloseTo(1, 10);
+ });
+
+ it("translate is 0 after DEFAULT_DURATION frames", () => {
+ const { style } = resolveTooltipTransition(DEFAULT_DURATION, steps);
+ expect(style.translate).toBeCloseTo(0, 10);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Speed contract
+// ---------------------------------------------------------------------------
+
+describe("resolveTooltipTransition: speed contract", () => {
+ // step at=8. speed=2: effectiveFrame = raw*2 → fires at raw=4.
+ const steps: Step<TooltipState>[] = [{ at: 8, state: "visible" }];
+
+ it("speed=2: step at=8 fires at raw=4 (eff=8)", () => {
+ const { to } = resolveTooltipTransition(4, steps, 2);
+ expect(to).toBe("visible");
+ });
+
+ it("speed=2: step at=8 has NOT fired at raw=3 (eff=6 < 8)", () => {
+ const { to } = resolveTooltipTransition(3, steps, 2);
+ expect(to).toBe("hidden");
+ });
+});
+
+// ===========================================================================
+// 5. tooltipConfig.controls — customizer control wiring
+// ===========================================================================
+
+describe("tooltipConfig.controls: state", () => {
+ it("state is a select control", () => {
+ expect(tooltipConfig.controls.state.type).toBe("select");
+ });
+
+ it("state options are ['hidden', 'visible']", () => {
+ const ctrl = tooltipConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["hidden", "visible"]);
+ });
+
+ it("state default is 'visible' (shows the resting tooltip in the preview)", () => {
+ expect(tooltipConfig.controls.state.default).toBe("visible");
+ });
+
+ it("every state option is a valid TooltipState", () => {
+ const ctrl = tooltipConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const opt of ctrl.options) {
+ expect(VALID_STATES).toContain(opt as TooltipState);
+ }
+ });
+});
+
+describe("tooltipConfig.controls: side", () => {
+ it("side is a select control", () => {
+ expect(tooltipConfig.controls.side.type).toBe("select");
+ });
+
+ it("side options are ['top', 'bottom', 'left', 'right']", () => {
+ const ctrl = tooltipConfig.controls.side;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["top", "bottom", "left", "right"]);
+ });
+
+ it("side default is 'top'", () => {
+ expect(tooltipConfig.controls.side.default).toBe("top");
+ });
+
+ it("every side option is a valid TooltipSide", () => {
+ const ctrl = tooltipConfig.controls.side;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const opt of ctrl.options) {
+ expect(VALID_SIDES).toContain(opt as TooltipSide);
+ }
+ });
+});
+
+describe("tooltipConfig.controls: mode", () => {
+ it("mode is a select control", () => {
+ expect(tooltipConfig.controls.mode.type).toBe("select");
+ });
+
+ it("mode options are ['light', 'dark']", () => {
+ const ctrl = tooltipConfig.controls.mode;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ expect(ctrl.options).toEqual(["light", "dark"]);
+ });
+
+ it("mode default is 'light'", () => {
+ expect(tooltipConfig.controls.mode.default).toBe("light");
+ });
+});
+
+describe("tooltipConfig.controls: label", () => {
+ it("label is a text control", () => {
+ expect(tooltipConfig.controls.label.type).toBe("text");
+ });
+
+ it("label default is 'Add to library'", () => {
+ expect(tooltipConfig.controls.label.default).toBe("Add to library");
+ });
+});
+
+// ===========================================================================
+// 6. tooltipConfig.snippet — pure JSX string builder
+// ===========================================================================
+
+describe("tooltipConfig.snippet: import line", () => {
+ it("includes 'import { Tooltip }' from the correct path", () => {
+ const out = snippet({ state: "visible" });
+ expect(out).toContain("import { Tooltip }");
+ expect(out).toContain('from "@/components/remocn/tooltip"');
+ });
+});
+
+describe("tooltipConfig.snippet: structural invariants", () => {
+ it("contains a <Tooltip JSX element", () => {
+ expect(snippet({ state: "visible" })).toContain("<Tooltip");
+ });
+
+ it("ends with a self-closing />", () => {
+ expect(snippet({ state: "visible" }).trimEnd().endsWith("/>")).toBe(true);
+ });
+
+ it("state prop is always emitted", () => {
+ expect(snippet({ state: "visible" })).toContain('state="visible"');
+ expect(snippet({ state: "hidden" })).toContain('state="hidden"');
+ });
+
+ it("label prop is always emitted", () => {
+ expect(snippet({ state: "visible" })).toContain('label="');
+ });
+});
+
+describe("tooltipConfig.snippet: label is always emitted", () => {
+ // label is required on <Tooltip>, always emitted even for the default.
+ it("emits label='Add to library' when label is the default", () => {
+ const out = snippet({ state: "visible", label: "Add to library" });
+ expect(out).toContain('label="Add to library"');
+ });
+
+ it("emits label when label is omitted from values (falls back to default)", () => {
+ const out = snippet({ state: "visible" });
+ expect(out).toContain('label="Add to library"');
+ });
+
+ it("emits a non-default label when provided", () => {
+ const out = snippet({ state: "visible", label: "Copy link" });
+ expect(out).toContain('label="Copy link"');
+ });
+});
+
+describe("tooltipConfig.snippet: default props are omitted", () => {
+ // Defaults: side=top, mode=light
+
+ it("omits side when it equals the default 'top'", () => {
+ const out = snippet({ state: "visible", side: "top" });
+ expect(out).not.toContain("side=");
+ });
+
+ it("omits mode when it equals the default 'light'", () => {
+ const out = snippet({ state: "visible", mode: "light" });
+ expect(out).not.toContain("mode=");
+ });
+});
+
+describe("tooltipConfig.snippet: non-default props are emitted", () => {
+ it("emits side='bottom' when non-default", () => {
+ expect(snippet({ state: "visible", side: "bottom" })).toContain(
+ 'side="bottom"',
+ );
+ });
+
+ it("emits side='left' when non-default", () => {
+ expect(snippet({ state: "visible", side: "left" })).toContain(
+ 'side="left"',
+ );
+ });
+
+ it("emits side='right' when non-default", () => {
+ expect(snippet({ state: "visible", side: "right" })).toContain(
+ 'side="right"',
+ );
+ });
+
+ it("emits mode='dark' when non-default", () => {
+ expect(snippet({ state: "visible", mode: "dark" })).toContain(
+ 'mode="dark"',
+ );
+ });
+});
+
+describe("tooltipConfig.snippet: state options round-trip", () => {
+ it("emits the correct state for every control option", () => {
+ const ctrl = tooltipConfig.controls.state;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ for (const state of ctrl.options) {
+ expect(snippet({ state })).toContain(`state="${state}"`);
+ }
+ });
+});
+
+describe("tooltipConfig.snippet: side options round-trip", () => {
+ it("emits the correct side for every non-default side option", () => {
+ const ctrl = tooltipConfig.controls.side;
+ if (ctrl.type !== "select") throw new Error("expected select");
+ const nonDefault = ctrl.options.filter((o) => o !== "top");
+ for (const side of nonDefault) {
+ expect(snippet({ state: "visible", side })).toContain(`side="${side}"`);
+ }
+ });
+});
diff --git a/registry/remocn-ui/tooltip/config.ts b/registry/remocn-ui/tooltip/config.ts
new file mode 100644
index 00000000..e29046e6
--- /dev/null
+++ b/registry/remocn-ui/tooltip/config.ts
@@ -0,0 +1,55 @@
+import { type ComponentConfig, FPS, H, W } from "@/lib/customizer-config";
+import type { TooltipState } from "@/registry/remocn-ui/tooltip";
+
+const DEFAULT_LABEL = "Add to library";
+
+export const tooltipConfig: ComponentConfig = {
+ componentName: "Tooltip",
+ importPath: "@/components/remocn/tooltip",
+ controls: {
+ label: { type: "text", default: DEFAULT_LABEL, label: "Label" },
+ side: {
+ type: "select",
+ default: "top",
+ options: ["top", "bottom", "left", "right"],
+ label: "Side",
+ },
+ state: {
+ type: "select",
+ // Default to `visible` so the preview shows the resting tooltip.
+ default: "visible",
+ options: ["hidden", "visible"],
+ label: "State",
+ },
+ mode: {
+ type: "select",
+ default: "light",
+ options: ["light", "dark"],
+ label: "Mode",
+ },
+ },
+ durationInFrames: 120,
+ fps: FPS,
+ compositionWidth: W,
+ compositionHeight: H,
+ snippet: (values) => {
+ const state = (values.state as TooltipState) ?? "visible";
+ const label = values.label as string | undefined;
+ const side = values.side as string | undefined;
+ const mode = values.mode as string | undefined;
+
+ const props: string[] = [
+ ` state="${state}"`,
+ ` label="${label ?? DEFAULT_LABEL}"`,
+ ];
+ if (side !== undefined && side !== "top") props.push(` side="${side}"`);
+ if (mode !== undefined && mode !== "light")
+ props.push(` mode="${mode}"`);
+
+ return `import { Tooltip } from "@/components/remocn/tooltip";
+
+<Tooltip
+${props.join("\n")}
+/>`;
+ },
+};
diff --git a/registry/remocn-ui/tooltip/index.tsx b/registry/remocn-ui/tooltip/index.tsx
new file mode 100644
index 00000000..3cf8ca2d
--- /dev/null
+++ b/registry/remocn-ui/tooltip/index.tsx
@@ -0,0 +1,179 @@
+"use client";
+
+import { type RemocnTheme, useRemocnTheme } from "@/lib/remocn-ui";
+
+export type TooltipState = "hidden" | "visible";
+
+export type TooltipSide = "top" | "bottom" | "left" | "right";
+
+export interface TooltipProps {
+ /** Current visual state (snap path). State changes snap (no enter-tweens). */
+ state?: TooltipState;
+ /**
+ * Resolved animated visual (smooth path). When provided, takes precedence over
+ * `state` — feed it an interpolated `TooltipStyle` from `useTooltipTransition`.
+ */
+ style?: TooltipStyle;
+ /** Tooltip text. */
+ label: string;
+ /**
+ * Which side of the anchor the tooltip sits on. STATIC — it sets the enter
+ * translate axis/sign (the bubble slides in toward the anchor) and which edge
+ * the arrow points from. Not animated.
+ */
+ side?: TooltipSide;
+ theme?: Partial<RemocnTheme>;
+ mode?: "light" | "dark";
+ className?: string;
+}
+
+/** Arrow half-size (px); the diamond is `ARROW` square, rotated 45°. */
+const ARROW = 10;
+
+// ===========================================================================
+// Tooltip visual — the COMPLETE animated look for a moment in time. A `state` is
+// a named preset of this visual (`tooltipStyle`); the smooth path feeds an
+// interpolated `TooltipStyle` straight through. The component is a pure renderer
+// of whichever `TooltipStyle` it receives. `translate` is a single magnitude in
+// px; the component applies it on the axis/sign chosen by `side`.
+// ===========================================================================
+
+export interface TooltipStyle {
+ /** Whole-tooltip opacity 0→1. */
+ opacity: number;
+ /** Enter zoom 0.96→1. */
+ scale: number;
+ /**
+ * Enter offset MAGNITUDE in px (4 hidden → 0 visible). The component turns
+ * this into a translateX/Y with the sign that slides the bubble in toward the
+ * anchor for the active `side`.
+ */
+ translate: number;
+}
+
+/**
+ * The COMPLETE resting visual for a state — a pure `(state) => TooltipStyle` map.
+ * Both presets are full keyframes; the tooltip enters from 4px offset at 0.96
+ * scale and rests at 0/1. To change how a state looks, edit one entry.
+ */
+export function tooltipStyle(state: TooltipState): TooltipStyle {
+ switch (state) {
+ case "visible":
+ return { opacity: 1, scale: 1, translate: 0 };
+ default:
+ return { opacity: 0, scale: 0.96, translate: 90 };
+ }
+}
+
+/**
+ * Resolve the `translate` magnitude into a CSS transform offset for a side. The
+ * bubble starts `translate` px on its OWN side away from the anchor and slides
+ * back toward it: side "top" (bubble above) enters moving up (+Y → 0), etc.
+ */
+function offsetFor(
+ side: TooltipSide,
+ translate: number,
+): {
+ x: number;
+ y: number;
+} {
+ switch (side) {
+ case "bottom":
+ return { x: 0, y: -translate };
+ case "left":
+ return { x: translate, y: 0 };
+ case "right":
+ return { x: -translate, y: 0 };
+ default: // top
+ return { x: 0, y: translate };
+ }
+}
+
+export function Tooltip({
+ state = "hidden",
+ style,
+ label,
+ side = "top",
+ theme: themeOverride,
+ mode,
+ className,
+}: TooltipProps) {
+ const theme = useRemocnTheme(themeOverride, mode);
+ const v = style ?? tooltipStyle(state);
+
+ // Actual current shadcn tooltip look: an INVERTED bubble — `bg-foreground` +
+ // `text-background` (dark-on-light in light mode), not the primary accent.
+ const bg = theme.foreground;
+ const fg = theme.background;
+ const { x, y } = offsetFor(side, v.translate);
+
+ // The arrow diamond is centered on the edge facing the anchor. We position it
+ // by the side opposite to `side` (top tooltip → arrow on its bottom edge).
+ const arrowStyle: React.CSSProperties = {
+ position: "absolute",
+ width: ARROW,
+ height: ARROW,
+ background: bg,
+ // shadcn arrow is a rotated square with softly rounded corners (rounded-[2px]).
+ borderRadius: 2,
+ transform: "rotate(45deg)",
+ ...(side === "top" && {
+ bottom: -ARROW / 2,
+ left: "50%",
+ marginLeft: -ARROW / 2,
+ }),
+ ...(side === "bottom" && {
+ top: -ARROW / 2,
+ left: "50%",
+ marginLeft: -ARROW / 2,
+ }),
+ ...(side === "left" && {
+ right: -ARROW / 2,
+ top: "50%",
+ marginTop: -ARROW / 2,
+ }),
+ ...(side === "right" && {
+ left: -ARROW / 2,
+ top: "50%",
+ marginTop: -ARROW / 2,
+ }),
+ };
+
+ return (
+ <div
+ className={className}
+ style={{
+ position: "relative",
+ display: "inline-flex",
+ alignItems: "center",
+ opacity: v.opacity,
+ transform: `translate(${x}px, ${y}px) scale(${v.scale})`,
+ transformOrigin: "center",
+ fontFamily:
+ "var(--font-geist-sans), -apple-system, BlinkMacSystemFont, sans-serif",
+ }}
+ >
+ <div
+ style={{
+ position: "relative",
+ padding: "6px 12px",
+ background: bg,
+ color: fg,
+ fontSize: 12,
+ fontWeight: 500,
+ lineHeight: 1.3,
+ letterSpacing: "-0.005em",
+ // shadcn `rounded-xl` ≈ theme.radius + 4 (repo radius ~8 → ~12).
+ borderRadius: theme.radius + 4,
+ whiteSpace: "nowrap",
+ boxShadow: "0 4px 12px -4px rgba(0,0,0,0.25)",
+ }}
+ >
+ {label}
+ {/* The arrow sits OUTSIDE the bubble's rounded box but behind its text;
+ it is clipped to a small diamond and shares the bubble background. */}
+ <span style={arrowStyle} />
+ </div>
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/tooltip/preview.tsx b/registry/remocn-ui/tooltip/preview.tsx
new file mode 100644
index 00000000..655bc94a
--- /dev/null
+++ b/registry/remocn-ui/tooltip/preview.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import { useRemocnTheme } from "@/lib/remocn-ui";
+import {
+ Tooltip,
+ type TooltipSide,
+ type TooltipState,
+} from "@/registry/remocn-ui/tooltip";
+
+export interface TooltipPreviewProps {
+ label?: string;
+ side?: TooltipSide;
+ state?: TooltipState;
+ mode?: "light" | "dark";
+}
+
+/**
+ * Preview-only wrapper for the customizer. The shipped `Tooltip` is a small
+ * placement-agnostic bubble in a transparent wrapper — the caller anchors it to
+ * a trigger (see the example). The customizer Player renders its `component` as
+ * the composition root, so a bare `Tooltip` would sit in normal flow and not
+ * center; this thin wrapper centers it on a theme-background stage just for the
+ * preview. NOT shipped: not listed in registry.json files.
+ */
+export function TooltipPreview({
+ label = "Add to library",
+ side = "top",
+ state = "visible",
+ mode,
+}: TooltipPreviewProps) {
+ const theme = useRemocnTheme(undefined, mode);
+
+ return (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ background: theme.background,
+ }}
+ >
+ <Tooltip label={label} side={side} state={state} mode={mode} />
+ </div>
+ );
+}
diff --git a/registry/remocn-ui/tooltip/use-tooltip-transition.ts b/registry/remocn-ui/tooltip/use-tooltip-transition.ts
new file mode 100644
index 00000000..5729546f
--- /dev/null
+++ b/registry/remocn-ui/tooltip/use-tooltip-transition.ts
@@ -0,0 +1,61 @@
+"use client";
+
+import {
+ easings,
+ type Step,
+ useStateTransition,
+} from "@/lib/remocn-ui";
+import {
+ tooltipStyle,
+ type TooltipState,
+ type TooltipStyle,
+} from "@/components/remocn/tooltip";
+// ^ 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 tooltip visuals: every field lerps. `TooltipStyle` carries no
+ * animated colors (the bubble bg/fg are static per theme), so there is no
+ * `mixOklch` here — but every field is covered so neither show nor hide freezes
+ * a channel.
+ */
+export function tweenTooltipStyle(
+ a: TooltipStyle,
+ b: TooltipStyle,
+ t: number,
+): TooltipStyle {
+ return {
+ opacity: a.opacity + (b.opacity - a.opacity) * t,
+ scale: a.scale + (b.scale - a.scale) * t,
+ translate: a.translate + (b.translate - a.translate) * t,
+ };
+}
+
+export interface TooltipTransitionOptions {
+ mode?: "light" | "dark";
+ speed?: number;
+ defaultDuration?: number;
+}
+
+/**
+ * Timeline → resolved (eased, tweened) TooltipStyle. The CALLER invokes this; it
+ * reads the frame, the `<Tooltip>` component does not. Feed the result to
+ * `<Tooltip style={...} />`. Both the show (hidden→visible) and the hide
+ * (visible→hidden) read from the same eased tween, so both look smooth.
+ */
+export function useTooltipTransition(
+ steps: Step<TooltipState>[],
+ opts: TooltipTransitionOptions = {},
+): TooltipStyle {
+ const { speed = 1, defaultDuration = DEFAULT_DURATION } = opts;
+ const { from, to, progress } = useStateTransition(
+ steps,
+ "hidden",
+ speed,
+ defaultDuration,
+ );
+ const t = easings.out(progress);
+ return tweenTooltipStyle(tooltipStyle(from), tooltipStyle(to), t);
+}