@jielga/tmdatagrid 0.1.0

package/src/tmdatagrid/columnUtils.ts

@@ -0,0 +1,43 @@
+import type { TMDataGridColumnType } from "./filterOperators";
+import type { TMDataGridColumnMeta } from "./useTMDataGrid";
+
+/**
+ * Structural shape of the column bits the chrome reads. Kept minimal so these
+ * helpers work with any `Column`/`Header` instance without dragging generics
+ * through every call site.
+ */
+type ColumnLike = {
+  id: string;
+  columnDef: { header?: unknown; meta?: TMDataGridColumnMeta };
+  /** Set on a leaf that sits inside a header group. */
+  parent?: unknown;
+};
+
+/** Menu- and panel-facing column name. */
+export function getColumnLabel(column: ColumnLike): string {
+  const label = column.columnDef.meta?.label;
+  if (label) return label;
+  const header = column.columnDef.header;
+  return typeof header === "string" ? header : column.id;
+}
+
+export function getColumnType(column: ColumnLike): TMDataGridColumnType {
+  return column.columnDef.meta?.type ?? "string";
+}
+
+export function getColumnAlign(column: ColumnLike): "left" | "right" | "center" {
+  return column.columnDef.meta?.align ?? "left";
+}
+
+/**
+ * Whether a column may be moved. Ordering is the one column feature TanStack
+ * has no column option for, so the switch lives in `meta.enableOrdering`.
+ *
+ * A leaf inside a header group is never movable: `columnOrder` sequences leaf
+ * columns, so moving one out of its group would leave the group header spanning
+ * columns that no longer belong to it.
+ */
+export function isColumnReorderable(column: ColumnLike): boolean {
+  if (column.columnDef.meta?.enableOrdering === false) return false;
+  return column.parent === undefined;
+}

package/src/tmdatagrid/filterOperators.ts

@@ -0,0 +1,171 @@
+import type { Row, RowData, TableFeatures } from "@tanstack/react-table";
+
+/**
+ * The value shape stored in `columnFilters` for every TMDataGrid column.
+ *
+ * TanStack resolves `filterFn` statically per column, so the operator travels
+ * 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).
+ */
+export type TMDataGridFilterValue = {
+  operator: TMDataGridFilterOperator;
+  value: string;
+};
+
+export type TMDataGridColumnType = "string" | "number";
+
+export type TMDataGridFilterOperator =
+  | "contains"
+  | "equals"
+  | "notEquals"
+  | "startsWith"
+  | "endsWith"
+  | "greaterThan"
+  | "greaterThanOrEqual"
+  | "lessThan"
+  | "lessThanOrEqual"
+  | "isEmpty"
+  | "isNotEmpty";
+
+export const FILTER_OPERATOR_LABELS: Record<TMDataGridFilterOperator, string> = {
+  contains: "contains",
+  equals: "equals",
+  notEquals: "does not equal",
+  startsWith: "starts with",
+  endsWith: "ends with",
+  greaterThan: "is greater than",
+  greaterThanOrEqual: "is greater than or equal to",
+  lessThan: "is less than",
+  lessThanOrEqual: "is less than or equal to",
+  isEmpty: "is empty",
+  isNotEmpty: "is not empty",
+};
+
+const STRING_OPERATORS: readonly TMDataGridFilterOperator[] = [
+  "contains",
+  "equals",
+  "notEquals",
+  "startsWith",
+  "endsWith",
+  "isEmpty",
+  "isNotEmpty",
+];
+
+const NUMBER_OPERATORS: readonly TMDataGridFilterOperator[] = [
+  "equals",
+  "notEquals",
+  "greaterThan",
+  "greaterThanOrEqual",
+  "lessThan",
+  "lessThanOrEqual",
+  "isEmpty",
+  "isNotEmpty",
+];
+
+/** Operators that ignore the value input (the input is disabled for these). */
+const VALUELESS_OPERATORS: readonly TMDataGridFilterOperator[] = [
+  "isEmpty",
+  "isNotEmpty",
+];
+
+export function getOperatorsForType(
+  type: TMDataGridColumnType,
+): readonly TMDataGridFilterOperator[] {
+  return type === "number" ? NUMBER_OPERATORS : STRING_OPERATORS;
+}
+
+export function getDefaultOperator(
+  type: TMDataGridColumnType,
+): TMDataGridFilterOperator {
+  return type === "number" ? "equals" : "contains";
+}
+
+export function operatorNeedsValue(operator: TMDataGridFilterOperator): boolean {
+  return !VALUELESS_OPERATORS.includes(operator);
+}
+
+export function isTMDataGridFilterValue(
+  value: unknown,
+): value is TMDataGridFilterValue {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "operator" in value &&
+    typeof (value as TMDataGridFilterValue).operator === "string"
+  );
+}
+
+/**
+ * A filter only narrows the row set once it has something to compare against.
+ * Half-typed filters stay in state (so the panel keeps rendering their row) but
+ * are treated as inactive for the funnel indicator and for row matching.
+ */
+export function isFilterActive(value: unknown): boolean {
+  if (!isTMDataGridFilterValue(value)) return false;
+  return !operatorNeedsValue(value.operator) || value.value.trim() !== "";
+}
+
+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 !== "";
+  }
+
+  const filterText = value.trim();
+  if (filterText === "") return true;
+
+  const numericCell = typeof cellValue === "number" ? cellValue : Number.NaN;
+  const numericFilter = Number(filterText);
+  const compareNumeric =
+    !Number.isNaN(numericCell) && !Number.isNaN(numericFilter);
+
+  switch (operator) {
+    case "greaterThan":
+      return compareNumeric && numericCell > numericFilter;
+    case "greaterThanOrEqual":
+      return compareNumeric && numericCell >= numericFilter;
+    case "lessThan":
+      return compareNumeric && numericCell < numericFilter;
+    case "lessThanOrEqual":
+      return compareNumeric && numericCell <= numericFilter;
+    default:
+      break;
+  }
+
+  const cellText = String(cellValue ?? "").toLowerCase();
+  const needle = filterText.toLowerCase();
+
+  switch (operator) {
+    case "contains":
+      return cellText.includes(needle);
+    case "equals":
+      return compareNumeric ? numericCell === numericFilter : cellText === needle;
+    case "notEquals":
+      return compareNumeric ? numericCell !== numericFilter : cellText !== needle;
+    case "startsWith":
+      return cellText.startsWith(needle);
+    case "endsWith":
+      return cellText.endsWith(needle);
+    default:
+      return true;
+  }
+}
+
+/**
+ * The single filter function every TMDataGrid column uses. It dispatches on the
+ * operator carried by the filter value, which is what lets one column offer
+ * "contains" / "does not equal" / "is empty" without redefining the column.
+ */
+export function tmDataGridFilterFn<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+>(row: Row<TFeatures, TData>, columnId: string, filterValue: unknown): boolean {
+  if (!isTMDataGridFilterValue(filterValue)) return true;
+  return matchesFilter(row.getValue(columnId), filterValue);
+}

package/src/tmdatagrid/icons.ts

@@ -0,0 +1,25 @@
+/**
+ * The grid's icon set, aliased in one place so swapping icon libraries is a
+ * single-file change.
+ *
+ * `@tabler/icons-react` ships one ES module per icon and declares
+ * `sideEffects: false`, so only the icons re-exported here reach the bundle.
+ */
+export {
+  IconArrowDown as ArrowDownIcon,
+  IconArrowLeft as MoveLeftIcon,
+  IconArrowRight as MoveRightIcon,
+  IconArrowUp as ArrowUpIcon,
+  IconChevronLeft as ChevronLeftIcon,
+  IconChevronRight as ChevronRightIcon,
+  IconColumns3 as ColumnsIcon,
+  IconDotsVertical as DotsVerticalIcon,
+  IconEyeOff as EyeOffIcon,
+  IconFilter as FilterIcon,
+  IconArrowBarToLeft as PinLeftIcon,
+  IconArrowBarToRight as PinRightIcon,
+  IconMenu2 as BurgerIcon,
+  IconPinnedOff as PinOffIcon,
+  IconSearch as SearchIcon,
+  IconX as CloseIcon,
+} from "@tabler/icons-react";

package/src/tmdatagrid/index.ts

@@ -0,0 +1,68 @@
+export { TMDataGrid, type TMDataGridProps } from "./TMDataGrid";
+export {
+  useTMDataGridContext,
+  type TMDataGridContextValue,
+  type TMDataGridRowData,
+} from "./TMDataGridContext";
+export {
+  createTMDataGridColumnHelper,
+  openColumnFilter,
+  SELECT_COLUMN_ID,
+  tmDataGridFeatures,
+  type TMDataGridApi,
+  type TMDataGridColumnMeta,
+  type TMDataGridFeatures,
+  type TMDataGridTable,
+  type TMDataGridTableMeta,
+  type TMDataGridUiActions,
+  type TMDataGridUiState,
+  type TMDataGridUiStore,
+  useTMDataGrid,
+  type UseTMDataGridOptions,
+} from "./useTMDataGrid";
+export {
+  type TMDataGridColumnType,
+  type TMDataGridFilterOperator,
+  type TMDataGridFilterValue,
+  FILTER_OPERATOR_LABELS,
+  isFilterActive,
+} from "./filterOperators";
+export {
+  getColumnLabel,
+  getColumnType,
+  isColumnReorderable,
+} from "./columnUtils";
+export {
+  getColumnRegion,
+  getStepTargetColumn,
+  moveColumn,
+  moveColumnByStep,
+  type ColumnStepArgs,
+  type MoveColumnArgs,
+  type TMDataGridColumnRegion,
+  type TMDataGridDropSide,
+} from "./columnOrdering";
+export {
+  getColumnCapabilities,
+  getGridCapabilities,
+  readFeatureFlags,
+  type TMDataGridCapabilities,
+  type TMDataGridColumnCapabilities,
+  type TMDataGridFeatureFlags,
+} from "./capabilities";
+export {
+  DEFAULT_TMDATAGRID_SIZE,
+  SIZE_CONTROL_SIZE,
+  SIZE_ROW_HEIGHT,
+  type TMDataGridSize,
+} from "./sizes";
+export {
+  DATA_STATE_SLICES,
+  SETTINGS_STATE_SLICES,
+  type TMDataGridDataSlice,
+  type TMDataGridPersistence,
+  type TMDataGridPersistKey,
+  type TMDataGridSettingsSlice,
+  type TMDataGridStorageMode,
+} from "./persistence";
+export type { TMDataGridColumnLayout } from "./TMDataGridTable";

package/src/tmdatagrid/persistence.ts

@@ -0,0 +1,187 @@
+import type { TableState } from "@tanstack/react-table";
+import type { TMDataGridFeatures } from "./useTMDataGrid";
+
+type GridState = TableState<TMDataGridFeatures>;
+
+/**
+ * Persistence deliberately does not use Mantine's `useLocalStorage`.
+ *
+ * That hook owns a piece of state and returns `[value, setValue]`. Here the
+ * table already owns the state and storage only mirrors it, so routing writes
+ * through the hook would keep a second copy and trigger a React state update on
+ * every change, including every pointer move during a column resize. Its
+ * defaults also work against this use: `getInitialValueInEffect: true` delivers
+ * the stored value after mount, while `initialState` is only read on the first
+ * render, and `sync: true` would let two open tabs overwrite each other's
+ * column layout.
+ *
+ * The option vocabulary follows Mantine's: `StorageType` is its type, and
+ * `serialize` / `deserialize` behave as they do in `UseStorageOptions`.
+ */
+
+/**
+ * State slices describing what the user is looking at. Derived from the data,
+ * so they can go stale as it changes.
+ */
+export const DATA_STATE_SLICES = [
+  "columnFilters",
+  "globalFilter",
+  "sorting",
+  "pagination",
+] as const satisfies ReadonlyArray<keyof GridState>;
+
+/**
+ * State slices describing how the user configured the grid. Independent of the
+ * data, and the ones users notice losing.
+ */
+export const SETTINGS_STATE_SLICES = [
+  "columnVisibility",
+  "columnSizing",
+  "columnOrder",
+  "columnPinning",
+] as const satisfies ReadonlyArray<keyof GridState>;
+
+export type TMDataGridDataSlice = (typeof DATA_STATE_SLICES)[number];
+export type TMDataGridSettingsSlice = (typeof SETTINGS_STATE_SLICES)[number];
+
+/**
+ * A storage key, optionally narrowed to a subset of its group's slices.
+ *
+ * - `"employees.data"` — persists every slice in the group.
+ * - `["employees.data", ["sorting"]]` — persists only the listed slices.
+ */
+export type TMDataGridPersistKey<TSlice extends string> =
+  | string
+  | readonly [key: string, slices: readonly TSlice[]];
+
+/** Same values as Mantine's `StorageType`, which the package does not re-export. */
+export type TMDataGridStorageMode = "localStorage" | "sessionStorage";
+
+export type TMDataGridPersistence = {
+  /** Key for filters, global filter, sorting and pagination. */
+  dataKey?: TMDataGridPersistKey<TMDataGridDataSlice>;
+  /** Key for column visibility, sizing, order and pinning. */
+  settingsKey?: TMDataGridPersistKey<TMDataGridSettingsSlice>;
+  /** Which storage area to use. Defaults to `"localStorage"`. */
+  storageMode?: TMDataGridStorageMode;
+  /** Serializes a payload before it is stored. Defaults to `JSON.stringify`. */
+  serialize?: (value: Partial<GridState>) => string;
+  /** Parses a stored payload. Defaults to `JSON.parse`. */
+  deserialize?: (value: string) => unknown;
+};
+
+type ResolvedKey = { key: string; slices: ReadonlyArray<keyof GridState> };
+
+function resolveKey<TSlice extends string>(
+  entry: TMDataGridPersistKey<TSlice> | undefined,
+  defaultSlices: ReadonlyArray<keyof GridState>,
+): ResolvedKey | null {
+  if (!entry) return null;
+  if (typeof entry === "string") return { key: entry, slices: defaultSlices };
+
+  const [key, slices] = entry;
+  if (!key) return null;
+  // An empty list means nothing was selected, which is not the same as "all".
+  return { key, slices: slices as ReadonlyArray<keyof GridState> };
+}
+
+function resolveStorage(
+  persistence: TMDataGridPersistence | undefined,
+): Storage | null {
+  if (!persistence) return null;
+  // Absent under SSR, and access throws outright in some privacy modes.
+  try {
+    if (typeof window === "undefined") return null;
+    return persistence.storageMode === "sessionStorage"
+      ? window.sessionStorage
+      : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function readSlices(
+  storage: Storage | null,
+  resolved: ResolvedKey | null,
+  deserialize: (value: string) => unknown,
+): Partial<GridState> {
+  if (!storage || !resolved) return {};
+  try {
+    const raw = storage.getItem(resolved.key);
+    if (!raw) return {};
+    const parsed = deserialize(raw);
+    if (typeof parsed !== "object" || parsed === null) return {};
+
+    const record = parsed as Record<string, unknown>;
+    const restored: Record<string, unknown> = {};
+    // Only copy the selected slices. A payload written before the selection was
+    // narrowed cannot reintroduce slices the caller has since opted out of.
+    for (const slice of resolved.slices) {
+      if (slice in record) restored[slice] = record[slice];
+    }
+    return restored as Partial<GridState>;
+  } catch {
+    return {};
+  }
+}
+
+function writeSlices(
+  storage: Storage | null,
+  resolved: ResolvedKey | null,
+  state: GridState,
+  serialize: (value: Partial<GridState>) => string,
+): void {
+  if (!storage || !resolved) return;
+  const payload: Record<string, unknown> = {};
+  for (const slice of resolved.slices) payload[slice] = state[slice];
+  try {
+    storage.setItem(resolved.key, serialize(payload as Partial<GridState>));
+  } catch {
+    // Quota exceeded or storage disabled. Persistence is best effort.
+  }
+}
+
+function resolveKeys(persistence: TMDataGridPersistence | undefined) {
+  return {
+    data: resolveKey(persistence?.dataKey, DATA_STATE_SLICES),
+    settings: resolveKey(persistence?.settingsKey, SETTINGS_STATE_SLICES),
+  };
+}
+
+/** True when at least one key is configured. */
+export function hasPersistenceKeys(
+  persistence: TMDataGridPersistence | undefined,
+): boolean {
+  const { data, settings } = resolveKeys(persistence);
+  return data !== null || settings !== null;
+}
+
+const defaultDeserialize = (value: string): unknown => JSON.parse(value);
+const defaultSerialize = (value: Partial<GridState>): string =>
+  JSON.stringify(value);
+
+/** State to merge into `initialState`, read once on mount. */
+export function readPersistedState(
+  persistence?: TMDataGridPersistence,
+): Partial<GridState> {
+  const storage = resolveStorage(persistence);
+  const { data, settings } = resolveKeys(persistence);
+  const deserialize = persistence?.deserialize ?? defaultDeserialize;
+  return {
+    ...readSlices(storage, settings, deserialize),
+    ...readSlices(storage, data, deserialize),
+  };
+}
+
+/** Writes both payloads. Called on every table state change. */
+export function writePersistedState(
+  state: GridState,
+  persistence?: TMDataGridPersistence,
+): void {
+  const storage = resolveStorage(persistence);
+  if (!storage) return;
+  const { data, settings } = resolveKeys(persistence);
+  const serialize = persistence?.serialize ?? defaultSerialize;
+  writeSlices(storage, data, state, serialize);
+  writeSlices(storage, settings, state, serialize);
+}

package/src/tmdatagrid/sizes.ts

@@ -0,0 +1,29 @@
+import type { MantineSize } from "@mantine/core";
+
+export type TMDataGridSize = MantineSize;
+
+export const DEFAULT_TMDATAGRID_SIZE: TMDataGridSize = "md";
+
+/**
+ * Row height per size, in px.
+ *
+ * The virtualizer needs this as a number — it cannot read the CSS variable —
+ * so the scale lives here and `TMDataGrid.module.css` mirrors it. `meta.rowHeight`
+ * overrides it when a grid needs a height the scale doesn't offer.
+ */
+export const SIZE_ROW_HEIGHT: Record<TMDataGridSize, number> = {
+  xs: 34,
+  sm: 42,
+  md: 52,
+  lg: 62,
+  xl: 72,
+};
+
+/** Size of the Mantine controls rendered inside the grid chrome. */
+export const SIZE_CONTROL_SIZE: Record<TMDataGridSize, MantineSize> = {
+  xs: "xs",
+  sm: "xs",
+  md: "sm",
+  lg: "sm",
+  xl: "md",
+};