From 726c7ea401a2789a546ab9b0271abc2d9ca06a8f Mon Sep 17 00:00:00 2001
From: Ross <xkjq@ymail.com>
Date: Thu, 13 Nov 2025 21:32:28 +0000
Subject: [PATCH] Enhance user search functionality with advanced search tips
 and help panel

---
 generic/forms.py | 40 +++++++++++++++++++++++++++++++++++++++-
 1 file changed, 39 insertions(+), 1 deletion(-)

diff --git a/generic/forms.py b/generic/forms.py
index 91a3aaab..5230ce39 100755
--- a/generic/forms.py
+++ b/generic/forms.py
@@ -622,13 +622,39 @@ class UserUserGroupForm(ModelForm):
                 </select>
 
                 <div class="mb-2">
-                    <div class="d-flex gap-2">
+                    <div class="d-flex gap-2 align-items-start">
                         <input type="search" id="{search_id}" class="form-control form-control-sm" placeholder="Search users by name, username or email" />
                         <select id="grade_filter_{self.name}" class="form-select form-select-sm" style="max-width:180px">
                             {grades_options}
                         </select>
+                        <!-- Help button for advanced search features -->
+                        <button type="button" id="user_search_help_btn_{self.name}" class="btn btn-sm btn-outline-secondary" aria-expanded="false" aria-controls="user_search_help_panel_{self.name}" title="Advanced search help">?</button>
                     </div>
+
                     <div id="{results_id}" class="mt-2"></div>
+
+                    <!-- Collapsible help panel (hidden by default) -->
+                    <div id="user_search_help_panel_{self.name}" class="card card-body mt-2 d-none" style="font-size:.9rem;">
+                        <strong>Advanced search tips</strong>
+                        <ul class="mb-0 mt-1">
+                            <li>Basic: type any part of a user's first name, last name, username or email (case-insensitive substring match). Example: <code>smith</code> or <code>joe@example.com</code>.</li>
+                            <li>Wildcards: use <code>*</code> or <code>%</code> as the query to return many users (use carefully). Wildcard queries return up to 50 results; normal queries return up to 10.</li>
+                            <li>Field-specific searches: prefix with <code>field:term</code> to restrict the search. Supported fields:
+                                <ul class="mb-0 mt-1">
+                                    <li><code>name:</code> or <code>full_name:</code> — matches first OR last name (e.g. <code>name:smith</code>).</li>
+                                    <li><code>first:</code> or <code>first_name:</code> — matches first name.</li>
+                                    <li><code>last:</code> or <code>last_name:</code> — matches last name.</li>
+                                    <li><code>email:</code> — matches email address.</li>
+                                    <li><code>username:</code> — matches username.</li>
+                                    <li><code>id:</code> or <code>pk:</code> — match by numeric user id (e.g. <code>id:123</code>).</li>
+                                    <li><code>grade:</code> — match by grade name or grade id (e.g. <code>grade:ST3</code> or <code>grade:2</code>).</li>
+                                </ul>
+                            </li>
+                            <li>Grade filter: use the grade dropdown next to the search box to narrow results by trainee grade in addition to your query.</li>
+                            <li>To add users, click the <em>Add</em> button beside a result. If an <em>Add all results</em> button appears, it will add all currently visible results.</li>
+                            <li>If you expect many matches, narrow your query or use a field-specific search to improve relevance and performance.</li>
+                        </ul>
+                    </div>
                 </div>
 
                 <div>
@@ -645,6 +671,8 @@ class UserUserGroupForm(ModelForm):
                         const select = document.getElementById('{field_id}');
                         const selectedList = document.getElementById('{selected_list_id}');
                         const gradeSelect = document.getElementById('grade_filter_{self.name}');
+                        const helpBtn = document.getElementById('user_search_help_btn_{self.name}');
+                        const helpPanel = document.getElementById('user_search_help_panel_{self.name}');
 
                         let timeout = null;
                         function fetchResults(q) {{
@@ -670,6 +698,16 @@ class UserUserGroupForm(ModelForm):
                             timeout = setTimeout(() => fetchResults(search.value), 50);
                         }});
 
+                        // Toggle help panel visibility
+                        if (helpBtn && helpPanel) {{
+                            helpBtn.addEventListener('click', function(e) {{
+                                e.preventDefault();
+                                helpPanel.classList.toggle('d-none');
+                                const expanded = !helpPanel.classList.contains('d-none');
+                                helpBtn.setAttribute('aria-expanded', expanded ? 'true' : 'false');
+                            }});
+                        }}
+
                         // fieldName for this widget instance
                         const widgetFieldName = '{self.name}';