Feature Request: Comprehensive Pagination Architecture for DataTable Component

[christoph2806]

@etherisc/ui-kit Feature Request: Comprehensive Pagination Architecture

Date: December 2024
Requestor: Web Application Team
Priority: High
Type: Enhancement

Problem Statement

The current DataTable component lacks comprehensive pagination support for enterprise applications. While it provides basic pageSize support, it's missing critical TanStack Table props needed for server-side pagination and enterprise-grade navigation features.

Current Gaps in DataTable Interface

❌ Missing TanStack Table Props:

• manualPagination?: boolean - Critical for server-side pagination
• pageCount?: number - Critical for total page information
• rowCount?: number - Critical for total row information
• onPaginationChange?: (state: PaginationState) => void - Critical for state management
• state?: { pagination: PaginationState } - For controlled pagination state
• initialState?: { pagination: Partial<PaginationState> } - For initial state

✅ Currently Available:

• pageSize?: number - Basic client-side pagination
• enableSorting?: boolean - TanStack Table sorting
• data and columns - Standard TanStack Table props

Current Workarounds Required

Teams are implementing server-side pagination outside DataTable with custom logic:

// Current workaround - custom pagination hook + separate UI
const { organizations, totalPages, currentPage, goToPage } = useOrganizations();

// Separate pagination UI components
<Pagination>
  <PaginationContent>
    <PaginationPrevious />
    <PaginationNext />
  </PaginationContent>
</Pagination>

This leads to:

• Inconsistent UX across different tables
• Duplicated pagination logic in every component
• Missing enterprise features (fast navigation, jump-to-page)
• No zero-config defaults for common use cases

Proposed Solution

1. Enhanced DataTable Component (TanStack Compatible)

interface DataTableProps<TData extends object> {
  // Existing props (maintained)
  data: TData[];
  columns: ColumnDef<TData>[];
  pageSize?: number;
  enableSorting?: boolean;
  enableResizing?: boolean;
  
  // Add missing TanStack Table props
  manualPagination?: boolean; // TanStack's standard prop
  pageCount?: number; // TanStack's standard prop  
  rowCount?: number; // TanStack's standard prop
  onPaginationChange?: (pagination: PaginationState) => void; // TanStack pattern
  
  // Enhanced pagination UI configuration
  pagination?: {
    pageSize?: number;
    showSizeSelector?: boolean;
    showPageInfo?: boolean;
    showNavigation?: boolean;
    pageSizeOptions?: number[]; // TanStack naming
    enableFastNavigation?: boolean;
    enableJumpToPage?: boolean;
  } | false; // false = disable pagination completely
  
  // Additional UI state
  loading?: boolean;
}

// TanStack Table compatible pagination state
interface PaginationState {
  pageIndex: number; // TanStack uses pageIndex (0-based)
  pageSize: number;
}

2. Usage Examples

No Pagination (Small Datasets)

<DataTable
  data={settings} // ≤15 items
  columns={columns}
  pagination={false} // Clean: no pagination
/>

Simple Server-Side Pagination

const paginationHook = usePagination({
  fetcher: userService.getUsers
});

<DataTable
  data={paginationHook.data}
  columns={columns}
  pagination={{}} // Default pagination UI
  manualPagination={true} // TanStack prop
  pageCount={paginationHook.pageCount} // TanStack prop
  rowCount={paginationHook.rowCount} // TanStack prop
  onPaginationChange={(state) => {
    paginationHook.setPageIndex(state.pageIndex);
    paginationHook.setPageSize(state.pageSize);
  }} // TanStack pattern
  loading={paginationHook.loading}
/>

Enterprise Pagination with Rich Controls

<DataTable
  data={data}
  columns={columns}
  pagination={{
    showSizeSelector: true,
    showPageInfo: true,
    enableFastNavigation: true, // ±5 pages
    enableJumpToPage: true, // "Go to page" input
    pageSizeOptions: [10, 25, 50, 100, 200]
  }}
  // ... TanStack props
/>

3. Rich Navigation Features

Pagination Controls Layout:

[First] [<<] [<] [1] [2] [3] ... [8] [9] [10] [>] [>>] [Last] | Rows: [25 ▼] | Go to: [___] [Go] | Showing 1-25 of 250

Navigation Functions:

1. Basic: Previous, Next, Direct page numbers
2. Fast Navigation: Fast backward (<<), Fast forward (>>) - ±5 pages
3. Boundary Navigation: First page, Last page
4. Jump Navigation: "Go to page" input field
5. Size Control: Rows per page selector
6. Info Display: "Showing X-Y of Z items"

Keyboard Shortcuts:

• ← / →: Previous/Next page
• Home / End: First/Last page
• PageUp / PageDown: Fast backward/forward
• Ctrl+G: Focus "Go to page" input

TanStack Table Integration

This architecture is designed to be fully compatible with TanStack Table v8 patterns:

Key Alignments

1. State Management: Uses TanStack's PaginationState shape with pageIndex (0-based) and pageSize
2. Method Names: Adopts TanStack's naming conventions:
   • setPageIndex(), setPageSize() instead of custom names
   • getCanNextPage(), getCanPreviousPage() for state checks
   • firstPage(), lastPage(), nextPage(), previousPage() for navigation
3. Table Options: Uses TanStack's standard props:
   • manualPagination: true for server-side pagination
   • pageCount and rowCount for total information
   • onPaginationChange callback pattern
4. Zero-Based Indexing: All page references use 0-based indexing like TanStack

Smart Pagination Defaults

// Auto-chooses best pagination strategy
<DataTable
  data={data}
  columns={columns}
  // Smart defaults:
  // - No pagination: data.length ≤ 15
  // - Server pagination: data.length > 15  
  pagination={data.length <= 15 ? false : {}}
/>

Recommended Thresholds

• No Pagination: ≤ 15 items (settings, small lookups, reference data) → pagination={false}
• Server Pagination: > 15 items (all other datasets for consistency) → pagination={{ /* config */ }}

Benefits

1. Zero Configuration: Works out of the box with sensible defaults
2. TanStack Compatible: Full alignment with established patterns
3. Rich UX: Enterprise-grade navigation controls when needed
4. Consistent: Same API across all tables
5. Scalable: Handles 5 items or 5 million items optimally
6. Type Safe: Full TypeScript support
7. Accessible: Keyboard navigation and screen reader support
8. UX Optimized: No pagination clutter for small datasets

Migration Path

Phase 1: Core Infrastructure

• Add missing TanStack Table props to DataTable interface
• Enhance DataTable with pagination configuration
• Maintain backward compatibility

Phase 2: Rich Navigation

• Add fast navigation features
• Implement jump-to-page functionality
• Add keyboard shortcuts

Phase 3: Advanced Features

• Search integration
• Filter integration
• Sort integration
• URL state synchronization

Implementation Notes

• Full TanStack Compatibility: All APIs align with TanStack Table v8 patterns
• Graceful Enhancement: Adds enterprise features without breaking TanStack conventions
• Backward Compatibility: Must maintain current DataTable API during transition
• Progressive Enhancement: Can be implemented incrementally alongside existing pagination
• Design System Alignment: Should follow ui-kit's design system and accessibility standards

Success Criteria

• Zero-config pagination works for simple use cases
• Server-side pagination supports all rich navigation features
• Performance remains excellent with large datasets
• API is intuitive and well-documented
• Accessibility score remains high (WCAG 2.1 AA)
• TypeScript support is comprehensive
• Full TanStack Table compatibility maintained

Context

This request comes from the BF2 comprehensive UI fixes initiative where duplicate pagination elements and non-working standard pagination were discovered. Teams are currently implementing custom workarounds for server-side pagination that could be standardized and enhanced through this feature.

---

Priority: High - This blocks consistent enterprise-grade table implementations across applications