npm package: @koddaai/ui
Description: kodda Design System — CLI + Registry
Latest version: 0.1.4

# @kodda/ui

Design system interno da kodda. CLI + Registry inspirado no [shadcn/ui](https://ui.shadcn.com/).

Os componentes **não são instalados como pacote NPM**. São copiados para dentro de cada projeto via CLI, garantindo autonomia total para customização local.

## Quick Start

```bash
# Inicializar no seu projeto
npx @kodda/ui init

# Adicionar componentes
npx @kodda/ui add data-table
npx @kodda/ui add list-page

# Listar componentes disponíveis
npx @kodda/ui list
```

## Como funciona

```
npx @kodda/ui add data-table
```

A CLI consulta o registry, resolve a árvore de dependências e copia os arquivos:

```
Será instalado:
  shadcn: table, checkbox, dropdown-menu, skeleton
  kodda: filter-bar, status-badge, data-table
  npm: @tanstack/react-table

✔ 3 componentes adicionados.
```

Os arquivos ficam no seu projeto:

```
src/components/
  ui/                          # shadcn (já existente)
    table.tsx
    badge.tsx
    ...
  kodda/                      # @kodda/ui
    composites/
      data-table/
      filter-bar/
      status-badge/
    templates/
      list-page/
    hooks/
    tokens/
```

## Arquitetura

Três camadas, cada uma consome apenas a inferior:

| Camada | Descrição | Exemplos |
|--------|-----------|----------|
| **Primitivos** | shadcn/ui | Button, Input, Table, Dialog, Badge |
| **Compostos** | Combinam primitivos com layout e comportamento | DataTable, PageHeader, FilterBar, ConfirmDialog |
| **Templates** | Layouts de página completos | ListPage, DetailPage, FormPage |

## Componentes

### Compostos

| Componente | Descrição |
|------------|-----------|
| `data-table` | Tabela com filtros, paginação, sorting, seleção e ações |
| `page-header` | Cabeçalho de página com breadcrumbs e ações |
| `filter-bar` | Barra de filtros (text, select, multi-select, date-range) |
| `form-section` | Seção de formulário com grid responsivo |
| `confirm-dialog` | Dialog de confirmação com variantes (danger, warning, info) |
| `status-badge` | Badge semântico de status com cores e ícones |
| `empty-state` | Estado vazio com ícone, título e ação |
| `copy-cell` | Célula com copy-to-clipboard e truncamento |
| `currency-input` | Input com formatação de moeda (BRL, USD) |
| `entity-combobox` | Combobox genérico com busca assíncrona |
| `address-form-fields` | Campos de endereço BR com lookup de CEP |

### Templates

| Template | Descrição |
|----------|-----------|
| `list-page` | PageHeader + FilterBar + DataTable + EmptyState |
| `detail-page` | PageHeader + Tabs + Seções de detalhe |
| `form-page` | PageHeader + FormSections + Barra de ações sticky |

### Hooks

| Hook | Descrição |
|------|-----------|
| `use-data-table` | Estado do DataTable (sorting, filtering, pagination, selection) |
| `use-filters` | Estado de filtros com URL sync |
| `use-pagination` | Paginação server-side com URL sync |
| `use-debounce` | Debounce genérico |

## CLI

### `init`

Inicializa o projeto. Cria `kodda.json` e a estrutura de pastas.

```bash
npx @kodda/ui init
```

### `add`

Adiciona componentes. Resolve dependências automaticamente.

```bash
npx @kodda/ui add data-table
npx @kodda/ui add data-table page-header confirm-dialog
npx @kodda/ui add list-page  # instala template + todas as dependências
```

### `list`

Lista componentes disponíveis e instalados.

```bash
npx @kodda/ui list
```

### `update`

Atualiza componentes para a versão mais recente do registry.

```bash
npx @kodda/ui update data-table
npx @kodda/ui update --all
npx @kodda/ui update --dry-run
```

### `diff`

Mostra diferenças entre a versão local e o registry.

```bash
npx @kodda/ui diff data-table
npx @kodda/ui diff --all
```

## Uso no código

```tsx
// Primitivos shadcn (sem mudança)
import { Button } from '@/components/ui/button'

// Compostos
import { DataTable } from '@/components/kodda/composites/data-table'
import { PageHeader } from '@/components/kodda/composites/page-header'

// Templates
import { ListPage } from '@/components/kodda/templates/list-page'

// Hooks
import { useDataTable } from '@/components/kodda/hooks/use-data-table'
```

## Exemplo: página de listagem

```tsx
import { ListPage } from '@/components/kodda/templates/list-page'

const columns = [
  { accessorKey: 'name', header: 'Nome' },
  { accessorKey: 'status', header: 'Status' },
  { accessorKey: 'createdAt', header: 'Criado em' },
]

export default function SubscriptionsPage() {
  return (
    <ListPage
      title="Assinaturas"
      description="Gerencie as assinaturas dos clientes"
      breadcrumbs={[{ label: 'Dashboard', href: '/' }, { label: 'Assinaturas' }]}
      primaryAction={{ label: 'Nova assinatura', onClick: () => router.push('/new') }}
      columns={columns}
      data={subscriptions}
      pagination={{ page: 1, perPage: 20, total: 100, totalPages: 5 }}
      onPageChange={setPage}
      onSearch={setSearch}
      isLoading={isLoading}
      emptyState={{
        title: 'Nenhuma assinatura',
        description: 'Crie sua primeira assinatura para começar.',
        actionLabel: 'Nova assinatura',
        onAction: () => router.push('/new'),
      }}
    />
  )
}
```

## Desenvolvimento

```bash
# Instalar dependências
npm install

# Build da CLI
npm run build

# Watch mode
npm run dev

# Testes
npm run test

# Storybook
npm run storybook
```

### Publicando uma nova versão no npm

```bash
# 1. Certifique-se de que o working tree está limpo
git status

# 2. Incremente a versão (patch/minor/major)
npm version patch   # 0.1.1 → 0.1.2 (bug fixes)
npm version minor   # 0.1.2 → 0.2.0 (novos componentes)
npm version major   # 0.2.0 → 1.0.0 (breaking changes)

# 3. Push do commit e da tag criados pelo npm version
git push --follow-tags

# 4. Publique no npm
pnpm publish --access public
```

O `prepublishOnly` roda `pnpm build` automaticamente antes de publicar.

Para verificar:

```bash
npx @kodda/ui@latest --help
```

### Criando um novo componente

1. Implemente em `src/components/composites/<nome>/`
2. Exporte via `index.ts`
3. Adicione ao `registry/registry.json` com dependências
4. Crie story em `stories/composites/<Nome>.stories.tsx`
5. Teste: `npx @kodda/ui add <nome>` em um projeto limpo

## Documentação

- [Catálogo de Componentes](docs/component-catalog.md) — Inventário de componentes
- [Plano de Implementação](docs/implementation.md) — Fases e detalhes técnicos
- [TODO](docs/todo.md) — Checklist de tarefas

## Stack

- [React](https://react.dev/)
- [Tailwind CSS](https://tailwindcss.com/)
- [shadcn/ui](https://ui.shadcn.com/)
- [TanStack Table](https://tanstack.com/table)
- [tsup](https://tsup.egoist.dev/) (build da CLI)
- [Vitest](https://vitest.dev/) (testes)
- [Storybook](https://storybook.js.org/) (documentação)