a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
hypermedia
frontend
signals
fix: broken doc links (#4)
* fix: dead links
* removed examples dir
+16
-311
+7
-8
ROADMAP.md
+7
-8
ROADMAP.md
···
18
18
| v0.3.0 | ✓ | [Global State](#global-state) |
19
19
| v0.4.0 | ✓ | [Animation & Transitions](#animation--transitions) |
20
20
| v0.5.0 | | [History API Routing Plugin](#history-api-routing-plugin) |
21
+
| | | [Navigation & History Management](#navigation--history-management) |
21
22
| | ✓ | [Refactor](#evaluator--binder-hardening) |
22
-
| | | [Persistence & Offline](#persistence--offline) |
23
-
| | | [Background Requests & Reactive Polling](#background-requests--reactive-polling) |
24
-
| v0.6.0 | | [Navigation & History Management](#navigation--history-management) |
23
+
| v0.6.0 | | [Background Requests & Reactive Polling](#background-requests--reactive-polling) |
25
24
| v0.7.0 | | [Streaming & Patch Engine](#streaming--patch-engine) |
26
25
| v0.8.0 | | PWA Capabilities |
26
+
| | | [Persistence & Offline](#persistence--offline) |
27
27
| v0.9.0 | | [Inspector & Developer Tools](#inspector--developer-tools) |
28
28
| v1.0.0 | | [Stable Release](#stable-release) |
29
29
···
72
72
**Goal:** Use JavaScript Proxies to improve reactivity ergonomics and automatic dependency tracking.
73
73
**Outcome:** More intuitive API with automatic dependency tracking and optional deep reactivity for objects/arrays.
74
74
**Summary:** Proxy-driven automatic dependency tracking, deep reactive() objects, reactive arrays, lazy signal creation, and debugging utilities improve reactivity ergonomics and performance.
75
-
**Notes:**
76
-
- Separate reactive() function for objects/arrays to gives users choice
77
-
- Keep .get()/.set() - explicitness is valuable for understanding reactivity (include in docs)
78
75
79
76
### Reactive Attributes & Event Modifiers
80
77
···
189
186
- Full API reference with examples
190
187
- Create generator in `@voltx/cli` package
191
188
- Finalized plugin registry and CLI (`volt plugins list/init`)
192
-
- Versioned documentation (stormlightlabs.github.io/volt)
189
+
- Versioned documentation (<https://stormlightlabs.github.io/volt>)
193
190
- Announcement post and release notes
194
191
- Community contribution guide & governance doc
195
192
···
198
195
### Evaluator & Binder Hardening
199
196
200
197
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.
198
+
199
+
### Naming
201
200
202
201
## Examples
203
202
···
235
234
236
235
- Authentication Flows - Login, signup, password reset, email verification (Go, Python, Rust, Node)
237
236
- File Upload with Progress - Chunked uploads, progress bars, validation (Go, Python, Rust, Node)
238
-
- Search with Server-Side Filtering - Debounced search, paginated results (Go, Python,Rust, Node)
237
+
- Search with Server-Side Filtering - Debounced search, paginated results (Go, Python, Rust, Node)
239
238
240
239
### Desktop Apps
241
240
+4
-4
docs/installation.md
+4
-4
docs/installation.md
···
139
139
</script>
140
140
```
141
141
142
-
See the [Server-Side Rendering & Lifecycle](./lifecycle) documentation for complete SSR patterns and hydration strategies.
142
+
See the [Server-Side Rendering & Lifecycle](./usage/lifecycle) documentation for complete SSR patterns and hydration strategies.
143
143
144
144
## Plugin Setup
145
145
···
178
178
## Next Up
179
179
180
180
- Read the [Framework Overview](./overview) to understand core concepts
181
-
- Learn about [State Management](./state) with signals and computed values
182
-
- Explore available [Bindings](./bindings) for DOM manipulation
183
-
- Check out [Expression Evaluation](./expressions) for template syntax
181
+
- Learn about [State Management](./usage/state) with signals and computed values
182
+
- Explore available [Bindings](./usage/bindings) for DOM manipulation
183
+
- Check out [Expression Evaluation](./usage/expressions) for template syntax
+4
-4
docs/usage/counter.md
+4
-4
docs/usage/counter.md
···
282
282
283
283
## Further Reading
284
284
285
-
- [State Management](../state) for advanced signal patterns
286
-
- [Bindings](../bindings) for complete binding reference
287
-
- [Expressions](../expressions) for template syntax details
288
-
- [Lifecycle](../lifecycle) for SSR and hydration
285
+
- [State Management](./state) for advanced signal patterns
286
+
- [Bindings](./bindings) for complete binding reference
287
+
- [Expressions](./expressions) for template syntax details
288
+
- [Lifecycle](./lifecycle) for SSR and hydration
+1
-1
docs/usage/state.md
+1
-1
docs/usage/state.md
···
37
37
- Logging or analytics
38
38
- Coordinating multiple signals
39
39
40
-
For asynchronous operations, use `asyncEffect()` (see [asyncEffect](./usage/async-effect)) which handles cleanup of pending operations when dependencies change or the effect is disposed.
40
+
For asynchronous operations, use `asyncEffect()` (see [asyncEffect](./async-effect.md)) which handles cleanup of pending operations when dependencies change or the effect is disposed.
41
41
42
42
## Declarative State
43
43
-61
examples/TODO.md
-61
examples/TODO.md
···
1
-
# Example TODO
2
-
3
-
Planned examples to demonstrate Volt.js features & show Volt.css
4
-
5
-
All examples use declarative mode by default (data-volt-state, charge()). This ensures users can build functional apps without writing JavaScript.
6
-
7
-
## Example Set
8
-
9
-
### Counter
10
-
11
-
Basic reactivity demonstration showing core primitives.
12
-
13
-
- **Features**: data-volt-state, data-volt-computed, data-volt-text, data-volt-on-click, data-volt-class
14
-
- **Shows**: Inline state declaration, computed values, event handlers that modify signals, conditional classes
15
-
- **Structure**: Single index.html file with inline state
16
-
17
-
### Form Validation
18
-
19
-
Real-world form handling with reactive validation.
20
-
21
-
- **Features**: data-volt-state, data-volt-model, data-volt-if/else, data-volt-computed for validation, data-volt-bind:disabled
22
-
- **Shows**: Two-way form binding, computed validation rules, conditional error messages, reactive button states
23
-
- **Structure**: Single index.html with validation logic in computed expressions
24
-
25
-
### Persistent Settings
26
-
27
-
Settings panel that survives page refresh.
28
-
29
-
- **Features**: data-volt-state, data-volt-model, persist plugin with localStorage
30
-
- **Shows**: Plugin usage, state persistence across page loads, settings form
31
-
- **Structure**: Single index.html demonstrating data-volt-persist
32
-
33
-
### HTTP Todo List
34
-
35
-
Full-featured todo app with server persistence and hypermedia.
36
-
37
-
- **Features**: data-volt-get/patch/post/delete, data-volt-swap, data-volt-indicator, data-volt-retry, data-volt-for
38
-
- **Shows**: Hypermedia approach, server communication, DOM swapping, loading states, error handling, smart retry, list rendering
39
-
- **Structure**: index.html + minimal bootstrap script to fetch initial todos
40
-
41
-
Made with a Go server with filesystem-based JSON persistence
42
-
43
-
**Implementation**:
44
-
45
-
- main.go with model, view & controller files
46
-
- Filesystem-based storage (todos.json)
47
-
- REST endpoints:
48
-
- GET /todos - List all todos (returns HTML fragment)
49
-
- POST /todos - Create new todo (returns HTML fragment)
50
-
- PATCH /todos/:id - Update todo (partial - complete, edit text)
51
-
- DELETE /todos/:id - Delete todo (returns empty or success fragment)
52
-
- Returns HTML fragments for Volt's DOM swapping
53
-
- REST API for demonstration
54
-
55
-
**Storage Format**:
56
-
57
-
```json
58
-
[
59
-
{"id": "1", "text": "Example todo", "completed": false}
60
-
]
61
-
```
-89
examples/counter/index.html
-89
examples/counter/index.html
···
1
-
<!DOCTYPE html>
2
-
<html lang="en">
3
-
<head>
4
-
<meta charset="UTF-8">
5
-
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6
-
<title>Counter - Volt.js Example</title>
7
-
<link rel="stylesheet" href="../dist/volt.min.css">
8
-
<style>
9
-
.counter-display {
10
-
font-size: 4rem;
11
-
font-weight: bold;
12
-
text-align: center;
13
-
margin: var(--space-2xl) 0;
14
-
transition: color var(--transition-base);
15
-
}
16
-
.counter-display.negative { color: var(--color-error); }
17
-
.counter-display.zero { color: var(--color-text-muted); }
18
-
.counter-display.positive { color: var(--color-success); }
19
-
20
-
.button-group {
21
-
display: flex;
22
-
gap: var(--space-sm);
23
-
justify-content: center;
24
-
flex-wrap: wrap;
25
-
}
26
-
27
-
.stats {
28
-
display: grid;
29
-
grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
30
-
gap: var(--space-md);
31
-
margin-top: var(--space-xl);
32
-
padding-top: var(--space-xl);
33
-
border-top: 1px solid var(--color-border);
34
-
}
35
-
36
-
.stat {
37
-
text-align: center;
38
-
padding: var(--space-md);
39
-
background: var(--color-bg-alt);
40
-
border-radius: var(--radius-md);
41
-
}
42
-
</style>
43
-
</head>
44
-
<body>
45
-
<article
46
-
data-volt
47
-
data-volt-state='{"count": 0}'
48
-
data-volt-computed:doubled="count * 2"
49
-
data-volt-computed:is-negative="count < 0"
50
-
data-volt-computed:is-zero="count === 0"
51
-
data-volt-computed:is-positive="count > 0"
52
-
>
53
-
<h1>Interactive Counter</h1>
54
-
<p>A simple demonstration of Volt.js reactivity with inline state, computed values, and conditional styling.</p>
55
-
56
-
<div class="counter-display" data-volt-class="{negative: isNegative, zero: isZero, positive: isPositive}">
57
-
<span data-volt-text="count">0</span>
58
-
</div>
59
-
60
-
<div class="button-group">
61
-
<button data-volt-on-click="count.set(count.get() - 10)">-10</button>
62
-
<button data-volt-on-click="count.set(count.get() - 1)">-1</button>
63
-
<input type="reset" value="Reset" data-volt-on-click="count.set(0)">
64
-
<button data-volt-on-click="count.set(count.get() + 1)">+1</button>
65
-
<button data-volt-on-click="count.set(count.get() + 10)">+10</button>
66
-
</div>
67
-
68
-
<div class="stats">
69
-
<div class="stat">
70
-
<h6>Current Value</h6>
71
-
<p data-volt-text="count">0</p>
72
-
</div>
73
-
<div class="stat">
74
-
<h6>Doubled</h6>
75
-
<p data-volt-text="doubled">0</p>
76
-
</div>
77
-
<div class="stat">
78
-
<h6>Status</h6>
79
-
<p data-volt-text="isNegative ? 'negative' : (isZero ? 'zero' : 'positive')">zero</p>
80
-
</div>
81
-
</div>
82
-
</article>
83
-
84
-
<script type="module">
85
-
import { charge } from './../dist/volt.min.js';
86
-
charge();
87
-
</script>
88
-
</body>
89
-
</html>
-144
examples/form-validation/index.html
-144
examples/form-validation/index.html
···
1
-
<!DOCTYPE html>
2
-
<html lang="en">
3
-
<head>
4
-
<meta charset="UTF-8">
5
-
<meta name="viewport" content="width=device-width, initial-scale=1.0">
6
-
<title>Form Validation - Volt.js Example</title>
7
-
<link rel="stylesheet" href="../dist/volt.min.css">
8
-
<style>
9
-
.error {
10
-
color: var(--color-error);
11
-
font-size: var(--font-size-sm);
12
-
margin-top: calc(-1 * var(--space-sm));
13
-
margin-bottom: var(--space-md);
14
-
}
15
-
16
-
.success {
17
-
padding: var(--space-md);
18
-
background: var(--color-bg-alt);
19
-
border-left: 4px solid var(--color-success);
20
-
border-radius: var(--radius-md);
21
-
margin: var(--space-lg) 0;
22
-
}
23
-
24
-
.form-group {
25
-
margin-bottom: var(--space-md);
26
-
}
27
-
28
-
input.invalid {
29
-
border-color: var(--color-error);
30
-
}
31
-
32
-
input.valid {
33
-
border-color: var(--color-success);
34
-
}
35
-
</style>
36
-
</head>
37
-
<body>
38
-
<article
39
-
data-volt
40
-
data-volt-state='{"email": "", "password": "", "confirmPassword": "", "agreedToTerms": false, "submitted": false}'
41
-
data-volt-computed:email-valid="email.length > 0 && email.includes('@') && email.includes('.')"
42
-
data-volt-computed:password-valid="password.length >= 8"
43
-
data-volt-computed:passwords-match="password === confirmPassword && confirmPassword.length > 0"
44
-
data-volt-computed:form-valid="emailValid && passwordValid && passwordsMatch && agreedToTerms">
45
-
<h1>Sign Up</h1>
46
-
<p>
47
-
Create your account with real-time validation. All validation rules are defined in HTML using computed
48
-
expressions.
49
-
</p>
50
-
51
-
<form data-volt-on-submit="submitted.set(true); $event.preventDefault()">
52
-
<div class="form-group">
53
-
<label for="email">Email Address</label>
54
-
<input
55
-
type="email"
56
-
id="email"
57
-
required
58
-
data-volt-model="email"
59
-
data-volt-class="{valid: email.length > 0 && emailValid, invalid: email.length > 0 && !emailValid}"
60
-
placeholder="you@example.com">
61
-
<div class="error" data-volt-if="email.length > 0 && !emailValid">
62
-
Please enter a valid email address.
63
-
</div>
64
-
</div>
65
-
66
-
<div class="form-group">
67
-
<label for="password">Password</label>
68
-
<input
69
-
type="password"
70
-
id="password"
71
-
required
72
-
data-volt-model="password"
73
-
data-volt-class="{valid: passwordValid, invalid: password.length > 0 && !passwordValid}"
74
-
placeholder="At least 8 characters">
75
-
<div class="error" data-volt-if="password.length > 0 && !passwordValid">
76
-
Password must be at least 8 characters long.
77
-
</div>
78
-
</div>
79
-
80
-
<div class="form-group">
81
-
<label for="confirmPassword">Confirm Password</label>
82
-
<input
83
-
type="password"
84
-
id="confirmPassword"
85
-
required
86
-
data-volt-model="confirmPassword"
87
-
data-volt-class="{valid: passwordsMatch, invalid: confirmPassword.length > 0 && !passwordsMatch}"
88
-
placeholder="Re-enter your password">
89
-
<div class="error" data-volt-if="confirmPassword.length > 0 && !passwordsMatch">
90
-
Passwords do not match.
91
-
</div>
92
-
</div>
93
-
94
-
<div class="form-group">
95
-
<label>
96
-
<input type="checkbox" data-volt-model="agreedToTerms" required>
97
-
I agree to the terms and conditions
98
-
</label>
99
-
</div>
100
-
101
-
<button type="submit" data-volt-bind:disabled="!formValid">
102
-
Create Account
103
-
</button>
104
-
</form>
105
-
106
-
<div class="success" data-volt-if="submitted && formValid">
107
-
<strong>Success!</strong> Your account has been created.
108
-
<details>
109
-
<summary>Form Data</summary>
110
-
<dl>
111
-
<dt>Email</dt>
112
-
<dd data-volt-text="email"></dd>
113
-
<dt>Password</dt>
114
-
<dd>••••••••</dd>
115
-
<dt>Terms Accepted</dt>
116
-
<dd data-volt-text="agreedToTerms ? 'Yes' : 'No'"></dd>
117
-
</dl>
118
-
</details>
119
-
</div>
120
-
121
-
<details style="margin-top: var(--space-xs);">
122
-
<summary>View Current State</summary>
123
-
<pre>
124
-
<code>{
125
-
"email": "<span data-volt-text="email"></span>",
126
-
"password": "<span data-volt-text="password"></span>",
127
-
"confirmPassword": "<span data-volt-text="confirmPassword"></span>",
128
-
"agreedToTerms": <span data-volt-text="agreedToTerms"></span>,
129
-
"submitted": <span data-volt-text="submitted"></span>,
130
-
"emailValid": <span data-volt-text="emailValid"></span>,
131
-
"passwordValid": <span data-volt-text="passwordValid"></span>,
132
-
"passwordsMatch": <span data-volt-text="passwordsMatch"></span>,
133
-
"formValid": <span data-volt-text="formValid"></span>
134
-
}</code>
135
-
</pre>
136
-
</details>
137
-
</article>
138
-
139
-
<script type="module">
140
-
import { charge } from "./../dist/volt.min.js";
141
-
charge();
142
-
</script>
143
-
</body>
144
-
</html>