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

package/src/components/TMDataGridToolbar.module.css

@@ -0,0 +1,21 @@
+.toolbar {
+  display: flex;
+  align-items: center;
+  gap: var(--mantine-spacing-xs);
+  padding: 6px var(--mantine-spacing-xs);
+  min-height: 42px;
+  flex-shrink: 0;
+}
+
+/* `withBottomBorder`: the line the header draws under itself, on the toolbar. */
+.toolbar[data-with-bottom-border] {
+  border-bottom: 1px solid var(--mantine-color-default-border);
+}
+
+.toolbarSpacer {
+  flex: 1;
+}
+
+.summaryCount {
+  white-space: nowrap;
+}

package/src/components/TMDataGridToolbar.tsx

@@ -0,0 +1,181 @@
+import {
+  ActionIcon,
+  Box,
+  type BoxProps,
+  Loader,
+  Text,
+  Tooltip,
+} from "@mantine/core";
+import { useSelector } from "@tanstack/react-store";
+import type { ReactNode } from "react";
+import classes from "./TMDataGridToolbar.module.css";
+import { useTMDataGridContext } from "../TMDataGridContext";
+import { getGridCapabilities } from "../core/capabilities";
+import { useSettledTableState } from "../core/useSettledTableState";
+import { isFilterActive } from "../core/filterOperators";
+import { FilterIcon } from "./icons";
+import { seedColumnFilter } from "../useTMDataGrid";
+
+export type TMDataGridToolbarProps = BoxProps & {
+  children?: ReactNode;
+  /**
+   * Draws a 1px line under the toolbar in the theme's default border colour -
+   * the same line the header draws under itself. Defaults to `false`.
+   */
+  withBottomBorder?: boolean;
+};
+
+/**
+ * Row above the grid. Compose it from the pieces below, or anything else.
+ * Takes Mantine's style props (`mb="sm"`, `px="md"`, `hiddenFrom="sm"`) and
+ * sets them on the row.
+ */
+export function TMDataGridToolbar({
+  children,
+  withBottomBorder = false,
+  className,
+  mod,
+  ...others
+}: TMDataGridToolbarProps) {
+  return (
+    <Box
+      data-dg-part="toolbar"
+      className={[classes.toolbar, className].filter(Boolean).join(" ")}
+      mod={[{ "with-bottom-border": withBottomBorder }, mod]}
+      {...others}
+    >
+      {children}
+    </Box>
+  );
+}
+
+/** Pushes the following toolbar items to the right. Takes Mantine's style props. */
+export function TMDataGridToolbarSpacer({ className, ...others }: BoxProps) {
+  return (
+    <Box
+      className={[classes.toolbarSpacer, className].filter(Boolean).join(" ")}
+      {...others}
+    />
+  );
+}
+
+/**
+ * A small spinner shown while `meta.loading` is true, and nothing otherwise.
+ *
+ * The body only shows its loading state while the grid is *empty* - a
+ * server-driven grid refetching with rows on screen keeps showing them, which
+ * is right, but leaves nothing saying a fetch is running. This is that signal,
+ * and the consumer decides where it sits by placing it in the toolbar:
+ *
+ * ```tsx
+ * <TMDataGrid.Toolbar>
+ *   <TMDataGrid.SummaryCount />
+ *   <TMDataGrid.Spacer />
+ *   <TMDataGrid.LoadingIndicator />
+ *   <TMDataGrid.FilterButton />
+ * </TMDataGrid.Toolbar>
+ * ```
+ */
+export function TMDataGridLoadingIndicator() {
+  const { table, labels } = useTMDataGridContext();
+  if (table.options.meta?.loading !== true) return null;
+  return <Loader size="xs" data-dg-part="loading" aria-label={labels.loading} />;
+}
+
+/**
+ * Visible rows over total rows. On a server-driven grid, set
+ * `meta.totalRowCount` for the denominator - the client never sees every row.
+ * Without it the count is rendered alone, since the fallback denominator would
+ * be the rows the server sent for the current page: a plausible-looking wrong
+ * total, and on an unfiltered first page the same number twice.
+ */
+export function TMDataGridSummaryCount({ children }: { children?: ReactNode }) {
+  const { table, controlSize } = useTMDataGridContext();
+  useSettledTableState(table.store);
+
+  const serverDriven =
+    table.options.manualFiltering === true ||
+    table.options.manualPagination === true;
+  const shown = table.getRowCount();
+  const total =
+    table.options.meta?.totalRowCount ??
+    (serverDriven ? undefined : table.getPreFilteredRowModel().rows.length);
+
+  return (
+    <Text
+      span
+      size={controlSize}
+      c="dimmed"
+      className={classes.summaryCount}
+      data-dg-part="summary-count"
+    >
+      {children !== undefined
+        ? children
+        : total === undefined
+          ? `${shown}`
+          : `${shown} / ${total}`}
+    </Text>
+  );
+}
+
+/**
+ * Toggles the grid's filter surface - the popup or the sidebar, whichever
+ * `filters.surface` names - seeding a filter row on the first filterable
+ * column. The count of active filters tints it.
+ *
+ * Renders nothing when no column can be filtered (`enableColumnFilters:
+ * false`), and nothing under `filters.surface: "none"`, where there is no
+ * automatic surface for it to toggle. Read `ui.state.filterPanelOpen` and
+ * render your own control if a hand-placed panel wants one.
+ */
+export function TMDataGridFilterButton() {
+  const api = useTMDataGridContext();
+  const { table, ui, features, filters, labels, controlSize } = api;
+  const opened = useSelector(ui, (state) => state.filterPanelOpen);
+  const columnFilters = useSelector(
+    table.store,
+    (state) => state.columnFilters,
+  );
+  const activeCount = columnFilters.filter((filter) =>
+    isFilterActive(filter.value),
+  ).length;
+
+  if (!getGridCapabilities(table, features).canFilterAny) return null;
+  if (filters.surface === "none") return null;
+
+  return (
+    <Tooltip label={labels.filters} openDelay={400}>
+      <ActionIcon
+        variant={opened || activeCount > 0 ? "light" : "subtle"}
+        color={activeCount > 0 ? undefined : "gray"}
+        size={controlSize}
+        aria-label={labels.filters}
+        // Also what the panel's click-away handler tests for, so that a click
+        // here reads as a toggle rather than as a click outside.
+        data-dg-part="filter-button"
+        onClick={() => {
+          if (opened) {
+            ui.actions.closeFilterPanel();
+            return;
+          }
+          // Not `openColumnFilter`: that one honours header filters and
+          // focuses the header control instead of opening anything. This
+          // button's whole job is to open the surface it belongs to, which a
+          // grid may well have alongside header filters.
+          //
+          // Seeded only when the panel would otherwise be empty: with filters
+          // already in state it has rows to show, and seeding would stack a
+          // blank row on the first filterable column on top of them.
+          const seedColumn =
+            columnFilters.length === 0
+              ? table.getAllLeafColumns().find((column) => column.getCanFilter())
+              : undefined;
+          if (seedColumn) seedColumnFilter(api, seedColumn.id);
+          ui.actions.openFilterPanel(seedColumn?.id ?? null);
+        }}
+      >
+        <FilterIcon size={16} stroke={1.6} />
+      </ActionIcon>
+    </Tooltip>
+  );
+}

package/src/{tmdatagrid/components → components}/editors/TMDataGridBooleanEditor.tsx

@@ -2,7 +2,7 @@ import { Checkbox } from "@mantine/core";
 import type { TMDataGridEditorArgs } from "../../core/editEngine";
 import { getColumnLabel } from "../../core/columnUtils";
 import { useTMDataGridContext } from "../../TMDataGridContext";
-import { useFieldError, useFieldValue } from "./editorShared";
+import { useFieldInvalid, useFieldValue } from "./editorShared";
 
 /** The built-in editor for `meta.type: "boolean"` - a focused checkbox. */
 export function TMDataGridBooleanEditor({
@@ -12,7 +12,7 @@ export function TMDataGridBooleanEditor({
 }: TMDataGridEditorArgs) {
   const { labels } = useTMDataGridContext();
   const value = useFieldValue(field);
-  const error = useFieldError(field);
+  const invalid = useFieldInvalid(field);
   return (
     <Checkbox
       size={size}
@@ -21,7 +21,7 @@ export function TMDataGridBooleanEditor({
       checked={value === true}
       onChange={(event) => field.handleChange(event.currentTarget.checked)}
       onBlur={field.handleBlur}
-      error={error}
+      error={invalid}
     />
   );
 }

package/src/{tmdatagrid/components → components}/editors/TMDataGridDateEditor.tsx

@@ -3,7 +3,7 @@ import { useRef } from "react";
 import type { TMDataGridEditorArgs } from "../../core/editEngine";
 import { getColumnLabel } from "../../core/columnUtils";
 import { useTMDataGridContext } from "../../TMDataGridContext";
-import { useFieldError, useFieldValue } from "./editorShared";
+import { useFieldInvalid, useFieldValue } from "./editorShared";
 
 /**
  * The built-in editor for `meta.type: "date"` - the native
@@ -17,7 +17,7 @@ export function TMDataGridDateEditor({
 }: TMDataGridEditorArgs) {
   const { labels } = useTMDataGridContext();
   const value = useFieldValue(field);
-  const error = useFieldError(field);
+  const invalid = useFieldInvalid(field);
   // The cell's original shape decides what the editor writes back: a `Date`
   // cell keeps getting Dates, an ISO-string cell keeps getting strings -
   // decided once at open, so clearing and retyping cannot flip the type.
@@ -49,7 +49,7 @@ export function TMDataGridDateEditor({
         );
       }}
       onBlur={field.handleBlur}
-      error={error}
+      error={invalid}
     />
   );
 }

package/src/{tmdatagrid/components → components}/editors/TMDataGridMultiSelectEditor.tsx

@@ -6,7 +6,7 @@ import {
 } from "../../core/columnOptions";
 import { getColumnLabel } from "../../core/columnUtils";
 import { useTMDataGridContext } from "../../TMDataGridContext";
-import { useFieldError, useFieldValue } from "./editorShared";
+import { useFieldInvalid, useFieldValue } from "./editorShared";
 
 /**
  * The built-in editor for `meta.type: "multiSelect"` - cells holding string
@@ -22,7 +22,7 @@ export function TMDataGridMultiSelectEditor({
 }: TMDataGridEditorArgs) {
   const { labels } = useTMDataGridContext();
   const value = useFieldValue(field);
-  const error = useFieldError(field);
+  const invalid = useFieldInvalid(field);
   return (
     <MultiSelect
       size={size}
@@ -37,7 +37,7 @@ export function TMDataGridMultiSelectEditor({
       value={Array.isArray(value) ? value.map(String) : []}
       onChange={(next) => field.handleChange(next)}
       onBlur={field.handleBlur}
-      error={error}
+      error={invalid}
     />
   );
 }

package/src/components/editors/TMDataGridNumberEditor.tsx

@@ -0,0 +1,70 @@
+import { NumberInput } from "@mantine/core";
+import { useState } from "react";
+import type { TMDataGridEditorArgs } from "../../core/editEngine";
+import { getColumnLabel } from "../../core/columnUtils";
+import { useTMDataGridContext } from "../../TMDataGridContext";
+import {
+  selectAllOnFocus,
+  useCaretKeeper,
+  useFieldInvalid,
+  useFieldValue,
+} from "./editorShared";
+
+/** The built-in editor for `meta.type: "number"`. */
+export function TMDataGridNumberEditor({ field, column, size }: TMDataGridEditorArgs) {
+  const { labels } = useTMDataGridContext();
+  const value = useFieldValue(field);
+  const invalid = useFieldInvalid(field);
+  const { inputRef, remember } = useCaretKeeper();
+  /**
+   * The last text Mantine reported instead of a number - "-" or "1e" on the
+   * way to one. Held so a half-typed number stays on screen while the field
+   * itself holds no value.
+   */
+  const [typed, setTyped] = useState<string | null>(null);
+  // The field is the source of truth: the text survives only while it still
+  // describes what the field holds, so a write from outside the editor -
+  // `edit.setCellValue`, a revert - replaces it rather than being masked.
+  const parsedTyped = typed === null || typed === "" ? null : Number(typed);
+  const textDescribesField = Number.isFinite(parsedTyped)
+    ? parsedTyped === value
+    : value === null;
+  return (
+    <NumberInput
+      ref={inputRef}
+      size={size}
+      w="100%"
+      onFocus={selectAllOnFocus}
+      hideControls
+      aria-label={labels.editCell(getColumnLabel(column))}
+      data-dg-part="editor-input"
+      value={
+        typed !== null && textDescribesField
+          ? typed
+          : typeof value === "number"
+            ? value
+            : ""
+      }
+      onChange={(next) => {
+        if (inputRef.current !== null) remember(inputRef.current);
+        if (typeof next === "number") {
+          setTyped(null);
+          field.handleChange(next);
+          return;
+        }
+        // Mantine reports a number once one can be parsed and a string while
+        // it cannot: "" for an empty cell, partial input on the way to a
+        // number. Anything that does not parse leaves the field empty rather
+        // than `NaN` - which is a number to every validator and would commit
+        // as one, with no message a user could act on.
+        setTyped(next);
+        const parsed = Number(next);
+        field.handleChange(
+          next !== "" && Number.isFinite(parsed) ? parsed : null,
+        );
+      }}
+      onBlur={field.handleBlur}
+      error={invalid}
+    />
+  );
+}

package/src/{tmdatagrid/components → components}/editors/TMDataGridSelectEditor.tsx

@@ -6,7 +6,7 @@ import {
 } from "../../core/columnOptions";
 import { getColumnLabel } from "../../core/columnUtils";
 import { useTMDataGridContext } from "../../TMDataGridContext";
-import { useFieldError, useFieldValue } from "./editorShared";
+import { useFieldInvalid, useFieldValue } from "./editorShared";
 
 /**
  * The built-in editor for `meta.type: "select"`. Options come from the same
@@ -23,7 +23,7 @@ export function TMDataGridSelectEditor({
 }: TMDataGridEditorArgs) {
   const { labels, features } = useTMDataGridContext();
   const value = useFieldValue(field);
-  const error = useFieldError(field);
+  const invalid = useFieldInvalid(field);
   return (
     <Select
       size={size}
@@ -45,7 +45,7 @@ export function TMDataGridSelectEditor({
         if (next !== null && features.editMode === "cell") void commit();
       }}
       onBlur={field.handleBlur}
-      error={error}
+      error={invalid}
     />
   );
 }

package/src/{tmdatagrid/components → components}/editors/TMDataGridStringEditor.tsx

@@ -5,7 +5,7 @@ import { useTMDataGridContext } from "../../TMDataGridContext";
 import {
   selectAllOnFocus,
   useCaretKeeper,
-  useFieldError,
+  useFieldInvalid,
   useFieldValue,
 } from "./editorShared";
 
@@ -13,7 +13,7 @@ import {
 export function TMDataGridStringEditor({ field, column, size }: TMDataGridEditorArgs) {
   const { labels } = useTMDataGridContext();
   const value = useFieldValue(field);
-  const error = useFieldError(field);
+  const invalid = useFieldInvalid(field);
   const { inputRef, remember } = useCaretKeeper();
   return (
     <TextInput
@@ -29,7 +29,7 @@ export function TMDataGridStringEditor({ field, column, size }: TMDataGridEditor
         field.handleChange(event.currentTarget.value);
       }}
       onBlur={field.handleBlur}
-      error={error}
+      error={invalid}
     />
   );
 }

package/src/{tmdatagrid/components → components}/editors/editorShared.ts

@@ -1,51 +1,37 @@
 import { useStore } from "@tanstack/react-form";
 import { useLayoutEffect, useRef, type RefObject } from "react";
-import type { TMDataGridEditField } from "../../core/editEngine";
-
-/**
- * The first error as text, whatever shape the validator produced - TanStack
- * Form keeps errors verbatim, so a Zod issue arrives as `{ message }`, a
- * plain function's return arrives as it was, and a form-level schema's
- * pathless issues arrive keyed under an empty path (`{ "": [issues] }`).
- * This digs until it finds a message.
- */
-export function firstErrorText(error: unknown): string | undefined {
-  if (error === null || error === undefined) return undefined;
-  if (typeof error === "string") return error;
-  if (Array.isArray(error)) {
-    for (const entry of error) {
-      const text = firstErrorText(entry);
-      if (text !== undefined) return text;
-    }
-    return undefined;
-  }
-  if (typeof error === "object") {
-    const message = (error as { message?: unknown }).message;
-    if (typeof message === "string") return message;
-    for (const value of Object.values(error)) {
-      const text = firstErrorText(value);
-      if (text !== undefined) return text;
-    }
-  }
-  return undefined;
-}
+import { isInputElement } from "../../core/dom";
+import { firstErrorText, type TMDataGridEditField } from "../../core/editEngine";
 
 /** The field's live value - one subscription, on the field's own store. */
 export function useFieldValue(field: TMDataGridEditField): unknown {
   return useStore(field.store, (state) => state.value as unknown);
 }
 
-/** The field's first error, for the Mantine input's `error` prop. */
+/** The field's first error - the message the editor's host puts in a tooltip. */
 export function useFieldError(field: TMDataGridEditField): string | undefined {
   return useStore(field.store, (state) =>
     firstErrorText(state.meta.errors as ReadonlyArray<unknown>),
   );
 }
 
+/**
+ * Whether the field has an error, for the Mantine input's `error` prop - the
+ * invalid border and nothing else. The message itself would wrap inside a
+ * narrow cell and be clipped, so the host shows it in a tooltip instead.
+ */
+export function useFieldInvalid(field: TMDataGridEditField): boolean {
+  return useStore(
+    field.store,
+    (state) =>
+      firstErrorText(state.meta.errors as ReadonlyArray<unknown>) !== undefined,
+  );
+}
+
 /** Select-all on focus - F2/Enter open with the value ready to replace. */
 export function selectAllOnFocus(event: { currentTarget: unknown }): void {
   const target = event.currentTarget;
-  if (target instanceof HTMLInputElement) target.select();
+  if (isInputElement(target)) target.select();
 }
 
 /**

package/src/{tmdatagrid/components → components}/filters/DgAutocompleteFilter.tsx

@@ -6,6 +6,7 @@ import {
   operatorTakesArrayValue,
   operatorTakesRangeValue,
 } from "../../core/filterOperators";
+import { filterFieldProps } from "./controlLayout";
 import { TMDataGridFilterValueInput } from "./TMDataGridFilterValueInput";
 
 /**
@@ -31,12 +32,12 @@ export function DgAutocompleteFilter(args: TMDataGridFilterControlArgs) {
 
   return (
     <Autocomplete
-      label={labels.filterValue}
+      {...filterFieldProps(args, { label: labels.filterValue, width: 180 })}
       size={size}
-      w={180}
-      comboboxProps={{ withinPortal: false }}
       disabled={!needsValue}
-      placeholder={needsValue ? labels.filterValuePlaceholder : ""}
+      placeholder={
+        needsValue && args.layout !== "header" ? labels.filterValuePlaceholder : ""
+      }
       data={suggestions.map((option) => option.value)}
       limit={20}
       value={needsValue && typeof value === "string" ? value : ""}

package/src/{tmdatagrid/components → components}/filters/DgDateRangeFilter.tsx

@@ -1,6 +1,7 @@
 import { Group, TextInput } from "@mantine/core";
 import type { TMDataGridFilterControlArgs } from "../../core/filterControls";
 import { operatorTakesRangeValue } from "../../core/filterOperators";
+import { filterFieldProps } from "./controlLayout";
 import { TMDataGridFilterValueInput } from "./TMDataGridFilterValueInput";
 
 /**
@@ -16,25 +17,41 @@ export function DgDateRangeFilter(args: TMDataGridFilterControlArgs) {
     return <TMDataGridFilterValueInput {...args} />;
   }
 
+  const fills = args.layout !== "row";
   const pair: [string, string] = Array.isArray(value)
     ? [String(value[0] ?? ""), String(value[1] ?? "")]
     : ["", ""];
 
   return (
-    <Group gap={4} wrap="nowrap" align="flex-start">
+    <Group
+      gap={4}
+      wrap="nowrap"
+      align="flex-start"
+      w={fills ? "100%" : undefined}
+    >
       <TextInput
-        label={labels.filterFrom}
+        {...filterFieldProps(
+          args,
+          { label: labels.filterFrom, width: 88 },
+          labels.filterFrom,
+        )}
         size={size}
-        w={88}
         type="date"
+        flex={fills ? 1 : undefined}
+        miw={0}
         value={pair[0]}
         onChange={(event) => onChange([event.currentTarget.value, pair[1]])}
       />
       <TextInput
-        label={labels.filterTo}
+        {...filterFieldProps(
+          args,
+          { label: labels.filterTo, width: 88 },
+          labels.filterTo,
+        )}
         size={size}
-        w={88}
         type="date"
+        flex={fills ? 1 : undefined}
+        miw={0}
         value={pair[1]}
         onChange={(event) => onChange([pair[0], event.currentTarget.value])}
       />

package/src/{tmdatagrid/components → components}/filters/DgRangeSliderFilter.tsx

@@ -1,6 +1,7 @@
 import { Input, RangeSlider } from "@mantine/core";
 import type { TMDataGridFilterControlArgs } from "../../core/filterControls";
 import { operatorTakesRangeValue } from "../../core/filterOperators";
+import { filterFieldProps } from "./controlLayout";
 import { TMDataGridFilterValueInput } from "./TMDataGridFilterValueInput";
 
 /**
@@ -30,7 +31,10 @@ export function DgRangeSliderFilter(args: TMDataGridFilterControlArgs) {
   const upper = pair[1] === undefined || pair[1] === "" ? max : Number(pair[1]);
 
   return (
-    <Input.Wrapper label={labels.filterValue} size={size} w={180}>
+    <Input.Wrapper
+      {...filterFieldProps(args, { label: labels.filterValue, width: 180 })}
+      size={size}
+    >
       <RangeSlider
         size={size}
         mt={6}

package/src/{tmdatagrid/components → components}/filters/DgTriStateFilter.tsx

@@ -5,6 +5,7 @@ import {
   operatorTakesArrayValue,
   operatorTakesRangeValue,
 } from "../../core/filterOperators";
+import { filterFieldProps } from "./controlLayout";
 import { TMDataGridFilterValueInput } from "./TMDataGridFilterValueInput";
 
 /**
@@ -21,7 +22,10 @@ export function DgTriStateFilter(args: TMDataGridFilterControlArgs) {
   const scalar = typeof value === "string" ? value : "";
 
   return (
-    <Input.Wrapper label={labels.filterValue} size={size}>
+    <Input.Wrapper
+      {...filterFieldProps(args, { label: labels.filterValue })}
+      size={size}
+    >
       <SegmentedControl
         size={size}
         disabled={!needsValue}