@jielga/tmdatagrid 2.1.3 → 2.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 A React data grid built on TanStack Table v9 and Mantine - always virtualized, with resizable, reorderable, sortable, filterable, hideable and pinnable columns.
 
-- Documentation: <https://jielga.github.io/react/>
+- Documentation: <https://jielga.github.io/react/tmdatagrid/>
 - Source, issues and the contributor guide: <https://github.com/Jielga/react>
 
 ```sh

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { BoxProps, MantineSize, MenuProps } from "@mantine/core";
 import { CSSProperties, ComponentType, MouseEvent, MutableRefObject, ReactNode } from "react";
-import { AccessorFn, AccessorFnColumnDef, AccessorKeyColumnDef, Cell, Column, ColumnFiltersState, ColumnHelper, ColumnPinningState, DeepKeys, DeepValue, DisplayColumnDef, ExpandedState, GroupColumnDef, Header, IdentifiedColumnDef, Row, RowData, RowSelectionState, Table, TableFeatures, TableOptions, TableState, aggregationFns } from "@tanstack/react-table";
+import { AccessorFn, AccessorFnColumnDef, AccessorKeyColumnDef, Cell, Column, ColumnFiltersState, ColumnHelper, ColumnPinningState, DeepKeys, DeepValue, DisplayColumnDef, ExpandedState, FilterMeta, GroupColumnDef, Header, IdentifiedColumnDef, Row, RowData, RowSelectionState, Table, TableFeatures, TableOptions, TableState, aggregationFns } from "@tanstack/react-table";
 import { Store } from "@tanstack/store";
 import { AnyFieldApi, AnyFormApi, StandardSchemaV1 } from "@tanstack/react-form";
 import { RankingInfo } from "@tanstack/match-sorter-utils";
@@ -1748,6 +1748,28 @@ type TMDataGridColumnMeta<TData extends RowData = TMDataGridRowData> = {
   /** Share of the leftover width this column claims. Defaults to `1`. */
   flex?: number;
   align?: "left" | "right" | "center";
+  /**
+   * How many columns this column's cell covers on a row, counting itself.
+   * Defaults to `1`.
+   *
+   * A cell spanning `n` is one cell `n` columns wide; the `n - 1` cells to its
+   * right do not render on that row. A function decides per row:
+   *
+   * ```tsx
+   * meta: {
+   *   // An open row's title takes the rest of the row.
+   *   colSpan: ({ row }) => (row.getIsExpanded() ? Infinity : 1),
+   * }
+   * ```
+   *
+   * Counted over the displayed columns, so hiding or moving a column changes
+   * what a span covers. A span stops at the last of your columns - it never
+   * covers the checkbox, tree, details or edit lane - and at the edge of its
+   * pinned block. Group rows, and a row open in row edit mode, ignore it.
+   *
+   * Display only: sorting, filtering, copy and export still see every column.
+   */
+  colSpan?: number | ((args: TMDataGridColSpanArgs<TData>) => number);
   /**
    * Size the column to its widest mounted content once, after the first rows
    * render - unless a persisted or user-set width already covers it. The same
@@ -1918,6 +1940,11 @@ type TMDataGridDetailsArgs<TData extends RowData> = {
   row: Row<TMDataGridFeatures, TData>;
   table: TMDataGridTable<TData>;
 };
+/** What a `meta.colSpan` function receives. */
+type TMDataGridColSpanArgs<TData extends RowData> = {
+  row: Row<TMDataGridFeatures, TData>;
+  table: TMDataGridTable<TData>;
+};
 /** Builds the panel shown underneath an expanded row. See `renderDetails`. */
 type TMDataGridDetailsRenderer<TData extends RowData> = (args: TMDataGridDetailsArgs<TData>) => ReactNode;
 /**
@@ -2679,6 +2706,15 @@ declare function formatFilterLabel({ label, type, filter, operatorLabels }: {
   /** Localized operator names - `labels.operators`. Defaults to English. */
   operatorLabels?: Record<TMDataGridFilterOperator, string>;
 }): string;
+declare function matchesFilter(cellValue: unknown, { operator, value }: TMDataGridFilterValue): boolean;
+/**
+ * The signature of a column's own `filterFn`. The third argument is the
+ * `{ operator, value }` envelope the grid writes into `columnFilters`; a
+ * column `filterFn` replaces `tmDataGridFilterFn` outright, so it is handed
+ * the envelope, not the unwrapped value. Delegate to `tmDataGridFilterFn`
+ * for the operators the function does not handle itself.
+ */
+type TMDataGridFilterFn<TData extends RowData> = (row: Row<TMDataGridFeatures, TData>, columnId: string, filterValue: TMDataGridFilterValue, addMeta?: (meta: FilterMeta) => void) => boolean;
 /**
  * The single filter function every TMDataGrid column uses. It dispatches on the
  * operator carried by the filter value, which is what lets one column offer
@@ -3967,4 +4003,4 @@ declare function getSelectableRowIds<TData extends RowData>(row: Row<TMDataGridF
  */
 declare function resolveRowSelectionClick<TData extends RowData>({ rows, rowId, anchorRowId, modifiers, selection, canReplaceSelection }: ResolveRowSelectionClickArgs<TData>): ResolvedRowSelection;
 //#endregion
-export { type BuildExportDataArgs, type ColumnStepArgs, DATA_STATE_SLICES, DEFAULT_EXPORT_OPTIONS, DEFAULT_TMDATAGRID_SIZE, DETAILS_COLUMN_ID, DgAutocompleteFilter, DgDateRangeFilter, DgRangeSliderFilter, DgTriStateFilter, EDIT_COLUMN_ID, type ExportGridArgs, FILTER_OPERATOR_LABELS, GROUP_COLUMN_ID, type MoveColumnArgs, PERSIST_PAYLOAD_VERSION, ROW_NUMBER_COLUMN_ID, type ResolveRangeBoundsArgs, type ResolveRowSelectionClickArgs, type ResolvedRowSelection, SELECT_COLUMN_ID, SETTINGS_STATE_SLICES, SIZE_CONTROL_SIZE, SIZE_ROW_HEIGHT, TMDATAGRID_LABELS_EN, TMDATAGRID_LABELS_SV, TMDataGrid, type TMDataGridAddRowsOptions, type TMDataGridAddRowsResult, type TMDataGridAggregationName, type TMDataGridApi, TMDataGridBooleanEditor, type TMDataGridCapabilities, type TMDataGridCellEventArgs, type TMDataGridCellPosition, type TMDataGridCellRange, type TMDataGridCellSelectionMode, type TMDataGridClipboardTextOptions, type TMDataGridColumnCapabilities, type TMDataGridColumnEditOptions, type TMDataGridColumnFilter, type TMDataGridColumnFilterOptions, type TMDataGridColumnHelper, type TMDataGridColumnMenuItemsArgs, type TMDataGridColumnMenuItemsRenderer, type TMDataGridColumnMeta, type TMDataGridColumnRegion, type TMDataGridColumnSearchable, type TMDataGridColumnType, type TMDataGridColumnsPanelProps, type TMDataGridCommitAllResult, type TMDataGridContextValue, type TMDataGridCsvFormatOptions, type TMDataGridDataSlice, TMDataGridDateEditor, type TMDataGridDetailsArgs, type TMDataGridDetailsRenderer, TMDataGridDraftActions, type TMDataGridDraftActionsActions, type TMDataGridDraftActionsControls, type TMDataGridDraftActionsProps, type TMDataGridDraftActionsSlotArgs, type TMDataGridDraftActionsState, type TMDataGridDropSide, type TMDataGridEditApi, type TMDataGridEditChange, type TMDataGridEditCommitArgs, type TMDataGridEditField, type TMDataGridEditMode, type TMDataGridEditRowProjection, type TMDataGridEditRowSnapshot, type TMDataGridEditState, type TMDataGridEditValueMap, type TMDataGridEditValueMapArgs, type TMDataGridEditingOptions, type TMDataGridEditorArgs, type TMDataGridEditorComponent, type TMDataGridExpandAllArgs, type TMDataGridExpandTarget, type TMDataGridExportApi, type TMDataGridExportColumns, type TMDataGridExportData, type TMDataGridExportFormat, type TMDataGridExportOptions, type TMDataGridExportPickerRequest, type TMDataGridExportRows, type TMDataGridExportSettings, type TMDataGridExportValueGetter, type TMDataGridExportWriteOptions, type TMDataGridFeatureFlags, type TMDataGridFeatures, type TMDataGridFieldValidate, type TMDataGridFilterControlArgs, type TMDataGridFilterControlComponent, type TMDataGridFilterControlLayout, type TMDataGridFilterOperator, type TMDataGridFilterPanelLayout, type TMDataGridFilterPanelProps, TMDataGridFilterPills, type TMDataGridFilterPillsProps, type TMDataGridFilterSidebarSide, type TMDataGridFilterSurface, type TMDataGridFilterValue, TMDataGridFilterValueInput, type TMDataGridFilterValueShape, type TMDataGridFiltersOptions, type TMDataGridFiltersSettings, type TMDataGridFooterProps, type TMDataGridJsonFormatOptions, type TMDataGridLabels, type TMDataGridLabelsOverride, type TMDataGridMenuColumnsProps, type TMDataGridMenuExportProps, type TMDataGridMenuProps, TMDataGridMultiSelectEditor, TMDataGridNumberEditor, type TMDataGridOption, type TMDataGridOptionsArgs, type TMDataGridOptionsSource, type TMDataGridPaginationActions, type TMDataGridPaginationApi, type TMDataGridPaginationControls, type TMDataGridPaginationSlotArgs, type TMDataGridPaginationState, type TMDataGridPersistKey, type TMDataGridPersistence, type TMDataGridProps, type TMDataGridQuickSearchMode, type TMDataGridRangeBounds, type TMDataGridRowAddArgs, type TMDataGridRowClickModifiers, type TMDataGridRowContextMenuArgs, type TMDataGridRowContextMenuRenderer, type TMDataGridRowData, type TMDataGridRowDeleteArgs, type TMDataGridRowEditForm, type TMDataGridRowStyle, type TMDataGridRowValidators, type TMDataGridSaveDraftsArgs, type TMDataGridSaveDraftsResponse, type TMDataGridSaveDraftsResult, type TMDataGridSaveOutcomes, type TMDataGridScrollAlign, type TMDataGridScrollToRowArgs, TMDataGridSearch, type TMDataGridSearchProps, TMDataGridSelectEditor, type TMDataGridSelectionMode, type TMDataGridSettingsSlice, type TMDataGridSize, type TMDataGridStorageMode, TMDataGridStringEditor, type TMDataGridTable, type TMDataGridTableMeta, type TMDataGridTableProps, type TMDataGridTableValidateArgs, type TMDataGridTableValidators, type TMDataGridToolbarProps, type TMDataGridTsvFormatOptions, type TMDataGridUiActions, type TMDataGridUiState, type TMDataGridUiStore, type UseTMDataGridOptions, activeColumnFilters, aggregateColumn, areAllRowsExpanded, autosizeColumn, buildExportData, clearedValueForType, countSelectedExportRows, createTMDataGridColumnHelper, csvExcelFormat, csvFormat, downloadFile, emptyValueForOperator, exportGrid, filterValueShape, formatExportValue, formatFilterLabel, formatGroupValue, fuzzyGlobalFilterFn, getColumnCapabilities, getColumnDefaultOperator, getColumnLabel, getColumnOperators, getColumnRegion, getColumnType, getDisplayedRows, getEditFieldName, getExportableColumns, getGridCapabilities, getGroupDataRows, getOperatorsForType, getSelectableRowIds, getStepTargetColumn, getTMDataGridPaginationApi, guardFormula, hasPendingEdits, isControlColumn, isFilterActive, isGeneratedColumn, isPagingActive, jsonFormat, keepGeneratedColumnsOutermost, mergeLabels, moveColumn, moveColumnByStep, normalizeFieldValidate, openColumnFilter, operatorNeedsValue, operatorTakesArrayValue, operatorTakesRangeValue, optionsToComboboxData, readFeatureFlags, resolveColumnOptions, resolveExpandAll, resolveExportOptions, resolveRangeBounds, resolveRowSelectionClick, toClipboardText, tsvFormat, useTMDataGrid, useTMDataGridContext, useTMDataGridExport, writeClipboardText, writeExportFile };
+export { type BuildExportDataArgs, type ColumnStepArgs, DATA_STATE_SLICES, DEFAULT_EXPORT_OPTIONS, DEFAULT_TMDATAGRID_SIZE, DETAILS_COLUMN_ID, DgAutocompleteFilter, DgDateRangeFilter, DgRangeSliderFilter, DgTriStateFilter, EDIT_COLUMN_ID, type ExportGridArgs, FILTER_OPERATOR_LABELS, GROUP_COLUMN_ID, type MoveColumnArgs, PERSIST_PAYLOAD_VERSION, ROW_NUMBER_COLUMN_ID, type ResolveRangeBoundsArgs, type ResolveRowSelectionClickArgs, type ResolvedRowSelection, SELECT_COLUMN_ID, SETTINGS_STATE_SLICES, SIZE_CONTROL_SIZE, SIZE_ROW_HEIGHT, TMDATAGRID_LABELS_EN, TMDATAGRID_LABELS_SV, TMDataGrid, type TMDataGridAddRowsOptions, type TMDataGridAddRowsResult, type TMDataGridAggregationName, type TMDataGridApi, TMDataGridBooleanEditor, type TMDataGridCapabilities, type TMDataGridCellEventArgs, type TMDataGridCellPosition, type TMDataGridCellRange, type TMDataGridCellSelectionMode, type TMDataGridClipboardTextOptions, type TMDataGridColSpanArgs, type TMDataGridColumnCapabilities, type TMDataGridColumnEditOptions, type TMDataGridColumnFilter, type TMDataGridColumnFilterOptions, type TMDataGridColumnHelper, type TMDataGridColumnMenuItemsArgs, type TMDataGridColumnMenuItemsRenderer, type TMDataGridColumnMeta, type TMDataGridColumnRegion, type TMDataGridColumnSearchable, type TMDataGridColumnType, type TMDataGridColumnsPanelProps, type TMDataGridCommitAllResult, type TMDataGridContextValue, type TMDataGridCsvFormatOptions, type TMDataGridDataSlice, TMDataGridDateEditor, type TMDataGridDetailsArgs, type TMDataGridDetailsRenderer, TMDataGridDraftActions, type TMDataGridDraftActionsActions, type TMDataGridDraftActionsControls, type TMDataGridDraftActionsProps, type TMDataGridDraftActionsSlotArgs, type TMDataGridDraftActionsState, type TMDataGridDropSide, type TMDataGridEditApi, type TMDataGridEditChange, type TMDataGridEditCommitArgs, type TMDataGridEditField, type TMDataGridEditMode, type TMDataGridEditRowProjection, type TMDataGridEditRowSnapshot, type TMDataGridEditState, type TMDataGridEditValueMap, type TMDataGridEditValueMapArgs, type TMDataGridEditingOptions, type TMDataGridEditorArgs, type TMDataGridEditorComponent, type TMDataGridExpandAllArgs, type TMDataGridExpandTarget, type TMDataGridExportApi, type TMDataGridExportColumns, type TMDataGridExportData, type TMDataGridExportFormat, type TMDataGridExportOptions, type TMDataGridExportPickerRequest, type TMDataGridExportRows, type TMDataGridExportSettings, type TMDataGridExportValueGetter, type TMDataGridExportWriteOptions, type TMDataGridFeatureFlags, type TMDataGridFeatures, type TMDataGridFieldValidate, type TMDataGridFilterControlArgs, type TMDataGridFilterControlComponent, type TMDataGridFilterControlLayout, type TMDataGridFilterFn, type TMDataGridFilterOperator, type TMDataGridFilterPanelLayout, type TMDataGridFilterPanelProps, TMDataGridFilterPills, type TMDataGridFilterPillsProps, type TMDataGridFilterSidebarSide, type TMDataGridFilterSurface, type TMDataGridFilterValue, TMDataGridFilterValueInput, type TMDataGridFilterValueShape, type TMDataGridFiltersOptions, type TMDataGridFiltersSettings, type TMDataGridFooterProps, type TMDataGridJsonFormatOptions, type TMDataGridLabels, type TMDataGridLabelsOverride, type TMDataGridMenuColumnsProps, type TMDataGridMenuExportProps, type TMDataGridMenuProps, TMDataGridMultiSelectEditor, TMDataGridNumberEditor, type TMDataGridOption, type TMDataGridOptionsArgs, type TMDataGridOptionsSource, type TMDataGridPaginationActions, type TMDataGridPaginationApi, type TMDataGridPaginationControls, type TMDataGridPaginationSlotArgs, type TMDataGridPaginationState, type TMDataGridPersistKey, type TMDataGridPersistence, type TMDataGridProps, type TMDataGridQuickSearchMode, type TMDataGridRangeBounds, type TMDataGridRowAddArgs, type TMDataGridRowClickModifiers, type TMDataGridRowContextMenuArgs, type TMDataGridRowContextMenuRenderer, type TMDataGridRowData, type TMDataGridRowDeleteArgs, type TMDataGridRowEditForm, type TMDataGridRowStyle, type TMDataGridRowValidators, type TMDataGridSaveDraftsArgs, type TMDataGridSaveDraftsResponse, type TMDataGridSaveDraftsResult, type TMDataGridSaveOutcomes, type TMDataGridScrollAlign, type TMDataGridScrollToRowArgs, TMDataGridSearch, type TMDataGridSearchProps, TMDataGridSelectEditor, type TMDataGridSelectionMode, type TMDataGridSettingsSlice, type TMDataGridSize, type TMDataGridStorageMode, TMDataGridStringEditor, type TMDataGridTable, type TMDataGridTableMeta, type TMDataGridTableProps, type TMDataGridTableValidateArgs, type TMDataGridTableValidators, type TMDataGridToolbarProps, type TMDataGridTsvFormatOptions, type TMDataGridUiActions, type TMDataGridUiState, type TMDataGridUiStore, type UseTMDataGridOptions, activeColumnFilters, aggregateColumn, areAllRowsExpanded, autosizeColumn, buildExportData, clearedValueForType, countSelectedExportRows, createTMDataGridColumnHelper, csvExcelFormat, csvFormat, downloadFile, emptyValueForOperator, exportGrid, filterValueShape, formatExportValue, formatFilterLabel, formatGroupValue, fuzzyGlobalFilterFn, getColumnCapabilities, getColumnDefaultOperator, getColumnLabel, getColumnOperators, getColumnRegion, getColumnType, getDisplayedRows, getEditFieldName, getExportableColumns, getGridCapabilities, getGroupDataRows, getOperatorsForType, getSelectableRowIds, getStepTargetColumn, getTMDataGridPaginationApi, guardFormula, hasPendingEdits, isControlColumn, isFilterActive, isGeneratedColumn, isPagingActive, jsonFormat, keepGeneratedColumnsOutermost, matchesFilter, mergeLabels, moveColumn, moveColumnByStep, normalizeFieldValidate, openColumnFilter, operatorNeedsValue, operatorTakesArrayValue, operatorTakesRangeValue, optionsToComboboxData, readFeatureFlags, resolveColumnOptions, resolveExpandAll, resolveExportOptions, resolveRangeBounds, resolveRowSelectionClick, tmDataGridFilterFn, toClipboardText, tsvFormat, useTMDataGrid, useTMDataGridContext, useTMDataGridExport, writeClipboardText, writeExportFile };