mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-08-01 08:48:05 +00:00
Add settings tooltips and search to the web UI (#387)
* Add settings tooltips and search to the web UI Help users quickly find settings and understand how each one works. Tooltips: a new delegated controller (static/v3/js/tooltips.js) drives an accessible (i) info tooltip that appears on hover, keyboard focus, and tap. A shared `help_tip` Jinja macro (partials/_macros.html) emits the trigger; the plugin config macro and the core settings partials now surface help text through it. Per the design, the always-visible field help paragraphs are folded into the tooltip to declutter the forms, and the hardware/display settings carry authored detail (default, range, recommendation). Search: a global header search box finds settings across every settings tab — even ones not yet opened — via a lazy client-side index built by scanning the same field markup (static/v3/js/settings-search.js). Selecting a result switches tabs, waits for the field to load, then scrolls to and flashes it. A per-tab filter box hides non-matching fields on the current tab. Plugin settings get tooltips for free by reusing each field's schema `description`; every settings field also gets a stable `setting-<tab>-<key>` anchor id for search navigation. Styling uses the existing --color-* theme vars so light/dark mode both work, and honors prefers-reduced-motion. Adds Flask render smoke tests that assert each settings partial ships tooltips, anchors, and a filter box. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz * Address Codacy static-analysis findings in settings JS Refactor the two new modules to clear the flagged patterns without any behavior change: - Build the search dropdown with DOM nodes + textContent instead of innerHTML string concatenation, removing the XSS sinks and the manual escapeHtml helper it needed. - Replace numeric index access (index[i], terms[j], opts[idx], currentResults[i]) with array iteration methods, NodeList.item(), and Array.prototype.at() to clear detect-object-injection. - Use === via a shared termsMatch() helper, optional-catch binding, and drop a useless initial assignment. Verified with ESLint (eslint:recommended + eslint-plugin-security) at zero findings and re-ran the headless-Chromium behavior test (tooltip, per-tab filter, global search navigation) — all green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz * Reduce complexity of revealAncestors in settings search Extract isNodeHidden() and revealNode() helpers so revealAncestors drops below the cyclomatic-complexity threshold. No behavior change; verified with the headless-Chromium test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz * Resolve remaining Codacy findings in settings search - Validate plugin ids against a strict allowlist (mirroring the server's _SAFE_PLUGIN_ID_RE) before they can appear in a fetch path, so the request URL is never built from unvalidated input (Codacy: user-controlled URL). - Document that the fetched HTML is parsed into an inert document (scripts never run, never inserted into the live DOM) purely to read field text for the search index. - Declare block-scoped locals with const instead of var where they were nested inside conditionals (Codacy: var not at function root). No behavior change; re-verified with ESLint and the headless-Chromium test. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz * Serve the settings search index from the server as JSON Move index building off the client so there is no client-side HTML fetching or DOM parsing (resolves Codacy's variable-fetch and DOMParser flags on the read-only, same-origin index build). - Add GET /v3/settings/search-index (pages_v3.py): renders the settings partials server-side and extracts each field's anchor id, key, label, tooltip, and section with a small stdlib HTMLParser, then caches the result keyed on the installed-plugin set. Parsing the rendered HTML keeps anchor ids identical to the live DOM, so the index cannot drift. - settings-search.js: buildIndex() now does a single fetch of the literal endpoint + .json(); removed the per-partial fetch loop, DOMParser, scanDoc, CORE_TABS, and the plugin-id allowlist. Search, keyboard nav, navigation, and the per-tab filter are unchanged. Net: fewer requests and no client-side HTML parsing. Verified with a new endpoint test in test_web_settings_ui.py (12 pass) and the headless-Chromium test (tooltip, filter, search navigate + flash all green). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz * Address CodeRabbit review on settings search/tooltips - pages_v3: include Durations tab in the search index so setting-durations-* fields are actually indexed - test_web_settings_ui: assert setting-durations-clock is present in the search-index endpoint response - settings-search.js: on index fetch failure, reset buildPromise instead of caching an empty (truthy) index so search can retry - settings-search.js: filterScope returns null (not document) when no tab container matches, and the caller guards, so the per-tab filter can't hide fields across unrelated tabs - settings-search.js: refresh the stale header comment to describe the server-side JSON index flow - app.css: cap #settings-search-results height with overflow-y so the dropdown scrolls instead of overflowing small screens Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz * Fix stuck search dropdown; add plugin-tab nested-settings filter Global search: - Close the results dropdown on input blur (guarded, with a short delay) so it reliably dismisses when focus leaves — previously it could linger because the only outside-close was a document click that Alpine/HTMX handlers can swallow. - Clear the query text after navigating to a result so refocusing the box doesn't re-open stale results. - Also dismiss on htmx:afterSwap (tab changes / navigation). Per-tab filter (now on plugin tabs too): - Render the shared settings_filter box in the plugin Configuration panel. It auto-wires: the delegated input handler and filterScope already target .plugin-config-tab. - Teach applyTabFilter to reveal matches inside collapsed nested sections (render_nested_section defaults them shut), hide nested-section wrappers with no matches, and restore the original collapsed layout when cleared (only re-collapsing sections the filter itself opened). - Count a visible nested-section as content for its parent heading so the heading isn't hidden while a subsection below still has matches. Adds a plugin-config render test (filter box + nested anchors + tooltips). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz * Close search dropdown via capture-phase outside-click The dropdown could stay open after clicking away because the only outside-click close was a bubble-phase document listener. The v3 UI is one Alpine app() component full of HTMX/Alpine/widget click handlers; when a click lands inside an element that calls stopPropagation(), the event never bubbles to document and the close never runs. - Replace the bubble-phase document 'click' close with a capture-phase 'pointerdown' listener scoped to #settings-search-wrap. Capture runs before any bubbling stopPropagation can swallow the event, so it always fires; pointerdown also covers touch on the Pi screen. Clicking a result stays inside the wrap, so selection is unaffected. - Guard the debounced input handler so a delayed render can't re-open the box after focus has left (type-then-click-away race). Keeps the existing blur / Escape / htmx:afterSwap closes as secondary paths. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_014gZxznuxw8L92FUMBN3Nqz * Fix settings search dropdown not visually closing .hidden has no effect in this app: app.css is a hand-picked utility subset (no Tailwind build step) and never defines .hidden { display: none }. openResults()/closeResults() only toggled the class, so the dropdown stayed rendered (display: block) even once closeResults() ran - confirmed via computed style in a headless browser. Set style.display directly, matching the fallback already used by revealNode()/collapseNode() elsewhere in this file. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> --------- Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
Chuck
@@ -1,6 +1,7 @@
|
||||
from flask import Blueprint, render_template, flash
|
||||
from flask import Blueprint, render_template, flash, jsonify
|
||||
from jinja2 import TemplateNotFound
|
||||
from markupsafe import escape
|
||||
from html.parser import HTMLParser
|
||||
import json
|
||||
import logging
|
||||
import os
|
||||
@@ -22,6 +23,114 @@ plugin_store_manager = None
|
||||
|
||||
pages_v3 = Blueprint('pages_v3', __name__)
|
||||
|
||||
|
||||
class _SettingsIndexParser(HTMLParser):
|
||||
"""Extract searchable settings fields from a rendered partial's HTML.
|
||||
|
||||
Captures one entry per ``<div class="form-group" id="setting-…">``: the
|
||||
anchor id, ``data-setting-key``, the field's ``<label>`` text, the
|
||||
``.help-tip`` tooltip text (``data-tooltip``), and the nearest preceding
|
||||
``<h3>``/``<h4>`` section heading. Parsing the *rendered* HTML (rather than
|
||||
the schema) guarantees the anchor ids match the live DOM exactly, so the
|
||||
search index cannot drift from what users actually see.
|
||||
"""
|
||||
|
||||
def __init__(self, tab, tab_label):
|
||||
super().__init__(convert_charrefs=True)
|
||||
self.tab = tab
|
||||
self.tab_label = tab_label
|
||||
self.fields = []
|
||||
self._section = ''
|
||||
self._field = None
|
||||
self._depth = 0 # open-div depth within the current field
|
||||
self._in_label = False
|
||||
self._label_parts = []
|
||||
self._in_heading = False
|
||||
self._heading_parts = []
|
||||
|
||||
def handle_starttag(self, tag, attrs):
|
||||
a = {k: (v or '') for k, v in attrs}
|
||||
classes = a.get('class', '').split()
|
||||
# Section headings (only when not already inside a field)
|
||||
if tag in ('h3', 'h4') and self._field is None:
|
||||
self._in_heading = True
|
||||
self._heading_parts = []
|
||||
if tag == 'div':
|
||||
fid = a.get('id', '')
|
||||
if self._field is None and 'form-group' in classes and fid.startswith('setting-'):
|
||||
self._field = {
|
||||
'anchorId': fid,
|
||||
'key': a.get('data-setting-key', '') or fid[len('setting-'):],
|
||||
'label': '',
|
||||
'help': '',
|
||||
'section': self._section,
|
||||
'tab': self.tab,
|
||||
'tabLabel': self.tab_label,
|
||||
}
|
||||
self._depth = 1
|
||||
return
|
||||
if self._field is not None:
|
||||
self._depth += 1
|
||||
if self._field is not None:
|
||||
if tag == 'label' and not self._field['label']:
|
||||
self._in_label = True
|
||||
self._label_parts = []
|
||||
if tag == 'button' and 'help-tip' in classes and not self._field['help']:
|
||||
self._field['help'] = a.get('data-tooltip', '')
|
||||
|
||||
def handle_data(self, data):
|
||||
if self._in_label:
|
||||
self._label_parts.append(data)
|
||||
elif self._in_heading:
|
||||
self._heading_parts.append(data)
|
||||
|
||||
def handle_endtag(self, tag):
|
||||
if tag in ('h3', 'h4') and self._in_heading:
|
||||
self._in_heading = False
|
||||
self._section = ' '.join(''.join(self._heading_parts).split()).strip()
|
||||
return
|
||||
if self._field is None:
|
||||
return
|
||||
if tag == 'label' and self._in_label:
|
||||
self._in_label = False
|
||||
self._field['label'] = ' '.join(''.join(self._label_parts).split()).strip()
|
||||
elif tag == 'div':
|
||||
self._depth -= 1
|
||||
if self._depth <= 0:
|
||||
if self._field['label']:
|
||||
self.fields.append(self._field)
|
||||
self._field = None
|
||||
self._depth = 0
|
||||
|
||||
|
||||
def _partial_html(loader):
|
||||
"""Run a partial loader and return its HTML string ('' on error)."""
|
||||
try:
|
||||
result = loader()
|
||||
except Exception:
|
||||
logger.warning("search-index: partial render failed", exc_info=True)
|
||||
return ''
|
||||
if isinstance(result, str):
|
||||
return result
|
||||
if isinstance(result, tuple): # loaders return (msg, status) on error
|
||||
return ''
|
||||
try:
|
||||
return result.get_data(as_text=True)
|
||||
except Exception:
|
||||
return ''
|
||||
|
||||
|
||||
def _extract_settings_fields(html, tab, tab_label):
|
||||
parser = _SettingsIndexParser(tab, tab_label)
|
||||
parser.feed(html)
|
||||
return parser.fields
|
||||
|
||||
|
||||
# Cache the built index keyed on the installed-plugin set. Core labels/tooltips
|
||||
# are static template text, so only a change in installed plugins invalidates it.
|
||||
_SEARCH_INDEX_CACHE = {'sig': None, 'fields': None}
|
||||
|
||||
|
||||
@pages_v3.route('/')
|
||||
def index():
|
||||
"""Main v3 interface page"""
|
||||
@@ -111,6 +220,56 @@ def load_plugin_config_partial(plugin_id):
|
||||
return '<div class="text-red-500 p-4">Error loading plugin config; see logs for details</div>', 500
|
||||
|
||||
|
||||
@pages_v3.route('/settings/search-index')
|
||||
def settings_search_index():
|
||||
"""Return a flat JSON index of every searchable setting (core + plugin).
|
||||
|
||||
Powers the web UI's global settings search. Built by rendering the settings
|
||||
partials server-side and extracting field metadata, then cached per
|
||||
installed-plugin set so it is off the display's hot path.
|
||||
"""
|
||||
# Core settings tabs: (activeTab value, human label, loader).
|
||||
core_tabs = [
|
||||
('general', 'General', _load_general_partial),
|
||||
('display', 'Display', _load_display_partial),
|
||||
('durations', 'Durations', _load_durations_partial),
|
||||
('schedule', 'Schedule', _load_schedule_partial),
|
||||
('wifi', 'WiFi', _load_wifi_partial),
|
||||
]
|
||||
try:
|
||||
plugin_ids = []
|
||||
if pages_v3.plugin_manager:
|
||||
try:
|
||||
pages_v3.plugin_manager.discover_plugins()
|
||||
plugin_ids = sorted(
|
||||
pi.get('id') for pi in pages_v3.plugin_manager.get_all_plugin_info()
|
||||
if pi.get('id')
|
||||
)
|
||||
except Exception:
|
||||
logger.warning("search-index: could not enumerate plugins", exc_info=True)
|
||||
|
||||
sig = tuple(plugin_ids)
|
||||
if _SEARCH_INDEX_CACHE['sig'] == sig and _SEARCH_INDEX_CACHE['fields'] is not None:
|
||||
return jsonify({'fields': _SEARCH_INDEX_CACHE['fields']})
|
||||
|
||||
fields = []
|
||||
for tab, label, loader in core_tabs:
|
||||
fields.extend(_extract_settings_fields(_partial_html(loader), tab, label))
|
||||
|
||||
for pid in plugin_ids:
|
||||
info = pages_v3.plugin_manager.get_plugin_info(pid) or {}
|
||||
label = info.get('name', pid)
|
||||
html = _partial_html(lambda pid=pid: _load_plugin_config_partial(pid))
|
||||
fields.extend(_extract_settings_fields(html, pid, label))
|
||||
|
||||
_SEARCH_INDEX_CACHE['sig'] = sig
|
||||
_SEARCH_INDEX_CACHE['fields'] = fields
|
||||
return jsonify({'fields': fields})
|
||||
except Exception:
|
||||
logger.error("Error building settings search index", exc_info=True)
|
||||
return jsonify({'fields': []}), 500
|
||||
|
||||
|
||||
@pages_v3.route('/plugin-ui/<plugin_id>/web-ui/<path:filename>')
|
||||
def serve_plugin_web_ui(plugin_id, filename):
|
||||
"""Serve a plugin's web_ui/ HTML fragment as a standalone page.
|
||||
|
||||
Reference in New Issue
Block a user