desertthunder.dev / voltx
a reactive (signals based) hypermedia web framework (wip) stormlightlabs.github.io/volt/
hypermedia frontend signals
0
fork

Configure Feed

Select the types of activity you want to include in your feed.

docs: update plan

Owais Jamil 91224ef4 101b3f19

+180 -161
+122 -157
ROADMAP.md
··· 3 3 - [Completed](#completed) 4 4 - [TODO](#to-do) 5 5 - [Parking Lot](#parking-lot) 6 - - [Examples (Planned)](#examples) 7 6 8 7 | Version | State | Milestone | 9 8 | ------- | ----- | -------------------------------------------------------------------------------- | ··· 19 18 | v0.4.0 | ✓ | [Animation & Transitions](#animation--transitions) | 20 19 | v0.5.0 | ✓ | [Navigation & History API Routing](#navigation--history-api-routing) | 21 20 | | ✓ | [Refactor](#evaluator--binder-hardening) | 22 - | v0.5.1 | ✓ | [Error Handling & Diagnostics](#error-handling--diagnostics) | 23 - | v0.5.2 | | | 24 - | v0.5.3 | | | 25 - | v0.5.4 | | | 26 - | v0.6.1 | | [Persistence & Offline](#persistence--offline) | 27 - | v0.6.2 | | | 28 - | v0.6.3 | | | 29 - | v0.6.4 | | [Background Requests & Reactive Polling](#background-requests--reactive-polling) | 30 - | v0.6.5 | | | 31 - | v0.6.6 | | | 32 - | v0.6.7 | | [Streaming & Patch Engine](#streaming--patch-engine) | 33 - | v0.6.8 | | | 34 - | v0.6.9 | | | 35 - | v0.6.10 | | | 36 - | v0.7.0 | | | 37 - | v0.8.0 | | Support `voltx-` & `vx-` attributes: recommend `vx-` | 38 - | | | Switch to `data-voltx` | 39 - | | | Update demo to be a multi page application with routing plugin | 40 - | v0.9.0 | | [Inspector & Developer Tools](#inspector--developer-tools) | 21 + | v0.5.1 | ✓ | [Error Handling & Diagnostics](#error-handling--diagnostics) (partial) | 22 + | v0.6.0 | | [Error Handling & Diagnostics](#error-handling--diagnostics) | 23 + | v0.7.0 | | [Bundle Size Optimization](#bundle-size-optimization) | 24 + | v0.8.0 | | [CSP Compatibility](#csp-compatibility) | 25 + | v0.9.0 | | [DOM Morphing & Streaming](#dom-morphing--streaming) | 26 + | v0.10.0 | | [Scope Inheritance & State Management](#scope-inheritance--state-management) | 27 + | v0.11.0 | | [Background Requests & Reactive Polling](#background-requests--reactive-polling) | 28 + | v0.12.0 | | [Attribute Prefix Support](#attribute-prefix-support) | 29 + | v0.13.0 | | [Persistence & Offline](#persistence--offline) (advanced features) | 30 + | v0.14.0 | | [Inspector & Developer Tools](#inspector--developer-tools) | 41 31 | v1.0.0 | | [Stable Release](#stable-release) | 42 32 43 33 ## Completed ··· 112 102 113 103 ## To-Do 114 104 105 + **Focus:** Versions v0.5.5 through v0.9.x prioritize core framework capabilities and performance: 106 + 107 + - Bundle size reduction to <15KB gzipped (currently 19KB) 108 + - CSP compatibility (removing Function constructor dependency) 109 + - DOM morphing and SSE streaming support 110 + - Optional scope inheritance for improved ergonomics 111 + 112 + These milestones strengthen VoltX.js as a signals-based reactive framework with declarative-first design. 113 + 115 114 ### Error Handling & Diagnostics 116 115 117 116 **Goal**: Provide clear, actionable feedback when runtime or directive errors occur. 118 117 **Outcome**: VoltX.js surfaces developer-friendly diagnostics for expression evaluation, 119 118 directive parsing, and network operations, making it easier to debug apps without opaque stack traces. 120 119 **Deliverables**: 121 - - v0.5.1 122 - ✓ Centralized error boundary system for directives and effects. 123 - ✓ Sandbox error wrapping with contextual hints (directive name, expression, element). 124 - ✓ `$volt.report(error, context)` API for plugin and app-level reporting. 125 - - v0.5.2 126 - - Visual in-DOM error overlays for development mode. 127 - - Enhanced console messages with source map trace and directive path. 128 - - Differentiated error levels: warn, error, fatal. 129 - - v0.5.3 130 - - Runtime health monitor tracking evaluation and subscription failures. 131 - - v0.5.4 132 - - Documentation: "Understanding VoltX Errors" guide. 133 - - Configurable global error policy (silent, overlay, throw). 134 - 135 - ### Streaming & Patch Engine 136 - 137 - **Goal:** Enable real-time updates via SSE/WebSocket streaming with intelligent DOM patching. 138 - **Outcome:** VoltX.js can receive and apply live updates from the server 139 - **Deliverables:** 140 - - v0.5.7 141 - - Server-Sent Events (SSE) integration 142 - - `data-volt-flow` attribute for SSE endpoints 143 - - v0.5.8 144 - - Signal patching from backend (`data-signals-*` merge system) 145 - - Backend action system with `$$spark()` syntax 146 - - v0.5.9 147 - - JSON Patch parser and DOM morphing engine 148 - - `data-volt-ignore-morph` for selective patch exclusion 149 - - v0.5.10 150 - - WebSocket as alternative to SSE 120 + - ✓ v0.5.1: Centralized error boundary system for directives and effects 121 + - ✓ v0.5.1: Sandbox error wrapping with contextual hints (directive name, expression, element) 122 + - ✓ v0.5.1: `$volt.report(error, context)` API for plugin and app-level reporting 123 + - v0.6.0: Enhanced console error messages with directive context 124 + - v0.6.0: Differentiated error levels: warn, error, fatal 125 + - v0.6.0: Documentation: "Understanding VoltX Errors" guide 126 + - v0.6.0: Add error handling examples to demo 127 + - v0.14.0: Visual in-DOM error overlays for development mode 128 + - v0.14.0: Runtime health monitor tracking failures 129 + - v0.14.0: Configurable global error policy 151 130 152 131 ### Persistence & Offline 153 132 ··· 156 135 **Deliverables:** 157 136 - ✓ Persistent signals (localStorage, sessionStorage, indexedDb) 158 137 - ✓ Storage plugin (`data-volt-persist`) 159 - - v0.5.1 160 - - Storage modifiers on signals: 161 - - `.local` modifier for localStorage persistence 162 - - `.session` modifier for sessionStorage persistence 163 - - `.ifmissing` modifier for conditional initialization 164 - - v0.5.2 165 - - Sync strategy API (merge, overwrite, patch) for conflict resolution 166 - - Cache invalidation strategies 167 - - v0.5.3 168 - - Offline queue for deferred stream events and HTTP requests 169 - - Service Worker integration for offline-first apps 170 - - Background sync for deferred requests 171 - - Cross-tab synchronization via `BroadcastChannel` 138 + - v0.13.0: Storage modifiers on signals (`.local`, `.session`, `.ifmissing`) 139 + - v0.13.0: Sync strategy API (merge, overwrite, patch) for conflict resolution 140 + - v0.13.0: Cache invalidation strategies 141 + - v0.13.0: Offline queue for deferred stream events and HTTP requests 142 + - v0.13.0: Service Worker integration for offline-first apps 143 + - v0.13.0: Background sync for deferred requests 144 + - v0.13.0: Cross-tab synchronization via `BroadcastChannel` 145 + 146 + ### Bundle Size Optimization 147 + 148 + **Goal:** Reduce bundle size to <15KB gzipped while maintaining full feature set. 149 + **Outcome:** Lightweight runtime footprint with comprehensive declarative capabilities. 150 + **Deliverables:** 151 + - v0.7.0: Audit and tree-shake unused code paths 152 + - v0.7.0: Optimize evaluator and binder implementations 153 + - v0.7.0: Minimize plugin footprint, ensure lazy loading 154 + - v0.7.0: Refactor expression compiler for smaller output 155 + - v0.7.0: Compress constant strings and reduce runtime helpers 156 + - v0.7.0: Optimize signal subscription management 157 + - v0.7.0: Production mode stripping (remove dev-only error messages) 158 + - v0.7.0: Aggressive minification pipeline tuning 159 + - v0.7.0: Target: <15KB gzipped sustained 160 + 161 + ### CSP Compatibility 162 + 163 + **Goal:** Make VoltX.js Content Security Policy compliant without 'unsafe-eval'. 164 + **Outcome:** VoltX.js can run in strict CSP environments (no Function constructor). 165 + **Deliverables:** 166 + - v0.8.0: Research and design CSP-safe evaluator architecture 167 + - v0.8.0: Evaluate trade-offs: AST interpreter vs limited expression subset 168 + - v0.8.0: Implement CSP-safe expression evaluator (AST-based or restricted syntax) 169 + - v0.8.0: Maintain expression feature parity where possible 170 + - v0.8.0: Fallback mode detection for environments requiring CSP 171 + - v0.8.0: Full test coverage for CSP mode 172 + - v0.8.0: Documentation on CSP limitations and alternatives 173 + - v0.8.0: Bundle split: standard build vs CSP build 174 + 175 + ### DOM Morphing & Streaming 176 + 177 + **Goal:** Add intelligent DOM morphing and Server-Sent Events for real-time updates. 178 + **Outcome:** Built-in morphing and SSE streaming for seamless server-driven UI updates. 179 + **Deliverables:** 180 + - v0.9.0: Integrate Idiomorph or implement lightweight morphing algorithm 181 + - v0.9.0: `data-volt-morph` attribute for morphing-based swaps 182 + - v0.9.0: Preserve focus, scroll, and input state during morphs 183 + - v0.9.0: Server-Sent Events (SSE) integration 184 + - v0.9.0: `data-volt-stream` attribute for SSE endpoints 185 + - v0.9.0: Automatic reconnection with exponential backoff 186 + - v0.9.0: Signal patching from backend SSE events 187 + - v0.9.0: JSON Patch support for partial updates 188 + - v0.9.0: `data-volt-ignore-morph` for selective exclusion 189 + - v0.9.0: WebSocket as alternative to SSE 190 + - v0.9.0: Unified streaming API across SSE/WebSocket 191 + 192 + ### Scope Inheritance & State Management 193 + 194 + **Goal:** Improve data scoping with optional inheritance for ergonomic nested components. 195 + **Outcome:** Flexible scoping patterns for complex component hierarchies. 196 + **Deliverables:** 197 + - v0.10.0: Optional scope inheritance via `data-volt-scope="inherit"` 198 + - v0.10.0: Child scopes inherit parent signals with override capability 199 + - v0.10.0: $parent accessor for explicit parent scope access 200 + - v0.10.0: Scoped context providers for dependency injection 201 + - v0.10.0: Enhanced $store with namespacing and modules 202 + - v0.10.0: Cross-scope signal sharing patterns 172 203 173 204 ### Background Requests & Reactive Polling 174 205 175 - **Goal:** Enable declarative background data fetching and periodic updates within the VoltX.js runtime. 206 + **Goal:** Enable declarative background data fetching and periodic updates. 176 207 **Outcome:** VoltX.js elements can fetch or refresh data automatically based on time, visibility, or reactive conditions. 177 208 **Deliverables:** 178 - - v0.5.4 179 - - `data-volt-visible` for fetching when an element enters the viewport (`IntersectionObserver`) 180 - - v0.5.5 181 - - `data-volt-fetch` attribute for declarative background requests 182 - - Configurable polling intervals, delays, and signal-based triggers 183 - - Automatic cancellation of requests when elements are unmounted 184 - - Conditional execution tied to reactive signals 185 - - Integration hooks for loading and pending states 186 - - v0.5.6 187 - - Background task scheduler with priority management 209 + - v0.11.0: `data-volt-visible` for fetching when element enters viewport (IntersectionObserver) 210 + - v0.11.0: `data-volt-poll` attribute for periodic background requests 211 + - v0.11.0: Configurable intervals, delays, and signal-based triggers 212 + - v0.11.0: Automatic cancellation when elements unmount 213 + - v0.11.0: Conditional polling tied to reactive signals 214 + - v0.11.0: Background task scheduler with priority management 215 + 216 + ### Attribute Prefix Support 217 + 218 + **Goal:** Support multiple attribute prefix options for developer preference. 219 + **Outcome:** VoltX.js supports `voltx-`, `vx-`, and `data-volt-` prefixes. 220 + **Deliverables:** 221 + - v0.12.0: Add support for `voltx-*` and `vx-*` attribute prefixes 222 + - v0.12.0: Recommend `vx-*` as primary in documentation 223 + - v0.12.0: Maintain backward compatibility with `data-volt-*` 224 + - v0.12.0: Update demo to use recommended prefix 188 225 189 226 ### Inspector & Developer Tools 190 227 191 228 **Goal:** Improve developer experience and runtime introspection. 192 229 **Outcome:** First-class developer ergonomics; VoltX.js is enjoyable to debug and extend. 193 230 **Deliverables:** 194 - - v0.9.1 195 - - Developer overlay for inspecting signals, subscriptions, and effects 196 - - Time-travel debugging for signal history 197 - - v0.9.2 198 - - Signal dependency graph visualization (graph data structure implemented in [proxy](#proxy-based-reactivity-enhancements) milestone) 199 - - v0.9.3 200 - - Browser console integration (`window.$volt.inspect()`) 201 - - Dev logging toggle (`Volt.debug = true`) 202 - - v0.9.4 203 - - Request/response debugging (HTTP actions, SSE streams) 204 - - v0.9.5 205 - - Performance profiling tools 206 - - v0.9.6 to v0.9.10 207 - - Browser DevTools extension 231 + - v0.14.0: Visual in-DOM error overlays for development mode 232 + - v0.14.0: Runtime health monitor tracking failures 233 + - v0.14.0: Configurable global error policy (silent, overlay, throw) 234 + - v0.14.0: Developer overlay for inspecting signals, subscriptions, and effects 235 + - v0.14.0: Time-travel debugging for signal history 236 + - v0.14.0: Signal dependency graph visualization 237 + - v0.14.0: Performance profiling tools 238 + - v0.14.0: Browser console integration (`window.$volt.inspect()`) 239 + - v0.14.0: Dev logging toggle (`Volt.debug = true`) 240 + - v0.14.0: Request/response debugging (HTTP actions, SSE streams) 241 + - v0.14.0: Browser DevTools extension with full integration 208 242 209 243 ### Stable Release 210 244 ··· 219 253 - Announcement post and release notes 220 254 - Community contribution guide & governance doc 221 255 222 - ### Better Demo 223 - 224 - **Goal:** Transform the current programmatic demo into a declarative multi-page SPA showcasing all framework and CSS features. 225 - **Outcome:** Production-quality reference application demonstrating VoltX.js best practices and real-world patterns. 226 - **Deliverables:** 227 - - Convert demo from programmatic to declarative mode (charge() + data-volt attributes) 228 - - Implement multi-page routing using Navigation & History API plugin 229 - - Add tooltips to VoltX css using data attributes 230 - - Example: data-vx-tooltip="Right" data-placement="right" 231 - - Page: Home - Framework overview and feature highlights 232 - - Page: Getting Started - Installation and first examples 233 - - Page: Reactivity - Signals, computed, effects, bindings, conditional/list rendering 234 - - Page: HTTP - Backend integration with all methods, swap strategies, retry logic 235 - - Page: State - Global stores and scope helpers ($store, $scope, $pulse, $uid, $probe, $pins, $arc) 236 - - Page: Persistence - localStorage/sessionStorage/IndexedDB, persist plugin, URL sync 237 - - Page: Animations - Surge directive, shift plugin, View Transitions 238 - - Page: Forms - Model binding, validation, event modifiers, multi-step forms 239 - - Page: CSS - Complete Volt CSS showcase (typography, layout, Tufte sidenotes, tables) 240 - - Page: Patterns - Real-world components (tabs, accordion, modal, autocomplete) 241 - - View-source friendly code with clear examples 242 - - Copy-paste ready patterns for common use cases 243 - 244 256 ## Parking Lot 245 257 246 258 ### Evaluator & Binder Hardening 247 259 248 260 All expression evaluation now flows through a cached `new Function` compiler guarded by a hardened scope proxy, with the binder slimmed into a directive registry so plugins self-register while tests verify the sandboxed error surfaces. 249 - 250 - ### Naming 251 - 252 - ## Examples 253 - 254 - Many of these are ideas, not planned to be implemented 255 - 256 - ### Components 257 - 258 - - Modal Dialog - Conditional rendering, focus trapping, backdrop, keyboard escape 259 - - Tabs & Accordion - Conditional rendering, active state management, keyboard navigation 260 - - Form Validation - Model binding, computed validation, conditional messages, error states 261 - 262 - ### Client-Side (SPA/Static) 263 - 264 - - ✓ Counter - Basic signals, computed, event handling 265 - - ✓ TodoMVC - List rendering, persistence, filtering, CRUD operations 266 - - Search with Autocomplete - Async effects, debouncing, API integration, keyboard navigation 267 - - Calculator - Event handling, computed expressions, button grid, operation state 268 - - Image Gallery - For loops, filtering, lightbox, category selection 269 - 270 - - Multi-Step Wizard - Form state across steps, validation per step, progress tracking, navigation 271 - - Note-Taking App - Rich CRUD, categories/tags, search/filter, localStorage persistence, markdown preview 272 - - Expense Tracker - Date handling, categories, computed totals/charts, filtering by date range, CSV export 273 - - Kanban Board - Drag-and-drop (via events), column management, task editing, state persistence 274 - - Timer/Stopwatch - Async effects, intervals, lap times, pause/resume, localStorage for history 275 - 276 - - Real-time Chat - SSE for messages, typing indicators, user presence, message history 277 - - Live Dashboard - SSE for metrics, charts updating in real-time, WebSocket fallback 278 - - Collaborative Editor - Operational transforms, SSE for changes, conflict resolution, cursor positions 279 - - Infinite Scroll Feed - Polling for new items, intersection observer, virtualized rendering 280 - - Admin Panel/CMS - CRUD operations, data tables, filters, pagination, bulk actions 281 - 282 - ### Server-Side Rendered (SSR) 283 - 284 - These will live in an example repo. 285 - 286 - - Authentication Flows - Login, signup, password reset, email verification (Go, Python, Rust, Node) 287 - - File Upload with Progress - Chunked uploads, progress bars, validation (Go, Python, Rust, Node) 288 - - Search with Server-Side Filtering - Debounced search, paginated results (Go, Python, Rust, Node) 289 - 290 - ### Desktop Apps 291 - 292 - - Note Editor - Local file system, syntax highlighting, multi-tab, settings persistence 293 - - System Monitor - CPU/memory graphs, process list, real-time updates 294 - - Database Client - Table browser, query editor, result grid, export 295 - - Media Player - File browser, playlists, controls, metadata display
+58 -4
TODO.md
··· 1 1 # Better Demo Implementation TODO 2 2 3 - This document tracks the implementation of the Better Demo deliverables from ROADMAP.md. 4 - 5 3 ## Existing Issues 6 4 7 5 - [x] **FIXME** (lib/src/demo/sections/plugins.ts:68): Sidenotes need stylesheet constraints - RESOLVED ··· 172 170 173 171 ## Phase 5: Polish & Documentation 174 172 175 - ### 14. View-Source Friendly Code 173 + ### 14. Framework Capabilities Showcase 174 + 175 + **Note:** Showcase framework capabilities as features are completed from ROADMAP.md 176 + 177 + - [ ] Add bundle size widget/badge highlighting <15KB achievement (from Bundle Size Optimization milestone) 178 + - [ ] Demonstrate CSP-safe mode when available (from CSP Compatibility milestone) 179 + - [ ] Showcase DOM morphing features (from DOM Morphing & Streaming milestone) 180 + - [ ] Demonstrate SSE streaming (from DOM Morphing & Streaming milestone) 181 + - [ ] Show scope inheritance patterns (from Scope Inheritance & State Management milestone) 182 + - [ ] Display reactive polling examples (from Background Requests & Reactive Polling milestone) 183 + 184 + ### 15. View-Source Friendly Code 176 185 177 186 - [ ] Ensure all HTML is readable and well-commented 178 187 - [ ] Add explanatory comments to complex bindings 179 188 - [ ] Include inline documentation where helpful 180 189 - [ ] Make examples copy-paste ready 181 190 182 - ### 15. Copy-Paste Ready Patterns 191 + ### 16. Copy-Paste Ready Patterns 183 192 184 193 - [ ] Extract reusable patterns into clearly marked sections 185 194 - [ ] Provide minimal examples for each feature ··· 212 221 components.css # Add tooltip styles here 213 222 ... 214 223 ``` 224 + 225 + ## Example Ideas 226 + 227 + Many of these are ideas, not planned to be implemented 228 + 229 + ### Components 230 + 231 + - Modal Dialog - Conditional rendering, focus trapping, backdrop, keyboard escape 232 + - Tabs & Accordion - Conditional rendering, active state management, keyboard navigation 233 + - Form Validation - Model binding, computed validation, conditional messages, error states 234 + 235 + ### Client-Side (SPA/Static) 236 + 237 + - ✓ Counter - Basic signals, computed, event handling 238 + - ✓ TodoMVC - List rendering, persistence, filtering, CRUD operations 239 + - Search with Autocomplete - Async effects, debouncing, API integration, keyboard navigation 240 + - Calculator - Event handling, computed expressions, button grid, operation state 241 + - Image Gallery - For loops, filtering, lightbox, category selection 242 + 243 + - Multi-Step Wizard - Form state across steps, validation per step, progress tracking, navigation 244 + - Note-Taking App - Rich CRUD, categories/tags, search/filter, localStorage persistence, markdown preview 245 + - Expense Tracker - Date handling, categories, computed totals/charts, filtering by date range, CSV export 246 + - Kanban Board - Drag-and-drop (via events), column management, task editing, state persistence 247 + - Timer/Stopwatch - Async effects, intervals, lap times, pause/resume, localStorage for history 248 + 249 + - Real-time Chat - SSE for messages, typing indicators, user presence, message history 250 + - Live Dashboard - SSE for metrics, charts updating in real-time, WebSocket fallback 251 + - Collaborative Editor - Operational transforms, SSE for changes, conflict resolution, cursor positions 252 + - Infinite Scroll Feed - Polling for new items, intersection observer, virtualized rendering 253 + - Admin Panel/CMS - CRUD operations, data tables, filters, pagination, bulk actions 254 + 255 + ### Server-Side Rendered (SSR) 256 + 257 + These will live in an example repo. 258 + 259 + - Authentication Flows - Login, signup, password reset, email verification (Go, Python, Rust, Node) 260 + - File Upload with Progress - Chunked uploads, progress bars, validation (Go, Python, Rust, Node) 261 + - Search with Server-Side Filtering - Debounced search, paginated results (Go, Python, Rust, Node) 262 + 263 + ### Desktop Apps 264 + 265 + - Note Editor - Local file system, syntax highlighting, multi-tab, settings persistence 266 + - System Monitor - CPU/memory graphs, process list, real-time updates 267 + - Database Client - Table browser, query editor, result grid, export 268 + - Media Player - File browser, playlists, controls, metadata display