/** A page item rendered in the pagination bar. */
export type PaginationPageItem = {
    type: 'page';
    page: number;
} | {
    type: 'ellipsis';
    key: string;
};
export interface UsePaginationProps {
    /** Total number of items in the data set. */
    totalItems: number;
    /** Number of items per page. @default 10 */
    pageSize?: number;
    /** Initial page (1-indexed). @default 1 */
    initialPage?: number;
    /**
     * Controlled current page (1-indexed).
     * When provided, page state is managed externally via `onPageChange`.
     */
    page?: number;
    /** Called whenever the page changes. */
    onPageChange?: (page: number) => void;
    /**
     * Number of page buttons to show on each side of the current page.
     * @default 1
     */
    siblingCount?: number;
}
export interface UsePaginationReturn {
    /** The currently active page (1-indexed). */
    currentPage: number;
    /** Total number of pages. */
    totalPages: number;
    /** Index of the first item on the current page (0-indexed, useful for slicing). */
    startIndex: number;
    /** Index of the last item on the current page (exclusive, useful for slicing). */
    endIndex: number;
    /** Whether there is a previous page available. */
    canGoPrev: boolean;
    /** Whether there is a next page available. */
    canGoNext: boolean;
    /** Whether the current page is the first page. */
    isFirstPage: boolean;
    /** Whether the current page is the last page. */
    isLastPage: boolean;
    /**
     * Ordered list of items to render in the pagination bar.
     * Each item is either a `{ type: 'page', page: number }` or
     * `{ type: 'ellipsis', key: string }`.
     */
    items: PaginationPageItem[];
    /** Navigate to a specific page (1-indexed, clamped to valid range). */
    goTo: (page: number) => void;
    /** Navigate to the next page (no-op if already on the last page). */
    next: () => void;
    /** Navigate to the previous page (no-op if already on the first page). */
    prev: () => void;
    /** Navigate to the first page. */
    first: () => void;
    /** Navigate to the last page. */
    last: () => void;
}
/**
 * Headless hook for pagination logic.
 *
 * @description
 * Computes the current page, total pages, slice indices, and the ordered list
 * of page items (numbers + ellipses) to render. Supports both controlled and
 * uncontrolled modes. Pair with any custom pagination UI or with the
 * `<Pagination>` visual components.
 *
 * @example
 * ```tsx
 * const { currentPage, totalPages, items, next, prev, goTo, canGoPrev, canGoNext } =
 *   usePagination({ totalItems: 200, pageSize: 20 });
 * ```
 */
export declare function usePagination({ totalItems, pageSize, initialPage, page: controlledPage, onPageChange, siblingCount, }: UsePaginationProps): UsePaginationReturn;