# @pulse-libs/core — Biblioteca Universal Atomizada

> **React · Hooks · Utils · Validators** em um único pacote  
> `npm install @pulse-libs/core`

---

## 📐 Estrutura real do projeto

```
@pulse-libs/core
├── src/
│   ├── types/         → Result / AsyncState / Paginated / SortConfig  (zero deps)
│   ├── utils/         → date, str, num, cn, debounce, throttle, storage, arr, obj  (zero deps)
│   ├── validators/    → Zod schemas: email, password, uuid, url, phone, CPF/CNPJ
│   ├── hooks/         → useToggle, useAsync, useDebounce, useLocalStorage, useMedia, useInterval, useOnClickOutside, useClipboard, useFetch
│   ├── components/    → Button, Input, Alert, Card (+Header/Title/Body), Spinner  (React)
│   └── index.ts       → barrel export principal
├── tests/             → vitest + jsdom — 57 testes, 100% passando
├── dist/              → ESM + CJS + DTS + sourcemaps (gerado por tsup v8)
├── Dockerfile         → multi-stage Node 20 Alpine
├── __docs__/          → guias de deploy, docker, arquitetura
└── package.json       → sub-exports por camada
```

## 📦 Imports por camada

```tsx
// ── Root barrel
import { Button, useAsync, date, cn } from '@pulse-libs/core';

// ── Sub-exports (tree-shakeable)
import { Button, Input, Alert }       from '@pulse-libs/core/components';
import { useToggle, useDebounce }      from '@pulse-libs/core/hooks';
import { cn, date, str, num, storage } from '@pulse-libs/core/utils';
import { emailSchema, safeParse }      from '@pulse-libs/core/validators';
import type { Result, AsyncState }     from '@pulse-libs/core/types';
```

## 🏗️ Filosofia atômica

Uma camada **nunca importa de uma camada de nível inferior**:

```
utils   ← zero deps
types   ← zero deps
validators ← usa utils, types, zod
hooks   ← usa utils, types, react
components ← usa utils, validators
```

### Convenções de código

| Regra | Por quê |
|-------|---------|
| `className` sempre no topo dos props | Tailwind merge via `cn()` |
| `...rest` sempre por último | Não mata props nativas |
| Funções puras em `utils/` | Testáveis sem setup |
| Schema Zod é a **única** fonte de verdade | Sem validação duplicada |
| DTS arquivos declarados (`--dts`) | Imports no TS dos consumidores |
| `flat(2)` nunca `flat(Infinity)` | Quebra DTS generate |

## 🔄 Versionamento

| Fase | Tag | Significado |
|------|-----|-------------|
| alpha | `1.0.0-alpha.x` | API instável |
| beta | `1.0.0-beta.x` | feature-complete, API pode mudar |
| stable | `1.0.0` | API congelada, sem breaking em minor |

## 🚀 Comandos

```bash
npm run build        # tsup ESM+CJS+DTS+sourcemaps
npm run build:esm    # ESM only
npm run build:cjs    # CJS only
npm test             # vitest run (57 testes)
npm test:w           # vitest watch mode
npm run coverage     # relatorio de cobertura
npm run typecheck    # tsc --noEmit
npm run lint         # eslint (se configurado)
npm run dev          # tsup --watch
npm run clean        # rm -rf dist coverage .tsup
npm run release      # bumpp + git push --follow-tags
```

## 🐳 Docker

```bash
# Build image
docker build -t pulse-libs/core:1.0.0-beta.1 .

# Ou com docker-compose
docker compose build

# Test local
docker compose run core npm test
```

## 📚 Documentação adicional

- [`__docs__/docker/build-guide.md`](__docs__/docker/build-guide.md) — Guia de build e publish Docker
- [`__docs__/docker/architecture.md`](__docs__/docker/architecture.md) — Arquitetura da biblioteca

## 🤝 Contribuir

- Issues com tag `[bug]`, `[feat]`, `[docs]`
- PRs devem Rodar `npm test` + `npm run typecheck` antes
- Cada camada nova precisa de pelo menos 1 teste unitário
- Breaking changes só em major version (`2.0.0`, `3.0.0`, …)
- Sem duplicação de lógica — extrair para utils antes de adicionar