docs: add comprehensive Jinja macros documentation

New documentation: - docs/frontend/shared/jinja-macros.md: Complete reference for all 94 macros - Alerts, Avatars, Badges, Buttons, Cards, Charts, Datepicker - Dropdowns, Forms, Headers, Modals, Pagination, Tables - Usage examples and parameter documentation - Complete page example showing all macros together Updated documentation: - docs/frontend/cdn-fallback-strategy.md: - Add Chart.js (v4.4.1) and Flatpickr (v4.6.13) sections - Document optional-libs.html loader macros - Update file structure and deployment checklist - docs/frontend/shared/ui-components.md: - Add tip box recommending Jinja macros for new development - Update related documentation links - mkdocs.yml: - Add Jinja Macros Library to navigation (top of Shared Components) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-06 19:15:27 +01:00
parent ffa15aee2b
commit dad0989948
4 changed files with 1288 additions and 7 deletions
--- a/docs/frontend/cdn-fallback-strategy.md
+++ b/docs/frontend/cdn-fallback-strategy.md
@@ -13,11 +13,21 @@ All three frontends (Shop, Vendor, Admin) implement a robust CDN fallback strate

 The following assets are loaded from CDN with automatic fallback to local copies:

+### Core Assets (Always Loaded)
+
 | Asset | CDN Source | Local Fallback |
 |-------|-----------|----------------|
 | **Tailwind CSS** | `https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css` | `static/shared/css/tailwind.min.css` |
 | **Alpine.js** | `https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js` | `static/shared/js/vendor/alpine.min.js` |

+### Optional Assets (Loaded On Demand)
+
+| Asset | CDN Source | Local Fallback | Used For |
+|-------|-----------|----------------|----------|
+| **Chart.js** | `https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js` | `static/shared/js/vendor/chart.umd.min.js` | Charts macros |
+| **Flatpickr JS** | `https://cdn.jsdelivr.net/npm/flatpickr@4.6.13/dist/flatpickr.min.js` | `static/shared/js/vendor/flatpickr.min.js` | Datepicker macros |
+| **Flatpickr CSS** | `https://cdn.jsdelivr.net/npm/flatpickr@4.6.13/dist/flatpickr.min.css` | `static/shared/css/vendor/flatpickr.min.css` | Datepicker styling |
+
 ## Implementation

 ### Tailwind CSS Fallback
@@ -71,25 +81,108 @@ Alpine.js uses dynamic script loading with error handling:
 6. Creates new script element pointing to local copy
 7. Appends fallback script to `<head>`

+### Optional Libraries (Chart.js & Flatpickr)
+
+Optional libraries are loaded on-demand using Jinja macros. This keeps page load times fast by only loading what's needed.
+
+**Location:** `app/templates/shared/includes/optional-libs.html`
+
+#### Loading Chart.js
+
+In your page template:
+
+```jinja
+{% block chartjs_script %}
+{% from 'shared/includes/optional-libs.html' import chartjs_loader %}
+{{ chartjs_loader() }}
+{% endblock %}
+```
+
+**Generated code:**
+
+```html
+<script>
+(function() {
+    var script = document.createElement('script');
+    script.src = 'https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js';
+
+    script.onerror = function() {
+        console.warn('Chart.js CDN failed, loading local copy...');
+        var fallbackScript = document.createElement('script');
+        fallbackScript.src = '/static/shared/js/vendor/chart.umd.min.js';
+        document.head.appendChild(fallbackScript);
+    };
+
+    document.head.appendChild(script);
+})();
+</script>
+```
+
+#### Loading Flatpickr
+
+Flatpickr requires both CSS and JS:
+
+```jinja
+{# In head - load CSS #}
+{% block flatpickr_css %}
+{% from 'shared/includes/optional-libs.html' import flatpickr_css_loader %}
+{{ flatpickr_css_loader() }}
+{% endblock %}
+
+{# Before page scripts - load JS #}
+{% block flatpickr_script %}
+{% from 'shared/includes/optional-libs.html' import flatpickr_loader %}
+{{ flatpickr_loader() }}
+{% endblock %}
+```
+
+**Generated CSS code:**
+
+```html
+<link rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/flatpickr@4.6.13/dist/flatpickr.min.css"
+      onerror="this.onerror=null; this.href='/static/shared/css/vendor/flatpickr.min.css';">
+```
+
+#### Available Blocks in admin/base.html
+
+| Block | Purpose | Location |
+|-------|---------|----------|
+| `flatpickr_css` | Flatpickr CSS | In `<head>` |
+| `chartjs_script` | Chart.js | Before page scripts |
+| `flatpickr_script` | Flatpickr JS | Before page scripts |
+| `extra_scripts` | Page-specific JS | Last in body |
+
 ## File Structure

 ```
 static/
 ├── shared/
 │   ├── css/
-│   │   └── tailwind.min.css       # 2.9M - Tailwind CSS v2.2.19
+│   │   ├── tailwind.min.css              # 2.9M - Tailwind CSS v2.2.19
+│   │   └── vendor/
+│   │       └── flatpickr.min.css         # 16K - Flatpickr v4.6.13
 │   └── js/
 │       └── vendor/
-│           └── alpine.min.js      # 44K - Alpine.js v3.13.3
+│           ├── alpine.min.js             # 44K - Alpine.js v3.13.3
+│           ├── chart.umd.min.js          # 205K - Chart.js v4.4.1
+│           └── flatpickr.min.js          # 51K - Flatpickr v4.6.13
 ├── shop/
 │   └── css/
-│       └── shop.css               # Shop-specific styles
+│       └── shop.css                      # Shop-specific styles
 ├── vendor/
 │   └── css/
-│       └── tailwind.output.css    # Vendor-specific overrides
+│       └── tailwind.output.css           # Vendor-specific overrides
 └── admin/
    └── css/
-        └── tailwind.output.css    # Admin-specific overrides
+        └── tailwind.output.css           # Admin-specific overrides
+
+app/templates/shared/
+├── includes/
+│   └── optional-libs.html                # CDN fallback loaders for Chart.js & Flatpickr
+└── macros/
+    ├── charts.html                       # Chart.js wrapper macros
+    └── datepicker.html                   # Flatpickr wrapper macros
 ```

 ## Frontend-Specific Implementations
@@ -217,7 +310,33 @@ cd static/shared/js/vendor
 curl -o alpine.min.js https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js
 ```

-**Important:** Update both the local file AND the CDN URL in all three base templates.
+To update Chart.js:
+
+```bash
+cd static/shared/js/vendor
+curl -o chart.umd.min.js https://cdn.jsdelivr.net/npm/chart.js@4.4.1/dist/chart.umd.min.js
+```
+
+To update Flatpickr:
+
+```bash
+# JavaScript
+cd static/shared/js/vendor
+curl -o flatpickr.min.js https://cdn.jsdelivr.net/npm/flatpickr@4.6.13/dist/flatpickr.min.js
+
+# CSS
+cd static/shared/css/vendor
+curl -o flatpickr.min.css https://cdn.jsdelivr.net/npm/flatpickr@4.6.13/dist/flatpickr.min.css
+```
+
+**Important:** Update both the local file AND the CDN URL in the following locations:
+
+| Asset | Update Location |
+|-------|-----------------|
+| Tailwind CSS | All three `base.html` templates |
+| Alpine.js | All three `base.html` templates |
+| Chart.js | `shared/includes/optional-libs.html` |
+| Flatpickr | `shared/includes/optional-libs.html` |

 ## Production Deployment

@@ -226,6 +345,8 @@ curl -o alpine.min.js https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.
 Before deploying to production, verify:

 - [ ] Local asset files exist in `static/shared/`
+- [ ] Core assets: `tailwind.min.css`, `alpine.min.js`
+- [ ] Optional assets: `chart.umd.min.js`, `flatpickr.min.js`, `flatpickr.min.css`
 - [ ] File permissions are correct (readable by web server)
 - [ ] Static file serving is enabled in FastAPI
 - [ ] CDN URLs are accessible from production network
@@ -239,9 +360,14 @@ Ensure local assets are included in Docker image:
 # Dockerfile
 COPY static/ /app/static/

-# Verify files exist
+# Verify core files exist
 RUN test -f /app/static/shared/css/tailwind.min.css && \
    test -f /app/static/shared/js/vendor/alpine.min.js
+
+# Verify optional library files exist
+RUN test -f /app/static/shared/js/vendor/chart.umd.min.js && \
+    test -f /app/static/shared/js/vendor/flatpickr.min.js && \
+    test -f /app/static/shared/css/vendor/flatpickr.min.css
 ```

 ### Static File Configuration
--- a/docs/frontend/shared/jinja-macros.md
+++ b/docs/frontend/shared/jinja-macros.md
--- a/docs/frontend/shared/ui-components.md
+++ b/docs/frontend/shared/ui-components.md
@@ -12,6 +12,22 @@ The admin panel uses a consistent set of UI components built with Tailwind CSS a

 **Live Component Library:** Visit `/admin/components` in the admin panel to see all components with copy-paste ready code.

+!!! tip "Use Jinja Macros Instead"
+    For new development, prefer using the **[Jinja Macros Library](jinja-macros.md)** instead of copy-pasting HTML. Macros provide:
+
+    - **Consistency:** Same styling across all pages
+    - **Maintainability:** Update once, apply everywhere
+    - **Less code:** Parameters instead of full HTML
+    - **Type safety:** Built-in Alpine.js bindings
+
+    ```jinja
+    {# Instead of 20 lines of HTML... #}
+    {% from 'shared/macros/buttons.html' import btn_primary %}
+    {{ btn_primary('Save Changes', icon='check', onclick='save()') }}
+    ```
+
+    See [Jinja Macros Library](jinja-macros.md) for full documentation.
+
 ---

 ## Page Layout Structure
@@ -462,6 +478,10 @@ function adminResourceList() {

 ## Related Documentation

+- **[Jinja Macros Library](jinja-macros.md)** - Reusable macro components (recommended)
+- [Pagination Guide](pagination.md)
+- [CDN Fallback Strategy](../cdn-fallback-strategy.md)
 - [Tailwind CSS](../tailwind-css.md)
+- [Icons Guide](../../development/icons-guide.md)
 - [Tailwind CSS Official Docs](https://tailwindcss.com/docs)
 - [Alpine.js Official Docs](https://alpinejs.dev/)