@jielga/tmdatagrid 0.2.0 → 0.5.0

package/src/tmdatagrid/core/labelsSv.ts

@@ -0,0 +1,108 @@
+import type { TMDataGridLabels } from "./labels";
+
+/**
+ * The complete Swedish dictionary. Typed as {@link TMDataGridLabels} rather
+ * than as an override, so a label added to the grid without a Swedish
+ * translation is a compile error here instead of English quietly leaking
+ * through.
+ *
+ * ```tsx
+ * useTMDataGrid({ data, columns, labels: TMDATAGRID_LABELS_SV });
+ * ```
+ */
+export const TMDATAGRID_LABELS_SV: TMDataGridLabels = {
+  operators: {
+    contains: "innehåller",
+    equals: "är lika med",
+    notEquals: "är inte lika med",
+    startsWith: "börjar med",
+    endsWith: "slutar med",
+    greaterThan: "är större än",
+    greaterThanOrEqual: "är större än eller lika med",
+    lessThan: "är mindre än",
+    lessThanOrEqual: "är mindre än eller lika med",
+    before: "är före",
+    after: "är efter",
+    onOrBefore: "är på eller före",
+    onOrAfter: "är på eller efter",
+    isAnyOf: "är någon av",
+    isNoneOf: "är ingen av",
+    isEmpty: "är tom",
+    isNotEmpty: "är inte tom",
+  },
+
+  manageColumns: "Hantera kolumner",
+  filters: "Filter",
+  searchPlaceholder: "Sök",
+  searchLabel: "Sök rader",
+  clearSearch: "Rensa sökningen",
+
+  columnsSearchPlaceholder: "Sök",
+  columnsNoMatch: (search) => `Inga kolumner matchar ”${search}”`,
+  columnsShowHideAll: "Visa/dölj alla",
+  columnsReset: "ÅTERSTÄLL",
+
+  filterColumn: "Kolumn",
+  filterOperator: "Operator",
+  filterValue: "Värde",
+  filterValuePlaceholder: "Filtervärde",
+  booleanTrue: "Ja",
+  booleanFalse: "Nej",
+  addFilter: "Lägg till filter",
+  clearAllFilters: "Rensa alla",
+  closeFilters: "Stäng filter",
+  removeFilter: "Ta bort filter",
+
+  activeFilters: "Aktiva filter",
+  clearFilter: (column) => `Rensa filtret för ${column}`,
+
+  sortAsc: "Sortera stigande",
+  sortDesc: "Sortera fallande",
+  filterMenuItem: "Filtrera",
+  groupBy: (column) => `Gruppera på ${column}`,
+  ungroup: (column) => `Avgruppera ${column}`,
+  expandAllGroups: "Expandera alla grupper",
+  collapseAllGroups: "Fäll ihop alla grupper",
+  pinLeft: "Fäst till vänster",
+  pinRight: "Fäst till höger",
+  unpin: "Lossa",
+  moveLeft: "Flytta åt vänster",
+  moveRight: "Flytta åt höger",
+  autosizeColumn: "Anpassa kolumnbredd",
+  hideColumn: "Dölj kolumn",
+  filterOn: (column) => `Filtrera på ${column}`,
+  sortColumn: (column) => `Sortera ${column}`,
+  columnMenu: (column) => `Kolumnmeny för ${column}`,
+
+  rowsPerPage: "Rader per sida:",
+  pageRange: ({ from, to, total }) => `${from}–${to} av ${total}`,
+  groupedAllRows: (total) => `Grupperad · alla ${total} rader`,
+  pagingSuspendedHint:
+    "Sidindelningen är avstängd medan raderna är grupperade: hela trädet renderas och virtualiseras. Avgruppera för att bläddra igen.",
+  previousPage: "Föregående sida",
+  nextPage: "Nästa sida",
+
+  noResults: "Inga rader matchar dina filter",
+  loading: "Laddar",
+
+  cellCount: (count) => (count === 1 ? "1 cell" : `${count} celler`),
+  copy: "Kopiera",
+  exportCsv: "Exportera som CSV för Excel",
+  includeHeaders: "Inkludera rubriker",
+
+  selectColumnLabel: "Kryssrutemarkering",
+  selectAllRows: "Markera alla rader",
+  selectRow: "Markera rad",
+  selectGroup: "Markera grupp",
+
+  detailsColumnLabel: "Detaljer",
+  showDetails: "Visa detaljer",
+  hideDetails: "Dölj detaljer",
+  expandAllDetails: "Expandera alla detaljer",
+  collapseAllDetails: "Fäll ihop alla detaljer",
+
+  groupColumnLabel: "Grupp",
+  blankGroupValue: "(Tom)",
+  expandGroup: (label) => `Expandera ${label}`,
+  collapseGroup: (label) => `Fäll ihop ${label}`,
+};

package/src/tmdatagrid/core/persistence.ts

@@ -28,6 +28,10 @@ export const DATA_STATE_SLICES = [
   "globalFilter",
   "sorting",
   "pagination",
+  // Which groups are open. Keyed by group ids built from the values themselves
+  // (`department:Design`), so a restored entry for a group the data no longer
+  // produces is simply never looked up.
+  "expanded",
 ] as const satisfies ReadonlyArray<keyof GridState>;
 
 /**
@@ -39,6 +43,10 @@ export const SETTINGS_STATE_SLICES = [
   "columnSizing",
   "columnOrder",
   "columnPinning",
+  // Which columns the rows are grouped by. A settings slice rather than a data
+  // one: it names columns, not values, so it survives the data changing under
+  // it the way the column layout does.
+  "grouping",
 ] as const satisfies ReadonlyArray<keyof GridState>;
 
 export type TMDataGridDataSlice = (typeof DATA_STATE_SLICES)[number];
@@ -162,6 +170,9 @@ const SLICE_GUARDS: Record<
       pageSize > 0
     );
   },
+  // `true` is a legal ExpandedState of its own, meaning every row is open.
+  expanded: (value) =>
+    value === true || isRecordOf(value, (entry) => typeof entry === "boolean"),
   columnVisibility: (value) =>
     isRecordOf(value, (entry) => typeof entry === "boolean"),
   columnSizing: (value) => isRecordOf(value, isFiniteNumber),
@@ -169,6 +180,7 @@ const SLICE_GUARDS: Record<
   columnPinning: (value) =>
     isArrayOf(prop(value, "left"), isString) &&
     isArrayOf(prop(value, "right"), isString),
+  grouping: (value) => isArrayOf(value, isString),
 };
 
 function isValidSlice(slice: keyof GridState, value: unknown): boolean {

package/src/tmdatagrid/core/rowSelection.ts

@@ -0,0 +1,202 @@
+import type { Row, RowData, RowSelectionState } from "@tanstack/react-table";
+import type { TMDataGridFeatureFlags } from "./capabilities";
+import { getGroupDataRows } from "./grouping";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+
+/**
+ * Rows in the order they are displayed, which is the order a shift-click range
+ * is measured over — so a range follows the active sort and skips filtered-out
+ * rows. Under pagination it is the current page, so a range cannot cross a page
+ * boundary.
+ *
+ * Once a column is grouped this includes the group rows, and only the leaves of
+ * groups that are open — and paging is suspended, so it is the whole tree. That
+ * is the right list for a range: it is what the user can see, and a range that
+ * swept collapsed rows would select things off screen. What a group row in the
+ * range contributes is decided by {@link getSelectableRowIds}.
+ */
+export function getDisplayedRows<TData extends RowData>(
+  table: TMDataGridTable<TData>,
+  features: TMDataGridFeatureFlags,
+): Array<Row<TMDataGridFeatures, TData>> {
+  return isPagingActive(table, features)
+    ? table.getPaginatedRowModel().rows
+    : table.getPrePaginatedRowModel().rows;
+}
+
+/**
+ * Whether the built-in pager is actually slicing anything.
+ *
+ * Grouping suspends it. A page can only count one kind of thing, and once the
+ * rows are a tree neither answer works: counting every row splits a group
+ * across a page boundary and strands the rest of the tree on pages the user has
+ * to go looking for, and counting only the top-level rows quietly redefines
+ * "rows per page" as groups per page, so a page of 25 can hold thousands of
+ * rows. Rather than pick, the grid renders the whole tree and leans on the
+ * virtualizer — which is its default mode anyway, pagination being opt-in.
+ *
+ * `TMDataGrid.Footer` reads this too, and greys the pager out rather than
+ * hiding it, so the pager going quiet is visible instead of mysterious.
+ */
+export function isPagingActive<TData extends RowData>(
+  table: TMDataGridTable<TData>,
+  features: TMDataGridFeatureFlags,
+): boolean {
+  return features.pagination && table.store.state.grouping.length === 0;
+}
+
+/**
+ * Which modifiers were held. Named for what they mean rather than for the keys,
+ * because the keys differ per platform — `toggle` is Ctrl on Windows/Linux and
+ * Cmd on macOS.
+ */
+export type TMDataGridRowClickModifiers = {
+  toggle: boolean;
+  extend: boolean;
+};
+
+export type ResolveRowSelectionClickArgs<TData extends RowData> = {
+  /** Displayed order — see {@link getDisplayedRows}. */
+  rows: ReadonlyArray<Row<TMDataGridFeatures, TData>>;
+  rowId: string;
+  /** The pivot a shift-click extends from. */
+  anchorRowId: string | null;
+  modifiers: TMDataGridRowClickModifiers;
+  selection: RowSelectionState;
+  /**
+   * Whether this gesture is allowed to clear rows it did not touch.
+   *
+   * `true` for a bare row click, where replacing is the whole point. `false` for
+   * a checkbox, which is only ever additive — ticking one box has never cleared
+   * the others, and shift-clicking one adds the range rather than becoming it.
+   */
+  canReplaceSelection: boolean;
+};
+
+export type ResolvedRowSelection = {
+  selection: RowSelectionState;
+  anchorRowId: string | null;
+};
+
+/**
+ * The row ids one gesture on this row selects.
+ *
+ * A group row is never selected itself: it holds no record, and TanStack
+ * derives its checked state from its descendants. So ticking a group means
+ * ticking every selectable leaf under it, which is also what makes the group's
+ * own box light up.
+ *
+ * Leaves rather than direct children, so one click on a top-level group takes
+ * the whole subtree however deeply it nests.
+ */
+export function getSelectableRowIds<TData extends RowData>(
+  row: Row<TMDataGridFeatures, TData>,
+): Array<string> {
+  return getGroupDataRows(row)
+    .filter((dataRow) => dataRow.getCanSelect())
+    .map((dataRow) => dataRow.id);
+}
+
+/**
+ * Turns one click into the next selection, following the convention every
+ * desktop list uses:
+ *
+ * | Gesture | Effect |
+ * | ------- | ------ |
+ * | Click | selection becomes only this row |
+ * | Ctrl/Cmd + click | toggle this row, leave the rest |
+ * | Shift + click | selection becomes the range anchor → this row |
+ * | Ctrl/Cmd + Shift + click | add that range to the selection |
+ *
+ * The anchor is a *pivot*, not "the last row touched": only a plain or
+ * Ctrl-click moves it, which is what lets a run of shift-clicks grow and shrink
+ * the same range from a fixed point.
+ *
+ * Selection state is rebuilt here and handed to `setRowSelection` wholesale
+ * rather than going through `row.toggleSelected()` per row, which would publish
+ * one state update each. That skips TanStack's sub-row cascade, so the cascade
+ * is done here instead: every row in the gesture is expanded through
+ * {@link getSelectableRowIds} before it reaches the map. Under grouping that is
+ * what makes one tick on a group select all of it.
+ */
+export function resolveRowSelectionClick<TData extends RowData>({
+  rows,
+  rowId,
+  anchorRowId,
+  modifiers,
+  selection,
+  canReplaceSelection,
+}: ResolveRowSelectionClickArgs<TData>): ResolvedRowSelection {
+  const index = rows.findIndex((row) => row.id === rowId);
+  const clickedRow = rows[index];
+  // Clicked row is not in the displayed set — nothing sensible to resolve.
+  if (index === -1 || clickedRow === undefined) return { selection, anchorRowId };
+
+  const targets = getSelectableRowIds(clickedRow);
+  // Nothing selectable under this gesture: a row the predicate refuses, or a
+  // group whose every leaf refuses.
+  if (targets.length === 0) return { selection, anchorRowId };
+
+  // `enableMultiRowSelection: false`, or the per-row predicate saying no: one
+  // row at a time, so the modifiers have nothing to build on and every gesture
+  // collapses to a single id.
+  //
+  // This has to be enforced here. Rebuilding the map and handing it to
+  // `setRowSelection` skips `mutateRowIsSelected`, which is where TanStack
+  // clears the other rows — so without this, Ctrl and Shift would quietly
+  // produce the multi-selection the option ruled out.
+  if (!clickedRow.getCanMultiSelect()) {
+    // A group stands for several rows, which single-select cannot express. The
+    // checkbox column drops the box on those rows for the same reason.
+    const only = targets.length === 1 ? targets[0] : undefined;
+    if (only === undefined) return { selection, anchorRowId };
+    // A checkbox must still be able to untick the one selected row; a row click
+    // only ever sets, so re-clicking it cannot empty the selection.
+    const untick = !canReplaceSelection && selection[only] === true;
+    return {
+      selection: untick ? {} : { [only]: true },
+      anchorRowId: rowId,
+    };
+  }
+
+  const anchorIndex =
+    anchorRowId === null
+      ? -1
+      : rows.findIndex((row) => row.id === anchorRowId);
+
+  // A range needs a pivot that is still on screen. When the anchor has been
+  // filtered or paged away, fall through and treat this as a fresh click.
+  if (modifiers.extend && anchorIndex !== -1) {
+    const from = Math.min(anchorIndex, index);
+    const to = Math.max(anchorIndex, index);
+    // Ctrl+Shift adds to what is already selected; Shift alone becomes the
+    // range — unless the gesture may not replace, in which case it also adds.
+    const next: RowSelectionState =
+      modifiers.toggle || !canReplaceSelection ? { ...selection } : {};
+    for (const row of rows.slice(from, to + 1)) {
+      // A group row inside the range brings its whole subtree, including leaves
+      // that are collapsed out of `rows` — sweeping past a closed group selects
+      // it entire, which is the only reading that matches what it displays.
+      for (const id of getSelectableRowIds(row)) next[id] = true;
+    }
+    // The pivot deliberately stays put.
+    return { selection: next, anchorRowId };
+  }
+
+  if (modifiers.toggle || !canReplaceSelection) {
+    const next: RowSelectionState = { ...selection };
+    // Asked of the targets rather than of `rowId`: a group row carries no id in
+    // the map, so it counts as selected exactly when all of its leaves do —
+    // which is also when its checkbox shows a tick rather than a dash.
+    const allSelected = targets.every((id) => selection[id] === true);
+    for (const id of targets) {
+      if (allSelected) delete next[id];
+      else next[id] = true;
+    }
+    return { selection: next, anchorRowId: rowId };
+  }
+
+  const next: RowSelectionState = {};
+  for (const id of targets) next[id] = true;
+  return { selection: next, anchorRowId: rowId };
+}

package/src/tmdatagrid/core/summary.ts

@@ -0,0 +1,35 @@
+import { aggregationFns, type RowData } from "@tanstack/react-table";
+import type { TMDataGridRowData } from "../TMDataGridContext";
+import type { TMDataGridTable } from "../useTMDataGrid";
+
+/** The registered aggregation names — the same set `aggregationFn` accepts. */
+export type TMDataGridAggregationName = keyof typeof aggregationFns;
+
+/**
+ * One column aggregated over every filtered row — the number a summary-row
+ * `footer` wants:
+ *
+ * ```tsx
+ * columnHelper.accessor("salary", {
+ *   footer: ({ table }) => sek(Number(aggregateColumn({ table, columnId: "salary" }))),
+ * });
+ * ```
+ *
+ * Filtered rather than paginated rows, so the total covers everything the
+ * filters left — all pages — and follows the filters as they change. Reuses
+ * TanStack's registered aggregation functions; `fn` defaults to `"sum"`.
+ */
+export function aggregateColumn<TData extends RowData>({
+  table,
+  columnId,
+  fn = "sum",
+}: {
+  table: TMDataGridTable<TData>;
+  columnId: string;
+  fn?: TMDataGridAggregationName;
+}): unknown {
+  const erased = table as unknown as TMDataGridTable<TMDataGridRowData>;
+  const rows = erased.getFilteredRowModel().rows;
+  // Leaf and child rows are the same set here: the filtered model is flat.
+  return aggregationFns[fn](columnId, rows, rows);
+}

package/src/tmdatagrid/index.ts

@@ -1,16 +1,24 @@
 export { TMDataGrid, type TMDataGridProps } from "./components/TMDataGrid";
 export {
+  useCellControlTabIndex,
   useTMDataGridContext,
   type TMDataGridContextValue,
   type TMDataGridRowData,
 } from "./TMDataGridContext";
 export { SELECT_COLUMN_ID } from "./components/TMDataGridSelectColumn";
+export { DETAILS_COLUMN_ID } from "./components/TMDataGridDetailsColumn";
+export {
+  formatGroupValue,
+  GROUP_COLUMN_ID,
+} from "./components/TMDataGridGroupColumn";
 export {
   createTMDataGridColumnHelper,
   openColumnFilter,
   tmDataGridFeatures,
   type TMDataGridApi,
   type TMDataGridColumnMeta,
+  type TMDataGridDetailsArgs,
+  type TMDataGridDetailsRenderer,
   type TMDataGridFeatures,
   type TMDataGridTable,
   type TMDataGridTableMeta,
@@ -20,18 +28,88 @@ export {
   useTMDataGrid,
   type UseTMDataGridOptions,
 } from "./useTMDataGrid";
+export {
+  TMDataGridFilterPills,
+  type TMDataGridFilterPillsProps,
+} from "./components/TMDataGridFilterPills";
+export {
+  TMDataGridSearch,
+  type TMDataGridSearchProps,
+} from "./components/TMDataGridSearch";
 export {
   type TMDataGridColumnType,
   type TMDataGridFilterOperator,
   type TMDataGridFilterValue,
   FILTER_OPERATOR_LABELS,
+  formatFilterLabel,
+  getDefaultOperator,
+  getOperatorsForType,
   isFilterActive,
+  operatorNeedsValue,
+  operatorTakesArrayValue,
 } from "./core/filterOperators";
+export {
+  optionsToComboboxData,
+  resolveColumnOptions,
+  type TMDataGridOption,
+  type TMDataGridOptionsArgs,
+  type TMDataGridOptionsSource,
+} from "./core/columnOptions";
+export {
+  mergeLabels,
+  TMDATAGRID_LABELS_EN,
+  type TMDataGridLabels,
+  type TMDataGridLabelsOverride,
+} from "./core/labels";
+export { TMDATAGRID_LABELS_SV } from "./core/labelsSv";
 export {
   getColumnLabel,
   getColumnType,
   isColumnReorderable,
+  isControlColumn,
 } from "./core/columnUtils";
+export { getGroupDataRows } from "./core/grouping";
+export {
+  aggregateColumn,
+  type TMDataGridAggregationName,
+} from "./core/summary";
+export { autosizeColumn, measureColumnContentWidth } from "./core/autosize";
+export {
+  isSameCell,
+  resolveCellMove,
+  type ResolveCellMoveArgs,
+  type TMDataGridCellCoords,
+  type TMDataGridCellPosition,
+} from "./core/cellNavigation";
+export {
+  boundsCellCount,
+  boundsEdges,
+  isWithinBounds,
+  resolveRangeBounds,
+  type ResolveRangeBoundsArgs,
+  type TMDataGridCellRange,
+  type TMDataGridRangeBounds,
+} from "./core/cellRange";
+export {
+  buildCellMatrix,
+  buildGridCellMatrix,
+  DEFAULT_CELL_EXPORT_OPTIONS,
+  downloadTextFile,
+  exportGridToCsv,
+  formatExportValue,
+  toClipboardText,
+  toExcelCsv,
+  writeClipboardText,
+  type BuildCellMatrixArgs,
+  type TMDataGridCellExportOptions,
+  type TMDataGridCellMatrix,
+} from "./core/cellExport";
+export {
+  areAllRowsExpanded,
+  resolveExpandAll,
+  type TMDataGridExpandAllArgs,
+  type TMDataGridExpandTarget,
+} from "./core/expanding";
 export {
   getColumnRegion,
   getStepTargetColumn,
@@ -46,11 +124,21 @@ export {
   getColumnCapabilities,
   getGridCapabilities,
   readFeatureFlags,
+  type TMDataGridCellSelectionMode,
   type TMDataGridCapabilities,
   type TMDataGridColumnCapabilities,
   type TMDataGridFeatureFlags,
-  type TMDataGridRowSelectionMode,
+  type TMDataGridSelectionMode,
 } from "./core/capabilities";
+export {
+  getDisplayedRows,
+  getSelectableRowIds,
+  isPagingActive,
+  resolveRowSelectionClick,
+  type ResolvedRowSelection,
+  type ResolveRowSelectionClickArgs,
+  type TMDataGridRowClickModifiers,
+} from "./core/rowSelection";
 export {
   DEFAULT_TMDATAGRID_SIZE,
   SIZE_CONTROL_SIZE,
@@ -66,7 +154,13 @@ export {
   type TMDataGridSettingsSlice,
   type TMDataGridStorageMode,
 } from "./core/persistence";
-export type { TMDataGridColumnLayout } from "./components/TMDataGridTable";
+export type {
+  TMDataGridCellNav,
+  TMDataGridColumnLayout,
+  TMDataGridRowContextMenu,
+  TMDataGridRowContextMenuArgs,
+  TMDataGridTableProps,
+} from "./components/TMDataGridTable";
 export {
   getTMDataGridPaginationApi,
   type TMDataGridFooterProps,