@tanstack/table-core 9.0.0-alpha.47 → 9.0.0-alpha.48

package/src/features/row-expanding/rowExpandingFeature.utils.ts

@@ -9,13 +9,14 @@ import type {
 } from './rowExpandingFeature.types'
 
 /**
- * Returns the default expanded state.
+ * Creates the default expanded state.
  *
- * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ * The feature default is an empty map, meaning no rows are expanded. Reset APIs
+ * use this value when `defaultState` is `true`.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultExpandedState()
+ * const expanded = getDefaultExpandedState()
  * ```
  */
 export function getDefaultExpandedState(): ExpandedState {
@@ -23,9 +24,11 @@ export function getDefaultExpandedState(): ExpandedState {
 }
 
 /**
- * Schedules an automatic reset for expanded.
+ * Schedules an expanded-state reset after row-structure changes.
  *
- * The reset only runs when the related feature options allow automatic resets for the current table state change.
+ * The reset runs when `autoResetAll`, `autoResetExpanded`, or the default
+ * client-side expanding behavior allows it. Manual expanding opts out unless
+ * the reset options explicitly opt back in.
  *
  * @example
  * ```ts
@@ -46,13 +49,14 @@ export function table_autoResetExpanded<
 }
 
 /**
- * Updates the table's expanded state slice.
+ * Routes an expanded-state updater through the table's expanded change handler.
  *
- * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ * The updater may be `true`, a row-id map, or a function of the previous
+ * expanded state, matching the instance `table.setExpanded` behavior.
  *
  * @example
  * ```ts
- * table_setExpanded(table, (old) => old)
+ * table_setExpanded(table, (old) => ({ ...old, [rowId]: true }))
  * ```
  */
 export function table_setExpanded<
@@ -63,9 +67,11 @@ export function table_setExpanded<
 }
 
 /**
- * Toggles all rows expanded for the table.
+ * Expands or collapses every row.
  *
- * This is the table-level convenience API used by UI controls that affect many columns or rows at once.
+ * Passing `true` stores the special expanded-all state. Passing `false` stores
+ * an empty map. Omitting the value toggles based on whether all rows are
+ * currently expanded.
  *
  * @example
  * ```ts
@@ -84,9 +90,10 @@ export function table_toggleAllRowsExpanded<
 }
 
 /**
- * Resets the table's expanded state slice.
+ * Resets `expanded` to the configured initial state or feature default.
  *
- * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ * With no argument, the reset clones `table.initialState.expanded` when it
+ * exists. Passing `true` ignores initial state and resets to `{}`.
  *
  * @example
  * ```ts
@@ -105,13 +112,14 @@ export function table_resetExpanded<
 }
 
 /**
- * Returns can some rows expand for the table.
+ * Checks whether at least one pre-paginated row can expand.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Pagination is intentionally ignored so controls can reflect expandable rows
+ * that may not be on the current page.
  *
  * @example
  * ```ts
- * const value = table_getCanSomeRowsExpand(table)
+ * const canExpand = table_getCanSomeRowsExpand(table)
  * ```
  */
 export function table_getCanSomeRowsExpand<
@@ -124,13 +132,14 @@ export function table_getCanSomeRowsExpand<
 }
 
 /**
- * Returns an event handler for all rows expanded handler.
+ * Creates an event handler that toggles all rows expanded.
  *
- * The handler calls the matching table toggle API and can be attached directly to checkbox or button UI.
+ * React-style synthetic events are persisted when present before the table state
+ * is toggled.
  *
  * @example
  * ```ts
- * const value = table_getToggleAllRowsExpandedHandler(table)
+ * const onClick = table_getToggleAllRowsExpandedHandler(table)
  * ```
  */
 export function table_getToggleAllRowsExpandedHandler<
@@ -144,13 +153,13 @@ export function table_getToggleAllRowsExpandedHandler<
 }
 
 /**
- * Returns is some rows expanded for the table.
+ * Checks whether any row is expanded.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The special expanded-all value `true` counts as some rows expanded.
  *
  * @example
  * ```ts
- * const value = table_getIsSomeRowsExpanded(table)
+ * const someExpanded = table_getIsSomeRowsExpanded(table)
  * ```
  */
 export function table_getIsSomeRowsExpanded<
@@ -162,13 +171,14 @@ export function table_getIsSomeRowsExpanded<
 }
 
 /**
- * Returns is all rows expanded for the table.
+ * Checks whether every row in the current row model is expanded.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The special expanded-all value `true` returns true immediately. Empty
+ * expanded state returns false.
  *
  * @example
  * ```ts
- * const value = table_getIsAllRowsExpanded(table)
+ * const allExpanded = table_getIsAllRowsExpanded(table)
  * ```
  */
 export function table_getIsAllRowsExpanded<
@@ -196,13 +206,14 @@ export function table_getIsAllRowsExpanded<
 }
 
 /**
- * Returns expanded depth for the table.
+ * Computes the deepest expanded row id depth.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Row ids are split on `.`; expanded-all state scans the current row model,
+ * while explicit expanded state scans its expanded id keys.
  *
  * @example
  * ```ts
- * const value = table_getExpandedDepth(table)
+ * const depth = table_getExpandedDepth(table)
  * ```
  */
 export function table_getExpandedDepth<
@@ -225,9 +236,11 @@ export function table_getExpandedDepth<
 }
 
 /**
- * Toggles expanded for a row.
+ * Expands or collapses this row.
  *
- * The update is routed through the table state updater for the owning feature state slice.
+ * Omitting `expanded` toggles the row. If the current state is expanded-all,
+ * the function first materializes that state into a row-id map before applying
+ * the row-specific change.
  *
  * @example
  * ```ts
@@ -270,13 +283,14 @@ export function row_toggleExpanded<
 }
 
 /**
- * Returns is expanded for a row.
+ * Checks whether this row is expanded.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * `options.getIsRowExpanded` can override state-derived behavior. Otherwise
+ * the row is expanded when expanded state is `true` or contains this row id.
  *
  * @example
  * ```ts
- * const value = row_getIsExpanded(row)
+ * const expanded = row_getIsExpanded(row)
  * ```
  */
 export function row_getIsExpanded<
@@ -292,13 +306,14 @@ export function row_getIsExpanded<
 }
 
 /**
- * Returns whether a row can use expand.
+ * Checks whether this row can be expanded.
  *
- * This evaluates row data, table options, and feature-specific enablement rules.
+ * `options.getRowCanExpand` wins when provided. Otherwise rows can expand when
+ * expanding is enabled and the row has subRows.
  *
  * @example
  * ```ts
- * const value = row_getCanExpand(row)
+ * const canExpand = row_getCanExpand(row)
  * ```
  */
 export function row_getCanExpand<
@@ -312,13 +327,13 @@ export function row_getCanExpand<
 }
 
 /**
- * Returns is all parents expanded for a row.
+ * Checks whether every ancestor of this row is expanded.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * The current row is not considered; only its parent chain is walked.
  *
  * @example
  * ```ts
- * const value = row_getIsAllParentsExpanded(row)
+ * const parentsExpanded = row_getIsAllParentsExpanded(row)
  * ```
  */
 export function row_getIsAllParentsExpanded<
@@ -337,13 +352,13 @@ export function row_getIsAllParentsExpanded<
 }
 
 /**
- * Returns an event handler for toggling expanded handler.
+ * Creates a row control handler that toggles this row's expanded state.
  *
- * The handler is intended for direct use in row-level controls such as expansion or selection buttons.
+ * The handler is a no-op when the row cannot expand.
  *
  * @example
  * ```ts
- * const value = row_getToggleExpandedHandler(row)
+ * const onClick = row_getToggleExpandedHandler(row)
  * ```
  */
 export function row_getToggleExpandedHandler<

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

@@ -47,23 +47,26 @@ export interface Table_RowPagination<
 > {
   _autoResetPageIndex: () => void
   /**
-   * Returns whether the table can go to the next page.
+   * Checks whether the current page index can move forward.
    */
   getCanNextPage: () => boolean
   /**
-   * Returns whether the table can go to the previous page.
+   * Checks whether the current page index can move backward.
    */
   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.
+   * Resolves the current page count from `options.pageCount` or row count and
+   * page size.
    */
   getPageCount: () => number
   /**
-   * Returns the row count. If manually paginating or controlling the pagination state, this will come directly from the `options.rowCount` table option, otherwise it will be calculated from the table data.
+   * Resolves the row count used for pagination math.
+   *
+   * `options.rowCount` wins; otherwise the pre-paginated row model is counted.
    */
   getRowCount: () => number
   /**
-   * Returns an array of page options (zero-index-based) for the current page size.
+   * Builds zero-based page indexes for the current page count.
    */
   getPageOptions: () => Array<number>
   /**
@@ -83,16 +86,20 @@ export interface Table_RowPagination<
    */
   lastPage: () => void
   /**
-   * Resets the page index to its initial state. If `defaultState` is `true`, the page index will be reset to `0` regardless of initial state.
+   * Resets `pagination.pageIndex` to initial state, or to `0` when
+   * `defaultState` is `true`.
    */
   resetPageIndex: (defaultState?: boolean) => void
   /**
-   * Resets the page size to its initial state. If `defaultState` is `true`, the page size will be reset to `10` regardless of initial state.
+   * Resets `pagination.pageSize` to initial state, or to `10` when
+   * `defaultState` is `true`.
    */
   resetPageSize: (defaultState?: boolean) => void
   /**
-   * Resets pagination state to `initialState.pagination`. Pass `true` to reset
-   * to the feature default of `{ pageIndex: 0, pageSize: 10 }`.
+   * Resets `pagination` to `initialState.pagination`.
+   *
+   * Pass `true` to ignore initial state and reset to
+   * `{ pageIndex: 0, pageSize: 10 }`.
    */
   resetPagination: (defaultState?: boolean) => void
   /**
@@ -104,7 +111,7 @@ export interface Table_RowPagination<
    */
   setPageSize: (updater: Updater<number>) => void
   /**
-   * Sets pagination state using a value or updater.
+   * Updates pagination state with a next state or updater function.
    */
   setPagination: (updater: Updater<PaginationState>) => void
 }
@@ -114,11 +121,11 @@ export interface Table_RowModels_Paginated<
   TData extends RowData,
 > {
   /**
-   * Returns the row model for the table after pagination has been applied.
+   * Resolves the row model after pagination has sliced the current page.
    */
   getPaginatedRowModel: () => RowModel<TFeatures, TData>
   /**
-   * Returns the row model for the table before any pagination has been applied.
+   * Reads the row model immediately before pagination.
    */
   getPrePaginatedRowModel: () => RowModel<TFeatures, TData>
 }

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

@@ -8,13 +8,14 @@ const defaultPageIndex = 0
 const defaultPageSize = 10
 
 /**
- * Returns the default pagination state.
+ * Creates the default pagination state used by the pagination feature.
  *
- * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ * The feature default starts at the first page with a page size of 10. Reset
+ * APIs use this value when `defaultState` is `true`.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultPaginationState()
+ * const pagination = getDefaultPaginationState()
  * ```
  */
 export function getDefaultPaginationState(): PaginationState {
@@ -25,9 +26,11 @@ export function getDefaultPaginationState(): PaginationState {
 }
 
 /**
- * Schedules an automatic reset for page index.
+ * Resets the page index when a page-altering change should return to page 0.
  *
- * The reset only runs when the related feature options allow automatic resets for the current table state change.
+ * The reset runs when `autoResetAll`, `autoResetPageIndex`, or the default
+ * client-side pagination behavior allows it. Manual pagination opts out unless
+ * the reset options explicitly opt back in.
  *
  * @example
  * ```ts
@@ -48,9 +51,11 @@ export function table_autoResetPageIndex<
 }
 
 /**
- * Updates the table's pagination state slice.
+ * Routes a pagination updater through the table's pagination change handler.
  *
- * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ * The updater may be a next state object or a function of the previous
+ * `PaginationState`; controlled state and external atoms observe the same
+ * updater path as the instance API.
  *
  * @example
  * ```ts
@@ -71,9 +76,11 @@ export function table_setPagination<
 }
 
 /**
- * Resets the table's pagination state slice.
+ * Resets `pagination` to the configured initial state or feature default.
  *
- * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ * With no argument, the reset clones `table.initialState.pagination` when it
+ * exists. Passing `true` ignores initial state and resets to
+ * `{ pageIndex: 0, pageSize: 10 }`.
  *
  * @example
  * ```ts
@@ -96,9 +103,10 @@ export function table_resetPagination<
 }
 
 /**
- * Updates the table's page index state slice.
+ * Updates `pagination.pageIndex` and clamps it to the known page range.
  *
- * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ * Unknown page counts (`undefined` or `-1`) allow any non-negative page index.
+ * Known page counts clamp the index between `0` and `pageCount - 1`.
  *
  * @example
  * ```ts
@@ -128,9 +136,10 @@ export function table_setPageIndex<
 }
 
 /**
- * Resets the table's page index state slice.
+ * Resets only `pagination.pageIndex`.
  *
- * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ * With no argument, the reset uses `table.initialState.pagination?.pageIndex`
+ * or `0`. Passing `true` always resets the page index to `0`.
  *
  * @example
  * ```ts
@@ -152,9 +161,10 @@ export function table_resetPageIndex<
 }
 
 /**
- * Resets the table's page size state slice.
+ * Resets only `pagination.pageSize`.
  *
- * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ * With no argument, the reset uses `table.initialState.pagination?.pageSize`
+ * or `10`. Passing `true` always resets the page size to `10`.
  *
  * @example
  * ```ts
@@ -176,9 +186,10 @@ export function table_resetPageSize<
 }
 
 /**
- * Updates the table's page size state slice.
+ * Updates `pagination.pageSize` while preserving the current top row.
  *
- * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ * The new size is clamped to at least `1`, and `pageIndex` is recalculated so
+ * the row that was previously at the top of the page remains in view.
  *
  * @example
  * ```ts
@@ -203,13 +214,14 @@ export function table_setPageSize<
 }
 
 /**
- * Returns page options for the table.
+ * Builds the zero-based page indexes available for the current page count.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Unknown or empty page counts return an empty array; otherwise the result is
+ * `[0, 1, ...pageCount - 1]`.
  *
  * @example
  * ```ts
- * const value = table_getPageOptions(table)
+ * const pageIndexes = table_getPageOptions(table)
  * ```
  */
 export function table_getPageOptions<
@@ -225,13 +237,14 @@ export function table_getPageOptions<
 }
 
 /**
- * Returns can previous page for the table.
+ * Checks whether the current page index can move backward.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The first page is page index `0`, so only positive page indexes can navigate
+ * to a previous page.
  *
  * @example
  * ```ts
- * const value = table_getCanPreviousPage(table)
+ * const canGoBack = table_getCanPreviousPage(table)
  * ```
  */
 export function table_getCanPreviousPage<
@@ -242,13 +255,14 @@ export function table_getCanPreviousPage<
 }
 
 /**
- * Returns can next page for the table.
+ * Checks whether the current page index can move forward.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * A `pageCount` of `-1` means the caller does not know the total page count, so
+ * this returns `true`. A page count of `0` returns `false`.
  *
  * @example
  * ```ts
- * const value = table_getCanNextPage(table)
+ * const canGoForward = table_getCanNextPage(table)
  * ```
  */
 export function table_getCanNextPage<
@@ -343,13 +357,14 @@ export function table_lastPage<
 }
 
 /**
- * Returns page count for the table.
+ * Resolves the number of pages for the current pagination state.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * `options.pageCount` wins for manual pagination. Otherwise the value is
+ * calculated from `table_getRowCount(table)` and the current `pageSize`.
  *
  * @example
  * ```ts
- * const value = table_getPageCount(table)
+ * const pages = table_getPageCount(table)
  * ```
  */
 export function table_getPageCount<
@@ -366,13 +381,15 @@ export function table_getPageCount<
 }
 
 /**
- * Returns row count for the table.
+ * Resolves the total row count used for pagination math.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * `options.rowCount` wins for manual pagination. Otherwise the count comes
+ * from the pre-paginated row model so filtering, grouping, sorting, and
+ * expansion are reflected before the page slice is applied.
  *
  * @example
  * ```ts
- * const value = table_getRowCount(table)
+ * const rows = table_getRowCount(table)
  * ```
  */
 export function table_getRowCount<

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

@@ -18,7 +18,9 @@ export interface TableOptions_RowPinning<
   TData extends RowData,
 > {
   /**
-   * Enables/disables row pinning for the table. Defaults to `true`.
+   * Allows rows to be pinned to top or bottom regions.
+   *
+   * Provide a predicate to decide per row. Defaults to `true`.
    */
   enableRowPinning?: boolean | ((row: Row<TFeatures, TData>) => boolean)
   /**
@@ -39,7 +41,7 @@ export interface RowPinningDefaultOptions {
 
 export interface Row_RowPinning {
   /**
-   * Returns whether or not the row can be pinned.
+   * Checks whether this row can be pinned.
    */
   getCanPin: () => boolean
   /**
@@ -65,27 +67,29 @@ export interface Table_RowPinning<
   TData extends RowData,
 > {
   /**
-   * Returns all bottom pinned rows.
+   * Gets rows pinned to the bottom region.
    */
   getBottomRows: () => Array<Row<TFeatures, TData>>
   /**
-   * Returns all rows that are not pinned to the top or bottom.
+   * Gets rows that are not pinned to the top or bottom region.
    */
   getCenterRows: () => Array<Row<TFeatures, TData>>
   /**
-   * Returns whether or not any rows are pinned. Optionally specify to only check for pinned rows in either the `top` or `bottom` position.
+   * Checks whether any rows are pinned, optionally limited to one region.
    */
   getIsSomeRowsPinned: (position?: RowPinningPosition) => boolean
   /**
-   * Returns all top pinned rows.
+   * Gets rows pinned to the top region.
    */
   getTopRows: () => Array<Row<TFeatures, TData>>
   /**
-   * Resets the **rowPinning** state to `initialState.rowPinning`, or `true` can be passed to force a default blank state reset to `{ top: [], bottom: [], }`.
+   * Resets `rowPinning` to `initialState.rowPinning`.
+   *
+   * Pass `true` to ignore initial state and reset to empty top/bottom arrays.
    */
   resetRowPinning: (defaultState?: boolean) => void
   /**
-   * Sets row pinning state using a value or updater.
+   * Updates row pinning state with a next state or updater function.
    */
   setRowPinning: (updater: Updater<RowPinningState>) => void
 }