@dashforge/tw 1.1.0 → 1.2.0

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

@@ -1,100 +0,0 @@
-// @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

@@ -1,100 +0,0 @@
-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

@@ -1,150 +0,0 @@
-// @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

@@ -1,141 +0,0 @@
-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

@@ -1,158 +0,0 @@
-// @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);
-  });
-});