a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
hypermedia
frontend
signals
feat: add "auto" sidebar
* update styling for vp site
* move spec docs to separate dir
* reorganized ROADMAP
+287
-241
+189
-58
ROADMAP.md
+189
-58
ROADMAP.md
···
1
1
# Roadmap
2
2
3
+
- [Completed](#completed)
4
+
- [TODO](#to-do)
5
+
- [Examples (Planned)](#examples)
6
+
3
7
| Version | State | Milestone | Summary |
4
8
| ------- | ----- | ---------------------------------------------------------- | ------------------------------------------------------------------------ |
5
9
| | ✓ | [Foundations](#foundations) | Initial project setup, tooling, and reactive signal prototype. |
6
-
| | ✓ | [Reactivity & Bindings](#reactivity--bindings) | Core DOM bindings (`data-x-*`) and declarative updates. |
10
+
| | ✓ | [Reactivity & Bindings](#reactivity--bindings) | Core DOM bindings (`dava-volt-*`) and declarative updates. |
7
11
| | ✓ | [Actions & Effects](#actions--effects) | Event system and derived reactivity primitives. |
8
-
| | | [Plugins Framework](#plugins-framework) | Modular plugin system and first built-in plugin set. |
12
+
| | ✓ | [Plugins Framework](#plugins-framework) | Modular plugin system and first built-in plugin set. |
9
13
| | | [Streaming & Patch Engine](#streaming--patch-engine) | SSE/WebSocket JSON patch streaming. |
10
14
| | | [Persistence & Offline](#persistence--offline) | State persistence, storage sync, and fallback behaviors. |
11
15
| v0.1.0 | ✓ | [Markup Based Reactivity](#markup-based-reactivity) | Allow users to write apps without any bundled JS |
···
15
19
| v0.5.0 | | PWA Capabilities | TODO |
16
20
| v1.0.0 | | [Release](#stable-release) | Public API freeze, plugin registry, and versioned documentation. |
17
21
18
-
## Details
22
+
## Completed
19
23
20
24
_NOTE_: `data-x-*` is now `data-volt-*`
21
25
···
44
48
**Goal:** Add event-driven behavior and derived reactivity.
45
49
**Outcome:** Fully functional reactive UI layer with event bindings and computed updates.
46
50
**Deliverables:**
47
-
- ✓ Event binding system (`data-x-on-*`)
51
+
- ✓ Event binding system (`dava-volt-on-*`)
48
52
- ✓ `$el` and `$event` scoped references
49
53
- ✓ Derived signals (`computed`, `effect`)
50
54
- ✓ Async effects (e.g., fetch triggers)
···
57
61
- ✓ `registerPlugin(name, fn)` API
58
62
- ✓ Context and lifecycle hooks
59
63
- ✓ Built-ins:
60
-
- ✓ `data-x-persist`
61
-
- ✓ `data-x-scroll`
62
-
- ✓ `data-x-url`
63
-
- ✓ Tests & registry
64
-
- ✓ Setup test coverage with generous thresholds (~50%)
65
-
- Example in docs/examples/plugins.md
66
-
- End-to-end examples (counter, form, live field updates)
67
-
- `docs/examples/reactivity.md`
68
-
- `actions`, `effects`, `signals`
64
+
- ✓ `dava-volt-persist`
65
+
- ✓ `dava-volt-scroll`
66
+
- ✓ `dava-volt-url`
67
+
- ✓ Registry
68
+
69
+
## To-Do
70
+
71
+
### Markup Based Reactivity
72
+
73
+
**Goal:** Allow Volt apps to declare state, bindings, and behavior entirely in HTML markup
74
+
**Outcome:** Authors can ship examples without companion JavaScript bundles
75
+
**Deliverables:**
76
+
- ✓ Auto-bootstrapping loader (`volt.min.js`) that detects `data-volt` roots and hydrates one scope per root.
77
+
- ✓ Declarative state primitives (`data-volt-state`, `data-volt-computed:*`) aligned with `docs/reactivity-spec.md`.
78
+
- ✓ Binding directives for text, attributes, classes, styles, and two-way form controls (`data-volt-[bind|text|model|class:*]`).
79
+
- ✓ Control-flow directives (`data-volt-for`, `data-volt-if`, `data-volt-else`) with lifecycle-safe teardown.
80
+
- ✓ Declarative event system (`data-volt-on:*`) with helper surface for list mutations and plugin hooks.
81
+
- Sandboxed expression evaluator
82
+
- SSR compatibility helpers
83
+
84
+
### Backend Integration & HTTP Actions
85
+
86
+
**Goal:** Provide backend integration with declarative HTTP requests and responses.
87
+
**Outcome:** Volt.js can make backend requests and update the DOM
88
+
**Deliverables:**
89
+
- HTTP action system (`data-volt-get`, `data-volt-post`, `data-volt-put`, `data-volt-patch`, `data-volt-delete`)
90
+
- Request configuration (`data-volt-trigger`, `data-volt-target`, `data-volt-swap`)
91
+
- Swap strategies (innerHTML, outerHTML, beforebegin, afterbegin, beforeend, afterend, delete, none)
92
+
- Loading states and indicators (`data-volt-indicator`)
93
+
- Error handling and retry logic
94
+
- See [svelte](https://svelte.dev/docs/svelte/await-expressions) for inspiration for loading & errors (`#await`)
95
+
- Form serialization and submission
96
+
- Request/response headers customization
69
97
70
98
### Streaming & Patch Engine
71
99
72
-
**Goal:** Enable real-time updates via SSE/WebSocket streaming.
100
+
**Goal:** Enable real-time updates via SSE/WebSocket streaming with intelligent DOM patching.
73
101
**Outcome:** Volt.js can receive and apply live updates from the server
74
102
**Deliverables:**
75
-
- JSON Patch parser and DOM applier
76
-
- `data-volt-stream` attribute
77
-
- Reconnection/backoff logic
78
-
- Raise test coverage threshold to 60%
79
-
- Integration test with mock SSE server
80
-
- Benchmarks for patch vs re-render
81
-
- Performance test suite
103
+
- Server-Sent Events (SSE) integration
104
+
- `data-volt-stream` attribute for SSE endpoints
105
+
- Signal patching from backend (`data-signals-*` merge system)
106
+
- Backend action system with `$$action()` syntax (TBD on final syntax decision)
107
+
- JSON Patch parser and DOM morphing engine
108
+
- WebSocket as alternative to SSE
109
+
- `data-volt-ignore-morph` for selective patch exclusion
82
110
83
111
### Persistence & Offline
84
112
···
86
114
**Outcome:** Resilient state persistence and offline replay built into Volt.js.
87
115
**Deliverables:**
88
116
- ✓ Persistent signals (localStorage, sessionStorage, indexedDb)
89
-
- ✓ Storage plugin (`data-x-persist`)
90
-
- Offline queue for deferred stream events
91
-
- Sync strategy API (merge, overwrite, patch)
92
-
- Example apps: note editor ([golang](#examples)), counter with persistence ([spa](#examples))
117
+
- ✓ Storage plugin (`data-volt-persist`)
118
+
- Storage modifiers on signals:
119
+
- `.local` modifier for localStorage persistence
120
+
- `.session` modifier for sessionStorage persistence
121
+
- `.ifmissing` modifier for conditional initialization
122
+
- Offline queue for deferred stream events and HTTP requests
123
+
- Sync strategy API (merge, overwrite, patch) for conflict resolution
124
+
- Service Worker integration for offline-first apps
125
+
- Background sync for deferred requests
126
+
- Cache invalidation strategies
127
+
- Cross-tab synchronization via `BroadcastChannel`
128
+
129
+
### Reactive Attributes & Event Modifiers
130
+
131
+
**Goal:** Extend Volt.js with expressive attribute patterns and event options for fine-grained control.
132
+
**Outcome:** Volt.js supports rich declarative behaviors and event semantics built entirely on standard DOM APIs.
133
+
**Deliverables:**
134
+
- `data-x-show` — toggles element visibility via CSS rather than DOM removal (complements `data-x-if`)
135
+
- `data-x-style` — binds inline styles to reactive expressions
136
+
- `data-x-skip` — marks elements or subtrees to exclude from Volt’s reactive parsing
137
+
- `data-x-cloak` — hides content until the Volt runtime initializes
138
+
- Event options for `data-x-on-*` attributes:
139
+
- `.prevent` — calls `preventDefault()` on the event
140
+
- `.stop` — stops propagation
141
+
- `.self` — triggers only when the event target is the bound element
142
+
- `.window` — attaches the listener to `window`
143
+
- `.document` — attaches the listener to `document`
144
+
- `.once` — runs the handler a single time
145
+
- `.debounce` — defers handler execution (optional milliseconds)
146
+
- `.throttle` — limits handler frequency (optional milliseconds)
147
+
- `.passive` — adds a passive event listener for scroll/touch performance
148
+
- Input options for `data-x-bind` and `data-x-model`:
149
+
- `.number` — coerces values to numbers
150
+
- `.trim` — removes surrounding whitespace
151
+
- `.lazy` — syncs only on `change` instead of `input`
152
+
- `.debounce` — delays updates to reduce jitter
153
+
154
+
### Global State
155
+
156
+
**Goal:** Implement store/context pattern
157
+
**Outcome:** Volt.js provides intuitive global state management
158
+
**Deliverables:**
159
+
- `$refs` - Scoped element references via dava-volt-ref="name". Provides an object mapping ref names to DOM nodes.
160
+
- Example: `dava-volt-on-click="$refs.username.focus()"`
161
+
- `$next()` - Defers execution to the next microtask tick after DOM updates.
162
+
- Example: `dava-volt-on-click="$count++; $next(() => console.log('updated'))"`
163
+
- `$watch(expr, fn)` - Imperatively observes a reactive signal or expression within the current scope.
164
+
- Example: `dava-volt-init="$watch('count', v => console.log(v))"`
165
+
- `$emit(event, detail?)` - Dispatches a native CustomEvent from the current element.
166
+
- Example: `dava-volt-on-click="$emit('user:save', { id })"`
167
+
- `$store` - Accesses global reactive state registered with Volt’s global store.
168
+
- Example: `dava-volt-text="$store.theme"`
169
+
- `$uid(name?)` - Generates a unique, deterministic ID string within the current scope.
170
+
- Example: `dava-volt-id="$uid('field')"`
171
+
- `$root` - Reference to the root element of the active reactive scope.
172
+
- `$scope` - Reference to the current reactive scope object (signals + context).
93
173
94
174
### Animation & Transitions
95
175
96
-
**Goal:** Add animation primitives for smooth UI transitions.
176
+
**Goal:** Add animation primitives for smooth UI transitions with Alpine/Datastar parity.
97
177
**Outcome:** Volt.js enables declarative animations and view transitions alongside reactivity.
98
178
**Deliverables:**
99
-
- `data-volt-animate` plugin
100
-
- View Transition API support (when available)
179
+
- `data-volt-transition` directive with enter/leave transitions
180
+
- Transition modifiers (duration, delay, opacity, scale, etc.)
181
+
- View Transitions API integration (when available)
101
182
- CSS-based transition helpers
102
-
- Timing utilities (`transition`, `raf`)
103
-
- Plugin tests and performance profiling
183
+
- `data-volt-animate` plugin for keyframe animations
184
+
- Timing utilities and easing functions
185
+
- Integration with `data-volt-if` and `data-volt-show` for automatic transitions
186
+
187
+
### Background Requests & Reactive Polling
188
+
189
+
**Goal:** Enable declarative background data fetching and periodic updates within the Volt.js runtime.
190
+
**Outcome:** Volt.js elements can fetch or refresh data automatically based on time, visibility, or reactive conditions.
191
+
**Deliverables:**
192
+
- `dava-volt-fetch` attribute for declarative background requests
193
+
- Configurable polling intervals, delays, and signal-based triggers
194
+
- `dava-volt-visible` for fetching when an element enters the viewport (`IntersectionObserver`)
195
+
- Background task scheduler with priority management
196
+
- Automatic cancellation of requests when elements are unmounted
197
+
- Conditional execution tied to reactive signals
198
+
- Integration hooks for loading and pending states
199
+
200
+
### Navigation & History Management
201
+
202
+
**Goal:** Introduce seamless client-side navigation and stateful history control using web standards.
203
+
**Outcome:** Volt.js provides enhanced navigation behavior with minimal overhead and full accessibility support.
204
+
**Deliverables:**
205
+
- `dava-volt-navigate` for intercepting link and form actions
206
+
- Integration with the History API (`pushState`, `replaceState`, `popState`)
207
+
- Reactive synchronization of route and signal state
208
+
- Smooth page and fragment transitions coordinated with Volt’s signal system
209
+
- Native back/forward button support
210
+
- Scroll position persistence and restoration
211
+
- Optional preloading of linked resources on hover or idle
212
+
- `dava-volt-url` for declarative history updates
213
+
- Optional View Transition API integration for animated route changes
104
214
105
215
### Inspector & Developer Tools
106
216
···
110
220
- Developer overlay for inspecting signals, subscriptions, and effects
111
221
- Dev logging toggle (`Volt.debug = true`)
112
222
- Browser console integration (`window.$volt.inspect()`)
113
-
- Visualization plugin for dependency graph
114
-
- Testing coverage for dev mode
223
+
- Signal dependency graph visualization
224
+
- Performance profiling tools
225
+
- Request/response debugging (HTTP actions, SSE streams)
226
+
- Time-travel debugging for signal history
227
+
- Browser DevTools extension
115
228
116
229
### Documentation & Stability Pass
117
230
···
120
233
**Deliverables:**
121
234
- ✓ Documentation site (VitePress)
122
235
- Full API reference with examples
123
-
- Migration and versioning guide
124
236
- Performance benchmarks (vs htmx, Alpine)
125
237
- Browser matrix tests (Chromium, Gecko, WebKit)
126
-
- Accessibility audits (ARIA reactivity)
238
+
- Accessibility audits (ARIA)
127
239
- Freeze API surface for 1.0
128
240
129
241
### Stable Release
130
242
131
-
**Goal:** Ship the first stable version of Volt.js.
243
+
**Goal:** Ship the first stable version of Volt.js
132
244
**Outcome:** Volt.js 1.0 is released as a mature, fully documented, type-safe, reactive web framework
133
245
**Deliverables:**
134
246
- Finalized plugin registry and CLI (`volt plugins list/init`)
···
136
248
- Announcement post and release notes
137
249
- Community contribution guide & governance doc
138
250
139
-
### Markup Based Reactivity
251
+
## Examples
252
+
253
+
Many of these are ideas, not planned to be implemented
254
+
255
+
### Components
256
+
257
+
- Modal Dialog - Conditional rendering, focus trapping, backdrop, keyboard escape
258
+
- Tabs & Accordion - Conditional rendering, active state management, keyboard navigation
259
+
- Form Validation - Model binding, computed validation, conditional messages, error states
260
+
261
+
### Client-Side (SPA/Static)
262
+
263
+
- ✓ Counter - Basic signals, computed, event handling
264
+
- ✓ TodoMVC - List rendering, persistence, filtering, CRUD operations
265
+
- Search with Autocomplete - Async effects, debouncing, API integration, keyboard navigation
266
+
- Calculator - Event handling, computed expressions, button grid, operation state
267
+
- Image Gallery - For loops, filtering, lightbox, category selection
268
+
269
+
- Multi-Step Wizard - Form state across steps, validation per step, progress tracking, navigation
270
+
- Note-Taking App - Rich CRUD, categories/tags, search/filter, localStorage persistence, markdown preview
271
+
- Expense Tracker - Date handling, categories, computed totals/charts, filtering by date range, CSV export
272
+
- Kanban Board - Drag-and-drop (via events), column management, task editing, state persistence
273
+
- Timer/Stopwatch - Async effects, intervals, lap times, pause/resume, localStorage for history
274
+
275
+
- Real-time Chat - SSE for messages, typing indicators, user presence, message history
276
+
- Live Dashboard - SSE for metrics, charts updating in real-time, WebSocket fallback
277
+
- Collaborative Editor - Operational transforms, SSE for changes, conflict resolution, cursor positions
278
+
- Infinite Scroll Feed - Polling for new items, intersection observer, virtualized rendering
279
+
- Admin Panel/CMS - CRUD operations, data tables, filters, pagination, bulk actions
280
+
281
+
### Server-Side Rendered (SSR)
282
+
283
+
These will live in an example repo.
140
284
141
-
**Goal:** Allow Volt apps to declare state, bindings, and behavior entirely in HTML markup
142
-
**Outcome:** Authors can ship examples without companion JavaScript bundles
143
-
**Deliverables:**
144
-
- ✓ Auto-bootstrapping loader (`volt.min.js`) that detects `data-volt` roots and hydrates one scope per root.
145
-
- ✓ Declarative state primitives (`data-volt-state`, `data-volt-computed:*`) aligned with `docs/reactivity-spec.md`.
146
-
- ✓ Binding directives for text, attributes, classes, styles, and two-way form controls (`data-volt-[bind|text|model|class:*]`).
147
-
- ✓ Control-flow directives (`data-volt-for`, `data-volt-if`, `data-volt-else`) with lifecycle-safe teardown.
148
-
- ✓ Declarative event system (`data-volt-on:*`) with helper surface for list mutations and plugin hooks.
149
-
- SSR compatibility helpers and sandboxed expression evaluator
285
+
- Authentication Flows - Login, signup, password reset, email verification (Go, Python, Rust, Node)
286
+
- File Upload with Progress - Chunked uploads, progress bars, validation (Go, Python, Rust, Node)
287
+
- Search with Server-Side Filtering - Debounced search, paginated results (Go, Python,Rust, Node)
150
288
151
-
## Examples
289
+
### Desktop Apps
152
290
153
-
- SSR
154
-
- Django (separate repo)
155
-
- FastAPI + jinja2 (separate repo)
156
-
- Golang + templ (separate repo)
157
-
- Fastify (separate repo)
158
-
- Express
159
-
- Golang
160
-
- SPA
161
-
- Web
162
-
- Tauri
163
-
- Wails
291
+
- Note Editor - Local file system, syntax highlighting, multi-tab, settings persistence
292
+
- System Monitor - CPU/memory graphs, process list, real-time updates
293
+
- Database Client - Table browser, query editor, result grid, export
294
+
- Media Player - File browser, playlists, controls, metadata display
164
295
165
296
## Docs
166
297
···
168
299
- [ ] Add async effect guide covering abort signals, debounce/throttle, retries, and `onError` handling.
169
300
- [ ] Write lifecycle instrumentation docs for `registerGlobalHook`, `registerElementHook`, `getElementBindings`, and plugin `context.lifecycle` callbacks.
170
301
- [ ] Explain `data-volt-bind:*` semantics, especially boolean attribute handling and dependency subscription behavior.
171
-
- [ ] Refresh README and overview content to use `data-volt-*` naming and reflect the current module layout.
302
+
- [ ] Refresh README and overview content to reflect the current module layout.
+6
-8
docs/.vitepress/config.ts
+6
-8
docs/.vitepress/config.ts
···
1
1
import { defineConfig } from "vitepress";
2
+
import { u } from "./utils";
2
3
3
4
// https://vitepress.dev/reference/site-config
4
5
export default defineConfig({
···
10
11
{ text: "Home", link: "/" },
11
12
{ text: "Overview", link: "/overview" },
12
13
{ text: "CSS", link: "/css/volt-css" },
13
-
{ text: "API", link: "/api-examples" },
14
+
{ text: "API", link: "/api" },
14
15
],
15
16
sidebar: [
16
-
{
17
-
text: "Getting Started",
18
-
items: [{ text: "Introduction", link: "/" }, { text: "Overview", link: "/overview" }],
19
-
},
17
+
{ text: "Getting Started", items: [{ text: "Overview", link: "/overview" }] },
20
18
{
21
19
text: "CSS",
22
20
collapsed: false,
23
-
items: [{ text: "Volt CSS", link: "/css/volt-css" }, { text: "CSS Reference", link: "/css/semantics" }],
21
+
items: [{ text: "Volt CSS", link: "/css/volt-css" }, { text: "Reference", link: "/css/semantics" }],
24
22
},
25
-
{ text: "API Reference", collapsed: false, items: [{ text: "Runtime API", link: "/api-examples" }] },
26
-
{ text: "Plugin System", collapsed: false, items: [{ text: "Plugin Spec", link: "/plugin-spec" }] },
23
+
{ text: "Specs", collapsed: true, items: u.scanDir("spec", "/spec") },
24
+
{ text: "API Reference", collapsed: true, items: u.scanDir("api", "/api") },
27
25
],
28
26
socialLinks: [{ icon: "github", link: "https://github.com/stormlightlabs/volt" }],
29
27
},
+10
-18
docs/.vitepress/theme/style.css
+10
-18
docs/.vitepress/theme/style.css
···
15
15
--vp-c-sonics-green-1: #2a6b5d;
16
16
--vp-c-sonics-green-2: #1f5248;
17
17
--vp-c-sonics-green-3: #173F35;
18
-
--vp-c-sonics-green-soft: rgba(23, 63, 53, 0.14);
18
+
--vp-c-sonics-green-soft: #c5dbd7;
19
19
20
20
/* SuperSonics Yellow - Secondary/Warning */
21
21
--vp-c-sonics-yellow-1: #ffbb33;
22
22
--vp-c-sonics-yellow-2: #ffad1a;
23
23
--vp-c-sonics-yellow-3: #FFA300;
24
-
--vp-c-sonics-yellow-soft: rgba(255, 163, 0, 0.14);
24
+
--vp-c-sonics-yellow-soft: #ffefc2;
25
25
26
26
/* SuperSonics Red - Danger */
27
27
--vp-c-sonics-red-1: #c24348;
28
28
--vp-c-sonics-red-2: #b03338;
29
29
--vp-c-sonics-red-3: #9E2A2F;
30
-
--vp-c-sonics-red-soft: rgba(158, 42, 47, 0.14);
30
+
--vp-c-sonics-red-soft: #edd5d7;
31
31
32
32
/* SuperSonics Bronze - Accent */
33
33
--vp-c-sonics-bronze-1: #a3836b;
34
34
--vp-c-sonics-bronze-2: #97735a;
35
35
--vp-c-sonics-bronze-3: #8B634B;
36
-
--vp-c-sonics-bronze-soft: rgba(139, 99, 75, 0.14);
36
+
--vp-c-sonics-bronze-soft: #e8ddd3;
37
37
}
38
38
39
39
/**
···
45
45
--vp-c-default-3: var(--vp-c-gray-3);
46
46
--vp-c-default-soft: var(--vp-c-gray-soft);
47
47
48
-
/* Use Emerald Green as primary brand color */
49
48
--vp-c-brand-1: var(--vp-c-sonics-green-1);
50
49
--vp-c-brand-2: var(--vp-c-sonics-green-2);
51
50
--vp-c-brand-3: var(--vp-c-sonics-green-3);
52
51
--vp-c-brand-soft: var(--vp-c-sonics-green-soft);
53
52
54
-
/* Tips use Bronze accent */
55
53
--vp-c-tip-1: var(--vp-c-sonics-bronze-1);
56
54
--vp-c-tip-2: var(--vp-c-sonics-bronze-2);
57
55
--vp-c-tip-3: var(--vp-c-sonics-bronze-3);
58
56
--vp-c-tip-soft: var(--vp-c-sonics-bronze-soft);
59
57
60
-
/* Warnings use Yellow */
61
58
--vp-c-warning-1: var(--vp-c-sonics-yellow-1);
62
59
--vp-c-warning-2: var(--vp-c-sonics-yellow-2);
63
60
--vp-c-warning-3: var(--vp-c-sonics-yellow-3);
64
61
--vp-c-warning-soft: var(--vp-c-sonics-yellow-soft);
65
62
66
-
/* Danger uses Red */
67
63
--vp-c-danger-1: var(--vp-c-sonics-red-1);
68
64
--vp-c-danger-2: var(--vp-c-sonics-red-2);
69
65
--vp-c-danger-3: var(--vp-c-sonics-red-3);
···
71
67
}
72
68
73
69
.dark {
74
-
/* Enhance dark mode background */
75
-
--vp-c-bg: #0d1117;
76
-
--vp-c-bg-soft: #161b22;
77
-
--vp-c-bg-mute: #1c2128;
70
+
--vp-c-bg: #1a1a1a;
71
+
--vp-c-bg-soft: #242424;
72
+
--vp-c-bg-mute: #2e2e2e;
73
+
--vp-c-bg-alt: #202020;
78
74
}
79
75
80
76
/**
···
92
88
--vp-button-brand-active-bg: var(--vp-c-brand-1);
93
89
}
94
90
95
-
/**
96
-
* Home
97
-
**/
91
+
98
92
:root {
99
93
--vp-home-hero-name-color: transparent;
100
94
--vp-home-hero-name-background: -webkit-linear-gradient(
···
123
117
}
124
118
}
125
119
126
-
/**
127
-
* Custom Block
128
-
**/
120
+
129
121
:root {
130
122
--vp-custom-block-tip-border: transparent;
131
123
--vp-custom-block-tip-text: var(--vp-c-text-1);
+62
docs/.vitepress/utils.ts
+62
docs/.vitepress/utils.ts
···
1
+
import fs from "node:fs";
2
+
import path from "node:path";
3
+
import { fileURLToPath } from "node:url";
4
+
import { DefaultTheme } from "vitepress";
5
+
6
+
type SidebarItem = DefaultTheme.SidebarItem;
7
+
8
+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
9
+
10
+
export const u = {
11
+
scanDir(dir: string, baseUrl = ""): SidebarItem[] {
12
+
const items: SidebarItem[] = [];
13
+
14
+
try {
15
+
const resolvedDir = path.resolve(__dirname, "..", dir);
16
+
const files = fs.readdirSync(resolvedDir);
17
+
18
+
for (const file of files) {
19
+
const fullPath = path.join(resolvedDir, file);
20
+
const stat = fs.statSync(fullPath);
21
+
22
+
if (stat.isDirectory()) {
23
+
continue;
24
+
}
25
+
26
+
if (!file.endsWith(".md")) {
27
+
continue;
28
+
}
29
+
30
+
if (file === "index.md") {
31
+
continue;
32
+
}
33
+
34
+
const content = fs.readFileSync(fullPath, "utf-8");
35
+
const title = this.extractTitle(content, file);
36
+
const link = `${baseUrl}/${path.parse(file).name}`;
37
+
38
+
items.push({ text: title, link });
39
+
}
40
+
} catch (error) {
41
+
console.error(`Error scanning directory ${dir}:`, error);
42
+
}
43
+
44
+
return items.toSorted((a, b) => a.text && b.text ? a.text.localeCompare(b.text) : 0);
45
+
},
46
+
extractTitle(content: string, filename: string): string {
47
+
const frontmatter = content.match(/^---\s*\n([\s\S]*?)\n---/);
48
+
if (frontmatter) {
49
+
const title = frontmatter[1].match(/title:\s*(.+)/);
50
+
if (title) {
51
+
return title[1].replace(/['"]/g, "").trim();
52
+
}
53
+
}
54
+
55
+
const heading = content.match(/^#\s+(.+)/m);
56
+
if (heading) {
57
+
return heading[1].trim();
58
+
}
59
+
60
+
return path.parse(filename).name.split("-").map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
61
+
},
62
+
};
-49
docs/api-examples.md
-49
docs/api-examples.md
···
1
-
---
2
-
outline: deep
3
-
---
4
-
5
-
# Runtime API Examples
6
-
7
-
This page demonstrates usage of some of the runtime APIs provided by VitePress.
8
-
9
-
The main `useData()` API can be used to access site, theme, and page data for the current page. It works in both `.md` and `.vue` files:
10
-
11
-
```md
12
-
<script setup>
13
-
import { useData } from 'vitepress'
14
-
15
-
const { theme, page, frontmatter } = useData()
16
-
</script>
17
-
18
-
## Results
19
-
20
-
### Theme Data
21
-
<pre>{{ theme }}</pre>
22
-
23
-
### Page Data
24
-
<pre>{{ page }}</pre>
25
-
26
-
### Page Frontmatter
27
-
<pre>{{ frontmatter }}</pre>
28
-
```
29
-
30
-
<script setup>
31
-
import { useData } from 'vitepress'
32
-
33
-
const { site, theme, page, frontmatter } = useData()
34
-
</script>
35
-
36
-
## Results
37
-
38
-
### Theme Data
39
-
<pre>{{ theme }}</pre>
40
-
41
-
### Page Data
42
-
<pre>{{ page }}</pre>
43
-
44
-
### Page Frontmatter
45
-
<pre>{{ frontmatter }}</pre>
46
-
47
-
## More
48
-
49
-
Check out the documentation for the [full list of runtime APIs](https://vitepress.dev/reference/runtime-api#usedata).
+16
-13
docs/css/volt-css.md
+16
-13
docs/css/volt-css.md
···
9
9
### Core Principles
10
10
11
11
- **Classless**: Style semantic HTML elements directly.
12
-
- Optimized line lengths, modular type scale, and generous whitespace optimized for reading
13
-
- Automatic light and dark modes via `prefers-color-scheme` to respect user preferences with carefully calibrated color palettes for both modes.
14
-
- **Accessibility**: WCAG AA contrast ratios, keyboard navigation support, and semantic HTML patterns
15
-
- Mobile-first (ish) design that adapts gracefully from phones to wide desktop monitors without compromising readability.
12
+
- **Accessible**: WCAG AA contrast ratios, keyboard navigation support, and semantic HTML patterns
13
+
14
+
- Optimized line lengths, modular type scale, and whitespace optimized for reading
15
+
- Automatic light and dark modes via `prefers-color-scheme`
16
+
- Mobile-first (ish) design that doesn't compromise readability
16
17
17
18
## Inspiration
18
19
···
38
39
39
40
### Tufte-Style Sidenotes
40
41
41
-
Inspired by Edward Tufte's beautiful book design, margin notes can be added using simple `<small>` elements within paragraphs.
42
+
Inspired by Edward Tufte's design principles, margin notes can be added using simple `<small>` elements within paragraphs.
42
43
43
44
**Desktop**: Notes appear in the right margin
44
45
**Mobile**: Notes appear inline with subtle styling
···
79
80
}
80
81
```
81
82
82
-
Both themes use carefully selected colors with proper contrast ratios for accessibility.
83
-
84
83
## Usage
85
84
86
85
### Basic Setup
···
124
123
<cite>Author Name</cite>
125
124
</blockquote>
126
125
127
-
<pre><code>// Code blocks use monospace fonts
128
-
const example = "syntax highlighting not included";</code></pre>
126
+
<pre>
127
+
<code>
128
+
// Code blocks use monospace fonts
129
+
const example = "syntax highlighting not included";
130
+
</code>
131
+
</pre>
129
132
130
133
<table>
131
134
<thead>
···
151
154
152
155
### Forms
153
156
154
-
Forms get styling with focus states, required field indicators, and proper spacing:
157
+
Forms get styling with focus states, required field indicators, and spacing between controls:
155
158
156
159
```html
157
160
<form>
···
285
288
286
289
- All color combinations meet WCAG AA standards (4.5:1 for normal text, 3:1 for large text)
287
290
- Clear, visible focus states for keyboard navigation
288
-
- Encourages proper heading hierarchy, landmark regions, and form labels
291
+
- Encourages logical heading hierarchy, landmark regions, and form labels
289
292
- Works on all devices and respects user font size preferences
290
293
- No animations that could trigger vestibular disorders
291
294
···
295
298
296
299
For maximum performance:
297
300
298
-
1. Serve with proper compression (gzip or brotli)
299
-
2. Set appropriate cache headers
301
+
1. Serve with compression (gzip or brotli)
302
+
2. Set cache headers
300
303
3. Consider inlining in `<style>` tags for above-the-fold content on single-page sites
301
304
302
305
## Design Decisions
+4
-4
docs/index.md
+4
-4
docs/index.md
···
5
5
hero:
6
6
name: "Volt.js"
7
7
text: "A reactive, hypermedia framework."
8
-
tagline: My great project tagline
8
+
tagline: A reactive, hypermedia framework.
9
9
actions:
10
10
- theme: brand
11
-
text: Markdown Examples
12
-
link: /markdown-examples
11
+
text: Overview
12
+
link: /overview
13
13
- theme: alt
14
-
text: API Examples
14
+
text: API Reference
15
15
link: /api-examples
16
16
17
17
features:
-85
docs/markdown-examples.md
-85
docs/markdown-examples.md
···
1
-
# Markdown Extension Examples
2
-
3
-
This page demonstrates some of the built-in markdown extensions provided by VitePress.
4
-
5
-
## Syntax Highlighting
6
-
7
-
VitePress provides Syntax Highlighting powered by [Shiki](https://github.com/shikijs/shiki), with additional features like line-highlighting:
8
-
9
-
**Input**
10
-
11
-
````md
12
-
```js{4}
13
-
export default {
14
-
data () {
15
-
return {
16
-
msg: 'Highlighted!'
17
-
}
18
-
}
19
-
}
20
-
```
21
-
````
22
-
23
-
**Output**
24
-
25
-
```js{4}
26
-
export default {
27
-
data () {
28
-
return {
29
-
msg: 'Highlighted!'
30
-
}
31
-
}
32
-
}
33
-
```
34
-
35
-
## Custom Containers
36
-
37
-
**Input**
38
-
39
-
```md
40
-
::: info
41
-
This is an info box.
42
-
:::
43
-
44
-
::: tip
45
-
This is a tip.
46
-
:::
47
-
48
-
::: warning
49
-
This is a warning.
50
-
:::
51
-
52
-
::: danger
53
-
This is a dangerous warning.
54
-
:::
55
-
56
-
::: details
57
-
This is a details block.
58
-
:::
59
-
```
60
-
61
-
**Output**
62
-
63
-
::: info
64
-
This is an info box.
65
-
:::
66
-
67
-
::: tip
68
-
This is a tip.
69
-
:::
70
-
71
-
::: warning
72
-
This is a warning.
73
-
:::
74
-
75
-
::: danger
76
-
This is a dangerous warning.
77
-
:::
78
-
79
-
::: details
80
-
This is a details block.
81
-
:::
82
-
83
-
## More
84
-
85
-
Check out the documentation for the [full list of markdown extensions](https://vitepress.dev/guide/markdown).
docs/plugin-spec.md
docs/spec/plugin-spec.md
docs/plugin-spec.md
docs/spec/plugin-spec.md
docs/reactivity-spec.md
docs/spec/reactivity-spec.md
docs/reactivity-spec.md
docs/spec/reactivity-spec.md
examples/.gitkeep
examples/.gitkeep
This is a binary file and will not be displayed.
-3
examples/counter/README.md
-3
examples/counter/README.md