@jmruthers/pace-core 0.6.10 → 0.6.11

package/src/components/DataTable/utils/importDateParser.test.ts

@@ -0,0 +1,162 @@
+/**
+ * @file Import Date Parser Tests
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils
+ */
+
+import { describe, it, expect } from 'vitest';
+import { parseImportDate } from './importDateParser';
+
+const TEST_TIMEOUT = 10000;
+
+describe('[unit] parseImportDate', () => {
+  it('returns null for null or undefined', () => {
+    expect(parseImportDate(null as unknown as string)).toBeNull();
+    expect(parseImportDate(undefined as unknown as string)).toBeNull();
+  }, TEST_TIMEOUT);
+
+  it('returns null for non-string input', () => {
+    expect(parseImportDate(123 as unknown as string)).toBeNull();
+    expect(parseImportDate({} as unknown as string)).toBeNull();
+  }, TEST_TIMEOUT);
+
+  it('returns null for empty string or whitespace-only', () => {
+    expect(parseImportDate('')).toBeNull();
+    expect(parseImportDate('   ')).toBeNull();
+    expect(parseImportDate('\t\n')).toBeNull();
+  }, TEST_TIMEOUT);
+
+  it('parses ISO date (YYYY-MM-DD)', () => {
+    const result = parseImportDate('2020-01-02');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2020);
+    expect(result!.getMonth()).toBe(0);
+    expect(result!.getDate()).toBe(2);
+  }, TEST_TIMEOUT);
+
+  it('parses ISO date with time', () => {
+    const result = parseImportDate('2020-01-02T12:30:45');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2020);
+    expect(result!.getMonth()).toBe(0);
+    expect(result!.getDate()).toBe(2);
+    expect(result!.getHours()).toBe(12);
+    expect(result!.getMinutes()).toBe(30);
+    expect(result!.getSeconds()).toBe(45);
+  }, TEST_TIMEOUT);
+
+  it('parses ISO date with time and milliseconds', () => {
+    const result = parseImportDate('2020-01-02T12:30:45.123Z');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2020);
+    expect(result!.getMonth()).toBe(0);
+    expect(result!.getDate()).toBe(2);
+  }, TEST_TIMEOUT);
+
+  it('parses US format MM/DD/YYYY', () => {
+    const result = parseImportDate('01/15/2020');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2020);
+    expect(result!.getMonth()).toBe(0);
+    expect(result!.getDate()).toBe(15);
+  }, TEST_TIMEOUT);
+
+  it('parses US short year (YY) as 20xx when YY < 50', () => {
+    const result = parseImportDate('01/15/25');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2025);
+  }, TEST_TIMEOUT);
+
+  it('parses US short year (YY) as 19xx when YY >= 50', () => {
+    const result = parseImportDate('01/15/95');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(1995);
+  }, TEST_TIMEOUT);
+
+  it('parses US dash format MM-DD-YYYY', () => {
+    const result = parseImportDate('03-20-2021');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2021);
+    expect(result!.getMonth()).toBe(2);
+    expect(result!.getDate()).toBe(20);
+  }, TEST_TIMEOUT);
+
+  it('parses EU format DD/MM/YYYY via dot format (unambiguous)', () => {
+    const result = parseImportDate('25.12.2020');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2020);
+    expect(result!.getMonth()).toBe(11);
+    expect(result!.getDate()).toBe(25);
+  }, TEST_TIMEOUT);
+
+  it('parses dash-separated date (MM-DD-YYYY or DD-MM-YYYY by pattern order)', () => {
+    const result = parseImportDate('15-06-2021');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getTime()).not.toBeNaN();
+  }, TEST_TIMEOUT);
+
+  it('parses EU dot format DD.MM.YYYY', () => {
+    const result = parseImportDate('25.12.2022');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2022);
+    expect(result!.getMonth()).toBe(11);
+    expect(result!.getDate()).toBe(25);
+  }, TEST_TIMEOUT);
+
+  it('parses natural date DD MMM YYYY', () => {
+    const result = parseImportDate('15 Jan 2020');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2020);
+    expect(result!.getMonth()).toBe(0);
+    expect(result!.getDate()).toBe(15);
+  }, TEST_TIMEOUT);
+
+  it('parses natural date MMM DD, YYYY', () => {
+    const result = parseImportDate('Jan 15, 2020');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2020);
+    expect(result!.getMonth()).toBe(0);
+    expect(result!.getDate()).toBe(15);
+  }, TEST_TIMEOUT);
+
+  it('parses natural date DD MMMM YYYY', () => {
+    const result = parseImportDate('15 January 2020');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2020);
+    expect(result!.getMonth()).toBe(0);
+    expect(result!.getDate()).toBe(15);
+  }, TEST_TIMEOUT);
+
+  it('parses natural date MMMM DD, YYYY', () => {
+    const result = parseImportDate('January 15, 2020');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2020);
+    expect(result!.getMonth()).toBe(0);
+    expect(result!.getDate()).toBe(15);
+  }, TEST_TIMEOUT);
+
+  it('trims whitespace before parsing', () => {
+    const result = parseImportDate('  2020-01-02  ');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2020);
+    expect(result!.getDate()).toBe(2);
+  }, TEST_TIMEOUT);
+
+  it('returns null for invalid date string that matches no pattern', () => {
+    expect(parseImportDate('not-a-date')).toBeNull();
+  }, TEST_TIMEOUT);
+
+  it('falls back to native Date for parseable strings', () => {
+    const result = parseImportDate('December 17, 1995 03:24:00');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(1995);
+    expect(result!.getMonth()).toBe(11);
+    expect(result!.getDate()).toBe(17);
+  }, TEST_TIMEOUT);
+
+  it('accepts optional fieldName parameter without affecting result', () => {
+    const result = parseImportDate('2020-01-02', 'someField');
+    expect(result).toBeInstanceOf(Date);
+    expect(result!.getFullYear()).toBe(2020);
+  }, TEST_TIMEOUT);
+});

package/src/components/DataTable/utils/importDateParser.ts

@@ -0,0 +1,114 @@
+/**
+ * @file Import Date Parser
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils
+ * @since 0.3.0
+ *
+ * Date parsing for flexible CSV import. Extracted from flexibleImport for max-lines-per-function.
+ */
+
+/**
+ * Parses a date string using common patterns and month names; falls back to native Date.
+ *
+ * @param dateStr - Raw date string from CSV
+ * @param _fieldName - Optional field name (reserved for format hints)
+ * @returns Parsed Date or null
+ */
+export function parseImportDate(dateStr: string, _fieldName?: string): Date | null {
+  if (!dateStr || typeof dateStr !== 'string') return null;
+
+  const trimmedDate = dateStr.trim();
+  if (!trimmedDate) return null;
+
+  const patterns = [
+    { pattern: /^(\d{4})-(\d{1,2})-(\d{1,2})T(\d{1,2}):(\d{1,2}):(\d{1,2})/, type: 'iso-time' as const },
+    { pattern: /^(\d{4})-(\d{1,2})-(\d{1,2})T(\d{1,2}):(\d{1,2}):(\d{1,2})\.(\d{3})Z?$/, type: 'iso-time-ms' as const },
+    { pattern: /^(\d{4})-(\d{1,2})-(\d{1,2})$/, type: 'iso' as const },
+    { pattern: /^(\d{1,2})\/(\d{1,2})\/(\d{4})$/, type: 'us-4' as const },
+    { pattern: /^(\d{1,2})\/(\d{1,2})\/(\d{2})$/, type: 'us-2' as const },
+    { pattern: /^(\d{1,2})-(\d{1,2})-(\d{4})$/, type: 'us-dash-4' as const },
+    { pattern: /^(\d{1,2})\/(\d{1,2})\/(\d{4})$/, type: 'eu-4' as const },
+    { pattern: /^(\d{1,2})\/(\d{1,2})\/(\d{2})$/, type: 'eu-2' as const },
+    { pattern: /^(\d{1,2})-(\d{1,2})-(\d{4})$/, type: 'eu-dash-4' as const },
+    { pattern: /^(\d{1,2})\.(\d{1,2})\.(\d{4})$/, type: 'eu-dot-4' as const },
+    { pattern: /^(\d{1,2})\s+(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+(\d{4})$/i, type: 'natural-dd-mmm-yyyy' as const },
+    { pattern: /^(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+(\d{1,2}),?\s+(\d{4})$/i, type: 'natural-mmm-dd-yyyy' as const },
+    { pattern: /^(\d{1,2})\s+(January|February|March|April|May|June|July|August|September|October|November|December)\s+(\d{4})$/i, type: 'natural-dd-mmmm-yyyy' as const },
+    { pattern: /^(January|February|March|April|May|June|July|August|September|October|November|December)\s+(\d{1,2}),?\s+(\d{4})$/i, type: 'natural-mmmm-dd-yyyy' as const },
+  ];
+
+  const monthNames: Record<string, number> = {
+    jan: 1, feb: 2, mar: 3, apr: 4, may: 5, jun: 6,
+    jul: 7, aug: 8, sep: 9, oct: 10, nov: 11, dec: 12,
+    january: 1, february: 2, march: 3, april: 4, june: 6,
+    july: 7, august: 8, september: 9, october: 10, november: 11, december: 12,
+  };
+
+  for (const { pattern, type } of patterns) {
+    const match = trimmedDate.match(pattern);
+    if (match) {
+      try {
+        let year: number; let month: number; let day: number;
+        let hour = 0; let minute = 0; let second = 0;
+
+        switch (type) {
+          case 'iso-time':
+            [, year, month, day, hour, minute, second] = match.map(Number);
+            break;
+          case 'iso-time-ms':
+            [, year, month, day, hour, minute, second] = match.map(Number);
+            break;
+          case 'iso':
+            [, year, month, day] = match.map(Number);
+            break;
+          case 'us-4':
+          case 'us-dash-4':
+            [, month, day, year] = match.map(Number);
+            break;
+          case 'us-2':
+            [, month, day, year] = match.map(Number);
+            year = year < 50 ? 2000 + year : 1900 + year;
+            break;
+          case 'eu-4':
+          case 'eu-dash-4':
+          case 'eu-dot-4':
+            [, day, month, year] = match.map(Number);
+            break;
+          case 'eu-2':
+            [, day, month, year] = match.map(Number);
+            year = year < 50 ? 2000 + year : 1900 + year;
+            break;
+          case 'natural-dd-mmm-yyyy':
+          case 'natural-dd-mmmm-yyyy': {
+            const dayStr = match[1];
+            const yearStr = match[3];
+            month = monthNames[match[2].toLowerCase()];
+            day = parseInt(dayStr, 10);
+            year = parseInt(yearStr, 10);
+            break;
+          }
+          case 'natural-mmm-dd-yyyy':
+          case 'natural-mmmm-dd-yyyy': {
+            const dayStr = match[2];
+            const yearStr = match[3];
+            month = monthNames[match[1].toLowerCase()];
+            day = parseInt(dayStr, 10);
+            year = parseInt(yearStr, 10);
+            break;
+          }
+          default:
+            continue;
+        }
+
+        const date = new Date(year, month - 1, day, hour, minute, second);
+        if (!isNaN(date.getTime())) return date;
+      } catch {
+        continue;
+      }
+    }
+  }
+
+  const nativeDate = new Date(trimmedDate);
+  if (!isNaN(nativeDate.getTime())) return nativeDate;
+  return null;
+}

package/src/components/DataTable/utils/importValueParser.test.ts

@@ -0,0 +1,138 @@
+/**
+ * @file Import Value Parser Tests
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils
+ */
+
+import { describe, it, expect } from 'vitest';
+import { sanitizeImportString, parseImportValue } from './importValueParser';
+
+const TEST_TIMEOUT = 10000;
+
+describe('[unit] sanitizeImportString', () => {
+  it('returns string unchanged when within max length and no special chars', () => {
+    expect(sanitizeImportString('hello', {})).toBe('hello');
+  }, TEST_TIMEOUT);
+
+  it('truncates to maxStringLength when provided', () => {
+    const long = 'a'.repeat(20);
+    expect(sanitizeImportString(long, { maxStringLength: 10 })).toBe('a'.repeat(10));
+  }, TEST_TIMEOUT);
+
+  it('uses default max length 10000 when not provided', () => {
+    const long = 'a'.repeat(10001);
+    expect(sanitizeImportString(long, {}).length).toBe(10000);
+  }, TEST_TIMEOUT);
+
+  it('strips control chars when allowControlChars is false', () => {
+    expect(sanitizeImportString('a\x00b\x01c', {})).toBe('abc');
+    expect(sanitizeImportString('hello\x07world', {})).toBe('helloworld');
+  }, TEST_TIMEOUT);
+
+  it('keeps non-null control chars when allowControlChars is true', () => {
+    const withControl = 'a\x01b';
+    expect(sanitizeImportString(withControl, { allowControlChars: true })).toBe(withControl);
+  }, TEST_TIMEOUT);
+
+  it('removes null bytes', () => {
+    expect(sanitizeImportString('a\0b\0c', {})).toBe('abc');
+  }, TEST_TIMEOUT);
+
+  it('escapes double quote to "', () => {
+    expect(sanitizeImportString('say "hi"', {})).toBe('say "hi"');
+  }, TEST_TIMEOUT);
+
+  it('escapes single quote to '', () => {
+    expect(sanitizeImportString("it's", {})).toBe('it's');
+  }, TEST_TIMEOUT);
+
+  it('escapes semicolon to ;', () => {
+    expect(sanitizeImportString('a;b', {})).toBe('a;b');
+  }, TEST_TIMEOUT);
+});
+
+describe('[unit] parseImportValue', () => {
+  it('returns default for null, undefined, or empty string', () => {
+    expect(parseImportValue(null, 'x', {})).toBe('');
+    expect(parseImportValue(undefined, 'x', {})).toBe('');
+    expect(parseImportValue('', 'x', {})).toBe('');
+  }, TEST_TIMEOUT);
+
+  it('returns defaultValues[fieldName] when value is empty and defaultValues provided', () => {
+    expect(parseImportValue('', 'myField', { defaultValues: { myField: 'default' } })).toBe('default');
+    expect(parseImportValue(null, 'other', { defaultValues: { other: 0 } })).toBe(0);
+  }, TEST_TIMEOUT);
+
+  it('parses string value and sanitizes it', () => {
+    expect(parseImportValue('hello', 'name', {})).toBe('hello');
+    expect(parseImportValue('  hello  ', 'name', {})).toBe('  hello  ');
+  }, TEST_TIMEOUT);
+
+  it('parses boolean true/false (case-insensitive)', () => {
+    expect(parseImportValue('true', 'active', {})).toBe(true);
+    expect(parseImportValue('TRUE', 'active', {})).toBe(true);
+    expect(parseImportValue('false', 'active', {})).toBe(false);
+    expect(parseImportValue('FALSE', 'active', {})).toBe(false);
+  }, TEST_TIMEOUT);
+
+  it('parses date field as ISO string', () => {
+    const result = parseImportValue('2020-01-02', 'startDate', {});
+    expect(typeof result).toBe('string');
+    const d = new Date(result as string);
+    expect(d.getFullYear()).toBe(2020);
+    expect(d.getMonth()).toBe(0);
+    expect(d.getDate()).toBe(2);
+  }, TEST_TIMEOUT);
+
+  it('parses startDate field as ISO string when parseable', () => {
+    const result = parseImportValue('2020-01-02T12:30:00', 'startDate', {});
+    expect(typeof result).toBe('string');
+    expect((result as string).includes('2020-01-02')).toBe(true);
+  }, TEST_TIMEOUT);
+
+  it('returns sanitized string for date field when not parseable as date', () => {
+    const result = parseImportValue('not-a-date', 'someDate', {});
+    expect(result).toBe('not-a-date');
+  }, TEST_TIMEOUT);
+
+  it('parses number for non-date field', () => {
+    expect(parseImportValue('42', 'count', {})).toBe(42);
+    expect(parseImportValue('3.14', 'price', {})).toBe(3.14);
+    expect(parseImportValue('-10', 'balance', {})).toBe(-10);
+  }, TEST_TIMEOUT);
+
+  it('does not parse number for date/time field (returns string)', () => {
+    const result = parseImportValue('42', 'dateField', {});
+    expect(result).not.toBe(42);
+    expect(typeof result).toBe('string');
+  }, TEST_TIMEOUT);
+
+  it('splits comma-separated for tag/category field', () => {
+    const result = parseImportValue('a, b, c', 'tags', {});
+    expect(result).toEqual(['a', 'b', 'c']);
+  }, TEST_TIMEOUT);
+
+  it('splits comma-separated for category field', () => {
+    const result = parseImportValue('x,y,z', 'category', {});
+    expect(result).toEqual(['x', 'y', 'z']);
+  }, TEST_TIMEOUT);
+
+  it('trims and filters empty items in comma-separated', () => {
+    const result = parseImportValue('a, , b,, c', 'tags', {});
+    expect(result).toEqual(['a', 'b', 'c']);
+  }, TEST_TIMEOUT);
+
+  it('returns non-string value as-is', () => {
+    expect(parseImportValue(42, 'x', {})).toBe(42);
+    expect(parseImportValue(true, 'x', {})).toBe(true);
+  }, TEST_TIMEOUT);
+
+  it('applies sanitization when parsing string', () => {
+    const withQuote = 'say "hi"';
+    expect(parseImportValue(withQuote, 'name', {})).toBe('say "hi"');
+  }, TEST_TIMEOUT);
+
+  it('returns empty string for empty value when no defaultValues', () => {
+    expect(parseImportValue('', 'any', {})).toBe('');
+  }, TEST_TIMEOUT);
+});

package/src/components/DataTable/utils/importValueParser.ts

@@ -0,0 +1,91 @@
+/**
+ * @file Import Value Parser
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils
+ * @since 0.3.0
+ *
+ * Value and string sanitization for flexible CSV import. Extracted from flexibleImport for max-lines-per-function.
+ */
+
+import type { CellValue } from '../types';
+import { parseImportDate } from './importDateParser';
+
+/** Options used by parseImportValue and sanitizeImportString. */
+export interface ImportValueParserOptions {
+  maxStringLength?: number;
+  allowControlChars?: boolean;
+  defaultValues?: Record<string, CellValue>;
+}
+
+/**
+ * Sanitizes a string value for import (length, control chars, null bytes, simple escaping).
+ */
+export function sanitizeImportString(value: string, options: ImportValueParserOptions): string {
+  const maxLength = options.maxStringLength ?? 10000;
+  let sanitized = value;
+
+  if (sanitized.length > maxLength) {
+    sanitized = sanitized.substring(0, maxLength);
+  }
+
+  if (!options.allowControlChars) {
+    sanitized = sanitized.replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F]/g, '');
+  }
+
+  sanitized = sanitized.replace(/\0/g, '');
+  sanitized = sanitized.replace(/['";]/g, (char) =>
+    char === '"' ? '&quot;' : char === "'" ? '&apos;' : '&semi;'
+  );
+
+  return sanitized;
+}
+
+/**
+ * Parses a single value for import: default handling, date/boolean/array/number detection, sanitization.
+ *
+ * @param value - Raw value from CSV row
+ * @param fieldName - Target field name (used for date/defaults)
+ * @param options - Parser options (defaultValues, maxStringLength, allowControlChars)
+ * @returns Parsed value (string, number, boolean, date ISO string, or array of strings)
+ */
+export function parseImportValue(
+  value: unknown,
+  fieldName: string,
+  options: ImportValueParserOptions
+): unknown {
+  if (value === null || value === undefined || value === '') {
+    return options.defaultValues?.[fieldName] ?? '';
+  }
+
+  if (typeof value === 'string') {
+    const sanitized = sanitizeImportString(value, options);
+    const lowerField = fieldName.toLowerCase();
+
+    if (lowerField.includes('date') || lowerField.includes('time')) {
+      const dateValue = parseImportDate(sanitized, fieldName);
+      if (dateValue) return dateValue.toISOString();
+    }
+
+    if (sanitized.toLowerCase() === 'true') return true;
+    if (sanitized.toLowerCase() === 'false') return false;
+
+    if (
+      sanitized.includes(',') &&
+      (lowerField.includes('tag') || lowerField.includes('category'))
+    ) {
+      return sanitized
+        .split(',')
+        .map((item: string) => item.trim())
+        .filter((item: string) => item);
+    }
+
+    if (!lowerField.includes('date') && !lowerField.includes('time')) {
+      const numValue = parseFloat(sanitized);
+      if (!isNaN(numValue) && isFinite(numValue)) return numValue;
+    }
+
+    return sanitized;
+  }
+
+  return value;
+}

package/src/components/DataTable/utils/{__tests__/paginationUtils.test.ts → paginationUtils.test.ts}

@@ -14,8 +14,8 @@ import {
   validatePaginationConfig,
   getPageSizeOptions,
   calculateOptimalPageSize,
-} from '../paginationUtils';
-import type { DataRecord, ServerSideResponse } from '../../types';
+} from './paginationUtils';
+import type { DataRecord, ServerSideResponse } from '../types';
 
 // Mock logger
 vi.mock('../../../utils/core/logger', () => ({

package/src/components/DataTable/utils/paginationUtils.ts

@@ -7,7 +7,7 @@
  * Unified pagination utilities that work consistently across client/server/hybrid modes.
  */
 
-import { Table } from '@tanstack/react-table';
+import { Table, type PaginationState } from '@tanstack/react-table';
 import type { PaginationMode, ServerSideResponse, DataRecord } from '../types';
 import { createLogger } from '../../../utils/core/logger';
 
@@ -71,6 +71,8 @@ export interface PaginationBindingConfig<TData extends DataRecord> {
   onPageChange?: (pageIndex: number) => void;
   /** Page size change callback (for server/hybrid modes) */
   onPageSizeChange?: (pageSize: number) => void;
+  /** React-tracked pagination state (preferred over table.getState().pagination for client mode) */
+  paginationState?: PaginationState;
 }
 
 /**
@@ -233,8 +235,9 @@ function calculatePaginationState<TData extends DataRecord>(
   }
 
   if (table) {
-    // Client or hybrid mode: use table state
-    const paginationState = table.getState().pagination;
+    // Client or hybrid mode: prefer React-tracked state over table state
+    // This ensures React knows when to re-render when pagination changes
+    const paginationState = config.paginationState ?? table.getState().pagination;
     const rowCount = totalCount ?? table.getRowCount();
     const pageCount = Math.ceil(rowCount / paginationState.pageSize);
     

package/src/components/DataTable/utils/{__tests__/performanceUtils.test.ts → performanceUtils.test.ts}

@@ -1,7 +1,7 @@
 /**
  * @file Unit Tests for performanceUtils
  * @package @jmruthers/pace-core
- * @module Components/DataTable/Utils/__tests__
+ * @module Components/DataTable/Utils
  */
 
 import { describe, it, expect, beforeEach, vi } from 'vitest';
@@ -14,8 +14,8 @@ import {
   debounce,
   throttle,
   VisibilityTracker
-} from '../performanceUtils';
-import type { ChunkingConfig, SearchIndexConfig, DataRecord } from '../../types';
+} from './performanceUtils';
+import type { ChunkingConfig, SearchIndexConfig, DataRecord } from '../types';
 
 describe('[unit] determinePaginationMode', () => {
   it('returns client for small datasets', () => {

package/src/components/DataTable/utils/{__tests__/rowUtils.test.ts → rowUtils.test.ts}

@@ -1,12 +1,12 @@
 /**
  * @file Unit Tests for rowUtils
  * @package @jmruthers/pace-core
- * @module Components/DataTable/Utils/__tests__
+ * @module Components/DataTable/Utils
  */
 
 import { describe, it, expect } from 'vitest';
-import { getRowIdSafe, hasValidRowId } from '../rowUtils';
-import type { GetRowId, DataRecord } from '../../types';
+import { getRowIdSafe, hasValidRowId } from './rowUtils';
+import type { GetRowId, DataRecord } from '../types';
 
 describe('[unit] getRowIdSafe', () => {
   it('uses custom getRowId when provided', () => {

package/src/components/DataTable/utils/{__tests__/selectFieldUtils.test.ts → selectFieldUtils.test.ts}

@@ -1,15 +1,15 @@
 /**
  * @file Select Field Utils Tests
  * @package @jmruthers/pace-core
- * @module Components/DataTable/Utils/__tests__
+ * @module Components/DataTable/Utils
  * @since 0.6.0
  * 
  * Unit tests for select field utility functions.
  */
 
 import { describe, it, expect } from 'vitest';
-import { findSelectLabel } from '../selectFieldUtils';
-import type { DataTableColumn } from '../../types';
+import { findSelectLabel, optionMatchesSearch } from './selectFieldUtils';
+import type { DataTableColumn } from '../types';
 
 describe('findSelectLabel', () => {
   describe('Simple Options', () => {
@@ -206,3 +206,66 @@ describe('findSelectLabel', () => {
     });
   });
 });
+
+describe('optionMatchesSearch', () => {
+  describe('Simple Options', () => {
+    it('returns true when label contains search string (case-insensitive)', () => {
+      expect(optionMatchesSearch({ value: 1, label: 'Mobile' }, 'mobile')).toBe(true);
+      expect(optionMatchesSearch({ value: 2, label: 'Home' }, 'home')).toBe(true);
+      expect(optionMatchesSearch({ value: 3, label: 'Work' }, 'wo')).toBe(true);
+    });
+
+    it('returns false when label does not contain search string', () => {
+      expect(optionMatchesSearch({ value: 1, label: 'Mobile' }, 'desk')).toBe(false);
+      expect(optionMatchesSearch({ value: 2, label: 'Home' }, 'office')).toBe(false);
+    });
+  });
+
+  describe('Group Options', () => {
+    it('returns true when any item label in group contains search string', () => {
+      const group = {
+        type: 'group' as const,
+        label: 'Primary',
+        items: [
+          { value: 1, label: 'Mobile' },
+          { value: 2, label: 'Home' },
+        ],
+      };
+      expect(optionMatchesSearch(group, 'mobile')).toBe(true);
+      expect(optionMatchesSearch(group, 'home')).toBe(true);
+      expect(optionMatchesSearch(group, 'mo')).toBe(true);
+    });
+
+    it('returns false when no item in group matches search string', () => {
+      const group = {
+        type: 'group' as const,
+        label: 'Primary',
+        items: [
+          { value: 1, label: 'Mobile' },
+          { value: 2, label: 'Home' },
+        ],
+      };
+      expect(optionMatchesSearch(group, 'desk')).toBe(false);
+      expect(optionMatchesSearch(group, 'xyz')).toBe(false);
+    });
+  });
+
+  describe('Separator and Non-matching Types', () => {
+    it('returns false for separator option', () => {
+      expect(optionMatchesSearch({ type: 'separator' }, 'any')).toBe(false);
+      expect(optionMatchesSearch({ type: 'separator' }, '')).toBe(false);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles empty searchLower: matches when label is empty or contains empty', () => {
+      expect(optionMatchesSearch({ value: 1, label: 'Mobile' }, '')).toBe(true);
+      expect(optionMatchesSearch({ value: 2, label: '' }, '')).toBe(true);
+    });
+
+    it('handles partial match in label', () => {
+      expect(optionMatchesSearch({ value: 1, label: 'Active' }, 'act')).toBe(true);
+      expect(optionMatchesSearch({ value: 2, label: 'Pending' }, 'ing')).toBe(true);
+    });
+  });
+});