@tanstack/table-core 9.0.0-alpha.6 → 9.0.0-beta.1

package/dist/features/column-grouping/columnGroupingFeature.types.d.ts

@@ -0,0 +1,165 @@
+import { CellData, OnChangeFn, RowData, Updater } from "../../types/type-utils.js";
+import { Row } from "../../types/Row.js";
+import { ColumnDefTemplate } from "../../types/ColumnDef.js";
+import { TableFeatures } from "../../types/TableFeatures.js";
+import { Table } from "../../types/Table.js";
+import { RowModel } from "../../core/row-models/coreRowModelsFeature.types.js";
+import { BuiltInAggregationFn } from "../../fns/aggregationFns.js";
+import { Cell } from "../../types/Cell.js";
+
+//#region src/features/column-grouping/columnGroupingFeature.types.d.ts
+type GroupingState = Array<string>;
+interface TableState_ColumnGrouping {
+  grouping: GroupingState;
+}
+interface RowModelFns_ColumnGrouping<TFeatures extends TableFeatures, TData extends RowData> {
+  aggregationFns: Record<keyof AggregationFns, AggregationFn<TFeatures, TData>>;
+}
+interface AggregationFns {}
+type AggregationFn<TFeatures extends TableFeatures, TData extends RowData> = (columnId: string, leafRows: Array<Row<TFeatures, TData>>, childRows: Array<Row<TFeatures, TData>>) => any;
+type CustomAggregationFns<TFeatures extends TableFeatures, TData extends RowData> = Record<string, AggregationFn<TFeatures, TData>>;
+type AggregationFnOption<TFeatures extends TableFeatures, TData extends RowData> = 'auto' | keyof AggregationFns | BuiltInAggregationFn | AggregationFn<TFeatures, TData>;
+interface ColumnDef_ColumnGrouping<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData> {
+  /**
+   * 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).
+   */
+  aggregatedCell?: ColumnDefTemplate<ReturnType<Cell<TFeatures, TData, TValue>['getContext']>>;
+  /**
+   * The resolved aggregation function for the column.
+   */
+  aggregationFn?: AggregationFnOption<TFeatures, TData>;
+  /**
+   * Allows this column to be added to grouping state.
+   *
+   * Defaults to `true`; table-level `enableGrouping` must also allow 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.
+   */
+  getGroupingValue?: (row: TData) => any;
+}
+interface Column_ColumnGrouping<TFeatures extends TableFeatures, TData extends RowData> {
+  /**
+   * Returns the aggregation function for the column.
+   */
+  getAggregationFn: () => AggregationFn<TFeatures, TData> | undefined;
+  /**
+   * Returns the automatically inferred aggregation function for the column.
+   */
+  getAutoAggregationFn: () => AggregationFn<TFeatures, TData> | undefined;
+  /**
+   * Checks whether this column can currently be grouped.
+   */
+  getCanGroup: () => boolean;
+  /**
+   * Finds this column's position in the ordered grouping state.
+   */
+  getGroupedIndex: () => number;
+  /**
+   * Checks whether this column id is present in grouping state.
+   */
+  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.
+   */
+  getToggleGroupingHandler: () => () => void;
+  /**
+   * Toggles the grouping state of the column.
+   */
+  toggleGrouping: () => void;
+}
+interface Row_ColumnGrouping {
+  _groupingValuesCache: Record<string, any>;
+  /**
+   * Reads the value used to group this row for a column id.
+   */
+  getGroupingValue: (columnId: string) => unknown;
+  /**
+   * Checks whether this row represents a grouped row.
+   */
+  getIsGrouped: () => boolean;
+  /**
+   * If this row is grouped, this is the id of the column that this row is grouped by.
+   */
+  groupingColumnId?: string;
+  /**
+   * If this row is grouped, this is the unique/shared value for the `groupingColumnId` for all of the rows in this group.
+   */
+  groupingValue?: unknown;
+}
+interface Cell_ColumnGrouping {
+  /**
+   * Checks whether this cell should render an aggregated value.
+   */
+  getIsAggregated: () => boolean;
+  /**
+   * Checks whether this cell represents the active grouping column.
+   */
+  getIsGrouped: () => boolean;
+  /**
+   * Checks whether this cell is hidden as a grouping placeholder.
+   */
+  getIsPlaceholder: () => boolean;
+}
+interface ColumnDefaultOptions {
+  enableGrouping: boolean;
+  onGroupingChange: OnChangeFn<GroupingState>;
+}
+interface TableOptions_ColumnGrouping {
+  /**
+   * Allows columns to be grouped for this table.
+   */
+  enableGrouping?: boolean;
+  /**
+   * 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.
+   */
+  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.
+   */
+  manualGrouping?: boolean;
+  /**
+   * Called with an updater when grouping state changes. Pair this with
+   * `state.grouping` when using external state; external atoms can own the
+   * slice without this callback.
+   */
+  onGroupingChange?: OnChangeFn<GroupingState>;
+}
+type GroupingColumnMode = false | 'reorder' | 'remove';
+interface Table_ColumnGrouping<TFeatures extends TableFeatures, TData extends RowData> {
+  /**
+   * Resets `grouping` to `initialState.grouping`.
+   *
+   * Pass `true` to ignore initial state and reset to `[]`.
+   */
+  resetGrouping: (defaultState?: boolean) => void;
+  /**
+   * Updates grouping state with a next ordered id array or updater function.
+   */
+  setGrouping: (updater: Updater<GroupingState>) => void;
+}
+interface Table_RowModels_Grouped<TFeatures extends TableFeatures, TData extends RowData> {
+  /**
+   * Resolves the row model after grouping and aggregation have been applied.
+   */
+  getGroupedRowModel: () => RowModel<TFeatures, TData>;
+  /**
+   * Reads the row model immediately before grouping.
+   */
+  getPreGroupedRowModel: () => RowModel<TFeatures, TData>;
+}
+interface CreateRowModel_Grouped<TFeatures extends TableFeatures, TData extends RowData> {
+  /**
+   * Factory used to retrieve the grouped row model. If using server-side
+   * grouping, this is not required. To use client-side grouping, pass
+   * `createGroupedRowModel()` or implement your own factory.
+   */
+  groupedRowModel?: (table: Table<TFeatures, TData>) => () => RowModel<TFeatures, TData>;
+}
+interface CachedRowModel_Grouped<TFeatures extends TableFeatures, TData extends RowData> {
+  groupedRowModel: () => RowModel<TFeatures, TData>;
+}
+//#endregion
+export { AggregationFn, AggregationFnOption, AggregationFns, CachedRowModel_Grouped, Cell_ColumnGrouping, ColumnDef_ColumnGrouping, ColumnDefaultOptions, Column_ColumnGrouping, CreateRowModel_Grouped, CustomAggregationFns, GroupingColumnMode, GroupingState, RowModelFns_ColumnGrouping, Row_ColumnGrouping, TableOptions_ColumnGrouping, TableState_ColumnGrouping, Table_ColumnGrouping, Table_RowModels_Grouped };
+//# sourceMappingURL=columnGroupingFeature.types.d.ts.map

package/dist/features/column-grouping/columnGroupingFeature.utils.cjs

@@ -0,0 +1,250 @@
+const require_utils = require('../../utils.cjs');
+
+//#region src/features/column-grouping/columnGroupingFeature.utils.ts
+/**
+* Creates the default grouping state.
+*
+* The feature default is an empty array, meaning no columns are grouped. Reset
+* APIs use this value when `defaultState` is `true`.
+*
+* @example
+* ```ts
+* const grouping = getDefaultGroupingState()
+* ```
+*/
+function getDefaultGroupingState() {
+	return [];
+}
+/**
+* Adds or removes this column id from the grouping state.
+*
+* Existing grouped columns keep their order. A column already present in
+* `state.grouping` is removed; otherwise it is appended.
+*
+* @example
+* ```ts
+* column_toggleGrouping(column)
+* ```
+*/
+function column_toggleGrouping(column) {
+	table_setGrouping(column.table, (old) => {
+		if (old.includes(column.id)) return old.filter((d) => d !== column.id);
+		return [...old, column.id];
+	});
+}
+/**
+* Checks whether this column can be used for grouping.
+*
+* Grouping must be enabled at the column and table level, and the column must
+* either have an accessor or provide `getGroupingValue`.
+*
+* @example
+* ```ts
+* const canGroup = column_getCanGroup(column)
+* ```
+*/
+function column_getCanGroup(column) {
+	return (column.columnDef.enableGrouping ?? true) && (column.table.options.enableGrouping ?? true) && (!!column.accessorFn || !!column.columnDef.getGroupingValue);
+}
+/**
+* Checks whether this column id is present in `state.grouping`.
+*
+* The result only reflects grouping state, not whether the grouped row model has
+* been calculated yet.
+*
+* @example
+* ```ts
+* const isGrouped = column_getIsGrouped(column)
+* ```
+*/
+function column_getIsGrouped(column) {
+	var _column$table$atoms$g;
+	return !!((_column$table$atoms$g = column.table.atoms.grouping) === null || _column$table$atoms$g === void 0 || (_column$table$atoms$g = _column$table$atoms$g.get()) === null || _column$table$atoms$g === void 0 ? void 0 : _column$table$atoms$g.includes(column.id));
+}
+/**
+* Finds this column's position in the ordered grouping state.
+*
+* The result is `-1` when the column is not grouped.
+*
+* @example
+* ```ts
+* const index = column_getGroupedIndex(column)
+* ```
+*/
+function column_getGroupedIndex(column) {
+	var _column$table$atoms$g2;
+	return ((_column$table$atoms$g2 = column.table.atoms.grouping) === null || _column$table$atoms$g2 === void 0 || (_column$table$atoms$g2 = _column$table$atoms$g2.get()) === null || _column$table$atoms$g2 === void 0 ? void 0 : _column$table$atoms$g2.indexOf(column.id)) ?? -1;
+}
+/**
+* Creates a header/control handler that toggles grouping for this column.
+*
+* The handler is a no-op when `column_getCanGroup(column)` is false.
+*
+* @example
+* ```ts
+* const onClick = column_getToggleGroupingHandler(column)
+* ```
+*/
+function column_getToggleGroupingHandler(column) {
+	const canGroup = column_getCanGroup(column);
+	return () => {
+		if (!canGroup) return;
+		column_toggleGrouping(column);
+	};
+}
+/**
+* Chooses a built-in aggregation function from the first core row value.
+*
+* Numeric columns default to `sum`, date-like values default to `extent`, and
+* other value types leave aggregation unspecified.
+*
+* @example
+* ```ts
+* const aggregationFn = column_getAutoAggregationFn(column)
+* ```
+*/
+function column_getAutoAggregationFn(column) {
+	const aggregationFns = column.table._rowModelFns.aggregationFns;
+	const firstRow = column.table.getCoreRowModel().flatRows[0];
+	const value = firstRow === null || firstRow === void 0 ? void 0 : firstRow.getValue(column.id);
+	if (typeof value === "number") return aggregationFns === null || aggregationFns === void 0 ? void 0 : aggregationFns.sum;
+	if (Object.prototype.toString.call(value) === "[object Date]") return aggregationFns === null || aggregationFns === void 0 ? void 0 : aggregationFns.extent;
+}
+/**
+* Resolves the aggregation function configured for a column.
+*
+* Function-valued `columnDef.aggregationFn` is returned directly, `'auto'`
+* delegates to `column_getAutoAggregationFn`, and string values are looked up in
+* the table's aggregation function registry.
+*
+* @example
+* ```ts
+* const aggregationFn = column_getAggregationFn(column)
+* ```
+*/
+function column_getAggregationFn(column) {
+	const aggregationFns = column.table._rowModelFns.aggregationFns;
+	return require_utils.isFunction(column.columnDef.aggregationFn) ? column.columnDef.aggregationFn : column.columnDef.aggregationFn === "auto" ? column_getAutoAggregationFn(column) : aggregationFns === null || aggregationFns === void 0 ? void 0 : aggregationFns[column.columnDef.aggregationFn];
+}
+/**
+* Routes a grouping updater through the table's grouping change handler.
+*
+* The updater may be a next `GroupingState` array or a function of the previous
+* grouping state, matching the instance `table.setGrouping` behavior.
+*
+* @example
+* ```ts
+* table_setGrouping(table, (old) => [...old, 'status'])
+* ```
+*/
+function table_setGrouping(table, updater) {
+	var _table$options$onGrou, _table$options;
+	(_table$options$onGrou = (_table$options = table.options).onGroupingChange) === null || _table$options$onGrou === void 0 || _table$options$onGrou.call(_table$options, updater);
+}
+/**
+* Resets `grouping` to the configured initial state or feature default.
+*
+* With no argument, the reset clones `table.initialState.grouping` when it
+* exists. Passing `true` ignores initial state and resets to `[]`.
+*
+* @example
+* ```ts
+* table_resetGrouping(table)
+* table_resetGrouping(table, true)
+* ```
+*/
+function table_resetGrouping(table, defaultState) {
+	table_setGrouping(table, defaultState ? [] : require_utils.cloneState(table.initialState.grouping ?? []));
+}
+/**
+* Checks whether this row was created as a grouped row.
+*
+* Grouped rows carry a `groupingColumnId`; ordinary leaf rows do not.
+*
+* @example
+* ```ts
+* const isGrouped = row_getIsGrouped(row)
+* ```
+*/
+function row_getIsGrouped(row) {
+	return !!row.groupingColumnId;
+}
+/**
+* Reads and caches this row's grouping value for a column.
+*
+* `columnDef.getGroupingValue` wins when provided; otherwise the normal row
+* accessor value is used.
+*
+* @example
+* ```ts
+* const groupValue = row_getGroupingValue(row, 'status')
+* ```
+*/
+function row_getGroupingValue(row, columnId) {
+	var _row$_groupingValuesC, _row$_groupingValuesC2;
+	if ((_row$_groupingValuesC = row._groupingValuesCache) === null || _row$_groupingValuesC === void 0 ? void 0 : _row$_groupingValuesC.hasOwnProperty(columnId)) return row._groupingValuesCache[columnId];
+	const column = row.table.getColumn(columnId);
+	if (!column.columnDef.getGroupingValue) return row.getValue(columnId);
+	if (row._groupingValuesCache) row._groupingValuesCache[columnId] = column.columnDef.getGroupingValue(row.original);
+	return (_row$_groupingValuesC2 = row._groupingValuesCache) === null || _row$_groupingValuesC2 === void 0 ? void 0 : _row$_groupingValuesC2[columnId];
+}
+/**
+* Checks whether this cell represents the grouped column for a grouped row.
+*
+* This is the cell that usually renders the grouped value and expansion control.
+*
+* @example
+* ```ts
+* const isGroupedCell = cell_getIsGrouped(cell)
+* ```
+*/
+function cell_getIsGrouped(cell) {
+	const row = cell.row;
+	return column_getIsGrouped(cell.column) && cell.column.id === row.groupingColumnId;
+}
+/**
+* Checks whether this cell is a placeholder hidden by grouping.
+*
+* Placeholder cells belong to grouped columns other than the row's active
+* grouping column.
+*
+* @example
+* ```ts
+* const isPlaceholder = cell_getIsPlaceholder(cell)
+* ```
+*/
+function cell_getIsPlaceholder(cell) {
+	return !cell_getIsGrouped(cell) && column_getIsGrouped(cell.column);
+}
+/**
+* Checks whether this cell should render an aggregated value.
+*
+* Aggregated cells are non-placeholder, non-grouped cells on rows that have
+* subRows.
+*
+* @example
+* ```ts
+* const isAggregated = cell_getIsAggregated(cell)
+* ```
+*/
+function cell_getIsAggregated(cell) {
+	return !cell_getIsGrouped(cell) && !cell_getIsPlaceholder(cell) && !!cell.row.subRows.length;
+}
+
+//#endregion
+exports.cell_getIsAggregated = cell_getIsAggregated;
+exports.cell_getIsGrouped = cell_getIsGrouped;
+exports.cell_getIsPlaceholder = cell_getIsPlaceholder;
+exports.column_getAggregationFn = column_getAggregationFn;
+exports.column_getAutoAggregationFn = column_getAutoAggregationFn;
+exports.column_getCanGroup = column_getCanGroup;
+exports.column_getGroupedIndex = column_getGroupedIndex;
+exports.column_getIsGrouped = column_getIsGrouped;
+exports.column_getToggleGroupingHandler = column_getToggleGroupingHandler;
+exports.column_toggleGrouping = column_toggleGrouping;
+exports.getDefaultGroupingState = getDefaultGroupingState;
+exports.row_getGroupingValue = row_getGroupingValue;
+exports.row_getIsGrouped = row_getIsGrouped;
+exports.table_resetGrouping = table_resetGrouping;
+exports.table_setGrouping = table_setGrouping;
+//# sourceMappingURL=columnGroupingFeature.utils.cjs.map

package/dist/features/column-grouping/columnGroupingFeature.utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"columnGroupingFeature.utils.cjs","names":["isFunction","cloneState"],"sources":["../../../src/features/column-grouping/columnGroupingFeature.utils.ts"],"sourcesContent":["import { cloneState, isFunction } from '../../utils'\nimport type { Column_Internal } from '../../types/Column'\nimport type { CellData, RowData, Updater } from '../../types/type-utils'\nimport type { TableFeatures } from '../../types/TableFeatures'\nimport type { Table_Internal } from '../../types/Table'\nimport type { Row } from '../../types/Row'\nimport type { Cell } from '../../types/Cell'\nimport type {\n  AggregationFn,\n  GroupingState,\n  Row_ColumnGrouping,\n} from './columnGroupingFeature.types'\n\n/**\n * Creates the default grouping state.\n *\n * The feature default is an empty array, meaning no columns are grouped. Reset\n * APIs use this value when `defaultState` is `true`.\n *\n * @example\n * ```ts\n * const grouping = getDefaultGroupingState()\n * ```\n */\nexport function getDefaultGroupingState(): GroupingState {\n  return []\n}\n\n/**\n * Adds or removes this column id from the grouping state.\n *\n * Existing grouped columns keep their order. A column already present in\n * `state.grouping` is removed; otherwise it is appended.\n *\n * @example\n * ```ts\n * column_toggleGrouping(column)\n * ```\n */\nexport function column_toggleGrouping<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(column: Column_Internal<TFeatures, TData, TValue>) {\n  table_setGrouping(column.table, (old) => {\n    // Find any existing grouping for this column\n    if (old.includes(column.id)) {\n      return old.filter((d) => d !== column.id)\n    }\n\n    return [...old, column.id]\n  })\n}\n\n/**\n * Checks whether this column can be used for grouping.\n *\n * Grouping must be enabled at the column and table level, and the column must\n * either have an accessor or provide `getGroupingValue`.\n *\n * @example\n * ```ts\n * const canGroup = column_getCanGroup(column)\n * ```\n */\nexport function column_getCanGroup<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(column: Column_Internal<TFeatures, TData, TValue>) {\n  return (\n    (column.columnDef.enableGrouping ?? true) &&\n    (column.table.options.enableGrouping ?? true) &&\n    (!!column.accessorFn || !!column.columnDef.getGroupingValue)\n  )\n}\n\n/**\n * Checks whether this column id is present in `state.grouping`.\n *\n * The result only reflects grouping state, not whether the grouped row model has\n * been calculated yet.\n *\n * @example\n * ```ts\n * const isGrouped = column_getIsGrouped(column)\n * ```\n */\nexport function column_getIsGrouped<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(column: Column_Internal<TFeatures, TData, TValue>): boolean {\n  return !!column.table.atoms.grouping?.get()?.includes(column.id)\n}\n\n/**\n * Finds this column's position in the ordered grouping state.\n *\n * The result is `-1` when the column is not grouped.\n *\n * @example\n * ```ts\n * const index = column_getGroupedIndex(column)\n * ```\n */\nexport function column_getGroupedIndex<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(column: Column_Internal<TFeatures, TData, TValue>): number {\n  return column.table.atoms.grouping?.get()?.indexOf(column.id) ?? -1\n}\n\n/**\n * Creates a header/control handler that toggles grouping for this column.\n *\n * The handler is a no-op when `column_getCanGroup(column)` is false.\n *\n * @example\n * ```ts\n * const onClick = column_getToggleGroupingHandler(column)\n * ```\n */\nexport function column_getToggleGroupingHandler<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(column: Column_Internal<TFeatures, TData, TValue>) {\n  const canGroup = column_getCanGroup(column)\n\n  return () => {\n    if (!canGroup) return\n    column_toggleGrouping(column)\n  }\n}\n\n/**\n * Chooses a built-in aggregation function from the first core row value.\n *\n * Numeric columns default to `sum`, date-like values default to `extent`, and\n * other value types leave aggregation unspecified.\n *\n * @example\n * ```ts\n * const aggregationFn = column_getAutoAggregationFn(column)\n * ```\n */\nexport function column_getAutoAggregationFn<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(column: Column_Internal<TFeatures, TData, TValue>) {\n  const aggregationFns:\n    | Record<string, AggregationFn<TFeatures, TData>>\n    | undefined = column.table._rowModelFns.aggregationFns\n\n  const firstRow = column.table.getCoreRowModel().flatRows[0]\n\n  const value = firstRow?.getValue(column.id)\n\n  if (typeof value === 'number') {\n    return aggregationFns?.sum\n  }\n\n  if (Object.prototype.toString.call(value) === '[object Date]') {\n    return aggregationFns?.extent\n  }\n}\n\n/**\n * Resolves the aggregation function configured for a column.\n *\n * Function-valued `columnDef.aggregationFn` is returned directly, `'auto'`\n * delegates to `column_getAutoAggregationFn`, and string values are looked up in\n * the table's aggregation function registry.\n *\n * @example\n * ```ts\n * const aggregationFn = column_getAggregationFn(column)\n * ```\n */\nexport function column_getAggregationFn<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(column: Column_Internal<TFeatures, TData, TValue>) {\n  const aggregationFns:\n    | Record<string, AggregationFn<TFeatures, TData>>\n    | undefined = column.table._rowModelFns.aggregationFns\n\n  return isFunction(column.columnDef.aggregationFn)\n    ? column.columnDef.aggregationFn\n    : column.columnDef.aggregationFn === 'auto'\n      ? column_getAutoAggregationFn(column)\n      : aggregationFns?.[column.columnDef.aggregationFn as string]\n}\n\n/**\n * Routes a grouping updater through the table's grouping change handler.\n *\n * The updater may be a next `GroupingState` array or a function of the previous\n * grouping state, matching the instance `table.setGrouping` behavior.\n *\n * @example\n * ```ts\n * table_setGrouping(table, (old) => [...old, 'status'])\n * ```\n */\nexport function table_setGrouping<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(table: Table_Internal<TFeatures, TData>, updater: Updater<GroupingState>) {\n  table.options.onGroupingChange?.(updater)\n}\n\n/**\n * Resets `grouping` to the configured initial state or feature default.\n *\n * With no argument, the reset clones `table.initialState.grouping` when it\n * exists. Passing `true` ignores initial state and resets to `[]`.\n *\n * @example\n * ```ts\n * table_resetGrouping(table)\n * table_resetGrouping(table, true)\n * ```\n */\nexport function table_resetGrouping<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean) {\n  table_setGrouping(\n    table,\n    defaultState ? [] : cloneState(table.initialState.grouping ?? []),\n  )\n}\n\n/**\n * Checks whether this row was created as a grouped row.\n *\n * Grouped rows carry a `groupingColumnId`; ordinary leaf rows do not.\n *\n * @example\n * ```ts\n * const isGrouped = row_getIsGrouped(row)\n * ```\n */\nexport function row_getIsGrouped<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(row: Row<TFeatures, TData> & Partial<Row_ColumnGrouping>) {\n  return !!row.groupingColumnId\n}\n\n/**\n * Reads and caches this row's grouping value for a column.\n *\n * `columnDef.getGroupingValue` wins when provided; otherwise the normal row\n * accessor value is used.\n *\n * @example\n * ```ts\n * const groupValue = row_getGroupingValue(row, 'status')\n * ```\n */\nexport function row_getGroupingValue<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n>(row: Row<TFeatures, TData> & Partial<Row_ColumnGrouping>, columnId: string) {\n  if (row._groupingValuesCache?.hasOwnProperty(columnId)) {\n    return row._groupingValuesCache[columnId]\n  }\n\n  const column = row.table.getColumn(columnId) as Column_Internal<\n    TFeatures,\n    TData\n  >\n\n  if (!column.columnDef.getGroupingValue) {\n    return row.getValue(columnId)\n  }\n\n  if (row._groupingValuesCache) {\n    row._groupingValuesCache[columnId] = column.columnDef.getGroupingValue(\n      row.original,\n    )\n  }\n\n  return row._groupingValuesCache?.[columnId]\n}\n\n/**\n * Checks whether this cell represents the grouped column for a grouped row.\n *\n * This is the cell that usually renders the grouped value and expansion control.\n *\n * @example\n * ```ts\n * const isGroupedCell = cell_getIsGrouped(cell)\n * ```\n */\nexport function cell_getIsGrouped<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(cell: Cell<TFeatures, TData, TValue>) {\n  const row = cell.row as Row<TFeatures, TData> & Partial<Row_ColumnGrouping>\n  return (\n    column_getIsGrouped(cell.column) && cell.column.id === row.groupingColumnId\n  )\n}\n\n/**\n * Checks whether this cell is a placeholder hidden by grouping.\n *\n * Placeholder cells belong to grouped columns other than the row's active\n * grouping column.\n *\n * @example\n * ```ts\n * const isPlaceholder = cell_getIsPlaceholder(cell)\n * ```\n */\nexport function cell_getIsPlaceholder<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(cell: Cell<TFeatures, TData, TValue>) {\n  return !cell_getIsGrouped(cell) && column_getIsGrouped(cell.column)\n}\n\n/**\n * Checks whether this cell should render an aggregated value.\n *\n * Aggregated cells are non-placeholder, non-grouped cells on rows that have\n * subRows.\n *\n * @example\n * ```ts\n * const isAggregated = cell_getIsAggregated(cell)\n * ```\n */\nexport function cell_getIsAggregated<\n  TFeatures extends TableFeatures,\n  TData extends RowData,\n  TValue extends CellData = CellData,\n>(cell: Cell<TFeatures, TData, TValue>) {\n  return (\n    !cell_getIsGrouped(cell) &&\n    !cell_getIsPlaceholder(cell) &&\n    !!cell.row.subRows.length\n  )\n}\n"],"mappings":"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"}

package/dist/features/column-grouping/columnGroupingFeature.utils.d.cts

@@ -0,0 +1,190 @@
+import { CellData, RowData, Updater } from "../../types/type-utils.cjs";
+import { Column_Internal } from "../../types/Column.cjs";
+import { Row } from "../../types/Row.cjs";
+import { TableFeatures } from "../../types/TableFeatures.cjs";
+import { Table_Internal } from "../../types/Table.cjs";
+import { AggregationFn, GroupingState, Row_ColumnGrouping } from "./columnGroupingFeature.types.cjs";
+import { Cell } from "../../types/Cell.cjs";
+
+//#region src/features/column-grouping/columnGroupingFeature.utils.d.ts
+/**
+ * Creates the default grouping state.
+ *
+ * The feature default is an empty array, meaning no columns are grouped. Reset
+ * APIs use this value when `defaultState` is `true`.
+ *
+ * @example
+ * ```ts
+ * const grouping = getDefaultGroupingState()
+ * ```
+ */
+declare function getDefaultGroupingState(): GroupingState;
+/**
+ * Adds or removes this column id from the grouping state.
+ *
+ * Existing grouped columns keep their order. A column already present in
+ * `state.grouping` is removed; otherwise it is appended.
+ *
+ * @example
+ * ```ts
+ * column_toggleGrouping(column)
+ * ```
+ */
+declare function column_toggleGrouping<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): void;
+/**
+ * Checks whether this column can be used for grouping.
+ *
+ * Grouping must be enabled at the column and table level, and the column must
+ * either have an accessor or provide `getGroupingValue`.
+ *
+ * @example
+ * ```ts
+ * const canGroup = column_getCanGroup(column)
+ * ```
+ */
+declare function column_getCanGroup<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): boolean;
+/**
+ * Checks whether this column id is present in `state.grouping`.
+ *
+ * The result only reflects grouping state, not whether the grouped row model has
+ * been calculated yet.
+ *
+ * @example
+ * ```ts
+ * const isGrouped = column_getIsGrouped(column)
+ * ```
+ */
+declare function column_getIsGrouped<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): boolean;
+/**
+ * Finds this column's position in the ordered grouping state.
+ *
+ * The result is `-1` when the column is not grouped.
+ *
+ * @example
+ * ```ts
+ * const index = column_getGroupedIndex(column)
+ * ```
+ */
+declare function column_getGroupedIndex<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): number;
+/**
+ * Creates a header/control handler that toggles grouping for this column.
+ *
+ * The handler is a no-op when `column_getCanGroup(column)` is false.
+ *
+ * @example
+ * ```ts
+ * const onClick = column_getToggleGroupingHandler(column)
+ * ```
+ */
+declare function column_getToggleGroupingHandler<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): () => void;
+/**
+ * Chooses a built-in aggregation function from the first core row value.
+ *
+ * Numeric columns default to `sum`, date-like values default to `extent`, and
+ * other value types leave aggregation unspecified.
+ *
+ * @example
+ * ```ts
+ * const aggregationFn = column_getAutoAggregationFn(column)
+ * ```
+ */
+declare function column_getAutoAggregationFn<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): AggregationFn<TFeatures, TData> | undefined;
+/**
+ * Resolves the aggregation function configured for a column.
+ *
+ * Function-valued `columnDef.aggregationFn` is returned directly, `'auto'`
+ * delegates to `column_getAutoAggregationFn`, and string values are looked up in
+ * the table's aggregation function registry.
+ *
+ * @example
+ * ```ts
+ * const aggregationFn = column_getAggregationFn(column)
+ * ```
+ */
+declare function column_getAggregationFn<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(column: Column_Internal<TFeatures, TData, TValue>): AggregationFn<TFeatures, TData> | undefined;
+/**
+ * Routes a grouping updater through the table's grouping change handler.
+ *
+ * The updater may be a next `GroupingState` array or a function of the previous
+ * grouping state, matching the instance `table.setGrouping` behavior.
+ *
+ * @example
+ * ```ts
+ * table_setGrouping(table, (old) => [...old, 'status'])
+ * ```
+ */
+declare function table_setGrouping<TFeatures extends TableFeatures, TData extends RowData>(table: Table_Internal<TFeatures, TData>, updater: Updater<GroupingState>): void;
+/**
+ * Resets `grouping` to the configured initial state or feature default.
+ *
+ * With no argument, the reset clones `table.initialState.grouping` when it
+ * exists. Passing `true` ignores initial state and resets to `[]`.
+ *
+ * @example
+ * ```ts
+ * table_resetGrouping(table)
+ * table_resetGrouping(table, true)
+ * ```
+ */
+declare function table_resetGrouping<TFeatures extends TableFeatures, TData extends RowData>(table: Table_Internal<TFeatures, TData>, defaultState?: boolean): void;
+/**
+ * Checks whether this row was created as a grouped row.
+ *
+ * Grouped rows carry a `groupingColumnId`; ordinary leaf rows do not.
+ *
+ * @example
+ * ```ts
+ * const isGrouped = row_getIsGrouped(row)
+ * ```
+ */
+declare function row_getIsGrouped<TFeatures extends TableFeatures, TData extends RowData>(row: Row<TFeatures, TData> & Partial<Row_ColumnGrouping>): boolean;
+/**
+ * Reads and caches this row's grouping value for a column.
+ *
+ * `columnDef.getGroupingValue` wins when provided; otherwise the normal row
+ * accessor value is used.
+ *
+ * @example
+ * ```ts
+ * const groupValue = row_getGroupingValue(row, 'status')
+ * ```
+ */
+declare function row_getGroupingValue<TFeatures extends TableFeatures, TData extends RowData>(row: Row<TFeatures, TData> & Partial<Row_ColumnGrouping>, columnId: string): any;
+/**
+ * Checks whether this cell represents the grouped column for a grouped row.
+ *
+ * This is the cell that usually renders the grouped value and expansion control.
+ *
+ * @example
+ * ```ts
+ * const isGroupedCell = cell_getIsGrouped(cell)
+ * ```
+ */
+declare function cell_getIsGrouped<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
+/**
+ * Checks whether this cell is a placeholder hidden by grouping.
+ *
+ * Placeholder cells belong to grouped columns other than the row's active
+ * grouping column.
+ *
+ * @example
+ * ```ts
+ * const isPlaceholder = cell_getIsPlaceholder(cell)
+ * ```
+ */
+declare function cell_getIsPlaceholder<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
+/**
+ * Checks whether this cell should render an aggregated value.
+ *
+ * Aggregated cells are non-placeholder, non-grouped cells on rows that have
+ * subRows.
+ *
+ * @example
+ * ```ts
+ * const isAggregated = cell_getIsAggregated(cell)
+ * ```
+ */
+declare function cell_getIsAggregated<TFeatures extends TableFeatures, TData extends RowData, TValue extends CellData = CellData>(cell: Cell<TFeatures, TData, TValue>): boolean;
+//#endregion
+export { cell_getIsAggregated, cell_getIsGrouped, cell_getIsPlaceholder, column_getAggregationFn, column_getAutoAggregationFn, column_getCanGroup, column_getGroupedIndex, column_getIsGrouped, column_getToggleGroupingHandler, column_toggleGrouping, getDefaultGroupingState, row_getGroupingValue, row_getIsGrouped, table_resetGrouping, table_setGrouping };
+//# sourceMappingURL=columnGroupingFeature.utils.d.cts.map