@adamosuiteservices/ui 1.2.4 → 1.3.5

package/docs/components/ui/button-group.md

@@ -0,0 +1,1002 @@
+# Button Group Component
+
+## Descripción
+
+Componente para **agrupar botones relacionados visualmente**, creando una interfaz cohesiva donde múltiples acciones están conectadas. Soporta orientación horizontal y vertical, separadores visuales, anidamiento de grupos, integración con inputs/selects, texto descriptivo, y manejo automático de bordes/esquinas. Ideal para toolbars, controles de medios, formateo de texto y acciones relacionadas.
+
+## Características
+
+- ✅ 2 orientaciones: horizontal (default) y vertical
+- ✅ Separadores visuales entre botones (ButtonGroupSeparator)
+- ✅ Texto descriptivo dentro del grupo (ButtonGroupText)
+- ✅ Soporte para grupos anidados con spacing automático
+- ✅ Integración con Input y Select
+- ✅ Bordes y esquinas automáticamente ajustados
+- ✅ Focus z-index para overlapping correcto
+- ✅ Split button pattern (acción + dropdown)
+- ✅ Compatible con todos los tamaños de Button
+- ✅ Role="group" para accesibilidad
+- ✅ Width auto-ajustable (w-fit)
+
+## Importación
+
+```typescript
+import {
+  ButtonGroup,
+  ButtonGroupSeparator,
+  ButtonGroupText,
+} from "@adamosuiteservices/ui/button-group";
+```
+
+## Uso Básico
+
+### Grupo Horizontal Simple
+
+```tsx
+import { Button } from "@adamosuiteservices/ui/button";
+
+<ButtonGroup>
+  <Button variant="outline">Archive</Button>
+  <Button variant="outline">Report</Button>
+  <Button variant="outline">Snooze</Button>
+</ButtonGroup>;
+```
+
+**Comportamiento**: Los botones se conectan visualmente eliminando bordes internos y redondeando solo las esquinas externas.
+
+### Con Separadores
+
+```tsx
+<ButtonGroup>
+  <Button variant="secondary" size="sm">
+    Copy
+  </Button>
+  <ButtonGroupSeparator />
+  <Button variant="secondary" size="sm">
+    Paste
+  </Button>
+</ButtonGroup>
+```
+
+**Uso**: Los separadores son útiles con variantes no-outline (secondary, default, etc.) para mejorar la separación visual.
+
+### Orientación Vertical
+
+```tsx
+<ButtonGroup orientation="vertical" className="h-fit">
+  <Button variant="outline" size="icon">
+    <PlusIcon />
+  </Button>
+  <Button variant="outline" size="icon">
+    <MinusIcon />
+  </Button>
+</ButtonGroup>
+```
+
+**Nota**: Agrega `className="h-fit"` para evitar que el grupo se estire verticalmente.
+
+## Componentes
+
+### ButtonGroup (Root)
+
+Contenedor principal que agrupa botones.
+
+| Prop        | Tipo                             | Default        | Descripción                                  |
+| ----------- | -------------------------------- | -------------- | -------------------------------------------- |
+| orientation | `"horizontal" \| "vertical"`     | `"horizontal"` | Orientación del grupo                        |
+| className   | `string`                         | -              | Clases CSS adicionales                       |
+| children    | `ReactNode`                      | -              | Botones, separadores, texto, inputs, selects |
+| ...props    | `HTMLAttributes<HTMLDivElement>` | -              | Props nativas de div                         |
+
+**Atributos automáticos**:
+
+- `role="group"`: Para accesibilidad
+- `data-slot="button-group"`: Identificación interna
+- `data-orientation`: Valor de orientation prop
+
+**Estilos aplicados**:
+
+- `flex`: Display flex
+- `w-fit`: Ancho auto-ajustable
+- `items-stretch`: Estira items verticalmente
+- Bordes y esquinas ajustados automáticamente según orientation
+
+### ButtonGroupSeparator
+
+Línea separadora visual entre botones.
+
+| Prop        | Tipo                         | Default      | Descripción                    |
+| ----------- | ---------------------------- | ------------ | ------------------------------ |
+| orientation | `"horizontal" \| "vertical"` | `"vertical"` | Orientación del separador      |
+| className   | `string`                     | -            | Clases CSS adicionales         |
+| ...props    | Props de Separator           | -            | Props del componente Separator |
+
+**Estilos aplicados**:
+
+- `bg-input`: Color de fondo
+- `relative`: Posicionamiento
+- `!m-0`: Sin márgenes
+- `self-stretch`: Se estira para llenar altura/ancho
+- `h-auto` cuando orientation="vertical"
+
+**Nota**: Usa `orientation="vertical"` (default) para grupos horizontales, y `orientation="horizontal"` para grupos verticales.
+
+### ButtonGroupText
+
+Texto descriptivo dentro del grupo.
+
+| Prop      | Tipo                             | Default | Descripción                       |
+| --------- | -------------------------------- | ------- | --------------------------------- |
+| asChild   | `boolean`                        | `false` | Renderiza el hijo en lugar de div |
+| className | `string`                         | -       | Clases CSS adicionales            |
+| children  | `ReactNode`                      | -       | Texto o contenido                 |
+| ...props  | `HTMLAttributes<HTMLDivElement>` | -       | Props nativas de div              |
+
+**Estilos aplicados**:
+
+- `bg-muted`: Fondo gris claro
+- `flex items-center gap-2`: Layout flex centrado
+- `rounded-md border`: Bordes redondeados
+- `px-4`: Padding horizontal
+- `text-sm font-medium`: Tipografía
+- `shadow-xs`: Sombra sutil
+- Iconos auto-dimensionados a 16px
+
+## Orientaciones
+
+### horizontal (Default)
+
+Botones en fila horizontal.
+
+```tsx
+<ButtonGroup orientation="horizontal">
+  <Button variant="outline">First</Button>
+  <Button variant="outline">Second</Button>
+  <Button variant="outline">Third</Button>
+</ButtonGroup>
+```
+
+**Estilos automáticos**:
+
+- `:not(:first-child)`: `rounded-l-none border-l-0` (elimina esquinas izquierdas y borde)
+- `:not(:last-child)`: `rounded-r-none` (elimina esquinas derechas)
+
+### vertical
+
+Botones apilados verticalmente.
+
+```tsx
+<ButtonGroup orientation="vertical" className="h-fit">
+  <Button variant="outline">First</Button>
+  <Button variant="outline">Second</Button>
+  <Button variant="outline">Third</Button>
+</ButtonGroup>
+```
+
+**Estilos automáticos**:
+
+- `flex-col`: Dirección vertical
+- `:not(:first-child)`: `rounded-t-none border-t-0` (elimina esquinas superiores y borde)
+- `:not(:last-child)`: `rounded-b-none` (elimina esquinas inferiores)
+
+## Tamaños
+
+Todos los tamaños de Button funcionan en ButtonGroup:
+
+```tsx
+{
+  /* Small */
+}
+<ButtonGroup>
+  <Button variant="outline" size="sm">
+    Small
+  </Button>
+  <Button variant="outline" size="sm">
+    Buttons
+  </Button>
+  <Button variant="outline" size="icon-sm">
+    <PlusIcon />
+  </Button>
+</ButtonGroup>;
+
+{
+  /* Default */
+}
+<ButtonGroup>
+  <Button variant="outline">Default</Button>
+  <Button variant="outline">Buttons</Button>
+  <Button variant="outline" size="icon">
+    <PlusIcon />
+  </Button>
+</ButtonGroup>;
+
+{
+  /* Large */
+}
+<ButtonGroup>
+  <Button variant="outline" size="lg">
+    Large
+  </Button>
+  <Button variant="outline" size="lg">
+    Buttons
+  </Button>
+  <Button variant="outline" size="icon-lg">
+    <PlusIcon />
+  </Button>
+</ButtonGroup>;
+```
+
+**Regla importante**: Mantén tamaños consistentes dentro del mismo grupo.
+
+## Patrones Avanzados
+
+### Grupos Anidados
+
+Para crear toolbars complejas con espaciado entre grupos lógicos.
+
+```tsx
+<ButtonGroup>
+  <ButtonGroup>
+    <Button variant="outline" size="sm">
+      1
+    </Button>
+    <Button variant="outline" size="sm">
+      2
+    </Button>
+    <Button variant="outline" size="sm">
+      3
+    </Button>
+  </ButtonGroup>
+  <ButtonGroup>
+    <Button variant="outline" size="icon-sm">
+      <ArrowLeftIcon />
+    </Button>
+    <Button variant="outline" size="icon-sm">
+      <ArrowRightIcon />
+    </Button>
+  </ButtonGroup>
+</ButtonGroup>
+```
+
+**Comportamiento**: Los grupos anidados tienen `gap-2` automático entre ellos.
+
+### Split Button
+
+Botón con acción principal y menú dropdown.
+
+```tsx
+<ButtonGroup>
+  <Button variant="secondary">Deploy</Button>
+  <ButtonGroupSeparator />
+  <Button size="icon" variant="secondary">
+    <ChevronDownIcon />
+  </Button>
+</ButtonGroup>
+```
+
+**Uso común**: Acción por defecto + opciones adicionales en dropdown.
+
+### Con Input (Search Box)
+
+```tsx
+import { Input } from "@adamosuiteservices/ui/input";
+import { SearchIcon } from "lucide-react";
+
+<ButtonGroup>
+  <Input placeholder="Search..." />
+  <Button variant="outline" aria-label="Search">
+    <SearchIcon />
+  </Button>
+</ButtonGroup>;
+```
+
+**Comportamiento**: El input se integra visualmente con el botón, creando una barra de búsqueda cohesiva.
+
+### Con Select (Currency Selector)
+
+```tsx
+import { Input } from "@adamosuiteservices/ui/input";
+import {
+  Select,
+  SelectTrigger,
+  SelectContent,
+  SelectItem,
+} from "@adamosuiteservices/ui/select";
+import { ArrowRightIcon } from "lucide-react";
+
+function CurrencyInput() {
+  const [currency, setCurrency] = useState("$");
+
+  return (
+    <ButtonGroup>
+      <ButtonGroup>
+        <Select value={currency} onValueChange={setCurrency}>
+          <SelectTrigger className="font-mono">{currency}</SelectTrigger>
+          <SelectContent className="min-w-24">
+            <SelectItem value="$">$ US Dollar</SelectItem>
+            <SelectItem value="€">€ Euro</SelectItem>
+            <SelectItem value="£">£ British Pound</SelectItem>
+          </SelectContent>
+        </Select>
+        <Input placeholder="10.00" pattern="[0-9]*" />
+      </ButtonGroup>
+      <ButtonGroup>
+        <Button aria-label="Send" size="icon" variant="outline">
+          <ArrowRightIcon />
+        </Button>
+      </ButtonGroup>
+    </ButtonGroup>
+  );
+}
+```
+
+### Controles de Medios
+
+Player de audio/video con controles agrupados.
+
+```tsx
+import {
+  PlayIcon,
+  PauseIcon,
+  SkipBackIcon,
+  SkipForwardIcon,
+  SquareIcon,
+} from "lucide-react";
+import { VolumeXIcon, Volume2Icon } from "lucide-react";
+
+function MediaControls() {
+  const [isPlaying, setIsPlaying] = useState(false);
+
+  return (
+    <div className="space-y-4">
+      {/* Controles de reproducción */}
+      <ButtonGroup>
+        <Button variant="outline" size="icon">
+          <SkipBackIcon />
+        </Button>
+        <Button
+          variant="outline"
+          size="icon"
+          onClick={() => setIsPlaying(!isPlaying)}
+        >
+          {isPlaying ? <PauseIcon /> : <PlayIcon />}
+        </Button>
+        <Button variant="outline" size="icon">
+          <SquareIcon />
+        </Button>
+        <Button variant="outline" size="icon">
+          <SkipForwardIcon />
+        </Button>
+      </ButtonGroup>
+
+      {/* Controles de volumen */}
+      <ButtonGroup>
+        <Button variant="outline" size="icon">
+          <VolumeXIcon />
+        </Button>
+        <ButtonGroupText className="px-4">Volume</ButtonGroupText>
+        <Button variant="outline" size="icon">
+          <Volume2Icon />
+        </Button>
+      </ButtonGroup>
+    </div>
+  );
+}
+```
+
+### Editor de Texto (Toolbar)
+
+Controles de formateo con estados toggle.
+
+```tsx
+import { BoldIcon, ItalicIcon, UnderlineIcon } from "lucide-react";
+import { AlignLeftIcon, AlignCenterIcon, AlignRightIcon } from "lucide-react";
+
+function TextEditor() {
+  const [formatting, setFormatting] = useState({
+    bold: false,
+    italic: false,
+    underline: false,
+  });
+  const [alignment, setAlignment] = useState("left");
+
+  return (
+    <div className="space-y-4">
+      {/* Formato de texto */}
+      <ButtonGroup>
+        <Button
+          variant={formatting.bold ? "default" : "outline"}
+          size="icon"
+          onClick={() =>
+            setFormatting((prev) => ({ ...prev, bold: !prev.bold }))
+          }
+        >
+          <BoldIcon />
+        </Button>
+        <Button
+          variant={formatting.italic ? "default" : "outline"}
+          size="icon"
+          onClick={() =>
+            setFormatting((prev) => ({ ...prev, italic: !prev.italic }))
+          }
+        >
+          <ItalicIcon />
+        </Button>
+        <Button
+          variant={formatting.underline ? "default" : "outline"}
+          size="icon"
+          onClick={() =>
+            setFormatting((prev) => ({ ...prev, underline: !prev.underline }))
+          }
+        >
+          <UnderlineIcon />
+        </Button>
+      </ButtonGroup>
+
+      {/* Alineación */}
+      <ButtonGroup>
+        <Button
+          variant={alignment === "left" ? "default" : "outline"}
+          size="icon"
+          onClick={() => setAlignment("left")}
+        >
+          <AlignLeftIcon />
+        </Button>
+        <Button
+          variant={alignment === "center" ? "default" : "outline"}
+          size="icon"
+          onClick={() => setAlignment("center")}
+        >
+          <AlignCenterIcon />
+        </Button>
+        <Button
+          variant={alignment === "right" ? "default" : "outline"}
+          size="icon"
+          onClick={() => setAlignment("right")}
+        >
+          <AlignRightIcon />
+        </Button>
+      </ButtonGroup>
+    </div>
+  );
+}
+```
+
+### Acciones de Archivo
+
+Grupos para operaciones de archivo.
+
+```tsx
+import { SaveIcon, DownloadIcon, UploadIcon } from "lucide-react";
+import {
+  UndoIcon,
+  RedoIcon,
+  CopyIcon,
+  ShareIcon,
+  TrashIcon,
+} from "lucide-react";
+
+<div className="space-y-4">
+  {/* Acciones principales */}
+  <ButtonGroup>
+    <Button variant="outline">
+      <SaveIcon />
+      Save
+    </Button>
+    <Button variant="outline">
+      <DownloadIcon />
+      Download
+    </Button>
+    <Button variant="outline">
+      <UploadIcon />
+      Upload
+    </Button>
+  </ButtonGroup>
+
+  {/* Acciones rápidas */}
+  <ButtonGroup>
+    <Button variant="outline" size="icon">
+      <UndoIcon />
+    </Button>
+    <Button variant="outline" size="icon">
+      <RedoIcon />
+    </Button>
+    <ButtonGroupSeparator />
+    <Button variant="outline" size="icon">
+      <CopyIcon />
+    </Button>
+    <Button variant="outline" size="icon">
+      <ShareIcon />
+    </Button>
+    <ButtonGroupSeparator />
+    <Button variant="outline" size="icon">
+      <TrashIcon />
+    </Button>
+  </ButtonGroup>
+</div>;
+```
+
+### Toolbar Compleja
+
+Layout con múltiples grupos anidados.
+
+```tsx
+import {
+  ArrowLeftIcon,
+  MoreHorizontalIcon,
+  SettingsIcon,
+  RefreshCwIcon,
+} from "lucide-react";
+
+<ButtonGroup>
+  <ButtonGroup>
+    <Button variant="outline" size="icon">
+      <ArrowLeftIcon />
+    </Button>
+  </ButtonGroup>
+  <ButtonGroup>
+    <Button variant="outline">Archive</Button>
+    <Button variant="outline">Report</Button>
+  </ButtonGroup>
+  <ButtonGroup>
+    <Button variant="outline">Snooze</Button>
+    <Button variant="outline" size="icon">
+      <MoreHorizontalIcon />
+    </Button>
+  </ButtonGroup>
+  <ButtonGroup>
+    <Button variant="outline" size="icon">
+      <SettingsIcon />
+    </Button>
+    <Button variant="outline" size="icon">
+      <RefreshCwIcon />
+    </Button>
+  </ButtonGroup>
+</ButtonGroup>;
+```
+
+### Con Texto Descriptivo
+
+Etiquetas para claridad contextual.
+
+```tsx
+import { EditIcon, CopyIcon } from "lucide-react";
+
+<div className="space-y-4">
+  {/* Texto antes */}
+  <ButtonGroup>
+    <ButtonGroupText>Actions:</ButtonGroupText>
+    <Button variant="outline">Edit</Button>
+    <Button variant="outline">Delete</Button>
+  </ButtonGroup>
+
+  {/* Texto entre botones */}
+  <ButtonGroup>
+    <Button variant="outline">
+      <EditIcon />
+      Edit
+    </Button>
+    <ButtonGroupText>or</ButtonGroupText>
+    <Button variant="outline">
+      <CopyIcon />
+      Copy
+    </Button>
+  </ButtonGroup>
+</div>;
+```
+
+## Casos de Uso Comunes
+
+### Paginación
+
+```tsx
+import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
+
+<ButtonGroup>
+  <Button variant="outline" size="icon" disabled={currentPage === 1}>
+    <ChevronLeftIcon />
+  </Button>
+  <ButtonGroupText>
+    {currentPage} of {totalPages}
+  </ButtonGroupText>
+  <Button variant="outline" size="icon" disabled={currentPage === totalPages}>
+    <ChevronRightIcon />
+  </Button>
+</ButtonGroup>;
+```
+
+### Filtros
+
+```tsx
+<ButtonGroup>
+  <ButtonGroupText>Filter:</ButtonGroupText>
+  <Button
+    variant={filter === "all" ? "default" : "outline"}
+    onClick={() => setFilter("all")}
+  >
+    All
+  </Button>
+  <Button
+    variant={filter === "active" ? "default" : "outline"}
+    onClick={() => setFilter("active")}
+  >
+    Active
+  </Button>
+  <Button
+    variant={filter === "archived" ? "default" : "outline"}
+    onClick={() => setFilter("archived")}
+  >
+    Archived
+  </Button>
+</ButtonGroup>
+```
+
+### Tabs Alternativos
+
+```tsx
+<ButtonGroup>
+  <Button
+    variant={tab === "overview" ? "default" : "outline"}
+    onClick={() => setTab("overview")}
+  >
+    Overview
+  </Button>
+  <Button
+    variant={tab === "analytics" ? "default" : "outline"}
+    onClick={() => setTab("analytics")}
+  >
+    Analytics
+  </Button>
+  <Button
+    variant={tab === "reports" ? "default" : "outline"}
+    onClick={() => setTab("reports")}
+  >
+    Reports
+  </Button>
+</ButtonGroup>
+```
+
+### Vista Toggle (List/Grid)
+
+```tsx
+import { LayoutGridIcon, LayoutListIcon } from "lucide-react";
+
+<ButtonGroup>
+  <Button
+    variant={view === "grid" ? "default" : "outline"}
+    size="icon"
+    onClick={() => setView("grid")}
+    aria-label="Grid view"
+  >
+    <LayoutGridIcon />
+  </Button>
+  <Button
+    variant={view === "list" ? "default" : "outline"}
+    size="icon"
+    onClick={() => setView("list")}
+    aria-label="List view"
+  >
+    <LayoutListIcon />
+  </Button>
+</ButtonGroup>;
+```
+
+### Zoom Controls
+
+```tsx
+import { ZoomInIcon, ZoomOutIcon } from "lucide-react";
+
+<ButtonGroup>
+  <Button variant="outline" size="icon" onClick={handleZoomOut}>
+    <ZoomOutIcon />
+  </Button>
+  <ButtonGroupText className="px-6 font-mono">{zoom}%</ButtonGroupText>
+  <Button variant="outline" size="icon" onClick={handleZoomIn}>
+    <ZoomInIcon />
+  </Button>
+</ButtonGroup>;
+```
+
+## Mejores Prácticas
+
+### Consistencia de Tamaños
+
+```tsx
+{
+  /* ✅ Correcto - Tamaños consistentes */
+}
+<ButtonGroup>
+  <Button variant="outline" size="sm">
+    One
+  </Button>
+  <Button variant="outline" size="sm">
+    Two
+  </Button>
+  <Button variant="outline" size="icon-sm">
+    <PlusIcon />
+  </Button>
+</ButtonGroup>;
+
+{
+  /* ❌ Incorrecto - Mezcla de tamaños */
+}
+<ButtonGroup>
+  <Button variant="outline" size="sm">
+    One
+  </Button>
+  <Button variant="outline">Two</Button> {/* Tamaño diferente */}
+  <Button variant="outline" size="lg">
+    Three
+  </Button>
+</ButtonGroup>;
+```
+
+### Variantes Consistentes
+
+```tsx
+{
+  /* ✅ Correcto - Misma variante */
+}
+<ButtonGroup>
+  <Button variant="outline">One</Button>
+  <Button variant="outline">Two</Button>
+  <Button variant="outline">Three</Button>
+</ButtonGroup>;
+
+{
+  /* ⚠️ Permitido - Variantes diferentes para estado activo */
+}
+<ButtonGroup>
+  <Button variant={isActive ? "default" : "outline"}>Active</Button>
+  <Button variant="outline">Inactive</Button>
+</ButtonGroup>;
+```
+
+### Separadores con Variantes No-Outline
+
+```tsx
+{
+  /* ✅ Correcto - Separador con variante secondary */
+}
+<ButtonGroup>
+  <Button variant="secondary">Copy</Button>
+  <ButtonGroupSeparator />
+  <Button variant="secondary">Paste</Button>
+</ButtonGroup>;
+
+{
+  /* ⚠️ Innecesario - Separador con outline (ya hay bordes) */
+}
+<ButtonGroup>
+  <Button variant="outline">Copy</Button>
+  <ButtonGroupSeparator /> {/* No se ve bien */}
+  <Button variant="outline">Paste</Button>
+</ButtonGroup>;
+```
+
+### aria-label en Botones de Icono
+
+```tsx
+{
+  /* ✅ Correcto - Labels descriptivas */
+}
+<ButtonGroup>
+  <Button variant="outline" size="icon" aria-label="Previous page">
+    <ArrowLeftIcon />
+  </Button>
+  <Button variant="outline" size="icon" aria-label="Next page">
+    <ArrowRightIcon />
+  </Button>
+</ButtonGroup>;
+
+{
+  /* ❌ Incorrecto - Sin labels */
+}
+<ButtonGroup>
+  <Button variant="outline" size="icon">
+    <ArrowLeftIcon />
+  </Button>
+  <Button variant="outline" size="icon">
+    <ArrowRightIcon />
+  </Button>
+</ButtonGroup>;
+```
+
+### Grupos Anidados para Organización
+
+```tsx
+{
+  /* ✅ Correcto - Agrupación lógica */
+}
+<ButtonGroup>
+  <ButtonGroup>
+    {/* Acciones de navegación */}
+    <Button variant="outline" size="icon">
+      <ArrowLeftIcon />
+    </Button>
+    <Button variant="outline" size="icon">
+      <ArrowRightIcon />
+    </Button>
+  </ButtonGroup>
+  <ButtonGroup>
+    {/* Acciones de contenido */}
+    <Button variant="outline">Save</Button>
+    <Button variant="outline">Delete</Button>
+  </ButtonGroup>
+</ButtonGroup>;
+
+{
+  /* ❌ Incorrecto - Todo mezclado */
+}
+<ButtonGroup>
+  <Button variant="outline" size="icon">
+    <ArrowLeftIcon />
+  </Button>
+  <Button variant="outline">Save</Button>
+  <Button variant="outline" size="icon">
+    <ArrowRightIcon />
+  </Button>
+  <Button variant="outline">Delete</Button>
+</ButtonGroup>;
+```
+
+## Notas de Implementación
+
+- Basado en CVA (class-variance-authority) para variants
+- Usa selectores CSS avanzados para bordes/esquinas automáticas
+- Focus z-index (`focus-visible:z-10 focus-visible:relative`) previene overlap
+- Width auto-ajustable con `w-fit`
+- `items-stretch` estira items verticalmente para altura consistente
+- Separadores usan componente Separator con `self-stretch`
+- Grupos anidados detectados con `has-[>[data-slot=button-group]]` para aplicar gap
+- Input en grupo usa `flex-1` para expandirse
+- Select width ajustado con `[&>[data-slot=select-trigger]:not([class*=w-])]:w-fit`
+- Role="group" para accesibilidad semántica
+
+## Accesibilidad
+
+### Role Group
+
+```tsx
+{
+  /* ✅ Automático - role="group" aplicado */
+}
+<ButtonGroup>
+  <Button variant="outline">One</Button>
+  <Button variant="outline">Two</Button>
+</ButtonGroup>;
+```
+
+### aria-label para Grupos
+
+```tsx
+{
+  /* ✅ Correcto - Describe el propósito del grupo */
+}
+<ButtonGroup aria-label="Text alignment options">
+  <Button variant="outline" size="icon" aria-label="Align left">
+    <AlignLeftIcon />
+  </Button>
+  <Button variant="outline" size="icon" aria-label="Align center">
+    <AlignCenterIcon />
+  </Button>
+  <Button variant="outline" size="icon" aria-label="Align right">
+    <AlignRightIcon />
+  </Button>
+</ButtonGroup>;
+```
+
+### Navegación por Teclado
+
+- ✅ **Tab**: Navega entre botones del grupo
+- ✅ **Arrow keys**: No implementado por defecto (considera `role="toolbar"` si necesitas)
+- ✅ **Space/Enter**: Activa el botón enfocado
+
+### Estados Toggle
+
+```tsx
+{
+  /* ✅ Correcto - aria-pressed para toggles */
+}
+<ButtonGroup>
+  <Button
+    variant={isBold ? "default" : "outline"}
+    size="icon"
+    aria-pressed={isBold}
+    onClick={() => setIsBold(!isBold)}
+  >
+    <BoldIcon />
+  </Button>
+</ButtonGroup>;
+```
+
+### Focus Visual
+
+El focus ring se superpone correctamente gracias a `focus-visible:z-10 focus-visible:relative`.
+
+## Troubleshooting
+
+### Grupo Vertical Demasiado Alto
+
+**Problema**: El grupo vertical se estira al 100% de altura.
+
+**Solución**:
+
+```tsx
+// ❌ Problema - se estira
+<ButtonGroup orientation="vertical">
+  <Button variant="outline">One</Button>
+  <Button variant="outline">Two</Button>
+</ButtonGroup>
+
+// ✅ Solución - agrega h-fit
+<ButtonGroup orientation="vertical" className="h-fit">
+  <Button variant="outline">One</Button>
+  <Button variant="outline">Two</Button>
+</ButtonGroup>
+```
+
+### Bordes Dobles Visibles
+
+**Problema**: Se ven bordes dobles entre botones.
+
+**Solución**:
+
+```tsx
+// ❌ Problema - variantes con bordes gruesos
+<ButtonGroup>
+  <Button>One</Button>  {/* variant="default" tiene border */}
+  <Button>Two</Button>
+</ButtonGroup>
+
+// ✅ Solución - usa outline o agrega separadores
+<ButtonGroup>
+  <Button variant="outline">One</Button>
+  <Button variant="outline">Two</Button>
+</ButtonGroup>
+```
+
+### Input No Se Expande
+
+**Problema**: Input dentro del grupo no toma espacio disponible.
+
+**Solución**:
+
+```tsx
+// ✅ El input automáticamente usa flex-1
+<ButtonGroup>
+  <Input placeholder="Search..." /> {/* Se expande automáticamente */}
+  <Button variant="outline" size="icon">
+    <SearchIcon />
+  </Button>
+</ButtonGroup>
+```
+
+### Spacing entre Grupos Anidados
+
+**Problema**: No hay espacio entre grupos anidados.
+
+**Solución**:
+
+```tsx
+// ✅ El spacing se aplica automáticamente
+<ButtonGroup>
+  <ButtonGroup>
+    <Button variant="outline">1</Button>
+    <Button variant="outline">2</Button>
+  </ButtonGroup>
+  <ButtonGroup>
+    {" "}
+    {/* gap-2 automático */}
+    <Button variant="outline">3</Button>
+    <Button variant="outline">4</Button>
+  </ButtonGroup>
+</ButtonGroup>
+```
+
+## Referencias
+
+- CVA (Class Variance Authority): https://cva.style/docs
+- ARIA Group Role: https://www.w3.org/TR/wai-aria-1.2/#group
+- ARIA Toolbar: https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/
+- Button Component: Ver documentación de Button