@tanstack/table-core 8.10.1 → 8.10.2

package/src/features/Sorting.ts

@@ -21,8 +21,8 @@ import { isFunction, makeStateUpdater } from '../utils'
 export type SortDirection = 'asc' | 'desc'
 
 export interface ColumnSort {
-  id: string
   desc: boolean
+  id: string
 }
 
 export type SortingState = ColumnSort[]
@@ -47,40 +47,187 @@ export type SortingFnOption<TData extends RowData> =
   | SortingFn<TData>
 
 export interface SortingColumnDef<TData extends RowData> {
-  sortingFn?: SortingFnOption<TData>
-  sortDescFirst?: boolean
-  enableSorting?: boolean
+  /**
+   * Enables/Disables multi-sorting for this column.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#enablemultisort)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   enableMultiSort?: boolean
+  /**
+   * Enables/Disables sorting for this column.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#enablesorting)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  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
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#invertsorting)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   invertSorting?: boolean
+  /**
+   * Set to `true` for sorting toggles on this column to start in the descending direction.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#sortdescfirst)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  sortDescFirst?: boolean
+  /**
+   * The sorting function to use with this column.
+   * - A `string` referencing a built-in sorting function
+   * - A custom sorting function
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#sortingfn)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  sortingFn?: SortingFnOption<TData>
+  /**
+   * - `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
 }
 
 export interface SortingColumn<TData extends RowData> {
-  getAutoSortingFn: () => SortingFn<TData>
+  /**
+   * Removes this column from the table's sorting state
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#clearsorting)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  clearSorting: () => void
+  /**
+   * Returns a sort direction automatically inferred based on the columns values.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getautosortdir)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   getAutoSortDir: () => SortDirection
-  getSortingFn: () => SortingFn<TData>
+  /**
+   * Returns a sorting function automatically inferred based on the columns values.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getautosortingfn)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  getAutoSortingFn: () => SortingFn<TData>
+  /**
+   * Returns whether this column can be multi-sorted.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getcanmultisort)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  getCanMultiSort: () => boolean
+  /**
+   * Returns whether this column can be sorted.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getcansort)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  getCanSort: () => boolean
+  /**
+   * Returns the first direction that should be used when sorting this column.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getfirstsortdir)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   getFirstSortDir: () => SortDirection
+  /**
+   * Returns the current sort direction of this column.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getissorted)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  getIsSorted: () => false | SortDirection
+  /**
+   * Returns the next sorting order.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getnextsortingorder)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   getNextSortingOrder: () => SortDirection | false
-  getCanSort: () => boolean
-  getCanMultiSort: () => boolean
+  /**
+   * Returns the index position of this column's sorting within the sorting state
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getsortindex)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   getSortIndex: () => number
-  getIsSorted: () => false | SortDirection
-  clearSorting: () => void
-  toggleSorting: (desc?: boolean, isMulti?: boolean) => void
+  /**
+   * Returns the resolved sorting function to be used for this column
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getsortingfn)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  getSortingFn: () => SortingFn<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.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#gettogglesortinghandler)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   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).
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#togglesorting)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  toggleSorting: (desc?: boolean, isMulti?: boolean) => void
 }
 
 interface SortingOptionsBase {
-  manualSorting?: boolean
-  onSortingChange?: OnChangeFn<SortingState>
-  enableSorting?: boolean
-  enableSortingRemoval?: boolean
+  /**
+   * Enables/disables the ability to remove multi-sorts
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#enablemultiremove)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   enableMultiRemove?: boolean
+  /**
+   * Enables/Disables multi-sorting for the table.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#enablemultisort)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   enableMultiSort?: boolean
-  sortDescFirst?: boolean
+  /**
+   * Enables/Disables sorting for the table.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#enablesorting)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  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' -> ...
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#enablesortingremoval)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  enableSortingRemoval?: boolean
+  /**
+   * 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.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getsortedrowmodel)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   getSortedRowModel?: (table: Table<any>) => () => RowModel<any>
-  maxMultiSortColCount?: number
+  /**
+   * 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.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#ismultisortevent)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   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.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#manualsorting)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  manualSorting?: boolean
+  /**
+   * Set a maximum number of columns that can be multi-sorted.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#maxmultisortcolcount)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  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.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#onsortingchange)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  onSortingChange?: OnChangeFn<SortingState>
+  /**
+   * If `true`, all sorts will default to descending as their first toggle state.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#sortdescfirst)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  sortDescFirst?: boolean
 }
 
 type ResolvedSortingFns = keyof SortingFns extends never
@@ -96,11 +243,31 @@ export interface SortingOptions<TData extends RowData>
     ResolvedSortingFns {}
 
 export interface SortingInstance<TData extends RowData> {
-  setSorting: (updater: Updater<SortingState>) => void
-  resetSorting: (defaultState?: boolean) => void
+  _getSortedRowModel?: () => RowModel<TData>
+  /**
+   * Returns the row model for the table before any sorting has been applied.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getpresortedrowmodel)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   getPreSortedRowModel: () => RowModel<TData>
+  /**
+   * Returns the row model for the table after sorting has been applied.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#getsortedrowmodel)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
   getSortedRowModel: () => RowModel<TData>
-  _getSortedRowModel?: () => RowModel<TData>
+  /**
+   * Resets the **sorting** state to `initialState.sorting`, or `true` can be passed to force a default blank state reset to `[]`.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#resetsorting)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  resetSorting: (defaultState?: boolean) => void
+  /**
+   * Sets or updates the `state.sorting` state.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/sorting#setsorting)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/sorting)
+   */
+  setSorting: (updater: Updater<SortingState>) => void
 }
 
 //

package/src/features/Visibility.ts

@@ -17,26 +17,87 @@ export interface VisibilityTableState {
 }
 
 export interface VisibilityOptions {
-  onColumnVisibilityChange?: OnChangeFn<VisibilityState>
   enableHiding?: boolean
+  /**
+   * If provided, this function will be called with an `updaterFn` when `state.columnVisibility` 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.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#oncolumnvisibilitychange)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
+  onColumnVisibilityChange?: OnChangeFn<VisibilityState>
 }
 
-export interface VisibilityDefaultOptions {
-  onColumnVisibilityChange: OnChangeFn<VisibilityState>
-}
+export type VisibilityDefaultOptions = Pick<
+  VisibilityOptions,
+  'onColumnVisibilityChange'
+>
 
 export interface VisibilityInstance<TData extends RowData> {
-  getVisibleFlatColumns: () => Column<TData, unknown>[]
-  getVisibleLeafColumns: () => Column<TData, unknown>[]
-  getLeftVisibleLeafColumns: () => Column<TData, unknown>[]
-  getRightVisibleLeafColumns: () => Column<TData, unknown>[]
+  /**
+   * If column pinning, returns a flat array of leaf-node columns that are visible in the unpinned/center portion of the table.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#getcentervisibleleafcolumns)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
   getCenterVisibleLeafColumns: () => Column<TData, unknown>[]
-  setColumnVisibility: (updater: Updater<VisibilityState>) => void
-  resetColumnVisibility: (defaultState?: boolean) => void
-  toggleAllColumnsVisible: (value?: boolean) => void
+  /**
+   * Returns whether all columns are visible
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#getisallcolumnsvisible)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
   getIsAllColumnsVisible: () => boolean
+  /**
+   * Returns whether any columns are visible
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#getissomecolumnsvisible)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
   getIsSomeColumnsVisible: () => boolean
+  /**
+   * If column pinning, returns a flat array of leaf-node columns that are visible in the left portion of the table.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#getleftvisibleleafcolumns)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
+  getLeftVisibleLeafColumns: () => Column<TData, unknown>[]
+  /**
+   * If column pinning, returns a flat array of leaf-node columns that are visible in the right portion of the table.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#getrightvisibleleafcolumns)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
+  getRightVisibleLeafColumns: () => Column<TData, unknown>[]
+  /**
+   * Returns a handler for toggling the visibility of all columns, meant to be bound to a `input[type=checkbox]` element.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#gettoggleallcolumnsvisibilityhandler)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
   getToggleAllColumnsVisibilityHandler: () => (event: unknown) => void
+  /**
+   * Returns a flat array of columns that are visible, including parent columns.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#getvisibleflatcolumns)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
+  getVisibleFlatColumns: () => Column<TData, unknown>[]
+  /**
+   * Returns a flat array of leaf-node columns that are visible.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#getvisibleleafcolumns)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
+  getVisibleLeafColumns: () => Column<TData, unknown>[]
+  /**
+   * Resets the column visibility state to the initial state. If `defaultState` is provided, the state will be reset to `{}`
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#resetcolumnvisibility)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
+  resetColumnVisibility: (defaultState?: boolean) => void
+  /**
+   * Sets or updates the `state.columnVisibility` state.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#setcolumnvisibility)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
+  setColumnVisibility: (updater: Updater<VisibilityState>) => void
+  /**
+   * Toggles the visibility of all columns.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#toggleallcolumnsvisible)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
+  toggleAllColumnsVisible: (value?: boolean) => void
 }
 
 export interface VisibilityColumnDef {
@@ -45,14 +106,39 @@ export interface VisibilityColumnDef {
 
 export interface VisibilityRow<TData extends RowData> {
   _getAllVisibleCells: () => Cell<TData, unknown>[]
+  /**
+   * Returns an array of cells that account for column visibility for the row.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#getvisiblecells)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
   getVisibleCells: () => Cell<TData, unknown>[]
 }
 
 export interface VisibilityColumn {
+  /**
+   * Returns whether the column can be hidden
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#getcanhide)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
   getCanHide: () => boolean
+  /**
+   * Returns whether the column is visible
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#getisvisible)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
   getIsVisible: () => boolean
-  toggleVisibility: (value?: boolean) => void
+  /**
+   * Returns a function that can be used to toggle the column visibility. This function can be used to bind to an event handler to a checkbox.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#gettogglevisibilityhandler)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
   getToggleVisibilityHandler: () => (event: unknown) => void
+  /**
+   * Toggles the visibility of the column.
+   * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-visibility#togglevisibility)
+   * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-visibility)
+   */
+  toggleVisibility: (value?: boolean) => void
 }
 
 //

package/src/filterFns.ts

@@ -69,8 +69,8 @@ const arrIncludesSome: FilterFn<any> = (
   columnId: string,
   filterValue: unknown[]
 ) => {
-  return filterValue.some(val =>
-    row.getValue<unknown[]>(columnId)?.includes(val)
+  return filterValue.some(
+    val => row.getValue<unknown[]>(columnId)?.includes(val)
   )
 }
 

package/src/types.ts

@@ -242,7 +242,7 @@ export interface IdentifiedColumnDef<TData extends RowData, TValue = unknown>
 
 export type DisplayColumnDef<
   TData extends RowData,
-  TValue = unknown
+  TValue = unknown,
 > = ColumnDefBase<TData, TValue> & ColumnIdentifiers<TData, TValue>
 
 interface GroupColumnDefBase<TData extends RowData, TValue = unknown>
@@ -252,7 +252,7 @@ interface GroupColumnDefBase<TData extends RowData, TValue = unknown>
 
 export type GroupColumnDef<
   TData extends RowData,
-  TValue = unknown
+  TValue = unknown,
 > = GroupColumnDefBase<TData, TValue> & ColumnIdentifiers<TData, TValue>
 
 interface AccessorFnColumnDefBase<TData extends RowData, TValue = unknown>
@@ -262,7 +262,7 @@ interface AccessorFnColumnDefBase<TData extends RowData, TValue = unknown>
 
 export type AccessorFnColumnDef<
   TData extends RowData,
-  TValue = unknown
+  TValue = unknown,
 > = AccessorFnColumnDefBase<TData, TValue> & ColumnIdentifiers<TData, TValue>
 
 interface AccessorKeyColumnDefBase<TData extends RowData, TValue = unknown>
@@ -273,7 +273,7 @@ interface AccessorKeyColumnDefBase<TData extends RowData, TValue = unknown>
 
 export type AccessorKeyColumnDef<
   TData extends RowData,
-  TValue = unknown
+  TValue = unknown,
 > = AccessorKeyColumnDefBase<TData, TValue> &
   Partial<ColumnIdentifiers<TData, TValue>>
 
@@ -290,7 +290,7 @@ export type ColumnDef<TData extends RowData, TValue = unknown> =
 
 export type ColumnDefResolved<
   TData extends RowData,
-  TValue = unknown
+  TValue = unknown,
 > = Partial<UnionToIntersection<ColumnDef<TData, TValue>>> & {
   accessorKey?: string
 }

package/src/utils.ts

@@ -20,7 +20,7 @@ export type IsKnown<T, Y, N> = unknown extends T ? N : Y
 
 type ComputeRange<
   N extends number,
-  Result extends Array<unknown> = []
+  Result extends Array<unknown> = [],
 > = Result['length'] extends N
   ? Result
   : ComputeRange<N, [...Result, Result['length']]>
@@ -36,7 +36,7 @@ type IsTuple<T> = T extends readonly any[] & { length: infer Length }
 // If this type is a tuple, what indices are allowed?
 type AllowedIndexes<
   Tuple extends ReadonlyArray<any>,
-  Keys extends number = never
+  Keys extends number = never,
 > = Tuple extends readonly []
   ? Keys
   : Tuple extends readonly [infer _, ...infer Tail]
@@ -62,7 +62,7 @@ export type DeepKeys<T, TDepth extends any[] = []> = TDepth['length'] extends 5
 type DeepKeysPrefix<
   T,
   TPrefix,
-  TDepth extends any[]
+  TDepth extends any[],
 > = TPrefix extends keyof T & (number | string)
   ? `${TPrefix}.${DeepKeys<T[TPrefix], [...TDepth, any]> & string}`
   : never