tempest-react-sdk 0.43.0 → 0.45.0

package/dist/tempest-react-sdk.d.ts

@@ -543,6 +543,16 @@ declare type AnyEventTarget = EventTarget | {
     current: EventTarget | null;
 } | null | undefined;
 
+/**
+ * Translation key the {@link useDescribeApiError} hook looks up.
+ *
+ * A catalog that does not define it falls back to
+ * {@link DEFAULT_API_ERROR_STRINGS}, because `t` returns the key itself when the
+ * lookup misses and printing `tempest.error.offline` at the user would be worse
+ * than printing pt-BR at them.
+ */
+export declare const API_ERROR_OFFLINE_KEY = "tempest.error.offline";
+
 export declare interface ApiClient {
     request<T>(path: string, options?: RequestOptions): Promise<T>;
     get<T>(path: string, options?: RequestOptions): Promise<T>;
@@ -554,8 +564,28 @@ export declare interface ApiClient {
 }
 
 export declare interface ApiClientConfig {
-    /** Base URL for every request. Required. */
+    /**
+     * Base URL for every request. Required.
+     *
+     * May carry a path (`https://api.example.com/api`) — it is kept, and a
+     * request for `"/auth/login"` lands on `/api/auth/login`. May also be
+     * relative (`"/api"`), which resolves against the current origin and is the
+     * shape to use behind a dev-server or reverse proxy.
+     */
     baseURL: string;
+    /**
+     * Path segment every request is nested under, such as `"/api"` — the
+     * `root_path` a Tempest FastAPI service is usually mounted on.
+     *
+     * The alternative to writing it into `baseURL`, and the better one when the
+     * base comes from an environment variable that other things also use (an
+     * SSE endpoint, a media host): the variable stays the bare origin and only
+     * the client carries the prefix.
+     *
+     * Applied at most once — a path that already opens with the prefix is left
+     * alone, so call sites can migrate one at a time.
+     */
+    prefix?: string;
     /** Returns the current bearer token (or null/undefined). Called per request. */
     getToken?: () => string | null | undefined;
     /**
@@ -627,6 +657,12 @@ export declare interface ApiError {
     body?: unknown;
 }
 
+/** The two fixed sentences {@link describeApiError} may need. */
+export declare interface ApiErrorStrings {
+    /** Shown when the request never reached the server. */
+    offline: string;
+}
+
 /**
  * Mobile-first top app bar for PWAs — leading (back / brand) + title +
  * trailing actions, sticky with safe-area padding out of the box.
@@ -675,7 +711,14 @@ export declare interface AppBarProps extends Omit<HTMLAttributes<HTMLElement>, "
     actions?: ReactNode;
     /** Center the title (three-column grid). Default `false` (left-aligned). */
     centered?: boolean;
-    /** Stick to the top of the scroll container. Default `true`. */
+    /**
+     * Stick to the top of the scroll container. Default `true`.
+     *
+     * The page has to leave the body out of the scrolling: `body { overflow-x:
+     * hidden }` makes the body a scroll container and the bar scrolls away with
+     * the content. Use `overflow-x: clip` on `html` and `body` instead — in
+     * development the bar says so in the console when it detects it.
+     */
     sticky?: boolean;
     /** Visual tone. Default `"surface"`. */
     tone?: AppBarTone;
@@ -687,6 +730,37 @@ export declare interface AppBarProps extends Omit<HTMLAttributes<HTMLElement>, "
 
 export declare type AppBarTone = "surface" | "primary" | "transparent";
 
+/**
+ * Run a filter set over an in-memory list.
+ *
+ * Closes the loop `FilterBar` opens: the bar produces `Filter[]`, this applies
+ * them. Filters combine with `AND`, matching the flat model the bar builds, and
+ * an incomplete filter is skipped rather than treated as a match of nothing — a
+ * half-filled form should not empty the table underneath it.
+ *
+ * Comparison follows the row's type, not the filter's: numbers compare
+ * numerically, dates compare by day, and everything else compares as text with
+ * `numeric: true` so `"item 2"` lands before `"item 10"`.
+ *
+ * A few behaviours differ from the SQL the server-side twin produces, and the
+ * difference is deliberate rather than accidental:
+ *
+ * - `ne` matches rows whose value is absent. In SQL, `column <> 'x'` is `NULL`
+ *   for a `NULL` column and the row drops out. Here "is not paid" shows the rows
+ *   with no status at all, which is what the chip claims.
+ * - `empty` matches `NULL`, blank text and empty lists; `__isnull` on the server
+ *   only matches `NULL`. A column that stores `""` instead of `NULL` is where
+ *   the two disagree.
+ *
+ * @example
+ * const visible = applyFilters(orders, filters);
+ *
+ * @param items - The full list.
+ * @param filters - Applied filters; incomplete ones are ignored.
+ * @returns A new array with the rows that satisfy every complete filter.
+ */
+export declare function applyFilters<T>(items: readonly T[], filters: readonly Filter[]): T[];
+
 /**
  * Apply a {@link KanbanMove} to a column list, returning new arrays.
  *
@@ -1359,6 +1433,84 @@ export declare interface BarcodeScanResult {
     cornerPoints: readonly BarcodePoint[];
 }
 
+/**
+ * A ranked distribution: label, proportional bar, value, optional share.
+ *
+ * The most common chart on an admin panel, and the one the SDK kept sending
+ * people to write by hand — `Progress` is a single bar and `Sparkline` is a time
+ * series, so a "users per plan" block ended up reimplemented per screen, each
+ * with its own CSS and its own `.sort()`.
+ *
+ * It is a **list**, not a picture: `<ul>` / `<li>` with the value written as
+ * text, the bar `aria-hidden` behind it. A screen reader reads "Free, 128, 62%"
+ * because that text is there, not because an `aria-label` restates a drawing.
+ * Which is also why the label never sits on top of the bar — text over a tinted
+ * fill has to be re-verified against that fill, and the SDK has been caught by
+ * that twice.
+ *
+ * Bar width is relative to the **largest** row, so the biggest bar fills the
+ * track; the percentage is the row's share of the **total**. They are different
+ * numbers on purpose: a width scaled by the total leaves every bar short in a
+ * long list, which is when the chart is needed most.
+ *
+ * @example
+ * <BarList
+ *     items={[{ label: "Free", value: 128 }, { label: "Pro", value: 32 }]}
+ *     valueFormatter={(n) => `${n} ativos`}
+ *     showPercentage
+ *     max={5}
+ *     otherLabel="Outros"
+ * />
+ *
+ * @param props - Items plus presentation.
+ * @returns The list.
+ */
+export declare function BarList({ items, valueFormatter, showPercentage, sort, max, otherLabel, className, ...rest }: BarListProps): JSX.Element;
+
+/** One entry of a {@link BarList}. */
+export declare interface BarListItem {
+    /** What the row is called. */
+    label: string;
+    /** The measured amount. */
+    value: number;
+    /** Override the bar colour. Defaults to the chart series token for its position. */
+    color?: string;
+}
+
+export declare interface BarListProps extends Omit<HTMLAttributes<HTMLUListElement>, "children"> {
+    /** The rows. Entries whose value is not finite are dropped. */
+    items: readonly BarListItem[];
+    /** Render the number. Defaults to the value as-is. */
+    valueFormatter?: (value: number) => string;
+    /** Show each row's share of the total next to its value. Default `false`. */
+    showPercentage?: boolean;
+    /** Ordering. Default `"desc"`, which is what a ranking means. */
+    sort?: BarListSort;
+    /** Keep at most this many rows. */
+    max?: number;
+    /**
+     * Label for one aggregated row holding everything `max` cut off.
+     *
+     * Without it, `max` simply truncates. The aggregate row only appears when more
+     * than one row was cut — collapsing a single row into "others" hides its name
+     * for nothing.
+     */
+    otherLabel?: string;
+}
+
+/** One row, with everything the component needs to draw it. */
+export declare interface BarListRow extends BarListItem {
+    /** Share of the total, 0–100. */
+    percentage: number;
+    /** Bar width relative to the largest row, 0–100. */
+    width: number;
+    /** Position in the original palette cycle. */
+    index: number;
+}
+
+/** How the list orders itself before drawing. */
+export declare type BarListSort = "desc" | "asc" | "none";
+
 /**
  * Decode a base64url string into bytes.
  *
@@ -1552,6 +1704,79 @@ export declare const BREAKPOINTS: Record<Breakpoint, number>;
 
 export { BrowserRouter }
 
+/**
+ * Join a base URL, an optional prefix and a request path into an absolute URL.
+ *
+ * `new URL(path, base)` on its own is wrong for an API client. It follows the
+ * URL spec, where a path starting with `/` is absolute against the *origin* and
+ * therefore discards whatever path the base carried: a client on
+ * `https://api.example.com/api` asked for `/auth/login` reaches
+ * `https://api.example.com/auth/login`, and every request 404s with nothing in
+ * the config that looks wrong. This function resolves the path against the base
+ * *path* instead, so the leading slash is a matter of taste rather than a
+ * silent 404, and `baseURL` + `prefix` are interchangeable ways to say the same
+ * thing.
+ *
+ * The prefix is applied at most once: a path that already opens with it — say
+ * `"/api/auth/login"` under a `"/api"` prefix — is left alone, so a codebase
+ * migrating to `prefix` can move its call sites one at a time. The check is per
+ * segment, so `/api-keys` is not mistaken for an already-prefixed path.
+ *
+ * A path that is itself an absolute URL wins over all of this, which is how a
+ * client reaches a second host (a signed upload endpoint, a CDN) without a
+ * second client.
+ *
+ * @example
+ * buildApiUrl("https://api.example.com", "/auth/login", { prefix: "/api" });
+ * // "https://api.example.com/api/auth/login"
+ *
+ * buildApiUrl("https://api.example.com/api", "auth/login");
+ * // "https://api.example.com/api/auth/login"
+ *
+ * @param baseURL - Absolute base URL, or a path relative to the current origin.
+ * @param path - The request path, or an absolute URL to use as-is.
+ * @param options - Optional prefix and query params.
+ * @returns The absolute URL to fetch.
+ * @throws When `baseURL` is relative and there is no `location` to resolve it.
+ */
+export declare function buildApiUrl(baseURL: string, path: string, options?: BuildApiUrlOptions): string;
+
+/** Options accepted by {@link buildApiUrl}. */
+export declare interface BuildApiUrlOptions {
+    /**
+     * Path segment every request is nested under, such as `"/api"`. Joined
+     * after the path the `baseURL` already carries.
+     */
+    prefix?: string;
+    /** Query params to append. `undefined` and `null` values are skipped. */
+    params?: Record<string, string | number | boolean | undefined | null>;
+}
+
+/**
+ * Order, truncate and measure the rows.
+ *
+ * Two different numbers come out of this, and conflating them is the classic bug
+ * in a hand-written bar list:
+ *
+ * - `percentage` is the row's share of the **total**, which is what the label
+ *   claims when it reads "32%".
+ * - `width` is relative to the **largest** row, so the biggest bar fills the
+ *   track. Scaling width by the total instead leaves every bar short in a list of
+ *   many small values, and the chart stops being readable exactly when it has the
+ *   most rows.
+ *
+ * The total counts positive values only. A negative amount draws no bar (a bar of
+ * negative width does not exist) and reports 0%, but its number is still shown —
+ * hiding the row would be worse than showing an odd one.
+ *
+ * @param items - The rows as given.
+ * @param sort - Ordering to apply. `"none"` keeps the caller's order.
+ * @param max - Keep at most this many rows.
+ * @param otherLabel - Aggregate what `max` cut into one row with this label.
+ * @returns The rows to draw, in order.
+ */
+export declare function buildBarListRows(items: readonly BarListItem[], sort: BarListSort, max: number | undefined, otherLabel: string | undefined): BarListRow[];
+
 /**
  * Builds an `intent://` URL that re-opens the current page inside Chrome on
  * Android. When Chrome is missing, the fallback URL points to the Play Store so
@@ -2328,6 +2553,66 @@ export declare interface CommandProps {
  */
 export declare function compareValues(a: unknown, b: unknown): number;
 
+/**
+ * Typed `localStorage` wrapper that gzips what it writes.
+ *
+ * Mirrors {@link storage} so the two are interchangeable at the call site; the
+ * difference is only in how the value is encoded.
+ */
+export declare const compressedStorage: {
+    /**
+     * Read and decompress a key.
+     *
+     * @typeParam T - The expected value shape.
+     * @param key - Storage key.
+     * @param fallback - Returned when the key is absent, unreadable, or corrupt.
+     * @returns The stored value, or `fallback`.
+     */
+    get<T>(key: string, fallback: T): T;
+    /**
+     * Compress and write a key.
+     *
+     * When compression itself fails the value is written as plain JSON rather
+     * than dropped: a slightly larger record still loads, an absent one does
+     * not. Only a storage-level failure — quota, blocked storage — loses the
+     * write.
+     *
+     * @typeParam T - The value being stored.
+     * @param key - Storage key.
+     * @param value - Any JSON-serializable value.
+     */
+    set<T>(key: string, value: T): void;
+};
+
+/**
+ * Codec pair for {@link useLocalStorage}, so a compressed key gets the hook's
+ * cross-tab sync and SSR guard for free.
+ *
+ * @example
+ * const [save, setSave] = useLocalStorage("save", EMPTY_SAVE, compressedStorageCodec);
+ */
+export declare const compressedStorageCodec: {
+    serialize: typeof compressToString;
+    deserialize: typeof decompressFromString;
+};
+
+/**
+ * Serialize a value to a gzipped, base64 string carrying the format marker.
+ *
+ * Base64 costs a third more characters than the raw compressed bytes, and
+ * `localStorage` bills two bytes per character on top of that. Packing the
+ * bytes into UTF-16 code units directly would be denser, but lone surrogates
+ * survive neither every storage implementation nor a JSON round-trip, and a
+ * save that decodes to garbage is far worse than one that is bigger. Even with
+ * that overhead a typical JSON document lands well under a third of its
+ * uncompressed size.
+ *
+ * @typeParam T - The value being stored.
+ * @param value - Any JSON-serializable value.
+ * @returns The encoded string, ready for `localStorage`.
+ */
+export declare function compressToString<T>(value: T): string;
+
 /**
  * Conditionally wraps its children with `wrapper`.
  *
@@ -3287,6 +3572,36 @@ export declare interface CreateSentryTelemetryAdapterOptions {
     breadcrumbCategory?: string;
 }
 
+/**
+ * A pool of preallocated `<audio>` elements for short sound effects.
+ *
+ * `new Audio(src)` on every play allocates an element and re-enters the network
+ * stack for a file the browser already has, which is the wrong shape for a
+ * sound that fires dozens of times a minute — a UI blip, a hit, a pickup. The
+ * pool allocates once per source and replays.
+ *
+ * This is deliberately not {@link createAudioPlayer}: that handle tracks a
+ * single "current" clip with loop, sink routing and lifecycle callbacks, which
+ * is what background music needs. Effects are the opposite case — many
+ * sources, all short, fire-and-forget, and the only thing that matters is that
+ * firing one is cheap.
+ *
+ * A blocked `play()` is swallowed. Browsers reject playback until the user has
+ * interacted with the page, and a sound effect is by definition not worth
+ * interrupting anything over; call {@link SfxPool.preload} after the first
+ * interaction if you want the pool warm.
+ *
+ * @param options - Master volume, base URL, voices per source and pool size.
+ * @returns The pool handle.
+ *
+ * @example
+ * const sfx = createSfxPool({ volume: 0.6, baseUrl: import.meta.env.BASE_URL });
+ * sfx.preload(["sfx/select.mp3", "sfx/back.mp3"]);
+ *
+ * <button onClick={() => sfx.play("sfx/select.mp3")}>Confirmar</button>
+ */
+export declare function createSfxPool(options?: SfxPoolOptions): SfxPool;
+
 /**
  * Create a typed Zustand store with optional `persist` middleware, wired with
  * Tempest defaults. This is the generic counterpart to `createAuthStore`: use
@@ -3377,6 +3692,16 @@ export declare function createTempestAuth<TUser, TCredentials = {
 export declare interface CreateTempestAuthOptions<TUser> {
     /** Base URL of the API. Required. */
     baseURL: string;
+    /**
+     * Path segment the API is mounted under, such as `"/api"`, forwarded to
+     * every client this preset builds — see the `prefix` option of
+     * `createApiClient`.
+     *
+     * Safe to combine with the default paths below: the prefix is applied at
+     * most once, so `"/api/auth/login"` under a `"/api"` prefix stays
+     * `"/api/auth/login"`.
+     */
+    prefix?: string;
     /** Login route (`POST`). Default: `"/api/auth/login"`. */
     loginPath?: string;
     /** Refresh route (`POST`). Default: `"/api/auth/refresh"`. */
@@ -3586,6 +3911,36 @@ export declare interface CredentialsContainerLike {
     }): Promise<Credential | null>;
 }
 
+/** One column of the exported file. */
+export declare interface CsvColumn<T> {
+    /** Property of the row this column reads from. Doubles as the column key. */
+    key: keyof T;
+    /** Column heading, written to the first line. */
+    header: string;
+    /**
+     * Value for the file. Defaults to `String(row[key])`, with nullish becoming an
+     * empty field.
+     *
+     * A `DataTableColumn` renders cells to `ReactNode`, which cannot be written to
+     * a text file — a badge or a link would serialize as `[object Object]`. Give
+     * the column this accessor and the export says what the badge said.
+     */
+    csv?: (row: T) => string | number | boolean | null | undefined;
+}
+
+/** Options for {@link toCsv}. */
+export declare interface CsvOptions {
+    /**
+     * Field separator. Default `","`.
+     *
+     * Use `";"` for Excel on a locale whose decimal separator is the comma —
+     * which is every pt-BR install — otherwise it opens the file in one column.
+     */
+    delimiter?: "," | ";";
+    /** Prefix the output with a UTF-8 BOM. Default `true`. */
+    bom?: boolean;
+}
+
 /** Cursor-paginated response envelope (`CursorPaginationSchema[T]`). */
 export declare interface CursorPage<T> {
     /** The rows for this batch. */
@@ -3744,7 +4099,7 @@ export declare interface DataProviderOptions {
  * render without changing behaviour. That is why `exhaustive-deps` is silenced on
  * that dependency array.
  */
-export declare function DataTable<T>({ data, columns, pageSize, searchable, searchKeys, initialSort, rowKey, emptyMessage, onCellChange, editLabels, className, ...rest }: DataTableProps<T>): JSX.Element;
+export declare function DataTable<T>({ data, columns, pageSize, searchable, searchKeys, initialSort, rowKey, emptyMessage, onCellChange, editLabels, totalItems, page: controlledPage, onPageChange, manualSort, onSortChange, manualSearch, onSearchChange, loading, className, ...rest }: DataTableProps<T>): JSX.Element;
 
 /** One accepted cell edit, handed to `onCellChange`. */
 export declare interface DataTableCellChange<T> {
@@ -3824,7 +4179,13 @@ export declare interface DataTableEditLabels {
 export declare type DataTableEditorType = "text" | "number" | "date" | "email" | "tel" | "url";
 
 export declare interface DataTableProps<T> extends HTMLAttributes<HTMLDivElement> {
-    /** Full, unfiltered dataset. Sorting/filtering/pagination happen client-side. */
+    /**
+     * The rows to work with.
+     *
+     * By default this is the **full** dataset and sorting, searching and paging
+     * all happen in memory. Pass `totalItems` and it becomes the current page as
+     * the server returned it, with those three delegated to the caller.
+     */
     data: T[];
     /** Column definitions. */
     columns: DataTableColumn<T>[];
@@ -3851,6 +4212,51 @@ export declare interface DataTableProps<T> extends HTMLAttributes<HTMLDivElement
     onCellChange?: (change: DataTableCellChange<T>) => void | Promise<void>;
     /** Override the PT-BR copy of the editing affordances. */
     editLabels?: Partial<DataTableEditLabels>;
+    /**
+     * Total row count across every page — the `total` of a paginated envelope.
+     *
+     * Passing it switches the table to **server mode**: `data` is read as the
+     * current page, the page count comes from this number instead of
+     * `data.length`, and sorting and searching are delegated to the caller
+     * (see `manualSort` / `manualSearch`, which are implied here). Pair it with
+     * `page` and `onPageChange`.
+     */
+    totalItems?: number;
+    /** Current page, 1-based. Controlled — required in server mode. */
+    page?: number;
+    /** Called with the next page. Required whenever `page` is controlled. */
+    onPageChange?: (page: number) => void;
+    /**
+     * Sorting is the caller's job: clicking a header reports through
+     * `onSortChange` and the rows are left in the order they arrived.
+     *
+     * Implied by `totalItems`, because sorting the page in memory would sort
+     * *that page only* while the header claims the whole table is ordered.
+     */
+    manualSort?: boolean;
+    /** Called with the next sort state — `null` when the header cycles back to unsorted. */
+    onSortChange?: (sort: DataTableSort<T> | null) => void;
+    /**
+     * Searching is the caller's job: typing reports through `onSearchChange` and
+     * the rows are left as they arrived.
+     *
+     * Implied by `totalItems`. Filtering the current page would hide the rows
+     * that do not match *on this page* and show nothing for a term that only
+     * matches on page three — an empty table that looks like "no results".
+     */
+    manualSearch?: boolean;
+    /** Called with the current search term (debouncing, if any, is the caller's). */
+    onSearchChange?: (term: string) => void;
+    /**
+     * A fetch is in flight.
+     *
+     * With rows already on screen they stay put, dimmed and `aria-busy`, so the
+     * page does not jump under the cursor between pages. With no rows yet it
+     * renders placeholder lines at full height, which is a different statement
+     * from `emptyMessage`: "loading" and "there is nothing" are not the same
+     * screen.
+     */
+    loading?: boolean;
 }
 
 export declare interface DataTableSort<T> {
@@ -3953,6 +4359,20 @@ export declare interface DecodedJWT {
  */
 export declare function decodeJWT(token: string): DecodedJWT;
 
+/**
+ * Decode a string produced by {@link compressToString}.
+ *
+ * A string without the marker is parsed as plain JSON, so values written before
+ * compression was enabled — or by a write that fell back after `gzipSync`
+ * failed — still read back.
+ *
+ * @typeParam T - The expected value shape.
+ * @param raw - The stored string.
+ * @returns The decoded value.
+ * @throws If the payload is neither valid compressed data nor valid JSON.
+ */
+export declare function decompressFromString<T>(raw: string): T;
+
 /**
  * Recursively merge `source` into `target`, returning a new object.
  *
@@ -3974,6 +4394,15 @@ export declare function decodeJWT(token: string): DecodedJWT;
  */
 export declare function deepMerge<T>(target: T, source: Partial<T>): T;
 
+/**
+ * PT-BR defaults, used when no strings are supplied and no catalog answers.
+ *
+ * The SDK's copy is pt-BR everywhere else (`FilterBar`, `DataTable`, `Chat`), so
+ * the default here matches rather than introducing an English string that only
+ * shows up on a network failure.
+ */
+export declare const DEFAULT_API_ERROR_STRINGS: ApiErrorStrings;
+
 /**
  * What a scanner looks for when you do not say.
  *
@@ -4035,6 +4464,36 @@ export declare const DEFAULT_PUB_KEY_CRED_PARAMS: {
  */
 export declare function defineRoutes(routes: TempestRouteObject[]): TempestRouteObject[];
 
+/**
+ * Turn any caught value into a sentence worth showing.
+ *
+ * The funnel, in order:
+ *
+ * 1. A request that never reached the server — `status === 0`, or a non-API
+ *    error thrown while the browser reports itself offline — produces the
+ *    offline sentence. This is the step apps skip, and skipping it renders
+ *    "erro 0" or a raw `TypeError` at the user.
+ * 2. The backend's own `detail`, which is the most specific thing available and
+ *    is already written for a person.
+ * 3. `fallback`, with `(HTTP <status>)` appended when a status is known, so the
+ *    screenshot in the support ticket carries the one fact a developer needs.
+ *
+ * Pure on purpose: it works in an interceptor, in a logger and anywhere outside
+ * the React tree. {@link useDescribeApiError} is the same funnel with the
+ * sentences resolved through `I18nProvider`.
+ *
+ * @example
+ * catch (error) {
+ *     toast(describeApiError(error, "Não foi possível salvar o pedido"));
+ * }
+ *
+ * @param error - The caught value, of any shape.
+ * @param fallback - What to say when the error carries nothing better.
+ * @param strings - Overrides for the fixed sentences.
+ * @returns A sentence to show the user.
+ */
+export declare function describeApiError(error: unknown, fallback: string, strings?: Partial<ApiErrorStrings>): string;
+
 /**
  * One filter, in words: `"Status é Pago"`.
  *
@@ -4169,6 +4628,25 @@ export declare type DividerVariant = "solid" | "dashed";
 
 export declare type DocumentVisibility = "visible" | "hidden";
 
+/**
+ * Build a CSV and hand it to the user.
+ *
+ * Goes through {@link shareOrDownloadBlob}, so on a phone it opens the native
+ * share sheet and everywhere else it downloads — the same path every other
+ * generated artifact in the SDK takes, instead of a fourth hand-rolled `<a
+ * download>`.
+ *
+ * @example
+ * await downloadCsv(users, COLUMNS, "usuarios.csv");
+ *
+ * @param rows - The rows to export.
+ * @param columns - Columns, in the order they should appear.
+ * @param fileName - File name offered to the user. Default `"export.csv"`.
+ * @param options - Delimiter and BOM, forwarded to {@link toCsv}.
+ * @returns A promise that resolves once the share or download completes.
+ */
+export declare function downloadCsv<T>(rows: readonly T[], columns: readonly CsvColumn<T>[], fileName?: string, options?: CsvOptions): Promise<void>;
+
 /**
  * Sliding side panel. Same building blocks as {@link Modal} but anchored to
  * an edge. Locks body scroll while open.
@@ -4637,6 +5115,51 @@ export declare type FilterPredicate<T> = (item: T, search: string) => boolean;
  */
 export declare function filtersFromSearchParams(params: URLSearchParams, fields: readonly FilterField[]): Filter[];
 
+/**
+ * Encode filters as query params for a paginated backend.
+ *
+ * The counterpart of {@link applyFilters}: same filter set, evaluated by the
+ * database instead of by the browser, which is the only option once the list is
+ * paginated on the server and the page in memory is not the whole result.
+ *
+ * The encoding is the `<column>__<op>` convention `tempest-fastapi-sdk` already
+ * reads (`BaseRepository._apply_filters` → `build_filter_condition`):
+ *
+ * | Operator | Param |
+ * | --- | --- |
+ * | `eq` | `field` (or `field__iexact` for the `name` column) |
+ * | `ne` | `field__ne` |
+ * | `contains` | `field__icontains` |
+ * | `gt` `gte` `lt` `lte` | `field__gt` … `field__lte` |
+ * | `between` | `field__between` twice, low value first |
+ * | `in` | `field__in` once per value |
+ * | `empty` / `notEmpty` | `field__isnull=true` / `=false` |
+ *
+ * Returns `URLSearchParams` rather than a plain object because `between` carries
+ * a pair and `in` carries a list: an object would keep only the last value of
+ * each, silently narrowing the filter. Repeated params are also how FastAPI
+ * receives a `list[str]` declared with `Query`.
+ *
+ * Two things the backend has to hold up its end of, or the filter fails quietly:
+ *
+ * - **Every key must be declared.** `BasePaginationFilterSchema.get_conditions()`
+ *   only forwards fields the subclass declares, so a `status__ne` the schema
+ *   never mentions is dropped by FastAPI before the repository sees it — no
+ *   error, no filtering.
+ * - **`isnull` matches `NULL` only.** A column that stores `""` for "no value"
+ *   will not answer an `empty` filter, while {@link applyFilters} treats blank
+ *   text as empty.
+ *
+ * @example
+ * const params = filtersToQueryParams(filters);
+ * params.set("page", String(page));
+ * const data = await api.get(`/orders?${params}`);
+ *
+ * @param filters - Applied filters; incomplete ones are ignored.
+ * @returns Params ready to append to a request URL.
+ */
+export declare function filtersToQueryParams(filters: readonly Filter[]): URLSearchParams;
+
 /**
  * Serialize filters into URL search params.
  *
@@ -4840,6 +5363,30 @@ export declare function formatCurrency(value: number): string;
  */
 export declare function formatDate(value: string | Date): string;
 
+/**
+ * Format an ISO date or Date instance as `yyyy-MM-dd`, the value an
+ * `<input type="date">` accepts.
+ *
+ * Built from the **local** calendar parts rather than `toISOString().slice(0, 10)`,
+ * which is the reflex and which is wrong: `toISOString` converts to UTC first, so
+ * anything after 21:00 in UTC-3 reports the next day and the form opens on the
+ * wrong date. `formatDate` cannot fill this role because a date input rejects
+ * `dd/MM/yyyy` outright.
+ *
+ * A value that is already `yyyy-MM-dd` is returned untouched, and that shortcut
+ * is load-bearing rather than an optimisation: `new Date("2026-05-16")` is parsed
+ * as **UTC** midnight, which in UTC-3 is the 15th at 21:00, so round-tripping the
+ * exact value a backend sent would move it back a day.
+ *
+ * @example
+ * <input type="date" defaultValue={formatDateForInput(order.createdAt)} />
+ *
+ * @param value - ISO string or Date.
+ * @returns The `yyyy-MM-dd` value, or an empty string when the input is invalid —
+ *   which is what a date input reads as "no value", unlike `"Invalid Date"`.
+ */
+export declare function formatDateForInput(value: string | Date): string;
+
 /**
  * Format an ISO date or Date instance as `dd/MM/yyyy HH:mm`.
  *
@@ -6186,17 +6733,22 @@ declare interface LayoutProps {
 }
 
 /**
- * Wrap `React.lazy` with automatic retry. Common cause of failure:
- * deployed-then-cached `index.html` references chunk filenames that no
- * longer exist. Retrying after a short delay typically picks up the new
- * bundle; a final `location.reload()` recovers from stale `index.html`.
+ * Wrap `React.lazy` with automatic retry and a `preload()` method.
+ *
+ * Common cause of failure: deployed-then-cached `index.html` references chunk
+ * filenames that no longer exist. Retrying after a short delay typically picks
+ * up the new bundle; a final `location.reload()` recovers from stale
+ * `index.html`.
  *
  * @example
  * const Settings = lazyWithRetry(() => import("./Settings"));
+ *
+ * // Warm the chunk when the route becomes likely, not when it is needed.
+ * <a href="/settings" onMouseEnter={() => void Settings.preload()}>Settings</a>
  */
 export declare function lazyWithRetry<T extends ComponentType<unknown>>(factory: () => Promise<{
     default: T;
-}>, options?: LazyWithRetryOptions): ReturnType<typeof lazy<T>>;
+}>, options?: LazyWithRetryOptions): PreloadableLazy<T>;
 
 export declare interface LazyWithRetryOptions {
     /** Max attempts. Default: 3. */
@@ -8005,6 +8557,33 @@ export declare interface PcmAudio {
     sampleRate: number;
 }
 
+/**
+ * What percentage of `total` is `part`, with an empty base yielding `0`.
+ *
+ * The guard is the whole point: `(part / total) * 100` produces `NaN` when the
+ * base is zero and `Infinity` when only the base is missing, and both reach the
+ * screen as a broken label — `NaN%` on an empty dashboard is the single most
+ * common way a panel announces that it has no data yet.
+ *
+ * Returns a **0–100** number, which is what a bar width and a label want.
+ * `formatPercent` takes a 0–1 fraction instead, so pair them as
+ * `formatPercent(percentOf(a, b) / 100)` — or skip `percentOf` and pass the
+ * fraction straight in.
+ *
+ * The result is not clamped: 120% of a target is a real number somebody wants to
+ * see, and capping it would hide the interesting case.
+ *
+ * @example
+ * percentOf(3, 4);  // 75
+ * percentOf(5, 0);  // 0
+ * percentOf(12, 8); // 150
+ *
+ * @param part - The measured amount.
+ * @param total - The base it is measured against.
+ * @returns The percentage, or `0` when the base is zero or either input is not finite.
+ */
+export declare function percentOf(part: number, total: number): number;
+
 /**
  * Extract a permission list from a JWT.
  *
@@ -8181,6 +8760,12 @@ export declare interface PlayAudioOptions {
     onError?: (error: unknown) => void;
 }
 
+/** Per-play overrides. */
+export declare interface PlaySfxOptions {
+    /** Volume for this play, `0`–`1`, multiplied by the pool's master. Default `1`. */
+    volume?: number;
+}
+
 /**
  * Pick the singular or plural form of a word based on `count`.
  *
@@ -8276,6 +8861,29 @@ export declare interface PostHogLike {
     reset?: () => void;
 }
 
+/** A lazy component that can also be fetched ahead of being rendered. */
+export declare type PreloadableLazy<T extends ComponentType<unknown>> = ReturnType<typeof lazy<T>> & {
+    /**
+     * Start fetching the chunk now, before anything renders it.
+     *
+     * Call it on the interaction that makes the route likely — hovering the
+     * link, opening the menu that holds it, finishing the step before it — so
+     * the chunk is warm by the time the user commits and the suspense fallback
+     * never appears.
+     *
+     * Shares its work with the render path: whichever fires first performs the
+     * single fetch and the other awaits the same promise. Safe to call
+     * repeatedly.
+     *
+     * @returns The module, once loaded. Rejects when every retry failed; that
+     *   rejection is already handled internally, so a fire-and-forget call
+     *   never surfaces as an unhandled rejection.
+     */
+    preload: () => Promise<{
+        default: T;
+    }>;
+};
+
 /** A model whose cached size should appear in the report. */
 export declare interface ProfiledModel {
     /** Label for the report row, e.g. `"detector"`. */
@@ -8475,7 +9083,12 @@ export declare type QRMode = "numeric" | "alphanumeric" | "byte";
 
 /**
  * Wrapper around `QueryClientProvider` that bootstraps a `QueryClient` with
- * sane SDK defaults (5-minute stale time, 30-minute gc time, 1 retry).
+ * sane SDK defaults (5-minute stale time, 30-minute gc time, one retry for
+ * failures worth replaying).
+ *
+ * Retries follow {@link shouldRetryQuery} rather than a flat count: a 4xx other
+ * than 408/429 is the server refusing on purpose, and replaying it only doubles
+ * the network log while the spinner keeps turning.
  */
 export declare function QueryProvider({ children, client, defaultOptions }: QueryProviderProps): JSX.Element;
 
@@ -9441,6 +10054,46 @@ export declare interface SequentialScaleOptions {
  */
 export declare function setAudioOutput(element: HTMLMediaElement | null, sinkId: string): Promise<boolean>;
 
+/** Imperative handle over a pool of short sound effects. */
+export declare interface SfxPool {
+    /** Play a clip, allocating and caching its element on first use. */
+    play: (src: string, options?: PlaySfxOptions) => void;
+    /** Fetch clips ahead of the first play, so it is not silent while the file downloads. */
+    preload: (src: string | string[]) => void;
+    /** Set the master volume, applying it to anything already sounding. */
+    setVolume: (volume: number) => void;
+    /** Stop one source, or every source when called with no argument. */
+    stop: (src?: string) => void;
+    /** Release every element. Call on unmount. */
+    dispose: () => void;
+}
+
+/** Options for {@link createSfxPool}. */
+export declare interface SfxPoolOptions {
+    /**
+     * Master volume, `0`–`1`, multiplied into every per-play volume. Default
+     * `1`. Wire it to the app's sound setting so one value governs the lot.
+     */
+    volume?: number;
+    /**
+     * Prefix applied to sources that are not absolute URLs — typically Vite's
+     * `import.meta.env.BASE_URL`, so a build served from a subpath resolves.
+     * Default `""`.
+     */
+    baseUrl?: string;
+    /**
+     * Elements kept per source. `1` (the default) restarts the clip on every
+     * play, which is what a menu blip wants. Raise it to let a sound overlap
+     * itself — a hit landing while the previous one is still ringing.
+     */
+    voices?: number;
+    /**
+     * Maximum number of distinct sources held. When exceeded, the least
+     * recently played source is released. Default `48`.
+     */
+    maxSources?: number;
+}
+
 /**
  * Wrap the Web Share API with a uniform result object. Falls through to
  * `unsupported: true` when the browser lacks `navigator.share`, leaving the
@@ -9493,6 +10146,25 @@ export declare interface ShareResult {
     error?: unknown;
 }
 
+/**
+ * Default `retry` for SDK queries: replay transport and server failures, never a
+ * deliberate client-side refusal.
+ *
+ * A flat `retry: 1` replays a 403 on an admin-only listing and a 404 for a record
+ * somebody deleted. The server meant both — the second attempt returns the same
+ * answer, doubles the network log and holds the spinner on screen for the length
+ * of another round trip. A network failure or a 5xx is a different thing: it may
+ * well succeed on the next try, so those keep the previous behaviour.
+ *
+ * @example
+ * new QueryClient({ defaultOptions: { queries: { retry: shouldRetryQuery } } });
+ *
+ * @param failureCount - Attempts already made, as react-query counts them.
+ * @param error - The rejection value from the query function.
+ * @returns Whether react-query should try again.
+ */
+export declare function shouldRetryQuery(failureCount: number, error: unknown): boolean;
+
 /**
  * Conditionally render children based on the viewport breakpoint.
  *
@@ -10642,6 +11314,28 @@ export declare interface ToastProviderProps {
 
 export declare type ToastVariant = "success" | "warning" | "error" | "info";
 
+/**
+ * Serialize rows to CSV text, RFC 4180 style.
+ *
+ * Rows are separated by `\r\n` — the RFC's terminator and the one Excel is least
+ * surprised by. A row is emitted for the header even when `rows` is empty, so the
+ * person who opens the file sees which columns they asked for instead of a blank
+ * document.
+ *
+ * @example
+ * const csv = toCsv(users, [
+ *     { key: "name", header: "Nome" },
+ *     { key: "email", header: "E-mail" },
+ *     { key: "plan", header: "Plano", csv: (user) => user.plan.label },
+ * ]);
+ *
+ * @param rows - The rows to export.
+ * @param columns - Columns, in the order they should appear.
+ * @param options - Delimiter and BOM.
+ * @returns The complete file contents.
+ */
+export declare function toCsv<T>(rows: readonly T[], columns: readonly CsvColumn<T>[], options?: CsvOptions): string;
+
 /**
  * A pressable two-state button — like a checkbox styled as a button.
  *
@@ -11598,6 +12292,41 @@ export declare interface UseClipboardResult {
     reset: () => void;
 }
 
+/**
+ * Counts down the time left on a window that started at a known instant.
+ *
+ * Written around a timestamp rather than a decrementing counter on purpose: the
+ * remaining time is recomputed from `Date.now()` on every tick, so a throttled
+ * background tab, a slow frame or a `setInterval` that drifts cannot make the
+ * countdown disagree with the clock. Remounting recovers the correct value too,
+ * which a counter held in state cannot do.
+ *
+ * The interval stops once it reaches zero instead of ticking forever behind a
+ * clamp.
+ *
+ * @param durationMs - Length of the window.
+ * @param startedAt - Epoch ms the window opened (`Date.now()` when it started).
+ * @param options - Tick cadence.
+ * @returns Milliseconds remaining, never below `0`.
+ *
+ * @example
+ * const remaining = useCountdown(60_000, lastSentAt);
+ *
+ * <button disabled={remaining > 0}>
+ *   {remaining > 0 ? `Reenviar em ${Math.ceil(remaining / 1000)}s` : "Reenviar código"}
+ * </button>
+ */
+export declare function useCountdown(durationMs: number, startedAt: number, options?: UseCountdownOptions): number;
+
+/** Options for {@link useCountdown}. */
+export declare interface UseCountdownOptions {
+    /**
+     * How often the remaining time is recomputed, in ms. Default `1000`, which
+     * suits a "try again in 3s" label; drop it to ~50 to drive a progress bar.
+     */
+    tickMs?: number;
+}
+
 /**
  * Numeric counter clamped to an optional `[min, max]` range.
  *
@@ -11712,6 +12441,31 @@ export declare function useDelete<T>(resource: string, options?: UseDeleteOption
 /** Options for the delete mutation (mutationFn + onSuccess are provided). */
 export declare type UseDeleteOptions<T> = Omit<UseMutationOptions<T, Error, string | number>, "mutationFn">;
 
+/**
+ * {@link describeApiError} with its fixed sentences resolved through the active
+ * `I18nProvider`.
+ *
+ * The funnel is not duplicated — this hook only supplies the strings and calls
+ * the pure function. Which is also why both exist: the pure one runs in an
+ * interceptor or a logger, where there is no React tree to read a context from,
+ * and this one runs in a component without every caller passing translations
+ * down by hand.
+ *
+ * Works with no provider at all: i18n is opt-in in this SDK, so a missing
+ * provider — or a catalog that never defined `tempest.error.offline` — falls
+ * back to the pt-BR default rather than crashing or printing the raw key.
+ *
+ * @example
+ * const describe = useDescribeApiError();
+ * const { mutate } = useMutation({
+ *     mutationFn: save,
+ *     onError: (error) => toast(describe(error, t("orders.saveFailed"))),
+ * });
+ *
+ * @returns A stable `(error, fallback) => string` function.
+ */
+export declare function useDescribeApiError(): (error: unknown, fallback: string) => string;
+
 /**
  * Manage open/closed boolean state with stable `open`/`close`/`toggle` handlers.
  *
@@ -12011,6 +12765,40 @@ export declare interface UseKeyboardShortcutOptions {
     ignoreInput?: boolean;
 }
 
+/**
+ * Keeps a ref pointing at the most recent value it was given.
+ *
+ * The escape hatch for reading fresh state inside something that must not be
+ * re-created when that state changes: an interval, a subscription, an event
+ * listener registered once on mount. Listing the value in the effect's
+ * dependencies would tear the effect down and set it back up on every change;
+ * omitting it captures the value from the render that created the closure and
+ * never sees another. The ref is neither — a stable object whose `current` is
+ * always current.
+ *
+ * The assignment happens **during render**, for the same reason
+ * {@link useStableCallback} does it: moving it into an effect opens a
+ * one-commit staleness window, where an effect declared earlier in the same
+ * commit reads the previous render's value.
+ *
+ * Reach for {@link useStableCallback} instead when the value is a function you
+ * want to *call* — it hands back a callable with a stable identity, rather than
+ * making every call site reach through `.current`.
+ *
+ * @typeParam T - The tracked value.
+ * @param value - The value to track. Written on every render.
+ * @returns A stable ref whose `current` holds the latest `value`.
+ *
+ * @example
+ * const optionsRef = useLatestRef(options);
+ *
+ * useEffect(() => {
+ *   const id = setInterval(() => poll(optionsRef.current), 5_000);
+ *   return () => clearInterval(id);
+ * }, []); // the interval survives every options change, and still reads the latest
+ */
+export declare function useLatestRef<T>(value: T): RefObject<T>;
+
 /**
  * Query a paginated list of a resource through the active {@link useDataProvider}.
  *
@@ -12609,6 +13397,18 @@ export declare interface UseOnlineOptions {
     timeoutMs?: number;
 }
 
+/**
+ * Access translation helpers when there may be no {@link I18nProvider} above.
+ *
+ * Returns `null` instead of throwing, which is what a piece of the SDK needs
+ * when it wants to be translated where a catalog exists and still work where one
+ * does not — i18n is opt-in in this SDK, and a helper that demanded a provider
+ * would turn "you did not configure translations" into a crash.
+ *
+ * @returns The context value, or `null` outside a provider.
+ */
+export declare function useOptionalI18n(): I18nContextValue | null;
+
 /**
  * Offset-pagination hook over TanStack Query for the fastapi-pagination /
  * Tempest envelope (`{ items, total, page, size, pages }`).
@@ -13187,6 +13987,30 @@ export declare interface UseSetResult<T> {
     size: number;
 }
 
+/**
+ * Component-scoped {@link createSfxPool}, with the lifecycle wired up.
+ *
+ * The pool is created once — through a lazy `useState` initializer, so no
+ * element is allocated on a render that gets discarded — and disposed on
+ * unmount, so its elements do not outlive the screen that owns them.
+ *
+ * `volume` is tracked separately: changing it calls `setVolume` on the existing
+ * pool rather than rebuilding it, which would throw away every clip the user
+ * has already downloaded — exactly the cost the pool exists to avoid.
+ * `baseUrl`, `voices` and `maxSources` are read once, at creation.
+ *
+ * @param options - Passed through to {@link createSfxPool}.
+ * @returns A stable pool handle.
+ *
+ * @example
+ * const sfx = useSfxPool({ volume: settings.sfxVolume / 100, baseUrl: import.meta.env.BASE_URL });
+ *
+ * useEffect(() => { sfx.preload(["sfx/select.mp3", "sfx/back.mp3"]); }, [sfx]);
+ *
+ * <button onClick={() => sfx.play("sfx/select.mp3")}>Confirmar</button>
+ */
+export declare function useSfxPool(options?: SfxPoolOptions): SfxPool;
+
 /**
  * Drag-to-reorder for a list, with a **keyboard path of equal standing**.
  *
@@ -13537,6 +14361,39 @@ export declare interface UseTorchResult {
  */
 export declare function useTranslate(): I18nContextValue["t"];
 
+/**
+ * Reveals a string one character at a time.
+ *
+ * Changing `text` restarts the reveal. The reset happens during render rather
+ * than in an effect, so the new string never flashes in full for one frame
+ * before the animation takes over.
+ *
+ * Always give the reader a way out: an animation that cannot be skipped is a
+ * tax on anyone re-reading or moving fast, which is what `skip` is for.
+ *
+ * @param text - The full string to reveal. Nullish is treated as empty.
+ * @param speedMs - Delay between characters. `0` or less renders instantly,
+ *   which is the hook-safe way to honour `prefers-reduced-motion`.
+ * @returns The revealed prefix, whether it finished, and a `skip` action.
+ *
+ * @example
+ * const reduced = useMediaQuery("(prefers-reduced-motion: reduce)");
+ * const { displayedText, isComplete, skip } = useTypewriter(line, reduced ? 0 : 30);
+ *
+ * return <p onClick={skip}>{displayedText}{isComplete ? "" : "▌"}</p>;
+ */
+export declare function useTypewriter(text: string, speedMs: number): UseTypewriterResult;
+
+/** State returned by {@link useTypewriter}. */
+export declare interface UseTypewriterResult {
+    /** The prefix of `text` revealed so far. */
+    displayedText: string;
+    /** `true` once the whole string is on screen. */
+    isComplete: boolean;
+    /** Reveal the rest immediately — wire it to a tap or a key press. */
+    skip: () => void;
+}
+
 /**
  * Update a record and invalidate both the list and the single-record caches.
  *