From 375a0a0ed7eda605958c7b4a4cf0c3460c564f7c Mon Sep 17 00:00:00 2001
From: Samir Boulahtit <samir.boulahtit@wizard.lu>
Date: Sun, 21 Dec 2025 21:15:39 +0100
Subject: [PATCH] docs: document action_dropdown macro in jinja-macros guide
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add documentation for the new action_dropdown macro including:
- Full parameter table with defaults
- Usage example with caller block pattern
- Features explanation for loading state behavior

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/frontend/shared/jinja-macros.md | 35 +++++++++++++++++++++++++++-
 1 file changed, 34 insertions(+), 1 deletion(-)

diff --git a/docs/frontend/shared/jinja-macros.md b/docs/frontend/shared/jinja-macros.md
index 3ceaeaa2..556dfabc 100644
--- a/docs/frontend/shared/jinja-macros.md
+++ b/docs/frontend/shared/jinja-macros.md
@@ -562,7 +562,7 @@ Time-only picker.
 **File:** `shared/macros/dropdowns.html`
 
 ```jinja
-{% from 'shared/macros/dropdowns.html' import dropdown, context_menu, dropdown_item, dropdown_divider %}
+{% from 'shared/macros/dropdowns.html' import dropdown, action_dropdown, context_menu, dropdown_item, dropdown_divider %}
 ```
 
 ### dropdown
@@ -586,6 +586,39 @@ Button with dropdown menu.
 | `icon` | string | `'chevron-down'` | Button icon |
 | `width` | string | `'w-48'` | Dropdown width |
 
+### action_dropdown
+
+Dropdown with loading/disabled state support for action buttons. Uses external Alpine.js state from parent component.
+
+```jinja
+{% call action_dropdown(
+    label='Run Scan',
+    loading_label='Scanning...',
+    open_var='scanDropdownOpen',
+    loading_var='scanning',
+    icon='search'
+) %}
+    {{ dropdown_item('Run All', 'runScan("all"); scanDropdownOpen = false') }}
+    {{ dropdown_item('Run Selected', 'runScan("selected"); scanDropdownOpen = false') }}
+{% endcall %}
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `label` | string | required | Button label |
+| `loading_label` | string | `'Loading...'` | Label shown when loading |
+| `open_var` | string | `'isDropdownOpen'` | Alpine.js variable for open state |
+| `loading_var` | string | `'isLoading'` | Alpine.js variable for loading/disabled state |
+| `icon` | string | `none` | Button icon (before label) |
+| `position` | string | `'right'` | `'left'`, `'right'` |
+| `variant` | string | `'primary'` | `'primary'`, `'secondary'` |
+| `width` | string | `'w-48'` | Dropdown width |
+
+**Features:**
+- Button is disabled when `loading_var` is true
+- Shows spinner icon and `loading_label` when loading
+- Uses external state (no `x-data` wrapper - expects parent component to define variables)
+
 ### context_menu
 
 Three-dot context menu (for table rows).