@jielga/tmdatagrid 0.2.0 → 0.5.0

package/src/tmdatagrid/components/TMDataGridDetailsColumn.tsx

@@ -0,0 +1,160 @@
+import { UnstyledButton } from "@mantine/core";
+import {
+  useCellControlTabIndex,
+  useTMDataGridContext,
+} from "../TMDataGridContext";
+import type { ColumnDef, Row, RowData } from "@tanstack/react-table";
+import { useSelector } from "@tanstack/react-store";
+import classes from "./TMDataGridDetailsColumn.module.css";
+import { ChevronRightIcon } from "./icons";
+import { areAllRowsExpanded, resolveExpandAll } from "../core/expanding";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+
+export const DETAILS_COLUMN_ID = "__details__";
+
+/**
+ * The chevron that opens a row's detail panel.
+ *
+ * Expansion is read through a subscription rather than from
+ * `row.getIsExpanded()` in the component body: the `row` identity survives an
+ * expand, so the React Compiler would cache the call along with it and the
+ * chevron would never turn. Same reason the select checkbox subscribes.
+ */
+function DetailsCell<TData extends RowData>({
+  row,
+}: {
+  row: Row<TMDataGridFeatures, TData>;
+}) {
+  const { labels } = useTMDataGridContext();
+  const expanded = useSelector(row.table.store, () => row.getIsExpanded());
+  // See useCellControlTabIndex: a body control is reached by stepping into its
+  // cell, not by Tab, or the grid would have one tab stop per mounted row.
+  const tabIndex = useCellControlTabIndex();
+
+  // Group rows open into their children, not into a panel — see the body's
+  // `showsDetails`. Their cells are aggregated, so this lane is already blank
+  // on them; the guard is what makes that a decision rather than a side effect.
+  if (row.getIsGrouped()) return null;
+
+  return (
+    <UnstyledButton
+      className={classes.detailsToggle}
+      tabIndex={tabIndex}
+      aria-expanded={expanded}
+      aria-label={expanded ? labels.hideDetails : labels.showDetails}
+      // The row underneath may select or highlight on click; opening a panel is
+      // its own gesture and must not also trigger those.
+      onClick={(event) => {
+        event.stopPropagation();
+        row.toggleExpanded();
+      }}
+    >
+      <span className={classes.chevron} data-expanded={expanded}>
+        <ChevronRightIcon size={16} stroke={1.6} />
+      </span>
+    </UnstyledButton>
+  );
+}
+
+/**
+ * Expand-all / collapse-all for the lane, the way the checkbox column's header
+ * selects and clears every row.
+ *
+ * Deliberately not `table.toggleAllRowsExpanded()`: that writes the `expanded`
+ * state's whole-table form, and one state holds both the tree and the panels —
+ * so it would unfold every group as well. Only the data rows are touched here;
+ * whatever the tree was showing, it goes on showing. See resolveExpandAll.
+ */
+function DetailsHeader<TData extends RowData>({
+  table,
+}: {
+  table: TMDataGridTable<TData>;
+}) {
+  const { labels } = useTMDataGridContext();
+  // Pre-paginated: expand-all means every row the filters left, not the page
+  // that happens to be on screen. Same model `getCanSomeRowsExpand` reads.
+  const detailRows = () => table.getPrePaginatedRowModel().flatRows;
+
+  const allExpanded = useSelector(table.store, (state) =>
+    areAllRowsExpanded({
+      rows: detailRows(),
+      expanded: state.expanded,
+      target: "details",
+    }),
+  );
+
+  return (
+    <UnstyledButton
+      className={classes.detailsToggle}
+      aria-expanded={allExpanded}
+      aria-label={
+        allExpanded ? labels.collapseAllDetails : labels.expandAllDetails
+      }
+      // Partly expanded opens the rest rather than closing what is already
+      // open — the same reading as an indeterminate select-all box.
+      onClick={() =>
+        table.setExpanded(
+          resolveExpandAll({
+            rows: detailRows(),
+            expanded: table.store.state.expanded,
+            target: "details",
+            expand: !allExpanded,
+          }),
+        )
+      }
+    >
+      <span className={classes.chevron} data-expanded={allExpanded}>
+        <ChevronRightIcon size={16} stroke={1.6} />
+      </span>
+    </UnstyledButton>
+  );
+}
+
+/**
+ * The generated details lane, prepended whenever `renderDetails` is set.
+ *
+ * Structural, like the checkbox and tree columns: fixed width, pinned to the
+ * left after both of them, not hideable, not movable and not resizable. A
+ * toggle that wandered off to the right of the grid — or hid itself — would
+ * leave rows with panels no one can open.
+ *
+ * Last of the three because it acts on one record: the checkbox picks rows out
+ * and the tree says which group they are in, and only then is there a row to
+ * open.
+ *
+ * Nothing stops a second toggle elsewhere: `row.toggleExpanded()` is the whole
+ * interface, and this lane is only the one the grid ships.
+ */
+export function createDetailsColumn<TData extends RowData>(
+  label = "Details",
+): ColumnDef<TMDataGridFeatures, TData, unknown> {
+  return {
+    id: DETAILS_COLUMN_ID,
+    meta: {
+      label,
+      align: "center",
+      // Structurally the last of the generated lanes.
+      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,
+    // Its visibility is not the user's to set: hiding it would strand every
+    // panel behind a control that is no longer there.
+    enableHiding: false,
+    // Structurally pinned to the left; users shouldn't be able to move it.
+    enablePinning: false,
+    header: ({ table }) => <DetailsHeader table={table} />,
+    cell: ({ row }) => <DetailsCell row={row} />,
+    // Deliberately no `aggregatedCell`: on a group row every cell outside the
+    // grouped column counts as aggregated, and blank is the right answer here —
+    // groups expand into their rows, not into a panel.
+  };
+}

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

@@ -18,3 +18,18 @@
   align-items: flex-end;
   gap: var(--mantine-spacing-xs);
 }
+
+.filterPanelHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--mantine-spacing-md);
+  padding-bottom: var(--mantine-spacing-xs);
+}
+
+.filterPanelFooter {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--mantine-spacing-md);
+}

package/src/tmdatagrid/components/TMDataGridFilterPanel.tsx

@@ -1,16 +1,29 @@
-import { ActionIcon, Button, Select, Stack, TextInput } from "@mantine/core";
+import {
+  ActionIcon,
+  Button,
+  MultiSelect,
+  Select,
+  Stack,
+  Text,
+  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 {
+  optionsToComboboxData,
+  resolveColumnOptions,
+} from "../core/columnOptions";
 import { getColumnLabel, getColumnType } from "../core/columnUtils";
 import {
   type TMDataGridFilterOperator,
   type TMDataGridFilterValue,
-  FILTER_OPERATOR_LABELS,
   getDefaultOperator,
   getOperatorsForType,
   isTMDataGridFilterValue,
   operatorNeedsValue,
+  operatorTakesArrayValue,
 } from "../core/filterOperators";
 import { CloseIcon } from "./icons";
 
@@ -27,12 +40,33 @@ function asFilterValue(value: unknown): TMDataGridFilterValue {
  * free — the state is forwarded to the server instead of a row model.
  */
 export function TMDataGridFilterPanel() {
-  const { table, ui, controlSize } = useTMDataGridContext();
+  const { table, ui, labels, controlSize } = useTMDataGridContext();
   const opened = useSelector(ui, (state) => state.filterPanelOpen);
   const columnFilters = useSelector(
     table.store,
     (state) => state.columnFilters,
   );
+  const panelRef = useRef<HTMLDivElement>(null);
+
+  // Clicking away hides the panel, 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 (panelRef.current?.contains(target)) return;
+      // The toolbar button toggles the panel itself. Closing from here first
+      // would leave its click reopening what the user meant to close.
+      if (target.closest("[data-dg-filter-toggle]")) return;
+      ui.actions.closeFilterPanel();
+    };
+
+    document.addEventListener("pointerdown", handlePointerDown);
+    return () => document.removeEventListener("pointerdown", handlePointerDown);
+  }, [opened, ui]);
 
   if (!opened) return null;
 
@@ -56,6 +90,18 @@ export function TMDataGridFilterPanel() {
       columnFilters.find((filter) => filter.id === fromColumnId)?.value,
     );
     const target = table.getColumn(toColumnId);
+    const operator = getDefaultOperator(
+      target ? getColumnType(target) : "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 =
+      operatorTakesArrayValue(operator) === Array.isArray(current.value)
+        ? current.value
+        : operatorTakesArrayValue(operator)
+          ? []
+          : "";
     table.setColumnFilters(
       columnFilters
         .filter((filter) => filter.id !== toColumnId)
@@ -63,12 +109,7 @@ export function TMDataGridFilterPanel() {
           filter.id === fromColumnId
             ? {
                 id: toColumnId,
-                value: {
-                  operator: getDefaultOperator(
-                    target ? getColumnType(target) : "string",
-                  ),
-                  value: current.value,
-                } satisfies TMDataGridFilterValue,
+                value: { operator, value } satisfies TMDataGridFilterValue,
               }
             : filter,
         ),
@@ -86,6 +127,29 @@ export function TMDataGridFilterPanel() {
     );
   }
 
+  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 the array/scalar boundary.
+    const value =
+      operatorTakesArrayValue(operator) === Array.isArray(current.value)
+        ? current.value
+        : operatorTakesArrayValue(operator)
+          ? []
+          : "";
+    patchFilter(columnId, { operator, value });
+  }
+
+  /** Clears every filter, including half-typed ones the pills never showed. */
+  function clearAllFilters() {
+    table.setColumnFilters([]);
+    // Same exit as removing the last filter row by hand: an empty panel has
+    // nothing to show but its own buttons.
+    ui.actions.closeFilterPanel();
+  }
+
   function addFilter() {
     const nextColumn = filterableColumns.find(
       (column) => !columnFilters.some((filter) => filter.id === column.id),
@@ -103,14 +167,47 @@ export function TMDataGridFilterPanel() {
     ]);
   }
 
+  const canAddFilter = filterableColumns.some(
+    (column) => !columnFilters.some((filter) => filter.id === column.id),
+  );
+
   return (
-    <div className={classes.filterPanel}>
+    <div
+      ref={panelRef}
+      role="group"
+      aria-label={labels.filters}
+      className={classes.filterPanel}
+      // 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();
+      }}
+    >
+      <div className={classes.filterPanelHeader}>
+        <Text size={controlSize} fw={600}>
+          {labels.filters}
+        </Text>
+        <ActionIcon
+          variant="subtle"
+          color="gray"
+          size="sm"
+          aria-label={labels.closeFilters}
+          onClick={ui.actions.closeFilterPanel}
+        >
+          <CloseIcon size={16} stroke={1.6} />
+        </ActionIcon>
+      </div>
+
       <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 takesArray = operatorTakesArrayValue(value.operator);
+          const scalarValue = typeof value.value === "string" ? value.value : "";
 
           return (
             <div key={filter.id} className={classes.filterRow}>
@@ -118,64 +215,122 @@ export function TMDataGridFilterPanel() {
                 variant="subtle"
                 color="gray"
                 size="lg"
-                aria-label="Remove filter"
+                aria-label={labels.removeFilter}
                 onClick={() => removeFilter(filter.id)}
               >
                 <CloseIcon size={18} stroke={1.6} />
               </ActionIcon>
 
               <Select
-                label="Column"
+                label={labels.filterColumn}
                 size={controlSize}
                 w={160}
                 allowDeselect={false}
+                // Both dropdowns render inside the panel: a portalled one is
+                // outside it in the DOM, and picking an option would read as a
+                // click away and close the panel under the user.
+                comboboxProps={{ withinPortal: false }}
                 data={columnOptions}
                 value={filter.id}
                 onChange={(next) => next && changeFilterColumn(filter.id, next)}
               />
 
               <Select
-                label="Operator"
+                label={labels.filterOperator}
                 size={controlSize}
                 w={170}
                 allowDeselect={false}
+                comboboxProps={{ withinPortal: false }}
                 data={getOperatorsForType(type).map((operator) => ({
                   value: operator,
-                  label: FILTER_OPERATOR_LABELS[operator],
+                  label: labels.operators[operator],
                 }))}
                 value={value.operator}
                 onChange={(next) =>
                   next &&
-                  patchFilter(filter.id, {
-                    operator: next as TMDataGridFilterOperator,
-                  })
+                  changeOperator(filter.id, next as TMDataGridFilterOperator)
                 }
               />
 
-              <TextInput
-                label="Value"
-                size={controlSize}
-                w={180}
-                type={type === "number" && needsValue ? "number" : "text"}
-                disabled={!needsValue}
-                placeholder={needsValue ? "Filter value" : ""}
-                value={needsValue ? value.value : ""}
-                onChange={(event) =>
-                  patchFilter(filter.id, { value: event.currentTarget.value })
-                }
-              />
+              {takesArray && column ? (
+                // The set the cell is tested against. Options come from
+                // `meta.options`; a select column that declares none still
+                // gets the values present in the data, via the faceted index.
+                <MultiSelect
+                  label={labels.filterValue}
+                  size={controlSize}
+                  w={180}
+                  comboboxProps={{ withinPortal: false }}
+                  searchable
+                  data={optionsToComboboxData(
+                    resolveColumnOptions({ table, column, fallback: "faceted" }),
+                  )}
+                  value={Array.isArray(value.value) ? [...value.value] : []}
+                  onChange={(next) => patchFilter(filter.id, { value: next })}
+                />
+              ) : type === "boolean" ? (
+                <Select
+                  label={labels.filterValue}
+                  size={controlSize}
+                  w={180}
+                  comboboxProps={{ withinPortal: false }}
+                  disabled={!needsValue}
+                  clearable
+                  placeholder={needsValue ? labels.filterValuePlaceholder : ""}
+                  data={[
+                    { value: "true", label: labels.booleanTrue },
+                    { value: "false", label: labels.booleanFalse },
+                  ]}
+                  value={needsValue && scalarValue !== "" ? scalarValue : null}
+                  onChange={(next) =>
+                    patchFilter(filter.id, { value: next ?? "" })
+                  }
+                />
+              ) : (
+                <TextInput
+                  label={labels.filterValue}
+                  size={controlSize}
+                  w={180}
+                  type={
+                    !needsValue
+                      ? "text"
+                      : type === "number"
+                        ? "number"
+                        : type === "date"
+                          ? "date"
+                          : "text"
+                  }
+                  disabled={!needsValue}
+                  placeholder={needsValue ? labels.filterValuePlaceholder : ""}
+                  value={needsValue ? scalarValue : ""}
+                  onChange={(event) =>
+                    patchFilter(filter.id, { value: event.currentTarget.value })
+                  }
+                />
+              )}
             </div>
           );
         })}
 
-        <Button
-          variant="subtle"
-          size="compact-sm"
-          style={{ alignSelf: "flex-start" }}
-          onClick={addFilter}
-        >
-          Add filter
-        </Button>
+        <div className={classes.filterPanelFooter}>
+          <Button
+            variant="subtle"
+            size="compact-sm"
+            disabled={!canAddFilter}
+            onClick={addFilter}
+          >
+            {labels.addFilter}
+          </Button>
+          <Button
+            variant="subtle"
+            color="gray"
+            size="compact-sm"
+            disabled={columnFilters.length === 0}
+            onClick={clearAllFilters}
+          >
+            {labels.clearAllFilters}
+          </Button>
+        </div>
       </Stack>
     </div>
   );

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

@@ -0,0 +1,35 @@
+/* Wraps rather than scrolls: the pills are a summary, and a summary that goes
+   off-screen is not one. */
+.filterPills {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: var(--mantine-spacing-xs);
+}
+
+/* Mantine's dark-scheme pill is `dark-7` — the same colour as the body — so a
+   pill sitting on the page rather than inside a `PillsInput` disappears. Both
+   schemes are restated here so the two stay a pair, with a border to keep the
+   shape readable against any surface. Scoped through `.filterPills` for the
+   specificity to beat Mantine's own rule whichever stylesheet loads last. */
+.filterPills .pill {
+  background-color: light-dark(
+    var(--mantine-color-gray-1),
+    var(--mantine-color-dark-5)
+  );
+  color: light-dark(var(--mantine-color-black), var(--mantine-color-dark-0));
+  border: 1px solid
+    light-dark(var(--mantine-color-gray-3), var(--mantine-color-dark-3));
+}
+
+/* The label is a button so a pill can be clicked back open, but it must read as
+   part of the pill — Mantine's own label styles carry the font. */
+.pillLabel {
+  font: inherit;
+  color: inherit;
+  cursor: pointer;
+}
+
+.pillLabel:hover {
+  text-decoration: underline;
+}

package/src/tmdatagrid/components/TMDataGridFilterPills.tsx

@@ -0,0 +1,136 @@
+import { 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";
+import { getColumnLabel, getColumnType } from "../core/columnUtils";
+import {
+  formatFilterLabel,
+  isFilterActive,
+  isTMDataGridFilterValue,
+} from "../core/filterOperators";
+import type { TMDataGridSize } from "../core/sizes";
+import { openColumnFilter, type TMDataGridApi } from "../useTMDataGrid";
+
+export type TMDataGridFilterPillsProps<TData extends RowData> = {
+  /** The object returned by `useTMDataGrid`. */
+  api: TMDataGridApi<TData>;
+  /** Mantine size of the pills. Defaults to `"sm"`. */
+  size?: TMDataGridSize;
+  /** "Clear all" button, shown once two filters are active. Defaults to `true`. */
+  showClearAll?: boolean;
+  /**
+   * Replaces what a click on a pill's label does. The default opens the grid's
+   * filter panel on that column.
+   */
+  onPillClick?: (columnId: string) => void;
+  className?: string;
+};
+
+/**
+ * One pill per active filter — `First name: Sofia ✕` — with the ✕ clearing that
+ * filter and a click on the label opening the filter panel on its column.
+ *
+ * The one grid component that takes the api as a prop instead of reading
+ * context, so it can live anywhere: a page header, a card title, a breadcrumb
+ * row. Renders nothing while no filter is active.
+ *
+ * ```tsx
+ * const grid = useTMDataGrid({ data, columns });
+ *
+ * <Group>
+ *   <Title order={3}>Employees</Title>
+ *   <TMDataGridFilterPills api={grid} />
+ * </Group>
+ * ```
+ *
+ * Half-typed filters are left out: a filter that is not narrowing the rows yet
+ * has nothing to report, which is the same rule the funnel indicator uses.
+ */
+export function TMDataGridFilterPills<TData extends RowData>({
+  api,
+  size = "sm",
+  showClearAll = true,
+  onPillClick,
+  className,
+}: TMDataGridFilterPillsProps<TData>) {
+  const { table, labels } = api;
+  const columnFilters = useSelector(
+    table.store,
+    (state) => state.columnFilters,
+  );
+
+  const activeFilters = columnFilters.filter((filter) =>
+    isFilterActive(filter.value),
+  );
+  if (activeFilters.length === 0) return null;
+
+  return (
+    <div
+      role="group"
+      aria-label={labels.activeFilters}
+      className={[classes.filterPills, className].filter(Boolean).join(" ")}
+    >
+      <Pill.Group size={size}>
+        {activeFilters.map((filter) => {
+          const column = table.getColumn(filter.id);
+          const label = column ? getColumnLabel(column) : filter.id;
+          const value = filter.value;
+          // isFilterActive already vouched for the shape; this narrows it.
+          if (!isTMDataGridFilterValue(value)) return null;
+
+          return (
+            <Pill
+              key={filter.id}
+              size={size}
+              className={classes.pill}
+              withRemoveButton
+              onRemove={() =>
+                table.setColumnFilters(
+                  columnFilters.filter((other) => other.id !== filter.id),
+                )
+              }
+              // Mantine hides its remove button from assistive tech and from
+              // the tab order, because inside a `PillsInput` Backspace is the
+              // way out. These pills stand on their own, so the ✕ has to be a
+              // real button.
+              removeButtonProps={{
+                "aria-label": labels.clearFilter(label),
+                "aria-hidden": false,
+                tabIndex: 0,
+              }}
+            >
+              <UnstyledButton
+                className={classes.pillLabel}
+                onClick={() =>
+                  onPillClick
+                    ? onPillClick(filter.id)
+                    : openColumnFilter(api, filter.id)
+                }
+              >
+                {formatFilterLabel({
+                  label,
+                  type: column ? getColumnType(column) : "string",
+                  filter: value,
+                  operatorLabels: labels.operators,
+                })}
+              </UnstyledButton>
+            </Pill>
+          );
+        })}
+      </Pill.Group>
+
+      {showClearAll && activeFilters.length > 1 && (
+        // Below two pills their own ✕ is the shorter path, so the button would
+        // only be a second way to do the same thing.
+        <Button
+          variant="subtle"
+          color="gray"
+          size="compact-xs"
+          onClick={() => table.setColumnFilters([])}
+        >
+          {labels.clearAllFilters}
+        </Button>
+      )}
+    </div>
+  );
+}

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

@@ -8,3 +8,11 @@
   flex-shrink: 0;
   border-top: 1px solid var(--mantine-color-default-border);
 }
+
+/* Grouping suspends paging. The pager stays put and fades rather than
+   disappearing, so the footer reads as switched off rather than as having
+   vanished — and the row it holds does not change height under the grid. Its
+   controls carry their own `disabled`; this is the label half. */
+.footer[data-paging-suspended="true"] {
+  opacity: 0.55;
+}