Initial Commit

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

@@ -0,0 +1,128 @@
+# HoverCard
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs --> - hover-card.variants — `hoverCardContentVariants` is…
+- [hover-card.variants](./hover-card.variants.md) — `hoverCardContentVariants` is the cva configuration powering the `<HoverCardContent>` floating panel. It is split from…
+- hover-card.variants — `hoverCardContentVariants` is…
+
+- [hover-card.variants](./hover-card.variants.md) — `hoverCardContentVariants` is the cva configuration powering the `<HoverCardContent>` floating panel. It is split from…
+
+- hover-card.variants — `hoverCardContentVariants` is…
+
+- [hover-card.variants](./hover-card.variants.md) — `hoverCardContentVariants` is the cva configuration powering the `<HoverCardContent>` floating panel. It is split from…
+
+- hover-card.variants — `hoverCardContentVariants` is…
+
+- [hover-card.variants](./hover-card.variants.md) — `hoverCardContentVariants` is the cva configuration powering the `<HoverCardContent>` floating panel. It is split from…
+- [hover-card.variants](./hover-card.variants.md) — `hoverCardContentVariants` is the cva configuration powering the `<HoverCardContent>` floating panel. It is split from…
+
+## Purpose
+
+`<HoverCard>` and its sub-components (`<HoverCardTrigger>`, `<HoverCardPortal>`, `<HoverCardContent>`, `<HoverCardArrow>`) are the chassis hover-card primitives built on `@radix-ui/react-hover-card`. Use this for non-modal previews that open on hover or focus over the trigger and dismiss on hover-out or blur — link previews, user-mention bios, contextual mini-cards.
+
+Distinct from `<Popover>`: HoverCard is hover-driven (mouse-only by spec; touch devices fall back to tap-to-open) with `openDelay` / `closeDelay` hysteresis. Distinct from `<Tooltip>`: HoverCard panels can hold rich content (multiple paragraphs, images, action links); Tooltip is a single short label.
+
+## Features
+
+- Opens on hover or focus over the trigger; closes on hover-out or blur.
+- `openDelay` / `closeDelay` numeric hysteresis (default 700/300 ms — Radix defaults).
+- Side / align positional API (`side`: top/right/bottom/left; `align`: start/center/end).
+- Self-portals via `<HoverCardPortal>`.
+- Optional `<HoverCardArrow>` decoration.
+- Theme-driven cva via `useThemedVariants("HoverCardContent")`.
+- All sub-components forward refs.
+- `motion-reduce:animate-none` collapses the open/close animations under `prefers-reduced-motion: reduce`.
+
+## Usage: Basic Example
+
+```tsx
+import {
+    HoverCard,
+    HoverCardContent,
+    HoverCardTrigger,
+} from "@suaveplan/react-ui";
+
+export function MentionPreview() {
+    return (
+        <HoverCard>
+            <HoverCardTrigger>@suaveplan</HoverCardTrigger>
+            <HoverCardContent>
+                Component library for the Suaveplan platform.
+            </HoverCardContent>
+        </HoverCard>
+    );
+}
+```
+
+## Usage: Advanced Example
+
+```tsx
+import {
+    HoverCard,
+    HoverCardArrow,
+    HoverCardContent,
+    HoverCardTrigger,
+} from "@suaveplan/react-ui";
+
+interface User {
+    readonly handle: string;
+    readonly displayName: string;
+    readonly bio: string;
+    readonly avatarUrl: string;
+}
+
+export function UserMention({ user }: { user: User }) {
+    return (
+        <HoverCard openDelay={400} closeDelay={200}>
+            <HoverCardTrigger asChild>
+                <a href={`/${user.handle}`}>@{user.handle}</a>
+            </HoverCardTrigger>
+            <HoverCardContent side="top" align="start" sideOffset={8}>
+                <HoverCardArrow />
+                <div className="flex gap-3">
+                    <img
+                        src={user.avatarUrl}
+                        alt=""
+                        className="h-10 w-10 rounded-full"
+                    />
+                    <div>
+                        <h4 className="font-semibold">{user.displayName}</h4>
+                        <p className="text-sm text-muted-foreground">
+                            @{user.handle}
+                        </p>
+                        <p className="mt-1 text-sm">{user.bio}</p>
+                    </div>
+                </div>
+            </HoverCardContent>
+        </HoverCard>
+    );
+}
+```
+
+## API Reference
+
+### `<HoverCard>`
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `open` | `boolean` | _uncontrolled_ | Controlled open state. |
+| `defaultOpen` | `boolean` | `false` | Initial open state. |
+| `onOpenChange` | `(open: boolean) => void` | _none_ | Fires on open/close transitions. |
+| `openDelay` | `number` | `700` | Delay (ms) before opening on hover. |
+| `closeDelay` | `number` | `300` | Delay (ms) before closing on hover-out. |
+
+### `<HoverCardContent>`
+
+Same positional props as `<PopoverContent>` (`side`, `align`, `sideOffset`, `alignOffset`, `avoidCollisions`, `collisionPadding`).
+
+### `<HoverCardTrigger>`, `<HoverCardArrow>`, `<HoverCardPortal>`
+
+Direct re-exports of the Radix sub-components.
+
+## Implementation Notes
+
+- The chassis NEVER assigns a numeric `z-index` — Radix portals handle stacking.
+- HoverCard is hover-driven and therefore inappropriate for touch-only UI; consider `<Popover>` (click-driven) for tap-to-open ergonomics.
+- `<HoverCardContent>` self-portals via `<HoverCardPortal>` so consumers do not need to compose the portal manually.
+- `align="center"` and `sideOffset={4}` are chassis defaults (matching shadcn upstream).