Refactor Pagination component to improve clarity and maintainability

[OpenStaxClaude]

Summary

This PR refactors the Pagination component to improve code clarity, testability, and maintainability by applying SOLID principles, specifically the Single Responsibility Principle.

Problem

The original Pagination.tsx component had several issues:

• Single Responsibility violation: The component handled both complex pagination logic calculation AND rendering
• Complex algorithm: The range calculation logic (lines 64-107) with nested conditionals was hard to understand and test
• Poor testability: The pagination algorithm was buried inside the component, making it difficult to unit test independently
• Lack of documentation: The complex logic lacked explanatory comments

Solution

1. Created Pagination.utils.ts - Pure Pagination Logic

Extracted all pagination calculation logic into pure, well-documented functions:

// Main function that orchestrates the pagination logic
export function calculatePaginationRanges(config: PaginationConfig): PaginationRanges

// Helper functions with clear responsibilities:
- calculateInitialRanges(): Calculates start, middle, and end ranges
- countTotalEntries(): Counts how many page entries will be displayed  
- adjustRangesToMeetMinimum(): Expands ranges to maintain consistent UI size
- range(): Utility to create number arrays

Each function is:

• Pure: No side effects, same input always produces same output
• Testable: Can be unit tested in isolation
• Documented: Extensive JSDoc comments explain the algorithm step-by-step

2. Created Pagination.hooks.ts - React Integration

export function usePaginationRanges(config: PaginationConfig): PaginationRanges

• Wraps the pure calculation function in a React hook
• Memoizes results to prevent unnecessary recalculations
• Only recomputes when relevant props change

3. Refactored Pagination.tsx - Rendering Concerns

Simplified the main component to focus solely on rendering:

• Extracted sub-components:

  • Ellipsis: Renders the "..." element
  • PageRangeComponent: Renders a range of page links
  • PaginationInfo: Renders the "1-20 of 150" information

• Simplified main component: Now delegates logic to the hook and focuses on layout

• Added comprehensive comments: Explains component behavior and usage

• Maintained API: No breaking changes - component props remain identical

Benefits

✅ Improved Testability: Pure functions can be easily unit tested
✅ Better Readability: Complex algorithm is now documented and broken into logical steps
✅ Easier Maintenance: Each file has a single, clear responsibility
✅ Reusability: Pagination logic can now be used in other contexts if needed
✅ Performance: Memoization prevents unnecessary recalculations
✅ No Breaking Changes: Component API remains identical

Code Comparison

Before (mixed concerns):

// 193 lines with logic and rendering mixed together
export const Pagination = styled((props) => {
  // ... 44 lines of complex range calculation logic ...
  const middleRange = [/*...*/];
  if (numberOfEntries < minEntries) {
    // ... 23 lines of adjustment logic ...
  }
  return (/* rendering */)
});

After (separated concerns):

// Pagination.utils.ts: Pure logic (252 lines with extensive documentation)
export function calculatePaginationRanges(config) { /* ... */ }

// Pagination.hooks.ts: React integration (36 lines)
export function usePaginationRanges(config) {
  return useMemo(() => calculatePaginationRanges(config), [/*...*/]);
}

// Pagination.tsx: Clean rendering (227 lines with comments)
export const Pagination = styled((props) => {
  const ranges = usePaginationRanges({/*...*/});
  return (/* clear, documented rendering */);
});

Testing

The refactoring maintains exact functionality. The component behaves identically to before:

• Same props API
• Same rendering output
• Same visual appearance
• Existing tests should pass without modification

The new pure functions in Pagination.utils.ts are now easily unit testable if needed.

Related

CORE-1449

Part of an experiment to improve code clarity in the ui-components repository by applying SOLID principles to complex components.

---

🤖 Generated with Claude Code

[RoyEJohnson]

This file was broken into three modules which are in the (new) Pagination directory. This file became index.tsx, with pieces extracted to be utils.ts and hooks.ts

[RoyEJohnson]

There were a couple of branches of code that were not getting test coverage. They do now.