@fiddle-digital/string-tune 1.2.0 → 1.2.1-alpha.1

package/dist/index.d.mts

@@ -242,6 +242,8 @@ interface IStringModule {
     onResize(): void;
     /** Called when the layout is resize width. */
     onResizeWidth(): void;
+    /** Called when DOM content changes (elements added/removed, images loaded) — no viewport remeasure. */
+    onRebuild(): void;
     /** Called when the system rebuilds the DOM (e.g. after mutations). */
     onDOMRebuild(): void;
     /** Called when scroll position changes. */
@@ -763,7 +765,7 @@ declare class LerpTool implements IStringTool<LerpInput, number> {
  */
 interface UnitParserInput {
     /** Unit string, e.g. `"20px"`, `"50%"`, `"1.5rem"`, or `"selfHeight"` */
-    value: string;
+    value: string | number;
     /** DOM element used for `"selfHeight"` calculation */
     element: HTMLElement;
     /** Viewport height in pixels (for percentage conversion) */
@@ -1066,6 +1068,7 @@ interface ISplitOptionItem {
  * Holds arrays of option definitions for each split type.
  */
 interface ISplitOptions {
+    segment?: "legacy" | "visual";
     fit?: boolean;
     trimInlineGaps?: boolean;
     line?: ISplitOptionItem[];
@@ -1091,6 +1094,7 @@ declare class SplitOptionsParserTool implements IStringTool<SplitOptionsParserIn
     process({ attributeValue }: SplitOptionsParserInput): ISplitOptions;
     private toCamelCase;
     private parseParamsArray;
+    private parseSegmentMode;
 }
 
 interface RuleParserInput {
@@ -1244,6 +1248,23 @@ type AttributeMapping = {
     transform?: (value: any) => any;
 };
 
+type StringSignalValue = number | boolean | string | null;
+declare class StringSignalHub {
+    private readonly emit;
+    private values;
+    constructor(emit: (eventName: string, payload?: any) => void);
+    publish(objectId: string, signal: string, value: StringSignalValue): void;
+    subscribe(objectId: string, signal: string, events: {
+        on<T = any>(eventName: string, callback: EventCallback<T>, id?: string | null): void;
+    }, callback: EventCallback<StringSignalValue>): void;
+    unsubscribe(objectId: string, signal: string, events: {
+        off<T = any>(eventName: string, callback: EventCallback<T>, id?: string): void;
+    }, callback: EventCallback<StringSignalValue>): void;
+    get(objectId: string, signal: string): StringSignalValue | undefined;
+    getEventName(objectId: string, signal: string): string;
+    private getKey;
+}
+
 interface ParseContext {
     element?: HTMLElement;
     boundingRect?: DOMRect;
@@ -1341,6 +1362,7 @@ declare class StringModule implements IStringModule {
      * Object manager for layout refreshes and in-view recalculation.
      */
     protected objectManager: ObjectManager;
+    protected signals: StringSignalHub;
     permissions: ModuleLifecyclePermissions;
     constructor(context: StringContext);
     /**
@@ -1383,7 +1405,7 @@ declare class StringModule implements IStringModule {
      * @param context Optional helper values like element or viewport size.
      * @returns The parsed and transformed value.
      */
-    protected parseAttribute(value: string | null, type: AttributeType, context?: ParseContext): any;
+    protected parseAttribute(value: string | number | null, type: AttributeType, context?: ParseContext): any;
     /**
      * Determines whether the module should attach to a given object,
      * based on the presence of the module's `htmlKey` in the object keys.
@@ -1474,6 +1496,8 @@ declare class StringModule implements IStringModule {
      * Returns a cached per-object event name to avoid building strings in hot paths.
      */
     protected getObjectEventName(object: StringObject, prefix: string, suffix?: string): string;
+    protected emitSignal(object: StringObject, signal: string, value: StringSignalValue): void;
+    protected getSignal(objectId: string, signal: string): StringSignalValue | undefined;
     protected clearManagedStyles(object: StringObject): void;
     protected onObjectModeActivated(object: StringObject): void;
     protected onObjectModeDeactivated(object: StringObject): void;
@@ -1497,6 +1521,8 @@ declare class StringModule implements IStringModule {
     onResize(): void;
     /** Called when the layout is resized width. */
     onResizeWidth(): void;
+    /** Called when DOM content changes (elements added/removed, images loaded) — no viewport remeasure. */
+    onRebuild(): void;
     /** Called when scroll position changes. */
     onScroll(data: StringData): void;
     /** Called when user changed scroll direction. */
@@ -1543,6 +1569,7 @@ declare class ModuleManager {
     onScroll(): void;
     onResizeWidth(): void;
     onResize(): void;
+    onRebuild(): void;
     onMouseMove(e: MouseEvent): void;
     onWheel(e: WheelEvent): void;
     onDirectionChange(): void;
@@ -1706,6 +1733,10 @@ interface StringContext {
      * Manages all interactive objects (elements with `string-*` attributes).
      */
     objectManager: ObjectManager;
+    /**
+     * Lightweight stateful signal transport for object-scoped values.
+     */
+    signals: StringSignalHub;
 }
 
 /**
@@ -1799,6 +1830,27 @@ declare class StringImpulse extends StringModule {
     onMutate(): void;
 }
 
+declare class StringMarquee extends StringModule {
+    private onFontsReadyBound;
+    constructor(context: StringContext);
+    onInit(): void;
+    onUnsubscribe(): void;
+    onObjectConnected(object: StringObject): void;
+    onObjectDisconnected(object: StringObject): void;
+    onResizeWidth(): void;
+    onFrame(data: StringData): void;
+    private createState;
+    private mountStructure;
+    private syncConfig;
+    private refresh;
+    private syncCopies;
+    private syncPartClass;
+    private updatePartProgress;
+    private onFontsReady;
+    private onMouseEnter;
+    private onMouseLeave;
+}
+
 declare class StringMasonry extends StringModule {
     private states;
     constructor(context: StringContext);
@@ -2049,6 +2101,7 @@ declare class StringScrollbar extends StringModule {
     onInit(): void;
     onScroll(data: StringData): void;
     onResize(): void;
+    onRebuild(): void;
     private addCustomStyles;
     private createScrollbar;
     private updateThumb;
@@ -2605,6 +2658,16 @@ declare class StringProgressPart extends StringModule {
     onObjectDisconnected(object: StringObject): void;
 }
 
+declare class StringSignal extends StringModule {
+    constructor(context: StringContext);
+    onObjectConnected(object: StringObject): void;
+    onObjectDisconnected(object: StringObject): void;
+    private applyRuleState;
+    private applyEffectState;
+    private applyEffect;
+    private resetEffect;
+}
+
 type Job = () => void;
 declare class FrameDOM {
     private measureQueue;
@@ -3699,6 +3762,8 @@ declare class StringTune {
     private observerContainerMutation;
     private pendingResizeRaf;
     private pendingResizeForce;
+    private pendingRebuildRaf;
+    private activeScrollIntent;
     /** Singleton instance of StringTune */
     private static i;
     /** Root scrollable element (typically <body>) */
@@ -3717,6 +3782,7 @@ declare class StringTune {
     private objectManager;
     /** Central event manager for internal pub-sub logic */
     private eventManager;
+    private signalHub;
     /** Handles custom cursor logic (if enabled) */
     private cursorController;
     /** Provides default utility tools (parsers, interpolation, etc.) */
@@ -3795,6 +3861,7 @@ declare class StringTune {
     set domBatcherEnabled(enabled: boolean);
     set intersectionObserverEnabled(enabled: boolean);
     private debouncedResize;
+    private debouncedRebuild;
     private constructor();
     /**
      * Returns the singleton instance of StringTune.
@@ -3902,6 +3969,8 @@ declare class StringTune {
     private onDOMChanged;
     private observeContainerMutations;
     private queueResize;
+    private queueRebuild;
+    onRebuild(): void;
     /**
      * Handles mouse move event and dispatches it to cursor and modules.
      * @param e Native mouse move event.
@@ -3952,7 +4021,7 @@ declare class StringTune {
      * Ignores height-only changes on mobile to prevent layout jumps.
      * Rebuilds layout and triggers module resize if size really changed.
      */
-    onResize(force?: boolean): void;
+    onResize(force?: boolean, source?: string): void;
     invalidateCenter(id: string): void;
     scrollTo(position: number): void;
     scrollTo(selector: string): void;
@@ -3972,7 +4041,9 @@ declare class StringTune {
     }): void;
     private resolveScrollToValue;
     private resolveElementScrollPosition;
+    private resolveScrollIntentPosition;
+    private clearActiveScrollIntent;
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, GridAdapter, type RulersLayoutGrid, type RulersTriggerAction, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringDevIconRegistry, StringDevInview, StringDevLayout, StringDevModule, StringDevOverlayRegistry, StringDevProgress, StringDevRulers, type StringDevStyleTokens, type StringDevtoolDefinition, type StringDevtoolProvider, type StringDevtoolState, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, type StringRulersTrigger, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, buildDevtoolsThemeBlock, StringTune as default, ensureStringDevtoolsSharedStyles, frameDOM, resolveDevtoolsIcon, styleTxn };
+export { CursorReactiveModule, DOMBatcher, GridAdapter, type RulersLayoutGrid, type RulersTriggerAction, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringDevIconRegistry, StringDevInview, StringDevLayout, StringDevModule, StringDevOverlayRegistry, StringDevProgress, StringDevRulers, type StringDevStyleTokens, type StringDevtoolDefinition, type StringDevtoolProvider, type StringDevtoolState, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMarquee, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, type StringRulersTrigger, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSignal, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, buildDevtoolsThemeBlock, StringTune as default, ensureStringDevtoolsSharedStyles, frameDOM, resolveDevtoolsIcon, styleTxn };

package/dist/index.d.ts

@@ -242,6 +242,8 @@ interface IStringModule {
     onResize(): void;
     /** Called when the layout is resize width. */
     onResizeWidth(): void;
+    /** Called when DOM content changes (elements added/removed, images loaded) — no viewport remeasure. */
+    onRebuild(): void;
     /** Called when the system rebuilds the DOM (e.g. after mutations). */
     onDOMRebuild(): void;
     /** Called when scroll position changes. */
@@ -763,7 +765,7 @@ declare class LerpTool implements IStringTool<LerpInput, number> {
  */
 interface UnitParserInput {
     /** Unit string, e.g. `"20px"`, `"50%"`, `"1.5rem"`, or `"selfHeight"` */
-    value: string;
+    value: string | number;
     /** DOM element used for `"selfHeight"` calculation */
     element: HTMLElement;
     /** Viewport height in pixels (for percentage conversion) */
@@ -1066,6 +1068,7 @@ interface ISplitOptionItem {
  * Holds arrays of option definitions for each split type.
  */
 interface ISplitOptions {
+    segment?: "legacy" | "visual";
     fit?: boolean;
     trimInlineGaps?: boolean;
     line?: ISplitOptionItem[];
@@ -1091,6 +1094,7 @@ declare class SplitOptionsParserTool implements IStringTool<SplitOptionsParserIn
     process({ attributeValue }: SplitOptionsParserInput): ISplitOptions;
     private toCamelCase;
     private parseParamsArray;
+    private parseSegmentMode;
 }
 
 interface RuleParserInput {
@@ -1244,6 +1248,23 @@ type AttributeMapping = {
     transform?: (value: any) => any;
 };
 
+type StringSignalValue = number | boolean | string | null;
+declare class StringSignalHub {
+    private readonly emit;
+    private values;
+    constructor(emit: (eventName: string, payload?: any) => void);
+    publish(objectId: string, signal: string, value: StringSignalValue): void;
+    subscribe(objectId: string, signal: string, events: {
+        on<T = any>(eventName: string, callback: EventCallback<T>, id?: string | null): void;
+    }, callback: EventCallback<StringSignalValue>): void;
+    unsubscribe(objectId: string, signal: string, events: {
+        off<T = any>(eventName: string, callback: EventCallback<T>, id?: string): void;
+    }, callback: EventCallback<StringSignalValue>): void;
+    get(objectId: string, signal: string): StringSignalValue | undefined;
+    getEventName(objectId: string, signal: string): string;
+    private getKey;
+}
+
 interface ParseContext {
     element?: HTMLElement;
     boundingRect?: DOMRect;
@@ -1341,6 +1362,7 @@ declare class StringModule implements IStringModule {
      * Object manager for layout refreshes and in-view recalculation.
      */
     protected objectManager: ObjectManager;
+    protected signals: StringSignalHub;
     permissions: ModuleLifecyclePermissions;
     constructor(context: StringContext);
     /**
@@ -1383,7 +1405,7 @@ declare class StringModule implements IStringModule {
      * @param context Optional helper values like element or viewport size.
      * @returns The parsed and transformed value.
      */
-    protected parseAttribute(value: string | null, type: AttributeType, context?: ParseContext): any;
+    protected parseAttribute(value: string | number | null, type: AttributeType, context?: ParseContext): any;
     /**
      * Determines whether the module should attach to a given object,
      * based on the presence of the module's `htmlKey` in the object keys.
@@ -1474,6 +1496,8 @@ declare class StringModule implements IStringModule {
      * Returns a cached per-object event name to avoid building strings in hot paths.
      */
     protected getObjectEventName(object: StringObject, prefix: string, suffix?: string): string;
+    protected emitSignal(object: StringObject, signal: string, value: StringSignalValue): void;
+    protected getSignal(objectId: string, signal: string): StringSignalValue | undefined;
     protected clearManagedStyles(object: StringObject): void;
     protected onObjectModeActivated(object: StringObject): void;
     protected onObjectModeDeactivated(object: StringObject): void;
@@ -1497,6 +1521,8 @@ declare class StringModule implements IStringModule {
     onResize(): void;
     /** Called when the layout is resized width. */
     onResizeWidth(): void;
+    /** Called when DOM content changes (elements added/removed, images loaded) — no viewport remeasure. */
+    onRebuild(): void;
     /** Called when scroll position changes. */
     onScroll(data: StringData): void;
     /** Called when user changed scroll direction. */
@@ -1543,6 +1569,7 @@ declare class ModuleManager {
     onScroll(): void;
     onResizeWidth(): void;
     onResize(): void;
+    onRebuild(): void;
     onMouseMove(e: MouseEvent): void;
     onWheel(e: WheelEvent): void;
     onDirectionChange(): void;
@@ -1706,6 +1733,10 @@ interface StringContext {
      * Manages all interactive objects (elements with `string-*` attributes).
      */
     objectManager: ObjectManager;
+    /**
+     * Lightweight stateful signal transport for object-scoped values.
+     */
+    signals: StringSignalHub;
 }
 
 /**
@@ -1799,6 +1830,27 @@ declare class StringImpulse extends StringModule {
     onMutate(): void;
 }
 
+declare class StringMarquee extends StringModule {
+    private onFontsReadyBound;
+    constructor(context: StringContext);
+    onInit(): void;
+    onUnsubscribe(): void;
+    onObjectConnected(object: StringObject): void;
+    onObjectDisconnected(object: StringObject): void;
+    onResizeWidth(): void;
+    onFrame(data: StringData): void;
+    private createState;
+    private mountStructure;
+    private syncConfig;
+    private refresh;
+    private syncCopies;
+    private syncPartClass;
+    private updatePartProgress;
+    private onFontsReady;
+    private onMouseEnter;
+    private onMouseLeave;
+}
+
 declare class StringMasonry extends StringModule {
     private states;
     constructor(context: StringContext);
@@ -2049,6 +2101,7 @@ declare class StringScrollbar extends StringModule {
     onInit(): void;
     onScroll(data: StringData): void;
     onResize(): void;
+    onRebuild(): void;
     private addCustomStyles;
     private createScrollbar;
     private updateThumb;
@@ -2605,6 +2658,16 @@ declare class StringProgressPart extends StringModule {
     onObjectDisconnected(object: StringObject): void;
 }
 
+declare class StringSignal extends StringModule {
+    constructor(context: StringContext);
+    onObjectConnected(object: StringObject): void;
+    onObjectDisconnected(object: StringObject): void;
+    private applyRuleState;
+    private applyEffectState;
+    private applyEffect;
+    private resetEffect;
+}
+
 type Job = () => void;
 declare class FrameDOM {
     private measureQueue;
@@ -3699,6 +3762,8 @@ declare class StringTune {
     private observerContainerMutation;
     private pendingResizeRaf;
     private pendingResizeForce;
+    private pendingRebuildRaf;
+    private activeScrollIntent;
     /** Singleton instance of StringTune */
     private static i;
     /** Root scrollable element (typically <body>) */
@@ -3717,6 +3782,7 @@ declare class StringTune {
     private objectManager;
     /** Central event manager for internal pub-sub logic */
     private eventManager;
+    private signalHub;
     /** Handles custom cursor logic (if enabled) */
     private cursorController;
     /** Provides default utility tools (parsers, interpolation, etc.) */
@@ -3795,6 +3861,7 @@ declare class StringTune {
     set domBatcherEnabled(enabled: boolean);
     set intersectionObserverEnabled(enabled: boolean);
     private debouncedResize;
+    private debouncedRebuild;
     private constructor();
     /**
      * Returns the singleton instance of StringTune.
@@ -3902,6 +3969,8 @@ declare class StringTune {
     private onDOMChanged;
     private observeContainerMutations;
     private queueResize;
+    private queueRebuild;
+    onRebuild(): void;
     /**
      * Handles mouse move event and dispatches it to cursor and modules.
      * @param e Native mouse move event.
@@ -3952,7 +4021,7 @@ declare class StringTune {
      * Ignores height-only changes on mobile to prevent layout jumps.
      * Rebuilds layout and triggers module resize if size really changed.
      */
-    onResize(force?: boolean): void;
+    onResize(force?: boolean, source?: string): void;
     invalidateCenter(id: string): void;
     scrollTo(position: number): void;
     scrollTo(selector: string): void;
@@ -3972,7 +4041,9 @@ declare class StringTune {
     }): void;
     private resolveScrollToValue;
     private resolveElementScrollPosition;
+    private resolveScrollIntentPosition;
+    private clearActiveScrollIntent;
     destroy(): void;
 }
 
-export { CursorReactiveModule, DOMBatcher, GridAdapter, type RulersLayoutGrid, type RulersTriggerAction, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringDevIconRegistry, StringDevInview, StringDevLayout, StringDevModule, StringDevOverlayRegistry, StringDevProgress, StringDevRulers, type StringDevStyleTokens, type StringDevtoolDefinition, type StringDevtoolProvider, type StringDevtoolState, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, type StringRulersTrigger, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, buildDevtoolsThemeBlock, StringTune as default, ensureStringDevtoolsSharedStyles, frameDOM, resolveDevtoolsIcon, styleTxn };
+export { CursorReactiveModule, DOMBatcher, GridAdapter, type RulersLayoutGrid, type RulersTriggerAction, ScrollController, type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringDevIconRegistry, StringDevInview, StringDevLayout, StringDevModule, StringDevOverlayRegistry, StringDevProgress, StringDevRulers, type StringDevStyleTokens, type StringDevtoolDefinition, type StringDevtoolProvider, type StringDevtoolState, StringFPSTracker, StringForm, StringGlide, StringImpulse, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringMarquee, StringMasonry, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringProgressPart, StringRandom, StringResponsive, type StringRulersTrigger, StringScrollContainer, StringScrollbar, StringScroller, StringSequence, StringSignal, StringSplit, StringSpotlight, StringTune, StringVideoAutoplay, buildDevtoolsThemeBlock, StringTune as default, ensureStringDevtoolsSharedStyles, frameDOM, resolveDevtoolsIcon, styleTxn };