fix(web): harden, polish and optimize the web UI per the Sept 2026 audit (#568)

* fix(web): harden, polish and optimize the web UI per the September 2026 audit

Works through docs/archive/WEB_UI_AUDIT_2026-09.md (health 8/20).

Implementation integrity (P0)
- app.css now defines every utility class the templates and JS use,
  including .hidden, so the ~145 JS show/hide toggles work. Button reset,
  and base component rules (.btn, .form-control) wrapped in :where() so
  utility classes on the same element win. New static-audit test fails
  when a used utility class has no rule.

Accessibility
- Focus rings render (the old ring rule referenced undefined variables);
  one :focus-visible outline everywhere; skip link; labelled nav landmarks.
- Shared dialog helper (js/utils/dialog.js): role/aria-modal, focus trap,
  Escape, focus return, applied to every modal.
- Named icon-only buttons and labelled ~70 form fields.
- Toasts announced once; errors persist >= 10s; one showNotification.
- Captive WiFi page: live region, timeouts, dark mode, 16px inputs.

Performance (Pi Zero 2 W)
- SSE streams and tab timers pause when hidden or off-tab; the display
  stream only runs while a preview is visible. app-shell.js deferred.
- Widget scripts served as one versioned bundle (/assets/widgets.js):
  52 -> 21 script tags, 66 -> 35 requests on first load.
- Stdlib gzip fallback when flask-compress is missing: first-load JS/CSS
  1358 KB -> 291 KB on the wire. SSE untouched.

Theming and responsive
- File managers, form fields and Fonts upload on theme tokens; bare
  inputs themed in dark mode; no more white surfaces.
- No horizontal overflow at 375px on any tab; 44px touch targets on
  coarse pointers; reduced-motion respected; header title truncates.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(web): clear Codacy findings on #568

- json-file-manager: focus-trap releases kept in a Map (no dynamic
  property access or delete; no value-returning forEach callback)
- notification / schedule-picker: style and day-label lookups via Map
- app.js: move the pending-queue assignment out of the expression
- diff_viewer / error_handler: named function declarations instead of
  arrow consts

No behavior change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* test: check the OAuth widget ships in the widget bundle

base.html no longer tags widget scripts one by one; they load through
/assets/widgets.js. Assert the page requests the bundle and the bundle
contains google-oauth.js, which is what the test was protecting.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(web): address review feedback on #568

- widget bundle version fingerprints every file (name, mtime_ns, size)
- gzip fallback appends Accept-Encoding to an existing Vary header
- dialog helper: releasing a non-top dialog no longer moves focus out of
  the dialog the user is in
- labels: file-upload targets its file input; fallback config fields get
  label for/id pairs; native color input has a fallback name
- utility audit also reads class names inside bound :class expressions

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(web): give the native color-picker input an accessible name

CodeRabbit flagged this on PR #568 as an outside-diff finding (never
posted inline, so it was missed in the round of fixes that addressed
the other 6 review comments). The <input type="color"> only carried a
title attribute; screen readers don't reliably announce title, and
there's no other label naming the control when showHexInput is false.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(web): clear Codacy findings in app-shell.js

- drop the unused catch binding on the SSE JSON parse
- move the pending-notification queue assignment out of the expression

No behavior change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix(web): contain plugin widgets/ dir and bound style-editor retries

From CodeRabbit review on #568 (code that arrived with the main merge):
- serve_plugin_widget resolves widgets/ with resolve_under before
  resolving the manifest script under it, so a symlinked widgets
  directory can't become the containment base (CWE-22). New test.
- style-editor init stops polling after ~10s when the widget never
  registers and leaves the plain fallback fields in place.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Chuck
2026-09-14 09:42:24 -04:00
committed by GitHub
co-authored by Claude Opus 5
parent 69d408b321
commit d1e821c625
45 changed files with 2869 additions and 870 deletions
+117 -78
View File
@@ -7,95 +7,97 @@
/**
* Comprehensive error code to user-friendly message mapping.
* Used only when the server response carries no message of its own.
*/
const ERROR_MESSAGES = {
// Configuration errors
'CONFIG_SAVE_FAILED': 'Failed to save configuration',
'CONFIG_LOAD_FAILED': 'Failed to load configuration',
'CONFIG_VALIDATION_FAILED': 'Configuration validation failed',
'CONFIG_ROLLBACK_FAILED': 'Failed to rollback configuration',
'CONFIG_SAVE_FAILED': "Couldn't save your settings. Check the values and try again",
'CONFIG_LOAD_FAILED': "Couldn't load your settings. Reload the page to try again",
'CONFIG_VALIDATION_FAILED': 'Some settings have invalid values. Fix the highlighted fields and save again',
'CONFIG_ROLLBACK_FAILED': "Couldn't restore the previous settings. Try again, or restore from Backup & Restore",
// Plugin errors
'PLUGIN_NOT_FOUND': 'Plugin not found',
'PLUGIN_INSTALL_FAILED': 'Failed to install plugin',
'PLUGIN_UPDATE_FAILED': 'Failed to update plugin',
'PLUGIN_UNINSTALL_FAILED': 'Failed to uninstall plugin',
'PLUGIN_LOAD_FAILED': 'Failed to load plugin',
'PLUGIN_OPERATION_CONFLICT': 'Plugin operation conflict - another operation is in progress',
'PLUGIN_NOT_FOUND': "That plugin isn't installed. Check the Plugin Manager",
'PLUGIN_INSTALL_FAILED': "Couldn't install the plugin. Check the Pi's internet connection and try again",
'PLUGIN_UPDATE_FAILED': "Couldn't update the plugin. Try again in a moment",
'PLUGIN_UNINSTALL_FAILED': "Couldn't uninstall the plugin. Try again in a moment",
'PLUGIN_LOAD_FAILED': "The plugin couldn't start. Check the Logs tab for details",
'PLUGIN_OPERATION_CONFLICT': 'Another plugin operation is still running. Wait for it to finish, then try again',
// Validation errors
'VALIDATION_ERROR': 'Validation error',
'SCHEMA_VALIDATION_FAILED': 'Configuration schema validation failed',
'INVALID_INPUT': 'Invalid input provided',
'VALIDATION_ERROR': 'Some values are invalid. Fix them and try again',
'SCHEMA_VALIDATION_FAILED': "Some settings don't match what the plugin expects. Fix them and save again",
'INVALID_INPUT': "That value isn't valid. Check it and try again",
// Network errors
'NETWORK_ERROR': 'Network error occurred',
'API_ERROR': 'API request failed',
'TIMEOUT': 'Operation timed out',
'NETWORK_ERROR': "Couldn't reach the LEDMatrix device. Check that it's on and connected, then try again",
'API_ERROR': 'The request failed. Try again in a moment',
'TIMEOUT': 'This took too long to respond. Try again in a moment',
// Permission errors
'PERMISSION_DENIED': 'Permission denied',
'FILE_PERMISSION_ERROR': 'File permission error',
'PERMISSION_DENIED': "LEDMatrix doesn't have permission to do that. See the troubleshooting guide",
'FILE_PERMISSION_ERROR': "LEDMatrix can't write a file it needs. See the troubleshooting guide",
// System errors
'SYSTEM_ERROR': 'System error occurred',
'SERVICE_UNAVAILABLE': 'Service unavailable',
'SYSTEM_ERROR': 'Something went wrong on the device. Check the Logs tab for details',
'SERVICE_UNAVAILABLE': 'The LEDMatrix service is not running. Restart it from the Overview tab',
// Unknown errors
'UNKNOWN_ERROR': 'An unknown error occurred'
'UNKNOWN_ERROR': 'Something went wrong. Try again, and check the Logs tab if it keeps happening'
};
/**
* Error code to troubleshooting documentation links.
*/
const TROUBLESHOOTING_URL = 'https://github.com/ChuckBuilds/LEDMatrix/blob/main/docs/TROUBLESHOOTING.md';
const ERROR_DOCS = {
'CONFIG_SAVE_FAILED': 'https://github.com/your-repo/LEDMatrix/wiki/Troubleshooting#configuration-errors',
'CONFIG_VALIDATION_FAILED': 'https://github.com/your-repo/LEDMatrix/wiki/Troubleshooting#validation-errors',
'PLUGIN_INSTALL_FAILED': 'https://github.com/your-repo/LEDMatrix/wiki/Troubleshooting#plugin-installation',
'PLUGIN_OPERATION_CONFLICT': 'https://github.com/your-repo/LEDMatrix/wiki/Troubleshooting#plugin-operations',
'PERMISSION_DENIED': 'https://github.com/your-repo/LEDMatrix/wiki/Troubleshooting#permissions',
'FILE_PERMISSION_ERROR': 'https://github.com/your-repo/LEDMatrix/wiki/Troubleshooting#permissions'
'CONFIG_SAVE_FAILED': TROUBLESHOOTING_URL + '#4-check-configuration',
'CONFIG_VALIDATION_FAILED': TROUBLESHOOTING_URL + '#4-check-configuration',
'PLUGIN_INSTALL_FAILED': TROUBLESHOOTING_URL + '#plugin-issues',
'PLUGIN_OPERATION_CONFLICT': TROUBLESHOOTING_URL + '#plugin-issues',
'PERMISSION_DENIED': TROUBLESHOOTING_URL + '#permission-issues',
'FILE_PERMISSION_ERROR': TROUBLESHOOTING_URL + '#permission-issues'
};
/**
* Format error message for display to user.
*
*
* @param {Object} error - Error object from API response
* @returns {string} Formatted error message
*/
function formatError(error) {
if (!error) {
return 'An unknown error occurred';
return ERROR_MESSAGES.UNKNOWN_ERROR;
}
// If error is a string, return it
if (typeof error === 'string') {
return error;
}
// If error has a message, use it
if (error.message) {
return error.message;
}
// If error has error_code, format it
if (error.error_code) {
const message = ERROR_MESSAGES[error.error_code] || error.message || 'An error occurred';
const message = ERROR_MESSAGES[error.error_code] || error.message || ERROR_MESSAGES.UNKNOWN_ERROR;
// Add details if available
if (error.details) {
return `${message}: ${error.details}`;
}
return message;
}
return 'An error occurred';
return ERROR_MESSAGES.UNKNOWN_ERROR;
}
/**
* Get suggested fixes for an error.
*
*
* @param {Object} error - Error object from API response
* @returns {Array<string>} Array of suggested fixes
*/
@@ -103,13 +105,13 @@ function getSuggestedFixes(error) {
if (!error || !error.suggested_fixes) {
return [];
}
return error.suggested_fixes;
}
/**
* Display error with suggestions in a rich UI.
*
*
* @param {Object} error - Error object from API response
* @param {string} context - Optional context about what was being done
* @param {Object} options - Display options
@@ -121,19 +123,19 @@ function displayError(error, context = null, options = {}) {
const suggestions = getSuggestedFixes(error);
const errorCode = error?.error_code;
const docLink = errorCode ? ERROR_DOCS[errorCode] : null;
// Build full message
let fullMessage = message;
if (context) {
fullMessage = `${context}: ${message}`;
}
if (suggestions.length > 0) {
fullMessage += '\n\nSuggested fixes:\n' + suggestions.map(s => `• ${s}`).join('\n');
}
// If showDetails is true, show a rich error modal
if (options.showDetails !== false && (suggestions.length > 0 || docLink || error.details)) {
if (options.showDetails !== false && (suggestions.length > 0 || docLink || error?.details)) {
showErrorModal(error, context, message, suggestions, docLink);
} else {
// Simple notification
@@ -146,9 +148,12 @@ function displayError(error, context = null, options = {}) {
}
}
// Release function for the open error modal's focus trap (see utils/dialog.js).
let errorModalRelease = null;
/**
* Show a rich error modal with details, suggestions, and copy button.
*
*
* @param {Object} error - Error object
* @param {string} context - Context
* @param {string} message - Formatted message
@@ -156,6 +161,9 @@ function displayError(error, context = null, options = {}) {
* @param {string} docLink - Documentation link
*/
function showErrorModal(error, context, message, suggestions, docLink) {
error = error || {};
suggestions = suggestions || [];
// Create modal container if it doesn't exist
let modalContainer = document.getElementById('error-modal-container');
if (!modalContainer) {
@@ -165,7 +173,13 @@ function showErrorModal(error, context, message, suggestions, docLink) {
modalContainer.style.display = 'none';
document.body.appendChild(modalContainer);
}
// Re-opening while open: release the previous trap before replacing it.
if (errorModalRelease) {
errorModalRelease();
errorModalRelease = null;
}
// Build modal content
const contextText = context ? `<div class="text-sm text-gray-600 mb-2">${escapeHtml(context)}</div>` : '';
const suggestionsHtml = suggestions.length > 0 ? `
@@ -176,15 +190,15 @@ function showErrorModal(error, context, message, suggestions, docLink) {
</ul>
</div>
` : '';
const docLinkHtml = docLink ? `
<div class="mt-4">
<a href="${docLink}" target="_blank" class="text-blue-600 hover:text-blue-800 text-sm underline">
<i class="fas fa-book mr-1"></i>View troubleshooting guide
<a href="${escapeHtml(docLink)}" target="_blank" rel="noopener noreferrer" class="text-blue-600 hover:text-blue-800 text-sm underline">
<i class="fas fa-book mr-1" aria-hidden="true"></i>View troubleshooting guide<span style="position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;"> (opens in a new tab)</span>
</a>
</div>
` : '';
const detailsHtml = error.details ? `
<div class="mt-4">
<details class="cursor-pointer">
@@ -193,26 +207,26 @@ function showErrorModal(error, context, message, suggestions, docLink) {
</details>
</div>
` : '';
const errorCodeHtml = error.error_code ? `
<div class="mt-2 text-xs text-gray-500">
Error code: <code class="bg-gray-100 px-1 py-0.5 rounded">${escapeHtml(error.error_code)}</code>
</div>
` : '';
modalContainer.innerHTML = `
<div class="flex items-center justify-center min-h-screen px-4 pt-4 pb-20 text-center sm:block sm:p-0">
<div class="fixed inset-0 bg-gray-500 bg-opacity-75 transition-opacity" onclick="window.errorHandler.closeErrorModal()"></div>
<div class="inline-block align-bottom bg-white rounded-lg text-left overflow-hidden shadow-xl transform transition-all sm:my-8 sm:align-middle sm:max-w-lg sm:w-full">
<div class="fixed inset-0 bg-gray-500 bg-opacity-75 transition-opacity" aria-hidden="true" onclick="window.errorHandler.closeErrorModal()"></div>
<div id="error-modal-panel" class="inline-block align-bottom bg-white rounded-lg text-left overflow-hidden shadow-xl transform transition-all sm:my-8 sm:align-middle sm:max-w-lg sm:w-full" style="position:relative;">
<div class="bg-white px-4 pt-5 pb-4 sm:p-6 sm:pb-4">
<div class="sm:flex sm:items-start">
<div class="mx-auto flex-shrink-0 flex items-center justify-center h-12 w-12 rounded-full bg-red-100 sm:mx-0 sm:h-10 sm:w-10">
<div class="mx-auto flex-shrink-0 flex items-center justify-center h-12 w-12 rounded-full bg-red-100 sm:mx-0 sm:h-10 sm:w-10" aria-hidden="true">
<i class="fas fa-exclamation-triangle text-red-600"></i>
</div>
<div class="mt-3 text-center sm:mt-0 sm:ml-4 sm:text-left flex-1">
<h3 class="text-lg leading-6 font-medium text-gray-900">Error</h3>
<div class="mt-2">
<h3 id="error-modal-title" class="text-lg leading-6 font-medium text-gray-900">Something went wrong</h3>
<div class="mt-2" id="error-modal-description">
${contextText}
<p class="text-sm text-gray-500">${escapeHtml(message)}</p>
${errorCodeHtml}
@@ -224,11 +238,11 @@ function showErrorModal(error, context, message, suggestions, docLink) {
</div>
</div>
<div class="bg-gray-50 px-4 py-3 sm:px-6 sm:flex sm:flex-row-reverse">
<button id="error-modal-copy-btn"
<button type="button" id="error-modal-copy-btn"
class="w-full inline-flex justify-center rounded-md border border-transparent shadow-sm px-4 py-2 bg-blue-600 text-base font-medium text-white hover:bg-blue-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-blue-500 sm:ml-3 sm:w-auto sm:text-sm">
<i class="fas fa-copy mr-2"></i>Copy Error Details
<i class="fas fa-copy mr-2" aria-hidden="true"></i>Copy Error Details
</button>
<button onclick="window.errorHandler.closeErrorModal()"
<button type="button" id="error-modal-close-btn" onclick="window.errorHandler.closeErrorModal()"
class="mt-3 w-full inline-flex justify-center rounded-md border border-gray-300 shadow-sm px-4 py-2 bg-white text-base font-medium text-gray-700 hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500 sm:mt-0 sm:ml-3 sm:w-auto sm:text-sm">
Close
</button>
@@ -236,7 +250,7 @@ function showErrorModal(error, context, message, suggestions, docLink) {
</div>
</div>
`;
// Attach event listener to copy button
const copyBtn = modalContainer.querySelector('#error-modal-copy-btn');
if (copyBtn) {
@@ -244,8 +258,20 @@ function showErrorModal(error, context, message, suggestions, docLink) {
copyErrorDetails(error);
});
}
modalContainer.style.display = 'block';
const panel = modalContainer.querySelector('#error-modal-panel');
if (panel) {
panel.setAttribute('aria-describedby', 'error-modal-description');
if (window.LEDDialog) {
errorModalRelease = window.LEDDialog.trap(panel, {
labelledBy: 'error-modal-title',
initialFocus: '#error-modal-close-btn',
onEscape: closeErrorModal
});
}
}
}
/**
@@ -256,6 +282,11 @@ function closeErrorModal() {
if (modalContainer) {
modalContainer.style.display = 'none';
}
if (errorModalRelease) {
const release = errorModalRelease;
errorModalRelease = null;
release();
}
}
/**
@@ -277,27 +308,35 @@ function escapeHtml(text) {
/**
* Copy error details to clipboard.
*
*
* @param {Object} error - Error object from API response
*/
function copyErrorDetails(error) {
const errorText = JSON.stringify(error, null, 2);
function copyFailed(err) {
console.error('Failed to copy error details:', err);
if (typeof showNotification === 'function') {
showNotification("Couldn't copy to the clipboard. Open Technical details and copy the text by hand.", 'warning');
}
}
if (navigator.clipboard && navigator.clipboard.writeText) {
navigator.clipboard.writeText(errorText).then(() => {
if (typeof showNotification === 'function') {
showNotification('Error details copied to clipboard', 'success');
}
}).catch(err => {
console.error('Failed to copy error details:', err);
});
}).catch(copyFailed);
} else {
// Fallback for older browsers
const textArea = document.createElement('textarea');
textArea.value = errorText;
textArea.style.position = 'fixed';
textArea.style.opacity = '0';
document.body.appendChild(textArea);
// Keep focus inside the open dialog while copying.
const panel = document.getElementById('error-modal-panel');
const host = panel && panel.offsetParent !== null ? panel : document.body;
const returnFocus = document.activeElement;
host.appendChild(textArea);
textArea.select();
try {
document.execCommand('copy');
@@ -305,9 +344,10 @@ function copyErrorDetails(error) {
showNotification('Error details copied to clipboard', 'success');
}
} catch (err) {
console.error('Failed to copy error details:', err);
copyFailed(err);
}
document.body.removeChild(textArea);
host.removeChild(textArea);
if (returnFocus && typeof returnFocus.focus === 'function') returnFocus.focus();
}
}
@@ -336,4 +376,3 @@ if (typeof module !== 'undefined' && module.exports) {
ERROR_DOCS
};
}