@tanstack/table-core 9.0.0-alpha.8 → 9.0.0-beta.2

package/src/fns/sortFns.ts

@@ -0,0 +1,218 @@
+import type { RowData } from '../types/type-utils'
+import type { TableFeatures } from '../types/TableFeatures'
+import type { Row } from '../types/Row'
+import type { SortFn } from '../features/row-sorting/rowSortingFeature.types'
+
+/**
+ * Regular expression used to split mixed text and numeric chunks.
+ *
+ * The alphanumeric sort functions use these chunks for natural sorting of
+ * strings like `item2` before `item10`.
+ */
+export const reSplitAlphaNumeric = /([0-9]+)/gm
+
+/**
+ * Sorts rows with the built-in alphanumeric strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_alphanumeric: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
+  return compareAlphanumeric(
+    toString(rowA.getValue(columnId)).toLowerCase(),
+    toString(rowB.getValue(columnId)).toLowerCase(),
+  )
+}
+
+/**
+ * Sorts rows with the built-in alphanumeric case sensitive strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_alphanumericCaseSensitive: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
+  return compareAlphanumeric(
+    toString(rowA.getValue(columnId)),
+    toString(rowB.getValue(columnId)),
+  )
+}
+
+// The text filter is more basic (less numeric support)
+// but is much faster
+/**
+ * Sorts rows with the built-in text strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_text: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
+  return compareBasic(
+    toString(rowA.getValue(columnId)).toLowerCase(),
+    toString(rowB.getValue(columnId)).toLowerCase(),
+  )
+}
+
+// The text filter is more basic (less numeric support)
+// but is much faster
+/**
+ * Sorts rows with the built-in text case sensitive strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_textCaseSensitive: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
+  return compareBasic(
+    toString(rowA.getValue(columnId)),
+    toString(rowB.getValue(columnId)),
+  )
+}
+
+/**
+ * Sorts rows with the built-in datetime strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_datetime: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
+  const a: number | string = rowA.getValue(columnId)
+  const b: number | string = rowB.getValue(columnId)
+
+  // Can handle nullish values
+  // Use > and < because == (and ===) doesn't work with
+  // Date objects (would require calling getTime()).
+  return a > b ? 1 : a < b ? -1 : 0
+}
+
+/**
+ * Sorts rows with the built-in basic strategy.
+ *
+ * This comparator returns ascending-order results; descending order is applied by the sorting row model.
+ */
+export const sortFn_basic: SortFn<any, any> = <
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  rowA: Row<any, any>,
+  rowB: Row<any, any>,
+  columnId: string,
+) => {
+  return compareBasic(rowA.getValue(columnId), rowB.getValue(columnId))
+}
+
+// Utils
+
+function compareBasic(a: any, b: any) {
+  return a === b ? 0 : a > b ? 1 : -1
+}
+
+function toString(a: any) {
+  if (typeof a === 'number') {
+    if (isNaN(a) || a === Infinity || a === -Infinity) {
+      return ''
+    }
+    return String(a)
+  }
+  if (typeof a === 'string') {
+    return a
+  }
+  return ''
+}
+
+// Mixed sorting is slow, but very inclusive of many edge cases.
+// It handles numbers, mixed alphanumeric combinations, and even
+// null, undefined, and Infinity
+function compareAlphanumeric(aStr: string, bStr: string) {
+  // Split on number groups, but keep the delimiter
+  // Then remove falsey split values
+  const a = aStr.split(reSplitAlphaNumeric).filter(Boolean)
+  const b = bStr.split(reSplitAlphaNumeric).filter(Boolean)
+
+  let ai = 0
+  let bi = 0
+  const aLen = a.length
+  const bLen = b.length
+
+  while (ai < aLen && bi < bLen) {
+    const aa = a[ai++]!
+    const bb = b[bi++]!
+
+    const an = parseInt(aa, 10)
+    const bn = parseInt(bb, 10)
+
+    const combo = [an, bn].sort()
+
+    // Both are string
+    if (isNaN(combo[0]!)) {
+      if (aa > bb) {
+        return 1
+      }
+      if (bb > aa) {
+        return -1
+      }
+      continue
+    }
+
+    // One is a string, one is a number
+    if (isNaN(combo[1]!)) {
+      return isNaN(an) ? -1 : 1
+    }
+
+    // Both are numbers
+    if (an > bn) {
+      return 1
+    }
+    if (bn > an) {
+      return -1
+    }
+  }
+
+  return aLen - ai - (bLen - bi)
+}
+
+// Exports
+
+/**
+ * The built-in sorting function registry.
+ *
+ * Pass this object to sorted row model creation or extend it with custom sorting functions.
+ */
+export const sortFns = {
+  alphanumeric: sortFn_alphanumeric,
+  alphanumericCaseSensitive: sortFn_alphanumericCaseSensitive,
+  basic: sortFn_basic,
+  datetime: sortFn_datetime,
+  text: sortFn_text,
+  textCaseSensitive: sortFn_textCaseSensitive,
+}
+
+export type BuiltInSortFn = keyof typeof sortFns

package/src/helpers/columnHelper.ts

@@ -0,0 +1,122 @@
+import type { DeepKeys, DeepValue, RowData } from '../types/type-utils'
+import type { TableFeatures } from '../types/TableFeatures'
+import type {
+  AccessorFn,
+  AccessorFnColumnDef,
+  AccessorKeyColumnDef,
+  ColumnDef,
+  DisplayColumnDef,
+  GroupColumnDef,
+  IdentifiedColumnDef,
+} from '../types/ColumnDef'
+
+export type ColumnHelper<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+> = {
+  /**
+   * Creates a data column definition with an accessor key or function to extract the cell value.
+   * @example
+   * ```ts
+   * helper.accessor('firstName', { cell: (info) => info.getValue() })
+   * helper.accessor((row) => row.lastName, { id: 'lastName' })
+   * ```
+   */
+  accessor: <
+    TAccessor extends AccessorFn<TData> | DeepKeys<TData>,
+    TValue extends TAccessor extends AccessorFn<TData, infer TReturn>
+      ? TReturn
+      : TAccessor extends DeepKeys<TData>
+        ? DeepValue<TData, TAccessor>
+        : never,
+  >(
+    accessor: TAccessor,
+    column: TAccessor extends AccessorFn<TData>
+      ? DisplayColumnDef<TFeatures, TData, TValue>
+      : IdentifiedColumnDef<TFeatures, TData, TValue>,
+  ) => TAccessor extends AccessorFn<TData>
+    ? AccessorFnColumnDef<TFeatures, TData, TValue>
+    : AccessorKeyColumnDef<TFeatures, TData, TValue>
+  /**
+   * Wraps an array of column definitions to preserve each column's individual TValue type.
+   * Uses variadic tuple types to infer element types before checking constraints, preventing type widening.
+   * @example
+   * ```ts
+   * helper.columns([helper.accessor('firstName', {}), helper.accessor('age', {})])
+   * ```
+   */
+  columns: <TColumns extends ReadonlyArray<ColumnDef<TFeatures, TData, any>>>(
+    columns: [...TColumns],
+  ) => Array<ColumnDef<TFeatures, TData, any>> & [...TColumns]
+  /**
+   * Creates a display column definition for non-data columns like actions or row selection.
+   * @example
+   * ```ts
+   * helper.display({ id: 'actions', header: 'Actions', cell: () => <button>Edit</button> })
+   * ```
+   */
+  display: (
+    column: DisplayColumnDef<TFeatures, TData>,
+  ) => DisplayColumnDef<TFeatures, TData, unknown>
+  /**
+   * Creates a group column definition that contains nested child columns.
+   * @example
+   * ```ts
+   * helper.group({
+   *   id: 'name',
+   *   header: 'Name',
+   *   columns: helper.columns([
+   *     helper.accessor('firstName', {}),
+   *     helper.accessor('lastName', { id: 'lastName' }),
+   *   ]),
+   * })
+   * ```
+   */
+  group: (
+    column: GroupColumnDef<TFeatures, TData, unknown>,
+  ) => GroupColumnDef<TFeatures, TData, unknown>
+}
+
+/**
+ * Creates helper functions for authoring column definitions with stronger value
+ * inference.
+ *
+ * `accessor` infers `TValue` from an accessor key or accessor function,
+ * `display` creates non-data columns, `group` creates parent columns, and
+ * `columns` preserves tuple-level value types for arrays. At runtime these
+ * helpers only return column definition objects.
+ *
+ * @example
+ * ```tsx
+ * const helper = createColumnHelper<typeof features, Person>() // features is the result of `tableFeatures({})` helper
+ * const columns = [
+ *  helper.display({ id: 'actions', header: 'Actions' }),
+ *  helper.accessor('firstName', {}),
+ *  helper.accessor((row) => row.lastName, { id: 'lastName' }),
+ * ]
+ * ```
+ */
+export function createColumnHelper<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): ColumnHelper<TFeatures, TData> {
+  return {
+    accessor: (accessor, column) => {
+      return typeof accessor === 'function'
+        ? ({
+            ...column,
+            accessorFn: accessor,
+          } as any)
+        : {
+            ...column,
+            accessorKey: accessor,
+          }
+    },
+    columns: <TColumns extends ReadonlyArray<ColumnDef<TFeatures, TData, any>>>(
+      columns: [...TColumns],
+    ): Array<ColumnDef<TFeatures, TData, any>> & [...TColumns] =>
+      columns as Array<ColumnDef<TFeatures, TData, any>> & [...TColumns],
+    display: (column) => column,
+    group: (column) => column,
+  }
+}

package/src/helpers/tableFeatures.ts

@@ -0,0 +1,24 @@
+import type { TableFeatures } from '../types/TableFeatures'
+
+/**
+ * A helper function to help define the features that are to be imported and applied to a table instance.
+ * Use this utility to make it easier to have the correct type inference for the features that are being imported.
+ * **Note:** It is recommended to use this utility statically outside of a component.
+ * @example
+ * ```
+ * import { tableFeatures, columnVisibilityFeature, rowPinningFeature } from '@tanstack/react-table'
+ * const features = tableFeatures({ columnVisibilityFeature, rowPinningFeature });
+ * const table = useTable({ features, rowModels: {}, columns, data });
+ * ```
+ */
+export function tableFeatures<TFeatures extends TableFeatures>(
+  features: TFeatures,
+): TFeatures {
+  return features
+}
+
+// test
+
+// const features = tableFeatures({
+//   rowPinningFeature: {},
+// });

package/src/helpers/tableOptions.ts

@@ -0,0 +1,117 @@
+import type { RowData } from '../types/type-utils'
+import type { TableFeatures } from '../types/TableFeatures'
+import type { TableOptions } from '../types/TableOptions'
+
+/**
+ * Preserves table option inference when reusable options omit `columns`.
+ *
+ * This is useful for composing shared options that will receive columns later
+ * from a framework adapter or table factory.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'columns'> & {
+    features: TFeatures
+  },
+): Omit<TableOptions<TFeatures, TData>, 'columns' | 'features'> & {
+  features: TFeatures
+}
+
+/**
+ * Preserves table option inference when reusable options omit `data`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'data'> & {
+    features: TFeatures
+  },
+): Omit<TableOptions<TFeatures, TData>, 'data' | 'features'> & {
+  features: TFeatures
+}
+
+/**
+ * Preserves table option inference when reusable options omit both `data` and
+ * `columns`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'data' | 'columns'> & {
+    features: TFeatures
+  },
+): Omit<TableOptions<TFeatures, TData>, 'data' | 'columns' | 'features'> & {
+  features: TFeatures
+}
+
+/**
+ * Preserves inference for a fully specified table options object.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(options: TableOptions<TFeatures, TData>): TableOptions<TFeatures, TData>
+
+/**
+ * Preserves inference when a wrapper supplies `features`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'features'>,
+): Omit<TableOptions<TFeatures, TData>, 'features'>
+
+/**
+ * Preserves inference when a wrapper supplies both `data` and `features`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'data' | 'features'>,
+): Omit<TableOptions<TFeatures, TData>, 'data' | 'features'>
+
+/**
+ * Preserves inference when a wrapper supplies both `columns` and `features`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<TableOptions<TFeatures, TData>, 'columns' | 'features'>,
+): Omit<TableOptions<TFeatures, TData>, 'columns' | 'features'>
+
+/**
+ * Preserves inference when a wrapper supplies `data`, `columns`, and
+ * `features`.
+ */
+export function tableOptions<
+  TFeatures extends TableFeatures,
+  TData extends RowData = any,
+>(
+  options: Omit<
+    TableOptions<TFeatures, TData>,
+    'data' | 'columns' | 'features'
+  >,
+): Omit<TableOptions<TFeatures, TData>, 'data' | 'columns' | 'features'>
+
+/**
+ * Runtime implementation for `tableOptions`.
+ *
+ * The helper returns the same object it receives; all value comes from the
+ * overloads preserving table option inference at compile time.
+ */
+export function tableOptions(options: unknown) {
+  return options
+}
+
+// test
+
+// const options = tableOptions({
+//   features: {},
+// })

package/src/index.ts

@@ -1,43 +1,138 @@
-//types
-export * from './columnHelper'
-export * from './types'
-
-//core
-export * from './core/cell'
-export * from './core/column'
-export * from './core/headers'
-export * from './core/row'
-export * from './core/table'
-
-//features
-export * from './features/ColumnFaceting'
-export * from './features/ColumnFiltering'
-export * from './features/ColumnGrouping'
-export * from './features/ColumnOrdering'
-export * from './features/ColumnPinning'
-export * from './features/ColumnSizing'
-export * from './features/ColumnVisibility'
-export * from './features/GlobalFaceting'
-export * from './features/GlobalFiltering'
-export * from './features/RowExpanding'
-export * from './features/RowPagination'
-export * from './features/RowPinning'
-export * from './features/RowSelection'
-export * from './features/RowSorting'
-
-//utils
+/**
+ * Types
+ */
+
+export * from './types/Cell'
+export * from './types/Column'
+export * from './types/ColumnDef'
+export * from './types/Header'
+export * from './types/HeaderGroup'
+export * from './types/Row'
+export * from './types/RowModel'
+export * from './types/RowModelFns'
+export * from './types/Table'
+export * from './types/TableFeatures'
+export * from './types/TableOptions'
+export * from './types/TableState'
+export * from './types/type-utils'
+
+/**
+ * Core
+ */
+
+export * from './core/coreFeatures'
+export * from './helpers/columnHelper'
+export * from './helpers/tableFeatures'
+export * from './helpers/tableOptions'
 export * from './utils'
-export * from './utils/getCoreRowModel'
-export * from './utils/getExpandedRowModel'
-export * from './utils/getFacetedMinMaxValues'
-export * from './utils/getFacetedRowModel'
-export * from './utils/getFacetedUniqueValues'
-export * from './utils/getFilteredRowModel'
-export * from './utils/getGroupedRowModel'
-export * from './utils/getPaginationRowModel'
-export * from './utils/getSortedRowModel'
-
-//fns
-export * from './aggregationFns'
-export * from './filterFns'
-export * from './sortingFns'
+
+// Cells
+export * from './core/cells/constructCell'
+export * from './core/cells/coreCellsFeature'
+export * from './core/cells/coreCellsFeature.types'
+
+// Columns
+export * from './core/columns/constructColumn'
+export * from './core/columns/coreColumnsFeature'
+export * from './core/columns/coreColumnsFeature.types'
+
+// Headers
+export * from './core/headers/buildHeaderGroups'
+export * from './core/headers/constructHeader'
+export * from './core/headers/coreHeadersFeature'
+export * from './core/headers/coreHeadersFeature.types'
+
+// Rows
+export * from './core/rows/constructRow'
+export * from './core/rows/coreRowsFeature'
+export * from './core/rows/coreRowsFeature.types'
+
+// Row Models
+export * from './core/row-models/coreRowModelsFeature'
+export * from './core/row-models/coreRowModelsFeature.types'
+export * from './core/row-models/createCoreRowModel'
+
+// Tables
+export * from './core/table/constructTable'
+export * from './core/table/coreTablesFeature'
+export * from './core/table/coreTablesFeature.types'
+
+/**
+ * RowModelFns
+ */
+
+export * from './fns/aggregationFns'
+export * from './fns/filterFns'
+export * from './fns/sortFns'
+
+/**
+ * Features
+ */
+
+export * from './features/stockFeatures'
+
+// columnFacetingFeature
+export * from './features/column-faceting/columnFacetingFeature'
+export * from './features/column-faceting/columnFacetingFeature.types'
+export * from './features/column-faceting/createFacetedMinMaxValues'
+export * from './features/column-faceting/createFacetedRowModel'
+export * from './features/column-faceting/createFacetedUniqueValues'
+
+// columnFilteringFeature
+export * from './features/column-filtering/columnFilteringFeature'
+export * from './features/column-filtering/columnFilteringFeature.types'
+export * from './features/column-filtering/createFilteredRowModel'
+
+// columnGroupingFeature
+export * from './features/column-grouping/columnGroupingFeature'
+export * from './features/column-grouping/columnGroupingFeature.types'
+export * from './features/column-grouping/createGroupedRowModel'
+
+// columnOrderingFeature
+export * from './features/column-ordering/columnOrderingFeature'
+export * from './features/column-ordering/columnOrderingFeature.types'
+
+// columnPinningFeature
+export * from './features/column-pinning/columnPinningFeature'
+export * from './features/column-pinning/columnPinningFeature.types'
+
+// columnResizingFeature
+export * from './features/column-resizing/columnResizingFeature'
+export * from './features/column-resizing/columnResizingFeature.types'
+
+// columnSizingFeature
+export * from './features/column-sizing/columnSizingFeature'
+export * from './features/column-sizing/columnSizingFeature.types'
+
+// columnVisibilityFeature
+export * from './features/column-visibility/columnVisibilityFeature'
+export * from './features/column-visibility/columnVisibilityFeature.types'
+
+// globalFilteringFeature
+export * from './features/global-filtering/globalFilteringFeature'
+export * from './features/global-filtering/globalFilteringFeature.types'
+
+// rowExpandingFeature
+export * from './features/row-expanding/rowExpandingFeature'
+export * from './features/row-expanding/rowExpandingFeature.types'
+export * from './features/row-expanding/createExpandedRowModel'
+
+// rowPaginationFeature
+export * from './features/row-pagination/rowPaginationFeature'
+export * from './features/row-pagination/rowPaginationFeature.types'
+export * from './features/row-pagination/createPaginatedRowModel'
+
+// rowPinningFeature
+export * from './features/row-pinning/rowPinningFeature'
+export * from './features/row-pinning/rowPinningFeature.types'
+
+// rowSelectionFeature
+export * from './features/row-selection/rowSelectionFeature'
+export * from './features/row-selection/rowSelectionFeature.types'
+
+// rowSortingFeature
+export * from './features/row-sorting/rowSortingFeature'
+export * from './features/row-sorting/rowSortingFeature.types'
+export * from './features/row-sorting/createSortedRowModel'
+
+// force

package/src/process-env.d.ts

@@ -0,0 +1,6 @@
+/** Minimal typing for `process.env` used in dev-only guards (bundlers define this). */
+declare const process: {
+  readonly env: {
+    readonly NODE_ENV?: string
+  }
+}

package/src/reactivity.ts

@@ -0,0 +1,2 @@
+export * from './core/reactivity/coreReactivityFeature.types'
+export * from './core/reactivity/coreReactivityFeature.utils'