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

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

@@ -12,13 +12,14 @@ import type {
 // State Utils
 
 /**
- * Returns the default row pinning state.
+ * Creates the default row pinning state.
  *
- * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ * Both pinning regions start empty. Reset APIs use this value when
+ * `defaultState` is `true`.
  *
  * @example
  * ```ts
- * const initialValue = getDefaultRowPinningState()
+ * const pinning = getDefaultRowPinningState()
  * ```
  */
 export function getDefaultRowPinningState(): RowPinningState {
@@ -29,13 +30,14 @@ export function getDefaultRowPinningState(): RowPinningState {
 }
 
 /**
- * Updates the table's row pinning state slice.
+ * Routes a row pinning updater through the table's row-pinning 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 `{ top, bottom }` state or a function of the
+ * previous state, matching the instance `table.setRowPinning` behavior.
  *
  * @example
  * ```ts
- * table_setRowPinning(table, (old) => old)
+ * table_setRowPinning(table, (old) => ({ ...old, top: [rowId] }))
  * ```
  */
 export function table_setRowPinning<
@@ -49,9 +51,11 @@ export function table_setRowPinning<
 }
 
 /**
- * Resets the table's row pinning state slice.
+ * Resets `rowPinning` 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.rowPinning` when it
+ * exists. Passing `true` ignores initial state and resets to empty top/bottom
+ * arrays.
  *
  * @example
  * ```ts
@@ -76,13 +80,14 @@ export function table_resetRowPinning<
 // Table Utils
 
 /**
- * Returns is some rows pinned for the table.
+ * Checks whether any rows are pinned.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * Omit `position` to check both regions, or pass `'top'`/`'bottom'` to inspect
+ * one region.
  *
  * @example
  * ```ts
- * const value = table_getIsSomeRowsPinned(table)
+ * const hasPinnedRows = table_getIsSomeRowsPinned(table)
  * ```
  */
 export function table_getIsSomeRowsPinned<
@@ -109,36 +114,39 @@ function table_getPinnedRows<
 ): Array<Row<TFeatures, TData>> {
   const visibleRows = table.getRowModel().rows
   const pinnedRowIds = table.atoms.rowPinning?.get()?.[position] ?? []
+  const keepPinnedRows = table.options.keepPinnedRows ?? true
 
-  const rows =
-    (table.options.keepPinnedRows ?? true)
-      ? // get all rows that are pinned even if they would not be otherwise visible
-        // account for expanded parent rows, but not pagination or filtering
-        pinnedRowIds.map((rowId) => {
-          const row = table.getRow(rowId, true)
-          return row_getIsAllParentsExpanded(row) ? row : null
-        })
-      : // else get only visible rows that are pinned
-        pinnedRowIds.map(
-          (rowId) => visibleRows.find((row) => row.id === rowId)!,
-        )
-
-  const filteredRows = rows.filter((r) => !!r)
-  // Assign position property directly to preserve prototype chain
-  filteredRows.forEach((row) => {
+  const result: Array<Row<TFeatures, TData>> = []
+  for (let i = 0; i < pinnedRowIds.length; i++) {
+    const rowId = pinnedRowIds[i]!
+    let row: Row<TFeatures, TData> | undefined
+    if (keepPinnedRows) {
+      // get all rows that are pinned even if they would not be otherwise
+      // visible; account for expanded parent rows, but not pagination/filtering
+      const fullRow = table.getRow(rowId, true)
+      if (row_getIsAllParentsExpanded(fullRow)) row = fullRow
+    } else {
+      // else get only visible rows that are pinned
+      row = visibleRows.find((r) => r.id === rowId)
+    }
+    if (!row)
+      continue
+      // Assign position property directly to preserve prototype chain
     ;(row as any).position = position
-  })
-  return filteredRows
+    result.push(row)
+  }
+  return result
 }
 
 /**
- * Returns top rows for the table.
+ * Resolves the visible rows pinned to the top region.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The result follows `state.rowPinning.top` order and marks each row with
+ * `position = 'top'`.
  *
  * @example
  * ```ts
- * const value = table_getTopRows(table)
+ * const rows = table_getTopRows(table)
  * ```
  */
 export function table_getTopRows<
@@ -149,13 +157,14 @@ export function table_getTopRows<
 }
 
 /**
- * Returns bottom rows for the table.
+ * Resolves the visible rows pinned to the bottom region.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The result follows `state.rowPinning.bottom` order and marks each row with
+ * `position = 'bottom'`.
  *
  * @example
  * ```ts
- * const value = table_getBottomRows(table)
+ * const rows = table_getBottomRows(table)
  * ```
  */
 export function table_getBottomRows<
@@ -166,13 +175,14 @@ export function table_getBottomRows<
 }
 
 /**
- * Returns center rows for the table.
+ * Resolves rows that are not pinned to top or bottom.
  *
- * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ * The current row model is filtered by `state.rowPinning.top` and
+ * `state.rowPinning.bottom`.
  *
  * @example
  * ```ts
- * const value = table_getCenterRows(table)
+ * const rows = table_getCenterRows(table)
  * ```
  */
 export function table_getCenterRows<
@@ -190,13 +200,14 @@ export function table_getCenterRows<
 // Row Utils
 
 /**
- * Returns whether a row can use pin.
+ * Checks whether this row can be pinned.
  *
- * This evaluates row data, table options, and feature-specific enablement rules.
+ * `options.enableRowPinning` may be a boolean or a row predicate; it defaults
+ * to `true`.
  *
  * @example
  * ```ts
- * const value = row_getCanPin(row)
+ * const canPin = row_getCanPin(row)
  * ```
  */
 export function row_getCanPin<
@@ -211,13 +222,14 @@ export function row_getCanPin<
 }
 
 /**
- * Returns is pinned for a row.
+ * Reads this row's current pinning region.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * Rows listed in `state.rowPinning.top` return `'top'`, rows listed in
+ * `bottom` return `'bottom'`, and unpinned rows return `false`.
  *
  * @example
  * ```ts
- * const value = row_getIsPinned(row)
+ * const position = row_getIsPinned(row)
  * ```
  */
 export function row_getIsPinned<
@@ -235,13 +247,13 @@ export function row_getIsPinned<
 }
 
 /**
- * Returns pinned index for a row.
+ * Finds this row's visible index within its pinned region.
  *
- * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ * Unpinned rows return `-1`.
  *
  * @example
  * ```ts
- * const value = row_getPinnedIndex(row)
+ * const index = row_getPinnedIndex(row)
  * ```
  */
 export function row_getPinnedIndex<

package/src/features/row-selection/rowSelectionFeature.types.ts

@@ -14,18 +14,22 @@ export interface TableOptions_RowSelection<
   TData extends RowData,
 > {
   /**
-   * - 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
+   * Allows rows to be selected alongside other rows.
+   *
+   * Provide a predicate to decide per row. Defaults to `true`.
    */
   enableMultiRowSelection?: boolean | ((row: Row<TFeatures, TData>) => 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
+   * Allows rows to be selected.
+   *
+   * Provide a predicate to decide per row. Defaults to `true`.
    */
   enableRowSelection?: boolean | ((row: Row<TFeatures, TData>) => 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)
+   * Controls whether selecting a parent row also selects its subRows.
+   *
+   * Provide a predicate to decide per row. This is most useful with expanding or
+   * grouping features and defaults to `true`.
    */
   enableSubRowSelection?: boolean | ((row: Row<TFeatures, TData>) => boolean)
   /**
@@ -49,31 +53,31 @@ export interface TableOptions_RowSelection<
 
 export interface Row_RowSelection {
   /**
-   * Returns whether or not the row can multi-select.
+   * Checks whether this row can be selected alongside other rows.
    */
   getCanMultiSelect: () => boolean
   /**
-   * Returns whether or not the row can be selected.
+   * Checks whether this row can currently be selected.
    */
   getCanSelect: () => boolean
   /**
-   * Returns whether or not the row can select sub rows automatically when the parent row is selected.
+   * Checks whether selecting this row should also select its subRows.
    */
   getCanSelectSubRows: () => boolean
   /**
-   * Returns whether or not all of the row's sub rows are selected.
+   * Checks whether all selectable descendants are selected.
    */
   getIsAllSubRowsSelected: () => boolean
   /**
-   * Returns whether or not the row is selected.
+   * Checks whether this row id is selected.
    */
   getIsSelected: () => boolean
   /**
-   * Returns whether or not some of the row's sub rows are selected.
+   * Checks whether some selectable descendants are selected.
    */
   getIsSomeSelected: () => boolean
   /**
-   * Returns a handler that can be used to toggle the row.
+   * Creates a checkbox-style handler that toggles this row's selected state.
    */
   getToggleSelectedHandler: () => (event: unknown) => void
   /**
@@ -87,27 +91,27 @@ export interface Table_RowSelection<
   TData extends RowData,
 > {
   /**
-   * Returns the row model of all rows that are selected after filtering has been applied.
+   * Builds a selected-row model from rows after filtering.
    */
   getFilteredSelectedRowModel: () => RowModel<TFeatures, TData>
   /**
-   * Returns the row model of all rows that are selected after grouping has been applied.
+   * Builds a selected-row model from rows after grouping.
    */
   getGroupedSelectedRowModel: () => RowModel<TFeatures, TData>
   /**
-   * Returns whether or not all rows on the current page are selected.
+   * Checks whether every selectable row on the current page is selected.
    */
   getIsAllPageRowsSelected: () => boolean
   /**
-   * Returns whether or not all rows in the table are selected.
+   * Checks whether every selectable filtered row is selected.
    */
   getIsAllRowsSelected: () => boolean
   /**
-   * Returns whether or not any rows on the current page are selected.
+   * Checks whether the current page has a partial row selection.
    */
   getIsSomePageRowsSelected: () => boolean
   /**
-   * Returns whether or not any rows in the table are selected.
+   * Checks whether filtered rows have a partial row selection.
    */
   getIsSomeRowsSelected: () => boolean
   /**
@@ -115,23 +119,25 @@ export interface Table_RowSelection<
    */
   getPreSelectedRowModel: () => RowModel<TFeatures, TData>
   /**
-   * Returns the row model of all rows that are selected.
+   * Builds a selected-row model from the core row model.
    */
   getSelectedRowModel: () => RowModel<TFeatures, TData>
   /**
-   * Returns a handler that can be used to toggle all rows on the current page.
+   * Creates a checkbox-style handler that toggles all current-page rows.
    */
   getToggleAllPageRowsSelectedHandler: () => (event: unknown) => void
   /**
-   * Returns a handler that can be used to toggle all rows in the table.
+   * Creates a checkbox-style handler that toggles all selectable rows.
    */
   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 `{}`.
+   * Resets `rowSelection` to `initialState.rowSelection`.
+   *
+   * Pass `true` to ignore initial state and reset to `{}`.
    */
   resetRowSelection: (defaultState?: boolean) => void
   /**
-   * Sets row selection state using a value or updater.
+   * Updates row selection state with a next map or updater function.
    */
   setRowSelection: (updater: Updater<RowSelectionState>) => void
   /**