StringProgress Module

Convert scroll position into predictable 0–1 progress curves. StringProgress watches an element’s travel through the viewport, writes the result to a CSS variable, and emits events you can hook into for bespoke animations.

Activation primer: Add string="progress" to every element you want StringProgress to track. Supply string-id="your-id" when you need a stable handle for events, mirrors, or string-copy-from; otherwise StringTune generates one automatically.

HTML Attributes

Attribute	Type	Default	Controls	Practical notes
`string-key`	string	`--progress`	CSS variable that will receive the progress value	Choose unique keys per element to avoid clashes; mirrors inherit the same key
`string-offset-top`	dimension	`0%`	Additional distance before progress starts	Accepts mixed units (`px`, `%`, `vh`, `rem`, combined expressions)
`string-offset-bottom`	dimension	`0%`	Extra travel after the element passes the viewport before progress reaches `1`	Use for delayed completions or sticking animations
`string-enter-el`	enum (`top`/`bottom`/`left`/`right`)	`top`	Which edge of the element is used as the entry reference	Pair with `string-enter-vp` to define trigger geometry
`string-enter-vp`	enum (`top`/`bottom`/`left`/`right`)	`bottom`	Viewport edge that must meet `enter-el` to begin progress	Swap to `top` for progress that begins earlier
`string-exit-el`	enum (`top`/`bottom`/`left`/`right`)	`bottom`	Element edge that signals completion	For horizontal timelines use `left`/`right` combinations
`string-exit-vp`	enum (`top`/`bottom`/`left`/`right`)	`top`	Viewport edge used for completion	Set both exit values to `bottom` for parallax-style overlaps
`string-easing`	easing string	`cubic-bezier(0.25, 0.25, 0.25, 0.25)`	Remaps raw linear progress before emission/CSS write	Supports cubic-bezier syntax and standard keywords
`string-copy-from`	string	—	Mirror another progress element by `string-id`	Perfect for syncing multiple layers without recomputation

Need a refresher on offset math? Visit Offset Concepts for supported units, chaining syntax, and practical diagrams.

Module Snapshot

Activation attribute: string="progress"
CSS variable populated: the value from string-key (defaults to --progress)
Progress range: clamped 0→1, eased if string-easing is supplied
Event channel: object:progress:<id> (emits eased progress)
Works best with: scroll-driven timelines, sticky sections, theme transitions, SVG morphs

Basic Usage

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

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

Annotate targets and consume the CSS variable:

<section string="progress" string-id="hero-progress" string-key="--hero-progress" class="hero">...</section>

.hero {
  --parallax: calc(var(--hero-progress) * 40vh);
  transform: translateY(var(--parallax));
}

How It Works

Geometry setup: base module logic calculates start-position, end-position, and difference-position using offsets and enter/exit pairs.
Raw progress: (scroll.transformedCurrent - start) / difference clamped to 0–1 yields progress-raw.
Easing pass: optional easing remaps the raw value before CSS or events.
CSS output: styleTxn writes the stringified progress to the variable specified by string-key for the element and all mirrors.
Mirror support: elements registered via string-copy-from reuse the origin’s progress without extra scroll calculations.
Change threshold: micro fluctuations under 1e-4 are ignored to keep the event bus quiet.

Event Signal

Channel pattern	Payload	Fired when	Use cases
`object:progress:<id>`	`number` (eased progress)	Value changes beyond epsilon (`1e-4`)	Blend WebGL timelines, drive audio fades, feed analytics checkpoints

Subscribe via the shared event bus:

stringTune.on('object:progress:hero-progress', (progress) => {
  // 0 → 1 eased value; drive counter animations or GLSL uniforms
});

StringProgress keeps scroll-driven storytelling deterministic—dial in the geometry once, deliver the value everywhere, and choreograph motion with confidence.