micro-sidebar 1.2.2__py3-none-any.whl → 2.2.0__py3-none-any.whl

{micro_sidebar-1.2.2.dist-info → micro_sidebar-2.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: micro-sidebar
-Version: 1.2.2
+Version: 2.2.0
 Summary: A Reusable RTL Django Sidebar App
 Home-page: https://github.com/debeski/micro-sidebar
 Author: DeBeski
@@ -66,6 +66,119 @@ Requires-Dist: Django (>=5.1)
     ]
     ```
 
+## Auto-Discovery Mode (New in v2.0.0)
+
+The sidebar can **automatically discover** your list views and generate navigation items!
+
+### Setup
+
+1. **Add context processor** to `settings.py`:
+    ```python
+    TEMPLATES = [{
+        'OPTIONS': {
+            'context_processors': [
+                ...
+                'sidebar.context_processors.sidebar_context',
+            ],
+        },
+    }]
+    ```
+
+2. **Use in your sidebar template:**
+    ```html
+    {% extends "sidebar/main.html" %}
+    {% load sidebar_tags %}
+
+    {% block items %}
+        {% auto_sidebar %}
+    {% endblock %}
+    ```
+
+That's it! The sidebar will automatically find all URLs with `list` in their name (e.g., `decree_list`), match them to models, and display `verbose_name_plural` as labels.
+
+### Configuration (Optional)
+
+Add to `settings.py`:
+```python
+SIDEBAR_AUTO = {
+    'ENABLED': True,                    # Enable auto-discovery
+    'URL_PATTERNS': ['list'],           # Keywords to match in URL names
+    'EXCLUDE_APPS': ['admin', 'auth'],  # Apps to exclude
+    'EXCLUDE_MODELS': [],               # Specific models to exclude
+    'CACHE_TIMEOUT': 3600,              # Cache timeout in seconds
+    'DEFAULT_ICON': 'bi-list',          # Default Bootstrap icon
+    'DEFAULT_ITEMS': {},                # See "Default Items" section below
+    'EXTRA_ITEMS': {},                  # See "Extra Items" section below
+}
+```
+
+### Default Items Configuration
+
+Use `DEFAULT_ITEMS` to customize auto-discovered items (labels, icons, ordering) without modifying your models:
+
+```python
+SIDEBAR_AUTO = {
+    # ...
+    'DEFAULT_ITEMS': {
+        'decree_list': {          # Key is the URL name
+            'label': 'Decisions', # Override display label
+            'icon': 'bi-gavel',   # Override icon
+            'order': 10,          # Sort order (lower = first)
+        },
+        'incoming_list': {
+            'order': 20,          # Only setting order
+        }
+    }
+}
+```
+
+Items not in `DEFAULT_ITEMS` will use defaults:
+- **Label**: Model's `verbose_name_plural`
+- **Icon**: `DEFAULT_ICON`
+- **Order**: 100
+
+### Extra Items (Non-Model URLs)
+
+For URLs that don't map to a model (e.g., management pages), use `EXTRA_ITEMS`:
+
+```python
+SIDEBAR_AUTO = {
+    # ... other config ...
+    'EXTRA_ITEMS': {
+        'الإدارة': {  # Group name (accordion header)
+            'icon': 'bi-gear',
+            'items': [
+                {
+                    'url_name': 'manage_sections',
+                    'label': 'إدارة الأقسام',
+                    'icon': 'bi-diagram-3',
+                    'permission': 'documents.manage_sections',
+                },
+                {
+                    'url_name': 'manage_users',
+                    'label': 'إدارة المستخدمين',
+                    'icon': 'bi-people',
+                    'permission': 'is_staff',      # or a special check to Only show to staff users.
+                },
+            ]
+        }
+    }
+}
+```
+
+Then in your sidebar template:
+```html
+{% extends "sidebar/main.html" %}
+{% load sidebar_tags %}
+
+{% block items %}
+    {% auto_sidebar %}
+    {% extra_sidebar %}
+{% endblock %}
+```
+
+Extra items appear at the bottom of the sidebar, grouped in Bootstrap accordions.
+
 ## Customization
 
 ### Override Default Menu
@@ -115,3 +228,6 @@ While it may theoretically work in LTR environments if standard Bootstrap files
 | **v1.2.0** | **New Theme Implementation:** Redesigned UI with rounded pill-shaped items, tactile micro-animations, and a refined color palette. Improved responsiveness with dynamic top-offset calculations and inline FOUC fixes for small screens. Fixed tooltip stickiness bug. |
 | **v1.2.1** | **Positioning Fix:** Added `align-self: flex-start` to resolve 60px vertical offset in flex containers. Removed legacy `sidebar-top-offset` CSS variable and JS calculations. Added `box-shadow: none` and `outline: none` to accordion buttons to remove focus ring. Fixed page flickering on wider screens by constraining sidebar height with `calc(100vh - header-height)`. |
 | **v1.2.2** | **CSP Compliance:** Added `nonce` attribute support to inline scripts for Content Security Policy compliance. |
+| **v2.0.0** | **Auto-Discovery:** New feature that introspects Django URL patterns and models to automatically generate sidebar navigation items. Adds `{% auto_sidebar %}` template tag, context processor, and configuration options. |
+| **v2.1.0** | **Refactor & Enhancements:** Decoupled customization from models by introducing `DEFAULT_ITEMS` setting for overriding auto-discovered items' labels/icons/order. Added `EXTRA_ITEMS` setting for manual, permission-aware sidebar links grouped in accordions with `{% extra_sidebar %}` tag. Removed deprecated model-level `sidebar_*` attributes. |
+| **v2.2.0** | **Drag-and-Drop Reordering:** New reorder toggle in sidebar toolbar (visible in expanded mode only). Click to enable reorder mode with shake animation. Drag items to reorder with visual drop indicator. Order persists to localStorage. Default order applies only if no user customization exists. Accordion headers remain fixed. |

micro_sidebar-2.2.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+sidebar/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sidebar/apps.py,sha256=iF89pf0Vfs32KLibizTjb9crYPOb3sKcpS0MddBYGrM,381
+sidebar/context_processors.py,sha256=g4TmjkAdyJDqGmQ7c1EhRtDUyt7gHQTPsNzbzy0o_sY,4221
+sidebar/discovery.py,sha256=6rBpji-g057Pwg3fS7Vp1JV61wz3ygmhZfosGMNXjAY,5636
+sidebar/urls.py,sha256=UL_9e1RLNMxZXkah65m7GRU1dbViZRGeNPBIiSZpOYg,142
+sidebar/views.py,sha256=MebyJ1ZiylSOPESXFkkQ8QTg-ClrkJn-oYLN6KrcgiM,418
+sidebar/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sidebar/static/sidebar/sidebar.css,sha256=fojQ5zofvpCz1SNe4zCHPB3Bx7kF0KiVKb_W3SSrA8g,6044
+sidebar/static/sidebar/sidebar.js,sha256=gcurW6nl0Dt9jPTzk749DX7uQ3U_7De4F6Gj8ci6W40,5233
+sidebar/static/sidebar/css/reorder.css,sha256=zOBzg6nJwbY0QRCQKAVjaKxqCXqpICY1kFmXe2qO-og,2177
+sidebar/static/sidebar/css/theme_picker.css,sha256=S2u9p_4rXZALf7hoCOsgyAU91NP3Hoy54WYnc4aGyww,4345
+sidebar/static/sidebar/js/reorder.js,sha256=BRAI-S9aTBeq7kwg1Z_ixgIrPdHB3A7LIdZbe8poRB4,9478
+sidebar/static/sidebar/js/theme_picker.js,sha256=Kt4S2fd0ocFjqeuOQXDcvWVLrLDAVxs7zANZqzIqA4g,2292
+sidebar/static/themes/blue.css,sha256=_CMBLoX8xuSkEdiSYP4HhM-_M368q5Zus9n2kGILBQw,1651
+sidebar/static/themes/dark.css,sha256=JmLG6UWSB7Erwogz0tCcpZUL1hgwxqgfyx-WSCXBtLU,14854
+sidebar/static/themes/gold.css,sha256=2Ry4ba5CIRvgYFTiAaeh5K5DUjvbX1uyVIcolVTPiwE,1619
+sidebar/static/themes/green.css,sha256=y-P-ShJ6ISOqT6FnuS2PNKNQX0kr4Whx-uMLozhPkvY,1951
+sidebar/static/themes/light.css,sha256=XqStIa8wTzWswWyy2nqbk4tMPKUuIR4967PBoJoPuOc,1717
+sidebar/static/themes/main.css,sha256=NaPBDAPL-PkTphtcIto7Qjb5CkiR9T_X5YztDT5SwwE,121
+sidebar/static/themes/main.js,sha256=DSz07M8c1KTXSlj7woxPq0Kf9VFb2uNCI13Cz87gghs,1412
+sidebar/static/themes/red.css,sha256=t8OTmvgszQXX4YtYxlIM86zjx1jp-SvfVx2G3X0FjDI,1613
+sidebar/templates/sidebar/auto.html,sha256=LQRLUJjiodRbRyWKxkj1MGorYrKAF67gsX_LC7LowH4,538
+sidebar/templates/sidebar/extra_groups.html,sha256=uyiT2BcsY1-GM5GXHoudajckccF1cDCrCftm2vxOflo,1568
+sidebar/templates/sidebar/main.html,sha256=djayBODnzWFaZerWG1THyHfvFV-4gYajIrx8BhBF_FY,6512
+sidebar/templatetags/__init__.py,sha256=RC19QrlHdcgslFc_19Se9UhOe-7_WH9GtNGYU_cZlXg,48
+sidebar/templatetags/sidebar_tags.py,sha256=KoZzjqRpMtiGcITKFUQBcs5RdbvtuzCaNrCWEzIbBlk,2245
+micro_sidebar-2.2.0.dist-info/LICENSE,sha256=Fco89ULLSSxKkC2KKnx57SaT0R7WOkZfuk8IYcGiN50,1063
+micro_sidebar-2.2.0.dist-info/METADATA,sha256=NMtlGHTlPMAP1SvLxA2BzGqsbK_XYfWkzfFzYsPT8o0,8607
+micro_sidebar-2.2.0.dist-info/WHEEL,sha256=pkctZYzUS4AYVn6dJ-7367OJZivF2e8RA9b_ZBjif18,92
+micro_sidebar-2.2.0.dist-info/top_level.txt,sha256=ih69sjMhU1wOB9HzUV90yEY98aiPuGhzPBBBE-YtJ3w,8
+micro_sidebar-2.2.0.dist-info/RECORD,,

sidebar/apps.py

@@ -1,5 +1,15 @@
 from django.apps import AppConfig
 
+
 class SidebarConfig(AppConfig):
     default_auto_field = 'django.db.models.BigAutoField'
     name = 'sidebar'
+    
+    def ready(self):
+        """
+        Called when Django starts.
+        Import discovery module to ensure it's available.
+        """
+        # Import to make discovery available
+        from . import discovery  # noqa: F401
+

sidebar/context_processors.py

@@ -0,0 +1,127 @@
+"""
+Context processor for auto-discovered sidebar items.
+
+Injects sidebar navigation items into every request context,
+filtered by user permissions.
+"""
+import hashlib
+import json
+from django.core.cache import cache
+from django.urls import reverse, NoReverseMatch
+from .discovery import discover_list_urls, get_sidebar_config
+
+
+def _get_config_hash(config):
+    """Generate a hash of the config for cache key."""
+    # Exclude EXTRA_ITEMS from hash since they're processed separately
+    config_copy = {k: v for k, v in config.items() if k != 'EXTRA_ITEMS'}
+    config_str = json.dumps(config_copy, sort_keys=True)
+    return hashlib.md5(config_str.encode()).hexdigest()[:8]
+
+
+def _process_extra_items(config, request):
+    """
+    Process EXTRA_ITEMS config into sidebar-ready format.
+    
+    Returns dict of groups, each with icon and list of items with resolved URLs.
+    """
+    extra_items = config.get('EXTRA_ITEMS', {})
+    processed_groups = {}
+    
+    for group_name, group_config in extra_items.items():
+        group_icon = group_config.get('icon', 'bi-gear')
+        items = []
+        
+        for item in group_config.get('items', []):
+            url_name = item.get('url_name', '')
+            
+            # Check permission if specified
+            permission = item.get('permission')
+            if permission:
+                if permission == 'is_staff' and not request.user.is_staff:
+                    continue
+                elif permission == 'is_superuser' and not request.user.is_superuser:
+                    continue
+                elif permission not in ['is_staff', 'is_superuser'] and not request.user.has_perm(permission):
+                    continue
+            
+            # Resolve URL
+            try:
+                url = reverse(url_name)
+                active = request.path == url or request.path.startswith(url.rstrip('/') + '/')
+            except NoReverseMatch:
+                url = '#'
+                active = False
+            
+            items.append({
+                'url_name': url_name,
+                'url': url,
+                'label': item.get('label', url_name),
+                'icon': item.get('icon', 'bi-link'),
+                'active': active,
+            })
+        
+        if items:  # Only add group if it has visible items
+            processed_groups[group_name] = {
+                'icon': group_icon,
+                'items': items,
+                'has_active': any(item['active'] for item in items),
+            }
+    
+    return processed_groups
+
+
+def sidebar_context(request):
+    """
+    Add auto-discovered sidebar items to template context.
+    
+    Items are cached for performance and filtered by user permissions.
+    Only authenticated users see sidebar items, and only items they
+    have view permission for.
+    
+    Returns:
+        Dictionary with 'sidebar_auto_items' and 'sidebar_extra_groups' keys.
+    """
+    config = get_sidebar_config()
+    # Include config hash in cache key so settings changes invalidate cache
+    cache_key = f'sidebar_auto_items_{_get_config_hash(config)}'
+    items = cache.get(cache_key)
+    
+    if items is None:
+        items = discover_list_urls()
+        cache.set(cache_key, items, timeout=config['CACHE_TIMEOUT'])
+    
+    # Filter by user permissions
+    if request.user.is_authenticated:
+        if request.user.is_superuser:
+            # Superusers see everything
+            visible = items
+        else:
+            visible = []
+            for item in items:
+                if not item.get('permissions'):
+                    visible.append(item)
+                elif any(request.user.has_perm(p) for p in item['permissions']):
+                    visible.append(item)
+            items = visible
+        
+        # Process extra items for authenticated users
+        extra_groups = _process_extra_items(config, request)
+    else:
+        items = []
+        extra_groups = {}
+    
+    return {
+        'sidebar_auto_items': items,
+        'sidebar_extra_groups': extra_groups,
+    }
+
+
+def clear_sidebar_cache():
+    """
+    Clear the sidebar items cache.
+    
+    Call this when models or URLs change and sidebar needs refresh.
+    """
+    cache.delete('sidebar_auto_items')
+

sidebar/discovery.py

@@ -0,0 +1,151 @@
+"""
+Auto-discovery module for sidebar navigation items.
+
+Scans Django URL patterns for list views and matches them to models
+to automatically generate sidebar navigation items.
+"""
+from django.urls import get_resolver, URLPattern, URLResolver
+from django.apps import apps
+from django.conf import settings
+from difflib import get_close_matches
+
+
+def get_sidebar_config():
+    """Get sidebar configuration from Django settings with defaults."""
+    defaults = {
+        'ENABLED': True,
+        'URL_PATTERNS': ['list'],
+        'EXCLUDE_APPS': ['admin', 'auth', 'contenttypes', 'sessions'],
+        'EXCLUDE_MODELS': [],
+        'CACHE_TIMEOUT': 3600,
+        'DEFAULT_ICON': 'bi-list',
+        # Extra items that don't require model matching
+        # Format: {'group_name': {'icon': 'bi-gear', 'items': [{'url_name': 'x', 'label': 'X', 'icon': 'bi-x'}]}}
+        'EXTRA_ITEMS': {},
+        # Default overrides for auto-discovered items
+        # Format: {'url_name': {'label': 'X', 'icon': 'bi-x', 'order': 10}}
+        'DEFAULT_ITEMS': {},
+    }
+    user_config = getattr(settings, 'SIDEBAR_AUTO', {})
+    return {**defaults, **user_config}
+
+
+
+def discover_list_urls():
+    """
+    Scan all URL patterns for names containing configured keywords.
+    Match them to Django models and extract verbose_name_plural.
+    
+    Returns:
+        List of sidebar item dictionaries sorted by order.
+    """
+    config = get_sidebar_config()
+    
+    if not config['ENABLED']:
+        return []
+    
+    resolver = get_resolver()
+    items = []
+    
+    for pattern in _iterate_patterns(resolver.url_patterns):
+        url_name = getattr(pattern, 'name', '') or ''
+        
+        # Check if URL name contains any of the configured patterns
+        matched_keyword = None
+        for kw in config['URL_PATTERNS']:
+            if kw in url_name.lower():
+                matched_keyword = kw
+                break
+        
+        if matched_keyword:
+            # Extract model hint (e.g., 'decree' from 'decree_list')
+            model_hint = url_name
+            for kw in config['URL_PATTERNS']:
+                model_hint = model_hint.replace(f'_{kw}', '').replace(f'-{kw}', '').replace(kw, '')
+            
+            model_hint = model_hint.strip('_-')
+            
+            # Try to find model - first with stripped hint, then with keyword itself
+            model = None
+            if model_hint:
+                model = _find_model(model_hint, config)
+            
+            # If no model found and keyword looks like it could be a model name, try that
+            if not model and matched_keyword not in ['list', 'index', 'view', 'page']:
+                model = _find_model(matched_keyword, config)
+            
+            if model:
+                # Check exclusions
+                if model._meta.app_label in config['EXCLUDE_APPS']:
+                    continue
+                if f"{model._meta.app_label}.{model.__name__}" in config['EXCLUDE_MODELS']:
+                    continue
+                
+                items.append({
+                    'url_name': url_name,
+                    'label': getattr(model._meta, 'sidebar_label', None) or str(model._meta.verbose_name_plural),
+                    'icon': getattr(model._meta, 'sidebar_icon', config['DEFAULT_ICON']),
+                    'order': getattr(model._meta, 'sidebar_order', 100),
+                    'app_label': model._meta.app_label,
+                    'model_name': model._meta.model_name,
+                    'permissions': [f'{model._meta.app_label}.view_{model._meta.model_name}'],
+                })
+
+            # Override with DEFAULT_ITEMS if present
+            default_items = config.get('DEFAULT_ITEMS', {})
+            if url_name in default_items:
+                item_config = default_items[url_name]
+                # Update last added item
+                if items:
+                    item = items[-1]
+                    if 'label' in item_config:
+                        item['label'] = item_config['label']
+                    if 'icon' in item_config:
+                        item['icon'] = item_config['icon']
+                    if 'order' in item_config:
+                        item['order'] = item_config['order']
+    
+    return sorted(items, key=lambda x: (x['order'], x['label']))
+
+
+def _iterate_patterns(patterns, prefix=''):
+    """Recursively iterate through URL patterns."""
+    for pattern in patterns:
+        if isinstance(pattern, URLResolver):
+            yield from _iterate_patterns(pattern.url_patterns, prefix + str(pattern.pattern))
+        elif isinstance(pattern, URLPattern):
+            yield pattern
+
+
+def _find_model(hint, config):
+    """
+    Find model by name using exact and fuzzy matching.
+    
+    Args:
+        hint: The model name hint extracted from URL
+        config: Sidebar configuration dictionary
+        
+    Returns:
+        Model class or None if not found
+    """
+    all_models = apps.get_models()
+    
+    # Build lookup excluding configured apps
+    model_names = {}
+    for m in all_models:
+        if m._meta.app_label not in config['EXCLUDE_APPS']:
+            model_names[m.__name__.lower()] = m
+    
+    hint_lower = hint.lower()
+    
+    # Exact match first
+    if hint_lower in model_names:
+        return model_names[hint_lower]
+    
+    # Handle common pluralization (simple 's' suffix)
+    if hint_lower.endswith('s') and hint_lower[:-1] in model_names:
+        return model_names[hint_lower[:-1]]
+    
+    # Fuzzy match as fallback
+    matches = get_close_matches(hint_lower, model_names.keys(), n=1, cutoff=0.8)
+    return model_names[matches[0]] if matches else None

sidebar/static/sidebar/css/reorder.css

@@ -0,0 +1,91 @@
+/* Reorder Toggle Button */
+.reorder-toggle {
+    font-size: 1.2rem;
+    color: #8c98a4;
+    cursor: pointer;
+    padding: 5px;
+    margin-left: 10px;
+    border-radius: 50%;
+    transition: all 0.2s ease;
+    pointer-events: auto;
+}
+
+.reorder-toggle:hover {
+    color: var(--primal, #2363c3);
+    transform: scale(1.1);
+}
+
+.reorder-toggle.active {
+    color: var(--primal, #2363c3);
+    background-color: rgba(35, 99, 195, 0.1);
+}
+
+/* Hide reorder toggle in collapsed sidebar */
+.sidebar.collapsed .reorder-toggle {
+    display: none;
+}
+
+/* Shake Animation for reorder mode */
+@keyframes shake {
+    0%, 100% { transform: translateX(0); }
+    10%, 30%, 50%, 70%, 90% { transform: translateX(-2px); }
+    20%, 40%, 60%, 80% { transform: translateX(2px); }
+}
+
+.sidebar.reorder-mode .list-group-item[draggable="true"],
+.sidebar.reorder-mode .accordion-body .list-group-item[draggable="true"] {
+    animation: shake 1.5s ease-in-out infinite;
+    cursor: grab;
+}
+
+.sidebar.reorder-mode .list-group-item[draggable="true"]:hover {
+    animation-play-state: paused;
+    background-color: rgba(35, 99, 195, 0.08) !important;
+}
+
+/* Dragging State */
+.sidebar .list-group-item.dragging {
+    opacity: 0.4;
+    cursor: grabbing;
+    animation: none !important;
+}
+
+/* Drop Indicator Line */
+.drop-indicator {
+    height: 3px;
+    background: var(--primal, #2363c3);
+    border-radius: 2px;
+    margin: 2px 10px;
+    pointer-events: none;
+    box-shadow: 0 0 8px rgba(35, 99, 195, 0.5);
+    animation: pulseIndicator 0.8s ease-in-out infinite;
+}
+
+@keyframes pulseIndicator {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.6; }
+}
+
+/* Ensure theme indicator stays in position */
+.sidebar.collapsed .sidebar-toolbar {
+    justify-content: center;
+}
+
+/* Dark Mode Overrides */
+:root.theme-dark .reorder-toggle {
+    color: rgba(255, 255, 255, 0.6);
+}
+
+:root.theme-dark .reorder-toggle:hover,
+:root.theme-dark .reorder-toggle.active {
+    color: var(--primal, #3b82f6);
+}
+
+:root.theme-dark .reorder-toggle.active {
+    background-color: rgba(59, 130, 246, 0.2);
+}
+
+:root.theme-dark .drop-indicator {
+    background: var(--primal, #3b82f6);
+    box-shadow: 0 0 8px rgba(59, 130, 246, 0.5);
+}