@dashforge/tw 0.5.0-beta → 0.7.0-beta

package/src/components/_shared/data/useTableSelection.test.ts

@@ -0,0 +1,100 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useState } from 'react';
+import { useTableSelection } from './useTableSelection.js';
+
+function setup(mode: 'none' | 'single' | 'multiple', initial: string[] = []) {
+  return renderHook(() => {
+    const [ids, setIds] = useState<string[]>(initial);
+    const setIdsWithFn = (next: string[] | ((prev: string[]) => string[])) =>
+      setIds((prev) => (typeof next === 'function' ? next(prev) : next));
+    const selection = useTableSelection(mode, ids, setIdsWithFn);
+    return { ids, selection };
+  });
+}
+
+describe('useTableSelection — single mode', () => {
+  it('toggleRow selects when not selected', () => {
+    const { result } = setup('single');
+    act(() => result.current.selection.toggleRow('a'));
+    expect(result.current.ids).toEqual(['a']);
+  });
+
+  it('toggleRow on a different row REPLACES', () => {
+    const { result } = setup('single', ['a']);
+    act(() => result.current.selection.toggleRow('b'));
+    expect(result.current.ids).toEqual(['b']);
+  });
+
+  it('toggleRow on same row DESELECTS', () => {
+    const { result } = setup('single', ['a']);
+    act(() => result.current.selection.toggleRow('a'));
+    expect(result.current.ids).toEqual([]);
+  });
+});
+
+describe('useTableSelection — multiple mode', () => {
+  it('toggleRow ADDS to selection', () => {
+    const { result } = setup('multiple');
+    act(() => result.current.selection.toggleRow('a'));
+    act(() => result.current.selection.toggleRow('b'));
+    expect(result.current.ids.sort()).toEqual(['a', 'b']);
+  });
+
+  it('toggleRow on selected row REMOVES', () => {
+    const { result } = setup('multiple', ['a', 'b']);
+    act(() => result.current.selection.toggleRow('a'));
+    expect(result.current.ids).toEqual(['b']);
+  });
+
+  it('toggleAll selects all when none selected', () => {
+    const { result } = setup('multiple');
+    act(() => result.current.selection.toggleAll(['a', 'b', 'c']));
+    expect(result.current.ids).toEqual(['a', 'b', 'c']);
+  });
+
+  it('toggleAll deselects all when all already selected', () => {
+    const { result } = setup('multiple', ['a', 'b', 'c']);
+    act(() => result.current.selection.toggleAll(['a', 'b', 'c']));
+    expect(result.current.ids).toEqual([]);
+  });
+
+  it('toggleAll selects all when SOME already selected', () => {
+    const { result } = setup('multiple', ['a']);
+    act(() => result.current.selection.toggleAll(['a', 'b', 'c']));
+    expect(result.current.ids).toEqual(['a', 'b', 'c']);
+  });
+
+  it('isAllSelected reflects state', () => {
+    const { result } = setup('multiple', ['a', 'b']);
+    expect(result.current.selection.isAllSelected(['a', 'b'])).toBe(true);
+    expect(result.current.selection.isAllSelected(['a', 'b', 'c'])).toBe(false);
+  });
+
+  it('isIndeterminate is true when some but not all selected', () => {
+    const { result } = setup('multiple', ['a']);
+    expect(result.current.selection.isIndeterminate(['a', 'b', 'c'])).toBe(true);
+    expect(result.current.selection.isIndeterminate(['a'])).toBe(false); // all selected → false
+  });
+
+  it('clearSelection resets to empty', () => {
+    const { result } = setup('multiple', ['a', 'b', 'c']);
+    act(() => result.current.selection.clearSelection());
+    expect(result.current.ids).toEqual([]);
+  });
+});
+
+describe('useTableSelection — none mode', () => {
+  it('toggleRow is no-op', () => {
+    const { result } = setup('none');
+    act(() => result.current.selection.toggleRow('a'));
+    expect(result.current.ids).toEqual([]);
+  });
+
+  it('toggleAll is no-op', () => {
+    const { result } = setup('none');
+    act(() => result.current.selection.toggleAll(['a', 'b']));
+    expect(result.current.ids).toEqual([]);
+  });
+});

package/src/components/_shared/data/useTableSelection.ts

@@ -0,0 +1,100 @@
+import { useCallback, useMemo } from 'react';
+import type { TableRowSelectionMode } from '../../Table/table.types.js';
+
+export interface UseTableSelectionResult {
+  selectedRowIds: string[];
+  isSelected: (rowId: string) => boolean;
+  toggleRow: (rowId: string) => void;
+  toggleAll: (allRowIds: string[]) => void;
+  clearSelection: () => void;
+  /** True when EVERY id in `allRowIds` is selected. */
+  isAllSelected: (allRowIds: string[]) => boolean;
+  /** True when at least one (but not all) of `allRowIds` is selected. */
+  isIndeterminate: (allRowIds: string[]) => boolean;
+}
+
+/**
+ * Selection logic helper. Given the controllable selection state +
+ * the setter (from `useControllableState`), exposes ergonomic
+ * helpers the Table calls from its render path.
+ *
+ *  - `single` mode: at most one row selected. Toggling another
+ *    replaces the previous.
+ *  - `multiple` mode: any subset selectable; toggling adds/removes.
+ *  - `none` mode: every toggle is a no-op (the Table shouldn't
+ *    render the checkbox cells anyway, but this is defensive).
+ */
+export function useTableSelection(
+  mode: TableRowSelectionMode,
+  selectedRowIds: string[],
+  setSelectedRowIds: (next: string[] | ((prev: string[]) => string[])) => void,
+): UseTableSelectionResult {
+  const selectedSet = useMemo(
+    () => new Set(selectedRowIds),
+    [selectedRowIds],
+  );
+
+  const isSelected = useCallback(
+    (rowId: string) => selectedSet.has(rowId),
+    [selectedSet],
+  );
+
+  const toggleRow = useCallback(
+    (rowId: string) => {
+      if (mode === 'none') return;
+      if (mode === 'single') {
+        setSelectedRowIds(selectedSet.has(rowId) ? [] : [rowId]);
+        return;
+      }
+      // multiple
+      setSelectedRowIds((prev) => {
+        const next = new Set(prev);
+        if (next.has(rowId)) next.delete(rowId);
+        else next.add(rowId);
+        return [...next];
+      });
+    },
+    [mode, selectedSet, setSelectedRowIds],
+  );
+
+  const toggleAll = useCallback(
+    (allRowIds: string[]) => {
+      if (mode !== 'multiple') return;
+      const allSelected = allRowIds.every((id) => selectedSet.has(id));
+      setSelectedRowIds(allSelected ? [] : [...allRowIds]);
+    },
+    [mode, selectedSet, setSelectedRowIds],
+  );
+
+  const clearSelection = useCallback(() => {
+    setSelectedRowIds([]);
+  }, [setSelectedRowIds]);
+
+  const isAllSelected = useCallback(
+    (allRowIds: string[]) => {
+      if (allRowIds.length === 0) return false;
+      return allRowIds.every((id) => selectedSet.has(id));
+    },
+    [selectedSet],
+  );
+
+  const isIndeterminate = useCallback(
+    (allRowIds: string[]) => {
+      if (allRowIds.length === 0) return false;
+      const some = allRowIds.some((id) => selectedSet.has(id));
+      const all = allRowIds.every((id) => selectedSet.has(id));
+      return some && !all;
+    },
+    [selectedSet],
+  );
+
+  return {
+    selectedRowIds,
+    isSelected,
+    toggleRow,
+    toggleAll,
+    clearSelection,
+    isAllSelected,
+    isIndeterminate,
+  };
+}

package/src/components/_shared/data/useTableSort.test.ts

@@ -0,0 +1,150 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useTableSort, cycleSortFor } from './useTableSort.js';
+import type { TableColumn, TableSortModel } from '../../Table/table.types.js';
+
+interface Row {
+  id: string;
+  name: string;
+  age: number | null;
+  joinedAt: Date | null;
+}
+
+const cols: TableColumn<Row>[] = [
+  { field: 'name',     header: 'Name',     sortable: true },
+  { field: 'age',      header: 'Age',      sortable: true },
+  { field: 'joinedAt' as never, header: 'Joined', sortable: true },
+];
+
+const rows: Row[] = [
+  { id: '1', name: 'Charlie', age: 30,   joinedAt: new Date('2024-01-15') },
+  { id: '2', name: 'Alice',   age: 25,   joinedAt: new Date('2024-03-01') },
+  { id: '3', name: 'Bob',     age: null, joinedAt: null },
+  { id: '4', name: 'alice',   age: 40,   joinedAt: new Date('2024-02-10') },
+];
+
+describe('useTableSort', () => {
+  it('returns rows untouched when sortModel is empty', () => {
+    const { result } = renderHook(() => useTableSort(rows, cols, []));
+    expect(result.current.map((r) => r.id)).toEqual(['1', '2', '3', '4']);
+  });
+
+  it('sorts strings asc (case-insensitive)', () => {
+    const sortModel: TableSortModel = [{ field: 'name', direction: 'asc' }];
+    const { result } = renderHook(() => useTableSort(rows, cols, sortModel));
+    // alice < Alice < Bob < Charlie (case-insensitive)
+    expect(result.current.map((r) => r.name.toLowerCase())).toEqual([
+      'alice', 'alice', 'bob', 'charlie',
+    ]);
+  });
+
+  it('sorts numbers desc', () => {
+    const sortModel: TableSortModel = [{ field: 'age', direction: 'desc' }];
+    const { result } = renderHook(() => useTableSort(rows, cols, sortModel));
+    // 40, 30, 25, null-last
+    expect(result.current.map((r) => r.age)).toEqual([40, 30, 25, null]);
+  });
+
+  it('places null values LAST regardless of direction (asc)', () => {
+    const sortModel: TableSortModel = [{ field: 'age', direction: 'asc' }];
+    const { result } = renderHook(() => useTableSort(rows, cols, sortModel));
+    // 25, 30, 40, null-last
+    expect(result.current.map((r) => r.age)).toEqual([25, 30, 40, null]);
+  });
+
+  it('sorts Date asc (epoch ms order)', () => {
+    const sortModel: TableSortModel = [{ field: 'joinedAt', direction: 'asc' }];
+    const { result } = renderHook(() => useTableSort(rows, cols, sortModel));
+    // 2024-01-15 → 2024-02-10 → 2024-03-01 → null-last
+    expect(result.current.map((r) => r.id)).toEqual(['1', '4', '2', '3']);
+  });
+
+  it('supports custom comparator', () => {
+    const colsCustom: TableColumn<Row>[] = [
+      // Sort by length of name ascending
+      { field: 'name', header: 'Name', sortable: (a, b) => a.name.length - b.name.length },
+    ];
+    const sortModel: TableSortModel = [{ field: 'name', direction: 'asc' }];
+    const { result } = renderHook(() => useTableSort(rows, colsCustom, sortModel));
+    expect(result.current.map((r) => r.name)).toEqual(['Bob', 'Alice', 'alice', 'Charlie']);
+  });
+
+  it('falls back to next sort item on tie (multi-column sort)', () => {
+    const sortModel: TableSortModel = [
+      { field: 'name', direction: 'asc' },  // 'alice', 'Alice' tie
+      { field: 'age',  direction: 'asc' },  // then 25 before 40
+    ];
+    const { result } = renderHook(() => useTableSort(rows, cols, sortModel));
+    // 'alice' and 'Alice' tie on name → 25 before 40 → so id=2 before id=4
+    expect(result.current.slice(0, 2).map((r) => r.id)).toEqual(['2', '4']);
+  });
+
+  it('ignores sort items for non-sortable columns', () => {
+    const colsNotSortable: TableColumn<Row>[] = cols.map((c) => ({ ...c, sortable: false }));
+    const sortModel: TableSortModel = [{ field: 'name', direction: 'asc' }];
+    const { result } = renderHook(() => useTableSort(rows, colsNotSortable, sortModel));
+    // Original order preserved
+    expect(result.current.map((r) => r.id)).toEqual(['1', '2', '3', '4']);
+  });
+});
+
+describe('cycleSortFor', () => {
+  it('none → asc on first click', () => {
+    expect(cycleSortFor([], 'name', false)).toEqual([{ field: 'name', direction: 'asc' }]);
+  });
+
+  it('asc → desc on second click', () => {
+    expect(cycleSortFor([{ field: 'name', direction: 'asc' }], 'name', false)).toEqual([
+      { field: 'name', direction: 'desc' },
+    ]);
+  });
+
+  it('desc → none (empty) on third click', () => {
+    expect(cycleSortFor([{ field: 'name', direction: 'desc' }], 'name', false)).toEqual([]);
+  });
+
+  it('single-click on different column REPLACES sort', () => {
+    expect(
+      cycleSortFor([{ field: 'name', direction: 'asc' }], 'age', false),
+    ).toEqual([{ field: 'age', direction: 'asc' }]);
+  });
+
+  it('shift-click on different column APPENDS (multi-sort)', () => {
+    expect(
+      cycleSortFor([{ field: 'name', direction: 'asc' }], 'age', true),
+    ).toEqual([
+      { field: 'name', direction: 'asc' },
+      { field: 'age', direction: 'asc' },
+    ]);
+  });
+
+  it('shift-click on existing column cycles its direction', () => {
+    expect(
+      cycleSortFor(
+        [
+          { field: 'name', direction: 'asc' },
+          { field: 'age', direction: 'asc' },
+        ],
+        'age',
+        true,
+      ),
+    ).toEqual([
+      { field: 'name', direction: 'asc' },
+      { field: 'age', direction: 'desc' },
+    ]);
+  });
+
+  it('shift-click on desc column REMOVES it (preserving rest)', () => {
+    expect(
+      cycleSortFor(
+        [
+          { field: 'name', direction: 'asc' },
+          { field: 'age', direction: 'desc' },
+        ],
+        'age',
+        true,
+      ),
+    ).toEqual([{ field: 'name', direction: 'asc' }]);
+  });
+});

package/src/components/_shared/data/useTableSort.ts

@@ -0,0 +1,141 @@
+import { useMemo } from 'react';
+import { getNestedValue } from './getNestedValue.js';
+import type {
+  TableColumn,
+  TableSortModel,
+  TableSortDirection,
+} from '../../Table/table.types.js';
+
+/**
+ * Default comparator. Handles the common primitive types in a
+ * sensible way:
+ *
+ *  - `null` / `undefined` always sort LAST (stable across asc/desc)
+ *  - `number` / `bigint`         → numeric comparison
+ *  - `string`                    → locale-aware compare via `Intl.Collator`
+ *  - `Date` / ISO-string-date    → numeric compare on epoch ms
+ *  - `boolean`                   → `false < true`
+ *  - mixed types fall back to string compare
+ *
+ * The locale collator is created once per call (cheap; cached
+ * upstream via memoization).
+ */
+function defaultCompare(a: unknown, b: unknown): number {
+  // Numbers
+  if (typeof a === 'number' && typeof b === 'number') {
+    return a - b;
+  }
+  if (typeof a === 'bigint' && typeof b === 'bigint') {
+    return a < b ? -1 : a > b ? 1 : 0;
+  }
+
+  // Dates
+  if (a instanceof Date && b instanceof Date) {
+    return a.getTime() - b.getTime();
+  }
+
+  // Booleans
+  if (typeof a === 'boolean' && typeof b === 'boolean') {
+    return a === b ? 0 : a ? 1 : -1;
+  }
+
+  // Strings (incl. ISO date strings — natural lexical ordering matches chronology)
+  if (typeof a === 'string' && typeof b === 'string') {
+    return a.localeCompare(b, undefined, { numeric: true, sensitivity: 'base' });
+  }
+
+  // Fallback: stringify and compare
+  return String(a).localeCompare(String(b), undefined, {
+    numeric: true,
+    sensitivity: 'base',
+  });
+}
+
+/**
+ * Applies the `sortModel` to `rows`. Returns a NEW sorted array
+ * (does not mutate input). Stable sort guaranteed by the underlying
+ * `Array.prototype.sort` in modern engines.
+ *
+ * Multi-column sort: items earlier in `sortModel` have higher
+ * precedence. Equal values fall through to the next sort item; if
+ * all sort items tie, the original order is preserved (stable).
+ */
+export function useTableSort<T extends object>(
+  rows: T[],
+  cols: TableColumn<T>[],
+  sortModel: TableSortModel,
+): T[] {
+  return useMemo(() => {
+    if (!sortModel || sortModel.length === 0) return rows;
+
+    const sortConfigs = sortModel
+      .map((item) => {
+        const col = cols.find((c) => (c.field as string) === item.field);
+        if (!col || !col.sortable) return null;
+        const customCompare =
+          typeof col.sortable === 'function' ? col.sortable : undefined;
+        return { item, col, customCompare };
+      })
+      .filter((x): x is NonNullable<typeof x> => x != null);
+
+    if (sortConfigs.length === 0) return rows;
+
+    // Decorate-sort-undecorate for stability across engines.
+    //
+    // Per sort item: null/undefined values always sort LAST, regardless
+    // of direction. This invariant lives outside the comparator so it's
+    // not inverted by `-cmp` when direction is `desc`. (Without this
+    // separation, `desc` flipped null-handling and placed nulls FIRST,
+    // which broke user expectations — fixed in the v1 implementation.)
+    return [...rows].sort((a, b) => {
+      for (const { item, customCompare } of sortConfigs) {
+        const aVal = customCompare ? a : getNestedValue(a, item.field);
+        const bVal = customCompare ? b : getNestedValue(b, item.field);
+
+        // Null-last (direction-independent)
+        const aNull = aVal == null;
+        const bNull = bVal == null;
+        if (aNull && bNull) continue;
+        if (aNull) return 1;
+        if (bNull) return -1;
+
+        const cmp = customCompare ? customCompare(a, b) : defaultCompare(aVal, bVal);
+        if (cmp !== 0) {
+          return item.direction === 'desc' ? -cmp : cmp;
+        }
+      }
+      return 0;
+    });
+  }, [rows, cols, sortModel]);
+}
+
+/**
+ * Three-state sort cycler: `none` → `asc` → `desc` → `none`.
+ *
+ * Used by the header click handler. Returns the next sort model
+ * to apply, given the current model + the clicked field + whether
+ * the user is multi-sorting (shift key).
+ */
+export function cycleSortFor(
+  current: TableSortModel,
+  field: string,
+  multi: boolean,
+): TableSortModel {
+  const existing = current.find((s) => s.field === field);
+  const nextDirection: TableSortDirection | null = !existing
+    ? 'asc'
+    : existing.direction === 'asc'
+      ? 'desc'
+      : null;
+
+  if (multi) {
+    // Multi-sort: keep other entries, update / add / remove this one.
+    const rest = current.filter((s) => s.field !== field);
+    if (nextDirection == null) return rest;
+    return [...rest, { field, direction: nextDirection }];
+  }
+
+  // Single-sort: replace the whole model.
+  if (nextDirection == null) return [];
+  return [{ field, direction: nextDirection }];
+}

package/src/components/_shared/data/useVirtualizer.test.ts

@@ -0,0 +1,158 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { computeWindow } from './useVirtualizer.js';
+
+describe('computeWindow', () => {
+  it('returns empty window when totalCount is 0', () => {
+    const w = computeWindow({
+      totalCount: 0,
+      rowHeight: 48,
+      viewportHeight: 600,
+      scrollTop: 0,
+    });
+    expect(w.endIndex).toBeLessThan(w.startIndex);
+    expect(w.paddingTop).toBe(0);
+    expect(w.paddingBottom).toBe(0);
+  });
+
+  it('returns first window when scrollTop=0 (with overscan)', () => {
+    const w = computeWindow({
+      totalCount: 1000,
+      rowHeight: 48,
+      viewportHeight: 600,
+      scrollTop: 0,
+      overscan: 5,
+    });
+    // viewport fits 600 / 48 = 12.5 → 13 rows + 5 overscan top + 5 overscan bottom
+    expect(w.startIndex).toBe(0);
+    // 13 visible + 5 overscan_bottom = end at 17 ish
+    expect(w.endIndex).toBeGreaterThanOrEqual(12);
+    expect(w.paddingTop).toBe(0);
+    expect(w.paddingBottom).toBeGreaterThan(0);
+  });
+
+  it('scrolls forward — start index advances with scrollTop', () => {
+    const w = computeWindow({
+      totalCount: 1000,
+      rowHeight: 48,
+      viewportHeight: 600,
+      scrollTop: 480, // 10 rows down
+      overscan: 0,
+    });
+    expect(w.startIndex).toBe(10);
+    expect(w.paddingTop).toBe(480);
+  });
+
+  it('overscan extends start index upward', () => {
+    const w = computeWindow({
+      totalCount: 1000,
+      rowHeight: 48,
+      viewportHeight: 600,
+      scrollTop: 480,
+      overscan: 5,
+    });
+    expect(w.startIndex).toBe(5);
+    expect(w.paddingTop).toBe(5 * 48);
+  });
+
+  it('overscan extends end index downward', () => {
+    const w = computeWindow({
+      totalCount: 1000,
+      rowHeight: 48,
+      viewportHeight: 600,
+      scrollTop: 0,
+      overscan: 5,
+    });
+    // raw end was ceil(600/48) = 13. with overscan: 13 + 5 = 18.
+    expect(w.endIndex).toBe(18);
+  });
+
+  it('clamps start at 0 when overscan would go negative', () => {
+    const w = computeWindow({
+      totalCount: 1000,
+      rowHeight: 48,
+      viewportHeight: 600,
+      scrollTop: 0,
+      overscan: 10,
+    });
+    expect(w.startIndex).toBe(0);
+    expect(w.paddingTop).toBe(0);
+  });
+
+  it('clamps end at totalCount-1 when overscan would exceed', () => {
+    // scroll near the end
+    const w = computeWindow({
+      totalCount: 20,
+      rowHeight: 48,
+      viewportHeight: 600,
+      scrollTop: 480, // would try to show rows 10-22
+      overscan: 5,
+    });
+    expect(w.endIndex).toBe(19); // clamped
+    expect(w.paddingBottom).toBe(0);
+  });
+
+  it('paddingTop + visible rows + paddingBottom = total scrollable height', () => {
+    const totalCount = 1000;
+    const rowHeight = 48;
+    const w = computeWindow({
+      totalCount,
+      rowHeight,
+      viewportHeight: 600,
+      scrollTop: 5000,
+      overscan: 3,
+    });
+    const visibleRowCount = w.endIndex - w.startIndex + 1;
+    const totalRendered = w.paddingTop + visibleRowCount * rowHeight + w.paddingBottom;
+    const totalExpected = totalCount * rowHeight;
+    expect(totalRendered).toBe(totalExpected);
+  });
+
+  it('handles small dataset (everything fits in viewport)', () => {
+    const w = computeWindow({
+      totalCount: 5,
+      rowHeight: 48,
+      viewportHeight: 600,
+      scrollTop: 0,
+      overscan: 5,
+    });
+    expect(w.startIndex).toBe(0);
+    expect(w.endIndex).toBe(4); // clamped to totalCount - 1
+    expect(w.paddingTop).toBe(0);
+    expect(w.paddingBottom).toBe(0);
+  });
+
+  it('returns empty window when rowHeight = 0 (defensive)', () => {
+    const w = computeWindow({
+      totalCount: 1000,
+      rowHeight: 0,
+      viewportHeight: 600,
+      scrollTop: 100,
+    });
+    expect(w.endIndex).toBeLessThan(w.startIndex);
+  });
+
+  it('returns empty window when viewportHeight = 0', () => {
+    const w = computeWindow({
+      totalCount: 1000,
+      rowHeight: 48,
+      viewportHeight: 0,
+      scrollTop: 100,
+    });
+    expect(w.endIndex).toBeLessThan(w.startIndex);
+  });
+
+  it('supports very large dataset (1 million rows)', () => {
+    const w = computeWindow({
+      totalCount: 1_000_000,
+      rowHeight: 48,
+      viewportHeight: 600,
+      scrollTop: 24_000_000, // ~middle
+      overscan: 5,
+    });
+    expect(w.startIndex).toBe(499_995);
+    expect(w.endIndex).toBeGreaterThan(w.startIndex);
+    expect(w.paddingTop).toBe(499_995 * 48);
+    expect(w.paddingBottom).toBeGreaterThan(0);
+  });
+});