@fiddle-digital/string-tune 1.0.3 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -756,294 +756,6 @@ interface ISplitOptions {
756
756
  wordLine?: ISplitOptionItem[];
757
757
  }
758
758
 
759
- /**
760
- * Represents a single word identified during layout calculation.
761
- */
762
- interface LayoutWord {
763
- /** The text content of the word. */
764
- text: string;
765
- }
766
-
767
- /**
768
- * Represents a line of text as determined by layout calculations.
769
- */
770
- interface LayoutLine {
771
- /** The full text content of the line as a single string. */
772
- text: string;
773
- /** An array of word objects that make up this line. */
774
- words: LayoutWord[];
775
- }
776
-
777
- /**
778
- * Holds the final calculated numerical value resulting from applying
779
- * a specific ISplitOptionItem rule to a word or character, along with
780
- * context about the rule itself (type, alignment).
781
- * This is used by the SplitDomBuilderTool to set CSS variables.
782
- */
783
- interface CalculatedValue {
784
- /**
785
- * The final numerical result after applying the alignment ('start', 'center', 'end', 'random')
786
- * and absolute value ('abs') logic based on the specific option rule.
787
- * This is the value that will be set for the CSS variable.
788
- */
789
- value: number;
790
- /**
791
- * Indicates which type of split option definition this value originated from.
792
- * Crucial for generating the correct CSS variable name prefix (e.g., '--word-', '--charLine-').
793
- */
794
- type: 'line' | 'word' | 'char' | 'wordLine' | 'charLine' | 'charWord';
795
- /**
796
- * Stores the specific alignment ('start', 'center', 'end', 'random')
797
- * defined in the option rule that produced this value.
798
- * Used for generating the CSS variable name suffix (e.g., '-center', '-end').
799
- */
800
- align: string;
801
- }
802
-
803
- /**
804
- * Represents a processed word, containing its text, contextual indices
805
- * (global, line, word-in-line), and an array of calculated values
806
- * based on the applicable 'word' and 'wordLine' options.
807
- */
808
- interface ProcessedWord {
809
- /** The text content of the word. */
810
- text: string;
811
- /** The zero-based index of the word across all words in all lines. */
812
- globalIndex: number;
813
- /** The zero-based index of the line this word belongs to. */
814
- lineIndex: number;
815
- /** The zero-based index of this word within its line. */
816
- wordIndexInLine: number;
817
- /** An array of calculated values based on ISplitOptions ('word', 'wordLine'). */
818
- calculatedValues: CalculatedValue[];
819
- }
820
-
821
- /**
822
- * Input for the CharIndexerTool.
823
- */
824
- interface CharIndexerInput {
825
- /** The array of processed words from WordIndexerTool. */
826
- processedWords: ProcessedWord[];
827
- /** The array of layout lines (needed to calculate total line characters). */
828
- lines: LayoutLine[];
829
- /** The parsed split options relevant for characters ('char', 'charLine', 'charWord'). */
830
- options: Pick<ISplitOptions, 'char' | 'charLine' | 'charWord'>;
831
- /** The total number of non-whitespace characters in the original text. */
832
- totalChars: number;
833
- }
834
-
835
- /**
836
- * Represents a processed character, containing its text, contextual indices
837
- * (global, line, word, plus parent info), and an array of calculated values
838
- * based on the applicable 'char', 'charLine', and 'charWord' options.
839
- */
840
- interface ProcessedChar {
841
- /** The character itself. */
842
- text: string;
843
- /** The zero-based index of the character across all non-whitespace characters. */
844
- globalCharIndex: number;
845
- /** The zero-based index of the character within its line (excluding spaces between words). */
846
- lineCharIndex: number;
847
- /** The zero-based index of the character within its word. */
848
- wordCharIndex: number;
849
- /** Index of the parent word across all words. */
850
- parentGlobalWordIndex: number;
851
- /** Index of the line this character belongs to. */
852
- parentLineIndex: number;
853
- /** Index of the parent word within its line. */
854
- parentWordIndexInLine: number;
855
- /** An array of calculated index values based on ISplitOptions ('char', 'charLine', 'charWord'). */
856
- calculatedValues: CalculatedValue[];
857
- }
858
-
859
- /**
860
- * Tool to process words split by layout, breaking them into characters
861
- * and assigning relevant indices (global, line, word) for each character.
862
- * Calculates index values based on ISplitOptions for characters ('char', 'charLine', 'charWord').
863
- * Produces an array of ProcessedChar objects.
864
- */
865
- declare class CharIndexerTool implements IStringTool<CharIndexerInput, ProcessedChar[]> {
866
- /**
867
- * Iterates through processed words, splits them into characters, assigns
868
- * global, line, and word character indices, and calculates index values
869
- * based on the provided character options ('char', 'charLine', 'charWord').
870
- *
871
- * @param input.processedWords - Array of ProcessedWord objects from WordIndexerTool.
872
- * @param input.lines - Array of LayoutLine objects (needed for calculating total characters per line).
873
- * @param input.options - The relevant ISplitOptions ('char', 'charLine', 'charWord').
874
- * @param input.totalChars - Total number of non-whitespace characters in the original text.
875
- * @returns An array of ProcessedChar objects, ready for DOM building/styling.
876
- */
877
- process({ processedWords, lines, options, totalChars, }: CharIndexerInput): ProcessedChar[];
878
- /**
879
- * Calculates the final numerical index value based on alignment options, context indices, and parent length.
880
- * (Identical helper function as in WordIndexerTool - could be extracted to a common utility).
881
- *
882
- * @param option - The specific option item definition ({ align, random, abs }).
883
- * @param primaryIndex - The main index used for calculation (global, line, or word char index).
884
- * @param localIndex - The secondary index (e.g., index within word).
885
- * @param parentLength - The total count in the relevant context (total chars, line chars, or word chars).
886
- * @returns The calculated numerical index value.
887
- */
888
- private calculateIndex;
889
- }
890
-
891
- /**
892
- * Input interface for the LayoutLineSplitterTool.
893
- * Requires both the text and the element it will be rendered within.
894
- */
895
- interface LayoutSplitInput {
896
- /** The raw text content to be split into lines based on layout. */
897
- text: string;
898
- /** The HTML element whose width and styles determine line breaks. */
899
- targetElement: HTMLElement;
900
- }
901
-
902
- /**
903
- * Tool to split a text string into structured lines and words based on how
904
- * the text would visually wrap within a given target HTML element.
905
- * This simulates browser rendering by measuring word widths.
906
- * Returns an array of LayoutLine objects.
907
- */
908
- declare class LayoutLineSplitterTool implements IStringTool<LayoutSplitInput, LayoutLine[]> {
909
- /**
910
- * Processes the input text and splits it into lines containing words,
911
- * simulating word wrapping within the boundaries of the targetElement.
912
- *
913
- * @param input.text - The text content to split.
914
- * @param input.targetElement - The HTMLElement used as a reference for width and font styles.
915
- * @returns An array of LayoutLine objects, each containing the line's text and an array of its words.
916
- * Returns an empty array on error or invalid input.
917
- */
918
- process({ text, targetElement }: LayoutSplitInput): LayoutLine[];
919
- /**
920
- * Measures the width of a given text string using the provided temporary span.
921
- * @param text - The text to measure.
922
- * @param tempSpan - The pre-styled temporary span element used for measurement.
923
- * @returns The width of the text in pixels.
924
- */
925
- private measureWidth;
926
- /**
927
- * Decodes basic HTML entities (currently just &amp;).
928
- * Can be expanded if more entities need handling.
929
- * @param str - The string potentially containing HTML entities.
930
- * @returns The string with '&amp;' decoded to '&'.
931
- */
932
- private decodeHtmlEntity;
933
- }
934
-
935
- /**
936
- * Defines the input structure required by the SplitDomBuilderTool.
937
- */
938
- interface DomBuilderInput {
939
- /** Array of lines determined by layout. */
940
- lines: LayoutLine[];
941
- /** Array of words with calculated indices and values. */
942
- words: ProcessedWord[];
943
- /** Array of characters with calculated indices and values. */
944
- chars: ProcessedChar[];
945
- /** The original parsed split options. */
946
- options: ISplitOptions;
947
- }
948
-
949
- /**
950
- * Tool to build the final innerHTML string with nested spans (-s-line, -s-word, -s-char)
951
- * and apply calculated CSS variables based on processed data from indexer tools.
952
- * Implements the IStringTool interface.
953
- */
954
- declare class SplitDomBuilderTool implements IStringTool<DomBuilderInput, string> {
955
- /**
956
- * Generates the innerHTML string for the split text by creating nested spans
957
- * (-s-line, -s-word, -s-char) based on options and applying styles from calculated index values.
958
- *
959
- * @param input An object containing layout lines, processed words, processed characters, and the original split options.
960
- * @returns The generated HTML string representing the split content.
961
- */
962
- process({ lines, words, chars, options }: DomBuilderInput): string;
963
- /**
964
- * Creates and styles a character span.
965
- * @param pChar - The processed character data.
966
- * @returns The styled HTMLSpanElement for the character.
967
- * @private
968
- */
969
- private createCharSpan;
970
- /**
971
- * Checks if any line-level splitting options (line, wordLine, charLine) are present.
972
- * @param options - The ISplitOptions object.
973
- * @returns True if any line-level options exist and have definitions, false otherwise.
974
- * @private
975
- */
976
- private hasLineOptions;
977
- /**
978
- * Checks if any word-level splitting options (word, wordLine) are present.
979
- * @param options - The ISplitOptions object.
980
- * @returns True if any word-level options exist and have definitions, false otherwise.
981
- * @private
982
- */
983
- private hasWordOptions;
984
- /**
985
- * Checks if any character-level splitting options (char, charLine, charWord) are present.
986
- * @param options - The ISplitOptions object.
987
- * @returns True if any character-level options exist and have definitions, false otherwise.
988
- * @private
989
- */
990
- private hasCharOptions;
991
- /**
992
- * Applies the pre-calculated index values as CSS custom properties to the element's style.
993
- * @param span - The HTMLElement (line, word, or char span) to apply styles to.
994
- * @param calculatedValues - An array of calculated values from the indexer tool.
995
- * @private
996
- */
997
- private applyStyles;
998
- /**
999
- * Generates a CSS custom property name based on the split type and alignment.
1000
- * @param type - The type of split element ('line', 'word', 'char', etc.).
1001
- * @param align - The alignment option ('start', 'center', 'end', 'random').
1002
- * @returns The generated CSS variable name string (e.g., '--word-center').
1003
- * @private
1004
- */
1005
- private generateVariableName;
1006
- }
1007
-
1008
- /**
1009
- * Input for the WordIndexerTool.
1010
- */
1011
- interface WordIndexerInput {
1012
- /** The array of layout lines produced by LayoutLineSplitterTool. */
1013
- lines: LayoutLine[];
1014
- /** The parsed split options relevant for words ('word', 'wordLine'). */
1015
- options: Pick<ISplitOptions, 'word' | 'wordLine'>;
1016
- }
1017
-
1018
- /**
1019
- * Tool to process layout lines and words, assigning relevant indices
1020
- * and calculating index values based on ISplitOptions ('word', 'wordLine').
1021
- * Produces an array of ProcessedWord objects.
1022
- */
1023
- declare class WordIndexerTool implements IStringTool<WordIndexerInput, ProcessedWord[]> {
1024
- /**
1025
- * Iterates through lines and words, assigning global and local indices,
1026
- * and calculating index values based on the provided options ('word', 'wordLine').
1027
- *
1028
- * @param input.lines - Array of LayoutLine objects from LayoutLineSplitterTool.
1029
- * @param input.options - The relevant ISplitOptions ('word', 'wordLine').
1030
- * @returns An array of ProcessedWord objects, each containing word text, indices,
1031
- * and an array of calculated values based on options.
1032
- */
1033
- process({ lines, options }: WordIndexerInput): ProcessedWord[];
1034
- /**
1035
- * Calculates the final numerical index value based on alignment options, context indices, and parent length.
1036
- * This logic determines the value eventually set as a CSS variable.
1037
- *
1038
- * @param option - The specific option item definition ({ align, random, abs }).
1039
- * @param primaryIndex - The main index used for calculation (global index for 'word', index within line for 'wordLine').
1040
- * @param localIndex - The secondary index (e.g., index within the line), potentially useful for some alignment logic.
1041
- * @param parentLength - The total count in the relevant context (total words for 'word', words in the current line for 'wordLine').
1042
- * @returns The calculated numerical index value.
1043
- */
1044
- private calculateIndex;
1045
- }
1046
-
1047
759
  /**
1048
760
  * Input interface for the SplitOptionsParserTool.
1049
761
  */
@@ -1143,10 +855,6 @@ interface StringToolsContainer {
1143
855
  */
1144
856
  lerpVector: LerpVector2Tool;
1145
857
  transformScaleParser: TransformScaleParserTool;
1146
- layoutSplitter: LayoutLineSplitterTool;
1147
- wordIndexer: WordIndexerTool;
1148
- charIndexer: CharIndexerTool;
1149
- domBuilder: SplitDomBuilderTool;
1150
858
  optionsParser: SplitOptionsParserTool;
1151
859
  }
1152
860
 
@@ -1229,6 +937,14 @@ declare class StringObject {
1229
937
  * Marks this object as "inactive" (usually on intersection/scroll leave).
1230
938
  */
1231
939
  leave(): void;
940
+ /**
941
+ * Removes the current object by iterating through all associated modules
942
+ * and invoking their `removeObject` method with the object's ID.
943
+ *
944
+ * This method ensures that the object is properly removed from all
945
+ * modules it is associated with.
946
+ */
947
+ remove(): void;
1232
948
  /**
1233
949
  * Shows the object, applies visual class and notifies connected modules.
1234
950
  */
@@ -1320,6 +1036,8 @@ interface IStringModule {
1320
1036
  * Called when the interaction leaves the object's area.
1321
1037
  */
1322
1038
  exitObject(id: string): void;
1039
+ addObject(id: string, object: StringObject): void;
1040
+ removeObject(id: string): void;
1323
1041
  }
1324
1042
 
1325
1043
  type AttributeType = "string" | "number" | "boolean" | "json" | "dimension" | "tuple" | "easing" | "color" | {
@@ -1370,6 +1088,16 @@ declare class StringModule implements IStringModule {
1370
1088
  * Example: ["offset-top", "offset-bottom"]
1371
1089
  */
1372
1090
  protected attributesToMap: AttributeMapping[];
1091
+ /**
1092
+ * A map that associates string keys with `StringObject` instances.
1093
+ * This map is used to manage and track `StringObject` instances on a page.
1094
+ */
1095
+ protected objectMapOnPage: Map<string, StringObject>;
1096
+ /**
1097
+ * A protected array that holds the collection of `StringObject` instances
1098
+ * currently present on the page.
1099
+ */
1100
+ protected objectsOnPage: StringObject[];
1373
1101
  /**
1374
1102
  * A map of all entered objects by their unique ID.
1375
1103
  */
@@ -1413,7 +1141,22 @@ declare class StringModule implements IStringModule {
1413
1141
  protected events: EventManager;
1414
1142
  constructor(context: StringContext);
1415
1143
  /**
1416
- * Called when a DOM element is detected as a potential interactive object.
1144
+ * Initializes a `StringObject` by mapping attributes from an HTML element
1145
+ * and applying transformations as needed.
1146
+ *
1147
+ * @param globalId - A unique identifier for the object being initialized.
1148
+ * @param object - The `StringObject` instance to be initialized.
1149
+ * @param element - The HTML element from which attributes are extracted.
1150
+ * @param attributes - A record of additional attributes to be used during initialization.
1151
+ *
1152
+ * The method performs the following steps:
1153
+ * 1. Retrieves the bounding rectangle of the provided HTML element.
1154
+ * 2. Iterates over a predefined list of attributes to map.
1155
+ * 3. Resolves fallback values for attributes, either from the provided attributes,
1156
+ * settings, or a fallback function.
1157
+ * 4. Processes and parses the raw attribute values based on their expected type.
1158
+ * 5. Applies optional transformations to the parsed values.
1159
+ * 6. Sets the processed attributes as properties on the `StringObject` instance.
1417
1160
  */
1418
1161
  initializeObject(globalId: number, object: StringObject, element: HTMLElement, attributes: Record<string, any>): void;
1419
1162
  /**
@@ -1462,6 +1205,30 @@ declare class StringModule implements IStringModule {
1462
1205
  * Unregisters the object when it leaves the module’s scope.
1463
1206
  */
1464
1207
  exitObject(id: string): void;
1208
+ /**
1209
+ * Adds a `StringObject` to the internal collections if it does not already exist.
1210
+ *
1211
+ * @param id - The unique identifier for the `StringObject`.
1212
+ * @param object - The `StringObject` to be added.
1213
+ *
1214
+ * @remarks
1215
+ * This method ensures that the object is added to both `objectMapOnPage` and
1216
+ * `objectsOnPage` only if the `id` is not already present in `objectMapOnPage`.
1217
+ */
1218
+ addObject(id: string, object: StringObject): void;
1219
+ /**
1220
+ * Removes an object from the page by its unique identifier.
1221
+ *
1222
+ * This method performs the following steps:
1223
+ * 1. Retrieves the object associated with the given `id` from `objectMapOnPage`.
1224
+ * 2. If the object is not found, the method exits early.
1225
+ * 3. Deletes the object from `objectMapOnPage`.
1226
+ * 4. Finds the index of the object in the `objectsOnPage` array.
1227
+ * 5. If the object exists in the array, it is removed using `splice`.
1228
+ *
1229
+ * @param id - The unique identifier of the object to be removed.
1230
+ */
1231
+ removeObject(id: string): void;
1465
1232
  /**
1466
1233
  * Called when an object is connected. Can be overridden to apply initial styles or logic.
1467
1234
  * @param object The connected object.
@@ -1566,6 +1333,11 @@ declare class StringLazy extends StringModule {
1566
1333
  private setAspectRatio;
1567
1334
  }
1568
1335
 
1336
+ /**
1337
+ * Represents a module responsible for handling loading-related functionality.
1338
+ * Extends the `StringModule` class and provides additional behavior for managing
1339
+ * loading states and timeouts.
1340
+ */
1569
1341
  declare class StringLoading extends StringModule {
1570
1342
  loadingTimeout: number;
1571
1343
  constructor(context: StringContext);
@@ -1582,11 +1354,24 @@ declare class StringResponsive extends StringModule {
1582
1354
  private updateElements;
1583
1355
  }
1584
1356
 
1357
+ /**
1358
+ * The `StringAnchor` class extends the `StringModule` class and is responsible for
1359
+ * managing anchor-related functionality within the string module system.
1360
+ *
1361
+ * This class maps an `anchor` attribute to a tuple containing x and y coordinates,
1362
+ * processes these coordinates using the `originParser` tool, and applies the resulting
1363
+ * values to the connected object's element as a CSS `transform-origin` style.
1364
+ */
1585
1365
  declare class StringAnchor extends StringModule {
1586
1366
  constructor(context: StringContext);
1587
1367
  onObjectConnected(object: StringObject): void;
1588
1368
  }
1589
1369
 
1370
+ /**
1371
+ * The `StringGlide` class is a module that handles the glide effect for string objects
1372
+ * based on scroll events. It calculates displacement, acceleration, and velocity
1373
+ * to create a smooth scrolling effect for objects.
1374
+ */
1590
1375
  declare class StringGlide extends StringModule {
1591
1376
  private previousLerp;
1592
1377
  private displacement;
@@ -1631,6 +1416,11 @@ declare class StringLerp extends StringModule {
1631
1416
  private setLerpValue;
1632
1417
  }
1633
1418
 
1419
+ /**
1420
+ * The `StringProgress` class extends the `StringModule` class and is responsible for
1421
+ * managing progress-based behavior for elements during scroll events. It maps specific
1422
+ * attributes, initializes objects, and updates their progress based on scroll data.
1423
+ */
1634
1424
  declare class StringProgress extends StringModule {
1635
1425
  constructor(context: StringContext);
1636
1426
  /**
@@ -1645,6 +1435,12 @@ declare class StringProgress extends StringModule {
1645
1435
  private setUpObject;
1646
1436
  }
1647
1437
 
1438
+ /**
1439
+ * The `StringParallax` class extends the `StringProgress` class to provide
1440
+ * functionality for handling parallax effects on scrollable elements.
1441
+ * It maps specific attributes related to parallax and calculates the
1442
+ * necessary transformations based on scroll progress and viewport size.
1443
+ */
1648
1444
  declare class StringParallax extends StringProgress {
1649
1445
  constructor(context: StringContext);
1650
1446
  /**
@@ -1692,60 +1488,61 @@ declare class StringScrollbar extends StringModule {
1692
1488
  }
1693
1489
 
1694
1490
  /**
1695
- * StringModule responsible for splitting text within HTML elements
1696
- * into lines, words, and characters based on layout and attributes,
1697
- * and applying CSS variables for animation purposes.
1698
- * Uses a tool-based approach for modularity.
1491
+ * StringSplit module: splits text into lines, words, chars,
1492
+ * computes alignment/random values, and applies CSS vars.
1699
1493
  */
1700
1494
  declare class StringSplit extends StringModule {
1701
- /**
1702
- * Initializes the StringSplit module and its tools.
1703
- * @param context - The global StringContext.
1704
- */
1705
1495
  constructor(context: StringContext);
1706
- /**
1707
- * Called when the module initializes.
1708
- * Processes elements already present in the DOM on load.
1709
- */
1710
- onInit(): void;
1711
- /**
1712
- * Called when the window is resized.
1713
- * Re-processes already split elements as their layout might have changed.
1714
- */
1715
1496
  onResize(): void;
1716
- /**
1717
- * Called when a new StringObject associated with this module connects.
1718
- * Processes the newly connected element.
1719
- * @param object - The StringObject representing the connected element.
1720
- */
1721
1497
  onObjectConnected(object: StringObject): void;
1498
+ split(element: HTMLElement, options: ISplitOptions): {
1499
+ fragment: DocumentFragment;
1500
+ result: DocumentFragment;
1501
+ };
1722
1502
  /**
1723
- * Central method to process splitting for a given HTML element for automatic DOM manipulation.
1724
- * Orchestrates the use of various tools: parsing options, calculating layout,
1725
- * indexing words and characters, building the final HTML, and updating the DOM.
1726
- * Includes error handling.
1727
- * @param element - The HTMLElement to process.
1728
- * @private
1729
- */
1730
- private processElement;
1731
- /**
1732
- * Generates an HTML string with split text based on the provided text,
1733
- * a reference element for layout measurement, and options. Does not modify the DOM.
1503
+ * Computes a numeric value based on the provided split option, index, and total count.
1504
+ *
1505
+ * @param opt - The split option item containing alignment and optional random range.
1506
+ * @param index - The current index in the sequence.
1507
+ * @param total - The total number of items in the sequence.
1508
+ * @returns A computed numeric value based on the alignment strategy:
1509
+ * - "random": A random value within the specified range or default range.
1510
+ * - "start": The current index.
1511
+ * - "end": The reverse index from the end of the sequence.
1512
+ * - "center": The distance from the center index.
1513
+ * - Default: The current index.
1514
+ */
1515
+ private computeValue;
1516
+ /**
1517
+ * Applies calculated values to the provided layout lines and their components (words and characters)
1518
+ * based on the given options. This method computes and assigns various calculated values
1519
+ * (e.g., alignment and value) to lines, words, and characters, depending on the specified options.
1520
+ *
1521
+ * @param lines - An array of `LayoutLine` objects representing the lines of text to process.
1522
+ * @param options - An `ISplitOptions` object specifying the calculation options for lines, words, and characters.
1734
1523
  *
1735
- * @param textToSplit - The text or HTML string to split.
1736
- * @param layoutReferenceElement - The HTMLElement used for layout calculations. Should be in the DOM for accurate results.
1737
- * @param options - The splitting options (ISplitOptions).
1738
- * @returns The generated HTML string with split elements, or an empty string on error.
1739
- * @public
1524
+ * The `options` parameter can include the following properties:
1525
+ * - `line`: An array of options for calculating values at the line level.
1526
+ * - `word`: An array of options for calculating values at the word level.
1527
+ * - `wordLine`: An array of options for calculating values at the word level relative to the line.
1528
+ * - `char`: An array of options for calculating values at the character level.
1529
+ * - `charWord`: An array of options for calculating values at the character level relative to the word.
1530
+ * - `charLine`: An array of options for calculating values at the character level relative to the line.
1531
+ *
1532
+ * Each calculated value is assigned to the corresponding `calculatedValues` property of the line, word, or character.
1533
+ * The method ensures that all specified options are processed and the calculated values are appended accordingly.
1740
1534
  */
1741
- generateSplitHtml(textToSplit: string, layoutReferenceElement: HTMLElement, options: ISplitOptions): string;
1535
+ private applyCalculatedValues;
1742
1536
  /**
1743
- * Example demonstrating how to use generateSplitHtml.
1744
- * @param spanElement - The element to split and use for layout reference.
1745
- * @returns The resulting HTML string.
1746
- * @public
1537
+ * Escapes the `src` attribute in a given string by removing the quotes around the URL.
1538
+ *
1539
+ * This method searches for occurrences of `src="URL"` where `URL` is an HTTP or HTTPS link,
1540
+ * and replaces it with `src=URL` (removing the quotes around the URL).
1541
+ *
1542
+ * @param str - The input string containing the `src` attributes to be escaped.
1543
+ * @returns The modified string with escaped `src` attributes.
1747
1544
  */
1748
- exampleUsage(spanElement: HTMLElement): string;
1545
+ private escapeAttribute;
1749
1546
  }
1750
1547
 
1751
1548
  /**
@@ -1887,6 +1684,48 @@ declare class StringVideoAutoplay extends StringModule {
1887
1684
  private tryPlay;
1888
1685
  }
1889
1686
 
1687
+ /**
1688
+ * Represents a rule for triggering actions based on scroll events.
1689
+ */
1690
+ interface ScrollMarkRule {
1691
+ /**
1692
+ * A unique identifier for the scroll trigger rule.
1693
+ */
1694
+ id: string;
1695
+ /**
1696
+ * The offset value (in pixels) from the top of the viewport where the rule is triggered.
1697
+ */
1698
+ offset: number;
1699
+ /**
1700
+ * The direction of the scroll that activates the rule.
1701
+ * - `"forward"`: Trigger when scrolling down.
1702
+ * - `"backward"`: Trigger when scrolling up.
1703
+ * - `"any"`: Trigger regardless of scroll direction.
1704
+ */
1705
+ direction: "forward" | "backward" | "any";
1706
+ /**
1707
+ * Optional callback function to execute when the scroll position enters the trigger zone.
1708
+ */
1709
+ onEnter?: () => void;
1710
+ /**
1711
+ * Optional callback function to execute when the scroll position leaves the trigger zone.
1712
+ */
1713
+ onLeave?: () => void;
1714
+ /**
1715
+ * Optional configuration for toggling a CSS class on a target element.
1716
+ */
1717
+ toggleClass?: {
1718
+ /**
1719
+ * The target HTML element on which the class will be toggled.
1720
+ */
1721
+ target: HTMLElement;
1722
+ /**
1723
+ * The name of the CSS class to toggle.
1724
+ */
1725
+ className: string;
1726
+ };
1727
+ }
1728
+
1890
1729
  declare class StringTune {
1891
1730
  /** Bound handler for the scroll start event */
1892
1731
  private onScrollStartBind;
@@ -2015,6 +1854,31 @@ declare class StringTune {
2015
1854
  * @param id Optional ID used during subscription.
2016
1855
  */
2017
1856
  off(eventName: string, callback: EventCallback<any>, id?: string): void;
1857
+ /**
1858
+ * Adds a scroll trigger rule that activates when the user scrolls past a defined offset
1859
+ * in a specific direction. This can be used to toggle CSS classes or execute callbacks
1860
+ * when elements come into view or go out of view.
1861
+ *
1862
+ * @param rule - The scroll trigger configuration object.
1863
+ * - `id`: A unique identifier for this rule.
1864
+ * - `offset`: The vertical scroll offset (in pixels) where the rule should activate.
1865
+ * - `direction`: Defines the scroll direction required to activate the rule.
1866
+ * Can be `"forward"`, `"backward"`, or `"any"`.
1867
+ * - `onEnter`: (Optional) A function that will be called when the scroll position enters the trigger zone
1868
+ * in the specified direction.
1869
+ * - `onLeave`: (Optional) A function that will be called when the scroll position leaves the trigger zone
1870
+ * or scrolls in the opposite direction.
1871
+ * - `toggleClass`: (Optional) An object defining a class toggle behavior.
1872
+ * It contains a target element and a class name to be added when the trigger is active
1873
+ * and removed when it's not.
1874
+ */
1875
+ addScrollMark(rule: ScrollMarkRule): void;
1876
+ /**
1877
+ * Removes a scroll trigger by its unique identifier.
1878
+ *
1879
+ * @param id - The unique identifier of the scroll trigger to be removed.
1880
+ */
1881
+ removeScrollMark(id: string): void;
2018
1882
  /**
2019
1883
  * Starts the scroll engine and initializes all listeners, observers, and modules.
2020
1884
  *
@@ -2088,4 +1952,4 @@ declare class StringTune {
2088
1952
  destroy(): void;
2089
1953
  }
2090
1954
 
2091
- export { StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringGlide, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringResponsive, StringScrollbar, StringSplit, StringTune, StringVideoAutoplay, StringTune as default };
1955
+ export { type ScrollMarkRule as ScrollTriggerRule, StringAnchor, type StringContext, StringCursor, StringData, StringDelayLerpTracker, StringFPSTracker, StringGlide, StringLazy, StringLerp, StringLerpTracker, StringLoading, StringMagnetic, StringModule, StringObject, StringParallax, StringPositionTracker, StringProgress, StringResponsive, StringScrollbar, StringSplit, StringTune, StringVideoAutoplay, StringTune as default };