@jielga/tmdatagrid 2.1.4 → 2.2.0

package/src/core/filterOperators.ts

@@ -1,10 +1,11 @@
 import type {
   ColumnFiltersState,
+  FilterMeta,
   Row,
   RowData,
   TableFeatures,
 } from "@tanstack/react-table";
-import type { TMDataGridTable } from "../useTMDataGrid";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
 
 /**
  * The value shape stored in `columnFilters` for every TMDataGrid column.
@@ -474,6 +475,20 @@ export function matchesFilter(
   }
 }
 
+/**
+ * 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.
+ */
+export 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

package/src/index.ts

@@ -16,6 +16,7 @@ export {
   openColumnFilter,
   type TMDataGridApi,
   type TMDataGridColumnMeta,
+  type TMDataGridColSpanArgs,
   type TMDataGridDetailsArgs,
   type TMDataGridDetailsRenderer,
   type TMDataGridFeatures,
@@ -50,6 +51,7 @@ export type {
 export {
   type TMDataGridColumnFilter,
   type TMDataGridColumnType,
+  type TMDataGridFilterFn,
   type TMDataGridFilterOperator,
   type TMDataGridFilterValue,
   type TMDataGridFilterValueShape,
@@ -60,9 +62,11 @@ export {
   formatFilterLabel,
   getOperatorsForType,
   isFilterActive,
+  matchesFilter,
   operatorNeedsValue,
   operatorTakesArrayValue,
   operatorTakesRangeValue,
+  tmDataGridFilterFn,
 } from "./core/filterOperators";
 export {
   fuzzyGlobalFilterFn,

package/src/useTMDataGrid.tsx

@@ -79,6 +79,7 @@ import {
   tmDataGridFilterFn,
 } from "./core/filterOperators";
 import {
+  DEFAULT_COLUMN_MIN_SIZE,
   getColumnDefaultOperator,
   isControlColumn,
   isGeneratedColumn,
@@ -194,6 +195,28 @@ export 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
@@ -385,6 +408,12 @@ export type TMDataGridDetailsArgs<TData extends RowData> = {
   table: TMDataGridTable<TData>;
 };
 
+/** What a `meta.colSpan` function receives. */
+export type TMDataGridColSpanArgs<TData extends RowData> = {
+  row: Row<TMDataGridFeatures, TData>;
+  table: TMDataGridTable<TData>;
+};
+
 /** Builds the panel shown underneath an expanded row. See `renderDetails`. */
 export type TMDataGridDetailsRenderer<TData extends RowData> = (
   args: TMDataGridDetailsArgs<TData>,
@@ -1556,6 +1585,14 @@ export function useTMDataGrid<TData extends RowData>({
     () => tableRef.current as unknown as TMDataGridQueryTable,
     [],
   );
+  // The grid's `minSize` floor under the consumer's `defaultColumn`, which
+  // still wins per key. Keyed on the consumer's object, because TanStack
+  // memoizes the default column def on `options.defaultColumn` identity.
+  const consumerDefaultColumn = options.defaultColumn;
+  const defaultColumn = useMemo(
+    () => ({ minSize: DEFAULT_COLUMN_MIN_SIZE, ...consumerDefaultColumn }),
+    [consumerDefaultColumn],
+  );
 
   // The sync of `state` into the table's atoms happens inside this call, in
   // the render body, and publishing from there makes React warn about the
@@ -1624,6 +1661,7 @@ export function useTMDataGrid<TData extends RowData>({
           ) as TableOptions<TMDataGridFeatures, TData>["onGroupingChange"],
         }
       : {}),
+    defaultColumn,
     // The rows as shown - see `shown` above. The consumer's own array passes
     // through untouched while nothing is committed.
     data: shown.rows,