django-cfg 1.4.48__py3-none-any.whl → 1.5.7__py3-none-any.whl

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

@@ -1,322 +0,0 @@
-# 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

django_cfg/templates/admin/snippets/components/activity_tracker.html

@@ -1,92 +0,0 @@
-{% load unfold %}
-
-<!-- Activity Tracker -->
-<div class="space-y-4">
-    <!-- Legend -->
-    <div class="flex items-center justify-between text-sm text-gray-600 dark:text-gray-400">
-        <span>Less</span>
-        <div class="flex items-center space-x-1">
-            <div class="w-3 h-3 bg-gray-200 dark:bg-gray-700 rounded-sm"></div>
-            <div class="w-3 h-3 bg-green-200 dark:bg-green-800 rounded-sm"></div>
-            <div class="w-3 h-3 bg-green-400 dark:bg-green-600 rounded-sm"></div>
-            <div class="w-3 h-3 bg-green-600 dark:bg-green-500 rounded-sm"></div>
-            <div class="w-3 h-3 bg-green-800 dark:bg-green-400 rounded-sm"></div>
-        </div>
-        <span>More</span>
-    </div>
-
-    <!-- Activity Tracker Grid -->
-    <div class="overflow-x-auto pb-2">
-        {% if activity_tracker %}
-            <!-- GitHub-style heatmap visualization -->
-            <div id="activity-heatmap" class="inline-flex gap-1"></div>
-
-            <script>
-            (function() {
-                const activityData = {{ activity_tracker }};
-                const heatmap = document.getElementById('activity-heatmap');
-
-                if (activityData && activityData.length > 0) {
-                    // Group days into weeks (7 days per column)
-                    const weeks = [];
-                    for (let i = 0; i < activityData.length; i += 7) {
-                        weeks.push(activityData.slice(i, i + 7));
-                    }
-
-                    // Create week columns
-                    weeks.forEach(week => {
-                        const weekColumn = document.createElement('div');
-                        weekColumn.className = 'flex flex-col gap-1';
-
-                        week.forEach(day => {
-                            const cell = document.createElement('div');
-                            cell.className = 'w-3 h-3 rounded-sm transition-all hover:ring-2 hover:ring-blue-400 cursor-pointer';
-
-                            // Color based on activity level
-                            if (day.count === 0) {
-                                cell.className += ' bg-gray-200 dark:bg-gray-700';
-                            } else if (day.count <= 2) {
-                                cell.className += ' bg-green-200 dark:bg-green-800';
-                            } else if (day.count <= 5) {
-                                cell.className += ' bg-green-400 dark:bg-green-600';
-                            } else if (day.count <= 10) {
-                                cell.className += ' bg-green-600 dark:bg-green-500';
-                            } else {
-                                cell.className += ' bg-green-800 dark:bg-green-400';
-                            }
-
-                            cell.title = `${day.date}: ${day.count} activities`;
-                            weekColumn.appendChild(cell);
-                        });
-
-                        heatmap.appendChild(weekColumn);
-                    });
-                }
-            })();
-            </script>
-        {% else %}
-            <div class="flex items-center justify-center p-8 bg-gray-50 dark:bg-gray-800 rounded-lg border border-gray-200 dark:border-gray-700">
-                <div class="text-center">
-                    <span class="material-icons text-4xl text-gray-400 dark:text-gray-500 mb-2">timeline</span>
-                    <p class="text-gray-600 dark:text-gray-400">No activity data available</p>
-                </div>
-            </div>
-        {% endif %}
-    </div>
-
-    <!-- Summary Stats -->
-    <div class="grid grid-cols-3 gap-4 pt-4 border-t border-gray-200 dark:border-gray-700">
-        <div class="text-center">
-            <div class="text-lg font-semibold text-gray-900 dark:text-gray-100">365</div>
-            <div class="text-xs text-gray-600 dark:text-gray-400">Days tracked</div>
-        </div>
-        <div class="text-center">
-            <div class="text-lg font-semibold text-green-600 dark:text-green-400">52</div>
-            <div class="text-xs text-gray-600 dark:text-gray-400">Weeks</div>
-        </div>
-        <div class="text-center">
-            <div class="text-lg font-semibold text-blue-600 dark:text-blue-400">{{ activity_tracker|length|default:"0" }}</div>
-            <div class="text-xs text-gray-600 dark:text-gray-400">Data points</div>
-        </div>
-    </div>
-</div> 

django_cfg/templates/admin/snippets/components/charts_section.html

@@ -1,179 +0,0 @@
-{% load unfold %}
-
-<!-- Charts Section -->
-<div class="mb-8 w-full">
-    {% include 'admin/components/section_header.html' with title='Analytics Overview' icon='analytics' icon_color='blue' %}
-
-    <!-- Time Range Navigation -->
-    {% if navigation %}
-        <div class="mb-6 flex items-center space-x-2">
-            {% for nav_item in navigation %}
-                <a href="{{ nav_item.link }}"
-                   class="px-4 py-2 rounded-default {% if nav_item.active %}bg-primary-600 text-white{% else %}bg-base-100 dark:bg-base-800 text-font-default-light dark:text-font-default-dark hover:bg-base-200 dark:hover:bg-base-700{% endif %} transition-colors flex items-center">
-                    {% if nav_item.icon %}
-                        <span class="material-icons text-sm mr-2">{{ nav_item.icon }}</span>
-                    {% endif %}
-                    {{ nav_item.title }}
-                </a>
-            {% endfor %}
-        </div>
-    {% endif %}
-
-    {% if charts %}
-    <div class="grid grid-cols-1 lg:grid-cols-2 gap-6">
-        <!-- User Registration Chart -->
-        <div class="bg-white dark:bg-base-900 rounded-lg border border-base-200 dark:border-base-700 p-6 shadow-sm">
-            <div class="mb-4">
-                <h3 class="text-lg font-semibold text-font-important-light dark:text-font-important-dark">User Registrations</h3>
-                <p class="text-sm text-font-subtle-light dark:text-font-subtle-dark">Last 7 days activity</p>
-            </div>
-            <div class="flex items-center mb-4">
-                <span class="material-icons text-primary-600 dark:text-primary-500 mr-2">trending_up</span>
-                <span class="text-sm text-font-subtle-light dark:text-font-subtle-dark">Growth Trends</span>
-            </div>
-            {% 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 registration chart:', error);
-                            }
-                        }
-                    });
-                </script>
-
-                <!-- Fallback data table if chart doesn't render -->
-                <div class="mt-4 text-xs text-font-subtle-light dark:text-font-subtle-dark">
-                    <div class="flex justify-between items-center mb-2">
-                        <span class="font-medium">Data Preview:</span>
-                        <span>{{ charts.user_registrations.datasets.0.label }}</span>
-                    </div>
-                    <div class="grid grid-cols-7 gap-1 text-center">
-                        {% for label in charts.user_registrations.labels %}
-                            <div class="bg-base-100 dark:bg-base-700 p-1 rounded text-xs">{{ label }}</div>
-                        {% endfor %}
-                    </div>
-                    <div class="grid grid-cols-7 gap-1 text-center mt-1">
-                        {% for value in charts.user_registrations.datasets.0.data %}
-                            <div class="bg-primary-50 dark:bg-primary-900/20 p-1 rounded text-xs font-medium">{{ value }}</div>
-                        {% endfor %}
-                    </div>
-                </div>
-            {% else %}
-                <div class="h-[300px] flex items-center justify-center bg-base-50 dark:bg-base-800 rounded-lg border border-base-200 dark:border-base-700">
-                    <p class="text-font-subtle-light dark:text-font-subtle-dark">No registration data available</p>
-                </div>
-            {% endif %}
-        </div>
-
-        <!-- User Activity Chart -->
-        <div class="bg-white dark:bg-base-900 rounded-lg border border-base-200 dark:border-base-700 p-6 shadow-sm">
-            <div class="mb-4">
-                <h3 class="text-lg font-semibold text-font-important-light dark:text-font-important-dark">User Activity</h3>
-                <p class="text-sm text-font-subtle-light dark:text-font-subtle-dark">Weekly engagement metrics</p>
-            </div>
-            <div class="flex items-center mb-4">
-                <span class="material-icons text-green-600 dark:text-green-400 mr-2">bar_chart</span>
-                <span class="text-sm text-font-subtle-light dark:text-font-subtle-dark">Activity Levels</span>
-            </div>
-            {% if charts.user_activity %}
-                <div class="relative h-[300px]">
-                    <canvas id="userActivityChart"></canvas>
-                </div>
-                <script>
-                    document.addEventListener('DOMContentLoaded', function() {
-                        const ctx = document.getElementById('userActivityChart');
-                        const chartData = {{ charts.user_activity_json|safe }};
-
-                        if (ctx && typeof Chart !== 'undefined') {
-                            try {
-                                new Chart(ctx, {
-                                    type: 'bar',
-                                    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 activity chart:', error);
-                            }
-                        }
-                    });
-                </script>
-
-                <!-- Fallback data table if chart doesn't render -->
-                <div class="mt-4 text-xs text-font-subtle-light dark:text-font-subtle-dark">
-                    <div class="flex justify-between items-center mb-2">
-                        <span class="font-medium">Data Preview:</span>
-                        <span>{{ charts.user_activity.datasets.0.label }}</span>
-                    </div>
-                    <div class="grid grid-cols-7 gap-1 text-center">
-                        {% for label in charts.user_activity.labels %}
-                            <div class="bg-base-100 dark:bg-base-700 p-1 rounded text-xs">{{ label }}</div>
-                        {% endfor %}
-                    </div>
-                    <div class="grid grid-cols-7 gap-1 text-center mt-1">
-                        {% for value in charts.user_activity.datasets.0.data %}
-                            <div class="bg-green-50 dark:bg-green-900/20 p-1 rounded text-xs font-medium">{{ value }}</div>
-                        {% endfor %}
-                    </div>
-                </div>
-            {% else %}
-                <div class="h-[300px] flex items-center justify-center bg-base-50 dark:bg-base-800 rounded-lg border border-base-200 dark:border-base-700">
-                    <p class="text-font-subtle-light dark:text-font-subtle-dark">No activity data available</p>
-                </div>
-            {% endif %}
-        </div>
-    </div>
-    {% else %}
-    <div class="bg-base-50 dark:bg-base-800 rounded-lg border border-base-200 dark:border-base-700 p-8 text-center">
-        <span class="material-icons text-4xl text-base-400 dark:text-base-500 mb-4">analytics</span>
-        <h3 class="text-lg font-medium text-font-default-light dark:text-font-default-dark mb-2">No Chart Data</h3>
-        <p class="text-font-subtle-light dark:text-font-subtle-dark">Charts data is not available in the context</p>
-    </div>
-    {% endif %}
-</div>