VoltX Plugin System Spec

Overview

The plugin system enables extending the framework with custom data-volt-* attribute bindings.

Plugins follow the same binding patterns as core bindings (text, html, class, events) but can implement specialized behaviors like persistence, scrolling, and URL synchronization.

Design Goals

Extensibility

Plugins can access the full binding context including the DOM element, reactive scope, signal utilities, and cleanup registration.

Explicit Opt-In

Built-in plugins require explicit registration to keep the core bundle minimal. Applications only load the functionality they use.

Simplicity

Plugin API mirrors the internal binding handler signature. Developers who end up familiar with Volt internals can easily create plugins.

Consistency

Plugins should integrate seamlessly with the mount/unmount lifecycle, cleanup system, and reactive primitives.

Plugin API

Registration

Plugins are registered using the registerPlugin() function:

registerPlugin(name: string, handler: PluginHandler): void

The plugin name becomes the data-volt-* attribute suffix. For example, registering a plugin named "tooltip" enables data-volt-tooltip attributes.

Plugin Handler

Plugin handlers receive a context object and the attribute value:

type PluginHandler = (context: PluginContext, value: string) => void

The handler should:

1. Parse the attribute value
2. Set up bindings and subscriptions
3. Register cleanup functions for unmount

PluginContext

The context object provides:

interface PluginContext {
  element: Element;                              // The bound DOM element
  scope: Scope;                                  // Reactive scope with signals
  addCleanup(fn: CleanupFunction): void;        // Register cleanup
  findSignal(path: string): Signal | undefined; // Locate signals by path
  evaluate(expression: string): unknown;        // Evaluate expressions
}

Example: Custom Tooltip Plugin

import { registerPlugin } from 'voltx.js';

registerPlugin('tooltip', (context, value) => {
  const tooltip = document.createElement('div');
  tooltip.className = 'tooltip';
  tooltip.textContent = context.evaluate(value);

  const show = () => document.body.appendChild(tooltip);
  const hide = () => tooltip.remove();

  context.element.addEventListener('mouseenter', show);
  context.element.addEventListener('mouseleave', hide);

  context.addCleanup(() => {
    hide();
    context.element.removeEventListener('mouseenter', show);
    context.element.removeEventListener('mouseleave', hide);
  });

  const signal = context.findSignal(value);
  if (signal) {
    const unsubscribe = signal.subscribe((newValue) => {
      tooltip.textContent = String(newValue);
    });
    context.addCleanup(unsubscribe);
  }
});

Built-in Plugins

VoltX.js ships with three built-in plugins that must be explicitly registered.

data-volt-persist

Synchronizes signal values with persistent storage (localStorage, sessionStorage, IndexedDB).

Syntax:

<input data-volt-persist="signalName:storageType" />

Storage Types:

• local - localStorage (persistent across sessions)
• session - sessionStorage (cleared on tab close)
• indexeddb - IndexedDB (large datasets, async)
• Custom adapters via registerStorageAdapter()

Behavior:

1. On mount: Load persisted value into signal (if exists)
2. On signal change: Persist new value to storage
3. On unmount: Clean up storage listeners

Examples:

<!-- Persist counter to localStorage -->
<div data-volt-text="count" data-volt-persist="count:local"></div>

<!-- Persist form state to sessionStorage -->
<input data-volt-on-input="updateForm" data-volt-persist="formData:session" />

<!-- Persist large dataset to IndexedDB -->
<div data-volt-persist="userData:indexeddb"></div>

Custom Storage Adapters:

interface StorageAdapter {
  get(key: string): Promise<unknown> | unknown;
  set(key: string, value: unknown): Promise<void> | void;
  remove(key: string): Promise<void> | void;
}

registerStorageAdapter('custom', {
  async get(key) { /* ... */ },
  async set(key, value) { /* ... */ },
  async remove(key) { /* ... */ }
});

data-volt-scroll

Manages scroll behavior including position restoration, programmatic scrolling, scroll spy, and smooth scrolling.

Syntax:

<!-- Scroll position restoration -->
<div data-volt-scroll="restore:position"></div>

<!-- Scroll to element when signal changes -->
<div data-volt-scroll="scrollTo:targetId"></div>

<!-- Scroll spy (updates signal when in viewport) -->
<div data-volt-scroll="spy:isVisible"></div>

<!-- Smooth scroll behavior -->
<div data-volt-scroll="smooth:true"></div>

Behaviors:

Position Restoration:

<div id="content" data-volt-scroll="restore:scrollPos">
  <!-- scroll position saved on scroll, restored on mount -->
</div>

Saves scroll position to the specified signal and restores on mount.

Scroll-To:

<button data-volt-on-click="scrollToSection.set('section2')">Go to Section 2</button>
<div id="section2" data-volt-scroll="scrollTo:scrollToSection"></div>

Scrolls to element when the specified signal changes to match element's ID or selector.

Scroll Spy:

<nav>
  <a data-volt-class="{ active: section1Visible }">Section 1</a>
  <a data-volt-class="{ active: section2Visible }">Section 2</a>
</nav>
<div data-volt-scroll="spy:section1Visible"></div>
<div data-volt-scroll="spy:section2Visible"></div>

Updates signal with boolean visibility state using Intersection Observer.

Smooth Scrolling:

<div data-volt-scroll="smooth:behavior"></div>

Enables smooth scrolling with configurable behavior from signal.

data-volt-url

Synchronizes signal values with URL parameters and hash-based routing.

Syntax:

<!-- One-way: Read URL param into signal on mount -->
<input data-volt-url="read:searchQuery" />

<!-- Bidirectional: Keep URL and signal in sync -->
<input data-volt-url="sync:filter" />

<!-- Hash-based routing -->
<div data-volt-url="hash:currentRoute"></div>

Behaviors:

Read URL Parameters:

<!-- Initialize signal from ?tab=profile -->
<div data-volt-url="read:tab"></div>

Reads URL parameter on mount and sets signal value. Signal changes do not update URL.

Bidirectional Sync:

<!-- Keep ?search=query in sync with searchQuery signal -->
<input data-volt-on-input="handleSearch" data-volt-url="sync:searchQuery" />

You can also use the shorthand attribute form where the signal name is encoded in the attribute suffix:

<!-- Equivalent to data-volt-url="sync:searchQuery" -->
<input data-volt-url:searchQuery="query" />

Changes to signal update URL parameter, changes to URL update signal. Uses History API for clean URLs.

Hash Routing:

<!-- Sync with #/page/about -->
<div data-volt-url="hash:route"></div>
<div data-volt-text="route === '/page/about' ? 'About Page' : 'Home'"></div>

Keeps hash portion of URL in sync with signal. Useful for client-side routing.

Notes:

• Uses History API (pushState/replaceState) for param sync
• Listens to popstate for browser back/forward
• Debounces URL updates to avoid excessive history entries
• Automatically serializes/deserializes values (strings, numbers, booleans)
• Accepts data-volt-url="mode:signal" or data-volt-url:signal="mode" forms
• Supports query, hash, and history mode aliases in shorthand attributes (e.g., data-volt-url:filter="query")

Implementation

Integration

The binder system checks the plugin registry before falling through to unknown attribute warnings

Context

The binder creates a PluginContext from BindingContext:

function createPluginContext(bindingContext: BindingContext): PluginContext {
  return {
    element: bindingContext.element,
    scope: bindingContext.scope,
    addCleanup: (fn) => bindingContext.cleanups.push(fn),
    findSignal: (path) => findSignalInScope(bindingContext.scope, path),
    evaluate: (expr) => evaluate(expr, bindingContext.scope)
  };
}

Module Structure

src/
  core/
    plugin.ts       # Plugin registry and API
    binder.ts       # Modified to integrate plugins
  plugins/
    persist.ts      # Persistence plugin
    scroll.ts       # Scroll behavior plugin
    url.ts          # URL synchronization plugin
  index.ts          # Exports registerPlugin and built-in plugins

Bundle Size Considerations

With explicit registration, applications control their bundle size:

• Core framework: ~15 KB gzipped (no plugins)
• Each plugin: ~1-3 KB gzipped
• Applications import only what they use
• Tree-shaking eliminates unused plugins

Example bundle breakdown:

volt/core         : 15 KB
volt/plugins/persist  : 2 KB
volt/plugins/scroll   : 2.5 KB
volt/plugins/url      : 1.5 KB
--------------------------------
Total (all plugins)   : 21 KB

Extension Points

Future plugin capabilities:

• Lifecycle hooks (beforeMount, afterMount, beforeUnmount)
• Plugin dependencies and composition
• Plugin configuration API
• Async plugin initialization
• Plugin registry