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)

3. Add Tooltip CSS Feature #

• 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