mirror of
https://github.com/ChuckBuilds/LEDMatrix.git
synced 2026-04-10 13:02:59 +00:00
71584d4361
* chore: Update basketball-scoreboard submodule for odds font fix
* feat(widgets): Add widget registry system for plugin configuration forms
- Create core widget registry system (registry.js, base-widget.js)
- Extract existing widgets to separate modules:
- file-upload.js: Image upload with drag-and-drop, preview, delete, scheduling
- checkbox-group.js: Multi-select checkboxes for array fields
- custom-feeds.js: Table-based RSS feed editor with logo uploads
- Implement plugin widget loading system (plugin-loader.js)
- Add comprehensive documentation (widget-guide.md, README.md)
- Include example custom widget (example-color-picker.js)
- Maintain backwards compatibility with existing plugins
- All widget handlers available globally for existing functionality
This enables:
- Reusable UI components for plugin configuration forms
- Third-party plugins to create custom widgets without modifying LEDMatrix
- Modular widget architecture for future enhancements
Existing plugins (odds-ticker, static-image, news) continue to work without changes.
* fix(widgets): Security and correctness fixes for widget system
- base-widget.js: Fix escapeHtml to always escape (coerce to string first)
- base-widget.js: Add sanitizeId helper for safe DOM ID usage
- base-widget.js: Use DOM APIs in showError instead of innerHTML
- checkbox-group.js: Normalize types in setValue for consistent comparison
- custom-feeds.js: Implement setValue with full row creation logic
- example-color-picker.js: Validate hex colors before using in style attributes
- file-upload.js: Replace innerHTML with DOM creation to prevent XSS
- file-upload.js: Preserve open schedule editors when updating image list
- file-upload.js: Normalize types when filtering deleted files
- file-upload.js: Sanitize imageId in openImageSchedule and all schedule handlers
- file-upload.js: Fix max-files check order and use allowed_types from config
- README.md: Add security guidance for ID sanitization in examples
* fix(widgets): Additional security and error handling improvements
- scripts/update_plugin_repos.py: Add explicit UTF-8 encoding and proper error handling for file operations
- scripts/update_plugin_repos.py: Fix git fetch/pull error handling with returncode checks and specific exception types
- base-widget.js: Guard notify method against undefined/null type parameter
- file-upload.js: Remove inline handlers from schedule template, use addEventListener with data attributes
- file-upload.js: Update hideUploadProgress to show dynamic file types from config instead of hardcoded list
- README.md: Update Color Picker example to use sanitized fieldId throughout
* fix(widgets): Update Slider example to use sanitized fieldId
- Add sanitizeId helper to Slider example render, getValue, and setValue methods
- Use sanitizedFieldId for all DOM IDs and query selectors
- Maintain consistency with Color Picker example pattern
* fix(plugins_manager): Move configurePlugin and togglePlugin to top of file
- Move configurePlugin and togglePlugin definitions to top level (after uninstallPlugin)
- Ensures these critical functions are available immediately when script loads
- Fixes 'Critical functions not available after 20 attempts' error
- Functions are now defined before any HTML rendering checks
* fix(plugins_manager): Fix checkbox state saving using querySelector
- Add escapeCssSelector helper function for safe CSS selector usage
- Replace form.elements[actualKey] with form.querySelector for boolean fields
- Properly handle checkbox checked state using element.checked property
- Fix both schema-based and schema-less boolean field processing
- Ensures checkboxes with dot notation names (nested fields) work correctly
Fixes issue where checkbox states were not properly saved when field names
use dot notation (e.g., 'display.scroll_enabled'). The form.elements
collection doesn't reliably handle dot notation in bracket notation access.
* fix(base.html): Fix form element lookup for dot notation field names
- Add escapeCssSelector helper function (both as method and standalone)
- Replace form.elements[key] with form.querySelector for element type detection
- Fixes element lookup failures when field names use dot notation
- Ensures checkbox and multi-select skipping logic works correctly
- Applies fix to both Alpine.js method and standalone function
This complements the fix in plugins_manager.js to ensure all form
element lookups handle nested field names (e.g., 'display.scroll_enabled')
reliably across the entire web interface.
* fix(plugins_manager): Add race condition protection to togglePlugin
- Initialize window._pluginToggleRequests map for per-plugin request tokens
- Generate unique token for each toggle request to track in-flight requests
- Disable checkbox and wrapper UI during request to prevent overlapping toggles
- Add visual feedback with opacity and pointer-events-none classes
- Verify token matches before applying response updates (both success and error)
- Ignore out-of-order responses to preserve latest user intent
- Clear token and re-enable UI after request completes
Prevents race conditions when users rapidly toggle plugins, ensuring
only the latest toggle request's response affects the UI state.
* refactor(escapeCssSelector): Use CSS.escape() for better selector safety
- Prefer CSS.escape() when available for proper CSS selector escaping
- Handles edge cases: unicode characters, leading digits, and spec compliance
- Keep regex-based fallback for older browsers without CSS.escape support
- Update all three instances: plugins_manager.js and both in base.html
CSS.escape() is the standard API for escaping CSS selectors and provides
more robust handling than custom regex, especially for unicode and edge cases.
* fix(plugins_manager): Fix syntax error - missing closing brace for file-upload if block
- Add missing closing brace before else-if for checkbox-group widget
- Fixes 'Unexpected token else' error at line 3138
- The if block for file-upload widget (line 3034) was missing its closing brace
- Now properly structured: if (file-upload) { ... } else if (checkbox-group) { ... }
* fix(plugins_manager): Fix indentation in file-upload widget if block
- Properly indent all code inside the file-upload if block
- Fix template string closing brace indentation
- Ensures proper structure: if (file-upload) { ... } else if (checkbox-group) { ... }
- Resolves syntax error at line 3138
* fix(plugins_manager): Skip checkbox-group [] inputs to prevent config leakage
- Add skip logic for keys ending with '[]' in handlePluginConfigSubmit
- Prevents checkbox-group bracket notation inputs from leaking into config
- Checkbox-group widgets emit name="...[]" checkboxes plus a _data JSON field
- The _data field is already processed correctly, so [] inputs are redundant
- Prevents schema validation failures and extra config keys
The checkbox-group widget creates:
1. Individual checkboxes with name="fullKey[]" (now skipped)
2. Hidden input with name="fullKey_data" containing JSON array (processed)
3. Sentinel hidden input with name="fullKey[]" and empty value (now skipped)
* fix(plugins_manager): Normalize string booleans when checkbox input is missing
- Fix boolean field processing to properly normalize string booleans in fallback path
- Prevents "false"/"0" from being coerced to true when checkbox element is missing
- Handles common string boolean representations: 'true', 'false', '1', '0', 'on', 'off'
- Applies to both schema-based (lines 2386-2400) and schema-less (lines 2423-2433) paths
When a checkbox element cannot be found, the fallback logic now:
1. Checks if value is a string and normalizes known boolean representations
2. Treats undefined/null as false
3. Coerces other types to boolean using Boolean()
This ensures string values like "false" or "0" are correctly converted to false
instead of being treated as truthy non-empty strings.
* fix(base.html): Improve escapeCssSelector fallback to match CSS.escape behavior
- Handle leading digits by converting to hex escape (e.g., '1' -> '\0031 ')
- Handle leading whitespace by converting to hex escape (e.g., ' ' -> '\0020 ')
- Escape internal spaces as '\ ' (preserving space in hex escapes)
- Ensures trailing space after hex escapes per CSS spec
- Applies to both Alpine.js method and standalone function
The fallback now better matches CSS.escape() behavior for older browsers:
1. Escapes leading digits (0-9) as hex escapes with trailing space
2. Escapes leading whitespace as hex escapes with trailing space
3. Escapes all special characters as before
4. Escapes internal spaces while preserving hex escape format
This prevents selector injection issues with field names starting with digits
or whitespace, matching the standard CSS.escape() API behavior.
---------
Co-authored-by: Chuck <chuck@example.com>
LEDMatrix Documentation
Welcome to the LEDMatrix documentation! This directory contains comprehensive guides, specifications, and reference materials for the LEDMatrix project.
📚 Documentation Overview
This documentation has been consolidated and organized to reduce redundancy while maintaining comprehensive coverage. Recent improvements include complete API references, enhanced plugin development guides, and better organization for both end users and developers.
📖 Quick Start
For New Users
- Installation: Follow the main README.md in the project root
- First Setup: Run
first_time_install.shfor initial configuration - Basic Usage: See TROUBLESHOOTING_QUICK_START.md for common issues
For Developers
- Plugin System: Read PLUGIN_QUICK_REFERENCE.md for an overview
- Plugin Development: See PLUGIN_DEVELOPMENT_GUIDE.md for development workflow
- API Reference: Check PLUGIN_API_REFERENCE.md for available methods
- Configuration: Check PLUGIN_CONFIGURATION_GUIDE.md
For API Integration
- REST API: See API_REFERENCE.md for all web interface endpoints
- Plugin API: See PLUGIN_API_REFERENCE.md for plugin developer APIs
- Quick Reference: See DEVELOPER_QUICK_REFERENCE.md for common tasks
📋 Documentation Categories
🚀 Getting Started & Setup
- EMULATOR_SETUP_GUIDE.md - Set up development environment with emulator
- TRIXIE_UPGRADE_GUIDE.md - Upgrade to Raspbian OS 13 "Trixie"
- TROUBLESHOOTING_QUICK_START.md - Common issues and solutions
🏗️ Architecture & Design
- PLUGIN_ARCHITECTURE_SPEC.md - Complete plugin system specification
- PLUGIN_IMPLEMENTATION_SUMMARY.md - Plugin system implementation details
- FEATURE_IMPLEMENTATION_SUMMARY.md - Major feature implementations
- NESTED_CONFIG_SCHEMAS.md - Configuration schema design
- NESTED_SCHEMA_IMPLEMENTATION.md - Schema implementation details
- NESTED_SCHEMA_VISUAL_COMPARISON.md - Schema comparison visuals
⚙️ Configuration & Management
- PLUGIN_CONFIGURATION_GUIDE.md - Complete plugin configuration guide
- PLUGIN_CONFIGURATION_TABS.md - Configuration tabs feature
- PLUGIN_CONFIG_QUICK_START.md - Quick configuration guide
🔌 Plugin Development
- PLUGIN_DEVELOPMENT_GUIDE.md - Complete plugin development guide
- PLUGIN_QUICK_REFERENCE.md - Plugin development quick reference
- PLUGIN_API_REFERENCE.md - Complete API reference for plugin developers
- ADVANCED_PLUGIN_DEVELOPMENT.md - Advanced patterns and examples
- PLUGIN_REGISTRY_SETUP_GUIDE.md - Setting up plugin registry
- PLUGIN_DEPENDENCY_GUIDE.md - Managing plugin dependencies
- PLUGIN_DEPENDENCY_TROUBLESHOOTING.md - Dependency troubleshooting
🎮 Plugin Features
- ON_DEMAND_DISPLAY_QUICK_START.md - Manual display triggering
- PLUGIN_LIVE_PRIORITY_QUICK_START.md - Live content priority
- PLUGIN_LIVE_PRIORITY_API.md - Live priority API reference
- PLUGIN_CUSTOM_ICONS_FEATURE.md - Custom plugin icons
- PLUGIN_DISPATCH_IMPLEMENTATION.md - Plugin dispatch system
- PLUGIN_TABS_FEATURE_COMPLETE.md - Plugin tabs feature
📡 API Reference
- API_REFERENCE.md - Complete REST API documentation for web interface
- PLUGIN_API_REFERENCE.md - Plugin developer API reference (Display Manager, Cache Manager, Plugin Manager)
- DEVELOPER_QUICK_REFERENCE.md - Quick reference for common developer tasks
- ON_DEMAND_DISPLAY_API.md - On-demand display API reference
🛠️ Development & Tools
- BACKGROUND_SERVICE_README.md - Background service architecture
- FONT_MANAGER_USAGE.md - Font management system
🔍 Analysis & Compatibility
- RASPBIAN_TRIXIE_COMPATIBILITY_ANALYSIS.md - Detailed Trixie compatibility analysis
- CONFIGURATION_CLEANUP_SUMMARY.md - Configuration cleanup details
- football_plugin_comparison.md - Football plugin analysis
📊 Utility & Scripts
- README_broadcast_logo_analyzer.md - Broadcast logo analysis tool
- README_soccer_logos.md - Soccer logo management
- WEB_INTERFACE_TROUBLESHOOTING.md - Web interface troubleshooting
🔄 Migration & Updates
Recent Consolidations (October 2025)
- Implementation Summaries: Consolidated 7 separate implementation summaries into 2 comprehensive guides:
FEATURE_IMPLEMENTATION_SUMMARY.md(AP Top 25, Plugin System, Configuration, Web Interface, Trixie Compatibility)PLUGIN_IMPLEMENTATION_SUMMARY.md(Plugin system technical details)
- Trixie Documentation: Merged 4 Trixie-related documents into
TRIXIE_UPGRADE_GUIDE.md - Removed Redundancy: Eliminated duplicate documents and outdated debug guides
- Total Reduction: 53 → 39 documents (26% reduction)
Migration Notes
- Old implementation summary documents have been consolidated
- Trixie upgrade information is now centralized in one guide
- Deprecated manager documentation has been removed (no longer applicable)
- Very specific debug documents have been archived or removed
🎯 Key Resources by Use Case
I'm new to LEDMatrix
- Main README - Installation and setup
- EMULATOR_SETUP_GUIDE.md - Development environment
- PLUGIN_QUICK_REFERENCE.md - Understanding the system
I want to create a plugin
- PLUGIN_DEVELOPMENT_GUIDE.md - Complete development guide
- PLUGIN_API_REFERENCE.md - Available methods and APIs
- ADVANCED_PLUGIN_DEVELOPMENT.md - Advanced patterns and examples
- PLUGIN_CONFIGURATION_GUIDE.md - Configuration setup
- PLUGIN_ARCHITECTURE_SPEC.md - Complete specification
I want to upgrade to Trixie
- TRIXIE_UPGRADE_GUIDE.md - Complete upgrade guide
- RASPBIAN_TRIXIE_COMPATIBILITY_ANALYSIS.md - Technical details
I need to troubleshoot an issue
- TROUBLESHOOTING_QUICK_START.md - Common issues
- WEB_INTERFACE_TROUBLESHOOTING.md - Web interface problems
- PLUGIN_DEPENDENCY_TROUBLESHOOTING.md - Dependency issues
I want to understand the architecture
- PLUGIN_ARCHITECTURE_SPEC.md - System architecture
- FEATURE_IMPLEMENTATION_SUMMARY.md - Feature overview
- PLUGIN_IMPLEMENTATION_SUMMARY.md - Implementation details
📝 Contributing to Documentation
Documentation Standards
- Use Markdown format with consistent headers
- Include code examples where helpful
- Provide both quick start and detailed reference sections
- Keep implementation summaries focused on what was built, not how to use
Adding New Documentation
- Place in appropriate category (see sections above)
- Update this README.md with the new document
- Follow naming conventions (FEATURE_NAME.md)
- Consider if content should be consolidated with existing docs
Consolidation Guidelines
- Implementation Summaries: Consolidate into feature-specific summaries
- Quick References: Keep if they provide unique value, otherwise merge
- Debug Documents: Remove after issues are resolved
- Migration Guides: Consolidate when migrations are complete
🔗 Related Documentation
- Main Project README - Installation and basic usage
- Web Interface README - Web interface details
- LEDMatrix Wiki - Extended documentation and guides
- GitHub Issues - Bug reports and feature requests
- GitHub Discussions - Community support
📊 Documentation Statistics
- Total Documents: ~35 (after consolidation)
- Categories: 8 major sections (including new API Reference section)
- Primary Languages: English
- Format: Markdown (.md)
- Last Update: December 2025
- Coverage: Installation, development, troubleshooting, architecture, API references
Recent Improvements (December 2025)
- ✅ Complete REST API documentation (50+ endpoints)
- ✅ Complete Plugin API reference (Display Manager, Cache Manager, Plugin Manager)
- ✅ Advanced plugin development guide with examples
- ✅ Consolidated plugin configuration documentation
- ✅ Developer quick reference guide
- ✅ Better organization for end users and developers
This documentation index was last updated: December 2025
For questions or suggestions about the documentation, please open an issue or start a discussion on GitHub.