fix: Magic shelf filtering bugs and add date format validation

Filter/Query Fixes:
- Fix "is_empty" operator on relationship fields (Series, Publisher, Author, Tag, Language)
  Returns books with no related records using ~relationship.any() instead of broken
  relationship.any(column == None) which always returned false
- Fix Description field completely broken - was pointing to Books.comments relationship
  instead of Comments.text column. Updated FIELD_MAP and RELATIONSHIP_MAP
- Add special handling for is_empty/is_null operators on relationships to check existence
  rather than value comparison

Date Format UI Improvements:
- Add dynamic date format hint box (styled like preview results)
- Automatically shows when Published Date or Date Added fields are used in rules
- Displays required format: YYYY-MM-DD with example
- Hides automatically when no date fields are present
- Positioned above preview section for better visibility

Operator Improvements:
- Handle is_empty and is_not_empty correctly for all relationship types
- Preserve existing operator behavior for value-based comparisons
- Add defensive checks in build_filter_from_rule for relationship operators

Files Changed:
- cps/magic_shelf.py: Fix relationship field handling and Description mapping
- cps/templates/magic_shelf_edit.html: Add date hint UI and show/hide logic
- cps/static/css/query_builder.css: Add date-format-hint styling

Resolves issues where:
- Series/Publisher "is empty" queries returned 0 results
- Description filter threw "Invalid rules format" error
- Users had no guidance on required date format (YYYY-MM-DD)
- Relationship fields checked null values instead of existence

Author: crocodilestick

cps/magic_shelf.py

@@ -139,7 +139,7 @@
     'timestamp': (db.Books, 'timestamp'),
     'has_cover': (db.Books, 'has_cover'),
     'series_index': (db.Books, 'series_index'),
-    'comments': (db.Books, 'comments'),
+    'comments': (db.Comments, 'text'),  # Fixed: Points to actual text column, not relationship
     'read_status': ('custom_column', 'read_status'),  # Special handling - uses config.config_read_column
     'hardcover_id': ('identifier', 'hardcover-id'),  # Special handling - checks Identifiers table
 }
@@ -182,6 +182,7 @@
     'publisher': 'publishers',
     'rating': 'ratings',
     'language': 'languages',
+    'comments': 'comments',  # For description field - requires join to Comments table
 }
 
 def build_filter_from_rule(rule, user_id=None):
@@ -308,10 +309,17 @@ def build_filter_from_rule(rule, user_id=None):
     relationship_name = RELATIONSHIP_MAP.get(field_name)
     try:
         if relationship_name:
-            filter_expr = operator(column, value)
-            if filter_expr is None:
-                return None
-            return getattr(db.Books, relationship_name).any(filter_expr)
+            # Special handling for is_empty/is_null on relationships:
+            # These check for absence of relationships, not null values in related records
+            if operator_name in ['is_empty', 'is_null']:
+                return ~getattr(db.Books, relationship_name).any()
+            elif operator_name in ['is_not_empty', 'is_not_null']:
+                return getattr(db.Books, relationship_name).any()
+            else:
+                filter_expr = operator(column, value)
+                if filter_expr is None:
+                    return None
+                return getattr(db.Books, relationship_name).any(filter_expr)
         else:
             filter_expr = operator(column, value)
             return filter_expr

cps/templates/magic_shelf_edit.html

@@ -63,6 +63,23 @@
     border: 1px solid #5a2d2d;
     color: #ff9090;
 }
+
+/* Date Format Help Tooltips */
+.date-format-help {
+    margin-top: 5px;
+    padding: 8px 12px;
+    background: #21252b;
+    border: 1px solid #3e444c;
+    border-radius: 4px;
+    color: #90b8e0;
+    font-size: 12px;
+    display: none;
+}
+.date-format-help.warning {
+    background: #3a2e1e;
+    border-color: #5a4d2d;
+    color: #ffcc66;
+}
 .preview-book-list {
     list-style: none;
     padding-left: 0;
@@ -231,6 +248,31 @@
     background: #292d32;
     padding: 0.5rem;
     padding-inline: 1rem;
+}
+
+/* Date format hint styling - matches preview results box */
+.date-format-hint {
+    display: none;
+    margin-top: 1rem;
+    padding: 1rem 1.5rem;
+    background: #1a1d21;
+    border: 1px solid #3a3d41;
+    border-radius: 4px;
+    border-left: 4px solid #5bc0de;
+}
+
+.date-format-hint .hint-icon {
+    color: #5bc0de;
+    margin-right: 0.5rem;
+}
+
+.date-format-hint .hint-format {
+    color: #cc7b19;
+    font-weight: bold;
+}
+
+.date-format-hint.show {
+    display: block;
     border-radius: 4px;
     border: 1px solid #3e444c;
 }
@@ -371,6 +413,12 @@ <h4>
                     </h4>
                     <div id="builder"></div>
 
+                    <!-- Date Format Hint (shown when date fields are used) -->
+                    <div id="date-format-hint" class="date-format-hint">
+                        <span class="glyphicon glyphicon-info-sign hint-icon"></span>
+                        <strong>Date Format:</strong> Use <span class="hint-format">YYYY-MM-DD</span> format for date fields (e.g., 2024-01-15)
+                    </div>
+                    
                     <!-- Preview Results -->
                     <div id="preview-results" class="preview-results">
                         <h5><span class="glyphicon space glyphicon-eye-open"></span> Preview Results</h5>
@@ -594,12 +642,84 @@ <h5><span class="glyphicon space glyphicon-eye-open"></span> Preview Results</h5
 
     var rules = {{ rules_json|safe }};
 
+    // Date validation helper
+    function isValidDate(dateString) {
+        if (!dateString) return true; // Empty is valid (will be handled by is_empty operator)
+        var regex = /^\d{4}-\d{2}-\d{2}$/;
+        if (!regex.test(dateString)) return false;
+        var date = new Date(dateString);
+        var timestamp = date.getTime();
+        if (typeof timestamp !== 'number' || Number.isNaN(timestamp)) return false;
+        return date.toISOString().startsWith(dateString);
+    }
+
+    // Show/hide date format hint based on rules
+    function checkForDateFields() {
+        var hasDateField = false;
+        
+        // Check all filter dropdowns for date fields
+        $('#builder .rule-filter-container select').each(function() {
+            var filterId = $(this).val();
+            if (filterId === 'pubdate' || filterId === 'timestamp') {
+                hasDateField = true;
+                return false; // break out of each loop
+            }
+        });
+        
+        if (hasDateField) {
+            $('#date-format-hint').addClass('show');
+        } else {
+            $('#date-format-hint').removeClass('show');
+        }
+    }
+
     $('#builder').queryBuilder({
         plugins: ['bt-tooltip-errors'],
         filters: fields,
         operators: operators,
         rules: rules
     });
+    
+    // Check for date fields on initialization and after changes
+    $('#builder').on('afterCreateRuleInput.queryBuilder afterUpdateRuleFilter.queryBuilder afterUpdateRuleValue.queryBuilder afterDeleteRule.queryBuilder afterUpdateRuleOperator.queryBuilder', function(e) {
+        setTimeout(function() {
+            checkForDateFields();
+        }, 100);
+        
+        // Validate date inputs
+        $(this).find('input[type="text"]').each(function() {
+            var $input = $(this);
+            var $rule = $input.closest('.rule-container');
+            var filterId = $rule.find('.rule-filter-container select').val();
+            
+            if (filterId === 'pubdate' || filterId === 'timestamp') {
+                $input.off('blur.dateValidation').on('blur.dateValidation', function() {
+                    var value = $(this).val();
+                    if (value && !isValidDate(value)) {
+                        $(this).css('border-color', '#d9534f');
+                        if (!$(this).next('.date-error').length) {
+                            $(this).after('<div class="date-error" style="color: #d9534f; font-size: 12px; margin-top: 4px;">Invalid format. Use YYYY-MM-DD (e.g., 2024-01-15)</div>');
+                        }
+                    } else {
+                        $(this).css('border-color', '');
+                        $(this).next('.date-error').remove();
+                    }
+                });
+            }
+        });
+    });
+    
+    // Also listen for direct changes on filter dropdowns
+    $('#builder').on('change', '.rule-filter-container select', function() {
+        setTimeout(function() {
+            checkForDateFields();
+        }, 100);
+    });
+    
+    // Initial check
+    setTimeout(function() {
+        checkForDateFields();
+    }, 100);
 
     // Preview Rules Functionality
     $('#preview-btn').on('click', function() {