fetta 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Custom splitText implementation with built-in kerning compensation.
+ * Measures character positions before splitting, applies compensation,
+ * then detects lines based on actual rendered positions.
+ */
+/**
+ * Configuration options for the splitText function.
+ *
+ * @example
+ * ```typescript
+ * const options: SplitTextOptions = {
+ *   type: "chars,words,lines",
+ *   charClass: "char",
+ *   mask: "lines",
+ *   autoSplit: true,
+ * };
+ * ```
+ */
+interface SplitTextOptions {
+    /** Split type: chars, words, lines, or combinations like "chars,words" */
+    type?: "chars" | "words" | "lines" | "chars,words" | "words,lines" | "chars,lines" | "chars,words,lines";
+    charClass?: string;
+    wordClass?: string;
+    lineClass?: string;
+    /** Apply overflow mask wrapper to elements for reveal animations */
+    mask?: "lines" | "words" | "chars";
+    /** Auto-split on resize (observes parent element) */
+    autoSplit?: boolean;
+    /** Callback when resize triggers re-split (does not re-trigger initial animations) */
+    onResize?: (result: Omit<SplitTextResult, "revert" | "dispose">) => void;
+    /** Callback fired after text is split, receives split elements. Return animation for revertOnComplete. */
+    onSplit?: (result: {
+        chars: HTMLSpanElement[];
+        words: HTMLSpanElement[];
+        lines: HTMLSpanElement[];
+    }) => void | {
+        finished: Promise<unknown>;
+    } | Array<{
+        finished: Promise<unknown>;
+    }> | Promise<unknown>;
+    /** Auto-revert when onSplit animation completes */
+    revertOnComplete?: boolean;
+    /** Add CSS custom properties (--char-index, --word-index, --line-index) */
+    propIndex?: boolean;
+    /** Add will-change: transform, opacity to split elements for better animation performance */
+    willChange?: boolean;
+}
+/**
+ * Result returned by splitText containing arrays of split elements and a revert function.
+ *
+ * Each array contains the created span elements. Empty arrays are returned for
+ * split types not requested (e.g., if `type: "words"`, chars and lines will be empty).
+ */
+interface SplitTextResult {
+    /** Array of character span elements (empty if chars not in type) */
+    chars: HTMLSpanElement[];
+    /** Array of word span elements (empty if words not in type) */
+    words: HTMLSpanElement[];
+    /** Array of line span elements (empty if lines not in type) */
+    lines: HTMLSpanElement[];
+    /** Revert the element to its original HTML and cleanup all observers/timers */
+    revert: () => void;
+}
+/**
+ * Split text into characters, words, and lines with kerning compensation.
+ *
+ * Fetta measures character positions before splitting, then applies margin adjustments
+ * after splitting to preserve the original kerning (letter spacing). This prevents
+ * the visual "jumping" that occurs with naive text splitting.
+ *
+ * @param element - The HTML element containing text to split. Must have text content.
+ * @param options - Configuration options for splitting behavior
+ * @returns Object containing arrays of split elements and a revert function
+ *
+ * @throws {Error} If element is not an HTMLElement
+ *
+ * @example
+ * ```typescript
+ * import { splitText } from "fetta";
+ * import { animate, stagger } from "motion";
+ *
+ * // Basic usage
+ * const { chars, words, lines, revert } = splitText(element);
+ *
+ * // Animate words
+ * animate(words, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.05) });
+ *
+ * // Revert to original HTML when done
+ * revert();
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Auto-revert after animation completes
+ * splitText(element, {
+ *   onSplit: ({ words }) => animate(words, { opacity: [0, 1] }),
+ *   revertOnComplete: true,
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Responsive re-splitting
+ * splitText(element, {
+ *   autoSplit: true,
+ *   onResize: ({ lines }) => {
+ *     // Re-animate after resize
+ *     animate(lines, { opacity: [0, 1] });
+ *   },
+ * });
+ * ```
+ */
+declare function splitText(element: HTMLElement, { type, charClass, wordClass, lineClass, mask, autoSplit, onResize, onSplit, revertOnComplete, propIndex, willChange, }?: SplitTextOptions): SplitTextResult;
+
+export { type SplitTextOptions, type SplitTextResult, splitText };

package/dist/index.js

@@ -0,0 +1 @@
+export { splitText } from './chunk-KGMU2B53.js';

package/dist/react.d.ts

@@ -0,0 +1,121 @@
+import * as react from 'react';
+import { ReactElement } from 'react';
+export { SplitTextOptions, SplitTextResult } from './index.js';
+
+interface SplitTextOptions {
+    type?: "chars" | "words" | "lines" | "chars,words" | "words,lines" | "chars,lines" | "chars,words,lines";
+    charClass?: string;
+    wordClass?: string;
+    lineClass?: string;
+    /** Apply overflow mask wrapper to elements for reveal animations */
+    mask?: "lines" | "words" | "chars";
+    propIndex?: boolean;
+    willChange?: 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;
+    /** Only trigger once. Default: false */
+    once?: boolean;
+}
+/**
+ * Result passed to SplitText callbacks (onSplit, onInView, onLeaveView, onResize).
+ *
+ * Contains arrays of split elements and a revert function for manual control.
+ * Empty arrays are returned for split types not requested in options.
+ */
+interface SplitTextElements {
+    /** Array of character span elements */
+    chars: HTMLSpanElement[];
+    /** Array of word span elements */
+    words: HTMLSpanElement[];
+    /** Array of line span elements */
+    lines: HTMLSpanElement[];
+    /** 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 {
+    children: ReactElement;
+    /**
+     * 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;
+    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;
+}
+/**
+ * React component wrapper for text splitting with kerning compensation.
+ *
+ * Wraps a single child element and splits its text content into characters,
+ * words, and/or lines. Handles lifecycle cleanup automatically on unmount.
+ *
+ * @param props - Component props including callbacks and options
+ * @returns The child element wrapped in a container div
+ *
+ * @example
+ * ```tsx
+ * import { SplitText } from "fetta/react";
+ * import { animate, stagger } from "motion";
+ *
+ * // Basic animation
+ * <SplitText
+ *   onSplit={({ words }) => {
+ *     animate(words, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.05) });
+ *   }}
+ * >
+ *   <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<HTMLDivElement>>;
+
+export { SplitText, type SplitTextElements };

package/dist/react.js

@@ -0,0 +1,181 @@
+import { splitText, __spreadProps, __spreadValues, normalizeToPromise } from './chunk-KGMU2B53.js';
+import { forwardRef, useRef, useCallback, useState, useLayoutEffect, useEffect, isValidElement, cloneElement } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+var SplitText = forwardRef(
+  function SplitText2({
+    children,
+    onSplit,
+    onResize,
+    options,
+    autoSplit = false,
+    revertOnComplete = false,
+    inView,
+    onInView,
+    onLeaveView
+  }, forwardedRef) {
+    const containerRef = useRef(null);
+    const mergedRef = useCallback(
+      (node) => {
+        containerRef.current = node;
+        if (typeof forwardedRef === "function") {
+          forwardedRef(node);
+        } else if (forwardedRef) {
+          forwardedRef.current = node;
+        }
+      },
+      [forwardedRef]
+    );
+    const [childElement, setChildElement] = useState(null);
+    const [isInView, setIsInView] = useState(false);
+    const onSplitRef = useRef(onSplit);
+    const onResizeRef = useRef(onResize);
+    const optionsRef = useRef(options);
+    const revertOnCompleteRef = useRef(revertOnComplete);
+    const inViewRef = useRef(inView);
+    const onInViewRef = useRef(onInView);
+    const onLeaveViewRef = useRef(onLeaveView);
+    useLayoutEffect(() => {
+      onSplitRef.current = onSplit;
+      onResizeRef.current = onResize;
+      optionsRef.current = options;
+      revertOnCompleteRef.current = revertOnComplete;
+      inViewRef.current = inView;
+      onInViewRef.current = onInView;
+      onLeaveViewRef.current = onLeaveView;
+    });
+    const hasSplitRef = useRef(false);
+    const hasRevertedRef = useRef(false);
+    const revertFnRef = useRef(null);
+    const splitResultRef = useRef(null);
+    const observerRef = useRef(null);
+    const hasTriggeredOnceRef = useRef(false);
+    const childRefCallback = useCallback((node) => {
+      setChildElement(node);
+    }, []);
+    useEffect(() => {
+      if (!childElement) return;
+      if (hasSplitRef.current) return;
+      let isMounted = true;
+      document.fonts.ready.then(() => {
+        var _a, _b;
+        if (!isMounted || hasSplitRef.current) return;
+        if (!containerRef.current) return;
+        const result = splitText(childElement, __spreadProps(__spreadValues({}, optionsRef.current), {
+          autoSplit,
+          onResize: (resizeResult) => {
+            var _a2;
+            const newSplitTextElements = {
+              chars: resizeResult.chars,
+              words: resizeResult.words,
+              lines: resizeResult.lines,
+              revert: result.revert
+            };
+            splitResultRef.current = newSplitTextElements;
+            (_a2 = onResizeRef.current) == null ? void 0 : _a2.call(onResizeRef, newSplitTextElements);
+          }
+        }));
+        revertFnRef.current = result.revert;
+        hasSplitRef.current = true;
+        const splitElements = {
+          chars: result.chars,
+          words: result.words,
+          lines: result.lines,
+          revert: result.revert
+        };
+        splitResultRef.current = splitElements;
+        containerRef.current.style.visibility = "visible";
+        if (onSplitRef.current) {
+          const callbackResult = onSplitRef.current(splitElements);
+          if (!inViewRef.current && revertOnCompleteRef.current) {
+            const promise = normalizeToPromise(callbackResult);
+            if (promise) {
+              promise.then(() => {
+                if (!isMounted || hasRevertedRef.current) return;
+                result.revert();
+                hasRevertedRef.current = true;
+              }).catch(() => {
+                console.warn("[fetta] Animation rejected, text not reverted");
+              });
+            } else if (callbackResult === void 0) ; else {
+              console.warn(
+                "SplitText: revertOnComplete is enabled but onSplit did not return an animation or promise."
+              );
+            }
+          }
+        }
+        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";
+          observerRef.current = new IntersectionObserver(
+            (entries) => {
+              const entry = entries[0];
+              if (!entry) return;
+              const isOnce = typeof inViewRef.current === "object" && inViewRef.current.once;
+              if (entry.isIntersecting) {
+                if (isOnce && hasTriggeredOnceRef.current) return;
+                hasTriggeredOnceRef.current = true;
+                setIsInView(true);
+              } else {
+                if (!isOnce) {
+                  setIsInView(false);
+                }
+              }
+            },
+            { threshold, rootMargin }
+          );
+          observerRef.current.observe(containerRef.current);
+        }
+      });
+      return () => {
+        isMounted = false;
+        if (observerRef.current) {
+          observerRef.current.disconnect();
+          observerRef.current = null;
+        }
+        if (revertFnRef.current) {
+          revertFnRef.current();
+        }
+        hasSplitRef.current = false;
+      };
+    }, [childElement, autoSplit]);
+    useEffect(() => {
+      if (!splitResultRef.current) return;
+      if (hasRevertedRef.current) return;
+      if (isInView && onInViewRef.current) {
+        const callbackResult = onInViewRef.current(splitResultRef.current);
+        const promise = normalizeToPromise(callbackResult);
+        if (revertOnCompleteRef.current && promise) {
+          promise.then(() => {
+            var _a;
+            if (hasRevertedRef.current) return;
+            (_a = splitResultRef.current) == null ? void 0 : _a.revert();
+            hasRevertedRef.current = true;
+          }).catch(() => {
+            console.warn("[fetta] Animation rejected, text not reverted");
+          });
+        }
+      } else if (!isInView && onLeaveViewRef.current && splitResultRef.current) {
+        onLeaveViewRef.current(splitResultRef.current);
+      }
+    }, [isInView]);
+    if (!isValidElement(children)) {
+      console.error("SplitText: children must be a single valid React element");
+      return null;
+    }
+    const clonedChild = cloneElement(children, {
+      ref: childRefCallback
+    });
+    return /* @__PURE__ */ jsx(
+      "div",
+      {
+        ref: mergedRef,
+        style: { visibility: "hidden", position: "relative" },
+        children: clonedChild
+      }
+    );
+  }
+);
+
+export { SplitText };

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "fetta",
+  "version": "1.0.0",
+  "description": "Text splitting library with kerning compensation for animations",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./core": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "pnpm run build",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "playwright test",
+    "test:all": "vitest run --coverage && playwright test"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.49.0",
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^19",
+    "@vitest/coverage-v8": "^2.1.8",
+    "@vitest/ui": "^2.1.8",
+    "jsdom": "^25.0.1",
+    "react": "^19.2.3",
+    "react-dom": "^19.0.0",
+    "serve": "^14.2.4",
+    "tsup": "^8.0.0",
+    "typescript": "^5",
+    "vitest": "^2.1.8"
+  },
+  "keywords": [
+    "text",
+    "split",
+    "animation",
+    "motion",
+    "kerning",
+    "typography",
+    "gsap"
+  ],
+  "license": "MIT",
+  "author": "dimi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dimicx/fetta.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dimicx/fetta/issues"
+  },
+  "homepage": "https://fetta.dimi.me",
+  "publishConfig": {
+    "access": "public"
+  }
+}