@jielga/tmdatagrid 2.0.0-beta.11 → 2.0.0-beta.13

package/src/tmdatagrid/components/TMDataGridFilterSurface.tsx

@@ -0,0 +1,162 @@
+import { ActionIcon, ScrollArea, Text } from "@mantine/core";
+import { useSelector } from "@tanstack/react-store";
+import { useEffect, useRef } from "react";
+import classes from "./TMDataGridFilterSurface.module.css";
+import { useTMDataGridContext } from "../TMDataGridContext";
+import { CloseIcon } from "./icons";
+import { TMDataGridFilterPanel } from "./TMDataGridFilterPanel";
+
+/**
+ * The title row both automatic surfaces wear: the "Filters" heading and the
+ * close button that puts the surface away without touching the filters.
+ */
+function FilterSurfaceHeader() {
+  const { ui, labels, controlSize } = useTMDataGridContext();
+  return (
+    <div className={classes.surfaceHeader}>
+      <Text span size={controlSize} fw={600}>
+        {labels.filters}
+      </Text>
+      <ActionIcon
+        variant="subtle"
+        color="gray"
+        size="sm"
+        aria-label={labels.closeFilters}
+        data-dg-part="filter-panel-close"
+        onClick={ui.actions.closeFilterPanel}
+      >
+        <CloseIcon size={16} stroke={1.6} />
+      </ActionIcon>
+    </div>
+  );
+}
+
+/**
+ * Closes the popup once its last filter row goes, covering both ways that
+ * happens - removed by hand, or "Clear all" - without either of them having
+ * to know which surface is showing.
+ *
+ * On the transition to zero, not on being zero: a popup asked to start open
+ * with no filters yet would otherwise close itself before its first paint.
+ */
+function useCloseWhenEmptied(opened: boolean) {
+  const { table, ui } = useTMDataGridContext();
+  const filterCount = useSelector(
+    table.store,
+    (state) => state.columnFilters.length,
+  );
+  const previousCount = useRef(filterCount);
+  useEffect(() => {
+    const emptied = previousCount.current > 0 && filterCount === 0;
+    previousCount.current = filterCount;
+    if (opened && emptied) ui.actions.closeFilterPanel();
+  }, [opened, filterCount, ui]);
+}
+
+/**
+ * `filters.surface: "popup"` - the panel floating over the first body rows,
+ * anchored under the header. The default surface, and the only one before
+ * `filters` existed.
+ *
+ * Everything that makes it floating lives here rather than in the panel: a
+ * pointerdown outside closes it, Escape closes it, and emptying it closes it.
+ *
+ * @internal Rendered by `TMDataGrid.Table`.
+ */
+export function TMDataGridFilterPopup() {
+  const { ui, labels } = useTMDataGridContext();
+  const opened = useSelector(ui, (state) => state.filterPanelOpen);
+  const popupRef = useRef<HTMLDivElement>(null);
+  useCloseWhenEmptied(opened);
+
+  // Clicking away hides the popup, the way any floating surface behaves. On
+  // pointerdown rather than click, so a press that starts outside dismisses it
+  // even when the pointer is released somewhere else.
+  useEffect(() => {
+    if (!opened) return;
+
+    const handlePointerDown = (event: PointerEvent) => {
+      const target = event.target;
+      if (!(target instanceof Element)) return;
+      if (popupRef.current?.contains(target)) return;
+      // The toolbar button toggles the popup itself. Closing from here first
+      // would leave its click reopening what the user meant to close.
+      if (target.closest('[data-dg-part="filter-button"]')) return;
+      // A portalled overlay - a header filter's dropdown, a custom control's
+      // portalled picker - is outside the popup in the DOM but not in meaning:
+      // a press in one is a press in a control, not a click away. Mantine
+      // stamps `data-portal` on every portal node it creates.
+      if (target.closest("[data-portal]")) return;
+      ui.actions.closeFilterPanel();
+    };
+
+    document.addEventListener("pointerdown", handlePointerDown);
+    return () => document.removeEventListener("pointerdown", handlePointerDown);
+  }, [opened, ui]);
+
+  if (!opened) return null;
+
+  return (
+    <div
+      ref={popupRef}
+      data-dg-part="filter-popup"
+      className={classes.filterPopup}
+      aria-label={labels.filters}
+      // Escape is what closes a floating surface, and every control that can
+      // hold focus in here sits inside this element.
+      onKeyDown={(event) => {
+        if (event.key !== "Escape") return;
+        event.stopPropagation();
+        ui.actions.closeFilterPanel();
+      }}
+    >
+      <FilterSurfaceHeader />
+      <TMDataGridFilterPanel />
+    </div>
+  );
+}
+
+/**
+ * `filters.surface: "sidebar"` - the panel beside the table, inside the grid
+ * frame and under the toolbar, taking width from the rows rather than covering
+ * them.
+ *
+ * Not a floating surface: a click in the table is a click on the rows the
+ * sidebar is filtering, so nothing about it dismisses the panel, and clearing
+ * the filters leaves it standing with its "Add filter" button - a place to
+ * work from rather than a thing that appears and goes away. Escape closes it,
+ * because a keyboard user inside it needs a way back out to the grid.
+ *
+ * @internal Rendered by `TMDataGrid.Table`.
+ */
+export function TMDataGridFilterSidebar() {
+  const { ui, filters, labels } = useTMDataGridContext();
+  const opened = useSelector(ui, (state) => state.filterPanelOpen);
+
+  if (!opened) return null;
+
+  return (
+    <div
+      data-dg-part="filter-sidebar"
+      data-side={filters.sidebarSide}
+      className={classes.filterSidebar}
+      style={{ width: filters.sidebarWidth }}
+      aria-label={labels.filters}
+      onKeyDown={(event) => {
+        if (event.key !== "Escape") return;
+        event.stopPropagation();
+        ui.actions.closeFilterPanel();
+      }}
+    >
+      <FilterSurfaceHeader />
+      {/* The panel's rows are as tall as the filters put in them, and the
+          sidebar is as tall as the table beside it - so the overflow is the
+          sidebar's to scroll, not the page's. */}
+      <ScrollArea type="auto" className={classes.filterSidebarBody}>
+        {/* Stacked, not side by side: a filter row wants about 550px laid out
+            in a line, and the sidebar is 280. */}
+        <TMDataGridFilterPanel layout="stacked" />
+      </ScrollArea>
+    </div>
+  );
+}

package/src/tmdatagrid/components/TMDataGridFooter.tsx

@@ -63,6 +63,12 @@ export type TMDataGridPaginationControls = {
   PageSize: () => ReactNode;
   /** The "1–25 of 300" range label. */
   Range: () => ReactNode;
+  /**
+   * The "Page 3 of 200" label - what a server-paged grid usually shows in
+   * place of a row range. Not in the default footer; put it in a
+   * `renderPagination` layout.
+   */
+  PageNumber: () => ReactNode;
   /** The previous/next buttons. */
   Pager: () => ReactNode;
 };
@@ -182,6 +188,26 @@ function PaginationRange() {
   );
 }
 
+function PaginationPageNumber() {
+  const { table, features, labels, controlSize } = useTMDataGridContext();
+  useSettledTableState(table.store);
+  const paging = isPagingActive(table, features);
+  const { pageIndex } = table.store.state.pagination;
+
+  return (
+    <Text span size={controlSize} c="dimmed" data-dg-part="page-number">
+      {paging
+        ? labels.pageNumber({
+            page: pageIndex + 1,
+            pageCount: table.getPageCount(),
+          })
+        : // Same reasoning as the range label: nothing is being sliced, so a
+          // page number would be a lie.
+          labels.groupedAllRows(table.getFilteredRowModel().rows.length)}
+    </Text>
+  );
+}
+
 function PaginationPager() {
   const { table, features, labels } = useTMDataGridContext();
   useSettledTableState(table.store);
@@ -223,7 +249,7 @@ export type TMDataGridFooterProps = {
    *   renderPagination={({ state, actions, Controls }) => (
    *     <Group>
    *       <Controls.PageSize />
-   *       <MyJumpToPage page={state.pageIndex} onJump={actions.setPageIndex} />
+   *       <Controls.PageNumber />
    *       <Controls.Pager />
    *     </Group>
    *   )}
@@ -258,6 +284,7 @@ export function TMDataGridFooter({
     () => ({
       PageSize: () => <PaginationPageSize pageSizeOptions={pageSizeOptions} />,
       Range: PaginationRange,
+      PageNumber: PaginationPageNumber,
       Pager: PaginationPager,
     }),
     [pageSizeOptions],

package/src/tmdatagrid/components/TMDataGridHeaderCell.module.css

@@ -149,6 +149,16 @@
   z-index: 1;
 }
 
+/* The last column's divider straddles inward instead. Half of a 10px box
+   hanging past the last track is 5px of scrollable overflow, which is a
+   permanent horizontal scrollbar under a grid whose columns fit exactly. The
+   grab area keeps its width, wholly inside the cell, and flex-end keeps the
+   visible line on the column edge where every other divider draws it. */
+.headerCell:last-child .columnSeparator {
+  transform: none;
+  justify-content: flex-end;
+}
+
 .columnSeparatorResizable {
   cursor: col-resize;
   touch-action: none;

package/src/tmdatagrid/components/TMDataGridHeaderCell.tsx

@@ -90,7 +90,7 @@ export function TMDataGridHeaderCell({
   renderColumnMenuItems?: TMDataGridColumnMenuItemsRenderer;
 }) {
   const api = useTMDataGridContext();
-  const { table, features, labels } = api;
+  const { table, features, filters, labels } = api;
   const column = header.column;
   const [menuOpened, setMenuOpened] = useState(false);
   const [contextMenuOpened, setContextMenuOpened] = useState(false);
@@ -298,7 +298,9 @@ export function TMDataGridHeaderCell({
       <Menu.Divider key="sort-divider" />,
     );
   }
-  if (canFilter) {
+  // Not under header filters: the item's only job is to reveal a control that
+  // is already on screen, one row below this menu.
+  if (canFilter && !filters.inHeader) {
     menuItems.push(
       <Menu.Item
         key="filter"
@@ -565,6 +567,11 @@ export function TMDataGridHeaderCell({
       onDragLeave={isDropTarget ? handleDragLeave : undefined}
       onDrop={isDropTarget ? handleDrop : undefined}
       style={{
+        // A group header covers the tracks of the leaves under it. Without the
+        // span it would sit in one track and leave the rest of its width with
+        // no cell at all - a gap the body rows scroll up through, since the
+        // header rows above the body are what hides them.
+        gridColumn: header.colSpan > 1 ? `span ${header.colSpan}` : undefined,
         left: pinnedAt === "left" ? layout.offset : undefined,
         right: pinnedAt === "right" ? layout.offset : undefined,
         position: pinnedAt ? "sticky" : undefined,
@@ -606,7 +613,9 @@ export function TMDataGridHeaderCell({
 
       {isLeaf && (
         <div className={classes.headerActions}>
-          {isFiltered && (
+          {/* Dropped under header filters, where the filled-in control below
+              is both the indicator and the way in. */}
+          {isFiltered && !filters.inHeader && (
             <ActionIcon
               className={classes.headerAction}
               data-pinned-visible="true"

package/src/tmdatagrid/components/TMDataGridHeaderFilterRow.module.css

@@ -0,0 +1,51 @@
+/* The second header row, under the group rows and above the body. Same column
+   tracks as every other row, through subgrid, so it follows resizing,
+   reordering and pinning without knowing about any of them.
+
+   Sticky like the header rows above it, and stacked under them by the same
+   measurement: the table writes every header row's `top` inline once it knows
+   how tall the rows before it are. This is the pre-measurement fallback, and
+   it is right for the common case of one header row. */
+.headerFilterRow {
+  display: grid;
+  grid-column: 1 / -1;
+  grid-template-columns: subgrid;
+  position: sticky;
+  top: var(--dg-header-height);
+  z-index: var(--dg-z-header, 6);
+}
+
+.headerFilterCell {
+  display: flex;
+  align-items: center;
+  gap: 2px;
+  min-width: 0;
+  /* A 60px column has room for the input and nothing beside it. Clipping is
+     what keeps the control from spilling over its neighbour; the operator
+     button is the first thing to go. */
+  overflow: hidden;
+  padding: calc(var(--dg-padding) / 2);
+  /* Opaque: the body scrolls underneath it. */
+  background-color: var(--mantine-color-body);
+  border-bottom: 1px solid var(--mantine-color-default-border);
+}
+
+/* The generated lanes - checkbox, details, row number - hold no filter, so
+   they keep the header's own padding rather than a control's. */
+.headerFilterCell[data-control-column="true"] {
+  padding: 0;
+}
+
+.headerFilterValue {
+  flex: 1;
+  min-width: 0;
+}
+
+.headerFilterOperator {
+  flex: none;
+}
+
+.operatorItemActive {
+  font-weight: 600;
+  color: var(--mantine-primary-color-filled);
+}

package/src/tmdatagrid/components/TMDataGridHeaderFilterRow.tsx

@@ -0,0 +1,303 @@
+import { ActionIcon, Menu, Tooltip } from "@mantine/core";
+import { useSelector } from "@tanstack/react-store";
+import { useEffect, useMemo, useRef, useState } from "react";
+import classes from "./TMDataGridHeaderFilterRow.module.css";
+import sticky from "./sticky.module.css";
+import { useTMDataGridContext } from "../TMDataGridContext";
+import {
+  getColumnDefaultOperator,
+  getColumnLabel,
+  getColumnType,
+  isControlColumn,
+} from "../core/columnUtils";
+import {
+  type TMDataGridFilterOperator,
+  type TMDataGridFilterValue,
+  emptyValueForOperator,
+  filterValueShape,
+  getOperatorsForType,
+  isTMDataGridFilterValue,
+} from "../core/filterOperators";
+import { FilterIcon } from "./icons";
+import {
+  filterControlFor,
+  filterOptionsUseFacets,
+} from "./filters/filterControlFor";
+import type { TMDataGridColumnLayout } from "./TMDataGridTable";
+import type { TMDataGridHeader } from "./TMDataGridHeaderCell";
+
+/**
+ * Whether a value says nothing at all - untrimmed, unlike `isFilterActive`,
+ * which is about whether a filter *narrows* anything. A lone space narrows
+ * nothing but is very much something the user typed.
+ */
+function isEmptyValue(value: string | ReadonlyArray<string>): boolean {
+  return Array.isArray(value)
+    ? value.every((entry) => entry === "")
+    : value === "";
+}
+
+/**
+ * One column's filter control, as it appears in the header row: the value
+ * control the column would get in the panel, plus a button for the operator
+ * when the column's type offers more than one.
+ *
+ * The column and operator dropdowns of a panel row have no place here - the
+ * column is the one the cell sits over, and a header cell has room for a value
+ * and not much else. Everything else is the same filter: the same operators,
+ * the same `meta.filter.control`, the same `columnFilters` state.
+ */
+function HeaderFilterControl({ column }: { column: TMDataGridHeader["column"] }) {
+  const { table, labels, controlSize } = useTMDataGridContext();
+  const filterValue = useSelector(
+    table.store,
+    (state) => state.columnFilters.find((filter) => filter.id === column.id)?.value,
+  );
+
+  const type = getColumnType(column);
+  const defaultOperator = getColumnDefaultOperator(column);
+  const current = isTMDataGridFilterValue(filterValue) ? filterValue : undefined;
+  const operator = current?.operator ?? defaultOperator;
+  const value = current?.value ?? emptyValueForOperator(operator);
+  const label = getColumnLabel(column);
+
+  /**
+   * Writes the filter, or drops it entirely once nothing is left to say. A
+   * header control is always on screen, so an empty one has no row to keep
+   * alive the way a panel row does, and leaving the entry behind would put a
+   * filter in `columnFilters` that says nothing.
+   *
+   * Emptiness here is the literal one, not `isFilterActive`'s: that one trims,
+   * and dropping the filter on a value of `" "` would take the space back out
+   * of the input the moment it was typed. An operator the user picked is worth
+   * keeping even with an empty value; the type's own default is not.
+   */
+  function write(next: TMDataGridFilterValue) {
+    const worthKeeping =
+      !isEmptyValue(next.value) || next.operator !== defaultOperator;
+    column.setFilterValue(worthKeeping ? next : undefined);
+  }
+
+  function changeOperator(next: TMDataGridFilterOperator) {
+    // Same arity rule as the panel: keep the value across operators of the
+    // same shape, reset it across any shape boundary.
+    write({
+      operator: next,
+      value:
+        filterValueShape(next) === filterValueShape(operator)
+          ? value
+          : emptyValueForOperator(next),
+    });
+  }
+
+  // Memoized because this row re-renders with the table - on every scroll
+  // frame, for every column - while resolving faceted options walks the
+  // faceted map into a sorted set. TanStack swaps that map's identity whenever
+  // the values behind it change, so it is exactly the right key.
+  const facetKey = filterOptionsUseFacets(column)
+    ? column.getFacetedUniqueValues()
+    : undefined;
+  const { options, ValueControl } = useMemo(
+    () => filterControlFor(table, column),
+    // `facetKey` is a cache key, not something the body reads: the resolution
+    // reaches the faceted map through the column, so nothing here names it.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [table, column, facetKey],
+  );
+  const operators = getOperatorsForType(type);
+
+  return (
+    <>
+      <div className={classes.headerFilterValue} data-dg-filter-value-slot>
+        <ValueControl
+          column={column}
+          table={table}
+          operator={operator}
+          value={value}
+          onChange={(next) => write({ operator, value: next })}
+          options={options}
+          size={controlSize}
+          labels={labels}
+          layout="header"
+        />
+      </div>
+
+      <OperatorMenu
+        columnId={column.id}
+        columnLabel={label}
+        operator={operator}
+        isDefault={operator === defaultOperator}
+        operators={operators}
+        onChange={changeOperator}
+      />
+    </>
+  );
+}
+
+/**
+ * The operator picker beside a header filter's value: which comparison the
+ * column is on, and the list to change it to.
+ *
+ * The tooltip is the only thing saying what the current operator is while the
+ * menu is shut, and the only thing in the way once it is open - so it is held
+ * back while the dropdown shows.
+ */
+function OperatorMenu({
+  columnId,
+  columnLabel,
+  operator,
+  isDefault,
+  operators,
+  onChange,
+}: {
+  columnId: string;
+  columnLabel: string;
+  operator: TMDataGridFilterOperator;
+  isDefault: boolean;
+  operators: ReadonlyArray<TMDataGridFilterOperator>;
+  onChange: (next: TMDataGridFilterOperator) => void;
+}) {
+  const { labels } = useTMDataGridContext();
+  const [opened, setOpened] = useState(false);
+
+  return (
+    <Menu
+      opened={opened}
+      onChange={setOpened}
+      position="bottom-end"
+      shadow="md"
+      width={220}
+      withinPortal
+    >
+      <Menu.Target>
+        <Tooltip
+          label={labels.operators[operator]}
+          openDelay={400}
+          disabled={opened}
+        >
+          <ActionIcon
+            className={classes.headerFilterOperator}
+            variant="subtle"
+            // Tinted while the column is on anything but its default operator -
+            // the one part of the filter the value cannot show.
+            color={isDefault ? "gray" : undefined}
+            size="sm"
+            aria-label={labels.filterOperatorFor(columnLabel)}
+            data-dg-part="header-filter-operator"
+            data-column-id={columnId}
+          >
+            <FilterIcon size={14} stroke={1.6} />
+          </ActionIcon>
+        </Tooltip>
+      </Menu.Target>
+      <Menu.Dropdown>
+        {operators.map((candidate) => (
+          <Menu.Item
+            key={candidate}
+            className={
+              candidate === operator ? classes.operatorItemActive : undefined
+            }
+            onClick={() => onChange(candidate)}
+          >
+            {labels.operators[candidate]}
+          </Menu.Item>
+        ))}
+      </Menu.Dropdown>
+    </Menu>
+  );
+}
+
+/**
+ * `filters.inHeader` - a second header row holding one value control per
+ * filterable column, always visible.
+ *
+ * A header row like the group rows above it, on the same column tracks and
+ * with the same pinned lanes, so resizing, reordering and pinning move the
+ * controls with their columns. It sticks below the group rows rather than at
+ * the top, and carries `data-dg-header-row` so the body's scroll offset counts
+ * it in.
+ *
+ * @internal Rendered by `TMDataGrid.Table`.
+ */
+export function TMDataGridHeaderFilterRow({
+  leafHeaders,
+  layoutFor,
+  ariaRowIndex,
+}: {
+  leafHeaders: ReadonlyArray<TMDataGridHeader>;
+  layoutFor: (columnId: string) => TMDataGridColumnLayout;
+  ariaRowIndex: number;
+}) {
+  const { ui, labels } = useTMDataGridContext();
+  const focusColumnId = useSelector(ui, (state) => state.headerFilterColumnId);
+  const rowRef = useRef<HTMLDivElement>(null);
+
+  // `openColumnFilter` under header filters means "put me in that column's
+  // control" - there is no panel to open. The column may be scrolled out
+  // sideways, so it is brought into view first.
+  useEffect(() => {
+    if (focusColumnId === null) return;
+    const cell = rowRef.current?.querySelector<HTMLElement>(
+      `[data-dg-part="header-filter-cell"][data-column-id="${CSS.escape(focusColumnId)}"]`,
+    );
+    cell?.scrollIntoView({ block: "nearest", inline: "nearest" });
+    cell
+      ?.querySelector<HTMLElement>(
+        "input:not([type='hidden']), textarea, select, [tabindex]:not([tabindex='-1'])",
+      )
+      ?.focus();
+    ui.actions.focusHeaderFilter(null);
+  }, [focusColumnId, ui]);
+
+  return (
+    <div
+      ref={rowRef}
+      role="row"
+      aria-rowindex={ariaRowIndex}
+      // Counted by the same measurement the group rows are: it is part of what
+      // the body scrolls under.
+      data-dg-header-row
+      data-dg-header-filter-row
+      data-dg-part="header-filter-row"
+      // The header/body boundary is this row once it exists, so it wears the
+      // scrolled-under shadow the last group row wears otherwise.
+      className={`${classes.headerFilterRow} ${sticky.headerBoundary}`}
+    >
+      {leafHeaders.map((header) => {
+        const column = header.column;
+        const layout = layoutFor(column.id);
+        return (
+          <div
+            key={header.id}
+            role="columnheader"
+            aria-label={labels.filterOn(getColumnLabel(column))}
+            data-dg-part="header-filter-cell"
+            data-column-id={column.id}
+            data-control-column={isControlColumn(column.id)}
+            className={[
+              classes.headerFilterCell,
+              layout.isBoundary && layout.pinnedAt === "left"
+                ? sticky.stickyLeft
+                : "",
+              layout.isBoundary && layout.pinnedAt === "right"
+                ? sticky.stickyRight
+                : "",
+            ]
+              .filter(Boolean)
+              .join(" ")}
+            style={{
+              left: layout.pinnedAt === "left" ? layout.offset : undefined,
+              right: layout.pinnedAt === "right" ? layout.offset : undefined,
+              position: layout.pinnedAt ? "sticky" : undefined,
+              zIndex: layout.pinnedAt
+                ? "var(--dg-z-header-pinned-cell, 7)"
+                : undefined,
+            }}
+          >
+            {column.getCanFilter() && <HeaderFilterControl column={column} />}
+          </div>
+        );
+      })}
+    </div>
+  );
+}