@jielga/tmdatagrid 2.0.0-beta.8 → 2.0.0

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,
+});

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

@@ -1,10 +1,11 @@
 import { Checkbox } from "@mantine/core";
 import { useSelector } from "@tanstack/react-store";
-import type { ColumnDef, Row, RowData } from "@tanstack/react-table";
+import type { Row, RowData } from "@tanstack/react-table";
 import {
-  useCellControlTabIndex,
+  useBodyControlTabIndex,
   useTMDataGridContext,
 } from "../TMDataGridContext";
+import { isMouseEvent } from "../core/dom";
 import {
   getDisplayedRows,
   getSelectableRowIds,
@@ -62,7 +63,7 @@ function SelectAllCheckbox<TData extends RowData>({
  * change - the same reason the rest of the chrome reads them. See
  * readFeatureFlags.
  */
-function SelectAllHeader<TData extends RowData>({
+export function SelectAllHeader<TData extends RowData>({
   table,
 }: {
   table: TMDataGridTable<TData>;
@@ -72,7 +73,7 @@ function SelectAllHeader<TData extends RowData>({
   return <SelectAllCheckbox table={table} />;
 }
 
-function SelectRowCheckbox<TData extends RowData>({
+export function SelectRowCheckbox<TData extends RowData>({
   row,
 }: {
   row: Row<TMDataGridFeatures, TData>;
@@ -80,12 +81,14 @@ function SelectRowCheckbox<TData extends RowData>({
   // Cells render inside the grid's provider, so the checkbox can reach the
   // chrome store - it needs the shift-click pivot, and the feature flags to know
   // which row model a range is measured over.
-  const { ui, features, labels } = useTMDataGridContext();
-  // Out of the tab order once the grid has a cell cursor - see
-  // useCellControlTabIndex. Enter on the lane still steps in, and Space on any
-  // cell of the row ticks it.
-  const tabIndex = useCellControlTabIndex();
+  const { ui, features, labels, edit } = useTMDataGridContext();
+  const tabIndex = useBodyControlTabIndex();
   const isGroupRow = row.subRows.length > 0;
+  // A deletion mark makes the row unselectable (see `enableRowSelection` in
+  // the hook), and the box below reads that through `getCanSelect`. The
+  // mark lives in the edit store, so the subscription is what re-renders
+  // the box when it lands - the row and cell identities do not change.
+  useSelector(edit.store, (state) => state.deletedRowIds.includes(row.id));
 
   // A group row is never selected by id: `rowSelection` only holds the leaves,
   // and TanStack's `getIsSelected()` is a plain lookup in that map. A group
@@ -109,6 +112,8 @@ function SelectRowCheckbox<TData extends RowData>({
   return (
     <Checkbox
       size="xs"
+      // See useBodyControlTabIndex: under cell selection Enter steps into the
+      // lane, the row's Tab walk reaches it, and Space on any cell ticks it.
       tabIndex={tabIndex}
       aria-label={isGroupRow ? labels.selectGroup : labels.selectRow}
       data-dg-part="select-row"
@@ -127,7 +132,7 @@ function SelectRowCheckbox<TData extends RowData>({
       // silently loses the clicked row, which `onChange` then toggles back off.
       onChange={(event) => {
         const native = event.nativeEvent;
-        const isMouse = native instanceof MouseEvent;
+        const isMouse = isMouseEvent(native);
         const resolved = resolveRowSelectionClick({
           rows: getDisplayedRows(row.table, features),
           rowId: row.id,
@@ -149,46 +154,3 @@ function SelectRowCheckbox<TData extends RowData>({
     />
   );
 }
-
-/**
- * The generated checkbox column, prepended under
- * `selectionMode: "checkbox"` (the default) or `"checkboxAndHighlight"`.
- */
-export function createSelectColumn<TData extends RowData>(
-  label = "Checkbox selection",
-): ColumnDef<TMDataGridFeatures, TData, unknown> {
-  return {
-    id: SELECT_COLUMN_ID,
-    meta: {
-      label,
-      align: "center",
-      // Structurally the first column; it also anchors the left pinned lane, so
-      // no other column can be moved in front of it.
-      enableOrdering: false,
-    },
-    // A system lane: as wide as the control it holds and no wider. Fixed at
-    // every scale - the control does not grow with the font size, so neither
-    // should its track.
-    size: 36,
-    minSize: 36,
-    maxSize: 36,
-    enableResizing: false,
-    enableSorting: false,
-    enableColumnFilter: false,
-    enableGlobalFilter: false,
-    // Not a column the user chose, so not one they can switch off: hiding the
-    // lane would take the grid's only way to select a row with it, with the
-    // row-selection state left behind and no way back to it. Keeping it out of
-    // "Manage columns" follows from this - the panel lists what can be hidden.
-    enableHiding: false,
-    // Structurally pinned to the left; users shouldn't be able to move it.
-    enablePinning: false,
-    header: ({ table }) => <SelectAllHeader table={table} />,
-    cell: ({ row }) => <SelectRowCheckbox row={row} />,
-    // Every cell on a group row that is not the grouped column counts as
-    // aggregated, this lane included, and an aggregated cell with nothing
-    // declared renders blank. Without this the checkbox would disappear from
-    // exactly the rows that select a whole group. See renderCellContent.
-    aggregatedCell: ({ row }) => <SelectRowCheckbox row={row} />,
-  };
-}