# tempest-react-sdk [![npm version](https://img.shields.io/npm/v/tempest-react-sdk.svg)](https://www.npmjs.com/package/tempest-react-sdk) [![CI](https://github.com/mauriciobenjamin700/tempest-react-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/mauriciobenjamin700/tempest-react-sdk/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) [![React 18 / 19](https://img.shields.io/badge/react-18%20%7C%2019-61dafb.svg?logo=react)](https://react.dev) [![TypeScript](https://img.shields.io/badge/types-TypeScript-3178c6.svg?logo=typescript)](https://www.typescriptlang.org/) [![Bundle size](https://img.shields.io/bundlephobia/minzip/tempest-react-sdk?label=gzip)](https://bundlephobia.com/package/tempest-react-sdk) [**πŸ“– Documentação completa (PT-BR) β†’**](https://mauriciobenjamin700.github.io/tempest-react-sdk/) Β· [**πŸ“– Full documentation (EN-US) β†’**](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/) > O site MkDocs Γ© bilΓ­ngue (**PT-BR** padrΓ£o Β· **EN-US**) com seletor de idioma πŸ‡§πŸ‡·/πŸ‡ΊπŸ‡Έ no cabeΓ§alho. β€” The MkDocs site is bilingual (**PT-BR** default Β· **EN-US**) with a πŸ‡§πŸ‡·/πŸ‡ΊπŸ‡Έ language switcher in the header. The site is the navigable, per-module source of truth; this README stays the npm/GitHub landing page. - **PT-BR:** [Scaffold](https://mauriciobenjamin700.github.io/tempest-react-sdk/scaffold/) Β· [Estrutura de app](https://mauriciobenjamin700.github.io/tempest-react-sdk/architecture/) Β· [Componentes](https://mauriciobenjamin700.github.io/tempest-react-sdk/components/) Β· [Hooks](https://mauriciobenjamin700.github.io/tempest-react-sdk/hooks/) Β· [UtilitΓ‘rios](https://mauriciobenjamin700.github.io/tempest-react-sdk/utilities/) - **EN-US:** [Scaffold](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/scaffold/) Β· [App foundation](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/architecture/) Β· [Components](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/components/) Β· [Hooks](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/hooks/) Β· [Utilities](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/utilities/) - **πŸ†• Novo na plataforma web?** A trilha opcional **Fundamentos da Web** cobre HTML, CSS, JavaScript, TypeScript e React antes do tutorial β€” [PT-BR](https://mauriciobenjamin700.github.io/tempest-react-sdk/basics/) Β· [EN-US](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/basics/). JΓ‘ sabe React? VΓ‘ direto ao tutorial β€” [PT-BR](https://mauriciobenjamin700.github.io/tempest-react-sdk/tutorial/) Β· [EN-US](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/tutorial/). - **πŸ€– For LLMs:** [llms.txt](https://mauriciobenjamin700.github.io/tempest-react-sdk/llms.txt) (curated index) Β· [llms-full.txt](https://mauriciobenjamin700.github.io/tempest-react-sdk/llms-full.txt) (full docs in one block) β€” [llmstxt.org](https://llmstxt.org) convention. > πŸ’‘ `pip install -r docs/requirements.txt && mkdocs serve` Γ© sΓ³ para preview local β€” em produção use as URLs do GitHub Pages acima. / For local preview only β€” in production use the GitHub Pages URLs above. Shared React/TypeScript building blocks used across Tempest frontends: UI components, hooks, HTTP client, auth store, query keys, forms (zod), real-time transports (SSE / WebSocket / Web Push / Service Worker), self-hosted geolocation (tile-free maps, trajectory tracking, distance/estimate math), a clickable Brazil map + states/cities dataset + BR payment/fiscal rails β€” Pix BR Code, boleto, NFe access key, national holidays (`/br`), theme, i18n, telemetry, feature flags, offline storage, error boundary, and a curated set of utilities (`cn`, `formatCurrency`, `formatCPF`, etc.). The goal is to start every new React frontend with the same opinionated foundation already in place β€” no copy-pasting `Button`/`Input` styles, no rewriting the same auth Zustand store, no re-inventing the SSE reconnect loop. The patterns here are a distillation of what was consolidated in **alofans-frontend** and **transport-admin-system** β€” apps that consume the SDK gain consistency without paying for boilerplate. --- ## Table of contents - [Recommended stack](#recommended-stack) - [Install](#install) - [Peer & bundled dependencies](#peer--bundled-dependencies) - [CSS import](#css-import) - [What's inside](#whats-inside) - [Scaffold a new app](#scaffold-a-new-app) - [Project CLI β€” `tempest` (doctor, fix, CSS analysis)](#project-cli--tempest) - [App foundation (routing, state, providers, Vite)](#app-foundation) - [Architecture overview](#architecture-overview) - [Quickstart β€” wiring the app providers](#quickstart--wiring-the-app-providers) - [Recipes](#recipes) - [HTTP client](#http-client-recipe) - [Response parsing with zod](#response-parsing-with-zod-recipe) - [Upload with progress](#upload-with-progress-recipe) - [Polling](#polling-recipe) - [Retry & idempotency](#retry--idempotency-recipe) - [Auth store (Zustand)](#auth-store-recipe) - [Route guard](#route-guard-recipe) - [JWT helpers & refresh queue](#jwt-helpers--refresh-queue-recipe) - [Code-splitting with retry](#code-splitting-with-retry-recipe) - [React Query](#react-query-recipe) - [Form layout (`Form`, `FormSection`, `FormRow`, `FormActions`)](#form-layout-recipe) - [Forms (zod)](#forms-zod-recipe) - [BR validators & masked inputs](#br-validators--masked-inputs-recipe) - [ViaCEP lookup](#viacep-lookup-recipe) - [WebSocket](#websocket-recipe) - [WebRTC (Opus SDP tuning)](#webrtc-opus-sdp-tuning-recipe) - [Server-Sent Events (SSE)](#server-sent-events-sse-recipe) - [Web Push](#web-push-recipe) - [Service Worker helpers](#service-worker-helpers-recipe) - [Audio playback](#audio-playback-recipe) - [Offline storage (IndexedDB / Dexie)](#offline-storage-indexeddb--dexie-recipe) - [Error boundary](#error-boundary-recipe) - [Toast notifications](#toast-notifications-recipe) - [Modal & ConfirmDialog](#modal--confirmdialog-recipe) - [Tables & pagination](#tables--pagination-recipe) - [Layout primitives](#layout-primitives-recipe) - [Virtual list](#virtual-list-recipe) - [Theming (light / dark)](#theming-light--dark-recipe) - [i18n](#i18n-recipe) - [Feature flags](#feature-flags-recipe) - [Telemetry](#telemetry-recipe) - [Logger](#logger-recipe) - [Web Share API](#web-share-api-recipe) - [Hooks catalogue](#hooks-catalogue-recipe) - [Utility helpers (`cn`, `format*`, `storage`)](#utility-helpers-recipe) - [Theming reference](#theming-reference) - [Conventions](#conventions) - [Development](#development) - [Release](#release) - [License](#license) --- ## Recommended stack **Vite + React + TypeScript** is the supported consumer stack. The SDK is built and tested against [Vite 8](https://vite.dev) in library mode and assumes a Vite-style host app: - ESM-first module resolution (the package's `exports` field declares `import` / `require` conditions). - `import.meta.env` for env vars (the recipes use `import.meta.env.VITE_API_URL`, `import.meta.env.VITE_VAPID_PUBLIC_KEY`, etc.). - Native CSS Modules (the package's hashed `tempest_*` class names are emitted as CSS Modules under the hood and consumed via the global `tempest-react-sdk/styles.css` import). - Fast HMR β€” provider files (`ThemeProvider`, `I18nProvider`, etc.) opt into React Refresh. - First-class compatibility with the Vite plugin ecosystem (`vite-plugin-pwa` for service workers, `vite-plugin-dts`, `vite-plugin-svgr`, etc.). **Fastest path β€” scaffold a fully wired app** with the `create-tempest-app` CLI that ships **inside the SDK** (Vite `@` alias, declarative routing, Zustand store, TanStack Query, providers β€” all pre-fiados): ```bash # brand-new project (no install needed) β€” create the folder, scaffold into it with "." mkdir my-app cd my-app npx -p tempest-react-sdk create-tempest-app . npm install cp .env.example .env npm run dev # want it installable + web-push + offline ready? add --pwa npx -p tempest-react-sdk create-tempest-app . --pwa ``` `.` means "the current directory" β€” it preserves files you already have (`git init`, `README.md`, `LICENSE`) and takes the project name from the folder, so it is the recommended mode. Passing a name (`create-tempest-app my-app`) creates the folder instead, and aborts when it is not empty. Note there is no `create-tempest-app` package on npm β€” `npm create tempest-app` 404s, because the CLI is this package's `bin`; that is what `-p tempest-react-sdk` is for. The `--pwa` flag overlays a manifest, install prompt (`useBeforeInstallPrompt`), push wiring (`usePushSubscription`), **offline caching** (app-shell precache + runtime caching), **generated icons** (`tempestPwaIcons`, via `sharp`) and a **dev-mode service worker** (`tempestPwaDevSw`) on top of the base app β€” full `vite-plugin-pwa` parity for the common case, built from `tempest-react-sdk/sw` + `tempest-react-sdk/vite`, with no `vite-plugin-pwa`. See [Scaffold β€Ί PWA mode](https://mauriciobenjamin700.github.io/tempest-react-sdk/scaffold/#modo-pwa-pwa). Already have a project? Install the SDK, then scaffold `src/` + configs into it: ```bash npm install tempest-react-sdk npx create-tempest-app . # merges into the current dir, skips existing files ``` See [Scaffold a new app](#scaffold-a-new-app) for the generated layout. Or start from a bare Vite template and add the SDK manually: ```bash npm create vite@latest my-app -- --template react-ts cd my-app npm install tempest-react-sdk ``` The demo gallery in [`examples/gallery`](./examples/gallery) is itself a Vite app β€” use it as the reference project layout. **Scope: client-side only.** This SDK targets client-rendered, offline-capable PWAs β€” service worker, IndexedDB outbox, install prompt, background sync. It does **not** support server-side rendering or React Server Components: no module ships a `"use client"` directive, and components assume they mount in a browser. Next.js App Router is not a target. Other client bundlers (Webpack, Rspack, Parcel) **may** work β€” the package ships standard ESM + CJS + rolled-up `.d.ts` β€” but they are **not** exercised in CI, and the Vite-specific pieces used in the recipes (`import.meta.env`, the `/vite` plugins) need their own equivalents. When in doubt, start with Vite. Vite reference: . React + TypeScript template: . --- ## Install ```bash npm install tempest-react-sdk ``` Via `package.json`: ```json { "dependencies": { "tempest-react-sdk": "^0.27.0" } } ``` Requires React `>=18` and Node `>=22.12` to build. **A bundler is assumed β€” outside one, load the shipped `.css` loader.** Every component module imports its own stylesheet (see [CSS import](#css-import)), and `.css` is not a format Node can load β€” `node -e "import('tempest-react-sdk')"` fails with `ERR_UNKNOWN_FILE_EXTENSION`. Vite, webpack, Rspack, Parcel and esbuild all resolve that import, and the SDK is client-side only, so no real app consumer is affected. For everything that is not a bundler β€” a script, a Jest suite, reading the surface by introspection β€” the package ships the loader: `node --import tempest-react-sdk/node-css-loader your-script.mjs` resolves every stylesheet to an empty module, for `import` and `require` both. A **Jest** suite can use it or the usual `moduleNameMapper: { "\\.css$": "/test/css-stub.js" }`. Vitest needs nothing. ### Peer & bundled dependencies **react**, **react-dom** and **react-router** are peer dependencies β€” those must come from the host app, because a second copy is not just wasted bytes, it is a second _instance_ of a React context and it breaks at runtime. Everything else (`zod`, `zustand`, `dexie`, `react-hook-form`, `@tanstack/react-query`, `lucide-react`) is a **direct dependency** of the SDK, installed automatically by `npm install tempest-react-sdk`. You never need to install them manually. | Package | Status | Used by | | ------------------------------------- | ------------------- | ----------------------------------------------------------------------- | | `react`, `react-dom` (`^18 \|\| ^19`) | **Peer (required)** | Everything | | `react-router` (`^7 \|\| ^8`) | **Peer (required)** | `AppRouter`, `defineRoutes`, `RouteGuard`, routing re-exports | | `@tanstack/react-query` (`^5`) | Direct dep (auto) | `QueryProvider`, `createQueryKeys`, `AppProviders` | | `zod` (`^3.23 \|\| ^4`) | Direct dep (auto) | `parseResponse`, `validateForm`, `zodResolver`, `useZodForm` | | `zustand` (`^4 \|\| ^5`) | Direct dep (auto) | `createAuthStore`, `createStore`, `createSelectors` | | `dexie` (`^4.4`) | Direct dep (auto) | `createOfflineStore` | | `react-hook-form` (`^7.76`) | Direct dep (auto) | `zodResolver`, `useZodForm`, masked inputs | | `lucide-react` (`^1.31`) | Direct dep (auto) | Component icons (`leftIcon`/`rightIcon` on `Input`, `Button`, etc.) | | `vite`, `@vitejs/plugin-react` | **Optional peer** | `createViteConfig` (`tempest-react-sdk/vite`) β€” already in any Vite app | The minimum install is just: ```bash npm install tempest-react-sdk react react-dom react-router ``` **Why `react-router` is a peer and not a bundled dep.** It holds React context. A copy nested under `tempest-react-sdk/node_modules` is a _different_ `` context than the one your app renders, so any SDK hook reaching for it throws `useNavigate() may be used only in the context of a ` β€” a runtime crash, not a size regression. That is the same reason `react` itself is a peer, and it is why `react-router` is the one exception to the "everything is a direct dep" rule. The `^7 || ^8` range means an app on either major installs one copy and the SDK adapts to it: the re-exported surface is identical across both, and both ship the DOM bindings inside `react-router` (there is no separate `react-router-dom`). **Bundle impact**: every bundled dep is externalised in the SDK's Rollup config, and `dist/` ships with the module graph preserved (one file per source module), so your bundler drops what you don't import instead of inheriting one opaque blob β€” importing `cn` alone costs **153 B** brotli, a full app shell around **6.8 KB**. Your app's bundler (Vite / webpack / Rspack) resolves the deps from `node_modules` and tree-shakes them the same way β€” if you never call `createOfflineStore`, Dexie never enters your final bundle. **Version conflicts**: if your app already pins (say) `zod@3.20`, npm dedupes when the range is compatible. If ranges diverge you get two copies β€” pin a single version in your own `package.json` to force one, or open an issue if the SDK's range is too tight. Adapters for external SDKs (`@sentry/browser`, `posthog-js`, `@growthbook/growthbook`, `launchdarkly-js-client-sdk`) are **not** bundled β€” install those only when you opt into the adapter. The caller passes the SDK instance to the factory. ### CSS import Import the base stylesheet **once** at the entry of your app (e.g. `main.tsx` / `src/index.tsx`): ```ts import "tempest-react-sdk/styles.css"; ``` This injects the design tokens (`--tempest-primary`, `--tempest-radius-md`, ...), a minimal CSS reset, and the per-component CSS Modules. Tokens live on `:root` and on `[data-tempest-theme="dark"]`, so the app can override them globally or per subtree (see [Theming](#theming-reference)). The reset claims the document surface too β€” `body { margin: 0 }` plus the theme's background and text colour, and a zero-specificity `height: 100%` chain down to `#root`. Without it an `AppShell` app opens with a spurious scrollbar and an unpainted frame around the shell in dark mode. All four are one ordinary declaration away from being overridden; see [The document surface](https://mauriciobenjamin700.github.io/tempest-react-sdk/en/styles/#the-document-surface). The styles ship hashed under the `tempest_` namespace β€” they do **not** collide with Tailwind, Stitches, Linaria, or app-level CSS Modules. **Importing less β€” every component carries its own CSS.** `import { Button }` brings the button's stylesheet with it, in any bundler, with no plugin: you import the foundation and nothing else. ```ts import "tempest-react-sdk/styles/tokens.css"; import "tempest-react-sdk/styles/scoped.css"; ``` Measured in a real Vite app mounting `Button`, `Card` and `Badge`: **241.73 kB raw / 29.15 kB brotli** with `styles.css`, **27.40 kB / 4.49 kB** with the foundation alone β€” and the computed styles of all 37 selectors are identical in light and dark. The same app under webpack: 28.53 kB / 4.88 kB. `sideEffects: ["**/*.css"]` is what lets the bundler drop the sheet of a component you never mount. `styles.css` stays published, and a sheet imported by hand still works β€” see [Styles](https://mauriciobenjamin700.github.io/tempest-react-sdk/styles/) for `styles/component/.css`, the groups, and why to prefer that path to `styles/.css`. **Trimming the foundation.** `tokens.css` is 220 tokens and a three-component app reads 105 of them, so it becomes the largest single item of CSS left. `tempestStyles()` closes over the tokens your sheets actually consult β€” 4.49 kB β†’ **3.37 kB** brotli on that same app: ```ts // vite.config.ts import { tempestStyles } from "tempest-react-sdk/vite"; export default defineConfig({ plugins: [react(), tempestStyles()] }); // src/main.tsx β€” one line, forever import "tempest-react-sdk/styles/auto.css"; ``` **If your app owns its own layout,** do not reach for `core.css`: 44 of its 46 selectors dress markup you own (`html`, `body`, `#root`, `button`, `table`, `:where(ul, ol)[class]`). Dropping it is not the fix either β€” the components are written _against_ that reset, so without it they lose their box model, not their polish. Take the foundation in two pieces instead, which is also what `tempestStyles()` emits by default: ```ts import "tempest-react-sdk/styles/tokens.css"; // the 220 --tempest-* tokens import "tempest-react-sdk/styles/scoped.css"; // the reset, confined to :where([class*="tempest_"]) ``` **3.03 kB brotli** against `core.css`'s 3.23 kB β€” near enough the same bytes, which is the point: what you drop is not weight, it is the SDK reaching outside its own components. **Rebranding.** The `--tempest-*` tokens are the only theming API, and `createTheme` writes them for you β€” `primary` alone yields the ten-step scale for **both** color schemes (dark inverts the ramp), plus the status families, the radius scale and the focus ring: ```ts import { applyTheme, createTheme, themePresets } from "tempest-react-sdk"; applyTheme(createTheme({ primary: "#7c3aed", radius: "lg" })); applyTheme(createTheme(themePresets.violet)); // or start from a preset ``` The ramp is derived in OKLCH (HSL lightness is not perceptual, which is what makes generated palettes look broken for some hues) and **anchored at step `500`**, so the color you pass is the color your buttons get. `--tempest-primary-foreground` and the text-on-soft step are picked by **measured** contrast, not convention β€” hardcoding white breaks a yellow brand. See [Theme β€Ί createTheme](https://mauriciobenjamin700.github.io/tempest-react-sdk/theme/). **Optional layout layer.** CSS Modules cover the inside of each component; the layer _around_ them (page shell, two-column form, action row, card, a region that scrolls sideways instead of the page) is a second, opt-in stylesheet: ```ts import "tempest-react-sdk/utilities.css"; ``` ~50 token-driven classes, all prefixed `tempest-`, **1.13 KB brotli** β€” a page shell like `
` with `.tempest-grid-auto`, `.tempest-form-grid`, `.tempest-card`, `.tempest-truncate`. It is not imported by `styles.css`, so an app with its own layout system pays nothing. It is deliberately _not_ a utility framework: no `p-4 mt-2 bg-blue-500` per value. See [Styles β€Ί opt-in utility layer](https://mauriciobenjamin700.github.io/tempest-react-sdk/styles/). --- ## What's inside Every module is re-exported from the package root β€” `import { Button, useDebounce, createApiClient } from "tempest-react-sdk"` always works. | Module | Exports | | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `components` | `Avatar`, `Badge`, `Breadcrumbs`, `Button`, `Card`, `Checkbox`, `ChipInput`, `ConfirmDialog`, `Container`, `DatePicker`, `Drawer`, `EmptyState`, `ErrorState`, `FileUpload`, `Form` (`FormSection`, `FormRow`, `FormActions`), `Grid`, `Input`, `InstallBanner`, `InstallButton`, `Modal`, `Pagination`, `Progress`, `Radio`, `RadioGroup`, `SearchBar`, `Select`, `Skeleton`, `Spinner`, `Stack`, `Stepper`, `Switch`, `Table`, `Tabs`, `Textarea`, `Toast` (`ToastProvider`, `useToast`), `Tooltip`, `VirtualList` | | `hooks` | `useDebounce`, `usePagination`, `useClientFilter`, `useMediaQuery`, `useOnline`, `useDocumentVisibility`, `useIntersectionObserver`, `useResizeObserver`, `useClipboard`, `useKeyboardShortcut`, `useBeforeInstallPrompt`, `useIdle`, `useGeolocation`, `useScrollLock`, `useFocusTrap`, `useStableCallback`, `useAnnounce` (+ pure `announce`/`clearAnnouncer` β€” one shared live-region pair), `useDeepMemo`, `useObjectUrl`, `useLongPressHandlers` (spreadable long-press handlers + `wasLongPress()` guard), `useInstallPrompt` (install-method resolver with decline cooldown), `useServiceWorkerUpdate` (consent-based SW update flow), `useStorageEstimate` + `estimateStorage`/`requestPersistentStorage` (Storage API quota & persistence), PWA env helpers `isIOS`/`isAndroid`/`isAndroidWithoutPromptApi`/`isStandalone`/`buildOpenInChromeIntent`, type `BeforeInstallPromptEvent` | | `http` | `createApiClient`, `buildApiUrl`, `parseResponse`, `uploadWithProgress`, `createResumableUpload` (tus 1.0.0: chunked + resumable, `pause`/`resume`/`abort`), `createLocalUploadStorage`, `uploadFingerprint`, `retry`, `generateIdempotencyKey`, `usePoll`, types: `ApiClient`, `ApiClientConfig`, `ApiError`, `BuildApiUrlOptions`, `RequestOptions`, `RetryOptions`, `UploadProgressEvent`, `UploadWithProgressOptions`, `UsePollOptions`, `UsePollResult` | | `auth` _(peer: `zustand`)_ | `createAuthStore`, `AuthGuard`, `decodeJWT`, `isJWTExpired`, `lazyWithRetry`, `createRefreshQueue`, **passkeys/WebAuthn**: `createPasskeyClient`, `usePasskeyRegistration`, `usePasskeySignIn`, `usePasskeyCapabilities`, `isPasskeySupported`, `isPlatformAuthenticatorAvailable`, `isConditionalMediationAvailable`, `classifyPasskeyError`, `PasskeyError`, `base64UrlToBytes`, `bytesToBase64Url`, types: `AuthState`, `CreateAuthStoreOptions`, `AuthGuardProps`, `DecodedJWT`, `LazyWithRetryOptions` | | `oauth` _(caller injects `@react-oauth/google`)_ | `GoogleSignIn` (normalises Google's credential/error payload), `useOAuthCallback` (runs the callback exchange once, StrictMode-proof), types: `GoogleSignInProps`, `OAuthCredential`, `OAuthError`, `UseOAuthCallbackOptions`, `UseOAuthCallbackResult` | | `query` _(peer: `@tanstack/react-query`)_ | `QueryProvider`, `createQueryKeys`, `STALE_TIME`, `CACHE_TIME`, `REFETCH_TIME`, `usePaginatedQuery`, `useCursorQuery`, `useOfflineMutation` (optimistic offline mutation + cache rollback), `upsertById`/`removeById` (optimistic list-cache helpers), `persistQueryClientOffline` (IndexedDB cache persistence for offline reads) | | `router` _(dep: `react-router`)_ | `defineRoutes`, `AppRouter`, `RouteGuard`, + re-exports (`Link`, `NavLink`, `Outlet`, `Navigate`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`, `useMatch`, `useRouteError`, `redirect`, `BrowserRouter`/`HashRouter`/`MemoryRouter`/`Routes`/`Route`), types: `TempestRouteObject`, `RouterKind`, `AppRouterProps`, `RouteGuardProps` | | `store` _(dep: `zustand`)_ | `createStore`, `createSelectors`, types: `CreateStoreOptions`, `CreateStorePersistOptions`, `WithSelectors` | | `app` | `AppProviders` (composes `ErrorBoundary` β†’ `QueryProvider` β†’ `ThemeProvider` β†’ `I18nProvider`), type: `AppProvidersProps` | | `vite` _(subpath `tempest-react-sdk/vite`)_ | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev`), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `AppleSplashSpec`, `TempestVitePlugin` | | `forms` _(peer: `zod`, `react-hook-form`)_ | `validateForm`, `zodResolver`, `useZodForm`, `validateCPF`, `validateCNPJ`, `formatCEP`, `formatCNPJ`, `unmask`, `CPFInput`, `CNPJInput`, `PhoneInput`, `CEPInput`, `MoneyInput`, `useViaCEP` | | `sse` | `createEventStream`, `useEventStream` (`schema` valida cada frame β€” zod/valibot/arktype via Standard Schema β€” e `onParseError` para frame que nΓ£o Γ© JSON) | | `ws` | `createWebSocket` (handshake timeout, silence watchdog, jittered backoff, `navigator.onLine` suspend, close-code classification, `opened` promise), `useWebSocket`, `schema` + `onValidationError` (frame fora do contrato nΓ£o Γ© entregue; o `pong` do heartbeat continua saindo), `onParseError` (frame que nΓ£o Γ© JSON: descarta em vez de entregar `string` como `T`), `isRejectionCloseCode`, `HEARTBEAT_CLOSE_CODE` | | `webrtc` | `tuneOpus` (Opus `fmtp` per audio m-line: per-key merge, `stereo` + `sprop-stereo`, inserts a missing `fmtp`), `setTunedLocalDescription` (falls back to the untouched SDP when the browser refuses the edit), `setSenderBitrate`, `createLinkStatsSampler` / `useLinkStats` / `readRoundTripMs` (throughput as a delta, round trip from the **selected** candidate pair) | | `geo` _(opt. peer `leaflet`)_ | `haversineKm`, `pathLengthKm`, `bearingDeg`, `estimateTravel`, `createOSRMBackend`, `boundingBox`, `projectMercator`, `fitProjection`, `createPositionTracker`, `usePositionTracker`, `TrajectoryMap` β€” tile-free SVG map + trajectory tracking (no external/paid API; Leaflet is an opt-in, lazy-loaded tile layer for self-hosted tiles), types: `Coordinate`, `TrackPoint`, `TravelEstimate`, `TravelMode`, `GeoBounds`, `RoutingBackend` | | `br` _(subpath `tempest-react-sdk/br`)_ | `BrazilMap`, `BrazilStateMap`, `BrazilStateCitySelect`, `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity`, `loadBrUfGeoJson`, `loadStateMunicipalities`, types `UF`, `BrRegion`, `BrazilState` β€” clickable 27-UF SVG map + per-state municipality submaps (bundled simplified IBGE GeoJSON, lazy per UF) + states/cities dataset, no external API; mirrors the FastAPI SDK `utils/locations` | | `push` | `WebPushClient`, `WebPushUnsupportedError`, `WebPushPermissionDeniedError`, `usePushSubscription`, `urlBase64ToUint8Array`, `isPushSupported` | | `sw` _(also subpath `tempest-react-sdk/sw`)_ | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline + Navigation Preload), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue + `periodicsync`), `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability) β€” the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts` | | `charts` _(subpath `tempest-react-sdk/charts`, opt. peer `recharts`)_ | `AreaChart`, `BarChart`, `LineChart`, `PieChart`, `RadarChart`, `DEFAULT_CHART_COLORS` β€” themed recharts wrappers (recharts externalized; install it only if you use charts) | | `icons` _(subpath `tempest-react-sdk/icons`)_ | `Icon`, `IconProvider`, `createIconRegistry`, `useIcon`, `preloadIcons`, `iconStatus`, `peekIcon`, `loadIcon`, `resolveIconAlias`, `isIconName`, `iconNames`, `iconAliases`, type `IconName` β€” render any of lucide's **2065 icons by kebab-case slug**. A literal slug becomes a static import via the `tempestIcons()` Vite plugin (zero extra requests); a runtime slug loads **one of 46 balanced shards** (40 slugs each) instead of the ~2000 chunk boundaries `lucide-react`'s own `DynamicIcon` forces β€” sharding by range rather than by initial letter took the worst fetch from 19.10 KB to 4.78 KB brotli. Unknown slug renders `fallback` and never throws; lucide's 258 deprecated aliases keep resolving | | `audio` | `createAudioPlayer`, `playAudio`, `stopAudio`, `useAudio`, `createAudioBus` / `useAudioBus` (gain above 100%, post-mix limiter, `setSinkId` routing), `DEFAULT_MAX_GAIN` | | `capture` | `BarcodeScanner`, `useBarcodeScanner`, `useTorch`, `isBarcodeDetectionSupported`, `getSupportedBarcodeFormats`, `createBarcodeDetector`, `normalizeBarcode`, `useVideoRecorder`, `createVideoRecorder`, `pickVideoMimeType`, `isVideoRecordingSupported`, `useScreenCapture`, `isScreenCaptureSupported`, `useSpeechRecognition`, `isSpeechRecognitionSupported`, `createMediaRecorder` β€” barcode/QR reading over the native `BarcodeDetector` (Chromium-only, so inject a polyfill through `detector` or render the `unsupported` fallback), video + screen recording on the same engine as the audio recorder, and Web Speech dictation (**Chromium streams the audio to a Google server**) | | `offline` _(peer: `dexie`)_ | `createOfflineStore`, `createOfflineSync` (outbox + delta-pull + watermark engine, now with `subscribe`/`getState`/`dispose` + cross-tab `crossTab`), `useOfflineSync`/`useSyncStatus` (reactive hooks), `lastWriteWins`/`higherVersionWins` (conflict resolvers), types: `OfflineStore`, `OfflineStoreConfig`, `ListOptions`, `OfflineSync`, `OfflineSyncConfig`, `OutboxEntry`, `PullPage`, `SyncPhase`, `SyncState`, `SyncRunSummary`, `SyncTrigger`, `SyncStatus`, `SyncTone`, `WatermarkStore` | | `error-boundary` | `ErrorBoundary`, `useErrorHandler`, types: `ErrorBoundaryProps`, `ErrorBoundaryRenderProps` | | `theme` | `ThemeProvider`, `useTheme`, `getInitialTheme`, `themeInitScript`, types: `ThemeMode`, `ResolvedTheme` | | `i18n` | `createI18n`, `I18nProvider`, `useI18n`, `useTranslate`, types: `Catalog`, `Messages`, `I18n`, `InterpolationValues` | | `logger` | `createLogger`, `consoleSink`, types: `Logger`, `LogEntry`, `LogLevel`, `LoggerSink` | | `telemetry` | `TelemetryProvider`, `useTelemetry`, `consoleTelemetryAdapter`, `createSentryTelemetryAdapter`, `createPostHogTelemetryAdapter`, types: `TelemetryAdapter`, `TelemetryEvent`, `TelemetryUser`, `CreateSentryTelemetryAdapterOptions`, `SentryLike`, `CreatePostHogTelemetryAdapterOptions`, `PostHogLike` | | `perf` | `createInferenceProfiler`, `readDeviceProfile`, `cachedResponseBytes`, `formatDurationMs`, types: `InferenceProfiler`, `InferenceReport`, `InferenceReportOptions`, `DeviceProfile`, `ProfiledModel`, `ProfiledModelSize` β€” custo de inferΓͺncia on-device: cronΓ΄metro por etapa, perfil do dispositivo (cores/RAM/heap) e tamanho dos modelos em Cache Storage | | `feature-flags` | `FeatureFlagsProvider`, `useFeatureFlag`, `useFlagValue`, `createInMemoryFlags`, `createGrowthBookFeatureFlagsAdapter`, `createLaunchDarklyFeatureFlagsAdapter`, types: `FeatureFlagsAdapter`, `FlagValue`, `GrowthBookLike`, `LDClientLike` | | `share` | `share`, `isShareSupported`, `shareOrDownloadBlob` (Web Share file β†’ download fallback), types: `SharePayload`, `ShareResult`, `ShareOrDownloadOptions` | | `utils` | `cn`, format BR (`formatCurrency`, `formatDate`, `formatDateForInput`, `formatDateTime`, `formatPhone`, `formatCPF`, `formatPercent`), `storage`, strings (`slugify`, `truncate`, `capitalize`, `camelCase`, `kebabCase`, `pluralize`), numbers (`clamp`, `formatBytes`, `formatCompactNumber`, `percentOf`), arrays (`groupBy`, `uniqueBy`, `chunk`, `range`), objects (`pick`, `omit`, `deepMerge`, `isEmpty`), guards (`isDefined`, `isString`, `isNumber`, `isPlainObject`, `assertNever`), functions (`debounce`, `throttle`, `once`, `memoizeOne`), promises (`sleep`, `withTimeout`), `randomId`, `relativeTime`, `writeXlsx` (generic single-sheet OOXML `.xlsx` writer β†’ `Uint8Array`), CSV (`toCsv`, `downloadCsv` β€” RFC 4180 escaping + BOM), `setDevBuild` (tell the SDK your build is dev β€” required under Vite) | | generic components | display (`CopyButton`, `RelativeTime`, `Money`, `TruncateText`, `VisuallyHidden`), headless (`Portal`, `ClickOutside`, `ConditionalWrapper`, `For`, `ErrorText`), media/content (`Image`, `DataList`, `DescriptionList`) | | Module | Exports | | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `components` | `Avatar`, `Badge`, `Breadcrumbs`, `Button`, `Card`, `Checkbox`, `ChipInput`, `ConfirmDialog`, `Container`, `DatePicker`, `Drawer`, `EmptyState`, `ErrorState`, `FileUpload`, `Form` (`FormSection`, `FormRow`, `FormActions`), `Grid`, `Input`, `InstallBanner`, `InstallButton`, `Modal`, `Pagination`, `Progress`, `Radio`, `RadioGroup`, `SearchBar`, `Select`, `Skeleton`, `Spinner`, `Stack`, `Stepper`, `Switch`, `Table`, `Tabs`, `Textarea`, `Toast` (`ToastProvider`, `useToast`), `Tooltip`, `VirtualList` | | `hooks` | `useDebounce`, `usePagination`, `useClientFilter`, `useMediaQuery`, `useOnline`, `useDocumentVisibility`, `useIntersectionObserver`, `useResizeObserver`, `useClipboard`, `useKeyboardShortcut`, `useBeforeInstallPrompt`, `useIdle`, `useGeolocation`, `useScrollLock`, `useFocusTrap`, `useStableCallback`, `useDeepMemo`, `useObjectUrl`, `useLongPressHandlers` (spreadable long-press handlers + `wasLongPress()` guard), `useInstallPrompt` (install-method resolver with decline cooldown), `useServiceWorkerUpdate` (consent-based SW update flow), `useStorageEstimate` + `estimateStorage`/`requestPersistentStorage` (Storage API quota & persistence), PWA env helpers `isIOS`/`isAndroid`/`isAndroidWithoutPromptApi`/`isStandalone`/`buildOpenInChromeIntent`, type `BeforeInstallPromptEvent` | | `http` | `createApiClient`, `buildApiUrl`, `parseResponse`, `uploadWithProgress`, `retry`, `generateIdempotencyKey`, `usePoll`, types: `ApiClient`, `ApiClientConfig`, `ApiError`, `BuildApiUrlOptions`, `RequestOptions`, `RetryOptions`, `UploadProgressEvent`, `UploadWithProgressOptions`, `UsePollOptions`, `UsePollResult` | | `auth` _(peer: `zustand`)_ | `createAuthStore`, `AuthGuard`, `decodeJWT`, `isJWTExpired`, `lazyWithRetry`, `createRefreshQueue`, types: `AuthState`, `CreateAuthStoreOptions`, `AuthGuardProps`, `DecodedJWT`, `LazyWithRetryOptions` | | `oauth` _(caller injects `@react-oauth/google`)_ | `GoogleSignIn` (normalises Google's credential/error payload), `useOAuthCallback` (runs the callback exchange once, StrictMode-proof), types: `GoogleSignInProps`, `OAuthCredential`, `OAuthError`, `UseOAuthCallbackOptions`, `UseOAuthCallbackResult` | | `query` _(peer: `@tanstack/react-query`)_ | `QueryProvider`, `createQueryKeys`, `STALE_TIME`, `CACHE_TIME`, `REFETCH_TIME`, `usePaginatedQuery`, `useCursorQuery`, `useOfflineMutation` (optimistic offline mutation + cache rollback), `upsertById`/`removeById` (optimistic list-cache helpers), `persistQueryClientOffline` (IndexedDB cache persistence for offline reads) | | `router` _(dep: `react-router`)_ | `defineRoutes`, `AppRouter`, `RouteGuard`, + re-exports (`Link`, `NavLink`, `Outlet`, `Navigate`, `useNavigate`, `useParams`, `useSearchParams`, `useLocation`, `useMatch`, `useRouteError`, `redirect`, `BrowserRouter`/`HashRouter`/`MemoryRouter`/`Routes`/`Route`), types: `TempestRouteObject`, `RouterKind`, `AppRouterProps`, `RouteGuardProps` | | `store` _(dep: `zustand`)_ | `createStore`, `createSelectors`, types: `CreateStoreOptions`, `CreateStorePersistOptions`, `WithSelectors` | | `app` | `AppProviders` (composes `ErrorBoundary` β†’ `QueryProvider` β†’ `ThemeProvider` β†’ `I18nProvider`), type: `AppProvidersProps` | | `vite` _(subpath `tempest-react-sdk/vite`)_ | `createViteConfig`, `tempestPwaManifest` (emits `precache-manifest.json` for offline precache), `tempestPwaIcons` (generates the PNG icon set from one SVG via `sharp`), `tempestPwaDevSw` (serves the SW under `npm run dev`), `tempestPwaIcons({ appleSplash })` (Apple splash screens), types: `CreateViteConfigOptions`, `ProxyEntry`, `TempestViteConfig`, `TempestPwaManifestOptions`, `TempestPwaIconsOptions`, `TempestPwaDevSwOptions`, `AppleSplashSpec`, `TempestVitePlugin` | | `forms` _(peer: `zod`, `react-hook-form`)_ | `validateForm`, `zodResolver`, `useZodForm`, `validateCPF`, `validateCNPJ`, `formatCEP`, `formatCNPJ`, `unmask`, `CPFInput`, `CNPJInput`, `PhoneInput`, `CEPInput`, `MoneyInput`, `useViaCEP` | | `sse` | `createEventStream`, `useEventStream` (`schema` valida cada frame β€” zod/valibot/arktype via Standard Schema β€” e `onParseError` para frame que nΓ£o Γ© JSON) | | `ws` | `createWebSocket` (handshake timeout, silence watchdog, jittered backoff, `navigator.onLine` suspend, close-code classification, `opened` promise), `useWebSocket`, `schema` + `onValidationError` (frame fora do contrato nΓ£o Γ© entregue; o `pong` do heartbeat continua saindo), `onParseError` (frame que nΓ£o Γ© JSON: descarta em vez de entregar `string` como `T`), `isRejectionCloseCode`, `HEARTBEAT_CLOSE_CODE` | | `webrtc` | `tuneOpus` (Opus `fmtp` per audio m-line: per-key merge, `stereo` + `sprop-stereo`, inserts a missing `fmtp`), `setTunedLocalDescription` (falls back to the untouched SDP when the browser refuses the edit), `setSenderBitrate`, `createLinkStatsSampler` / `useLinkStats` / `readRoundTripMs` (throughput as a delta, round trip from the **selected** candidate pair) | | `geo` _(opt. peer `leaflet`)_ | `haversineKm`, `pathLengthKm`, `bearingDeg`, `estimateTravel`, `createOSRMBackend`, `boundingBox`, `projectMercator`, `fitProjection`, `createPositionTracker`, `usePositionTracker`, `TrajectoryMap` β€” tile-free SVG map + trajectory tracking (no external/paid API; Leaflet is an opt-in, lazy-loaded tile layer for self-hosted tiles), types: `Coordinate`, `TrackPoint`, `TravelEstimate`, `TravelMode`, `GeoBounds`, `RoutingBackend` | | `br` _(subpath `tempest-react-sdk/br`)_ | `BrazilMap`, `BrazilStateMap`, `BrazilStateCitySelect`, `listStates`, `getState`, `citiesByUf`, `statesByRegion`, `ufChoices`, `cityChoices`, `isValidUf`, `normalizeUf`, `isValidCity`, `loadBrUfGeoJson`, `loadStateMunicipalities`, types `UF`, `BrRegion`, `BrazilState` β€” clickable 27-UF SVG map + per-state municipality submaps (bundled simplified IBGE GeoJSON, lazy per UF) + states/cities dataset, no external API; mirrors the FastAPI SDK `utils/locations` | | `icons` _(subpath `tempest-react-sdk/icons`)_ | `Icon`, `IconProvider`, `createIconRegistry`, `useIcon`, `preloadIcons`, `iconStatus`, `peekIcon`, `loadIcon`, `resolveIconAlias`, `isIconName`, `iconNames`, `iconAliases`, type `IconName` β€” render any of lucide's **2065 icons by kebab-case slug**. A literal slug becomes a static import via the `tempestIcons()` Vite plugin (zero extra requests); a runtime slug loads **one of 46 balanced shards** (40 slugs each) instead of the ~2000 chunk boundaries `lucide-react`'s own `DynamicIcon` forces β€” sharding by range rather than by initial letter took the worst fetch from 19.10 KB to 4.78 KB brotli. Unknown slug renders `fallback` and never throws; lucide's 258 deprecated aliases keep resolving | | `push` | `WebPushClient`, `WebPushUnsupportedError`, `WebPushPermissionDeniedError`, `usePushSubscription`, `urlBase64ToUint8Array`, `isPushSupported` | | `sw` _(also subpath `tempest-react-sdk/sw`)_ | `registerServiceWorker` (opt-in `autoUpdate` poll + reload, no `vite-plugin-pwa`), `skipWaiting`, `unregisterAllServiceWorkers`, `installPushHandler`, `installNotificationClickHandler`, `installSkipWaitingListener`, `installPrecache` (app-shell offline + Navigation Preload), `installRuntimeCache` (per-route caching, incl. `rangeRequests`), `createPartialResponse` (206 range slicing), `installBackgroundSync` (offline mutation queue + `periodicsync`), `registerPeriodicSync` (main-thread periodic sync), `inspectCaches`/`clearCaches` (cache observability) β€” the React-free `tempest-react-sdk/sw` subpath is ideal for bundling into your own `sw.ts` | | `editor` _(subpath `tempest-react-sdk/editor`, opt. peers `@tiptap/react`+`@tiptap/starter-kit`)_ | `RichTextEditor` β€” themed tiptap v3 rich-text editor with toolbar (tiptap externalized; install it only if you use the editor) | | `vision` _(subpath `tempest-react-sdk/vision`, opt. peer `onnxruntime-web`)_ | `Classifier`, `Detector`, `Segmenter`, `DetectClassify` (fused detectβ†’classify pipeline) + `warmup()`, `raiseOnEmpty`/`NoDetectionsError`, `LetterboxPipeline`, `readFusionSpec` and results/labels/preprocess β€” on-device ONNX vision inference, vendored from `@mauriciobenjamin700/ort-vision-sdk-web` (onnxruntime-web externalized; install it only if you use vision). Plus browser capture primitives: `useCameraStream` (rear-camera `getUserMedia` + classified errors + `retry()`), `computeImageLuminance`/`isLuminanceAcceptable`/`LowLuminanceError`/`LUMINANCE_SAMPLE_MAX_EDGE` (BT.709 brightness), `useLiveLuminance` (live rAF sampling) | | `tabular` _(subpath `tempest-react-sdk/tabular`, opt. peer `onnxruntime-web`)_ | `TabularPredictor`, `useTabularPredictor` β€” scikit-learn models exported by `tempest-fastapi-sdk`'s `export_sklearn_to_onnx`, running in the browser with no inference server. Offline by design: `fetchModelBytes`/`isModelCached`/`cacheModelBytes`/`clearModelCache` (Cache Storage, cache-first) plus `configureOrtAssets`/`ortAssetUrls`/`ORT_WASM_ASSETS` for the runtime's WebAssembly binaries, which ONNX Runtime Web fetches at session creation. Import the default `onnxruntime-web` entry β€” the WebGPU build has no `ai.onnx.ml` kernels | | `imaging` _(subpath `tempest-react-sdk/imaging`, no deps)_ | `resizeImage`, `cropImage`, `rotateImage`, `flipImage`, `compressToTarget` (binary-searches quality into a byte budget), `createThumbnails` (several sizes from one decode), `captureFrame` (one frame out of a `