@fiddle-digital/string-tune 1.1.48 → 1.1.49

package/dist/index.d.ts

@@ -71,7 +71,7 @@ declare class RenderState {
 }
 
 type ScrollDirection = 'vertical' | 'horizontal';
-type ScrollMode = 'smooth' | 'disable' | 'default';
+type ScrollMode = 'smooth' | 'disable' | 'default' | (string & {});
 /**
  * Describes current scroll-related state for all calculations and modules.
  */
@@ -132,6 +132,7 @@ declare class ScrollState {
 declare class SystemState {
     fpsTracker: boolean;
     positionTracker: boolean;
+    suppressMasonryResize: boolean;
 }
 
 /**
@@ -230,6 +231,10 @@ interface IStringModule {
     destroy(): void;
     /** Called once when the module is initialized. */
     onInit(): void;
+    /** Called once when the module is registered and can subscribe to events. */
+    onSubscribe(): void;
+    /** Called once when the module is being removed and should unsubscribe. */
+    onUnsubscribe(): void;
     /** Called on each frame with current scroll and state data. */
     onFrame(data: StringData): void;
     /** Called when the window or layout is resized. */
@@ -240,7 +245,7 @@ interface IStringModule {
     onDOMRebuild(): void;
     /** Called when scroll position changes. */
     onScroll(data: StringData): void;
-    /** Called when scroll change diraction. */
+    /** Called when scroll change direction. */
     onDirectionChange(): void;
     /** Called when scrolling starts (user begins scroll). */
     onScrollStart(): void;
@@ -529,6 +534,14 @@ declare class HoverTracker {
     activeObjects(): StringObject[];
 }
 
+interface ISettingsChangeData {
+    isDesktop: boolean;
+    isForceRebuild: boolean;
+    widthChanged: boolean;
+    heightChanged: boolean;
+    scrollHeightChanged: boolean;
+}
+
 /**
  * Base interface for injectable core tools in the String system.
  * Each tool takes input and returns output (transform, extract, calculate).
@@ -1125,38 +1138,6 @@ interface StringToolsContainer {
     ruleParser: RuleParserTool;
 }
 
-/**
- * Shared context object passed to all modules and core controllers.
- *
- * Provides access to shared tools, data, settings, and event handling.
- */
-interface StringContext {
-    /**
-     * Collection of utility tools (e.g. lerp, dom parser, unit converter).
-     */
-    tools: StringToolsContainer;
-    /**
-     * Reactive state container including scroll, viewport, cursor, etc.
-     */
-    data: StringData;
-    /**
-     * Global configuration settings for modules and system behavior.
-     */
-    settings: StringSettings;
-    /**
-     * Centralized event emitter and listener system.
-     */
-    events: EventManager;
-    /**
-     * Caches the center positions of string objects.
-     */
-    centers: CenterCache;
-    /**
-     * Tracks hover states of string objects.
-     */
-    hover: HoverTracker;
-}
-
 type AttributeType = "string" | "number" | "boolean" | "json" | "dimension" | "breakpoint-dimension" | "tuple" | "easing" | "color" | {
     type: "enum";
     values: string[];
@@ -1264,6 +1245,10 @@ declare class StringModule implements IStringModule {
      * Tracker for managing hover states of objects.
      */
     protected hover: HoverTracker;
+    /**
+     * Object manager for layout refreshes and in-view recalculation.
+     */
+    protected objectManager: ObjectManager;
     permissions: ModuleLifecyclePermissions;
     constructor(context: StringContext);
     /**
@@ -1379,6 +1364,10 @@ declare class StringModule implements IStringModule {
     destroy(): void;
     /** Called once when the module is initialized. */
     onInit(): void;
+    /** Called once when the module is registered and can subscribe to events. */
+    onSubscribe(): void;
+    /** Called once when the module is being removed and should unsubscribe. */
+    onUnsubscribe(): void;
     /** Called on each frame with current scroll and state data. */
     onFrame(data: StringData): void;
     onMutate(data: StringData): void;
@@ -1390,7 +1379,7 @@ declare class StringModule implements IStringModule {
     onResizeWidth(): void;
     /** Called when scroll position changes. */
     onScroll(data: StringData): void;
-    /** Called when user changed scroll diraction. */
+    /** Called when user changed scroll direction. */
     onDirectionChange(): void;
     /** Called when user starts scrolling. */
     onScrollStart(): void;
@@ -1418,6 +1407,179 @@ declare class StringModule implements IStringModule {
     onDOMMutate(added: NodeList, removed: NodeList): void;
 }
 
+declare class ModuleManager {
+    private data;
+    private modules;
+    private uiModules;
+    private allModules;
+    constructor(data: StringData);
+    register(module: StringModule): void;
+    find<T>(type: new (...args: any[]) => T): T | undefined;
+    onInit(): void;
+    onFrame(): void;
+    onMutate(): void;
+    onScrollMeasure(): void;
+    onMouseMoveMeasure(): void;
+    onScroll(): void;
+    onResizeWidth(): void;
+    onResize(): void;
+    onMouseMove(e: MouseEvent): void;
+    onWheel(e: WheelEvent): void;
+    onDirectionChange(): void;
+    onScrollStart(): void;
+    onScrollStop(): void;
+    onAxisChange(): void;
+    onDeviceChange(): void;
+    onScrollConfigChange(): void;
+    onSettingsChange(_data: ISettingsChangeData): void;
+    onDOMMutate(added: NodeList, removed: NodeList): void;
+    destroy(): void;
+    get all(): IStringModule[];
+    get core(): IStringModule[];
+    get ui(): IStringModule[];
+    private callAll;
+    private callLifecycle;
+    private rebuildAllModules;
+}
+
+declare class ObjectManager {
+    private data;
+    private modules;
+    private events;
+    private tools;
+    private objects;
+    private connectQueue;
+    private mirrors;
+    private mirrorId;
+    private globalId;
+    private domBatcher;
+    private domBatcherEnabled;
+    private inviewStarts;
+    private inviewEnds;
+    private inviewActive;
+    private inviewStartIdx;
+    private inviewEndIdx;
+    private inviewIndexDirty;
+    private lastInviewScrollPos;
+    private intersectionObserverEnabled;
+    constructor(data: StringData, modules: ModuleManager, events: EventManager, tools: StringToolsContainer);
+    /**
+     * Returns the object map (read-only).
+     */
+    get all(): ReadonlyMap<string, StringObject>;
+    /**
+     * Adds a new object from an element.
+     */
+    add(el: HTMLElement): void;
+    setDOMBatcherEnabled(enabled: boolean): void;
+    setIntersectionObserverEnabled(enabled: boolean): void;
+    invalidateInviewIndex(): void;
+    refreshLayoutForRoot(root: HTMLElement): void;
+    /**
+     * Removes an object by its id.
+     */
+    remove(id: string): void;
+    /**
+     * Add an element that will connect later.
+     */
+    enqueueConnection(id: string, element: HTMLElement): void;
+    linkMirror(id: string, element: HTMLElement): void;
+    private attachMirrorToObject;
+    private detachMirrorByElement;
+    private detachMirrorById;
+    private getMirrorIds;
+    private setMirrorIds;
+    private clearMirrorIds;
+    /**
+     * Retrieves all attributes of a given HTML element and returns them as a record.
+     *
+     * @param el - The HTML element from which to extract attributes.
+     * @returns A record where the keys are attribute names and the values are attribute values.
+     */
+    private getAllAttributes;
+    /**
+     * Initializes IntersectionObservers for a given object and its associated HTML element.
+     *
+     * This method sets up observer:
+     * - A "progress" observer to track when the object enters or leaves the viewport.
+     *
+     * The observers are configured with custom root margins and thresholds based on the object's properties.
+     * Existing observers, if any, are disconnected before creating new ones.
+     *
+     * @param obj - The `StringObject` instance containing properties and methods for interaction.
+     * @param el - The `HTMLElement` to observe for intersection changes.
+     */
+    private initObservers;
+    /**
+     * Observes DOM mutations to auto-add/remove elements with [string] attribute.
+     * Should be called once after DOM is ready.
+     */
+    observeDOM(): void;
+    /**
+     * Removes an object and its observers.
+     */
+    private handleRemoved;
+    /**
+     * Re-applies module initialization logic to all managed objects after settings change.
+     *
+     * This method should be called when `StringSettings` are updated at runtime,
+     * especially if the new settings affect how modules calculate offsets,
+     * easing, origins, or custom configuration.
+     *
+     * Internally, it re-runs `initializeObject`, `calculatePositions`, and `connectObject`
+     * for each core module that can connect to the object.
+     *
+     * This is useful for supporting dynamic configuration updates without requiring
+     * a full DOM rebuild or reinitialization.
+     */
+    onSettingsChange(data: ISettingsChangeData): void;
+    /**
+     * Checks whether the element is marked as fixed (not managed).
+     */
+    private isFixed;
+    checkInview(): void;
+    private checkInviewForObject;
+    private updateInviewWindow;
+    private rebuildInviewIndex;
+    private upperBound;
+}
+
+/**
+ * Shared context object passed to all modules and core controllers.
+ *
+ * Provides access to shared tools, data, settings, and event handling.
+ */
+interface StringContext {
+    /**
+     * Collection of utility tools (e.g. lerp, dom parser, unit converter).
+     */
+    tools: StringToolsContainer;
+    /**
+     * Reactive state container including scroll, viewport, cursor, etc.
+     */
+    data: StringData;
+    /**
+     * Global configuration settings for modules and system behavior.
+     */
+    settings: StringSettings;
+    /**
+     * Centralized event emitter and listener system.
+     */
+    events: EventManager;
+    /**
+     * Caches the center positions of string objects.
+     */
+    centers: CenterCache;
+    /**
+     * Tracks hover states of string objects.
+     */
+    hover: HoverTracker;
+    /**
+     * Manages all interactive objects (elements with `string-*` attributes).
+     */
+    objectManager: ObjectManager;
+}
+
 /**
  * StringCursor Module
  *
@@ -1506,6 +1668,27 @@ declare class StringImpulse extends StringModule {
     onFrame(_: StringData): void;
 }
 
+declare class StringMasonry extends StringModule {
+    private states;
+    constructor(context: StringContext);
+    private parseEasing;
+    onObjectConnected(object: StringObject): void;
+    onFrame(data: StringData): void;
+    onResize(): void;
+    cleanupObject(object: StringObject): void;
+    private createState;
+    private handleAnimationEnd;
+    private scheduleLayout;
+    /**
+     * Performs the layout calculation and application synchronously.
+     * Optimizes for batched DOM reads and writes via `styleTxn`.
+     */
+    private performSyncLayout;
+    private getGridSettings;
+    private attachImgLoaders;
+    private cleanupImgListeners;
+}
+
 declare class StringMagnetic extends StringModule {
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
@@ -2031,6 +2214,11 @@ interface ScrollMarkRule {
          */
         className: string;
     };
+    /**
+     * Internal state tracking whether the rule is currently active.
+     * prevents redundant callbacks and class toggles.
+     */
+    isActive?: boolean;
 }
 
 declare class StringSequence extends StringModule {
@@ -2154,6 +2342,92 @@ declare class StyleTxn {
 }
 declare const styleTxn: StyleTxn;
 
+declare class StringRandom extends StringModule {
+    constructor(context: StringContext);
+    onObjectConnected(object: StringObject): void;
+}
+
+/**
+ * Base class for managing scroll behavior in the system.
+ * Handles abstract scroll state and updates, intended for extension.
+ */
+declare class ScrollController {
+    /** Shared context containing data and tools */
+    protected context: StringContext;
+    /** Reference to the document object */
+    protected document: Document;
+    /** Name of the scroll mode (e.g. 'default', 'smooth', etc.) */
+    name: string;
+    /** Whether the system is in programmatic scroll mode */
+    isProg: boolean;
+    /** Whether parallax-related logic should be active */
+    isParallaxEnabled: boolean;
+    /** Scroll direction: vertical or horizontal */
+    protected _scrollDirection: "vertical" | "horizontal";
+    /**
+     * Current scroll direction.
+     * - `true` — scrolling down
+     * - `false` — scrolling up
+     * - `null` — unknown (initial state)
+     */
+    protected isBottomScrollDirection: boolean | null;
+    protected isLastBottomScrollDirection: boolean;
+    protected scrollTriggerRules: Array<ScrollMarkRule>;
+    /**
+     * Sets scroll direction and updates internal scroll logic.
+     * @param scrollDirection Either 'vertical' or 'horizontal'.
+     */
+    set scrollDirection(scrollDirection: "vertical" | "horizontal");
+    /**
+     * Creates a new ScrollController instance.
+     * @param context Shared context containing data and settings.
+     */
+    constructor(context: StringContext);
+    /**
+     * Called when scroll direction changes (up ↔ down).
+     * Override this callback in subclasses or instances.
+     */
+    onChangeDirection: () => void;
+    /**
+     * Called when scroll starts (user input).
+     * Override this callback in subclasses or instances.
+     */
+    onScrollStart: () => void;
+    /**
+     * Called when scroll ends.
+     * Override this callback in subclasses or instances.
+     */
+    onScrollStop: () => void;
+    /**
+     * Scroll-to function called on each frame.
+     * This will be reassigned depending on scroll direction.
+     */
+    onCalcUpdate: () => void;
+    /**
+     * Called every animation frame.
+     * Intended to be overridden in subclasses.
+     */
+    onFrame(): void;
+    /**
+     * Called when wheel event is fired.
+     * Override to implement custom scroll interaction.
+     * @param e Wheel event.
+     */
+    onWheel(e: any): void;
+    /**
+     * Called when native scroll event is fired.
+     * Override to track native scroll position.
+     * @param e Scroll event.
+     */
+    onScroll(e: any): void;
+    disableScrollEvents(): void;
+    enableScrollEvents(): void;
+    protected triggerScrollRules(): void;
+    addScrollMark(rule: ScrollMarkRule): void;
+    removeScrollMark(id: string): void;
+    scrollTo(position: number): void;
+}
+
 interface ModuleBatchContext {
     module: StringModule;
     object: StringObject;
@@ -2200,6 +2474,8 @@ declare class StringTune {
     private onResizeBind;
     /** Bound mouse move handler */
     private onMouseMoveBind;
+    /** Bound scroll to handler */
+    private onScrollToBind;
     private onContainerTransitionEndBind;
     private onResizeObserverBind;
     private pendingScroll;
@@ -2313,6 +2589,19 @@ declare class StringTune {
      * @param settings Optional settings specific to this module.
      */
     use(objectClass: typeof StringModule, settings?: any): void;
+    /**
+     * Registers a new scroll mode (provider) to the system.
+     * Allows integrating custom scroll implementations (e.g. Lenis, Locomotive).
+     *
+     * @param name The unique name for this scroll mode (e.g. 'smooth', 'lenis').
+     * @param factory A function that receives the StringContext and returns a ScrollController instance, OR a ScrollController class constructor.
+     *
+     * Example:
+     * ```ts
+     * stringTune.registerScrollMode("lenis", (context) => new LenisAdapter(context));
+     * ```
+     */
+    registerScrollMode(name: string, factory: ((context: StringContext) => ScrollController) | (new (context: StringContext) => ScrollController)): void;
     /**
      * Subscribes to a global event within the system.
      *
@@ -2423,28 +2712,9 @@ declare class StringTune {
      * Rebuilds layout and triggers module resize if size really changed.
      */
     onResize(force?: boolean): void;
-    /**
-     * Scrolls the container to the specified element identified by a CSS selector, applying an optional offset.
-     *
-     * Calculates the vertical position of the target element relative to the scroll container and updates the scroll delta accordingly.
-     * If the element is not found, a warning is logged to the console.
-     *
-     * @param selector - The CSS selector string used to identify the target element.
-     * @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;
     invalidateCenter(id: string): 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.
-     */
+    scrollTo(position: number): void;
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, 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 };
+export { CursorReactiveModule, DOMBatcher, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, StringTune as default, frameDOM, styleTxn };