@adamosuiteservices/ui 2.11.17 → 2.11.18

package/docs/components/ui/command.md

@@ -1,454 +1,454 @@
-# Command
-
-Paleta de comandos estilo Cmd+K basada en `cmdk` con búsqueda fuzzy, navegación por teclado, grupos, separadores, y shortcuts. Útil para command palettes, búsqueda rápida, y navegación.
-
-## Importación
-
-```tsx
-import {
-  Command,
-  CommandInput,
-  CommandList,
-  CommandEmpty,
-  CommandGroup,
-  CommandItem,
-  CommandSeparator,
-  CommandShortcut,
-  CommandDialog,
-} from "@adamosuiteservices/ui/command";
-```
-
-## Anatomía
-
-```tsx
-<Command>
-  <CommandInput placeholder="Search..." />
-  <CommandList>
-    <CommandEmpty>No results found.</CommandEmpty>
-    <CommandGroup heading="Actions">
-      <CommandItem>
-        New File
-        <CommandShortcut>⌘N</CommandShortcut>
-      </CommandItem>
-      <CommandItem>Open</CommandItem>
-    </CommandGroup>
-    <CommandSeparator />
-    <CommandGroup heading="Settings">
-      <CommandItem>Preferences</CommandItem>
-    </CommandGroup>
-  </CommandList>
-</Command>
-```
-
-**Componentes**: 8 (Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut)
-
-## Props Principales
-
-### Command (Root)
-
-| Prop            | Tipo                                        | Default     | Descripción                            |
-| --------------- | ------------------------------------------- | ----------- | -------------------------------------- |
-| `value`         | `string`                                    | -           | Valor controlado del item seleccionado |
-| `onValueChange` | `(value: string) => void`                   | -           | Callback cuando cambia selección       |
-| `filter`        | `(value: string, search: string) => number` | Fuzzy match | Función de filtrado custom             |
-| `shouldFilter`  | `boolean`                                   | `true`      | Habilita filtrado automático           |
-| `loop`          | `boolean`                                   | `false`     | Navegación circular con arrow keys     |
-| `className`     | `string`                                    | -           | Clases CSS adicionales                 |
-
-### CommandInput
-
-| Prop            | Tipo                       | Descripción                |
-| --------------- | -------------------------- | -------------------------- |
-| `placeholder`   | `string`                   | Texto placeholder          |
-| `value`         | `string`                   | Valor controlado del input |
-| `onValueChange` | `(search: string) => void` | Callback al escribir       |
-| `className`     | `string`                   | Clases CSS adicionales     |
-
-### CommandList
-
-| Prop        | Tipo        | Default | Descripción                |
-| ----------- | ----------- | ------- | -------------------------- |
-| `className` | `string`    | -       | Clases CSS adicionales     |
-| `children`  | `ReactNode` | -       | Grupos, items, separadores |
-
-**Estilos default**: `max-h-[300px]`, scroll vertical automático
-
-### CommandItem
-
-| Prop        | Tipo                      | Descripción                                |
-| ----------- | ------------------------- | ------------------------------------------ |
-| `value`     | `string`                  | Valor único del item (usado para búsqueda) |
-| `onSelect`  | `(value: string) => void` | Callback al seleccionar                    |
-| `disabled`  | `boolean`                 | Desactiva selección                        |
-| `keywords`  | `string[]`                | Palabras clave adicionales para búsqueda   |
-| `className` | `string`                  | Clases CSS adicionales                     |
-
-### CommandDialog
-
-| Prop              | Tipo                      | Default             | Descripción              |
-| ----------------- | ------------------------- | ------------------- | ------------------------ |
-| `open`            | `boolean`                 | -                   | Estado del dialog        |
-| `onOpenChange`    | `(open: boolean) => void` | -                   | Callback al abrir/cerrar |
-| `title`           | `string`                  | `"Command Palette"` | Título (sr-only)         |
-| `description`     | `string`                  | `"Search for..."`   | Descripción (sr-only)    |
-| `showCloseButton` | `boolean`                 | `true`              | Muestra botón de cerrar  |
-| `className`       | `string`                  | -                   | Clases CSS adicionales   |
-
-## Patrones de Uso
-
-### Básico (Inline)
-
-```tsx
-<Command>
-  <CommandInput placeholder="Type to search..." />
-  <CommandList>
-    <CommandEmpty>No results found.</CommandEmpty>
-    <CommandGroup heading="Suggestions">
-      <CommandItem>Calendar</CommandItem>
-      <CommandItem>Search Emoji</CommandItem>
-      <CommandItem>Calculator</CommandItem>
-    </CommandGroup>
-  </CommandList>
-</Command>
-```
-
-### Command Dialog (Cmd+K)
-
-```tsx
-import { useEffect, useState } from "react";
-
-function CommandMenu() {
-  const [open, setOpen] = useState(false);
-
-  useEffect(() => {
-    const down = (e: KeyboardEvent) => {
-      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
-        e.preventDefault();
-        setOpen((open) => !open);
-      }
-    };
-
-    document.addEventListener("keydown", down);
-    return () => document.removeEventListener("keydown", down);
-  }, []);
-
-  return (
-    <CommandDialog open={open} onOpenChange={setOpen}>
-      <CommandInput placeholder="Type a command or search..." />
-      <CommandList>
-        <CommandEmpty>No results found.</CommandEmpty>
-        <CommandGroup heading="Actions">
-          <CommandItem>
-            New File
-            <CommandShortcut>⌘N</CommandShortcut>
-          </CommandItem>
-          <CommandItem>
-            Open File
-            <CommandShortcut>⌘O</CommandShortcut>
-          </CommandItem>
-        </CommandGroup>
-      </CommandList>
-    </CommandDialog>
-  );
-}
-```
-
-### Con Iconos
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<Command>
-  <CommandInput placeholder="Search..." />
-  <CommandList>
-    <CommandGroup heading="Suggestions">
-      <CommandItem>
-        <Icon symbol="calendar_month" />
-        Calendar
-      </CommandItem>
-      <CommandItem>
-        <Icon symbol="sentiment_satisfied" />
-        Search Emoji
-      </CommandItem>
-      <CommandItem>
-        <Icon symbol="rocket_launch" />
-        Launch
-      </CommandItem>
-    </CommandGroup>
-  </CommandList>
-</Command>;
-```
-
-**Nota**: SVGs tienen `size-4` automático y `text-muted-foreground` si no tienen clase `text-*`.
-
-### Múltiples Grupos con Separadores
-
-```tsx
-<Command>
-  <CommandInput placeholder="Search..." />
-  <CommandList>
-    <CommandGroup heading="Files">
-      <CommandItem>New File</CommandItem>
-      <CommandItem>New Folder</CommandItem>
-    </CommandGroup>
-
-    <CommandSeparator />
-
-    <CommandGroup heading="Edit">
-      <CommandItem>Copy</CommandItem>
-      <CommandItem>Paste</CommandItem>
-    </CommandGroup>
-
-    <CommandSeparator />
-
-    <CommandGroup heading="View">
-      <CommandItem>Toggle Sidebar</CommandItem>
-      <CommandItem>Full Screen</CommandItem>
-    </CommandGroup>
-  </CommandList>
-</Command>
-```
-
-### Con Callbacks (Ejecutar Acciones)
-
-```tsx
-function App() {
-  const runCommand = (command: string) => {
-    console.log(`Running: ${command}`);
-    // Ejecutar acción
-  };
-
-  return (
-    <Command>
-      <CommandInput placeholder="Search..." />
-      <CommandList>
-        <CommandGroup heading="Actions">
-          <CommandItem onSelect={() => runCommand("new-file")}>
-            New File
-          </CommandItem>
-          <CommandItem onSelect={() => runCommand("open-file")}>
-            Open File
-          </CommandItem>
-          <CommandItem onSelect={() => runCommand("save")}>Save</CommandItem>
-        </CommandGroup>
-      </CommandList>
-    </Command>
-  );
-}
-```
-
-### Items Deshabilitados
-
-```tsx
-<Command>
-  <CommandList>
-    <CommandGroup>
-      <CommandItem>Available Option</CommandItem>
-      <CommandItem disabled>Coming Soon</CommandItem>
-      <CommandItem disabled>Premium Feature</CommandItem>
-    </CommandGroup>
-  </CommandList>
-</Command>
-```
-
-**Estilos**: `opacity-50`, `pointer-events-none`, `data-[disabled=true]`
-
-### Con Keywords para Búsqueda
-
-```tsx
-<Command>
-  <CommandInput placeholder="Search settings..." />
-  <CommandList>
-    <CommandGroup heading="Settings">
-      <CommandItem
-        value="theme"
-        keywords={["appearance", "dark", "light", "color"]}
-      >
-        Theme Settings
-      </CommandItem>
-      <CommandItem
-        value="shortcuts"
-        keywords={["keyboard", "hotkeys", "bindings"]}
-      >
-        Keyboard Shortcuts
-      </CommandItem>
-    </CommandGroup>
-  </CommandList>
-</Command>
-```
-
-**Búsqueda**: Encuentra items por `value`, `children` text, o `keywords[]`
-
-### Navegación de Páginas
-
-```tsx
-function PageSearch() {
-  const navigate = useNavigate();
-  const [open, setOpen] = useState(false);
-
-  return (
-    <CommandDialog open={open} onOpenChange={setOpen}>
-      <CommandInput placeholder="Search pages..." />
-      <CommandList>
-        <CommandGroup heading="Pages">
-          <CommandItem
-            onSelect={() => {
-              navigate("/dashboard");
-              setOpen(false);
-            }}
-          >
-            Dashboard
-          </CommandItem>
-          <CommandItem
-            onSelect={() => {
-              navigate("/settings");
-              setOpen(false);
-            }}
-          >
-            Settings
-          </CommandItem>
-          <CommandItem
-            onSelect={() => {
-              navigate("/profile");
-              setOpen(false);
-            }}
-          >
-            Profile
-          </CommandItem>
-        </CommandGroup>
-      </CommandList>
-    </CommandDialog>
-  );
-}
-```
-
-### Filtrado Custom
-
-```tsx
-// Exacto match en lugar de fuzzy
-const exactMatch = (value: string, search: string) => {
-  return value.toLowerCase().includes(search.toLowerCase()) ? 1 : 0;
-};
-
-<Command filter={exactMatch}>
-  <CommandInput placeholder="Search..." />
-  <CommandList>
-    <CommandGroup>
-      <CommandItem>Apple</CommandItem>
-      <CommandItem>Banana</CommandItem>
-      <CommandItem>Cherry</CommandItem>
-    </CommandGroup>
-  </CommandList>
-</Command>;
-```
-
-### Sin Filtrado Automático
-
-```tsx
-// Control manual del filtrado
-function CustomFilter() {
-  const [search, setSearch] = useState("");
-  const [filteredItems, setFilteredItems] = useState(allItems);
-
-  useEffect(() => {
-    setFilteredItems(
-      allItems.filter((item) =>
-        item.toLowerCase().includes(search.toLowerCase())
-      )
-    );
-  }, [search]);
-
-  return (
-    <Command shouldFilter={false}>
-      <CommandInput
-        value={search}
-        onValueChange={setSearch}
-        placeholder="Search..."
-      />
-      <CommandList>
-        <CommandGroup>
-          {filteredItems.map((item) => (
-            <CommandItem key={item}>{item}</CommandItem>
-          ))}
-        </CommandGroup>
-      </CommandList>
-    </Command>
-  );
-}
-```
-
-## Casos de Uso Comunes
-
-**Command palette (Cmd+K)**: Búsqueda rápida de acciones/comandos  
-**Page navigation**: Navegación rápida entre páginas  
-**File picker**: Búsqueda de archivos en proyecto  
-**Settings search**: Encontrar configuraciones  
-**Action menu**: Menú de acciones contextuales  
-**Spotlight search**: Búsqueda global tipo macOS
-
-## Estados y Data Attributes
-
-### CommandItem States
-
-- **Selected**: `data-[selected=true]` → `bg-accent`, `text-accent-foreground`
-- **Disabled**: `data-[disabled=true]` → `opacity-50`, `pointer-events-none`
-
-### Empty State
-
-- Automático cuando búsqueda no encuentra resultados
-- Personalizable con `<CommandEmpty>`
-
-## Navegación por Teclado
-
-- ✅ **Arrow Up/Down**: Navega entre items
-- ✅ **Enter**: Selecciona item enfocado
-- ✅ **Escape**: Cierra dialog (si CommandDialog)
-- ✅ **Type to search**: Filtrado automático
-- ✅ **Tab**: Sale del Command (no navega items)
-- ✅ **Home/End**: Primer/último item (si `loop={true}`)
-
-## Accesibilidad
-
-- ✅ **ARIA**: `role="combobox"` en Command, `role="option"` en items
-- ✅ **Screen readers**: Anuncia items y cuenta de resultados
-- ✅ **Keyboard navigation**: Navegación completa por teclado
-- ✅ **Focus management**: Focus visible en items seleccionados
-- ✅ **Live regions**: Anuncia cuando cambian resultados
-- ✅ **Disabled items**: `aria-disabled` en items deshabilitados
-
-## Notas de Implementación
-
-- **Basado en cmdk**: Librería `cmdk` de Paco Coursey
-- **Fuzzy search**: Búsqueda difusa por defecto (typo-tolerant)
-- **Performance**: Virtualización automática con muchos items
-- **Search icon**: Incluido automáticamente en CommandInput (Material Symbol "search")
-- **CommandDialog**: Wrapper de Command + Dialog con estilos predefinidos
-- **Data slots**: Cada componente tiene `data-slot` para CSS targeting
-- **Icon sizing**: Material Symbol icons automáticamente `text-lg` (18px) con shrink-0 y opacity-50
-- **CommandShortcut**: Elemento visual para shortcuts (no ejecuta código)
-- **Max height**: CommandList tiene `max-h-[300px]` default
-- **Scroll behavior**: `scroll-py-1` para padding al scrollear
-
-## Estilos Especiales en CommandDialog
-
-Cuando se usa en Dialog, aplica estilos adicionales:
-
-- Items con `py-3` (más padding)
-- Input con `h-12`
-- SVGs con `h-5 w-5` (más grandes)
-- Groups con heading más prominente
-
-## Troubleshooting
-
-**Búsqueda no funciona**: Verifica que `shouldFilter={true}` (default) o implementa filtrado manual  
-**Items no se ven**: Asegúrate de envolver en `<CommandList>` y `<CommandGroup>`  
-**Cmd+K no abre dialog**: Verifica que el `useEffect` esté ejecutándose y no haya conflictos con otros shortcuts  
-**Empty no aparece**: Solo se muestra cuando no hay resultados después de búsqueda  
-**Shortcuts no ejecutan**: `CommandShortcut` es solo visual, implementa lógica aparte  
-**Dialog no cierra**: Asegúrate de llamar `setOpen(false)` en `onSelect` de items  
-**Navegación circular no funciona**: Activa `loop={true}` en Command root
-
-## Referencias
-
-- **cmdk**: https://cmdk.paco.me
-- **ARIA Combobox**: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/
+# Command
+
+Paleta de comandos estilo Cmd+K basada en `cmdk` con búsqueda fuzzy, navegación por teclado, grupos, separadores, y shortcuts. Útil para command palettes, búsqueda rápida, y navegación.
+
+## Importación
+
+```tsx
+import {
+  Command,
+  CommandInput,
+  CommandList,
+  CommandEmpty,
+  CommandGroup,
+  CommandItem,
+  CommandSeparator,
+  CommandShortcut,
+  CommandDialog,
+} from "@adamosuiteservices/ui/command";
+```
+
+## Anatomía
+
+```tsx
+<Command>
+  <CommandInput placeholder="Search..." />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Actions">
+      <CommandItem>
+        New File
+        <CommandShortcut>⌘N</CommandShortcut>
+      </CommandItem>
+      <CommandItem>Open</CommandItem>
+    </CommandGroup>
+    <CommandSeparator />
+    <CommandGroup heading="Settings">
+      <CommandItem>Preferences</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+**Componentes**: 8 (Command, CommandInput, CommandList, CommandEmpty, CommandGroup, CommandItem, CommandSeparator, CommandShortcut)
+
+## Props Principales
+
+### Command (Root)
+
+| Prop            | Tipo                                        | Default     | Descripción                            |
+| --------------- | ------------------------------------------- | ----------- | -------------------------------------- |
+| `value`         | `string`                                    | -           | Valor controlado del item seleccionado |
+| `onValueChange` | `(value: string) => void`                   | -           | Callback cuando cambia selección       |
+| `filter`        | `(value: string, search: string) => number` | Fuzzy match | Función de filtrado custom             |
+| `shouldFilter`  | `boolean`                                   | `true`      | Habilita filtrado automático           |
+| `loop`          | `boolean`                                   | `false`     | Navegación circular con arrow keys     |
+| `className`     | `string`                                    | -           | Clases CSS adicionales                 |
+
+### CommandInput
+
+| Prop            | Tipo                       | Descripción                |
+| --------------- | -------------------------- | -------------------------- |
+| `placeholder`   | `string`                   | Texto placeholder          |
+| `value`         | `string`                   | Valor controlado del input |
+| `onValueChange` | `(search: string) => void` | Callback al escribir       |
+| `className`     | `string`                   | Clases CSS adicionales     |
+
+### CommandList
+
+| Prop        | Tipo        | Default | Descripción                |
+| ----------- | ----------- | ------- | -------------------------- |
+| `className` | `string`    | -       | Clases CSS adicionales     |
+| `children`  | `ReactNode` | -       | Grupos, items, separadores |
+
+**Estilos default**: `max-h-[300px]`, scroll vertical automático
+
+### CommandItem
+
+| Prop        | Tipo                      | Descripción                                |
+| ----------- | ------------------------- | ------------------------------------------ |
+| `value`     | `string`                  | Valor único del item (usado para búsqueda) |
+| `onSelect`  | `(value: string) => void` | Callback al seleccionar                    |
+| `disabled`  | `boolean`                 | Desactiva selección                        |
+| `keywords`  | `string[]`                | Palabras clave adicionales para búsqueda   |
+| `className` | `string`                  | Clases CSS adicionales                     |
+
+### CommandDialog
+
+| Prop              | Tipo                      | Default             | Descripción              |
+| ----------------- | ------------------------- | ------------------- | ------------------------ |
+| `open`            | `boolean`                 | -                   | Estado del dialog        |
+| `onOpenChange`    | `(open: boolean) => void` | -                   | Callback al abrir/cerrar |
+| `title`           | `string`                  | `"Command Palette"` | Título (sr-only)         |
+| `description`     | `string`                  | `"Search for..."`   | Descripción (sr-only)    |
+| `showCloseButton` | `boolean`                 | `true`              | Muestra botón de cerrar  |
+| `className`       | `string`                  | -                   | Clases CSS adicionales   |
+
+## Patrones de Uso
+
+### Básico (Inline)
+
+```tsx
+<Command>
+  <CommandInput placeholder="Type to search..." />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Suggestions">
+      <CommandItem>Calendar</CommandItem>
+      <CommandItem>Search Emoji</CommandItem>
+      <CommandItem>Calculator</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+### Command Dialog (Cmd+K)
+
+```tsx
+import { useEffect, useState } from "react";
+
+function CommandMenu() {
+  const [open, setOpen] = useState(false);
+
+  useEffect(() => {
+    const down = (e: KeyboardEvent) => {
+      if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        setOpen((open) => !open);
+      }
+    };
+
+    document.addEventListener("keydown", down);
+    return () => document.removeEventListener("keydown", down);
+  }, []);
+
+  return (
+    <CommandDialog open={open} onOpenChange={setOpen}>
+      <CommandInput placeholder="Type a command or search..." />
+      <CommandList>
+        <CommandEmpty>No results found.</CommandEmpty>
+        <CommandGroup heading="Actions">
+          <CommandItem>
+            New File
+            <CommandShortcut>⌘N</CommandShortcut>
+          </CommandItem>
+          <CommandItem>
+            Open File
+            <CommandShortcut>⌘O</CommandShortcut>
+          </CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </CommandDialog>
+  );
+}
+```
+
+### Con Iconos
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<Command>
+  <CommandInput placeholder="Search..." />
+  <CommandList>
+    <CommandGroup heading="Suggestions">
+      <CommandItem>
+        <Icon symbol="calendar_month" />
+        Calendar
+      </CommandItem>
+      <CommandItem>
+        <Icon symbol="sentiment_satisfied" />
+        Search Emoji
+      </CommandItem>
+      <CommandItem>
+        <Icon symbol="rocket_launch" />
+        Launch
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>;
+```
+
+**Nota**: SVGs tienen `size-4` automático y `text-muted-foreground` si no tienen clase `text-*`.
+
+### Múltiples Grupos con Separadores
+
+```tsx
+<Command>
+  <CommandInput placeholder="Search..." />
+  <CommandList>
+    <CommandGroup heading="Files">
+      <CommandItem>New File</CommandItem>
+      <CommandItem>New Folder</CommandItem>
+    </CommandGroup>
+
+    <CommandSeparator />
+
+    <CommandGroup heading="Edit">
+      <CommandItem>Copy</CommandItem>
+      <CommandItem>Paste</CommandItem>
+    </CommandGroup>
+
+    <CommandSeparator />
+
+    <CommandGroup heading="View">
+      <CommandItem>Toggle Sidebar</CommandItem>
+      <CommandItem>Full Screen</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+### Con Callbacks (Ejecutar Acciones)
+
+```tsx
+function App() {
+  const runCommand = (command: string) => {
+    console.log(`Running: ${command}`);
+    // Ejecutar acción
+  };
+
+  return (
+    <Command>
+      <CommandInput placeholder="Search..." />
+      <CommandList>
+        <CommandGroup heading="Actions">
+          <CommandItem onSelect={() => runCommand("new-file")}>
+            New File
+          </CommandItem>
+          <CommandItem onSelect={() => runCommand("open-file")}>
+            Open File
+          </CommandItem>
+          <CommandItem onSelect={() => runCommand("save")}>Save</CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  );
+}
+```
+
+### Items Deshabilitados
+
+```tsx
+<Command>
+  <CommandList>
+    <CommandGroup>
+      <CommandItem>Available Option</CommandItem>
+      <CommandItem disabled>Coming Soon</CommandItem>
+      <CommandItem disabled>Premium Feature</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+**Estilos**: `opacity-50`, `pointer-events-none`, `data-[disabled=true]`
+
+### Con Keywords para Búsqueda
+
+```tsx
+<Command>
+  <CommandInput placeholder="Search settings..." />
+  <CommandList>
+    <CommandGroup heading="Settings">
+      <CommandItem
+        value="theme"
+        keywords={["appearance", "dark", "light", "color"]}
+      >
+        Theme Settings
+      </CommandItem>
+      <CommandItem
+        value="shortcuts"
+        keywords={["keyboard", "hotkeys", "bindings"]}
+      >
+        Keyboard Shortcuts
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+**Búsqueda**: Encuentra items por `value`, `children` text, o `keywords[]`
+
+### Navegación de Páginas
+
+```tsx
+function PageSearch() {
+  const navigate = useNavigate();
+  const [open, setOpen] = useState(false);
+
+  return (
+    <CommandDialog open={open} onOpenChange={setOpen}>
+      <CommandInput placeholder="Search pages..." />
+      <CommandList>
+        <CommandGroup heading="Pages">
+          <CommandItem
+            onSelect={() => {
+              navigate("/dashboard");
+              setOpen(false);
+            }}
+          >
+            Dashboard
+          </CommandItem>
+          <CommandItem
+            onSelect={() => {
+              navigate("/settings");
+              setOpen(false);
+            }}
+          >
+            Settings
+          </CommandItem>
+          <CommandItem
+            onSelect={() => {
+              navigate("/profile");
+              setOpen(false);
+            }}
+          >
+            Profile
+          </CommandItem>
+        </CommandGroup>
+      </CommandList>
+    </CommandDialog>
+  );
+}
+```
+
+### Filtrado Custom
+
+```tsx
+// Exacto match en lugar de fuzzy
+const exactMatch = (value: string, search: string) => {
+  return value.toLowerCase().includes(search.toLowerCase()) ? 1 : 0;
+};
+
+<Command filter={exactMatch}>
+  <CommandInput placeholder="Search..." />
+  <CommandList>
+    <CommandGroup>
+      <CommandItem>Apple</CommandItem>
+      <CommandItem>Banana</CommandItem>
+      <CommandItem>Cherry</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>;
+```
+
+### Sin Filtrado Automático
+
+```tsx
+// Control manual del filtrado
+function CustomFilter() {
+  const [search, setSearch] = useState("");
+  const [filteredItems, setFilteredItems] = useState(allItems);
+
+  useEffect(() => {
+    setFilteredItems(
+      allItems.filter((item) =>
+        item.toLowerCase().includes(search.toLowerCase())
+      )
+    );
+  }, [search]);
+
+  return (
+    <Command shouldFilter={false}>
+      <CommandInput
+        value={search}
+        onValueChange={setSearch}
+        placeholder="Search..."
+      />
+      <CommandList>
+        <CommandGroup>
+          {filteredItems.map((item) => (
+            <CommandItem key={item}>{item}</CommandItem>
+          ))}
+        </CommandGroup>
+      </CommandList>
+    </Command>
+  );
+}
+```
+
+## Casos de Uso Comunes
+
+**Command palette (Cmd+K)**: Búsqueda rápida de acciones/comandos  
+**Page navigation**: Navegación rápida entre páginas  
+**File picker**: Búsqueda de archivos en proyecto  
+**Settings search**: Encontrar configuraciones  
+**Action menu**: Menú de acciones contextuales  
+**Spotlight search**: Búsqueda global tipo macOS
+
+## Estados y Data Attributes
+
+### CommandItem States
+
+- **Selected**: `data-[selected=true]` → `bg-accent`, `text-accent-foreground`
+- **Disabled**: `data-[disabled=true]` → `opacity-50`, `pointer-events-none`
+
+### Empty State
+
+- Automático cuando búsqueda no encuentra resultados
+- Personalizable con `<CommandEmpty>`
+
+## Navegación por Teclado
+
+- ✅ **Arrow Up/Down**: Navega entre items
+- ✅ **Enter**: Selecciona item enfocado
+- ✅ **Escape**: Cierra dialog (si CommandDialog)
+- ✅ **Type to search**: Filtrado automático
+- ✅ **Tab**: Sale del Command (no navega items)
+- ✅ **Home/End**: Primer/último item (si `loop={true}`)
+
+## Accesibilidad
+
+- ✅ **ARIA**: `role="combobox"` en Command, `role="option"` en items
+- ✅ **Screen readers**: Anuncia items y cuenta de resultados
+- ✅ **Keyboard navigation**: Navegación completa por teclado
+- ✅ **Focus management**: Focus visible en items seleccionados
+- ✅ **Live regions**: Anuncia cuando cambian resultados
+- ✅ **Disabled items**: `aria-disabled` en items deshabilitados
+
+## Notas de Implementación
+
+- **Basado en cmdk**: Librería `cmdk` de Paco Coursey
+- **Fuzzy search**: Búsqueda difusa por defecto (typo-tolerant)
+- **Performance**: Virtualización automática con muchos items
+- **Search icon**: Incluido automáticamente en CommandInput (Material Symbol "search")
+- **CommandDialog**: Wrapper de Command + Dialog con estilos predefinidos
+- **Data slots**: Cada componente tiene `data-slot` para CSS targeting
+- **Icon sizing**: Material Symbol icons automáticamente `text-lg` (18px) con shrink-0 y opacity-50
+- **CommandShortcut**: Elemento visual para shortcuts (no ejecuta código)
+- **Max height**: CommandList tiene `max-h-[300px]` default
+- **Scroll behavior**: `scroll-py-1` para padding al scrollear
+
+## Estilos Especiales en CommandDialog
+
+Cuando se usa en Dialog, aplica estilos adicionales:
+
+- Items con `py-3` (más padding)
+- Input con `h-12`
+- SVGs con `h-5 w-5` (más grandes)
+- Groups con heading más prominente
+
+## Troubleshooting
+
+**Búsqueda no funciona**: Verifica que `shouldFilter={true}` (default) o implementa filtrado manual  
+**Items no se ven**: Asegúrate de envolver en `<CommandList>` y `<CommandGroup>`  
+**Cmd+K no abre dialog**: Verifica que el `useEffect` esté ejecutándose y no haya conflictos con otros shortcuts  
+**Empty no aparece**: Solo se muestra cuando no hay resultados después de búsqueda  
+**Shortcuts no ejecutan**: `CommandShortcut` es solo visual, implementa lógica aparte  
+**Dialog no cierra**: Asegúrate de llamar `setOpen(false)` en `onSelect` de items  
+**Navegación circular no funciona**: Activa `loop={true}` en Command root
+
+## Referencias
+
+- **cmdk**: https://cmdk.paco.me
+- **ARIA Combobox**: https://www.w3.org/WAI/ARIA/apg/patterns/combobox/