@etus/ui 0.1.0

package/src/components/primitives/ButtonGroup/README.md

@@ -0,0 +1,945 @@
+# ButtonGroup
+
+## Visão Geral
+
+O **ButtonGroup** e um componente de layout que agrupa botoes e outros elementos interativos de forma coesa, removendo espacamentos e bordas redundantes entre os elementos adjacentes. Como componente atomico, permite criar toolbars, filtros segmentados e acoes relacionadas em uma unica unidade visual.
+
+### Casos de Uso
+
+- Toolbars com acoes relacionadas
+- Filtros segmentados (toggle group)
+- Acoes de paginacao (anterior/proximo)
+- Grupos de botoes de formatacao (bold, italic, underline)
+- Seletores de visualizacao (grid/list/table)
+- Input groups com botoes de acao
+
+### Classificacao
+
+**Categoria:** Atom (Primitivo)
+**Dependencias:** `@radix-ui/react-slot`, `class-variance-authority`, `Separator`
+
+---
+
+## Design Specs
+
+### Variantes (`orientation`)
+
+| Variante     | Uso                           | Classes                                                                                           |
+| ------------ | ----------------------------- | ------------------------------------------------------------------------------------------------- |
+| `horizontal` | Agrupamento em linha (padrao) | Remove `rounded-l` do 2o+, remove `border-l` do 2o+, remove `rounded-r` do penultimo-             |
+| `vertical`   | Agrupamento em coluna         | `flex-col`, remove `rounded-t` do 2o+, remove `border-t` do 2o+, remove `rounded-b` do penultimo- |
+
+### Sub-componentes
+
+| Componente             | Uso                  | Descricao                                   |
+| ---------------------- | -------------------- | ------------------------------------------- |
+| `ButtonGroup`          | Container principal  | Agrupa elementos com `role="group"`         |
+| `ButtonGroupText`      | Texto/label estatico | Elemento nao-interativo com estilo de botao |
+| `ButtonGroupSeparator` | Divisor visual       | Separa grupos logicos de botoes             |
+
+### Estados
+
+| Estado       | Classes/Atributos                       | Comportamento                       |
+| ------------ | --------------------------------------- | ----------------------------------- |
+| Default      | -                                       | Layout flexbox com items adjacentes |
+| Focus child  | `[&>*]:focus-visible:z-10`              | Eleva z-index do filho focado       |
+| Nested group | `has-[>[data-slot=button-group]]:gap-2` | Adiciona gap entre grupos aninhados |
+
+### Tokens Utilizados
+
+| Token                                   | Tipo       | Descrição                            |
+| --------------------------------------- | ---------- | ------------------------------------ |
+| `--button-group-root-radius`            | dimension  | Border radius do container segmented |
+| `--button-group-root-border-color`      | color      | Cor da borda do container segmented  |
+| `--button-group-root-shadow`            | shadow     | Sombra do container segmented        |
+| `--button-group-item-height`            | dimension  | Altura dos itens                     |
+| `--button-group-item-padding-x`         | dimension  | Padding horizontal dos itens         |
+| `--button-group-item-padding-y`         | dimension  | Padding vertical dos itens           |
+| `--button-group-item-gap`               | dimension  | Gap entre ícone e texto              |
+| `--button-group-item-font-size`         | dimension  | Tamanho da fonte                     |
+| `--button-group-item-font-weight`       | fontWeight | Peso da fonte                        |
+| `--button-group-item-background`        | color      | Cor de fundo padrão                  |
+| `--button-group-item-background-hover`  | color      | Cor de fundo no hover                |
+| `--button-group-item-background-active` | color      | Cor de fundo quando ativo            |
+| `--button-group-separator-color`        | color      | Cor do separador                     |
+
+### Padrão de Tokens com Tailwind v4
+
+No Tailwind v4, valores arbitrários com CSS variables precisam de type hints:
+
+```tsx
+// ✅ CORRETO - cores com color:
+bg-[color:var(--button-group-item-background)]
+bg-[color:var(--button-group-item-background-hover)]
+bg-[color:var(--button-group-item-background-active)]
+border-[color:var(--button-group-root-border-color)]
+
+// ✅ CORRETO - font-size com length:
+text-[length:var(--button-group-item-font-size)]
+
+// ✅ CORRETO - dimensões (não precisam de type hint)
+h-[var(--button-group-item-height)]
+px-[var(--button-group-item-padding-x)]
+py-[var(--button-group-item-padding-y)]
+gap-[var(--button-group-item-gap)]
+rounded-[var(--button-group-root-radius)]
+
+// ✅ CORRETO - font-weight, shadow (não precisam de type hint)
+font-[var(--button-group-item-font-weight)]
+shadow-[var(--button-group-root-shadow)]
+
+// ❌ INCORRETO - nunca usar hsl() (tokens OKLCH são valores completos)
+bg-[hsl(var(--button-group-item-background))]
+```
+
+### data-slot
+
+```html
+<div data-slot="button-group" data-orientation="horizontal" role="group">
+  <button data-slot="button">...</button>
+  <div data-slot="button-group-separator">...</div>
+  <button data-slot="button">...</button>
+</div>
+```
+
+### Logica de Bordas Adjacentes
+
+O ButtonGroup usa seletores CSS avancados para remover bordas e radius redundantes:
+
+```css
+/* Horizontal */
+[&>*:not(:first-child)]:rounded-l-none  /* Remove radius esquerdo */
+[&>*:not(:first-child)]:border-l-0      /* Remove borda esquerda */
+[&>*:not(:last-child)]:rounded-r-none   /* Remove radius direito */
+
+/* Vertical */
+[&>*:not(:first-child)]:rounded-t-none  /* Remove radius superior */
+[&>*:not(:first-child)]:border-t-0      /* Remove borda superior */
+[&>*:not(:last-child)]:rounded-b-none   /* Remove radius inferior */
+```
+
+---
+
+## API
+
+### Props - ButtonGroup
+
+| Prop          | Tipo                         | Padrao         | Descricao                    |
+| ------------- | ---------------------------- | -------------- | ---------------------------- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direcao do agrupamento       |
+| `className`   | `string`                     | -              | Classes CSS adicionais       |
+| `children`    | `ReactNode`                  | -              | Botoes e elementos a agrupar |
+| `ref`         | `Ref<HTMLDivElement>`        | -              | Referencia ao elemento DOM   |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### Props - ButtonGroupText
+
+| Prop        | Tipo        | Padrao  | Descricao                                       |
+| ----------- | ----------- | ------- | ----------------------------------------------- |
+| `asChild`   | `boolean`   | `false` | Renderiza children como elemento (polimorfismo) |
+| `className` | `string`    | -       | Classes CSS adicionais                          |
+| `children`  | `ReactNode` | -       | Conteudo do texto                               |
+
+> Herda todas as props de `React.ComponentProps<"div">`
+
+### Props - ButtonGroupSeparator
+
+| Prop          | Tipo                         | Padrao       | Descricao               |
+| ------------- | ---------------------------- | ------------ | ----------------------- |
+| `orientation` | `"horizontal" \| "vertical"` | `"vertical"` | Orientacao do separador |
+| `className`   | `string`                     | -            | Classes CSS adicionais  |
+
+> Herda todas as props do componente `Separator`
+
+### TypeScript
+
+```typescript
+import { type VariantProps } from "class-variance-authority";
+
+// Variants exportadas
+const buttonGroupVariants = cva(/* ... */);
+
+// Props do ButtonGroup
+type ButtonGroupProps = React.ComponentProps<"div"> &
+  VariantProps<typeof buttonGroupVariants>;
+
+// Props do ButtonGroupText
+type ButtonGroupTextProps = React.ComponentProps<"div"> & {
+  asChild?: boolean;
+};
+
+// Props do ButtonGroupSeparator
+type ButtonGroupSeparatorProps = React.ComponentProps<typeof Separator>;
+
+// Tipos derivados uteis
+type ButtonGroupOrientation = NonNullable<
+  VariantProps<typeof buttonGroupVariants>["orientation"]
+>;
+```
+
+### Comparativo com Design Systems de Referencia
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature              | ETUS | Shadcn | Radix | React Aria | Chakra | MUI | Mantine | AntD | NextUI | Headless | Ariakit | Fluent | Carbon | Blueprint |
+| -------------------- | :--: | :----: | :---: | :--------: | :----: | :-: | :-----: | :--: | :----: | :------: | :-----: | :----: | :----: | :-------: |
+| **Orientacao**       |  2   |   2    |   -   |     2      |   -    |  3  |    2    |  -   |   -    |    -     |    -    |   2    |   -    |     2     |
+| **CVA/cva**          |  X   |   X    |   -   |     -      |   -    |  -  |    -    |  -   |   X    |    -     |    -    |   -    |   -    |     -     |
+| **role="group"**     |  X   |   X    |   -   |     X      |   X    |  X  |    X    |  -   |   -    |    -     |    X    |   X    |   X    |     X     |
+| **data-slot**        |  X   |   X    |   -   |     -      |   -    |  -  |    -    |  -   |   X    |    -     |    -    |   -    |   -    |     -     |
+| **Separador**        |  X   |   -    |   -   |     -      |   -    |  -  |    -    |  -   |   -    |    -     |    -    |   -    |   -    |     -     |
+| **Texto/Label**      |  X   |   -    |   -   |     -      |   -    |  -  |    -    |  -   |   -    |    -     |    -    |   -    |   -    |     -     |
+| **asChild/Slot**     |  X   |   X    |   X   |     -      |   -    |  -  |    -    |  -   |   X    |    X     |    X    |   -    |   -    |     -     |
+| **attached**         |  X   |   X    |   -   |     -      |   X    |  X  |    X    |  -   |   -    |    -     |    -    |   -    |   -    |     X     |
+| **spacing**          |  -   |   -    |   -   |     -      |   -    |  X  |    -    |  -   |   -    |    -     |    -    |   X    |   -    |     X     |
+| **size herdado**     |  -   |   -    |   -   |     -      |   X    |  X  |    X    |  X   |   -    |    -     |    -    |   X    |   X    |     X     |
+| **variant herdado**  |  -   |   -    |   -   |     -      |   X    |  X  |    X    |  X   |   -    |    -     |    -    |   X    |   X    |     X     |
+| **disabled herdado** |  -   |   -    |   -   |     -      |   X    |  X  |    X    |  X   |   -    |    -     |    -    |   X    |   X    |     X     |
+| **fullWidth**        |  -   |   -    |   -   |     -      |   -    |  X  |    -    |  -   |   -    |    -     |    -    |   -    |   -    |     X     |
+
+#### Comparativo de Props por Design System
+
+| Prop               | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Fluent | Blueprint |
+| ------------------ | :--: | :----: | :-: | :-----: | :--: | :----: | :----: | :-------: |
+| `orientation`      |  X   |   -    |  X  |    X    |  -   |   -    |   X    |     X     |
+| `variant` (herdar) |  -   |   X    |  X  |    X    |  X   |   -    |   X    |     X     |
+| `size` (herdar)    |  -   |   X    |  X  |    X    |  X   |   -    |   X    |     X     |
+| `spacing`          |  -   |   X    |  -  |    -    |  -   |   -    |   X    |     X     |
+| `isAttached`       |  X   |   X    |  -  |    -    |  -   |   -    |   -    |     -     |
+| `isDisabled`       |  -   |   X    |  X  |    -    |  X   |   -    |   X    |     -     |
+| `fullWidth`        |  -   |   -    |  X  |    -    |  -   |   -    |   -    |     X     |
+| `color`            |  -   |   X    |  X  |    X    |  -   |   -    |   -    |     -     |
+
+#### Abordagens de Implementacao
+
+| Design System  | Abordagem                       | Caracteristicas                         |
+| -------------- | ------------------------------- | --------------------------------------- |
+| **ETUS**       | CSS-only (seletores adjacentes) | Sem Context, performance maxima         |
+| **Shadcn/ui**  | CSS-only (seletores adjacentes) | Mesma abordagem que ETUS                |
+| **Chakra UI**  | Context API                     | Heranca de props (size, variant)        |
+| **MUI**        | Context API + cloneElement      | Heranca completa, orientation 3 valores |
+| **Mantine**    | Context API                     | Heranca de props                        |
+| **Ant Design** | cloneElement                    | Injeta props nos filhos                 |
+| **Fluent UI**  | Context API                     | Sistema complexo de tokens              |
+| **Blueprint**  | Context API                     | Heranca + spacing                       |
+
+#### Comparativo de Nomenclatura
+
+| Feature    | ETUS                   | Chakra               | MUI           | Mantine        | Fluent        |
+| ---------- | ---------------------- | -------------------- | ------------- | -------------- | ------------- |
+| Container  | `ButtonGroup`          | `ButtonGroup`        | `ButtonGroup` | `Button.Group` | `ButtonGroup` |
+| Orientacao | `orientation`          | -                    | `orientation` | `orientation`  | `orientation` |
+| Vertical   | `"vertical"`           | `isAttached` + Stack | `"vertical"`  | `"vertical"`   | `"vertical"`  |
+| Separador  | `ButtonGroupSeparator` | -                    | -             | -              | `Divider`     |
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo           | Uso                           | Implementacao             |
+| ------------------ | ----------------------------- | ------------------------- |
+| `role="group"`     | Agrupa elementos relacionados | Automatico no ButtonGroup |
+| `aria-label`       | Descreve o proposito do grupo | Manual, recomendado       |
+| `aria-orientation` | Indica orientacao             | Via `data-orientation`    |
+
+### Suporte a Teclado
+
+| Tecla              | Acao                                                   |
+| ------------------ | ------------------------------------------------------ |
+| `Tab`              | Move foco entre botoes do grupo                        |
+| `Enter` / `Space`  | Ativa o botao focado                                   |
+| `Arrow Left/Right` | Navegacao horizontal (se implementado roving tabindex) |
+| `Arrow Up/Down`    | Navegacao vertical (se implementado roving tabindex)   |
+
+### Focus Management
+
+```tsx
+// Focus visible com z-index elevado para evitar sobreposicao
+[&>*]:focus-visible:z-10
+[&>*]:focus-visible:relative
+```
+
+### Contraste de Cores
+
+| Elemento        | Foreground     | Background | Ratio            |
+| --------------- | -------------- | ---------- | ---------------- |
+| ButtonGroupText | `--foreground` | `--muted`  | >= 4.5:1         |
+| Separator       | `--input`      | -          | N/A (decorativo) |
+
+### Screen Readers
+
+- Usar `aria-label` para descrever o proposito do grupo
+- Exemplo: `aria-label="Opcoes de formatacao"`
+- O `role="group"` anuncia os elementos como relacionados
+
+### Comparativo A11y (14 Design Systems)
+
+| Feature              |  ETUS  | React Aria | Radix | Ariakit | Headless | Chakra |  MUI   | Mantine | AntD | NextUI | Fluent | Carbon | Blueprint | PrimeReact |
+| -------------------- | :----: | :--------: | :---: | :-----: | :------: | :----: | :----: | :-----: | :--: | :----: | :----: | :----: | :-------: | :--------: |
+| **role="group"**     |   X    |     X      |   -   |    X    |    -     |   X    |   X    |    X    |  -   |   -    |   X    |   X    |     X     |     -      |
+| **aria-label**       | Manual |    Auto    |   -   |  Auto   |    -     | Manual | Manual | Manual  |  -   |   -    | Manual | Manual |  Manual   |     -      |
+| **aria-orientation** |   X    |     X      |   -   |    X    |    -     |   -    |   X    |    X    |  -   |   -    |   X    |   -    |     X     |     -      |
+| **Roving tabindex**  |   -    |     X      |   -   |    X    |    X     |   -    |   -    |    -    |  -   |   -    |   X    |   -    |     X     |     -      |
+| **Focus visible**    |   X    |     X      |   X   |    X    |    X     |   X    |   X    |    X    |  X   |   X    |   X    |   X    |     X     |     X      |
+| **Keyboard nav**     |  Tab   |   Arrows   |  Tab  | Arrows  |  Arrows  |  Tab   |  Tab   |   Tab   | Tab  |  Tab   | Arrows |  Tab   |    Tab    |    Tab     |
+
+**Legenda:** X = Suporte completo | Manual = Requer configuracao | - = Nao suportado
+
+---
+
+## Exemplos
+
+### Uso Basico
+
+```tsx
+import { Button } from "@etus/ui";
+import { ButtonGroup } from "@etus/ui";
+
+function Example() {
+  return (
+    <ButtonGroup aria-label="Acoes do documento">
+      <Button variant="outline">Salvar</Button>
+      <Button variant="outline">Editar</Button>
+      <Button variant="outline">Excluir</Button>
+    </ButtonGroup>
+  );
+}
+```
+
+### Orientacao Vertical
+
+```tsx
+<ButtonGroup orientation="vertical" aria-label="Navegacao">
+  <Button variant="outline">Pagina 1</Button>
+  <Button variant="outline">Pagina 2</Button>
+  <Button variant="outline">Pagina 3</Button>
+</ButtonGroup>
+```
+
+### Com Separador
+
+```tsx
+import { ButtonGroup, ButtonGroupSeparator } from "@etus/ui";
+
+<ButtonGroup aria-label="Acoes de edicao">
+  <Button variant="outline">Copiar</Button>
+  <Button variant="outline">Colar</Button>
+  <ButtonGroupSeparator />
+  <Button variant="outline">Desfazer</Button>
+  <Button variant="outline">Refazer</Button>
+</ButtonGroup>;
+```
+
+### Com Texto/Label
+
+```tsx
+import { ButtonGroup, ButtonGroupText } from "@etus/ui";
+
+<ButtonGroup aria-label="Filtro de status">
+  <ButtonGroupText>Status:</ButtonGroupText>
+  <Button variant="outline">Ativo</Button>
+  <Button variant="outline">Inativo</Button>
+  <Button variant="outline">Todos</Button>
+</ButtonGroup>;
+```
+
+### Com Icones
+
+```tsx
+import {
+  Bold,
+  Italic,
+  Underline,
+  AlignLeft,
+  AlignCenter,
+  AlignRight,
+} from "lucide-react";
+
+<ButtonGroup aria-label="Formatacao de texto">
+  <Button variant="outline" size="icon" aria-label="Negrito">
+    <Bold />
+  </Button>
+  <Button variant="outline" size="icon" aria-label="Italico">
+    <Italic />
+  </Button>
+  <Button variant="outline" size="icon" aria-label="Sublinhado">
+    <Underline />
+  </Button>
+  <ButtonGroupSeparator />
+  <Button variant="outline" size="icon" aria-label="Alinhar a esquerda">
+    <AlignLeft />
+  </Button>
+  <Button variant="outline" size="icon" aria-label="Centralizar">
+    <AlignCenter />
+  </Button>
+  <Button variant="outline" size="icon" aria-label="Alinhar a direita">
+    <AlignRight />
+  </Button>
+</ButtonGroup>;
+```
+
+### Diferentes Variantes de Button
+
+```tsx
+// Outline (mais comum em grupos)
+<ButtonGroup>
+  <Button variant="outline">Opcao 1</Button>
+  <Button variant="outline">Opcao 2</Button>
+  <Button variant="outline">Opcao 3</Button>
+</ButtonGroup>
+
+// Secondary
+<ButtonGroup>
+  <Button variant="secondary">Anterior</Button>
+  <Button variant="secondary">Proximo</Button>
+</ButtonGroup>
+
+// Ghost
+<ButtonGroup>
+  <Button variant="ghost">Tab 1</Button>
+  <Button variant="ghost">Tab 2</Button>
+  <Button variant="ghost">Tab 3</Button>
+</ButtonGroup>
+```
+
+### Com Select
+
+```tsx
+import { Select, SelectTrigger, SelectContent, SelectItem } from "@etus/ui";
+
+<ButtonGroup>
+  <Button variant="outline">Acao</Button>
+  <Select>
+    <SelectTrigger className="w-[120px]">
+      <span>Opcoes</span>
+    </SelectTrigger>
+    <SelectContent>
+      <SelectItem value="1">Opcao 1</SelectItem>
+      <SelectItem value="2">Opcao 2</SelectItem>
+    </SelectContent>
+  </Select>
+</ButtonGroup>;
+```
+
+### Com Input
+
+```tsx
+<ButtonGroup>
+  <Input placeholder="Buscar..." className="rounded-r-none" />
+  <Button variant="outline" size="icon" aria-label="Buscar">
+    <Search />
+  </Button>
+</ButtonGroup>
+```
+
+### Grupos Aninhados
+
+```tsx
+<ButtonGroup aria-label="Editor toolbar">
+  <ButtonGroup aria-label="Formatacao">
+    <Button variant="outline" size="icon">
+      <Bold />
+    </Button>
+    <Button variant="outline" size="icon">
+      <Italic />
+    </Button>
+  </ButtonGroup>
+  <ButtonGroup aria-label="Alinhamento">
+    <Button variant="outline" size="icon">
+      <AlignLeft />
+    </Button>
+    <Button variant="outline" size="icon">
+      <AlignCenter />
+    </Button>
+  </ButtonGroup>
+</ButtonGroup>
+```
+
+### Responsividade
+
+```tsx
+// Stack vertical em mobile, horizontal em desktop
+<ButtonGroup
+  orientation="vertical"
+  className="sm:flex-row sm:[&>*:not(:first-child)]:rounded-l-none sm:[&>*:not(:first-child)]:rounded-t-md sm:[&>*:not(:first-child)]:border-l-0 sm:[&>*:not(:first-child)]:border-t sm:[&>*:not(:last-child)]:rounded-r-none sm:[&>*:not(:last-child)]:rounded-b-md"
+>
+  <Button variant="outline">Opcao 1</Button>
+  <Button variant="outline">Opcao 2</Button>
+  <Button variant="outline">Opcao 3</Button>
+</ButtonGroup>
+
+// Full width em mobile
+<ButtonGroup className="w-full sm:w-fit">
+  <Button variant="outline" className="flex-1 sm:flex-none">Sim</Button>
+  <Button variant="outline" className="flex-1 sm:flex-none">Nao</Button>
+</ButtonGroup>
+```
+
+### ButtonGroupText com asChild
+
+```tsx
+// Como span
+<ButtonGroupText asChild>
+  <span>Prefixo</span>
+</ButtonGroupText>
+
+// Como label
+<ButtonGroupText asChild>
+  <label htmlFor="search-input">Buscar:</label>
+</ButtonGroupText>
+```
+
+---
+
+## Testes
+
+### Testes Unitarios
+
+```tsx
+// ButtonGroup.test.tsx
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Button } from "../Button";
+import {
+  ButtonGroup,
+  ButtonGroupSeparator,
+  ButtonGroupText,
+} from "./ButtonGroup";
+
+describe("ButtonGroup", () => {
+  it("renders children correctly", () => {
+    render(
+      <ButtonGroup>
+        <Button>Button 1</Button>
+        <Button>Button 2</Button>
+      </ButtonGroup>,
+    );
+    expect(
+      screen.getByRole("button", { name: "Button 1" }),
+    ).toBeInTheDocument();
+    expect(
+      screen.getByRole("button", { name: "Button 2" }),
+    ).toBeInTheDocument();
+  });
+
+  it("has role group", () => {
+    render(
+      <ButtonGroup>
+        <Button>Test</Button>
+      </ButtonGroup>,
+    );
+    expect(screen.getByRole("group")).toBeInTheDocument();
+  });
+
+  it("has data-slot attribute", () => {
+    render(
+      <ButtonGroup>
+        <Button>Test</Button>
+      </ButtonGroup>,
+    );
+    expect(screen.getByRole("group")).toHaveAttribute(
+      "data-slot",
+      "button-group",
+    );
+  });
+
+  it("applies horizontal orientation by default", () => {
+    render(
+      <ButtonGroup>
+        <Button>Test</Button>
+      </ButtonGroup>,
+    );
+    expect(screen.getByRole("group")).toHaveAttribute(
+      "data-orientation",
+      "horizontal",
+    );
+  });
+
+  it("applies vertical orientation when specified", () => {
+    render(
+      <ButtonGroup orientation="vertical">
+        <Button>Test</Button>
+      </ButtonGroup>,
+    );
+    expect(screen.getByRole("group")).toHaveAttribute(
+      "data-orientation",
+      "vertical",
+    );
+    expect(screen.getByRole("group")).toHaveClass("flex-col");
+  });
+
+  it("merges custom className", () => {
+    render(
+      <ButtonGroup className="custom-class">
+        <Button>Test</Button>
+      </ButtonGroup>,
+    );
+    expect(screen.getByRole("group")).toHaveClass("custom-class");
+  });
+});
+```
+
+### Testes de Sub-componentes
+
+```tsx
+describe("ButtonGroupText", () => {
+  it("renders text content", () => {
+    render(<ButtonGroupText>Label:</ButtonGroupText>);
+    expect(screen.getByText("Label:")).toBeInTheDocument();
+  });
+
+  it("applies default styling", () => {
+    render(<ButtonGroupText>Label:</ButtonGroupText>);
+    expect(screen.getByText("Label:")).toHaveClass("bg-muted");
+  });
+
+  it("supports asChild pattern", () => {
+    render(
+      <ButtonGroupText asChild>
+        <span data-testid="custom">Custom</span>
+      </ButtonGroupText>,
+    );
+    expect(screen.getByTestId("custom")).toHaveClass("bg-muted");
+  });
+});
+
+describe("ButtonGroupSeparator", () => {
+  it("renders separator element", () => {
+    render(<ButtonGroupSeparator data-testid="separator" />);
+    expect(screen.getByTestId("separator")).toBeInTheDocument();
+  });
+
+  it("has data-slot attribute", () => {
+    render(<ButtonGroupSeparator data-testid="separator" />);
+    expect(screen.getByTestId("separator")).toHaveAttribute(
+      "data-slot",
+      "button-group-separator",
+    );
+  });
+
+  it("defaults to vertical orientation", () => {
+    render(<ButtonGroupSeparator data-testid="separator" />);
+    expect(screen.getByTestId("separator")).toHaveAttribute(
+      "data-orientation",
+      "vertical",
+    );
+  });
+});
+```
+
+### Testes de Integracao
+
+```tsx
+describe("ButtonGroup integration", () => {
+  it("renders complete toolbar", () => {
+    render(
+      <ButtonGroup aria-label="Formatting options">
+        <Button>Bold</Button>
+        <Button>Italic</Button>
+        <ButtonGroupSeparator data-testid="separator" />
+        <Button>Align</Button>
+      </ButtonGroup>,
+    );
+
+    expect(
+      screen.getByRole("group", { name: "Formatting options" }),
+    ).toBeInTheDocument();
+    expect(screen.getAllByRole("button")).toHaveLength(3);
+    expect(screen.getByTestId("separator")).toBeInTheDocument();
+  });
+
+  it("renders with ButtonGroupText", () => {
+    render(
+      <ButtonGroup>
+        <ButtonGroupText>Filter:</ButtonGroupText>
+        <Button>Active</Button>
+        <Button>All</Button>
+      </ButtonGroup>,
+    );
+
+    expect(screen.getByText("Filter:")).toBeInTheDocument();
+    expect(screen.getAllByRole("button")).toHaveLength(2);
+  });
+});
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe";
+
+expect.extend(toHaveNoViolations);
+
+describe("ButtonGroup accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <ButtonGroup aria-label="Actions">
+        <Button>Save</Button>
+        <Button>Cancel</Button>
+      </ButtonGroup>,
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("supports aria-label", () => {
+    render(
+      <ButtonGroup aria-label="Document actions">
+        <Button>Save</Button>
+      </ButtonGroup>,
+    );
+    expect(
+      screen.getByRole("group", { name: "Document actions" }),
+    ).toBeInTheDocument();
+  });
+
+  it("children are focusable in order", () => {
+    render(
+      <ButtonGroup>
+        <Button>First</Button>
+        <Button>Second</Button>
+        <Button>Third</Button>
+      </ButtonGroup>,
+    );
+
+    const buttons = screen.getAllByRole("button");
+    buttons[0].focus();
+    expect(buttons[0]).toHaveFocus();
+  });
+
+  it("icon buttons have accessible names", async () => {
+    const { container } = render(
+      <ButtonGroup aria-label="Text formatting">
+        <Button size="icon" aria-label="Bold">
+          B
+        </Button>
+        <Button size="icon" aria-label="Italic">
+          I
+        </Button>
+      </ButtonGroup>,
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+});
+```
+
+### Testes de Layout/Visual
+
+```tsx
+describe("ButtonGroup layout", () => {
+  it("applies correct classes for horizontal layout", () => {
+    render(
+      <ButtonGroup>
+        <Button>Test</Button>
+      </ButtonGroup>,
+    );
+
+    const group = screen.getByRole("group");
+    expect(group).toHaveClass("flex");
+    expect(group).not.toHaveClass("flex-col");
+  });
+
+  it("applies correct classes for vertical layout", () => {
+    render(
+      <ButtonGroup orientation="vertical">
+        <Button>Test</Button>
+      </ButtonGroup>,
+    );
+
+    const group = screen.getByRole("group");
+    expect(group).toHaveClass("flex-col");
+  });
+
+  it("has w-fit by default", () => {
+    render(
+      <ButtonGroup>
+        <Button>Test</Button>
+      </ButtonGroup>,
+    );
+    expect(screen.getByRole("group")).toHaveClass("w-fit");
+  });
+});
+```
+
+### Cenarios Criticos
+
+```tsx
+describe("ButtonGroup edge cases", () => {
+  it("handles single child", () => {
+    render(
+      <ButtonGroup>
+        <Button>Only Button</Button>
+      </ButtonGroup>,
+    );
+    expect(screen.getByRole("button")).toBeInTheDocument();
+  });
+
+  it("handles empty group", () => {
+    render(<ButtonGroup data-testid="empty" />);
+    expect(screen.getByTestId("empty")).toBeInTheDocument();
+  });
+
+  it("handles nested ButtonGroups", () => {
+    render(
+      <ButtonGroup aria-label="Outer">
+        <ButtonGroup aria-label="Inner 1">
+          <Button>A</Button>
+          <Button>B</Button>
+        </ButtonGroup>
+        <ButtonGroup aria-label="Inner 2">
+          <Button>C</Button>
+          <Button>D</Button>
+        </ButtonGroup>
+      </ButtonGroup>,
+    );
+
+    expect(screen.getByRole("group", { name: "Outer" })).toBeInTheDocument();
+    expect(screen.getByRole("group", { name: "Inner 1" })).toBeInTheDocument();
+    expect(screen.getByRole("group", { name: "Inner 2" })).toBeInTheDocument();
+  });
+
+  it("forwards ref correctly", () => {
+    const ref = { current: null };
+    render(
+      <ButtonGroup ref={ref}>
+        <Button>Test</Button>
+      </ButtonGroup>,
+    );
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+  });
+});
+```
+
+---
+
+## Roadmap / Features Futuras
+
+Baseado na analise comparativa com 14 design systems, as seguintes features sao candidatas para implementacao futura:
+
+### Prioridade Alta
+
+#### Heranca de `size` e `variant`
+
+Propagar props para todos os botoes filhos via Context API.
+
+```tsx
+// Proposta de API
+<ButtonGroup size="sm" variant="outline">
+  <Button>Small Outline 1</Button>
+  <Button>Small Outline 2</Button>
+</ButtonGroup>
+```
+
+**Referencias:** Chakra, MUI, Mantine, AntD, Fluent UI, Carbon
+
+#### Heranca de `disabled`
+
+Desabilitar todos os botoes do grupo de uma vez.
+
+```tsx
+// Proposta de API
+<ButtonGroup disabled>
+  <Button>Disabled 1</Button>
+  <Button>Disabled 2</Button>
+</ButtonGroup>
+```
+
+**Referencias:** Chakra, MUI, AntD, Fluent UI
+
+### Prioridade Media
+
+#### Roving Tabindex
+
+Navegacao por setas entre botoes (um unico tab stop).
+
+```tsx
+// Proposta de API
+<ButtonGroup rovingTabIndex>
+  <Button>1</Button> {/* Tab para ca */}
+  <Button>2</Button> {/* Arrow Right */}
+  <Button>3</Button> {/* Arrow Right */}
+</ButtonGroup>
+```
+
+**Referencias:** React Aria, Ariakit, Headless UI, Fluent UI, Blueprint
+
+#### `spacing`
+
+Controle de espacamento entre botoes nao-attached.
+
+```tsx
+// Proposta de API
+<ButtonGroup spacing={2} attached={false}>
+  <Button>1</Button>
+  <Button>2</Button>
+</ButtonGroup>
+```
+
+**Referencias:** MUI, Fluent UI, Blueprint
+
+### Prioridade Baixa
+
+#### `fullWidth`
+
+Botoes ocupam 100% da largura disponivel.
+
+```tsx
+// Proposta de API
+<ButtonGroup fullWidth>
+  <Button>Metade 1</Button>
+  <Button>Metade 2</Button>
+</ButtonGroup>
+```
+
+**Referencias:** MUI, Blueprint
+
+### Decisoes de Design
+
+| Feature            | Recomendacao | Justificativa             |
+| ------------------ | ------------ | ------------------------- |
+| `size` herdado     | Implementar  | Alta demanda, DX melhor   |
+| `variant` herdado  | Implementar  | Consistencia visual       |
+| `disabled` herdado | Implementar  | UX em estados de loading  |
+| Roving tabindex    | Avaliar      | Complexidade vs beneficio |
+| `spacing`          | Evitar       | Usar className            |
+| `fullWidth`        | Evitar       | Usar className="w-full"   |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System   | Documentacao ButtonGroup                                                              | GitHub                                                                        |
+| --------------- | ------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| **Shadcn/ui**   | [Button](https://ui.shadcn.com/docs/components/button)                                | [shadcn-ui/ui](https://github.com/shadcn-ui/ui)                               |
+| **Radix UI**    | [Toolbar](https://www.radix-ui.com/primitives/docs/components/toolbar)                | [radix-ui/primitives](https://github.com/radix-ui/primitives)                 |
+| **React Aria**  | [ButtonGroup](https://react-spectrum.adobe.com/react-aria/ButtonGroup.html)           | [adobe/react-spectrum](https://github.com/adobe/react-spectrum)               |
+| **Chakra UI**   | [ButtonGroup](https://chakra-ui.com/docs/components/button#button-group)              | [chakra-ui/chakra-ui](https://github.com/chakra-ui/chakra-ui)                 |
+| **MUI**         | [ButtonGroup](https://mui.com/material-ui/react-button-group/)                        | [mui/material-ui](https://github.com/mui/material-ui)                         |
+| **Mantine**     | [Button.Group](https://mantine.dev/core/button/#buttongroup)                          | [mantinedev/mantine](https://github.com/mantinedev/mantine)                   |
+| **Ant Design**  | [Button](https://ant.design/components/button)                                        | [ant-design/ant-design](https://github.com/ant-design/ant-design)             |
+| **NextUI**      | [ButtonGroup](https://nextui.org/docs/components/button#button-group)                 | [nextui-org/nextui](https://github.com/nextui-org/nextui)                     |
+| **Headless UI** | -                                                                                     | [tailwindlabs/headlessui](https://github.com/tailwindlabs/headlessui)         |
+| **Ariakit**     | [Group](https://ariakit.org/components/group)                                         | [ariakit/ariakit](https://github.com/ariakit/ariakit)                         |
+| **Fluent UI**   | [ButtonGroup](https://react.fluentui.dev/?path=/docs/components-buttongroup--default) | [microsoft/fluentui](https://github.com/microsoft/fluentui)                   |
+| **Carbon**      | [ButtonSet](https://carbondesignsystem.com/components/button/usage/#button-groups)    | [carbon-design-system/carbon](https://github.com/carbon-design-system/carbon) |
+| **Blueprint**   | [ButtonGroup](https://blueprintjs.com/docs/#core/components/button-group)             | [palantir/blueprint](https://github.com/palantir/blueprint)                   |
+| **PrimeReact**  | [ButtonGroup](https://primereact.org/button/#buttongroup)                             | [primefaces/primereact](https://github.com/primefaces/primereact)             |
+
+### Especificacoes e Padroes
+
+- [WAI-ARIA APG - Toolbar Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/toolbar/)
+- [WAI-ARIA - role="group"](https://www.w3.org/TR/wai-aria-1.2/#group)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [Radix Slot](https://www.radix-ui.com/primitives/docs/utilities/slot)
+- [Lucide Icons](https://lucide.dev/icons/)