a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
hypermedia
frontend
signals
1# Better Demo Implementation TODO
2
3## Existing Issues
4
5- [x] **FIXME** (lib/src/demo/sections/plugins.ts:68): Sidenotes need stylesheet constraints - RESOLVED
6- [x] **FIXME** (lib/src/demo/sections/interactivity.ts:46): Dialog footer structure needs correction - RESOLVED
7
8## Phase 1: Foundation (First 4 Deliverables)
9
10### 1. Convert to Declarative Mode
11
12**Approach:** Use DOM utilities (lib/src/demo/utils.ts) to programmatically build HTML markup that uses declarative VoltX attributes (data-volt-state, data-volt-computed, data-volt-*), then mount with charge() instead of programmatic mount() + signals.
13
14- [x] Add window.$helpers for DOM operations (openDialog, closeDialog, scrollTo, etc.)
15- [x] Update buildDemoStructure() to add data-volt attribute to root element
16- [x] Add data-volt-state with all initial state as JSON on root element
17- [x] Add data-volt-computed attributes for derived values (doubled, activeTodos, completedTodos)
18- [x] Convert all sections to produce markup with declarative bindings:
19 - [x] Interactivity section - use $helpers.openDialog(), button expressions
20 - [x] Reactivity section - reference state directly in expressions (count.get(), etc.)
21 - [x] Forms section - use $helpers.handleFormSubmit(), data-volt-model on inputs
22 - [x] Plugins section - declarative persist/scroll/url attributes (already mostly done)
23 - [x] Animations section - declarative surge/shift attributes (already done)
24 - [x] Typography section - no changes needed (static content)
25- [x] Remove demoScope export (replaced by declarative state on element)
26- [x] Update setupDemo() to use charge() instead of mount()
27- [x] Update lib/src/main.ts to just call setupDemo() (no other code)
28
29### 2. Implement Multi-Page Routing
30
31- [x] Register navigate plugin in main.ts
32- [x] Initialize navigation listener with initNavigationListener()
33- [x] Create route-based content structure (added currentPage signal)
34- [x] Add navigation menu with declarative page switching
35- [x] Implement content swapping mechanism (conditional rendering with data-volt-if)
36- [x] Ensure browser back/forward buttons work correctly (initNavigationListener)
37- [x] Add View Transition API integration (built into navigate plugin)
38
39### 3. Add Tooltip CSS Feature
40
41- [x] Design tooltip data attribute API (data-vx-tooltip, data-placement)
42- [x] Add tooltip CSS to lib/src/styles/components.css
43- [x] Support placements: top, right, bottom, left
44- [x] Implement tooltip positioning logic (CSS-only with pseudo-elements)
45- [x] Add hover/focus interactions
46- [x] Ensure accessibility (uses native attributes)
47- [x] Test tooltips across different viewport sizes (responsive: hidden on mobile)
48- [x] Add tooltip examples to home page
49
50### 4. Create Home Page
51
52- [x] Design home page layout
53- [x] Add framework overview section
54- [x] Create feature highlights grid/list
55 - Bundle size < 15KB
56 - No virtual DOM
57 - Signal-based reactivity
58 - Zero dependencies
59 - Declarative-first approach
60- [x] Add quick navigation to demo pages
61- [x] Include getting started code snippet
62- [x] Add links to documentation and GitHub
63- [x] Ensure home page uses Volt CSS classless styling
64
65## PHASE 1 COMPLETE ✓
66
67## Phase 2: Core Feature Pages
68
69### 5. Page: Getting Started
70
71- [ ] Installation instructions (npm, JSR, CDN)
72- [ ] First example with charge()
73- [ ] Declarative vs programmatic comparison
74- [ ] Basic signal usage example
75- [ ] Link to full documentation
76
77### 6. Page: Reactivity
78
79- [ ] Migrate existing reactivity section
80- [ ] Signals demo (get/set/subscribe)
81- [ ] Computed values demo
82- [ ] Effects demo
83- [ ] Conditional rendering (data-volt-if/else)
84- [ ] List rendering (data-volt-for)
85- [ ] Class bindings (data-volt-class)
86- [ ] Two-way binding (data-volt-model)
87
88### 7. Page: HTTP
89
90- [ ] Demonstrate all HTTP methods (GET, POST, PUT, PATCH, DELETE)
91- [ ] Show swap strategies (innerHTML, outerHTML, beforebegin, afterbegin, beforeend, afterend, delete, none)
92- [ ] Loading indicators with data-volt-indicator
93- [ ] Error handling patterns
94- [ ] Retry logic demonstration
95- [ ] Form serialization for POST/PUT/PATCH
96- [ ] Target selector usage
97
98### 8. Page: State
99
100- [ ] Global store demonstration
101- [ ] Scope helpers overview
102 - $store - access global state
103 - $scope - current scope reference
104 - $pulse - microtask scheduling
105 - $uid - deterministic IDs
106 - $probe - element refs
107 - $pins - custom helpers
108 - $arc - custom event dispatch
109- [ ] Cross-component communication patterns
110- [ ] Store registration and updates
111
112## Phase 3: Plugin & Advanced Pages
113
114### 9. Page: Persistence
115
116- [ ] Migrate existing persist plugin demo
117- [ ] localStorage persistence demo
118- [ ] sessionStorage persistence demo
119- [ ] IndexedDB persistence demo
120- [ ] URL sync with url plugin
121- [ ] Demonstrate storage modifiers (.local, .session, .ifmissing)
122- [ ] Cross-tab synchronization example
123
124### 10. Page: Animations
125
126- [ ] Migrate existing animations section
127- [ ] Surge plugin demos (fade, slide, scale, blur)
128- [ ] Custom timing (duration, delay)
129- [ ] Different enter/leave transitions
130- [ ] Shift plugin demos (bounce, shake, pulse, flash, spin)
131- [ ] Custom animation settings
132- [ ] Combined effects (surge + shift)
133- [ ] View Transition API integration
134
135### 11. Page: Forms
136
137- [ ] Migrate existing forms section
138- [ ] Complete form example with all input types
139- [ ] Two-way binding demonstration
140- [ ] Validation patterns
141- [ ] Event modifiers (.prevent, .stop, etc.)
142- [ ] Multi-step form example
143- [ ] Form submission handling
144
145## Phase 4: Reference & Patterns
146
147### 12. Page: CSS
148
149- [ ] Migrate existing typography section
150- [ ] Expand with additional Volt CSS features
151- [ ] Typography showcase (headings, paragraphs, lists)
152- [ ] Tufte-style sidenotes
153- [ ] Tables with zebra striping
154- [ ] Code blocks and inline code
155- [ ] Blockquotes and citations
156- [ ] Semantic HTML elements
157- [ ] Layout examples
158- [ ] Responsive behavior
159
160### 13. Page: Patterns
161
162- [ ] Tabs component pattern
163- [ ] Accordion component pattern
164- [ ] Modal dialog pattern (expand existing)
165- [ ] Autocomplete/search pattern
166- [ ] Dropdown menu pattern
167- [ ] Toast/notification pattern
168- [ ] Pagination pattern
169- [ ] Infinite scroll pattern
170
171## Phase 5: Polish & Documentation
172
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
185
186- [ ] Ensure all HTML is readable and well-commented
187- [ ] Add explanatory comments to complex bindings
188- [ ] Include inline documentation where helpful
189- [ ] Make examples copy-paste ready
190
191### 16. Copy-Paste Ready Patterns
192
193- [ ] Extract reusable patterns into clearly marked sections
194- [ ] Provide minimal examples for each feature
195- [ ] Include both inline and external script examples
196- [ ] Document common pitfalls and solutions
197
198## File Structure
199
200```sh
201lib/
202 index.html # Main entry with routing and global state
203 src/
204 main.ts # Minimal bootstrap (charge + navigate init)
205 demo/
206 index.ts # Removed or minimal utilities only
207 sections/ # Keep or convert to HTML partials
208 utils.ts # DOM utilities (may still be useful)
209 pages/ # New directory for page templates
210 home.html
211 getting-started.html
212 reactivity.html
213 http.html
214 state.html
215 persistence.html
216 animations.html
217 forms.html
218 css.html
219 patterns.html
220 styles/
221 components.css # Add tooltip styles here
222 ...
223```
224
225## Example Ideas
226
227Many 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
257These 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