advanced-filter-system 1.0.6 → 1.0.8

package/README.md

@@ -1,324 +1,560 @@
-# Advanced Filter System
-
-A powerful and flexible JavaScript library for filtering DOM elements with comprehensive search, sorting, and filtering capabilities.
+# Advanced Filter System (AFS)
+
+A powerful and flexible vanilla JavaScript filtering system that provides advanced filtering, searching, sorting, and pagination capabilities for DOM elements. Zero dependencies, lightweight, and highly customizable.
+
+[Live Demo](https://misits.github.io/advanced-filter-system) | [NPM Package](https://www.npmjs.com/package/advanced-filter-system)
+
+## Table of Contents
+
+- [Advanced Filter System (AFS)](#advanced-filter-system-afs)
+  - [Table of Contents](#table-of-contents)
+  - [Features](#features)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+    - [HTML Structure](#html-structure)
+    - [JavaScript Initialization](#javascript-initialization)
+  - [Basic Usage](#basic-usage)
+    - [Filtering](#filtering)
+    - [Searching](#searching)
+    - [Sorting](#sorting)
+    - [Pagination](#pagination)
+  - [Advanced Usage](#advanced-usage)
+    - [Custom Animation](#custom-animation)
+    - [Filter Groups](#filter-groups)
+    - [Custom Sorting](#custom-sorting)
+    - [URL State Management](#url-state-management)
+  - [Components](#components)
+    - [Filter System](#filter-system)
+    - [Range Filter](#range-filter)
+    - [Date Filter](#date-filter)
+    - [Search System](#search-system)
+    - [Sort System](#sort-system)
+    - [Pagination](#pagination-1)
+    - [URL Manager](#url-manager)
+  - [Styling \& Theming](#styling--theming)
+    - [Built-in Themes](#built-in-themes)
+    - [Custom Themes](#custom-themes)
+    - [Animations](#animations)
+  - [Browser Support](#browser-support)
+  - [TypeScript Support](#typescript-support)
+  - [Contributing](#contributing)
+  - [License](#license)
 
 ## Features
 
-### Core Filtering
-
-- 🔍 Multiple filter types (category, price, status, etc.)
-- 🔀 Flexible filter modes (AND/OR logic)
-- 👥 Filter groups with independent logic
-- 📊 Multi-criteria sorting
-- 🔎 Text search with debouncing
-- 📱 Responsive design support
-- ✨ Smooth animations and transitions
-- 🔢 Results counter
-- 🔗 URL state management
-
-### Advanced Features
-
-- 📑 Pagination support
-- 📊 Range-based filtering
-- 💾 Filter presets (save/load)
-- 📈 Analytics integration
-- ⌨️ Keyboard navigation
-- 🔄 Custom sort comparators
-- 🎯 Event system
-- 📱 Responsive breakpoints
-- 🔍 Multiple search keys
-- 🎨 Customizable animations
+- 🔍 **Advanced Filtering**
+  - Multiple filter types (text, range, date)
+  - AND/OR logic
+  - Filter groups
+  - Dynamic filters
+- 🔎 **Smart Search**
+  - Real-time search
+  - Multiple fields
+  - Highlight matches
+  - Minimum character threshold
+- ↕️ **Flexible Sorting**
+  - Multi-column sort
+  - Custom comparators
+  - Auto-detect data types
+- 📄 **Pagination**
+  - Dynamic page size
+  - Custom controls
+  - Scroll to top
+- 🔗 **URL Management**
+  - State persistence
+  - Browser history support
+  - Shareable URLs
+- ⚡ **Performance**
+  - Debounced updates
+  - Efficient DOM manipulation
+  - Minimal reflows
+- 🎨 **Rich Animation**
+  - 15+ built-in animations
+  - Custom transitions
+  - Hardware acceleration
+- 💾 **State Management**
+  - Centralized state
+  - Import/Export
+  - Undo/Redo support
+- 🎯 **Event System**
+  - Rich event API
+  - Custom events
+  - Event debugging
 
 ## Installation
 
-### Via npm
-
 ```bash
+# NPM
 npm install advanced-filter-system
-```
 
-### Via yarn
-
-```bash
+# Yarn
 yarn add advanced-filter-system
+
+# PNPM
+pnpm add advanced-filter-system
 ```
 
-### Direct Download
+Or include via CDN:
 
-Download `src/AFS.js` from this repository and include it in your project.
+```html
+<script src="https://unpkg.com/advanced-filter-system@1.0.8/dist/AFS.min.js"></script>
+```
 
-## Usage Guide
+## Quick Start
 
-### Basic Setup
+### HTML Structure
 
 ```html
-<div class="filter-container">
-    <!-- Filter buttons -->
-    <div class="filters">
-        <button class="btn-filter" data-filter="*">All</button>
-        <button class="btn-filter" data-filter="category:web">Web</button>
-        <button class="btn-filter" data-filter="category:design">Design</button>
-    </div>
+<!DOCTYPE html>
+<html>
+<head>
+    <title>AFS Demo</title>
+</head>
+<body>
+    <!-- Counter -->
+    <div class="filter-counter"></div>
 
-    <!-- Optional components -->
+    <!-- Search -->
     <input type="text" class="filter-search" placeholder="Search...">
-    <div class="filter-counter"></div>
+    
+    <!-- Filter Buttons -->
+    <div class="filter-buttons">
+        <button class="btn-filter" data-filter="all">All</button>
+        <button class="btn-filter" data-filter="category1">Category 1</button>
+        <button class="btn-filter" data-filter="category2">Category 2</button>
+    </div>
+
+    <!-- Sort Buttons -->
+    <div class="sort-buttons">
+        <button class="btn-sort" data-sort-key="price">
+            Price <span class="sort-direction">↑</span>
+        </button>
+        <button class="btn-sort" data-sort-key="date">
+            Date <span class="sort-direction">↑</span>
+        </button>
+    </div>
 
-    <!-- Filterable items -->
-    <div class="items">
+    <!-- Range Filter -->
+    <div id="price-range"></div>
+
+    <!-- Date Filter -->
+    <div id="date-filter"></div>
+
+    <!-- Items Container -->
+    <div id="items-container">
         <div class="filter-item" 
-             data-categories="category:web" 
-             data-title="Project 1"
-             data-price="599"
-             data-year="2023">
-            <!-- Content -->
+             data-categories="category1" 
+             data-price="99.99"
+             data-date="2024-03-15"
+             data-title="Item 1"
+             data-description="Description for item 1">
+            <h3>Item 1</h3>
+            <p>$99.99</p>
+            <p>March 15, 2024</p>
         </div>
+        <!-- More items... -->
     </div>
-</div>
+
+    <!-- Pagination -->
+    <div class="pagination-container"></div>
+
+    <!-- Scripts -->
+    <script src="https://unpkg.com/advanced-filter-system@1.0.8/dist/AFS.min.js"></script>
+    <script>
+        const afs = AFS.createAFS({
+            containerSelector: '#items-container',
+            itemSelector: '.filter-item',
+            searchInputSelector: '.filter-search',
+            filterButtonSelector: '.btn-filter',
+            sortButtonSelector: '.btn-sort',
+            counterSelector: '.filter-counter',
+            debug: true,
+            responsive: true,
+            preserveState: true,
+            animation: {
+                type: 'fade',
+                duration: 300
+            },
+            pagination: {
+                enabled: true,
+                itemsPerPage: 10
+            }
+        });
+
+        // Add range filter
+        afs.rangeFilter.addRangeSlider({
+            key: 'price',
+            container: document.querySelector('#price-range'),
+            min: 0,
+            max: 1000,
+            step: 10
+        });
+
+        // Add date filter
+        afs.dateFilter.addDateRange({
+            key: 'date',
+            container: document.querySelector('#date-filter')
+        });
+    </script>
+</body>
+</html>
 ```
 
-### Basic JavaScript Initialization
+### JavaScript Initialization
+
+Using ES modules:
 
 ```javascript
-import { AFS } from 'advanced-filter-system';
+import { createAFS } from 'advanced-filter-system';
 
-const filter = new AFS({
-    containerSelector: '.filter-container',
+const afs = createAFS({
+    containerSelector: '#items-container',
     itemSelector: '.filter-item',
-    filterButtonSelector: '.btn-filter'
+    debug: true,
+    animation: {
+        type: 'fade',
+        duration: 300
+    }
 });
 ```
 
-## Feature Documentation
+## Basic Usage
 
-### 1. Filter Modes
+### Filtering
 
 ```javascript
-// Set filter logic mode
-filter.setFilterMode('AND'); // Items must match all selected filters
-filter.setFilterMode('OR');  // Items must match any selected filter
+// HTML
+<button class="btn-filter" data-filter="category1">Category 1</button>
+<button class="btn-filter" data-filter="category2">Category 2</button>
 
-// Alternative method
-filter.setLogic('AND');
-filter.setLogic(true); // true = AND, false = OR
-```
-
-### 2. Filter Groups
+<div class="filter-item" data-categories="category1,category2">
+    Item content
+</div>
 
-Groups allow complex filtering logic with independent AND/OR operations.
+// JavaScript
+// Set filter mode
+afs.filter.setFilterMode('AND'); // or 'OR'
 
-```javascript
-// Add filter groups
-filter.addFilterGroup('categories', ['category:tech', 'category:web'], 'OR');
-filter.addFilterGroup('price', ['price:low', 'price:medium'], 'AND');
+// Add filter programmatically
+afs.filter.addFilter('category1');
 
-// Set how groups combine
-filter.setGroupMode('AND'); // Items must match all groups
-filter.setGroupMode('OR');  // Items must match any group
+// Remove filter
+afs.filter.removeFilter('category1');
 
-// Remove groups
-filter.removeFilterGroup('price');
+// Clear all filters
+afs.filter.clearAllFilters();
 ```
 
-### 3. Search Functionality
+### Searching
 
 ```javascript
+// HTML
+<input type="text" class="filter-search">
+<div class="filter-item" 
+     data-title="Product Name" 
+     data-description="Product description">
+    Item content
+</div>
+
+// JavaScript
 // Configure search
-const filter = new AFS({
-    searchInputSelector: '.filter-search',
-    searchKeys: ['title', 'description'], // Data attributes to search in
-    debounceTime: 300 // Milliseconds
+afs.search.updateConfig({
+    searchKeys: ['title', 'description'],
+    minSearchLength: 2,
+    highlightMatches: true,
+    debounceTime: 300
 });
 
-// Programmatic search
-filter.search('query');
+// Perform search programmatically
+afs.search.search('query');
+
+// Clear search
+afs.search.clearSearch();
 ```
 
-### 4. Sorting
+### Sorting
 
 ```javascript
-// Multi-criteria sorting
-filter.sortMultiple([
-    { key: 'year', direction: 'desc' },
-    { key: 'title', direction: 'asc' }
-]);
+// HTML
+<button class="btn-sort" data-sort-key="price">Sort by Price</button>
+<button class="btn-sort" data-sort-key="date">Sort by Date</button>
 
-// Custom comparator
-filter.sortWithComparator('price', (a, b) => parseFloat(a) - parseFloat(b));
-```
-
-### 5. Range Filtering
+<div class="filter-item" data-price="99.99" data-date="2024-03-15">
+    Item content
+</div>
 
-```javascript
-// Filter by numeric range
-filter.addRangeFilter('price', 100, 500);
-```
+// JavaScript
+// Basic sort
+afs.sort.sort('price', 'asc');
 
-### 6. Pagination
+// Multiple criteria sort
+afs.sort.sortMultiple([
+    { key: 'category', direction: 'asc' },
+    { key: 'price', direction: 'desc' }
+]);
 
-```javascript
-// Enable pagination
-filter.setPagination(12); // 12 items per page
+// Reset sort
+afs.sort.reset();
 ```
 
-### 7. State Management
+### Pagination
 
 ```javascript
-// URL State
-// Automatically managed, creates URLs like:
-// ?category=web,design&price=low,medium&search=project
+// HTML
+<div class="pagination-container"></div>
+
+// JavaScript
+// Configure pagination
+const afs = createAFS({
+    pagination: {
+        enabled: true,
+        itemsPerPage: 10,
+        maxButtons: 7,
+        showPrevNext: true,
+        scrollToTop: true
+    }
+});
 
-// Export/Import State
-const state = filter.exportState();
-filter.importState(state);
+// Navigate pages
+afs.pagination.goToPage(2);
 
-// Presets
-filter.savePreset('myFilters');
-filter.loadPreset('myFilters');
+// Change items per page
+afs.pagination.setItemsPerPage(20);
+
+// Get pagination info
+const info = afs.pagination.getPageInfo();
 ```
 
-### 8. Analytics
+## Advanced Usage
+
+### Custom Animation
 
 ```javascript
-filter.enableAnalytics((data) => {
-    console.log('Filter event:', data);
-    // { type: 'filter', filters: [...], visibleItems: 10, timestamp: '...' }
+// Custom animation configuration
+const afs = createAFS({
+    animation: {
+        type: 'custom',
+        duration: 500,
+        easing: 'cubic-bezier(0.4, 0, 0.2, 1)',
+        inClass: 'my-enter',
+        outClass: 'my-leave'
+    }
 });
+
+// CSS
+.my-enter {
+    opacity: 0;
+    transform: scale(0.9);
+}
+
+.my-enter.my-enter-active {
+    opacity: 1;
+    transform: scale(1);
+    transition: opacity 500ms cubic-bezier(0.4, 0, 0.2, 1),
+                transform 500ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+
+.my-leave {
+    opacity: 1;
+    transform: scale(1);
+}
+
+.my-leave.my-leave-active {
+    opacity: 0;
+    transform: scale(0.9);
+    transition: opacity 500ms cubic-bezier(0.4, 0, 0.2, 1),
+                transform 500ms cubic-bezier(0.4, 0, 0.2, 1);
+}
 ```
 
-### 9. Responsive Design
+### Filter Groups
 
 ```javascript
-filter.setResponsiveOptions({
-    '768': {
-        animationDuration: 200,
-        itemsPerPage: 8
-    },
-    '480': {
-        animationDuration: 0,
-        itemsPerPage: 4
-    }
+// Create filter groups with different operators
+afs.filter.addFilterGroup('price', {
+    ranges: [[0, 100], [101, 500], [501, 1000]],
+    operator: 'OR'
+});
+
+afs.filter.addFilterGroup('categories', {
+    filters: ['electronics', 'books'],
+    operator: 'AND'
 });
+
+// Set group mode
+afs.filter.setGroupMode('AND');
+
+// Remove group
+afs.filter.removeFilterGroup('price');
 ```
 
-### 10. Animation Configuration
+### Custom Sorting
 
 ```javascript
-filter.setAnimationOptions({
-    duration: 300,
-    type: 'ease-out'
+// Custom comparator for special sorting needs
+afs.sort.sortWithComparator('title', (a, b) => {
+    // Sort by last word
+    const getLastWord = str => str.split(' ').pop();
+    const lastA = getLastWord(a);
+    const lastB = getLastWord(b);
+    return lastA.localeCompare(lastB);
+});
+
+// Sort with multiple languages
+afs.sort.sortWithComparator('title', (a, b) => {
+    return a.localeCompare(b, 'es', { 
+        sensitivity: 'base',
+        numeric: true
+    });
 });
 ```
 
-### 11. Event System
+### URL State Management
 
 ```javascript
-filter.on('filter', (data) => {
-    console.log('Filter changed:', data);
+// Enable URL state
+const afs = createAFS({
+    urlStateEnabled: true,
+    urlStateKey: 'filter'
 });
-```
 
-### 12. Keyboard Navigation
+// Handle state changes
+afs.on('urlStateLoaded', (state) => {
+    console.log('State loaded:', state);
+});
 
-```javascript
-filter.enableKeyboardNavigation();
+// Manual control
+afs.urlManager.updateURL();
+afs.urlManager.loadFromURL();
+afs.urlManager.clearURL();
+
+// Get specific parameter
+const searchQuery = afs.urlManager.getParam('search');
 ```
 
-### 13. Sort asc/desc
+## Components
 
-```javascript
-filter.sortWithComparator('price', (a, b) => parseFloat(a) - parseFloat(b), 'asc');
+Each component can be used independently or as part of the AFS system.
 
-// or
+### Filter System
+See [Filter Documentation](docs/filter.md)
 
-filter.sortWithOrder('price');
-```
+### Range Filter
+See [Range Filter Documentation](docs/range-filter.md)
 
-### 13. Shuffle
+### Date Filter
+See [Date Filter Documentation](docs/date-filter.md)
 
-```javascript
-filter.shuffle();
-```
+### Search System
+See [Search Documentation](docs/search.md)
+
+### Sort System
+See [Sort Documentation](docs/sort.md)
+
+### Pagination
+See [Pagination Documentation](docs/pagination.md)
 
-## Browser Compatibility
+### URL Manager
+See [URL Manager Documentation](docs/url-manager.md)
 
-- ✅ Chrome
-- ✅ Firefox
-- ✅ Safari
-- ✅ Edge
-- ✅ IE11 (with polyfills)
+## Styling & Theming
 
-## Full Configuration Options
+### Built-in Themes
 
 ```javascript
-const filter = new AFS({
-    // Required
-    containerSelector: '.filter-container',
-    itemSelector: '.filter-item',
-    filterButtonSelector: '.btn-filter',
-    
-    // Optional (with defaults)
-    searchInputSelector: '.filter-search',
-    counterSelector: '.filter-counter',
-    activeClass: 'active',
-    hiddenClass: 'hidden',
-    animationDuration: 300,
-    filterMode: 'OR',
-    searchKeys: ['title'],
-    debounceTime: 300,
-    debug: false, // Enable console logs
-    logLevel: 'info', // 'info', 'warn', 'error', 'debug'
+const afs = createAFS({
+    styles: {
+        colors: {
+            primary: '#3b82f6',
+            background: '#f3f4f6',
+            text: '#1f2937'
+        }
+    }
 });
 ```
 
-## API Methods Reference
+### Custom Themes
 
-### Filter Management
+```javascript
+const afs = createAFS({
+    styles: {
+        colors: {
+            primary: '#custom-color',
+            background: '#custom-bg',
+            text: '#custom-text'
+        },
+        components: {
+            button: {
+                borderRadius: '8px',
+                padding: '8px 16px'
+            },
+            input: {
+                borderWidth: '2px',
+                focusRing: '3px'
+            }
+        }
+    }
+});
+```
 
-- `addFilter(type, value)`
-- `removeFilter(type, value)`
-- `getActiveFiltersByType(type)`
-- `setFilterMode(mode)`
-- `resetFilters()`
+### Animations
 
-### Filter Groups
+```javascript
+const afs = createAFS({
+    animation: {
+        type: 'fade', // or 'slide', 'scale', etc.
+        duration: 300,
+    }
+});
+```
 
-- `addFilterGroup(groupId, filters, operator)`
-- `removeFilterGroup(groupId)`
-- `setGroupMode(mode)`
+## Browser Support
 
-### Search and Sort
+- Chrome (last 2 versions)
+- Firefox (last 2 versions)
+- Safari (last 2 versions)
+- Edge (last 2 versions)
+- iOS Safari (last 2 versions)
+- Android Chrome (last 2 versions)
 
-- `search(query)`
-- `sortMultiple(criteria)`
-- `sortWithComparator(key, comparator)`
-- `addRangeFilter(key, min, max)`
-- `shuffle()`
-- `sortWithOrder(key)`
+Required browser features:
 
-### State Management
+- CSS Transitions
+- Flexbox
+- CSS Grid (optional)
+- History API
+- localStorage
+- MutationObserver
 
-- `exportState()`
-- `importState(state)`
-- `savePreset(presetName)`
-- `loadPreset(presetName)`
+## TypeScript Support
 
-### UI and Display
+Full TypeScript support with type definitions included:
 
-- `setPagination(itemsPerPage)`
-- `setAnimationOptions(options)`
-- `setResponsiveOptions(breakpoints)`
-- `enableKeyboardNavigation()`
+```typescript
+import { createAFS, AFSOptions } from 'advanced-filter-system';
 
-### Events and Analytics
+const options: AFSOptions = {
+    containerSelector: '#items-container',
+    itemSelector: '.filter-item'
+};
 
-- `on(eventName, callback)`
-- `enableAnalytics(callback)`
+const afs = createAFS(options);
+```
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit issues and pull requests.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details on:
+
+1. Setting up the development environment
+2. Coding standards
+3. Pull request process
+4. Bug reporting
+5. Feature requests
 
 ## License
 
-MIT License - feel free to use this in your projects!
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+Made with ♥ by [misits](https://github.com/misits)