@jielga/tmdatagrid 2.1.4 → 2.3.0

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";
@@ -1037,6 +1037,14 @@ type TMDataGridColumnFilterOptions = {
    * See {@link TMDataGridFilterControlComponent}.
    */
   control?: TMDataGridFilterControlComponent;
+  /**
+   * Whether this column's filter goes into the `persist.urlKey` search param.
+   * Defaults to `true`. `false` keeps it out of the param, on read and on
+   * write. Only has an effect when `urlKey` carries `columnFilters`, and since such
+   * a slice is not stored under `dataKey` either, the filter is then not
+   * persisted anywhere.
+   */
+  url?: boolean;
 };
 //#endregion
 //#region .types-tmp/core/filterSurface.d.ts
@@ -1173,11 +1181,31 @@ type TMDataGridSettingsSlice = (typeof SETTINGS_STATE_SLICES)[number];
 type TMDataGridPersistKey<TSlice extends string> = string | readonly [key: string, slices: readonly TSlice[]];
 /** Same values as Mantine's `StorageType`, which the package does not re-export. */
 type TMDataGridStorageMode = "localStorage" | "sessionStorage";
+/**
+ * Reads and writes the one URL search param that `urlKey` names. Replaces the
+ * default, which reads `window.location.search` and writes with
+ * `history.replaceState`, for a router that owns the URL.
+ */
+type TMDataGridUrlStorage = {
+  /** The param's current value, or `null` when the URL has none. */
+  get(name: string): string | null;
+  /** Sets the param to `value`, or removes it when `value` is `null`. */
+  set(name: string, value: string | null): void;
+};
 type TMDataGridPersistence = {
   /** Key for filters, global filter, sorting and pagination. */
   dataKey?: TMDataGridPersistKey<TMDataGridDataSlice>;
   /** Key for column visibility, sizing, order and pinning. */
   settingsKey?: TMDataGridPersistKey<TMDataGridSettingsSlice>;
+  /**
+   * Search param for data slices kept in the URL, so a link opens the grid on
+   * the same state. Takes the slices it lists away from `dataKey`. The param
+   * holds only the slices that differ from the initial state, and carries no
+   * version stamp.
+   */
+  urlKey?: TMDataGridPersistKey<TMDataGridDataSlice>;
+  /** Where `urlKey` reads and writes. Defaults to the browser's URL. */
+  urlStorage?: TMDataGridUrlStorage;
   /** Which storage area to use. Defaults to `"localStorage"`. */
   storageMode?: TMDataGridStorageMode;
   /** Serializes a payload before it is stored. Defaults to `JSON.stringify`. */
@@ -1748,6 +1776,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 +1968,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;
 /**
@@ -2283,8 +2338,9 @@ type UseTMDataGridOptions<TData extends RowData> = Omit<TableOptions<TMDataGridF
   getRowId: NonNullable<TableOptions<TMDataGridFeatures, TData>["getRowId"]>;
 }) & {
   /**
-   * Restore and persist table state across mounts. Two keys, because the two
-   * kinds of state have different lifetimes - see {@link TMDataGridPersistence}.
+   * Restore and persist table state across mounts. Two storage keys, because
+   * the two kinds of state have different lifetimes, and a URL search param
+   * for the data slices a link should carry - see {@link TMDataGridPersistence}.
    *
    * Keep the object referentially stable (module scope or `useMemo`); it is a
    * dependency of the subscription that writes back.
@@ -2679,6 +2735,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
@@ -3285,6 +3350,14 @@ type TMDataGridTableProps<TData extends RowData> = {
    * stay put while the virtualizer mounts and unmounts rows.
    */
   striped?: boolean;
+  /**
+   * Whether a body row takes the hover tint under the pointer. Unset, a row
+   * takes it when the row itself answers a gesture: `selectionMode: "row"`,
+   * a highlight mode, `onRowClick` or `renderRowContextMenu`. Group rows sit
+   * out those gestures and so sit out the tint too. `true` tints every row,
+   * `false` none. The row carries `data-highlight-on-hover` while it applies.
+   */
+  highlightOnHover?: boolean;
   /**
    * Called when the scroll *arrives* at an edge - once per arrival, not per
    * scroll event, and not on mount (the grid starts at the top-left edge).
@@ -3396,7 +3469,7 @@ type TMDataGridTableProps<TData extends RowData> = {
  * no-pagination mode work at any row count. Pagination is opt in through
  * `enablePagination`, or implied by `manualPagination`.
  */
-declare function TMDataGridTable$1<TData extends RowData = TMDataGridRowData>({ onRowClick, onCellClick, onCellDoubleClick, onCellContextMenu, rowClassName, rowStyle, striped, onScrollToTop, onScrollToBottom, onScrollToLeft, onScrollToRight, renderEmptyState, renderRowContextMenu, renderColumnMenuItems, rowContextMenuProps, onReachEnd, reachEndThreshold, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy }: TMDataGridTableProps<TData>): import("react").JSX.Element;
+declare function TMDataGridTable$1<TData extends RowData = TMDataGridRowData>({ onRowClick, onCellClick, onCellDoubleClick, onCellContextMenu, rowClassName, rowStyle, striped, highlightOnHover, onScrollToTop, onScrollToBottom, onScrollToLeft, onScrollToRight, renderEmptyState, renderRowContextMenu, renderColumnMenuItems, rowContextMenuProps, onReachEnd, reachEndThreshold, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy }: TMDataGridTableProps<TData>): import("react").JSX.Element;
 //#endregion
 //#region .types-tmp/components/TMDataGridToolbar.d.ts
 type TMDataGridToolbarProps = BoxProps & {
@@ -3967,4 +4040,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 TMDataGridUrlStorage, 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 };