tempest-react-sdk 0.24.0 → 0.25.0

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

@@ -304,6 +304,41 @@ export declare interface AppBarProps extends Omit<HTMLAttributes<HTMLElement>, "
 
 export declare type AppBarTone = "surface" | "primary" | "transparent";
 
+/**
+ * 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 +533,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 +1218,9 @@ export declare interface CollapsibleProps extends HTMLAttributes<HTMLDivElement>
     children: ReactNode;
 }
 
+/** A generated tint scale, keyed by step. */
+export declare type ColorScale = Record<ScaleStep, string>;
+
 /**
  * Combobox — text input with a filterable dropdown of options.
  *
@@ -1311,6 +1398,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 +1502,19 @@ export declare interface CreateAuthStoreOptions<TUser> {
     initialToken?: string | null;
 }
 
+/**
+ * Build a ten-step tint scale from a single brand 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"]`.
+ */
+export declare function createColorScale(hex: string, mode?: "light" | "dark"): ColorScale;
+
 /**
  * Create a {@link DataProvider} bound to an {@link ApiClient}.
  *
@@ -1974,6 +2077,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 +3225,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 +3305,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 +3434,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;
 
@@ -3902,6 +4091,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> {
@@ -4701,6 +4951,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 +5064,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;
@@ -5351,6 +5635,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 +5779,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 +5945,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 +6072,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 +6304,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;
 
@@ -6158,6 +6545,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 +6554,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 +6597,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 +6996,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 +7010,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 +7033,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 +7087,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 +7399,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`.
@@ -9067,6 +9567,109 @@ 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, 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;
+    /**
+     * 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