tempest-react-sdk 0.66.0 → 0.68.0

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

@@ -171,6 +171,47 @@ export declare interface AccordionProps {
     className?: string;
 }
 
+/**
+ * Resolve which navigation key is active for the current route.
+ *
+ * A menu whose keys are URLs almost never has a key equal to the pathname —
+ * `/dashboard/tips/42` has to highlight `/dashboard/tips`. This picks the
+ * **longest key that covers the path on a segment boundary**, which is what fixes
+ * the two ways the one-line `keys.find((k) => pathname.startsWith(k))` goes wrong:
+ * `/dashboard` stays lit on every screen of the panel (the array order decides),
+ * and `/dashboard/tip` lights `/dashboard/tips`.
+ *
+ * The rules:
+ *
+ * - Query string and hash are ignored, on both sides.
+ * - A trailing slash, on the route or on the key, changes nothing.
+ * - `/` is active only on `/` itself, as with react-router's `NavLink`.
+ * - The comparison is case-sensitive, as URL paths are.
+ * - No match returns `""` — never `undefined`, never a throw — so the result can
+ *   go straight into a `value` prop.
+ *
+ * The keys and the pathname have to live in the same space: with a router
+ * `basename`, pass `useLocation().pathname` (which has the basename stripped) and
+ * keys without it.
+ *
+ * Framework-agnostic on purpose: it takes a string, so it works with
+ * react-router, with `window.location.pathname`, and for `BottomNavigation`,
+ * `NavigationRail` or a `Drawer` menu just as for `Sidebar` — which does the same
+ * resolution itself with `match="route"`.
+ *
+ * @param pathname - The current route, e.g. `useLocation().pathname`.
+ * @param keys - The navigation keys, each one a URL path.
+ * @returns The active key exactly as given in `keys`, or `""` when none covers
+ *     the route.
+ *
+ * @example
+ * const { pathname } = useLocation();
+ * const value = activeNavKey(pathname, ["/dashboard", "/dashboard/tips"]);
+ * // "/dashboard/tips/42" → "/dashboard/tips"
+ * // "/dashboard/tip"     → "/dashboard"
+ */
+export declare function activeNavKey(pathname: string, keys: readonly string[]): string;
+
 /**
  * A conversation with a model: role-based turns, Markdown answers, a reasoning
  * block, a streaming caret, per-turn actions and a composer that turns into a stop
@@ -518,6 +559,15 @@ export declare type AlertVariant = "neutral" | "info" | "success" | "warning" |
 /** Every symbology in the spec, used to validate what a detector reports back. */
 export declare const ALL_BARCODE_FORMATS: readonly BarcodeFormat[];
 
+/**
+ * The value {@link withAllOption} gives its entry, exported so the filter code
+ * compares against a name instead of a magic string.
+ *
+ * @example
+ * const where = status === ALL_OPTION_VALUE ? {} : { status };
+ */
+export declare const ALL_OPTION_VALUE = "all";
+
 /**
  * Announce a message to screen readers, from anywhere — a hook, an event handler,
  * a plain function outside React.
@@ -739,7 +789,6 @@ export declare interface ApiClientConfig {
      * permission the caller does not have.
      */
     retry?: boolean | RetryOptions;
-    /** Whether to send cookies on cross-origin requests (default: false). */
     /**
      * Milliseconds before a request is abandoned. Default `15_000`. `null` turns
      * it off.
@@ -769,7 +818,32 @@ export declare interface ApiClientConfig {
      * particular call does not fit either default.
      */
     uploadTimeout?: number | null;
+    /** Whether to send cookies on cross-origin requests (default: false). */
     withCredentials?: boolean;
+    /**
+     * Send a CSRF token on every request that can change state. Off by default.
+     *
+     * A bearer token is immune to cross-site request forgery because the
+     * browser never attaches `Authorization` on its own. A cookie session is
+     * not: the browser sends the cookie with a request another site triggers.
+     * That is the mode `withCredentials: true` exists for — and before 0.68.0
+     * the SDK had no piece of the defense.
+     *
+     * `true` uses the defaults of `tempest-fastapi-sdk`'s `CSRFMiddleware`:
+     * read the `csrf_token` cookie, send it as `X-CSRF-Token`. Pass
+     * {@link CsrfOptions} to rename either, or to supply the token yourself.
+     *
+     * The header goes on `POST`, `PUT`, `PATCH`, `DELETE` and any other
+     * non-safe method, never on `GET`/`HEAD`/`OPTIONS`/`TRACE`; only to the
+     * origins the bearer token may reach (`baseURL`'s plus
+     * {@link trustedOrigins}); on `skipAuth` requests too, because login and
+     * refresh are the writes a cookie session exposes; and never over a CSRF
+     * header you set yourself.
+     *
+     * Independent of `withCredentials`: a same-origin app sends its cookies
+     * without it, and is exposed the same way.
+     */
+    csrf?: boolean | CsrfOptions;
     /** Default headers merged into every request. */
     headers?: Record<string, string>;
     /** Optional fetch implementation (defaults to globalThis.fetch). */
@@ -1908,7 +1982,9 @@ export declare interface BottomNavigationProps extends Omit<HTMLAttributes<HTMLE
 
 /**
  * Slide-up modal panel — mobile-style sheet anchored to the bottom edge.
- * Uses portal + safe-area padding + scroll lock.
+ * Uses portal + safe-area padding + scroll lock, and traps keyboard focus in the
+ * sheet like `Modal`: focus enters on open, `Tab` cycles inside and returns to
+ * the opener on close.
  *
  * @example
  * <BottomSheet open={open} onClose={() => setOpen(false)} title="Filters">
@@ -2952,7 +3028,7 @@ declare interface ColorScaleOptions {
  * Selecting an option fires `onChange(value)`. Typing filters the list.
  * Keyboard: ArrowUp/ArrowDown to navigate, Enter to select, Esc to close.
  */
-export declare function Combobox({ options, value, onChange, label, placeholder, helperText, error, disabled, filter, emptyMessage, className, }: ComboboxProps): JSX.Element;
+export declare function Combobox({ options, value, onChange, label, placeholder, helperText, error, disabled, filter, emptyMessage, portal, className, }: ComboboxProps): JSX.Element;
 
 export declare interface ComboboxOption {
     value: string;
@@ -2973,6 +3049,16 @@ export declare interface ComboboxProps {
     filter?: (option: ComboboxOption, query: string) => boolean;
     /** Message shown when no option matches. */
     emptyMessage?: string;
+    /**
+     * Render the list in a portal, positioned under the field. Default `true`.
+     *
+     * In flow, an ancestor with `overflow` other than `visible` clips the list —
+     * in the last row of a `DataTable` none of it was visible (measured in Chrome
+     * at 1440 px). In a portal it escapes the clip, takes the field's width,
+     * flips above the field when there is no room below, and follows it on
+     * scroll, resize and when the field or the list changes size.
+     */
+    portal?: boolean;
     className?: string;
 }
 
@@ -3303,6 +3389,12 @@ export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "value
  * header, and a development build says so once. Declare the exceptions in
  * {@link ApiClientConfig.trustedOrigins}.
  *
+ * **CSRF** is off unless you set `csrf`. With it, every unsafe request (anything
+ * but `GET`/`HEAD`/`OPTIONS`/`TRACE`) echoes the `csrf_token` cookie in an
+ * `X-CSRF-Token` header — the double-submit contract of `tempest-fastapi-sdk`'s
+ * `CSRFMiddleware` — scoped to the same origins as the bearer token and sent on
+ * `skipAuth` requests too. See {@link ApiClientConfig.csrf}.
+ *
  * **Retries** are off unless you set `retry`. See {@link ApiClientConfig.retry}
  * for the built-in policy; it never replays a write. A single call overrides it
  * with {@link RequestOptions.retry}, and opts out of auth entirely with
@@ -4441,6 +4533,16 @@ export declare interface CreateTempestAuthOptions<TUser> {
     storage?: "local" | "session";
     /** Send cookies (needed when the refresh token lives in an httpOnly cookie). */
     withCredentials?: boolean;
+    /**
+     * CSRF token for every write, forwarded to `createApiClient`'s `csrf`. Off
+     * by default; `true` echoes the `csrf_token` cookie as `X-CSRF-Token`.
+     *
+     * The pair to `withCredentials`: once the refresh token lives in a cookie,
+     * the browser attaches it to a `POST /auth/refresh` that another site
+     * triggers. Login and refresh carry the header too — they go out with
+     * `skipAuth`, and the CSRF header does not follow auth.
+     */
+    csrf?: boolean | CsrfOptions;
     /** Custom fetch implementation (testing / SSR). Defaults to `globalThis.fetch`. */
     fetcher?: typeof fetch;
     /**
@@ -4811,6 +4913,91 @@ export declare interface CredentialsContainerLike {
     }): Promise<Credential | null>;
 }
 
+/**
+ * The CSRF header a request should carry, or an empty object.
+ *
+ * Every request path in the SDK — `createApiClient`, `uploadWithProgress`,
+ * `createResumableUpload` — asks this function, so the rules are one rule:
+ *
+ * - **Off unless configured.** Without `csrf`, nothing changes.
+ * - **Unsafe methods only.** `GET`, `HEAD`, `OPTIONS` and `TRACE` never carry
+ *   it; they must not change state, and a token in a `GET` ends up in logs
+ *   and caches for nothing.
+ * - **Never across an origin.** The token follows the same scope as the bearer
+ *   credential ({@link isTrustedCredentialTarget}), because a URL can come off
+ *   the network — a tus `Location`, a pagination link — and a CSRF token sent
+ *   to a third party is a token that third party can replay. Withheld tokens
+ *   are reported once per origin in a development build.
+ * - **Your header wins.** A CSRF header you set by hand, in any casing, is
+ *   left alone.
+ * - **Independent of auth.** It is sent on `skipAuth` requests too: login and
+ *   refresh are exactly the writes a cookie session exposes to forgery.
+ *
+ * Exported for the request you build by hand, so it follows the same rules.
+ *
+ * @example
+ * const headers = csrfHeaders({
+ *     method: "POST",
+ *     url: "https://api.acme.com/orders",
+ *     reference: "https://api.acme.com",
+ *     csrf: true,
+ * });
+ * // { "X-CSRF-Token": "<value of the csrf_token cookie>" }
+ *
+ * @param input - The request and the CSRF config.
+ * @returns A header record to spread into the request's headers.
+ */
+export declare function csrfHeaders(input: CsrfHeadersInput): Record<string, string>;
+
+/** What {@link csrfHeaders} needs to decide. */
+export declare interface CsrfHeadersInput {
+    /** The HTTP method of the request. Case-insensitive. */
+    method: string;
+    /** The URL the request is going to. */
+    url: string;
+    /**
+     * The origin the token belongs to, normally the API's `baseURL`. The token
+     * is only sent to this origin or to one listed in `trustedOrigins`.
+     */
+    reference: string;
+    /** The CSRF config. `undefined` or `false` turns the header off. */
+    csrf: boolean | CsrfOptions | undefined;
+    /** Extra origins allowed to receive the token. */
+    trustedOrigins?: readonly string[];
+    /** Headers the caller already set. A CSRF header among them is never replaced. */
+    headers?: HeadersInit;
+}
+
+/**
+ * Where the CSRF token comes from and which header carries it.
+ *
+ * The default is the **double-submit cookie**: the server sets a cookie that is
+ * deliberately not `HttpOnly`, the client reads it and echoes the value in a
+ * header, and the server rejects a write whose header does not match the
+ * cookie. A page on another site can make the browser *send* the cookie, but
+ * cannot *read* it, so it cannot write the header.
+ *
+ * The token is read again on every request, so a server that rotates the
+ * cookie is followed without any capture step: the browser's cookie jar is the
+ * store. That is also why there is no "read the token from a response header"
+ * mode — it would depend on `Access-Control-Expose-Headers`, and a missing
+ * expose header fails silently, as a `403` on the second write.
+ */
+export declare interface CsrfOptions {
+    /** Cookie to read the token from. Default {@link DEFAULT_CSRF_COOKIE_NAME}. */
+    cookieName?: string;
+    /** Header to send the token in. Default {@link DEFAULT_CSRF_HEADER_NAME}. */
+    headerName?: string;
+    /**
+     * Supply the token yourself instead of reading `cookieName`.
+     *
+     * For the cases the cookie cannot serve: an API on another **site**, whose
+     * cookie `document.cookie` cannot see, or a backend that hands the token
+     * out in a response body. Called per request, like `getToken`.
+     */
+    getToken?: () => string | null | undefined;
+}
+
 /**
  * @tempest-limits param-count — `downloadCsv(rows, columns, "usuarios.csv")` reads
  * in the order the sentence does, and its two trailing parameters have defaults,
@@ -4984,7 +5171,8 @@ export declare interface DataProviderOptions {
  * - Clicking a sortable header cycles asc → desc → unsorted.
  * - Search matches a case-insensitive substring across `searchKeys`
  *   (or every string/number column when not provided).
- * - Pagination is hidden when the result fits on a single page.
+ * - Pagination is hidden when the result fits on a single page — unless
+ *   `onPageSizeChange` is set, because the footer then carries the size selector.
  * - A column with `editable` renders a button that opens an inline editor;
  *   `Enter` commits, `Escape` discards, `Tab` walks to the next editable cell.
  *
@@ -5005,7 +5193,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, totalItems, page: controlledPage, onPageChange, manualSort, onSortChange, manualSearch, onSearchChange, loading, className, ...rest }: DataTableProps<T>): JSX.Element;
+export declare function DataTable<T>({ data, columns, pageSize: pageSizeProp, searchable, searchKeys, initialSort, rowKey, emptyMessage, onCellChange, editLabels, totalItems, page: controlledPage, onPageChange, onPageSizeChange, pageSizeOptions, 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> {
@@ -5019,7 +5207,13 @@ export declare interface DataTableBaseProps<T> extends HTMLAttributes<HTMLDivEle
     data: T[];
     /** Column definitions. */
     columns: DataTableColumn<T>[];
-    /** Rows per page. Default 10. */
+    /**
+     * Rows per page. Default 10.
+     *
+     * Always read on every render, so it is already a controlled value; what turns
+     * it into a user-facing choice is `onPageSizeChange` (see
+     * {@link DataTablePageSizeProps}), which then makes it required.
+     */
     pageSize?: number;
     /** Render a search input above the table. Default false. */
     searchable?: boolean;
@@ -5131,6 +5325,40 @@ export declare interface DataTableEditLabels {
 /** Input types an editable column can use. */
 export declare type DataTableEditorType = "text" | "number" | "date" | "email" | "tel" | "url";
 
+/**
+ * The items-per-page selector: owned by the caller, or absent.
+ *
+ * The footer is the SDK's own `Pagination`, which already renders a size
+ * `<select>`; this is the channel that reaches it. Two shapes only, for the same
+ * reason as {@link DataTablePagingProps}: `pageSizeOptions` with no
+ * `onPageSizeChange` is a selector that changes nothing, and `onPageSizeChange`
+ * with no `pageSize` is one whose choice never comes back — the table would keep
+ * counting pages by the default 10 while the selector claims 50. Both are build
+ * errors instead.
+ */
+export declare type DataTablePageSizeProps = {
+    /** No selector: `pageSize` is fixed by the caller. */
+    onPageSizeChange?: never;
+    /** Nothing to choose from. */
+    pageSizeOptions?: never;
+} | {
+    /** The size currently shown. Required, since the selector reports and you feed it back. */
+    pageSize: number;
+    /**
+     * Called with the size the user picked. Passing it renders the selector in the
+     * footer, and keeps the footer on screen even when everything fits on one page
+     * — otherwise picking 100 for 40 rows would remove the only control that can
+     * pick 10 again.
+     *
+     * The table also moves back to page 1 (through `onPageChange` when the page
+     * is controlled), after this call. Page 7 of 10-per-page has no meaning at
+     * 100-per-page, and 1 is the only page guaranteed to exist under the new size.
+     */
+    onPageSizeChange: (size: number) => void;
+    /** Sizes offered. Default `[10, 25, 50, 100]`; the current `pageSize` is always included. */
+    pageSizeOptions?: number[];
+};
+
 /**
  * Paging, as one of the three shapes that actually work.
  *
@@ -5182,10 +5410,10 @@ export declare type DataTablePagingProps = {
 };
 
 /**
- * The table's props: the shared half, plus one valid paging shape and one valid
- * sorting shape.
+ * The table's props: the shared half, plus one valid shape per axis — paging,
+ * page size, sorting and searching.
  */
-export declare type DataTableProps<T> = DataTableBaseProps<T> & DataTablePagingProps & DataTableSortProps<T> & DataTableSearchProps;
+export declare type DataTableProps<T> = DataTableBaseProps<T> & DataTablePagingProps & DataTablePageSizeProps & DataTableSortProps<T> & DataTableSearchProps;
 
 /**
  * Searching: delegated, and therefore reported, or neither.
@@ -5414,6 +5642,25 @@ export declare const DEFAULT_CHUNK_SIZE: number;
  */
 export declare const DEFAULT_CIRCUITY_FACTOR = 1.3;
 
+/**
+ * Default cookie the CSRF token is read from.
+ *
+ * Ported from `tempest-fastapi-sdk`'s `CSRF_COOKIE_NAME`
+ * (`tempest_fastapi_sdk/api/middlewares/csrf.py`), which is the cookie its
+ * `make_csrf_token_dependency()` sets and its `CSRFMiddleware` compares against.
+ * Matching it is what lets `csrf: true` work against that backend with no
+ * configuration on either side.
+ */
+export declare const DEFAULT_CSRF_COOKIE_NAME = "csrf_token";
+
+/**
+ * Default header the CSRF token is echoed in.
+ *
+ * Ported from `tempest-fastapi-sdk`'s `CSRF_HEADER_NAME`, the header its
+ * `CSRFMiddleware` reads on every unsafe request.
+ */
+export declare const DEFAULT_CSRF_HEADER_NAME = "X-CSRF-Token";
+
 /** Default ceiling for a per-source or master gain, as a multiplier. */
 export declare const DEFAULT_MAX_GAIN = 3;
 
@@ -5503,6 +5750,11 @@ export declare function defineRoutes(routes: TempestRouteObject[]): TempestRoute
  * 0. `codes[error.code]` — the sentence you wrote for that exact backend case.
  *    Checked first because nothing the funnel derives can beat it, and because a
  *    request that never landed carries no `code` for it to shadow.
+ * 0.5. `statuses[error.status]` — the sentence for a whole class of failure,
+ *    for the errors that arrive with no useful body. It beats the backend's
+ *    `detail`, because a generic line emitted by the framework is worse than the
+ *    one the app wrote for that status, and it beats the offline sentence when
+ *    the caller maps `0` explicitly.
  * 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
@@ -5590,6 +5842,29 @@ export declare interface DescribeApiErrorOptions extends Partial<ApiErrorStrings
      * knew both the backend contract and the screen it lands on.
      */
     codes?: Readonly<Record<string, string>>;
+    /**
+     * Maps an HTTP status to a sentence, for the failures that arrive with no
+     * useful body.
+     *
+     * `codes` covers the cases the backend named; this covers the ones it did
+     * not. The reference case is the `403` of an admin-only route: the body
+     * carries a generic `detail` (or none), so the funnel fell through to the
+     * fallback and an administrator read "Não foi possível carregar" when the
+     * fact that answers their question is "esta listagem é só para
+     * administradores".
+     *
+     * Checked after `codes` and **before** the backend's `detail`: a generic
+     * sentence emitted by the framework is worse than the one the app wrote for
+     * that status. `useDetail: false` remains the way to suppress `detail`
+     * entirely.
+     *
+     * A `0` key is honoured like any other, ahead of the offline sentence —
+     * `statuses` is the caller's explicit map, and the fixed `offline` string is
+     * already the way to reword that case. Status `0` covers a request that
+     * never landed **and** one abandoned by the client timeout, so an app that
+     * maps it is taking both.
+     */
+    statuses?: Readonly<Record<number, string>>;
     /**
      * Whether the backend's `detail` may be shown when no `code` matched.
      * Default `true`.
@@ -5754,9 +6029,14 @@ export declare type DocumentVisibility = "visible" | "hidden";
  */
 export declare function downloadCsv<T>(rows: readonly T[], columns: readonly CsvColumn<T>[], fileName?: string, options?: CsvOptions): Promise<void>;
 
+/** An edit to the draft: a partial object merged over it, or an updater. */
+export declare type DraftFiltersPatch<T> = Partial<T> | ((draft: T) => T);
+
 /**
  * Sliding side panel. Same building blocks as {@link Modal} but anchored to
- * an edge. Locks body scroll while open.
+ * an edge. Locks body scroll while open, and traps keyboard focus in the panel
+ * the same way `Modal` does: focus enters on open, `Tab` cycles inside (portalled
+ * panels opened from it included) and returns to the opener on close.
  */
 export declare function Drawer({ open, onClose, placement, title, children, footer, closeOnBackdrop, closeOnEsc, hideCloseButton, className, mobilePlacement, showHandle, }: DrawerProps): ReactPortal | null;
 
@@ -5794,13 +6074,17 @@ export declare interface DrawerProps {
  * - `ArrowUp` / `ArrowDown` move with wrap, `Home` / `End` jump to the ends.
  * - `Escape` closes and returns focus to the trigger, so the next `Tab` continues
  *   from where the user was rather than from the top of the document.
- * - `Tab` closes the menu and lets the page's own tab order take over.
+ * - `Tab` closes the menu and lets the page's own tab order take over, counted
+ *   from the trigger: focus goes back to the trigger synchronously and the key's
+ *   default action then moves on from there. Without that, a portalled menu —
+ *   the last thing in `body` — would hand `Tab` to whatever follows it, which
+ *   inside a `Modal` is outside the dialog.
  * - Focus is managed: entries carry `tabIndex={-1}` and only the active one is
  *   `0`, which is what stops `Tab` from walking the menu one entry at a time.
  *
  * Disabled entries, separators and labels are skipped by every movement.
  */
-export declare function DropdownMenu({ trigger, items, placement, className, }: DropdownMenuProps): JSX.Element;
+export declare function DropdownMenu({ trigger, items, placement, portal, className, }: DropdownMenuProps): JSX.Element;
 
 export declare type DropdownMenuEntry = {
     type: "item";
@@ -5848,6 +6132,23 @@ export declare interface DropdownMenuProps {
     }>;
     items: DropdownMenuEntry[];
     placement?: DropdownMenuPlacement;
+    /**
+     * Render the menu in a portal, positioned against the trigger. Default `true`.
+     *
+     * Without it the menu is `position: absolute` inside the trigger's wrapper,
+     * and any ancestor with `overflow` other than `visible` clips it. The ordinary
+     * victim is the action column of a `DataTable`: its wrapper scrolls
+     * horizontally, `overflow-x: auto` forces `overflow-y` to `auto` too, and the
+     * menu of the last row showed one of three entries (measured in Chrome at
+     * 1440 px). In a portal the menu escapes the clip, flips above the trigger
+     * when there is no room below, and follows the trigger on scroll and resize.
+     *
+     * The portalled menu stacks at `--tempest-z-popover`, above
+     * `--tempest-z-modal`, so a menu opened inside a `Modal` still paints on top.
+     * `false` keeps the in-flow menu, for a container that must own the menu's
+     * stacking or clipping on purpose.
+     */
+    portal?: boolean;
     className?: string;
 }
 
@@ -6230,6 +6531,95 @@ export declare type FilterFieldType = "text" | "number" | "date" | "select" | "b
 /** Comparison a filter can make. */
 export declare type FilterOperator = "eq" | "ne" | "contains" | "gt" | "gte" | "lt" | "lte" | "between" | "in" | "empty" | "notEmpty";
 
+/**
+ * The frame around a fixed set of filters: a card with a title, a grid of the
+ * fields the screen declares, and the actions that belong to no field — clear,
+ * apply, export.
+ *
+ * It holds no state and has no opinion on the fields. `FilterBar` is for ad hoc
+ * querying (the user picks field, operator and value); this is for the set a
+ * screen already knows — município, UF, situação, a search box. Pair it with
+ * `useDraftFilters`: the fields edit `draft`, `onApply` and `onClear` are the
+ * hook's `apply` and `clear`.
+ *
+ * What it settles, each measured in Chromium against the `Card` + `Grid`
+ * composition it replaces:
+ *
+ * - **The grid follows the panel, not the viewport.** `Grid` switches columns on
+ *   viewport breakpoints, so the same filters in a 360 px column of a 1280 px
+ *   screen got four 57.5 px fields. The default here is
+ *   `repeat(auto-fill, minmax(min(100%, minFieldWidth), 1fr))`: the column count
+ *   comes from the room the panel has, and `min(100%, …)` keeps a floor wider than
+ *   the phone from overflowing it.
+ * - **Cells align to the top.** A field showing an error is taller; with the grid
+ *   default (`stretch`), its row-mates' boxes grew to match.
+ * - **The header wraps.** Three actions next to the title measured 527 px in a
+ *   308 px header at 390 px wide, and scrolled the whole page sideways. `Card`'s
+ *   header now wraps, and so do the actions inside it.
+ * - **Clear and apply have a fixed place**, at the end of the header, apply last.
+ *
+ * @example
+ * const filters = useDraftFilters({ search: "", uf: "" });
+ * <FilterPanel
+ *     onApply={() => filters.apply()}
+ *     onClear={filters.clear}
+ *     applyDisabled={!filters.isDirty}
+ * >
+ *     <Input label="Busca" value={filters.draft.search}
+ *         onChange={(e) => filters.set({ search: e.target.value })} />
+ *     <Select label="UF" options={UFS} value={filters.draft.uf}
+ *         onChange={(e) => filters.set({ uf: e.target.value })} />
+ * </FilterPanel>
+ */
+export declare function FilterPanel({ children, title, actions, onClear, onApply, applyDisabled, locale, labels, minFieldWidth, columns, className, style, ...props }: FilterPanelProps): JSX.Element;
+
+/** Labels the panel writes itself. */
+export declare interface FilterPanelLabels {
+    /** Default title. `"Filtros"` / `"Filters"`. */
+    title: string;
+    /** The clear button. `"Limpar filtros"` / `"Clear filters"`. */
+    clear: string;
+    /** The apply button. `"Filtrar"` / `"Apply filters"`. */
+    apply: string;
+}
+
+export declare interface FilterPanelProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps_14> {
+    /** The filter controls the screen declares — `Input`, `Select`, a date picker. One grid cell each. */
+    children: ReactNode;
+    /** Heading. Default from `locale`. A string renders as an `h3`; a node renders as given. */
+    title?: ReactNode;
+    /** Header actions that are not fields — "Atualizar a cada 30s", "Exportar CSV". */
+    actions?: ReactNode;
+    /** Return the screen to its initial filters. Renders the clear button only when set. */
+    onClear?: () => void;
+    /**
+     * Publish the draft. When set, the fields sit in a `<form>`: the apply button
+     * submits it and Enter in any text field applies.
+     */
+    onApply?: () => void;
+    /**
+     * Disable the apply button — pass `!filters.isDirty`. Enter follows the button:
+     * it is the form's default button, so a disabled one blocks implicit submission
+     * too, and nothing is re-applied when nothing changed.
+     */
+    applyDisabled?: boolean;
+    /** Locale for the default title and button labels. Default `"pt-BR"`. */
+    locale?: "pt-BR" | "en";
+    /** Override any of the labels. */
+    labels?: Partial<FilterPanelLabels>;
+    /**
+     * Narrowest a field may get before the grid drops a column. Default `"12rem"`.
+     * The count follows the **panel's** width, so the same panel fits a page and a
+     * sidebar.
+     */
+    minFieldWidth?: string;
+    /**
+     * Fixed columns per viewport, as in `Grid` — `{ mobile: 1, tablet: 2, desktop: 4 }`.
+     * Replaces `minFieldWidth`, and follows the **viewport**, not the panel.
+     */
+    columns?: ResponsiveValue<number | string>;
+}
+
 export declare type FilterPredicate<T> = (item: T, search: string) => boolean;
 
 /**
@@ -7134,13 +7524,18 @@ export declare function higherVersionWins<T>(local: T | undefined, remote: T, ge
  *
  * - Opens after `openDelay` on `mouseenter`/`focus`.
  * - Closes after `closeDelay` on `mouseleave`/`blur`.
- * - Positioned relative to the trigger via `placement`.
+ * - Positioned relative to the trigger via `placement`, in a portal by default.
+ * - Moving the pointer from the trigger into the card keeps it open: React
+ *   dispatches `mouseenter`/`mouseleave` along the component tree, and the
+ *   portalled card is still inside the trigger's wrapper there.
+ * - A link or button in the card is the next `Tab` stop after the trigger, as it
+ *   was in flow.
  * - The card is rendered as a labelled `role="dialog"` region; the trigger stays keyboard focusable.
  *
  * @param props - The hover card props.
  * @returns The trigger wrapper and the anchored card when open.
  */
-export declare function HoverCard({ trigger, children, openDelay, closeDelay, placement, className, ...rest }: HoverCardProps): JSX.Element;
+export declare function HoverCard({ trigger, children, openDelay, closeDelay, placement, portal, className, style, ...rest }: HoverCardProps): JSX.Element;
 
 export declare type HoverCardPlacement = "top" | "bottom" | "left" | "right";
 
@@ -7155,6 +7550,15 @@ export declare interface HoverCardProps extends HTMLAttributes<HTMLDivElement> {
     closeDelay?: number;
     /** Where the card is anchored relative to the trigger. Default "bottom". */
     placement?: HoverCardPlacement;
+    /**
+     * Render the card in a portal, positioned against the trigger. Default `true`.
+     *
+     * In flow, an ancestor with `overflow` other than `visible` clips the card — a
+     * user handle in the last row of a `DataTable` showed 17% of it (measured in
+     * Chrome at 1440 px). In a portal it escapes the clip and flips to the
+     * opposite side at the viewport edge.
+     */
+    portal?: boolean;
 }
 
 export declare interface I18n {
@@ -9011,7 +9415,7 @@ export { MemoryRouter }
  *     ]}
  * />
  */
-export declare function Menubar({ menus, className, ...props }: MenubarProps): JSX.Element;
+export declare function Menubar({ menus, portal, className, ...props }: MenubarProps): JSX.Element;
 
 export declare type MenubarItem = {
     /** Visible label for the action. */
@@ -9036,6 +9440,18 @@ export declare interface MenubarMenu {
 export declare interface MenubarProps extends HTMLAttributes<HTMLDivElement> {
     /** Top-level menus rendered left-to-right. */
     menus: MenubarMenu[];
+    /**
+     * Render the open panel in a portal, positioned under its trigger. Default
+     * `true`.
+     *
+     * In flow, an ancestor with `overflow` other than `visible` clips the panel,
+     * and the SDK's own `Navbar` is one: its `nav` slot scrolls horizontally, and
+     * `overflow-x: auto` forces `overflow-y` to `auto` too — a menu showed
+     * 0% of its panel there (measured in Chrome at 1440 px). In a portal the
+     * panel escapes the clip, flips at the viewport edge, stays in the tab order
+     * right after its trigger, and follows it on scroll and resize.
+     */
+    portal?: boolean;
 }
 
 /**
@@ -9213,6 +9629,13 @@ export declare type MicrophoneStatus = "idle" | "requesting" | "ready" | "error"
  * Portal-rendered modal dialog with backdrop, Esc handler, and slots for
  * header/body/footer. Locks body scroll while open.
  *
+ * Keyboard focus is trapped in the dialog while it is open (`useFocusTrap`): it
+ * enters on the first tab stop — or the dialog itself when there is none —,
+ * `Tab`/`Shift+Tab` cycle inside it, including the panels of a `Popover` or
+ * `HoverCard` opened from it, and closing returns focus to the element that
+ * opened it. `aria-modal="true"` tells a screen reader the page behind is inert;
+ * the trap is what makes that true for the keyboard.
+ *
  * The `dialog` role needs an accessible name: a `title` supplies it via
  * `aria-labelledby`, and a titleless dialog should pass `aria-label`. The
  * header heading is only rendered when there is a title, so a close-button-only
@@ -9371,7 +9794,7 @@ export declare function moveItem<T>(items: T[], from: number, to: number): T[];
  * Keyboard: ArrowUp/ArrowDown navigate, Enter toggles the active option, Esc
  * closes, Backspace (empty input) pops the last chip.
  */
-export declare function MultiSelect({ options, value, onChange, label, placeholder, helperText, error, disabled, maxItems, filter, emptyMessage, className, }: MultiSelectProps): JSX.Element;
+export declare function MultiSelect({ options, value, onChange, label, placeholder, helperText, error, disabled, maxItems, filter, emptyMessage, portal, className, }: MultiSelectProps): JSX.Element;
 
 export declare interface MultiSelectOption {
     value: string;
@@ -9395,6 +9818,16 @@ export declare interface MultiSelectProps {
     filter?: (option: MultiSelectOption, query: string) => boolean;
     /** Message shown when no option matches. */
     emptyMessage?: string;
+    /**
+     * Render the list in a portal, positioned under the field. Default `true`.
+     *
+     * In flow, an ancestor with `overflow` other than `visible` clips the list —
+     * in the last row of a `DataTable` none of it was visible (measured in Chrome
+     * at 1440 px). In a portal it escapes the clip, takes the field's width,
+     * flips above the field when there is no room below, and follows it on
+     * scroll, resize and when the field grows a line of chips.
+     */
+    portal?: boolean;
     className?: string;
 }
 
@@ -9458,7 +9891,7 @@ export { NavigateOptions }
  *     ]}
  * />
  */
-export declare function NavigationMenu({ items, className, ...props }: NavigationMenuProps): JSX.Element;
+export declare function NavigationMenu({ items, portal, className, ...props }: NavigationMenuProps): JSX.Element;
 
 export declare interface NavigationMenuItem {
     /** Visible label for the entry. */
@@ -9474,6 +9907,18 @@ export declare interface NavigationMenuItem {
 export declare interface NavigationMenuProps extends HTMLAttributes<HTMLElement> {
     /** Top-level navigation entries. */
     items: NavigationMenuItem[];
+    /**
+     * Render the open panel in a portal, positioned under its trigger. Default
+     * `true`.
+     *
+     * In flow, an ancestor with `overflow` other than `visible` clips the panel,
+     * and the SDK's own `Navbar` is one: its `nav` slot scrolls horizontally, and
+     * `overflow-x: auto` forces `overflow-y` to `auto` too — a submenu showed
+     * 0% of its panel there (measured in Chrome at 1440 px). In a portal the
+     * panel escapes the clip, flips at the viewport edge, stays in the tab order
+     * right after its trigger, and follows it on scroll and resize.
+     */
+    portal?: boolean;
 }
 
 /**
@@ -10097,6 +10542,26 @@ export declare interface OpenModalOptions {
 /** The operators a field offers. */
 export declare function operatorsFor(field: FilterField): FilterOperator[];
 
+/**
+ * The shape every option list in the SDK shares: `Select`, `MultiSelect` and
+ * `Combobox` all accept an array of it.
+ *
+ * `value` is always a `string` here, because that is what a `<select>` hands
+ * back in `event.target.value` whatever the option was built from: an option
+ * built with the number `0` comes back as the string `"0"`, so a list that kept
+ * numbers could never be compared with `===` against what the control emits.
+ */
+export declare interface OptionEntry {
+    value: string;
+    label: string;
+}
+
+/** The minimum an option needs for the helpers to prepend to its list. */
+declare type OptionLike = {
+    value: string | number;
+    label: string;
+};
+
 /**
  * @tempest-limits file-lines — parsing a session description, merging one
  * `fmtp` line and inserting a missing one are the same pass over the same
@@ -10254,6 +10719,9 @@ declare type OverriddenDomProps_12 = "children";
 /** DOM attributes this component redefines. */
 declare type OverriddenDomProps_13 = "children" | "onChange";
 
+/** DOM attributes this component redefines. */
+declare type OverriddenDomProps_14 = "title" | "children" | "onSubmit";
+
 /**
  * DOM attributes this component redefines.
  *
@@ -10338,6 +10806,14 @@ export declare interface PaginationProps {
     onPageChange: (page: number) => void;
     pageSize?: number;
     onPageSizeChange?: (size: number) => void;
+    /**
+     * Sizes offered in the selector. Default `[10, 25, 50, 100]`.
+     *
+     * The current `pageSize` is always offered too, merged in ascending order. A
+     * `<select>` whose value matches no option displays its first option, so
+     * `pageSize={20}` against the default list used to read "10 / página" over a
+     * table showing 20 rows.
+     */
     pageSizeOptions?: number[];
     /** Total items count; if provided, renders the summary text. */
     totalItems?: number;
@@ -10987,11 +11463,14 @@ export declare interface PlaySfxOptions {
 export declare function pluralize(count: number, singular: string, plural?: string): string;
 
 /**
- * Lightweight popover. Renders a positioned panel anchored to a trigger,
- * dismissed on outside click / Escape. Does NOT include collision detection
- * or smart positioning — pair with Floating UI if you need that.
+ * Lightweight popover. Renders a panel anchored to a trigger, dismissed on
+ * outside click / Escape.
+ *
+ * Portalled by default, with viewport-aware placement: the panel flips to the
+ * opposite side when the requested one overflows, and is clamped inside the
+ * viewport otherwise.
  */
-export declare function Popover({ trigger, children, placement, open, onOpenChange, defaultOpen, closeOnEsc, closeOnOutsideClick, className, }: PopoverProps): JSX.Element;
+export declare function Popover({ trigger, children, placement, portal, open, onOpenChange, defaultOpen, closeOnEsc, closeOnOutsideClick, className, }: PopoverProps): JSX.Element;
 
 export declare type PopoverPlacement = "top" | "bottom" | "left" | "right";
 
@@ -11004,6 +11483,16 @@ export declare interface PopoverProps {
     }>;
     children: ReactNode;
     placement?: PopoverPlacement;
+    /**
+     * Render the panel in a portal, positioned against the trigger. Default `true`.
+     *
+     * In flow, any ancestor with `overflow` other than `visible` clips the panel —
+     * inside a `DataTable` cell only 3% of it was visible (measured in Chrome at
+     * 1440 px). In a portal it escapes the clip, flips to the opposite side when
+     * the requested one has no room, and follows the trigger on scroll and resize.
+     * `false` keeps the in-flow panel.
+     */
+    portal?: boolean;
     /** Controlled open state. */
     open?: boolean;
     /** Called when the user toggles or dismisses. */
@@ -12012,6 +12501,17 @@ export declare interface ResumableUploadOptions {
     trustedOrigins?: readonly string[];
     /** Send cookies. Default `false`. */
     withCredentials?: boolean;
+    /**
+     * Send a CSRF token on the creation `POST`, every chunk `PATCH` and the
+     * discarding `DELETE` — never on the offset `HEAD`. Off by default; `true`
+     * reads the `csrf_token` cookie into `X-CSRF-Token`, as `createApiClient`
+     * does.
+     *
+     * Scoped like the bearer token, to `endpoint`'s origin plus
+     * {@link trustedOrigins}: a `Location` pointing at object storage on
+     * another host gets neither.
+     */
+    csrf?: boolean | CsrfOptions;
     /**
      * Resume key. Defaults to a fingerprint of endpoint + file name/size/mtime, so
      * picking the same file after a reload resumes instead of restarting.
@@ -12535,7 +13035,7 @@ export declare interface SegmentedControlProps<TValue extends string = string> e
  * Native `<select>` wrapper. Either provide `options` for a quick render, or
  * pass `<option>` children directly.
  *
- * Two variants:
+ * Three variants:
  *
  * - `"field"` (default) — label, control, helper text and error slot, for a form.
  * - `"chip"` — the control alone, sized to its content, for a settings row where
@@ -12544,20 +13044,60 @@ export declare interface SegmentedControlProps<TValue extends string = string> e
  *   list item, which is why every app ended up hand-rolling a native `<select>`
  *   with `appearance: none` — and hand-rolling it loses the focus ring, the
  *   disabled styling and the caret this component already solves.
+ * - `"bare"` — the same mechanism with none of the look, for an app with its own
+ *   visual identity: the shell renders `wrapper > select + caret`, and the app
+ *   dresses the wrapper through `wrapperClassName`. See {@link SelectBareProps}.
  *
  * @example
  * <Select label="Estado" options={states} placeholder="Selecione" />
  *
  * @example
  * <ListTile title="Idioma" trailing={<Select variant="chip" aria-label="Idioma" options={langs} />} />
+ *
+ * @example
+ * <Select variant="bare" wrapperClassName={styles.filtro} aria-label="Status" options={status} />
  */
 export declare const Select: ForwardRefExoticComponent<SelectProps & RefAttributes<HTMLSelectElement>>;
 
-/** What both variants of {@link Select} accept. */
-declare interface SelectBaseProps extends SelectHTMLAttributes<HTMLSelectElement> {
+/**
+ * The mechanism without the look: `appearance: none`, the caret and the focus
+ * ring, and no border, background, radius, shadow or height.
+ *
+ * The `<select>` inherits `background-color` and `color` from the shell (the
+ * element `wrapperClassName` lands on). The background is not cosmetic: the
+ * native popup paints each `<option>` from the `<select>`'s background, so a
+ * transparent control would hand the menu back to the system white.
+ *
+ * Like `"chip"`, the variant has no visible label, so an accessible name is
+ * required — through `aria-label` or `aria-labelledby`.
+ */
+export declare type SelectBareProps = SelectBaseProps & {
+    variant: "bare";
+} & ({
+    "aria-label": string;
+} | {
+    "aria-labelledby": string;
+});
+
+/** What every variant of {@link Select} accepts. */
+export declare interface SelectBaseProps extends SelectHTMLAttributes<HTMLSelectElement> {
     options?: SelectOption[];
     placeholder?: string;
+    /**
+     * Class for the outermost element. On `"bare"` that element is the shell
+     * holding the `<select>` and the caret, which is where the app's own look goes.
+     */
     wrapperClassName?: string;
+    /**
+     * Replaces the built-in chevron, following the `icon?: ReactNode` convention
+     * the rest of the SDK uses.
+     *
+     * The icon is drawn in the caret slot, which is positioned by
+     * `--tempest-control-caret-offset` and sized by `--tempest-control-caret-size`;
+     * an `<svg>` passed here is stretched to that size, so the token — not the
+     * icon's own `width`/`height` — decides how big the caret is in every density.
+     */
+    caretIcon?: ReactNode;
 }
 
 /**
@@ -12568,13 +13108,13 @@ declare interface SelectBaseProps extends SelectHTMLAttributes<HTMLSelectElement
  * row's own text, which the `<select>` has no relationship to — so without this
  * the screen reader announces a combobox with no name at all.
  */
-declare interface SelectChipProps extends SelectBaseProps {
+export declare interface SelectChipProps extends SelectBaseProps {
     variant: "chip";
     "aria-label": string;
 }
 
 /** The full form field: label, control, helper text and error slot. */
-declare interface SelectFieldProps extends SelectBaseProps {
+export declare interface SelectFieldProps extends SelectBaseProps {
     variant?: "field";
     label?: string;
     helperText?: string;
@@ -12587,7 +13127,7 @@ export declare interface SelectOption {
     disabled?: boolean;
 }
 
-export declare type SelectProps = SelectFieldProps | SelectChipProps;
+export declare type SelectProps = SelectFieldProps | SelectChipProps | SelectBareProps;
 
 /**
  * Minimal subset of `@sentry/browser` used by the adapter. Lets you pass
@@ -12938,6 +13478,17 @@ export declare interface ShowProps {
  * </Show>
  *
  * @example
+ * const { pathname } = useLocation();
+ * <Sidebar
+ *     match="route"
+ *     value={pathname}
+ *     items={[
+ *         { key: "overview", label: "Overview", href: "/dashboard" },
+ *         { key: "tips", label: "Tips", href: "/dashboard/tips" },
+ *     ]}
+ * />
+ *
+ * @example
  * <Sidebar
  *     items={[
  *         { type: "section", key: "monitoring", label: "Monitoring" },
@@ -12950,7 +13501,7 @@ export declare interface ShowProps {
  *     onChange={setTab}
  * />
  */
-export declare function Sidebar({ header, items, value, onChange, footer, collapsed, width, collapsedWidth, className, style, ...props }: SidebarProps): JSX.Element;
+export declare function Sidebar({ header, items, value, onChange, match, footer, collapsed, width, collapsedWidth, className, style, ...props }: SidebarProps): JSX.Element;
 
 /**
  * One entry of the navigation list.
@@ -12989,8 +13540,28 @@ export declare interface SidebarProps extends Omit<HTMLAttributes<HTMLElement>,
     header?: ReactNode;
     /** Navigation entries. An entry with no `type` is an item. */
     items: SidebarEntry[];
-    /** Active item key. */
+    /**
+     * The active item: its `key` by default, or the current route with
+     * `match="route"`.
+     */
     value?: string;
+    /**
+     * How `value` picks the active item.
+     *
+     * - `"key"` (default): the item whose `key` equals `value`.
+     * - `"route"`: `value` is the current pathname, and the active item is the one
+     *   whose `href` (or `key`, when it has no `href`) is the longest path covering
+     *   it on a segment boundary — see `activeNavKey`. `/dashboard/tips/42` lights
+     *   `/dashboard/tips`, not `/dashboard`, and `/users-admin` never lights
+     *   `/users`. Sections and separators take no part.
+     *
+     * `"route"` is what lets the app pass `useLocation().pathname` and stop
+     * computing a key: the component already holds the entries the resolution runs
+     * against, so asking the app to repeat them is how the two drift apart. It
+     * reads no router itself — the value comes in as a string — so the component
+     * keeps working with no router mounted.
+     */
+    match?: "key" | "route";
     /** Fires when an item is clicked. Receives the item's `key`. */
     onChange?: (key: string) => void;
     /** Bottom slot — typically settings/profile/logout. */
@@ -14287,8 +14858,13 @@ export declare type TokenKind = "plain" | "comment" | "string" | "number" | "key
  * Lightweight tooltip. Shows on hover and on focus (keyboard-friendly). Wraps
  * a single child element via `cloneElement`, so the trigger keeps its own ref
  * and props.
+ *
+ * `Escape` hides it without moving the pointer or the focus, which is what
+ * WCAG 2.2 SC 1.4.13 (Content on Hover or Focus) asks of content that appears on
+ * hover. It is an `Escape` layer like the overlays, so inside a `Modal` the first
+ * press hides the tooltip and the second closes the modal.
  */
-export declare function Tooltip({ content, placement, children, disabled, openDelay, }: TooltipProps): JSX.Element;
+export declare function Tooltip({ content, placement, children, disabled, openDelay, portal, }: TooltipProps): JSX.Element;
 
 export declare type TooltipPlacement = "top" | "bottom" | "left" | "right";
 
@@ -14303,8 +14879,46 @@ export declare interface TooltipProps {
     disabled?: boolean;
     /** Delay (ms) before showing the tooltip. Default: 150. */
     openDelay?: number;
+    /**
+     * Render the bubble in a portal, positioned against the trigger. Default `true`.
+     *
+     * In flow, an ancestor with `overflow` other than `visible` clips the bubble —
+     * a `DataTable` cell cut it 23 px short (measured in Chrome at 1440 px). In a
+     * portal it escapes the clip and flips to the opposite side at the viewport
+     * edge. `false` keeps the in-flow bubble.
+     */
+    portal?: boolean;
 }
 
+/**
+ * Turn a `value → label` map into the option list `Select`, `MultiSelect` and
+ * `Combobox` take.
+ *
+ * Every key becomes a string `value` (see {@link OptionEntry} for why), so the
+ * result is assignable to `SelectOption[]`, `MultiSelectOption[]` and
+ * `ComboboxOption[]` alike.
+ *
+ * **Order.** A `Map` keeps the order it was written in, always. A plain object
+ * does too — **except for integer-like keys**, which JavaScript enumerates first
+ * and in ascending order whatever order they were written in
+ * (`OrdinaryOwnPropertyKeys`, ECMA-262 §10.1.11.1). Measured in Node 24:
+ * `Object.keys({ 5: "Ótimo", 3: "Ok", 1: "Ruim" })` is `["1", "3", "5"]`, and
+ * `{ baixa, 10, 2, alta }` enumerates as `["2", "10", "baixa", "alta"]`. When
+ * the business order of a numeric scale is not ascending, pass a `Map`.
+ *
+ * @param source - A record or a `Map` from value to label.
+ * @returns A new array, one entry per key, in the order described above.
+ *
+ * @example
+ * const STATUS = { active: "Ativo", paused: "Pausado" };
+ * <Select aria-label="Status" variant="chip" options={toOptions(STATUS)} />
+ *
+ * @example
+ * const HUMOR = new Map([[5, "Ótimo"], [3, "Ok"], [1, "Ruim"]]);
+ * toOptions(HUMOR); // 5, 3, 1 — the order written
+ */
+export declare function toOptions(source: Readonly<Record<string, string>> | ReadonlyMap<string | number, string>): OptionEntry[];
+
 /** Convert degrees to radians. */
 export declare function toRadians(degrees: number): number;
 
@@ -14820,6 +15434,18 @@ export declare interface UploadWithProgressOptions {
     trustedOrigins?: readonly string[];
     /** Send cookies. Defaults to false. */
     withCredentials?: boolean;
+    /**
+     * Send a CSRF token with the upload, as `createApiClient`'s `csrf` does.
+     * Off by default; `true` reads the `csrf_token` cookie into `X-CSRF-Token`.
+     *
+     * Scoped to {@link credentialOrigin} plus {@link trustedOrigins} — and,
+     * unlike the bearer token, scoped even when `credentialOrigin` is unset:
+     * then the scope is the page's own origin. The bearer default stays open
+     * only for compatibility with every version before 0.66.0; this option is
+     * new, so it starts closed. An API on another origin sets
+     * `credentialOrigin` to receive the token.
+     */
+    csrf?: boolean | CsrfOptions;
     /** Called on every `progress` event from the XHR upload channel. */
     onProgress?: (event: UploadProgressEvent) => void;
     /** Abort the request. */
@@ -15417,6 +16043,80 @@ export declare function useDocumentTitle(title: string): void;
 /** Subscribe to `document.visibilityState`. Returns `"visible"` during SSR. */
 export declare function useDocumentVisibility(): DocumentVisibility;
 
+/**
+ * Draft vs applied state for a server-side filter: the controls edit a draft
+ * freely, and the query only sees it when the user applies (a click, or Enter).
+ *
+ * A server-side filter cannot react to every keystroke — each character typed in
+ * a search box would be a request. Every admin screen then writes the same pair of
+ * `useState`s, and gets the same three details wrong:
+ *
+ * - **Clearing moves both halves.** Resetting only the draft leaves a filtered
+ *   list under an empty bar; resetting only the applied value leaves the opposite.
+ * - **Applying a value that is not in state yet.** "Filter by this code" has to
+ *   write the draft and publish it in one gesture; calling `setDraft(x)` and then
+ *   publishing `draft` reads the previous value. `apply(patch)` computes the next
+ *   draft from a ref that every call keeps current, so it never depends on the
+ *   order React flushes state in.
+ * - **Resetting the page.** Filtering while on page 7 of a result that now has two
+ *   pages shows an empty table. `usePaginatedQuery` handles it by itself when
+ *   `applied` is in its `queryKey`; a page kept elsewhere resets in `onApply`.
+ *
+ * There is no effect in here: applying happens inside the event that asked for it,
+ * so one click is one request. `applied` keeps its reference while nothing new is
+ * applied, so it can sit in a `queryKey` without a phantom refetch.
+ *
+ * Like `useState`, the initial value is read on the first render only; `clear()`
+ * returns to it.
+ *
+ * @param initial - The empty filter form: what the screen shows and queries first.
+ * @param options - `onApply` and `isEqual`.
+ * @returns The draft, the applied value and the gestures between them.
+ *
+ * @example
+ * const filters = useDraftFilters({ code: "", level: "all" });
+ * const logs = usePaginatedQuery({
+ *     queryKey: ["logs", filters.applied],
+ *     queryFn: (params) => api.listLogs({ ...params, ...toQuery(filters.applied) }),
+ * });
+ * // <Input value={filters.draft.code} onChange={(e) => filters.set({ code: e.target.value })} />
+ * // <Button disabled={!filters.isDirty} onClick={() => filters.apply()}>Filtrar</Button>
+ */
+export declare function useDraftFilters<T extends object>(initial: T, options?: UseDraftFiltersOptions<T>): UseDraftFiltersResult<T>;
+
+export declare interface UseDraftFiltersOptions<T> {
+    /**
+     * Called with the applied value on every `apply()` and `clear()` — the place to
+     * reset a page number you keep yourself. `usePaginatedQuery` does not need it:
+     * it goes back to page 1 on its own when `applied` changes its `queryKey`.
+     */
+    onApply?: (applied: T) => void;
+    /** Equality behind `isDirty` and the stable `applied`. Default: structural. */
+    isEqual?: (a: T, b: T) => boolean;
+}
+
+export declare interface UseDraftFiltersResult<T> {
+    /** What the filter controls edit. Changes on every keystroke. */
+    draft: T;
+    /**
+     * What the query reads. Changes only on `apply()`/`clear()`, and keeps its
+     * reference when the value applied is equal to the current one — safe to put
+     * in a `queryKey`.
+     */
+    applied: T;
+    /** Whether the draft differs from what is applied — enable the apply button on it. */
+    isDirty: boolean;
+    /** Edit the draft, merging a partial object or running an updater. Never applies. */
+    set: (patch: DraftFiltersPatch<T>) => void;
+    /**
+     * Publish the draft. With a patch, merge it into the draft **and** publish the
+     * result in the same call — "filter by this code" from a table row.
+     */
+    apply: (patch?: DraftFiltersPatch<T>) => void;
+    /** Reset the draft and the applied value to the initial one, together. */
+    clear: () => void;
+}
+
 /**
  * Hook that propagates errors to the nearest {@link ErrorBoundary}.
  *
@@ -15523,9 +16223,38 @@ export { UseFieldArrayReturn }
 export declare function useFlagValue<T extends FlagValue = FlagValue>(key: string, defaultValue?: T): T;
 
 /**
- * Trap keyboard focus inside `containerRef` while `active` is true. Cycles
- * Tab and Shift+Tab between the first and last focusable descendants. Pair
- * with Modal/Drawer for fully-accessible overlays.
+ * Trap keyboard focus inside `containerRef` while `active` is true.
+ *
+ * - **On activation** focus moves to the first tab stop, or to the container
+ *   itself when it has none (give it `tabIndex={-1}`). Content that already put
+ *   focus inside — an `autoFocus` input — is left where it is.
+ * - **`Tab` / `Shift+Tab`** wrap between the first and the last stop, and pull
+ *   focus back in when it sits outside.
+ * - **On release** focus returns to the element that held it when the trap
+ *   armed. That element is read during the render that arms the trap, before
+ *   React commits: an `autoFocus` child takes focus in the commit, ahead of any
+ *   effect, and reading it there would "restore" to the child that is about to
+ *   unmount — which dropped focus on `body` in `Command`.
+ *
+ * **Portalled panels stay reachable.** A `Popover` or `HoverCard` opened from
+ * inside the container renders at the end of `body`, outside it. Those panels
+ * register themselves (see `usePortalTabOrder`), and the trap treats them as
+ * part of the container, spliced right after their trigger. A `Tab` another
+ * layer already consumed is not moved again, unless it moved focus out of the
+ * container and its panels — the portal bridge leaving the last panel stop for
+ * whatever follows the trap in the page.
+ *
+ * **Traps stack.** Only the most recent active trap handles `Tab`, so a modal
+ * opened over another owns the keyboard until it closes, and then hands focus
+ * back to the element it was opened from, inside the one below.
+ *
+ * The listener is on `document` in the bubble phase, after React's own
+ * handlers: a menu that closes on `Tab` and returns focus to its trigger has
+ * already done so when the trap looks at where focus is.
+ *
+ * @param containerRef - The element focus is confined to.
+ * @param active - Whether the trap is armed.
+ * @returns Nothing.
  */
 export declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, active: boolean): void;
 
@@ -16490,6 +17219,13 @@ export declare function useOptionalI18n(): I18nContextValue | null;
  * fetcher, keeps the previous page visible while the next loads, and derives
  * `hasNext`/`hasPrev`/`pageCount`.
  *
+ * A structurally different `queryKey` (compared with TanStack's `hashKey`) is a
+ * different result set, so the page returns to 1. The reset is applied during
+ * render rather than in an effect: an effect would let one render go out with the
+ * new key and the old page, and that render is a request — on page 7 of an
+ * unfiltered list, applying a filter used to ask for page 7 of a two-page result
+ * and show an empty table (#356).
+ *
  * @example
  * const users = usePaginatedQuery<User>({
  *     queryKey: ["users"],
@@ -16501,7 +17237,11 @@ export declare function useOptionalI18n(): I18nContextValue | null;
 export declare function usePaginatedQuery<T>(options: UsePaginatedQueryOptions<T>): UsePaginatedQueryResult<T>;
 
 export declare interface UsePaginatedQueryOptions<T> extends Omit<UseQueryOptions<OffsetPage<T>, Error, OffsetPage<T>, QueryKey>, "queryKey" | "queryFn"> {
-    /** Base query key — the current page/sort is appended for cache isolation. */
+    /**
+     * Base query key — the current page/sort is appended for cache isolation.
+     * Put the applied filters here: when the key changes structurally, the page
+     * goes back to 1 in the same render.
+     */
     queryKey: QueryKey;
     /** Fetcher receiving the offset params; return the backend envelope. */
     queryFn: (params: OffsetParams) => Promise<OffsetPage<T>> | OffsetPage<T>;
@@ -16525,7 +17265,7 @@ export declare interface UsePaginatedQueryResult<T> {
     page: OffsetPage<T> | undefined;
     /** The rows of the current page (empty array while pending). */
     items: T[];
-    /** Current 1-based page number (controlled by the hook). */
+    /** Current 1-based page number (controlled by the hook; back to 1 on a new `queryKey`). */
     pageNumber: number;
     /** Total page count from the last successful response. */
     pageCount: number;
@@ -18569,6 +19309,36 @@ export declare interface WindowSize {
     height: number;
 }
 
+/**
+ * Prepend the "no filter" entry to an option list.
+ *
+ * A filter needs this as a real option, not as the select's placeholder: a
+ * placeholder reads as "nothing chosen yet", so the screen cannot tell whether
+ * the column is filtered. The entry uses {@link ALL_OPTION_VALUE}.
+ *
+ * @param options - The list to extend. It is not mutated.
+ * @param label - The entry's label. Defaults to `"Todos"`.
+ * @returns A new array with the entry first.
+ */
+export declare function withAllOption<T extends OptionLike>(options: readonly T[], label?: string): (T | OptionEntry)[];
+
+/**
+ * Prepend the empty entry a nullable field needs.
+ *
+ * Without it a `<select>` has no way to show "unset": a controlled
+ * `value=""` with no matching option reads back as the **first option** (measured
+ * in jsdom: `select.value === "a"`), so opening an edit form and saving it
+ * writes a value nobody chose. `Select`'s `placeholder` does not cover this — its
+ * entry is `disabled hidden`, so once something is picked the field can never be
+ * cleared again. The entry's value is `""`, which is what an unanswered nullable field
+ * submits.
+ *
+ * @param options - The list to extend. It is not mutated.
+ * @param label - The entry's label. Defaults to `"— Não definido —"`.
+ * @returns A new array with the entry first.
+ */
+export declare function withEmptyOption<T extends OptionLike>(options: readonly T[], label?: string): (T | OptionEntry)[];
+
 /**
  * A bound Zustand hook augmented with auto-generated per-field selector hooks
  * under `.use`. Reading a single field via `store.use.field()` subscribes the