@adamosuiteservices/ui 2.11.15 → 2.11.16

package/docs/components/ui/popover.md

@@ -1,536 +1,536 @@
-# Popover
-
-Contenido flotante anclado a un trigger, basado en Radix UI. Ideal para forms compactos, settings, información adicional o acciones contextuales.
-
-## Descripción
-
-El componente `Popover` muestra contenido flotante anclado a un elemento trigger.
-
-## Importación
-
-```typescript
-import {
-  Popover,
-  PopoverContent,
-  PopoverTrigger,
-} from "@adamosuiteservices/ui/popover";
-```
-
-## Anatomía
-
-```tsx
-<Popover>
-  <PopoverTrigger>Open</PopoverTrigger>
-  <PopoverContent>Place content for the popover here.</PopoverContent>
-</Popover>
-```
-
-**Componentes**: 4 (Popover, PopoverTrigger, PopoverContent, PopoverAnchor)
-
-## Props Principales
-
-### Popover (Root)
-
-| Prop           | Tipo                      | Default | Descripción                             |
-| -------------- | ------------------------- | ------- | --------------------------------------- |
-| `open`         | `boolean`                 | -       | Estado controlado                       |
-| `defaultOpen`  | `boolean`                 | `false` | Estado inicial no controlado            |
-| `onOpenChange` | `(open: boolean) => void` | -       | Callback cuando cambia estado           |
-| `modal`        | `boolean`                 | `false` | Si es modal (bloquea interacción fuera) |
-
-### PopoverTrigger
-
-| Prop        | Tipo      | Descripción                                        |
-| ----------- | --------- | -------------------------------------------------- |
-| `asChild`   | `boolean` | Pasa props al child en lugar de renderizar wrapper |
-| `className` | `string`  | Clases CSS adicionales                             |
-
-### PopoverContent
-
-| Prop          | Tipo                                     | Default    | Descripción                      |
-| ------------- | ---------------------------------------- | ---------- | -------------------------------- |
-| `side`        | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Lado donde aparece               |
-| `align`       | `"start" \| "center" \| "end"`           | `"center"` | Alineamiento horizontal/vertical |
-| `sideOffset`  | `number`                                 | `4`        | Distancia desde trigger (px)     |
-| `alignOffset` | `number`                                 | `0`        | Offset del alineamiento          |
-| `className`   | `string`                                 | -          | Clases CSS adicionales           |
-
-**Estilos default**: `w-72`, `p-4`, `rounded-md`, `border`, `shadow-md`, `z-50`
-
-### PopoverAnchor
-
-| Prop        | Tipo      | Descripción            |
-| ----------- | --------- | ---------------------- |
-| `asChild`   | `boolean` | Pasa props al child    |
-| `className` | `string`  | Clases CSS adicionales |
-
-**Uso**: Ancla popover a elemento diferente del trigger
-
-## Patrones de Uso
-
-### Básico
-
-```tsx
-<Popover>
-  <PopoverTrigger asChild>
-    <Button variant="outline">Open popover</Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-80">
-    <div className="grid gap-4">
-      <div className="space-y-2">
-        <h4 className="font-medium leading-none">Dimensions</h4>
-        <p className="text-sm text-muted-foreground">
-          Set the dimensions for the layer.
-        </p>
-      </div>
-      <div className="grid gap-2">
-        <div className="grid grid-cols-3 items-center gap-4">
-          <Label htmlFor="width">Width</Label>
-          <Input id="width" defaultValue="100%" className="col-span-2 h-8" />
-        </div>
-        <div className="grid grid-cols-3 items-center gap-4">
-          <Label htmlFor="height">Height</Label>
-          <Input id="height" defaultValue="25px" className="col-span-2 h-8" />
-        </div>
-      </div>
-    </div>
-  </PopoverContent>
-</Popover>
-```
-
-### Simple
-
-```tsx
-<Popover>
-  <PopoverTrigger asChild>
-    <Button variant="outline">Click me</Button>
-  </PopoverTrigger>
-  <PopoverContent>
-    <p>This is a simple popover with just text content.</p>
-  </PopoverContent>
-</Popover>
-```
-
-### Con User Profile
-
-```tsx
-import {
-  Avatar,
-  AvatarImage,
-  AvatarFallback,
-} from "@adamosuiteservices/ui/avatar";
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<Popover>
-  <PopoverTrigger asChild>
-    <Button variant="ghost" className="h-auto p-2">
-      <Avatar className="h-8 w-8">
-        <AvatarImage src="https://github.com/shadcn.png" />
-        <AvatarFallback>SC</AvatarFallback>
-      </Avatar>
-    </Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-80">
-    <div className="flex gap-4">
-      <Avatar>
-        <AvatarImage src="https://github.com/shadcn.png" />
-        <AvatarFallback>SC</AvatarFallback>
-      </Avatar>
-      <div className="space-y-1">
-        <h4 className="text-sm font-semibold">@shadcn</h4>
-        <p className="text-sm">
-          The React Framework – created and maintained by @vercel.
-        </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>
-  </PopoverContent>
-</Popover>;
-```
-
-### Con Settings
-
-```tsx
-import { Switch } from "@adamosuiteservices/ui/switch";
-import { Separator } from "@adamosuiteservices/ui/separator";
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<Popover>
-  <PopoverTrigger asChild>
-    <Button variant="outline" size="icon">
-      <Icon symbol="settings" className="text-lg" />
-    </Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-80">
-    <div className="grid gap-4">
-      <div className="space-y-2">
-        <h4 className="font-medium leading-none">Settings</h4>
-        <p className="text-sm text-muted-foreground">
-          Configure your preferences
-        </p>
-      </div>
-      <div className="grid gap-2">
-        <div className="flex items-center justify-between">
-          <Label htmlFor="notifications">Push notifications</Label>
-          <Switch id="notifications" />
-        </div>
-        <div className="flex items-center justify-between">
-          <Label htmlFor="emails">Email updates</Label>
-          <Switch id="emails" defaultChecked />
-        </div>
-      </div>
-      <Separator />
-      <div className="flex justify-between">
-        <Button variant="outline" size="sm">
-          Cancel
-        </Button>
-        <Button size="sm">Save changes</Button>
-      </div>
-    </div>
-  </PopoverContent>
-</Popover>;
-```
-
-### Con Calendar
-
-```tsx
-import { useState } from "react";
-import { Calendar } from "@adamosuiteservices/ui/calendar";
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-function App() {
-  const [date, setDate] = useState<Date | undefined>(new Date());
-
-  return (
-    <Popover>
-      <PopoverTrigger asChild>
-        <Button
-          variant="outline"
-          className={cn(
-            "w-[240px] justify-start text-left font-normal",
-            !date && "text-muted-foreground"
-          )}
-        >
-          <Icon symbol="calendar_month" className="mr-2 text-lg" />
-          {date ? date.toLocaleDateString() : "Pick a date"}
-        </Button>
-      </PopoverTrigger>
-      <PopoverContent className="w-auto p-0" align="start">
-        <Calendar
-          mode="single"
-          selected={date}
-          onSelect={setDate}
-          initialFocus
-        />
-      </PopoverContent>
-    </Popover>
-  );
-}
-```
-
-### Con Counter
-
-```tsx
-import { useState } from "react";
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-function App() {
-  const [count, setCount] = useState(0);
-
-  return (
-    <Popover>
-      <PopoverTrigger asChild>
-        <Button variant="outline">Counter: {count}</Button>
-      </PopoverTrigger>
-      <PopoverContent className="w-64">
-        <div className="grid gap-4">
-          <div className="space-y-2">
-            <h4 className="font-medium leading-none">Counter Control</h4>
-            <p className="text-sm text-muted-foreground">
-              Adjust the counter value
-            </p>
-          </div>
-          <div className="flex items-center justify-center space-x-2">
-            <Button
-              variant="outline"
-              size="icon"
-              onClick={() => setCount(Math.max(0, count - 1))}
-              disabled={count === 0}
-            >
-              <Icon symbol="remove" className="text-lg" />
-            </Button>
-            <div className="flex items-center justify-center w-16 h-10 border rounded">
-              {count}
-            </div>
-            <Button
-              variant="outline"
-              size="icon"
-              onClick={() => setCount(count + 1)}
-            >
-              <Icon symbol="add" className="text-lg" />
-            </Button>
-          </div>
-          <div className="flex gap-2">
-            <Button variant="outline" size="sm" onClick={() => setCount(0)}>
-              Reset
-            </Button>
-            <Button size="sm" onClick={() => setCount(10)}>
-              Set to 10
-            </Button>
-          </div>
-        </div>
-      </PopoverContent>
-    </Popover>
-  );
-}
-```
-
-### Con Info Icon
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<div className="flex items-center gap-4">
-  <span>Complex Feature</span>
-  <Popover>
-    <PopoverTrigger asChild>
-      <Button variant="ghost" size="icon" className="h-5 w-5">
-        <Icon symbol="info" className="text-sm" />
-      </Button>
-    </PopoverTrigger>
-    <PopoverContent className="w-80">
-      <div className="space-y-3">
-        <div className="flex items-center gap-2">
-          <Icon symbol="error" className="text-lg text-primary" />
-          <h4 className="font-medium">About this feature</h4>
-        </div>
-        <p className="text-sm text-muted-foreground">
-          This is a complex feature that requires additional explanation.
-        </p>
-        <div className="space-y-2">
-          <h5 className="text-sm font-medium">Key benefits:</h5>
-          <ul className="text-sm space-y-1 text-muted-foreground">
-            <li>• Improved performance</li>
-            <li>• Better user experience</li>
-            <li>• Advanced customization</li>
-          </ul>
-        </div>
-      </div>
-    </PopoverContent>
-  </Popover>
-</div>;
-```
-
-### Con Notifications
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-import { Badge } from "@adamosuiteservices/ui/badge";
-import { Separator } from "@adamosuiteservices/ui/separator";
-
-<Popover>
-  <PopoverTrigger asChild>
-    <Button variant="outline" size="icon" className="relative">
-      <Icon symbol="mail" className="text-lg" />
-      <Badge
-        className="absolute -top-2 -right-2 h-5 w-5 p-0 flex items-center justify-center"
-        variant="destructive"
-      >
-        3
-      </Badge>
-    </Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-80">
-    <div className="space-y-3">
-      <div className="flex items-center justify-between">
-        <h4 className="font-medium">Notifications</h4>
-        <Button variant="ghost" size="sm">
-          Mark all read
-        </Button>
-      </div>
-      <div className="space-y-2">
-        <div className="flex items-start gap-3 p-2 rounded hover:bg-muted bg-muted/50">
-          <div className="flex-1">
-            <p className="text-sm font-medium">New message</p>
-            <p className="text-xs text-muted-foreground">2 min ago</p>
-          </div>
-          <div className="h-2 w-2 bg-primary rounded-full mt-1" />
-        </div>
-      </div>
-      <Separator />
-      <Button variant="outline" size="sm" className="w-full">
-        View all notifications
-      </Button>
-    </div>
-  </PopoverContent>
-</Popover>;
-```
-
-### Posicionamiento Custom
-
-```tsx
-{
-  /* Top */
-}
-<Popover>
-  <PopoverTrigger asChild>
-    <Button variant="outline">Top</Button>
-  </PopoverTrigger>
-  <PopoverContent side="top">
-    <p>This popover appears on top</p>
-  </PopoverContent>
-</Popover>;
-
-{
-  /* Right */
-}
-<Popover>
-  <PopoverTrigger asChild>
-    <Button variant="outline">Right</Button>
-  </PopoverTrigger>
-  <PopoverContent side="right">
-    <p>This popover appears on the right</p>
-  </PopoverContent>
-</Popover>;
-
-{
-  /* Start aligned */
-}
-<Popover>
-  <PopoverTrigger asChild>
-    <Button variant="outline">Start aligned</Button>
-  </PopoverTrigger>
-  <PopoverContent align="start">
-    <p>This popover is aligned to the start</p>
-  </PopoverContent>
-</Popover>;
-```
-
-### Con Anchor
-
-```tsx
-<div className="space-y-4">
-  <p>
-    This is some text with an{" "}
-    <Popover>
-      <PopoverAnchor asChild>
-        <span className="underline cursor-pointer">anchored element</span>
-      </PopoverAnchor>
-      <PopoverTrigger asChild>
-        <Button variant="outline" className="ml-2">
-          Show info
-        </Button>
-      </PopoverTrigger>
-      <PopoverContent>
-        <p>This popover is anchored to the underlined text above!</p>
-      </PopoverContent>
-    </Popover>
-  </p>
-</div>
-```
-
-### Controlado
-
-```tsx
-import { useState } from "react";
-
-function App() {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <Popover open={open} onOpenChange={setOpen}>
-      <PopoverTrigger asChild>
-        <Button variant="outline">Toggle</Button>
-      </PopoverTrigger>
-      <PopoverContent>
-        <div className="space-y-2">
-          <p>Controlled popover content</p>
-          <Button onClick={() => setOpen(false)}>Close</Button>
-        </div>
-      </PopoverContent>
-    </Popover>
-  );
-}
-```
-
-## Casos de Uso Comunes
-
-**Date pickers**: Mostrar calendar en popover  
-**Settings**: Controles compactos de configuración  
-**User profiles**: Preview de perfiles al hover/click  
-**Notifications**: Lista de notificaciones  
-**Quick actions**: Acciones contextuales sin modal  
-**Info tooltips**: Información rica vs tooltip simple  
-**Forms**: Formularios compactos inline
-
-## Estados y Data Attributes
-
-### PopoverContent 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`
-
-### Side Animations
-
-- **Top**: `data-[side=top]` → `slide-in-from-bottom-2`
-- **Right**: `data-[side=right]` → `slide-in-from-left-2`
-- **Bottom**: `data-[side=bottom]` → `slide-in-from-top-2`
-- **Left**: `data-[side=left]` → `slide-in-from-right-2`
-
-## Interacción
-
-- ✅ **Click to open**: Click en trigger abre popover
-- ✅ **Click outside**: Click fuera cierra popover (si no es modal)
-- ✅ **Escape**: Presionar Esc cierra popover
-- ✅ **Focus trap**: Si `modal=true`, foco queda atrapado dentro
-- ✅ **Keyboard**: Tab navega entre elementos internos
-
-## Accesibilidad
-
-- ✅ **ARIA**: `role="dialog"`, `aria-labelledby`, `aria-describedby` según contenido
-- ✅ **Focus management**: Focus automático al abrir
-- ✅ **Keyboard**: Esc para cerrar, Tab para navegar
-- ✅ **Portal**: Renderiza en `document.body` para evitar problemas de z-index
-- ✅ **Modal mode**: `modal=true` para bloquear interacción fuera del popover
-
-## Notas de Implementación
-
-- **Radix UI**: Basado en `@radix-ui/react-popover`
-- **Portal rendering**: Content se renderiza en `document.body`
-- **Collision detection**: Auto-ajusta posición si sale del viewport
-- **Transform origin**: CSS variables de Radix para animaciones
-- **Default width**: `w-72` (288px)
-- **Default padding**: `p-4`
-- **Z-index**: 50 para aparecer sobre contenido
-- **Modal**: Por defecto `modal=false` (permite interacción fuera)
-
-## Diferencias con Dialog y HoverCard
-
-| Aspecto          | Popover           | Dialog                | HoverCard       |
-| ---------------- | ----------------- | --------------------- | --------------- |
-| **Trigger**      | Click             | Click                 | Hover           |
-| **Modal**        | Opcional          | Siempre               | No              |
-| **Backdrop**     | Opcional          | Sí                    | No              |
-| **Contenido**    | Compacto          | Extenso               | Preview         |
-| **Persistencia** | Hasta click fuera | Hasta close explícito | Hasta hover out |
-
-## Troubleshooting
-
-**No aparece**: Verifica que PopoverContent esté dentro de Popover root  
-**Posición incorrecta**: Ajusta `side`, `align`, `sideOffset` y `alignOffset`  
-**Contenido cortado**: Verifica que no haya `overflow: hidden` en containers  
-**No cierra**: Si `modal=true`, solo cierra con Esc o close explícito  
-**Focus no funciona**: Content debe tener elementos focuseables  
-**Backdrop no se ve**: Popover no tiene backdrop por defecto, usa `modal=true` y customiza  
-**Z-index issues**: Content usa portal, debe aparecer sobre todo  
-**Anchor no funciona**: PopoverAnchor debe estar dentro de Popover root
-
-## Referencias
-
-- **Radix UI Popover**: <https://www.radix-ui.com/primitives/docs/components/popover>
-- **shadcn/ui Popover**: <https://ui.shadcn.com/docs/components/popover>
+# Popover
+
+Contenido flotante anclado a un trigger, basado en Radix UI. Ideal para forms compactos, settings, información adicional o acciones contextuales.
+
+## Descripción
+
+El componente `Popover` muestra contenido flotante anclado a un elemento trigger.
+
+## Importación
+
+```typescript
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from "@adamosuiteservices/ui/popover";
+```
+
+## Anatomía
+
+```tsx
+<Popover>
+  <PopoverTrigger>Open</PopoverTrigger>
+  <PopoverContent>Place content for the popover here.</PopoverContent>
+</Popover>
+```
+
+**Componentes**: 4 (Popover, PopoverTrigger, PopoverContent, PopoverAnchor)
+
+## Props Principales
+
+### Popover (Root)
+
+| Prop           | Tipo                      | Default | Descripción                             |
+| -------------- | ------------------------- | ------- | --------------------------------------- |
+| `open`         | `boolean`                 | -       | Estado controlado                       |
+| `defaultOpen`  | `boolean`                 | `false` | Estado inicial no controlado            |
+| `onOpenChange` | `(open: boolean) => void` | -       | Callback cuando cambia estado           |
+| `modal`        | `boolean`                 | `false` | Si es modal (bloquea interacción fuera) |
+
+### PopoverTrigger
+
+| Prop        | Tipo      | Descripción                                        |
+| ----------- | --------- | -------------------------------------------------- |
+| `asChild`   | `boolean` | Pasa props al child en lugar de renderizar wrapper |
+| `className` | `string`  | Clases CSS adicionales                             |
+
+### PopoverContent
+
+| Prop          | Tipo                                     | Default    | Descripción                      |
+| ------------- | ---------------------------------------- | ---------- | -------------------------------- |
+| `side`        | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Lado donde aparece               |
+| `align`       | `"start" \| "center" \| "end"`           | `"center"` | Alineamiento horizontal/vertical |
+| `sideOffset`  | `number`                                 | `4`        | Distancia desde trigger (px)     |
+| `alignOffset` | `number`                                 | `0`        | Offset del alineamiento          |
+| `className`   | `string`                                 | -          | Clases CSS adicionales           |
+
+**Estilos default**: `w-72`, `p-4`, `rounded-md`, `border`, `shadow-md`, `z-50`
+
+### PopoverAnchor
+
+| Prop        | Tipo      | Descripción            |
+| ----------- | --------- | ---------------------- |
+| `asChild`   | `boolean` | Pasa props al child    |
+| `className` | `string`  | Clases CSS adicionales |
+
+**Uso**: Ancla popover a elemento diferente del trigger
+
+## Patrones de Uso
+
+### Básico
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">Open popover</Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-80">
+    <div className="grid gap-4">
+      <div className="space-y-2">
+        <h4 className="font-medium leading-none">Dimensions</h4>
+        <p className="text-sm text-muted-foreground">
+          Set the dimensions for the layer.
+        </p>
+      </div>
+      <div className="grid gap-2">
+        <div className="grid grid-cols-3 items-center gap-4">
+          <Label htmlFor="width">Width</Label>
+          <Input id="width" defaultValue="100%" className="col-span-2 h-8" />
+        </div>
+        <div className="grid grid-cols-3 items-center gap-4">
+          <Label htmlFor="height">Height</Label>
+          <Input id="height" defaultValue="25px" className="col-span-2 h-8" />
+        </div>
+      </div>
+    </div>
+  </PopoverContent>
+</Popover>
+```
+
+### Simple
+
+```tsx
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">Click me</Button>
+  </PopoverTrigger>
+  <PopoverContent>
+    <p>This is a simple popover with just text content.</p>
+  </PopoverContent>
+</Popover>
+```
+
+### Con User Profile
+
+```tsx
+import {
+  Avatar,
+  AvatarImage,
+  AvatarFallback,
+} from "@adamosuiteservices/ui/avatar";
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="ghost" className="h-auto p-2">
+      <Avatar className="h-8 w-8">
+        <AvatarImage src="https://github.com/shadcn.png" />
+        <AvatarFallback>SC</AvatarFallback>
+      </Avatar>
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-80">
+    <div className="flex gap-4">
+      <Avatar>
+        <AvatarImage src="https://github.com/shadcn.png" />
+        <AvatarFallback>SC</AvatarFallback>
+      </Avatar>
+      <div className="space-y-1">
+        <h4 className="text-sm font-semibold">@shadcn</h4>
+        <p className="text-sm">
+          The React Framework – created and maintained by @vercel.
+        </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>
+  </PopoverContent>
+</Popover>;
+```
+
+### Con Settings
+
+```tsx
+import { Switch } from "@adamosuiteservices/ui/switch";
+import { Separator } from "@adamosuiteservices/ui/separator";
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline" size="icon">
+      <Icon symbol="settings" className="text-lg" />
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-80">
+    <div className="grid gap-4">
+      <div className="space-y-2">
+        <h4 className="font-medium leading-none">Settings</h4>
+        <p className="text-sm text-muted-foreground">
+          Configure your preferences
+        </p>
+      </div>
+      <div className="grid gap-2">
+        <div className="flex items-center justify-between">
+          <Label htmlFor="notifications">Push notifications</Label>
+          <Switch id="notifications" />
+        </div>
+        <div className="flex items-center justify-between">
+          <Label htmlFor="emails">Email updates</Label>
+          <Switch id="emails" defaultChecked />
+        </div>
+      </div>
+      <Separator />
+      <div className="flex justify-between">
+        <Button variant="outline" size="sm">
+          Cancel
+        </Button>
+        <Button size="sm">Save changes</Button>
+      </div>
+    </div>
+  </PopoverContent>
+</Popover>;
+```
+
+### Con Calendar
+
+```tsx
+import { useState } from "react";
+import { Calendar } from "@adamosuiteservices/ui/calendar";
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+function App() {
+  const [date, setDate] = useState<Date | undefined>(new Date());
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button
+          variant="outline"
+          className={cn(
+            "w-[240px] justify-start text-left font-normal",
+            !date && "text-muted-foreground"
+          )}
+        >
+          <Icon symbol="calendar_month" className="mr-2 text-lg" />
+          {date ? date.toLocaleDateString() : "Pick a date"}
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-auto p-0" align="start">
+        <Calendar
+          mode="single"
+          selected={date}
+          onSelect={setDate}
+          initialFocus
+        />
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+### Con Counter
+
+```tsx
+import { useState } from "react";
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+function App() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <Button variant="outline">Counter: {count}</Button>
+      </PopoverTrigger>
+      <PopoverContent className="w-64">
+        <div className="grid gap-4">
+          <div className="space-y-2">
+            <h4 className="font-medium leading-none">Counter Control</h4>
+            <p className="text-sm text-muted-foreground">
+              Adjust the counter value
+            </p>
+          </div>
+          <div className="flex items-center justify-center space-x-2">
+            <Button
+              variant="outline"
+              size="icon"
+              onClick={() => setCount(Math.max(0, count - 1))}
+              disabled={count === 0}
+            >
+              <Icon symbol="remove" className="text-lg" />
+            </Button>
+            <div className="flex items-center justify-center w-16 h-10 border rounded">
+              {count}
+            </div>
+            <Button
+              variant="outline"
+              size="icon"
+              onClick={() => setCount(count + 1)}
+            >
+              <Icon symbol="add" className="text-lg" />
+            </Button>
+          </div>
+          <div className="flex gap-2">
+            <Button variant="outline" size="sm" onClick={() => setCount(0)}>
+              Reset
+            </Button>
+            <Button size="sm" onClick={() => setCount(10)}>
+              Set to 10
+            </Button>
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+### Con Info Icon
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<div className="flex items-center gap-4">
+  <span>Complex Feature</span>
+  <Popover>
+    <PopoverTrigger asChild>
+      <Button variant="ghost" size="icon" className="h-5 w-5">
+        <Icon symbol="info" className="text-sm" />
+      </Button>
+    </PopoverTrigger>
+    <PopoverContent className="w-80">
+      <div className="space-y-3">
+        <div className="flex items-center gap-2">
+          <Icon symbol="error" className="text-lg text-primary" />
+          <h4 className="font-medium">About this feature</h4>
+        </div>
+        <p className="text-sm text-muted-foreground">
+          This is a complex feature that requires additional explanation.
+        </p>
+        <div className="space-y-2">
+          <h5 className="text-sm font-medium">Key benefits:</h5>
+          <ul className="text-sm space-y-1 text-muted-foreground">
+            <li>• Improved performance</li>
+            <li>• Better user experience</li>
+            <li>• Advanced customization</li>
+          </ul>
+        </div>
+      </div>
+    </PopoverContent>
+  </Popover>
+</div>;
+```
+
+### Con Notifications
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+import { Badge } from "@adamosuiteservices/ui/badge";
+import { Separator } from "@adamosuiteservices/ui/separator";
+
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline" size="icon" className="relative">
+      <Icon symbol="mail" className="text-lg" />
+      <Badge
+        className="absolute -top-2 -right-2 h-5 w-5 p-0 flex items-center justify-center"
+        variant="destructive"
+      >
+        3
+      </Badge>
+    </Button>
+  </PopoverTrigger>
+  <PopoverContent className="w-80">
+    <div className="space-y-3">
+      <div className="flex items-center justify-between">
+        <h4 className="font-medium">Notifications</h4>
+        <Button variant="ghost" size="sm">
+          Mark all read
+        </Button>
+      </div>
+      <div className="space-y-2">
+        <div className="flex items-start gap-3 p-2 rounded hover:bg-muted bg-muted/50">
+          <div className="flex-1">
+            <p className="text-sm font-medium">New message</p>
+            <p className="text-xs text-muted-foreground">2 min ago</p>
+          </div>
+          <div className="h-2 w-2 bg-primary rounded-full mt-1" />
+        </div>
+      </div>
+      <Separator />
+      <Button variant="outline" size="sm" className="w-full">
+        View all notifications
+      </Button>
+    </div>
+  </PopoverContent>
+</Popover>;
+```
+
+### Posicionamiento Custom
+
+```tsx
+{
+  /* Top */
+}
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">Top</Button>
+  </PopoverTrigger>
+  <PopoverContent side="top">
+    <p>This popover appears on top</p>
+  </PopoverContent>
+</Popover>;
+
+{
+  /* Right */
+}
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">Right</Button>
+  </PopoverTrigger>
+  <PopoverContent side="right">
+    <p>This popover appears on the right</p>
+  </PopoverContent>
+</Popover>;
+
+{
+  /* Start aligned */
+}
+<Popover>
+  <PopoverTrigger asChild>
+    <Button variant="outline">Start aligned</Button>
+  </PopoverTrigger>
+  <PopoverContent align="start">
+    <p>This popover is aligned to the start</p>
+  </PopoverContent>
+</Popover>;
+```
+
+### Con Anchor
+
+```tsx
+<div className="space-y-4">
+  <p>
+    This is some text with an{" "}
+    <Popover>
+      <PopoverAnchor asChild>
+        <span className="underline cursor-pointer">anchored element</span>
+      </PopoverAnchor>
+      <PopoverTrigger asChild>
+        <Button variant="outline" className="ml-2">
+          Show info
+        </Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <p>This popover is anchored to the underlined text above!</p>
+      </PopoverContent>
+    </Popover>
+  </p>
+</div>
+```
+
+### Controlado
+
+```tsx
+import { useState } from "react";
+
+function App() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Popover open={open} onOpenChange={setOpen}>
+      <PopoverTrigger asChild>
+        <Button variant="outline">Toggle</Button>
+      </PopoverTrigger>
+      <PopoverContent>
+        <div className="space-y-2">
+          <p>Controlled popover content</p>
+          <Button onClick={() => setOpen(false)}>Close</Button>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+## Casos de Uso Comunes
+
+**Date pickers**: Mostrar calendar en popover  
+**Settings**: Controles compactos de configuración  
+**User profiles**: Preview de perfiles al hover/click  
+**Notifications**: Lista de notificaciones  
+**Quick actions**: Acciones contextuales sin modal  
+**Info tooltips**: Información rica vs tooltip simple  
+**Forms**: Formularios compactos inline
+
+## Estados y Data Attributes
+
+### PopoverContent 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`
+
+### Side Animations
+
+- **Top**: `data-[side=top]` → `slide-in-from-bottom-2`
+- **Right**: `data-[side=right]` → `slide-in-from-left-2`
+- **Bottom**: `data-[side=bottom]` → `slide-in-from-top-2`
+- **Left**: `data-[side=left]` → `slide-in-from-right-2`
+
+## Interacción
+
+- ✅ **Click to open**: Click en trigger abre popover
+- ✅ **Click outside**: Click fuera cierra popover (si no es modal)
+- ✅ **Escape**: Presionar Esc cierra popover
+- ✅ **Focus trap**: Si `modal=true`, foco queda atrapado dentro
+- ✅ **Keyboard**: Tab navega entre elementos internos
+
+## Accesibilidad
+
+- ✅ **ARIA**: `role="dialog"`, `aria-labelledby`, `aria-describedby` según contenido
+- ✅ **Focus management**: Focus automático al abrir
+- ✅ **Keyboard**: Esc para cerrar, Tab para navegar
+- ✅ **Portal**: Renderiza en `document.body` para evitar problemas de z-index
+- ✅ **Modal mode**: `modal=true` para bloquear interacción fuera del popover
+
+## Notas de Implementación
+
+- **Radix UI**: Basado en `@radix-ui/react-popover`
+- **Portal rendering**: Content se renderiza en `document.body`
+- **Collision detection**: Auto-ajusta posición si sale del viewport
+- **Transform origin**: CSS variables de Radix para animaciones
+- **Default width**: `w-72` (288px)
+- **Default padding**: `p-4`
+- **Z-index**: 50 para aparecer sobre contenido
+- **Modal**: Por defecto `modal=false` (permite interacción fuera)
+
+## Diferencias con Dialog y HoverCard
+
+| Aspecto          | Popover           | Dialog                | HoverCard       |
+| ---------------- | ----------------- | --------------------- | --------------- |
+| **Trigger**      | Click             | Click                 | Hover           |
+| **Modal**        | Opcional          | Siempre               | No              |
+| **Backdrop**     | Opcional          | Sí                    | No              |
+| **Contenido**    | Compacto          | Extenso               | Preview         |
+| **Persistencia** | Hasta click fuera | Hasta close explícito | Hasta hover out |
+
+## Troubleshooting
+
+**No aparece**: Verifica que PopoverContent esté dentro de Popover root  
+**Posición incorrecta**: Ajusta `side`, `align`, `sideOffset` y `alignOffset`  
+**Contenido cortado**: Verifica que no haya `overflow: hidden` en containers  
+**No cierra**: Si `modal=true`, solo cierra con Esc o close explícito  
+**Focus no funciona**: Content debe tener elementos focuseables  
+**Backdrop no se ve**: Popover no tiene backdrop por defecto, usa `modal=true` y customiza  
+**Z-index issues**: Content usa portal, debe aparecer sobre todo  
+**Anchor no funciona**: PopoverAnchor debe estar dentro de Popover root
+
+## Referencias
+
+- **Radix UI Popover**: <https://www.radix-ui.com/primitives/docs/components/popover>
+- **shadcn/ui Popover**: <https://ui.shadcn.com/docs/components/popover>