@tanstack/table-core 9.0.0-alpha.4 → 9.0.0-alpha.41

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

@@ -0,0 +1,136 @@
+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
+}
+
+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 (Row) Sorting feature adds sorting state and APIs to the table and column objects.
+ */
+export const rowSortingFeature = constructRowSortingFeature()

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

@@ -0,0 +1,229 @@
+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
+  /**
+   * Returns the current sort direction of this column.
+   */
+  getIsSorted: () => false | SortDirection
+  /**
+   * Returns the next sorting order.
+   */
+  getNextSortingOrder: () => SortDirection | false
+  /**
+   * Returns the index position of this column's sorting within the sorting state
+   */
+  getSortIndex: () => number
+  /**
+   * Returns the resolved sorting function to be used for this column
+   */
+  getSortFn: () => SortFn<TFeatures, TData>
+  /**
+   * Returns a function that can be used to toggle this column's sorting state. This is useful for attaching a click handler to the column header.
+   */
+  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 {
+  /**
+   * Enables/disables the ability to remove multi-sorts
+   */
+  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
+  /**
+   * If provided, this function will be called with an `updaterFn` when `state.sorting` changes. This overrides the default internal state management, so you will need to persist the state change either fully or partially outside of the table.
+   */
+  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 the **sorting** state to `initialState.sorting`, or `true` can be passed to force a default blank state reset to `[]`.
+   */
+  resetSorting: (defaultState?: boolean) => void
+  /**
+   * Sets or updates the `state.sorting` state.
+   */
+  setSorting: (updater: Updater<SortingState>) => void
+}
+
+export interface Table_RowModels_Sorted<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * Returns the row model for the table before any sorting has been applied.
+   */
+  getPreSortedRowModel: () => RowModel<TFeatures, TData>
+  /**
+   * Returns the row model for the table after sorting has been applied.
+   */
+  getSortedRowModel: () => RowModel<TFeatures, TData>
+}
+
+export interface CreateRowModel_Sorted<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  /**
+   * This function is used to retrieve the sorted row model. If using server-side sorting, this function is not required. To use client-side sorting, pass the exported `getSortedRowModel()` from your adapter to your table or implement your own.
+   */
+  sortedRowModel?: (
+    table: Table<TFeatures, TData>,
+  ) => () => RowModel<TFeatures, TData>
+}
+
+export interface CachedRowModel_Sorted<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> {
+  sortedRowModel: () => RowModel<TFeatures, TData>
+}

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

@@ -0,0 +1,319 @@
+import { reSplitAlphaNumeric, sortFn_basic } from '../../fns/sortFns'
+import { cloneState, isFunction } from '../../utils'
+import type { CellData, RowData, Updater } from '../../types/type-utils'
+import type { TableFeatures } from '../../types/TableFeatures'
+import type { Table_Internal } from '../../types/Table'
+import type { Column_Internal } from '../../types/Column'
+import type {
+  SortDirection,
+  SortFn,
+  SortingState,
+} from './rowSortingFeature.types'
+
+// State Utils
+
+export function getDefaultSortingState(): SortingState {
+  return []
+}
+
+export function table_setSorting<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, updater: Updater<SortingState>) {
+  table.options.onSortingChange?.(updater)
+}
+
+export function table_resetSorting<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {
+  table_setSorting(
+    table,
+    defaultState ? [] : cloneState(table.initialState.sorting ?? []),
+  )
+}
+
+// Column Utils
+
+export function column_getAutoSortFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): SortFn<TFeatures, TData> {
+  const sortFns: Record<string, SortFn<TFeatures, TData>> | undefined =
+    column.table._rowModelFns.sortFns
+
+  let sortFn: SortFn<TFeatures, TData> | undefined
+
+  const firstRows = column.table.getFilteredRowModel().flatRows.slice(10)
+
+  let isString = false
+
+  for (const row of firstRows) {
+    const value = row.getValue(column.id)
+
+    if (Object.prototype.toString.call(value) === '[object Date]') {
+      sortFn = sortFns?.datetime
+    }
+
+    if (typeof value === 'string') {
+      isString = true
+
+      if (value.split(reSplitAlphaNumeric).length > 1) {
+        sortFn = sortFns?.alphanumeric
+      }
+    }
+  }
+
+  if (isString) {
+    sortFn = sortFns?.text
+  }
+
+  return sortFn ?? sortFn_basic
+}
+
+export function column_getAutoSortDir<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  const firstRow = column.table.getFilteredRowModel().flatRows[0]
+
+  const value = firstRow ? firstRow.getValue(column.id) : undefined
+
+  if (typeof value === 'string') {
+    return 'asc'
+  }
+
+  return 'desc'
+}
+
+export function column_getSortFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): SortFn<TFeatures, TData> {
+  const sortFns: Record<string, SortFn<TFeatures, TData>> | undefined =
+    column.table._rowModelFns.sortFns
+
+  return isFunction(column.columnDef.sortFn)
+    ? column.columnDef.sortFn
+    : column.columnDef.sortFn === 'auto'
+      ? column_getAutoSortFn(column)
+      : (sortFns?.[column.columnDef.sortFn as string] ?? sortFn_basic)
+}
+
+export function column_toggleSorting<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(
+  column: Column_Internal<TFeatures, TData, TValue>,
+  desc?: boolean,
+  multi?: boolean,
+) {
+  // if (column.columns.length) {
+  //   column.columns.forEach((c, i) => {
+  //     if (c.id) {
+  //       table.toggleColumnSorting(c.id, undefined, multi || !!i)
+  //     }
+  //   })
+  //   return
+  // }
+
+  // this needs to be outside of table.setSorting to be in sync with rerender
+  const nextSortingOrder = column_getNextSortingOrder(column)
+  const hasManualValue = typeof desc !== 'undefined'
+
+  table_setSorting(column.table, (old) => {
+    // Find any existing sorting for this column
+    const existingSorting = old.find((d) => d.id === column.id)
+    const existingIndex = old.findIndex((d) => d.id === column.id)
+
+    let newSorting: SortingState = []
+
+    // What should we do with this sort action?
+    let sortAction: 'add' | 'remove' | 'toggle' | 'replace'
+    const nextDesc = hasManualValue ? desc : nextSortingOrder === 'desc'
+
+    // Multi-mode
+    if (old.length && column_getCanMultiSort(column) && multi) {
+      if (existingSorting) {
+        sortAction = 'toggle'
+      } else {
+        sortAction = 'add'
+      }
+    } else {
+      // Normal mode
+      if (old.length && existingIndex !== old.length - 1) {
+        sortAction = 'replace'
+      } else if (existingSorting) {
+        sortAction = 'toggle'
+      } else {
+        sortAction = 'replace'
+      }
+    }
+
+    // Handle toggle states that will remove the sorting
+    if (sortAction === 'toggle') {
+      // If we are "actually" toggling (not a manual set value), should we remove the sorting?
+      if (!hasManualValue) {
+        // Is our intention to remove?
+        if (!nextSortingOrder) {
+          sortAction = 'remove'
+        }
+      }
+    }
+
+    if (sortAction === 'add') {
+      newSorting = [
+        ...old,
+        {
+          id: column.id,
+          desc: nextDesc,
+        },
+      ]
+      // Take latest n columns
+      newSorting.splice(
+        0,
+        newSorting.length -
+          (column.table.options.maxMultiSortColCount ??
+            Number.MAX_SAFE_INTEGER),
+      )
+    } else if (sortAction === 'toggle') {
+      // This flips (or sets) the
+      newSorting = old.map((d) => {
+        if (d.id === column.id) {
+          return {
+            ...d,
+            desc: nextDesc,
+          }
+        }
+        return d
+      })
+    } else if (sortAction === 'remove') {
+      newSorting = old.filter((d) => d.id !== column.id)
+    } else {
+      newSorting = [
+        {
+          id: column.id,
+          desc: nextDesc,
+        },
+      ]
+    }
+
+    return newSorting
+  })
+}
+
+export function column_getFirstSortDir<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  const sortDescFirst =
+    column.columnDef.sortDescFirst ??
+    column.table.options.sortDescFirst ??
+    column_getAutoSortDir(column) === 'desc'
+  return sortDescFirst ? 'desc' : 'asc'
+}
+
+export function column_getNextSortingOrder<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>, multi?: boolean) {
+  const firstSortDirection = column_getFirstSortDir(column)
+  const isSorted = column_getIsSorted(column)
+
+  if (!isSorted) {
+    return firstSortDirection
+  }
+
+  if (
+    isSorted !== firstSortDirection &&
+    (column.table.options.enableSortingRemoval ?? true) && // If enableSortRemove, enable in general
+    (multi ? (column.table.options.enableMultiRemove ?? true) : true) // If multi, don't allow if enableMultiRemove))
+  ) {
+    return false
+  }
+  return isSorted === 'desc' ? 'asc' : 'desc'
+}
+
+export function column_getCanSort<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  return (
+    (column.columnDef.enableSorting ?? true) &&
+    (column.table.options.enableSorting ?? true) &&
+    !!column.accessorFn
+  )
+}
+
+export function column_getCanMultiSort<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): boolean {
+  return (
+    column.columnDef.enableMultiSort ??
+    column.table.options.enableMultiSort ??
+    !!column.accessorFn
+  )
+}
+
+export function column_getIsSorted<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): false | SortDirection {
+  const columnSort = column.table.atoms.sorting
+    ?.get()
+    ?.find((d) => d.id === column.id)
+  return !columnSort ? false : columnSort.desc ? 'desc' : 'asc'
+}
+
+export function column_getSortIndex<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>): number {
+  return (
+    column.table.atoms.sorting?.get()?.findIndex((d) => d.id === column.id) ??
+    -1
+  )
+}
+
+export function column_clearSorting<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  // clear sorting for just 1 column
+  table_setSorting(column.table, (old) =>
+    old.length ? old.filter((d) => d.id !== column.id) : [],
+  )
+}
+
+export function column_getToggleSortingHandler<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TValue extends CellData = CellData,
+>(column: Column_Internal<TFeatures, TData, TValue>) {
+  const canSort = column_getCanSort(column)
+
+  return (e: unknown) => {
+    if (!canSort) return
+    ;(e as any).persist?.()
+    column_toggleSorting(
+      column,
+
+      undefined,
+      column_getCanMultiSort(column)
+        ? column.table.options.isMultiSortEvent?.(e)
+        : false,
+    )
+  }
+}