@fiddle-digital/string-tune 1.1.49 → 1.1.50

package/dist/index.d.mts

@@ -71,7 +71,8 @@ declare class RenderState {
 }
 
 type ScrollDirection = 'vertical' | 'horizontal';
-type ScrollMode = 'smooth' | 'disable' | 'default' | (string & {});
+type BuiltInScrollMode = 'smooth' | 'disable' | 'default';
+type ScrollMode = BuiltInScrollMode | string;
 /**
  * Describes current scroll-related state for all calculations and modules.
  */
@@ -455,6 +456,30 @@ declare class StringObject {
      * Internal key-value store of dynamic object properties (like offsets, progress, etc.).
      */
     private properties;
+    private eventNameCache;
+    private eventNameSuffixCache;
+    /**
+     * Direct properties for extremely hot, per-frame accessed metrics
+     * to avoid going through the Map and incurring overhead.
+     */
+    progress: number;
+    progressRaw: number;
+    startPosition: number;
+    differencePosition: number;
+    transformValue: {
+        transform: string;
+    } | null;
+    eventProgressName: string | null;
+    lerp: number;
+    glide: number;
+    isMagneting: boolean;
+    magneticX: number;
+    magneticY: number;
+    magneticTargetX: number;
+    magneticTargetY: number;
+    eventLerpName: string | null;
+    eventGlideName: string | null;
+    eventMagneticName: string | null;
     /**
      * Modules currently connected to this object.
      */
@@ -465,6 +490,12 @@ declare class StringObject {
      */
     events: EventManager;
     constructor(id: string, element: HTMLElement);
+    /**
+     * Returns a cached event name in one of these forms:
+     * - `${prefix}:${id}`
+     * - `${prefix}:${id}:${suffix}`
+     */
+    getScopedEventName(prefix: string, suffix?: string): string;
     /**
      * Stores a property value for this object.
      * @param key - Property name
@@ -505,7 +536,7 @@ declare class StringObject {
      * Connects a module to this object if not already connected.
      * @param module - The module to connect
      */
-    connect(module: IStringModule): void;
+    connect(module: IStringModule): boolean;
     addMirror(mirror: StringMirrorObject): void;
     removeMirror(id: string): void;
     get mirrorObjects(): StringMirrorObject[];
@@ -542,6 +573,32 @@ interface ISettingsChangeData {
     scrollHeightChanged: boolean;
 }
 
+type StyleValue = string | number;
+type StyleVars = Record<string, StyleValue>;
+type StyleProps = Record<string, StyleValue>;
+declare class StyleTxn {
+    pendingVars: Map<Element, StyleVars>;
+    pendingProps: Map<Element, StyleProps>;
+    isOpen: boolean;
+    private canUseTypedOM;
+    private writeVar;
+    begin(): void;
+    setVars(el: Element, vars: StyleVars): void;
+    setVar(el: Element, key: string, value: StyleValue): void;
+    /**
+     * Directly sets a CSS custom property (variable) on an element using CSS Typed OM
+     * for improved performance. Falls back to string-based assignment if not supported.
+     * Note: This writes immediately. Use `begin()`, `setVar()`, `commit()` for batched writes.
+     */
+    setVarDirect(el: Element, key: string, value: StyleValue): void;
+    setProps(el: Element, props: StyleProps): void;
+    setProp(el: Element, key: string, value: StyleValue): void;
+    run(fn: () => void): void;
+    commit(): void;
+    cancel(): void;
+}
+declare const styleTxn: StyleTxn;
+
 /**
  * Base interface for injectable core tools in the String system.
  * Each tool takes input and returns output (transform, extract, calculate).
@@ -1075,7 +1132,8 @@ declare class ValidationTool implements IStringTool<ValidateInput, ValidationRes
 }
 
 /**
- * Interface describing all available tools used inside modules.
+ * Container holding references to all essential tools used within the library.
+ * Dependency injection.
  */
 interface StringToolsContainer {
     /** Tool for reading DOM attributes (including data-*). */
@@ -1136,6 +1194,7 @@ interface StringToolsContainer {
     transformScaleParser: TransformScaleParserTool;
     optionsParser: SplitOptionsParserTool;
     ruleParser: RuleParserTool;
+    styleTxn: typeof styleTxn;
 }
 
 type AttributeType = "string" | "number" | "boolean" | "json" | "dimension" | "breakpoint-dimension" | "tuple" | "easing" | "color" | {
@@ -1186,6 +1245,17 @@ declare class StringModule implements IStringModule {
      * Example: ["offset-top", "offset-bottom"]
      */
     protected attributesToMap: AttributeMapping[];
+    /**
+     * Defines CSS Custom Properties (Houdini) strictly required by this module.
+     * ModuleManager will automatically register these properties on initialization
+     * for Typed Object Model hardware acceleration.
+     */
+    cssProperties: Array<{
+        name: string;
+        syntax: string;
+        initialValue: string;
+        inherits: boolean;
+    }>;
     /**
      * A map that associates string keys with `StringObject` instances.
      * This map is used to manage and track `StringObject` instances on a page.
@@ -1358,6 +1428,26 @@ declare class StringModule implements IStringModule {
      * @param applyFn The function that receives an HTMLElement and performs any update.
      */
     protected applyToElementAndConnects(object: StringObject, applyFn: (el: HTMLElement) => void, copyFn?: (el: HTMLElement, mirror?: StringMirrorObject) => void): void;
+    /**
+     * Directly applies a CSS variable to the object's element without closures.
+     */
+    protected applyVarToElement(object: StringObject, key: string, value: string | number): void;
+    /**
+     * Directly applies a standard CSS property to the object's element without closures.
+     */
+    protected applyPropToElement(object: StringObject, key: string, value: string | number): void;
+    /**
+     * Directly applies a CSS variable to all connected mirrors without closures.
+     */
+    protected applyVarToConnects(object: StringObject, key: string, value: string | number): void;
+    /**
+     * Directly applies a standard CSS property to all connected mirrors without closures.
+     */
+    protected applyPropToConnects(object: StringObject, key: string, value: string | number): void;
+    /**
+     * Returns a cached per-object event name to avoid building strings in hot paths.
+     */
+    protected getObjectEventName(object: StringObject, prefix: string, suffix?: string): string;
     /**
      * Cleans up internal state and detaches the module from the system.
      */
@@ -1438,7 +1528,7 @@ declare class ModuleManager {
     get core(): IStringModule[];
     get ui(): IStringModule[];
     private callAll;
-    private callLifecycle;
+    private callLifecycleStrict;
     private rebuildAllModules;
 }
 
@@ -1449,6 +1539,7 @@ declare class ObjectManager {
     private tools;
     private objects;
     private connectQueue;
+    private connectableModulesBuffer;
     private mirrors;
     private mirrorId;
     private globalId;
@@ -1462,6 +1553,7 @@ declare class ObjectManager {
     private inviewIndexDirty;
     private lastInviewScrollPos;
     private intersectionObserverEnabled;
+    private domObserver;
     constructor(data: StringData, modules: ModuleManager, events: EventManager, tools: StringToolsContainer);
     /**
      * Returns the object map (read-only).
@@ -1542,6 +1634,8 @@ declare class ObjectManager {
     private updateInviewWindow;
     private rebuildInviewIndex;
     private upperBound;
+    private splitPipeAndTrim;
+    destroy(): void;
 }
 
 /**
@@ -1637,6 +1731,7 @@ declare class StringCursor extends StringModule {
     private bindGlobalLifecycleListeners;
     private unbindGlobalLifecycleListeners;
     private setMouseCoordinates;
+    private writePortalVars;
     private parseCursorVars;
     private getFrameAdjustedLerp;
     private getObjectDimensions;
@@ -1666,6 +1761,7 @@ declare class StringImpulse extends StringModule {
      */
     private getRotationOriginFromRect;
     onFrame(_: StringData): void;
+    onMutate(): void;
 }
 
 declare class StringMasonry extends StringModule {
@@ -1694,6 +1790,7 @@ declare class StringMagnetic extends StringModule {
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
     onMouseMove(e: MouseEvent): void;
     onFrame(data: StringData): void;
+    onMutate(): void;
 }
 
 declare abstract class CursorReactiveModule extends StringModule {
@@ -1716,11 +1813,13 @@ declare abstract class CursorReactiveModule extends StringModule {
 }
 
 declare class StringSpotlight extends CursorReactiveModule {
+    private readonly stepResult;
     constructor(context: any);
     initializeObject(id: number, obj: StringObject, el: HTMLElement, attrs: Record<string, any>): void;
     onMutate(data: StringData): void;
     protected onCursorScrollUpdate(): void;
     private updateSpotlightState;
+    private writeSpotlightVars;
 }
 
 declare class StringLazy extends StringModule {
@@ -1793,6 +1892,7 @@ declare class StringGlide extends StringModule {
     private negativeVelocityMultiplier;
     private maxDisplacementValue;
     constructor(context: StringContext);
+    initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
     private setupItem;
     private onUpdateDesktopEvent;
     private onUpdateMobileEvent;
@@ -1804,6 +1904,9 @@ declare class StringGlide extends StringModule {
     onScrollStart(): void;
     onScrollStop(): void;
     onFrame(data: StringData): void;
+    onMutate(): void;
+    private applyPendingGlideStyles;
+    private flushPendingGlideStyles;
 }
 
 /**
@@ -1849,9 +1952,15 @@ declare class StringLerp extends StringModule {
 
 declare class StringProgress extends StringModule {
     protected updateScheduled: boolean;
+    private batchStarts;
+    private batchDiffs;
+    private batchOut;
     constructor(context: StringContext);
     initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
+    private sanitizeRawProgress;
+    private applyRawProgress;
     private recomputeProgress;
+    private ensureBatchCapacity;
     calculatePositions(object: StringObject, windowSize: number): void;
     onScroll(data: StringData): void;
     onObjectConnected(object: StringObject): void;
@@ -1896,6 +2005,7 @@ declare class StringScrollbar extends StringModule {
     private scrollbarState;
     private scrollbarStateHorizontal;
     private scrollbarStateVertical;
+    private requestScrollTo;
     constructor(context: StringContext);
     destructor(): void;
     onInit(): void;
@@ -2309,6 +2419,95 @@ declare class StringScroller extends StringModule {
     onObjectDisconnected(object: StringObject): void;
 }
 
+/**
+ * Module that provides smooth scrolling behavior for isolated containers.
+ * Allows nested elements to have independent smooth scroll physics similar to the main window.
+ *
+ * Usage:
+ * Add `string="scroll-container"` to any block element.
+ * Optional: `string-lerp="0.1"` to controls the smoothing factor.
+ */
+declare class StringScrollContainer extends StringModule {
+    /**
+     * WeakMap storing the state for each managed HTMLElement.
+     */
+    private states;
+    /**
+     * Initializes the StringScrollContainer module.
+     * Registers the `lerp` attribute configuration.
+     *
+     * @param context The shared StringTune context.
+     */
+    constructor(context: StringContext);
+    /**
+     * Called when a new object with `string="scroll-container"` is initialized.
+     * Sets up initial state, event listeners, and default styles.
+     *
+     * @param object The StringObject instance being connected.
+     */
+    onObjectConnected(object: StringObject): void;
+    /**
+     * Called when an object is removed from the DOM or disconnected.
+     * Cleans up the state associated with the element.
+     *
+     * @param object The StringObject instance being disconnected.
+     */
+    onObjectDisconnected(object: StringObject): void;
+    /**
+     * Main animation loop for the module.
+     * Updates the scroll position of active containers based on their target state.
+     *
+     * @param data Global frame data including time deltas.
+     */
+    onFrame(data: StringData): void;
+    /**
+     * Called when the window or layout is resized.
+     * Recalculates scroll boundaries for all managed containers.
+     */
+    onResize(): void;
+    /**
+     * Recalculates the maximum scrollable distance for a container.
+     *
+     * @param el The scroll container element.
+     * @param state The state object associated with the element.
+     */
+    private measure;
+    /**
+     * Handles the mouse wheel event to apply custom scroll physics.
+     * Intercepts the event to prevent native scrolling and updates the target position.
+     * Allows event propagation if scrolling past the boundaries (scroll chaining).
+     *
+     * @param e The WheelEvent triggered by the user.
+     * @param el The target scroll container element.
+     * @param state The state object associated with the element.
+     */
+    private handleWheel;
+    /**
+     * Placeholder for global wheel handler if needed by generic StringModule interface.
+     * Specific handling is done via local event listeners in `handleWheel`.
+     *
+     * @param e Global WheelEvent.
+     */
+    onWheel(e: WheelEvent): void;
+    /**
+     * Handles native scroll events (dragbars, keyboard, touch).
+     * Syncs the internal state with the native scroll position if the custom animation is not active.
+     *
+     * @param e The Scroll event.
+     * @param el The target scroll container element.
+     * @param state The state object associated with the element.
+     */
+    private onNativeScroll;
+    /**
+     * Updates the element's scrollTop property by interpolating towards the target.
+     * Stops the animation if the difference is negligible.
+     *
+     * @param el The scroll container element.
+     * @param state The state object associated with the element.
+     */
+    private updateScroll;
+}
+
 declare class StringProgressPart extends StringModule {
     constructor(context: StringContext);
     onObjectConnected(object: StringObject): void;
@@ -2322,26 +2521,11 @@ declare class FrameDOM {
     private scheduled;
     measure(fn: Job): void;
     mutate(fn: Job): void;
-    private schedule;
+    schedule(): void;
+    flush(): void;
 }
 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 StringRandom extends StringModule {
     constructor(context: StringContext);
     onObjectConnected(object: StringObject): void;
@@ -2373,6 +2557,10 @@ declare class ScrollController {
     protected isBottomScrollDirection: boolean | null;
     protected isLastBottomScrollDirection: boolean;
     protected scrollTriggerRules: Array<ScrollMarkRule>;
+    /** Tracks whether this controller is currently active */
+    protected isActive: boolean;
+    /** Last direction applied to DOM classes (for global-class toggles) */
+    protected lastAppliedDirection: boolean | null;
     /**
      * Sets scroll direction and updates internal scroll logic.
      * @param scrollDirection Either 'vertical' or 'horizontal'.
@@ -2422,10 +2610,30 @@ declare class ScrollController {
     onScroll(e: any): void;
     disableScrollEvents(): void;
     enableScrollEvents(): void;
+    /**
+     * Called when this controller becomes the active scroll engine.
+     * Ensures event bindings are attached only once.
+     */
+    activate(): void;
+    /**
+     * Called when this controller is deactivated.
+     * Ensures event bindings are detached only once.
+     */
+    deactivate(): void;
+    /**
+     * Allows controllers to clean up resources on global destroy.
+     */
+    destroy(): void;
+    /**
+     * Updates scroll direction state, emits events, and toggles global classes.
+     * Intended for reuse by custom scroll adapters.
+     */
+    protected updateScrollDirection(newDirection: boolean): void;
+    protected clearScrollingClasses(): void;
     protected triggerScrollRules(): void;
     addScrollMark(rule: ScrollMarkRule): void;
     removeScrollMark(id: string): void;
-    scrollTo(position: number): void;
+    scrollTo(position: number, immediate?: boolean): void;
 }
 
 interface ModuleBatchContext {
@@ -2476,10 +2684,14 @@ declare class StringTune {
     private onMouseMoveBind;
     /** Bound scroll to handler */
     private onScrollToBind;
+    private onDOMChangedBind;
     private onContainerTransitionEndBind;
     private onResizeObserverBind;
     private pendingScroll;
     private lastScrollEmitted;
+    private observerContainerMutation;
+    private pendingResizeRaf;
+    private pendingResizeForce;
     /** Singleton instance of StringTune */
     private static i;
     /** Root scrollable element (typically <body>) */
@@ -2598,7 +2810,7 @@ declare class StringTune {
      *
      * Example:
      * ```ts
-     * stringTune.registerScrollMode("lenis", (context) => new LenisAdapter(context));
+     * stringTune.registerScrollMode("custom", (context) => new CustomAdapter(context));
      * ```
      */
     registerScrollMode(name: string, factory: ((context: StringContext) => ScrollController) | (new (context: StringContext) => ScrollController)): void;
@@ -2664,6 +2876,9 @@ declare class StringTune {
     setupSettings(settings: StringSettings): void;
     private onResizeObserverEvent;
     private onContainerTransitionEnd;
+    private onDOMChanged;
+    private observeContainerMutations;
+    private queueResize;
     /**
      * Handles mouse move event and dispatches it to cursor and modules.
      * @param e Native mouse move event.
@@ -2713,8 +2928,11 @@ declare class StringTune {
      */
     onResize(force?: boolean): void;
     invalidateCenter(id: string): void;
-    scrollTo(position: number): void;
+    scrollTo(value: number | {
+        position: number;
+        immediate?: boolean;
+    }): void;
     destroy(): void;
 }
 
-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 };
+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, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, StringTune as default, frameDOM, styleTxn };