@jmruthers/pace-core 0.6.9 → 0.6.11

package/src/components/DataTable/ui/table/FilterRow.test.tsx

@@ -0,0 +1,416 @@
+/**
+ * @file Filter Row Component Tests
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Components
+ * @since 0.4.0
+ * 
+ * Comprehensive test suite for FilterRow component following testing guidelines.
+ * Tests cover all major functionality, edge cases, and user interactions.
+ */
+
+import React from 'react';
+import { render, screen, renderHook } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createColumnHelper, useReactTable, getCoreRowModel, getFilteredRowModel } from '@tanstack/react-table';
+import { FilterRow } from './FilterRow';
+import type { DataRecord } from '../../types';
+
+// Mock ColumnFilter so tests get predictable DOM (data-testid="column-filter").
+// Path must match FilterRow's import; use same-dir path so Vite resolves the same module.
+vi.mock('../shared/ColumnFilter', () => ({
+  ColumnFilter: ({ column, filterType, options, placeholder }: any) => (
+    <div
+      data-testid="column-filter"
+      data-column-id={column.id}
+      data-filter-type={filterType}
+      data-options-count={options?.length || 0}
+      data-placeholder={placeholder}
+    >
+      Filter: {column.id}
+    </div>
+  ),
+}));
+
+interface TestData extends DataRecord {
+  id: string;
+  name: string;
+  email: string;
+  age: number;
+  status: string;
+  createdAt: Date;
+  createdDate?: Date; // For date filter test
+}
+
+describe('[component] FilterRow', () => {
+  const columnHelper = createColumnHelper<TestData>();
+  
+  const defaultColumns = [
+    columnHelper.accessor('name', {
+      header: 'Name',
+    }),
+    columnHelper.accessor('email', {
+      header: 'Email',
+    }),
+    columnHelper.accessor('age', {
+      header: 'Age',
+    }),
+    columnHelper.accessor('status', {
+      header: 'Status',
+      filterSelectOptions: [
+        { value: 'active', label: 'Active' },
+        { value: 'inactive', label: 'Inactive' },
+      ],
+    }),
+  ];
+
+  const defaultData: TestData[] = [
+    { id: '1', name: 'John', email: 'john@example.com', age: 30, status: 'active', createdAt: new Date() },
+    { id: '2', name: 'Jane', email: 'jane@example.com', age: 25, status: 'inactive', createdAt: new Date() },
+    { id: '3', name: 'Bob', email: 'bob@example.com', age: 35, status: 'active', createdAt: new Date() },
+  ];
+
+  const createTable = (columns = defaultColumns, data = defaultData) => {
+    // Use renderHook to call useReactTable hook properly
+    // Import the row model functions from TanStack Table
+    const { result } = renderHook(() => {
+      return useReactTable({
+        data,
+        columns,
+        enableFiltering: true,
+        // Use the actual row model functions from TanStack Table
+        getCoreRowModel: getCoreRowModel(),
+        getFilteredRowModel: getFilteredRowModel(),
+        // Provide minimal state to avoid errors
+        initialState: {
+          columnFilters: [],
+          sorting: [],
+          columnVisibility: {},
+          globalFilter: '',
+          pagination: { pageIndex: 0, pageSize: 10 },
+          grouping: [],
+          expanded: {},
+        },
+      });
+    });
+    return result.current;
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Rendering', () => {
+    it('renders filter row with all visible columns', () => {
+      const table = createTable();
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filterRow = screen.getByRole('row');
+      expect(filterRow).toBeInTheDocument();
+    });
+
+    it('renders ColumnFilter for each filterable column', () => {
+      const table = createTable();
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filters = screen.getAllByTestId('column-filter');
+      expect(filters.length).toBeGreaterThan(0);
+    });
+
+    it('displays non-breaking space for non-filterable columns', () => {
+      const columns = [
+        columnHelper.accessor('name', {
+          header: 'Name',
+          enableColumnFilter: false,
+        }),
+      ];
+      const table = createTable(columns);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      const { container } = render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      // Check that the cell exists and does not contain a filter component
+      const cell = container.querySelector('td');
+      expect(cell).toBeInTheDocument();
+      // The cell should not contain a ColumnFilter component
+      expect(cell?.querySelector('[data-testid="column-filter"]')).not.toBeInTheDocument();
+      // The cell should be empty or contain only whitespace (non-breaking space from React Fragment)
+      // React Fragment with &nbsp; renders as a non-breaking space, but textContent may normalize it
+      // The important thing is that no filter component is rendered
+      expect(cell?.children.length).toBe(0);
+    });
+
+    it('uses column header text in filter placeholder', () => {
+      const columns = [
+        columnHelper.accessor('name', {
+          header: 'Full Name',
+        }),
+      ];
+      const table = createTable(columns);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      expect(filter).toHaveAttribute('data-placeholder', 'Filter Full Name...');
+    });
+  });
+
+  describe('Filter Type Detection', () => {
+    it('uses explicit filterType when provided', () => {
+      const columns = [
+        columnHelper.accessor('status', {
+          header: 'Status',
+          filterType: 'text',
+        }),
+      ];
+      const table = createTable(columns);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      expect(filter).toHaveAttribute('data-filter-type', 'text');
+    });
+
+    it('auto-detects select filter when filterSelectOptions provided', () => {
+      const columns = [
+        columnHelper.accessor('status', {
+          header: 'Status',
+          filterSelectOptions: [
+            { value: 'active', label: 'Active' },
+            { value: 'inactive', label: 'Inactive' },
+          ],
+        }),
+      ];
+      const table = createTable(columns);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      expect(filter).toHaveAttribute('data-filter-type', 'select');
+    });
+
+    it('auto-detects date filter for date columns', () => {
+      // Column ID must include 'date' or 'time' for auto-detection
+      const columns = [
+        columnHelper.accessor('createdDate', {
+          header: 'Created Date',
+        }),
+      ];
+      // Use data with Date values - need to match the column accessor
+      const dateData: TestData[] = [
+        { id: '1', name: 'John', email: 'john@example.com', age: 30, status: 'active', createdAt: new Date('2024-01-01'), createdDate: new Date('2024-01-01') },
+      ];
+      const table = createTable(columns, dateData);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      // Column ID includes 'date', so it should detect as 'date'
+      expect(filter).toHaveAttribute('data-filter-type', 'date');
+    });
+
+    it('auto-detects number filter for numeric columns', () => {
+      const columns = [
+        columnHelper.accessor('age', {
+          header: 'Age',
+        }),
+      ];
+      const table = createTable(columns);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      expect(filter).toHaveAttribute('data-filter-type', 'number');
+    });
+
+    it('auto-detects select filter when unique values ≤ 10', () => {
+      const limitedData: TestData[] = Array.from({ length: 5 }, (_, i) => ({
+        id: String(i),
+        name: `User ${i}`,
+        email: `user${i}@example.com`,
+        age: 20 + i,
+        status: ['active', 'inactive', 'pending'][i % 3],
+        createdAt: new Date(),
+      }));
+      
+      const columns = [
+        columnHelper.accessor('status', {
+          header: 'Status',
+        }),
+      ];
+      const table = createTable(columns, limitedData);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      expect(filter).toHaveAttribute('data-filter-type', 'select');
+    });
+
+    it('respects explicit filterType: text even when unique values ≤ 10', () => {
+      // This test reproduces the bug: filterType: 'text' should not be overridden
+      // by auto-detection when there are ≤10 unique values
+      const limitedData: TestData[] = Array.from({ length: 7 }, (_, i) => ({
+        id: String(i),
+        name: `Brand ${i % 7}`,
+        email: `user${i}@example.com`,
+        age: 20 + i,
+        status: ['active', 'inactive', 'pending'][i % 3],
+        createdAt: new Date(),
+      }));
+      
+      const columns = [
+        columnHelper.accessor('name', {
+          header: 'Brand',
+          filterType: 'text', // Explicitly set to text
+        }),
+      ];
+      const table = createTable(columns, limitedData);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      // Should remain as 'text' filter, NOT auto-detect to 'select'
+      expect(filter).toHaveAttribute('data-filter-type', 'text');
+    });
+
+    it('defaults to text filter when no auto-detection matches', () => {
+      // Use data with many unique values (>10) to avoid auto-detection as select
+      const manyUniqueData: TestData[] = Array.from({ length: 15 }, (_, i) => ({
+        id: String(i),
+        name: `Unique Name ${i}`,
+        email: `user${i}@example.com`,
+        age: 20 + i,
+        status: 'active',
+        createdAt: new Date(),
+      }));
+      
+      const columns = [
+        columnHelper.accessor('name', {
+          header: 'Name',
+        }),
+      ];
+      const table = createTable(columns, manyUniqueData);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      // With >10 unique values, it should default to 'text' filter
+      expect(filter).toHaveAttribute('data-filter-type', 'text');
+    });
+  });
+
+  describe('Filter Options Generation', () => {
+    it('uses filterSelectOptions when provided', () => {
+      const columns = [
+        columnHelper.accessor('status', {
+          header: 'Status',
+          filterSelectOptions: [
+            { value: 'active', label: 'Active' },
+            { value: 'inactive', label: 'Inactive' },
+          ],
+        }),
+      ];
+      const table = createTable(columns);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      expect(filter).toHaveAttribute('data-options-count', '2');
+    });
+
+    it('generates options from unique values when filterSelectOptions not provided', () => {
+      const columns = [
+        columnHelper.accessor('status', {
+          header: 'Status',
+        }),
+      ];
+      const table = createTable(columns);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      // Should have generated options from unique values (active, inactive)
+      expect(filter).toHaveAttribute('data-options-count', '2');
+    });
+
+    it('handles columns with no data', () => {
+      const columns = [
+        columnHelper.accessor('name', {
+          header: 'Name',
+        }),
+      ];
+      const table = createTable(columns, []);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      expect(filter).toHaveAttribute('data-options-count', '0');
+    });
+
+    it('filters out null and undefined values when generating options', () => {
+      const dataWithNulls: TestData[] = [
+        { id: '1', name: 'John', email: 'john@example.com', age: 30, status: 'active', createdAt: new Date() },
+        { id: '2', name: 'Jane', email: 'jane@example.com', age: 25, status: null as any, createdAt: new Date() },
+        { id: '3', name: 'Bob', email: 'bob@example.com', age: 35, status: undefined as any, createdAt: new Date() },
+      ];
+      
+      const columns = [
+        columnHelper.accessor('status', {
+          header: 'Status',
+        }),
+      ];
+      const table = createTable(columns, dataWithNulls);
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filter = screen.getByTestId('column-filter');
+      expect(filter).toBeInTheDocument();
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles empty visibleColumns array', () => {
+      const table = createTable();
+      
+      render(<FilterRow table={table} visibleColumns={[]} />);
+      
+      const filterRow = screen.getByRole('row');
+      expect(filterRow).toBeInTheDocument();
+    });
+
+
+
+  });
+
+  describe('Accessibility', () => {
+    it('renders as accessible table row', () => {
+      const table = createTable();
+      const visibleColumns = table.getHeaderGroups()[0]?.headers || [];
+      
+      render(<FilterRow table={table} visibleColumns={visibleColumns} />);
+      
+      const filterRow = screen.getByRole('row');
+      expect(filterRow).toBeInTheDocument();
+    });
+  });
+});
+

package/src/components/DataTable/ui/table/FilterRow.tsx

@@ -0,0 +1,148 @@
+import React from 'react';
+import { ColumnFilter } from '../shared/ColumnFilter';
+import type { Column, Header, Table } from '@tanstack/react-table';
+import { getColumnHeaderText } from '../../utils/columnUtils';
+import type { DataRecord, DataTableColumn } from '../../types';
+
+/**
+ * Props for the FilterRow component.
+ * @template TData - The type of data records in the table
+ */
+interface FilterRowProps<TData extends DataRecord> {
+  table: Table<TData>;
+  visibleColumns: Header<TData, unknown>[];
+}
+
+/**
+ * Filter row component for DataTable.
+ * Renders filter inputs for each visible column.
+ * 
+ * @template TData - The type of data records in the table
+ * @param props - Filter row configuration
+ * @returns The rendered filter row
+ */
+export function FilterRow<TData extends DataRecord>({ table, visibleColumns }: FilterRowProps<TData>) {
+
+  // Get unique values for select filters
+  const getColumnOptions = React.useCallback((columnId: string) => {
+    const column = table.getColumn(columnId);
+    if (!column) return [];
+
+    const columnDef = column.columnDef as DataTableColumn<TData>;
+    
+    // Check for filterSelectOptions first (preferred for filters)
+    if (columnDef.filterSelectOptions && Array.isArray(columnDef.filterSelectOptions)) {
+      return columnDef.filterSelectOptions;
+    }
+    
+    // Check if column has explicit field options
+    if (columnDef.fieldOptions && Array.isArray(columnDef.fieldOptions)) {
+      return columnDef.fieldOptions;
+    }
+
+    // Fallback to generating options from data
+    const uniqueValues = new Set<string>();
+    table.getRowModel().rows.forEach((row) => {
+      const value = row.getValue(columnId);
+      if (value !== null && value !== undefined) {
+        uniqueValues.add(String(value));
+      }
+    });
+
+    return Array.from(uniqueValues)
+      .sort()
+      .map((value) => ({ value, label: value }));
+  }, [table]);
+
+  // Determine filter type based on column data
+  // IMPORTANT: Explicit filterType always takes priority - auto-detection only runs if filterType is not set
+  const getFilterType = React.useCallback((columnId: string) => {
+    const column = table.getColumn(columnId);
+    if (!column) return 'text';
+
+    const columnDef = column.columnDef as DataTableColumn<TData>;
+    
+    // PRIORITY 1: Check if column has explicit filter type configuration
+    // This MUST be checked first and must respect any explicit value, including 'text'
+    // Check for valid filter type strings explicitly to prevent any edge cases
+    // This prevents auto-detection from overriding explicit filterType settings
+    const explicitFilterType = columnDef.filterType;
+    if (
+      explicitFilterType === 'text' ||
+      explicitFilterType === 'select' ||
+      explicitFilterType === 'number' ||
+      explicitFilterType === 'date'
+    ) {
+      // Explicit filterType set - return it immediately (no auto-detection)
+      // This ensures filterType: 'text' is always respected, even for columns with ≤10 unique values
+      return explicitFilterType as 'text' | 'select' | 'number' | 'date';
+    }
+    
+    // Only proceed with auto-detection if filterType was NOT explicitly set
+    
+    // PRIORITY 2: Auto-detect select filter if filterSelectOptions is explicitly provided
+    if (columnDef.filterSelectOptions && Array.isArray(columnDef.filterSelectOptions)) {
+      return 'select';
+    }
+
+    // PRIORITY 3: Check if it's a date column (by column ID pattern)
+    if (columnId.toLowerCase().includes('date') || columnId.toLowerCase().includes('time')) {
+      return 'date';
+    }
+
+    // PRIORITY 4: Check if it's a number column (by data type)
+    const firstValue = table.getRowModel().rows[0]?.getValue(columnId);
+    if (typeof firstValue === 'number') {
+      return 'number';
+    }
+
+    // PRIORITY 5: Auto-detect select filter if limited unique values (≤10)
+    // Only runs if filterType was NOT explicitly set (checked above)
+    const uniqueValues = getColumnOptions(columnId);
+    if (uniqueValues.length <= 10 && uniqueValues.length > 1) {
+      return 'select';
+    }
+
+    // Default to text filter
+    return 'text';
+  }, [table, getColumnOptions]);
+
+  return (
+    <tr className="border-b bg-sec-50/50">
+      {visibleColumns.map((header) => {
+        const column = header.column;
+        const canFilter = column.getCanFilter();
+        const filterType = getFilterType(column.id);
+        const rawOptions = filterType === 'select' ? getColumnOptions(column.id) : [];
+        
+        // Filter and normalize options for ColumnFilter (only simple options, convert to string values)
+        const options: Array<{ value: string; label: string }> = rawOptions
+          .filter((opt): opt is { value: string | number; label: string } => 
+            'value' in opt && 'label' in opt && !('type' in opt)
+          )
+          .map(opt => ({
+            value: String(opt.value),
+            label: opt.label
+          }));
+
+        return (
+          <td
+            key={header.id}
+            className="p-1"
+          >
+            {canFilter ? (
+              <ColumnFilter
+                column={column as unknown as Column<DataRecord, unknown>}
+                filterType={filterType}
+                options={options}
+                placeholder={`Filter ${getColumnHeaderText(column as unknown as Column<DataRecord, unknown>)}...`}
+              />
+            ) : (
+              <>&nbsp;</>
+            )}
+          </td>
+        );
+      })}
+    </tr>
+  );
+}

package/src/components/DataTable/ui/table/LoadingState.test.tsx

@@ -0,0 +1,77 @@
+/**
+ * @file LoadingState Component Tests
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Components
+ * @since 0.4.0
+ * 
+ * Comprehensive test suite for LoadingState component following testing guidelines.
+ * Tests focus on user-visible behavior and accessibility, not implementation details.
+ */
+
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { describe, it, expect } from 'vitest';
+import { LoadingState } from './LoadingState';
+
+describe('[component] LoadingState', () => {
+  describe('Rendering', () => {
+    it('displays loading spinner', () => {
+      render(<LoadingState />);
+      
+      // LoadingSpinner renders as a canvas with role="status"
+      const spinner = screen.getByRole('status');
+      expect(spinner).toBeInTheDocument();
+      expect(spinner.tagName).toBe('CANVAS');
+    });
+
+    it('displays visible loading text', () => {
+      render(<LoadingState />);
+      
+      // There are two "Loading..." texts - one visible in <strong>, one sr-only
+      const visibleText = screen.getByText('Loading...', { selector: 'strong' });
+      expect(visibleText).toBeInTheDocument();
+    });
+
+    it('renders both spinner and text together', () => {
+      render(<LoadingState />);
+      
+      const spinner = screen.getByRole('status');
+      const visibleText = screen.getByText('Loading...', { selector: 'strong' });
+      
+      expect(spinner).toBeInTheDocument();
+      expect(visibleText).toBeInTheDocument();
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('provides accessible loading state announcement', () => {
+      render(<LoadingState />);
+      
+      // LoadingSpinner has role="status" which announces to screen readers
+      const spinner = screen.getByRole('status');
+      expect(spinner).toHaveAttribute('role', 'status');
+    });
+
+    it('announces loading state to screen readers', () => {
+      render(<LoadingState />);
+      
+      // Screen reader text should be present in the spinner
+      const srText = screen.getByText('Loading...', { selector: '.sr-only' });
+      expect(srText).toBeInTheDocument();
+    });
+  });
+
+  describe('Visual Presentation', () => {
+    it('centers content visually', () => {
+      render(<LoadingState />);
+      const containerElement = screen.getByRole('region', { name: 'Loading' });
+      expect(containerElement).toHaveClass('grid', 'place-items-center');
+    });
+
+    it('applies appropriate spacing', () => {
+      render(<LoadingState />);
+      const containerElement = screen.getByRole('region', { name: 'Loading' });
+      expect(containerElement).toHaveClass('p-8');
+    });
+  });
+});

package/src/components/DataTable/ui/table/LoadingState.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { LoadingSpinner } from '../../../LoadingSpinner/LoadingSpinner';
+
+/**
+ * Loading state component for DataTable.
+ * Displays a loading spinner and message while data is being fetched.
+ * 
+ * @returns The rendered loading state UI
+ */
+export function LoadingState() {
+  return (
+    <section aria-label="Loading" className="grid place-items-center text-center p-8">
+        <LoadingSpinner />
+        <strong>Loading...</strong>
+    </section>
+  );
+}