fetta 1.4.4 → 1.5.0

package/dist/react.d.ts

@@ -1,25 +1,9 @@
 import * as react from 'react';
 import { ReactElement } from 'react';
-export { SplitTextOptions, SplitTextResult } from './index.js';
+import { A as AnimationCallbackReturn } from './index-c1UKfWWK.js';
+export { a as CoreSplitTextOptions, S as SplitTextResult } from './index-c1UKfWWK.js';
+import { I as InitialStyles, a as InitialClasses } from './initialStyles-BGuPp5CS.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;
@@ -33,16 +17,21 @@ interface SplitTextOptions {
      * Use this if you prefer no compensation over imperfect Safari compensation. */
     disableKerning?: boolean;
 }
-interface InViewOptions {
-    /** How much of the element must be visible (0-1). Default: 0 */
-    amount?: number;
-    /** Root margin for IntersectionObserver. Default: "0px" */
-    margin?: string;
+/** Matches Motion's viewport prop */
+interface ViewportOptions {
     /** Only trigger once. Default: false */
     once?: boolean;
+    /** How much of the element must be visible. Motion supports "some" | "all" | number. Default: 0 */
+    amount?: number | "some" | "all";
+    /** How much visibility is required to consider the element out of view. Default: 0 (fully out) */
+    leave?: number | "some" | "all";
+    /** Root margin for IntersectionObserver. Default: "0px" */
+    margin?: string;
+    /** Root element for IntersectionObserver */
+    root?: React.RefObject<Element>;
 }
 /**
- * Result passed to SplitText callbacks (onSplit, onInView, onLeaveView, onResize).
+ * Result passed to SplitText callbacks (onSplit, onViewportEnter, onViewportLeave, onResplit).
  *
  * Contains arrays of split elements and a revert function for manual control.
  * Empty arrays are returned for split types not requested in options.
@@ -57,16 +46,12 @@ interface SplitTextElements {
     /** Revert to original HTML and cleanup observers */
     revert: () => void;
 }
-/** Return type for callbacks - void, single animation, array of animations, or promise */
-type CallbackReturn = void | {
-    finished: Promise<unknown>;
-} | Array<{
-    finished: Promise<unknown>;
-}> | Promise<unknown>;
-interface SplitTextProps {
+type ControlledWrapperHTMLKeys = "children" | "className" | "style" | "ref" | "as" | "onSplit" | "onResplit" | "options" | "autoSplit" | "revertOnComplete" | "viewport" | "onViewportEnter" | "onViewportLeave" | "onRevert" | "initialStyles" | "initialClasses" | "resetOnViewportLeave" | "waitForFonts";
+type WrapperHTMLProps = Omit<React.HTMLAttributes<HTMLElement>, ControlledWrapperHTMLKeys>;
+interface SplitTextProps extends WrapperHTMLProps {
     children: ReactElement;
     /** The wrapper element type. Default: "div" */
-    as?: keyof React.JSX.IntrinsicElements;
+    as?: keyof HTMLElementTagNameMap;
     /** Class name for the wrapper element */
     className?: string;
     /** Additional styles for the wrapper element (merged with internal styles) */
@@ -74,30 +59,33 @@ interface SplitTextProps {
     /**
      * Called after text is split.
      * Return an animation or promise to enable revert (requires revertOnComplete).
-     * If inView is enabled, this is called immediately but animation typically runs in onInView.
      */
-    onSplit?: (result: SplitTextElements) => CallbackReturn;
-    /** Called when autoSplit triggers a re-split on resize */
-    onResize?: (result: SplitTextElements) => void;
+    onSplit?: (result: SplitTextElements) => AnimationCallbackReturn;
+    /** Called when autoSplit/full-resplit replaces split output elements */
+    onResplit?: (result: SplitTextElements) => void;
     options?: SplitTextOptions;
     autoSplit?: boolean;
     /** When true, reverts to original HTML after animation promise resolves */
     revertOnComplete?: boolean;
-    /** Enable viewport detection. Pass true for defaults or InViewOptions for customization */
-    inView?: boolean | InViewOptions;
-    /** Called when element enters viewport. Return animation for revertOnComplete support */
-    onInView?: (result: SplitTextElements) => CallbackReturn;
-    /** Called when element leaves viewport */
-    onLeaveView?: (result: SplitTextElements) => CallbackReturn;
+    /** Viewport observer options (replaces `inView`). Configures IntersectionObserver. */
+    viewport?: ViewportOptions;
+    /** Called when element enters viewport (replaces `onInView`). Return animation for revertOnComplete support */
+    onViewportEnter?: (result: SplitTextElements) => AnimationCallbackReturn;
+    /** Called when element leaves viewport (replaces `onLeaveView`) */
+    onViewportLeave?: (result: SplitTextElements) => AnimationCallbackReturn;
+    /** Called when split text is reverted (manual or automatic) */
+    onRevert?: () => void;
     /** 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.
+    /** Re-apply initialStyles/initialClasses when element leaves viewport.
      * Useful for scroll-triggered animations that should reset when scrolling away. */
-    resetOnLeave?: boolean;
+    resetOnViewportLeave?: boolean;
+    /** Wait for `document.fonts.ready` before splitting. Disable for immediate split. */
+    waitForFonts?: boolean;
 }
 /**
  * React component wrapper for text splitting with kerning compensation.
@@ -105,6 +93,8 @@ interface SplitTextProps {
  * Wraps a single child element and splits its text content into characters,
  * words, and/or lines. Handles lifecycle cleanup automatically on unmount.
  *
+ * Supports callback mode via `onSplit`, `onViewportEnter`, `onViewportLeave`.
+ *
  * @param props - Component props including callbacks and options
  * @returns The child element wrapped in a container div
  *
@@ -113,7 +103,7 @@ interface SplitTextProps {
  * import { SplitText } from "fetta/react";
  * import { animate, stagger } from "motion";
  *
- * // Basic animation
+ * // Imperative animation
  * <SplitText
  *   onSplit={({ words }) => {
  *     animate(words, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.05) });
@@ -122,36 +112,7 @@ interface SplitTextProps {
  *   <h1>Animated Text</h1>
  * </SplitText>
  * ```
- *
- * @example
- * ```tsx
- * // Scroll-triggered with auto-revert
- * <SplitText
- *   onSplit={({ chars }) => {
- *     chars.forEach(c => c.style.opacity = "0");
- *   }}
- *   inView={{ amount: 0.5, once: true }}
- *   onInView={({ chars }) =>
- *     animate(chars, { opacity: 1 }, { delay: stagger(0.02) })
- *   }
- *   revertOnComplete
- * >
- *   <p>Reveals on scroll, reverts after animation</p>
- * </SplitText>
- * ```
- *
- * @example
- * ```tsx
- * // Responsive re-splitting
- * <SplitText
- *   autoSplit
- *   onSplit={({ lines }) => animate(lines, { opacity: [0, 1] })}
- *   onResize={({ lines }) => animate(lines, { opacity: [0, 1] })}
- * >
- *   <p>Re-animates when container resizes</p>
- * </SplitText>
- * ```
  */
 declare const SplitText: react.ForwardRefExoticComponent<SplitTextProps & react.RefAttributes<HTMLElement>>;
 
-export { SplitText, type SplitTextElements };
+export { SplitText, type SplitTextElements, type SplitTextOptions };

package/dist/react.js

@@ -1,45 +1,47 @@
-import { splitText, __spreadProps, __spreadValues, normalizeToPromise } from './chunk-Y4GCLM4K.js';
-import { forwardRef, useRef, useCallback, useState, useLayoutEffect, useEffect, isValidElement, cloneElement } from 'react';
-import { jsx } from 'react/jsx-runtime';
+import { waitForFontsReady, reapplyInitialStyles, reapplyInitialClasses } from './chunk-FP4I6OR2.js';
+import { splitText, normalizeToPromise } from './chunk-UPF3IYHC.js';
+import { __objRest, __spreadProps, __spreadValues } from './chunk-ORMEWXMH.js';
+import { forwardRef, useRef, useCallback, useState, useLayoutEffect, useEffect, isValidElement, createElement } from 'react';
 
-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,
-    as: Component = "div",
-    className,
-    style: userStyle,
-    onSplit,
-    onResize,
-    options,
-    autoSplit = false,
-    revertOnComplete = false,
-    inView,
-    onInView,
-    onLeaveView,
-    initialStyles,
-    initialClasses,
-    resetOnLeave = false
-  }, forwardedRef) {
+  function SplitText2(_a, forwardedRef) {
+    var _b = _a, {
+      children,
+      as: Component = "div",
+      className,
+      style: userStyle,
+      onSplit,
+      onResplit,
+      options,
+      autoSplit = false,
+      revertOnComplete = false,
+      viewport,
+      onViewportEnter,
+      onViewportLeave,
+      onRevert,
+      initialStyles,
+      initialClasses,
+      resetOnViewportLeave = false,
+      waitForFonts = true
+    } = _b, wrapperProps = __objRest(_b, [
+      "children",
+      "as",
+      "className",
+      "style",
+      "onSplit",
+      "onResplit",
+      "options",
+      "autoSplit",
+      "revertOnComplete",
+      "viewport",
+      "onViewportEnter",
+      "onViewportLeave",
+      "onRevert",
+      "initialStyles",
+      "initialClasses",
+      "resetOnViewportLeave",
+      "waitForFonts"
+    ]);
     const containerRef = useRef(null);
     const mergedRef = useCallback(
       (node) => {
@@ -54,27 +56,30 @@ var SplitText = forwardRef(
     );
     const [childElement, setChildElement] = useState(null);
     const [isInView, setIsInView] = useState(false);
+    const needsViewport = !!(onViewportEnter || onViewportLeave || resetOnViewportLeave || viewport);
     const onSplitRef = useRef(onSplit);
-    const onResizeRef = useRef(onResize);
+    const onResplitRef = useRef(onResplit);
     const optionsRef = useRef(options);
     const revertOnCompleteRef = useRef(revertOnComplete);
-    const inViewRef = useRef(inView);
-    const onInViewRef = useRef(onInView);
-    const onLeaveViewRef = useRef(onLeaveView);
+    const viewportRef = useRef(viewport);
+    const onViewportEnterRef = useRef(onViewportEnter);
+    const onViewportLeaveRef = useRef(onViewportLeave);
+    const onRevertRef = useRef(onRevert);
     const initialStylesRef = useRef(initialStyles);
     const initialClassesRef = useRef(initialClasses);
-    const resetOnLeaveRef = useRef(resetOnLeave);
+    const resetOnViewportLeaveRef = useRef(resetOnViewportLeave);
     useLayoutEffect(() => {
       onSplitRef.current = onSplit;
-      onResizeRef.current = onResize;
+      onResplitRef.current = onResplit;
       optionsRef.current = options;
       revertOnCompleteRef.current = revertOnComplete;
-      inViewRef.current = inView;
-      onInViewRef.current = onInView;
-      onLeaveViewRef.current = onLeaveView;
+      viewportRef.current = viewport;
+      onViewportEnterRef.current = onViewportEnter;
+      onViewportLeaveRef.current = onViewportLeave;
+      onRevertRef.current = onRevert;
       initialStylesRef.current = initialStyles;
       initialClassesRef.current = initialClasses;
-      resetOnLeaveRef.current = resetOnLeave;
+      resetOnViewportLeaveRef.current = resetOnViewportLeave;
     });
     const hasSplitRef = useRef(false);
     const hasRevertedRef = useRef(false);
@@ -82,53 +87,65 @@ var SplitText = forwardRef(
     const splitResultRef = useRef(null);
     const observerRef = useRef(null);
     const hasTriggeredOnceRef = useRef(false);
-    const childRefCallback = useCallback((node) => {
-      setChildElement(node);
-    }, []);
+    useLayoutEffect(() => {
+      var _a2;
+      const element = (_a2 = containerRef.current) == null ? void 0 : _a2.firstElementChild;
+      setChildElement(element instanceof HTMLElement ? element : null);
+    }, [children]);
     useEffect(() => {
       if (!childElement) return;
       if (hasSplitRef.current) return;
       let isMounted = true;
-      document.fonts.ready.then(() => {
-        var _a, _b;
+      waitForFontsReady(waitForFonts).then(() => {
         if (!isMounted || hasSplitRef.current) return;
         if (!containerRef.current) return;
+        let coreRevert = null;
+        const revert = () => {
+          var _a2;
+          if (hasRevertedRef.current) return;
+          hasRevertedRef.current = true;
+          try {
+            (_a2 = onRevertRef.current) == null ? void 0 : _a2.call(onRevertRef);
+          } finally {
+            coreRevert == null ? void 0 : coreRevert();
+          }
+        };
         const result = splitText(childElement, __spreadProps(__spreadValues({}, optionsRef.current), {
           autoSplit,
           revertOnComplete: revertOnCompleteRef.current,
           initialStyles: initialStylesRef.current,
           initialClasses: initialClassesRef.current,
-          onResize: (resizeResult) => {
+          onResplit: (resizeResult) => {
             var _a2;
             const newSplitTextElements = {
               chars: resizeResult.chars,
               words: resizeResult.words,
               lines: resizeResult.lines,
-              revert: result.revert
+              revert
             };
             splitResultRef.current = newSplitTextElements;
-            (_a2 = onResizeRef.current) == null ? void 0 : _a2.call(onResizeRef, newSplitTextElements);
+            (_a2 = onResplitRef.current) == null ? void 0 : _a2.call(onResplitRef, newSplitTextElements);
           }
         }));
-        revertFnRef.current = result.revert;
+        coreRevert = result.revert;
+        revertFnRef.current = revert;
         hasSplitRef.current = true;
         const splitElements = {
           chars: result.chars,
           words: result.words,
           lines: result.lines,
-          revert: result.revert
+          revert
         };
         splitResultRef.current = splitElements;
         containerRef.current.style.visibility = "visible";
         if (onSplitRef.current) {
           const callbackResult = onSplitRef.current(splitElements);
-          if (!inViewRef.current && revertOnCompleteRef.current) {
+          if (!needsViewport && revertOnCompleteRef.current) {
             const promise = normalizeToPromise(callbackResult);
             if (promise) {
               promise.then(() => {
                 if (!isMounted || hasRevertedRef.current) return;
-                result.revert();
-                hasRevertedRef.current = true;
+                splitElements.revert();
               }).catch(() => {
                 console.warn("[fetta] Animation rejected, text not reverted");
               });
@@ -139,29 +156,44 @@ var SplitText = forwardRef(
             }
           }
         }
-        if (inViewRef.current && containerRef.current) {
-          const inViewOptions = typeof inViewRef.current === "object" ? inViewRef.current : {};
-          const threshold = (_a = inViewOptions.amount) != null ? _a : 0;
-          const rootMargin = (_b = inViewOptions.margin) != null ? _b : "0px";
-          const thresholds = threshold > 0 ? [0, threshold] : 0;
-          observerRef.current = new IntersectionObserver(
-            (entries) => {
-              const entry = entries[0];
-              if (!entry) return;
-              const isOnce = typeof inViewRef.current === "object" && inViewRef.current.once;
-              if (entry.isIntersecting && entry.intersectionRatio >= threshold) {
-                if (isOnce && hasTriggeredOnceRef.current) return;
-                hasTriggeredOnceRef.current = true;
-                setIsInView(true);
-              } else if (!entry.isIntersecting && !isOnce) {
-                setIsInView(false);
-              }
-            },
-            { threshold: thresholds, rootMargin }
-          );
-          observerRef.current.observe(containerRef.current);
+        if (needsViewport && containerRef.current) {
+          setupViewportObserver(containerRef.current);
         }
       });
+      function setupViewportObserver(container) {
+        var _a2, _b2, _c, _d, _e;
+        const vpOptions = viewportRef.current || {};
+        const amount = (_a2 = vpOptions.amount) != null ? _a2 : 0;
+        const leave = (_b2 = vpOptions.leave) != null ? _b2 : 0;
+        const threshold = amount === "some" ? 0 : amount === "all" ? 1 : amount;
+        const leaveThreshold = leave === "some" ? 0 : leave === "all" ? 1 : leave;
+        const rootMargin = (_c = vpOptions.margin) != null ? _c : "0px";
+        const root = (_e = (_d = vpOptions.root) == null ? void 0 : _d.current) != null ? _e : void 0;
+        const thresholdValues = Array.from(
+          /* @__PURE__ */ new Set([0, threshold, leaveThreshold])
+        ).sort((a, b) => a - b);
+        const thresholds = thresholdValues.length === 1 ? thresholdValues[0] : thresholdValues;
+        observerRef.current = new IntersectionObserver(
+          (entries) => {
+            const entry = entries[0];
+            if (!entry) return;
+            const isOnce = vpOptions.once;
+            if (entry.isIntersecting && entry.intersectionRatio >= threshold) {
+              if (isOnce && hasTriggeredOnceRef.current) return;
+              hasTriggeredOnceRef.current = true;
+              setIsInView(true);
+              return;
+            }
+            if (isOnce) return;
+            const shouldLeave = leaveThreshold === 0 ? !entry.isIntersecting : entry.intersectionRatio <= leaveThreshold;
+            if (shouldLeave) {
+              setIsInView(false);
+            }
+          },
+          { threshold: thresholds, rootMargin, root }
+        );
+        observerRef.current.observe(container);
+      }
       return () => {
         isMounted = false;
         if (observerRef.current) {
@@ -173,25 +205,26 @@ var SplitText = forwardRef(
         }
         hasSplitRef.current = false;
       };
-    }, [childElement, autoSplit]);
+    }, [childElement, autoSplit, needsViewport, waitForFonts]);
     useEffect(() => {
       if (!splitResultRef.current) return;
       if (hasRevertedRef.current) return;
-      if (isInView && onInViewRef.current) {
-        const callbackResult = onInViewRef.current(splitResultRef.current);
+      if (isInView && onViewportEnterRef.current) {
+        const callbackResult = onViewportEnterRef.current(
+          splitResultRef.current
+        );
         const promise = normalizeToPromise(callbackResult);
         if (revertOnCompleteRef.current && promise) {
           promise.then(() => {
-            var _a;
+            var _a2;
             if (hasRevertedRef.current) return;
-            (_a = splitResultRef.current) == null ? void 0 : _a.revert();
-            hasRevertedRef.current = true;
+            (_a2 = splitResultRef.current) == null ? void 0 : _a2.revert();
           }).catch(() => {
             console.warn("[fetta] Animation rejected, text not reverted");
           });
         }
       } else if (!isInView && splitResultRef.current) {
-        if (resetOnLeaveRef.current) {
+        if (resetOnViewportLeaveRef.current) {
           const { chars, words, lines } = splitResultRef.current;
           const styles = initialStylesRef.current;
           const classes = initialClassesRef.current;
@@ -206,8 +239,8 @@ var SplitText = forwardRef(
             reapplyInitialClasses(lines, classes.lines);
           }
         }
-        if (onLeaveViewRef.current) {
-          onLeaveViewRef.current(splitResultRef.current);
+        if (onViewportLeaveRef.current) {
+          onViewportLeaveRef.current(splitResultRef.current);
         }
       }
     }, [isInView]);
@@ -215,18 +248,20 @@ var SplitText = forwardRef(
       console.error("SplitText: children must be a single valid React element");
       return null;
     }
-    const clonedChild = cloneElement(children, {
-      ref: childRefCallback
-    });
     const Wrapper = Component;
-    return /* @__PURE__ */ jsx(
+    return createElement(
       Wrapper,
-      {
+      __spreadProps(__spreadValues({
         ref: mergedRef,
+        "data-fetta-auto-split-wrapper": "true"
+      }, wrapperProps), {
         className,
-        style: __spreadValues({ visibility: "hidden", position: "relative" }, userStyle),
-        children: clonedChild
-      }
+        style: __spreadValues({
+          visibility: waitForFonts ? "hidden" : "visible",
+          position: "relative"
+        }, userStyle)
+      }),
+      children
     );
   }
 );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fetta",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "description": "Text splitting library with kerning compensation for animations",
   "type": "module",
   "sideEffects": false,
@@ -13,9 +13,17 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     },
+    "./helpers": {
+      "types": "./dist/helpers.d.ts",
+      "import": "./dist/helpers.js"
+    },
     "./react": {
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js"
+    },
+    "./motion": {
+      "types": "./dist/motion.d.ts",
+      "import": "./dist/motion.js"
     }
   },
   "main": "./dist/index.js",
@@ -33,6 +41,7 @@
     "test": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest run --coverage",
+    "pretest:e2e": "pnpm run build",
     "test:e2e": "playwright test",
     "test:all": "vitest run --coverage && playwright test",
     "size": "size-limit",
@@ -49,14 +58,29 @@
       "path": "dist/react.js",
       "import": "*",
       "ignore": ["react"]
+    },
+    {
+      "name": "Motion",
+      "path": "dist/motion.js",
+      "import": "*",
+      "ignore": ["react", "motion", "motion/react"]
+    },
+    {
+      "name": "Helpers",
+      "path": "dist/helpers.js",
+      "import": "*"
     }
   ],
   "peerDependencies": {
-    "react": ">=18.0.0"
+    "react": ">=18.0.0",
+    "motion": ">=11.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
+    },
+    "motion": {
+      "optional": true
     }
   },
   "devDependencies": {