@jielga/tmdatagrid 2.0.0-beta.9 → 2.0.1

package/src/components/TMDataGridHeaderFilterRow.tsx

@@ -0,0 +1,301 @@
+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,
+  getColumnOperators,
+  isControlColumn,
+} from "../core/columnUtils";
+import {
+  type TMDataGridFilterOperator,
+  type TMDataGridFilterValue,
+  emptyValueForOperator,
+  filterValueShape,
+  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 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 = getColumnOperators(column);
+
+  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) || undefined}
+            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>
+  );
+}

package/src/components/TMDataGridMenu.tsx

@@ -0,0 +1,357 @@
+import {
+  ActionIcon,
+  Checkbox,
+  Menu,
+  ScrollArea,
+  Tooltip,
+  type MenuProps,
+} from "@mantine/core";
+import {
+  useState,
+  type ComponentPropsWithoutRef,
+  type KeyboardEvent,
+  type ReactNode,
+} from "react";
+import { useTMDataGridContext } from "../TMDataGridContext";
+import {
+  getColumnLabel,
+  showColumnSearch,
+  type TMDataGridColumnSearchable,
+} from "../core/columnUtils";
+import type {
+  TMDataGridExportColumns,
+  TMDataGridExportOptions,
+} from "../core/export";
+import { useTMDataGridExport } from "../useTMDataGridExport";
+import { useHideableColumns } from "./useHideableColumns";
+import { BurgerIcon, DownloadIcon, RestoreIcon } from "./icons";
+
+/**
+ * The column toggles are `Menu.Item`s with a `Checkbox.Indicator` in front,
+ * not `Menu.CheckboxItem`: that one draws its tick only when checked, so an
+ * unchecked column next to the consumer's own items reads as a plain action.
+ * A box that is visibly empty says "off, click to turn on".
+ *
+ * `Menu.Item` writes `role="menuitem"` after the props it is given, so the
+ * checkbox role goes on through `renderRoot`, the polymorphic escape hatch.
+ */
+const asCheckboxItem = (props: ComponentPropsWithoutRef<"button">) => (
+  <button {...props} role="menuitemcheckbox" />
+);
+
+export type TMDataGridMenuProps = Omit<MenuProps, "children"> & {
+  /** The dropdown's content: Mantine `Menu.Item`s and the `TMDataGrid.Menu.*` items. */
+  children: ReactNode;
+  /** Replaces the burger icon on the trigger. */
+  icon?: ReactNode;
+  /** Tooltip and `aria-label` of the trigger. Default `labels.menuButton`. */
+  label?: string;
+};
+
+export type TMDataGridMenuColumnsProps = {
+  /**
+   * Renders a `Menu.Search` above the toggles: `"auto"` (the default) from
+   * six hideable columns, `true` always, `false` never. Use `false` inside a
+   * `Menu.Sub`.
+   */
+  searchable?: TMDataGridColumnSearchable;
+};
+
+// Documented on the `TMDataGridMenu` export below.
+function TMDataGridMenuRoot({
+  children,
+  icon,
+  label,
+  ...menuProps
+}: TMDataGridMenuProps) {
+  const { labels, controlSize } = useTMDataGridContext();
+  const triggerLabel = label ?? labels.menuButton;
+
+  return (
+    <Menu
+      position="bottom-end"
+      shadow="md"
+      width={260}
+      withinPortal
+      {...menuProps}
+    >
+      {/* The Tooltip goes outside the Target. Inside it, the Target's
+          `aria-expanded` / `aria-controls` reach the Tooltip, which hands
+          unknown props to its own floating label, not to the button. */}
+      <Tooltip label={triggerLabel} openDelay={400}>
+        <Menu.Target>
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            size={controlSize}
+            aria-label={triggerLabel}
+            data-dg-part="menu-button"
+          >
+            {icon ?? <BurgerIcon size={18} stroke={1.6} />}
+          </ActionIcon>
+        </Menu.Target>
+      </Tooltip>
+      <Menu.Dropdown>{children}</Menu.Dropdown>
+    </Menu>
+  );
+}
+
+/**
+ * The whole column chooser as menu items: a search box, one checkbox item per
+ * hideable column, show/hide all, and Reset layout. Renders nothing when no
+ * column can be hidden.
+ *
+ * `searchable` is only for a block at the top level of a dropdown.
+ * `Menu.Search` registers on the root menu context (`hasSearch`), which
+ * switches off type-ahead and the arrow-key handling of every dropdown of that
+ * menu, so a search inside a `Menu.Sub` breaks the parent menu's keyboard
+ * behaviour.
+ */
+export function TMDataGridMenuColumns({
+  searchable = "auto",
+}: TMDataGridMenuColumnsProps) {
+  const { labels, controlSize } = useTMDataGridContext();
+  const { columns } = useHideableColumns();
+  const [search, setSearch] = useState("");
+
+  if (columns.length === 0) return null;
+
+  const withSearch = showColumnSearch(searchable, columns.length);
+
+  // `Menu.Search` walks every item of the dropdown from the top, so with items
+  // placed above this block ArrowDown from the search lands on the first of
+  // those - and Enter runs it. When something precedes the block, ArrowDown
+  // moves focus to the first listed column instead; when nothing does,
+  // Mantine's own walk already starts there and is left alone.
+  const handleSearchKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key !== "ArrowDown") return;
+    const dropdown = event.currentTarget.closest('[role="menu"]');
+    const first = dropdown?.querySelector('[role^="menuitem"]');
+    const firstToggle = dropdown?.querySelector<HTMLElement>(
+      '[data-dg-part="columns-toggle"]',
+    );
+    if (!first || !firstToggle || first === firstToggle) return;
+    event.preventDefault();
+    firstToggle.focus();
+  };
+
+  return (
+    <>
+      {withSearch && (
+        <Menu.Search
+          value={search}
+          onChange={(event) => setSearch(event.currentTarget.value)}
+          onKeyDown={handleSearchKeyDown}
+          placeholder={labels.columnsSearchPlaceholder}
+          size={controlSize}
+          data-dg-part="columns-search"
+        />
+      )}
+      <TMDataGridMenuColumnToggles search={search} />
+      <Menu.Divider />
+      <TMDataGridMenuShowHideAll />
+      <TMDataGridMenuResetLayout />
+    </>
+  );
+}
+
+/**
+ * One checkbox item per hideable column, narrowed to `search` when one is
+ * given. Renders nothing when no column can be hidden.
+ */
+export function TMDataGridMenuColumnToggles({ search }: { search?: string }) {
+  const { labels, controlSize } = useTMDataGridContext();
+  const { columns, columnVisibility } = useHideableColumns();
+
+  if (columns.length === 0) return null;
+
+  const needle = (search ?? "").trim().toLowerCase();
+  const listed = needle
+    ? columns.filter((column) =>
+        getColumnLabel(column).toLowerCase().includes(needle),
+      )
+    : columns;
+
+  return (
+    <ScrollArea.Autosize mah={260} type="auto">
+      {listed.length === 0 ? (
+        <Menu.Label>{labels.columnsNoMatch(search ?? "")}</Menu.Label>
+      ) : (
+        listed.map((column) => {
+          const visible = columnVisibility[column.id] !== false;
+          return (
+            <Menu.Item
+              key={column.id}
+              renderRoot={asCheckboxItem}
+              aria-checked={visible}
+              closeMenuOnClick={false}
+              leftSection={
+                <Checkbox.Indicator checked={visible} size={controlSize} />
+              }
+              onClick={() => column.toggleVisibility(!visible)}
+              data-dg-part="columns-toggle"
+              data-column-id={column.id}
+            >
+              {getColumnLabel(column)}
+            </Menu.Item>
+          );
+        })
+      )}
+    </ScrollArea.Autosize>
+  );
+}
+
+/**
+ * Shows or hides every listed column at once. Renders nothing when no column
+ * can be hidden.
+ */
+export function TMDataGridMenuShowHideAll() {
+  const { labels, controlSize } = useTMDataGridContext();
+  const { columns, shownCount, setAllVisible } = useHideableColumns();
+
+  if (columns.length === 0) return null;
+
+  const all = shownCount === columns.length;
+  // Some shown but not all: an indeterminate box, and a click shows all - the
+  // same reading as the panel's checkbox.
+  const some = shownCount > 0 && !all;
+
+  return (
+    <Menu.Item
+      renderRoot={asCheckboxItem}
+      aria-checked={some ? "mixed" : all}
+      closeMenuOnClick={false}
+      leftSection={
+        <Checkbox.Indicator
+          checked={all}
+          indeterminate={some}
+          size={controlSize}
+        />
+      }
+      onClick={() => setAllVisible(!all)}
+      data-dg-part="columns-toggle-all"
+    >
+      {labels.columnsShowHideAll}
+    </Menu.Item>
+  );
+}
+
+/**
+ * Resets the whole layout, not only visibility: order, widths, pinning and
+ * grouping go back too. Not `table.resetColumnVisibility()`, which resets to
+ * `initialState` - and under persistence the mount built that *from* the
+ * persisted payload.
+ */
+export function TMDataGridMenuResetLayout() {
+  const { labels, resetSettings } = useTMDataGridContext();
+
+  return (
+    <Menu.Item
+      leftSection={<RestoreIcon size={16} stroke={1.6} />}
+      onClick={() => resetSettings()}
+      data-dg-part="columns-reset"
+    >
+      {labels.columnsReset}
+    </Menu.Item>
+  );
+}
+
+/** Per-item overrides of the grid's `exportOptions`, and the item's text. */
+export type TMDataGridMenuExportProps = Omit<
+  TMDataGridExportOptions,
+  "columns"
+> & {
+  /**
+   * Which columns the item writes: `"visible"`, `"all"`, a list of ids, or
+   * `"custom"` - a picker listing every exportable column with the visible
+   * ones ticked, and the download on its Export button. Defaults to the grid's
+   * `exportOptions.columns`.
+   */
+  columns?: TMDataGridExportColumns | "custom";
+  /**
+   * The item's text. Defaults to `labels.exportAll`, or for the selected-rows
+   * item `labels.exportSelected(count)`. Two items offering two formats need
+   * two texts, which is what this is for.
+   */
+  label?: ReactNode;
+};
+
+/** The item's props as export options, with `"custom"` set aside for the picker. */
+function splitExportProps({ label, columns, ...rest }: TMDataGridMenuExportProps) {
+  const custom = columns === "custom";
+  const options: TMDataGridExportOptions = custom
+    ? rest
+    : { ...rest, columns };
+  return { label, custom, options };
+}
+
+/**
+ * Downloads every filtered and sorted row, all pages, in the grid's export
+ * format. Props override `exportOptions` for this item alone, which is how one
+ * menu offers two formats.
+ */
+export function TMDataGridMenuExport(props: TMDataGridMenuExportProps) {
+  const { label, custom, options } = splitExportProps(props);
+  const { ui, labels } = useTMDataGridContext();
+  const { exportAll } = useTMDataGridExport(options);
+
+  return (
+    <Menu.Item
+      leftSection={<DownloadIcon size={16} stroke={1.6} />}
+      onClick={() => {
+        if (custom) ui.actions.openExportPicker({ rows: "all", options });
+        else void exportAll();
+      }}
+      data-dg-part="menu-export"
+    >
+      {label ?? labels.exportAll}
+    </Menu.Item>
+  );
+}
+
+/**
+ * Downloads the selected rows, in grid order. Disabled while nothing is
+ * selected; renders nothing when row selection is off, since then there is
+ * never anything for it to do.
+ */
+export function TMDataGridMenuExportSelected(props: TMDataGridMenuExportProps) {
+  const { label, custom, options } = splitExportProps(props);
+  const { ui, labels } = useTMDataGridContext();
+  const { exportSelected, selectedCount, canExportSelected } =
+    useTMDataGridExport(options);
+
+  if (!canExportSelected) return null;
+
+  return (
+    <Menu.Item
+      leftSection={<DownloadIcon size={16} stroke={1.6} />}
+      disabled={selectedCount === 0}
+      onClick={() => {
+        if (custom) ui.actions.openExportPicker({ rows: "selected", options });
+        else void exportSelected();
+      }}
+      data-dg-part="menu-export-selected"
+    >
+      {label ?? labels.exportSelected(selectedCount)}
+    </Menu.Item>
+  );
+}
+
+/**
+ * Burger menu in the grid's top-right corner, holding whatever the consumer
+ * puts in it. Every Mantine `Menu` prop is accepted and wins over the defaults
+ * below.
+ *
+ * It always renders. It cannot know whether its children render anything, so
+ * a menu holding only `TMDataGrid.Menu.Columns` on a grid where nothing can be
+ * hidden still shows its button over an empty dropdown - leave the menu out of
+ * the toolbar in that case.
+ */
+export const TMDataGridMenu = Object.assign(TMDataGridMenuRoot, {
+  Columns: TMDataGridMenuColumns,
+  ColumnToggles: TMDataGridMenuColumnToggles,
+  ShowHideAll: TMDataGridMenuShowHideAll,
+  ResetLayout: TMDataGridMenuResetLayout,
+  Export: TMDataGridMenuExport,
+  ExportSelected: TMDataGridMenuExportSelected,
+});