Sorting & Pagination Managers
Relevant source files
The following files were used as context for generating this wiki page:
Sorting and Pagination Managers are foundational state management components within the @better-tables/core package. They provide a headless, framework-agnostic way to manage the complex states of data tables, including multi-column sorting logic and page-based navigation. These managers are designed to work in tandem with the Table State Manager to provide a unified source of truth for table interactions.
Sources: packages/core/README.md:1-12, CLAUDE.md:10-15
Sorting Manager
The SortingManager handles the lifecycle of sorting states, supporting both single-column and multi-column sorting configurations. It validates column definitions to ensure only columns marked as sortable can be manipulated.
Core Logic and Toggling
The manager implements a state machine for sorting directions. By default, toggling a column follows a cycle: None → ASC → DESC → ASC. If the resetOnClick configuration is enabled, the cycle changes to include a removal step: None → ASC → DESC → None.
The diagram shows the state transition logic for column sorting directions based on the resetOnClick configuration.
Sources: packages/core/tests/managers/sorting-manager.test.ts:93-113
Multi-Column Sorting
When multiSort is enabled, the manager maintains an array of sorting objects. It enforces a maxSortColumns limit; if this limit is exceeded by adding a new sort, the manager automatically removes the oldest sort entry to accommodate the new one.
| Configuration Option | Type | Default | Description |
|---|---|---|---|
multiSort | boolean | false | Enables sorting by multiple columns simultaneously. |
maxSortColumns | number | 1 | The maximum number of columns that can be sorted at once. |
resetOnClick | boolean | false | If true, clicking a DESC sorted column returns it to an unsorted state. |
Sources: packages/core/tests/managers/sorting-manager.test.ts:39-55, packages/core/tests/managers/sorting-manager.test.ts:115-150
Key Methods
toggleSort(columnId): Automatically switches the direction of the specified column.addSort(columnId, direction): Explicitly adds a sorting rule.removeSort(columnId): Removes sorting for a specific column.clearSorting(): Resets the entire sorting state to an empty array.getSorting(): Returns the currentSortingState[].
Sources: packages/core/tests/managers/sorting-manager.test.ts:65-91, packages/core/README.md:126-140
Pagination Manager
The PaginationManager coordinates the current page index and page size. It provides safety checks to ensure users do not navigate to invalid page ranges.
Pagination Calculations
The manager tracks the page (1-indexed) and limit (page size). It provides helper methods to navigate through data chunks.
The flow represents how pagination state is updated via external UI triggers and subsequently notifies listeners.
Sources: packages/core/README.md:144-162
Configuration and State
Pagination is typically initialized with a default page size and a list of available size options.
| Parameter | Type | Description |
|---|---|---|
defaultPageSize | number | The initial number of rows per page (e.g., 20). |
pageSizeOptions | number[] | Array of allowed page sizes (e.g., [10, 20, 50, 100]). |
Sources: packages/core/README.md:144-150
Subscription and Notification System
Both managers implement a subscription pattern (Subscribable). This allows UI hooks or other managers to listen for state changes and trigger side effects, such as re-fetching data from an adapter.
Event Types
The SortingManager emits specific events based on the action performed:
sorts_replaced: Emitted when the entire sorting array is overwritten.sort_updated: Emitted when a single column's direction changes.sort_removed: Emitted when a specific column is no longer sorted.sorts_cleared: Emitted when all sorting is removed.
The sequence diagram illustrates the reactive flow from a user interaction to state notification for subscribers.
Sources: packages/core/tests/managers/sorting-manager.test.ts:220-258
Table State Manager Coordination
While individual managers handle specific logic, the TableStateManager serves as a unified coordinator. It encapsulates instances of FilterManager, SortingManager, and PaginationManager.
The class diagram shows the composition relationship where TableStateManager acts as the aggregate root for specific sub-managers.
Sources: packages/core/README.md:166-192, packages/core/README.md:368-375
Implementation Summary
Sorting and Pagination managers ensure that table logic remains consistent regardless of the rendering layer. By using these managers, the system can:
- Enforce Validation: Prevent sorting on non-sortable columns like those containing custom actions.
- Ensure Stability: Use stable default identities (e.g.,
EMPTY_FILTERS) to prevent unnecessary re-renders in React hooks. - Support Complex Logic: Handle multi-column priorities and circular toggling without leaking logic into UI components.
Sources: packages/core/tests/managers/sorting-manager.test.ts:192-205, plans/034-usetabledata-loop-and-date-render.md:58-75