/**
 * Compute pagination state for a list view.
 *
 * Clamps `page` into [1, totalPages] so an out-of-range query string
 * (?page=999) lands on the last page instead of an empty offset.
 */
export function paginate(
    rawPage: number | undefined,
    totalCount: number,
    perPage: number,
): { page: number; totalPages: number; offset: number } {
    const totalPages = Math.max(1, Math.ceil(totalCount / perPage));
    const page = Math.min(Math.max(1, rawPage ?? 1), totalPages);
    return { page, totalPages, offset: (page - 1) * perPage };
}