@jielga/tmdatagrid 0.2.0 → 0.5.0

package/src/tmdatagrid/core/expanding.ts

@@ -0,0 +1,93 @@
+import type { ExpandedState, Row, RowData } from "@tanstack/react-table";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
+
+/**
+ * Which rows an expand-all control is about.
+ *
+ * TanStack keeps one `expanded` state, and the grid opens two unrelated things
+ * out of it: a group row opens into its children, a data row opens into its
+ * detail panel. So `toggleAllRowsExpanded` — which writes the state's
+ * whole-table form — is the wrong verb for either control. "Expand all groups"
+ * in the tree menu would open every panel in the grid, and the details lane's
+ * chevron would unfold the whole tree.
+ *
+ * These helpers narrow both to the rows their control is for, and leave the
+ * other kind exactly as it was.
+ */
+export type TMDataGridExpandTarget = "groups" | "details";
+
+function isTarget<TData extends RowData>(
+  row: Row<TMDataGridFeatures, TData>,
+  target: TMDataGridExpandTarget,
+): boolean {
+  return target === "groups" ? row.getIsGrouped() : !row.getIsGrouped();
+}
+
+/**
+ * The state as a map. `true` is the whole-table form, which has to be written
+ * out before one kind of row can be taken back out of it — the same thing
+ * TanStack does before toggling a single row.
+ */
+function toExpandedMap<TData extends RowData>(
+  rows: ReadonlyArray<Row<TMDataGridFeatures, TData>>,
+  expanded: ExpandedState,
+): Record<string, boolean> {
+  if (expanded !== true) return { ...expanded };
+  const all: Record<string, boolean> = {};
+  for (const row of rows) all[row.id] = true;
+  return all;
+}
+
+export type TMDataGridExpandAllArgs<TData extends RowData> = {
+  /**
+   * Every row in the model, groups and records alike — `flatRows` off any of
+   * them. A grouped model lists its leaves both under their group and in the
+   * flat list, so this may repeat rows; both helpers are written so that a
+   * repeat costs nothing.
+   */
+  rows: ReadonlyArray<Row<TMDataGridFeatures, TData>>;
+  expanded: ExpandedState;
+  target: TMDataGridExpandTarget;
+};
+
+/**
+ * Whether every row of this kind is open — what the control shows, and what a
+ * bare toggle inverts.
+ *
+ * `false` when there are none of them, matching TanStack's own
+ * `getIsAllRowsExpanded()` on an empty state: an empty set is nothing to
+ * collapse.
+ */
+export function areAllRowsExpanded<TData extends RowData>({
+  rows,
+  expanded,
+  target,
+}: TMDataGridExpandAllArgs<TData>): boolean {
+  let found = false;
+  for (const row of rows) {
+    if (!isTarget(row, target)) continue;
+    found = true;
+    if (expanded === true) continue;
+    if (expanded[row.id] !== true) return false;
+  }
+  return found;
+}
+
+/**
+ * The next `expanded` state after an expand-all or collapse-all on one kind of
+ * row. Rows of the other kind keep whatever they had.
+ */
+export function resolveExpandAll<TData extends RowData>({
+  rows,
+  expanded,
+  target,
+  expand,
+}: TMDataGridExpandAllArgs<TData> & { expand: boolean }): ExpandedState {
+  const next = toExpandedMap(rows, expanded);
+  for (const row of rows) {
+    if (!isTarget(row, target)) continue;
+    if (expand) next[row.id] = true;
+    else delete next[row.id];
+  }
+  return next;
+}

package/src/tmdatagrid/core/filterOperators.ts

@@ -7,13 +7,23 @@ import type { Row, RowData, TableFeatures } from "@tanstack/react-table";
  * inside the filter *value* instead. That keeps the whole filter model plain,
  * serialisable JSON — which is what makes it portable to a server-side
  * `manualFiltering` table (just forward `columnFilters` to the API).
+ *
+ * `value` is a string array under `isAnyOf` / `isNoneOf` (the set the cell is
+ * tested against) and a single string everywhere else — dates travel as ISO
+ * `YYYY-MM-DD` strings, booleans as `"true"` / `"false"`. Still plain JSON.
  */
 export type TMDataGridFilterValue = {
   operator: TMDataGridFilterOperator;
-  value: string;
+  value: string | ReadonlyArray<string>;
 };
 
-export type TMDataGridColumnType = "string" | "number";
+export type TMDataGridColumnType =
+  | "string"
+  | "number"
+  | "boolean"
+  | "date"
+  | "select"
+  | "multiSelect";
 
 export type TMDataGridFilterOperator =
   | "contains"
@@ -25,6 +35,12 @@ export type TMDataGridFilterOperator =
   | "greaterThanOrEqual"
   | "lessThan"
   | "lessThanOrEqual"
+  | "before"
+  | "after"
+  | "onOrBefore"
+  | "onOrAfter"
+  | "isAnyOf"
+  | "isNoneOf"
   | "isEmpty"
   | "isNotEmpty";
 
@@ -38,6 +54,12 @@ export const FILTER_OPERATOR_LABELS: Record<TMDataGridFilterOperator, string> =
   greaterThanOrEqual: "is greater than or equal to",
   lessThan: "is less than",
   lessThanOrEqual: "is less than or equal to",
+  before: "is before",
+  after: "is after",
+  onOrBefore: "is on or before",
+  onOrAfter: "is on or after",
+  isAnyOf: "is any of",
+  isNoneOf: "is none of",
   isEmpty: "is empty",
   isNotEmpty: "is not empty",
 };
@@ -63,28 +85,95 @@ const NUMBER_OPERATORS: readonly TMDataGridFilterOperator[] = [
   "isNotEmpty",
 ];
 
+// `equals` doubles as a date's "is": it compares by calendar day whenever the
+// cell holds a Date (see matchesFilter), so a separate `is` operator would be
+// the same comparison under a second name.
+const DATE_OPERATORS: readonly TMDataGridFilterOperator[] = [
+  "equals",
+  "notEquals",
+  "before",
+  "after",
+  "onOrBefore",
+  "onOrAfter",
+  "isEmpty",
+  "isNotEmpty",
+];
+
+const BOOLEAN_OPERATORS: readonly TMDataGridFilterOperator[] = [
+  "equals",
+  "notEquals",
+  "isEmpty",
+  "isNotEmpty",
+];
+
+// One set for both select types: the operators are about membership in the
+// filter's set, which reads the same whether the cell holds one value or many.
+const SELECT_OPERATORS: readonly TMDataGridFilterOperator[] = [
+  "isAnyOf",
+  "isNoneOf",
+  "isEmpty",
+  "isNotEmpty",
+];
+
 /** Operators that ignore the value input (the input is disabled for these). */
 const VALUELESS_OPERATORS: readonly TMDataGridFilterOperator[] = [
   "isEmpty",
   "isNotEmpty",
 ];
 
+/** Operators whose value is a set of strings rather than one. */
+const ARRAY_OPERATORS: readonly TMDataGridFilterOperator[] = [
+  "isAnyOf",
+  "isNoneOf",
+];
+
+const OPERATORS_BY_TYPE: Record<
+  TMDataGridColumnType,
+  readonly TMDataGridFilterOperator[]
+> = {
+  string: STRING_OPERATORS,
+  number: NUMBER_OPERATORS,
+  boolean: BOOLEAN_OPERATORS,
+  date: DATE_OPERATORS,
+  select: SELECT_OPERATORS,
+  multiSelect: SELECT_OPERATORS,
+};
+
+const DEFAULT_OPERATOR_BY_TYPE: Record<
+  TMDataGridColumnType,
+  TMDataGridFilterOperator
+> = {
+  string: "contains",
+  number: "equals",
+  boolean: "equals",
+  date: "equals",
+  select: "isAnyOf",
+  multiSelect: "isAnyOf",
+};
+
 export function getOperatorsForType(
   type: TMDataGridColumnType,
 ): readonly TMDataGridFilterOperator[] {
-  return type === "number" ? NUMBER_OPERATORS : STRING_OPERATORS;
+  return OPERATORS_BY_TYPE[type];
 }
 
 export function getDefaultOperator(
   type: TMDataGridColumnType,
 ): TMDataGridFilterOperator {
-  return type === "number" ? "equals" : "contains";
+  return DEFAULT_OPERATOR_BY_TYPE[type];
 }
 
 export function operatorNeedsValue(operator: TMDataGridFilterOperator): boolean {
   return !VALUELESS_OPERATORS.includes(operator);
 }
 
+/** Whether the operator's value is a string array — `isAnyOf` / `isNoneOf`. */
+export function operatorTakesArrayValue(
+  operator: TMDataGridFilterOperator,
+): boolean {
+  return ARRAY_OPERATORS.includes(operator);
+}
+
 export function isTMDataGridFilterValue(
   value: unknown,
 ): value is TMDataGridFilterValue {
@@ -103,23 +192,113 @@ export function isTMDataGridFilterValue(
  */
 export function isFilterActive(value: unknown): boolean {
   if (!isTMDataGridFilterValue(value)) return false;
-  return !operatorNeedsValue(value.operator) || value.value.trim() !== "";
+  if (!operatorNeedsValue(value.operator)) return true;
+  return Array.isArray(value.value)
+    ? value.value.length > 0
+    : typeof value.value === "string" && value.value.trim() !== "";
+}
+
+/**
+ * One-line description of a single filter, as shown on a filter pill.
+ *
+ * The type's default operator is left implicit — "First name: Sofia" reads the
+ * way a person would say it — while any other operator is spelled out, since
+ * that is the part a reader cannot guess.
+ */
+export function formatFilterLabel({
+  label,
+  type,
+  filter,
+  operatorLabels = FILTER_OPERATOR_LABELS,
+}: {
+  label: string;
+  type: TMDataGridColumnType;
+  filter: TMDataGridFilterValue;
+  /** Localized operator names — `labels.operators`. Defaults to English. */
+  operatorLabels?: Record<TMDataGridFilterOperator, string>;
+}): string {
+  const { operator, value } = filter;
+  if (!operatorNeedsValue(operator)) {
+    return `${label} ${operatorLabels[operator]}`;
+  }
+  const text = Array.isArray(value) ? value.join(", ") : String(value).trim();
+  if (operator === getDefaultOperator(type)) return `${label}: ${text}`;
+  return `${label} ${operatorLabels[operator]} ${text}`;
+}
+
+/**
+ * A value's calendar day as `YYYY-MM-DD`, or `null` for anything that has no
+ * day to speak of. A `Date` is read in local time — `sv-SE` formats as ISO,
+ * which is the shape `<input type="date">` produced on the other side — and a
+ * string contributes its leading ISO day, so both `2026-07-31` and a full
+ * timestamp compare by day.
+ */
+function toIsoDay(value: unknown): string | null {
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime())
+      ? null
+      : value.toLocaleDateString("sv-SE");
+  }
+  if (typeof value === "string") {
+    const match = /^(\d{4}-\d{2}-\d{2})/.exec(value.trim());
+    return match ? match[1] : null;
+  }
+  return null;
+}
+
+function isEmptyCell(cellValue: unknown): boolean {
+  return (
+    cellValue === null ||
+    cellValue === undefined ||
+    cellValue === "" ||
+    (Array.isArray(cellValue) && cellValue.length === 0)
+  );
 }
 
 export function matchesFilter(
   cellValue: unknown,
   { operator, value }: TMDataGridFilterValue,
 ): boolean {
-  if (operator === "isEmpty") {
-    return cellValue === null || cellValue === undefined || cellValue === "";
-  }
-  if (operator === "isNotEmpty") {
-    return cellValue !== null && cellValue !== undefined && cellValue !== "";
+  if (operator === "isEmpty") return isEmptyCell(cellValue);
+  if (operator === "isNotEmpty") return !isEmptyCell(cellValue);
+
+  // Set membership. The cell side is also a list — a multiSelect cell holds an
+  // array — so "any of" is an intersection test and "none of" its complement.
+  if (operator === "isAnyOf" || operator === "isNoneOf") {
+    const set = (Array.isArray(value) ? value : [value])
+      .map((entry) => String(entry).toLowerCase())
+      .filter((entry) => entry !== "");
+    if (set.length === 0) return true;
+    const cellEntries = Array.isArray(cellValue) ? cellValue : [cellValue];
+    const hit = cellEntries.some((entry) =>
+      set.includes(String(entry ?? "").toLowerCase()),
+    );
+    return operator === "isAnyOf" ? hit : !hit;
   }
 
-  const filterText = value.trim();
+  const filterText =
+    typeof value === "string" ? value.trim() : value.join(",").trim();
   if (filterText === "") return true;
 
+  // Day ordering. ISO days compare correctly as strings, which keeps this
+  // free of timezone arithmetic — the whole comparison lives in local days.
+  switch (operator) {
+    case "before":
+    case "after":
+    case "onOrBefore":
+    case "onOrAfter": {
+      const cellDay = toIsoDay(cellValue);
+      const filterDay = toIsoDay(filterText);
+      if (cellDay === null || filterDay === null) return false;
+      if (operator === "before") return cellDay < filterDay;
+      if (operator === "after") return cellDay > filterDay;
+      if (operator === "onOrBefore") return cellDay <= filterDay;
+      return cellDay >= filterDay;
+    }
+    default:
+      break;
+  }
+
   const numericCell = typeof cellValue === "number" ? cellValue : Number.NaN;
   const numericFilter = Number(filterText);
   const compareNumeric =
@@ -138,7 +317,14 @@ export function matchesFilter(
       break;
   }
 
-  const cellText = String(cellValue ?? "").toLowerCase();
+  // A Date compares by its calendar day, which is what makes `equals` on a
+  // date column mean "is this day" rather than a doomed string comparison
+  // against the Date's default stringification.
+  const cellText = (
+    cellValue instanceof Date
+      ? (toIsoDay(cellValue) ?? "")
+      : String(cellValue ?? "")
+  ).toLowerCase();
   const needle = filterText.toLowerCase();
 
   switch (operator) {

package/src/tmdatagrid/core/grouping.ts

@@ -0,0 +1,21 @@
+import type { Row, RowData } from "@tanstack/react-table";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
+
+/**
+ * The data rows under a group row, at any depth.
+ *
+ * Not `row.getLeafRows()`, despite the name: that flattens the whole subtree
+ * and keeps the branches, so a group nested two deep reports its sub-groups
+ * alongside the records. Grouping `city` then `name` would have Stockholm
+ * counting four rows and three names as seven, and one tick on it selecting
+ * ids that hold no record.
+ *
+ * A row with no subRows is a data row, which also makes this the identity on an
+ * ungrouped grid.
+ */
+export function getGroupDataRows<TData extends RowData>(
+  row: Row<TMDataGridFeatures, TData>,
+): Array<Row<TMDataGridFeatures, TData>> {
+  if (row.subRows.length === 0) return [row];
+  return row.getLeafRows().filter((leaf) => leaf.subRows.length === 0);
+}

package/src/tmdatagrid/core/labels.ts

@@ -0,0 +1,211 @@
+import {
+  FILTER_OPERATOR_LABELS,
+  type TMDataGridFilterOperator,
+} from "./filterOperators";
+
+/**
+ * Every user-facing string in the grid — menu items, panels, tooltips, the
+ * pager, and the `aria-label`s a screen reader speaks. One flat object, so an
+ * override is a spread rather than a deep merge; `operators` is the single
+ * nested record and {@link mergeLabels} folds it separately.
+ *
+ * Labels that carry a value are functions rather than template strings, so a
+ * language is free to put the value wherever its grammar wants it.
+ */
+export type TMDataGridLabels = {
+  /** Filter operator names, as shown in the operator dropdown and on pills. */
+  operators: Record<TMDataGridFilterOperator, string>;
+
+  // Toolbar
+  /** "Manage columns" — the burger button and the header menu item. */
+  manageColumns: string;
+  /** "Filters" — the funnel button and the filter panel's title. */
+  filters: string;
+  searchPlaceholder: string;
+  searchLabel: string;
+  clearSearch: string;
+
+  // Columns panel
+  columnsSearchPlaceholder: string;
+  columnsNoMatch: (search: string) => string;
+  columnsShowHideAll: string;
+  columnsReset: string;
+
+  // Filter panel
+  filterColumn: string;
+  filterOperator: string;
+  filterValue: string;
+  filterValuePlaceholder: string;
+  /** What a boolean column's `true` reads as — its filter choice and cell text. */
+  booleanTrue: string;
+  booleanFalse: string;
+  addFilter: string;
+  clearAllFilters: string;
+  closeFilters: string;
+  removeFilter: string;
+
+  // Filter pills
+  activeFilters: string;
+  clearFilter: (column: string) => string;
+
+  // Header menu
+  sortAsc: string;
+  sortDesc: string;
+  filterMenuItem: string;
+  groupBy: (column: string) => string;
+  ungroup: (column: string) => string;
+  expandAllGroups: string;
+  collapseAllGroups: string;
+  pinLeft: string;
+  pinRight: string;
+  unpin: string;
+  moveLeft: string;
+  moveRight: string;
+  autosizeColumn: string;
+  hideColumn: string;
+  filterOn: (column: string) => string;
+  sortColumn: (column: string) => string;
+  columnMenu: (column: string) => string;
+
+  // Footer / pager
+  rowsPerPage: string;
+  pageRange: (args: { from: number; to: number; total: number }) => string;
+  groupedAllRows: (total: number) => string;
+  pagingSuspendedHint: string;
+  previousPage: string;
+  nextPage: string;
+
+  // Body
+  noResults: string;
+  loading: string;
+
+  // Cell selection menu
+  cellCount: (count: number) => string;
+  copy: string;
+  exportCsv: string;
+  includeHeaders: string;
+
+  // Generated checkbox lane
+  selectColumnLabel: string;
+  selectAllRows: string;
+  selectRow: string;
+  selectGroup: string;
+
+  // Generated details lane
+  detailsColumnLabel: string;
+  showDetails: string;
+  hideDetails: string;
+  expandAllDetails: string;
+  collapseAllDetails: string;
+
+  // Generated tree lane
+  groupColumnLabel: string;
+  blankGroupValue: string;
+  expandGroup: (label: string) => string;
+  collapseGroup: (label: string) => string;
+};
+
+/**
+ * What the `labels` option accepts: any subset, merged over the English
+ * defaults — so `{ noResults: "Inga rader" }` is a complete configuration.
+ */
+export type TMDataGridLabelsOverride = Partial<
+  Omit<TMDataGridLabels, "operators">
+> & {
+  operators?: Partial<Record<TMDataGridFilterOperator, string>>;
+};
+
+/** The built-in defaults. Also the reference for what a preset must cover. */
+export const TMDATAGRID_LABELS_EN: TMDataGridLabels = {
+  operators: FILTER_OPERATOR_LABELS,
+
+  manageColumns: "Manage columns",
+  filters: "Filters",
+  searchPlaceholder: "Search",
+  searchLabel: "Search rows",
+  clearSearch: "Clear search",
+
+  columnsSearchPlaceholder: "Search",
+  columnsNoMatch: (search) => `No columns match “${search}”`,
+  columnsShowHideAll: "Show/Hide All",
+  columnsReset: "RESET",
+
+  filterColumn: "Column",
+  filterOperator: "Operator",
+  filterValue: "Value",
+  filterValuePlaceholder: "Filter value",
+  booleanTrue: "Yes",
+  booleanFalse: "No",
+  addFilter: "Add filter",
+  clearAllFilters: "Clear all",
+  closeFilters: "Close filters",
+  removeFilter: "Remove filter",
+
+  activeFilters: "Active filters",
+  clearFilter: (column) => `Clear ${column} filter`,
+
+  sortAsc: "Sort by ASC",
+  sortDesc: "Sort by DESC",
+  filterMenuItem: "Filter",
+  groupBy: (column) => `Group by ${column}`,
+  ungroup: (column) => `Ungroup ${column}`,
+  expandAllGroups: "Expand all groups",
+  collapseAllGroups: "Collapse all groups",
+  pinLeft: "Pin to left",
+  pinRight: "Pin to right",
+  unpin: "Unpin",
+  moveLeft: "Move left",
+  moveRight: "Move right",
+  autosizeColumn: "Autosize column",
+  hideColumn: "Hide column",
+  filterOn: (column) => `Filter on ${column}`,
+  sortColumn: (column) => `Sort ${column}`,
+  columnMenu: (column) => `${column} column menu`,
+
+  rowsPerPage: "Rows per page:",
+  pageRange: ({ from, to, total }) => `${from}–${to} of ${total}`,
+  groupedAllRows: (total) => `Grouped · all ${total} rows`,
+  pagingSuspendedHint:
+    "Paging is off while the rows are grouped: the whole tree is rendered and virtualized. Ungroup to page again.",
+  previousPage: "Previous page",
+  nextPage: "Next page",
+
+  noResults: "No rows match your filters",
+  loading: "Loading",
+
+  cellCount: (count) => (count === 1 ? "1 cell" : `${count} cells`),
+  copy: "Copy",
+  exportCsv: "Export as CSV for Excel",
+  includeHeaders: "Include headers",
+
+  selectColumnLabel: "Checkbox selection",
+  selectAllRows: "Select all rows",
+  selectRow: "Select row",
+  selectGroup: "Select group",
+
+  detailsColumnLabel: "Details",
+  showDetails: "Show details",
+  hideDetails: "Hide details",
+  expandAllDetails: "Expand all details",
+  collapseAllDetails: "Collapse all details",
+
+  groupColumnLabel: "Group",
+  blankGroupValue: "(Blank)",
+  expandGroup: (label) => `Expand ${label}`,
+  collapseGroup: (label) => `Collapse ${label}`,
+};
+
+/** A partial override folded over the English defaults. */
+export function mergeLabels(
+  override?: TMDataGridLabelsOverride,
+): TMDataGridLabels {
+  if (!override) return TMDATAGRID_LABELS_EN;
+  return {
+    ...TMDATAGRID_LABELS_EN,
+    ...override,
+    operators: {
+      ...TMDATAGRID_LABELS_EN.operators,
+      ...override.operators,
+    },
+  };
+}