@adamosuiteservices/ui 2.11.14 → 2.11.16

package/docs/components/ui/context-menu.md

@@ -1,540 +1,540 @@
-# Context Menu
-
-Menú contextual al hacer clic derecho, basado en Radix UI. Soporta submenús, checkboxes, radio groups, separadores, y shortcuts visuales. Útil para acciones contextuales en elementos.
-
-## Importación
-
-```tsx
-import {
-  ContextMenu,
-  ContextMenuTrigger,
-  ContextMenuContent,
-  ContextMenuItem,
-  ContextMenuCheckboxItem,
-  ContextMenuRadioGroup,
-  ContextMenuRadioItem,
-  ContextMenuLabel,
-  ContextMenuSeparator,
-  ContextMenuShortcut,
-  ContextMenuSub,
-  ContextMenuSubContent,
-  ContextMenuSubTrigger,
-  ContextMenuGroup,
-  ContextMenuPortal,
-} from "@adamosuiteservices/ui/context-menu";
-```
-
-## Anatomía
-
-```tsx
-<ContextMenu>
-  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
-  <ContextMenuContent>
-    <ContextMenuLabel>Actions</ContextMenuLabel>
-    <ContextMenuItem>
-      Edit
-      <ContextMenuShortcut>⌘E</ContextMenuShortcut>
-    </ContextMenuItem>
-    <ContextMenuSeparator />
-    <ContextMenuCheckboxItem checked={showBookmarks}>
-      Show Bookmarks
-    </ContextMenuCheckboxItem>
-    <ContextMenuSeparator />
-    <ContextMenuSub>
-      <ContextMenuSubTrigger>More Options</ContextMenuSubTrigger>
-      <ContextMenuSubContent>
-        <ContextMenuItem>Export</ContextMenuItem>
-      </ContextMenuSubContent>
-    </ContextMenuSub>
-  </ContextMenuContent>
-</ContextMenu>
-```
-
-**Componentes**: 14 (Trigger, Content, Item, CheckboxItem, RadioGroup, RadioItem, Label, Separator, Shortcut, Sub, SubTrigger, SubContent, Group, Portal)
-
-## Props Principales
-
-### ContextMenu (Root)
-
-| Prop           | Tipo                      | Default | Descripción                                        |
-| -------------- | ------------------------- | ------- | -------------------------------------------------- |
-| `onOpenChange` | `(open: boolean) => void` | -       | Callback cuando cambia estado del menú             |
-| `modal`        | `boolean`                 | `true`  | Comportamiento modal (bloquea interacción externa) |
-
-### ContextMenuTrigger
-
-| Prop        | Tipo      | Descripción                                        |
-| ----------- | --------- | -------------------------------------------------- |
-| `asChild`   | `boolean` | Pasa props al child en lugar de renderizar wrapper |
-| `disabled`  | `boolean` | Desactiva el trigger                               |
-| `className` | `string`  | Clases CSS adicionales                             |
-
-### ContextMenuContent
-
-| Prop                   | Tipo              | Default | Descripción                                   |
-| ---------------------- | ----------------- | ------- | --------------------------------------------- |
-| `alignOffset`          | `number`          | `0`     | Offset del alineamiento                       |
-| `sideOffset`           | `number`          | `0`     | Distancia desde trigger                       |
-| `className`            | `string`          | -       | Clases CSS adicionales                        |
-| `loop`                 | `boolean`         | `false` | Navegación circular con arrow keys            |
-| `onCloseAutoFocus`     | `(event) => void` | -       | Callback al cerrar (antes de restaurar focus) |
-| `onEscapeKeyDown`      | `(event) => void` | -       | Callback al presionar Escape                  |
-| `onPointerDownOutside` | `(event) => void` | -       | Callback al hacer clic fuera                  |
-
-**Estilos default**: `min-w-[8rem]`, `max-h-(--radix-context-menu-content-available-height)`, scroll automático, `z-50`
-
-### ContextMenuItem
-
-| Prop        | Tipo                         | Default     | Descripción                             |
-| ----------- | ---------------------------- | ----------- | --------------------------------------- |
-| `onSelect`  | `(event) => void`            | -           | Callback al seleccionar (click o Enter) |
-| `disabled`  | `boolean`                    | `false`     | Desactiva el item                       |
-| `inset`     | `boolean`                    | `false`     | Agrega padding izquierdo (`pl-8`)       |
-| `variant`   | `"default" \| "destructive"` | `"default"` | Estilo del item                         |
-| `className` | `string`                     | -           | Clases CSS adicionales                  |
-
-**Variantes**:
-
-- `default`: `focus:bg-accent`, `focus:text-accent-foreground`
-- `destructive`: `text-destructive`, `focus:bg-destructive/10`, `focus:text-destructive`
-
-### ContextMenuCheckboxItem
-
-| Prop              | Tipo                         | Descripción                |
-| ----------------- | ---------------------------- | -------------------------- |
-| `checked`         | `boolean \| "indeterminate"` | Estado del checkbox        |
-| `onCheckedChange` | `(checked: boolean) => void` | Callback al cambiar estado |
-| `disabled`        | `boolean`                    | Desactiva el item          |
-| `className`       | `string`                     | Clases CSS adicionales     |
-
-**Indicador**: Check icon (Material Symbol "check") automático cuando `checked={true}`, posicionado con `pl-8`
-
-### ContextMenuRadioGroup
-
-| Prop            | Tipo                      | Descripción               |
-| --------------- | ------------------------- | ------------------------- |
-| `value`         | `string`                  | Valor seleccionado        |
-| `onValueChange` | `(value: string) => void` | Callback al cambiar valor |
-
-### ContextMenuRadioItem
-
-| Prop        | Tipo      | Descripción            |
-| ----------- | --------- | ---------------------- |
-| `value`     | `string`  | Valor único del item   |
-| `disabled`  | `boolean` | Desactiva el item      |
-| `className` | `string`  | Clases CSS adicionales |
-
-**Indicador**: Circle icon (Material Symbol "circle") automático cuando seleccionado, posicionado con `pl-8`
-
-### ContextMenuSub
-
-| Prop           | Tipo                      | Descripción                   |
-| -------------- | ------------------------- | ----------------------------- |
-| `open`         | `boolean`                 | Estado controlado del submenú |
-| `onOpenChange` | `(open: boolean) => void` | Callback al cambiar estado    |
-
-### ContextMenuSubTrigger
-
-| Prop        | Tipo      | Descripción                |
-| ----------- | --------- | -------------------------- |
-| `disabled`  | `boolean` | Desactiva el trigger       |
-| `inset`     | `boolean` | Padding izquierdo (`pl-8`) |
-| `className` | `string`  | Clases CSS adicionales     |
-
-**Indicador**: Chevron right icon (Material Symbol "chevron_right") automático con `ml-auto`
-
-### ContextMenuLabel
-
-| Prop        | Tipo      | Descripción                |
-| ----------- | --------- | -------------------------- |
-| `inset`     | `boolean` | Padding izquierdo (`pl-8`) |
-| `className` | `string`  | Clases CSS adicionales     |
-
-**Estilos**: `text-foreground`, `font-medium`
-
-### ContextMenuShortcut
-
-| Prop        | Tipo     | Descripción            |
-| ----------- | -------- | ---------------------- |
-| `className` | `string` | Clases CSS adicionales |
-
-**Estilos**: `text-muted-foreground`, `text-xs`, `tracking-widest`, `ml-auto`
-
-## Patrones de Uso
-
-### Básico
-
-```tsx
-<ContextMenu>
-  <ContextMenuTrigger className="flex h-24 w-48 items-center justify-center rounded-md border">
-    Right click here
-  </ContextMenuTrigger>
-  <ContextMenuContent>
-    <ContextMenuItem>Profile</ContextMenuItem>
-    <ContextMenuItem>Billing</ContextMenuItem>
-    <ContextMenuItem>Team</ContextMenuItem>
-    <ContextMenuItem>Settings</ContextMenuItem>
-  </ContextMenuContent>
-</ContextMenu>
-```
-
-### Con Iconos y Shortcuts
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<ContextMenu>
-  <ContextMenuTrigger>Right click</ContextMenuTrigger>
-  <ContextMenuContent>
-    <ContextMenuItem>
-      <Icon symbol="person" />
-      Profile
-      <ContextMenuShortcut>⌘P</ContextMenuShortcut>
-    </ContextMenuItem>
-    <ContextMenuItem>
-      <Icon symbol="settings" />
-      Settings
-      <ContextMenuShortcut>⌘S</ContextMenuShortcut>
-    </ContextMenuItem>
-    <ContextMenuSeparator />
-    <ContextMenuItem variant="destructive">
-      <Icon symbol="logout" />
-      Log Out
-      <ContextMenuShortcut>⌘Q</ContextMenuShortcut>
-    </ContextMenuItem>
-  </ContextMenuContent>
-</ContextMenu>;
-```
-
-**Nota**: Material Symbol icons automáticamente `text-lg` (18px), `text-muted-foreground` (excepto en variant destructive). SVG icons soportados con `size-4`.
-
-### Con Checkboxes
-
-```tsx
-import { useState } from "react";
-
-function Preferences() {
-  const [showBookmarks, setShowBookmarks] = useState(true);
-  const [showFullUrls, setShowFullUrls] = useState(false);
-
-  return (
-    <ContextMenu>
-      <ContextMenuTrigger>Right click</ContextMenuTrigger>
-      <ContextMenuContent>
-        <ContextMenuCheckboxItem
-          checked={showBookmarks}
-          onCheckedChange={setShowBookmarks}
-        >
-          Show Bookmarks
-        </ContextMenuCheckboxItem>
-        <ContextMenuCheckboxItem
-          checked={showFullUrls}
-          onCheckedChange={setShowFullUrls}
-        >
-          Show Full URLs
-        </ContextMenuCheckboxItem>
-      </ContextMenuContent>
-    </ContextMenu>
-  );
-}
-```
-
-### Con Radio Group
-
-```tsx
-import { useState } from "react";
-
-function Settings() {
-  const [theme, setTheme] = useState("light");
-
-  return (
-    <ContextMenu>
-      <ContextMenuTrigger>Right click</ContextMenuTrigger>
-      <ContextMenuContent>
-        <ContextMenuLabel>Theme</ContextMenuLabel>
-        <ContextMenuRadioGroup value={theme} onValueChange={setTheme}>
-          <ContextMenuRadioItem value="light">Light</ContextMenuRadioItem>
-          <ContextMenuRadioItem value="dark">Dark</ContextMenuRadioItem>
-          <ContextMenuRadioItem value="system">System</ContextMenuRadioItem>
-        </ContextMenuRadioGroup>
-      </ContextMenuContent>
-    </ContextMenu>
-  );
-}
-```
-
-### Con Submenú
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<ContextMenu>
-  <ContextMenuTrigger>Right click</ContextMenuTrigger>
-  <ContextMenuContent>
-    <ContextMenuItem>Edit</ContextMenuItem>
-    <ContextMenuItem>Duplicate</ContextMenuItem>
-    <ContextMenuSeparator />
-    <ContextMenuSub>
-      <ContextMenuSubTrigger>
-        <Icon symbol="more_horiz" />
-        More Options
-      </ContextMenuSubTrigger>
-      <ContextMenuSubContent>
-        <ContextMenuItem>
-          <Icon symbol="download" />
-          Export
-        </ContextMenuItem>
-        <ContextMenuItem>
-          <Icon symbol="share" />
-          Share
-        </ContextMenuItem>
-      </ContextMenuSubContent>
-    </ContextMenuSub>
-  </ContextMenuContent>
-</ContextMenu>;
-```
-
-### File Manager (Multiple Items)
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<div className="grid grid-cols-3 gap-4">
-  <ContextMenu>
-    <ContextMenuTrigger className="flex h-24 flex-col items-center justify-center rounded-lg border p-4">
-      <Icon symbol="description" className="text-2xl mb-2" />
-      <span className="text-sm">Document.pdf</span>
-    </ContextMenuTrigger>
-    <ContextMenuContent>
-      <ContextMenuItem>Open</ContextMenuItem>
-      <ContextMenuItem>Open with...</ContextMenuItem>
-      <ContextMenuSeparator />
-      <ContextMenuItem>
-        <Icon symbol="content_copy" />
-        Copy
-      </ContextMenuItem>
-      <ContextMenuItem variant="destructive">
-        <Icon symbol="delete" />
-        Delete
-      </ContextMenuItem>
-    </ContextMenuContent>
-  </ContextMenu>
-
-  <ContextMenu>
-    <ContextMenuTrigger className="flex h-24 flex-col items-center justify-center rounded-lg border p-4">
-      <Icon symbol="folder" className="text-2xl mb-2" />
-      <span className="text-sm">Projects</span>
-    </ContextMenuTrigger>
-    <ContextMenuContent>
-      <ContextMenuItem>Open</ContextMenuItem>
-      <ContextMenuItem>Open in new window</ContextMenuItem>
-      <ContextMenuSeparator />
-      <ContextMenuItem>
-        <Icon symbol="content_copy" />
-        Copy
-      </ContextMenuItem>
-      <ContextMenuItem variant="destructive">
-        <TrashIcon />
-        Delete
-      </ContextMenuItem>
-    </ContextMenuContent>
-  </ContextMenu>
-</div>;
-```
-
-### Con Labels y Grupos
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<ContextMenu>
-  <ContextMenuTrigger>Right click</ContextMenuTrigger>
-  <ContextMenuContent className="w-56">
-    <ContextMenuLabel>File Operations</ContextMenuLabel>
-    <ContextMenuItem>
-      <Icon symbol="description" />
-      New File
-      <ContextMenuShortcut>⌘N</ContextMenuShortcut>
-    </ContextMenuItem>
-    <ContextMenuItem>
-      <Icon symbol="folder" />
-      New Folder
-      <ContextMenuShortcut>⌘⇧N</ContextMenuShortcut>
-    </ContextMenuItem>
-
-    <ContextMenuSeparator />
-
-    <ContextMenuLabel>Edit</ContextMenuLabel>
-    <ContextMenuItem>
-      <Icon symbol="content_copy" />
-      Copy
-      <ContextMenuShortcut>⌘C</ContextMenuShortcut>
-    </ContextMenuItem>
-    <ContextMenuItem>
-      <Icon symbol="edit" />
-      Paste
-      <ContextMenuShortcut>⌘V</ContextMenuShortcut>
-    </ContextMenuItem>
-  </ContextMenuContent>
-</ContextMenu>;
-```
-
-### Items Deshabilitados
-
-```tsx
-<ContextMenu>
-  <ContextMenuTrigger>Right click</ContextMenuTrigger>
-  <ContextMenuContent>
-    <ContextMenuItem>Available Action</ContextMenuItem>
-    <ContextMenuItem disabled>Disabled Action</ContextMenuItem>
-    <ContextMenuItem>Another Action</ContextMenuItem>
-    <ContextMenuSeparator />
-    <ContextMenuItem variant="destructive" disabled>
-      Cannot Delete
-    </ContextMenuItem>
-  </ContextMenuContent>
-</ContextMenu>
-```
-
-**Estilos disabled**: `opacity-50`, `pointer-events-none`, `data-[disabled=true]`
-
-### Con Callbacks
-
-```tsx
-function App() {
-  const handleAction = (action: string) => {
-    console.log(`Action: ${action}`);
-  };
-
-  return (
-    <ContextMenu>
-      <ContextMenuTrigger>Right click</ContextMenuTrigger>
-      <ContextMenuContent>
-        <ContextMenuItem onSelect={() => handleAction("edit")}>
-          Edit
-        </ContextMenuItem>
-        <ContextMenuItem onSelect={() => handleAction("copy")}>
-          Copy
-        </ContextMenuItem>
-        <ContextMenuItem
-          variant="destructive"
-          onSelect={() => handleAction("delete")}
-        >
-          Delete
-        </ContextMenuItem>
-      </ContextMenuContent>
-    </ContextMenu>
-  );
-}
-```
-
-### Con asChild Pattern
-
-```tsx
-// Usar elemento custom como trigger sin wrapper adicional
-<ContextMenu>
-  <ContextMenuTrigger asChild>
-    <button className="custom-button">Custom Trigger</button>
-  </ContextMenuTrigger>
-  <ContextMenuContent>
-    <ContextMenuItem>Action 1</ContextMenuItem>
-    <ContextMenuItem>Action 2</ContextMenuItem>
-  </ContextMenuContent>
-</ContextMenu>
-```
-
-## Casos de Uso Comunes
-
-**File managers**: Acciones contextuales en archivos/carpetas  
-**Image galleries**: Opciones sobre imágenes (download, share, delete)  
-**Text editors**: Copy, paste, format options  
-**Browser menus**: Back, forward, reload, more tools  
-**Data tables**: Row actions (edit, duplicate, delete)  
-**Canvas/diagram apps**: Acciones sobre elementos seleccionados
-
-## Estados y Data Attributes
-
-### ContextMenuItem States
-
-- **Focus**: `data-[highlighted]` → `bg-accent`, `text-accent-foreground`
-- **Disabled**: `data-[disabled=true]` → `opacity-50`, `pointer-events-none`
-- **Destructive**: `data-[variant=destructive]` → `text-destructive`
-
-### ContextMenuSubTrigger States
-
-- **Open**: `data-[state=open]` → `bg-accent`, `text-accent-foreground`
-
-### Content Animations
-
-- **Opening**: `data-[state=open]` → `animate-in`, `fade-in-0`, `zoom-in-95`
-- **Closing**: `data-[state=closed]` → `animate-out`, `fade-out-0`, `zoom-out-95`
-- **Slide in**: `data-[side=top|right|bottom|left]` → direccional
-
-## Navegación por Teclado
-
-- ✅ **Arrow Up/Down**: Navega entre items
-- ✅ **Arrow Right**: Abre submenú (si disponible)
-- ✅ **Arrow Left**: Cierra submenú
-- ✅ **Enter/Space**: Activa item enfocado
-- ✅ **Escape**: Cierra menú
-- ✅ **Tab**: Mueve focus fuera del menú
-- ✅ **Home/End**: Primer/último item (si `loop={true}`)
-- ✅ **Type ahead**: Busca item por primera letra
-
-## Accesibilidad
-
-- ✅ **ARIA**: `role="menu"` en content, `role="menuitem"` en items
-- ✅ **Keyboard navigation**: Navegación completa por teclado
-- ✅ **Focus management**: Focus visible y restaurado correctamente
-- ✅ **Screen readers**: Anuncia items, estado de checkboxes/radios, disabled
-- ✅ **Disabled items**: `aria-disabled="true"` en items deshabilitados
-- ✅ **Submenus**: `aria-haspopup="menu"` en SubTriggers
-- ✅ **Checked state**: `aria-checked` en CheckboxItem y RadioItem
-
-## Notas de Implementación
-
-- **Basado en Radix UI**: `@radix-ui/react-context-menu`
-- **Right click only**: Se activa solo con botón derecho del mouse
-- **Auto positioning**: Portal con posicionamiento automático
-- **Collision detection**: Evita salirse del viewport
-- **Auto-close**: Cierra al seleccionar item (excepto checkboxes/radios)
-- **Focus trap**: Mientras está abierto, focus queda dentro del menú
-- **Portal rendering**: Content se renderiza en `document.body` por defecto
-- **SVG auto-sizing**: Iconos automáticamente `size-4` y color muted
-- **Inset support**: `inset` prop agrega `pl-8` para alinear con items con iconos
-- **ChevronRightIcon**: Incluido automáticamente en SubTriggers
-- **CheckIcon/CircleIcon**: Incluidos automáticamente en CheckboxItem/RadioItem
-- **Variant destructive**: SVGs ignoran color muted y usan `text-destructive`
-
-## Posicionamiento
-
-Por defecto, el menú aparece en la posición del cursor. Se puede personalizar:
-
-```tsx
-<ContextMenuContent alignOffset={10} sideOffset={5} className="w-64">
-  {/* ... */}
-</ContextMenuContent>
-```
-
-**Opciones**:
-
-- `alignOffset`: Ajusta alineamiento horizontal
-- `sideOffset`: Distancia desde el cursor
-- `className="w-*"`: Controla ancho del menú
-
-## Troubleshooting
-
-**Menú no aparece al hacer clic derecho**: Verifica que estés usando `ContextMenuTrigger` correctamente y que no haya CSS que bloquee eventos  
-**Items no responden a click**: Asegúrate de usar `onSelect` en lugar de `onClick`  
-**Iconos mal alineados**: Usa `inset` en items sin iconos cuando otros sí tienen  
-**Menú no cierra al seleccionar**: CheckboxItems y RadioItems no cierran automáticamente (comportamiento esperado)  
-**Submenú no abre**: Verifica que estés usando `ContextMenuSub` + `ContextMenuSubTrigger` + `ContextMenuSubContent`  
-**Shortcuts no ejecutan**: `ContextMenuShortcut` es solo visual, implementa lógica en `onSelect`  
-**Focus se pierde al cerrar**: Usa `onCloseAutoFocus` para control custom del focus  
-**Posición incorrecta**: Verifica que el trigger no tenga `transform` CSS que afecte portales
-
-## Referencias
-
-- **Radix UI Context Menu**: https://www.radix-ui.com/primitives/docs/components/context-menu
-- **shadcn/ui Context Menu**: https://ui.shadcn.com/docs/components/context-menu
-- **ARIA Menu Pattern**: https://www.w3.org/WAI/ARIA/apg/patterns/menu/
+# Context Menu
+
+Menú contextual al hacer clic derecho, basado en Radix UI. Soporta submenús, checkboxes, radio groups, separadores, y shortcuts visuales. Útil para acciones contextuales en elementos.
+
+## Importación
+
+```tsx
+import {
+  ContextMenu,
+  ContextMenuTrigger,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuCheckboxItem,
+  ContextMenuRadioGroup,
+  ContextMenuRadioItem,
+  ContextMenuLabel,
+  ContextMenuSeparator,
+  ContextMenuShortcut,
+  ContextMenuSub,
+  ContextMenuSubContent,
+  ContextMenuSubTrigger,
+  ContextMenuGroup,
+  ContextMenuPortal,
+} from "@adamosuiteservices/ui/context-menu";
+```
+
+## Anatomía
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger>Right click here</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuLabel>Actions</ContextMenuLabel>
+    <ContextMenuItem>
+      Edit
+      <ContextMenuShortcut>⌘E</ContextMenuShortcut>
+    </ContextMenuItem>
+    <ContextMenuSeparator />
+    <ContextMenuCheckboxItem checked={showBookmarks}>
+      Show Bookmarks
+    </ContextMenuCheckboxItem>
+    <ContextMenuSeparator />
+    <ContextMenuSub>
+      <ContextMenuSubTrigger>More Options</ContextMenuSubTrigger>
+      <ContextMenuSubContent>
+        <ContextMenuItem>Export</ContextMenuItem>
+      </ContextMenuSubContent>
+    </ContextMenuSub>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+**Componentes**: 14 (Trigger, Content, Item, CheckboxItem, RadioGroup, RadioItem, Label, Separator, Shortcut, Sub, SubTrigger, SubContent, Group, Portal)
+
+## Props Principales
+
+### ContextMenu (Root)
+
+| Prop           | Tipo                      | Default | Descripción                                        |
+| -------------- | ------------------------- | ------- | -------------------------------------------------- |
+| `onOpenChange` | `(open: boolean) => void` | -       | Callback cuando cambia estado del menú             |
+| `modal`        | `boolean`                 | `true`  | Comportamiento modal (bloquea interacción externa) |
+
+### ContextMenuTrigger
+
+| Prop        | Tipo      | Descripción                                        |
+| ----------- | --------- | -------------------------------------------------- |
+| `asChild`   | `boolean` | Pasa props al child en lugar de renderizar wrapper |
+| `disabled`  | `boolean` | Desactiva el trigger                               |
+| `className` | `string`  | Clases CSS adicionales                             |
+
+### ContextMenuContent
+
+| Prop                   | Tipo              | Default | Descripción                                   |
+| ---------------------- | ----------------- | ------- | --------------------------------------------- |
+| `alignOffset`          | `number`          | `0`     | Offset del alineamiento                       |
+| `sideOffset`           | `number`          | `0`     | Distancia desde trigger                       |
+| `className`            | `string`          | -       | Clases CSS adicionales                        |
+| `loop`                 | `boolean`         | `false` | Navegación circular con arrow keys            |
+| `onCloseAutoFocus`     | `(event) => void` | -       | Callback al cerrar (antes de restaurar focus) |
+| `onEscapeKeyDown`      | `(event) => void` | -       | Callback al presionar Escape                  |
+| `onPointerDownOutside` | `(event) => void` | -       | Callback al hacer clic fuera                  |
+
+**Estilos default**: `min-w-[8rem]`, `max-h-(--radix-context-menu-content-available-height)`, scroll automático, `z-50`
+
+### ContextMenuItem
+
+| Prop        | Tipo                         | Default     | Descripción                             |
+| ----------- | ---------------------------- | ----------- | --------------------------------------- |
+| `onSelect`  | `(event) => void`            | -           | Callback al seleccionar (click o Enter) |
+| `disabled`  | `boolean`                    | `false`     | Desactiva el item                       |
+| `inset`     | `boolean`                    | `false`     | Agrega padding izquierdo (`pl-8`)       |
+| `variant`   | `"default" \| "destructive"` | `"default"` | Estilo del item                         |
+| `className` | `string`                     | -           | Clases CSS adicionales                  |
+
+**Variantes**:
+
+- `default`: `focus:bg-accent`, `focus:text-accent-foreground`
+- `destructive`: `text-destructive`, `focus:bg-destructive/10`, `focus:text-destructive`
+
+### ContextMenuCheckboxItem
+
+| Prop              | Tipo                         | Descripción                |
+| ----------------- | ---------------------------- | -------------------------- |
+| `checked`         | `boolean \| "indeterminate"` | Estado del checkbox        |
+| `onCheckedChange` | `(checked: boolean) => void` | Callback al cambiar estado |
+| `disabled`        | `boolean`                    | Desactiva el item          |
+| `className`       | `string`                     | Clases CSS adicionales     |
+
+**Indicador**: Check icon (Material Symbol "check") automático cuando `checked={true}`, posicionado con `pl-8`
+
+### ContextMenuRadioGroup
+
+| Prop            | Tipo                      | Descripción               |
+| --------------- | ------------------------- | ------------------------- |
+| `value`         | `string`                  | Valor seleccionado        |
+| `onValueChange` | `(value: string) => void` | Callback al cambiar valor |
+
+### ContextMenuRadioItem
+
+| Prop        | Tipo      | Descripción            |
+| ----------- | --------- | ---------------------- |
+| `value`     | `string`  | Valor único del item   |
+| `disabled`  | `boolean` | Desactiva el item      |
+| `className` | `string`  | Clases CSS adicionales |
+
+**Indicador**: Circle icon (Material Symbol "circle") automático cuando seleccionado, posicionado con `pl-8`
+
+### ContextMenuSub
+
+| Prop           | Tipo                      | Descripción                   |
+| -------------- | ------------------------- | ----------------------------- |
+| `open`         | `boolean`                 | Estado controlado del submenú |
+| `onOpenChange` | `(open: boolean) => void` | Callback al cambiar estado    |
+
+### ContextMenuSubTrigger
+
+| Prop        | Tipo      | Descripción                |
+| ----------- | --------- | -------------------------- |
+| `disabled`  | `boolean` | Desactiva el trigger       |
+| `inset`     | `boolean` | Padding izquierdo (`pl-8`) |
+| `className` | `string`  | Clases CSS adicionales     |
+
+**Indicador**: Chevron right icon (Material Symbol "chevron_right") automático con `ml-auto`
+
+### ContextMenuLabel
+
+| Prop        | Tipo      | Descripción                |
+| ----------- | --------- | -------------------------- |
+| `inset`     | `boolean` | Padding izquierdo (`pl-8`) |
+| `className` | `string`  | Clases CSS adicionales     |
+
+**Estilos**: `text-foreground`, `font-medium`
+
+### ContextMenuShortcut
+
+| Prop        | Tipo     | Descripción            |
+| ----------- | -------- | ---------------------- |
+| `className` | `string` | Clases CSS adicionales |
+
+**Estilos**: `text-muted-foreground`, `text-xs`, `tracking-widest`, `ml-auto`
+
+## Patrones de Uso
+
+### Básico
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger className="flex h-24 w-48 items-center justify-center rounded-md border">
+    Right click here
+  </ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Profile</ContextMenuItem>
+    <ContextMenuItem>Billing</ContextMenuItem>
+    <ContextMenuItem>Team</ContextMenuItem>
+    <ContextMenuItem>Settings</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+### Con Iconos y Shortcuts
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<ContextMenu>
+  <ContextMenuTrigger>Right click</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>
+      <Icon symbol="person" />
+      Profile
+      <ContextMenuShortcut>⌘P</ContextMenuShortcut>
+    </ContextMenuItem>
+    <ContextMenuItem>
+      <Icon symbol="settings" />
+      Settings
+      <ContextMenuShortcut>⌘S</ContextMenuShortcut>
+    </ContextMenuItem>
+    <ContextMenuSeparator />
+    <ContextMenuItem variant="destructive">
+      <Icon symbol="logout" />
+      Log Out
+      <ContextMenuShortcut>⌘Q</ContextMenuShortcut>
+    </ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>;
+```
+
+**Nota**: Material Symbol icons automáticamente `text-lg` (18px), `text-muted-foreground` (excepto en variant destructive). SVG icons soportados con `size-4`.
+
+### Con Checkboxes
+
+```tsx
+import { useState } from "react";
+
+function Preferences() {
+  const [showBookmarks, setShowBookmarks] = useState(true);
+  const [showFullUrls, setShowFullUrls] = useState(false);
+
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger>Right click</ContextMenuTrigger>
+      <ContextMenuContent>
+        <ContextMenuCheckboxItem
+          checked={showBookmarks}
+          onCheckedChange={setShowBookmarks}
+        >
+          Show Bookmarks
+        </ContextMenuCheckboxItem>
+        <ContextMenuCheckboxItem
+          checked={showFullUrls}
+          onCheckedChange={setShowFullUrls}
+        >
+          Show Full URLs
+        </ContextMenuCheckboxItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  );
+}
+```
+
+### Con Radio Group
+
+```tsx
+import { useState } from "react";
+
+function Settings() {
+  const [theme, setTheme] = useState("light");
+
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger>Right click</ContextMenuTrigger>
+      <ContextMenuContent>
+        <ContextMenuLabel>Theme</ContextMenuLabel>
+        <ContextMenuRadioGroup value={theme} onValueChange={setTheme}>
+          <ContextMenuRadioItem value="light">Light</ContextMenuRadioItem>
+          <ContextMenuRadioItem value="dark">Dark</ContextMenuRadioItem>
+          <ContextMenuRadioItem value="system">System</ContextMenuRadioItem>
+        </ContextMenuRadioGroup>
+      </ContextMenuContent>
+    </ContextMenu>
+  );
+}
+```
+
+### Con Submenú
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<ContextMenu>
+  <ContextMenuTrigger>Right click</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Edit</ContextMenuItem>
+    <ContextMenuItem>Duplicate</ContextMenuItem>
+    <ContextMenuSeparator />
+    <ContextMenuSub>
+      <ContextMenuSubTrigger>
+        <Icon symbol="more_horiz" />
+        More Options
+      </ContextMenuSubTrigger>
+      <ContextMenuSubContent>
+        <ContextMenuItem>
+          <Icon symbol="download" />
+          Export
+        </ContextMenuItem>
+        <ContextMenuItem>
+          <Icon symbol="share" />
+          Share
+        </ContextMenuItem>
+      </ContextMenuSubContent>
+    </ContextMenuSub>
+  </ContextMenuContent>
+</ContextMenu>;
+```
+
+### File Manager (Multiple Items)
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<div className="grid grid-cols-3 gap-4">
+  <ContextMenu>
+    <ContextMenuTrigger className="flex h-24 flex-col items-center justify-center rounded-lg border p-4">
+      <Icon symbol="description" className="text-2xl mb-2" />
+      <span className="text-sm">Document.pdf</span>
+    </ContextMenuTrigger>
+    <ContextMenuContent>
+      <ContextMenuItem>Open</ContextMenuItem>
+      <ContextMenuItem>Open with...</ContextMenuItem>
+      <ContextMenuSeparator />
+      <ContextMenuItem>
+        <Icon symbol="content_copy" />
+        Copy
+      </ContextMenuItem>
+      <ContextMenuItem variant="destructive">
+        <Icon symbol="delete" />
+        Delete
+      </ContextMenuItem>
+    </ContextMenuContent>
+  </ContextMenu>
+
+  <ContextMenu>
+    <ContextMenuTrigger className="flex h-24 flex-col items-center justify-center rounded-lg border p-4">
+      <Icon symbol="folder" className="text-2xl mb-2" />
+      <span className="text-sm">Projects</span>
+    </ContextMenuTrigger>
+    <ContextMenuContent>
+      <ContextMenuItem>Open</ContextMenuItem>
+      <ContextMenuItem>Open in new window</ContextMenuItem>
+      <ContextMenuSeparator />
+      <ContextMenuItem>
+        <Icon symbol="content_copy" />
+        Copy
+      </ContextMenuItem>
+      <ContextMenuItem variant="destructive">
+        <TrashIcon />
+        Delete
+      </ContextMenuItem>
+    </ContextMenuContent>
+  </ContextMenu>
+</div>;
+```
+
+### Con Labels y Grupos
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<ContextMenu>
+  <ContextMenuTrigger>Right click</ContextMenuTrigger>
+  <ContextMenuContent className="w-56">
+    <ContextMenuLabel>File Operations</ContextMenuLabel>
+    <ContextMenuItem>
+      <Icon symbol="description" />
+      New File
+      <ContextMenuShortcut>⌘N</ContextMenuShortcut>
+    </ContextMenuItem>
+    <ContextMenuItem>
+      <Icon symbol="folder" />
+      New Folder
+      <ContextMenuShortcut>⌘⇧N</ContextMenuShortcut>
+    </ContextMenuItem>
+
+    <ContextMenuSeparator />
+
+    <ContextMenuLabel>Edit</ContextMenuLabel>
+    <ContextMenuItem>
+      <Icon symbol="content_copy" />
+      Copy
+      <ContextMenuShortcut>⌘C</ContextMenuShortcut>
+    </ContextMenuItem>
+    <ContextMenuItem>
+      <Icon symbol="edit" />
+      Paste
+      <ContextMenuShortcut>⌘V</ContextMenuShortcut>
+    </ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>;
+```
+
+### Items Deshabilitados
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger>Right click</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Available Action</ContextMenuItem>
+    <ContextMenuItem disabled>Disabled Action</ContextMenuItem>
+    <ContextMenuItem>Another Action</ContextMenuItem>
+    <ContextMenuSeparator />
+    <ContextMenuItem variant="destructive" disabled>
+      Cannot Delete
+    </ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+**Estilos disabled**: `opacity-50`, `pointer-events-none`, `data-[disabled=true]`
+
+### Con Callbacks
+
+```tsx
+function App() {
+  const handleAction = (action: string) => {
+    console.log(`Action: ${action}`);
+  };
+
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger>Right click</ContextMenuTrigger>
+      <ContextMenuContent>
+        <ContextMenuItem onSelect={() => handleAction("edit")}>
+          Edit
+        </ContextMenuItem>
+        <ContextMenuItem onSelect={() => handleAction("copy")}>
+          Copy
+        </ContextMenuItem>
+        <ContextMenuItem
+          variant="destructive"
+          onSelect={() => handleAction("delete")}
+        >
+          Delete
+        </ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  );
+}
+```
+
+### Con asChild Pattern
+
+```tsx
+// Usar elemento custom como trigger sin wrapper adicional
+<ContextMenu>
+  <ContextMenuTrigger asChild>
+    <button className="custom-button">Custom Trigger</button>
+  </ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Action 1</ContextMenuItem>
+    <ContextMenuItem>Action 2</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+## Casos de Uso Comunes
+
+**File managers**: Acciones contextuales en archivos/carpetas  
+**Image galleries**: Opciones sobre imágenes (download, share, delete)  
+**Text editors**: Copy, paste, format options  
+**Browser menus**: Back, forward, reload, more tools  
+**Data tables**: Row actions (edit, duplicate, delete)  
+**Canvas/diagram apps**: Acciones sobre elementos seleccionados
+
+## Estados y Data Attributes
+
+### ContextMenuItem States
+
+- **Focus**: `data-[highlighted]` → `bg-accent`, `text-accent-foreground`
+- **Disabled**: `data-[disabled=true]` → `opacity-50`, `pointer-events-none`
+- **Destructive**: `data-[variant=destructive]` → `text-destructive`
+
+### ContextMenuSubTrigger States
+
+- **Open**: `data-[state=open]` → `bg-accent`, `text-accent-foreground`
+
+### Content Animations
+
+- **Opening**: `data-[state=open]` → `animate-in`, `fade-in-0`, `zoom-in-95`
+- **Closing**: `data-[state=closed]` → `animate-out`, `fade-out-0`, `zoom-out-95`
+- **Slide in**: `data-[side=top|right|bottom|left]` → direccional
+
+## Navegación por Teclado
+
+- ✅ **Arrow Up/Down**: Navega entre items
+- ✅ **Arrow Right**: Abre submenú (si disponible)
+- ✅ **Arrow Left**: Cierra submenú
+- ✅ **Enter/Space**: Activa item enfocado
+- ✅ **Escape**: Cierra menú
+- ✅ **Tab**: Mueve focus fuera del menú
+- ✅ **Home/End**: Primer/último item (si `loop={true}`)
+- ✅ **Type ahead**: Busca item por primera letra
+
+## Accesibilidad
+
+- ✅ **ARIA**: `role="menu"` en content, `role="menuitem"` en items
+- ✅ **Keyboard navigation**: Navegación completa por teclado
+- ✅ **Focus management**: Focus visible y restaurado correctamente
+- ✅ **Screen readers**: Anuncia items, estado de checkboxes/radios, disabled
+- ✅ **Disabled items**: `aria-disabled="true"` en items deshabilitados
+- ✅ **Submenus**: `aria-haspopup="menu"` en SubTriggers
+- ✅ **Checked state**: `aria-checked` en CheckboxItem y RadioItem
+
+## Notas de Implementación
+
+- **Basado en Radix UI**: `@radix-ui/react-context-menu`
+- **Right click only**: Se activa solo con botón derecho del mouse
+- **Auto positioning**: Portal con posicionamiento automático
+- **Collision detection**: Evita salirse del viewport
+- **Auto-close**: Cierra al seleccionar item (excepto checkboxes/radios)
+- **Focus trap**: Mientras está abierto, focus queda dentro del menú
+- **Portal rendering**: Content se renderiza en `document.body` por defecto
+- **SVG auto-sizing**: Iconos automáticamente `size-4` y color muted
+- **Inset support**: `inset` prop agrega `pl-8` para alinear con items con iconos
+- **ChevronRightIcon**: Incluido automáticamente en SubTriggers
+- **CheckIcon/CircleIcon**: Incluidos automáticamente en CheckboxItem/RadioItem
+- **Variant destructive**: SVGs ignoran color muted y usan `text-destructive`
+
+## Posicionamiento
+
+Por defecto, el menú aparece en la posición del cursor. Se puede personalizar:
+
+```tsx
+<ContextMenuContent alignOffset={10} sideOffset={5} className="w-64">
+  {/* ... */}
+</ContextMenuContent>
+```
+
+**Opciones**:
+
+- `alignOffset`: Ajusta alineamiento horizontal
+- `sideOffset`: Distancia desde el cursor
+- `className="w-*"`: Controla ancho del menú
+
+## Troubleshooting
+
+**Menú no aparece al hacer clic derecho**: Verifica que estés usando `ContextMenuTrigger` correctamente y que no haya CSS que bloquee eventos  
+**Items no responden a click**: Asegúrate de usar `onSelect` en lugar de `onClick`  
+**Iconos mal alineados**: Usa `inset` en items sin iconos cuando otros sí tienen  
+**Menú no cierra al seleccionar**: CheckboxItems y RadioItems no cierran automáticamente (comportamiento esperado)  
+**Submenú no abre**: Verifica que estés usando `ContextMenuSub` + `ContextMenuSubTrigger` + `ContextMenuSubContent`  
+**Shortcuts no ejecutan**: `ContextMenuShortcut` es solo visual, implementa lógica en `onSelect`  
+**Focus se pierde al cerrar**: Usa `onCloseAutoFocus` para control custom del focus  
+**Posición incorrecta**: Verifica que el trigger no tenga `transform` CSS que afecte portales
+
+## Referencias
+
+- **Radix UI Context Menu**: https://www.radix-ui.com/primitives/docs/components/context-menu
+- **shadcn/ui Context Menu**: https://ui.shadcn.com/docs/components/context-menu
+- **ARIA Menu Pattern**: https://www.w3.org/WAI/ARIA/apg/patterns/menu/