tempest-react-sdk 0.2.0 → 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>;
@@ -283,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>>;
@@ -332,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"`.
@@ -376,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>>;
@@ -826,6 +934,46 @@ export declare interface DrawerProps {
     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 {
     width: number;
     height: number;
@@ -1383,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;
@@ -1529,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>>;
@@ -1556,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
@@ -1662,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;
@@ -1881,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;
 
@@ -2158,6 +2407,13 @@ export declare interface ToastProviderProps {
 
 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
@@ -2237,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
@@ -2347,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
@@ -2447,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.
  *
@@ -2574,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.
  */