tempest-react-sdk 0.25.0 → 0.26.1

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,24 @@ 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.
  *
@@ -1221,6 +1241,30 @@ export declare interface CollapsibleProps extends HTMLAttributes<HTMLDivElement>
 /** 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.
  *
@@ -1289,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`.
  *
@@ -1503,7 +1566,7 @@ export declare interface CreateAuthStoreOptions<TUser> {
 }
 
 /**
- * Build a ten-step tint scale from a single brand color.
+ * 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
@@ -1512,8 +1575,9 @@ export declare interface CreateAuthStoreOptions<TUser> {
  * @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"): ColorScale;
+export declare function createColorScale(hex: string, mode?: "light" | "dark", options?: ColorScaleOptions): ColorScale;
 
 /**
  * Create a {@link DataProvider} bound to an {@link ApiClient}.
@@ -3969,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>`.
@@ -4456,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
@@ -4627,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
@@ -5091,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.
@@ -6436,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";
 
 /**
@@ -7689,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.
@@ -7893,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;
 
@@ -8169,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;
@@ -8341,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
@@ -8883,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;
 
@@ -9135,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
@@ -9605,7 +10181,7 @@ export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?
  * </FormProvider>
  * ```
  */
-export declare function Wizard({ steps, activeIndex, defaultActiveIndex, onStepChange, onComplete, nextLabel, backLabel, finishLabel, clickableSteps, renderActions, className, }: WizardProps): JSX.Element;
+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 {
@@ -9640,6 +10216,12 @@ export declare interface WizardProps {
     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.