docs/overview.md at main · desertthunder.dev/voltx

desertthunder.dev / voltx
a reactive (signals based) hypermedia web framework (wip) stormlightlabs.github.io/volt/
hypermedia frontend signals
voltx / docs / overview.md
at main 3.0 kB view raw view rendered
 1---
 2outline: deep
 3---
 4
 5# Overview
 6
 7VoltX is a lightweight, hypermedia based reactive framework for building declarative UIs.
 8
 9It combines HTML-driven behavior via `data-volt-*` attributes with signal-based reactivity.
10
11## Features
12
13### Reactivity
14
15- Signal-based state management with `signal`, `computed`, and `effect` primitives
16- Predicatable direct DOM updates without virtual DOM diffing
17
18### Hypermedia Integration
19
20- Declarative HTTP requests with `data-volt-get`, `data-volt-post`, `data-volt-put`, `data-volt-patch`, and `data-volt-delete`
21- Multiple DOM swap strategies for server-rendered HTML fragments/partials
22- "Smart" retry with exponential backoff for failed requests
23- Automatic form serialization
24
25### Plugins
26
27- Built-In
28    - State persistence across page loads using `localStorage`, `sessionStorage`, or `IndexedDB`
29    - Scroll management including position restore, scroll-to, scroll-spy, and smooth scrolling
30    - URL synchronization for query parameters and hash-based routing
31- Extensibility
32    - Custom plugin system via `registerPlugin` for domain-specific bindings
33    - Global lifecycle hooks for mount, unmount, and binding creation
34    - Automatic cleanup management
35
36### Design Constraints
37
38- Core runtime under 15 KB gzipped
39- Zero dependencies
40- No custom build systems
41- TypeScript source
42- Every feature tested
43
44## Concepts
45
46| Concept  | Description                                                                                               |
47| -------- | --------------------------------------------------------------------------------------------------------- |
48| Signals  | Reactive primitives that automatically update DOM bindings when changed.                                  |
49| Bindings | `data-volt-text`, `data-volt-html`, `data-volt-class` connect attributes or text to expressions.          |
50| Actions  | `data-volt-on-click`, `data-volt-on-input`, etc. attach event handlers declaratively.                     |
51| Streams  | `data-volt-stream="/events"` listens for SSE or WebSocket updates and applies JSON patches.               |
52| Plugins  | Modular extensions (`data-volt-persist`, `data-volt-surge`, `data-volt-shift`, etc.) to enhance the core. |
53
54## VoltX.css
55
56VoltX ships with an optional classless CSS framework inspired by Pico CSS and Tufte CSS. It provides beautiful, semantic styling for HTML elements without requiring any CSS classes—just write semantic markup and it looks great out of the box.
57
58Features include typography with modular scale, Tufte-style sidenotes, styled form elements, dialogs, accordions, tooltips, tables, and more.
59
60Here are some highlights
61
62![VoltX Typography](./images/voltx-css_typography.png)
63
64![VoltX Structured Content](./images/voltx-css_structured-content.png)
65
66![VoltX Components](./images/voltx-css_components.png)
67
68## Browser Support
69
70Modern browsers (Chrome 90+, Firefox 88+, Safari 14+) with support for:
71
72- ES modules
73- Proxy objects
74- CSS custom properties