@epilot/volt-ui 1.1.18 → 1.1.21

package/dist/lib/pagination.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Pagination utility functions for calculating pagination metadata.
+ */
+export type PaginationParams = {
+    page: number;
+    pageSize: number;
+    totalItems: number;
+};
+export type PaginationMeta = {
+    /** Total number of pages */
+    totalPages: number;
+    /** First item index on current page (1-indexed for display) */
+    start: number;
+    /** Last item index on current page (1-indexed for display) */
+    end: number;
+    /** Whether there is a next page */
+    hasNextPage: boolean;
+    /** Whether there is a previous page */
+    hasPreviousPage: boolean;
+    /** Whether current page is the first page */
+    isFirstPage: boolean;
+    /** Whether current page is the last page */
+    isLastPage: boolean;
+};
+/**
+ * Calculate pagination metadata from current state.
+ *
+ * @example
+ * ```tsx
+ * const meta = calculatePagination({ page: 1, pageSize: 10, totalItems: 25 })
+ * // Returns: { totalPages: 3, start: 1, end: 10, hasNextPage: true, ... }
+ * ```
+ */
+export declare function calculatePagination(params: PaginationParams): PaginationMeta;
+/**
+ * Clamp a page number to valid bounds.
+ *
+ * @example
+ * ```tsx
+ * clampPage(5, 3) // Returns 3 (clamped to max)
+ * clampPage(0, 3) // Returns 1 (clamped to min)
+ * ```
+ */
+export declare function clampPage(page: number, totalPages: number): number;
+/** Represents a page number or an ellipsis marker in pagination */
+export type PageItem = {
+    type: "page";
+    page: number;
+} | {
+    type: "ellipsis";
+    targetPage: number;
+};
+/**
+ * Generate page numbers with ellipsis for pagination UI.
+ *
+ * Pattern rules:
+ * - Fixed slot count: always shows TOTAL_SLOTS items (default: 7)
+ * - Right ellipsis when not near end: [pages..., ..., lastPage]
+ * - Near end: expanded window with no ellipsis
+ * - Ellipsis is clickable and jumps to midpoint
+ *
+ * @example
+ * ```tsx
+ * getPageNumbers(1, 10)   // [1, 2, 3, 4, 5, ellipsis→7, 10] (7 items)
+ * getPageNumbers(5, 10)   // [3, 4, 5, 6, 7, ellipsis→8, 10] (7 items)
+ * getPageNumbers(7, 10)   // [4, 5, 6, 7, 8, 9, 10] (7 items - expanded)
+ * getPageNumbers(10, 10)  // [4, 5, 6, 7, 8, 9, 10] (7 items - expanded)
+ * getPageNumbers(2, 5)    // [1, 2, 3, 4, 5] (5 items - small table)
+ * ```
+ */
+export declare function getPageNumbers(currentPage: number, totalPages: number, siblingCount?: number): PageItem[];