@jielga/tmdatagrid 2.0.0-beta.2 → 2.0.0-beta.21

package/src/core/resizePreview.ts

@@ -0,0 +1,141 @@
+/**
+ * What a running column resize drag paints, frame by frame.
+ *
+ * The grid's whole layout is one `grid-template-columns` on the grid element -
+ * every row follows it through `subgrid` - so a drag only has to rewrite that
+ * one string. Rendering the drag through React state instead costs a pass over
+ * every mounted cell per pointer move, which is what makes a resize feel heavy
+ * on a wide grid.
+ *
+ * This module computes the frame; `TMDataGridTable` writes it to the DOM and
+ * TanStack commits the width into `columnSizing` when the pointer is released.
+ */
+
+/** One entry of the grid's track list, paired with the column it sizes. */
+export type TMDataGridColumnTrack = {
+  id: string;
+  /** The `grid-template-columns` entry - `120px` or `minmax(120px, 1fr)`. */
+  track: string;
+  /** The exact width where the track is exact, the floor where it is fluid. */
+  minWidth: number;
+};
+
+/** TanStack's transient `columnResizing` state, narrowed to what a frame reads. */
+export type TMDataGridResizeProgress = {
+  isResizingColumn: string | false;
+  columnSizingStart: Array<[string, number]>;
+  deltaPercentage: number | null;
+};
+
+/** A column's declared bounds, as `column_getSize` reads them. */
+export type TMDataGridSizeBounds = { minSize?: number; maxSize?: number };
+
+/** A sticky offset the drag has moved. */
+export type TMDataGridOffsetPatch = {
+  columnId: string;
+  side: "left" | "right";
+  offset: number;
+};
+
+export type TMDataGridResizePreview = {
+  gridTemplateColumns: string;
+  minWidth: number;
+  offsets: Array<TMDataGridOffsetPatch>;
+};
+
+/**
+ * TanStack's own defaults, from `getDefaultColumnSizingColumnDef()`. Not
+ * exported by the package, and the preview has to clamp exactly the way
+ * `column_getSize` will once the width is committed - a preview that rounds
+ * differently makes the column settle by a pixel when the pointer is released.
+ */
+const DEFAULT_MIN_SIZE = 20;
+const DEFAULT_MAX_SIZE = Number.MAX_SAFE_INTEGER;
+
+/** The width `columnSizing` would hold if the drag ended on this delta. */
+function draggedWidth(
+  startWidth: number,
+  deltaPercentage: number,
+  bounds: TMDataGridSizeBounds,
+): number {
+  // Two decimals and the `max(…, 0)` are what `header_getResizeHandler`
+  // commits; the clamp around it is what `column_getSize` applies on read.
+  const dragged =
+    Math.round(Math.max(startWidth + startWidth * deltaPercentage, 0) * 100) /
+    100;
+  return Math.min(
+    Math.max(bounds.minSize ?? DEFAULT_MIN_SIZE, dragged),
+    bounds.maxSize ?? DEFAULT_MAX_SIZE,
+  );
+}
+
+function* laneOffsets(
+  lane: Array<string>,
+  side: "left" | "right",
+  widthOf: (columnId: string) => number,
+): Generator<TMDataGridOffsetPatch> {
+  let offset = 0;
+  for (const columnId of lane) {
+    yield { columnId, side, offset };
+    offset += widthOf(columnId);
+  }
+}
+
+/**
+ * The frame to paint for the drag in `progress`, or `null` when no drag is
+ * running - which is also the answer for the first publish of a gesture, made
+ * before the pointer has moved at all.
+ *
+ * `leftLane` and `rightLane` are the pinned lanes in the order the grid stacks
+ * them: left to right, and outermost last on the right. Their offsets come
+ * back only when the drag is resizing a pinned column, since nothing else
+ * moves them.
+ */
+export function resizePreview({
+  progress,
+  tracks,
+  boundsOf,
+  leftLane,
+  rightLane,
+}: {
+  progress: TMDataGridResizeProgress;
+  tracks: Array<TMDataGridColumnTrack>;
+  boundsOf: (columnId: string) => TMDataGridSizeBounds;
+  leftLane: Array<string>;
+  rightLane: Array<string>;
+}): TMDataGridResizePreview | null {
+  if (progress.isResizingColumn === false) return null;
+  if (progress.columnSizingStart.length === 0) return null;
+
+  const deltaPercentage = progress.deltaPercentage ?? 0;
+  const widths = new Map<string, number>();
+  for (const [columnId, startWidth] of progress.columnSizingStart) {
+    widths.set(
+      columnId,
+      draggedWidth(startWidth, deltaPercentage, boundsOf(columnId)),
+    );
+  }
+
+  const template: Array<string> = [];
+  let minWidth = 0;
+  for (const track of tracks) {
+    const width = widths.get(track.id);
+    template.push(width === undefined ? track.track : `${width}px`);
+    minWidth += width ?? track.minWidth;
+  }
+
+  const inLane = (lane: Array<string>) => lane.some((id) => widths.has(id));
+  const widthOf = (columnId: string) =>
+    widths.get(columnId) ??
+    tracks.find((track) => track.id === columnId)?.minWidth ??
+    0;
+
+  return {
+    gridTemplateColumns: template.join(" "),
+    minWidth,
+    offsets: [
+      ...(inLane(leftLane) ? laneOffsets(leftLane, "left", widthOf) : []),
+      ...(inLane(rightLane) ? laneOffsets(rightLane, "right", widthOf) : []),
+    ],
+  };
+}

package/src/core/summary.ts

@@ -0,0 +1,59 @@
+import {
+  type AggregationContext,
+  aggregationFns,
+  type RowData,
+} from "@tanstack/react-table";
+import type { TMDataGridRowData } from "../TMDataGridContext";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+
+/** The registered aggregation names - the same set `aggregationFn` accepts. */
+export type TMDataGridAggregationName = keyof typeof aggregationFns;
+
+/**
+ * One column aggregated over every filtered row - the number a summary-row
+ * `footer` wants:
+ *
+ * ```tsx
+ * columnHelper.accessor("salary", {
+ *   footer: ({ table }) => sek(Number(aggregateColumn({ table, columnId: "salary" }))),
+ * });
+ * ```
+ *
+ * Filtered rather than paginated rows, so the total covers everything the
+ * filters left (all pages), and follows the filters as they change. Reuses
+ * TanStack's registered aggregation functions; `fn` defaults to `"sum"`.
+ *
+ * Every data row counts once. Grouping builds its group rows from this model
+ * rather than into it, so a grouped grid totals its records, not its records
+ * plus their subtotals; a tree counts parents and children alike.
+ */
+export function aggregateColumn<TData extends RowData>({
+  table,
+  columnId,
+  fn = "sum",
+}: {
+  table: TMDataGridTable<TData>;
+  columnId: string;
+  fn?: TMDataGridAggregationName;
+}): unknown {
+  const erased = table as unknown as TMDataGridTable<TMDataGridRowData>;
+  const column = erased.getColumn(columnId);
+  // A summary for a column the table does not hold has no value.
+  if (!column) return undefined;
+  // `flatRows`, not `rows`: the filtered model nests under `getSubRows`, and
+  // the top-level array would total a tree's roots and drop every child.
+  // Grouping does not nest it - the group rows are built from this model, not
+  // held in it - so a grouped grid is unaffected either way.
+  const rows = erased.getFilteredRowModel().flatRows;
+  // The rows are already every row, so there is nothing below them to select:
+  // `maxDepth: 0`, and no `subRows` or `groupingRow` - this is not a group.
+  const context: AggregationContext<TMDataGridFeatures, TMDataGridRowData> = {
+    column,
+    columnId,
+    maxDepth: 0,
+    getValue: (row) => row.getValue(columnId),
+    rows,
+    table: erased,
+  };
+  return aggregationFns[fn].aggregate(context);
+}

package/src/core/useSettledTableState.ts

@@ -0,0 +1,36 @@
+import { useSelector } from "@tanstack/react-store";
+import { shallow } from "@tanstack/store";
+import type { ReadonlyStore, Store } from "@tanstack/store";
+
+/** The one slice a settled subscription leaves out. */
+const TRANSIENT_SLICE = "columnResizing";
+
+/**
+ * Subscribes to every table state slice except the transient resize state.
+ *
+ * `columnResizing` publishes a new delta on every pointer move of a resize
+ * drag. Nothing renders from those deltas - the divider highlight reads
+ * `isResizingColumn` through its own selector, and the drag itself is painted
+ * straight onto the grid's track list (see `resizePreview`) - so a component
+ * subscribed to the whole store would re-render the grid dozens of times a
+ * second for state it does not show.
+ *
+ * The comparison is shallow over the remaining slices, which is the
+ * granularity TanStack publishes at: a slice keeps its identity until it
+ * changes.
+ */
+export function useSettledTableState<TState extends object>(
+  store: Store<TState> | ReadonlyStore<TState>,
+): void {
+  useSelector(
+    store,
+    (state) => {
+      const settled: Record<string, unknown> = {};
+      for (const [slice, value] of Object.entries(state)) {
+        if (slice !== TRANSIENT_SLICE) settled[slice] = value;
+      }
+      return settled;
+    },
+    { compare: shallow },
+  );
+}

package/src/{tmdatagrid/index.ts → index.ts}

@@ -1,6 +1,5 @@
 export { TMDataGrid, type TMDataGridProps } from "./components/TMDataGrid";
 export {
-  useCellControlTabIndex,
   useTMDataGridContext,
   type TMDataGridContextValue,
   type TMDataGridRowData,
@@ -33,6 +32,10 @@ export {
   useTMDataGrid,
   type UseTMDataGridOptions,
 } from "./useTMDataGrid";
+export {
+  useTMDataGridExport,
+  type TMDataGridExportApi,
+} from "./useTMDataGridExport";
 export {
   TMDataGridFilterPills,
   type TMDataGridFilterPillsProps,
@@ -41,12 +44,21 @@ export {
   TMDataGridSearch,
   type TMDataGridSearchProps,
 } from "./components/TMDataGridSearch";
+export type {
+  TMDataGridMenuColumnsProps,
+  TMDataGridMenuExportProps,
+  TMDataGridMenuProps,
+} from "./components/TMDataGridMenu";
 export {
+  type TMDataGridColumnFilter,
   type TMDataGridColumnType,
   type TMDataGridFilterOperator,
   type TMDataGridFilterValue,
+  type TMDataGridFilterValueShape,
+  activeColumnFilters,
   emptyValueForOperator,
   FILTER_OPERATOR_LABELS,
+  filterValueShape,
   formatFilterLabel,
   getDefaultOperator,
   getOperatorsForType,
@@ -67,13 +79,13 @@ export {
   type TMDataGridOptionsSource,
 } from "./core/columnOptions";
 export {
-  TMDataGridEditActions,
-  type TMDataGridEditActionsActions,
-  type TMDataGridEditActionsControls,
-  type TMDataGridEditActionsProps,
-  type TMDataGridEditActionsSlotArgs,
-  type TMDataGridEditActionsState,
-} from "./components/TMDataGridEditActions";
+  TMDataGridDraftActions,
+  type TMDataGridDraftActionsActions,
+  type TMDataGridDraftActionsControls,
+  type TMDataGridDraftActionsProps,
+  type TMDataGridDraftActionsSlotArgs,
+  type TMDataGridDraftActionsState,
+} from "./components/TMDataGridDraftActions";
 export {
   clearedValueForType,
   getEditFieldName,
@@ -82,12 +94,18 @@ export {
   type TMDataGridEditApi,
   type TMDataGridEditChange,
   type TMDataGridEditCommitArgs,
+  type TMDataGridSaveDraftsArgs,
+  type TMDataGridSaveDraftsResult,
+  type TMDataGridSaveOutcomes,
   type TMDataGridEditCommitDraftsArgs,
+  type TMDataGridAddRowsOptions,
+  type TMDataGridAddRowsResult,
   type TMDataGridEditField,
   type TMDataGridEditMode,
   type TMDataGridEditorArgs,
   type TMDataGridEditorComponent,
   type TMDataGridEditRowProjection,
+  type TMDataGridEditRowSnapshot,
   type TMDataGridEditState,
   type TMDataGridEditValueMap,
   type TMDataGridEditValueMapArgs,
@@ -96,12 +114,25 @@ export {
   type TMDataGridRowDeleteArgs,
   type TMDataGridRowEditForm,
   type TMDataGridRowValidators,
+  type TMDataGridTableValidateArgs,
+  type TMDataGridTableValidators,
 } from "./core/editEngine";
 export type {
   TMDataGridColumnFilterOptions,
   TMDataGridFilterControlArgs,
   TMDataGridFilterControlComponent,
+  TMDataGridFilterControlLayout,
+  TMDataGridFilterPanelLayout,
 } from "./core/filterControls";
+export type {
+  TMDataGridFiltersOptions,
+  TMDataGridFiltersSettings,
+  TMDataGridFilterSidebarSide,
+  TMDataGridFilterSurface,
+} from "./core/filterSurface";
+export type { TMDataGridFilterPanelProps } from "./components/TMDataGridFilterPanel";
+export type { TMDataGridColumnsPanelProps } from "./components/TMDataGridColumnsPanel";
+export type { TMDataGridToolbarProps } from "./components/TMDataGridToolbar";
 export { TMDataGridFilterValueInput } from "./components/filters/TMDataGridFilterValueInput";
 export { DgRangeSliderFilter } from "./components/filters/DgRangeSliderFilter";
 export { DgDateRangeFilter } from "./components/filters/DgDateRangeFilter";
@@ -123,12 +154,14 @@ export { TMDATAGRID_LABELS_SV } from "./core/labelsSv";
 export {
   getColumnDefaultOperator,
   getColumnFilterControl,
+  getColumnOperators,
   getColumnLabel,
   getColumnType,
   isColumnEditableForRow,
   isColumnReorderable,
   isControlColumn,
   isGeneratedColumn,
+  type TMDataGridColumnSearchable,
 } from "./core/columnUtils";
 export { getGroupDataRows } from "./core/grouping";
 export {
@@ -153,19 +186,49 @@ export {
   type TMDataGridRangeBounds,
 } from "./core/cellRange";
 export {
+  buildExportData,
+  countSelectedExportRows,
+  csvExcelFormat,
+  csvFormat,
+  DEFAULT_EXPORT_OPTIONS,
+  downloadFile,
+  exportGrid,
+  formatExportValue,
+  getExportableColumns,
+  guardFormula,
+  jsonFormat,
+  resolveExportOptions,
+  toClipboardText,
+  tsvFormat,
+  writeClipboardText,
+  writeExportFile,
+  type BuildExportDataArgs,
+  type ExportGridArgs,
+  type TMDataGridClipboardTextOptions,
+  type TMDataGridCsvFormatOptions,
+  type TMDataGridExportColumns,
+  type TMDataGridExportData,
+  type TMDataGridExportFormat,
+  type TMDataGridExportOptions,
+  type TMDataGridExportPickerRequest,
+  type TMDataGridExportRows,
+  type TMDataGridExportSettings,
+  type TMDataGridExportValueGetter,
+  type TMDataGridExportWriteOptions,
+  type TMDataGridJsonFormatOptions,
+  type TMDataGridTsvFormatOptions,
+  // Deprecated, gone in the next beta.
   buildCellMatrix,
   buildGridCellMatrix,
   DEFAULT_CELL_EXPORT_OPTIONS,
   downloadTextFile,
   exportGridToCsv,
-  formatExportValue,
-  toClipboardText,
+  fromCellExportOptions,
   toExcelCsv,
-  writeClipboardText,
   type BuildCellMatrixArgs,
   type TMDataGridCellExportOptions,
   type TMDataGridCellMatrix,
-} from "./core/cellExport";
+} from "./core/export";
 export {
   areAllRowsExpanded,
   resolveExpandAll,