rick/LEDMatrix
1
0
Fork 0
mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-08-02 17:28:05 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add settings tooltips and search to the web UI

Browse Source 
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
This commit is contained in:
Claude
2026-07-08 15:01:19 +00:00
parent 63a233f3ed
commit 58a28f3a14
13 changed files with 1044 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files
web_interface/static/v3/js/tooltips.js
+161
View File
@@ -0,0 +1,161 @@
/*
* tooltips.js — accessible, delegated tooltip controller for the v3 web UI.
*
* A single controller handles every `.help-tip` trigger on the page, including
* ones inside partials that HTMX swaps in later, with zero per-field wiring.
* Triggers are emitted by the `help_tip` Jinja macro (partials/_macros.html) as
* <button class="help-tip" data-tooltip="..."><i class="fas fa-circle-info">.
*
* Behaviour:
* - hover (mouse) -> show / hide
* - keyboard focus -> show / hide (only for :focus-visible)
* - click / tap -> toggle (the touch path)
* - Escape / outside click -> hide
* The tooltip text is set via textContent (XSS-safe) and supports "\n" line
* breaks via CSS `white-space: pre-line`. Styling lives in app.css and uses the
* --color-* theme vars, so light/dark mode work automatically.
*/
(function () {
'use strict';
if (window._tooltipsInit) return;
window._tooltipsInit = true;
var panel = null;
var currentTrigger = null;
function getPanel() {
if (panel) return panel;
panel = document.createElement('div');
panel.id = 'ledm-tooltip';
panel.setAttribute('role', 'tooltip');
panel.hidden = true;
document.body.appendChild(panel);
return panel;
}
function positionPanel(trigger) {
var p = getPanel();
var margin = 8;
var rect = trigger.getBoundingClientRect();
var pw = p.offsetWidth;
var ph = p.offsetHeight;
var vw = document.documentElement.clientWidth;
var vh = document.documentElement.clientHeight;
// Prefer above the trigger; flip below if it would clip the top.
var top = rect.top - ph - margin;
var placedBelow = false;
if (top < margin) {
top = rect.bottom + margin;
placedBelow = true;
}
// Keep it on screen vertically as a last resort.
if (top + ph > vh - margin) top = Math.max(margin, vh - ph - margin);
// Center horizontally on the trigger, clamped to the viewport.
var left = rect.left + rect.width / 2 - pw / 2;
if (left < margin) left = margin;
if (left + pw > vw - margin) left = Math.max(margin, vw - pw - margin);
p.style.top = Math.round(top) + 'px';
p.style.left = Math.round(left) + 'px';
p.setAttribute('data-placement', placedBelow ? 'below' : 'above');
}
function show(trigger) {
var text = trigger.getAttribute('data-tooltip');
if (!text) return;
var p = getPanel();
p.textContent = text;
p.hidden = false;
// Measure after it is displayed, then position.
positionPanel(trigger);
trigger.setAttribute('aria-describedby', 'ledm-tooltip');
currentTrigger = trigger;
}
function hide() {
if (!panel) return;
panel.hidden = true;
if (currentTrigger) {
currentTrigger.removeAttribute('aria-describedby');
currentTrigger = null;
}
}
function triggerFrom(target) {
return target && target.closest ? target.closest('.help-tip') : null;
}
// --- Delegated listeners on document (survive HTMX swaps) ---
document.addEventListener('mouseover', function (e) {
var t = triggerFrom(e.target);
if (t) show(t);
});
document.addEventListener('mouseout', function (e) {
var t = triggerFrom(e.target);
if (!t) return;
// Ignore moves that stay within the same trigger.
var to = e.relatedTarget;
if (to && t.contains(to)) return;
if (currentTrigger === t) hide();
});
document.addEventListener('focusin', function (e) {
var t = triggerFrom(e.target);
if (!t) return;
// Only auto-show on keyboard focus, so a mouse/touch focus does not
// fight the click handler below.
var focusVisible = true;
try {
focusVisible = t.matches(':focus-visible');
} catch (err) {
focusVisible = true; // older browsers: fall back to always show
}
if (focusVisible) show(t);
});
document.addEventListener('focusout', function (e) {
var t = triggerFrom(e.target);
if (t && currentTrigger === t) hide();
});
document.addEventListener('click', function (e) {
var t = triggerFrom(e.target);
if (t) {
// Prevent an enclosing <label> from toggling its control, and
// prevent form submission.
e.preventDefault();
e.stopPropagation();
if (currentTrigger === t && !getPanel().hidden) {
hide();
} else {
show(t);
}
return;
}
// Click anywhere else closes an open tooltip.
if (panel && !panel.hidden && !panel.contains(e.target)) hide();
});
document.addEventListener('keydown', function (e) {
if (e.key === 'Escape' && panel && !panel.hidden) hide();
});
// Reposition while visible; close when content is swapped out.
window.addEventListener('scroll', function () {
if (currentTrigger && panel && !panel.hidden) positionPanel(currentTrigger);
}, true);
window.addEventListener('resize', function () {
if (currentTrigger && panel && !panel.hidden) positionPanel(currentTrigger);
});
document.body.addEventListener('htmx:afterSwap', function () {
// The current trigger may have been removed by the swap.
if (currentTrigger && !document.body.contains(currentTrigger)) hide();
});
console.log('[Tooltips] controller registered');
})();