@tanstack/table-core 9.0.0-alpha.10 → 9.0.0-alpha.12

package/src/features/row-pagination/rowPaginationFeature.ts

@@ -0,0 +1,121 @@
+import { assignTableAPIs, makeStateUpdater } from '../../utils'
+import {
+  getDefaultPaginationState,
+  table_autoResetPageIndex,
+  table_firstPage,
+  table_getCanNextPage,
+  table_getCanPreviousPage,
+  table_getPageCount,
+  table_getPageOptions,
+  table_getRowCount,
+  table_lastPage,
+  table_nextPage,
+  table_previousPage,
+  table_resetPageIndex,
+  table_resetPageSize,
+  table_resetPagination,
+  table_setPageIndex,
+  table_setPageSize,
+  table_setPagination,
+} from './rowPaginationFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   CachedRowModel_Paginated,
+//   CreateRowModel_Paginated,
+//   TableOptions_RowPagination,
+//   TableState_RowPagination,
+//   Table_RowPagination,
+// } from './rowPaginationFeature.types'
+
+interface RowPaginationFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // CachedRowModel: CachedRowModel_Paginated<TFeatures, TData>
+  // CreateRowModels: CreateRowModel_Paginated<TFeatures, TData>
+  // Table: Table_RowPagination<TFeatures, TData>
+  // TableOptions: TableOptions_RowPagination<TFeatures, TData>
+  // TableState: TableState_RowPagination
+}
+
+export function constructRowPaginationFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<RowPaginationFeatureConstructors<TFeatures, TData>> {
+  return {
+    getInitialState: (initialState) => {
+      return {
+        ...initialState,
+        pagination: {
+          ...getDefaultPaginationState(),
+          ...initialState.pagination,
+        },
+      }
+    },
+
+    getDefaultTableOptions: (table) => {
+      return {
+        onPaginationChange: makeStateUpdater('pagination', table),
+      }
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('rowPaginationFeature', table, {
+        table_autoResetPageIndex: {
+          fn: () => table_autoResetPageIndex(table),
+        },
+        table_setPagination: {
+          fn: (updater) => table_setPagination(table, updater),
+        },
+        table_resetPagination: {
+          fn: (defaultState) => table_resetPagination(table, defaultState),
+        },
+        table_setPageIndex: {
+          fn: (updater) => table_setPageIndex(table, updater),
+        },
+        table_resetPageIndex: {
+          fn: (defaultState) => table_resetPageIndex(table, defaultState),
+        },
+        table_setPageSize: {
+          fn: (updater) => table_setPageSize(table, updater),
+        },
+        table_getPageCount: {
+          fn: () => table_getPageCount(table),
+        },
+        table_resetPageSize: {
+          fn: (defaultState) => table_resetPageSize(table, defaultState),
+        },
+        table_getPageOptions: {
+          fn: () => table_getPageOptions(table),
+        },
+        table_getCanPreviousPage: {
+          fn: () => table_getCanPreviousPage(table),
+        },
+        table_getCanNextPage: {
+          fn: () => table_getCanNextPage(table),
+        },
+        table_previousPage: {
+          fn: () => table_previousPage(table),
+        },
+        table_nextPage: {
+          fn: () => table_nextPage(table),
+        },
+        table_firstPage: {
+          fn: () => table_firstPage(table),
+        },
+        table_lastPage: {
+          fn: () => table_lastPage(table),
+        },
+        table_getRowCount: {
+          fn: () => table_getRowCount(table),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The (Row) Pagination feature adds pagination state and APIs to the table object.
+ */
+export const rowPaginationFeature = constructRowPaginationFeature()

package/src/features/row-pagination/rowPaginationFeature.types.ts

@@ -0,0 +1,141 @@
+import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
+import type { Table } from '../../types/Table'
+import type { OnChangeFn, RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+
+export interface PaginationState {
+  pageIndex: number
+  pageSize: number
+}
+
+export interface TableState_RowPagination {
+  pagination: PaginationState
+}
+
+export interface TableOptions_RowPagination {
+  /**
+   * If set to `true`, pagination will be reset to the first page when page-altering state changes eg. `data` is updated, filters change, grouping changes, etc.
+   */
+  autoResetPageIndex?: boolean
+  /**
+   * Enables manual pagination. If this option is set to `true`, the table will not automatically paginate rows using `getPaginatedRowModel()` and instead will expect you to manually paginate the rows before passing them to the table. This is useful if you are doing server-side pagination and aggregation.
+   */
+  manualPagination?: boolean
+  /**
+   * If this function is provided, it will be called when the pagination state changes and you will be expected to manage the state yourself. You can pass the managed state back to the table via the `tableOptions.state.pagination` option.
+   */
+  onPaginationChange?: OnChangeFn<PaginationState>
+  /**
+   * When manually controlling pagination, you can supply a total `pageCount` value to the table if you know it (Or supply a `rowCount` and `pageCount` will be calculated). If you do not know how many pages there are, you can set this to `-1`.
+   */
+  pageCount?: number
+  /**
+   * When manually controlling pagination, you can supply a total `rowCount` value to the table if you know it. The `pageCount` can be calculated from this value and the `pageSize`.
+   */
+  rowCount?: number
+}
+
+export interface PaginationDefaultOptions {
+  onPaginationChange: OnChangeFn<PaginationState>
+}
+
+export interface Table_RowPagination<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  _autoResetPageIndex: () => void
+  /**
+   * Returns whether the table can go to the next page.
+   */
+  getCanNextPage: () => boolean
+  /**
+   * Returns whether the table can go to the previous page.
+   */
+  getCanPreviousPage: () => boolean
+  /**
+   * Returns the page count. If manually paginating or controlling the pagination state, this will come directly from the `options.pageCount` table option, otherwise it will be calculated from the table data using the total row count and current page size.
+   */
+  getPageCount: () => number
+  /**
+   * Returns the row count. If manually paginating or controlling the pagination state, this will come directly from the `options.rowCount` table option, otherwise it will be calculated from the table data.
+   */
+  getRowCount: () => number
+  /**
+   * Returns an array of page options (zero-index-based) for the current page size.
+   */
+  getPageOptions: () => Array<number>
+  /**
+   * Increments the page index by one, if possible.
+   */
+  nextPage: () => void
+  /**
+   * Decrements the page index by one, if possible.
+   */
+  previousPage: () => void
+  /**
+   * Sets the page index to `0`.
+   */
+  firstPage: () => void
+  /**
+   * Sets the page index to the last page.
+   */
+  lastPage: () => void
+  /**
+   * Resets the page index to its initial state. If `defaultState` is `true`, the page index will be reset to `0` regardless of initial state.
+   */
+  resetPageIndex: (defaultState?: boolean) => void
+  /**
+   * Resets the page size to its initial state. If `defaultState` is `true`, the page size will be reset to `10` regardless of initial state.
+   */
+  resetPageSize: (defaultState?: boolean) => void
+  /**
+   * Resets the **pagination** state to `initialState.pagination`, or `true` can be passed to force a default blank state reset to `[]`.
+   */
+  resetPagination: (defaultState?: boolean) => void
+  /**
+   * Updates the page index using the provided function or value in the `state.pagination.pageIndex` state.
+   */
+  setPageIndex: (updater: Updater<number>) => void
+  /**
+   * Updates the page size using the provided function or value in the `state.pagination.pageSize` state.
+   */
+  setPageSize: (updater: Updater<number>) => void
+  /**
+   * Sets or updates the `state.pagination` state.
+   */
+  setPagination: (updater: Updater<PaginationState>) => void
+}
+
+export interface Table_RowModels_Paginated<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns the row model for the table after pagination has been applied.
+   */
+  getPaginatedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Returns the row model for the table before any pagination has been applied.
+   */
+  getPrePaginatedRowModel: () => RowModel<TFeatures, TData>
+}
+
+export interface CreateRowModel_Paginated<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns the row model after pagination has taken place, but no further.
+   * Pagination columns are automatically reordered by default to the start of the columns list. If you would rather remove them or leave them as-is, set the appropriate mode here.
+   */
+  paginatedRowModel?: (
+    table: Table<TFeatures, TData>,
+  ) => () => RowModel<TFeatures, TData>
+}
+
+export interface CachedRowModel_Paginated<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  paginatedRowModel: () => RowModel<TFeatures, TData>
+}

package/src/features/row-pagination/rowPaginationFeature.utils.ts

@@ -0,0 +1,204 @@
+import { functionalUpdate } from '../../utils'
+import type { RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Table_Internal } from '../../types/Table'
+import type { PaginationState } from './rowPaginationFeature.types'
+
+const defaultPageIndex = 0
+const defaultPageSize = 10
+
+export function getDefaultPaginationState(): PaginationState {
+  return structuredClone({
+    pageIndex: defaultPageIndex,
+    pageSize: defaultPageSize,
+  })
+}
+
+export function table_autoResetPageIndex<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  if (
+    table.options.autoResetAll ??
+    table.options.autoResetPageIndex ??
+    !table.options.manualPagination
+  ) {
+    table_resetPageIndex(table)
+  }
+}
+
+export function table_setPagination<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, updater: Updater<PaginationState>) {
+  const safeUpdater: Updater<PaginationState> = (old) => {
+    const newState = functionalUpdate(updater, old)
+
+    return newState
+  }
+
+  return table.options.onPaginationChange?.(safeUpdater)
+}
+
+export function table_resetPagination<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setPagination(
+    table,
+    defaultState
+      ? getDefaultPaginationState()
+      : (table.initialState.pagination ?? getDefaultPaginationState()),
+  )
+}
+
+export function table_setPageIndex<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, updater: Updater<number>) {
+  table_setPagination(table, (old) => {
+    let pageIndex = functionalUpdate(updater, old.pageIndex)
+
+    const maxPageIndex =
+      typeof table.options.pageCount === 'undefined' ||
+      table.options.pageCount === -1
+        ? Number.MAX_SAFE_INTEGER
+        : table.options.pageCount - 1
+
+    pageIndex = Math.max(0, Math.min(pageIndex, maxPageIndex))
+
+    return {
+      ...old,
+      pageIndex,
+    }
+  })
+}
+
+export function table_resetPageIndex<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setPageIndex(
+    table,
+    defaultState
+      ? defaultPageIndex
+      : (table.initialState.pagination?.pageIndex ?? defaultPageIndex),
+  )
+}
+
+export function table_resetPageSize<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setPageSize(
+    table,
+    defaultState
+      ? defaultPageSize
+      : (table.initialState.pagination?.pageSize ?? defaultPageSize),
+  )
+}
+
+export function table_setPageSize<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, updater: Updater<number>) {
+  table_setPagination(table, (old) => {
+    const pageSize = Math.max(1, functionalUpdate(updater, old.pageSize))
+    const topRowIndex = old.pageSize * old.pageIndex
+    const pageIndex = Math.floor(topRowIndex / pageSize)
+
+    return {
+      ...old,
+      pageIndex,
+      pageSize,
+    }
+  })
+}
+
+export function table_getPageOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  const pageCount = table_getPageCount(table)
+  let pageOptions: Array<number> = []
+  if (pageCount && pageCount > 0) {
+    pageOptions = [...new Array(pageCount)].fill(null).map((_, i) => i)
+  }
+  return pageOptions
+}
+
+export function table_getCanPreviousPage<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return (table.store.state.pagination?.pageIndex ?? 0) > 0
+}
+
+export function table_getCanNextPage<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  const pageIndex = table.store.state.pagination?.pageIndex ?? defaultPageIndex
+
+  const pageCount = table_getPageCount(table)
+
+  if (pageCount === -1) {
+    return true
+  }
+
+  if (pageCount === 0) {
+    return false
+  }
+
+  return pageIndex < pageCount - 1
+}
+
+export function table_previousPage<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return table_setPageIndex(table, (old) => old - 1)
+}
+
+export function table_nextPage<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return table_setPageIndex(table, (old) => {
+    return old + 1
+  })
+}
+
+export function table_firstPage<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return table_setPageIndex(table, 0)
+}
+
+export function table_lastPage<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return table_setPageIndex(table, table_getPageCount(table) - 1)
+}
+
+export function table_getPageCount<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return (
+    table.options.pageCount ??
+    Math.ceil(
+      table_getRowCount(table) /
+        (table.store.state.pagination?.pageSize ?? defaultPageSize),
+    )
+  )
+}
+
+export function table_getRowCount<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>) {
+  return table.options.rowCount ?? table.getPrePaginatedRowModel().rows.length
+}

package/src/features/row-pinning/rowPinningFeature.ts

@@ -0,0 +1,121 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  getDefaultRowPinningState,
+  row_getCanPin,
+  row_getIsPinned,
+  row_getPinnedIndex,
+  row_pin,
+  table_getBottomRows,
+  table_getCenterRows,
+  table_getIsSomeRowsPinned,
+  table_getTopRows,
+  table_resetRowPinning,
+  table_setRowPinning,
+} from './rowPinningFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   Row_RowPinning,
+//   TableOptions_RowPinning,
+//   TableState_RowPinning,
+//   Table_RowPinning,
+// } from './rowPinningFeature.types'
+
+interface RowPinningFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // Row: Row_RowPinning
+  // Table: Table_RowPinning<TFeatures, RowData>
+  // TableOptions: TableOptions_RowPinning<TFeatures, RowData>
+  // TableState: TableState_RowPinning
+}
+
+export function constructRowPinningFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<RowPinningFeatureConstructors<TFeatures, TData>> {
+  return {
+    getInitialState: (initialState) => {
+      return {
+        ...initialState,
+        rowPinning: {
+          ...getDefaultRowPinningState(),
+          ...initialState.rowPinning,
+        },
+      }
+    },
+
+    getDefaultTableOptions: (table) => {
+      return {
+        onRowPinningChange: makeStateUpdater('rowPinning', table),
+      }
+    },
+
+    assignRowPrototype: (prototype, table) => {
+      assignPrototypeAPIs('rowPinningFeature', prototype, table, {
+        row_getCanPin: {
+          fn: (row) => row_getCanPin(row),
+        },
+        row_getIsPinned: {
+          fn: (row) => row_getIsPinned(row),
+        },
+        row_getPinnedIndex: {
+          fn: (row) => row_getPinnedIndex(row),
+          memoDeps: (row) => [
+            row.table.getRowModel().rows,
+            row.table.store.state.rowPinning,
+          ],
+        },
+        row_pin: {
+          fn: (row, position, includeLeafRows, includeParentRows) =>
+            row_pin(row, position, includeLeafRows, includeParentRows),
+        },
+      })
+    },
+
+    constructTableAPIs: (table) => {
+      assignTableAPIs('rowPinningFeature', table, {
+        table_setRowPinning: {
+          fn: (updater) => table_setRowPinning(table, updater),
+        },
+        table_resetRowPinning: {
+          fn: (defaultState) => table_resetRowPinning(table, defaultState),
+        },
+        table_getIsSomeRowsPinned: {
+          fn: (position) => table_getIsSomeRowsPinned(table, position),
+        },
+        table_getTopRows: {
+          fn: () => table_getTopRows(table),
+          memoDeps: () => [
+            table.getRowModel().rows,
+            table.store.state.rowPinning?.top,
+          ],
+        },
+        table_getBottomRows: {
+          fn: () => table_getBottomRows(table),
+          memoDeps: () => [
+            table.getRowModel().rows,
+            table.store.state.rowPinning?.bottom,
+          ],
+        },
+        table_getCenterRows: {
+          fn: () => table_getCenterRows(table),
+          memoDeps: () => [
+            table.getRowModel().rows,
+            table.store.state.rowPinning,
+          ],
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The Row Pinning feature adds row pinning state and APIs to the table and row objects.
+ */
+export const rowPinningFeature = constructRowPinningFeature()

package/src/features/row-pinning/rowPinningFeature.types.ts

@@ -0,0 +1,89 @@
+import type { OnChangeFn, RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+
+export type RowPinningPosition = false | 'top' | 'bottom'
+
+export interface RowPinningState {
+  bottom: Array<string>
+  top: Array<string>
+}
+
+export interface TableState_RowPinning {
+  rowPinning: RowPinningState
+}
+
+export interface TableOptions_RowPinning<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Enables/disables row pinning for the table. Defaults to `true`.
+   */
+  enableRowPinning?: boolean | ((row: Row<TFeatures, TData>) => boolean)
+  /**
+   * When `false`, pinned rows will not be visible if they are filtered or paginated out of the table. When `true`, pinned rows will always be visible regardless of filtering or pagination. Defaults to `true`.
+   */
+  keepPinnedRows?: boolean
+  /**
+   * If provided, this function will be called with an `updaterFn` when `state.rowPinning` changes. This overrides the default internal state management, so you will also need to supply `state.rowPinning` from your own managed state.
+   */
+  onRowPinningChange?: OnChangeFn<RowPinningState>
+}
+
+export interface RowPinningDefaultOptions {
+  onRowPinningChange: OnChangeFn<RowPinningState>
+}
+
+export interface Row_RowPinning {
+  /**
+   * Returns whether or not the row can be pinned.
+   */
+  getCanPin: () => boolean
+  /**
+   * Returns the pinned position of the row. (`'top'`, `'bottom'` or `false`)
+   */
+  getIsPinned: () => RowPinningPosition
+  /**
+   * Returns the numeric pinned index of the row within a pinned row group.
+   */
+  getPinnedIndex: () => number
+  /**
+   * Pins a row to the `'top'` or `'bottom'`, or unpins the row to the center if `false` is passed.
+   */
+  pin: (
+    position: RowPinningPosition,
+    includeLeafRows?: boolean,
+    includeParentRows?: boolean,
+  ) => void
+}
+
+export interface Table_RowPinning<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns all bottom pinned rows.
+   */
+  getBottomRows: () => Array<Row<TFeatures, TData>>
+  /**
+   * Returns all rows that are not pinned to the top or bottom.
+   */
+  getCenterRows: () => Array<Row<TFeatures, TData>>
+  /**
+   * Returns whether or not any rows are pinned. Optionally specify to only check for pinned rows in either the `top` or `bottom` position.
+   */
+  getIsSomeRowsPinned: (position?: RowPinningPosition) => boolean
+  /**
+   * Returns all top pinned rows.
+   */
+  getTopRows: () => Array<Row<TFeatures, TData>>
+  /**
+   * Resets the **rowPinning** state to `initialState.rowPinning`, or `true` can be passed to force a default blank state reset to `{ top: [], bottom: [], }`.
+   */
+  resetRowPinning: (defaultState?: boolean) => void
+  /**
+   * Sets or updates the `state.rowPinning` state.
+   */
+  setRowPinning: (updater: Updater<RowPinningState>) => void
+}