@bmsuisse/datagrid 0.32.2 → 0.33.0

package/dist/index.d.ts

@@ -219,6 +219,26 @@ interface BaseColumn<TRow> {
      * override for their own concerns.
      */
     formatForClipboard?: (value: unknown, row: TRow) => string;
+    /**
+     * Computes this column's aggregate cell content from a set of rows — the
+     * same function feeds both `DataGridProps`/`TreeDataGridProps`
+     * `groupBy`'s optional per-group summary row (called once per bucket, with
+     * that bucket's own rows) and `showTotals`'s grand-total row (called once,
+     * with every currently-rendered row). No calculation happens by default:
+     * omit this to leave the column's cell blank in both rows. There's
+     * deliberately no separate "group subtotal" vs. "grand total" variant —
+     * both are just "reduce this set of rows to a value for this column", so
+     * one function covers both.
+     *
+     * `showTotals`'s grand-total row calls this with EVERY currently-rendered
+     * row, which can be an empty array (e.g. a filter narrows the current page
+     * to zero rows) — a bare `rows.reduce((a, b) => ...)` with no seed throws
+     * on an empty array, so seed your reducer (`rows.reduce((a, b) => ..., 0)`)
+     * rather than assuming at least one row. A per-group summary row never
+     * has this problem: a bucket only exists because at least one row produced
+     * its key.
+     */
+    summary?: (rows: TRow[]) => ReactNode;
 }
 type StringColumn<TRow> = BaseColumn<TRow> & {
     type: "string";
@@ -1498,10 +1518,14 @@ interface DataGridProps<TRow> {
      * rendering one full-width `colSpan`'d group-header row before each
      * bucket's own rows, in first-seen bucket order (rows are never re-sorted
      * to cluster a group together — the caller's own sort already determines
-     * which key appears first). Single level only — no nested grouping, no
-     * aggregate/summary calculation; a caller wanting a subtotal computes it
-     * themselves in `renderGroupHeader` off that bucket's own row array.
-     * Operates on whatever `rows` already resolved to — i.e. the current page,
+     * which key appears first). Single level only — no nested grouping. A
+     * caller wanting a combined label (e.g. `"Acme (5 pending)"`) still
+     * computes that themselves in `renderGroupHeader` off that bucket's own
+     * row array; a caller wanting a value aligned under one or more specific
+     * *columns* instead sets `ColumnDef.summary` on those columns — see its
+     * own doc — which renders a second row of per-column cells right below
+     * the label, once at least one visible column defines it. Operates on
+     * whatever `rows` already resolved to — i.e. the current page,
      * if paginated — with no special-casing; pair with a large `pageSize`/
      * `showPagination: false` if a group's full membership should never be
      * split across pages. Omit entirely to disable — no grouping, no header
@@ -1545,6 +1569,17 @@ interface DataGridProps<TRow> {
     onExpandedGroupsChange?: (expanded: Record<string, boolean>) => void;
     /** Alternates body row backgrounds for readability on wide/dense tables. Defaults to true. */
     zebra?: boolean;
+    /**
+     * Renders a `<tfoot>` totals row below the grid's body, with one cell per
+     * visible column computed via that column's own `ColumnDef.summary(rows)`
+     * — `rows` being every row `<DataGrid>` currently has (the current page,
+     * if paginated; same scope `groupBy` itself operates on). A column with no
+     * `summary` renders a blank cell in this row. Independent of `groupBy` —
+     * the two compose (a per-group summary row under each bucket, plus one
+     * grand-total row at the very bottom) but neither requires the other.
+     * Defaults to false: no totals row, unchanged rendering.
+     */
+    showTotals?: boolean;
     /**
      * Enables the built-in inline-editing workflow: any column with
      * `editable` set renders as an interactive editor, edits accumulate
@@ -1575,7 +1610,7 @@ interface DataGridProps<TRow> {
  * (`"server"`). Column filter UI defaults to the type-appropriate widget
  * from `src/filter` unless a column supplies its own `cell` renderer.
  */
-declare function DataGrid<TRow extends RowData>({ columns, dataSource, getRowId, rowActions, headerActions, enableMultiSort, initialState, columnVisibility, renderDetail, enableColumnResizing, columnResizeMode, columnSizing: controlledColumnSizing, onColumnSizingChange, virtualize, showPagination, getRowProps, getRowTestId, gridState, selectedIds: controlledSelectedIds, onSelectedIdsChange, testId, loading: loadingProp, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, editing, cellEditing, }: DataGridProps<TRow>): ReactElement;
+declare function DataGrid<TRow extends RowData>({ columns, dataSource, getRowId, rowActions, headerActions, enableMultiSort, initialState, columnVisibility, renderDetail, enableColumnResizing, columnResizeMode, columnSizing: controlledColumnSizing, onColumnSizingChange, virtualize, showPagination, getRowProps, getRowTestId, gridState, selectedIds: controlledSelectedIds, onSelectedIdsChange, testId, loading: loadingProp, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, showTotals, editing, cellEditing, }: DataGridProps<TRow>): ReactElement;
 
 interface GridStateController {
     state: GridState;
@@ -1921,7 +1956,12 @@ interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
      * than "which root it belongs to" wouldn't have a sensible rendering.
      * Groups appear in first-seen bucket order — roots are never re-sorted to
      * cluster a group together. Omit entirely to disable — no grouping, no
-     * header rows, unchanged default rendering.
+     * header rows, unchanged default rendering. A caller wanting a value
+     * aligned under one or more specific columns (rather than folded into
+     * `renderGroupHeader`'s single label) sets `ColumnDef.summary` on those
+     * columns — see its own doc — which renders a second row of per-column
+     * cells, computed from that bucket's own *root* rows, right below the
+     * label once at least one visible column defines it.
      *
      * Not supported together with virtualization — when both are set,
      * virtualization is silently disabled and the tree renders as a plain,
@@ -1942,6 +1982,17 @@ interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
     onExpandedGroupsChange?: (expanded: Record<string, boolean>) => void;
     /** Alternates body row backgrounds for readability on wide/dense tables. Defaults to true. */
     zebra?: boolean;
+    /**
+     * Renders a `<tfoot>` totals row below the tree, with one cell per visible
+     * column computed via that column's own `ColumnDef.summary(data)` — the
+     * root-level rows in `data`, NOT the flattened tree (a child's value is
+     * usually already reflected in its parent's, so summing every flattened
+     * row would typically double-count). A column with no `summary` renders a
+     * blank cell. Independent of `groupBy` — the two compose (a per-group
+     * summary row under each bucket, plus one grand-total row at the very
+     * bottom) but neither requires the other. Defaults to false.
+     */
+    showTotals?: boolean;
     /**
      * Enables the same built-in inline-editing workflow `<DataGrid>` has:
      * any column with `editable` set renders as an interactive editor
@@ -1970,7 +2021,7 @@ interface TreeDataGridProps<TRow> extends TreeAccessors<TRow> {
  * column's cell matches `treeColumnId` (defaults to `columns[0]`); every
  * other column renders exactly like it would in `<DataGrid>`.
  */
-declare function TreeDataGrid<TRow>({ columns, data, loading, treeColumnId, columnVisibility, getRowId, getChildren, hasChildren, onLoadChildren, initialExpandedLevel, expanded: controlledExpanded, onExpandedChange, childrenMap: controlledChildrenMap, onChildrenMapChange, indentSize, getRowProps, getRowTestId, rowActions, virtualizeThreshold, estimatedRowHeight, maxBodyHeight, testId, selectedIds: controlledSelectedIds, onSelectedIdsChange, getRowSelectionState, isRowSelectionDisabled, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, editing, }: TreeDataGridProps<TRow>): ReactElement;
+declare function TreeDataGrid<TRow>({ columns, data, loading, treeColumnId, columnVisibility, getRowId, getChildren, hasChildren, onLoadChildren, initialExpandedLevel, expanded: controlledExpanded, onExpandedChange, childrenMap: controlledChildrenMap, onChildrenMapChange, indentSize, getRowProps, getRowTestId, rowActions, virtualizeThreshold, estimatedRowHeight, maxBodyHeight, testId, selectedIds: controlledSelectedIds, onSelectedIdsChange, getRowSelectionState, isRowSelectionDisabled, groupBy, renderGroupHeader, defaultGroupsExpanded, expandedGroups: controlledExpandedGroups, onExpandedGroupsChange, zebra, showTotals, editing, }: TreeDataGridProps<TRow>): ReactElement;
 
 interface FlatTreeRow<TRow> {
     row: TRow;

package/dist/index.js

@@ -3245,6 +3245,7 @@ function DataGrid({
   expandedGroups: controlledExpandedGroups,
   onExpandedGroupsChange,
   zebra = true,
+  showTotals = false,
   editing,
   cellEditing
 }) {
@@ -3349,6 +3350,7 @@ function DataGrid({
   const hasFilterRow = visibleColumns.some((column) => isFilterable(column) && column.filterDisplay === "row");
   const headerRuns = useMemo8(() => computeHeaderRuns(visibleColumns), [visibleColumns]);
   const hasHeaderGroups = visibleColumns.some((column) => column.headerGroup);
+  const hasColumnSummary = visibleColumns.some((column) => column.summary);
   function renderFilterWidget(column) {
     const value = filtersByColumn.get(column.id);
     const onChange = (next) => setColumnFilter(column.id, next);
@@ -3826,35 +3828,92 @@ function DataGrid({
       showDetailColumn && isExpanded && renderDetail && /* @__PURE__ */ jsx33("tr", { "data-testid": `${rowTestId}-detail`, children: /* @__PURE__ */ jsx33("td", { colSpan: totalColumnCount, className: "border-b border-border p-2", children: renderDetail(row.original) }) })
     ] }, row.id);
   }
+  function renderGroupSummaryCells(rows2, bgClassName) {
+    return visibleColumns.map((column) => {
+      const cellProps = bodyCellPropsByColumn.get(column.id);
+      return /* @__PURE__ */ jsx33(
+        "td",
+        {
+          className: cn(cellProps?.className, bgClassName, "font-medium", alignClassName(column)),
+          style: cellProps?.style,
+          children: column.summary?.(rows2)
+        },
+        column.id
+      );
+    });
+  }
+  function summaryLeadingCellSpan() {
+    return (showDetailColumn ? 1 : 0) + (showSelectionColumn ? 1 : 0);
+  }
+  function renderGroupSummaryRow(rows2) {
+    const leadingSpan = summaryLeadingCellSpan();
+    const bgClassName = zebra ? "bg-muted" : "bg-background";
+    const fillerClass = cn("border-b border-border p-2", bgClassName);
+    return /* @__PURE__ */ jsxs20("tr", { "data-testid": "group-summary-row", className: "divide-x divide-border", children: [
+      leadingSpan > 0 && /* @__PURE__ */ jsx33("td", { colSpan: leadingSpan, className: fillerClass }),
+      renderGroupSummaryCells(rows2, bgClassName),
+      showRowActionsColumn && /* @__PURE__ */ jsx33("td", { className: fillerClass, "aria-hidden": true })
+    ] });
+  }
+  function renderTotalsFooter() {
+    if (!showTotals || !hasColumnSummary) return null;
+    const summaryRows = tableRows.map((row) => row.original);
+    const leadingSpan = summaryLeadingCellSpan();
+    const fillerClass = "sticky bottom-0 z-20 border-t border-border bg-muted p-2";
+    return /* @__PURE__ */ jsx33("tfoot", { children: /* @__PURE__ */ jsxs20("tr", { "data-testid": "totals-row", className: "divide-x divide-border", children: [
+      leadingSpan > 0 && /* @__PURE__ */ jsx33("td", { colSpan: leadingSpan, className: fillerClass }),
+      visibleColumns.map((column) => {
+        const pinnedProps = pinnedCellProps(column, "header");
+        return /* @__PURE__ */ jsx33(
+          "td",
+          {
+            className: cn(
+              "border-t border-border p-2 font-medium",
+              alignClassName(column),
+              pinnedProps.className,
+              "sticky bottom-0 z-20 bg-muted"
+            ),
+            style: pinnedProps.style,
+            children: column.summary?.(summaryRows)
+          },
+          column.id
+        );
+      }),
+      showRowActionsColumn && /* @__PURE__ */ jsx33("td", { className: fillerClass, "aria-hidden": true })
+    ] }) });
+  }
   function renderGroupHeaderTbody(key, rows2, measureRef, dataIndex) {
     const expanded = isGroupExpanded(key);
-    return /* @__PURE__ */ jsx33("tbody", { ref: measureRef, "data-index": dataIndex, children: /* @__PURE__ */ jsx33("tr", { "data-testid": `group-header-${key}`, children: /* @__PURE__ */ jsx33(
-      "td",
-      {
-        colSpan: totalColumnCount,
-        className: cn("sticky z-20 border-b p-2 font-medium", zebra ? "bg-muted" : "bg-background"),
-        style: { top: groupHeaderTop },
-        children: /* @__PURE__ */ jsxs20(
-          "button",
-          {
-            type: "button",
-            className: "flex w-full items-center gap-1 text-left",
-            onClick: () => toggleGroupExpanded(key),
-            "aria-expanded": expanded,
-            children: [
-              /* @__PURE__ */ jsx33(
-                ChevronRight,
-                {
-                  className: `h-4 w-4 shrink-0 transition-transform${expanded ? " rotate-90" : ""}`,
-                  "aria-hidden": true
-                }
-              ),
-              renderGroupHeader ? renderGroupHeader(key, rows2, expanded) : `${key} (${rows2.length})`
-            ]
-          }
-        )
-      }
-    ) }) }, `group-${key}`);
+    return /* @__PURE__ */ jsxs20("tbody", { ref: measureRef, "data-index": dataIndex, children: [
+      /* @__PURE__ */ jsx33("tr", { "data-testid": `group-header-${key}`, children: /* @__PURE__ */ jsx33(
+        "td",
+        {
+          colSpan: totalColumnCount,
+          className: cn("sticky z-20 border-b p-2 font-medium", zebra ? "bg-muted" : "bg-background"),
+          style: { top: groupHeaderTop },
+          children: /* @__PURE__ */ jsxs20(
+            "button",
+            {
+              type: "button",
+              className: "flex w-full items-center gap-1 text-left",
+              onClick: () => toggleGroupExpanded(key),
+              "aria-expanded": expanded,
+              children: [
+                /* @__PURE__ */ jsx33(
+                  ChevronRight,
+                  {
+                    className: `h-4 w-4 shrink-0 transition-transform${expanded ? " rotate-90" : ""}`,
+                    "aria-hidden": true
+                  }
+                ),
+                renderGroupHeader ? renderGroupHeader(key, rows2, expanded) : `${key} (${rows2.length})`
+              ]
+            }
+          )
+        }
+      ) }),
+      hasColumnSummary && renderGroupSummaryRow(rows2)
+    ] }, `group-${key}`);
   }
   function renderGroupedBucket(bucket) {
     const expanded = isGroupExpanded(bucket.key);
@@ -4135,7 +4194,8 @@ function DataGrid({
                     )
                   ),
                   paddingBottom > 0 && /* @__PURE__ */ jsx33("tbody", { children: /* @__PURE__ */ jsx33("tr", { "aria-hidden": "true", children: /* @__PURE__ */ jsx33("td", { colSpan: totalColumnCount, style: { padding: 0, border: "none", height: paddingBottom } }) }) })
-                ] }) : groupedBuckets ? groupedBuckets.map((bucket) => renderGroupedBucket(bucket)) : tableRows.map((row) => renderRow(row))
+                ] }) : groupedBuckets ? groupedBuckets.map((bucket) => renderGroupedBucket(bucket)) : tableRows.map((row) => renderRow(row)),
+                renderTotalsFooter()
               ] }),
               hasCellEditing && /* @__PURE__ */ jsx33(
                 SelectionOverlay,
@@ -4427,6 +4487,7 @@ function TreeDataGrid({
   expandedGroups: controlledExpandedGroups,
   onExpandedGroupsChange,
   zebra = true,
+  showTotals = false,
   editing
 }) {
   const accessors = useMemo10(
@@ -4521,6 +4582,10 @@ function TreeDataGrid({
     for (const column of visibleColumns) map.set(column.id, `p-2 ${alignClassName(column)}`);
     return map;
   }, [visibleColumns]);
+  const hasColumnSummary = visibleColumns.some((column) => column.summary);
+  function renderGroupSummaryCells(rows) {
+    return visibleColumns.map((column) => /* @__PURE__ */ jsx34("td", { className: cn(bodyTdClassByColumn.get(column.id), "font-medium"), children: column.summary?.(rows) }, column.id));
+  }
   const scrollRef = useRef13(null);
   const shouldVirtualize = !groupBy && flatRows.length > virtualizeThreshold;
   const virtualizer = useVirtualizer2({
@@ -4675,6 +4740,24 @@ function TreeDataGrid({
                   )
                 }
               ) }),
+              hasColumnSummary && /* @__PURE__ */ jsxs21(
+                "tr",
+                {
+                  "data-testid": `group-summary-${bucket.key}`,
+                  className: "border-b border-border divide-x divide-border",
+                  children: [
+                    showSelectionColumn && /* @__PURE__ */ jsx34(
+                      "td",
+                      {
+                        className: cn("p-2", zebra ? "bg-muted" : "bg-background"),
+                        style: { width: SELECTION_COLUMN_WIDTH }
+                      }
+                    ),
+                    renderGroupSummaryCells(bucket.roots),
+                    showRowActionsColumn && /* @__PURE__ */ jsx34("td", { className: cn("p-2", zebra ? "bg-muted" : "bg-background"), "aria-hidden": true })
+                  ]
+                }
+              ),
               groupExpanded && (() => {
                 const startIndex = groupedRender?.startIndexByBucket.get(bucket.key) ?? 0;
                 return bucket.flatRows.map((flatRow, i) => renderRow(flatRow, startIndex + i));
@@ -4692,7 +4775,36 @@ function TreeDataGrid({
                 style: { padding: 0, border: "none", height: paddingBottom }
               }
             ) })
-          ] }) : flatRows.map((flatRow, index) => renderRow(flatRow, index)) })
+          ] }) : flatRows.map((flatRow, index) => renderRow(flatRow, index)) }),
+          showTotals && hasColumnSummary && // Sticky to the BOTTOM of the scroll container, mirroring the
+          // `<thead>`'s own `top-0` stickiness — see `<DataGrid>`'s own
+          // `renderTotalsFooter` for the full reasoning. Summarizes `data`
+          // (the root-level rows), not `flatRows`/`allFlatRows` — same
+          // "roots only" scope `groupBy` itself uses, and for the same
+          // reason (a child's value is usually already folded into its
+          // parent's).
+          /* @__PURE__ */ jsx34("tfoot", { children: /* @__PURE__ */ jsxs21("tr", { "data-testid": "totals-row", className: "divide-x divide-border", children: [
+            showSelectionColumn && /* @__PURE__ */ jsx34(
+              "td",
+              {
+                className: "sticky bottom-0 z-20 border-t border-border bg-muted p-2",
+                style: { width: SELECTION_COLUMN_WIDTH }
+              }
+            ),
+            visibleColumns.map((column) => /* @__PURE__ */ jsx34(
+              "td",
+              {
+                style: column.width ? { width: column.width } : void 0,
+                className: cn(
+                  "sticky bottom-0 z-20 border-t border-border bg-muted p-2 font-medium",
+                  alignClassName(column)
+                ),
+                children: column.summary?.(data)
+              },
+              column.id
+            )),
+            showRowActionsColumn && /* @__PURE__ */ jsx34("td", { className: "sticky bottom-0 z-20 border-t border-border bg-muted p-2", "aria-hidden": true })
+          ] }) })
         ] })
       }
     )