@adamosuiteservices/ui 2.11.20 → 2.12.0

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

@@ -1,984 +1,986 @@
-# 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
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<ButtonGroup orientation="vertical" className="h-fit">
-  <Button variant="outline" size="icon">
-    <Icon symbol="add" />
-  </Button>
-  <Button variant="outline" size="icon">
-    <Icon symbol="remove" />
-  </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">
-    <Icon symbol="add" />
-  </Button>
-</ButtonGroup>;
-
-{
-  /* Default */
-}
-<ButtonGroup>
-  <Button variant="outline">Default</Button>
-  <Button variant="outline">Buttons</Button>
-  <Button variant="outline" size="icon">
-    <Icon symbol="add" />
-  </Button>
-</ButtonGroup>;
-
-{
-  /* Large */
-}
-<ButtonGroup>
-  <Button variant="outline" size="lg">
-    Large
-  </Button>
-  <Button variant="outline" size="lg">
-    Buttons
-  </Button>
-  <Button variant="outline" size="icon-lg">
-    <Icon symbol="add" />
-  </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">
-      <Icon symbol="arrow_back" />
-    </Button>
-    <Button variant="outline" size="icon-sm">
-      <Icon symbol="arrow_forward" />
-    </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">
-    <Icon symbol="keyboard_arrow_down" />
-  </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 { Icon } from "@adamosuiteservices/ui/icon";
-
-<ButtonGroup>
-  <Input placeholder="Search..." />
-  <Button variant="outline" aria-label="Search">
-    <Icon symbol="search" />
-  </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 { Icon } from "@adamosuiteservices/ui/icon";
-
-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">
-          <Icon symbol="arrow_forward" />
-        </Button>
-      </ButtonGroup>
-    </ButtonGroup>
-  );
-}
-```
-
-### Controles de Medios
-
-Player de audio/video con controles agrupados.
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-function MediaControls() {
-  const [isPlaying, setIsPlaying] = useState(false);
-
-  return (
-    <div className="space-y-4">
-      {/* Controles de reproducción */}
-      <ButtonGroup>
-        <Button variant="outline" size="icon">
-          <Icon symbol="skip_previous" />
-        </Button>
-        <Button
-          variant="outline"
-          size="icon"
-          onClick={() => setIsPlaying(!isPlaying)}
-        >
-          {isPlaying ? <Icon symbol="pause" /> : <Icon symbol="play_arrow" />}
-        </Button>
-        <Button variant="outline" size="icon">
-          <Icon symbol="stop" />
-        </Button>
-        <Button variant="outline" size="icon">
-          <Icon symbol="skip_next" />
-        </Button>
-      </ButtonGroup>
-
-      {/* Controles de volumen */}
-      <ButtonGroup>
-        <Button variant="outline" size="icon">
-          <Icon symbol="volume_off" />
-        </Button>
-        <ButtonGroupText className="px-4">Volume</ButtonGroupText>
-        <Button variant="outline" size="icon">
-          <Icon symbol="volume_up" />
-        </Button>
-      </ButtonGroup>
-    </div>
-  );
-}
-```
-
-### Editor de Texto (Toolbar)
-
-Controles de formateo con estados toggle.
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-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 }))
-          }
-        >
-          <Icon symbol="format_bold" />
-        </Button>
-        <Button
-          variant={formatting.italic ? "default" : "outline"}
-          size="icon"
-          onClick={() =>
-            setFormatting((prev) => ({ ...prev, italic: !prev.italic }))
-          }
-        >
-          <Icon symbol="format_italic" />
-        </Button>
-        <Button
-          variant={formatting.underline ? "default" : "outline"}
-          size="icon"
-          onClick={() =>
-            setFormatting((prev) => ({ ...prev, underline: !prev.underline }))
-          }
-        >
-          <Icon symbol="format_underlined" />
-        </Button>
-      </ButtonGroup>
-
-      {/* Alineación */}
-      <ButtonGroup>
-        <Button
-          variant={alignment === "left" ? "default" : "outline"}
-          size="icon"
-          onClick={() => setAlignment("left")}
-        >
-          <Icon symbol="format_align_left" />
-        </Button>
-        <Button
-          variant={alignment === "center" ? "default" : "outline"}
-          size="icon"
-          onClick={() => setAlignment("center")}
-        >
-          <Icon symbol="format_align_center" />
-        </Button>
-        <Button
-          variant={alignment === "right" ? "default" : "outline"}
-          size="icon"
-          onClick={() => setAlignment("right")}
-        >
-          <Icon symbol="format_align_right" />
-        </Button>
-      </ButtonGroup>
-    </div>
-  );
-}
-```
-
-### Acciones de Archivo
-
-Grupos para operaciones de archivo.
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<div className="space-y-4">
-  {/* Acciones principales */}
-  <ButtonGroup>
-    <Button variant="outline">
-      <Icon symbol="save" />
-      Save
-    </Button>
-    <Button variant="outline">
-      <Icon symbol="download" />
-      Download
-    </Button>
-    <Button variant="outline">
-      <Icon symbol="upload" />
-      Upload
-    </Button>
-  </ButtonGroup>
-
-  {/* Acciones rápidas */}
-  <ButtonGroup>
-    <Button variant="outline" size="icon">
-      <Icon symbol="undo" />
-    </Button>
-    <Button variant="outline" size="icon">
-      <Icon symbol="redo" />
-    </Button>
-    <ButtonGroupSeparator />
-    <Button variant="outline" size="icon">
-      <Icon symbol="content_copy" />
-    </Button>
-    <Button variant="outline" size="icon">
-      <Icon symbol="share" />
-    </Button>
-    <ButtonGroupSeparator />
-    <Button variant="outline" size="icon">
-      <Icon symbol="delete" />
-    </Button>
-  </ButtonGroup>
-</div>;
-```
-
-### Toolbar Compleja
-
-Layout con múltiples grupos anidados.
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<ButtonGroup>
-  <ButtonGroup>
-    <Button variant="outline" size="icon">
-      <Icon symbol="arrow_back" />
-    </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">
-      <Icon symbol="more_horiz" />
-    </Button>
-  </ButtonGroup>
-  <ButtonGroup>
-    <Button variant="outline" size="icon">
-      <Icon symbol="settings" />
-    </Button>
-    <Button variant="outline" size="icon">
-      <Icon symbol="refresh" />
-    </Button>
-  </ButtonGroup>
-</ButtonGroup>;
-```
-
-### Con Texto Descriptivo
-
-Etiquetas para claridad contextual.
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<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">
-      <Icon symbol="edit" />
-      Edit
-    </Button>
-    <ButtonGroupText>or</ButtonGroupText>
-    <Button variant="outline">
-      <Icon symbol="content_copy" />
-      Copy
-    </Button>
-  </ButtonGroup>
-</div>;
-```
-
-## Casos de Uso Comunes
-
-### Paginación
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<ButtonGroup>
-  <Button variant="outline" size="icon" disabled={currentPage === 1}>
-    <Icon symbol="chevron_left" />
-  </Button>
-  <ButtonGroupText>
-    {currentPage} of {totalPages}
-  </ButtonGroupText>
-  <Button variant="outline" size="icon" disabled={currentPage === totalPages}>
-    <Icon symbol="chevron_right" />
-  </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 { Icon } from "@adamosuiteservices/ui/icon";
-
-<ButtonGroup>
-  <Button
-    variant={view === "grid" ? "default" : "outline"}
-    size="icon"
-    onClick={() => setView("grid")}
-    aria-label="Grid view"
-  >
-    <Icon symbol="grid_view" />
-  </Button>
-  <Button
-    variant={view === "list" ? "default" : "outline"}
-    size="icon"
-    onClick={() => setView("list")}
-    aria-label="List view"
-  >
-    <Icon symbol="list" />
-  </Button>
-</ButtonGroup>;
-```
-
-### Zoom Controls
-
-```tsx
-import { Icon } from "@adamosuiteservices/ui/icon";
-
-<ButtonGroup>
-  <Button variant="outline" size="icon" onClick={handleZoomOut}>
-    <Icon symbol="zoom_out" />
-  </Button>
-  <ButtonGroupText className="px-6 font-mono">{zoom}%</ButtonGroupText>
-  <Button variant="outline" size="icon" onClick={handleZoomIn}>
-    <Icon symbol="zoom_in" />
-  </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">
-    <Icon symbol="add" />
-  </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">
-    <Icon symbol="arrow_back" />
-  </Button>
-  <Button variant="outline" size="icon" aria-label="Next page">
-    <Icon symbol="arrow_forward" />
-  </Button>
-</ButtonGroup>;
-
-{
-  /* ❌ Incorrecto - Sin labels */
-}
-<ButtonGroup>
-  <Button variant="outline" size="icon">
-    <Icon symbol="arrow_back" />
-  </Button>
-  <Button variant="outline" size="icon">
-    <Icon symbol="arrow_forward" />
-  </Button>
-</ButtonGroup>;
-```
-
-### Grupos Anidados para Organización
-
-```tsx
-{
-  /* ✅ Correcto - Agrupación lógica */
-}
-<ButtonGroup>
-  <ButtonGroup>
-    {/* Acciones de navegación */}
-    <Button variant="outline" size="icon">
-      <Icon symbol="arrow_back" />
-    </Button>
-    <Button variant="outline" size="icon">
-      <Icon symbol="arrow_forward" />
-    </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">
-    <Icon symbol="arrow_back" />
-  </Button>
-  <Button variant="outline">Save</Button>
-  <Button variant="outline" size="icon">
-    <Icon symbol="arrow_forward" />
-  </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">
-    <Icon symbol="format_align_left" />
-  </Button>
-  <Button variant="outline" size="icon" aria-label="Align center">
-    <Icon symbol="format_align_center" />
-  </Button>
-  <Button variant="outline" size="icon" aria-label="Align right">
-    <Icon symbol="format_align_right" />
-  </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)}
-  >
-    <Icon symbol="format_bold" />
-  </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">
-    <Icon symbol="search" />
-  </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
+# 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
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<ButtonGroup orientation="vertical" className="h-fit">
+  <Button variant="outline" size="icon">
+    <Icon symbol="add" />
+  </Button>
+  <Button variant="outline" size="icon">
+    <Icon symbol="remove" />
+  </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
+- `h-10`: Altura fija de 40px (alineada con Button e Input)
+- `flex items-center gap-2`: Layout flex centrado
+- `rounded-[12px] border`: Bordes redondeados de 12px
+- `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">
+    <Icon symbol="add" />
+  </Button>
+</ButtonGroup>;
+
+{
+  /* Default */
+}
+<ButtonGroup>
+  <Button variant="outline">Default</Button>
+  <Button variant="outline">Buttons</Button>
+  <Button variant="outline" size="icon">
+    <Icon symbol="add" />
+  </Button>
+</ButtonGroup>;
+
+{
+  /* Large */
+}
+<ButtonGroup>
+  <Button variant="outline" size="lg">
+    Large
+  </Button>
+  <Button variant="outline" size="lg">
+    Buttons
+  </Button>
+  <Button variant="outline" size="icon-lg">
+    <Icon symbol="add" />
+  </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">
+      <Icon symbol="arrow_back" />
+    </Button>
+    <Button variant="outline" size="icon-sm">
+      <Icon symbol="arrow_forward" />
+    </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">
+    <Icon symbol="keyboard_arrow_down" />
+  </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 { Icon } from "@adamosuiteservices/ui/icon";
+
+<ButtonGroup>
+  <Input placeholder="Search..." />
+  <Button variant="outline" aria-label="Search">
+    <Icon symbol="search" />
+  </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 { Icon } from "@adamosuiteservices/ui/icon";
+
+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">
+          <Icon symbol="arrow_forward" />
+        </Button>
+      </ButtonGroup>
+    </ButtonGroup>
+  );
+}
+```
+
+### Controles de Medios
+
+Player de audio/video con controles agrupados.
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+function MediaControls() {
+  const [isPlaying, setIsPlaying] = useState(false);
+
+  return (
+    <div className="space-y-4">
+      {/* Controles de reproducción */}
+      <ButtonGroup>
+        <Button variant="outline" size="icon">
+          <Icon symbol="skip_previous" />
+        </Button>
+        <Button
+          variant="outline"
+          size="icon"
+          onClick={() => setIsPlaying(!isPlaying)}
+        >
+          {isPlaying ? <Icon symbol="pause" /> : <Icon symbol="play_arrow" />}
+        </Button>
+        <Button variant="outline" size="icon">
+          <Icon symbol="stop" />
+        </Button>
+        <Button variant="outline" size="icon">
+          <Icon symbol="skip_next" />
+        </Button>
+      </ButtonGroup>
+
+      {/* Controles de volumen */}
+      <ButtonGroup>
+        <Button variant="outline" size="icon">
+          <Icon symbol="volume_off" />
+        </Button>
+        <ButtonGroupText className="px-4">Volume</ButtonGroupText>
+        <Button variant="outline" size="icon">
+          <Icon symbol="volume_up" />
+        </Button>
+      </ButtonGroup>
+    </div>
+  );
+}
+```
+
+### Editor de Texto (Toolbar)
+
+Controles de formateo con estados toggle.
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+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 }))
+          }
+        >
+          <Icon symbol="format_bold" />
+        </Button>
+        <Button
+          variant={formatting.italic ? "default" : "outline"}
+          size="icon"
+          onClick={() =>
+            setFormatting((prev) => ({ ...prev, italic: !prev.italic }))
+          }
+        >
+          <Icon symbol="format_italic" />
+        </Button>
+        <Button
+          variant={formatting.underline ? "default" : "outline"}
+          size="icon"
+          onClick={() =>
+            setFormatting((prev) => ({ ...prev, underline: !prev.underline }))
+          }
+        >
+          <Icon symbol="format_underlined" />
+        </Button>
+      </ButtonGroup>
+
+      {/* Alineación */}
+      <ButtonGroup>
+        <Button
+          variant={alignment === "left" ? "default" : "outline"}
+          size="icon"
+          onClick={() => setAlignment("left")}
+        >
+          <Icon symbol="format_align_left" />
+        </Button>
+        <Button
+          variant={alignment === "center" ? "default" : "outline"}
+          size="icon"
+          onClick={() => setAlignment("center")}
+        >
+          <Icon symbol="format_align_center" />
+        </Button>
+        <Button
+          variant={alignment === "right" ? "default" : "outline"}
+          size="icon"
+          onClick={() => setAlignment("right")}
+        >
+          <Icon symbol="format_align_right" />
+        </Button>
+      </ButtonGroup>
+    </div>
+  );
+}
+```
+
+### Acciones de Archivo
+
+Grupos para operaciones de archivo.
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<div className="space-y-4">
+  {/* Acciones principales */}
+  <ButtonGroup>
+    <Button variant="outline">
+      <Icon symbol="save" />
+      Save
+    </Button>
+    <Button variant="outline">
+      <Icon symbol="download" />
+      Download
+    </Button>
+    <Button variant="outline">
+      <Icon symbol="upload" />
+      Upload
+    </Button>
+  </ButtonGroup>
+
+  {/* Acciones rápidas */}
+  <ButtonGroup>
+    <Button variant="outline" size="icon">
+      <Icon symbol="undo" />
+    </Button>
+    <Button variant="outline" size="icon">
+      <Icon symbol="redo" />
+    </Button>
+    <ButtonGroupSeparator />
+    <Button variant="outline" size="icon">
+      <Icon symbol="content_copy" />
+    </Button>
+    <Button variant="outline" size="icon">
+      <Icon symbol="share" />
+    </Button>
+    <ButtonGroupSeparator />
+    <Button variant="outline" size="icon">
+      <Icon symbol="delete" />
+    </Button>
+  </ButtonGroup>
+</div>;
+```
+
+### Toolbar Compleja
+
+Layout con múltiples grupos anidados.
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<ButtonGroup>
+  <ButtonGroup>
+    <Button variant="outline" size="icon">
+      <Icon symbol="arrow_back" />
+    </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">
+      <Icon symbol="more_horiz" />
+    </Button>
+  </ButtonGroup>
+  <ButtonGroup>
+    <Button variant="outline" size="icon">
+      <Icon symbol="settings" />
+    </Button>
+    <Button variant="outline" size="icon">
+      <Icon symbol="refresh" />
+    </Button>
+  </ButtonGroup>
+</ButtonGroup>;
+```
+
+### Con Texto Descriptivo
+
+Etiquetas para claridad contextual.
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<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">
+      <Icon symbol="edit" />
+      Edit
+    </Button>
+    <ButtonGroupText>or</ButtonGroupText>
+    <Button variant="outline">
+      <Icon symbol="content_copy" />
+      Copy
+    </Button>
+  </ButtonGroup>
+</div>;
+```
+
+## Casos de Uso Comunes
+
+### Paginación
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<ButtonGroup>
+  <Button variant="outline" size="icon" disabled={currentPage === 1}>
+    <Icon symbol="chevron_left" />
+  </Button>
+  <ButtonGroupText>
+    {currentPage} of {totalPages}
+  </ButtonGroupText>
+  <Button variant="outline" size="icon" disabled={currentPage === totalPages}>
+    <Icon symbol="chevron_right" />
+  </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 { Icon } from "@adamosuiteservices/ui/icon";
+
+<ButtonGroup>
+  <Button
+    variant={view === "grid" ? "default" : "outline"}
+    size="icon"
+    onClick={() => setView("grid")}
+    aria-label="Grid view"
+  >
+    <Icon symbol="grid_view" />
+  </Button>
+  <Button
+    variant={view === "list" ? "default" : "outline"}
+    size="icon"
+    onClick={() => setView("list")}
+    aria-label="List view"
+  >
+    <Icon symbol="list" />
+  </Button>
+</ButtonGroup>;
+```
+
+### Zoom Controls
+
+```tsx
+import { Icon } from "@adamosuiteservices/ui/icon";
+
+<ButtonGroup>
+  <Button variant="outline" size="icon" onClick={handleZoomOut}>
+    <Icon symbol="zoom_out" />
+  </Button>
+  <ButtonGroupText className="px-6 font-mono">{zoom}%</ButtonGroupText>
+  <Button variant="outline" size="icon" onClick={handleZoomIn}>
+    <Icon symbol="zoom_in" />
+  </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">
+    <Icon symbol="add" />
+  </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">
+    <Icon symbol="arrow_back" />
+  </Button>
+  <Button variant="outline" size="icon" aria-label="Next page">
+    <Icon symbol="arrow_forward" />
+  </Button>
+</ButtonGroup>;
+
+{
+  /* ❌ Incorrecto - Sin labels */
+}
+<ButtonGroup>
+  <Button variant="outline" size="icon">
+    <Icon symbol="arrow_back" />
+  </Button>
+  <Button variant="outline" size="icon">
+    <Icon symbol="arrow_forward" />
+  </Button>
+</ButtonGroup>;
+```
+
+### Grupos Anidados para Organización
+
+```tsx
+{
+  /* ✅ Correcto - Agrupación lógica */
+}
+<ButtonGroup>
+  <ButtonGroup>
+    {/* Acciones de navegación */}
+    <Button variant="outline" size="icon">
+      <Icon symbol="arrow_back" />
+    </Button>
+    <Button variant="outline" size="icon">
+      <Icon symbol="arrow_forward" />
+    </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">
+    <Icon symbol="arrow_back" />
+  </Button>
+  <Button variant="outline">Save</Button>
+  <Button variant="outline" size="icon">
+    <Icon symbol="arrow_forward" />
+  </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`
+- Select último con aria-hidden usa `rounded-r-[12px]` para consistencia
+- 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">
+    <Icon symbol="format_align_left" />
+  </Button>
+  <Button variant="outline" size="icon" aria-label="Align center">
+    <Icon symbol="format_align_center" />
+  </Button>
+  <Button variant="outline" size="icon" aria-label="Align right">
+    <Icon symbol="format_align_right" />
+  </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)}
+  >
+    <Icon symbol="format_bold" />
+  </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">
+    <Icon symbol="search" />
+  </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