tempest-react-sdk 0.2.0 → 0.4.0

package/dist/{index.d.ts → tempest-react-sdk.d.ts}

@@ -1,17 +1,26 @@
 import { ButtonHTMLAttributes } from 'react';
 import { Component } from 'react';
 import { ComponentType } from 'react';
+import { Control } from 'react-hook-form';
+import { Controller } from 'react-hook-form';
+import { ControllerRenderProps } from 'react-hook-form';
 import { CSSProperties } from 'react';
 import { default as default_2 } from 'dexie';
 import { DefaultOptions } from '@tanstack/react-query';
 import { ErrorInfo } from 'react';
+import { FieldArrayWithId } from 'react-hook-form';
+import { FieldError } from 'react-hook-form';
+import { FieldErrors } from 'react-hook-form';
+import { FieldPath } from 'react-hook-form';
 import { FieldValues } from 'react-hook-form';
 import { FormHTMLAttributes } from 'react';
+import { FormProvider } from 'react-hook-form';
 import { ForwardRefExoticComponent } from 'react';
 import { HTMLAttributes } from 'react';
 import { InputHTMLAttributes } from 'react';
 import { JSX } from 'react/jsx-runtime';
 import { lazy } from 'react';
+import { Path } from 'react-hook-form';
 import { PersistOptions } from 'zustand/middleware';
 import { QueryClient } from '@tanstack/react-query';
 import { ReactElement } from 'react';
@@ -21,13 +30,48 @@ import { RefAttributes } from 'react';
 import { RefObject } from 'react';
 import { SelectHTMLAttributes } from 'react';
 import { StoreApi } from 'zustand';
+import { SubmitHandler } from 'react-hook-form';
 import { Table as Table_2 } from 'dexie';
 import { TextareaHTMLAttributes } from 'react';
 import { UseBoundStore } from 'zustand';
+import { useFieldArray } from 'react-hook-form';
+import { UseFieldArrayReturn } from 'react-hook-form';
+import { useForm } from 'react-hook-form';
+import { useFormContext } from 'react-hook-form';
 import { UseFormProps } from 'react-hook-form';
+import { UseFormRegister } from 'react-hook-form';
 import { UseFormReturn } from 'react-hook-form';
+import { useFormState } from 'react-hook-form';
+import { useWatch } 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 +96,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 +136,63 @@ export declare interface ApiError {
     body?: unknown;
 }
 
+/**
+ * Full app layout — composes [[Navbar]] + [[Sidebar]] + content +
+ * [[BottomNavigation]] + footer with responsive behaviour:
+ *
+ * - **Desktop (`>= sidebarBreakpoint`)**: navbar + sidebar + main + footer.
+ * - **Mobile (`< sidebarBreakpoint`)**: navbar + main + bottom nav + footer
+ *   (sidebar hidden — app should expose it via `<Drawer>` from a hamburger).
+ *
+ * @example
+ * <AppShell
+ *     navbar={<Navbar logo={<Brand />} actions={<UserMenu />} />}
+ *     sidebar={<Sidebar items={...} value={tab} onChange={setTab} />}
+ *     bottomNav={<BottomNavigation items={...} value={tab} onChange={setTab} />}
+ *     footer={<Footer />}
+ * >
+ *     <Page title="Dashboard">{content}</Page>
+ * </AppShell>
+ */
+export declare function AppShell({ navbar, sidebar, bottomNav, footer, sidebarBreakpoint, className, children, ...props }: AppShellProps): JSX.Element;
+
+export declare interface AppShellProps extends HTMLAttributes<HTMLDivElement> {
+    /** Top navigation bar (Navbar / custom). Renders on every breakpoint. */
+    navbar?: ReactNode;
+    /** Side navigation (Sidebar). Hidden below `md` — pair with `<Drawer>` for mobile. */
+    sidebar?: ReactNode;
+    /** Mobile-only bottom navigation (BottomNavigation). Hidden at `md+`. */
+    bottomNav?: ReactNode;
+    /** Footer rendered after the main content. */
+    footer?: ReactNode;
+    /** Breakpoint at which the sidebar appears. Default `"md"`. */
+    sidebarBreakpoint?: "sm" | "md" | "lg" | "xl";
+    children?: ReactNode;
+}
+
+/**
+ * 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>;
@@ -182,6 +287,105 @@ export declare type BadgeSize = "sm" | "md" | "lg";
 
 export declare type BadgeVariant = "neutral" | "primary" | "success" | "warning" | "danger" | "info";
 
+/**
+ * Top-of-page persistent notice. Use for environment indicators
+ * ("Você está em sandbox"), maintenance windows, account warnings.
+ * Different from `Alert` (inline near a field) and `Toast` (transient).
+ *
+ * @example
+ * <Banner variant="warning" dismissible onDismiss={() => setOpen(false)}>
+ *     Sua assinatura expira em 3 dias.
+ * </Banner>
+ */
+export declare function Banner({ variant, icon, title, action, dismissible, onDismiss, className, children, ...props }: BannerProps): JSX.Element | null;
+
+export declare interface BannerProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    /** Visual variant. Default `"info"`. */
+    variant?: BannerVariant;
+    /** Optional leading icon. */
+    icon?: ReactNode;
+    /** Optional title displayed before description. */
+    title?: ReactNode;
+    /** Optional action button rendered on the right side. */
+    action?: ReactNode;
+    /** Show a dismiss button on the right. */
+    dismissible?: boolean;
+    /** Callback fired when the dismiss button is clicked. */
+    onDismiss?: () => void;
+    children?: ReactNode;
+}
+
+export declare type BannerVariant = "info" | "success" | "warning" | "danger";
+
+/**
+ * Fixed-bottom mobile tab bar. 3–5 items recommended. Pair with
+ * `<Show below="md">` to render only on mobile.
+ *
+ * @example
+ * <Show below="md">
+ *     <BottomNavigation
+ *         items={[
+ *             { key: "home", label: "Início", icon: <Home /> },
+ *             { key: "search", label: "Buscar", icon: <Search /> },
+ *             { key: "profile", label: "Perfil", icon: <User /> },
+ *         ]}
+ *         value={tab}
+ *         onChange={setTab}
+ *     />
+ * </Show>
+ */
+export declare function BottomNavigation({ items, value, onChange, showLabels, className, ...props }: BottomNavigationProps): JSX.Element;
+
+export declare interface BottomNavigationItem {
+    /** Unique identifier — used as React key and for value matching. */
+    key: string;
+    /** Visible label. */
+    label: ReactNode;
+    /** Icon rendered above the label. */
+    icon?: ReactNode;
+    /** Optional badge content rendered above the icon. */
+    badge?: ReactNode;
+    /** When true, the item is not selectable. */
+    disabled?: boolean;
+}
+
+export declare interface BottomNavigationProps extends Omit<HTMLAttributes<HTMLElement>, "onChange"> {
+    items: BottomNavigationItem[];
+    /** Selected key. */
+    value: string;
+    /** Called with the new selected key on click. */
+    onChange: (key: string) => void;
+    /** Show label below each icon. Default `true`. */
+    showLabels?: boolean;
+}
+
+/**
+ * Slide-up modal panel — mobile-style sheet anchored to the bottom edge.
+ * Uses portal + safe-area padding + scroll lock.
+ *
+ * @example
+ * <BottomSheet open={open} onClose={() => setOpen(false)} title="Filters">
+ *     <FilterForm />
+ * </BottomSheet>
+ */
+export declare function BottomSheet({ open, onClose, title, showHandle, dismissOnBackdrop, dismissOnEsc, className, children, ...props }: BottomSheetProps): ReactPortal | null;
+
+export declare interface BottomSheetProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+    /** Controlled open state. */
+    open: boolean;
+    /** Fires when user dismisses (backdrop click, Esc, swipe). */
+    onClose: () => void;
+    /** Optional title rendered at the top of the sheet. */
+    title?: ReactNode;
+    /** Show a drag handle indicator at the top. Default `true`. */
+    showHandle?: boolean;
+    /** When `true`, clicking the backdrop closes the sheet. Default `true`. */
+    dismissOnBackdrop?: boolean;
+    /** When `true`, pressing Esc closes the sheet. Default `true`. */
+    dismissOnEsc?: boolean;
+    children?: ReactNode;
+}
+
 export declare interface BreadcrumbItem {
     label: ReactNode;
     href?: string;
@@ -283,7 +487,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 +560,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 +634,11 @@ 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 { Control }
+
+export { Controller }
+
+export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
 } & RefAttributes<HTMLInputElement>>;
@@ -826,6 +1088,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;
@@ -941,6 +1243,16 @@ export declare interface FeatureFlagsProviderProps {
     children: ReactNode;
 }
 
+export { FieldArrayWithId }
+
+export { FieldError }
+
+export { FieldErrors }
+
+export { FieldPath }
+
+export { FieldValues }
+
 /**
  * Drag-and-drop file dropzone. Pair with `uploadWithProgress` from the SDK
  * to wire actual uploads with byte-level progress.
@@ -1066,11 +1378,70 @@ export declare function formatPercent(value: number): string;
  */
 export declare function formatPhone(value: string): string;
 
+/**
+ * Glue between `react-hook-form` `Controller` and the SDK's controlled
+ * components. Wraps any control that accepts `{ value, onChange, label,
+ * error }` and routes RHF state into it — eliminating the per-field
+ * `<Controller render={...} />` boilerplate.
+ *
+ * @example
+ * const form = useZodForm(schema);
+ * <FormProvider {...form}>
+ *     <Form>
+ *         <FormField name="email" label="Email" required>
+ *             <Input type="email" />
+ *         </FormField>
+ *         <FormField name="cep" label="CEP">
+ *             <CEPInput />
+ *         </FormField>
+ *     </Form>
+ * </FormProvider>;
+ */
+export declare function FormField<TValues extends FieldValues = FieldValues, TName extends FieldPath<TValues> = FieldPath<TValues>>({ name, label, helperText, required, control, children }: FormFieldProps<TValues, TName>): JSX.Element;
+
+export declare interface FormFieldChildProps {
+    name: string;
+    value: unknown;
+    onChange: (...args: unknown[]) => void;
+    onBlur: () => void;
+    ref: ControllerRenderProps["ref"];
+    error?: string;
+    "aria-invalid"?: boolean;
+    "aria-describedby"?: string;
+    label?: ReactNode;
+    helperText?: ReactNode;
+    required?: boolean;
+    id?: string;
+}
+
+export declare interface FormFieldProps<TValues extends FieldValues = FieldValues, TName extends FieldPath<TValues> = FieldPath<TValues>> {
+    /** Field name (dot path supported, e.g. `"address.city"`). */
+    name: TName;
+    /** Field label rendered by the wrapped control. */
+    label?: ReactNode;
+    /** Helper text rendered by the wrapped control when there is no error. */
+    helperText?: ReactNode;
+    /** When `true`, marks the control as required (visual hint + native attribute). */
+    required?: boolean;
+    /**
+     * Explicit `control` from `useForm()` / `useZodForm()`. Optional when a
+     * `FormProvider` is in the tree.
+     */
+    control?: Control<TValues>;
+    /**
+     * The control to render. Receives `{ value, onChange, onBlur, ref, error, ... }`
+     * via `cloneElement`. Pass `<Input />`, `<Select />`, masked inputs, etc.
+     */
+    children: ReactElement;
+}
+
 export declare type FormLayout = "stack" | "inline" | "grid";
 
 export declare interface FormProps extends FormHTMLAttributes<HTMLFormElement>, LayoutProps {
 }
 
+export { FormProvider }
+
 /**
  * Forces a horizontal row regardless of parent layout — useful for grouping
  * two short fields side-by-side inside an otherwise stacked form (e.g. CEP +
@@ -1138,6 +1509,71 @@ export declare interface GetInitialThemeOptions {
     defaultTheme?: ThemeMode;
 }
 
+/**
+ * Thin wrapper over `@react-oauth/google`'s `<GoogleLogin>` that:
+ *
+ * 1. Normalises the success payload into [[OAuthCredential]] (`idToken`,
+ *    `provider: "google"`, `raw`).
+ * 2. Normalises errors into [[OAuthError]].
+ * 3. Lets you pass `GoogleLogin` via the `component` prop, so the SDK does
+ *    not declare `@react-oauth/google` as a peer dep — apps that don't use
+ *    Google never pay for it.
+ *
+ * @example
+ * import { GoogleLogin, GoogleOAuthProvider } from "@react-oauth/google";
+ * import { GoogleSignIn } from "tempest-react-sdk";
+ *
+ * <GoogleOAuthProvider clientId={import.meta.env.VITE_GOOGLE_CLIENT_ID}>
+ *     <GoogleSignIn
+ *         component={GoogleLogin}
+ *         onSuccess={async ({ idToken }) => {
+ *             await api.post("/auth/google", { body: { id_token: idToken } });
+ *         }}
+ *         onError={(err) => toast.error(err.message)}
+ *     />
+ * </GoogleOAuthProvider>
+ */
+export declare function GoogleSignIn({ component: Component, onSuccess, onError, locale, theme, text, shape, size, disableOneTap, width, className, style, }: GoogleSignInProps): JSX.Element;
+
+export declare interface GoogleSignInProps {
+    /**
+     * `GoogleLogin` component from `@react-oauth/google`. The caller imports
+     * it and passes it through so the SDK doesn't take `@react-oauth/google`
+     * as a peer dep.
+     */
+    component: (props: Record<string, unknown>) => ReactNode;
+    /** Fired with the validated credential on success. */
+    onSuccess: (credential: OAuthCredential) => void | Promise<void>;
+    /** Fired with a normalised error on failure. */
+    onError?: (error: OAuthError) => void;
+    /** Optional locale override (e.g. `"pt-BR"`). Falls back to browser locale. */
+    locale?: string;
+    /** Visual theme — passed through to `<GoogleLogin>`. */
+    theme?: GoogleSignInTheme;
+    /** Button text variant. */
+    text?: GoogleSignInText;
+    /** Button shape. */
+    shape?: GoogleSignInShape;
+    /** Button size. */
+    size?: GoogleSignInSize;
+    /** Disable Google's "One Tap" auto-prompt. Default `false`. */
+    disableOneTap?: boolean;
+    /** Optional `width` override (px) — Google's button is fixed-width. */
+    width?: number;
+    /** Optional className applied to the wrapper. */
+    className?: string;
+    /** Optional inline style applied to the wrapper. */
+    style?: CSSProperties;
+}
+
+export declare type GoogleSignInShape = "rectangular" | "pill" | "circle" | "square";
+
+export declare type GoogleSignInSize = "large" | "medium" | "small";
+
+export declare type GoogleSignInText = "signin_with" | "signup_with" | "continue_with" | "signin";
+
+export declare type GoogleSignInTheme = "filled_blue" | "filled_black" | "outline";
+
 /** Simple CSS-Grid wrapper for equal-width or custom column layouts. */
 export declare function Grid({ columns, gap, className, style, children, ...props }: GridProps): JSX.Element;
 
@@ -1383,6 +1819,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;
@@ -1449,6 +1890,56 @@ export declare interface MoneyInputProps extends Omit<InputProps, "value" | "onC
     locale?: string;
 }
 
+/**
+ * Top app bar. Three-slot layout (logo / nav / actions) that collapses
+ * gracefully on mobile (nav slot wraps below).
+ *
+ * @example
+ * <Navbar
+ *     logo={<img src="/logo.svg" alt="App" />}
+ *     nav={<NavLinks />}
+ *     actions={<UserMenu />}
+ * />
+ */
+export declare function Navbar({ logo, nav, actions, sticky, tone, bordered, className, ...props }: NavbarProps): JSX.Element;
+
+export declare interface NavbarProps extends HTMLAttributes<HTMLElement> {
+    /** Left slot — typically logo + brand name. */
+    logo?: ReactNode;
+    /** Center slot — typically nav links. */
+    nav?: ReactNode;
+    /** Right slot — typically user menu / actions. */
+    actions?: ReactNode;
+    /** Make the bar sticky at the top of the scroll container. Default `true`. */
+    sticky?: boolean;
+    /** Visual tone. Default `"surface"`. */
+    tone?: NavbarTone;
+    /** When set, renders a thin bottom border. Default `true`. */
+    bordered?: boolean;
+}
+
+export declare type NavbarTone = "surface" | "primary" | "transparent";
+
+export declare interface OAuthCredential {
+    /** Provider-issued ID token (JWT). */
+    idToken: string;
+    /** Provider name (e.g. `"google"`, `"facebook"`). */
+    provider: string;
+    /** Raw response from the provider's SDK — opaque, for app-level inspection. */
+    raw?: unknown;
+}
+
+export declare interface OAuthError {
+    /** Provider name. */
+    provider: string;
+    /** Provider-specific error code, when available. */
+    code?: string;
+    /** Human-readable message. */
+    message: string;
+    /** Raw underlying error object. */
+    raw?: unknown;
+}
+
 export declare interface OfflineStore<TItem, TKey extends string | number> {
     /** Insert or replace a record. */
     put: (item: TItem, owner?: string) => Promise<TKey>;
@@ -1497,6 +1988,35 @@ export declare interface OfflineStoreConfig<TItem> {
     ownerField?: keyof TItem & string;
 }
 
+/**
+ * Page wrapper with header + (optional) toolbar + content + footer. Pairs
+ * with `Container` when you want a max-width content well.
+ *
+ * @example
+ * <Page title="Pedidos" description="Acompanhe seus pedidos" actions={<Button>Novo</Button>}>
+ *     <Table {...} />
+ * </Page>
+ */
+export declare function Page({ title, eyebrow, description, actions, toolbar, footer, padded, className, children, ...props }: PageProps): JSX.Element;
+
+export declare interface PageProps extends Omit<HTMLAttributes<HTMLElement>, "title"> {
+    /** Page title rendered as `<h1>`. */
+    title?: ReactNode;
+    /** Optional subtitle / breadcrumbs slot rendered above the title. */
+    eyebrow?: ReactNode;
+    /** Optional description rendered below the title. */
+    description?: ReactNode;
+    /** Right-side actions slot in the header (buttons, menus). */
+    actions?: ReactNode;
+    /** Sticky tab bar / filter row rendered just below the header. */
+    toolbar?: ReactNode;
+    /** Footer slot rendered at the bottom of the content area. */
+    footer?: ReactNode;
+    /** Page-level padding. Default `true`. */
+    padded?: boolean;
+    children?: ReactNode;
+}
+
 /**
  * Numeric pagination controls. Pair with {@link usePagination} for state.
  */
@@ -1529,7 +2049,9 @@ 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 { Path }
+
+export declare const PhoneInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
 } & RefAttributes<HTMLInputElement>>;
@@ -1556,6 +2078,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 +2215,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;
@@ -1762,6 +2360,28 @@ export declare interface RetryOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * Apply `env(safe-area-inset-*)` padding so content avoids iOS notch /
+ * Android navbar / device chrome. Wrap the outermost container of pages
+ * with sticky headers/footers.
+ *
+ * @example
+ * <SafeArea edges={["top"]}>
+ *     <Navbar />
+ * </SafeArea>
+ */
+export declare function SafeArea({ edges, inline, className, children, ...props }: SafeAreaProps): JSX.Element;
+
+export declare type SafeAreaEdge = "top" | "right" | "bottom" | "left";
+
+export declare interface SafeAreaProps extends HTMLAttributes<HTMLDivElement> {
+    /** Edges to pad. Default `["top","right","bottom","left"]` (all). */
+    edges?: SafeAreaEdge[];
+    /** Render as inline (use `display: contents`). */
+    inline?: boolean;
+    children?: ReactNode;
+}
+
 /**
  * Search input with magnifier icon and a clear button. Controlled component:
  * pass `value` and `onChange`.
@@ -1864,6 +2484,51 @@ export declare interface ShowProps {
     children: ReactNode;
 }
 
+/**
+ * Desktop sidebar navigation. Pair with `<Show above="md">` and a `Drawer`
+ * for mobile.
+ *
+ * @example
+ * const [tab, setTab] = useState("home");
+ * <Show above="md">
+ *     <Sidebar
+ *         header={<Brand />}
+ *         items={[{ key: "home", label: "Home", icon: <Home /> }]}
+ *         value={tab}
+ *         onChange={setTab}
+ *     />
+ * </Show>
+ */
+export declare function Sidebar({ header, items, value, onChange, footer, collapsed, width, collapsedWidth, className, style, ...props }: SidebarProps): JSX.Element;
+
+export declare interface SidebarItem {
+    key: string;
+    label: ReactNode;
+    icon?: ReactNode;
+    badge?: ReactNode;
+    disabled?: boolean;
+    href?: string;
+}
+
+export declare interface SidebarProps extends Omit<HTMLAttributes<HTMLElement>, "onChange"> {
+    /** Top slot — typically the logo + brand. */
+    header?: ReactNode;
+    /** Navigation items. */
+    items: SidebarItem[];
+    /** Active item key. */
+    value?: string;
+    /** Fires when an item is clicked. Receives the item's `key`. */
+    onChange?: (key: string) => void;
+    /** Bottom slot — typically settings/profile/logout. */
+    footer?: ReactNode;
+    /** Collapsed mode — only icons visible. Default `false`. */
+    collapsed?: boolean;
+    /** Width when expanded, in pixels or any CSS length. Default `240px`. */
+    width?: number | string;
+    /** Width when collapsed, in pixels or any CSS length. Default `64px`. */
+    collapsedWidth?: number | 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;
 
@@ -1881,6 +2546,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;
 
@@ -1920,6 +2605,32 @@ export declare const STALE_TIME: {
     readonly INFINITE: number;
 };
 
+/**
+ * KPI card. Dashboard widget showing a label + big value + optional
+ * delta/trend and hint.
+ *
+ * @example
+ * <Stat label="Receita" value="R$ 12.345" delta="+12,4%" trend="up" hint="vs. mês anterior" />
+ */
+export declare function Stat({ label, value, delta, trend, hint, icon, className, ...props }: StatProps): JSX.Element;
+
+export declare interface StatProps extends HTMLAttributes<HTMLDivElement> {
+    /** Metric label (e.g. "Revenue", "Active users"). */
+    label: ReactNode;
+    /** Metric value (e.g. "R$ 12.345", "1.2k"). */
+    value: ReactNode;
+    /** Optional comparison delta — when set, renders alongside the value. */
+    delta?: ReactNode;
+    /** Trend direction for the delta. Default inferred from delta string. */
+    trend?: StatTrend;
+    /** Optional supporting context line below the value. */
+    hint?: ReactNode;
+    /** Optional leading icon. */
+    icon?: ReactNode;
+}
+
+export declare type StatTrend = "up" | "down" | "flat";
+
 export declare interface StepItem {
     label: ReactNode;
 }
@@ -1952,6 +2663,8 @@ export declare const storage: {
     remove(key: string): void;
 };
 
+export { SubmitHandler }
+
 /** Toggle switch backed by a checkbox input. Accessible via keyboard. */
 export declare const Switch: ForwardRefExoticComponent<SwitchProps & RefAttributes<HTMLInputElement>>;
 
@@ -2026,6 +2739,33 @@ export declare interface TabsProps {
     className?: string;
 }
 
+/**
+ * Removable chip — used for filter tokens, applied search filters,
+ * selected entities. Different from `Badge` (status-only, not removable).
+ *
+ * @example
+ * <Tag variant="primary" onRemove={() => removeFilter("sao-paulo")}>
+ *     São Paulo
+ * </Tag>
+ */
+export declare function Tag({ variant, size, onRemove, removeLabel, className, children, ...props }: TagProps): JSX.Element;
+
+export declare interface TagProps extends Omit<HTMLAttributes<HTMLSpanElement>, "onRemove"> {
+    /** Visual variant. Default `"neutral"`. */
+    variant?: TagVariant;
+    /** Visual size. Default `"md"`. */
+    size?: TagSize;
+    /** When set, renders a close button that fires this callback. */
+    onRemove?: () => void;
+    /** Custom remove label for screen readers. Default `"Remover"`. */
+    removeLabel?: string;
+    children?: ReactNode;
+}
+
+export declare type TagSize = "sm" | "md" | "lg";
+
+export declare type TagVariant = "neutral" | "primary" | "success" | "warning" | "danger" | "info";
+
 export declare interface TelemetryAdapter {
     /** Optional. Called when the provider mounts. */
     init?: () => void | Promise<void>;
@@ -2158,6 +2898,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 +2984,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 +3122,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
@@ -2382,6 +3172,10 @@ export declare interface UseEventStreamResult<T> {
  */
 export declare function useFeatureFlag(key: string, defaultValue?: boolean): boolean;
 
+export { useFieldArray }
+
+export { UseFieldArrayReturn }
+
 /**
  * Read a typed flag value (string / number / boolean / null) and re-render
  * on change.
@@ -2395,6 +3189,18 @@ export declare function useFlagValue<T extends FlagValue = FlagValue>(key: strin
  */
 export declare function useFocusTrap(containerRef: RefObject<HTMLElement | null>, active: boolean): void;
 
+export { useForm }
+
+export { useFormContext }
+
+export { UseFormProps }
+
+export { UseFormRegister }
+
+export { UseFormReturn }
+
+export { useFormState }
+
 /** React hook around the Geolocation API. */
 export declare function useGeolocation(options?: UseGeolocationOptions): GeolocationState;
 
@@ -2447,6 +3253,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.
  *
@@ -2455,6 +3273,55 @@ export declare interface UseKeyboardShortcutOptions {
  */
 export declare function useMediaQuery(query: string): boolean;
 
+/**
+ * Run an OAuth-callback "exchange" exactly once on mount. Designed for
+ * `/callback` routes that receive provider redirects and need to swap a
+ * code/token for an app session via the backend.
+ *
+ * Survives React StrictMode double-mounting in dev — uses a ref guard to
+ * ensure `exchange` runs once.
+ *
+ * @example
+ * function OAuthCallback() {
+ *     const { loading, error } = useOAuthCallback({
+ *         exchange: async () => {
+ *             const code = new URLSearchParams(location.search).get("code")!;
+ *             return api.post("/auth/google/exchange", { body: { code } });
+ *         },
+ *         onSuccess: ({ token, user }) => {
+ *             useAuthStore.getState().setSession({ user, token });
+ *             navigate("/dashboard", { replace: true });
+ *         },
+ *         onError: () => navigate("/login?error=oauth", { replace: true }),
+ *     });
+ *
+ *     if (loading) return <Spinner />;
+ *     if (error) return <ErrorState description="OAuth falhou" />;
+ *     return null;
+ * }
+ */
+export declare function useOAuthCallback<T>(options: UseOAuthCallbackOptions<T>): UseOAuthCallbackResult<T>;
+
+export declare interface UseOAuthCallbackOptions<T> {
+    /** Function that exchanges the provider response for an app session. Called once on mount. */
+    exchange: () => Promise<T>;
+    /** Fired with the result on success. Receives the value resolved by `exchange`. */
+    onSuccess?: (result: T) => void | Promise<void>;
+    /** Fired when `exchange` throws or rejects. */
+    onError?: (error: unknown) => void;
+}
+
+export declare interface UseOAuthCallbackResult<T> {
+    /** `true` while the exchange promise is pending. */
+    loading: boolean;
+    /** Last resolved value, when `status === "success"`. */
+    data: T | null;
+    /** Last rejection reason, when `status === "error"`. */
+    error: unknown;
+    /** Aggregated state — `"pending"`, `"success"`, or `"error"`. */
+    status: "pending" | "success" | "error";
+}
+
 /**
  * Track the browser's `navigator.onLine` value and re-render on changes.
  * Returns `true` during SSR (assumption: server is online).
@@ -2574,6 +3441,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.
  */
@@ -2595,6 +3470,8 @@ export declare interface UseViaCEPResult {
     reset: () => void;
 }
 
+export { useWatch }
+
 /**
  * React hook around {@link createWebSocket}. Manages the connection lifecycle
  * for the host component and tears it down on unmount.