fetta 1.3.5 → 1.4.0

package/README.md

@@ -86,6 +86,8 @@ const result = splitText(element, options);
 | `revertOnComplete` | `boolean` | `false` | Auto-revert when animation completes |
 | `propIndex` | `boolean` | `false` | Add CSS custom properties: `--char-index`, `--word-index`, `--line-index` |
 | `disableKerning` | `boolean` | `false` | Skip kerning compensation (no margin adjustments) |
+| `initialStyles` | `object` | — | Apply initial inline styles to chars/words/lines after split |
+| `initialClasses` | `object` | — | Apply initial CSS classes to chars/words/lines after split |
 
 #### Return Value
 
@@ -117,6 +119,9 @@ import { SplitText } from 'fetta/react';
 | `inView` | `boolean \| InViewOptions` | `false` | Enable viewport detection |
 | `onInView` | `function` | — | Called when element enters viewport |
 | `onLeaveView` | `function` | — | Called when element leaves viewport |
+| `initialStyles` | `object` | — | Apply initial inline styles to chars/words/lines |
+| `initialClasses` | `object` | — | Apply initial CSS classes to chars/words/lines |
+| `resetOnLeave` | `boolean` | `false` | Re-apply initialStyles/initialClasses when leaving viewport |
 
 #### InView Options
 
@@ -147,13 +152,15 @@ import { SplitText } from 'fetta/react';
 
 ```tsx
 <SplitText
-  onSplit={({ words }) => {
-    words.forEach(w => (w.style.opacity = '0'));
+  options={{ type: 'words' }}
+  initialStyles={{
+    words: { opacity: '0', transform: 'translateY(20px)' }
   }}
-  inView={{ amount: 0.5, once: true }}
+  inView={{ amount: 0.5 }}
   onInView={({ words }) => {
-    animate(words, { opacity: 1, y: [20, 0] }, { delay: stagger(0.03) });
+    animate(words, { opacity: 1, y: 0 }, { delay: stagger(0.03) });
   }}
+  resetOnLeave
 >
   <p>Animates when scrolled into view</p>
 </SplitText>

package/dist/{chunk-HQLYE4Q5.js → chunk-NTRJ6XDH.js}

@@ -411,6 +411,32 @@ function createMaskWrapper(display = "inline-block") {
   wrapper.style.overflow = "clip";
   return wrapper;
 }
+var PROTECTED_STYLES = /* @__PURE__ */ new Set([
+  "display",
+  "position",
+  "textDecoration",
+  "fontVariantLigatures"
+]);
+function applyInitialStyles(elements, style) {
+  if (!style || elements.length === 0) return;
+  const isFn = typeof style === "function";
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    const styles = isFn ? style(el, i) : style;
+    for (const [key, value] of Object.entries(styles)) {
+      if (!PROTECTED_STYLES.has(key) && value !== void 0) {
+        el.style[key] = value;
+      }
+    }
+  }
+}
+function applyInitialClasses(elements, className) {
+  if (!className || elements.length === 0) return;
+  const classes = className.split(/\s+/).filter(Boolean);
+  for (const el of elements) {
+    el.classList.add(...classes);
+  }
+}
 function groupIntoLines(elements, element) {
   const fontSize = parseFloat(getComputedStyle(element).fontSize);
   const tolerance = Math.max(5, fontSize * 0.3);
@@ -437,6 +463,7 @@ function groupIntoLines(elements, element) {
   return lineGroups;
 }
 function performSplit(element, measuredWords, charClass, wordClass, lineClass, splitChars, splitWords, splitLines, options) {
+  var _a, _b;
   element.textContent = "";
   const allChars = [];
   const allWords = [];
@@ -738,12 +765,34 @@ function performSplit(element, measuredWords, charClass, wordClass, lineClass, s
           element.appendChild(lineSpan);
         }
       });
+      if (options == null ? void 0 : options.initialStyles) {
+        const { chars, words, lines } = options.initialStyles;
+        if (chars) applyInitialStyles(allChars, chars);
+        if (words) applyInitialStyles(allWords, words);
+        if (lines) applyInitialStyles(allLines, lines);
+      }
+      if (options == null ? void 0 : options.initialClasses) {
+        const { chars, words, lines } = options.initialClasses;
+        if (chars) applyInitialClasses(allChars, chars);
+        if (words) applyInitialClasses(allWords, words);
+        if (lines) applyInitialClasses(allLines, lines);
+      }
       return {
         chars: allChars,
         words: splitWords ? allWords : [],
         lines: allLines
       };
     }
+    if (options == null ? void 0 : options.initialStyles) {
+      const { chars, words } = options.initialStyles;
+      if (chars) applyInitialStyles(allChars, chars);
+      if (words) applyInitialStyles(allWords, words);
+    }
+    if (options == null ? void 0 : options.initialClasses) {
+      const { chars, words } = options.initialClasses;
+      if (chars) applyInitialClasses(allChars, chars);
+      if (words) applyInitialClasses(allWords, words);
+    }
     return {
       chars: allChars,
       words: splitWords ? allWords : [],
@@ -795,6 +844,12 @@ function performSplit(element, measuredWords, charClass, wordClass, lineClass, s
           element.appendChild(lineSpan);
         }
       });
+      if ((_a = options == null ? void 0 : options.initialStyles) == null ? void 0 : _a.lines) {
+        applyInitialStyles(allLines, options.initialStyles.lines);
+      }
+      if ((_b = options == null ? void 0 : options.initialClasses) == null ? void 0 : _b.lines) {
+        applyInitialClasses(allLines, options.initialClasses.lines);
+      }
       return { chars: [], words: [], lines: allLines };
     } else {
       const fullText = measuredWords.map((w) => w.chars.map((c) => c.char).join("")).join(" ");
@@ -814,7 +869,9 @@ function splitText(element, {
   onSplit,
   revertOnComplete = false,
   propIndex = false,
-  disableKerning = false
+  disableKerning = false,
+  initialStyles,
+  initialClasses
 } = {}) {
   var _a;
   if (!(element instanceof HTMLElement)) {
@@ -865,7 +922,7 @@ function splitText(element, {
     splitChars,
     splitWords,
     splitLines,
-    { propIndex, mask, ariaHidden: !trackAncestors, disableKerning }
+    { propIndex, mask, ariaHidden: !trackAncestors, disableKerning, initialStyles, initialClasses }
   );
   currentChars = chars;
   currentWords = words;
@@ -940,7 +997,7 @@ function splitText(element, {
             splitChars,
             splitWords,
             splitLines,
-            { propIndex, mask, ariaHidden: !trackAncestors, disableKerning }
+            { propIndex, mask, ariaHidden: !trackAncestors, disableKerning, initialStyles, initialClasses }
           );
           currentChars = result.chars;
           currentWords = result.words;

package/dist/index.d.ts

@@ -46,7 +46,27 @@ interface SplitTextOptions {
      * Kerning is naturally lost when splitting into inline-block spans.
      * Use this if you prefer no compensation over imperfect Safari compensation. */
     disableKerning?: boolean;
+    /** Apply initial inline styles to elements after split (and after kerning compensation).
+     * Can be a static style object or a function that receives (element, index). */
+    initialStyles?: {
+        chars?: InitialStyle;
+        words?: InitialStyle;
+        lines?: InitialStyle;
+    };
+    /** Apply initial classes to elements after split (and after kerning compensation).
+     * Classes are added via classList.add() and support space-separated class names. */
+    initialClasses?: {
+        chars?: string;
+        words?: string;
+        lines?: string;
+    };
 }
+/** Style value for initialStyles - a partial CSSStyleDeclaration object */
+type InitialStyleValue = Partial<CSSStyleDeclaration>;
+/** Function that returns styles based on element and index */
+type InitialStyleFn = (element: HTMLElement, index: number) => InitialStyleValue;
+/** Initial style can be a static object or a function */
+type InitialStyle = InitialStyleValue | InitialStyleFn;
 /**
  * Result returned by splitText containing arrays of split elements and a revert function.
  *
@@ -112,6 +132,6 @@ interface SplitTextResult {
  * });
  * ```
  */
-declare function splitText(element: HTMLElement, { type, charClass, wordClass, lineClass, mask, autoSplit, onResize, onSplit, revertOnComplete, propIndex, disableKerning, }?: SplitTextOptions): SplitTextResult;
+declare function splitText(element: HTMLElement, { type, charClass, wordClass, lineClass, mask, autoSplit, onResize, onSplit, revertOnComplete, propIndex, disableKerning, initialStyles, initialClasses, }?: SplitTextOptions): SplitTextResult;
 
 export { type SplitTextOptions, type SplitTextResult, splitText };

package/dist/index.js

@@ -1 +1 @@
-export { splitText } from './chunk-HQLYE4Q5.js';
+export { splitText } from './chunk-NTRJ6XDH.js';

package/dist/react.d.ts

@@ -2,6 +2,24 @@ import * as react from 'react';
 import { ReactElement } from 'react';
 export { SplitTextOptions, SplitTextResult } from './index.js';
 
+/** Style value for initialStyles - a partial CSSStyleDeclaration object */
+type InitialStyleValue = Partial<CSSStyleDeclaration>;
+/** Function that returns styles based on element and index */
+type InitialStyleFn = (element: HTMLElement, index: number) => InitialStyleValue;
+/** Initial style can be a static object or a function */
+type InitialStyle = InitialStyleValue | InitialStyleFn;
+/** Initial styles configuration for chars, words, and/or lines */
+interface InitialStyles {
+    chars?: InitialStyle;
+    words?: InitialStyle;
+    lines?: InitialStyle;
+}
+/** Initial classes configuration for chars, words, and/or lines */
+interface InitialClasses {
+    chars?: string;
+    words?: string;
+    lines?: string;
+}
 interface SplitTextOptions {
     type?: "chars" | "words" | "lines" | "chars,words" | "words,lines" | "chars,lines" | "chars,words,lines";
     charClass?: string;
@@ -71,6 +89,15 @@ interface SplitTextProps {
     onInView?: (result: SplitTextElements) => CallbackReturn;
     /** Called when element leaves viewport */
     onLeaveView?: (result: SplitTextElements) => CallbackReturn;
+    /** Apply initial inline styles to elements after split (and after kerning compensation).
+     * Can be a static style object or a function that receives (element, index). */
+    initialStyles?: InitialStyles;
+    /** Apply initial classes to elements after split (and after kerning compensation).
+     * Classes are added via classList.add() and support space-separated class names. */
+    initialClasses?: InitialClasses;
+    /** Re-apply initialStyles and initialClasses when element leaves viewport.
+     * Useful for scroll-triggered animations that should reset when scrolling away. */
+    resetOnLeave?: boolean;
 }
 /**
  * React component wrapper for text splitting with kerning compensation.

package/dist/react.js

@@ -1,7 +1,27 @@
-import { splitText, __spreadProps, __spreadValues, normalizeToPromise } from './chunk-HQLYE4Q5.js';
+import { splitText, __spreadProps, __spreadValues, normalizeToPromise } from './chunk-NTRJ6XDH.js';
 import { forwardRef, useRef, useCallback, useState, useLayoutEffect, useEffect, isValidElement, cloneElement } from 'react';
 import { jsx } from 'react/jsx-runtime';
 
+function reapplyInitialStyles(elements, style) {
+  if (!style || elements.length === 0) return;
+  const isFn = typeof style === "function";
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    const styles = isFn ? style(el, i) : style;
+    for (const [key, value] of Object.entries(styles)) {
+      if (value !== void 0) {
+        el.style[key] = value;
+      }
+    }
+  }
+}
+function reapplyInitialClasses(elements, className) {
+  if (!className || elements.length === 0) return;
+  const classes = className.split(/\s+/).filter(Boolean);
+  for (const el of elements) {
+    el.classList.add(...classes);
+  }
+}
 var SplitText = forwardRef(
   function SplitText2({
     children,
@@ -15,7 +35,10 @@ var SplitText = forwardRef(
     revertOnComplete = false,
     inView,
     onInView,
-    onLeaveView
+    onLeaveView,
+    initialStyles,
+    initialClasses,
+    resetOnLeave = false
   }, forwardedRef) {
     const containerRef = useRef(null);
     const mergedRef = useCallback(
@@ -38,6 +61,9 @@ var SplitText = forwardRef(
     const inViewRef = useRef(inView);
     const onInViewRef = useRef(onInView);
     const onLeaveViewRef = useRef(onLeaveView);
+    const initialStylesRef = useRef(initialStyles);
+    const initialClassesRef = useRef(initialClasses);
+    const resetOnLeaveRef = useRef(resetOnLeave);
     useLayoutEffect(() => {
       onSplitRef.current = onSplit;
       onResizeRef.current = onResize;
@@ -46,6 +72,9 @@ var SplitText = forwardRef(
       inViewRef.current = inView;
       onInViewRef.current = onInView;
       onLeaveViewRef.current = onLeaveView;
+      initialStylesRef.current = initialStyles;
+      initialClassesRef.current = initialClasses;
+      resetOnLeaveRef.current = resetOnLeave;
     });
     const hasSplitRef = useRef(false);
     const hasRevertedRef = useRef(false);
@@ -67,6 +96,8 @@ var SplitText = forwardRef(
         const result = splitText(childElement, __spreadProps(__spreadValues({}, optionsRef.current), {
           autoSplit,
           revertOnComplete: revertOnCompleteRef.current,
+          initialStyles: initialStylesRef.current,
+          initialClasses: initialClassesRef.current,
           onResize: (resizeResult) => {
             var _a2;
             const newSplitTextElements = {
@@ -159,8 +190,25 @@ var SplitText = forwardRef(
             console.warn("[fetta] Animation rejected, text not reverted");
           });
         }
-      } else if (!isInView && onLeaveViewRef.current && splitResultRef.current) {
-        onLeaveViewRef.current(splitResultRef.current);
+      } else if (!isInView && splitResultRef.current) {
+        if (resetOnLeaveRef.current) {
+          const { chars, words, lines } = splitResultRef.current;
+          const styles = initialStylesRef.current;
+          const classes = initialClassesRef.current;
+          if (styles) {
+            reapplyInitialStyles(chars, styles.chars);
+            reapplyInitialStyles(words, styles.words);
+            reapplyInitialStyles(lines, styles.lines);
+          }
+          if (classes) {
+            reapplyInitialClasses(chars, classes.chars);
+            reapplyInitialClasses(words, classes.words);
+            reapplyInitialClasses(lines, classes.lines);
+          }
+        }
+        if (onLeaveViewRef.current) {
+          onLeaveViewRef.current(splitResultRef.current);
+        }
       }
     }, [isInView]);
     if (!isValidElement(children)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fetta",
-  "version": "1.3.5",
+  "version": "1.4.0",
   "description": "Text splitting library with kerning compensation for animations",
   "type": "module",
   "sideEffects": false,