@fiddle-digital/string-tune 1.1.27 → 1.1.29

package/dist/index.d.mts

@@ -129,6 +129,11 @@ declare class ScrollState {
     speedAccelerate: number;
 }
 
+declare class SystemState {
+    fpsTracker: boolean;
+    positionTracker: boolean;
+}
+
 /**
  * Represents the time-related state of the current and previous animation frames.
  *
@@ -207,12 +212,13 @@ declare class StringData {
      */
     render: RenderState;
     /**
-    * Time-related state object.
-    * Tracks frame timings, including current timestamp, delta between frames,
-    * and total elapsed time since animation start.
-    * Useful for time-based animations, easing, frame consistency, and syncing logic.
-    */
+     * Time-related state object.
+     * Tracks frame timings, including current timestamp, delta between frames,
+     * and total elapsed time since animation start.
+     * Useful for time-based animations, easing, frame consistency, and syncing logic.
+     */
     time: TimeState;
+    system: SystemState;
 }
 
 /**
@@ -390,6 +396,30 @@ declare class EventManager {
     clearAll(): void;
 }
 
+type MirrorEasingFn = (value: number) => number;
+/**
+ * Lightweight wrapper that mirrors a primary StringObject while keeping
+ * its own easing and state. Intended for elements linked via
+ * `[string-copy-from]`.
+ */
+declare class StringMirrorObject {
+    private parent;
+    readonly id: string;
+    readonly htmlElement: HTMLElement;
+    private properties;
+    private easingFn?;
+    constructor(id: string, element: HTMLElement, parent: StringObject);
+    get parentObject(): StringObject;
+    setProperty<T>(key: string, value: T): void;
+    getProperty<T>(key: string): T;
+    setEasing(easing: MirrorEasingFn | null | undefined): void;
+    getEasing(): MirrorEasingFn | undefined;
+    /**
+     * Returns eased progress using mirror easing (if set) or fallback.
+     */
+    applyProgress(rawProgress: number, fallback?: MirrorEasingFn): number;
+}
+
 /**
  * Internal class representing a DOM-bound interactive object.
  * Connected to modules and holds its own internal state.
@@ -408,9 +438,9 @@ declare class StringObject {
      */
     keys: string[];
     /**
-     * A list of elements that should be affected in sync with this one.
+     * Mirror objects linked via `string-copy-from`.
      */
-    connects: HTMLElement[];
+    private mirrors;
     /**
      * Internal key-value store of dynamic object properties (like offsets, progress, etc.).
      */
@@ -466,6 +496,10 @@ declare class StringObject {
      * @param module - The module to connect
      */
     connect(module: IStringModule): void;
+    addMirror(mirror: StringMirrorObject): void;
+    removeMirror(id: string): void;
+    get mirrorObjects(): StringMirrorObject[];
+    get connects(): HTMLElement[];
 }
 
 declare class CenterCache {
@@ -1298,7 +1332,7 @@ declare class StringModule implements IStringModule {
      * @param object The object whose elements to update.
      * @param applyFn The function that receives an HTMLElement and performs any update.
      */
-    protected applyToElementAndConnects(object: StringObject, applyFn: (el: HTMLElement) => void): void;
+    protected applyToElementAndConnects(object: StringObject, applyFn: (el: HTMLElement) => void, copyFn?: (el: HTMLElement, mirror?: StringMirrorObject) => void): void;
     /**
      * Cleans up internal state and detaches the module from the system.
      */
@@ -1307,6 +1341,9 @@ declare class StringModule implements IStringModule {
     onInit(): void;
     /** Called on each frame with current scroll and state data. */
     onFrame(data: StringData): void;
+    onMutate(data: StringData): void;
+    onScrollMeasure(data: StringData): void;
+    onMouseMoveMeasure(data: StringData): void;
     /** Called when the window or layout is resized. */
     onResize(): void;
     /** Called when the layout is resized width. */
@@ -1341,25 +1378,53 @@ declare class StringModule implements IStringModule {
     onDOMMutate(added: NodeList, removed: NodeList): void;
 }
 
+/**
+ * StringCursor Module
+ *
+ * Handles cursor tracking and hover states for StringTune objects.
+ *
+ * Safari Navigation Fix:
+ * Safari has an issue where mouseleave events are not fired when navigation occurs
+ * (especially with NuxtLink/router navigation). This module includes several
+ * workarounds to ensure proper cleanup:
+ *
+ * 1. MutationObserver - detects when elements are removed from DOM
+ * 2. beforeunload/pagehide - captures traditional navigation
+ * 3. visibilitychange - captures modern SPA navigation
+ * 4. DOM existence checks - prevents operations on removed elements
+ */
 declare class StringCursor extends StringModule {
     protected enterObjectsMap: Map<string, StringObject>;
     protected enterObjects: Array<StringObject>;
     cursor: any;
     cursorContent: any;
     overCount: number;
+    private cursorPrev;
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
-    onFrame(data: StringData): void;
+    onMutate(data: StringData): void;
     onObjectConnected(object: StringObject): void;
     getCursorClass(object: StringObject): string | null;
     onMouseEnter(object: StringObject): void;
     onMouseLeave(object: StringObject): void;
     private onEnterObject;
     private onLeaveObject;
+    private safariNavigationCleanup;
+    private onElementRemovedFromDOM;
+    onObjectDisconnected(object: StringObject): void;
     private setMouseCoordinates;
     private calculateOffset;
 }
 
+declare class StringImpulse extends StringModule {
+    constructor(context: StringContext);
+    onObjectConnected(object: StringObject): void;
+    onObjectDisconnected(object: StringObject): void;
+    onMouseMove(_e?: MouseEvent): void;
+    private getElementsAtPoint;
+    onFrame(_: StringData): void;
+}
+
 declare class StringMagnetic extends StringModule {
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
@@ -1367,19 +1432,57 @@ declare class StringMagnetic extends StringModule {
     onFrame(data: StringData): void;
 }
 
+declare abstract class CursorReactiveModule extends StringModule {
+    protected nearOnly: boolean;
+    protected useAllObjects: boolean;
+    protected maxDistanceMultiplier: number;
+    protected updateThreshold: number;
+    private objectDeltaData;
+    constructor(context: StringContext);
+    onObjectConnected(object: StringObject): void;
+    removeObject(id: string): void;
+    onScroll(): void;
+    onMouseMoveMeasure(data: StringData): void;
+    onMutate(data: StringData): void;
+    protected getCursorTargets(): StringObject[];
+    protected refreshPointerState(target?: StringObject): void;
+    private scrollUpdateScheduled;
+    protected scheduleCursorUpdate(): void;
+    protected onCursorScrollUpdate(): void;
+}
+
+declare class StringSpotlight extends CursorReactiveModule {
+    protected onCursorFrame(data: StringData, frame: number): void;
+    private updateScheduledSpotlight;
+    constructor(context: any);
+    initializeObject(id: number, obj: StringObject, el: HTMLElement, attrs: Record<string, any>): void;
+    protected onPointerDelta(obj: StringObject, dx: number, dy: number, dist: number): void;
+    onMouseMoveMeasure(data: StringData): void;
+    onMutate(data: StringData): void;
+    private ensurePointerState;
+    private updateSpotlightState;
+    protected onCursorScrollUpdate(): void;
+}
+
 /**
  * Module that handles lazy-loading of images with `string-lazy` attribute.
- * It loads the image only once, calculates its aspect-ratio to prevent layout shift,
- * and then displays it.
+ * Aspect ratios are precomputed before the real source is revealed in view.
  */
 declare class StringLazy extends StringModule {
     private isStartLoaded;
     private loadingCount;
+    private imageStates;
     constructor(context: StringContext);
     onInit(): void;
     onObjectConnected(object: StringObject): void;
-    private loadImage;
-    private handleLoadingCompletion;
+    onObjectDisconnected(object: StringObject): void;
+    private ensureState;
+    private readSource;
+    private prepareAspectRatio;
+    private loadIntrinsicSize;
+    private handleInView;
+    private maybeActivateImage;
+    private activateImage;
 }
 
 /**
@@ -1469,23 +1572,21 @@ declare class StringLerp extends StringModule {
     private setLerpValue;
 }
 
-/**
- * The `StringProgress` class extends the `StringModule` class and is responsible for
- * managing progress-based behavior for elements during scroll events. It maps specific
- * attributes, initializes objects, and updates their progress based on scroll data.
- */
 declare class StringProgress extends StringModule {
+    protected updateScheduled: boolean;
+    private static readonly PROGRESS_EPSILON;
     constructor(context: StringContext);
-    /**
-     * Called when an object is initialized.
-     */
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
-    /**
-     * Called on scroll.
-     */
+    private recomputeProgress;
+    private applyProgressValue;
+    calculatePositions(object: StringObject, windowSize: number): void;
     onScroll(data: StringData): void;
     onObjectConnected(object: StringObject): void;
-    private setUpObject;
+    onScrollMeasure(data: StringData): void;
+    onMutate(): void;
+    private updateObjectProgress;
+    private hasProgressChanged;
+    onObjectDisconnected(object: StringObject): void;
 }
 
 /**
@@ -1495,22 +1596,20 @@ declare class StringProgress extends StringModule {
  * necessary transformations based on scroll progress and viewport size.
  */
 declare class StringParallax extends StringProgress {
+    private updateScheduledTransform;
+    private calculateParallaxForObject;
     constructor(context: StringContext);
     /**
      * Called when an object is initialized.
      */
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
-    /**
-     * Called on scroll.
-     */
+    calculatePositions(object: StringObject, windowSize: number): void;
     onScroll(data: StringData): void;
-    /**
-     * Called on resize.
-     */
     onResize(): void;
-    private handleScrollDesktop;
-    private handleScrollMobile;
-    private scrollHandler;
+    onScrollMeasure(data: StringData): void;
+    onMutate(): void;
+    private calculateDesktopParallax;
+    private calculateMobileParallax;
 }
 
 declare class StringScrollbar extends StringModule {
@@ -1551,6 +1650,7 @@ declare class StringSplit extends StringModule {
     split(element: HTMLElement, options: ISplitOptions): {
         fragment: DocumentFragment;
         result: DocumentFragment;
+        extraProps: Map<string, string>;
     };
     /**
      * Computes a numeric value based on the provided split option, index, and total count.
@@ -1825,41 +1925,45 @@ declare class StringForm extends StringModule {
     getFieldValue(field: HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement): any;
 }
 
-declare abstract class CursorReactiveModule extends StringModule {
-    protected nearOnly: boolean;
-    protected emitEveryN: number;
-    protected updateThreshold: number;
-    private rafFrame;
-    constructor(context: StringContext);
-    onObjectConnected(object: StringObject): void;
-    removeObject(id: string): void;
-    onScroll(): void;
-    onMouseMove(e: MouseEvent): void;
-    onFrame(data: StringData): void;
-    protected abstract onPointerDelta(obj: StringObject, dx: number, dy: number, dist: number): void;
-    protected abstract onCursorFrame(data: StringData, frame: number): void;
-}
-
 declare class StringScroller extends StringModule {
     constructor(context: StringContext);
     onObjectConnected(object: StringObject): void;
     onObjectDisconnected(object: StringObject): void;
 }
 
-declare class StringImpulse extends StringModule {
-    constructor(context: StringContext);
-    onObjectConnected(object: StringObject): void;
-    onObjectDisconnected(object: StringObject): void;
-    onMouseMove(_e?: MouseEvent): void;
-    onFrame(_: StringData): void;
-}
-
 declare class StringProgressPart extends StringModule {
     constructor(context: StringContext);
     onObjectConnected(object: StringObject): void;
     onObjectDisconnected(object: StringObject): void;
 }
 
+type Job = () => void;
+declare class FrameDOM {
+    private measureQueue;
+    private mutateQueue;
+    private scheduled;
+    measure(fn: Job): void;
+    mutate(fn: Job): void;
+    private schedule;
+}
+declare const frameDOM: FrameDOM;
+
+type StyleValue = string | number;
+type StyleVars = Record<string, StyleValue>;
+type StyleProps = Record<string, StyleValue>;
+declare class StyleTxn {
+    private pendingVars;
+    private pendingProps;
+    private isOpen;
+    begin(): void;
+    setVars(el: Element, vars: StyleVars): void;
+    setProps(el: Element, props: StyleProps): void;
+    run(fn: () => void): void;
+    commit(): void;
+    cancel(): void;
+}
+declare const styleTxn: StyleTxn;
+
 declare class StringTune {
     /** Bound handler for the scroll start event */
     private onScrollStartBind;
@@ -1876,6 +1980,7 @@ declare class StringTune {
     /** Bound mouse move handler */
     private onMouseMoveBind;
     private onContainerTransitionEndBind;
+    private onResizeObserverBind;
     /** Singleton instance of StringTune */
     private static i;
     /** Root scrollable element (typically <body>) */
@@ -1908,6 +2013,8 @@ declare class StringTune {
     private centers;
     /** Tracks hover states of string objects. */
     private hoverManager;
+    private observerContainerResize;
+    canRebuild: boolean;
     /**
      * Sets the scroll position manually.
      * This overrides all internal scroll states including target and lerped values.
@@ -1930,7 +2037,9 @@ declare class StringTune {
      * Gets the current scroll position in pixels.
      * This is typically updated every frame.
      */
-    get speed(): number;
+    get scrollPosition(): number;
+    get scrollHeight(): number;
+    get containerHeight(): number;
     /**
      * Sets the base scroll speed for smooth scrolling.
      * Typically a value between 0 and 1.
@@ -2037,6 +2146,7 @@ declare class StringTune {
      * @param settings A key-value map of default settings (e.g. 'offset-top': '-10%').
      */
     setupSettings(settings: StringSettings): void;
+    private onResizeObserverEvent;
     private onContainerTransitionEnd;
     /**
      * Handles mouse move event and dispatches it to cursor and modules.
@@ -2096,6 +2206,12 @@ declare class StringTune {
      * @param offset - Optional. The number of pixels to offset from the target element's top position. Defaults to 0.
      */
     scrollToElement(selector: string, offset?: number): void;
+    scrollTo(position: number): void;
+    /**
+     * Forces center cache recalculation for all tracked objects.
+     * Useful when DOM geometry changes outside of StringTune's control.
+     */
+    invalidateCenters(): void;
     /**
      * Cleans up the system, removes all event listeners, stops the loop,
      * and destroys modules and event subscriptions.
@@ -2103,4 +2219,4 @@ declare class StringTune {
     destroy(): void;
 }
 
-export { CursorReactiveModule, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringResponsive, StringScrollbar, StringScroller, StringSequence, StringSplit, StringTune, StringVideoAutoplay, StringTune as default };
+export { CursorReactiveModule, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringResponsive, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, StringTune as default, frameDOM, styleTxn };