tempest-react-sdk 0.10.0 → 0.11.0

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

@@ -82,15 +82,52 @@ import { useFormState } from 'react-hook-form';
 import { UseInfiniteQueryOptions } from '@tanstack/react-query';
 import { useLocation } from 'react-router-dom';
 import { useMatch } from 'react-router-dom';
+import { UseMutationOptions } from '@tanstack/react-query';
+import { UseMutationResult } from '@tanstack/react-query';
 import { useNavigate } from 'react-router-dom';
 import { useParams } from 'react-router-dom';
 import { UseQueryOptions } from '@tanstack/react-query';
+import { UseQueryResult } from '@tanstack/react-query';
 import { useRouteError } from 'react-router-dom';
 import { useSearchParams } from 'react-router-dom';
 import { useWatch } from 'react-hook-form';
 import { WheelEventHandler } from 'react';
 import { z } from 'zod';
 
+/**
+ * A pluggable access-control strategy. Implementations decide whether a given
+ * action is allowed, returning a plain boolean, a {@link CanResult}, or a
+ * promise of either (for async sources such as a remote policy server).
+ */
+export declare interface AccessControl {
+    /**
+     * Resolve whether the described action is permitted.
+     *
+     * @param params - The action/resource being checked.
+     * @returns `true`/`false`, a {@link CanResult}, or a promise of either.
+     */
+    can: (params: CanParams) => boolean | CanResult | Promise<boolean | CanResult>;
+}
+
+/**
+ * Provide an {@link AccessControl} strategy to the React tree. Components such
+ * as `<Can>` and the `useCan` hook read it from context.
+ *
+ * @example
+ * ```tsx
+ * <AccessControlProvider control={createRoleAccessControl({ role: "admin", roles: { admin: ["*"] } })}>
+ *   <App />
+ * </AccessControlProvider>
+ * ```
+ */
+export declare function AccessControlProvider({ control, children }: AccessControlProviderProps): JSX.Element;
+
+export declare interface AccessControlProviderProps {
+    /** The access-control strategy made available to descendants. */
+    control: AccessControl;
+    children: ReactNode;
+}
+
 /**
  * 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
@@ -682,6 +719,50 @@ export declare interface CalendarProps extends Omit<HTMLAttributes<HTMLDivElemen
  */
 export declare function camelCase(value: string): string;
 
+/**
+ * Conditionally render based on an access check. Renders `children` when the
+ * action is allowed, otherwise `fallback` (or nothing). While an async check is
+ * pending, nothing is rendered.
+ *
+ * @example
+ * ```tsx
+ * <Can action="create" resource="posts" fallback={<p>No access</p>}>
+ *   <NewPostButton />
+ * </Can>
+ * ```
+ */
+export declare function Can({ action, resource, params, children, fallback }: CanProps): JSX.Element;
+
+/**
+ * Arguments describing the access check to perform.
+ */
+export declare interface CanParams {
+    /** The action being attempted (e.g. `"create"`, `"read"`, `"delete"`). */
+    action: string;
+    /** The resource the action targets (e.g. `"posts"`). Optional for global actions. */
+    resource?: string;
+    /** Arbitrary extra context an access-control strategy may inspect. */
+    params?: Record<string, unknown>;
+}
+
+export declare interface CanProps extends CanParams {
+    /** Rendered when the action is allowed. */
+    children: ReactNode;
+    /** Rendered when the action is denied. Defaults to nothing. */
+    fallback?: ReactNode;
+}
+
+/**
+ * Detailed result of an access check. Use the bare `boolean` form when no
+ * reason is needed, or this object to surface *why* access was denied.
+ */
+export declare interface CanResult {
+    /** Whether the action is permitted. */
+    can: boolean;
+    /** Human-readable explanation, typically present when `can` is `false`. */
+    reason?: string;
+}
+
 /**
  * Uppercase the first character of `value`, leaving the rest untouched.
  *
@@ -1003,6 +1084,24 @@ export declare interface ConfirmDialogProps {
     onCancel: () => void;
 }
 
+/** Options accepted by {@link ModalsApi.confirm}. */
+export declare interface ConfirmModalOptions {
+    /** Header title. */
+    title?: ReactNode;
+    /** Prompt message rendered in the dialog body. */
+    message: ReactNode;
+    /** Confirm button label. Default `Confirmar`. */
+    confirmLabel?: string;
+    /** Cancel button label. Default `Cancelar`. */
+    cancelLabel?: string;
+    /** Render the confirm button in the danger variant. */
+    danger?: boolean;
+    /** Called when the user confirms. */
+    onConfirm?: () => void | Promise<void>;
+    /** Called when the user cancels or dismisses. */
+    onCancel?: () => void;
+}
+
 /** Default sink that writes to the browser console. */
 export declare const consoleSink: LoggerSink;
 
@@ -1083,6 +1182,13 @@ export declare interface CopyButtonProps extends ButtonHTMLAttributes<HTMLButton
     onCopied?: () => void;
 }
 
+export declare interface CounterHandlers {
+    increment: () => void;
+    decrement: () => void;
+    set: (value: number) => void;
+    reset: () => void;
+}
+
 export declare const CPFInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
@@ -1137,6 +1243,29 @@ export declare interface CreateAuthStoreOptions<TUser> {
     initialToken?: string | null;
 }
 
+/**
+ * Create a {@link DataProvider} bound to an {@link ApiClient}.
+ *
+ * Maps Refine-style calls to the Tempest FastAPI SDK conventions: list →
+ * `GET /{resource}?page=&size=&order_by=&ascending=&...filters`, one →
+ * `GET /{resource}/{id}`, create → `POST`, update → `PATCH`/`PUT`,
+ * delete → `DELETE`.
+ *
+ * @param client - The HTTP client created by `createApiClient`.
+ * @param options - Optional overrides for param names, sort encoding,
+ *   update method and path building.
+ * @returns A stateless data provider.
+ *
+ * @example
+ * const dataProvider = createDataProvider(apiClient);
+ * const page = await dataProvider.getList<User>("users", {
+ *     pagination: { page: 1, pageSize: 20 },
+ *     sort: { field: "created_at", order: "desc" },
+ *     filters: { active: true },
+ * });
+ */
+export declare function createDataProvider(client: ApiClient, options?: DataProviderOptions): DataProvider;
+
 /**
  * Open a Server-Sent Events stream with automatic exponential-backoff reconnect.
  *
@@ -1379,6 +1508,30 @@ export declare function createQueryKeys<TKey extends string, TEntries extends Re
  */
 export declare function createRefreshQueue(refresh: () => Promise<void>): () => Promise<void>;
 
+/**
+ * Build a simple RBAC {@link AccessControl} from a static permission set.
+ *
+ * Permission strings are `"<resource>:<action>"` (e.g. `"posts:create"`) or a
+ * bare `"<action>"`. Wildcards are supported: `"*"` grants everything and
+ * `"<resource>:*"` grants every action on a resource.
+ *
+ * The effective set is `config.permissions` plus, for each active role in
+ * `config.role`, the permissions listed in `config.roles[role]`.
+ *
+ * @param config - Permissions, role map, and active role(s).
+ * @returns An access-control strategy backed by the resolved permission set.
+ *
+ * @example
+ * ```ts
+ * const ac = createRoleAccessControl({
+ *   role: "editor",
+ *   roles: { editor: ["posts:*", "comments:read"] },
+ * });
+ * ac.can({ action: "create", resource: "posts" }); // true
+ * ```
+ */
+export declare function createRoleAccessControl(config: RoleAccessControlConfig): AccessControl;
+
 /**
  * Attach auto-generated selector hooks to a Zustand store. Instead of writing
  * `useStore((s) => s.user)` at every call site, you get `useStore.use.user()`
@@ -1603,6 +1756,9 @@ export declare interface CursorParams {
     ascending?: boolean;
 }
 
+/** Filters passed to {@link DataProvider.getList}, spread verbatim into the query string. */
+export declare type DataFilters = Record<string, ParamValue>;
+
 /**
  * Generic, typed list that renders a `<ul>` with one `<li>` per item.
  *
@@ -1629,6 +1785,86 @@ export declare interface DataListProps<T> extends HTMLAttributes<HTMLUListElemen
     empty?: ReactNode;
 }
 
+/**
+ * Refine-style data provider over the Tempest FastAPI SDK CRUD/pagination
+ * conventions. Implementations are stateless wrappers around an {@link ApiClient}.
+ */
+export declare interface DataProvider {
+    /**
+     * Fetch a paginated list of a resource.
+     *
+     * @param resource - The resource name (e.g. `"users"`).
+     * @param params - Pagination, sort and filter parameters.
+     * @returns The offset-paginated envelope.
+     */
+    getList<T>(resource: string, params?: GetListParams): Promise<OffsetPage<T>>;
+    /**
+     * Fetch a single record by id.
+     *
+     * @param resource - The resource name.
+     * @param id - The record id.
+     * @returns The record.
+     */
+    getOne<T>(resource: string, id: string | number): Promise<T>;
+    /**
+     * Fetch many records by id (default: parallel {@link DataProvider.getOne}).
+     *
+     * @param resource - The resource name.
+     * @param ids - The record ids.
+     * @returns The records, in the same order as `ids`.
+     */
+    getMany<T>(resource: string, ids: (string | number)[]): Promise<T[]>;
+    /**
+     * Create a record.
+     *
+     * @param resource - The resource name.
+     * @param data - The creation payload.
+     * @returns The created record.
+     */
+    create<T>(resource: string, data: unknown): Promise<T>;
+    /**
+     * Update a record (PATCH by default, PUT when configured).
+     *
+     * @param resource - The resource name.
+     * @param id - The record id.
+     * @param data - The update payload.
+     * @returns The updated record.
+     */
+    update<T>(resource: string, id: string | number, data: unknown): Promise<T>;
+    /**
+     * Delete a record by id.
+     *
+     * @param resource - The resource name.
+     * @param id - The record id.
+     * @returns The delete response (often the deleted record).
+     */
+    deleteOne<T>(resource: string, id: string | number): Promise<T>;
+}
+
+/** Options to tailor {@link createDataProvider} to a backend's conventions. */
+export declare interface DataProviderOptions {
+    /** Query-param name for the page number. Default: `"page"`. */
+    pageParam?: string;
+    /** Query-param name for the page size. Default: `"size"`. */
+    sizeParam?: string;
+    /** Query-param name for the sort field. Default: `"order_by"`. */
+    sortFieldParam?: string;
+    /** Query-param name for the sort order. Default: `"ascending"`. */
+    sortOrderParam?: string;
+    /**
+     * When `true` (default), emit the sort order as a boolean
+     * (`order:"asc"` → `true`). When `false`, emit the literal `"asc"`/`"desc"`.
+     */
+    sortOrderAsBoolean?: boolean;
+    /** HTTP method used by {@link DataProvider.update}. Default: `"patch"`. */
+    updateMethod?: "patch" | "put";
+    /**
+     * Build the request path for a resource (and optional id).
+     * Default: `id == null ? "/" + resource : "/" + resource + "/" + id`.
+     */
+    buildPath?: (resource: string, id?: string | number) => string;
+}
+
 /**
  * Stateful, headless data table built on top of {@link Table}. Adds
  * client-side searching, click-to-sort columns, and pagination while
@@ -1713,6 +1949,37 @@ export declare interface DatePickerProps extends Omit<InputHTMLAttributes<HTMLIn
     wrapperClassName?: string;
 }
 
+/** A selected range. Either bound may be `null` while picking. */
+export declare interface DateRange {
+    start: Date | null;
+    end: Date | null;
+}
+
+/**
+ * Date-range picker: pick a start day, then an end day, across one or more
+ * month grids. The hovered day previews the range before the end is committed.
+ * Pure `Date` math — no date libraries. For a single date, use `Calendar`.
+ *
+ * Selection: first click sets `start` (clears `end`); the next click sets `end`
+ * (auto-ordered if you click earlier than the start); a third click starts over.
+ */
+export declare function DateRangePicker({ value, onChange, numberOfMonths, defaultMonth, minDate, maxDate, weekStartsOn, className, ...props }: DateRangePickerProps): JSX.Element;
+
+export declare interface DateRangePickerProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange" | "defaultValue"> {
+    /** Controlled selected range. */
+    value: DateRange;
+    /** Called with the new range as the user picks start then end. */
+    onChange: (range: DateRange) => void;
+    /** How many month grids to show side by side. Default `2`. */
+    numberOfMonths?: number;
+    /** Initial visible month (uncontrolled). Defaults to the range start or today. */
+    defaultMonth?: Date;
+    minDate?: Date;
+    maxDate?: Date;
+    /** First column of the week — `0` Sunday (default) or `1` Monday. */
+    weekStartsOn?: WeekStart_2;
+}
+
 /**
  * Create a trailing-edge debounced version of `fn`.
  *
@@ -1805,6 +2072,12 @@ export declare interface DescriptionListProps extends HTMLAttributes<HTMLDListEl
     items: DescriptionListItem[];
 }
 
+export declare interface DisclosureHandlers {
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+}
+
 /**
  * Horizontal or vertical visual separator. When `label` is provided in
  * horizontal mode the divider splits and centers the label between two lines.
@@ -1897,6 +2170,37 @@ export declare interface DropdownMenuProps {
     className?: string;
 }
 
+/**
+ * Drag-and-drop file area with a hidden file input. Clickable and keyboard
+ * focusable; filters by `maxSize` before calling `onDrop`.
+ *
+ * @example
+ * <Dropzone accept="image/*" maxSize={5 * 1024 * 1024} onDrop={setFiles}>
+ *     Solte imagens aqui ou clique para selecionar
+ * </Dropzone>
+ */
+export declare function Dropzone({ onDrop, accept, multiple, disabled, maxSize, onReject, children, className, }: DropzoneProps): JSX.Element;
+
+/** Props for {@link Dropzone}. */
+export declare interface DropzoneProps {
+    /** Called with the accepted files after a drop or file-dialog selection. */
+    onDrop: (files: File[]) => void;
+    /** `accept` attribute forwarded to the hidden file input. */
+    accept?: string;
+    /** Allow selecting/dropping multiple files. Default `true`. */
+    multiple?: boolean;
+    /** Disable interaction. */
+    disabled?: boolean;
+    /** Maximum file size in bytes; larger files are filtered out. */
+    maxSize?: number;
+    /** Called with files rejected by `maxSize`. */
+    onReject?: (files: File[]) => void;
+    /** Custom inner content. Falls back to a default prompt. */
+    children?: ReactNode;
+    /** Extra class applied to the drop area. */
+    className?: string;
+}
+
 export declare interface ElementSize {
     width: number;
     height: number;
@@ -2084,6 +2388,46 @@ export declare type FilterPredicate<T> = (item: T, search: string) => boolean;
 
 export declare type FlagValue = boolean | string | number | null;
 
+/**
+ * Material Floating Action Button. Renders a round FAB when only an `icon` is
+ * given, or an extended pill FAB when a `label` is also provided. By default it
+ * is fixed to the bottom-right corner; set `position="none"` to place it inline.
+ *
+ * Spreads all native `<button>` props (`onClick`, `disabled`, etc.).
+ *
+ * @remarks
+ * Always pass an `aria-label` when there is no `label`, since an icon-only FAB
+ * has no accessible name otherwise.
+ *
+ * @example
+ * <FloatingActionButton icon={<Plus />} aria-label="Adicionar" onClick={create} />
+ *
+ * @example
+ * <FloatingActionButton icon={<Plus />} label="Novo" onClick={create} />
+ */
+export declare function FloatingActionButton({ icon, label, position, size, variant, className, ...props }: FloatingActionButtonProps): JSX.Element;
+
+declare type FloatingActionButtonPosition = "bottom-right" | "bottom-left" | "none";
+
+export declare interface FloatingActionButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Icon rendered inside the FAB. Required. */
+    icon: ReactNode;
+    /** When present, renders an extended (pill) FAB with icon + label. */
+    label?: ReactNode;
+    /** Corner placement, or `"none"` for static/inline. Default `"bottom-right"`. */
+    position?: FloatingActionButtonPosition;
+    /** Size token. Default `"md"`. */
+    size?: FloatingActionButtonSize;
+    /** Visual style. Default `"primary"`. */
+    variant?: FloatingActionButtonVariant;
+    /** Extra class names merged onto the root. */
+    className?: string;
+}
+
+declare type FloatingActionButtonSize = "sm" | "md" | "lg";
+
+declare type FloatingActionButtonVariant = "primary" | "surface";
+
 /**
  * Typed, JSX-friendly list renderer.
  *
@@ -2356,6 +2700,22 @@ export declare interface GetInitialThemeOptions {
     defaultTheme?: ThemeMode;
 }
 
+/** Parameters for a paginated, sorted, filtered list request. */
+export declare interface GetListParams {
+    /** Offset pagination — 1-based `page` and `pageSize`. */
+    pagination?: {
+        page?: number;
+        pageSize?: number;
+    };
+    /** Single-field sort. `order` defaults to `"asc"`. */
+    sort?: {
+        field: string;
+        order?: "asc" | "desc";
+    };
+    /** Arbitrary filter query params, spread onto the request. */
+    filters?: DataFilters;
+}
+
 /**
  * Thin wrapper over `@react-oauth/google`'s `<GoogleLogin>` that:
  *
@@ -2929,6 +3289,63 @@ export declare interface ListOptions<TItem> {
     filter?: (item: TItem) => boolean;
 }
 
+/**
+ * Build the cache key for a resource list query.
+ *
+ * @param resource - The resource name.
+ * @param params - The list params (page/sort/filters).
+ * @returns A stable TanStack Query key.
+ */
+export declare function listQueryKey(resource: string, params?: GetListParams): unknown[];
+
+export declare interface ListStateHandlers<T> {
+    append: (...items: T[]) => void;
+    prepend: (...items: T[]) => void;
+    insert: (index: number, ...items: T[]) => void;
+    remove: (...indices: number[]) => void;
+    reorder: (payload: ReorderPayload) => void;
+    setItem: (index: number, item: T) => void;
+    setState: (items: T[]) => void;
+    apply: (fn: (item: T, index: number) => T) => void;
+    clear: () => void;
+}
+
+/**
+ * The canonical Material list row: an optional leading slot, a title with an
+ * optional subtitle, and an optional trailing slot. When `onClick` is supplied
+ * the tile renders as a full-width, keyboard-accessible `<button>`; otherwise it
+ * renders as a static `<div>`.
+ *
+ * @example
+ * <ListTile
+ *     leading={<User />}
+ *     title="Maria Silva"
+ *     subtitle="maria@example.com"
+ *     trailing={<ChevronRight />}
+ *     onClick={() => open(user)}
+ * />
+ */
+export declare function ListTile({ leading, title, subtitle, trailing, onClick, disabled, selected, className, }: ListTileProps): JSX.Element;
+
+export declare interface ListTileProps {
+    /** Left slot — typically an icon or avatar. */
+    leading?: ReactNode;
+    /** Primary line. Required. */
+    title: ReactNode;
+    /** Secondary line rendered under the title. */
+    subtitle?: ReactNode;
+    /** Right slot — typically an icon, switch or meta text. */
+    trailing?: ReactNode;
+    /** When provided, the tile becomes an interactive button. */
+    onClick?: () => void;
+    /** When true, the tile is dimmed and non-interactive. */
+    disabled?: boolean;
+    /** When true, the tile is highlighted as the active row. */
+    selected?: boolean;
+    /** Extra class names merged onto the root. */
+    className?: string;
+}
+
 export declare type LocalStorageOptions<T> = {
     serialize?: (value: T) => string;
     deserialize?: (raw: string) => T;
@@ -3047,8 +3464,36 @@ export declare interface ModalProps {
     fullscreenOnMobile?: boolean;
 }
 
+/** Imperative API returned by {@link useModals}. */
+export declare interface ModalsApi {
+    /** Push a content modal. Returns its stack id. */
+    open: (options: OpenModalOptions) => string;
+    /** Push a confirmation dialog. Returns its stack id. */
+    confirm: (options: ConfirmModalOptions) => string;
+    /** Remove the modal with the given id. */
+    close: (id: string) => void;
+    /** Remove every modal from the stack. */
+    closeAll: () => void;
+}
+
 export declare type ModalSize = "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
 
+/**
+ * Provides imperative modal control via {@link useModals} and renders the open
+ * modal stack. Mount once near the app root.
+ *
+ * @example
+ * <ModalsProvider>
+ *     <App />
+ * </ModalsProvider>
+ */
+export declare function ModalsProvider({ children }: ModalsProviderProps): JSX.Element;
+
+/** Props for {@link ModalsProvider}. */
+export declare interface ModalsProviderProps {
+    children: ReactNode;
+}
+
 /**
  * Render a monetary amount given in cents as a localized currency string
  * inside a `<span>`.
@@ -3087,6 +3532,41 @@ export declare interface MoneyProps extends HTMLAttributes<HTMLSpanElement> {
     locale?: string;
 }
 
+/**
+ * MultiSelect — a filterable dropdown that selects many options, shown as
+ * removable chips inside the field. Selecting toggles a value; Backspace on an
+ * empty query removes the last chip.
+ *
+ * Keyboard: ArrowUp/ArrowDown navigate, Enter toggles the active option, Esc
+ * closes, Backspace (empty input) pops the last chip.
+ */
+export declare function MultiSelect({ options, value, onChange, label, placeholder, helperText, error, disabled, maxItems, filter, emptyMessage, className, }: MultiSelectProps): JSX.Element;
+
+export declare interface MultiSelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+
+export declare interface MultiSelectProps {
+    options: MultiSelectOption[];
+    /** Currently selected values. */
+    value: string[];
+    onChange: (value: string[]) => void;
+    label?: string;
+    placeholder?: string;
+    helperText?: string;
+    error?: string;
+    disabled?: boolean;
+    /** Cap the number of selectable items. */
+    maxItems?: number;
+    /** Custom filter — return true to keep the option. Default: case-insensitive substring on label. */
+    filter?: (option: MultiSelectOption, query: string) => boolean;
+    /** Message shown when no option matches. */
+    emptyMessage?: string;
+    className?: string;
+}
+
 /**
  * Top app bar. Three-slot layout (logo / nav / actions) that collapses
  * gracefully on mobile (nav slot wraps below).
@@ -3161,8 +3641,114 @@ export declare interface NavigationMenuProps extends HTMLAttributes<HTMLElement>
     items: NavigationMenuItem[];
 }
 
+/**
+ * Vertical, compact navigation column for desktop and tablet layouts. Each item
+ * stacks an icon over its label, with the active item flagged via
+ * `aria-current="page"`. Use `labelVisibility="selected"` to show only the
+ * active item's label, or `"none"` for an icon-only rail.
+ *
+ * @example
+ * <NavigationRail
+ *     header={<FloatingActionButton icon={<Plus />} position="none" />}
+ *     items={[
+ *         { key: "home", label: "Início", icon: <Home /> },
+ *         { key: "inbox", label: "Caixa", icon: <Inbox />, badge: 3 },
+ *     ]}
+ *     value={tab}
+ *     onChange={setTab}
+ * />
+ */
+export declare function NavigationRail({ items, value, onChange, header, footer, labelVisibility, className, ...props }: NavigationRailProps): JSX.Element;
+
+export declare interface NavigationRailItem {
+    /** 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 over the icon. */
+    badge?: ReactNode;
+    /** When true, the item is not selectable. */
+    disabled?: boolean;
+}
+
+declare type NavigationRailLabelVisibility = "all" | "selected" | "none";
+
+export declare interface NavigationRailProps extends Omit<HTMLAttributes<HTMLElement>, "onChange"> {
+    items: NavigationRailItem[];
+    /** Selected key. */
+    value: string;
+    /** Called with the new selected key on click. */
+    onChange: (key: string) => void;
+    /** Top slot — e.g. a FAB or logo. */
+    header?: ReactNode;
+    /** Bottom slot — pushed to the bottom of the rail. */
+    footer?: ReactNode;
+    /** Which item labels to show. Default `"all"`. */
+    labelVisibility?: NavigationRailLabelVisibility;
+    /** Extra class names merged onto the root. */
+    className?: string;
+}
+
 export { NavLink }
 
+/**
+ * Module-level singleton progress controller. Drive it imperatively from
+ * anywhere (router transitions, fetch interceptors) and render the visual bar
+ * with {@link NProgressBar}.
+ *
+ * @example
+ * nprogress.start();
+ * await loadData();
+ * nprogress.done();
+ */
+export declare const nprogress: NProgressController;
+
+/**
+ * Fixed top loading bar bound to the {@link nprogress} singleton. Mount once
+ * near the app root; it renders nothing while inactive.
+ *
+ * @example
+ * <NProgressBar />
+ */
+export declare function NProgressBar({ color, height, className }: NProgressBarProps): JSX.Element | null;
+
+/** Props for {@link NProgressBar}. */
+export declare interface NProgressBarProps {
+    /** Bar color. Defaults to `var(--tempest-primary)`. */
+    color?: string;
+    /** Bar height in pixels. Default `3`. */
+    height?: number;
+    /** Extra class applied to the bar element. */
+    className?: string;
+}
+
+/** Imperative top-loading-bar controller. */
+export declare interface NProgressController {
+    /** Show the bar and start trickling toward ~0.9. */
+    start: () => void;
+    /** Complete to `1`, then hide the bar shortly after. */
+    done: () => void;
+    /** Set the progress explicitly. Values are clamped to `0..1`. */
+    set: (n: number) => void;
+    /** Increment progress by `amount` (default a small trickle step). */
+    inc: (amount?: number) => void;
+    /** Subscribe to state changes. Returns an unsubscribe function. */
+    subscribe: (listener: NProgressListener) => () => void;
+}
+
+/** Listener invoked whenever the progress state changes. */
+export declare type NProgressListener = (state: NProgressState) => void;
+
+/** Snapshot of the progress controller state delivered to subscribers. */
+export declare interface NProgressState {
+    /** Current progress, `0` (empty) to `1` (complete). */
+    value: number;
+    /** Whether the bar should be visible. */
+    active: boolean;
+}
+
 export declare interface OAuthCredential {
     /** Provider-issued ID token (JWT). */
     idToken: string;
@@ -3279,6 +3865,33 @@ export declare function omit<T extends object, K extends keyof T>(obj: T, keys:
  */
 export declare function once<A extends unknown[], R>(fn: (...args: A) => R): (...args: A) => R;
 
+/**
+ * Build the cache key for a single-record query.
+ *
+ * @param resource - The resource name.
+ * @param id - The record id.
+ * @returns A stable TanStack Query key.
+ */
+export declare function oneQueryKey(resource: string, id: string | number | null | undefined): unknown[];
+
+/** Options accepted by {@link ModalsApi.open}. */
+export declare interface OpenModalOptions {
+    /** Header title. */
+    title?: ReactNode;
+    /** Modal body content. */
+    children: ReactNode;
+    /** Dialog size. Default `md`. */
+    size?: ModalSize;
+    /** Allow closing by clicking the backdrop. Default `true`. */
+    closeOnBackdrop?: boolean;
+    /** Allow closing with the Esc key. Default `true`. */
+    closeOnEsc?: boolean;
+    /** Hide the header close button. */
+    hideCloseButton?: boolean;
+    /** Called after the modal is removed from the stack. */
+    onClose?: () => void;
+}
+
 export { Outlet }
 
 /**
@@ -3331,6 +3944,9 @@ export declare interface PaginationProps {
 
 export { Params }
 
+/** Query-param values accepted by the API client for a list request. */
+declare type ParamValue = string | number | boolean | undefined | null;
+
 /**
  * Validate an unknown response payload against a zod schema.
  *
@@ -3378,6 +3994,25 @@ export declare type PasswordStrength = 0 | 1 | 2 | 3 | 4;
 
 export { Path }
 
+/**
+ * Extract a permission list from a JWT.
+ *
+ * Reads the configured claim (default `"permissions"`); if absent, falls back to
+ * the OAuth `"scopes"`/`"scope"` claims. Array claims are used as-is; string
+ * claims are split on whitespace. Returns `[]` on any decode failure or when no
+ * recognizable claim is present.
+ *
+ * @param token - The JWT to inspect (signature is **not** verified).
+ * @param options - Optional claim override.
+ * @returns The list of permission strings, or `[]` on failure.
+ */
+export declare function permissionsFromToken(token: string, options?: PermissionsFromTokenOptions): string[];
+
+export declare interface PermissionsFromTokenOptions {
+    /** JWT claim to read permissions from. Default: `"permissions"`. */
+    claim?: string;
+}
+
 export declare const PhoneInput: ForwardRefExoticComponent<Omit<InputProps, "value" | "onChange"> & {
 value: string;
 onChange: (value: string) => void;
@@ -3721,6 +4356,27 @@ export declare const REFETCH_TIME: {
     readonly SLOW: number;
 };
 
+/**
+ * RefreshIndicator — pull-to-refresh wrapper for touch devices.
+ *
+ * Wraps scrollable `children` and listens for a downward drag that starts while the
+ * container is scrolled to the top. Pulling past `threshold` and releasing triggers
+ * `onRefresh`; the SDK {@link Spinner} is shown while pulling and during the refresh.
+ */
+export declare function RefreshIndicator({ onRefresh, children, threshold, disabled, className, }: RefreshIndicatorProps): JSX.Element;
+
+export declare interface RefreshIndicatorProps {
+    /** Invoked when the user pulls past `threshold` and releases. May be async. */
+    onRefresh: () => void | Promise<void>;
+    /** Scrollable content to wrap. */
+    children: ReactNode;
+    /** Pixels the user must pull past to trigger a refresh. Defaults to `80`. */
+    threshold?: number;
+    /** When true, pull-to-refresh is inert. */
+    disabled?: boolean;
+    className?: string;
+}
+
 /**
  * Register a service worker with consistent update-detection wiring.
  *
@@ -3783,6 +4439,11 @@ export declare interface RelativeTimeProps extends HTMLAttributes<HTMLTimeElemen
     locale?: "pt" | "en";
 }
 
+export declare interface ReorderPayload {
+    from: number;
+    to: number;
+}
+
 export declare interface RequestOptions extends Omit<RequestInit, "body"> {
     body?: unknown;
     params?: Record<string, string | number | boolean | undefined | null>;
@@ -3878,6 +4539,15 @@ export declare interface RetryOptions {
     signal?: AbortSignal;
 }
 
+export declare interface RoleAccessControlConfig {
+    /** Permission strings granted directly, regardless of role. */
+    permissions?: string[];
+    /** Map of role name → permission strings granted by that role. */
+    roles?: Record<string, string[]>;
+    /** The active role(s). Their permissions (from `roles`) are merged in. */
+    role?: string | string[];
+}
+
 export { Route }
 
 /**
@@ -4205,6 +4875,29 @@ export declare function skipWaiting(worker: ServiceWorker): void;
  */
 export declare function sleep(ms: number): Promise<void>;
 
+/**
+ * Single-thumb slider built on a native `<input type="range">`, so it stays
+ * accessible (keyboard + screen reader) with no positioning libs. The active
+ * fill is a percentage-width bar. For a two-thumb range, use `RangeSlider`.
+ */
+export declare function Slider({ value, onChange, min, max, step, label, helperText, disabled, formatValue, className, }: SliderProps): JSX.Element;
+
+export declare interface SliderProps {
+    /** Current value. */
+    value: number;
+    /** Called with the new value on every change. */
+    onChange: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    label?: string;
+    helperText?: string;
+    disabled?: boolean;
+    /** Formatter for the value badge next to the label. Defaults to the raw number. */
+    formatValue?: (value: number) => string;
+    className?: string;
+}
+
 /**
  * Convert a string into a URL-safe slug.
  *
@@ -4553,6 +5246,26 @@ export declare interface TempestAuth<TUser, TCredentials> {
     getToken: () => string | null;
 }
 
+/**
+ * Inject a {@link DataProvider} into the React tree so the resource hooks
+ * (`useList`, `useOne`, `useCreate`, …) can resolve it via {@link useDataProvider}.
+ *
+ * @example
+ * const dataProvider = createDataProvider(apiClient);
+ * <TempestDataProvider provider={dataProvider}>
+ *     <App />
+ * </TempestDataProvider>
+ */
+export declare function TempestDataProvider({ provider, children }: TempestDataProviderProps): JSX.Element;
+
+/** Props for {@link TempestDataProvider}. */
+export declare interface TempestDataProviderProps {
+    /** The data provider to expose to descendant resource hooks. */
+    provider: DataProvider;
+    /** The subtree that consumes the provider. */
+    children: ReactNode;
+}
+
 /**
  * A single declarative route node. Mirrors React Router's nested `<Route>`
  * model but adds first-class `lazy` (code-split with retry) and `guard`
@@ -4709,6 +5422,30 @@ export declare interface TimelineProps extends HTMLAttributes<HTMLOListElement>
     connector?: boolean;
 }
 
+/**
+ * TimePicker — inline, dependency-free time picker with Material "spinner column" styling.
+ *
+ * Renders scrollable columns of selectable cells (hours, minutes, and AM/PM when
+ * `use12Hours`). Always emits a 24h `"HH:MM"` string via `onChange`, regardless of
+ * whether the 12h display is enabled.
+ */
+export declare function TimePicker({ value, onChange, minuteStep, use12Hours, label, helperText, disabled, className, }: TimePickerProps): JSX.Element;
+
+export declare interface TimePickerProps {
+    /** Selected time as a 24h `"HH:MM"` string (e.g. `"14:30"`). May be `""` for none. */
+    value: string;
+    /** Fired with the new 24h `"HH:MM"` string whenever a cell is picked. */
+    onChange: (value: string) => void;
+    /** Granularity of the minute column. Defaults to `5`. */
+    minuteStep?: number;
+    /** When true, show a 1–12 hour column plus an AM/PM column (still emits 24h). */
+    use12Hours?: boolean;
+    label?: string;
+    helperText?: string;
+    disabled?: boolean;
+    className?: string;
+}
+
 export { To }
 
 export declare interface ToastApi {
@@ -4901,6 +5638,14 @@ export declare function unmask(value: string): string;
  */
 export declare function unregisterAllServiceWorkers(): Promise<number>;
 
+/** Variables accepted by the update mutation. */
+export declare interface UpdateVariables {
+    /** The record id to update. */
+    id: string | number;
+    /** The update payload. */
+    data: unknown;
+}
+
 export declare interface UploadProgressEvent {
     /** Bytes already uploaded. */
     loaded: number;
@@ -4953,6 +5698,16 @@ export declare interface UploadWithProgressOptions {
  */
 export declare function urlBase64ToUint8Array(base64String: string): Uint8Array<ArrayBuffer>;
 
+/**
+ * Read the current {@link AccessControl} from context.
+ *
+ * Returns `null` when no {@link AccessControlProvider} is present. Callers MUST
+ * treat the absence of a provider as **"allow all"** — i.e. when this returns
+ * `null`, access checks should default to permitted. This keeps the SDK
+ * opt-in: dropping in a provider adds enforcement, removing it disables it.
+ */
+export declare function useAccessControl(): AccessControl | null;
+
 /**
  * Run an async function and track its `idle/pending/success/error` state.
  *
@@ -5024,6 +5779,36 @@ export declare interface UseBeforeInstallPromptResult {
  */
 export declare function useBreakpoint(): BreakpointHelpers;
 
+/**
+ * Resolve an access check against the {@link AccessControl} in context.
+ *
+ * Handles sync booleans, sync {@link CanResult}, and promises of either. When
+ * no provider is present, access is allowed (see `useAccessControl`). The check
+ * re-runs whenever the params change.
+ *
+ * @param params - The action/resource being checked.
+ */
+export declare function useCan(params: CanParams): UseCanResult;
+
+export declare interface UseCanResult {
+    /** Whether the action is permitted. Defaults to `true` while loading is not the concern of the caller. */
+    allowed: boolean;
+    /** `true` while an async `can` check is pending. */
+    isLoading: boolean;
+    /** Optional explanation, typically present when `allowed` is `false`. */
+    reason?: string;
+}
+
+/**
+ * Call `handler` when a `mousedown` / `touchstart` occurs outside the returned
+ * ref's element. SSR-safe — listeners are only attached in the browser.
+ *
+ * @typeParam T - element type to attach the ref to.
+ * @param handler - invoked on an outside interaction.
+ * @returns A ref to attach to the element treated as "inside".
+ */
+export declare function useClickOutside<T extends HTMLElement = HTMLElement>(handler: () => void): RefObject<T | null>;
+
 /**
  * Client-side filter helper. Performs a case-insensitive match on the listed
  * keys when no custom predicate is provided.
@@ -5056,6 +5841,32 @@ export declare interface UseClipboardResult {
     reset: () => void;
 }
 
+/**
+ * Numeric counter clamped to an optional `[min, max]` range.
+ *
+ * @param initial - initial value (default `0`), clamped to the range.
+ * @param options - optional `min` / `max` bounds.
+ * @returns Tuple `[count, { increment, decrement, set, reset }]`.
+ */
+export declare function useCounter(initial?: number, options?: UseCounterOptions): [number, CounterHandlers];
+
+export declare interface UseCounterOptions {
+    min?: number;
+    max?: number;
+}
+
+/**
+ * Create a record and invalidate the resource list cache on success.
+ *
+ * @param resource - The resource name.
+ * @param options - Extra TanStack Mutation options.
+ * @returns The mutation; `mutate(data)` creates the record.
+ */
+export declare function useCreate<T>(resource: string, options?: UseCreateOptions<T>): UseMutationResult<T, Error, unknown>;
+
+/** Options for the create mutation (mutationFn + onSuccess are provided). */
+export declare type UseCreateOptions<T> = Omit<UseMutationOptions<T, Error, unknown>, "mutationFn">;
+
 /**
  * Cursor-pagination hook over TanStack Query's `useInfiniteQuery` for the
  * Tempest `CursorPaginationSchema` envelope
@@ -5102,6 +5913,14 @@ export declare interface UseCursorQueryResult<T> {
     refetch: () => void;
 }
 
+/**
+ * Read the {@link DataProvider} from context.
+ *
+ * @returns The data provider supplied to the nearest {@link TempestDataProvider}.
+ * @throws {Error} When used outside a {@link TempestDataProvider}.
+ */
+export declare function useDataProvider(): DataProvider;
+
 /**
  * Debounce a fast-changing value. Returns the latest value once `delay` ms
  * have elapsed without further changes.
@@ -5119,6 +5938,37 @@ export declare function useDebounce<T>(value: T, delay?: number): T;
  */
 export declare function useDeepMemo<T>(value: T): T;
 
+/**
+ * Delete a record by id and invalidate the resource list cache on success.
+ *
+ * @param resource - The resource name.
+ * @param options - Extra TanStack Mutation options.
+ * @returns The mutation; `mutate(id)` deletes the record.
+ */
+export declare function useDelete<T>(resource: string, options?: UseDeleteOptions<T>): UseMutationResult<T, Error, string | number>;
+
+/** Options for the delete mutation (mutationFn + onSuccess are provided). */
+export declare type UseDeleteOptions<T> = Omit<UseMutationOptions<T, Error, string | number>, "mutationFn">;
+
+/**
+ * Manage open/closed boolean state with stable `open`/`close`/`toggle` handlers.
+ *
+ * Richer than {@link useToggle} for UI elements like modals, drawers and
+ * popovers: the handlers are referentially stable across renders.
+ *
+ * @param initial - initial opened state (default `false`).
+ * @returns Tuple `[opened, { open, close, toggle }]`.
+ */
+export declare function useDisclosure(initial?: boolean): [boolean, DisclosureHandlers];
+
+/**
+ * Set `document.title` while the component is mounted, restoring the previous
+ * title on unmount. SSR-safe — no-op when `document` is unavailable.
+ *
+ * @param title - the title to apply.
+ */
+export declare function useDocumentTitle(title: string): void;
+
 /** Subscribe to `document.visibilityState`. Returns `"visible"` during SSR. */
 export declare function useDocumentVisibility(): DocumentVisibility;
 
@@ -5179,6 +6029,15 @@ export declare interface UseEventStreamResult<T> {
     reconnect: () => void;
 }
 
+/**
+ * Swap the document favicon by updating the `<link rel="icon">` href.
+ * Creates the link element when it is missing. SSR-safe — no-op when
+ * `document` is unavailable.
+ *
+ * @param href - the favicon URL to apply.
+ */
+export declare function useFavicon(href: string): void;
+
 /**
  * Read a boolean flag and re-render when the adapter fires `onChange`.
  *
@@ -5270,6 +6129,13 @@ export declare interface UseIntersectionObserverOptions extends IntersectionObse
  */
 export declare function useInterval(fn: () => void, delay: number | null): void;
 
+/**
+ * Return `true` on the first render of the component and `false` thereafter.
+ *
+ * @returns Whether the current render is the first one.
+ */
+export declare function useIsFirstRender(): boolean;
+
 /**
  * Bind a global keyboard shortcut. Supports modifier combinations and a
  * cross-OS `mod` key (Ctrl on Windows/Linux, Cmd on macOS).
@@ -5288,6 +6154,28 @@ export declare interface UseKeyboardShortcutOptions {
     ignoreInput?: boolean;
 }
 
+/**
+ * Query a paginated list of a resource through the active {@link useDataProvider}.
+ *
+ * @param resource - The resource name.
+ * @param params - Pagination, sort and filter parameters.
+ * @param options - Extra TanStack Query options.
+ * @returns The TanStack Query result for the offset page.
+ */
+export declare function useList<T>(resource: string, params?: GetListParams, options?: UseListOptions<T>): UseQueryResult<OffsetPage<T>, Error>;
+
+/** Extra TanStack Query options for {@link useList} (key + fn are provided). */
+export declare type UseListOptions<T> = Omit<UseQueryOptions<OffsetPage<T>, Error, OffsetPage<T>>, "queryKey" | "queryFn">;
+
+/**
+ * Manage an array as state with a rich set of immutable handlers.
+ *
+ * @typeParam T - element type.
+ * @param initial - initial list (default `[]`).
+ * @returns Tuple `[list, handlers]`.
+ */
+export declare function useListState<T>(initial?: T[]): [T[], ListStateHandlers<T>];
+
 /**
  * State synced with `localStorage`. SSR-safe — initial render returns the
  * provided default; the stored value is hydrated after mount. Updates to the
@@ -5320,6 +6208,27 @@ export declare interface UseLongPressOptions {
     moveThreshold?: number;
 }
 
+/**
+ * Reactive `Map` wrapper. Mutating via `set` / `delete` / `clear` triggers a
+ * re-render and yields a fresh `map` reference each time.
+ *
+ * @typeParam K - key type.
+ * @typeParam V - value type.
+ * @param initial - initial entries.
+ * @returns `{ map, set, delete, clear, get, has, size }`.
+ */
+export declare function useMap<K, V>(initial?: Iterable<readonly [K, V]>): UseMapResult<K, V>;
+
+export declare interface UseMapResult<K, V> {
+    map: ReadonlyMap<K, V>;
+    set: (key: K, value: V) => void;
+    delete: (key: K) => void;
+    clear: () => void;
+    get: (key: K) => V | undefined;
+    has: (key: K) => boolean;
+    size: number;
+}
+
 export { useMatch }
 
 /**
@@ -5330,6 +6239,17 @@ export { useMatch }
  */
 export declare function useMediaQuery(query: string): boolean;
 
+/**
+ * Access the imperative modals API. Must be used within a {@link ModalsProvider}.
+ *
+ * @example
+ * const modals = useModals();
+ * modals.confirm({ message: "Excluir item?", danger: true, onConfirm: del });
+ *
+ * @throws Error when called outside a {@link ModalsProvider}.
+ */
+export declare function useModals(): ModalsApi;
+
 export { useNavigate }
 
 /**
@@ -5381,6 +6301,23 @@ export declare interface UseOAuthCallbackResult<T> {
     status: "pending" | "success" | "error";
 }
 
+/**
+ * Query a single record by id through the active {@link useDataProvider}.
+ *
+ * The query is disabled while `id` is `null`/`undefined`.
+ *
+ * @param resource - The resource name.
+ * @param id - The record id.
+ * @param options - Extra TanStack Query options.
+ * @returns The TanStack Query result for the record.
+ */
+export declare function useOne<T>(resource: string, id: string | number | null | undefined, options?: UseOneOptions<T>): UseQueryResult<T, Error>;
+
+/** Extra TanStack Query options for {@link useOne} (key + fn + enabled are provided). */
+export declare type UseOneOptions<T> = Omit<UseQueryOptions<T, Error, T>, "queryKey" | "queryFn" | "enabled"> & {
+    enabled?: boolean;
+};
+
 /**
  * Track the browser's `navigator.onLine` value and re-render on changes.
  * Returns `true` during SSR (assumption: server is online).
@@ -5543,6 +6480,36 @@ export declare interface UsePushSubscriptionResult {
     refresh: () => Promise<void>;
 }
 
+/**
+ * FIFO queue with an optional `limit`. When more items are added than `limit`
+ * allows, the surplus is kept in an internal overflow buffer and surfaces into
+ * `queue` as room frees up (e.g. after `cleanQueue`). Loosely mirrors Mantine's
+ * `useQueue` shape.
+ *
+ * @typeParam T - element type.
+ * @param options - `initialValues` and `limit` (default limit `Infinity`).
+ * @returns `{ queue, add, update, cleanQueue, size }`.
+ */
+export declare function useQueue<T>(options?: UseQueueOptions<T>): UseQueueResult<T>;
+
+export declare interface UseQueueOptions<T> {
+    initialValues?: T[];
+    limit?: number;
+}
+
+export declare interface UseQueueResult<T> {
+    /** Items currently held within the queue (up to `limit`). */
+    queue: T[];
+    /** Append items; overflow beyond `limit` is held back, not dropped. */
+    add: (...items: T[]) => void;
+    /** Replace the held queue via a mapper over the current held items. */
+    update: (fn: (state: T[]) => T[]) => void;
+    /** Drop all currently held (visible) items, keeping any overflow. */
+    cleanQueue: () => void;
+    /** Number of visible items in the queue. */
+    size: number;
+}
+
 /**
  * Track size changes of a DOM element via `ResizeObserver`.
  * Returns `null` until the first measurement.
@@ -5559,6 +6526,26 @@ export declare function useScrollLock(active: boolean): void;
 
 export { useSearchParams }
 
+/**
+ * Reactive `Set` wrapper. Mutating via `add` / `delete` / `clear` / `toggle`
+ * triggers a re-render and yields a fresh `set` reference each time.
+ *
+ * @typeParam T - element type.
+ * @param initial - initial values.
+ * @returns `{ set, add, delete, clear, has, toggle, size }`.
+ */
+export declare function useSet<T>(initial?: Iterable<T>): UseSetResult<T>;
+
+export declare interface UseSetResult<T> {
+    set: ReadonlySet<T>;
+    add: (value: T) => void;
+    delete: (value: T) => void;
+    clear: () => void;
+    has: (value: T) => boolean;
+    toggle: (value: T) => void;
+    size: number;
+}
+
 /**
  * Returns a stable function reference that always invokes the latest
  * `callback` argument. Use to break dependency cycles in effects without
@@ -5616,6 +6603,18 @@ export declare function useToggle(initial?: boolean): [boolean, ToggleHelpers];
  */
 export declare function useTranslate(): I18nContextValue["t"];
 
+/**
+ * Update a record and invalidate both the list and the single-record caches.
+ *
+ * @param resource - The resource name.
+ * @param options - Extra TanStack Mutation options.
+ * @returns The mutation; `mutate({ id, data })` updates the record.
+ */
+export declare function useUpdate<T>(resource: string, options?: UseUpdateOptions<T>): UseMutationResult<T, Error, UpdateVariables>;
+
+/** Options for the update mutation (mutationFn + onSuccess are provided). */
+export declare type UseUpdateOptions<T> = Omit<UseMutationOptions<T, Error, UpdateVariables>, "mutationFn">;
+
 /**
  * React hook for the public ViaCEP service (`viacep.com.br`). No backend
  * required. Returns address fields when the CEP exists, or sets `error` for
@@ -6141,6 +7140,8 @@ export declare type WebSocketStatus = "idle" | "connecting" | "open" | "closing"
 
 export declare type WeekStart = 0 | 1;
 
+declare type WeekStart_2 = 0 | 1;
+
 export declare interface WindowSize {
     width: number;
     height: number;