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

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

@@ -11,6 +11,16 @@ import type {
 
 // State Utils
 
+/**
+ * Returns the default row pinning state.
+ *
+ * Feature constructors use this value to initialize the table state or option defaults when no user value is provided.
+ *
+ * @example
+ * ```ts
+ * const initialValue = getDefaultRowPinningState()
+ * ```
+ */
 export function getDefaultRowPinningState(): RowPinningState {
   return {
     top: [],
@@ -18,6 +28,16 @@ export function getDefaultRowPinningState(): RowPinningState {
   }
 }
 
+/**
+ * Updates the table's row pinning state slice.
+ *
+ * The updater follows TanStack Table updater semantics and is routed through the corresponding `on*Change` option or backing atom.
+ *
+ * @example
+ * ```ts
+ * table_setRowPinning(table, (old) => old)
+ * ```
+ */
 export function table_setRowPinning<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -28,6 +48,17 @@ export function table_setRowPinning<
   table.options.onRowPinningChange?.(updater)
 }
 
+/**
+ * Resets the table's row pinning state slice.
+ *
+ * By default the reset uses `table.initialState`; when supported, a blank/default reset bypasses the saved initial value.
+ *
+ * @example
+ * ```ts
+ * table_resetRowPinning(table)
+ * table_resetRowPinning(table, true)
+ * ```
+ */
 export function table_resetRowPinning<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -44,6 +75,16 @@ export function table_resetRowPinning<
 
 // Table Utils
 
+/**
+ * Returns is some rows pinned for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getIsSomeRowsPinned(table)
+ * ```
+ */
 export function table_getIsSomeRowsPinned<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -68,28 +109,40 @@ 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.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getTopRows(table)
+ * ```
+ */
 export function table_getTopRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -97,6 +150,16 @@ export function table_getTopRows<
   return table_getPinnedRows(table, 'top')
 }
 
+/**
+ * Returns bottom rows for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getBottomRows(table)
+ * ```
+ */
 export function table_getBottomRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -104,6 +167,16 @@ export function table_getBottomRows<
   return table_getPinnedRows(table, 'bottom')
 }
 
+/**
+ * Returns center rows for the table.
+ *
+ * This reads the relevant table atoms, options, and row-model cache to derive the current table-level value.
+ *
+ * @example
+ * ```ts
+ * const value = table_getCenterRows(table)
+ * ```
+ */
 export function table_getCenterRows<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -118,6 +191,16 @@ export function table_getCenterRows<
 
 // Row Utils
 
+/**
+ * Returns whether a row can use pin.
+ *
+ * This evaluates row data, table options, and feature-specific enablement rules.
+ *
+ * @example
+ * ```ts
+ * const value = row_getCanPin(row)
+ * ```
+ */
 export function row_getCanPin<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -129,6 +212,16 @@ export function row_getCanPin<
   return enableRowPinning ?? true
 }
 
+/**
+ * Returns is pinned for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getIsPinned(row)
+ * ```
+ */
 export function row_getIsPinned<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -143,6 +236,16 @@ export function row_getIsPinned<
       : false
 }
 
+/**
+ * Returns pinned index for a row.
+ *
+ * This is the static implementation behind the matching row instance API and may read row caches or table state atoms.
+ *
+ * @example
+ * ```ts
+ * const value = row_getPinnedIndex(row)
+ * ```
+ */
 export function row_getPinnedIndex<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -159,6 +262,17 @@ export function row_getPinnedIndex<
   return visiblePinnedRowIds.indexOf(row.id)
 }
 
+/**
+ * Pins or unpins a row.
+ *
+ * Optional flags let callers include parent rows or leaf rows when updating
+ * the row pinning state.
+ *
+ * @example
+ * ```ts
+ * row_pin(row, 'top')
+ * ```
+ */
 export function row_pin<TFeatures extends TableFeatures, TData extends RowData>(
   row: Row<TFeatures, TData>,
   position: RowPinningPosition,

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

@@ -47,6 +47,11 @@ export interface RowSelectionFeatureConstructors<
   // TableState: TableState_RowSelection
 }
 
+/**
+ * Creates the stock row selection feature.
+ *
+ * The returned feature registers its state defaults, option defaults, and instance APIs so it can be included in a `tableFeatures({ ... })` call.
+ */
 export function constructRowSelectionFeature<
   TFeatures extends TableFeatures,
   TData extends RowData,
@@ -159,6 +164,9 @@ export function constructRowSelectionFeature<
 }
 
 /**
- * The Row Selection feature adds row selection state and APIs to the table and row objects.
+ * The stock row selection feature.
+ *
+ * Register this feature to add row selection state, selected row-model helpers,
+ * and table/row APIs for checkbox and bulk-selection UI.
  */
 export const rowSelectionFeature = constructRowSelectionFeature()

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

@@ -29,7 +29,9 @@ export interface TableOptions_RowSelection<
    */
   enableSubRowSelection?: boolean | ((row: Row<TFeatures, TData>) => 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.
+   * Called with an updater when row selection state changes. Pair this with
+   * `state.rowSelection` when using external state; external atoms can own the
+   * slice without this callback.
    */
   onRowSelectionChange?: OnChangeFn<RowSelectionState>
   // enableGroupingRowSelection?:
@@ -129,7 +131,7 @@ export interface Table_RowSelection<
    */
   resetRowSelection: (defaultState?: boolean) => void
   /**
-   * Sets or updates the `state.rowSelection` state.
+   * Sets row selection state using a value or updater.
    */
   setRowSelection: (updater: Updater<RowSelectionState>) => void
   /**