/** An item in the pagination range — either a page number or an ellipsis marker */
export type PaginationRangeItem = number | 'dots';
/** Options for usePagination */
export interface UsePaginationOptions {
    /** Total number of pages (1-indexed max). Values below 1 are clamped to 1. */
    total: number;
    /** Initial active page when uncontrolled. Default: `1` */
    initialPage?: number;
    /** Controlled active page. When provided, the hook operates in controlled mode. */
    page?: number;
    /** Number of sibling pages shown on each side of the active page. Default: `1` */
    siblings?: number;
    /** Number of pages shown at the start and end of the range. Default: `1` */
    boundaries?: number;
    /** Callback fired when the active page changes */
    onChange?: (page: number) => void;
}
/** Return value of usePagination */
export interface UsePaginationReturn {
    /** Current active page (1-indexed, always within `[1, total]`) */
    activePage: number;
    /** Visible range with ellipsis markers (e.g. `[1, 'dots', 9, 10, 11, 'dots', 20]`) */
    range: PaginationRangeItem[];
    /** Set the active page (clamped to `[1, total]`) */
    setPage: (page: number) => void;
    /** Advance to the next page (no-op if on last page) */
    next: () => void;
    /** Go to the previous page (no-op if on first page) */
    previous: () => void;
    /** Jump to the first page */
    first: () => void;
    /** Jump to the last page */
    last: () => void;
}
/**
 * Calculates the visible pagination range and provides navigation controls.
 * Works in both controlled and uncontrolled modes.
 *
 * The range algorithm shows the active page with `siblings` neighbours on
 * each side, `boundaries` pages pinned to the start and end, and `'dots'`
 * ellipsis markers filling the gaps.
 *
 * @param {UsePaginationOptions} options - Pagination configuration
 * @returns {UsePaginationReturn} Active page, range, and navigation helpers
 *
 * @example
 * const { activePage, range, setPage } = usePagination({
 *   total: 20,
 *   siblings: 1,
 *   boundaries: 1,
 * });
 * // activePage = 1  → [1, 2, 3, 4, 5, 'dots', 20]
 * // activePage = 10 → [1, 'dots', 9, 10, 11, 'dots', 20]
 * // activePage = 20 → [1, 'dots', 16, 17, 18, 19, 20]
 */
export declare function usePagination(options: UsePaginationOptions): UsePaginationReturn;
/** The 1-indexed item range covered by a page, plus the grand total. */
export interface PaginationSummaryRange {
    /** 1-indexed index of the first item on the page (`0` when `total === 0`). */
    from: number;
    /** 1-indexed index of the last item on the page, never exceeding `total`. */
    to: number;
    /** Total number of items across all pages (echoed back for convenience). */
    total: number;
}
/**
 * Pure helper that computes the "X–Y of N" item range for a given page.
 *
 * Both {@link DataPagination} and downstream consumers can call this to render
 * identical summary text. The math is the canonical
 * `from = (page - 1) * pageSize + 1` / `to = min(page * pageSize, total)`,
 * with `total === 0` collapsing to `{ from: 0, to: 0, total: 0 }`.
 *
 * Inputs are defensively normalised: `page`/`pageSize` are floored to at least
 * `1`, and `total` is floored to at least `0`. The returned `to` is additionally
 * clamped so it never exceeds `total`.
 *
 * @param page - The 1-indexed active page.
 * @param pageSize - Items per page.
 * @param total - Total number of items across all pages.
 * @returns {PaginationSummaryRange} The `{ from, to, total }` item range.
 *
 * @example
 * paginationSummary(1, 20, 248); // → { from: 1,   to: 20,  total: 248 }
 * paginationSummary(13, 20, 248); // → { from: 241, to: 248, total: 248 }
 * paginationSummary(1, 20, 0); // → { from: 0,   to: 0,   total: 0 }
 */
export declare function paginationSummary(page: number, pageSize: number, total: number): PaginationSummaryRange;