mirror of https://github.com/ChuckBuilds/LEDMatrix.git synced 2026-04-10 21:03:01 +00:00

Files

Chuck 71584d4361 Feature/widget registry system (#190 )

* 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>

2026-01-16 14:09:38 -05:00

README.md

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.sh for 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

📝 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

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.