---

# access-control.md

# Access Control (RBAC)

Checagens de **permissão e papel** para esconder ou bloquear ações que o usuário não pode executar. Enquanto o [`AuthGuard`](./auth.md) responde só "está logado?", o Access Control responde "esse usuário pode **excluir um post**?" — granularidade de `<resource>:<action>`.

!!! info "Por que isso existe além do `AuthGuard`?"
    `AuthGuard` é binário: autenticado ou não. Mas dentro de um app logado, um editor pode criar posts e um leitor não; um admin vê o botão de excluir e o resto não. Esconder esses controles na UI (e idealmente bloquear no backend) é trabalho de RBAC. O Access Control entrega um contrato plugável (`AccessControl`), uma estratégia pronta baseada em papéis, e os utilitários de UI (`useCan`, `<Can>`) para amarrar tudo.

!!! warning "RBAC no frontend é UX, não segurança"
    Esconder um botão **não** protege o endpoint. A decisão de permissão que importa acontece no backend (no `tempest-fastapi-sdk`). O Access Control aqui melhora a experiência — evita mostrar ações que vão falhar com 403 — mas o servidor continua sendo a fonte da verdade.

## Quando usar

- Esconder/desabilitar botões e links conforme a permissão (`<Can>`).
- Ramificar lógica por permissão dentro de um componente (`useCan`).
- Derivar o conjunto de permissões do usuário a partir do JWT (`permissionsFromToken`).

## Provider — `<AccessControlProvider>`

Envolva o app com `<AccessControlProvider control={…}>`, passando uma estratégia `AccessControl`. Toda checagem (`useCan`, `<Can>`) lê dessa estratégia via contexto:

```tsx
import { AccessControlProvider, createRoleAccessControl } from "tempest-react-sdk";
import { App } from "./App";

const accessControl = createRoleAccessControl({
  role: "editor",
  roles: {
    editor: ["posts:create", "posts:update", "comments:read"],
    admin: ["*"],
  },
});

export function Root() {
  return (
    <AccessControlProvider control={accessControl}>
      <App />
    </AccessControlProvider>
  );
}
```

!!! note "Sem provider → libera tudo"
    Se **nenhum** `<AccessControlProvider>` estiver acima na árvore, `useCan`/`<Can>` tratam toda checagem como **permitida**. Isso mantém o SDK opt-in: você liga a aplicação dropando um provider, e desliga removendo-o. Útil em dev ou em apps sem RBAC ainda — os componentes que usam `<Can>` continuam funcionando, só não bloqueiam nada.

## `createRoleAccessControl`

Constrói uma estratégia RBAC a partir de um conjunto estático de permissões. A assinatura é `createRoleAccessControl({ permissions?, roles?, role? })`:

- `permissions` — strings concedidas diretamente, independente de papel.
- `roles` — mapa `nome do papel → permissões` que aquele papel concede.
- `role` — o(s) papel(éis) ativo(s) (string ou array). As permissões deles (de `roles`) são mescladas.

O conjunto efetivo é `permissions` **mais**, para cada papel ativo em `role`, as permissões listadas em `roles[role]`.

### Regras de matching

Cada permissão é uma string `"<resource>:<action>"` (ex.: `"posts:create"`) ou um `"<action>"` sozinho. Os curingas:

| Permissão concedida | O que libera                                              |
| ------------------- | -------------------------------------------------------- |
| `"*"`               | **tudo** — qualquer action em qualquer resource          |
| `"posts:*"`         | qualquer action no resource `posts`                      |
| `"posts:create"`    | exatamente a action `create` no resource `posts`         |
| `"export"`          | a action global `export` (checagem **sem** `resource`)   |

```ts
import { createRoleAccessControl } from "tempest-react-sdk";

const ac = createRoleAccessControl({
  role: "editor",
  roles: { editor: ["posts:*", "comments:read"] },
});

ac.can({ action: "create", resource: "posts" }); // { can: true } — bate em "posts:*"
ac.can({ action: "read", resource: "comments" }); // { can: true } — bate exato
ac.can({ action: "delete", resource: "users" }); // { can: false, reason: "missing permission" }
```

!!! tip "Combine `permissions` e `roles`"
    `permissions` é para concessões diretas (um override pontual num usuário específico), `roles` + `role` é para o caso comum baseado em papel. Os dois se somam — uma permissão direta vale mesmo que nenhum papel a conceda.

## `permissionsFromToken` — permissões a partir do JWT

Em vez de manter a lista de permissões à mão, derive-a do JWT do usuário. `permissionsFromToken(token, { claim })`:

- Lê a claim configurada (default `"permissions"`).
- Se ausente, cai para as claims OAuth `"scopes"` e depois `"scope"`.
- Claim em array é usada como está; claim em string é quebrada por espaços (convenção de `scope` OAuth).
- Retorna `[]` em qualquer falha de decode ou quando nenhuma claim reconhecível existe.

```ts
import { createRoleAccessControl, permissionsFromToken } from "tempest-react-sdk";

const token = getAccessTokenFromSomewhere();

// Lê a claim "permissions" (default), caindo para "scopes"/"scope"
const permissions = permissionsFromToken(token);

const accessControl = createRoleAccessControl({ permissions });
```

!!! warning "`permissionsFromToken` não valida assinatura"
    Ele só decodifica o payload do JWT (via `decodeJWT`) para ler a claim — **não** verifica a assinatura. É leitura defensiva para UX, igual ao [`decodeJWT`](./auth.md). Confiar nessas permissões para segurança real é trabalho do backend.

Para uma claim custom (ex.: o backend emite `"perms"`):

```ts
const permissions = permissionsFromToken(token, { claim: "perms" });
```

## `useCan` — checagem programática

`useCan({ action, resource })` resolve a checagem contra a estratégia em contexto e devolve `{ allowed, isLoading, reason }`. Funciona com `can` síncrono (boolean ou `CanResult`) e com `Promise` (políticas remotas), re-rodando quando os params mudam:

```tsx
import { useCan } from "tempest-react-sdk";

export function PostActions({ postId }: { postId: string }) {
  const { allowed, isLoading } = useCan({ action: "update", resource: "posts" });

  if (isLoading) return null; // checagem assíncrona em andamento

  return (
    <button disabled={!allowed} onClick={() => editPost(postId)}>
      Editar
    </button>
  );
}
```

!!! note "`reason` explica o `false`"
    Quando `allowed` é `false`, `reason` costuma trazer o motivo (`"missing permission"` vindo do `createRoleAccessControl`, ou a mensagem de erro de uma política async que rejeitou). Útil para tooltip ("Você não tem permissão para X") em vez de só esconder.

## `<Can>` — render condicional

`<Can action resource fallback>` renderiza `children` quando a action é permitida, senão o `fallback` (ou nada). Enquanto uma checagem async está pendente, renderiza o `fallback` (ou nada):

```tsx
import { Can } from "tempest-react-sdk";

<Can action="create" resource="posts" fallback={<p>Sem permissão para criar.</p>}>
  <NewPostButton />
</Can>;
```

## `useAccessControl` — a estratégia crua

Quando você precisa da estratégia em si (chamar `can` fora de render, checar
várias permissões num loop, decidir uma rota antes de montar a árvore),
`useAccessControl()` devolve o `AccessControl` do contexto — ou `null` quando
não há provider:

```tsx
import { useAccessControl } from "tempest-react-sdk";

function useBulkPermissions(ids: string[]) {
  const control = useAccessControl();

  return ids.filter((id) => control?.can({ action: "delete", resource: "posts", params: { id } }) ?? true);
}
```

!!! danger "`null` significa **permitir**, não negar"
    Sem provider na árvore, `useAccessControl()` devolve `null` — e a convenção
    do SDK é tratar isso como "libera tudo", igual ao `useCan`/`<Can>`. Escrever
    `control?.can(...) ?? false` inverte a regra e trava o app inteiro em
    qualquer ambiente que ainda não montou o provider. O `?? true` do exemplo
    não é descuido.

## Exemplo completo — botão "Excluir" protegido

Tudo junto: deriva permissões do JWT, configura a estratégia, e protege a ação de excluir tanto por render (`<Can>`) quanto por estado desabilitado (`useCan`):

```tsx
import {
  AccessControlProvider,
  Can,
  createRoleAccessControl,
  permissionsFromToken,
  useCan,
} from "tempest-react-sdk";

// 1. Estratégia derivada do JWT do usuário logado.
function buildAccessControl(token: string) {
  return createRoleAccessControl({
    // ex.: token com { permissions: ["posts:read", "posts:delete"] }
    permissions: permissionsFromToken(token),
  });
}

// 2. Provider no topo do app.
export function Root({ token }: { token: string }) {
  return (
    <AccessControlProvider control={buildAccessControl(token)}>
      <PostRow id="post-1" title="Olá mundo" />
    </AccessControlProvider>
  );
}

// 3a. Esconder a ação inteira com <Can>.
function PostRow({ id, title }: { id: string; title: string }) {
  return (
    <div>
      <span>{title}</span>
      <Can action="delete" resource="posts" fallback={null}>
        <DeleteButton id={id} />
      </Can>
    </div>
  );
}

// 3b. Mostrar sempre, mas desabilitar + explicar com useCan.
function DeleteButton({ id }: { id: string }) {
  const { allowed, isLoading, reason } = useCan({ action: "delete", resource: "posts" });

  return (
    <button
      disabled={!allowed || isLoading}
      title={allowed ? "Excluir post" : reason}
      onClick={() => deletePost(id)}
    >
      Excluir
    </button>
  );
}
```

!!! tip "`<Can>` esconde; `useCan` desabilita"
    Use `<Can>` quando a ação simplesmente não deve existir para quem não pode (limpa a UI). Use `useCan` quando você quer manter o controle visível mas inerte, com um `title`/tooltip explicando o porquê — útil para descoberta ("isso existe, mas precisa de outro papel").

## Recap

- `<AccessControlProvider control={…}>` injeta uma estratégia `AccessControl`; **sem provider, toda checagem libera** (opt-in).
- `createRoleAccessControl({ permissions, roles, role })` monta RBAC estático; matching por `"<resource>:<action>"`, com curingas `"*"` (tudo) e `"<resource>:*"` (resource inteiro).
- `permissionsFromToken(token, { claim })` lê permissões do JWT (claim default `"permissions"`, fallback `"scopes"`/`"scope"`); não valida assinatura.
- `useCan({ action, resource })` → `{ allowed, isLoading, reason }`, com suporte a checagens síncronas e assíncronas.
- `<Can action resource fallback>` esconde a UI; `useCan` desabilita e explica com `reason`.
- RBAC no frontend é UX — o backend continua sendo a fonte da verdade da autorização.

## Veja também

- [Auth + Guard](./auth.md) — `AuthGuard` (autenticado?) e `decodeJWT`/`isJWTExpired`
- [Data Provider](./data-provider.md) — proteja as ações de CRUD por papel/permissão

---

# app-providers.md

# AppProviders

Todo app React precisa de um punhado de _providers_ no topo da árvore: cache de
dados, tema, internacionalização, captura de erros. `<AppProviders>` reúne todos
eles em **um único bloco declarativo** — você diz o que quer ligado e como
configurar, e o SDK monta a pirâmide na ordem certa pra você. 🚀

## O problema: a pirâmide de providers

Sem o `<AppProviders>`, a raiz da sua aplicação costuma virar uma pirâmide
aninhada à mão. Você precisa lembrar **quais** providers existem, **a ordem**
certa de aninhamento e repetir isso em todo projeto:

```tsx
// App.tsx — montagem manual (o que queremos evitar)
import {
  ErrorBoundary,
  QueryProvider,
  ThemeProvider,
  I18nProvider,
  AppRouter,
} from "tempest-react-sdk";
import { routes } from "@/routes";

export function App() {
  return (
    <ErrorBoundary fallback={<p>Something went wrong.</p>}>
      <QueryProvider>
        <ThemeProvider>
          <I18nProvider locale="pt-BR" messages={messages}>
            <AppRouter routes={routes} fallback={<p>Loading…</p>} />
          </I18nProvider>
        </ThemeProvider>
      </QueryProvider>
    </ErrorBoundary>
  );
}
```

Funciona, mas é frágil: a ordem importa (o `ErrorBoundary` precisa ficar por
fora pra capturar erros dos providers internos), o aninhamento cresce em
diagonal e cada app reescreve a mesma estrutura.

!!! note "Os providers continuam existindo isolados"

    `QueryProvider`, `ThemeProvider`, `I18nProvider` e `ErrorBoundary` seguem
    exportados individualmente — use-os direto quando precisar de controle fino.
    O `<AppProviders>` é só a conveniência que conecta os quatro pra você.

## A solução: um bloco só

```tsx
// App.tsx
import { AppProviders, AppRouter } from "tempest-react-sdk";
import { routes } from "@/routes";

export function App() {
  return (
    <AppProviders errorBoundary={{ fallback: <p>Something went wrong.</p> }}>
      <AppRouter routes={routes} fallback={<p>Loading…</p>} />
    </AppProviders>
  );
}
```

É isso. O `<AppProviders>` aninha tudo de fora pra dentro nesta ordem:

```text
ErrorBoundary → QueryProvider → ThemeProvider → I18nProvider → children
```

Repare que **Query e Theme já vêm ligados** com os defaults do SDK — você não
precisou configurar nada. Só pedimos o `errorBoundary` porque ele é opcional
(veja abaixo).

!!! tip "Onde o `<AppProviders>` mora"

    Os providers ficam **por fora** do roteamento; o `<AppRouter>` (e portanto
    todas as suas rotas) fica **por dentro**. Assim cada página tem acesso a
    cache, tema e i18n, e qualquer erro de renderização de qualquer rota cai no
    `ErrorBoundary`. Veja a página de roteamento pra detalhes do `<AppRouter>`.

## O que vem ligado por padrão vs. opt-in

| Prop            | Estado padrão      | Como ligar / configurar                  |
| --------------- | ------------------ | ---------------------------------------- |
| `query`         | **Ligado**         | Já ativo. Passe um objeto pra ajustar.   |
| `theme`         | **Ligado**         | Já ativo. Passe um objeto pra ajustar.   |
| `i18n`          | Desligado (opt-in) | Passe `{ locale, messages }` pra montar. |
| `errorBoundary` | Desligado (opt-in) | Passe `{ fallback }` pra montar.         |

- **`query`** e **`theme`** já estão ativos com os defaults do SDK — o caso
  comum (você quer cache de dados e tema) não exige nenhuma configuração.
- **`i18n`** e **`errorBoundary`** só entram na árvore quando você passa a prop
  correspondente. Omitiu? O provider simplesmente não é montado.

!!! info "Defaults de query"

    Quando ligado por padrão, o `QueryProvider` usa: `staleTime` de 5 minutos,
    `gcTime` de 30 minutos, `retry: 1` e `refetchOnWindowFocus: false`.

## Desligando um padrão com `false`

Às vezes o app já monta o seu próprio `QueryClient`, ou você não quer o tema do
SDK. Passe `false` na prop pra **remover aquele provider** da árvore:

```tsx
// query e theme desligados — o app monta os seus por fora
import { AppProviders } from "tempest-react-sdk";

export function App() {
  return (
    <AppProviders query={false} theme={false}>
      <YourOwnProviders />
    </AppProviders>
  );
}
```

!!! warning "`false` remove o provider — não o desativa silenciosamente"

    Com `query={false}`, nenhum `QueryClient` é montado pelo `<AppProviders>`.
    Se algum componente filho usar `useQuery`, ele precisa de um provider montado
    por você mais acima na árvore — senão o React Query lança erro em runtime.

## Ajustando cada provider

Cada prop aceita um objeto com as mesmas opções do provider isolado (menos
`children`, que o `<AppProviders>` controla).

### Query

```tsx
import { AppProviders } from "tempest-react-sdk";

<AppProviders query={{ defaultOptions: { queries: { retry: 3 } } }}>
  <App />
</AppProviders>;
```

Você também pode passar um `client` (`QueryClient`) já configurado em vez de
`defaultOptions`.

### Theme

```tsx
import { AppProviders } from "tempest-react-sdk";

<AppProviders theme={{ defaultTheme: "dark", storageKey: "my-app-theme" }}>
  <App />
</AppProviders>;
```

### i18n

```tsx
import { AppProviders } from "tempest-react-sdk";

const messages = {
  "pt-BR": { hello: "Olá" },
  "en-US": { hello: "Hello" },
};

<AppProviders i18n={{ locale: "pt-BR", messages, fallbackLocale: "en-US" }}>
  <App />
</AppProviders>;
```

`i18n` aceita `locale`, `messages`, e opcionalmente `fallbackLocale` e
`storageKey`.

## A fallback do ErrorBoundary

A prop `errorBoundary` aceita `fallback` em duas formas: um `ReactNode` fixo, ou
uma **função de render** que recebe `{ error, reset }` — útil pra mostrar a
mensagem do erro e oferecer um botão de "tentar de novo":

```tsx
import { AppProviders } from "tempest-react-sdk";

<AppProviders
  errorBoundary={{
    fallback: ({ error, reset }) => <button onClick={reset}>{error.message}</button>,
  }}
>
  <App />
</AppProviders>;
```

Além de `fallback`, você pode passar `onError` (callback ao capturar) e
`resetKeys` (valores que, ao mudarem, resetam o boundary automaticamente).

## Exemplo completo: todas as props juntas

Aqui está tudo em ação — query ajustada, tema desligado, i18n montado e
error boundary com função de render:

```tsx
import { AppProviders } from "tempest-react-sdk";

const messages = {
  "pt-BR": { hello: "Olá" },
  "en-US": { hello: "Hello" },
};

export function Root() {
  return (
    <AppProviders
      query={{ defaultOptions: { queries: { retry: 3 } } }}
      theme={false}
      i18n={{ locale: "pt-BR", messages }}
      errorBoundary={{
        fallback: ({ error, reset }) => <button onClick={reset}>{error.message}</button>,
      }}
    >
      <App />
    </AppProviders>
  );
}
```

## Recap

- `<AppProviders>` substitui a pirâmide manual de providers por **um bloco
  declarativo**, aninhando de fora pra dentro: `ErrorBoundary → QueryProvider →
ThemeProvider → I18nProvider → children`. ✅
- **`query` e `theme` vêm ligados** com os defaults do SDK; **`i18n` e
  `errorBoundary` são opt-in** — só montam quando você passa a prop.
- Passe `false` em `query` ou `theme` pra **remover** aquele provider (quando o
  app monta o seu próprio).
- Passe um **objeto** em qualquer prop pra ajustar o provider correspondente.
- A `fallback` do error boundary pode ser um `ReactNode` ou uma **função** que
  recebe `{ error, reset }`.
- Coloque o `<AppProviders>` **por fora** do `<AppRouter>`: providers fora,
  rotas dentro. 💡

---

# architecture.md

# Arquitetura

O `tempest-react-sdk` é um pacote único com camadas independentes. O consumidor
importa só o que usa; tudo é externalizado no bundle do SDK, então o bundler do
app faz tree-shake do que não é referenciado.

!!! info "Esta página é a arquitetura **do pacote**"
    Aqui você aprende como o SDK é montado — camadas, dependências, subpaths,
    bundle. Se o que você quer é como organizar o **seu app** (camadas, pastas,
    onde mora cada estado, limites de arquivo), a página é
    [Camadas de um app frontend](./design/architecture.md), na aba
    [Design de Software](./design/index.md).

!!! tip "Importe só o que usa"
    Não existe penalidade por o SDK ser grande. Cada camada (HTTP, auth, query,
    forms…) é independente — se você nunca importa `createOfflineStore`, o `dexie`
    não entra no seu bundle. Comece com um `Button` e cresça a partir daí.

> Diagrama editável: [architecture.drawio](./diagrams/architecture.drawio) (abra no [draw.io](https://app.diagrams.net)).

## Escopo: só client-side

O SDK é feito para **SPA client-rendered com capacidade offline** — service
worker, outbox no IndexedDB, prompt de instalação, background sync. Ele **não**
suporta SSR nem React Server Components: nenhum módulo declara `"use client"` e
os componentes assumem que montam num browser. O App Router do Next não é alvo.

!!! warning "Isso é escolha de escopo, não lacuna"
    Cobrir os dois mundos custaria em cada API (dois caminhos de render,
    hidratação, `window` proibido no topo do módulo) e o offline-first — a razão
    de existir do pacote — sairia pior. Os guards
    `typeof window === "undefined"` que existem nos hooks servem pra não explodir
    fora do browser (testes em Node, contexto de service worker, plugin de
    build), não pra prometer render no servidor.


## Camadas

### Fundação de aplicação

A base opinativa que monta um app React inteiro. É o que a CLI
[`create-tempest-app`](./scaffold.md) gera.

| Camada                 | O que faz                                                                             | Página                           |
| ---------------------- | ------------------------------------------------------------------------------------- | -------------------------------- |
| **Vite (`vite/`)**     | `createViteConfig` — plugin React + alias `@` → `src` + dev server (subpath `/vite`). | [Vite & alias](./vite-config.md) |
| **Router (`router/`)** | `defineRoutes`, `<AppRouter>`, `<RouteGuard>` + re-exports do React Router v8.        | [Roteamento](./routing.md)       |
| **Store (`store/`)**   | `createStore`, `createSelectors` (fábricas Zustand genéricas).                        | [Estado](./state.md)             |
| **App (`app/`)**       | `<AppProviders>` — compõe ErrorBoundary → Query → Theme → i18n num bloco.             | [Providers](./app-providers.md)  |

### Blocos de UI e integrações

| Camada                                                | O que faz                                                                                                             |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Componentes (`components/`)**                       | 70+ UI primitives (Button, Input, Modal, Table, DataTable, Command, Calendar…) com CSS Modules prefixados `tempest_`. |
| **Hooks (`hooks/`)**                                  | `useDebounce`, `usePagination`, `useMediaQuery`, `useKeyboardShortcut`, `useFocusTrap`…                               |
| **HTTP (`http/`)**                                    | `createApiClient`, `parseResponse`, `uploadWithProgress`, `retry`, `usePoll`.                                         |
| **Auth (`auth/`)**                                    | `createAuthStore` (Zustand) + `AuthGuard` + JWT helpers + `lazyWithRetry`.                                            |
| **Query (`query/`)**                                  | `QueryProvider`, `createQueryKeys`, presets de tempo.                                                                 |
| **SSE / WebSocket / Push / SW**                       | Transportes em tempo real com reconnect.                                                                              |
| **Offline (`offline/`)**                              | `createOfflineStore` (Dexie).                                                                                         |
| **Forms (`forms/`)**                                  | `useZodForm`, `zodResolver`, `FormField`, inputs mascarados BR.                                                       |
| **Theme / i18n / Logger / Telemetry / Feature Flags** | Tema (no-flash), i18n in-house, logger leveled, adapters injetáveis.                                                  |
| **Utils (`utils/`)**                                  | `cn`, format BR, arrays/objects/guards/functions/promises, strings, numbers, `randomId`.                              |

## Dependências

**`react`**, **`react-dom`** e **`react-router`** são **peer dependencies** — os
três carregam contexto React, e uma segunda cópia não é peso extra no bundle, é
uma segunda *instância* que quebra em runtime. Todo o resto é **dependência
direta** — instalada automaticamente por `npm install tempest-react-sdk` e
externalizada no bundle (o bundler do app resolve do `node_modules` e faz
tree-shake).

| Pacote                         | Status              | Usado por                                                                                |
| ------------------------------ | ------------------- | ---------------------------------------------------------------------------------------- |
| `react`, `react-dom`           | **Peer (obrigat.)** | Tudo                                                                                     |
| `react-router` (`^7 \|\| ^8`)  | **Peer (obrigat.)** | `AppRouter`, `defineRoutes`, `RouteGuard`, re-exports                                    |
| `zustand`                      | Dep direta          | `createStore`, `createSelectors`, `createAuthStore`                                      |
| `@tanstack/react-query`        | Dep direta          | `QueryProvider`, `createQueryKeys`, `AppProviders`                                       |
| `zod`                          | Dep direta          | `parseResponse`, `validateForm`, `zodResolver`, `useZodForm`                             |
| `react-hook-form`              | Dep direta          | `useZodForm`, `FormField`, inputs mascarados                                             |
| `dexie`                        | Dep direta          | `createOfflineStore`                                                                     |
| `lucide-react`                 | Dep direta          | Ícones (`leftIcon`/`rightIcon`)                                                          |
| `vite`, `@vitejs/plugin-react` | **Peer opcional**   | `createViteConfig` (subpath `tempest-react-sdk/vite`) — já presente em qualquer app Vite |

!!! warning "Por que `react-router` é peer, e não dep direta"
    Ele guarda contexto React. Uma cópia aninhada em
    `tempest-react-sdk/node_modules` é um `<Router>` **diferente** do que o seu
    app renderiza, então qualquer hook do SDK que alcance esse contexto estoura
    com `useNavigate() may be used only in the context of a <Router>` — crash de
    runtime, não regressão de tamanho. É a mesma razão de `react` ser peer, e é a
    única exceção à regra "todo o resto é dep direta". O range `^7 || ^8` deixa o
    app em qualquer um dos dois majors instalar uma cópia só: a superfície
    re-exportada é idêntica nas duas versões, e ambas entregam os bindings de DOM
    dentro do próprio `react-router` (não existe `react-router-dom` separado).

!!! note "O resto continua dep direta"
    `zustand`, `zod`, `dexie`, `react-hook-form`, `@tanstack/react-query` e
    `lucide-react` são dependências diretas — `npm install tempest-react-sdk` já
    traz tudo, sem você listar nada à mão. Duas cópias dessas custam bytes, não
    correção.

Adapters de SDKs externos (Sentry, PostHog, GrowthBook, LaunchDarkly) **não**
são declarados — o caller injeta a instância na factory.

## Subpaths

| Import                         | Conteúdo                                              |
| ------------------------------ | ----------------------------------------------------- |
| `tempest-react-sdk`            | Barrel principal (componentes, hooks, foundation…).   |
| `tempest-react-sdk/styles.css` | Tokens `--tempest-*` + reset + CSS Modules.           |
| `tempest-react-sdk/vite`       | `createViteConfig` (Node-only, pro `vite.config.ts`). |
| `tempest-react-sdk/testing`    | `createMockHandlers` (helpers MSW pra testes).        |
| `tempest-react-sdk/icons`      | `Icon` por slug + registro estático ([Ícones](./icons.md)). |

## Bundle

Vite library mode → ESM (`tempest-react-sdk.js`) + CJS (`.cjs`) + `.d.ts`
rollupado + `styles.css` (CSS Modules num arquivo só, `cssCodeSplit: false`).
Orçamento monitorado por `size-limit` no CI.

## Recap

- Um pacote, camadas independentes; você importa só o que usa e o bundler faz
  tree-shake do resto.
- Só `react` + `react-dom` são peers; as demais libs são deps diretas instaladas
  junto.
- Subpaths: o barrel principal, `…/styles.css`, `…/vite` (Node-only), `…/testing` e
  `…/icons` (ícone por slug).
- A fundação de app ([Vite](./vite-config.md) · [Router](./routing.md) ·
  [Store](./state.md) · [Providers](./app-providers.md)) é o que o
  [`create-tempest-app`](./scaffold.md) monta pra você.

## Veja também

- [Design de Software — camadas do seu app](./design/architecture.md)
- [Scaffold — `create-tempest-app`](./scaffold.md)
- [HTTP — fluxo de request](./http.md)
- Diagrama: [architecture.drawio](./diagrams/architecture.drawio)

---

# audio.md

# Áudio

Áudio no navegador, nas duas direções.

**Reprodução** — notificação sonora (chime de mensagem, confirmação de pagamento) com `playAudio`, `useAudio` e `createAudioPlayer`, e o componente `AudioPlayer` quando você precisa de transporte (play/pause, barra, tempos).

**Captura** — `AudioRecorder` pra uma nota de voz em uma linha, e por baixo `useMediaPermission`, `useMediaDevices`, `useMicrophone`, `useAudioRecorder`, `createLevelMeter` e `blobToWav`. Nenhuma dependência nova: a fatia inteira mede **5,50 KB brotli**.

!!! tip "Se você só quer gravar uma nota de voz, pule para [Gravação](#gravacao-comece-pelo-componente)"
    O resto da página é a camada de baixo, pra quando o componente não serve.

!!! info "Por que um wrapper em volta de `new Audio()`?"
    Tocar som no navegador esbarra na _autoplay policy_ e em vazamento de elementos `Audio`. O SDK encapsula: rastreia o clipe atual (pra dar `stop`), normaliza volume, trata o bloqueio de autoplay devolvendo `null` em vez de estourar, e limpa no unmount quando você usa o hook.

## `playAudio` — one-off no player compartilhado

Ideal pra um som disparado por um evento, sem estado de UI:

```tsx
import { playAudio, useEventStream } from "tempest-react-sdk";

interface StreamEvent {
  type: "NOTIFY" | "PAYMENT-SUCCESS";
}

export function PaymentSounds() {
  useEventStream<StreamEvent>(`${import.meta.env.VITE_API_URL}/notifications`, {
    onMessage: ({ data }) => {
      if (data.type === "PAYMENT-SUCCESS") {
        void playAudio("/audio/dinheiro.mp3", { volume: 0.5 });
      }
    },
  });

  return null;
}
```

`playAudio(src, options)` retorna `Promise<HTMLAudioElement | null>` — `null` quando o navegador bloqueou o autoplay. Opções: `volume` (0–1, default 1), `loop`, `autoplay`, `stopPrevious`, `onEnded`, `onError`. Pra parar o que o player compartilhado está tocando, use `stopAudio()`.

## `useAudio` — player privado por componente

Cada instância do hook tem seu próprio player, então desmontar para o áudio automaticamente:

```tsx
import { useAudio } from "tempest-react-sdk";

export function NotificationBell() {
  const audio = useAudio();

  return (
    <button onClick={() => audio.play("/audio/plim.wav", { volume: 0.8 })}>
      🔔 {audio.unlocked ? "" : "(toque pra ativar som)"}
    </button>
  );
}
```

- `audio.play(src, options)` — toca no player privado (mesmas options do `playAudio`).
- `audio.stop()` — para o clipe atual.
- `audio.unlocked` — vira `true` após o primeiro `play()` bem-sucedido. Útil pra esconder UI que pede a interação inicial.
- Cleanup automático no unmount.

!!! tip "Use `unlocked` pra guiar o usuário"
    Antes do primeiro clique, o navegador bloqueia áudio. Mostre uma dica ("toque pra ativar som") enquanto `unlocked === false` e esconda assim que ele virar `true`.

## `createAudioPlayer` — canais isolados

`createAudioPlayer()` cria um tracker independente do default. Use quando precisar tocar dois sons simultaneamente sem que um corte o outro (ex.: música de fundo + efeito sonoro):

```ts
import { createAudioPlayer } from "tempest-react-sdk";

const music = createAudioPlayer();
const sfx = createAudioPlayer();

await music.play("/audio/loop.mp3", { loop: true, volume: 0.3 });
await sfx.play("/audio/coin.wav", { volume: 1 }); // não corta a música

music.stop(); // para só a música
console.log(sfx.current()); // HTMLAudioElement | null
```

Cada player rastreia **um** clipe atual. `stopPrevious: true` no `play()` para o clipe anterior daquele mesmo player antes de tocar o novo.

## `createSfxPool` / `useSfxPool` — efeitos sonoros curtos

`new Audio(src)` a cada disparo aloca um elemento e re-entra na pilha de rede por um arquivo que o navegador já tem. Para um som que toca dezenas de vezes por minuto — um blip de menu, um hit, um pickup — é a forma errada. O pool aloca uma vez por fonte e reproduz.

```ts
import { useSfxPool } from "tempest-react-sdk";

function Menu({ sfxVolume }: { sfxVolume: number }) {
  const sfx = useSfxPool({ volume: sfxVolume / 100, baseUrl: import.meta.env.BASE_URL });

  useEffect(() => {
    sfx.preload(["sfx/move.mp3", "sfx/select.mp3", "sfx/back.mp3"]);
  }, [sfx]);

  return <button onClick={() => sfx.play("sfx/select.mp3")}>Confirmar</button>;
}
```

- `play(src, { volume })` — o volume por play é multiplicado pelo master do pool.
- `preload(src | src[])` — busca antes do primeiro disparo, pra ele não sair mudo enquanto o arquivo baixa.
- `setVolume(v)` — aplica também no que já está soando, **reescalando pelo ganho de cada um**: um clipe que começou a meio volume não é puxado pra cima.
- `stop(src?)` — para uma fonte, ou todas.
- `dispose()` — libera tudo. O `useSfxPool` já chama no unmount.

!!! note "`voices`: repetir ou sobrepor"
    O default (`voices: 1`) **reinicia** o clipe a cada play, que é o que um blip de menu quer. Suba pra deixar o som se sobrepor — um hit tocando enquanto o anterior ainda ressoa:

    ```ts
    const hits = createSfxPool({ voices: 3 });
    ```

!!! tip "Não confunda com `createAudioPlayer`"
    `createAudioPlayer` rastreia **um** clipe atual, com loop, roteamento de saída e callbacks de ciclo de vida — é o que música de fundo precisa. Efeitos são o caso oposto: muitas fontes, todas curtas, dispara-e-esquece, e o que importa é que disparar seja barato.

Mudar `volume` no `useSfxPool` chama `setVolume` no pool existente em vez de recriá-lo — recriar jogaria fora todo elemento que o usuário já baixou, que é exatamente o custo que o pool existe pra evitar. `baseUrl`, `voices` e `maxSources` são lidos uma vez, na criação.

## Autoplay policy

Navegadores bloqueiam playback antes da primeira interação do usuário. `playAudio` / `play()` retornam `null` quando bloqueado (e chamam `onError` se passado) — em vez de lançar.

!!! warning "Destrave o áudio no primeiro clique"
    Não dá pra tocar som antes de qualquer interação. Desenhe o app pra disparar um `play()` (mesmo de um clipe silencioso curto) no primeiro clique de qualquer botão; a partir daí o navegador libera os próximos.

## Assets

O SDK **não** embute áudios. Sirva em `/audio/*` (ou CDN) e passe a URL. Inspiração de paleta sonora (alofans):

```ts
export const AUDIOS = {
  plim: "/audio/plim.wav",
  dinheiro: "/audio/dinheiro.mp3",
  notification: "/audio/bell_sound.wav",
};
```

## Gravação: comece pelo componente

Se você só quer uma nota de voz, é uma linha. O `AudioRecorder` cuida da permissão, do medidor de nível, do relógio e da revisão antes de você receber o áudio:

```tsx
import { AudioRecorder } from "tempest-react-sdk";

export function NotaDeVoz({ ticketId }: { ticketId: string }) {
  return (
    <AudioRecorder
      maxDurationMs={120_000}
      onRecorded={({ blob, mimeType, durationMs }) => {
        const form = new FormData();
        form.append("audio", blob, `nota.${mimeType.includes("mp4") ? "m4a" : "webm"}`);
        form.append("duracao", String(durationMs));
        void fetch(`/api/tickets/${ticketId}/audio`, { method: "POST", body: form });
      }}
      footer={<small>Máximo 2 minutos.</small>}
    />
  );
}
```

O que você ganha sem escrever nada:

| Você fez | O componente faz |
| --- | --- |
| nada | **Não** pede o microfone no mount — só no primeiro toque em Gravar |
| nada | Se a permissão já está `denied`, diz isso e como resolver, em vez de oferecer um botão que não funciona |
| nada | Medidor de nível ao vivo, relógio que **desconta pausa**, pausar/continuar |
| `maxDurationMs` | Para sozinho no limite, e mostra o limite ao lado do relógio |
| nada | Player de revisão com transporte, e "Gravar de novo" reaproveitando o mesmo stream |
| `format="wav"` | Converte antes de te entregar, então o `onRecorded` **sempre** dá o formato que você pediu |

!!! danger "O prompt de permissão não é disparado no mount, e isso é a decisão mais importante da página"
    Um prompt que o usuário não provocou é a forma mais confiável de ganhar um **Block permanente** — e depois disso o `getUserMedia` rejeita **sem nunca mais perguntar**. Por isso o microfone abre no primeiro toque em Gravar, e o toque sobrevive ao round-trip: o componente arma a gravação e começa quando o stream chega. Esperar um segundo clique faria o primeiro parecer quebrado.

### Props

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `onRecorded` | `(recording: AudioRecording) => void` | — | Recebe o áudio pronto. Não dispara em cancelamento. |
| `maxDurationMs` | `number` | — | Para sozinho. **Vale sempre setar** em tela pública. |
| `deviceId` | `string` | — | Microfone específico, de `useMediaDevices().audioInputs`. |
| `format` | `"native" \| "wav"` | `"native"` | `"wav"` converte no stop. Veja o custo abaixo. |
| `wavOptions` | `WavOptions` | — | `{ mono: true, sampleRate: 16000 }` serve pra fala. |
| `audioBitsPerSecond` | `number` | — | 32000–64000 basta pra voz em Opus. |
| `review` | `boolean` | `true` | Player de revisão antes de entregar. |
| `locale` | `"pt-BR" \| "en"` | `"pt-BR"` | Rótulos. |
| `footer` | `ReactNode` | — | Dica, contagem, aviso legal. |
| `onError` | `(error: unknown) => void` | — | Falha do gravador, ou conversão WAV que não deu. |

`AudioRecording = { blob, mimeType, durationMs }`.

## `AudioPlayer` — transporte pra um clipe

Aceita `Blob` direto, porque o que um app mais toca é a gravação que ele acabou de fazer:

```tsx
<AudioPlayer src={recording.blob} durationMs={recording.durationMs} />
<AudioPlayer src="/audio/briefing.mp3" sinkId={saidaEscolhida} />
```

!!! warning "Passe `durationMs` sempre que tiver — o `<audio>` mente sobre gravação nova"
    O `MediaRecorder` escreve WebM **sem duração no header**, então `<audio>.duration` de uma gravação fresca é `Infinity`. É por isso que o gravador mantém o próprio relógio e você deve repassá-lo. Sem ele o componente aplica o único contorno que existe — buscar além do fim pra forçar o browser a demuxar até o último frame — e a barra fica travada até isso resolver.

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `src` | `string \| Blob \| null` | — | URL ou blob. Blob vira object URL com revoke automático. |
| `durationMs` | `number` | — | Duração conhecida. Ganha do `<audio>`. |
| `sinkId` | `string` | — | Saída escolhida. Só Chromium. |
| `autoPlay` · `loop` | `boolean` | `false` | Como no elemento nativo. |
| `actions` | `ReactNode` | — | À direita dos tempos — baixar, apagar. |
| `onEnded` · `onError` | `() => void` | — | Fim e falha de decode/rede. |

## Permissão sem disparar o prompt

`useMediaPermission` lê o estado **sem** pedir o dispositivo. É o que torna um fluxo decente possível:

```tsx
import { useMediaPermission } from "tempest-react-sdk";

export function BotaoDeGravar({ onStart }: { onStart: () => void }) {
  const { state, supported } = useMediaPermission("microphone");

  if (state === "denied") {
    return <p>Microfone bloqueado. Libere nas configurações do site e recarregue.</p>;
  }
  return (
    <button onClick={onStart}>
      {state === "prompt" || !supported ? "Permitir microfone e gravar" : "Gravar"}
    </button>
  );
}
```

| Estado | Significa | O que a UI deve fazer |
| --- | --- | --- |
| `"prompt"` | nunca pediu | botão; pedir mostra o prompt |
| `"granted"` | liberado | botão normal |
| `"denied"` | **sticky** — pedir de novo rejeita na hora, sem prompt | instrução pras configurações do site, não botão |
| `"unknown"` | Permissions API não respondeu (Safari não expõe `microphone`) | trate como "vai ter que pedir pra descobrir" |

O estado é **ao vivo**: se o usuário mudar a permissão nas configurações do site, o hook atualiza.

## Dispositivos: microfone e saída

```tsx
import { useMediaDevices, isAudioOutputSelectionSupported } from "tempest-react-sdk";

const { audioInputs, audioOutputs, labelsAvailable } = useMediaDevices();
```

!!! warning "Os nomes só aparecem depois da permissão"
    Antes de o usuário liberar uma captura, **todo** `label` é `""` — os ids e a contagem são reais, os nomes não. Um seletor renderizado ali é uma coluna de vazios. Use `labelsAvailable` pra decidir quando mostrar. Peça o microfone primeiro, depois ofereça a escolha.

!!! info "A lista muda com a página aberta"
    Plugar um fone no meio da gravação é o caso normal, não borda. O hook assina `devicechange` em vez de enumerar uma vez no mount.

`audioOutputs` vem **vazio** onde o browser não tem roteamento de saída — Safari e Firefox não implementam `setSinkId`. Vazio ali significa "você não pode oferecer essa escolha", não "não há alto-falantes". Cheque com `isAudioOutputSelectionSupported()` antes de renderizar o seletor, ou o controle é uma mentira em dois dos três motores.

```tsx
import { setAudioOutput } from "tempest-react-sdk";

const ok = await setAudioOutput(audioRef.current, dispositivoEscolhido);
if (!ok) toast("Este navegador não permite escolher a saída de som.");
```

`playAudio` também aceita `sinkId`, útil pra um chime cair no fone enquanto o áudio da chamada fica no alto-falante.

## Montando você mesmo: os hooks

```tsx
import { useMicrophone, useAudioRecorder } from "tempest-react-sdk";

export function GravadorProprio() {
  const mic = useMicrophone({ deviceId: undefined, noiseSuppression: true });
  const rec = useAudioRecorder(mic.stream, { maxDurationMs: 60_000 });

  return (
    <>
      <button onClick={mic.start} disabled={mic.status === "ready"}>
        Liberar microfone
      </button>
      <button onClick={rec.start} disabled={!rec.ready}>
        Gravar
      </button>
      <button onClick={() => void rec.stop()}>Parar</button>
      <meter min={0} max={1} value={rec.level} />
      <span>{rec.durationMs} ms</span>
      {mic.error && <p role="alert">{mic.error.message}</p>}
    </>
  );
}
```

!!! danger "`stop()` no microfone não é opcional"
    Soltar a última referência de um `MediaStream` **não** desliga o microfone. Cada track tem que ser parada à mão — senão o browser continua mostrando o indicador de gravação, o SO mantém o dispositivo ocupado, e o **próximo** `getUserMedia` (em outra aba do mesmo app, tipicamente) falha com `NotReadableError`. O `useMicrophone` para as tracks no `stop()`, no unmount e antes de reabrir.

!!! info "O gravador **não** é dono do stream"
    `rec.stop()` deixa o microfone aberto de propósito, pra uma segunda gravação não precisar de outro round-trip de permissão. Fechar é do `mic.stop()`.

### Erros classificados

`useMicrophone().error` já vem traduzido de `DOMException` para algo em que dá pra ramificar:

| `kind` | Causa | Ação |
| --- | --- | --- |
| `insecure` | página em HTTP puro | a correção é uma **URL**, não uma configuração |
| `unsupported` | motor sem captura | outro navegador |
| `permission-denied` | negado | configurações do site |
| `not-found` | nenhum dispositivo, ou nenhum que casa com as constraints | relaxar `deviceId` |
| `in-use` | hardware ocupado | fechar o outro app/aba |
| `unknown` | o resto | mostra a mensagem original |

A ordem importa: um `mediaDevices` ausente é quase nunca "este navegador não faz áudio" — é uma página em HTTP, onde a API inteira simplesmente não existe. Reportar `unsupported` ali manda o dev procurar polyfill pra um problema que um `https://` resolve.

## Nível de gravação

`useAudioRecorder` já publica `level` (0–1) a 10 Hz. Pra uma barra por frame, use o `createLevelMeter` direto e escreva no DOM:

```tsx
const meter = createLevelMeter(stream);
const tick = () => {
  barra.style.transform = `scaleX(${meter.level()})`;
  raf = requestAnimationFrame(tick);
};
// ...e sempre meter.stop() no cleanup
```

!!! warning "Medidor não é enfeite"
    Uma entrada mutada no SO, ou um headset com o braço do mic dobrado pra cima, produz uma gravação **perfeitamente bem-sucedida de silêncio** — e sem nível visível o usuário só descobre depois de terminar de falar.

O valor é RMS, não pico: pico reage a uma amostra só e pisca, RMS acompanha volume percebido. O ataque é instantâneo e a queda é suavizada, que é como todo medidor de hardware se comporta — um que atrasa na subida parece "não está gravando".

!!! info "Feche o `AudioContext`"
    O medidor cria um `AudioContext` e o `stop()` fecha. Navegadores limitam contextos vivos (Chrome permite ~6), então um medidor esquecido em unmount quebra todos os próximos da página. Os hooks e os componentes já fecham; se você usar o `createLevelMeter` cru, o `stop()` é seu.

## Formato: o que dá e o que não dá

!!! danger "`MediaRecorder` não produz MP3 nem WAV — em nenhum navegador"
    Chromium e Firefox produzem **Opus** (em WebM ou Ogg); Safari produz **AAC** (em MP4). Nenhum motor implementa encoder MP3 ou WAV pra ele. O padrão do SDK negocia nessa ordem e devolve o que saiu de fato — `AudioRecording.mimeType` é o que o browser reportou, não o que você pediu.

Se o backend só aceita **WAV**, o `blobToWav` converte no cliente, com **zero dependência**: decodifica com o decoder do próprio browser (`decodeAudioData`) e reencoda RIFF/PCM 16-bit.

```tsx
import { blobToWav } from "tempest-react-sdk";

const wav = await blobToWav(recording.blob, { mono: true, sampleRate: 16000 });
```

!!! warning "WAV custa ~10× mais bytes"
    A mesma nota de voz que tem 40 KB em Opus fica em torno de 500 KB em WAV a 48 kHz estéreo. `{ mono: true, sampleRate: 16000 }` leva isso pra ~80 KB — e 16 kHz mono é o que um endpoint de speech-to-text quer de todo jeito. O reamostrador é o `OfflineAudioContext`, ou seja o do próprio browser, não um escrito à mão.

Se o backend só aceita **MP3**: transcodifique no servidor. Um encoder MP3 no cliente significa um build WASM da ordem de 150 KB no bundle de **todo** consumidor do SDK pra servir um formato — é a troca que este SDK não faz.

## Fora do React: os primitivos

`useAudioRecorder` é uma casca fina em cima de um gravador que não sabe nada de
React. Quando a gravação acontece longe de um componente — num store, num
worker, numa máquina de estados — use o primitivo direto:

```ts
import { createAudioRecorder, isAudioRecordingSupported } from "tempest-react-sdk";

if (!isAudioRecordingSupported()) throw new Error("Este navegador não grava áudio");

const rec = createAudioRecorder(stream, { audioBitsPerSecond: 48_000 });
rec.start();
// ...
const recording = await rec.stop(); // { blob, mimeType, durationMs }
```

O handle expõe `start`, `pause`, `resume`, `stop`, `cancel`, mais os leitores
`status()` e `durationMs()` (que descontam o tempo pausado) e o `mimeType`
negociado.

| Símbolo                              | O que é                                                                   |
| ------------------------------------ | ------------------------------------------------------------------------- |
| `createAudioRecorder(stream, opts)`  | O gravador por trás do hook. Não é dono do stream — pare o mic você mesmo. |
| `isAudioRecordingSupported()`        | `MediaRecorder` existe **e** algum container é produzível.                 |
| `isMediaCaptureSupported()`          | A mesma pergunta para captura em geral (`getUserMedia` + `MediaRecorder`) — use antes de oferecer qualquer botão de gravar. |
| `pickAudioMimeType(preferred?)`      | Primeiro container da lista que o browser realmente produz, ou `null`.     |
| `AUDIO_MIME_CANDIDATES`              | A ordem que o SDK negocia: Opus (WebM/Ogg) → AAC (MP4).                    |
| `encodeWav({ channels, sampleRate })`| RIFF/PCM 16-bit a partir de canais Float32 — o motor do `blobToWav`.       |

!!! tip "`isAudioRecordingSupported()` responde a pergunta certa"
    Checar só `typeof MediaRecorder !== "undefined"` deixa passar o motor que
    tem a API e não produz nenhum dos containers — a falha aparece no
    `start()`, com o usuário já esperando. Esta função checa as duas coisas.

## Upload longo: chunks

```tsx
const rec = useAudioRecorder(mic.stream, {
  timesliceMs: 5_000,
  onChunk: (chunk) => void upload(chunk),
});
```

Sem `timesliceMs` a gravação inteira fica em memória até o `stop()` — ok pra nota de voz, não ok pra uma reunião de uma hora. **Os chunks não são tocáveis isoladamente**: só o conjunto forma um arquivo válido.

## Recap

- `playAudio(src, options)` — som one-off no player compartilhado; retorna `null` se o autoplay foi bloqueado. `stopAudio()` para esse player.
- `useAudio()` — player privado por componente com `play`/`stop`/`unlocked` e cleanup no unmount.
- `createAudioPlayer()` — canal isolado pra tocar sons simultâneos sem um cortar o outro.
- A autoplay policy é tratada devolvendo `null`; destrave o áudio na primeira interação.
- O SDK não traz arquivos de áudio — você serve e passa a URL.
- `AudioRecorder` — nota de voz completa: permissão, nível, relógio, revisão, retake.
- `AudioPlayer` — transporte pra um clipe; aceita `Blob` e **precisa** de `durationMs` pra gravação nova.
- `useMediaPermission` — estado da permissão **sem** disparar o prompt; separa "nunca pedi" de "negado" (que é sticky).
- `useMediaDevices` — mics e saídas, reage a `devicechange`; `labelsAvailable` diz quando o seletor vale a pena.
- `useMicrophone` — stream + erro classificado; `stop()` **precisa** ser chamado ou o indicador de gravação não apaga.
- `useAudioRecorder` — status, relógio que desconta pausa, nível, `maxDurationMs`, chunks.
- `blobToWav` — WAV sem dependência, ~10× os bytes; MP3 fica no servidor.
- `setAudioOutput` / `isAudioOutputSelectionSupported` — roteamento de saída, só Chromium.

## Veja também

- [SSE](./sse.md) / [Push](./push.md) — gatilhos típicos de áudio

---

# auth.md

# Auth

Autenticação no front-end é sempre o mesmo punhado de problemas: onde guardar a sessão, como proteger uma rota, como ler o que tem dentro do token e o que fazer quando ele expira no meio de um deploy. O módulo `auth` do `tempest-react-sdk` resolve cada um desses problemas com uma peça pequena e independente — você pega só o que precisa, sem herdar um framework de auth inteiro.

São cinco peças, todas desacopladas entre si:

1. `createAuthStore` — fabrica um Zustand store tipado pelo `TUser` do app.
2. `AuthGuard` — gate de rota router-agnostic.
3. `decodeJWT` / `isJWTExpired` — leitura defensiva de JWTs (sem validação criptográfica).
4. `lazyWithRetry` — `React.lazy` com retry de chunk + reload na falha final.
5. `createRefreshQueue` — coalesce chamadas de refresh concorrentes.

!!! info "Por que peças soltas em vez de um `<AuthProvider>` monolítico"
    Cada app Tempest tem um modelo de usuário, um fluxo de login e um backend
    diferentes. Um provider monolítico forçaria todos a um único formato. Cinco
    primitivos compõem livremente: você usa o store sem o guard, o guard sem o
    JWT decoder, e por aí vai.

## Store — `createAuthStore<TUser>`

O SDK **não é dono do seu modelo de usuário**. Você passa o `TUser` e ganha um store Zustand tipado, já com `persist` configurado.

```tsx
import { createAuthStore } from "tempest-react-sdk";

type SessionUser = { id: string; name: string; is_admin: boolean };

export const useAuthStore = createAuthStore<SessionUser>({
  name: "tempest-app-auth",
  storage: "local",
});

// dentro de um componente: leia o estado (re-renderiza quando muda)
function Header() {
  const { user, isAuthenticated, logout } = useAuthStore();
  return isAuthenticated ? <button onClick={logout}>Sair de {user?.name}</button> : null;
}

// fora do React: escreva pelo getState()
useAuthStore.getState().setSession({
  user: { id: "u1", name: "Ana", is_admin: false },
  token: "eyJhbGciOi…",
});
useAuthStore.getState().logout();
```

Persiste em `localStorage` (default) ou `sessionStorage` (`storage: "session"`). Apenas `user` e `token` são persistidos (`partialize`); após o hydrate, `isAuthenticated` é re-derivado de `!!token` no `onRehydrateStorage`.

Opções extras: `initialUser`, `initialToken` (úteis para hydration em SSR).

!!! tip "Selecione o mínimo necessário"
    `const isAuth = useAuthStore((s) => s.isAuthenticated)` re-renderiza só
    quando `isAuthenticated` muda. Desestruturar o store inteiro
    (`const { ... } = useAuthStore()`) assina **todas** as fatias e re-renderiza
    em qualquer mudança — prefira o seletor em componentes quentes.

## Guard — `AuthGuard`

Router-agnostic: é um if/else puro. Você decide o que renderizar em cada ramo — tipicamente `<Outlet />` quando autenticado e `<Navigate />` para o redirect.

```tsx
import { Navigate, Outlet } from "react-router";
import { AuthGuard } from "tempest-react-sdk";

export function ProtectedLayout() {
  const isAuthenticated = useAuthStore((s) => s.isAuthenticated);
  return (
    <AuthGuard isAuthenticated={isAuthenticated} fallback={<Navigate to="/login" replace />}>
      <Outlet />
    </AuthGuard>
  );
}
```

`AuthGuard` recebe `isAuthenticated`, `children` e `fallback` — sem opinião sobre router. Compõe com guards de role customizados: aninhe um segundo guard dentro do `children`.

!!! note "Relação com `<RouteGuard>` do módulo routing"
    Se você usa o módulo de roteamento do SDK, o [`<RouteGuard>`](./routing.md)
    declarativo já cobre o caso comum (`when` + `redirectTo`) direto na árvore de
    rotas. Use `AuthGuard` quando precisar de controle imperativo sobre o que
    renderiza em cada ramo, ou quando não estiver usando o `<AppRouter>`.

## JWT — `decodeJWT` / `isJWTExpired`

Decoder de **payload only** — **não** valida a assinatura. Use no client para inspeção/UX (mostrar nome, esconder botão de admin, decidir quando renovar). A autorização real é sempre no backend.

```ts
import { decodeJWT, isJWTExpired } from "tempest-react-sdk";

// decodeJWT LANÇA quando o token é malformado — envolva em try/catch
try {
  const { header, payload, signature } = decodeJWT(token);
  console.log(payload.sub, payload.exp);
} catch {
  // token sem 3 segmentos, ou header/payload não-JSON
}

// isJWTExpired nunca lança — token inválido conta como expirado
const expired = isJWTExpired(token, 30); // 30s de leeway → expirado 30s antes do exp
```

!!! warning "`decodeJWT` lança; não retorna `null`"
    Em um token malformado, `decodeJWT` **lança** `Error` — sempre envolva em
    `try/catch`. Já `isJWTExpired` é defensivo: qualquer erro de decode é tratado
    como "expirado" (`true`), então é seguro chamar direto. A assinatura é
    `isJWTExpired(token, leewaySeconds = 0)`.

!!! danger "Nunca autorize no client"
    O payload de um JWT é base64 — qualquer um pode lê-lo e forjá-lo. Use
    `decodeJWT` só para UX. Toda decisão de permissão de verdade acontece no
    servidor, que valida a assinatura.

## Code-splitting — `lazyWithRetry`

`React.lazy` com retry de chunk + fallback `window.location.reload()` na falha final.

**Por que existe**: após um deploy, usuários com a aba aberta tentam carregar chunks que já foram deletados (404). O retry com backoff geralmente pega a nova versão; o reload resolve quando o `index.html` em cache também está stale.

```tsx
import { Suspense } from "react";
import { lazyWithRetry } from "tempest-react-sdk";
import { Spinner } from "tempest-react-sdk";

const Settings = lazyWithRetry(() => import("./Settings"), {
  retries: 3, // default
  initialDelay: 400, // default — backoff exponencial: 400, 800, 1600ms
  reloadOnFinalFailure: true, // default
});

export function SettingsRoute() {
  return (
    <Suspense fallback={<Spinner />}>
      <Settings />
    </Suspense>
  );
}
```

### Aquecendo o chunk — `preload()`

O componente devolvido carrega um `preload()`. Chame no momento em que a rota fica **provável**, não quando ela é necessária — o hover do link, a abertura do menu que contém ela, o fim do passo anterior — e o chunk chega antes do usuário decidir. O `Suspense` fallback simplesmente não aparece.

```tsx
<a href="/settings" onMouseEnter={() => void Settings.preload()}>
  Configurações
</a>
```

O trabalho é compartilhado com o caminho de render: quem disparar primeiro faz o único fetch, e o outro espera a mesma promise. Chamar várias vezes é seguro.

!!! tip "Aquecer várias rotas de uma vez"
    `preload()` devolve a promise, então dá para esperar por um conjunto:

    ```ts
    await Promise.all([Settings.preload(), Profile.preload()]);
    ```

    Ou dispare e esqueça — a rejeição já é tratada internamente, então um preload especulativo que ninguém aguarda nunca vira `unhandledrejection`.

## Refresh queue — `createRefreshQueue`

Coalesce N chamadas de refresh concorrentes em **1** request. Enquanto um refresh está em voo, toda chamada extra recebe a **mesma** promise; quando ela resolve, todas retomam juntas.

```ts
import { createRefreshQueue } from "tempest-react-sdk";

const refresh = createRefreshQueue(
  async () => {
    const { token } = await api.post<{ token: string }>("/auth/refresh");
    useAuthStore.getState().setToken(token);
  },
  { getToken: () => useAuthStore.getState().token },
);

// 5 requests com 401 simultâneos → 1 único refresh, todos retomam:
await Promise.all([refresh(), refresh(), refresh(), refresh(), refresh()]);
```

!!! warning "Compartilhar a promise sozinho não colapsa uma rajada — passe o `getToken`"
    Uma página que dispara várias requests de uma vez recebe vários 401 de volta, mas eles **não chegam na mesma janela**: os retardatários resolvem depois do primeiro refresh já ter terminado, não encontram promise nenhuma pra entrar, e cada um começa outra — rotacionando um token que já está novo. Medido contra um backend de mentira, cinco requests expiradas concorrentes gastaram **dois** refreshes, não um.

    O `getToken` fecha essa brecha: a fila lembra qual token o último refresh instalou, e uma chamada que encontra esse mesmo token ainda no lugar retorna na hora, porque o refresh que ela ia fazer já aconteceu. Aí as mesmas cinco requests gastam exatamente um refresh — e vinte também.

!!! tip "Plugue direto no `createApiClient`"
    Passe a fila como `refresh` no cliente HTTP — ele a chama em todo 401 e a coalescência acontece de graça, evitando uma tempestade de refreshes paralelos derrubando seu endpoint de auth.

Use junto com `createApiClient`:

```ts
const refresh = createRefreshQueue(async () => {
  await AuthService.refresh();
});

const api = createApiClient({
  baseURL: "...",
  refresh, // chamado em 401 — coalesce concorrentes
  onUnauthorized: () => useAuthStore.getState().logout(),
});
```

## Exemplo completo — login, guard e refresh juntos

Um app real costura as cinco peças. Este é o esqueleto completo e copiável:

```tsx
// auth-store.ts
import { createAuthStore } from "tempest-react-sdk";

export type SessionUser = { id: string; name: string; email: string };

export const useAuthStore = createAuthStore<SessionUser>({
  name: "tempest-app-auth",
  storage: "local",
});
```

```ts
// api.ts
import { createApiClient, createRefreshQueue } from "tempest-react-sdk";
import { useAuthStore } from "./auth-store";

const refresh = createRefreshQueue(async () => {
  const res = await fetch("/api/auth/refresh", { method: "POST", credentials: "include" });
  const { token } = (await res.json()) as { token: string };
  useAuthStore.getState().setToken(token);
});

export const api = createApiClient({
  baseURL: "/api",
  getToken: () => useAuthStore.getState().token,
  refresh, // chamado em 401 → coalesce → retry da request original
  onUnauthorized: () => useAuthStore.getState().logout(),
});
```

```tsx
// LoginPage.tsx
import { useNavigate } from "react-router";
import { useAuthStore, type SessionUser } from "./auth-store";
import { api } from "./api";

export function LoginPage() {
  const navigate = useNavigate();
  const setSession = useAuthStore((s) => s.setSession);

  async function handleSubmit(email: string, password: string) {
    const { user, token } = await api.post<{ user: SessionUser; token: string }>("/auth/login", {
      body: { email, password },
    });
    setSession({ user, token });
    navigate("/", { replace: true });
  }

  return <form onSubmit={(e) => e.preventDefault()}>{/* ...campos... */}</form>;
}
```

```tsx
// ProtectedLayout.tsx
import { Navigate, Outlet } from "react-router";
import { AuthGuard } from "tempest-react-sdk";
import { useAuthStore } from "./auth-store";

export function ProtectedLayout() {
  const isAuthenticated = useAuthStore((s) => s.isAuthenticated);
  return (
    <AuthGuard isAuthenticated={isAuthenticated} fallback={<Navigate to="/login" replace />}>
      <Outlet />
    </AuthGuard>
  );
}
```

O fluxo: o login chama `setSession`, persistindo `user` + `token`. O `ProtectedLayout` lê `isAuthenticated` do store. Cada request injeta o token via `getToken`; ao tomar 401, o `createApiClient` chama a fila de refresh (coalescida) e refaz a request. Se o refresh falhar, `onUnauthorized` dispara `logout()` e o guard redireciona para `/login`.

## Resumo

- **`createAuthStore<TUser>`** — store Zustand tipado e persistido; você é dono do `TUser`.
- **`AuthGuard`** — if/else router-agnostic; você escolhe `children` e `fallback`.
- **`decodeJWT`** lança em token inválido; **`isJWTExpired`** é defensivo e nunca lança. Só para UX, nunca para autorização.
- **`lazyWithRetry`** — sobrevive a chunks stale pós-deploy com backoff + reload.
- **`createRefreshQueue`** — N refreshes concorrentes viram 1.

### Veja também

- [Routing](./routing.md) — `<RouteGuard>` declarativo, alternativa ao `AuthGuard` na árvore de rotas
- [HTTP](./http.md) — `getToken: () => useAuthStore.getState().token` + `refresh: queue`
- [Error Boundary](./error-boundary.md) — a falha final do `lazyWithRetry` vira um `ChunkLoadError` que o boundary captura

---

# br-pagamentos.md

# Pagamentos & fiscal BR

Os quatro trilhos que todo produto brasileiro acaba precisando: **Pix**, **boleto**, **chave de acesso da NFe** e **feriados / dias úteis**. Tudo puro TypeScript, **sem nenhuma dependência nova** — a fatia inteira mede **9,22 KB brotli**, e só Pix (payload + CRC + componente de QR) mede **6,1 KB**.

!!! info "Import pelo subpath `tempest-react-sdk/br`"
    Igual ao resto do módulo BR, estes helpers vivem em `tempest-react-sdk/br` — não na raiz. Quem não importa, não paga.

    ```ts
    import { pixPayload, parseLinhaDigitavel, parseChaveNFe, isBusinessDay } from "tempest-react-sdk/br";
    ```

!!! warning "O SDK não fala com banco nenhum"
    Nada aqui consulta o Bacen, a SEFAZ ou uma API de PSP. São **codificadores e validadores locais**: eles montam a string certa, conferem os dígitos verificadores e leem os campos. Se um boleto existe, está registrado ou já foi pago — só o banco responde. Se uma NF-e foi autorizada — só a SEFAZ.

---

## Parte 1 — Pix

### O problema

Um QR de Pix não é um QR "de link". É um payload **EMV MPM** (o mesmo padrão da EMVCo que o Bacen adotou no "Manual de Padrões para Iniciação do Pix"): uma lista de triplas `ID + tamanho de 2 dígitos + valor`, terminada por um CRC-16.

Escrever isso na mão dá errado sempre no mesmo lugar — o checksum. Ele é CRC-16/CCITT-FALSE (polinômio `0x1021`, valor inicial `0xFFFF`) calculado sobre **todo o payload anterior mais os literais `6304`**, ou seja, incluindo o cabeçalho da própria tag 63. Errar isso produz um QR que abre no app e falha na leitura.

### O caminho curto: `<PixQRCode>`

```tsx
import { PixQRCode } from "tempest-react-sdk/br";

export function CheckoutPix() {
  return (
    <PixQRCode
      pix={{
        key: "loja@tempest.dev",
        merchantName: "Loja Tempest",
        merchantCity: "São Paulo",
        amount: 25.5,
        txid: "PEDIDO123",
      }}
      amountLabel="R$ 25,50"
      payeeLabel="Loja Tempest"
    />
  );
}
```

Isso renderiza o símbolo **e** a linha copia-e-cola com botão de copiar. As duas coisas juntas não é enfeite:

!!! tip "Nunca mostre só o QR"
    Num checkout mobile, o QR aparece **no mesmo aparelho** que iria escaneá-lo. Sem a string copiável, o usuário fica travado. É o erro mais comum de tela de Pix.

O payload é montado no navegador e o QR é desenhado pelo encoder próprio do SDK (o mesmo do [`QRCode`](./components/utility.md#qrcode)). Chave, valor e txid **não saem da página** — um serviço de imagem de QR receberia os três.

Quando o payload vem pronto do PSP (cobrança dinâmica assinada), passe direto:

```tsx
<PixQRCode payload={charge.brcode} level="Q" size={220} />
```

!!! warning "`pix` e `payload` são mutuamente exclusivos"
    Passar os dois lança `PixError`. Prefira `payload` para cobrança dinâmica: aquela string foi o PSP que emitiu, e remontá-la aqui só cria um jeito de errar.

### `pixPayload` — a string, sem UI

```ts
import { pixPayload } from "tempest-react-sdk/br";

const payload = pixPayload({
  key: "12345678909",
  merchantName: "Loja Tempest",
  merchantCity: "Sao Paulo",
  amount: 25.5,
  txid: "PEDIDO123",
});

// 00020101021126330014br.gov.bcb.pix0111123456789095204000053039865405
// 25.505802BR5912Loja Tempest6009Sao Paulo62130509PEDIDO1236304D68C
```

Campos aceitos:

| Campo | Tag | Obrigatório | Nota |
| --- | --- | --- | --- |
| `key` | 26 / 01 | ✅ | CPF, CNPJ, e-mail, telefone ou EVP. Validada e normalizada. |
| `merchantName` | 59 | ✅ | Máx. **25** caracteres. Acima disso, erro. |
| `merchantCity` | 60 | ✅ | Máx. **15** caracteres. |
| `amount` | 54 | — | Reais. Omita para o pagador digitar o valor. |
| `txid` | 62 / 05 | — | `[A-Za-z0-9]{1,25}`. Default `***`. |
| `description` | 26 / 02 | — | Texto livre que alguns apps mostram. |
| `postalCode` | 61 | — | CEP, só dígitos. |
| `oneTime` | 01 | — | `true` → tag `12` (uso único) em vez de `11`. |

### Estático × dinâmico

A distinção **muda o que liquida**, então não é cosmética:

=== "Estático"

    A tag 26 carrega a **chave**. O QR é autocontido, pode ser impresso e reusado. Se `amount` for omitido, liquida com o valor que o pagador digitou.

    ```ts
    pixPayload({
      key: "loja@tempest.dev",
      merchantName: "Tempest",
      merchantCity: "Belo Horizonte",
    });
    ```

=== "Dinâmico"

    A tag 26 carrega uma **URL** (`payloadLocation`), e a carteira busca valor e recebedor no PSP. Liquida com o que o PSP serviu. Default: uso único.

    ```ts
    pixPayload({
      kind: "dynamic",
      url: "pix.example.com/qr/v2/abc123",
      merchantName: "Tempest",
      merchantCity: "Recife",
    });
    ```

!!! tip "Cobrança que precisa reconciliar centavo a centavo pede dinâmico"
    Um QR estático sem valor liquida o que o pagador digitou — inclusive R$ 1,00 numa fatura de R$ 100,00.

### Chaves: validação e a armadilha dos 11 dígitos

```ts
import { normalizePixKey, pixKeyType } from "tempest-react-sdk/br";

pixKeyType("123.456.789-09"); // "cpf"
pixKeyType("11.222.333/0001-81"); // "cnpj"
pixKeyType("loja@tempest.dev"); // "email"
pixKeyType("+5511987654321"); // "phone"
pixKeyType("123e4567-e89b-12d3-a456-426614174000"); // "evp"
pixKeyType("não é chave"); // null

normalizePixKey("(11) 98765-4321"); // { type: "phone", value: "+5511987654321" }
```

CPF e CNPJ passam por `validateCPF` / `validateCNPJ` (os mesmos de [Forms BR](./forms-br.md)) — chave com dígito verificador errado é rejeitada com `PixError`.

!!! danger "CPF e celular nacional têm os dois 11 dígitos"
    `"11987654321"` é um celular válido **e** poderia ser um CPF. O desempate é o dígito verificador: 11 dígitos com DV válido viram `"cpf"`, o resto vira `"phone"`. Passe telefone como `+5511987654321` e a ambiguidade desaparece.

### Acentos

O conjunto de caracteres do BR Code não tem acento. O SDK **remove os diacríticos** e rejeita o que sobrar fora do ASCII imprimível:

```ts
pixPayload({ key: "…", merchantName: "Padaria Açúcar", merchantCity: "São Paulo" });
// → "5914Padaria Acucar" … "6009Sao Paulo"

pixPayload({ key: "…", merchantName: "Loja ✅", merchantCity: "Recife" });
// → PixError: merchantName has characters the BR Code cannot carry
```

!!! note "Por que remover em vez de lançar"
    "São Paulo" é o nome real da cidade e o payload não pode carregá-lo. Um QR que não escaneia é pior do que um nome sem cedilha. Já um emoji é erro de quem chamou, e esse aparece.

### Lendo um payload de volta

```ts
import { parsePixPayload } from "tempest-react-sdk/br";

const data = parsePixPayload(colado);
data.key; // "12345678909"
data.amount; // 25.5
data.txid; // "PEDIDO123"
data.crcValid; // true
data.fields; // toda TLV, na ordem, inclusive as desconhecidas
```

É **tolerante com tag desconhecida** — PSPs adicionam templates próprios, e um leitor que rejeita isso não serve em produção. O que **não** é tolerado: frame quebrado (tamanho que passa do fim, `6304` ausente) e **CRC divergente**, que lança. Para inspecionar um payload que você já sabe estar corrompido:

```ts
parsePixPayload(colado, { requireCrc: false }); // crcValid: false, sem lançar
```

!!! danger "CRC divergente não é aviso"
    Um BR Code com checksum errado foi corrompido no caminho, e a conta que ele aponta agora **não é** a conta que o recebedor publicou. Por isso o default lança.

### `pixCrc16`, se você precisa do checksum sozinho

```ts
import { pixCrc16 } from "tempest-react-sdk/br";

pixCrc16("123456789"); // "29B1" — o check value publicado do CRC-16/CCITT-FALSE
pixCrc16(payload.slice(0, -4)); // os 4 hex que fecham o payload
```

---

## Parte 2 — Boleto

### Dois layouts, o mesmo tamanho

O código de barras tem 44 dígitos nos dois casos, e é aí que mora o bug:

| | Primeiro dígito | Linha digitável | Uso |
| --- | --- | --- | --- |
| **Cobrança** (`"banco"`) | ≠ 8 | 47 dígitos | Boleto de banco contra uma fatura |
| **Arrecadação** (`"arrecadacao"`) | `8` | 48 dígitos | Concessionária, tributo, multa |

Não são variantes de um formato: **todo campo muda de posição e de significado**. O SDK detecta pelo primeiro dígito e devolve uma união discriminada — estreite por `kind` antes de ler.

### Ler o que o leitor de código de barras entregou

```ts
import { parseCodigoBarras, parseLinhaDigitavel } from "tempest-react-sdk/br";

const boleto = parseCodigoBarras("34191157000001234560000123456789012345678901");

if (boleto.kind === "banco") {
  boleto.banco; // "341"
  boleto.valor; // 1234.56
  boleto.vencimento; // Date — 2026-09-15
  boleto.linhaDigitavel; // 47 dígitos, já com os DVs
} else {
  boleto.segmentoLabel; // "Órgãos governamentais"
  boleto.valor; // reais, ou null quando o campo é referência
  boleto.empresa; // código FEBRABAN, ou prefixo do CNPJ no segmento 6
}
```

`parseLinhaDigitavel` faz o caminho inverso e aceita as duas linhas (47 ou 48). Os dois parsers **conferem todos os dígitos verificadores** que o layout permite conferir: os 3 (banco) ou 4 (arrecadação) DVs de bloco, mais o DV geral. Qualquer um errado lança `BoletoError` dizendo qual.

Conversão explícita, quando você só quer a outra representação:

```ts
import { codigoBarrasToLinhaDigitavel, linhaDigitavelToCodigoBarras } from "tempest-react-sdk/br";

linhaDigitavelToCodigoBarras("34190000172345678901723456789017115700000123456");
// "34191157000001234560000123456789012345678901"
```

### Validar entrada digitada

```ts
import { formatLinhaDigitavel, validateBoleto } from "tempest-react-sdk/br";

validateBoleto(input); // true / false, sem lançar
formatLinhaDigitavel(input);
// "34190.00017 23456.789017 23456.789017 1 15700000123456"
```

`formatLinhaDigitavel` é helper de **exibição**: entrada que não tem 47 nem 48 dígitos volta intacta.

### Só o layout, sem parsear: `boletoKind`

Para ramificar a UI antes de validar (mostrar o campo certo, escolher o ícone),
`boletoKind` diz o layout a partir do tamanho e do primeiro dígito, e devolve
`null` para entrada que não é boleto — sem lançar:

```ts
import { boletoKind } from "tempest-react-sdk/br";

boletoKind("34191157000001234560000123456789012345678901"); // "banco"
boletoKind("848900000017..."); // "arrecadacao"
boletoKind("123"); // null
```

E `boletoDueDate(fator, options?)` resolve o fator de vencimento isolado — útil
quando o fator veio de outro sistema e você não tem o código de barras inteiro.
Devolve `{ date, epoch }` (dizendo **qual** base foi usada) ou `null` quando o
fator é `0`, que é o valor de "sem vencimento":

```ts
import { boletoDueDate } from "tempest-react-sdk/br";

boletoDueDate(1000, { epoch: "legacy" }); // { date: 2000-07-03, epoch: "legacy" }
boletoDueDate(1000, { epoch: "current" }); // { date: 2025-02-22, epoch: "current" }
boletoDueDate(0); // null
```

O `epoch` de volta importa: ele diz qual das duas leituras ambíguas (abaixo)
saiu, o que é a diferença entre exibir a data e exibir a data **certa**.

### A virada do fator de vencimento (fev/2025)

O vencimento não está no boleto como data — está como **fator de vencimento**, quatro dígitos contando dias desde uma data-base. E essa data-base **mudou**:

- Base original **07/10/1997**. O campo saturou em `9999` no dia **21/02/2025**.
- A partir de **22/02/2025** o contador reiniciou em `1000` sobre a nova base **29/05/2022** (comunicado FEBRABAN FB-009/2023).

!!! danger "As duas leituras são genuinamente ambíguas"
    Todo fator entre 1000 e 9999 tem uma leitura em cada base — a antiga cai em `2000-07-03 … 2025-02-21`, a nova em `2025-02-22 … 2049-10-14`. **Nada no código de barras diz qual.**

    O default `"auto"` escolhe a que cai mais perto de `reference` (hoje, por default). Isso acerta o caso que importa — um boleto sendo pago agora — e erra numa varredura de arquivo histórico. Quando você sabe, diga:

    ```ts
    parseCodigoBarras(barcode, { epoch: "current" }); // base 29/05/2022
    parseCodigoBarras(barcode, { epoch: "legacy" }); // base 07/10/1997
    parseCodigoBarras(barcode, { reference: new Date(2025, 5, 1) });
    ```

O campo resolvido vem acompanhado de qual base foi usada, então a UI pode avisar:

```ts
const boleto = parseCodigoBarras(barcode);
if (boleto.kind === "banco") {
  boleto.fatorVencimento; // 1570
  boleto.vencimentoEpoch; // "current"
  boleto.vencimento; // Date, ou null quando o fator é 0 (boleto sem vencimento)
}
```

Para emitir, o inverso:

```ts
import { fatorVencimento } from "tempest-react-sdk/br";

fatorVencimento(new Date(2025, 1, 22)); // 1000 — base atual
fatorVencimento(new Date(2025, 1, 21), "legacy"); // 9999
fatorVencimento(new Date(2020, 0, 1)); // BoletoError — nenhum fator representa isso
```

### Arrecadação: o que é lido e o que não é

A posição 3 diz duas coisas ao mesmo tempo — se o valor é dinheiro e qual módulo calcula o DV geral:

| Posição 3 | Valor | DV geral |
| --- | --- | --- |
| `6` | Reais | módulo 10 |
| `7` | Quantidade de moeda / referência | módulo 10 |
| `8` | Reais | módulo 11 |
| `9` | Quantidade de moeda / referência | módulo 11 |

Com `7` ou `9`, `valor` vem `null` e o campo cru fica em `valorRaw` — o SDK **não** finge que uma referência é dinheiro. Posição 3 fora de `6-9` é rejeitada em vez de lida errado.

!!! warning "`vencimentoCampoLivre` é pista, não data de liquidação"
    O layout diz que uma data de vencimento, **se existir**, ocupa os 8 primeiros dígitos do campo livre como `AAAAMMDD`. Mas o campo é opcional e nada marca sua presença, então um campo livre que só *parece* data também cai ali. Use na UI; nunca para liquidar.

### Os três dígitos verificadores, exportados

Aparecem em qualquer integração FEBRABAN, então estão no barrel:

```ts
import { mod10Dac, mod11DacArrecadacao, mod11DacCobranca } from "tempest-react-sdk/br";

mod10Dac("01230067896"); // 3 — o exemplo resolvido do layout FEBRABAN v7
```

!!! danger "Módulo 11 de cobrança ≠ módulo 11 de arrecadação"
    Mesmos pesos, mesma subtração — e regras **diferentes** para os restos degenerados. Cobrança resolve resto `0`, `1` e `10` para **`1`**; arrecadação resolve resto `0` e `1` para **`0`**. Usar um no layout do outro dá dígito errado exatamente 3 vezes em 11, o que passa em teste feito com uma amostra pequena. São funções separadas por isso.

---

## Parte 3 — Chave de acesso da NFe

Os 44 dígitos que identificam qualquer documento fiscal eletrônico:

```text
35 2601 12345678000195 55 001 000000123 1 12345678 5
cUF AAMM CNPJ           mod série nNF    tp cNF     cDV
```

```ts
import { formatChaveNFe, parseChaveNFe, validateChaveNFe } from "tempest-react-sdk/br";

validateChaveNFe(input); // true / false

const chave = parseChaveNFe("35260112345678000195550010000001231123456785");
chave.uf; // "SP" — o tipo UF do próprio módulo br
chave.ano; // 2026
chave.mes; // 1
chave.cnpj; // "12345678000195"
chave.modeloLabel; // "NF-e"
chave.serie; // "001"
chave.numero; // "000000123"
chave.tipoEmissaoLabel; // "Normal"

chave.dv; // "5"

formatChaveNFe("35260112345678000195550010000001231123456785");
// "3526 0112 3456 7800 0195 5500 1000 0001 2311 2345 6785"
```

`validateChaveNFe` confere três coisas: 44 dígitos, `cUF` que é uma UF de verdade, e DV que recalcula (módulo 11, pesos 2–9 da direita para a esquerda, resto `0` ou `1` → dígito `0`).

!!! note "O layout é compartilhado — `modelo` é o que diz o que você tem na mão"
    NF-e (`55`), NFC-e (`65`), CT-e (`57`), MDF-e (`58`), BP-e (`63`), NF3e (`66`)… todos usam a mesma chave de 44 dígitos. Modelo fora da tabela vem com `modeloLabel: null` em vez de um chute.

!!! tip "O `cUF` vira o tipo `UF`"
    `chave.uf` é o mesmo union `UF` que `citiesByUf`, `getState` e o `BrazilMap` usam — dá para encadear direto com o resto do módulo BR.

### Emitindo: calcular o DV e tratar o erro

Quem **monta** a chave (em vez de só ler uma pronta) precisa do dígito
verificador dos 43 primeiros dígitos. `chaveNFeCheckDigit` faz esse cálculo
isolado, e lança `ChaveNFeError` quando o corpo não tem exatamente 43 dígitos:

```ts
import { ChaveNFeError, chaveNFeCheckDigit } from "tempest-react-sdk/br";

const corpo = "3526011234567800019555001000000123112345678"; // 43 dígitos

try {
  const dv = chaveNFeCheckDigit(corpo); // 5
  const chave = `${corpo}${dv}`;
} catch (err) {
  if (err instanceof ChaveNFeError) console.error(err.message);
}
```

`ChaveNFeError` é a única exceção do grupo NFe — `validateChaveNFe` continua
devolvendo `false` em vez de lançar, porque validar entrada de usuário não é
caso excepcional.

---

## Parte 4 — Feriados e dias úteis

### O que está na tabela

```ts
import { holidaysFor } from "tempest-react-sdk/br";

holidaysFor(2026);
// 13 entradas: 9 feriados nacionais + 4 dias móveis do sistema financeiro
```

Cada entrada traz `date` (`YYYY-MM-DD`), `name`, `movable` e um `kind`:

- **`"national"`** — feriado nacional em lei federal. 9 datas fixas (Lei 662/1949 com a redação da Lei 10.607/2002, Lei 6.802/1980 para 12 de outubro, Lei 14.759/2023 para 20 de novembro).
- **`"banking"`** — não é feriado em lei, mas o sistema financeiro não opera: **Carnaval (segunda e terça)**, **Sexta-feira da Paixão** e **Corpus Christi**. Agência fechada, compensação parada — um boleto ou uma TED datada aí liquida depois.

!!! info "Por que os dois tipos existem"
    Carnaval e Corpus Christi **não são feriados nacionais por lei** — mas a Resolução CMN 4.880/2020 fecha os bancos nos quatro dias. Se você calcula prazo de pagamento, os dois contam; se você calcula obrigação trabalhista, só `"national"` conta. O default é o calendário bancário, porque é o que quebra dinheiro:

    ```ts
    isBusinessDay("2026-04-03"); // false — Sexta-feira da Paixão
    isBusinessDay("2026-04-03", { kinds: ["national"] }); // true
    ```

### O que **não** está, e não vai estar

!!! danger "Feriado estadual e municipal não estão cobertos"
    A data magna varia por estado e cada um dos 5 570 municípios pode declarar os seus, incluindo até quatro dias religiosos. Nenhuma tabela fica completa e atualizada. Passe pelo `extra`:

    ```ts
    const SAO_PAULO = ["2026-01-25", "2026-07-09", "2026-11-20"];
    isBusinessDay("2026-07-09", { extra: SAO_PAULO }); // false
    ```

Também de fora, de propósito:

- **Ponto facultativo.** Decreto que libera servidor público não é feriado e não muda prazo de ninguém.
- **História pré-2002.** A tabela codifica a lei como está hoje. Pedir 1998 devolve o conjunto de hoje deslocado para 1998, não o que valia então. A única exceção modelada é 20 de novembro, que só aparece **a partir de 2024**.

### Aritmética de dia útil

```ts
import { addBusinessDays, isBusinessDay, isHoliday, nextBusinessDay } from "tempest-react-sdk/br";

isHoliday("2026-11-20"); // true
isBusinessDay("2026-08-03"); // true — segunda-feira comum

nextBusinessDay("2026-12-24"); // 2026-12-28 — pula o Natal e o fim de semana
addBusinessDays("2026-04-01", 2); // 2026-04-06 — pula a Paixão e o fim de semana
addBusinessDays("2026-04-06", -2); // 2026-04-01 — negativo anda para trás
```

Aceitam `Date` ou `"YYYY-MM-DD"` e devolvem `Date` na **meia-noite local**.

!!! warning "Tudo é calendário local, nunca UTC"
    "Hoje é feriado?" é pergunta sobre o calendário de quem está olhando. Os helpers usam `getFullYear/getMonth/getDate` e constroem com `new Date(y, m, d)`; passar por `toISOString()` deslocaria o dia para todo viewer a leste de Greenwich.

!!! note "`addBusinessDays(date, 0)` devolve o dia intacto"
    Mesmo quando não é dia útil. Ajustar em silêncio esconderia justo o caso que você precisa ver.

### Onde a Páscoa entra

Os quatro dias móveis são derivados do domingo de Páscoa, não listados:

```ts
import { easterSunday } from "tempest-react-sdk/br";

easterSunday(2026); // 2026-04-05
```

É o *computus* gregoriano anônimo (Meeus/Jones/Butcher): aritmética inteira sobre o ano, sem tabela e sem dependência — exato para qualquer ano gregoriano.

---

## Recapitulando

- **Pix** — `pixPayload` monta o BR Code EMV com o CRC-16/CCITT-FALSE certo (incluindo os literais `6304`); `parsePixPayload` lê de volta, tolerante com tag desconhecida e intolerante com checksum errado; `<PixQRCode>` desenha o símbolo **e** a copia-e-cola, porque num celular só o QR não serve.
- **Boleto** — `parseLinhaDigitavel` / `parseCodigoBarras` convertem 47↔44 e 48↔44 conferindo todo DV; cobrança e arrecadação são layouts diferentes e o SDK nunca confunde os dois; o fator de vencimento tem **duas** bases desde fev/2025 e a escolha é explícita.
- **NFe** — `parseChaveNFe` abre os 44 dígitos e resolve o `cUF` no tipo `UF` do módulo; `validateChaveNFe` confere tamanho, UF e DV.
- **Feriados** — `holidaysFor` devolve os 9 feriados nacionais + os 4 dias bancários móveis, marcados; estado e município entram por `extra`; `isBusinessDay` / `nextBusinessDay` / `addBusinessDays` fazem a conta no calendário local.

Nada disso fala com banco. Para o lado servidor (registrar boleto, criar cobrança Pix, autorizar NF-e), veja [Integração FastAPI](./integration-fastapi.md).

---

# br.md

# Mapa do Brasil & localidades

Mapa nacional **clicável** das 27 unidades federativas + dataset de estados e cidades — **sem nenhuma API paga ou externa**. A geometria é um GeoJSON do IBGE **simplificado e empacotado** no SDK (renderizado como SVG), e a lista de localidades espelha o `utils/locations` do [`tempest-fastapi-sdk`](https://pypi.org/project/tempest-fastapi-sdk/).

!!! info "Import pelo subpath `tempest-react-sdk/br`"
    Este módulo empacota dados (nomes de ~5600 cidades + geometria das UFs). Pra não pesar no bundle de quem não usa, ele vive num **subpath separado** — importe de `tempest-react-sdk/br`, não da raiz. A geometria do mapa ainda carrega **lazy** (só quando o `BrazilMap` monta).

    ```ts
    import { BrazilMap, citiesByUf } from "tempest-react-sdk/br";
    ```

## Quando usar

- Um **mapa do Brasil clicável** pra selecionar um estado (dashboards, filtros regionais).
- **Choropleth**: pintar estados por uma métrica (vendas, usuários, cobertura).
- Um **seletor Estado → Cidade** encadeado em formulários.
- Consultar estados/cidades/regiões offline (`citiesByUf`, `ufChoices`, ...).

---

## Parte 1 — Dados de localidade

Comece pelos dados: funções puras, sem rede, disponíveis imediatamente.

```ts
import {
  listStates,
  getState,
  citiesByUf,
  statesByRegion,
  ufChoices,
  isValidUf,
  normalizeUf,
} from "tempest-react-sdk/br";

listStates().length; // 27 (ordenados por nome)

getState("sp");
// { uf: "SP", name: "São Paulo", region: "Sudeste", cities: [...] }

citiesByUf("RJ");     // ["Angra dos Reis", "Aperibé", ..., "Rio de Janeiro", ...]
citiesByUf("XX");     // [] — UF inválida devolve lista vazia (não lança)

statesByRegion("Sul").map((s) => s.uf); // ["PR", "RS", "SC"]

normalizeUf(" rj "); // "RJ"
normalizeUf("zz");   // null
isValidUf("mg");     // true
```

!!! tip "Coleções vazias não são erro"
    `citiesByUf` de uma UF inexistente devolve `[]`, não lança. Segue a convenção do backend: "sem correspondência" é um resultado válido.

### Alimentar um `<Select>` / `<Combobox>`

`ufChoices()` e `cityChoices(uf)` já devolvem `{ value, label }`:

```tsx
import { Select } from "tempest-react-sdk";
import { ufChoices } from "tempest-react-sdk/br";

<Select label="Estado" placeholder="Selecione" options={ufChoices()} />;
```

---

## Parte 2 — Seletor Estado → Cidade

O `BrazilStateCitySelect` encadeia dois selects: escolher o estado filtra as cidades daquele UF. A cidade reseta quando o estado muda.

```tsx
import { BrazilStateCitySelect } from "tempest-react-sdk/br";

export function EnderecoForm() {
  return (
    <BrazilStateCitySelect
      onChange={({ uf, city }) => console.log(uf, city)}
      stateLabel="UF"
      cityLabel="Município"
    />
  );
}
```

- `defaultUf` / `defaultCity` — valores iniciais (não-controlado).
- `onChange({ uf, city })` — dispara a cada mudança; `uf`/`city` são `null` quando vazios.
- `layout="column"` empilha os selects (default é lado a lado).
- `disabled` trava ambos.

!!! note "Cidade só habilita depois do estado"
    O select de cidade fica desabilitado até um estado ser escolhido — não há o que listar antes disso.

---

## Parte 3 — O mapa `BrazilMap`

Mapa SVG das 27 UFs, com auto-fit, rótulos de sigla e clique por estado. Nenhum tile externo.

### Mapa clicável

```tsx
import { useState } from "react";
import { BrazilMap, type UF } from "tempest-react-sdk/br";

export function SeletorNoMapa() {
  const [uf, setUf] = useState<UF | null>(null);
  return (
    <>
      <BrazilMap selected={uf} onSelect={setUf} height={440} />
      {uf && <p>Selecionado: {uf}</p>}
    </>
  );
}
```

- `onSelect(uf)` dispara no clique (e no Enter/Espaço — os estados são focáveis quando há `onSelect`).
- `selected` aceita uma UF **ou uma lista** — útil pra seleção múltipla.
- Cada estado tem `aria-label` com o nome — acessível por padrão.

!!! tip "Tooltip ao passar o mouse"
    Por padrão (`showTooltip`, default `true`) aparece uma **dica flutuante** ao passar o mouse: **nome, sigla, região e nº de cidades** — e o valor do choropleth quando `values` está setado (ex.: `São Paulo (SP) · Sudeste · 645 cidades`). Passe `showTooltip={false}` pra desligar, ou `renderTooltip={(data) => ...}` pra customizar o conteúdo (`data` = `{ uf, name, value? }`).

    ```tsx
    <BrazilMap
      renderTooltip={({ uf, name, value }) => (
        <><strong>{name}</strong> — {value ?? "sem dado"}</>
      )}
    />
    ```

### Choropleth (tinta por métrica)

Passe `values` (um número por UF) e cada estado é tingido linearmente entre `minColor` e `maxColor`:

```tsx
import { BrazilMap } from "tempest-react-sdk/br";

const vendas = { SP: 1200, MG: 640, RJ: 580, BA: 410, RS: 390 };

<BrazilMap
  values={vendas}
  minColor="#e0f2fe"
  maxColor="#0369a1"
  showLabels={false}
/>;
```

Estados sem valor ficam com a cor base de superfície.

### Mapa + cidades (receita completa)

O caso que motivou o módulo: clicar no mapa e listar as cidades do estado.

```tsx
import { useState } from "react";
import {
  BrazilMap,
  BrazilStateCitySelect,
  getState,
  type UF,
} from "tempest-react-sdk/br";

export function MapaNacional() {
  const [uf, setUf] = useState<UF | null>(null);
  const estado = uf ? getState(uf) : null;

  return (
    <div>
      <BrazilMap selected={uf} onSelect={setUf} height={440} />

      {estado && (
        <section>
          <h3>
            {estado.name} — {estado.cities.length} cidades
          </h3>
          <BrazilStateCitySelect
            key={uf}
            defaultUf={uf!}
            onChange={({ city }) => console.log("cidade:", city)}
          />
        </section>
      )}
    </div>
  );
}
```

!!! tip "Reset ao trocar de estado"
    O `key={uf}` remonta o seletor quando a UF muda pelo mapa, garantindo que a cidade zere.

### Props do `BrazilMap`

_(veja também o [`BrazilStateMap`](#parte-4-submapa-de-estado-brazilstatemap) para o nível de município.)_


| Prop | Tipo | Default | Descrição |
| --- | --- | --- | --- |
| `selected` | `UF \| UF[] \| null` | — | UF(s) destacada(s). |
| `onSelect` | `(uf: UF) => void` | — | Clique/teclado num estado. |
| `values` | `Partial<Record<UF, number>>` | — | Métrica por UF → choropleth. |
| `minColor` / `maxColor` | `string` | tons de primary | Extremos da escala do choropleth. |
| `height` | `number` | `440` | Altura do viewport em px. |
| `padding` | `number` | `12` | Margem interna em px. |
| `showLabels` | `boolean` | `true` | Sigla no centroide de cada UF. |
| `showTooltip` | `boolean` | `true` | Dica flutuante (nome + região + nº cidades + valor) no hover. |
| `renderTooltip` | `(data) => ReactNode` | — | Conteúdo custom do tooltip (`{ uf, name, value? }`). |
| `label` | `string` | `"Mapa do Brasil por estado"` | Rótulo acessível da região. |

---

## Parte 4 — Submapa de estado (`BrazilStateMap`)

Um submapa de **um estado** com **todos os seus municípios** clicáveis. A geometria municipal é dividida por UF e carregada **lazy** — abrir o mapa de SP baixa só o chunk de SP (~40-70 KB gzip), nunca os ~2 MB do país inteiro.

```tsx
import { useState } from "react";
import { BrazilStateMap, type Municipality } from "tempest-react-sdk/br";

export function MunicipiosDeSP() {
  const [city, setCity] = useState<Municipality | null>(null);
  return (
    <>
      <BrazilStateMap uf="SP" selected={city?.name} onSelect={setCity} height={420} />
      {city && <p>{city.name} — IBGE {city.id}</p>}
    </>
  );
}
```

- `uf` (obrigatório) — o estado a desenhar.
- `onSelect({ id, name })` — dispara ao clicar num município (`id` = código IBGE de 7 dígitos).
- `selected` — casa por `id` **ou** por `name`; aceita lista.
- `values` — choropleth por município (chave = `id` ou `name`).
- `showLabels` — **`false` por padrão**: um estado tem centenas de municípios e os rótulos se sobrepõem.
- `showTooltip` (default `true`) — dica flutuante no hover com **nome + código IBGE** (+ valor do choropleth quando houver). `renderTooltip={(data) => ...}` customiza (`data` = `{ id, name, value? }`).

### Drill-down nacional → estado (receita)

Combine os dois mapas: clicar no mapa nacional troca o estado do submapa.

```tsx
import { useState } from "react";
import { BrazilMap, BrazilStateMap, type Municipality, type UF } from "tempest-react-sdk/br";

export function DrillDown() {
  const [uf, setUf] = useState<UF>("SP");
  const [city, setCity] = useState<Municipality | null>(null);

  return (
    <div style={{ display: "flex", gap: 16 }}>
      <BrazilMap
        selected={uf}
        onSelect={(u) => {
          setUf(u);
          setCity(null);
        }}
        height={320}
      />
      <BrazilStateMap uf={uf} selected={city?.name} onSelect={setCity} height={320} />
    </div>
  );
}
```

### Choropleth municipal

```tsx
import { BrazilStateMap } from "tempest-react-sdk/br";

<BrazilStateMap
  uf="RJ"
  values={{ "Rio de Janeiro": 100, Niterói: 40, "Duque de Caxias": 55 }}
/>;
```

!!! note "Nomes do mapa × dataset de nomes"
    Os nomes dos municípios no mapa vêm do GeoJSON do IBGE; o `citiesByUf` vem do dataset de nomes. São quase idênticos, mas grafias/acentos podem divergir em casos raros. Para casar valores, prefira o **código IBGE** (`id`) quando tiver.

### Acesso direto à geometria municipal

```ts
import { loadStateMunicipalities } from "tempest-react-sdk/br";

const sp = await loadStateMunicipalities("SP");
sp?.features.length; // 644
```

---

## Parte 5 — Geocoding offline

Converter entre nome/coordenada e município, **sem rede**. Usa um índice compacto de centroides (~97 KB gzip) carregado **lazy** — nenhuma chamada de rede, nenhuma API key.

```ts
import {
  reverseGeocode,
  nearestMunicipality,
  geocodeMunicipality,
  municipalityCentroid,
  stateCentroid,
} from "tempest-react-sdk/br";

// Coordenada → município que a CONTÉM (point-in-polygon, exato):
await reverseGeocode({ latitude: -23.5505, longitude: -46.6333 });
// { id: "3550308", name: "São Paulo", uf: "SP" }

// Coordenada → município de centroide mais próximo (rápido, aproximado, sem geometria):
await nearestMunicipality({ latitude: -23.55, longitude: -46.63 });
// { id, name, uf: "SP", latitude, longitude, distanceKm }

// Nome → coordenada (pode haver homônimos em UFs diferentes):
await geocodeMunicipality("Bonito");          // vários
await geocodeMunicipality("São Paulo", "SP"); // filtra por UF

// Centroides:
await municipalityCentroid("3550308"); // { id, name, uf, latitude, longitude }
await stateCentroid("SP");             // { latitude, longitude }
```

!!! tip "`reverseGeocode` vs `nearestMunicipality`"
    - **`reverseGeocode`** faz **point-in-polygon** → devolve o município que realmente contém o ponto. Carrega a geometria de **um** estado (chunk lazy por UF). Passe `{ uf }` se já souber, pra pular a detecção do estado candidato.
    - **`nearestMunicipality`** compara só **centroides** → rápido e sem carregar geometria, mas perto de bordas/em municípios grandes pode cair num vizinho.

### Receita: "onde estou?" (GPS → município)

Combine com o `usePositionTracker` do módulo [Geolocalização](./geo.md):

```tsx
import { useEffect, useState } from "react";
import { usePositionTracker } from "tempest-react-sdk";
import { reverseGeocode, type ReverseGeocodeResult } from "tempest-react-sdk/br";

export function OndeEstou() {
  const { lastPoint, start } = usePositionTracker({ autoStart: true });
  const [local, setLocal] = useState<ReverseGeocodeResult | null>(null);

  useEffect(() => {
    if (lastPoint) reverseGeocode(lastPoint).then(setLocal);
  }, [lastPoint]);

  return <p>{local ? `Você está em ${local.name} — ${local.uf}` : "Localizando…"}</p>;
}
```

!!! warning "Precisão"
    A geometria é simplificada (~2 km). Pontos a ~1-2 km de uma divisa podem resolver pro município vizinho; pontos no mar/fora do território devolvem o vizinho mais próximo por centroide.

---

## Parte 6 — Marcadores, escalas de cor e legenda

### Marcadores (pins)

`BrazilMap`, `BrazilStateMap` e o `TrajectoryMap` (módulo [Geolocalização](./geo.md)) aceitam `markers` — pontos `{ latitude, longitude }` plotados sobre o mapa, com `label` (tooltip), `color`, `radius` e `id`. `onMarkerClick(marker, index)` no clique.

```tsx
import { BrazilMap, type GeoMarker } from "tempest-react-sdk/br";

const capitais: GeoMarker[] = [
  { id: "sp", latitude: -23.55, longitude: -46.63, label: "São Paulo", color: "#e11d48" },
  { id: "rj", latitude: -22.91, longitude: -43.17, label: "Rio de Janeiro" },
];

<BrazilMap markers={capitais} onMarkerClick={(m) => console.log(m.label)} />;
```

!!! tip "Pins a partir do geocode"
    Combine com o geocode (Parte 5): `municipalityCentroid(id)` ou `geocodeMunicipality(name)` dão as coordenadas pra virar `markers`.

### Escalas de cor + legenda

Pra choropleth além do gradiente de 2 cores, passe `colorScale` (de `sequentialScale`/`quantizeScale`/`thresholdScale`) e emparelhe com `<MapLegend>`. Paletas prontas (colorblind-safe): `SEQUENTIAL_BLUES`, `SEQUENTIAL_GREENS`, `SEQUENTIAL_VIRIDIS`, `DIVERGING_RDBU`.

```tsx
import {
  BrazilMap,
  MapLegend,
  sequentialScale,
  SEQUENTIAL_VIRIDIS,
} from "tempest-react-sdk/br";

const vendas = { SP: 1200, MG: 640, RJ: 580, BA: 410, RS: 390 };
const scale = sequentialScale(0, 1200, SEQUENTIAL_VIRIDIS);

<div>
  <BrazilMap values={vendas} colorScale={scale} showLabels={false} />
  <MapLegend title="Vendas (R$ mil)" min={0} max={1200} palette={SEQUENTIAL_VIRIDIS} />
</div>;
```

- **`sequentialScale(min, max, palette)`** — gradiente contínuo.
- **`quantizeScale(min, max, palette)`** — `palette.length` faixas iguais.
- **`thresholdScale(thresholds, palette)`** — faixas por corte (`palette` tem `thresholds.length + 1` cores).
- **`<MapLegend>`** — gradiente contínuo (`min`/`max`/`palette` + `format`) **ou** faixas discretas (`items={[{ color, label }]}`).

!!! note "Paleta da marca"
    As paletas são padrões públicos (ColorBrewer/Viridis). Troque por qualquer lista ordenada de hex da sua marca — os builders de escala aceitam qualquer `string[]`.

---

## Parte 7 — Zoom, cor por região e busca de município

### Pan & zoom

`zoomable` liga roda-do-mouse (zoom no cursor) + arrastar (pan) em `BrazilMap`/`BrazilStateMap`. Duplo-clique reseta; um botão **Reset** aparece quando há zoom/pan.

```tsx
<BrazilStateMap uf="MG" zoomable />
```

### Cor por região

`colorByRegion` tinge cada estado pela macro-região (categórico), sobrepondo `values`/`colorScale`. Emparelhe com uma legenda de faixas via `regionLegendItems()`.

```tsx
import { BrazilMap, MapLegend, regionLegendItems } from "tempest-react-sdk/br";

<div>
  <BrazilMap colorByRegion showLabels={false} />
  <MapLegend title="Região" items={regionLegendItems()} />
</div>;
```

`REGION_COLORS` expõe o mapa `região → cor` (troque pela paleta da marca se quiser).

### Busca de município (autocomplete)

`MunicipalitySearch` é um autocomplete offline (usa `searchMunicipalities`, debounced). Ligue o `onSelect` ao `selected` de um `BrazilStateMap` pra destacar no mapa.

```tsx
import { useState } from "react";
import { MunicipalitySearch, BrazilStateMap, type UF } from "tempest-react-sdk/br";

export function BuscaNoMapa() {
  const [uf] = useState<UF>("SP");
  const [city, setCity] = useState<string | null>(null);
  return (
    <>
      <MunicipalitySearch uf={uf} label="Município" onSelect={(m) => setCity(m.name)} />
      <BrazilStateMap uf={uf} selected={city} zoomable />
    </>
  );
}
```

- `uf` restringe a busca a um estado; sem ele, busca no país todo (resultado mostra a UF).
- `onSelect(m)` recebe `{ id, name, uf, latitude, longitude }` — dá pra centralizar/marcar também.

---

## Sobre a geometria

- Fonte: fronteiras das UFs do **IBGE** (domínio público), simplificadas com Douglas-Peucker (~2 km de tolerância) e arredondadas a 3 casas decimais.
- Tamanho: **~119 KB cru / ~36 KB gzip**, num chunk à parte carregado **lazy** pelo `BrazilMap`.
- Precisão: adequada pra um **mapa de visão geral clicável**, **não** pra análise geográfica precisa nem cálculo de área.

!!! info "Município: use o `BrazilStateMap`"
    O `BrazilMap` desenha **estados**. Para o nível de **município**, o [`BrazilStateMap`](#parte-4-submapa-de-estado-brazilstatemap) desenha todos os municípios de um estado — a geometria municipal (~2 MB no total) é dividida por UF e carregada **lazy**, um chunk por estado, então nunca cai tudo num bundle só.

## Acesso avançado à geometria

Precisa do GeoJSON pra um render próprio? Carregue-o lazy:

```ts
import { loadBrUfGeoJson } from "tempest-react-sdk/br";

const collection = await loadBrUfGeoJson();
collection.features.length; // 27
```

---

## Recap

- **Dados**: `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity` — offline, espelhando o `utils/locations` do FastAPI SDK.
- **Seletor**: `BrazilStateCitySelect` encadeia Estado → Cidade.
- **Mapa nacional**: `BrazilMap` renderiza as 27 UFs em SVG — clicável (`onSelect`), destacável (`selected`) e choropleth (`values`). Zero tile externo; geometria empacotada e lazy.
- **Submapa de estado**: `BrazilStateMap` desenha todos os municípios de uma UF — clicável, choropleth, geometria por estado carregada lazy. `loadStateMunicipalities(uf)` expõe a geometria crua.
- **Import** sempre pelo subpath `tempest-react-sdk/br`.

## Veja também

- [Geolocalização](./geo.md) — coleta de lat/lon, trajetória e `TrajectoryMap` (tile-free)
- [Forms BR](./forms-br.md) — CPF/CNPJ/CEP e `useViaCEP`
- [Componentes: Entrada de dados](./components/inputs.md) — `Select`, `Combobox`

---

# charts.md

# Charts (recharts)

Gráficos transformam números em forma: uma tendência que sobe, uma fatia que
domina, um eixo onde uma série cruza a outra. O SDK embrulha o
[recharts](https://recharts.org) em cinco componentes temados — `AreaChart`,
`BarChart`, `LineChart`, `PieChart` e `RadarChart` — que recebem **dados
tabulares simples** (um array de objetos) e cuidam de eixos, grid, legenda,
tooltip e cores pra você.

Você não monta `<XAxis>`/`<YAxis>`/`<Tooltip>` na mão: passa `data`, diz qual
chave é o eixo (`index`) e quais chaves virar séries (`categories`), e o
componente faz o resto.

## Por que um subpath separado

Os gráficos não vêm do barrel principal. Você os importa de
`tempest-react-sdk/charts`:

```tsx
import { BarChart, LineChart, AreaChart } from "tempest-react-sdk/charts";
```

!!! info "Por que isolar os charts num subpath?"
    O `recharts` é uma dependência **pesada** (D3 por baixo). A maioria dos apps
    Tempest não desenha gráfico nenhum — e seria injusto cobrar esse peso de
    todos. Por isso os charts moram num subpath dedicado e o `recharts` fica
    **externalizado** no bundle do SDK. Apps que nunca importam de
    `tempest-react-sdk/charts` **não pagam nada**: o tree-shaking do bundler do
    app remove tudo.

!!! tip "Só quer a forma da série? Não precisa de chart"
    Um mini-gráfico inline — tendência numa célula de tabela, ao lado de um KPI —
    é o [`Sparkline`](./components/data.md#sparkline), que mora na **entrada
    raiz** e é SVG puro. Nenhum `recharts` envolvido. Use os charts desta página
    quando o leitor precisa **ler valores no eixo**.

Isso é o mesmo padrão do **caller injeta a dependência pesada** que o SDK já usa
nos adapters de telemetria (Sentry/PostHog) e feature flags
(GrowthBook/LaunchDarkly): o SDK descreve a integração, mas a biblioteca de
verdade fica por conta do app. A diferença é que aqui o `recharts` é uma **peer
dependency opcional** — você o instala uma vez e os cinco componentes o
reutilizam.

### Instalação

```bash
npm i recharts
```

!!! warning "Sem o `recharts`, os charts não renderizam"
    Como o `recharts` é peer dep **opcional**, o `npm install tempest-react-sdk`
    não o traz junto. Se você importar de `tempest-react-sdk/charts` sem ter
    rodado `npm i recharts`, o build quebra com `Cannot find module 'recharts'`.
    Instale-o no app que de fato usa gráficos.

## A família cartesiana: Area, Bar, Line

`AreaChart`, `BarChart` e `LineChart` compartilham a **mesma** interface de
props, `CartesianChartProps`. Aprenda uma e você sabe as três — troca só o nome
do componente.

O modelo mental é sempre o mesmo:

- `data` — suas linhas (array de objetos).
- `index` — a chave que vira o **eixo X** (rótulos: meses, dias, nomes…).
- `categories` — as chaves que viram **séries** (uma área/barra/linha cada).

### BarChart

```tsx
import { BarChart } from "tempest-react-sdk/charts";

const faturamento = [
  { mes: "Jan", receita: 12000, custo: 8000 },
  { mes: "Fev", receita: 15000, custo: 9000 },
  { mes: "Mar", receita: 18000, custo: 9500 },
  { mes: "Abr", receita: 21000, custo: 11000 },
];

export function FaturamentoMensal() {
  return (
    <BarChart
      data={faturamento}
      index="mes"
      categories={["receita", "custo"]}
      valueFormatter={(v) => `R$ ${v.toLocaleString("pt-BR")}`}
      height={320}
    />
  );
}
```

Duas séries (`receita`, `custo`), agrupadas lado a lado por mês. O
`valueFormatter` formata os números no tooltip **e** no eixo Y.

### LineChart

Mesma forma de dados, mesmo `index` e `categories` — só muda o componente:

```tsx
import { LineChart } from "tempest-react-sdk/charts";

const visitas = [
  { dia: "Seg", organico: 320, pago: 120 },
  { dia: "Ter", organico: 410, pago: 150 },
  { dia: "Qua", organico: 380, pago: 90 },
  { dia: "Qui", organico: 520, pago: 200 },
  { dia: "Sex", organico: 610, pago: 240 },
];

export function VisitasSemanais() {
  return (
    <LineChart
      data={visitas}
      index="dia"
      categories={["organico", "pago"]}
      valueFormatter={(v) => v.toLocaleString("pt-BR")}
    />
  );
}
```

!!! note "`stack` não empilha linhas"
    `CartesianChartProps` tem a prop `stack` por uniformidade, mas o `LineChart`
    a **ignora** — linhas empilhadas raramente fazem sentido. Use `stack` no
    `AreaChart` ou no `BarChart`, onde ele de fato empilha as séries num
    `stackId` comum.

### AreaChart (com `stack`)

```tsx
import { AreaChart } from "tempest-react-sdk/charts";

const trafego = [
  { hora: "08h", desktop: 120, mobile: 80, tablet: 20 },
  { hora: "12h", desktop: 200, mobile: 160, tablet: 30 },
  { hora: "18h", desktop: 90, mobile: 240, tablet: 25 },
  { hora: "22h", desktop: 60, mobile: 300, tablet: 40 },
];

export function TrafegoPorDispositivo() {
  return (
    <AreaChart
      data={trafego}
      index="hora"
      categories={["desktop", "mobile", "tablet"]}
      stack
      valueFormatter={(v) => `${v} sessões`}
    />
  );
}
```

Com `stack`, as três áreas se empilham e o topo mostra o total por hora.

### `CartesianChartProps` — referência

| Prop             | Tipo                        | Default                | O que faz                                                                       |
| ---------------- | --------------------------- | ---------------------- | ------------------------------------------------------------------------------- |
| `data`           | `ChartData`                 | —                      | Linhas a plotar (array de objetos `chave → string \| number`).                  |
| `index`          | `string`                    | —                      | Chave da linha usada no eixo X (cartesiano) ou eixo angular (radar).            |
| `categories`     | `string[]`                  | —                      | Chaves a plotar, uma série cada.                                                |
| `colors`         | `string[]`                  | tokens `--tempest-chart-*` | Cores das séries, cicladas por categoria.                                       |
| `height`         | `number`                    | `300`                  | Altura do gráfico em pixels.                                                     |
| `width`          | `number`                    | —                      | Largura fixa em px. Quando definida, dispensa o `ResponsiveContainer`.          |
| `stack`          | `boolean`                   | `false`                | Empilha as séries num `stackId` comum (ignorado pelo `LineChart`).              |
| `showLegend`     | `boolean`                   | `true`                 | Renderiza a legenda.                                                            |
| `showGrid`       | `boolean`                   | `true`                 | Renderiza o grid cartesiano.                                                    |
| `showTooltip`    | `boolean`                   | `true`                 | Renderiza o tooltip.                                                            |
| `valueFormatter` | `(value: number) => string` | —                      | Formata valores numéricos no tooltip e no eixo Y.                               |
| `className`      | `string`                    | —                      | Classe extra aplicada ao wrapper do gráfico.                                    |

`ChartData = Array<Record<string, string | number>>` — cada linha mapeia uma
chave de coluna a um rótulo (string) ou valor (number).

!!! tip "Uma série, ou várias"
    `categories` é um array, então você decide quantas séries quer. Uma só
    (`categories={["receita"]}`) desenha um gráfico simples; várias desenham
    séries comparativas, cada uma com a próxima cor da paleta.

## PieChart

A `PieChart` tem uma forma de dados diferente: **uma linha por fatia**. Em vez de
`categories`, você diz qual chave segura o **valor** (`category`) e qual segura o
**rótulo** (`index`).

```tsx
import { PieChart } from "tempest-react-sdk/charts";

const planos = [
  { plano: "Free", usuarios: 4200 },
  { plano: "Pro", usuarios: 1800 },
  { plano: "Business", usuarios: 600 },
  { plano: "Enterprise", usuarios: 120 },
];

export function DistribuicaoDePlanos() {
  return (
    <PieChart
      data={planos}
      category="usuarios"
      index="plano"
      donut
      valueFormatter={(v) => `${v.toLocaleString("pt-BR")} usuários`}
    />
  );
}
```

Cada linha vira uma fatia colorida pela próxima cor da paleta. Com `donut`, o
centro fica vazio (raio interno de 60%) — ótimo pra colocar um total no meio.

### `PieChartProps` — referência

| Prop             | Tipo                        | Default                | O que faz                                                              |
| ---------------- | --------------------------- | ---------------------- | --------------------------------------------------------------------- |
| `data`           | `ChartData`                 | —                      | Linhas a plotar, uma fatia cada.                                      |
| `category`       | `string`                    | —                      | Chave da linha com o **valor** numérico da fatia.                     |
| `index`          | `string`                    | —                      | Chave da linha com o **nome/rótulo** da fatia.                        |
| `colors`         | `string[]`                  | tokens `--tempest-chart-*` | Cores das fatias, cicladas por fatia.                                 |
| `height`         | `number`                    | `300`                  | Altura do gráfico em pixels.                                          |
| `width`          | `number`                    | —                      | Largura fixa em px. Quando definida, dispensa o `ResponsiveContainer`.|
| `donut`          | `boolean`                   | `false`                | Renderiza como rosca (raio interno não-zero) em vez de pizza cheia.   |
| `showLegend`     | `boolean`                   | `true`                 | Renderiza a legenda.                                                  |
| `showTooltip`    | `boolean`                   | `true`                 | Renderiza o tooltip.                                                  |
| `valueFormatter` | `(value: number) => string` | —                      | Formata valores numéricos no tooltip.                                 |
| `className`      | `string`                    | —                      | Classe extra aplicada ao wrapper.                                     |

!!! note "A `PieChart` não tem `showGrid` nem `stack`"
    Pizza não tem grid cartesiano nem empilhamento — essas props da família
    cartesiana simplesmente não existem aqui.

## RadarChart

A `RadarChart` reusa `CartesianChartProps` (mesma assinatura de Area/Bar/Line),
mas plota polígonos num eixo radial: `index` vira o **eixo angular** (os vértices)
e cada entrada de `categories` vira um polígono.

```tsx
import { RadarChart } from "tempest-react-sdk/charts";

const skills = [
  { atributo: "Velocidade", time_a: 80, time_b: 65 },
  { atributo: "Defesa", time_a: 70, time_b: 90 },
  { atributo: "Ataque", time_a: 95, time_b: 75 },
  { atributo: "Resistência", time_a: 60, time_b: 85 },
  { atributo: "Técnica", time_a: 88, time_b: 80 },
];

export function ComparativoDeTimes() {
  return (
    <RadarChart
      data={skills}
      index="atributo"
      categories={["time_a", "time_b"]}
      valueFormatter={(v) => `${v} pts`}
    />
  );
}
```

Dois polígonos sobrepostos comparam `time_a` e `time_b` em cada atributo —
perfeito pra comparar perfis multidimensionais.

!!! note "A `RadarChart` ignora `showGrid` e `stack`"
    O radar sempre desenha seu próprio `PolarGrid` (não há `showGrid`), e não
    empilha séries (`stack` é ignorado). `showLegend`/`showTooltip`/`colors`/
    `valueFormatter` funcionam normalmente.

## Cores e tema

**Você não precisa fazer nada:** por padrão as séries saem dos tokens
`--tempest-chart-1` … `--tempest-chart-8` do tema. Trocar a marca com
`createTheme({ chart: [...] })` move os gráficos junto, e virar o tema escuro
troca a paleta pela versão clareada — sem prop nenhuma no gráfico.

```css
/* o que o SDK já define (colors.css) */
:root {
  --tempest-chart-1: #2563eb; /* azul    */
  --tempest-chart-2: #16a34a; /* verde   */
  --tempest-chart-3: #f59e0b; /* âmbar   */
  --tempest-chart-4: #7c3aed; /* violeta */
  --tempest-chart-5: #ec4899; /* rosa    */
  --tempest-chart-6: #06b6d4; /* ciano   */
  --tempest-chart-7: #ea580c;
  --tempest-chart-8: #0f766e;
}
```

!!! warning "Uma paleta de 6 cores não deve virar 8"
    Se você define só `chart-1..6`, o leitor continuaria andando nos
    `--tempest-chart-7`/`-8` embutidos do SDK e o gráfico com 7 séries sairia com
    paleta misturada — 6 cores da sua marca + 2 sobras. Por isso existe
    `--tempest-chart-count`: o `createTheme` escreve quantas cores o tema tem, e o
    `resolveChartColors` para ali. Definindo tokens à mão, declare junto:

    ```css
    :root {
      --tempest-chart-1: #0f766e;
      --tempest-chart-2: #f97316;
      --tempest-chart-count: 2;
    }
    ```

Sobrescreva no seu CSS, ou gere com o factory de tema:

```tsx
import { applyTheme, createTheme } from "tempest-react-sdk";

applyTheme(createTheme({
  primary: "#0f766e",
  chart: ["#0f766e", "#f97316", "#9333ea"],
}));
```

!!! danger "`colors={["var(--meu-token)"]}` **não** funciona"
    O recharts aplica cor como **atributo de apresentação** do SVG
    (`fill="…"`), e navegador nenhum substitui `var()` ali — custom property só
    é resolvida em **declaração** CSS. Um `var()` passado em `colors` renderiza
    como cor inválida (série invisível).

    É por isso que o SDK **lê os tokens** via `getComputedStyle` e entrega cor
    literal pro recharts. Se você precisa do valor de um token seu em JS, use o
    mesmo caminho:

    ```tsx
    import { readThemeToken } from "tempest-react-sdk";

    const marca = readThemeToken("--minha-marca"); // "#0f766e"
    ```

Para um gráfico específico, `colors` continua ganhando de tudo — é a via de
escape, ciclada por índice da série (ou fatia):

```tsx
import { BarChart, DEFAULT_CHART_COLORS } from "tempest-react-sdk/charts";

export function VendasComCoresDaMarca() {
  return (
    <BarChart
      data={vendas}
      index="mes"
      categories={["loja_a", "loja_b", "loja_c"]}
      colors={["#0f766e", "#f97316", "#9333ea"]}
    />
  );
}

// Ajustar só a primeira cor e manter o resto do fallback:
const minhaPaleta = ["#e11d48", ...DEFAULT_CHART_COLORS.slice(1)];
```

`DEFAULT_CHART_COLORS` é o **fallback**, usado quando os tokens não são
legíveis: sem `styles.css` importado, fora do browser (testes, script de build)
ou numa página que removeu os tokens.

### Resolvendo tokens você mesmo

```tsx
import { resolveChartColors, useChartColors } from "tempest-react-sdk/charts";

// dentro de um componente — re-resolve quando o tema virar
const colors = useChartColors();

// fora do React (canvas, export de imagem, tooltip customizado)
const palette = resolveChartColors();
```

`useChartColors` observa o atributo `data-tempest-theme` e re-resolve na troca de
tema; passar um array explícito curto-circuita o hook (nenhum observer é criado).
Precisa da cor do grid/eixo? `resolveChartChrome("grid" | "axis")`.

!!! tip "Tema escopado numa seção"
    Os dois aceitam um elemento: `useChartColors(undefined, sectionRef.current)`
    resolve os tokens **daquela** subárvore, então uma seção com tema próprio
    pinta seus gráficos com a paleta dela.

## Escala contínua: magnitude e polaridade

As 8 cores de série codificam **identidade** — qual série é qual. Um heatmap ou um
choropleth codifica **quanto**, e isso é outro trabalho: precisa de *um* hue
escalonado por claridade, não de oito hues.

```tsx
import { sequentialScale, divergingScale, scaleSteps } from "tempest-react-sdk";

const cor = sequentialScale({ min: 0, max: 250 });
<rect fill={cor(valor)} />;

// Polaridade: variação contra a meta
const desvio = divergingScale({ min: 80, max: 130, center: 100 });
<rect fill={desvio(realizado)} />;
```

| Export                  | O que faz                                                     |
| ----------------------- | ------------------------------------------------------------- |
| `sequentialScale`       | `{ min, max, ordinal? }` → `(valor) => cor`                   |
| `divergingScale`        | `{ min, max, center? }` → `(valor) => cor`                    |
| `scaleSteps`            | Todos os passos em ordem, pra montar a legenda                 |
| `SEQUENTIAL_STEP_COUNT` | `7`                                                           |
| `DIVERGING_STEP_COUNT`  | `9` (1–4 frio · 5 neutro · 6–9 quente)                        |
| `ORDINAL_START_STEP`    | `3` — primeiro passo que passa 2:1 na superfície                |

!!! info "Sai da raiz, não do `/charts`"
    São matemática de token pura, **sem recharts**. Quem mais precisa delas — um
    choropleth do `/br`, um heatmap feito à mão — não tem motivo pra instalar
    recharts. Custo medido: **365 B brotli** importando da raiz. O `/charts`
    re-exporta só por descoberta.

!!! tip "Devolvem token, não hex"
    O retorno é `var(--tempest-chart-sequential-4)`. Um heatmap pintado uma vez
    segue o tema — inclusive o escuro, cujos passos são **escolhidos** pra superfície
    escura, não invertidos do claro.

!!! warning "Sequencial deixa o zero recuar; ordinal não pode"
    Numa **sequencial** o passo mais claro some na superfície de propósito: é o que
    "quase nada" deve parecer num heatmap. Numa **ordinal** — degrau de funil, faixa,
    tier — cada passo é uma marca que alguém precisa ver, e um passo invisível é um
    dado perdido. Passe `ordinal: true` e a escala começa no passo 3.

    ```tsx
    sequentialScale({ min: 0, max: 4, ordinal: true }); // usa 3..7
    ```

!!! check "Cada braço da divergente escala pelo próprio alcance"
    Num domínio assimétrico (−5 a +80) os negativos ainda usam o braço frio inteiro.
    Escalar os dois braços pelo mais largo — o erro fácil — colapsaria todo negativo
    no passo ao lado do meio e esconderia o sinal.

!!! danger "O meio da divergente é cinza, nunca um hue"
    Um meio colorido lê como uma **terceira categoria** em vez de "sem desvio", que é
    a única coisa que uma divergente existe pra mostrar. Por isso o token 5 é neutro
    nos dois modos.

!!! note "Escala contínua precisa de legenda"
    Sem uma faixa com rótulo nas pontas, ninguém converte cor de volta em número. O
    `scaleSteps` existe pra isso:

    ```tsx
    <div style={{ display: "flex" }}>
      {scaleSteps("sequential").map((cor) => (
        <span key={cor} style={{ background: cor, width: 20, height: 10 }} />
      ))}
    </div>
    <span>0</span> … <span>250</span>
    ```

### Como as rampas foram feitas

Não foram escolhidas a olho. Os passos são **calculados** em OKLCH com claridade
espaçada por igual, então passo igual de dado parece passo igual de cor — o que não
acontece espaçando em RGB. A croma segue um domo: as pontas ficam críveis e o meio
carrega o hue.

Cada rampa foi validada por script nos dois modos: claridade monótona, gap ≥ 0,06
entre passos adjacentes, hue único, e a ponta perto da superfície passando 2:1 no
recorte ordinal. O `createTheme` refaz as duas escalas a partir do hue da marca
(usando o `danger` do tema como polo quente, pra "quente" e "ruim" não discordarem na
tela), então rebrandar move o heatmap junto em vez de deixá-lo azul do SDK.

## Responsivo por padrão, fixo quando preciso

Por padrão, cada gráfico se **estica pra largura do pai** via um
`ResponsiveContainer` do recharts — você controla só a `height`. É o que você
quer em quase todo dashboard: a largura acompanha a coluna.

```tsx
// Largura fluida (preenche o container), altura fixa de 300px (default).
<LineChart data={data} index="dia" categories={["valor"]} />
```

Mas há casos em que você precisa de uma largura **fixa e determinística**: testes
de snapshot, renderização no servidor (SSR), exportar um PNG de tamanho exato. Aí
você passa `width`:

```tsx
// Largura fixa de 600px — sem ResponsiveContainer.
<LineChart data={data} index="dia" categories={["valor"]} width={600} height={300} />
```

!!! warning "`width` desliga o `ResponsiveContainer`"
    Quando você define `width`, o gráfico renderiza **naquela largura exata** e
    **não** é embrulhado num `ResponsiveContainer`. Isso é intencional: o
    `ResponsiveContainer` mede o pai no cliente e não funciona bem em SSR/jsdom,
    onde não há layout calculado. Para uma página normal no navegador, **omita**
    `width` e deixe ele preencher o pai.

## Recap

- Importe os charts de **`tempest-react-sdk/charts`** — subpath dedicado. O
  `recharts` é peer dep **opcional**: rode `npm i recharts` no app que usa
  gráficos. Quem não importa de lá não paga o peso (mesmo padrão do "caller
  injeta a dep pesada" dos adapters de telemetria/flags).
- `AreaChart`, `BarChart` e `LineChart` compartilham `CartesianChartProps`:
  `data` + `index` (eixo X) + `categories` (séries). `stack` empilha em
  Area/Bar; o `LineChart` o ignora.
- `PieChart` usa `category` (valor) + `index` (rótulo), uma linha por fatia, com
  `donut` opcional.
- `RadarChart` reusa `CartesianChartProps` (`index` = eixo angular); ignora
  `showGrid`/`stack`.
- `DEFAULT_CHART_COLORS` é a paleta padrão (6 cores); sobrescreva via a prop
  `colors`, cicladas por série/fatia.
- Sem `width`, o gráfico é **responsivo** (estica no pai via
  `ResponsiveContainer`, você controla a `height`). Com `width`, ele renderiza
  num tamanho **fixo** sem `ResponsiveContainer` — útil pra testes/SSR.

---

# cli.md

# CLI `tempest`

Além da CLI de scaffolding [`create-tempest-app`](./scaffold.md), o pacote
`tempest-react-sdk` instala um segundo `bin` — **`tempest`** — pra cuidar da
saúde e da higiene do seu projeto no dia a dia: um **doctor** (no estilo do
`flutter doctor`) e um **fix/lint/format** que organiza imports, remove imports
mortos e arruma espaçamento.

Como ele vem dentro do SDK, está disponível assim que você instala a lib — rode
com `npx tempest <comando>` ou pelos scripts `npm run doctor` / `npm run fix`
que o scaffold já cria.

## `tempest doctor`

Faz um diagnóstico do projeto atual e imprime um relatório `[✓] / [!] / [✗]`
**agrupado por seção** (estilo `flutter doctor`) — inclusive **problemas
silenciosos** que não quebram o build mas explodem em runtime ou drenam horas de
depuração:

```bash
npx tempest doctor
```

```text
tempest doctor (/caminho/do/seu/app)

Environment
  [✓] Node 22.13.0
  [i] tempest CLI v0.18.0

Project
  [✓] package.json found
  [✓] tempest-react-sdk in dependencies — ^0.18.0
  [✓] tempest-react-sdk installed — v0.18.0
  [✓] react + react-dom present — v19.2.0

Dependency health
  [!] duplicate instance: react — nested copy under tempest-react-sdk;
      rode `npm dedupe`; duas instâncias quebram hooks/context
  [✓] @types/react matches react — v19
  [!] recharts missing (used by charts) — você importa charts mas recharts não
      está instalado — npm i recharts
  [✓] tempest-react-sdk up to date — v0.18.0

TypeScript
  [✓] tsconfig "@/*" alias
  [!] moduleResolution: node — use "bundler" (senão os subpaths
      tempest-react-sdk/br, /charts… não resolvem tipos)
  [✓] jsx: "react-jsx"
  [!] strict mode off — enable "strict": true

Integration
  [✓] vite.config.ts uses createViteConfig
  [✓] src/main.tsx imports styles.css

Stylesheets
  [i] 34 stylesheet(s) · 210 rules · 806 declarations
  [✗] src/pages/Dashboard.module.css:12 — a `;` está faltando: o valor de
      `padding` engole as declarações abaixo, e o browser derruba todas
  [!] src/components/Card.module.css:8 — `bacground-color` não é propriedade
      CSS — você quis dizer `background-color`?
  [i] src/components/Row.module.css:4 — 7 rules em 6 arquivo(s) declaram as
      mesmas 3 propriedades — uma classe global bate 7 cópias locais
  [i] 2 finding(s) are auto-fixable — rode `tempest fix`

Design
  [i] 42 source file(s) · 1830 lines of code · median 38 — largest:
      src/pages/Orders.tsx (204)
  [!] src/pages/Orders.tsx:1 — 204 lines of code (limit 150) — extract a
      sub-component, a hook or a pure function
  [!] src/pages/Orders.tsx:31 — a component must not call the network — move it
      to a service and read it with useQuery
  [i] 2 limit(s) waived with a written reason — @tempest-limits markers

Tooling
  [✓] ESLint config present
  [✓] eslint installed
  [✓] prettier installed

! 3 warning(s) — usable, but worth fixing.
```

!!! info "O que conta como uso, e o que não conta"
    As checagens que perguntam "esse projeto usa X?" leem o **código**, não a prosa:
    comentários saem antes da busca, então um `@example` mostrando
    `import "tempest-react-sdk/styles.css"` não vira um segundo import, e um docstring
    com `<TrajectoryMap tileUrl=…>` não passa a exigir o `leaflet`. Arquivos de teste
    também ficam de fora — um teste que renderiza um componente justamente para provar
    como ele degrada **sem** o peer opcional não é o projeto pedindo aquele peer.

    Peer marcada como `optional` em `peerDependenciesMeta` nunca é reportada como não
    satisfeita: é exatamente o que "opcional" quer dizer.

!!! success "Funciona em projeto que ainda não usa o SDK"
    Se o `tempest-react-sdk` não está nas suas dependências, o `doctor` roda em
    **modo genérico**: audita a saúde de um app React + Vite qualquer e **não** reprova
    você por não ter adotado nada.

    As checagens que são convenção do SDK saem do relatório — alias `@/*`,
    `createViteConfig`, o import do `styles.css`, o `src/main.tsx` esperado, os peers
    opcionais dos subpaths. O que continua é o que vale pra qualquer app: versão do
    Node, instância duplicada de React, dependência declarada e não instalada, peer não
    satisfeita, `@types/react` desalinhado, `strict`/`jsx`/`moduleResolution`, lockfile
    (presente, único, não desatualizado), ESLint e Prettier, `.env` no `.gitignore` e
    variável de cliente sem prefixo `VITE_`.

    ```console
    $ npx tempest doctor
    …
      [i] tempest-react-sdk not installed — checking generic React/Vite health only
    …
    Adopting the SDK (optional)
      [i] install — npm i tempest-react-sdk
      [i] import the stylesheet once, in your entry — import "tempest-react-sdk/styles.css"
      [i] not all-or-nothing — one component at a time works
    ```

    Antes disso o comando dava **duas falhas e exit 1** por um único fato — "você não
    instalou isto ainda" — e enterrava os achados acionáveis no meio de avisos que eram
    só a opinião do SDK. Ou seja: era inútil exatamente no projeto onde deveria ajudar
    mais.

!!! tip "Use no onboarding e na CI"
    Rode `tempest doctor` ao clonar um projeto (confirma que tudo está no lugar)
    e como passo rápido na CI. Ele sai com código **1** se houver qualquer `✗`
    (problema bloqueante); avisos `!` não falham o comando.

### O que ele verifica

**Environment** — Node ≥ 22.12 (e aviso se for uma linha **não-LTS**, major ímpar); versão da CLI; versões do **TypeScript** (≥5) e **Vite** (≥5); `engines.node` do `package.json` satisfeito.

**Project** — `tempest-react-sdk` declarado e instalado (com versão); `react`/`react-dom` presentes; **React major** ≥ 18.

**Dependency health** (os silenciosos):

- **Instância duplicada** de React ou de libs com estado/contexto (`@tanstack/react-query`, `zustand`, `react-hook-form`, `react-router`): uma cópia **aninhada** dentro do `tempest-react-sdk` significa **duas instâncias** no runtime — hooks inválidos, `QueryClient`/contexto de RHF que "somem". Sugere `npm dedupe`. _(Pulado quando o SDK é `file:`/`link:` local.)_
- **Deps declaradas mas não instaladas** (drift entre `package.json` e `node_modules`) → `npm install`.
- **`peerDependencies` do próprio app** não satisfeitas.
- **`@types/react` × `react`** com majors diferentes → erros de tipo fantasma.
- **Peers opcionais de subpaths usados**: se você importa `tempest-react-sdk/charts` sem `recharts`, `/editor` sem `@tiptap/react`, `/vision` sem `onnxruntime-web`, ou passa `tileUrl` no `TrajectoryMap` sem `leaflet` — tudo compila, mas quebra no import lazy em runtime.
- **SDK desatualizado** vs o `latest` no npm (best-effort, com timeout curto; pulado offline).
- **`lucide-react` em cópia dupla** — checagem separada da de cima, porque duas cópias de lucide não quebram hooks como um segundo React: elas duplicam bytes e, o que é pior, deixam as **tabelas de slug geradas** do `/icons` apontando pra exports que a cópia mais antiga não tem. Avisa quando o seu `package.json` declara lucide numa faixa diferente da do SDK (é a causa), quando existe cópia aninhada sob `tempest-react-sdk` (é a prova), e **reprova** quando a versão instalada é mais antiga do que as tabelas exigem — esse caso quebra o build com `… is not exported by lucide-react` apontando pra dentro do SDK. Ver [Ícones por slug](./icons.md).

**TypeScript** — alias `@/*`; **`moduleResolution`** ∈ `bundler`/`node16`/`nodenext` (senão os _subpath exports_ como `tempest-react-sdk/br` não resolvem tipos — silencioso!); **`jsx: "react-jsx"`**; **`strict: true`**; **`skipLibCheck`** ligado; com testes + `vitest`, avisa se o `types` do tsconfig omite `vitest/globals`.

**Integration** — `vite.config.*` usando `createViteConfig`; **`@vitejs/plugin-react`** instalado (JSX/Fast Refresh); import do `styles.css` no entry (e aviso se importado **mais de uma vez**).

**Stylesheets** — análise de **sintaxe e semântica** de todo `.css` do projeto (CSS Modules incluídos): CSS que o browser derruba, declaração morta, nome que não existe, e bloco repetido que pede uma classe global. É a seção detalhada na próxima seção deste guia — [Análise de CSS](#analise-de-css). Aqui o `doctor` mostra no máximo **6 achados por severidade** e diz quantos ficaram de fora; a lista completa sai no `tempest fix --dry-run`.

**Design** — os limites e anti-padrões de [Design de Software](./design/limits.md) medidos no seu código: arquivo/função/hook acima do limite, `<X>Props` com props demais, `any` e `@ts-ignore`, `fetch` dentro de um `.tsx`, `catch` vazio e cor literal em `style={{ … }}`. Mostra **6 achados por severidade** e a mediana de linhas do projeto. Todo achado é `warn` — limite é heurística com saída de emergência escrita (`@tempest-limits <regra> — <motivo>`), então a seção **nunca** derruba o exit code. Pule com `--no-design`.

**Tooling** — config + binários de ESLint e Prettier; **lockfile** presente, único (npm/yarn/pnpm misturados dessincronizam) e **não desatualizado** (`package.json` mais novo que o lock → `npm install`).

**Env & secrets** — **`.env` no `.gitignore`** (senão segredos vazam no commit); variáveis usadas via `import.meta.env.*` **sem prefixo `VITE_`** (o Vite não expõe pro browser → `undefined` em runtime); `.env` vs `.env.example`.

## Análise de CSS

O ESLint não lê `.css` e o Prettier só reformata: entre os dois, **CSS quebrado
passa batido**. O `tempest` analisa cada folha do projeto — inclusive CSS Modules
— em duas frentes, e o resultado alimenta os dois comandos: o `doctor` mostra o
resumo, o `fix` remove a parte que é comprovadamente morta.

```bash
npx tempest doctor                 # resumo, na seção Stylesheets
npx tempest fix --dry-run          # lista completa, sem escrever nada
npx tempest fix                    # remove o que é morto de verdade
npx tempest fix src/components     # só um caminho
npx tempest fix --no-css           # pula a passada de CSS
```

### Sintaxe — o que o browser derruba

Erros (`✗`) são coisas que o browser **descarta em silêncio**. Nenhuma delas
quebra o build do Vite, e é justamente isso que as torna caras:

| Achado | Exemplo |
| -- | -- |
| `;` faltando entre declarações | `padding: 8px⏎margin: 0;` → **as duas** morrem |
| declaração sem `:` | `color red;` |
| valor vazio | `color: ;` |
| bloco nunca fechado / `}` sobrando | `.a { color: red;` |
| comentário, string ou `(` sem fechar | `/* pra sempre`, `content: "ops` |
| declaração fora de qualquer regra | `color: red;` no topo do arquivo |
| `{` sem seletor antes | `{ color: red; }` |

!!! danger "O `;` que falta é o pior deles"
    `padding: 8px` seguido de `margin: 0;` sem ponto e vírgula no meio é **uma**
    declaração sintaticamente válida com valor `8px margin: 0` — o browser
    derruba as duas, sem aviso no console, e o layout fica errado num lugar que
    você não escreveu. É o achado que paga a análise inteira.

### Semântica — CSS válido que está errado

Avisos (`!`) são folhas que o browser aceita e que ainda assim não fazem o que o
autor quis:

- **Declaração duplicada** — `color` duas vezes com o **mesmo** valor: a primeira
  é morta. Auto-fixável.
- **Declaração sobrescrita** — `color` duas vezes com valores **diferentes** na
  mesma regra: uma das duas é um engano. Não é fixável — escolher qual valor você
  quis é palpite dentro do design de alguém.
- **Seletor declarado duas vezes** — no mesmo contexto de `@media`; diz quais
  propriedades a segunda regra mata e pede o merge. Quando as duas regras são
  idênticas declaração por declaração, é auto-fixável.
- **Propriedade que não existe** — `bacground-color`, `dispaly`, `paddign`. Só
  reporta quando existe uma propriedade real a **até 2 edições** de distância,
  então uma propriedade nova que a tabela não conhece nunca é acusada.
- **`@at-rule` inexistente** — `@medai`, `@suports`: o browser pula o bloco todo.
- **Token `--tempest-*` que não existe** — comparado com a tabela lida do
  `styles.css` **instalado**, nunca com uma cópia chumbada na CLI.
- **`var(--x)` que ninguém define** e não tem fallback — resolve pra nada.
- **Regra vazia** — código morto. Em `.module.css` é reportada e **nunca**
  removida: pode ser a classe-marcador que o seu JS referencia via `styles.x`.

!!! info "Um `var()` com fallback nunca é reportado"
    `var(--tempest-card-padding, var(--tempest-space-5))` é o **idioma de knob**
    do SDK: o nome não é um token, é um gancho que o app pode sobrescrever. Como
    o fallback garante que renderiza, a checagem fica calada. Sem fallback o
    mesmo `var()` resolve pra nada — aí é defeito e é reportado.

    Foi essa regra que derrubou 43 falsos positivos quando a análise rodou no CSS
    do próprio SDK — e deixou de pé **4 bugs reais** (`--tempest-duration-normal`,
    `--tempest-primary-solid`, `--tempest-primary-on`, `--tempest-danger-on` sem
    fallback), corrigidos no mesmo commit que trouxe a análise.

### Sugestão (`i`) — quando o global bate o local repetido

É a checagem que o CSS Modules **não pode** fazer por você: o escopo garante que
`.card` de um módulo nunca colide com `.card` de outro, e o preço é que nada te
conta que os dois são idênticos. A duplicação é invisível por design.

```text
[i] src/br/MapLegend.module.css:32 — 39 rules em 31 arquivo(s) re-implementam
    `.tempest-stack` do utilities.css — importe "tempest-react-sdk/utilities.css"
    uma vez e use a classe
[i] src/components/Row.module.css:4 — 7 rules em 6 arquivo(s) declaram as mesmas
    4 propriedades (display: flex; align-items: center; gap: 8px; …+1) — uma
    classe global bate 7 cópias locais
```

Duas formas do mesmo achado:

- **`global-candidate`** — bloco com **≥ 3 declarações** repetido em **≥ 3
  regras** e **≥ 2 arquivos** (dentro de um único arquivo, exige a 4ª cópia).
  Agrupa por declaração, não por nome de classe: `.row`, `.line` e `.bar` com o
  mesmo corpo contam como três cópias.
- **`utility-candidate`** — quando o bloco repetido é um idioma que o
  [`utilities.css`](./styles.md) já entrega: `.tempest-row`, `.tempest-stack`,
  `.tempest-center`, `.tempest-cluster`, `.tempest-spread`, `.tempest-truncate`,
  `.tempest-grid-auto`, `.tempest-card`. O casamento ignora o valor do `gap`, e
  distingue vizinhos (uma coluna é `stack`, não `row`).

Além disso, `hardcoded-token-value` aponta valor literal que é **exatamente** o
de um token (`gap: 8px` → `var(--tempest-space-2)`) — e só quando **um único**
token tem aquele valor, porque `4px` é o valor de vários e mandar você usar
`--tempest-space-1` onde você quis uma borda é um palpite dito com confiança.

!!! tip "Sugestão nunca reprova o comando"
    `i` é conselho: pode não valer a pena, e transformar cinco blocos iguais em
    uma classe global é uma decisão de **acoplamento entre telas** que a CLI não
    tem competência pra tomar. Ela mostra o número e sai da frente.

### O que o `fix` remove — e o que ele nunca toca

A passada de CSS remove **três** coisas, todas comprovadamente mortas:

1. declaração repetida com valor idêntico na mesma regra;
2. regra que repete uma anterior declaração por declaração;
3. regra vazia em folha comum (**não** em `.module.css`).

```console
$ npx tempest fix
→ css (dedupe declarations · drop dead rules)
  src/components/Card.module.css 2
    12: removed duplicate `color` — line 14 declares the same value
    31: removed `.title` — line 40 repeats it exactly
  ✓ removed 2 dead declaration(s)/rule(s) in 1 file(s)
```

!!! warning "Sempre a cópia **anterior**, nunca a de baixo"
    CSS é last-wins: remover a declaração de baixo mudaria o resultado sempre que
    algo entre as duas mexer na mesma propriedade. Remover a de cima não muda
    nada do que o browser computa — é o que faz a operação segura.

!!! note "Folha com erro de sintaxe não é escrita"
    Offset tirado de uma folha pela qual o parser teve que adivinhar caminho não
    é offset pra fazer splice. O `fix` reporta o erro, deixa o arquivo intacto e
    sai com código **1**: conserte a sintaxe e rode de novo.

    O `fix` também **não** reescreve valor pra token, não faz merge de seletor
    duplicado e não converte bloco repetido em classe global. Tudo isso é edição
    de design, não limpeza.

### `--extract-css`: mover o bloco repetido pra classe global

O `fix` normal **reporta** bloco repetido e não mexe. Com a flag, ele executa: o
bloco vai pra folha global do projeto, as regras locais somem e **os `styles.x`
no TSX passam a apontar pra classe nova**.

```bash
npx tempest fix --extract-css --dry-run          # revisa o plano, não escreve
npx tempest fix --extract-css                    # aplica
npx tempest fix --extract-css --css-target src/styles/globals.css
npx tempest fix --extract-css --css-prefix shared-
```

```console
$ npx tempest fix --extract-css
→ css extract (bloco repetido → classe global)
  src/components/Card.module.css 1
    removida `.row` (linha 1) → `.u-row` em src/index.css
  src/components/Card.tsx 1
    `styles.row` → `"u-row"` (linha 5)
  src/components/List.module.css 1
    removida `.line` (linha 1) → `.u-row` em src/index.css
  src/components/List.tsx 1
    `styles.line` → `"u-row"` (linha 5)
  ✓ movidas 2 regra(s) local(is) para 1 classe(s) em src/index.css
```

O que ele reescreve no TSX:

```tsx
// antes                                    // depois
<div className={styles.row} />              <div className="u-row" />
<li className={cn(styles.line, on && x)} /> <li className={cn("u-row", on && x)} />
<div className={styles["bar"]} />           <div className="u-row" />
```

!!! danger "É opt-in porque é decisão de design, não limpeza"
    As outras passadas removem o que está **comprovadamente morto**. Esta decide
    que N telas passam a compartilhar uma classe — e portanto **mudam juntas**. É
    uma decisão de acoplamento entre telas; a CLI executa, não escolhe. Por isso
    nunca roda sem a flag, e por isso o `--dry-run` existe.

!!! check "Ela recusa tudo que não consegue provar seguro — e diz o motivo"
    Nenhuma recusa é silenciosa. Uma ocorrência só é movida quando **todas** valem:

    | Condição | Por que |
    | -- | -- |
    | seletor é uma classe sozinha (`.row`), fora de `@media` | mover pra fora de um `@media` mudaria **quando** a regra vale |
    | nenhuma outra regra da folha menciona a classe | um `.row:hover` ou `.row .child` ficaria sem sujeito |
    | o módulo continua com pelo menos outra regra | senão o import vira código morto, o ESLint remove, e as regras que sobraram **param de carregar** |
    | a classe é lida só como `styles.row` / `styles["row"]` | `styles[key]` ou `Object.keys(styles)` tornam o módulo **opaco**: nada nele é extraído |
    | a folha global existe **e** alguém a importa | escrever numa folha que ninguém carrega é no-op silencioso |
    | o nome novo não colide na folha global | use `--css-prefix` |

    ```console
    [!] src/components/Card.module.css:1 não extraído — outra regra na mesma folha
        usa `.row` (linha 12) e ficaria sem sujeito
    ```

!!! info "As chamadas são achadas pelo compilador do **seu** projeto"
    A varredura usa o `typescript` instalado no projeto, não regex: `styles.row`
    dentro de comentário, template literal ou string não é uso, e regex não sabe
    diferenciar. Sem `typescript` instalado, a passada avisa e não escreve nada.
    O alias do `tsconfig` é respeitado, então `@/components/Card.module.css`
    resolve igual.

!!! tip "O nome da classe nova"
    É o nome local que o seu código mais usa (por módulo, e depois por número de
    chamadas), com o prefixo `u-`. Empate é o caso normal — as cópias moram em
    módulos diferentes justamente porque ninguém combinou um nome —, e aí a ordem
    das ocorrências decide, o que mantém o resultado igual entre execuções. O nome
    escolhido aparece **antes** de qualquer escrita, no `--dry-run`.

!!! info "O que a análise deixa de fora, de propósito"
    Folha **minificada** (`*.min.css` ou densidade alta de bytes por linha),
    arquivo acima de **512 KB**, e as pastas `node_modules/`, `dist/`, `build/`,
    `coverage/`, `public/`, `vendor/`. Acima de **600 folhas** o `doctor` avisa
    que bateu o teto em vez de truncar em silêncio. A varredura roda em ~0,3 s
    nas 200+ folhas do próprio SDK.

## `tempest fix`

Arruma o código de uma vez: **converte import relativo pra `@/`**, **remove CSS
morto**, **organiza imports**, **remove imports não usados**, **limpa linhas em
branco extras e espaços no fim**, e roda o **Prettier**.

```bash
npx tempest fix              # o projeto inteiro
npx tempest fix src/app      # só um caminho
npx tempest fix --dry-run    # mostra o que mudaria, não escreve
npx tempest fix --no-alias   # pula a conversão de import
npx tempest fix --no-css     # pula a passada de CSS
npx tempest fix --extract-css  # opt-in: bloco repetido → uma classe global
```

São quatro passadas, nessa ordem: a conversão de alias, a
[análise de CSS](#analise-de-css), `eslint --fix` (com as regras
`simple-import-sort`, `unused-imports/no-unused-imports`,
`no-multiple-empty-lines`, `no-trailing-spaces`, `eol-last`) e `prettier --write`.
A conversão vem **primeiro** de propósito: trocar `../../services/api` por
`@/services/api` muda o grupo de ordenação do `simple-import-sort`, então rodar o
ESLint depois deixa tudo ordenado num único `fix`. O CSS vem antes do Prettier
pelo mesmo motivo: o que a remoção deixa torto, o Prettier arruma na sequência.

!!! tip "`--dry-run` é a superfície de revisão do CSS"
    O `doctor` mostra 6 achados por severidade; o `--dry-run` lista **todos** os
    erros e avisos (só a cauda de sugestões é limitada a 10) e não escreve nada.
    É o que você lê antes de deixar a ferramenta mexer.

### A conversão de import

A regra é uma só: **nenhum import sobe de diretório**.

```ts
// antes                                    // depois
import { api } from "../../services/api";   import { api } from "@/services/api";
import { Button } from "../Button";         import { Button } from "@/components/Button";
import { Row } from "./Row";                // inalterado — irmão continua relativo
import cfg from "../../../vite.config";     // inalterado — resolve fora de src/
```

Um import de irmão (`./x`) fica como está: ele já diz "isso mora aqui do lado",
que é informação que o `@/` joga fora. Um caminho que resolve **fora** da base do
alias também fica — é isso que protege `../../../vite.config` e
`../../../scripts/x`.

O que a conversão alcança, além de `import` e `export … from`:

```ts
import type { User } from "../../types/user";       // import type
const m = await import("../../pages/Dashboard");    // import() dinâmico
vi.mock("../../lib/api");                            // vi.mock / vi.doMock
```

E em arquivo `.css` (o Vite resolve alias em CSS também):

```css
@import "../../styles/tokens.css";        /* → @/styles/tokens.css */
.hero {
    background: url(../../assets/bg.png); /* → @/assets/bg.png */
}
```

!!! tip "Rode com `--dry-run` primeiro num projeto grande"
    O `--dry-run` lista arquivo, linha e o antes/depois de cada import sem
    escrever nada — e sem rodar ESLint ou Prettier. É a forma de revisar o
    diff antes de deixar a ferramenta mexer.

    ```console
    $ npx tempest fix --dry-run
    → alias imports (../ → @/) [dry-run]
      src/pages/admin/Users.tsx 2
        1: "../../lib/api" → "@/lib/api"
        2: "../../styles/tokens.css" → "@/styles/tokens.css"
      ✓ would convert 2 import(s) in 1 file(s)
    ```

!!! info "O alias vem do seu `tsconfig.json`, não é chumbado"
    A base é lida de `compilerOptions.paths` — seguindo `extends` e aceitando
    comentário no JSON. Se o seu projeto usa `~/*` ou `#/*` em vez de `@/*`, é
    esse prefixo que sai na conversão; se usa `app/` em vez de `src/`, é essa a
    base.

!!! warning "Sem `paths` no tsconfig, a conversão não roda"
    Isso é de propósito. O `paths` é o que o **type-checker** honra: um alias
    achado ali é um alias que o `tsc --noEmit` aceita depois da conversão.
    Adivinhar `@` → `src` só porque existe um `src/` produziria import que não
    resolve em projeto nenhum que não tenha o alias configurado. Quando não acha,
    o comando avisa e segue pro ESLint sem tocar em nada:

    ```console
    ! no path alias found — skipping alias pass  add "paths": { "@/*": ["./src/*"] } to tsconfig.json
    ```

    A conversão também precisa do `typescript` instalado no projeto: ela usa o
    compilador **do seu projeto** pra achar as posições de import, então uma
    string parecida com caminho dentro de comentário, template literal ou
    variável nunca é reescrita por engano.

!!! warning "Código morto = imports/vars, não funções inteiras"
    O `fix` **remove imports não usados** e **avisa** sobre variáveis não usadas
    (não apaga, pra não arriscar). Ele **não** faz eliminação de dead code mais
    profunda (funções/exports órfãos) — isso exige análise dedicada e é
    arriscado automatizar. Para isso, use uma ferramenta como `knip` à parte.

!!! warning "TypeScript 7 não tem a API que os codemods usam"
    O 7 é o **port nativo**: instala com o mesmo nome de pacote, mas publica a API JS
    só em `typescript/unstable/*`, com outra forma — o `ts.readConfigFile`/
    `ts.createSourceFile` clássicos não existem lá. Como as duas passadas de codemod
    (a conversão de alias e o `--extract-css`) precisam do AST, elas **saem do
    caminho** e dizem por quê:

    ```console
    ! alias pass skipped — typescript 7.0.2 não expõe a API clássica do compilador…
    ```

    Todo o resto continua: a análise de CSS, o dedupe, o ESLint, o Prettier, e as
    checagens de tsconfig do `doctor` (que caem num parser JSONC próprio). Pra usar os
    codemods, tenha o TypeScript 6 instalado no projeto.

    Antes da 0.29.1 isso não era um aviso: a CLI resolvia o pacote, concluía que tinha
    TypeScript e chamava a API — `tempest doctor` morria com
    `ts.readConfigFile is not a function`.

!!! note "Precisa de ESLint + Prettier no projeto"
    Apps gerados pelo `create-tempest-app` já vêm com tudo configurado. Em um
    projeto pelado, instale: `npm i -D eslint prettier eslint-plugin-simple-import-sort eslint-plugin-unused-imports`.

## `tempest lint` e `tempest format`

```bash
npx tempest lint     # eslint . (só reporta, não altera)
npx tempest format   # prettier --write . (só formatação)
```

`lint` é o relatório read-only; `fix` é o `lint` que corrige + formata. Flags que
você passar são repassadas pro binário (`npx tempest lint --max-warnings 0`), e o
caminho continua sendo posicional.

## Ajuda

```bash
npx tempest --help
npx tempest --version
```

## Recap

- O `bin` **`tempest`** vem dentro do SDK — `npx tempest <comando>`.
- **`doctor`** diagnostica o projeto (estilo `flutter doctor`), sai com código 1 em problemas bloqueantes.
- **`fix`** converte import relativo pra `@/` + remove CSS morto + organiza imports + remove imports mortos + limpa espaçamento + Prettier. `--dry-run` pra revisar, `--no-alias`/`--no-css` pra pular uma passada.
- A **[análise de CSS](#analise-de-css)** acha sintaxe que o browser derruba, declaração/regra duplicada, nome que não existe e bloco repetido que pede uma classe global. O `doctor` resume, o `--dry-run` lista tudo, o `fix` remove só o que é morto.
- A **[análise de design](./design/limits.md)** mede limite de arquivo/função/hook, contagem de props, `any`, `fetch` em componente, `catch` vazio e cor literal inline — sempre como aviso, com `@tempest-limits <regra> — <motivo>` como saída de emergência escrita.
- **`lint`** reporta; **`format`** só formata.
- Veja também: [Scaffold](./scaffold.md) · [Arquitetura](./architecture.md).

---

# components.md

# Componentes UI

O catálogo foi dividido por categoria para facilitar navegação. Cada arquivo cobre props, exemplos e notas de acessibilidade.

➡️ **[Começar pela Entrada de dados](./components/inputs.md)**

!!! tip "Ícone por nome"
    Precisa renderizar um ícone cujo nome só existe em runtime (menu vindo da API,
    campo de CMS)? Veja [Ícones por slug](./icons.md) — `<Icon name="save" />` cobre
    os 2024 slugs do lucide sem o custo de chunk do `DynamicIcon`.

## Categorias

- **[Entrada de dados](./components/inputs.md)** — Input, Textarea, Select, Combobox, MultiSelect, Checkbox, Radio/RadioGroup, Switch, ChipInput, SearchBar, DatePicker, DateRangePicker, TimePicker, FileUpload, Dropzone, Slider, RangeSlider, RatingStars, PinInput, PasswordInput, StepperInput, Form\*, ImageCropper, SignaturePad
- **[Ação](./components/actions.md)** — Button, FloatingActionButton, Tooltip, DropdownMenu, Popover, ConfirmDialog, InstallButton, InstallBanner
- **[Navegação](./components/navigation.md)** — Navbar, AppBar, Sidebar, NavigationRail, BottomNavigation, Tabs, Stepper, Breadcrumbs, Pagination, SegmentedControl
- **[Overlay](./components/overlay.md)** — Modal, Drawer, BottomSheet, ModalsManager, Lightbox
- **[Layout](./components/layout.md)** — AppShell, Page, Container, Stack, Grid, Divider, Spacer, Center, AspectRatio, SafeArea, Show, Hide
- **[Dados](./components/data.md)** — Table, VirtualList, VirtualTable, DataTable, ListTile, Accordion, Timeline, TreeView, Sparkline
- **[Status & feedback](./components/feedback.md)** — Alert, Banner, Badge, Tag, Stat, Progress, NProgress, Spinner, Skeleton, RefreshIndicator, Toast, EmptyState, ErrorState, OfflineIndicator, SyncStatusBadge, UpdatePrompt
- **[Identidade & micro](./components/identity.md)** — Avatar, AvatarGroup, Card, Kbd
- **[Utilitários & headless](./components/utility.md)** — CopyButton, RelativeTime, Money, TruncateText, VisuallyHidden, Portal, ClickOutside, ConditionalWrapper, For, ErrorText, Image, DataList, DescriptionList, CodeBlock, QRCode
- **Overlays & avançados** — os componentes em paridade com a shadcn/ui, em cinco páginas ([visão geral](./components/advanced.md)):
    - **[Essenciais](./components/advanced-essentials.md)** — Toggle, ToggleGroup, Label, Collapsible, ContextMenu, HoverCard, Command
    - **[Layout & UX](./components/advanced-layout.md)** — ScrollArea, Resizable, Calendar, Scheduler
    - **[Navegação & conteúdo](./components/advanced-navigation.md)** — NavigationMenu, Menubar, Carousel
    - **[Dados](./components/advanced-data.md)** — DataTable, Wizard, Markdown, Masonry, Tour, Transfer, FilterBar, Kanban
    - **[Conversa](./components/advanced-chat.md)** — Chat, AIChat

## Convenções globais

- **CSS Modules** com prefix `tempest_` — não colide com estilos do app.
- **`className` prop** sempre disponível para customização local.
- **Tokens CSS** (`--tempest-*`) — customize via root, não via copy-paste de CSS.
- **Forward ref** em inputs / textarea / select / botões — funciona com `react-hook-form`.
- **A11y baseline** — `aria-invalid` em erro, `aria-label` em close buttons, `aria-current="page"` em nav, focus trap em Modal/Drawer/BottomSheet.
- **Mobile-aware** — Navbar/BottomNavigation/BottomSheet/Toast/Modal.fullscreen aplicam `env(safe-area-inset-*)`.
- **Responsive props** — `Stack.direction`, `Grid.columns`, `Form.layout` aceitam `ResponsiveValue<T>` (`{ base, sm, md, lg, xl }`).

## Veja também

- [Tema + tokens CSS](./styles.md)
- [Forms (zod + Form layout + masked inputs BR)](./forms.md)
- [Hooks](./hooks.md)
- [Testing helpers (subpath)](./testing.md)
- [README raiz](https://github.com/mauriciobenjamin700/tempest-react-sdk#readme)
- [Gallery (demo)](./gallery.md)

---

# components/actions.md

# Ação

Componentes de **ação** são o ponto onde o usuário dispara algo: clicar, escolher numa lista, confirmar. Eles carregam intenção — um clique muda dados, navega, ou inicia um fluxo. Por isso a categoria reúne tanto o gatilho direto (`Button`) quanto os elementos que cercam uma ação: dica contextual (`Tooltip`), conjunto de ações secundárias (`DropdownMenu`), painel ancorado (`Popover`) e a salvaguarda antes de algo destrutivo (`ConfirmDialog`).

Use esta página quando precisar que o usuário **faça** algo. Para entrada de dados (texto, seleção, datas) veja [inputs](./inputs.md); para apresentar coleções, veja [data](./data.md).

## `Button`

> **Quando usar**: a ação primária ou secundária de qualquer tela — submeter um form, abrir um modal, navegar. É o gatilho de ação por padrão.

Botão primário com variants, sizes, estado de loading.

```tsx
import { Button } from "tempest-react-sdk";
import { Plus, Trash } from "lucide-react";

<Button>Salvar</Button>;
<Button variant="danger" leftIcon={<Trash size={16} />}>
  Excluir
</Button>;
<Button variant="outline" loading>
  Carregando…
</Button>;
<Button variant="link" rightIcon={<ArrowRight size={14} />}>
  Ver mais
</Button>;
<Button iconOnly aria-label="Adicionar">
  <Plus size={16} />
</Button>;
<Button fullWidth pill>
  CTA
</Button>;
```

| Prop        | Tipo                                                                                            | Default     |
| ----------- | ----------------------------------------------------------------------------------------------- | ----------- |
| `variant`   | `"primary" \| "secondary" \| "success" \| "danger" \| "soft" \| "outline" \| "ghost" \| "link"` | `"primary"` |
| `size`      | `"xs" \| "sm" \| "md" \| "lg" \| "xl"`                                                          | `"md"`      |
| `loading`   | `boolean`                                                                                       | `false`     |
| `fullWidth` | `boolean`                                                                                       | `false`     |
| `iconOnly`  | `boolean` (square, requer `aria-label`)                                                         | `false`     |
| `pill`      | `boolean` (border-radius pílula)                                                                | `false`     |
| `leftIcon`  | `ReactNode`                                                                                     | —           |
| `rightIcon` | `ReactNode`                                                                                     | —           |

!!! warning "iconOnly precisa de rótulo acessível"
    `iconOnly` remove o texto visível, então leitores de tela não têm o que anunciar. Sempre passe `aria-label` descrevendo a ação (`aria-label="Excluir"`). Sem isso o botão é um ícone mudo para tecnologia assistiva.

!!! tip "loading bloqueia duplo clique"
    `loading` desabilita o botão e seta `aria-busy="true"` — é o padrão para submits assíncronos. Ative-o assim que disparar a request para evitar requisições duplicadas por cliques repetidos.

## `FloatingActionButton`

> **Quando usar**: a ação primária e persistente de uma tela (criar, compor, adicionar) que deve ficar sempre acessível, flutuando sobre o conteúdo. Redondo quando só tem ícone, ou estendido (pílula) quando tem `label`.

Por padrão fica fixo no canto inferior direito; passe `position="none"` para posicioná-lo inline (ex.: dentro de um `NavigationRail`). Espalha todos os props nativos de `<button>` (`onClick`, `disabled`, etc.).

```tsx
import { FloatingActionButton } from "tempest-react-sdk";
import { Plus } from "lucide-react";

<FloatingActionButton icon={<Plus />} aria-label="Novo" position="none" onClick={create} />;
<FloatingActionButton icon={<Plus />} label="Novo pedido" onClick={create} />;
```

| Prop       | Tipo                                       | Default          |
| ---------- | ------------------------------------------ | ---------------- |
| `icon`     | `ReactNode`                                | —                |
| `label`    | `ReactNode` (presente → FAB estendido)     | —                |
| `position` | `"bottom-right" \| "bottom-left" \| "none"` | `"bottom-right"` |
| `size`     | `"sm" \| "md" \| "lg"`                     | `"md"`           |
| `variant`  | `"primary" \| "surface"`                   | `"primary"`      |
| ...        | Todos os atributos de `HTMLButtonElement`  | —                |

!!! warning "FAB só de ícone precisa de `aria-label`"
    Sem `label` visível, o FAB redondo não tem nome acessível. Sempre passe `aria-label` descrevendo a ação (`aria-label="Novo"`); quando há `label`, ele já serve de nome.

## `Tooltip`

> **Quando usar**: dar contexto extra a um controle cujo significado não é óbvio — tipicamente botões `iconOnly`. Nunca para informação crítica.

Hover tooltip portalado. Aparece no hover **e** no foco por teclado.

```tsx
<Tooltip content="Excluir permanentemente" placement="bottom" openDelay={300}>
  <Button variant="danger" iconOnly aria-label="Excluir">
    <Trash />
  </Button>
</Tooltip>
```

| Prop        | Tipo                                     | Default |
| ----------- | ---------------------------------------- | ------- |
| `content`   | `ReactNode`                              | —       |
| `placement` | `"top" \| "right" \| "bottom" \| "left"` | `"top"` |
| `openDelay` | `number` (ms antes de aparecer)          | `150`   |
| `disabled`  | `boolean` (desliga sem mexer no trigger) | `false` |

!!! warning "Não esconda informação essencial num tooltip"
    Usuários de touch não têm hover — eles nunca verão o conteúdo. Tooltip é reforço, não a única fonte de uma informação necessária para concluir a tarefa.

## `DropdownMenu`

> **Quando usar**: agrupar ações secundárias atrás de um único gatilho ("Mais ações", menu de perfil) quando elas não cabem na barra principal.

Menu suspenso de ações. Navegação por teclado (↑↓ Home End Esc). Cada entrada precisa de um `id` estável (usado como key do React).

```tsx
<DropdownMenu
  trigger={<Button variant="ghost">Mais ações</Button>}
  items={[
    { type: "label", id: "h", label: "Conta" },
    { type: "item", id: "edit", label: "Editar perfil", onSelect: () => navigate("/profile") },
    { type: "separator", id: "s1" },
    { type: "item", id: "logout", label: "Sair", onSelect: logout, danger: true },
  ]}
/>
```

| Entry type    | Campos                                                     |
| ------------- | ---------------------------------------------------------- |
| `"item"`      | `id`, `label`, `icon?`, `onSelect`, `disabled?`, `danger?` |
| `"label"`     | `id`, `label`                                              |
| `"separator"` | `id`                                                       |

Props do componente: `trigger` (`ReactElement`), `items` (`DropdownMenuEntry[]`), `placement` (`"bottom-start" \| "bottom-end" \| "top-start" \| "top-end"`, default `"bottom-start"`).

!!! note "Fecha após selecionar"
    Selecionar um item dispara `onSelect` e fecha o menu. Para um painel que permanece aberto com múltiplas escolhas (checkboxes, filtros), use `Popover` em vez de `DropdownMenu`.

## `Popover`

> **Quando usar**: um painel flutuante com conteúdo arbitrário (filtros, mini-form, preview) ancorado a um gatilho — quando você precisa de mais que uma lista de ações.

Painel flutuante genérico (anchor + outside-click + Esc dismiss). Funciona controlado (`open` + `onOpenChange`) ou não-controlado (`defaultOpen`).

```tsx
<Popover
  open={open}
  onOpenChange={setOpen}
  placement="bottom"
  trigger={<Button>Filtros</Button>}
>
  <Stack gap={3}>
    <Checkbox label="Apenas ativos" />
    <Checkbox label="Pago" />
    <Button onClick={() => setOpen(false)}>Aplicar</Button>
  </Stack>
</Popover>
```

| Prop                  | Tipo                                     | Default        |
| --------------------- | ---------------------------------------- | -------------- |
| `trigger`             | `ReactElement` (clonado com handlers)    | —              |
| `open`                | `boolean`                                | — (controlled) |
| `onOpenChange`        | `(open: boolean) => void`                | —              |
| `defaultOpen`         | `boolean` (uso não-controlado)           | `false`        |
| `placement`           | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"`     |
| `closeOnEsc`          | `boolean`                                | `true`         |
| `closeOnOutsideClick` | `boolean`                                | `true`         |

!!! note "Sem collision detection"
    O `Popover` não reposiciona automaticamente quando esbarra na borda da viewport. Se você precisa de flip/shift automático, prefira o `DropdownMenu` (lista simples) ou integre Floating UI no app.

## `ConfirmDialog`

> **Quando usar**: a última barreira antes de uma ação irreversível ou cara (excluir, sobrescrever, cancelar). Sempre com `variant="danger"` quando destrutiva.

Prompt destrutivo pré-montado em cima do [`Modal`](./overlay.md) (texto + 2 botões).

```tsx
<ConfirmDialog
  open={open}
  title="Excluir usuário"
  description={`Esta ação é permanente. Excluir ${user.name}?`}
  confirmLabel="Sim, excluir"
  cancelLabel="Cancelar"
  variant="danger"
  loading={deleting}
  onConfirm={async () => {
    await deleteUser(user.id);
    setOpen(false);
  }}
  onCancel={() => setOpen(false)}
/>
```

| Prop           | Tipo                                                    | Default       |
| -------------- | ------------------------------------------------------- | ------------- |
| `open`         | `boolean`                                               | —             |
| `title`        | `ReactNode`                                             | —             |
| `description`  | `ReactNode`                                             | —             |
| `confirmLabel` | `string`                                                | `"Confirmar"` |
| `cancelLabel`  | `string`                                                | `"Cancelar"`  |
| `variant`      | `"primary" \| "danger"`                                 | `"primary"`   |
| `loading`      | `boolean` (mostra spinner + desabilita ambos os botões) | `false`       |
| `onConfirm`    | `() => void \| Promise<void>`                           | —             |
| `onCancel`     | `() => void`                                            | —             |

!!! tip "Controle o loading durante a request"
    `onConfirm` aceita uma promise, mas o `ConfirmDialog` não gerencia o estado de loading sozinho — passe `loading={deleting}` controlado pelo seu estado para travar ambos os botões enquanto a ação assíncrona corre.

## `InstallButton`

Botão de instalação do PWA, ligado ao prompt `beforeinstallprompt` ([`useBeforeInstallPrompt`](../hooks.md)). **Renderiza `null`** quando o app não pode ser instalado — prompt ainda não capturado, já instalado, ou rodando standalone — então você o solta na UI sem guardar visibilidade. Herda todas as props do [`Button`](#button).

```tsx
import { InstallButton } from "tempest-react-sdk";
import { Download } from "lucide-react";

<InstallButton variant="primary" leftIcon={<Download size={18} />} />;
```

| Prop       | Tipo                                                       | Default          |
| ---------- | ---------------------------------------------------------- | ---------------- |
| `label`    | `ReactNode`                                                | `"Instalar app"` |
| `onResult` | `(o: "accepted" \| "dismissed" \| "unsupported") => void`  | —                |
| …          | todas as props de `Button` (`variant`, `size`, `leftIcon`) | —                |

## `InstallBanner`

Banner inferior dispensável que convida a instalar o PWA. Aparece só quando há prompt capturado e o app **não** está standalone; em plataformas que nunca disparam `beforeinstallprompt` (iOS Safari) fica oculto — surfa instruções manuais em outro lugar. `storageKey` lembra a dispensa entre recarregamentos.

```tsx
<InstallBanner
  title="Instale o app"
  description="Acesso offline e atalho na tela inicial."
  storageKey="meu-app:install-dismissed"
/>;
```

| Prop           | Tipo                  | Default        |
| -------------- | --------------------- | -------------- |
| `title`        | `ReactNode`           | `"Instale o app"` |
| `description`  | `ReactNode`           | —              |
| `installLabel` | `string`              | `"Instalar"`   |
| `dismissLabel` | `string`              | `"Dispensar"`  |
| `icon`         | `ReactNode`           | —              |
| `storageKey`   | `string`              | — (sessão)     |
| `onResult`     | `(o) => void`         | —              |

## Resumo

| Componente      | Use para                                       | Gatilho    |
| --------------- | ---------------------------------------------- | ---------- |
| `Button`        | Disparar a ação primária/secundária            | clique     |
| `FloatingActionButton` | Ação primária flutuante e persistente   | clique     |
| `InstallButton` | Instalar o PWA (some quando não aplicável)     | clique     |
| `InstallBanner` | Convite dispensável pra instalar o PWA         | clique     |
| `Tooltip`       | Contexto não-crítico num controle              | hover/foco |
| `DropdownMenu`  | Lista de ações secundárias (fecha ao escolher) | clique     |
| `Popover`       | Painel flutuante com conteúdo arbitrário       | clique     |
| `ConfirmDialog` | Confirmar ação destrutiva antes de executar    | —          |

Pontos-chave de acessibilidade:

- Ações destrutivas devem usar `variant="danger"`.
- `Button.loading` é o padrão para submits async — bloqueia duplos cliques.
- Tooltips não devem conter informação crítica (usuários de touch não veem hover).
- `iconOnly` **exige** `aria-label`.

Relacionados: [overlay](./overlay.md) (`ConfirmDialog` é construído sobre `Modal`) · [inputs](./inputs.md) (entrada de dados) · [feedback](./feedback.md) (toasts/alerts após a ação).

---

# components/advanced-chat.md

# Avançados: conversa

`Chat` para thread entre pessoas e `AIChat` para conversa com um modelo. São componentes diferentes, não variantes — e é por isso que têm página própria.

## `Chat`

> **Quando usar**: uma thread de mensagens — suporte, chat interno, comentário de documento, histórico de atendimento.

Agrupa por autor e por dia, marca o lado do usuário atual, mostra estado de entrega, quem está digitando, e traz o composer quando você passa `onSend`.

```tsx
import { Chat, Avatar, type ChatMessage } from "tempest-react-sdk";
import { useState } from "react";

export function Suporte({ me }: { me: { id: string } }) {
  const [mensagens, setMensagens] = useState<ChatMessage[]>([]);

  /** Insert otimista: a mensagem aparece antes do servidor confirmar. */
  const enviar = async (texto: string) => {
    const id = crypto.randomUUID();
    setMensagens((atual) => [
      ...atual,
      { id, body: texto, authorId: me.id, sentAt: Date.now(), status: "sending" },
    ]);
    await api.post("/mensagens", { body: { id, texto } });
    setMensagens((atual) =>
      atual.map((m) => (m.id === id ? { ...m, status: "sent" } : m)),
    );
  };

  return (
    <Chat
      messages={mensagens}
      currentUserId={me.id}
      onSend={enviar}
      onRetry={(m) => reenviar(m.id)}
      renderAvatar={(m) => <Avatar name={m.authorName ?? m.authorId} size="sm" />}
    />
  );
}
```

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `messages` | `ChatMessage[]` | — | A thread, **mais antiga primeiro**. Nunca reordenada. |
| `currentUserId` | `string` | — | Autor tratado como "seu": lado, cor e ticks de entrega. |
| `onSend` | `(text: string) => void \| Promise<void>` | — | Renderiza o composer. Recebe o texto já trimado. |
| `onRetry` | `(message: ChatMessage) => void` | — | Liga o botão de retry numa mensagem `"failed"`. |
| `onSendError` | `(error: unknown) => void` | — | Chamado quando `onSend` rejeita. O rascunho fica no campo. |
| `typing` | `string[]` | `[]` | Quem está digitando. Um, dois ou a contagem é fraseado pra você. |
| `renderAvatar` | `(message) => ReactNode` | — | Avatar da **primeira** mensagem de cada bloco. |
| `header` | `ReactNode` | — | Barra acima da thread, dentro do painel. |
| `groupWindowMs` | `number` | `300000` | Intervalo que ainda mantém mensagens no mesmo bloco. |
| `locale` | `"pt-BR" \| "en"` | `"pt-BR"` | Rótulos ("Hoje", "Você", "Enviando"…). |
| `emptyState` | `ReactNode` | `<EmptyState/>` | Thread vazia. |
| `composerDisabled` | `boolean` | `false` | Sem permissão, thread arquivada, offline. |

`ChatMessage = { id, body, authorId, authorName?, sentAt, status?, data? }` · `status` ∈ `"sending" | "sent" | "read" | "failed"`.

O componente é **apresentacional e controlado**, como o resto do SDK: recebe a lista e emite intenção. De onde vêm as mensagens (REST, o `createWebSocket` do SDK, um stream SSE) e como o insert otimista é feito ficam com o app, porque isso muda por backend.

!!! tip "A rolagem só pula pro fim se você já estava no fim"
    Uma thread que sempre rola pra mensagem nova arranca quem está lendo o histórico, toda vez que qualquer pessoa digita. Então o pulo acontece só quando o leitor já estava embaixo (com 48px de folga pra última linha parcialmente visível) — a regra pra qual todo app de chat converge. Verificado no browser: lendo o histórico no topo, três mensagens chegaram e a posição não se moveu.

!!! info "Bloco quebra por autor, por dia **e** por intervalo"
    Repetir avatar e nome em cada linha de uma rajada de cinco transforma conversa em lista de recibos. Mas uma resposta uma hora depois é um novo momento da conversa mesmo que ninguém tenha falado no meio — juntar ao bloco anterior colocaria um timestamp só em mensagens separadas por uma hora. O `groupWindowMs` é esse limite.

!!! warning "Estado de falha não é enfeite"
    Sem `"failed"` + `onRetry`, o usuário redigita o que já está na tela. A bolha que falhou mantém o **texto legível** (borda e meta em vermelho, não o fundo inteiro) justamente porque reler a mensagem é o que a pessoa faz antes de decidir reenviar.

!!! info "A thread é `role=\"log\"` com `aria-live=\"polite\"` e alcançável por teclado"
    Mensagem nova é anunciada sem roubar o foco. O contêiner tem `tabIndex={0}` porque uma área que rola e não tem nada focável dentro é inacessível pelo teclado — o mesmo problema que a [correção de rolagem](./data.md) resolveu no `Table`. Estado de entrega vai em texto (`VisuallyHidden`), não só no glifo: "✓✓" não é lido.

!!! tip "Serve como thread de comentários"
    É o mesmo componente **sem** `currentUserId` e sem `typing`: todos do mesmo lado, nome por bloco. Foi por isso que "quem sou eu" virou uma prop em vez de um campo `own` em cada mensagem — num comentário de documento ninguém quer marcar 200 mensagens.

#### `ChatComposer`

Exportado à parte pra quem monta o próprio layout (composer fixo no rodapé de uma rota, por exemplo). Textarea que cresce com o conteúdo, `Enter` envia, `Shift+Enter` quebra linha.

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `onSend` | `(text: string) => void \| Promise<void>` | — | Recebe o texto trimado. Limpa o campo só se não rejeitar. |
| `onError` | `(error: unknown) => void` | — | Erro do `onSend`. Rascunho preservado de qualquer forma. |
| `actions` | `ReactNode` | — | Antes do botão de enviar — anexo, emoji. |
| `maxRows` | `number` | `6` | Altura máxima, em linhas. |
| `sendLabel` | `string` | locale | Rótulo do botão. |

!!! warning "Ele é **não controlado**, de propósito"
    Rascunho de chat muda a cada tecla, e subir isso pro estado do app re-renderiza a thread inteira por caractere — o único lugar onde "controlado por default" custa algo visível. Quem precisa do rascunho (composer persistido, menu de slash-command) lê pelo `onChange` ou usa o ref (`focus()`, `setValue()`).

!!! danger "IME: `Enter` durante composição não envia"
    Compondo japonês ou coreano, `Enter` confirma a palavra candidata. Enviar ali publica meia palavra e come a confirmação — daí a checagem de `isComposing`.

## `AIChat`

> **Quando usar**: conversa com um **modelo** — copiloto do seu app, assistente de suporte, busca conversacional. É a forma que o ChatGPT, o Claude e o DeepSeek convergiram.

Turnos por papel (`user` / `assistant` / `system`), resposta em Markdown com bloco de código, raciocínio em bloco separado, cursor de streaming, ações por turno (copiar, gerar de novo, editar, 👍/👎) e um composer que **vira botão de parar** enquanto a resposta chega.

!!! info "`AIChat` e [`Chat`](#chat) são componentes diferentes, não variantes"
    Uma thread humana é endereçada por **autor** e se preocupa com estado de entrega. Um transcript de modelo é endereçado por **papel**, não tem estado de entrega nenhum, e precisa de três coisas que uma thread humana nunca precisa: saída parcial, raciocínio separado da resposta e re-perguntar. Encaixar os dois num `variant` misturaria dois modelos de dados no mesmo `props` e deixaria `authorId`/ticks mortos no caminho LLM.

Comece com o mínimo — uma lista e um `onSend`:

```tsx
import { AIChat, type AIChatMessage } from "tempest-react-sdk";
import { useState } from "react";

export function Copiloto() {
  const [turnos, setTurnos] = useState<AIChatMessage[]>([]);

  const perguntar = async (texto: string) => {
    setTurnos((atual) => [
      ...atual,
      { id: crypto.randomUUID(), role: "user", content: texto },
    ]);
    const resposta = await fetch("/api/ask", {
      method: "POST",
      body: JSON.stringify({ prompt: texto }),
    }).then((r) => r.json());
    setTurnos((atual) => [
      ...atual,
      { id: crypto.randomUUID(), role: "assistant", content: resposta.text },
    ]);
  };

  return <AIChat messages={turnos} onSend={perguntar} />;
}
```

Isso já te dá o transcript, o Markdown, o composer, o `Enter`/`Shift+Enter`, a rolagem que segue a resposta e a ação de copiar. O que falta é o **streaming** — e é aí que o componente ganha a cara de produto.

#### Streaming, do zero

O SDK **não** faz a chamada por você: "como eu faço streaming do meu backend" tem resposta diferente por provider. O que ele faz é renderizar o estado. O contrato é simples — vá reescrevendo o `content` do **último** turno e mantenha `streaming: true` nele até acabar:

```tsx
import { AIChat, type AIChatMessage } from "tempest-react-sdk";
import { useRef, useState } from "react";

export function CopilotoStreaming() {
  const [turnos, setTurnos] = useState<AIChatMessage[]>([]);
  const [pendente, setPendente] = useState(false);
  const abortar = useRef<AbortController | null>(null);

  /** Reescreve o último turno a cada chunk — o componente segue o texto sozinho. */
  const escrever = (id: string, texto: string) =>
    setTurnos((atual) =>
      atual.map((t) => (t.id === id ? { ...t, content: texto } : t)),
    );

  const perguntar = async (prompt: string) => {
    const idResposta = crypto.randomUUID();
    setTurnos((atual) => [
      ...atual,
      { id: crypto.randomUUID(), role: "user", content: prompt },
    ]);
    setPendente(true);

    abortar.current = new AbortController();
    const resposta = await fetch("/api/stream", {
      method: "POST",
      body: JSON.stringify({ prompt }),
      signal: abortar.current.signal,
    });

    setPendente(false);
    setTurnos((atual) => [
      ...atual,
      { id: idResposta, role: "assistant", content: "", streaming: true },
    ]);

    const leitor = resposta.body!.pipeThrough(new TextDecoderStream()).getReader();
    let acumulado = "";
    try {
      while (true) {
        const { value, done } = await leitor.read();
        if (done) break;
        acumulado += value;
        escrever(idResposta, acumulado);
      }
    } catch (erro) {
      if ((erro as Error).name !== "AbortError") throw erro;
    } finally {
      setTurnos((atual) =>
        atual.map((t) =>
          t.id === idResposta ? { ...t, streaming: false } : t,
        ),
      );
    }
  };

  return (
    <AIChat
      messages={turnos}
      pending={pendente}
      onSend={perguntar}
      onStop={() => abortar.current?.abort()}
      composerFooter={<small>Pode errar — confira números antes de decidir.</small>}
    />
  );
}
```

O que você ganha de graça nesse trecho:

| Você fez | O componente faz |
| --- | --- |
| `pending` enquanto a request está no ar | Mostra os três pontinhos e já troca **Enviar** por **Parar** |
| `streaming: true` no último turno | Desenha o cursor `▍` no fim do texto e esconde as ações daquele turno |
| Reescreve `content` a cada chunk | Rola pra acompanhar — **só se** o leitor já estava embaixo |
| `onStop` | Botão de parar no lugar do enviar, e `Escape` no campo também aborta |
| `streaming: false` no fim | Cursor sai, ações voltam, e o leitor de tela anuncia "Resposta concluída" |

!!! tip "Se seu backend fala SSE, use o `createEventStream` do SDK"
    O laço acima é `fetch` + `ReadableStream` porque é o caminho comum de APIs de LLM. Pra um endpoint `text/event-stream` de verdade, o [`sse`](../sse.md) do SDK já cuida de reconexão e `Last-Event-ID` — o loop de `escrever()` é o mesmo.

#### Raciocínio (extended thinking / R1)

Um turno com `reasoning` ganha um bloco colapsável **acima** da resposta:

```tsx
{
  id: "a1",
  role: "assistant",
  content: "São 12 pedidos.",
  reasoning: "Filtrei por data de entrega vencida e status != entregue…",
}
```

!!! info "Enquanto só o raciocínio chegou, o bloco abre sozinho"
    Se o turno está com `streaming: true` e o `content` ainda está vazio, o bloco de raciocínio monta **aberto** — é o único conteúdo que existe, e escondê-lo deixaria a tela parada com um cursor piscando no vácuo. Terminou, ele continua aberto (quem quiser fecha); usar `defaultReasoningOpen` abre **todos**, o que serve pra uma tela de auditoria.

#### Ações por turno

| Ação | Aparece em | Prop que liga |
| --- | --- | --- |
| Copiar | todo turno | sempre (copia o Markdown **cru**, não o HTML) |
| Gerar de novo | **só** o turno de assistente mais novo | `onRegenerate` |
| 👍 / 👎 | turno de assistente | `onFeedback` |
| Editar | turno de usuário | `onEditSubmit` |
| Tentar de novo | turno com `error` | `onRetry` |

```tsx
<AIChat
  messages={turnos}
  onRegenerate={(turno) => reperguntar(turno)}
  onFeedback={(turno, voto) => track("answer_rated", { id: turno.id, voto })}
  onEditSubmit={(turno, texto) => {
    truncarAPartirDe(turno.id);   // seu app decide o que cai
    return perguntar(texto);
  }}
  votes={votosSalvos}             // opcional: votos que vieram do banco
/>
```

!!! warning "Gerar de novo aparece só no último turno de assistente — de propósito"
    Re-perguntar um turno do meio joga fora **todo** turno depois dele. Isso é uma operação diferente ("ramificar aqui") e precisa da própria confirmação; oferecer o mesmo botão nos dois casos convida a perder metade da conversa num clique.

!!! info "Editar não decide o que apagar"
    O `onEditSubmit` te entrega o turno e o texto novo. Quem trunca o transcript é o app, porque "apagar tudo depois" e "criar uma ramificação" são produtos diferentes e o SDK não deve escolher por você.

#### Prompts sugeridos e estado vazio

```tsx
<AIChat
  messages={[]}
  onSend={perguntar}
  suggestions={["Resuma o último relatório", "Quais pedidos atrasaram?"]}
/>
```

Numa conversa vazia as sugestões aparecem no rodapé da área de transcript; clicar em uma envia direto. Somem no primeiro turno. Sem `onSend` elas não são renderizadas (não haveria pra onde mandar) e cai no `EmptyState` — ou no seu `emptyState`.

#### Props

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `messages` | `AIChatMessage[]` | — | O transcript, **mais antigo primeiro**. Nunca reordenado. |
| `onSend` | `(text: string) => void \| Promise<void>` | — | Renderiza o composer. Recebe o prompt já trimado. |
| `onStop` | `() => void` | — | Aborta o turno no ar. Troca enviar por parar; `Escape` também aborta. |
| `pending` | `boolean` | `false` | Request no ar, nada de volta ainda. |
| `onRegenerate` | `(message) => void` | — | Liga o "gerar de novo" no último turno de assistente. |
| `onEditSubmit` | `(message, text) => void \| Promise<void>` | — | Liga o "editar" nos turnos de usuário. |
| `onFeedback` | `(message, vote) => void` | — | Liga 👍/👎. `vote` ∈ `"up" \| "down"`. |
| `onRetry` | `(message) => void` | — | Liga o retry num turno com `error`. |
| `onSendError` | `(error: unknown) => void` | — | Erro do `onSend` **ou** do `onEditSubmit`. Rascunho preservado. |
| `votes` | `Record<string, AIChatVote>` | — | Votos que o app guarda. Sem isso o estado pressionado é local. |
| `suggestions` | `string[]` | `[]` | Prompts oferecidos numa conversa vazia. |
| `renderAvatar` | `(message) => ReactNode` | — | Avatar por turno. |
| `renderContent` | `(message) => ReactNode` | — | Substitui o corpo — card de tool-call, gráfico, lista de citações. |
| `showSystem` | `boolean` | `false` | Mostra turnos `"system"`. |
| `defaultReasoningOpen` | `boolean` | `false` | Abre todos os blocos de raciocínio. |
| `showLineNumbers` | `boolean` | `false` | Numera linha em bloco de código. |
| `header` | `ReactNode` | — | Barra acima do transcript, dentro do painel. |
| `composerActions` | `ReactNode` | — | Antes do botão de enviar — anexo, seletor de modelo. |
| `composerFooter` | `ReactNode` | — | Abaixo do campo — contagem de token, disclaimer. |
| `composerDisabled` | `boolean` | `false` | Sem crédito, conversa arquivada, offline. |
| `maxRows` | `number` | `8` | Altura máxima do composer, em linhas. |
| `locale` | `"pt-BR" \| "en"` | `"pt-BR"` | Rótulos ("Parar", "Raciocínio", "Você"…). |
| `emptyState` | `ReactNode` | `<EmptyState/>` | Conversa vazia. |

`AIChatMessage = { id, role, content, reasoning?, streaming?, error?, createdAt?, model?, attachments?, data? }` · `role` ∈ `"user" \| "assistant" \| "system"`.

`AIChatAttachment = { id, name, size?, url?, mimeType? }` — com `url` vira miniatura, sem `url` vira chip com nome e tamanho.

#### Decisões que valem saber

!!! info "Resposta é Markdown, prompt é texto puro"
    Um modelo emite Markdown por contrato. Uma pessoa que digitou `calcule 2 * 3 * 4` não quis abrir um span de ênfase — e ver o próprio prompt reescrito é desconcertante. Por isso o turno de usuário é `white-space: pre-wrap` e o de assistente passa pelo [`Markdown`](advanced-data.md#markdown) (que já usa o [`CodeBlock`](utility.md#codeblock) nos blocos cercados). Quer Markdown no prompt também? `renderContent`.

!!! tip "A resposta é o documento, não uma bolha"
    Turno de assistente ocupa a largura toda, sem bolha; turno de usuário é uma bolha estreita encostada no fim da linha. Envolver a resposta numa bolha limitaria a largura dela, brigaria com as tabelas e blocos de código dentro, e faria resposta longa parecer mensagem gritada. O prompt é curto e precisa ser distinguido num relance, o que a bolha faz melhor que qualquer outra coisa.

!!! danger "O transcript **não** é `aria-live` — e isso é acessibilidade, não descuido"
    Uma região viva sobre texto em streaming faz o leitor de tela reler a resposta a cada token: inutilizável. Então o `role="log"` fica sem `aria-live`, e os dois momentos que importam ("Gerando resposta", "Resposta concluída") são anunciados por um `role="status"` separado. O turno em andamento leva `aria-busy`, e a resposta pronta é lida do log no ritmo de quem lê. O `axe` do jsdom não pega esse tipo de erro — foi decisão de projeto, verificada no browser.

!!! tip "A rolagem só segue a resposta se você já estava no fim"
    Mesma regra do [`Chat`](#chat), e aqui ela pesa mais: um transcript que sempre pula pro texto novo arrancaria o leitor **dezenas de vezes por segundo** durante o streaming. Quando você não está no fim, aparece um botão redondo pra voltar — o pulo nunca acontece sem você pedir.

!!! warning "A dependência do efeito de rolagem não é a lista"
    Streaming acrescenta ao **último** turno. Um app que mutasse esse objeto no lugar — ou que re-renderizasse de uma store guardando o mesmo array — manteria a mesma dependência enquanto o texto cresce, e a visão pararia de seguir a resposta. É por isso que existe `tailSignature()` (exportado): tamanho da lista + identidade do último turno + tamanho do texto dele cobrem as duas formas.

!!! info "Só o turno que cresce re-parseia"
    O `Markdown` parseia no próprio render, e o React não re-renderiza um filho cujo elemento é referencialmente o mesmo. Segurar esse elemento entre renders é o que impede um transcript de cinquenta turnos de re-parsear toda resposta já pronta a cada token da mais nova.

!!! tip "Parar ocupa o lugar do enviar, não um botão ao lado"
    O único botão embaixo do dedo é sempre o que você quer a seguir: enviar quando está parado, abortar quando a resposta está vindo. Dois botões lado a lado significariam acertar o certo no meio do stream.

!!! warning "Ação escondida em `:hover` é ação inexistente no touch"
    A linha de ações aparece no hover e no foco de teclado, e fica **sempre** visível onde não existe hover (`@media (hover: none)`). Sem isso, num celular o primeiro toque cairia no que estiver embaixo. Verificado com device de toque emulado: `hover: none` e `pointer: coarse` verdadeiros, linha com `opacity: 1`.

    Os botões medem 28×28 — acima do piso de 24×24 da WCAG 2.5.8, abaixo dos 44×44 da 2.5.5, e são **quatro** lado a lado. Em `pointer: coarse` um hit-slop de `::after` leva o alvo real a **44×44** sem mover um pixel do que se vê, o mesmo truque que o [`Button`](actions.md#button) usa nos tamanhos icon-only. Aumentar o `padding` em vez disso espalharia a linha no desktop, onde o ponteiro é preciso e a linha deve ficar quieta.

#### Responsivo: de celular a TV

Medido no browser em 360×640, 390×844, 740×360 (celular em paisagem), 768×1024, 1440×900, 1920×1080 e 3840×2160. Em **toda** largura: zero overflow horizontal na página e no transcript, composer sempre visível, tabela e bloco de código rolando **na própria caixa**.

O que muda com a largura:

| Faixa | O que acontece |
| --- | --- |
| até 480px | `gap` e `padding` do transcript encurtam, bolha do usuário e editor vão a `max-width: 100%` |
| 480px – 768px | a coluna de leitura acompanha a largura disponível |
| 768px e acima | a coluna trava em `48rem` e **centraliza**; a sobra fica de margem |

!!! tip "A largura da coluna é um knob: `--tempest-ai-chat-width`"
    Coluna limitada é a resposta certa do celular até um desktop 1920 — texto passando de ~90 caracteres por linha é mensuravelmente mais difícil de rastrear de volta ao começo da linha seguinte, e deixar a resposta correr a tela toda de um monitor largo piora, não ajuda.

    De 2560 pra cima a troca se inverte: 768px no meio de uma tela de sala é quase só espaço vazio, e **só o app sabe** a que distância a pessoa está sentada. Por isso é knob e não constante:

    ```css
    :root {
      --tempest-ai-chat-width: 72rem; /* default 48rem */
    }
    ```

    Um valor só move os turnos, o indicador de "pensando", as sugestões **e** o composer juntos.

!!! warning "Tamanho de tipo não é resolvido aqui"
    A fonte é a mesma em 360px e em 4K. Escalar tipo pra TV é decisão de `typography.css` e `density.css` — uma rampa de fonte local ao componente brigaria com os tokens que todo app tematiza. Se você mira TV, suba `--tempest-text-*` no `:root` (ou use `[data-tempest-density="spacious"]`) junto com `--tempest-ai-chat-width`.

#### `AIChatComposer` e `AIChatTurn`

Exportados à parte pra quem monta o próprio layout — um composer fixo no rodapé de uma rota, um diff lado a lado de duas respostas. Mesmas props relevantes do painel, e o `AIChatComposer` é **não controlado** pelo mesmo motivo do [`ChatComposer`](#chatcomposer): rascunho muda a cada tecla, e subir isso pro estado do app re-renderiza o transcript inteiro por caractere — com uma resposta em streaming em cima, isso é visível.

| Helper exportado | Pra que serve |
| --- | --- |
| `visibleTurns({ messages, showSystem })` | A lista que o painel realmente renderiza. |
| `isGenerating(messages)` | Algum turno está em streaming. |
| `lastAssistantId(messages)` | Qual turno recebe o "gerar de novo". |
| `tailSignature(messages)` | Dependência de efeito que muda quando a cauda cresce. |
| `aiChatStrings(locale)` · `roleLabel(role, strings)` · `turnTime(ts, locale)` | Rótulos, pra reusar num layout próprio. |

## Recap

- **Conversa**: `Chat` para thread entre pessoas (autor, entrega, digitando) e `AIChat` para conversa com um modelo (papel, streaming, raciocínio, re-perguntar). São componentes diferentes, não variantes.
- Todos seguem os mesmos padrões controlado/não-controlado, expõem A11y por teclado e importam de `tempest-react-sdk`.

---

# components/advanced-data.md

# Avançados: dados

Tabela stateful, assistente em passos, markdown, mural, tour guiado, transferência entre listas, barra de filtros e kanban. Cada um resolve uma tela inteira.

## `DataTable<T>`

Tabela de dados stateful construída sobre o `Table` headless. Adiciona busca client-side, ordenação por clique no cabeçalho e paginação, delegando toda a marcação à `Table` subjacente.

```tsx
import { DataTable, type DataTableColumn } from "tempest-react-sdk";

interface User {
  id: number;
  name: string;
  email: string;
  role: string;
}

const columns: DataTableColumn<User>[] = [
  { key: "name", header: "Nome", sortable: true },
  { key: "email", header: "E-mail" },
  { key: "role", header: "Papel", sortable: true, align: "right" },
];

<DataTable
  data={users}
  columns={columns}
  searchable
  pageSize={10}
  initialSort={{ key: "name", direction: "asc" }}
  rowKey={(row) => row.id}
  emptyMessage="Nenhum usuário encontrado"
/>;
```

| Prop           | Tipo                                  | Default | Descrição                                               |
| -------------- | ------------------------------------- | ------- | ------------------------------------------------------- |
| `data`         | `T[]`                                 | —       | Dataset completo; sort/filtro/paginação são client-side |
| `columns`      | `DataTableColumn<T>[]`                | —       | Definições de coluna                                    |
| `pageSize`     | `number`                              | `10`    | Linhas por página                                       |
| `searchable`   | `boolean`                             | `false` | Renderiza um input de busca acima da tabela             |
| `searchKeys`   | `(keyof T)[]`                         | —       | Chaves buscadas; default = colunas string/number        |
| `initialSort`  | `DataTableSort<T>`                    | —       | Ordenação inicial antes de interagir com o cabeçalho    |
| `rowKey`       | `(row: T, index) => string \| number` | índice  | Extrator de chave estável por linha                     |
| `emptyMessage` | `ReactNode`                           | —       | Conteúdo exibido quando nenhuma linha combina           |

`DataTableColumn<T>` = `{ key: keyof T; header: ReactNode; render?: (row: T) => ReactNode; sortable?: boolean; align?: TableAlign; priority?: TablePriority; width?: string | number }`. `DataTableSort<T>` = `{ key: keyof T; direction: "asc" | "desc" }`.

!!! info "Comportamento"
    Clicar um cabeçalho ordenável cicla asc → desc → sem ordenação. A busca combina substring case-insensitive nas `searchKeys` (ou em toda coluna string/number quando omitidas). A paginação some quando o resultado cabe em uma única página.

## `Wizard`

Fluxo multi-passo: indicador, um corpo por vez e navegação que respeita **validação por passo**. O `Stepper` desenha o indicador; o `Wizard` é dono do que todo app reescrevia — índice ativo, gate assíncrono antes de avançar, botões desabilitados/pendentes e a chamada de conclusão.

```tsx
import { Button, FormActions, FormField, Input, Wizard, useZodForm } from "tempest-react-sdk";
import { FormProvider } from "react-hook-form";
import { z } from "zod";

const schema = z.object({
  nome: z.string().min(2, "Informe o nome"),
  email: z.string().email("E-mail inválido"),
  cep: z.string().min(9, "CEP incompleto"),
});

export function CadastroEmEtapas() {
  const form = useZodForm(schema, { defaultValues: { nome: "", email: "", cep: "" } });

  return (
    <FormProvider {...form}>
      <Wizard
        nextLabel="Avançar"
        backLabel="Voltar"
        finishLabel="Concluir"
        onComplete={form.handleSubmit((values) => console.log(values))}
        steps={[
          {
            id: "dados",
            label: "Dados",
            description: "Quem é o cliente",
            validate: () => form.trigger(["nome", "email"]),
            content: (
              <>
                <FormField name="nome" label="Nome" required><Input /></FormField>
                <FormField name="email" label="E-mail" required><Input type="email" /></FormField>
              </>
            ),
          },
          {
            id: "endereco",
            label: "Endereço",
            validate: () => form.trigger(["cep"]),
            content: <FormField name="cep" label="CEP" required><Input /></FormField>,
          },
          {
            id: "revisao",
            label: "Revisão",
            content: ({ back }) => (
              <>
                <pre>{JSON.stringify(form.getValues(), null, 2)}</pre>
                <Button variant="ghost" onClick={back}>Corrigir</Button>
              </>
            ),
          },
        ]}
      />
    </FormProvider>
  );
}
```

| Prop                 | Tipo                                          | Default    | Descrição                                                    |
| -------------------- | --------------------------------------------- | ---------- | ------------------------------------------------------------ |
| `steps`              | `WizardStep[]`                                | —          | Passos do fluxo.                                             |
| `activeIndex`        | `number`                                      | —          | Índice controlado.                                           |
| `defaultActiveIndex` | `number`                                      | `0`        | Índice inicial (não controlado).                             |
| `onStepChange`       | `(index, step) => void`                       | —          | Chamado a cada troca de passo.                               |
| `onComplete`         | `() => void \| Promise<void>`                 | —          | Chamado quando o último passo passa na validação.            |
| `nextLabel`          | `string`                                      | `"Next"`   | Rótulo do botão de avanço.                                   |
| `backLabel`          | `string`                                      | `"Back"`   | Rótulo do botão de voltar.                                   |
| `finishLabel`        | `string`                                      | `"Finish"` | Rótulo no último passo.                                      |
| `optionalLabel`      | `string`                                      | `"(optional)"` | Sufixo do passo opcional no indicador — troque para localizar.  |
| `clickableSteps`     | `boolean`                                     | `false`    | Permite pular clicando no indicador.                         |
| `renderActions`      | `(controls: WizardControls) => ReactNode`     | —          | Substitui a linha de botões padrão.                          |

`WizardStep = { id, label, description?, content, validate?, optional? }` — `content` aceita `ReactNode` **ou** função que recebe os controles.

`WizardControls = { activeIndex, step, validating, isFirst, isLast, next, back, goTo }`.

!!! warning "Só o passo ativo está montado"
    Input não commitado em um passo que você abandona **se perde**, a menos que o estado viva fora (o `FormProvider` do react-hook-form, uma store, um `useState` do pai) — que é onde ele deveria estar de todo jeito, já que o último passo normalmente submete tudo de uma vez.

!!! tip "`validate` assíncrono já vem com estado de pendência"
    Enquanto a promise corre, o botão de avanço fica em `loading` e o de voltar desabilitado. Um `validate` que **lança** conta como "não permitido": um gate ligado a checagem de rede não deve deixar o usuário num fluxo meio-avançado quando a requisição falha.

!!! note "`clickableSteps` é `false` de propósito"
    Um wizard existe porque a **ordem importa**. Com `clickableSteps`, pular pra trás é livre (voltar nunca bloqueia), mas pular pra frente valida **cada passo atravessado** — o primeiro gate que reprovar interrompe o salto ali.

## `Markdown`

> **Quando usar**: renderizar texto que veio de gente — comentário, descrição de ticket, release notes, corpo de mensagem.

Subconjunto de Markdown: headings, parágrafos, listas (aninhadas e numeradas), citação, código cercado (via [`CodeBlock`](utility.md#codeblock)), regra, tabela GFM com alinhamento, e o inline usual (`**forte**`, `*itálico*`, `` `código` ``, `~~riscado~~`, link, imagem, autolink, quebra forçada).

```tsx
import { Markdown } from "tempest-react-sdk";

<Markdown source={comentario.corpo} linkProps={{ target: "_blank", rel: "noreferrer" }} />;
```

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `source` | `string` | — | O Markdown. |
| `headingOffset` | `number` | `2` | Nível que o `#` do documento vira. |
| `highlightCode` | `boolean` | `true` | Código cercado via `CodeBlock` (copiar, número de linha). |
| `showLineNumbers` | `boolean` | `false` | Número de linha no código cercado. |
| `linkProps` | `AnchorHTMLAttributes` | — | Props extras em **todo** link. |

!!! danger "A segurança é estrutural, não uma promessa de escape"
    `dangerouslySetInnerHTML` **não existe** neste componente. O parser produz uma árvore de nós e o render vira elementos React — e um filho de React só pode ser texto. Então `<script>alert(1)</script>` num comentário renderiza como os caracteres que a pessoa digitou, e `<img src=x onerror=...>` também.

    Isso não é "HTML sanitizado": **é texto**. É por isso que não há sanitizador aqui, nem lista de tags permitidas — não há caminho por onde markup entre.

!!! danger "URL passa por allowlist de esquema, não blocklist"
    Link aceita `http`, `https`, `mailto`, `tel`, `sms` e relativo. Imagem aceita os mesmos, mais `data:image/` **raster** (png/jpeg/gif/webp/avif) — `data:image/svg+xml` fica fora de propósito: um SVG é um documento, carrega `<script>` e handler de evento.

    `[clique](javascript:alert(1))` renderiza **"clique"** como texto: o link cai, as palavras ficam. Blocklist teria que enumerar `javascript:`, `JaVaScRiPt:`, `java\tscript:`, `\u0001javascript:` — e erraria a que ninguém pensou. A allowlist não tem essa dívida.

!!! warning "É um subconjunto, e isso é o teto escolhido"
    Não tem HTML embutido, nota de rodapé, definition list, referência de link (`[a][b]`), nem lista de tarefa. Se o seu caso precisa de CommonMark completo com plugins, use `react-markdown` + `remark` direto — são 40 KB e uma cadeia de plugins que o SDK inteiro não paga. O escopo aqui é o que um comentário de usuário usa.

!!! info "`#` vira `h2` por default"
    Um comentário renderizado numa página cujo `h1` é o título da página não pode emitir um segundo `h1`. O `headingOffset` desloca a escala inteira e o componente nunca passa de `h6`, então a outline continua válida.

!!! check "Tabela larga rola na própria caixa, e a caixa é alcançável"
    A parada de tabulação aparece **só enquanto** o transbordo é real — área que rola sem nada focável dentro é inalcançável por teclado, e adicionar a parada sempre poluiria a ordem de tabulação com uma entrada por tabela.

## `Masonry`

> **Quando usar**: cards de **altura desigual** que não têm ordem entre si — mural de notas, galeria de fotos, cartões de dashboard.

Mede os cards e joga cada um na coluna mais curta, então a borda de baixo fica o mais reta que o conteúdo permite.

```tsx
import { Masonry, Card } from "tempest-react-sdk";

<Masonry items={notas} itemKey={(nota) => nota.id} columns={{ 0: 1, 640: 2, 1024: 3 }}>
  {(nota) => <Card title={nota.titulo}>{nota.corpo}</Card>}
</Masonry>;
```

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `items` | `T[]` | — | O que distribuir. |
| `children` | `(item: T, index: number) => ReactNode` | — | Render de um card. |
| `columns` | `number \| Record<number, number>` | `{ 0: 1, 640: 2, 1024: 3 }` | Número fixo, ou mapa **largura → colunas**. |
| `itemKey` | `(item: T, index: number) => string \| number` | índice | Chave estável por item. |
| `gap` | `string` | `--tempest-space-4` | Espaço entre cards. |

!!! info "Por que não é uma linha de CSS"
    `columns` do CSS **quebra o card** na fronteira da coluna, e `grid-auto-flow: dense` mantém cada linha na altura da célula mais alta — que é exatamente a borda serrilhada que se usa masonry pra evitar. As duas são uma linha de CSS e nenhuma faz este trabalho.

!!! warning "A ordem de leitura desce a coluna, não atravessa a linha"
    Card 2 fica **embaixo** do card 1, não ao lado. É por isso que este layout serve pra itens **independentes**: uma lista em que o item 2 precisa vir depois do 1 quer um grid, não isto. Se a ordem importa pro seu conteúdo, não use masonry — nem aqui, nem em CSS puro.

!!! check "O mapa de breakpoints é sobre o contêiner, não sobre o viewport"
    Um masonry dentro de um drawer ou de uma página de duas colunas é mais estreito que a janela, e uma media query daria a ele três colunas com 300px de largura. Um `ResizeObserver` é o que faz `{ 0: 1, 640: 2 }` significar "deste contêiner", que é a única leitura útil.

!!! info "Coluna mais curta, não round-robin"
    `index % colunas` é o caminho óbvio e produz colunas desiguais no primeiro momento em que os itens têm alturas diferentes — que é o único motivo pra usar masonry.

!!! tip "Imagem que carrega depois é re-medida"
    Cada card é observado individualmente: altura medida na montagem erra justamente no caso da imagem que ainda estava baixando. O primeiro paint usa peso 1 pra todos (nunca aparece vazio) e o passe medido redistribui.

## `Tour`

> **Quando usar**: apresentar uma tela nova — onboarding de primeiro acesso, um recurso que mudou de lugar, um fluxo que ninguém acha sozinho.

Escurece a página, destaca um elemento por vez e explica. O elemento destacado **continua clicável**.

```tsx
import { Tour } from "tempest-react-sdk";
import { useState } from "react";

export function Pedidos() {
  const [aberto, setAberto] = useState(!storage.get("tour-pedidos-v1"));

  return (
    <>
      {/* … a tela … */}
      <Tour
        open={aberto}
        steps={[
          { target: "#novo-pedido", title: "Comece aqui", body: "Todo pedido nasce deste botão." },
          { target: "[data-tour='filtros']", body: "E filtre por período aqui.", placement: "right" },
        ]}
        onClose={() => setAberto(false)}
        onFinish={() => storage.set("tour-pedidos-v1", true)}
      />
    </>
  );
}
```

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `steps` | `TourStep[]` | — | As paradas, em ordem. |
| `open` | `boolean` | — | Controlado pelo app. |
| `onClose` | `() => void` | — | `Esc`, botão de fechar, "pular" ou clique no escuro. |
| `onFinish` | `() => void` | — | Depois do último passo, antes do `onClose`. |
| `index` / `onIndexChange` | `number` / `(i) => void` | interno | O app dirige o passo atual, se quiser. |
| `spotlightPadding` | `number` | `4` | Folga em volta do elemento destacado. |
| `locale` | `"pt-BR" \| "en"` | `"pt-BR"` | Rótulos. |

`TourStep = { target?, title?, body, placement? }` · `placement` ∈ `"top" | "bottom" | "left" | "right" | "center"`.

!!! check "O elemento destacado continua clicável — e é isso que faz um coachmark útil"
    O escuro são **quatro retângulos** em volta do alvo, não um overlay com buraco de `box-shadow`. Motivo: sombra **não é hit-testável**, então um buraco feito assim não bloquearia clique nenhum — o resto da página continuaria clicável e o alvo, não. Com quatro retângulos é o contrário, que é o que "aperte este botão" precisa.

!!! info "O alvo é um **seletor**, não um ref"
    Assim um tour pode ser declarado como dado — num arquivo de config, vindo do backend, ao lado da cópia — sem cada tela ter que passar refs pra quem renderiza o tour.

!!! warning "Passo cujo alvo não existe aparece centralizado, não desaparece"
    É o caso real: um recurso escondido por permissão, um botão que só existe com dado. Sumir com o passo esconderia a mensagem em silêncio, e pular pro seguinte poderia pular o tour inteiro.

!!! check "Teclado: setas andam, `Esc` sai, foco vai pro card"
    O card é `role="dialog"` + `aria-modal`, nomeado pelo título e descrito pelo corpo, com armadilha de foco (`useFocusTrap`) e "Passo 2 de 5" visível. O `Esc` é tratado **no card**, não na `window`: um tour aberto sobre um modal não fecha os dois.

!!! info "O card vira de lado quando não cabe — e vai pro centro quando nada cabe"
    Tenta o lado preferido, depois o **oposto** (vira relação de leitura com o alvo; pular pro lado moveria o card pela tela sem motivo visível), depois os outros. Card metade fora da tela é pior que card no meio — e isso acontece de verdade quando o alvo é mais alto que o viewport.

!!! tip "Persistir 'já viu' é do app"
    O componente recebe `open` e emite `onClose`/`onFinish`. Gravar a flag é uma linha no app (`storage.set`) e seria um default errado aqui — a chave tem versão, escopo por usuário, e às vezes mora no backend.

## `Transfer`

> **Quando usar**: escolher um **subconjunto** de um catálogo — permissões de um perfil, cidades de uma rota, membros de um grupo, colunas de um relatório.

Dois painéis, quatro controles de mover, busca em cada lado. Controlado pelos **ids do lado direito**; os dois painéis são derivados.

```tsx
import { Transfer, type TransferItem } from "tempest-react-sdk";
import { useState } from "react";

const PERMISSOES: TransferItem[] = [
  { id: "pedidos.ler", label: "Ler pedidos" },
  { id: "pedidos.criar", label: "Criar pedidos" },
  { id: "auditoria.ler", label: "Ler auditoria", disabled: true },
];

export function PermissoesDoPerfil() {
  const [permissoes, setPermissoes] = useState<string[]>([]);

  return (
    <Transfer
      items={PERMISSOES}
      value={permissoes}
      onChange={setPermissoes}
      sourceTitle="Disponíveis"
      targetTitle="Do perfil"
    />
  );
}
```

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `items` | `TransferItem[]` | — | O catálogo inteiro. Os dois painéis saem dele. |
| `value` | `string[]` | — | Ids do lado direito. **Controlado.** |
| `onChange` | `(value: string[]) => void` | — | Próximo valor, sempre na ordem do catálogo. |
| `sourceTitle` / `targetTitle` | `ReactNode` | `"Disponíveis"` / `"Selecionados"` | Título de cada painel. |
| `searchable` | `boolean` | `true` acima de 8 itens | Caixa de busca em cada painel. |
| `renderItem` | `(item, side) => ReactNode` | `item.label` | Corpo customizado da linha. |
| `height` | `string` | `"16rem"` | Altura da área de rolagem de cada painel. |
| `locale` | `"pt-BR" \| "en"` | `"pt-BR"` | Rótulos e anúncios. |
| `disabled` | `boolean` | `false` | Bloqueia todo movimento. |

`TransferItem = { id, label, searchText?, disabled?, data? }`

!!! info "Só os ids do lado direito são estado — os painéis são derivados"
    Guardar duas listas parece mais simples e **deriva** no primeiro momento em que o catálogo muda por baixo: uma permissão removida no servidor fica pendurada no painel que a tinha, e um id que aparece nos dois lados é um bug que ninguém vê. Com um `value` só, `items` manda: o que saiu do catálogo simplesmente desaparece dos dois lados.

!!! check "O botão de mover todos respeita o filtro"
    Filtrar por `sao` e clicar em "mover todos" move **o que você está vendo**, não o painel inteiro. Mover as linhas que o filtro escondeu é o tipo de surpresa que faz a pessoa parar de confiar no botão — e foi um bug real, pego por teste antes do merge.

!!! check "Busca dobra acento, nos dois sentidos"
    `sao` acha "São Paulo" e `são` também. Para um público PT-BR isso não é refinamento: um `includes` cru falharia na metade das buscas.

!!! warning "Linha `disabled` não se move por nenhum caminho"
    A checagem vive no `applyMove`, não em cada um dos quatro botões — é uma permissão obrigatória, um assento travado. Por isso o `»` move "todos os movíveis", não "todos".

!!! info "Depois de mover, as marcações são limpas"
    Senão o próximo clique no botão oposto manda tudo de volta, e o componente parece estar se desfazendo.

!!! info "Os controles ficam no meio pela grade, mas por último no DOM"
    Um teclado que chegasse nos botões antes de ver o que eles movem teria que voltar; e um leitor de tela leria "mover marcados pra direita" sem ideia do que está marcado. Cada painel é uma `region` nomeada pelo título, e cada movimento é anunciado num `role="status"`.

## `FilterBar`

> **Quando usar**: filtrar uma lista de admin — pedidos por status e período, usuários por papel, títulos por vencimento.

Chips com os filtros aplicados, e um editor pequeno pra adicionar outro. Os filtros são combinados com **E**, achatados.

```tsx
import {
  FilterBar,
  filtersFromSearchParams,
  filtersToSearchParams,
  type Filter,
  type FilterField,
} from "tempest-react-sdk";

const CAMPOS: FilterField[] = [
  { name: "titulo", label: "Título", type: "text" },
  { name: "total", label: "Total", type: "number" },
  { name: "criadoEm", label: "Criado em", type: "date" },
  {
    name: "status",
    label: "Status",
    type: "select",
    options: [
      { value: "paid", label: "Pago" },
      { value: "sent", label: "Enviado" },
    ],
  },
];

export function Pedidos() {
  // O conjunto vem da URL, então um link compartilhado abre com os mesmos filtros.
  const [filtros, setFiltros] = useState<Filter[]>(() =>
    filtersFromSearchParams(new URLSearchParams(location.search), CAMPOS),
  );

  const { data } = useQuery({
    queryKey: ["pedidos", filtros],
    queryFn: () => api.get(`/pedidos?${filtersToSearchParams(filtros)}`),
  });

  return <FilterBar fields={CAMPOS} value={filtros} onChange={setFiltros} />;
}
```

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `fields` | `FilterField[]` | — | Campos que podem ser filtrados. |
| `value` | `Filter[]` | — | Filtros aplicados. **Controlado.** |
| `onChange` | `(filters: Filter[]) => void` | — | Próximo conjunto, combinado com E. |
| `actions` | `ReactNode` | — | Ao lado dos controles — "salvar visão", contador. |
| `locale` | `"pt-BR" \| "en"` | `"pt-BR"` | Rótulos e descrições. |

`FilterField = { name, label, type, options?, operators?, placeholder? }` · `type` ∈ `"text" | "number" | "date" | "select" | "boolean"`
`Filter = { field, operator, value? }` · `operator` ∈ `eq · ne · contains · gt · gte · lt · lte · between · in · empty · notEmpty`

**Helpers exportados**: `applyFilters`, `filtersToQueryParams`, `filtersToSearchParams`, `filtersFromSearchParams`, `describeFilter`, `operatorsFor`.

#### Aplicando os filtros

O `FilterBar` **produz** `Filter[]`; quem avalia é você. O SDK dá as duas saídas, e você escolhe uma pelo tamanho da lista, não pelo gosto.

**Lista inteira na memória** — `applyFilters` roda os onze operadores:

```tsx
import { FilterBar, applyFilters, type Filter } from "tempest-react-sdk";

export function Pedidos({ pedidos }: { pedidos: Pedido[] }) {
  const [filtros, setFiltros] = useState<Filter[]>([]);
  const visiveis = useMemo(() => applyFilters(pedidos, filtros), [pedidos, filtros]);

  return (
    <>
      <FilterBar fields={CAMPOS} value={filtros} onChange={setFiltros} />
      <DataTable data={visiveis} columns={COLUNAS} />
    </>
  );
}
```

**Listagem paginada no servidor** — `filtersToQueryParams`, que fala o dialeto do `tempest-fastapi-sdk`:

```tsx
const params = filtersToQueryParams(filtros);
params.set("page", String(pagina));
params.set("page_size", "20");

const { data } = useQuery({
  queryKey: ["pedidos", filtros, pagina],
  queryFn: () => api.get(`/pedidos?${params}`),
});
```

| Operador | Param enviado |
| --- | --- |
| `eq` | `campo` (ou `campo__iexact` na coluna `name`) |
| `ne` | `campo__ne` |
| `contains` | `campo__icontains` |
| `gt` `gte` `lt` `lte` | `campo__gt` … `campo__lte` |
| `between` | `campo__between` duas vezes, menor primeiro |
| `in` | `campo__in`, uma vez por valor |
| `empty` / `notEmpty` | `campo__isnull=true` / `=false` |

!!! tip "O dialeto é o **default**, não uma lei"
    A tabela acima é o dialeto do `tempest-fastapi-sdk`. Backend diferente passa
    `options` em vez de reescrever o encoder:

    ```tsx
    // A coluna pesquisável é `razao_social`, e `ne` se escreve à moda Django.
    const params = filtersToQueryParams(filtros, {
      substringColumns: ["razao_social"],
      operatorSuffix: { ne: "__exclude" },
    });
    ```

    - `substringColumns` — as colunas cujo `eq` sai como `coluna__iexact`. Default
      `["name"]`, que é o caso especial de `build_filter_condition`. Passe `[]` se o
      seu backend não trata nenhuma coluna assim e um `eq` deve sair puro.
    - `operatorSuffix` — mesclado **sobre** o default, então o override nomeia só os
      operadores que diferem.

    Até a v0.44.0 os dois eram constantes fechadas no módulo. Quem tinha a coluna
    chamada `nome` ou `titulo` não conseguia o tratamento, e quem não tinha o caso
    especial recebia um `__iexact` que ninguém pediu.

!!! danger "O backend precisa **declarar** cada chave, senão o filtro falha calado"
    `BasePaginationFilterSchema.get_conditions()` só repassa campos que a subclasse declara. Um `status__ne` que o schema não menciona é descartado pelo FastAPI antes do repositório ver — sem erro, sem filtro, e a lista volta inteira parecendo que "o filtro não pegou". Declare `status__ne: str | None = None` no schema de filtro para cada operador que a tela oferece.

!!! warning "`applyFilters` e o backend discordam em dois pontos, de propósito"
    **`ne` casa linha sem valor.** No SQL, `coluna <> 'x'` é `NULL` quando a coluna é `NULL` e a linha some. No cliente, "não é pago" mostra também os pedidos sem status — que é o que o chip promete.
    **`empty` casa texto em branco.** `__isnull` no servidor só casa `NULL`; coluna que guarda `""` em vez de `NULL` responde diferente dos dois lados.
    Se a mesma tela alterna entre os dois modos, escolha um e fique nele por campo.

!!! info "`eq` é sensível a maiúscula; `contains` não é"
    É o alinhamento com o servidor: `eq` vira `WHERE coluna = valor`, e um cliente insensível discordaria dele. `contains` vira `icontains` e é insensível dos dois lados — e como é o operador **default** de campo de texto, o comportamento amigável é o que se ganha sem pedir.

!!! tip "Data compara por **dia**, e `between` é inclusivo nas duas pontas"
    Linha carimbada `2026-03-05T13:00:00Z` casa `eq 2026-03-05`, e um `between` invertido (data maior primeiro) é **normalizado** em vez de não casar nada — quem escolheu a data final primeiro quis o intervalo, não uma lista vazia.

!!! warning "É **E** achatado, não árvore com OU — e isso é o teto escolhido"
    Grupos aninhados (`(a OU b) E c`) são outro componente: exigem UI de árvore com operador por nó e outra serialização. Tentar ser os dois produz um builder desengonçado justamente no caso de 95% — "status é pago, criado depois de março, título contém nota". Se você precisa de OU aninhado, o que você quer é um query builder de verdade, e ele não cabe atrás desta API.

!!! check "O conjunto de filtros cabe na URL — e volta dela"
    `filtersToSearchParams` escreve `status=eq:paid&total=between:10|90`; `filtersFromSearchParams` lê de volta, e tem teste de **round-trip**. Filtro que não sobrevive a um reload é filtro que a pessoa redigita toda vez que abre um link que alguém mandou.

!!! danger "O que não parseia é **descartado**, não adivinhado"
    URL editada à mão é a forma normal desse dado chegar. Um operador que o campo não oferece (`total=contains:1`), um campo desconhecido, um `between` com uma ponta só — tudo cai fora. Renderizar um chip que o backend não consegue avaliar mostraria uma lista que não corresponde ao que o chip afirma.

!!! check "O chip lê em palavras, e é o mesmo texto que o leitor de tela ouve"
    "Status é Pago" — com o **label** da opção, não a chave (`paid`). O botão de remover usa a mesma frase no `aria-label` ("Remover filtro: Status é Pago"), porque um chip que diz uma coisa pra quem vê e outra pra quem ouve são duas verdades diferentes.

!!! info "O input segue o **campo**, não o operador"
    Campo de data ganha date picker mesmo no `between` (dois deles). Digitar data em caixa de texto é o caminho mais rápido pra produzir filtro que o backend não entende.

!!! tip "Filtro incompleto só desabilita o Aplicar"
    Não é erro pra gritar — é formulário meio preenchido. Trocar o operador limpa o valor, porque valor carregado entre operadores produz filtro que ninguém quis escrever.

## `Kanban`

> **Quando usar**: quadro de colunas com cards que mudam de estágio — backlog, pipeline de vendas, ordens de serviço por status.

Reordena dentro da coluna e move entre colunas, por ponteiro **ou** teclado. A máquina de arrasto é o `useSortable` — o quadro não reimplementa nada disso.

```tsx
import { applyKanbanMove, Kanban, type KanbanColumn } from "tempest-react-sdk";
import { useState } from "react";

export function QuadroDoBacklog() {
  const [colunas, setColunas] = useState<KanbanColumn[]>([
    { id: "todo", title: "A fazer", cards: [{ id: "1", content: "Corrigir login" }] },
    { id: "doing", title: "Fazendo", cards: [] },
    { id: "done", title: "Feito", cards: [], locked: true },
  ]);

  return (
    <Kanban
      label="Backlog"
      columns={colunas}
      onMove={(move) => setColunas((atual) => applyKanbanMove(atual, move))}
    />
  );
}
```

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `columns` | `KanbanColumn[]` | — | Colunas com seus cards, em ordem de exibição. |
| `onMove` | `(move: KanbanMove) => void` | — | Chamado **uma vez** por movimento confirmado. Você aplica. |
| `renderCard` | `(card, column) => ReactNode` | conteúdo do card | Customiza o corpo do card. |
| `label` | `string` | `"Quadro"` | Nome acessível do quadro. |
| `emptyLabel` | `ReactNode` | `"Nenhum card"` | Texto da coluna vazia. |
| `cardRoleDescription` | `string` | instrução de teclado | Anunciado por card — troque para localizar. |
| `disabled` | `boolean` | `false` | Bloqueia todo arrasto. |

`KanbanColumn = { id, title, cards, locked? }` · `KanbanCard = { id, content }` · `KanbanMove = { cardId, fromColumn, toColumn, toIndex }`.

`applyKanbanMove(columns, move)` é o reducer que aplica o movimento devolvendo arrays novos — exportado porque todo consumidor precisa do mesmo, e é onde vive o off-by-one.

!!! info "Coluna `locked` recusa entrada, mas deixa sair"
    É o caso de uma coluna "Feito" que não aceita mais trabalho, mas cujos cards ainda podem voltar atrás.

!!! warning "Movimento por teclado só alcança posição que tem card"
    O movimento caminha pelo espaço de índices dos cards existentes, então **soltar numa coluna vazia funciona por ponteiro, mas não por teclado**. Isso é limitação da implementação atual, não desenho: enquanto teclas de troca de coluna não entrarem, o caminho é mover para uma coluna que já tenha um card e reordenar.

!!! info "ARIA: um `listbox` por coluna, não um por quadro"
    Cada coluna com cards é um `listbox` nomeado pelo título, contendo só `option`. Um listbox único no quadro não sobrevive à marcação que um quadro precisa — `listbox` exige filhos `option`/`group`, e o cabeçalho da coluna no meio quebra essa posse. Coluna **vazia** não é marcada como listbox (zero `option` reprova `aria-required-children`), e o cabeçalho é `div`, não `<header>`: fora de elemento de seccionamento, todo `<header>` vira landmark `banner` — com três colunas, três banners duplicados.

## Recap

- **Dados**: `DataTable<T>` envolve o `Table` headless com busca, ordenação e paginação client-side.
- Todos seguem os mesmos padrões controlado/não-controlado, expõem A11y por teclado e importam de `tempest-react-sdk`.

---

# components/advanced-essentials.md

# Avançados: essenciais

Toggles, label, regiões expansíveis, menus disparados por interação e a paleta de comandos. A fatia que quase toda tela usa em algum momento.

## `Toggle`

Botão de dois estados — como um checkbox estilizado de botão. Controlado (`pressed` + `onPressedChange`) ou não-controlado (`defaultPressed`).

```tsx
import { Toggle } from "tempest-react-sdk";

<Toggle
  defaultPressed
  variant="outline"
  size="md"
  onPressedChange={(pressed) => console.log(pressed)}
>
  Negrito
</Toggle>;
```

| Prop              | Tipo                         | Default     | Descrição                                           |
| ----------------- | ---------------------------- | ----------- | --------------------------------------------------- |
| `pressed`         | `boolean`                    | —           | Estado controlado. Quando definido, vira controlado |
| `defaultPressed`  | `boolean`                    | `false`     | Estado inicial no modo não-controlado               |
| `onPressedChange` | `(pressed: boolean) => void` | —           | Disparado com o próximo estado ao ativar            |
| `size`            | `"sm" \| "md" \| "lg"`       | `"md"`      | Tamanho visual                                      |
| `variant`         | `"default" \| "outline"`     | `"default"` | Estilo visual                                       |

Demais props de `<button>` são repassadas.

!!! info "A11y"
    Renderiza um `<button type="button">` nativo expondo o estado via `aria-pressed` e `data-state="on"|"off"`.

## `ToggleGroup` (+ `ToggleGroupItem`)

Conjunto de toggles que compartilham estado de seleção via contexto. Modo `single` (valor `string`) ou `multiple` (valor `string[]`).

```tsx
import { ToggleGroup, ToggleGroupItem } from "tempest-react-sdk";

<ToggleGroup type="single" defaultValue="left" onValueChange={(value) => console.log(value)}>
  <ToggleGroupItem value="left">Esquerda</ToggleGroupItem>
  <ToggleGroupItem value="center">Centro</ToggleGroupItem>
  <ToggleGroupItem value="right">Direita</ToggleGroupItem>
</ToggleGroup>;
```

`ToggleGroup`:

| Prop            | Tipo                                  | Default    | Descrição                                                 |
| --------------- | ------------------------------------- | ---------- | --------------------------------------------------------- |
| `type`          | `"single" \| "multiple"`              | `"single"` | `single` mantém um valor; `multiple` mantém um conjunto   |
| `value`         | `string \| string[]`                  | —          | Valor controlado (`string` para single, `string[]` multi) |
| `defaultValue`  | `string \| string[]`                  | —          | Valor inicial não-controlado                              |
| `onValueChange` | `(value: string \| string[]) => void` | —          | Disparado com o próximo valor                             |
| `children`      | `ReactNode`                           | —          | Itens `ToggleGroupItem`                                   |

`ToggleGroupItem`:

| Prop       | Tipo        | Default | Descrição                           |
| ---------- | ----------- | ------- | ----------------------------------- |
| `value`    | `string`    | —       | Valor estável que identifica o item |
| `disabled` | `boolean`   | —       | Desabilita o item                   |
| `children` | `ReactNode` | —       | Conteúdo do item                    |

!!! note "Single mode"
    Em `single`, `onValueChange` recebe `""` (string vazia) quando nada está selecionado.

## `Label`

Um `<label>` de formulário. Associe a um controle via `htmlFor`. Com `required`, anexa um asterisco decorativo (`aria-hidden`).

```tsx
import { Label } from "tempest-react-sdk";

<Label htmlFor="email" required>
  E-mail
</Label>;
```

| Prop       | Tipo      | Default | Descrição                                                      |
| ---------- | --------- | ------- | -------------------------------------------------------------- |
| `required` | `boolean` | `false` | Anexa um asterisco em cor de perigo marcando campo obrigatório |

Demais props de `<label>` (incl. `htmlFor`) são repassadas.

## `Collapsible`

Uma única região expandir/recolher — alternativa mais leve ao `Accordion` para um bloco. Controlado (`open` + `onOpenChange`) ou não-controlado (`defaultOpen`).

```tsx
import { Collapsible } from "tempest-react-sdk";

<Collapsible trigger="Ver detalhes" defaultOpen={false}>
  <p>Conteúdo revelado ao expandir.</p>
</Collapsible>;
```

| Prop           | Tipo                      | Default | Descrição                                           |
| -------------- | ------------------------- | ------- | --------------------------------------------------- |
| `open`         | `boolean`                 | —       | Estado controlado. Quando definido, vira controlado |
| `defaultOpen`  | `boolean`                 | `false` | Estado inicial não-controlado                       |
| `onOpenChange` | `(open: boolean) => void` | —       | Disparado com o próximo estado ao ativar o gatilho  |
| `trigger`      | `ReactNode`               | —       | Conteúdo renderizado dentro do botão gatilho        |
| `children`     | `ReactNode`               | —       | Conteúdo recolhível, oculto enquanto fechado        |

!!! info "A11y"
    O gatilho é um `<button aria-expanded aria-controls>` ligado a uma `role="region"` de mesmo id; a região fica `hidden` enquanto fechada.

## `ContextMenu`

Menu de clique direito. Abre na posição do cursor via `onContextMenu` (menu nativo suprimido), renderizado por um `Portal`. Fecha no clique fora, Escape ou seleção.

```tsx
import { ContextMenu } from "tempest-react-sdk";

<ContextMenu
  items={[
    { label: "Editar", onSelect: () => edit() },
    { label: "Duplicar", onSelect: () => duplicate() },
    { separator: true },
    { label: "Excluir", danger: true, onSelect: () => remove() },
  ]}
>
  <div>Clique direito aqui</div>
</ContextMenu>;
```

| Prop        | Tipo                | Default | Descrição                                              |
| ----------- | ------------------- | ------- | ------------------------------------------------------ |
| `items`     | `ContextMenuItem[]` | —       | Entradas do menu — itens selecionáveis e separadores   |
| `children`  | `ReactNode`         | —       | Área de gatilho; clique direito em qualquer parte abre |
| `className` | `string`            | —       | Classes extras repassadas ao elemento do menu          |

`ContextMenuItem` = `{ label: ReactNode; onSelect?: () => void; disabled?: boolean; danger?: boolean }` ou `{ separator: true }`.

!!! tip "Teclado"
    Setas ↑/↓ movem o foco entre itens selecionáveis; Enter ativa o item focado.

## `HoverCard`

Pré-visualização de conteúdo exibida ao passar o mouse ou focar o gatilho. Abre após `openDelay`, fecha após `closeDelay`.

```tsx
import { HoverCard } from "tempest-react-sdk";

<HoverCard trigger={<a href="/u/maria">@maria</a>} placement="bottom">
  <div>
    <strong>Maria Silva</strong>
    <p>Engenheira de software · 2.3k seguidores</p>
  </div>
</HoverCard>;
```

| Prop         | Tipo                                     | Default    | Descrição                                       |
| ------------ | ---------------------------------------- | ---------- | ----------------------------------------------- |
| `trigger`    | `ReactNode`                              | —          | Elemento que o usuário foca/aponta para revelar |
| `children`   | `ReactNode`                              | —          | Conteúdo do card                                |
| `openDelay`  | `number` (ms)                            | `300`      | Atraso antes de abrir em `mouseenter`/`focus`   |
| `closeDelay` | `number` (ms)                            | `150`      | Atraso antes de fechar em `mouseleave`/`blur`   |
| `placement`  | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Ancoragem do card relativa ao gatilho           |

!!! info "A11y"
    O card é uma `role="dialog"` rotulada; o gatilho permanece focável por teclado.

## `Command` (paleta ⌘K)

Paleta de comandos estilo ⌘K: diálogo em overlay com input que filtra itens por substring (label + keywords), agrupa resultados e suporta navegação por teclado (↑/↓, Enter, Escape). Prende o foco enquanto aberto.

```tsx
import { Command } from "tempest-react-sdk";
import { useState } from "react";

const [open, setOpen] = useState(false);

<Command
  open={open}
  onOpenChange={setOpen}
  placeholder="Digite um comando…"
  items={[
    { id: "new", label: "Novo documento", group: "Arquivo", onSelect: () => create() },
    {
      id: "open",
      label: "Abrir…",
      group: "Arquivo",
      keywords: ["recente"],
      onSelect: () => openFile(),
    },
    { id: "theme", label: "Alternar tema", group: "Preferências", onSelect: () => toggleTheme() },
  ]}
/>;
```

| Prop           | Tipo                      | Default             | Descrição                                            |
| -------------- | ------------------------- | ------------------- | ---------------------------------------------------- |
| `open`         | `boolean`                 | —                   | Se a paleta está visível                             |
| `onOpenChange` | `(open: boolean) => void` | —                   | Próximo estado (Escape, seleção, clique no backdrop) |
| `items`        | `CommandItem[]`           | —                   | Candidatos a filtrar e exibir                        |
| `placeholder`  | `string`                  | `"Type a command…"` | Placeholder do input de busca                        |
| `emptyMessage` | `ReactNode`               | `"No results"`      | Exibido quando nada combina com a busca              |
| `className`    | `string`                  | —                   | Repassado ao elemento de diálogo                     |

`CommandItem` = `{ id: string; label: string; group?: string; keywords?: string[]; onSelect: () => void; icon?: ReactNode }`.

!!! tip "Gatilho global"
    Combine com `useKeyboardShortcut("mod+k", () => setOpen(true))` para abrir via ⌘K / Ctrl+K.

## Recap

- **Essenciais**: `Toggle`/`ToggleGroup` para estados pressionáveis, `Label` para formulários, `Collapsible` para um bloco expansível, `ContextMenu`/`HoverCard` para overlays disparados por interação e `Command` para a paleta ⌘K.
- Todos seguem os mesmos padrões controlado/não-controlado, expõem A11y por teclado e importam de `tempest-react-sdk`.

---

# components/advanced-layout.md

# Avançados: layout & UX

Rolagem estilizada, painéis redimensionáveis, calendário e agenda. Dão forma ao espaço em volta do conteúdo, sem dependência externa.

## `ScrollArea`

Contêiner de rolagem estilizado que transborda no eixo escolhido e renderiza uma barra de rolagem fina (WebKit). Repassa `className`, `style` e `ref` ao `<div>`.

```tsx
import { ScrollArea } from "tempest-react-sdk";

<ScrollArea maxHeight={240} orientation="vertical">
  <ul>
    {items.map((item) => (
      <li key={item.id}>{item.name}</li>
    ))}
  </ul>
</ScrollArea>;
```

| Prop          | Tipo                                   | Default      | Descrição                             |
| ------------- | -------------------------------------- | ------------ | ------------------------------------- |
| `maxHeight`   | `number \| string`                     | —            | Limita a altura; números viram pixels |
| `orientation` | `"vertical" \| "horizontal" \| "both"` | `"vertical"`   | Qual eixo rola                        |
| `scrollLabel` | `string`                               | `"Área rolável"` | Nome acessível da região rolável    |

Demais props de `<div>` são repassadas.

!!! info "Enquanto transborda, vira um grupo focável"
    Uma área cujo conteúdo é texto puro não tem nada focável dentro. Sem um ponto de tabulação próprio, quem navega por teclado vê a barra de rolagem e não tem como movê-la — o foco nunca pousa onde as setas rolariam. Por isso a área recebe `tabIndex={0}` + `role="group"` + `aria-label` **só enquanto o conteúdo de fato transborda**, e o perde de volta quando cabe. Uma área que não rola nunca adiciona parada de tab. `role` e `tabIndex` passados pelo chamador continuam vencendo.

## `Resizable`

Layout de dois painéis com divisor arrastável. O primeiro painel é dimensionado via `flex-basis` em porcentagem; o segundo preenche o resto. Arraste com o ponteiro ou foque o divisor e use as setas (passo de 2%).

```tsx
import { Resizable } from "tempest-react-sdk";

<Resizable direction="horizontal" defaultSize={40} min={20} max={80}>
  <aside>Painel lateral</aside>
  <main>Conteúdo principal</main>
</Resizable>;
```

| Prop          | Tipo                         | Default        | Descrição                                          |
| ------------- | ---------------------------- | -------------- | -------------------------------------------------- |
| `direction`   | `"horizontal" \| "vertical"` | `"horizontal"` | `horizontal` coloca os painéis lado a lado         |
| `defaultSize` | `number` (%)                 | `50`           | Tamanho inicial do primeiro painel, em porcentagem |
| `min`         | `number` (%)                 | `10`           | Clamp inferior do primeiro painel                  |
| `max`         | `number` (%)                 | `90`           | Clamp superior do primeiro painel                  |
| `children`    | `[ReactNode, ReactNode]`     | —              | Exatamente dois painéis — `[paneA, paneB]`         |

!!! warning "Exatamente dois filhos"
    `children` é uma tupla `[ReactNode, ReactNode]`. O tamanho é sempre fixado em `[min, max]`.

## `Calendar`

Seletor de data em grade mensal. Cabeçalho com mês/ano + botões prev/next, linha de dias da semana e grade 6×7 de botões de dia. Seleção e mês visível controláveis ou não-controlados. Aritmética com `Date` puro — sem bibliotecas externas.

```tsx
import { Calendar } from "tempest-react-sdk";
import { useState } from "react";

const [date, setDate] = useState<Date>();

<Calendar value={date} onChange={setDate} weekStartsOn={1} minDate={new Date(2026, 0, 1)} />;
```

| Prop            | Tipo                    | Default | Descrição                                         |
| --------------- | ----------------------- | ------- | ------------------------------------------------- |
| `value`         | `Date`                  | —       | Data selecionada controlada                       |
| `defaultValue`  | `Date`                  | —       | Data inicial no caso não-controlado               |
| `onChange`      | `(date: Date) => void`  | —       | Chamado com a nova data selecionada               |
| `month`         | `Date`                  | —       | Mês visível controlado (qualquer dia dentro dele) |
| `onMonthChange` | `(month: Date) => void` | —       | Chamado quando o mês visível muda (prev/next)     |
| `minDate`       | `Date`                  | —       | Data mínima selecionável (inclusiva)              |
| `maxDate`       | `Date`                  | —       | Data máxima selecionável (inclusiva)              |
| `weekStartsOn`  | `0 \| 1`                | `0`     | Primeira coluna — `0` domingo, `1` segunda        |

!!! tip "Teclado"
    Setas movem o foco por dia (←/→) ou por semana (↑/↓); Enter/Espaço seleciona o dia focado.

## `Scheduler`

Agenda: eventos posicionados numa grade de tempo ao longo de dias consecutivos. O `Calendar` acima é um **seletor de data** — responde "qual dia?". Este responde "o que tem nesses dias, e quando", o que exige estrutura diferente: eixo vertical de tempo, evento dimensionado pela duração e eventos sobrepostos lado a lado.

```tsx
import { Scheduler, type SchedulerEvent } from "tempest-react-sdk";

const events: SchedulerEvent[] = [
  { id: "1", title: "Daily", start: new Date(2026, 6, 27, 9, 0), end: new Date(2026, 6, 27, 9, 15) },
  { id: "2", title: "Cliente", start: new Date(2026, 6, 27, 9, 0), end: new Date(2026, 6, 27, 10, 30) },
  { id: "3", title: "Feriado", start: new Date(2026, 6, 29), end: new Date(2026, 6, 30), allDay: true },
];

<Scheduler
  events={events}
  days={7}
  startHour={7}
  endHour={21}
  onEventClick={(event) => abrir(event.id)}
  onSlotClick={(start) => criarEm(start)}
/>;
```

| Prop              | Tipo                                    | Default   | Descrição                                              |
| ----------------- | --------------------------------------- | --------- | ------------------------------------------------------ |
| `events`          | `SchedulerEvent[]`                      | —         | Eventos; instantes lidos no fuso local                 |
| `anchor`          | `Date`                                  | hoje      | Qualquer dia dentro do intervalo a mostrar             |
| `days`            | `number`                                | `7`       | Dias consecutivos — `1` é visão de dia                 |
| `startHour`       | `number`                                | `8`       | Primeira hora visível                                  |
| `endHour`         | `number`                                | `20`      | Última hora visível                                    |
| `snapMinutes`     | `number`                                | `30`      | Granularidade do clique em espaço vazio                |
| `onEventClick`    | `(event: SchedulerEvent) => void`       | —         | Evento ativado                                         |
| `onSlotClick`     | `(start: Date) => void`                 | —         | Clique em espaço vazio, já snapado                     |
| `renderEvent`     | `(event: SchedulerEvent) => ReactNode`  | —         | Conteúdo do evento                                     |
| `locale`          | `string`                                | `"pt-BR"` | Rótulos de dia e hora                                  |
| `showCurrentTime` | `boolean`                               | `true`    | Linha de agora                                         |
| `now`             | `Date`                                  | relógio   | "Agora" fixo — use em teste e demo pra determinismo     |

Evento: `{ id, title, start, end, allDay?, data? }`.

!!! info "Sobreposição é o que quase toda implementação erra"
    Eventos sobrepostos são agrupados em **clusters de sobreposição mútua** — uma
    cadeia onde cada evento sobrepõe ao menos um outro — e **todos no cluster
    compartilham a mesma contagem de colunas**. É isso que faz as larguras baterem;
    atribuir coluna par a par produz o layout esfarrapado onde dois eventos ocupam
    metade cada e um terceiro cobre um deles silenciosamente.

    A coluna é **reaproveitada assim que libera**: `9–10`, `9–10`, `10–11` usa duas
    colunas, não três. E encostar não é sobrepor — `9–10` seguido de `10–11` ficam os
    dois com largura cheia.

    O layout é puro e mora em `scheduler-layout.ts`, com teste próprio.

!!! warning "Horário local, e DST não duplica dia"
    `start`/`end` são instantes lidos no fuso do navegador. O intervalo de dias é
    montado **incrementando o dia do calendário**, não somando 24 h em milissegundos:
    num limite de horário de verão o dia tem 23 ou 25 horas, e a aritmética de
    milissegundo produziria data duplicada ou pulada.

!!! check "Evento cruzando meia-noite aparece nas duas colunas"
    Uma reserva 23:00–01:00 é dividida em dois segmentos, cada um clipado à janela
    visível do seu dia. Sem isso ela ou desaparece ou é desenhada fora da coluna.

!!! note "Dia inteiro tem faixa própria"
    Evento com `allDay` sai numa faixa acima da grade, atravessando os dias que
    cobre — posição vertical não significaria nada pra ele. A faixa não é renderizada
    quando não há nenhum.

!!! tip "Clique em espaço vazio cria; clique no evento não"
    O `onSlotClick` só dispara quando o clique caiu na coluna, não num evento dentro
    dela — o instante vem snapado em `snapMinutes` e clampado à janela.

!!! warning "Não é `role="grid"`"
    Uma grade ARIA exige filhos `row`, e aqui os eventos são **irmãos** das colunas
    dentro de um único CSS grid: um wrapper `row` faria as colunas deixarem de ser
    itens do grid e o layout colapsaria. Cada dia é um `group` rotulado — o leitor de
    tela tabula os botões de evento e o nome do grupo dá o dia. Verificado com `axe`.

## Recap

- **Layout & UX**: `ScrollArea` para rolagem estilizada, `Resizable` para painéis divididos e `Calendar` para seleção de datas sem dependências externas.
- Todos seguem os mesmos padrões controlado/não-controlado, expõem A11y por teclado e importam de `tempest-react-sdk`.

---

# components/advanced-navigation.md

# Avançados: navegação & conteúdo

Navegação com dropdowns, barra de menus e carrossel. Três formas de levar a pessoa a outro lugar, ou de mostrar mais do que cabe na tela.

## `NavigationMenu`

Menu de navegação horizontal com submenus dropdown via hover/clique/foco. Itens de topo em `<nav><ul>`; itens com `children` abrem um painel `role="menu"`. Apenas um painel aberto por vez.

```tsx
import { NavigationMenu } from "tempest-react-sdk";

<NavigationMenu
  items={[
    { label: "Início", href: "/" },
    {
      label: "Produtos",
      children: [
        { label: "Analytics", href: "/analytics" },
        { label: "Billing", onSelect: () => openBilling() },
      ],
    },
  ]}
/>;
```

| Prop    | Tipo                   | Default | Descrição                     |
| ------- | ---------------------- | ------- | ----------------------------- |
| `items` | `NavigationMenuItem[]` | —       | Entradas de navegação de topo |

`NavigationMenuItem` = `{ label: ReactNode; href?: string; onSelect?: () => void; children?: NavigationMenuItem[] }`.

!!! note "Fechamento"
    Fecha no clique fora, Escape, ou ao selecionar uma entrada-folha.

## `Menubar`

Barra de menus de aplicação (estilo Arquivo / Editar). `role="menubar"`; cada menu é um botão que abre um dropdown. Setas ←/→ navegam entre menus (com wrap).

```tsx
import { Menubar } from "tempest-react-sdk";

<Menubar
  menus={[
    {
      label: "Arquivo",
      items: [
        { label: "Novo", shortcut: "⌘N", onSelect: () => create() },
        { separator: true },
        { label: "Sair", onSelect: () => quit() },
      ],
    },
  ]}
/>;
```

| Prop    | Tipo            | Default | Descrição                                         |
| ------- | --------------- | ------- | ------------------------------------------------- |
| `menus` | `MenubarMenu[]` | —       | Menus de topo, renderizados da esquerda à direita |

`MenubarMenu` = `{ label: ReactNode; items: MenubarItem[] }`. `MenubarItem` = `{ label: ReactNode; onSelect?: () => void; disabled?: boolean; shortcut?: string }` ou `{ separator: true }`.

## `Carousel`

Slider horizontal de conteúdo mostrando um slide por vez. A track translada pelo índice ativo. Setas prev/next (desabilitadas nas pontas, salvo `loop`) e indicadores em dots. Controlado (`index`) ou não-controlado (`defaultIndex`).

```tsx
import { Carousel } from "tempest-react-sdk";

<Carousel loop showArrows showDots>
  <img src="/1.jpg" alt="" />
  <img src="/2.jpg" alt="" />
  <img src="/3.jpg" alt="" />
</Carousel>;
```

| Prop            | Tipo                      | Default | Descrição                             |
| --------------- | ------------------------- | ------- | ------------------------------------- |
| `children`      | `ReactNode[]`             | —       | Slides — um renderizado por vez       |
| `loop`          | `boolean`                 | `false` | Dá a volta nas pontas em vez de parar |
| `showArrows`    | `boolean`                 | `true`  | Exibe botões de seta prev/next        |
| `showDots`      | `boolean`                 | `true`  | Exibe indicadores em dots             |
| `index`         | `number`                  | —       | Índice ativo controlado               |
| `defaultIndex`  | `number`                  | `0`     | Índice inicial não-controlado         |
| `onIndexChange` | `(index: number) => void` | —       | Chamado quando o índice ativo muda    |

!!! tip "Teclado"
    Setas ←/→ sobre a região focada navegam entre slides.

## Recap

- **Navegação & conteúdo**: `NavigationMenu` e `Menubar` para navegação com dropdowns, `Carousel` para sliders.
- Todos seguem os mesmos padrões controlado/não-controlado, expõem A11y por teclado e importam de `tempest-react-sdk`.

---

# components/advanced.md

# Overlays & avançados

Componentes em paridade com a shadcn/ui, agrupados por para o que servem. Cada página é autocontida: propósito, exemplo executável, tabela de props e recap. Todos importados de `tempest-react-sdk`.

- **[Avançados: essenciais](advanced-essentials.md)** — Toggles, label, regiões expansíveis, menus disparados por interação e a paleta de comandos. A fatia que quase toda tela usa em algum momento.
- **[Avançados: layout & UX](advanced-layout.md)** — Rolagem estilizada, painéis redimensionáveis, calendário e agenda. Dão forma ao espaço em volta do conteúdo, sem dependência externa.
- **[Avançados: navegação & conteúdo](advanced-navigation.md)** — Navegação com dropdowns, barra de menus e carrossel. Três formas de levar a pessoa a outro lugar, ou de mostrar mais do que cabe na tela.
- **[Avançados: dados](advanced-data.md)** — Tabela stateful, assistente em passos, markdown, mural, tour guiado, transferência entre listas, barra de filtros e kanban. Cada um resolve uma tela inteira.
- **[Avançados: conversa](advanced-chat.md)** — `Chat` para thread entre pessoas e `AIChat` para conversa com um modelo. São componentes diferentes, não variantes — e é por isso que têm página própria.

!!! info "Por que cinco páginas"
    Isto era um arquivo de 1376 linhas. Quem chegava pelo `FilterBar` rolava 450 linhas de outra coisa antes. Os grupos são os que o recap da página original já nomeava — inclusive conversa, que ele descrevia como categoria própria: “`Chat` … e `AIChat` … São componentes diferentes, não variantes.”

---

# components/data.md

# Dados

Componentes de **dados** apresentam coleções — várias entidades do mesmo tipo — de forma legível e navegável. A escolha depende de _quantos_ itens e de _como_ o usuário os percorre: comparar campos lado a lado (`Table`), rolar milhares de linhas sem travar (`VirtualList`), expandir/colapsar seções de conteúdo (`Accordion`) ou seguir uma sequência de eventos no tempo (`Timeline`).

Use esta página quando precisa **listar/comparar** registros. Para um único registro use um [`Card`](./identity.md); para entrada de dados, [inputs](./inputs.md).

## `Table<T>`

> **Quando usar**: comparar registros estruturados campo a campo em colunas — pedidos, usuários, transações. Tipada por `T`, com prioridade responsiva por coluna e stack opcional em mobile.

```tsx
const columns: TableColumn<Order>[] = [
  { key: "id", header: "ID", align: "right", priority: "always" },
  { key: "customer", header: "Cliente", priority: "always" },
  {
    key: "total",
    header: "Total",
    align: "right",
    render: (row) => formatCurrency(row.total),
    priority: "always",
  },
  {
    key: "created_at",
    header: "Data",
    render: (row) => formatDate(row.created_at),
    priority: "tablet",
  },
  {
    key: "status",
    header: "Status",
    render: (row) => <Badge variant={statusVariant(row.status)}>{row.status}</Badge>,
    priority: "desktop",
  },
  {
    key: "actions",
    header: "",
    render: (row) => (
      <Button size="sm" onClick={() => edit(row.id)}>
        Editar
      </Button>
    ),
    priority: "desktop",
  },
];

<Table
  columns={columns}
  data={orders}
  rowKey={(row) => row.id}
  onRowClick={(row) => navigate(`/orders/${row.id}`)}
  stackOnMobile
  emptyMessage="Nenhum pedido encontrado."
/>;
```

| Prop            | Tipo                                           | Default                         |
| --------------- | ---------------------------------------------- | ------------------------------- |
| `columns`       | `TableColumn<T>[]`                             | —                               |
| `data`          | `T[]`                                          | —                               |
| `rowKey`        | `(row: T, index: number) => string \| number`  | —                               |
| `onRowClick`    | `(row: T) => void`                             | —                               |
| `emptyMessage`  | `ReactNode` (exibido quando `data` está vazio) | `"Nenhum registro encontrado."` |
| `stackOnMobile` | `boolean` (rows viram cards label/value < md)  | `false`                         |

`TableColumn<T>`:

| Campo       | Tipo                                          | Notas                                                      |
| ----------- | --------------------------------------------- | ---------------------------------------------------------- |
| `key`       | `string`                                      | Identificador + key padrão (lê `row[key]`)                 |
| `header`    | `ReactNode`                                   | Cabeçalho da coluna; vira `data-label` no modo stack       |
| `render`    | `(row: T, index: number) => ReactNode`        | Default = `row[key]`                                       |
| `align`     | `"left" \| "right" \| "center"`               | Default `"left"`                                           |
| `priority`  | `"always" \| "tablet" \| "desktop"`           | `tablet`: escondida em < md. `desktop`: escondida em < lg. |
| `width`     | `string \| number`                            | CSS width (`120px`, `20%`, `auto`)                         |
| `className` | `string`                                      | Classe extra aplicada às células daquela coluna            |

!!! warning "Não existe prop `loading`"
    A `Table` não renderiza skeleton rows por conta própria. Para um estado de carregamento, renderize seu próprio skeleton condicionalmente _antes_ da tabela, ou passe linhas placeholder em `data`. O `emptyMessage` cobre apenas o caso "consulta válida, zero resultados".

**Responsive**:

- `priority="tablet"` → colunas escondidas em viewport `< md` (768px).
- `priority="desktop"` → escondidas em `< lg` (1024px).
- `stackOnMobile` → no `< sm` (640px), cada row vira um card label/value.

## `VirtualList`

> **Quando usar**: rolar listas muito longas (500+ itens) de linhas com **altura fixa** sem inundar o DOM — chats, logs, feeds infinitos.

Renderiza apenas a janela visível + um pequeno buffer de overscan. Cada linha precisa de altura fixa (`itemHeight`); o container precisa de uma altura (`height`).

```tsx
<VirtualList
  items={messages}
  itemHeight={64}
  height={480}
  overscan={5}
  getKey={(message) => message.id}
  renderItem={(message) => <MessageRow message={message} />}
/>
```

| Prop         | Tipo                                           | Default |
| ------------ | ---------------------------------------------- | ------- |
| `items`      | `T[]`                                          | —       |
| `itemHeight` | `number` (altura fixa de cada linha, px)       | —       |
| `height`     | `number \| string` (altura do container)       | —       |
| `renderItem` | `(item: T, index: number) => ReactNode`        | —       |
| `overscan`   | `number` (itens acima/abaixo da viewport)      | `4`     |
| `getKey`     | `(item: T, index: number) => string \| number` | `index` |

!!! warning "Altura fixa obrigatória"
    O `VirtualList` assume `itemHeight` constante para calcular a janela. Para linhas de altura variável use `@tanstack/react-virtual` ou `react-window` — resolvem o caso geral ao custo de mais setup.

!!! note "Busca nativa (Ctrl+F) só acha o visível"
    Itens fora da viewport não estão no DOM, então o `Ctrl+F` do navegador não os encontra. Abaixo de ~500 itens, prefira renderização normal: o ganho de perf é negligível e você mantém a busca nativa.

## `VirtualTable<T>`

> **Quando usar**: uma tabela de **milhares de linhas** numa única grade rolável — extrato, log de auditoria, exportação bruta. O `Table` renderiza tudo o que recebe e o `DataTable` pagina pra manter esse número pequeno; nenhum dos dois responde "me mostre as 40 000 linhas de uma vez".

Renderiza só a janela visível, como o `VirtualList`, mas continua sendo uma `<table>` de verdade: colunas alinhadas pelo browser, cabeçalho fixo, semântica de grade pra leitor de tela.

```tsx
<VirtualTable
  data={rows}
  columns={[
    { key: "id", header: "#", width: 80, sortable: true },
    { key: "name", header: "Nome", width: 240, sortable: true },
    { key: "total", header: "Total", width: 120, align: "right", sortable: true },
  ]}
  rowHeight={40}
  height={480}
  rowKey={(row) => row.id}
  onRowClick={(row) => open(row.id)}
/>
```

| Prop            | Tipo                                            | Default                            |
| --------------- | ----------------------------------------------- | ---------------------------------- |
| `data`          | `T[]`                                           | —                                  |
| `columns`       | `VirtualTableColumn<T>[]`                       | —                                  |
| `rowHeight`     | `number` (px, **uniforme**)                     | —                                  |
| `height`        | `number \| string` (altura do viewport)         | —                                  |
| `overscan`      | `number`                                        | `4`                                |
| `rowKey`        | `(row: T, index: number) => string \| number`   | `index`                            |
| `initialSort`   | `{ key: keyof T; direction: "asc" \| "desc" }`  | —                                  |
| `onRowClick`    | `(row: T, index: number) => void`               | —                                  |
| `scrollToIndex` | `number`                                        | —                                  |
| `caption`       | `ReactNode` (nome acessível, oculto visualmente) | —                                  |
| `emptyMessage`  | `ReactNode`                                     | `"Nenhum registro encontrado."`    |

Coluna: `{ key, header, render?, sortable?, align?, width? }`.

!!! info "Por que continua uma `<table>`"
    A janela é feita com **duas linhas espaçadoras** — uma acima da fatia visível, outra abaixo — em vez de posicionar linhas com `position: absolute`. Absoluto colapsaria o layout de tabela: cada largura de coluna teria que ser calculada à mão, e o elemento deixaria de ser uma tabela pra tecnologia assistiva. Com espaçadoras, o browser continua fazendo o layout das colunas e o leitor de tela continua anunciando uma grade.

!!! tip "Índice real, não o da janela"
    Como só uma fatia está no DOM, `aria-rowcount` na tabela e `aria-rowindex` em cada linha carregam os números **reais**. Sem isso o leitor de tela anuncia "linha 3 de 20" enquanto o usuário está na linha 5003 de 40 000 — é o detalhe que quase toda tabela virtualizada erra.

!!! warning "`rowHeight` uniforme, e igual ao que o CSS produz"
    É o que mapeia offset de rolagem pra índice de linha. Se o CSS renderizar uma altura diferente da declarada, a janela sai deslocada. Para altura variável use `@tanstack/react-virtual`.

!!! note "Defina `width` em toda coluna"
    Linhas entram e saem do DOM durante a rolagem, então deixar o browser dimensionar as colunas pelo que está renderizado agora faz elas pularem no meio do scroll. O componente usa `table-layout: fixed` justamente pra isso funcionar.

### `VirtualTable` ou `DataTable`?

| Precisa de…                                     | Use            |
| ----------------------------------------------- | -------------- |
| Busca + paginação, dezenas a centenas de linhas | `DataTable`    |
| Uma grade rolável de milhares de linhas         | `VirtualTable` |
| Controle total do markup, poucas linhas         | `Table`        |

Os dois ordenam com o mesmo comparador (`compareValues`), então "ordenado" quer dizer a mesma coisa nos dois — número numericamente, data por timestamp, string com `localeCompare` e `numeric: true`.

## `DataTable<T>` — edição inline

> **Quando usar**: tela de admin. Você já lista os registros com `DataTable`; agora
> alguém precisa corrigir um nome sem abrir um modal por linha.

Marque a coluna com `editable` e dê um `onCellChange` à tabela. Sem as duas coisas
nada muda — a edição é estritamente opt-in, e um `DataTable` sem coluna editável
renderiza exatamente o que renderizava antes.

```tsx
import { DataTable, type DataTableColumn } from "tempest-react-sdk";
import { api } from "@/lib/api";

interface Colaborador {
  id: number;
  nome: string;
  email: string;
  salario: number;
}

const columns: DataTableColumn<Colaborador>[] = [
  {
    key: "nome",
    header: "Nome",
    editable: true,
    validate: (value) => (String(value).trim().length < 3 ? "Mínimo de 3 letras." : null),
  },
  {
    key: "salario",
    header: "Salário",
    align: "right",
    editable: true,
    editorType: "number",
    validate: (value) => (Number(value) <= 0 ? "Precisa ser positivo." : null),
  },
  { key: "email", header: "E-mail" },
];

export function Equipe({ pessoas }: { pessoas: Colaborador[] }) {
  return (
    <DataTable
      data={pessoas}
      columns={columns}
      rowKey={(row) => row.id}
      onCellChange={({ row, key, value }) =>
        api.patch(`/api/colaboradores/${row.id}`, { body: { [key]: value } })
      }
    />
  );
}
```

Pedaço por pedaço:

- **`editable: true`** transforma a célula num botão com o valor dentro. Clicar (ou
  `Enter`) abre um `<input>`.
- **`editorType`** é o `type` do input (`"text"` por padrão; `"number"`, `"date"`,
  `"email"`, `"tel"`, `"url"`).
- **`validate`** devolve mensagem pra recusar, ou `null` pra aceitar.
- **`onCellChange`** persiste. Devolver uma promessa é o que liga o comportamento
  otimista.

### Teclado

| Tecla | O que faz |
| --- | --- |
| `Enter` | Confirma e fecha; o foco volta pro botão da célula |
| `Escape` | Descarta o rascunho e fecha |
| `Tab` | Confirma e abre a **próxima** célula editável (linha a linha) |
| `Shift+Tab` | Confirma e abre a anterior |
| clique fora | Confirma — perder o que foi digitado é o bug que os usuários reportam como "a tabela comeu minha edição" |

`Tab` é interceptado de propósito: a ordem natural levaria pro botão da linha
seguinte, e numa tabela em edição andar de célula em célula é o que se espera.

### Otimista, com rollback **visível**

Uma edição aceita aparece na hora e o `onCellChange` roda em segundo plano
(`aria-busy` no botão enquanto isso). Se a promessa rejeitar, a célula volta ao valor
antigo **e** mostra o motivo num `role="alert"` amarrado a ela por `aria-describedby`.

```tsx
onCellChange={async ({ row, key, value }) => {
  const res = await fetch(`/api/colaboradores/${row.id}`, { /* … */ });
  if (!res.ok) throw new Error("Este e-mail já está em uso.");
}}
```

A mensagem do `Error` que você lançar é a que aparece na célula. Sem mensagem, entra o
texto padrão (`editLabels.saveFailed`).

!!! danger "Reverter em silêncio é pior do que não ser otimista"
    A pessoa viu a edição aparecer e não tem motivo nenhum pra desconfiar. Se o
    servidor recusou e a célula só voltar ao valor antigo sem dizer nada, ela vai
    embora achando que salvou. É por isso que o erro fica na célula em vez de virar um
    toast que desaparece.

### Acessibilidade

- Fechada, a célula é um `<button>` cujo nome sai do **próprio conteúdo**: um
  `Editar {coluna}:` invisível na frente do que a coluna renderizou. Um `aria-label`
  montado com o valor cru leria "850000" numa célula que mostra `R$ 8.500,00` — isso
  reprova o WCAG 2.5.3 (Label in Name) e deixa controle por voz sem como chamar a
  célula pelo que ela diz. Um `<td>` com `onClick` seria invisível pro teclado e sem
  papel pro leitor de tela.
- Aberta, o `<input>` tem `aria-label` `{coluna}, linha {n}`.
- Erro de validação marca `aria-invalid` e liga a mensagem por `aria-describedby`.
- Um save bem-sucedido é anunciado por [`useAnnounce`](../hooks.md#falar-com-o-leitor-de-tela-useannounce)
  (`"{coluna} salvo"`), porque é o único evento aqui que não tem representação na tela.
  A falha **não** é anunciada duas vezes: o `role="alert"` da célula já faz isso.
- Em ponteiro grosso (toque), a área de toque do botão cresce até cobrir o `<td>`
  inteiro — 44px sem invadir a linha vizinha, que um hit-slop simétrico invadiria.

### Props de edição

| Prop | Tipo | Onde |
| --- | --- | --- |
| `editable` | `boolean` | coluna |
| `editorType` | `"text" \| "number" \| "date" \| "email" \| "tel" \| "url"` | coluna |
| `formatEdit` | `(row: T) => string` | coluna — texto com que o editor abre |
| `parse` | `(raw: string, row: T) => unknown` | coluna — string → valor guardado |
| `validate` | `(value: unknown, row: T) => string \| null` | coluna |
| `onCellChange` | `(change: DataTableCellChange<T>) => void \| Promise<void>` | tabela |
| `editLabels` | `Partial<DataTableEditLabels>` | tabela — a cópia PT-BR |

`DataTableCellChange<T>` traz `{ row, key, value, previous, rowIndex }`, com `rowIndex`
no **dataset completo**, não na página.

!!! tip "Coluna com `render` continua funcionando"
    Uma coluna que renderiza `<Money cents={row.salario} />` recebe a linha com o valor
    otimista já aplicado, então o número novo aparece formatado do jeito certo enquanto
    o save está em voo.

## `DataTable<T>` — paginação no servidor

> **Quando usar**: a listagem normal de admin. O backend pagina, filtra e ordena; o
> navegador recebe uma página por vez e não tem como responder sozinho "quantas
> linhas existem" nem "qual é a primeira em ordem alfabética".

Por padrão o `DataTable` recebe o **dataset inteiro** e faz tudo em memória. Passe
`totalItems` e ele troca de modo: `data` passa a ser a página atual, a contagem de
páginas vem desse número, e ordenação e busca são delegadas a você.

```tsx
import { useState } from "react";
import {
  DataTable,
  usePaginatedQuery,
  type DataTableColumn,
  type DataTableSort,
} from "tempest-react-sdk";

type Pessoa = { id: number; nome: string; cargo: string };

const COLUNAS: DataTableColumn<Pessoa>[] = [
  { key: "nome", header: "Nome", sortable: true },
  { key: "cargo", header: "Cargo", sortable: true },
];

export function Pessoas() {
  const [sort, setSort] = useState<DataTableSort<Pessoa> | null>(null);
  const [termo, setTermo] = useState("");

  const { items, total, pageNumber, setPage, isFetching } = usePaginatedQuery<Pessoa>({
    queryKey: ["pessoas", sort, termo],
    queryFn: ({ page, size }) =>
      fetch(`/api/pessoas?page=${page}&size=${size}&q=${termo}`).then((r) => r.json()),
    pageSize: 20,
  });

  return (
    <DataTable
      data={items}
      columns={COLUNAS}
      rowKey={(row) => row.id}
      pageSize={20}
      totalItems={total}
      page={pageNumber}
      onPageChange={setPage}
      onSortChange={(next) => {
        setSort(next);
        setPage(1);
      }}
      searchable
      onSearchChange={(next) => {
        setTermo(next);
        setPage(1);
      }}
      loading={isFetching}
    />
  );
}
```

!!! check "`usePaginatedQuery` já é a outra metade"
    Ele mantém a página, devolve `items`, `total`, `pageNumber` e `setPage` — exatamente as quatro props que o modo servidor pede. Não precisa de `useState` para a página; o `useState` que sobra é o da ordenação e o do termo, porque eles fazem parte da **query key**.

| Prop | Tipo | O que faz |
| --- | --- | --- |
| `totalItems` | `number` | Liga o modo servidor e manda na contagem de páginas. |
| `page` | `number` | Página controlada, 1-based. |
| `onPageChange` | `(page: number) => void` | Próxima página pedida pelo paginador. |
| `manualSort` | `boolean` | Delega a ordenação. Implícito com `totalItems`. |
| `onSortChange` | `(sort: DataTableSort<T> \| null) => void` | `asc` → `desc` → `null`. |
| `manualSearch` | `boolean` | Delega a busca. Implícito com `totalItems`. |
| `onSearchChange` | `(term: string) => void` | Termo digitado; debounce é seu. |
| `loading` | `boolean` | Requisição em voo. |

!!! check "O compilador agora recusa a combinação inválida"
    As props são uma **união** das formas que funcionam, então três erros que antes
    compilavam viraram erro de build no seu call site:

    | Você escreveu | Por que não compila |
    | --- | --- |
    | `totalItems` sem `page`/`onPageChange` | O paginador andaria a página interna enquanto `data` segue mostrando a página 1 |
    | `page` sem `onPageChange` | Página controlada sem ninguém para trocá-la |
    | `manualSort` sem `onSortChange` | A seta do header gira e mais nada acontece |
    | `manualSearch` sem `onSearchChange` | A caixa de busca não filtra nada e não avisa ninguém |

    Até a v0.44.0 cada prop era opcional por conta própria, então isso só aparecia
    como `console.warn` em dev, no browser, com o componente montado — o `tsc` do
    seu CI nunca via. Os avisos de runtime continuam, para os callers que o tipo não
    alcança (JavaScript puro, ou props chegando por spread tipado `any`).

    Os tipos das metades são exportados quando você precisa deles:
    `DataTableBaseProps`, `DataTablePagingProps`, `DataTableSortProps` e
    `DataTableSearchProps`. `Partial` de união não funciona — para variar só a
    metade compartilhada num helper de teste, use `Partial<DataTableBaseProps<T>>`.

!!! warning "Um caso o tipo **não** pega: busca implícita no modo servidor"
    `totalItems` já **implica** `manualSearch`. Então `searchable` sem
    `onSearchChange` numa tabela em modo servidor é a mesma caixa inerte — sem que
    ninguém escreva `manualSearch`, e portanto sem o eixo de busca ter como ver.

    Fechar isso exigiria o eixo de busca ler o eixo de paginação, cruzando duas
    uniões de três membros em nove e transformando qualquer erro num paredão de
    formas candidatas. Esse caso continua sendo **aviso de dev em runtime** — é o
    único dos quatro em que runtime é de fato a checagem mais barata.

!!! danger "Busca e ordenação **precisam** ir junto — filtrar a página mente"
    `searchable` sozinho filtra `data` em memória, e no modo servidor `data` é só a
    página atual. O usuário digita, some tudo que não está na página 3 e a tabela
    parece dizer "não existe". Por isso `totalItems` já implica `manualSearch` e
    `manualSort`: ordenar cinco linhas alegando ter ordenado 23 é o mesmo tipo de
    mentira.

!!! tip "`manualSort` e `manualSearch` também servem sem paginação de servidor"
    Lista inteira na memória mas ordenada pelo backend (por relevância, por um
    campo calculado) é um caso legítimo: passe `manualSort` sem `totalItems`.

!!! check "Carregando e vazio são telas diferentes"
    Com linhas na tela, `loading` esmaece e marca `aria-busy` — as linhas antigas
    ficam, então a paginação não salta sob o cursor entre páginas. Sem linhas ainda,
    desenha placeholders na altura real em vez do `emptyMessage`, porque "estou
    buscando" e "não há nada" não são a mesma frase.

!!! warning "Combinação incompleta avisa em dev"
    `totalItems` sem `page` controlada, `page` sem `onPageChange`, ordenação
    delegada sem `onSortChange` — cada um renderiza uma tela que parece funcionar e
    não funciona (o cabeçalho ordena e nada se move). Nenhum é erro de tipo, então
    o aviso sai no `console` em desenvolvimento.

!!! info "O modo cliente não mudou uma linha"
    Sem `totalItems`, `manualSort`, `manualSearch` ou `loading`, o markup e o
    comportamento são exatamente os de antes — inclusive o clamp de página quando o
    dataset encolhe, que no modo servidor é desligado de propósito (a página é sua,
    e um clamp contra um `totalItems` que ainda não chegou mandaria o usuário pra
    uma página que ele não pediu, no meio do fetch).

## `BarList`

> **Quando usar**: distribuição ranqueada — usuários por plano, erros por endpoint,
> vendas por categoria. É o gráfico mais comum de painel, e o único que costuma ser
> reescrito quatro vezes no mesmo dashboard, cada vez com seu CSS e seu `.sort()`.

Rótulo, barra proporcional, valor e (opcionalmente) a fatia do total. Sem recharts —
é `div` com largura percentual, igual ao `Sparkline`.

```tsx
import { BarList } from "tempest-react-sdk";

<BarList
  items={[
    { label: "Free", value: 128 },
    { label: "Pro", value: 32 },
    { label: "Team", value: 16 },
  ]}
  valueFormatter={(n) => `${n} ativos`}
  showPercentage
  max={5}
  otherLabel="Outros"
/>;
```

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `items` | `BarListItem[]` | — | `{ label, value, color? }`. Valor não-finito é descartado. |
| `valueFormatter` | `(value: number) => string` | — | Como o número aparece. |
| `showPercentage` | `boolean` | `false` | Mostra a fatia do total ao lado do valor. |
| `sort` | `"desc" \| "asc" \| "none"` | `"desc"` | Ordenação — `"none"` respeita a ordem dada. |
| `max` | `number` | — | Mantém no máximo N linhas. |
| `otherLabel` | `string` | — | Agrega o que `max` cortou numa linha só. |

!!! info "Largura e percentual são números **diferentes**, de propósito"
    A largura é relativa à **maior** linha, então a maior barra preenche a trilha. O
    percentual é a fatia do **total**. Escalar a largura pelo total deixa toda barra
    curta numa lista de muitos valores pequenos — o gráfico para de ser legível
    exatamente quando tem mais linhas.

!!! check "É lista, não figura"
    `<ul>`/`<li>` com o valor escrito como **texto**, e a barra `aria-hidden` atrás.
    O leitor de tela lê "Free, 128, 62%" porque isso está escrito, não porque um
    `aria-label` narra um desenho.

!!! danger "O rótulo nunca fica em cima da barra"
    Texto sobre preenchimento tingido precisa ser reverificado contra aquele
    preenchimento — e a rampa `--tempest-chart-*` é de **marca** (3:1), reprovando
    como texto. O SDK já foi pego por isso duas vezes, e as duas só apareceram em
    browser real, porque o `axe` em jsdom desliga `color-contrast` sem paint. Este
    layout evita a classe inteira do problema.

!!! warning "Valor negativo não desenha barra, mas continua na lista"
    Barra de largura negativa não existe: a largura vira 0 e o percentual vira 0,
    mas o número aparece. Some da lista seria pior do que aparecer estranho. Pela
    mesma razão o total conta só os valores positivos, senão as fatias não fecham.

!!! tip "Soma zero mostra zero, não `NaN%`"
    O percentual passa por `percentOf`, então painel recém-criado exibe `0%` em vez
    do `NaN%` que `(parte / total) * 100` produziria.

!!! note "`otherLabel` só agrega quando sobra mais de uma linha"
    Colapsar uma única linha em "Outros" esconderia o nome dela à toa — nesse caso
    ela aparece com o próprio nome.

!!! tip "A paleta respeita `--tempest-chart-count`"
    A cor de cada linha vem de `useChartColors`, o mesmo resolvedor que todo chart
    do SDK usa, então um tema que declara **menos** de oito séries cicla dentro da
    própria paleta. Um tema de marca com 6 cores repete a 1ª e a 2ª nas linhas 7 e 8,
    em vez de cair no azul e no teal default do SDK.

    Até a v0.44.0 a cor era lida por `var(--tempest-chart-N)` com `N = index % 8`.
    O CSS não consegue usar `--tempest-chart-count` como módulo, então o `8` era
    fixo e a marca perdia as duas últimas linhas. `palette.ts` não importa nada,
    então isso não puxa biblioteca de gráfico pra fatia.

    `color` por item continua ganhando de tudo.

!!! tip "A aritmética é exportada: `buildBarListRows`"
    `buildBarListRows({ items, sort, max, otherLabel })` devolve as linhas já
    ordenadas, cortadas e medidas (`percentage`, `width`, `index`) sem renderizar
    nada. Serve pra quem quer o mesmo cálculo com outro desenho — uma legenda, uma
    tabela, um export. Só `items` é obrigatório; `sort` default é `"desc"`.

    ```typescript
    const rows = buildBarListRows({ items: vendas, max: 5, otherLabel: "Outros" });
    ```

## `ListTile`

> **Quando usar**: a linha canônica de lista do Material — um item com slot à esquerda (ícone/avatar), título com subtítulo opcional e slot à direita (ícone, switch, meta). Ideal para listas de configurações, contatos ou menus.

Renderiza como `<div>` estático por padrão; ao receber `onClick` vira um `<button>` de largura total, acessível por teclado.

```tsx
import { useState } from "react";
import { ListTile, Switch } from "tempest-react-sdk";
import { Bell } from "lucide-react";

function NotificationsRow() {
  const [enabled, setEnabled] = useState(true);

  return (
    <ListTile
      leading={<Bell size={20} />}
      title="Notificações"
      subtitle="Receber alertas por push"
      trailing={
        <Switch checked={enabled} onChange={(e) => setEnabled(e.target.checked)} />
      }
    />
  );
}
```

| Prop       | Tipo                                  | Default |
| ---------- | ------------------------------------- | ------- |
| `title`    | `ReactNode`                           | —       |
| `leading`  | `ReactNode` (slot esquerdo)           | —       |
| `subtitle` | `ReactNode` (linha secundária)        | —       |
| `trailing` | `ReactNode` (slot direito)            | —       |
| `onClick`  | `() => void` (torna a tile um botão)  | —       |
| `selected` | `boolean` (destaca a linha ativa)     | `false` |
| `disabled` | `boolean` (esmaecida, não-interativa) | `false` |

!!! note "Botão só quando há `onClick`"
    Sem `onClick`, a `ListTile` é um `<div>` puramente visual. Com `onClick`, ela vira `<button>` com `aria-pressed` (quando `selected`) e respeita `disabled` — não envolva em outro elemento clicável.

## `Accordion`

> **Quando usar**: condensar conteúdo seccionável que o usuário expande sob demanda — FAQs, formulários longos em etapas, painéis de configurações.

Modo single (default) ou `multiple`. Controlado via `value` + `onChange`, ou não-controlado via `defaultValue`.

```tsx
<Accordion
  items={[
    { id: "1", title: "Como cancelo minha assinatura?", children: <p>...</p> },
    { id: "2", title: "Quais formas de pagamento?", children: <p>...</p> },
  ]}
/>;

<Accordion multiple value={openIds} onChange={setOpenIds} items={faqItems} />;
```

| Prop           | Tipo                                 | Default |
| -------------- | ------------------------------------ | ------- |
| `items`        | `AccordionItem[]`                    | —       |
| `multiple`     | `boolean` (permite vários abertos)   | `false` |
| `value`        | `string[]` (ids abertos, controlled) | —       |
| `defaultValue` | `string[]` (ids abertos iniciais)    | `[]`    |
| `onChange`     | `(openIds: string[]) => void`        | —       |

`AccordionItem = { id, title, children, disabled? }`.

!!! note "Acessibilidade já incluída"
    Os cabeçalhos são `<button aria-expanded>` e o conteúdo recebe `aria-hidden` quando fechado. As setas ↑↓ trocam o item focado; Home/End pulam para o primeiro/último.

## `Timeline`

> **Quando usar**: mostrar uma sequência de eventos no tempo — rastreio de pedido, log de auditoria, feed de atividade. Cada entrada tem marker colorido, título, descrição e meta opcionais.

Feed vertical com markers coloridos. Renderiza como `<ol>` semântica (cada item é `<li>`).

```tsx
<Timeline
  items={[
    { id: "1", title: "Pedido criado", meta: "10:24", marker: "primary" },
    { id: "2", title: "Pagamento aprovado", meta: "10:25", marker: "success" },
    {
      id: "3",
      title: "Saiu pra entrega",
      description: "Motorista: João",
      meta: "11:00",
      marker: "warning",
    },
    { id: "4", title: "Entregue", meta: "12:30", marker: "success" },
  ]}
/>
```

| Prop        | Tipo                            | Default |
| ----------- | ------------------------------- | ------- |
| `items`     | `TimelineItem[]`                | —       |
| `connector` | `boolean` (linha entre markers) | `true`  |

`TimelineItem = { id, title, description?, meta?, icon?, marker?: "primary" \| "success" \| "warning" \| "danger" \| "neutral" }`.

## `TreeView`

> **Quando usar**: dados **hierárquicos** — árvore de categorias, permissões por módulo, pastas, organograma. Quando o dado é uma lista plana, `Table` ou `ListTile` servem melhor.

Implementa `role="tree"` com **roving tabindex**: uma única linha é tabulável e as setas movem o foco dentro do widget. É isso que evita uma árvore de 500 nós adicionar 500 paradas na ordem de tabulação da página.

```tsx
import { TreeView, type TreeNode } from "tempest-react-sdk";

const permissoes: TreeNode[] = [
  {
    id: "vendas",
    label: "Vendas",
    children: [
      { id: "vendas.ler", label: "Visualizar" },
      { id: "vendas.editar", label: "Editar" },
      { id: "vendas.excluir", label: "Excluir", disabled: true },
    ],
  },
  { id: "config", label: "Configurações", children: [] },
  { id: "sobre", label: "Sobre" },
];

export function PermissoesDoPapel() {
  const [selecionado, setSelecionado] = useState<string | null>(null);

  return (
    <TreeView
      label="Permissões"
      nodes={permissoes}
      defaultExpandedIds={["vendas"]}
      selectedId={selecionado}
      onSelect={(node) => setSelecionado(node.id)}
    />
  );
}
```

| Prop                 | Tipo                        | Default | O que faz                                                          |
| -------------------- | --------------------------- | ------- | ------------------------------------------------------------------ |
| `nodes`              | `TreeNode[]`                | —       | Nós raiz.                                                          |
| `expandedIds`        | `string[]`                  | —       | Expansão controlada.                                               |
| `defaultExpandedIds` | `string[]`                  | `[]`    | Expansão inicial (não controlada).                                 |
| `onExpandedChange`   | `(ids: string[]) => void`   | —       | Chamado a cada expandir/colapsar.                                  |
| `selectedId`         | `string \| null`            | —       | Seleção controlada.                                                |
| `defaultSelectedId`  | `string \| null`            | `null`  | Seleção inicial.                                                   |
| `onSelect`           | `(node: TreeNode) => void`  | —       | Chamado ao selecionar (clique, `Enter` ou `Espaço`).                |
| `toggleOnSelect`     | `boolean`                   | `true`  | Selecionar um galho também o expande/colapsa.                      |
| `label`              | `string`                    | —       | Nome acessível da árvore.                                          |

`TreeNode = { id, label, children?, icon?, disabled? }`.

**Teclado**: `↓`/`↑` movem · `→` expande (ou desce pro primeiro filho) · `←` colapsa (ou sobe pro pai) · `Home`/`End` primeira/última linha visível · `Enter`/`Espaço` selecionam.

!!! tip "`children: []` é um galho vazio, não uma folha"
    A distinção importa: uma pasta vazia deve mostrar o chevron e anunciar `aria-expanded`. Folha é `children` **ausente**.

!!! note "`toggleOnSelect={false}` quando o galho é uma escolha válida"
    O default (`true`) imita explorador de arquivos: clicar na pasta abre a pasta. Passe `false` quando o galho em si é selecionável — uma categoria que também é destino, por exemplo.

!!! info "O chevron não é um botão"
    Ele é decoração (`aria-hidden`): a linha já carrega `aria-expanded`, então um segundo controle focável ali só adicionaria ruído no leitor de tela, duplicando uma ação que o teclado já tem. Clique nele funciona (com o evento parado, então expande sem selecionar).

## `Sparkline`

> **Quando usar**: mostrar a **forma** de uma série ao lado do número que ela explica — uma célula de tabela, um card de métrica, uma linha de lista. Não é substituto de gráfico: se o leitor precisa ler valores no eixo, use [`LineChart`](../charts.md).

Um sparkline é SVG puro na entrada raiz, **sem recharts**. Uma coluna de tendência numa tabela não deveria obrigar o app a instalar uma biblioteca de gráfico inteira.

```tsx
import { formatCurrency, Sparkline, Table } from "tempest-react-sdk";

const produtos = [
  { nome: "Plano Pro", receita: 48200, serie: [12, 18, 15, 24, 22, 31, 29] },
  { nome: "Plano Base", receita: 19400, serie: [22, 19, 20, 17, 14, 13, 11] },
];

export function TendenciaPorProduto() {
  return (
    <Table
      data={produtos}
      columns={[
        { key: "nome", header: "Produto" },
        {
          key: "serie",
          header: "7 dias",
          render: (linha) => (
            <Sparkline data={linha.serie} label={`Tendência de ${linha.nome}`} />
          ),
        },
        { key: "receita", header: "Receita", render: (l) => formatCurrency(l.receita) },
      ]}
      rowKey={(linha) => linha.nome}
    />
  );
}
```

### Variantes

```tsx
<Sparkline data={serie} />                        {/* linha (default) */}
<Sparkline data={serie} variant="area" />         {/* linha + preenchimento lavado */}
<Sparkline data={serie} variant="bar" />          {/* uma barra por ponto */}
```

| Prop             | Tipo                              | Default                    | O que faz                                                        |
| ---------------- | --------------------------------- | -------------------------- | ---------------------------------------------------------------- |
| `data`           | `readonly number[]`               | —                          | A série, em ordem. Entradas não-finitas são descartadas.          |
| `variant`        | `"line" \| "area" \| "bar"`       | `"line"`                   | Qual marca desenhar.                                              |
| `width`          | `number`                          | `88`                       | Largura de desenho em px.                                         |
| `height`         | `number`                          | `24`                       | Altura de desenho em px.                                          |
| `color`          | `string`                          | `var(--tempest-chart-1)`   | Qualquer cor CSS.                                                 |
| `showEnd`        | `boolean`                         | `true` (exceto em `"bar"`) | Marca o último ponto com um ponto.                                |
| `min` / `max`    | `number`                          | extremos da série          | Fixa o eixo de valor — é o que torna várias linhas comparáveis.   |
| `valueFormatter` | `(value: number) => string`       | `String`                   | Como renderizar um valor na descrição acessível.                  |
| `label`          | `string`                          | descrição gerada           | Nome acessível.                                                   |

### Comparar linhas exige eixo compartilhado

Por padrão cada sparkline se normaliza contra os próprios extremos. Numa coluna de tabela isso é uma armadilha: uma linha que vai de 2 a 4 e outra que vai de 200 a 400 desenham **exatamente a mesma forma**.

```tsx
const teto = Math.max(...produtos.flatMap((p) => p.serie));

<Sparkline data={linha.serie} min={0} max={teto} />;
```

!!! warning "Sem `min`/`max`, a forma é relativa — nunca comparável"
    Passe os dois quando os sparklines aparecem empilhados. É o erro mais comum com esse componente, e ele não gera nenhum aviso: os gráficos ficam bonitos e mentem.

### Acessibilidade

O componente carrega `role="img"` e um `aria-label` que **descreve a série em palavras**: quantidade de pontos, direção, extremos e as pontas.

```text
"7 pontos, subindo. Início 12, fim 29. Mínimo 12, máximo 31."
```

Um sparkline não tem eixo nem legenda para servir de apoio — sem essa frase ele é uma imagem sem nome, e o leitor de tela chega nele e não lê nada. Passe `label` quando o texto ao redor já diz o que está plotado.

!!! tip "A forma é contexto, nunca o único caminho pro valor"
    Sempre coloque o sparkline **ao lado do número** que ele anota. Ele responde "está subindo?", não "quanto?".

!!! info "Séries com buraco não apagam o gráfico"
    Um `NaN` no meio de um atributo `d` anula o path inteiro silenciosamente — o gráfico some sem erro nenhum. Valores não-finitos são filtrados antes de projetar.

!!! note "Série achatada fica centralizada"
    Uma série sem variação é desenhada no meio da caixa, não colada numa borda. É a leitura honesta de "não variou" e evita dividir por um domínio de altura zero.

## Resumo

| Componente    | Use para                                    | Volume típico      |
| ------------- | ------------------------------------------- | ------------------ |
| `Table<T>`    | Comparar registros em colunas               | dezenas a centenas |
| `VirtualList` | Rolar listas longas de altura fixa          | 500+ itens         |
| `VirtualTable<T>` | Grade rolável de linhas em colunas      | milhares de linhas |
| `ListTile`    | Linha de lista (ícone + título + ação)      | qualquer           |
| `Accordion`   | Seções expansíveis sob demanda (FAQ, steps) | poucas seções      |
| `Timeline`    | Sequência de eventos no tempo               | qualquer           |
| `TreeView`    | Hierarquia navegável (categorias, permissões) | dezenas a centenas |
| `Sparkline`   | Forma de uma série ao lado do número que ela explica | 5 a ~100 pontos |

Pontos-chave de acessibilidade:

- `Table` usa `<th scope="col">` (já incluso); `onRowClick` aplica `role="button"` + `tabIndex={0}`.
- `Table` e `VirtualList` ganham **ponto de tabulação próprio enquanto rolam** (`role="group"`/`role="list"` + `tabIndex={0}`), e o perdem quando o conteúdo cabe. Sem isso o contêiner não tem nada focável dentro e quem usa teclado vê a barra de rolagem sem conseguir movê-la. Nomeie com `scrollLabel` (Table) ou `label` (VirtualList) quando a página tiver vários.
- `VirtualList`: itens fora da viewport não são renderizados — `Ctrl+F` só acha o visível.
- `VirtualTable`: continua uma `<table>` real (espaçadoras em vez de posicionamento absoluto), com `aria-rowcount`/`aria-rowindex` carregando os índices reais e não os da janela; cabeçalho ordenável expõe `aria-sort`.
- `Accordion`: ↑↓ trocam o item focado, Home/End pulam pro primeiro/último.
- `Timeline`: ordem semântica via `<ol>`; cada item é `<li>`.
- `Sparkline`: `role="img"` com uma frase descrevendo direção, pontas e extremos — sem eixo nem legenda, é a única leitura possível fora da visão.
- `TreeView`: `role="tree"` + roving tabindex (uma parada de tab só); `aria-level` reporta a profundidade e nós desabilitados são pulados na navegação.

Relacionados: [identity](./identity.md) (`Card flush` para hospedar a `Table`) · [feedback](./feedback.md) (`Badge` dentro de células) · [actions](./actions.md) (botões de linha).

---

# components/feedback.md

# Status & feedback

Sinalizar estado, sucesso, erro, atividade. Spinners, skeletons, alertas, KPIs.

## O que é esta categoria

Componentes que **comunicam estado** ao usuário — o que aconteceu, o que está acontecendo e o que não tem ali. Agrupam-se por intenção:

- **Mensagens** (sucesso/erro/aviso): `Alert` (inline), `Banner` (topo da página), `Toast` (transiente) — três escopos do mesmo conceito.
- **Rótulos de status**: `Badge` (status fixo), `Tag` (chip removível), `Stat` (KPI).
- **Atividade/carregamento**: `Spinner`, `Progress`, `Skeleton`, `NProgressBar` (barra fixa no topo).
- **Estados vazios/erro de tela**: `EmptyState`, `ErrorState`.

**Quando usar:** sempre que o usuário precisar saber o resultado de uma ação ou o estado de um dado. A regra de ouro: **nunca deixe uma ação assíncrona sem feedback** — mostre `Spinner`/`Skeleton` durante, `Toast`/`Alert` ao terminar.

!!! tip "Alert vs Banner vs Toast — escolha pelo escopo"
    `Alert` é inline e fica até o usuário resolver o contexto. `Banner` é persistente no topo e vale para a página/app inteiro. `Toast` é transiente e some sozinho. Use `Toast` para confirmações rápidas, `Alert` para erros ligados a um campo/seção, `Banner` para avisos globais (manutenção, expiração).

## `Alert`

**Quando usar:** mensagem ligada a um contexto específico da tela (erro de formulário, resultado de uma operação numa seção). Fica visível até a condição mudar.

Banner inline. Diferente de `Banner` (top-of-page) e `Toast` (transient).

```tsx
<Alert variant="success" appearance="soft" title="Salvo">
  Suas alterações foram aplicadas com sucesso.
</Alert>;

<Alert
  variant="danger"
  appearance="outline"
  icon={<AlertCircle />}
  dismissible
  onDismiss={() => setOpen(false)}
>
  Falha ao processar pagamento.
</Alert>;
```

| Prop          | Tipo                                                        | Default  |
| ------------- | ----------------------------------------------------------- | -------- |
| `variant`     | `"neutral" \| "info" \| "success" \| "warning" \| "danger"` | `"info"` |
| `appearance`  | `"soft" \| "solid" \| "outline"`                            | `"soft"` |
| `title`       | `ReactNode`                                                 | —        |
| `icon`        | `ReactNode`                                                 | —        |
| `action`      | `ReactNode`                                                 | —        |
| `dismissible` | `boolean`                                                   | `false`  |
| `onDismiss`   | `() => void`                                                | —        |

**A11y**: `role="status"` para info/success, `role="alert"` para warning/danger.

## `Banner`

Persistente, top-of-page. Use para environment indicators, manutenção, expiração.

```tsx
<Banner
  variant="warning"
  dismissible
  onDismiss={() => setOpen(false)}
  action={<Button size="sm">Renovar</Button>}
>
  Sua assinatura expira em 3 dias.
</Banner>
```

Mesmas variants do Alert.

## `Badge`

**Quando usar:** rótulo de status curto e somente-leitura ao lado de um item (status de pedido, contagem). Para um chip que o usuário remove, use `Tag`.

Status pill — não removível.

```tsx
<Badge>Default</Badge>
<Badge variant="success">Pago</Badge>
<Badge variant="danger" appearance="solid">Atrasado</Badge>
<Badge variant="warning" appearance="outline" shape="square">Pendente</Badge>
<Badge variant="info" dot>3</Badge>
```

| Prop         | Tipo                                                                     | Default     |
| ------------ | ------------------------------------------------------------------------ | ----------- |
| `variant`    | `"neutral" \| "primary" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` |
| `appearance` | `"soft" \| "solid" \| "outline"`                                         | `"soft"`    |
| `shape`      | `"pill" \| "square"`                                                     | `"pill"`    |
| `size`       | `"sm" \| "md" \| "lg"`                                                   | `"md"`      |
| `dot`        | `boolean` (indicador de status + número)                                 | `false`     |

## `Tag`

Chip removível. Use para filter tokens, applied filters, selected entities.

```tsx
<Tag onRemove={() => removeFilter("sp")} variant="primary">São Paulo</Tag>
<Tag size="sm">Em estoque</Tag>
```

| Prop          | Tipo                                                                     | Default     |
| ------------- | ------------------------------------------------------------------------ | ----------- |
| `variant`     | `"neutral" \| "primary" \| "success" \| "warning" \| "danger" \| "info"` | `"neutral"` |
| `size`        | `"sm" \| "md" \| "lg"`                                                   | `"md"`      |
| `onRemove`    | `() => void`                                                             | —           |
| `removeLabel` | `string` (a11y)                                                          | `"Remover"` |

## `Stat`

**Quando usar:** destacar uma métrica única com variação (receita, sessões, NPS) em dashboards. Para vários KPIs lado a lado, combine com `Grid`.

KPI card para dashboards.

```tsx
<Stat
  label="Receita"
  value="R$ 12.345"
  delta="+12,4%"
  hint="vs. mês anterior"
  icon={<TrendingUp />}
/>;

<Stat label="Sessões" value="1.2k" delta="-3%" hint="últimos 7 dias" />;
<Stat label="NPS" value="78" delta="0" trend="flat" />;
```

| Prop    | Tipo                       | Default                              |
| ------- | -------------------------- | ------------------------------------ |
| `label` | `ReactNode`                | —                                    |
| `value` | `ReactNode`                | —                                    |
| `delta` | `ReactNode`                | —                                    |
| `trend` | `"up" \| "down" \| "flat"` | inferido por `+`/`-` em delta string |
| `hint`  | `ReactNode`                | —                                    |
| `icon`  | `ReactNode`                | —                                    |

## `Progress`

Barra de progresso.

```tsx
<Progress value={uploadProgress} max={100} variant="primary" />;
<Progress value={100} variant="success" />;
<Progress indeterminate variant="primary" />;
```

| Prop            | Tipo                                 | Default     |
| --------------- | ------------------------------------ | ----------- |
| `value`         | `number`                             | —           |
| `max`           | `number`                             | `100`       |
| `variant`       | `"primary" \| "success" \| "danger"` | `"primary"` |
| `indeterminate` | `boolean`                            | `false`     |

## `NProgress`

**Quando usar:** barra de carregamento fixa no topo da página para transições que não têm uma posição exata — navegação de rotas, requests em background. Para progresso determinístico de um upload, prefira `Progress`.

Controlador imperativo (`nprogress`) + a barra visual (`<NProgressBar>`). Monte a barra uma vez perto da raiz do app e dirija o controlador de qualquer lugar (transições de rota, interceptors de fetch).

```tsx
import { NProgressBar, nprogress, Button } from "tempest-react-sdk";

// raiz do app — renderiza nada enquanto inativo
<NProgressBar color="var(--tempest-primary)" height={3} />;

// dispare de qualquer lugar
async function loadPage() {
  nprogress.start();
  try {
    await fetch("/api/data");
  } finally {
    nprogress.done();
  }
}

<Button onClick={loadPage}>Carregar</Button>;
```

| `nprogress` | Assinatura            | O que faz                                         |
| ----------- | --------------------- | ------------------------------------------------- |
| `start`     | `() => void`          | Mostra a barra e começa a "trickle" até ~0.9.    |
| `done`      | `() => void`          | Completa em `1` e esconde a barra logo depois.   |
| `set`       | `(n: number) => void` | Define o progresso explicitamente (clamp `0..1`). |
| `inc`       | `(amount?: number) => void` | Incrementa o progresso por `amount`.        |

| Prop (`NProgressBar`) | Tipo     | Default                  |
| --------------------- | -------- | ------------------------ |
| `color`               | `string` | `var(--tempest-primary)` |
| `height`              | `number` | `3`                      |
| `className`           | `string` | —                        |

!!! tip "Ótimo com navegação de rotas"
    Chame `nprogress.start()` ao iniciar a transição e `nprogress.done()` quando a rota montar. O `nprogress` é um singleton de módulo — não precisa de provider nem de props drilling.

**A11y**: a barra usa `role="progressbar"` com `aria-valuenow` refletindo o percentual.

## `Spinner`

Loader genérico.

```tsx
<Spinner />;
<Spinner size="lg" />;
<Spinner size="lg" caption="Carregando…" />;
<Spinner overlay caption="Carregando…" />; // fallback de Suspense/rota
```

| Prop      | Tipo                                   | Default        | Descrição                                                       |
| --------- | -------------------------------------- | -------------- | --------------------------------------------------------------- |
| `size`    | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"`         | Tamanho do indicador.                                           |
| `label`   | `string`                               | `"Carregando"` | Rótulo acessível (lido por leitores de tela).                   |
| `caption` | `ReactNode`                            | —              | Texto **visível** abaixo do spinner.                            |
| `overlay` | `boolean`                              | `false`        | Centraliza num container de área cheia (`position: absolute`).  |

!!! note "Back-compat"
    `<Spinner />` sem `caption`/`overlay` continua um único `<span role="status">` — nada muda no uso antigo.

## `Skeleton`

**Quando usar:** carregamento de conteúdo cuja **forma** já é conhecida (cards, linhas de tabela, avatar). Reduz o salto de layout. Para carregamento sem forma definida (um botão processando), use `Spinner`.

Placeholder com shimmer enquanto data carrega.

!!! tip "Skeleton imita o layout final"
    Faça o skeleton ter as mesmas dimensões/proporções do conteúdo real — é isso que elimina o layout shift quando os dados chegam. Skeletons genéricos demais (um bloco só) confundem mais do que ajudam.

```tsx
{
  loading ? (
    <Stack gap={2}>
      <Skeleton variant="text" width="60%" />
      <Skeleton variant="text" width="40%" />
      <Skeleton variant="rect" height={120} />
    </Stack>
  ) : (
    <ActualContent />
  );
}
<Skeleton variant="circle" width={40} height={40} />;
```

| Prop      | Tipo                           | Default  |
| --------- | ------------------------------ | -------- |
| `variant` | `"rect" \| "text" \| "circle"` | `"rect"` |
| `width`   | `number \| string`             | `"100%"` |
| `height`  | `number \| string`             | —        |

## `RefreshIndicator`

**Quando usar:** dar ao usuário um gesto de **pull-to-refresh** em listas/telas roláveis no mobile (touch) — feeds, caixas de entrada, dashboards. Envolve o conteúdo rolável e dispara `onRefresh` quando o usuário puxa além do limite e solta.

É um gesto **de toque** — não há equivalente com mouse. O `Spinner` do SDK aparece enquanto puxa e durante a atualização.

```tsx
import { RefreshIndicator } from "tempest-react-sdk";

function Feed({ items, refetch }) {
  return (
    <RefreshIndicator onRefresh={async () => await refetch()}>
      <ul>
        {items.map((item) => (
          <li key={item.id}>{item.title}</li>
        ))}
      </ul>
    </RefreshIndicator>
  );
}
```

| Prop         | Tipo                          | Default |
| ------------ | ----------------------------- | ------- |
| `onRefresh`  | `() => void \| Promise<void>` | —       |
| `children`   | `ReactNode` (conteúdo rolável)| —       |
| `threshold`  | `number` (px até disparar)    | `80`    |
| `disabled`   | `boolean`                     | `false` |

!!! note "Gesto só de toque"
    O `RefreshIndicator` escuta arrastos de toque que começam com o container no topo do scroll — não responde ao mouse. Em desktop, ofereça um botão de "Atualizar" explícito como alternativa.

## `Toast`

**Quando usar:** confirmação transiente de uma ação que já terminou ("Salvo", "Item removido") — não exige atenção e some sozinho. Para erros que o usuário precisa resolver, prefira `Alert`/`Banner` (que ficam).

Notificações transientes. Setup via `ToastProvider` + uso via `useToast()`.

!!! warning "Toast não é para erros críticos"
    Toasts somem em poucos segundos — se o usuário precisar **agir** sobre a mensagem (corrigir um campo, tentar de novo), ela tem que persistir. Use `Toast` só para feedback descartável; erros acionáveis vão em `Alert`/`ErrorState`.

```tsx
// app root
<ToastProvider position="top-right" defaultDuration={4000}>
  <App />
</ToastProvider>;

// componentes
const toast = useToast();
toast.success("Salvo");
toast.error("Falha ao processar pagamento", { duration: 8000 });
toast.show({ title: "Sincronização", description: "Em andamento…", variant: "info" });
```

| `ToastApi` | Assinatura                                       |
| ---------- | ------------------------------------------------ |
| `show`     | `(options: ToastOptions) => string` (returns id) |
| `success`  | `(description, options?) => string`              |
| `error`    | `(description, options?) => string`              |
| `warning`  | `(description, options?) => string`              |
| `info`     | `(description, options?) => string`              |
| `dismiss`  | `(id: string) => void`                           |

`ToastProvider.position`: `"top-right"` (default), `"top-left"`, `"top-center"`, `"bottom-right"`, `"bottom-left"`, `"bottom-center"`.

**Safe-area aware**.

## `EmptyState`

**Quando usar:** uma lista/coleção retornou **zero itens com sucesso** (sem pedidos ainda, busca sem resultados). Sempre ofereça uma ação de saída (criar o primeiro item, limpar filtros). Não confunda com erro — para falha use `ErrorState`.

"Nada por aqui" centralizado.

```tsx
<EmptyState
  icon={<InboxIcon />}
  title="Nenhum pedido"
  description="Quando seus clientes fizerem pedidos, eles aparecem aqui."
  action={<Button leftIcon={<Plus />}>Novo pedido</Button>}
/>
```

## `ErrorState`

**Quando usar:** uma operação **falhou** (request com erro, exceção) e o usuário pode tentar de novo. Diferente de `EmptyState`, que representa sucesso sem dados.

Falha com botão de retry.

```tsx
<ErrorState title="Não foi possível carregar" description={String(error)} onRetry={refetch} />
```

## `OfflineIndicator`

**Quando usar:** avisar que o app está offline e confirmar quando a conexão volta. Guiado por `useOnline` — não renderiza nada online, então monte na raiz sem `if`.

```tsx
<OfflineIndicator position="top" />
```

`position`: `"top"` | `"bottom"` (default). Passe `children` pra substituir o corpo, ou `onlineFlashMs={0}` pra não piscar a confirmação. Veja [PWA & Offline-First](../pwa.md).

## `SyncStatusBadge`

**Quando usar:** mostrar o estado do motor offline (sincronizado / sincronizando / pendente / offline / erro). Dois modos: passe `sync` pra conectar direto no motor (zero fiação), ou passe `tone` explícito (apresentacional, testável sem IndexedDB).

```tsx
// Conectado — auto-fia o motor:
<SyncStatusBadge sync={notesSync} />;

// Apresentacional — você controla o estado:
const { tone, pending } = useSyncStatus(notesSync);
<SyncStatusBadge tone={tone} pending={pending} />;
```

`tone`: `"idle"` | `"syncing"` | `"pending"` | `"offline"` | `"error"`. `iconOnly` esconde o label; `labels` sobrescreve os textos por tom.

## `UpdatePrompt`

**Quando usar:** avisar que há uma versão nova do app (service worker) e deixar o usuário recarregar. Par de `useServiceWorkerUpdate`.

```tsx
const { updateAvailable, applyUpdate } = useServiceWorkerUpdate({ url: "/sw.js" });
<UpdatePrompt open={updateAvailable} onUpdate={applyUpdate} />;
```

Renderiza nada com `open={false}`. `onDismiss` (opcional) mostra o botão de dispensar; `position` `"top"`/`"bottom"`.

## A11y geral

- `Alert`/`Banner` com variant `warning`/`danger` usam `role="alert"` (anunciado imediatamente).
- `Toast` container é `aria-live="polite"` + `aria-atomic="true"`.
- `Spinner`/`Progress.indeterminate` adicionam `aria-busy="true"`.
- `Skeleton` é decorativo — não anuncia (`aria-hidden`).
- `Stat.value` com tabular-nums alinha valores numéricos em colunas.

## Resumo

- **Nunca deixe uma ação assíncrona sem feedback**: `Spinner`/`Skeleton` durante, `Toast`/`Alert` ao terminar.
- Mensagens por escopo: `Alert` (inline/contextual), `Banner` (global/topo), `Toast` (transiente).
- `EmptyState` = sucesso sem dados; `ErrorState` = falha com retry. Não troque um pelo outro.
- `Toast` só para feedback descartável; erros acionáveis ficam em `Alert`/`ErrorState`.

Páginas relacionadas:

- [Entrada de dados](./inputs.md) — `error` em campos de formulário, complementar a `Alert` de seção.
- [Dados](./data.md) — `Table`/`DataTable` que combinam com `Skeleton` (loading) e `EmptyState`/`ErrorState`.
- [Sobreposições](./overlay.md) — `ConfirmDialog` para ações destrutivas que pedem confirmação antes do `Toast`.
- [Layout](./layout.md) — `Grid` para dispor vários `Stat`; `Center` para `Spinner` em tela cheia.

---

# components/identity.md

# Identidade & micro

Componentes de **identidade** representam _quem_ ou _o quê_ na interface: a pessoa por trás de uma conta (`Avatar`), um bloco de conteúdo agrupado e reconhecível (`Card`) e a tipografia semântica de uma tecla de atalho (`Kbd`). São peças pequenas e de alta frequência — aparecem em listas, headers, feeds — então a consistência delas define a "cara" do app.

Use esta página quando precisar **mostrar** uma entidade ou agrupar conteúdo, não quando precisar de uma ação ([actions](./actions.md)) ou de layout puro ([layout](./layout.md)).

## `Avatar`

> **Quando usar**: representar visualmente um usuário/entidade em listas, comentários, headers — com foto quando disponível e iniciais coloridas como fallback.

Foto de usuário com fallback automático para iniciais coloridas quando não há `src` ou a imagem falha ao carregar. As iniciais são derivadas de `name` (não de `alt`).

```tsx
<Avatar src={user.photo} name={user.name} alt={user.name} />;
<Avatar size="lg" status="online" name="Ana" />;
<Avatar name="João da Silva" />; // fallback gera iniciais "JS"
<Avatar name="João" status="busy" size="sm" />;
```

| Prop      | Tipo                                        | Default |
| --------- | ------------------------------------------- | ------- |
| `src`     | `string`                                    | —       |
| `alt`     | `string` (texto alternativo da imagem)      | —       |
| `name`    | `string` (gera as iniciais do fallback)     | `""`    |
| `size`    | `"xs" \| "sm" \| "md" \| "lg" \| "xl"`      | `"md"`  |
| `status`  | `"online" \| "offline" \| "busy"`           | —       |
| `onClick` | `() => void`                                | —       |

!!! warning "Iniciais vêm de `name`, não de `alt`"
    O fallback de iniciais é calculado a partir de `name`. Se você passar só `alt`, o avatar mostra `?` quando a imagem falha. Para um nome composto, ele usa a primeira letra do primeiro e do último termo (`"João da Silva"` → `"JS"`).

!!! tip "Sempre forneça `alt` quando houver `src`"
    Quando `src` está setado, `alt` é o texto que leitores de tela anunciam. Descreva a pessoa (o nome), não a mídia — evite `"foto de…"`.

## `Card`

> **Quando usar**: agrupar conteúdo relacionado num bloco com elevação visual — um item de lista, um painel de dashboard, um container para tabela.

Container com slots de header (`title` + `actions`) e `footer`.

```tsx
<Card title="Pedido #12345" actions={<Button variant="ghost">Editar</Button>}>
    Conteúdo do card.
</Card>;

<Card elevation="raised" interactive onClick={() => navigate("/x")}>
    Card clicável com hover effect.
</Card>;

<Card flush footer={<Pagination ... />}>
    <Table ... />
</Card>;
```

| Prop          | Tipo                                                  | Default     |
| ------------- | ----------------------------------------------------- | ----------- |
| `title`       | `ReactNode`                                           | —           |
| `actions`     | `ReactNode` (slot direito do header)                  | —           |
| `footer`      | `ReactNode`                                           | —           |
| `elevation`   | `"flat" \| "default" \| "raised" \| "elevated"`       | `"default"` |
| `interactive` | `boolean` (cursor pointer + hover ring)               | `false`     |
| `flush`       | `boolean` (zero padding interno — pra hospedar Table) | `false`     |

!!! tip "Use `flush` para hospedar tabelas e listas"
    Cards têm padding interno por padrão. Ao colocar uma `Table` ou lista que já tem suas próprias margens, ative `flush` para o conteúdo encostar nas bordas do card sem padding duplo.

!!! note "`interactive` torna o card inteiro um botão"
    Com `interactive`, o card recebe `role="button"`, `tabIndex={0}` e handler de teclado (Enter/Space). Evite colocar outros elementos clicáveis dentro de um card interativo — clicks aninhados disputam o mesmo gesto e confundem a navegação por teclado.

## `Kbd`

> **Quando usar**: exibir uma tecla ou combinação (atalhos, dicas de command palette) com a aparência de tecla física.

`<kbd>` estilizado para atalhos de teclado.

```tsx
<p>Aperte <Kbd>Ctrl</Kbd>+<Kbd>K</Kbd> para abrir o command palette.</p>
<Kbd size="lg">⌘</Kbd>
```

| Prop   | Tipo                   | Default |
| ------ | ---------------------- | ------- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"`  |

!!! tip "Um `<Kbd>` por tecla"
    Para combinações, repita o componente em vez de juntar tudo em texto plano: `<Kbd>Ctrl</Kbd>+<Kbd>K</Kbd>`. Cada `<Kbd>` renderiza um elemento `<kbd>` semântico que leitores de tela anunciam individualmente.

## `AvatarGroup`

> **Quando usar**: mostrar várias pessoas num espaço pequeno — participantes de uma reunião, responsáveis por uma tarefa, membros de um time.

Fileira de avatares sobrepostos com chip `+N` no fim.

```tsx
<AvatarGroup
  label="Participantes"
  max={3}
  items={[
    { name: "Ada Lovelace", src: ada },
    { name: "Grace Hopper" },
    { name: "Alan Turing" },
    { name: "Edsger Dijkstra" },
  ]}
  onOverflowClick={() => setDrawerAberto(true)}
/>
```

| Prop              | Tipo                | Default | O que faz                                                    |
| ----------------- | ------------------- | ------- | ------------------------------------------------------------ |
| `items`           | `AvatarGroupItem[]` | —       | Pessoas do grupo (`{ name, src? }`).                          |
| `max`             | `number`            | `4`     | Quantos avatares antes de colapsar em `+N`.                   |
| `size`            | `AvatarSize`        | `"md"`  | Tamanho aplicado aos avatares **e** ao chip.                  |
| `label`           | `string`            | —       | Nome acessível do grupo.                                      |
| `onOverflowClick` | `() => void`        | —       | Torna o chip `+N` um botão focável (ex.: abrir "ver todos").   |

!!! info "Um grupo, um nome acessível"
    A fileira é um `role="group"` com um nome só, e cada avatar expõe o nome da pessoa. Anunciar sete imagens soltas sem relação entre elas é ruído; o chip `+N` carrega o restante da contagem, então o total nunca fica escondido do leitor de tela.

!!! tip "A sobreposição é ajustável"
    `--tempest-avatar-overlap` controla o quanto cada avatar cobre o anterior — os defaults são proporcionais ao `size`.

## Resumo

| Componente | Use para                                       |
| ---------- | ---------------------------------------------- |
| `Avatar`   | Representar um usuário (foto ou iniciais)      |
| `Card`     | Agrupar conteúdo relacionado num bloco elevado |
| `Kbd`      | Exibir teclas/atalhos de teclado               |

Pontos-chave de acessibilidade:

- `Avatar.alt` descreve o usuário (nome), não a mídia; as iniciais vêm de `name`.
- `Card` com `interactive` aplica `role="button"` + teclado (Enter/Space) — não aninhe outros clicáveis.
- `Kbd`: repita um por tecla em combinações.

Relacionados: [actions](./actions.md) (`Button` dentro de `Card.actions`) · [data](./data.md) (`Card flush` hospedando `Table`) · [layout](./layout.md) (organizar cards em grid/stack).

---

# components/inputs.md

# Entrada de dados

Controles para coleta de dados do usuário. Todos forward refs para o elemento DOM nativo (compatível com `react-hook-form`).

## O que é esta categoria

Esta página reúne todo o conjunto de **controles de formulário** do SDK — desde o `Input` de texto simples até campos especializados como `PinInput` (OTP), `PasswordInput` (com medidor de força), `RangeSlider` (faixa dupla) e `Dropzone` (arrastar-e-soltar arquivos). Todos compartilham a mesma API de rótulo/erro/tamanho (ver a seção Convenções abaixo) e fazem forward de `ref`, então plugam direto em `react-hook-form` sem wrappers extras.

**Quando usar:** sempre que precisar coletar um valor do usuário. Escolha o controle pelo tipo de dado — texto curto (`Input`), texto longo (`Textarea`), uma opção entre poucas (`Radio`/`Select`), uma opção entre muitas com busca (`Combobox`), booleano (`Switch`/`Checkbox`), código de verificação (`PinInput`), número com incremento (`StepperInput`), etc.

!!! tip "Comece pelas Convenções"
    Todos os campos aceitam `label`, `helperText`, `error`, `required` e `size` da mesma forma. Aprenda essas 5 props uma vez e você sabe usar qualquer campo desta página.

## Convenções

- `label` (string ou node) — rótulo acima do campo.
- `helperText` — texto auxiliar abaixo; substituído por `error` quando este é setado.
- `error` (string) — mensagem de erro; adiciona `aria-invalid="true"` + borda vermelha.
- `required` — adiciona `*` no label e propaga `required` no input.
- `size: "sm" | "md" | "lg"` — escala de altura/padding/font via tokens density.

## `Input`

Texto single-line.

```tsx
import { Input } from "tempest-react-sdk";
import { Search } from "lucide-react";

<Input label="Email" type="email" placeholder="user@example.com" required />;
<Input label="Buscar" leftIcon={<Search size={16} />} placeholder="palavra-chave" />;
<Input label="Senha" type="password" error="Mínimo 8 caracteres" />;
```

| Prop               | Tipo                                                   | Default |
| ------------------ | ------------------------------------------------------ | ------- |
| `label`            | `string`                                               | —       |
| `helperText`       | `string`                                               | —       |
| `error`            | `string`                                               | —       |
| `leftIcon`         | `ReactNode`                                            | —       |
| `rightIcon`        | `ReactNode`                                            | —       |
| `size`             | `"sm" \| "md" \| "lg"`                                 | `"md"`  |
| `wrapperClassName` | `string`                                               | —       |
| ...                | Todos os atributos de `HTMLInputElement` exceto `size` | —       |

## `Textarea`

Multi-linha. Mesma API do `Input` (sem `leftIcon`/`rightIcon`).

```tsx
<Textarea label="Mensagem" rows={4} helperText="Máximo 500 caracteres" />
```

## `Select`

Nativo `<select>`. Aceita `options` (lista) ou `<option>` children.

```tsx
<Select
  label="UF"
  options={[
    { value: "SP", label: "São Paulo" },
    { value: "RJ", label: "Rio de Janeiro" },
  ]}
/>
```

| Prop      | Tipo             | Default |
| --------- | ---------------- | ------- |
| `options` | `SelectOption[]` | —       |
| `label`   | `string`         | —       |
| `error`   | `string`         | —       |

## `Combobox`

**Quando usar:** uma opção entre muitas (dezenas+), onde o usuário precisa digitar para filtrar. Para poucas opções use `Select`.

Select com busca + filtro. Keyboard nav (↑↓ Enter Esc).

```tsx
<Combobox
  label="Cidade"
  options={cities}
  value={city}
  onChange={setCity}
  filter={(opt, query) => opt.label.toLowerCase().includes(query.toLowerCase())}
/>
```

## `MultiSelect`

**Quando usar:** várias opções entre muitas, com busca e chips removíveis. Para uma única opção use `Combobox`; para poucas opções booleanas use `Checkbox`.

Multi-select filtrável com chips removíveis. Keyboard nav (↑↓ navega, Enter alterna, Esc fecha, Backspace com query vazia remove o último chip).

```tsx
import { MultiSelect, type MultiSelectOption } from "tempest-react-sdk";
import { useState } from "react";

function Example() {
  const [sel, setSel] = useState<string[]>([]);
  const options: MultiSelectOption[] = [
    { value: "sp", label: "São Paulo" },
    { value: "rj", label: "Rio de Janeiro" },
  ];

  return <MultiSelect label="Estados" options={options} value={sel} onChange={setSel} />;
}
```

| Prop           | Tipo                                            | Default                       |
| -------------- | ----------------------------------------------- | ----------------------------- |
| `options`      | `MultiSelectOption[]`                           | — (obrigatório)               |
| `value`        | `string[]`                                       | — (obrigatório, controlled)   |
| `onChange`     | `(value: string[]) => void`                      | — (obrigatório)               |
| `label`        | `string`                                         | —                             |
| `placeholder`  | `string`                                         | `"Selecione"`                 |
| `helperText`   | `string`                                         | —                             |
| `error`        | `string`                                         | —                             |
| `disabled`     | `boolean`                                         | `false`                       |
| `maxItems`     | `number`                                          | —                             |
| `filter`       | `(option, query) => boolean`                     | —                             |
| `emptyMessage` | `string`                                          | `"Nenhuma opção encontrada"`  |
| `className`    | `string`                                         | —                             |

`MultiSelectOption` é `{ value: string; label: string; disabled?: boolean }`.

## `Checkbox`

Single checkbox. Suporta `indeterminate`.

```tsx
<Checkbox label="Aceito os termos" />;
<Checkbox label="Selecionar todos" indeterminate={someSelected && !allSelected} />;
```

## `Radio` / `RadioGroup`

Radio standalone OU agrupado com value único.

```tsx
<RadioGroup label="Plano" value={plan} onChange={setPlan}>
  <Radio value="free" label="Grátis" />
  <Radio value="pro" label="Pro" />
  <Radio value="team" label="Team" />
</RadioGroup>
```

## `Switch`

**Quando usar:** ligar/desligar uma preferência com efeito imediato (ex.: notificações). Para opt-in que só vale ao submeter o form (ex.: aceitar termos), prefira `Checkbox`.

Toggle on/off.

```tsx
<Switch
  label="Receber emails"
  checked={subscribed}
  onChange={(e) => setSubscribed(e.target.checked)}
/>
```

!!! note "Switch vs Checkbox — não são intercambiáveis"
    `Switch` comunica uma ação que acontece **agora**; `Checkbox` comunica um estado que será aplicado **depois** (no submit). Trocar um pelo outro confunde o usuário sobre quando a mudança tem efeito.

## `ChipInput`

Lista de chips com adição por Enter + dedup automático.

```tsx
<ChipInput label="Tags" value={tags} onChange={setTags} placeholder="adicione e pressione Enter" />
```

## `SearchBar`

Input de busca com clear button + debounce opcional via `useDebounce`.

```tsx
<SearchBar value={q} onChange={setQ} placeholder="O que você procura?" />
```

## `DatePicker`

`<input type="date">` (ou `time`, `datetime-local`, `month`) com label/error.

```tsx
<DatePicker label="Data" value={date} onChange={setDate} mode="date" min="2025-01-01" />;
<DatePicker label="Início" mode="datetime-local" value={start} onChange={setStart} />;
```

## `DateRangePicker`

**Quando usar:** seleção de um intervalo de datas (início + fim) num calendário. Para uma única data use `Calendar`.

Calendário de intervalo: o primeiro clique define `start`, o próximo define `end` (reordenado automaticamente se for anterior), um terceiro clique recomeça; o dia sob o cursor pré-visualiza o intervalo. Matemática de `Date` pura, sem dependências.

```tsx
import { DateRangePicker, type DateRange } from "tempest-react-sdk";
import { useState } from "react";

function Example() {
  const [range, setRange] = useState<DateRange>({ start: null, end: null });

  return <DateRangePicker value={range} onChange={setRange} numberOfMonths={2} />;
}
```

| Prop             | Tipo                              | Default                     |
| ---------------- | --------------------------------- | --------------------------- |
| `value`          | `DateRange`                       | — (obrigatório, controlled) |
| `onChange`       | `(range: DateRange) => void`      | — (obrigatório)             |
| `numberOfMonths` | `number`                          | `2`                         |
| `defaultMonth`   | `Date`                            | —                           |
| `minDate`        | `Date`                            | —                           |
| `maxDate`        | `Date`                            | —                           |
| `weekStartsOn`   | `0 \| 1`                          | `0`                         |
| `className`      | `string`                          | —                           |

`DateRange` é `{ start: Date | null; end: Date | null }`.
## `TimePicker`

**Quando usar:** escolher um horário em colunas roláveis (estilo "spinner" do Material) — agendamentos, lembretes, janelas de atendimento. Para um campo nativo simples, use o `DatePicker` com `mode="time"`.

Sempre emite uma string 24h `"HH:MM"` via `onChange`, mesmo com `use12Hours` ligado. O `minuteStep` controla a granularidade da coluna de minutos.

```tsx
import { useState } from "react";
import { TimePicker } from "tempest-react-sdk";

function ScheduleField() {
  const [t, setT] = useState("09:30");

  return (
    <TimePicker
      label="Horário"
      value={t}
      onChange={setT}
      minuteStep={15}
      helperText="Selecione hora e minuto"
    />
  );
}
```

| Prop         | Tipo                          | Default |
| ------------ | ----------------------------- | ------- |
| `value`      | `string` (24h `"HH:MM"`)      | —       |
| `onChange`   | `(value: string) => void`     | —       |
| `minuteStep` | `number` (granularidade)      | `5`     |
| `use12Hours` | `boolean` (colunas 1–12 + AM/PM) | `false` |
| `label`      | `string`                      | —       |
| `helperText` | `string`                      | —       |
| `disabled`   | `boolean`                     | `false` |

!!! note "Sempre 24h na saída"
    Mesmo com `use12Hours` (colunas 1–12 + AM/PM), o `onChange` continua emitindo `"HH:MM"` em 24h — o display 12h é só visual. Guarde e envie o valor de 24h direto.

## `FileUpload`

Drag-and-drop + click-to-upload + lista de arquivos.

```tsx
<FileUpload
  label="Anexar"
  accept="image/*"
  multiple
  onFilesChange={(files) => setFiles(files)}
  maxSize={5 * 1024 * 1024}
/>
```

## `Slider`

**Quando usar:** escolher um único valor numa faixa contínua (volume, brilho, etc.). Para uma faixa de dois valores use `RangeSlider`.

Slider de thumb único sobre `<input type="range">` nativo.

```tsx
import { Slider } from "tempest-react-sdk";
import { useState } from "react";

function Example() {
  const [vol, setVol] = useState(30);

  return <Slider value={vol} onChange={setVol} label="Volume" formatValue={(v) => v + "%"} />;
}
```

| Prop          | Tipo                          | Default                     |
| ------------- | ----------------------------- | --------------------------- |
| `value`       | `number`                      | — (obrigatório, controlled) |
| `onChange`    | `(value: number) => void`     | — (obrigatório)             |
| `min`         | `number`                      | `0`                         |
| `max`         | `number`                      | `100`                       |
| `step`        | `number`                      | `1`                         |
| `label`       | `string`                      | —                           |
| `helperText`  | `string`                      | —                           |
| `disabled`    | `boolean`                     | `false`                     |
| `formatValue` | `(value: number) => string`   | —                           |
| `className`   | `string`                      | —                           |
## `Dropzone`

**Quando usar:** uma área de arrastar-e-soltar enxuta, quando você só precisa
capturar os arquivos (`onDrop`) e renderizar a lista/preview por conta própria.
Para um campo pronto com label, lista de arquivos e estilo de formulário, use
`FileUpload`.

Área drag-and-drop com input de arquivo escondido — clicável e focável por
teclado. Filtra por `maxSize` antes de chamar `onDrop`; rejeitados vão em
`onReject`.

```tsx
import { useState } from "react";
import { Dropzone } from "tempest-react-sdk";

function Uploader() {
  const [files, setFiles] = useState<File[]>([]);
  return (
    <>
      <Dropzone
        accept="image/*"
        multiple
        maxSize={5 * 1024 * 1024}
        onDrop={(accepted) => setFiles(accepted)}
        onReject={(rejected) => alert(`${rejected.length} arquivo(s) acima de 5 MB`)}
      >
        Arraste imagens aqui ou clique para selecionar
      </Dropzone>
      <ul>
        {files.map((file) => (
          <li key={file.name}>{file.name}</li>
        ))}
      </ul>
    </>
  );
}
```

| Prop        | Tipo                       | Default |
| ----------- | -------------------------- | ------- |
| `onDrop`    | `(files: File[]) => void`  | —       |
| `accept`    | `string`                   | —       |
| `multiple`  | `boolean`                  | `true`  |
| `maxSize`   | `number` (bytes)           | —       |
| `onReject`  | `(files: File[]) => void`  | —       |
| `disabled`  | `boolean`                  | `false` |
| `children`  | `ReactNode`                | prompt padrão |
| `className` | `string`                   | —       |

**A11y**: `role="button"` + `tabIndex` (Enter/Espaço abrem o seletor); `aria-disabled` quando `disabled`.

## `RangeSlider`

Dual-thumb slider com clamp `low ≤ high`.

```tsx
<RangeSlider
  label="Faixa de preço"
  min={0}
  max={1000}
  step={10}
  value={range}
  onChange={setRange}
  format={(n) => `R$ ${n}`}
/>
```

## `RatingStars`

Radio group de estrelas.

```tsx
<RatingStars value={rating} onChange={setRating} max={5} size="md" />;
<RatingStars value={4.5} readonly size="lg" />;
```

## `PinInput`

**Quando usar:** códigos de verificação curtos (OTP, 2FA, confirmação por SMS/email). Para senhas use `PasswordInput`.

OTP / one-time-code com N células. Paste, auto-advance, backspace flowback, arrow nav.

!!! tip "Colar o código inteiro funciona"
    O usuário pode colar `123456` em qualquer célula que o `PinInput` distribui os dígitos automaticamente — defina `type="numeric"` para que o teclado mobile abra no modo numérico.

```tsx
<PinInput length={6} type="numeric" onComplete={(otp) => verify(otp)} />;
<PinInput length={4} type="alphanumeric" masked autoFocus />;
```

| Prop           | Tipo                          | Default        |
| -------------- | ----------------------------- | -------------- |
| `length`       | `number`                      | `6`            |
| `type`         | `"numeric" \| "alphanumeric"` | `"numeric"`    |
| `value`        | `string`                      | — (controlled) |
| `defaultValue` | `string`                      | `""`           |
| `onChange`     | `(value: string) => void`     | —              |
| `onComplete`   | `(value: string) => void`     | —              |
| `masked`       | `boolean`                     | `false`        |
| `size`         | `"sm" \| "md" \| "lg"`        | `"md"`         |
| `autoFocus`    | `boolean`                     | `false`        |

## `PasswordInput`

Field tipo `password` com toggle de visibilidade + strength meter opcional (5 níveis).

```tsx
<PasswordInput label="Senha" autoComplete="new-password" showStrength />
```

Helper exposto: `estimatePasswordStrength(value)` retorna `0-4` (length, case mix, digits, symbols).

!!! warning "Use `autoComplete` correto"
    Em telas de cadastro use `autoComplete="new-password"`; em login use `autoComplete="current-password"`. O valor errado faz o gerenciador de senhas do navegador sugerir/salvar a senha de forma incorreta.

| Prop             | Tipo                                      | Default                                                  |
| ---------------- | ----------------------------------------- | -------------------------------------------------------- |
| `showStrength`   | `boolean`                                 | `false`                                                  |
| `strength`       | `0 \| 1 \| 2 \| 3 \| 4` (override manual) | `estimatePasswordStrength(value)`                        |
| `strengthLabels` | `[string,string,string,string,string]`    | `["Muito fraca","Fraca","Razoável","Forte","Excelente"]` |
| `toggleLabels`   | `{ show, hide }`                          | `{ show: "Mostrar senha", hide: "Esconder senha" }`      |

## `StepperInput`

`+ / −` numeric com clamp em `min/max`.

```tsx
<StepperInput value={qty} onChange={setQty} min={1} max={10} />;
<StepperInput value={price} onChange={setPrice} step={5} format={(n) => `R$ ${n}`} />;
```

## `Form` / `FormSection` / `FormRow` / `FormActions` / `FormField`

Layout wrappers para forms (`stack`/`inline`/`grid`) + integração RHF.

```tsx
<Form layout="grid" columns={2} gap={4}>
  <Input label="Nome" />
  <Input label="Email" type="email" />
  <FormActions style={{ gridColumn: "1 / -1" }}>
    <Button type="submit">Salvar</Button>
  </FormActions>
</Form>
```

Detalhes completos em [../forms.md](../forms.md).

## `ImageCropper`

> **Quando usar**: par natural do [`FileUpload`](#fileupload) — foto de perfil, foto de documento, capa. O app decide a proporção de saída; o usuário só escolhe o que cai dentro dela.

O frame fica **parado** e a imagem pana e dá zoom atrás dele. É o modelo que um fluxo de avatar quer: por construção não existe recorte fora da proporção.

```tsx
import { useRef, useState } from "react";
import { Button, FileUpload, ImageCropper, type ImageCropperHandle } from "tempest-react-sdk";

export function AvatarField({ onSave }: { onSave: (blob: Blob) => void }) {
  const [files, setFiles] = useState<File[]>([]);
  const cropper = useRef<ImageCropperHandle>(null);

  return (
    <>
      <FileUpload value={files} onChange={setFiles} accept="image/*" label="Foto" />
      {files[0] && (
        <>
          <ImageCropper
            ref={cropper}
            src={files[0]}
            aspect={1}
            shape="circle"
            maxSize={512}
            outputType="image/jpeg"
          />
          <Button
            onClick={async () => {
              const blob = await cropper.current?.crop();
              if (blob) onSave(blob);
            }}
          >
            Salvar
          </Button>
        </>
      )}
    </>
  );
}
```

| Prop            | Tipo                                             | Default              |
| --------------- | ------------------------------------------------ | -------------------- |
| `src`           | `File \| Blob \| string`                         | —                    |
| `aspect`        | `number` (`largura / altura`)                    | `1`                  |
| `maxZoom`       | `number`                                         | `4`                  |
| `maxSize`       | `number` (teto da maior aresta exportada, px)    | —                    |
| `outputType`    | `string`                                         | `"image/png"`        |
| `outputQuality` | `number` (`0`–`1`, tipos com perda)              | `0.92`               |
| `shape`         | `"rect" \| "circle"`                             | `"rect"`             |
| `onCropChange`  | `({ zoom, offset }) => void`                     | —                    |
| `label`         | `string` (nome acessível da área)                | `"Área de recorte"`  |
| `ref`           | `Ref<ImageCropperHandle>`                        | —                    |

O `ref` expõe `{ crop, reset }`. O `crop()` devolve `Promise<Blob | null>`.

!!! tip "Exporta os pixels originais, não o preview"
    O recorte é lido do tamanho **natural** da imagem via canvas. Uma foto de 4000 px
    recortada num preview de 320 px sai com a resolução do original, não com a do
    preview — que é o erro mais comum em cropper caseiro.

    Use `maxSize` pra limitar: uma foto de 12 MP recortada pra um avatar de 96 px são
    megabytes de desperdício.

!!! check "Nunca sai borda vazia"
    A imagem é sempre **clampada pra cobrir o frame**, em pan e em zoom. É o outro
    defeito clássico: arrastar ou dar zoom-out até o frame mostrar fundo, e aí a faixa
    transparente (ou preta) fica assada no arquivo exportado. Aqui é impossível por
    construção — inclusive ao dar zoom-out, quando um offset que era legal deixa de
    ser.

!!! info "Teclado de igual peso"
    A área de recorte é focável. **Setas** movem (com `Shift` movem 4×), **`+`/`−`**
    dão zoom, **`0`** centraliza. Roda do mouse também dá zoom. Um cropper que só
    funciona arrastando exclui quem navega por teclado.

!!! warning "`crop()` devolve `null`, não lança"
    Antes da imagem carregar, ou se o navegador recusar o encode, o retorno é `null`.
    Um handler de submit não precisa de `try/catch` — precisa checar o retorno.

!!! note "`File`/`Blob` viram object URL, e ele é revogado"
    Trocar de foto ou desmontar o componente revoga a URL anterior. Sem isso, cada
    re-escolha de foto vazaria a anterior pelo resto da vida do documento.

## `SignaturePad`

> **Quando usar**: coletar assinatura de próprio punho — comprovante de entrega, ordem de serviço, termo de aceite. Em campo, no celular, com o dedo.

Canvas com captura por `pointer` (mouse, dedo e caneta pelo mesmo caminho). Os traços são guardados como **listas de pontos** e o canvas é redesenhado a partir delas — é isso que torna o `undo` possível: canvas guarda pixel, não histórico, então remover o último traço significa repintar o resto.

```tsx
import { Button, SignaturePad, type SignaturePadHandle } from "tempest-react-sdk";
import { useRef, useState } from "react";

export function AssinaturaDaEntrega({ entregaId }: { entregaId: string }) {
  const pad = useRef<SignaturePadHandle>(null);
  const [vazio, setVazio] = useState(true);

  async function enviar() {
    const blob = await pad.current?.toBlob("image/png");
    if (!blob) return;
    const form = new FormData();
    form.append("assinatura", blob, `${entregaId}.png`);
    await api.post(`/entregas/${entregaId}/assinatura`, form);
  }

  return (
    <>
      <SignaturePad
        label="Assinatura do cliente"
        width={360}
        height={180}
        onEmptyChange={setVazio}
      />
      <Button disabled={vazio} onClick={enviar}>Confirmar entrega</Button>
    </>
  );
}
```

| Prop            | Tipo                        | Default       | O que faz                                                     |
| --------------- | --------------------------- | ------------- | ------------------------------------------------------------- |
| `width`         | `number`                    | `400`         | Largura da superfície em px CSS.                              |
| `height`        | `number`                    | `160`         | Altura da superfície em px CSS.                               |
| `penColor`      | `string`                    | cor computada | Cor do traço. O default segue `--tempest-text`.               |
| `penWidth`      | `number`                    | `2`           | Espessura do traço.                                           |
| `disabled`      | `boolean`                   | `false`       | Bloqueia o desenho e esmaece a superfície.                    |
| `label`         | `string`                    | `"Signature"` | Nome acessível do canvas.                                     |
| `onBegin`       | `() => void`                | —             | Chamado no início de cada traço.                              |
| `onEnd`         | `(dataUrl: string) => void` | —             | Chamado ao fim de cada traço, com a imagem atual.             |
| `onEmptyChange` | `(isEmpty: boolean) => void`| —             | Chamado quando a vacuidade muda — ligue no botão de submit.    |
| `showActions`   | `boolean`                   | `true`        | Renderiza os botões Desfazer/Limpar.                          |

**Handle imperativo** (`ref`): `clear()`, `undo()`, `isEmpty()`, `toDataURL(type?, quality?)`, `toBlob(type?, quality?)`.

!!! tip "Suba `toBlob()`, não `toDataURL()`"
    Data URL é base64: ~33% mais bytes, e ainda vira string no meio do seu JSON. `toBlob()` entrega binário pronto pro `FormData`.

!!! info "Nitidez em tela de alta densidade"
    O buffer do canvas é escalado por `devicePixelRatio` e o contexto recebe o `setTransform` correspondente. Sem isso o traço sai borrado no celular — é o defeito clássico de canvas em 1x.

!!! note "A cor do traço segue o tema"
    O default lê a cor **computada** do canvas, que o CSS liga em `--tempest-text`. Assinatura desenhada no tema escuro sai clara; no claro, escura. Passe `penColor` só se precisar de tinta fixa (azul de caneta, por exemplo).

## A11y

- Sempre use `label` — screen readers anunciam o campo.
- `error` adiciona `aria-invalid="true"` + descreve via `aria-describedby`.
- `required` propaga atributo `required` nativo + indicador visual `*`.
- `PinInput` cells expõem `aria-label="Dígito N"` individuais.
- `PasswordInput.toggle` usa `aria-pressed` e label `aria-label` localizada.

## Resumo

- Escolha o controle pelo **tipo de dado** — não force um `Input` onde um `Select`, `Switch` ou `PinInput` comunica melhor a intenção.
- Todos os campos compartilham `label` / `helperText` / `error` / `required` / `size` e fazem forward de `ref` → plugam direto em `react-hook-form`.
- `error` substitui `helperText` e adiciona `aria-invalid` automaticamente — não duplique a mensagem.

Páginas relacionadas:

- [Validação de formulários](../forms.md) — `validateForm`, `useZodForm`, máscaras BR, `useViaCEP` e o wrapper `<FormField>`.
- [Layout](./layout.md) — `Form`/`FormSection`/`FormRow`/`FormActions` para estruturar os campos.
- [Ações](./actions.md) — `Button` para o submit do formulário.
- [Status & feedback](./feedback.md) — `Alert`/`Toast` para confirmar sucesso ou erro do envio.

---

# components/layout.md

# Layout

Shell completo + primitivos de espaçamento + utilitários responsivos.

## O que é esta categoria

Os componentes de layout não desenham conteúdo — eles **organizam o espaço**. Há três níveis:

1. **Shell de aplicação** (`AppShell` + `Page` + `Container`) — a moldura responsiva que segura navbar, sidebar/bottom-nav, header e conteúdo.
2. **Primitivos de espaçamento** (`Stack`, `Grid`, `Divider`, `Spacer`, `Center`, `AspectRatio`) — flex/grid declarativos sem você escrever CSS.
3. **Utilitários responsivos** (`SafeArea`, `<Show>`/`<Hide>`, `ResponsiveValue`) — adaptam o layout por breakpoint e respeitam notches/barras do sistema.

**Quando usar:** prefira esses primitivos a `<div style={{ display: "flex" }}>` ad-hoc. Eles usam os tokens de spacing do SDK (escala 4px), são responsivos por construção e mantêm o espaçamento consistente entre apps.

!!! tip "Componha de fora pra dentro"
    Pense `AppShell` → `Container` → `Page` → `Stack`/`Grid` → conteúdo. Cada camada tem uma responsabilidade única; empilhá-las dá um layout responsivo completo sem nenhuma media query manual.

## `AppShell`

**Quando usar:** como a moldura raiz de um app com navegação persistente (dashboard, painel admin). Para uma landing page simples, um `Container` basta.

Composer: navbar + sidebar (desktop) / bottomNav (mobile) + main + footer responsivo.

```tsx
<AppShell
    navbar={<Navbar logo={<Brand />} actions={<UserMenu />} />}
    sidebar={<Sidebar items={...} value={tab} onChange={setTab} />}
    bottomNav={<BottomNavigation items={...} value={tab} onChange={setTab} />}
    footer={<Footer />}
    sidebarBreakpoint="md"
>
    <Page title="Dashboard">
        {content}
    </Page>
</AppShell>;
```

Comportamento responsivo:

- **>= `sidebarBreakpoint`**: navbar + sidebar + main + footer.
- **< `sidebarBreakpoint`**: navbar + main + bottomNav + footer (sidebar ocultado).

| Prop                | Tipo                           | Default |
| ------------------- | ------------------------------ | ------- |
| `navbar`            | `ReactNode`                    | —       |
| `sidebar`           | `ReactNode`                    | —       |
| `bottomNav`         | `ReactNode`                    | —       |
| `footer`            | `ReactNode`                    | —       |
| `sidebarBreakpoint` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"`  |

## `Page`

Page wrapper com header (`eyebrow` + `title` + `description` + `actions`) + `toolbar` + `content` + `footer`.

```tsx
<Page
    eyebrow="Vendas"
    title="Pedidos"
    description="Acompanhe seus pedidos em tempo real"
    actions={
        <>
            <Button variant="ghost" leftIcon={<Download />}>Exportar</Button>
            <Button leftIcon={<Plus />}>Novo</Button>
        </>
    }
    toolbar={<OrderFilters />}
    footer={<Pagination ... />}
>
    <Table {...} />
</Page>;
```

| Prop          | Tipo        | Default |
| ------------- | ----------- | ------- |
| `title`       | `ReactNode` | —       |
| `eyebrow`     | `ReactNode` | —       |
| `description` | `ReactNode` | —       |
| `actions`     | `ReactNode` | —       |
| `toolbar`     | `ReactNode` | —       |
| `footer`      | `ReactNode` | —       |
| `padded`      | `boolean`   | `true`  |

## `Container`

Max-width wrapper.

```tsx
<Container size="lg">
  <Page title="Settings">...</Page>
</Container>
```

| `size`   | Max-width |
| -------- | --------- |
| `"sm"`   | `640px`   |
| `"md"`   | `768px`   |
| `"lg"`   | `1024px`  |
| `"xl"`   | `1280px`  |
| `"full"` | `100%`    |

## `Stack`

**Quando usar:** o primitivo padrão para empilhar elementos em uma dimensão (coluna ou linha) com espaçamento uniforme. Para grade 2D use `Grid`.

Flex vertical ou horizontal com `gap`, `align`, `justify`, `wrap`. Aceita `ResponsiveValue` em `direction` e `gap`.

```tsx
<Stack direction="vertical" gap={4}>
  <Card>One</Card>
  <Card>Two</Card>
</Stack>;

<Stack direction={{ base: "vertical", md: "horizontal" }} gap={{ base: 2, md: 4 }}>
  <Card>Mobile stacks, desktop side-by-side</Card>
</Stack>;
```

| Prop        | Tipo                                                | Default      |
| ----------- | --------------------------------------------------- | ------------ |
| `direction` | `"vertical" \| "horizontal"` (ou `ResponsiveValue`) | `"vertical"` |
| `gap`       | `number \| string` (ou `ResponsiveValue`)           | `2` (8px)    |
| `align`     | `"start" \| "center" \| "end" \| "stretch"`         | —            |
| `justify`   | `"start" \| "center" \| "end" \| "between"`         | —            |
| `wrap`      | `boolean`                                           | `false`      |

`gap` numérico mapeia para escala 4px (`2 → 8px`, `4 → 16px`).

## `Grid`

CSS Grid wrapper.

```tsx
<Grid columns={3} gap={4}>
  <Card>1</Card>
  <Card>2</Card>
  <Card>3</Card>
</Grid>;

<Grid columns={{ base: 1, sm: 2, lg: 4 }} gap={3}>
  {items.map((it) => (
    <Stat key={it.id} {...it} />
  ))}
</Grid>;

<Grid columns="2fr 1fr" gap={6}>
  <Article />
  <Sidebar />
</Grid>;
```

| Prop      | Tipo                                      | Default |
| --------- | ----------------------------------------- | ------- |
| `columns` | `number \| string` (ou `ResponsiveValue`) | `2`     |
| `gap`     | `number \| string`                        | `4`     |

`columns` numérico → `repeat(N, minmax(0, 1fr))`. String passa direto pra `grid-template-columns`.

!!! tip "Colunas responsivas sem media query"
    `columns={{ base: 1, sm: 2, lg: 4 }}` é a forma idiomática de uma grade que vira lista no mobile e abre colunas no desktop. O `minmax(0, 1fr)` evita o overflow clássico de células com conteúdo largo (texto longo, `<pre>`).

## `Divider`

Separador horizontal/vertical com label opcional.

```tsx
<Divider />;
<Divider variant="dashed" />;
<Divider orientation="vertical" />;
<Divider align="center">OU</Divider>;
```

| Prop          | Tipo                                   | Default        |
| ------------- | -------------------------------------- | -------------- |
| `orientation` | `"horizontal" \| "vertical"`           | `"horizontal"` |
| `variant`     | `"solid" \| "dashed" \| "dotted"`      | `"solid"`      |
| `align`       | `"start" \| "center" \| "end"` (label) | `"center"`     |

## `Spacer`

Flex push.

```tsx
<Stack direction="horizontal">
  <Button>Cancelar</Button>
  <Spacer />
  <Button variant="primary">Salvar</Button>
</Stack>
```

| Prop   | Tipo                   | Default  |
| ------ | ---------------------- | -------- |
| `axis` | `"both" \| "x" \| "y"` | `"both"` |

## `Center`

Centraliza children horizontal/vertical/ambos.

```tsx
<Center axis="both" minHeight="100vh">
  <Spinner />
</Center>
```

| Prop        | Tipo                                   | Default  |
| ----------- | -------------------------------------- | -------- |
| `axis`      | `"both" \| "horizontal" \| "vertical"` | `"both"` |
| `minHeight` | `number \| string`                     | —        |
| `fullWidth` | `boolean`                              | `true`   |

## `AspectRatio`

Preserva proporção pra media.

```tsx
<AspectRatio ratio={16 / 9}>
  <img src="/cover.jpg" alt="" style={{ width: "100%", height: "100%", objectFit: "cover" }} />
</AspectRatio>;

<AspectRatio ratio={1}>
  <video src="/clip.mp4" autoPlay loop muted />
</AspectRatio>;
```

| Prop    | Tipo     | Default  |
| ------- | -------- | -------- |
| `ratio` | `number` | `16 / 9` |

Usa CSS `aspect-ratio` nativo. Compatível com todos navegadores modernos.

## `SafeArea`

Padding por edge usando `env(safe-area-inset-*)`.

```tsx
<SafeArea edges={["top", "bottom"]}>
  <App />
</SafeArea>
```

| Prop     | Tipo                                            | Default                           |
| -------- | ----------------------------------------------- | --------------------------------- |
| `edges`  | `("top" \| "right" \| "bottom" \| "left")[]`    | `["top","right","bottom","left"]` |
| `inline` | `boolean` (`display: contents` em vez de block) | `false`                           |

Componentes que já cuidam de safe-area automaticamente: `Navbar` (top), `BottomNavigation`/`BottomSheet` (bottom), `Modal.fullscreen` (todos), `Toast` (top+bottom).

!!! warning "Não empilhe `SafeArea` em quem já trata"
    Se você já usa `Navbar`/`BottomNavigation`/`Toast`, não envolva-os de novo em `SafeArea` — o padding dobra e cria um vão visível. Use `SafeArea` só em superfícies custom (um sheet ou overlay próprio).

## `<Show>` / `<Hide>`

**Quando usar:** trocar de árvore inteira por breakpoint (nav desktop vs. mobile, por exemplo). Para apenas ocultar via CSS sem desmontar, prefira CSS responsivo — `<Show>`/`<Hide>` desmontam o componente do DOM.

Conditional render baseado em breakpoint. SSR-safe — primeiro render usa `xs` (mobile first), re-renderiza ao client.

```tsx
<Show above="md"><DesktopNav /></Show>
<Hide above="md"><MobileNav /></Hide>
<Show below="lg"><Banner>Promo</Banner></Show>
<Show only={["sm", "md"]}><TabletOnlyHint /></Show>
```

| Prop    | Tipo                              |
| ------- | --------------------------------- |
| `above` | `Breakpoint` (xs/sm/md/lg/xl/2xl) |
| `below` | `Breakpoint`                      |
| `only`  | `Breakpoint \| Breakpoint[]`      |

`only` sobrescreve `above`/`below` quando setado.

## Responsive values

`Stack.direction`, `Grid.columns`, `Form.layout` aceitam `ResponsiveValue<T>`:

```ts
type ResponsiveValue<T> = T | { base?: T; sm?: T; md?: T; lg?: T; xl?: T; "2xl"?: T };
```

Falls back para o último valor definido por breakpoint cascading.

## A11y geral

- `Page.title` é `<h1>` — apenas um por página para hierarquia correta.
- `AppShell` envolve em `<main>` semântico.
- `<Show>`/`<Hide>` renderizam `null` no servidor + ajustam no client (no SEO impact, primeira tinta pode flickerizar).

## Resumo

- Componha de fora pra dentro: `AppShell` → `Container` → `Page` → `Stack`/`Grid` → conteúdo.
- Use os primitivos (`Stack`/`Grid`/`Spacer`/`Center`) em vez de CSS flex/grid ad-hoc — eles usam os tokens de spacing (escala 4px) e são responsivos por construção.
- `direction`/`columns`/`layout` aceitam `ResponsiveValue` → layout responsivo sem escrever media query.
- `SafeArea` só em superfícies custom; `Navbar`/`BottomNavigation`/`Toast`/`Modal.fullscreen` já tratam o notch.

Páginas relacionadas:

- [Navegação](./navigation.md) — `Navbar`, `Sidebar`, `BottomNavigation` que preenchem os slots do `AppShell`.
- [Entrada de dados](./inputs.md) — `Form`/`FormSection`/`FormRow`/`FormActions` para estruturar campos dentro de um `Page`.
- [Dados](./data.md) — `Table`/`DataTable`/`Pagination` que vivem no conteúdo de um `Page`.
- [App Providers](../app-providers.md) e [Roteamento](../routing.md) — a glue que envolve o `AppShell`.

---

# components/navigation.md

# Navegação

Top bars, side navs, bottom nav, tabs, breadcrumbs, paginação, segmented control.

## O que é esta categoria

Componentes que ajudam o usuário a **se localizar e se mover** pelo app. Eles se dividem por escopo:

- **Navegação primária** (entre seções do app): `Navbar` (topo), `Sidebar` (lateral desktop), `BottomNavigation` (rodapé mobile) — tipicamente os três slots de um `AppShell`.
- **Navegação local** (dentro de uma tela): `Tabs`, `SegmentedControl`, `Stepper`.
- **Orientação e travessia**: `Breadcrumbs` (onde estou) e `Pagination` (próxima/anterior em listas).

**Quando usar:** escolha pelo escopo — não use `Tabs` para navegar entre rotas de nível superior (isso é `Navbar`/`Sidebar`), nem `Navbar` para alternar visões de uma mesma tela (isso é `Tabs`/`SegmentedControl`).

!!! tip "Padrão responsivo Sidebar + BottomNavigation"
    A combinação idiomática: `Sidebar` dentro de `<Show above="md">` no desktop e `BottomNavigation` dentro de `<Hide above="md">` no mobile, ambos compartilhando o mesmo `value`/`onChange`. O `AppShell` já faz essa troca automaticamente quando você passa os dois slots.

## `Navbar`

**Quando usar:** barra superior persistente com marca + ações globais (busca, avatar, notificações). É a navegação de mais alto nível.

App bar superior. Três slots (`logo` / `nav` / `actions`). Sticky por padrão.

```tsx
<Navbar
  logo={<img src="/logo.svg" alt="App" />}
  nav={
    <>
      <NavLink to="/orders">Pedidos</NavLink>
      <NavLink to="/products">Produtos</NavLink>
    </>
  }
  actions={
    <>
      <Button variant="ghost" iconOnly aria-label="Buscar">
        <Search />
      </Button>
      <Avatar src={user.photo} />
    </>
  }
/>
```

| Prop       | Tipo                                      | Default     |
| ---------- | ----------------------------------------- | ----------- |
| `logo`     | `ReactNode`                               | —           |
| `nav`      | `ReactNode`                               | —           |
| `actions`  | `ReactNode`                               | —           |
| `sticky`   | `boolean`                                 | `true`      |
| `tone`     | `"surface" \| "primary" \| "transparent"` | `"surface"` |
| `bordered` | `boolean`                                 | `true`      |

**Safe-area**: aplica `padding-top: max(space-3, env(safe-area-inset-top))` automático.

## `AppBar`

**Quando usar:** app bar **mobile-first de PWA** — o padrão "voltar + título + ação" que toda tela de detalhe repete. Use `AppBar` em apps mobile/PWA; use `Navbar` quando precisar do nav horizontal de desktop (três slots).

Layout em grade: slot **leading** (botão voltar + marca) · **título** (`<h1>`) · **actions** (à direita). Sticky + safe-area por padrão. O botão voltar é acessível e, sem `onBack`, cai em `window.history.back()` — com router, passe `onBack={() => navigate(-1)}`.

```tsx
// Tela de detalhe: voltar + ação
<AppBar
  title="Perfil"
  showBack
  onBack={() => navigate(-1)}
  actions={
    <Button variant="ghost" iconOnly aria-label="Ajustes" onClick={openSettings}>
      <Settings />
    </Button>
  }
/>

// Tela inicial: marca à esquerda, sem voltar
<AppBar brand="Famachapp" actions={<Avatar src={user.photo} />} />

// Título centralizado (estilo iOS)
<AppBar title="Histórico" showBack centered />
```

| Prop        | Tipo                                      | Default     |
| ----------- | ----------------------------------------- | ----------- |
| `title`     | `ReactNode`                               | —           |
| `leading`   | `ReactNode` (substitui voltar + marca)    | —           |
| `showBack`  | `boolean`                                 | `false`     |
| `onBack`    | `() => void`                              | `history.back()` |
| `backLabel` | `string` (aria-label do botão)            | `"Go back"` |
| `backIcon`  | `ReactNode`                               | seta ←      |
| `brand`     | `ReactNode`                               | —           |
| `actions`   | `ReactNode`                               | —           |
| `centered`  | `boolean`                                 | `false`     |
| `sticky`    | `boolean`                                 | `true`      |
| `tone`      | `"surface" \| "primary" \| "transparent"` | `"surface"` |
| `bordered`  | `boolean`                                 | `true`      |
| `safeArea`  | `boolean`                                 | `true`      |

!!! tip "Customização visual"
    O SDK entrega só o layout + comportamento. Cor, altura e tipografia saem dos tokens `--tempest-*` (sobrescreva no `:root`). Para um ícone/menu customizado no lado direito, passe qualquer node em `actions`; para substituir o lado esquerdo inteiro (ex.: avatar no lugar do voltar), use `leading`.

!!! warning "A barra some ao rolar?"
    Quase nunca é a `AppBar` — é uma linha do CSS global do seu app:

    ```css
    /* ❌ o clamp horizontal que mata o sticky */
    body {
        overflow-x: hidden;
    }

    /* ✅ clampa igual, sem virar scroll container */
    html,
    body {
        overflow-x: clip;
    }
    ```

    `overflow-x: hidden` no `body` força o `overflow-y` computado a virar `auto` — regra do CSS, não bug de browser — e com isso o `body` vira **scroll container**. Todo elemento sticky passa a se prender ao scrollport do `body` em vez do viewport, e esse scrollport rola junto com o documento. Medido no Chromium a 390px, numa página longa: a barra ficou em `top: -900px` depois de rolar 900px. Ou seja, fora da tela.

    No desktop o sintoma quase não aparece, porque as telas costumam caber sem rolagem. No Chrome Android a barra de URL que encolhe transforma qualquer tela em tela longa — e aí some sempre.

    O `clip` precisa estar nos **dois** elementos: com ele só no `html`, ou só no `body`, o documento continua arrastando na horizontal.

    Em desenvolvimento a própria `AppBar` avisa no console quando detecta esse CSS. 💡

## `Sidebar`

Side nav desktop. `items: SidebarEntry[]` (itens, seções e separadores), slots
`header`/`footer`, modo `collapsed` (apenas ícones).

```tsx
const [tab, setTab] = useState("home");
const [collapsed, setCollapsed] = useState(false);

<Sidebar
  header={<Brand collapsed={collapsed} />}
  items={[
    { key: "home", label: "Início", icon: <Home /> },
    { key: "orders", label: "Pedidos", icon: <Package />, badge: 3 },
    { key: "settings", label: "Ajustes", icon: <Cog /> },
  ]}
  value={tab}
  onChange={setTab}
  footer={<Button onClick={() => setCollapsed(!collapsed)}>Colapsar</Button>}
  collapsed={collapsed}
  width={240}
  collapsedWidth={64}
/>;
```

| Prop             | Tipo                           | Default |
| ---------------- | ------------------------------ | ------- |
| `header`         | `ReactNode`                    | —       |
| `items`          | `SidebarEntry[]`               | —       |
| `value`          | `string`                       | —       |
| `onChange`       | `(key: string) => void`        | —       |
| `footer`         | `ReactNode`                    | —       |
| `collapsed`      | `boolean`                      | `false` |
| `width`          | `number \| string` (px ou CSS) | `240`   |
| `collapsedWidth` | `number \| string`             | `64`    |

```ts
type SidebarItem = { key, label, icon?, badge?, disabled?, href? };

type SidebarEntry =
  | ({ type?: "item" } & SidebarItem)
  | { type: "section"; key: string; label: ReactNode }
  | { type: "separator"; key: string };
```

`type` é opcional no ramo do item, então **um `SidebarItem[]` continua sendo um
`SidebarEntry[]` válido** — nenhum call site existente muda uma linha.

### Agrupando em seções

Lista corrida funciona até uns 8 itens. Acima disso vira parede: 16 telas sem
rótulo deixam "Diagnósticos" visualmente colado em "Campanhas", e o admin perde a
âncora que dizia em que parte do painel ele está.

Uma seção abre um grupo, e os itens seguintes pertencem a ele **até a próxima
seção ou separador**:

```tsx
import { useState } from "react";
import { Sidebar } from "tempest-react-sdk";
import { Activity, BarChart3, FileText, Settings, Users } from "lucide-react";

function AdminNav() {
  const [tab, setTab] = useState("overview");

  return (
    <Sidebar
      items={[
        { type: "section", key: "monitoring", label: "Monitoramento" },
        { key: "overview", label: "Visão Geral", icon: <BarChart3 /> },
        { key: "activity", label: "Atividade", icon: <Activity /> },
        { key: "reports", label: "Relatórios", icon: <FileText /> },

        { type: "section", key: "users", label: "Gestão de Usuários" },
        { key: "users", label: "Usuários", icon: <Users /> },

        { type: "separator", key: "before-admin" },
        { key: "settings", label: "Configurações", icon: <Settings /> },
      ]}
      value={tab}
      onChange={setTab}
    />
  );
}
```

O que sai no HTML:

```html
<nav aria-label="Navegação lateral">
  <div role="group" aria-labelledby="…-monitoring">
    <div id="…-monitoring" role="presentation">Monitoramento</div>
    <!-- Visão Geral, Atividade, Relatórios -->
  </div>
  <div role="group" aria-labelledby="…-users">…</div>
  <hr />
  <div><!-- Configurações, solto --></div>
</nav>
```

!!! info "Por que `role="group"` e não um item estilizado"
    Usar `disabled: true` como rótulo renderiza `<button disabled>`: passa
    visualmente com CSS, mas o leitor de tela anuncia **"botão indisponível"** no
    lugar de um cabeçalho, e a entrada continua na árvore de navegação. Com
    `role="group"` + `aria-labelledby`, o anúncio é "Monitoramento, grupo, 3
    itens" — sem inventar um botão que não existe.

!!! tip "Itens antes da primeira seção ficam soltos"
    É o comportamento de sempre. Quem não usa seção nenhuma não vê `role="group"`
    no HTML — a lista sai exatamente como saía antes.

!!! warning "No modo `collapsed` o rótulo sai de vista, não da árvore"
    64px não cabe "Gestão de Usuários", então o rótulo vira `clip-path: inset(50%)`
    e o grupo ganha uma linha divisória no topo. O `aria-labelledby` **continua**
    apontando pra ele, para o leitor de tela não perder a estrutura quando o admin
    recolhe a coluna.

### Item que é link

`href` renderiza um `<a>` em vez de `<button>`, e `onChange` continua disparando
no clique:

```tsx
<Sidebar
  items={[{ key: "overview", label: "Visão Geral", href: "/overview" }]}
  value={tab}
  onChange={setTab}
/>
```

Com isso o middle-click abre em outra aba, o ctrl-click funciona, "copiar endereço
do link" aparece no menu de contexto, e o leitor de tela anuncia link em vez de
botão. Item `disabled` ignora o `href` e continua `<button disabled>`: âncora não
tem estado desabilitado, e tirar o `href` pra simular um deixaria um link que se
anuncia acionável e não é.

**Mobile**: esconda com `<Show above="md">` e exponha via `<Drawer>` no menu hambúrguer.

## `NavigationRail`

**Quando usar:** coluna de navegação vertical e compacta para desktop/tablet — uma alternativa mais estreita à `Sidebar` quando você só precisa de ícones empilhados sobre rótulos curtos. Cada item empilha ícone sobre o label; o ativo recebe `aria-current="page"`.

`items: NavigationRailItem[]`, slots `header`/`footer` e controle de rótulos via `labelVisibility`.

```tsx
import { useState } from "react";
import { NavigationRail, FloatingActionButton } from "tempest-react-sdk";
import { Home, Inbox, Settings, Plus } from "lucide-react";

function AppRail() {
  const [tab, setTab] = useState("home");

  return (
    <NavigationRail
      header={<FloatingActionButton icon={<Plus />} aria-label="Novo" position="none" />}
      items={[
        { key: "home", label: "Início", icon: <Home /> },
        { key: "inbox", label: "Caixa", icon: <Inbox />, badge: 3 },
        { key: "settings", label: "Ajustes", icon: <Settings /> },
      ]}
      value={tab}
      onChange={setTab}
      labelVisibility="all"
    />
  );
}
```

| Prop              | Tipo                              | Default |
| ----------------- | --------------------------------- | ------- |
| `items`           | `NavigationRailItem[]`            | —       |
| `value`           | `string` (key selecionada)        | —       |
| `onChange`        | `(key: string) => void`           | —       |
| `header`          | `ReactNode` (topo — ex.: FAB)     | —       |
| `footer`          | `ReactNode` (rodapé)              | —       |
| `labelVisibility` | `"all" \| "selected" \| "none"`   | `"all"` |

Tipo `NavigationRailItem = { key, label, icon?, badge?, disabled? }`.

!!! tip "`labelVisibility` controla a densidade"
    Use `"selected"` para mostrar só o rótulo do item ativo (rail mais estreito) ou `"none"` para um rail puramente de ícones. Em telas pequenas prefira a `BottomNavigation`.

## `BottomNavigation`

Tab bar fixa no rodapé pra mobile. 3-5 items.

```tsx
<Show below="md">
  <BottomNavigation
    items={[
      { key: "home", label: "Início", icon: <Home /> },
      { key: "search", label: "Buscar", icon: <Search /> },
      { key: "cart", label: "Carrinho", icon: <Cart />, badge: cartCount },
      { key: "profile", label: "Perfil", icon: <User /> },
    ]}
    value={tab}
    onChange={setTab}
  />
</Show>
```

| Prop         | Tipo                           | Default |
| ------------ | ------------------------------ | ------- |
| `items`      | `BottomNavigationItem[]` (3–5) | —       |
| `value`      | `string`                       | —       |
| `onChange`   | `(key: string) => void`        | —       |
| `showLabels` | `boolean`                      | `true`  |

Tipo `BottomNavigationItem = { key, label, icon?, badge?, disabled? }`.

**Safe-area**: aplica `padding-bottom: env(safe-area-inset-bottom)` automático.

## `Tabs`

**Quando usar:** alternar entre painéis de conteúdo **dentro de uma mesma tela** (visão geral / detalhes / logs). Não use para navegar entre rotas.

Tabs controlled/uncontrolled. Fade-edge mask em overflow horizontal. Variantes visuais via `variant` (`"underline"` default ou `"pill"`).

```tsx
<Tabs
  value={tab}
  onChange={setTab}
  items={[
    { key: "overview", label: "Visão geral", content: <Overview /> },
    { key: "details", label: "Detalhes", content: <Details /> },
    { key: "logs", label: "Logs", content: <Logs /> },
  ]}
/>
```

| Prop           | Tipo                    | Default |
| -------------- | ----------------------- | ------- |
| `items`        | `TabItem[]`             | —       |
| `value`        | `string` (controlled)   | —       |
| `defaultValue` | `string` (uncontrolled) | —       |
| `onChange`     | `(key: string) => void` | —       |

## `Stepper`

**Quando usar:** mostrar progresso em um fluxo linear de múltiplas etapas (checkout, onboarding, wizard). É indicador de progresso, não um seletor — controle o `current` pela lógica do fluxo.

Wizard linear com steps numerados. `orientation` aceita `"horizontal"` (default) ou `"vertical"`.

```tsx
<Stepper
  current={step}
  steps={[
    { key: "info", label: "Informações" },
    { key: "payment", label: "Pagamento" },
    { key: "review", label: "Revisão" },
  ]}
/>
```

## `Breadcrumbs`

**Quando usar:** sinalizar a posição em uma hierarquia profunda (Home › Pedidos › #12345) e permitir voltar a níveis anteriores. Dispensável em apps de 1-2 níveis.

Navegação hierárquica.

```tsx
<Breadcrumbs
  items={[{ label: "Home", href: "/" }, { label: "Pedidos", href: "/orders" }, { label: "#12345" }]}
/>
```

**A11y**: último item é marcado com `aria-current="page"`.

## `Pagination`

**Quando usar:** percorrer listas grandes em páginas discretas (resultados de busca, tabelas). Para feeds contínuos, prefira scroll infinito (`VirtualList` + `usePoll`/Query).

Numeric com siblings + page-size opcional.

!!! note "`page` é 1-indexed, `total` é contagem de itens"
    `total` é o número **de itens** (não de páginas) — o componente calcula as páginas a partir de `pageSize`. Lembre de resetar `page` para `1` quando o filtro muda, senão você pode parar numa página que não existe mais.

```tsx
<Pagination
  page={page}
  pageSize={size}
  total={data?.total ?? 0}
  onPageChange={setPage}
  onPageSizeChange={setSize}
  siblings={1}
/>
```

| Prop               | Tipo                     | Default |
| ------------------ | ------------------------ | ------- |
| `page`             | `number` (1-indexed)     | —       |
| `pageSize`         | `number`                 | —       |
| `total`            | `number` (item count)    | —       |
| `onPageChange`     | `(page: number) => void` | —       |
| `onPageSizeChange` | `(size: number) => void` | —       |
| `siblings`         | `number` (vizinhos)      | `1`     |

## `SegmentedControl`

**Quando usar:** alternar entre 2-5 visões mutuamente exclusivas da mesma tela (lista/grade/mapa). É mais compacto que `Tabs` e não tem painéis de conteúdo embutidos — você troca a view manualmente pelo `value`.

iOS-style pill bar (2-5 opções).

```tsx
<SegmentedControl
  value={view}
  onChange={setView}
  options={[
    { value: "list", label: "Lista", icon: <List /> },
    { value: "grid", label: "Grade", icon: <Grid /> },
    { value: "map", label: "Mapa", icon: <Map /> },
  ]}
  size="md"
  fullWidth
/>
```

| Prop        | Tipo                       | Default |
| ----------- | -------------------------- | ------- |
| `options`   | `SegmentedControlOption[]` | —       |
| `value`     | `string`                   | —       |
| `onChange`  | `(value: string) => void`  | —       |
| `size`      | `"sm" \| "md" \| "lg"`     | `"md"`  |
| `fullWidth` | `boolean`                  | `false` |

**A11y**: `role="radiogroup"` + `role="radio"` com `aria-checked`.

## A11y geral

- Navbar: use `<nav>` (já incluso); marque ativos com `aria-current="page"`.
- Sidebar/BottomNavigation: keyboard accessible — Tab cycle entre items.
- Tabs: setas ←→ trocam tab quando focada.
- Breadcrumbs: separador (`/`) é decorativo (aria-hidden).

!!! warning "Marque o item ativo com `aria-current`"
    Navbar/Sidebar/BottomNavigation precisam que o item da rota atual carregue `aria-current="page"` — sem isso, leitores de tela não anunciam onde o usuário está. `Breadcrumbs` já faz isso no último item automaticamente.

## Resumo

- Escolha pelo **escopo**: `Navbar`/`Sidebar`/`NavigationRail`/`BottomNavigation` para navegar entre seções; `Tabs`/`SegmentedControl`/`Stepper` para mover-se dentro de uma tela.
- O trio `Navbar` + `Sidebar` + `BottomNavigation` são os slots do `AppShell` — deixe ele orquestrar a troca desktop/mobile.
- `Pagination` para listas paginadas; `Breadcrumbs` para hierarquias profundas.
- Sempre marque o item ativo com `aria-current="page"` na navegação primária.

Páginas relacionadas:

- [Layout](./layout.md) — `AppShell` que compõe `Navbar`/`Sidebar`/`BottomNavigation` + `Page`.
- [Sobreposições](./overlay.md) — `Drawer` para expor a `Sidebar` no menu hambúrguer mobile.
- [Dados](./data.md) — `Table`/`DataTable` que usam `Pagination` no rodapé.
- [Roteamento](../routing.md) — `defineRoutes`/`<AppRouter>`/`<RouteGuard>` que ligam a navegação às rotas.

---

# components/overlay.md

# Overlay

Componentes de **overlay** interrompem o fluxo principal para focar a atenção numa tarefa isolada — eles aparecem _por cima_ da página, com backdrop, e capturam o foco até serem fechados. Use-os quando o usuário precisa lidar com algo (editar um registro, confirmar, escolher uma opção) sem perder o contexto da tela de fundo, mas sem poder ignorá-lo.

Os três compartilham o mesmo motor (portal para `document.body` + backdrop + Esc + focus trap + scroll lock) e diferem só na ancoragem e na vocação:

- `Modal` — centralizado, propósito geral.
- `Drawer` — ancorado a uma borda, painel lateral.
- `BottomSheet` — ancorado embaixo, mobile-first.

!!! info "Tudo é portalado"
    Os três renderizam em `document.body`, fora da árvore do componente que os invoca. Isso evita problemas de `overflow: hidden` / `z-index` de ancestrais, mas significa que estilos com escopo no pai não vazam para dentro do overlay.

## `Modal`

> **Quando usar**: um fluxo central que pausa o contexto — criar/editar um registro, um wizard curto, um form que exige atenção total.

Portal + backdrop + Esc + focus trap + scroll lock.

```tsx
const [open, setOpen] = useState(false);

<Modal
  open={open}
  onClose={() => setOpen(false)}
  title="Editar perfil"
  size="md"
  footer={
    <FormActions>
      <Button variant="ghost" onClick={() => setOpen(false)}>
        Cancelar
      </Button>
      <Button onClick={save}>Salvar</Button>
    </FormActions>
  }
>
  <ProfileForm />
</Modal>;
```

| Prop                 | Tipo                                             | Default |
| -------------------- | ------------------------------------------------ | ------- |
| `open`               | `boolean`                                        | —       |
| `onClose`            | `() => void`                                     | —       |
| `title`              | `ReactNode`                                      | —       |
| `size`               | `"sm" \| "md" \| "lg" \| "xl" \| "2xl" \| "3xl"` | `"md"`  |
| `footer`             | `ReactNode`                                      | —       |
| `fullscreen`         | `boolean` (ocupa 100dvh independente do size)    | `false` |
| `fullscreenOnMobile` | `boolean` (vira fullscreen abaixo de 640px)      | `false` |
| `dismissOnBackdrop`  | `boolean`                                        | `true`  |
| `dismissOnEsc`       | `boolean`                                        | `true`  |

!!! tip "Safe-area em fullscreen"
    Em `fullscreen` o Modal aplica `env(safe-area-inset-*)` em todos os edges, respeitando notch e barra de gestos. Use `fullscreenOnMobile` para um modal denso virar tela cheia abaixo de 640px em vez de espremer num cartão minúsculo.

**A11y**: `role="dialog"` + `aria-modal="true"` + `aria-labelledby` quando `title` é string. O foco fica preso dentro do dialog e volta ao trigger ao fechar.

## `Drawer`

> **Quando usar**: um painel lateral persistente que complementa a tela de fundo — filtros, detalhes de um item, navegação secundária. Encosta numa borda em vez de centralizar.

Side drawer. `placement: left/right/top/bottom`. Auto-switch pra bottom-sheet em mobile via `mobilePlacement`.

```tsx
<Drawer
  open={open}
  onClose={() => setOpen(false)}
  placement="right"
  mobilePlacement="bottom" // vira bottom sheet em mobile
  title="Filtros"
  showHandle // drag indicator visual quando vira bottom-sheet
  footer={<Button onClick={apply}>Aplicar</Button>}
>
  <FilterForm />
</Drawer>
```

| Prop              | Tipo                                                          | Default   |
| ----------------- | ------------------------------------------------------------- | --------- |
| `open`            | `boolean`                                                     | —         |
| `onClose`         | `() => void`                                                  | —         |
| `placement`       | `"left" \| "right" \| "top" \| "bottom"`                      | `"right"` |
| `mobilePlacement` | `"left" \| "right" \| "top" \| "bottom"` (override em mobile) | —         |
| `title`           | `ReactNode`                                                   | —         |
| `footer`          | `ReactNode`                                                   | —         |
| `showHandle`      | `boolean` (drag indicator estilo bottom-sheet)                | `false`   |
| `hideCloseButton` | `boolean`                                                     | `false`   |
| `closeOnBackdrop` | `boolean`                                                     | `true`    |
| `closeOnEsc`      | `boolean`                                                     | `true`    |

!!! note "Drawer dimensiona pelo conteúdo, não por `size`"
    Diferente do `Modal`, o `Drawer` não tem prop `size` — a largura/altura segue o conteúdo (e o CSS do placement). Para um painel mobile-first com largura total e altura limitada, prefira `BottomSheet` ou `mobilePlacement="bottom"`.

## `BottomSheet`

> **Quando usar**: ações ou escolhas mobile-first que sobem do rodapé — menu de compartilhar, opções de um item, seletor curto. É o padrão nativo de iOS/Android.

Modal ancorado na borda inferior — slide-up via animation. Otimizado pra mobile.

```tsx
<BottomSheet open={open} onClose={() => setOpen(false)} title="Compartilhar">
  <Stack gap={3}>
    <Button leftIcon={<MessageCircle />}>WhatsApp</Button>
    <Button leftIcon={<Mail />}>Email</Button>
    <Button leftIcon={<Link />}>Copiar link</Button>
  </Stack>
</BottomSheet>
```

| Prop                | Tipo         | Default |
| ------------------- | ------------ | ------- |
| `open`              | `boolean`    | —       |
| `onClose`           | `() => void` | —       |
| `title`             | `ReactNode`  | —       |
| `showHandle`        | `boolean`    | `true`  |
| `dismissOnBackdrop` | `boolean`    | `true`  |
| `dismissOnEsc`      | `boolean`    | `true`  |

!!! tip "Safe-area automática"
    O `BottomSheet` adiciona `padding-bottom` respeitando `env(safe-area-inset-bottom)`, então os controles não ficam escondidos atrás da barra de gestos em iPhones/Androids modernos.

**Diferença vs `Drawer`**: BottomSheet é sempre slide-up + max-height 90dvh + drag handle. Use `Drawer` quando precisa de placement variável (lateral/topo) ou de comportamento diferente entre desktop e mobile.

!!! warning "Cuidado ao desligar `closeOnBackdrop`/`dismissOnBackdrop`"
    Desabilitar o dismiss por backdrop ou Esc prende o usuário no overlay até concluir a tarefa. Faça isso só em forms verdadeiramente críticos (perda de dados) — caso contrário sempre ofereça uma saída clara, ou a navegação por teclado vira uma armadilha.

## `ModalsManager`

> **Quando usar**: quando você quer abrir modais e confirmações de forma **imperativa** — direto de um handler, sem montar `<Modal open={...}>` controlado por estado local em cada lugar. Ideal para confirmações de exclusão e diálogos pontuais.

`<ModalsProvider>` monta uma vez perto da raiz e gerencia uma pilha de modais; `useModals()` expõe a API imperativa sobre os componentes `Modal` e `ConfirmDialog` já existentes.

```tsx
import { ModalsProvider, useModals, Button } from "tempest-react-sdk";

// raiz do app
<ModalsProvider>
  <App />
</ModalsProvider>;

// em qualquer componente abaixo do provider
function DeleteButton({ id }: { id: string }) {
  const modals = useModals();
  return (
    <Button
      variant="danger"
      onClick={() =>
        modals.confirm({
          title: "Excluir item",
          message: "Esta ação não pode ser desfeita. Continuar?",
          confirmLabel: "Excluir",
          danger: true,
          onConfirm: async () => {
            await fetch(`/api/items/${id}`, { method: "DELETE" });
          },
        })
      }
    >
      Excluir
    </Button>
  );
}
```

| `useModals()` | Assinatura                                | O que faz                                |
| ------------- | ----------------------------------------- | ---------------------------------------- |
| `open`        | `(options: OpenModalOptions) => string`   | Empilha um modal de conteúdo; retorna o id. |
| `confirm`     | `(options: ConfirmModalOptions) => string` | Empilha um `ConfirmDialog`; retorna o id. |
| `close`       | `(id: string) => void`                    | Remove o modal com aquele id.            |
| `closeAll`    | `() => void`                              | Remove todos os modais da pilha.         |

!!! info "Construído sobre os componentes existentes"
    `open` renderiza um `Modal` e `confirm` renderiza um `ConfirmDialog` — você herda focus trap, scroll lock, Esc e backdrop sem configurar nada. O `onConfirm` pode ser `async`: o dialog mostra `loading` até a promise resolver e fecha sozinho ao terminar.

!!! warning "Precisa do `<ModalsProvider>` acima"
    `useModals()` lança um erro se chamado fora de um `<ModalsProvider>`. Monte o provider uma única vez perto da raiz do app.

## `Lightbox`

> **Quando usar**: visualizar foto em tela cheia com navegação — galeria de imóvel, anexos de uma ocorrência, fotos de vistoria.

Overlay `role="dialog" aria-modal` com foco preso dentro e rolagem da página travada. Só a imagem atual é montada; as vizinhas são **pré-carregadas** via `Image()`, então apertar `→` não pisca um quadro vazio.

```tsx
import { Lightbox } from "tempest-react-sdk";
import { useState } from "react";

export function GaleriaDaVistoria({ fotos }: { fotos: { url: string; descricao: string }[] }) {
  const [aberto, setAberto] = useState(false);
  const [indice, setIndice] = useState(0);

  return (
    <>
      <div className="tempest-grid-auto">
        {fotos.map((foto, i) => (
          <button key={foto.url} type="button" onClick={() => { setIndice(i); setAberto(true); }}>
            <img src={foto.url} alt={foto.descricao} className="tempest-aspect-square" />
          </button>
        ))}
      </div>

      <Lightbox
        open={aberto}
        items={fotos.map((f) => ({ src: f.url, alt: f.descricao }))}
        index={indice}
        onIndexChange={setIndice}
        onClose={() => setAberto(false)}
      />
    </>
  );
}
```

| Prop             | Tipo                       | Default             | O que faz                                     |
| ---------------- | -------------------------- | ------------------- | --------------------------------------------- |
| `items`          | `LightboxItem[]`           | —                   | Imagens da galeria.                           |
| `open`           | `boolean`                  | —                   | Controla a visibilidade.                      |
| `index`          | `number`                   | `0`                 | Índice exibido.                               |
| `onIndexChange`  | `(index: number) => void`  | —                   | Passar isso torna o índice **controlado**.     |
| `onClose`        | `() => void`               | —                   | Chamado no `Esc` e no botão fechar.            |
| `showThumbnails` | `boolean`                  | `true` se > 1 item  | Faixa de miniaturas.                           |
| `showCounter`    | `boolean`                  | `true`              | Contador `3 / 12`.                             |
| `loop`           | `boolean`                  | `true`              | Circula nas pontas.                            |

`LightboxItem = { src, alt, caption?, thumbnail? }` — `alt` é **obrigatório**: galeria de imagem sem rótulo é inutilizável em leitor de tela.

**Teclado**: `Esc` fecha · `←`/`→` navegam · `Home`/`End` vão pras pontas.

!!! note "`loop` é `true` de propósito"
    Em visualizador de foto, esbarrar num fim morto na última imagem é lido como bug mais vezes do que como limite. Passe `loop={false}` quando a ordem tem significado (um passo-a-passo, por exemplo) — aí os botões de navegação desabilitam nas pontas.

## A11y geral

- **Focus trap**: Tab circula apenas dentro do dialog. Restaura o foco no trigger ao fechar.
- **Scroll lock**: `body.overflow = "hidden"` enquanto aberto.
- **Esc** fecha (`Modal`/`BottomSheet`: `dismissOnEsc={false}`; `Drawer`: `closeOnEsc={false}`).
- **`aria-modal="true"`** indica para leitores de tela que o resto da página está bloqueado.
- **Backdrop**: clicks fecham (`Modal`/`BottomSheet`: `dismissOnBackdrop={false}`; `Drawer`: `closeOnBackdrop={false}`).

## Resumo

| Componente    | Ancoragem        | Vocação                           | Prop de dismiss                    |
| ------------- | ---------------- | --------------------------------- | ---------------------------------- |
| `Modal`       | centralizado     | fluxos centrais (criar/editar)    | `dismissOnBackdrop`/`dismissOnEsc` |
| `Drawer`      | borda (variável) | painéis laterais persistentes     | `closeOnBackdrop`/`closeOnEsc`     |
| `BottomSheet` | borda inferior   | ações mobile-first (compartilhar) | `dismissOnBackdrop`/`dismissOnEsc` |
| `ModalsManager` | pilha (imperativa) | abrir modais/confirmações via código | `useModals().close`/`closeAll`     |

Para confirmação destrutiva pré-montada, use o `ConfirmDialog` ([actions](./actions.md)), construído sobre o `Modal`. Para abrir modais imperativamente (sem estado local), use `<ModalsProvider>` + `useModals()`.

Relacionados: [actions](./actions.md) (`ConfirmDialog`, botões no `footer`) · [inputs](./inputs.md) (forms dentro do overlay) · [navigation](./navigation.md) (`Drawer` como nav secundária).

---

# components/utility.md

# Utilitários & headless

Componentes pequenos e focados: alguns renderizam pedaços de UI (`Money`, `RelativeTime`, `CopyButton`), outros são **headless** — controlam comportamento/lógica sem opinar sobre o visual (`Portal`, `ClickOutside`, `For`). Todos importados de `tempest-react-sdk`.

## Display

### `CopyButton`

Botão que copia uma string pra clipboard e mostra um estado transiente de "copiado".

```tsx
import { CopyButton } from "tempest-react-sdk";

<CopyButton value="npm i tempest-react-sdk" />;

<CopyButton value={token} timeout={3000} onCopied={() => toast("Token copiado")}>
  Copiar token
</CopyButton>;
```

| Prop       | Tipo          | Default             | Notas                                                        |
| ---------- | ------------- | ------------------- | ------------------------------------------------------------ |
| `value`    | `string`      | —                   | Texto escrito no clipboard.                                  |
| `timeout`  | `number` (ms) | `2000`              | Quanto tempo o estado "copiado" fica ativo.                  |
| `children` | `ReactNode`   | `"Copy"`/`"Copied"` | Label fixo nos dois estados; sem `children` o texto alterna. |
| `onCopied` | `() => void`  | —                   | Chamado após escrita bem-sucedida.                           |

Estende `ButtonHTMLAttributes`. Falha de clipboard é silenciada; o timer é limpo no unmount.

### `RelativeTime`

Renderiza uma data como string relativa ("5 min atrás") dentro de um `<time>` semântico com `dateTime` legível por máquina.

```tsx
import { RelativeTime } from "tempest-react-sdk";

<RelativeTime date={post.createdAt} />; // pt-BR
<RelativeTime date={post.createdAt} locale="en" />;
```

| Prop     | Tipo                       | Default | Notas                        |
| -------- | -------------------------- | ------- | ---------------------------- |
| `date`   | `Date \| string \| number` | —       | Instante a renderizar.       |
| `locale` | `"pt" \| "en"`             | `"pt"`  | `"pt"` mapeia pra `"pt-BR"`. |

Estende `HTMLAttributes<HTMLTimeElement>`.

### `Money`

Renderiza um valor monetário **em centavos** como string de moeda localizada num `<span>`.

```tsx
import { Money } from "tempest-react-sdk";

<Money cents={1990} />; // "R$ 19,90"
<Money cents={500} currency="USD" locale="en-US" />; // "$5.00"
```

| Prop       | Tipo     | Default   | Notas                              |
| ---------- | -------- | --------- | ---------------------------------- |
| `cents`    | `number` | —         | Valor na menor unidade (centavos). |
| `currency` | `string` | `"BRL"`   | Código ISO 4217.                   |
| `locale`   | `string` | `"pt-BR"` | Locale BCP 47 usado na formatação. |

Estende `HTMLAttributes<HTMLSpanElement>`. Internamente divide `cents` por 100 e usa `Intl.NumberFormat`.

### `TruncateText`

Limita o texto a um número fixo de linhas via CSS line-clamp, com reticências no overflow.

```tsx
import { TruncateText } from "tempest-react-sdk";

<TruncateText lines={2}>{longDescription}</TruncateText>;
```

| Prop       | Tipo        | Default | Notas                                              |
| ---------- | ----------- | ------- | -------------------------------------------------- |
| `lines`    | `number`    | `1`     | Linhas antes de clampar (`--tempest-clamp-lines`). |
| `children` | `ReactNode` | —       | Conteúdo a clampar.                                |

Estende `HTMLAttributes<HTMLDivElement>`.

### `VisuallyHidden`

Conteúdo escondido visualmente mas acessível a leitores de tela — o padrão `sr-only`.

```tsx
import { VisuallyHidden } from "tempest-react-sdk";

<button>
  <Icon />
  <VisuallyHidden>Fechar</VisuallyHidden>
</button>;
```

| Prop | Tipo                          | Default  | Notas                             |
| ---- | ----------------------------- | -------- | --------------------------------- |
| `as` | `keyof JSX.IntrinsicElements` | `"span"` | Elemento intrínseco a renderizar. |

Estende `HTMLAttributes<HTMLElement>`.

---

## Headless / lógicos

Sem CSS próprio: encapsulam comportamento e te deixam fornecer a marcação.

### `Portal`

Renderiza os filhos em outra parte da árvore DOM via React portal — ideal pra overlays que precisam escapar de `overflow`/stacking contexts.

```tsx
import { Portal } from "tempest-react-sdk";

<Portal>
  <div className="toast">Salvo!</div>
</Portal>;

<Portal container={drawerRoot}>{menu}</Portal>;
```

| Prop        | Tipo              | Default         | Notas                                   |
| ----------- | ----------------- | --------------- | --------------------------------------- |
| `children`  | `ReactNode`       | —               | Conteúdo renderizado através do portal. |
| `container` | `Element \| null` | `document.body` | Nó DOM alvo.                            |

!!! info "SSR-safe"
    Renderiza `null` no servidor e no primeiro render do cliente; monta o portal só depois da hidratação.

### `ClickOutside`

Embrulha os filhos num `<div>` e dispara `onOutside` quando um `mousedown`/`touchstart` acontece fora da subárvore. Útil pra fechar popovers e menus.

```tsx
import { ClickOutside } from "tempest-react-sdk";

<ClickOutside onOutside={() => setOpen(false)}>
  <Menu />
</ClickOutside>;
```

| Prop        | Tipo                                        | Default | Notas                         |
| ----------- | ------------------------------------------- | ------- | ----------------------------- |
| `onOutside` | `(event: MouseEvent \| TouchEvent) => void` | —       | Chamado em interação externa. |
| `children`  | `ReactNode`                                 | —       | Conteúdo dentro da fronteira. |

Estende `HTMLAttributes<HTMLDivElement>` (passa props pro `<div>` wrapper).

### `ConditionalWrapper`

Embrulha os filhos com `wrapper` só quando `condition` é `true` — evita duplicar a subárvore só pra adicionar um wrapper opcional (link, tooltip, boundary).

```tsx
import { ConditionalWrapper } from "tempest-react-sdk";

<ConditionalWrapper condition={Boolean(href)} wrapper={(children) => <a href={href}>{children}</a>}>
  <CardBody />
</ConditionalWrapper>;
```

| Prop        | Tipo                                 | Default | Notas                              |
| ----------- | ------------------------------------ | ------- | ---------------------------------- |
| `condition` | `boolean`                            | —       | Quando `true`, aplica o `wrapper`. |
| `wrapper`   | `(children: ReactNode) => ReactNode` | —       | Função de embrulho.                |
| `children`  | `ReactNode`                          | —       | Conteúdo que pode ser embrulhado.  |

### `For`

Renderizador de listas tipado e JSX-friendly, com fallback pra coleção vazia. O tipo do item é inferido de `each`.

```tsx
import { For } from "tempest-react-sdk";

<For each={users} fallback={<p>Nenhum usuário</p>}>
  {(user, index) => (
    <li key={user.id}>
      {index + 1}. {user.name}
    </li>
  )}
</For>;
```

| Prop       | Tipo                                    | Default | Notas                                 |
| ---------- | --------------------------------------- | ------- | ------------------------------------- |
| `each`     | `readonly T[]`                          | —       | Coleção a iterar.                     |
| `children` | `(item: T, index: number) => ReactNode` | —       | Render por item.                      |
| `fallback` | `ReactNode`                             | `null`  | Renderizado quando `each` está vazio. |

### `ErrorText`

Mensagem de erro de campo de formulário como `<p role="alert">`. Renderiza `null` quando não há children — pode ficar fixo abaixo do campo e só aparece quando há erro.

```tsx
import { ErrorText } from "tempest-react-sdk";

<input aria-invalid={Boolean(error)} />
<ErrorText>{error}</ErrorText>;
```

| Prop       | Tipo        | Default | Notas                                               |
| ---------- | ----------- | ------- | --------------------------------------------------- |
| `children` | `ReactNode` | —       | Mensagem; `null`/`""`/`false` → não renderiza nada. |

Estende `HTMLAttributes<HTMLParagraphElement>`. Estilizado com o token `--tempest-danger`.

---

## Mídia / conteúdo

### `Image`

`<img>` com lazy loading nativo e fallback de uma tentativa.

```tsx
import { Image } from "tempest-react-sdk";

<Image src={user.avatarUrl} fallback="/avatar-placeholder.png" alt={user.name} />;
```

| Prop       | Tipo      | Default | Notas                                       |
| ---------- | --------- | ------- | ------------------------------------------- |
| `src`      | `string`  | —       | Fonte primária.                             |
| `fallback` | `string`  | —       | Fonte trocada uma vez se a primária falhar. |
| `alt`      | `string`  | —       | Texto alternativo (obrigatório).            |
| `lazy`     | `boolean` | `true`  | `true` → `loading="lazy"`; `false` → eager. |

Estende `ImgHTMLAttributes` (sem `src`). O fallback é guardado pra não entrar em loop de `onError`.

### `DataList`

Lista genérica tipada que renderiza um `<ul>` com um `<li>` por item, com slot de vazio.

```tsx
import { DataList } from "tempest-react-sdk";

<DataList
  items={notifications}
  keyExtractor={(n) => n.id}
  renderItem={(n) => <NotificationRow notification={n} />}
  empty={<p>Sem novidades</p>}
/>;
```

| Prop           | Tipo                                           | Default | Notas                                  |
| -------------- | ---------------------------------------------- | ------- | -------------------------------------- |
| `items`        | `readonly T[]`                                 | —       | Coleção a renderizar.                  |
| `renderItem`   | `(item: T, index: number) => ReactNode`        | —       | Conteúdo de cada `<li>`.               |
| `keyExtractor` | `(item: T, index: number) => string \| number` | índice  | Key estável por item.                  |
| `empty`        | `ReactNode`                                    | —       | Renderizado quando `items` está vazio. |

Estende `HTMLAttributes<HTMLUListElement>`.

### `DescriptionList`

`<dl>` semântico de pares termo/descrição, com estilização chave/valor baseada em tokens.

```tsx
import { DescriptionList } from "tempest-react-sdk";

<DescriptionList
  items={[
    { term: "Pedido", description: "#1042" },
    { term: "Status", description: <Badge variant="success">Pago</Badge> },
    { term: "Total", description: <Money cents={1990} /> },
  ]}
/>;
```

| Prop    | Tipo                    | Default | Notas                |
| ------- | ----------------------- | ------- | -------------------- |
| `items` | `DescriptionListItem[]` | —       | Pares `<dt>`/`<dd>`. |

`DescriptionListItem = { term: ReactNode; description: ReactNode }`. Estende `HTMLAttributes<HTMLDListElement>`.

### `CodeBlock`

Amostra de código somente leitura: cores de sintaxe, número de linha opcional, botão de copiar.

```tsx
import { CodeBlock } from "tempest-react-sdk";

<CodeBlock code={snippet} language="ts" filename="src/api.ts" showLineNumbers />
<CodeBlock code={log} language="bash" maxHeight={280} />
```

| Prop              | Tipo                | Default | Notas                                                       |
| ----------------- | ------------------- | ------- | ----------------------------------------------------------- |
| `code`            | `string`            | —       | A fonte. Linhas em branco nas pontas são aparadas.           |
| `language`        | `string`            | —       | Gramática ou apelido. Desconhecido renderiza como texto.     |
| `filename`        | `ReactNode`         | —       | Mostrado no cabeçalho.                                       |
| `showLineNumbers` | `boolean`           | `false` | Numera as linhas.                                            |
| `highlightLines`  | `number[]`          | —       | Linhas 1-based marcadas como o ponto do trecho.              |
| `copyable`        | `boolean`           | `true`  | Botão de copiar no cabeçalho.                                |
| `maxHeight`       | `number \| string`  | —       | Limita a altura; o corpo rola.                               |
| `wrap`            | `boolean`           | `false` | Quebra linha em vez de rolar na horizontal.                  |
| `label`           | `string`            | —       | Nome acessível da região.                                    |

Gramáticas: `typescript` · `javascript` · `tsx` · `jsx` · `json` · `css` · `html` · `bash` · `python` · `sql`, com apelidos (`ts`, `js`, `sh`, `py`, `scss`, `xml`, `shell`, `zsh`, `jsonc`…).

!!! warning "É um scanner, não um parser — e isso é um teto escolhido"
    O realce reconhece comentário, string, número, palavra-chave e pontuação **por padrão de texto**. Ele não sabe nada de escopo, tipo ou gramática. Um parser de verdade por linguagem é uma dependência do tamanho do resto do SDK, e o ganho — acertar os cantos raros de um trecho de documentação — é pequeno. Onde não tem certeza ele emite `plain`, que sai como texto normal em vez de sair **errado**. Linguagem desconhecida vira um bloco sem cor, que é resultado normal e nunca erro.

!!! info "O `<pre>` é sempre focável"
    Um bloco de código rola e não tem nada focável dentro. Sem parada de tabulação, quem navega por teclado vê a barra de rolagem e não tem como movê-la — o foco nunca pousa onde as setas rolariam. É o único contêiner de rolagem do SDK onde a parada é incondicional em vez de medida: um trecho de código existe pra ser alcançado, lido e selecionado por conta própria. Os outros ([`Table`](./data.md), `VirtualList`, `ScrollArea`) só ganham a parada enquanto de fato transbordam.

!!! tip "Número de linha é decoração — e some do clipboard"
    Ele é `aria-hidden` (um leitor anunciando "um const dois import" não ajuda) e `user-select: none`. Selecionar o bloco com o mouse e copiar devolve a fonte, sem os números. Verificado no browser: a seleção do `<code>` inteiro sai idêntica ao original.

!!! note "As cores de sintaxe têm tokens próprios, não a rampa de chart"
    `--tempest-code-*`. A rampa de chart é validada pro piso de **marca** (3:1); isso aqui é texto e precisa de **4,5:1**. Medindo a rampa como texto ela falha nos dois modos — uma palavra-chave deu 3,47:1 na superfície escura, uma string 2,03:1 na clara. Cada token de código foi resolvido em OKLCH contra **os dois fundos** em que pode cair: a superfície do bloco e a linha marcada depois que o realce compõe sobre ela. Ver [tokens de estilo](../styles.md).

### `QRCode`

Um símbolo QR codificado **no browser** e desenhado em SVG. Sem dependência e sem ida a serviço de imagem — um gerador remoto entregaria o conteúdo (link de pagamento, token de sessão, convite) a um terceiro.

```tsx
import { QRCode } from "tempest-react-sdk";

<QRCode value="https://tempest.dev" />
<QRCode value={pixPayload} level="H" size={220} label="QR do Pix — R$ 42,00" />
```

| Prop         | Tipo                        | Default            | Notas                                                     |
| ------------ | --------------------------- | ------------------ | --------------------------------------------------------- |
| `value`      | `string`                    | —                  | O conteúdo. UTF-8 quando não é só dígito ou caixa alta.    |
| `size`       | `number`                    | `160`              | Lado renderizado em px, zona de silêncio incluída.         |
| `level`      | `"L" \| "M" \| "Q" \| "H"`  | `"M"`              | Correção de erro: ~7% · ~15% · ~25% · ~30% recuperável.    |
| `margin`     | `number`                    | `4`                | Zona de silêncio em módulos.                               |
| `color`      | `string`                    | `#000000`          | Cor dos módulos.                                           |
| `background` | `string`                    | `#ffffff`          | Cor do fundo.                                              |
| `label`      | `string`                    | `QR code: {value}` | Nome acessível.                                            |

!!! danger "Preto no branco nos dois temas — de propósito"
    É a única parte do SDK que **ignora os tokens de tema**. Leitor de QR espera escuro sobre claro, e os que lidam com símbolo invertido fazem isso devagar e sem confiança. Ligar os módulos em `--tempest-text` inverteria eles no dark mode e deixaria um símbolo claro sobre o fundo branco — que não lê como nada. Um QR que combina com a página escura e escaneia na terceira tentativa é pior que um que parece colado por cima. Só mexa em `color`/`background` com um leitor na mão pra testar.

!!! tip "O modo muda o tamanho do símbolo, e o tamanho muda a facilidade de leitura"
    O encoder escolhe automaticamente o modo mais denso que o conteúdo permite: **numérico** empacota 3 dígitos em 10 bits, **alfanumérico** 2 caracteres em 11, **byte** gasta 8 bits por byte. Um telefone em dígitos puros cabe num símbolo visivelmente mais grosso que o mesmo número em bytes — e módulo maior é módulo mais fácil de escanear. Se você controla o formato do payload, caixa alta e sem acento vale tamanho de símbolo.

!!! warning "Zona de silêncio abaixo de 4 módulos é onde leitor começa a errar"
    O `margin` default segue a norma. Diminuir pra ganhar espaço na tela é a otimização que mais custa taxa de leitura.

!!! info "Nível de correção não é qualidade — é tolerância a dano"
    `L` basta pra QR de tela, que ninguém amassa. `Q`/`H` valem quando o símbolo vai pra papel, adesivo, vitrine ou crachá: recuperam ~25%/~30% dos codewords, então rasgo, dobra e sujeira ainda leem. O custo é um símbolo maior pro mesmo conteúdo.

!!! note "Leitor de tela não escaneia"
    Por isso o `aria-label` default **nomeia o conteúdo** (`QR code: https://…`) em vez de dizer só "QR code". Quando o payload é opaco — um BR Code do Pix, por exemplo — passe `label` descrevendo o que ele faz, e ofereça o mesmo dado em texto ou botão de copiar ao lado.

#### Conteúdo grande demais

Um payload que não cabe nem numa versão 40 lança `QRCapacityError` em vez de desenhar um símbolo truncado que escaneia errado. É erro de programação, não estado a renderizar — se o conteúdo vem do usuário, valide antes ou embrulhe num [`ErrorBoundary`](../error-boundary.md).

```tsx
import { encodeQR, QRCapacityError } from "tempest-react-sdk";

try {
  encodeQR(payload, { level: "H" });
} catch (error) {
  if (error instanceof QRCapacityError) {
    // error.length (bytes) e error.level
  }
}
```

`encodeQR(value, { level, minVersion })` devolve a matriz crua (`modules`, `size`, `version`, `mode`, `mask`) pra quem precisa desenhar por conta própria — canvas, PDF, etiqueta térmica. `matrixToPath(matrix, margin)` gera o mesmo `d` que o componente usa.

---

## Recap

- **Display**: `CopyButton` (clipboard + estado transiente), `RelativeTime` (`<time>` relativo), `Money` (centavos → moeda), `TruncateText` (line-clamp), `VisuallyHidden` (sr-only).
- **Headless/lógicos**: `Portal` (SSR-safe), `ClickOutside`, `ConditionalWrapper`, `For` (lista tipada com fallback), `ErrorText` (erro de campo `role="alert"`).
- **Mídia/conteúdo**: `Image` (lazy + fallback), `DataList` (`<ul>` genérico), `DescriptionList` (`<dl>` termo/valor), `CodeBlock` (amostra de código com realce), `QRCode` (símbolo QR em SVG, codificado no browser).
- Componentes "display" e "conteúdo" usam tokens `--tempest-*`; os headless não trazem CSS — você fornece a marcação.

## Veja também

- [Utilitários](../utilities.md) — `Money`/`RelativeTime` são as versões em componente de helpers de formatação.
- [Dados](./data.md) — `Table`/`VirtualList` para coleções maiores.

---

# cookbook.md

# Cookbook — Receitas

Esta página é um **livro de receitas**: cada seção responde a um "eu quero fazer X"
com **um exemplo completo e copiável** (imports inclusos, sem `...`), seguido de
algumas explicações. As receitas combinam vários módulos do `tempest-react-sdk` em
fluxos que apps Tempest repetem o tempo todo. 🚀

!!! info "Pré-requisitos comuns"
    Todas as receitas assumem que você já instalou o SDK e importou o CSS uma vez no
    entrypoint do app:

    ```bash
    npm install tempest-react-sdk react react-dom react-router
    ```

    ```tsx
    // src/main.tsx
    import "tempest-react-sdk/styles.css";
    ```

    `react`, `react-dom` e `react-router` (`^7 || ^8`) são **peer dependencies** —
    os três carregam contexto React, então precisam vir do app em uma cópia só. O
    resto (`zod`, `zustand`, `dexie`, `react-hook-form`, `@tanstack/react-query`,
    `lucide-react`) é instalado junto como dependência direta. A versão publicada
    mais recente está na [página do npm](https://www.npmjs.com/package/tempest-react-sdk).

## Fluxo de autenticação completo

Você quer login persistido, rotas protegidas e um cliente HTTP que injeta o token
e desloga sozinho quando o backend responde 401. Junte `createAuthStore`,
`<RouteGuard>` e `createApiClient`.

```tsx
// src/stores/auth.ts
import { createAuthStore, createSelectors } from "tempest-react-sdk";

export interface User {
  id: string;
  name: string;
  email: string;
}

export const useAuth = createSelectors(
  createAuthStore<User>({ name: "app-auth", storage: "local" }),
);

// src/lib/api.ts
import { createApiClient } from "tempest-react-sdk";
import { useAuth } from "@/stores/auth";

export const api = createApiClient({
  baseURL: import.meta.env.VITE_API_URL,
  getToken: () => useAuth.getState().token,
  onUnauthorized: () => useAuth.getState().logout(),
});

// src/pages/Login.tsx
import { useState } from "react";
import { Button, Form, FormActions, Input, useNavigate } from "tempest-react-sdk";
import { api } from "@/lib/api";
import { useAuth, type User } from "@/stores/auth";

export function Login() {
  const navigate = useNavigate();
  const setSession = useAuth.use.setSession();
  const [email, setEmail] = useState("");
  const [password, setPassword] = useState("");

  async function onSubmit(event: React.FormEvent) {
    event.preventDefault();
    const { user, token } = await api.post<{ user: User; token: string }>("/auth/login", {
      body: { email, password },
    });
    setSession({ user, token });
    navigate("/dashboard");
  }

  return (
    <Form layout="stack" gap={4} onSubmit={onSubmit}>
      <Input
        label="Email"
        type="email"
        value={email}
        onChange={(event) => setEmail(event.target.value)}
      />
      <Input
        label="Senha"
        type="password"
        value={password}
        onChange={(event) => setPassword(event.target.value)}
      />
      <FormActions align="end">
        <Button type="submit">Entrar</Button>
      </FormActions>
    </Form>
  );
}

// src/routes.tsx
import { defineRoutes, RouteGuard } from "tempest-react-sdk";
import { Login } from "@/pages/Login";
import { Dashboard } from "@/pages/Dashboard";

export const routes = defineRoutes([
  { path: "login", element: <Login /> },
  {
    path: "dashboard",
    element: (
      <RouteGuard when={useAuth.getState().isAuthenticated} redirectTo="/login">
        <Dashboard />
      </RouteGuard>
    ),
  },
]);
```

- `createAuthStore<User>` é um store Zustand persistido; `setSession`, `token`,
  `isAuthenticated` e `logout` vêm prontos. `getState()` lê o valor atual **fora**
  do React — exatamente o que o cliente HTTP e o guard precisam.
- O `createApiClient` injeta `Authorization: Bearer <token>` quando `getToken()`
  devolve string e, em um 401, chama `onUnauthorized` (aqui, `logout()`). Para
  renovar o token em vez de deslogar, adicione `refresh`/`createRefreshQueue` —
  veja [Auth](./auth.md).

!!! tip "Guard como rota vs. componente"
    Use `guard: () => useAuth.getState().isAuthenticated` direto na árvore de
    `defineRoutes` quando a rota inteira é protegida; use `<RouteGuard when={...}>`
    quando você protege um pedaço de JSX. Detalhes em [Routing](./routing.md).

## Lista paginada com busca e ordenação

Você quer uma tabela com busca, ordenação por coluna e paginação sem escrever esse
estado na mão. O `DataTable<T>` faz tudo client-side sobre os dados que você passar.

```tsx
// src/pages/Users.tsx
import { useQuery } from "@tanstack/react-query";
import { DataTable, type DataTableColumn } from "tempest-react-sdk";
import { api } from "@/lib/api";

interface User {
  id: number;
  name: string;
  email: string;
  role: string;
}

const columns: DataTableColumn<User>[] = [
  { key: "name", header: "Nome", sortable: true },
  { key: "email", header: "E-mail" },
  { key: "role", header: "Papel", sortable: true, align: "right" },
];

export function Users() {
  const { data, isLoading } = useQuery({
    queryKey: ["users"],
    queryFn: () => api.get<User[]>("/users"),
  });

  if (isLoading) return <p>Carregando…</p>;

  return (
    <DataTable
      data={data ?? []}
      columns={columns}
      searchable
      pageSize={10}
      initialSort={{ key: "name", direction: "asc" }}
      rowKey={(row) => row.id}
      emptyMessage="Nenhum usuário encontrado"
    />
  );
}
```

- `DataTable` recebe o dataset **completo** em `data` e cuida de busca,
  ordenação e paginação no cliente. Marque as colunas que podem ordenar com
  `sortable: true`; clicar no cabeçalho cicla asc → desc → sem ordenação.
- `searchable` adiciona um input acima da tabela que filtra por substring
  case-insensitive. Restrinja as colunas buscadas com `searchKeys`. Veja
  [Overlays & avançados](./components/advanced.md).

!!! note "Paginação server-side"
    Para datasets grandes, busque uma página por vez (passe `page`/`pageSize` na
    `queryFn`) e use o `Table` headless em vez do `DataTable` — assim a ordenação e a
    paginação ficam por conta do backend.

## Formulário com validação zod

Você quer um formulário validado por um schema zod, com campos brasileiros
mascarados (CPF, telefone) e mensagens de erro automáticas. Junte `useZodForm`,
`<FormProvider>` e `<FormField>`.

```tsx
// src/pages/Signup.tsx
import {
  Button,
  CPFInput,
  Form,
  FormActions,
  FormField,
  FormProvider,
  Input,
  PhoneInput,
  useZodForm,
  validateCPF,
} from "tempest-react-sdk";
import { z } from "zod";

const schema = z.object({
  name: z.string().min(2, "Informe seu nome"),
  email: z.string().email("E-mail inválido"),
  cpf: z.string().refine(validateCPF, "CPF inválido"),
  phone: z.string().min(14, "Telefone inválido"),
});

type SignupValues = z.infer<typeof schema>;

export function Signup() {
  const form = useZodForm(schema, {
    defaultValues: { name: "", email: "", cpf: "", phone: "" },
  });

  function onSubmit(values: SignupValues) {
    console.log("payload", values);
  }

  return (
    <FormProvider {...form}>
      <Form layout="stack" gap={4} onSubmit={form.handleSubmit(onSubmit)}>
        <FormField name="name" label="Nome" required>
          <Input />
        </FormField>
        <FormField name="email" label="E-mail" required>
          <Input type="email" />
        </FormField>
        <FormField name="cpf" label="CPF" required>
          <CPFInput />
        </FormField>
        <FormField name="phone" label="Telefone" required>
          <PhoneInput />
        </FormField>
        <FormActions align="end">
          <Button type="submit" loading={form.formState.isSubmitting}>
            Criar conta
          </Button>
        </FormActions>
      </Form>
    </FormProvider>
  );
}
```

- `useZodForm(schema, options)` embrulha `useForm` + `zodResolver` e **infere** o
  tipo dos valores a partir do schema — você não digita o tipo do form duas vezes.
- `<FormField name="cpf">` injeta `value`/`onChange`/`error` no controle filho via
  `Controller`, eliminando o boilerplate de `<Controller render={...} />`. Ele lê o
  `control` do `<FormProvider>` na árvore. Os inputs BR (`CPFInput`, `PhoneInput`)
  já aplicam a máscara — `validateCPF` valida os dígitos verificadores de verdade.
  Veja [Forms](./forms.md) e [Forms BR](./forms-br.md).

## Dark mode sem flash

Você quer alternar entre claro e escuro **sem o flash branco** no carregamento da
página. O segredo é rodar um script inline no `<head>` antes do CSS, com
`themeInitScript()`, e usar `ThemeProvider` + `useTheme` no app.

```html
<!-- index.html -->
<!doctype html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <script>
      // Substitua pelo retorno de themeInitScript() — lê localStorage["tempest-theme"]
      // e aplica data-tempest-theme em <html> antes da primeira pintura.
      (function () {
        try {
          var stored = localStorage.getItem("tempest-theme");
          var dark =
            stored === "dark" ||
            (stored !== "light" && matchMedia("(prefers-color-scheme: dark)").matches);
          if (dark) document.documentElement.setAttribute("data-tempest-theme", "dark");
        } catch (e) {}
      })();
    </script>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

```tsx
// src/App.tsx
import { ThemeProvider, useTheme } from "tempest-react-sdk";

function ThemeToggle() {
  const { theme, resolvedTheme, toggle } = useTheme();
  return (
    <button onClick={toggle}>
      {resolvedTheme === "dark" ? "🌙" : "☀️"} ({theme})
    </button>
  );
}

export function App() {
  return (
    <ThemeProvider defaultTheme="system">
      <ThemeToggle />
    </ThemeProvider>
  );
}
```

- O script inline é a parte que mata o flash: ele aplica `data-tempest-theme="dark"`
  em `<html>` **antes** de qualquer CSS pintar. Gere o conteúdo dele com
  `themeInitScript()` (em SSR/React, injete via
  `<script dangerouslySetInnerHTML={{ __html: themeInitScript() }} />`).
- `useTheme()` devolve `theme` (preferência crua), `resolvedTheme` (o que está
  aplicado) e `toggle()`. Em `defaultTheme="system"`, o provider reage ao
  `prefers-color-scheme` do sistema. Os tokens `--tempest-*` reagem sozinhos. Veja
  [Tema](./theme.md).

!!! tip "Usando o `AppProviders`"
    Se você usa o `<AppProviders>`, o tema já vem ligado — ajuste com
    `theme={{ defaultTheme: "dark" }}`. O script inline no `index.html` continua sendo
    necessário para o no-flash.

## Offline-first

Você quer guardar dados localmente (notificações, drafts) que sobrevivem a reload e
sincronizar com o backend quando estiver online. Junte `createOfflineStore` (Dexie)
com o cliente HTTP.

```ts
// src/stores/notifications.ts
import { createOfflineStore } from "tempest-react-sdk";
import { api } from "@/lib/api";

export type Notification = {
  message_id: string;
  owner_id: string;
  type: "NOTIFY" | "PAYMENT-SUCCESS";
  message: string;
  created_at: string;
  read: boolean;
};

export const notificationsStore = createOfflineStore<Notification, string>({
  databaseName: "TempestNotifications",
  version: 1,
  tableName: "notifications",
  indexes: "&message_id, owner_id, read, created_at",
  keyPath: "message_id",
  ownerField: "owner_id",
});

/**
 * Baixa do backend, grava no IndexedDB e devolve o que está em cache local.
 * Se a rede falhar, cai pro cache offline em vez de quebrar a UI.
 */
export async function syncNotifications(ownerId: string): Promise<Notification[]> {
  try {
    const fresh = await api.get<Notification[]>("/notifications");
    await notificationsStore.bulkPut(fresh, ownerId);
  } catch {
    // Offline ou backend indisponível — segue com o cache local.
  }
  return notificationsStore.list(ownerId, {
    orderBy: "created_at",
    reverse: true,
    limit: 50,
  });
}

// Marcar todas como lidas, localmente:
export async function markAllRead(ownerId: string): Promise<void> {
  await notificationsStore.updateMany(ownerId, { read: true });
}
```

- `createOfflineStore<T, K>` empacota Dexie com scoping por owner: toda operação
  recebe o `ownerId`, então dados de usuários diferentes nunca se misturam. A
  sintaxe de `indexes` é a do Dexie (`&` = chave primária única).
- O padrão de sync é simples: tenta o backend, grava o resultado com `bulkPut`, e
  **sempre** lê do store local no fim — assim a UI funciona online e offline com o
  mesmo código. Veja [Offline](./offline.md).

!!! warning "Não use para estado de UI volátil"
    IndexedDB é para dados que precisam **sobreviver a reload** (histórico, drafts,
    cache). Para estado de UI efêmero (spinner, aba ativa) use Zustand — é muito mais
    barato. Veja [State](./state.md).

## Paleta de comandos ⌘K

Você quer uma paleta estilo ⌘K que abre com o atalho de teclado e navega pelo app.
Junte o componente `Command`, o hook `useKeyboardShortcut` e o `useNavigate`.

```tsx
// src/components/CommandPalette.tsx
import { useState } from "react";
import { Command, useKeyboardShortcut, useNavigate, useTheme } from "tempest-react-sdk";

export function CommandPalette() {
  const [open, setOpen] = useState(false);
  const navigate = useNavigate();
  const { toggle } = useTheme();

  // ⌘K (macOS) / Ctrl+K (Windows/Linux) abre a paleta.
  useKeyboardShortcut({ key: "k", mod: true }, () => setOpen(true));

  return (
    <Command
      open={open}
      onOpenChange={setOpen}
      placeholder="Digite um comando…"
      emptyMessage="Nenhum resultado"
      items={[
        {
          id: "home",
          label: "Ir para o início",
          group: "Navegação",
          onSelect: () => navigate("/"),
        },
        {
          id: "dashboard",
          label: "Abrir dashboard",
          group: "Navegação",
          keywords: ["painel"],
          onSelect: () => navigate("/dashboard"),
        },
        {
          id: "theme",
          label: "Alternar tema",
          group: "Preferências",
          onSelect: () => toggle(),
        },
      ]}
    />
  );
}
```

- O `Command` filtra os itens por substring (em `label` + `keywords`), agrupa por
  `group`, prende o foco enquanto aberto e fecha no Escape, clique fora ou seleção.
  Cada `item.onSelect` é a ação — aqui, `navigate(...)` e `toggle()`.
- `useKeyboardShortcut({ key: "k", mod: true }, ...)` casa **Ctrl ou Cmd + K** em
  qualquer OS. O hook recebe um objeto `KeyboardShortcut` (não uma string), e por
  padrão ignora o atalho quando o foco está dentro de um input. Veja
  [Overlays & avançados](./components/advanced.md) e [Hooks](./hooks.md).

## App do zero em 1 minuto

Você quer começar um projeto novo já cabeado com providers, roteamento e store de
auth — sem montar a pirâmide na mão. Use a CLI `create-tempest-app`.

```bash
# Pasta nova — crie o diretório e scaffolde dentro dele com "."
mkdir my-app
cd my-app
npx -p tempest-react-sdk create-tempest-app .
npm install
cp .env.example .env
npm run dev            # http://127.0.0.1:5173
```

O `src/App.tsx` gerado já liga tudo com `<AppProviders>` (React Query + tema +
error boundary) por fora e o `<AppRouter>` por dentro:

```tsx
// src/App.tsx — gerado pela CLI
import { AppProviders, AppRouter } from "tempest-react-sdk";
import { routes } from "@/routes";

export function App() {
  return (
    <AppProviders errorBoundary={{ fallback: <p>Something went wrong.</p> }}>
      <AppRouter routes={routes} fallback={<p>Loading…</p>} />
    </AppProviders>
  );
}
```

- A CLI é o **`bin` do próprio `tempest-react-sdk`** — não um pacote separado. O
  app gerado já nasce com `createAuthStore` + `createSelectors`, `defineRoutes`
  (com rota `lazy` + guard) e `createApiClient`, cada arquivo demonstrando um
  recurso do SDK.
- `<AppProviders>` aninha `ErrorBoundary → QueryProvider → ThemeProvider →
I18nProvider → children` na ordem certa, e o `<AppRouter>` monta router +
  `<Suspense>` + `<Routes>` a partir do array de rotas. Veja
  [Scaffold](./scaffold.md), [App Providers](./app-providers.md) e
  [Routing](./routing.md).

!!! tip "Já tem um projeto?"
    Dentro de um projeto existente, rode `npm install tempest-react-sdk` e
    `npx create-tempest-app .` — a CLI gera `src/` + configs **no diretório atual**,
    preservando arquivos que já existem e mesclando o `package.json`.

## Recap

- **Auth completo**: `createAuthStore` (sessão persistida) + `createApiClient`
  (token + `onUnauthorized` → `logout`) + `<RouteGuard>`/`guard` para proteger
  rotas.
- **Listas**: `DataTable<T>` resolve busca + ordenação + paginação client-side
  sobre os dados de um `useQuery`.
- **Formulários**: `useZodForm` + `<FormProvider>` + `<FormField>` + inputs BR
  mascarados dão validação tipada com schema único.
- **Dark mode**: script inline (`themeInitScript`) no `<head>` mata o flash;
  `ThemeProvider` + `useTheme().toggle()` alternam.
- **Offline**: `createOfflineStore` (Dexie, owner-scoped) + um sync "tenta backend,
  cai pro cache".
- **Paleta ⌘K**: `Command` + `useKeyboardShortcut({ key: "k", mod: true })` +
  `useNavigate`.
- **App do zero**: `create-tempest-app` gera tudo cabeado com `<AppProviders>` +
  `<AppRouter>`.

---

# data-provider.md

# Data Provider (CRUD)

Camada de CRUD no estilo [Refine](https://refine.dev) fiada nas convenções de paginação e endpoints do [`tempest-fastapi-sdk`](https://pypi.org/project/tempest-fastapi-sdk/). Em vez de escrever uma `queryFn` à mão para cada lista, cada `getOne`, cada mutation de criar/editar/excluir, você descreve **o recurso** (`"posts"`, `"users"`) e o SDK monta a URL, serializa paginação/ordenação/filtros e invalida o cache certo no sucesso.

!!! info "Por que um data provider em cima do `createApiClient` + TanStack Query?"
    O [`createApiClient`](./http.md) entrega fetch tipado e a [Query](./query.md) entrega cache. O que falta é a **cola repetitiva**: traduzir `{ page, sort, filters }` para `?page=&size=&order_by=&ascending=`, escolher PATCH vs PUT, e lembrar de invalidar a lista depois de criar. O data provider centraliza esse padrão uma vez, alinhado às convenções do backend FastAPI. Você troca dezenas de `useQuery`/`useMutation` quase idênticos por `useList("posts")`, `useCreate("posts")`, etc.

## Quando usar

- Telas de CRUD: listagens paginadas, detalhe, formulários de criar/editar, botão de excluir.
- Backends que seguem as convenções do `tempest-fastapi-sdk` (paginação offset `BasePaginationSchema`, endpoints `/{resource}` e `/{resource}/{id}`).
- Quando você quer cache + invalidação automática sem escrever `queryKey`/`invalidateQueries` à mão em cada tela.

Para chamadas que **não** são CRUD de recurso (RPC, agregações, endpoints custom), continue usando o [`createApiClient`](./http.md) direto.

## `createDataProvider`

Crie o provider uma vez, a partir do seu `apiClient`, e passe-o para a árvore via `<TempestDataProvider>`:

```ts
import { createApiClient, createDataProvider } from "tempest-react-sdk";

const apiClient = createApiClient({
  baseURL: import.meta.env.VITE_API_URL,
});

export const dataProvider = createDataProvider(apiClient);
```

`createDataProvider(client, options?)` recebe o cliente HTTP e um objeto opcional de overrides. Os defaults já casam com o `tempest-fastapi-sdk`:

| Opção                | Default        | Para que serve                                                                              |
| -------------------- | -------------- | ------------------------------------------------------------------------------------------ |
| `pageParam`          | `"page"`       | Nome do query-param do número da página.                                                    |
| `sizeParam`          | `"size"`       | Nome do query-param do tamanho da página.                                                   |
| `sortFieldParam`     | `"order_by"`   | Nome do query-param do campo de ordenação.                                                  |
| `sortOrderParam`     | `"ascending"`  | Nome do query-param da direção da ordenação.                                                |
| `sortOrderAsBoolean` | `true`         | `true` → emite booleano (`order:"asc"` vira `true`). `false` → emite `"asc"`/`"desc"`.      |
| `updateMethod`       | `"patch"`      | Método HTTP usado por `update` (`"patch"` ou `"put"`).                                       |
| `buildPath`          | ver abaixo     | Monta o path do recurso. Default: `id == null ? "/{resource}" : "/{resource}/{id}"`.        |

!!! note "Os defaults seguem o `tempest-fastapi-sdk`"
    `BasePaginationFilterSchema` usa `page`/`size`/`order_by`/`ascending`, e `ascending` é um booleano. Por isso `sortOrderAsBoolean` é `true` por default. Se o seu backend espera `?sort=desc` em vez de `?ascending=false`, ajuste `sortOrderParam` e `sortOrderAsBoolean`.

Exemplo com overrides — um backend que pagina com `pageSize` e ordena com `sort=field:desc` num único param:

```ts
import { createApiClient, createDataProvider } from "tempest-react-sdk";

const apiClient = createApiClient({ baseURL: import.meta.env.VITE_API_URL });

export const dataProvider = createDataProvider(apiClient, {
  sizeParam: "pageSize",
  sortOrderAsBoolean: false, // emite "asc"/"desc" literais
  updateMethod: "put", // PUT em vez de PATCH
  buildPath: (resource, id) => (id == null ? `/api/${resource}` : `/api/${resource}/${id}`),
});
```

### Como cada chamada vira uma requisição

| Método do provider                 | Requisição HTTP                                                |
| ---------------------------------- | ------------------------------------------------------------- |
| `getList("posts", params)`         | `GET /posts?page=&size=&order_by=&ascending=&...filters`      |
| `getOne("posts", id)`              | `GET /posts/{id}`                                             |
| `getMany("posts", ids)`            | `getOne` em paralelo para cada id                            |
| `create("posts", data)`            | `POST /posts`                                                 |
| `update("posts", id, data)`        | `PATCH /posts/{id}` (ou `PUT` com `updateMethod: "put"`)      |
| `deleteOne("posts", id)`           | `DELETE /posts/{id}`                                          |

## Provider na árvore

Envolva o app com `<TempestDataProvider>` passando o provider criado. Ele **precisa** estar abaixo de um [`<QueryProvider>`](./query.md) — os hooks de recurso usam o `QueryClient` por baixo:

```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { QueryProvider, TempestDataProvider } from "tempest-react-sdk";
import "tempest-react-sdk/styles.css";
import { App } from "./App";
import { dataProvider } from "./data-provider";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <QueryProvider>
      <TempestDataProvider provider={dataProvider}>
        <App />
      </TempestDataProvider>
    </QueryProvider>
  </StrictMode>,
);
```

!!! warning "`<QueryProvider>` por cima, sempre"
    `useList`/`useOne`/`useCreate`/… chamam `useQuery`/`useMutation` internamente. Sem um `<QueryProvider>` (ou outro `QueryClientProvider`) acima na árvore, eles lançam o erro do TanStack Query "No QueryClient set". E sem um `<TempestDataProvider>` acima, os hooks lançam `useDataProvider must be used within a <TempestDataProvider>`.

## Os hooks de recurso

Todos resolvem o provider via contexto — você só informa o nome do recurso e, opcionalmente, os parâmetros.

- `useList<T>(resource, params?, options?)` → `UseQueryResult<OffsetPage<T>, Error>`
- `useOne<T>(resource, id, options?)` → `UseQueryResult<T, Error>` (desabilitado enquanto `id` for `null`/`undefined`)
- `useCreate<T>(resource, options?)` → mutation; `mutate(data)`
- `useUpdate<T>(resource, options?)` → mutation; `mutate({ id, data })`
- `useDelete<T>(resource, options?)` → mutation; `mutate(id)`

As mutations já invalidam o cache certo no sucesso:

| Hook        | Invalida no `onSuccess`                          |
| ----------- | ----------------------------------------------- |
| `useCreate` | a lista do recurso                              |
| `useUpdate` | a lista **e** o registro `useOne` daquele `id`  |
| `useDelete` | a lista do recurso                              |

!!! tip "Você ainda passa opções do TanStack Query"
    Cada hook aceita um último argumento `options` que é repassado para o `useQuery`/`useMutation` por baixo (menos `queryKey`/`queryFn`/`mutationFn`, que o SDK controla). Então `staleTime`, `placeholderData`, `onError`, `onSuccess` (chamado **depois** da invalidação do SDK) continuam funcionando normalmente.

### As chaves de cache, quando você precisa delas

Os hooks montam as próprias chaves, mas invalidar de fora — depois de um
WebSocket avisar que um registro mudou, por exemplo — exige a mesma chave que
eles usaram. `listQueryKey` e `oneQueryKey` são exatamente essas:

```ts
import { useQueryClient } from "@tanstack/react-query";
import { listQueryKey, oneQueryKey } from "tempest-react-sdk";

const queryClient = useQueryClient();

queryClient.invalidateQueries({ queryKey: listQueryKey("posts") });
queryClient.invalidateQueries({ queryKey: oneQueryKey("posts", 42) });
```

`listQueryKey(resource, params?)` devolve `["data", <recurso>, "list", params]`
e `oneQueryKey(resource, id)` devolve `["data", <recurso>, "one", id]`. Montar
esse array à mão funciona até o dia em que o formato mudar — as funções não.

### O envelope `OffsetPage<T>`

`useList` resolve com o envelope de paginação offset do `tempest-fastapi-sdk` — você não mapeia nada à mão:

```ts
interface OffsetPage<T> {
  items: T[]; // as linhas da página atual
  total: number; // total de registros que casam, em todas as páginas
  page: number; // página atual (1-based)
  pages: number; // total de páginas
  size?: number; // tamanho da página (convenção fastapi-pagination)
  page_size?: number; // tamanho da página (convenção alternativa)
}
```

## Exemplo completo — recurso "posts"

Listagem paginada + ordenada + filtrada, criação via mutation, e a invalidação acontecendo sozinha:

```tsx
import { useState } from "react";
import { useList, useCreate } from "tempest-react-sdk";

interface Post {
  id: string;
  title: string;
  published: boolean;
}

export function PostsPage() {
  const [page, setPage] = useState(1);
  const [onlyPublished, setOnlyPublished] = useState(false);

  // GET /posts?page=1&size=20&order_by=created_at&ascending=false&published=true
  const { data, isLoading, isError } = useList<Post>("posts", {
    pagination: { page, pageSize: 20 },
    sort: { field: "created_at", order: "desc" },
    filters: onlyPublished ? { published: true } : undefined,
  });

  // POST /posts — invalida a lista de "posts" no sucesso, sem código extra
  const createPost = useCreate<Post>("posts");

  if (isLoading) return <p>Carregando…</p>;
  if (isError) return <p>Erro ao carregar posts.</p>;

  const pageData = data!; // OffsetPage<Post>

  return (
    <div>
      <label>
        <input
          type="checkbox"
          checked={onlyPublished}
          onChange={(e) => {
            setOnlyPublished(e.target.checked);
            setPage(1);
          }}
        />
        Só publicados
      </label>

      <button
        disabled={createPost.isPending}
        onClick={() => createPost.mutate({ title: "Novo post", published: false })}
      >
        Criar post
      </button>

      <ul>
        {pageData.items.map((post) => (
          <li key={post.id}>
            {post.title} {post.published ? "✅" : "📝"}
          </li>
        ))}
      </ul>

      <footer>
        Página {pageData.page} de {pageData.pages} — {pageData.total} no total
        <button disabled={page <= 1} onClick={() => setPage((p) => p - 1)}>
          Anterior
        </button>
        <button disabled={page >= pageData.pages} onClick={() => setPage((p) => p + 1)}>
          Próxima
        </button>
      </footer>
    </div>
  );
}
```

E uma tela de edição usando `useOne` + `useUpdate` + `useDelete`:

```tsx
import { useOne, useUpdate, useDelete } from "tempest-react-sdk";

interface Post {
  id: string;
  title: string;
  published: boolean;
}

export function EditPost({ id }: { id: string }) {
  const { data: post, isLoading } = useOne<Post>("posts", id);

  const updatePost = useUpdate<Post>("posts");
  const deletePost = useDelete<Post>("posts", {
    onSuccess: () => console.log("post removido"),
  });

  if (isLoading || !post) return <p>Carregando…</p>;

  return (
    <div>
      <h2>{post.title}</h2>

      <button
        disabled={updatePost.isPending}
        // PATCH /posts/{id} — invalida a lista E o useOne deste id
        onClick={() => updatePost.mutate({ id: post.id, data: { published: !post.published } })}
      >
        {post.published ? "Despublicar" : "Publicar"}
      </button>

      <button disabled={deletePost.isPending} onClick={() => deletePost.mutate(post.id)}>
        Excluir
      </button>
    </div>
  );
}
```

!!! note "`useOne` se desabilita sozinho sem `id`"
    Quando `id` é `null`/`undefined`, o `useOne` não dispara o fetch (`enabled: false`). Útil em telas que recebem o id de forma assíncrona (rota, seleção) — não precisa de `enabled` manual no caso comum. Você ainda pode passar `enabled` em `options` para combinar com outra condição.

## Recap

- `createDataProvider(client, options?)` transforma um `apiClient` num provider CRUD no estilo Refine, com defaults alinhados ao `tempest-fastapi-sdk` (`page`/`size`/`order_by`/`ascending`, `ascending` booleano, PATCH no update).
- Envolva a árvore com `<TempestDataProvider provider={…}>` **abaixo** de um `<QueryProvider>`.
- `useList` resolve um `OffsetPage<T>` (`items`/`total`/`page`/`pages`); `useOne` busca um registro e se desabilita sem `id`.
- `useCreate` / `useUpdate` / `useDelete` são mutations que invalidam o cache certo no sucesso — lista (create/delete) ou lista + registro (update).
- Backends fora da convenção? Ajuste `pageParam`/`sizeParam`/`sortFieldParam`/`sortOrderParam`/`sortOrderAsBoolean`/`updateMethod`/`buildPath`.

## Veja também

- [HTTP](./http.md) — o `createApiClient` que alimenta o data provider
- [Query](./query.md) — o `<QueryProvider>` obrigatório por cima
- [Access Control](./access-control.md) — restringir ações de CRUD por papel/permissão

---

# design/anti-patterns.md

# Anti-padrões

As páginas anteriores dizem o que fazer. Esta diz o que você vai **encontrar** —
num app existente, ou num PR seu de sexta-feira à noite.

Cada entrada tem o mesmo formato: como reconhecer, por que dói, e o refactor.

## 1. O componente Deus

**Reconhecer:** um `.tsx` com 400+ linhas, `useState` misturado com `fetch`,
formatação, validação e JSX.

**Dói porque:** cinco motivos de mudança num arquivo — toda alteração tem chance
de quebrar algo não relacionado, e ninguém lê o arquivo inteiro antes de editar.

**Refactor:** três cortes, nesta ordem.

1. `fetch` → [serviço](data-flow.md).
2. Estado + handlers → [hook](components.md#logic-to-hook).
3. Blocos de JSX → sub-componentes.

Sempre nessa ordem: tirar a rede primeiro é o que torna o resto testável.

## 2. `fetch` dentro do componente

**Reconhecer:**

```tsx
useEffect(() => {
  fetch(`/api/orders?page=${page}`)
    .then((r) => r.json())
    .then(setOrders);
}, [page]);
```

**Dói porque:** intestável sem servidor, sem cache, sem dedupe, sem tratamento de
erro, sem cancelamento — e o mesmo endpoint chamado em duas telas dispara dois
requests.

**Refactor:** serviço + `useQuery`. Vira uma linha no componente:

```tsx
const { data = [], isLoading } = useOrders(page);
```

Ver [Fluxo de dados](data-flow.md).

## 3. `useEffect` de sincronização

**Reconhecer:** `useEffect` cujo corpo só chama `setState` a partir de outro
estado ou prop.

```tsx
useEffect(() => {
  setFullName(`${first} ${last}`);
}, [first, last]);
```

**Dói porque:** render extra, uma janela em que o valor está velho, e uma segunda
fonte de verdade.

**Refactor:** calcule.

```tsx
const fullName = `${first} ${last}`;
```

Ver [Onde mora cada estado](state.md#derived).

## 4. Estado de servidor duplicado no store

**Reconhecer:** `useOrdersStore` com um array de pedidos que vem da API, mais um
`fetchOrders()` que preenche o array.

**Dói porque:** você reimplementou cache — mas sem invalidação, sem revalidação,
sem `staleTime`. O sintoma é sempre "a tela não atualiza depois do POST".

**Refactor:** dado de servidor → [Query](../query.md). O store fica só com o que é
de cliente (sessão, tema, carrinho).

## 5. Prop drilling de 4 níveis

**Reconhecer:** a mesma prop atravessando componentes que não a usam, só pra
chegar no neto do neto.

**Dói porque:** todo componente do caminho conhece um dado que não é dele, e
adicionar um campo mexe em cinco arquivos.

**Refactor:** três opções, na ordem:

1. **Composição** — passe `children` já montado, em vez de dados pro filho montar.
2. **Contexto** — quando é realmente global (tema, sessão, i18n).
3. **Store** — quando é global **e** muda com frequência.

!!! warning "Contexto não é a primeira resposta"
    Contexto re-renderiza todo consumidor quando o valor muda. Composição resolve
    a maioria dos casos de drilling sem custo nenhum de render.

## 6. Pass-through {#passthrough}

**Reconhecer:** função, hook ou componente cujo corpo só repassa os argumentos.

```ts
// ❌ camada sem lógica nenhuma
export async function listCustomers(params: GetListParams) {
  return dataProvider.getList<Customer>("customers", params);
}
```

**Dói porque:** é uma indireção a mais pra ler, um arquivo a mais pra abrir, e
zero comportamento adicionado. E quando a assinatura de baixo muda, você mexe em
dois lugares.

**Refactor:** apague e chame direto — `useList<Customer>("customers", params)`.

Exceções legítimas: fronteira de abstração intencional (fachada pública sobre
implementação privada, hook de framework, implementação de interface). Se for o
caso, o JSDoc diz que é.

## 7. Cerimônia {#cerimonia}

**Reconhecer:** camada criada por simetria, não por necessidade — `types/`,
`constants/`, `mappers/` com um arquivo de duas linhas cada, um `mapper` que copia
campo por campo sem transformar nada.

```ts
// ❌ mapeia A em A
export function toOrder(dto: OrderDto): Order {
  return { id: dto.id, code: dto.code, status: dto.status };
}
```

**Dói porque:** cada camada vazia é mais um lugar pra procurar e mais um pra
manter em sincronia, em troca de nada.

**Refactor:** delete. Estrutura se adiciona quando o segundo caso aparece, não
antes.

## 8. Barrel gigante no app

**Reconhecer:** um `src/index.ts` (ou `components/index.ts`) reexportando tudo, e
imports do tipo `import { X } from "@/components"`.

**Dói porque:** ciclo de import (A → barrel → B → barrel → A), e o Vite
reprocessa a árvore inteira a cada edição — o dev server fica lento sem motivo
aparente.

**Refactor:** barrel só na **fronteira de feature** (`features/orders/index.ts`).
Dentro da feature e dentro de `components/`, caminho direto.

!!! note "No SDK é diferente — de propósito"
    Um pacote publicado precisa do barrel: é o contrato de import do consumidor. O
    custo é pago com `preserveModules` no build, que preserva o grafo de módulos
    para o bundler do app tree-shakear. App não publica nada, então não tem esse
    problema pra resolver.

## 9. `any` e `as` pra calar o compilador

**Reconhecer:** `as any`, `@ts-ignore`, `props: any`, `!` espalhado.

**Dói porque:** o erro não desaparece — ele muda de lugar, pra runtime, longe da
causa.

**Refactor:** `unknown` + validação na borda, union discriminada, early return. Ver
[Tipagem forte](typing.md).

## 10. Booleana como variante

**Reconhecer:** `<Alert error warning info small />`.

**Dói porque:** representa estados impossíveis (`error warning` juntos) e a
precedência fica escondida no CSS.

**Refactor:** `union` de string — `<Alert variant="error" size="sm" />`.

## 11. Teste acoplado à implementação

**Reconhecer:** `container.querySelector(".tempest_card_1a2b")`, snapshot de 400
linhas, assert de que `useState` foi chamado.

**Dói porque:** falha quando o CSS muda e passa quando o comportamento quebra.
Confiança falsa é pior que nenhum teste.

**Refactor:** consulte por papel (`getByRole`) e verifique comportamento
observável. Ver [Estratégia de testes](testing.md).

## 12. `catch` silencioso

**Reconhecer:**

```ts
try {
  await payOrder(id);
} catch {
  // ignora
}
```

**Dói porque:** troca um erro visível por um comportamento errado invisível. O
usuário clica, nada acontece, e não existe log.

**Refactor:** trate (mensagem específica), ou **não capture** — deixe subir pro
[ErrorBoundary](../error-boundary.md) e registre no [logger](../logger.md).

## 13. Hardcode de string mágica

**Reconhecer:** `if (status === "paid")` em sete arquivos; `["orders", "list", page]`
montado à mão na query e na invalidação.

**Dói porque:** o typo não é erro de compilação. `"payed"` num dos sete arquivos
é um `if` que nunca entra.

**Refactor:** union + constante derivada. Query key via
[`createQueryKeys`](../query.md); rótulo via tabela `satisfies Record<Status, string>`
([Tipagem](typing.md#satisfies)).

## 14. Estilo inline em vez de token

**Reconhecer:** `style={{ color: "#2563eb", padding: 12 }}`.

**Dói porque:** não respeita tema dark, não respeita densidade, não tem estado
(`:hover`/`:focus-visible`) e vira 40 tons de azul diferentes pelo app.

**Refactor:** CSS Module + tokens `--tempest-*`:

```css
.card {
  color: var(--tempest-text);
  background: var(--tempest-surface);
  padding: var(--tempest-space-3);
}
```

Ver [Estilos & Design Tokens](../styles.md).

!!! tip "`tempest doctor` acha parte disso"
    O CLI analisa o CSS do projeto: propriedade e token inexistentes, declaração
    duplicada, sintaxe que o browser derruba, bloco repetido que pede classe
    utilitária.

    ```bash
    npx tempest doctor
    npx tempest fix --dry-run
    ```

## 15. Reimplementar o que o SDK tem

**Reconhecer:** um `Modal` próprio, um `useDebounce` próprio, um `formatCurrency`
próprio, uma máscara de CPF própria.

**Dói porque:** foco-trap, `Esc`, restauração de foco, `aria-modal`, scroll lock e
portal são seis detalhes que a versão caseira não tem — e cada um é um bug de
acessibilidade.

**Refactor:** procure primeiro. São 117 componentes, 46 hooks, utilitários BR
(CPF/CNPJ/CEP/telefone/moeda) e 384 exports na raiz. Ver
[catálogo de componentes](../components.md), [hooks](../hooks.md),
[utilitários](../utilities.md).

## O ranking, se você só puder atacar três

| Prioridade | Anti-padrão                       | Por quê                                         |
| ---------- | --------------------------------- | ----------------------------------------------- |
| 🔴 1       | `fetch` no componente             | bloqueia teste, cache e reuso de uma vez        |
| 🔴 2       | Estado de servidor duplicado      | causa direta de "tela com dado velho"           |
| 🔴 3       | `any` / `as` pra calar erro       | move o bug pra produção                         |
| 🟡 4       | Componente Deus                   | doloroso, mas melhora incremental funciona      |
| 🟡 5       | `catch` silencioso                | barato de corrigir, alto retorno                |
| 🟢 6       | Cerimônia / pass-through          | irritante, não perigoso                         |

## Recap

- Os três caros: **`fetch` no componente**, **estado de servidor duplicado**,
  **`any` pra calar o compilador**.
- Componente Deus se resolve em ordem: rede → lógica → JSX.
- `useEffect` que só faz `setState` é estado derivado disfarçado.
- Pass-through e cerimônia são custo sem retorno — delete.
- Antes de escrever primitivo, procure no SDK.

Próxima: [Checklist de revisão](checklist.md) — a versão de uma página.

---

# design/architecture.md

# Camadas de um app frontend

Backend tem um desenho de camadas que todo mundo reconhece: router → controller →
service → repository. Frontend tem o mesmo problema e quase nunca o mesmo
cuidado — o resultado é o componente que valida CPF, monta a URL, faz `fetch`,
trata erro, formata data e renderiza tabela. Seis motivos de mudança num arquivo.

Esta página define as camadas de um app Tempest e a **única regra** que faz elas
valerem algo.

## As seis camadas

```mermaid
flowchart TD
    subgraph borda["Borda do app"]
        BOOT["main.tsx — bootstrap"]
        PROV["providers — composition root"]
        ROUTES["routes.tsx — mapa de URLs"]
    end
    subgraph tela["Tela"]
        PAGE["pages/ — orquestração"]
        FEAT["features/ — domínio + UI do domínio"]
        UI["components/ + SDK — UI sem domínio"]
    end
    subgraph dados["Dados"]
        SVC["services/ — fala com o backend"]
        INFRA["lib/ — apiClient, storage, logger"]
    end

    BOOT --> PROV --> ROUTES --> PAGE
    PAGE --> FEAT
    FEAT --> UI
    FEAT --> SVC
    SVC --> INFRA
```

| #   | Camada         | Responsabilidade                                                                | Nunca faz                                        |
| --- | -------------- | ------------------------------------------------------------------------------- | ------------------------------------------------ |
| 1   | **Bootstrap**  | `createRoot`, importar o CSS, montar `<App />`                                   | lógica de qualquer tipo                          |
| 2   | **Providers**  | Compor contexto global (query, tema, i18n, auth, flags, telemetria)             | conhecer feature nenhuma                         |
| 3   | **Rotas**      | Mapear URL → página, guardas, code splitting                                    | buscar dados                                     |
| 4   | **Páginas**    | Ler params da URL, compor features, definir layout da tela                      | regra de negócio, `fetch`, formatação            |
| 5   | **Features**   | Um domínio: seus componentes, hooks, tipos e serviços                           | importar outra feature por dentro                |
| 6   | **UI**         | Renderizar props, emitir eventos, acessibilidade, estilo                        | saber o que é um "pedido"                        |
| 7   | **Serviços**   | Chamar endpoint, validar resposta, devolver tipo do domínio                     | tocar em React                                   |
| 8   | **Infra**      | `apiClient`, storage, logger, telemetria — o "como", não o "o quê"              | saber nome de recurso do domínio                 |

!!! note "Oito linhas, seis camadas"
    Bootstrap/providers/rotas são a **borda** — código que existe uma vez no app.
    As camadas que você edita todo dia são páginas, features, UI, serviços.

## A regra da seta única

> **Uma camada só importa camadas abaixo dela. Nunca ao contrário.**

Isso é a coisa toda. Sem essa regra, "camada" é só um nome de pasta.

=== "✅ Certo"

    ```tsx
    // features/orders/OrderList.tsx
    import { DataTable } from "tempest-react-sdk";

    import { useOrders } from "./use-orders";
    ```

    Feature importa UI (abaixo) e o próprio hook. Seta pra baixo.

=== "❌ Errado"

    ```tsx
    // components/StatusBadge.tsx
    import { useOrders } from "@/features/orders/use-orders";
    ```

    UI importando feature. Agora `StatusBadge` só funciona onde existe pedido,
    não dá pra reusar em faturas, e o teste dele precisa de servidor.

Consequências práticas de respeitar a seta:

- **Testar é barato.** Serviço testa com `fetch` mockado, sem React. UI testa com
  props, sem servidor.
- **Mover código é barato.** Um componente de UI sem domínio sobe pro SDK sem
  reescrita.
- **Apagar feature é barato.** Deletar `features/orders/` não deixa buraco em
  `components/`.

!!! danger "O import que fura a camada é o começo de todo emaranhado"
    Nenhum app apodrece de uma vez. Apodrece com um import "só esse aqui" que
    ninguém remove. Trate import de camada errada como **erro**, não como
    detalhe de estilo — o `tempest lint` e a revisão existem pra isso.

## Como cada camada fica, em código

Um exemplo completo: a tela de pedidos. Oito arquivos, nenhum com mais de 40
linhas.

### 1. Infra — o cliente HTTP existe uma vez

```ts
// src/lib/api.ts
import { createApiClient } from "tempest-react-sdk";

import { useAuth } from "@/stores/auth";

/**
 * Single HTTP client for the app. Every service goes through it, so bearer
 * token, request id and 401 handling are configured in exactly one place.
 */
export const api = createApiClient({
  baseURL: import.meta.env.VITE_API_URL,
  getToken: () => useAuth.getState().token,
  onUnauthorized: () => useAuth.getState().logout(),
});
```

### 2. Serviço — fala com o backend e devolve tipo do domínio

```ts
// src/features/orders/orders.service.ts
import { parseResponse } from "tempest-react-sdk";

import { api } from "@/lib/api";

import { orderListSchema, orderSchema } from "./orders.schema";
import type { Order } from "./orders.schema";

/**
 * Read the paginated order list. The raw payload is validated against the
 * schema, so every consumer downstream can trust the shape.
 */
export async function listOrders(page: number): Promise<Order[]> {
  const raw = await api.get<unknown>("/orders", { params: { page } });
  return parseResponse(orderListSchema, raw, "listOrders");
}

/** Advance an order to the paid state. */
export async function payOrder(id: string): Promise<Order> {
  const raw = await api.post<unknown>(`/orders/${id}/pay`);
  return parseResponse(orderSchema, raw, "payOrder");
}
```

### 3. Hook da feature — cola serviço com React

```ts
// src/features/orders/use-orders.ts
import { useQuery } from "@tanstack/react-query";
import { createQueryKeys } from "tempest-react-sdk";

import { listOrders } from "./orders.service";

export const orderKeys = createQueryKeys("orders", {
  list: (page: number) => ["list", page] as const,
  detail: (id: string) => ["detail", id] as const,
});

/** Order list for a page, cached by TanStack Query. */
export function useOrders(page: number) {
  return useQuery({
    queryKey: orderKeys.list(page),
    queryFn: () => listOrders(page),
  });
}
```

### 4. Componente da feature — sabe o que é pedido, não sabe HTTP

```tsx
// src/features/orders/OrderTable.tsx
import { Badge, Button, DataTable, type DataTableColumn } from "tempest-react-sdk";

import type { Order } from "./orders.schema";

interface OrderTableProps {
  orders: Order[];
  onPay: (id: string) => void;
}

/**
 * Presentational table for orders. Receives data, emits intent — no fetching,
 * no mutation, no knowledge of where the rows came from.
 */
export function OrderTable({ orders, onPay }: OrderTableProps) {
  const columns: DataTableColumn<Order>[] = [
    { key: "code", header: "Código", sortable: true },
    { key: "status", header: "Status", render: (o) => <Badge>{o.status}</Badge> },
    {
      key: "id",
      header: "",
      align: "right",
      render: (o) => (
        <Button size="sm" onClick={() => onPay(o.id)}>
          Pagar
        </Button>
      ),
    },
  ];

  return <DataTable data={orders} columns={columns} rowKey={(o) => o.id} searchable />;
}
```

!!! note "`key` é `keyof T` — de propósito"
    A coluna de ações reusa `key: "id"` porque o tipo obriga a apontar pra um
    campo real da linha. Isso impede a coluna fantasma (`key: "actions"`) que
    quebra silenciosamente quando o campo muda de nome — é
    [tipagem cobrando o desenho](typing.md).

### 5. Página — orquestra, não implementa

```tsx
// src/pages/Orders.tsx
import { Page, Spinner, useSearchParams } from "tempest-react-sdk";

import { OrderTable } from "@/features/orders/OrderTable";
import { useOrders } from "@/features/orders/use-orders";
import { usePayOrder } from "@/features/orders/use-pay-order";

/** Orders screen: reads the page from the URL and wires the feature together. */
export function Orders() {
  const [params] = useSearchParams();
  const page = Number(params.get("page") ?? 1);

  const { data = [], isLoading } = useOrders(page);
  const { mutate: pay } = usePayOrder();

  return (
    <Page title="Pedidos">
      {isLoading ? <Spinner /> : <OrderTable orders={data} onPay={pay} />}
    </Page>
  );
}
```

Repare no que a página **não** tem: nenhuma URL de API, nenhum `useState` de
dado remoto, nenhuma formatação, nenhuma regra. Ela lê a URL, chama a feature e
posiciona. É o teto de complexidade de uma página bem desenhada.

## Tabela de importações permitidas

Cole isso na revisão de código:

| De ↓ / Pode importar →   | Infra | Serviços | UI  | Features | Páginas | Rotas |
| ------------------------ | ----- | -------- | --- | -------- | ------- | ----- |
| **Infra** (`lib/`)       | ✅    | ❌       | ❌  | ❌       | ❌      | ❌    |
| **Serviços**             | ✅    | ⚠️        | ❌  | ❌       | ❌      | ❌    |
| **UI** (`components/`)   | ❌    | ❌       | ✅  | ❌       | ❌      | ❌    |
| **Features**             | ✅    | ✅       | ✅  | ⚠️        | ❌      | ❌    |
| **Páginas**              | ⚠️     | ❌       | ✅  | ✅       | ❌      | ❌    |
| **Rotas / Providers**    | ✅    | ❌       | ✅  | ⚠️        | ✅      | ✅    |

- ✅ livre.
- ⚠️ com critério: serviço pode compor outro serviço; feature importa outra
  feature **só pelo `index.ts` dela**; página pode ler infra pra coisas globais
  (logger, flags).
- ❌ é erro. Sem exceção "temporária".

!!! tip "UI não importa nada do app — nem `lib/`"
    Um componente de `components/` que importe `@/lib/api` deixou de ser UI. Se
    ele precisa de dado, ele recebe por prop. É esse rigor que faz o componente
    virar candidato a subir pro SDK depois.

## Onde o SDK entra

Você não implementa as camadas 1–3 e 8 na mão:

| Camada    | Use                                                                              |
| --------- | -------------------------------------------------------------------------------- |
| Providers | [`<AppProviders>`](../app-providers.md)                                          |
| Rotas     | [`defineRoutes` + `<AppRouter>` + `<RouteGuard>`](../routing.md)                  |
| Serviços  | [`createApiClient` + `parseResponse`](../http.md)                                 |
| CRUD puro | [`createDataProvider` + `useList`/`useOne`/`useCreate`](../data-provider.md)      |
| UI        | [Catálogo de componentes](../components.md)                                      |
| Infra     | [Logger](../logger.md), [Telemetry](../telemetry.md), [Feature Flags](../feature-flags.md) |

E o [`create-tempest-app`](../scaffold.md) já gera o app com `lib/`, `stores/`,
`layouts/`, `pages/` e `routes.tsx` no lugar.

!!! info "CRUD sem regra? Pule o serviço"
    Quando o recurso é REST previsível e não tem transformação nenhuma, o
    [Data Provider](../data-provider.md) substitui o par serviço+hook. Escrever
    um serviço que só repassa é um [pass-through](anti-patterns.md#passthrough) —
    indireção sem lógica.

## Recap

- Oito papéis, seis camadas que você edita: **página → feature → UI** de um lado,
  **serviço → infra** do outro.
- A **regra da seta única** é o que transforma nome de pasta em arquitetura.
- Página orquestra e nada mais; UI não conhece domínio; serviço não conhece React.
- Import de camada errada é **erro de revisão**, não detalhe.
- O SDK entrega borda (providers/rotas), serviços (HTTP) e UI — você mantém as
  fronteiras.

Próxima: [Estrutura de pastas](folders.md) — onde cada uma dessas camadas mora no
disco.

---

# design/checklist.md

# Checklist de revisão

Toda a seção em uma página. Use antes de abrir o PR e durante a revisão do PR de
outra pessoa.

!!! tip "Copie pro seu repositório"
    Vale colar esta lista em `.github/pull_request_template.md`. Checklist que
    aparece sozinho no formulário do PR é usado; checklist que mora num wiki não é.

## Antes de abrir o PR

### Camadas

- [ ] Nenhum componente chama `fetch`/`apiClient` direto.
- [ ] Nenhum import de camada de cima (UI não importa feature, feature não importa
      página).
- [ ] Feature importada de fora só pelo `index.ts` dela.
- [ ] Nenhum `../../../` — só `@/` ou irmão (`./`).
- [ ] Arquivo está na pasta da **feature**, não numa pasta por tipo de arquivo.

### Estado

- [ ] Nada que dê pra calcular está em `useState`.
- [ ] Nenhum `useEffect` cujo corpo só chama `setState`.
- [ ] Dado de servidor está no Query, não em `useState`/store.
- [ ] Filtro/página/aba estão na URL, não duplicados em `useState`.
- [ ] Campo de formulário está no `useZodForm`, não em `useState`.

### Tipos

- [ ] Zero `any`. Zero `@ts-ignore`.
- [ ] Nenhum `as` novo (fora `as const` e estreitamento pós-guard).
- [ ] Tipo do domínio derivado do schema (`z.infer`), não redigitado.
- [ ] Resposta de rede passa por `parseResponse`/schema.
- [ ] Estado com mais de um caso é **union discriminada**, não flags booleanas.
- [ ] Variante de componente é `union` de string, não booleana.
- [ ] Coleção vazia é `[]`, não `null`.
- [ ] `npx tsc -b --noEmit` passa.

### Tamanho

- [ ] `.tsx` ≤ 150 linhas de código — ou JSDoc explicando o motivo de estourar.
- [ ] Função/componente ≤ 80 linhas.
- [ ] Hook ≤ 100 linhas.
- [ ] ≤ 7 props por componente.
- [ ] Aninhamento de JSX ≤ 4.

### Componente

- [ ] Antes de escrever, procurei no [catálogo](../components.md) e nos
      [hooks](../hooks.md) do SDK.
- [ ] Componente de apresentação não conhece domínio nenhum.
- [ ] `...rest` tipado via `HTMLAttributes<T>`, e `className` do chamador entra por
      último no `cn(...)`.
- [ ] Ação é `<button>`, navegação é `<a>` — nunca `<div onClick>`.
- [ ] Todo campo tem `label` associado.
- [ ] Overlay novo: `Esc` fecha, foco preso dentro, foco volta pro gatilho.

### Estilo

- [ ] Nenhum valor de cor/espaço hardcoded — tokens `--tempest-*`.
- [ ] Nenhum `style={{...}}` com o que deveria ser CSS Module.
- [ ] Testado em tema **claro e escuro**.
- [ ] Testado em ≤ 430px e ≥ 1024px.
- [ ] Texto sobre superfície tingida usa o foreground daquela superfície
      (ex. `--tempest-primary-on-soft`), não `--tempest-text-subtle`.

### Erro

- [ ] Nenhum `catch` vazio ou que só faz `console.log`.
- [ ] Erro que a feature não trata **sobe** (não vira toast genérico).
- [ ] A tela tem estado de erro e estado vazio, não só o de sucesso.

### Testes

- [ ] Todo teste novo responde "que bug isso pegaria?".
- [ ] Consulta por papel (`getByRole`), não por classe CSS.
- [ ] Serviço novo tem teste com payload **inválido**, não só o feliz.
- [ ] Nenhum snapshot grande novo.
- [ ] `npm run test:run` e `npm run lint` passam.

### Visual

- [ ] Mudança de UI foi vista **no browser**, não só no `expect`.
- [ ] Console do browser sem erro novo.

## Durante a revisão do PR de outra pessoa

Cinco perguntas que pegam a maior parte dos problemas reais:

1. **Onde esse dado nasce e onde ele morre?** Se a resposta atravessa camadas na
   ordem errada, é aí.
2. **Esse estado tem duas fontes?** Procure `useState` que espelha URL, prop ou
   resposta de API.
3. **O que acontece quando a rede falha?** Se não há resposta no diff, falta
   estado de erro.
4. **Esse teste falharia se eu quebrasse o comportamento?** Se ele só falha com
   mudança de CSS, não é teste.
5. **Isso já existe no SDK?** `Modal`, `useDebounce`, máscara de CPF, formatação
   de moeda — quase sempre sim.

!!! warning "Revisão não é caça a `nit:`"
    Formatação é trabalho do Prettier; ordem de import é do ESLint. Se um
    comentário de revisão pode ser resolvido por ferramenta, configure a
    ferramenta em vez de escrever o comentário. Revisão humana serve pro que
    ferramenta não vê: desenho, fronteira, estado duplicado, caso não tratado.

## Os comandos

```bash
npx tsc -b --noEmit      # tipos, incluindo testes
npx tempest lint         # ESLint
npx tempest fix          # imports (../ → @/), ordem, import morto, CSS morto
npx tempest doctor       # config, env, deps, análise de CSS
npm run test:run         # suíte
npm run test:coverage    # pisos de cobertura
```

Rodar isso antes do push é mais rápido que descobrir no CI.

## Recap

- O checklist é o resumo executável de tudo na seção: camadas, estado, tipos,
  tamanho, componente, estilo, erro, testes, visual.
- Cole no template de PR do repositório — é onde ele é lido.
- Na revisão do outro, as cinco perguntas valem mais que a lista inteira.
- `nit:` de formatação é bug de configuração de ferramenta, não de revisão.

Voltar ao começo: [Design de Software Frontend](index.md).

---

# design/components.md

# Pensando em componentes

Componente é a unidade de reuso do React, e é onde a maior parte dos apps
acumula dívida. Não porque as pessoas escrevem componente ruim — porque escrevem
**um** componente onde havia três.

Esta página é sobre encontrar as juntas.

## Duas espécies, e não misture

| Espécie             | Sabe o quê                          | Recebe                     | Testa como           |
| ------------------- | ----------------------------------- | -------------------------- | -------------------- |
| **De apresentação** | como algo **parece**                 | props                      | render + props       |
| **De domínio**      | o que é um "pedido"                  | props + hooks da feature   | render + mock do hook |

O componente de apresentação não sabe de onde vem o dado. O de domínio sabe o
domínio, mas não sabe HTTP (isso é [serviço](data-flow.md)).

```tsx
// Apresentação: reusável em qualquer app, qualquer domínio.
export function StatusBadge({ tone, children }: StatusBadgeProps) {
  return <Badge variant={tone}>{children}</Badge>;
}

// Domínio: traduz "pedido" para "aparência".
export function OrderStatusBadge({ status }: { status: OrderStatus }) {
  return <StatusBadge tone={STATUS_TONE[status]}>{STATUS_LABEL[status]}</StatusBadge>;
}
```

O de apresentação é candidato a subir pro SDK. O de domínio nunca sobe — ele é
do seu app, e está certo assim.

!!! tip "Antes de escrever um componente de apresentação, procure no SDK"
    São 117 componentes. `Badge`, `DataTable`, `Modal`, `Combobox`, `Stepper`,
    `EmptyState`, `Skeleton`, `Toast`… Veja o
    [catálogo](../components.md). Reescrever `Modal` com foco-trap correto é uma
    semana que você não precisa gastar.

## Quando quebrar um componente

Não quebre por tamanho — quebre por **motivo de mudança**. Os quatro sinais:

### 1. O nome tem "e"

`UserCardAndActions`, `TableWithFilters`, `FormAndPreview`. O nome está te
contando que são dois.

### 2. Um pedaço muda por outro motivo

Se o `<header>` da tela muda quando o design muda e a `<table>` muda quando a
API muda, são duas responsabilidades num arquivo.

### 3. Um pedaço se repete

Duas vezes: talvez coincidência. Três: extraia.

### 4. Você precisa de um `if` grande no JSX

```tsx
// ❌ três telas num componente
{isLoading ? <Spinner /> : error ? <ErrorState … /> : orders.length === 0 ? <EmptyState … /> : <table>…</table>}
```

Isso pede um componente de estado ou um `switch` num sub-componente.

!!! warning "Quebrar cedo demais também custa"
    Um componente de 6 linhas usado em um lugar só, com 5 props, é indireção sem
    ganho. A pergunta não é "dá pra quebrar?" — é "**esse pedaço tem vida
    própria?**".

## Props: desenhe a interface, não a passagem de dados

Props são a API pública do componente. As regras que mais economizam dor:

### Máximo 7 props — e conte de verdade

Passar de 7 é o sinal mais confiável de que existem dois componentes ali. A saída
não é "agrupar em um objeto" (isso só esconde), é dividir.

### Prop booleana não escala

=== "❌ Errado"

    ```tsx
    <Button primary secondary danger small large />
    ```

    Oito combinações inválidas representáveis. O que acontece com
    `primary danger`?

=== "✅ Certo"

    ```tsx
    <Button variant="danger" size="sm" />
    ```

    Union de string: o compilador só aceita o que existe. É como todo componente
    do SDK é desenhado.

Regra: **três ou mais booleanas mutuamente exclusivas → vira `union`.**

### Passe `children`, não `content`

```tsx
// ✅ composição: quem chama decide o que vai dentro
<Card>
  <OrderSummary order={order} />
</Card>

// ❌ configuração: o Card precisa conhecer todos os casos
<Card contentType="order-summary" order={order} />
```

Composição é o que evita o componente que cresce uma prop por caso de uso.

### Slots quando precisa de mais de um lugar

```tsx
interface PageProps {
  title: ReactNode;
  actions?: ReactNode; // slot: botão, menu, o que o chamador quiser
  toolbar?: ReactNode;
  children: ReactNode;
}
```

`ReactNode` em slot é melhor que `string`: quem chama pode passar texto, ícone,
ou um componente inteiro, sem que `Page` mude.

### Nunca `...props` sem tipo

```tsx
// ✅ estende o elemento nativo — herda aria-*, data-*, onClick, className
interface CardProps extends HTMLAttributes<HTMLDivElement> {
  elevated?: boolean;
}

export function Card({ elevated, className, ...rest }: CardProps) {
  return <div className={cn(styles.card, elevated && styles.elevated, className)} {...rest} />;
}
```

Estender `HTMLAttributes<T>` dá acessibilidade e composição de graça, com
autocomplete. `props: any` dá nada.

!!! info "`cn` é o utilitário pra isso"
    `cn(...)` do SDK junta classes ignorando `false`/`undefined`, e a `className`
    do chamador entra **por último** — então quem consome consegue sobrescrever.
    Veja [Utilitários](../utilities.md).

## Extraia lógica pra hook, não pra componente {#logic-to-hook}

Quando o componente está grande por causa de **lógica**, o corte não é vertical
(dois componentes) — é horizontal (componente + hook):

=== "Antes — 180 linhas"

    ```tsx
    export function OrderTable({ orders }: OrderTableProps) {
      const [sort, setSort] = useState<Sort>({ field: "code", order: "asc" });
      const [selected, setSelected] = useState<Set<string>>(new Set());
      const [page, setPage] = useState(1);

      const toggle = (id: string) => { /* 12 linhas */ };
      const sorted = /* 20 linhas */;
      const paged = /* 8 linhas */;

      return <table>{/* 110 linhas de JSX */}</table>;
    }
    ```

=== "Depois — 40 + 60 linhas"

    ```tsx
    // use-order-table.ts — a lógica, testável sem DOM
    export function useOrderTable(orders: Order[]) {
      const [sort, setSort] = useState<Sort>({ field: "code", order: "asc" });
      const [selected, setSelected] = useState<Set<string>>(new Set());
      const [page, setPage] = useState(1);

      const rows = useMemo(() => paginate(sortBy(orders, sort), page), [orders, sort, page]);

      return { rows, sort, setSort, selected, toggle, page, setPage };
    }

    // OrderTable.tsx — só a marcação
    export function OrderTable({ orders }: OrderTableProps) {
      const { rows, sort, setSort, selected, toggle } = useOrderTable(orders);
      return <table>{/* JSX enxuto */}</table>;
    }
    ```

O hook testa com `renderHook` — sem DOM, sem `screen.getByRole`, rápido. O
componente testa o que importa nele: o que aparece na tela.

!!! tip "O hook customizado é o 'service' do frontend"
    É onde a lógica de tela mora. Mas ele tem [limite](limits.md) também: hook de
    250 linhas é serviço disfarçado — quebre em hooks menores ou mova a parte pura
    pra uma função em `lib/`.

## `React.memo`, `useMemo`, `useCallback`: por medição

React re-renderiza rápido. `memo` em tudo custa comparação de props em cada
render e complica o código com `useCallback` em cascata.

Use quando:

- O componente renderiza **listas grandes** (centenas de itens).
- O profiler mostra um render caro — não "parece caro".
- A prop é objeto/array recriado a cada render **e** o filho é `memo`.

!!! note "Antes de otimizar render, olhe o desenho"
    Lista de 5.000 itens não precisa de `memo` — precisa de
    [`VirtualList`/`VirtualTable`](../components/data.md). O ganho de virtualizar é
    ordens de magnitude maior que qualquer memoização.

## Acessibilidade é parte do componente, não polimento

Um componente interativo sem isso está incompleto:

- Elemento certo: `<button>` pra ação, `<a>` pra navegação. `<div onClick>` não
  recebe foco nem responde a Enter.
- `label` associado a todo campo (`<Label htmlFor>` ou `aria-label`).
- Foco visível — nunca `outline: none` sem substituto.
- Overlay (modal, drawer, popover): foco preso dentro, `Esc` fecha, foco volta pro
  gatilho ao sair.

Os componentes do SDK já implementam isso; o que você escreve por cima é que
precisa de atenção. O CI roda `axe` no gallery — veja
[Estratégia de testes](testing.md).

## Recap

- Duas espécies: **apresentação** (não sabe domínio) e **domínio** (não sabe HTTP).
- Quebre por **motivo de mudança**, não por linha: nome com "e", pedaço repetido,
  `if` grande no JSX.
- ≤ 7 props; booleana exclusiva vira `union`; `children` e slots antes de
  configuração.
- `...rest` tipado via `HTMLAttributes<T>` — acessibilidade e composição de graça.
- Componente grande por **lógica** → extraia **hook**, não outro componente.
- Memoize por medição; lista grande é virtualização, não `memo`.

Próxima: [Limites objetivos](limits.md) — os números.

---

# design/data-flow.md

# Fluxo de dados

Toda tela é a mesma pergunta: **como o dado do servidor chega no pixel, e como a
intenção do usuário volta pro servidor.** Se cada tela responde isso do seu jeito,
o app tem N arquiteturas.

Esta página fixa **um** caminho, nos dois sentidos.

## O caminho de leitura

```mermaid
flowchart LR
    BE[("Backend")] -->|JSON cru| AC["apiClient<br/>(infra)"]
    AC -->|unknown| SVC["service<br/>+ parseResponse"]
    SVC -->|tipo do domínio| HOOK["useQuery<br/>(cache)"]
    HOOK -->|data| PAGE["página"]
    PAGE -->|props| UI["componente"]
```

Cinco paradas, e cada uma tem exatamente um trabalho:

| Parada         | Entrada           | Saída               | Trabalho                                    |
| -------------- | ----------------- | ------------------- | ------------------------------------------- |
| `apiClient`    | path + params     | `unknown`           | URL, headers, bearer, 401, request id       |
| `service`      | `unknown`         | tipo do domínio     | **validar** e mapear DTO → domínio          |
| `useQuery`     | função + key      | `data`/`error`      | cache, dedupe, revalidação, loading         |
| página         | `data`            | props               | orquestrar, ler URL                         |
| componente     | props             | DOM                 | renderizar, emitir eventos                  |

!!! danger "A única regra que não tem exceção"
    **Componente não chama `fetch`, `axios`, nem `apiClient`.** Nem "só nesse
    caso". Um componente que busca dado é intestável sem servidor, irreusável em
    outro contexto e invisível pro cache.

### `unknown` na entrada, tipo estreito na saída

O `apiClient` devolve `unknown` de propósito:

```ts
const raw = await api.get<unknown>("/orders", { params: { page } });
return parseResponse(orderListSchema, raw, "listOrders");
```

Por que não `api.get<Order[]>` direto? Porque `get<Order[]>` é uma **promessa
sua**, não uma verificação. Se o backend renomear `total_amount` pra `amount`, o
TypeScript continua feliz e o app quebra em produção, num `.toFixed()` de
`undefined`, três telas depois.

O `parseResponse` transforma isso num erro **na borda**, com contexto:

```text
[listOrders] resposta inválida: total_amount — Required
```

!!! tip "Valide na borda, confie no miolo"
    Esse é o ponto todo. Uma validação na fronteira compra o direito de escrever
    o resto do app sem `if (order?.total_amount != null)` em cada linha. Sem ela,
    a checagem defensiva vaza pra dentro de cada componente. Veja
    [Tipagem forte](typing.md).

### DTO e tipo do domínio não são a mesma coisa

Backend fala `snake_case`, manda data como string ISO, manda dinheiro como
centavos. Nada disso precisa vazar pra dentro do app:

```ts
// src/features/orders/orders.schema.ts
import { z } from "zod";

/** Wire format, exactly as the backend sends it. */
const orderDtoSchema = z.object({
  id: z.string().uuid(),
  code: z.string(),
  status: z.enum(["pending", "paid", "shipped", "delivered", "cancelled"]),
  total_cents: z.number().int(),
  created_at: z.string().datetime(),
});

/**
 * Domain shape used everywhere inside the app: camelCase, real Date, money in
 * a single unit. The transform is the only place that knows the wire format.
 */
export const orderSchema = orderDtoSchema.transform((dto) => ({
  id: dto.id,
  code: dto.code,
  status: dto.status,
  totalCents: dto.total_cents,
  createdAt: new Date(dto.created_at),
}));

export const orderListSchema = z.array(orderSchema);

export type Order = z.infer<typeof orderSchema>;
export type OrderStatus = Order["status"];
```

Ganhos concretos:

- `createdAt` já é `Date` — nenhum componente faz `new Date(...)`.
- `snake_case` morre no schema; o app é `camelCase` inteiro.
- Trocar o backend de campo é editar **um** arquivo.

!!! warning "Não transforme o que você não precisa"
    Se o DTO já está no formato que você quer, não invente `transform` só pra ter
    uma camada. Mapeamento sem propósito é [cerimônia](anti-patterns.md#cerimonia),
    e cerimônia é custo sem retorno.

## O caminho de escrita

```mermaid
flowchart LR
    UI["componente"] -->|onPay id| PAGE["página"]
    PAGE -->|mutate| MUT["useMutation"]
    MUT --> SVC["service"]
    SVC --> AC["apiClient"] --> BE[("Backend")]
    MUT -.->|invalidateQueries| HOOK["cache de leitura"]
```

O componente **não** decide o que acontece — ele avisa a intenção (`onPay(id)`).
Quem sabe o efeito é o hook de mutation:

```ts
// src/features/orders/use-pay-order.ts
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { useToast } from "tempest-react-sdk";

import { payOrder } from "./orders.service";
import { orderKeys } from "./use-orders";

/**
 * Pay an order and refresh every cached order query. Invalidating `all`
 * (instead of a single page key) is intentional: paying changes counters and
 * list ordering, so any cached page may now be stale.
 */
export function usePayOrder() {
  const queryClient = useQueryClient();
  const toast = useToast();

  return useMutation({
    mutationFn: payOrder,
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: orderKeys.all });
      toast.success("Pedido pago.");
    },
  });
}
```

O `orderKeys.all` vem de graça no
[`createQueryKeys`](../query.md) — é a key mais ampla do domínio.

!!! tip "Key montada à mão é bug esperando"
    `["orders", "list", page]` escrito na query e `["order", "list", page]`
    escrito na invalidação não dão erro de compilação — dão uma tela que não
    atualiza. Centralizar em `createQueryKeys` fecha essa porta.

## Tratando erro uma vez, não em toda tela

O cliente HTTP joga `TempestApiError` com `status`, `detail`, `code` e
`requestId`. Três níveis de tratamento, e cada erro cai em um só:

| Nível          | Onde                                            | Trata                                        |
| -------------- | ----------------------------------------------- | -------------------------------------------- |
| **Global**     | `createApiClient({ onUnauthorized })`           | 401 → logout/refresh                         |
| **Da feature** | `onError` do `useMutation`                      | regra de negócio (`code === "STOCK_EMPTY"`)  |
| **Da tela**    | `<ErrorState>` / `isError` do `useQuery`        | "não deu, tente de novo"                     |

```ts
import { isApiError } from "tempest-react-sdk";

onError: (error: unknown) => {
  if (isApiError(error) && error.code === "STOCK_EMPTY") {
    toast.error("Sem estoque para esse pedido.");
    return;
  }
  throw error;
},
```

O `throw error` no final não é descuido: erro que a feature não sabe tratar sobe
pro [ErrorBoundary](../error-boundary.md) em vez de virar um `toast` genérico que
esconde o problema.

!!! danger "`catch {}` vazio é a pior linha de código que existe"
    Um catch silencioso troca um erro visível por um comportamento errado
    silencioso. Se você não sabe o que fazer com o erro, **não capture** — deixe
    o [ErrorBoundary](../error-boundary.md) e o [logger](../logger.md) fazerem o
    trabalho.

## Atalho: CRUD sem serviço

Recurso REST previsível, sem transformação nem regra? O
[Data Provider](../data-provider.md) já é o serviço:

```tsx
import { useList } from "tempest-react-sdk";

const { data, isLoading } = useList<Customer>("customers", {
  pagination: { page: 1, pageSize: 20 },
  sort: { field: "name", order: "asc" },
});
```

Escrever um `customers.service.ts` que só repassa esses argumentos é
[pass-through](anti-patterns.md#passthrough). Escreva o serviço quando existir
**alguma** das três coisas: validação com transform, composição de endpoints, ou
regra de negócio.

## Offline: a mesma mutation, com outbox

Em app PWA a escrita pode acontecer sem rede. Não muda o desenho — muda o hook:

```ts
import { useOfflineMutation } from "tempest-react-sdk";

import { orderKeys } from "./use-orders";
import { ordersSync } from "./orders.sync";
import type { Order } from "./orders.schema";

/** Pay an order even offline: the write goes to the outbox and syncs later. */
export function usePayOrderOffline(page: number) {
  return useOfflineMutation<string, Order[], { paid: true }>({
    sync: ordersSync,
    queryKey: orderKeys.list(page),
    toEntry: (id) => ({ op: "update", recordId: id, payload: { paid: true } }),
    applyOptimistic: (current = [], id) =>
      current.map((o) => (o.id === id ? { ...o, status: "paid" } : o)),
  });
}
```

A mutation continua na feature, a UI continua só emitindo intenção. Detalhes em
[PWA & Offline-First](../pwa.md) e [Offline Sync](../offline-sync.md).

## Recap

- Leitura: `apiClient` → `service` (+`parseResponse`) → `useQuery` → página → UI.
- Escrita: UI emite **intenção** → mutation na feature → serviço → invalidação.
- `unknown` entra, tipo do domínio sai. Validar na **borda** paga o resto do app.
- DTO ≠ domínio: `snake_case`, ISO e centavos morrem no schema.
- Erro tem três níveis, cada um com um dono. `catch {}` vazio nunca.
- CRUD trivial: use o [Data Provider](../data-provider.md) e não escreva serviço.

Próxima: [Onde mora cada estado](state.md).

---

# design/folders.md

# Estrutura de pastas

As [camadas](architecture.md) são um conceito. Pasta é onde o conceito encosta no
disco — e é onde a maioria dos apps escorrega, porque a estrutura mais óbvia
(`components/`, `hooks/`, `services/`, `types/`) é a que envelhece pior.

## Por tipo de arquivo não escala

Comece com a estrutura que todo tutorial mostra:

```text
src/
├── components/     ← 84 arquivos
├── hooks/          ← 31 arquivos
├── services/       ← 22 arquivos
└── types/          ← 19 arquivos
```

Agora responda: **quais desses arquivos formam a tela de pedidos?**

Você não sabe. Pra mexer em pedidos você abre quatro pastas, cada uma com dezenas
de vizinhos irrelevantes. Pra apagar pedidos você caça arquivo por arquivo e
deixa três órfãos.

!!! danger "O sintoma é o `git status`"
    Se um PR de uma única feature toca arquivos em 4 pastas diferentes e nenhuma
    delas se chama como a feature, a estrutura está agrupando pela coisa errada.

O problema é que `components/`, `hooks/` e `services/` agrupam por **como o
arquivo foi escrito**. Você nunca precisa "de todos os hooks". Você precisa
"de tudo que é pedido".

## Agrupe por feature

```text
src/
├── main.tsx                      # bootstrap
├── App.tsx                       # providers + router
├── routes.tsx                    # mapa de URLs
│
├── lib/                          # INFRA — existe uma vez no app
│   ├── api.ts                    # createApiClient
│   ├── logger.ts                 # createLogger
│   └── storage.ts
│
├── stores/                       # estado global de cliente
│   └── auth.ts                   # createAuthStore
│
├── layouts/                      # cascas de tela
│   └── RootLayout.tsx
│
├── components/                   # UI DO APP sem domínio (raro — o SDK cobre)
│   └── MoneyInput/
│
├── features/                     # ⭐ o corpo do app
│   ├── orders/
│   │   ├── index.ts              # API pública da feature
│   │   ├── orders.schema.ts      # zod + tipos do domínio
│   │   ├── orders.service.ts     # fala com o backend
│   │   ├── use-orders.ts         # hooks de query/mutation
│   │   ├── use-orders.test.ts
│   │   ├── OrderTable.tsx
│   │   ├── OrderTable.test.tsx
│   │   ├── OrderStatusBadge.tsx
│   │   └── OrderTable.module.css
│   └── customers/
│       └── …
│
└── pages/                        # uma tela por rota
    ├── Orders.tsx
    └── OrderDetail.tsx
```

O `create-tempest-app` já gera `lib/`, `stores/`, `layouts/`, `pages/` e
`routes.tsx` — veja [Scaffold](../scaffold.md). `features/` é o que **você**
adiciona quando a primeira feature aparece.

!!! tip "Teste mora ao lado do arquivo testado"
    `OrderTable.test.tsx` fica junto de `OrderTable.tsx`, não numa árvore
    `__tests__/` paralela. Duas razões: você vê num `ls` se algo tem teste, e
    mover a feature move os testes com ela.

## `index.ts`: a API pública da feature

Uma feature é uma caixa. O `index.ts` é o que sai da caixa:

```ts
// src/features/orders/index.ts

/**
 * Public surface of the orders feature. Anything not re-exported here is an
 * internal detail — other features and pages must not import it directly.
 */
export { OrderTable } from "./OrderTable";
export { useOrders } from "./use-orders";
export { usePayOrder } from "./use-pay-order";
export type { Order, OrderStatus } from "./orders.schema";
```

E o consumo:

=== "✅ Certo"

    ```tsx
    import { OrderTable, useOrders } from "@/features/orders";
    ```

=== "❌ Errado"

    ```tsx
    import { OrderTable } from "@/features/orders/OrderTable";
    import { buildOrderQuery } from "@/features/orders/internal/query-builder";
    ```

    O segundo import amarra outra parte do app a um detalhe interno. Renomear
    `query-builder.ts` agora é breaking change.

!!! info "Duas regras de barrel, e elas parecem contraditórias"
    **Fora da feature**, importe sempre pelo `index.ts` — é o contrato.
    **Dentro da feature**, importe o caminho direto (`./orders.service`), nunca
    o próprio barrel — barrel interno cria ciclo de import e faz o Vite
    reprocessar a feature inteira a cada edição.

## Quando criar uma pasta de feature

Não crie `features/` no primeiro dia. O gatilho é objetivo:

| Situação                                                           | Onde vai                                        |
| ------------------------------------------------------------------ | ----------------------------------------------- |
| Um componente, usado numa página só, sem serviço                   | fica na própria página ou em `components/`       |
| Dois ou mais arquivos que compartilham o mesmo tipo de domínio     | **cria `features/<domínio>/`**                   |
| Tem serviço (fala com backend) + componente                        | **cria `features/<domínio>/`**                   |
| Componente sem nenhum tipo de domínio, reusado em 2+ features      | `components/` — ou candidato a subir pro SDK     |

O nome da pasta é o **domínio**, não a tela: `orders`, não `orders-page`;
`billing`, não `billing-tab`.

!!! warning "Feature não importa o miolo de outra feature"
    `features/billing` pode importar `features/orders` — **pelo `index.ts`**.
    Quando duas features começam a puxar detalhe uma da outra toda hora, elas
    eram uma feature só, ou existe um terceiro conceito compartilhado que
    ninguém extraiu ainda (aí sim: `features/shared/` ou `lib/`).

## Convenção de nomes

Nome previsível economiza mais tempo que qualquer ferramenta de busca.

| Tipo de arquivo         | Padrão                | Exemplo                    |
| ----------------------- | --------------------- | -------------------------- |
| Componente              | `PascalCase.tsx`      | `OrderTable.tsx`           |
| Teste                   | `<arquivo>.test.tsx`  | `OrderTable.test.tsx`      |
| CSS Module              | `<Componente>.module.css` | `OrderTable.module.css` |
| Hook                    | `use-<coisa>.ts`      | `use-orders.ts`            |
| Serviço                 | `<domínio>.service.ts` | `orders.service.ts`       |
| Schema/tipos do domínio | `<domínio>.schema.ts` | `orders.schema.ts`         |
| Store Zustand           | `<domínio>.ts` em `stores/` | `stores/auth.ts`     |
| Utilitário              | `kebab-case.ts`       | `format-invoice.ts`        |

O identificador **exportado** é sempre `PascalCase` pra componente e
`camelCase` pra função — o `kebab-case` é só do nome de arquivo, o que evita
conflito de case em filesystem case-insensitive (macOS) contra Linux no CI.

## Import com `@/`, sempre

O alias `@` → `src` vem configurado pelo
[`createViteConfig`](../vite-config.md). Use ele pra tudo que cruza pasta:

=== "✅ Certo"

    ```ts
    import { api } from "@/lib/api";
    import { useOrders } from "@/features/orders";

    import { OrderRow } from "./OrderRow";
    ```

=== "❌ Errado"

    ```ts
    import { api } from "../../../lib/api";
    ```

Relativo (`./`) só entre irmãos do mesmo diretório. `../../../` é sinal de que
você está furando uma fronteira **ou** de que o arquivo está na pasta errada.

!!! tip "`tempest fix` converte isso pra você"
    ```bash
    npx tempest fix --dry-run   # lista o que seria reescrito
    npx tempest fix             # aplica: ../../../ → @/, ordena imports, remove import morto
    ```
    Detalhes em [CLI tempest](../cli.md).

## Ordem dos imports

Três blocos, separados por linha em branco — é o que o
`simple-import-sort` do template já impõe:

```ts
import { useState } from "react";                    // 1. externos
import { Button, DataTable } from "tempest-react-sdk";

import { api } from "@/lib/api";                     // 2. do app (@/)
import { useOrders } from "@/features/orders";

import { OrderRow } from "./OrderRow";               // 3. relativos
import styles from "./OrderTable.module.css";
```

Não é frescura: com ordem fixa, o diff de um import novo é uma linha, não uma
reorganização do bloco inteiro.

## Recap

- Agrupar por **tipo de arquivo** não escala; agrupar por **feature** escala.
- Feature é caixa: `index.ts` é o contrato, o resto é interno.
- Dentro da feature use caminho direto; de fora use só o barrel.
- Gatilho pra criar feature: **2+ arquivos com o mesmo domínio**, ou serviço +
  componente.
- Nome de arquivo `PascalCase` pra componente, `kebab-case` pro resto; `@/` pra
  cruzar pasta e `tempest fix` pra manter isso.

Próxima: [Fluxo de dados](data-flow.md) — quem tem permissão de falar com o
backend.

---

# design/index.md

# Design de Software Frontend

O SDK te dá as **peças**. Esta seção ensina a **arrumar** as peças.

Um app React quebra por motivos previsíveis: o componente que era pequeno virou
um arquivo de 900 linhas, o `fetch` que era um só virou dezoito espalhados, o
estado que era um `useState` virou seis fontes de verdade que discordam entre si.
Nada disso é falta de biblioteca — é falta de **desenho**.

!!! tip "Você não precisa saber tudo antes de começar"
    Cada página aqui é curta e assume só as anteriores. Comece na primeira,
    aplique no seu app, volte pra próxima. Nada aqui exige refatorar tudo de uma
    vez.

## O problema, em uma frase

> Todo app frontend cresce. O que decide se ele fica agradável ou insuportável é
> **quantas coisas você precisa ter na cabeça pra mudar uma linha**.

Design de software é o trabalho de manter esse número baixo. As técnicas são
sempre as mesmas três:

1. **Separar** o que muda por motivos diferentes (camadas).
2. **Limitar** o tamanho de cada peça (limites objetivos).
3. **Deixar o compilador cobrar** o que você não quer revisar à mão (tipagem).

## As quatro perguntas

Quando você abre um arquivo e não sabe se aquele código deveria estar ali, é
sempre uma dessas quatro:

| Pergunta                          | Onde a resposta mora                                       |
| --------------------------------- | ---------------------------------------------------------- |
| **Em que camada isso vive?**      | [Camadas de um app frontend](architecture.md)              |
| **Em que arquivo/pasta isso vai?** | [Estrutura de pastas](folders.md)                          |
| **Quem sabe falar com o backend?** | [Fluxo de dados](data-flow.md)                             |
| **Onde esse estado deveria morar?** | [Onde mora cada estado](state.md)                          |

E quando o arquivo já existe e você precisa decidir se ele está bom:

| Pergunta                            | Onde a resposta mora                       |
| ----------------------------------- | ------------------------------------------ |
| **Esse componente está grande demais?** | [Limites objetivos](limits.md)         |
| **Como quebro sem virar sopa de props?** | [Pensando em componentes](components.md) |
| **Como o tipo impede o bug?**       | [Tipagem forte](typing.md)                 |
| **O que eu testo disso?**           | [Estratégia de testes](testing.md)         |

## O caminho recomendado

```mermaid
flowchart LR
    A[Camadas] --> B[Pastas]
    B --> C[Fluxo de dados]
    C --> D[Estado]
    D --> E[Componentes]
    E --> F[Limites]
    F --> G[Tipagem]
    G --> H[Testes]
    H --> I[Anti-padrões]
    I --> J[Checklist]
```

**Desenho do sistema** (as quatro primeiras) responde _onde as coisas moram_.
**Escrevendo o código** (as três do meio) responde _como cada peça é escrita_.
**Sustentando** (as três últimas) responde _como isso continua verdade em seis
meses_.

## O resumo de tudo, numa tabela

Se você só ler uma coisa desta seção, leia esta tabela. Todo o resto é a
justificativa dela.

| Regra                                                               | Por quê                                                        | Página                          |
| ------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------- |
| Arquivo `.tsx` de componente: **≤ 150 linhas**                      | Acima disso ninguém lê o arquivo inteiro antes de editar        | [Limites](limits.md)            |
| Hook customizado: **≤ 100 linhas**, uma responsabilidade            | Hook grande é serviço disfarçado                                | [Limites](limits.md)            |
| Props de um componente: **≤ 7**                                     | Mais que isso é sinal de dois componentes num só                | [Componentes](components.md)    |
| **Zero `any`**. `unknown` na borda, tipo estreito depois            | `any` desliga o compilador exatamente onde você mais precisa    | [Tipagem](typing.md)            |
| Toda resposta de rede passa por **schema zod**                      | Backend muda sem avisar; a borda é o único lugar de validar     | [Fluxo de dados](data-flow.md)  |
| Componente **nunca** chama `fetch` direto                           | Amarra UI a transporte e mata o teste                           | [Fluxo de dados](data-flow.md)  |
| Dado de servidor vive no **TanStack Query**, não em `useState`      | Cache, revalidação e loading de graça, sem sincronizar à mão    | [Estado](state.md)              |
| Filtro/paginação/aba vivem na **URL**                               | Link compartilhável, botão voltar funcionando                   | [Estado](state.md)              |
| Camada de baixo **não importa** camada de cima                      | A seta única é o que permite testar e mover código              | [Camadas](architecture.md)      |
| Uma pasta por **feature**, não por tipo de arquivo                  | Você edita features, não "todos os hooks do app"                | [Pastas](folders.md)            |

!!! warning "Regra não é dogma — é default"
    Cada limite aqui tem uma saída de emergência documentada na página dele.
    Passar de 150 linhas num arquivo de tabela com 30 colunas pode ser a escolha
    certa. O que **não** é aceitável é passar sem perceber.

## Como isso se conecta ao SDK

O `tempest-react-sdk` já implementa a maior parte da infraestrutura que este
desenho pede. Você não constrói as camadas do zero:

| Camada             | O que o SDK já entrega                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------ |
| Bootstrap/providers | [`<AppProviders>`](../app-providers.md) — ErrorBoundary → Query → Theme → i18n num bloco  |
| Rotas              | [`defineRoutes`, `<AppRouter>`, `<RouteGuard>`](../routing.md)                              |
| Serviços/HTTP      | [`createApiClient`, `parseResponse`](../http.md), [`createDataProvider`](../data-provider.md) |
| Estado de servidor | [`QueryProvider`, `createQueryKeys`, `usePaginatedQuery`](../query.md)                       |
| Estado de cliente  | [`createStore`, `createSelectors`](../state.md)                                              |
| Formulários        | [`useZodForm`, `<FormField>`](../forms.md)                                                   |
| UI                 | [117 componentes](../components.md) com tokens `--tempest-*`                                 |
| Ferramenta         | [`tempest doctor` / `lint` / `fix`](../cli.md)                                                |

## Recap

- Design existe pra manter baixo o **número de coisas na cabeça** por mudança.
- Três alavancas: **separar** por motivo de mudança, **limitar** tamanho, **tipar**
  pra o compilador cobrar.
- A tabela de regras acima é o contrato; cada página explica o porquê e a saída
  de emergência.
- O SDK já implementa as camadas — seu trabalho é **não furar** as fronteiras.

Próxima página: [Camadas de um app frontend](architecture.md) 🚀

---

# design/limits.md

# Limites objetivos

"Mantenha os componentes pequenos" é um conselho que ninguém consegue aplicar,
porque não é verificável. Duas pessoas discordam sobre "pequeno" e a discussão
morre no gosto.

Limite com **número** resolve isso. O número não precisa ser perfeito — precisa
ser combinado.

## A tabela

| O que                            | Limite      | Ação ao estourar                             |
| -------------------------------- | ----------- | -------------------------------------------- |
| Arquivo `.tsx` de componente     | **150**     | extrai sub-componente ou hook                |
| Corpo de uma função/componente   | **80**      | extrai função pura ou hook                   |
| Hook customizado                 | **100**     | quebra em hooks menores                      |
| Props de um componente           | **7**       | provavelmente são dois componentes           |
| Profundidade de aninhamento JSX  | **4**       | extrai sub-componente                        |
| Complexidade ciclomática         | **10**      | tabela de lookup ou early return             |
| Parâmetros de função             | **3**       | vira um objeto nomeado                       |
| Arquivo `.ts` de serviço/util    | **200**     | separa por responsabilidade                  |

!!! info "Por que 150 e não 200 ou 100?"
    150 linhas é o que cabe em duas telas de editor. É o ponto em que você ainda
    consegue **ler o arquivo inteiro** antes de mudar uma linha — e ler o arquivo
    inteiro é o que evita a mudança que quebra outra parte dele. Acima disso você
    passa a editar por busca, não por compreensão.

## O que o número mede de verdade

Linha é um **proxy**. O que você está de fato limitando é:

| Sintoma                            | Consequência real                                    |
| ---------------------------------- | ---------------------------------------------------- |
| Arquivo longo                      | ninguém lê inteiro → mudança de efeito imprevisto    |
| Função longa                       | não cabe na cabeça → bug de estado intermediário     |
| Muitas props                       | muitos casos → combinação inválida representável     |
| JSX profundo                       | não se enxerga a estrutura → CSS/layout quebra        |
| Complexidade alta                  | caminhos não testados → bug em branch raro           |

Por isso vale contar **linhas de código**, não do arquivo: JSDoc e a `interface`
de props não custam carga cognitiva — ajudam.

## Dogfood: onde o próprio SDK fica

Números reais deste repositório (157 arquivos `.tsx` de produção, contando só
linhas de código):

| Métrica                       | Valor    |
| ----------------------------- | -------- |
| Mediana de linhas por arquivo | **65**   |
| Arquivos acima de 150         | **28**   |
| Maior arquivo                 | `FilterBar.tsx` — 279 |

Ou seja: **o limite não é obedecido em 100% dos casos, de propósito.** A mediana
é 65 porque a regra funciona; os 28 que estouram são widgets de comportamento
irredutível — `ImageCropper` (arrasto + zoom + recorte em canvas), `Calendar`
(grade + teclado + intervalo), `BrazilMap` (SVG + hit-testing).

## A saída de emergência: `@tempest-limits`

Estourar o limite é aceitável quando você **escreve o motivo**. O marcador é
`@tempest-limits <regra> — <motivo>` num comentário do arquivo:

```tsx
/**
 * Interactive image cropper.
 *
 * @tempest-limits file-lines — pointer drag, wheel zoom, aspect-ratio clamping
 * and canvas export share one piece of geometry state. Splitting them would mean
 * threading that state through props and duplicating the clamp maths.
 */
```

- A **regra** é o id da tabela abaixo (`file-lines`, `props-count`, …), várias
  separadas por vírgula, ou `*` para todas.
- O **motivo** vem depois de `—`, `-` ou `:`. Menos de 12 caracteres não conta
  como motivo: o `tempest doctor` reporta o marcador vazio, porque waiver sem
  explicação é exatamente o que ele existe pra evitar.

!!! tip "O que não é aceitável é estourar sem perceber"
    O marcador não é burocracia — é o que transforma "esse arquivo é grande" de
    acidente em decisão. Quem ler daqui a seis meses sabe se pode quebrar.

!!! info "`eslint-disable` também vale"
    Um `// eslint-disable-next-line @typescript-eslint/no-explicit-any` já
    silencia o `any` daquela linha no `doctor` — o mecanismo padrão ganha, sem
    precisar de um segundo marcador.

## `tempest doctor` já cobra isso

O [CLI](../cli.md) tem uma seção **Design** que mede o projeto e reporta cada
estouro com arquivo e linha:

```bash
npx tempest doctor              # inclui a análise de design
npx tempest doctor --no-design  # pula a seção
```

```text
Design
  [i] 42 source file(s) · 1830 lines of code · median 38 — largest: src/pages/Orders.tsx (204)
  [!] src/pages/Orders.tsx:1 — 204 lines of code (limit 150) — extract a sub-component, a hook or a pure function
  [!] src/pages/Orders.tsx:31 — a component must not call the network — move it to a service and read it with useQuery
  [!] src/features/orders/OrderTable.tsx:12 — OrderTableProps has 9 props (limit 7) — likely two components in one
  [i] 2 limit(s) waived with a written reason — @tempest-limits markers — nothing to do
```

As regras, e o id de cada uma pro marcador:

| Id                     | O que mede                                                       |
| ---------------------- | ---------------------------------------------------------------- |
| `file-lines`           | linhas de código do arquivo (150 `.tsx` / 200 `.ts`)             |
| `function-lines`       | corpo de função/componente (80)                                  |
| `hook-lines`           | corpo de hook `use*` (100)                                       |
| `props-count`          | membros de `<X>Props` ou props desestruturadas (7)               |
| `param-count`          | parâmetros de função **exportada** (3)                           |
| `explicit-any`         | `any` em posição de tipo, `as any`                               |
| `ts-ignore`            | `@ts-ignore` / `@ts-nocheck`                                     |
| `fetch-in-component`   | `fetch(`/`axios` num `.tsx`                                      |
| `empty-catch`          | `catch` de corpo vazio                                           |
| `inline-style-literal` | cor literal dentro de `style={{ … }}`                            |

!!! note "A seção Design nunca falha o exit code"
    Todos os achados são `warn` ou nota. Limite é heurística com saída de
    emergência escrita — falhar o CI por heurística é o caminho mais rápido pra
    alguém silenciar a ferramenta. Os gates duros continuam onde devem estar:
    `no-explicit-any` como `error` no ESLint e `tsc --noEmit`.

!!! info "O que a análise **não** julga"
    Três classes de arquivo saem antes de qualquer regra rodar, porque a resposta
    para um achado nelas não está no arquivo:

    - **Código gerado ou vendorado** — qualquer arquivo cujo cabeçalho traga
      `@generated` ou `Do not hand-edit`. É a forma que o upstream escolheu, e uma
      edição aqui morre na próxima regeneração. O `src/vision/` deste SDK é assim:
      cada arquivo sai carimbado do `npm run vendor:vision`.
    - **Barrel** — arquivo que só re-exporta. Um `index.ts` de 350 linhas de
      `export { X } from "./x"` é uma listagem de diretório, e "extraia um
      sub-componente" não quer dizer nada ali.
    - **Arquivo de teste** — para as regras de tamanho. Um teste longo é
      normalmente um teste completo.

!!! note "Uma contagem de props, não duas"
    Quando o componente desestrutura exatamente as props que o `<Nome>Props`
    declara, o achado sai **uma** vez, no tipo. Duas linhas para o mesmo fato leem
    como dois problemas. A desestruturação só vira achado próprio quando passa do
    que o tipo declara — aí ela está recebendo props de outro lugar.

!!! info "O que o doctor **não** mede"
    Profundidade de aninhamento JSX e complexidade ciclomática. As duas precisam
    de um parser de verdade pra não gerar falso positivo com quebra de linha do
    Prettier — ficam com o ESLint (`max-depth`, `complexity`) e com a revisão.

## Como fazer o linter cobrar também

Adicione ao `eslint.config.js` do seu app (o
[template do scaffold](../scaffold.md) traz a base; isto é a camada de design):

```js
{
    files: ["**/*.{ts,tsx}"],
    rules: {
        "max-lines": [
            "warn",
            { max: 150, skipBlankLines: true, skipComments: true },
        ],
        "max-lines-per-function": [
            "warn",
            { max: 80, skipBlankLines: true, skipComments: true },
        ],
        "max-depth": ["warn", 4],
        "max-params": ["warn", 3],
        complexity: ["warn", 10],
        "@typescript-eslint/no-explicit-any": "error",
    },
},
{
    // Testes descrevem cenários; contá-los como código de produção só produz
    // ruído e incentiva teste menos legível.
    files: ["**/*.test.{ts,tsx}"],
    rules: {
        "max-lines": "off",
        "max-lines-per-function": "off",
    },
},
```

!!! warning "`warn` nos limites, `error` na tipagem"
    Limite de tamanho é heurística — `error` transforma cada exceção legítima num
    `eslint-disable`, e `eslint-disable` espalhado é pior que arquivo grande.
    `warn` aparece no PR e alguém decide. Já `no-explicit-any` é `error`: não tem
    caso legítimo que valha o silêncio (veja [Tipagem forte](typing.md)).

Rodando:

```bash
npx tempest lint                      # ESLint com a config do projeto
npx tempest lint --max-warnings 0     # no CI, quando quiser o limite duro
```

Detalhes do CLI em [CLI tempest](../cli.md).

## Encontrando os estouros hoje

Antes de ligar a regra, veja o tamanho do problema:

```bash
# Top 15 arquivos por linhas de código (ignora blank, // e blocos /* */)
find src -name "*.tsx" ! -name "*.test.tsx" | while read -r f; do
  n=$(grep -vcE '^\s*($|//|/\*|\*|\*/)' "$f")
  echo "$n $f"
done | sort -rn | head -15
```

Se aparecerem 3 arquivos acima do limite, corrija hoje. Se aparecerem 60, ligue a
regra como `warn` e resolva o que você já ia tocar — refatoração em massa gera PR
irrevisável e nenhum ganho imediato.

## Os três cortes que resolvem 90% dos casos

### 1. Sub-componente por bloco de JSX

O `.tsx` de 300 linhas quase sempre é 4 blocos visuais num arquivo. Cada bloco
com nome próprio:

```text
OrderDetail.tsx (300)
└── OrderDetail.tsx (60) + OrderHeader.tsx (50) + OrderItems.tsx (70) + OrderTotals.tsx (40)
```

### 2. Hook pra lógica

Estado + efeitos + handlers saem pro `use-<coisa>.ts`. O `.tsx` fica só com
marcação. Exemplo completo em
[Pensando em componentes](components.md#logic-to-hook).

### 3. Função pura pra fora do React

`sortBy`, `paginate`, `formatInvoice`, `buildQuery` não precisam de React —
vão pra `lib/` ou pro arquivo da feature, e ganham teste unitário barato.

!!! danger "Corte que não vale: mover o JSX pra uma função no mesmo arquivo"
    ```tsx
    function renderHeader() { … }   // ❌ não é componente, não é reusável
    ```
    Isso reduz a contagem de linhas da função e não reduz nada do que importa: o
    arquivo continua do mesmo tamanho e o "componente interno" não pode ser
    memoizado, testado nem reusado. Extraia de verdade.

## Recap

- Limite vira número pra parar de ser discussão de gosto: **150** arquivo, **80**
  função, **100** hook, **7** props, **4** aninhamento, **10** complexidade.
- Linha é proxy de **carga cognitiva** — conte linhas de código, não JSDoc.
- O SDK tem mediana 65 e 28 estouros conscientes; a saída de emergência é
  `@tempest-limits <regra> — <motivo>`, nunca o silêncio.
- `npx tempest doctor` mede e reporta com arquivo e linha (sempre `warn`); o
  ESLint cobra com `max-lines` e `no-explicit-any` como `error`.
- Três cortes resolvem quase tudo: sub-componente, hook, função pura.

Próxima: [Tipagem forte](typing.md).

---

# design/state.md

# Onde mora cada estado

Quase todo bug difícil de app frontend é a mesma coisa: **duas fontes de verdade
pro mesmo dado**. A lista veio do servidor e também está num `useState`; o filtro
está na URL e também num store; o total é campo e também é soma. Uma das duas
sempre fica velha.

A cura não é uma biblioteca melhor. É decidir, pra cada pedaço de estado, **um**
lugar onde ele mora.

## Cinco lugares, cinco perguntas

```mermaid
flowchart TD
    Q1{"Dá pra calcular<br/>do que já existe?"} -->|sim| DER["Não é estado.<br/>Calcule no render."]
    Q1 -->|não| Q2{"Veio do servidor?"}
    Q2 -->|sim| SRV["TanStack Query"]
    Q2 -->|não| Q3{"Deve sobreviver a<br/>reload / link compartilhado?"}
    Q3 -->|sim| URL["URL (searchParams)"]
    Q3 -->|não| Q4{"É campo de formulário?"}
    Q4 -->|sim| FORM["react-hook-form"]
    Q4 -->|não| Q5{"Mais de uma tela<br/>precisa disso?"}
    Q5 -->|sim| GLB["Store Zustand"]
    Q5 -->|não| LOC["useState local"]
```

| Tipo de estado             | Mora em                              | Exemplo                             |
| -------------------------- | ------------------------------------ | ----------------------------------- |
| **Derivado**               | nada — calcule                       | total, `isValid`, contagem, label   |
| **De servidor**            | [TanStack Query](../query.md)         | lista de pedidos, perfil            |
| **De navegação**           | URL (`useSearchParams`)              | página, filtro, aba, busca          |
| **De formulário**          | [`useZodForm`](../forms.md)           | campos, erros, `isSubmitting`       |
| **Global de cliente**      | [`createStore`](../state.md)          | sessão, tema, carrinho, preferência |
| **Local de UI**            | `useState`                           | modal aberto, hover, acordeão       |
| **Offline persistido**     | [`createOfflineStore`](../offline.md) | outbox, cache Dexie                 |

## 1. Derivado não é estado {#derived}

O erro mais comum e o mais barato de corrigir:

=== "❌ Errado"

    ```tsx
    const [orders, setOrders] = useState<Order[]>([]);
    const [total, setTotal] = useState(0);

    useEffect(() => {
      setTotal(orders.reduce((sum, o) => sum + o.totalCents, 0));
    }, [orders]);
    ```

    Duas fontes, um `useEffect` de sincronização e uma janela de render em que
    `total` está errado.

=== "✅ Certo"

    ```tsx
    const [orders, setOrders] = useState<Order[]>([]);
    const total = orders.reduce((sum, o) => sum + o.totalCents, 0);
    ```

    Uma fonte. Impossível divergir.

!!! tip "`useEffect` que só chama `setState` é quase sempre estado derivado"
    Procure por esse padrão no seu app — é o achado com melhor relação
    esforço/ganho que existe. E não, você não precisa de `useMemo` pra isso:
    memoize quando **medir** que o cálculo é caro, não por reflexo.

## 2. Dado de servidor não vive em `useState`

=== "❌ Errado"

    ```tsx
    const [orders, setOrders] = useState<Order[]>([]);
    const [isLoading, setIsLoading] = useState(true);
    const [error, setError] = useState<Error | null>(null);

    useEffect(() => {
      let alive = true;
      listOrders(page)
        .then((data) => alive && setOrders(data))
        .catch((e) => alive && setError(e))
        .finally(() => alive && setIsLoading(false));
      return () => {
        alive = false;
      };
    }, [page]);
    ```

=== "✅ Certo"

    ```tsx
    const { data: orders = [], isLoading, error } = useOrders(page);
    ```

O primeiro tem 3 estados pra manter em sincronia, uma flag `alive` pra evitar
setState depois do unmount, zero cache, zero dedupe entre componentes, zero
revalidação ao voltar pra aba. O segundo tem tudo isso — porque **estado de
servidor é cache**, e cache é um problema resolvido.

!!! info "Foco no que a Query já faz por você"
    Dedupe de requests simultâneos, `staleTime`, refetch em foco/reconexão,
    retry, mutation otimista, invalidação por key, persistência offline. Cada uma
    dessas linhas é um bug que você não escreve. Veja [Query](../query.md).

## 3. Estado de navegação mora na URL

Filtro, página, ordenação, aba ativa, termo de busca: se o usuário puder querer
**mandar o link pra alguém**, o estado é da URL.

```tsx
import { useSearchParams } from "tempest-react-sdk";

/**
 * Orders screen. Page and status live in the query string, so the browser back
 * button, refresh and a shared link all restore the same view.
 */
export function Orders() {
  const [params, setParams] = useSearchParams();

  const page = Number(params.get("page") ?? 1);
  const status = params.get("status") ?? "all";

  const setStatus = (next: string) => {
    setParams({ status: next, page: "1" });
  };

  const { data = [], isLoading } = useOrders({ page, status });
  // …
}
```

Repare: nenhum `useState`. Nenhum `useEffect` sincronizando URL com estado. A URL
**é** o estado.

!!! warning "Duplicar a URL num `useState` é o clássico"
    `const [page, setPage] = useState(Number(params.get("page")))` cria a segunda
    fonte de verdade na hora: o botão voltar muda a URL e não muda o `useState`.
    Leia da URL a cada render — é barato e sempre correto.

## 4. Formulário tem dono próprio

Campo controlado por `useState` é `onChange` re-renderizando a tela inteira a cada
tecla, validação escrita à mão e erro fora de sincronia:

```tsx
import { FormField, Input, useZodForm } from "tempest-react-sdk";
import { z } from "zod";

const schema = z.object({
  name: z.string().min(3, "Mínimo 3 caracteres"),
  email: z.string().email("E-mail inválido"),
});

/** Customer form: one schema drives types, validation and error messages. */
export function CustomerForm({ onSave }: { onSave: (v: z.infer<typeof schema>) => void }) {
  const form = useZodForm(schema);

  return (
    <form onSubmit={form.handleSubmit(onSave)}>
      <FormField name="name" label="Nome" control={form.control}>
        <Input />
      </FormField>
      <FormField name="email" label="E-mail" control={form.control}>
        <Input type="email" />
      </FormField>
      <button type="submit" disabled={form.formState.isSubmitting}>
        Salvar
      </button>
    </form>
  );
}
```

Um schema gera **três** coisas: o tipo TypeScript, a validação em runtime e a
mensagem de erro. Detalhes em [Forms (zod)](../forms.md).

## 5. Global de cliente: store, e só o necessário

Store é pra estado que **não** vem do servidor e **várias** telas precisam:
sessão, tema, carrinho, preferências, wizard multi-etapa.

```ts
// src/stores/cart.ts
import { createSelectors, createStore } from "tempest-react-sdk";

interface CartState {
  items: string[];
  add: (id: string) => void;
  clear: () => void;
}

/**
 * Cart slice. Only `items` is persisted — the actions are recreated on load,
 * so writing them to storage would just bloat the payload.
 */
export const useCart = createSelectors(
  createStore<CartState>(
    (set) => ({
      items: [],
      add: (id) => set((s) => ({ items: [...s.items, id] })),
      clear: () => set({ items: [] }),
    }),
    { persist: { name: "cart", partialize: (s) => ({ items: s.items }) } },
  ),
);
```

O `createSelectors` gera `useCart.use.items()` — o componente assina **um campo**
em vez do store inteiro, e não re-renderiza quando outro campo muda.

!!! danger "Store não é cache de servidor"
    Colocar a lista de pedidos num Zustand store recria à mão tudo que a Query já
    faz — e sem invalidação, sem revalidação, sem dedupe. O sintoma é sempre o
    mesmo: a tela mostra dado velho depois de um POST.

## 6. Local de UI: `useState` sem culpa

Modal aberto, item em hover, acordeão expandido, índice do carrossel. Nada disso
precisa de biblioteca:

```tsx
const [isOpen, setIsOpen] = useState(false);
```

Se só **um** componente e seus filhos diretos precisam, `useState` é a resposta
certa. Subir isso pra store global é acoplamento gratuito.

## O teste dos 10 segundos

Olhe um `useState` do seu app e pergunte, nessa ordem:

1. Consigo **calcular** isso? → apague.
2. Isso **veio da rede**? → Query.
3. Faz sentido no **link**? → URL.
4. É **campo**? → form.
5. **Outra tela** precisa? → store.
6. Nenhuma? → fica onde está. Está certo.

## Recap

- Bug de estado é quase sempre **duas fontes de verdade**.
- Derivado não é estado: calcule no render, não sincronize com `useEffect`.
- Servidor → **Query**. Navegação → **URL**. Campo → **form**. Compartilhado →
  **store**. Só aqui → **`useState`**.
- `createSelectors` faz o componente assinar um campo, não o store inteiro.
- Store nunca substitui cache de servidor.

Próxima: [Pensando em componentes](components.md).

---

# design/testing.md

# Estratégia de testes

Teste de frontend tem uma armadilha própria: é fácil escrever muitos testes que
não protegem nada. Eles verificam que o componente renderiza o texto que o
componente renderiza, quebram a cada refatoração e passam mesmo quando o app está
quebrado.

A pergunta que separa teste bom de teste ruim é sempre a mesma: **que bug esse
teste teria pegado?** Se não tem resposta, apague.

## O que testar em cada camada

As [camadas](architecture.md) definem o tipo de teste. Não é a mesma técnica em
todas:

| Camada        | Técnica                          | O que verifica                                | Quantidade |
| ------------- | -------------------------------- | --------------------------------------------- | ---------- |
| Função pura   | teste unitário                    | entrada → saída, incluindo borda              | muitos     |
| Serviço       | unitário com `fetch` mockado      | monta request, valida resposta, mapeia erro   | muitos     |
| Hook          | `renderHook`                      | transição de estado, efeito, cleanup          | muitos     |
| Componente UI | `render` + `screen` por **papel** | o que o usuário vê e consegue fazer           | médio      |
| Página        | render com provider + MSW         | a tela junta as peças                         | poucos     |
| Fluxo         | Playwright                        | o caminho crítico ponta a ponta               | pouquíssimos |

```mermaid
flowchart TD
    A["Funções puras + serviços + hooks<br/>(rápidos, muitos)"] --> B["Componentes<br/>(médios)"]
    B --> C["Páginas com MSW<br/>(poucos)"]
    C --> D["E2E Playwright<br/>(caminho crítico só)"]
```

!!! tip "Teste barato primeiro"
    Um teste de função pura roda em milissegundos e nunca fica instável. Um E2E
    roda em segundos e quebra por timing. Empurre a verificação pro nível mais
    barato que consegue provar a coisa — e é a arquitetura em camadas que dá essa
    opção.

## Ferramenta: o que o SDK usa

```bash
npm test              # vitest watch
npm run test:run      # uma passada
npm run test:coverage
npm run typecheck     # tsc -b --noEmit (inclui os testes)
```

Stack: **Vitest** + **@testing-library/react** + **jsdom**, com
`fake-indexeddb/auto` no setup pra Dexie funcionar em Node. O
[template do scaffold](../scaffold.md) já vem com isso.

Números deste repositório, como referência do que é sustentável: **3283 testes em
414 arquivos, ~29 s**. Os pisos de cobertura que gateiam o CI:

| Métrica    | Piso |
| ---------- | ---- |
| lines      | 98%  |
| statements | 97%  |
| functions  | 96%  |
| branches   | 94%  |

!!! warning "Cobertura é piso, não meta"
    100% de cobertura com asserts fracos protege menos que 80% com asserts que
    checam comportamento. O piso serve pra impedir código **não exercitado
    nenhuma vez** — ele não mede qualidade de teste.

## Componente: consulte por papel, não por classe

A regra que decide se o teste vai sobreviver a uma refatoração:

=== "✅ Certo"

    ```tsx
    it("dispara onPay ao clicar em Pagar", async () => {
      const onPay = vi.fn();
      const user = userEvent.setup();

      render(<OrderTable orders={[order]} onPay={onPay} />);
      await user.click(screen.getByRole("button", { name: "Pagar" }));

      expect(onPay).toHaveBeenCalledWith(order.id);
    });
    ```

=== "❌ Errado"

    ```tsx
    it("renderiza a tabela", () => {
      const { container } = render(<OrderTable orders={[order]} onPay={vi.fn()} />);
      expect(container.querySelector(".tempest_table_3f9a")).toBeTruthy();
    });
    ```

O primeiro teste falha quando o comportamento muda. O segundo falha quando o
**CSS** muda — e passa mesmo se o botão parar de funcionar. Ele é pior que
nenhum teste, porque dá confiança falsa.

Ordem de preferência de consulta:

1. `getByRole` (com `name`) — é o que o usuário e o leitor de tela veem.
2. `getByLabelText` — campos de formulário.
3. `getByText` — conteúdo visível.
4. `getByTestId` — último recurso, quando não existe papel nem texto estável.

!!! info "Consultar por papel testa acessibilidade de graça"
    Se `getByRole("button", { name: "Pagar" })` não acha, é porque você usou
    `<div onClick>` ou esqueceu o nome acessível. O teste te avisa de um problema
    real de a11y sem você escrever um teste de a11y.

## Serviço: mocke `fetch`, não o serviço

```ts
import { describe, expect, it, vi } from "vitest";

import { listOrders } from "./orders.service";

describe("listOrders", () => {
  it("valida a resposta e converte createdAt em Date", async () => {
    vi.stubGlobal(
      "fetch",
      vi.fn().mockResolvedValue(
        new Response(
          JSON.stringify([
            {
              id: "3f2a…",
              code: "PED-1",
              status: "paid",
              total_cents: 1990,
              created_at: "2026-07-28T12:00:00Z",
            },
          ]),
          { status: 200, headers: { "Content-Type": "application/json" } },
        ),
      ),
    );

    const orders = await listOrders(1);

    expect(orders[0].createdAt).toBeInstanceOf(Date);
    expect(orders[0].totalCents).toBe(1990);
  });

  it("rejeita payload fora do schema", async () => {
    vi.stubGlobal(
      "fetch",
      vi.fn().mockResolvedValue(new Response(JSON.stringify([{ id: 1 }]), { status: 200 })),
    );

    await expect(listOrders(1)).rejects.toThrow();
  });
});
```

O segundo teste é o que justifica o `parseResponse` existir. Sem ele, o schema é
decoração.

## Página: MSW com `createMockHandlers`

Teste de página verifica que as peças se encaixam — não repete o que o teste do
componente já cobriu:

```ts
import { createMockHandlers } from "tempest-react-sdk/testing";

export const orderHandlers = createMockHandlers([
  { method: "GET", path: "/orders", body: [{ id: "1", code: "PED-1", status: "paid" }] },
  { method: "POST", path: "/orders/1/pay", status: 200, body: { id: "1", status: "paid" } },
  { method: "GET", path: "/orders/999", status: 404, body: { detail: "Not found" } },
]);
```

Um handler por cenário, incluindo o de erro — a tela de erro é a que ninguém testa
e a que o usuário mais vê. Detalhes em [Testing helpers](../testing.md).

## Hook: `renderHook` sem DOM

```ts
import { renderHook } from "@testing-library/react";
import { act } from "react";

it("alterna a seleção de uma linha", () => {
  const { result } = renderHook(() => useOrderTable([order]));

  act(() => result.current.toggle(order.id));
  expect(result.current.selected.has(order.id)).toBe(true);

  act(() => result.current.toggle(order.id));
  expect(result.current.selected.has(order.id)).toBe(false);
});
```

É por isso que [extrair lógica pra hook](components.md#logic-to-hook)
compensa: você testa a regra sem montar tabela, sem procurar botão, sem esperar
render.

## O que **não** testar

| Não teste                                    | Porque                                            |
| -------------------------------------------- | ------------------------------------------------- |
| Que o componente do SDK funciona             | ele já tem 3283 testes                            |
| Classe CSS, estrutura de DOM, snapshot grande | quebra em refatoração, não pega bug               |
| Implementação interna (`useState` chamado)   | você testou o código, não o comportamento         |
| Getter/setter trivial                        | não existe bug possível ali                       |
| Que `zod` valida                             | é a lib; teste **o seu schema** com payload errado |

!!! danger "Snapshot grande é dívida disfarçada de cobertura"
    Um `toMatchSnapshot()` de 400 linhas passa a ser atualizado com `-u` sem
    ninguém ler o diff. Ele deixa de ser teste e vira ruído no PR. Snapshot vale
    pra saída pequena e estável (uma string formatada, um objeto de config).

## Acessibilidade e pixel

Duas coisas que teste em jsdom **não** pega:

- **Contraste de cor.** O `axe` desliga a regra `color-contrast` em jsdom porque
  não há paint. Esse bug só aparece em browser real — aconteceu duas vezes neste
  repositório com token de texto sobre superfície tingida.
- **Layout.** jsdom não calcula layout: `offsetParent` é sempre `null`, altura é
  sempre 0.

Por isso o CI tem um smoke Playwright no [gallery](../gallery.md) além do sweep
`axe` em jsdom. Para o seu app: mudança visual se valida em browser, não em
`expect`.

## Recap

- Todo teste responde "**que bug isso pegaria?**". Sem resposta, apague.
- Camada define técnica: função/serviço/hook unitário (muitos) → componente
  (médio) → página com MSW (poucos) → E2E (pouquíssimos).
- Consulte por **papel**, nunca por classe CSS — e ganhe verificação de a11y de
  graça.
- Serviço testa com `fetch` mockado, **incluindo payload inválido**.
- Cobertura é piso (98/97/96/94 aqui), não meta.
- Contraste e layout só se validam em **browser real**.

Próxima: [Anti-padrões](anti-patterns.md).

---

# design/typing.md

# Tipagem forte

TypeScript não é "JavaScript com autocomplete". É a única ferramenta que verifica
o desenho do seu app **sem rodar o app**. Quanto mais estreito o tipo, mais bug
ele pega de graça.

O objetivo desta página: fazer o compilador recusar o estado errado, em vez de
você revisar o estado errado.

## Regra zero: zero `any`

```js
"@typescript-eslint/no-explicit-any": "error"
```

`any` desliga o compilador. Pior: ele **vaza** — uma variável `any` contamina
tudo que toca nela, e o erro aparece três arquivos depois, em runtime.

Não existe caso legítimo. Existem dois substitutos:

| Situação                                 | Use                                        |
| ---------------------------------------- | ------------------------------------------ |
| Não sei o que é (resposta de rede, `JSON.parse`) | **`unknown`** + validação            |
| Aceito qualquer objeto                   | `Record<string, unknown>`                  |
| Genérico de verdade                      | `<T>` com constraint                        |

```ts
// ❌ any: o erro vai aparecer em outro arquivo
function handle(payload: any) {
  return payload.user.name.toUpperCase();
}

// ✅ unknown: o compilador exige que você prove a forma antes de usar
function handle(payload: unknown): string {
  const parsed = userSchema.parse(payload);
  return parsed.name.toUpperCase();
}
```

!!! danger "`as` é `any` com outro nome"
    `payload as User` não verifica nada — é você prometendo. `as` só é aceitável
    em três lugares: `as const`, estreitar `unknown` **depois** de um type guard,
    e contornar limitação conhecida de tipagem de lib (com JSDoc explicando).
    Fora disso, `as` é onde os bugs entram.

## Tipo derivado do schema, nunca escrito duas vezes

O erro mais comum em app com zod: escrever a `interface` e o schema
separados.

=== "❌ Errado"

    ```ts
    interface Order {
      id: string;
      status: string;
      totalCents: number;
    }

    const orderSchema = z.object({
      id: z.string(),
      status: z.string(),
      total_cents: z.number(), // ⚠️ divergiu e ninguém percebe
    });
    ```

=== "✅ Certo"

    ```ts
    export const orderSchema = z.object({
      id: z.string().uuid(),
      status: z.enum(["pending", "paid", "shipped", "delivered", "cancelled"]),
      totalCents: z.number().int().nonnegative(),
    });

    export type Order = z.infer<typeof orderSchema>;
    export type OrderStatus = Order["status"];
    ```

Uma fonte de verdade. Mudar o schema muda o tipo, e o compilador aponta cada lugar
que precisa acompanhar. Veja [Fluxo de dados](data-flow.md).

!!! tip "`z.enum` em vez de `z.string()`"
    `status: z.string()` aceita `"banana"`. `z.enum([...])` faz o `switch` no
    componente ficar exaustivo e o backend inventando valor novo virar erro na
    borda, não tela em branco.

## Union discriminada: o estado impossível deixa de existir

Este é o ganho mais alto de tipagem em app React, e o mais ignorado.

=== "❌ Errado — 8 combinações, 5 inválidas"

    ```ts
    interface OrderState {
      isLoading: boolean;
      data?: Order;
      error?: Error;
    }
    ```

    `{ isLoading: true, data: order, error: err }` compila. O que a tela mostra?

=== "✅ Certo — 3 estados, todos válidos"

    ```ts
    type OrderState =
      | { status: "loading" }
      | { status: "success"; data: Order }
      | { status: "error"; error: Error };
    ```

    ```tsx
    switch (state.status) {
      case "loading":
        return <Spinner />;
      case "success":
        return <OrderCard order={state.data} />; // `data` existe aqui, garantido
      case "error":
        return <ErrorState message={state.error.message} />;
    }
    ```

Dentro de cada `case`, o TypeScript sabe exatamente quais campos existem. Não tem
`state.data!`, não tem `if (!state.data) return null` defensivo.

### Exaustividade que o compilador cobra

```ts
/** Fails to compile when a new OrderState variant is added and not handled. */
function assertNever(value: never): never {
  throw new Error(`Unhandled variant: ${JSON.stringify(value)}`);
}

switch (state.status) {
  case "loading":
    return <Spinner />;
  case "success":
    return <OrderCard order={state.data} />;
  case "error":
    return <ErrorState message={state.error.message} />;
  default:
    return assertNever(state);
}
```

Adicione `{ status: "empty" }` na union e o build **quebra** no `assertNever`,
apontando o lugar exato. É a diferença entre descobrir na compilação e descobrir
em produção.

## Props: modele o que é válido

O mesmo raciocínio nas props de componente:

```tsx
// ❌ permite `variant="link"` sem `href`, e `href` com onClick
interface ButtonProps {
  variant?: string;
  href?: string;
  onClick?: () => void;
}

// ✅ ou é link com href, ou é botão com onClick — nunca os dois
type ButtonProps =
  | { as: "link"; href: string; children: ReactNode }
  | { as?: "button"; onClick: () => void; children: ReactNode };
```

E para variantes, `union` de string em vez de booleanas — o padrão de todo
componente do SDK:

```ts
export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger";
export type ButtonSize = "xs" | "sm" | "md" | "lg" | "xl";
```

O autocomplete mostra as opções, o typo não compila, e não existe
`primary danger`.

## Os utilitários que valem decorar

```ts
type Order = { id: string; code: string; status: OrderStatus; totalCents: number };

type OrderPreview = Pick<Order, "id" | "code">;          // só esses campos
type OrderDraft = Omit<Order, "id">;                      // tudo menos id
type OrderPatch = Partial<Order>;                         // tudo opcional
type FullOrder = Required<OrderDraft>;                    // tudo obrigatório
type OrderReadonly = Readonly<Order>;                     // sem mutação
type OrdersById = Record<string, Order>;                  // mapa
type OrderStatus2 = Order["status"];                      // acesso indexado
type ListResult = Awaited<ReturnType<typeof listOrders>>; // tipo do retorno async
```

O padrão: **derive**, não redigite. Um `OrderDraft` escrito à mão sai de sincronia
com `Order` na primeira mudança; `Omit<Order, "id">` não sai nunca.

## `satisfies`: valida sem alargar {#satisfies}

```ts
// ❌ o tipo da const vira Record<string, string> — perde as chaves exatas
const STATUS_LABEL: Record<OrderStatus, string> = {
  pending: "Pendente",
  paid: "Pago",
  shipped: "Enviado",
  delivered: "Entregue",
  cancelled: "Cancelado",
};

// ✅ valida que cobre todo OrderStatus E mantém as chaves literais
const STATUS_LABEL = {
  pending: "Pendente",
  paid: "Pago",
  shipped: "Enviado",
  delivered: "Entregue",
  cancelled: "Cancelado",
} satisfies Record<OrderStatus, string>;
```

Com `satisfies` você ganha as duas coisas: se faltar um status, erro de
compilação; e `typeof STATUS_LABEL` continua sabendo as chaves exatas para
autocomplete e para derivar tipos.

!!! tip "Tabela de lookup mata `switch` gigante"
    `STATUS_LABEL[status]` substitui cinco `case`. E com `satisfies`, adicionar um
    status novo à union **obriga** a preencher a tabela. Esse par
    (`union` + `satisfies Record<>`) é o jeito mais barato de fazer o compilador
    cobrar completude.

## Genérico com constraint, não genérico solto

```ts
// ❌ T não garante nada — `item.id` pode não existir
function indexById<T>(items: T[]): Record<string, T> {
  return Object.fromEntries(items.map((i) => [i.id, i])); // erro ou any
}

// ✅ a constraint documenta o requisito e o compilador cobra
function indexById<T extends { id: string }>(items: T[]): Record<string, T> {
  return Object.fromEntries(items.map((item) => [item.id, item]));
}
```

Constraint é documentação executável: quem chamar com `{ uuid: string }[]` recebe
erro na chamada, com a mensagem certa.

## Nulo explícito

`undefined` implícito é o `NullPointerException` do TypeScript. Deixe `strict`
ligado (o template já deixa) e trate na borda:

```ts
// ✅ o tipo diz que pode não achar; quem chama é obrigado a tratar
export async function findOrder(id: string): Promise<Order | null> {
  const raw = await api.get<unknown>(`/orders/${id}`).catch(() => null);
  return raw === null ? null : parseResponse(orderSchema, raw, "findOrder");
}
```

E do lado que usa, prefira early return a `?.` em cascata:

```tsx
if (!order) return <EmptyState title="Pedido não encontrado" />;
// daqui pra baixo `order` é Order, sem `?.` em nenhuma linha
```

!!! warning "`!` (non-null assertion) é promessa, não verificação"
    `order!.code` é você garantindo ao compilador algo que ele não conseguiu
    provar. Quando você estiver certo, funciona; quando estiver errado, é
    `undefined` em produção. Use early return.

## Coleção vazia é `[]`, não `null`

```ts
// ✅
function listOrders(): Promise<Order[]>;          // sem resultado → []
interface OrderResponse { items: Order[] }         // default: []

// ❌
function listOrders(): Promise<Order[] | null>;    // agora todo caller checa null
```

"Nenhum resultado" é um resultado bem-sucedido. Devolver `[]` faz o `.map()` do
componente funcionar sem `if`, e é a convenção que o backend Tempest também segue.

## Onde checar

```bash
npx tsc -b --noEmit     # inclui os testes — bug de tipo em teste também é bug
npx tempest lint
npx tempest doctor      # checa tsconfig strict, alias, env, CSS
```

O `typecheck` é o gate mais barato do CI: roda em segundos e pega o que nenhum
teste pegaria sem escrever o caso.

## Recap

- **Zero `any`.** `unknown` na borda + validação; `as` só em três casos raros.
- Tipo **derivado** do schema zod (`z.infer`), nunca escrito duas vezes.
- **Union discriminada** apaga o estado impossível; `assertNever` cobra
  exaustividade no build.
- Props modelam o que é válido: `union` de string, não booleana; variantes
  mutuamente exclusivas em union de objetos.
- Derive com `Pick`/`Omit`/`Partial`/`ReturnType`; valide com `satisfies`.
- Genérico com **constraint**; nulo explícito com early return; coleção vazia é
  `[]`.

Próxima: [Estratégia de testes](testing.md).

---

# device-capture.md

# Captura de dispositivo

Quatro APIs do navegador que não custam dependência nenhuma: a **câmera lendo códigos**
(`BarcodeScanner`, `useBarcodeScanner`), **vídeo gravado** (`useVideoRecorder`), a **tela
compartilhada** (`useScreenCapture`) e **fala virando texto** (`useSpeechRecognition`).

A fatia inteira mede **5,40 KB brotli** — e cada uma dessas quatro coisas é uma API que o
navegador já tem, não uma biblioteca que o SDK embarcou.

!!! tip "Se você só quer ler um código de barras, pule para [Ler códigos](#ler-codigos-comece-pelo-componente)"
    O resto da página é vídeo, tela e fala, e a camada de baixo de cada uma.

!!! info "A captura de **áudio** mora em outra página"
    Microfone, gravação de voz, medidor de nível e WAV estão em [Áudio](./audio.md). As
    duas páginas compartilham o mesmo motor de gravação e a mesma taxonomia de erro — o
    que muda é o dispositivo.

## Ler códigos: comece pelo componente

O SDK já tinha o [`QRCode`](./components/utility.md), que **só codifica**. O
`BarcodeScanner` fecha o ciclo:

```tsx
import { BarcodeScanner } from "tempest-react-sdk";

export function LeitorDeProdutos({ onProduto }: { onProduto: (gtin: string) => void }) {
  return (
    <BarcodeScanner
      formats={["ean_13", "qr_code", "code_128"]}
      onScan={({ rawValue, format }) => {
        if (format === "ean_13") onProduto(rawValue);
      }}
      footer={<small>Aponte para o código de barras da embalagem.</small>}
      unsupported={<CampoDigitarCodigo onSubmit={onProduto} />}
    />
  );
}
```

O que você ganha sem escrever nada:

| Você fez | O componente faz |
| --- | --- |
| nada | Visor de proporção fixa, cantos de mira e um indicador de varredura |
| nada | Loop de detecção que **não se sobrepõe** — nunca enfileira uma leitura sobre a anterior |
| nada | Suprime a repetição do mesmo código; um valor **diferente** passa na hora |
| nada | Lanterna, quando a câmera tem uma |
| nada | Erro de câmera classificado, com um botão de tentar de novo |
| `unsupported` | Onde não há decodificador, mostra o seu caminho alternativo em vez de uma tela preta |

!!! danger "Montar o leitor abre a câmera — monte só quando o usuário pedir"
    O `useCameraStream` adquire no mount, então renderizar o scanner **é** disparar o
    prompt. Um prompt que o usuário não provocou é a forma mais confiável de ganhar um
    **Block permanente** — e depois disso o `getUserMedia` rejeita sem nunca mais
    perguntar, o que também queima a *próxima* feature que precisar da câmera. O padrão é
    um botão que revela o leitor:

    ```tsx
    const [lendo, setLendo] = useState(false);

    return lendo ? (
      <BarcodeScanner onScan={aceitar} />
    ) : (
      <Button onClick={() => setLendo(true)}>Ler código</Button>
    );
    ```

### `BarcodeDetector` não existe em metade dos navegadores

Essa é a parte que decide o desenho da sua tela, então está aqui e não numa nota de pé:

| Motor | Tem `BarcodeDetector`? |
| --- | --- |
| Chromium no Android e ChromeOS | **sim** |
| Chromium no macOS | em geral sim |
| Chromium no Windows e Linux | **não** |
| Firefox (qualquer sistema) | **não** |
| Qualquer navegador no iOS (todos são WebKit por baixo, Chrome incluído) | **não** |

O SDK **não embarca decodificador nenhum**, e isso é uma escolha, não uma lacuna: um
leitor de QR é correção de erro Reed–Solomon mais correção de perspectiva mais busca de
padrão de localização, e as opções honestas eram um build WASM que **todo** consumidor
deste SDK carregaria, ou nada. Então o que existe é a costura:

```tsx
import { BarcodeDetector } from "barcode-detector/pure"; // ou seu wrapper de zxing-wasm
import { BarcodeScanner } from "tempest-react-sdk";

<BarcodeScanner
  detector={new BarcodeDetector({ formats: ["qr_code", "ean_13"] })}
  onScan={aceitar}
/>;
```

Qualquer objeto com um `detect(source)` que resolva com `{ rawValue }` serve — é o que a
interface `BarcodeDetectorLike` diz, e é o que os testes do SDK exercitam com um
decodificador de verdade.

!!! check "Você não precisa de decodificador nenhum para o caso mais comum"
    Em telas de operação (conferência de carga, PDV, inventário) o alvo é um celular
    Android, onde a API existe. `unsupported` cobre o desktop do escritório com um campo
    de digitar — que costuma ser o que o operador prefere de teclado, aliás.

### Props

| Prop | Tipo | Default | O que faz |
| --- | --- | --- | --- |
| `onScan` | `(result: BarcodeScanResult) => void` | — | Cada leitura aceita. |
| `formats` | `BarcodeFormat[]` | `DEFAULT_BARCODE_FORMATS` = `["qr_code","ean_13","code_128"]` | Cada símbolo extra é trabalho por frame. `ALL_BARCODE_FORMATS` traz o domínio inteiro, para montar um seletor. |
| `paused` | `boolean` | `false` | Para de procurar **sem** soltar a câmera. |
| `detector` | `BarcodeDetectorLike` | — | Polyfill injetado. |
| `intervalMs` | `number` | `200` | Frequência com que um frame é examinado. |
| `repeatDelayMs` | `number` | `2500` | Janela em que o mesmo valor não dispara de novo. |
| `torch` | `boolean` | `true` | Oferece a lanterna quando a câmera tem uma. |
| `aspectRatio` | `number` | `4 / 3` | Proporção do visor. |
| `locale` | `"pt-BR" \| "en"` | `"pt-BR"` | Rótulos. |
| `footer` · `unsupported` | `ReactNode` | — | Instrução e caminho alternativo. |
| `onError` | `(error: unknown) => void` | — | Frame que o motor recusou (rotineiro). |

`BarcodeScanResult = { rawValue, format, boundingBox, cornerPoints }` — `boundingBox` é
`null` e `cornerPoints` é `[]` quando o motor não reporta geometria.

### Os formatos que importam aqui

Três carregam o peso no Brasil: **`ean_13`** é o código de barras de todo produto
embalado, **`qr_code`** é onde viaja um "copia e cola" do Pix, e **`code_128`** é a
etiqueta de uma remessa. O default é exatamente esses três.

!!! warning "Pedir um formato que o motor não tem faz o construtor lançar"
    `NotSupportedError`, que parece bug no seu código. A lista de formatos é do
    decodificador **da plataforma**, não do navegador, então dois Chromium em dois
    sistemas respondem diferente. O hook resolve isso pedindo a interseção — e você pode
    olhar antes:

    ```tsx
    import { getSupportedBarcodeFormats } from "tempest-react-sdk";

    const formatos = await getSupportedBarcodeFormats(); // [] onde não há decodificador
    ```

### Supressão de repetição não é detalhe

Um símbolo fica em quadro enquanto o usuário mantém a câmera ali. Sem supressão, o mesmo
código dispara cinco vezes por segundo — e ligado em "adicionar ao carrinho" isso é um bug
que o cliente paga. `repeatDelayMs` (2,5 s por padrão) é a janela em que **o mesmo** valor
é ignorado; um valor diferente nunca é.

Se a sua tela abre uma confirmação depois da leitura, use `paused` enquanto ela estiver
aberta — para de procurar sem soltar a câmera, então fechar a confirmação não custa outro
round-trip de permissão.

### Lanterna

```tsx
import { useTorch } from "tempest-react-sdk";

const torch = useTorch(stream);
{torch.supported && <button onClick={() => void torch.toggle()}>Lanterna</button>}
```

!!! info "A lanterna não é um dispositivo — é uma constraint numa track viva"
    Não há o que controlar antes de existir stream de câmera, e ela desaparece quando o
    stream é liberado. É por isso que `supported` só pode ser respondido depois: o mesmo
    código dá `true` na câmera traseira de um Android e `false` na frontal do mesmo
    aparelho. Onde nem `getCapabilities()` nem `getSettings()` mencionam `torch`, o hook
    diz `false` em vez de oferecer um botão que não faz nada.

### Montando você mesmo: `useBarcodeScanner`

```tsx
import { useBarcodeScanner } from "tempest-react-sdk";

export function LeitorProprio() {
  const scanner = useBarcodeScanner({
    formats: ["ean_13"],
    onScan: ({ rawValue }) => console.log(rawValue),
  });

  if (!scanner.supported) return <p>Este navegador não decodifica códigos.</p>;

  return (
    <>
      <video ref={scanner.videoRef} muted playsInline style={{ width: "100%" }} />
      <p>{scanner.scanning ? "Procurando…" : scanner.status}</p>
      {scanner.error && <p role="alert">{scanner.error.message}</p>}
    </>
  );
}
```

O loop se re-agenda **depois** que cada `detect()` resolve, não num `setInterval`:
decodificar às vezes leva mais que o intervalo, e um intervalo enfileiraria chamadas mais
rápido do que o motor as drena até a aba travar.

## Gravar vídeo

`useVideoRecorder` é o `useAudioRecorder` com uma track de vídeo e `videoBitsPerSecond` —
o relógio que **desconta pausa**, o `stop()` que resolve com todos os chunks na mão e a
negociação de container são os mesmos, porque são o mesmo motor.

```tsx
import { useScreenCapture, useVideoRecorder } from "tempest-react-sdk";

export function GravadorDeTela() {
  const screen = useScreenCapture({ preferCurrentTab: true });
  const rec = useVideoRecorder(screen.stream, {
    maxDurationMs: 120_000,
    videoBitsPerSecond: 2_500_000,
    onRecorded: ({ blob, durationMs }) => enviar(blob, durationMs),
  });

  return (
    <>
      <button onClick={screen.start}>Compartilhar tela</button>
      <button disabled={!rec.ready} onClick={rec.start}>Gravar</button>
      <button disabled={rec.status !== "recording"} onClick={() => void rec.stop()}>
        Parar
      </button>
      <span>{(rec.durationMs / 1000).toFixed(1)} s</span>
    </>
  );
}
```

`ready` fica `false` até existir stream, então a UI inteira pode ser renderizada
desabilitada enquanto o usuário ainda não escolheu a tela.

!!! warning "O container que sai não é o que você pediu"
    `VideoRecording.mimeType` é o que o navegador **reportou**, não o que foi negociado:
    entregamos `video/webm;codecs=vp9,opus` e o Chromium responde `video/webm;codecs=vp9`
    quando não há áudio. Use o valor que voltou para nomear o arquivo e para o
    `Content-Type` do upload. A ordem de preferência é VP9 → VP8 → WebM → MP4/H.264 (o
    último existe para o Safari, que não produz outra coisa).

!!! danger "Vídeo enche a memória uma ordem de magnitude mais rápido que áudio"
    Um minuto de 1080p a 2,5 Mbps é cerca de **19 MB** parados na memória até o `stop()`.
    Em qualquer captura que possa passar de alguns minutos, use `timesliceMs` e mande os
    pedaços embora:

    ```tsx
    useVideoRecorder(stream, {
      timesliceMs: 5_000,
      onChunk: (chunk) => void upload(chunk),
    });
    ```

    Os chunks **não** são tocáveis isoladamente: só o conjunto forma um arquivo válido.

!!! info "Não há medidor de nível aqui, e é de propósito"
    Medir nível num compartilhamento de tela significa abrir um `AudioContext` sobre um
    stream que quase sempre não tem track de áudio, e navegadores limitam contextos vivos
    (o Chrome permite ~6). Se você grava uma câmera **e** quer nível, rode o
    [`createLevelMeter`](./audio.md#nivel-de-gravacao) no mesmo stream.

O gravador **não** é dono do stream: parar a gravação deixa o compartilhamento vivo, porque
um fluxo de suporte normalmente grava, para, deixa a pessoa olhar e grava de novo.

## Compartilhar a tela

```tsx
import { useScreenCapture } from "tempest-react-sdk";

export function BotaoDeCompartilhar() {
  const screen = useScreenCapture({
    preferCurrentTab: true,
    audio: true,
    onCancelled: () => setDica("Você fechou o seletor — nada foi compartilhado."),
    onEnded: () => salvarEFechar(),
  });

  return (
    <>
      <button onClick={screen.start} disabled={screen.status === "sharing"}>
        Compartilhar tela
      </button>
      {screen.status === "sharing" && (
        <p>
          Compartilhando {screen.surface} · áudio: {screen.hasAudio ? "sim" : "não"}
        </p>
      )}
      {screen.error && <p role="alert">{screen.error.message}</p>}
    </>
  );
}
```

Três estados decidem se isso parece certo, e dois deles são fáceis de perder:

| Estado | O que aconteceu | O que o hook faz |
| --- | --- | --- |
| **Seletor fechado** | o usuário desistiu | volta para `idle`, `error` fica `null`, chama `onCancelled` |
| **Parou pela barra do navegador** | nada na sua UI foi clicado | limpa o stream, volta para `idle`, chama `onEnded` |
| **Compartilhando** | escolheu algo | `surface` diz o quê, `hasAudio` diz se veio áudio |

!!! danger "O evento `ended` é o único sinal de que o usuário parou de compartilhar"
    O Chrome mostra uma barra própria com "Parar compartilhamento". Quando ela é usada,
    **nenhuma promise rejeita** e nada na sua UI foi clicado — o único aviso é o evento
    `ended` da track de vídeo. Sem esse listener, o app fica exibindo "gravando" sobre um
    stream que já morreu. O hook escuta e limpa; você só precisa do `onEnded` se tiver algo
    a salvar.

!!! warning "Seletor fechado não é erro — e não existe exceção própria para ele"
    Fechar o seletor produz o mesmo `NotAllowedError` que um bloqueio por política, e
    algumas versões reportam `AbortError`. O hook trata os dois como **cancelamento**,
    porque um prompt de captura de tela é **sempre** iniciado pelo usuário — nada consegue
    abri-lo por trás — então a causa esmagadoramente provável é "mudei de ideia", e um
    toast vermelho para isso pune quem usou o seletor. A rejeição crua vai para
    `onCancelled`, se você precisar distinguir um bloqueio de sistema (permissão de
    gravação de tela do macOS).

### Dicas para o seletor

| Opção | Efeito |
| --- | --- |
| `displaySurface` | `"monitor"`, `"window"` ou `"browser"` (uma aba) primeiro na lista |
| `preferCurrentTab` | põe **esta** aba no topo — o certo para "grave o que você está vendo" |
| `selfBrowserSurface: "exclude"` | evita a captura em espelho infinito |
| `surfaceSwitching: "include"` | deixa trocar de superfície no meio, sem novo prompt |
| `systemAudio` | áudio do sistema quando a tela inteira é compartilhada |
| `audio: true` | pede o áudio da aba |

!!! warning "Tudo aí é dica, nunca garantia"
    O usuário pode escolher outra coisa, o Firefox ignora as dicas e o áudio de exibição só
    existe para **aba** no Chromium (o Safari não tem nenhum). Por isso o hook devolve
    `surface` e `hasAudio`: leia o que aconteceu, não o que você pediu.

## Fala → texto

```tsx
import { useSpeechRecognition } from "tempest-react-sdk";

export function CampoDitado({ onTexto }: { onTexto: (texto: string) => void }) {
  const speech = useSpeechRecognition({
    lang: "pt-BR",
    continuous: true,
    onFinal: (texto) => onTexto(texto),
  });

  if (!speech.supported) return null;

  return (
    <>
      <button onClick={speech.listening ? speech.stop : speech.start}>
        {speech.listening ? "Parar" : "Ditar"}
      </button>
      <p>
        {speech.transcript}
        <em>{speech.interim}</em>
      </p>
      {speech.error && <p role="alert">{speech.error.message}</p>}
    </>
  );
}
```

!!! danger "O reconhecimento não é local: o Chromium manda o áudio para um servidor do Google"
    Nada na API diz isso, não existe configuração que mude, e acontece a **cada**
    `start()`. Tudo o que o usuário falar enquanto a sessão está aberta sai do aparelho.
    Não coloque isso num campo de anotação clínica, de credencial ou de dado financeiro de
    cliente sem avisar antes — e se o dado não pode sair da sua infraestrutura, esta API é a
    ferramenta errada e um modelo self-hosted é a certa. Colocar o aviso na interface, ao
    lado do botão, é o mínimo.

### Interim e final

`transcript` acumula as frases que o motor **fechou**; `interim` é o palpite que ele ainda
está revisando e é substituído inteiro a cada evento. Renderizar `transcript + interim` dá
o efeito de legenda ao vivo; renderizar só `transcript` dá o texto confirmado.

| Opção | Default | O que faz |
| --- | --- | --- |
| `lang` | `"pt-BR"` | Tag BCP-47. |
| `continuous` | `false` | Continua depois da primeira frase fechar. |
| `interimResults` | `true` | Publica o palpite em andamento. |
| `maxAlternatives` | `1` | Quantas leituras por frase pedir. |
| `onResult` · `onFinal` · `onError` · `onEnd` | — | Cada atualização, só o texto fechado, falha classificada, fim da sessão. |
| `factory` | — | Construa o reconhecedor você mesmo — outro motor, ou um stub em teste. |

### Erros classificados

| `kind` | Causa | O que a UI deve fazer |
| --- | --- | --- |
| `unsupported` | Firefox e todo motor não-Chromium | esconda o botão |
| `not-allowed` | microfone negado (inclui `service-not-allowed`) | instrução para as configurações do site |
| `no-speech` | ninguém falou | **rotineiro** — não é falha para reportar |
| `audio-capture` | nenhum microfone no aparelho | diga isso |
| `network` | o serviço de reconhecimento não respondeu | ofereça digitar |
| `aborted` | cancelado | rotineiro |
| `language-not-supported` | o serviço não fala esse idioma | caia para `pt-BR` ou `en-US` |

!!! info "Não existe auto-restart, de propósito"
    Mesmo com `continuous: true` o motor encerra a sessão sozinho depois de um trecho de
    silêncio — é timeout do servidor, não bug. Um loop de reinício é como um app acaba
    segurando o microfone para sempre e, no Chromium, transmitindo áudio para terceiros
    para sempre. Mostre que parou de ouvir e deixe a pessoa apertar de novo.

### Ditando no `AIChat`

O `AIChat` **não** conhece o reconhecimento de fala, e não vai conhecer: isso faria todo
consumidor do componente pagar por uma API que manda áudio para terceiros. O que existe é o
`composerRef` — o botão que você põe dentro do composer escreve no campo:

```tsx
import { useRef } from "react";
import {
  AIChat,
  Button,
  useSpeechRecognition,
  type AIChatComposerHandle,
} from "tempest-react-sdk";

export function ChatComDitado({ messages, onSend }: ChatProps) {
  const composer = useRef<AIChatComposerHandle>(null);
  const speech = useSpeechRecognition({
    continuous: true,
    onFinal: (texto) =>
      composer.current?.setValue(`${composer.current.getValue()} ${texto}`.trim()),
  });

  return (
    <AIChat
      messages={messages}
      onSend={onSend}
      composerRef={composer}
      composerActions={
        <Button
          size="sm"
          variant={speech.listening ? "primary" : "soft"}
          disabled={!speech.supported}
          onClick={speech.listening ? speech.stop : speech.start}
        >
          {speech.listening ? "Ouvindo…" : "Ditar"}
        </Button>
      }
      composerFooter={<small>O áudio ditado sai do dispositivo.</small>}
    />
  );
}
```

!!! tip "`getValue()` é o que torna qualquer coisa **aditiva** possível"
    O composer é não-controlado de propósito (uma tecla por render do transcrito inteiro
    seria caro), então sem ler o rascunho a única forma de **acrescentar** — uma frase
    ditada, um comando de barra, uma citação colada — seria espelhar o valor inteiro no
    estado do app e torcer para os dois não divergirem.

## Recap

- `BarcodeScanner` — leitor completo: visor, mira, lanterna, supressão de repetição, erro
  classificado. Montar abre a câmera, então monte quando o usuário pedir.
- `BarcodeDetector` é Chromium-only. O SDK não embarca decodificador; `unsupported` cobre
  quem não tem, e `detector` aceita um polyfill.
- `useBarcodeScanner` — a metade de decodificação, sobre `useCameraStream`; loop que não se
  sobrepõe, `formats` resolvidos pela interseção com o motor.
- `useTorch` — a lanterna é constraint de track viva, não dispositivo; `supported` só vale
  depois do stream.
- `useVideoRecorder` — mesmo motor do áudio: relógio que desconta pausa, `stop()` com todos
  os chunks, container negociado. Use `timesliceMs` para captura longa.
- `useScreenCapture` — seletor fechado é cancelamento (não erro); `ended` é o **único**
  sinal de que o usuário parou; `surface`/`hasAudio` dizem o que aconteceu de fato.
- `useSpeechRecognition` — interim vs final, erros classificados, sem auto-restart. **O
  áudio sai do dispositivo no Chromium.**
- `AIChat` + `composerRef` — ditado sem o componente conhecer a API de fala.

## Veja também

- [Áudio](./audio.md) — microfone, gravação de voz, WAV, saída de som
- [Componentes utilitários](./components/utility.md) — o `QRCode`, que codifica
- [Vision (ONNX)](./vision.md) — o `useCameraStream` que este módulo reaproveita

---

# editor.md

# Rich Text Editor (`tempest-react-sdk/editor`)

Editor WYSIWYG controlado, construído sobre [tiptap](https://tiptap.dev). Vive
num subpath separado (`tempest-react-sdk/editor`) porque o tiptap é pesado — e
quem **não** usa o editor não paga nada por ele.

## Por que um subpath separado?

Um editor rich-text traz uma árvore de dependências grande (tiptap +
ProseMirror). Forçar isso em todo app que instala o SDK seria injusto com quem só
quer um `Button` e um `createApiClient`.

A solução é o mesmo padrão dos outros wrappers do SDK: **o caller injeta a
dependência pesada**. O `RichTextEditor` importa `@tiptap/react` e
`@tiptap/starter-kit`, mas esses pacotes são **peer deps opcionais** — declarados
no SDK como _optional_ e externalizados no bundle. Resultado:

- Quem usa o editor instala o tiptap explicitamente uma vez.
- Quem não usa nunca puxa tiptap pro bundle — o subpath fica fora do barrel raiz.

!!! tip "Importe do subpath, não do barrel raiz"
    `RichTextEditor` só existe em `tempest-react-sdk/editor`. Ele **não** é
    re-exportado de `tempest-react-sdk` — assim o tiptap nunca vaza pro bundle de
    quem só importa o barrel principal.

## Instalação

Instale o SDK normalmente e adicione os dois peers do tiptap:

```bash
npm install tempest-react-sdk
npm install @tiptap/react @tiptap/starter-kit
```

!!! info "Por que os peers são opcionais"
    `@tiptap/react` e `@tiptap/starter-kit` são declarados como
    `peerDependencies` **opcionais**. Apps que nunca importam
    `tempest-react-sdk/editor` podem ignorá-los sem warning de instalação. No
    momento em que você importar o editor sem tê-los instalado, o bundler
    acusa o módulo faltando — aí é só rodar o `npm install` acima.

## Estilos

O `RichTextEditor` usa CSS Modules com tokens `--tempest-*`, então ele já segue
o tema do app (claro/escuro) sem config extra. Basta importar o `styles.css` do
SDK uma vez no entry do app (você já faz isso pros outros componentes):

```ts
// src/main.tsx
import "tempest-react-sdk/styles.css";
```

A área editável (a `.ProseMirror`) e a toolbar herdam cor de texto, borda, anel
de foco e radius dos tokens `--tempest-*`. Para customizar, sobrescreva os
tokens no `:root` como em qualquer outro componente — veja
[Styles & tokens](./styles.md).

## API

```tsx
<RichTextEditor
  value={html} // string HTML controlada (obrigatório)
  onChange={setHtml} // (html: string) => void (obrigatório)
  placeholder="Escreva algo…" // texto quando vazio (opcional)
  editable // false = somente leitura (default true)
  toolbar // false = esconde a toolbar (default true)
  className="meu-editor" // classes extras no wrapper (opcional)
/>
```

| Prop          | Tipo                      | Default | Descrição                                          |
| ------------- | ------------------------- | ------- | -------------------------------------------------- |
| `value`       | `string`                  | —       | Conteúdo do editor como **HTML** (controlado).     |
| `onChange`    | `(html: string) => void`  | —       | Chamado com o HTML atualizado a cada mudança.      |
| `placeholder` | `string`                  | —       | Texto exibido quando o editor está vazio.          |
| `editable`    | `boolean`                 | `true`  | `false` torna o conteúdo somente leitura.          |
| `toolbar`     | `boolean`                 | `true`  | `false` esconde a toolbar de formatação.           |
| `className`   | `string`                  | —       | Classes extras aplicadas ao elemento wrapper.      |

### A toolbar embutida

Quando `toolbar` é `true` (default), o editor renderiza uma barra acima da área
editável com os comandos do `StarterKit`:

- **Negrito**, **Itálico**, **Tachado**, **Código** (inline)
- **Título 1**, **Título 2**
- **Lista com marcadores**, **Lista numerada**, **Citação** (blockquote)
- **Desfazer** / **Refazer** (desabilitados quando não há histórico)

Os botões refletem o estado do cursor (ficam ativos quando a seleção já está em
negrito, dentro de uma lista, etc.) e têm `aria-label` + `aria-pressed` para
acessibilidade.

## Exemplo completo — editor controlado

Programa copiável de ponta a ponta. O estado HTML vive no React via `useState`,
o editor o reflete e um `<details>` mostra o HTML emitido ao vivo.

```tsx
import { useState } from "react";
import { RichTextEditor } from "tempest-react-sdk/editor";
import "tempest-react-sdk/styles.css";

export function ArticleEditor() {
  const [html, setHtml] = useState<string>("<p>Comece a escrever seu artigo…</p>");

  return (
    <div style={{ maxWidth: 720, margin: "0 auto" }}>
      <h1>Novo artigo</h1>

      <RichTextEditor
        value={html}
        onChange={setHtml}
        placeholder="Escreva algo incrível…"
      />

      <details style={{ marginTop: 16 }}>
        <summary>HTML emitido</summary>
        <pre>{html}</pre>
      </details>
    </div>
  );
}
```

!!! note "`value` é HTML, `onChange` recebe HTML"
    O editor é totalmente controlado por uma string HTML. Você guarda esse HTML
    onde quiser (state, formulário, API) e o passa de volta em `value`. Mudanças
    externas em `value` são sincronizadas para dentro do editor **sem**
    re-disparar `onChange`, então não há loop de atualização.

### Somente leitura

Para exibir conteúdo sem permitir edição (preview de um artigo, por exemplo),
passe `editable={false}`. Você normalmente também esconde a toolbar:

```tsx
<RichTextEditor value={savedHtml} onChange={() => {}} editable={false} toolbar={false} />
```

!!! tip "Renderize HTML salvo com o mesmo tema"
    Usar o `RichTextEditor` em modo `editable={false}` é a forma mais simples de
    renderizar HTML salvo com a **mesma** tipografia e tokens da edição — a
    `.ProseMirror` aplica o estilo do tema tanto na escrita quanto na leitura.

!!! warning "`onChange` continua obrigatório"
    `onChange` é uma prop obrigatória mesmo em modo somente leitura. Em
    `editable={false}` ela nunca é chamada, então passe um no-op
    (`() => {}`) para satisfazer o tipo.

### Sem toolbar (UI própria)

Passe `toolbar={false}` quando quiser uma barra de formatação própria ou um
editor minimalista (um campo de comentário, por exemplo):

```tsx
<RichTextEditor value={comment} onChange={setComment} toolbar={false} placeholder="Comente…" />
```

## Recap

- `RichTextEditor` é um editor WYSIWYG **controlado** sobre tiptap, exposto no
  subpath `tempest-react-sdk/editor` — fora do barrel raiz, então quem não usa
  não paga nada.
- `@tiptap/react` e `@tiptap/starter-kit` são **peer deps opcionais**: o caller
  injeta a dependência pesada com `npm i @tiptap/react @tiptap/starter-kit`.
- `value` é uma string **HTML** e `onChange(html)` devolve o HTML a cada edição;
  mudanças externas em `value` são sincronizadas sem re-disparar `onChange`.
- A toolbar embutida cobre negrito/itálico/tachado/código, H1/H2, listas,
  citação e desfazer/refazer — desligue com `toolbar={false}`.
- `editable={false}` deixa o editor somente leitura (ótimo para preview); o
  visual da `.ProseMirror` segue os tokens `--tempest-*` via `styles.css`.

## Veja também

- [Styles & tokens](./styles.md) — customizar o tema `--tempest-*` da `.ProseMirror`.
- [Forms](./forms.md) — integrar o HTML do editor num formulário controlado.

---

# error-boundary.md

# Error Boundary

`ErrorBoundary` captura erros lançados durante o render de qualquer descendente e mostra um fallback no lugar de uma tela branca. `useErrorHandler` estende isso para erros assíncronos, que o React não captura sozinho.

!!! info "Por que isso importa"
    Sem um boundary, um erro de render em qualquer componente desmonta a árvore inteira — o usuário vê uma página em branco. Um boundary isola a falha: o ramo quebrado vira um fallback amigável (com botão de tentar de novo) e o resto do app continua de pé.

## Uso típico

`fallback` aceita um nó estático ou uma render-prop que recebe `{ error, reset }`. A render-prop é o caminho recomendado — você mostra a mensagem e oferece um botão de retry que limpa o boundary:

```tsx
import { useEffect } from "react";
import { ErrorBoundary, ErrorState } from "tempest-react-sdk";
import { useLocation } from "react-router";

export function Shell({ children }: { children: React.ReactNode }) {
  const location = useLocation();

  return (
    <ErrorBoundary
      resetKeys={[location.pathname]}
      onError={(error, info) => reportToSentry(error, info)}
      fallback={({ error, reset }) => (
        <ErrorState title="Algo deu errado" description={error.message} onRetry={reset} />
      )}
    >
      {children}
    </ErrorBoundary>
  );
}

declare function reportToSentry(error: Error, info: React.ErrorInfo): void;
```

As três props que importam:

- `fallback`: nó estático **ou** `({ error, reset }) => ReactNode`. `error` é o `Error` capturado; `reset()` limpa o estado e re-renderiza os filhos.
- `onError(error, info)`: chamado no `componentDidCatch`. Encaminhe para seu rastreador (Sentry, Datadog, console). `info.componentStack` mostra onde estourou.
- `resetKeys`: array observado por igualdade `Object.is`. Quando **qualquer** valor muda, o boundary reseta sozinho.

!!! tip "`resetKeys` limpa o erro ao navegar"
    Passando `resetKeys={[location.pathname]}`, o boundary se recupera automaticamente quando o usuário troca de rota — sem isso, o fallback ficaria preso na tela até um `reset()` manual.

## Erros assíncronos

Boundaries só capturam erros lançados **durante o render**. Falhas em callbacks, timers, websockets ou promises acontecem fora do render, então o React não as vê. `useErrorHandler` resolve isso: ele re-lança o erro dentro de um `setState`, forçando uma passada de render que o boundary acima intercepta.

```tsx
import { useEffect } from "react";
import { useErrorHandler } from "tempest-react-sdk";

export function LiveFeed({ socket }: { socket: WebSocket }) {
  const throwError = useErrorHandler();

  useEffect(() => {
    const onError = (event: Event) => throwError(event);
    socket.addEventListener("error", onError);
    return () => socket.removeEventListener("error", onError);
  }, [socket, throwError]);

  return <Feed />;
}
```

!!! note "Aceita qualquer valor"
    `throwError` recebe `unknown` e normaliza para `Error`: se você passar algo que não é `Error` (uma string, um objeto), ele embrulha em `new Error(String(value))` antes de propagar.

## Como o AppProviders monta o boundary

`AppProviders` já posiciona o `ErrorBoundary` como **a camada mais externa** (acima de Query, Theme e i18n), de modo que um erro de qualquer provider ou da própria UI cai no fallback. Ele é opt-in: o boundary só monta se você passar `errorBoundary` com um `fallback`.

```tsx
import { AppProviders, ErrorState } from "tempest-react-sdk";

<AppProviders
  errorBoundary={{
    fallback: ({ error, reset }) => <ErrorState description={error.message} onRetry={reset} />,
    onError: (error, info) => reportToSentry(error, info),
  }}
  i18n={{ locale: "pt-BR", messages }}
>
  <App />
</AppProviders>;
```

A ordem interna é `ErrorBoundary → QueryProvider → ThemeProvider → I18nProvider`, ou seja, o boundary global cobre tudo.

## Onde colocar boundaries

- **Um global** no shell do app (via `AppProviders` ou manual), com fallback genérico — a rede de segurança.
- **Locais** ao redor de widgets opcionais (feed lateral, gráficos, embeds) para que um erro isolado não derrube a tela inteira. Cada boundary local pode ter seu próprio `fallback` e `resetKeys`.

## Recap

- `ErrorBoundary` captura erros de **render**; `fallback` é nó estático ou render-prop `({ error, reset })`.
- `onError(error, info)` encaminha para telemetria; `info.componentStack` localiza a falha.
- `resetKeys` reseta o boundary quando qualquer valor (por `Object.is`) muda — ótimo com `location.pathname`.
- `useErrorHandler()` cobre erros **assíncronos** re-lançando no render; aceita `unknown` e normaliza para `Error`.
- `AppProviders` monta o boundary como camada mais externa quando você passa `errorBoundary={{ fallback }}`.
- Combine um boundary global com boundaries locais ao redor de widgets opcionais.

## Veja também

- [Componentes — ErrorState](./components.md) — fallback pronto com retry
- [App Providers](./app-providers.md) — onde o boundary global é montado
- [Logger](./logger.md) / [Telemetry](./telemetry.md) — destinos para o `onError`

---

# feature-flags.md

# Feature Flags

Feature flags ligam e desligam funcionalidades sem novo deploy: rollouts graduais (`new-checkout` para 10% dos usuários), kill-switches (`disable_payments` quando o gateway cai), experimentos A/B. O problema é o mesmo da telemetria — você não quer amarrar o app a um SDK específico de flags. O módulo `feature-flags` resolve com uma **interface mínima** (`isEnabled` / `get` / `onChange?`) que isola o app do provider real (GrowthBook, LaunchDarkly, Unleash, custom).

Adapters concretos vêm prontos para GrowthBook e LaunchDarkly; nenhum dos SDKs externos é peer dep — o **caller injeta a instância** já configurada, então você instala apenas o que usa.

!!! info "Por que o adapter recebe a instância, não a cria"
    Cada SDK de flags é inicializado de um jeito (GrowthBook carrega features pela
    rede com `loadFeatures()`, LaunchDarkly espera `waitUntilReady()`, ambos
    recebem atributos de targeting do usuário). O app é dono dessa inicialização;
    o adapter só roteia os lookups. Por isso você passa a instância pronta:
    `createGrowthBookFeatureFlagsAdapter({ growthbook: gb })`.

## Interface

```ts
import type { FeatureFlagsAdapter, FlagValue } from "tempest-react-sdk";

type FlagValue = boolean | string | number | null;

interface FeatureFlagsAdapter {
  isEnabled: (key: string, defaultValue?: boolean) => boolean;
  get: <T extends FlagValue = FlagValue>(key: string, defaultValue?: T) => T;
  onChange?: (listener: () => void) => () => void;
}
```

`onChange` é opcional — quando presente, os hooks re-renderizam os filhos a cada notificação (via `useSyncExternalStore`).

## Setup com `InMemory` (dev / testes)

```tsx
import { FeatureFlagsProvider, createInMemoryFlags } from "tempest-react-sdk";

const flags = createInMemoryFlags({
  initial: { "new-feed": true, max_items: 50 },
});

<FeatureFlagsProvider adapter={flags}>{children}</FeatureFlagsProvider>;
```

`createInMemoryFlags` também expõe `set(key, value)` para mutações dinâmicas em testes:

```ts
flags.set("new-feed", false); // dispara onChange → re-render automático
```

!!! warning "`useFeatureFlag` / `useFlagValue` exigem o provider"
    Os hooks lançam `Error("useFeatureFlag requires <FeatureFlagsProvider>")`
    quando não há provider montado acima. Diferente do `useTelemetry` (que
    devolve `null`), aqui não há fallback silencioso — sempre monte um
    `<FeatureFlagsProvider>`, nem que seja com `createInMemoryFlags()` vazio em
    testes.

## Uso em componentes

```tsx
import { useFeatureFlag, useFlagValue } from "tempest-react-sdk";

const showNewFeed = useFeatureFlag("new-feed", false);
const maxItems = useFlagValue<number>("max_items", 10);

return showNewFeed ? <NewFeed limit={maxItems} /> : <ClassicFeed limit={maxItems} />;
```

`useFeatureFlag` faz coerce-to-boolean; `useFlagValue<T>` mantém o tipo (`string` / `number` / `boolean` / `null`).

## Exemplo completo — gate de feature da raiz ao componente

Costurando provider, hook e default seguro num app real:

```tsx
// flags.tsx — adapter na raiz (in-memory aqui; troque pelo provider real em prod)
import { FeatureFlagsProvider, createInMemoryFlags } from "tempest-react-sdk";
import type { ReactNode } from "react";

const flagsAdapter = createInMemoryFlags({
  initial: { "new-checkout": false, "max_cart_items": 20 },
});

export function AppFlags({ children }: { children: ReactNode }) {
  return <FeatureFlagsProvider adapter={flagsAdapter}>{children}</FeatureFlagsProvider>;
}
```

```tsx
// CheckoutPage.tsx — escolhe a UI pelo flag, lê um limite tipado
import { useFeatureFlag, useFlagValue } from "tempest-react-sdk";
import { NewCheckout } from "./NewCheckout";
import { ClassicCheckout } from "./ClassicCheckout";

export function CheckoutPage() {
  const useNewCheckout = useFeatureFlag("new-checkout", false); // default seguro: false
  const maxCartItems = useFlagValue<number>("max_cart_items", 10); // default seguro: 10

  return useNewCheckout ? (
    <NewCheckout maxItems={maxCartItems} />
  ) : (
    <ClassicCheckout maxItems={maxCartItems} />
  );
}
```

Quando o flag muda no provider (rollout aumentado, kill-switch acionado), `onChange` dispara e os componentes que leem o flag re-renderizam automaticamente — sem reload.

## GrowthBook adapter

Wrap uma instância `GrowthBook` (criada e configurada pelo app — `apiHost`, `clientKey`, `attributes`, `loadFeatures()`).

```ts
import { GrowthBook } from "@growthbook/growthbook";
import { FeatureFlagsProvider, createGrowthBookFeatureFlagsAdapter } from "tempest-react-sdk";

const gb = new GrowthBook({
    apiHost: import.meta.env.VITE_GROWTHBOOK_API_HOST,
    clientKey: import.meta.env.VITE_GROWTHBOOK_KEY,
    attributes: { id: userId },
});
await gb.loadFeatures();

const adapter = createGrowthBookFeatureFlagsAdapter({ growthbook: gb });

<FeatureFlagsProvider adapter={adapter}>{children}</FeatureFlagsProvider>;
```

Mapeamento:

| `FeatureFlagsAdapter`     | `GrowthBook`                                                                                    |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| `isEnabled(key, default)` | `growthbook.isOn(key)` (fallback no default se retorno não-bool)                                |
| `get(key, default)`       | `growthbook.getFeatureValue(key, default)`                                                      |
| `onChange(listener)`      | `growthbook.setRenderer(...)` — instalado lazy na 1ª inscrição, multiplexa para todos listeners |

`GrowthBook` aceita apenas **um** `setRenderer`, então o adapter mantém um fan-out interno (`Set<listener>`) e instala o renderer único na primeira chamada de `onChange`.

## LaunchDarkly adapter

Wrap `launchdarkly-js-client-sdk` (criado e inicializado pelo app).

```ts
import * as LDClient from "launchdarkly-js-client-sdk";
import { FeatureFlagsProvider, createLaunchDarklyFeatureFlagsAdapter } from "tempest-react-sdk";

const client = LDClient.initialize(import.meta.env.VITE_LD_CLIENT_ID, {
    kind: "user",
    key: userId,
});
await client.waitUntilReady();

const adapter = createLaunchDarklyFeatureFlagsAdapter({ client });

<FeatureFlagsProvider adapter={adapter}>{children}</FeatureFlagsProvider>;
```

Mapeamento:

| `FeatureFlagsAdapter`     | `LDClient`                                                |
| ------------------------- | --------------------------------------------------------- |
| `isEnabled(key, default)` | `client.variation(key, default) === true`                 |
| `get(key, default)`       | `client.variation(key, default)`                          |
| `onChange(listener)`      | `client.on("change", listener)` + `client.off` no cleanup |

!!! tip "O padrão de injeção é idêntico ao da Telemetry"
    Os tipos `GrowthBookLike` / `LDClientLike` declaram só o subset usado — úteis
    pra mockar em testes. Para qualquer provider novo (Unleash, Split,
    Cloudflare), o mesmo padrão se aplica: caller injeta a instância, adapter
    expõe `<X>Like`, mapeamento direto sem estado. Veja
    [Telemetry](./telemetry.md) — é a mesma receita.

## Adapter custom

A interface é minúscula — ~20 linhas para qualquer SDK:

```ts
import type { FeatureFlagsAdapter } from "tempest-react-sdk";
import unleash from "unleash-proxy-client";

export const unleashAdapter: FeatureFlagsAdapter = {
  isEnabled: (key, defaultValue = false) => unleash.isEnabled(key) ?? defaultValue,
  get: (key, defaultValue) => unleash.getVariant(key)?.payload?.value ?? defaultValue,
  onChange: (listener) => {
    unleash.on("update", listener);
    return () => unleash.off("update", listener);
  },
};
```

## Padrões

- **Default seguro sempre** — `useFlagValue<number>("k", 10)`. Se o provider está offline ou ainda carregando, você ganha o fallback.
- **Não use pra estado de UI** — use apenas para rollouts (`new-checkout`) e kill-switches (`disable_payments`). Estado de UI vai pra Zustand/local state.
- **Não cacheia tipo** — `useFlagValue<number>("k")` retorna o valor cru declarado; faça narrowing/coerção no callsite quando precisar.
- **Rastreie exposições** — combine com [Telemetry](./telemetry.md) para gravar quem viu qual variante: `telemetry?.track({ name: "flag.exposure", properties: { flag, variant } })`.

## Resumo

- **Programe contra `FeatureFlagsAdapter`** (`isEnabled` / `get` / `onChange?`) — troca de provider é trivial.
- **`<FeatureFlagsProvider>` é obrigatório** — os hooks lançam sem ele (diferente de `useTelemetry`).
- **`useFeatureFlag`** → boolean; **`useFlagValue<T>`** → valor tipado; ambos re-renderizam via `onChange`.
- **Adapters injetam a instância** já configurada (`{ growthbook }`, `{ client }`) — nunca peer dep.
- **Sempre passe um default seguro**; flags são para rollouts e kill-switches, não para estado de UI.

### Veja também

- [Telemetry](./telemetry.md) — rastrear exposições do flag; adapters seguem exatamente o mesmo padrão de injeção

---

# forms-br.md

# Forms BR — máscaras, validadores, ViaCEP

Tudo que apps brasileiros usam diariamente: validar CPF/CNPJ de verdade, mascarar
entrada enquanto o usuário digita e preencher endereço a partir do CEP. Combina com
[zod + react-hook-form](./forms.md) ou form controlado manual.

!!! info "Por que não validar só o tamanho?"
    "Tem 11 dígitos" não significa que o CPF existe. Documentos brasileiros
    carregam **dígitos verificadores** calculados a partir dos demais — é assim que
    o backend da Receita rejeita números digitados errado. Validar só o tamanho
    deixa passar `123.456.789-00` e qualquer sequência repetida. As funções abaixo
    rodam o algoritmo completo.

## Validadores

```ts
import { validateCPF, validateCNPJ } from "tempest-react-sdk";

validateCPF("529.982.247-25"); // true
validateCPF("111.111.111-11"); // false (rejeita todos-iguais)
validateCPF("12345678900"); // false (dígito verificador inválido)
validateCNPJ("11.222.333/0001-81"); // true
```

Algoritmo completo (dígitos verificadores), não só "11 dígitos". Aceita string com ou sem máscara.

!!! note "Por que rejeitar dígitos repetidos"
    `111.111.111-11`, `000.000.000-00`, etc. **passam** na conta de dígito
    verificador por coincidência matemática — o algoritmo bruto os aceitaria. Como
    nenhum desses é um documento real, ambos os validadores têm um curto-circuito
    explícito (`/^(\d)\1+$/`) que rejeita qualquer valor com todos os dígitos
    iguais antes de calcular.

!!! tip "São puras — combine como quiser"
    `validateCPF` / `validateCNPJ` recebem `string` e devolvem `boolean`, sem
    estado nem React. Use direto num `onBlur`, num `.refine()` do zod (veja o fim
    da página), ou no servidor — é o mesmo código nos dois lados.

## Inputs com máscara

| Componente   | Mask                              | inputMode |
| ------------ | --------------------------------- | --------- |
| `CPFInput`   | `000.000.000-00`                  | numeric   |
| `CNPJInput`  | `00.000.000/0000-00`              | numeric   |
| `PhoneInput` | `(00) 00000-0000` (ou 10 dígitos) | tel       |
| `CEPInput`   | `00000-000`                       | numeric   |
| `MoneyInput` | `R$ X.XXX,XX` (cents)             | numeric   |

API uniforme — todos recebem `value: string` (ou `number` para `MoneyInput`) + `onChange`:

```tsx
import { useState } from "react";
import { CPFInput } from "tempest-react-sdk";

function CPFExample() {
  const [cpf, setCpf] = useState("");
  return <CPFInput value={cpf} onChange={setCpf} label="CPF" required />;
}
```

!!! warning "`onChange` entrega string, não um evento"
    Os inputs mascarados são **controlados** e chamam `onChange(maskedValue)` com a
    string já formatada — **não** com um `ChangeEvent`. Não tente `e.target.value`.
    Para guardar só os dígitos, use [`unmask`](#unmask-strip) na hora de enviar.

`MoneyInput` trabalha em **centavos** (`number`) pra evitar erro de float:

```tsx
import { useState } from "react";
import { MoneyInput } from "tempest-react-sdk";

function PriceExample() {
  const [cents, setCents] = useState(0);
  return <MoneyInput value={cents} onChange={setCents} label="Preço" />;
  // cents=12990 → "R$ 129,90"
}
```

Para outras moedas: `<MoneyInput currency="USD" locale="en-US" />`.

!!! warning "MoneyInput é centavos inteiros — nunca float"
    `value` e `onChange` lidam com **centavos inteiros** (`12990`), não reais
    (`129.90`). Persistir o valor como inteiro evita o clássico `0.1 + 0.2 !== 0.3`.
    Na hora de exibir/calcular em reais, divida por 100 só na borda.

### `unmask` — só os dígitos {#unmask-strip}

```ts
import { unmask } from "tempest-react-sdk";

unmask("529.982.247-25"); // "52998224725"
```

Use antes de enviar pro backend, que normalmente espera dígitos crus. Também
existem `formatCEP` e `formatCNPJ` exportados se você precisar mascarar uma string
fora de um input controlado.

### Campo só de celular — `formatPhone({ mobile: true })`

Por padrão o agrupamento é decidido pelo **tamanho**, que é o certo pra um campo que aceita fixo e celular. Num campo que só aceita celular ele erra enquanto o usuário digita: qualquer valor até dez dígitos é lido como fixo e o hífen cai depois do quarto dígito do assinante.

```ts
import { formatPhone } from "tempest-react-sdk";

formatPhone("1191234");                      // "(11) 9123-4"   ← hífen cedo demais
formatPhone("1191234", { mobile: true });    // "(11) 91234"    ← separador no lugar
formatPhone("1112345678", { mobile: true }); // "(11) 91234-5678" ← insere o 9
```

Os dois concordam quando os 11 dígitos entram; a diferença aparece **durante** a digitação, onde o hífen do modo padrão salta pra trás ao chegar o décimo primeiro dígito. O `mobile` também insere o `9` obrigatório, então um número de dez dígitos é corrigido em vez de mascarado como fixo.

## ViaCEP

`useViaCEP` consulta o serviço público ViaCEP e devolve os campos de endereço — sem
backend próprio.

```tsx
import { useState } from "react";
import { CEPInput, Input, useViaCEP } from "tempest-react-sdk";

function AddressForm() {
  const [cep, setCep] = useState("");
  const [street, setStreet] = useState("");
  const [city, setCity] = useState("");
  const [uf, setUf] = useState("");
  const viacep = useViaCEP();

  async function handleLookup() {
    const result = await viacep.lookup(cep);
    if (result) {
      setStreet(result.logradouro);
      setCity(result.localidade);
      setUf(result.uf);
    }
  }

  return (
    <>
      <CEPInput value={cep} onChange={setCep} onBlur={handleLookup} label="CEP" />
      {viacep.loading && <span>Buscando…</span>}
      {viacep.error && <span role="alert">{viacep.error}</span>}
      <Input value={street} onChange={(e) => setStreet(e.target.value)} label="Rua" />
      <Input value={city} onChange={(e) => setCity(e.target.value)} label="Cidade" />
      <Input value={uf} onChange={(e) => setUf(e.target.value)} label="UF" />
    </>
  );
}
```

Sem backend — usa `https://viacep.com.br/ws/<cep>/json/`.

!!! note "Dois tipos de falha"
    `viacep.error` é setado tanto pra **CEP com formato inválido** (≠ 8 dígitos, sem
    chamada de rede) quanto pra **CEP não encontrado** (a API respondeu `{ erro: true }`).
    Em ambos `lookup` resolve com `null` — sempre cheque o retorno antes de usar.

!!! tip "Dispare no `onBlur`, não a cada tecla"
    `lookup` faz uma requisição HTTP. Chame quando o campo perde foco (`onBlur`) ou
    quando os 8 dígitos estão completos — não a cada keystroke, pra não martelar o
    serviço público.

## Combinando com react-hook-form

Como os validadores são funções puras, eles entram direto num `.refine()` do zod, e
o input mascarado é ligado com um `<Controller>` (ou com o [`<FormField>`](./forms.md)
do SDK, que elimina o boilerplate):

```tsx
import { Controller, useForm } from "react-hook-form";
import { CPFInput, validateCPF, zodResolver } from "tempest-react-sdk";
import { z } from "zod";

const schema = z.object({
  cpf: z.string().refine(validateCPF, "CPF inválido"),
});

function CPFField() {
  const form = useForm({ resolver: zodResolver(schema), defaultValues: { cpf: "" } });
  return (
    <Controller
      control={form.control}
      name="cpf"
      render={({ field, fieldState }) => (
        <CPFInput
          value={field.value ?? ""}
          onChange={field.onChange}
          onBlur={field.onBlur}
          error={fieldState.error?.message}
          label="CPF"
        />
      )}
    />
  );
}
```

!!! tip "Menos boilerplate com FormField"
    O `<Controller>` acima pode virar uma linha com o `<FormField>` do SDK dentro de
    um `<FormProvider>`: `<FormField name="cpf" label="CPF"><CPFInput /></FormField>`.
    Veja o [exemplo ponta-a-ponta](./forms.md#exemplo-completo-schema-provider-fields-submit).

## Resumo

- `validateCPF` / `validateCNPJ` rodam o **algoritmo de dígito verificador** completo e rejeitam sequências repetidas — são funções puras reaproveitáveis no client e no servidor.
- Os inputs mascarados são **controlados** e chamam `onChange(string)` (não um evento); `MoneyInput` trabalha em **centavos inteiros**.
- `unmask` tira a máscara antes de enviar pro backend.
- `useViaCEP` resolve `null` em qualquer falha (formato inválido ou CEP inexistente) — sempre cheque o retorno; dispare no `onBlur`.
- Plugue os validadores no zod via `.refine()` e ligue os inputs com `<Controller>` ou `<FormField>`.

## Veja também

- [Forms (zod)](./forms.md) — `useZodForm`, `FormField`, layout e o exemplo ponta-a-ponta
- [HTTP](./http.md) — `parseResponse` valida a resposta da API
- [Hooks](./hooks.md) — `useDebounce` para adiar a busca de CEP enquanto digita

---

# forms.md

# Forms

Forms quase sempre travam em dois problemas que não têm nada a ver um com o outro:
**como os campos se arrumam na tela** e **como os valores são validados**. O SDK
separa esses dois eixos de propósito — você pode adotar um sem o outro.

1. **Layout** — `Form` / `FormSection` / `FormRow` / `FormActions` cuidam de como os campos se arranjam na tela.
2. **Validação** — `validateForm` / `zodResolver` / `useZodForm` cuidam de validar valores com zod.

Use os dois juntos ou separados — o `Form` component **não** se acopla a nenhuma form library.

!!! info "Por que zod como fonte de verdade?"
    Em vez de declarar o tipo do form e _depois_ escrever regras de validação que
    podem divergir dele, você escreve um schema zod e o tipo TypeScript é
    **inferido** com `z.infer`. Schema e tipo nunca saem de sincronia, e a mesma
    regra vale no client (`validateForm`/`zodResolver`) e no servidor.

## Layout — `Form` + subcomponentes

Substitui o padrão `<form><Stack>` boilerplate quando você quer um wrapper opinionado por layout.

```tsx
import { Form, FormSection, FormRow, FormActions, Input, Select, Button } from "tempest-react-sdk";
```

!!! note "De onde vem o `form` dos exemplos"
    Os trechos desta seção são sobre **layout**, então mostram só o JSX. O `form`
    que aparece neles (`form.register`, `form.handleSubmit`, `form.formState`) é o
    retorno do `react-hook-form`, criado uma vez no topo do componente:

    ```tsx
    const form = useZodForm(schema, { defaultValues: { name: "", email: "" } });
    ```

    O primeiro exemplo abaixo — [Stacked](#stacked) — está completo, com schema,
    imports e componente. Veja [`useZodForm`](#3-usezodform-tudo-em-um) para o hook
    e [Exemplo completo](#exemplo-completo-schema-provider-fields-submit) para um
    form ponta-a-ponta. Se você já usa `useForm` direto, `const form = useForm({
    resolver: zodResolver(schema) })` serve igual — o `Form` não se acopla a
    nenhuma form library.

### Variantes de `layout`

| `layout`   | Comportamento                                                                            |
| ---------- | ---------------------------------------------------------------------------------------- |
| `"stack"`  | (default) — flex coluna, gap = `gap` (default 4 → 16px).                                 |
| `"inline"` | Flex row com `flex-wrap: wrap` + `align-items: flex-end`. Filter bars, login curto, etc. |
| `"grid"`   | `display: grid` com `grid-template-columns: repeat(columns, minmax(0, 1fr))`.            |

`columns` aceita `number` (`repeat(N, minmax(0, 1fr))`) ou `string` (`"2fr 1fr"`, `"min-content auto"`).

`gap` aceita `number` (escala 4px: `2` → `8px`, `4` → `16px`) ou `string` (qualquer CSS length: `"1.5rem"`, `"20px"`).

### Stacked

O default: uma coluna, um campo por linha. Este exemplo está completo — copie,
cole e rode.

```tsx
import { Form, FormActions, Input, Button, useZodForm } from "tempest-react-sdk";
import { z } from "zod";

const signupSchema = z.object({
  name: z.string().min(2, "Informe seu nome"),
  email: z.string().email("Email inválido"),
  password: z.string().min(8, "Mínimo de 8 caracteres"),
});

type SignupValues = z.infer<typeof signupSchema>;

export function SignupForm() {
  const form = useZodForm(signupSchema, {
    defaultValues: { name: "", email: "", password: "" },
  });

  const onSubmit = async (values: SignupValues) => {
    await api.post("/signup", values);
  };

  return (
    <Form layout="stack" gap={4} onSubmit={form.handleSubmit(onSubmit)}>
      <Input label="Nome" {...form.register("name")} error={form.formState.errors.name?.message} />
      <Input
        label="Email"
        type="email"
        {...form.register("email")}
        error={form.formState.errors.email?.message}
      />
      <Input
        label="Senha"
        type="password"
        {...form.register("password")}
        error={form.formState.errors.password?.message}
      />
      <FormActions align="end">
        <Button type="submit" loading={form.formState.isSubmitting}>
          Criar conta
        </Button>
      </FormActions>
    </Form>
  );
}
```

Os exemplos seguintes mostram só o JSX do `Form` — o `form` e o `onSubmit` vêm do
mesmo lugar que aqui.

### Grid

```tsx
<Form layout="grid" columns={2} gap={4} onSubmit={form.handleSubmit(onSubmit)}>
  <Input label="Nome" {...form.register("name")} />
  <Input label="Sobrenome" {...form.register("last_name")} />
  <Input label="Email" type="email" {...form.register("email")} />
  <Input label="Telefone" {...form.register("phone")} />
  <FormActions align="end" style={{ gridColumn: "1 / -1" }}>
    <Button type="submit">Salvar</Button>
  </FormActions>
</Form>
```

!!! tip "Span de linha inteira"
    Use `gridColumn: "1 / -1"` para um campo (ou o `FormActions`) ocupar a linha
    inteira do grid, independente de quantas colunas existem.

### Inline

Filter bar não precisa de form library nenhuma — `onSubmit` aqui é o handler
nativo do `<form>`, que o `Form` repassa direto.

```tsx
const statusOptions = [
  { value: "active", label: "Ativo" },
  { value: "archived", label: "Arquivado" },
];

function handleFilter(event: React.FormEvent<HTMLFormElement>) {
  event.preventDefault();
  const data = new FormData(event.currentTarget);
  setFilters({ q: String(data.get("q") ?? ""), status: String(data.get("status") ?? "") });
}

<Form layout="inline" gap={2} onSubmit={handleFilter}>
  <Input name="q" label="Buscar" placeholder="nome…" />
  <Select name="status" label="Status" options={statusOptions} />
  <Button type="submit">Filtrar</Button>
</Form>;
```

Filter bars típicos: `align-items: flex-end` faz os botões ficarem alinhados com o baseline dos inputs.

### `FormSection` — subgrupos com layout independente

```tsx
<Form layout="stack" gap={5}>
  <Input label="Email" {...form.register("email")} />

  <FormSection title="Endereço" description="Usado para entrega" layout="grid" columns={3} gap={3}>
    <Input label="CEP" {...form.register("cep")} />
    <Input label="Cidade" {...form.register("city")} />
    <Input label="UF" {...form.register("state")} />
    <Input label="Rua" style={{ gridColumn: "1 / -1" }} {...form.register("street")} />
  </FormSection>

  <FormActions align="end">
    <Button type="submit">Salvar</Button>
  </FormActions>
</Form>
```

`FormSection` renderiza um `<section>` com `<header>` (quando `title` ou `description` presente) + body. O body tem o seu próprio `layout` / `columns` / `gap`.

### `FormRow` — side-by-side dentro de stack

```tsx
<Form layout="stack" gap={4}>
  <Input label="Número do cartão" />
  <FormRow gap={3}>
    <Input label="Validade" placeholder="MM/AA" />
    <Input label="CVV" />
  </FormRow>
</Form>
```

`FormRow` sempre é horizontal com `flex-wrap: wrap`. Children dividem largura igualmente (`flex: 1 1 0`).

### `FormActions` — footer buttons

```tsx
<FormActions align="between" gap={2}>
  <Button variant="ghost" type="button" onClick={onCancel}>
    Cancelar
  </Button>
  <Button type="submit" loading={form.formState.isSubmitting}>
    Salvar
  </Button>
</FormActions>
```

`align`: `"start"` / `"center"` / `"end"` (default) / `"between"`.

## Validação — zod

Três níveis de integração com zod, do mais leve ao mais opinativo. Schema é a **fonte de verdade** — o tipo é inferido.

### 1. `validateForm` — agnóstico

Não requer `react-hook-form`. Útil pra forms controlados manuais ou validação em batch.

```ts
import { validateForm } from "tempest-react-sdk";

const result = validateForm(schema, values);
if (!result.success) {
  setErrors(result.errors); // Record<path, message>
  return;
}
await save(result.data);
```

Path em dot-notation (`"address.city"`, `"items.0.name"`). Erros de root: `_root`.

!!! note "Primeiro erro por campo vence"
    `validateForm` mantém só a **primeira** issue de cada path no map de erros —
    UIs de form quase sempre mostram uma mensagem por campo. Se você precisa de
    _todas_ as mensagens (ex.: checklist de regras de senha), use
    `schema.safeParse(values).error.issues` direto.

### 2. `zodResolver` — react-hook-form

Substitui `@hookform/resolvers/zod` (sem dependência extra).

```ts
import { useForm } from "react-hook-form";
import { zodResolver } from "tempest-react-sdk";

const form = useForm({ resolver: zodResolver(loginSchema) });
```

### 3. `useZodForm` — tudo-em-um

```tsx
const form = useZodForm(loginSchema, { defaultValues: { email: "", password: "" } });

<Form layout="stack" onSubmit={form.handleSubmit(login)}>
  <Input label="Email" {...form.register("email")} error={form.formState.errors.email?.message} />
  <Input
    label="Senha"
    type="password"
    {...form.register("password")}
    error={form.formState.errors.password?.message}
  />
  <FormActions>
    <Button type="submit" loading={form.formState.isSubmitting}>
      Entrar
    </Button>
  </FormActions>
</Form>;
```

## Exemplo completo — schema → provider → fields → submit

Os três trechos acima são fatias da mesma história. Aqui está um form ponta-a-ponta
de cadastro: um único schema dirige tipos, validação **e** o `<FormField>` injeta o
estado do RHF em cada controle sem `<Controller>` repetido.

```tsx
import {
  Form,
  FormField,
  FormProvider,
  FormActions,
  Button,
  Input,
  useZodForm,
  type SubmitHandler,
} from "tempest-react-sdk";
import { z } from "zod";

// 1. Schema = fonte de verdade. O tipo SignupValues é inferido dele.
const signupSchema = z
  .object({
    name: z.string().min(2, "Informe seu nome"),
    email: z.string().email("Email inválido"),
    password: z.string().min(8, "Mínimo de 8 caracteres"),
    confirm: z.string(),
  })
  .refine((data) => data.password === data.confirm, {
    message: "As senhas não conferem",
    path: ["confirm"], // erro atribuído ao campo "confirm"
  });

type SignupValues = z.infer<typeof signupSchema>;

export function SignupForm() {
  // 2. useZodForm fia o resolver zod + infere SignupValues automaticamente.
  const form = useZodForm(signupSchema, {
    defaultValues: { name: "", email: "", password: "", confirm: "" },
  });

  // 4. handleSubmit só dispara o submit quando o schema passa.
  const onSubmit: SubmitHandler<SignupValues> = async (values) => {
    await fetch("/api/signup", {
      method: "POST",
      body: JSON.stringify(values),
    });
  };

  return (
    // 3. FormProvider expõe o `control` na árvore; FormField o consome via contexto.
    <FormProvider {...form}>
      <Form layout="stack" gap={4} onSubmit={form.handleSubmit(onSubmit)}>
        <FormField name="name" label="Nome" required>
          <Input />
        </FormField>
        <FormField name="email" label="Email" required>
          <Input type="email" />
        </FormField>
        <FormField name="password" label="Senha" required>
          <Input type="password" />
        </FormField>
        <FormField name="confirm" label="Confirmar senha" required>
          <Input type="password" />
        </FormField>
        <FormActions align="end">
          <Button type="submit" loading={form.formState.isSubmitting}>
            Criar conta
          </Button>
        </FormActions>
      </Form>
    </FormProvider>
  );
}
```

Como as peças se encaixam:

- **`useZodForm(schema)`** retorna o objeto `UseFormReturn` do react-hook-form, já
  com o resolver zod plugado. Você ganha `register`, `handleSubmit`, `formState`,
  `control` etc. tipados em cima de `SignupValues`.
- **`<FormProvider {...form}>`** publica esse retorno no contexto do RHF. É o que
  permite o `<FormField>` achar o `control` sozinho.
- **`<FormField name="..." label="...">`** envolve um `<Controller>` por baixo e usa
  `cloneElement` pra injetar `value` / `onChange` / `onBlur` / `ref` / `error` /
  `aria-invalid` no controle filho. Você passa um `<Input />` "burro" e o FormField
  conecta tudo.
- **`form.handleSubmit(onSubmit)`** roda o schema antes; `onSubmit` só recebe
  `values` já validados e tipados.

!!! tip "FormField elimina o `<Controller>` repetido"
    Sem ele, cada campo controlado vira um `<Controller name=... render={({ field, fieldState }) => ...} />`
    de 5 linhas. O `<FormField>` faz esse render-prop uma vez e repassa `error` +
    `aria-invalid` pro controle automaticamente.

!!! warning "FormField precisa de control ou Provider"
    `<FormField>` busca o `control` no contexto do `<FormProvider>`. Se você não
    quer um provider, passe `control={form.control}` explicitamente em cada
    `<FormField>`. Sem nenhum dos dois ele lança
    `"FormField requires either a control prop or a <FormProvider> in the tree."`.

!!! note "O controle filho precisa aceitar as props injetadas"
    O `<FormField>` espera que o filho aceite `value` / `onChange` / `onBlur` /
    `ref` / `error` / `label`. Os componentes do SDK (`Input`, `Select`, e os
    [inputs com máscara BR](./forms-br.md)) já aceitam — um `<input>` cru do DOM
    **não** entende `error`/`label` e vai logar warning de prop desconhecida.

!!! tip "Erros cross-field"
    Validações que dependem de dois campos (senha × confirmação) vão num
    `.refine()` no schema com `path: ["campo"]` — assim o erro aparece atribuído ao
    campo certo no `formState.errors`.

## O react-hook-form sai pelo mesmo barrel

O SDK re-exporta os hooks do `react-hook-form` que você usaria junto com
`useZodForm`, então um arquivo de formulário tem **um** import só:

```tsx
import {
  FormProvider,
  useFieldArray,
  useFormContext,
  useFormState,
  useWatch,
  useZodForm,
} from "tempest-react-sdk";
```

| Hook              | Para que serve                                                                    |
| ----------------- | --------------------------------------------------------------------------------- |
| `useFieldArray`   | Lista dinâmica de campos (itens de um pedido, telefones) com `append`/`remove`.   |
| `useFormContext`  | Alcança o form de dentro de um componente-filho, sem passar `control` por prop.    |
| `useWatch`        | Observa um campo re-renderizando **só** quem observa, não o formulário inteiro.    |
| `useFormState`    | Lê `errors`/`isDirty`/`isSubmitting` com a mesma granularidade de subscrição.      |

São os hooks do `react-hook-form`, sem casca: a documentação deles vale
literalmente, e importar direto de `react-hook-form` funciona igual. O
re-export existe para o app não precisar declarar a dependência que o SDK já
traz.

!!! tip "`useWatch` e `useFormState` existem por performance"
    `form.watch("campo")` e `form.formState.errors` re-renderizam o componente
    que segura o form — num formulário grande, isso é a tela inteira a cada
    tecla. Os hooks assinam só o pedaço observado, no componente que observa.

!!! danger "\"FormField found no form to bind to\" com um `<FormProvider>` visível acima"
    Quando isso acontece com o provider montado logo acima, a causa não é o que a
    frase sugere: o app e o SDK estão resolvendo **duas cópias** do
    `react-hook-form`. O `<FormProvider>` publica no contexto de uma cópia e o
    `useFormContext` de dentro do `<FormField>` lê o da outra, que está vazio.

    É o mesmo mecanismo do `useNavigate() may be used only in the context of a
    <Router>`, e passa despercebido pela mesma razão: ninguém vai olhar
    `node_modules` enquanto está olhando pro provider na tela. Por isso a mensagem
    de erro do SDK nomeia as duas causas desde a v0.52.1.

    Conserto: `npm dedupe`, ou `npx tempest doctor` para listar as duplicadas.

## Padrão de schema

Mantenha schemas em `src/schemas/<dominio>.ts`, exporte o `z.infer` em `src/types/<dominio>.ts` via `declare global` quando quiser tipos globais. Convenção herdada do alofans-frontend.

## Resumo

- O SDK separa **layout** (`Form`/`FormSection`/`FormRow`/`FormActions`) de **validação** (zod) — adote um sem o outro.
- A validação tem três degraus: `validateForm` (agnóstico), `zodResolver` (RHF), `useZodForm` (tudo-em-um).
- Um único **schema zod** dirige tipo (`z.infer`), validação e mensagens de erro.
- `<FormProvider>` + `<FormField>` removem o `<Controller>` repetido e propagam `error` + `aria-invalid` pros controles.
- `handleSubmit` só chama seu `onSubmit` com valores já validados.

## Veja também

- [Forms BR](./forms-br.md) — `CPFInput` / `CNPJInput` / `CEPInput` / `MoneyInput` / `useViaCEP` / algoritmos de validação BR
- [HTTP](./http.md) — `parseResponse` usa o mesmo zod
- [Componentes](./components.md) — `Input` / `Select` / `Textarea` que vivem dentro do Form
- [Hooks](./hooks.md) — `useAsync` para o estado do submit quando você não usa RHF

---

# gallery.md

# Gallery — catálogo visual + funcional

Demo interativo de todos os componentes e features do SDK. Roda como app Vite + React em [`examples/gallery`](https://github.com/mauriciobenjamin700/tempest-react-sdk/blob/main/examples/gallery).

## O que é a gallery?

A gallery é um app Vite + React **real** que consome o SDK exatamente como um app
de produção faria — via `npm install` apontando para `file:../..`. Ela substitui
o Storybook: cada seção monta componentes com props variadas, exercita hooks ao
vivo (SSE, toast, paginação) e serve como banco de provas visual quando você
mexe em estilos ou layout. Se um componente parece certo na gallery, parece certo
nos apps consumidores.

## Como rodar

```bash
# raiz do repo
npm install
npm run build           # gera dist/ do SDK

cd examples/gallery
npm install
npm run dev             # http://127.0.0.1:5173
```

`tempest-react-sdk` é consumido via `file:../..` — qualquer rebuild da raiz aparece na gallery após reload.

!!! tip "Rode `npm run dev` na raiz em paralelo"
    A gallery serve o `dist/` do SDK. Para ver mudanças no SDK na hora, deixe um
    `npm run dev` (vite build --watch) rodando na raiz numa aba e o
    `npm run dev` da gallery em outra — cada rebuild recarrega a página.

!!! note "Valide UI nos dois breakpoints"
    A gallery é o lugar pra conferir responsividade: redimensione para ≤ 430px
    (mobile) e ≥ 1024px (desktop) antes de dar uma mudança visual como pronta.
    Stack/Grid/Modal/Drawer/Table todos têm comportamento responsivo aqui.

## Seções

Cada seção é um arquivo em [`examples/gallery/src/sections/`](https://github.com/mauriciobenjamin700/tempest-react-sdk/tree/main/examples/gallery/src/sections) e cada exemplo é embrulhado pelo wrapper [`<Example>`](https://github.com/mauriciobenjamin700/tempest-react-sdk/blob/main/examples/gallery/src/Example.tsx) (demo + código + botão copiar).

| #   | Seção                                  | Componentes / Features                                                            |
| --- | -------------------------------------- | -------------------------------------------------------------------------------- |
| 1   | Buttons                                | `Button` (variantes, tamanhos, loading, fullWidth)                               |
| 2   | Form fields                            | `Input`, `Select`, `Textarea`, `SearchBar`                                        |
| 3   | Checkbox · Radio · Switch              | `Checkbox`, `RadioGroup`, `Switch`                                                |
| 4   | Toggle · Rating · Range · Combobox     | `Toggle`, `ToggleGroup`, `RatingStars`, `RangeSlider`, `Combobox`, `Label`       |
| 5   | Feedback                               | `Badge`, `Card`, `Spinner`, `Skeleton`                                            |
| 6   | Stat · Tag · Money · Banner            | `Stat`, `Tag`, `Banner`, `Money`, `RelativeTime`, `TruncateText`, `DataList`, `DescriptionList`, `CopyButton` |
| 7   | Avatar · Image · Carousel              | `Avatar`, `Image` (fallback), `AspectRatio`, `Carousel`                          |
| 8   | Modal & Toast                          | `Modal`, `ConfirmDialog`, `ToastProvider`, `useToast`                            |
| 9   | Overlays                               | `Popover`, `DropdownMenu`, `HoverCard`, `ContextMenu`, `Menubar`, `Command` (⌘K) |
| 10  | Disclosure                             | `Accordion`, `Collapsible`, `ScrollArea`                                          |
| 11  | Navigation                             | `Breadcrumbs`, `Tabs`, `Tooltip`, `Drawer`                                        |
| 12  | Stepper · Progress · VirtualList       | `Stepper`, `Progress`, `ChipInput`, `FileUpload`, `VirtualList`                   |
| 13  | Table & Pagination                     | `Table`, `Pagination`, `EmptyState`, `ErrorState`, `usePagination`               |
| 14  | DataTable                              | `DataTable` (busca, ordenação, paginação client-side)                            |
| 15  | Forms (zod)                            | `useZodForm`, `zodResolver`                                                       |
| 16  | BR Forms                               | `CPFInput`, `CNPJInput`, `PhoneInput`, `MoneyInput`, `CEPInput`, `useViaCEP`     |
| 17  | Store (Zustand)                        | `createStore`, `createSelectors` (contador persistido)                           |
| 18  | Tema + i18n                            | `ThemeProvider`, `useTheme`, `I18nProvider`, `useI18n`                           |
| 19  | Network · Clipboard · Share            | `useOnline`, `useClipboard`, `share`, `useKeyboardShortcut`, `useIntersectionObserver` |
| 20  | SSE · Push · Audio                     | `useEventStream` (SSE vivo), `isPushSupported`, `playAudio`                      |
| 21  | PWA: Install · Push                    | `useBeforeInstallPrompt`, `usePushSubscription`, `isPushSupported`               |
| 22  | Utils                                  | `formatCurrency`, `formatDate`, `formatPhone`, `formatCPF`, `formatPercent`      |

## Matriz de variantes

### Button

| Prop      | Valores                                      |
| --------- | -------------------------------------------- |
| `variant` | `primary` · `secondary` · `danger` · `ghost` |
| `size`    | `sm` · `md` · `lg`                           |
| Flags     | `loading`, `fullWidth`, `disabled`           |
| Slots     | `leftIcon`, `rightIcon`                      |

### Badge

| `variant` | Uso típico          |
| --------- | ------------------- |
| `neutral` | Tag genérica        |
| `success` | Pago, ativo, online |
| `warning` | Pendente, degradado |
| `danger`  | Falha, bloqueado    |
| `info`    | Em revisão, beta    |

### Modal

| Prop   | Valores                                            |
| ------ | -------------------------------------------------- |
| `size` | `sm` · `md` · `lg` · `xl`                          |
| Flags  | `closeOnBackdrop`, `closeOnEsc`, `hideCloseButton` |
| Slots  | `title`, `children` (body), `footer`               |

### Toast (via `useToast`)

| Método                                                  | Variante |
| ------------------------------------------------------- | -------- |
| `toast.success(text)`                                   | success  |
| `toast.error(text)`                                     | error    |
| `toast.warning(text)`                                   | warning  |
| `toast.info(text)`                                      | info     |
| `toast.show({ title, description, variant, duration })` | custom   |

### Table

| Coluna (`TableColumn<T>`) | Descrição                         |
| ------------------------- | --------------------------------- |
| `key`                     | identificador único               |
| `header`                  | label do cabeçalho                |
| `render(row, i)`          | célula custom; default `row[key]` |
| `align`                   | `left` · `right` · `center`       |
| `width`                   | string ou número                  |

### Spinner / Skeleton

| Spinner `size`     | Skeleton `variant`         |
| ------------------ | -------------------------- |
| `sm` · `md` · `lg` | `rect` · `text` · `circle` |

### Theme modes

| Mode     | Comportamento                                         |
| -------- | ----------------------------------------------------- |
| `light`  | força claro, ignora OS                                |
| `dark`   | força escuro, ignora OS                               |
| `system` | escuta `prefers-color-scheme`, atualiza em tempo real |

## Screenshots

Cada exemplo aparece **lado a lado com o código-fonte** (botão "Copiar"), então a
gallery é também uma referência copia-e-cola. Capturas do app rodando:

### Visão geral

![Visão geral da gallery](assets/gallery/gallery-overview.png)

### Avatar · Image · AspectRatio · Carousel

![Componentes de mídia](assets/gallery/gallery-display-media.png)

### Stat · Tag · Banner · Money · listas

![Componentes de dados](assets/gallery/gallery-data-display.png)

### Toggle · Rating · Range · Combobox · Calendar

![Inputs avançados](assets/gallery/gallery-inputs-advanced.png)

### Popover · Dropdown · HoverCard · ContextMenu · Menubar · Command

![Overlays](assets/gallery/gallery-overlays.png)

### DataTable

![DataTable com busca, ordenação e paginação](assets/gallery/gallery-data-table.png)

### Store (Zustand): createStore + createSelectors

![Foundation / store](assets/gallery/gallery-foundation.png)

### PWA: install prompt + web push

![PWA](assets/gallery/gallery-pwa.png)

## Resumo

- A gallery é um app Vite + React real que consome o SDK via `file:../..` — faz
  o papel de Storybook.
- Rode com `npm run build` na raiz, depois `npm run dev` em `examples/gallery`
  (porta `5173`).
- 22 seções cobrem componentes, overlays, mídia/imagens, inputs avançados,
  DataTable, store, tema/i18n, integrações ao vivo, PWA e utils — cada exemplo
  com código copia-e-cola ao lado.
- Use-a pra validar UI nos breakpoints mobile e desktop antes de fechar uma
  mudança visual.

## Veja também

- [README do app gallery](https://github.com/mauriciobenjamin700/tempest-react-sdk/blob/main/examples/gallery/README.md)
- [Arquitetura](./architecture.md)
- [Componentes](./components.md)

---

# geo.md

# Geolocalização

Módulo de geolocalização **100% self-hosted**: coleta de latitude/longitude pela API do navegador, cálculo de distância/trajetória e plot de mapas — **sem nenhuma API paga ou externa**. O mapa padrão é um plot **SVG tile-free** (sem imagens de tiles, sem requests). Espelha o módulo `geo` do [`tempest-fastapi-sdk`](https://pypi.org/project/tempest-fastapi-sdk/), então os tipos e a matemática batem entre cliente e servidor.

!!! info "Por que tile-free?"
    Qualquer mapa com imagem (OpenStreetMap, Mapbox, Google) baixa _tiles_ de um servidor externo. Isso colide com o requisito de "nada externo". Por isso o `TrajectoryMap` desenha a trajetória projetada em SVG (Web Mercator) sem fundo — zero request. Se você **hospeda seu próprio** servidor de tiles, dá pra ligar a camada Leaflet opcional passando `tileUrl`.

## Quando usar

- Coletar a posição do usuário (uma vez ou contínua) via `navigator.geolocation`.
- Gravar e exibir uma **trajetória** (corrida, entrega, trilha).
- Calcular distância entre pontos ou estimar tempo de viagem **offline**.
- Plotar tudo sem depender de mapa pago/externo.

## Tipos — `Coordinate`, `TrackPoint`, `TravelEstimate`

Os tipos espelham os schemas do FastAPI SDK (snake_case preservado no `TravelEstimate` pra desserializar direto de uma resposta):

```ts
import type { Coordinate, TrackPoint, TravelEstimate, TravelMode } from "tempest-react-sdk";

const sp: Coordinate = { latitude: -23.5505, longitude: -46.6333 };

// TrackPoint = Coordinate + quando foi capturado (+ accuracy opcional)
const ponto: TrackPoint = { ...sp, timestamp: Date.now(), accuracy: 12 };

// TravelMode = "car" | "motorcycle" | "bus"
const modo: TravelMode = "car";
```

Validadores utilitários: `isValidLatitude`, `isValidLongitude`, `isCoordinate` (type guard), `clampLatitude`, `normalizeLongitude` (wrap no antimeridiano).

## Distância e trajetória — `haversineKm`, `pathLengthKm`, `bearingDeg`

Matemática pura, sem rede, idêntica ao servidor:

```ts
import { haversineKm, pathLengthKm, bearingDeg } from "tempest-react-sdk";

const sp = { latitude: -23.5505, longitude: -46.6333 };
const rio = { latitude: -22.9068, longitude: -43.1729 };

haversineKm(sp, rio); // ≈ 360.9 (km, grande-círculo)

// Comprimento total de uma trajetória (soma dos trechos):
pathLengthKm([sp, { latitude: -23.2, longitude: -45 }, rio]);

// Azimute inicial (graus, 0 = norte, sentido horário):
bearingDeg(sp, rio); // ≈ 65 (nordeste)
```

### Enquadrar um conjunto de pontos — `boundingBox`, `boundsCenter`, `expandBounds`

Para centralizar um mapa numa trajetória, ou decidir o zoom que a cobre:

```ts
import { boundingBox, boundsCenter, expandBounds } from "tempest-react-sdk";

const bounds = boundingBox([sp, rio]); // { north, south, east, west } | null

if (bounds) {
  boundsCenter(bounds); // o ponto médio, para centralizar
  expandBounds(bounds, 0.1); // 10% de folga, para a rota não colar na borda
}
```

O `boundingBox` devolve `null` para lista vazia — não existe moldura em volta
de ponto nenhum, e devolver uma caixa zerada jogaria o mapa no Atlântico.

`expandBounds` existe porque enquadrar exatamente nos extremos encosta o primeiro
e o último ponto na moldura — a margem é o que faz o traçado caber visualmente.

### A matemática crua

`haversineKm` é a fórmula pronta, mas as duas peças dela saem avulsas para quem
monta um cálculo próprio: `EARTH_RADIUS_KM` (6371, o raio médio que a fórmula
assume) e `toRadians(graus)`. E `unprojectMercator` é o par de
`projectMercator` — converte de volta de coordenada de tela para lat/long, que é
o que um clique no mapa precisa.

```ts
import { EARTH_RADIUS_KM, projectMercator, toRadians, unprojectMercator } from "tempest-react-sdk";

const xy = projectMercator({ latitude: -23.55, longitude: -46.63 });
unprojectMercator(xy); // de volta ao par lat/long

EARTH_RADIUS_KM * toRadians(1); // ≈ 111.2 km por grau de latitude
```

## Estimativa de viagem offline — `estimateTravel`

Sem rede: distância grande-círculo × fator de sinuosidade, duração por velocidade média ajustada ao modo. Espelha `estimate_travel` do FastAPI SDK.

```ts
import { estimateTravel } from "tempest-react-sdk";

const est = estimateTravel(sp, rio, "car");
// { mode: "car", distance_km: ~469, duration_minutes: ~562, source: "heuristic" }

// Ônibus é ~1.6× mais lento que carro no mesmo trecho:
estimateTravel(sp, rio, "bus").duration_minutes;

// Ajuste os fatores:
estimateTravel(sp, rio, "car", { circuityFactor: 1.4, carSpeedKmh: 60 });
```

!!! tip "Fatores padrão"
    `circuityFactor = 1.3` (a estrada é ~30% maior que a reta), `carSpeedKmh = 50`, multiplicadores de duração `car: 1.0 · motorcycle: 0.95 · bus: 1.6`.

    Eles também são exportados — `DEFAULT_CIRCUITY_FACTOR`, `DEFAULT_CAR_SPEED_KMH`
    e `DEFAULT_MODE_DURATION_FACTORS` — para uma tela de ajustes mostrar o valor
    que está prestes a sobrescrever, em vez de repeti-lo e sair de sincronia.

## Rota real (opt-in) — `createOSRMBackend`

Quando você **hospeda um OSRM** e quer rota por ruas de verdade, construa um backend injetando a URL do **seu** servidor. É o único ponto que faz request — e só quando você o cria.

```ts
import { createOSRMBackend } from "tempest-react-sdk";

const backend = createOSRMBackend({ baseUrl: "https://osrm.interno" });
const est = await backend.route(sp, rio, { mode: "car" });
// { …, source: "osrm" }
```

!!! warning "Isto faz request de rede"
    O SDK não embute nenhum endpoint. Aponte `baseUrl` pra um motor de roteamento **seu**. Pra estimativa zero-rede, use `estimateTravel`.

Qualquer motor (Valhalla, GraphHopper) serve: implemente a interface `RoutingBackend` (`route(origin, destination, { mode }) => Promise<TravelEstimate>`).

## Rastreamento ao vivo — `usePositionTracker`

Grava uma trajetória a partir de `watchPosition`, filtrando jitter e acumulando distância. Ciclo de vida amarrado ao componente (o watch é encerrado no unmount).

```tsx
import { usePositionTracker, TrajectoryMap } from "tempest-react-sdk";

export function CorridaAoVivo() {
  const { points, lastPoint, distanceKm, isTracking, start, stop, clear } =
    usePositionTracker({ minDistanceKm: 0.01, positionOptions: { enableHighAccuracy: true } });

  return (
    <div>
      <button onClick={isTracking ? stop : start}>
        {isTracking ? "Parar" : "Rastrear"}
      </button>
      <button onClick={clear}>Limpar</button>
      <span>{distanceKm.toFixed(2)} km · {points.length} pontos</span>
      <TrajectoryMap points={points} current={lastPoint} height={360} />
    </div>
  );
}
```

- `minDistanceKm` (default `0.005` = 5 m) descarta amostras muito próximas — filtra o tremido do GPS parado.
- `maxPoints` limita o array retido (a distância total continua contando).
- `autoStart: true` já começa a rastrear na montagem.

### Versão imperativa — `createPositionTracker`

Fora do React (services), o controller expõe `start`/`stop`/`clear` + getters `points`/`distanceKm`/`status`:

```ts
import { createPositionTracker } from "tempest-react-sdk";

const tracker = createPositionTracker({
  minDistanceKm: 0.01,
  onUpdate: (pts) => console.log(pts.length),
});
tracker.start();
// …depois
tracker.stop();
console.log(tracker.distanceKm);
```

## Plot do mapa — `TrajectoryMap`

Por padrão, plot **SVG tile-free**: projeta os pontos (Web Mercator), auto-ajusta aos bounds, desenha a polyline + marcadores (início verde, atual pulsante) + grid + barra de escala em km. Zero dependência, zero rede.

```tsx
import { TrajectoryMap } from "tempest-react-sdk";

<TrajectoryMap
  points={points}
  current={lastPoint}
  height={360}
  showGrid
  showScale
/>;
```

### Tiles reais (opt-in) com Leaflet

Se você **hospeda tiles próprios**, passe `tileUrl` — o componente carrega o Leaflet sob demanda (import dinâmico) e sobe uma camada de tiles de verdade. Requer o `leaflet` instalado no app e a folha de estilo importada uma vez.

```tsx
// npm install leaflet
import "leaflet/dist/leaflet.css";
import { TrajectoryMap } from "tempest-react-sdk";

<TrajectoryMap
  points={points}
  tileUrl="https://tiles.SEU-SERVIDOR/{z}/{x}/{y}.png"
  tileAttribution="© Seus dados de mapa"
  height={420}
/>;
```

!!! note "Leaflet é peer opcional"
    Sem `tileUrl`, o Leaflet **nunca** entra no bundle (o import é lazy). Se `tileUrl` for passado e o `leaflet` não estiver instalado, o componente mostra uma mensagem em vez de quebrar.

| Prop | Tipo | Default | Descrição |
| --- | --- | --- | --- |
| `points` | `readonly Coordinate[]` | — | Trajetória a desenhar. |
| `current` | `Coordinate \| null` | — | Marcador de posição atual (pulsante). |
| `height` | `number` | `320` | Altura do viewport em px. |
| `padding` | `number` | `24` | Margem interna em px. |
| `showGrid` / `showScale` | `boolean` | `true` | Grid e barra de escala (modo SVG). |
| `strokeColor` | `string` | token primário | Cor da linha. |
| `tileUrl` | `string` | — | Template `{z}/{x}/{y}` do **seu** tile server → liga o Leaflet. |
| `tileAttribution` | `string` | — | Atribuição sobre os tiles. |

## Recap

- **Coleta**: `usePositionTracker` / `createPositionTracker` gravam trajetória via `navigator.geolocation`, filtrando jitter — tudo no navegador.
- **Matemática**: `haversineKm`, `pathLengthKm`, `bearingDeg`, `estimateTravel` — offline, espelhando o `tempest-fastapi-sdk`.
- **Mapa**: `TrajectoryMap` plota em SVG sem tiles por padrão; `tileUrl` liga o Leaflet só com servidor **seu**.
- **Rota real**: `createOSRMBackend` é opt-in e aponta pro **seu** OSRM — o único ponto que toca a rede.

## Veja também

- [Hooks utilitários](./hooks.md) — `useGeolocation` (fix único / watch de baixo nível)
- [HTTP](./http.md) — enviar a trajetória pro backend
- [Offline](./offline.md) — persistir a trajetória localmente

---

# hooks.md

# Hooks utilitários

Toda app React reescreve os mesmos wrappers: "debounce esse input", "fecha o menu
no Escape", "guarda o tema no localStorage", "re-renderiza quando a janela muda de
tamanho". São pequenos, mas cada um tem uma armadilha — limpeza de listener, segurança
sem `window`, array de dependências. O SDK empacota esses padrões em hooks
granulares, testados e independentes — importe só o que precisar.

!!! note "Safe fora do browser ≠ suporte a SSR"
    Vários hooks abaixo aparecem como *safe* fora do browser: eles checam
    `typeof window === "undefined"` e devolvem um default em vez de explodir. Isso
    existe para testes em Node, contexto de service worker e plugins de build —
    **não** é promessa de render no servidor. O SDK é client-only por decisão
    (veja [Arquitetura](./architecture.md#escopo-so-client-side)).

!!! info "Cada hook é uma peça isolada"
    Nenhum hook depende de outro nem de provider. `import { useDebounce } from "tempest-react-sdk"`
    e pronto — o bundler tree-shake o resto. Eles agrupam só por _propósito_ aqui na
    doc, não por acoplamento.

## Catálogo por propósito

### DOM / viewport

| Hook                                              | O que faz                                                                                                    |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `useMediaQuery(query)`                            | Subscreve `matchMedia` e re-renderiza ao mudar.                                                              |
| `useBreakpoint()`                                 | `{ current, width, above, below, isMobile, isTablet, isDesktop }` — breakpoint reativo (xs/sm/md/lg/xl/2xl). |
| `useWindowSize()`                                 | `{ width, height }` da janela, reativo.                                                                      |
| `useEventListener(name, handler, target?, opts?)` | Wrap genérico safe sem `window`. `target` default = `window`. Aceita ref ou `EventTarget` direto.                     |
| `useOnline(opts?)`                                | `navigator.onLine` reativo; `{ pingUrl, intervalMs, timeoutMs }` adiciona probe de reachability real (capta captive portal / link morto). |
| `useDocumentVisibility()`                         | `document.visibilityState` reativo.                                                                          |
| `useIntersectionObserver(ref, opts?)`             | `IntersectionObserverEntry` ou `null`.                                                                       |
| `useResizeObserver(ref)`                          | `{ width, height }` da referência.                                                                           |
| `useScrollOverflow(ref, axis?)`                    | `true` enquanto o conteúdo transborda a caixa — use pra dar ponto de tabulação a um contêiner de rolagem só quando há o que rolar. |
| `useScrollLock(active)`                           | Lock de `body.overflow`.                                                                                     |
| `useFocusTrap(ref, active)`                       | Confina Tab dentro do container.                                                                             |
| `useHover(ref)` / `useLongPress(handler, opts?)`  | Gestos de ponteiro (hover reativo / long-press).                                                             |
| `useBeforeInstallPrompt()`                        | PWA install prompt diferido (`installable`, `installed`, `isStandalone`, `prompt()`).                        |
| `useServiceWorkerUpdate({ url })`                 | Registra o SW e expõe `{ updateAvailable, applyUpdate, registration }` — fluxo de update com consentimento (par de `<UpdatePrompt>`). Veja [PWA](./pwa.md). |
| `useStorageEstimate({ pollMs? })`                 | `{ usage, quota, ratio, persisted, requestPersist, refresh }` — quota do Storage API + `persist()`. Pares puros: `estimateStorage`, `requestPersistentStorage`. |
| `useIdle(timeout?)`                               | True quando usuário ocioso por `timeout` ms.                                                                 |
| `useGeolocation(opts?)`                           | Position + erro + loading.                                                                                   |
| `useClickOutside(handler)`                        | Retorna um ref; chama `handler` em `mousedown`/`touchstart` fora do elemento. safe sem `window`.                      |
| `useDocumentTitle(title)`                         | Seta `document.title` enquanto montado, restaurando o anterior no unmount. safe sem `window`.                         |
| `useFavicon(href)`                                | Troca o favicon via `<link rel="icon">` (cria o elemento se faltar). safe sem `window`.                               |
| `useAnnounce()`                                   | Devolve `announce(mensagem, politeness?)` — fala pro leitor de tela por uma região viva compartilhada. Pares puros: `announce`, `clearAnnouncer`. |

### Entrada / interação

| Hook                                            | O que faz                                                  |
| ----------------------------------------------- | ---------------------------------------------------------- |
| `useDebounce(value, delay?)`                    | Retorna o valor estabilizado após `delay` ms sem mudanças. |
| `useThrottle(value, interval?)`                 | Limita atualizações a no máximo uma por `interval` ms.     |
| `useClipboard(opts?)`                           | `{ copied, copy, reset }` com TTL configurável.            |
| `useKeyboardShortcut(shortcut, handler, opts?)` | Atalho global; aceita `mod` (Ctrl/Cmd).                    |

### Estado

| Hook                                              | O que faz                                                                                                       |
| ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| `usePagination(initialPage?, initialSize?)`       | `{ page, size, setPage, setSize, reset }`.                                                                      |
| `useClientFilter(items, search, keysOrPredicate)` | Filtro client-side por keys ou predicado (memoizado). Os itens são objetos (`T extends Record<string, unknown>`). |
| `useLocalStorage<T>(key, default)`                | State persistido em localStorage + sincronizado cross-tab via `storage` event. safe sem `window`.                        |
| `useToggle(initial?)`                             | `[value, { toggle, setTrue, setFalse, set }]` — açúcar pra boolean state.                                       |
| `useAsync<T>(fn, deps?, { immediate? })`          | Track `idle/pending/success/error`. `{ status, data, error, run, reset }`. Distinto de React Query (sem cache). |
| `usePrevious(value)`                              | Valor anterior do render passado.                                                                               |
| `useDisclosure(initial?)`                         | `[opened, { open, close, toggle }]` — handlers estáveis para modais/drawers/popovers.                          |
| `useCounter(initial?, { min, max })`              | `[count, { increment, decrement, set, reset }]` — contador numérico com clamp opcional.                        |
| `useListState<T>(initial?)`                       | `[list, handlers]` com `append`/`prepend`/`insert`/`remove`/`reorder`/`setItem`/`setState`/`apply`/`clear`.     |
| `useMap<K, V>(initial?)`                          | `{ map, set, delete, clear, get, has, size }` — `Map` reativo (nova referência a cada mutação).                 |
| `useSet<T>(initial?)`                             | `{ set, add, delete, clear, has, toggle, size }` — `Set` reativo (nova referência a cada mutação).              |
| `useQueue<T>({ initialValues, limit })`           | `{ queue, add, update, cleanQueue, size }` — fila FIFO com `limit` e buffer de overflow.                        |
| `useIsFirstRender()`                              | `true` no primeiro render do componente, `false` depois.                                                        |
| `useObjectUrl(blob)`                              | Cria `URL.createObjectURL(blob)` e o revoga no unmount / quando o blob muda; `null` pra entrada nula.           |

### Timers

| Hook                                                | O que faz                                                                                                    |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `useInterval(callback, delay)`                       | `setInterval` declarativo; `delay = null` pausa.                                                              |
| `useTimeout(callback, delay)`                        | `setTimeout` declarativo; `delay = null` cancela.                                                             |
| `useCountdown(durationMs, startedAt, { tickMs })`    | Tempo restante de uma janela, recalculado do relógio a cada tick. Trava em `0` e para o interval.             |
| `useTypewriter(text, speedMs)`                       | `{ displayedText, isComplete, skip }` — revela o texto letra a letra. `speedMs <= 0` renderiza tudo de uma vez. |

### Performance

| Hook                     | O que faz                                                        |
| ------------------------ | ---------------------------------------------------------------- |
| `useStableCallback(fn)`  | Ref estável que chama o callback atual.                          |
| `useLatestRef(value)`    | Ref estável cujo `current` é sempre o último `value` recebido.    |
| `useDeepMemo(value)`     | Memoização com igualdade estrutural.                             |

!!! tip "safe sem `window` por padrão"
    Os hooks que tocam APIs do browser (`useMediaQuery`, `useBreakpoint`,
    `useWindowSize`, `useOnline`, `useDocumentVisibility`, `useLocalStorage`,
    `useEventListener`) checam `typeof window === "undefined"` e retornam um default
    seguro no servidor, hidratando o valor real **após o mount**. Por isso o primeiro
    render no client pode mostrar o default (ex.: `width: 0`) por um instante.

## Exemplos

### Offline-aware badge

```tsx
import { useOnline, Badge } from "tempest-react-sdk";

function NetworkPill() {
  const online = useOnline();
  return <Badge variant={online ? "success" : "danger"}>{online ? "online" : "offline"}</Badge>;
}
```

### Atalho global — `useKeyboardShortcut`

```tsx
import { useState } from "react";
import { useKeyboardShortcut } from "tempest-react-sdk";

function CommandPalette() {
  const [open, setOpen] = useState(false);
  useKeyboardShortcut({ key: "k", mod: true }, () => setOpen(true));
  return open ? <div role="dialog">Command palette…</div> : null;
}
```

`mod: true` aceita Ctrl ou Cmd, simplificando cross-OS.

!!! note "Não dispara dentro de inputs"
    Por default (`ignoreInput: true`) o atalho é ignorado quando o foco está num
    `<input>`, `<textarea>`, `<select>` ou `[contenteditable]` — pra não roubar o
    "k" que o usuário está digitando. Passe `{ ignoreInput: false }` se quiser o
    contrário.

### Busca com debounce — `useDebounce`

```tsx
import { useEffect, useState } from "react";
import { useDebounce } from "tempest-react-sdk";

function SearchBox() {
  const [text, setText] = useState("");
  const debounced = useDebounce(text, 400);

  useEffect(() => {
    if (debounced) fetch(`/api/search?q=${encodeURIComponent(debounced)}`);
  }, [debounced]);

  return <input value={text} onChange={(e) => setText(e.target.value)} placeholder="Buscar…" />;
}
```

`useDebounce` adia o _valor_; o `useEffect` só dispara quando ele estabiliza.

### Lazy load via IntersectionObserver

```tsx
import { useRef } from "react";
import { useIntersectionObserver } from "tempest-react-sdk";

function LazyChart() {
  const ref = useRef<HTMLDivElement>(null);
  const entry = useIntersectionObserver(ref, { once: true });
  return <div ref={ref}>{entry?.isIntersecting && <HeavyChart />}</div>;
}
```

### Copy-to-clipboard com feedback — `useClipboard`

```tsx
import { useClipboard, Button } from "tempest-react-sdk";

function CopyButton() {
  const { copied, copy } = useClipboard({ resetAfter: 2000 });
  return (
    <Button onClick={() => copy("npm install tempest-react-sdk")}>
      {copied ? "Copiado!" : "Copiar"}
    </Button>
  );
}
```

### Responsive — `useBreakpoint`

```tsx
import { useBreakpoint } from "tempest-react-sdk";

function Hero() {
  const bp = useBreakpoint();
  return <h1 style={{ fontSize: bp.isMobile ? 24 : 48 }}>Bem-vindo</h1>;
}
```

`bp.above("lg")` / `bp.below("md")` cobrem comparações arbitrárias além dos atalhos
`isMobile` / `isTablet` / `isDesktop`.

Os limites são os do `BREAKPOINTS`, exportado para quando o mesmo corte precisa
existir fora do React — numa media query montada em JS, num teste, num cálculo
de layout:

```ts
import { BREAKPOINTS } from "tempest-react-sdk";

BREAKPOINTS; // { xs: 480, sm: 640, md: 768, lg: 1024, xl: 1280, "2xl": 1536 }
window.matchMedia(`(min-width: ${BREAKPOINTS.lg}px)`);
```

### Persisted state — `useLocalStorage`

```tsx
import { useLocalStorage } from "tempest-react-sdk";

function ThemeToggle() {
  const [theme, setTheme] = useLocalStorage<"light" | "dark">("theme", "light");
  return <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>{theme}</button>;
}
```

Multi-tab: outras abas recebem update via `window.addEventListener("storage", ...)` interno.

!!! warning "A `key` deve ser estável e única"
    `useLocalStorage` usa a `key` como dependência interna. Não a monte inline com
    valores que mudam (`` `user-${id}` `` muda toda vez que `id` muda e troca o slot
    de armazenamento). E como a key é global no domínio, escolha um nome com prefixo
    pra não colidir com outra feature.

### Async — `useAsync`

```tsx
import { useAsync, Spinner, ErrorState } from "tempest-react-sdk";

interface User {
  id: string;
  name: string;
}

function UserPanel({ id }: { id: string }) {
  const { status, data, error, run } = useAsync<User>(
    () => fetch(`/api/users/${id}`).then((r) => r.json()),
    [id],
    { immediate: true },
  );

  if (status === "pending") return <Spinner />;
  if (status === "error") return <ErrorState description={String(error)} onRetry={run} />;
  return <p>{data?.name}</p>;
}
```

!!! tip "useAsync vs React Query"
    `useAsync` é o primitivo de uma chamada só, sem cache e sem dependências extras —
    ideal pra ações pontuais (submit, "carregar mais"). Pra dados de servidor com
    cache, dedup e revalidação, use [React Query](./query.md). `useAsync` descarta
    resultados de runs obsoletos, então trocar `id` rápido não causa race.

### Global listener — `useEventListener`

```tsx
import { useState } from "react";
import { useEventListener } from "tempest-react-sdk";

function ScrollWatcher() {
  const [scrolled, setScrolled] = useState(false);
  useEventListener("scroll", () => setScrolled(window.scrollY > 100), undefined, {
    passive: true,
  });
  return <header data-scrolled={scrolled}>…</header>;
}
```

### Focus trap em Modal custom

```tsx
import { useRef } from "react";
import { useFocusTrap, useScrollLock } from "tempest-react-sdk";

function CustomModal({ open }: { open: boolean }) {
  const ref = useRef<HTMLDivElement>(null);
  useFocusTrap(ref, open);
  useScrollLock(open);
  return open ? (
    <div ref={ref} role="dialog" aria-modal="true">
      …
    </div>
  ) : null;
}
```

!!! note "Acessibilidade do focus trap"
    `useFocusTrap` confina o Tab dentro do container, mas não substitui o resto do
    contrato de diálogo: marque `role="dialog"` + `aria-modal="true"`, devolva o foco
    ao gatilho ao fechar e trate o Escape. O componente `Modal` do SDK já faz tudo
    isso — só recorra a este hook em overlays caseiros.

### Falar com o leitor de tela — `useAnnounce`

Algo aconteceu que quem vê a tela percebe e quem usa leitor de tela não: um filtro
reduziu a lista, uma linha salvou, uma cópia deu certo. `useAnnounce` devolve uma
função estável que anuncia isso.

```tsx
import { useAnnounce, useClientFilter } from "tempest-react-sdk";
import { useEffect, useState } from "react";

interface Produto extends Record<string, unknown> {
  id: string;
  nome: string;
}

export function ListaFiltrada({ items }: { items: Produto[] }) {
  const [termo, setTermo] = useState("");
  const visiveis = useClientFilter(items, termo, ["nome"]);
  const announce = useAnnounce();

  useEffect(() => {
    announce(`${visiveis.length} resultados`);
  }, [visiveis.length, announce]);

  return (
    <>
      <input value={termo} onChange={(e) => setTermo(e.target.value)} aria-label="Buscar" />
      <ul>
        {visiveis.map((item) => (
          <li key={item.id}>{item.nome}</li>
        ))}
      </ul>
    </>
  );
}
```

`announce(mensagem)` é polido por padrão; `announce(mensagem, "assertive")` interrompe
o que estiver sendo lido — reserve pra erro que exige ação.

!!! info "Duas regiões, uma polida e uma assertiva — de propósito"
    Politeness é propriedade **da região**, lida quando a tecnologia assistiva a
    registra. Trocar `aria-live` depois é honrado por alguns leitores, ignorado por
    outros e às vezes perde o anúncio. Duas regiões que nunca mudam é a única versão
    que se comporta igual em todo lugar. E são **compartilhadas**: várias regiões vivas
    mutando ao mesmo tempo é como anúncio se perde ou sai duplicado.

!!! warning "A mesma string duas vezes normalmente não anuncia de novo"
    O leitor anuncia quando o **conteúdo muda** — escrever o mesmo texto não é
    mudança, então "Item removido" duas vezes seguidas é lido uma. Em vez de mexer no
    texto, cada chamada troca o **elemento filho** da região: a mutação é real mesmo
    com a string idêntica, e o leitor ouve exatamente a sua mensagem, sem caractere de
    padding pendurado.

!!! danger "Nunca embrulhe texto em streaming numa região viva"
    Uma região viva sobre texto que cresce token a token faz o leitor recomeçar a
    resposta inteira a cada token. Anuncie as **bordas** — "gerando resposta",
    "resposta concluída" — e deixe a transcrição num `role="log"` comum, lido no ritmo
    da pessoa. É o que o `AIChat` faz.

E o que **não** mandar pro announce: conteúdo que já está na tela dentro de uma região
com papel — um `SyncStatusBadge` (`role="status"`), um toast, um erro de campo ligado
ao input. Anunciar de novo lê duas vezes.

Fora do React, `announce(mensagem, politeness?)` é a mesma função e cria a região no
primeiro uso. `clearAnnouncer()` remove as regiões — serve pra teardown de teste e pra
micro-frontend saindo de uma página que não é dele.

### Toggle — `useToggle`

```tsx
import { useToggle } from "tempest-react-sdk";

function Disclosure() {
  const [open, { toggle, setTrue }] = useToggle(false);
  return (
    <>
      <button onClick={toggle}>{open ? "Fechar" : "Abrir"}</button>
      <button onClick={setTrue}>Forçar aberto</button>
      {open && <p>Conteúdo</p>}
    </>
  );
}
```

!!! warning "O segundo elemento é um objeto, não funções soltas"
    `useToggle` retorna `[value, { toggle, setTrue, setFalse, set }]`. Desestruture o
    objeto (`const [on, { toggle }] = useToggle()`) — não `const [on, toggle] = ...`,
    que daria o objeto inteiro em `toggle`.

### Performance — `useStableCallback`

```tsx
import { useEffect } from "react";
import { useStableCallback } from "tempest-react-sdk";

function Tracker({ onSelect }: { onSelect: (id: string) => void }) {
  const stable = useStableCallback(onSelect);
  // `stable` tem ref constante; o effect não re-dispara quando onSelect muda.
  useEffect(() => bindSomething(stable), [stable]);
  return null;
}
```

!!! tip "Cuidado com o array de dependências"
    Passe `useStableCallback` para effects/listeners que você **não** quer re-rodar
    quando o callback muda de identidade. Já valores derivados (`useDebounce`,
    `useAsync` com `deps`) devem entrar nas deps normalmente — omiti-los gera bugs de
    valor obsoleto. Regra geral: confie no `eslint-plugin-react-hooks`.

### Valor fresco dentro de um effect que roda uma vez — `useLatestRef`

Um effect montado uma única vez — um interval, uma subscription, um listener — fica preso ao render que criou o closure. Listar o valor nas dependências desmonta e remonta o effect a cada mudança; omitir congela o valor. `useLatestRef` é a terceira saída:

```tsx
import { useEffect } from "react";
import { useLatestRef } from "tempest-react-sdk";

function Poller({ options }: { options: PollOptions }) {
  const optionsRef = useLatestRef(options);

  useEffect(() => {
    const id = setInterval(() => poll(optionsRef.current), 5_000);
    return () => clearInterval(id);
  }, [optionsRef]); // o interval sobrevive a toda mudança de options — e lê a última

  return null;
}
```

!!! note "`useLatestRef` ou `useStableCallback`?"
    Se o valor é uma **função que você quer chamar**, use `useStableCallback`: ele devolve algo chamável com identidade estável, sem obrigar cada call site a passar por `.current`. `useLatestRef` é para todo o resto — objetos de config, state, props.

### Cooldown — `useCountdown`

```tsx
import { useCountdown } from "tempest-react-sdk";

function ResendButton({ lastSentAt }: { lastSentAt: number }) {
  const remaining = useCountdown(60_000, lastSentAt);

  return (
    <button disabled={remaining > 0}>
      {remaining > 0 ? `Reenviar em ${Math.ceil(remaining / 1000)}s` : "Reenviar código"}
    </button>
  );
}
```

O hook é escrito em cima de um **timestamp**, não de um contador que decrementa. O restante é recalculado de `Date.now()` a cada tick, então aba em background throttlada, frame lento ou `setInterval` que derrapa não fazem a contagem discordar do relógio — e remontar o componente retoma no valor certo em vez de reiniciar. O interval para ao chegar em zero, em vez de continuar rodando atrás de um clamp.

Passe `{ tickMs: 50 }` quando o valor alimenta uma barra de progresso; o padrão de `1000` serve pro rótulo "tente de novo em Ns".

### Texto revelado letra a letra — `useTypewriter`

```tsx
import { useMediaQuery, useTypewriter } from "tempest-react-sdk";

function Dialogue({ line }: { line: string }) {
  const reduced = useMediaQuery("(prefers-reduced-motion: reduce)");
  const { displayedText, isComplete, skip } = useTypewriter(line, reduced ? 0 : 30);

  return <p onClick={skip}>{displayedText}{isComplete ? "" : "▌"}</p>;
}
```

Trocar `text` reinicia a revelação. O reset acontece **durante o render**, não num effect, então a string nova nunca pisca inteira por um frame antes da animação assumir.

!!! warning "Sempre dê saída ao leitor"
    Uma animação que não pode ser pulada é imposto sobre quem relê ou lê rápido. Ligue `skip` a um clique ou tecla — e trate `prefers-reduced-motion` passando `speedMs = 0`, que renderiza tudo de uma vez sem ramo condicional no componente.

### Disclosure — `useDisclosure`

```tsx
import { useDisclosure, Modal, Button } from "tempest-react-sdk";

function EditPanel() {
  const [opened, { open, close }] = useDisclosure(false);
  return (
    <>
      <Button onClick={open}>Editar</Button>
      <Modal open={opened} onClose={close} title="Editar perfil">
        …
      </Modal>
    </>
  );
}
```

Os handlers (`open`/`close`/`toggle`) têm referência estável entre renders — diferente de `useToggle`, é o atalho certo para overlays.

### Contador com clamp — `useCounter`

```tsx
import { useCounter, Button } from "tempest-react-sdk";

function Quantity() {
  const [count, { increment, decrement, reset }] = useCounter(1, { min: 1, max: 10 });
  return (
    <>
      <Button onClick={decrement}>−</Button>
      <span>{count}</span>
      <Button onClick={increment}>+</Button>
      <Button onClick={reset}>Resetar</Button>
    </>
  );
}
```

`useCounter(initial, { min, max })` clampa o valor — `increment`/`decrement`/`set` respeitam os limites.

### Lista como estado — `useListState`

```tsx
import { useListState, Button } from "tempest-react-sdk";

function TodoList() {
  const [items, handlers] = useListState<string>(["Comprar pão"]);
  return (
    <>
      <Button onClick={() => handlers.append("Novo item")}>Adicionar</Button>
      <ul>
        {items.map((item, i) => (
          <li key={i} onClick={() => handlers.remove(i)}>
            {item}
          </li>
        ))}
      </ul>
    </>
  );
}
```

Handlers imutáveis: `append`/`prepend`/`insert`/`remove`/`reorder`/`setItem`/`setState`/`apply`/`clear`. Use `handlers.reorder({ from, to })` para drag-and-drop.

### Map e Set reativos — `useMap` / `useSet`

```tsx
import { useMap, useSet } from "tempest-react-sdk";

function SelectionTracker() {
  const selected = useSet<string>();
  const meta = useMap<string, number>();

  return (
    <button
      onClick={() => {
        selected.toggle("a");
        meta.set("clicks", (meta.get("clicks") ?? 0) + 1);
      }}
    >
      {selected.size} selecionados · {meta.get("clicks") ?? 0} cliques
    </button>
  );
}
```

`useMap` retorna `{ map, set, delete, clear, get, has, size }` e `useSet` retorna `{ set, add, delete, clear, has, toggle, size }` — cada mutação gera uma nova referência e re-renderiza.

### Fila FIFO — `useQueue`

```tsx
import { useQueue, Button } from "tempest-react-sdk";

function Notifications() {
  const { queue, add, cleanQueue, size } = useQueue<string>({ limit: 3 });
  return (
    <>
      <Button onClick={() => add(`msg ${Date.now()}`)}>Enfileirar</Button>
      <Button onClick={cleanQueue}>Limpar visíveis ({size})</Button>
      <ul>
        {queue.map((msg, i) => (
          <li key={i}>{msg}</li>
        ))}
      </ul>
    </>
  );
}
```

`useQueue({ initialValues, limit })` mantém até `limit` itens visíveis em `queue`; o excedente fica num buffer e entra conforme `cleanQueue` libera espaço.

### Fechar ao clicar fora — `useClickOutside`

```tsx
import { useState } from "react";
import { useClickOutside } from "tempest-react-sdk";

function Menu() {
  const [open, setOpen] = useState(false);
  const ref = useClickOutside<HTMLDivElement>(() => setOpen(false));
  return open ? (
    <div ref={ref} role="menu">
      …
    </div>
  ) : null;
}
```

`useClickOutside(handler)` devolve um ref; o `handler` dispara em `mousedown`/`touchstart` fora do elemento.

### Título e favicon — `useDocumentTitle` / `useFavicon`

```tsx
import { useDocumentTitle, useFavicon } from "tempest-react-sdk";

function InboxPage({ unread }: { unread: number }) {
  useDocumentTitle(unread > 0 ? `(${unread}) Caixa de entrada` : "Caixa de entrada");
  useFavicon(unread > 0 ? "/favicon-alert.ico" : "/favicon.ico");
  return <main>…</main>;
}
```

Ambos são safe sem `window`; `useDocumentTitle` restaura o título anterior no unmount.

### Primeiro render — `useIsFirstRender`

```tsx
import { useEffect } from "react";
import { useIsFirstRender } from "tempest-react-sdk";

function Analytics({ query }: { query: string }) {
  const first = useIsFirstRender();
  useEffect(() => {
    if (!first) track("search-refined", { query });
  }, [query, first]);
  return null;
}
```

Retorna `true` apenas na primeira renderização — útil para pular efeitos de montagem.

## PWA & gestos de ponteiro

### Prompt de instalação com fallback — `useInstallPrompt`

`useBeforeInstallPrompt` (acima) só captura o evento `beforeinstallprompt` do Chromium. Mas metade dos seus usuários está no iOS Safari (que nunca dispara o evento) ou num fork Chromium do Android que removeu a API. `useInstallPrompt` resolve **qual estratégia** oferecer, num único `method`:

```tsx
import { useInstallPrompt } from "tempest-react-sdk";

function InstallButton() {
  const { method, install, openInChromeIntent } = useInstallPrompt();

  if (method === "native")
    return <button onClick={install}>Instalar app</button>;
  if (method === "ios")
    return <p>Toque em Compartilhar → Adicionar à Tela de Início</p>;
  if (method === "manual")
    return openInChromeIntent ? (
      <a href={openInChromeIntent}>Abrir no Chrome para instalar</a>
    ) : (
      <p>Use o menu do navegador → Instalar app</p>
    );
  return null; // "none" — já instalado ou runtime sem suporte
}
```

O `method` é resolvido assim:

- `"native"` → o evento `beforeinstallprompt` chegou; chame `install()` para disparar o prompt nativo.
- `"ios"` → iOS/iPadOS Safari; mostre as instruções de "Adicionar à Tela de Início".
- `"manual"` → fork Chromium sem a API, **ou** nenhum evento chegou dentro de `manualFallbackDelayMs` (3s por padrão); mostre instruções genéricas de menu.
- `"none"` → já rodando como PWA instalado (display-mode standalone) ou o cooldown de recusa está ativo.

Quando o usuário recusa, o hook grava um timestamp no `localStorage` e esconde a CTA por `declineCooldownMs` (7 dias por padrão). Tudo é plugável e safe sem `window`:

| Opção                   | Padrão                        | O que faz                                             |
| ----------------------- | ----------------------------- | ----------------------------------------------------- |
| `declineStorageKey`     | `"tempest:install-declined-at"` | Chave do `localStorage` para o timestamp de recusa. |
| `declineCooldownMs`     | `604800000` (7 dias)          | Por quanto tempo a CTA some após recusar.             |
| `manualFallbackDelayMs` | `3000`                        | Espera por `beforeinstallprompt` antes de cair em `"manual"`. |

!!! info "Helpers de ambiente exportados à parte"
    As funções puras por trás do hook também são exportadas — úteis sozinhas: `isIOS()`, `isAndroid()`, `isAndroidWithoutPromptApi()` (Mi/UC/Opera Mini/Huawei/KaiOS), `isStandalone()` e `buildOpenInChromeIntent()` (monta uma URL `intent://` que reabre a página no Chrome do Android, com fallback pra Play Store). O tipo `BeforeInstallPromptEvent` também vem do SDK.

### Long-press que devolve handlers — `useLongPressHandlers`

O `useLongPress(ref, fn)` (na tabela **DOM / viewport** acima) anexa listeners de ponteiro a um `ref`. Quando você prefere **espalhar handlers** direto num elemento e ainda suprimir o clique que segue o long-press, use `useLongPressHandlers`:

```tsx
import { useLongPressHandlers } from "tempest-react-sdk";

function AnimalCard({ id }: { id: string }) {
  const longPress = useLongPressHandlers(() => enterSelectionMode(id), {
    delayMs: 500,
  });

  return (
    <button
      {...longPress}
      onClick={() => {
        if (longPress.wasLongPress()) return; // segura o clique pós-hold
        openDetails(id);
      }}
    >
      Animal {id}
    </button>
  );
}

declare function enterSelectionMode(id: string): void;
declare function openDetails(id: string): void;
```

Dispara `onLongPress` uma vez após `delayMs` (mouse ou toque), cancela ao soltar/mover, e liga o `contextmenu` para o botão direito no desktop abrir o modo de seleção igual ao long-press do Android. `wasLongPress()` diz se a última interação foi um long-press — use no `onClick` pra não navegar duas vezes. Passe `{ disabled: true }` para deixar os handlers inertes.

### Reordenar por arrastar — `useSortable`

Arrastar para reordenar, com **caminho de teclado de igual peso**. O hook cuida só da interação: ele nunca mexe nos seus dados. `onReorder` dispara **uma vez** por movimento confirmado e você aplica, normalmente com `moveItem`.

```tsx
import { moveItem, useSortable } from "tempest-react-sdk";
import { useState } from "react";

export function PrioridadeDoBacklog() {
  const [itens, setItens] = useState(["Corrigir login", "Exportar CSV", "Modo escuro"]);

  const sortable = useSortable({
    itemCount: itens.length,
    roleDescription: "Item reordenável",
    onReorder: ({ from, to }) => setItens((atual) => moveItem(atual, from, to)),
  });

  return (
    <ul {...sortable.getListProps()} aria-label="Prioridade" ref={sortable.setContainer}>
      {itens.map((item, index) => (
        <li
          key={item}
          {...sortable.getItemProps(index)}
          className={index === sortable.overIndex ? "destaque" : undefined}
        >
          {item}
        </li>
      ))}
    </ul>
  );
}
```

| Campo | Tipo | O que é |
| --- | --- | --- |
| `activeIndex` | `number \| null` | Índice sendo arrastado, ou `null` em repouso |
| `overIndex` | `number \| null` | Onde ele cairia se soltasse agora — use pra desenhar o indicador |
| `getItemProps(index)` | props | Espalhe em cada item (pointer, teclado, `role="option"`, `tabIndex`) |
| `getListProps()` | props | Espalhe no container (`role="listbox"`) |
| `setContainer` | callback ref | Aponte pro container: é ali que o hit-test procura os itens |
| `cancel()` | `() => void` | Aborta o arrasto sem reordenar |

**Teclado**: `Espaço` pega o item · setas movem · `Espaço`/`Enter` soltam · `Escape` cancela.

!!! warning "Reorder que só funciona arrastando exclui quem usa teclado"
    É onde a maioria das implementações de drag-and-drop falha. Aqui o caminho de teclado não é um extra: é o mesmo estado (`activeIndex`/`overIndex`), a mesma confirmação e o mesmo `onReorder`. `role="listbox"` + `role="option"` + `aria-roledescription` são o que faz o leitor de tela anunciar que a lista é reordenável.

!!! info "Um `onReorder` por movimento, não por frame"
    O hook **não** chama `onReorder` durante o arrasto. Se chamasse, uma lista controlada re-renderizaria a cada `pointermove` — e os índices mudariam debaixo do próprio arrasto. Você desenha o preview com `overIndex`; a mutação acontece uma vez, no soltar.

!!! tip "Alturas diferentes funcionam"
    O hit-test lê os rects vivos dos filhos `[data-sortable-index]` em vez de supor altura fixa de linha. Mudar `itemCount` no meio de um arrasto **cancela** ele: a lista não tem mais os índices em que o arrasto se baseava, e confirmar moveria a linha errada.

## Resumo

- Hooks granulares, independentes e tree-shakáveis — importe só o que usar.
- Os que tocam o browser são **safe sem `window`**: retornam um default no servidor e hidratam após o mount.
- `useToggle` devolve `[value, { toggle, setTrue, setFalse, set }]` — o segundo item é um objeto.
- `useDisclosure`/`useCounter`/`useListState` retornam uma tupla `[estado, handlers]`; `useMap`/`useSet`/`useQueue` retornam um objeto único.
- `useAsync` é o primitivo sem cache; para dados de servidor com cache use React Query.
- Atenção aos arrays de dependência: `useStableCallback` para fugir de re-runs, deps explícitas no resto.

## Veja também

- [Componentes](./components.md) — `<Show>` / `<Hide>` usam `useBreakpoint` por baixo
- [Theme](./theme.md) — `useMediaQuery` pra responsivo programático
- [Query](./query.md) — React Query quando precisar de cache de servidor
- [Forms](./forms.md) — `useDebounce` em campos de busca, `useAsync` no submit

---

# http.md

# HTTP

Camada de fetch tipada com tratamento de 401 + refresh, parse JSON automático e upload com progresso. Inspirada no `RequestHandler` do alofans-frontend, mas factory-based pra cada app instanciar o seu próprio cliente.

!!! info "Por que um factory em vez de um singleton global?"
    Cada app tem seu próprio `baseURL`, sua forma de guardar o token e sua estratégia de logout. Um factory deixa você criar o cliente uma vez, injetar essas dependências, e exportar uma instância pronta — sem `import` de estado global espalhado pelo código.

## Quando usar

- Toda chamada HTTP do app passa por `createApiClient`.
- Pra validar a resposta contra um schema, combine com `parseResponse`.
- Pra upload com barra de progresso, use `uploadWithProgress`.
- Pra retentar operações instáveis, use `retry`; pra acompanhar um job, `usePoll`.

> Diagrama editável: [request-flow.drawio](./diagrams/request-flow.drawio) (abra no [draw.io](https://app.diagrams.net)).

## `createApiClient`

Crie o cliente uma vez (ex.: `src/services/api.ts`) e exporte:

```ts
import { createApiClient } from "tempest-react-sdk";
import { useAuthStore } from "./auth-store";
import { AuthService } from "./auth-service";

export const api = createApiClient({
  baseURL: import.meta.env.VITE_API_URL,
  getToken: () => useAuthStore.getState().token,
  onUnauthorized: () => useAuthStore.getState().logout(),
  refresh: async () => {
    await AuthService.refresh(); // refresh seta novo token no store
  },
  withCredentials: true,
  headers: { "X-Client": "web" },
});
```

Opções (todas exceto `baseURL` são opcionais):

- `baseURL` — prefixo de toda requisição. **Obrigatório.** Pode carregar caminho (`https://api.exemplo.com/api`) e pode ser relativo (`"/api"`, resolvido contra a origem atual). Ver [Base URL e prefixo](#base-url-e-prefixo).
- `prefix` — segmento sob o qual toda requisição fica aninhada, tipo `"/api"`. Ver [Base URL e prefixo](#base-url-e-prefixo).
- `getToken()` — chamado a cada request; retornar string injeta `Authorization: Bearer <token>`.
- `onUnauthorized(response)` — disparado sempre que a requisição termina sem autorização: 401 sem `refresh`, `refresh()` que rejeitou, ou repetição que voltou 401 de novo. Use pra deslogar.
- `refresh()` — quando presente e o request der 401, o cliente aguarda `refresh()` e repete a requisição **uma vez**.
- `retry` — `true` ou `RetryOptions`. **Desligado por default.** Ver [Retentativa embutida](#retentativa-embutida).
- `logger` — para onde o cliente reporta cada requisição que terminou. **Desligado por default.** Ver [Log de requisição](#log-de-requisicao).
- `withCredentials` — envia cookies em cross-origin (default `false`).
- `headers` — headers default mesclados em toda request.
- `fetcher` — implementação de `fetch` alternativa (default `globalThis.fetch`) — útil em testes.

Métodos: `get`, `post`, `put`, `patch`, `delete`, `upload`, `request`. Cada um aceita `RequestOptions` (`body`, `params`, e qualquer campo de `RequestInit` exceto `body`):

```ts
// GET com query params (serializados automaticamente)
const users = await api.get<User[]>("/users", {
  params: { page: 1, size: 20, active: true },
});

// POST com body JSON
const created = await api.post<User>("/users", {
  body: { name: "Ana", email: "ana@x.com" },
});

// DELETE
await api.delete<void>(`/users/${id}`);
```

Comportamento:

- `Content-Type: application/json` automático (exceto `FormData`).
- `Authorization: Bearer <token>` quando `getToken()` retorna string.
- Em 401 com `refresh` configurado: aguarda `refresh()`, repete o request 1x. Se falhar, chama `onUnauthorized` e lança `ApiError`.
- Em 401 sem `refresh`: chama `onUnauthorized` e lança `ApiError`.
- 204 retorna `undefined`.
- `Content-Type: application/json` na resposta → `JSON.parse`. Caso contrário, retorna texto cru.

!!! warning "`refresh` só repete uma vez"
    Se o `refresh()` rodar mas o retry ainda devolver 401, o cliente desiste, chama `onUnauthorized` e lança. Isso evita loop infinito de refresh quando a sessão realmente expirou.

    **Esse segundo 401 é o caso que importa.** Um `refresh()` que resolve não prova que a sessão está viva: o backend pode devolver um token que ele mesmo recusa — refresh token revogado, permissão retirada, corrida entre abas. Sem `onUnauthorized` aí, o app ficaria com um store dizendo "autenticado" enquanto toda requisição dá 401, e o usuário veria um erro genérico sem caminho de volta pro login.

!!! warning "`onUnauthorized` não deveria fazer requisição"
    O trabalho do hook é **local**: limpar store, storage e cache. `POST /auth/logout` pertence ao logout explícito do usuário, quando o token ainda vale — chamar de dentro do `onUnauthorized` é mandar a requisição com o token que o backend acabou de recusar, e ela volta 401/422.

    **O erro do hook não vaza mais.** O cliente aguarda o `onUnauthorized` e captura o que ele lançar, então quem chamou continua recebendo o `ApiError` da requisição original — antes da v0.48.0 o throw do hook tomava o lugar do 401, e o console mostrava dois erros onde havia um, o segundo sem relação com a requisição que falhou. Com um `logger` configurado, a falha do hook sai como `warn` em vez de desaparecer.

## Base URL e prefixo

Um serviço FastAPI da Tempest quase nunca fica na raiz do host: ele é montado sob um `root_path`, tipicamente `/api`. Você diz isso ao cliente de duas formas equivalentes — escrevendo o caminho no `baseURL`, ou passando `prefix`:

```ts
// as duas chegam em https://api.exemplo.com/api/auth/login
createApiClient({ baseURL: "https://api.exemplo.com/api" });
createApiClient({ baseURL: "https://api.exemplo.com", prefix: "/api" });

await api.post("/auth/login", { body: credentials });
```

!!! tip "Quando preferir `prefix`"
    Quando a variável de ambiente é usada por mais coisa que o cliente HTTP — um endpoint SSE, um host de mídia, um link que você mostra na tela. Deixe `VITE_API_URL` sendo a origem pura e ponha o prefixo só no cliente; nada mais precisa saber dele.

A barra inicial no caminho da chamada é indiferente — `"/auth/login"` e `"auth/login"` chegam no mesmo lugar:

```ts
const api = createApiClient({ baseURL: "https://api.exemplo.com", prefix: "/api" });

await api.get("/orders"); // https://api.exemplo.com/api/orders
await api.get("orders"); //  https://api.exemplo.com/api/orders
```

!!! warning "Isso mudou na v0.45.0"
    Até a v0.44.0 o cliente resolvia o caminho com `new URL(path, baseURL)`. Pela spec de URL, um caminho iniciado por `/` é absoluto **contra a origem**, então ele descartava em silêncio o caminho do `baseURL`: um cliente em `https://api.exemplo.com/api` pedindo `"/auth/login"` batia em `https://api.exemplo.com/auth/login` e tomava 404 em toda requisição, sem nada na config parecendo errado. O único jeito de acertar era escrever todo caminho sem a barra inicial.

    Se o seu app fez isso — caminhos relativos por causa do bug —, nada quebra: eles continuam resolvendo igual. Você pode voltar a escrever `/auth/login` quando quiser.

O prefixo é aplicado **no máximo uma vez**. Um caminho que já começa com ele passa direto, então dá pra migrar as chamadas aos poucos:

```ts
const api = createApiClient({ baseURL: "https://api.exemplo.com", prefix: "/api" });

await api.get("/api/orders"); // https://api.exemplo.com/api/orders — não vira /api/api
await api.get("/api-keys"); //  https://api.exemplo.com/api/api-keys — comparação por segmento
```

Duas escapadas úteis:

- **Caminho absoluto vence tudo.** `api.get("https://cdn.exemplo.com/arquivo")` ignora `baseURL` e `prefix` — é assim que se alcança um segundo host (upload assinado, CDN) sem criar um segundo cliente.
- **`baseURL` relativo** (`"/api"`) resolve contra a origem atual, que é a forma certa atrás do proxy do dev server ou de um reverse proxy servindo app e API do mesmo host. Fora do browser (sem `location`) isso lança um `TypeError` dizendo qual config corrigir, em vez de um `Invalid base URL` genérico.

Para montar a mesma URL fora do cliente — um `EventSource` de SSE, um `<img>` — o helper é exportado:

```ts
import { buildApiUrl } from "tempest-react-sdk";

const stream = new EventSource(
  buildApiUrl(import.meta.env.VITE_API_URL, "/sse/events", {
    prefix: "/api",
    params: { access_token: token },
  }),
);
```

## Log de requisição

O cliente não escreve em console nenhum por conta própria. Passe um `logger` e cada tentativa que termina vira uma linha:

```ts
import { createApiClient, createLogger } from "tempest-react-sdk";

const log = createLogger({ level: import.meta.env.DEV ? "debug" : "warn" });

export const api = createApiClient({
  baseURL: import.meta.env.VITE_API_URL,
  logger: log.child("http"),
});

await api.get("/orders");
// [http] GET /orders → 200  { requestId: "8f2c…", status: 200, ms: 143 }
```

O que sai:

| Evento | Nível | Linha |
| --- | --- | --- |
| Resposta abaixo de 400 | `debug` | `GET /orders → 200` |
| Resposta 400 ou acima | `warn` | `GET /admin → 403` |
| Requisição que não teve resposta | `warn` | `GET /orders → no response` (contexto carrega o `error`) |
| `onUnauthorized` disparando | `warn` | `unauthorized — calling onUnauthorized` |
| `onUnauthorized` lançando | `warn` | `onUnauthorized threw — keeping the original response error` (contexto com o `error`) |

O contexto de cada linha traz `requestId`, `status` e o `ms` decorrido. É **uma linha por tentativa**, então a repetição depois do `refresh` e cada retry aparecem — é assim que se lê "401, renovou, 200" no log.

!!! info "É `logger`, não `debug: true`"
    Uma flag booleana daria um botão só para o SDK inteiro: ou tudo ou nada, sempre no `console`, e as strings ficariam no bundle mesmo desligada. Com `logger` o **nível** mora no logger (`createLogger({ level })`), o **destino** mora no sink (console em dev, Sentry em produção, array no teste) e o **escopo** mora no namespace — `log.child("http")` separa dois clientes no mesmo app.

    Qualquer objeto com `debug` e `warn` serve (o tipo exportado é `ApiClientLogger`), então não precisa ser o logger do SDK.

!!! warning "O que o log nunca carrega"
    Body, header e query string ficam de fora, de propósito: o `Authorization` é bearer token, o body do login é senha, e um `access_token` em query param acabaria escrito no sink junto. O que é logado é o método, o caminho como o call site escreveu, e os números.

    Se você precisa do payload para depurar, envolva o `fetcher` no seu app — aí a decisão de logar segredo é sua, explícita, e não vai para produção por descuido.

## Retentativa embutida

`retry` liga a repetição automática dentro do próprio cliente, com o mesmo backoff exponencial do helper `retry()`:

```ts
const api = createApiClient({
  baseURL: import.meta.env.VITE_API_URL,
  retry: true, // política embutida
});

const users = await api.get<User[]>("/users"); // repete sozinho se der 503
```

**Vem desligado**, e ligar não é obrigatório: sem `retry`, o cliente falha na primeira tentativa, exatamente como antes.

A política embutida é conservadora de propósito:

| Repete | Não repete |
| ------ | ---------- |
| `GET`, `HEAD`, `OPTIONS` | `POST`, `PUT`, `PATCH`, `DELETE` |
| Falha de rede (status `0`), `408`, `425`, `429`, qualquer `5xx` | `400`, `401`, `403`, `404`, `422` — qualquer outro `4xx` |

!!! danger "Escrita nunca repete sozinha"
    Um `POST` repetido pode cobrar duas vezes, criar dois pedidos, disparar dois webhooks. `PUT` e `DELETE` são idempotentes no papel, mas um backend que registra ou fatura por chamada ainda vê duas — por isso ficam de fora também.

    Para repetir uma escrita, torne-a idempotente com [`generateIdempotencyKey`](#generateidempotencykey) e passe seu próprio `shouldRetry`:

    ```ts
    const key = generateIdempotencyKey(); // uma vez, fora do loop

    const api = createApiClient({
      baseURL,
      headers: { "Idempotency-Key": key },
      retry: { shouldRetry: (error) => isApiError(error) && error.status >= 500 },
    });
    ```

    Um `shouldRetry` seu **substitui a política inteira**, checagem de método incluída — é esse o ponto de escape.

Repetir um `400` ou um `403` não conserta payload errado nem permissão que o usuário não tem: só gasta o tempo dele pra mostrar o mesmo erro. Por isso o corte é por status, não "qualquer erro".

Detalhes que valem saber:

- A retentativa envolve a requisição **inteira**, refresh incluído. Uma tentativa que gasta o ciclo de 401 → refresh → repetição conta como uma tentativa só.
- Cada tentativa carrega o seu próprio `X-Request-ID`, então o backend consegue distinguir as tentativas nos logs.
- `Retry-After` (em `429`/`503`) é respeitado e sobrepõe o backoff daquela tentativa.
## Timeout e cancelamento

O cliente abandona uma requisição depois de **15 s** por default, e depois de **5 min** quando o body é `FormData`.

```ts
const api = createApiClient({
  baseURL: import.meta.env.VITE_API_URL,
  timeout: 15_000, // default
  uploadTimeout: 300_000, // default, aplicado quando o body é FormData
});

// Override por chamada, para o endpoint que não cabe em nenhum dos dois.
const report = await api.get("/relatorio-pesado", { timeout: 60_000 });

// `null` desliga — para stream ou long poll.
const stream = await api.get("/eventos", { timeout: null });
```

!!! danger "Antes disso não havia timeout nenhum"
    Uma conexão TCP que morre sem FIN **não devolve erro**: o browser segura a
    requisição por minutos, ou para sempre. Sem piso, o sintoma é spinner eterno
    exatamente na rede ruim que um SDK offline-first existe para sobreviver.

!!! tip "Por que upload tem timeout próprio"
    Upload binário não é uma requisição lenta, é outro tipo de requisição. Um
    timeout único obriga a escolher entre curto o bastante para proteger uma
    chamada normal e longo o bastante para terminar um arquivo — e 15 s corta o
    upload no meio do body, que o servidor precisa então interpretar como payload
    truncado.

    A detecção é o body ser `FormData`, o mesmo teste que já decide o
    `Content-Type`.

### Timeout vira `status: 0`, abort continua abort

Timeout chega como `ApiError` com `status: 0` — a mesma forma que o cliente já usava para "não chegou ao servidor". Isso não é detalhe de implementação, é o que faz a política de retry replicar um timeout **sem caso especial**: `isRetriableStatus(0)` é `true`.

Já um `abort` que **você** pediu propaga como `DOMException`, e portanto nunca é retentado — o `shouldRetry` embutido exige `TempestApiError`.

```ts
const controller = new AbortController();
const pending = api.get("/lento", { signal: controller.signal });
controller.abort(); // rejeita com DOMException, sem retentar
```

!!! check "`signal` sempre funcionou — só não estava documentado"
    `RequestOptions` estende `Omit<RequestInit, "body">`, então `signal` era aceito
    e repassado ao `fetch` desde sempre. Ninguém tinha como descobrir: não
    aparecia na interface e não estava em nenhuma doc. Agora está declarado
    explicitamente, o que para o compilador é redundante e para quem lê não é.

    O caso que isso resolve é o react-query: passe o `signal` que a `queryFn`
    recebe e a requisição é cancelada em unmount e em refetch.

    ```tsx
    useQuery({
      queryKey: ["pedidos"],
      queryFn: ({ signal }) => api.get("/pedidos", { signal }),
    });
    ```

- Precisa de retentativa em uma chamada específica, não no cliente todo? O helper [`retry`](#retry-backoff-exponencial) continua ali, e agora usa a **mesma** classificação de status.

## `parseResponse`

Valida payload com zod. Em dev/test, mostra exatamente qual campo divergiu (contract drift). Em prod, mensagem genérica (não vaza estrutura interna).

```ts
import { parseResponse } from "tempest-react-sdk";
import { z } from "zod";
import { api } from "./api";

const userSchema = z.object({ id: z.string(), name: z.string() });

const raw = await api.get<unknown>("/users/me");
const user = parseResponse(userSchema, raw, "GET /users/me");
// user: { id: string; name: string } — tipado a partir do schema
```

!!! tip "O 3º argumento é o contexto"
    Passe sempre um label como `"GET /users/me"`. Ele aparece na mensagem de erro de dev e torna trivial localizar qual endpoint quebrou o contrato.

## `uploadWithProgress`

`fetch` não reporta upload progress no navegador — esse helper usa `XMLHttpRequest` por baixo, mantendo o mesmo contrato de erro do `createApiClient` (lança `ApiError`).

```tsx
import { useState } from "react";
import { uploadWithProgress } from "tempest-react-sdk";
import { useAuthStore } from "./auth-store";

export function AvatarUpload() {
  const [progress, setProgress] = useState(0);

  async function handleFile(file: File) {
    const formData = new FormData();
    formData.append("file", file);
    const controller = new AbortController();

    const result = await uploadWithProgress<{ url: string }>({
      url: `${import.meta.env.VITE_API_URL}/uploads`,
      method: "POST",
      body: formData,
      getToken: () => useAuthStore.getState().token,
      onProgress: ({ fraction }) => fraction !== null && setProgress(Math.round(fraction * 100)),
      signal: controller.signal,
    });

    console.log("URL final:", result.url);
  }

  return (
    <label>
      <input type="file" onChange={(e) => e.target.files?.[0] && handleFile(e.target.files[0])} />
      <progress value={progress} max={100} />
    </label>
  );
}
```

`onProgress` recebe `{ loaded, total, fraction, lengthComputable }`. `fraction` é `null` quando o tamanho total é desconhecido. Abortar via `signal` rejeita com `DOMException("Aborted")`.

## `retry` — backoff exponencial

Reexecuta uma factory async com delays crescentes (`initialDelay` dobrando a cada tentativa, limitado por `maxDelay`):

```ts
import { retry } from "tempest-react-sdk";
import { api } from "./api";
import type { ApiError } from "tempest-react-sdk";

const data = await retry(() => api.get("/flaky-endpoint"), {
  retries: 5,
  initialDelay: 300,
  maxDelay: 10_000,
  // Não retentar erros de cliente (4xx) — só falhas transitórias
  shouldRetry: (error) => (error as ApiError).status >= 500,
  onRetry: ({ attempt, delay }) => console.warn(`Tentativa ${attempt} em ${delay}ms`),
});
```

!!! note "O default já evita retentar o que não vai melhorar"
    Você **não precisa** escrever o `shouldRetry` do exemplo acima. Sem ele, o
    default replica qualquer erro que não tenha forma de erro de API — falha de
    transporte não tem status pra julgar — e, para os que têm, só os status que
    `isRetriableStatus` aceita: falha de rede (`0`), `408`, `425`, `429` e qualquer
    `5xx`. Um 403 ou 422 falha de primeira.

!!! tip "`isRetriableStatus` — a política, reutilizável"
    A lista é exportada, então um `shouldRetry` seu estende a política em vez de
    reescrevê-la:

    ```ts
    import { isApiError, isRetriableStatus, retry } from "tempest-react-sdk";

    const data = await retry(() => api.post("/import", { body }), {
      shouldRetry: (error) =>
        isApiError(error) &&
        (isRetriableStatus(error.status) || error.code === "IMPORT_LOCKED"),
    });
    ```

    Ela é a **única** dona dessa decisão: o cliente, o default das queries e este
    helper leem daqui. Eram três listas, e a das queries estava sem o `425` — o
    mesmo `425 Too Early` era retentado por um caminho e não pelo outro.

## `usePoll` — polling com guarda de overlap

Chama uma factory async num intervalo fixo, pulando ticks enquanto a chamada anterior não terminou. Ideal pra acompanhar o status de um job:

```tsx
import { usePoll } from "tempest-react-sdk";
import { api } from "./api";

interface Job {
  id: string;
  status: "pending" | "done" | "failed";
}

export function JobStatus({ jobId }: { jobId: string }) {
  const { data, loading, error, stop } = usePoll<Job>(() => api.get<Job>(`/jobs/${jobId}`), {
    interval: 3000,
    stopWhen: (job) => job.status !== "pending",
    onError: (err) => console.error(err),
  });

  if (loading && !data) return <p>Verificando…</p>;
  if (error) return <p>Erro ao consultar job.</p>;
  return (
    <div>
      Status: {data?.status}
      <button onClick={stop}>Parar</button>
    </div>
  );
}
```

`usePoll` também devolve `start()` pra retomar manualmente, e aceita `disabled` pra pausar sem desmontar.

## `generateIdempotencyKey`

Gera um UUID v4 pra usar no header `Idempotency-Key`. Mande o **mesmo** valor em retries de uma operação que não pode rodar duas vezes (cobrança, criação de pedido):

```ts
import { generateIdempotencyKey } from "tempest-react-sdk";
import { api } from "./api";

const key = generateIdempotencyKey();

await api.post("/orders", {
  body: { items },
  headers: { "Idempotency-Key": key },
});
```

!!! warning "Gere a key uma vez por operação, não por tentativa"
    Se você gerar uma key nova a cada retry, o servidor trata cada chamada como nova e a proteção some. Crie a key **antes** do loop de retry e reutilize.

## Erros

`ApiError = { status, detail, body }`. Sempre lance — não retorne resultado falsy. UIs podem reagir por `status`:

```ts
import type { ApiError } from "tempest-react-sdk";
import { api } from "./api";

try {
  await api.get("/users/me");
} catch (err) {
  const error = err as ApiError;
  if (error.status === 403) toast.error("Sem permissão");
  else toast.error(error.detail);
}
```

!!! info "422 do FastAPI: `detail` é lista, e `error.fields` é o que o formulário quer"
    Um erro de validação do FastAPI chega como `detail: [{ loc, msg, type }]`. O cliente monta duas coisas dessa lista:

    - **`error.fields`** — `{ email: "Field required", "items.0.price": "Input should be greater than 0" }`, indexado pelo caminho do campo, que é o que um formulário precisa. O prefixo de `loc` que só nomeia a parte da requisição (`body`, `query`, `path`, `header`, `cookie`) é descartado. Campo repetido mantém a primeira mensagem — input mostra um erro por vez.
    - **`error.detail`** — a mesma coisa achatada numa linha, para log. Carrega caminho de campo e a redação do validador; é texto de desenvolvedor.

    ```ts
    import { isApiError } from "tempest-react-sdk";

    try {
      await api.post("/users", { body: form });
    } catch (err) {
      if (isApiError(err) && err.fields) {
        for (const [field, message] of Object.entries(err.fields)) {
          setError(field, { message });
        }
      }
      toast.error(describeApiError(err, "Não foi possível salvar"));
    }
    ```

    Sem `fields` isso exigia varrer `error.body` com um cast — parsear de volta a linha que o próprio SDK montou.

!!! warning "Não jogue o `detail` de um 422 na tela"
    `"items.0.price: Input should be greater than 0"` numa interface em pt-BR é meia frase em inglês nomeando estrutura interna. É por isso que o `describeApiError` **não** repassa o `detail` quando `fields` está preenchido: ele devolve a frase de validação ("Confira os campos destacados e tente de novo.", traduzível por `tempest.error.validation`), e as mensagens por campo ficam onde servem — nos inputs.

### Do erro tipado para a frase na tela — `describeApiError`

O `try/catch` acima escreve a frase à mão, e todo app escreve o mesmo funil — errando sempre no mesmo lugar: a requisição que **não chegou** ao servidor tem `status === 0`, e sem tratamento ela vira "erro 0" na tela.

```ts
import { describeApiError } from "tempest-react-sdk";

try {
  await api.get("/pedidos");
} catch (error) {
  toast.error(describeApiError(error, "Não foi possível carregar os pedidos"));
}
```

A ordem do funil:

1. **`codes[error.code]`** — a frase que **você** escreveu pra aquele caso do backend. Ganha de todo o resto: nada que o funil deduz bate uma frase escrita por quem conhecia o contrato e a tela.
2. **Requisição que não chegou** — `status === 0`, ou um erro qualquer com o browser se declarando offline → frase de offline.
3. **Rejeição de validação** — `error.fields` preenchido → frase de validação, **não** o `detail` (que é técnico). As mensagens por campo continuam em `fields`.
4. **`detail` do backend** — o texto mais específico disponível, e já escrito para uma pessoa.
5. **`fallback`**, com `(HTTP <status>)` anexado quando há status — o print no chamado de suporte carrega o único dado que o dev precisa.

### `codes` — o `switch` que todo app reescrevia

O cliente já entrega o `code` do backend no `ApiError`, mas sem um lugar pra ele cada app escreve o mesmo `switch` pra virar frase no idioma dele:

```ts
import { describeApiError } from "tempest-react-sdk";

try {
  await api.post("/services/1/candidates", { body: payload });
} catch (error) {
  toast.error(
    describeApiError(error, "Não foi possível se candidatar", {
      codes: {
        SERVICE_FULL: "Este serviço atingiu o limite de vagas.",
        CANDIDATE_ALREADY_EXISTS: "Você já se candidatou a este serviço.",
      },
    }),
  );
}
```

Código que o catálogo não conhece simplesmente segue o funil. Sem `codes`, nada muda.

!!! tip "`useDetail: false` quando o `detail` é pra desenvolvedor"
    Alguns backends escrevem o `detail` pro log, não pra tela — ou ele ecoa interno. Com `useDetail: false` o passo 4 é pulado e o resultado é sempre uma frase sua, a de offline, a de validação, ou o `fallback` com `(HTTP <status>)`. As frases de offline e validação continuam valendo: elas são do SDK, não do backend.

Duas superfícies, mesmo funil:

| | Quando usar |
| --- | --- |
| `describeApiError(error, fallback, options?)` | Função pura. Roda em interceptor, logger, qualquer lugar fora da árvore React. |
| `useDescribeApiError()` | Hook. Resolve a frase fixa pelo `I18nProvider` ativo; devolve `(error, fallback, options?) => string`, com as mesmas opções da função pura. |

```tsx
import { useDescribeApiError } from "tempest-react-sdk";

const describe = useDescribeApiError();
const { mutate } = useMutation({
  mutationFn: salvar,
  onError: (error) => toast.error(describe(error, "Não foi possível salvar")),
});
```

!!! info "O hook não duplica o funil — ele só entrega as strings"
    `useDescribeApiError` chama a função pura. Existir nos dois formatos é sobre **onde** o código roda: contexto React não é alcançável de um interceptor, e passar tradução na mão em todo componente é o que o hook evita.

!!! check "Funciona sem `I18nProvider`, e sem a chave no catálogo"
    i18n é opt-in no SDK. Sem provider, ou com um catálogo que nunca definiu `tempest.error.offline`, a frase cai no default em pt-BR — em vez de estourar ou de imprimir a chave crua na cara do usuário (que é o que `t` devolve quando não encontra).

!!! note "As constantes que acompanham"
    `DEFAULT_API_ERROR_STRINGS` traz as frases pt-BR usadas quando nada mais responde
    (`offline` e `validation`) — útil pra escrever as suas a partir delas.
    `API_ERROR_OFFLINE_KEY` (`"tempest.error.offline"`) e
    `API_ERROR_VALIDATION_KEY` (`"tempest.error.validation"`) são as chaves que o hook
    procura no catálogo; defina-as no seu `messages` para traduzir cada frase.

!!! warning "`detail` sintético não vence o seu `fallback`"
    Quando a resposta não traz corpo, `buildApiError` sintetiza `Erro <status>`. `describeApiError` reconhece esse texto e prefere o seu `fallback` — "Erro 500" diz estritamente menos que "Não foi possível carregar os pedidos".

## Recap

- `createApiClient({ baseURL, getToken, onUnauthorized, refresh, ... })` cria um cliente tipado; instancie uma vez e exporte.
- `baseURL` pode carregar caminho (`https://host/api`) ou ser relativo (`"/api"`), e `prefix: "/api"` diz a mesma coisa deixando a env var como origem pura. A barra inicial na chamada é indiferente; o prefixo nunca é aplicado duas vezes. `buildApiUrl` monta a mesma URL fora do cliente.
- 401 com `refresh` → tenta renovar e repete 1x. `onUnauthorized` dispara em todo desfecho sem autorização — sem refresh, refresh que rejeitou, ou repetição que voltou 401.
- `retry: true` liga a retentativa dentro do cliente: só método idempotente, só falha de rede/`408`/`425`/`429`/`5xx`. Escrita nunca repete sozinha.
- `logger` é opt-in e o client não escreve em console sem ele: uma linha por tentativa (`debug` abaixo de 400, `warn` de 400 pra cima) com `requestId`, `status` e `ms`, nunca body/header/query.
- `parseResponse(schema, raw, context)` valida o payload com zod e aponta o campo divergente em dev.
- `uploadWithProgress` usa XHR pra reportar progresso byte a byte; para arquivo grande, `createResumableUpload` divide em chunks e retoma — veja [Upload resumível](./resumable-upload.md).
- `retry` (backoff exponencial + `shouldRetry`) e `usePoll` (intervalo com guarda de overlap) cobrem operações instáveis e acompanhamento de jobs.
- `generateIdempotencyKey` — gere uma vez por operação, reutilize nos retries.
- `describeApiError(error, fallback)` (puro) e `useDescribeApiError()` (com i18n) transformam o erro tipado na frase da tela, tratando `status === 0` como offline em vez de "erro 0" e um 422 com `fields` como frase de validação em vez do `detail` técnico.
- `error.fields` indexa as mensagens do 422 por caminho de campo — é o que vai direto pro `setError` do formulário.

## Veja também

- [Auth + Guard](./auth.md)
- [Passkeys](./passkeys.md) — login sem senha em cima do mesmo client
- [Upload resumível (tus)](./resumable-upload.md) — quando uma request só não basta
- [Logger](./logger.md) — o `logger` que o client aceita
- [Query](./query.md) — alimenta as `queryFn`
- [SSE](./sse.md) — usa `withCredentials` igual ao client
- Diagrama: [request-flow.drawio](./diagrams/request-flow.drawio)

---

# i18n.md

# i18n

i18n minimalista (≈ 1.5KB gzip) embutido no SDK. Cobre o caso comum — 2 ou 3 idiomas, interpolação e plural simples — sem o peso de uma biblioteca completa.

!!! info "Por que um i18n próprio?"
    A maioria dos apps Tempest precisa apenas de PT-BR + EN com algumas dezenas de strings. Puxar `i18next` (e seus plugins de backend, detector e formatador) para isso adiciona kilobytes e configuração que ninguém vai manter. O SDK entrega o suficiente para o caso simples e barato — e sai do caminho quando você precisa de mais.

## O catálogo

Tudo começa por um catálogo: um mapa `{ [locale]: { [key]: "texto" } }`. As chaves são suas — use nomes planos, com namespace (`"auth.login"`) ou o que combinar com o seu pipeline de strings. O SDK não impõe schema.

```tsx
// src/i18n.ts
import type { Catalog } from "tempest-react-sdk";

export const messages: Catalog = {
  "pt-BR": {
    greet: "Olá, {name}",
    "nav.home": "Início",
    alos_one: "{count} Alô",
    alos_other: "{count} Alôs",
  },
  en: {
    greet: "Hi, {name}",
    "nav.home": "Home",
    alos_one: "{count} Alo",
    alos_other: "{count} Alos",
  },
};
```

## Montando o provider

Envolva a árvore com `I18nProvider`, informando o `locale` inicial, um `fallbackLocale` opcional e o catálogo. Aqui vai um app completo e executável:

```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { I18nProvider } from "tempest-react-sdk";
import "tempest-react-sdk/styles.css";
import { messages } from "./i18n";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <I18nProvider locale="pt-BR" fallbackLocale="en" messages={messages}>
      <App />
    </I18nProvider>
  </StrictMode>,
);
```

!!! tip "Grátis: `<html lang>` e persistência"
    O `I18nProvider` escreve `<html lang="pt-BR">` automaticamente (bom para SEO e leitores de tela) e persiste a escolha do usuário em `localStorage["tempest-locale"]`. Para desativar a persistência, passe `storageKey={null}`.

## Traduzindo na UI

`useI18n()` devolve os helpers de tradução mais `setLocale`, `locale` e `availableLocales`. Um componente completo:

```tsx
import { useI18n } from "tempest-react-sdk";

export function Header() {
  const { t, plural, formatNumber, locale, availableLocales, setLocale } = useI18n();

  return (
    <header>
      <p>{t("greet", { name: "Mau" })}</p> {/* "Olá, Mau" */}
      <p>{plural("alos", 3)}</p> {/* "3 Alôs" */}
      <p>{formatNumber(1234.5, { style: "currency", currency: "BRL" })}</p> {/* "R$ 1.234,50" */}
      <select value={locale} onChange={(event) => setLocale(event.target.value)}>
        {availableLocales.map((code) => (
          <option key={code} value={code}>
            {code}
          </option>
        ))}
      </select>
    </header>
  );
}
```

Quando só precisa de `t`, use o atalho `useTranslate()` — evita o destructuring:

```tsx
import { useTranslate } from "tempest-react-sdk";

function NavHome() {
  const t = useTranslate();
  return <a href="/">{t("nav.home")}</a>;
}
```

!!! warning "`useI18n` exige o provider"
    Chamar `useI18n()` (ou `useTranslate()`) fora de um `<I18nProvider>` lança `useI18n must be used inside an <I18nProvider>`. Mantenha o provider acima de qualquer componente que traduza.

!!! tip "`useOptionalI18n()` para código que precisa funcionar sem catálogo"
    Devolve `null` fora do provider em vez de lançar. É o que uma peça reutilizável usa quando quer ser traduzida onde existe catálogo e continuar funcionando onde não existe — i18n é opt-in neste SDK, e exigir o provider transformaria "você não configurou tradução" em crash. O `useDescribeApiError` do módulo `http` é exatamente esse caso.

    ```tsx
    const i18n = useOptionalI18n();
    const titulo = i18n?.t("dashboard.title") ?? "Painel";
    ```

## Interpolação

Placeholders no formato `{name}` são substituídos pelos valores passados em `params`. Uma chave ausente cai para o `fallbackLocale`; se também faltar lá, o helper devolve a própria chave (nunca quebra a tela). Um placeholder sem valor permanece literal — `{name}` — facilitando achar a string esquecida.

```tsx
t("greet", { name: "Ana" }); // "Olá, Ana"
t("greet"); // "Olá, {name}"  (sem params → placeholder literal)
t("inexistente"); // "inexistente" (sem fallback → a própria chave)
```

## Texto default por chave

Quando a chave não existe em nenhum dos locales, `t` devolve a própria chave — o que é ótimo para achar string esquecida em desenvolvimento e péssimo para o usuário, que lê `cart.empty` na tela. O terceiro argumento resolve:

```tsx
t("cart.empty", undefined, { default: "Seu carrinho está vazio" });
// catálogo definiu  → a tradução
// catálogo não definiu → "Seu carrinho está vazio"
```

O default é **interpolado como qualquer outra mensagem**, então carrega placeholders:

```tsx
t("cart.count", { n: 3 }, { default: "{n} itens" }); // "3 itens"
```

`plural` aceita o mesmo, depois das duas buscas com sufixo:

```tsx
plural("boxes", 2, undefined, { default: "{count} caixas" }); // "2 caixas"
```

!!! danger "Não detecte o miss comparando com a chave"
    A tentação é `const v = t(k); const texto = v === k ? meuDefault : v;`. Isso está
    **errado** para um catálogo que mapeia legitimamente a chave para ela mesma —
    `{ "cart.empty": "cart.empty" }`, o que catálogo gerado por máquina ou catálogo
    placeholder faz — e nesse caso o seu default vence uma tradução que existia.

    Só a camada de i18n sabe se houve miss, porque só ela viu o catálogo. Passe
    `default` e deixe ela responder. Este é o caminho que as strings internas do
    próprio SDK usam (`tempest.error.offline`, em `useDescribeApiError`).

## Plurais

`plural(key, count, params?)` escolhe entre `${key}_one` (quando `count === 1`) e `${key}_other` (qualquer outro valor), com `{count}` disponível na interpolação:

```tsx
plural("alos", 1); // "1 Alô"   → usa alos_one
plural("alos", 5); // "5 Alôs"  → usa alos_other
```

!!! note "Plurais ricos? Vá de i18next"
    Esse esquema `_one` / `_other` cobre PT-BR e EN. Idiomas com mais categorias plurais (russo, polonês, árabe) precisam de `Intl.PluralRules` — não vale a pena reimplementar aqui. Para esses casos, troque por [`i18next`](https://www.i18next.com/) diretamente. O SDK assume o caso simples deliberadamente.

## Sem React (imperativo)

`createI18n` é a base; o provider só adiciona o estado React por cima. Use-o em utilitários, testes ou loaders fora da árvore de componentes:

```ts
import { createI18n } from "tempest-react-sdk";
import { messages } from "./i18n";

const i18n = createI18n({ locale: "pt-BR", fallbackLocale: "en", messages });

i18n.t("greet", { name: "Mau" }); // "Olá, Mau"
i18n.formatDate(new Date(), { dateStyle: "long" });

const en = i18n.withLocale("en"); // novo I18n, mesmo catálogo
en.t("greet", { name: "Mau" }); // "Hi, Mau"
```

## Carregamento dinâmico

Carregue um JSON por locale e passe para o provider. Para code-split por rota, troque `messages` via state — chaves não encontradas caem no fallback enquanto o resto carrega:

```ts
const ptBR = await fetch("/i18n/pt-BR.json").then((response) => response.json());
```

## Recap

- O **catálogo** é um mapa `{ locale: { key: "texto" } }` — chaves livres, sem schema.
- `I18nProvider` recebe `locale`, `fallbackLocale` e `messages`; escreve `<html lang>` e persiste em `localStorage["tempest-locale"]` (desative com `storageKey={null}`).
- `useI18n()` expõe `t`, `plural`, `formatNumber`, `formatDate`, `setLocale`, `locale`, `availableLocales`; `useTranslate()` é o atalho só-`t`.
- `t` interpola `{placeholder}`, cai no fallback e por fim devolve a própria chave — nunca quebra.
- `plural` usa os sufixos `_one` / `_other`; plurais complexos pedem `i18next`.
- `createI18n` roda fora do React; `withLocale` clona o objeto em outro idioma.

## Veja também

- [Tema](./theme.md) — combinar com `<html lang>` é grátis
- [App Providers](./app-providers.md) — montar i18n junto com Query, Theme e ErrorBoundary
- [Utils](https://github.com/mauriciobenjamin700/tempest-react-sdk#utils) — `formatCurrency` / `formatDate` para PT-BR direto

---

# icons.md

# Ícones por slug

Todo componente do SDK que aceita ícone aceita um `ReactNode`:

```tsx
import { Button } from "tempest-react-sdk";
import { Save } from "lucide-react";

<Button leftIcon={<Save size={18} />}>Salvar</Button>;
```

Isso resolve o caso em que **você sabe o ícone na hora de escrever o código**. Mas
às vezes o nome do ícone chega pronto: um menu que a API devolve, um cadastro no
CMS, uma tabela de configuração. Aí não há o que importar — só existe a string
`"layout-dashboard"`.

É pra isso que existe o subpath `tempest-react-sdk/icons`. 🚀

## O caminho mais curto

```tsx
import { Icon } from "tempest-react-sdk/icons";

export function Toolbar() {
    return (
        <div>
            <Icon name="save" size={18} />
            <Icon name="trash-2" size={18} />
        </div>
    );
}
```

Pronto — sem provider, sem configuração. Os **2024 slugs** do lucide funcionam
assim, incluindo nome que só existe em runtime:

```tsx
<Icon name={row.iconSlug} />
```

!!! info "Slug é kebab-case, não PascalCase"
    O nome é o do lucide em kebab-case: `"circle-alert"`, não `"CircleAlert"`.
    `"trash-2"`, não `"Trash2"`. Em dev, um nome errado sai no console com essa
    dica.

## Não instale `lucide-react` você mesmo

O `lucide-react` é **dependência direta do SDK** — instalar ele no seu app é o que
cria problema, não o que resolve.

```bash
npm uninstall lucide-react
```

!!! danger "Duas cópias de lucide = bytes duplicados e tabela de slug quebrada"
    Se o seu `package.json` declara `lucide-react` numa faixa diferente da do SDK,
    o gerenciador instala **duas cópias físicas**. Dois efeitos, e o segundo é o
    grave:

    1. **Bytes duplicados** no bundle — o app importa da cópia dele, o SDK da
       cópia dele, e nenhuma das duas é tree-shaken pela outra.
    2. **Skew de versão**: as tabelas de slug do `/icons` são **geradas** contra a
       versão que o SDK declara (`^1.31.0`). Uma segunda cópia mais antiga pode não
       ter exports que as tabelas referenciam, e aí o erro aparece no build do app
       como `X is not exported by lucide-react` — apontando pra dentro do SDK, o
       que torna a causa difícil de achar.

    A regra: **uma cópia só**, a que o SDK trouxe.

!!! info "Se você importa componentes do lucide direto"
    Usando só `<Icon name="…" />`, não precisa declarar lucide em lugar nenhum.

    Se você também escreve `import { Save } from "lucide-react"` no seu código, o
    que acontece depende do gerenciador:

    - **npm / yarn** — hoisting deixa a cópia do SDK visível na raiz do seu
      `node_modules`, então o import resolve sem você declarar nada. É o caminho
      recomendado.
    - **pnpm** (isolamento estrito) — o app não vê dependência que não declarou,
      então você **precisa** declarar. Nesse caso use **a mesma faixa do SDK**
      (`"lucide-react": "^1.31.0"`) pra continuar existindo uma cópia só.

!!! tip "Confirme que sobrou uma"
    ```bash
    npm ls lucide-react
    ```
    Mais de uma linha na saída (ou uma cópia aninhada em
    `node_modules/tempest-react-sdk/node_modules/`) significa duas instâncias —
    rode `npm dedupe`, e se persistir, remova a declaração do seu `package.json`.

## Por que não `DynamicIcon` do lucide

O `lucide-react` traz um `DynamicIcon` que parece resolver o mesmo problema. Ele
tem um custo que inviabiliza o uso:

!!! danger "`DynamicIcon` gera ~2000 fronteiras de chunk"
    O mapa que ele usa (`dynamicIconImports`) é um módulo de **116 KB** com uma
    chamada `import()` para **cada** um dos 2024 ícones. Qualquer bundler que veja
    esse módulo é obrigado a criar um chunk por ícone: no build de produção isso
    vira ~2024 arquivos minúsculos, e em desenvolvimento vira uma enxurrada de
    requisições no navegador.

    Além disso ele resolve o ícone **depois** da renderização (num `useEffect`), então
    o primeiro quadro nunca tem ícone e o layout pula. E um nome inexistente faz
    `throw`, derrubando a árvore React — justamente no caso em que o nome vem de
    fora.

O `<Icon>` do SDK troca isso por **um chunk por faixa de 40 ícones**. Renderizar
130 ícones diferentes pede algumas requisições, não 130:

```console
GET .../icons/generated/shard-09.js   200
GET .../icons/generated/shard-21.js   200
GET .../icons/generated/shard-36.js   200
… uma por faixa tocada, no máximo 45
```

O maior shard pesa **4,78 KB brotli**, a mediana **4,19 KB** e o menor **1,52 KB**.
O runtime do `<Icon>`, sem shard nenhum, custa **~0,1 KB brotli**.

!!! info "Por que faixa e não letra inicial"
    A primeira letra é a pior chave de particionamento possível, porque os nomes do
    lucide são fortemente enviesados: `c` tem 284 slugs e `q` tem 4. Desenhar **um**
    ícone de categoria que começasse com `c` baixava 284 ícones — 19,10 KB brotli
    para um glifo de meio KB, fator de desperdício de ~130x.

    As faixas são contíguas e ordenadas, então o SDK acha o shard dono de um slug com
    uma **busca binária** sobre 45 limites — em vez de embarcar o mapa de 2024
    entradas slug→chunk que faz o `dynamicIconImports` do próprio lucide custar 120 KB
    no chunk principal.

## Catálogo fechado: `registerIcons`

Painel administrativo costuma ter vinte ícones e nenhum a mais. Para esse caso não
precisa de plugin nem de provider — registre uma vez no entrypoint:

```tsx
// src/main.tsx
import { createRoot } from "react-dom/client";
import { registerIcons } from "tempest-react-sdk/icons";
import { House, Save, Settings, Trash2, Users } from "lucide-react";
import { App } from "@/App";

registerIcons({
    house: House,
    save: Save,
    settings: Settings,
    "trash-2": Trash2,
    users: Users,
});

createRoot(document.getElementById("root")!).render(<App />);
```

Pronto: qualquer `<Icon name="save" />` na árvore resolve **no primeiro frame, sem
requisição**. Os imports são estáticos, então o bundler mantém exatamente esses
cinco ícones e joga o resto fora.

!!! tip "Serve também para arte própria"
    A chave não precisa ser um slug do lucide. `registerIcons({ "minha-marca": Marca })`
    faz `<Icon name="minha-marca" />` funcionar — mesmo call site, mesmo default de
    `size`, sem `if` no componente.

!!! info "Slug depreciado entra pelo nome canônico"
    `registerIcons({ "alert-circle": AlertCircle })` grava sob `circle-alert`, então
    as duas grafias resolvem. É o mesmo mapa de alias que o `<Icon>` usa.

`registerIcons` é acumulativo e idempotente: chame de quantos módulos quiser, e
registrar o mesmo par duas vezes não custa render. Registrar **depois** de a árvore
já ter renderizado também funciona — todo `<Icon>` montado no fallback é avisado e
re-renderiza.

### Já tem o componente na mão? Passe direto

```tsx
import { Icon } from "tempest-react-sdk/icons";
import { Wrench } from "lucide-react";

<Icon icon={Wrench} />
```

Sem lookup, sem registro, sem shard. Existe para a tela que mistura ícone literal
com ícone vindo de dados poder usar **um** componente nos dois casos — e assim os
defaults de `size`/`strokeWidth` do `IconProvider` valerem para os dois. `name` e
`icon` são mutuamente exclusivos: passar os dois é erro de tipo.

### Quando ainda vale o `IconProvider`

Depois do `registerIcons`, sobra para o provider o que é **escopo de árvore**:

- default de `size` / `strokeWidth` para uma subárvore;
- um registro que precisa **ganhar** do global só ali (tema alternativo, preview de
  ícone dentro de um modal).

A precedência é: registro do provider → registro global (`registerIcons` e shards já
baixados) → busca do shard.

## Custo zero de requisição para os slugs que você escreveu

Um `<Icon name="save" />` escrito no código não precisa de shard nenhum: o slug é
conhecido em tempo de build. O plugin `tempestIcons()` varre o seu source, acha
esses nomes e gera um registro com imports estáticos comuns.

### 1. Ligue o plugin

Se você usa `createViteConfig`, **já está ligado** — o plugin entra por default:

```ts
// vite.config.ts
import { createViteConfig } from "tempest-react-sdk/vite";

export default createViteConfig();
```

Config manual? Adicione o plugin:

```ts
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { tempestIcons } from "tempest-react-sdk/vite";

export default defineConfig({
    plugins: [react(), tempestIcons()],
});
```

### 2. Passe o registro pro provider

```tsx
// src/main.tsx
import { createRoot } from "react-dom/client";
import { IconProvider } from "tempest-react-sdk/icons";
import { staticIcons } from "tempest-react-sdk/icons/virtual";
import { App } from "@/App";

createRoot(document.getElementById("root")!).render(
    <IconProvider registry={staticIcons} size={18}>
        <App />
    </IconProvider>,
);
```

!!! info "Não precisa declarar tipo nenhum"
    `tempest-react-sdk/icons/virtual` é um módulo **de verdade** do pacote: os tipos
    vêm pelo `exports`, e ele resolve mesmo **sem** o plugin — para um registro
    vazio. É o que faz o mesmo arquivo carregar no vitest sem o plugin, no `tsx`, num
    Storybook com builder próprio ou em qualquer script Node que importe a árvore da
    app. Antes disso, `import { staticIcons } from "virtual:tempest-icons"` fora de um
    build Vite com o plugin não deixava **um ícone** faltando: derrubava o módulo
    inteiro.

!!! warning "A grafia antiga continua funcionando"
    `import { staticIcons } from "virtual:tempest-icons"` segue resolvendo quando o
    plugin está instalado, e o `/// <reference types="tempest-react-sdk/icons/virtual" />`
    que você já tem no `vite-env.d.ts` continua válido — pode apagar, não precisa.
    Só não use essa grafia em código novo: ela é a que não resolve fora do Vite.

Feito isso, todo slug literal do seu código resolve **no primeiro frame, sem
requisição extra**. Slug de runtime continua caindo no shard — o comportamento não
muda, só fica mais barato onde dá.

!!! tip "O provider também guarda os defaults"
    `size` e `strokeWidth` no `IconProvider` valem pra toda a subárvore, então você
    para de repetir `size={18}` em cada chamada. Prop explícita no `<Icon>` sempre
    ganha do default.

## `icon_code` do banco chega sujo — e renderiza

Todo backend que grava ícone grava sujo. `snake_case` de formulário antigo, espaço
e maiúscula de valor digitado à mão, e slug que o lucide depreciou desde então. O
`<Icon>` limpa antes de procurar, então os três casos renderizam:

```tsx
<Icon name="shopping_cart" />   {/* → shopping-cart */}
<Icon name="  Save " />         {/* → save */}
<Icon name="alert-circle" />    {/* → circle-alert (alias) */}
<Icon name=" Alert_Circle " />  {/* → circle-alert (os três de uma vez) */}
```

A normalização é: `trim` → minúsculas → `_` vira `-` → `resolveIconAlias`. Nessa
ordem, e é a mesma função que você pode chamar sozinho:

```tsx
import { normalizeIconName } from "tempest-react-sdk/icons";

normalizeIconName(" Alert_Circle ");  // "circle-alert"
```

Exporta sozinho porque o **formulário precisa dela antes de submeter**, não só para
renderizar: você grava o slug canônico no banco em vez de guardar a sujeira e
limpar em toda leitura.

!!! warning "Normalizar não é validar"
    `normalizeIconName` devolve a grafia canônica, não a garantia de que o ícone
    existe: `normalizeIconName("Not_An_Icon")` é `"not-an-icon"`. Quem decide o que
    fazer com um nome desconhecido é você — `isIconName` responde, e o `<Icon>`
    renderiza o `fallback`.

!!! tip "Lookup estrito quando você quer ver o erro"
    `normalize={false}` desliga a limpeza para aquele call site. Serve para quando
    uma grafia inesperada **deve** aparecer como ícone faltando em vez de ser
    consertada em silêncio.

O aviso de dev cita o nome **como foi escrito**, não o normalizado: quem lê o
console é quem digitou, e `name="CircleAlert"` é bem mais útil ali do que o
`"circlealert"` que aquilo normaliza.

## Nome que não existe

Nunca lança. Sem `fallback`, não renderiza nada:

```tsx
<Icon name="nao-existe" />
```

Com `fallback`, renderiza o que você mandar — inclusive um placeholder do mesmo
tamanho, pra o layout não pular enquanto o shard está no ar:

```tsx
<Icon
    name={row.iconSlug}
    size={20}
    fallback={<span style={{ width: 20, height: 20 }} />}
/>
```

Em **desenvolvimento** sai um `console.warn` uma vez por slug, e só quando o nome é
realmente inexistente — nunca enquanto um ícone válido está carregando.

!!! warning "Valide na borda, não no componente"
    Se o nome vem de fora, decida o fallback **uma vez**, onde o dado entra:

    ```tsx
    import { isIconName } from "tempest-react-sdk/icons";

    const slug = isIconName(row.icon) ? row.icon : "circle-help";
    ```

    `isIconName` importa a lista completa de slugs (~7 KB brotli). O `<Icon>` **não**
    importa essa lista — só pague por ela onde precisa validar ou listar.

## Slug antigo continua funcionando

O lucide renomeou vários ícones (`alert-circle` → `circle-alert`,
`alert-triangle` → `triangle-alert`) e mantém os 257 nomes antigos como alias. O
SDK carrega esse mapa, então um slug gravado no banco há dois anos ainda renderiza:

```tsx
<Icon name="alert-circle" />  {/* renderiza circle-alert */}
```

O alias resolve pro nome canônico **antes** de escolher o shard, então
`alert-circle` puxa o shard `c`, não o `a`.

## Quando o shard não chega

Slug de runtime baixa um chunk, chunk tem hash no nome, e o hash muda a cada
deploy. Isso monta um cenário rotineiro em SPA de aba longa:

1. o usuário abre o app, e o shard daquela faixa ainda não foi baixado;
2. sai um deploy, e os assets antigos somem do CDN;
3. o usuário navega pra uma tela que precisa daquele ícone;
4. o `import()` rejeita — 404.

O SDK trata isso em três partes:

**Retry curto.** Duas tentativas extras, 100 ms e 400 ms, porque a falha que
retry conserta é a transitória: conexão instável, edge de CDN atrasado. Se uma
delas passar, o ícone aparece e ninguém fica sabendo.

**Falha de carga não é nome errado.** `iconStatus` ganhou um quarto estado:

```tsx
iconStatus("save");  // "ready" | "loading" | "missing" | "error"
```

`"missing"` só sai quando isso é de fato sabível — o shard **chegou** e o slug não
estava nele. Shard que falhou responde `"error"`, e por isso o `<Icon>` para de
avisar "no such lucide icon" sobre um nome perfeitamente válido. O estado também
não é permanente: um render posterior tenta de novo, respeitando um cooldown de
10 s para um chunk realmente morto não virar laço de requisição.

**Sinal para o observability.** Retry não conserta 404 de deploy; o que conserta é
o app saber:

```tsx
import { subscribeToIconErrors } from "tempest-react-sdk/icons";

subscribeToIconErrors(({ shard, slug, attempts, error }) => {
    Sentry.captureException(error, { tags: { iconShard: shard, slug, attempts } });
    promptReloadForStaleChunks();
});
```

Chame uma vez no entrypoint. O callback roda uma vez por shard que desistiu, com
o shard, o slug que pediu, quantas tentativas houve e a última rejeição.

!!! tip "Sem ninguém assinando, dev avisa no console"
    Falha silenciosa foi justamente o problema — então em build de desenvolvimento
    sai um `console.warn` por shard, dizendo que a causa mais comum é deploy que
    rotacionou nome de chunk com a aba aberta. Assinou? O console fica quieto, e o
    relato é seu.

## Aquecendo os shards

Antes de abrir um menu grande ou um seletor de ícone, dá pra carregar os shards
enquanto o usuário ainda está indo com o mouse:

```tsx
import { preloadIcons } from "tempest-react-sdk/icons";

<button onMouseEnter={() => void preloadIcons(MENU.map((i) => i.name))}>Menu</button>;
```

Depois disso os ícones aparecem no primeiro frame, sem passar pelo `fallback`.

## Sem Vite? Use o CLI

O plugin é a forma mais confortável, mas não é a única. O CLI gera o mesmo
registro como um arquivo de verdade, que você versiona:

```bash
npx tempest gen icons --out src/icons.generated.ts
```

```console
→ scanning src

✓ 37 icon(s) from 42 file(s) → src/icons.generated.ts

Wire it up:
  import { IconProvider } from "tempest-react-sdk/icons";
  import { icons } from "@/icons.generated";
  <IconProvider registry={icons}>…</IconProvider>
```

Re-rode depois de adicionar ícones novos. Um slug que o scan não vê (nome montado
por concatenação, por exemplo) continua funcionando pelo shard — só não ganha o
caminho estático.

## Seletor de ícone pronto

Todo painel que deixa alguém escolher um ícone reescrevia a mesma tela: filtrar a
lista, cortar em N sugestões, montar o `<datalist>` e barrar o submit quando o
slug não existe. Esse último passo é o que importa — sem ele o valor inválido
chega no banco e só aparece como ícone faltando em toda tela que rende aquele
registro.

```tsx
import { useState } from "react";
import { IconPicker } from "tempest-react-sdk/icons";

export function CategoryForm({ onSave }: { onSave: (icon: string) => void }) {
    const [icon, setIcon] = useState("");

    return (
        <form
            onSubmit={(event) => {
                event.preventDefault();
                onSave(icon);
            }}
        >
            <label htmlFor="icon">Ícone</label>
            <IconPicker id="icon" value={icon} onChange={setIcon} required />
            <button type="submit">Salvar</button>
        </form>
    );
}
```

O que você ganha:

- **autocomplete nativo** sobre os 2024 slugs, via `<datalist>` — teclado, leitor de
  tela e o comportamento mobile vêm da plataforma;
- **preview** do ícone escolhido ao lado do campo;
- **validação no form nativo**: o input carrega `setCustomValidity`, então um
  `<form>` comum se recusa a submeter e o browser aponta pro campo;
- **entrada legada aceita, slug canônico emitido** — digitou `Shopping_Cart`, o
  `onChange` recebe `shopping-cart`; digitou `alert-circle`, recebe `circle-alert`.

!!! tip "Sugestões são cortadas por default"
    `limit` é **40**. Montar 2024 `<option>` a cada tecla travava o datalist — é o
    motivo da prop existir, em vez de um default "mostra tudo".

!!! warning "Usa react-hook-form ou zod? A regra é exportada"
    Não duplique a validação — é assim que as duas divergem:

    ```tsx
    import { validateIconName } from "tempest-react-sdk/icons";

    // react-hook-form
    register("icon", { validate: (value) => validateIconName(value) ?? true });

    // zod
    z.string().refine((value) => !validateIconName(value), {
        message: "Ícone inexistente",
    });
    ```

    Vazio **passa** em `validateIconName`: "não escolheu ícone" é pergunta do
    `required`, não erro de grafia — juntar as duas tornaria o campo impossível de
    limpar.

!!! info "Custa a lista inteira, e só aqui"
    O `IconPicker` importa `iconNames` (~7 KB brotli), porque um seletor precisa da
    lista. O `<Icon>` **não** — veja [O que cada import
    custa](#o-que-cada-import-custa). E o estilo vem do `styles.css` do SDK, como
    todo componente.

### Prefere montar o seu?

A lista é pública e ordenada:

```tsx
import { useMemo, useState } from "react";
import { Icon, iconNames } from "tempest-react-sdk/icons";

export function OwnPicker({ onPick }: { onPick: (slug: string) => void }) {
    const [query, setQuery] = useState("");
    const matches = useMemo(
        () => iconNames.filter((name) => name.includes(query.trim().toLowerCase())),
        [query],
    );

    return (
        <div>
            <input value={query} onChange={(e) => setQuery(e.target.value)} />
            <p>
                {matches.length} de {iconNames.length}
            </p>
            {matches.slice(0, 120).map((name) => (
                <button key={name} onClick={() => onPick(name)} title={name}>
                    <Icon name={name} size={20} />
                </button>
            ))}
        </div>
    );
}
```

Veja rodando na [gallery](./gallery.md), seção **Ícones por slug**.

## Lista completa, para consultar fora do app

O backend que grava o slug — o seed de categorias, a tabela do admin, a
validação do Pydantic — não consegue importar `iconNames`. Para esses casos a
lista sai publicada junto com esta documentação, gerada pelo mesmo script que
gera as tabelas do SDK, então ela nunca fica atrasada em relação ao que o
`<Icon>` aceita:

| Arquivo                                     | O que tem                                                    |
| ------------------------------------------- | ------------------------------------------------------------ |
| [`icon-slugs.txt`](assets/icon-slugs.txt)   | Os 1767 slugs **canônicos**, um por linha                     |
| [`icon-slugs.csv`](assets/icon-slugs.csv)   | Os 2024 slugs com `status` (`canonical`/`deprecated`) e o canônico correspondente |

Use o `.txt` para o que **valida escrita** — é a lista do que pode ser gravado
hoje. Use o `.csv` para o que **lê dado antigo**: a coluna `canonical` diz para
onde cada nome depreciado resolve, que é a mesma resolução que o `<Icon>` faz em
runtime.

!!! tip "Validando no backend Python"
    ```python
    from pathlib import Path

    ICON_SLUGS: frozenset[str] = frozenset(
        Path("icon-slugs.txt").read_text().split()
    )

    if category.icon_code not in ICON_SLUGS:
        raise ValueError(f"{category.icon_code!r} is not a lucide icon slug")
    ```

!!! warning "Vocabulário: é lucide, não Material Symbols"
    Se o seu seed veio de um app Android/Flutter, os códigos são Material Symbols
    em `snake_case` (`format_paint`, `electrical_services`) e **nenhum** deles é
    um slug lucide. Pior: um punhado colide por acidente (`settings`, `code`,
    `key`, `lock`, `shield`, `tv`) e renderiza certo em ~10% das linhas, o que
    faz o problema parecer "sumiram alguns ícones". Converta o vocabulário antes
    de gravar — ou use a ponte da próxima seção, se não puder mexer no seed.

## Backend que grava Material Symbols

A saída mais limpa é o backend passar a gravar slug lucide direto: um vocabulário
só, ponta a ponta, e nada para traduzir. Quando isso não é possível — o seed é
antigo, tem um app Flutter lendo o mesmo banco, ou você herdou os dados — o SDK
oferece a ponte:

```tsx
import { Icon, fromMaterialSymbol } from "tempest-react-sdk/icons";

export function CategoryTile({ category }: { category: Category }) {
    return (
        <li>
            <Icon name={fromMaterialSymbol(category.icon_code)} size={20} />
            <span>{category.name}</span>
        </li>
    );
}
```

`fromMaterialSymbol` **nunca** devolve `undefined`. Um código que a tabela não
conhece cai num glifo neutro (`circle-question-mark`), porque uma categoria criada
no admin com um código novo ainda tem que desenhar alguma coisa em vez de abrir
buraco no grid. Passe o segundo argumento quando o seu domínio tiver um padrão
melhor:

```tsx
<Icon name={fromMaterialSymbol(category.icon_code, "folder")} size={20} />
```

### A tabela é uma semente, não o vocabulário inteiro

Material Symbols publica ~6100 nomes e quase nenhum vai aparecer num `icon_code`
nosso. `materialToLucide` tem hoje **261 pares** — o lote de ofícios com que
começou, mais a **cabeça do ranking de popularidade publicado pelo próprio Google**
(`fonts.google.com/metadata/icons`), que é uso medido e não chute sobre quais nomes
um seed vai conter. E **cresce sob demanda**, com cada par escrito à mão — mapa
gerado por heurística de nome erra feio, a começar por `build`, que em Material
Symbols é uma chave inglesa e não tem nada a ver com construção.

!!! info "Quando dois lotes discordaram do mesmo código"
    Seis chaves apareceram nos dois lotes com destinos diferentes. O critério de
    desempate foi **preferir o mapeamento que mantém dois nomes distintos do
    Material Symbols distintos no lucide**:

    | Código | Ficou | Porque |
    | --- | --- | --- |
    | `error` | `circle-alert` | `cancel` já é `circle-x` |
    | `payments` | `banknote` | `account_balance_wallet` já é `wallet` |
    | `receipt_long` | `receipt-text` | `receipt` já é `receipt` |
    | `construction` | `construction` | `engineering` já é `hard-hat` |
    | `today` / `event` | `calendar` / `calendar-days` | separa os nomes genéricos de calendário do datado |

O lado lucide de **todo** par é conferido por teste contra a lista real de slugs,
então par apontando para nome que o lucide não envia — ou que ele já depreciou —
reprova a suíte em vez de chegar no seu grid. O que teste nenhum confere é se o
ícone escolhido é a **metáfora** certa: é por isso que os pares entram à mão.

| Material Symbol                                | lucide                   | Observação                              |
| ---------------------------------------------- | ------------------------ | --------------------------------------- |
| `build`, `handyman`, `hardware`                | `wrench`                 | Aproximação — três para um              |
| `carpenter`                                    | `hammer`                 |                                         |
| `format_paint`                                 | `paint-roller`           |                                         |
| `electrical_services`                          | `plug-zap`               |                                         |
| `plumbing`                                     | `shower-head`            | Aproximação — lucide não tem cano       |
| `roofing`                                      | `house`                  | Aproximação — mesmo glifo de `home`     |
| `construction`                                 | `hard-hat`               |                                         |
| `cleaning_services`                            | `spray-can`              | Aproximação — a atividade, não o objeto |
| `iron`                                         | `shirt`                  | Aproximação — lucide não tem ferro      |
| `local_laundry_service`                        | `washing-machine`        |                                         |
| `dentistry`                                    | `face-slightly-smiling`  | Aproximação — lucide não tem dente      |
| `medical_services`                             | `stethoscope`            |                                         |
| `vaccines`                                     | `syringe`                |                                         |
| `content_cut`                                  | `scissors`               | Barbearia, no vocabulário de seed       |
| `spa`                                          | `flower-2`               |                                         |
| `local_florist`                                | `flower`                 |                                         |
| `yard`                                         | `trees`                  |                                         |
| `grass`                                        | `sprout`                 |                                         |
| `pest_control`                                 | `bug`                    |                                         |
| `pedal_bike`, `two_wheeler`, `delivery_dining` | `bike`                   | Aproximação — três para um              |
| `car_repair`, `directions_car`                 | `car`                    | Aproximação — lucide não tem carro+chave |
| `local_taxi`                                   | `car-taxi-front`         |                                         |
| `local_shipping`                               | `truck`                  |                                         |
| `local_gas_station`                            | `fuel`                   |                                         |
| `group`, `groups`                              | `users`                  | Aproximação — dois para um              |
| `store`, `storefront`                          | `store`                  | Aproximação — dois para um              |
| `home`                                         | `house`                  |                                         |
| `person`                                       | `user`                   |                                         |
| `payments`                                     | `banknote`               |                                         |
| `account_balance`                              | `landmark`               |                                         |
| `savings`                                      | `piggy-bank`             |                                         |
| `receipt_long`                                 | `receipt`                |                                         |
| `dashboard`                                    | `layout-dashboard`       |                                         |
| `bar_chart`, `pie_chart`                       | `chart-column`, `chart-pie` |                                      |
| `description`                                  | `file-text`              |                                         |
| `event`, `today`, `schedule`                   | `calendar`, `calendar-days`, `clock` |                             |
| `location_on`                                  | `map-pin`                |                                         |
| `chat`, `forum`                                | `message-circle`, `messages-square` |                              |
| `campaign`                                     | `megaphone`              |                                         |
| `support_agent`                                | `headset`                |                                         |
| `notifications`                                | `bell`                   |                                         |
| `favorite`                                     | `heart`                  |                                         |
| `visibility`                                   | `eye`                    |                                         |
| `edit`, `delete`                               | `pencil`, `trash-2`      |                                         |
| `help`, `info`, `warning`, `error`             | `circle-question-mark`, `info`, `triangle-alert`, `circle-x` |      |
| `verified`                                     | `badge-check`            |                                         |
| `security`                                     | `shield-check`           |                                         |
| `history`                                      | `rotate-ccw-clock`       |                                         |
| `sync`                                         | `refresh-cw`             |                                         |
| `translate`                                    | `languages`              |                                         |
| `balance`                                      | `scale`                  |                                         |
| `computer`                                     | `monitor`                |                                         |
| `photo_camera`, `videocam`, `music_note`       | `camera`, `video`, `music` |                                       |
| `school`, `work`                               | `graduation-cap`, `briefcase` |                                    |
| `child_care`, `pets`                           | `baby`, `paw-print`      |                                         |
| `restaurant`, `local_cafe`, `local_bar`        | `utensils`, `coffee`, `wine` |                                     |
| `fitness_center`                               | `dumbbell`               |                                         |
| `hotel`, `flight`                              | `bed-double`, `plane`    |                                         |
| `soap`                                         | `soap-dispenser-droplet` |                                         |
| `kitchen`, `chair`, `door_front`               | `refrigerator`, `armchair`, `door-open` |                          |
| `water_drop`, `bolt`, `ac_unit`                | `droplet`, `zap`, `snowflake` |                                    |
| `settings`, `code`, `key`, `lock`, `shield`, `brush`, `tv`, `smartphone`, `mic`, `palette`, `router`, `gavel`, `warehouse`, `search`, `store`, `map`, `mail`, `phone`, `menu`, `check`, `star`, `folder`, `image`, `cloud`, `wifi`, `bluetooth`, `laptop`, `cake`, `info`, `upload`, `download` | (o mesmo nome) | Colidem por acidente |

!!! info "Por que as colisões estão na tabela"
    Esses 31 já renderizam hoje, porque o nome bate nos dois vocabulários. Se
    ficassem de fora, `fromMaterialSymbol` os mandaria para o fallback e a ponte
    seria uma **regressão** justamente para os códigos que funcionavam.

!!! warning "Passe a tabela no `include` do plugin"
    Slug resolvido em runtime puxa o shard da faixa dele. Um catálogo com ~130
    categorias espalha por dezenas de faixas, então o ganho de DX vira dezenas de
    requisições se você não avisar o build:

    ```ts
    import { defineConfig } from "vite";
    import { tempestIcons } from "tempest-react-sdk/vite";
    import { materialToLucide } from "tempest-react-sdk/icons";

    export default defineConfig({
        plugins: [tempestIcons({ include: Object.values(materialToLucide) })],
    });
    ```

!!! tip "Faltou um código?"
    Abra uma issue com os `icon_code` que o seu seed usa. Cada par entra escrito
    à mão e um teste trava a tabela inteira contra a lista real de slugs, então
    uma entrada apontando para ícone inexistente reprova a suíte em vez de
    chegar no seu grid.

## Referência

| Export               | O que faz                                                              |
| -------------------- | ---------------------------------------------------------------------- |
| `Icon`               | Renderiza por slug (`name`) ou por componente (`icon`), + `size`, `strokeWidth`, `fallback` e props de SVG |
| `registerIcons`      | Registra slug → componente global, sem provider e sem plugin            |
| `staticIcons`        | O registro que o plugin gera, em `tempest-react-sdk/icons/virtual`       |
| `IconProvider`       | Registro estático + defaults de `size`/`strokeWidth`                    |
| `createIconRegistry` | Monta um registro a partir de componentes lucide importados             |
| `useIcon`            | Resolve um slug pro componente (o que o `Icon` usa por dentro)          |
| `preloadIcons`       | Aquece os shards de uma lista de slugs                                  |
| `iconStatus`         | `"ready"` / `"loading"` / `"missing"` / `"error"` para um slug           |
| `subscribeToIconErrors` | Assina falha de carga de shard (Sentry, reload de chunk stale)        |
| `IconLoadError`      | O payload da falha: `shard`, `slug`, `attempts`, `error`                 |
| `peekIcon`           | Lê do cache sem disparar carregamento                                   |
| `loadIcon`           | Carrega o shard de um slug                                              |
| `resolveIconAlias`   | Slug depreciado → slug canônico                                        |
| `isIconName`         | Type guard contra a lista real (importa a lista)                        |
| `normalizeIconName`  | `icon_code` sujo → slug canônico (trim, lower, `_`→`-`, alias)          |
| `IconPicker`         | Campo de ícone: autocomplete + preview + validação nativa               |
| `validateIconName`   | A regra de validação do picker, para react-hook-form/zod                |
| `DEFAULT_ICON_PICKER_MESSAGE` | A mensagem default de slug inexistente                         |
| `fromMaterialSymbol` | Código Material Symbols → slug lucide, sempre devolvendo um             |
| `materialToLucide`   | A tabela de pares, para passar no `include` do plugin                   |
| `MATERIAL_SYMBOL_FALLBACK` | O glifo neutro que um código desconhecido usa                    |
| `iconNames`          | Os 2024 slugs, ordenados (~7 KB brotli)                                 |
| `iconAliases`        | Os 257 pares alias → canônico                                          |
| `IconName`           | União de tipo com todos os slugs (só tipo, custo zero)                  |

### O que cada import custa

Medido com `esbuild --bundle --minify` + brotli, `react` e `lucide-react` externos —
ou seja, o que o **SDK** adiciona ao seu bundle:

| Você importa           | Brotli   | Puxa a lista de 2024 slugs? |
| ---------------------- | -------- | --------------------------- |
| `{ Icon }`             | ~2,5 KB  | **Não**                     |
| `{ resolveIconAlias }` | 2,06 KB  | Não                         |
| `{ normalizeIconName }`| 2,09 KB  | Não                         |
| `{ isIconName }`       | 7,20 KB  | Sim (é o que ela consulta)  |
| `{ iconNames }`        | 7,17 KB  | Sim                         |

!!! info "Não existe subpath `/icons/catalog` — e não precisa"
    A separação entre runtime e catálogo **já acontece**, por tree-shaking: nenhum
    módulo do caminho do `<Icon>` importa a lista, então o bundler simplesmente não
    a inclui. Um subpath separado moveria o mesmo código de lugar, quebraria o
    import de quem usa `iconNames` hoje e economizaria **zero byte**.

    O que ficou no lugar disso é um **guard**: o `postbuild`
    (`scripts/check-dist-guards.mjs`) percorre o grafo de imports estáticos do
    `dist` a partir do `Icon.js` e falha o build se a lista aparecer ali. Com
    `preserveModules`, os imports estáticos de um módulo **são** as dependências
    reais dele, então isso é uma resposta exata, não uma estimativa. Um
    `import { iconNames }` de conveniência dentro do `use-icon` custaria ~6 KB a
    todo app que renderiza um ícone, e nada no source pareceria errado.

    O que **é** eager no caminho do `<Icon>` é a tabela de 257 aliases (~2 KB): ela
    tem que resolver **antes** de escolher o shard, então não dá pra adiar sem uma
    segunda ida à rede para todo slug antigo. 2 KB é o preço de um `icon_code`
    gravado há dois anos continuar renderizando.

### Custos medidos

| O que                                            | Brotli    |
| ------------------------------------------------ | --------- |
| Runtime do `<Icon>`, antes de qualquer shard     | ~0,1 KB   |
| Menor shard (7 ícones), sob demanda              | 1,52 KB   |
| Shard mediano (40 ícones), sob demanda           | 4,19 KB   |
| Maior shard (40 ícones), sob demanda             | 4,78 KB   |
| Maior shard **antes** do rebalanceamento (`s`)   | 19,10 KB  |
| `{ iconNames }` — a lista dos 2024 slugs         | 6,1 KB    |
| Runtime + os 45 shards juntos (teto absoluto)    | 130,0 KB  |

!!! info "Como isso foi medido"
    Os shards e a lista saem do `size-limit` **com o `lucide-react` dentro da
    medição** — é o que a rede realmente transfere, já que um shard só
    re-exporta os ícones. Medir o arquivo emitido sozinho daria ~2 KB por shard
    e seria uma mentira confortável. O runtime é o brotli dos quatro módulos
    que carregam antes do primeiro ícone (`Icon`, `shard-cache`, `use-icon`,
    `icon-context`), que não puxam lucide nenhum.

    Reproduza com `npm run build` seguido de `npx size-limit`, cujas entradas de
    ícone estão em `.size-limit.json`.

## Recap

- `<Icon name="save" />` resolve qualquer um dos **2024 slugs** do lucide, sem
  configuração.
- Slug **literal** vira import estático via `tempestIcons()` (ligado por default no
  `createViteConfig`) → **zero requisição extra**.
- Catálogo fechado? `registerIcons({ save: Save })` no entrypoint dá o mesmo caminho
  estático **sem plugin e sem provider**. Já tem o componente? `<Icon icon={Save} />`.
- `tempest-react-sdk/icons/virtual` é módulo real: resolve **sem** o plugin (registro
  vazio), então vitest, `tsx` e Storybook carregam o mesmo arquivo.
- Slug de **runtime** carrega **um shard da faixa dele** — faixas de 40 ícones
  achadas por busca binária, no máximo 4,78 KB brotli por requisição.
- Nome inexistente renderiza `fallback` (nada, por default) e **nunca lança**;
  `console.warn` só em dev.
- Shard que não chega ganha **2 retries curtos**, responde `iconStatus` `"error"`
  (não `"missing"`) e é reportado por `subscribeToIconErrors` — deploy que rotaciona
  chunk deixou de virar fallback permanente e silencioso.
- Os 257 **aliases** antigos do lucide continuam resolvendo.
- `icon_code` do banco renderiza sujo: `shopping_cart`, `" Save"` e alias antigo são
  normalizados antes do lookup. `normalize={false}` para lookup estrito, e
  `normalizeIconName` sozinho para validar no formulário.
- `<IconPicker value onChange />` é o campo pronto: autocomplete nativo, preview e
  `setCustomValidity` para o form recusar slug inexistente. `validateIconName` para
  react-hook-form/zod.
- `iconNames` fica **fora** do custo do `<Icon>` — importe só se for listar ou
  validar.
- **Não declare `lucide-react` no seu app**: ele já vem com o SDK, e uma segunda
  cópia duplica bytes e pode não ter os exports que as tabelas de slug geradas
  referenciam.
- Veja também: [Vite & alias](./vite-config.md) · [CLI tempest](./cli.md) ·
  [Componentes](./components.md)

---

# imaging.md

# Imaging (processamento de imagem no navegador)

Foto tirada no celular, tratada **no aparelho**: redimensiona, corta, gira,
troca de formato e cabe num orçamento de bytes — sem servidor, sem
dependência, sem a imagem do usuário viajar antes da hora.

É o que um PWA de campo precisa. Pode estar offline, a conexão pode ser
cara, e a foto pode ter GPS embutido que ninguém pediu para enviar.

```tsx
import { compressToTarget } from "tempest-react-sdk/imaging";

// `file` é o que um <input type="file"> entrega: event.target.files[0]
const upload = await compressToTarget(file, {
  maxBytes: 1_000_000,
  width: 1600,
  type: "image/webp",
});

console.log(upload.bytes, upload.quality, upload.withinBudget);
```

```text
192512 0.86 true
```

## O que ele resolve por você

### Foto de celular vem deitada

Retrato é gravado como paisagem mais uma etiqueta de rotação. Quem decodifica
sem honrar a etiqueta mostra **toda** foto vertical de lado — o bug mais
reportado em fluxo de upload.

```tsx
import { decodeImage } from "tempest-react-sdk/imaging";

const { width, height } = await decodeImage(file); // já na orientação certa
```

Medido no Chromium: JPEG 120x60 com `Orientation=6` decodifica como 60x120.

### Formato não suportado falha em silêncio

```tsx
import { bestSupportedType, supportsImageType } from "tempest-react-sdk/imaging";

const type = await bestSupportedType(["image/avif", "image/webp", "image/jpeg"]);
```

!!! danger "Pedir AVIF onde não há encoder devolve PNG, sem erro"
    Medido em Chromium **e** Firefox: `convertToBlob({ type: "image/avif" })`
    não lança — devolve `image/png`. Um app que confiou no pedido sobe
    megabytes onde planejou centenas de kilobytes.

    Por isso todo retorno traz `type` — o formato **produzido**, não o
    pedido — e `supportsImageType` responde antes.

### Reencodar apaga o EXIF

Redimensionar passa pelo canvas, e o canvas não carrega metadado. GPS,
número de série da câmera e horário **não sobrevivem**. Para app que lida
com foto de usuário isso costuma ser exatamente o que se quer — e vale saber
que acontece.

## Medições reais

Foto sintética de 3000x2000 (731 KB), Chromium:

| Operação | Resultado |
| --- | --- |
| Redimensionar para 1200 px, JPEG q0.85 | 124 KB em 66 ms |
| Mesma coisa em WebP q0.85 | 75 KB (40% menor) |
| `compressToTarget` para 200 KB | 192 KB, q0.86, 7 encodes, 313 ms |

!!! info "O que foi removido depois de medir"
    A receita clássica para reduzir muito num canvas é **dividir por dois
    repetidamente**, porque um `drawImage` único supostamente aliasa. Isso
    chegou a ser implementado aqui, e aí foi medido: xadrez de 512 px
    reduzido para 32 px deu resultado **idêntico** (desvio padrão 0,0 nos
    dois) em Chromium e Firefox, enquanto o caminho em passos custou
    **39,19 ms contra 0,13 ms** numa foto 4000x3000 — 300 vezes mais, além
    de três canvas intermediários num aparelho que talvez não tenha memória.

    Motor moderno honra `imageSmoothingQuality = "high"`, que é o que o
    módulo liga. O código foi apagado em vez de mantido "por garantia":
    benefício não mensurável a 300x o custo não é garantia, é peso morto.

## Redimensionar

```tsx
import { resizeImage } from "tempest-react-sdk/imaging";

const thumb = await resizeImage(file, { width: 320, height: 320, fit: "cover" });
```

| `fit` | O que faz |
| --- | --- |
| `contain` (padrão) | Cabe dentro da caixa; resultado pode ser menor num lado |
| `cover` | Preenche a caixa; sobra é cortada, centralizada |
| `fill` | Estica para a caixa, mudando a proporção |
| `pad` | Como `contain`, mas completa a caixa com `background` |

Nunca aumenta por padrão (`withoutEnlargement`): ampliar não cria detalhe e
multiplica bytes.

!!! tip "JPEG não tem alpha"
    Encodar PNG transparente como JPEG pinta os pixels transparentes de
    preto. O módulo preenche de branco antes — passe `background` para outra
    cor.

## Cortar, girar, espelhar

```tsx
import { cropImage, flipImage, rotateImage } from "tempest-react-sdk/imaging";

const badge = await cropImage(file, { x: 120, y: 80, width: 400, height: 400 });
const upright = await rotateImage(file, 90);
const selfie = await flipImage(capture, { horizontal: true });
```

O retângulo é limitado à imagem, então corte arrastado além da borda produz
resultado menor em vez de borda transparente. `rotateImage` aceita só
múltiplos de 90 — ângulo livre exige decidir o que fazer com os cantos, e
isso é design do seu app, não default de utilitário.

## Várias miniaturas de uma decodificação

```tsx
import { createThumbnails } from "tempest-react-sdk/imaging";

const [thumb, card] = await createThumbnails(file, [
  { name: "thumb", size: 96 },
  { name: "card", size: 480 },
]);
```

Três chamadas separadas de `resizeImage` decodificariam a mesma foto três
vezes — e numa imagem de 12 megapixels a decodificação é o custo, não a
escala. `size` é a **maior aresta**, então retrato e paisagem cabem na mesma
célula de grid sem conta separada.

## No React

```tsx
import { useImagePreview, useImageProcessing } from "tempest-react-sdk/imaging";

function PhotoUpload() {
  const [file, setFile] = useState<File | null>(null);
  const { url } = useImagePreview(file);
  const { compress, isWorking } = useImageProcessing();

  async function send() {
    if (file === null) return;
    const ready = await compress(file, { maxBytes: 1_000_000, width: 1600 });
    await fetch("/api/photos", { method: "POST", body: ready.blob });
  }

  return (
    <>
      {url !== null && <img src={url} alt="" />}
      <button disabled={isWorking || file === null} onClick={send}>Enviar</button>
    </>
  );
}
```

`useImagePreview` revoga o object URL quando a fonte muda ou o componente
desmonta — sem isso o blob inteiro fica na memória pelo resto da vida da
página. `useImageProcessing` não escreve estado depois do unmount, o caso de
uma foto grande que termina depois do usuário sair da tela.

## Fora da main thread

Todas as funções usam `OffscreenCanvas` quando existe, então rodam dentro de
um worker sem alteração:

```ts
// worker.ts
import { compressToTarget } from "tempest-react-sdk/imaging";

self.onmessage = async (event: MessageEvent<File>) => {
  const result = await compressToTarget(event.data, { maxBytes: 1_000_000 });
  self.postMessage(result.blob);
};
```

Vale a pena: redimensionar foto de 12 megapixels na main thread congela a UI
por dezenas de milissegundos por imagem.

## API

| Símbolo | O que é |
| --- | --- |
| `resizeImage(source, options?)` | Redimensiona e reencoda |
| `cropImage(source, rect, options?)` | Corta em pixels da origem |
| `rotateImage(source, degrees, options?)` | Gira em múltiplos de 90 |
| `flipImage(source, axes, options?)` | Espelha |
| `compressToTarget(source, options)` | Busca binária de qualidade até caber |
| `createThumbnails(source, specs, options?)` | Vários tamanhos, uma decodificação |
| `decodeImage(source)` / `readImageInfo(blob)` | Pixels orientados / dimensões e tamanho |
| `encodeImage(surface, options?)` | Canvas para bytes |
| `supportsImageType(type)` / `bestSupportedType(list)` | O que este navegador encoda mesmo |
| `createSurface` / `getContext` / `drawScaled` | Primitivas de canvas |
| `useImagePreview(blob)` / `useImageProcessing()` | Hooks |

Erros: `ImagingError` na raiz, com `ImageDecodeError`, `ImageEncodeError`,
`UnsupportedImageTypeError` e `ImagingUnavailableError`.

Os defaults de cada opção também saem exportados, para uma tela de ajustes
exibir o valor que está prestes a sobrescrever em vez de repeti-lo:
`DEFAULT_QUALITY` (0.85), `DEFAULT_TYPE` (`image/jpeg`), `DEFAULT_BACKGROUND`
(`#ffffff`, o fundo que substitui a transparência ao ir para JPEG) e, na busca do
`compressToTarget`, `DEFAULT_MIN_QUALITY` (0.4), `DEFAULT_MAX_QUALITY` (0.92) e
`DEFAULT_COMPRESS_STEPS` (6 iterações).

## Recapitulando

- Decodifique com `decodeImage` — orientação de celular já resolvida.
- Cheque o formato com `supportsImageType`; confie no `type` do retorno.
- `compressToTarget` para orçamento de bytes; `withoutEnlargement` fica ligado.
- Reencodar apaga EXIF — é a etapa de privacidade, além da de banda.
- Rode num worker: `OffscreenCanvas` é usado sozinho quando existe.

---

# index.md

# tempest-react-sdk

Blocos de construção React/TypeScript compartilhados pelos frontends da Tempest:
uma **fundação de aplicação** (Vite + alias `@`, roteamento declarativo, estado
com Zustand, cache com TanStack Query, providers), componentes de UI, hooks,
cliente HTTP, store de auth, formulários (zod), transportes em tempo real
(SSE / WebSocket / Web Push / Service Worker), tema, i18n, telemetria, feature
flags, storage offline, error boundary e um conjunto curado de utilitários.

A meta é começar todo novo frontend React com a mesma fundação opinativa já
montada — sem reconfigurar Vite, sem reescrever o store de auth, sem reinventar
o loop de reconexão do SSE. Inclui a CLI **`create-tempest-app`** que gera um
projeto inteiro já cabeado.

> :material-translate: **Idiomas / Languages** — esta documentação é bilíngue.
> Use o seletor de idioma no topo da página para alternar entre
> **Português (BR)** e **English (US)**.

## Comece em 1 minuto

Gere um app novo já fiado com o SDK (a CLI vem dentro do pacote — crie a pasta e
scaffolde dentro dela com `.`):

```bash
mkdir my-app
cd my-app
npx -p tempest-react-sdk create-tempest-app .
npm install
cp .env.example .env
npm run dev            # http://127.0.0.1:5173
```

O `.` é o destino: **diretório atual**. Ele preserva o que já existe na pasta
(`git init`, `README.md`) e tira o nome do projeto do nome do diretório —
por isso é o modo recomendado. `npm create tempest-app` **não** existe: a CLI é o
`bin` do SDK, então o `-p tempest-react-sdk` é o que diz ao `npx` de onde buscá-la.
Os dois modos e cada pedaço do comando estão explicados em [Scaffold](scaffold.md).

Novo por aqui? Siga o **[Tutorial — Guia do Usuário](tutorial/index.md)**: do
scaffold ao app completo, um conceito por página.

Já sabe usar o SDK e quer saber **como organizar o app**? A aba
**[Design de Software](design/index.md)** ensina o desenho: camadas, estrutura de
pastas, onde mora cada estado, tipagem forte, limites objetivos (`.tsx` ≤ 150
linhas) e o checklist de revisão.

## Instalação manual

Em um projeto Vite + React + TS existente:

```bash
npm install tempest-react-sdk
```

Importe o CSS uma vez no entrypoint do app:

```ts
import "tempest-react-sdk/styles.css";
```

**`react`**, **`react-dom`** e **`react-router`** (`^7 || ^8`) são peer
dependencies — os três carregam contexto React, e uma segunda cópia quebra em
runtime. Todo o resto — `zustand`, `@tanstack/react-query`, `zod`,
`react-hook-form`, `dexie`, `lucide-react` — é **dependência direta**, instalada
automaticamente com o SDK e externalizada no bundle (seu bundler faz tree-shake
do que não usar). Detalhes em [Arquitetura](architecture.md).

## O que tem dentro

| Área                       | Páginas                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Tutorial**               | [Comece aqui](tutorial/index.md) · [Roteamento](tutorial/routing.md) · [Estado](tutorial/state.md) · [Buscando dados](tutorial/data-fetching.md) · [Formulários](tutorial/forms.md) · [Fluxo de auth](tutorial/auth-flow.md)                                                                                                                                                                     |
| **Estrutura de aplicação** | [Scaffold](scaffold.md), [Vite & alias](vite-config.md), [Roteamento](routing.md), [Estado (Zustand)](state.md), [Providers](app-providers.md)                                                                                                                                                                                                                                                   |
| **Design de Software**     | [Mapa](design/index.md) — [Camadas](design/architecture.md), [Pastas](design/folders.md), [Fluxo de dados](design/data-flow.md), [Estado](design/state.md), [Componentes](design/components.md), [Limites](design/limits.md), [Tipagem](design/typing.md), [Testes](design/testing.md), [Anti-padrões](design/anti-patterns.md), [Checklist](design/checklist.md) |
| **Guia**                   | [Arquitetura](architecture.md), [Gallery (demo)](gallery.md)                                                                                                                                                                                                                                                                                                                                     |
| **Componentes**            | [Catálogo](components.md) — [Entrada](components/inputs.md), [Ação](components/actions.md), [Navegação](components/navigation.md), [Overlay](components/overlay.md), [Layout](components/layout.md), [Dados](components/data.md), [Feedback](components/feedback.md), [Identidade](components/identity.md), [Utilitários](components/utility.md), [Overlays & avançados](components/advanced.md) |
| **Hooks**                  | [Hooks utilitários](hooks.md)                                                                                                                                                                                                                                                                                                                                                                    |
| **Integrações**            | [HTTP](http.md), [Auth](auth.md), [Query](query.md), [SSE](sse.md), [WebSocket](websocket.md), [Web Push](push.md), [Offline](offline.md), [Web Share](share.md), [Áudio](audio.md)                                                                                                                                                                                                              |
| **Formulários**            | [Forms (zod)](forms.md), [Forms BR](forms-br.md)                                                                                                                                                                                                                                                                                                                                                 |
| **Estilo & Tema**          | [Estilos & Design Tokens](styles.md), [Tema](theme.md), [i18n](i18n.md)                                                                                                                                                                                                                                                                                                                          |
| **Observabilidade**        | [Telemetry](telemetry.md), [Feature Flags](feature-flags.md), [Logger](logger.md), [Error Boundary](error-boundary.md)                                                                                                                                                                                                                                                                           |
| **Receitas**               | [Cookbook](cookbook.md), [Utilitários](utilities.md)                                                                                                                                                                                                                                                                                                                                             |
| **Projeto**                | [Testing helpers](testing.md), [Release pipeline](release.md)                                                                                                                                                                                                                                                                                                                                    |

## Início rápido (manual)

Monte a raiz do app com `<AppProviders>` (error boundary + Query + tema + i18n
num bloco só) e `<AppRouter>` (rotas declarativas):

```tsx
import { AppProviders, AppRouter, defineRoutes } from "tempest-react-sdk";
import "tempest-react-sdk/styles.css";

const routes = defineRoutes([{ path: "/", element: <h1>Olá 👋</h1> }]);

export function App() {
  return (
    <AppProviders errorBoundary={{ fallback: <p>Algo deu errado.</p> }}>
      <AppRouter routes={routes} fallback={<p>Carregando…</p>} />
    </AppProviders>
  );
}
```

## Repositório & npm

- **npm:** <https://www.npmjs.com/package/tempest-react-sdk>
- **GitHub:** <https://github.com/mauriciobenjamin700/tempest-react-sdk>
- **Para LLMs:** [llms.txt](llms.txt) (índice curado) · [llms-full.txt](llms-full.txt) (docs completos)

> O README do repositório é a landing page do npm/GitHub. Esta documentação é a
> fonte de verdade navegável por módulo.

---

# integration-fastapi.md

# Integração full-stack Tempest (React ⇄ FastAPI)

Você tem um backend feito com o [`tempest-fastapi-sdk`](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/) e um frontend feito com este SDK. Esta página mostra como os dois **falam o mesmo contrato sem cola manual**: erros tipados, correlação por `request_id`, paginação, autenticação e geração de serviços a partir do OpenAPI.

!!! info "O que você vai aprender"
    - Como um erro do backend vira um `TempestApiError` tipado no front (`err.code`, `err.requestId`).
    - Como propagar o `X-Request-ID` para correlacionar logs dos dois lados.
    - Como respeitar `Retry-After` em `429`/`503`.
    - Como consumir paginação **offset** e **cursor** com hooks prontos.
    - Como montar autenticação JWT turn-key com `createTempestAuth`.
    - Como gerar serviços tipados a partir do `/openapi.json`.

---

## O contrato que os dois lados compartilham

O `tempest-fastapi-sdk` padroniza alguns formatos. Este SDK foi alinhado a eles:

| Conceito | Formato do backend |
| --- | --- |
| **Erro** | `{ "detail": str, "code": "ERROR_CODE", "details": { "request_id": str } }` |
| **Paginação offset** | `{ items, total, page, size, pages }` · query `?page&size` (convenção `fastapi-pagination`) |
| **Paginação cursor** | `{ items, next_cursor, has_more, limit }` · query `?cursor&limit&order_by&ascending` |
| **Login** | `{ access_token, token_type: "bearer" }` · header `Authorization: Bearer <token>` |
| **Correlação** | middleware lê/gera `X-Request-ID`; ecoa em `details.request_id` no erro |
| **Rate limit** | `429 Too Many Requests` + `Retry-After: <segundos>` |

---

## 1. Erros tipados (`TempestApiError`)

Toda resposta não-2xx do `createApiClient` (e do `uploadWithProgress`) vira um `TempestApiError` — um `Error` de verdade que carrega os campos do envelope.

```tsx
import { createApiClient, isApiError } from "tempest-react-sdk";

const api = createApiClient({ baseURL: import.meta.env.VITE_API_URL });

try {
    await api.post("/api/users", { body: { email } });
} catch (err) {
    if (isApiError(err) && err.code === "EMAIL_TAKEN") {
        setFieldError("email", err.detail); // mensagem humana do backend
        console.warn("falhou", err.requestId); // mesmo id que está no log do backend
    } else {
        throw err;
    }
}
```

O `err` tem este formato:

```ts
interface ApiError {
    status: number; // 409
    detail: string; // "Email já cadastrado"
    code?: string; // "EMAIL_TAKEN"  (do campo `code`)
    requestId?: string; // "req-abc"      (de details.request_id)
    retryAfter?: number; // segundos, quando houver Retry-After
    body?: unknown; // corpo cru
}
```

!!! tip "Branch por `code`, não por `detail`"
    O `detail` é texto para humanos e pode ser traduzido/mudar. O `code` é estável — use-o para lógica (`if (err.code === "INSUFFICIENT_FUNDS")`).

!!! check "Nada para configurar"
    Isso já é o comportamento padrão. Qualquer chamada via `createApiClient` ou pela classe gerada pelo codegen (que usa o `ApiClient` por baixo) entrega o erro nesse formato.

---

## 2. Correlação com `X-Request-ID`

O `createApiClient` envia um header `X-Request-ID` único por requisição. O `RequestIDMiddleware` do backend o reutiliza (em vez de gerar outro) e o ecoa de volta no `details.request_id` do erro — então um clique no front e a linha de log no backend compartilham o mesmo id.

```tsx
import { createApiClient, createLogger } from "tempest-react-sdk";

const log = createLogger({ namespace: "app" });

const api = createApiClient({
    baseURL: import.meta.env.VITE_API_URL,
    // Opcional: use seu próprio gerador (ex.: derivado do trace do navegador).
    requestId: () => crypto.randomUUID(),
});
```

Quando algo falha, logue o `requestId` para casar com o backend:

```tsx
catch (err) {
    if (isApiError(err)) log.error("request failed", { requestId: err.requestId });
}
```

!!! note "Desligando o header"
    Passe `requestId: () => ""` para não enviar o header (ex.: se um proxy já injeta o seu).

---

## 3. Respeitando `Retry-After`

Quando o backend devolve `429`/`503` com `Retry-After`, o `TempestApiError` já traz `retryAfter` (segundos). O helper `retry()` honra isso automaticamente, sobrepondo o backoff exponencial.

```tsx
import { retry, isApiError } from "tempest-react-sdk";

const data = await retry(() => api.get("/api/reports"), {
    retries: 5,
    // só re-tenta em rate limit / indisponibilidade
    shouldRetry: (err) => isApiError(err) && [429, 503].includes(err.status),
});
```

!!! warning "O hint é limitado pelo `maxDelay`"
    Se o servidor pedir 300 s mas seu `maxDelay` for 10 s, a espera fica em 10 s. Ajuste `maxDelay` se quiser obedecer esperas longas. Para ignorar o header, passe `respectRetryAfter: false`.

---

## 4. Paginação

### Offset — `usePaginatedQuery`

Para rotas que devolvem `{ items, total, page, size, pages }`:

```tsx
import { usePaginatedQuery } from "tempest-react-sdk";

function UsersTable() {
    const users = usePaginatedQuery<User>({
        queryKey: ["users"],
        pageSize: 25,
        queryFn: (params) => api.get<OffsetPage<User>>("/api/users", { params }),
    });

    if (users.isLoading) return <Spinner />;

    return (
        <>
            <ul>
                {users.items.map((u) => (
                    <li key={u.id}>{u.email}</li>
                ))}
            </ul>
            <button onClick={users.prev} disabled={!users.hasPrev}>
                Anterior
            </button>
            <span>
                {users.pageNumber} / {users.pageCount} · {users.total} no total
            </span>
            <button onClick={users.next} disabled={!users.hasNext}>
                Próxima
            </button>
        </>
    );
}
```

O hook **controla o estado de página** internamente, envia `page` + `size` para o `queryFn`, mantém a página anterior visível enquanto a próxima carrega (`keepPreviousData`) e deriva `hasNext`/`hasPrev`/`pageCount`.

!!! tip "`size` vs `page_size`"
    O default segue o `fastapi-pagination` (`?size=`). Se o seu backend usa `page_size`, passe `sizeParam: "page_size"`. O `order_by`/`ascending` só são enviados quando você define `orderBy`.

### Cursor — `useCursorQuery`

Para rotas de feed infinito que devolvem `{ items, next_cursor, has_more, limit }`:

```tsx
import { useCursorQuery } from "tempest-react-sdk";

function Feed() {
    const feed = useCursorQuery<Post>({
        queryKey: ["feed"],
        limit: 30,
        queryFn: (params) => api.get<CursorPage<Post>>("/api/feed", { params }),
    });

    return (
        <>
            {feed.items.map((p) => (
                <Card key={p.id} post={p} />
            ))}
            {feed.hasNextPage && (
                <button onClick={feed.fetchNextPage} disabled={feed.isFetchingNextPage}>
                    Carregar mais
                </button>
            )}
        </>
    );
}
```

O `next_cursor` opaco é repassado literalmente como próximo cursor; o loop para quando `has_more` vira `false`.

!!! tip "Cursor é opaco"
    Nunca tente interpretar o `next_cursor` — ele é base64/JSON do backend. Só devolva o valor recebido.

### Descobrir qual envelope veio

Endpoint que responde os dois formatos (ou código genérico que aceita
qualquer um) precisa distinguir em runtime. Os type guards fazem isso e já
estreitam o tipo:

```ts
import { emptyOffsetPage, isCursorPage, isOffsetPage } from "tempest-react-sdk";

const payload: unknown = await api.get("/api/items");

if (isOffsetPage<Item>(payload)) {
    console.log(payload.total, payload.pages);
} else if (isCursorPage<Item>(payload)) {
    console.log(payload.next_cursor, payload.has_more);
}
```

`isOffsetPage` exige `items` + `total` + `pages`; `isCursorPage` exige `items` +
`has_more` + a chave `next_cursor`. Para o primeiro render antes de qualquer
resposta, `emptyOffsetPage<Item>(25)` devolve um envelope zerado pronto para
`placeholderData`/`initialData` — evita o `items?.map` espalhado pela tela.

---

## 5. Autenticação turn-key — `createTempestAuth`

Em vez de montar `createAuthStore` + `createRefreshQueue` + `createApiClient` na mão, o preset conecta tudo ao contrato real: login `{ access_token }`, header `Bearer`, e `401 → refresh → retry` deduplicado.

```tsx
import { createTempestAuth } from "tempest-react-sdk";

export const auth = createTempestAuth<User, { email: string; password: string }>({
    baseURL: import.meta.env.VITE_API_URL,
    loginPath: "/api/auth/login", // default
    refreshPath: "/api/auth/refresh", // default
    mePath: "/api/auth/me", // opcional: busca o usuário após o login
});
```

!!! tip "`prefix`: o `root_path` em um lugar só"
    Se o serviço está montado sob `root_path="/api"` — o normal com o `tempest-fastapi-sdk` —, passe `prefix: "/api"` e escreva os caminhos sem ele. Vale para o preset e para qualquer `createApiClient`; detalhes em [HTTP → Base URL e prefixo](./http.md#base-url-e-prefixo).

    ```tsx
    export const auth = createTempestAuth<User>({
        baseURL: import.meta.env.VITE_API_URL, // https://api.exemplo.com
        prefix: "/api",
        mePath: "/auth/me",
    });

    await auth.api.get("/orders"); // https://api.exemplo.com/api/orders
    ```

    Os defaults `loginPath`/`refreshPath` continuam com `/api` escrito e **não** duplicam sob o prefixo — ele é aplicado no máximo uma vez.

Use em qualquer lugar:

```tsx
// Login (armazena a sessão e resolve o usuário)
const user = await auth.login({ email, password });

// Requisições autenticadas — o token Bearer é injetado, e um 401 dispara
// um refresh único e re-tenta a chamada original
const orders = await auth.api.get("/api/orders");

// Logout (limpa sessão + refresh token guardado)
auth.logout();
```

O store é o mesmo `createAuthStore` (persistido), então funciona com o `<AuthGuard>`:

```tsx
import { Navigate } from "react-router";
import { AuthGuard } from "tempest-react-sdk";

function ProtectedDashboard() {
    const isAuthenticated = auth.useAuthStore((state) => state.isAuthenticated);

    return (
        <AuthGuard isAuthenticated={isAuthenticated} fallback={<Navigate to="/login" />}>
            <Dashboard />
        </AuthGuard>
    );
}
```

### Quando a sessão morre de verdade

Um `refresh()` que resolve não prova que a sessão está viva — o backend pode devolver um token que ele mesmo recusa (refresh token revogado, permissão retirada, corrida entre abas). Nesse caso o preset **limpa a sessão do mesmo jeito**: `isAuthenticated` vira `false`, o token guardado some, e o `<AuthGuard>` acima passa a renderizar o `fallback`. O app nunca fica preso num store que diz "autenticado" enquanto toda requisição dá 401.

Isso basta na maioria dos apps, porque o guard já navega. Quando a expiração pode acontecer **fora** de qualquer subárvore guardada, passe `redirectTo` e o preset navega ele mesmo:

```tsx
export const auth = createTempestAuth<User>({
    baseURL: import.meta.env.VITE_API_URL,
    redirectTo: "/login", // navegação dura, só quando o guard não dá conta
});
```

!!! tip "Prefira o guard ao `redirectTo`"
    `redirectTo` usa `window.location.assign`, o que recarrega a aplicação inteira e descarta o histórico do router. O caminho declarativo (`<RouteGuard when={isAuthenticated} redirectTo="/login">`) mantém a SPA viva e não precisa de opção nenhuma — o `logout()` interno já dispara a navegação.

    `redirectTo` **não** dispara num `auth.logout()` explícito: ali quem chamou normalmente já navega, e duas navegações competindo é pior que nenhuma.

### Retentativa

O cliente de `auth.api` aceita a mesma opção `retry` do [`createApiClient`](./http.md#retentativa-embutida) — desligada por default, e conservadora quando ligada (só método idempotente, só falha de rede/`5xx`/`429`):

```tsx
export const auth = createTempestAuth<User>({
    baseURL: import.meta.env.VITE_API_URL,
    retry: true,
});
```

!!! info "Refresh token: corpo ou cookie"
    Por padrão, se o login devolver `refresh_token`, ele é guardado e enviado como `{ refresh_token }` no refresh. Se o seu backend usa cookie httpOnly, passe `withCredentials: true` e o refresh vai sem corpo, confiando no cookie.

!!! danger "Onde guardar o token"
    O preset persiste no `localStorage` por padrão (DX). Para apps sensíveis, prefira refresh token em **cookie httpOnly** (`withCredentials: true`) — assim o JS nunca toca o refresh token.

---

## 6. Gerando serviços do OpenAPI

O comando `tempest gen api` lê o `/openapi.json` do FastAPI e gera, por grupo de rotas, um `service.ts` tipado (veja [OpenAPI (codegen)](openapi.md) para o detalhe completo). A integração com tudo acima é automática:

```bash
npx tempest gen api http://localhost:8000/openapi.json --out src/api
```

- Os métodos chamam o `ApiClient` por baixo → **erros já viram `TempestApiError`**.
- Rotas que devolvem os envelopes de paginação geram retornos `OffsetPage<T>` / `CursorPage<T>` automaticamente — prontos para `usePaginatedQuery`/`useCursorQuery`.

```ts
// gerado em src/api/users/service.ts
import type { ApiClient, OffsetPage } from "tempest-react-sdk";

export class UsersService {
    constructor(private readonly api: ApiClient) {}

    /** `GET /api/users` */
    async listUsers(params: { page?: number; page_size?: number }): Promise<OffsetPage<User>> {
        return this.api.get<OffsetPage<User>>("/api/users", { params });
    }
}
```

Ligue o serviço gerado ao client autenticado:

```tsx
import { UsersService } from "./api/users";

const usersService = new UsersService(auth.api);

const users = usePaginatedQuery<User>({
    queryKey: ["users"],
    queryFn: (params) => usersService.listUsers(params),
});
```

---

## O loop completo

```text
backend (tempest-fastapi-sdk)
   │  expõe /openapi.json + contratos (erro, paginação, JWT, X-Request-ID)
   ▼
tempest gen api  ──►  src/api/<grupo>/{schemas,types,service}.ts
   │
   ▼
createTempestAuth  ──►  auth.api (Bearer + refresh + erros TempestApiError)
   │
   ▼
usePaginatedQuery / useCursorQuery  ──►  UI tipada, correlação por request_id
```

## Recursos pareados que já existem dos dois lados

| Frontend (este SDK) | Backend (`tempest-fastapi-sdk`) |
| --- | --- |
| `createEventStream` / `useEventStream` | SSE (Real-time) |
| `WebPushClient` / `usePushSubscription` | Web Push (VAPID) |
| `validateCPF` / `validateCNPJ` / `useViaCEP` | Brazilian Helpers |
| `createApiClient` (retry, idempotency) | HTTP Client (retry/backoff) |

## Recap

- Erros do backend chegam como **`TempestApiError`** com `code` + `requestId` — use `isApiError` e faça branch por `code`. ✅
- O **`X-Request-ID`** é enviado automaticamente e correlaciona front ↔ backend. ✅
- **`Retry-After`** é respeitado pelo `retry()` em `429`/`503`. ✅
- **`usePaginatedQuery`** (offset) e **`useCursorQuery`** (cursor) consomem os envelopes do backend sem mapeamento manual. ✅
- **`createTempestAuth`** entrega login + Bearer + refresh/retry em uma chamada. ✅
- **`tempest gen api`** gera serviços tipados que já falam todos esses contratos. ✅

---

# logger.md

# Logger

`createLogger` é um logger nivelado com **sinks plugáveis**. O padrão escreve no `console`; você troca ou soma destinos (Sentry, Datadog, ingestão remota) implementando a interface `LoggerSink`. Cada entrada é estruturada (`{ level, message, context, timestamp }`), não uma string solta.

!!! info "Por que não `console.log` direto?"
    `console.log` espalhado pelo código não tem nível (não dá pra silenciar `debug` em produção), não tem namespace (de onde veio aquele log?) e não dá pra redirecionar para um serviço remoto. O logger resolve os três: filtra por nível, prefixa namespaces e despacha a mesma entrada para quantos sinks você quiser.

## Uso

```ts
import { createLogger } from "tempest-react-sdk";

const log = createLogger({ level: "info" });

log.info("app booted");
log.warn("cache miss", { key: "user:42" });
log.error("payment failed", { orderId: "ord_1", reason: "card_declined" });
log.debug("verbose trace"); // descartado: debug < info
```

O segundo argumento (`context`) é um objeto livre `Record<string, unknown>` — anexe metadados estruturados em vez de interpolar na mensagem.

## Níveis

A ordem é `debug` < `info` < `warn` < `error`. Tudo **abaixo** do `level` configurado é descartado antes mesmo de chegar aos sinks:

```ts
const prod = createLogger({ level: "warn" });
prod.info("isso some"); // descartado
prod.warn("isso aparece"); // emitido
```

!!! tip "Ajuste o nível por ambiente"
    Use `level: "debug"` em desenvolvimento e `level: "warn"` (ou `"error"`) em produção. Como o filtro acontece antes dos sinks, logs silenciados não custam I/O nem chamadas de rede.

## Namespaces (loggers filhos)

`log.child(namespace)` cria um logger que prefixa `[namespace]` em cada mensagem. Filhos podem ter filhos — os namespaces se acumulam com `:`:

```ts
const log = createLogger({ level: "debug" });

const auth = log.child("auth");
auth.info("login ok"); // "[auth] login ok"

const refresh = auth.child("refresh");
refresh.warn("retry"); // "[auth:refresh] retry"
```

!!! note "Filhos herdam nível e sinks"
    Um logger filho compartilha o `level` e os `sinks` do pai — só o namespace muda. Configure o destino uma vez na raiz e crie filhos à vontade pelos módulos.

## Sinks custom

Um sink é só uma função `(entry: LogEntry) => void`. Implemente a interface `LoggerSink` para mandar logs a qualquer lugar:

```ts
import { createLogger, type LoggerSink } from "tempest-react-sdk";

const datadogSink: LoggerSink = (entry) => {
  fetch("https://http-intake.logs.datadoghq.com/api/v2/logs", {
    method: "POST",
    headers: { "DD-API-KEY": import.meta.env.VITE_DD_KEY },
    body: JSON.stringify({
      status: entry.level,
      message: entry.message,
      context: entry.context,
      timestamp: entry.timestamp,
    }),
  }).catch(() => {
    /* nunca propaga falha de rede pro logging */
  });
};

const log = createLogger({ level: "info", sinks: [datadogSink] });
```

Para escrever no console **e** num destino remoto, combine sinks no array — `consoleSink` é exportado para isso:

```ts
import { createLogger, consoleSink } from "tempest-react-sdk";

const log = createLogger({
  level: "info",
  sinks: [consoleSink, datadogSink],
});
```

!!! warning "Sinks nunca derrubam o app"
    Cada sink roda dentro de um `try/catch` interno — se um sink lançar exceção, o erro é engolido e os demais sinks ainda recebem a entrada. Logging defeituoso não pode quebrar a aplicação.

## Plugando na telemetria

O mesmo padrão de sink conecta o logger ao seu provider de telemetria. Aqui um sink que vira breadcrumbs no Sentry:

```ts
import { createLogger, type LoggerSink } from "tempest-react-sdk";
import * as Sentry from "@sentry/browser";

const sentrySink: LoggerSink = (entry) => {
  Sentry.addBreadcrumb({
    level: entry.level === "warn" ? "warning" : entry.level,
    message: entry.message,
    data: entry.context,
  });
};

export const log = createLogger({ level: "info", sinks: [sentrySink] });
```

!!! note "Logger ≠ Telemetry"
    O logger é para **diagnóstico técnico** (traces, falhas, estados). Eventos de produto/negócio (`signup`, `purchase`) vão pelo módulo de [Telemetry](./telemetry.md), que tem semântica própria de eventos e adapters dedicados. Use cada um para o que foi feito.

## Recap

- `createLogger({ level, sinks, namespace })` cria um logger nivelado; padrão é `level: "info"` + `consoleSink`.
- Níveis `debug` < `info` < `warn` < `error`; o que está abaixo do `level` é filtrado antes dos sinks.
- `log.child(ns)` prefixa `[ns]`; filhos aninham com `:` e herdam nível/sinks do pai.
- Um `LoggerSink` é `(entry: LogEntry) => void`; combine vários no array `sinks` (incluindo o exportado `consoleSink`).
- Sinks rodam em `try/catch` — um sink quebrado nunca derruba o app nem os outros sinks.
- Logger é para diagnóstico técnico; eventos de produto vão pela Telemetry.

## Veja também

- [HTTP client](./http.md#log-de-requisicao) — passe o logger em `createApiClient({ logger })`
- [Telemetry](./telemetry.md) — para eventos de produto, não logs
- [Error Boundary](./error-boundary.md) — encaminhe `onError` para um sink/telemetria

---

# oauth.md

# OAuth (Google)

O módulo `oauth` cobre as **duas pontas** de um login social: o botão que o usuário clica (`<GoogleSignIn>`) e a rota de callback que troca a credencial do provider por uma sessão da sua API (`useOAuthCallback`).

!!! info "Por que envolver o `@react-oauth/google`?"
    Duas dores. Primeiro, o payload de sucesso do Google vem como `{ credential?: string }` — opcional, então todo call site precisa checar se veio vazio, e o `onError` não recebe argumento nenhum. Segundo, se o SDK declarasse `@react-oauth/google` como peer dep, **todo** app que instala `tempest-react-sdk` pagaria por ele, inclusive os que não têm login social. O wrapper resolve os dois: normaliza sucesso/erro em `OAuthCredential`/`OAuthError`, e você passa o `GoogleLogin` pela prop `component`.

## Instale o SDK do Google

O `@react-oauth/google` é do **seu app**, não do SDK:

```bash
npm install @react-oauth/google
```

## O botão: `<GoogleSignIn>`

Programa completo, copiável:

```tsx
import { GoogleLogin, GoogleOAuthProvider } from "@react-oauth/google";
import { GoogleSignIn } from "tempest-react-sdk";

export function LoginPage() {
  return (
    <GoogleOAuthProvider clientId={import.meta.env.VITE_GOOGLE_CLIENT_ID}>
      <GoogleSignIn
        component={GoogleLogin}
        locale="pt-BR"
        text="continue_with"
        onSuccess={async ({ idToken }) => {
          await fetch("/api/auth/google", {
            method: "POST",
            headers: { "content-type": "application/json" },
            body: JSON.stringify({ id_token: idToken }),
          });
        }}
        onError={(error) => console.error(error.message)}
      />
    </GoogleOAuthProvider>
  );
}
```

Peça por peça:

1. `GoogleOAuthProvider` (do `@react-oauth/google`) carrega o script do Google e injeta o `clientId`. Ele fica **em volta**, normalmente no topo da árvore ou só na página de login.
2. `component={GoogleLogin}` é a injeção de dependência — é assim que o SDK renderiza o botão oficial do Google sem depender dele.
3. `onSuccess` recebe um `OAuthCredential` já validado: se o Google devolver resposta sem `credential`, o wrapper chama `onError` e **não** chama `onSuccess`. Você nunca lida com `idToken` vazio.
4. `onError` recebe um `OAuthError` com `provider` e `message` preenchidos.

### Props

| Prop            | Tipo                                         | Descrição                                                                 |
| --------------- | -------------------------------------------- | ------------------------------------------------------------------------- |
| `component`     | `(props) => ReactNode`                       | **Obrigatório.** O `GoogleLogin` importado pelo seu app.                  |
| `onSuccess`     | `(c: OAuthCredential) => void \| Promise`    | **Obrigatório.** Recebe `{ idToken, provider, raw }`.                     |
| `onError`       | `(e: OAuthError) => void`                    | Erro normalizado (inclui o caso "veio sem credential").                   |
| `locale`        | `string`                                     | Idioma do botão (ex.: `"pt-BR"`). Default: locale do browser.             |
| `theme`         | `"filled_blue" \| "filled_black" \| "outline"` | Tema visual repassado ao Google.                                        |
| `text`          | `"signin_with" \| "signup_with" \| "continue_with" \| "signin"` | Texto do botão.                                       |
| `shape`         | `"rectangular" \| "pill" \| "circle" \| "square"` | Forma do botão.                                                     |
| `size`          | `"large" \| "medium" \| "small"`             | Tamanho.                                                                  |
| `disableOneTap` | `boolean`                                    | Desliga o auto-prompt "One Tap". Default `false` (One Tap **ligado**).     |
| `width`         | `number`                                     | Largura em px — o botão do Google é fixo por padrão.                      |
| `className`     | `string`                                     | Aplicada no wrapper.                                                      |
| `style`         | `CSSProperties`                              | Aplicado no wrapper.                                                      |

!!! warning "One Tap vem ligado"
    `disableOneTap` tem default `false`, ou seja o SDK passa `useOneTap: true` pro Google. Se você não quer o prompt automático aparecendo sozinho no canto da tela (comum em telas que não são de login), passe `disableOneTap`.

### O que chega no `onSuccess` / `onError`

```ts
interface OAuthCredential {
  idToken: string; // JWT do provider — manda pro seu backend validar
  provider: string; // "google"
  raw?: unknown; // resposta crua do SDK do provider
}

interface OAuthError {
  provider: string;
  code?: string;
  message: string;
  raw?: unknown;
}
```

!!! danger "Nunca confie no `idToken` no cliente"
    O `idToken` é um JWT assinado pelo Google, mas quem **valida a assinatura** tem que ser o seu backend (via as chaves públicas do Google), conferindo `aud` (seu `clientId`) e `iss`. Decodificar no cliente com `decodeJWT` serve pra UI (mostrar nome/foto), nunca pra autorizar.

## A rota de callback: `useOAuthCallback`

Quando o fluxo é **redirect** (o provider volta pra `/callback?code=…`) em vez de popup, você precisa trocar esse código por uma sessão — exatamente uma vez.

```tsx
import { useNavigate } from "tempest-react-sdk";
import { ErrorState, Spinner, useOAuthCallback } from "tempest-react-sdk";

interface Session {
  token: string;
  user: { id: string; name: string };
}

export function OAuthCallbackPage() {
  const navigate = useNavigate();

  const { loading, error } = useOAuthCallback<Session>({
    exchange: async () => {
      const code = new URLSearchParams(window.location.search).get("code");
      if (!code) throw new Error("missing code");
      const response = await fetch("/api/auth/google/exchange", {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({ code }),
      });
      if (!response.ok) throw new Error("exchange failed");
      return (await response.json()) as Session;
    },
    onSuccess: () => navigate("/dashboard", { replace: true }),
    onError: () => navigate("/login?error=oauth", { replace: true }),
  });

  if (loading) return <Spinner />;
  if (error) return <ErrorState description="Não foi possível concluir o login." />;
  return null;
}
```

Resultado: enquanto o POST está em voo aparece o spinner; ao resolver, o hook chama `onSuccess` e você redireciona; se estourar, `onError` manda pro login com a flag de erro.

!!! check "Roda uma vez, mesmo em StrictMode"
    Em desenvolvimento o React 18/19 monta cada componente duas vezes de propósito. Sem guarda, `exchange` dispararia dois POSTs e o segundo falharia — código OAuth é de uso único. O hook usa um `ref` pra garantir uma execução só, então você não vê o erro fantasma "code already redeemed" em dev.

### Retorno

| Campo     | Tipo                                  | Significado                            |
| --------- | ------------------------------------- | -------------------------------------- |
| `loading` | `boolean`                             | `true` enquanto `exchange` está pendente |
| `data`    | `T \| null`                           | Valor resolvido, quando deu certo      |
| `error`   | `unknown`                             | Motivo da rejeição, quando falhou      |
| `status`  | `"pending" \| "success" \| "error"`   | Estado agregado                        |

!!! tip "`exchange` só precisa ser uma Promise"
    O hook não sabe nada de OAuth — ele só executa uma função assíncrona uma vez e expõe o estado. Serve pra qualquer troca de "callback vira sessão": magic link, SSO corporativo, confirmação de e-mail.

## Fechando o ciclo com o `auth`

O par natural é o [`createAuthStore`](auth.md): o `onSuccess` grava a sessão, e daí em diante o `AuthGuard` e o `createApiClient` já enxergam o usuário logado.

```tsx
const { loading } = useOAuthCallback<Session>({
  exchange: () => api.post<Session>("/auth/google/exchange", { body: { code } }),
  onSuccess: ({ token, user }) => {
    useAuthStore.getState().setSession({ token, user });
    navigate("/dashboard", { replace: true });
  },
});
```

## Recapitulando

- `@react-oauth/google` é dependência do **seu** app; o SDK só recebe o `GoogleLogin` pela prop `component`.
- `<GoogleSignIn>` normaliza sucesso e erro — `onSuccess` só roda com `idToken` presente.
- One Tap vem **ligado**; desligue com `disableOneTap` onde não faz sentido.
- Validar o `idToken` é trabalho do backend, sempre.
- `useOAuthCallback` roda a troca uma vez só (à prova de StrictMode) e devolve `loading`/`data`/`error`/`status`.
- Casa com [`auth`](auth.md) pra gravar a sessão e com [`routing`](routing.md) pra redirecionar.

---

# offline-sync.md

# Offline Sync com `tempest-fastapi-sdk`

Esta receita liga o **frontend** (`tempest-react-sdk`) ao **backend** (`tempest-fastapi-sdk`) num fluxo offline-first completo: o app continua usável sem rede, grava localmente, e sincroniza com o servidor quando a conexão volta — sem perder nada e sem duplicar.

Ela é o par desta receita do backend: **[Offline-First Sync — tempest-fastapi-sdk](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/recipes/offline-sync/)**. Leia as duas juntas: o contrato (endpoints, watermark, tombstones) vem do backend; aqui montamos o lado do navegador.

## As duas metades

```text
┌─────────────── navegador (tempest-react-sdk) ───────────────┐      ┌──────── servidor (tempest-fastapi-sdk) ────────┐
│  createOfflineStore (IndexedDB)   ← fonte de verdade local   │      │  GET /api/analyses/changes  → delta (since)     │
│  createApiClient                  → push (upsert por id)     │ ───► │  PUT /api/analyses/{id}     → upsert idempotente │
│  installBackgroundSync (SW)       → fila + replay offline    │      │  soft delete (is_deleted/deleted_at)            │
└──────────────────────────────────────────────────────────────┘      └─────────────────────────────────────────────┘
```

- **Pull** (servidor → local): busca só o que mudou desde o último `server_time` (watermark), pagina até esgotar, aplica upserts e tombstones no store local.
- **Push** (local → servidor): cada mutação usa um `id` gerado no cliente e faz **upsert** — então repetir a chamada não duplica. O service worker enfileira o que falhar offline e **reenvia sozinho** quando volta a rede.

!!! info "Por que isso funciona com replay automático"
    O contrato do backend é **upsert por `id` do cliente** (idempotente) + **last-write-wins por `updated_at`**. Isso é exatamente o que torna o `installBackgroundSync` seguro: reenviar a mesma mutação N vezes converge pro mesmo estado.

## O jeito rápido: `createOfflineSync`

O `createOfflineSync` empacota o motor inteiro — **outbox** durável (IndexedDB), **flush single-flight** (push → pull), **guarda de offline**, **loop de paginação** e **watermark** — atrás de três callbacks de transporte. Você diz *como* entregar uma mutação, *como* buscar uma página do delta e *como* aplicar um item; o SDK cuida do resto.

```ts
// src/sync/engine.ts
import { createOfflineSync } from "tempest-react-sdk";
import { api } from "@/lib/api";
import { analyses } from "./store"; // createOfflineStore
import { fromDto, toPayload, type Analysis, type AnalysisDto } from "./types";

export const sync = createOfflineSync<Analysis, AnalysisDto>({
  databaseName: "AnalysesOutbox",
  watermark: { storageKey: "analyses.watermark" },

  // push: entregue uma mutação da fila
  deliver: async (entry) => {
    if (entry.op === "delete") {
      await api.delete(`/api/analyses/${entry.recordId}`);
      return;
    }
    await api.put(`/api/analyses/${entry.recordId}`, { body: toPayload(entry.payload!) });
  },

  // pull: uma página do delta desde o watermark
  pullPage: async (since, cursor) => {
    const page = await api.get<{ items: AnalysisDto[]; next_cursor: string | null; server_time: string }>(
      "/api/analyses/changes",
      { params: { since: since ?? undefined, cursor: cursor ?? undefined } },
    );
    return { items: page.items, nextCursor: page.next_cursor, serverTime: page.server_time };
  },

  // applyRemote: funda um item do servidor no store local (você é dono do conflito)
  applyRemote: async (dto) => {
    if (dto.is_deleted) {
      await analyses.delete(dto.id);
      return;
    }
    const local = await analyses.get(dto.id);
    // last-write-wins: preserva uma edição local pendente que seja mais nova
    if (local?.pending && local.updated_at > dto.updated_at) return;
    await analyses.put(fromDto(dto));
  },
});
```

Uso na UI:

```ts
// grava local, enfileira e dispara o flush
await analyses.put({ ...record, pending: true });
await sync.enqueue(record.createdOnServer ? "update" : "create", record.id, record);
await sync.flush("after-mutation");

sync.pendingCount(); // badge de pendências
sync.resetWatermark(); // no logout / troca de conta
sync.clearOutbox();
```

!!! tip "Quando sincronizar"
    Dispare `sync.flush("boot")` no boot, `sync.flush("online-event")` quando a rede voltar (veja `useOnline`), e no handler de web push. O flush é single-flight — gatilhos concorrentes colapsam num único run — e é **pulado sozinho** quando offline (`summary.skipped`).

!!! info "Entregas que falham ficam na fila"
    Se `deliver` lança, a entrada **permanece** na outbox com `attempts` incrementado e `lastError` gravado — o próximo flush tenta de novo. Combine com `installBackgroundSync` no service worker para reenviar mesmo com o app fechado.

!!! danger "A ordem por registro é preservada na falha — e antes não era"
    Quando uma entrada falha, as **demais entradas daquele mesmo registro** ficam
    sem ser tentadas nesta passada, e voltam na próxima na ordem original. Elas
    aparecem em `summary.deferred`, separadas de `summary.failed`, porque nunca
    foram enviadas.

    Isso importa porque `deliver` normalmente é um `PUT` upsert. Sem a regra, um
    `create` que falha seguido de um `update` do mesmo registro entregava o
    **update primeiro**: o servidor criava o registro pelo payload do update, e o
    `create` reenviado depois sobrescrevia com o snapshot **mais antigo**. A edição
    do usuário desaparecia sem erro em lugar nenhum.

    O bloqueio é **por registro, não por passada**: um registro que o servidor está
    recusando não segura as mutações de nenhum outro.

As seções abaixo mostram **o que o motor faz por baixo** (e como montar à mão quando você precisa de controle fino — múltiplos stores, merge por campo, etc.).

## Pré-requisitos

1. Backend com a receita offline-sync do `tempest-fastapi-sdk` (endpoint `GET /api/analyses/changes` + rota de upsert).
2. `dexie` instalado (peer do `createOfflineStore`): `npm i dexie`.
3. Um app PWA — gere com `create-tempest-app --pwa` (já traz o service worker). Veja [Scaffold › PWA](./scaffold.md#modo-pwa-pwa).

## 1. O modelo

Espelhe a entidade do backend. O `id` é **gerado no cliente** (UUID) e `updated_at` é a chave de conflito:

```ts
// src/sync/types.ts
export interface Analysis {
  id: string; // UUID gerado no cliente (crypto.randomUUID)
  user_id: string;
  animal_id: string;
  notes: string;
  created_at: string; // ISO 8601
  updated_at: string; // ISO 8601 — last-write-wins
  is_deleted: boolean;
  deleted_at: string | null;
}

/** Resposta de GET /api/analyses/changes (SyncPaginationSchema do backend). */
export interface ChangesResponse {
  items: Analysis[];
  next_cursor: string | null;
  has_more: boolean;
  limit: number;
  server_time: string; // watermark — guarde para o próximo `since`
}
```

## 2. O store local (IndexedDB)

```ts
// src/sync/store.ts
import { createOfflineStore } from "tempest-react-sdk";
import type { Analysis } from "./types";

/** Fonte de verdade offline, escopada por usuário. */
export const analyses = createOfflineStore<Analysis, string>({
  databaseName: "FamachaOffline",
  version: 1,
  tableName: "analyses",
  indexes: "&id, user_id, updated_at",
  ownerField: "user_id",
});
```

## 3. Pull — baixar o delta

Drena todas as páginas desde o watermark, aplica upserts e remove tombstones, e **só então** persiste o novo `server_time`. A regra de ouro do backend: o próximo `since` é o `server_time` da resposta, **nunca** o relógio do cliente.

```ts
// src/sync/pull.ts
import { analyses } from "./store";
import { api } from "@/lib/api";
import type { Analysis, ChangesResponse } from "./types";

const sinceKey = (userId: string) => `sync:analyses:since:${userId}`;

/** Sincroniza o servidor → local. Idempotente: pode rodar quantas vezes quiser. */
export async function pullAnalyses(userId: string): Promise<void> {
  const since = localStorage.getItem(sinceKey(userId)) ?? undefined;
  let cursor: string | undefined;
  let serverTime: string | undefined;

  do {
    const page = await api.get<ChangesResponse>("/api/analyses/changes", {
      params: { since, cursor, limit: 100, include_deleted: true },
    });

    const live = page.items.filter((a) => !a.is_deleted);
    const tombstones = page.items.filter((a) => a.is_deleted);

    if (live.length) await analyses.bulkPut(live, userId);
    for (const dead of tombstones) await analyses.delete(dead.id);

    serverTime ??= page.server_time; // snapshot da 1ª página
    cursor = page.has_more ? (page.next_cursor ?? undefined) : undefined;
  } while (cursor);

  if (serverTime) localStorage.setItem(sinceKey(userId), serverTime);
}
```

!!! warning "Primeira sincronia drena tudo"
    Sem `since`, o backend devolve o estado completo paginado. O loop acima respeita `has_more` e `next_cursor` até esgotar — não pare na primeira página.

## 4. Push — mutações offline-first

Grave **primeiro no local** (UI responde na hora), depois faça o upsert no servidor. Como o `id` é do cliente e a rota é upsert, o reenvio é seguro:

```ts
// src/sync/push.ts
import { analyses } from "./store";
import { api } from "@/lib/api";
import type { Analysis } from "./types";

export async function saveAnalysis(
  userId: string,
  input: { animal_id: string; notes: string; id?: string },
): Promise<Analysis> {
  const now = new Date().toISOString();
  const existing = input.id ? await analyses.get(input.id) : undefined;

  const record: Analysis = {
    id: input.id ?? crypto.randomUUID(),
    user_id: userId,
    animal_id: input.animal_id,
    notes: input.notes,
    created_at: existing?.created_at ?? now,
    updated_at: now,
    is_deleted: false,
    deleted_at: null,
  };

  // 1. Local primeiro — a UI nunca espera a rede.
  await analyses.put(record, userId);

  // 2. Upsert no servidor (idempotente por id). Se falhar offline, o
  //    service worker enfileira e reenvia sozinho (passo 5).
  await api.put(`/api/analyses/${record.id}`, { body: record });

  return record;
}

/** Soft delete: marca tombstone local + propaga. */
export async function deleteAnalysis(userId: string, id: string): Promise<void> {
  const now = new Date().toISOString();
  await analyses.update(id, { is_deleted: true, deleted_at: now, updated_at: now });
  await api.put(`/api/analyses/${id}`, {
    body: { ...(await analyses.get(id)) },
  });
}
```

## 5. Background sync no service worker

No `src/sw.ts` (gerado pelo `--pwa`), enfileire as mutações de `/api/analyses` que falharem offline — elas são reenviadas quando a conexão voltar:

```ts
// src/sw.ts
import { installBackgroundSync } from "tempest-react-sdk/sw";

installBackgroundSync({
  match: (url) => url.pathname.startsWith("/api/analyses"),
});
```

Isso cobre **PUT/POST/PATCH/DELETE**. O `saveAnalysis` acima já gravou local, então a UI não trava: o `await api.put(...)` rejeita offline, o SW guarda a requisição numa fila IndexedDB e a replaya no evento `sync` (ou no próximo request, em navegadores sem Background Sync API). Como o upsert é idempotente, o replay converge. Detalhes em [Web Push & Service Worker](./push.md).

## 6. Quando sincronizar

Dispare um `pullAnalyses` no boot, ao voltar online e periodicamente:

```ts
// src/sync/index.ts
import { pullAnalyses } from "./pull";
import { useAuth } from "@/stores/auth";

export function startSync(): void {
  const userId = useAuth.getState().user?.id;
  if (!userId) return;

  const run = () => void pullAnalyses(userId).catch(console.warn);

  run(); // boot
  window.addEventListener("online", run); // reconectou
  setInterval(run, 60_000); // polling leve (ou troque por web push)
}
```

!!! tip "Push em vez de polling"
    Se o backend dispara um **web push** quando há mudança, troque o `setInterval` por um `pullAnalyses` no handler de notificação — sincronia quase em tempo real e sem polling. Veja [Web Push](./push.md) + `usePushSubscription`.

## UI reativa e flush automático

Não fie o estado de sincronização na mão: `useOfflineSync(sync, opts)` inscreve o componente no motor (via `subscribe`/`getState`) e expõe `{ phase, pending, syncing, lastSummary, lastError, flush, enqueue }`, com flush opcional no mount, no evento `online` e num intervalo. `useSyncStatus(sync)` devolve um `{ tone, pending, syncing }` pronto pro `<SyncStatusBadge>`. Para a barra offline e o prompt de atualização do SW, veja **[PWA & Offline-First](./pwa.md)**.

```tsx
import { useOfflineSync, SyncStatusBadge, useSyncStatus } from "tempest-react-sdk";
import { sync } from "@/sync/engine";

function SyncBadge() {
  const { tone, pending } = useSyncStatus(sync);
  return <SyncStatusBadge tone={tone} pending={pending} />;
}
```

Para mutações otimistas ligadas ao TanStack Query, use `useOfflineMutation` — veja [Query](./query.md#useofflinemutation).

!!! tip "Coerência entre abas"
    Passe `crossTab: true` no `createOfflineSync` pra propagar o `SyncState` entre abas do mesmo origin via `BroadcastChannel` — uma aba que dá flush zera o badge de pendências em todas. O outbox já é um IndexedDB compartilhado; isto só espelha o estado em memória. `flush` continua single-flight **por aba** (entregas idempotentes por `id` cobrem o resto). Chame `sync.dispose()` no teardown pra fechar o canal.

    ```ts
    export const sync = createOfflineSync<Analysis, AnalysisDto>({
      databaseName: "AnalysesOutbox",
      crossTab: true,
      // ...
    });
    ```

## Conflitos: last-write-wins

O backend resolve por `updated_at` (a escrita mais recente vence). No cliente, o pull faz `bulkPut`, que **sobrescreve** o registro local pela versão do servidor — então uma edição local não confirmada pode ser substituída por uma versão mais nova do servidor. Se o seu domínio precisa de merge mais fino (campos independentes, CRDT), trate isso na camada de `saveAnalysis`/pull; o SDK te dá os blocos, não impõe a política.

Para os dois casos comuns, o SDK exporta resolvedores prontos pra usar dentro do `applyRemote` (empate → remoto vence):

```ts
import { lastWriteWins, higherVersionWins } from "tempest-react-sdk";

applyRemote: async (dto) => {
  const local = await analyses.get(dto.id);
  await analyses.save(lastWriteWins(local, dto, (r) => r.updatedAt));
  // ou: higherVersionWins(local, dto, (r) => r.version)
};
```

## Recap

- **`createOfflineStore`** é a fonte de verdade local (IndexedDB, escopado por `user_id`).
- **Pull** drena `GET /api/analyses/changes` por `has_more`, aplica upserts/tombstones e guarda o `server_time` como próximo `since`.
- **Push** grava local primeiro e faz **upsert por `id`** — idempotente.
- **`installBackgroundSync`** reenfileira e replaya mutações offline; idempotência torna o replay seguro.
- Conflito = **last-write-wins por `updated_at`**, definido pelo backend.
- Casa 1:1 com a [receita offline-sync do `tempest-fastapi-sdk`](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/recipes/offline-sync/). 🚀

---

# offline.md

# Offline (IndexedDB)

`createOfflineStore` empacota o Dexie com scoping opcional por owner. Use pra histórico de SSE/push, drafts e cache local que precisa sobreviver a reload.

!!! info "Por que IndexedDB e não `localStorage`?"
    `localStorage` é síncrono, limitado a ~5 MB e só guarda strings. IndexedDB é assíncrono, comporta MBs de dados estruturados e suporta índices/consultas. O `createOfflineStore` esconde a verbosidade do Dexie por trás de um CRUD tipado — e o `dexie` já vem como dependência direta do SDK (v0.2.0+), instalado junto com `npm install tempest-react-sdk`.

## Quando usar

- Mensagens recebidas via SSE/WebSocket que devem ficar visíveis offline.
- Drafts de formulários longos.
- Cache de dados raramente alterados (cidades, categorias) — combina com `initialData` do TanStack Query.

!!! warning "Não use pra estado de UI volátil"
    Toggle de menu, aba ativa, modal aberto — isso é estado de UI que morre no reload. Zustand (veja [State](./state.md)) é muito mais barato. Reserve o offline store pra dados que **precisam** persistir.

## Setup

```ts
import { createOfflineStore } from "tempest-react-sdk";

interface Notification {
  message_id: string;
  owner_id: string;
  type: "NOTIFY" | "PAYMENT-SUCCESS";
  message: string;
  created_at: string;
  read: boolean;
}

export const notificationsStore = createOfflineStore<Notification, string>({
  databaseName: "TempestNotifications",
  version: 1,
  tableName: "notifications",
  indexes: "&message_id, owner_id, read, created_at",
  keyPath: "message_id",
  ownerField: "owner_id",
});
```

Sintaxe do `indexes`: Dexie. `&` = primary key único, vírgulas separam indexes adicionais. `keyPath` aponta a propriedade usada como chave primária (default `"id"`). `ownerField` ativa o scoping multi-tenant — veja abaixo.

## Owner-scoping

Quando `ownerField` está configurado, todo método de leitura/escrita honra um argumento `owner` e persiste esse valor em cada registro. Isso isola os dados de cada usuário no mesmo banco — essencial quando duas contas usam o app no mesmo navegador:

```ts
const userId = "u-42";

// put carimba owner_id = "u-42" automaticamente
await notificationsStore.put(
  {
    message_id: "m-1",
    owner_id: "", // sobrescrito pelo owner
    type: "NOTIFY",
    message: "Bem-vindo",
    created_at: new Date().toISOString(),
    read: false,
  },
  userId,
);

// list só traz registros daquele owner
const mine = await notificationsStore.list(userId);

// count / clear / updateMany também ficam restritos ao owner
await notificationsStore.clear(userId); // não afeta outros usuários
```

!!! tip "Sem `ownerField`, o store vira global"
    Se você não configurar `ownerField`, os métodos ignoram o argumento `owner` e operam sobre a tabela inteira. Use o store global pra dados não associados a um usuário (catálogo de cidades, por exemplo).

## CRUD completo

```ts
const ownerId = "u-42";

// CREATE / UPDATE (upsert)
await notificationsStore.put(notification, ownerId);
await notificationsStore.bulkPut(notifications, ownerId); // uma transação

// READ
const one = await notificationsStore.get("m-1"); // por primary key
const recent = await notificationsStore.list(ownerId, {
  orderBy: "created_at",
  reverse: true,
  limit: 50,
  offset: 0,
  filter: (n) => !n.read, // predicate aplicado após o índice
});
const total = await notificationsStore.count(ownerId);

// UPDATE parcial
await notificationsStore.update("m-1", { read: true }); // por key
await notificationsStore.updateMany(ownerId, { read: true }); // todos do owner

// DELETE
await notificationsStore.delete("m-1"); // por key
await notificationsStore.clear(ownerId); // todos do owner
```

`raw` (a `Table` do Dexie) e `db` (a instância Dexie) ficam expostos pra queries avançadas — transações multi-tabela, `where().and()` complexos:

```ts
import { notificationsStore } from "./stores";

await notificationsStore.db.transaction("rw", notificationsStore.raw, async () => {
  const unread = await notificationsStore.raw
    .where("owner_id")
    .equals("u-42")
    .and((n) => !n.read)
    .toArray();
  console.log(`${unread.length} não lidas`);
});
```

## Combinando com SSE + TanStack Query

Padrão comum: receber por SSE, persistir offline, e usar o cache local como `initialData` pra a UI aparecer instantânea no reload:

```ts
import { notificationsStore } from "./stores";

useEventStream<Notification>(`${API}/notifications/stream`, {
  enabled: !!userId,
  onMessage: ({ data }) => {
    void notificationsStore.put(data, userId);
  },
});

useQuery({
  queryKey: ["notifications", userId],
  queryFn: () => notificationsStore.list(userId, { orderBy: "created_at", reverse: true }),
});
```

## `createOfflineDatabase` — várias tabelas numa base

`createOfflineStore` dá a cada store uma base só dela, que é a forma certa pra um cache isolado. Deixa de ser assim no instante em que as tabelas pertencem uma à outra: chats e suas mensagens, uma entidade e seus rascunhos, qualquer coisa que você leria ou limparia como uma unidade. Separá-las em bases diferentes custa a transação de verdade — o Dexie só roda uma atomicamente **dentro** de uma mesma base — e ainda espalha o bump de versão de uma mudança relacionada por dois lugares.

```ts
import { createOfflineDatabase } from "tempest-react-sdk";

type Chat = { id: string; service_id: string; updated_at: string };
type Message = { id: string; service_chat_id: string; created_at: string };

const database = createOfflineDatabase<{ chats: Chat; messages: Message }>({
  databaseName: "ChatDatabase",
  version: 1,
  tables: {
    chats: { indexes: "&id, service_id, updated_at" },
    messages: { indexes: "&id, service_chat_id, created_at" },
  },
});

const chats = database.store<Chat>("chats");
const messages = database.store<Message>("messages");

// As duas tabelas numa transação só — impossível entre bases separadas.
await database.db.transaction("rw", chats.raw, messages.raw, async () => {
  await chats.put(chat);
  await messages.bulkPut(pending);
});
```

Cada store tem exatamente a mesma superfície de `createOfflineStore` (`put`, `list`, `update`, `clear`, `count`, `raw`, …); só muda quem é dono da base. O `ownerField` é configurado **por tabela**, porque é comum uma base misturar dado por usuário com dado compartilhado.

!!! note "Por que o tipo vai na chamada, e não no schema"
    `database.store<Chat>("chats")` repete o tipo que o schema já declara. Não é gosto: o `Table<T>` do Dexie expande `UpdateSpec<T>` sobre as chaves de `T`, e derivar isso de um `TSchema[K]` ainda genérico faz o TypeScript desistir com `TS2589` ("excessively deep"). O **nome** continua checado contra o schema — errar a tabela é erro de tipo, e em runtime a chamada lança listando as disponíveis.

!!! warning "Uma base, uma versão"
    Mudou o índice de qualquer tabela, sobe o `version` da base inteira. É o preço de tê-las juntas — e é justamente o que evita duas bases relacionadas saírem de sincronia.

## Migrations

Bump `version` quando mudar `indexes`. Dexie roda migrações in-place. Pra rename de campo ou data shift, registre um upgrader via a instância Dexie exposta:

```ts
notificationsStore.db.version(2).upgrade(async (tx) => {
  await tx
    .table("notifications")
    .toCollection()
    .modify((n) => {
      n.read = n.read ?? false;
    });
});
```

!!! warning "Esquecer de bumpar a `version` quebra silenciosamente"
    Mudar `indexes` sem subir `version` faz o Dexie lançar `VersionError` na abertura do banco. Sempre incremente `version` junto com qualquer mudança de schema.

## Recap

- `createOfflineStore({ databaseName, version, tableName, indexes, keyPath, ownerField })` devolve um CRUD tipado sobre IndexedDB via Dexie (dependência direta do SDK).
- `ownerField` ativa scoping multi-tenant: `put`/`list`/`count`/`clear`/`updateMany` respeitam o `owner` e isolam dados por usuário.
- CRUD: `put`/`bulkPut`, `get`/`list` (com `orderBy`/`reverse`/`limit`/`offset`/`filter`), `update`/`updateMany`, `delete`/`clear`, `count`.
- `raw` e `db` abrem a porta pra queries Dexie avançadas.
- Bump `version` ao mudar `indexes`; use `db.version(N).upgrade(...)` pra migrações de dados.

## Veja também

- [SSE](./sse.md) — origem natural dos dados persistidos
- [Query](./query.md) — usar o store como `initialData`
- [Push](./push.md)

---

# openapi.md

# Gerar serviços do OpenAPI (`tempest gen api`)

Se o seu backend é FastAPI (ou qualquer API que exponha um **OpenAPI 3.x**), o
`tempest gen api` lê o spec e **gera o cliente tipado** pra você — no padrão da
Tempest: **schemas Zod**, **tipos TS** e uma **classe de serviço por grupo de
rotas** (tag), com **validação de entrada via Zod**.

Nada de escrever `fetch` na mão nem manter tipos sincronizados com o backend.

```bash
npx tempest gen api http://127.0.0.1:8000/openapi.json --out src/api
# ou a partir de um arquivo:
npx tempest gen api ./openapi.json --out src/api
```

## O que é gerado

Para cada **grupo de rotas** (a `tag` da operação no OpenAPI) sai uma pasta com
três arquivos:

```text
src/api/
├── index.ts            # re-exporta tudo
├── users/
│   ├── schemas.ts      # schemas Zod (z.object…) de cada model do grupo
│   ├── types.ts        # tipos TS (z.infer dos schemas)
│   └── service.ts      # classe UsersService com 1 método por rota
└── products/
    ├── schemas.ts
    ├── types.ts
    └── service.ts
```

### `schemas.ts` — Zod por model

```ts
import { z } from "zod";

export const UserSchema = z.object({
  id: z.number().int(),
  email: z.string().email(),
  role: z.enum(["admin", "member"]).optional(),
  bio: z.string().nullable().optional(),
});

export const UserCreateSchema = z.object({
  email: z.string().email(),
  name: z.string().optional(),
});
```

### `types.ts` — tipos inferidos

```ts
import type { z } from "zod";
import * as S from "./schemas";

export type User = z.infer<typeof S.UserSchema>;
export type UserCreate = z.infer<typeof S.UserCreateSchema>;
```

### `service.ts` — classe por grupo, com validação

```ts
import type { ApiClient } from "tempest-react-sdk";
import * as S from "./schemas";
import type { User, UserCreate } from "./types";

export class UsersService {
  constructor(private readonly api: ApiClient) {}

  /** `GET /users` */
  async listUsers(params: { limit?: number }): Promise<User[]> {
    return this.api.get<User[]>("/users", { params });
  }

  /** `POST /users` */
  async createUser(body: UserCreate): Promise<User> {
    S.UserCreateSchema.parse(body); // valida a entrada em runtime
    return this.api.post<User>("/users", { body });
  }

  /** `GET /users/{id}` */
  async getUser(id: number): Promise<User> {
    return this.api.get<User>(`/users/${id}`);
  }
}
```

## Como usar

A classe **recebe um `ApiClient`** (do [`createApiClient`](./http.md)) no
construtor — você injeta o seu, com a base URL e o token:

```ts
import { createApiClient } from "tempest-react-sdk";
import { UsersService } from "@/api/users";
import { useAuth } from "@/stores/auth";

const api = createApiClient({
  baseURL: import.meta.env.VITE_API_URL,
  getToken: () => useAuth.getState().token,
});

export const users = new UsersService(api);

// users.listUsers({ limit: 20 })  →  Promise<User[]>
// users.createUser({ email: "a@b.c" })  →  valida com Zod, depois POST
```

Com o TanStack Query (já montado pelo [`AppProviders`](./app-providers.md)):

```ts
import { useQuery } from "@tanstack/react-query";
import { users } from "@/api";

function UserList() {
  const { data } = useQuery({ queryKey: ["users"], queryFn: () => users.listUsers({}) });
  // data: User[] | undefined
}
```

!!! tip "Re-gere quando o backend mudar"
    Rode `tempest gen api` de novo após mexer no backend — os arquivos em
    `src/api/` são **gerados**, então trate-os como build artifact (não edite à
    mão; versione se quiser, mas regenere ao mudar o contrato).

!!! note "Validação de **entrada**, tipagem na **saída**"
    O método valida o **body** com `Schema.parse(...)` (erro cedo se você mandar
    dado inválido) e **tipa** a resposta. A resposta não é validada em runtime
    por padrão — confie no contrato do backend, ou valide manualmente com o
    schema correspondente se precisar de garantia.

!!! warning "Suporte atual"
    v1 cobre o comum de specs FastAPI: `components.schemas` (object, enum, array,
    `$ref`, nullable, anyOf/oneOf/allOf), parâmetros de path/query, body e
    resposta JSON, agrupados pela primeira `tag`. YAML e múltiplos content-types
    ainda não — aponte para o `/openapi.json` (JSON).

## Recap

- `tempest gen api <url|file> --out src/api` gera, **por grupo de rotas**, três arquivos: `schemas.ts` (Zod), `types.ts` (`z.infer`) e `service.ts` (classe).
- A classe de serviço recebe um `ApiClient` injetado e **valida o body com Zod** antes de chamar a API.
- Trate `src/api/` como artefato gerado — **regenere** quando o contrato mudar.
- Veja também: [HTTP / `createApiClient`](./http.md) · [Query](./query.md) · [CLI `tempest`](./cli.md).

---

# passkeys.md

# Passkeys (WebAuthn)

Login sem senha, com a biometria que o usuário já usa pra desbloquear o aparelho.

O SDK cobre **a metade do cliente**: as duas cerimônias (`navigator.credentials.create` e `.get`), a conversão base64url ↔ `ArrayBuffer` que todo mundo reimplementa errado, os sondadores de capacidade e a classificação de erro. A outra metade é o seu backend — e esta página diz exatamente o que ele precisa mandar e receber, porque um cliente WebAuthn que documenta só o próprio lado é inútil.

!!! info "Por que passkey e não senha"
    A chave privada nunca sai do aparelho, então não existe base de senhas pra vazar, nem phishing que funcione: o navegador só assina para o domínio que registrou a credencial. Pro usuário é um toque no sensor.

## A superfície

| Símbolo | Para quê |
| --- | --- |
| `createPasskeyClient` | Cliente sem framework: `register` + `authenticate` + sondadores |
| `usePasskeyRegistration` | Hook do fluxo "criar passkey" |
| `usePasskeySignIn` | Hook do fluxo "entrar com passkey", com autofill opcional |
| `usePasskeyCapabilities` | Só os três sondadores, quando você quer decidir a UI antes |
| `isPasskeySupported` | O navegador tem WebAuthn |
| `isPlatformAuthenticatorAvailable` | **Este aparelho** tem Face ID / Hello / digital |
| `isConditionalMediationAvailable` | O autofill de passkey está disponível |
| `classifyPasskeyError` / `PasskeyError` | Erro com `kind` no qual a UI faz `switch` |
| `base64UrlToBytes` / `bytesToBase64Url` | O encanamento, exposto porque você vai precisar |

## Comece pelo hook

Dois botões, dois hooks. Este é o cadastro, na tela de conta:

```tsx
import { usePasskeyRegistration } from "tempest-react-sdk";

import { api } from "../lib/api";

export function CriarPasskey() {
  const passkey = usePasskeyRegistration({
    getOptions: () => api.post("/api/webauthn/register/begin"),
    verify: (credential) =>
      api.post("/api/webauthn/register/finish", { body: credential }),
  });

  if (passkey.platformAvailable === null) return null;

  if (passkey.error?.kind === "already-registered") {
    return <p>Este aparelho já tem uma passkey da sua conta. 👍</p>;
  }

  return (
    <>
      <button
        type="button"
        onClick={() => void passkey.register()}
        disabled={passkey.status === "prompting" || passkey.status === "verifying"}
      >
        {passkey.status === "prompting" ? "Confirme no aparelho…" : "Criar passkey"}
      </button>
      {passkey.error && <p role="alert">{passkey.error.message}</p>}
      {passkey.status === "success" && <p>Passkey criada. ✅</p>}
    </>
  );
}
```

Peça por peça:

- **`getOptions`** é a sua rota `begin`. O servidor sorteia o desafio e devolve as opções.
- **`verify`** é a sua rota `finish`. Recebe o JSON que o SDK serializou.
- **`platformAvailable === null`** significa "ainda não sei" — o sondador é assíncrono. Não renderize nada de passkey nesse estado.
- **`register()` resolve, nunca rejeita.** Toda falha já é estado (`status`, `error.kind`) que a UI precisa desenhar; obrigar um `try/catch` num handler de botão só duplicaria o que o hook guarda.

!!! warning "`platformAvailable === false` não é "sem passkey""
    Significa "sem autenticador embutido **aqui**". O usuário ainda pode usar o celular por QR/hybrid. Ofereça como "usar meu celular", não como um toque.

## O login, e o autofill que faz a diferença

```tsx
import { usePasskeySignIn } from "tempest-react-sdk";

import { api } from "../lib/api";
import { useAuthStore } from "../store/auth";

export function LoginForm() {
  const passkey = usePasskeySignIn<{ access_token: string }>({
    conditional: true,
    getOptions: () => api.post("/api/webauthn/signin/begin"),
    verify: (assertion) =>
      api.post<{ access_token: string }>("/api/webauthn/signin/finish", {
        body: assertion,
      }),
    onSuccess: ({ access_token }) => useAuthStore.getState().setToken(access_token),
  });

  return (
    <form>
      <label htmlFor="email">E-mail</label>
      <input id="email" name="email" autoComplete="username webauthn" />

      <button type="button" onClick={() => void passkey.signIn()}>
        Entrar com passkey
      </button>
      {passkey.error && <p role="alert">{passkey.error.message}</p>}
    </form>
  );
}
```

`conditional: true` liga o fluxo de **autofill**: nenhum modal aparece; o navegador lista as passkeys **dentro do campo de e-mail**. O usuário toca em uma e está dentro, sem digitar nada.

!!! danger "`autocomplete="username webauthn"` não é opcional"
    Sem esse atributo no input, a lista **nunca** aparece — e não há erro nenhum, o pedido só fica pendurado. O hook não pode fazer essa parte por você: quem sabe qual campo é o de identificação é a sua tela.

Duas outras regras do modo condicional:

- **Um por página.** Um segundo pedido condicional simultâneo derruba o primeiro.
- **Abortar não é erro.** Se o usuário digitar a senha em vez de escolher a passkey, ou a tela desmontar, o pedido é abortado e o hook **não** marca erro — nada falhou, a pessoa escolheu outra porta.

## Os erros, e o que fazer com cada um

`error.kind` é o que a UI olha. `error.message` é texto em inglês, seguro de mostrar, mas o normal é você escrever a sua cópia por `kind`:

| `kind` | Causa | O que a UI faz |
| --- | --- | --- |
| `cancelled` | `NotAllowedError` | Nada de vermelho. Volte ao estado inicial |
| `already-registered` | `InvalidStateError` | **Sucesso disfarçado**: "já configurado neste aparelho" |
| `rp-mismatch` | `SecurityError` | Bug seu: `rp.id` não bate com a origem |
| `not-supported` | `NotSupportedError` | Nenhum autenticador aceita os algoritmos pedidos |
| `invalid-options` | `TypeError` | O `begin` mandou base64url quebrado |
| `insecure` | Página em HTTP | Sirva por HTTPS |
| `unsupported` | Navegador sem WebAuthn | Esconda a opção |
| `aborted` | Seu `signal` abortou | Silencie |
| `unknown` | O resto | Log + mensagem genérica |

!!! danger "`cancelled` é "cancelou **ou** expirou" — e é impossível saber qual"
    `NotAllowedError` cobre os dois casos **por design**: dizer ao site "essa conta não tem credencial aqui" vazaria a existência da conta. Trate como um só evento e nunca escreva "você cancelou" com certeza.

!!! tip "`rp-mismatch` é o erro de integração nº 1"
    `rp.id` tem que ser o domínio da página ou um **pai registrável** dele. `app.acme.com` pode usar `acme.com`; `acme.com` **não** pode usar `app.acme.com`. Em `localhost` deixe `rp.id` de fora.

## Sem React: `createPasskeyClient`

Os hooks são uma casca. O cliente é o que faz o trabalho, e serve num formulário puro, num worker ou num teste:

```ts
import { createPasskeyClient } from "tempest-react-sdk";

const passkeys = createPasskeyClient({ rpId: "acme.com", timeoutMs: 60_000 });

const options = await fetch("/api/webauthn/signin/begin", { method: "POST" }).then((r) =>
  r.json(),
);
const assertion = await passkeys.authenticate(options);
await fetch("/api/webauthn/signin/finish", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(assertion),
});
```

`rpId` e `timeoutMs` são só **defaults**: o que vier do servidor sempre ganha.

??? info "Injetando um `credentials` falso (testes)"
    `createPasskeyClient({ credentials })` aceita qualquer objeto com `create` e `get` — a interface `CredentialsContainerLike`. É assim que o próprio SDK testa as cerimônias, já que o jsdom não tem `navigator.credentials`.

## O que o seu backend precisa implementar

Quatro rotas. O SDK não fala com nenhuma delas por conta própria: você passa `getOptions` e `verify`.

### 1. `POST /webauthn/register/begin` → opções

Devolva um `PasskeyCreationOptionsJSON`. Todo campo binário é **base64url**:

```json
{
  "challenge": "9WVvY2..._Q",
  "rp": { "name": "Acme", "id": "acme.com" },
  "user": { "id": "dXNlci0x", "name": "ada@acme.com", "displayName": "Ada Lovelace" },
  "pubKeyCredParams": [{ "type": "public-key", "alg": -7 }],
  "excludeCredentials": [{ "id": "AQID", "type": "public-key" }],
  "authenticatorSelection": { "residentKey": "required", "userVerification": "preferred" }
}
```

- `challenge`: ≥16 bytes aleatórios, **guardados na sessão**, uso único.
- `user.id`: identificador opaco e estável. **Nunca** o e-mail — ele muda e fica gravado no autenticador.
- `excludeCredentials`: as credenciais que o usuário já tem. É o que faz o autenticador responder `InvalidStateError` (→ `already-registered`) em vez de criar uma duplicada.
- `pubKeyCredParams` pode ser omitido: o SDK oferece `-8` (Ed25519), `-7` (ES256) e `-257` (RS256) — a lista exata está exportada como `DEFAULT_PUB_KEY_CRED_PARAMS`, para o backend declarar o mesmo conjunto sem repetir os números.
- `residentKey: "required"` é o que torna a passkey **descobrível** — pré-requisito do login sem digitar nada.

### 2. `POST /webauthn/register/finish` ← credencial

Recebe um `PasskeyRegistrationJSON`. No servidor:

1. Decodifique `response.clientDataJSON` e confira `type === "webauthn.create"`, o `challenge` guardado e o `origin`.
2. Parseie `response.attestationObject`, extraia a chave pública e o contador de assinatura.
3. Grave `id`, chave pública, contador e `response.transports` (ajuda o login depois).

### 3. `POST /webauthn/signin/begin` → opções

Um `PasskeyRequestOptionsJSON` com um desafio novo. **Omita `allowCredentials`** para login sem identificação prévia e para o autofill — é o que deixa o navegador oferecer qualquer passkey do domínio.

### 4. `POST /webauthn/signin/finish` ← assertion

Recebe um `PasskeyAuthenticationJSON`:

1. Ache a credencial por `id` (ou por `response.userHandle`, que vem preenchido em credencial descobrível).
2. Confira o `clientDataJSON` como no passo 2, agora com `type === "webauthn.get"`.
3. Verifique `response.signature` sobre `authenticatorData || sha256(clientDataJSON)` com a chave pública guardada.
4. **Rejeite contador que não cresceu** — indica credencial clonada.
5. Só então emita o token de sessão.

!!! tip "Do lado do FastAPI"
    Uma biblioteca de servidor (`py_webauthn`, por exemplo) faz os passos 1–4. O que ela **não** faz é o que está nesta página: guardar o desafio na sessão, escolher o `user.id` e montar o `excludeCredentials`.

## Resumo

- **`createPasskeyClient`** — duas cerimônias, encanamento base64url, um tipo de erro. Sem framework.
- **`usePasskeyRegistration` / `usePasskeySignIn`** — estado (`status`, `error`, `data`) + a ação. Resolvem `null` em falha.
- **`isPlatformAuthenticatorAvailable()`** decide se o botão aparece; `platformAvailable === null` é "ainda não sei".
- **`conditional: true` + `autocomplete="username webauthn"`** é o login de um toque. O atributo é obrigatório.
- **`kind: "already-registered"` é sucesso**, `"cancelled"` é ambíguo por design, `"rp-mismatch"` é bug seu.
- O servidor faz 4 rotas; o cliente não inventa nenhuma delas.

### Veja também

- [Auth](./auth.md) — onde guardar o token que o `finish` devolveu
- [HTTP](./http.md) — o `api` dos exemplos
- [Access Control (RBAC)](./access-control.md) — o que a sessão pode fazer depois

---

# perf.md

# Custo de inferência on-device

Quando a inferência roda no dispositivo do usuário, você perde o gráfico do
servidor. O que chega é um relato: *"o app está lento no celular do fulano"*.
E sem número, "lento" pode ser três coisas diferentes que pedem correções
opostas. 🤔

O módulo `perf` mede o que o navegador **realmente** consegue observar sobre
uma execução: quanto tempo cada etapa levou, o que o dispositivo diz sobre si
mesmo, e o tamanho dos pesos que você precachou.

!!! info "Não existe contador de energia no navegador"
    Nenhuma API web reporta joules ou FLOPs. "Custo computacional" aqui é
    montado com o que dá para observar de dentro da página. O que a
    plataforma não expõe vem `null` — nunca um número inventado.

## Cronometrando um pipeline

```typescript
import { createInferenceProfiler } from "tempest-react-sdk";
import { Detector } from "tempest-react-sdk/vision";

const profiler = createInferenceProfiler();

const detector = await profiler.stage("load-model", () =>
    Detector.create("/models/detect.onnx"),
);
const results = await profiler.stage("detect", () => detector.predict(blob));

const report = await profiler.report();
console.log(report.timings); // { "load-model": 1840.5, detect: 118.9 }
console.log(report.totalMs); // 1959.4
```

Três formas de registrar tempo:

| Método | Para |
| --- | --- |
| `stage(nome, fn)` | Trabalho assíncrono — o valor resolvido passa direto |
| `stageSync(nome, fn)` | Trabalho síncrono — idem, sem `await` |
| `mark(nome, ms)` | Duração que **você já tem** medida em outro lugar |

Nomes repetidos **acumulam**, então duas passadas da mesma natureza somam numa
linha só.

!!! tip "Uma etapa que lança ainda é medida"
    O `stage()` registra a duração no `finally` e repropaga o erro. Um pipeline
    que falhou também tem uma história de tempo para contar — geralmente a mais
    interessante.

## ⚠️ Etapas concorrentes não fatiam o total

Etapas são medidas de forma **independente**, não como um ladrilhamento da
execução. Duas etapas iniciadas juntas recebem cada uma o seu span de relógio
inteiro:

```typescript
const profiler = createInferenceProfiler();

const [modelo, imagem] = await Promise.all([
    profiler.stage("models", () => Detector.create("/models/detect.onnx")),
    profiler.stage("decode", () => createImageBitmap(blob)),
]);

const report = await profiler.report();
// timings.models + timings.decode > report.totalMs — e está certo:
// as duas rodaram ao mesmo tempo.
```

Isso é a leitura honesta para um pipeline que decodifica a imagem enquanto as
sessões carregam. Só cuide de **não** desenhar as barras como se fossem uma
divisão do total — diga na interface que são frações indicativas.

## Aproveitando o `speed` do `/vision`

Cada `predict()` do subpath `/vision` já devolve o próprio detalhamento em
`results[0].speed` (`load`, `preprocess`, `inference`, `postprocess`). Dobre o
que interessa para dentro do relatório com `mark`:

```typescript
const results = await profiler.stage("detect", () => detector.predict(blob));
profiler.mark("forward-pass", results[0].speed.inference);
```

Agora o relatório tem o custo da chamada inteira **e** o do kernel — e a
diferença entre os dois é exatamente quanto pré/pós-processamento você está
pagando.

## O perfil do dispositivo

```typescript
import { readDeviceProfile } from "tempest-react-sdk";

const device = readDeviceProfile();
// { hardwareConcurrency: 8, deviceMemoryGb: 8, jsHeapUsedMb: 137.4 }
```

| Campo | Origem | Disponível em |
| --- | --- | --- |
| `hardwareConcurrency` | `navigator.hardwareConcurrency` | Todos os navegadores modernos |
| `deviceMemoryGb` | `navigator.deviceMemory` | Chromium apenas |
| `jsHeapUsedMb` | `performance.memory` | Chromium apenas (não padronizado) |

Em Firefox e Safari os dois últimos vêm `null`. O `report()` já inclui esse
perfil, então normalmente você não precisa chamar direto — a função existe para
quando você quer o dado fora de uma execução.

!!! note "Seguro em SSR"
    Sem `navigator`, todos os campos vêm `null` em vez de estourar.

## Quanto pesam os modelos

Modelos que você baixa e precacha em Cache Storage são o maior custo fixo de um
app de inferência on-device. O `report()` mede quem você listar:

```typescript
const report = await profiler.report({
    models: [
        { name: "detector", cacheName: "app-models", url: "/models/detect.onnx" },
        { name: "classifier", cacheName: "app-models", url: "/models/classify.onnx" },
    ],
});

console.log(report.models);
// [ { name: "detector", bytes: 12582912 }, { name: "classifier", bytes: null } ]
```

`bytes: null` significa uma de três coisas: o modelo não está em cache, o
Cache Storage não está disponível, ou a resposta guardada não tem
`Content-Length` (transferência chunked).

!!! warning "Por que o header e não o corpo"
    Ler `(await response.blob()).size` traria dezenas de megabytes de pesos
    para a memória só para descobrir o comprimento — a cada medição. O
    `cachedResponseBytes` lê só o `Content-Length`.

## Renderizando

`formatDurationMs` cobre a faixa que interessa aqui: milissegundos para um
forward pass, segundos para um cold start.

```typescript
import { formatBytes, formatDurationMs } from "tempest-react-sdk";

formatDurationMs(0.04); // "<1 ms"   — medido, mas rápido demais
formatDurationMs(142.6); // "143 ms"
formatDurationMs(4321); // "4.32 s"
formatDurationMs(NaN); // "—"

formatBytes(12582912); // "12 MB"
```

O `"<1 ms"` existe de propósito: `"0 ms"` seria lido como "não medido".

## Recap

- `createInferenceProfiler()` → `stage` / `stageSync` / `mark` → `report()`. ✅
- Etapas concorrentes somam mais que o `totalMs` — mostre isso na interface.
- `results[0].speed` do `/vision` entra no relatório via `mark`.
- Campos que a plataforma não expõe vêm `null`, para a UI mostrar "—".
- `formatDurationMs` + `formatBytes` para exibir.

---

# push.md

# Web Push + Service Worker

Notificações push no navegador têm duas metades que conversam: a **main thread** (sua UI pede permissão e cria a inscrição) e a **worker thread** (o service worker recebe o push e desenha a notificação, mesmo com a aba fechada). O módulo `push` do `tempest-react-sdk` cobre as duas metades — a parte browser (permissão, `pushManager.subscribe`, `notificationclick`) é do SDK; os endpoints de persistência e o envio do push são do seu app, via callbacks.

> Diagrama editável: [push-flow.drawio](./diagrams/push-flow.drawio) (abra no [draw.io](https://app.diagrams.net)).

## Como o Web Push funciona (visão de 30 segundos)

1. O app pede **permissão** ao usuário (`Notification.requestPermission()`).
2. Concedida a permissão, o navegador cria uma **`PushSubscription`** assinada com a sua chave **VAPID pública**.
3. O app envia o JSON da inscrição ao **seu backend**, que o guarda.
4. Mais tarde, o backend usa a chave **VAPID privada** para mandar um push pro endpoint da inscrição.
5. O **service worker** acorda no evento `push`, lê o payload e chama `showNotification`.

O SDK te dá os passos 1–3 (e os handlers do passo 5); os passos 3 (storage) e 4 (envio) são responsabilidade do backend.

!!! info "O que é VAPID, em uma frase"
    VAPID (_Voluntary Application Server Identification_) é um par de chaves
    (pública + privada) que identifica o seu servidor para o push service do
    navegador. A **pública** vai no front (`VITE_VAPID_PUBLIC_KEY`); a
    **privada** fica só no backend e nunca é exposta. Gere o par uma vez com
    `npx web-push generate-vapid-keys`.

## Pré-requisitos

1. Backend que armazena `PushSubscriptionJSON` e envia notificações via web-push (VAPID).
2. Service worker registrado (`vite-plugin-pwa`, `registerServiceWorker`, ou `navigator.serviceWorker.register`).
3. Variável `VITE_VAPID_PUBLIC_KEY` no front (chave pública VAPID URL-safe base64).
4. **HTTPS**, ou `localhost`. Service worker e Push API não existem em origem insegura — nem em IP de rede local (`http://192.168.0.10:5173`) enquanto você testa no celular. Pra isso, use um túnel HTTPS (`cloudflared`, `ngrok`).

!!! warning "O hook NÃO registra o service worker"
    `usePushSubscription` assume que o SW já está registrado e usa
    `navigator.serviceWorker.ready` por padrão. Registre o SW você mesmo (passo
    abaixo) — ou passe `getRegistration` para reusar uma registration própria.
    Sem SW registrado, o `subscribe()` nunca resolve.

## Adotando num app que já existe

Esta seção é pro caso mais comum: **o app já está no ar** e você vai ligar push
agora. Nada aqui exige adotar o scaffold, o `createViteConfig` ou virar PWA.

Checklist, na ordem:

1. Gerar o par VAPID e colocar a pública no front.
2. Ter um service worker servido **na raiz** (três cenários abaixo).
3. Instalar os handlers de push dentro desse SW.
4. Combinar o contrato dos dois endpoints com o backend.
5. Ligar o `usePushSubscription` num botão.
6. Amarrar `subscribe`/`unsubscribe` ao **login e logout** — o passo que quase todo mundo esquece.

### 1. Chaves VAPID

```bash
npx web-push generate-vapid-keys
```

```dotenv
# .env — só a pública vai pro front
VITE_VAPID_PUBLIC_KEY=BOxx…
```

A privada fica no backend. Trocar esse par depois **invalida todas as inscrições
existentes** — veja [rotação de chave](#rotacao-da-chave-vapid).

### 2. O service worker: três cenários

!!! danger "O arquivo do SW tem que ser servido na raiz do escopo"
    Um service worker só controla páginas **dentro do próprio caminho**: um
    `/assets/sw-abc123.js` controla `/assets/…` e mais nada — então
    `navigator.serviceWorker.ready` nunca resolve na sua home e o `subscribe()`
    fica pendurado pra sempre, sem erro no console.

    É o modo de falhar mais comum ao ligar push num app com bundler: o SW não
    pode passar pelo pipeline de assets com hash. Ele precisa sair em `/sw.js`
    (ou receber `Service-Worker-Allowed: /` no header). Confira em
    **DevTools → Application → Service workers**: o campo `Scope` tem que ser `/`.

=== "a. Não tenho service worker nenhum"

    Crie `src/sw.ts` e bunde ele **separado** do app, porque o entry do app
    passa pelo pipeline de assets e o SW não pode:

    ```ts
    /// <reference lib="webworker" />
    import {
      installNotificationClickHandler,
      installPushHandler,
      installSkipWaitingListener,
    } from "tempest-react-sdk/sw";

    declare const self: ServiceWorkerGlobalScope;

    installSkipWaitingListener();
    installPushHandler({ defaultTitle: "Minha App", defaultIcon: "/icons/logo.png" });
    installNotificationClickHandler();
    ```

    ```ts
    // vite.sw.config.ts — build só do worker, em dist/sw.js
    import { resolve } from "node:path";
    import { defineConfig } from "vite";

    export default defineConfig({
      build: {
        emptyOutDir: false, // não apaga o dist/ do app
        lib: {
          entry: resolve(__dirname, "src/sw.ts"),
          formats: ["iife"], // worker clássico, sem import/export
          name: "sw",
          fileName: () => "sw.js",
        },
        rollupOptions: { output: { entryFileNames: "sw.js", inlineDynamicImports: true } },
      },
    });
    ```

    ```json
    {
      "scripts": {
        "build": "vite build && npm run build:sw",
        "build:sw": "vite build --config vite.sw.config.ts"
      }
    }
    ```

    Registre no entry do app:

    ```ts
    // src/main.tsx
    import { registerServiceWorker } from "tempest-react-sdk";

    registerServiceWorker({ url: "/sw.js" });
    ```

    !!! tip "Sem passo de build, se você preferir"
        Um `public/sw.js` escrito na mão também funciona — arquivos de `public/`
        são copiados crus pra raiz do `dist/`. O custo é não poder `import` os
        helpers do SDK ali dentro: você escreve os listeners de `push` e
        `notificationclick` à mão. Vale pro caso simples; passando disso, bunde.

=== "b. Já uso `vite-plugin-pwa`"

    Só o modo **`injectManifest`** deixa você escrever o SW. Se o seu está em
    `generateSW` (o default), troque:

    ```ts
    // vite.config.ts
    VitePWA({
      strategies: "injectManifest",
      srcDir: "src",
      filename: "sw.ts",
      injectRegister: "auto",
    });
    ```

    E no `src/sw.ts`, junte os handlers do SDK aos seus do Workbox — eles não
    competem, são eventos diferentes (`push`/`notificationclick` de um lado,
    `fetch` do outro):

    ```ts
    /// <reference lib="webworker" />
    import { precacheAndRoute } from "workbox-precaching";
    import { installNotificationClickHandler, installPushHandler } from "tempest-react-sdk/sw";

    declare const self: ServiceWorkerGlobalScope & { __WB_MANIFEST: unknown[] };

    precacheAndRoute(self.__WB_MANIFEST); // o que o plugin já fazia
    installPushHandler({ defaultTitle: "Minha App" });
    installNotificationClickHandler();
    ```

    Mantenha o registro do plugin (`virtual:pwa-register`) — **não** chame
    `registerServiceWorker` também: dois registros do mesmo arquivo brigam pelo
    ciclo de update.

=== "c. Já tenho um SW próprio"

    Duas linhas dentro do que já existe, e nada do seu código muda:

    ```ts
    import { installNotificationClickHandler, installPushHandler } from "tempest-react-sdk/sw";

    installPushHandler({ defaultTitle: "Minha App" });
    installNotificationClickHandler();
    ```

    Já tem um `addEventListener("push", …)` seu? Escolha um dos dois: os dois
    handlers rodando mostram **duas** notificações para o mesmo push, porque cada
    listener chama `showNotification`.

    Se você registra o SW por conta própria e quer reusar aquela registration em
    vez do `navigator.serviceWorker.ready`, passe `getRegistration`:

    ```ts
    const registration = await navigator.serviceWorker.register("/sw.js");

    usePushSubscription({
      vapidPublicKey: import.meta.env.VITE_VAPID_PUBLIC_KEY,
      getRegistration: async () => registration,
      onSubscribe: (sub) => api.post("/webpush/subscribe", { body: sub }),
    });
    ```

### 3. O contrato com o backend

O SDK não escolhe rota, verbo nem formato — ele te entrega o
`PushSubscriptionJSON` e você decide. É exatamente isto que chega no
`onSubscribe`:

```json
{
  "endpoint": "https://fcm.googleapis.com/fcm/send/dQw4w9Wg...",
  "expirationTime": null,
  "keys": {
    "p256dh": "BNcRdreALRFXTkOOUHK1EtK2wtaz5Ry4YfYCA_0QTpQtUbVlUls0VJXg7A8u-Ts1XbjhazAkj7I99e8QcYP7DkM=",
    "auth": "tBHItJI5svbpez7KI4CCXg=="
  }
}
```

Duas rotas resolvem o ciclo — e a **chave natural é o `endpoint`**, não o usuário:

| Rota | Quando | Corpo |
| -- | -- | -- |
| `POST /webpush/subscribe` | inscreveu (ou re-sincronizou) | o JSON acima + o usuário logado, vindo do token |
| `DELETE /webpush/subscribe` | desinscreveu | `{ "endpoint": "…" }` |

!!! warning "Um usuário tem N inscrições, uma por navegador"
    Celular, notebook do trabalho, Chrome e Firefox na mesma máquina: cada um é
    uma inscrição com endpoint próprio. Se o backend guarda **uma** inscrição por
    usuário (`UPDATE … WHERE user_id = ?`), cada novo dispositivo desliga o
    anterior em silêncio — o usuário instala no celular e para de receber no
    desktop, sem nada explicando por quê.

    Guarde uma linha por endpoint, com `UNIQUE(endpoint)` e `user_id` indexado.
    O `POST` é **upsert por endpoint**: o mesmo navegador reenviando a mesma
    inscrição (o que acontece a cada `subscribe()` — veja
    [re-sincronização](#o-que-acontece-quando-ja-existe-inscricao)) não pode
    criar linha duplicada.

## Main-thread

### Registrar o SW

```ts
import { registerServiceWorker, skipWaiting } from "tempest-react-sdk";

registerServiceWorker({
  url: "/sw.js",
  onUpdate: (waiting) => {
    if (confirm("Nova versão disponível. Recarregar?")) {
      skipWaiting(waiting);
      window.location.reload();
    }
  },
});
```

!!! tip "Atualização automática (sem `vite-plugin-pwa`)"
    Se você prefere que cada deploy chegue sozinho ao usuário — sem prompt de "recarregar?" — ligue `autoUpdate`. O helper passa a chamar `registration.update()` num intervalo (`updateIntervalMs`, padrão 1h) e recarrega a página assim que um novo worker assume o controle (`controllerchange`), com guarda contra loop de reload. É o comportamento auto-update do `vite-plugin-pwa`, mas implementado direto sobre `navigator.serviceWorker`, sem depender dele:

    ```ts
    import { registerServiceWorker } from "tempest-react-sdk";

    registerServiceWorker({
      url: "/sw.js",
      autoUpdate: true, // poll + reload no controllerchange
      updateIntervalMs: 60 * 60 * 1000, // 1h (padrão)
      reloadOnActivate: true, // padrão; use `false` para só fazer o poll
    });
    ```

    Deixe `reloadOnActivate: false` quando quiser continuar o poll mas controlar o reload você mesmo (ex.: exibir um toast antes).

### Inscrever o usuário (com o hook)

```tsx
import { usePushSubscription, Button } from "tempest-react-sdk";

const push = usePushSubscription({
  vapidPublicKey: import.meta.env.VITE_VAPID_PUBLIC_KEY,
  onSubscribe: (sub) => api.post("/webpush/subscribe", { body: sub }),
  onUnsubscribe: (sub) => api.delete("/webpush/subscribe", { body: { endpoint: sub.endpoint } }),
});

<Button loading={push.loading} onClick={() => push.subscribe()}>
  {push.subscribed ? "Desinscrever" : "Receber notificações"}
</Button>;
```

O hook expõe `supported`, `permission`, `subscribed`, `loading`, `error`, `subscribe()`, `unsubscribe()` e `refresh()`. Versão imperativa: `WebPushClient`. Erros tipados: `WebPushUnsupportedError`, `WebPushPermissionDeniedError`.

#### O que `subscribe()` faz, passo a passo

1. `Notification.requestPermission()` — o prompt do navegador. Recusa lança `WebPushPermissionDeniedError`.
2. Pega a registration (`navigator.serviceWorker.ready`, ou o seu `getRegistration`).
3. **Se já existe inscrição neste navegador, reusa ela** e chama `onSubscribe` de novo.
4. Se não existe, cria com `pushManager.subscribe({ userVisibleOnly: true, applicationServerKey })` e chama `onSubscribe`.

#### O que acontece quando já existe inscrição

O passo 3 é de propósito, e é o que faz o botão servir de **re-sincronização**:
chamar `subscribe()` num navegador que já está inscrito não cria inscrição nova —
reenvia a mesma pro seu backend. Serve pra recuperar o caso em que o banco perdeu
a linha (restore de backup, migration, troca de ambiente) e o navegador continua
inscrito: sem o reenvio, esse dispositivo ficaria inscrito no navegador e
desconhecido no servidor, ou seja, mudo pra sempre.

O preço é do lado do backend: o `POST` **precisa** ser upsert por `endpoint`. Se
for insert cego, o mesmo dispositivo vira duas linhas e o usuário recebe a mesma
notificação duas vezes.

!!! warning "`subscribed` começa `false`, sempre"
    Saber se existe inscrição exige `await pushManager.getSubscription()`, então o
    primeiro render **não pode** saber a resposta: o hook devolve `false` e corrige
    logo depois. Um botão que lê só `subscribed` pisca "Receber notificações" antes
    de virar "Desinscrever".

    Espere o estado assentar antes de decidir o rótulo — `loading` é `false` nesse
    intervalo, então use uma flag própria de "já checou":

    ```tsx
    const push = usePushSubscription({ /* … */ });
    const [checked, setChecked] = useState(false);

    useEffect(() => {
        void push.refresh().finally(() => setChecked(true));
    }, [push.refresh]);

    if (!checked) return <Skeleton height={40} />;
    ```

!!! tip "`refresh()` é pra quando o estado muda fora do seu app"
    O usuário libera ou bloqueia notificação nas **configurações do navegador**, ou
    remove a inscrição em `chrome://settings/content/notifications`, e o seu React
    não fica sabendo — não existe evento pra isso. Chame `refresh()` quando a aba
    volta a ficar visível:

    ```tsx
    useEffect(() => {
        const onVisible = () => {
            if (document.visibilityState === "visible") void push.refresh();
        };
        document.addEventListener("visibilitychange", onVisible);
        return () => document.removeEventListener("visibilitychange", onVisible);
    }, [push.refresh]);
    ```

### Fluxo de permissão e inscrição (exemplo completo)

Este componente mostra o estado completo do ciclo de vida — não suportado, permissão negada, inscrito, alternar — e trata o erro de permissão negada:

```tsx
import { usePushSubscription, WebPushPermissionDeniedError, Button } from "tempest-react-sdk";
import { api } from "./api";

export function PushToggle() {
  const push = usePushSubscription({
    vapidPublicKey: import.meta.env.VITE_VAPID_PUBLIC_KEY,
    onSubscribe: (sub) => api.post("/webpush/subscribe", { body: sub }),
    onUnsubscribe: (sub) =>
      api.delete("/webpush/subscribe", { body: { endpoint: sub.endpoint } }),
  });

  // 1. Browser sem suporte (iOS Safari fora de PWA, navegadores antigos)
  if (!push.supported) {
    return <p>Notificações não são suportadas neste navegador.</p>;
  }

  // 2. Usuário bloqueou nas configurações do navegador
  if (push.permission === "denied") {
    return <p>Permissão de notificação bloqueada. Libere nas configurações do navegador.</p>;
  }

  async function handleSubscribe() {
    try {
      await push.subscribe();
    } catch (err) {
      if (err instanceof WebPushPermissionDeniedError) {
        alert("Você precisa permitir notificações para recebê-las.");
      }
    }
  }

  // 3. Alternar inscrição
  return (
    <Button
      loading={push.loading}
      onClick={() => (push.subscribed ? push.unsubscribe() : handleSubscribe())}
    >
      {push.subscribed ? "Desinscrever" : "Receber notificações"}
    </Button>
  );
}
```

### Desinscrever — o que quase todo mundo erra

`unsubscribe()` faz duas coisas, **nessa ordem**:

1. chama `onUnsubscribe(subscription)` — a sua rota de exclusão;
2. só então chama `subscription.unsubscribe()` no navegador.

A ordem é escolhida: se o backend falhar, a inscrição **continua** no navegador e
o `unsubscribe()` lança. É o lado seguro do erro — o oposto (apagar no navegador
primeiro) perderia o `endpoint`, e sem ele o backend nunca saberia qual linha
apagar. Ficaria mandando push pra um endpoint morto até o push service devolver
`410`.

#### Apague pelo `endpoint`, não pela sessão

```tsx
const push = usePushSubscription({
  vapidPublicKey: import.meta.env.VITE_VAPID_PUBLIC_KEY,
  onSubscribe: (sub) => api.post("/webpush/subscribe", { body: sub }),
  // ✅ o argumento é a inscrição que está saindo — use o endpoint dela
  onUnsubscribe: (sub) => api.delete("/webpush/subscribe", { body: { endpoint: sub.endpoint } }),
});
```

```tsx
// ❌ ignora o argumento: o backend só sabe "algum dispositivo deste usuário saiu"
onUnsubscribe: () => api.delete("/webpush/my"),
```

O segundo padrão só funciona se o usuário tiver **um** dispositivo. Com dois, ou
o backend apaga todos (o celular para de receber porque você desligou no desktop)
ou apaga um qualquer (e o desktop volta a receber sozinho depois). O `endpoint`
é o que identifica o dispositivo — ele está no argumento justamente pra isso.

#### Desinscrever **não** revoga a permissão

`Notification.permission` continua `"granted"` depois do `unsubscribe()`, e não
existe API pra revogar — só o usuário, nas configurações do navegador.

Consequência prática: `permission === "granted"` **não** quer dizer inscrito. Quem
decide o rótulo do botão é `subscribed`; a `permission` só serve pra saber se
ainda dá pra pedir (`"default"`) ou se está bloqueado de fora (`"denied"`). Um
segundo `subscribe()` depois de desinscrever não mostra prompt nenhum — a
permissão já está lá — e volta na hora.

#### Logout e troca de usuário

Este é o furo que aparece em produção, não em teste. A inscrição pertence ao
**navegador**, não ao usuário: se a Ana faz logout e o Bruno entra no mesmo
Chrome, o endpoint continua o mesmo — e continua amarrado à Ana no seu banco. O
Bruno passa a receber as notificações da Ana, no aparelho dele, com o app
mostrando a conta dele.

Desinscreva no logout, **antes** de jogar o token fora:

```ts
// src/stores/auth.ts — ou onde seu logout mora
import { WebPushClient } from "tempest-react-sdk";

async function logout() {
    const push = new WebPushClient({
        vapidPublicKey: import.meta.env.VITE_VAPID_PUBLIC_KEY,
        onSubscribe: () => {},
        onUnsubscribe: (sub) =>
            api.delete("/webpush/subscribe", { body: { endpoint: sub.endpoint } }),
    });

    // Sem token, o DELETE volta 401 e a inscrição fica órfã no banco.
    await push.unsubscribe().catch(() => {
        // Rede caiu: o backend limpa quando o push service devolver 404/410.
    });

    auth.clear();
}
```

!!! tip "Se você não quer perder a permissão conquistada"
    `unsubscribe()` no logout mantém a permissão (veja acima), então o próximo
    login só precisa de um `subscribe()` — sem prompt, instantâneo. Chame no
    sucesso do login, não numa tela de onboarding:

    ```ts
    async function onLoginSuccess() {
        if (Notification.permission === "granted") await push.subscribe();
    }
    ```

    Isso também cobre o dispositivo que ficou meses fora: um `subscribe()` por
    login re-sincroniza o endpoint com o backend sem incomodar ninguém.

!!! warning "Nunca chame `unsubscribe()` em `beforeunload`"
    Fechar a aba não é sair do app — a inscrição existe pra receber push com o
    app **fechado**. Desinscrever ali desliga o push de todo mundo que fecha a
    aba, e o `beforeunload` não espera promise: o `DELETE` provavelmente nem sai.

### Manter a inscrição viva

Uma inscrição não é eterna, e as três formas de ela morrer são silenciosas.

#### `pushsubscriptionchange`: o navegador troca por conta própria

O navegador pode invalidar e recriar a inscrição sozinho — troca de chave interna
do push service, reinstalação do app no Android, tempo. O endpoint muda, o seu
banco continua com o antigo, e o push simplesmente **para de chegar** semanas
depois de tudo funcionar.

O SDK não tem helper pra isso (o evento existe só dentro do worker e ainda tem
suporte irregular). São 15 linhas no seu `sw.ts`:

```ts
/// <reference lib="webworker" />
import { urlBase64ToUint8Array } from "tempest-react-sdk";

declare const self: ServiceWorkerGlobalScope;

const VAPID_PUBLIC_KEY = "BOxx…"; // a mesma do front

self.addEventListener("pushsubscriptionchange", (event: Event) => {
    const change = event as Event & { oldSubscription?: PushSubscription };
    event.waitUntil(
        (async () => {
            const fresh = await self.registration.pushManager.subscribe({
                userVisibleOnly: true,
                applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC_KEY),
            });
            await fetch("/webpush/subscribe", {
                method: "POST",
                headers: { "Content-Type": "application/json" },
                body: JSON.stringify({
                    subscription: fresh.toJSON(),
                    replaces: change.oldSubscription?.endpoint ?? null,
                }),
            });
        })(),
    );
});
```

!!! note "Sem cookie de sessão, o worker precisa de outra forma de autenticar"
    O `fetch` do worker não tem o seu token em memória. Se a sua autenticação é
    por cookie `HttpOnly`, ele vai junto e resolve. Se é `Authorization: Bearer`,
    aceite essa rota pelo `replaces` (o endpoint antigo já identifica o dono) ou
    guarde o token em IndexedDB pra ler aqui.

#### `404`/`410` do push service: apague no backend

Quando o usuário revoga a permissão, limpa os dados do site ou desinstala o PWA,
você não é avisado — o próximo envio devolve `404 Not Found` ou `410 Gone`. Trate
os dois como "apague esta linha", ou a sua tabela cresce de endpoint morto e cada
envio fica mais lento:

```python
# backend (exemplo com pywebpush)
from pywebpush import WebPushException, webpush

try:
    webpush(subscription_info=sub, data=payload, vapid_private_key=KEY, vapid_claims=CLAIMS)
except WebPushException as exc:
    if exc.response is not None and exc.response.status_code in (404, 410):
        subscriptions.delete(endpoint=sub["endpoint"])
    else:
        raise
```

#### Rotação da chave VAPID

Uma inscrição é **assinada** com a chave pública que a criou. Trocar o par VAPID
invalida todas: os envios passam a falhar com `403`.

E tem uma armadilha aqui: como `subscribe()` reusa a inscrição existente, chamar
ele depois de trocar a chave **não** conserta nada — ele reenvia a inscrição
antiga, assinada com a chave velha. O caminho é desinscrever e inscrever de novo:

```ts
await push.unsubscribe(); // limpa navegador + backend
await push.subscribe(); // cria com a chave nova (sem prompt: permissão já é granted)
```

Se você precisa disso pra base inteira, versione a chave no cliente e compare com
a que criou a inscrição:

```ts
const sub = await client.getSubscription();
const current = sub?.options.applicationServerKey; // ArrayBuffer | null
const stale =
    !!current &&
    new Uint8Array(current).toString() !==
        new Uint8Array(urlBase64ToUint8Array(VAPID_PUBLIC_KEY)).toString();

if (stale) {
    await client.unsubscribe();
    await client.subscribe();
}
```

Melhor ainda: **não rotacione**. Guarde o par VAPID como segredo de longo prazo —
ele não identifica usuário nenhum, só o seu servidor.

### Versão imperativa — `WebPushClient`

Quando você precisa do fluxo fora do React (um botão vanilla, um setup script), use a classe direto:

```ts
import { WebPushClient } from "tempest-react-sdk";

const client = new WebPushClient({
  vapidPublicKey: import.meta.env.VITE_VAPID_PUBLIC_KEY,
  onSubscribe: async (sub) => {
    await fetch("/webpush/subscribe", { method: "POST", body: JSON.stringify(sub) });
  },
});

if (WebPushClient.isSupported()) {
  await client.subscribe(); // pede permissão + cria inscrição + chama onSubscribe
}
```

## Worker-thread (`sw.ts`)

Dentro do **seu** service worker, importe os handlers do subpath `tempest-react-sdk/sw`:

```ts
/// <reference lib="webworker" />
import {
  installPushHandler,
  installNotificationClickHandler,
  installSkipWaitingListener,
} from "tempest-react-sdk/sw";

installSkipWaitingListener();

installPushHandler({
  defaultTitle: "Tempest",
  defaultIcon: "/icons/Logo.png",
  transform: (payload) => (payload.tag === "silent-ping" ? null : payload),
});

installNotificationClickHandler();
```

!!! tip "Importe de `tempest-react-sdk/sw`, não do barrel raiz"
    Os helpers de worker têm um subpath dedicado: `tempest-react-sdk/sw`. Ele é
    **puro e sem React** — importar daí mantém o bundle do seu `sw.ts` minúsculo
    (~1 KB) e impede que o grafo de componentes do SDK vaze pro escopo do worker.
    Importar do barrel raiz (`tempest-react-sdk`) também funciona graças ao
    tree-shaking, mas o subpath é a forma à prova de bala. É exatamente o que o
    [`create-tempest-app --pwa`](./scaffold.md#modo-pwa-pwa) gera.

`installPushHandler` tenta `event.data.json()` e cai pra `event.data.text()`. Use `transform` pra suprimir (`null`) ou enriquecer notificações.

`installNotificationClickHandler` foca o client existente quando a URL bate, ou abre nova janela.

!!! tip "Cache offline mora no mesmo módulo"
    `tempest-react-sdk/sw` também exporta `installPrecache` (app shell offline) e
    `installRuntimeCache` (caching por rota: cache-first / network-first /
    stale-while-revalidate). Junto com o plugin `tempestPwaManifest()` de
    `tempest-react-sdk/vite`, dão paridade com o `vite-plugin-pwa` no caso comum
    — sem dependência nova. É o que o
    [`create-tempest-app --pwa`](./scaffold.md#modo-pwa-pwa) já cabeia.

!!! tip "`urlBase64ToUint8Array` e `isPushSupported` são exportados"
    Você raramente os chama na mão — `WebPushClient` já usa os dois internamente
    (`applicationServerKey` exige `Uint8Array`, não a string base64). Eles estão
    no barrel para quem precisa de uma checagem de suporte fora do hook
    (`isPushSupported()`) ou de um fluxo de inscrição 100% customizado — inclusive
    **dentro do worker**, que é o caso do handler de
    [`pushsubscriptionchange`](#pushsubscriptionchange-o-navegador-troca-por-conta-propria).
    A conversão funciona nos dois escopos a partir da **0.28.1**; antes disso ela
    chamava `window.atob` e estourava `ReferenceError` no worker.

    `isPushSupported()` continua sendo main-thread por definição: ele checa
    `window`, então dentro do worker o resultado é sempre `false` — lá o suporte
    já está provado pelo simples fato de o worker estar rodando.

## Inbox na aplicação (`NotificationCenter`)

Um push mostra uma notificação do sistema e depois **desaparece** — no que
depende da sua UI, ele nunca existiu. O usuário que fechou o toast não tem onde
reencontrar aquilo. É a metade que falta do web push: um inbox dentro do app.

O service worker roda **fora** da página e não pode tocar em estado React. A ponte
é uma mensagem:

```ts
// src/sw.ts — dentro do seu handler de push
self.addEventListener("push", (event) => {
    const payload = event.data?.json() ?? {};
    event.waitUntil(
        (async () => {
            await self.registration.showNotification(payload.title, payload);
            const clients = await self.clients.matchAll({ includeUncontrolled: true });
            for (const client of clients) {
                client.postMessage({ type: "tempest:notification", notification: payload });
            }
        })(),
    );
});
```

E, no app, `useNotificationInbox` escuta essa mensagem por default:

```tsx
import { NotificationCenter, useNotificationInbox, Popover, Button } from "tempest-react-sdk";

export function NotificationsButton() {
    const inbox = useNotificationInbox();

    return (
        <Popover
            trigger={
                <Button variant="ghost" aria-label={`Notificações (${inbox.unreadCount} não lidas)`}>
                    🔔 {inbox.unreadCount > 0 && inbox.unreadCount}
                </Button>
            }
        >
            <NotificationCenter
                items={inbox.items}
                onMarkRead={inbox.markRead}
                onMarkAllRead={inbox.markAllRead}
                onDismiss={inbox.remove}
                onSelect={(item) => item.url && navigate(item.url)}
            />
        </Popover>
    );
}
```

### `useNotificationInbox`

| Opção                   | Tipo                                          | Default                   |
| ----------------------- | --------------------------------------------- | ------------------------- |
| `initialItems`          | `NotificationItem[]`                          | `[]`                      |
| `listenToServiceWorker` | `boolean`                                     | `true`                    |
| `messageType`           | `string`                                      | `"tempest:notification"`  |
| `limit`                 | `number`                                      | `100`                     |
| `onChange`              | `(items: NotificationItem[]) => void`         | —                         |

Retorna `{ items, unreadCount, add, markRead, markUnread, markAllRead, remove, clear }`.
Entrada: `{ id, title, body?, receivedAt, read?, url?, data? }`.

!!! info "Filtra por `type`, e isso não é detalhe"
    O canal de mensagens do service worker é **compartilhado** — um ping de
    progresso de sync ou um aviso de cache atualizado passam pelo mesmo lugar.
    Sem filtrar por `type`, tudo isso apareceria no inbox do usuário.

!!! warning "Persistência é decisão sua"
    O hook guarda a lista em memória e nada mais: onde um inbox mora (servidor,
    Dexie, `localStorage`) muda por app, e um default errado seria pior que
    nenhum. Use `onChange` pra escrever e `initialItems` pra ler de volta.

    ```tsx
    const inbox = useNotificationInbox({
        initialItems: restored,
        onChange: (items) => storage.set("inbox", items),
    });
    ```

!!! tip "`limit` existe porque um inbox alimentado por push cresce sem fim"
    Default de 100, os mais antigos caem fora. Aumente se você persiste e pagina.

### `NotificationCenter`

| Prop            | Tipo                                    | Default            |
| --------------- | --------------------------------------- | ------------------ |
| `items`         | `NotificationItem[]`                    | —                  |
| `title`         | `ReactNode` (`null` remove o cabeçalho) | `"Notificações"`   |
| `onSelect`      | `(item: NotificationItem) => void`      | —                  |
| `onMarkRead`    | `(id: string) => void`                  | —                  |
| `onMarkAllRead` | `() => void`                            | —                  |
| `onDismiss`     | `(id: string) => void`                  | —                  |
| `renderIcon`    | `(item: NotificationItem) => ReactNode` | —                  |
| `locale`        | `"pt-BR" \| "en"`                       | `"pt-BR"`          |
| `emptyState`    | `ReactNode`                             | `<EmptyState …/>`  |
| `now`           | `number` (referência dos timestamps)    | agora, no render   |

!!! note "É só o painel, não um popover"
    Monte dentro do seu `Popover`, `Drawer` ou de uma rota própria. Um componente
    que fosse dono do inbox **e** de uma estratégia de posicionamento serviria pra
    menos casos, não mais.

!!! check "Abrir é ler"
    Ativar uma notificação chama `onMarkRead` junto com `onSelect` — senão todo app
    teria que lembrar de chamar os dois, e o contador de não lidas continuaria
    contando algo que o usuário já viu.

!!! tip "Não lida não é só cor"
    A linha ganha barra à esquerda **e** fundo tingido, mais `aria-current="true"`.
    Cor sozinha não sobrevive a monocromia nem a daltonismo.

`renderIcon` casa direto com o subpath de ícones:

```tsx
import { Icon } from "tempest-react-sdk/icons";

<NotificationCenter
    items={inbox.items}
    renderIcon={(item) => <Icon name={(item.data?.icon as string) ?? "bell"} size={16} />}
/>
```

## Compatibilidade

- iOS Safari só funciona quando o app é instalado como PWA (Add to Home Screen) — e o app precisa de `manifest.json` com `display: "standalone"` pra ser instalável. Fora disso, `isPushSupported()` dá `false` no iOS **mesmo no Safari atual**: não é bug seu.
- `usePushSubscription` expõe `supported` — esconda o toggle quando `false`.
- Origem insegura (`http://` que não seja `localhost`) não tem service worker nem Push API.

## Quando não chega notificação: por onde olhar

| Sintoma | Causa provável | Onde confirmar |
| -- | -- | -- |
| `subscribe()` nunca resolve | SW não controla a página (escopo errado, ou nunca registrado) | DevTools → Application → Service workers: `Scope` tem que ser `/` e o status `activated` |
| `supported === false` no iOS | app não está instalado como PWA | Add to Home Screen e abrir pelo ícone |
| Inscreveu, backend não recebeu | `onSubscribe` falhou em silêncio | o `error` do hook; o `subscribe()` re-lança, então trate o `catch` |
| Push some semanas depois | inscrição rotacionada pelo navegador | [`pushsubscriptionchange`](#pushsubscriptionchange-o-navegador-troca-por-conta-propria) |
| Envio devolve `403` | par VAPID trocado, ou a pública do front não é o par da privada do backend | [rotação de chave](#rotacao-da-chave-vapid) |
| Envio devolve `404`/`410` | usuário revogou/limpou dados; endpoint morto | apague a linha ([acima](#404410-do-push-service-apague-no-backend)) |
| Notificação duplicada | dois handlers de `push` no SW, ou `POST` não é upsert por endpoint | o seu `sw.ts`; a tabela de inscrições |
| Usuário recebe notificação de outra conta | não desinscreveu no logout | [logout e troca de usuário](#logout-e-troca-de-usuario) |
| `ReferenceError: window is not defined` no SW | SDK anterior a 0.28.1 usando `urlBase64ToUint8Array` no worker | atualize o SDK |

## Resumo

- **VAPID**: pública no front, privada só no backend. Gere uma vez com `web-push` e **não rotacione** — trocar invalida toda inscrição existente.
- **Você registra o SW**; o hook só assina/desassina sobre uma registration pronta. O arquivo tem que ser servido em `/sw.js` — SW com hash dentro de `/assets/` não controla a sua home, e aí o `subscribe()` fica pendurado sem erro.
- **Num app que já existe**: [três cenários de SW](#2-o-service-worker-tres-cenarios) (nenhum, `vite-plugin-pwa` em `injectManifest`, SW próprio) — em nenhum deles você precisa adotar o resto do SDK.
- **A inscrição é do navegador, não do usuário**: guarde uma linha por `endpoint` (`UNIQUE`), faça upsert no `POST` e **apague pelo `endpoint`** no `DELETE`. Um usuário tem quantos dispositivos quiser.
- **Desinscreva no logout, antes de descartar o token** — senão o próximo usuário do mesmo navegador recebe as notificações do anterior. A permissão sobrevive, então o próximo login re-inscreve sem prompt.
- **`unsubscribe()` não revoga permissão**: `permission === "granted"` não significa inscrito. Quem manda no rótulo do botão é `subscribed`.
- **`subscribed` começa `false`** (a checagem é assíncrona) e `refresh()` existe pro estado que muda fora do app (configurações do navegador).
- **Inscrição morre em silêncio**: trate `pushsubscriptionchange` no worker e apague no backend em `404`/`410`.
- **`usePushSubscription`** dá todo o estado (`supported`/`permission`/`subscribed`/`loading`/`error`) + ações; **`WebPushClient`** é a versão imperativa.
- **Handlers do worker** (`installPushHandler`/`installNotificationClickHandler`/`installSkipWaitingListener`) vão dentro do _seu_ `sw.ts`.
- **iOS** só recebe push em PWA instalado — esconda o toggle quando `!supported`.
- **`useNotificationInbox` + `NotificationCenter`** fecham o ciclo: o worker faz `postMessage`, o hook guarda a lista (filtrando por `type`, com `limit`) e o painel mostra lida/não lida com ação por item. Persistência fica com o app, via `onChange`/`initialItems`.

### Veja também

- [HTTP](./http.md) — transporte das inscrições para o backend
- Diagrama: [push-flow.drawio](./diagrams/push-flow.drawio)

---

# pwa.md

# PWA & Offline-First

O `tempest-react-sdk` traz tudo que um app Tempest precisa pra virar um **PWA offline-first** — sem depender de Workbox nem de `vite-plugin-pwa`. Esta página é o mapa: registro e atualização do service worker, cache, sincronização em background, durabilidade do armazenamento e a UI de status. O **motor de sincronização** (`createOfflineSync`) tem sua própria receita em [Offline Sync (FastAPI)](./offline-sync.md) — aqui cobrimos a camada PWA ao redor dele.

!!! info "As peças"
    | Camada | O que faz | Onde roda |
    | -- | -- | -- |
    | `tempest-react-sdk/vite` | gera manifest, ícones, SW de dev | build (Vite) |
    | `tempest-react-sdk/sw` | precache, cache runtime, background sync | dentro do `sw.ts` |
    | hooks + componentes | update, status, quota, indicadores | main thread (React) |

## 1. Registrar o service worker e atualizar com consentimento

`registerServiceWorker` cuida do `register()` + detecção de update. Para o fluxo **guiado pelo usuário** ("Nova versão — atualizar"), use o hook `useServiceWorkerUpdate` com o componente `<UpdatePrompt>`:

```tsx
import { useServiceWorkerUpdate, UpdatePrompt } from "tempest-react-sdk";

export function ServiceWorkerGate() {
  const { updateAvailable, applyUpdate } = useServiceWorkerUpdate({ url: "/sw.js" });
  return <UpdatePrompt open={updateAvailable} onUpdate={applyUpdate} />;
}
```

Quando um worker novo termina de instalar, `updateAvailable` vira `true`; `applyUpdate()` ativa o worker em espera (`skipWaiting`) e recarrega a página assim que ele assume o controle.

!!! tip "Deixe `autoUpdate` desligado aqui"
    `useServiceWorkerUpdate` existe para dar a decisão de recarregar ao usuário. Se você quer recarga silenciosa, use `registerServiceWorker({ url, autoUpdate: true })` direto, sem o hook.

## 2. Precache + cache runtime + navigation preload

Dentro do seu `sw.ts`, registre as rotas específicas **antes** do precache (para vencerem o catch-all):

```ts
/// <reference lib="webworker" />
import { installRuntimeCache, installPrecache } from "tempest-react-sdk/sw";

installRuntimeCache([
  { match: /\/api\//, strategy: "network-first", cacheName: "api", maxAgeSeconds: 300 },
  { match: /\.(png|jpg|webp)$/, strategy: "cache-first", cacheName: "img", maxEntries: 60 },
]);

installPrecache(); // app shell + navegação offline
```

`installPrecache` liga a **Navigation Preload API** no `activate` por padrão (`navigationPreload: true`): o navegador começa a buscar a navegação em paralelo com o boot do worker e o handler serve `event.preloadResponse`, cortando a latência da primeira navegação depois que o worker sobe.

!!! note "De onde vem o manifest"
    `installPrecache` lê `precache-manifest.json`, emitido pelo plugin `tempestPwaManifest()` do subpath `tempest-react-sdk/vite`. Veja [Vite config](./vite-config.md).

!!! warning "Deploy em subpath (GitHub Pages e afins)"
    O `tempestPwaManifest()` prefixa as URLs com o `base` do Vite, mas o `installPrecache` roda no worker e **não** enxerga essa config. Se o seu `base` não é `/`, aponte as duas opções de caminho para dentro dele:

    ```ts
    installPrecache({
      manifestUrl: "/meu-app/precache-manifest.json",
      navigateFallback: "/meu-app/index.html",
    });
    ```

    Com os defaults (`/precache-manifest.json` e `/index.html`), o worker instala, busca um manifest que responde 404 e a navegação offline nunca resolve.

## 3. Background sync + periodic sync

`installBackgroundSync` enfileira mutações (`POST`/`PUT`/`PATCH`/`DELETE`) que falham offline e as reenvia quando a rede volta — via Background Sync API, com fallback oportunista para navegadores sem ela (Safari).

```ts
import { installBackgroundSync } from "tempest-react-sdk/sw";

installBackgroundSync({ match: (url) => url.pathname.startsWith("/api/") });
```

Para reenviar mesmo **sem uma navegação nova**, registre um *periodic sync* na main thread. O SW já escuta o evento `periodicsync`:

```ts
import { registerPeriodicSync } from "tempest-react-sdk/sw";

const registration = await navigator.serviceWorker.ready;
await registerPeriodicSync({ registration, minIntervalMinutes: 360 });
```

`registerPeriodicSync` checa a permissão `periodic-background-sync` primeiro e retorna `false` quando indisponível (Chrome-only) — chamar sempre é seguro.

## 4. Durabilidade: peça armazenamento persistente

Sem `navigator.storage.persist()`, o navegador pode **despejar** o IndexedDB e o Cache Storage sob pressão de disco — fatal pra dados offline. `useStorageEstimate` mostra uso/quota e expõe a ação de tornar o armazenamento permanente:

```tsx
import { useStorageEstimate } from "tempest-react-sdk";

function StorageMeter() {
  const { usage, quota, ratio, persisted, requestPersist } = useStorageEstimate();
  return (
    <div>
      <progress value={ratio ?? 0} />
      <span>
        {((usage ?? 0) / 1e6).toFixed(1)} de {((quota ?? 0) / 1e6).toFixed(0)} MB
      </span>
      {!persisted && <button onClick={requestPersist}>Tornar permanente</button>}
    </div>
  );
}
```

Fora do React, use as funções puras `estimateStorage()` e `requestPersistentStorage()`.

## 5. Observabilidade do cache

Para um readout "X MB cacheado" ou um "limpar cache" no logout, use os helpers de main thread:

```ts
import { inspectCaches, clearCaches } from "tempest-react-sdk/sw";

const reports = await inspectCaches({ filter: "tempest-" });
const totalMb = reports.reduce((n, r) => n + (r.bytes ?? 0), 0) / 1e6;

await clearCaches("tempest-"); // no logout
```

`inspectCaches` mede bytes por padrão (lendo cada resposta); passe `measureBytes: false` para um relatório rápido só de contagem.

## 6. UI de status offline

Dois componentes prontos, guiados por `useOnline` e pelo motor de sync:

```tsx
import { OfflineIndicator, SyncStatusBadge, useSyncStatus } from "tempest-react-sdk";
import { notesSync } from "@/sync/engine";

function StatusBar() {
  const { tone, pending } = useSyncStatus(notesSync);
  return (
    <>
      <OfflineIndicator position="top" />
      <SyncStatusBadge tone={tone} pending={pending} />
    </>
  );
}
```

- **`<OfflineIndicator>`** — barra fixa que aparece offline e pisca uma confirmação ao reconectar. Não renderiza nada online, então é seguro montar na raiz do app.
- **`<SyncStatusBadge>`** — pílula com ícone + label + contagem de pendências, alimentada por `useSyncStatus(sync).tone`.

## 7. Hooks reativos do motor de sync

`useOfflineSync` inscreve um componente no `OfflineSync` e opcionalmente dispara flush no mount, no evento `online` e num intervalo:

```tsx
import { useOfflineSync } from "tempest-react-sdk";
import { notesSync } from "@/sync/engine";

function useNotesSync() {
  return useOfflineSync(notesSync, { flushOnMount: true, intervalMs: 30_000 });
  // → { phase, pending, syncing, lastSummary, lastError, lastSyncedAt, enqueue, flush }
}
```

Para mutações **otimistas** que gravam no outbox e atualizam o cache do TanStack Query (com rollback em falha), use `useOfflineMutation` — veja [Query](./query.md#useofflinemutation).

## 8. Resolução de conflitos

O pull sobrescreve o registro local pela versão do servidor. Quando precisar de uma política explícita dentro do `applyRemote`, os helpers cobrem os dois casos comuns (empate → remoto vence):

```ts
import { lastWriteWins, higherVersionWins } from "tempest-react-sdk";

applyRemote: async (dto) => {
  const local = await store.get(dto.id);
  await store.save(lastWriteWins(local, dto, (r) => r.updatedAt));
};
```

## Recap

- **`useServiceWorkerUpdate` + `<UpdatePrompt>`** dão o fluxo de atualização com consentimento. ✅
- **`installPrecache`** liga navigation preload; **`installRuntimeCache`** cobre as estratégias Workbox-like.
- **`installBackgroundSync`** + **`registerPeriodicSync`** reenviam mutações offline, com ou sem navegação nova.
- **`useStorageEstimate`** + **`requestPersistentStorage`** evitam o despejo do IndexedDB.
- **`inspectCaches`/`clearCaches`** dão visibilidade e limpeza do cache.
- **`<OfflineIndicator>` / `<SyncStatusBadge>` / `useOfflineSync` / `useSyncStatus`** montam a UI de status reativa. 🚀

---

# query.md

# Query (TanStack Query)

Wrappers finos pra padronizar tempos de cache, chaves de query e o `QueryClient`. Você continua usando o `@tanstack/react-query` de sempre — o SDK só entrega os defaults bem calibrados e um factory de keys tipado.

!!! info "Por que esses wrappers existem?"
    Sem padronização, cada tela escolhe um `staleTime` no chute e cada domínio escreve `queryKey: ["user", id]` à mão. Isso gera invalidações que não pegam (key montada diferente em dois lugares) e refetch agressivo demais. O SDK centraliza ambos: presets nomeados e um factory que garante a mesma key em todo lugar.

## Provider

Envolva a árvore do app uma única vez, normalmente no `main.tsx` (ou dentro de `<AppProviders>`):

```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { QueryProvider } from "tempest-react-sdk";
import "tempest-react-sdk/styles.css";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <QueryProvider>
      <App />
    </QueryProvider>
  </StrictMode>,
);
```

Defaults aplicados quando você **não** passa um `client`:

- `staleTime`: 5 min (`STALE_TIME.DEFAULT`)
- `gcTime`: 30 min (`CACHE_TIME.DEFAULT`)
- `retry`: `shouldRetryQuery` (queries) / 0 (mutations)
- `refetchOnWindowFocus`: false

!!! danger "4xx **não** é retentado — e isso mudou"
    O default era `retry: 1` chapado, que replicava um 403 numa listagem admin-only e um 404 de registro apagado. O servidor recusou de propósito nos dois casos: a segunda tentativa devolve a mesma resposta, dobra o log de rede e segura o spinner na tela por mais um round trip.

    `shouldRetryQuery` retenta uma vez apenas o que pode mudar sozinho: falha de rede (`status === 0`), `5xx`, `408`, `425` e `429` (que é uma recusa cujo significado literal é "mais tarde"), e erro de formato desconhecido — que pode ser falha de transporte. Todo o resto do 4xx falha de primeira.

    A classificação vem de `isRetriableStatus`, a mesma que `createApiClient({ retry: true })` e o helper `retry()` usam. Até a v0.44.0 era uma cópia própria aqui, **sem o `425`** — então o mesmo `425 Too Early` era retentado pelo cliente e não pela query.

    Se o seu app dependia de retry em 4xx, o override é o de sempre: `defaultOptions={{ queries: { retry: 1 } }}`.

Para sobrescrever, passe `defaultOptions` (mesclado por cima dos defaults) ou um `client` pronto (ignora os defaults do SDK):

```tsx
import { QueryClient } from "@tanstack/react-query";
import { QueryProvider, STALE_TIME } from "tempest-react-sdk";

// Opção A — só ajustar alguns defaults
<QueryProvider defaultOptions={{ queries: { staleTime: STALE_TIME.LONG } }}>
  <App />
</QueryProvider>;

// Opção B — trazer seu próprio client (compartilhar entre roots, plugar devtools, etc.)
const client = new QueryClient();
<QueryProvider client={client}>
  <App />
</QueryProvider>;
```

!!! warning "Um único `QueryClient` por app"
    Não aninhe dois `QueryProvider` sem passar o mesmo `client`. Cada provider cria um cache isolado, e queries de subárvores diferentes deixam de compartilhar dados. Para múltiplos roots, crie o `QueryClient` uma vez e passe via prop `client`.

!!! danger "\"No QueryClient set\" com o provider montado = duas cópias do react-query"
    O `client` que você passa é o único ponto onde a cópia do app e a do SDK se encostam. Se o `npm` aninhou uma segunda cópia de `@tanstack/react-query` dentro do SDK, o `QueryClientProvider` publica o seu client no contexto **daquela** cópia — e todo `useQuery` do app lê o contexto da outra, não acha nada, e lança:

    ```text
    No QueryClient set, use QueryClientProvider to set one
    ```

    Com o provider visivelmente montado três linhas acima. Nada nessa mensagem aponta pra duplicata, e é por isso que ela custa uma tarde.

    A partir da v0.52.1 o SDK detecta e avisa em desenvolvimento: um client de outra cópia faz duck-type perfeito mas falha o `instanceof`, que é a discriminação exata. O conserto é `npm dedupe`, e `npx tempest doctor` lista toda dependência duplicada.

## Presets de tempo

```ts
import { useQuery } from "@tanstack/react-query";
import { STALE_TIME, CACHE_TIME, REFETCH_TIME } from "tempest-react-sdk";

useQuery({
  queryKey: ["dashboard"],
  queryFn: fetchDashboard,
  staleTime: STALE_TIME.LONG, // 30 min — dado muda pouco
  gcTime: CACHE_TIME.LONG, // 1 h
  refetchInterval: REFETCH_TIME.FAST, // 30 s — polling de status
});
```

- `STALE_TIME`: `SHORT` 30s, `DEFAULT` 5min, `LONG` 30min, `INFINITE` ∞
- `CACHE_TIME`: `SHORT` 5min, `DEFAULT` 30min, `LONG` 1h
- `REFETCH_TIME`: `REALTIME` 5s, `FAST` 30s, `DEFAULT` 60s, `SLOW` 5min

!!! tip "Quando usar `INFINITE`"
    `STALE_TIME.INFINITE` marca o dado como nunca obsoleto — o TanStack só refaz o fetch via invalidação manual. Ideal para listas estáticas (categorias, cidades) que mudam por deploy, não por uso.

## Query keys tipadas

`createQueryKeys` recebe um `scope` (prefixo do domínio) e um mapa de builders. Cada saída já vem com o scope na frente, então a mesma key é montada de forma idêntica em toda a base de código:

```ts
import { createQueryKeys } from "tempest-react-sdk";

export const userKeys = createQueryKeys("user", {
  me: () => ["me"] as const,
  byId: (id: string) => [id] as const,
  list: (filters: { page: number; size: number }) => ["list", filters] as const,
});

userKeys.all; // ["user"]
userKeys.me(); // ["user", "me"]
userKeys.byId("42"); // ["user", "42"]
userKeys.list({ page: 1, size: 20 }); // ["user", "list", { page: 1, size: 20 }]
```

Note o `all`: ele é gerado automaticamente e é a key mais ampla do domínio — invalidá-lo derruba todas as queries `user/*` de uma vez.

## Exemplo completo — query + mutation + invalidação

Esse componente lê o perfil com `useQuery`, atualiza com `useMutation` e invalida só as keys afetadas no sucesso:

```tsx
import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
import { createApiClient, createQueryKeys } from "tempest-react-sdk";

interface User {
  id: string;
  name: string;
}

const api = createApiClient({ baseURL: import.meta.env.VITE_API_URL });

export const userKeys = createQueryKeys("user", {
  me: () => ["me"] as const,
  byId: (id: string) => [id] as const,
});

export function ProfileCard() {
  const queryClient = useQueryClient();

  const { data: user, isLoading } = useQuery({
    queryKey: userKeys.me(),
    queryFn: () => api.get<User>("/users/me"),
  });

  const rename = useMutation({
    mutationFn: (name: string) => api.patch<User>("/users/me", { body: { name } }),
    onSuccess: (updated) => {
      // Atualiza o cache local sem novo fetch...
      queryClient.setQueryData(userKeys.me(), updated);
      // ...e invalida o registro por id, caso outra tela o use.
      queryClient.invalidateQueries({ queryKey: userKeys.byId(updated.id) });
    },
  });

  if (isLoading) return <p>Carregando…</p>;

  return (
    <div>
      <h2>{user?.name}</h2>
      <button disabled={rename.isPending} onClick={() => rename.mutate("Novo nome")}>
        Renomear
      </button>
    </div>
  );
}
```

!!! note "Por que `setQueryData` + `invalidateQueries`?"
    `setQueryData` aplica a resposta da mutation no cache imediatamente (UI sem flicker), enquanto `invalidateQueries` marca queries _relacionadas_ como obsoletas pra revalidar no background. Usar uma key factory garante que a key invalidada seja exatamente a mesma que a query consultou.

Padrão de organização: cada domínio em `src/constants/query-keys/<dominio>.ts`, agrupados num barrel.

## `useOfflineMutation`

Quando o app é offline-first, uma mutation não deve bater na rede direto — ela grava no **outbox** do [`createOfflineSync`](./offline-sync.md) e sincroniza depois. `useOfflineMutation` faz a ponte entre o motor de sync e o TanStack Query: no `mutate` ele enfileira a entrada, **atualiza o cache da query otimisticamente**, dá o **flush** e faz **rollback** do cache se o enqueue falhar.

```tsx
import { useOfflineMutation } from "tempest-react-sdk";
import { notesSync } from "@/sync/engine";
import type { Note } from "@/sync/types";

function useAddNote() {
  return useOfflineMutation<Note, Note[], Note>({
    sync: notesSync,
    queryKey: ["notes"],
    toEntry: (note) => ({ op: "create", recordId: note.id, payload: note }),
    applyOptimistic: (current = [], note) => [...current, note],
  });
}

// const addNote = useAddNote();
// addNote.mutate({ id: crypto.randomUUID(), text: "offline!" });
```

- `toEntry` mapeia as variáveis pra `{ op, recordId, payload }` do outbox.
- `applyOptimistic` produz o próximo valor do cache; o anterior é restaurado se o enqueue lançar.
- `flush` (default `true` → `"after-mutation"`) dispara a sincronização; `false` deixa isso pro `useOfflineSync`.
- `invalidate` (default `false`) revalida a `queryKey` no `onSettled`.

!!! tip "Helpers de cache de lista"
    Para o caso comum (cache é uma lista), use `upsertById()` / `removeById()` no lugar de escrever o spread na mão:

    ```ts
    import { upsertById, removeById } from "tempest-react-sdk";

    applyOptimistic: upsertById(); // insere ou faz merge por `id`
    applyOptimistic: removeById(); // remove por `id` (op "delete")
    // campo custom: upsertById("uuid")
    ```

!!! tip "A entrega ao servidor acontece no flush"
    O `mutate` resolve com o **id da entrada no outbox**, não com a resposta do servidor — a entrega real roda no loop de flush do motor, então a UI atualiza na hora e sobrevive a reloads e a períodos offline.

## `persistQueryClientOffline`

Persiste o cache do `QueryClient` no IndexedDB e restaura no boot — um reload ou início offline mostra os últimos dados conhecidos em vez de telas vazias. Self-contained: usa `dehydrate`/`hydrate` do próprio `@tanstack/react-query`, sem precisar do `@tanstack/react-query-persist-client`.

```ts
import { persistQueryClientOffline } from "tempest-react-sdk";
import { queryClient } from "@/lib/query";

const persistence = persistQueryClientOffline({ queryClient });
await persistence.restore(); // antes do primeiro render

// no logout:
await persistence.clear();
// no teardown:
persistence.unsubscribe();
```

As gravações são throttled (`throttleMs`, default 1s) e assinam o cache. `flush()` grava na hora; `clear()` apaga o snapshot; `unsubscribe()` para de persistir. Dexie é peer dependency do store offline — instale (`npm i dexie`).

## Recap

- `<QueryProvider>` na raiz — um por app — entrega defaults calibrados; sobrescreva via `defaultOptions` ou `client`.
- `STALE_TIME` / `CACHE_TIME` / `REFETCH_TIME` substituem números mágicos por presets nomeados.
- `createQueryKeys(scope, builders)` gera keys tipadas e consistentes, com um `all` automático pra invalidação ampla.
- Combine `setQueryData` (resposta imediata) com `invalidateQueries` (revalidação) usando a mesma key factory.
- `useOfflineMutation` liga o motor offline ao cache: enqueue + optimistic update + flush + rollback.

## Veja também

- [HTTP](./http.md) — o `createApiClient` que alimenta as `queryFn`
- [Offline](./offline.md) — combinar com `initialData` pra fallback offline
- [PWA & Offline-First](./pwa.md) — service worker, background sync, status UI

---

# release.md

# Release pipeline

Como o `tempest-react-sdk` é publicado no npm — workflow tag-push automático, com fallback manual.

## Visão geral

```text
Local:                                  GitHub Actions:
  make release TAG=X.Y.Z
       │
       ▼
  ┌─────────────────────────┐
  │ scripts/release.sh:     │
  │  1. branch release/vTAG │
  │  2. npm version TAG     │
  │  3. fecha o CHANGELOG   │
  │     ([Unreleased] →     │
  │      [TAG] — data)      │
  │  4. validate (lint +    │
  │     format + typecheck  │
  │     + test + build)     │
  │  5. commit + tag local  │
  │  6. push branch + tag   │──────────► tag push triggers
  │  7. abre PR via gh      │            .github/workflows/release-npm.yml
  └─────────────────────────┘                     │
                                                  ▼
                                       ┌────────────────────────────┐
                                       │ 1. Checkout @ tag          │
                                       │ 2. tag == package.json?    │
                                       │ 3. Lint + format-check     │
                                       │ 4. Typecheck               │
                                       │ 5. Tests (vitest)          │
                                       │ 6. Build (vite + dts)      │
                                       │ 7. Smoke install           │
                                       │ 8. npm publish             │
                                       │    --provenance            │
                                       │ 9. read-back: registry     │
                                       │    serve a versão e o      │
                                       │    dist-tag latest bate?   │
                                       │ 10. GitHub Release da tag  │
                                       │     (notas = CHANGELOG,    │
                                       │      tarball anexado)      │
                                       └────────────────────────────┘
```

**As três superfícies andam juntas**: a git tag, a versão no npm e o GitHub
Release. O workflow falha se a tag não descrever a versão do `package.json`, e
falha se o registry não estiver servindo a versão como `latest` — então "workflow
verde" significa de fato "publicado e visível".

Tag push é a **única** forma de publicar. Não há "publish via PR merge" — o merge do release PR é apenas para sincronizar `main` com `package.json` + `RELEASES.md` atualizados.

## Comandos

### `make release TAG=0.1.5`

Pipeline completo. Requer working tree limpo + tag inexistente local/remoto.

Bloqueia se `CHANGELOG.md` não mencionar `[TAG]` ou `[Unreleased]` (com prompt para forçar continuação).

### `make release TAG=0.1.5 DRY_RUN=1`

Idêntico, mas para antes do push — você inspeciona a branch e o tag locais antes de continuar manualmente:

```bash
git push -u origin release/v0.1.5
git push origin v0.1.5
gh pr create --base main --head release/v0.1.5 --title "chore: release v0.1.5"
```

### `make release TAG=0.1.5 SKIP_VALIDATE=1`

Pula a validação local (`npm ci`, lint, format-check, typecheck, test, build, pack dry-run). Use apenas em emergências — o CI vai validar novamente do zero.

### `make validate`

Roda toda a validação local sem fazer release. Equivalente ao bloco de validação do CI.

### `make publish`

Fallback manual. Requer `NPM_TOKEN` no `~/.npmrc` (token com bypass 2FA) ou `npm login` interativo. **Não dispara workflow** — publish direto.

```bash
npm config set //registry.npmjs.org/:_authToken=npm_xxx... --location=user
npm run build
make publish
```

Sem token com bypass 2FA, npm exige OTP:

```bash
npm publish --access public --otp=123456
```

### `make releases`

Lista todas as tags `v*.*.*` ordenadas por versão (mais recentes primeiro).

### `make releases-md`

Regenera `RELEASES.md` a partir das git tags. Chamado automaticamente pelo `scripts/release.sh` após criar a tag.

### `make releases-check`

Relatório de sincronia das três superfícies — uma linha por git tag, dizendo se a versão existe no npm e se a tag tem GitHub Release:

```text
TAG          NPM      RELEASE  STATUS
v0.24.0      ok       ok       sincronizado
v0.23.0      ok       FALTA    DESSINCRONIZADO
```

Só leitura, seguro de rodar sempre. Use antes e depois de um release.

### `make releases-sync` / `make releases-sync-dry`

Cria os **GitHub Releases faltantes** para tags que já existem (backfill), com as notas vindas da seção correspondente do `CHANGELOG.md`. Tags que já têm Release são puladas — o script é idempotente e nunca reescreve um Release existente.

```bash
make releases-sync-dry   # lista o que faria, sem criar nada
make releases-sync       # cria de verdade
```

Necessário porque o publish no npm e a criação do Release passaram a andar juntos só a partir da v0.24.0: as tags anteriores existiam no git e no npm, mas sem Release no GitHub.

!!! info "Notas de um backfill nunca herdam `[Unreleased]`"
    O `scripts/changelog.mjs notes <versão>` só cai no bloco `[Unreleased]` quando recebe `--allow-unreleased` (o que o workflow faz, para o caso de um release cortado antes de datar a seção). No backfill a flag **não** é passada — assim uma tag antiga nunca recebe as notas do ciclo seguinte; sem seção, o Release sai com um ponteiro para o `CHANGELOG.md`.

## CI workflow (`.github/workflows/release-npm.yml`)

Disparado por:

- **`push: tags: [v*.*.*]`** — fluxo principal. `make release TAG=X` push uma tag e o workflow dispara automaticamente.
- **`workflow_dispatch`** — manual via `gh workflow run release-npm.yml --ref main`. Útil quando o publish de uma tag falhou e você quer re-rodar sem incrementar versão.

Passos do job `publish`:

1. **Checkout** (`actions/checkout@v5`) com `fetch-depth: 0`.
2. **Node 22** + `registry-url: https://registry.npmjs.org` + cache npm, e `npm install -g npm@latest` (Trusted Publishing exige npm >= 11.5.1).
3. **Guard de versão** — compara a tag (`GITHUB_REF_NAME` sem o `v`) com o `version` do `package.json` e **aborta** se divergirem, antes de qualquer publish. Também deriva `prerelease` (versão com `-`) para marcar o Release corretamente. Em `workflow_dispatch` a tag é derivada do `package.json`.
4. **`npm ci`**.
5. **Lint** (`npm run lint`).
6. **Format check** (`npm run format:check`).
7. **Typecheck** (`npm run typecheck`).
8. **Tests** (`npm run test:run`).
9. **Build** (`npm run build`).
10. **Smoke install** — gera tarball via `npm pack`, instala em `/tmp/sdk-smoke` com `react@^19 react-dom@^19` (as demais deps vêm como dependências diretas do pacote), importa o pacote dinamicamente e valida que 20 exports core estão presentes.
11. **`npm publish --provenance --access public`** via **Trusted Publishing (OIDC)** — sem `NPM_TOKEN`. `id-token: write` é o que permite o attestation de provenance no sigstore.
12. **Read-back do registry** — confirma que o npm serve `tempest-react-sdk@<versão>` (com até 5 tentativas, porque o registry demora a propagar) **e** que `dist-tags.latest` aponta para ela. Falha o job caso contrário: publish que aterrissou em outra tag deixaria de parecer verde.
13. **GitHub Release** — `gh release create <tag>` com o tarball anexado e as notas extraídas da seção do `CHANGELOG.md` (`scripts/changelog.mjs notes <versão> --allow-unreleased`), acrescidas do link para a versão no npm. Se o Release já existe, faz `gh release edit` + `upload --clobber` em vez de falhar, então re-rodar o workflow para a mesma tag é seguro. Exige `contents: write` no job.

## Segredos necessários no GitHub

**Nenhum.** O publish usa **Trusted Publishing** do npm: o `npm publish` troca a identidade OIDC do GitHub Actions por um token de vida curta, então não existe `NPM_TOKEN` no repositório. O que precisa estar configurado é um **Trusted Publisher** em npmjs.com apontando para este repositório + o arquivo `release-npm.yml`.

O `GITHUB_TOKEN` (usado para criar o Release) é fornecido automaticamente pelo Actions runtime — só o `permissions: contents: write` do job precisa estar declarado, e está.

!!! warning "O `NPM_TOKEN` continua sendo assunto do fallback local"
    `make publish` publica da sua máquina e aí sim precisa de token no `~/.npmrc` (Classic Automation, ou Granular com "Allow bypass 2FA" marcado). Esse caminho **não** gera provenance e **não** cria o GitHub Release — se você usar o fallback, rode `make releases-sync` depois para o Release não ficar faltando.

## Provenance signing

O publish inclui `--provenance` quando rodado no CI. Isso requer:

- `permissions: id-token: write` no workflow (já configurado).
- npm >= 11.5.1 no runner (o step de upgrade cuida disso).
- Um Trusted Publisher configurado no npmjs.com para este repositório.

O resultado: cada versão publicada carrega um attestation assinado pelo sigstore, ligando o tarball ao commit + workflow run que o produziram. Visível no [registry](https://www.npmjs.com/package/tempest-react-sdk) como badge "Verified provenance".

Publish manual local **não** consegue provenance — não há OIDC provider fora do CI. `make publish` sempre roda sem `--provenance`.

## Histórico

Veja [`RELEASES.md`](https://github.com/mauriciobenjamin700/tempest-react-sdk/blob/main/RELEASES.md) (auto-gerado via `make releases-md`) e [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-react-sdk/blob/main/CHANGELOG.md) (escrito à mão antes de cada release).

## Veja também

- [`CHANGELOG.md`](https://github.com/mauriciobenjamin700/tempest-react-sdk/blob/main/CHANGELOG.md) — registro de mudanças por versão
- [`RELEASES.md`](https://github.com/mauriciobenjamin700/tempest-react-sdk/blob/main/RELEASES.md) — tabela de tags com data e commit
- [`Makefile`](https://github.com/mauriciobenjamin700/tempest-react-sdk/blob/main/Makefile) — definição dos alvos
- [`scripts/release.sh`](https://github.com/mauriciobenjamin700/tempest-react-sdk/blob/main/scripts/release.sh) — script bash do pipeline

---

# resumable-upload.md

# Upload resumível (tus)

`uploadWithProgress` faz **uma** request. Isso funciona até o arquivo ficar grande: um áudio de 40 minutos gravado com `useAudioRecorder`, um vídeo, um dump. Aí um 4G que oscila por três segundos joga fora 300 MB já enviados, e recarregar a página joga fora tudo de novo.

`createResumableUpload` divide o arquivo em chunks, guarda onde parou e continua — depois de uma queda de rede **ou** de um reload.

!!! info "Protocolo: tus 1.0.0, não um esquema nosso"
    O cliente fala [tus](https://tus.io) (core + as extensões *creation* e *termination*). Isso é deliberado: um cliente resumível de formato próprio obriga o backend a ser sempre nosso. Com tus você pode apontar para `tusd`, `tus-node-server` ou `py-tus` sem escrever servidor nenhum — e a seção [O que o backend precisa implementar](#o-que-o-backend-precisa-implementar) cabe numa tabela.

## O exemplo mínimo

```tsx
import { createResumableUpload, type ResumableUpload } from "tempest-react-sdk";
import { useRef, useState } from "react";

export function EnviarGravacao({ file }: { file: File }) {
  const upload = useRef<ResumableUpload | null>(null);
  const [percent, setPercent] = useState(0);
  const [state, setState] = useState("idle");

  async function start() {
    upload.current ??= createResumableUpload({
      endpoint: "/api/uploads",
      file,
      metadata: { filename: file.name },
      onProgress: ({ fraction }) => setPercent(Math.round(fraction * 100)),
      onStateChange: setState,
    });

    const done = await upload.current.start();
    if (done) await fetch(`/api/gravacoes?url=${encodeURIComponent(done.url)}`, { method: "POST" });
  }

  return (
    <>
      <progress value={percent} max={100} />
      <button type="button" onClick={() => void start()}>Enviar</button>
      <button type="button" onClick={() => upload.current?.pause()}>Pausar</button>
      <button type="button" onClick={() => void upload.current?.resume()}>Continuar</button>
      <button type="button" onClick={() => void upload.current?.abort({ discard: true })}>
        Cancelar
      </button>
      <p>{state}</p>
    </>
  );
}
```

O que acontece: um `POST` cria o upload, uma sequência de `PATCH` empurra 5 MiB por vez, `onProgress` recebe cada tick de bytes, e no fim `start()` resolve com `{ url, size }` — a URL tus, que você grava junto do registro.

!!! tip "`start()` resolve `null` quando você pausou ou cancelou"
    Só uma **falha** rejeita. `pause()` e `abort()` não são falhas, então a promessa resolve `null` e você não precisa de `try/catch` em volta de um botão de pausar.

## Estados

`upload.state` (e o `onStateChange`) passa por:

| Estado | Significado |
| --- | --- |
| `idle` | Nada começou |
| `creating` | O `POST` de criação está em voo |
| `uploading` | Chunks indo |
| `paused` | `pause()` — o ponto de retomada **fica** guardado |
| `done` | Terminou; o registro persistido foi apagado |
| `error` | As tentativas acabaram; `start()` rejeitou |
| `aborted` | `abort()` — com `discard: true`, o registro foi apagado |

## Retomar depois de um reload

É o motivo de existir. O cliente guarda `{ url, offset, size, idempotencyKey }` sob uma **chave de retomada** e, no próximo `start()`, reencontra o upload:

```ts
const upload = createResumableUpload({ endpoint: "/api/uploads", file });
// Recarregou a página, o usuário escolheu o mesmo arquivo, chamou start() de novo:
// → HEAD no upload antigo, offset volta em 312 MB, os PATCH continuam de lá.
```

A chave padrão é uma impressão digital de `endpoint + nome + tamanho + tipo + lastModified` — o mesmo critério dos clientes tus de referência. Barato (não hasheia 400 MB) e muda sempre que o arquivo muda, que é a propriedade importante: retomar dentro do arquivo errado corromperia os dois.

!!! warning "Um `Blob` sem nome tem impressão digital fraca"
    `Blob` não tem `name` nem `lastModified`, então dois blobs do mesmo tamanho e tipo colidem. Passe `key` explícito quando o que você envia não é um `File`.

### Onde o estado mora

Por padrão, `localStorage`, via `createLocalUploadStorage()`. **Não** IndexedDB, e isso é escolha: o registro tem quatro campos e uma URL, o requisito é só sobreviver a um reload, e puxar Dexie pra isso colocaria IndexedDB no bundle de todo app que envia um arquivo.

Se o seu app já tem um banco Dexie aberto, plugue o seu:

```ts
import {
  createOfflineStore,
  createResumableUpload,
  type ResumableUploadRecord,
} from "tempest-react-sdk";

const store = createOfflineStore<{ id: string; record: ResumableUploadRecord }, string>({
  databaseName: "Uploads",
  version: 1,
  tableName: "resume",
  indexes: "&id",
});

createResumableUpload({
  endpoint: "/api/uploads",
  file,
  storage: {
    get: async (key) => (await store.get(key))?.record ?? null,
    set: async (key, record) => {
      await store.put({ id: key, record });
    },
    delete: async (key) => {
      await store.delete(key);
    },
  },
});
```

`storage: null` desliga a persistência: aí a retomada sobrevive a uma queda de rede, mas não a um reload.

## A falha que realmente acontece

Não é o chunk que se perde. É o chunk que o **servidor gravou e cuja resposta não voltou**. O cliente não distingue isso de um chunk perdido, e reenviar às cegas duplicaria bytes.

Duas coisas impedem:

**1. Escritas são endereçadas, não anexadas.** Todo `PATCH` declara o offset em que escreve (`Upload-Offset`). Se a resposta se perdeu e o cliente repetir, ele está pedindo pra escrever bytes que o servidor já tem — e leva `409`. Em **qualquer** retentativa, o cliente relê a verdade com `HEAD` antes de escrever e continua de onde o servidor realmente está.

**2. A criação leva `Idempotency-Key`.** O tus não tem criação idempotente; sem isso, um `201` perdido deixaria um upload órfão no servidor e o cliente criaria um segundo. A chave (de `generateIdempotencyKey`) é gravada **antes** da primeira tentativa e reusada na retentativa. Backend que honra o header devolve o mesmo `Location`; backend que ignora funciona igual, só fica com o órfão.

!!! tip "O backoff é o `retry` do SDK"
    Não existe um segundo backoff aqui: cada chunk roda dentro do [`retry`](./http.md#retry-backoff-exponencial) — exponencial, com `Retry-After` respeitado. Ajuste por `retry: { retries, initialDelay, shouldRetry }`.

!!! check "O que o loop de chunk retenta, e o que não"
    Duas decisões são **específicas do protocolo de retomada** e não seguem a
    política geral do SDK:

    | Resposta | Retenta? | Por quê |
    | --- | --- | --- |
    | falha de rede, `408`, `425`, `429`, `5xx` | **sim** | política padrão: pode mudar sozinho |
    | `409`, `412` | **sim** | é o sinal de offset divergente — o replay *é* a correção, e o `HEAD` de resync a executa |
    | `404`, `410` | **não** | o upload sumiu do servidor. Recriar só acontece no attach, nunca dentro do loop |
    | `400`, `403`, `413`, `415`, `422` | **não** | recusa deliberada; a 5ª tentativa recebe a mesma resposta |

    O `409` é o caso interessante: a política geral do SDK recusa 4xx, e com razão
    — mas aqui ele significa "seu offset está errado", que é exatamente o que a
    retentativa conserta.

    O `404` é o inverso. Recurso que desapareceu *parece* transitório, mas o
    `HEAD` de resync bate no mesmo `404`, então retentar era sondar um recurso
    morto cinco vezes e só então mostrar "o upload expirou" — com o backoff somado
    em cima. Nesse caso, comece um upload novo.

    Um `shouldRetry` seu **substitui** essa política inteira, nas duas direções.

## O que o backend precisa implementar

Toda request leva `Tus-Resumable: 1.0.0`.

| Passo | Request | Resposta esperada |
| --- | --- | --- |
| Criar | `POST {endpoint}` + `Upload-Length`, `Upload-Metadata`, `Idempotency-Key` | `201` + `Location` (URL do upload, absoluta ou relativa) |
| Sondar | `HEAD {uploadUrl}` | `200`/`204` + `Upload-Offset` |
| Escrever | `PATCH {uploadUrl}` + `Upload-Offset`, `Content-Type: application/offset+octet-stream`, corpo = chunk | `204` + o novo `Upload-Offset`; `409` quando o offset não bate |
| Descartar | `DELETE {uploadUrl}` | `204` |

Detalhes que costumam morder:

- **`Location` pode ser relativo.** O cliente resolve contra a página, então `/api/uploads/abc` serve.
- **`Upload-Metadata`** é `chave base64(valor)` separado por vírgula, com o valor em **UTF-8 antes** do base64 — é assim que `nota-ação.webm` sobrevive a um header HTTP.
- **`HEAD` respondendo `404`/`410`** é lido como "o servidor esqueceu esse upload": o cliente recria do zero em vez de travar.
- **`Upload-Offset` ausente num `PATCH` bem-sucedido** é tolerado — o cliente assume o fim do chunk —, mas mandar é melhor.
- Reflita o `Idempotency-Key` numa tabela de chaves se quiser evitar órfãos.

!!! info "Servidor pronto"
    `tusd` (Go), `tus-node-server` (Node) e `tuspy`/`py-tus` (Python) já implementam a tabela. Num FastAPI próprio são quatro rotas.

## Progresso e pausa, com precisão

```ts
const upload = createResumableUpload({
  endpoint: "/api/uploads",
  file,
  chunkSize: 1024 * 1024, // 1 MiB: tick mais fino, mais round-trips
  // o padrão é DEFAULT_CHUNK_SIZE (5 MiB), exportado para uma tela de ajustes exibir
  getToken: () => auth.getToken(),
  withCredentials: true,
  retry: { retries: 8, initialDelay: 500 },
  onProgress: ({ loaded, total, fraction, resumedFrom }) => {
    console.log(`${loaded}/${total} (${Math.round(fraction * 100)}%), retomou em ${resumedFrom}`);
  },
});
```

- `onProgress` recebe **bytes do arquivo inteiro**, não do chunk. `resumedFrom` diz quantos já estavam no servidor quando esta execução começou — útil pra não anunciar "0%" num upload que retomou em 80%.
- `pause()` derruba o chunk em voo; o offset persistido continua o do último chunk **confirmado**. O `resume()` faz `HEAD` primeiro, então bytes parciais que o servidor aceitou não se perdem.
- `abort({ discard: true })` manda `DELETE` e apaga o registro; sem `discard`, o ponto de retomada fica.

!!! warning "`XMLHttpRequest`, não `fetch`"
    Como em `uploadWithProgress`: `fetch` ainda não reporta progresso de **upload** em navegador nenhum. Aqui há um segundo motivo — o tus devolve o novo offset num **header de resposta**, e `uploadWithProgress` só entrega corpo parseado, então não dava pra reaproveitar.

## Resumo

- **`createResumableUpload({ endpoint, file })`** — chunks de 5 MiB, retomada por rede e por reload, protocolo tus 1.0.0.
- **`start()` / `pause()` / `resume()` / `abort({ discard })`**; `start()` resolve `null` quando você parou de propósito.
- O ponto de retomada mora em `localStorage` por padrão; troque por `storage`, desligue com `null`.
- Resposta perdida é resolvida por **offset endereçado + `HEAD` antes de cada retentativa**, e a criação por **`Idempotency-Key`**.
- Backoff é o `retry` do SDK — não existe um segundo.

### Veja também

- [HTTP](./http.md) — `uploadWithProgress` (uma request), `retry`, `generateIdempotencyKey`
- [Áudio](./audio.md) — `useAudioRecorder`, que produz os arquivos longos que motivaram isso
- [Offline](./offline.md) — `createOfflineStore`, se você preferir IndexedDB pro estado de retomada

---

# routing.md

# Routing

O módulo `routing` do `tempest-react-sdk` embrulha o **React Router em modo declarativo** (`^7 || ^8`) e devolve uma superfície única de import: você declara sua árvore de rotas com `defineRoutes`, monta tudo com um único `<AppRouter>` e importa cada primitivo (`Link`, `Outlet`, `useNavigate`, …) direto do SDK. Em cima disso, o SDK adiciona o que todo app Tempest repete na mão: code-splitting com retry automático em chunk velho, guards declarativos de rota e um `<Suspense>` já pronto. Esta página te leva do zero a uma árvore com layout aninhado, lazy loading e rotas protegidas.

!!! warning "`react-router` é peer dependency — instale no seu app"
    ```bash
    npm install react-router
    ```

    O SDK **não** empacota o `react-router` junto, porque ele guarda contexto React: uma cópia aninhada em `tempest-react-sdk/node_modules` seria um `<Router>` diferente do seu, e todo hook do SDK estouraria com `useNavigate() may be used only in the context of a <Router>`. O range aceito é `^7 || ^8` — a superfície re-exportada aqui é idêntica nos dois majors, e nenhum deles usa `react-router-dom` (os bindings de DOM vêm no próprio `react-router`).

## Por que o SDK é dono do roteamento agora

Antes, cada app criava seu próprio `<Suspense>`, escrevia o seu helper de guard e reinventava o retry de chunk. Isso gerava divergência entre os apps Tempest e import paths espalhados.

Com o módulo `routing` você ganha:

- **Uma só superfície de import.** Tudo vem de `"tempest-react-sdk"` — componentes, hooks e os primitivos re-exportados do React Router. Seu app instala o `react-router` (peer), mas importa de um lugar só.
- **Declarativo.** Você descreve _o que_ são as rotas (uma árvore de objetos), não _como_ montá-las imperativamente.
- **Baterias inclusas.** `<AppRouter>` já constrói o router, o `<Suspense>` e as `<Routes>`. `defineRoutes` te dá tipagem. Guards e lazy loading são campos da própria rota.

!!! info "Primitivos re-exportados"
    O SDK re-exporta os primitivos declarativos do React Router para você importar tudo do mesmo lugar: `BrowserRouter`, `HashRouter`, `MemoryRouter`, `Routes`, `Route`, `Outlet`, `Navigate`, `Link`, `NavLink`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`, `useMatch`, `useRouteError` e `redirect`.

    Importar direto de `react-router` também funciona e resolve para a mesma cópia — o re-export existe por conveniência, não por isolamento. Isso torna a adoção incremental possível: um app que já usa `react-router` direto pode passar a usar o SDK sem reescrever import nenhum.

## Construindo a árvore com `defineRoutes`

`defineRoutes` é um helper de **identidade**: ele recebe um array de `TempestRouteObject` e devolve o mesmo array, mas com tipagem completa. Você ganha autocomplete e checagem de tipos na árvore sem precisar anotar nada na mão.

```tsx
// routes.tsx
import { defineRoutes } from "tempest-react-sdk";
import { Home } from "@/pages/Home";
import { Login } from "@/pages/Login";

export const routes = defineRoutes([
  {
    path: "/",
    element: <Home />,
  },
  {
    path: "login",
    element: <Login />,
  },
]);
```

Cada `TempestRouteObject` aceita:

| Campo           | Tipo                                        | Descrição                                                                       |
| --------------- | ------------------------------------------- | ------------------------------------------------------------------------------- |
| `path`          | `string`                                    | Segmento de URL da rota.                                                        |
| `index`         | `boolean`                                   | Rota índice do pai. Mutuamente exclusivo com `path`.                            |
| `element`       | `ReactNode`                                 | O que renderizar quando a rota casa.                                            |
| `lazy`          | `() => Promise<{ default: ComponentType }>` | Carrega o componente sob demanda (code-split). Retry automático em chunk velho. |
| `children`      | `TempestRouteObject[]`                      | Rotas aninhadas.                                                                |
| `guard`         | `boolean \| (() => boolean)`                | Quando _falsy_, renderiza um redirect no lugar do `element`.                    |
| `redirectTo`    | `string`                                    | Destino do redirect do guard. Padrão `"/"`.                                     |
| `caseSensitive` | `boolean`                                   | Faz o match de `path` diferenciar maiúsculas/minúsculas.                        |

Depois é só passar a árvore para o `<AppRouter>`:

```tsx
// App.tsx
import { AppRouter } from "tempest-react-sdk";
import { routes } from "@/routes";

export function App() {
  return <AppRouter routes={routes} />;
}
```

O `<AppRouter>` monta sozinho o router, o `<Suspense>` e as `<Routes>` a partir da árvore. Props disponíveis:

| Prop             | Tipo                              | Padrão      | Descrição                                                |
| ---------------- | --------------------------------- | ----------- | -------------------------------------------------------- |
| `routes`         | `TempestRouteObject[]`            | —           | A árvore de rotas (obrigatória).                         |
| `router`         | `"browser" \| "hash" \| "memory"` | `"browser"` | Qual tipo de router usar.                                |
| `basename`       | `string`                          | —           | Prefixo de path comum a todas as rotas.                  |
| `initialEntries` | `string[]`                        | —           | Histórico inicial — só para o router `"memory"`.         |
| `fallback`       | `ReactNode`                       | —           | Fallback do `<Suspense>` enquanto um chunk lazy carrega. |

## `index` vs `path`

Toda rota com `children` precisa decidir o que mostrar quando a URL casa **exatamente** com o pai. Essa é a rota `index`: ela não tem `path` próprio, apenas marca `index: true`.

```tsx
// routes.tsx
import { defineRoutes } from "tempest-react-sdk";
import { RootLayout } from "@/layouts/RootLayout";
import { Home } from "@/pages/Home";
import { About } from "@/pages/About";

export const routes = defineRoutes([
  {
    path: "/",
    element: <RootLayout />,
    children: [
      { index: true, element: <Home /> },
      { path: "about", element: <About /> },
    ],
  },
]);
```

Aqui, abrir `/` renderiza o `<RootLayout>` com o `<Home>` dentro; abrir `/about` renderiza o `<RootLayout>` com o `<About>` dentro.

!!! warning "`index` e `path` são mutuamente exclusivos"
    Uma rota é índice (`index: true`) **ou** tem `path`, nunca os dois. Marcar os dois é um erro de configuração.

## Layouts aninhados com `Outlet`

A rota pai renderiza o **layout**; os filhos renderizam dentro dele através do `<Outlet>`. O `<Outlet>` é o ponto onde o React Router injeta a rota filha que casou.

```tsx
// RootLayout.tsx
import { Link, Outlet } from "tempest-react-sdk";

export function RootLayout() {
  return (
    <div>
      <nav>
        <Link to="/">Home</Link>
        <Link to="/dashboard">Dashboard</Link>
      </nav>
      <Outlet />
    </div>
  );
}
```

A `<nav>` fica visível em todas as rotas filhas; o `<Outlet>` troca de conteúdo conforme a URL. Use `<Link>` (também re-exportado pelo SDK) para navegar sem recarregar a página.

!!! tip "Navegação programática"
    Para navegar a partir de código (depois de um submit, por exemplo), use `useNavigate`: `const navigate = useNavigate(); navigate("/dashboard");`.

## Lazy loading + o fallback do Suspense

Páginas pesadas não precisam entrar no bundle inicial. Use o campo `lazy` para carregar o componente sob demanda. Ele recebe uma função que faz `import()` dinâmico e devolve o módulo com `default`.

```tsx
// routes.tsx
import { defineRoutes } from "tempest-react-sdk";
import { RootLayout } from "@/layouts/RootLayout";
import { Home } from "@/pages/Home";

export const routes = defineRoutes([
  {
    path: "/",
    element: <RootLayout />,
    children: [
      { index: true, element: <Home /> },
      {
        path: "dashboard",
        lazy: () => import("@/pages/Dashboard"),
      },
    ],
  },
]);
```

Como o chunk demora um instante para baixar, o `<AppRouter>` envolve tudo num `<Suspense>`. Passe um `fallback` para mostrar algo enquanto carrega:

```tsx
// App.tsx
import { AppRouter } from "tempest-react-sdk";
import { routes } from "@/routes";

export function App() {
  return <AppRouter routes={routes} fallback={<p>Loading…</p>} />;
}
```

!!! note "Retry automático em chunk velho"
    Quando você faz um novo deploy, os nomes dos chunks mudam. Um usuário com a aba aberta há horas pode pedir um chunk que não existe mais e tomar um erro de import. O `lazy` do SDK detecta esse caso e tenta recarregar automaticamente — você não precisa escrever esse retry na mão.

## Guards: protegendo rotas

Quase todo app tem rotas que só usuários autenticados podem ver. O campo `guard` resolve isso direto na árvore: quando o valor é _falsy_, o `<AppRouter>` renderiza um redirect no lugar do `element`.

### Forma booleana

Se a condição já está disponível como valor, passe um booleano:

```tsx
// routes.tsx
import { defineRoutes } from "tempest-react-sdk";
import { Dashboard } from "@/pages/Dashboard";

const isAuthenticated = false;

export const routes = defineRoutes([
  {
    path: "dashboard",
    element: <Dashboard />,
    guard: isAuthenticated,
    redirectTo: "/login",
  },
]);
```

### Forma de função (auth store)

Na prática, o estado de auth vive numa store. Passe uma **função** que lê a store na hora da renderização — assim o guard sempre vê o valor atual:

```tsx
// routes.tsx
import { defineRoutes } from "tempest-react-sdk";
import { useAuth } from "@/stores/auth"; // store baseada em createAuthStore
import { RootLayout } from "@/layouts/RootLayout";
import { Home } from "@/pages/Home";
import { Login } from "@/pages/Login";

export const routes = defineRoutes([
  {
    path: "/",
    element: <RootLayout />,
    children: [
      { index: true, element: <Home /> },
      { path: "login", element: <Login /> },
      {
        path: "dashboard",
        lazy: () => import("@/pages/Dashboard"),
        guard: () => useAuth.getState().isAuthenticated,
        redirectTo: "/login",
      },
    ],
  },
]);
```

!!! warning "O guard roda na renderização — leia a store via `getState()` ou um hook"
    A função do `guard` é avaliada **durante a renderização** da rota. Por isso ela precisa ler o estado _naquele momento_: use `useAuth.getState().isAuthenticated` (leitura imperativa, fora do React) ou um hook de seleção dentro de um componente. Não capture o valor uma vez fora da função — você congelaria o estado de auth no carregamento inicial.

Quando `guard` é _falsy_, o usuário é redirecionado para `redirectTo` (padrão `"/"`). No exemplo acima, quem não está autenticado e tenta abrir `/dashboard` cai em `/login`.

## `RouteGuard` standalone

Às vezes você quer proteger uma parte da UI sem que ela seja uma rota — ou prefere o guard explícito no JSX. Para isso existe o `<RouteGuard>`: ele renderiza os `children` quando `when` é verdadeiro, senão emite um `<Navigate>`.

```tsx
// ProtectedDashboard.tsx
import { RouteGuard } from "tempest-react-sdk";
import { useAuth } from "@/stores/auth";
import { Dashboard } from "@/pages/Dashboard";

export function ProtectedDashboard() {
  const isAuthenticated = useAuth((state) => state.isAuthenticated);

  return (
    <RouteGuard when={isAuthenticated} redirectTo="/login" replace>
      <Dashboard />
    </RouteGuard>
  );
}
```

Props do `<RouteGuard>`:

| Prop         | Tipo        | Padrão | Descrição                                            |
| ------------ | ----------- | ------ | ---------------------------------------------------- |
| `when`       | `boolean`   | —      | Renderiza os `children` quando verdadeiro.           |
| `redirectTo` | `string`    | `"/"`  | Destino quando `when` é falso.                       |
| `replace`    | `boolean`   | `true` | Substitui a entrada no histórico em vez de empilhar. |
| `children`   | `ReactNode` | —      | O que proteger.                                      |

!!! tip "Mesma regra de leitura de estado"
    Aqui você está num componente React, então leia a store com o hook (`useAuth((state) => state.isAuthenticated)`) para re-renderizar quando o auth mudar — diferente do `guard` da árvore, que usa `getState()` por rodar fora do ciclo de hooks.

## Escolhendo o tipo de router

O `<AppRouter>` aceita três tipos via a prop `router`:

- **`"browser"`** (padrão) — usa a History API; URLs limpas (`/dashboard`). É o que você quer em produção.
- **`"hash"`** — URLs com `#` (`/#/dashboard`). Útil quando o servidor não consegue fazer fallback de todas as rotas para o `index.html`.
- **`"memory"`** — histórico em memória, sem tocar a URL do navegador. Ideal para **testes** e ambientes não-DOM.

Em testes, combine `"memory"` com `initialEntries` para começar numa rota específica:

```tsx
// App.test.tsx
import { render, screen } from "@testing-library/react";
import { AppRouter } from "tempest-react-sdk";
import { routes } from "@/routes";

test("renders the dashboard route", () => {
  render(
    <AppRouter
      routes={routes}
      router="memory"
      initialEntries={["/dashboard"]}
      fallback={<p>Loading…</p>}
    />,
  );

  expect(screen.getByRole("heading", { name: /dashboard/i })).toBeInTheDocument();
});
```

!!! note "`initialEntries` é só do router `memory`"
    `initialEntries` define o histórico inicial e só faz sentido com `router="memory"`. Nos routers `browser`/`hash` a rota inicial vem da própria URL do navegador.

## Recap

- O módulo `routing` embrulha o **React Router v8 declarativo** e te dá uma **superfície única de import** — tudo vem de `"tempest-react-sdk"`.
- `defineRoutes` tipa sua árvore; `<AppRouter routes={...} />` monta router + `<Suspense>` + `<Routes>` sozinho.
- Use `index: true` para a rota padrão de um layout e `path` para as demais — nunca os dois juntos.
- Layouts aninhados renderizam filhos no `<Outlet>`; navegue com `<Link>`.
- `lazy` faz code-split com retry automático em chunk velho; mostre o `fallback` do Suspense enquanto carrega.
- Proteja rotas com `guard` (booleano ou função) + `redirectTo`, ou com `<RouteGuard when={...}>` no JSX. O guard roda na renderização — leia a store via `getState()` (na árvore) ou via hook (no componente).
- Escolha o router com a prop `router`: `"browser"` em produção, `"memory"` + `initialEntries` em testes.

---

# scaffold.md

# Scaffold — `create-tempest-app`

`create-tempest-app` é a CLI oficial de scaffolding da Tempest. Com **um comando** você cria um app React 19 + Vite + TypeScript já pré-cabeado com o `tempest-react-sdk`: providers, roteamento, store de autenticação e cliente HTTP saem prontos pra rodar. A CLI **não é um pacote separado** — ela vem **dentro do próprio `tempest-react-sdk`** como o `bin` do pacote (`create-tempest-app`), junto com um `template/` embutido no tarball.

```json
"bin": { "create-tempest-app": "./bin/create-tempest-app.mjs" }
```

Esta página é um tutorial: vamos do comando vazio até o app rodando no navegador, e depois passeamos por cada arquivo gerado pra entender qual recurso do SDK ele demonstra. 🚀

!!! info "Versionada junto com o SDK"
    Como a CLI mora dentro do `tempest-react-sdk`, ela é **versionada junto com o SDK**. Fixar uma versão é fixar a versão do SDK: `npx -p tempest-react-sdk@0.5.1 create-tempest-app …`. E o app gerado já nasce com a dependência `tempest-react-sdk` **carimbada na mesma versão** que o produziu — nada de número hardcoded que desatualiza.

## Crie seu primeiro app

O caminho **recomendado** é criar a pasta você mesmo e scaffoldar dentro dela com `.`:

```bash
mkdir my-app
cd my-app
npx -p tempest-react-sdk create-tempest-app .
npm install
cp .env.example .env
npm run dev            # http://127.0.0.1:5173
```

Abra **<http://127.0.0.1:5173>** — o app já está no ar com providers, rotas e store funcionando.

### O que cada pedaço do comando faz

| Pedaço                 | O que faz                                                                                                                    |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `npx`                  | Baixa e executa um binário **sem instalar nada global** — descarta o download depois.                                         |
| `-p tempest-react-sdk` | Diz **de qual pacote** vem o binário. Necessário porque a CLI mora dentro do SDK, com nome diferente do nome do pacote.        |
| `create-tempest-app`   | O nome do `bin` dentro daquele pacote — é o que roda de fato.                                                                 |
| `.`                    | O **destino**: o diretório atual (modo recomendado). Um nome no lugar do `.` cria a pasta e exige que ela esteja vazia.        |

!!! tip "Prefira `.` a `create-tempest-app my-app`"
    As duas formas funcionam, mas `.` é melhor no dia a dia:

    - **Você controla a pasta e o nome** — o `name` do `package.json` sai do nome do diretório atual, sem risco de acabar com `my-app/my-app` por já estar dentro da pasta.
    - **Convive com o que já existe** — `git init`, `README.md`, `LICENSE` e afins são **preservados** (a CLI lista o que pulou). O modo com nome **aborta** se a pasta não estiver vazia.
    - **Um comando só** pra pasta nova e pra projeto existente.

!!! info "Rodar sem argumento = `.`"
    `npx -p tempest-react-sdk create-tempest-app` (sem nada depois) faz exatamente o mesmo que passar `.`: scaffold no diretório atual. A CLI **não** pergunta nome de projeto.

!!! warning "`npm create tempest-app` não funciona"
    Não existe pacote `create-tempest-app` publicado no npm — a CLI é o `bin` do `tempest-react-sdk`, então `npm create tempest-app` falha com 404. Use `npx -p tempest-react-sdk create-tempest-app .`; dentro de um projeto que já tem o SDK instalado, o `-p` é dispensável.

!!! warning "No modo com nome, a pasta precisa estar vazia"
    Em `create-tempest-app my-app`, o diretório alvo **não pode existir** ou precisa estar **vazio** — isso evita sobrescrever um projeto seu por acidente. Se a pasta já tem arquivos, a CLI sugere usar `.` para **mesclar** no diretório atual em vez de abortar (veja a próxima seção).

### Os dois modos, lado a lado

| Você digita                 | Destino           | Se a pasta tem arquivos                         | Nome do projeto     |
| --------------------------- | ----------------- | ----------------------------------------------- | ------------------- |
| `create-tempest-app .`      | diretório atual   | **preserva** os seus e reporta o que foi pulado | nome da pasta atual |
| `create-tempest-app` (só)   | diretório atual   | idem                                             | nome da pasta atual |
| `create-tempest-app my-app` | `./my-app`        | **aborta** se existir e não estiver vazia        | `my-app`            |

## Scaffold dentro de um projeto existente

Se você já tem um projeto que depende do SDK, dá pra gerar o `src/` + configs **no diretório atual**, sem criar uma pasta nova:

```bash
npm install tempest-react-sdk
npx create-tempest-app .
```

Aqui o `npx create-tempest-app` resolve o `bin` a partir do `tempest-react-sdk` que você acabou de instalar — não precisa do `-p`. Rodar **sem argumento** se comporta igual a `.`.

Nesse modo "diretório atual":

- **Arquivos existentes são preservados** — a CLI pula cada um que já existe e **reporta** o que foi pulado, sem sobrescrever nada seu.
- Um `package.json` existente tem os scripts e deps da Tempest **mesclados**: seu `name`/`version` e os scripts/deps que já estavam lá são mantidos, e o `tempest-react-sdk` é fixado na **própria versão do SDK** que está rodando o scaffold.

!!! info "O `.env`"
    O `.env.example` declara `VITE_API_URL`, a base usada pelo cliente HTTP em `src/lib/api.ts`. Copie pra `.env` e ajuste pra apontar pro seu backend.

### Scripts disponíveis

O `package.json` gerado vem com estes scripts:

| Script              | O que faz                                                 |
| ------------------- | --------------------------------------------------------- |
| `npm run dev`       | `vite` — dev server em `127.0.0.1:5173`                   |
| `npm run build`     | `tsc --noEmit && vite build` — checa tipos e empacota     |
| `npm run preview`   | `vite preview` — serve o build de produção                |
| `npm run typecheck` | `tsc --noEmit` — só checagem de tipos                     |
| `npm run lint`      | `eslint .` — ESLint 9 flat config (react-hooks + refresh) |
| `npm run lint:fix`  | `eslint . --fix` — autocorrige o que dá                   |

## Tour pelo que foi gerado

O projeto gerado é enxuto de propósito: cada arquivo existe pra **demonstrar um recurso do SDK** que você vai reaproveitar. Esta é a estrutura completa:

```text
my-app/
├── index.html
├── package.json          # deps: react, react-dom, tempest-react-sdk; devDeps: vite, @vitejs/plugin-react, typescript, @types/*
├── tsconfig.json         # alias @ -> ./src em "paths"
├── vite.config.ts        # export default createViteConfig()
├── .env.example          # VITE_API_URL
├── .gitignore
└── src/
    ├── main.tsx          # createRoot + "tempest-react-sdk/styles.css" + <App/>
    ├── App.tsx           # <AppProviders> envolvendo <AppRouter routes fallback/>
    ├── routes.tsx        # defineRoutes([...]) com index, login e dashboard lazy + protegido
    ├── layouts/RootLayout.tsx   # nav (Link) + <Outlet/>, lê useAuth.use.isAuthenticated()
    ├── pages/Home.tsx
    ├── pages/Login.tsx          # fakeia uma sessão via useAuth.use.setSession() e navigate("/dashboard")
    ├── pages/Dashboard.tsx      # export default (lazy), rota protegida
    ├── stores/auth.ts           # createSelectors(createAuthStore<User>({ name: "app-auth" }))
    └── lib/api.ts               # createApiClient({ baseURL, getToken, onUnauthorized }) + createQueryKeys
```

### Cada arquivo → o recurso do SDK que ele mostra

| Arquivo              | Recurso do SDK demonstrado                                   |
| -------------------- | ------------------------------------------------------------ |
| `vite.config.ts`     | `createViteConfig` — config Vite pronta pro SDK              |
| `src/App.tsx`        | `AppProviders` + `AppRouter` — providers e roteamento        |
| `src/routes.tsx`     | `defineRoutes` com rota `lazy` + guard de autenticação       |
| `src/stores/auth.ts` | `createAuthStore` + `createSelectors` — store de auth tipada |
| `src/lib/api.ts`     | `createApiClient` + `createQueryKeys` — cliente HTTP + cache |

Vamos olhar os três mais importantes.

#### `vite.config.ts` → `createViteConfig`

```ts
import { createViteConfig } from "tempest-react-sdk/vite";

export default createViteConfig();
```

Uma linha. O `createViteConfig` já liga o plugin de React, o alias `@ -> ./src` e os defaults que o SDK espera. Veja a página [Vite Config](./vite-config.md) pra customizar.

#### `src/App.tsx` → `AppProviders` + `AppRouter`

```tsx
import { AppProviders, AppRouter } from "tempest-react-sdk";
import { routes } from "@/routes";

export function App() {
  return (
    <AppProviders errorBoundary={{ fallback: <p>Something went wrong.</p> }}>
      <AppRouter routes={routes} fallback={<p>Loading…</p>} />
    </AppProviders>
  );
}
```

`AppProviders` monta numa tacada só o React Query, o error boundary, o tema e o roteador. `AppRouter` consome o array de rotas e renderiza o `fallback` enquanto rotas `lazy` carregam. Detalhes em [App Providers](./app-providers.md).

#### `src/stores/auth.ts` → `createAuthStore` + `createSelectors`

```ts
import { createAuthStore, createSelectors } from "tempest-react-sdk";

export interface User {
  id: string;
  name: string;
  email: string;
}

export const useAuth = createSelectors(createAuthStore<User>({ name: "app-auth" }));
```

`createAuthStore<User>` cria uma store Zustand de autenticação persistida (`name: "app-auth"` é a chave de storage). `createSelectors` te dá acesso atômico via `useAuth.use.<campo>()` — é assim que `RootLayout.tsx` lê `useAuth.use.isAuthenticated()` e `Login.tsx` chama `useAuth.use.setSession()`. Mais padrões em [State](./state.md).

!!! note "O resto se explica sozinho"
    `routes.tsx` usa `defineRoutes([...])` com uma rota index, uma de login e um `dashboard` que é ao mesmo tempo **lazy** e **protegido** por guard. `lib/api.ts` instancia `createApiClient` com `baseURL`/`getToken`/`onUnauthorized` e exporta `createQueryKeys` pra você organizar as chaves de cache.

## Modo PWA (`--pwa`)

Quer que o app já nasça **instalável** (ícone na home screen), capaz de **emitir notificações web push** e **funcionar offline** (app shell + cache)? Passe a flag `--pwa`:

```bash
npx -p tempest-react-sdk create-tempest-app . --pwa
```

A flag funciona nos dois modos (pasta nova **e** `.`/merge). Ela **sobrepõe** o template PWA por cima do base: tudo do app normal continua igual, mais alguns arquivos novos e alguns sobrescritos.

!!! info "Sem `vite-plugin-pwa`, sem Workbox"
    Instalação, push **e** o cache offline são montados com os próprios helpers do SDK (`tempest-react-sdk/sw` + `tempest-react-sdk/vite`) e empacotados por um build dedicado. Nada de dependência extra de PWA — o app PWA usa exatamente as mesmas deps do app base. (Comparação completa vs `vite-plugin-pwa` mais abaixo.)

### O que a flag adiciona

```text
my-app/
├── index.html                  # (sobrescrito) link do manifest + theme-color + metas apple
├── vite.config.ts              # (sobrescrito) createViteConfig + tempestPwaIcons + Manifest + DevSw
├── vite.sw.config.ts           # build dedicado que empacota src/sw.ts -> dist/sw.js
├── public/
│   ├── manifest.webmanifest    # metadados de instalação (aponta pros PNGs gerados)
│   └── icon.svg                # ícone-fonte (troque pelo seu — os PNGs saem daqui)
└── src/
    ├── sw.ts                   # service worker: push + notificationclick + skip-waiting + cache
    ├── main.tsx                # (sobrescrito) registra /sw.js em dev e produção
    ├── vite-env.d.ts           # (sobrescrito) tipa VITE_VAPID_PUBLIC_KEY
    └── pages/Dashboard.tsx     # (sobrescrito) botão Instalar + toggle de notificações
```

O `package.json` também é ajustado: o script `build` passa a empacotar o SW (`tsc --noEmit && vite build && npm run build:sw`) e ganha um `build:sw`; `sharp` entra como `devDependency` (gera os ícones). O build emite `dist/precache-manifest.json` (lista de assets pro cache offline) via `tempestPwaManifest()` e o set de ícones PNG (`dist/icons/*.png` + `apple-touch-icon.png`) via `tempestPwaIcons()`.

!!! warning "Em merge, seus arquivos são preservados"
    No modo `.` (mesclar em projeto existente), a CLI **nunca sobrescreve um arquivo seu** — só os que ela mesma acabou de gerar. Se você já tinha um `index.html`, ele é pulado e reportado, e a parte PWA dele fica por sua conta.

### As cinco peças

#### 1. Instalação → `useBeforeInstallPrompt`

O `index.html` linka o `manifest.webmanifest`, e o `Dashboard.tsx` mostra um botão **Instalar** só quando o navegador oferece o prompt:

```tsx
const install = useBeforeInstallPrompt();
// ...
{
  install.installable && <Button onClick={() => void install.prompt()}>Install app</Button>;
}
```

#### 2. Service worker → `tempest-react-sdk/sw`

O `src/sw.ts` é só cola em cima dos helpers do SDK:

```ts
/// <reference lib="webworker" />
import {
  installNotificationClickHandler,
  installPushHandler,
  installSkipWaitingListener,
} from "tempest-react-sdk/sw";

installPushHandler({ defaultTitle: "Notificação", defaultIcon: "/icon.svg" });
installNotificationClickHandler();
installSkipWaitingListener();
```

O `vite.sw.config.ts` empacota esse arquivo (e os helpers que ele importa) num **service worker clássico** em `dist/sw.js`, e o `main.tsx` registra ele via `registerServiceWorker`. Em **dev**, o plugin `tempestPwaDevSw()` compila o `sw.ts` na hora e serve em `/sw.js` — então push e cache funcionam também no `npm run dev` (sem ele, o SW só existiria no build). A compilação passa por **um** contexto incremental do esbuild, criado na primeira requisição: o browser rebusca o script do worker a cada navegação e nas checagens de update dele, então bundle a frio por requisição seria bundle a frio o dia inteiro. Veja os detalhes dos helpers em [Web Push](./push.md).

#### 3. Web push → `usePushSubscription`

O `Dashboard.tsx` liga o toggle de notificações ao hook, lendo a chave VAPID do `.env`:

```tsx
const push = usePushSubscription({
  vapidPublicKey: import.meta.env.VITE_VAPID_PUBLIC_KEY ?? "",
  onSubscribe: async (subscription) => {
    // mande a subscription pro seu backend entregar os pushes
    await api.post("/webpush/subscribe", { body: subscription });
  },
  onUnsubscribe: async () => {
    await api.delete("/webpush/my");
  },
});
```

#### 4. Offline → `installPrecache` + `installRuntimeCache`

O `vite.config.ts` adiciona o plugin `tempestPwaManifest()`, que emite um `dist/precache-manifest.json` com todos os assets do build (o equivalente sem-dependência ao `__WB_MANIFEST` do Workbox). No `sw.ts`, dois helpers consomem isso:

```ts
import { installPrecache, installRuntimeCache } from "tempest-react-sdk/sw";

// Rotas específicas PRIMEIRO (ganham do catch-all do precache):
installRuntimeCache([
  {
    match: (url) => url.pathname.startsWith("/api/"),
    strategy: "network-first", // ou "cache-first" / "stale-while-revalidate"
    cacheName: "api",
    networkTimeoutSeconds: 5,
    maxEntries: 50,
    maxAgeSeconds: 60 * 5,
  },
]);

// App shell por último — abre offline:
installPrecache({ navigateFallback: "/index.html", navigateFallbackDenylist: [/^\/api\//] });
```

- **`installPrecache`** cacheia o app shell no `install`, serve assets cache-first, e devolve o `navigateFallback` (SPA) quando a navegação acontece offline. Versiona o cache pelo `version` do manifest e limpa versões antigas no `activate`.
- **`installRuntimeCache`** aplica estratégias por rota (cache-first / network-first / stale-while-revalidate) com `maxEntries` e `maxAgeSeconds`.

#### 5. Ícones → `tempestPwaIcons`

O `vite.config.ts` adiciona o plugin `tempestPwaIcons({ source: "public/icon.svg" })`, que no build rasteriza **um único SVG-fonte** no set completo de ícones — o equivalente sem-dependência ao `@vite-pwa/assets-generator`:

```ts
import { tempestPwaIcons } from "tempest-react-sdk/vite";

tempestPwaIcons({ source: "public/icon.svg" });
// emite: dist/icons/icon-192.png, icon-512.png, maskable-512.png, dist/apple-touch-icon.png
```

A rasterização usa **`sharp`** (já incluído como `devDependency` do template). O `manifest.webmanifest` aponta pros PNGs gerados, e o `tempestPwaManifest()` os inclui no precache automaticamente. Trocar o ícone do app = trocar o `public/icon.svg`.

!!! note "`sharp` é opcional"
    O plugin importa `sharp` de forma preguiçosa: se ele não estiver instalado, o build **não falha** — só emite um aviso e pula a geração. O template já traz `sharp` como devDep, então funciona out-of-the-box.

!!! danger "Push e offline só valem num build de produção"
    A geração de ícones acontece **em tempo de build**, e o app shell só é precacheado depois de `npm run build`. No `npm run dev` o `tempestPwaDevSw()` serve o SW (push + runtime cache funcionam), mas o precache offline e os PNGs só existem no build. Pra testar instalação + offline completos, rode `npm run build && npm run preview` (e no DevTools › Network marque **Offline** pra ver o app shell servir).

### `--pwa` vs `vite-plugin-pwa`

O `--pwa` agora cobre o mesmo terreno do `vite-plugin-pwa` para o caso comum, sem dependência de runtime nova:

| Recurso                             | `vite-plugin-pwa` (Workbox) | `--pwa` (SDK)                               |
| ----------------------------------- | --------------------------- | ------------------------------------------- |
| Manifest + instalável               | ✅                          | ✅                                          |
| Install prompt                      | manual                      | ✅ `useBeforeInstallPrompt`                 |
| Web push + `notificationclick`      | você escreve                | ✅ helpers do SDK                           |
| Update flow (skip-waiting)          | ✅                          | ✅ `registerServiceWorker`                  |
| Precache do app shell               | ✅ (`__WB_MANIFEST`)        | ✅ `tempestPwaManifest` + `installPrecache` |
| Runtime caching (cache/network/SWR) | ✅                          | ✅ `installRuntimeCache`                    |
| `navigateFallback` (SPA offline)    | ✅                          | ✅                                          |
| Limpeza de caches antigos           | ✅                          | ✅ (versão no `activate`)                   |
| Geração automática de ícones        | ✅ (sharp)                  | ✅ `tempestPwaIcons` (sharp, opcional)      |
| SW em dev                           | ✅ (`devOptions`)           | ✅ `tempestPwaDevSw` (esbuild)              |
| Background Sync                      | ✅ (`BackgroundSyncPlugin`) | ✅ `installBackgroundSync`                  |
| Range requests (mídia)              | ✅ (`RangeRequestsPlugin`)  | ✅ `installRuntimeCache({ rangeRequests })` |
| Splash screens (Apple)              | ✅ (assets generator)       | ✅ `tempestPwaIcons({ appleSplash })`       |

Cobertura total do caso comum. Pra extremos muito específicos (range requests parciais de precache, estratégias Workbox exóticas), `vite-plugin-pwa` ainda existe e pode ser passado via `plugins: [...]` no `createViteConfig`.

### Recursos avançados

#### Background Sync — mutações offline que reenviam sozinhas

`installBackgroundSync` enfileira POST/PUT/PATCH/DELETE que falham offline (IndexedDB) e os **reenvia quando a conexão volta** — via Background Sync API onde existe, e oportunisticamente (no próximo request) onde não:

```ts
import { installBackgroundSync } from "tempest-react-sdk/sw";

installBackgroundSync({ match: (url) => url.pathname.startsWith("/api/") });
```

O fetch original ainda **rejeita** no momento (seu app mostra estado offline), mas a requisição é replayada depois. `maxRetentionMinutes` descarta entradas velhas; respostas 4xx são dropadas (erro do cliente não se conserta sozinho).

#### Range requests — seek de áudio/vídeo offline

Marque uma rota com `rangeRequests: true` pra servir `206 Partial Content` fatiando o recurso cacheado — sem isso, mídia não dá seek offline:

```ts
installRuntimeCache([
  {
    match: (url) => /\.(mp3|mp4|webm)$/.test(url.pathname),
    strategy: "cache-first",
    cacheName: "media",
    rangeRequests: true,
  },
]);
```

O helper `createPartialResponse(request, response)` também é exportado pra uso manual.

#### Splash screens (Apple) — telas de abertura no iOS

`tempestPwaIcons({ appleSplash: true })` gera as launch images por device (iPhone/iPad, portrait) e injeta os `<link rel="apple-touch-startup-image" media=...>` no `index.html`. Passe um array pra customizar os tamanhos:

```ts
tempestPwaIcons({
  source: "public/icon.svg",
  appleSplash: [{ width: 390, height: 844, ratio: 3 }],
});
```

### Recap do modo PWA

`--pwa` te entrega manifest + service worker + push + **cache offline** + **ícones gerados** + **SW em dev** + **background sync** + **range requests** + **splash screens**, já cabeados sobre o mesmo app base, usando `tempest-react-sdk/sw` (`installPushHandler`, `installPrecache`, `installRuntimeCache`, `installBackgroundSync`, `createPartialResponse`), `tempest-react-sdk/vite` (`tempestPwaManifest`, `tempestPwaIcons`, `tempestPwaDevSw`), `usePushSubscription` e `useBeforeInstallPrompt` — sem `vite-plugin-pwa`. Gere o VAPID no backend, preencha `VITE_VAPID_PUBLIC_KEY` no `.env`, troque o `public/icon.svg`, e teste com `npm run build && npm run preview`. 🚀

## Próximos passos

Com o app rodando, aqui está como crescer a partir dele:

### 1. Adicione uma página

Crie `src/pages/Sobre.tsx` e registre a rota em `src/routes.tsx`:

```tsx
import { defineRoutes } from "tempest-react-sdk";

export const routes = defineRoutes([
  // ...rotas existentes
  { path: "/sobre", element: <Sobre /> },
]);
```

### 2. Adicione uma store

Pra estado que não é de autenticação, use `createStore` do SDK:

```ts
import { createStore } from "tempest-react-sdk";

export const useCounter = createStore<{ count: number; inc: () => void }>((set) => ({
  count: 0,
  inc: () => set((state) => ({ count: state.count + 1 })),
}));
```

### 3. Busque dados com React Query + queryKeys + api

Combine o cliente HTTP, as query keys e o `useQuery` (já disponível pelo `AppProviders`):

```tsx
import { useQuery } from "@tanstack/react-query";
import { api, queryKeys } from "@/lib/api";

export function UserList() {
  const { data, isLoading } = useQuery({
    queryKey: queryKeys.users.all,
    queryFn: () => api.get("/users"),
  });

  if (isLoading) return <p>Carregando…</p>;
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}
```

Aprofunde em [Query](./query.md) e [HTTP](./http.md).

## Recap

- A CLI é o **`bin` do próprio `tempest-react-sdk`** (`create-tempest-app`), com um `template/` embutido no tarball — versionada junto com o SDK, não um pacote separado. ✅
- Caminho recomendado: `mkdir my-app && cd my-app && npx -p tempest-react-sdk create-tempest-app .` — o `.` (igual a rodar **sem argumento**) gera no diretório atual, **preserva arquivos existentes** e tira o nome do projeto da pasta. Use `@X` no `-p` pra fixar a versão do SDK.
- Modo com nome: `npx -p tempest-react-sdk create-tempest-app my-app` cria a pasta, mas **aborta** se ela já existir e não estiver vazia. A CLI **não pergunta** nome de projeto em nenhum modo.
- Projeto existente: `npm install tempest-react-sdk` e `npx create-tempest-app .` (sem `-p`, o `bin` vem do `node_modules`) — o `package.json` tem scripts/deps **mesclados** (`tempest-react-sdk` fixado na versão do SDK).
- `npm install && cp .env.example .env && npm run dev` te leva a **<http://127.0.0.1:5173>** com providers, rotas e auth funcionando.
- Cada arquivo gerado **demonstra um recurso**: `createViteConfig`, `AppProviders` + `AppRouter`, `defineRoutes` (lazy + guard), `createAuthStore` + `createSelectors`, `createApiClient` + `createQueryKeys`.
- Pra crescer: adicione páginas em `pages/` + entradas em `routes.tsx`, crie stores com `createStore`, e busque dados com `useQuery` + `queryKeys` + `api`.

---

# share.md

# Web Share

`share()` é um wrapper sobre a Web Share API (`navigator.share`) que devolve um **resultado uniforme** em vez de lançar exceções. Você decide o que fazer em cada caso — incluindo um fallback custom (copiar link, botões sociais) quando o browser não suporta.

!!! info "Por que envolver `navigator.share`?"
    A API nativa rejeita a promise tanto quando o usuário cancela o diálogo quanto em erros reais, e nem todo browser a expõe. Tratar isso manualmente vira um `try/catch` cheio de checagens em cada call site. `share()` colapsa tudo num objeto `ShareResult` com booleanos claros (`shared` / `unsupported` / `cancelled`), então o seu código vira um `if` simples.

## Uso

```ts
import { share } from "tempest-react-sdk";

async function shareEvent() {
  const result = await share({
    title: "Tempest",
    text: "Confira esse evento",
    url: window.location.href,
  });

  if (result.unsupported) {
    copyLinkInstead(); // fallback: copiar o link
  } else if (result.cancelled) {
    // usuário fechou o sheet — silencioso, não faça nada
  } else if (result.shared) {
    toast.success("Compartilhado");
  } else if (result.error) {
    reportError(result.error); // erro real — mande pra telemetria
  }
}

declare function copyLinkInstead(): void;
declare function reportError(error: unknown): void;
declare const toast: { success: (message: string) => void };
```

### O payload (`SharePayload`)

Todos os campos são opcionais — passe os que fizerem sentido:

| Campo   | Tipo     | Descrição                                           |
| ------- | -------- | --------------------------------------------------- |
| `title` | `string` | Título do conteúdo                                  |
| `text`  | `string` | Texto/descrição                                     |
| `url`   | `string` | URL a compartilhar                                  |
| `files` | `File[]` | Arquivos (suportado só num subconjunto de browsers) |

### O resultado (`ShareResult`)

| Campo         | Tipo      | Significado                                          |
| ------------- | --------- | ---------------------------------------------------- |
| `shared`      | `boolean` | `navigator.share` resolveu OK                        |
| `unsupported` | `boolean` | API ausente, ou o payload (arquivos) não é suportado |
| `cancelled`   | `boolean` | Usuário fechou o sheet (`AbortError`)                |
| `error`       | `unknown` | Outro erro — capture para telemetria                 |

!!! tip "`cancelled` não é erro"
    Quando o usuário fecha o sheet de compartilhamento, isso vem como `cancelled: true`, **não** em `error`. Trate como um no-op silencioso — mostrar um toast de erro aqui irrita o usuário.

## Detectando suporte antecipadamente

Use `isShareSupported()` para decidir se mostra o botão "Compartilhar" ou já parte para o fallback, sem esperar o clique:

```tsx
import { isShareSupported, share } from "tempest-react-sdk";

export function ShareButton({ url }: { url: string }) {
  if (!isShareSupported()) {
    return <CopyLinkButton url={url} />;
  }

  return <button onClick={() => share({ title: "Tempest", url })}>Compartilhar</button>;
}

declare function CopyLinkButton(props: { url: string }): JSX.Element;
```

## Compartilhando arquivos

Passe `files` para compartilhar imagens, PDFs, etc. `share()` chama `navigator.canShare({ files })` **antes** de tentar — se o browser não permite arquivos (iOS antigo, Firefox desktop), você recebe `unsupported: true` em vez de uma exceção:

```ts
import { share } from "tempest-react-sdk";

async function shareImage(imageFile: File) {
  const result = await share({ title: "Imagem", files: [imageFile] });
  if (result.unsupported) {
    // este browser não compartilha arquivos — ofereça download
    downloadFile(imageFile);
  }
}

declare function downloadFile(file: File): void;
```

!!! warning "Web Share API exige HTTPS e gesto do usuário"
    `navigator.share` só funciona em contexto seguro (HTTPS ou `localhost`) e precisa ser chamado dentro de um handler de gesto do usuário (ex.: `onClick`). Chamar fora de um clique faz o browser rejeitar — o que cai em `error`, não em `unsupported`.

## Exportar um arquivo — `shareOrDownloadBlob`

O caso mais comum de `files` é "gerei um artefato, agora entrega pro usuário": no celular abre a sheet nativa de compartilhamento, e no desktop (ou onde arquivos não são suportados) cai num download simples. `shareOrDownloadBlob(blob, fileName, options?)` encapsula exatamente esse fluxo — é um companheiro do `share()` construído em cima dele:

```ts
import { shareOrDownloadBlob } from "tempest-react-sdk";

async function exportReport(bytes: Uint8Array<ArrayBuffer>) {
  const zip = new Blob([bytes], { type: "application/zip" });
  await shareOrDownloadBlob(zip, "relatorio.zip");
}
```

Por baixo ele chama `share({ title, files: [file] })`. Se o usuário **compartilhou** ou **cancelou** a sheet, a função retorna e nada mais acontece. Caso contrário (browser sem suporte a compartilhar arquivos), ela cria um `<a download>`, dispara o clique e revoga o object URL — o download clássico.

| Parâmetro       | Tipo     | Descrição                                            |
| --------------- | -------- | ---------------------------------------------------- |
| `blob`          | `Blob`   | O conteúdo binário a compartilhar/baixar             |
| `fileName`      | `string` | Nome do arquivo apresentado ao usuário               |
| `options.title` | `string` | Título da sheet de compartilhamento (padrão: o nome) |

!!! tip "Combina com `writeXlsx` / geração de ZIP"
    Gere a planilha com [`writeXlsx`](./utilities.md#planilhas-xlsx-writexlsx), embrulhe num `Blob` e passe pro `shareOrDownloadBlob` — exportação de dados completa, do byte à sheet nativa, sem dependência extra.

## Recap

- `share(payload)` envolve `navigator.share` e devolve `ShareResult` em vez de lançar.
- `shareOrDownloadBlob(blob, fileName)` compartilha o arquivo quando dá, senão baixa via `<a download>`.
- Cheque na ordem: `unsupported` → fallback, `cancelled` → silêncio, `shared` → sucesso, `error` → telemetria.
- `SharePayload` aceita `title`, `text`, `url`, `files` (todos opcionais).
- `isShareSupported()` decide antecipadamente entre o botão nativo e o fallback.
- `files` é validado via `canShare` antes de tentar; browsers sem suporte devolvem `unsupported: true`.
- Requer HTTPS e um gesto do usuário (chame de um `onClick`).

## Veja também

- [Hooks](./hooks.md) — `useClipboard` para o fallback "copiar link"

---

# sse.md

# Server-Sent Events

Wrapper sobre `EventSource` com reconnect exponencial, heartbeat opt-in e parsing JSON. Caso de uso original: stream de notificações (`NEW-ALO`, `PAYMENT-SUCCESS`, etc.) do alofans-frontend.

!!! info "SSE vs WebSocket — qual escolher?"
    SSE é unidirecional (servidor → cliente), roda sobre HTTP comum, reconecta sozinho e autentica por cookie sem cerimônia. Se o cliente **não precisa enviar** mensagens, SSE é mais simples e barato. Pra tráfego bidirecional (chat, colaboração), use [WebSocket](./websocket.md).

## Quando usar

- Push unilateral servidor → cliente, sem necessidade de envio do cliente.
- Reconexão automática barata.
- Autenticação por cookie (`withCredentials: true`).

## API imperativa — `createEventStream`

Use fora de React (services, inicialização) quando você gerencia o ciclo de vida na mão:

```ts
import { createEventStream } from "tempest-react-sdk";

interface StreamEvent {
  type: "NOTIFY" | "PAYMENT-SUCCESS";
  message: string;
}

const stream = createEventStream<StreamEvent>(
  `${import.meta.env.VITE_API_URL}/notifications/stream`,
  {
    withCredentials: true,
    namedEvents: ["notification", "payment"],
    heartbeatEvents: ["ping"],
    maxRetries: 10,
    onOpen: () => console.log("SSE aberto"),
    onMessage: ({ event, data, id }) => {
      if (event === "payment") handlePayment(data);
      else addNotification(data);
    },
    onStatusChange: (status) => console.log("SSE", status),
    onError: (err) => console.error(err),
  },
);

// Mais tarde, ao desmontar / deslogar:
stream.close();

// Forçar reconexão imediata (zera o contador de tentativas):
stream.reconnect();

// Ler o status atual:
console.log(stream.status);
```

Cada `onMessage` recebe `{ event, data, id, raw }`: `event` é o nome do evento SSE (default `"message"`), `data` já vem JSON-parsed (com fallback pra string crua), `id` é o `lastEventId` do servidor e `raw` é o `MessageEvent` original.

### Reconexão e heartbeat

```text
Backoff: 1s → 2s → 4s → 8s → ... (limitado em 30s), até maxRetries (default 10)
```

- A cada erro o stream fecha, agenda reconexão com backoff exponencial e emite status `"closed"`. Ao reabrir com sucesso, o contador zera.
- Esgotadas as `maxRetries`, o status vira `"error"` e o stream para de tentar.
- Eventos listados em `heartbeatEvents` (default `["ping"]`) **não** disparam `onMessage` — só mantêm o socket vivo.

!!! tip "Configure os `heartbeatEvents` conforme seu backend"
    Se o servidor envia keep-alives sob outro nome de evento (ex.: `"keepalive"`), liste-o em `heartbeatEvents` pra não poluir o `onMessage` com pings.

## Hook — `useEventStream`

Dentro de componentes, o hook amarra o ciclo de vida do stream ao componente — abre na montagem, fecha no unmount:

```tsx
import { useEventStream } from "tempest-react-sdk";

interface Notification {
  id: string;
  message: string;
}

export function NotificationListener({ user }: { user: { id: string } | null }) {
  const { status, lastMessage, reconnect } = useEventStream<Notification>(
    `${import.meta.env.VITE_API_URL}/notifications/stream`,
    {
      enabled: !!user, // só conecta quando o usuário existe
      withCredentials: true,
      onMessage: ({ data }) => addToInbox(data),
    },
  );

  return (
    <div>
      <span>Stream: {status}</span>
      {status === "error" && <button onClick={reconnect}>Reconectar</button>}
      {lastMessage && <p>Última: {lastMessage.data.message}</p>}
    </div>
  );
}
```

- `enabled: false` desconecta o stream (use enquanto espera o `user` carregar).
- Mudar a URL re-abre a conexão; mudar o `onMessage` **não** (callback via ref interna — sem reconexões à toa).
- `lastMessage` guarda a última mensagem recebida (heartbeats não contam).
- Cleanup automático no unmount.

!!! warning "`error` significa que esgotou as tentativas"
    Quando o status chega em `"error"`, o stream desistiu sozinho. Ofereça um botão chamando `reconnect()` (que zera o contador) em vez de esperar uma reconexão automática que não vem mais.

## Status

`"idle" | "connecting" | "open" | "closed" | "error"`:

- `idle` — ainda não conectou (ou `enabled: false`).
- `connecting` — handshake em andamento.
- `open` — conectado e recebendo.
- `closed` — fechado, possivelmente aguardando reconexão.
- `error` — esgotou `maxRetries`, não tenta mais.

## Recap

- `createEventStream(url, options)` abre um SSE com reconnect exponencial; o controller expõe `close`, `reconnect` e `status`.
- `useEventStream(url, options)` é o wrapper React: amarra o ciclo de vida ao componente, expõe `status`/`lastMessage`/`reconnect` e respeita `enabled`.
- Heartbeats (default `["ping"]`) mantêm o socket vivo sem disparar `onMessage`.
- Status `"error"` = esgotou tentativas; ofereça `reconnect()` ao usuário.

## Veja também

- [WebSocket](./websocket.md) — quando o cliente também precisa enviar
- [Offline](./offline.md) — persistir histórico recebido por SSE
- [Audio](./audio.md) — tocar um som ao receber certos eventos
- [HTTP](./http.md)

---

# state.md

# State (Zustand)

Toda aplicação precisa guardar estado que vive **fora** de um único componente: o carrinho de compras, as preferências do usuário, o passo atual de um wizard, a sessão de autenticação. O módulo `state` do `tempest-react-sdk` te dá duas peças pequenas em cima do [Zustand](https://github.com/pmndrs/zustand) para isso: `createStore` (uma fábrica genérica de store, com persistência opcional) e `createSelectors` (gera seletores por campo automaticamente, para menos re-renders).

A ideia é que você nunca mais escreva à mão o boilerplate de `persist` + `createJSONStorage` nem digite seletores um a um. Você descreve o estado, e o SDK cuida do resto. 🚀

!!! info "Já conhece o `createAuthStore`?"
    Se você leu a página de [Auth](auth.md), já viu o `createAuthStore<TUser>` — um store de autenticação **pronto e persistido**. O `createStore` é o **primo genérico** dele: serve para qualquer fatia de domínio (carrinho, preferências, wizard). Ambos são Zustand por baixo dos panos, então tudo que você aprender aqui vale para os dois.

## O que o Zustand te dá (e por que o SDK envolve)

Zustand é uma store mínima baseada em hooks: você cria um store com um _initializer_ `(set, get) => estado` e recebe de volta um hook (`useStore`) que componentes assinam. Quando o estado muda, só os componentes que leem aquele pedaço re-renderizam.

É excelente, mas no dia a dia você acaba reescrevendo dois pedaços de cerimônia repetidamente:

- **Persistência** — embrulhar o store no middleware `persist`, montar o `createJSONStorage`, escolher entre `localStorage` e `sessionStorage`, lembrar do `partialize`...
- **Seletores por campo** — para evitar re-renders, você quer ler um campo só (`useStore((s) => s.count)`). Fazer isso à mão, campo por campo, é verboso e fácil de errar.

O SDK colapsa esses dois pontos em opções declarativas. Você foca no formato do estado. 💡

## `createStore` — o store em memória

Vamos do mais simples. Sem opções, `createStore` é um store Zustand puro, **em memória** (some no reload). Você passa um initializer padrão do Zustand e recebe um hook ligado de volta.

```ts
import { createStore } from "tempest-react-sdk";

interface CounterState {
  count: number;
  increment: () => void;
  reset: () => void;
}

export const useCounter = createStore<CounterState>((set) => ({
  count: 0,
  increment: () => set((s) => ({ count: s.count + 1 })),
  reset: () => set({ count: 0 }),
}));
```

Dentro de um componente você usa como qualquer hook Zustand:

```tsx
function Counter() {
  const count = useCounter((s) => s.count);
  const increment = useCounter((s) => s.increment);
  return <button onClick={increment}>Cliquei {count} vezes</button>;
}
```

O hook devolvido também carrega os métodos estáticos do Zustand: `useCounter.getState()`, `useCounter.setState()` e `useCounter.subscribe()` (mais sobre `getState` no fim).

## `createStore` com persistência

Agora o pulo do gato. Passe `options.persist` e o SDK embrulha o store no middleware `persist` para você — escolhendo o storage, serializando em JSON e reidratando no carregamento da página.

Aqui está um carrinho que sobrevive a reloads:

```ts
import { createStore } from "tempest-react-sdk";

interface CartState {
  items: string[];
  add: (id: string) => void;
  clear: () => void;
}

export const useCart = createStore<CartState>(
  (set) => ({
    items: [],
    add: (id) => set((s) => ({ items: [...s.items, id] })),
    clear: () => set({ items: [] }),
  }),
  { persist: { name: "cart", partialize: (s) => ({ items: s.items }) } },
);
```

Recapitulando peça por peça:

- O **primeiro argumento** é o initializer Zustand de sempre — nada muda.
- O **segundo argumento** é `options`. Com `persist`, o store passa a salvar em storage.
- `name: "cart"` é a chave usada no storage. É obrigatória quando você persiste.
- `partialize: (s) => ({ items: s.items })` diz **o que** salvar — só `items`, não as funções.

### As opções de `persist`

| Opção        | Tipo                        | Default    | O que faz                                                    |
| ------------ | --------------------------- | ---------- | ------------------------------------------------------------ |
| `name`       | `string`                    | —          | Chave no storage (obrigatória).                              |
| `storage`    | `"local"` \| `"session"`    | `"local"`  | `localStorage` (persiste entre sessões) ou `sessionStorage`. |
| `partialize` | `(state) => Partial<T>`     | salva tudo | Seleciona quais campos serializar.                           |
| `version`    | `number`                    | —          | Versão do schema persistido — combine com `migrate`.         |
| `migrate`    | `(persisted, version) => T` | —          | Transforma um payload antigo no formato atual ao reidratar.  |

!!! tip "Sempre use `partialize` para campos transitórios"
    Estado derivado ou efêmero — um spinner `isLoading`, um `searchQuery` digitado agora, handlers — **não** deveria viver no storage. Se você persistir tudo, um `isLoading: true` salvo no meio de uma requisição pode reidratar travado em `true` no próximo reload. Liste em `partialize` só o que é fonte de verdade durável (aqui, `items`). ✅

### Reidratação entre reloads

Quando a página carrega, o middleware `persist` lê o payload salvo no storage e **funde** de volta no estado inicial. Concretamente, no exemplo do carrinho:

1. O usuário adiciona `"sku-1"` e `"sku-2"` → `items` vira `["sku-1", "sku-2"]` e é salvo em `localStorage["cart"]`.
2. O usuário recarrega a aba. O componente monta com o initializer (`items: []`).
3. O `persist` lê `localStorage["cart"]` e reidrata `items` para `["sku-1", "sku-2"]`.
4. Os componentes que assinam `items` re-renderizam com o carrinho restaurado.

Isso acontece de forma síncrona com storage web, então na primeira pintura o estado já está restaurado — sem flash de carrinho vazio.

!!! note "Versionando o schema persistido"
    Mudou o formato do estado salvo (renomeou um campo, trocou `string[]` por objetos)? Suba `version` e escreva um `migrate` que recebe o payload antigo e devolve o novo formato. Sem isso, um payload antigo no navegador de um usuário pode reidratar com um shape que seu código não espera mais.

## `createSelectors` — uma assinatura por campo

Por padrão, ler estado com `useStore((s) => s.count)` já assina só `count`. Mas escrever esse seletor inline em todo lugar é repetitivo, e é fácil escorregar e escrever `const state = useStore()` — o que assina o store **inteiro** e re-renderiza o componente sempre que **qualquer** fatia muda.

`createSelectors` resolve isso. Você passa um store ligado e recebe **o mesmo hook**, agora com um namespace `.use` contendo um hook de seletor memoizado por chave de topo do estado.

```ts
import { createStore, createSelectors } from "tempest-react-sdk";

interface CounterState {
  count: number;
  increment: () => void;
  reset: () => void;
}

export const useCounter = createSelectors(
  createStore<CounterState>((set) => ({
    count: 0,
    increment: () => set((s) => ({ count: s.count + 1 })),
    reset: () => set({ count: 0 }),
  })),
);
```

Agora cada campo vira um hook próprio sob `.use`:

```tsx
function Counter() {
  const count = useCounter.use.count(); // com createSelectors
  // equivale a: const count = useCounter((s) => s.count);  // Zustand puro
  return <span>{count}</span>;
}
```

`useCounter.use.count()` assina **só** `count`. Se outra fatia do estado mudar, este componente não re-renderiza. Você ganha a granularidade de seletor sem digitar funções de seletor.

!!! tip "Por que isso importa para performance"
    Em um store com muitos campos, um componente que só mostra `count` não deveria re-renderizar quando `items` muda. Os seletores por campo do `.use` dão exatamente esse isolamento — cada componente assina o mínimo que precisa, e re-renders viram localizados em vez de globais.

### Combinando com `createAuthStore`

Como `createAuthStore` também devolve um store Zustand ligado, você pode envolvê-lo com `createSelectors` da mesma forma:

```ts
// auto-seletores sobre um store de auth
import { createAuthStore, createSelectors } from "tempest-react-sdk";

interface User {
  id: string;
  name: string;
  email: string;
}

export const useAuth = createSelectors(createAuthStore<User>({ name: "app-auth" }));

// em um componente:
//   const isAuthenticated = useAuth.use.isAuthenticated();
//   const logout = useAuth.use.logout();
```

Cada campo do estado de auth (`user`, `token`, `isAuthenticated`, `logout`, ...) vira um hook isolado sob `useAuth.use`.

## Lendo estado fora do React — `getState()`

Nem todo código que precisa de estado é um componente. Um interceptor de HTTP, um guard de rota, um utilitário — esses rodam fora da árvore React e não podem chamar hooks. Para eles, use `getState()` no hook ligado:

```ts
import { useAuth } from "./auth-store";

function requireAuth(): boolean {
  // Sem hook — leitura síncrona e pontual, fora do React.
  return useAuth.getState().isAuthenticated;
}
```

É exatamente assim que um guard de rota lê a sessão de auth: ele precisa do valor _agora_, uma vez, sem assinar para re-renders. `getState()` te dá um snapshot. (Para _reagir_ a mudanças fora do React, use `useStore.subscribe()`.)

!!! warning "`getState()` não assina"
    `getState()` lê uma vez e não re-renderiza nada quando o estado muda depois. Dentro de componentes, prefira sempre o hook (`useStore(...)` ou `useStore.use.campo()`) para que a UI se mantenha em sincronia. Reserve `getState()` para o código fora do React.

## Recap

- **`createStore<T>(initializer, options?)`** envolve o `create` do Zustand. Sem `options`, é um store puro em memória; com `options.persist`, ganha persistência sem boilerplate.
- **Opções de `persist`**: `name` (chave do storage, obrigatória), `storage` (`"local"` padrão ou `"session"`), `partialize` (escolha o que salvar — **sempre** exclua campos transitórios), `version` + `migrate` (evolução de schema).
- **Reidratação** é automática no carregamento: o payload salvo é fundido de volta no estado inicial.
- **`createSelectors(store)`** adiciona um namespace `.use` com um hook por campo; `useStore.use.campo()` assina só aquele campo → menos re-renders.
- **`getState()`** lê o estado fora do React (guards de rota, interceptors) — snapshot pontual, sem assinatura.
- **`createStore` é o genérico; `createAuthStore` é o de auth pronto.** Ambos são Zustand, então `createSelectors` e `getState()` funcionam igual nos dois.

---

# styles.md

# Estilos & Design Tokens

O SDK expõe um conjunto de CSS Custom Properties (`--tempest-*`) que controlam toda a aparência dos componentes. Apps consumidores customizam o tema sobrescrevendo esses tokens — **não é necessário tocar em CSS Modules**.

```tsx
import "tempest-react-sdk/styles.css";
```

Pronto. Tudo o que está abaixo já está disponível na sua aplicação.

!!! tip "Sobrescreva tokens no `:root`"
    A única forma de tematizar é redefinir os tokens `--tempest-*` no seu próprio
    CSS. Coloque os overrides num `:root` (ou numa subárvore para escopo parcial)
    **depois** do import — nunca edite os CSS Modules do SDK.

!!! warning "Tokens são API pública"
    Os nomes `--tempest-*` fazem parte do contrato semver do SDK. Veja a
    [política de versionamento](#politica-de-versionamento-de-tokens) no fim da
    página antes de depender de um token específico.

## Sumário

- [Cor](#cor)
  - [Brand — primary tints](#brand-primary-tints)
  - [Neutros — gray scale](#neutros-gray-scale)
  - [Status — triplets (fg/bg/border/solid)](#status-triplets-fgbgbordersolid)
  - [Data viz — cores de série](#data-viz-cores-de-serie)
  - [Gerando a paleta com `createTheme`](#gerando-a-paleta-com-createtheme)
- [Tipografia](#tipografia)
- [Espaçamento](#espacamento)
- [Radius](#radius)
- [Elevação (shadow)](#elevacao-shadow)
- [Motion](#motion)
- [Focus ring](#focus-ring)
- [Z-index](#z-index)
- [Densidade — `data-tempest-density`](#densidade-data-tempest-density)
- [Tema dark — `data-tempest-theme`](#tema-dark-data-tempest-theme)
- [Componentes — variants disponíveis](#componentes-variants-disponiveis)
- [Camada utilitária opt-in — `utilities.css`](#camada-utilitaria-opt-in-utilitiescss)

---

## Cor

### Brand — primary tints

Scale `50` (mais claro) → `900` (mais escuro). Use `--tempest-primary` como cor canônica de ação.

```css
--tempest-primary-50: #eef4ff;
--tempest-primary-100: #d9e6ff;
--tempest-primary-500: #0066ff; /* === --tempest-primary */
--tempest-primary-700: #003d99;
--tempest-primary-900: #001f4d;
```

Aliases:

- `--tempest-primary` = primary-500
- `--tempest-primary-hover` = primary-600 no claro, primary-**600** no escuro (a rampa do escuro é invertida, então 600 é mais **claro** que 500)
- `--tempest-primary-active` = primary-700
- `--tempest-primary-soft` = primary-50 (fundo tinted para soft buttons/badges)
- `--tempest-primary-foreground` = `#ffffff` no claro, `#1f0606` no escuro (cor do texto **sobre** a primary)
- `--tempest-primary-on-soft` = primary-600 no claro, primary-700 no escuro (cor do texto/ícone **sobre** `--tempest-primary-soft`)

### Texto sobre preenchimento saturado: `*-on-solid`

- `--tempest-danger-on-solid` · `--tempest-info-on-solid` = `#ffffff` no claro, `#1f0606` no escuro
- `--tempest-success-on-solid` · `--tempest-warning-on-solid` = `#1f0606` nos **dois** temas

!!! danger "`#ffffff` sobre preenchimento de status não é seguro, e nunca foi"
    Medido contra os preenchimentos do **tema claro**, o default: branco sobre
    `--tempest-success-solid` dá **3,30:1** e sobre `--tempest-warning-solid`
    **3,19:1**. Verde médio e âmbar simplesmente não carregam texto branco — todo
    design system que os embarca põe texto escuro em cima. No tema escuro, onde os
    preenchimentos são mais claros, **todos** falham: `primary` 3,68:1, `danger`
    3,76:1, `info` 3,68:1, `success` 2,28:1, `warning` 2,15:1.

    Por isso a cor do texto é um token por status em vez de um `#ffffff` cravado. A
    tinta escura é um quase-preto puxado pro próprio matiz (`#1f0606`), não preto
    puro — lê como parte da amostra, não como um buraco nela.

!!! info "No escuro, `hover` e `active` vão pro **claro**"
    A escala de primary é invertida no tema escuro (300 é o passo mais escuro, 900 o
    mais claro), então pegar 400/300 no hover fazia o botão **escurecer** sob o
    ponteiro — o gesto do tema claro aplicado numa superfície escura. Também fazia o
    preenchimento fugir do próprio texto: nenhum foreground único passava 4,5:1
    contra `#3b82f6`, `#2563eb` e `#1a4399` ao mesmo tempo. Subir a rampa resolve os
    dois.

!!! check "Um teste segura isso"
    `src/styles/contrast.test.ts` calcula a razão de **cada** par (texto, fundo) que
    o SDK renderiza, direto do `colors.css`, nos dois temas. Se você redefinir a
    paleta e um par cair abaixo de 4,5:1, o teste falha — em vez de o problema
    aparecer no produto de alguém. O `axe` do jsdom **não** pega isso: ele desliga
    `color-contrast` porque não há paint.

!!! warning "Texto sobre `primary-soft` usa `primary-on-soft`, não `primary`"
    `--tempest-primary` sobre `--tempest-primary-soft` dá **4,38:1** no tema claro e
    **4,28:1** no escuro — o
    WCAG AA pede 4.5:1 pra texto. Por isso existe o `--tempest-primary-on-soft`
    (~6:1). Se você redefinir a paleta, redefina os dois: trocar só o
    `--tempest-primary` deixa os estados selecionados (Toggle, ToggleGroup,
    ListTile, Stepper, NavigationRail, FileUpload) fora de conformidade.

Para trocar a brand inteira:

```css
:root {
  --tempest-primary-500: #7c3aed; /* roxo */
  --tempest-primary-600: #6d28d9;
  --tempest-primary-700: #5b21b6;
  --tempest-primary-soft: #ede9fe;
}
```

### Neutros — gray scale

```css
--tempest-gray-50: #f8f9fb;
--tempest-gray-500: #667085;
--tempest-gray-900: #101828;
```

Aliases semânticos:

| Token                     | Uso                                  |
| ------------------------- | ------------------------------------ |
| `--tempest-bg`            | Background canvas                    |
| `--tempest-surface`       | Cards, headers, footers              |
| `--tempest-surface-2`     | Surface elevada (chip, button hover) |
| `--tempest-surface-3`     | Surface mais elevada                 |
| `--tempest-border`        | Borda padrão                         |
| `--tempest-border-strong` | Borda com mais contraste             |
| `--tempest-text`          | Texto principal                      |
| `--tempest-text-muted`    | Texto secundário                     |
| `--tempest-text-subtle`   | Texto terciário (placeholders)       |

### Status — triplets (fg/bg/border/solid)

Cada status (`success`, `warning`, `danger`, `info`) expõe 4 cores:

```css
--tempest-success-fg:     /* texto sobre bg soft */ --tempest-success-bg: /* fundo soft tinted */
  --tempest-success-border: /* borda outline */ --tempest-success-solid: /* fill solid */;
```

Atalhos:

- `--tempest-success` — cor principal (igual a `success` solid escuro no light, mais clara no dark).
- `--tempest-danger-hover` — variação para hover em danger solid.

Componentes que aceitam `appearance="soft|solid|outline"` (Badge, Alert, etc.) escolhem automaticamente a combinação certa.

### Data viz — cores de série

Oito cores categóricas em ordem cíclica, mais o cromado do gráfico:

| Token                        | Uso                                                   |
| ---------------------------- | ----------------------------------------------------- |
| `--tempest-chart-1` … `-8`   | Cores de série, aplicadas por índice (ciclam)          |
| `--tempest-chart-grid`       | Linhas de grid                                         |
| `--tempest-chart-axis`       | Linhas e rótulos de eixo                               |

As oito são espaçadas por **matiz** — são categóricas, não um ramp. Para escala sequencial ou divergente, use `--tempest-primary-*`.

O módulo `tempest-react-sdk/charts` lê esses tokens em runtime e re-resolve quando o tema vira, então sobrescrevê-los muda os gráficos sem tocar em prop nenhuma:

```css
:root {
  --tempest-chart-1: #0f766e;
  --tempest-chart-2: #f97316;
}
```

!!! warning "Não passe `var()` como cor de série"
    O recharts aplica cor como atributo de apresentação do SVG, e `var()` não é resolvido ali. É por isso que o SDK lê o token via `getComputedStyle` e entrega cor literal. Detalhes em [Charts › Cores e tema](charts.md#cores-e-tema).

### Gerando a paleta com `createTheme`

Escrever os ~30 valores de uma marca na mão (dez degraus × claro/escuro + aliases) é trabalhoso e fácil de errar no dark, onde o ramp **inverte**. `createTheme` deriva tudo de uma cor, em OKLCH:

```tsx
import { applyTheme, createTheme } from "tempest-react-sdk";

applyTheme(createTheme({ primary: "#7c3aed", radius: "lg" }));
```

Isso emite os mesmos tokens desta página — é açúcar sobre a API de token, não um segundo sistema de tema. Guia completo em [Tema › `createTheme`](theme.md#createtheme-a-marca-inteira-a-partir-de-uma-cor).

---


### Cores de sintaxe (`--tempest-code-*`)

`CodeBlock` pinta com dez tokens próprios: `comment` · `punctuation` · `string` · `number` · `keyword` · `literal` · `function` · `tag` · `attribute` · `property`.

!!! danger "Não reaproveite a rampa de chart pra texto"
    É tentador — as oito cores de série já existem e já são validadas. Mas elas são validadas pro piso de **marca**: 3:1, que é o que a WCAG pede pra um elemento gráfico. Cor de sintaxe é **texto**, e texto precisa de **4,5:1**. Medindo a rampa como texto no browser, uma palavra-chave em `--tempest-chart-1` deu **3,47:1** na superfície escura e uma string em `--tempest-chart-3` deu **2,03:1** na clara. As duas passam como marca e reprovam como texto.

Cada token de código foi resolvido em OKLCH: fixa a matiz, e busca a claridade mais alta (no dark, a mais baixa) que ainda passa AA contra **os dois fundos** em que o token pode cair — a superfície do bloco e a linha marcada, depois que o realce de 10% do primary compõe sobre ela. Resolver só contra a superfície não basta: o realce move o chão, e uma palavra-chave chegou a medir 4,17:1 em cima dele.

`src/styles/colors.contrast.test.ts` lê o `colors.css` e reafere cada token nos dois modos contra os dois fundos. Se você sobrescrever esses tokens no seu app, refaça essa conta.

## Tipografia

### Famílias

```css
--tempest-font-sans:    /* system stack */ --tempest-font-mono: /* monospace stack */
  --tempest-font-display: /* === sans, override pra heading */;
```

### Tamanhos

| Token                 | Pixels |
| --------------------- | ------ |
| `--tempest-text-2xs`  | 10px   |
| `--tempest-text-xs`   | 12px   |
| `--tempest-text-sm`   | 13px   |
| `--tempest-text-base` | 14px   |
| `--tempest-text-md`   | 15px   |
| `--tempest-text-lg`   | 16px   |
| `--tempest-text-xl`   | 18px   |
| `--tempest-text-2xl`  | 20px   |
| `--tempest-text-3xl`  | 24px   |
| `--tempest-text-4xl`  | 30px   |
| `--tempest-text-5xl`  | 36px   |
| `--tempest-text-6xl`  | 48px   |

### Line heights

`--tempest-leading-none|tight|snug|normal|relaxed|loose` (1.0 → 1.9).

### Pesos

`--tempest-weight-regular|medium|semibold|bold|extrabold` (400 → 800).

### Letter spacing

`--tempest-tracking-tight|normal|wide|wider|widest`.

---

## Espaçamento

Base 4px. Vai de 0 até 24 (96px).

```css
--tempest-space-0: 0 --tempest-space-1: 4px --tempest-space-2: 8px --tempest-space-3: 12px
  --tempest-space-4: 16px --tempest-space-5: 20px --tempest-space-6: 24px --tempest-space-7: 28px
  --tempest-space-8: 32px --tempest-space-10: 40px --tempest-space-12: 48px --tempest-space-16: 64px
  --tempest-space-20: 80px --tempest-space-24: 96px;
```

---

## Radius

```css
--tempest-radius-xs: 2px --tempest-radius-sm: 4px --tempest-radius-md: 8px /* controls padrão */
  --tempest-radius-lg: 12px /* cards padrão */ --tempest-radius-xl: 16px /* modais */
  --tempest-radius-2xl: 24px --tempest-radius-full: 9999px;
```

---

## Elevação (shadow)

```css
--tempest-shadow-xs:    /* hairline, controls em rest */ --tempest-shadow-sm: /* card padrão */
  --tempest-shadow-md: /* hover card, dropdown */ --tempest-shadow-lg: /* drawer, popover */
  --tempest-shadow-xl: /* modal */ --tempest-shadow-inner: /* tracks, inputs sunken */;
```

Shadows são automaticamente mais escuros no tema dark.

---

## Motion

### Duração

```css
--tempest-duration-instant: 0ms --tempest-duration-fast: 120ms /* hover, focus */
  --tempest-duration-base: 180ms /* enter/leave padrão */ --tempest-duration-slow: 280ms
  /* drawer, modal */ --tempest-duration-slower: 420ms;
```

### Easing

```css
--tempest-ease-linear
--tempest-ease-in
--tempest-ease-out
--tempest-ease-in-out
--tempest-ease-emphasized  /* enter animations */
--tempest-ease-bounce
```

### Composite shortcuts

```css
--tempest-transition-color:      /* color + bg + border, fast */ --tempest-transition-shadow:
  /* box-shadow, base */
  --tempest-transition-transform: /* transform, fast */
  --tempest-transition-base: /* tudo acima + opacity */;
```

### Reduced motion

`@media (prefers-reduced-motion: reduce)` zera todas as durações de tokens automaticamente. Componentes que usam keyframes pesados (modal, drawer, toast, tooltip, skeleton) também detectam e desabilitam animações específicas.

---

## Focus ring

```css
--tempest-focus-ring-color: rgba(0, 102, 255, 0.35) --tempest-focus-ring-width: 3px
  --tempest-focus-ring-offset: 2px;
```

`:focus-visible` global aplicado em `reset.css`. Componentes interactive (Button, Card interactive, Tabs, Pagination, etc.) reaplicam o ring com tokens.

Para customizar o ring por subárvore (ex: tema marca branca):

```css
.my-app {
  --tempest-focus-ring-color: rgba(124, 58, 237, 0.4);
}
```

---

## Z-index

```css
--tempest-z-base: 0 --tempest-z-raised: 10 --tempest-z-dropdown: 1000 --tempest-z-sticky: 1020
  --tempest-z-overlay: 1050 --tempest-z-modal: 1100 --tempest-z-popover: 1150
  --tempest-z-toast: 1200 --tempest-z-tooltip: 1300;
```

---

## Densidade — `data-tempest-density`

Atributo aplicado em qualquer elemento (geralmente `<html>` ou `<body>`) ajusta altura, padding, font-size e radius de todos os controles na subárvore.

```html
<html data-tempest-density="compact"></html>
```

Valores: `compact` | `comfortable` (padrão) | `spacious`.

Tokens controlados:

```css
--tempest-control-height-xs..xl
--tempest-control-padding-xs..xl
--tempest-control-font-xs..xl
--tempest-control-radius
--tempest-control-gap
```

Button, Input, Select, Textarea já lêem desses tokens — basta trocar o atributo no root e tudo redimensiona junto.

---

## Tema dark — `data-tempest-theme`

```html
<html data-tempest-theme="dark"></html>
```

Atributo aplicado em qualquer elemento ativa o tema escuro só naquela subárvore. Tokens de cor (primary scale, neutrals, status, focus ring, shadow) são todos sobrescritos.

Use junto com `<ThemeProvider>` (`tempest-react-sdk/theme`) para persistência + flash prevention.

!!! warning "Use `data-tempest-theme=\"dark\"`, não `class=\"dark\"`"
    O dark mode do SDK liga pelo atributo `data-tempest-theme`, nunca por uma
    classe `dark`. Isso permite escopar o tema escuro a uma subárvore específica
    em vez do documento inteiro — algo que a convenção de classe não faz.

---

## Componentes — variants disponíveis

### Button

```tsx
<Button variant="primary | secondary | danger | success | ghost | soft | outline | link" />
<Button size="xs | sm | md | lg | xl" />
<Button iconOnly aria-label="..." />
<Button pill />
<Button loading />
```

### Badge

```tsx
<Badge
  variant="neutral | primary | success | warning | danger | info"
  appearance="soft | solid | outline"
  size="sm | md | lg"
  shape="pill | square"
  dot
/>
```

### Alert

```tsx
<Alert variant="neutral | info | success | warning | danger"
       appearance="soft | solid | outline"
       title="..."
       description="..."
       icon={<Icon />}
       onClose={() => ...} />
```

### Card

```tsx
<Card elevation="flat | default | raised | elevated"
      interactive
      title="..."
      actions={...}
      footer={...} />
```

### Input

```tsx
<Input size="sm | md | lg" />
```

### Spinner

```tsx
<Spinner size="xs | sm | md | lg | xl" />
```

### Divider

```tsx
<Divider
  orientation="horizontal | vertical"
  variant="solid | dashed"
  label="OR"
  align="start | center | end"
/>
```

### Kbd

```tsx
<Kbd size="sm | md | lg">Ctrl</Kbd>
```

---

## Importando tokens em CSS-in-JS

!!! note "O prefixo `tempest_` evita colisão"
    As classes geradas pelos CSS Modules saem prefixadas com `tempest_`, então
    nunca colidem com o CSS do seu app nem com Tailwind/Stitches/Linaria rodando
    lado a lado. Você só interage com os tokens `--tempest-*` — não precisa
    conhecer os nomes de classe.

!!! warning "CSS Modules é a única estratégia de estilo do SDK"
    Os componentes são estilizados por CSS Modules + tokens `--tempest-*`, e ponto.
    Não existe modo "headless" nem hook de classe (`data-tempest-classname`) para
    Tailwind/Stitches/Linaria assumirem a estilização — e isso não está no
    backlog. Manter dois caminhos de estilo dobraria a superfície de cada
    componente e diluiria os tokens.

    O que você **pode** fazer: rodar seu utilitário favorito lado a lado no resto
    do app, ler os tokens do SDK com `var(--tempest-*)` e customizar o SDK
    sobrescrevendo os tokens no `:root`.

Como os tokens são CSS Custom Properties, qualquer solução (`styled-components`, `emotion`, `vanilla-extract`, Tailwind arbitrary values) lê com `var(--tempest-*)`:

```ts
import styled from "styled-components";

const Card = styled.div`
  background: var(--tempest-bg);
  border: 1px solid var(--tempest-border);
  border-radius: var(--tempest-radius-lg);
  padding: var(--tempest-space-5);
  box-shadow: var(--tempest-shadow-sm);
`;
```

Tailwind via `theme.extend.colors`:

```js
// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        tempest: {
          primary: "var(--tempest-primary)",
          bg: "var(--tempest-bg)",
          border: "var(--tempest-border)",
        },
      },
    },
  },
};
```

---

## Camada utilitária opt-in — `utilities.css`

Os componentes são estilizados por CSS Modules, o que resolve o **dentro** deles. O que sobrava pro app era o **em volta**: casca de página, form de duas colunas, linha de ações, card, região que rola na horizontal. Todo app reescrevia esse CSS.

`utilities.css` é essa camada, escrita só com tokens `--tempest-*` — então ela acompanha o tema, incluindo o que sai do `createTheme` e o modo escuro.

```ts
// src/main.tsx
import "tempest-react-sdk/styles.css";
import "tempest-react-sdk/utilities.css"; // opt-in
```

!!! info "Por que opt-in e não dentro do `styles.css`"
    São ~50 nomes de classe **globais**. Um app que já tem o próprio sistema de layout não deve pagar por eles, e injetar classe global em página alheia sem pedir é falta de educação. Custo se você optar: **1.13 KB brotli**.

!!! warning "Isto não é um Tailwind, e não vira"
    A camada tem um punhado de primitivas de layout — não existe (nem entra no backlog) `p-4 mt-2 text-sm bg-blue-500` para cada valor possível. A [decisão consolidada](https://github.com/mauriciobenjamin700/tempest-react-sdk/blob/main/CLAUDE.md) segue valendo: **CSS Modules + tokens é a estratégia de estilo dos componentes**. Isso aqui é ferramenta pro código do *app*, não um segundo caminho de estilizar o SDK.

### Layout

| Classe                    | O que faz                                                                | Ajuste                                             |
| ------------------------- | ------------------------------------------------------------------------ | -------------------------------------------------- |
| `.tempest-container`      | Centraliza, limita a largura, aplica gutter respeitando a safe area       | `--tempest-container-width`, `--tempest-container-gutter` |
| `.tempest-stack`          | Fluxo vertical com um gap só                                             | `--tempest-stack-gap`                              |
| `.tempest-cluster`        | Grupo horizontal que **quebra linha** em vez de estourar                  | `--tempest-cluster-gap`                            |
| `.tempest-row`            | Grupo horizontal que não quebra (toolbar, campos inline)                  | `--tempest-row-gap`                                |
| `.tempest-center`         | Centraliza o filho nos dois eixos                                        | —                                                  |
| `.tempest-spread`         | Empurra primeiro e último filho pras pontas (título ↔ ações)              | `--tempest-row-gap`                                |
| `.tempest-grid-auto`      | Grid de cards responsivo **sem media query** (`auto-fill` + `minmax`)     | `--tempest-grid-min`, `--tempest-grid-gap`         |
| `.tempest-sidebar-layout` | Sidebar + conteúdo; vira uma coluna abaixo de 768px                      | `--tempest-sidebar-width`, `--tempest-sidebar-gap` |
| `.tempest-form-grid`      | Form de 2 colunas que colapsa abaixo de 640px                            | `--tempest-form-columns`, `--tempest-form-gap`     |
| `.tempest-form-span`      | Campo que ocupa a linha inteira do grid de form                          | —                                                  |
| `.tempest-fill`           | Ocupa o espaço restante do flex (com `min-width: 0`, então truncar funciona) | —                                               |
| `.tempest-fixed`          | Nunca encolhe abaixo do conteúdo (botão de ícone ao lado de campo)        | —                                                  |

### Espaçamento, texto, superfície, scroll

| Grupo         | Classes                                                                                      |
| ------------- | -------------------------------------------------------------------------------------------- |
| Gap           | `.tempest-gap-{0,1,2,3,4,5,6,8,10,12}`                                                       |
| Padding       | `.tempest-pad-{0,2,3,4,6,8}`, `.tempest-pad-block`, `.tempest-pad-inline`                     |
| Texto         | `.tempest-truncate`, `.tempest-clamp-{2,3,4}`, `.tempest-text-{muted,subtle}`, `.tempest-text-{xs,sm,base,lg,xl,2xl}`, `.tempest-weight-{medium,semibold,bold}`, `.tempest-numeric` |
| Superfície    | `.tempest-card`, `.tempest-panel`, `.tempest-inset`, `.tempest-divider`                       |
| Scroll        | `.tempest-scroll-x`, `.tempest-scroll-y`                                                      |
| Mídia         | `.tempest-aspect-video`, `.tempest-aspect-square`                                             |
| Diversos      | `.tempest-visually-hidden`, `.tempest-no-select`, `.tempest-busy`                             |

!!! tip "`.tempest-numeric` existe por um motivo específico"
    `font-variant-numeric: tabular-nums` impede que uma coluna de números **dance** quando o valor muda (dígitos proporcionais têm larguras diferentes). Use em tabela de valores, contador ao vivo e `Stat`.

!!! tip "`.tempest-scroll-x` em volta de tabela larga"
    Sem ele, uma tabela larga faz a **página** rolar na horizontal — que é o defeito de layout mais comum em mobile. Com ele, a rolagem fica contida na região.

### Página inteira, montada

```tsx
export function UsersPage() {
  return (
    <div className="tempest-container tempest-page">
      <header className="tempest-page-header">
        <div>
          <h1 className="tempest-page-title">Usuários</h1>
          <p className="tempest-page-subtitle">142 ativos · 8 convites pendentes</p>
        </div>
        <div className="tempest-cluster">
          <Button variant="secondary">Exportar</Button>
          <Button>Convidar</Button>
        </div>
      </header>

      <div className="tempest-toolbar tempest-toolbar-sticky">
        <SearchBar className="tempest-fill" placeholder="Buscar por nome ou e-mail" />
        <Select className="tempest-fixed" options={papeis} />
      </div>

      <div className="tempest-card tempest-scroll-x">
        <DataTable data={usuarios} columns={colunas} />
      </div>

      <div className="tempest-grid-auto" style={{ "--tempest-grid-min": "220px" } as React.CSSProperties}>
        <Stat label="Ativos" value={142} />
        <Stat label="Convidados" value={8} />
        <Stat label="Bloqueados" value={3} />
      </div>
    </div>
  );
}
```

Note o `style={{ "--tempest-grid-min": "220px" }}`: os hooks locais são custom properties, então dá pra ajustar **por instância** sem escrever CSS nem criar variante de classe.

### Dashboard de widgets

A camada tem uma fatia própria pra isso, e o que a torna diferente de um grid comum é
que as colunas reagem à largura do **contêiner**, não do viewport.

```tsx
import "tempest-react-sdk/utilities.css";

export function OperacaoPage() {
  return (
    <div className="tempest-container tempest-page">
      <header className="tempest-page-header">
        <div>
          <h1 className="tempest-page-title">Operação</h1>
          <p className="tempest-page-subtitle">Últimos 30 dias</p>
        </div>
        <Badge variant="success">no ar</Badge>
      </header>

      {/* Fileira de tiles: cabe quantos couberem, sem span nenhum */}
      <div className="tempest-stat-row">
        <div className="tempest-widget-frame">
          <span className="tempest-text-muted tempest-text-xs">Pedidos</span>
          <strong className="tempest-text-2xl tempest-numeric">1.284</strong>
        </div>
        {/* … */}
      </div>

      {/* Grid de 12 colunas com spans por container query */}
      <div className="tempest-dashboard">
        <section className="tempest-widget tempest-widget-two-thirds">
          <div className="tempest-widget-frame">
            <div className="tempest-widget-header">
              <h2 className="tempest-widget-title">Vendas por dia</h2>
              <span className="tempest-text-subtle tempest-text-xs">12 dias</span>
            </div>
            <div className="tempest-widget-body">
              <Sparkline data={vendas} width={320} height={72} label="Vendas por dia" />
            </div>
          </div>
        </section>

        <section className="tempest-widget tempest-widget-third">{/* … */}</section>
        <section className="tempest-widget tempest-widget-half">{/* … */}</section>
        <section className="tempest-widget tempest-widget-half">{/* … */}</section>
      </div>
    </div>
  );
}
```

| Classe | O que faz |
| --- | --- |
| `.tempest-dashboard` | grid de 12 colunas **e** container de tamanho (`container-type: inline-size`) |
| `.tempest-widget` | largura total por default — o estado em que um widget passa a maior parte da vida |
| `.tempest-widget-half` · `-third` · `-quarter` · `-two-thirds` | spans que abrem em **40rem e 64rem de contêiner** |
| `.tempest-widget-tall` | `grid-row: span 2` — gráfico ao lado de uma pilha de tiles |
| `.tempest-stat-row` | fileira de tiles com `auto-fit`, sem span. Ajuste com `--tempest-stat-min` |
| `.tempest-widget-frame` · `-header` · `-title` · `-body` | a moldura do widget |

Hooks: `--tempest-dashboard-columns` (12), `--tempest-dashboard-gap`, `--tempest-widget-padding`, `--tempest-stat-min`.

!!! check "As colunas são do contêiner, não do viewport — e isso é o ponto"
    Medido no browser, com **viewport de 1360px**: o mesmo dashboard dentro de um painel de 440px renderiza em **coluna única**; com 660px, o `-third` e o `-half` vão pra mesma linha (`span 6`); com 1060px, `-two-thirds` fica em `span 8` ao lado do `-third` em `span 4`, e as duas metades dividem a linha seguinte.

    Media query daria o span de desktop pro painel de 440px, e cada widget viraria uma coluna de texto amassado. É o mesmo motivo pelo qual o `Masonry` observa o contêiner.

!!! warning "`width: 100%` no `.tempest-page` não é decoração"
    Solto dentro de um flex **row** — painel de preview, split view — um contêiner de página é um flex item e dimensiona pelo conteúdo: o dashboard colapsou pra ~200px enquanto o pai tinha 500. Só o browser mostra isso; em fluxo normal a declaração não muda nada. Achado exatamente assim, montando esta receita na gallery.

!!! info "`min-height: 0` no `-body` é o que deixa um gráfico caber"
    Filho de grid tem `min-height: auto` por default, então um canvas que reporta altura intrínseca grande empurra a linha em vez de caber nela — e o dashboard ganha uma barra de rolagem que ninguém pediu.

!!! tip "Widget redimensionável pelo usuário é outra coisa"
    Arrastar a borda de um widget briga com a grade: os tracks vêm do grid, e uma largura em pixel vinda do drag não pode conviver com isso. Se você precisa disso, use o [`Resizable`](./components/advanced-layout.md#resizable) numa área livre, ou guarde o span escolhido por widget e aplique a classe correspondente — que é a versão que sobrevive a um reload e cabe na URL.

### Form de duas colunas

```tsx
<Form className="tempest-form-grid" onSubmit={form.handleSubmit(onSubmit)}>
  <FormField name="nome" label="Nome" required><Input /></FormField>
  <FormField name="email" label="E-mail" required><Input type="email" /></FormField>
  <FormField name="cpf" label="CPF"><CPFInput /></FormField>
  <FormField name="telefone" label="Telefone"><PhoneInput /></FormField>

  <FormField name="observacoes" label="Observações" className="tempest-form-span">
    <Textarea rows={4} />
  </FormField>

  <FormActions align="end" className="tempest-form-span">
    <Button type="submit">Salvar</Button>
  </FormActions>
</Form>
```

Uma coluna no celular, duas a partir de 640px, e `.tempest-form-span` para o que ocupa a linha inteira.

---

## Responsive — mobile / tablet / desktop

### Breakpoints

| Token              | Pixels | Device esperado |
| ------------------ | ------ | --------------- |
| `--tempest-bp-xs`  | 480px  | Phones pequenos |
| `--tempest-bp-sm`  | 640px  | Phones large    |
| `--tempest-bp-md`  | 768px  | Tablets         |
| `--tempest-bp-lg`  | 1024px | Laptops         |
| `--tempest-bp-xl`  | 1280px | Desktop padrão  |
| `--tempest-bp-2xl` | 1536px | Ultrawide       |

Convenção `useBreakpoint()` / `<Show>` / `<Hide>`:

- **mobile** = `< md` (`< 768px`)
- **tablet** = `md..lg-1` (`768..1023px`)
- **desktop** = `>= lg` (`>= 1024px`)

### `useBreakpoint()` hook

```tsx
import { useBreakpoint } from "tempest-react-sdk";

const bp = useBreakpoint();
bp.current; // "xs" | "sm" | "md" | "lg" | "xl" | "2xl"
bp.width; // pixels (0 no SSR)
bp.above("md"); // boolean
bp.below("lg"); // boolean
bp.isMobile; // < md
bp.isTablet; // md..lg-1
bp.isDesktop; // >= lg
```

SSR-safe — no servidor retorna `xs` / `width: 0`, atualiza no mount.

### `<Show>` / `<Hide>` components

```tsx
<Show above="md">Desktop nav</Show>
<Show below="md">Mobile menu</Show>
<Show only="xl">Wide-only banner</Show>
<Show only={["md", "lg"]}>Tablet + laptop</Show>

<Hide above="lg">Hide on desktop</Hide>
```

### Utility classes (CSS-only, sem JS)

```html
<div class="tempest-hide-mobile">desktop apenas</div>
<div class="tempest-show-only-mobile">mobile apenas</div>
<div class="tempest-hide-tablet">esconde em tablets</div>
<div class="tempest-show-only-touch">touch devices apenas</div>
<div class="tempest-hide-print">não imprimir</div>
```

### Componentes responsive — props

#### `<Container>` — padding responsivo automático

`space-4` mobile / `space-6` tablet / `space-8` desktop.

#### `<Stack>` / `<Grid>` — props aceitam objeto

```tsx
<Stack direction={{ mobile: "vertical", desktop: "horizontal" }} gap={{ mobile: 2, desktop: 4 }} />

<Grid columns={{ mobile: 1, tablet: 2, desktop: 3 }} gap={4} />
```

#### `<Modal>` — fullscreen / fullscreenOnMobile / 2xl / 3xl

```tsx
<Modal size="2xl" />                  // 1280px
<Modal size="3xl" />                  // 1440px
<Modal fullscreen />                  // fill viewport
<Modal fullscreenOnMobile />          // auto-fullscreen < 640px
```

Padding interno e radius já reduzem abaixo de 640px.

#### `<Drawer>` — mobilePlacement + showHandle

```tsx
// desktop: right drawer; mobile: bottom-sheet
<Drawer placement="right" mobilePlacement="bottom" showHandle />
```

#### `<Table>` — priority + stackOnMobile

```tsx
<Table
  stackOnMobile
  columns={[
    { key: "name", header: "Nome" }, // sempre visível
    { key: "email", header: "E-mail", priority: "tablet" }, // some < 768px
    { key: "role", header: "Cargo", priority: "desktop" }, // some < 1024px
  ]}
  data={users}
/>
```

#### `<ToastProvider>` — position

```tsx
<ToastProvider position="top-right" />        // padrão
<ToastProvider position="bottom-center" />    // mobile-friendly default
```

Em telas `< 480px`, container estica `left: 0; right: 0` automaticamente.

### Touch targets

- `data-tempest-density="touch"` — força altura mínima 44px em todos os controles.
- `@media (pointer: coarse)` aplica auto-bump no `xs`/`sm`/`md` quando o usuário está em dispositivo touch (a menos que `density="compact"` explícito).
- `Button iconOnly` size `xs`/`sm` ganha hit-slop invisível de 8px em todos os lados em pointer coarse.

### Safe-area (iOS notch / Android gestures)

Tokens disponíveis:

```css
--tempest-safe-area-top
--tempest-safe-area-right
--tempest-safe-area-bottom
--tempest-safe-area-left
```

Toast, Modal overlay padding e Drawer já consomem automaticamente. Lembre-se de incluir no HTML:

```html
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
```

### Dynamic viewport (iOS Safari address bar bug)

Modal e Drawer usam `dvh` com fallback `vh`. Apps que precisam de altura cheia podem fazer o mesmo:

```css
.app {
  min-height: 100vh;
  min-height: 100dvh;
}
```

### Fluid type

Para headings que escalam com viewport:

```css
.hero-title {
  font-size: var(--tempest-text-fluid-5xl); /* clamp(32px, 24px + 4vw, 72px) */
}
```

Tokens: `--tempest-text-fluid-sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl`.

### Hover-only effects

Efeitos `transform` / `box-shadow` em hover (Card interactive lift, Button elevation) ficam atrás de `@media (hover: hover) and (pointer: fine)` — não disparam em tap mobile.

### Print

Tudo embutido em `print.css`:

- Modal, Drawer, Toast, Tooltip ocultos.
- Background grayscale, cards `page-break-inside: avoid`.
- Links recebem `(href)` ao lado.

Classe `tempest-hide-print` para esconder elementos próprios.

---

## Política de versionamento de tokens

Tokens são **API pública**. Mudanças quebram apps consumidores. Política:

- **Adições** (novos tokens) — bump minor.
- **Renames / removals** — bump major. Tokens antigos ficam como alias deprecated por pelo menos 1 minor antes de remoção.
- **Mudanças de valor** que afetam aparência visivelmente (cor primária, radius padrão, font stack) — bump minor + nota no changelog.

---

## Resumo

- Importe `tempest-react-sdk/styles.css` uma vez; tematize sobrescrevendo tokens
  `--tempest-*` no `:root` (ou numa subárvore).
- Dark mode liga por `data-tempest-theme="dark"`; densidade por
  `data-tempest-density` — ambos escopáveis a qualquer subárvore.
- As classes de CSS Module saem prefixadas com `tempest_`, sem colisão com o CSS
  do app nem com Tailwind/Stitches/Linaria.
- Tokens são **API pública** sob semver — adições bumpam minor, renames/removals
  bumpam major.

---

# tabular.md

# Tabular (scikit-learn no navegador)

Modelo de scikit-learn respondendo **no navegador**, sem servidor de
inferência e sem enviar os dados do usuário pra lugar nenhum. O subpath
`tempest-react-sdk/tabular` roda o `.onnx` que o
[`tempest-fastapi-sdk`](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/recipes/modelops/)
exporta — mesmo arquivo, mesmo contrato, no cliente em vez de num
dispositivo.

```tsx
import { TabularPredictor } from "tempest-react-sdk/tabular";

const predictor = await TabularPredictor.create("/models/classifier.onnx");
const { labels, probabilities } = await predictor.predict([[5.1, 3.5, 1.4, 0.2]]);

console.log(labels[0], probabilities[0]);
```

```text
0 [0.6662, 0.1061, 0.2277]
```

## Antes de tudo: de onde vem o modelo

Este módulo **não treina** nada. Ele executa um modelo que já foi treinado —
em Python, pela sua equipe de dados — e exportado para um formato que o
navegador consegue ler.

O caminho inteiro tem duas metades:

```mermaid
flowchart LR
    A[Python: modelo treinado] -->|edge_pipeline| B[pasta com o modelo]
    B -->|você publica junto do app| C[public/models/risco/]
    C -->|loadEdgePackage| D[React: predição no navegador]
```

**Metade 1 — Python, uma vez por versão do modelo** (roda como está, o
dataset vem no scikit-learn):

```python
from sklearn.datasets import load_iris
from sklearn.ensemble import RandomForestClassifier

from tempest_fastapi_sdk.modelops import edge_pipeline

data = load_iris()
model = RandomForestClassifier(n_estimators=20, max_depth=4, random_state=0)
model.fit(data.data, data.target)

edge_pipeline(
    model,
    data.data,
    "public/models/flores",     # dentro do seu app React
    name="flores",
    labels=data.target,
    feature_names=list(data.feature_names),
    compact=True,               # a versão que dispensa runtime
)
```

Isso escreve uma **pasta**, não um arquivo:

```text
public/models/flores/
├── flores.onnx        o modelo em ONNX
├── flores.tmc         o mesmo modelo, formato compacto
├── baseline.json      referência dos dados de treino
└── manifest.json      o que tem aí dentro
```

**Metade 2 — React, no navegador.** Se o pacote tem a versão compacta
(`compact=True` acima), **não há nada a instalar** além do próprio SDK:

```tsx
import { loadEdgePackage } from "tempest-react-sdk/tabular";

const pkg = await loadEdgePackage("/models/flores/");

console.log(pkg.featureNames);
// ["sepal length (cm)", "sepal width (cm)", "petal length (cm)", "petal width (cm)"]

const { labels, probabilities } = await pkg.predictor.predict([[5.1, 3.5, 1.4, 0.2]]);
console.log(labels[0], probabilities[0]);
```

!!! tip "A ordem das colunas vem junto"
    `pkg.featureNames` diz em que ordem os valores têm que entrar. Use isso
    para montar a linha a partir do seu formulário — modelo alimentado com
    os números certos **na ordem errada** responde com confiança e errado, e
    não existe checagem em runtime que pegue.

!!! info "Só tenho um `.onnx` solto, sem pasta"
    Funciona também — `TabularPredictor.create("/models/classifier.onnx")`.
    Você perde o que o manifesto carrega (ordem das colunas, nomes das
    classes, versão), e passa a precisar do `onnxruntime-web`.

## Três rotas, você escolhe

Rodar sklearn no navegador tem um custo que não é o modelo. Medido:

| | Tamanho |
| --- | --- |
| Runtime `onnxruntime-web` (`.wasm`) | **25,6 MB** — 6,0 MB gzipped |
| Floresta de 12 árvores em ONNX | 20 KB |
| A mesma em formato compacto | 9,6 KB |
| O leitor compacto (código do SDK) | **1,49 KB** brotli |

O modelo é ruído. **O runtime é a conta.** Daí existirem três caminhos, e o
certo depender do que o seu app já carrega.

### A — Sem runtime (`CompactPredictor`)

```python
# Python, no build
package = edge_pipeline(model, X_train, "dist/risk", labels=y_train, compact=True)
```

```tsx
import { loadEdgePackage } from "tempest-react-sdk/tabular";

const pkg = await loadEdgePackage("/models/risk/");
console.log(pkg.runtime); // "compact"
```

Sem WebAssembly, sem `onnxruntime-web`, sem peer dependency. Modelo linear é
produto escalar; árvore é comparação encadeada — isso cabe em 1,49 KB de
JavaScript (medido, brotli).

**Cobre** linear (logística, linear, ridge, SGD, SVC linear), árvore,
floresta, extra-trees, regressores dos mesmos, e `StandardScaler`/
`MinMaxScaler` dentro de Pipeline.
**Não cobre** gradient boosting, MLP, ou qualquer transformação que não seja
`(x - offset) / escala` — e **recusa exportar** em vez de aproximar.

!!! check "Verificado contra o scikit-learn, não contra a minha ideia do formato"
    O exportador compara o arquivo escrito com as predições do próprio
    estimador e **se recusa a gravar** se discordarem. Do lado do navegador,
    os testes rodam contra fixtures geradas pelo Python junto das saídas do
    scikit-learn — 7 famílias, rótulos idênticos e probabilidades batendo em
    5 casas.

    O arquivo é **dado, nunca código**: nada de JavaScript gerado, nada de
    `eval`, nada que uma CSP estrita proíba.

!!! check "Sem `onnxruntime-web` instalado, mesmo assim funciona"
    Verificado empacotando o SDK e instalando num projeto vazio, sem o peer:
    o barril importa, `CompactPredictor` prediz e bate com o scikit-learn.
    Pedir a rota ONNX ali dá erro nomeando o `npm install onnxruntime-web` e
    a alternativa compacta.

    Isso quebrou na v0.33.0 — o módulo de assets importava o runtime no topo,
    então quem só queria a rota A precisava instalar 25,6 MB de wasm assim
    mesmo. Corrigido na v0.33.1: o runtime entra por `import()` dinâmico, só
    quando um modelo ONNX é carregado. Tem guard de teste travando isso.

### B — Runtime mínimo (`.ort` + build próprio)

```tsx
import { configureOrtAssets, TabularPredictor } from "tempest-react-sdk/tabular";

configureOrtAssets("/ort-minimal/");
const predictor = await TabularPredictor.create("/models/classifier.ort");
```

O `export_onnx_to_ort` do `tempest-fastapi-sdk` gera o `.ort` **e** o
`required_operators.config`, que é o que permite compilar um ONNX Runtime só
com os operadores do seu modelo. Aponte `configureOrtAssets` para esse build.

!!! warning "O `.ort` sozinho não economiza — ele aumenta"
    Medido: 526 B de ONNX viram **2.360 B** de `.ort`; uma floresta de 266 KB
    vira 650 KB. O `.ort` é formato de carregamento, não de compressão.

    Quem encolhe é o **runtime compilado sob medida**, e isso custa
    compilar o ORT do zero (Docker, horas) e manter esse build. O bundle
    padrão lê `.ort` normalmente — testado — então dá para preparar a rota
    antes de ter o build.

### C — ONNX padrão (`TabularPredictor`)

```tsx
const pkg = await loadEdgePackage("/models/risk/", { runtime: "onnx" });
```

O caminho de sempre. **Custo marginal zero se o app já carrega
`onnxruntime-web`** — por exemplo se usa `tempest-react-sdk/vision`. Aí o
runtime já foi pago e o ONNX cobre qualquer estimador.

### Medido no navegador, com o `dist` construído

Chromium, mesma floresta de 10 árvores servida nas duas rotas, wasm servido
localmente (ou seja, **sem latência de rede** — o piso):

| | Compacta | ONNX |
| --- | --- | --- |
| Carga até poder responder | **6,0 ms** | 579,6 ms |
| Predição (lote de 3 linhas) | **0,0035 ms** | 0,0575 ms |
| `.wasm` baixado | **nenhum** | 25,6 MB |

A carga é 97x mais rápida, e a predição 16x — o leitor não aloca tensor nem
atravessa a fronteira do WebAssembly, que nesse tamanho de modelo é o custo
inteiro.

A suíte `e2e/tabular.spec.ts` prova as três coisas em Chromium de verdade:
que a rota compacta **não busca nenhum `.wasm`** (lendo a timeline de recursos
da própria página), que ela responde igual ao scikit-learn nas 7 famílias, e
que continua respondendo com o `fetch` derrubado.

### Como decidir

| Situação | Rota |
| --- | --- |
| PWA só com modelo tabular | **A** — 6 MB gzipped a menos |
| App já roda visão/ONNX | **C** — custo marginal zero, cobertura total |
| Precisa de gradient boosting, MLP, pipeline complexo | **C** |
| Precisa de cobertura ampla **e** binário pequeno | **B** |
| Modelo muda toda semana e o time só publica `.pkl` | Qualquer uma — a esteira é a mesma |

!!! tip "A escolha não vaza para o seu código"
    As duas rotas devolvem o mesmo objeto: `predict(rows)` com `labels`,
    `probabilities`, `numRows` e `ms` — **inclusive o tipo do rótulo**
    (`0`, não `"0"`, quando o scikit-learn usou inteiro). Trocar de rota é
    mudar uma opção, não reescrever a tela.

    ```tsx
    const pkg = await loadEdgePackage("/models/risk/", { runtime: "auto" });
    ```

    `"auto"` pega a compacta quando o pacote tem, e ONNX quando não tem.
    Pedir `"compact"` num pacote que não a carrega dá erro dizendo isso —
    em vez de baixar 25 MB de WebAssembly em silêncio.

## Quando isso vale a pena

| Vale | Não vale |
| --- | --- |
| Score que precisa aparecer enquanto o usuário digita | Modelo que muda de hora em hora |
| Dado sensível que não deve sair do dispositivo | Modelo grande (deep learning pesado) |
| App que precisa funcionar sem rede | Predição que exige dados que só o servidor tem |

Latência medida no Chromium: **0,2 ms** para um lote de 3 linhas numa
regressão logística; ~0,05 ms por linha numa floresta de 10 árvores. A conta
não é sobre computação — é sobre a viagem de rede que deixa de existir.

!!! tip "O que você economiza é a viagem, não o cálculo"
    Medido no lado do servidor com o `tempest-fastapi-sdk`: uma predição de
    uma linha custa **0,0075 ms de inferência dentro de 1,22 ms de HTTP** —
    160x mais transporte que modelo, e isso com cliente em processo, sem
    rede.

    No navegador esse 1,22 ms simplesmente não existe: a mesma predição sai
    em ~0,05 ms, local. Por isso o critério da tabela acima é sobre
    **frescor do modelo e tamanho**, não sobre velocidade de cálculo — a
    velocidade você já ganhou tirando a rede do caminho.

## Num componente React

O hook cuida do que todo componente erra igual: carregamento assíncrono,
cancelamento quando o componente desmonta antes de terminar, e liberação da
sessão.

```tsx
import { useState } from "react";
import { useTabularPredictor } from "tempest-react-sdk/tabular";

function RiskWidget() {
  const { predict, isReady, error } = useTabularPredictor("/models/risk-v3.onnx");
  const [score, setScore] = useState<number | null>(null);

  async function onScore(features: number[]) {
    const { probabilities } = await predict([features]);
    setScore(probabilities[0]?.[1] ?? null);
  }

  if (error) return <p>Modelo indisponível: {error.message}</p>;

  return (
    <button disabled={!isReady} onClick={() => onScore([1, 2, 3, 4])}>
      {isReady ? "Calcular score" : "Carregando modelo..."}
    </button>
  );
}
```

!!! tip "Versione o nome do arquivo"
    `classifier-v3.onnx`, não `classifier.onnx`. O cache do navegador não
    tem como saber que o conteúdo mudou, e um modelo velho servido do cache
    é o tipo de bug que ninguém liga ao deploy da semana passada. Com o
    pacote (`loadEdgePackage`) isso vem resolvido: a `version` do manifesto
    é derivada do conteúdo.

!!! danger "Exportar com `skl2onnx` na mão quebra no navegador"
    Medido: o default do `skl2onnx` deixa o **ZipMap** ligado, e a saída de
    probabilidade vira uma *sequência de mapas*. O ONNX Runtime Web recusa
    valores que não são tensor — `Reading data from non-tensor typed value is
    not supported` — e a predição morre em runtime, não no build.

    Use `export_sklearn_to_onnx` (ou `edge_pipeline`), que desliga o ZipMap.
    Se o `.onnx` veio de outra origem, o módulo detecta e o erro diz o que
    fazer em vez de repetir a mensagem do runtime.

## Pacote de borda: o manifesto que vem do Python

Do lado do Python, `edge_pipeline` publica um **diretório**, não um arquivo:

```text
dist/risk/
├── risk.onnx          o grafo
├── risk.onnx.gz       o mesmo, ~10% do tamanho
├── baseline.json      referência de deriva
└── manifest.json      o contrato
```

Sirva esse diretório como asset estático e o navegador lê o mesmo contrato:

```tsx
import { loadEdgePackage } from "tempest-react-sdk/tabular";

const pkg = await loadEdgePackage("/models/risk/");

console.log(pkg.featureNames); // ["age", "income", "tenure", "score"]
console.log(pkg.classes);      // ["0", "1", "2"]

const { probabilities } = await pkg.predictor.predict([[41, 5200, 3, 0.82]]);
console.log(pkg.explain(probabilities[0]!));
```

```text
[{ name: "2", score: 0.7484 }, { name: "0", score: 0.1564 }, { name: "1", score: 0.0952 }]
```

!!! danger "A ordem das colunas é o campo que salva você"
    Modelo alimentado com as features certas **na ordem errada** responde com
    confiança e errado. Não existe checagem em runtime que pegue isso — o
    tensor tem a largura certa, os números são plausíveis, e a resposta é
    lixo.

    `featureNames` vem do treino, gravado pelo `edge_pipeline`. Use-o para
    montar a linha a partir do seu formulário, em vez de confiar que a ordem
    do `<form>` bate com a do `DataFrame` de seis meses atrás.

!!! info "Modelo que nasceu de um `.pkl`"
    Se o pacote foi gerado por `edge_pipeline_from_pickle`, o manifesto traz
    `source` — nome, SHA-256 e a versão do scikit-learn que converteu:

    ```tsx
    const manifest = await fetchEdgeManifest("/models/risk/");
    console.log(manifest.source?.file, manifest.source?.sha256.slice(0, 12));
    ```

    O `.pkl` **não** viaja para o navegador, e não é limitação: pickle é
    programa Python, não dado. O que viaja é o ONNX mais o carimbo de qual
    arquivo o produziu — o suficiente para rastrear um modelo rodando numa
    aba de volta até a esteira, seis meses depois.

### Checar versão sem baixar o modelo

```tsx
import { fetchEdgeManifest } from "tempest-react-sdk/tabular";

const manifest = await fetchEdgeManifest("/models/risk/");
if (manifest.version !== localStorage.getItem("risk-version")) {
  // modelo novo publicado — vale baixar
}
```

O manifesto tem algumas centenas de bytes. A `version` é derivada do
conteúdo, então republicar os mesmos bytes **não** parece versão nova.

!!! info "Compatibilidade é explícita"
    O `schema_version` é conferido. Pacote escrito por um SDK mais novo do
    que este leitor entende é **recusado**, com a instrução de atualizar —
    ler assim mesmo arriscaria interpretar errado justamente o campo de
    ordem das colunas. Campos desconhecidos, ao contrário, são ignorados: um
    acréscimo compatível não quebra nada.

## Instalação

`onnxruntime-web` é **peer dependency opcional**: só quem usa esse subpath
instala.

```bash
npm install onnxruntime-web
```

!!! danger "Importe o pacote padrão, nunca `onnxruntime-web/webgpu`"
    Medido no Chromium: o build WebGPU carrega um binário WebAssembly **sem o
    domínio `ai.onnx.ml`**, e a sessão nem chega a abrir —
    `No Op registered for TreeEnsembleClassifier`.

    Modelos de scikit-learn são feitos desses operadores
    (`TreeEnsembleClassifier`, `LinearClassifier`, `Scaler`), então não há
    velocidade sobrando pra buscar na GPU: o backend `wasm` é o único que os
    implementa, e é o default do módulo. Quando o erro acontece, ele vira
    `UnsupportedGraphError` com a instrução de trocar o import.

## Offline de verdade

São **duas** coisas que precisam estar no dispositivo, e esquecer a segunda é
o erro clássico.

### O modelo

Fica em Cache Storage na primeira visita:

```tsx
import { fetchModelBytes, isModelCached } from "tempest-react-sdk/tabular";

const bytes = await fetchModelBytes("/models/classifier-v3.onnx");
const predictor = await TabularPredictor.create(bytes);

console.log(await isModelCached("/models/classifier-v3.onnx")); // true
```

Cache-first, não network-first: um arquivo de modelo é imutável para uma dada
versão, então revalidar a cada carga gasta uma ida à rede pra não aprender
nada. Publique versão nova sob URL nova (ou passe `revalidate: true`).

O hook faz isso sozinho quando a fonte é uma URL — `cache: false` desliga. O
nome do Cache Storage usado é `DEFAULT_MODEL_CACHE`, exportado para um botão de
"limpar modelos baixados" apagar exatamente o que o SDK criou.

### O runtime

```tsx
import { configureOrtAssets, ortAssetUrls } from "tempest-react-sdk/tabular";

configureOrtAssets("/ort/");
```

!!! warning "O ONNX Runtime Web não embute o WebAssembly — nem nos builds `.bundle`"
    Medido: servindo o app sem os `.wasm` ao lado, a criação da sessão falha
    com `Aborted(both async and sync fetching of the wasm failed)` — uma
    mensagem que não diz qual arquivo faltou. No Chromium o arquivo buscado
    foi `ort-wasm-simd-threaded.jsep.wasm`.

    Copie os binários de `node_modules/onnxruntime-web/dist/` para o seu
    diretório público no build, e precache junto:

    Os `.wasm` moram em `public/`, então o Vite não os emite no bundle e eles
    não entram sozinhos no manifest de precache. Liste-os em `additionalUrls`,
    no `vite.config.ts`:

    ```ts
    import { defineConfig } from "vite";
    import { tempestPwaManifest } from "tempest-react-sdk/vite";
    import { ortAssetUrls } from "tempest-react-sdk/tabular";

    export default defineConfig({
      plugins: [tempestPwaManifest({ additionalUrls: ortAssetUrls("/ort/") })],
    });
    ```

    O service worker então precacheia tudo pelo manifest, sem lista repetida:

    ```ts
    import { installPrecache } from "tempest-react-sdk/sw";

    installPrecache();
    ```

    Qual binário é buscado depende do suporte a threads e SIMD do navegador,
    então um app que precisa funcionar em todo lugar leva todos —
    `ORT_WASM_ASSETS` tem a lista.

## Detalhes que o módulo resolve por você

!!! info "Rótulo int64 chega como `bigint`"
    O ONNX Runtime Web devolve o tensor de rótulo como `BigInt64Array`. Quem
    compara `label === 1` recebe `false` em silêncio, e `JSON.stringify`
    lança. O módulo converte para `number` — índice de classe nunca chega
    perto de `Number.MAX_SAFE_INTEGER`.

!!! info "Qual saída é qual"
    Classificador devolve `label` + `probabilities`; regressor devolve um
    único `variable`. Indexar por posição funciona até o dia em que você
    publica o outro tipo. `predictor.info` diz o que foi carregado:

    ```ts
    console.log(predictor.info);
    // { inputName: "input", numFeatures: 4, isClassifier: true, ... }
    ```

!!! info "Linha de largura errada falha antes do runtime"
    `FeatureShapeError` nomeando a expectativa (`o modelo espera 4 features
    por linha, recebeu 2`), em vez de um erro opaco vindo do WebAssembly.
    Lote irregular também: o erro diz **qual linha**.

## Erros

Todos herdam de `TabularError`, então dá pra pegar a família inteira. O
`name` é literal — o minificador renomeia classes, e um build real reportava
`error.name === "t"` antes disso ser corrigido.

| Erro | Quando |
| --- | --- |
| `UnsupportedGraphError` | Runtime sem os operadores `ai.onnx.ml` (build WebGPU) |
| `ModelLoadError` | Bytes não viraram sessão |
| `ModelFetchError` | Offline e nada em cache — problema de deploy, não de modelo |
| `FeatureShapeError` | Lote vazio, irregular ou da largura errada |
| `InferenceError` | Rodou mas a saída não é legível (export com ZipMap) |
| `CompactFormatError` | Pacote em formato compacto cujo cabeçalho o leitor não reconhece |

## API

| Símbolo | O que é |
| --- | --- |
| `TabularPredictor.create(source, options?)` | Carrega um modelo (URL ou bytes) |
| `predictor.predict(rows)` | Prediz um lote; devolve `labels`, `probabilities`, `ms` |
| `predictor.info` | Entrada, nº de features, saídas, providers em uso |
| `predictor.dispose()` | Libera a sessão |
| `useTabularPredictor(source, options?)` | Hook com `status`/`isReady`/`predict`/`reload` |
| `loadEdgePackage(directoryUrl, options?)` | Carrega um pacote publicado pelo `edge_pipeline` |
| `configureOrtAssets(path)` / `configuredOrtAssetPath()` | Define de onde os `.wasm` do ORT são servidos, e lê de volta o que está valendo |
| `fetchEdgeManifest(directoryUrl)` | Só o manifesto — versão, colunas, classes |
| `fetchModelBytes(url, options?)` | Bytes do cache, com rede como fallback |
| `isModelCached(url)` / `cacheModelBytes` / `clearModelCache` | Gestão do cache |
| `configureOrtAssets(basePath)` / `ortAssetUrls(basePath)` / `ORT_WASM_ASSETS` | Assets do runtime |
| `DEFAULT_TABULAR_PROVIDERS` | `["wasm"]`, pelo motivo acima |

## Recapitulando

- Exporte com `export_sklearn_to_onnx` — ZipMap ligado não roda no navegador.
- Importe `onnxruntime-web`, **não** o subpath `/webgpu`.
- Sirva o `.onnx` como asset versionado; o cache cuida do resto.
- Copie e precache os `.wasm`, senão "offline" só funciona online.
- Use o hook em componente; a classe direto em worker ou fora do React.

---

# telemetry.md

# Telemetry

Toda app precisa de telemetria — identificar usuários, rastrear eventos, capturar exceções — mas você não quer espalhar chamadas de `Sentry.captureException` ou `posthog.capture` por todo o código. Se um dia trocar de provider, teria que caçar cada callsite. O módulo `telemetry` resolve isso com uma **interface mínima** que isola o app do provider real (Sentry, PostHog, Datadog, custom). Você programa contra a interface; o provider é injetado uma vez, na raiz.

Adapters concretos para os providers mais comuns vêm prontos no SDK; nenhum deles é peer dep — o **caller injeta a instância** do SDK externo, então você instala apenas o que usa.

!!! info "Por que injetar a instância em vez de declarar peer dep"
    Apps que já inicializam o Sentry no startup (DSN, sample rate, integrações)
    querem reusar _aquela_ instância — não uma criada pelo SDK. E apps que não
    usam Sentry não devem pagar por ele no bundle. Por isso cada
    `create<Provider>Adapter` recebe a instância pronta no options
    (`{ sentry: Sentry }`, `{ posthog }`).

## Interface

```ts
import type { TelemetryAdapter, TelemetryEvent, TelemetryUser } from "tempest-react-sdk";

interface TelemetryAdapter {
  init?: () => void | Promise<void>;
  identify: (user: TelemetryUser | null) => void;
  track: (event: TelemetryEvent) => void;
  captureException: (error: unknown, context?: Record<string, unknown>) => void;
  flush?: () => Promise<void> | void;
}

interface TelemetryUser {
  id?: string;
  email?: string;
  name?: string;
  traits?: Record<string, unknown>;
}

interface TelemetryEvent {
  name: string;
  properties?: Record<string, unknown>;
}
```

## Provider

```tsx
import { TelemetryProvider, consoleTelemetryAdapter } from "tempest-react-sdk";

<TelemetryProvider adapter={consoleTelemetryAdapter}>{children}</TelemetryProvider>;
```

`consoleTelemetryAdapter` é o default para dev/teste — loga cada chamada no `console`.

`TelemetryProvider` invoca `adapter.init?.()` no mount e `adapter.flush?.()` no unmount.

## Uso em componentes

```tsx
import { useTelemetry } from "tempest-react-sdk";

const telemetry = useTelemetry();
telemetry?.track({ name: "alo_purchased", properties: { aloId, valueBRL: 990 } });
```

`useTelemetry()` retorna `null` quando não há provider montado — a UI não quebra em testes.

!!! warning "Sempre use optional chaining"
    `useTelemetry()` devolve `null` fora de um `<TelemetryProvider>`. Chame
    sempre com `?.` (`telemetry?.track(...)`) — assim os callsites continuam
    funcionando em testes unitários e em árvores que não montam o provider, sem
    explodir com "cannot read property of null".

## Setup completo — adapter + provider + identify + track

Um app real inicializa o adapter na raiz, identifica o usuário no login e rastreia eventos nas ações. Esqueleto completo e copiável:

```tsx
// telemetry.tsx
import posthog from "posthog-js";
import { createPostHogTelemetryAdapter, TelemetryProvider } from "tempest-react-sdk";
import type { ReactNode } from "react";

export const telemetryAdapter = createPostHogTelemetryAdapter({
  posthog,
  init: {
    apiKey: import.meta.env.VITE_POSTHOG_KEY,
    options: { api_host: "https://us.i.posthog.com" },
  },
});

export function AppTelemetry({ children }: { children: ReactNode }) {
  return <TelemetryProvider adapter={telemetryAdapter}>{children}</TelemetryProvider>;
}
```

```tsx
// useSessionTelemetry.ts — identifica/reseta quando a sessão muda
import { useEffect } from "react";
import { useTelemetry } from "tempest-react-sdk";
import { useAuthStore } from "./auth-store";

export function useSessionTelemetry() {
  const telemetry = useTelemetry();
  const user = useAuthStore((s) => s.user);

  useEffect(() => {
    if (user) {
      telemetry?.identify({ id: user.id, email: user.email, name: user.name });
    } else {
      telemetry?.identify(null); // logout → reset
    }
  }, [telemetry, user]);
}
```

```tsx
// CheckoutButton.tsx — rastreia um evento de negócio
import { useTelemetry, Button } from "tempest-react-sdk";

export function CheckoutButton({ aloId, valueBRL }: { aloId: string; valueBRL: number }) {
  const telemetry = useTelemetry();
  return (
    <Button
      onClick={() => {
        telemetry?.track({ name: "alo_purchased", properties: { aloId, valueBRL } });
      }}
    >
      Comprar
    </Button>
  );
}
```

## Sentry adapter

Wrap `@sentry/browser` (ou `@sentry/react`) — o SDK Sentry é passado pelo caller, não vira peer dep.

```ts
import * as Sentry from "@sentry/browser";
import { createSentryTelemetryAdapter, TelemetryProvider } from "tempest-react-sdk";

const adapter = createSentryTelemetryAdapter({
    sentry: Sentry,
    initOptions: {
        dsn: import.meta.env.VITE_SENTRY_DSN,
        environment: import.meta.env.MODE,
        tracesSampleRate: 0.1,
    },
    flushTimeout: 2000,        // default
    breadcrumbCategory: "app", // default
});

<TelemetryProvider adapter={adapter}>{children}</TelemetryProvider>;
```

Mapeamento:

| `TelemetryAdapter`           | `@sentry/browser`                                                  |
| ---------------------------- | ------------------------------------------------------------------ |
| `init()`                     | `Sentry.init(initOptions)` (apenas quando `initOptions` é passado) |
| `identify(user)`             | `Sentry.setUser({id, email, username, ...traits})`                 |
| `identify(null)`             | `Sentry.setUser(null)`                                             |
| `track({name, properties})`  | `Sentry.addBreadcrumb({category, message, level:"info", data})`    |
| `captureException(err, ctx)` | `Sentry.captureException(err, { extra: ctx })`                     |
| `flush()`                    | `Sentry.flush(flushTimeout)`                                       |

O tipo `SentryLike` é exportado pra você mockar em testes:

```ts
import type { SentryLike } from "tempest-react-sdk";

const fakeSentry: SentryLike = {
  setUser: vi.fn(),
  addBreadcrumb: vi.fn(),
  captureException: vi.fn(),
};
```

## PostHog adapter

Wrap `posthog-js`.

```ts
import posthog from "posthog-js";
import { createPostHogTelemetryAdapter, TelemetryProvider } from "tempest-react-sdk";

const adapter = createPostHogTelemetryAdapter({
    posthog,
    init: {
        apiKey: import.meta.env.VITE_POSTHOG_KEY,
        options: { api_host: "https://us.i.posthog.com" },
    },
});

<TelemetryProvider adapter={adapter}>{children}</TelemetryProvider>;
```

Mapeamento:

| `TelemetryAdapter`           | `posthog-js`                                                                                            |
| ---------------------------- | ------------------------------------------------------------------------------------------------------- |
| `init()`                     | `posthog.init(apiKey, options)` (apenas quando `init` é passado)                                        |
| `identify({id, ...})`        | `posthog.identify(id, { email, name, ...traits })` (skip se `id` ausente)                               |
| `identify(null)`             | `posthog.reset()`                                                                                       |
| `track({name, properties})`  | `posthog.capture(name, properties)`                                                                     |
| `captureException(err, ctx)` | `posthog.captureException(err, ctx)` quando disponível, fallback `posthog.capture("$exception", {...})` |

!!! tip "`SentryLike` / `PostHogLike` são subsets, não os SDKs inteiros"
    Cada adapter declara só os métodos que usa (`setUser`, `addBreadcrumb`,
    `capture`…). Isso te dá um alvo minúsculo para mockar em testes — você
    monta um objeto com 3 `vi.fn()` em vez de stubar o SDK completo — e mantém
    o adapter resiliente a mudanças de API que não tocam esse subset.

## Adapter custom

Para Datadog, Amplitude, Mixpanel — escreva ~20 linhas:

```ts
import type { TelemetryAdapter } from "tempest-react-sdk";
import { datadogRum } from "@datadog/browser-rum";

export const datadogAdapter: TelemetryAdapter = {
  init: () => datadogRum.init({ clientToken: "...", applicationId: "...", site: "datadoghq.com" }),
  identify: (user) =>
    user ? datadogRum.setUser({ id: user.id, email: user.email }) : datadogRum.clearUser(),
  track: ({ name, properties }) => datadogRum.addAction(name, properties),
  captureException: (error, context) => datadogRum.addError(error, context),
};
```

## Integração com ErrorBoundary

```tsx
const telemetry = useTelemetry();

<ErrorBoundary onError={(err, info) => telemetry?.captureException(err, info)}>
  {children}
</ErrorBoundary>;
```

## Resumo

- **Programe contra `TelemetryAdapter`**, não contra o SDK do provider — troca de provider = troca de uma linha na raiz.
- **`TelemetryProvider`** injeta o adapter; chama `init` no mount, `flush` no unmount.
- **`useTelemetry()` pode ser `null`** — sempre `telemetry?.track(...)` com optional chaining.
- **Adapters injetam a instância** (`{ sentry }`, `{ posthog }`) — nunca peer dep.
- **Adapter custom** é ~20 linhas mapeando 4 métodos.

### Veja também

- [Error Boundary](./error-boundary.md) — `onError` → `captureException`
- [Logger](./logger.md) — logs estruturados locais
- [Feature Flags](./feature-flags.md) — adapters seguem exatamente o mesmo padrão de injeção

---

# testing.md

# Testing helpers (`tempest-react-sdk/testing`)

Subpath bundle separado, opt-in via `tempest-react-sdk/testing`. Sem peer dep MSW — output é puro data-shape.

## Por que um subpath de testes?

Mockar respostas HTTP é o caso de teste mais comum num app que consome o SDK
(testar `createApiClient`, telas que fazem fetch, etc.). O problema é que cada
time escolhe um harness diferente — `msw`, stub de `fetch` no vitest, `nock`. Se
o SDK declarasse `msw` como peer dep, forçaria essa escolha em todo mundo.

A solução é um helper **data-shape**: você descreve os fixtures uma vez
(`{ method, path, status, body }`) e converte pro seu harness com um `map` de
poucas linhas. Por ser só dado, ele vive num subpath separado
(`tempest-react-sdk/testing`) que **não entra no bundle de produção** do app.

!!! tip "Importe do subpath, não do barrel raiz"
    `createMockHandlers` só existe em `tempest-react-sdk/testing`. Ele nunca é
    re-exportado do `tempest-react-sdk` principal — assim código de teste jamais
    vaza pro bundle de produção.

## `createMockHandlers`

Factory MSW-shaped. Define fixtures em um lugar só, alimente em `msw`/`vi.fn`/custom harness.

```ts
import { createMockHandlers } from "tempest-react-sdk/testing";

const fixtures = createMockHandlers([
  { method: "GET", path: "/users/me", status: 200, body: { id: "u1", name: "Mauricio" } },
  { method: "POST", path: "/orders", status: 201, body: { id: "o1" } },
  { method: "GET", path: "/explode", status: 500, body: { detail: "kaboom" } },
  { method: "GET", path: "/slow", body: { ok: true }, delayMs: 300 },
]);
```

### Tipo

```ts
type MockHandlerMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";

interface MockHandlerInput {
  method: MockHandlerMethod;
  path: string;
  status?: number; // default 200
  body?: unknown; // default null
  headers?: Record<string, string>; // default { "Content-Type": "application/json" }
  delayMs?: number; // default 0
}

interface MockHandler {
  method: MockHandlerMethod;
  path: string;
  status: number;
  body: unknown;
  headers: Record<string, string>;
  delayMs: number;
}
```

### Integrando com MSW

```ts
import { http, HttpResponse, delay } from "msw";
import { setupServer } from "msw/node";
import { createMockHandlers } from "tempest-react-sdk/testing";

const fixtures = createMockHandlers([{ method: "GET", path: "/users/me", body: { id: "u1" } }]);

const handlers = fixtures.map((f) => {
  const httpMethod = f.method.toLowerCase() as "get" | "post" | "put" | "patch" | "delete";
  return http[httpMethod](f.path, async () => {
    if (f.delayMs > 0) await delay(f.delayMs);
    return HttpResponse.json(f.body, { status: f.status, headers: f.headers });
  });
});

export const server = setupServer(...handlers);
```

### Integrando com vitest fetch stub

```ts
import { vi } from "vitest";
import { createMockHandlers } from "tempest-react-sdk/testing";

const fixtures = createMockHandlers([
  { method: "POST", path: "/login", status: 401, body: { detail: "bad creds" } },
]);

global.fetch = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {
  const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
  const method = (init?.method ?? "GET").toUpperCase();
  const match = fixtures.find((f) => url.endsWith(f.path) && f.method === method);
  if (!match) return new Response(null, { status: 404 });
  return new Response(JSON.stringify(match.body), {
    status: match.status,
    headers: match.headers,
  });
});
```

!!! tip "Restaure o `fetch` entre testes"
    Sob `vitest + jsdom`, sobrescrever `global.fetch` num teste vaza pros
    seguintes. Coloque `vi.restoreAllMocks()` (ou reatribua o `fetch` original)
    num `afterEach` para isolar cada caso.

!!! note "`delayMs` testa estados de loading"
    O campo `delayMs` (default `0`) existe pra você exercitar spinners e
    skeletons. No exemplo MSW, o `await delay(f.delayMs)` aplica esse atraso;
    no stub de `fetch`, envolva o retorno num `setTimeout`/`await` equivalente.

## Exemplo completo — testando `createApiClient`

Programa copiável de ponta a ponta: fixtures → MSW server → asserção sobre o
client do SDK.

```ts
import { afterAll, afterEach, beforeAll, expect, it } from "vitest";
import { http, HttpResponse, delay } from "msw";
import { setupServer } from "msw/node";
import { createMockHandlers } from "tempest-react-sdk/testing";
import { createApiClient } from "tempest-react-sdk";

const fixtures = createMockHandlers([
  { method: "GET", path: "/users/me", body: { id: "u1", name: "Mauricio" } },
  { method: "GET", path: "/explode", status: 500, body: { detail: "kaboom" } },
]);

const server = setupServer(
  ...fixtures.map((f) => {
    const method = f.method.toLowerCase() as "get" | "post" | "put" | "patch" | "delete";
    return http[method](`https://api.test${f.path}`, async () => {
      if (f.delayMs > 0) await delay(f.delayMs);
      return HttpResponse.json(f.body, { status: f.status, headers: f.headers });
    });
  }),
);

beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

const api = createApiClient({ baseURL: "https://api.test" });

it("resolves the happy path", async () => {
  const me = await api.get("/users/me");
  expect(me).toEqual({ id: "u1", name: "Mauricio" });
});

it("surfaces the error path", async () => {
  await expect(api.get("/explode")).rejects.toThrow();
});
```

## Por que não declarar `msw` como peer

- Apps que usam vitest fetch stub / nock / outros não precisam de msw.
- Apps que usam msw já têm a versão fixada — declarar peer adicionaria conflito sem benefício.
- O output do helper é trivialmente convertível pra qualquer harness — 5 linhas de map.

## Recap

- `createMockHandlers` é um helper **data-shape** num subpath separado
  (`tempest-react-sdk/testing`) — fora do bundle de produção.
- Você descreve fixtures uma vez (`{ method, path, status, body, headers, delayMs }`)
  e converte pro seu harness (MSW, stub de `fetch`, nock) com um `map` curto.
- Defaults: `status` 200, `body` `null`, `headers` `Content-Type: application/json`,
  `delayMs` 0.
- `msw` **não** é peer dep — o caller fixa a própria versão; restaure o `fetch`
  entre testes; use `delayMs` pra exercitar estados de loading.

## Veja também

- [HTTP client](./http.md) — testar `createApiClient` é o caso de uso mais comum.

---

# theme.md

# Tema (dark / light)

`ThemeProvider` decide o tema efetivo e escreve `data-tempest-theme="dark"` (ou `"light"`) em `<html>`. Os tokens CSS `--tempest-*` reagem a esse atributo, então **trocar o tema é trocar um atributo** — nenhum componente precisa saber que o tema mudou. Veja os tokens em [`src/styles/colors.css`](https://github.com/mauriciobenjamin700/tempest-react-sdk/blob/main/src/styles/colors.css).

!!! info "Por que um atributo, e não `class=\"dark\"`?"
    Usar `data-tempest-theme` (em vez da convenção `class="dark"`) evita colisão com classes do app e permite escopo parcial: você pode aplicar um tema diferente em uma subárvore (preview, portal, docs) sem afetar o resto da página. É a única forma de tema suportada pelo SDK.

## Setup

Envolva a árvore com `ThemeProvider`. O modo padrão é `"system"`, que segue a preferência do sistema operacional:

```tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { ThemeProvider } from "tempest-react-sdk";
import "tempest-react-sdk/styles.css";
import { App } from "./App";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <ThemeProvider defaultTheme="system">
      <App />
    </ThemeProvider>
  </StrictMode>,
);
```

Modos disponíveis: `"light"`, `"dark"`, `"system"`. Em `"system"`, o provider escuta `prefers-color-scheme` e reage a mudanças do SO em tempo real. A escolha do usuário é persistida em `localStorage["tempest-theme"]` (desative com `storageKey={null}`).

## Toggle de tema

`useTheme()` lê e muta o tema. Um botão completo de alternância:

```tsx
import { useTheme } from "tempest-react-sdk";

export function ThemeToggle() {
  const { theme, resolvedTheme, setTheme, toggle } = useTheme();

  return (
    <div>
      <button onClick={toggle}>{resolvedTheme === "dark" ? "🌙 Escuro" : "☀️ Claro"}</button>

      {/* ou controle os três modos explicitamente */}
      <select value={theme} onChange={(event) => setTheme(event.target.value as typeof theme)}>
        <option value="light">Claro</option>
        <option value="dark">Escuro</option>
        <option value="system">Sistema</option>
      </select>
    </div>
  );
}
```

O que cada campo significa:

- `theme`: a **preferência crua** do usuário — `"light"`, `"dark"` ou `"system"`.
- `resolvedTheme`: o tema **efetivamente aplicado** — sempre `"light"` ou `"dark"` (nunca `"system"`).
- `setTheme(next)`: grava a preferência (e persiste).
- `toggle()`: inverte o `resolvedTheme`. Em modo `"system"`, alterna para o oposto do que está aplicado.

!!! tip "Use `resolvedTheme` para renderizar, `theme` para o seletor"
    Quando precisar decidir qual ícone/imagem mostrar, leia `resolvedTheme` (é sempre concreto). Reserve `theme` para refletir a escolha no seletor de três opções.

## No-flash (evitar o flash do tema errado)

Há um problema clássico: o HTML pinta antes do React montar, então por um instante o usuário vê o tema padrão antes de o `ThemeProvider` corrigir. A solução é um script síncrono inline no `<head>`, **antes de qualquer CSS**, que aplica o atributo na primeira pintura.

`themeInitScript()` devolve exatamente esse trecho. Em um `index.html` Vite:

```html
<!doctype html>
<html lang="pt-BR">
  <head>
    <meta charset="UTF-8" />
    <!-- Aplica data-tempest-theme antes de pintar. Cole a saída de themeInitScript() aqui. -->
    <script>
      (function () {
        try {
          var key = "tempest-theme";
          var def = "system";
          var stored = localStorage.getItem(key);
          var mode = stored || def;
          var resolved =
            mode === "dark" || mode === "light"
              ? mode
              : matchMedia("(prefers-color-scheme: dark)").matches
                ? "dark"
                : "light";
          document.documentElement.setAttribute("data-tempest-theme", resolved);
        } catch (e) {}
      })();
    </script>
  </head>
  <body>
    <div id="root"></div>
    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>
```

Se você renderiza o HTML por SSR/React (Next, Remix, etc.), injete via `dangerouslySetInnerHTML` para manter a string gerada em sincronia com o SDK:

```tsx
import { themeInitScript } from "tempest-react-sdk";

export function Head() {
  return <script dangerouslySetInnerHTML={{ __html: themeInitScript() }} />;
}
```

!!! warning "O script precisa ser síncrono e vir cedo"
    Não use `defer`, `async` nem mova o script para o fim do `<body>` — ele tem que rodar antes da primeira pintura, senão o flash volta. `getInitialTheme()` expõe a mesma lógica de resolução para quando você quiser o tema calculado em JS sem injetar o script.

## Customizando tokens

Os tokens `--tempest-*` são a única API de tema. Sobrescreva-os em qualquer ponto da cascata — um para o tema claro, outro dentro do seletor de tema escuro:

```css
:root {
  --tempest-primary: #ff3366;
  --tempest-radius-md: 6px;
}

[data-tempest-theme="dark"] {
  --tempest-primary: #ff6688;
}
```

!!! note "Tokens são API pública"
    Como apps dependem desses nomes, mudar/remover um token é breaking change — por isso eles seguem o versionamento semântico do SDK.

## `createTheme` — a marca inteira a partir de uma cor

Sobrescrever token por token funciona pra um ajuste pontual. Pra **trocar a marca**, são ~30 valores só de `primary` (dez degraus × claro/escuro, mais os aliases de hover/active/soft) — e é fácil errar a inversão do ramp no dark. `createTheme` gera tudo:

```tsx
import { applyTheme, createTheme } from "tempest-react-sdk";

const theme = createTheme({ primary: "#7c3aed" });

applyTheme(theme);
```

Pronto: os 104 componentes passam a usar a marca nova, no claro e no escuro.

### O que ele gera

```ts
const theme = createTheme({
  primary: "#7c3aed",          // escala 50→900 + hover/active/soft/foreground/focus-ring
  gray: "#6b7280",             // superfícies, bordas e texto
  success: "#16a34a",          // cada status vira -fg / -bg / -border / -solid
  danger: "#dc2626",
  chart: ["#7c3aed", "#0ea5e9", "#22c55e"],  // --tempest-chart-1..N + -count (ver Charts)
  radius: "lg",                // "none" | "sm" | "md" | "lg" | "xl" | "full"
  focusRingAlpha: 0.35,
});

theme.light; // { "--tempest-primary-500": "#7c3aed", … } — a sua cor, exata
theme.dark;  // idem, com o ramp invertido
theme.css;   // ":root { … }\n\n[data-tempest-theme=\"dark\"] { … }"
```

Só as famílias que você passa são geradas — o resto continua vindo do `colors.css` do SDK. Um tema é um **patch**, não um fork da paleta.

!!! check "O degrau `500` é exatamente a cor que você passou"
    A escala é **ancorada** no `500`: a lightness da sua marca vira o ponto fixo e
    as duas metades do ramp são reescaladas em volta dela. Sem isso o `500` era
    forçado na lightness alvo da curva e `#7c3aed` voltava como `#9161fe` — mesma
    matiz, mesma croma, **re-clareado**. Parece bom isolado e está errado de todo
    jeito: a única cor que o designer entregou é justamente a que os botões
    precisam ter. Marca muito clara (amarelo) ou muito escura (navy) simplesmente
    ganha um trecho mais curto do lado apertado, e o ramp continua monótono.

!!! info "Por que OKLCH e não HSL"
    A escala é derivada em OKLCH porque lightness em HSL **não é perceptual**: um amarelo e um azul com o mesmo `L` em HSL têm brilho visivelmente diferente, e é exatamente isso que faz uma paleta gerada parecer "quebrada" em algumas cores. Em OKLCH o degrau `500` de qualquer marca ocupa o mesmo lugar visual.

!!! tip "O passo de texto sobre a tinta soft é medido, não convencionado"
    `--tempest-primary-on-soft` não é fixo no `600`: o SDK **mede** o contraste contra a tinta `50` e desce no ramp até passar de 4.5:1 (AA para texto). Isso não é preciosismo — o azul padrão só alcança 4.37:1 no `500` sobre a própria tinta, e um emerald gerado para em 4.41:1 no `600`. Os dois reprovariam AA por um fio.

### Presets prontos

```tsx
import { applyTheme, createTheme, themePresets } from "tempest-react-sdk";

applyTheme(createTheme(themePresets.violet));

// ou partindo de um e ajustando
applyTheme(createTheme({ ...themePresets.emerald, radius: "full" }));
```

Presets disponíveis: `tempest` (o default do SDK), `violet`, `emerald`, `rose`, `slate`, `amber`. Cada um é um objeto de opções — dado, não CSS —, então dá pra guardar o nome escolhido em `localStorage` e resolver com `getThemePreset(name)` (que devolve `undefined` para nome inválido em vez de explodir no boot).

### Trocando de tema em runtime

```tsx
import { applyTheme, createTheme, getThemePreset } from "tempest-react-sdk";
import { useEffect, useState } from "react";

export function BrandPicker() {
  const [brand, setBrand] = useState(() => localStorage.getItem("brand") ?? "tempest");

  useEffect(() => {
    const preset = getThemePreset(brand);
    if (!preset) return;
    localStorage.setItem("brand", brand);
    return applyTheme(createTheme(preset));
  }, [brand]);

  return (
    <select value={brand} onChange={(event) => setBrand(event.target.value)}>
      {["tempest", "violet", "emerald", "rose", "slate", "amber"].map((name) => (
        <option key={name} value={name}>{name}</option>
      ))}
    </select>
  );
}
```

`applyTheme` é **idempotente**: ele é dono de um `<style id="tempest-theme">` e reescreve o conteúdo, então um seletor de marca pode ser acionado à vontade sem empilhar folhas mortas no `<head>`. O retorno é o disposer (usado como cleanup do effect acima).

!!! tip "Tema escopado numa subárvore"
    Passe `selector`/`darkSelector` no `createTheme` e `id`/`target` no `applyTheme` pra pintar só um pedaço da tela — útil pra preview de marca:

    ```tsx
    applyTheme(
      createTheme({ primary: "#e11d48", selector: ".preview", darkSelector: '.preview[data-tempest-theme="dark"]' }),
      { id: "preview-theme" },
    );
    ```

### Sem JS: cole o CSS gerado

`theme.css` é texto. Se você prefere um tema estático (zero JS no caminho crítico), gere uma vez e cole no CSS global do app:

```bash
node -e "import('tempest-react-sdk').then(({ createTheme }) => console.log(createTheme({ primary: '#7c3aed' }).css))" > src/brand.css
```

### Auditando o contraste da sua marca

```ts
import { contrastRatio, createColorScale, themeContrast } from "tempest-react-sdk";

themeContrast({ primary: "#fde047" }); // 15.2 — texto escuro foi escolhido automaticamente

const scale = createColorScale("#7c3aed");
contrastRatio(scale[500], "#ffffff");  // asserte no seu teste, se a marca é requisito
```

`--tempest-primary-foreground` (e `--tempest-text-on-primary`) é escolhido por contraste medido entre branco e o cinza escuro — hardcodar branco produziria botões ilegíveis em marcas claras (amarelo, lima, ciano).

### As conversões de cor, avulsas

O `createTheme` faz o trabalho todo, mas as conversões que ele usa por dentro
são exportadas para quando você precisa de uma só — clarear um badge, gerar um
overlay, comparar duas cores no seu próprio teste:

```ts
import { hexToOklch, hexToRgb, hexToRgbaString, oklchToHex } from "tempest-react-sdk";

const { l, c, h } = hexToOklch("#7c3aed"); // luminosidade, croma, matiz
oklchToHex({ l: l + 0.1, c, h }); // 10% mais claro, mesma matiz e saturação

hexToRgbaString("#7c3aed", 0.12); // "rgb(124 58 237 / 0.12)" — overlay/hover
hexToRgb("#7c3aed"); // { r, g, b } em 0–1, para cálculo próprio
rgbToHex({ r: 0.49, g: 0.23, b: 0.93 }); // de volta para "#7c3aed"
```

Duas outras vêm do lado do contraste, e são as que o `createTheme` usa para
escolher um foreground legível em vez de fixar branco:

```ts
import { readableForeground, relativeLuminance } from "tempest-react-sdk";

relativeLuminance("#fde047"); // 0.83 — luminância relativa WCAG, a entrada do contrastRatio
readableForeground("#fde047"); // o foreground escuro: branco nesse amarelo é ilegível
```

!!! info "Por que OKLCH e não HSL"
    Clarear em HSL muda a cor percebida: `hsl(240 100% 50%)` e
    `hsl(60 100% 50%)` têm a mesma "luminosidade" declarada e brilhos
    completamente diferentes aos olhos. OKLCH é perceptualmente uniforme, então
    `l + 0.1` clareia o mesmo tanto em qualquer matiz — é por isso que a escala
    do `createTheme` sai regular em vez de embolar nos amarelos.
    `oklchToHex` ainda reduz o croma até a cor caber no gamut sRGB, em vez de
    devolver um hex recortado.

## Integração com o CSS do app + `theme-color`

Os componentes do SDK leem `data-tempest-theme`. Se o **CSS próprio do seu app** já chaveia o tema em outro atributo (ex.: `[data-theme="dark"]`), você não precisa de um effect de sincronização — passe um array em `attribute` e o provider escreve o tema resolvido em **todos**:

```tsx
<ThemeProvider attribute={["data-tempest-theme", "data-theme"]}>
  <App />
</ThemeProvider>
```

Para sincronizar a barra do navegador / status bar do PWA, passe `themeColor` — o provider atualiza `<meta name="theme-color">` com a cor do tema resolvido (a meta tag precisa existir no `<head>`):

```tsx
<ThemeProvider themeColor={{ light: "#1f7a3f", dark: "#0f1411" }}>
  <App />
</ThemeProvider>
```

!!! tip "Por que isso existe"
    Antes, apps que misturavam CSS próprio + componentes do SDK escreviam um hook só pra espelhar o tema em `data-theme` e atualizar a meta tag. `attribute` (array) + `themeColor` cobrem os dois casos no próprio provider.

## Escopo parcial

Passe `target` para aplicar o tema em uma subárvore específica em vez de `<html>` — útil para um preview ou portal que precisa de tema independente:

```tsx
<ThemeProvider target={() => document.getElementById("preview")} defaultTheme="dark">
  <Preview />
</ThemeProvider>
```

## Recap

- `ThemeProvider` escreve `data-tempest-theme` no `<html>` (ou no elemento de `target`); os tokens `--tempest-*` reagem sozinhos.
- Modos: `"light"`, `"dark"`, `"system"` — o último segue `prefers-color-scheme` ao vivo. A escolha persiste em `localStorage["tempest-theme"]`.
- `useTheme()` dá `theme` (preferência crua), `resolvedTheme` (sempre `light`/`dark`), `setTheme` e `toggle`.
- Inline o `themeInitScript()` **síncrono no `<head>`, antes do CSS**, para eliminar o flash do tema errado.
- Customize o visual sobrescrevendo os tokens `--tempest-*`; use `target` para tema em subárvore.

## Veja também

- [Componentes](./components.md) — todos consomem os tokens
- [Estilos](./styles.md) — catálogo completo dos tokens `--tempest-*`
- [App Providers](./app-providers.md) — montar o tema junto com Query e i18n

---

# tutorial/auth-flow.md

# Tutorial — Fluxo de autenticação

Você já tem todas as peças soltas: a store de auth ([Estado](state.md)), o guard
de rota ([Roteamento](routing.md)), o cliente HTTP ([Buscando dados](data-fetching.md))
e os formulários validados ([Formulários](forms.md)). Nesta página final a gente
**costura tudo** num fluxo completo: login → área protegida → logout, mais o
logout automático quando o backend responde **401**.

## O ciclo completo, em uma imagem

```text
1. Usuário abre /dashboard sem sessão
        → guard lê useAuth.getState().isAuthenticated (false)
        → redirect pra /login
2. Usuário envia o login
        → api.post("/auth/login")  → { user, token }
        → useAuth.use.setSession({ user, token })
        → navigate("/dashboard")
3. guard agora lê isAuthenticated === true → mostra o Dashboard
4. Qualquer chamada que volte 401
        → onUnauthorized → useAuth.getState().logout()
        → guard volta a redirecionar pra /login
5. Usuário clica em "Sair"
        → useAuth.use.logout() → volta pro passo 1
```

Cada passo usa exatamente uma peça que você já construiu. Vamos montá-las.

## Passo 1 — A store e o cliente (recapitulando)

Estes dois arquivos já existem das páginas anteriores. Eles são a fundação do
fluxo — repare como o cliente lê e limpa a **mesma** store:

```ts
// src/stores/auth.ts
import { createAuthStore, createSelectors } from "tempest-react-sdk";

export interface User {
  id: string;
  name: string;
  email: string;
}

export const useAuth = createSelectors(
  createAuthStore<User>({ name: "app-auth", storage: "local" }),
);
```

```ts
// src/lib/api.ts
import { createApiClient } from "tempest-react-sdk";
import { useAuth } from "@/stores/auth";

export const api = createApiClient({
  baseURL: import.meta.env.VITE_API_URL,
  getToken: () => useAuth.getState().token,
  onUnauthorized: () => useAuth.getState().logout(),
});
```

O `getToken` injeta o token em cada requisição; o `onUnauthorized` desloga quando
o backend recusa o token. Ambos leem a store fora do React com `getState()`.

## Passo 2 — A tela de login

O login chama o backend, recebe `{ user, token }`, grava a sessão com
`setSession` e navega pro dashboard. Reusamos `useZodForm` + `FormField` do
capítulo de formulários:

```tsx
// src/pages/Login.tsx
import { useState } from "react";
import {
  useZodForm,
  FormProvider,
  Form,
  FormField,
  FormActions,
  Input,
  Button,
  useNavigate,
} from "tempest-react-sdk";
import { z } from "zod";
import { api } from "@/lib/api";
import { useAuth, type User } from "@/stores/auth";

const loginSchema = z.object({
  email: z.string().email("E-mail inválido"),
  password: z.string().min(1, "Informe a senha"),
});

type LoginValues = z.infer<typeof loginSchema>;

export function Login() {
  const navigate = useNavigate();
  const setSession = useAuth.use.setSession();
  const [failed, setFailed] = useState(false);

  const form = useZodForm(loginSchema, {
    defaultValues: { email: "", password: "" },
  });

  async function onSubmit(values: LoginValues) {
    setFailed(false);
    try {
      const session = await api.post<{ user: User; token: string }>("/auth/login", {
        body: values,
      });
      setSession(session);
      navigate("/dashboard");
    } catch {
      setFailed(true);
    }
  }

  return (
    <FormProvider {...form}>
      <Form layout="stack" gap={4} onSubmit={form.handleSubmit(onSubmit)}>
        <FormField name="email" label="E-mail" required>
          <Input type="email" />
        </FormField>
        <FormField name="password" label="Senha" required>
          <Input type="password" />
        </FormField>
        {failed && <p role="alert">E-mail ou senha inválidos.</p>}
        <FormActions align="end">
          <Button type="submit" loading={form.formState.isSubmitting}>
            Entrar
          </Button>
        </FormActions>
      </Form>
    </FormProvider>
  );
}
```

Peça por peça:

- `setSession({ user, token })` é a **única** ação que liga a sessão: ela grava o
  usuário e o token e re-deriva `isAuthenticated` pra `true`.
- `navigate("/dashboard")` leva pro destino protegido — que agora abre, porque o
  guard vê `isAuthenticated === true`.
- O `try/catch` separa o erro de **rede/credenciais** (mostra a mensagem) da
  validação do zod (que nem deixa o `onSubmit` rodar com campos vazios).

## Passo 3 — A área protegida (o guard)

A rota do dashboard já tem o guard que você escreveu no capítulo de roteamento.
Ele é o portão que lê a store **no momento da renderização**:

```tsx
// src/routes.tsx (a rota protegida)
{
  path: "dashboard",
  lazy: () => import("@/pages/Dashboard"),
  guard: () => useAuth.getState().isAuthenticated,
  redirectTo: "/login",
},
```

Antes do login, `isAuthenticated` é `false` → o `<AppRouter>` redireciona pra
`/login`. Depois do `setSession`, a próxima tentativa de abrir `/dashboard`
encontra `true` → o Dashboard renderiza.

!!! warning "Por que o guard usa `getState()` e não o hook"

    O `guard` roda **fora** do ciclo de hooks (durante a montagem da rota), então
    não pode chamar `useAuth.use.isAuthenticated()`. Ele lê o snapshot atual com
    `getState()`. Dentro de **componentes** — como o `RootLayout` — você usa o
    hook `.use` pra re-renderizar quando o auth muda. Mesma store, duas formas de
    ler conforme o contexto. 💡

## Passo 4 — Logout manual

O `RootLayout` (do capítulo de estado) já mostra um botão "Sair" quando há sessão.
Ele chama a ação `logout`:

```tsx
// trecho do src/layouts/RootLayout.tsx
import { useAuth } from "@/stores/auth";

const logout = useAuth.use.logout();
// ...
<button onClick={logout}>Sair</button>;
```

`logout()` limpa `user`, `token` e `isAuthenticated`. Como o `RootLayout` lê
`isAuthenticated` pelo hook `.use`, a `<nav>` re-renderiza na hora: o botão "Sair"
some e o link "Entrar" volta. Se o usuário estiver numa rota protegida, o guard o
manda de volta pro login.

## Passo 5 — Logout automático no 401

Aqui o fluxo se fecha. Quando um token expira, o backend responde **401** na
próxima chamada. O `onUnauthorized` do cliente — que você configurou no Passo 1 —
dispara o `logout()`:

```ts
// já no src/lib/api.ts
onUnauthorized: () => useAuth.getState().logout(),
```

Você **não** precisa checar 401 manualmente em cada `useQuery`/`useMutation`:
qualquer chamada via `api` que volte 401 desloga o usuário centralmente, e o guard
faz o resto. Um único ponto de verdade pra "a sessão acabou".

!!! tip "Renovando o token em vez de deslogar"

    Se o seu backend tem refresh token, dá pra **renovar** a sessão antes de
    desistir: passe um `refresh` ao `createApiClient` e ele tenta `refresh()` e
    repete a requisição uma vez no 401, deslogando só se o refresh também falhar.
    Veja a página de [Auth](../auth.md) (`createRefreshQueue`) pra esse padrão
    avançado.

## Parabéns! 🎉

Você construiu um app completo com o `tempest-react-sdk`, ponta a ponta:

- **Roteamento** com layout, páginas, rota lazy e guard.
- **Estado** com `createStore`, `createSelectors` e a store de auth persistida.
- **Dados** com `createApiClient`, `createQueryKeys`, `useQuery` e `useMutation`.
- **Formulários** validados com `useZodForm` + `FormField` + campos BR mascarados.
- **Autenticação** ligando store + guard + cliente HTTP num fluxo coeso.

## Recap

- O fluxo de auth é **uma store + um guard + um cliente**, todos lendo a **mesma**
  `useAuth`. ✅
- **Login**: `api.post("/auth/login")` → `setSession({ user, token })` →
  `navigate("/dashboard")`.
- **Área protegida**: o `guard` lê `useAuth.getState().isAuthenticated` na
  renderização e redireciona com `redirectTo` quando falso.
- **Logout manual**: `useAuth.use.logout()` num botão; o `RootLayout` re-renderiza
  porque lê pelo hook `.use`.
- **Logout automático**: `onUnauthorized: () => useAuth.getState().logout()` no
  cliente desloga em qualquer 401 — um único ponto de verdade.
- Dentro de componentes, leia com `.use`; fora do React (guard, cliente), leia com
  `getState()`.

---

# tutorial/data-fetching.md

# Tutorial — Buscando dados

Nossa lista de tarefas precisa vir de algum lugar: um backend. Nesta página você
vai montar os _providers_ no topo do app, criar um cliente HTTP tipado com
`createApiClient`, organizar as chaves de cache com `createQueryKeys`, e buscar e
alterar dados com `useQuery` e `useMutation`, tratando os estados de carregando e
erro.

## Passo 1 — Os providers no topo

Para o React Query funcionar, o app precisa de um provider de cache no topo da
árvore. O `<AppProviders>` monta esse provider (e o tema, e o error boundary) de
uma vez. Ele já vem no `App.tsx` gerado:

```tsx
// src/App.tsx
import { AppProviders, AppRouter } from "tempest-react-sdk";
import { routes } from "@/routes";

export function App() {
  return (
    <AppProviders errorBoundary={{ fallback: <p>Algo deu errado.</p> }}>
      <AppRouter routes={routes} fallback={<p>Carregando…</p>} />
    </AppProviders>
  );
}
```

O `<AppProviders>` aninha de fora pra dentro: `ErrorBoundary → QueryProvider →
ThemeProvider → I18nProvider → children`. **Query e Theme já vêm ligados** com os
defaults do SDK — você não configura nada pra ter cache de dados.

!!! info "Defaults do cache"

    Quando ligado por padrão, o `QueryProvider` usa: `staleTime` de 5 minutos,
    `gcTime` de 30 minutos, `retry: 1` e `refetchOnWindowFocus: false`. Para
    ajustar, passe `query={{ defaultOptions: { queries: { retry: 3 } } }}`.

## Passo 2 — O cliente HTTP com `createApiClient`

`createApiClient` cria um cliente `fetch` tipado que cuida de JSON, query params,
bearer token e tratamento de 401. Vamos centralizá-lo em `src/lib/api.ts`:

```ts
// src/lib/api.ts
import { createApiClient, createQueryKeys } from "tempest-react-sdk";
import { useAuth } from "@/stores/auth";

export const api = createApiClient({
  baseURL: import.meta.env.VITE_API_URL,
  getToken: () => useAuth.getState().token,
  onUnauthorized: () => useAuth.getState().logout(),
});
```

Peça por peça:

- `baseURL` vem do `.env` (`VITE_API_URL`) — a base de toda requisição.
- `getToken` é chamado **a cada requisição**; lendo o token via `getState()`,
  cada chamada usa o token atual e manda o header `Authorization: Bearer ...`.
- `onUnauthorized` dispara em respostas **401** — aqui deslogamos o usuário.

O cliente expõe `get`, `post`, `put`, `patch`, `delete` (todos genéricos no tipo
de retorno) e `upload`. Cada um devolve o JSON já parseado e tipado.

!!! tip "Lembra do `getToken` com `getState()`?"

    O cliente HTTP roda **fora** do React, então lê a store de auth com
    `getState()` — exatamente o padrão que você viu na página de
    [Estado](state.md). Sem hook, sem assinatura: só um snapshot do token na hora
    da chamada. 💡

## Passo 3 — Chaves de cache com `createQueryKeys`

O React Query identifica cada pedaço de cache por uma **query key**. Em vez de
espalhar arrays mágicos pelo código, centralize-as com `createQueryKeys`:

```ts
// src/lib/api.ts (continuação)
export const taskKeys = createQueryKeys("tasks", {
  all: () => ["all"] as const,
  byId: (id: string) => [id] as const,
});

// taskKeys.all()  === ["tasks", "all"]
// taskKeys.byId("42") === ["tasks", "42"]
```

Cada chave é prefixada com o domínio (`"tasks"`), então não há colisão entre
domínios diferentes.

## Passo 4 — Lendo dados com `useQuery`

Agora a lista de tarefas. `useQuery` vem do `@tanstack/react-query` (dependência
**direta** do SDK, instalada junto — você não precisa instalar nada à parte).

!!! note "De onde vem o `useQuery`"

    Os hooks `useQuery` e `useMutation` são importados de `"@tanstack/react-query"`,
    não de `"tempest-react-sdk"`. O SDK fornece o **provider** (`QueryProvider`,
    via `AppProviders`), as **chaves** (`createQueryKeys`) e os presets de tempo;
    os hooks você usa direto do React Query. Como ele é dependência direta do SDK,
    já está instalado.

```tsx
// src/pages/Home.tsx
import { useQuery } from "@tanstack/react-query";
import { api, taskKeys } from "@/lib/api";

interface Task {
  id: string;
  title: string;
  done: boolean;
}

export function Home() {
  const { data, isLoading, isError, error } = useQuery({
    queryKey: taskKeys.all(),
    queryFn: () => api.get<Task[]>("/tasks"),
  });

  if (isLoading) return <p>Carregando tarefas…</p>;
  if (isError) return <p>Erro: {(error as Error).message}</p>;

  return (
    <ul>
      {data?.map((task) => (
        <li key={task.id}>
          {task.done ? "✅" : "⬜"} {task.title}
        </li>
      ))}
    </ul>
  );
}
```

Peça por peça:

- `queryKey: taskKeys.all()` identifica este cache — outros componentes que usem a
  mesma chave compartilham o mesmo dado.
- `queryFn` faz a requisição. `api.get<Task[]>("/tasks")` devolve um `Task[]` já
  tipado.
- `isLoading` / `isError` / `error` são os **estados** que o React Query mantém
  pra você — trate-os antes de renderizar os dados.

## Passo 5 — Alterando dados com `useMutation`

Buscar é só metade. Para **criar** uma tarefa, use `useMutation` (também do
`@tanstack/react-query`). Depois do sucesso, invalidamos a query da lista para que
ela seja buscada de novo com a tarefa nova.

```tsx
// src/components/AddTask.tsx
import { useState } from "react";
import { useMutation, useQueryClient } from "@tanstack/react-query";
import { api, taskKeys } from "@/lib/api";

interface Task {
  id: string;
  title: string;
  done: boolean;
}

export function AddTask() {
  const [title, setTitle] = useState("");
  const queryClient = useQueryClient();

  const mutation = useMutation({
    mutationFn: (newTitle: string) =>
      api.post<Task>("/tasks", { body: { title: newTitle, done: false } }),
    onSuccess: () => {
      queryClient.invalidateQueries({ queryKey: taskKeys.all() });
      setTitle("");
    },
  });

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        mutation.mutate(title);
      }}
    >
      <input value={title} onChange={(e) => setTitle(e.target.value)} placeholder="Nova tarefa" />
      <button type="submit" disabled={mutation.isPending}>
        {mutation.isPending ? "Salvando…" : "Adicionar"}
      </button>
      {mutation.isError && <p>Erro ao salvar.</p>}
    </form>
  );
}
```

Peça por peça:

- `mutationFn` recebe o argumento de `mutation.mutate(...)` e faz o `POST`. Note o
  `{ body: {...} }` — o `createApiClient` serializa o `body` em JSON pra você.
- `onSuccess` invalida `taskKeys.all()`: o React Query re-busca a lista
  automaticamente, e a `<Home>` mostra a tarefa nova sem você recarregar a página.
- `mutation.isPending` desabilita o botão durante o envio; `mutation.isError`
  mostra o erro.

!!! tip "Por que invalidar em vez de inserir na mão"

    Invalidar a query (`invalidateQueries`) deixa o servidor ser a fonte de
    verdade: você re-busca a lista e ganha o `id` real, timestamps, qualquer campo
    que o backend preencheu. É mais robusto do que tentar inserir o objeto otimista
    na lista local. ✅

## Recap

- O `<AppProviders>` monta o `QueryProvider` (cache) **ligado por padrão** — sem
  config você já tem React Query funcionando. ✅
- **`createApiClient({ baseURL, getToken, onUnauthorized })`** cria um cliente
  `fetch` tipado: `getToken` injeta o bearer a cada chamada, `onUnauthorized`
  dispara em 401. Lê a auth store com `getState()`.
- **`createQueryKeys("dominio", {...})`** centraliza as chaves de cache, prefixadas
  pelo domínio.
- **`useQuery`** (de `@tanstack/react-query`, dependência direta do SDK) busca
  dados e te dá `isLoading` / `isError` / `data`.
- **`useMutation`** + `queryClient.invalidateQueries(...)` altera dados e re-busca
  a lista — o servidor continua sendo a fonte de verdade.

➡️ **Próxima página:** [Formulários — validação com zod e máscaras BR](forms.md)

---

# tutorial/forms.md

# Tutorial — Formulários

Antes do usuário entrar no app, ele precisa se cadastrar — e o cadastro precisa
ser **validado**: e-mail com formato certo, senha com tamanho mínimo, telefone
preenchido. Nesta página você monta um formulário de cadastro com `useZodForm`
(validação por schema), `FormField` (cola a validação aos componentes) e um campo
mascarado de telefone BR (`PhoneInput`), e por fim envia os dados pro cliente HTTP.

A regra de ouro: o **schema zod é a fonte de verdade**. O tipo dos valores é
inferido dele — você não declara o tipo duas vezes.

## Passo 1 — O schema com zod

`zod` é dependência **direta** do SDK, já instalada. Descreva o formato do
formulário com `z.object`:

```ts
// src/schemas/signup.ts
import { z } from "zod";

export const signupSchema = z.object({
  name: z.string().min(2, "Informe seu nome"),
  email: z.string().email("E-mail inválido"),
  phone: z.string().min(14, "Telefone incompleto"),
  password: z.string().min(8, "Mínimo de 8 caracteres"),
});

export type SignupValues = z.infer<typeof signupSchema>;
```

Cada `.min(...)` / `.email(...)` carrega a **mensagem de erro** que aparece no
campo. O `z.infer` deriva o tipo `SignupValues` — a única definição de tipo que
você precisa.

## Passo 2 — `useZodForm`, o tudo-em-um

`useZodForm` embrulha o `useForm` do react-hook-form já ligado ao seu schema, sem
precisar de pacote de resolver extra. Você passa o schema e os valores iniciais:

```tsx
// src/pages/Signup.tsx (esqueleto)
import { useZodForm } from "tempest-react-sdk";
import { signupSchema, type SignupValues } from "@/schemas/signup";

export function Signup() {
  const form = useZodForm(signupSchema, {
    defaultValues: { name: "", email: "", phone: "", password: "" },
  });

  // form.register, form.handleSubmit, form.formState, form.control ...
}
```

O `form` devolvido é o objeto padrão do react-hook-form — `register`,
`handleSubmit`, `control`, `formState.errors`, `formState.isSubmitting`.

## Passo 3 — `FormField` + `FormProvider`

Ligar cada campo à validação na mão dá trabalho. O `FormField` é a cola entre o
react-hook-form e os componentes controlados do SDK: ele injeta `value`,
`onChange`, `label`, `error` e o estado de erro no componente filho
automaticamente. Para o `FormField` achar o `control`, envolva tudo num
`FormProvider` (também re-exportado pelo SDK).

```tsx
// src/pages/Signup.tsx
import {
  useZodForm,
  FormProvider,
  Form,
  FormField,
  FormActions,
  Input,
  Button,
  PhoneInput,
} from "tempest-react-sdk";
import { signupSchema, type SignupValues } from "@/schemas/signup";

export function Signup() {
  const form = useZodForm(signupSchema, {
    defaultValues: { name: "", email: "", phone: "", password: "" },
  });

  function onSubmit(values: SignupValues) {
    console.log("válido!", values);
  }

  return (
    <FormProvider {...form}>
      <Form layout="stack" gap={4} onSubmit={form.handleSubmit(onSubmit)}>
        <FormField name="name" label="Nome" required>
          <Input />
        </FormField>
        <FormField name="email" label="E-mail" required>
          <Input type="email" />
        </FormField>
        <FormField name="phone" label="Telefone" required>
          <PhoneInput />
        </FormField>
        <FormField name="password" label="Senha" required>
          <Input type="password" />
        </FormField>
        <FormActions align="end">
          <Button type="submit" loading={form.formState.isSubmitting}>
            Criar conta
          </Button>
        </FormActions>
      </Form>
    </FormProvider>
  );
}
```

Peça por peça:

- `<FormProvider {...form}>` publica o `form` no contexto — é o que o `FormField`
  lê pra achar o `control`.
- `<Form layout="stack" gap={4}>` é só **layout** (flex coluna, gap de 16px) — ele
  não se acopla a nenhuma form library.
- Cada `<FormField name="..." label="...">` casa o `name` com uma chave do schema e
  injeta `value`/`onChange`/`error` no filho. Os erros do zod aparecem
  automaticamente abaixo do campo.
- `form.handleSubmit(onSubmit)` só chama o `onSubmit` quando **tudo** valida.

!!! warning "O `name` precisa bater com uma chave do schema"

    `<FormField name="email">` exige uma chave `email` no `signupSchema`. Como
    `useZodForm` é tipado pelo schema, escrever `name="emial"` vira erro de
    compilação — você pega o engano antes de rodar. ✅

## Passo 4 — O campo mascarado de telefone

Você não escreveu nenhuma lógica de máscara — `PhoneInput` é um dos campos BR
prontos do SDK. Ele formata o que o usuário digita (`11999998888` →
`(11) 99999-8888`) e repassa o valor mascarado pro form. Outros disponíveis:

| Componente   | Formata                    |
| ------------ | -------------------------- |
| `PhoneInput` | telefone `(11) 99999-8888` |
| `CPFInput`   | CPF `123.456.789-09`       |
| `CNPJInput`  | CNPJ `12.345.678/0001-90`  |
| `CEPInput`   | CEP `01310-100`            |
| `MoneyInput` | moeda `R$ 1.234,56`        |

Todos funcionam dentro de um `FormField` exatamente como o `PhoneInput` acima —
basta trocar o filho.

!!! info "A máscara afeta o valor validado"

    O `phone` chega ao schema **já mascarado** (`(11) 99999-8888`, 15 caracteres).
    Por isso o `.min(14)` do schema considera os caracteres da máscara. Se o seu
    backend quiser só dígitos, desmascare no `onSubmit` antes de enviar (o SDK
    exporta `unmask` pra isso).

## Passo 5 — Enviando pro backend

Agora ligue o `onSubmit` ao cliente HTTP que você criou na página de
[busca de dados](data-fetching.md). Em vez de `console.log`, faça o `POST` e, no
sucesso, navegue pra tela de login:

```tsx
// src/pages/Signup.tsx (apenas o onSubmit)
import { useNavigate } from "tempest-react-sdk";
import { api } from "@/lib/api";
import type { SignupValues } from "@/schemas/signup";

// dentro do componente:
const navigate = useNavigate();

async function onSubmit(values: SignupValues) {
  await api.post("/auth/signup", { body: values });
  navigate("/login");
}
```

Repare que `form.formState.isSubmitting` (passado em `loading={...}` no botão)
fica `true` enquanto a `Promise` do `onSubmit` não resolve — o botão mostra o
estado de carregamento sozinho, porque o react-hook-form acompanha a `async`
function.

!!! tip "Erros de validação x erros de rede"

    O zod cuida da validação **antes** do envio: campos inválidos nem chegam ao
    `onSubmit`. Já um erro **de rede** (o `POST` falhar) é um `throw` do
    `api.post` — trate com `try/catch` no `onSubmit` se quiser mostrar uma
    mensagem de "falha ao cadastrar".

## Recap

- O **schema zod é a fonte de verdade**: mensagens de erro moram nele e o tipo
  sai de `z.infer`. ✅
- **`useZodForm(schema, { defaultValues })`** embrulha o react-hook-form já ligado
  ao zod — sem pacote de resolver extra.
- **`<FormProvider {...form}>`** publica o form no contexto; cada
  **`<FormField name="..." label="...">`** cola validação e erros ao componente
  filho. O `name` é checado contra o schema em tempo de compilação.
- **`<Form layout="stack">`** cuida só do layout — não se acopla a form library.
- Campos BR mascarados (`PhoneInput`, `CPFInput`, `CNPJInput`, `CEPInput`,
  `MoneyInput`) entram como filhos do `FormField` sem código de máscara seu.
- `form.handleSubmit(onSubmit)` só chama o `onSubmit` quando tudo valida; lá
  dentro você chama `api.post(...)` e navega no sucesso.

➡️ **Próxima página:** [Fluxo de autenticação — juntando store, guard e cliente HTTP](auth-flow.md)

---

# tutorial/index.md

# Tutorial — Comece aqui

Bem-vindo! 🚀 Este é o **Tutorial — Guia do Usuário** do `tempest-react-sdk`. Ele é
linear: cada página ensina **um conceito**, em cima do anterior, com exemplos
completos que você pode copiar e colar. Comece nesta página e siga os links de
"próxima página" — você nunca vai ficar travado.

Ao longo do tutorial vamos construir **o mesmo app pequeno**, página a página: uma
lista de tarefas com login. Nada de teoria solta — cada conceito entra porque o
app precisa dele.

## O que é o `tempest-react-sdk`?

É o SDK de frontend da Tempest: um único pacote npm que reúne tudo que um app
React precisa repetir — roteamento, estado, cache de dados, formulários,
autenticação, tema — atrás de **uma só superfície de import**. Você importa tudo
de `"tempest-react-sdk"` e nunca precisa colar a integração na mão.

!!! info "Só `react` e `react-dom` são peer deps"

    Quando você instala o SDK, **todo o resto vem junto** automaticamente:
    `react-router`, `zustand`, `@tanstack/react-query`, `zod`,
    `react-hook-form`, `dexie`, `lucide-react`. São **dependências diretas** do
    SDK. As únicas dependências que **você** precisa garantir são `react` e
    `react-dom` — porque o React exige uma única instância no app inteiro.

## Passo 1 — Crie o app com `create-tempest-app`

A CLI oficial de scaffolding **vem dentro do próprio SDK** (é o `bin` do pacote —
não existe um pacote separado). O caminho recomendado é **criar a pasta você
mesmo e scaffoldar dentro dela** com `.`:

```bash
mkdir my-app
cd my-app
npx -p tempest-react-sdk create-tempest-app .
npm install
cp .env.example .env
npm run dev
```

Abra **<http://127.0.0.1:5173>** — o app já está no ar com providers, rotas e
store de autenticação funcionando.

### Anatomia do comando

Esse comando parece longo, mas cada pedaço tem um papel:

| Pedaço                  | O que faz                                                                                                                    |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `npx`                   | Baixa e executa um binário **sem instalar nada global**. Ele descarta o download depois.                                      |
| `-p tempest-react-sdk`  | Diz **de qual pacote** vem o binário. Necessário porque a CLI mora dentro do SDK, e o nome dela é diferente do nome do pacote. |
| `create-tempest-app`    | O nome do `bin` dentro daquele pacote — é o que de fato roda.                                                                 |
| `.`                     | O **destino**: o diretório atual. É o modo recomendado.                                                                       |

!!! tip "Por que `.` e não `create-tempest-app my-app`?"

    Passar um nome também funciona (`create-tempest-app my-app` cria a pasta
    `my-app` e escreve dentro dela), mas o fluxo com `.` é melhor no dia a dia:

    - **Você controla a pasta e o nome.** O `name` do `package.json` sai do nome
      do diretório em que você está — nada de descobrir depois que ficou
      `my-app/my-app` porque você já estava dentro da pasta.
    - **Convive com o que já existe.** Se você já rodou `git init`, ou já tem um
      `README.md`/`LICENSE`/`.git` na pasta, o modo `.` **preserva** cada arquivo
      que já existe e lista o que pulou. O modo com nome **aborta** se a pasta
      não estiver vazia.
    - **É o mesmo comando pra pasta nova e pra projeto existente** — um fluxo só
      pra decorar.

!!! info "Rodar sem argumento = `.`"

    `npx -p tempest-react-sdk create-tempest-app` (sem nada depois) faz
    exatamente o mesmo que passar `.`: scaffold no diretório atual. A CLI **não**
    pergunta um nome de projeto.

!!! warning "`npm create tempest-app` **não** funciona"

    Não existe um pacote `create-tempest-app` publicado no npm — a CLI é o `bin`
    do `tempest-react-sdk`. Então `npm create tempest-app` falha com 404. Use
    sempre a forma com `-p`:

    ```bash
    npx -p tempest-react-sdk create-tempest-app .
    ```

    Já num projeto que **tem o SDK instalado**, o `-p` é dispensável — o `npx`
    acha o `bin` no `node_modules` local:

    ```bash
    npm install tempest-react-sdk
    npx create-tempest-app .
    ```

### Os dois modos, lado a lado

| Você digita              | Destino            | Se a pasta tem arquivos                        | Nome do projeto        |
| ------------------------ | ------------------ | ---------------------------------------------- | ---------------------- |
| `create-tempest-app .`   | diretório atual    | **preserva** os seus e reporta o que foi pulado | nome da pasta atual    |
| `create-tempest-app` (só) | diretório atual    | idem                                            | nome da pasta atual    |
| `create-tempest-app my-app` | `./my-app`      | **aborta** se existir e não estiver vazia       | `my-app`               |

!!! tip "Quer um PWA?"

    Some `--pwa` em qualquer um dos modos
    (`npx -p tempest-react-sdk create-tempest-app . --pwa`) e o scaffold sai com
    service worker, manifest e wiring de web push. Detalhes em
    [Scaffold](../scaffold.md) e [PWA](../pwa.md).

### Fixando a versão do SDK

O app gerado nasce com a dependência `tempest-react-sdk` **carimbada na mesma
versão da CLI que rodou o scaffold**. Pra escolher essa versão, ponha o `@` no
`-p`:

```bash
npx -p tempest-react-sdk@0.23.0 create-tempest-app .
```

## Passo 2 — A linha mais importante: o CSS

O SDK envia seu próprio CSS (tokens de cor, tipografia, reset). O app gerado já
importa pra você em `src/main.tsx`:

```tsx
// src/main.tsx
import { createRoot } from "react-dom/client";
import "tempest-react-sdk/styles.css";
import { App } from "@/App";

createRoot(document.getElementById("root")!).render(<App />);
```

!!! warning "É `tempest-react-sdk/styles.css`, sem `/dist/`"

    O import correto é `import "tempest-react-sdk/styles.css"`. Não use
    `tempest-react-sdk/dist/styles.css` — esse caminho não é exposto pelo pacote.
    Sem essa linha, os componentes renderizam **sem estilo**.

## Passo 3 — Conheça os arquivos gerados

O projeto é enxuto de propósito: cada arquivo demonstra **um recurso** que você
vai reaproveitar no tutorial. Esta é a estrutura:

```text
my-app/
├── vite.config.ts        # createViteConfig() — config Vite pronta pro SDK
├── .env.example          # VITE_API_URL — base do cliente HTTP
└── src/
    ├── main.tsx          # createRoot + "tempest-react-sdk/styles.css" + <App/>
    ├── App.tsx           # <AppProviders> envolvendo <AppRouter/>
    ├── routes.tsx        # defineRoutes([...]) — index, login e dashboard lazy + protegido
    ├── layouts/RootLayout.tsx   # nav com <Link> + <Outlet/>
    ├── pages/Home.tsx
    ├── pages/Login.tsx
    ├── pages/Dashboard.tsx       # export default (lazy), rota protegida
    ├── stores/auth.ts            # createSelectors(createAuthStore<User>(...))
    └── lib/api.ts               # createApiClient(...) + createQueryKeys
```

Cada arquivo é uma porta de entrada pra um conceito deste tutorial:

| Arquivo              | Conceito                | Página do tutorial                 |
| -------------------- | ----------------------- | ---------------------------------- |
| `src/App.tsx`        | Providers + roteamento  | [Roteamento](routing.md)           |
| `src/routes.tsx`     | Árvore de rotas + guard | [Roteamento](routing.md)           |
| `src/stores/auth.ts` | Estado (Zustand + auth) | [Estado](state.md)                 |
| `src/lib/api.ts`     | Cliente HTTP + cache    | [Buscando dados](data-fetching.md) |

## Passo 4 — Confirme que está rodando

Com `npm run dev` ativo, abra <http://127.0.0.1:5173>. Você deve ver a página
inicial com uma `<nav>` no topo (links **Home** e **Dashboard**) e o conteúdo da
rota `/` abaixo. Clicar em **Dashboard** sem estar logado te leva pro login —
esse é o guard de rota em ação, que você vai entender em [Roteamento](routing.md).

!!! check "Pronto pra começar"

    Se o app abriu no navegador e os links de navegação trocam o conteúdo sem
    recarregar a página, sua base está perfeita. Vamos construir em cima dela. ✅

## Se algo deu errado

| Sintoma                                                            | Causa                                                                | O que fazer                                                                                    |
| ------------------------------------------------------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `404 Not Found - create-tempest-app`                               | Você usou `npm create tempest-app` — esse pacote não existe no npm.  | Use `npx -p tempest-react-sdk create-tempest-app .`                                             |
| `✗ Directory "my-app" exists and is not empty.`                    | Modo pasta-nova com pasta já populada.                               | `cd my-app && npx -p tempest-react-sdk create-tempest-app .` — o modo `.` preserva seus arquivos. |
| `Skipped N existing file(s)`                                       | Não é erro: a CLI **não sobrescreveu** arquivos seus.                | Confira a lista; se quiser a versão do template, remova o arquivo e rode de novo.               |
| Componentes aparecem sem estilo                                    | Falta o import do CSS.                                               | `import "tempest-react-sdk/styles.css"` em `src/main.tsx` (**sem** `/dist/`).                    |
| Erro de sintaxe/engine ao rodar o `npx`                            | Node antigo.                                                         | O SDK exige **Node >= 22.12**. Confira com `node -v`.                                           |
| `VITE_API_URL` undefined em runtime                                | Faltou o `.env`.                                                     | `cp .env.example .env` e ajuste a URL do backend.                                               |

## Recap

- O `tempest-react-sdk` reúne roteamento, estado, dados, formulários e auth atrás
  de **uma só superfície de import** (`"tempest-react-sdk"`). ✅
- **Só `react` e `react-dom` são peer deps**; todo o resto (`react-router`,
  `zustand`, `@tanstack/react-query`, `zod`, `react-hook-form`, ...) é dependência
  **direta** instalada junto.
- Crie o app com `mkdir my-app && cd my-app`, depois
  `npx -p tempest-react-sdk create-tempest-app .` — o `.` scaffolda no diretório
  atual, preserva o que já existe e tira o nome do projeto da pasta. Em seguida
  `npm install`, `cp .env.example .env` e `npm run dev`.
- `npm create tempest-app` **não** existe; a CLI é o `bin` do SDK, então a forma
  correta tem `-p tempest-react-sdk` (ou nenhum `-p`, se o SDK já está instalado
  no projeto).
- A linha de CSS é `import "tempest-react-sdk/styles.css"` (**sem** `/dist/`) — sem
  ela os componentes ficam sem estilo.
- Cada arquivo gerado é a porta de entrada pra um conceito do tutorial.

➡️ **Próxima página:** [Roteamento — adicionando páginas e rotas](routing.md)

---

# tutorial/routing.md

# Tutorial — Roteamento

Nosso app vai ter mais de uma tela: a lista de tarefas, uma página de login e um
painel. Para o usuário trocar de tela **sem recarregar a página**, precisamos de
rotas. Nesta página você vai adicionar uma página nova, ligá-la a uma URL,
navegar com `<Link>` e, por fim, criar uma rota **lazy** e **protegida**.

Tudo vem de `"tempest-react-sdk"` — você nunca importa de `react-router`
diretamente. O SDK embrulha o React Router v8 declarativo e expõe `defineRoutes`,
`<AppRouter>`, `<Link>`, `<Outlet>` e `useNavigate` num só lugar.

## A árvore de rotas que já existe

O app gerado já tem uma árvore em `src/routes.tsx`. Vamos partir de uma versão
enxuta dela: um layout na raiz, com a Home como rota índice e o login como filho.

```tsx
// src/routes.tsx
import { defineRoutes } from "tempest-react-sdk";
import { RootLayout } from "@/layouts/RootLayout";
import { Home } from "@/pages/Home";
import { Login } from "@/pages/Login";

export const routes = defineRoutes([
  {
    path: "/",
    element: <RootLayout />,
    children: [
      { index: true, element: <Home /> },
      { path: "login", element: <Login /> },
    ],
  },
]);
```

Peça por peça:

- `defineRoutes([...])` é um helper de **identidade tipada**: devolve o mesmo
  array, mas com autocomplete e checagem de tipos. Você não anota nada na mão.
- A rota `"/"` renderiza o `<RootLayout>` (o "esqueleto" com a navegação).
- `{ index: true }` é a rota **padrão** do layout — o que aparece quando a URL
  casa exatamente com `/`.
- `{ path: "login" }` casa com `/login`.

!!! warning "`index` e `path` são mutuamente exclusivos"

    Uma rota é índice (`index: true`) **ou** tem `path`, nunca os dois juntos.
    Marcar ambos é um erro de configuração.

## O layout e o `<Outlet>`

A rota pai renderiza o layout; as rotas filhas aparecem dentro dele, no ponto
marcado por `<Outlet>`. A navegação fica fixa, e só o conteúdo abaixo troca.

```tsx
// src/layouts/RootLayout.tsx
import { Link, Outlet } from "tempest-react-sdk";

export function RootLayout() {
  return (
    <div>
      <nav>
        <Link to="/">Tarefas</Link> | <Link to="/sobre">Sobre</Link>
      </nav>
      <main>
        <Outlet />
      </main>
    </div>
  );
}
```

Use `<Link to="...">` (re-exportado pelo SDK) em vez de `<a href="...">`: o
`<Link>` navega no cliente, sem recarregar a página. O `<Outlet>` é onde o React
Router injeta a rota filha que casou com a URL atual.

## Adicionando uma página nova

Vamos criar uma página "Sobre". Primeiro o componente:

```tsx
// src/pages/Sobre.tsx
export function Sobre() {
  return (
    <section>
      <h1>Sobre</h1>
      <p>Uma lista de tarefas feita com o tempest-react-sdk.</p>
    </section>
  );
}
```

Agora registre a rota como filha do layout, ao lado da Home e do login:

```tsx
// src/routes.tsx
import { defineRoutes } from "tempest-react-sdk";
import { RootLayout } from "@/layouts/RootLayout";
import { Home } from "@/pages/Home";
import { Login } from "@/pages/Login";
import { Sobre } from "@/pages/Sobre";

export const routes = defineRoutes([
  {
    path: "/",
    element: <RootLayout />,
    children: [
      { index: true, element: <Home /> },
      { path: "login", element: <Login /> },
      { path: "sobre", element: <Sobre /> },
    ],
  },
]);
```

Pronto: o link **Sobre** do `RootLayout` agora abre `/sobre` e o `<Outlet>`
mostra a página. Não precisou mexer em mais nada. 🚀

## Como tudo é montado: `<AppRouter>`

Você nunca instancia o router na mão. O `<AppRouter>` recebe a árvore e monta o
router, o `<Suspense>` e as `<Routes>` sozinho. No app gerado ele vive dentro do
`App.tsx`:

```tsx
// src/App.tsx
import { AppProviders, AppRouter } from "tempest-react-sdk";
import { routes } from "@/routes";

export function App() {
  return (
    <AppProviders errorBoundary={{ fallback: <p>Algo deu errado.</p> }}>
      <AppRouter routes={routes} fallback={<p>Carregando…</p>} />
    </AppProviders>
  );
}
```

O `fallback` é o que aparece enquanto uma rota **lazy** (próxima seção) baixa seu
código. Você vai entender o `<AppProviders>` em detalhe na página de
[busca de dados](data-fetching.md) — por ora, saiba só que ele fica **por fora**
do roteamento.

## Rota lazy: carregando código sob demanda

Páginas pesadas não precisam entrar no bundle inicial. O campo `lazy` carrega o
componente só quando o usuário visita a rota. Diferente das outras páginas, um
componente lazy precisa de um **`export default`**:

```tsx
// src/pages/Dashboard.tsx
export default function Dashboard() {
  return (
    <section>
      <h1>Dashboard</h1>
      <p>Suas tarefas concluídas e estatísticas.</p>
    </section>
  );
}
```

E na árvore, troque `element` por `lazy`:

```tsx
// src/routes.tsx (trecho)
{
  path: "dashboard",
  lazy: () => import("@/pages/Dashboard"),
},
```

Enquanto o chunk baixa, o `<AppRouter>` mostra o `fallback` que você passou no
`App.tsx`.

!!! note "Retry automático em chunk velho"

    Depois de um deploy, os nomes dos chunks mudam. Um usuário com a aba aberta há
    horas pode pedir um chunk que não existe mais e tomar erro de import. O `lazy`
    do SDK detecta esse caso e tenta recarregar **automaticamente** — você não
    escreve esse retry na mão.

## Protegendo uma rota com `guard`

O dashboard só deve ser visível para quem está logado. O campo `guard` resolve
isso direto na árvore: quando o valor é _falsy_, o `<AppRouter>` renderiza um
redirect no lugar do `element`.

```tsx
// src/routes.tsx
import { defineRoutes } from "tempest-react-sdk";
import { useAuth } from "@/stores/auth";
import { RootLayout } from "@/layouts/RootLayout";
import { Home } from "@/pages/Home";
import { Login } from "@/pages/Login";
import { Sobre } from "@/pages/Sobre";

export const routes = defineRoutes([
  {
    path: "/",
    element: <RootLayout />,
    children: [
      { index: true, element: <Home /> },
      { path: "login", element: <Login /> },
      { path: "sobre", element: <Sobre /> },
      {
        path: "dashboard",
        lazy: () => import("@/pages/Dashboard"),
        guard: () => useAuth.getState().isAuthenticated,
        redirectTo: "/login",
      },
    ],
  },
]);
```

Quem não está autenticado e tenta abrir `/dashboard` cai em `/login`. A store
`useAuth` ainda não existe — você vai criá-la na próxima página. Por enquanto,
foque em **como** o guard lê o estado.

!!! warning "O guard roda na renderização — leia a store via `getState()`"

    A função do `guard` é avaliada **durante a renderização** da rota, fora do
    ciclo de hooks. Por isso ela lê o valor _naquele instante_ com
    `useAuth.getState().isAuthenticated`. **Não** capture o valor fora da função
    (`const ok = useAuth.getState().isAuthenticated` no topo do arquivo) — você
    congelaria o estado de auth no carregamento inicial.

## Navegação programática

Às vezes você navega a partir de código — por exemplo, depois de um login
bem-sucedido. Use `useNavigate`:

```tsx
// src/pages/Login.tsx (esqueleto — completaremos depois)
import { useNavigate } from "tempest-react-sdk";

export function Login() {
  const navigate = useNavigate();

  function handleLogin() {
    // ...autenticar...
    navigate("/dashboard");
  }

  return <button onClick={handleLogin}>Entrar</button>;
}
```

## Múltiplos layouts (mobile/desktop · público/autenticado)

Apps reais raramente têm um layout só. Os dois eixos mais comuns:

- **Público vs autenticado** — a tela de login/cadastro usa um shell minimalista (um card centralizado), enquanto a área logada usa o shell do app (nav + conteúdo). São **layouts diferentes**, não a mesma casca com um `if`.
- **Mobile vs desktop** — no desktop um menu lateral fixo; no mobile uma barra inferior. O mesmo conteúdo, cascas diferentes.

O router declarativo resolve o primeiro eixo com **rotas de layout aninhadas**, e o segundo com o hook `useBreakpoint` **dentro** do layout.

### Um layout por seção (rotas de layout)

Uma rota **sem `path`**, só com `element` + `children`, é uma _layout route_: ela
envolve os filhos no seu `<Outlet>` sem adicionar segmento à URL. Agrupe as rotas
públicas sob um layout e as protegidas sob outro:

```tsx
// routes.tsx
import { defineRoutes } from "tempest-react-sdk";
import { AuthLayout } from "@/layouts/AuthLayout";
import { AppLayout } from "@/layouts/AppLayout";
import { Login } from "@/pages/Login";
import { Signup } from "@/pages/Signup";
import { TaskList } from "@/pages/TaskList";

export const routes = defineRoutes([
  {
    // Grupo PÚBLICO — shell de autenticação, sem guard.
    element: <AuthLayout />,
    children: [
      { path: "/login", element: <Login /> },
      { path: "/signup", element: <Signup /> },
    ],
  },
  {
    // Grupo PROTEGIDO — shell do app; o próprio layout faz o guard.
    element: <AppLayout />,
    children: [
      { index: true, element: <TaskList /> },
      { path: "settings", lazy: () => import("@/pages/Settings") },
    ],
  },
]);
```

O layout público é simples — só centraliza o `<Outlet>`:

```tsx
// layouts/AuthLayout.tsx
import { Outlet } from "tempest-react-sdk";

export function AuthLayout() {
  return (
    <div style={{ display: "grid", placeItems: "center", minHeight: "100vh" }}>
      <main style={{ width: "min(360px, 90vw)" }}>
        <Outlet />
      </main>
    </div>
  );
}
```

### Shell responsivo + guard no layout protegido

O `AppLayout` faz duas coisas: **protege** a seção inteira (redireciona se não
autenticado) e **troca a casca** conforme o breakpoint via `useBreakpoint`:

```tsx
// layouts/AppLayout.tsx
import { Link, Navigate, Outlet, useBreakpoint } from "tempest-react-sdk";
import { useAuth } from "@/stores/auth";

export function AppLayout() {
  const isAuthenticated = useAuth.use.isAuthenticated();
  const { isDesktop } = useBreakpoint();

  // Guarda a seção protegida inteira de uma vez.
  if (!isAuthenticated) return <Navigate to="/login" replace />;

  const nav = (
    <nav style={{ display: "flex", gap: 12 }}>
      <Link to="/">Tarefas</Link>
      <Link to="/settings">Ajustes</Link>
    </nav>
  );

  return (
    <div style={{ display: "flex", minHeight: "100vh" }}>
      {/* Desktop: menu lateral fixo */}
      {isDesktop && <aside style={{ width: 220, padding: 16 }}>{nav}</aside>}

      <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
        <main style={{ flex: 1, padding: 16 }}>
          <Outlet />
        </main>

        {/* Mobile: barra de navegação inferior */}
        {!isDesktop && (
          <footer style={{ borderTop: "1px solid var(--tempest-border)", padding: 8 }}>
            {nav}
          </footer>
        )}
      </div>
    </div>
  );
}
```

!!! tip "Guard no layout vs. guard por rota"
    Proteger **uma seção inteira** fica mais limpo com o redirect dentro do
    layout (um lugar só). Para proteger **uma rota isolada**, use o campo
    `guard` / o `<RouteGuard>` que vimos antes. Os dois convivem.

!!! note "`useBreakpoint` é SSR-safe"
    No servidor ele devolve `xs` / `width: 0` e atualiza depois do mount — então
    o shell mobile é o padrão até o JS hidratar. Para evitar “pulo” de layout,
    prefira CSS (`Show`/`Hide` ou media queries) quando o conteúdo for o mesmo;
    use `useBreakpoint` quando a **estrutura** muda (sidebar vs bottom-nav).

!!! warning "Layout route não adiciona segmento"
    A rota de layout **não tem `path`** — ela só envolve os filhos. Quem define a
    URL são os filhos (`/login`, `/settings`, índice em `/`). Não coloque `path`
    na rota de layout a menos que queira um prefixo (ex.: `path: "/app"`).

Resultado: `/login` e `/signup` renderizam dentro do `AuthLayout`; `/` e
`/settings` dentro do `AppLayout` (já protegido e responsivo). Cada seção tem o
seu shell, sem `if` espalhado pelas páginas.

## Recap

- Tudo de roteamento vem de `"tempest-react-sdk"` — você nunca importa de
  `react-router`. ✅
- `defineRoutes([...])` tipa a árvore; `<AppRouter routes={routes} />` monta
  router + `<Suspense>` + `<Routes>` sozinho.
- Use `index: true` para a rota padrão de um layout e `path` para as demais —
  nunca os dois juntos.
- Layouts renderizam filhos no `<Outlet>`; navegue com `<Link to="...">` (no JSX)
  ou `useNavigate()` (no código).
- `lazy: () => import("...")` carrega o código sob demanda (com retry automático
  em chunk velho) — o componente precisa de `export default`.
- Proteja rotas com `guard` (booleano ou função) + `redirectTo`; o guard roda na
  renderização, então leia a store com `getState()`.
- **Múltiplos layouts**: rotas de layout aninhadas (sem `path`) separam shells
  público/autenticado; `useBreakpoint` dentro do layout troca mobile/desktop.

➡️ **Próxima página:** [Estado — a store de autenticação](state.md)

---

# tutorial/state.md

# Tutorial — Estado

Na página anterior, o guard do dashboard leu `useAuth.getState().isAuthenticated`
— mas a store `useAuth` ainda não existe. Vamos criá-la agora. De passagem, você
aprende as duas peças de estado do SDK: `createStore` (uma store genérica) e
`createAuthStore` (a store de autenticação pronta), ambas em cima do
[Zustand](https://github.com/pmndrs/zustand), com `createSelectors` por cima.

Estado é tudo que vive **fora** de um único componente e precisa ser lido em
vários lugares: a sessão do usuário, um filtro de tarefas, um contador. É disso
que esta página trata.

## `createStore` — uma store genérica

Comece pelo mais simples. `createStore` recebe um _initializer_ no estilo Zustand
`(set) => estado` e devolve um hook ligado. Vamos guardar o filtro da lista de
tarefas:

```ts
// src/stores/filter.ts
import { createStore } from "tempest-react-sdk";

type Filter = "all" | "active" | "done";

interface FilterState {
  filter: Filter;
  setFilter: (filter: Filter) => void;
}

export const useFilter = createStore<FilterState>((set) => ({
  filter: "all",
  setFilter: (filter) => set({ filter }),
}));
```

Dentro de um componente, você usa como qualquer hook Zustand — passando um
**seletor** pra ler só o pedaço que importa:

```tsx
// src/components/FilterTabs.tsx
import { useFilter } from "@/stores/filter";

export function FilterTabs() {
  const filter = useFilter((s) => s.filter);
  const setFilter = useFilter((s) => s.setFilter);

  return (
    <div>
      <button onClick={() => setFilter("all")} disabled={filter === "all"}>
        Todas
      </button>
      <button onClick={() => setFilter("active")} disabled={filter === "active"}>
        Ativas
      </button>
      <button onClick={() => setFilter("done")} disabled={filter === "done"}>
        Concluídas
      </button>
    </div>
  );
}
```

`useFilter((s) => s.filter)` assina **só** `filter` — se outra fatia do estado
mudar, este componente não re-renderiza.

## `createSelectors` — um hook por campo

Escrever `(s) => s.filter` inline em todo lugar é repetitivo, e é fácil escorregar
e escrever `const state = useFilter()` — o que assina a store **inteira** e
re-renderiza sempre que **qualquer** campo muda. `createSelectors` resolve isso:
você envolve a store e ganha um namespace `.use` com um hook por campo.

```ts
// src/stores/filter.ts
import { createStore, createSelectors } from "tempest-react-sdk";

type Filter = "all" | "active" | "done";

interface FilterState {
  filter: Filter;
  setFilter: (filter: Filter) => void;
}

export const useFilter = createSelectors(
  createStore<FilterState>((set) => ({
    filter: "all",
    setFilter: (filter) => set({ filter }),
  })),
);
```

Agora cada campo é um hook próprio sob `.use`:

```tsx
// src/components/FilterTabs.tsx
import { useFilter } from "@/stores/filter";

export function FilterTabs() {
  const filter = useFilter.use.filter(); // assina só `filter`
  const setFilter = useFilter.use.setFilter();
  // ...mesmos botões de antes...
}
```

!!! tip "Por que isso importa pra performance"

    `useFilter.use.filter()` assina **só** `filter`. Num app com muitas fatias de
    estado, um componente que só mostra o filtro não re-renderiza quando a lista
    de tarefas muda. Você ganha a granularidade de seletor sem digitar funções de
    seletor à mão. ✅

## `createAuthStore` — a store de autenticação pronta

A sessão do usuário tem sempre a mesma forma: `user`, `token`, `isAuthenticated`,
e ações `setSession` / `logout`. O SDK já entrega isso pronto e **persistido** com
`createAuthStore`. Você só informa o **formato do seu usuário** (`TUser`) — o SDK
não é dono do seu modelo de usuário.

```ts
// src/stores/auth.ts
import { createAuthStore, createSelectors } from "tempest-react-sdk";

export interface User {
  id: string;
  name: string;
  email: string;
}

export const useAuth = createSelectors(
  createAuthStore<User>({ name: "app-auth", storage: "local" }),
);
```

- `createAuthStore<User>` cria a store Zustand de auth já com `persist`.
- `name: "app-auth"` é a chave usada no storage.
- `storage: "local"` usa `localStorage` (sobrevive entre sessões); `"session"`
  usaria `sessionStorage`.
- `createSelectors(...)` dá os hooks por campo via `useAuth.use.<campo>()`.

O estado e as ações disponíveis:

| Campo / ação      | Tipo                                         | O que faz                                          |
| ----------------- | -------------------------------------------- | -------------------------------------------------- |
| `user`            | `User \| null`                               | O usuário logado, ou `null`.                       |
| `token`           | `string \| null`                             | O token de acesso atual.                           |
| `isAuthenticated` | `boolean`                                    | Derivado de `!!token`.                             |
| `setSession`      | `(s: { user: User; token: string }) => void` | Loga: grava usuário + token de uma vez.            |
| `setUser`         | `(user: User \| null) => void`               | Atualiza só o usuário.                             |
| `setToken`        | `(token: string \| null) => void`            | Atualiza só o token (re-deriva `isAuthenticated`). |
| `logout`          | `() => void`                                 | Desloga: limpa usuário, token e flag.              |

!!! note "Reidratação automática"

    Como a store é persistida, ao recarregar a página o SDK lê o payload salvo no
    `localStorage` e restaura `user` + `token`, re-derivando `isAuthenticated` de
    `!!token`. O usuário continua logado entre reloads — sem código extra.

## Lendo a store num componente

Dentro de um componente React, use os hooks `.use` pra que a UI re-renderize
quando o auth mudar:

```tsx
// src/layouts/RootLayout.tsx
import { Link, Outlet } from "tempest-react-sdk";
import { useAuth } from "@/stores/auth";

export function RootLayout() {
  const isAuthenticated = useAuth.use.isAuthenticated();
  const user = useAuth.use.user();
  const logout = useAuth.use.logout();

  return (
    <div>
      <nav>
        <Link to="/">Tarefas</Link>
        {isAuthenticated ? (
          <>
            <Link to="/dashboard">Dashboard</Link>
            <span>Olá, {user?.name}</span>
            <button onClick={logout}>Sair</button>
          </>
        ) : (
          <Link to="/login">Entrar</Link>
        )}
      </nav>
      <main>
        <Outlet />
      </main>
    </div>
  );
}
```

## Lendo a store fora do React — `getState()`

Nem todo código que precisa do estado é um componente. O guard de rota da página
anterior roda **fora** da árvore React e não pode chamar hooks. Para esses casos,
use `getState()` no hook ligado — um snapshot pontual, sem assinatura:

```ts
// trecho do guard, da página de roteamento
guard: () => useAuth.getState().isAuthenticated,
```

!!! warning "`getState()` não assina — use só fora do React"

    `getState()` lê uma vez e **não** re-renderiza nada quando o estado muda
    depois. Dentro de componentes, prefira sempre o hook (`useAuth.use.campo()`)
    para a UI ficar em sincronia. Reserve `getState()` para guards de rota,
    interceptors de HTTP e outros códigos fora da árvore React.

## Recap

- **`createStore<T>(initializer, options?)`** cria uma store Zustand genérica;
  leia com um seletor (`useStore((s) => s.campo)`) pra assinar só o que importa.
- **`createSelectors(store)`** adiciona o namespace `.use`, com um hook por campo
  (`useStore.use.campo()`) → menos re-renders, sem digitar seletores. ✅
- **`createAuthStore<TUser>({ name, storage })`** é a store de auth pronta e
  **persistida**, com `user` / `token` / `isAuthenticated` / `setSession` /
  `setToken` / `setUser` / `logout`. Você só define o `TUser`.
- Dentro de componentes, leia com `.use.campo()`; fora do React (guards,
  interceptors), leia com `getState()` — snapshot sem assinatura.
- Ambas são Zustand por baixo, então `createSelectors` e `getState()` funcionam
  igual nas duas.

➡️ **Próxima página:** [Buscando dados — providers, cliente HTTP e React Query](data-fetching.md)

---

# utilities.md

# Utilitários

Coleção de funções puras, sem dependência de React, pra resolver as tarefas chatas do dia a dia — agrupar listas, mesclar objetos, debouncar callbacks, formatar bytes. Tudo é importado direto de `tempest-react-sdk` e funciona em qualquer ambiente JS (browser, Node, worker).

```ts
import { groupBy, pick, debounce, formatBytes } from "tempest-react-sdk";
```

!!! tip "Tree-shaking"
    Cada função é um export nomeado independente. Importe só o que usar — o bundler do seu app remove o resto.

---

## Arrays

Helpers de coleção que **nunca mutam** a entrada — sempre devolvem um novo array (ou objeto).

| Função                     | Assinatura                                                  | O que faz                                                        |
| -------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------- |
| `groupBy(items, key)`      | `<T, K>(items: T[], key: (item: T) => K) => Record<K, T[]>` | Agrupa items em baldes pela chave retornada por `key`.           |
| `uniqueBy(items, key)`     | `<T>(items: T[], key: (item: T) => unknown) => T[]`         | Remove duplicatas, mantendo a primeira ocorrência de cada chave. |
| `chunk(items, size)`       | `<T>(items: T[], size: number) => T[][]`                    | Quebra a lista em pedaços de no máximo `size` items.             |
| `range(start, end, step?)` | `(start: number, end: number, step?: number) => number[]`   | Gera uma faixa numérica `[start, end)` com passo `step` (1).     |

```ts
import { groupBy, uniqueBy, chunk, range } from "tempest-react-sdk";

groupBy([1, 2, 3, 4], (n) => (n % 2 === 0 ? "even" : "odd"));
// { odd: [1, 3], even: [2, 4] }

uniqueBy(
  [
    { id: 1, v: "a" },
    { id: 1, v: "b" },
    { id: 2, v: "c" },
  ],
  (u) => u.id,
);
// [{ id: 1, v: "a" }, { id: 2, v: "c" }]

chunk([1, 2, 3, 4, 5], 2); // [[1, 2], [3, 4], [5]]

range(0, 5); // [0, 1, 2, 3, 4]
range(0, 10, 2); // [0, 2, 4, 6, 8]
range(5, 0, -1); // [5, 4, 3, 2, 1]
```

!!! warning "`chunk` exige `size >= 1`"
    Chamar `chunk(items, 0)` lança `RangeError`. `range` com passo na direção errada (ou `0`) devolve `[]` em vez de estourar.

---

## Objetos

Cópias imutáveis e merge recursivo. Nenhuma dessas funções altera a entrada.

| Função                   | Assinatura                                                | O que faz                                                           |
| ------------------------ | --------------------------------------------------------- | ------------------------------------------------------------------- |
| `pick(obj, keys)`        | `<T, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>` | Novo objeto só com as chaves pedidas (chaves ausentes são puladas). |
| `omit(obj, keys)`        | `<T, K extends keyof T>(obj: T, keys: K[]) => Omit<T, K>` | Novo objeto sem as chaves indicadas.                                |
| `deepMerge(target, src)` | `<T>(target: T, source: Partial<T>) => T`                 | Merge recursivo de objetos planos; arrays/instâncias substituem.    |
| `isEmpty(value)`         | `(value: unknown) => boolean`                             | `true` pra `null`, `""`, `[]`, `{}`, `Map`/`Set` vazios.            |

```ts
import { pick, omit, deepMerge, isEmpty } from "tempest-react-sdk";

pick({ id: 1, name: "Ana", age: 30 }, ["id", "name"]);
// { id: 1, name: "Ana" }

omit({ id: 1, name: "Ana", age: 30 }, ["age"]);
// { id: 1, name: "Ana" }

interface Settings {
  a: number;
  nested: { x: number; y: number; z?: number };
}

const base: Settings = { a: 1, nested: { x: 1, y: 2 } };

deepMerge(base, { nested: { x: 1, y: 20, z: 30 } });
// { a: 1, nested: { x: 1, y: 20, z: 30 } }

isEmpty(0); // false — números nunca são "vazios"
isEmpty(false); // false
isEmpty(""); // true
```

!!! info "`deepMerge` não funde arrays"
    Arrays e valores não-planos (datas, instâncias de classe, primitivos) **substituem** o valor do `target` inteiro — não há merge elemento a elemento. `deepMerge({ tags: ["a", "b"] }, { tags: ["c"] })` resulta em `{ tags: ["c"] }`.

---

## Type guards

Narrowing seguro de tipos. Combinam bem com `Array.prototype.filter` e `switch` exaustivos.

| Função                         | Assinatura                                             | O que faz                                                |
| ------------------------------ | ------------------------------------------------------ | -------------------------------------------------------- |
| `isDefined(value)`             | `<T>(value: T \| null \| undefined) => value is T`     | `true` quando o valor não é `null` nem `undefined`.      |
| `isString(value)`              | `(value: unknown) => value is string`                  | `true` pra string primitiva.                             |
| `isNumber(value)`              | `(value: unknown) => value is number`                  | `true` pra número, **excluindo** `NaN`.                  |
| `isPlainObject(value)`         | `(value: unknown) => value is Record<string, unknown>` | `true` só pra objeto literal (não array/data/instância). |
| `assertNever(value, message?)` | `(value: never, message?: string) => never`            | Lança sempre — marca caminhos inalcançáveis.             |

```ts
import { isDefined, isNumber, assertNever } from "tempest-react-sdk";

const xs: (number | null)[] = [1, null, 2];
const clean: number[] = xs.filter(isDefined); // [1, 2] — tipo já narrowed

isNumber(NaN); // false
isNumber("42"); // false

type Shape = "circle" | "square";
function area(shape: Shape): number {
  switch (shape) {
    case "circle":
      return 1;
    case "square":
      return 2;
    default:
      return assertNever(shape); // erro de compilação se um caso for esquecido
  }
}
```

!!! tip "`assertNever` é checagem de exaustividade"
    Use no `default` de um `switch`. Se você adicionar um membro novo à union e esquecer de tratá-lo, o TypeScript reclama na hora da compilação — e o runtime falha alto se algo escapar.

---

## Funções

Wrappers de controle de execução. `debounce` e `throttle` expõem `.cancel()`.

| Função               | Assinatura                                                                     | O que faz                                                          |
| -------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `debounce(fn, wait)` | `<A>(fn: (...a: A) => void, wait: number) => ((...a: A) => void) & { cancel }` | Adia `fn` até `wait` ms sem novas chamadas (trailing-edge).        |
| `throttle(fn, wait)` | `<A>(fn: (...a: A) => void, wait: number) => ((...a: A) => void) & { cancel }` | Executa no máximo 1x por `wait` ms (leading + trailing edge).      |
| `once(fn)`           | `<A, R>(fn: (...a: A) => R) => (...a: A) => R`                                 | Roda `fn` só na primeira chamada; depois devolve o cache.          |
| `memoizeOne(fn)`     | `<A, R>(fn: (...a: A) => R) => (...a: A) => R`                                 | Memoiza apenas a última chamada (args comparados com `Object.is`). |

```ts
import { debounce, throttle, once, memoizeOne } from "tempest-react-sdk";

const save = debounce((q: string) => search(q), 300);
save("a");
save("ab");
save("abc"); // só "abc" roda após 300ms
save.cancel(); // cancela a chamada pendente

const onScroll = throttle(() => render(), 200);
window.addEventListener("scroll", onScroll);

const init = once(() => expensiveSetup());
init(); // roda
init(); // devolve o mesmo resultado, sem re-rodar

const select = memoizeOne((a: number, b: number) => a + b);
select(1, 2); // calcula 3
select(1, 2); // cache 3
select(2, 2); // recalcula 4
```

!!! note "`memoizeOne` lembra só do último"
    Diferente de um cache LRU — qualquer lista de argumentos diferente recomputa e substitui o cache. Ideal pra selectors derivados de props.

---

## Promises

| Função                           | Assinatura                                                             | O que faz                                                      |
| -------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------- |
| `sleep(ms)`                      | `(ms: number) => Promise<void>`                                        | Resolve depois de `ms` milissegundos.                          |
| `withTimeout(promise, ms, msg?)` | `<T>(promise: Promise<T>, ms: number, message?: string) => Promise<T>` | Corre `promise` contra um timeout; rejeita com `TimeoutError`. |

```ts
import { sleep, withTimeout } from "tempest-react-sdk";

await sleep(500); // pausa meio segundo

try {
  await withTimeout(fetch("/slow"), 3000, "request too slow");
} catch (error) {
  // error.name === "TimeoutError" quando estourou os 3s
}
```

---

## IDs

| Função              | Assinatura                    | O que faz                                                         |
| ------------------- | ----------------------------- | ----------------------------------------------------------------- |
| `randomId(prefix?)` | `(prefix?: string) => string` | Id resistente a colisão (usa `crypto.randomUUID()` com fallback). |

```ts
import { randomId } from "tempest-react-sdk";

randomId(); // "9f1c2b3a-..." (uuid) ou "lq3f8k-4a9z1" (fallback)
randomId("user"); // "user-9f1c2b3a-..."
```

!!! tip "Bom pra keys de UI"
    Use em listas geradas no cliente quando não há id estável vindo do servidor. Para ids persistidos, prefira o id real do backend.

---

## Strings

| Função                            | Assinatura                                                     | O que faz                                                     |
| --------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------- |
| `capitalize(value)`               | `(value: string) => string`                                    | Maiúscula só no primeiro caractere.                           |
| `camelCase(value)`                | `(value: string) => string`                                    | Converte pra `camelCase`.                                     |
| `kebabCase(value)`                | `(value: string) => string`                                    | Converte pra `kebab-case` (quebra também em `camelCase`).     |
| `pluralize(count, singular, pl?)` | `(count: number, singular: string, plural?: string) => string` | Escolhe singular/plural pela contagem (devolve só a palavra). |

```ts
import { capitalize, camelCase, kebabCase, pluralize } from "tempest-react-sdk";

capitalize("hello world"); // "Hello world"

camelCase("foo-bar_baz"); // "fooBarBaz"
camelCase("API response"); // "apiResponse"

kebabCase("helloWorld"); // "hello-world"
kebabCase("APIResponse"); // "api-response"

pluralize(1, "item"); // "item"
pluralize(3, "item"); // "items"
pluralize(2, "person", "people"); // "people"
```

!!! note "Pré-existentes — `slugify` e `truncate`"
    Já presentes no módulo de strings: `slugify(input)` gera um slug URL-safe (`"São Paulo / Centro"` → `"sao-paulo-centro"`), e `truncate(input, max, suffix?)` corta texto em `max` caracteres acrescentando `…` (ou o `suffix` informado).

---

## Números

| Função                             | Assinatura                                     | O que faz                                                  |
| ---------------------------------- | ---------------------------------------------- | ---------------------------------------------------------- |
| `formatBytes(bytes, decimals?)`    | `(bytes: number, decimals?: number) => string` | Tamanho legível em B/KB/MB/GB/TB (base 1024).              |
| `formatCompactNumber(value, loc?)` | `(value: number, locale?: string) => string`   | Notação compacta (`1.2K`, `3.4M`) via `Intl.NumberFormat`. |
| `percentOf(part, total)`           | `(part: number, total: number) => number`      | Percentual 0–100, com base zero devolvendo `0`.            |

```ts
import { formatBytes, formatCompactNumber, clamp } from "tempest-react-sdk";

formatBytes(0); // "0 B"
formatBytes(1536); // "1.5 KB"
formatBytes(1536, 2); // "1.50 KB"

formatCompactNumber(1234); // "1.2K"
formatCompactNumber(5600000); // "5.6M"
formatCompactNumber(1234, "pt-BR"); // "1,2 mil"
```

!!! note "Pré-existente — `clamp`"
    `clamp(value, min, max)` prende um número no intervalo `[min, max]` (e tolera `min > max`, trocando os limites). `clamp(120, 0, 100)` → `100`.

!!! danger "`percentOf` existe pelo `NaN%`, não pela divisão"
    `(ativos / total) * 100` com `total === 0` produz `NaN`, e `NaN%` no painel vazio é a forma mais comum de um dashboard anunciar que ainda não tem dado. `percentOf(5, 0)` é `0`; não-finito também vira `0`.
    Ele **não** limita em 100 — 150% de uma meta é dado real que alguém quer ver.
    Cuidado com o par: `formatPercent` recebe **fração** (0–1), então é `formatPercent(percentOf(a, b) / 100)`.

---

## Data para `<input type="date">` — `formatDateForInput`

`formatDate` produz `dd/MM/yyyy`, que um `<input type="date">` rejeita — ele exige `yyyy-MM-dd`. Todo formulário com data reescreve esse recorte, e reescreve errado.

```ts
import { formatDateForInput } from "tempest-react-sdk";

formatDateForInput(new Date(2026, 4, 16)); // "2026-05-16"
formatDateForInput("2026-05-16"); // "2026-05-16"
formatDateForInput("não é data"); // "" — o input lê como "sem valor"
```

!!! danger "`toISOString().slice(0, 10)` erra o dia, e erra só à noite"
    É o reflexo de todo mundo, e `toISOString` converte pra UTC antes: em UTC-3, qualquer horário depois das 21h reporta o **dia seguinte**. O formulário abre na data errada só pra quem mexe à noite, que é o pior tipo de bug pra reproduzir. `formatDateForInput` monta a data pelas partes **locais**.

!!! warning "String `yyyy-MM-dd` volta intacta — e isso é essencial, não atalho"
    `new Date("2026-05-16")` é meia-noite **UTC**, que em UTC-3 é dia 15 às 21h. Sem esse desvio, devolver ao input exatamente o valor que o backend mandou o moveria um dia pra trás.

---

## Planilhas `.xlsx` — `writeXlsx`

Exportar dados como CSV parece simples até um acento virar `é` no Excel. `writeXlsx(headers, rows)` gera um workbook Office Open XML (`.xlsx`) de uma aba direto em memória — UTF-8 de ponta a ponta, então acentos sobrevivem em Excel/LibreOffice/Google Sheets sem a fragilidade de BOM do CSV. A única dependência é o `fflate` (usado para deflate do pacote), já embutido no SDK.

```ts
import { writeXlsx } from "tempest-react-sdk";

const bytes = writeXlsx(
  ["Nome", "Score", "Observação"],
  [
    ["Ada", 99, "aprovada"],
    ["Alan", 87, null], // null vira célula vazia
  ],
);

const blob = new Blob([bytes], {
  type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
});
```

- `headers: string[]` — a primeira linha (cabeçalho).
- `rows: (string | number | null)[][]` — cada valor vira uma célula: `number` usa o tipo nativo `"n"` (o app de planilha reconhece como número), `null` (ou `""`) vira célula vazia, o resto é string inline.
- Retorna os bytes do arquivo como `Uint8Array`.

O XML é enxuto de propósito: strings inline (sem tabela de shared-strings), sem estilos, sem merge. É um escritor **genérico** — mapeie seus registros de domínio para `headers`/`rows` na camada da sua aplicação.

!!! tip "Do byte ao usuário"
    Combine com [`shareOrDownloadBlob`](./share.md#exportar-um-arquivo-shareordownloadblob): `writeXlsx` → `new Blob([...])` → `shareOrDownloadBlob(blob, "dados.xlsx")` abre a sheet nativa no celular e baixa no desktop.

---

## CSV — `toCsv` e `downloadCsv`

O `.xlsx` é o formato certo pra quem vai **abrir** a planilha. CSV é o formato certo pra quem vai **importar** o arquivo em outro sistema — e é o que quase todo painel acaba escrevendo na mão, errando sempre nos mesmos dois pontos: um nome com vírgula parte a linha, e um nome com aspas quebra justamente a proteção que as aspas deveriam dar.

```ts
import { toCsv, downloadCsv, type CsvColumn } from "tempest-react-sdk";

const COLUNAS: CsvColumn<Usuario>[] = [
  { key: "nome", header: "Nome" },
  { key: "email", header: "E-mail" },
  { key: "plano", header: "Plano", csv: (u) => u.plano?.label ?? "" },
];

const texto = toCsv(usuarios, COLUNAS); // string pronta
await downloadCsv(usuarios, COLUNAS, "usuarios.csv"); // entrega ao usuário
```

| Assinatura | O que faz |
| --- | --- |
| `toCsv(rows, columns, options?)` | Devolve o arquivo inteiro como `string`. |
| `downloadCsv(rows, columns, fileName?, options?)` | Monta o blob `text/csv;charset=utf-8` e passa pro `shareOrDownloadBlob`. |
| `CsvColumn<T>` | `{ key, header, csv? }` |
| `CsvOptions` | `{ delimiter?: "," \| ";", bom?: boolean }` — defaults `","` e `true`. |

!!! danger "A coluna do `DataTable` **não** serve direto quando tem `render`"
    `DataTableColumn.render` devolve `ReactNode`. Exportar isso escreve `[object Object]` justamente na coluna que tem badge, link ou data formatada — a mais importante da tabela. Uma coluna **sem** `render` é estruturalmente compatível e pode ser reaproveitada; com `render`, dê o acessor `csv`.

!!! check "Escaping RFC 4180, e o BOM que o Excel pt-BR exige"
    Campo com o delimitador, com aspas ou com quebra de linha vira campo citado, e cada aspas interna é duplicada. O arquivo termina as linhas com `\r\n`. O BOM vem por padrão porque sem ele o Excel em pt-BR lê UTF-8 como Latin-1 e todo acento vira mojibake.

!!! tip "Delimitador `;` é o certo em locale pt-BR"
    Onde o separador decimal é a vírgula, o Excel abre um CSV separado por vírgula **em uma coluna só**. `{ delimiter: ";" }` resolve — e o escaping acompanha, citando o campo que contém `;` em vez do que contém `,`.

!!! info "`0` e `false` são exportados; `null` e `undefined` viram campo vazio"
    Vazio é ausência, não falsidade. Tratar `0` como vazio é como um relatório passa a sub-reportar toda linha que legitimamente vale zero. `Date` sai em ISO, que qualquer sistema reimporta sem adivinhar formato.

!!! note "Lista vazia gera o cabeçalho, não um arquivo vazio"
    Quem abre precisa ver quais colunas pediu. Arquivo de zero byte parece erro de exportação.

---

## Storage comprimido — `compressedStorage`

`localStorage` dá cerca de **5 MB por origem** e cobra **dois bytes por caractere**. Um app offline-first que guarda estado de verdade — um save de jogo, um rascunho longo, um cache de catálogo — bate nesse teto antes do que parece, e o sintoma é um `QuotaExceededError` no meio de uma escrita, não um aviso.

`compressedStorage` é o mesmo wrapper tipado do `storage`, só que gzipando o que escreve:

```ts
import { compressedStorage } from "tempest-react-sdk";

compressedStorage.set("save", { level: 12, inventory: items });

const save = compressedStorage.get("save", null);
```

- `get<T>(key, fallback)` — descomprime e faz parse. Chave ausente, ilegível ou corrompida devolve `fallback`; nunca lança.
- `set<T>(key, value)` — comprime e grava.
- `remove(key)` — apaga a chave.

!!! tip "Mesma implementação dos dois, via `createJsonStorage`"
    `storage` e `compressedStorage` são a **mesma** função por baixo —
    `createJsonStorage(codec)` — então a superfície dos dois não pode divergir. Até
    a v0.44.0 o comprimido era uma cópia escrita à mão das mesmas guardas, e **não
    tinha `remove`**, enquanto a docstring dele prometia que os dois eram
    intercambiáveis no call site. Quem seguiu a promessa quebrou no primeiro
    `remove`.

    Codec próprio é o mesmo caminho:

    ```ts
    import { createJsonStorage } from "tempest-react-sdk";

    // Um store que cifra antes de gravar.
    const secrets = createJsonStorage({
      serialize: (value) => encrypt(JSON.stringify(value)),
      deserialize: (raw) => JSON.parse(decrypt(raw)),
    });
    ```

    Se o codec **lançar**, o valor é gravado como JSON puro em vez de descartado:
    registro maior ainda carrega, registro ausente não. Só um valor que nem JSON
    representa (referência circular) perde a escrita.

### O formato é autodescritivo

Cada valor gravado leva o prefixo `~tgz1:`. Isso resolve o problema chato de ligar compressão numa chave que já existe: uma leitura sem o marcador cai no `JSON.parse` normal, então **os dados que já estavam lá continuam legíveis**. Nada de migração, nada de save órfão.

O mesmo caminho cobre a escrita degradada: se a compressão falhar, o valor é gravado como JSON puro em vez de descartado — um registro maior ainda carrega, um ausente não.

!!! note "Por que base64, e não empacotar em UTF-16"
    Base64 gasta um terço a mais de caracteres que os bytes comprimidos, e o `localStorage` ainda cobra dois bytes por caractere em cima disso. Empacotar os bytes direto em code units UTF-16 seria mais denso, mas surrogates soltos não sobrevivem a toda implementação de storage nem a um round-trip de JSON — e um save que decodifica em lixo é muito pior que um save maior. Mesmo com essa folga, um JSON típico fica bem abaixo de um terço do tamanho original.

### Com `useLocalStorage`

Para estado React, passe o codec em vez de usar a API imperativa — você ganha a sincronia entre abas e o guard de SSR do hook de graça:

```ts
import { compressedStorageCodec, useLocalStorage } from "tempest-react-sdk";

const [save, setSave] = useLocalStorage("save", EMPTY_SAVE, compressedStorageCodec);
```

`compressToString` / `decompressFromString` também são exportados soltos, para quando o destino não é `localStorage` (um `POST` de backup, um `IndexedDB`).

!!! warning "Não é para tudo"
    Comprimir custa CPU nas duas pontas. Para uma preferência de tema ou um flag booleano, use o `storage` normal — o ganho é zero e o custo não. `compressedStorage` vale a partir de payloads na casa das dezenas de KB.

---

## Recap

- Importe qualquer helper direto de `tempest-react-sdk` — todos são exports nomeados, puros e tree-shakable.
- **Planilhas**: `writeXlsx(headers, rows)` gera um `.xlsx` UTF-8 de uma aba como `Uint8Array` (sem drama de BOM do CSV).
- **CSV**: `toCsv(rows, columns)` escreve o arquivo com escaping RFC 4180 e BOM; `downloadCsv(...)` entrega direto ao usuário.
- **Datas e percentuais**: `formatDateForInput` dá o `yyyy-MM-dd` que o `<input type="date">` exige (pelas partes locais, sem o desvio de UTC); `percentOf` devolve `0` em vez de `NaN` quando a base é zero.
- **Storage comprimido**: `compressedStorage.get/set` gzipa o que grava; formato autodescritivo (`~tgz1:`) lê valores antigos sem migração. Com React, `useLocalStorage(key, def, compressedStorageCodec)`.
- **Arrays/Objetos**: `groupBy`, `uniqueBy`, `chunk`, `range`, `pick`, `omit`, `deepMerge`, `isEmpty` — sempre imutáveis; `deepMerge` substitui arrays em vez de fundir.
- **Guards**: `isDefined`, `isString`, `isNumber`, `isPlainObject`, `assertNever` — narrowing seguro + exaustividade em `switch`.
- **Funções**: `debounce`/`throttle` (com `.cancel()`), `once`, `memoizeOne` para controlar execução.
- **Promises/IDs/Strings/Números**: `sleep`, `withTimeout`, `randomId`, `capitalize`/`camelCase`/`kebabCase`/`pluralize`, `formatBytes`/`formatCompactNumber`.

## Veja também

- [Hooks utilitários](./hooks.md) — `useDebounce` é a versão React de `debounce`.
- [Utilitários & headless](./components/utility.md) — componentes que embrulham parte desses helpers (`Money`, `RelativeTime`).

---

# vision.md

# Vision (ONNX Runtime Web)

Visão computacional **no dispositivo** — direto no navegador, sem servidor de
inferência, sem upload da imagem pra lugar nenhum. O subpath
`tempest-react-sdk/vision` roda três tarefas clássicas em modelos ONNX:
**classificação** (que imagem é essa?), **detecção** (onde estão os objetos?) e
**segmentação de instâncias** (qual o contorno exato de cada objeto?) — mais o
pipeline fundido **detect→classify** num arquivo só.

A API é a mesma para todas: você cria um objeto com
`await Tarefa.create(modelo, opções)`, chama `predict(imagem)` e recebe um array
de resultados — um por imagem. Aprende uma, sabe as quatro.

```tsx
import { Detector } from "tempest-react-sdk/vision";

const det = await Detector.create("/models/yolov8n.onnx", { labels: "coco" });
const result = (await det.predict("/images/street.jpg"))[0];

for (const d of result) {
  console.log(d.name, d.confidence, d.box.xyxy);
}
```

## Por que um subpath separado

As tarefas de visão não vêm do barrel principal. Você as importa de
`tempest-react-sdk/vision`:

```tsx
import { Classifier, Detector, Segmenter } from "tempest-react-sdk/vision";
```

!!! info "De onde vem esse módulo"
    O código de visão é **vendorizado** do
    [`@mauriciobenjamin700/ort-vision-sdk-web`](https://www.npmjs.com/package/@mauriciobenjamin700/ort-vision-sdk-web)
    (MIT, mesmo autor do SDK). Em vez de você instalar um pacote a mais, ele já
    vem **dentro** do `tempest-react-sdk` — basta importar do subpath `/vision`.
    A API espelha 1-para-1 a do pacote original.

### `onnxruntime-web` é peer dependency opcional

O motor que de fato roda os modelos `.onnx` — o
[`onnxruntime-web`](https://onnxruntime.ai/docs/get-started/with-javascript/web.html)
— **não** vem junto. Ele é uma peer dependency **opcional**: o app o instala uma
vez, e o subpath de visão o reutiliza.

```bash
npm i onnxruntime-web
```

!!! warning "Sem o `onnxruntime-web`, a inferência não roda"
    Como o `onnxruntime-web` é peer dep **opcional**, o
    `npm install tempest-react-sdk` não o traz. Se você importar de
    `tempest-react-sdk/vision` sem ter rodado `npm i onnxruntime-web`, o build
    quebra com `Cannot find module 'onnxruntime-web'`. Ele fica **externalizado**
    no bundle do SDK — quem nunca importa do subpath `/vision` não paga esse peso
    (mesmo padrão do `recharts` nos charts e dos adapters que injetam a dep).

!!! danger "Você precisa servir os arquivos `.wasm`"
    O `onnxruntime-web` carrega o runtime via WebAssembly. Os arquivos `.wasm`
    correspondentes à **mesma versão** que você instalou têm que estar
    acessíveis em runtime (servidos pelo seu bundler ou copiados pra pasta
    pública). Versão do JS e dos `.wasm` desalinhadas é a causa nº 1 de "o modelo
    não carrega". Cada bundler tem sua receita (no Vite, costuma-se copiar os
    `.wasm` pra `public/` e apontar `ort.env.wasm.wasmPaths`).

!!! tip "WebGPU primeiro, WASM como fallback"
    Por padrão o SDK tenta os execution providers nesta ordem:
    `["webgpu", "wasm"]` (exportada como `DEFAULT_PROVIDERS`). O ORT-Web usa a
    GPU via **WebGPU** quando o navegador/dispositivo suporta e cai
    automaticamente para **WASM** (CPU) quando não. Você pode forçar a ordem
    passando `providers` nas opções de `create()`.

## A imagem de entrada

Todas as tarefas aceitam o **mesmo** conjunto de entradas — o tipo `ImageInput`.
Você não precisa decodificar nada na mão; o SDK resolve para o formato canônico
interno (`RGBImage`, HWC RGB uint8).

| Entrada              | Exemplo                                          |
| -------------------- | ------------------------------------------------ |
| `string` (URL)       | `det.predict("/images/cat.jpg")`                 |
| `Blob`               | `det.predict(await (await fetch(url)).blob())`   |
| `File`               | `det.predict(inputFile.files[0])`                |
| `HTMLImageElement`   | `det.predict(document.querySelector("img"))`     |
| `HTMLCanvasElement`  | `det.predict(canvas)`                            |
| `OffscreenCanvas`    | `det.predict(offscreen)`                         |
| `ImageBitmap`        | `det.predict(await createImageBitmap(blob))`     |
| `ImageData`          | `det.predict(ctx.getImageData(0, 0, w, h))`      |
| `RGBImage`           | `det.predict(rgbImage)` (formato canônico do SDK)|

!!! note "`File` entra pela porta do `Blob`"
    O tipo `ImageInput` lista `Blob`, e `File` é uma subclasse de `Blob` — então
    um `File` vindo de um `<input type="file">` é aceito direto, sem conversão.
    É o caminho natural pra "usuário escolheu uma foto".

## Detector — onde estão os objetos

`Detector` roda modelos YOLO anchor-free (v8/v9/v10/v11/v12) e devolve uma caixa
por objeto encontrado.

```tsx
import { Detector } from "tempest-react-sdk/vision";

const det = await Detector.create("/models/yolov8n.onnx", { labels: "coco" });

const result = (await det.predict("/images/street.jpg"))[0];

console.log(`${result.length} objetos detectados`);
for (const d of result) {
  console.log(d.name, d.confidence.toFixed(2), d.box.xyxy);
}
```

### A forma do resultado

`predict()` sempre devolve uma **Promise de um array de 1 elemento** — um
envelope por imagem, espelhando o `YOLO("img.jpg")` do Ultralytics. Por isso o
`[0]` logo após o `await`:

```tsx
const results = await det.predict(img); // DetectionResults[]
const result = results[0]; // DetectionResults
```

O envelope (`DetectionResults`) é **iterável**: percorrer com `for...of` dá uma
`DetectionResult` por objeto. Cada objeto traz nomes idiomáticos do estilo
Ultralytics **e** os nomes verbosos equivalentes — use o que preferir:

| Estilo Ultralytics | Nome verboso  | Tipo          | O que é                                  |
| ------------------ | ------------- | ------------- | ---------------------------------------- |
| `d.cls`            | `d.classId`   | `number`      | id numérico da classe                    |
| `d.name`           | `d.className` | `string`      | nome da classe (rótulo resolvido)        |
| `d.conf`           | `d.confidence`| `number`      | confiança em `[0, 1]`                     |
| `d.box`            | `d.bbox`      | `BoundingBox` | a caixa delimitadora                     |

A `BoundingBox` expõe as coordenadas em vários formatos:

```tsx
for (const d of result) {
  d.box.xyxy; // [x1, y1, x2, y2] em pixels absolutos (readonly tuple)
  d.box.xywh; // [cx, cy, w, h] com centro em (cx, cy)
  d.box.asXywh(); // [x, y, w, h] com canto superior-esquerdo em (x, y)
  d.box.xyxyn([result.origShape[0], result.origShape[1]]); // normalizado [0,1]
  d.box.width;
  d.box.height;
  d.box.area;
}
```

!!! tip "Visão em massa: a coleção `boxes`"
    Pra desenhar tudo numa só passada (num canvas, por exemplo), em vez de
    iterar use a view "numpy-style" `result.boxes`. Ela expõe arrays achatados:
    `boxes.xyxy` (`Float32Array` de `4 * N`), `boxes.cls` (`Int32Array`),
    `boxes.conf` (`Float32Array`), além de `boxes.xywh`, `boxes.xyxyn`,
    `boxes.xywhn` e `boxes.length`. E `result.names` mapeia id → nome, igual ao
    `model.names` do Ultralytics.

### Filtros e thresholds

```tsx
const result = (
  await det.predict(img, {
    confThreshold: 0.4, // só mantém detecções com confiança ≥ 0.4
    iouThreshold: 0.5, // IoU do non-maximum suppression
    classes: [0, 2], // só "person" (0) e "car" (2)
  })
)[0];
```

Os defaults (definidos no `create()`) são `confThreshold: 0.25`,
`iouThreshold: 0.45`, `maxDetections: 300` e `inputSize: [640, 640]` — este
último só entra em cena quando o modelo não declara resolução (ver
[A resolução vem do modelo](#a-resolucao-vem-do-modelo)).

### `raiseOnEmpty` — quando "não achei nada" é erro

Por padrão, uma run que não encontra nada resolve com um envelope **vazio**:
olhar e não achar é uma inferência bem-sucedida. Quando o vazio deve **parar** o
fluxo em volta (um wizard que exige ao menos um documento na foto, por exemplo),
ligue `raiseOnEmpty` e trate o `NoDetectionsError`:

```tsx
import { Detector, NoDetectionsError } from "tempest-react-sdk/vision";

const det = await Detector.create("/models/yolov8n.onnx", {
  confThreshold: 0.7,
  raiseOnEmpty: true,
});

try {
  const result = (await det.predict("/images/doc.jpg"))[0];
  console.log(result.length); // sempre ≥ 1 aqui
} catch (err) {
  if (err instanceof NoDetectionsError) {
    // NoDetectionsError: No detections in /images/doc.jpg: nothing cleared
    // confThreshold=0.7.
    console.warn(err.message);
  }
}
```

A flag existe no `create()` e como override por chamada
(`det.predict(img, { raiseOnEmpty: false })`). Vale para `Detector`, `Segmenter`
e [`DetectClassify`](#detectclassify-detectar-e-classificar-num-modelo-so) — os
três compartilham a mesma mensagem, que nomeia o threshold aplicado e, quando
existirem, a imagem e o filtro de classes que estreitaram a busca.

!!! note "Vazio continua sendo o default — de propósito"
    Coleção vazia não é erro (é a mesma regra dos endpoints de listagem do
    SDK). `raiseOnEmpty` é opt-in porque só quem conhece o fluxo em volta sabe
    se zero linhas é resultado ou falha.

## Classifier — que imagem é essa

`Classifier` aplica pré-processamento estilo ImageNet (224×224 por padrão,
normalização com média/desvio do ImageNet) e devolve a distribuição de
probabilidades. `labels` é opcional: sem ele valem os `names` que o export
gravou no `.onnx` (ver [Rótulos vêm do modelo](#rotulos-vem-do-modelo)). Um
ResNet ImageNet baixado pronto normalmente **não** traz `names`, então aí você
passa a lista:

```tsx
import { Classifier } from "tempest-react-sdk/vision";

const labels = await fetch("/models/imagenet-classes.json").then((r) => r.json());

const clf = await Classifier.create("/models/resnet50.onnx", { labels });

const result = (await clf.predict("/images/dog.jpg"))[0];

console.log(result.cls, result.conf, result.name); // top-1
console.log(result.probs.top5, result.probs.top5conf); // top-5
```

O envelope `ClassificationResults` expõe atalhos pro top-1 (`cls`, `conf`,
`name`) e a coleção `probs` com a distribuição completa:

| Acesso              | Tipo          | O que é                                  |
| ------------------- | ------------- | ---------------------------------------- |
| `result.cls`        | `number`      | id da classe top-1                       |
| `result.conf`       | `number`      | confiança da classe top-1                |
| `result.name`       | `string`      | nome da classe top-1                     |
| `result.probs.top1` | `number`      | id da classe mais provável               |
| `result.probs.top5` | `Int32Array`  | ids das 5 classes mais prováveis         |
| `result.probs.data` | `Float32Array`| vetor completo de probabilidades         |

Pra truncar a lista por-classe ao top-K, passe `topK` em `predict`:

```tsx
const result = (await clf.predict(img, { topK: 3 }))[0];
for (const p of result.probabilities) {
  console.log(p.name, p.conf);
}
```

## Segmenter — o contorno de cada objeto

`Segmenter` roda modelos YOLO-seg (v8-seg / v11-seg / ...) e devolve, além da
caixa, uma **máscara binária por instância**.

```tsx
import { Segmenter } from "tempest-react-sdk/vision";

const seg = await Segmenter.create("/models/yolov8n-seg.onnx", { labels: "coco" });

const result = (await seg.predict("/images/street.jpg"))[0];

for (const inst of result) {
  console.log(inst.name, inst.conf, inst.box.xyxy);
  console.log(inst.mask.width, inst.mask.height); // máscara recortada na caixa
}
```

O envelope `SegmentationResults` é iterável (dá uma `SegmentationResult` por
instância) e ainda expõe duas views em massa:

- `result.boxes` — a mesma view de caixas do `Detector`.
- `result.masks` — coleção iterável de máscaras binárias, cada uma recortada na
  caixa da sua instância (`masks.length`, e cada item tem `data`, `width`,
  `height`).

Cada `SegmentationResult` carrega os mesmos campos da detecção (`cls`/`conf`/
`name`/`box` + aliases) mais:

- `mask` — a máscara binária (`Mask`, valores `0`/`255`, recortada na caixa).
- `segmentedImage` — o recorte original com o fundo zerado (pronto pra exibir).

## DetectClassify — detectar e classificar num modelo só

O caso clássico de duas etapas: um detector acha os objetos, e um classificador
diz **qual sub-categoria** cada objeto é ("tem um pássaro aqui" → "é um
bem-te-vi"). Fazer isso com dois `.onnx` custa dois downloads, duas
inicializações de sessão (WASM/WebGPU) e uma ida-e-volta pelo JavaScript por
recorte — cortar, redimensionar e reempilhar as regiões antes do segundo modelo
ver qualquer coisa.

`DetectClassify` roda um `.onnx` **fundido**: os dois modelos mais a ponte de
crop-and-resize entre eles vivem no mesmo grafo. Um download, uma sessão,
nenhuma ida-e-volta.

```tsx
import { DetectClassify } from "tempest-react-sdk/vision";

const pipeline = await DetectClassify.create("/models/birds-pipeline.onnx");

const result = (await pipeline.predict("/images/flock.jpg"))[0];

for (const d of result) {
  console.log(d.name, d.conf.toFixed(2)); // o que o detector viu
  console.log(d.classification?.name, d.classification?.conf); // a espécie
}
```

!!! info "O arquivo fundido é construído em Python"
    A fusão é um passo de build do `ort-vision-sdk` em Python
    (`ort_vision_sdk.compose.fuse_detect_classify`, 0.7.0+). O navegador só
    **roda** o pipeline pronto. Carregar um `.onnx` comum aqui lança
    `FusionError` com a mensagem apontando o caminho certo (usar
    `Detector`/`Classifier`, ou fundir antes).

Nada é reconfigurado do lado do JavaScript: a resolução do letterbox, o tamanho
do crop, se a saída do classificador ainda precisa de softmax e os nomes de
classe **das duas etapas** são lidos do metadata `ovs.*` que a fusão gravou no
arquivo. Por isso um pipeline fundido uma vez se comporta igual nos dois
runtimes. Pra inspecionar isso na mão, `readFusionSpec(session.metadata)` devolve
o `FusionSpec`, e a task expõe o seu em `pipeline.spec`.

### O envelope tem dois espaços de rótulo

`DetectClassifyResults` é iterável como o do `Detector`, e cada item é uma
`DetectionResult` normal (`cls`/`conf`/`name`/`box` + aliases, `croppedImage`)
com um campo a mais:

| Acesso                     | Tipo                          | O que é                                        |
| -------------------------- | ----------------------------- | ---------------------------------------------- |
| `d.classification`         | `ClassificationResult \| null`| o que o classificador disse **daquele recorte** |
| `result.names`             | `Record<number, string>`      | rótulos da etapa de **detecção**                |
| `result.classifierNames`   | `Record<number, string>`      | rótulos da etapa de **classificação**           |
| `result.boxes`             | `Boxes`                       | a mesma view em massa do `Detector`             |

Os dois mapas são separados porque as duas etapas respondem perguntas
diferentes, com espaços de classe sem relação entre si — colapsar num só perderia
uma das respostas. Para sobrescrever, `labels` vale pra detecção e
`classifierLabels` pra classificação.

### Filtros do pipeline

```tsx
const result = (
  await pipeline.predict(img, {
    confThreshold: 0.5, // filtra **além** do NMS já fixado na fusão
    classes: [14], // só a classe 14 do detector
    topK: 3, // trunca d.classification.probabilities
    raiseOnEmpty: true, // vazio vira NoDetectionsError
  })
)[0];
```

!!! warning "O threshold da fusão é um piso, não um teto"
    O NMS e o `confThreshold` do grafo foram fixados **no momento da fusão**.
    `confThreshold` aqui só filtra mais — não dá pra afrouxar pra baixo do que
    o arquivo já decidiu. Precisa de um piso menor? Refunda o pipeline em
    Python.

## A resolução vem do modelo

`inputSize` é opcional e serve de **fallback**. A resolução em que a task
pré-processa é lida do shape que o grafo `.onnx` declara:

```tsx
const clf = await Classifier.create("/models/classify.onnx", { labels: LABELS });
console.log(clf.inputSize); // [224, 224] — lido do arquivo, não configurado
```

!!! danger "Por que isso não podia ficar na configuração"
    Um export `-cls` do Ultralytics sai em 224×224; um detector, em 640×640.
    Alimentar o grafo com o tamanho errado faz o ORT abortar a run com
    `Got invalid dimensions for input: images ... Got: 640 Expected: 224` — e o
    número só existe dentro do `.onnx`, então nenhuma constante, manifest ou env
    var ao lado dele podia acertar sozinha.

Passar um `inputSize` que contradiz um grafo estático emite um aviso no console
e é ignorado: obedecer ali só trocaria um problema corrigível por uma execução
que falha. Em modelos com eixo dinâmico o seu valor vale, e o default da task é
o último recurso.

A sessão também expõe o que leu, e agora sabe se liberar:

```tsx
console.log(clf.session.inputShape); // [1, 3, 224, 224] — null em eixo dinâmico
await clf.session.release(); // libera a sessão nativa
```

!!! tip "Telemetria honesta"
    `task.inputSize` é a resolução que a inferência **realmente** usou. Reportar
    o valor configurado esconde justamente o bug que você está caçando.

!!! warning "Celular com pouca memória: `release()` não é opcional"
    O ORT copia o `.onnx` para o heap WASM e aloca grafo e pesos **em cima** dessa
    cópia. Enquanto isso, os bytes que o SDK baixou para ler os metadados também
    estão vivos no heap JS — um modelo de 5 MB custa 5 MB + 5 MB + pesos no mesmo
    instante. O SDK lê os metadados **antes** de construir a sessão justamente para
    esse buffer morrer o quanto antes (desde a v0.38.1 — antes disso ele sobrevivia
    a toda a construção).

    Quando a conta não fecha, o ORT desiste com `Can't create a session. failed to
    allocate a buffer of size N`. Na ordem: **carregue um modelo por vez** (dois
    `create` concorrentes dobram o pico), chame `session.release()` no que sai de
    uso — soltar a referência JS **não** libera a sessão nativa — e decodifique a
    foto já reduzida, que num celular pesa mais que os dois modelos juntos. Se
    ainda não bastar, `readMetadata: false` **com `labels` explícito** tira o SDK do
    caminho: o ORT busca o modelo sozinho e nada aqui segura os bytes (o tamanho de
    entrada continua vindo do grafo; só os nomes das classes se perdem).

Os helpers puros por trás disso (`spatialInputSize`, `resolveInputSize`,
`declaredShapesFrom`) também são exportados, para quem monta o próprio pipeline
sem precisar importar tipos do `onnxruntime-web`.

## Rótulos vêm do modelo

`labels` é opcional nas três tarefas. Omitido, valem os `names` que o export
gravou nos metadados do `.onnx` — o Ultralytics escreve
`{0: 'deworm', 1: 'not_deworm'}` — e só um modelo sem `names` cai no preset COCO
(detecção/segmentação) ou em `class_<id>` (classificação):

```tsx
const det = await Detector.create("/models/detect.onnx");

console.log(det.labels); // ["ocular-mucosa"] — do modelo, não de um preset
console.log(det.numClasses); // 1 — deduzido do shape de saída (B, 4 + nc, N)
```

A precedência é a mesma do `ort-vision-sdk` em Python: o que você passa ganha,
depois os `names` do modelo, e por último o preset. Passar `numClasses` continua
validando os rótulos contra o modelo (`LabelMapError` se divergir).

!!! danger "Lista de rótulos à mão é o pior tipo de configuração"
    Ela não falha quando está errada — as predições só trocam de classe, e você
    descobre olhando resultado. Isso também consertou um tropeço real: um detector
    de **uma** classe **falhava** sem `labels` explícito, porque o default COCO de
    80 nomes discordava da contagem de classes do modelo.

A sessão expõe o que leu do arquivo, para quem quer os dados crus:

```tsx
console.log(det.session.metadata.task); // "detect" — o mapa que o export gravou
console.log(det.session.outputShape); // [1, 5, 8400] — null em eixo dinâmico
```

Os helpers puros também são exportados: `readModelMetadata`, `modelNames`,
`detectionNumClasses` e `classificationNumClasses`.

!!! info "Um modelo informado por URL é baixado pelo SDK"
    O `onnxruntime-web` não expõe o mapa de metadados do modelo (diferente do
    `custom_metadata_map` do Python), então os `metadata_props` são lidos dos
    próprios bytes do `.onnx`. É o mesmo download único, e `readMetadata: false`
    nas opções da sessão restaura o caminho anterior (o ORT busca a URL). Um fetch
    que falha ainda entrega a URL ao ORT, para não transformar perda de metadados
    em falha de carregamento.

## Rótulos: presets, listas e dicts

Como o navegador não tem sistema de arquivos, o SDK **não** lê rótulos de um
caminho — você passa os nomes direto. A função `resolveLabels` (e o campo
`labels` de cada tarefa) aceita:

```tsx
import { resolveLabels, COCO_CLASSES } from "tempest-react-sdk/vision";

resolveLabels("coco"); // preset → as 80 classes do COCO
resolveLabels(["gato", "cachorro"]); // array explícito, indexado por id
resolveLabels({ 0: "gato", 2: "pássaro" }); // dict esparso (lacunas viram class_1)
resolveLabels(null, { numClasses: 3 }); // auto: ["class_0", "class_1", "class_2"]

COCO_CLASSES; // o array readonly das 80 classes, em ordem canônica
```

!!! note "Default de rótulos por tarefa"
    Omitir `labels` primeiro tenta os `names` do próprio modelo
    ([Rótulos vêm do modelo](#rotulos-vem-do-modelo)). Só quando o `.onnx` não
    carrega nenhum é que `Detector` e `Segmenter` assumem o preset **`"coco"`** —
    afinal os pesos YOLO mais comuns são treinados no COCO — e o `Classifier` gera
    `class_<id>` a partir da contagem de classes lida do shape de saída. Passar
    `numClasses` valida que a contagem de rótulos bate com a do modelo
    (`LabelMapError` se divergir).

## Hooks de câmera e luminância

Antes de rodar qualquer modelo você precisa de um **frame** — e de um frame que
preste. O subpath `/vision` traz três primitivas de navegador pra isso: abrir a
câmera, medir o brilho ao vivo e rejeitar capturas escuras demais. Elas são
genéricas (não dependem de nenhum modelo), mas moram no `/vision` porque é ali
que a captura acontece.

### `useCameraStream` — abrir a câmera

Pede um `MediaStream` via `getUserMedia`, prende num `<video>` e expõe
`status`/`error` já classificados, pra você renderizar os estados de permissão e
erro sem decorar os nomes de `DOMException`. O stream é liberado sozinho no
unmount e no `retry()`.

```tsx
import { useCameraStream } from "tempest-react-sdk/vision";

function CameraView() {
  const { status, error, videoRef, retry } = useCameraStream();

  if (status === "error") {
    return (
      <div>
        <p>{error?.message}</p>
        <button onClick={retry}>Tentar de novo</button>
      </div>
    );
  }

  return (
    <video ref={videoRef} playsInline muted style={{ opacity: status === "ready" ? 1 : 0.4 }} />
  );
}
```

Por padrão pede a câmera **traseira** (`facingMode: "environment"`) em Full-HD —
o ideal pra tirar foto de algo à sua frente. Desktops caem na única câmera que
expõem. Pra sobrescrever, passe `constraints`:

```tsx
const cam = useCameraStream({
  constraints: { video: { facingMode: "user" }, audio: false }, // câmera frontal
});
```

O `error.kind` é um enum estável — mapeie-o pra UI, não pra `error.message`:

| `kind`              | Quando acontece                                             |
| ------------------- | ----------------------------------------------------------- |
| `unsupported`       | navegador sem `getUserMedia` (ou SSR).                      |
| `insecure`          | página fora de HTTPS (contexto não seguro).                 |
| `permission-denied` | usuário negou (ou o SO bloqueou) o acesso.                  |
| `no-camera`         | nenhum dispositivo de câmera / constraints impossíveis.     |
| `in-use`            | a câmera está presa por outro app.                          |
| `unknown`           | qualquer outra falha (a mensagem original vem em `message`).|

!!! warning "Câmera só em contexto seguro"
    `getUserMedia` só funciona sob **HTTPS** (ou `localhost`). Numa origem
    insegura o hook devolve `status: "error"` com `kind: "insecure"` — não é bug,
    é política do navegador. As mensagens em `error.message` são em **inglês**;
    traduza na sua camada de i18n se precisar.

### `computeImageLuminance` + `useLiveLuminance` — medir o brilho

`computeImageLuminance` calcula a **luminância média BT.709**
(`0.2126*R + 0.7152*G + 0.0722*B`, escala `0..255`) de um frame já
decodificado — `<img>`, `<video>`, `<canvas>`, `ImageBitmap` ou
`OffscreenCanvas`. Faz downsample até no máximo `LUMINANCE_SAMPLE_MAX_EDGE`
(256px) antes de ler os pixels — estatisticamente equivalente pra um threshold e
ordens de magnitude mais rápido que ler o frame inteiro.

```tsx
import {
  computeImageLuminance,
  isLuminanceAcceptable,
  LowLuminanceError,
} from "tempest-react-sdk/vision";

const luminance = computeImageLuminance(videoOrImageOrCanvas); // 0..255
if (!isLuminanceAcceptable(luminance, 70)) {
  throw new LowLuminanceError(luminance, 70);
}
```

!!! note "O threshold é seu"
    `isLuminanceAcceptable(luminance, threshold)` recebe o `threshold`
    **obrigatoriamente** — o valor ideal depende do seu modelo, da luz em que ele
    foi treinado e da taxa de rejeição aceitável. O SDK não crava um default.
    `LowLuminanceError` carrega `.luminance` e `.threshold` pra você mostrar
    feedback acionável.

!!! tip "Foto de celular: decodifique reduzido e meça o mesmo frame"
    Uma foto de 12 MP virá a ~48 MB de RGBA se você decodificar inteira — mais que
    os dois modelos somados, e o pico onde o ORT começa a recusar sessão. Peça o
    frame já reduzido e trabalhe nele; `ImageBitmap` é aceito tanto aqui quanto no
    `predict()` das tasks, então o frame que você mede é o frame que você infere:

    ```tsx
    const frame = await createImageBitmap(photoBlob, {
      resizeWidth: 1280,
      resizeQuality: "high",
    });
    const luminance = computeImageLuminance(frame); // 0..255, sem outro decode
    const result = (await det.predict(frame))[0];
    frame.close(); // libera na hora, sem esperar o GC
    ```

    As caixas voltam no espaço do frame reduzido — multiplique pelo fator de
    escala se você persiste coordenadas na resolução original. E `close()` importa:
    é a única forma determinística de devolver a memória.

Pra feedback **ao vivo** (barra de brilho, borda que muda de cor enquanto a
câmera está aberta), `useLiveLuminance` amostra o `<video>` num laço de
`requestAnimationFrame`, reaproveitando um único canvas offscreen:

```tsx
import { useCameraStream, useLiveLuminance, isLuminanceAcceptable } from "tempest-react-sdk/vision";

function BrightnessGuardedCamera() {
  const { status, videoRef } = useCameraStream();
  const luminance = useLiveLuminance(videoRef, { enabled: status === "ready" });
  const bright = isLuminanceAcceptable(luminance, 70);

  return (
    <div style={{ border: `3px solid ${bright ? "green" : "orange"}` }}>
      <video ref={videoRef} playsInline muted />
      {!bright && <p>Ambiente escuro — aproxime-se de uma luz.</p>}
    </div>
  );
}
```

Ele pausa sozinho quando `enabled` é `false` ou enquanto o vídeo ainda não está
pronto (`readyState < 2`), e é limitado por `intervalMs` (padrão `160`, ~6 fps —
mais que suficiente pra UX).

!!! tip "Pré-visualizar o frame capturado: `useObjectUrl`"
    Depois de exportar o frame pra um `Blob` (`canvas.toBlob(...)`), use o
    [`useObjectUrl`](hooks.md) (barrel principal, `tempest-react-sdk`) pra virar
    um `src` de `<img>` sem vazar memória — ele cria o `URL.createObjectURL` e o
    revoga sozinho quando o blob muda ou o componente desmonta.

    ```tsx
    import { useObjectUrl } from "tempest-react-sdk";

    const previewUrl = useObjectUrl(capturedBlob);
    return previewUrl ? <img src={previewUrl} alt="Prévia" /> : null;
    ```

## `warmup()` — a primeira inferência não é representativa

A primeira run de uma sessão paga custos que nenhuma das seguintes paga: o
WebGPU compila os shaders nela, e o backend WASM materializa suas arenas. Num
celular isso vira "o primeiro frame demorou segundos, os outros levam dezenas de
milissegundos". `warmup()` roda o modelo uma vez num tensor de zeros, movendo
esse custo pra onde o usuário já está olhando um spinner:

```tsx
const det = await Detector.create("/models/yolov8n.onnx", { labels: "coco" });
await det.warmup(); // ainda na tela de carregamento

// a partir daqui, cada predict() é tempo de inferência de verdade
const result = (await det.predict(frame))[0];
```

Disponível nas **quatro** tarefas. `warmup(2)` roda duas vezes — uma basta pro
WASM, e o WebGPU às vezes só assenta na segunda. Em `DetectClassify` é onde mais
rende: dois modelos e a ponte compilam juntos na primeira inferência.

!!! tip "Aqueça as duas etapas de uma análise, não só a primeira"
    Num app que detecta e depois classifica com **dois modelos separados**, cada
    sessão paga a sua própria primeira inferência. Aquecer só o detector deixa o
    custo do classificador exatamente onde ele mais aparece: no instante entre o
    usuário terminar de esperar e a resposta surgir.

    ```tsx
    await Promise.all([detector.warmup(), classifier.warmup()]);
    ```

## Saindo da main thread (`env.wasm.proxy`)

O backend WASM roda na thread que chamou ele — e essa é a main thread. Então
criar a sessão e cada `predict()` **travam a interface** enquanto rodam. Medido
num desktop de 32 núcleos: um `warmup()` de detector + classificador congelou a
página por **805 ms**. Num celular de 4 núcleos / 2 GB, uma análise leva 50 a
103 s.

O ONNX Runtime tem uma flag pra isso. Com `env.wasm.proxy` ligada, ele cria um
Web Worker próprio (`onnxruntime-web-proxy-worker`) e manda create, run e release
por `postMessage`. O mesmo warmup medido acima: pior frame de **18 ms**, zero
frames acima de 50 ms.

Ligue **uma vez, antes da primeira sessão**:

```tsx
import { env } from "onnxruntime-web";
import { Detector } from "tempest-react-sdk/vision";

env.wasm.proxy = true; // antes do primeiro Detector.create

const det = await Detector.create("/models/yolov8n.onnx", { labels: "coco" });
await det.warmup(); // agora aquece sem travar a tela de carregamento
const result = (await det.predict(frame))[0];
```

!!! warning "Antes da primeira sessão, não depois"
    O ORT lê `env.wasm` quando inicializa o runtime WASM, e isso acontece dentro
    do primeiro `InferenceSession.create`. Setar a flag depois disso é ignorado em
    silêncio — a inferência volta pra main thread sem nada avisar. Num app com
    sessões lazy, o lugar seguro é o começo da função que constrói a sessão, não
    um hook de boot que um refactor pode reordenar.

!!! note "O worker não deixa nada mais barato"
    Ele muda *onde* o custo é pago, não o quanto. O heap WASM e a reserva de
    memória compartilhada do build pthread apenas mudam de thread: um aparelho que
    não consegue criar a sessão na main thread também não consegue no worker.

!!! info "Precisa do `onnxruntime-web` >= 1.17 e desta versão do SDK"
    O proxy posta os tensores de entrada com os `ArrayBuffer`s na *transfer list*,
    o que **destaca** o buffer deste lado. As pipelines de pré-processamento
    reusam um `Float32Array` entre chamadas, e até a 0.42.0 reentregavam o buffer
    destacado — o ORT rejeitava com
    `Tensor's size(1228800) does not match data length(0).` a cada duas
    inferências. Corrigido nesta versão (vision vendorada `0.7.1`).

## Quanto tempo levou

Todo envelope traz um `speed` com o tempo de cada etapa do `predict()`, em
milissegundos:

```typescript
const results = await detector.predict(blob);
console.log(results[0].speed);
// { load: 84.2, preprocess: 11.7, inference: 118.9, postprocess: 6.4 }
```

`preprocess` / `inference` / `postprocess` são as mesmas três chaves do
Ultralytics, medidas nas mesmas fronteiras. `load` é o fetch/decode que o
`predict()` faz por dentro quando você passa uma URL ou `Blob` — com cache
frio costuma ser a maior fatia da chamada. Criar a tarefa
(`Detector.create`) **não** entra: é custo de inicialização, pago uma vez.

Para medir o pipeline inteiro do app — incluindo o que acontece *entre* dois
`predict()` — use o [módulo `perf`](perf.md), e dobre o `speed` para dentro do
relatório com `profiler.mark("forward-pass", results[0].speed.inference)`.
O `SpeedTimer` também é exportado daqui, para quem quiser as mesmas fronteiras
do SDK em código próprio.

!!! tip "O `preprocess` de hoje é ~2x mais rápido que o de antes"
    As quatro tarefas pré-processam por uma pipeline fundida: um único
    `drawImage` redimensiona (e, quando há padding, posiciona) o conteúdo, e um
    laço só lê o RGBA resultante escrevendo float32 planar num buffer reusado
    entre frames. Medido no Chromium, letterbox pra 640×640: 19,8 → 10,7 ms
    (1920×1080), 13,8 → 7,8 ms (1280×720), 6,8 → 3,1 ms (640×480) — com saída
    **bit-idêntica** à do caminho antigo.

    São duas pipelines porque as tarefas querem coisas diferentes:
    `LetterboxPipeline` preserva a proporção e preenche o resto (detecção e
    segmentação precisam desfazer essa geometria depois), e `ResizePipeline`
    estica direto até a entrada do modelo já normalizando com `mean`/`std` — o
    que o `Classifier` faz, já que ele não mapeia nada de volta pra imagem
    original. Os primitivos (`letterbox`, `resize`, `normalize`, `toCHW`, …)
    continuam exportados; quem quiser o caminho fundido em código próprio usa a
    pipeline (ou `letterboxToTensorData`/`resizeToTensorData`, as formas de uma
    chamada só).

!!! warning "Classificar era o caminho caro até a 0.41.0"
    O `Classifier` era a única tarefa ainda na rota composta
    (`resize` → `normalize` → `toCHW`): três varreduras e três alocações por
    `predict()`, ~1,4 MB de lixo novo a cada imagem 224×224. Num aparelho perto
    do teto de memória do ORT, isso era gerado no pior momento possível. Se você
    fixou uma versão anterior por causa disso, esta é a que resolve.

## Referência: o que mais o subpath exporta

As tarefas cobrem o caminho comum. Abaixo está o resto da superfície — o que
você usa quando monta um pipeline próprio, roda um modelo com uma cabeça que o
SDK não conhece, ou precisa tratar uma falha específica.

| Grupo             | Exports                                                                                             |
| ----------------- | --------------------------------------------------------------------------------------------------- |
| Sessão            | `OrtSession` (carrega o `.onnx`, expõe `metadata`/`inputName`), `resolveProviders`, `DEFAULT_PROVIDERS`, `VisionTask` (base das tarefas), `VERSION` |
| Entrada           | `loadImage` (qualquer `ImageInput` → `RGBImage`), `normalize`, `toTensor`, `toFloat32`/`toFloat32Tensor`, `zeroTensorData`, `fromCv2`/`toCv2` (BGR ↔ RGB) |
| Preprocess fundido | `LetterboxPipeline` + `letterboxToTensorData` (detecção/segmentação), `ResizePipeline` + `resizeToTensorData` (classificação), `writePlanarFloat32` (o laço planar compartilhado) |
| Decodificação     | `decodeYolo` (cabeça anchor-free, v8→v12), `decodeYoloAnchors` (cabeça com âncoras), `decodeYoloSeg`, `nms`, `batchedNms` |
| Rótulos           | `resolveLabels`, `defaultLabels`, `parseNames`, `modelNames`, `readModelMetadata`, `COCO_CLASSES`      |
| Views em massa    | `Boxes`, `Masks`, `Probs` — as coleções "numpy-style" por trás de `result.boxes`/`.masks`/`.probs`    |
| Erros             | `OrtVisionError` (base), `ModelLoadError`, `ImageLoadError`, `InferenceError`, `LabelMapError`, `ProviderNotAvailableError`, `NoDetectionsError`, `FusionError` |
| Contrato de fusão | `readFusionSpec`, `FusionSpec`, `CropSource`, `INPUT_IMAGE`/`INPUT_SOURCE`/`INPUT_SCALE`/`INPUT_PAD`, `OUTPUT_BOXES`/`OUTPUT_SCORES`/`OUTPUT_CLASSES`/`OUTPUT_PROBS`/`OUTPUT_NUM_DETECTIONS`, `METADATA_PREFIX`, `FUSION_KIND_DETECT_CLASSIFY` |
| Auxiliares        | `requireDetections` (a checagem por trás do `raiseOnEmpty`), `SpeedTimer`, `softmax`, `topK`          |

!!! tip "Cabeça com âncoras: `decodeYoloAnchors`"
    `decodeYolo` cobre as cabeças anchor-free (o padrão de v8 em diante).
    Um modelo mais antigo — YOLOv5/v7, ou um export customizado que mantém as
    âncoras — decodifica com `decodeYoloAnchors`. Passar a saída errada pra
    função errada não dá erro: dá caixa em lugar nenhum.

!!! info "Todos os erros descendem de `OrtVisionError`"
    Um `catch (err) { if (err instanceof OrtVisionError) … }` pega tudo que o
    subpath lança, e as subclasses separam o que dá pra tratar: `ModelLoadError`
    (URL errada, 404, arquivo corrompido) pede outra URL,
    `ProviderNotAvailableError` pede outro provider, `LabelMapError` é
    configuração sua, e `InferenceError` é o modelo recusando a entrada.

## Paridade com o `ort-vision-sdk` em Python

Essa API espelha de propósito a do pacote Python
[`ort-vision-sdk`](https://pypi.org/project/ort-vision-sdk/) do mesmo autor:
`Classifier` / `Detector` / `Segmenter`, `predict()` devolvendo uma lista de 1
resultado por imagem, e os mesmos nomes idiomáticos do Ultralytics
(`cls`/`conf`/`name`/`box`, `boxes.xyxy`, `probs.top5`). Quem porta código de
visão entre o backend Python e o frontend TypeScript reaproveita o modelo mental
quase sem atrito.

A paridade vai além da forma da API: o `raiseOnEmpty` existe dos dois lados com
a **mesma mensagem** (inclusive o threshold formatado igual — `conf_threshold=1`
não vira `1.0` de um lado só), e um pipeline fundido pelo `compose` do Python é
lido aqui a partir do metadata que ele mesmo gravou. Fundir uma vez, rodar nos
dois runtimes, com o mesmo resultado.

## Recap

- Importe de **`tempest-react-sdk/vision`** — subpath dedicado. O código é
  vendorizado do `@mauriciobenjamin700/ort-vision-sdk-web` (MIT), então **já vem
  no SDK**, sem pacote extra.
- O **`onnxruntime-web` é peer dep opcional**: rode `npm i onnxruntime-web` e
  **sirva os `.wasm` da mesma versão**. Quem não importa do `/vision` não paga o
  peso. Providers: **WebGPU → WASM** (`DEFAULT_PROVIDERS`).
- Quatro tarefas, mesma forma: `await Tarefa.create(modelo, opções)` →
  `(await tarefa.predict(imagem))[0]`. O `predict` sempre devolve um array de
  **1 elemento** (um envelope por imagem).
- **`DetectClassify`** roda detector + classificador num `.onnx` **fundido**
  (construído pelo `compose` do SDK Python): um download, uma sessão, e a
  sub-categoria de cada objeto em `d.classification`. Modelo sem metadata de
  fusão → `FusionError`.
- **`warmup()`** paga a compilação de shader / arenas antes do usuário —
  chame na tela de carregamento. **`raiseOnEmpty`** transforma resultado vazio
  em `NoDetectionsError` quando zero linhas deve parar o fluxo (default:
  envelope vazio).
- Itere o envelope com `for...of` pra resultados por-instância:
  `d.name`/`d.className`, `d.confidence`/`d.conf`, `d.box`/`d.bbox` (com
  `.xyxy`/`.xywh`/`.asXywh()`/`.xyxyn()`). Ou use a view em massa `result.boxes`
  (`.xyxy`/`.cls`/`.conf`) e `result.names`.
- Entradas aceitas: URL `string`, `Blob`, `File`, `HTMLImageElement`, canvas
  (`HTMLCanvasElement`/`OffscreenCanvas`), `ImageBitmap`, `ImageData` e
  `RGBImage`.
- Rótulos via `resolveLabels` / `COCO_CLASSES`: preset `"coco"`, array, dict
  esparso ou auto-gerado. `labels` é **opcional** nas três tarefas — omitido,
  valem os `names` do próprio `.onnx`, e só um modelo sem eles cai no preset
  `"coco"` (det/seg) ou em `class_<id>` (classificação).
- A API espelha o `ort-vision-sdk` em Python — mesmo modelo mental nos dois
  lados.
- Pra **capturar** o frame: `useCameraStream` (câmera traseira por padrão,
  `error.kind` estável, `retry()`), `computeImageLuminance` +
  `isLuminanceAcceptable` + `LowLuminanceError` pra checar o brilho (threshold
  obrigatório) e `useLiveLuminance` pro feedback ao vivo. Pra pré-visualizar o
  `Blob` capturado, `useObjectUrl` (barrel principal).

---

# vite-config.md

# Vite Config

Todo app frontend Tempest começa com o mesmo `vite.config.ts`: o plugin React, o
alias `@` → `src` e os defaults do dev server. Copiar esse bloco de app em app é
chato, fácil de errar e diverge com o tempo. O helper `createViteConfig` mata esse
boilerplate: você chama uma função, recebe um objeto de config pronto e atribui
direto ao `export default`.

```ts
// vite.config.ts
import { createViteConfig } from "tempest-react-sdk/vite";

export default createViteConfig({
  proxy: { "/api": "http://127.0.0.1:8000" },
});
```

Pronto. Plugin React ligado, `@` resolvendo pra `src`, dev server escutando em
`127.0.0.1:5173` e as chamadas pra `/api` indo pro seu backend local. Tudo isso
em quatro linhas.

## O subpath `tempest-react-sdk/vite`

Repare no import: ele vem de `tempest-react-sdk/vite`, **não** do barrel principal
`tempest-react-sdk`.

```ts
import { createViteConfig } from "tempest-react-sdk/vite";
```

!!! info "Por que um subpath separado?"
    O barrel principal roda no **navegador** (componentes React, hooks). Já o
    `createViteConfig` roda no **Node**, dentro do `vite.config.ts`, durante o
    build. São ambientes diferentes, então o helper mora num subpath dedicado pra
    nunca arrastar código de config pro seu bundle de produção.

### Peer deps

`vite` e `@vitejs/plugin-react` são **peer dependencies opcionais** do SDK. Como
todo app Vite já tem os dois no `devDependencies`, não há nada extra pra instalar
— o helper apenas os reutiliza.

## O exemplo mínimo

Sem nenhuma opção, você ainda ganha os defaults completos:

```ts
// vite.config.ts
import { createViteConfig } from "tempest-react-sdk/vite";

export default createViteConfig();
```

Isso te dá:

| Default       | Valor         |
| ------------- | ------------- |
| Plugin React  | ligado        |
| Alias `@`     | → `src`       |
| `server.port` | `5173`        |
| `server.host` | `"127.0.0.1"` |
| `server.open` | `false`       |

## O alias `@` (e o tsconfig que precisa acompanhar)

O default mais útil é o alias `@`: ele aponta pro seu diretório de fontes, então
`@/components/Button` resolve pra `<raiz>/src/components/Button`. Chega de
`../../../components/Button`.

```ts
// src/main.tsx
import { Button } from "@/components/Button";
import { formatBRL } from "@/utils/money";
```

O caminho de origem é resolvido contra `process.cwd()` (a raiz do projeto, de onde
o Vite roda). Quer aliasar outra pasta? Use `srcDir`:

```ts
// vite.config.ts
import { createViteConfig } from "tempest-react-sdk/vite";

export default createViteConfig({
  srcDir: "app", // agora @ → <raiz>/app
});
```

!!! warning "O alias `@` também precisa estar no `tsconfig.json`"
    O Vite e o TypeScript resolvem caminhos de forma **independente**. O
    `createViteConfig` ensina o Vite a resolver `@`, mas o type-checker não sabe
    de nada até você declarar o mesmo alias em `compilerOptions.paths`. Sem isso, o
    `tsc` vai reclamar de "Cannot find module '@/...'" mesmo com o app rodando.

    ```jsonc
    // tsconfig.json — mantenha o alias @ em sincronia com o type-checker
    {
      "compilerOptions": {
        "paths": { "@/*": ["./src/*"] }
      }
    }
    ```

    Se você mudar o `srcDir`, mude o `paths` junto (ex.: `"@/*": ["./app/*"]`).

## Proxy: atalho de string vs. objeto

A opção `proxy` aceita dois formatos. Valores **string** são o atalho mais comum:
você passa só a URL de destino e o helper expande automaticamente pra
`{ target, changeOrigin: true }`.

```ts
// vite.config.ts
import { createViteConfig } from "tempest-react-sdk/vite";

export default createViteConfig({
  proxy: { "/api": "http://127.0.0.1:8000" },
});
// vira { "/api": { target: "http://127.0.0.1:8000", changeOrigin: true } }
```

Precisa de controle fino (rewrite de path, websocket, headers)? Passe um **objeto**
— ele segue cru como `ProxyOptions` do Vite, sem nenhuma mágica:

```ts
// vite.config.ts
import { createViteConfig } from "tempest-react-sdk/vite";

export default createViteConfig({
  proxy: {
    "/api": "http://127.0.0.1:8000", // atalho string
    "/ws": {
      target: "ws://127.0.0.1:8000", // objeto cru
      ws: true,
      changeOrigin: true,
    },
  },
});
```

!!! tip "Misture os dois à vontade"
    Cada chave do `proxy` é tratada de forma independente: strings são expandidas,
    objetos passam direto. Use o atalho onde der e o objeto onde precisar.

## O escape hatch: `overrides`

Os defaults cobrem a maioria dos apps, mas nenhum helper antecipa tudo. A opção
`overrides` recebe um `UserConfig` arbitrário do Vite e faz **deep-merge por
último**, depois de tudo o que o helper montou.

```ts
// vite.config.ts
import { createViteConfig } from "tempest-react-sdk/vite";

export default createViteConfig({
  srcDir: "app",
  port: 3000,
  alias: { "~": "/lib" },
  overrides: { build: { target: "es2020" } },
});
```

!!! note "Merge, não substituição"
    Em `overrides`, as chaves `plugins`, `resolve` e `server` são **mescladas** com
    o que o helper já configurou — não sobrescritas. Então um `overrides.server`
    com uma chave nova convive com o `port`/`host` que você passou nas opções de
    primeiro nível, e `overrides.plugins` são acrescentados aos seus. O resto do
    `UserConfig` (`build`, `define`, etc.) entra normalmente.

## Referência das opções

Todas as opções são opcionais.

| Opção       | Tipo                               | Default       | O que faz                                                                          |
| ----------- | ---------------------------------- | ------------- | ---------------------------------------------------------------------------------- |
| `srcDir`    | `string`                           | `"src"`       | Diretório aliasado pra `@`, resolvido contra `process.cwd()`.                      |
| `port`      | `number`                           | `5173`        | Porta do dev server.                                                               |
| `host`      | `string \| boolean`                | `"127.0.0.1"` | Host do dev server.                                                                |
| `open`      | `boolean`                          | `false`       | Abre o navegador ao iniciar o dev.                                                 |
| `proxy`     | `Record<string, string \| object>` | —             | Proxy do dev. Strings viram `{ target, changeOrigin: true }`; objetos passam crus. |
| `alias`     | `Record<string, string>`           | —             | Aliases extras mesclados por cima do `@` default.                                  |
| `plugins`   | `unknown[]`                        | —             | Plugins Vite acrescentados depois do plugin React.                                 |
| `overrides` | `Record<string, unknown>`          | —             | `UserConfig` arbitrário com deep-merge por último.                                 |

## Recap

- Importe `createViteConfig` de **`tempest-react-sdk/vite`** — subpath dedicado de
  Node, separado do barrel do navegador.
- Chame e atribua: `export default createViteConfig({ ... })`. Sem opções, você já
  ganha o plugin React, o alias `@` → `src` e o dev server em `127.0.0.1:5173`.
- Declare **também** o alias `@` no `tsconfig.json` (`"paths": { "@/*": ["./src/*"] }`)
  — Vite e TS resolvem caminhos de forma independente.
- No `proxy`, strings são atalho (`{ target, changeOrigin: true }`); objetos passam
  crus como `ProxyOptions`.
- `overrides` é o escape hatch: deep-merge por último, mesclando `plugins`/`resolve`/`server`
  em vez de substituí-los.

---

# websocket.md

# WebSocket

`createWebSocket` + `useWebSocket` espelham a API de SSE, mas adicionam o canal de **envio**. Use quando o cliente precisar mandar mensagens, não só receber.

!!! info "Quando WebSocket em vez de SSE?"
    SSE só recebe. Assim que o cliente precisa **enviar** (chat, cursores compartilhados, comandos em tempo real), você precisa de um canal bidirecional — é aí que entra o WebSocket. Se for só push servidor → cliente, [SSE](./sse.md) é mais simples.

## Quando usar

- Chat / colaboração real-time.
- Bidirecional, latência baixa.
- Frames binários (também suportados via `send(ArrayBuffer)`).

## API imperativa — `createWebSocket`

```ts
import { createWebSocket } from "tempest-react-sdk";

interface ChatEvent {
  user: string;
  text: string;
}

const socket = createWebSocket<ChatEvent>(`${import.meta.env.VITE_WS_URL}/chat`, {
  pingInterval: 30_000, // mantém o socket vivo
  maxRetries: 10,
  onOpen: () => console.log("ws aberto"),
  onMessage: ({ data }) => render(data),
  onClose: (event) => console.log("fechou", event.code),
  onStatusChange: (status) => console.log("WS", status),
});

// Enviar — retorna false se o socket não estiver aberto:
const sent = socket.send(JSON.stringify({ user: "ana", text: "oi" }));

// Frame binário:
socket.send(new Uint8Array([1, 2, 3]).buffer);

// Encerrar (não tenta reconectar):
socket.close();

// Forçar reconexão imediata (zera o contador):
socket.reconnect();
```

`onMessage` recebe `{ data, raw }` — `data` já vem JSON-parsed (fallback pra string), `raw` é o `MessageEvent` original.

### Reconexão, ping e fechamento limpo

```text
Backoff: 1s → 2s → 4s → ... (limitado em 30s), até maxRetries (default 10)
```

- Reconnect exponencial igual ao SSE (default `maxRetries: 10`).
- `pingInterval` (ms) envia `pingPayload` periodicamente — default `JSON.stringify({ type: "ping" })`. Passe `0` (default) pra desativar.
- `respondToPing` (default `true`) responde `pongPayload` a todo frame `{"type":"ping"}` que **chega**. É esse o heartbeat que o `tempest-fastapi-sdk` espera: sem o `pong` ele fecha o socket com o código `4408` ao estourar `WS_HEARTBEAT_TIMEOUT_SECONDS`.
- `queueWhileClosed` (default `false`) guarda o que você tentar enviar enquanto o socket está caído e drena na próxima abertura, mais antigo primeiro, com teto em `maxQueuedMessages` (default 100).
- **Reconnect só dispara em `close.wasClean === false`.** Fechamentos limpos (`socket.close()` ou um close normal do servidor) **não** tentam reabrir.

!!! warning "`send()` é no-op quando o socket não está aberto"
    Se você chamar `send()` antes do status virar `"open"` (ou após um `close`), nada é enviado e o retorno é `false`. Sempre confira `status === "open"` (ou o boolean de retorno) antes de assumir que a mensagem saiu.

    Ligue `queueWhileClosed: true` quando a ação **não pode** sumir: aí o `send()` bufferiza durante o backoff e devolve `true`, e a fila é despejada no `open` seguinte. A fila morre no `close()` — nada sobrevive a um fechamento explícito.

!!! danger "Contra o servidor Tempest, não ligue `pingInterval`"
    O `tempest-fastapi-sdk` **manda** o ping e quer o `pong` de volta. Um `{"type":"ping"}` vindo do cliente é frame desconhecido pra ele — um handler estrito recusa. Deixe `pingInterval: 0` (default) e o `respondToPing` cuida do heartbeat.

## Hook — `useWebSocket`

```tsx
import { useState } from "react";
import { useWebSocket } from "tempest-react-sdk";

interface ChatEvent {
  user: string;
  text: string;
}

export function Chat({ enabled }: { enabled: boolean }) {
  const [draft, setDraft] = useState("");
  const [log, setLog] = useState<ChatEvent[]>([]);

  const ws = useWebSocket<ChatEvent>(`${import.meta.env.VITE_WS_URL}/chat`, {
    enabled,
    pingInterval: 30_000,
    onMessage: ({ data }) => setLog((prev) => [...prev, data]),
  });

  function sendMessage() {
    const ok = ws.send(JSON.stringify({ user: "me", text: draft }));
    if (ok) setDraft("");
  }

  return (
    <div>
      <span>Status: {ws.status}</span>
      <ul>
        {log.map((m, i) => (
          <li key={i}>
            <strong>{m.user}:</strong> {m.text}
          </li>
        ))}
      </ul>
      <input value={draft} onChange={(e) => setDraft(e.target.value)} />
      <button disabled={ws.status !== "open"} onClick={sendMessage}>
        Enviar
      </button>
      {ws.status === "error" && <button onClick={ws.reconnect}>Reconectar</button>}
    </div>
  );
}
```

- O hook devolve `{ status, lastMessage, send, reconnect }`.
- `enabled: false` não abre o socket; mudar a URL reabre. **Todos** os callbacks (`onOpen`, `onMessage`, `onClose`, `onError`) passam por ref: arrow function inline é seguro, sempre roda a closure atual e nunca reabre o socket.
- Opções que moldam a conexão (`protocols`, `maxRetries`, `initialBackoff`, `maxBackoff`, `pingInterval`, `queueWhileClosed`) fazem parte do handshake — mudar uma **reabre** o socket com o valor novo, em vez de ser ignorada em silêncio.

!!! warning "`lastMessage` é foto, não fila"
    Cada frame vira um `setState`, então dois que cheguem no mesmo tick colapsam num render só e você enxerga apenas o último. Uma única ação no servidor costuma emitir vários frames em sequência. Para **stream** use `onMessage`, que dispara uma vez por frame; `lastMessage` serve pra renderizar estado atual.
- `send` é estável (`useCallback`) — pode ir em deps sem reabrir nada.
- Cleanup automático no unmount (fechamento limpo, não tenta reconectar).

## Status

`"idle" | "connecting" | "open" | "closing" | "closed" | "error"` — `error` indica que o socket esgotou `maxRetries` após fechamentos não-limpos.

## Recap

- `createWebSocket(url, options)` abre um WebSocket bidirecional; o controller expõe `send`, `close`, `reconnect` e `status`.
- `send()` retorna `false` (no-op) quando o socket não está aberto — sempre cheque antes.
- Reconnect exponencial só dispara em fechamento **não-limpo**; closes limpos não reabrem.
- `pingInterval` + `pingPayload` mantêm a conexão viva.
- `useWebSocket` amarra tudo ao componente e expõe `status`/`lastMessage`/`send`/`reconnect`.

## Veja também

- [SSE](./sse.md) — quando só recebe (mais simples)
- [HTTP](./http.md)