a reactive (signals based) hypermedia web framework (wip)
stormlightlabs.github.io/volt/
desertthunder.dev
hypermedia
frontend
signals
1---
2outline: deep
3---
4
5# Surge Plugin
6
7The surge plugin powers enter/leave transitions for conditional DOM. It combines CSS property interpolation, optional
8View Transitions, and a signal-aware state machine to animate elements appearing or disappearing.
9
10## Quick Start
11
12```html
13<section data-volt-surge="isOpen:fade">
14 <p>Panel content...</p>
15</section>
16```
17
18- `isOpen` resolves to a signal. Falsy values hide the element (`display: none`).
19- The `fade` preset runs when the signal flips to truthy and again in reverse when it returns to falsy.
20
21## Presets and Overrides
22
23`data-volt-surge="presetName"` attaches a preset from the transition registry without watching a signal. Combine with
24granular variants when you need independent enter/leave control:
25
26```html
27<article
28 data-volt-surge="show:slide-down.400"
29 data-volt-surge:enter="fade.200"
30 data-volt-surge:leave="scale-down.250">
31 ...
32</article>
33```
34
35- `data-volt-surge:enter` and `:leave` use the same parsing logic as the core transition helpers (`duration.delay`
36 suffixes honored via `parseTransitionValue` and `applyOverrides`).
37- When both shorthand and phase-specific attributes exist, the phase-specific value wins.
38
39## Signal Lifecycle
40
41When bound to a signal the plugin:
42
431. Checks the initial signal value. Falsy values hide the element immediately.
442. Subscribes to the signal and debounces concurrent transitions so rapid toggles stay smooth.
453. Uses `execEnter`/`execLeave` helpers to apply styles, classes, delays, and easing.
464. Cleans up the subscription when the element unmounts.
47
48The underlying transition promise resolves before the element is marked visible or hidden, ensuring sequential updates
49remain ordered.
50
51## View Transitions Integration
52
53Surge participates in the View Transition API whenever the preset’s config opts in (default). Calling variants like
54`slide-down.400` runs inside `withViewTransition`, making swapping sections feel native. Add `:notransition` to your
55navigate bindings if you need to avoid double animations when combining plugins.
56
57## Manual Execution
58
59Volt’s runtime calls the internal helpers automatically for keyed iterations and DOM diffs. If you render content
60manually, you can trigger the same behavior:
61
62```ts
63import { executeSurgeEnter, executeSurgeLeave, hasSurge } from "volt/plugins/surge";
64
65if (hasSurge(el)) {
66 await executeSurgeEnter(el);
67}
68```
69
70`hasSurge` checks whether the element owns any surge metadata (signal config or phase overrides) before attempting an
71explicit enter/leave.
72
73## Reduced Motion
74
75When the user prefers reduced motion the plugin skips transitions, applies the `to` styles or classes immediately, and
76avoids firing View Transition effects. This keeps the animation accessible without extra work on your part.