@adamosuiteservices/ui 2.11.15 → 2.11.17

package/docs/components/ui/hover-card.md

@@ -1,446 +1,446 @@
-# Hover Card Component
-
-Card emergente al hacer hover, basado en Radix UI. Ideal para previsualizar contenido, mostrar información adicional de usuarios, links o productos sin necesidad de click.
-
-## Descripción
-
-El componente `HoverCard` muestra contenido adicional al pasar el mouse sobre un elemento.
-
-## Importación
-
-```typescript
-import {
-  HoverCard,
-  HoverCardContent,
-  HoverCardTrigger,
-} from "@adamosuiteservices/ui/hover-card";
-```
-
-## Uso Básico
-
-```tsx
-<HoverCard>
-  <HoverCardTrigger>Hover me</HoverCardTrigger>
-  <HoverCardContent>
-    <div>
-      <h4 className="font-semibold">@nextjs</h4>
-      <p className="text-sm">The React Framework for the Web</p>
-    </div>
-  </HoverCardContent>
-</HoverCard>
-```
-
-## Con Avatar y Detalles
-
-```tsx
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <a href="https://github.com/vercel" className="underline">
-      @vercel
-    </a>
-  </HoverCardTrigger>
-  <HoverCardContent className="w-80">
-    <div className="flex gap-4">
-      <Avatar>
-        <AvatarImage src="https://github.com/vercel.png" />
-        <AvatarFallback>V</AvatarFallback>
-      </Avatar>
-      <div className="space-y-1">
-        <h4 className="text-sm font-semibold">@vercel</h4>
-        <p className="text-sm">
-          Deploy web projects with the best frontend developer experience.
-        </p>
-      </div>
-    </div>
-  </HoverCardContent>
-</HoverCard>
-```
-
-**Componentes**: 3 (HoverCard, HoverCardTrigger, HoverCardContent)
-
-## Props
-
-| Prop       | Tipo     | Default | Descripción                |
-| ---------- | -------- | ------- | -------------------------- |
-| openDelay  | `number` | `200`   | Delay antes de abrir (ms)  |
-| closeDelay | `number` | `300`   | Delay antes de cerrar (ms) |
-
-## Referencias
-
-- <https://ui.shadcn.com/docs/components/hover-card>
-- <https://www.radix-ui.com/primitives/docs/components/hover-card>
-
-## Patrones de Uso
-
-### Básico
-
-```tsx
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Button variant="link">@nextjs</Button>
-  </HoverCardTrigger>
-  <HoverCardContent className="w-80">
-    <div className="space-y-2">
-      <h4 className="text-sm font-semibold">@nextjs</h4>
-      <p className="text-sm">
-        The React Framework – created and maintained by @vercel.
-      </p>
-    </div>
-  </HoverCardContent>
-</HoverCard>
-```
-
-### Con Avatar (User Preview)
-
-```tsx
-import {
-  Avatar,
-  AvatarImage,
-  AvatarFallback,
-} from "@adamosuiteservices/ui/avatar";
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Button variant="link">@shadcn</Button>
-  </HoverCardTrigger>
-  <HoverCardContent className="w-80">
-    <div className="flex justify-between gap-4">
-      <Avatar>
-        <AvatarImage src="https://github.com/shadcn.png" />
-        <AvatarFallback>CN</AvatarFallback>
-      </Avatar>
-      <div className="space-y-1">
-        <h4 className="text-sm font-semibold">@shadcn</h4>
-        <p className="text-sm">
-          Building design systems and web apps. Creator of ui.shadcn.com.
-        </p>
-        <div className="flex items-center pt-2">
-          <Icon symbol="calendar_month" className="mr-2 text-lg opacity-70" />
-          <span className="text-xs text-muted-foreground">
-            Joined December 2021
-          </span>
-        </div>
-      </div>
-    </div>
-  </HoverCardContent>
-</HoverCard>;
-```
-
-### Trigger con Avatar
-
-```tsx
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Avatar className="cursor-pointer">
-      <AvatarImage src="https://github.com/shadcn.png" />
-      <AvatarFallback>CN</AvatarFallback>
-    </Avatar>
-  </HoverCardTrigger>
-  <HoverCardContent className="w-80">
-    <div className="space-y-3">
-      <div className="flex items-center gap-3">
-        <Avatar>
-          <AvatarImage src="https://github.com/shadcn.png" />
-          <AvatarFallback>CN</AvatarFallback>
-        </Avatar>
-        <div>
-          <h4 className="text-sm font-semibold">shadcn</h4>
-          <p className="text-sm text-muted-foreground">@shadcn</p>
-        </div>
-      </div>
-      <p className="text-sm">Building design systems and web apps.</p>
-      <div className="flex items-center gap-4 text-sm text-muted-foreground">
-        <div className="flex items-center gap-1">
-          <UsersIcon className="h-4 w-4" />
-          <span>2.1k followers</span>
-        </div>
-        <div>Following 180</div>
-      </div>
-    </div>
-  </HoverCardContent>
-</HoverCard>
-```
-
-### Repository Info
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Button variant="link" className="font-mono">
-      shadcn/ui
-    </Button>
-  </HoverCardTrigger>
-  <HoverCardContent className="w-80">
-    <div className="space-y-3">
-      <div>
-        <h4 className="text-sm font-semibold">shadcn/ui</h4>
-        <p className="text-sm text-muted-foreground">
-          Beautifully designed components that you can copy and paste into your
-          apps.
-        </p>
-      </div>
-      <div className="flex items-center gap-4 text-sm text-muted-foreground">
-        <div className="flex items-center gap-1">
-          <Icon symbol="star" className="text-lg" />
-          <span>45.2k</span>
-        </div>
-        <div className="flex items-center gap-1">
-          <Icon symbol="account_tree" className="text-lg" />
-          <span>4.1k</span>
-        </div>
-        <div className="flex items-center gap-1">
-          <div className="h-3 w-3 rounded-full bg-primary" />
-          <span>TypeScript</span>
-        </div>
-      </div>
-    </div>
-  </HoverCardContent>
-</HoverCard>;
-```
-
-### Inline Link Preview
-
-```tsx
-<p className="text-sm leading-relaxed">
-  This paragraph contains an{" "}
-  <HoverCard>
-    <HoverCardTrigger asChild>
-      <a href="#" className="underline underline-offset-4">
-        inline link
-      </a>
-    </HoverCardTrigger>
-    <HoverCardContent className="w-64">
-      <div className="space-y-2">
-        <h4 className="text-sm font-semibold">Link Preview</h4>
-        <p className="text-sm text-muted-foreground">
-          This shows additional context when you hover over the link.
-        </p>
-      </div>
-    </HoverCardContent>
-  </HoverCard>{" "}
-  that shows a preview when hovered.
-</p>
-```
-
-### Product Preview con Imagen
-
-```tsx
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Button variant="link">View product</Button>
-  </HoverCardTrigger>
-  <HoverCardContent className="w-80">
-    <div className="space-y-3">
-      <img
-        src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd?w=800"
-        alt="Product preview"
-        className="w-full h-32 object-cover rounded-md"
-      />
-      <div>
-        <h4 className="text-sm font-semibold">Wireless Headphones</h4>
-        <p className="text-sm text-muted-foreground">
-          High-quality wireless headphones with noise cancellation.
-        </p>
-        <p className="text-lg font-bold mt-2">$299.99</p>
-      </div>
-    </div>
-  </HoverCardContent>
-</HoverCard>
-```
-
-### Con Delays Custom
-
-```tsx
-<HoverCard openDelay={1000} closeDelay={500}>
-  <HoverCardTrigger asChild>
-    <Button variant="outline">Hover (1s delay)</Button>
-  </HoverCardTrigger>
-  <HoverCardContent className="w-64">
-    <div className="space-y-2">
-      <h4 className="text-sm font-semibold">Delayed Hover Card</h4>
-      <p className="text-sm text-muted-foreground">
-        This hover card has a 1 second open delay and 500ms close delay.
-      </p>
-    </div>
-  </HoverCardContent>
-</HoverCard>
-```
-
-### Diferentes Tamaños
-
-```tsx
-{
-  /* Small */
-}
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Button variant="outline" size="sm">
-      Small
-    </Button>
-  </HoverCardTrigger>
-  <HoverCardContent className="w-48">
-    <p className="text-sm">Small hover card content.</p>
-  </HoverCardContent>
-</HoverCard>;
-
-{
-  /* Medium (default) */
-}
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Button variant="outline">Medium</Button>
-  </HoverCardTrigger>
-  <HoverCardContent className="w-64">
-    <p className="text-sm">Medium sized hover card.</p>
-  </HoverCardContent>
-</HoverCard>;
-
-{
-  /* Large */
-}
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Button variant="outline" size="lg">
-      Large
-    </Button>
-  </HoverCardTrigger>
-  <HoverCardContent className="w-96">
-    <div className="space-y-2">
-      <h4 className="text-sm font-semibold">Large Hover Card</h4>
-      <p className="text-sm">
-        This is a larger hover card with more content space.
-      </p>
-    </div>
-  </HoverCardContent>
-</HoverCard>;
-```
-
-### Posicionamiento Custom
-
-```tsx
-{
-  /* Top */
-}
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Button variant="outline">Top</Button>
-  </HoverCardTrigger>
-  <HoverCardContent side="top" className="w-48">
-    <p className="text-sm">Content positioned above.</p>
-  </HoverCardContent>
-</HoverCard>;
-
-{
-  /* Right */
-}
-<HoverCard>
-  <HoverCardTrigger asChild>
-    <Button variant="outline">Right</Button>
-  </HoverCardTrigger>
-  <HoverCardContent side="right" className="w-48">
-    <p className="text-sm">Content positioned to the right.</p>
-  </HoverCardContent>
-</HoverCard>;
-```
-
-### Controlado
-
-```tsx
-import { useState } from "react";
-
-function App() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <HoverCard open={open} onOpenChange={setOpen}>
-      <HoverCardTrigger asChild>
-        <Button>Controlled</Button>
-      </HoverCardTrigger>
-      <HoverCardContent>
-        <p className="text-sm">Hover card content</p>
-        <Button onClick={() => setOpen(false)}>Close</Button>
-      </HoverCardContent>
-    </HoverCard>
-  );
-}
-```
-
-## Casos de Uso Comunes
-
-**User mentions**: Preview de perfil al hover sobre @username  
-**Link previews**: Información adicional sobre links externos  
-**Product cards**: Preview rápido de productos sin navegar  
-**Repository info**: Stats y detalles de repos en listas  
-**Tooltips ricos**: Información estructurada vs simple tooltip  
-**Avatar hovers**: Detalles de usuario al hover sobre avatar
-
-## Estados y Data Attributes
-
-### Content States
-
-- **Open**: `data-[state=open]` → `animate-in`, `fade-in-0`, `zoom-in-95`
-- **Closed**: `data-[state=closed]` → `animate-out`, `fade-out-0`, `zoom-out-95`
-
-### Animations
-
-- **Slide in**: `data-[side=top|right|bottom|left]` → direccional
-
-## Interacción
-
-- ✅ **Hover to open**: Abre al pasar mouse sobre trigger
-- ✅ **Hover to close**: Cierra al sacar mouse del trigger y content
-- ✅ **Delay**: `openDelay` y `closeDelay` configurables
-- ✅ **Safe area**: Mouse puede moverse entre trigger y content sin cerrar
-- ✅ **Keyboard**: No se abre con teclado (solo mouse/pointer)
-- ✅ **Touch**: No funciona en dispositivos táctiles (solo hover)
-
-## Accesibilidad
-
-- ✅ **ARIA**: `role="tooltip"` o `aria-describedby` según contenido
-- ✅ **Keyboard**: No accesible por teclado (por diseño)
-- ✅ **Screen readers**: Contenido anunciado al abrir
-- ✅ **Focus**: No recibe focus, solo hover
-- ⚠️ **Mobile**: No funciona en touch devices (considerar alternativas)
-
-**Nota**: Para contenido crítico, no uses HoverCard. Usa Dialog o incluye la info directamente.
-
-## Notas de Implementación
-
-- **Basado en Radix UI**: `@radix-ui/react-hover-card`
-- **Hover only**: Solo funciona con mouse/pointer, no touch
-- **Portal rendering**: Content se renderiza en `document.body`
-- **Collision detection**: Auto-ajusta posición si sale del viewport
-- **Safe area**: Permite mover mouse entre trigger y content
-- **No keyboard**: No se puede abrir con teclado (limitación intencional)
-- **Default delays**: 200ms open, 300ms close
-- **Z-index**: 50 para aparecer sobre contenido
-- **Transform origin**: CSS variables de Radix para animaciones
-
-## Diferencias con Tooltip
-
-| Aspecto         | HoverCard                           | Tooltip              |
-| --------------- | ----------------------------------- | -------------------- |
-| **Contenido**   | Rico (texto, imágenes, links)       | Simple (texto plano) |
-| **Interacción** | Hoverable (puede hacer clic dentro) | No interactivo       |
-| **Tamaño**      | Variable, usualmente más grande     | Pequeño, compacto    |
-| **Keyboard**    | No accesible                        | Accesible con focus  |
-| **Uso**         | Previews, información adicional     | Labels, ayuda breve  |
-
-## Troubleshooting
-
-**No aparece en mobile**: HoverCard solo funciona con hover, no en touch devices  
-**Se cierra inmediatamente**: Verifica `closeDelay` o que no haya CSS interfiriendo  
-**No abre**: Verifica que `asChild` esté correcto en trigger con componentes custom  
-**Posición incorrecta**: Ajusta `side`, `align`, `sideOffset` y `alignOffset`  
-**Contenido cortado**: Asegúrate de que el portal no esté limitado por overflow  
-**Flicker al abrir**: Aumenta `openDelay` para evitar opens accidentales  
-**No se puede hacer clic en links**: Content debe ser hoverable, verifica que no se cierre muy rápido  
-**Keyboard no funciona**: HoverCard no es accesible por teclado por diseño
-
-## Referencias
-
-- **Radix UI Hover Card**: https://www.radix-ui.com/primitives/docs/components/hover-card
-- **shadcn/ui Hover Card**: https://ui.shadcn.com/docs/components/hover-card
+# Hover Card Component
+
+Card emergente al hacer hover, basado en Radix UI. Ideal para previsualizar contenido, mostrar información adicional de usuarios, links o productos sin necesidad de click.
+
+## Descripción
+
+El componente `HoverCard` muestra contenido adicional al pasar el mouse sobre un elemento.
+
+## Importación
+
+```typescript
+import {
+  HoverCard,
+  HoverCardContent,
+  HoverCardTrigger,
+} from "@adamosuiteservices/ui/hover-card";
+```
+
+## Uso Básico
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger>Hover me</HoverCardTrigger>
+  <HoverCardContent>
+    <div>
+      <h4 className="font-semibold">@nextjs</h4>
+      <p className="text-sm">The React Framework for the Web</p>
+    </div>
+  </HoverCardContent>
+</HoverCard>
+```
+
+## Con Avatar y Detalles
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <a href="https://github.com/vercel" className="underline">
+      @vercel
+    </a>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-80">
+    <div className="flex gap-4">
+      <Avatar>
+        <AvatarImage src="https://github.com/vercel.png" />
+        <AvatarFallback>V</AvatarFallback>
+      </Avatar>
+      <div className="space-y-1">
+        <h4 className="text-sm font-semibold">@vercel</h4>
+        <p className="text-sm">
+          Deploy web projects with the best frontend developer experience.
+        </p>
+      </div>
+    </div>
+  </HoverCardContent>
+</HoverCard>
+```
+
+**Componentes**: 3 (HoverCard, HoverCardTrigger, HoverCardContent)
+
+## Props
+
+| Prop       | Tipo     | Default | Descripción                |
+| ---------- | -------- | ------- | -------------------------- |
+| openDelay  | `number` | `200`   | Delay antes de abrir (ms)  |
+| closeDelay | `number` | `300`   | Delay antes de cerrar (ms) |
+
+## Referencias
+
+- <https://ui.shadcn.com/docs/components/hover-card>
+- <https://www.radix-ui.com/primitives/docs/components/hover-card>
+
+## Patrones de Uso
+
+### Básico
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="link">@nextjs</Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-80">
+    <div className="space-y-2">
+      <h4 className="text-sm font-semibold">@nextjs</h4>
+      <p className="text-sm">
+        The React Framework – created and maintained by @vercel.
+      </p>
+    </div>
+  </HoverCardContent>
+</HoverCard>
+```
+
+### Con Avatar (User Preview)
+
+```tsx
+import {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+} from "@adamosuiteservices/ui/avatar";
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="link">@shadcn</Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-80">
+    <div className="flex justify-between gap-4">
+      <Avatar>
+        <AvatarImage src="https://github.com/shadcn.png" />
+        <AvatarFallback>CN</AvatarFallback>
+      </Avatar>
+      <div className="space-y-1">
+        <h4 className="text-sm font-semibold">@shadcn</h4>
+        <p className="text-sm">
+          Building design systems and web apps. Creator of ui.shadcn.com.
+        </p>
+        <div className="flex items-center pt-2">
+          <Icon symbol="calendar_month" className="mr-2 text-lg opacity-70" />
+          <span className="text-xs text-muted-foreground">
+            Joined December 2021
+          </span>
+        </div>
+      </div>
+    </div>
+  </HoverCardContent>
+</HoverCard>;
+```
+
+### Trigger con Avatar
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Avatar className="cursor-pointer">
+      <AvatarImage src="https://github.com/shadcn.png" />
+      <AvatarFallback>CN</AvatarFallback>
+    </Avatar>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-80">
+    <div className="space-y-3">
+      <div className="flex items-center gap-3">
+        <Avatar>
+          <AvatarImage src="https://github.com/shadcn.png" />
+          <AvatarFallback>CN</AvatarFallback>
+        </Avatar>
+        <div>
+          <h4 className="text-sm font-semibold">shadcn</h4>
+          <p className="text-sm text-muted-foreground">@shadcn</p>
+        </div>
+      </div>
+      <p className="text-sm">Building design systems and web apps.</p>
+      <div className="flex items-center gap-4 text-sm text-muted-foreground">
+        <div className="flex items-center gap-1">
+          <UsersIcon className="h-4 w-4" />
+          <span>2.1k followers</span>
+        </div>
+        <div>Following 180</div>
+      </div>
+    </div>
+  </HoverCardContent>
+</HoverCard>
+```
+
+### Repository Info
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="link" className="font-mono">
+      shadcn/ui
+    </Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-80">
+    <div className="space-y-3">
+      <div>
+        <h4 className="text-sm font-semibold">shadcn/ui</h4>
+        <p className="text-sm text-muted-foreground">
+          Beautifully designed components that you can copy and paste into your
+          apps.
+        </p>
+      </div>
+      <div className="flex items-center gap-4 text-sm text-muted-foreground">
+        <div className="flex items-center gap-1">
+          <Icon symbol="star" className="text-lg" />
+          <span>45.2k</span>
+        </div>
+        <div className="flex items-center gap-1">
+          <Icon symbol="account_tree" className="text-lg" />
+          <span>4.1k</span>
+        </div>
+        <div className="flex items-center gap-1">
+          <div className="h-3 w-3 rounded-full bg-primary" />
+          <span>TypeScript</span>
+        </div>
+      </div>
+    </div>
+  </HoverCardContent>
+</HoverCard>;
+```
+
+### Inline Link Preview
+
+```tsx
+<p className="text-sm leading-relaxed">
+  This paragraph contains an{" "}
+  <HoverCard>
+    <HoverCardTrigger asChild>
+      <a href="#" className="underline underline-offset-4">
+        inline link
+      </a>
+    </HoverCardTrigger>
+    <HoverCardContent className="w-64">
+      <div className="space-y-2">
+        <h4 className="text-sm font-semibold">Link Preview</h4>
+        <p className="text-sm text-muted-foreground">
+          This shows additional context when you hover over the link.
+        </p>
+      </div>
+    </HoverCardContent>
+  </HoverCard>{" "}
+  that shows a preview when hovered.
+</p>
+```
+
+### Product Preview con Imagen
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="link">View product</Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-80">
+    <div className="space-y-3">
+      <img
+        src="https://images.unsplash.com/photo-1588345921523-c2dcdb7f1dcd?w=800"
+        alt="Product preview"
+        className="w-full h-32 object-cover rounded-md"
+      />
+      <div>
+        <h4 className="text-sm font-semibold">Wireless Headphones</h4>
+        <p className="text-sm text-muted-foreground">
+          High-quality wireless headphones with noise cancellation.
+        </p>
+        <p className="text-lg font-bold mt-2">$299.99</p>
+      </div>
+    </div>
+  </HoverCardContent>
+</HoverCard>
+```
+
+### Con Delays Custom
+
+```tsx
+<HoverCard openDelay={1000} closeDelay={500}>
+  <HoverCardTrigger asChild>
+    <Button variant="outline">Hover (1s delay)</Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-64">
+    <div className="space-y-2">
+      <h4 className="text-sm font-semibold">Delayed Hover Card</h4>
+      <p className="text-sm text-muted-foreground">
+        This hover card has a 1 second open delay and 500ms close delay.
+      </p>
+    </div>
+  </HoverCardContent>
+</HoverCard>
+```
+
+### Diferentes Tamaños
+
+```tsx
+{
+  /* Small */
+}
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="outline" size="sm">
+      Small
+    </Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-48">
+    <p className="text-sm">Small hover card content.</p>
+  </HoverCardContent>
+</HoverCard>;
+
+{
+  /* Medium (default) */
+}
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="outline">Medium</Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-64">
+    <p className="text-sm">Medium sized hover card.</p>
+  </HoverCardContent>
+</HoverCard>;
+
+{
+  /* Large */
+}
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="outline" size="lg">
+      Large
+    </Button>
+  </HoverCardTrigger>
+  <HoverCardContent className="w-96">
+    <div className="space-y-2">
+      <h4 className="text-sm font-semibold">Large Hover Card</h4>
+      <p className="text-sm">
+        This is a larger hover card with more content space.
+      </p>
+    </div>
+  </HoverCardContent>
+</HoverCard>;
+```
+
+### Posicionamiento Custom
+
+```tsx
+{
+  /* Top */
+}
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="outline">Top</Button>
+  </HoverCardTrigger>
+  <HoverCardContent side="top" className="w-48">
+    <p className="text-sm">Content positioned above.</p>
+  </HoverCardContent>
+</HoverCard>;
+
+{
+  /* Right */
+}
+<HoverCard>
+  <HoverCardTrigger asChild>
+    <Button variant="outline">Right</Button>
+  </HoverCardTrigger>
+  <HoverCardContent side="right" className="w-48">
+    <p className="text-sm">Content positioned to the right.</p>
+  </HoverCardContent>
+</HoverCard>;
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react";
+
+function App() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <HoverCard open={open} onOpenChange={setOpen}>
+      <HoverCardTrigger asChild>
+        <Button>Controlled</Button>
+      </HoverCardTrigger>
+      <HoverCardContent>
+        <p className="text-sm">Hover card content</p>
+        <Button onClick={() => setOpen(false)}>Close</Button>
+      </HoverCardContent>
+    </HoverCard>
+  );
+}
+```
+
+## Casos de Uso Comunes
+
+**User mentions**: Preview de perfil al hover sobre @username  
+**Link previews**: Información adicional sobre links externos  
+**Product cards**: Preview rápido de productos sin navegar  
+**Repository info**: Stats y detalles de repos en listas  
+**Tooltips ricos**: Información estructurada vs simple tooltip  
+**Avatar hovers**: Detalles de usuario al hover sobre avatar
+
+## Estados y Data Attributes
+
+### Content States
+
+- **Open**: `data-[state=open]` → `animate-in`, `fade-in-0`, `zoom-in-95`
+- **Closed**: `data-[state=closed]` → `animate-out`, `fade-out-0`, `zoom-out-95`
+
+### Animations
+
+- **Slide in**: `data-[side=top|right|bottom|left]` → direccional
+
+## Interacción
+
+- ✅ **Hover to open**: Abre al pasar mouse sobre trigger
+- ✅ **Hover to close**: Cierra al sacar mouse del trigger y content
+- ✅ **Delay**: `openDelay` y `closeDelay` configurables
+- ✅ **Safe area**: Mouse puede moverse entre trigger y content sin cerrar
+- ✅ **Keyboard**: No se abre con teclado (solo mouse/pointer)
+- ✅ **Touch**: No funciona en dispositivos táctiles (solo hover)
+
+## Accesibilidad
+
+- ✅ **ARIA**: `role="tooltip"` o `aria-describedby` según contenido
+- ✅ **Keyboard**: No accesible por teclado (por diseño)
+- ✅ **Screen readers**: Contenido anunciado al abrir
+- ✅ **Focus**: No recibe focus, solo hover
+- ⚠️ **Mobile**: No funciona en touch devices (considerar alternativas)
+
+**Nota**: Para contenido crítico, no uses HoverCard. Usa Dialog o incluye la info directamente.
+
+## Notas de Implementación
+
+- **Basado en Radix UI**: `@radix-ui/react-hover-card`
+- **Hover only**: Solo funciona con mouse/pointer, no touch
+- **Portal rendering**: Content se renderiza en `document.body`
+- **Collision detection**: Auto-ajusta posición si sale del viewport
+- **Safe area**: Permite mover mouse entre trigger y content
+- **No keyboard**: No se puede abrir con teclado (limitación intencional)
+- **Default delays**: 200ms open, 300ms close
+- **Z-index**: 50 para aparecer sobre contenido
+- **Transform origin**: CSS variables de Radix para animaciones
+
+## Diferencias con Tooltip
+
+| Aspecto         | HoverCard                           | Tooltip              |
+| --------------- | ----------------------------------- | -------------------- |
+| **Contenido**   | Rico (texto, imágenes, links)       | Simple (texto plano) |
+| **Interacción** | Hoverable (puede hacer clic dentro) | No interactivo       |
+| **Tamaño**      | Variable, usualmente más grande     | Pequeño, compacto    |
+| **Keyboard**    | No accesible                        | Accesible con focus  |
+| **Uso**         | Previews, información adicional     | Labels, ayuda breve  |
+
+## Troubleshooting
+
+**No aparece en mobile**: HoverCard solo funciona con hover, no en touch devices  
+**Se cierra inmediatamente**: Verifica `closeDelay` o que no haya CSS interfiriendo  
+**No abre**: Verifica que `asChild` esté correcto en trigger con componentes custom  
+**Posición incorrecta**: Ajusta `side`, `align`, `sideOffset` y `alignOffset`  
+**Contenido cortado**: Asegúrate de que el portal no esté limitado por overflow  
+**Flicker al abrir**: Aumenta `openDelay` para evitar opens accidentales  
+**No se puede hacer clic en links**: Content debe ser hoverable, verifica que no se cierre muy rápido  
+**Keyboard no funciona**: HoverCard no es accesible por teclado por diseño
+
+## Referencias
+
+- **Radix UI Hover Card**: https://www.radix-ui.com/primitives/docs/components/hover-card
+- **shadcn/ui Hover Card**: https://ui.shadcn.com/docs/components/hover-card