django-cfg 1.3.11__py3-none-any.whl → 1.4.0__py3-none-any.whl

django_cfg/templates/admin/sections/overview_section.html

@@ -0,0 +1,112 @@
+{% load unfold %}
+
+<!-- Overview Section -->
+<div class="space-y-10 flex flex-col gap-8">
+    <!-- Hero Section with Key Metrics -->
+    <div>
+        <div class="flex items-center justify-between mb-6">
+            <div>
+                <h1 class="text-2xl font-bold theme-text">{{ title|default:"System Overview" }}</h1>
+                <p class="text-gray-600 dark:text-gray-300 mt-2">
+                    Real-time monitoring and key performance indicators
+                </p>
+            </div>
+            <div class="flex items-center space-x-2 text-sm text-gray-500 dark:text-gray-400">
+                <span class="material-icons text-green-500">fiber_manual_record</span>
+                <span>Live data</span>
+            </div>
+        </div>
+
+        <!-- Key Statistics Cards -->
+        <div class="grid grid-cols-1 md:grid-cols-3 gap-6">
+            {% for key, value in data.stats.items %}
+                <div class="theme-card p-6 rounded-lg shadow-sm border theme-border">
+                    <div class="flex items-center justify-between">
+                        <div>
+                            <p class="text-sm text-gray-600 dark:text-gray-400 uppercase">{{ key }}</p>
+                            <p class="text-3xl font-bold theme-text mt-2">{{ value }}</p>
+                        </div>
+                        <span class="material-icons text-blue-500 text-4xl">{{ icon|default:"analytics" }}</span>
+                    </div>
+                </div>
+            {% endfor %}
+        </div>
+    </div>
+
+    <!-- System Health & Quick Actions -->
+    <div class="grid grid-cols-1 lg:grid-cols-2 gap-8 mb-8">
+        <div class="theme-card rounded-lg shadow-sm border theme-border">
+            <div class="p-6 border-b theme-border">
+                <h3 class="text-lg font-semibold theme-text flex items-center">
+                    <span class="material-icons text-green-500 mr-2">favorite</span>
+                    System Health
+                </h3>
+            </div>
+            <div class="p-6">
+                <div class="space-y-4">
+                    {% for key, value in data.system_health.items %}
+                        <div class="flex items-center justify-between">
+                            <span class="text-gray-700 dark:text-gray-300">{{ key|title }}</span>
+                            <span class="font-mono text-sm theme-text">{{ value }}</span>
+                        </div>
+                    {% endfor %}
+                </div>
+            </div>
+        </div>
+
+        <!-- Quick Actions Card -->
+        <div class="theme-card rounded-lg border theme-border shadow-sm">
+            <div class="p-6">
+                {% include 'admin/snippets/components/quick_actions.html' %}
+            </div>
+        </div>
+    </div>
+
+    <!-- Charts & Recent Activity -->
+    <div class="space-y-8">
+        <!-- Charts Section -->
+        {% include 'admin/snippets/components/charts_section.html' %}
+
+        <!-- Recent Activity Stream -->
+        <div class="theme-card rounded-lg shadow-sm border theme-border">
+            <div class="p-6 border-b theme-border">
+                <h3 class="text-lg font-semibold theme-text flex items-center">
+                    <span class="material-icons text-blue-600 mr-2">timeline</span>
+                    Recent Activity
+                </h3>
+            </div>
+            <div class="p-6">
+                {% include 'admin/snippets/components/recent_activity_improved.html' %}
+            </div>
+        </div>
+    </div>
+
+    <!-- Secondary Metrics Row -->
+    <div class="grid grid-cols-1 lg:grid-cols-2 gap-8">
+        <!-- System Metrics -->
+        <div class="theme-card rounded-lg border theme-border shadow-sm">
+            <div class="p-6 border-b theme-border">
+                <h3 class="text-lg font-semibold theme-text flex items-center">
+                    <span class="material-icons text-blue-500 mr-2">memory</span>
+                    System Metrics
+                </h3>
+            </div>
+            <div class="p-6">
+                {% include 'admin/snippets/components/system_metrics.html' %}
+            </div>
+        </div>
+
+        <!-- Activity Tracker -->
+        <div class="theme-card rounded-lg border theme-border shadow-sm">
+            <div class="p-6 border-b theme-border">
+                <h3 class="text-lg font-semibold theme-text flex items-center">
+                    <span class="material-icons text-blue-600 mr-2">track_changes</span>
+                    Activity Tracker
+                </h3>
+            </div>
+            <div class="p-6">
+                {% include 'admin/snippets/components/activity_tracker.html' %}
+            </div>
+        </div>
+    </div>
+</div>

django_cfg/templates/admin/sections/stats_section.html

@@ -0,0 +1,35 @@
+{% load unfold %}
+
+<!-- Statistics Section -->
+<div class="space-y-8">
+    <div class="flex items-center justify-between mb-6">
+        <div>
+            <h1 class="text-2xl font-bold theme-text">{{ title|default:"Statistics" }}</h1>
+            <p class="text-gray-600 dark:text-gray-300 mt-2">
+                Detailed metrics for each application module
+            </p>
+        </div>
+    </div>
+
+    <!-- App Statistics -->
+    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
+        {% for app in data.app_stats %}
+            <div class="theme-card p-6 rounded-lg shadow-sm border theme-border">
+                <div class="flex items-center justify-between mb-4">
+                    <h3 class="font-semibold theme-text">{{ app.name }}</h3>
+                    <span class="material-icons text-blue-500">{{ app.icon|default:"apps" }}</span>
+                </div>
+                <div class="space-y-2">
+                    <div class="flex justify-between text-sm">
+                        <span class="text-gray-600 dark:text-gray-400">Label:</span>
+                        <span class="theme-text">{{ app.label }}</span>
+                    </div>
+                    <div class="flex justify-between text-sm">
+                        <span class="text-gray-600 dark:text-gray-400">Models:</span>
+                        <span class="theme-text font-mono">{{ app.models_count }}</span>
+                    </div>
+                </div>
+            </div>
+        {% endfor %}
+    </div>
+</div>

django_cfg/templates/admin/sections/system_section.html

@@ -0,0 +1,99 @@
+{% load unfold %}
+
+<!-- System Management Section -->
+<div class="space-y-8">
+    <div class="flex items-center justify-between mb-6">
+        <div>
+            <h1 class="text-2xl font-bold theme-text">{{ title|default:"System Management" }}</h1>
+            <p class="text-gray-600 dark:text-gray-300 mt-2">
+                System health checks and configuration overview
+            </p>
+        </div>
+        <div class="flex items-center space-x-2">
+            {% if data.health.status == 'healthy' %}
+                <span class="material-icons text-green-500">check_circle</span>
+                <span class="text-sm text-green-600 dark:text-green-400 font-medium">Healthy</span>
+            {% else %}
+                <span class="material-icons text-red-500">error</span>
+                <span class="text-sm text-red-600 dark:text-red-400 font-medium">Issues Detected</span>
+            {% endif %}
+        </div>
+    </div>
+
+    <!-- Health Checks Grid -->
+    <div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-6 mb-8">
+        {% for check_name, check_status in data.health.checks.items %}
+            <div class="theme-card p-6 rounded-lg shadow-sm border theme-border">
+                <div class="flex items-center justify-between">
+                    <div>
+                        <p class="text-sm text-gray-600 dark:text-gray-400 uppercase">{{ check_name|title }}</p>
+                        <p class="text-lg font-semibold theme-text mt-2">
+                            {% if check_status %}
+                                <span class="text-green-600 dark:text-green-400">Operational</span>
+                            {% else %}
+                                <span class="text-red-600 dark:text-red-400">Failed</span>
+                            {% endif %}
+                        </p>
+                    </div>
+                    {% if check_status %}
+                        <span class="material-icons text-green-500 text-3xl">check_circle</span>
+                    {% else %}
+                        <span class="material-icons text-red-500 text-3xl">cancel</span>
+                    {% endif %}
+                </div>
+            </div>
+        {% endfor %}
+    </div>
+
+    <!-- Configuration & Services -->
+    <div class="grid grid-cols-1 lg:grid-cols-2 gap-8">
+        <!-- Configuration Card -->
+        <div class="theme-card rounded-lg shadow-sm border theme-border">
+            <div class="p-6 border-b theme-border">
+                <h3 class="text-lg font-semibold theme-text flex items-center">
+                    <span class="material-icons text-blue-500 mr-2">settings</span>
+                    Configuration
+                </h3>
+            </div>
+            <div class="p-6">
+                <div class="space-y-4">
+                    {% for key, value in data.configuration.items %}
+                        <div class="flex items-center justify-between">
+                            <span class="text-gray-700 dark:text-gray-300">{{ key|title }}</span>
+                            <span class="font-mono text-sm theme-text">{{ value }}</span>
+                        </div>
+                    {% endfor %}
+                </div>
+            </div>
+        </div>
+
+        <!-- Services Status Card -->
+        <div class="theme-card rounded-lg shadow-sm border theme-border">
+            <div class="p-6 border-b theme-border">
+                <h3 class="text-lg font-semibold theme-text flex items-center">
+                    <span class="material-icons text-purple-500 mr-2">cloud</span>
+                    Services
+                </h3>
+            </div>
+            <div class="p-6">
+                {% if data.services %}
+                    <div class="space-y-3">
+                        {% for service_name, service_status in data.services.items %}
+                            <div class="flex items-center justify-between text-sm">
+                                <span class="theme-text">{{ service_name }}</span>
+                                <div class="status-indicator">
+                                    <span class="status-dot {% if service_status %}success{% else %}error{% endif %}"></span>
+                                    <span class="text-gray-600 dark:text-gray-400">
+                                        {% if service_status %}Active{% else %}Inactive{% endif %}
+                                    </span>
+                                </div>
+                            </div>
+                        {% endfor %}
+                    </div>
+                {% else %}
+                    <p class="text-gray-500 dark:text-gray-400 text-sm">No external services configured</p>
+                {% endif %}
+            </div>
+        </div>
+    </div>
+</div>

django_cfg/templates/admin/snippets/components/CHARTS_GUIDE.md

@@ -0,0 +1,322 @@
+# Chart.js Integration Guide
+
+## Overview
+
+This guide documents the Chart.js integration in the Django CFG dashboard, including key insights, best practices, and solutions to common issues.
+
+## Architecture
+
+### Data Flow
+
+```
+Python (callbacks/charts.py)
+  → Pydantic Models (ChartData, ChartDataset)
+  → JSON Serialization (.model_dump())
+  → Django Template (|safe filter)
+  → JavaScript (Chart.js)
+```
+
+### File Structure
+
+- **Backend**: `/django_cfg/modules/django_unfold/callbacks/charts.py` - Chart data generation
+- **Models**: `/django_cfg/modules/django_unfold/models/charts.py` - Pydantic data models
+- **Template**: `/django_cfg/templates/admin/snippets/components/charts_section.html` - Chart rendering
+
+## Key Implementation Details
+
+### 1. Container Height - CRITICAL
+
+**❌ WRONG - Infinite Height Growth:**
+```html
+<canvas id="myChart" height="300"></canvas>
+```
+
+**✅ CORRECT - Fixed Container:**
+```html
+<div class="relative h-[300px]">
+    <canvas id="myChart"></canvas>
+</div>
+```
+
+**Why:** Chart.js with `responsive: true` + `maintainAspectRatio: false` needs a fixed-height parent container. Without it, the canvas grows infinitely as Chart.js tries to maintain responsiveness.
+
+### 2. Data Format
+
+Chart.js expects this structure:
+
+```javascript
+{
+    type: 'line',  // or 'bar', 'pie', etc.
+    data: {
+        labels: ['Day 1', 'Day 2', ...],
+        datasets: [{
+            label: 'Dataset Name',
+            data: [10, 20, 30, ...],
+            backgroundColor: 'rgba(59, 130, 246, 0.1)',
+            borderColor: 'rgb(59, 130, 246)',
+            tension: 0.4  // for line charts
+        }]
+    },
+    options: { ... }
+}
+```
+
+**Our Implementation:**
+```javascript
+new Chart(ctx, {
+    type: 'line',
+    data: chartData,  // chartData = {labels: [...], datasets: [...]}
+    options: { ... }
+});
+```
+
+### 3. Python to JavaScript Bridge
+
+**Backend (charts.py):**
+```python
+from .models.charts import ChartData, ChartDataset
+
+def get_user_registration_chart_data(self) -> Dict[str, Any]:
+    chart_data = ChartData(
+        labels=["09/26", "09/27", ...],
+        datasets=[
+            ChartDataset(
+                label="New Users",
+                data=[2, 5, 3, ...],
+                backgroundColor="rgba(59, 130, 246, 0.1)",
+                borderColor="rgb(59, 130, 246)",
+                tension=0.4
+            )
+        ]
+    )
+    return chart_data.model_dump()  # Converts Pydantic to dict
+```
+
+**Template:**
+```html
+<!-- Serialize to JSON for JavaScript -->
+"charts": {
+    "user_registrations_json": json.dumps(self.get_user_registration_chart_data()),
+    "user_registrations": self.get_user_registration_chart_data(),
+}
+```
+
+**HTML/JavaScript:**
+```html
+<script>
+    const chartData = {{ charts.user_registrations_json|safe }};
+    new Chart(ctx, {
+        type: 'line',
+        data: chartData,
+        options: { ... }
+    });
+</script>
+```
+
+### 4. Chart.js Configuration Best Practices
+
+```javascript
+{
+    type: 'line',  // or 'bar'
+    data: chartData,
+    options: {
+        responsive: true,              // Chart resizes with container
+        maintainAspectRatio: false,   // Don't maintain aspect ratio
+        plugins: {
+            legend: {
+                display: true,
+                position: 'top'
+            }
+        },
+        scales: {
+            y: {
+                beginAtZero: true,    // Start Y axis at 0
+                ticks: {
+                    precision: 0      // Show integers only (no decimals)
+                }
+            }
+        }
+    }
+}
+```
+
+## Common Issues & Solutions
+
+### Issue 1: Charts Not Displaying
+
+**Symptoms:** Canvas element exists but no chart visible
+
+**Debug Checklist:**
+```javascript
+console.log('Chart.js loaded:', typeof Chart !== 'undefined');
+console.log('Canvas element:', document.getElementById('myChart'));
+console.log('Chart data:', chartData);
+console.log('Data has labels:', 'labels' in chartData);
+console.log('Data has datasets:', 'datasets' in chartData);
+```
+
+**Common Causes:**
+1. Chart.js library not loaded
+2. Canvas ID mismatch
+3. Data format incorrect
+4. DOMContentLoaded not fired yet
+
+### Issue 2: Infinite Height Growth
+
+**Symptoms:** Chart keeps expanding vertically, page becomes very tall
+
+**Solution:** Wrap canvas in fixed-height container (see section 1 above)
+
+### Issue 3: Data Not Updating
+
+**Symptoms:** Chart shows old data after refresh
+
+**Solution:** Ensure Chart.js recreates instead of updates:
+```javascript
+// Destroy existing chart first
+if (window.myChart) {
+    window.myChart.destroy();
+}
+window.myChart = new Chart(ctx, config);
+```
+
+### Issue 4: Dark Mode Colors
+
+**Best Practices:**
+```python
+ChartDataset(
+    backgroundColor="rgba(59, 130, 246, 0.1)",  # Light with transparency
+    borderColor="rgb(59, 130, 246)",            # Solid color
+    # Use theme-aware colors that work in both light/dark modes
+)
+```
+
+## Template Integration
+
+### Complete Working Example
+
+```html
+{% if charts.user_registrations %}
+    <div class="relative h-[300px]">
+        <canvas id="userRegistrationsChart"></canvas>
+    </div>
+    <script>
+        document.addEventListener('DOMContentLoaded', function() {
+            const ctx = document.getElementById('userRegistrationsChart');
+            const chartData = {{ charts.user_registrations_json|safe }};
+
+            if (ctx && typeof Chart !== 'undefined') {
+                try {
+                    new Chart(ctx, {
+                        type: 'line',
+                        data: chartData,
+                        options: {
+                            responsive: true,
+                            maintainAspectRatio: false,
+                            plugins: {
+                                legend: {
+                                    display: true,
+                                    position: 'top'
+                                }
+                            },
+                            scales: {
+                                y: {
+                                    beginAtZero: true,
+                                    ticks: {
+                                        precision: 0
+                                    }
+                                }
+                            }
+                        }
+                    });
+                } catch (error) {
+                    console.error('Error creating chart:', error);
+                }
+            }
+        });
+    </script>
+{% else %}
+    <div class="h-[300px] flex items-center justify-center">
+        <p class="text-gray-500">No chart data available</p>
+    </div>
+{% endif %}
+```
+
+## Testing Chart Integration
+
+### 1. Verify Chart.js Load
+
+```javascript
+console.log('Chart.js version:', Chart.version); // Should show: 4.4.0
+```
+
+### 2. Check Data Structure
+
+```python
+# In callbacks/charts.py
+chart_data = self.get_user_registration_chart_data()
+print(f"Labels: {chart_data['labels']}")
+print(f"Dataset count: {len(chart_data['datasets'])}")
+print(f"Data points: {chart_data['datasets'][0]['data']}")
+```
+
+### 3. Template Debugging
+
+```html
+<!-- Add temporary debug output -->
+<pre>{{ charts.user_registrations|pprint }}</pre>
+```
+
+## Performance Considerations
+
+1. **Limit Data Points**: Keep chart data to reasonable size (e.g., 7-90 days max)
+2. **Lazy Loading**: Load charts only when tab/section is visible
+3. **Caching**: Cache chart data in backend if queries are expensive
+4. **Animation**: Disable animations for large datasets:
+   ```javascript
+   options: {
+       animation: false  // or { duration: 0 }
+   }
+   ```
+
+## Future Enhancements
+
+### 1. Interactive Features
+- Click to drill down
+- Hover tooltips with detailed info
+- Date range picker integration
+
+### 2. Additional Chart Types
+- Pie/Doughnut for distribution
+- Mixed charts (line + bar)
+- Area charts for cumulative data
+
+### 3. Export Functionality
+- Download as PNG/SVG
+- Export data as CSV
+- Share chart snapshots
+
+## Troubleshooting Reference
+
+| Symptom | Likely Cause | Solution |
+|---------|--------------|----------|
+| Chart not visible | No fixed-height container | Add `h-[300px]` to parent div |
+| Infinite scrolling | Canvas height attribute set | Remove `height="300"` from canvas |
+| No data | Backend not providing data | Check callback method |
+| Wrong data | Cache issue | Clear browser cache |
+| Colors don't match theme | Hardcoded colors | Use CSS variables or theme-aware colors |
+| Chart flickers | Multiple DOMContentLoaded listeners | Ensure single initialization |
+
+## References
+
+- [Chart.js Documentation](https://www.chartjs.org/docs/latest/)
+- [Chart.js Examples](https://www.chartjs.org/docs/latest/samples/)
+- [Tailwind CSS Height Utilities](https://tailwindcss.com/docs/height)
+- Pydantic Models: `/django_cfg/modules/django_unfold/models/charts.py`
+- Chart Callbacks: `/django_cfg/modules/django_unfold/callbacks/charts.py`
+
+---
+
+**Last Updated:** 2025-10-03
+**Chart.js Version:** 4.4.0
+**Django Version:** 5.x