@jmruthers/pace-core 0.2.4

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

@@ -0,0 +1,218 @@
+/**
+ * @file Hierarchical Data Processing Utilities
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils/hierarchicalUtils
+ * @since 0.4.35
+ */
+
+import type { HierarchicalDataRow, DataTableColumn, DataRecord } from '../types';
+
+/**
+ * Validates that data conforms to hierarchical structure
+ */
+export function validateHierarchicalData<TData extends HierarchicalDataRow>(
+  data: TData[]
+): { isValid: boolean; errors: string[] } {
+  const errors: string[] = [];
+  
+  // Check that all rows have required fields
+  data.forEach((row, index) => {
+    if (!row.id) {
+      errors.push(`Row ${index}: Missing required 'id' field`);
+    }
+    
+    if (typeof row.isParent !== 'boolean') {
+      errors.push(`Row ${index}: Missing or invalid 'isParent' field`);
+    }
+    
+    if (!row.isParent && !row.parentId) {
+      errors.push(`Row ${index}: Child row missing 'parentId' field`);
+    }
+  });
+
+  // Check for orphaned child rows
+  const parentIds = new Set(data.filter(row => row.isParent).map(row => row.id));
+  data.forEach((row, index) => {
+    if (!row.isParent && row.parentId && !parentIds.has(row.parentId)) {
+      errors.push(`Row ${index}: Child row references non-existent parent '${row.parentId}'`);
+    }
+  });
+
+  // Check for duplicate IDs
+  const ids = data.map(row => row.id);
+  const duplicateIds = ids.filter((id, index) => ids.indexOf(id) !== index);
+  if (duplicateIds.length > 0) {
+    errors.push(`Duplicate IDs found: ${duplicateIds.join(', ')}`);
+  }
+
+  return {
+    isValid: errors.length === 0,
+    errors,
+  };
+}
+
+/**
+ * Sorts hierarchical data to ensure parent rows come before their children
+ */
+export function sortHierarchicalData<TData extends HierarchicalDataRow>(
+  data: TData[]
+): TData[] {
+  const sorted: TData[] = [];
+  const processed = new Set<string>();
+  
+  // First, add all parent rows
+  data.forEach(row => {
+    if (row.isParent && !processed.has(row.id)) {
+      sorted.push(row);
+      processed.add(row.id);
+    }
+  });
+  
+  // Then, add children in order
+  data.forEach(row => {
+    if (!row.isParent && !processed.has(row.id)) {
+      sorted.push(row);
+      processed.add(row.id);
+    }
+  });
+  
+  return sorted;
+}
+
+/**
+ * Groups data into parent-child relationships
+ */
+export function groupHierarchicalData<TData extends HierarchicalDataRow>(
+  data: TData[]
+): Map<string, { parent: TData; children: TData[] }> {
+  const groups = new Map<string, { parent: TData; children: TData[] }>();
+  
+  // Initialize groups for parent rows
+  data.forEach(row => {
+    if (row.isParent) {
+      groups.set(row.id, { parent: row, children: [] });
+    }
+  });
+  
+  // Add children to their parent groups
+  data.forEach(row => {
+    if (!row.isParent && row.parentId) {
+      const group = groups.get(row.parentId);
+      if (group) {
+        group.children.push(row);
+      }
+    }
+  });
+  
+  return groups;
+}
+
+/**
+ * Gets the depth level of a row in the hierarchy
+ */
+export function getRowDepth<TData extends HierarchicalDataRow>(
+  row: TData,
+  allData: TData[]
+): number {
+  if (row.isParent) {
+    return 0;
+  }
+  
+  if (!row.parentId) {
+    return 0;
+  }
+  
+  // Find parent and calculate depth
+  const parent = allData.find(p => p.id === row.parentId);
+  if (!parent) {
+    return 0;
+  }
+  
+  return 1 + getRowDepth(parent, allData);
+}
+
+/**
+ * Determines if a column should be visible for a given row type
+ */
+export function shouldShowColumnForRow<TData extends HierarchicalDataRow>(
+  column: DataTableColumn<TData>,
+  isParent: boolean
+): boolean {
+  if (isParent && column.hideForParent) {
+    return false;
+  }
+  
+  if (!isParent && column.hideForChild) {
+    return false;
+  }
+  
+  return true;
+}
+
+/**
+ * Gets the appropriate cell renderer for a row type
+ */
+export function getCellRenderer<TData extends HierarchicalDataRow>(
+  column: DataTableColumn<TData>,
+  row: TData
+): ((row: TData) => React.ReactNode) | undefined {
+  if (row.isParent && column.renderForParent) {
+    return column.renderForParent;
+  }
+  
+  if (!row.isParent && column.renderForChild) {
+    return column.renderForChild;
+  }
+  
+  return column.cell as ((row: TData) => React.ReactNode) | undefined;
+}
+
+/**
+ * Calculates the indentation for a child row
+ */
+export function calculateIndentation<TData extends HierarchicalDataRow>(
+  row: TData,
+  allData: TData[],
+  baseIndent: number = 24
+): number {
+  const depth = getRowDepth(row, allData);
+  return depth * baseIndent;
+}
+
+/**
+ * Creates a hierarchical data structure from flat data
+ */
+export function createHierarchicalStructure<TData extends DataRecord>(
+  data: TData[],
+  parentKey: keyof TData,
+  childrenKey: keyof TData,
+  idKey: keyof TData = 'id' as keyof TData
+): HierarchicalDataRow[] {
+  const result: HierarchicalDataRow[] = [];
+  
+  data.forEach(item => {
+    // Add parent row
+    const parentRow: HierarchicalDataRow = {
+      ...item,
+      id: String(item[idKey]),
+      isParent: true,
+    };
+    result.push(parentRow);
+    
+    // Add child rows
+    const children = item[childrenKey] as TData[] | undefined;
+    if (children && Array.isArray(children)) {
+      children.forEach(child => {
+        const childRow: HierarchicalDataRow = {
+          ...child,
+          id: `${String(item[idKey])}-${String(child[idKey])}`,
+          isParent: false,
+          parentId: String(item[idKey]),
+        };
+        result.push(childRow);
+      });
+    }
+  });
+  
+  return result;
+}

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

@@ -0,0 +1 @@
+export * from './exportUtils';

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

@@ -0,0 +1,351 @@
+/**
+ * @file Performance Utilities for DataTable
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils/Performance
+ * @since 0.3.0
+ */
+
+import type { 
+  DataRecord, 
+  PaginationMode, 
+  ChunkingConfig, 
+  SearchIndexConfig
+} from '../types';
+
+// ============================================================================
+// PAGINATION MODE DETECTION
+// ============================================================================
+
+/**
+ * Determines the optimal pagination mode based on dataset size
+ */
+export function determinePaginationMode(
+  dataLength: number,
+  serverSideThreshold: number = 10000
+): PaginationMode {
+  if (dataLength <= 1000) return 'client';
+  if (dataLength <= serverSideThreshold) return 'hybrid';
+  return 'server';
+}
+
+/**
+ * Gets optimal page size options based on pagination mode and dataset size
+ */
+export function getOptimalPageSizeOptions(
+  mode: PaginationMode,
+  dataLength: number
+): number[] {
+  switch (mode) {
+    case 'client':
+      return dataLength <= 100 ? [10, 25, 50] : [10, 25, 50, 100];
+    case 'hybrid':
+      return [50, 100, 250, 500];
+    case 'server':
+      return [25, 50, 100, 250];
+    default:
+      return [10, 25, 50, 100];
+  }
+}
+
+// ============================================================================
+// DATA CHUNKING
+// ============================================================================
+
+/**
+ * Splits data into chunks for memory management
+ */
+export function chunkData<TData extends DataRecord>(
+  data: TData[],
+  chunkSize: number
+): TData[][] {
+  const chunks: TData[][] = [];
+  for (let i = 0; i < data.length; i += chunkSize) {
+    chunks.push(data.slice(i, i + chunkSize));
+  }
+  return chunks;
+}
+
+/**
+ * Manages data chunks with LRU cache
+ */
+export class DataChunkManager<TData extends DataRecord> {
+  private chunks: Map<number, TData[]> = new Map();
+  private accessOrder: number[] = [];
+  private maxChunks: number;
+  private chunkSize: number;
+
+  constructor(config: ChunkingConfig) {
+    this.maxChunks = config.maxChunksInMemory;
+    this.chunkSize = config.chunkSize;
+  }
+
+  getChunk(chunkIndex: number, allData: TData[]): TData[] {
+    // Check if chunk is already in memory
+    if (this.chunks.has(chunkIndex)) {
+      this.updateAccessOrder(chunkIndex);
+      return this.chunks.get(chunkIndex)!;
+    }
+
+    // Calculate chunk bounds
+    const startIndex = chunkIndex * this.chunkSize;
+    const endIndex = Math.min(startIndex + this.chunkSize, allData.length);
+    const chunk = allData.slice(startIndex, endIndex);
+
+    // Add chunk to memory
+    this.addChunk(chunkIndex, chunk);
+    return chunk;
+  }
+
+  private addChunk(chunkIndex: number, chunk: TData[]): void {
+    // Remove oldest chunk if at capacity
+    if (this.chunks.size >= this.maxChunks && !this.chunks.has(chunkIndex)) {
+      const oldestChunk = this.accessOrder.shift();
+      if (oldestChunk !== undefined) {
+        this.chunks.delete(oldestChunk);
+      }
+    }
+
+    this.chunks.set(chunkIndex, chunk);
+    this.updateAccessOrder(chunkIndex);
+  }
+
+  private updateAccessOrder(chunkIndex: number): void {
+    const existingIndex = this.accessOrder.indexOf(chunkIndex);
+    if (existingIndex > -1) {
+      this.accessOrder.splice(existingIndex, 1);
+    }
+    this.accessOrder.push(chunkIndex);
+  }
+
+  clear(): void {
+    this.chunks.clear();
+    this.accessOrder = [];
+  }
+
+  getMemoryUsage(): number {
+    let totalSize = 0;
+    for (const chunk of this.chunks.values()) {
+      totalSize += JSON.stringify(chunk).length;
+    }
+    return totalSize / (1024 * 1024); // Convert to MB
+  }
+}
+
+// ============================================================================
+// SEARCH INDEXING
+// ============================================================================
+
+/**
+ * Creates a search index for fast text searching
+ */
+export class SearchIndex<TData extends DataRecord> {
+  private index: Map<string, Set<number>> = new Map();
+  private data: TData[] = [];
+  private indexedFields: string[];
+  private fuzzySearch: boolean;
+  private fuzzyThreshold: number;
+
+  constructor(config: SearchIndexConfig) {
+    this.indexedFields = config.indexedFields;
+    this.fuzzySearch = config.fuzzySearch ?? false;
+    this.fuzzyThreshold = config.fuzzyThreshold ?? 0.6;
+  }
+
+  buildIndex(data: TData[]): void {
+    this.data = data;
+    this.index.clear();
+
+    data.forEach((row, rowIndex) => {
+      this.indexedFields.forEach(field => {
+        const value = this.getNestedValue(row, field);
+        if (value != null) {
+          const searchableText = String(value).toLowerCase();
+          const words = this.tokenize(searchableText);
+          
+          words.forEach(word => {
+            if (!this.index.has(word)) {
+              this.index.set(word, new Set());
+            }
+            this.index.get(word)!.add(rowIndex);
+          });
+        }
+      });
+    });
+  }
+
+  search(query: string): number[] {
+    if (!query.trim()) return [];
+
+    const searchTerms = this.tokenize(query.toLowerCase());
+    const matchingSets: Set<number>[] = [];
+
+    searchTerms.forEach(term => {
+      const matches = new Set<number>();
+      
+      // Exact matches
+      if (this.index.has(term)) {
+        this.index.get(term)!.forEach(index => matches.add(index));
+      }
+
+      // Fuzzy matches
+      if (this.fuzzySearch) {
+        for (const [indexedTerm, indices] of this.index.entries()) {
+          if (this.calculateSimilarity(term, indexedTerm) >= this.fuzzyThreshold) {
+            indices.forEach(index => matches.add(index));
+          }
+        }
+      }
+
+      matchingSets.push(matches);
+    });
+
+    // Find intersection of all matching sets
+    if (matchingSets.length === 0) return [];
+    
+    let result = matchingSets[0];
+    for (let i = 1; i < matchingSets.length; i++) {
+      result = new Set([...result].filter(x => matchingSets[i].has(x)));
+    }
+
+    return Array.from(result);
+  }
+
+  private getNestedValue(obj: any, path: string): any {
+    return path.split('.').reduce((current, key) => current?.[key], obj);
+  }
+
+  private tokenize(text: string): string[] {
+    return text
+      .replace(/[^\w\s]/g, ' ')
+      .split(/\s+/)
+      .filter(word => word.length > 0);
+  }
+
+  private calculateSimilarity(str1: string, str2: string): number {
+    const longer = str1.length > str2.length ? str1 : str2;
+    const shorter = str1.length > str2.length ? str2 : str1;
+    
+    if (longer.length === 0) return 1.0;
+    
+    const editDistance = this.levenshteinDistance(longer, shorter);
+    return (longer.length - editDistance) / longer.length;
+  }
+
+  private levenshteinDistance(str1: string, str2: string): number {
+    const matrix = Array(str2.length + 1).fill(null).map(() => 
+      Array(str1.length + 1).fill(null)
+    );
+
+    for (let i = 0; i <= str1.length; i++) matrix[0][i] = i;
+    for (let j = 0; j <= str2.length; j++) matrix[j][0] = j;
+
+    for (let j = 1; j <= str2.length; j++) {
+      for (let i = 1; i <= str1.length; i++) {
+        const substitutionCost = str1[i - 1] === str2[j - 1] ? 0 : 1;
+        matrix[j][i] = Math.min(
+          matrix[j][i - 1] + 1, // insertion
+          matrix[j - 1][i] + 1, // deletion
+          matrix[j - 1][i - 1] + substitutionCost // substitution
+        );
+      }
+    }
+
+    return matrix[str2.length][str1.length];
+  }
+}
+
+
+// ============================================================================
+// DEBOUNCE UTILITIES
+// ============================================================================
+
+/**
+ * Creates a debounced function
+ */
+export function debounce<T extends (...args: any[]) => any>(
+  func: T,
+  delay: number
+): (...args: Parameters<T>) => void {
+  let timeoutId: NodeJS.Timeout;
+  
+  return (...args: Parameters<T>) => {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => func(...args), delay);
+  };
+}
+
+/**
+ * Creates a throttled function
+ */
+export function throttle<T extends (...args: any[]) => any>(
+  func: T,
+  delay: number
+): (...args: Parameters<T>) => void {
+  let lastCall = 0;
+  
+  return (...args: Parameters<T>) => {
+    const now = Date.now();
+    if (now - lastCall >= delay) {
+      lastCall = now;
+      func(...args);
+    }
+  };
+}
+
+// ============================================================================
+// MEMORY MANAGEMENT
+// ============================================================================
+
+/**
+ * Intersection Observer for tracking visible rows
+ */
+export class VisibilityTracker {
+  private observer: IntersectionObserver | null = null;
+  private visibleElements = new Set<Element>();
+  private callbacks = new Set<(visibleCount: number) => void>();
+
+  constructor() {
+    if (typeof IntersectionObserver !== 'undefined') {
+      this.observer = new IntersectionObserver(
+        (entries) => {
+          entries.forEach(entry => {
+            if (entry.isIntersecting) {
+              this.visibleElements.add(entry.target);
+            } else {
+              this.visibleElements.delete(entry.target);
+            }
+          });
+          
+          this.callbacks.forEach(callback => {
+            callback(this.visibleElements.size);
+          });
+        },
+        { threshold: 0.1 }
+      );
+    }
+  }
+
+  observe(element: Element): void {
+    this.observer?.observe(element);
+  }
+
+  unobserve(element: Element): void {
+    this.observer?.unobserve(element);
+    this.visibleElements.delete(element);
+  }
+
+  onVisibilityChange(callback: (visibleCount: number) => void): () => void {
+    this.callbacks.add(callback);
+    return () => this.callbacks.delete(callback);
+  }
+
+  getVisibleCount(): number {
+    return this.visibleElements.size;
+  }
+
+  destroy(): void {
+    this.observer?.disconnect();
+    this.visibleElements.clear();
+    this.callbacks.clear();
+  }
+}