tempest-react-sdk 0.3.0 → 0.5.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,11 +30,19 @@ 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';
 
 /**
@@ -119,6 +136,40 @@ 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`
@@ -236,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;
@@ -400,6 +550,16 @@ export declare interface ChipInputProps {
     className?: string;
 }
 
+/**
+ * Clamp `value` between `min` and `max` (inclusive).
+ *
+ * @example
+ * clamp(120, 0, 100); // 100
+ * clamp(-5, 0, 100);  // 0
+ * clamp(42, 0, 100);  // 42
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+
 declare type ClassValue = string | number | bigint | boolean | null | undefined | ClassValue[];
 
 /**
@@ -484,6 +644,10 @@ export declare interface ContainerProps extends HTMLAttributes<HTMLDivElement> {
 
 export declare type ContainerSize = "sm" | "md" | "lg" | "xl" | "full";
 
+export { Control }
+
+export { Controller }
+
 export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
@@ -1051,6 +1215,8 @@ export declare interface ErrorStateProps {
     className?: string;
 }
 
+export declare function estimatePasswordStrength(value: string): PasswordStrength;
+
 export declare interface EventStreamController {
     close: () => void;
     /** Force an immediate reconnect, resetting the retry counter. */
@@ -1089,6 +1255,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.
@@ -1214,11 +1390,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 +
@@ -1286,6 +1521,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;
 
@@ -1602,6 +1902,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>;
@@ -1650,6 +2000,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.
  */
@@ -1682,11 +2061,90 @@ export declare interface PaginationProps {
  */
 export declare function parseResponse<TSchema extends z.ZodTypeAny>(schema: TSchema, raw: unknown, context: string): z.infer<TSchema>;
 
+/**
+ * Password field with toggle-visibility button and optional strength meter.
+ *
+ * @example
+ * <PasswordInput label="Senha" showStrength autoComplete="new-password" />
+ */
+export declare const PasswordInput: ForwardRefExoticComponent<PasswordInputProps & RefAttributes<HTMLInputElement>>;
+
+export declare interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "size"> {
+    /** Label rendered above the input. */
+    label?: ReactNode;
+    /** Helper text below — replaced by `error` when set. */
+    helperText?: ReactNode;
+    /** Error message. Adds `aria-invalid` + red border. */
+    error?: string;
+    /** Visual size of the input. */
+    size?: "sm" | "md" | "lg";
+    /** Show a strength meter below the field. Default `false`. */
+    showStrength?: boolean;
+    /** Override the automatic strength calc (0–4). */
+    strength?: PasswordStrength;
+    /** Custom labels per strength level (5 entries). */
+    strengthLabels?: readonly [string, string, string, string, string];
+    /** Custom toggle button labels for accessibility. */
+    toggleLabels?: {
+        show: string;
+        hide: string;
+    };
+}
+
+export declare type PasswordStrength = 0 | 1 | 2 | 3 | 4;
+
+export { Path }
+
 export declare const PhoneInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
 } & RefAttributes<HTMLInputElement>>;
 
+/**
+ * One-time-password style input — N independent cells, paste support, auto-
+ * advance on input, backspace flows back, arrow keys navigate.
+ *
+ * @example
+ * <PinInput length={6} type="numeric" onComplete={(otp) => verify(otp)} />
+ */
+export declare const PinInput: ForwardRefExoticComponent<PinInputProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface PinInputProps {
+    /** Number of cells. Default `6`. */
+    length?: number;
+    /** Allowed character set. `numeric` (default) rejects letters, `alphanumeric` allows both. */
+    type?: PinInputType;
+    /** Visual size. Default `"md"`. */
+    size?: PinInputSize;
+    /** Controlled value. */
+    value?: string;
+    /** Initial value (uncontrolled mode). */
+    defaultValue?: string;
+    /** Fires on every change with the current concatenated value. */
+    onChange?: (value: string) => void;
+    /** Fires when the user fills the last cell. */
+    onComplete?: (value: string) => void;
+    /** Show characters obscured (`*`). Default `false`. */
+    masked?: boolean;
+    /** Label rendered above the cells. */
+    label?: string;
+    /** Helper text below the cells. */
+    helperText?: string;
+    /** Error message — turns cells red and replaces helperText. */
+    error?: string;
+    /** Disable all cells. */
+    disabled?: boolean;
+    /** Auto-focus the first cell on mount. Default `false`. */
+    autoFocus?: boolean;
+    /** id for the wrapping group label association. */
+    id?: string;
+    className?: string;
+}
+
+export declare type PinInputSize = "sm" | "md" | "lg";
+
+export declare type PinInputType = "numeric" | "alphanumeric";
+
 /**
  * Convenience wrapper around a shared {@link AudioPlayer}. Use this for
  * one-off notification sounds. For more complex flows (e.g. several
@@ -1927,6 +2385,21 @@ export declare interface RegisterServiceWorkerOptions {
     onError?: (error: unknown) => void;
 }
 
+/**
+ * Render a `Date` / ISO string as a relative-time string. Supports past and
+ * future, PT-BR (default) and English.
+ *
+ * @example
+ * relativeTime(new Date(Date.now() - 90_000));         // "1 min atrás"
+ * relativeTime("2026-05-17T10:00:00Z", { locale: "en" }); // "5h ago"
+ */
+export declare function relativeTime(input: Date | string | number, options?: {
+    locale?: RelativeTimeLocale;
+    now?: Date | number;
+}): string;
+
+export declare type RelativeTimeLocale = "pt-BR" | "en";
+
 export declare interface RequestOptions extends Omit<RequestInit, "body"> {
     body?: unknown;
     params?: Record<string, string | number | boolean | undefined | null>;
@@ -1991,6 +2464,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`.
@@ -2004,6 +2499,44 @@ export declare interface SearchBarProps extends Omit<InputHTMLAttributes<HTMLInp
     wrapperClassName?: string;
 }
 
+/**
+ * iOS-style segmented control. Two-to-five mutually-exclusive options
+ * rendered as a single connected pill bar.
+ *
+ * @example
+ * <SegmentedControl
+ *     value={view}
+ *     onChange={setView}
+ *     options={[
+ *         { value: "list", label: "Lista" },
+ *         { value: "grid", label: "Grade" },
+ *     ]}
+ * />
+ */
+export declare function SegmentedControl<TValue extends string = string>({ options, value, onChange, size, fullWidth, className, "aria-label": ariaLabel, ...props }: SegmentedControlProps<TValue>): JSX.Element;
+
+export declare interface SegmentedControlOption<TValue extends string = string> {
+    value: TValue;
+    label: ReactNode;
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+
+export declare interface SegmentedControlProps<TValue extends string = string> extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    /** Available segments. */
+    options: SegmentedControlOption<TValue>[];
+    /** Selected value. */
+    value: TValue;
+    /** Fires with the new value when a segment is selected. */
+    onChange: (value: TValue) => void;
+    /** Visual size. Default `"md"`. */
+    size?: "sm" | "md" | "lg";
+    /** Stretch to full width of container. Default `false`. */
+    fullWidth?: boolean;
+    /** Group label for screen readers. */
+    "aria-label"?: string;
+}
+
 /**
  * Native `<select>` wrapper with label/helper/error slots. Either provide
  * `options` for a quick render, or pass `<option>` children directly.
@@ -2093,6 +2626,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;
 
@@ -2110,6 +2688,19 @@ export declare interface SkeletonProps {
  */
 export declare function skipWaiting(worker: ServiceWorker): void;
 
+/**
+ * Convert a string into a URL-safe slug.
+ *
+ * - Strips accents/diacritics.
+ * - Lowercases.
+ * - Replaces non-alphanumeric runs with `-`.
+ * - Trims leading/trailing separators.
+ *
+ * @example
+ * slugify("São Paulo / Centro"); // "sao-paulo-centro"
+ */
+export declare function slugify(input: string): string;
+
 /**
  * Flex spacer — pushes siblings apart inside a flex container. Equivalent
  * to `<div style={{ flex: 1 }}>` but typed and intent-revealing.
@@ -2169,6 +2760,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;
 }
@@ -2180,6 +2797,42 @@ export declare interface StepItem {
  */
 export declare function Stepper({ steps, current, orientation, className }: StepperProps): JSX.Element;
 
+/**
+ * Numeric +/− stepper. Common in checkout quantity selectors and admin
+ * forms. Clamps to `[min, max]` and emits already-bounded values.
+ *
+ * @example
+ * <StepperInput value={qty} onChange={setQty} min={1} max={10} />
+ */
+export declare const StepperInput: ForwardRefExoticComponent<StepperInputProps & RefAttributes<HTMLDivElement>>;
+
+export declare interface StepperInputProps {
+    /** Current value. */
+    value: number;
+    /** Fires with the new value (already clamped to min/max). */
+    onChange: (value: number) => void;
+    /** Lower bound. Default `0`. */
+    min?: number;
+    /** Upper bound. Default `Number.POSITIVE_INFINITY`. */
+    max?: number;
+    /** Increment per click. Default `1`. */
+    step?: number;
+    /** Visual size. Default `"md"`. */
+    size?: "sm" | "md" | "lg";
+    /** Disable the whole control. */
+    disabled?: boolean;
+    /** Optional label rendered above. */
+    label?: ReactNode;
+    /** Optional formatter for the displayed value. */
+    format?: (value: number) => string;
+    /** Custom button labels for accessibility. */
+    labels?: {
+        decrement: string;
+        increment: string;
+    };
+    className?: string;
+}
+
 export declare interface StepperProps {
     steps: StepItem[];
     /** Index of the currently active step (0-based). */
@@ -2201,6 +2854,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>>;
 
@@ -2275,6 +2930,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>;
@@ -2372,6 +3054,43 @@ export declare interface ThemeProviderProps {
     attribute?: string;
 }
 
+/**
+ * Vertical event timeline — activity feeds, order trackers, audit logs.
+ * Each entry has a marker (color or custom icon), title, optional
+ * description and right-aligned meta column.
+ *
+ * @example
+ * <Timeline items={[
+ *     { id: "1", title: "Pedido criado", meta: "10:24", marker: "primary" },
+ *     { id: "2", title: "Aprovação", meta: "10:25", marker: "success" },
+ *     { id: "3", title: "Saiu pra entrega", meta: "11:00", marker: "warning" },
+ * ]} />
+ */
+export declare function Timeline({ items, connector, className, ...props }: TimelineProps): JSX.Element;
+
+export declare interface TimelineItem {
+    /** Stable identifier (used as React key). */
+    id: string;
+    /** Title rendered as the entry headline. */
+    title: ReactNode;
+    /** Optional subtitle / description below the title. */
+    description?: ReactNode;
+    /** Right-aligned meta column (timestamps, durations). */
+    meta?: ReactNode;
+    /** Optional custom icon rendered inside the marker. */
+    icon?: ReactNode;
+    /** Marker color. Default `"primary"`. */
+    marker?: TimelineMarker;
+}
+
+export declare type TimelineMarker = "primary" | "success" | "warning" | "danger" | "neutral";
+
+export declare interface TimelineProps extends HTMLAttributes<HTMLOListElement> {
+    items: TimelineItem[];
+    /** Show the connecting line between markers. Default `true`. */
+    connector?: boolean;
+}
+
 export declare interface ToastApi {
     show: (options: ToastOptions) => string;
     dismiss: (id: string) => void;
@@ -2436,6 +3155,16 @@ export declare interface TooltipProps {
     openDelay?: number;
 }
 
+/**
+ * Truncate a string to `max` characters, appending `suffix` when cut.
+ * Returns the original when shorter than (or equal to) `max`.
+ *
+ * @example
+ * truncate("The quick brown fox", 12);              // "The quick…"
+ * truncate("The quick brown fox", 12, " (more)");   // "The qu (more)"
+ */
+export declare function truncate(input: string, max: number, suffix?: string): string;
+
 /** Strip any masking and return only digits. */
 export declare function unmask(value: string): string;
 
@@ -2681,6 +3410,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.
@@ -2694,6 +3427,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;
 
@@ -2704,6 +3449,17 @@ export declare interface UseGeolocationOptions extends PositionOptions {
     disabled?: boolean;
 }
 
+/**
+ * Track whether the pointer is hovering over the referenced element.
+ * Returns `false` on touch-only devices (no pointer hover).
+ *
+ * @example
+ * const ref = useRef<HTMLDivElement>(null);
+ * const hovered = useHover(ref);
+ * return <div ref={ref}>{hovered ? "✨" : ""}</div>;
+ */
+export declare function useHover<T extends HTMLElement>(ref: RefObject<T | null>): boolean;
+
 /**
  * Access translation helpers. Must be used inside an {@link I18nProvider}.
  */
@@ -2728,6 +3484,15 @@ export declare interface UseIntersectionObserverOptions extends IntersectionObse
     once?: boolean;
 }
 
+/**
+ * Reactive `setInterval`. Pass `null` as `delay` to pause. `fn` is stored in
+ * a ref so inline callbacks don't reset the interval on every render.
+ *
+ * @example
+ * useInterval(() => poll(), enabled ? 5000 : null);
+ */
+export declare function useInterval(fn: () => void, delay: number | null): void;
+
 /**
  * Bind a global keyboard shortcut. Supports modifier combinations and a
  * cross-OS `mod` key (Ctrl on Windows/Linux, Cmd on macOS).
@@ -2758,6 +3523,24 @@ export declare interface UseKeyboardShortcutOptions {
  */
 export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: LocalStorageOptions<T>): [T, (value: T | ((prev: T) => T)) => void, () => void];
 
+/**
+ * Detect long-press / long-tap gestures. Fires `fn` after `delay` ms
+ * while the element is held. Cancels on move beyond `moveThreshold` or
+ * pointer up before `delay`.
+ *
+ * @example
+ * const ref = useRef<HTMLDivElement>(null);
+ * useLongPress(ref, () => openContextMenu(), { delay: 600 });
+ */
+export declare function useLongPress<T extends HTMLElement>(ref: RefObject<T | null>, fn: () => void, options?: UseLongPressOptions): void;
+
+export declare interface UseLongPressOptions {
+    /** Press duration in ms. Default `500`. */
+    delay?: number;
+    /** Pixel threshold — finger/mouse movement beyond this cancels the press. Default `10`. */
+    moveThreshold?: number;
+}
+
 /**
  * Subscribe to a CSS media query and re-render on match changes.
  *
@@ -2766,6 +3549,55 @@ export declare function useLocalStorage<T>(key: string, defaultValue: T, options
  */
 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).
@@ -2815,6 +3647,19 @@ export declare interface UsePollResult<T> {
     start: () => void;
 }
 
+/**
+ * Return the value from the previous render. `undefined` on the first render.
+ *
+ * @example
+ * const previousCount = usePrevious(count);
+ * useEffect(() => {
+ *     if (previousCount !== undefined && previousCount !== count) {
+ *         analytics.track("count.changed", { from: previousCount, to: count });
+ *     }
+ * }, [count, previousCount]);
+ */
+export declare function usePrevious<T>(value: T): T | undefined;
+
 /**
  * React hook around {@link WebPushClient}. Tracks subscription, permission and
  * loading state; exposes imperative `subscribe`/`unsubscribe` actions.
@@ -2878,6 +3723,25 @@ export declare function useTelemetry(): TelemetryAdapter | null;
  */
 export declare function useTheme(): ThemeContextValue;
 
+/**
+ * Return a value that updates at most once every `delay` ms. Complements
+ * `useDebounce` — throttle emits on the leading edge and again after the
+ * interval; debounce only emits after a period of stillness.
+ *
+ * @example
+ * const throttledScroll = useThrottle(scrollY, 100);
+ */
+export declare function useThrottle<T>(value: T, delay: number): T;
+
+/**
+ * Run a callback after `delay` ms. Pass `null` to disable. Resets when
+ * `delay` changes; the callback ref always points at the latest closure.
+ *
+ * @example
+ * useTimeout(() => setShow(false), show ? 3000 : null);
+ */
+export declare function useTimeout(fn: () => void, delay: number | null): void;
+
 /**
  * Access the toast API. Must be used inside a {@link ToastProvider}.
  *
@@ -2914,6 +3778,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.
@@ -2935,6 +3801,16 @@ export declare interface UseWebSocketResult<T> {
     reconnect: () => void;
 }
 
+/**
+ * Reactive window dimensions. SSR-safe — returns `{ width: 0, height: 0 }`
+ * until the first client render.
+ *
+ * @example
+ * const { width, height } = useWindowSize();
+ * const columns = width < 640 ? 1 : width < 1024 ? 2 : 3;
+ */
+export declare function useWindowSize(): WindowSize;
+
 /**
  * Convenience wrapper around `react-hook-form`'s `useForm` that wires a zod
  * resolver and infers the form's value type from the schema.
@@ -3114,6 +3990,11 @@ export declare interface WebSocketMessage<T> {
 
 export declare type WebSocketStatus = "idle" | "connecting" | "open" | "closing" | "closed" | "error";
 
+export declare interface WindowSize {
+    width: number;
+    height: number;
+}
+
 /**
  * Minimal `react-hook-form` resolver built on top of zod. Mirrors the shape
  * produced by `@hookform/resolvers/zod` so it can be passed straight to