From 24078883da87e469de0a3d39111a0416ef0dbc52 Mon Sep 17 00:00:00 2001 From: Patrick Balsiger Date: Fri, 15 Aug 2025 21:33:19 +0200 Subject: [PATCH] docs: add comprehensive README with UI framework documentation --- README.md | 220 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 220 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..8840245 --- /dev/null +++ b/README.md @@ -0,0 +1,220 @@ +# Sprocket UI Framework + +A modern web-based user interface framework for Sprocket devices, providing real-time control, visualization, and management capabilities through a responsive web interface. + +## Overview + +The Sprocket UI Framework is a comprehensive web application that enables users to interact with Sprocket devices through an intuitive browser-based interface. It features real-time communication, component-based architecture, and modern web technologies. + +## Features + +- **Real-Time Communication**: WebSocket-based live updates and control +- **Component-Based Architecture**: Modular, reusable UI components +- **Responsive Design**: Works on desktop and mobile devices +- **Live Data Binding**: Real-time synchronization with device state +- **Plugin Integration**: Support for various Sprocket plugins +- **Modern Web Stack**: Built with ES6+, Webpack, and Less + +## Architecture + +### Core Components +- **App**: Main application controller +- **Mediator**: Event-driven communication system +- **Component System**: Modular UI component framework +- **Data Store**: State management and persistence +- **WebSocket Client**: Real-time device communication + +### UI Components +- **Form Controls**: Input fields, sliders, switches, and selectors +- **Color Picker**: Advanced color selection with gradients +- **Chat Interface**: Real-time messaging and logging +- **Parameter Controls**: Dynamic parameter adjustment +- **Preset Management**: Save and load device configurations + +## Technology Stack + +### Frontend +- **JavaScript**: ES6+ with Babel transpilation +- **CSS**: Less preprocessor for styling +- **Build Tools**: Webpack for bundling and optimization +- **Dependencies**: jQuery, Mustache, WebSocket + +### Development +- **Build System**: Webpack with hot reloading +- **CSS Processing**: Less compilation +- **Development Server**: Live-server with auto-reload +- **Docker Support**: Containerized development and deployment + +## Getting Started + +### Prerequisites +- Node.js (v12 or higher) +- Yarn package manager +- Modern web browser + +### Installation + +```bash +# Install dependencies +yarn install + +# Setup development environment +yarn setup + +# Start development server +yarn dev +``` + +### Build Commands + +```bash +# Build frontend assets +yarn build:frontend + +# Build specific components +yarn build:js # JavaScript bundle +yarn build:css # CSS compilation +yarn build:html # HTML templates +``` + +## Development Workflow + +### File Structure +``` +src/ +├── app/ # Application logic +│ ├── core/ # Core framework +│ ├── components/ # UI components +│ └── main.js # Entry point +├── pages/ # HTML templates +├── styles/ # Less stylesheets +└── data/ # Generated assets +``` + +### Component Development +Components are modular and follow a consistent pattern: +- **HTML Template**: Structure and markup +- **JavaScript Logic**: Behavior and event handling +- **CSS Styling**: Component-specific styles +- **Data Binding**: Integration with data store + +### Real-Time Features +- **WebSocket Communication**: Live device updates +- **Event System**: Component-to-component messaging +- **State Synchronization**: Automatic UI updates +- **Live Controls**: Real-time device control + +## Configuration + +### WebSocket Endpoint +Configure the WebSocket connection endpoint: +```javascript +let endpoint = '/ws'; // Default WebSocket path +``` + +### Component Registration +Register components with the main application: +```javascript +let app = new App($('body')) + .components(components) + .websocket(wsConnection); +``` + +## Deployment + +### Docker +```bash +# Build container +yarn docker:build + +# Run locally +yarn docker:run + +# Release to registry +yarn docker:release +``` + +### Production Build +```bash +# Build optimized assets +yarn build:frontend + +# Deploy to web server +# Copy data/ directory to web root +``` + +## API Integration + +### WebSocket Events +- **Device Status**: Real-time device state updates +- **Control Commands**: Send commands to devices +- **Configuration**: Update device settings +- **Monitoring**: Live sensor data and metrics + +### REST Endpoints +- **Device Control**: POST commands to devices +- **Status Information**: GET device status +- **Configuration**: GET/SET device settings +- **System Management**: Restart, update, etc. + +## Customization + +### Themes +- **Color Schemes**: Customizable color palettes +- **Layout Options**: Flexible component arrangement +- **Responsive Breakpoints**: Mobile-first design +- **Component Styling**: Individual component customization + +### Plugins +- **Component Extensions**: Add new UI components +- **Data Sources**: Integrate with external systems +- **Communication Protocols**: Support for various protocols +- **Storage Backends**: Different data persistence options + +## Browser Support + +- **Modern Browsers**: Chrome, Firefox, Safari, Edge +- **Mobile Support**: iOS Safari, Chrome Mobile +- **ES6 Features**: Arrow functions, classes, modules +- **WebSocket**: Real-time communication support + +## Performance + +- **Code Splitting**: Lazy loading of components +- **Asset Optimization**: Minified and compressed assets +- **Caching**: Browser caching strategies +- **Lazy Loading**: On-demand component loading + +## Troubleshooting + +### Common Issues +- **WebSocket Connection**: Check device connectivity +- **Build Errors**: Verify Node.js and Yarn versions +- **Component Loading**: Check component registration +- **Styling Issues**: Verify Less compilation + +### Debug Mode +Enable debug output for troubleshooting: +```javascript +// Enable debug logging +app.debug = true; +``` + +## Contributing + +1. Fork the repository +2. Create feature branch +3. Implement changes +4. Add tests if applicable +5. Submit pull request + +## License + +See LICENSE file for details. + +## Support + +- **Documentation**: Check the docs/ directory +- **Issues**: Report bugs via GitHub issues +- **Community**: Join the Sprocket community +- **Examples**: See examples/ directory for usage patterns \ No newline at end of file