@visns-studio/visns-components 5.11.10 → 5.11.12

package/src/utils/relationshipSortingUtils.js

@@ -0,0 +1,289 @@
+/**
+ * Intelligent Relationship Sorting Utilities
+ * 
+ * Automatically determines if relationship columns should be sortable
+ * based on column configuration patterns and field types.
+ */
+
+/**
+ * Fields that are typically sortable
+ */
+const SORTABLE_FIELD_PATTERNS = [
+    // Text fields
+    'name', 'title', 'label', 'description', 'email', 'username', 'slug',
+    'first_name', 'last_name', 'full_name', 'display_name', 'company_name',
+    'organization', 'department', 'position', 'role', 'status', 'type',
+    'category', 'tag', 'code', 'reference', 'identifier', 'serial',
+    
+    // Date fields  
+    'created_at', 'updated_at', 'deleted_at', 'published_at', 'expires_at',
+    'start_date', 'end_date', 'due_date', 'birth_date', 'date', 'timestamp',
+    
+    // Numeric fields
+    'id', 'order', 'sort_order', 'priority', 'weight', 'score', 'rating',
+    'amount', 'price', 'cost', 'total', 'quantity', 'count', 'number',
+    'percentage', 'rate', 'value', 'balance', 'age', 'duration',
+    
+    // Boolean/Status fields (often useful for sorting)
+    'active', 'enabled', 'visible', 'published', 'featured', 'verified',
+    'approved', 'completed', 'archived', 'deleted'
+];
+
+/**
+ * Fields that should NOT be sortable
+ */
+const UNSORTABLE_FIELD_PATTERNS = [
+    // Large text/blob fields
+    'content', 'body', 'text', 'html', 'markdown', 'notes', 'comments',
+    'description_long', 'bio', 'about', 'details', 'message', 'review',
+    
+    // Binary/complex data
+    'data', 'metadata', 'settings', 'config', 'options', 'attributes',
+    'properties', 'json', 'xml', 'blob', 'binary', 'file', 'image',
+    'photo', 'avatar', 'logo', 'attachment', 'upload',
+    
+    // Sensitive fields
+    'password', 'token', 'key', 'secret', 'hash', 'signature', 'checksum'
+];
+
+/**
+ * Relationship depth limits for sorting
+ */
+const MAX_RELATIONSHIP_DEPTH = 3;
+
+/**
+ * Determines if a relationship column should be sortable based on intelligent analysis
+ * 
+ * @param {Object} column - Column configuration object
+ * @param {Object} options - Additional options for sorting intelligence
+ * @returns {boolean} - Whether the column should be sortable
+ */
+export const isRelationshipColumnSortable = (column, options = {}) => {
+    const {
+        enableIntelligentSorting = true,
+        maxRelationshipDepth = MAX_RELATIONSHIP_DEPTH,
+        customSortableFields = [],
+        customUnsortableFields = [],
+        respectExplicitSortable = true
+    } = options;
+
+    // If intelligent sorting is disabled, fall back to explicit configuration
+    if (!enableIntelligentSorting) {
+        return column.sortable === true;
+    }
+
+    // Respect explicit sortable configuration if specified
+    if (respectExplicitSortable && column.hasOwnProperty('sortable')) {
+        return column.sortable === true;
+    }
+
+    // Only analyze relation and relationArray types
+    if (!['relation', 'relationArray'].includes(column.type)) {
+        return false;
+    }
+
+    // Check relationship depth
+    const relationshipDepth = Array.isArray(column.id) ? column.id.length : 1;
+    if (relationshipDepth > maxRelationshipDepth) {
+        console.warn(`Relationship depth ${relationshipDepth} exceeds maximum ${maxRelationshipDepth} for sorting: ${getRelationshipPath(column)}`);
+        return false;
+    }
+
+    // Analyze the target field name
+    let fieldName = column.nameFrom;
+    if (!fieldName) {
+        return false;
+    }
+    
+    // Handle array nameFrom (for relationArray columns)
+    if (Array.isArray(fieldName)) {
+        // Use the first field name for analysis
+        fieldName = fieldName[0];
+        if (!fieldName) {
+            return false;
+        }
+    }
+
+    // Check custom configurations first
+    const customSortable = [...SORTABLE_FIELD_PATTERNS, ...customSortableFields];
+    const customUnsortable = [...UNSORTABLE_FIELD_PATTERNS, ...customUnsortableFields];
+
+    // Explicit unsortable fields take precedence
+    if (isFieldInPatterns(fieldName, customUnsortable)) {
+        return false;
+    }
+
+    // Check if field matches sortable patterns
+    if (isFieldInPatterns(fieldName, customSortable)) {
+        return true;
+    }
+
+    // Analyze field name patterns for common sortable types
+    return analyzeFieldNamePattern(fieldName);
+};
+
+/**
+ * Checks if a field name matches any of the given patterns
+ * 
+ * @param {string} fieldName - The field name to check
+ * @param {Array} patterns - Array of patterns to match against
+ * @returns {boolean} - Whether the field matches any pattern
+ */
+const isFieldInPatterns = (fieldName, patterns) => {
+    // Ensure fieldName is a string
+    if (typeof fieldName !== 'string') {
+        return false;
+    }
+    
+    const normalizedFieldName = fieldName.toLowerCase();
+    
+    return patterns.some(pattern => {
+        const normalizedPattern = pattern.toLowerCase();
+        
+        // Exact match
+        if (normalizedFieldName === normalizedPattern) {
+            return true;
+        }
+        
+        // Contains pattern (for composite field names)
+        if (normalizedFieldName.includes(normalizedPattern)) {
+            return true;
+        }
+        
+        // Pattern contains field name (for abbreviated fields)
+        if (normalizedPattern.includes(normalizedFieldName)) {
+            return true;
+        }
+        
+        return false;
+    });
+};
+
+/**
+ * Analyzes field name patterns to determine if they're likely sortable
+ * 
+ * @param {string} fieldName - The field name to analyze
+ * @returns {boolean} - Whether the field appears to be sortable
+ */
+const analyzeFieldNamePattern = (fieldName) => {
+    const normalizedName = fieldName.toLowerCase();
+    
+    // Date-like patterns
+    if (/_at$|_date$|date_|_time$|time_/.test(normalizedName)) {
+        return true;
+    }
+    
+    // ID patterns
+    if (/^id$|_id$|^uuid$|_uuid$/.test(normalizedName)) {
+        return true;
+    }
+    
+    // Name patterns
+    if (/name|title|label/.test(normalizedName)) {
+        return true;
+    }
+    
+    // Order/priority patterns
+    if (/order|priority|sort|rank|position|sequence/.test(normalizedName)) {
+        return true;
+    }
+    
+    // Status patterns
+    if (/status|state|active|enabled|visible/.test(normalizedName)) {
+        return true;
+    }
+    
+    // Numeric patterns
+    if (/amount|price|cost|total|count|number|quantity|score|rating/.test(normalizedName)) {
+        return true;
+    }
+    
+    // Default to false for unknown patterns to be conservative
+    return false;
+};
+
+/**
+ * Constructs the relationship path for a column (for logging/debugging)
+ * 
+ * @param {Object} column - Column configuration object
+ * @returns {string} - The relationship path (e.g., "user.profile.name")
+ */
+export const getRelationshipPath = (column) => {
+    if (!Array.isArray(column.id)) {
+        return column.nameFrom || 'unknown';
+    }
+    
+    const relationPath = column.id.join('.');
+    return column.nameFrom ? `${relationPath}.${column.nameFrom}` : relationPath;
+};
+
+/**
+ * Analyzes all relationship columns in a column configuration array
+ * and provides sorting recommendations
+ * 
+ * @param {Array} columns - Array of column configuration objects
+ * @param {Object} options - Options for analysis
+ * @returns {Object} - Analysis results with recommendations
+ */
+export const analyzeRelationshipSorting = (columns, options = {}) => {
+    const results = {
+        totalRelationColumns: 0,
+        sortableRelationColumns: 0,
+        unsortableRelationColumns: 0,
+        recommendations: [],
+        sortableColumns: [],
+        unsortableColumns: []
+    };
+    
+    columns.forEach(column => {
+        if (['relation', 'relationArray'].includes(column.type)) {
+            results.totalRelationColumns++;
+            
+            const isSortable = isRelationshipColumnSortable(column, options);
+            const relationshipPath = getRelationshipPath(column);
+            
+            if (isSortable) {
+                results.sortableRelationColumns++;
+                results.sortableColumns.push({
+                    column,
+                    path: relationshipPath,
+                    reason: 'Matches sortable field pattern'
+                });
+            } else {
+                results.unsortableRelationColumns++;
+                results.unsortableColumns.push({
+                    column,
+                    path: relationshipPath,
+                    reason: 'Does not match sortable patterns or exceeds depth limit'
+                });
+            }
+        }
+    });
+    
+    // Generate recommendations
+    if (results.unsortableRelationColumns > 0) {
+        results.recommendations.push(
+            `Consider adding explicit sortable: true to ${results.unsortableRelationColumns} relationship columns if sorting is needed`
+        );
+    }
+    
+    if (results.sortableRelationColumns > 10) {
+        results.recommendations.push(
+            'Large number of sortable relationship columns detected - consider performance impact'
+        );
+    }
+    
+    return results;
+};
+
+/**
+ * Default configuration for intelligent sorting
+ */
+export const DEFAULT_INTELLIGENT_SORTING_CONFIG = {
+    enableIntelligentSorting: true,
+    maxRelationshipDepth: MAX_RELATIONSHIP_DEPTH,
+    customSortableFields: [],
+    customUnsortableFields: [],
+    respectExplicitSortable: true,
+    logAnalysis: process.env.NODE_ENV === 'development'
+};

package/src/utils/relationshipSortingUtilsSimple.js

@@ -0,0 +1,51 @@
+/**
+ * Simplified version for testing import issues
+ */
+
+export const DEFAULT_INTELLIGENT_SORTING_CONFIG = {
+    enableIntelligentSorting: true,
+    maxRelationshipDepth: 3,
+    customSortableFields: [],
+    customUnsortableFields: [],
+    respectExplicitSortable: true,
+    logAnalysis: false
+};
+
+export const isRelationshipColumnSortable = (column, options = {}) => {
+    // Simple implementation for testing
+    if (options.enableIntelligentSorting === false) {
+        return column.sortable === true;
+    }
+    
+    if (column.hasOwnProperty('sortable')) {
+        return column.sortable === true;
+    }
+    
+    // Basic field name analysis
+    const fieldName = column.nameFrom;
+    if (!fieldName) return false;
+    
+    const sortablePatterns = ['name', 'title', 'email', 'created_at', 'updated_at', 'id'];
+    const unsortablePatterns = ['bio', 'content', 'data', 'notes', 'description'];
+    
+    const normalizedName = fieldName.toLowerCase();
+    
+    if (unsortablePatterns.some(pattern => normalizedName.includes(pattern))) {
+        return false;
+    }
+    
+    if (sortablePatterns.some(pattern => normalizedName.includes(pattern))) {
+        return true;
+    }
+    
+    return false;
+};
+
+export const getRelationshipPath = (column) => {
+    if (!Array.isArray(column.id)) {
+        return column.nameFrom || 'unknown';
+    }
+    
+    const relationPath = column.id.join('.');
+    return column.nameFrom ? `${relationPath}.${column.nameFrom}` : relationPath;
+};