tempest-react-sdk 0.24.0 → 0.26.0

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

@@ -32,6 +32,7 @@ import { InfiniteData } from '@tanstack/react-query';
 import { InputEventHandler } from 'react';
 import { InputHTMLAttributes } from 'react';
 import { JSX } from 'react';
+import { KeyboardEvent as KeyboardEvent_2 } from 'react';
 import { KeyboardEventHandler } from 'react';
 import { LabelHTMLAttributes } from 'react';
 import { lazy } from 'react';
@@ -46,6 +47,7 @@ import { Outlet } from 'react-router';
 import { Params } from 'react-router';
 import { Path } from 'react-hook-form';
 import { PersistOptions } from 'zustand/middleware';
+import { PointerEvent as PointerEvent_2 } from 'react';
 import { PointerEventHandler } from 'react';
 import { QueryClient } from '@tanstack/react-query';
 import { QueryKey } from '@tanstack/react-query';
@@ -304,6 +306,59 @@ export declare interface AppBarProps extends Omit<HTMLAttributes<HTMLElement>, "
 
 export declare type AppBarTone = "surface" | "primary" | "transparent";
 
+/**
+ * Apply a {@link KanbanMove} to a column list, returning new arrays.
+ *
+ * Exported because every consumer needs the same reducer.
+ *
+ * `toIndex` is the position of the card that was dropped **onto**, read from the
+ * board as it looked before the move. Inserting at that same index *after* removing
+ * the dragged card lands where the user aimed in both directions — moving down, the
+ * removal shifts the target up by one and the insertion lands after it; moving up,
+ * nothing shifted. Compensating for the shift (the "obvious" `toIndex - 1`) is what
+ * turns a one-step move down into a no-op.
+ *
+ * @param columns - Current board.
+ * @param move - The move reported by `onMove`.
+ * @returns A new column list, or the same reference when the move cannot apply.
+ */
+export declare function applyKanbanMove(columns: KanbanColumn[], move: KanbanMove): KanbanColumn[];
+
+/**
+ * Install a generated theme (or raw CSS) into the document.
+ *
+ * Safe to call outside a browser: with no `document` it is a no-op returning a
+ * no-op disposer, so app bootstrap code does not need a `typeof window` guard.
+ *
+ * @param theme - A {@link GeneratedTheme} from `createTheme`, or CSS text.
+ * @param options - Style element id and mount target.
+ * @returns A function that removes the injected `<style>` element.
+ *
+ * @example
+ * ```ts
+ * import { applyTheme, createTheme, themePresets } from "tempest-react-sdk";
+ *
+ * const dispose = applyTheme(createTheme(themePresets.violet));
+ * // later: dispose();
+ * ```
+ */
+export declare function applyTheme(theme: GeneratedTheme | string, options?: ApplyThemeOptions): () => void;
+
+/** Options for {@link applyTheme}. */
+export declare interface ApplyThemeOptions {
+    /**
+     * `id` of the managed `<style>` element. Reusing the same id replaces the
+     * previous theme; a distinct id lets two themes coexist (e.g. a scoped
+     * preview under its own selector). Default `"tempest-theme"`.
+     */
+    id?: string;
+    /**
+     * Node the `<style>` is appended to. Default `document.head`. Pass a shadow
+     * root to theme a single web component.
+     */
+    target?: Document | ShadowRoot | HTMLElement;
+}
+
 /**
  * Compose the Tempest app-wide providers in one place: error boundary →
  * TanStack Query → theme → i18n. Query and theme are on by default; i18n and
@@ -498,6 +553,55 @@ export declare interface AuthState<TUser> {
  */
 export declare function Avatar({ src, alt, name, size, status, className, onClick, }: AvatarProps): JSX.Element;
 
+/**
+ * Overlapping row of avatars with a `+N` overflow chip — participants of a
+ * meeting, assignees of a task, members of a team.
+ *
+ * The whole row is one `role="group"` with a single accessible name, and each
+ * avatar's name is exposed as its label. That is deliberate: announcing seven
+ * separate images with no relation between them is noise, and the overflow chip
+ * carries the remaining count so the total is never hidden from a screen reader.
+ *
+ * @example
+ * ```tsx
+ * <AvatarGroup
+ *   label="Participantes"
+ *   max={3}
+ *   items={[
+ *     { name: "Ada Lovelace", src: ada },
+ *     { name: "Grace Hopper" },
+ *     { name: "Alan Turing" },
+ *     { name: "Edsger Dijkstra" },
+ *   ]}
+ *   onOverflowClick={() => setDrawerOpen(true)}
+ * />
+ * ```
+ */
+export declare function AvatarGroup({ items, max, size, label, onOverflowClick, className, }: AvatarGroupProps): JSX.Element;
+
+/** One participant of the group. */
+export declare interface AvatarGroupItem {
+    /** Image URL. Falls back to initials from `name`. */
+    src?: string;
+    /** Full name — drives the initials and the accessible label. */
+    name: string;
+}
+
+export declare interface AvatarGroupProps {
+    items: AvatarGroupItem[];
+    /** How many avatars to show before collapsing into `+N`. Default `4`. */
+    max?: number;
+    size?: AvatarSize;
+    /** Accessible name of the group, e.g. `"Participantes"`. */
+    label?: string;
+    /**
+     * Called when the `+N` chip is activated — a natural hook for "see all
+     * participants". Without it the chip is plain text and not focusable.
+     */
+    onOverflowClick?: () => void;
+    className?: string;
+}
+
 export declare interface AvatarProps {
     src?: string;
     alt?: string;
@@ -1134,6 +1238,33 @@ export declare interface CollapsibleProps extends HTMLAttributes<HTMLDivElement>
     children: ReactNode;
 }
 
+/** A generated tint scale, keyed by step. */
+export declare type ColorScale = Record<ScaleStep, string>;
+
+/** Options for {@link createColorScale}. */
+declare interface ColorScaleOptions {
+    /**
+     * Pin step `500` to the input color's exact lightness. Default `true`.
+     *
+     * Right for a **brand** color: the hex a designer hands over is the one the
+     * buttons must be. Wrong for a **neutral**: nobody checks that `gray-500` is
+     * exactly the input, while everybody notices that a surface stopped being
+     * near-white — anchoring rescales both halves around the input and compresses
+     * exactly the range a neutral needs wide. With `false`, the ramp keeps the
+     * tuned lightness curve and the input only contributes hue and chroma (a warm
+     * or cool neutral, as asked).
+     */
+    anchor?: boolean;
+    /**
+     * Use the neutral lightness curve instead of the brand one. Default `false`.
+     *
+     * The neutral curve is wider at both ends, which is what keeps
+     * `text-muted`-on-`surface-3` above AA. Implies the ramp is meant for
+     * surfaces, borders and text rather than for an action color.
+     */
+    neutral?: boolean;
+}
+
 /**
  * Combobox — text input with a filterable dropdown of options.
  *
@@ -1202,6 +1333,25 @@ export declare interface CommandProps {
     className?: string;
 }
 
+/**
+ * Compare two arbitrary cell values with stable, type-aware ordering.
+ *
+ * The comparator every table in the SDK sorts with, so `DataTable` and
+ * `VirtualTable` agree on what "sorted" means. The type-aware branches exist
+ * because the naive `String(a) < String(b)` gets the two most common cases wrong:
+ * numbers would sort `10` before `9`, and dates would sort by their formatted
+ * text. Strings fall back to `localeCompare` with `numeric: true`, so `"item 2"`
+ * lands before `"item 10"`.
+ *
+ * `null` and `undefined` sort first, together — a missing value is not smaller
+ * than another missing value.
+ *
+ * @param a - First value.
+ * @param b - Second value.
+ * @returns Negative when `a < b`, positive when `a > b`, zero when equal.
+ */
+export declare function compareValues(a: unknown, b: unknown): number;
+
 /**
  * Conditionally wraps its children with `wrapper`.
  *
@@ -1311,6 +1461,9 @@ export declare interface ContextMenuProps {
     className?: string;
 }
 
+/** WCAG 2.x contrast ratio between two hex colors, from `1` to `21`. */
+export declare function contrastRatio(a: string, b: string): number;
+
 export { Control }
 
 export { Controller }
@@ -1412,6 +1565,20 @@ export declare interface CreateAuthStoreOptions<TUser> {
     initialToken?: string | null;
 }
 
+/**
+ * Build a ten-step tint scale from a single color.
+ *
+ * The input color's hue is kept throughout and its chroma sets the intensity of
+ * the whole ramp, so a muted brand color yields a muted scale instead of being
+ * "corrected" into something the brand never approved.
+ *
+ * @param hex - Any hex color (`#abc` or `#aabbcc`), the intended `500` step.
+ * @param mode - `"light"` for a light→dark ramp, `"dark"` for the inverted ramp
+ *   used under `[data-tempest-theme="dark"]`.
+ * @param options - See {@link ColorScaleOptions}.
+ */
+export declare function createColorScale(hex: string, mode?: "light" | "dark", options?: ColorScaleOptions): ColorScale;
+
 /**
  * Create a {@link DataProvider} bound to an {@link ApiClient}.
  *
@@ -1974,6 +2141,60 @@ export declare interface CreateTempestAuthOptions<TUser> {
     refreshBody?: (refreshToken: string | null) => unknown;
 }
 
+/**
+ * Generate `--tempest-*` overrides from a small brand description.
+ *
+ * Only the families you pass are generated; everything else falls through to the
+ * SDK's own tokens, so a theme stays a patch and not a fork of `colors.css`.
+ *
+ * @example
+ * ```ts
+ * import { applyTheme, createTheme } from "tempest-react-sdk";
+ *
+ * const theme = createTheme({
+ *   primary: "#7c3aed",
+ *   radius: "lg",
+ *   chart: ["#7c3aed", "#0ea5e9", "#22c55e", "#f59e0b"],
+ * });
+ *
+ * applyTheme(theme);
+ * ```
+ *
+ * @param options - Brand colors plus optional radius / chart / focus-ring tuning.
+ * @returns The light and dark token maps and the CSS text that carries them.
+ */
+export declare function createTheme(options?: CreateThemeOptions): GeneratedTheme;
+
+/** Input for {@link createTheme}. Every field is optional — omitted families keep the built-in tokens. */
+export declare interface CreateThemeOptions {
+    /** Brand color, used as the `500` step of the primary scale. */
+    primary?: string;
+    /** Neutral color, used as the `500` step of the gray scale (surfaces, borders, text). */
+    gray?: string;
+    /** Success color (`--tempest-success*`). */
+    success?: string;
+    /** Warning color (`--tempest-warning*`). */
+    warning?: string;
+    /** Danger color (`--tempest-danger*`). */
+    danger?: string;
+    /** Info color (`--tempest-info*`). */
+    info?: string;
+    /**
+     * Categorical series colors for `tempest-react-sdk/charts`, in cycle order.
+     * Written to `--tempest-chart-1` … `--tempest-chart-N`, so charts follow the
+     * theme instead of a hardcoded palette.
+     */
+    chart?: string[];
+    /** Corner radius scale. A preset name, or explicit per-step values. */
+    radius?: ThemeRadius | Partial<Record<"xs" | "sm" | "md" | "lg" | "xl" | "2xl", string>>;
+    /** Alpha of `--tempest-focus-ring-color`, derived from the brand color. Default `0.35`. */
+    focusRingAlpha?: number;
+    /** Selector the light tokens are written under. Default `":root"`. */
+    selector?: string;
+    /** Selector the dark tokens are written under. Default `'[data-tempest-theme="dark"]'`. */
+    darkSelector?: string;
+}
+
 /**
  * Open a WebSocket with automatic exponential-backoff reconnect, optional
  * heartbeat pings, and typed JSON parsing.
@@ -3068,6 +3289,16 @@ export declare interface ForProps<T> {
     fallback?: ReactNode;
 }
 
+/** A generated theme: token maps per color scheme, plus the CSS text that carries them. */
+export declare interface GeneratedTheme {
+    /** Light-scheme custom properties, without the leading `--`-less names (keys include `--`). */
+    light: Record<string, string>;
+    /** Dark-scheme custom properties. */
+    dark: Record<string, string>;
+    /** Both blocks rendered as CSS, ready for {@link applyTheme} or a stylesheet. */
+    css: string;
+}
+
 /**
  * Generate an RFC4122 v4 idempotency key (UUID). Use as the value for an
  * `Idempotency-Key` header on POST/PATCH requests that must not run twice.
@@ -3138,6 +3369,15 @@ export declare interface GetListParams {
     filters?: DataFilters;
 }
 
+/**
+ * Look up a preset by name.
+ *
+ * @param name - Preset name.
+ * @returns The preset options, or `undefined` when the name is unknown (so a
+ *   value coming from `localStorage` or a query string cannot crash boot).
+ */
+export declare function getThemePreset(name: string): CreateThemeOptions | undefined;
+
 /**
  * Thin wrapper over `@react-oauth/google`'s `<GoogleLogin>` that:
  *
@@ -3258,6 +3498,19 @@ export { HashRouter }
  */
 export declare function haversineKm(origin: Coordinate, destination: Coordinate): number;
 
+/** Convert a hex color to OKLCH. */
+export declare function hexToOklch(hex: string): Oklch;
+
+/** Parse a hex color into sRGB channels in the `0`–`1` range. */
+export declare function hexToRgb(hex: string): {
+    r: number;
+    g: number;
+    b: number;
+};
+
+/** Format a hex color as `rgb(r g b / alpha)`, for focus rings and overlays. */
+export declare function hexToRgbaString(hex: string, alpha: number): string;
+
 /** Inverse of `<Show>` — hides children when the condition matches. */
 export declare function Hide({ above, below, only, children }: HideProps): ReactNode;
 
@@ -3780,6 +4033,109 @@ export declare function isValidLatitude(value: number): boolean;
 /** True when `value` is a finite longitude in `[-180, 180]`. */
 export declare function isValidLongitude(value: number): boolean;
 
+/**
+ * Kanban board: columns of cards, reorderable within a column and movable across
+ * columns, by pointer **or** keyboard.
+ *
+ * The drag machine is `useSortable` — the board does not reimplement it. Cards are
+ * indexed globally across columns so a single sortable can span the whole board;
+ * the component translates that flat index back into `{ column, index }` for
+ * `onMove`, which is the shape an app actually needs.
+ *
+ * Nothing is mutated here: `onMove` reports the intent once and the parent applies
+ * it. That keeps the board a controlled value and avoids a re-render per pointer
+ * frame.
+ *
+ * ARIA shape: **one `listbox` per column**, named by the column title, containing
+ * only `option` cards. A single board-wide listbox does not survive the markup a
+ * board needs — `listbox` requires `option`/`group` children, and the column header
+ * and card wrapper in between break that ownership. Per-column listboxes also read
+ * better: a screen reader announces which column it is in and how many cards it
+ * holds. The column header is a plain `div`, not a `<header>`, because outside a
+ * sectioning element every `<header>` becomes a page-level banner landmark — with
+ * three columns that is three duplicate banners. An **empty** column is not marked
+ * as a listbox at all: a listbox with zero options fails `aria-required-children`,
+ * and "no cards" is exactly zero options.
+ *
+ * Known limitation: a **keyboard** move can only target positions that hold a card,
+ * because the move walks the flat index space of existing cards. Dropping into an
+ * empty column works by pointer; by keyboard it does not. Moving a card to a column
+ * that already has one card, then reordering, is the workaround until column-switch
+ * keys land.
+ *
+ * @example
+ * ```tsx
+ * const [columns, setColumns] = useState<KanbanColumn[]>([
+ *   { id: "todo", title: "A fazer", cards: [{ id: "1", content: "Corrigir login" }] },
+ *   { id: "doing", title: "Fazendo", cards: [] },
+ *   { id: "done", title: "Feito", cards: [], locked: true },
+ * ]);
+ *
+ * <Kanban
+ *   columns={columns}
+ *   onMove={({ cardId, fromColumn, toColumn, toIndex }) =>
+ *     setColumns((current) => applyKanbanMove(current, { cardId, fromColumn, toColumn, toIndex }))
+ *   }
+ * />
+ * ```
+ */
+export declare function Kanban({ columns, onMove, renderCard, emptyLabel, cardRoleDescription, label, disabled, className, }: KanbanProps): JSX.Element;
+
+/** One card on the board. */
+export declare interface KanbanCard {
+    /** Stable identifier, unique across the whole board. */
+    id: string;
+    /** Card body. A string renders as the card's title. */
+    content: ReactNode;
+}
+
+/** One column of the board. */
+export declare interface KanbanColumn {
+    /** Stable identifier, used as the drop group. */
+    id: string;
+    /** Column heading. */
+    title: ReactNode;
+    /** Cards in display order. */
+    cards: KanbanCard[];
+    /**
+     * Refuses drops into this column. The cards inside can still be picked up and
+     * moved elsewhere — a "done" column that no longer accepts work, for instance.
+     */
+    locked?: boolean;
+}
+
+/** Where a card ended up. */
+export declare interface KanbanMove {
+    cardId: string;
+    fromColumn: string;
+    toColumn: string;
+    /** Index within the destination column. */
+    toIndex: number;
+}
+
+export declare interface KanbanProps {
+    columns: KanbanColumn[];
+    /**
+     * Called once per committed move — on pointer release or on a keyboard drop.
+     * You own the data: apply the move and pass the new `columns` back.
+     */
+    onMove: (move: KanbanMove) => void;
+    /** Renders a card. Defaults to its `content`. */
+    renderCard?: (card: KanbanCard, column: KanbanColumn) => ReactNode;
+    /** Text shown in a column with no cards. */
+    emptyLabel?: ReactNode;
+    /** Announced per card, so a screen reader user learns the keyboard contract. */
+    cardRoleDescription?: string;
+    /**
+     * Accessible name of the board. A `listbox` without a name is unusable with a
+     * screen reader, so this has a default rather than being optional in practice.
+     */
+    label?: string;
+    /** Blocks all dragging. */
+    disabled?: boolean;
+    className?: string;
+}
+
 /**
  * Renders a `<kbd>` styled like a keyboard key — useful for shortcut hints.
  * Compose multiple keys by rendering siblings: `<Kbd>Ctrl</Kbd> + <Kbd>K</Kbd>`.
@@ -3902,6 +4258,67 @@ export declare interface LDClientLike {
     off?: (event: string, handler: () => void) => void;
 }
 
+/**
+ * Full-screen image viewer with keyboard navigation.
+ *
+ * `Esc` closes, `←`/`→` walk the gallery, `Home`/`End` jump to the ends. Focus is
+ * trapped inside while open and the page behind is scroll-locked, so the overlay
+ * behaves like the dialog it is instead of a fancy `<div>` the keyboard can escape.
+ *
+ * Only the current image is mounted; neighbours are **preloaded** via `Image()` so
+ * pressing `→` does not flash an empty frame.
+ *
+ * @example
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ * const [index, setIndex] = useState(0);
+ *
+ * <Lightbox
+ *   open={open}
+ *   items={photos.map((p) => ({ src: p.url, alt: p.description }))}
+ *   index={index}
+ *   onIndexChange={setIndex}
+ *   onClose={() => setOpen(false)}
+ * />
+ * ```
+ */
+export declare function Lightbox({ items, open, index, onIndexChange, onClose, showThumbnails, showCounter, loop, closeLabel, previousLabel, nextLabel, className, }: LightboxProps): JSX.Element | null;
+
+/** One item of the gallery. */
+export declare interface LightboxItem {
+    /** Full-size image URL. */
+    src: string;
+    /** Alt text. Required: a gallery of unlabeled images is unusable with a screen reader. */
+    alt: string;
+    /** Caption rendered under the image. */
+    caption?: string;
+    /** Thumbnail URL for the strip. Falls back to `src`. */
+    thumbnail?: string;
+}
+
+export declare interface LightboxProps {
+    items: LightboxItem[];
+    /** Whether the overlay is open. */
+    open: boolean;
+    /** Index shown while open. Default `0`. */
+    index?: number;
+    onIndexChange?: (index: number) => void;
+    onClose: () => void;
+    /** Renders the thumbnail strip. Default `true` when there is more than one item. */
+    showThumbnails?: boolean;
+    /** Renders the `3 / 12` counter. Default `true`. */
+    showCounter?: boolean;
+    /**
+     * Wrap around at the ends. Default `true` — in a photo viewer, hitting a dead
+     * end at the last image reads as a bug more often than as a boundary.
+     */
+    loop?: boolean;
+    closeLabel?: string;
+    previousLabel?: string;
+    nextLabel?: string;
+    className?: string;
+}
+
 export { Link }
 
 export declare interface ListOptions<TItem> {
@@ -4206,6 +4623,9 @@ export declare interface MoneyProps extends HTMLAttributes<HTMLSpanElement> {
     locale?: string;
 }
 
+/** Reorder helper: move `from` to `to`, returning a new array. */
+export declare function moveItem<T>(items: T[], from: number, to: number): T[];
+
 /**
  * MultiSelect — a filterable dropdown that selects many options, shown as
  * removable chips inside the field. Selecting toggles a value; Backspace on an
@@ -4377,6 +4797,78 @@ export { NavLink }
  */
 export declare function normalizeLongitude(longitude: number): number;
 
+/**
+ * Inbox panel for notifications the app has received.
+ *
+ * Deliberately presentational and controlled: it takes a list and emits intent.
+ * Where the list comes from — an API, a service-worker push, `localStorage` — and
+ * where read state is written are app decisions, and a component that assumed any
+ * of them would be wrong for most apps. `useNotificationInbox` is the companion
+ * that holds the state, including the service-worker bridge.
+ *
+ * It is also just the panel, not a popover: apps mount it inside their own
+ * `Popover`, `Drawer` or route. That keeps one component from owning both the
+ * inbox and a positioning strategy.
+ *
+ * @example
+ * const inbox = useNotificationInbox();
+ *
+ * <Popover trigger={<Button>Notificações ({inbox.unreadCount})</Button>}>
+ *     <NotificationCenter
+ *         items={inbox.items}
+ *         onMarkRead={inbox.markRead}
+ *         onMarkAllRead={inbox.markAllRead}
+ *         onDismiss={inbox.remove}
+ *         onSelect={(item) => item.url && navigate(item.url)}
+ *     />
+ * </Popover>
+ */
+export declare function NotificationCenter({ items, title, onSelect, onMarkRead, onMarkAllRead, onDismiss, renderIcon, locale, emptyState, now, className, ...rest }: NotificationCenterProps): JSX.Element;
+
+export declare interface NotificationCenterProps extends Omit<HTMLAttributes<HTMLDivElement>, OverriddenDomProps> {
+    /** Entries to show. Rendered in the order given — `useNotificationInbox` sorts newest first. */
+    items: readonly NotificationItem[];
+    /**
+     * Panel heading. Pass `null` to render the list with no header.
+     *
+     * Widened from the DOM `title` attribute (a `string`) on purpose: this is a
+     * rendered heading, not a tooltip, so it takes a node.
+     */
+    title?: ReactNode;
+    /** Activate an entry: click, `Enter` or `Space`. Also marks it read when `onMarkRead` is set. */
+    onSelect?: (item: NotificationItem) => void;
+    /** Mark one entry as read. Enables the per-item read control. */
+    onMarkRead?: (id: string) => void;
+    /** Mark every entry as read. Enables the header action. */
+    onMarkAllRead?: () => void;
+    /** Remove one entry. Enables the per-item dismiss control. */
+    onDismiss?: (id: string) => void;
+    /** Icon rendered at the leading edge of each row — an `<Icon name={…} />`, say. */
+    renderIcon?: (item: NotificationItem) => ReactNode;
+    /** Locale for the relative timestamps. Default `"pt-BR"`. */
+    locale?: RelativeTimeLocale;
+    /** Shown when `items` is empty. */
+    emptyState?: ReactNode;
+    /** Reference point for the relative timestamps. Default: now, at render time. */
+    now?: number;
+}
+
+/** One entry in the inbox. */
+export declare interface NotificationItem {
+    /** Stable id. Re-adding an existing id updates that entry instead of duplicating it. */
+    id: string;
+    title: string;
+    /** Body text. Optional — a title-only notification is a legitimate shape. */
+    body?: string;
+    /** Epoch milliseconds. Used for ordering and for the relative timestamp. */
+    receivedAt: number;
+    read?: boolean;
+    /** Where activating the notification should take the user. */
+    url?: string;
+    /** Free-form payload the app passes through, e.g. the entity it refers to. */
+    data?: Record<string, unknown>;
+}
+
 /**
  * Module-level singleton progress controller. Drive it imperatively from
  * anywhere (router transitions, fetch interceptors) and render the visual bar
@@ -4701,6 +5193,35 @@ export declare interface OffsetParams {
     ascending?: boolean;
 }
 
+/**
+ * Color math behind {@link createTheme} — OKLab/OKLCH conversions, tint scale
+ * generation and WCAG contrast picking.
+ *
+ * Everything here is pure and dependency-free: the SDK generates brand ramps at
+ * runtime in the browser, so a color library would be a disproportionate cost
+ * for ~150 lines of well-specified math. OKLCH is used instead of HSL because
+ * HSL lightness is not perceptual — an HSL ramp of a yellow and of a blue at the
+ * same `L` read as wildly different brightness, which is exactly what breaks a
+ * generated palette.
+ */
+/** A color in the OKLCH space: perceptual lightness, chroma and hue. */
+export declare interface Oklch {
+    /** Perceptual lightness, `0` (black) to `1` (white). */
+    l: number;
+    /** Chroma (colorfulness). `0` is gray; sRGB rarely exceeds `~0.37`. */
+    c: number;
+    /** Hue angle in degrees, `0`–`360`. */
+    h: number;
+}
+
+/**
+ * Convert OKLCH to a hex color, reducing chroma until the result fits sRGB.
+ *
+ * Lightness and hue are preserved: desaturating is far less noticeable than
+ * shifting either of them, and a naive channel clamp would do both.
+ */
+export declare function oklchToHex(color: Oklch): string;
+
 /**
  * Create a new object with the given `keys` removed from `obj`.
  *
@@ -4785,7 +5306,12 @@ export declare interface OutboxEntry<TPayload = unknown> {
     op: OutboxOp;
     /** Primary key of the record the mutation targets. */
     recordId: string;
-    /** Epoch milliseconds when the mutation was queued. */
+    /**
+     * Epoch milliseconds when the mutation was queued, and the FIFO sort key for
+     * `listPending()` and the delivery loop. Strictly increasing per engine
+     * instance: entries queued inside the same millisecond are spaced by 1ms so
+     * the order never depends on how the index breaks a tie.
+     */
     enqueuedAt: number;
     /** How many delivery attempts have been made so far. */
     attempts: number;
@@ -4807,6 +5333,16 @@ export declare type OutboxOp = "create" | "update" | "delete";
 
 export { Outlet }
 
+/**
+ * DOM attributes this component redefines.
+ *
+ * `title` becomes a rendered heading node instead of a tooltip string, and
+ * `onSelect` becomes "an entry was activated" instead of the DOM text-selection
+ * event. Both would be type errors if merged, and silently confusing if allowed
+ * through.
+ */
+declare type OverriddenDomProps = "children" | "title" | "onSelect";
+
 /**
  * Page wrapper with header + (optional) toolbar + content + footer. Pairs
  * with `Container` when you want a max-width content well.
@@ -5351,6 +5887,29 @@ export declare interface RatingStarsProps {
     className?: string;
 }
 
+/**
+ * Pick the readable foreground for a background, by contrast ratio.
+ *
+ * Used for `--tempest-primary-foreground`: a generated brand color can land
+ * anywhere on the lightness axis, and hardcoding white would silently produce
+ * unreadable buttons for light brands (yellow, lime, cyan).
+ */
+export declare function readableForeground(background: string, light?: string, dark?: string): string;
+
+/**
+ * Read a token's computed value from an element (default: `<html>`).
+ *
+ * Useful to bridge CSS tokens into JS that cannot take a `var()` — canvas
+ * drawing, chart libraries that set SVG attributes, `<meta name="theme-color">`.
+ *
+ * @param name - Token name, with or without the leading `--`.
+ * @param element - Element to resolve against. Omit for `document.documentElement`;
+ *   an explicit `null` (a ref that has not attached yet) reads nothing rather than
+ *   silently falling back to the root, whose value may be a different theme.
+ * @returns The trimmed value, or `""` when unset or outside a browser.
+ */
+export declare function readThemeToken(name: string, element?: Element | null): string;
+
 export { redirect }
 
 /** Recommended refetch intervals (milliseconds). */
@@ -5472,6 +6031,9 @@ export declare interface RegisterServiceWorkerOptions {
     reloadOnActivate?: boolean;
 }
 
+/** WCAG 2.x relative luminance of a hex color. */
+export declare function relativeLuminance(hex: string): number;
+
 /**
  * Render a date as a human-friendly relative-time string (e.g. "5 min atrás")
  * inside a semantic `<time>` element with a machine-readable `dateTime`.
@@ -5635,6 +6197,9 @@ export declare interface RetryOptions {
     signal?: AbortSignal;
 }
 
+/** Serialize sRGB channels (`0`–`1`, clamped) back to a `#rrggbb` string. */
+export declare function rgbToHex(r: number, g: number, b: number): string;
+
 export declare interface RoleAccessControlConfig {
     /** Permission strings granted directly, regardless of role. */
     permissions?: string[];
@@ -5759,6 +6324,9 @@ export declare interface SafeAreaProps extends HTMLAttributes<HTMLDivElement> {
     children?: ReactNode;
 }
 
+/** The ten steps of a Tempest tint scale, lightest to darkest. */
+export declare type ScaleStep = 50 | 100 | 200 | 300 | 400 | 500 | 600 | 700 | 800 | 900;
+
 /**
  * A styled scroll container that overflows on the chosen axis and renders a
  * thin custom scrollbar (WebKit) while staying fully functional in browsers
@@ -5988,6 +6556,77 @@ export declare interface SidebarProps extends Omit<HTMLAttributes<HTMLElement>,
     collapsedWidth?: number | string;
 }
 
+/**
+ * Signature capture on a canvas — the "sign here" field of a delivery receipt,
+ * a service order, a term of acceptance.
+ *
+ * Strokes are kept as point lists and the canvas is **redrawn** from them, which
+ * is what makes `undo` possible at all: a canvas holds pixels, not history, so
+ * removing the last stroke means replaying the rest.
+ *
+ * The backing store is scaled by `devicePixelRatio`, so the line is crisp on a
+ * phone instead of the blurry 1x bitmap a naive canvas produces.
+ *
+ * @example
+ * ```tsx
+ * const pad = useRef<SignaturePadHandle>(null);
+ * const [empty, setEmpty] = useState(true);
+ *
+ * async function submit() {
+ *   const blob = await pad.current?.toBlob("image/png");
+ *   if (blob) await api.upload("/receipts/42/signature", blob);
+ * }
+ *
+ * <SignaturePad ref={pad} label="Assinatura do cliente" onEmptyChange={setEmpty} />
+ * <Button disabled={empty} onClick={submit}>Enviar</Button>
+ * ```
+ */
+export declare const SignaturePad: ForwardRefExoticComponent<SignaturePadProps & RefAttributes<SignaturePadHandle>>;
+
+/** Imperative handle exposed through `ref`. */
+export declare interface SignaturePadHandle {
+    /** Drop every stroke. */
+    clear: () => void;
+    /** Drop the last stroke. */
+    undo: () => void;
+    /** `true` while nothing has been drawn. */
+    isEmpty: () => boolean;
+    /** Export as a data URL. Returns `""` when the canvas is unavailable. */
+    toDataURL: (type?: string, quality?: number) => string;
+    /** Export as a `Blob` — what you actually upload. `null` when unavailable. */
+    toBlob: (type?: string, quality?: number) => Promise<Blob | null>;
+}
+
+export declare interface SignaturePadProps {
+    /** Drawing surface width in CSS pixels. Default `400`. */
+    width?: number;
+    /** Drawing surface height in CSS pixels. Default `160`. */
+    height?: number;
+    /**
+     * Stroke color. Defaults to the canvas' computed `color`, which the
+     * stylesheet binds to `--tempest-text` — so the signature follows the theme
+     * (including dark mode) instead of being hardcoded black.
+     */
+    penColor?: string;
+    /** Stroke width in CSS pixels. Default `2`. */
+    penWidth?: number;
+    /** Blocks drawing and dims the surface. */
+    disabled?: boolean;
+    /** Accessible name of the surface. Default `"Signature"`. */
+    label?: string;
+    /** Called on the first move of each stroke. */
+    onBegin?: () => void;
+    /** Called when a stroke ends, with the current image as a data URL. */
+    onEnd?: (dataUrl: string) => void;
+    /** Called whenever the emptiness changes — wire it to a submit button. */
+    onEmptyChange?: (isEmpty: boolean) => void;
+    /** Renders the Clear/Undo buttons. Default `true`. */
+    showActions?: boolean;
+    clearLabel?: string;
+    undoLabel?: string;
+    className?: string;
+}
+
 /** Loading placeholder block. Use `variant="text"` for inline lines, `circle` for avatars. */
 export declare function Skeleton({ variant, width, height, className, style }: SkeletonProps): JSX.Element;
 
@@ -6049,6 +6688,40 @@ export declare interface SliderProps {
  */
 export declare function slugify(input: string): string;
 
+/** Where a dragged item would land if dropped now. */
+export declare interface SortableDropTarget {
+    /** Index the item started at, within its own group. */
+    from: number;
+    /** Index it would move to, within the destination group. */
+    to: number;
+    /**
+     * Group the item started in — a Kanban column, for instance. `undefined` for a
+     * plain single-list sortable.
+     */
+    fromGroup?: string;
+    /** Destination group. Equal to `fromGroup` when the move stays in one group. */
+    toGroup?: string;
+}
+
+/** Props to spread on each sortable item. */
+export declare interface SortableItemProps {
+    /** Marks the item for hit-testing. */
+    "data-sortable-index": number;
+    /** Group the item belongs to, when the sortable spans several lists. */
+    "data-sortable-group"?: string;
+    /** `true` while this item is the one being moved. */
+    "data-sortable-active"?: boolean;
+    /** Grab handle wiring: starts a pointer drag. */
+    onPointerDown: (event: PointerEvent_2<HTMLElement>) => void;
+    /** Keyboard reordering — see {@link UseSortableResult}. */
+    onKeyDown: (event: KeyboardEvent_2<HTMLElement>) => void;
+    /** Puts the item in the tab order so the keyboard path is reachable. */
+    tabIndex: number;
+    role: "option";
+    "aria-roledescription": string;
+    "aria-selected": boolean;
+}
+
 export declare type SortDirection = "asc" | "desc";
 
 /**
@@ -6158,6 +6831,8 @@ export declare type StatTrend = "up" | "down" | "flat";
 
 export declare interface StepItem {
     label: ReactNode;
+    /** Secondary line under the label — a hint, or "optional". */
+    description?: ReactNode;
 }
 
 /**
@@ -6165,7 +6840,7 @@ export declare interface StepItem {
  * render as completed; the step at `current` is active; later steps are
  * upcoming.
  */
-export declare function Stepper({ steps, current, orientation, className }: StepperProps): JSX.Element;
+export declare function Stepper({ steps, current, orientation, onStepClick, className, }: StepperProps): JSX.Element;
 
 /**
  * Numeric +/− stepper. Common in checkout quantity selectors and admin
@@ -6208,6 +6883,12 @@ export declare interface StepperProps {
     /** Index of the currently active step (0-based). */
     current: number;
     orientation?: "horizontal" | "vertical";
+    /**
+     * Makes each step activatable. Without it the steps are a read-only
+     * indicator, which is the right default — in a gated flow, jumping ahead
+     * would skip the gates.
+     */
+    onStepClick?: (index: number) => void;
     className?: string;
 }
 
@@ -6601,6 +7282,9 @@ export declare interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAr
     wrapperClassName?: string;
 }
 
+/** The default `<style>` element id owned by {@link applyTheme}. */
+export declare const THEME_STYLE_ID = "tempest-theme";
+
 export declare interface ThemeContextValue {
     /** Raw user preference (light / dark / system). */
     theme: ThemeMode;
@@ -6612,6 +7296,17 @@ export declare interface ThemeContextValue {
     toggle: () => void;
 }
 
+/**
+ * Contrast ratio of `--tempest-primary-foreground` over the brand color.
+ *
+ * Exposed so an app (or a test) can assert its own brand clears WCAG AA (4.5) for
+ * body text or AA-large (3.0) for button labels, instead of trusting the pick.
+ *
+ * @param options - The same input given to {@link createTheme}.
+ * @returns The ratio, or `null` when no `primary` was provided.
+ */
+export declare function themeContrast(options: CreateThemeOptions): number | null;
+
 /**
  * Plain HTML snippet that sets `data-tempest-theme` on `<html>` before React
  * hydrates. Inline this in `<head>` to avoid a flash of the wrong theme on
@@ -6624,6 +7319,17 @@ export declare function themeInitScript(options?: GetInitialThemeOptions): strin
 
 export declare type ThemeMode = "light" | "dark" | "system";
 
+/** Name of a bundled preset. */
+export declare type ThemePresetName = "tempest" | "violet" | "emerald" | "rose" | "slate" | "amber";
+
+/**
+ * The bundled presets.
+ *
+ * `tempest` restates the SDK's own defaults — useful as a starting point to
+ * tweak, and as the "reset to default" entry in a theme picker.
+ */
+export declare const themePresets: Record<ThemePresetName, CreateThemeOptions>;
+
 /**
  * Wire dark/light theming. Writes a data attribute on a target element (the
  * `<html>` element by default) and exposes the current preference via
@@ -6667,6 +7373,12 @@ export declare interface ThemeProviderProps {
     };
 }
 
+/** Radius presets, applied to the whole `--tempest-radius-*` family at once. */
+export declare type ThemeRadius = "none" | "sm" | "md" | "lg" | "xl" | "full";
+
+/** Status token families that {@link createTheme} can regenerate. */
+export declare type ThemeStatus = "success" | "warning" | "danger" | "info";
+
 /**
  * Create a throttled version of `fn` with leading and trailing edges.
  *
@@ -6973,6 +7685,80 @@ export declare interface TravelEstimate {
  */
 export declare type TravelMode = "car" | "motorcycle" | "bus";
 
+/** One node of the tree. Children make it a branch; no children makes it a leaf. */
+export declare interface TreeNode {
+    /** Stable identifier, unique across the whole tree. */
+    id: string;
+    /** Rendered label. */
+    label: ReactNode;
+    /** Child nodes. An empty array still renders as a branch (an empty folder). */
+    children?: TreeNode[];
+    /** Icon rendered before the label. */
+    icon?: ReactNode;
+    /** Blocks selection and expansion, and skips the node in keyboard navigation. */
+    disabled?: boolean;
+}
+
+/**
+ * Accessible tree for hierarchical data — categories, permissions, folders, an
+ * org chart.
+ *
+ * Implements the `tree` role with **roving tabindex**: exactly one row is
+ * tabbable, and the arrow keys move focus within the widget. That is what keeps a
+ * 500-node tree from adding 500 stops to the page's tab order.
+ *
+ * Keyboard map: `↓`/`↑` move, `→` expands (or descends), `←` collapses (or goes to
+ * the parent), `Home`/`End` jump to the first/last visible row, `Enter`/`Space`
+ * select.
+ *
+ * The chevron is decoration (`aria-hidden`), not a button: the row itself carries
+ * `aria-expanded`, so a second focusable control there would only add noise for a
+ * screen reader while duplicating an action the keyboard map already has. It still
+ * accepts a click, with the event stopped so it toggles without also selecting.
+ *
+ * @example
+ * ```tsx
+ * const nodes: TreeNode[] = [
+ *   {
+ *     id: "vendas",
+ *     label: "Vendas",
+ *     children: [
+ *       { id: "vendas.ler", label: "Ler" },
+ *       { id: "vendas.editar", label: "Editar" },
+ *     ],
+ *   },
+ *   { id: "config", label: "Configurações", children: [] },
+ * ];
+ *
+ * <TreeView nodes={nodes} defaultExpandedIds={["vendas"]} onSelect={(node) => console.log(node.id)} />
+ * ```
+ */
+export declare function TreeView({ nodes, expandedIds, defaultExpandedIds, onExpandedChange, selectedId, defaultSelectedId, onSelect, toggleOnSelect, label, className, }: TreeViewProps): JSX.Element;
+
+export declare interface TreeViewProps {
+    /** Root nodes. */
+    nodes: TreeNode[];
+    /** Controlled expanded ids. */
+    expandedIds?: string[];
+    /** Uncontrolled initial expanded ids. */
+    defaultExpandedIds?: string[];
+    onExpandedChange?: (expandedIds: string[]) => void;
+    /** Controlled selected id. `null` means nothing selected. */
+    selectedId?: string | null;
+    /** Uncontrolled initial selection. */
+    defaultSelectedId?: string | null;
+    onSelect?: (node: TreeNode) => void;
+    /**
+     * Selecting a branch also toggles it. Default `true` — matches how a file
+     * explorer behaves; set `false` when a branch is itself a meaningful choice
+     * (a category that owns items, for instance).
+     */
+    toggleOnSelect?: boolean;
+    /** Accessible name for the tree. */
+    label?: string;
+    className?: string;
+}
+
 /**
  * Truncate a string to `max` characters, appending `suffix` when cut.
  * Returns the original when shorter than (or equal to) `max`.
@@ -7189,6 +7975,11 @@ export declare interface UseAsyncResult<T> {
 }
 
 /**
+ * The player lives in a state initializer, not in a lazily-written ref: the
+ * initializer runs exactly once and is not a side effect during render, which is
+ * what the ref version was. The player identity never changes, so state holds it
+ * fine and the value is non-null from the first render.
+ *
  * Hook-managed audio player. Each component instance gets its own
  * {@link AudioPlayer}, so unmounting cleanly stops playback. Useful for
  * notification chimes, UI feedback sounds, and per-component soundtracks.
@@ -7393,6 +8184,11 @@ export declare function useDebounce<T>(value: T, delay?: number): T;
  * Memoize a value with a structural equality check. Use when an object/array
  * created during render is fed to `useEffect` dependencies and you want to
  * avoid spurious effect runs when only the reference changes.
+ *
+ * The cache is a ref read and written during render. That is flagged by the React
+ * Compiler rules and is nonetheless correct here: the write is idempotent — a
+ * discarded render either wrote a structurally equal value or nothing at all — so
+ * replaying the render cannot change the result.
  */
 export declare function useDeepMemo<T>(value: T): T;
 
@@ -7669,6 +8465,11 @@ export declare function useInterval(fn: () => void, delay: number | null): void;
 /**
  * Return `true` on the first render of the component and `false` thereafter.
  *
+ * Reads *and* flips a ref during render, which the React Compiler rules flag on
+ * sight — here it is the entire hook. Under StrictMode's double render in dev the
+ * second pass already sees `false`, so treat the result as "first committed
+ * render" and not as a strict render counter.
+ *
  * @returns Whether the current render is the first one.
  */
 export declare function useIsFirstRender(): boolean;
@@ -7841,6 +8642,76 @@ export declare function useModals(): ModalsApi;
 
 export { useNavigate }
 
+/**
+ * Client-side inbox state for received notifications.
+ *
+ * Newest first, deduplicated by `id`, capped at `limit`. Pairs with
+ * `NotificationCenter` for the UI and with the `push` module for the source:
+ * point a service worker's `postMessage` at it and a push that arrives while the
+ * app is open shows up in the inbox instead of only as an OS notification.
+ *
+ * Persistence is deliberately left out — where an inbox belongs (server, Dexie,
+ * `localStorage`) is an app decision. Use `onChange` to write it wherever it goes,
+ * and `initialItems` to read it back.
+ *
+ * @example
+ * const inbox = useNotificationInbox({
+ *     initialItems: await api.notifications.list(),
+ *     onChange: (items) => storage.set("inbox", items),
+ * });
+ *
+ * <NotificationCenter
+ *     items={inbox.items}
+ *     onMarkRead={inbox.markRead}
+ *     onMarkAllRead={inbox.markAllRead}
+ *     onDismiss={inbox.remove}
+ * />
+ */
+export declare function useNotificationInbox(options?: UseNotificationInboxOptions): UseNotificationInboxResult;
+
+export declare interface UseNotificationInboxOptions {
+    /** Entries the inbox starts with — typically what the API returned. */
+    initialItems?: readonly NotificationItem[];
+    /**
+     * Listen for `message` events from the service worker and add whatever
+     * arrives. Default `true`.
+     *
+     * This is the missing half of web push: a service worker runs outside the
+     * page and cannot touch React state, so a push that arrives while the app is
+     * open shows an OS notification and then vanishes as far as the UI is
+     * concerned. Have the worker `postMessage` the payload and it lands here.
+     */
+    listenToServiceWorker?: boolean;
+    /**
+     * Message `type` to accept from the worker. Default `"tempest:notification"`.
+     *
+     * Filtering by type matters because the SW message channel is shared — a
+     * sync-progress ping or a cache-updated notice would otherwise show up in the
+     * user's inbox.
+     */
+    messageType?: string;
+    /**
+     * Cap on stored entries; the oldest are dropped past it. Default `100`.
+     *
+     * An inbox fed by push grows without bound otherwise, and it lives in memory.
+     */
+    limit?: number;
+    /** Called whenever the list changes — the hook for persisting it. */
+    onChange?: (items: readonly NotificationItem[]) => void;
+}
+
+export declare interface UseNotificationInboxResult {
+    items: NotificationItem[];
+    unreadCount: number;
+    /** Add an entry, or update the existing one with the same id. */
+    add: (item: NotificationItem) => void;
+    markRead: (id: string) => void;
+    markUnread: (id: string) => void;
+    markAllRead: () => void;
+    remove: (id: string) => void;
+    clear: () => void;
+}
+
 /**
  * Run an OAuth-callback "exchange" exactly once on mount. Designed for
  * `/callback` routes that receive provider redirects and need to swap a
@@ -8383,10 +9254,126 @@ export declare interface UseSetResult<T> {
     size: number;
 }
 
+/**
+ * Drag-to-reorder for a list, with a **keyboard path of equal standing**.
+ *
+ * Pointer events cover mouse, touch and stylus through one code path, and pointer
+ * capture keeps the drag alive when the pointer leaves the item. `Space` picks an
+ * item up, the arrows move it, `Space`/`Enter` drops it and `Escape` cancels —
+ * because a reorder that only works by dragging excludes keyboard users
+ * completely, which is where most drag-and-drop implementations fail.
+ *
+ * The hook owns interaction only: it never mutates your data. `onReorder` fires
+ * once per committed move and you apply it, typically with {@link moveItem}. That
+ * keeps the list a controlled value and avoids a re-render per pointer frame.
+ *
+ * Hit-testing reads the live DOM rects of `[data-sortable-index]` children rather
+ * than assuming a fixed row height, so it works with rows of different sizes.
+ *
+ * A change in `itemCount` cancels an in-flight drag: the list no longer has the
+ * indices the drag was based on, and committing anyway would move the wrong row.
+ *
+ * Note for consumers: the indices and groups are exposed as **state** (so rendering
+ * from them is reactive) and mirrored into refs only so the window-level `pointerup`
+ * listener can read both synchronously. Because the handlers returned by
+ * `getItemProps` close over those mirrors, the React Compiler `refs` rule reports
+ * the *call site* — a component spreading these props may need a file-level
+ * exemption, as `Kanban` documents.
+ *
+ * @example
+ * ```tsx
+ * const [items, setItems] = useState(["Alfa", "Bravo", "Charlie"]);
+ * const sortable = useSortable({
+ *   itemCount: items.length,
+ *   onReorder: ({ from, to }) => setItems((current) => moveItem(current, from, to)),
+ * });
+ *
+ * <ul {...sortable.getListProps()} aria-label="Prioridade" ref={sortable.setContainer}>
+ *   {items.map((item, index) => (
+ *     <li key={item} {...sortable.getItemProps(index)}>
+ *       {item}
+ *     </li>
+ *   ))}
+ * </ul>
+ * ```
+ */
+export declare function useSortable(options: UseSortableOptions): UseSortableResult;
+
+export declare interface UseSortableOptions {
+    /**
+     * How many items are in the sortable. Changing it cancels an in-flight drag.
+     *
+     * With groups, pass the **total** across groups: the number only has to change
+     * whenever the indices the drag was based on stop being valid.
+     */
+    itemCount: number;
+    /**
+     * Called once, when a move is committed — on pointer release or on a keyboard
+     * move. Never called mid-drag, so a controlled list re-renders once instead of
+     * on every pointer frame.
+     */
+    onReorder: (target: SortableDropTarget) => void;
+    /** Blocks all interaction. */
+    disabled?: boolean;
+    /**
+     * Description announced for each item, so a screen reader user learns the
+     * keyboard contract. Default is in English — override it to localize.
+     */
+    roleDescription?: string;
+}
+
+export declare interface UseSortableResult {
+    /** Index being dragged, or `null` when idle. */
+    activeIndex: number | null;
+    /** Index the item would land on, or `null` when idle. */
+    overIndex: number | null;
+    /** Group the dragged item came from, when using groups. */
+    activeGroup?: string;
+    /** Group the item is currently over, when using groups. */
+    overGroup?: string;
+    /**
+     * Spread on each item. Pass `group` when the sortable spans several lists (a
+     * Kanban column id), so a drop can land in a different group.
+     */
+    getItemProps: (index: number, group?: string) => SortableItemProps;
+    /**
+     * Spread on an **empty** group's drop area, so an item can be moved into a
+     * column that has no cards yet — hit-testing works off item rects, and a group
+     * with no items has none.
+     */
+    getEmptyGroupProps: (group: string) => {
+        "data-sortable-group": string;
+        "data-sortable-empty": true;
+    };
+    /** Spread on the list container (`role="listbox"` + a label of your own). */
+    getListProps: () => {
+        role: "listbox";
+        "aria-orientation": "vertical";
+    };
+    /** Abort the current drag without reordering. */
+    cancel: () => void;
+    /**
+     * Callback ref for the element that contains the sortable items — hit-testing
+     * searches inside it.
+     *
+     * Named `setContainer` rather than `ref` because it is a **callback**, not a ref
+     * object: `ref={sortable.setContainer}`. The old name also read as a readable
+     * ref to the React Compiler rules, which flagged every consumer.
+     */
+    setContainer: (node: HTMLElement | null) => void;
+}
+
 /**
  * Returns a stable function reference that always invokes the latest
  * `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
+ * `useEffectEvent` once it ships as stable.
  */
 export declare function useStableCallback<TArgs extends unknown[], TReturn>(callback: (...args: TArgs) => TReturn): (...args: TArgs) => TReturn;
 
@@ -8635,6 +9622,95 @@ export declare interface VirtualListProps<T> {
     style?: CSSProperties;
 }
 
+/**
+ * A table that stays responsive at 10k+ rows by rendering only the visible window.
+ *
+ * `Table` renders every row it is given and `DataTable` paginates to keep that
+ * count small; neither has an answer for "show me all 40 000 rows in one
+ * scrollable grid". This does, at the cost of one constraint: **`rowHeight` must
+ * be uniform**, since mapping a scroll offset to a row index is what makes the
+ * window computable without measuring anything.
+ *
+ * It stays a real `<table>`. The window is produced by two spacer rows — one
+ * above the visible slice, one below — instead of absolutely positioning rows.
+ * That is deliberate: `position: absolute` on `<tr>` collapses table layout, so
+ * every column width would have to be computed by hand, and the element would
+ * stop being a table for assistive technology. With spacer rows the browser keeps
+ * doing column layout and screen readers keep announcing a grid.
+ *
+ * Because only a slice is in the DOM, `aria-rowcount` on the table and
+ * `aria-rowindex` on each row carry the real numbers — without them a screen
+ * reader announces "row 3 of 20" while the user is on row 5003 of 40 000.
+ *
+ * @example
+ * <VirtualTable
+ *     data={rows}
+ *     columns={[
+ *         { key: "id", header: "#", width: 80, sortable: true },
+ *         { key: "name", header: "Nome", width: 240, sortable: true },
+ *         { key: "total", header: "Total", align: "right", width: 120, sortable: true },
+ *     ]}
+ *     rowHeight={40}
+ *     height={480}
+ *     rowKey={(row) => row.id}
+ * />
+ */
+export declare function VirtualTable<T>({ data, columns, rowHeight, height, overscan, rowKey, initialSort, onRowClick, emptyMessage, caption, scrollToIndex, className, ...rest }: VirtualTableProps<T>): JSX.Element;
+
+export declare interface VirtualTableColumn<T> {
+    /** Property of the row this column reads from. Doubles as the cell key. */
+    key: keyof T;
+    /** Column heading. */
+    header: ReactNode;
+    /** Custom cell renderer. Defaults to `row[key]`. */
+    render?: (row: T, index: number) => ReactNode;
+    /** Enable click-to-sort on this column's header. */
+    sortable?: boolean;
+    /** Text alignment. */
+    align?: TableAlign;
+    /**
+     * Column width. Recommended for every column: virtualized rows enter and
+     * leave the DOM as you scroll, so letting the browser auto-size columns from
+     * whatever is currently rendered makes them jump mid-scroll.
+     */
+    width?: string | number;
+}
+
+export declare interface VirtualTableProps<T> extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Full dataset. Every row is accounted for; only the visible ones render. */
+    data: T[];
+    /** Column definitions. */
+    columns: VirtualTableColumn<T>[];
+    /**
+     * Row height in px. Must be uniform and must match what the CSS produces,
+     * because it is what maps scroll offset to row index.
+     */
+    rowHeight: number;
+    /** Height of the scroll viewport — a number of px or any CSS length. */
+    height: number | string;
+    /** Rows rendered above and below the viewport. Default `4`. */
+    overscan?: number;
+    /** Stable key extractor. Defaults to the row's index in `data`. */
+    rowKey?: (row: T, index: number) => string | number;
+    /** Sort applied before any header interaction. */
+    initialSort?: VirtualTableSort<T>;
+    /** Called when a row is activated by click, `Enter` or `Space`. */
+    onRowClick?: (row: T, index: number) => void;
+    /** Content shown when `data` is empty. */
+    emptyMessage?: ReactNode;
+    /** Accessible name for the table. Rendered as a visually hidden `<caption>`. */
+    caption?: ReactNode;
+    /** Scroll this row into view whenever it changes. */
+    scrollToIndex?: number;
+}
+
+export declare interface VirtualTableSort<T> {
+    key: keyof T;
+    direction: VirtualTableSortDirection;
+}
+
+export declare type VirtualTableSortDirection = "asc" | "desc";
+
 /**
  * Render content that is hidden visually but remains available to screen
  * readers — the standard "sr-only" pattern. Useful for accessible labels on
@@ -9067,6 +10143,115 @@ export declare type WithSelectors<S> = S extends {
  */
 export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
 
+/**
+ * Multi-step flow: step indicator, one body at a time, and navigation that
+ * respects per-step validation.
+ *
+ * `Stepper` draws the indicator; this owns the part every app was rewriting — the
+ * active index, the async gate before advancing, the disabled/pending buttons and
+ * the completion call.
+ *
+ * Only the active step's body is mounted. Uncommitted input in a step you leave is
+ * therefore lost unless the state lives outside (react-hook-form's `FormProvider`,
+ * a store, a parent `useState`) — which is the right place for it anyway, since
+ * the last step usually needs to submit everything at once.
+ *
+ * @example
+ * ```tsx
+ * const form = useZodForm(schema);
+ *
+ * <FormProvider {...form}>
+ *   <Wizard
+ *     steps={[
+ *       {
+ *         id: "dados",
+ *         label: "Dados",
+ *         validate: () => form.trigger(["nome", "email"]),
+ *         content: (
+ *           <>
+ *             <FormField name="nome" label="Nome"><Input /></FormField>
+ *             <FormField name="email" label="E-mail"><Input type="email" /></FormField>
+ *           </>
+ *         ),
+ *       },
+ *       { id: "revisao", label: "Revisão", content: <Review /> },
+ *     ]}
+ *     onComplete={form.handleSubmit(onSubmit)}
+ *   />
+ * </FormProvider>
+ * ```
+ */
+export declare function Wizard({ steps, activeIndex, defaultActiveIndex, onStepChange, onComplete, nextLabel, backLabel, finishLabel, optionalLabel, clickableSteps, renderActions, className, }: WizardProps): JSX.Element;
+
+/** Flow controls handed to a step body and to `renderActions`. */
+export declare interface WizardControls {
+    /** Zero-based index of the current step. */
+    activeIndex: number;
+    /** The current step. */
+    step: WizardStep;
+    /** `true` while a `validate` promise is pending. */
+    validating: boolean;
+    isFirst: boolean;
+    isLast: boolean;
+    /** Run the current step's `validate` and advance when it passes. */
+    next: () => Promise<void>;
+    /** Go back one step. No validation — going back never blocks. */
+    back: () => void;
+    /** Jump to an index. Forward jumps validate every step in between. */
+    goTo: (index: number) => Promise<void>;
+}
+
+export declare interface WizardProps {
+    steps: WizardStep[];
+    /** Controlled active index. */
+    activeIndex?: number;
+    /** Uncontrolled initial index. Default `0`. */
+    defaultActiveIndex?: number;
+    onStepChange?: (index: number, step: WizardStep) => void;
+    /** Called when the last step passes validation. */
+    onComplete?: () => void | Promise<void>;
+    /** Label of the advance button. Default `"Next"`. */
+    nextLabel?: string;
+    /** Label of the back button. Default `"Back"`. */
+    backLabel?: string;
+    /** Label of the button on the last step. Default `"Finish"`. */
+    finishLabel?: string;
+    /**
+     * Suffix appended to an optional step's description in the indicator.
+     * Default `"(optional)"` — override it to localize, since the SDK ships no
+     * translation for component-internal copy.
+     */
+    optionalLabel?: string;
+    /**
+     * Allow clicking the indicator to jump. Default `false` — a wizard exists
+     * because order matters, and a free jump skips the gates.
+     */
+    clickableSteps?: boolean;
+    /** Replace the default button row. */
+    renderActions?: (controls: WizardControls) => ReactNode;
+    className?: string;
+}
+
+/** One step of the flow. */
+export declare interface WizardStep {
+    /** Stable identifier. */
+    id: string;
+    /** Step label shown in the indicator. */
+    label: string;
+    /** Optional description under the label. */
+    description?: string;
+    /** Step body. A function receives the flow controls, for a "skip" link inside the form. */
+    content: ReactNode | ((controls: WizardControls) => ReactNode);
+    /**
+     * Gate for leaving this step forward. Return `false` (or a rejected/`false`
+     * promise) to keep the user here — typically `() => form.trigger()`.
+     * Async is supported: the Next button shows a pending state while it runs.
+     */
+    validate?: () => boolean | Promise<boolean>;
+    /** Marks the step as optional, so `onComplete` can ignore it. */
+    optional?: boolean;
+}
+
 /**
  * Write a minimal single-sheet Office Open XML (`.xlsx`) workbook and return
  * its bytes. No extra dependency beyond `fflate` — the archive is assembled and