# Comparison Table Filters - Implementation Documentation

**Last Updated:** 2025-01-27

## Overview

The comparison table filter system provides comprehensive filtering capabilities for the feature comparison table, allowing users to filter by search term, categories, plans, and differences-only mode.

## Filter Types

### 1. Search Filter

- **Parameter:** `search`
- **Type:** Text input
- **Functionality:** Searches feature names (case-insensitive)
- **Debounce:** 500ms
- **Keyboard Shortcuts:**
  - `Enter` - Apply filter immediately
  - `Escape` - Clear search
  - `Ctrl+F` / `Cmd+F` - Focus search input

### 2. Category Filter

- **Parameter:** `categories` (comma-separated)
- **Type:** Multiple checkboxes
- **Functionality:** Filters features by category
- **Default:** All categories selected
- **Helper Buttons:**
  - "Alle auswählen" - Select all categories
  - "Alle abwählen" - Deselect all categories

### 3. Plan Filter

- **Parameter:** `plans` (comma-separated)
- **Type:** Multiple checkboxes
- **Functionality:** Filters visible plan columns and features
- **Default:** All plans selected
- **Plans:** starter, plus, pro, enterprise

### 4. Differences Only

- **Parameter:** `differences` (value: "1")
- **Type:** Single checkbox
- **Functionality:** Shows only features that differ between plans

## URL Parameters

All filters are stored in URL parameters for shareability and browser history:

- `?search=zeiterfassung` - Search for "zeiterfassung"
- `?categories=schichtplan,zeiterfassung` - Filter by categories
- `?plans=pro,enterprise` - Show only Pro and Enterprise columns
- `?differences=1` - Show only differences
- Combined: `?search=app&categories=schichtplan&plans=pro&differences=1`

## Implementation Files

### PHP Files

- `v2/sections/comparison-table-modern.php` - Filter UI structure
- `v2/sections/comparison-table-category-view.php` - Category view with filtering
- `v2/sections/comparison-table-plan-view.php` - Plan view with filtering
- `v2/helpers/comparison-table-data.php` - Filter helper functions

### JavaScript Files

- `v2/js/pricing-page.js` - Filter logic and event handlers

### CSS Files

- `v2/css/pricing-page.css` - Filter styling and animations

## Key Functions

### PHP Functions

#### `filterComparisonCategories($categoryIds)`

Filters categories by IDs.

#### `filterComparisonByPlans($categories, $selectedPlans)`

Filters categories to show only features available in selected plans.

#### `filterComparisonDifferencesOnly($categories)`

Filters to show only features that differ between plans.

#### `validatePlanIds($planIds)`

Validates and sanitizes plan IDs.

### JavaScript Functions

#### `updateComparisonFilters()`

Updates URL parameters and reloads page with new filters. Includes:

- Loading indicator
- Scroll position preservation
- Duplicate prevention

#### `clearComparisonFilters()`

Clears all filters and reloads page.

#### `syncFilterUIWithURL()`

Syncs filter UI elements with URL parameters on page load.

#### `countActiveFilters()`

Counts number of active filters.

#### `countVisibleFeatures()`

Counts number of visible features in the table.

#### `updateFilterCount()`

Updates the filter results count display.

#### `restoreScrollPosition()`

Restores scroll position after page reload.

## User Experience Features

### Loading States

- Loading spinner appears during filter application
- Smooth transitions for filter changes

### Visual Feedback

- Active filter indicators (highlighted checkboxes)
- Hover effects on all interactive elements
- Filter count display showing visible features

### Accessibility

- Full keyboard navigation support
- ARIA labels on all interactive elements
- Screen reader compatible
- Focus indicators

### Responsive Design

- Mobile: 2-column category grid
- Tablet: 3-4 column category grid
- Desktop: 6-column category grid
- Horizontal scroll for table on mobile

## Filter Logic Flow

1. User interacts with filter (checkbox, search, etc.)
2. Event listener triggers `updateComparisonFilters()`
3. Function collects all filter values
4. Updates URL parameters
5. Shows loading indicator
6. Saves scroll position
7. Reloads page with new URL
8. PHP reads URL parameters
9. Applies filters to data
10. Renders filtered table
11. JavaScript restores scroll position
12. Updates filter count display

## Edge Cases Handled

- Empty search term (removed from URL)
- All categories selected (removed from URL)
- All plans selected (removed from URL)
- No results found (displays "Keine Ergebnisse gefunden")
- Multiple simultaneous filter updates (prevented)
- Browser back/forward navigation (filters preserved in URL)

## Performance Considerations

- Debounced search input (500ms)
- Server-side filtering (no client-side data processing)
- Static caching in PHP helpers
- Minified CSS and JavaScript
- Efficient DOM queries

## Testing Checklist

- [ ] Search filter works
- [ ] Category filter works (single and multiple)
- [ ] Plan filter works in category view
- [ ] Plan filter works in plan view
- [ ] Differences-only toggle works
- [ ] Clear filters button works
- [ ] Multiple filters work together
- [ ] URL parameters are correct
- [ ] Browser back/forward works
- [ ] Scroll position is preserved
- [ ] Loading indicator appears
- [ ] Filter count displays correctly
- [ ] Keyboard navigation works
- [ ] Mobile responsive design works
- [ ] No horizontal overflow

## Maintenance Notes

### Adding New Filter Types

1. Add filter UI element in `comparison-table-modern.php`
2. Add event listener in `initializeComparisonFilters()`
3. Add parameter handling in `updateComparisonFilters()`
4. Add PHP filtering logic in view files
5. Update `countActiveFilters()` function
6. Add CSS styling if needed
7. Update documentation

### Modifying Filter Logic

- Filter logic is primarily in PHP for performance
- JavaScript handles UI updates and URL management
- Always test with multiple filter combinations
- Ensure URL parameters are properly encoded/decoded

## Known Limitations

- Page reload required for filtering (no AJAX)
- Filter state not preserved in session storage (only URL)
- Plan filtering in category view hides columns but doesn't filter features by availability

## Future Enhancements

- AJAX-based filtering (no page reload)
- Filter presets/saved filters
- Export filtered results
- Analytics tracking for filter usage
- Client-side filtering option for instant feedback