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

package/src/components/TMDataGridFilterPanel.module.css

@@ -0,0 +1,54 @@
+/* A plain block of controls. Nothing here positions it - the popup and the
+   sidebar own their own placement, and a consumer placing the panel by hand
+   places it the way any other block. */
+.filterPanel {
+  display: flex;
+  flex-direction: column;
+  gap: var(--mantine-spacing-xs);
+}
+
+/* Column, operator and value side by side, bottom-aligned so their fields line
+   up under labels of differing heights. */
+.filterRow {
+  display: flex;
+  align-items: flex-end;
+  gap: var(--mantine-spacing-xs);
+}
+
+/* The narrow-host layout: the same three fields one under the other, each
+   filling the width, with the ✕ beside the column it removes. A card rather
+   than a bare stack, because without the side-by-side alignment there is
+   nothing else saying where one filter ends and the next begins. */
+.filterRow[data-layout="stacked"] {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  align-items: end;
+  gap: 6px var(--mantine-spacing-xs);
+  padding: var(--mantine-spacing-xs);
+  border: 1px solid var(--mantine-color-default-border);
+  border-radius: var(--mantine-radius-sm);
+}
+
+.filterRow[data-layout="stacked"] .filterRemove {
+  grid-column: 2;
+  grid-row: 1;
+}
+
+.filterRow[data-layout="stacked"] .filterColumnSlot {
+  grid-column: 1;
+  grid-row: 1;
+  min-width: 0;
+}
+
+.filterRow[data-layout="stacked"] .filterOperatorSlot,
+.filterRow[data-layout="stacked"] .filterValueSlot {
+  grid-column: 1 / -1;
+  min-width: 0;
+}
+
+.filterPanelFooter {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--mantine-spacing-md);
+}

package/src/components/TMDataGridFilterPanel.tsx

@@ -0,0 +1,348 @@
+import {
+  ActionIcon,
+  Box,
+  type BoxProps,
+  Button,
+  Select,
+  Stack,
+  TextInput,
+} from "@mantine/core";
+import { useSelector } from "@tanstack/react-store";
+import { useEffect, useRef } from "react";
+import classes from "./TMDataGridFilterPanel.module.css";
+import { useTMDataGridContext } from "../TMDataGridContext";
+import {
+  getColumnDefaultOperator,
+  getColumnOperators,
+  getColumnLabel,
+  getColumnType,
+} from "../core/columnUtils";
+import {
+  type TMDataGridFilterOperator,
+  type TMDataGridFilterValue,
+  emptyValueForOperator,
+  filterValueShape,
+  getDefaultOperator,
+  getOperatorsForType,
+  isTMDataGridFilterValue,
+  operatorNeedsValue,
+} from "../core/filterOperators";
+import type { TMDataGridFilterPanelLayout } from "../core/filterControls";
+import { CloseIcon } from "./icons";
+import { filterControlFor } from "./filters/filterControlFor";
+import { TMDataGridFilterValueInput } from "./filters/TMDataGridFilterValueInput";
+
+const FALLBACK_FILTER: TMDataGridFilterValue = { operator: "contains", value: "" };
+
+function asFilterValue(value: unknown): TMDataGridFilterValue {
+  return isTMDataGridFilterValue(value) ? value : FALLBACK_FILTER;
+}
+
+/** Mantine's style props (`p="md"`, `w={320}`) are set on the panel block. */
+export type TMDataGridFilterPanelProps = BoxProps & {
+   /**
+    * How one filter row is laid out.
+    *
+    * `"row"` - the default - puts column, operator and value side by side,
+    * which wants about 550px. `"stacked"` puts them one under the other, each
+    * filling the width, for a host too narrow for that: the sidebar surface
+    * uses it, and so should a panel you place in a drawer or a narrow column.
+    *
+    * Passed through to every value control as its `layout`, so a
+    * `meta.filter.control` can size itself to the same decision.
+    */
+  layout?: TMDataGridFilterPanelLayout;
+};
+
+/**
+ * The MUI-style filter surface: one row per active column filter, each row a
+ * column / operator / value triple, over an "Add filter" / "Clear all" footer.
+ *
+ * A plain block of controls, the way `TMDataGrid.ColumnsPanel` is - it renders
+ * whenever it is mounted and knows nothing about floating. The chrome that
+ * makes a floating surface (a title, a close button, click-away, Escape)
+ * belongs to the popup and the sidebar, so this can equally be dropped into a
+ * drawer, a page column or a form. See the `filters.surface` option.
+ *
+ * It only ever reads and writes the table's `columnFilters` state, so a
+ * `manualFiltering` grid gets the same panel for free - the state is forwarded
+ * to the server instead of a row model.
+ */
+export function TMDataGridFilterPanel({
+  layout = "row",
+  className,
+  ...others
+}: TMDataGridFilterPanelProps = {}) {
+  const { table, ui, labels, controlSize } = useTMDataGridContext();
+  const columnFilters = useSelector(
+    table.store,
+    (state) => state.columnFilters,
+  );
+  const focusColumnId = useSelector(ui, (state) => state.filterPanelColumnId);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const stacked = layout === "stacked";
+
+  // Whoever pointed at a column - the column menu, a pill, the toolbar button -
+  // meant "let me type here", so the value slot takes the focus. Cleared once
+  // taken, which is what lets the same column be pointed at twice.
+  useEffect(() => {
+    if (focusColumnId === null) return;
+    const row = panelRef.current?.querySelector<HTMLElement>(
+      `[data-dg-part="filter-row"][data-column-id="${CSS.escape(focusColumnId)}"]`,
+    );
+    const slot = row?.querySelector<HTMLElement>("[data-dg-filter-value-slot]");
+    slot
+      ?.querySelector<HTMLElement>(
+        "input:not([type='hidden']), textarea, select, [tabindex]:not([tabindex='-1'])",
+      )
+      ?.focus();
+    ui.actions.focusPanelFilter(null);
+  }, [focusColumnId, ui]);
+
+  const filterableColumns = table
+    .getAllLeafColumns()
+    .filter((column) => column.getCanFilter());
+
+  const columnOptions = filterableColumns.map((column) => ({
+    value: column.id,
+    label: getColumnLabel(column),
+  }));
+
+  function removeFilter(columnId: string) {
+    table.setColumnFilters(
+      columnFilters.filter((filter) => filter.id !== columnId),
+    );
+  }
+
+  function changeFilterColumn(fromColumnId: string, toColumnId: string) {
+    const current = asFilterValue(
+      columnFilters.find((filter) => filter.id === fromColumnId)?.value,
+    );
+    const target = table.getColumn(toColumnId);
+    const operator = target
+      ? getColumnDefaultOperator(target)
+      : getDefaultOperator("string");
+    // The typed value only survives the move while it still fits the new
+    // operator - a text needle has no meaning to an `isAnyOf` set, or a set
+    // to a text input.
+    const value =
+      filterValueShape(operator) === filterValueShape(current.operator)
+        ? current.value
+        : emptyValueForOperator(operator);
+    table.setColumnFilters(
+      columnFilters
+        .filter((filter) => filter.id !== toColumnId)
+        .map((filter) =>
+          filter.id === fromColumnId
+            ? {
+                id: toColumnId,
+                value: { operator, value } satisfies TMDataGridFilterValue,
+              }
+            : filter,
+        ),
+    );
+    // The row now names a different column; put the caret back in its value
+    // slot rather than leaving it on a dropdown whose meaning just changed.
+    ui.actions.focusPanelFilter(toColumnId);
+  }
+
+  function patchFilter(columnId: string, patch: Partial<TMDataGridFilterValue>) {
+    table.setColumnFilters(
+      columnFilters.map((filter) =>
+        filter.id === columnId
+          ? { ...filter, value: { ...asFilterValue(filter.value), ...patch } }
+          : filter,
+      ),
+    );
+  }
+
+  function changeOperator(columnId: string, operator: TMDataGridFilterOperator) {
+    const current = asFilterValue(
+      columnFilters.find((filter) => filter.id === columnId)?.value,
+    );
+    // Same arity rule as changing the column: keep the value across operators
+    // of the same shape, reset it across any shape boundary.
+    const value =
+      filterValueShape(operator) === filterValueShape(current.operator)
+        ? current.value
+        : emptyValueForOperator(operator);
+    patchFilter(columnId, { operator, value });
+  }
+
+  function addFilter() {
+    const nextColumn = filterableColumns.find(
+      (column) => !columnFilters.some((filter) => filter.id === column.id),
+    );
+    if (!nextColumn) return;
+    const operator = getColumnDefaultOperator(nextColumn);
+    table.setColumnFilters([
+      ...columnFilters,
+      {
+        id: nextColumn.id,
+        value: {
+          operator,
+          value: emptyValueForOperator(operator),
+        } satisfies TMDataGridFilterValue,
+      },
+    ]);
+    ui.actions.focusPanelFilter(nextColumn.id);
+  }
+
+  const canAddFilter = filterableColumns.some(
+    (column) => !columnFilters.some((filter) => filter.id === column.id),
+  );
+
+  return (
+    <Box
+      ref={panelRef}
+      role="group"
+      aria-label={labels.filters}
+      data-dg-part="filter-panel"
+      data-layout={layout}
+      className={[classes.filterPanel, className].filter(Boolean).join(" ")}
+      {...others}
+    >
+      <Stack gap="xs">
+        {columnFilters.map((filter) => {
+          const column = table.getColumn(filter.id);
+          const value = asFilterValue(filter.value);
+          const type = column ? getColumnType(column) : "string";
+          const needsValue = operatorNeedsValue(value.operator);
+          const scalarValue = typeof value.value === "string" ? value.value : "";
+          // The same options-and-control decision the header cells make.
+          const { options, ValueControl } =
+            column === undefined
+              ? { options: [], ValueControl: TMDataGridFilterValueInput }
+              : filterControlFor(table, column);
+
+          return (
+            <div
+              key={filter.id}
+              // The row is the handle: a `meta.filter.control` renders whatever
+              // it likes in the value slot, so the one thing a test can always
+              // count on is which row it is in.
+              data-dg-part="filter-row"
+              data-column-id={filter.id}
+              data-layout={layout}
+              className={classes.filterRow}
+            >
+              <ActionIcon
+                variant="subtle"
+                color="gray"
+                size="lg"
+                className={classes.filterRemove}
+                aria-label={labels.removeFilter}
+                data-dg-part="filter-remove"
+                onClick={() => removeFilter(filter.id)}
+              >
+                <CloseIcon size={18} stroke={1.6} />
+              </ActionIcon>
+
+              <div className={classes.filterColumnSlot}>
+                <Select
+                  label={labels.filterColumn}
+                  size={controlSize}
+                  w={stacked ? "100%" : 160}
+                  allowDeselect={false}
+                  // Both dropdowns portal, like every dropdown in the panel:
+                  // drawn inline they are clipped by the grid frame's
+                  // `overflow: hidden` under the popup, or by the sidebar's
+                  // scroller. The popup's click-away exempts portal nodes.
+                  data-dg-part="filter-column"
+                  data={columnOptions}
+                  value={filter.id}
+                  onChange={(next) =>
+                    next && changeFilterColumn(filter.id, next)
+                  }
+                />
+              </div>
+
+              <div className={classes.filterOperatorSlot}>
+                <Select
+                  label={labels.filterOperator}
+                  size={controlSize}
+                  w={stacked ? "100%" : 170}
+                  allowDeselect={false}
+                  data-dg-part="filter-operator"
+                  data={(column
+                    ? getColumnOperators(column)
+                    : getOperatorsForType(type)
+                  ).map((operator) => ({
+                    value: operator,
+                    label: labels.operators[operator],
+                  }))}
+                  value={value.operator}
+                  onChange={(next) =>
+                    next &&
+                    changeOperator(filter.id, next as TMDataGridFilterOperator)
+                  }
+                />
+              </div>
+
+              {/* What the focus effect above aims at. A `meta.filter.control`
+                  may render anything, so the slot is the only landmark the
+                  panel can count on. */}
+              <div className={classes.filterValueSlot} data-dg-filter-value-slot>
+                {column ? (
+                  // `meta.filter.control` if the column declares one, the
+                  // built-in shape-by-operator input otherwise - both through
+                  // the same value-only contract.
+                  <ValueControl
+                    column={column}
+                    table={table}
+                    operator={value.operator}
+                    value={value.value}
+                    onChange={(next) => patchFilter(filter.id, { value: next })}
+                    options={options}
+                    size={controlSize}
+                    labels={labels}
+                    layout={layout}
+                  />
+                ) : (
+                  // The column is gone from the definition; the row survives
+                  // only to be re-pointed or removed.
+                  <TextInput
+                    label={labels.filterValue}
+                    size={controlSize}
+                    w={stacked ? "100%" : 180}
+                    data-dg-part="filter-value"
+                    disabled={!needsValue}
+                    placeholder={needsValue ? labels.filterValuePlaceholder : ""}
+                    value={needsValue ? scalarValue : ""}
+                    onChange={(event) =>
+                      patchFilter(filter.id, {
+                        value: event.currentTarget.value,
+                      })
+                    }
+                  />
+                )}
+              </div>
+            </div>
+          );
+        })}
+
+        <div className={classes.filterPanelFooter}>
+          <Button
+            variant="subtle"
+            size="compact-sm"
+            disabled={!canAddFilter}
+            data-dg-part="filter-add"
+            onClick={addFilter}
+          >
+            {labels.addFilter}
+          </Button>
+          <Button
+            variant="subtle"
+            color="gray"
+            size="compact-sm"
+            disabled={columnFilters.length === 0}
+            data-dg-part="filter-clear-all"
+            onClick={() => table.setColumnFilters([])}
+          >
+            {labels.clearAllFilters}
+          </Button>
+        </div>
+      </Stack>
+    </Box>
+  );
+}

package/src/{tmdatagrid/components → components}/TMDataGridFilterPills.tsx

@@ -1,4 +1,4 @@
-import { Button, Pill, UnstyledButton } from "@mantine/core";
+import { Box, type BoxProps, Button, Pill, UnstyledButton } from "@mantine/core";
 import type { RowData } from "@tanstack/react-table";
 import { useSelector } from "@tanstack/react-store";
 import classes from "./TMDataGridFilterPills.module.css";
@@ -11,7 +11,8 @@ import {
 import type { TMDataGridSize } from "../core/sizes";
 import { openColumnFilter, type TMDataGridApi } from "../useTMDataGrid";
 
-export type TMDataGridFilterPillsProps<TData extends RowData> = {
+/** Mantine's style props (`mb="sm"`, `hiddenFrom="sm"`) are set on the wrapper. */
+export type TMDataGridFilterPillsProps<TData extends RowData> = BoxProps & {
   /** The object returned by `useTMDataGrid`. */
   api: TMDataGridApi<TData>;
   /** Mantine size of the pills. Defaults to `"sm"`. */
@@ -23,7 +24,6 @@ export type TMDataGridFilterPillsProps<TData extends RowData> = {
    * filter panel on that column.
    */
   onPillClick?: (columnId: string) => void;
-  className?: string;
 };
 
 /**
@@ -52,6 +52,7 @@ export function TMDataGridFilterPills<TData extends RowData>({
   showClearAll = true,
   onPillClick,
   className,
+  ...others
 }: TMDataGridFilterPillsProps<TData>) {
   const { table, labels } = api;
   const columnFilters = useSelector(
@@ -65,11 +66,12 @@ export function TMDataGridFilterPills<TData extends RowData>({
   if (activeFilters.length === 0) return null;
 
   return (
-    <div
+    <Box
       role="group"
       aria-label={labels.activeFilters}
       data-dg-part="filter-pills"
       className={[classes.filterPills, className].filter(Boolean).join(" ")}
+      {...others}
     >
       <Pill.Group size={size}>
         {activeFilters.map((filter) => {
@@ -137,6 +139,6 @@ export function TMDataGridFilterPills<TData extends RowData>({
           {labels.clearAllFilters}
         </Button>
       )}
-    </div>
+    </Box>
   );
 }

package/src/components/TMDataGridFilterSurface.module.css

@@ -0,0 +1,54 @@
+/* Chrome shared by the two automatic surfaces. The panel inside them is a
+   plain block; everything that makes one float or sit beside the rows is
+   here. */
+
+.surfaceHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--mantine-spacing-md);
+  padding-bottom: var(--mantine-spacing-xs);
+}
+
+/* Floats over the first body rows, anchored to `.tableWrapper`. Sits below the
+   whole header - group rows and the filter row included - which the table
+   measures onto the wrapper as `--dg-header-stack-height`. The size scale's
+   single-row value is the fallback for the frame before the first
+   measurement. */
+.filterPopup {
+  position: absolute;
+  top: calc(var(--dg-header-stack-height, var(--dg-header-height)) + 2px);
+  left: var(--mantine-spacing-md);
+  z-index: var(--dg-z-filter-popup, 20);
+  padding: var(--mantine-spacing-sm);
+  border-radius: var(--mantine-radius-md);
+  border: 1px solid var(--mantine-color-default-border);
+  background-color: var(--mantine-color-body);
+  box-shadow: var(--mantine-shadow-md);
+}
+
+/* A column of the table wrapper rather than a layer over it: the rows give up
+   the width instead of being covered by it. `flex: none` so the declared
+   width holds whatever the panel inside asks for. */
+.filterSidebar {
+  display: flex;
+  flex-direction: column;
+  flex: none;
+  min-width: 0;
+  padding: var(--mantine-spacing-sm);
+  background-color: var(--mantine-color-body);
+  border-left: 1px solid var(--mantine-color-default-border);
+}
+
+/* On the left it is the same panel with its divider on the other edge, and
+   ahead of the scroll container in the flex order. */
+.filterSidebar[data-side="left"] {
+  order: -1;
+  border-left: none;
+  border-right: 1px solid var(--mantine-color-default-border);
+}
+
+.filterSidebarBody {
+  flex: 1;
+  min-height: 0;
+}

package/src/components/TMDataGridFilterSurface.tsx

@@ -0,0 +1,167 @@
+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 { isElement } from "../core/dom";
+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 (!isElement(target)) 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();
+    };
+
+    // The popup's own document, not the global one: rendered through a
+    // portal into a window opened with `window.open`, the global `document`
+    // is the opener's and never sees a press in the grid's window.
+    const doc = popupRef.current?.ownerDocument ?? document;
+    doc.addEventListener("pointerdown", handlePointerDown);
+    return () => doc.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>
+  );
+}