tempest-react-sdk 0.1.6 → 0.3.0

package/dist/index.d.ts

@@ -28,6 +28,33 @@ import { UseFormProps } from 'react-hook-form';
 import { UseFormReturn } from 'react-hook-form';
 import { z } from 'zod';
 
+/**
+ * Accessible accordion. Each item collapses/expands its content. Single-mode by
+ * default — pass `multiple` to allow more than one item open at a time. Can be
+ * controlled via `value` + `onChange`, or uncontrolled via `defaultValue`.
+ */
+export declare function Accordion({ items, multiple, value, defaultValue, onChange, className, }: AccordionProps): JSX.Element;
+
+export declare interface AccordionItem {
+    /** Stable identifier. */
+    id: string;
+    title: ReactNode;
+    children: ReactNode;
+    disabled?: boolean;
+}
+
+export declare interface AccordionProps {
+    items: AccordionItem[];
+    /** When `true` multiple items can be open simultaneously. Default `false`. */
+    multiple?: boolean;
+    /** Controlled open ids. */
+    value?: string[];
+    /** Uncontrolled default open ids. */
+    defaultValue?: string[];
+    onChange?: (openIds: string[]) => void;
+    className?: string;
+}
+
 /**
  * Inline alert / notice with tone (info/success/warning/danger) and appearance
  * (soft/solid/outline). Accepts optional `icon`, `title`, `description` and
@@ -52,6 +79,10 @@ export declare interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>,
 
 export declare type AlertVariant = "neutral" | "info" | "success" | "warning" | "danger";
 
+declare type AnyEventTarget = EventTarget | {
+    current: EventTarget | null;
+} | null | undefined;
+
 export declare interface ApiClient {
     request<T>(path: string, options?: RequestOptions): Promise<T>;
     get<T>(path: string, options?: RequestOptions): Promise<T>;
@@ -88,6 +119,29 @@ export declare interface ApiError {
     body?: unknown;
 }
 
+/**
+ * Preserve a constant aspect ratio for media (images, video, embeds). The
+ * inner child stretches to fill the box. Uses the native `aspect-ratio`
+ * CSS property — works on all modern browsers (Safari 15+, Chrome 88+).
+ *
+ * @example
+ * <AspectRatio ratio={16 / 9}>
+ *     <img src="/cover.jpg" alt="" style={{ width: "100%", height: "100%", objectFit: "cover" }} />
+ * </AspectRatio>
+ */
+export declare function AspectRatio({ ratio, className, style, children, ...props }: AspectRatioProps): JSX.Element;
+
+export declare interface AspectRatioProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * Width-to-height ratio. Pass `16/9` for widescreen, `1` for square,
+     * `4/3` for SD video, `3/4` for portrait, etc. Default `16/9`.
+     */
+    ratio?: number;
+    children?: ReactNode;
+}
+
+export declare type AsyncStatus = "idle" | "pending" | "success" | "error";
+
 export declare interface AudioPlayer {
     /** Play `src`. Returns the underlying element, or `null` when the browser blocked autoplay. */
     play: (src: string, options?: PlayAudioOptions) => Promise<HTMLAudioElement | null>;
@@ -201,6 +255,30 @@ export declare interface BreadcrumbsProps {
     className?: string;
 }
 
+/**
+ * Breakpoint keys exposed by the SDK. Values mirror the CSS tokens
+ * `--tempest-bp-xs|sm|md|lg|xl|2xl` defined in `styles/colors.css`.
+ */
+export declare type Breakpoint = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+
+export declare interface BreakpointHelpers {
+    /** Current breakpoint key (the largest one whose min-width is matched). */
+    current: Breakpoint;
+    /** Window width in pixels at last update. `0` when SSR. */
+    width: number;
+    /** True when viewport width is `>=` the given breakpoint. */
+    above: (bp: Breakpoint) => boolean;
+    /** True when viewport width is `<` the given breakpoint. */
+    below: (bp: Breakpoint) => boolean;
+    /** Convenience flags mapping to typical device shapes. */
+    isMobile: boolean;
+    isTablet: boolean;
+    isDesktop: boolean;
+}
+
+/** Pixel value paired with each breakpoint key. */
+export declare const BREAKPOINTS: Record<Breakpoint, number>;
+
 /**
  * Primary action button with variants, sizes and a loading state that
  * preserves layout via an absolutely-positioned spinner.
@@ -259,7 +337,31 @@ export declare interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>,
 
 export declare type Catalog = Record<string, Messages>;
 
-export declare const CEPInput: ForwardRefExoticComponent<Omit<InputProps, "onChange" | "value"> & {
+/**
+ * Center children horizontally, vertically, or both. Flex-based; works with
+ * any child size. Pair with `minHeight` (or set parent height) when
+ * centering vertically.
+ *
+ * @example
+ * <Center axis="both" minHeight="100vh">
+ *     <Spinner />
+ * </Center>
+ */
+export declare function Center({ axis, minHeight, fullWidth, className, style, children, ...props }: CenterProps): JSX.Element;
+
+export declare type CenterAxis = "both" | "horizontal" | "vertical";
+
+export declare interface CenterProps extends HTMLAttributes<HTMLDivElement> {
+    /** Which axis to center on. Default `"both"`. */
+    axis?: CenterAxis;
+    /** Fixed height for the container. Numbers map to `${n}px`; strings pass through. Useful when centering inside an unsized parent. */
+    minHeight?: number | string;
+    /** When `true` (default), takes up `100%` width of the parent. */
+    fullWidth?: boolean;
+    children?: ReactNode;
+}
+
+export declare const CEPInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
 } & RefAttributes<HTMLInputElement>>;
@@ -308,11 +410,41 @@ declare type ClassValue = string | number | bigint | boolean | null | undefined
  */
 export declare function cn(...values: ClassValue[]): string;
 
-export declare const CNPJInput: ForwardRefExoticComponent<Omit<InputProps, "onChange" | "value"> & {
+export declare const CNPJInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
 } & RefAttributes<HTMLInputElement>>;
 
+/**
+ * Combobox — text input with a filterable dropdown of options.
+ *
+ * Selecting an option fires `onChange(value)`. Typing filters the list.
+ * Keyboard: ArrowUp/ArrowDown to navigate, Enter to select, Esc to close.
+ */
+export declare function Combobox({ options, value, onChange, label, placeholder, helperText, error, disabled, filter, emptyMessage, className, }: ComboboxProps): JSX.Element;
+
+export declare interface ComboboxOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+
+export declare interface ComboboxProps {
+    options: ComboboxOption[];
+    value: string;
+    onChange: (value: string) => void;
+    label?: string;
+    placeholder?: string;
+    helperText?: string;
+    error?: string;
+    disabled?: boolean;
+    /** Custom filter — return true to keep the option. Default is case-insensitive substring match on label. */
+    filter?: (option: ComboboxOption, query: string) => boolean;
+    /** Message shown when no option matches. */
+    emptyMessage?: string;
+    className?: string;
+}
+
 /**
  * Quick confirmation prompt built on top of {@link Modal}. Use for destructive
  * actions with `variant="danger"`.
@@ -340,7 +472,10 @@ export declare const consoleSink: LoggerSink;
  */
 export declare const consoleTelemetryAdapter: TelemetryAdapter;
 
-/** Page-level horizontal container with a max-width preset and side padding. */
+/**
+ * Page-level horizontal container with a max-width preset and responsive
+ * side padding (`space-4` mobile / `space-6` tablet / `space-8` desktop).
+ */
 export declare function Container({ size, className, children, ...props }: ContainerProps): JSX.Element;
 
 export declare interface ContainerProps extends HTMLAttributes<HTMLDivElement> {
@@ -349,7 +484,7 @@ export declare interface ContainerProps extends HTMLAttributes<HTMLDivElement> {
 
 export declare type ContainerSize = "sm" | "md" | "lg" | "xl" | "full";
 
-export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "onChange" | "value"> & {
+export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
 } & RefAttributes<HTMLInputElement>>;
@@ -774,7 +909,7 @@ export declare type DocumentVisibility = "visible" | "hidden";
  * Sliding side panel. Same building blocks as {@link Modal} but anchored to
  * an edge. Locks body scroll while open.
  */
-export declare function Drawer({ open, onClose, placement, title, children, footer, closeOnBackdrop, closeOnEsc, hideCloseButton, className, }: DrawerProps): ReactPortal | null;
+export declare function Drawer({ open, onClose, placement, title, children, footer, closeOnBackdrop, closeOnEsc, hideCloseButton, className, mobilePlacement, showHandle, }: DrawerProps): ReactPortal | null;
 
 export declare type DrawerPlacement = "right" | "left" | "top" | "bottom";
 
@@ -789,6 +924,54 @@ export declare interface DrawerProps {
     closeOnEsc?: boolean;
     hideCloseButton?: boolean;
     className?: string;
+    /**
+     * Auto-switch to bottom-sheet placement on mobile viewports (< md).
+     * Modern mobile apps default to bottom drawers; on desktop the original
+     * `placement` is preserved.
+     */
+    mobilePlacement?: DrawerPlacement;
+    /** Render a drag handle indicator at the leading edge (bottom-sheet style). */
+    showHandle?: boolean;
+}
+
+/**
+ * Dropdown menu — list of selectable actions anchored to a trigger.
+ *
+ * - Toggle on trigger click.
+ * - Close on outside click / Escape / item selection.
+ * - Arrow keys navigate, Enter activates focused item.
+ */
+export declare function DropdownMenu({ trigger, items, placement, className, }: DropdownMenuProps): JSX.Element;
+
+export declare type DropdownMenuEntry = {
+    type: "item";
+    id: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    danger?: boolean;
+    disabled?: boolean;
+    onSelect: () => void;
+} | {
+    type: "separator";
+    id: string;
+} | {
+    type: "label";
+    id: string;
+    label: ReactNode;
+};
+
+export declare type DropdownMenuPlacement = "bottom-start" | "bottom-end" | "top-start" | "top-end";
+
+export declare interface DropdownMenuProps {
+    trigger: ReactElement<{
+        onClick?: (e: React.MouseEvent) => void;
+        "aria-expanded"?: boolean;
+        "aria-controls"?: string;
+        "aria-haspopup"?: boolean | "menu";
+    }>;
+    items: DropdownMenuEntry[];
+    placement?: DropdownMenuPlacement;
+    className?: string;
 }
 
 export declare interface ElementSize {
@@ -1107,10 +1290,10 @@ export declare interface GetInitialThemeOptions {
 export declare function Grid({ columns, gap, className, style, children, ...props }: GridProps): JSX.Element;
 
 export declare interface GridProps extends HTMLAttributes<HTMLDivElement> {
-    /** Number of columns or a custom `grid-template-columns` value. */
-    columns?: number | string;
-    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. */
-    gap?: number | string;
+    /** Number of columns or a custom `grid-template-columns` value. Accepts responsive object. */
+    columns?: ResponsiveValue<number | string>;
+    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. Accepts responsive object. */
+    gap?: ResponsiveValue<number | string>;
     children?: ReactNode;
 }
 
@@ -1125,6 +1308,19 @@ export declare interface GrowthBookLike {
     setRenderer?: (renderer: () => void) => void;
 }
 
+/** Inverse of `<Show>` — hides children when the condition matches. */
+export declare function Hide({ above, below, only, children }: HideProps): ReactNode;
+
+export declare interface HideProps {
+    /** Hide children when viewport width is `>=` this breakpoint. */
+    above?: Breakpoint;
+    /** Hide children when viewport width is `<` this breakpoint. */
+    below?: Breakpoint;
+    /** Hide on specific breakpoints. */
+    only?: Breakpoint | Breakpoint[];
+    children: ReactNode;
+}
+
 export declare interface I18n {
     /** Currently active locale. */
     locale: string;
@@ -1335,6 +1531,11 @@ export declare interface ListOptions<TItem> {
     filter?: (item: TItem) => boolean;
 }
 
+export declare type LocalStorageOptions<T> = {
+    serialize?: (value: T) => string;
+    deserialize?: (raw: string) => T;
+};
+
 export declare interface LogEntry {
     level: LogLevel;
     message: string;
@@ -1363,7 +1564,7 @@ export declare type Messages = Record<string, string>;
  * Portal-rendered modal dialog with backdrop, Esc handler, and slots for
  * header/body/footer. Locks body scroll while open.
  */
-export declare function Modal({ open, onClose, title, children, footer, size, closeOnBackdrop, closeOnEsc, className, hideCloseButton, }: ModalProps): ReactPortal | null;
+export declare function Modal({ open, onClose, title, children, footer, size, closeOnBackdrop, closeOnEsc, className, hideCloseButton, fullscreen, fullscreenOnMobile, }: ModalProps): ReactPortal | null;
 
 export declare interface ModalProps {
     open: boolean;
@@ -1376,9 +1577,13 @@ export declare interface ModalProps {
     closeOnEsc?: boolean;
     className?: string;
     hideCloseButton?: boolean;
+    /** Force fullscreen at all breakpoints. */
+    fullscreen?: boolean;
+    /** Auto-fullscreen on mobile viewports (< 640px). Default `false`. */
+    fullscreenOnMobile?: boolean;
 }
 
-export declare type ModalSize = "sm" | "md" | "lg" | "xl";
+export declare type ModalSize = "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
 
 /**
  * Currency-masked input. Stores the value as an integer number of cents to
@@ -1477,7 +1682,7 @@ export declare interface PaginationProps {
  */
 export declare function parseResponse<TSchema extends z.ZodTypeAny>(schema: TSchema, raw: unknown, context: string): z.infer<TSchema>;
 
-export declare const PhoneInput: ForwardRefExoticComponent<Omit<InputProps, "onChange" | "value"> & {
+export declare const PhoneInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
 } & RefAttributes<HTMLInputElement>>;
@@ -1504,6 +1709,37 @@ export declare interface PlayAudioOptions {
     onError?: (error: unknown) => void;
 }
 
+/**
+ * Lightweight popover. Renders a positioned panel anchored to a trigger,
+ * dismissed on outside click / Escape. Does NOT include collision detection
+ * or smart positioning — pair with Floating UI if you need that.
+ */
+export declare function Popover({ trigger, children, placement, open, onOpenChange, defaultOpen, closeOnEsc, closeOnOutsideClick, className, }: PopoverProps): JSX.Element;
+
+export declare type PopoverPlacement = "top" | "bottom" | "left" | "right";
+
+export declare interface PopoverProps {
+    /** Trigger element. Receives `onClick`/`aria-expanded`/`aria-controls`. */
+    trigger: ReactElement<{
+        onClick?: (e: React.MouseEvent) => void;
+        "aria-expanded"?: boolean;
+        "aria-controls"?: string;
+    }>;
+    children: ReactNode;
+    placement?: PopoverPlacement;
+    /** Controlled open state. */
+    open?: boolean;
+    /** Called when the user toggles or dismisses. */
+    onOpenChange?: (open: boolean) => void;
+    /** Default open state for uncontrolled usage. */
+    defaultOpen?: boolean;
+    /** Close on Escape. Default true. */
+    closeOnEsc?: boolean;
+    /** Close on outside click. Default true. */
+    closeOnOutsideClick?: boolean;
+    className?: string;
+}
+
 /**
  * Minimal subset of `posthog-js` used by the adapter. Pass either the real
  * default export (`import posthog from "posthog-js"`) or a stubbed object
@@ -1610,6 +1846,51 @@ export declare interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputEl
     wrapperClassName?: string;
 }
 
+/**
+ * Dual-thumb range slider. Built on two native `<input type="range">` so it
+ * stays accessible and works with keyboards/screen readers without
+ * heavyweight positioning libs. The active fill is positioned via percentages.
+ */
+export declare function RangeSlider({ value, onChange, min, max, step, label, helperText, disabled, formatValue, className, }: RangeSliderProps): JSX.Element;
+
+export declare interface RangeSliderProps {
+    value: RangeValue;
+    onChange: (value: RangeValue) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    label?: string;
+    helperText?: string;
+    disabled?: boolean;
+    /** Formatter for the value badge next to the label. Defaults to `min – max`. */
+    formatValue?: (value: RangeValue) => string;
+    className?: string;
+}
+
+export declare type RangeValue = [number, number];
+
+export declare type RatingSize = "sm" | "md" | "lg";
+
+/**
+ * Star rating control. Renders `max` stars, fills the first `value`. Click a
+ * star to set rating (when not readonly). Hovering previews the value.
+ */
+export declare function RatingStars({ value, max, onChange, size, readonly, disabled, label, className, }: RatingStarsProps): JSX.Element;
+
+export declare interface RatingStarsProps {
+    /** Current selected value (1..max). 0 means none. */
+    value: number;
+    /** Total number of stars. Default 5. */
+    max?: number;
+    onChange?: (value: number) => void;
+    size?: RatingSize;
+    readonly?: boolean;
+    disabled?: boolean;
+    /** Accessible label for the rating group. */
+    label?: string;
+    className?: string;
+}
+
 /** Recommended refetch intervals (milliseconds). */
 export declare const REFETCH_TIME: {
     readonly REALTIME: number;
@@ -1667,6 +1948,17 @@ declare interface ResolverOutput<T> {
     errors: Record<string, ResolverError | object>;
 }
 
+/**
+ * Responsive value — either a single value applied at all breakpoints, or
+ * an object with `mobile` / `tablet` / `desktop` overrides. Apps can mix
+ * any combination; `mobile` is the base, `tablet` / `desktop` cascade up.
+ */
+export declare type ResponsiveValue<T> = T | {
+    mobile?: T;
+    tablet?: T;
+    desktop?: T;
+};
+
 /**
  * Run `factory()` with exponential backoff. Each attempt awaits an
  * increasing delay capped at `maxDelay`. Throws the last error if every
@@ -1779,6 +2071,28 @@ export declare interface ShareResult {
     error?: unknown;
 }
 
+/**
+ * Conditionally render children based on the viewport breakpoint.
+ *
+ * - `above` — render when viewport width is `>=` the given breakpoint.
+ * - `below` — render when viewport width is `<` the given breakpoint.
+ * - `only` — render only on the listed breakpoint(s).
+ *
+ * SSR-safe: first render uses `xs` (renders mobile content first); the
+ * component re-renders once `useBreakpoint` has the real viewport width.
+ */
+export declare function Show({ above, below, only, children }: ShowProps): ReactNode;
+
+export declare interface ShowProps {
+    /** Render children only when viewport width is `>=` this breakpoint. */
+    above?: Breakpoint;
+    /** Render children only when viewport width is `<` this breakpoint. */
+    below?: Breakpoint;
+    /** Render only on specific breakpoints. Wins over `above`/`below` when set. */
+    only?: Breakpoint | Breakpoint[];
+    children: ReactNode;
+}
+
 /** Loading placeholder block. Use `variant="text"` for inline lines, `circle` for avatars. */
 export declare function Skeleton({ variant, width, height, className, style }: SkeletonProps): JSX.Element;
 
@@ -1796,6 +2110,26 @@ export declare interface SkeletonProps {
  */
 export declare function skipWaiting(worker: ServiceWorker): void;
 
+/**
+ * Flex spacer — pushes siblings apart inside a flex container. Equivalent
+ * to `<div style={{ flex: 1 }}>` but typed and intent-revealing.
+ *
+ * @example
+ * <Stack direction="horizontal">
+ *     <Button>Cancelar</Button>
+ *     <Spacer />
+ *     <Button variant="primary">Salvar</Button>
+ * </Stack>
+ */
+export declare function Spacer({ axis, className, ...props }: SpacerProps): JSX.Element;
+
+export declare type SpacerAxis = "both" | "x" | "y";
+
+export declare interface SpacerProps extends HTMLAttributes<HTMLDivElement> {
+    /** Axis to flex along. Default `"both"` (`flex: 1`). */
+    axis?: SpacerAxis;
+}
+
 /** Loading spinner with preset sizes (xs..xl). Provide `label` for screen readers. */
 export declare function Spinner({ size, className, label }: SpinnerProps): JSX.Element;
 
@@ -1812,13 +2146,15 @@ export declare function Stack({ direction, gap, align, justify, wrap, className,
 
 export declare type StackAlign = "start" | "center" | "end" | "stretch";
 
+export declare type StackDirection = "vertical" | "horizontal";
+
 export declare type StackJustify = "start" | "center" | "end" | "between";
 
 export declare interface StackProps extends HTMLAttributes<HTMLDivElement> {
-    /** Direction. Default `vertical`. */
-    direction?: "vertical" | "horizontal";
-    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. */
-    gap?: number | string;
+    /** Direction. Accepts responsive object — e.g. `{ mobile: "vertical", desktop: "horizontal" }`. */
+    direction?: ResponsiveValue<StackDirection>;
+    /** Gap as a CSS length. Numbers map to a multiple of the 4px scale. Accepts responsive object. */
+    gap?: ResponsiveValue<number | string>;
     align?: StackAlign;
     justify?: StackJustify;
     wrap?: boolean;
@@ -1881,11 +2217,13 @@ export declare interface TabItem {
 }
 
 /**
- * Lightweight table that maps a list of rows through declarative `columns`.
- * Provide `rowKey` so React reconciliation works. Rows become clickable when
- * `onRowClick` is supplied.
+ * Lightweight table with declarative columns + mobile niceties.
+ *
+ * - `priority` per column lets less-important data hide on narrow viewports.
+ * - `stackOnMobile` re-renders each row as a label/value card on mobile,
+ *   avoiding horizontal scroll for dense data.
  */
-export declare function Table<T>({ columns, data, rowKey, onRowClick, emptyMessage, className, }: TableProps<T>): JSX.Element;
+export declare function Table<T>({ columns, data, rowKey, onRowClick, emptyMessage, className, stackOnMobile, }: TableProps<T>): JSX.Element;
 
 export declare type TableAlign = "left" | "right" | "center";
 
@@ -1897,8 +2235,15 @@ export declare interface TableColumn<T> {
     align?: TableAlign;
     width?: string | number;
     className?: string;
+    /**
+     * Visibility priority: `always` (default) shows on every viewport,
+     * `tablet` hides below md (< 768px), `desktop` hides below lg (< 1024px).
+     */
+    priority?: TablePriority;
 }
 
+export declare type TablePriority = "always" | "tablet" | "desktop";
+
 export declare interface TableProps<T> {
     columns: TableColumn<T>[];
     data: T[];
@@ -1906,6 +2251,11 @@ export declare interface TableProps<T> {
     onRowClick?: (row: T) => void;
     emptyMessage?: ReactNode;
     className?: string;
+    /**
+     * Stack mode — render rows as label/value cards on mobile (< md).
+     * Better than horizontal scroll when each row has 3+ columns of dense data.
+     */
+    stackOnMobile?: boolean;
 }
 
 /**
@@ -2040,19 +2390,30 @@ export declare interface ToastOptions {
     duration?: number;
 }
 
+export declare type ToastPosition = "top-right" | "top-left" | "top-center" | "bottom-right" | "bottom-left" | "bottom-center";
+
 /**
  * Renders a portalled toast container and exposes the imperative {@link useToast} API.
  */
-export declare function ToastProvider({ children, defaultDuration }: ToastProviderProps): JSX.Element;
+export declare function ToastProvider({ children, defaultDuration, position, }: ToastProviderProps): JSX.Element;
 
 export declare interface ToastProviderProps {
     children: ReactNode;
     /** Default auto-dismiss duration (ms). Default 4000. */
     defaultDuration?: number;
+    /** Stack position on screen. Default `"top-right"`. */
+    position?: ToastPosition;
 }
 
 export declare type ToastVariant = "success" | "warning" | "error" | "info";
 
+export declare interface ToggleHelpers {
+    toggle: () => void;
+    setTrue: () => void;
+    setFalse: () => void;
+    set: (next: boolean) => void;
+}
+
 /**
  * Lightweight tooltip. Shows on hover and on focus (keyboard-friendly). Wraps
  * a single child element via `cloneElement`, so the trigger keeps its own ref
@@ -2132,6 +2493,34 @@ export declare interface UploadWithProgressOptions {
  */
 export declare function urlBase64ToUint8Array(base64String: string): Uint8Array<ArrayBuffer>;
 
+/**
+ * Run an async function and track its `idle/pending/success/error` state.
+ *
+ * - Discards results from stale runs (race-condition safe).
+ * - `immediate` (default `false`) triggers the function on mount and when
+ *   `deps` change. With `false`, call `run()` manually.
+ * - Returns a stable object so callers can destructure or pass around safely.
+ *
+ * For server data with caching, prefer React Query — `useAsync` is the
+ * minimal one-shot primitive without dependencies.
+ */
+export declare function useAsync<T>(asyncFn: () => Promise<T>, deps?: ReadonlyArray<unknown>, options?: {
+    immediate?: boolean;
+}): UseAsyncResult<T>;
+
+export declare interface UseAsyncResult<T> {
+    status: AsyncStatus;
+    data: T | undefined;
+    error: unknown;
+    isPending: boolean;
+    isSuccess: boolean;
+    isError: boolean;
+    /** Trigger the async function. Resolves with the new data or rejects. */
+    run: () => Promise<T>;
+    /** Reset state back to idle. */
+    reset: () => void;
+}
+
 /**
  * Hook-managed audio player. Each component instance gets its own
  * {@link AudioPlayer}, so unmounting cleanly stops playback. Useful for
@@ -2166,6 +2555,15 @@ export declare interface UseBeforeInstallPromptResult {
     prompt: () => Promise<"accepted" | "dismissed" | "unsupported">;
 }
 
+/**
+ * Reactive viewport-breakpoint hook.
+ *
+ * Returns the current breakpoint key plus `above` / `below` helpers and
+ * `isMobile` / `isTablet` / `isDesktop` flags. SSR-safe — returns `xs` /
+ * `width: 0` on the server, then updates after mount.
+ */
+export declare function useBreakpoint(): BreakpointHelpers;
+
 /**
  * Client-side filter helper. Performs a case-insensitive match on the listed
  * keys when no custom predicate is provided.
@@ -2233,6 +2631,21 @@ export declare function useDocumentVisibility(): DocumentVisibility;
  */
 export declare function useErrorHandler(): (error: unknown) => void;
 
+/**
+ * Subscribe to a DOM event with React-friendly semantics.
+ *
+ * - Handler is stored in a ref so callers can pass inline functions without
+ *   resubscribing on every render.
+ * - `target` defaults to `window`. Accepts a raw `EventTarget` (window, document,
+ *   element) OR a ref pointing at one.
+ * - Returns nothing — cleanup is automatic on unmount or when `eventName`/`target` change.
+ */
+export declare function useEventListener<K extends keyof WindowEventMap>(eventName: K, handler: (event: WindowEventMap[K]) => void, target?: AnyEventTarget, options?: AddEventListenerOptions | boolean): void;
+
+export declare function useEventListener<K extends keyof DocumentEventMap>(eventName: K, handler: (event: DocumentEventMap[K]) => void, target?: AnyEventTarget, options?: AddEventListenerOptions | boolean): void;
+
+export declare function useEventListener<K extends keyof HTMLElementEventMap>(eventName: K, handler: (event: HTMLElementEventMap[K]) => void, target?: AnyEventTarget, options?: AddEventListenerOptions | boolean): void;
+
 /**
  * React hook wrapper around {@link createEventStream}. Connection lifecycle is
  * tied to the component (and the `url`/`enabled` dependencies); the stream
@@ -2333,6 +2746,18 @@ export declare interface UseKeyboardShortcutOptions {
     ignoreInput?: boolean;
 }
 
+/**
+ * State synced with `localStorage`. SSR-safe — initial render returns the
+ * provided default; the stored value is hydrated after mount. Updates to the
+ * same key in other tabs are picked up via the `storage` event.
+ *
+ * @param key - localStorage key.
+ * @param defaultValue - value used when nothing is stored or in SSR.
+ * @param options - custom `serialize` / `deserialize` (default JSON).
+ * @returns Tuple `[value, setValue, remove]`.
+ */
+export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: LocalStorageOptions<T>): [T, (value: T | ((prev: T) => T)) => void, () => void];
+
 /**
  * Subscribe to a CSS media query and re-render on match changes.
  *
@@ -2460,6 +2885,14 @@ export declare function useTheme(): ThemeContextValue;
  */
 export declare function useToast(): ToastApi;
 
+/**
+ * Boolean state with `toggle`/`setTrue`/`setFalse` helpers.
+ *
+ * @param initial - initial value (default `false`).
+ * @returns Tuple `[value, helpers]`.
+ */
+export declare function useToggle(initial?: boolean): [boolean, ToggleHelpers];
+
 /**
  * Shortcut for components that only need the `t` function — avoids destructuring.
  */