@dashforge/tw 0.5.0-beta → 0.6.0-beta

package/src/components/Table/_internal/getNestedValue.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from 'vitest';
+import { getNestedValue } from './getNestedValue.js';
+
+describe('getNestedValue', () => {
+  it('returns top-level value', () => {
+    expect(getNestedValue({ a: 1 }, 'a')).toBe(1);
+  });
+
+  it('returns nested value (1 level)', () => {
+    expect(getNestedValue({ user: { name: 'Jane' } }, 'user.name')).toBe('Jane');
+  });
+
+  it('returns nested value (3 levels)', () => {
+    expect(
+      getNestedValue({ a: { b: { c: { d: 42 } } } }, 'a.b.c.d'),
+    ).toBe(42);
+  });
+
+  it('returns undefined when path is empty', () => {
+    expect(getNestedValue({ a: 1 }, '')).toBeUndefined();
+  });
+
+  it('returns undefined when intermediate segment is null', () => {
+    expect(getNestedValue({ user: null as never }, 'user.name')).toBeUndefined();
+  });
+
+  it('returns undefined when intermediate segment is undefined', () => {
+    expect(getNestedValue({} as { a?: { b?: number } }, 'a.b')).toBeUndefined();
+  });
+
+  it('returns undefined when intermediate segment is a primitive', () => {
+    expect(getNestedValue({ a: 'hello' }, 'a.b')).toBeUndefined();
+  });
+
+  it('preserves zero value (not coerced to undefined)', () => {
+    expect(getNestedValue({ a: { b: 0 } }, 'a.b')).toBe(0);
+  });
+
+  it('preserves false value', () => {
+    expect(getNestedValue({ a: { b: false } }, 'a.b')).toBe(false);
+  });
+
+  it('preserves empty string value', () => {
+    expect(getNestedValue({ a: { b: '' } }, 'a.b')).toBe('');
+  });
+
+  it('returns the full sub-object when path stops mid-tree', () => {
+    expect(getNestedValue({ a: { b: { c: 1 } } }, 'a.b')).toEqual({ c: 1 });
+  });
+});

package/src/components/Table/_internal/getNestedValue.ts

@@ -0,0 +1,32 @@
+/**
+ * Walk a dotted path through an object and return the value, or
+ * `undefined` if any segment is missing / nullish.
+ *
+ * Bug fix from the MUI-side Table (Sprint 4.1 motivation): the
+ * existing wrapper typed `field: NestedKeyOf<T>` but performed a
+ * flat `row[col.field]` lookup at runtime — nested keys silently
+ * returned `undefined`. This helper makes the runtime match the
+ * type contract.
+ *
+ * @example
+ * ```ts
+ * getNestedValue({ user: { name: 'Jane' } }, 'user.name')  // 'Jane'
+ * getNestedValue({ user: null }, 'user.name')              // undefined
+ * getNestedValue({}, 'a.b.c')                              // undefined
+ * getNestedValue({ a: { b: 0 } }, 'a.b')                   // 0 (NOT undefined)
+ * ```
+ */
+export function getNestedValue<T extends object>(
+  row: T,
+  path: string,
+): unknown {
+  if (!path) return undefined;
+  const segments = path.split('.');
+  let current: unknown = row;
+  for (const segment of segments) {
+    if (current == null) return undefined;
+    if (typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}

package/src/components/Table/_internal/themeIdentity.test.ts

@@ -0,0 +1,84 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, it, expect } from 'vitest';
+
+/**
+ * Theme-identity regression test.
+ *
+ * Enforces the Dashforge rule (memory: `feedback_dashforge_preset_is_identity`):
+ * the `@dashforge/tw-theme` default preset auto-inverts the neutral
+ * palette via a CSS-variable swap. Adding `dark:` Tailwind variants
+ * on `neutral-*` classes creates a DOUBLE inversion that breaks
+ * dark mode (both classes resolve to the dark value).
+ *
+ * This test scans Table source files for the anti-pattern and fails
+ * if any are introduced. Color palettes (`primary`, `secondary`,
+ * `success`, `warning`, `danger`, `info`) are EXEMPT — they do not
+ * auto-invert, so `dark:` variants on them are a legitimate design
+ * choice (e.g. RenderChip color rows).
+ */
+const TABLE_DIR = join(__dirname, '..');
+
+/**
+ * Match `dark:<modifier>?:bg-neutral-X` / `text-neutral-X` /
+ * `border-neutral-X` / `placeholder:text-neutral-X` / `ring-neutral-X` etc.
+ *
+ * The `(?:[a-z-]+:)*` chunk eats arbitrary intermediate variants
+ * (e.g. `dark:hover:bg-neutral-...`, `dark:placeholder:text-neutral-...`).
+ */
+const NEUTRAL_DARK_RE =
+  /dark:(?:[a-z-]+:)*(?:bg|text|border|ring|placeholder:text|focus-visible:bg|hover:bg|hover:text|focus:bg)?-?neutral-\d+/;
+
+function walkSourceFiles(dir: string): string[] {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  const out: string[] = [];
+  for (const entry of entries) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      out.push(...walkSourceFiles(full));
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    if (entry.name.endsWith('.test.ts')) continue;
+    if (entry.name.endsWith('.test.tsx')) continue;
+    if (!/\.(ts|tsx)$/.test(entry.name)) continue;
+    out.push(full);
+  }
+  return out;
+}
+
+describe('Table — theme identity rule (no `dark:` on neutral palette)', () => {
+  const files = walkSourceFiles(TABLE_DIR).filter(
+    // The test file itself contains the regex example — exclude.
+    (f) => !f.endsWith('themeIdentity.test.ts'),
+  );
+
+  it('finds at least the expected source files', () => {
+    expect(files.length).toBeGreaterThan(5);
+  });
+
+  for (const file of files) {
+    const rel = file.replace(TABLE_DIR + '/', '');
+    it(`${rel} — contains no \`dark:*-neutral-N\` classes`, () => {
+      const source = readFileSync(file, 'utf-8');
+      // Strip line comments to avoid false positives in docstrings
+      const stripped = source
+        .replace(/\/\/.*$/gm, '')
+        .replace(/\/\*[\s\S]*?\*\//g, '');
+      const match = stripped.match(NEUTRAL_DARK_RE);
+      if (match) {
+        // Surface the offending excerpt to make the failure actionable.
+        const idx = stripped.indexOf(match[0]);
+        const context = stripped.slice(Math.max(0, idx - 60), idx + match[0].length + 60);
+        throw new Error(
+          `Found \`dark:\`-on-neutral anti-pattern in ${rel}:\n  ...${context}...\n` +
+            `Rule: dashforgePreset() auto-inverts neutral palette via CSS-var swap. ` +
+            `Adding \`dark:bg-neutral-N\` (etc.) creates double inversion and breaks dark mode.\n` +
+            `Fix: drop the \`dark:\` variant — the same class works in both modes.\n` +
+            `See memory: \`feedback_dashforge_preset_is_identity\`.`,
+        );
+      }
+      expect(match).toBeNull();
+    });
+  }
+});

package/src/components/Table/_internal/useColumnAutoDetect.test.ts

@@ -0,0 +1,123 @@
+// @vitest-environment jsdom
+import { describe, it, expect } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import {
+  useColumnAutoDetect,
+  resolveAlign,
+  resolveMonospace,
+  resolveTabularNums,
+} from './useColumnAutoDetect.js';
+import type { TableColumn } from '../table.types.js';
+
+interface Row {
+  name: string;
+  age: number;
+  active: boolean;
+  joinedAt: Date;
+  isoDate: string;
+  meta: { count: number };
+  unknownField?: never;
+}
+
+const cols: TableColumn<Row>[] = [
+  { field: 'name',     header: 'Name' },
+  { field: 'age',      header: 'Age' },
+  { field: 'active',   header: 'Active' },
+  { field: 'joinedAt' as never, header: 'JoinedAt' },
+  { field: 'isoDate' as never,  header: 'ISO Date' },
+  { field: 'meta.count' as never, header: 'Count' },
+  { field: 'unknownField' as never, header: 'Unknown' },
+];
+
+const rows: Row[] = [
+  {
+    name: 'Jane', age: 30, active: true,
+    joinedAt: new Date('2024-01-15'),
+    isoDate: '2024-01-15T00:00:00Z',
+    meta: { count: 5 },
+  },
+];
+
+describe('useColumnAutoDetect', () => {
+  it('infers number / boolean / string / date / nested-number', () => {
+    const { result } = renderHook(() => useColumnAutoDetect(rows, cols));
+    expect(result.current.get('name')).toBe('string');
+    expect(result.current.get('age')).toBe('number');
+    expect(result.current.get('active')).toBe('boolean');
+    expect(result.current.get('joinedAt')).toBe('date');
+    expect(result.current.get('isoDate')).toBe('date');
+    expect(result.current.get('meta.count')).toBe('number');
+    expect(result.current.get('unknownField')).toBe('unknown');
+  });
+
+  it('returns unknown for empty rows array', () => {
+    const { result } = renderHook(() => useColumnAutoDetect([], cols));
+    for (const col of cols) {
+      expect(result.current.get(col.field as string)).toBe('unknown');
+    }
+  });
+
+  it('skips null values to find the first non-null sample', () => {
+    const colsAge: TableColumn<{ age: number | null }>[] = [{ field: 'age', header: 'Age' }];
+    const sparseRows = [{ age: null }, { age: null }, { age: 42 }];
+    const { result } = renderHook(() => useColumnAutoDetect(sparseRows, colsAge));
+    expect(result.current.get('age')).toBe('number');
+  });
+});
+
+describe('resolveAlign', () => {
+  it('explicit align wins', () => {
+    expect(resolveAlign({ align: 'center' }, 'number')).toBe('center');
+  });
+  it('number → right', () => {
+    expect(resolveAlign({}, 'number')).toBe('right');
+  });
+  it('boolean → center', () => {
+    expect(resolveAlign({}, 'boolean')).toBe('center');
+  });
+  it('string → left (default)', () => {
+    expect(resolveAlign({}, 'string')).toBe('left');
+  });
+  it('date → left', () => {
+    expect(resolveAlign({}, 'date')).toBe('left');
+  });
+  it('unknown → left', () => {
+    expect(resolveAlign({}, 'unknown')).toBe('left');
+  });
+});
+
+describe('resolveMonospace', () => {
+  // Library MUST NOT auto-pick a font family — it would override
+  // the consumer's theme font. Only explicit opt-in turns it on.
+  it('explicit monospace=true wins', () => {
+    expect(resolveMonospace({ monospace: true })).toBe(true);
+  });
+  it('explicit monospace=false → false', () => {
+    expect(resolveMonospace({ monospace: false })).toBe(false);
+  });
+  it('omitted → false (never auto-applies)', () => {
+    expect(resolveMonospace({})).toBe(false);
+  });
+});
+
+describe('resolveTabularNums', () => {
+  // tabular-nums is a font-feature-setting (digit alignment) — does
+  // NOT change the font family. Safe to auto-apply for number/date.
+  it('explicit tabularNums=true wins', () => {
+    expect(resolveTabularNums({ tabularNums: true }, 'string')).toBe(true);
+  });
+  it('explicit tabularNums=false wins (opt-out)', () => {
+    expect(resolveTabularNums({ tabularNums: false }, 'number')).toBe(false);
+  });
+  it('number → true (auto)', () => {
+    expect(resolveTabularNums({}, 'number')).toBe(true);
+  });
+  it('date → true (auto, ISO digits align)', () => {
+    expect(resolveTabularNums({}, 'date')).toBe(true);
+  });
+  it('string / boolean / unknown → false', () => {
+    expect(resolveTabularNums({}, 'string')).toBe(false);
+    expect(resolveTabularNums({}, 'boolean')).toBe(false);
+    expect(resolveTabularNums({}, 'unknown')).toBe(false);
+  });
+});

package/src/components/Table/_internal/useColumnAutoDetect.ts

@@ -0,0 +1,100 @@
+import { useMemo } from 'react';
+import { getNestedValue } from './getNestedValue.js';
+import type { TableColumn, TableColumnInferredType } from '../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/Table/_internal/useControllableState.ts

@@ -0,0 +1,48 @@
+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/Table/_internal/useDebouncedValue.ts

@@ -0,0 +1,24 @@
+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/Table/_internal/useTableFilter.ts

@@ -0,0 +1,37 @@
+import { useMemo } from 'react';
+import { getNestedValue } from './getNestedValue.js';
+import { stringifyForSearch } from './useTableSearch.js';
+import type { TableFilterModel } from '../table.types.js';
+
+/**
+ * Filters `rows` by the per-column filter model. v1 only supports
+ * the `contains` operator (text substring) — additional ops
+ * (`equals`, `in`, `gte`, `lte`, `between`, `before`, `after`)
+ * land in v1-bis once the filter UI surface for each shape is
+ * fleshed out.
+ *
+ * AND semantics across columns: a row must match EVERY active
+ * filter. Within a single filter, the op decides the predicate.
+ */
+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);
+        const stringValue = stringifyForSearch(value).toLowerCase();
+        const needle = filter.value.trim().toLowerCase();
+        if (!needle) return true; // empty filter == no-op
+        switch (filter.op) {
+          case 'contains':
+            return stringValue.includes(needle);
+          default:
+            return true;
+        }
+      }),
+    );
+  }, [rows, filterModel]);
+}

package/src/components/Table/_internal/useTableSearch.test.ts

@@ -0,0 +1,115 @@
+// @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.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/Table/_internal/useTableSearch.ts

@@ -0,0 +1,66 @@
+import { useMemo } from 'react';
+import { getNestedValue } from './getNestedValue.js';
+import type { TableColumn } from '../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]);
+}