@jielga/tmdatagrid 0.5.0 → 1.0.0

package/src/tmdatagrid/core/quickSearch.ts

@@ -0,0 +1,144 @@
+import {
+  compareItems,
+  rankItem,
+  type RankingInfo,
+} from "@tanstack/match-sorter-utils";
+import {
+  createSortedRowModel,
+  type Row,
+  type RowData,
+  type RowModel,
+  type Table,
+  type TableFeatures,
+} from "@tanstack/react-table";
+
+/** How the quick search matches — see `quickSearchMode` on the hook options. */
+export type TMDataGridQuickSearchMode = "fuzzy" | "contains";
+
+/**
+ * The fuzzy filter's registry name — what `globalFilterFn` resolves to while
+ * `quickSearchMode` is `"fuzzy"`. The rank ordering keys off this name, so an
+ * explicit `globalFilterFn` override switches the ordering off with it.
+ */
+export const FUZZY_FILTER_FN_NAME = "tmDataGridFuzzy";
+
+/** What {@link fuzzyGlobalFilterFn} records per column via `addMeta`. */
+type FuzzyFilterMeta = { fuzzyRank: RankingInfo };
+
+function isFuzzyFilterMeta(value: unknown): value is FuzzyFilterMeta {
+  if (typeof value !== "object" || value === null) return false;
+  const rank = (value as { fuzzyRank?: unknown }).fuzzyRank;
+  return (
+    typeof rank === "object" &&
+    rank !== null &&
+    typeof (rank as { rank?: unknown }).rank === "number"
+  );
+}
+
+/**
+ * Match-sorter ranking as the global filter: a row passes when a globally
+ * filterable column ranks above match-sorter's threshold — typos and skipped
+ * characters forgiven — and the rank is recorded for the ordering to read.
+ *
+ * TanStack stops probing a row's columns at the first passing one, so the
+ * recorded ranks cover the columns up to and including it; the best of those
+ * stands for the row. Good enough for a quick search: the first passing
+ * column is almost always the one the user is looking at.
+ */
+export function fuzzyGlobalFilterFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(
+  row: Row<TFeatures, TData>,
+  columnId: string,
+  filterValue: unknown,
+  addMeta?: (meta: FuzzyFilterMeta) => void,
+): boolean {
+  const rank = rankItem(
+    String(row.getValue(columnId) ?? ""),
+    String(filterValue),
+  );
+  addMeta?.({ fuzzyRank: rank });
+  return rank.passed;
+}
+
+/** The best fuzzy rank any column recorded for this row, or `null`. */
+function bestRank<TFeatures extends TableFeatures, TData extends RowData>(
+  row: Row<TFeatures, TData>,
+): RankingInfo | null {
+  let best: RankingInfo | null = null;
+  // As a plain record, for the same generic-features reason as the options
+  // read in isRankingActive.
+  const { columnFiltersMeta } = row as {
+    columnFiltersMeta?: Record<string, unknown>;
+  };
+  for (const meta of Object.values(columnFiltersMeta ?? {})) {
+    if (!isFuzzyFilterMeta(meta)) continue;
+    if (best === null || meta.fuzzyRank.rank > best.rank) best = meta.fuzzyRank;
+  }
+  return best;
+}
+
+/**
+ * Whether the ranked ordering applies: the fuzzy quick search is narrowing
+ * the grid, and nothing else claims an order — no sort, no grouping.
+ */
+function isRankingActive<TFeatures extends TableFeatures, TData extends RowData>(
+  table: Table<TFeatures, TData>,
+): boolean {
+  // Off the options as a plain record: a generic `TFeatures` does not carry
+  // the global-filtering feature's option types, and this file stays generic
+  // to avoid a cycle with useTMDataGrid.
+  const { globalFilterFn } = table.options as { globalFilterFn?: unknown };
+  if (globalFilterFn !== FUZZY_FILTER_FN_NAME) return false;
+  const state = table.store.state as {
+    sorting?: Array<unknown>;
+    grouping?: Array<unknown>;
+    globalFilter?: unknown;
+  };
+  return (
+    (state.sorting?.length ?? 0) === 0 &&
+    (state.grouping?.length ?? 0) === 0 &&
+    typeof state.globalFilter === "string" &&
+    state.globalFilter.trim() !== ""
+  );
+}
+
+/**
+ * The sorted row model, with one addition: while {@link isRankingActive},
+ * rows order by match quality, best first. Declarative — the ordering is
+ * derived from filter state, never written into `sorting`, so no column
+ * claims `aria-sort`, the persisted slice stays untouched, and the user's
+ * next sort click suspends it just by existing.
+ *
+ * Sits upstream of pagination, so a ranked first page really is the best
+ * matches of the whole set.
+ */
+export function createFuzzyRankedSortedRowModel<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(): (table: Table<TFeatures, TData>) => () => RowModel<TFeatures, TData> {
+  const base = createSortedRowModel<TFeatures, TData>();
+  return (table) => {
+    const getSorted = base(table);
+    // One-slot memo: every input of the ordering — filter text, data, the
+    // sorting and grouping states — changes the sorted model's identity, so
+    // the model alone is the cache key.
+    let lastModel: RowModel<TFeatures, TData> | null = null;
+    let ranked: RowModel<TFeatures, TData> | null = null;
+    return () => {
+      const model = getSorted();
+      if (!isRankingActive(table)) return model;
+      if (model === lastModel && ranked !== null) return ranked;
+      const rows = [...model.rows].sort((a, b) => {
+        const rankA = bestRank(a);
+        const rankB = bestRank(b);
+        if (rankA !== null && rankB !== null) return compareItems(rankA, rankB);
+        return rankA !== null ? -1 : rankB !== null ? 1 : 0;
+      });
+      ranked = { rows, flatRows: model.flatRows, rowsById: model.rowsById };
+      lastModel = model;
+      return ranked;
+    };
+  };
+}

package/src/tmdatagrid/core/rowPinning.ts

@@ -0,0 +1,37 @@
+import type { Row, RowData } from "@tanstack/react-table";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+
+/**
+ * The rows pinned to one edge, resolved safely and in pin order.
+ *
+ * Not TanStack's `getTopRows()`: that resolves each pinned id with
+ * `getRow(id, true)`, which throws once the row's data is gone — and pinned
+ * ids outlive data. A delete, a server-side page swap, a refetch that comes
+ * back without the row: any of these would take the whole grid down. Here a
+ * stale id is skipped instead; it stays in state, harmless, and the row
+ * returns to its edge if its data comes back.
+ *
+ * The semantics are TanStack's `keepPinnedRows: true`: a pinned row stays at
+ * its edge even when a filter or the pager would have dropped it from the
+ * body. Ids resolve against the pre-pagination model first — those rows carry
+ * the live sort and filter context — with the core model as the fallback for
+ * rows the filters removed. A leaf whose group is collapsed stays hidden,
+ * as upstream does.
+ */
+export function readPinnedRows<TData extends RowData>(
+  table: TMDataGridTable<TData>,
+  position: "top" | "bottom",
+): Array<Row<TMDataGridFeatures, TData>> {
+  const ids = table.store.state.rowPinning[position];
+  if (ids.length === 0) return [];
+  const visible = table.getPrePaginatedRowModel().rowsById;
+  const all = table.getCoreRowModel().rowsById;
+  const rows: Array<Row<TMDataGridFeatures, TData>> = [];
+  for (const id of ids) {
+    const row = visible[id] ?? all[id];
+    if (row === undefined) continue;
+    if (!row.getIsAllParentsExpanded()) continue;
+    rows.push(row);
+  }
+  return rows;
+}

package/src/tmdatagrid/core/rowSelection.ts

@@ -14,14 +14,23 @@ import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
  * 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}.
+ *
+ * Rows pinned to an edge leave this list — they render in their own sticky
+ * blocks, outside the scrolling order a shift-click range or the virtualizer
+ * walks. See `readPinnedRows`.
  */
 export function getDisplayedRows<TData extends RowData>(
   table: TMDataGridTable<TData>,
   features: TMDataGridFeatureFlags,
 ): Array<Row<TMDataGridFeatures, TData>> {
-  return isPagingActive(table, features)
+  const rows = isPagingActive(table, features)
     ? table.getPaginatedRowModel().rows
     : table.getPrePaginatedRowModel().rows;
+  if (!features.rowPinning) return rows;
+  const { top, bottom } = table.store.state.rowPinning;
+  if (top.length === 0 && bottom.length === 0) return rows;
+  const pinned = new Set([...top, ...bottom]);
+  return rows.filter((row) => !pinned.has(row.id));
 }
 
 /**

package/src/tmdatagrid/index.ts

@@ -7,6 +7,8 @@ export {
 } from "./TMDataGridContext";
 export { SELECT_COLUMN_ID } from "./components/TMDataGridSelectColumn";
 export { DETAILS_COLUMN_ID } from "./components/TMDataGridDetailsColumn";
+export { EDIT_COLUMN_ID } from "./components/TMDataGridEditColumn";
+export { ROW_NUMBER_COLUMN_ID } from "./components/TMDataGridRowNumberColumn";
 export {
   formatGroupValue,
   GROUP_COLUMN_ID,
@@ -23,6 +25,9 @@ export {
   type TMDataGridTable,
   type TMDataGridTableMeta,
   type TMDataGridUiActions,
+  type TMDataGridEditingOptions,
+  type TMDataGridScrollAlign,
+  type TMDataGridScrollToRowArgs,
   type TMDataGridUiState,
   type TMDataGridUiStore,
   useTMDataGrid,
@@ -40,6 +45,7 @@ export {
   type TMDataGridColumnType,
   type TMDataGridFilterOperator,
   type TMDataGridFilterValue,
+  emptyValueForOperator,
   FILTER_OPERATOR_LABELS,
   formatFilterLabel,
   getDefaultOperator,
@@ -47,7 +53,12 @@ export {
   isFilterActive,
   operatorNeedsValue,
   operatorTakesArrayValue,
+  operatorTakesRangeValue,
 } from "./core/filterOperators";
+export {
+  fuzzyGlobalFilterFn,
+  type TMDataGridQuickSearchMode,
+} from "./core/quickSearch";
 export {
   optionsToComboboxData,
   resolveColumnOptions,
@@ -55,6 +66,42 @@ export {
   type TMDataGridOptionsArgs,
   type TMDataGridOptionsSource,
 } from "./core/columnOptions";
+export { TMDataGridEditActions } from "./components/TMDataGridEditActions";
+export {
+  clearedValueForType,
+  getEditFieldName,
+  normalizeFieldValidate,
+  type TMDataGridEditApi,
+  type TMDataGridEditChange,
+  type TMDataGridEditCommitArgs,
+  type TMDataGridEditCommitBatchArgs,
+  type TMDataGridEditField,
+  type TMDataGridEditMode,
+  type TMDataGridEditorArgs,
+  type TMDataGridEditorComponent,
+  type TMDataGridEditRowProjection,
+  type TMDataGridEditState,
+  type TMDataGridFieldValidate,
+  type TMDataGridRowAddArgs,
+  type TMDataGridRowDeleteArgs,
+  type TMDataGridRowEditForm,
+  type TMDataGridRowValidators,
+} from "./core/editEngine";
+export type {
+  TMDataGridFilterControlArgs,
+  TMDataGridFilterControlComponent,
+} from "./core/filterControls";
+export { TMDataGridFilterValueInput } from "./components/filters/TMDataGridFilterValueInput";
+export { DgRangeSliderFilter } from "./components/filters/DgRangeSliderFilter";
+export { DgDateRangeFilter } from "./components/filters/DgDateRangeFilter";
+export { DgAutocompleteFilter } from "./components/filters/DgAutocompleteFilter";
+export { DgTriStateFilter } from "./components/filters/DgTriStateFilter";
+export { TMDataGridStringEditor } from "./components/editors/TMDataGridStringEditor";
+export { TMDataGridNumberEditor } from "./components/editors/TMDataGridNumberEditor";
+export { TMDataGridBooleanEditor } from "./components/editors/TMDataGridBooleanEditor";
+export { TMDataGridDateEditor } from "./components/editors/TMDataGridDateEditor";
+export { TMDataGridSelectEditor } from "./components/editors/TMDataGridSelectEditor";
+export { TMDataGridMultiSelectEditor } from "./components/editors/TMDataGridMultiSelectEditor";
 export {
   mergeLabels,
   TMDATAGRID_LABELS_EN,
@@ -63,6 +110,7 @@ export {
 } from "./core/labels";
 export { TMDATAGRID_LABELS_SV } from "./core/labelsSv";
 export {
+  getColumnDefaultOperator,
   getColumnLabel,
   getColumnType,
   isColumnReorderable,
@@ -147,6 +195,7 @@ export {
 } from "./core/sizes";
 export {
   DATA_STATE_SLICES,
+  PERSIST_PAYLOAD_VERSION,
   SETTINGS_STATE_SLICES,
   type TMDataGridDataSlice,
   type TMDataGridPersistence,
@@ -155,10 +204,12 @@ export {
   type TMDataGridStorageMode,
 } from "./core/persistence";
 export type {
+  TMDataGridCellEventArgs,
   TMDataGridCellNav,
   TMDataGridColumnLayout,
   TMDataGridRowContextMenu,
   TMDataGridRowContextMenuArgs,
+  TMDataGridRowStyle,
   TMDataGridTableProps,
 } from "./components/TMDataGridTable";
 export {