diff --git a/docs/api/core/cell.md b/docs/api/core/cell.md index cd14a693e1..8aa83eaabc 100644 --- a/docs/api/core/cell.md +++ b/docs/api/core/cell.md @@ -24,6 +24,14 @@ getValue: () => any Returns the value for the cell, accessed via the associated column's accessor key or accessor function. +### `renderValue` + +```tsx +renderValue: () => any +``` + +Renders the value for a cell the same as `getValue`, but will return the `renderFallbackValue` if no value is found. + ### `row` ```tsx @@ -48,8 +56,8 @@ getContext: () => { column: Column row: Row cell: Cell - getValue: () => TTValue - renderValue: () => TTValue | null + getValue: () => TTValue + renderValue: () => TTValue | null } ``` diff --git a/docs/api/core/header.md b/docs/api/core/header.md index 5aec0eef7d..feaa8cf64c 100644 --- a/docs/api/core/header.md +++ b/docs/api/core/header.md @@ -111,3 +111,133 @@ Returns the rendering context (or props) for column-based components like header ```tsx flexRender(header.column.columnDef.header, header.getContext()) ``` + +## Table API + +### `getHeaderGroups` + +```tsx +type getHeaderGroups = () => HeaderGroup[] +``` + +Returns all header groups for the table. + +### `getLeftHeaderGroups` + +```tsx +type getLeftHeaderGroups = () => HeaderGroup[] +``` + +If pinning, returns the header groups for the left pinned columns. + +### `getCenterHeaderGroups` + +```tsx +type getCenterHeaderGroups = () => HeaderGroup[] +``` + +If pinning, returns the header groups for columns that are not pinned. + +### `getRightHeaderGroups` + +```tsx +type getRightHeaderGroups = () => HeaderGroup[] +``` + +If pinning, returns the header groups for the right pinned columns. + +### `getFooterGroups` + +```tsx +type getFooterGroups = () => HeaderGroup[] +``` + +Returns all footer groups for the table. + +### `getLeftFooterGroups` + +```tsx +type getLeftFooterGroups = () => HeaderGroup[] +``` + +If pinning, returns the footer groups for the left pinned columns. + +### `getCenterFooterGroups` + +```tsx +type getCenterFooterGroups = () => HeaderGroup[] +``` + +If pinning, returns the footer groups for columns that are not pinned. + +### `getRightFooterGroups` + +```tsx +type getRightFooterGroups = () => HeaderGroup[] +``` + +If pinning, returns the footer groups for the right pinned columns. + +### `getFlatHeaders` + +```tsx +type getFlatHeaders = () => Header[] +``` + +Returns headers for all columns in the table, including parent headers. + +### `getLeftFlatHeaders` + +```tsx +type getLeftFlatHeaders = () => Header[] +``` + +If pinning, returns headers for all left pinned columns in the table, including parent headers. + +### `getCenterFlatHeaders` + +```tsx +type getCenterFlatHeaders = () => Header[] +``` + +If pinning, returns headers for all columns that are not pinned, including parent headers. + +### `getRightFlatHeaders` + +```tsx +type getRightFlatHeaders = () => Header[] +``` + +If pinning, returns headers for all right pinned columns in the table, including parent headers. + +### `getLeafHeaders` + +```tsx +type getLeafHeaders = () => Header[] +``` + +Returns headers for all leaf columns in the table, (not including parent headers). + +### `getLeftLeafHeaders` + +```tsx +type getLeftLeafHeaders = () => Header[] +``` + +If pinning, returns headers for all left pinned leaf columns in the table, (not including parent headers). + +### `getCenterLeafHeaders` + +```tsx +type getCenterLeafHeaders = () => Header[] +``` + +If pinning, returns headers for all columns that are not pinned, (not including parent headers). + +### `getRightLeafHeaders` + +```tsx +type getRightLeafHeaders = () => Header[] +``` + +If pinning, returns headers for all right pinned leaf columns in the table, (not including parent headers). diff --git a/docs/api/core/row.md b/docs/api/core/row.md index 9f6c3d7991..027dbcef02 100644 --- a/docs/api/core/row.md +++ b/docs/api/core/row.md @@ -53,11 +53,27 @@ If nested, this row's parent row id. ### `getValue` ```tsx -getValue: (columnId: string) => any +getValue: (columnId: string) => TValue ``` Returns the value from the row for a given columnId +### `renderValue` + +```tsx +renderValue: (columnId: string) => TValue +``` + +Renders the value from the row for a given columnId, but will return the `renderFallbackValue` if no value is found. + +### `getUniqueValues` + +```tsx +getUniqueValues: (columnId: string) => TValue[] +``` + +Returns a unique array of values from the row for a given columnId. + ### `subRows` ```tsx diff --git a/docs/api/features/column-visibility.md b/docs/api/features/column-visibility.md index 11b9b333dc..ad9a9cc709 100644 --- a/docs/api/features/column-visibility.md +++ b/docs/api/features/column-visibility.md @@ -82,7 +82,7 @@ Enables/disables hiding of columns. ### `getVisibleFlatColumns` ```tsx -getVisibleFlatColumns: () => Column < TData > [] +getVisibleFlatColumns: () => Column[] ``` Returns a flat array of columns that are visible, including parent columns. @@ -90,7 +90,7 @@ Returns a flat array of columns that are visible, including parent columns. ### `getVisibleLeafColumns` ```tsx -getVisibleLeafColumns: () => Column < TData > [] +getVisibleLeafColumns: () => Column[] ``` Returns a flat array of leaf-node columns that are visible. @@ -98,7 +98,7 @@ Returns a flat array of leaf-node columns that are visible. ### `getLeftVisibleLeafColumns` ```tsx -getLeftVisibleLeafColumns: () => Column < TData > [] +getLeftVisibleLeafColumns: () => Column[] ``` If column pinning, returns a flat array of leaf-node columns that are visible in the left portion of the table. @@ -106,7 +106,7 @@ If column pinning, returns a flat array of leaf-node columns that are visible in ### `getRightVisibleLeafColumns` ```tsx -getRightVisibleLeafColumns: () => Column < TData > [] +getRightVisibleLeafColumns: () => Column[] ``` If column pinning, returns a flat array of leaf-node columns that are visible in the right portion of the table. @@ -114,7 +114,7 @@ If column pinning, returns a flat array of leaf-node columns that are visible in ### `getCenterVisibleLeafColumns` ```tsx -getCenterVisibleLeafColumns: () => Column < TData > [] +getCenterVisibleLeafColumns: () => Column[] ``` If column pinning, returns a flat array of leaf-node columns that are visible in the unpinned/center portion of the table. @@ -166,3 +166,13 @@ getToggleAllColumnsVisibilityHandler: () => ((event: unknown) => void) ``` Returns a handler for toggling the visibility of all columns, meant to be bound to a `input[type=checkbox]` element. + +## Row API + +### `getVisibleCells` + +```tsx +getVisibleCells: () => Cell[] +``` + +Returns an array of cells that account for column visibility for the row. \ No newline at end of file diff --git a/docs/api/features/expanding.md b/docs/api/features/expanding.md index 6caf3dfc02..26d1ba6542 100644 --- a/docs/api/features/expanding.md +++ b/docs/api/features/expanding.md @@ -33,6 +33,14 @@ getIsExpanded: () => boolean Returns whether the row is expanded. +### `getIsAllParentsExpanded` + +```tsx +getIsAllParentsExpanded: () => boolean +``` + +Returns whether all parent rows of the row are expanded. + ### `getCanExpand` ```tsx diff --git a/docs/api/features/filters.md b/docs/api/features/filters.md index 65e8f9ff91..864fa89db6 100644 --- a/docs/api/features/filters.md +++ b/docs/api/features/filters.md @@ -213,7 +213,7 @@ Returns whether or not the column can be **column** filtered. getCanGlobalFilter: () => boolean ``` -Returns whether or not the column can be **globally** filtered. +Returns whether or not the column can be **globally** filtered. Set to `false` to disable a column from being scanned during global filtering. ### `getFilterIndex` diff --git a/docs/api/features/grouping.md b/docs/api/features/grouping.md index fc6ed273b5..dfed1777bd 100644 --- a/docs/api/features/grouping.md +++ b/docs/api/features/grouping.md @@ -184,6 +184,8 @@ Returns the automatically inferred aggregation function for the column. getAggregationFn: () => AggregationFn | undefined ``` +Returns the aggregation function for the column. + ## Row API ### `groupingColumnId` @@ -323,3 +325,29 @@ getGroupedRowModel: () => RowModel ``` Returns the row model for the table after grouping has been applied. + +## Cell API + +### `getIsAggregated` + +```tsx +getIsAggregated: () => boolean +``` + +Returns whether or not the cell is currently aggregated. + +### `getIsGrouped` + +```tsx +getIsGrouped: () => boolean +``` + +Returns whether or not the cell is currently grouped. + +### `getIsPlaceholder` + +```tsx +getIsPlaceholder: () => boolean +``` + +Returns whether or not the cell is currently a placeholder. \ No newline at end of file diff --git a/docs/api/features/pinning.md b/docs/api/features/pinning.md index 59b58bf7f3..a4d8db8121 100644 --- a/docs/api/features/pinning.md +++ b/docs/api/features/pinning.md @@ -49,7 +49,7 @@ export type RowPinningRowState = { enablePinning?: boolean ``` -Enables/disables all pinning for the table. +Enables/disables all pinning for the table. Defaults to `true`. ### `enableColumnPinning` @@ -81,7 +81,7 @@ When `false`, pinned rows will not be visible if they are filtered or paginated onColumnPinningChange?: OnChangeFn ``` -If provided, this function will be called with an `updaterFn` when `state.columnPinning` 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. +If provided, this function will be called with an `updaterFn` when `state.columnPinning` changes. This overrides the default internal state management, so you will also need to supply `state.columnPinning` from your own managed state. ### `onRowPinningChange` @@ -89,7 +89,7 @@ If provided, this function will be called with an `updaterFn` when `state.column onRowPinningChange?: OnChangeFn ``` -If provided, this function will be called with an `updaterFn` when `state.rowPinning` 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. +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. ## Column Def Options @@ -156,7 +156,7 @@ Returns whether or not any rows are pinned. Optionally specify to only check for ### `getLeftHeaderGroups` ```tsx -getLeftHeaderGroups: () => HeaderGroup < TData > [] +getLeftHeaderGroups: () => HeaderGroup[] ``` Returns the left pinned header groups for the table. @@ -164,7 +164,7 @@ Returns the left pinned header groups for the table. ### `getCenterHeaderGroups` ```tsx -getCenterHeaderGroups: () => HeaderGroup < TData > [] +getCenterHeaderGroups: () => HeaderGroup[] ``` Returns the unpinned/center header groups for the table. @@ -172,7 +172,7 @@ Returns the unpinned/center header groups for the table. ### `getRightHeaderGroups` ```tsx -getRightHeaderGroups: () => HeaderGroup < TData > [] +getRightHeaderGroups: () => HeaderGroup[] ``` Returns the right pinned header groups for the table. @@ -180,7 +180,7 @@ Returns the right pinned header groups for the table. ### `getLeftFooterGroups` ```tsx -getLeftFooterGroups: () => HeaderGroup < TData > [] +getLeftFooterGroups: () => HeaderGroup[] ``` Returns the left pinned footer groups for the table. @@ -188,7 +188,7 @@ Returns the left pinned footer groups for the table. ### `getCenterFooterGroups` ```tsx -getCenterFooterGroups: () => HeaderGroup < TData > [] +getCenterFooterGroups: () => HeaderGroup[] ``` Returns the unpinned/center footer groups for the table. @@ -196,7 +196,7 @@ Returns the unpinned/center footer groups for the table. ### `getRightFooterGroups` ```tsx -getRightFooterGroups: () => HeaderGroup < TData > [] +getRightFooterGroups: () => HeaderGroup[] ``` Returns the right pinned footer groups for the table. @@ -204,7 +204,7 @@ Returns the right pinned footer groups for the table. ### `getLeftFlatHeaders` ```tsx -getLeftFlatHeaders: () => Header < TData > [] +getLeftFlatHeaders: () => Header[] ``` Returns a flat array of left pinned headers for the table, including parent headers. @@ -212,7 +212,7 @@ Returns a flat array of left pinned headers for the table, including parent head ### `getCenterFlatHeaders` ```tsx -getCenterFlatHeaders: () => Header < TData > [] +getCenterFlatHeaders: () => Header[] ``` Returns a flat array of unpinned/center headers for the table, including parent headers. @@ -220,7 +220,7 @@ Returns a flat array of unpinned/center headers for the table, including parent ### `getRightFlatHeaders` ```tsx -getRightFlatHeaders: () => Header < TData > [] +getRightFlatHeaders: () => Header[] ``` Returns a flat array of right pinned headers for the table, including parent headers. @@ -228,7 +228,7 @@ Returns a flat array of right pinned headers for the table, including parent hea ### `getLeftLeafHeaders` ```tsx -getLeftLeafHeaders: () => Header < TData > [] +getLeftLeafHeaders: () => Header[] ``` Returns a flat array of leaf-node left pinned headers for the table. @@ -236,7 +236,7 @@ Returns a flat array of leaf-node left pinned headers for the table. ### `getCenterLeafHeaders` ```tsx -getCenterLeafHeaders: () => Header < TData > [] +getCenterLeafHeaders: () => Header[] ``` Returns a flat array of leaf-node unpinned/center headers for the table. @@ -244,7 +244,7 @@ Returns a flat array of leaf-node unpinned/center headers for the table. ### `getRightLeafHeaders` ```tsx -getRightLeafHeaders: () => Header < TData > [] +getRightLeafHeaders: () => Header[] ``` Returns a flat array of leaf-node right pinned headers for the table. @@ -252,7 +252,7 @@ Returns a flat array of leaf-node right pinned headers for the table. ### `getLeftLeafColumns` ```tsx -getLeftLeafColumns: () => Column < TData > [] +getLeftLeafColumns: () => Column[] ``` Returns all left pinned leaf columns. @@ -260,7 +260,7 @@ Returns all left pinned leaf columns. ### `getRightLeafColumns` ```tsx -getRightLeafColumns: () => Column < TData > [] +getRightLeafColumns: () => Column[] ``` Returns all right pinned leaf columns. @@ -268,7 +268,7 @@ Returns all right pinned leaf columns. ### `getCenterLeafColumns` ```tsx -getCenterLeafColumns: () => Column < TData > [] +getCenterLeafColumns: () => Column[] ``` Returns all center pinned (unpinned) leaf columns. @@ -276,7 +276,7 @@ Returns all center pinned (unpinned) leaf columns. ### `getTopRows` ```tsx -getTopRows: () => Row < TData > [] +getTopRows: () => Row[] ``` Returns all top pinned rows. @@ -284,7 +284,7 @@ Returns all top pinned rows. ### `getBottomRows` ```tsx -getBottomRows: () => Row < TData > [] +getBottomRows: () => Row[] ``` Returns all bottom pinned rows. @@ -292,7 +292,7 @@ Returns all bottom pinned rows. ### `getCenterRows` ```tsx -getCenterRows: () => Row < TData > [] +getCenterRows: () => Row[] ``` Returns all rows that are not pinned to the top or bottom. @@ -368,7 +368,7 @@ Returns the numeric pinned index of the row within a pinned row group. ### `getLeftVisibleCells` ```tsx -getLeftVisibleCells: () => Cell < TData > [] +getLeftVisibleCells: () => Cell[] ``` Returns all left pinned leaf cells in the row. @@ -376,7 +376,7 @@ Returns all left pinned leaf cells in the row. ### `getRightVisibleCells` ```tsx -getRightVisibleCells: () => Cell < TData > [] +getRightVisibleCells: () => Cell[] ``` Returns all right pinned leaf cells in the row. @@ -384,7 +384,7 @@ Returns all right pinned leaf cells in the row. ### `getCenterVisibleCells` ```tsx -getCenterVisibleCells: () => Cell < TData > [] +getCenterVisibleCells: () => Cell[] ``` Returns all center pinned (unpinned) leaf cells in the row. diff --git a/docs/api/features/row-selection.md b/docs/api/features/row-selection.md index ef38b827c0..6032f3803f 100644 --- a/docs/api/features/row-selection.md +++ b/docs/api/features/row-selection.md @@ -177,6 +177,14 @@ getIsSomeSelected: () => boolean Returns whether or not some of the row's sub rows are selected. +### `getIsAllSubRowsSelected` + +```tsx +getIsAllSubRowsSelected: () => boolean +``` + +Returns whether or not all of the row's sub rows are selected. + ### `getCanSelect` ```tsx diff --git a/docs/api/features/sorting.md b/docs/api/features/sorting.md index 1029f42b3e..33ea67166a 100644 --- a/docs/api/features/sorting.md +++ b/docs/api/features/sorting.md @@ -199,6 +199,14 @@ getIsSorted: () => false | SortDirection Returns whether this column is sorted. +### `getFirstSortDir` + +```tsx +getFirstSortDir: () => SortDirection +``` + +Returns the first direction that should be used when sorting this column. + ### `clearSorting` ```tsx @@ -285,8 +293,8 @@ enableSortingRemoval?: 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' -> ... +- 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' -> ... ### `enableMultiRemove` diff --git a/packages/react-table/src/index.tsx b/packages/react-table/src/index.tsx index c13a086a07..614cd65b5b 100755 --- a/packages/react-table/src/index.tsx +++ b/packages/react-table/src/index.tsx @@ -12,6 +12,9 @@ export type Renderable = React.ReactNode | React.ComponentType // +/** + * If rendering headers, cells, or footers with custom markup, use flexRender instead of `cell.getValue()` or `cell.renderValue()`. + */ export function flexRender( Comp: Renderable, props: TProps diff --git a/packages/table-core/src/columnHelper.ts b/packages/table-core/src/columnHelper.ts index ee2c7216bb..98ba993cdd 100644 --- a/packages/table-core/src/columnHelper.ts +++ b/packages/table-core/src/columnHelper.ts @@ -56,7 +56,7 @@ export type ColumnHelper = { ? TReturn : TAccessor extends DeepKeys ? DeepValue - : never + : never, >( accessor: TAccessor, column: TAccessor extends AccessorFn @@ -68,7 +68,7 @@ export type ColumnHelper = { } export function createColumnHelper< - TData extends RowData + TData extends RowData, >(): ColumnHelper { return { accessor: (accessor, column) => { diff --git a/packages/table-core/src/core/cell.ts b/packages/table-core/src/core/cell.ts index 3ce841f620..f84da80f7f 100644 --- a/packages/table-core/src/core/cell.ts +++ b/packages/table-core/src/core/cell.ts @@ -2,21 +2,51 @@ import { RowData, Cell, Column, Row, Table } from '../types' import { Getter, memo } from '../utils' export interface CellContext { - table: Table - column: Column - row: Row cell: Cell + column: Column getValue: Getter renderValue: Getter + row: Row + table: Table } export interface CoreCell { - id: string + /** + * The associated Column object for the cell. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/cell#column) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/cells) + */ + column: Column + /** + * Returns the rendering context (or props) for cell-based components like cells and aggregated cells. Use these props with your framework's `flexRender` utility to render these using the template of your choice: + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/cell#getcontext) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/cells) + */ + getContext: () => CellContext + /** + * Returns the value for the cell, accessed via the associated column's accessor key or accessor function. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/cell#getvalue) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/cells) + */ getValue: CellContext['getValue'] + /** + * The unique ID for the cell across the entire table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/cell#id) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/cells) + */ + id: string + /** + * Renders the value for a cell the same as `getValue`, but will return the `renderFallbackValue` if no value is found. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/cell#rendervalue) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/cells) + */ renderValue: CellContext['renderValue'] + /** + * The associated Row object for the cell. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/cell#row) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/cells) + */ row: Row - column: Column - getContext: () => CellContext } export function createCell( diff --git a/packages/table-core/src/core/column.ts b/packages/table-core/src/core/column.ts index e0b05ca0e3..fddca5afe3 100644 --- a/packages/table-core/src/core/column.ts +++ b/packages/table-core/src/core/column.ts @@ -9,14 +9,57 @@ import { import { memo } from '../utils' export interface CoreColumn { - id: string - depth: number + /** + * The resolved accessor function to use when extracting the value for the column from each row. Will only be defined if the column def has a valid accessor key or function defined. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/column#accessorfn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-defs) + */ accessorFn?: AccessorFn + /** + * The original column def used to create the column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/column#columndef) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-defs) + */ columnDef: ColumnDef + /** + * The child column (if the column is a group column). Will be an empty array if the column is not a group column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/column#columns) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-defs) + */ columns: Column[] - parent?: Column + /** + * The depth of the column (if grouped) relative to the root column def array. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/column#depth) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-defs) + */ + depth: number + /** + * Returns the flattened array of this column and all child/grand-child columns for this column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/column#getflatcolumns) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-defs) + */ getFlatColumns: () => Column[] + /** + * Returns an array of all leaf-node columns for this column. If a column has no children, it is considered the only leaf-node column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/column#getleafcolumns) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-defs) + */ getLeafColumns: () => Column[] + /** + * The resolved unique identifier for the column resolved in this priority: + - A manual `id` property from the column def + - The accessor key from the column def + - The header string from the column def + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/column#id) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-defs) + */ + id: string + /** + * The parent column for this column. Will be undefined if this is a root column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/column#parent) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-defs) + */ + parent?: Column } export function createColumn( diff --git a/packages/table-core/src/core/headers.ts b/packages/table-core/src/core/headers.ts index 81991a9f1a..3c8dc12dd6 100644 --- a/packages/table-core/src/core/headers.ts +++ b/packages/table-core/src/core/headers.ts @@ -3,51 +3,200 @@ import { memo } from '../utils' import { TableFeature } from './table' export interface CoreHeaderGroup { - id: string depth: number headers: Header[] + id: string } export interface HeaderContext { - table: Table - header: Header + /** + * An instance of a column. + */ column: Column + /** + * An instance of a header. + */ + header: Header + /** + * The table instance. + */ + table: Table } export interface CoreHeader { - id: string - index: number - depth: number - column: Column - headerGroup: HeaderGroup - subHeaders: Header[] + /** + * The col-span for the header. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#colspan) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ colSpan: number - rowSpan: number + /** + * The header's associated column object. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#column) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ + column: Column + /** + * The depth of the header, zero-indexed based. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#depth) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ + depth: number + /** + * Returns the rendering context (or props) for column-based components like headers, footers and filters. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#getcontext) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ + getContext: () => HeaderContext + /** + * Returns the leaf headers hierarchically nested under this header. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#getleafheaders) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getLeafHeaders: () => Header[] + /** + * The header's associated header group object. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#headergroup) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ + headerGroup: HeaderGroup + /** + * The unique identifier for the header. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#id) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ + id: string + /** + * The index for the header within the header group. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#index) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ + index: number + /** + * A boolean denoting if the header is a placeholder header. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#isplaceholder) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ isPlaceholder: boolean + /** + * If the header is a placeholder header, this will be a unique header ID that does not conflict with any other headers across the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#placeholderid) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ placeholderId?: string - getContext: () => HeaderContext + /** + * The row-span for the header. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#rowspan) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ + rowSpan: number + /** + * The header's hierarchical sub/child headers. Will be empty if the header's associated column is a leaf-column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/header#subheaders) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ + subHeaders: Header[] } export interface HeadersInstance { + /** + * Returns all header groups for the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getheadergroups) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getHeaderGroups: () => HeaderGroup[] + /** + * If pinning, returns the header groups for the left pinned columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getleftheadergroups) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getLeftHeaderGroups: () => HeaderGroup[] + /** + * If pinning, returns the header groups for columns that are not pinned. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getcenterheadergroups) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getCenterHeaderGroups: () => HeaderGroup[] + /** + * If pinning, returns the header groups for the right pinned columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getrightheadergroups) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getRightHeaderGroups: () => HeaderGroup[] + /** + * Returns the footer groups for the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getfootergroups) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getFooterGroups: () => HeaderGroup[] + /** + * If pinning, returns the footer groups for the left pinned columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getleftfootergroups) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getLeftFooterGroups: () => HeaderGroup[] + /** + * If pinning, returns the footer groups for columns that are not pinned. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getcenterfootergroups) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getCenterFooterGroups: () => HeaderGroup[] + /** + * If pinning, returns the footer groups for the right pinned columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getrightfootergroups) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getRightFooterGroups: () => HeaderGroup[] + /** + * Returns headers for all columns in the table, including parent headers. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getflatheaders) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getFlatHeaders: () => Header[] + /** + * If pinning, returns headers for all left pinned columns in the table, including parent headers. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getleftflatheaders) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getLeftFlatHeaders: () => Header[] + /** + * If pinning, returns headers for all columns that are not pinned, including parent headers. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getcenterflatheaders) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getCenterFlatHeaders: () => Header[] + /** + * If pinning, returns headers for all right pinned columns in the table, including parent headers. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getrightflatheaders) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getRightFlatHeaders: () => Header[] + /** + * Returns headers for all leaf columns in the table, (not including parent headers). + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getleafheaders) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getLeafHeaders: () => Header[] + /** + * If pinning, returns headers for all left pinned leaf columns in the table, (not including parent headers). + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getleftleafheaders) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getLeftLeafHeaders: () => Header[] + /** + * If pinning, returns headers for all columns that are not pinned, (not including parent headers). + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getcenterleafheaders) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getCenterLeafHeaders: () => Header[] + /** + * If pinning, returns headers for all right pinned leaf columns in the table, (not including parent headers). + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/headers#getrightleafheaders) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/headers) + */ getRightLeafHeaders: () => Header[] } diff --git a/packages/table-core/src/core/row.ts b/packages/table-core/src/core/row.ts index 7027c49c5b..0faf138f93 100644 --- a/packages/table-core/src/core/row.ts +++ b/packages/table-core/src/core/row.ts @@ -3,23 +3,93 @@ import { flattenBy, memo } from '../utils' import { createCell } from './cell' export interface CoreRow { + _getAllCellsByColumnId: () => Record> + _uniqueValuesCache: Record + _valuesCache: Record + /** + * The depth of the row (if nested or grouped) relative to the root row array. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#depth) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ + depth: number + /** + * Returns all of the cells for the row. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#getallcells) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ + getAllCells: () => Cell[] + /** + * Returns the leaf rows for the row, not including any parent rows. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#getleafrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ + getLeafRows: () => Row[] + /** + * Returns the parent row for the row, if it exists. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#getparentrow) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ + getParentRow: () => Row | undefined + /** + * Returns the parent rows for the row, all the way up to a root row. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#getparentrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ + getParentRows: () => Row[] + /** + * Returns a unique array of values from the row for a given columnId. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#getuniquevalues) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ + getUniqueValues: (columnId: string) => TValue[] + /** + * Returns the value from the row for a given columnId. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#getvalue) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ + getValue: (columnId: string) => TValue + /** + * The resolved unique identifier for the row resolved via the `options.getRowId` option. Defaults to the row's index (or relative index if it is a subRow). + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#id) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ id: string + /** + * The index of the row within its parent array (or the root data array). + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#index) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ index: number + /** + * The original row object provided to the table. If the row is a grouped row, the original row object will be the first original in the group. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#original) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ original: TData - depth: number + /** + * An array of the original subRows as returned by the `options.getSubRows` option. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#originalsubrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ + originalSubRows?: TData[] + /** + * If nested, this row's parent row id. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#parentid) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ parentId?: string - _valuesCache: Record - _uniqueValuesCache: Record - getValue: (columnId: string) => TValue - getUniqueValues: (columnId: string) => TValue[] + /** + * Renders the value for the row in a given columnId the same as `getValue`, but will return the `renderFallbackValue` if no value is found. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#rendervalue) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ renderValue: (columnId: string) => TValue + /** + * An array of subRows for the row as returned and created by the `options.getSubRows` option. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/row#subrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/rows) + */ subRows: Row[] - getLeafRows: () => Row[] - originalSubRows?: TData[] - getAllCells: () => Cell[] - _getAllCellsByColumnId: () => Record> - getParentRow: () => Row | undefined - getParentRows: () => Row[] } export const createRow = ( @@ -112,10 +182,13 @@ export const createRow = ( _getAllCellsByColumnId: memo( () => [row.getAllCells()], allCells => { - return allCells.reduce((acc, cell) => { - acc[cell.column.id] = cell - return acc - }, {} as Record>) + return allCells.reduce( + (acc, cell) => { + acc[cell.column.id] = cell + return acc + }, + {} as Record> + ) }, { key: diff --git a/packages/table-core/src/core/table.ts b/packages/table-core/src/core/table.ts index 701cb5cb7b..4b54218152 100644 --- a/packages/table-core/src/core/table.ts +++ b/packages/table-core/src/core/table.ts @@ -34,14 +34,14 @@ import { Sorting } from '../features/Sorting' import { Visibility } from '../features/Visibility' export interface TableFeature { - getDefaultOptions?: (table: any) => any - getInitialState?: (initialState?: InitialTableState) => any - createTable?: (table: any) => any - getDefaultColumnDef?: () => any + createCell?: (cell: any, column: any, row: any, table: any) => any createColumn?: (column: any, table: any) => any createHeader?: (column: any, table: any) => any - createCell?: (cell: any, column: any, row: any, table: any) => any createRow?: (row: any, table: any) => any + createTable?: (table: any) => any + getDefaultColumnDef?: () => any + getDefaultOptions?: (table: any) => any + getInitialState?: (initialState?: InitialTableState) => any } const features = [ @@ -63,50 +63,211 @@ const features = [ export interface CoreTableState {} export interface CoreOptions { + /** + * Set this option to override any of the `autoReset...` feature options. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#autoresetall) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + autoResetAll?: boolean + /** + * The array of column defs to use for the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#columns) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + columns: ColumnDef[] + /** + * The data for the table to display. This array should match the type you provided to `table.setRowType<...>`. Columns can access this data via string/index or a functional accessor. When the `data` option changes reference, the table will reprocess the data. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#data) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ data: TData[] - state: Partial - onStateChange: (updater: Updater) => void + /** + * Set this option to `true` to output all debugging information to the console. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#debugall) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ debugAll?: boolean - debugTable?: boolean - debugHeaders?: boolean + /** + * Set this option to `true` to output column debugging information to the console. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#debugcolumns) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ debugColumns?: boolean + /** + * Set this option to `true` to output header debugging information to the console. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#debugheaders) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + debugHeaders?: boolean + /** + * Set this option to `true` to output row debugging information to the console. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#debugrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ debugRows?: boolean + /** + * Set this option to `true` to output table debugging information to the console. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#debugtable) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + debugTable?: boolean + /** + * Default column options to use for all column defs supplied to the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#defaultcolumn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + defaultColumn?: Partial> + /** + * This required option is a factory for a function that computes and returns the core row model for the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#getcorerowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + getCoreRowModel: (table: Table) => () => RowModel + /** + * This optional function is used to derive a unique ID for any given row. If not provided the rows index is used (nested rows join together with `.` using their grandparents' index eg. `index.index.index`). If you need to identify individual rows that are originating from any server-side operations, it's suggested you use this function to return an ID that makes sense regardless of network IO/ambiguity eg. a userId, taskId, database ID field, etc. + * @example getRowId: row => row.userId + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#getrowid) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + getRowId?: (originalRow: TData, index: number, parent?: Row) => string + /** + * This optional function is used to access the sub rows for any given row. If you are using nested rows, you will need to use this function to return the sub rows object (or undefined) from the row. + * @example getSubRows: row => row.subRows + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#getsubrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + getSubRows?: (originalRow: TData, index: number) => undefined | TData[] + /** + * Use this option to optionally pass initial state to the table. This state will be used when resetting various table states either automatically by the table (eg. `options.autoResetPageIndex`) or via functions like `table.resetRowSelection()`. Most reset function allow you optionally pass a flag to reset to a blank/default state instead of the initial state. + * + * Table state will not be reset when this object changes, which also means that the initial state object does not need to be stable. + * + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#initialstate) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ initialState?: InitialTableState - autoResetAll?: boolean + /** + * This option is used to optionally implement the merging of table options. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#mergeoptions) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ mergeOptions?: ( defaultOptions: TableOptions, options: Partial> ) => TableOptions + /** + * You can pass any object to `options.meta` and access it anywhere the `table` is available via `table.options.meta`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#meta) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ meta?: TableMeta - getCoreRowModel: (table: Table) => () => RowModel - getSubRows?: (originalRow: TData, index: number) => undefined | TData[] - getRowId?: (originalRow: TData, index: number, parent?: Row) => string - columns: ColumnDef[] - defaultColumn?: Partial> + /** + * The `onStateChange` option can be used to optionally listen to state changes within the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#onstatechange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + onStateChange: (updater: Updater) => void + /** + * Value used when the desired value is not found in the data. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#renderfallbackvalue) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ renderFallbackValue: any + /** + * The `state` option can be used to optionally _control_ part or all of the table state. The state you pass here will merge with and overwrite the internal automatically-managed state to produce the final state for the table. You can also listen to state changes via the `onStateChange` option. + * > Note: Any state passed in here will override both the internal state and any other `initialState` you provide. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#state) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + state: Partial } export interface CoreInstance { - initialState: TableState - reset: () => void - options: RequiredKeys, 'state'> - setOptions: (newOptions: Updater>) => void - getState: () => TableState - setState: (updater: Updater) => void _features: readonly TableFeature[] - _queue: (cb: () => void) => void - _getRowId: (_: TData, index: number, parent?: Row) => string - getCoreRowModel: () => RowModel + _getAllFlatColumnsById: () => Record> + _getColumnDefs: () => ColumnDef[] _getCoreRowModel?: () => RowModel - getRowModel: () => RowModel - getRow: (id: string, searchAll?: boolean) => Row _getDefaultColumnDef: () => Partial> - _getColumnDefs: () => ColumnDef[] - _getAllFlatColumnsById: () => Record> + _getRowId: (_: TData, index: number, parent?: Row) => string + _queue: (cb: () => void) => void + /** + * Returns all columns in the table in their normalized and nested hierarchy. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#getallcolumns) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ getAllColumns: () => Column[] + /** + * Returns all columns in the table flattened to a single level. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#getallflatcolumns) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ getAllFlatColumns: () => Column[] + /** + * Returns all leaf-node columns in the table flattened to a single level. This does not include parent columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#getallleafcolumns) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ getAllLeafColumns: () => Column[] + /** + * Returns a single column by its ID. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#getcolumn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ getColumn: (columnId: string) => Column | undefined + /** + * Returns the core row model before any processing has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#getcorerowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + getCoreRowModel: () => RowModel + /** + * Returns the row with the given ID. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#getrow) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + getRow: (id: string, searchAll?: boolean) => Row + /** + * Returns the final model after all processing from other used features has been applied. This is the row model that is most commonly used for rendering. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#getrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + getRowModel: () => RowModel + /** + * Call this function to get the table's current state. It's recommended to use this function and its state, especially when managing the table state manually. It is the exact same state used internally by the table for every feature and function it provides. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#getstate) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + getState: () => TableState + /** + * This is the resolved initial state of the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#initialstate) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + initialState: TableState + /** + * A read-only reference to the table's current options. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#options) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + options: RequiredKeys, 'state'> + /** + * Call this function to reset the table state to the initial state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#reset) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + reset: () => void + /** + * This function can be used to update the table options. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#setoptions) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + setOptions: (newOptions: Updater>) => void + /** + * Call this function to update the table state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/core/table#setstate) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/tables) + */ + setState: (updater: Updater) => void } export function createTable( diff --git a/packages/table-core/src/features/ColumnSizing.ts b/packages/table-core/src/features/ColumnSizing.ts index 7265bddf98..2ddc80516a 100644 --- a/packages/table-core/src/features/ColumnSizing.ts +++ b/packages/table-core/src/features/ColumnSizing.ts @@ -13,59 +13,182 @@ export interface ColumnSizingTableState { export type ColumnSizingState = Record export interface ColumnSizingInfoState { - startOffset: null | number - startSize: null | number + columnSizingStart: [string, number][] deltaOffset: null | number deltaPercentage: null | number isResizingColumn: false | string - columnSizingStart: [string, number][] + startOffset: null | number + startSize: null | number } export type ColumnResizeMode = 'onChange' | 'onEnd' export interface ColumnSizingOptions { - enableColumnResizing?: boolean + /** + * Determines when the columnSizing state is updated. `onChange` updates the state when the user is dragging the resize handle. `onEnd` updates the state when the user releases the resize handle. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#columnresizemode) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ columnResizeMode?: ColumnResizeMode + /** + * Enables or disables column resizing for the column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#enablecolumnresizing) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + enableColumnResizing?: boolean + /** + * If provided, this function will be called with an `updaterFn` when `state.columnSizing` changes. This overrides the default internal state management, so you will also need to supply `state.columnSizing` from your own managed state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#oncolumnsizingchange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ onColumnSizingChange?: OnChangeFn + /** + * If provided, this function will be called with an `updaterFn` when `state.columnSizingInfo` changes. This overrides the default internal state management, so you will also need to supply `state.columnSizingInfo` from your own managed state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#oncolumnsizinginfochange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ onColumnSizingInfoChange?: OnChangeFn } -export interface ColumnSizingDefaultOptions { - columnResizeMode: ColumnResizeMode - onColumnSizingChange: OnChangeFn - onColumnSizingInfoChange: OnChangeFn -} +export type ColumnSizingDefaultOptions = Pick< + ColumnSizingOptions, + 'columnResizeMode' | 'onColumnSizingChange' | 'onColumnSizingInfoChange' +> export interface ColumnSizingInstance { - setColumnSizing: (updater: Updater) => void - setColumnSizingInfo: (updater: Updater) => void - resetColumnSizing: (defaultState?: boolean) => void - resetHeaderSizeInfo: (defaultState?: boolean) => void - getTotalSize: () => number - getLeftTotalSize: () => number + /** + * If pinning, returns the total size of the center portion of the table by calculating the sum of the sizes of all unpinned/center leaf-columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#getcentertotalsize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ getCenterTotalSize: () => number + /** + * Returns the total size of the left portion of the table by calculating the sum of the sizes of all left leaf-columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#getlefttotalsize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + getLeftTotalSize: () => number + /** + * Returns the total size of the right portion of the table by calculating the sum of the sizes of all right leaf-columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#getrighttotalsize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ getRightTotalSize: () => number + /** + * Returns the total size of the table by calculating the sum of the sizes of all leaf-columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#gettotalsize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + getTotalSize: () => number + /** + * Resets column sizing to its initial state. If `defaultState` is `true`, the default state for the table will be used instead of the initialValue provided to the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#resetcolumnsizing) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + resetColumnSizing: (defaultState?: boolean) => void + /** + * Resets column sizing info to its initial state. If `defaultState` is `true`, the default state for the table will be used instead of the initialValue provided to the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#resetheadersizeinfo) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + resetHeaderSizeInfo: (defaultState?: boolean) => void + /** + * Sets the column sizing state using an updater function or a value. This will trigger the underlying `onColumnSizingChange` function if one is passed to the table options, otherwise the state will be managed automatically by the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#setcolumnsizing) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + setColumnSizing: (updater: Updater) => void + /** + * Sets the column sizing info state using an updater function or a value. This will trigger the underlying `onColumnSizingInfoChange` function if one is passed to the table options, otherwise the state will be managed automatically by the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#setcolumnsizinginfo) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + setColumnSizingInfo: (updater: Updater) => void } export interface ColumnSizingColumnDef { + /** + * Enables or disables column resizing for the column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#enableresizing) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ enableResizing?: boolean - size?: number - minSize?: number + /** + * The maximum allowed size for the column + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#maxsize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ maxSize?: number + /** + * The minimum allowed size for the column + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#minsize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + minSize?: number + /** + * The desired size for the column + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#size) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + size?: number } export interface ColumnSizingColumn { - getSize: () => number - getStart: (position?: ColumnPinningPosition) => number + /** + * Returns `true` if the column can be resized. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#getcanresize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ getCanResize: () => boolean + /** + * Returns `true` if the column is currently being resized. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#getisresizing) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ getIsResizing: () => boolean + /** + * Returns the current size of the column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#getsize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + getSize: () => number + /** + * Returns the offset measurement along the row-axis (usually the x-axis for standard tables) for the header. This is effectively a sum of the offset measurements of all preceding headers. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#getstart) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + getStart: (position?: ColumnPinningPosition) => number + /** + * Resets the column to its initial size. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#resetsize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ resetSize: () => void } export interface ColumnSizingHeader { + /** + * Returns an event handler function that can be used to resize the header. It can be used as an: + * - `onMouseDown` handler + * - `onTouchStart` handler + * + * The dragging and release events are automatically handled for you. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#getresizehandler) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ + getResizeHandler: () => (event: unknown) => void + /** + * Returns the current size of the header. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#getsize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ getSize: () => number + /** + * Returns the offset measurement along the row-axis (usually the x-axis for standard tables) for the header. This is effectively a sum of the offset measurements of all preceding headers. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-sizing#getstart) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-sizing) + */ getStart: (position?: ColumnPinningPosition) => number - getResizeHandler: () => (event: unknown) => void } // diff --git a/packages/table-core/src/features/Expanding.ts b/packages/table-core/src/features/Expanding.ts index d86fafe38e..b67cec939c 100644 --- a/packages/table-core/src/features/Expanding.ts +++ b/packages/table-core/src/features/Expanding.ts @@ -10,37 +10,152 @@ export interface ExpandedTableState { } export interface ExpandedRow { - toggleExpanded: (expanded?: boolean) => void - getIsExpanded: () => boolean + /** + * Returns whether the row can be expanded. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getcanexpand) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ getCanExpand: () => boolean + /** + * Returns whether all parent rows of the row are expanded. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getisallparentsexpanded) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ getIsAllParentsExpanded: () => boolean + /** + * Returns whether the row is expanded. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getisexpanded) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ + getIsExpanded: () => boolean + /** + * Returns a function that can be used to toggle the expanded state of the row. This function can be used to bind to an event handler to a button. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#gettoggleexpandedhandler) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ getToggleExpandedHandler: () => () => void + /** + * Toggles the expanded state (or sets it if `expanded` is provided) for the row. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#toggleexpanded) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ + toggleExpanded: (expanded?: boolean) => void } export interface ExpandedOptions { - manualExpanding?: boolean - onExpandedChange?: OnChangeFn + /** + * Enable this setting to automatically reset the expanded state of the table when expanding state changes. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#autoresetexpanded) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ autoResetExpanded?: boolean + /** + * Enable/disable expanding for all rows. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#enableexpanding) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ enableExpanding?: boolean + /** + * This function is responsible for returning the expanded row model. If this function is not provided, the table will not expand rows. You can use the default exported `getExpandedRowModel` function to get the expanded row model or implement your own. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getexpandedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ getExpandedRowModel?: (table: Table) => () => RowModel + /** + * If provided, allows you to override the default behavior of determining whether a row is currently expanded. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getisrowexpanded) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ getIsRowExpanded?: (row: Row) => boolean + /** + * If provided, allows you to override the default behavior of determining whether a row can be expanded. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getrowcanexpand) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ getRowCanExpand?: (row: Row) => boolean + /** + * Enables manual row expansion. If this is set to `true`, `getExpandedRowModel` will not be used to expand rows and you would be expected to perform the expansion in your own data model. This is useful if you are doing server-side expansion. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#manualexpanding) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ + manualExpanding?: boolean + /** + * This function is called when the `expanded` table state changes. If a function is provided, you will be responsible for managing this state on your own. To pass the managed state back to the table, use the `tableOptions.state.expanded` option. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#onexpandedchange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ + onExpandedChange?: OnChangeFn + /** + * If `true` expanded rows will be paginated along with the rest of the table (which means expanded rows may span multiple pages). If `false` expanded rows will not be considered for pagination (which means expanded rows will always render on their parents page. This also means more rows will be rendered than the set page size) + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#paginateexpandedrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ paginateExpandedRows?: boolean } export interface ExpandedInstance { _autoResetExpanded: () => void - setExpanded: (updater: Updater) => void - toggleAllRowsExpanded: (expanded?: boolean) => void - resetExpanded: (defaultState?: boolean) => void + _getExpandedRowModel?: () => RowModel + /** + * Returns whether there are any rows that can be expanded. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getcansomerowsexpand) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ getCanSomeRowsExpand: () => boolean - getToggleAllRowsExpandedHandler: () => (event: unknown) => void - getIsSomeRowsExpanded: () => boolean - getIsAllRowsExpanded: () => boolean + /** + * Returns the maximum depth of the expanded rows. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getexpandeddepth) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ getExpandedDepth: () => number + /** + * Returns the row model after expansion has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getexpandedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ getExpandedRowModel: () => RowModel - _getExpandedRowModel?: () => RowModel + /** + * Returns whether all rows are currently expanded. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getisallrowsexpanded) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ + getIsAllRowsExpanded: () => boolean + /** + * Returns whether there are any rows that are currently expanded. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getissomerowsexpanded) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ + getIsSomeRowsExpanded: () => boolean + /** + * Returns the row model before expansion has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#getpreexpandedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ getPreExpandedRowModel: () => RowModel + /** + * Returns a handler that can be used to toggle the expanded state of all rows. This handler is meant to be used with an `input[type=checkbox]` element. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#gettoggleallrowsexpandedhandler) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ + getToggleAllRowsExpandedHandler: () => (event: unknown) => void + /** + * Resets the expanded state of the table to the initial state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#resetexpanded) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ + resetExpanded: (defaultState?: boolean) => void + /** + * Updates the expanded state of the table via an update function or value. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#setexpanded) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ + setExpanded: (updater: Updater) => void + /** + * Toggles the expanded state for all rows. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/expanding#toggleallrowsexpanded) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/expanding) + */ + toggleAllRowsExpanded: (expanded?: boolean) => void } // diff --git a/packages/table-core/src/features/Filters.ts b/packages/table-core/src/features/Filters.ts index 0c422b0b0d..b7c0684ec8 100644 --- a/packages/table-core/src/features/Filters.ts +++ b/packages/table-core/src/features/Filters.ts @@ -65,49 +65,196 @@ export type FilterFnOption = | FilterFn export interface FiltersColumnDef { + /** + * The filter function to use with this column. Can be the name of a built-in filter function or a custom filter function. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#filterfn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ filterFn?: FilterFnOption + /** + * Enables/disables the **column** filter for this column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#enablecolumnfilter) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ enableColumnFilter?: boolean + /** + * Enables/disables the **global** filter for this column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#enableglobalfilter) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ enableGlobalFilter?: boolean } export interface FiltersColumn { + _getFacetedMinMaxValues?: () => undefined | [number, number] + _getFacetedRowModel?: () => RowModel + _getFacetedUniqueValues?: () => Map + /** + * Returns an automatically calculated filter function for the column based off of the columns first known value. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getautofilterfn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ getAutoFilterFn: () => FilterFn | undefined - getFilterFn: () => FilterFn | undefined - setFilterValue: (updater: Updater) => void + /** + * Returns whether or not the column can be **column** filtered. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getcanfilter) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ getCanFilter: () => boolean + /** + * Returns whether or not the column can be **globally** filtered. Set to `false` to disable a column from being scanned during global filtering. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getcanglobalfilter) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ getCanGlobalFilter: () => boolean + /** + * A function that **computes and returns** a min/max tuple derived from `column.getFacetedRowModel`. Useful for displaying faceted result values. + * > ⚠️ Requires that you pass a valid `getFacetedMinMaxValues` function to `options.getFacetedMinMaxValues`. A default implementation is provided via the exported `getFacetedMinMaxValues` function. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getfacetedminmaxvalues) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + getFacetedMinMaxValues: () => undefined | [number, number] + /** + * Returns the row model with all other column filters applied, excluding its own filter. Useful for displaying faceted result counts. + * > ⚠️ Requires that you pass a valid `getFacetedRowModel` function to `options.facetedRowModel`. A default implementation is provided via the exported `getFacetedRowModel` function. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getfacetedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ getFacetedRowModel: () => RowModel - _getFacetedRowModel?: () => RowModel - getIsFiltered: () => boolean - getFilterValue: () => unknown - getFilterIndex: () => number + /** + * A function that **computes and returns** a `Map` of unique values and their occurrences derived from `column.getFacetedRowModel`. Useful for displaying faceted result values. + * > ⚠️ Requires that you pass a valid `getFacetedUniqueValues` function to `options.getFacetedUniqueValues`. A default implementation is provided via the exported `getFacetedUniqueValues` function. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getfaceteduniquevalues) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ getFacetedUniqueValues: () => Map - _getFacetedUniqueValues?: () => Map - getFacetedMinMaxValues: () => undefined | [number, number] - _getFacetedMinMaxValues?: () => undefined | [number, number] + /** + * Returns the filter function (either user-defined or automatic, depending on configuration) for the columnId specified. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getfilterfn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + getFilterFn: () => FilterFn | undefined + /** + * Returns the index (including `-1`) of the column filter in the table's `state.columnFilters` array. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getfilterindex) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + getFilterIndex: () => number + /** + * Returns the current filter value for the column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getfiltervalue) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + getFilterValue: () => unknown + /** + * Returns whether or not the column is currently filtered. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getisfiltered) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + getIsFiltered: () => boolean + /** + * A function that sets the current filter value for the column. You can pass it a value or an updater function for immutability-safe operations on existing values. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#setfiltervalue) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + setFilterValue: (updater: Updater) => void } export interface FiltersRow { + /** + * The column filters map for the row. This object tracks whether a row is passing/failing specific filters by their column ID. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#columnfilters) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ columnFilters: Record + /** + * The column filters meta map for the row. This object tracks any filter meta for a row as optionally provided during the filtering process. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#columnfiltersmeta) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ columnFiltersMeta: Record } interface FiltersOptionsBase { + /** + * Enables/disables all filtering for the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#enablefilters) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ enableFilters?: boolean - manualFiltering?: boolean + /** + * By default, filtering is done from parent rows down (so if a parent row is filtered out, all of its children will be filtered out as well). Setting this option to `true` will cause filtering to be done from leaf rows up (which means parent rows will be included so long as one of their child or grand-child rows is also included). + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#filterfromleafrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ filterFromLeafRows?: boolean - maxLeafRowFilterDepth?: number + /** + * If provided, this function is called **once** per table and should return a **new function** which will calculate and return the row model for the table when it's filtered. + * - For server-side filtering, this function is unnecessary and can be ignored since the server should already return the filtered row model. + * - For client-side filtering, this function is required. A default implementation is provided via any table adapter's `{ getFilteredRowModel }` export. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getfilteredrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ getFilteredRowModel?: (table: Table) => () => RowModel + /** + * Disables the `getFilteredRowModel` from being used to filter data. This may be useful if your table needs to dynamically support both client-side and server-side filtering. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#manualfiltering) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + manualFiltering?: boolean + /** + * By default, filtering is done for all rows (max depth of 100), no matter if they are root level parent rows or the child leaf rows of a parent row. Setting this option to `0` will cause filtering to only be applied to the root level parent rows, with all sub-rows remaining unfiltered. Similarly, setting this option to `1` will cause filtering to only be applied to child leaf rows 1 level deep, and so on. + + * This is useful for situations where you want a row's entire child hierarchy to be visible regardless of the applied filter. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#maxleafrowfilterdepth) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + maxLeafRowFilterDepth?: number // Column - onColumnFiltersChange?: OnChangeFn + /** + * Enables/disables **column** filtering for all columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#enablecolumnfilters) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ enableColumnFilters?: boolean + /** + * If provided, this function will be called with an `updaterFn` when `state.columnFilters` 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/filters#oncolumnfilterschange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + onColumnFiltersChange?: OnChangeFn // Global - globalFilterFn?: FilterFnOption - onGlobalFilterChange?: OnChangeFn + /** + * Enables/disables **global** filtering for all columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#enableglobalfilter) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ enableGlobalFilter?: boolean + /** + * If provided, this function will be called with the column and should return `true` or `false` to indicate whether this column should be used for global filtering. + * + * This is useful if the column can contain data that is not `string` or `number` (i.e. `undefined`). + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getcolumncanglobalfilter) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ getColumnCanGlobalFilter?: (column: Column) => boolean + /** + * The filter function to use for global filtering. + * - A `string` referencing a built-in filter function + * - A `string` that references a custom filter functions provided via the `tableOptions.filterFns` option + * - A custom filter function + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#globalfilterfn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + globalFilterFn?: FilterFnOption + /** + * If provided, this function will be called with an `updaterFn` when `state.globalFilter` 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/filters#onglobalfilterchange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + onGlobalFilterChange?: OnChangeFn // Faceting getFacetedRowModel?: ( @@ -137,26 +284,80 @@ export interface FiltersOptions ResolvedFilterFns {} export interface FiltersInstance { + /** + * Sets or updates the `state.columnFilters` state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#setcolumnfilters) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ setColumnFilters: (updater: Updater) => void - + /** + * Resets the **columnFilters** state to `initialState.columnFilters`, or `true` can be passed to force a default blank state reset to `[]`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#resetcolumnfilters) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ resetColumnFilters: (defaultState?: boolean) => void // Column Filters - getPreFilteredRowModel: () => RowModel - getFilteredRowModel: () => RowModel _getFilteredRowModel?: () => RowModel + /** + * Returns the row model for the table after **column** filtering has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getfilteredrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + getFilteredRowModel: () => RowModel + /** + * Returns the row model for the table before any **column** filtering has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getprefilteredrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + getPreFilteredRowModel: () => RowModel // Global Filters - setGlobalFilter: (updater: Updater) => void - resetGlobalFilter: (defaultState?: boolean) => void - getGlobalAutoFilterFn: () => FilterFn | undefined - getGlobalFilterFn: () => FilterFn | undefined - getGlobalFacetedRowModel: () => RowModel + _getGlobalFacetedMinMaxValues?: () => undefined | [number, number] _getGlobalFacetedRowModel?: () => RowModel - getGlobalFacetedUniqueValues: () => Map _getGlobalFacetedUniqueValues?: () => Map + /** + * Currently, this function returns the built-in `includesString` filter function. In future releases, it may return more dynamic filter functions based on the nature of the data provided. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getglobalautofilterfn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + getGlobalAutoFilterFn: () => FilterFn | undefined + /** + * Returns the faceted min and max values for the global filter. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getglobalfacetedminmaxvalues) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ getGlobalFacetedMinMaxValues: () => undefined | [number, number] - _getGlobalFacetedMinMaxValues?: () => undefined | [number, number] + /** + * Returns the row model for the table after **global** filtering has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getglobalfacetedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + getGlobalFacetedRowModel: () => RowModel + /** + * Returns the faceted unique values for the global filter. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getglobalfaceteduniquevalues) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + getGlobalFacetedUniqueValues: () => Map + /** + * Returns the filter function (either user-defined or automatic, depending on configuration) for the global filter. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#getglobalfilterfn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + getGlobalFilterFn: () => FilterFn | undefined + /** + * Resets the **globalFilter** state to `initialState.globalFilter`, or `true` can be passed to force a default blank state reset to `undefined`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#resetglobalfilter) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + resetGlobalFilter: (defaultState?: boolean) => void + /** + * Sets or updates the `state.globalFilter` state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/filters#setglobalfilter) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/filters) + */ + setGlobalFilter: (updater: Updater) => void } // diff --git a/packages/table-core/src/features/Grouping.ts b/packages/table-core/src/features/Grouping.ts index c333deacfb..ab1cfec5e0 100644 --- a/packages/table-core/src/features/Grouping.ts +++ b/packages/table-core/src/features/Grouping.ts @@ -35,50 +35,164 @@ export type AggregationFnOption = | AggregationFn export interface GroupingColumnDef { - aggregationFn?: AggregationFnOption + /** + * The cell to display each row for the column if the cell is an aggregate. If a function is passed, it will be passed a props object with the context of the cell and should return the property type for your adapter (the exact type depends on the adapter being used). + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#aggregatedcell) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ aggregatedCell?: ColumnDefTemplate< ReturnType['getContext']> > + /** + * The resolved aggregation function for the column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#aggregationfn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + aggregationFn?: AggregationFnOption + /** + * Enables/disables grouping for this column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#enablegrouping) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ enableGrouping?: boolean + /** + * Specify a value to be used for grouping rows on this column. If this option is not specified, the value derived from `accessorKey` / `accessorFn` will be used instead. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getgroupingvalue) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ getGroupingValue?: (row: TData) => any } export interface GroupingColumn { + /** + * Returns the aggregation function for the column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getaggregationfn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + getAggregationFn: () => AggregationFn | undefined + /** + * Returns the automatically inferred aggregation function for the column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getautoaggregationfn) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + getAutoAggregationFn: () => AggregationFn | undefined + /** + * Returns whether or not the column can be grouped. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getcangroup) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ getCanGroup: () => boolean - getIsGrouped: () => boolean + /** + * Returns the index of the column in the grouping state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getgroupedindex) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ getGroupedIndex: () => number - toggleGrouping: () => void + /** + * Returns whether or not the column is currently grouped. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getisgrouped) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + getIsGrouped: () => boolean + /** + * Returns a function that toggles the grouping state of the column. This is useful for passing to the `onClick` prop of a button. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#gettogglegroupinghandler) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ getToggleGroupingHandler: () => () => void - getAutoAggregationFn: () => AggregationFn | undefined - getAggregationFn: () => AggregationFn | undefined + /** + * Toggles the grouping state of the column. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#togglegrouping) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + toggleGrouping: () => void } export interface GroupingRow { + _groupingValuesCache: Record + /** + * Returns the grouping value for any row and column (including leaf rows). + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getgroupingvalue) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + getGroupingValue: (columnId: string) => unknown + /** + * Returns whether or not the row is currently grouped. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getisgrouped) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + getIsGrouped: () => boolean + /** + * If this row is grouped, this is the id of the column that this row is grouped by. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#groupingcolumnid) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ groupingColumnId?: string + /** + * If this row is grouped, this is the unique/shared value for the `groupingColumnId` for all of the rows in this group. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#groupingvalue) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ groupingValue?: unknown - getIsGrouped: () => boolean - getGroupingValue: (columnId: string) => unknown - _groupingValuesCache: Record } export interface GroupingCell { + /** + * Returns whether or not the cell is currently aggregated. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getisaggregated) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + getIsAggregated: () => boolean + /** + * Returns whether or not the cell is currently grouped. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getisgrouped) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ getIsGrouped: () => boolean + /** + * Returns whether or not the cell is currently a placeholder cell. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getisplaceholder) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ getIsPlaceholder: () => boolean - getIsAggregated: () => boolean } export interface ColumnDefaultOptions { - // Column - onGroupingChange: OnChangeFn enableGrouping: boolean + onGroupingChange: OnChangeFn } interface GroupingOptionsBase { - manualGrouping?: boolean - onGroupingChange?: OnChangeFn + /** + * Enables/disables grouping for the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#enablegrouping) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ enableGrouping?: boolean + /** + * Returns the row model after grouping has taken place, but no further. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getgroupedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ getGroupedRowModel?: (table: Table) => () => RowModel + /** + * Grouping 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. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#groupedcolumnmode) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ groupedColumnMode?: false | 'reorder' | 'remove' + /** + * Enables manual grouping. If this option is set to `true`, the table will not automatically group rows using `getGroupedRowModel()` and instead will expect you to manually group the rows before passing them to the table. This is useful if you are doing server-side grouping and aggregation. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#manualgrouping) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + manualGrouping?: boolean + /** + * If this function is provided, it will be called when the grouping 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.grouping` option. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#ongroupingchange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + onGroupingChange?: OnChangeFn } type ResolvedAggregationFns = keyof AggregationFns extends never @@ -96,11 +210,31 @@ export interface GroupingOptions export type GroupingColumnMode = false | 'reorder' | 'remove' export interface GroupingInstance { - setGrouping: (updater: Updater) => void - resetGrouping: (defaultState?: boolean) => void - getPreGroupedRowModel: () => RowModel - getGroupedRowModel: () => RowModel _getGroupedRowModel?: () => RowModel + /** + * Returns the row model for the table after grouping has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getgroupedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + getGroupedRowModel: () => RowModel + /** + * Returns the row model for the table before any grouping has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#getpregroupedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + getPreGroupedRowModel: () => RowModel + /** + * Resets the **grouping** state to `initialState.grouping`, or `true` can be passed to force a default blank state reset to `[]`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#resetgrouping) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + resetGrouping: (defaultState?: boolean) => void + /** + * Updates the grouping state of the table via an update function or value. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/grouping#setgrouping) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/grouping) + */ + setGrouping: (updater: Updater) => void } // diff --git a/packages/table-core/src/features/Ordering.ts b/packages/table-core/src/features/Ordering.ts index 39295762a9..80ff8287c5 100644 --- a/packages/table-core/src/features/Ordering.ts +++ b/packages/table-core/src/features/Ordering.ts @@ -12,6 +12,11 @@ export interface ColumnOrderTableState { export type ColumnOrderState = string[] export interface ColumnOrderOptions { + /** + * If provided, this function will be called with an `updaterFn` when `state.columnOrder` 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-ordering#oncolumnorderchange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-ordering) + */ onColumnOrderChange?: OnChangeFn } @@ -20,11 +25,21 @@ export interface ColumnOrderDefaultOptions { } export interface ColumnOrderInstance { - setColumnOrder: (updater: Updater) => void - resetColumnOrder: (defaultState?: boolean) => void _getOrderColumnsFn: () => ( columns: Column[] ) => Column[] + /** + * Resets the **columnOrder** state to `initialState.columnOrder`, or `true` can be passed to force a default blank state reset to `[]`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-ordering#resetcolumnorder) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-ordering) + */ + resetColumnOrder: (defaultState?: boolean) => void + /** + * Sets or updates the `state.columnOrder` state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/column-ordering#setcolumnorder) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/column-ordering) + */ + setColumnOrder: (updater: Updater) => void } // diff --git a/packages/table-core/src/features/Pagination.ts b/packages/table-core/src/features/Pagination.ts index e0ae94e713..9493902d86 100644 --- a/packages/table-core/src/features/Pagination.ts +++ b/packages/table-core/src/features/Pagination.ts @@ -16,11 +16,38 @@ export interface PaginationInitialTableState { } export interface PaginationOptions { - pageCount?: number - manualPagination?: boolean - onPaginationChange?: OnChangeFn + /** + * 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. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#autoresetpageindex) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ autoResetPageIndex?: boolean + /** + * 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. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#getpaginationrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ getPaginationRowModel?: (table: Table) => () => RowModel + /** + * Enables manual pagination. If this option is set to `true`, the table will not automatically paginate rows using `getPaginationRowModel()` 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. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#manualpagination) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + 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. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#onpaginationchange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + onPaginationChange?: OnChangeFn + /** + * When manually controlling pagination, you should supply a total `pageCount` value to the table if you know it. If you do not know how many pages there are, you can set this to `-1`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#pagecount) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + pageCount?: number } export interface PaginationDefaultOptions { @@ -29,22 +56,97 @@ export interface PaginationDefaultOptions { export interface PaginationInstance { _autoResetPageIndex: () => void - setPagination: (updater: Updater) => void - resetPagination: (defaultState?: boolean) => void - setPageIndex: (updater: Updater) => void + _getPaginationRowModel?: () => RowModel + /** + * Returns whether the table can go to the next page. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#getcannextpage) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + getCanNextPage: () => boolean + /** + * Returns whether the table can go to the previous page. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#getcanpreviouspage) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + 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. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#getpagecount) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + getPageCount: () => number + /** + * Returns an array of page options (zero-index-based) for the current page size. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#getpageoptions) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + getPageOptions: () => number[] + /** + * Returns the row model for the table after pagination has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#getpaginationrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + getPaginationRowModel: () => RowModel + /** + * Returns the row model for the table before any pagination has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#getprepaginationrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + getPrePaginationRowModel: () => RowModel + /** + * Increments the page index by one, if possible. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#nextpage) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + nextPage: () => void + /** + * Decrements the page index by one, if possible. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#previouspage) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + previousPage: () => 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. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#resetpageindex) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ resetPageIndex: (defaultState?: boolean) => void - setPageSize: (updater: Updater) => 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. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#resetpagesize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ resetPageSize: (defaultState?: boolean) => void + /** + * Resets the **pagination** state to `initialState.pagination`, or `true` can be passed to force a default blank state reset to `[]`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#resetpagination) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + resetPagination: (defaultState?: boolean) => void + /** + * Updates the page count using the provided function or value. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#setpagecount) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ setPageCount: (updater: Updater) => void - getPageOptions: () => number[] - getCanPreviousPage: () => boolean - getCanNextPage: () => boolean - previousPage: () => void - nextPage: () => void - getPrePaginationRowModel: () => RowModel - getPaginationRowModel: () => RowModel - _getPaginationRowModel?: () => RowModel - getPageCount: () => number + /** + * Updates the page index using the provided function or value in the `state.pagination.pageIndex` state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#setpageindex) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + setPageIndex: (updater: Updater) => void + /** + * Updates the page size using the provided function or value in the `state.pagination.pageSize` state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#setpagesize) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + setPageSize: (updater: Updater) => void + /** + * Sets or updates the `state.pagination` state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pagination#setpagination) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pagination) + */ + setPagination: (updater: Updater) => void } // diff --git a/packages/table-core/src/features/Pinning.ts b/packages/table-core/src/features/Pinning.ts index f2217d60dc..77e10dc2f4 100644 --- a/packages/table-core/src/features/Pinning.ts +++ b/packages/table-core/src/features/Pinning.ts @@ -19,8 +19,8 @@ export interface ColumnPinningState { } export interface RowPinningState { - top?: string[] bottom?: string[] + top?: string[] } export interface ColumnPinningTableState { @@ -32,15 +32,45 @@ export interface RowPinningTableState { } export interface ColumnPinningOptions { - onColumnPinningChange?: OnChangeFn - enablePinning?: boolean + /** + * Enables/disables column pinning for the table. Defaults to `true`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#enablecolumnpinning) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ enableColumnPinning?: boolean + /** + * Enables/disables all pinning for the table. Defaults to `true`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#enablepinning) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ + enablePinning?: boolean + /** + * If provided, this function will be called with an `updaterFn` when `state.columnPinning` changes. This overrides the default internal state management, so you will also need to supply `state.columnPinning` from your own managed state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#oncolumnpinningchange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/oncolumnpinningchange) + */ + onColumnPinningChange?: OnChangeFn } export interface RowPinningOptions { - onRowPinningChange?: OnChangeFn + /** + * Enables/disables row pinning for the table. Defaults to `true`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#enablerowpinning) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ enableRowPinning?: boolean | ((row: Row) => 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`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#keeppinnedrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ 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. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#onrowpinningchange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/onrowpinningchange) + */ + onRowPinningChange?: OnChangeFn } export interface ColumnPinningDefaultOptions { @@ -52,26 +82,86 @@ export interface RowPinningDefaultOptions { } export interface ColumnPinningColumnDef { + /** + * Enables/disables column pinning for this column. Defaults to `true`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#enablepinning-1) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ enablePinning?: boolean } export interface ColumnPinningColumn { + /** + * Returns whether or not the column can be pinned. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getcanpin) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getCanPin: () => boolean - getPinnedIndex: () => number + /** + * Returns the pinned position of the column. (`'left'`, `'right'` or `false`) + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getispinned) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getIsPinned: () => ColumnPinningPosition + /** + * Returns the numeric pinned index of the column within a pinned column group. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getpinnedindex) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ + getPinnedIndex: () => number + /** + * Pins a column to the `'left'` or `'right'`, or unpins the column to the center if `false` is passed. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#pin) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ pin: (position: ColumnPinningPosition) => void } export interface ColumnPinningRow { - getLeftVisibleCells: () => Cell[] + /** + * Returns all center pinned (unpinned) leaf cells in the row. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getcentervisiblecells) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getCenterVisibleCells: () => Cell[] + /** + * Returns all left pinned leaf cells in the row. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getleftvisiblecells) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ + getLeftVisibleCells: () => Cell[] + /** + * Returns all right pinned leaf cells in the row. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getrightvisiblecells) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getRightVisibleCells: () => Cell[] } export interface RowPinningRow { + /** + * Returns whether or not the row can be pinned. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getcanpin-1) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getCanPin: () => boolean + /** + * Returns the pinned position of the row. (`'top'`, `'bottom'` or `false`) + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getispinned-1) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getIsPinned: () => RowPinningPosition + /** + * Returns the numeric pinned index of the row within a pinned row group. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getpinnedindex-1) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getPinnedIndex: () => number + /** + * Pins a row to the `'top'` or `'bottom'`, or unpins the row to the center if `false` is passed. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#pin-1) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ pin: ( position: RowPinningPosition, includeLeafRows?: boolean, @@ -80,22 +170,82 @@ export interface RowPinningRow { } export interface ColumnPinningInstance { - setColumnPinning: (updater: Updater) => void - resetColumnPinning: (defaultState?: boolean) => void + /** + * Returns all center pinned (unpinned) leaf columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getcenterleafcolumns) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ + getCenterLeafColumns: () => Column[] + /** + * Returns whether or not any columns are pinned. Optionally specify to only check for pinned columns in either the `left` or `right` position. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getissomecolumnspinned) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getIsSomeColumnsPinned: (position?: ColumnPinningPosition) => boolean + /** + * Returns all left pinned leaf columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getleftleafcolumns) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getLeftLeafColumns: () => Column[] + /** + * Returns all right pinned leaf columns. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getrightleafcolumns) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getRightLeafColumns: () => Column[] - getCenterLeafColumns: () => Column[] + /** + * Resets the **columnPinning** state to `initialState.columnPinning`, or `true` can be passed to force a default blank state reset to `{ left: [], right: [], }`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#resetcolumnpinning) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ + resetColumnPinning: (defaultState?: boolean) => void + /** + * Sets or updates the `state.columnPinning` state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#setcolumnpinning) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ + setColumnPinning: (updater: Updater) => void } export interface RowPinningInstance { - setRowPinning: (updater: Updater) => void - resetRowPinning: (defaultState?: boolean) => void - getIsSomeRowsPinned: (position?: RowPinningPosition) => boolean _getPinnedRows: (position: 'top' | 'bottom') => Row[] - getTopRows: () => Row[] + /** + * Returns all bottom pinned rows. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getbottomrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getBottomRows: () => Row[] + /** + * Returns all rows that are not pinned to the top or bottom. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getcenterrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ getCenterRows: () => Row[] + /** + * Returns whether or not any rows are pinned. Optionally specify to only check for pinned rows in either the `top` or `bottom` position. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#getissomerowspinned) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ + getIsSomeRowsPinned: (position?: RowPinningPosition) => boolean + /** + * Returns all top pinned rows. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#gettoprows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ + getTopRows: () => Row[] + /** + * Resets the **rowPinning** state to `initialState.rowPinning`, or `true` can be passed to force a default blank state reset to `{ top: [], bottom: [], }`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#resetrowpinning) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ + resetRowPinning: (defaultState?: boolean) => void + /** + * Sets or updates the `state.rowPinning` state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/pinning#setrowpinning) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/pinning) + */ + setRowPinning: (updater: Updater) => void } // diff --git a/packages/table-core/src/features/RowSelection.ts b/packages/table-core/src/features/RowSelection.ts index 4fcf693ddc..f6e7e1ad6a 100644 --- a/packages/table-core/src/features/RowSelection.ts +++ b/packages/table-core/src/features/RowSelection.ts @@ -9,9 +9,32 @@ export interface RowSelectionTableState { } export interface RowSelectionOptions { - enableRowSelection?: boolean | ((row: Row) => boolean) + /** + * - Enables/disables multiple row selection for all rows in the table OR + * - A function that given a row, returns whether to enable/disable multiple row selection for that row's children/grandchildren + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#enablemultirowselection) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ enableMultiRowSelection?: boolean | ((row: Row) => boolean) + /** + * - Enables/disables row selection for all rows in the table OR + * - A function that given a row, returns whether to enable/disable row selection for that row + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#enablerowselection) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + enableRowSelection?: boolean | ((row: Row) => boolean) + /** + * Enables/disables automatic sub-row selection when a parent row is selected, or a function that enables/disables automatic sub-row selection for each row. + * (Use in combination with expanding or grouping features) + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#enablesubrowselection) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ enableSubRowSelection?: boolean | ((row: Row) => boolean) + /** + * If provided, this function will be called with an `updaterFn` when `state.rowSelection` 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/row-selection#onrowselectionchange) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ onRowSelectionChange?: OnChangeFn // enableGroupingRowSelection?: // | boolean @@ -27,31 +50,141 @@ export interface RowSelectionOptions { } export interface RowSelectionRow { - getIsSelected: () => boolean - getIsSomeSelected: () => boolean - getIsAllSubRowsSelected: () => boolean - getCanSelect: () => boolean + /** + * Returns whether or not the row can multi-select. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getcanmultiselect) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ getCanMultiSelect: () => boolean + /** + * Returns whether or not the row can be selected. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getcanselect) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + getCanSelect: () => boolean + /** + * Returns whether or not the row can select sub rows automatically when the parent row is selected. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getcanselectsubrows) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ getCanSelectSubRows: () => boolean - toggleSelected: (value?: boolean) => void + /** + * Returns whether or not all of the row's sub rows are selected. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getisallsubrowsselected) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + getIsAllSubRowsSelected: () => boolean + /** + * Returns whether or not the row is selected. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getisselected) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + getIsSelected: () => boolean + /** + * Returns whether or not some of the row's sub rows are selected. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getissomeselected) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + getIsSomeSelected: () => boolean + /** + * Returns a handler that can be used to toggle the row. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#gettoggleselectedhandler) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ getToggleSelectedHandler: () => (event: unknown) => void + /** + * Selects/deselects the row. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#toggleselected) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + toggleSelected: (value?: boolean) => void } export interface RowSelectionInstance { - getToggleAllRowsSelectedHandler: () => (event: unknown) => void - getToggleAllPageRowsSelectedHandler: () => (event: unknown) => void - setRowSelection: (updater: Updater) => void - resetRowSelection: (defaultState?: boolean) => void - getIsAllRowsSelected: () => boolean + /** + * Returns the row model of all rows that are selected after filtering has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getfilteredselectedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + getFilteredSelectedRowModel: () => RowModel + /** + * Returns the row model of all rows that are selected after grouping has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getgroupedselectedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + getGroupedSelectedRowModel: () => RowModel + /** + * Returns whether or not all rows on the current page are selected. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getisallpagerowsselected) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ getIsAllPageRowsSelected: () => boolean - getIsSomeRowsSelected: () => boolean + /** + * Returns whether or not all rows in the table are selected. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getisallrowsselected) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + getIsAllRowsSelected: () => boolean + /** + * Returns whether or not all rows on the current page are selected. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getissomepagerowsselected) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ getIsSomePageRowsSelected: () => boolean - toggleAllRowsSelected: (value?: boolean) => void - toggleAllPageRowsSelected: (value?: boolean) => void + /** + * Returns whether or not all rows in the table are selected. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getissomerowsselected) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + getIsSomeRowsSelected: () => boolean + /** + * Returns the core row model of all rows before row selection has been applied. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getpreselectedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ getPreSelectedRowModel: () => RowModel + /** + * Returns the row model of all rows that are selected. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#getselectedrowmodel) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ getSelectedRowModel: () => RowModel - getFilteredSelectedRowModel: () => RowModel - getGroupedSelectedRowModel: () => RowModel + /** + * Returns a handler that can be used to toggle all rows on the current page. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#gettoggleallpagerowsselectedhandler) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + getToggleAllPageRowsSelectedHandler: () => (event: unknown) => void + /** + * Returns a handler that can be used to toggle all rows in the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#gettoggleallrowsselectedhandler) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + getToggleAllRowsSelectedHandler: () => (event: unknown) => void + /** + * Resets the **rowSelection** state to the `initialState.rowSelection`, or `true` can be passed to force a default blank state reset to `{}`. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#resetrowselection) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + resetRowSelection: (defaultState?: boolean) => void + /** + * Sets or updates the `state.rowSelection` state. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#setrowselection) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + setRowSelection: (updater: Updater) => void + /** + * Selects/deselects all rows on the current page. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#toggleallpagerowsselected) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + toggleAllPageRowsSelected: (value?: boolean) => void + /** + * Selects/deselects all rows in the table. + * @link [API Docs](https://tanstack.com/table/v8/docs/api/features/row-selection#toggleallrowsselected) + * @link [Guide](https://tanstack.com/table/v8/docs/guide/row-selection) + */ + toggleAllRowsSelected: (value?: boolean) => void } // @@ -497,7 +630,7 @@ export function isSubRowSelected( table: Table ): boolean | 'some' | 'all' { if (!row.subRows?.length) return false - + let allChildrenSelected = true let someSelected = false diff --git a/packages/table-core/src/features/Sorting.ts b/packages/table-core/src/features/Sorting.ts index 7ecf7f7380..60a581109a 100644 --- a/packages/table-core/src/features/Sorting.ts +++ b/packages/table-core/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 = | SortingFn export interface SortingColumnDef { - sortingFn?: SortingFnOption - 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 + /** + * - `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 { - getAutoSortingFn: () => SortingFn + /** + * 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 + /** + * 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 + /** + * 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 + /** + * 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 - 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) => () => RowModel - 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 + /** + * 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 ResolvedSortingFns {} export interface SortingInstance { - setSorting: (updater: Updater) => void - resetSorting: (defaultState?: boolean) => void + _getSortedRowModel?: () => RowModel + /** + * 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 + /** + * 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 - _getSortedRowModel?: () => RowModel + /** + * 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) => void } // diff --git a/packages/table-core/src/features/Visibility.ts b/packages/table-core/src/features/Visibility.ts index 6942a27a8c..2deb419192 100644 --- a/packages/table-core/src/features/Visibility.ts +++ b/packages/table-core/src/features/Visibility.ts @@ -17,26 +17,87 @@ export interface VisibilityTableState { } export interface VisibilityOptions { - onColumnVisibilityChange?: OnChangeFn 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 } -export interface VisibilityDefaultOptions { - onColumnVisibilityChange: OnChangeFn -} +export type VisibilityDefaultOptions = Pick< + VisibilityOptions, + 'onColumnVisibilityChange' +> export interface VisibilityInstance { - getVisibleFlatColumns: () => Column[] - getVisibleLeafColumns: () => Column[] - getLeftVisibleLeafColumns: () => Column[] - getRightVisibleLeafColumns: () => Column[] + /** + * 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[] - setColumnVisibility: (updater: Updater) => 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[] + /** + * 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[] + /** + * 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[] + /** + * 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[] + /** + * 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) => 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 { _getAllVisibleCells: () => Cell[] + /** + * 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[] } 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 } // diff --git a/packages/table-core/src/filterFns.ts b/packages/table-core/src/filterFns.ts index df3219dd45..757a163269 100644 --- a/packages/table-core/src/filterFns.ts +++ b/packages/table-core/src/filterFns.ts @@ -69,8 +69,8 @@ const arrIncludesSome: FilterFn = ( columnId: string, filterValue: unknown[] ) => { - return filterValue.some(val => - row.getValue(columnId)?.includes(val) + return filterValue.some( + val => row.getValue(columnId)?.includes(val) ) } diff --git a/packages/table-core/src/types.ts b/packages/table-core/src/types.ts index bbc8995fa3..2a6e0a76ef 100644 --- a/packages/table-core/src/types.ts +++ b/packages/table-core/src/types.ts @@ -242,7 +242,7 @@ export interface IdentifiedColumnDef export type DisplayColumnDef< TData extends RowData, - TValue = unknown + TValue = unknown, > = ColumnDefBase & ColumnIdentifiers interface GroupColumnDefBase @@ -252,7 +252,7 @@ interface GroupColumnDefBase export type GroupColumnDef< TData extends RowData, - TValue = unknown + TValue = unknown, > = GroupColumnDefBase & ColumnIdentifiers interface AccessorFnColumnDefBase @@ -262,7 +262,7 @@ interface AccessorFnColumnDefBase export type AccessorFnColumnDef< TData extends RowData, - TValue = unknown + TValue = unknown, > = AccessorFnColumnDefBase & ColumnIdentifiers interface AccessorKeyColumnDefBase @@ -273,7 +273,7 @@ interface AccessorKeyColumnDefBase export type AccessorKeyColumnDef< TData extends RowData, - TValue = unknown + TValue = unknown, > = AccessorKeyColumnDefBase & Partial> @@ -290,7 +290,7 @@ export type ColumnDef = export type ColumnDefResolved< TData extends RowData, - TValue = unknown + TValue = unknown, > = Partial>> & { accessorKey?: string } diff --git a/packages/table-core/src/utils.ts b/packages/table-core/src/utils.ts index 21f682072e..44fa13f5fa 100755 --- a/packages/table-core/src/utils.ts +++ b/packages/table-core/src/utils.ts @@ -20,7 +20,7 @@ export type IsKnown = unknown extends T ? N : Y type ComputeRange< N extends number, - Result extends Array = [] + Result extends Array = [], > = Result['length'] extends N ? Result : ComputeRange @@ -36,7 +36,7 @@ type IsTuple = T extends readonly any[] & { length: infer Length } // If this type is a tuple, what indices are allowed? type AllowedIndexes< Tuple extends ReadonlyArray, - 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 = TDepth['length'] extends 5 type DeepKeysPrefix< T, TPrefix, - TDepth extends any[] + TDepth extends any[], > = TPrefix extends keyof T & (number | string) ? `${TPrefix}.${DeepKeys & string}` : never