npm package: @g4business/design-system
Description: React design system for G4 Gestão 4.0 — 40+ accessible components, design tokens, hooks, and utilities. React 19 + TypeScript + Tailwind CSS v4 + CVA.
Latest version: 0.6.6

# G4 Atlas Design System

Biblioteca de componentes React, tokens de design e utilitários para construção de interfaces consistentes nos produtos G4.

<p align="center">
  <img src="https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=white" alt="React 19" />
  <img src="https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
  <img src="https://img.shields.io/badge/Tailwind_CSS-4-06B6D4?logo=tailwindcss&logoColor=white" alt="Tailwind CSS v4" />
  <img src="https://img.shields.io/badge/Storybook-10-FF4785?logo=storybook&logoColor=white" alt="Storybook" />
</p>

---

## Índice

- [Instalação](#instalação)
- [Setup](#setup)
- [Componentes](#componentes)
- [Hooks](#hooks)
- [Utilitários](#utilitários)
- [Providers](#providers)
- [Storybook](#storybook)

---

## Instalação

O pacote é publicado no **npm público** — nenhuma configuração de autenticação é necessária.

```bash
pnpm add @g4business/design-system
# ou
npm install @g4business/design-system
```

---

## Setup

### 1. Importe os estilos

No arquivo CSS principal da sua aplicação:

```css
@import "@g4business/design-system/styles/theme";
@import "@g4business/design-system/styles/gradients"; /* opcional */
```

### 2. Configure o ThemeProvider

```tsx
import { ThemeProvider } from "@g4business/design-system";

function App() {
  return (
    <ThemeProvider defaultTheme="system">
      {/* sua aplicação */}
    </ThemeProvider>
  );
}
```

### Exports disponíveis

| Export | Conteúdo |
|---|---|
| `@g4business/design-system` | Componentes, hooks, utilitários e tipos |
| `@g4business/design-system/styles/theme` | Tema completo com variáveis CSS |
| `@g4business/design-system/styles/gradients` | Gradientes customizados |

---

## Componentes

### Foundations

| Componente | Descrição |
|---|---|
| `Logomark` | Marca G4 (`minimal`, `illustration`, `app`) |
| `Logo` | Logo completo G4 (`brand-default`, `brand-alternate`, `white`, `black`) |
| Payment Icons | Ícones de bandeiras de pagamento (Visa, Mastercard, Amex, etc.) |

### Primitives

| Componente | Descrição |
|---|---|
| `DSButton` | Botão com 10 variantes, 5 tamanhos, suporte a ícones e loading |
| `ButtonClose` | Botão de fechar (ícone X) |
| `ButtonGroup` | Agrupador de botões com bordas unificadas |
| `DSTooltip` | Tooltip acessível via React Aria |
| `Badge` | Badge com 17 cores, 3 tamanhos, dot, avatar e dismiss |
| `Avatar` | Avatar com foto, iniciais ou placeholder e indicador de status |
| `Checkbox` | Checkbox acessível com label e supporting text |
| `Switch` | Toggle switch acessível |
| `Radio` | Radio button acessível |
| `RadioGroup` | Container de agrupamento de radios |
| `Tag` | Label compacta com checkbox, avatar, dot e count |
| `Tabs` | Abas com variantes `underline`, `button` e `button-brand` |
| `TextareaField` | Campo de texto multilinha com validação |
| `ContentDivider` | Divisor horizontal com conteúdo centralizado |
| `BreadcrumbButton` | Item de breadcrumb polimórfico (button/link) |
| `Table` | Tabela composicional (`Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, `TableCell`, `TableCaption`) |
| `ProgressBar` | Barra de progresso linear |
| `ProgressCircle` | Indicador de progresso circular SVG |
| `Slider` | Slider com thumb único ou range |
| `DatePicker` | Seletor de data com calendário |
| `PaginationItem` | Botão de página individual |
| `PaginationDotIndicator` | Indicador de posição dot/bar |
| `ActivityGauge` | Gauge circular SVG com múltiplas séries |
| `BarChart` | Gráfico de barras (Recharts) |
| `LineChart` | Gráfico de linhas (Recharts) |
| `PieChart` | Gráfico pizza/donut (Recharts) |
| `RadarChart` | Gráfico radar/spider (Recharts) |

### Composed

| Componente | Descrição |
|---|---|
| `AvatarGroup` | Grupo de avatares empilhados com "+N" e botão de adicionar |
| `AvatarLabelGroup` | Avatar + título + subtítulo |
| `RadioGroupItem` | Card selecionável para uso com `RadioGroup` |
| `EditorToolbar` | Toolbar de editor de texto rico |
| `EditorColorPicker` | Seletor de cores com grid de swatches |
| `VideoPlayer` | Player de vídeo com controles customizados |
| `Breadcrumbs` | Navegação breadcrumb semântica |
| `DateRangePicker` | Seletor de intervalo de datas com presets |
| `MetricItem` | Card de KPI com sparkline e trend |
| `Pagination` | Controle de paginação (`numbers`, `simple`, `compact`, `bar`) |
| `TagInput` | Campo de input multi-tag |
| `VerificationCodeInput` | Input OTP/2FA multi-dígito |

### Patterns

| Componente | Descrição |
|---|---|
| `TextEditor` | Editor de texto rico com toolbar integrada |

---

## Hooks

| Hook | Descrição |
|---|---|
| `useBreakpoint(breakpoint)` | Retorna `true` quando o viewport atinge o breakpoint informado |
| `useBreakpoints()` | Retorna o mapa completo de breakpoints ativos |
| `useClipboard(timeoutMs?)` | Copia texto para o clipboard com feedback de estado |
| `useMask({ mask, onChange?, onChangeRaw? })` | Aplica máscaras de input (`9` dígito, `A` letra, `*` qualquer) |
| `useTextEditor({ defaultValue?, onChange? })` | Editor rich text com `contenteditable` e rastreamento de formatações |

```tsx
import { useBreakpoint, useClipboard, useMask } from "@g4business/design-system";

const isDesktop = useBreakpoint("lg");

const { copied, copy } = useClipboard(2000);

const cpfMask = useMask({ mask: "999.999.999-99", onChange: setMasked });
```

---

## Utilitários

| Utilitário | Descrição |
|---|---|
| `cn(...inputs)` | Merge de classes Tailwind sem conflitos (`clsx` + `tailwind-merge`) |
| `applyMask(value, mask)` | Aplica uma máscara a um valor bruto |
| `unmask(value, mask)` | Remove a máscara de um valor formatado |

```tsx
import { cn, applyMask, unmask } from "@g4business/design-system";

cn("p-4 bg-brand-500", isActive && "bg-brand-700", className);

applyMask("12345678901", "999.999.999-99"); // "123.456.789-01"
unmask("123.456.789-01", "999.999.999-99"); // "12345678901"
```

---

## Providers

### `ThemeProvider`

Gerencia o tema light/dark/system com persistência em `localStorage`:

```tsx
import { ThemeProvider, useTheme } from "@g4business/design-system";

<ThemeProvider defaultTheme="system" storageKey="g4-theme" darkModeClass="dark-mode">
  <App />
</ThemeProvider>

// Em qualquer componente filho
const { theme, setTheme } = useTheme();
setTheme("dark");
```

| Prop | Tipo | Default | Descrição |
|---|---|---|---|
| `defaultTheme` | `"light" \| "dark" \| "system"` | `"system"` | Tema quando nenhum está salvo |
| `storageKey` | `string` | `"ui-theme"` | Chave no localStorage |
| `darkModeClass` | `string` | `"dark-mode"` | Classe aplicada no root no modo escuro |

---

## Storybook

Todos os componentes e tokens visuais estão documentados no Storybook.  
Consulte o Storybook para explorar variantes, props e exemplos interativos de cada componente.

---

## Licença

Projeto proprietário — **G4 Gestão 4.0**. Todos os direitos reservados.