# tempest-react-sdk

> Blocos de construção React/TypeScript compartilhados pelos frontends da Tempest: componentes de UI, hooks, cliente HTTP, store de auth, formulários (zod), transportes em tempo real (SSE/WebSocket/Web Push), tema, i18n, telemetria, feature flags, storage offline e roteamento.

## Documentação

- [Access Control (RBAC)](https://mauriciobenjamin700.github.io/tempest-react-sdk/access-control/): Checagens de permissão e papel para esconder ou bloquear ações que o usuário não pode executar.
- [AppProviders](https://mauriciobenjamin700.github.io/tempest-react-sdk/app-providers/): Todo app React precisa de um punhado de _providers_ no topo da árvore: cache de
- [Arquitetura](https://mauriciobenjamin700.github.io/tempest-react-sdk/architecture/): O tempest-react-sdk é um pacote único com camadas independentes.
- [Áudio](https://mauriciobenjamin700.github.io/tempest-react-sdk/audio/): Áudio no navegador, nas duas direções.
- [Auth](https://mauriciobenjamin700.github.io/tempest-react-sdk/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.
- [Pagamentos & fiscal BR](https://mauriciobenjamin700.github.io/tempest-react-sdk/br-pagamentos/): Os quatro trilhos que todo produto brasileiro acaba precisando: Pix, boleto, chave de acesso da NFe e feriados / dias úteis.
- [Mapa do Brasil & localidades](https://mauriciobenjamin700.github.io/tempest-react-sdk/br/): Mapa nacional clicável das 27 unidades federativas + dataset de estados e cidades — sem nenhuma API paga ou externa.
- [Charts (recharts)](https://mauriciobenjamin700.github.io/tempest-react-sdk/charts/): Gráficos transformam números em forma: uma tendência que sobe, uma fatia que
- [CLI `tempest`](https://mauriciobenjamin700.github.io/tempest-react-sdk/cli/): Além da CLI de scaffolding create-tempest-app, o pacote
- [Cookbook — Receitas](https://mauriciobenjamin700.github.io/tempest-react-sdk/cookbook/): Esta página é um livro de receitas: cada seção responde a um "eu quero fazer X"
- [Data Provider (CRUD)](https://mauriciobenjamin700.github.io/tempest-react-sdk/data-provider/): Camada de CRUD no estilo Refine fiada nas convenções de paginação e endpoints do tempest-fastapi-sdk.
- [Anti-padrões](https://mauriciobenjamin700.github.io/tempest-react-sdk/design/anti-patterns/): As páginas anteriores dizem o que fazer. Esta diz o que você vai encontrar —
- [Camadas de um app frontend](https://mauriciobenjamin700.github.io/tempest-react-sdk/design/architecture/): Backend tem um desenho de camadas que todo mundo reconhece: router → controller →
- [Checklist de revisão](https://mauriciobenjamin700.github.io/tempest-react-sdk/design/checklist/): Toda a seção em uma página. Use antes de abrir o PR e durante a revisão do PR de
- [Pensando em componentes](https://mauriciobenjamin700.github.io/tempest-react-sdk/design/components/): Componente é a unidade de reuso do React, e é onde a maior parte dos apps
- [Fluxo de dados](https://mauriciobenjamin700.github.io/tempest-react-sdk/design/data-flow/): Toda tela é a mesma pergunta: **como o dado do servidor chega no pixel, e como a
- [Estrutura de pastas](https://mauriciobenjamin700.github.io/tempest-react-sdk/design/folders/): As camadas são um conceito. Pasta é onde o conceito encosta no
- [Design de Software Frontend](https://mauriciobenjamin700.github.io/tempest-react-sdk/design/index/): O SDK te dá as peças. Esta seção ensina a arrumar as peças.
- [Limites objetivos](https://mauriciobenjamin700.github.io/tempest-react-sdk/design/limits/): "Mantenha os componentes pequenos" é um conselho que ninguém consegue aplicar,
- [Onde mora cada estado](https://mauriciobenjamin700.github.io/tempest-react-sdk/design/state/): Quase todo bug difícil de app frontend é a mesma coisa: **duas fontes de verdade
- [Estratégia de testes](https://mauriciobenjamin700.github.io/tempest-react-sdk/design/testing/): Teste de frontend tem uma armadilha própria: é fácil escrever muitos testes que
- [Tipagem forte](https://mauriciobenjamin700.github.io/tempest-react-sdk/design/typing/): TypeScript não é "JavaScript com autocomplete".
- [Captura de dispositivo](https://mauriciobenjamin700.github.io/tempest-react-sdk/device-capture/): Quatro APIs do navegador que não custam dependência nenhuma: a câmera lendo códigos
- [Rich Text Editor (`tempest-react-sdk/editor`)](https://mauriciobenjamin700.github.io/tempest-react-sdk/editor/): Editor WYSIWYG controlado, construído sobre tiptap.
- [Error Boundary](https://mauriciobenjamin700.github.io/tempest-react-sdk/error-boundary/): ErrorBoundary captura erros lançados durante o render de qualquer descendente e mostra um fallback no lugar de uma tela branca.
- [Feature Flags](https://mauriciobenjamin700.github.io/tempest-react-sdk/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.
- [Forms BR — máscaras, validadores, ViaCEP](https://mauriciobenjamin700.github.io/tempest-react-sdk/forms-br/): Tudo que apps brasileiros usam diariamente: validar CPF/CNPJ de verdade, mascarar
- [Forms](https://mauriciobenjamin700.github.io/tempest-react-sdk/forms/): Forms quase sempre travam em dois problemas que não têm nada a ver um com o outro:
- [Geolocalização](https://mauriciobenjamin700.github.io/tempest-react-sdk/geo/): 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.
- [Hooks utilitários](https://mauriciobenjamin700.github.io/tempest-react-sdk/hooks/): Toda app React reescreve os mesmos wrappers: "debounce esse input", "fecha o menu
- [HTTP](https://mauriciobenjamin700.github.io/tempest-react-sdk/http/): Camada de fetch tipada com tratamento de 401 + refresh, parse JSON automático e upload com progresso.
- [i18n](https://mauriciobenjamin700.github.io/tempest-react-sdk/i18n/): i18n minimalista (≈ 1.5KB gzip) embutido no SDK.
- [Ícones por slug](https://mauriciobenjamin700.github.io/tempest-react-sdk/icons/): Todo componente do SDK que aceita ícone aceita um ReactNode:
- [Imaging (processamento de imagem no navegador)](https://mauriciobenjamin700.github.io/tempest-react-sdk/imaging/): Foto tirada no celular, tratada no aparelho: redimensiona, corta, gira,
- [tempest-react-sdk](https://mauriciobenjamin700.github.io/tempest-react-sdk/): Blocos de construção React/TypeScript compartilhados pelos frontends da Tempest:
- [Integração full-stack Tempest (React ⇄ FastAPI)](https://mauriciobenjamin700.github.io/tempest-react-sdk/integration-fastapi/): Você tem um backend feito com o tempest-fastapi-sdk e um frontend feito com este SDK.
- [Logger](https://mauriciobenjamin700.github.io/tempest-react-sdk/logger/): createLogger é um logger nivelado com sinks plugáveis.
- [OAuth (Google)](https://mauriciobenjamin700.github.io/tempest-react-sdk/oauth/): 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).
- [Offline Sync com `tempest-fastapi-sdk`](https://mauriciobenjamin700.github.io/tempest-react-sdk/offline-sync/): 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.
- [Offline (IndexedDB)](https://mauriciobenjamin700.github.io/tempest-react-sdk/offline/): createOfflineStore empacota o Dexie com scoping opcional por owner.
- [Gerar serviços do OpenAPI (`tempest gen api`)](https://mauriciobenjamin700.github.io/tempest-react-sdk/openapi/): Se o seu backend é FastAPI (ou qualquer API que exponha um OpenAPI 3.x), o
- [Passkeys (WebAuthn)](https://mauriciobenjamin700.github.io/tempest-react-sdk/passkeys/): Login sem senha, com a biometria que o usuário já usa pra desbloquear o aparelho.
- [Custo de inferência on-device](https://mauriciobenjamin700.github.io/tempest-react-sdk/perf/): Quando a inferência roda no dispositivo do usuário, você perde o gráfico do
- [Web Push + Service Worker](https://mauriciobenjamin700.github.io/tempest-react-sdk/push/): 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).
- [PWA & Offline-First](https://mauriciobenjamin700.github.io/tempest-react-sdk/pwa/): 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.
- [Query (TanStack Query)](https://mauriciobenjamin700.github.io/tempest-react-sdk/query/): Wrappers finos pra padronizar tempos de cache, chaves de query e o QueryClient.
- [Upload resumível (tus)](https://mauriciobenjamin700.github.io/tempest-react-sdk/resumable-upload/): 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.
- [Routing](https://mauriciobenjamin700.github.io/tempest-react-sdk/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.
- [Scaffold — `create-tempest-app`](https://mauriciobenjamin700.github.io/tempest-react-sdk/scaffold/): create-tempest-app é a CLI oficial de scaffolding da Tempest.
- [Web Share](https://mauriciobenjamin700.github.io/tempest-react-sdk/share/): share() é um wrapper sobre a Web Share API (navigator.share) que devolve um resultado uniforme em vez de lançar exceções.
- [Server-Sent Events](https://mauriciobenjamin700.github.io/tempest-react-sdk/sse/): Wrapper sobre EventSource com reconnect exponencial, heartbeat opt-in e parsing JSON.
- [State (Zustand)](https://mauriciobenjamin700.github.io/tempest-react-sdk/state/): 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.
- [Estilos & Design Tokens](https://mauriciobenjamin700.github.io/tempest-react-sdk/styles/): O SDK expõe um conjunto de CSS Custom Properties (--tempest-*) que controlam toda a aparência dos componentes.
- [Tabular (scikit-learn no navegador)](https://mauriciobenjamin700.github.io/tempest-react-sdk/tabular/): Modelo de scikit-learn respondendo no navegador, sem servidor de
- [Telemetry](https://mauriciobenjamin700.github.io/tempest-react-sdk/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.
- [Testing helpers (`tempest-react-sdk/testing`)](https://mauriciobenjamin700.github.io/tempest-react-sdk/testing/): Subpath bundle separado, opt-in via tempest-react-sdk/testing.
- [Tema (dark / light)](https://mauriciobenjamin700.github.io/tempest-react-sdk/theme/): ThemeProvider decide o tema efetivo e escreve data-tempest-theme="dark" (ou "light") em <html>.
- [Tutorial — Fluxo de autenticação](https://mauriciobenjamin700.github.io/tempest-react-sdk/tutorial/auth-flow/): Você já tem todas as peças soltas: a store de auth (Estado), o guard
- [Tutorial — Buscando dados](https://mauriciobenjamin700.github.io/tempest-react-sdk/tutorial/data-fetching/): Nossa lista de tarefas precisa vir de algum lugar: um backend.
- [Tutorial — Formulários](https://mauriciobenjamin700.github.io/tempest-react-sdk/tutorial/forms/): Antes do usuário entrar no app, ele precisa se cadastrar — e o cadastro precisa
- [Tutorial — Comece aqui](https://mauriciobenjamin700.github.io/tempest-react-sdk/tutorial/index/): Bem-vindo! Este é o Tutorial — Guia do Usuário do tempest-react-sdk.
- [Tutorial — Roteamento](https://mauriciobenjamin700.github.io/tempest-react-sdk/tutorial/routing/): Nosso app vai ter mais de uma tela: a lista de tarefas, uma página de login e um
- [Tutorial — Estado](https://mauriciobenjamin700.github.io/tempest-react-sdk/tutorial/state/): Na página anterior, o guard do dashboard leu useAuth.getState().isAuthenticated
- [Utilitários](https://mauriciobenjamin700.github.io/tempest-react-sdk/utilities/): 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.
- [Vision (ONNX Runtime Web)](https://mauriciobenjamin700.github.io/tempest-react-sdk/vision/): Visão computacional no dispositivo — direto no navegador, sem servidor de
- [Vite Config](https://mauriciobenjamin700.github.io/tempest-react-sdk/vite-config/): Todo app frontend Tempest começa com o mesmo vite.config.ts: o plugin React, o
- [WebSocket](https://mauriciobenjamin700.github.io/tempest-react-sdk/websocket/): createWebSocket + useWebSocket espelham a API de SSE, mas adicionam o canal de envio.

## Componentes

- [Componentes UI](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/): O catálogo foi dividido por categoria para facilitar navegação.
- [Ação](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/actions/): Componentes de ação são o ponto onde o usuário dispara algo: clicar, escolher numa lista, confirmar.
- [Avançados: conversa](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/advanced-chat/): Chat para thread entre pessoas e AIChat para conversa com um modelo.
- [Avançados: dados](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/advanced-data/): Tabela stateful, assistente em passos, markdown, mural, tour guiado, transferência entre listas, barra de filtros e kanban.
- [Avançados: essenciais](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/advanced-essentials/): Toggles, label, regiões expansíveis, menus disparados por interação e a paleta de comandos.
- [Avançados: layout & UX](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/advanced-layout/): Rolagem estilizada, painéis redimensionáveis, calendário e agenda.
- [Avançados: navegação & conteúdo](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/advanced-navigation/): Navegação com dropdowns, barra de menus e carrossel.
- [Overlays & avançados](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/advanced/): Componentes em paridade com a shadcn/ui, agrupados por para o que servem.
- [Dados](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/data/): Componentes de dados apresentam coleções — várias entidades do mesmo tipo — de forma legível e navegável.
- [Status & feedback](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/feedback/): Sinalizar estado, sucesso, erro, atividade.
- [Identidade & micro](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/identity/): 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).
- [Entrada de dados](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/inputs/): Controles para coleta de dados do usuário.
- [Layout](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/layout/): Shell completo + primitivos de espaçamento + utilitários responsivos.
- [Navegação](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/navigation/): Top bars, side navs, bottom nav, tabs, breadcrumbs, paginação, segmented control.
- [Overlay](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/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.
- [Utilitários & headless](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/utility/): 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).

## Receitas

- [Gallery — catálogo visual + funcional](https://mauriciobenjamin700.github.io/tempest-react-sdk/gallery/): Demo interativo de todos os componentes e features do SDK.
- [Release pipeline](https://mauriciobenjamin700.github.io/tempest-react-sdk/release/): Como o tempest-react-sdk é publicado no npm — workflow tag-push automático, com fallback manual.