tempest-react-sdk 0.47.0 → 0.49.0

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

@@ -553,6 +553,12 @@ declare type AnyEventTarget = EventTarget | {
  */
 export declare const API_ERROR_OFFLINE_KEY = "tempest.error.offline";
 
+/**
+ * Translation key for the validation sentence, looked up the same way as
+ * {@link API_ERROR_OFFLINE_KEY}.
+ */
+export declare const API_ERROR_VALIDATION_KEY = "tempest.error.validation";
+
 export declare interface ApiClient {
     request<T>(path: string, options?: RequestOptions): Promise<T>;
     get<T>(path: string, options?: RequestOptions): Promise<T>;
@@ -680,14 +686,32 @@ export declare interface ApiError {
      * header (commonly on `429`/`503`). Honored by {@link retry}.
      */
     retryAfter?: number;
+    /**
+     * Field-level messages from a validation response, keyed by the field path
+     * the backend named (`"email"`, `"items.0.price"`).
+     *
+     * Present only when the body carried a validation list — a FastAPI `422`
+     * answers with `detail: [{ loc, msg, type }]`. This is the shape a form
+     * needs: `detail` is one line for a log or a developer, and pulling the
+     * fields back out of it means parsing prose. The first message wins when a
+     * field appears twice, because a field shows one error at a time.
+     */
+    fields?: Record<string, string>;
     /** The raw parsed error body, when available. */
     body?: unknown;
 }
 
-/** The two fixed sentences {@link describeApiError} may need. */
+/** The fixed sentences {@link describeApiError} may need. */
 export declare interface ApiErrorStrings {
     /** Shown when the request never reached the server. */
     offline: string;
+    /**
+     * Shown when the backend rejected the payload field by field.
+     *
+     * The per-field messages are on `error.fields`, to be attached to the inputs
+     * themselves; this sentence is what the toast says.
+     */
+    validation: string;
 }
 
 /**
@@ -782,6 +806,12 @@ export declare type AppBarTone = "surface" | "primary" | "transparent";
  * @example
  * const visible = applyFilters(orders, filters);
  *
+ * Each filter's values are normalised once, before the scan, rather than inside
+ * the per-row predicate: the arity, the `between` ordering and the value array
+ * depend only on the filter, so deriving them per row multiplied that work by
+ * the row count. `empty`/`notEmpty` ignore their values entirely, which is why
+ * the prepared shape does not need to distinguish them.
+ *
  * @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.
@@ -1480,6 +1510,15 @@ export declare interface BarcodeScanResult {
  * 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.
  *
+ * Colors come from {@link useChartColors}, the same resolver every chart in the
+ * SDK uses, so a theme that declares fewer series than the eight
+ * `--tempest-chart-*` slots cycles within its own palette. Reading the tokens
+ * through CSS `var()` could not do that: the count lives in
+ * `--tempest-chart-count`, which CSS cannot use as a modulus, so a six-color
+ * brand palette got the SDK's leftover defaults in rows seven and eight — the
+ * exact regression that token exists to prevent. `palette.ts` imports nothing,
+ * so this pulls no chart library into the slice.
+ *
  * @example
  * <BarList
  *     items={[{ label: "Free", value: 128 }, { label: "Pro", value: 32 }]}
@@ -1547,6 +1586,9 @@ export declare type BarListSort = "desc" | "asc" | "none";
  * `atob` and losing the last byte — is the classic broken-WebAuthn bug, which is
  * why the SDK owns it instead of leaving it to each app.
  *
+ * This is the WebAuthn-facing name for {@link base64ToBytes}; the codec itself is
+ * shared, so the padding rule has one implementation rather than three.
+ *
  * @param value - Base64url text, with or without `=` padding.
  * @returns The decoded bytes.
  */
@@ -1846,6 +1888,9 @@ export declare type ButtonVariant = "primary" | "secondary" | "danger" | "succes
 /**
  * Encode bytes as an unpadded base64url string.
  *
+ * Normalises `ArrayBuffer` to a view — which is what the WebAuthn response
+ * fields hand over — and delegates the encoding to {@link bytesToBase64}.
+ *
  * @param value - Bytes to encode, as a view or a raw buffer.
  * @returns Base64url text, safe to put in JSON and in a URL.
  */
@@ -2583,33 +2628,17 @@ 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.
+ * {@link createJsonStorage} with {@link compressedStorageCodec}, so it is the
+ * same implementation as {@link storage} and genuinely interchangeable with it —
+ * `get`, `set` and `remove`, differing only in how the value is encoded. It used
+ * to be a hand-written copy that had no `remove`, which made that promise false
+ * for anybody who took the docstring at its word.
+ *
+ * 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.
  */
-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;
-};
+export declare const compressedStorage: JsonStorage;
 
 /**
  * Codec pair for {@link useLocalStorage}, so a compressed key gets the hook's
@@ -2618,10 +2647,7 @@ export declare const compressedStorage: {
  * @example
  * const [save, setSave] = useLocalStorage("save", EMPTY_SAVE, compressedStorageCodec);
  */
-export declare const compressedStorageCodec: {
-    serialize: typeof compressToString;
-    deserialize: typeof decompressFromString;
-};
+export declare const compressedStorageCodec: StorageCodec;
 
 /**
  * Serialize a value to a gzipped, base64 string carrying the format marker.
@@ -3036,6 +3062,10 @@ export declare interface CreateGrowthBookFeatureFlagsAdapterOptions {
  * });
  * i18n.t("greet", { name: "Mau" });          // "Olá, Mau"
  * i18n.plural("alos", 3);                     // "3 Alôs"
+ *
+ * @example
+ * // A key the catalog does not define, with text to show instead of the key.
+ * i18n.t("cart.empty", undefined, { default: "Seu carrinho está vazio" });
  */
 export declare function createI18n(options: CreateI18nOptions): I18n;
 
@@ -3096,6 +3126,34 @@ export declare function createInMemoryFlags(options?: InMemoryFlagsOptions): Fea
     set: (key: string, value: FlagValue) => void;
 };
 
+/**
+ * Build a typed `localStorage` wrapper around a codec.
+ *
+ * One implementation behind every store the SDK ships, so they cannot drift in
+ * surface. {@link storage} and {@link compressedStorage} are both this function —
+ * before it, the compressed one was a hand-written copy of the same guards and
+ * had no `remove`, while its own docstring promised the two were interchangeable
+ * at the call site. They were not, and the promise failed exactly where somebody
+ * followed it.
+ *
+ * @example
+ * const session = createJsonStorage();
+ * session.set("draft", { title: "Sem título" });
+ *
+ * @example
+ * const packed = createJsonStorage(compressedStorageCodec);
+ *
+ * @param codec - Encoder pair. Defaults to plain JSON.
+ * @returns A store with `get` / `set` / `remove`.
+ *
+ * @tempest-limits empty-catch — every method is best-effort by contract:
+ * `localStorage` throws on quota exhaustion, in Safari private mode, and when a
+ * cross-origin frame has storage blocked. A caller persisting a preference has no
+ * recovery to run and no user-facing message to show, so the write is dropped and
+ * the app keeps the value in memory for the session.
+ */
+export declare function createJsonStorage(codec?: StorageCodec): JsonStorage;
+
 /**
  * Build a [[FeatureFlagsAdapter]] backed by a LaunchDarkly JS client. Apps
  * initialise the client themselves (`LDClient.initialize(envKey, ctx)`) and
@@ -3606,34 +3664,6 @@ 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;
 
 /**
@@ -4135,6 +4165,64 @@ export declare interface DataProviderOptions {
  */
 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;
 
+/** Everything a table needs regardless of who owns paging, sorting and searching. */
+export declare interface DataTableBaseProps<T> extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * 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>[];
+    /** Rows per page. Default 10. */
+    pageSize?: number;
+    /** Render a search input above the table. Default false. */
+    searchable?: boolean;
+    /**
+     * Keys to match the search term against. When omitted, every column whose
+     * value is a string or number is searched.
+     */
+    searchKeys?: (keyof T)[];
+    /** Initial sort applied before any header interaction. */
+    initialSort?: DataTableSort<T>;
+    /** Stable key extractor for rows. Defaults to the row index. */
+    rowKey?: (row: T, index: number) => string | number;
+    /** Content shown when no rows match. */
+    emptyMessage?: ReactNode;
+    /**
+     * Persist an accepted cell edit. Return a promise: while it is pending the cell
+     * already shows the new value, and a rejection rolls that back and surfaces the
+     * error in the cell. Without this prop no column is editable.
+     */
+    onCellChange?: (change: DataTableCellChange<T>) => void | Promise<void>;
+    /** Override the PT-BR copy of the editing affordances. */
+    editLabels?: Partial<DataTableEditLabels>;
+    /**
+     * 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;
+}
+
 /** One accepted cell edit, handed to `onCellChange`. */
 export declare interface DataTableCellChange<T> {
     /** The row as it was before the edit. */
@@ -4212,40 +4300,24 @@ export declare interface DataTableEditLabels {
 /** Input types an editable column can use. */
 export declare type DataTableEditorType = "text" | "number" | "date" | "email" | "tel" | "url";
 
-export declare interface DataTableProps<T> extends HTMLAttributes<HTMLDivElement> {
-    /**
-     * 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>[];
-    /** Rows per page. Default 10. */
-    pageSize?: number;
-    /** Render a search input above the table. Default false. */
-    searchable?: boolean;
-    /**
-     * Keys to match the search term against. When omitted, every column whose
-     * value is a string or number is searched.
-     */
-    searchKeys?: (keyof T)[];
-    /** Initial sort applied before any header interaction. */
-    initialSort?: DataTableSort<T>;
-    /** Stable key extractor for rows. Defaults to the row index. */
-    rowKey?: (row: T, index: number) => string | number;
-    /** Content shown when no rows match. */
-    emptyMessage?: ReactNode;
-    /**
-     * Persist an accepted cell edit. Return a promise: while it is pending the cell
-     * already shows the new value, and a rejection rolls that back and surfaces the
-     * error in the cell. Without this prop no column is editable.
-     */
-    onCellChange?: (change: DataTableCellChange<T>) => void | Promise<void>;
-    /** Override the PT-BR copy of the editing affordances. */
-    editLabels?: Partial<DataTableEditLabels>;
+/**
+ * Paging, as one of the three shapes that actually work.
+ *
+ * These used to be three optional props, so the compiler accepted
+ * `totalItems` with no `page` — a table whose pager moves an internal page while
+ * `data` keeps showing page one. Every prop was optional on its own, so the only
+ * place left to catch it was a `console.warn` in dev, in the browser, with the
+ * component mounted. As a union the same mistake is a build error at the call
+ * site, for free, everywhere.
+ */
+export declare type DataTablePagingProps = {
+    /** Not server mode. */
+    totalItems?: never;
+    /** The table owns the page. */
+    page?: never;
+    /** Nothing to report to. */
+    onPageChange?: never;
+} | {
     /**
      * Total row count across every page — the `total` of a paginated envelope.
      *
@@ -4255,49 +4327,64 @@ export declare interface DataTableProps<T> extends HTMLAttributes<HTMLDivElement
      * (see `manualSort` / `manualSearch`, which are implied here). Pair it with
      * `page` and `onPageChange`.
      */
-    totalItems?: number;
+    totalItems?: never;
     /** Current page, 1-based. Controlled — required in server mode. */
-    page?: number;
+    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;
+    onPageChange: (page: number) => void;
+} | {
     /**
-     * A fetch is in flight.
+     * Total row count across every page — the `total` of a paginated envelope.
      *
-     * 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.
+     * 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). `page` and
+     * `onPageChange` come with it — the type says so, because a server-mode
+     * table without them silently shows page one forever.
      */
-    loading?: boolean;
-}
+    totalItems: number;
+    /** Current page, 1-based. Controlled, and required in server mode. */
+    page: number;
+    /** Called with the next page. */
+    onPageChange: (page: number) => void;
+};
+
+/**
+ * The table's props: the shared half, plus one valid paging shape and one valid
+ * sorting shape.
+ */
+export declare type DataTableProps<T> = DataTableBaseProps<T> & DataTablePagingProps & DataTableSortProps<T>;
 
 export declare interface DataTableSort<T> {
     key: keyof T;
     direction: SortDirection;
 }
 
+/**
+ * Sorting: delegated, and therefore reported, or neither.
+ *
+ * `manualSort` without `onSortChange` renders a header that moves its arrow and
+ * changes nothing else — the arrow is a lie the compiler can now catch.
+ */
+export declare type DataTableSortProps<T> = {
+    /** The table sorts the rows it has. */
+    manualSort?: false;
+    /** Called with the next sort state — `null` when the header cycles back to unsorted. */
+    onSortChange?: (sort: DataTableSort<T> | null) => 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: true;
+    /** Where the click goes. Required, since nothing else acts on it. */
+    onSortChange: (sort: DataTableSort<T> | null) => void;
+};
+
 /**
  * Thin wrapper around the native `<input type="date">` (or `datetime-local`,
  * `time`, `month`). For richer pickers, pair with `react-datepicker` directly
@@ -4507,9 +4594,16 @@ export declare function defineRoutes(routes: TempestRouteObject[]): TempestRoute
  *    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
+ * 2. A validation rejection — `error.fields` is set — produces the validation
+ *    sentence, **not** `detail`. On a `422` the `detail` line is assembled from
+ *    the backend's field paths and the validator's own wording
+ *    (`"items.0.price: Input should be greater than 0"`), which is right for a
+ *    log and wrong for a person: it is half English in a pt-BR screen and it
+ *    names internals. The per-field messages stay on `fields`, where a form can
+ *    attach them to the inputs that failed.
+ * 3. 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
+ * 4. `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
@@ -5184,15 +5278,55 @@ export declare function filtersFromSearchParams(params: URLSearchParams, fields:
  *   will not answer an `empty` filter, while {@link applyFilters} treats blank
  *   text as empty.
  *
+ * The defaults are that dialect, not a universal truth. A backend that names its
+ * substring column something other than `name`, or that spells its operators
+ * differently, passes `options` — the alternative was an encoder whose special
+ * cases were a wall for anyone not on the Tempest stack.
+ *
  * @example
  * const params = filtersToQueryParams(filters);
  * params.set("page", String(page));
  * const data = await api.get(`/orders?${params}`);
  *
+ * @example
+ * // A backend whose searchable column is `razao_social` and that spells `ne`
+ * // the Django way.
+ * const params = filtersToQueryParams(filters, {
+ *     substringColumns: ["razao_social"],
+ *     operatorSuffix: { ne: "__exclude" },
+ * });
+ *
  * @param filters - Applied filters; incomplete ones are ignored.
+ * @param options - Dialect overrides. Defaults to the `tempest-fastapi-sdk` one.
  * @returns Params ready to append to a request URL.
  */
-export declare function filtersToQueryParams(filters: readonly Filter[]): URLSearchParams;
+export declare function filtersToQueryParams(filters: readonly Filter[], options?: FiltersToQueryParamsOptions): URLSearchParams;
+
+/** Overrides for the backend dialect {@link filtersToQueryParams} encodes into. */
+export declare interface FiltersToQueryParamsOptions {
+    /**
+     * Columns whose `eq` is emitted as `<column>__iexact` rather than as the bare
+     * column name. Default `["name"]`, which is what `build_filter_condition`
+     * special-cases.
+     *
+     * Pass the columns **your** backend treats that way — `nome`, `titulo`,
+     * `razao_social` — or `[]` when it treats none of them specially and a bare
+     * `eq` should stay bare.
+     */
+    substringColumns?: readonly string[];
+    /**
+     * Operator suffixes, merged over the `tempest-fastapi-sdk` dialect, so an
+     * override names only the operators that differ.
+     *
+     * @example
+     * // A DRF-style backend
+     * filtersToQueryParams(filters, {
+     *     substringColumns: [],
+     *     operatorSuffix: { contains: "__icontains", ne: "__exclude" },
+     * });
+     */
+    operatorSuffix?: Partial<Record<FilterOperator, string>>;
+}
 
 /**
  * Serialize filters into URL search params.
@@ -5883,14 +6017,16 @@ export declare interface I18n {
     fallbackLocale: string | null;
     /**
      * Translate `key`, interpolating `{name}` placeholders from `params`.
-     * Falls back to the configured fallback locale, then to the key itself.
+     * Falls back to the configured fallback locale, then to `options.default`,
+     * then to the key itself.
      */
-    t: (key: string, params?: InterpolationValues) => string;
+    t: (key: string, params?: InterpolationValues, options?: TranslateOptions) => string;
     /**
      * Plural-aware translation. Tries `${key}_one` for `count === 1` and
      * `${key}_other` otherwise, with `{count}` available for interpolation.
+     * Falls back to `options.default`, then to the key itself.
      */
-    plural: (key: string, count: number, params?: InterpolationValues) => string;
+    plural: (key: string, count: number, params?: InterpolationValues, options?: TranslateOptions) => string;
     /** Format a number using `Intl.NumberFormat` on the active locale. */
     formatNumber: (value: number, options?: Intl.NumberFormatOptions) => string;
     /** Format a Date using `Intl.DateTimeFormat` on the active locale. */
@@ -6424,42 +6560,6 @@ export declare function isCursorPage<T = unknown>(value: unknown): value is Curs
  */
 export declare function isDefined<T>(value: T | null | undefined): value is T;
 
-/**
- * Whether the consuming app was built for development.
- *
- * Reads `process.env.NODE_ENV`, which every supported bundler (Vite, webpack,
- * Rspack, Parcel) replaces with a literal **while building the app**. That
- * timing is the whole point: `import.meta.env.DEV` looks equivalent and is not,
- * because Vite replaces it while building *this package*, so a published
- * artifact carries the constant `false` and every guard behind it becomes dead
- * code the app's own dev server can no longer switch on.
- *
- * The expression is written out in full, and the failure is caught rather than
- * guarded against. A `typeof process === "undefined"` check would read as the
- * careful version and quietly reintroduce the bug: bundlers substitute the
- * member expression `process.env.NODE_ENV` and nothing else, so in a browser —
- * where the identifier `process` does not exist — the guard would return early
- * while the literal right after it had already been replaced with
- * `"development"`.
- *
- * Returns `false` when the read throws, which is the environment that defines
- * neither symbol: a raw service-worker context, a plain
- * `<script type="module">`, a bundler substituting nothing. Staying quiet there
- * is deliberate — a dev-only warning that cannot prove it is in development is
- * better silent than shouting in someone's production console.
- *
- * @returns Whether development-only diagnostics should run.
- *
- * @example
- * if (isDevBuild()) console.warn("[my-app] this prop combination does nothing");
- *
- * @tempest-limits empty-catch — the only thing the read can throw is the
- * environment answering "not defined", which is the return value, not an error
- * worth reporting. Logging it would print on every call in exactly the context
- * that has nowhere to print.
- */
-export declare function isDevBuild(): boolean;
-
 /**
  * Check whether a value is considered "empty".
  *
@@ -6568,6 +6668,31 @@ export declare function isPlatformAuthenticatorAvailable(): Promise<boolean>;
  */
 export declare function isPushSupported(): boolean;
 
+/**
+ * Whether an HTTP status describes a condition a replay can plausibly fix.
+ *
+ * The single owner of that decision. It used to be spelled out in three places —
+ * the client's own policy, the react-query default and the bare `retry()` helper
+ * — and they had already drifted: the query default was missing `425`, so the
+ * same `425 Too Early` was replayed through `createApiClient({ retry: true })`
+ * and not replayed through `useQuery`. Same app, same error, two behaviours, and
+ * no test caught it because each file asserted against its own copy.
+ *
+ * Deliberately about the status and nothing else. Whether a *non*-API error is
+ * worth replaying, and whether the request's method may be replayed at all, are
+ * the caller's calls: {@link createApiClient} refuses a non-idempotent method,
+ * while a bare `retry()` has no method to inspect.
+ *
+ * @example
+ * await api.get("/report", {
+ *     retry: { shouldRetry: (error) => isApiError(error) && isRetriableStatus(error.status) },
+ * });
+ *
+ * @param status - The HTTP status, where `0` means the request never landed.
+ * @returns Whether a retry is worth attempting.
+ */
+export declare function isRetriableStatus(status: number): boolean;
+
 /** Whether `getDisplayMedia` is reachable at all. */
 export declare function isScreenCaptureSupported(): boolean;
 
@@ -6604,6 +6729,33 @@ export declare function isValidLongitude(value: number): boolean;
 /** Whether `MediaRecorder` exists and can produce at least one video container. */
 export declare function isVideoRecordingSupported(): boolean;
 
+/** The surface every store built by {@link createJsonStorage} exposes. */
+export declare interface JsonStorage {
+    /**
+     * Read and decode 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;
+    /**
+     * Encode and write a key.
+     *
+     * @typeParam T - The value being stored.
+     * @param key - Storage key.
+     * @param value - Any value the codec can represent.
+     */
+    set<T>(key: string, value: T): void;
+    /**
+     * Delete a key.
+     *
+     * @param key - Storage key.
+     */
+    remove(key: string): void;
+}
+
 /**
  * Kanban board: columns of cards, reorderable within a column and movable across
  * columns, by pointer **or** keyboard.
@@ -9708,7 +9860,12 @@ export declare interface RetryOptions {
     respectRetryAfter?: boolean;
     /**
      * Return false to stop retrying for a specific error.
-     * Default: retry on any thrown error.
+     *
+     * Default: replay anything that is not a recognisable API error — a
+     * transport failure has no status to judge — and, for one that is, only the
+     * statuses {@link isRetriableStatus} accepts. A `403` on an admin-only
+     * endpoint and a `404` for a deleted record are the server's final answer;
+     * repeating them spends the caller's time to show the same error twice.
      */
     shouldRetry?: (error: unknown, attempt: number) => boolean;
     /** Called before each retry with the upcoming delay. */
@@ -10226,6 +10383,11 @@ export declare interface ShareResult {
  * 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.
  *
+ * The status list is {@link isRetriableStatus}, shared with the client's own
+ * policy. It used to be a second copy here, and the copy was missing `425` — so
+ * a `425 Too Early` was replayed by `createApiClient({ retry: true })` and not
+ * by a query, for the same error in the same app.
+ *
  * @example
  * new QueryClient({ defaultOptions: { queries: { retry: shouldRetryQuery } } });
  *
@@ -10261,6 +10423,12 @@ export declare interface ShowProps {
  * Desktop sidebar navigation. Pair with `<Show above="md">` and a `Drawer`
  * for mobile.
  *
+ * Sixteen screens in one flat list is a wall, so `items` also takes section
+ * headings and separators. A section renders as a labelled `role="group"`, which
+ * is what tells a screen reader "Monitoring, group, 3 items" — the reason it is
+ * not a styled `disabled` item, which would announce an unavailable button and
+ * stay in the navigation order.
+ *
  * @example
  * const [tab, setTab] = useState("home");
  * <Show above="md">
@@ -10271,23 +10439,59 @@ export declare interface ShowProps {
  *         onChange={setTab}
  *     />
  * </Show>
+ *
+ * @example
+ * <Sidebar
+ *     items={[
+ *         { type: "section", key: "monitoring", label: "Monitoring" },
+ *         { key: "overview", label: "Overview", href: "/overview" },
+ *         { key: "activity", label: "Activity", href: "/activity" },
+ *         { type: "section", key: "admin", label: "Administration" },
+ *         { key: "settings", label: "Settings", href: "/settings" },
+ *     ]}
+ *     value={tab}
+ *     onChange={setTab}
+ * />
  */
 export declare function Sidebar({ header, items, value, onChange, footer, collapsed, width, collapsedWidth, className, style, ...props }: SidebarProps): JSX.Element;
 
+/**
+ * One entry of the navigation list.
+ *
+ * An entry with no `type` is an item, which is what keeps a plain
+ * `SidebarItem[]` a valid `SidebarEntry[]`: adding sections to this component
+ * needed no change at any existing call site.
+ */
+export declare type SidebarEntry = ({
+    type?: "item";
+} & SidebarItem) | SidebarSection | SidebarSeparator;
+
 export declare interface SidebarItem {
     key: string;
     label: ReactNode;
     icon?: ReactNode;
     badge?: ReactNode;
     disabled?: boolean;
+    /**
+     * Renders the entry as a link to this URL instead of a button.
+     *
+     * `onChange` still fires on click, so an app that tracks the active key keeps
+     * working — the difference is that the entry now behaves like navigation:
+     * middle-click, ctrl-click and "copy link address" do what the user expects,
+     * and a screen reader announces a link rather than a button.
+     *
+     * A `disabled` entry ignores this and stays a `<button disabled>`: there is no
+     * disabled state for an anchor, and dropping the `href` to fake one leaves a
+     * link that announces itself as actionable and is not.
+     */
     href?: string;
 }
 
 export declare interface SidebarProps extends Omit<HTMLAttributes<HTMLElement>, "onChange"> {
     /** Top slot — typically the logo + brand. */
     header?: ReactNode;
-    /** Navigation items. */
-    items: SidebarItem[];
+    /** Navigation entries. An entry with no `type` is an item. */
+    items: SidebarEntry[];
     /** Active item key. */
     value?: string;
     /** Fires when an item is clicked. Receives the item's `key`. */
@@ -10302,6 +10506,22 @@ export declare interface SidebarProps extends Omit<HTMLAttributes<HTMLElement>,
     collapsedWidth?: number | string;
 }
 
+/**
+ * A section heading. Every item after it belongs to the section, until the next
+ * section or separator.
+ */
+export declare interface SidebarSection {
+    type: "section";
+    key: string;
+    label: ReactNode;
+}
+
+/** A plain divider, for splitting the list without naming the parts. */
+export declare interface SidebarSeparator {
+    type: "separator";
+    key: string;
+}
+
 /**
  * Signature capture on a canvas — the "sign here" field of a delivery receipt,
  * a service order, a term of acceptance.
@@ -10757,20 +10977,18 @@ export declare interface StepperProps {
 export declare function stopAudio(): void;
 
 /**
- * Typed wrapper around `localStorage` that JSON-encodes values and
- * silently handles environments where storage is unavailable (SSR, private mode).
- *
- * @tempest-limits empty-catch — every method here is best-effort by contract:
- * `localStorage` throws on quota exhaustion, in Safari private mode, and when a
- * cross-origin frame has storage blocked. A caller persisting a preference has no
- * recovery to run and no user-facing message to show, so the write is dropped and
- * the app keeps the value in memory for the session.
+ * Typed wrapper around `localStorage` that JSON-encodes values and silently
+ * handles environments where storage is unavailable (SSR, private mode).
  */
-export declare const storage: {
-    get<T>(key: string, fallback: T): T;
-    set<T>(key: string, value: T): void;
-    remove(key: string): void;
-};
+export declare const storage: JsonStorage;
+
+/** How a {@link createJsonStorage} store turns values into text and back. */
+export declare interface StorageCodec {
+    /** Encode a value for storage. */
+    serialize: <T>(value: T) => string;
+    /** Decode a stored string. */
+    deserialize: <T>(raw: string) => T;
+}
 
 /** Raw usage/quota reading from the Storage API, in bytes. */
 declare interface StorageEstimate_2 {
@@ -10810,6 +11028,16 @@ export declare interface SyncRunSummary {
     succeeded: number;
     /** Entries that failed and stay queued for the next run. */
     failed: number;
+    /**
+     * Entries left untried because an earlier entry for the **same record**
+     * failed this run.
+     *
+     * They stay queued and are attempted next run, in order. Counted apart from
+     * `failed` because they were never sent: reporting them as failures would
+     * blame the server for a decision this engine made, and folding them in would
+     * make `succeeded + failed` stop accounting for the queue.
+     */
+    deferred: number;
     /** Total wall-clock milliseconds the run took. */
     durationMs: number;
     /** `true` when the run was skipped because the device was offline. */
@@ -11077,6 +11305,7 @@ export declare class TempestApiError extends Error implements ApiError {
     readonly detail: string;
     readonly code?: string;
     readonly requestId?: string;
+    readonly fields?: Record<string, string>;
     readonly body?: unknown;
     constructor(init: ApiError);
 }
@@ -11714,6 +11943,23 @@ export declare interface TransferProps extends Omit<HTMLAttributes<HTMLDivElemen
 /** Which pane an operation is about. */
 export declare type TransferSide = "source" | "target";
 
+/** Per-call options for {@link I18n.t} and {@link I18n.plural}. */
+export declare interface TranslateOptions {
+    /**
+     * Text to use when the catalog defines neither the key nor its fallback.
+     *
+     * Without this, a miss returns the key, and a caller that wants its own text
+     * instead has to *detect* the miss — which from the outside means comparing
+     * the result against the key it just passed in. That heuristic is wrong for a
+     * catalog that legitimately maps a key to itself, and it is what every
+     * translatable string the SDK ships would otherwise have to copy.
+     *
+     * Interpolated like any other message, so a default carries `{placeholders}`
+     * too and is not second-class.
+     */
+    default?: string;
+}
+
 /**
  * Estimated travel between two coordinates. Mirrors the `TravelEstimate`
  * schema from `tempest-fastapi-sdk` (`geo/schemas.py`), snake_case preserved so
@@ -12372,7 +12618,8 @@ export declare interface UseClipboardResult {
  * which a counter held in state cannot do.
  *
  * The interval stops once it reaches zero instead of ticking forever behind a
- * clamp.
+ * clamp — `useInterval` pauses on a `null` delay, so reaching zero is what tears
+ * the timer down.
  *
  * @param durationMs - Length of the window.
  * @param startedAt - Epoch ms the window opened (`Date.now()` when it started).
@@ -12511,29 +12758,6 @@ 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;
 
 /**
@@ -12855,6 +13079,17 @@ export declare interface UseKeyboardShortcutOptions {
  * want to *call* — it hands back a callable with a stable identity, rather than
  * making every call site reach through `.current`.
  *
+ * **List the returned ref in your effect's dependencies.** It is a stable object,
+ * so the effect never re-runs because of it, but `react-hooks/exhaustive-deps`
+ * cannot prove that for a custom hook the way it does for a bare `useRef`.
+ * Listing it lets the rule verify the array instead of taking an omission on
+ * trust.
+ *
+ * **Not for holding the previous value.** The write happens during render, so
+ * `.current` is already the current value by the time any effect reads it. A hook
+ * that wants the value from the *previous* commit — `usePrevious` — needs the
+ * effect-based write, and swapping it for this would make it return the present.
+ *
  * @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`.
@@ -14067,7 +14302,9 @@ export declare interface UseSetResult<T> {
  * `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.
+ * `baseUrl`, `voices` and `maxSources` are read once, at creation. The options
+ * object is forwarded whole rather than rebuilt field by field, so a field added
+ * to {@link SfxPoolOptions} does not silently stop reaching the pool.
  *
  * @param options - Passed through to {@link createSfxPool}.
  * @returns A stable pool handle.
@@ -14285,12 +14522,15 @@ export declare interface UseSpeechRecognitionResult {
  * `callback` argument. Use to break dependency cycles in effects without
  * triggering re-runs when the callback identity changes.
  *
- * The assignment happens **during render** on purpose. Moving it into an effect
- * would satisfy the React Compiler rules but open a one-commit staleness window:
- * an effect declared before this hook's own effect, in the same commit, would call
- * the previous render's callback. This is a primitive other hooks build on, so a
- * subtle staleness here is worse than the rule violation. Prefer React's
+ * Built on {@link useLatestRef}, which owns the render-time assignment and the
+ * reason it is not an effect: an effect would satisfy the React Compiler rules
+ * but open a one-commit staleness window. What this adds is the callable with a
+ * stable identity, so callers do not reach through `.current`. Prefer React's
  * `useEffectEvent` once it ships as stable.
+ *
+ * The ref is listed as a dependency because it is one — a stable object across
+ * renders, so the returned identity never changes. Listing it is what lets the
+ * exhaustive-deps rule verify that instead of taking an empty array on trust.
  */
 export declare function useStableCallback<TArgs extends unknown[], TReturn>(callback: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
 
@@ -14441,6 +14681,11 @@ export declare function useTranslate(): I18nContextValue["t"];
  * 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.
  *
+ * How far the reveal got is derived rather than stored: a `speedMs` of `0` reads
+ * as "all of it" without a state write, and `useInterval` pausing on a `null`
+ * delay is what stops the timer at the end. Both used to need an effect that
+ * cleared its own interval from inside a state updater.
+ *
  * @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`.