Initial Commit

packages/ui/react/react-ui/src/components/hover-card/hover-card.variants.md

@@ -0,0 +1,52 @@
+# HoverCard Variants (cva config)
+
+## Purpose
+
+`hoverCardContentVariants` is the cva configuration powering the `<HoverCardContent>` floating panel. It is split from `hover-card.tsx` into its own module so an ejected source copy under `npx shadcn@latest add @suaveplan/hover-card` keeps the cva configuration in a dedicated file. Theme overrides flow through `useThemedVariants("HoverCardContent")`.
+
+The cva carries the visual recipe (rounded border, popover-foreground colours, shadow, fixed `w-64` width — narrower than `<PopoverContent>` because hover cards typically hold richer content but live shorter on screen) plus the same animation recipe as Popover.
+
+## Features
+
+- Fixed `w-64` width (slightly narrower than Popover's `w-72`).
+- `data-state` open/close fade + zoom animations.
+- `data-side` slide-in direction matching the resolved positioning.
+- `bg-popover text-popover-foreground` so the panel reads against any surface.
+- `motion-reduce:animate-none` collapses animations under reduced-motion preference.
+
+## Usage: Basic Example
+
+```ts
+import { hoverCardContentVariants } from "@suaveplan/react-ui";
+
+const className = hoverCardContentVariants();
+```
+
+## Usage: Advanced Example
+
+```ts
+import { hoverCardContentVariants, cn } from "@suaveplan/react-ui";
+
+export function CustomHoverCardShell() {
+    return (
+        <div
+            data-state="open"
+            data-side="top"
+            className={cn(hoverCardContentVariants(), "w-80 p-6")}
+        >
+            …
+        </div>
+    );
+}
+```
+
+## API Reference
+
+### `hoverCardContentVariants(): string`
+
+Returns the hover-card content classes; takes no arguments — the hover card is not parameterised by an axis.
+
+## Implementation Notes
+
+- Per the shadcn skill rule, the cva NEVER assigns a numeric `z-index`. Radix's `<Portal>` mounts the content above all page content via DOM placement.
+- Width is fixed at `w-64` to match the shadcn upstream recipe — consumers who need a wider panel layer their own width override via `cn(...)` at the call site.