Something went wrong. Try again.
a reactive (signals based) hypermedia web framework (wip) stormlightlabs.github.io/volt
hypermedia frontend signals
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200/** * Scroll plugin for managing scroll behavior * Supports position restoration, scroll-to, scroll spy, and smooth scrolling */
import type { PluginContext, Signal } from "$types/volt";
/** * Scroll plugin handler to manage various scroll-related behaviors. * * Syntax: data-volt-scroll="mode:signalPath" or data-volt-scroll="mode" * Modes: * - restore:signalPath - Save/restore scroll position * - scrollTo:signalPath - Scroll to element when signal changes * - spy:signalPath - Update signal when element is visible * - smooth:signalPath - Enable smooth scrolling behavior * - history - Integrate with navigation history (auto save/restore on navigation) */export function scrollPlugin(ctx: PluginContext, value: string): void { if (value === "history") { handleScrollHistory(ctx); return; }
const parts = value.split(":"); if (parts.length !== 2) { console.error(`Invalid scroll binding: "${value}". Expected format: "mode:signalPath" or "history"`); return; }
const [mode, signalPath] = parts.map((p) => p.trim());
switch (mode) { case "restore": { handleScrollRestore(ctx, signalPath); break; } case "scrollTo": { handleScrollTo(ctx, signalPath); break; } case "spy": { handleScrollSpy(ctx, signalPath); break; } case "smooth": { handleSmoothScroll(ctx, signalPath); break; } default: { console.error(`Unknown scroll mode: "${mode}"`); } }}
/** * Saves current scroll position to signal on scroll events; Restores scroll position from signal on mount. */function handleScrollRestore(ctx: PluginContext, signalPath: string): void { const signal = ctx.findSignal(signalPath); if (!signal) { console.error(`Signal "${signalPath}" not found for scroll restore`); return; }
const element = ctx.element as HTMLElement; const savedPosition = signal.get(); if (typeof savedPosition === "number") { element.scrollTop = savedPosition; }
const savePosition = () => { (signal as Signal<number>).set(element.scrollTop); };
element.addEventListener("scroll", savePosition, { passive: true });
ctx.addCleanup(() => { element.removeEventListener("scroll", savePosition); });}
/** * Scroll to element when signal value matches element's ID or selector. * Listens for changes to the target signal to determine position */function handleScrollTo(ctx: PluginContext, signalPath: string): void { const signal = ctx.findSignal(signalPath); if (!signal) { console.error(`Signal "${signalPath}" not found for scrollTo`); return; }
const element = ctx.element as HTMLElement; const elementId = element.id;
const checkAndScroll = (target: unknown) => { if (target === elementId || target === `#${elementId}`) { element.scrollIntoView({ behavior: "smooth", block: "start" }); } };
checkAndScroll(signal.get());
const unsubscribe = signal.subscribe(checkAndScroll); ctx.addCleanup(unsubscribe);}
/** * Update signal when element enters or exits viewport. * Uses {@link IntersectionObserver} to track visibility. */function handleScrollSpy(ctx: PluginContext, signalPath: string): void { const signal = ctx.findSignal(signalPath); if (!signal) { console.error(`Signal "${signalPath}" not found for scroll spy`); return; }
const element = ctx.element as HTMLElement;
const observer = new IntersectionObserver((entries) => { for (const entry of entries) { if (entry.target === element) { (signal as Signal<boolean>).set(entry.isIntersecting); } } }, { threshold: 0.1 });
observer.observe(element);
ctx.addCleanup(() => { observer.disconnect(); });}
/** * Enable smooth scrolling behavior and apply based on signal value. */function handleSmoothScroll(ctx: PluginContext, signalPath: string): void { const signal = ctx.findSignal(signalPath); if (!signal) { console.error(`Signal "${signalPath}" not found for smooth scroll`); return; }
const element = ctx.element as HTMLElement;
const applyBehavior = (value: unknown) => { if (value === true || value === "smooth") { element.style.scrollBehavior = "smooth"; } else if (value === false || value === "auto") { element.style.scrollBehavior = "auto"; } };
applyBehavior(signal.get());
const unsubscribe = signal.subscribe(applyBehavior);
ctx.addCleanup(() => { unsubscribe(); element.style.scrollBehavior = ""; });}
/** * Integrate scroll position with browser history * Automatically saves and restores scroll position on navigation * Works with volt:navigate and volt:popstate events */function handleScrollHistory(ctx: PluginContext): void { const element = ctx.element as HTMLElement; const scrollPositions = new Map<string, number>();
const handleNavigate = () => { const key = `${globalThis.location.pathname}${globalThis.location.search}`; scrollPositions.set(key, element.scrollTop); };
const handlePopstate = () => { const key = `${globalThis.location.pathname}${globalThis.location.search}`; const savedPosition = scrollPositions.get(key);
if (savedPosition !== undefined) { requestAnimationFrame(() => { element.scrollTop = savedPosition; }); } };
globalThis.addEventListener("volt:navigate", handleNavigate); globalThis.addEventListener("volt:popstate", handlePopstate);
ctx.addCleanup(() => { globalThis.removeEventListener("volt:navigate", handleNavigate); globalThis.removeEventListener("volt:popstate", handlePopstate); });}