Better Demo Implementation TODO#

Existing Issues#

FIXME (lib/src/demo/sections/plugins.ts:68): Sidenotes need stylesheet constraints - RESOLVED
FIXME (lib/src/demo/sections/interactivity.ts:46): Dialog footer structure needs correction - RESOLVED

Phase 1: Foundation (First 4 Deliverables)#

1. Convert to Declarative Mode#

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.

Add window.$helpers for DOM operations (openDialog, closeDialog, scrollTo, etc.)
Update buildDemoStructure() to add data-volt attribute to root element
Add data-volt-state with all initial state as JSON on root element
Add data-volt-computed attributes for derived values (doubled, activeTodos, completedTodos)
Convert all sections to produce markup with declarative bindings:
- Interactivity section - use $helpers.openDialog(), button expressions
- Reactivity section - reference state directly in expressions (count.get(), etc.)
- Forms section - use $helpers.handleFormSubmit(), data-volt-model on inputs
- Plugins section - declarative persist/scroll/url attributes (already mostly done)
- Animations section - declarative surge/shift attributes (already done)
- Typography section - no changes needed (static content)
Remove demoScope export (replaced by declarative state on element)
Update setupDemo() to use charge() instead of mount()
Update lib/src/main.ts to just call setupDemo() (no other code)

2. Implement Multi-Page Routing#

Register navigate plugin in main.ts
Initialize navigation listener with initNavigationListener()
Create route-based content structure (added currentPage signal)
Add navigation menu with declarative page switching
Implement content swapping mechanism (conditional rendering with data-volt-if)
Ensure browser back/forward buttons work correctly (initNavigationListener)
Add View Transition API integration (built into navigate plugin)

Design tooltip data attribute API (data-vx-tooltip, data-placement)
Add tooltip CSS to lib/src/styles/components.css
Support placements: top, right, bottom, left
Implement tooltip positioning logic (CSS-only with pseudo-elements)
Add hover/focus interactions
Ensure accessibility (uses native attributes)
Test tooltips across different viewport sizes (responsive: hidden on mobile)
Add tooltip examples to home page

4. Create Home Page#

Design home page layout
Add framework overview section
Create feature highlights grid/list
- Bundle size < 15KB
- No virtual DOM
- Signal-based reactivity
- Zero dependencies
- Declarative-first approach
Add quick navigation to demo pages
Include getting started code snippet
Add links to documentation and GitHub
Ensure home page uses Volt CSS classless styling

PHASE 1 COMPLETE ✓#

Phase 2: Core Feature Pages#

5. Page: Getting Started#

Installation instructions (npm, JSR, CDN)
First example with charge()
Declarative vs programmatic comparison
Basic signal usage example
Link to full documentation

6. Page: Reactivity#

Migrate existing reactivity section
Signals demo (get/set/subscribe)
Computed values demo
Effects demo
Conditional rendering (data-volt-if/else)
List rendering (data-volt-for)
Class bindings (data-volt-class)
Two-way binding (data-volt-model)

7. Page: HTTP#

Demonstrate all HTTP methods (GET, POST, PUT, PATCH, DELETE)
Show swap strategies (innerHTML, outerHTML, beforebegin, afterbegin, beforeend, afterend, delete, none)
Loading indicators with data-volt-indicator
Error handling patterns
Retry logic demonstration
Form serialization for POST/PUT/PATCH
Target selector usage

8. Page: State#

Global store demonstration
Scope helpers overview
- $store - access global state
- $scope - current scope reference
- $pulse - microtask scheduling
- $uid - deterministic IDs
- $probe - element refs
- $pins - custom helpers
- $arc - custom event dispatch
Cross-component communication patterns
Store registration and updates

Phase 3: Plugin & Advanced Pages#

9. Page: Persistence#

Migrate existing persist plugin demo
localStorage persistence demo
sessionStorage persistence demo
IndexedDB persistence demo
URL sync with url plugin
Demonstrate storage modifiers (.local, .session, .ifmissing)
Cross-tab synchronization example

10. Page: Animations#

Migrate existing animations section
Surge plugin demos (fade, slide, scale, blur)
Custom timing (duration, delay)
Different enter/leave transitions
Shift plugin demos (bounce, shake, pulse, flash, spin)
Custom animation settings
Combined effects (surge + shift)
View Transition API integration

11. Page: Forms#

Migrate existing forms section
Complete form example with all input types
Two-way binding demonstration
Validation patterns
Event modifiers (.prevent, .stop, etc.)
Multi-step form example
Form submission handling

Phase 4: Reference & Patterns#

12. Page: CSS#

Migrate existing typography section
Expand with additional Volt CSS features
Typography showcase (headings, paragraphs, lists)
Tufte-style sidenotes
Tables with zebra striping
Code blocks and inline code
Blockquotes and citations
Semantic HTML elements
Layout examples
Responsive behavior

13. Page: Patterns#

Tabs component pattern
Accordion component pattern
Modal dialog pattern (expand existing)
Autocomplete/search pattern
Dropdown menu pattern
Toast/notification pattern
Pagination pattern
Infinite scroll pattern

Phase 5: Polish & Documentation#

14. Framework Capabilities Showcase#

Note: Showcase framework capabilities as features are completed from ROADMAP.md

Add bundle size widget/badge highlighting <15KB achievement (from Bundle Size Optimization milestone)
Demonstrate CSP-safe mode when available (from CSP Compatibility milestone)
Showcase DOM morphing features (from DOM Morphing & Streaming milestone)
Demonstrate SSE streaming (from DOM Morphing & Streaming milestone)
Show scope inheritance patterns (from Scope Inheritance & State Management milestone)
Display reactive polling examples (from Background Requests & Reactive Polling milestone)

15. View-Source Friendly Code#

Ensure all HTML is readable and well-commented
Add explanatory comments to complex bindings
Include inline documentation where helpful
Make examples copy-paste ready

16. Copy-Paste Ready Patterns#

Extract reusable patterns into clearly marked sections
Provide minimal examples for each feature
Include both inline and external script examples
Document common pitfalls and solutions

File Structure#

lib/
  index.html              # Main entry with routing and global state
  src/
    main.ts              # Minimal bootstrap (charge + navigate init)
    demo/
      index.ts           # Removed or minimal utilities only
      sections/          # Keep or convert to HTML partials
      utils.ts           # DOM utilities (may still be useful)
    pages/               # New directory for page templates
      home.html
      getting-started.html
      reactivity.html
      http.html
      state.html
      persistence.html
      animations.html
      forms.html
      css.html
      patterns.html
    styles/
      components.css     # Add tooltip styles here
      ...

Example Ideas#

Many of these are ideas, not planned to be implemented

Components#

Modal Dialog - Conditional rendering, focus trapping, backdrop, keyboard escape
Tabs & Accordion - Conditional rendering, active state management, keyboard navigation
Form Validation - Model binding, computed validation, conditional messages, error states

Client-Side (SPA/Static)#

✓ Counter - Basic signals, computed, event handling
✓ TodoMVC - List rendering, persistence, filtering, CRUD operations
Search with Autocomplete - Async effects, debouncing, API integration, keyboard navigation
Calculator - Event handling, computed expressions, button grid, operation state
Image Gallery - For loops, filtering, lightbox, category selection
Multi-Step Wizard - Form state across steps, validation per step, progress tracking, navigation
Note-Taking App - Rich CRUD, categories/tags, search/filter, localStorage persistence, markdown preview
Expense Tracker - Date handling, categories, computed totals/charts, filtering by date range, CSV export
Kanban Board - Drag-and-drop (via events), column management, task editing, state persistence
Timer/Stopwatch - Async effects, intervals, lap times, pause/resume, localStorage for history
Real-time Chat - SSE for messages, typing indicators, user presence, message history
Live Dashboard - SSE for metrics, charts updating in real-time, WebSocket fallback
Collaborative Editor - Operational transforms, SSE for changes, conflict resolution, cursor positions
Infinite Scroll Feed - Polling for new items, intersection observer, virtualized rendering
Admin Panel/CMS - CRUD operations, data tables, filters, pagination, bulk actions

Server-Side Rendered (SSR)#

These will live in an example repo.

Authentication Flows - Login, signup, password reset, email verification (Go, Python, Rust, Node)
File Upload with Progress - Chunked uploads, progress bars, validation (Go, Python, Rust, Node)
Search with Server-Side Filtering - Debounced search, paginated results (Go, Python, Rust, Node)

Desktop Apps#

Note Editor - Local file system, syntax highlighting, multi-tab, settings persistence
System Monitor - CPU/memory graphs, process list, real-time updates
Database Client - Table browser, query editor, result grid, export
Media Player - File browser, playlists, controls, metadata display