@tanstack/table-core 9.0.0-alpha.6 → 9.0.0-beta.1

package/src/features/row-sorting/createSortedRowModel.ts

@@ -0,0 +1,157 @@
+import { tableMemo } from '../../utils'
+import { table_autoResetPageIndex } from '../row-pagination/rowPaginationFeature.utils'
+import { column_getCanSort, column_getSortFn } from './rowSortingFeature.utils'
+import type { Column_Internal } from '../../types/Column'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
+import type { Table, Table_Internal } from '../../types/Table'
+import type { Row } from '../../types/Row'
+import type { SortFn, SortFns } from './rowSortingFeature.types'
+import type { RowData } from '../../types/type-utils'
+
+/**
+ * Creates a memoized sorted row model factory.
+ *
+ * The factory reads the relevant table state atoms and options, then returns a row model function used by the table row-model pipeline.
+ */
+export function createSortedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  sortFns: Record<keyof SortFns, SortFn<TFeatures, TData>>,
+): (table: Table<TFeatures, TData>) => () => RowModel<TFeatures, TData> {
+  return (_table) => {
+    const table: Table_Internal<TFeatures, TData> = _table
+    if (!table._rowModelFns.sortFns) table._rowModelFns.sortFns = sortFns
+    return tableMemo({
+      feature: 'rowSortingFeature',
+      table,
+      fnName: 'table.getSortedRowModel',
+      memoDeps: () => [
+        table.atoms.sorting?.get(),
+        table.getPreSortedRowModel(),
+      ],
+      fn: () => _createSortedRowModel(table),
+      onAfterUpdate: () => table_autoResetPageIndex(table),
+    })
+  }
+}
+
+function _createSortedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(table: Table_Internal<TFeatures, TData>): RowModel<TFeatures, TData> {
+  const preSortedRowModel = table.getPreSortedRowModel()
+  const sorting = table.atoms.sorting?.get()
+
+  if (!preSortedRowModel.rows.length || !sorting?.length) {
+    return preSortedRowModel
+  }
+
+  const sortedFlatRows: Array<Row<TFeatures, TData>> = []
+
+  // Filter out sortings that correspond to non existing columns
+  const availableSorting = sorting.filter((sort) =>
+    column_getCanSort(
+      table.getColumn(sort.id) as Column_Internal<TFeatures, TData>,
+    ),
+  )
+
+  const columnInfoById: Record<
+    string,
+    {
+      sortUndefined?: false | -1 | 1 | 'first' | 'last'
+      invertSorting?: boolean
+      sortFn: SortFn<TFeatures, TData>
+    }
+  > = {}
+
+  availableSorting.forEach((sortEntry) => {
+    const column: Column_Internal<TFeatures, TData> | undefined =
+      table.getColumn(sortEntry.id)
+    if (!column) return
+
+    columnInfoById[sortEntry.id] = {
+      sortUndefined: column.columnDef.sortUndefined,
+      invertSorting: column.columnDef.invertSorting,
+      sortFn: column_getSortFn(column),
+    }
+  })
+
+  const sortData = (rows: Array<Row<TFeatures, TData>>) => {
+    const sortedData = rows.slice()
+
+    sortedData.sort((rowA, rowB) => {
+      for (let i = 0; i < availableSorting.length; i++) {
+        const sortEntry = availableSorting[i]!
+        const columnInfo = columnInfoById[sortEntry.id]!
+        const sortUndefined = columnInfo.sortUndefined
+        const isDesc = sortEntry.desc
+
+        let sortInt = 0
+
+        // All sorting ints should always return in ascending order
+        if (sortUndefined) {
+          const aValue = rowA.getValue(sortEntry.id)
+          const bValue = rowB.getValue(sortEntry.id)
+
+          const aUndefined = aValue === undefined
+          const bUndefined = bValue === undefined
+
+          if (aUndefined || bUndefined) {
+            if (sortUndefined === 'first') return aUndefined ? -1 : 1
+            if (sortUndefined === 'last') return aUndefined ? 1 : -1
+            sortInt =
+              aUndefined && bUndefined
+                ? 0
+                : aUndefined
+                  ? sortUndefined
+                  : -sortUndefined
+          }
+        }
+
+        if (sortInt === 0) {
+          sortInt = columnInfo.sortFn(rowA, rowB, sortEntry.id)
+        }
+
+        // If sorting is non-zero, take care of desc and inversion
+        if (sortInt !== 0) {
+          if (isDesc) {
+            sortInt *= -1
+          }
+
+          if (columnInfo.invertSorting) {
+            sortInt *= -1
+          }
+
+          return sortInt
+        }
+      }
+      return rowA.index - rowB.index
+    })
+
+    // If there are sub-rows, sort them. Clone only rows that need mutation
+    // (i.e. have subRows) so we don't corrupt the source row model.
+    for (let i = 0; i < sortedData.length; i++) {
+      const row = sortedData[i]!
+      if (row.subRows.length) {
+        // Preserve prototype chain so methods like getValue() remain accessible
+        const cloned = Object.create(Object.getPrototypeOf(row))
+        Object.assign(cloned, row)
+        cloned.subRows = sortData(row.subRows)
+        sortedData[i] = cloned
+        sortedFlatRows.push(cloned)
+      } else {
+        sortedFlatRows.push(row)
+      }
+    }
+
+    return sortedData
+  }
+
+  return {
+    rows: sortData(preSortedRowModel.rows),
+    flatRows: sortedFlatRows,
+    rowsById: preSortedRowModel.rowsById,
+  }
+}

package/src/features/row-sorting/rowSortingFeature.ts

@@ -0,0 +1,144 @@
+import {
+  assignPrototypeAPIs,
+  assignTableAPIs,
+  makeStateUpdater,
+} from '../../utils'
+import {
+  column_clearSorting,
+  column_getAutoSortDir,
+  column_getAutoSortFn,
+  column_getCanMultiSort,
+  column_getCanSort,
+  column_getFirstSortDir,
+  column_getIsSorted,
+  column_getNextSortingOrder,
+  column_getSortFn,
+  column_getSortIndex,
+  column_getToggleSortingHandler,
+  column_toggleSorting,
+  getDefaultSortingState,
+  table_resetSorting,
+  table_setSorting,
+} from './rowSortingFeature.utils'
+import type { RowData } from '../../types/type-utils'
+import type { TableFeature, TableFeatures } from '../../types/TableFeatures'
+// import type {
+//   CachedRowModel_Sorted,
+//   ColumnDef_RowSorting,
+//   Column_RowSorting,
+//   CreateRowModel_Sorted,
+//   RowModelFns_RowSorting,
+//   TableOptions_RowSorting,
+//   TableState_RowSorting,
+//   Table_RowSorting,
+// } from './rowSortingFeature.types'
+
+export interface RowSortingFeatureConstructors<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  // CachedRowModel: CachedRowModel_Sorted<TFeatures, TData>
+  // Column: Column_RowSorting<TFeatures, TData>
+  // ColumnDef: ColumnDef_RowSorting<TFeatures, TData>
+  // CreateRowModels: CreateRowModel_Sorted<TFeatures, TData>
+  // RowModelFns: RowModelFns_RowSorting<TFeatures, TData>
+  // Table: Table_RowSorting<TFeatures, TData>
+  // TableOptions: TableOptions_RowSorting
+  // TableState: TableState_RowSorting
+}
+
+/**
+ * Creates the stock row sorting feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
+export function constructRowSortingFeature<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): TableFeature<RowSortingFeatureConstructors<TFeatures, TData>> {
+  return {
+    getInitialState(initialState) {
+      return {
+        sorting: getDefaultSortingState(),
+        ...initialState,
+      }
+    },
+
+    getDefaultColumnDef() {
+      return {
+        sortFn: 'auto',
+        sortUndefined: 1,
+      }
+    },
+
+    getDefaultTableOptions(table) {
+      return {
+        onSortingChange: makeStateUpdater('sorting', table),
+        isMultiSortEvent: (e: unknown) => {
+          return (e as MouseEvent).shiftKey
+        },
+      }
+    },
+
+    assignColumnPrototype(prototype, table) {
+      assignPrototypeAPIs('rowSortingFeature', prototype, table, {
+        column_getAutoSortFn: {
+          fn: (column) => column_getAutoSortFn(column),
+        },
+        column_getAutoSortDir: {
+          fn: (column) => column_getAutoSortDir(column),
+        },
+        column_getSortFn: {
+          fn: (column) => column_getSortFn(column),
+        },
+        column_toggleSorting: {
+          fn: (column, desc, multi) =>
+            column_toggleSorting(column, desc, multi),
+        },
+        column_getFirstSortDir: {
+          fn: (column) => column_getFirstSortDir(column),
+        },
+        column_getNextSortingOrder: {
+          fn: (column, multi) => column_getNextSortingOrder(column, multi),
+        },
+        column_getCanSort: {
+          fn: (column) => column_getCanSort(column),
+        },
+        column_getCanMultiSort: {
+          fn: (column) => column_getCanMultiSort(column),
+        },
+        column_getIsSorted: {
+          fn: (column) => column_getIsSorted(column),
+        },
+        column_getSortIndex: {
+          fn: (column) => column_getSortIndex(column),
+        },
+        column_clearSorting: {
+          fn: (column) => column_clearSorting(column),
+        },
+        column_getToggleSortingHandler: {
+          fn: (column) => column_getToggleSortingHandler(column),
+        },
+      })
+    },
+
+    constructTableAPIs(table) {
+      assignTableAPIs('rowSortingFeature', table, {
+        table_setSorting: {
+          fn: (updater) => table_setSorting(table, updater),
+        },
+        table_resetSorting: {
+          fn: (defaultState) => table_resetSorting(table, defaultState),
+        },
+      })
+    },
+  }
+}
+
+/**
+ * The stock row sorting feature.
+ *
+ * Register this feature to add sorting state, column sorting APIs, and sorted
+ * row-model support for client-side or manual sorting.
+ */
+export const rowSortingFeature = constructRowSortingFeature()

package/src/features/row-sorting/rowSortingFeature.types.ts

@@ -0,0 +1,235 @@
+import type { RowModel } from '../../core/row-models/coreRowModelsFeature.types'
+import type { Table } from '../../types/Table'
+import type { BuiltInSortFn } from '../../fns/sortFns'
+import type { OnChangeFn, RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Row } from '../../types/Row'
+
+export type SortDirection = 'asc' | 'desc'
+
+export interface ColumnSort {
+  desc: boolean
+  id: string
+}
+
+export type SortingState = Array<ColumnSort>
+
+export interface TableState_RowSorting {
+  sorting: SortingState
+}
+
+export interface RowModelFns_RowSorting<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  sortFns: Record<keyof SortFns, SortFn<TFeatures, TData>>
+}
+
+export interface SortFns {}
+
+export interface SortFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  (
+    rowA: Row<TFeatures, TData>,
+    rowB: Row<TFeatures, TData>,
+    columnId: string,
+  ): number
+}
+
+export type CustomSortFns<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = Record<string, SortFn<TFeatures, TData>>
+
+export type SortFnOption<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = 'auto' | keyof SortFns | BuiltInSortFn | SortFn<TFeatures, TData>
+
+export interface ColumnDef_RowSorting<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Enables/Disables multi-sorting for this column.
+   */
+  enableMultiSort?: boolean
+  /**
+   * Enables/Disables sorting for this column.
+   */
+  enableSorting?: boolean
+  /**
+   * Inverts the order of the sorting for this column. This is useful for values that have an inverted best/worst scale where lower numbers are better, eg. a ranking (1st, 2nd, 3rd) or golf-like scoring
+   */
+  invertSorting?: boolean
+  /**
+   * Set to `true` for sorting toggles on this column to start in the descending direction.
+   */
+  sortDescFirst?: boolean
+  /**
+   * The sorting function to use with this column.
+   * - A `string` referencing a built-in sorting function
+   * - A custom sorting function
+   */
+  sortFn?: SortFnOption<TFeatures, TData>
+  /**
+   * The priority of undefined values when sorting this column.
+   * - `false`
+   *   - Undefined values will be considered tied and need to be sorted by the next column filter or original index (whichever applies)
+   * - `-1`
+   *   - Undefined values will be sorted with higher priority (ascending) (if ascending, undefined will appear on the beginning of the list)
+   * - `1`
+   *   - Undefined values will be sorted with lower priority (descending) (if ascending, undefined will appear on the end of the list)
+   */
+  sortUndefined?: false | -1 | 1 | 'first' | 'last'
+}
+
+export interface Column_RowSorting<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Removes this column from the table's sorting state
+   */
+  clearSorting: () => void
+  /**
+   * Returns a sort direction automatically inferred based on the columns values.
+   */
+  getAutoSortDir: () => SortDirection
+  /**
+   * Returns a sorting function automatically inferred based on the columns values.
+   */
+  getAutoSortFn: () => SortFn<TFeatures, TData>
+  /**
+   * Returns whether this column can be multi-sorted.
+   */
+  getCanMultiSort: () => boolean
+  /**
+   * Returns whether this column can be sorted.
+   */
+  getCanSort: () => boolean
+  /**
+   * Returns the first direction that should be used when sorting this column.
+   */
+  getFirstSortDir: () => SortDirection
+  /**
+   * Reads this column's current sort direction, or `false` when unsorted.
+   */
+  getIsSorted: () => false | SortDirection
+  /**
+   * Returns the next sorting order.
+   */
+  getNextSortingOrder: () => SortDirection | false
+  /**
+   * Finds this column's position in the ordered sorting state.
+   */
+  getSortIndex: () => number
+  /**
+   * Returns the resolved sorting function to be used for this column
+   */
+  getSortFn: () => SortFn<TFeatures, TData>
+  /**
+   * Creates a header/control handler that toggles this column's sorting state.
+   */
+  getToggleSortingHandler: () => undefined | ((event: unknown) => void)
+  /**
+   * Toggles this columns sorting state. If `desc` is provided, it will force the sort direction to that value. If `isMulti` is provided, it will additivity multi-sort the column (or toggle it if it is already sorted).
+   */
+  toggleSorting: (desc?: boolean, isMulti?: boolean) => void
+}
+
+export interface TableOptions_RowSorting {
+  /**
+   * Allows multi-sort toggles to remove a column from sorting state.
+   */
+  enableMultiRemove?: boolean
+  /**
+   * Enables/Disables multi-sorting for the table.
+   */
+  enableMultiSort?: boolean
+  /**
+   * Enables/Disables sorting for the table.
+   */
+  enableSorting?: boolean
+  /**
+   * Enables/Disables the ability to remove sorting for the table.
+   * - If `true` then changing sort order will circle like: 'none' -> 'desc' -> 'asc' -> 'none' -> ...
+   * - If `false` then changing sort order will circle like: 'none' -> 'desc' -> 'asc' -> 'desc' -> 'asc' -> ...
+   */
+  enableSortingRemoval?: boolean
+  /**
+   * Pass a custom function that will be used to determine if a multi-sort event should be triggered. It is passed the event from the sort toggle handler and should return `true` if the event should trigger a multi-sort.
+   */
+  isMultiSortEvent?: (e: unknown) => boolean
+  /**
+   * Enables manual sorting for the table. If this is `true`, you will be expected to sort your data before it is passed to the table. This is useful if you are doing server-side sorting.
+   */
+  manualSorting?: boolean
+  /**
+   * Set a maximum number of columns that can be multi-sorted.
+   */
+  maxMultiSortColCount?: number
+  /**
+   * Called with an updater when sorting state changes. Pair this with
+   * `state.sorting` when using external state; external atoms can own the slice
+   * without this callback.
+   */
+  onSortingChange?: OnChangeFn<SortingState>
+  /**
+   * If `true`, all sorts will default to descending as their first toggle state.
+   */
+  sortDescFirst?: boolean
+}
+
+export interface Table_RowSorting<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Resets `sorting` to `initialState.sorting`.
+   *
+   * Pass `true` to ignore initial state and reset to `[]`.
+   */
+  resetSorting: (defaultState?: boolean) => void
+  /**
+   * Updates sorting state with a next ordered array or updater function.
+   */
+  setSorting: (updater: Updater<SortingState>) => void
+}
+
+export interface Table_RowModels_Sorted<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Reads the row model immediately before sorting.
+   */
+  getPreSortedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Resolves the row model after sorting has been applied.
+   */
+  getSortedRowModel: () => RowModel<TFeatures, TData>
+}
+
+export interface CreateRowModel_Sorted<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Factory used to retrieve the sorted row model. If using server-side
+   * sorting, this is not required. To use client-side sorting, pass the
+   * exported `createSortedRowModel()` or implement your own factory.
+   */
+  sortedRowModel?: (
+    table: Table<TFeatures, TData>,
+  ) => () => RowModel<TFeatures, TData>
+}
+
+export interface CachedRowModel_Sorted<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  sortedRowModel: () => RowModel<TFeatures, TData>
+}