Add search app configuration, views, and templates for advanced filtering functionality

search/README.md

@@ -0,0 +1,106 @@
+# Search & Filter System
+
+A flexible, reusable search and filtering system that can be used across any Django model in the project.
+
+## Features
+
+- Modular filter system with composable mixins
+- HTMX integration for dynamic updates
+- Responsive, accessible filter UI components
+- Automatic filter generation based on model fields
+- Location-based filtering support
+- Flexible template system
+
+## Usage
+
+### Basic Implementation
+
+Add filtering to any ListView by using the `HTMXFilterableMixin`:
+
+```python
+from django.views.generic import ListView
+from search.mixins import HTMXFilterableMixin
+
+class MyModelListView(HTMXFilterableMixin, ListView):
+    model = MyModel
+    template_name = "myapp/mymodel_list.html"
+    search_fields = ['name', 'description']  # Fields to include in text search
+```
+
+### Custom Filters
+
+Add custom filters for specific model needs:
+
+```python
+additional_filters = {
+    'category': ChoiceFilter(choices=MyModel.CATEGORY_CHOICES),
+    'rating': RangeFilter(field_name='average_rating'),
+}
+```
+
+### Template Integration
+
+Extend the base filtered list template:
+
+```html
+{% extends "search/layouts/filtered_list.html" %}
+
+{% block list_actions %}
+<a href="{% url 'myapp:create' %}" class="btn btn-primary">
+    Add New
+</a>
+{% endblock %}
+```
+
+### Custom Result Display
+
+Create a custom results template in `templates/search/partials/mymodel_results.html`:
+
+```html
+<div class="divide-y">
+    {% for object in object_list %}
+    <div class="p-4">
+        <h3>{{ object.name }}</h3>
+        <!-- Custom display logic -->
+    </div>
+    {% endfor %}
+</div>
+```
+
+## Components
+
+### Mixins
+
+- `LocationFilterMixin`: Adds location-based filtering
+- `RatingFilterMixin`: Adds rating range filters
+- `DateRangeFilterMixin`: Adds date range filtering
+
+### Factory Function
+
+Use `create_model_filter` to dynamically create filters:
+
+```python
+MyModelFilter = create_model_filter(
+    model=MyModel,
+    search_fields=['name', 'description'],
+    mixins=[LocationFilterMixin, RatingFilterMixin],
+    additional_filters={...}
+)
+```
+
+### Template Tags
+
+- `model_name`: Get human-readable model name
+- `groupby_filters`: Group filter fields logically
+- `add_field_classes`: Add Tailwind classes to form fields
+
+## Performance Considerations
+
+- Use `select_related` and `prefetch_related` in your querysets
+- Index commonly filtered fields
+- Consider caching for static filter choices
+- Use the built-in pagination
+
+## Examples
+
+See `search/examples.py` for detailed implementation examples across different model types.