@dashforge/tw 1.1.0 → 1.2.0

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

@@ -1,100 +0,0 @@
-import { useMemo } from 'react';
-import { getNestedValue } from './getNestedValue.js';
-import type { TableColumn, TableColumnInferredType } from '../../Table/table.types.js';
-
-/**
- * Auto-detects the primitive type of each column by scanning the
- * first non-null value across the supplied rows. Drives smart
- * defaults for `align` and `monospace` on the cell render path.
- *
- * Scans only the first N rows (default 50) for performance — if the
- * dataset's first 50 rows are unrepresentative, the consumer can
- * override per-column via explicit `align` / `monospace` props.
- *
- * Returns `Map<columnField, inferredType>`.
- */
-export function useColumnAutoDetect<T extends object>(
-  rows: T[],
-  cols: TableColumn<T>[],
-  sampleSize = 50,
-): Map<string, TableColumnInferredType> {
-  return useMemo(() => {
-    const result = new Map<string, TableColumnInferredType>();
-    const sample = rows.slice(0, sampleSize);
-    for (const col of cols) {
-      const field = col.field as string;
-      let inferred: TableColumnInferredType = 'unknown';
-      for (const row of sample) {
-        const value = getNestedValue(row, field);
-        if (value == null) continue;
-        inferred = inferType(value);
-        break; // first non-null wins
-      }
-      result.set(field, inferred);
-    }
-    return result;
-  }, [rows, cols, sampleSize]);
-}
-
-function inferType(value: unknown): TableColumnInferredType {
-  if (typeof value === 'number') return 'number';
-  if (typeof value === 'boolean') return 'boolean';
-  if (value instanceof Date) return 'date';
-  if (typeof value === 'string') {
-    // Heuristic: ISO date string (YYYY-MM-DD[T...]) → 'date'
-    if (/^\d{4}-\d{2}-\d{2}/.test(value)) return 'date';
-    return 'string';
-  }
-  return 'unknown';
-}
-
-/**
- * Resolves the effective `align` for a column, honoring explicit
- * `col.align` first and falling back to the inferred type.
- */
-export function resolveAlign(
-  col: { align?: 'left' | 'right' | 'center' },
-  inferred: TableColumnInferredType | undefined,
-): 'left' | 'right' | 'center' {
-  if (col.align) return col.align;
-  switch (inferred) {
-    case 'number':
-      return 'right';
-    case 'boolean':
-      return 'center';
-    default:
-      return 'left';
-  }
-}
-
-/**
- * Resolves the effective `tabularNums` flag for a column.
- *
- * `tabular-nums` is a `font-variant-numeric` rule that makes every
- * digit occupy the same width — it does NOT change the font family.
- * Auto-applied for `number` and `date` columns so currency values
- * and ISO dates align cleanly. Explicit `col.tabularNums` wins.
- */
-export function resolveTabularNums(
-  col: { tabularNums?: boolean },
-  inferred: TableColumnInferredType | undefined,
-): boolean {
-  if (col.tabularNums !== undefined) return col.tabularNums;
-  return inferred === 'number' || inferred === 'date';
-}
-
-/**
- * Resolves the effective `monospace` flag for a column.
- *
- * `font-mono` changes the font FAMILY to a monospace stack, which
- * would override the consumer's theme `font-sans`. The library
- * never auto-applies it — only an explicit `col.monospace: true`
- * opts in. Consumers wanting a custom mono stack configure it
- * through Tailwind's `theme.extend.fontFamily.mono` in their own
- * preset (the dashforgePreset does not own the `fontFamily` axis).
- */
-export function resolveMonospace(
-  col: { monospace?: boolean },
-): boolean {
-  return col.monospace === true;
-}

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

@@ -1,48 +0,0 @@
-import { useCallback, useRef, useState } from 'react';
-
-/**
- * Generic "controllable" state hook — switches between controlled
- * (via parent-supplied value + setter) and uncontrolled (internal
- * `useState`).
- *
- * - If `controlledValue !== undefined`, the hook is in **controlled**
- *   mode: the internal state is ignored; the returned setter calls
- *   `onControlledChange` only.
- * - Otherwise it's in **uncontrolled** mode: internal `useState`,
- *   defaulting to `defaultValue`. The optional `onControlledChange`
- *   is still fired on every change so the parent can react.
- *
- * The control mode is determined per-render. Mixing modes (passing
- * `controlledValue` undefined sometimes) is a consumer bug — we don't
- * try to "remember" the last mode (React's rules-of-hooks make that
- * unsafe).
- */
-export function useControllableState<T>(args: {
-  controlledValue: T | undefined;
-  defaultValue: T;
-  onChange?: (value: T) => void;
-}): [T, (next: T | ((prev: T) => T)) => void] {
-  const { controlledValue, defaultValue, onChange } = args;
-  const [uncontrolledValue, setUncontrolledValue] = useState<T>(defaultValue);
-  const isControlled = controlledValue !== undefined;
-  const value = isControlled ? (controlledValue as T) : uncontrolledValue;
-
-  // Stable ref to `onChange` so the setter doesn't change identity
-  // every render (consumer can pass an inline lambda safely).
-  const onChangeRef = useRef(onChange);
-  onChangeRef.current = onChange;
-
-  const setValue = useCallback(
-    (next: T | ((prev: T) => T)) => {
-      const resolved =
-        typeof next === 'function' ? (next as (prev: T) => T)(value) : next;
-      if (!isControlled) {
-        setUncontrolledValue(resolved);
-      }
-      onChangeRef.current?.(resolved);
-    },
-    [isControlled, value],
-  );
-
-  return [value, setValue];
-}

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

@@ -1,24 +0,0 @@
-import { useEffect, useState } from 'react';
-
-/**
- * Returns a debounced version of `value` — only updates after `delayMs`
- * of no further changes. Used by the search input so we don't re-filter
- * the entire row set on every keystroke.
- *
- * `delayMs <= 0` short-circuits to the input value (no debounce —
- * useful for tests).
- */
-export function useDebouncedValue<T>(value: T, delayMs: number): T {
-  const [debounced, setDebounced] = useState<T>(value);
-
-  useEffect(() => {
-    if (delayMs <= 0) {
-      setDebounced(value);
-      return;
-    }
-    const timer = setTimeout(() => setDebounced(value), delayMs);
-    return () => clearTimeout(timer);
-  }, [value, delayMs]);
-
-  return debounced;
-}

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

@@ -1,166 +0,0 @@
-// @vitest-environment node
-import { describe, it, expect } from 'vitest';
-import { passesFilter, toNumber, toDateMs } from './useTableFilter.js';
-
-describe('useTableFilter — toNumber', () => {
-  it('returns null for null and undefined', () => {
-    expect(toNumber(null)).toBeNull();
-    expect(toNumber(undefined)).toBeNull();
-  });
-
-  it('returns the value for finite numbers', () => {
-    expect(toNumber(42)).toBe(42);
-    expect(toNumber(0)).toBe(0);
-    expect(toNumber(-3.14)).toBe(-3.14);
-  });
-
-  it('returns null for non-finite numbers', () => {
-    expect(toNumber(Number.NaN)).toBeNull();
-    expect(toNumber(Number.POSITIVE_INFINITY)).toBeNull();
-  });
-
-  it('coerces numeric strings', () => {
-    expect(toNumber('42')).toBe(42);
-    expect(toNumber('0.5')).toBe(0.5);
-  });
-
-  it('returns null for non-numeric strings', () => {
-    expect(toNumber('abc')).toBeNull();
-  });
-
-  // JS quirk: Number('') === 0 (finite). Empty-string is treated as 0
-  // by toNumber. Callers that need open-range semantics (e.g. the
-  // NumberRangeFilter UI) explicitly null-out empty inputs before
-  // passing them through.
-  it('returns 0 for empty string (JS Number("") === 0)', () => {
-    expect(toNumber('')).toBe(0);
-  });
-
-  it('coerces bigint to number', () => {
-    expect(toNumber(10n)).toBe(10);
-  });
-
-  it('returns null for objects/arrays/booleans', () => {
-    expect(toNumber({})).toBeNull();
-    expect(toNumber([])).toBeNull();
-    expect(toNumber(true)).toBeNull();
-  });
-});
-
-describe('useTableFilter — toDateMs', () => {
-  it('returns null for null and undefined', () => {
-    expect(toDateMs(null)).toBeNull();
-    expect(toDateMs(undefined)).toBeNull();
-  });
-
-  it('returns epoch ms for Date instances', () => {
-    const d = new Date('2026-05-19T00:00:00Z');
-    expect(toDateMs(d)).toBe(d.getTime());
-  });
-
-  it('parses ISO strings', () => {
-    const ms = toDateMs('2026-05-19');
-    expect(ms).not.toBeNull();
-    expect(new Date(ms!).toISOString()).toContain('2026-05-19');
-  });
-
-  it('returns null for invalid date strings', () => {
-    expect(toDateMs('not-a-date')).toBeNull();
-  });
-});
-
-describe('useTableFilter — passesFilter (contains)', () => {
-  it('returns true for empty needle (no-op filter)', () => {
-    expect(passesFilter('Hello', 'contains', '')).toBe(true);
-    expect(passesFilter('Hello', 'contains', '   ')).toBe(true);
-  });
-
-  it('matches substring case-insensitively', () => {
-    expect(passesFilter('Hello World', 'contains', 'hello')).toBe(true);
-    expect(passesFilter('Hello World', 'contains', 'WORLD')).toBe(true);
-    expect(passesFilter('Hello World', 'contains', 'xyz')).toBe(false);
-  });
-
-  it('stringifies non-string row values for searching', () => {
-    expect(passesFilter(42, 'contains', '42')).toBe(true);
-    expect(passesFilter(true, 'contains', 'true')).toBe(true);
-  });
-});
-
-describe('useTableFilter — passesFilter (equals)', () => {
-  it('returns true when filter value is null (no-op)', () => {
-    expect(passesFilter('anything', 'equals', null)).toBe(true);
-  });
-
-  it('does strict equality for booleans', () => {
-    expect(passesFilter(true, 'equals', true)).toBe(true);
-    expect(passesFilter(false, 'equals', false)).toBe(true);
-    expect(passesFilter(true, 'equals', false)).toBe(false);
-  });
-
-  it('does strict equality for primitives', () => {
-    expect(passesFilter('a', 'equals', 'a')).toBe(true);
-    expect(passesFilter('a', 'equals', 'b')).toBe(false);
-    expect(passesFilter(1, 'equals', 1)).toBe(true);
-  });
-});
-
-describe('useTableFilter — passesFilter (between, number range)', () => {
-  it('returns true when range is fully open', () => {
-    expect(passesFilter(42, 'between', [null, null])).toBe(true);
-  });
-
-  it('respects min bound', () => {
-    expect(passesFilter(5, 'between', [10, null])).toBe(false);
-    expect(passesFilter(10, 'between', [10, null])).toBe(true);
-    expect(passesFilter(15, 'between', [10, null])).toBe(true);
-  });
-
-  it('respects max bound', () => {
-    expect(passesFilter(5, 'between', [null, 10])).toBe(true);
-    expect(passesFilter(10, 'between', [null, 10])).toBe(true);
-    expect(passesFilter(15, 'between', [null, 10])).toBe(false);
-  });
-
-  it('respects both bounds inclusively', () => {
-    expect(passesFilter(7, 'between', [5, 10])).toBe(true);
-    expect(passesFilter(5, 'between', [5, 10])).toBe(true);
-    expect(passesFilter(10, 'between', [5, 10])).toBe(true);
-    expect(passesFilter(4, 'between', [5, 10])).toBe(false);
-    expect(passesFilter(11, 'between', [5, 10])).toBe(false);
-  });
-
-  it('coerces string row values to number', () => {
-    expect(passesFilter('7', 'between', [5, 10])).toBe(true);
-  });
-
-  it('returns true for malformed filter value (defensive)', () => {
-    expect(passesFilter(42, 'between', 'not a tuple')).toBe(true);
-    expect(passesFilter(42, 'between', [1])).toBe(true);
-  });
-});
-
-describe('useTableFilter — passesFilter (between, date range)', () => {
-  it('respects ISO date range bounds', () => {
-    const row = '2026-05-19';
-    expect(passesFilter(row, 'between', ['2026-01-01', '2026-12-31'])).toBe(true);
-    expect(passesFilter(row, 'between', ['2026-06-01', '2026-12-31'])).toBe(false);
-    expect(passesFilter(row, 'between', ['2026-01-01', '2026-05-01'])).toBe(false);
-  });
-
-  it('accepts Date instances as row values', () => {
-    const row = new Date('2026-05-19T00:00:00Z');
-    expect(passesFilter(row, 'between', ['2026-01-01', '2026-12-31'])).toBe(true);
-  });
-
-  it('treats null bounds as open ended', () => {
-    expect(passesFilter('2026-05-19', 'between', [null, '2026-12-31'])).toBe(true);
-    expect(passesFilter('2026-05-19', 'between', ['2026-01-01', null])).toBe(true);
-  });
-});
-
-describe('useTableFilter — passesFilter (unknown operator)', () => {
-  it('returns true for unrecognized operator (defensive no-op)', () => {
-    expect(passesFilter('anything', 'unknownOp', 'anything')).toBe(true);
-  });
-});

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

@@ -1,118 +0,0 @@
-import { useMemo } from 'react';
-import { getNestedValue } from './getNestedValue.js';
-import { stringifyForSearch } from './useTableSearch.js';
-import type { TableFilterModel } from '../../Table/table.types.js';
-
-/**
- * Coerce a value to a number for range comparison. Returns
- * `null` if not coercible.
- */
-function toNumber(value: unknown): number | null {
-  if (value == null) return null;
-  if (typeof value === 'number') return Number.isFinite(value) ? value : null;
-  if (typeof value === 'bigint') return Number(value);
-  if (typeof value === 'string') {
-    const n = Number(value);
-    return Number.isFinite(n) ? n : null;
-  }
-  return null;
-}
-
-/**
- * Coerce a value to a Date's epoch ms for date-range comparison.
- * Accepts `Date` instances + ISO 8601 strings. Returns `null` if
- * not coercible.
- */
-function toDateMs(value: unknown): number | null {
-  if (value == null) return null;
-  if (value instanceof Date) return value.getTime();
-  if (typeof value === 'string') {
-    const d = new Date(value);
-    const t = d.getTime();
-    return Number.isNaN(t) ? null : t;
-  }
-  return null;
-}
-
-/**
- * Test one row × one filter. Returns `true` if the row passes the
- * filter. The operator decides the predicate:
- *
- *  - `contains` → substring match on stringified value (text filter)
- *  - `equals` → strict equality (boolean filter mostly)
- *  - `between` → `value: [min, max]` tuple. Each end can be `null`
- *    for an open range. Used by number range + date range filters.
- *
- * Empty filter is a no-op (passes every row).
- */
-function passesFilter(rowValue: unknown, op: string, filterValue: unknown): boolean {
-  switch (op) {
-    case 'contains': {
-      const needle =
-        typeof filterValue === 'string' ? filterValue.trim().toLowerCase() : '';
-      if (!needle) return true;
-      return stringifyForSearch(rowValue).toLowerCase().includes(needle);
-    }
-    case 'equals': {
-      if (filterValue == null) return true;
-      return rowValue === filterValue;
-    }
-    case 'between': {
-      if (!Array.isArray(filterValue) || filterValue.length !== 2) return true;
-      const [min, max] = filterValue as [unknown, unknown];
-      if (min == null && max == null) return true;
-
-      // Try number range first.
-      const rowNum = toNumber(rowValue);
-      const minNum = min == null ? null : toNumber(min);
-      const maxNum = max == null ? null : toNumber(max);
-      if (rowNum != null && (minNum != null || maxNum != null)) {
-        if (minNum != null && rowNum < minNum) return false;
-        if (maxNum != null && rowNum > maxNum) return false;
-        return true;
-      }
-
-      // Fall through to date range.
-      const rowMs = toDateMs(rowValue);
-      const minMs = min == null ? null : toDateMs(min);
-      const maxMs = max == null ? null : toDateMs(max);
-      if (rowMs != null && (minMs != null || maxMs != null)) {
-        if (minMs != null && rowMs < minMs) return false;
-        if (maxMs != null && rowMs > maxMs) return false;
-        return true;
-      }
-
-      // If neither coercion worked, let the row pass (defensive).
-      return true;
-    }
-    default:
-      return true;
-  }
-}
-
-/**
- * Filters `rows` by the per-column filter model. AND semantics
- * across columns — a row must pass EVERY active filter.
- *
- * Each filter item specifies an `op` (`'contains'` / `'equals'` /
- * `'between'`) and a `value` whose shape matches the operator
- * (string for contains; primitive for equals; `[min, max]` tuple
- * for between).
- */
-export function useTableFilter<T extends object>(
-  rows: T[],
-  filterModel: TableFilterModel,
-): T[] {
-  return useMemo(() => {
-    if (!filterModel || filterModel.length === 0) return rows;
-    return rows.filter((row) =>
-      filterModel.every((filter) => {
-        const value = getNestedValue(row, filter.field);
-        return passesFilter(value, filter.op, filter.value);
-      }),
-    );
-  }, [rows, filterModel]);
-}
-
-// Exposed for testing.
-export { passesFilter, toNumber, toDateMs };

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

@@ -1,115 +0,0 @@
-// @vitest-environment jsdom
-import { describe, it, expect } from 'vitest';
-import { renderHook } from '@testing-library/react';
-import { useTableSearch, stringifyForSearch } from './useTableSearch.js';
-import type { TableColumn } from '../../Table/table.types.js';
-
-interface User {
-  name: string;
-  email: string;
-  age: number;
-  active: boolean;
-  joinedAt: Date;
-  meta: { city: string };
-}
-
-const cols: TableColumn<User>[] = [
-  { field: 'name',  header: 'Name',  searchable: true },
-  { field: 'email', header: 'Email', searchable: true },
-  { field: 'age',   header: 'Age',   searchable: true },
-  { field: 'active', header: 'Active', searchable: true },
-  { field: 'joinedAt' as never, header: 'Joined', searchable: true },
-  { field: 'meta.city' as never, header: 'City', searchable: true },
-];
-
-const rows: User[] = [
-  {
-    name: 'Jane', email: 'jane@example.com', age: 30, active: true,
-    joinedAt: new Date('2024-01-15'), meta: { city: 'Roma' },
-  },
-  {
-    name: 'Bob',  email: 'bob@example.org',  age: 45, active: false,
-    joinedAt: new Date('2023-06-20'), meta: { city: 'Milano' },
-  },
-];
-
-describe('stringifyForSearch', () => {
-  it('handles null/undefined', () => {
-    expect(stringifyForSearch(null)).toBe('');
-    expect(stringifyForSearch(undefined)).toBe('');
-  });
-  it('returns strings as-is', () => {
-    expect(stringifyForSearch('hello')).toBe('hello');
-  });
-  it('stringifies numbers', () => {
-    expect(stringifyForSearch(42)).toBe('42');
-  });
-  it('stringifies booleans', () => {
-    expect(stringifyForSearch(true)).toBe('true');
-    expect(stringifyForSearch(false)).toBe('false');
-  });
-  it('stringifies Date as ISO', () => {
-    expect(stringifyForSearch(new Date('2024-01-15T00:00:00.000Z'))).toBe(
-      '2024-01-15T00:00:00.000Z',
-    );
-  });
-  it('stringifies objects via JSON.stringify', () => {
-    expect(stringifyForSearch({ a: 1 })).toBe('{"a":1}');
-  });
-  it('stringifies arrays via join-space of stringified elements', () => {
-    expect(stringifyForSearch(['a', 'b', 1])).toBe('a b 1');
-  });
-});
-
-describe('useTableSearch', () => {
-  it('returns all rows when query is empty', () => {
-    const { result } = renderHook(() => useTableSearch(rows, cols, ''));
-    expect(result.current).toHaveLength(2);
-  });
-
-  it('returns all rows when query is only whitespace', () => {
-    const { result } = renderHook(() => useTableSearch(rows, cols, '   '));
-    expect(result.current).toHaveLength(2);
-  });
-
-  it('filters by string match (case-insensitive)', () => {
-    const { result } = renderHook(() => useTableSearch(rows, cols, 'jane'));
-    expect(result.current).toHaveLength(1);
-    expect(result.current[0]!.name).toBe('Jane');
-  });
-
-  it('filters by number coerced to string', () => {
-    const { result } = renderHook(() => useTableSearch(rows, cols, '45'));
-    expect(result.current).toHaveLength(1);
-    expect(result.current[0]!.age).toBe(45);
-  });
-
-  it('filters by boolean', () => {
-    const { result } = renderHook(() => useTableSearch(rows, cols, 'false'));
-    expect(result.current).toHaveLength(1);
-    expect(result.current[0]!.active).toBe(false);
-  });
-
-  it('filters by Date (ISO substring)', () => {
-    const { result } = renderHook(() => useTableSearch(rows, cols, '2024-01'));
-    expect(result.current).toHaveLength(1);
-    expect(result.current[0]!.name).toBe('Jane');
-  });
-
-  it('filters by NESTED key', () => {
-    const { result } = renderHook(() => useTableSearch(rows, cols, 'roma'));
-    expect(result.current).toHaveLength(1);
-    expect(result.current[0]!.name).toBe('Jane');
-  });
-
-  it('returns empty when nothing matches', () => {
-    const { result } = renderHook(() => useTableSearch(rows, cols, 'xxxxxxx'));
-    expect(result.current).toHaveLength(0);
-  });
-
-  it('returns all rows if no column is searchable', () => {
-    const noneSearchable: TableColumn<User>[] = cols.map((c) => ({ ...c, searchable: false }));
-    const { result } = renderHook(() => useTableSearch(rows, noneSearchable, 'jane'));
-    expect(result.current).toHaveLength(2);
-  });
-});

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

@@ -1,66 +0,0 @@
-import { useMemo } from 'react';
-import { getNestedValue } from './getNestedValue.js';
-import type { TableColumn } from '../../Table/table.types.js';
-
-/**
- * Stringify any value into a search-comparable form. Handles all
- * the edge cases that bit the MUI-side Table:
- *
- *   - `null` / `undefined`      → `''`
- *   - `string`                  → as-is
- *   - `number` / `bigint`       → `String(value)`
- *   - `boolean`                 → `'true'` / `'false'`
- *   - `Date`                    → ISO 8601
- *   - `Array` / object          → `JSON.stringify` (best effort)
- */
-export function stringifyForSearch(value: unknown): string {
-  if (value == null) return '';
-  if (typeof value === 'string') return value;
-  if (typeof value === 'number' || typeof value === 'bigint') return String(value);
-  if (typeof value === 'boolean') return value ? 'true' : 'false';
-  if (value instanceof Date) return value.toISOString();
-  if (Array.isArray(value)) {
-    try {
-      return value.map(stringifyForSearch).join(' ');
-    } catch {
-      return '';
-    }
-  }
-  if (typeof value === 'object') {
-    try {
-      return JSON.stringify(value);
-    } catch {
-      return '';
-    }
-  }
-  return String(value);
-}
-
-/**
- * Filters `rows` by `query` against the columns flagged
- * `searchable: true`. Empty / whitespace-only query is a no-op
- * (returns the original rows).
- *
- * Case-insensitive substring match. The caller is responsible for
- * debouncing the input (use `useDebouncedValue`).
- */
-export function useTableSearch<T extends object>(
-  rows: T[],
-  cols: TableColumn<T>[],
-  query: string,
-): T[] {
-  return useMemo(() => {
-    const trimmed = query.trim();
-    if (!trimmed) return rows;
-    const needle = trimmed.toLowerCase();
-    const searchableCols = cols.filter((c) => c.searchable);
-    if (searchableCols.length === 0) return rows;
-    return rows.filter((row) =>
-      searchableCols.some((col) =>
-        stringifyForSearch(getNestedValue(row, col.field as string))
-          .toLowerCase()
-          .includes(needle),
-      ),
-    );
-  }, [rows, cols, query]);
-}