StringScroller Module

Delegate wheel interactions from a specific container back to the StringTune scroll engine. StringScroller listens for wheel events on annotated elements and forwards them through the shared event bus, letting you build custom scroll surfaces that still drive the global timeline.

Module Snapshot

• Activation attribute: string="scroller"
• Event forwarding: listens to native wheel on the element and re-emits it as wheel on the StringTune event bus
• No CSS outputs: the module does not mutate styles or set variables
• Lifecycle: one wheel handler per element; automatically removed on disconnect to avoid leaks
• Pairing: complements engines like StringScrollSmooth that subscribe to the global wheel event

Basic Usage

import StringTune, { StringScroller } from '@fiddle-digital/string-tune';

const stringTune = StringTune.getInstance();
stringTune.use(StringScroller);
stringTune.start(60);

<div class="modal-shell" string="scroller">
  <div class="modal-body">
    ...
    <div class="scrollable-panel">Your content here</div>
  </div>
</div>

.modal-shell {
  position: fixed;
  inset: 0;
  overflow-y: auto;
}

.scrollable-panel {
  min-height: 200vh;
}

How It Works

• Connection guard: the module tracks a scroller-inited flag on each object to ensure the wheel listener is attached only once.
• Wheel proxy: every native wheel event is emitted as this.events.emit('wheel', event). The core StringTune instance subscribes to this channel, so custom containers behave the same as the default scroll root.
• Cleanup: on disconnect the listener is removed and state cleared, preventing orphaned handlers when elements unmount.
• Multiple scrollers: you can register several containers; each contributes wheel input to the same global stream, so whichever one the user interacts with will steer the scroll controller.
• ScrollManager integration: forward events travel through the scroll manager (scrollManager.get().onWheel) and module manager, keeping scroll physics consistent across devices.

Event Signal

stringTune.on('wheel', (event: WheelEvent) => {
  if (event.metaKey) {
    // Custom zoom behaviour or prevent default
    event.preventDefault();
  }
});

StringScroller keeps alternative scroll surfaces in sync with StringTune’s timeline—tag the containers that should drive the engine, let the module proxy wheel signals, and keep your custom layouts responsive without rewriting core scroll logic.