@vysmo/text-react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maesto LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# @vysmo/text-react
+
+React bindings for [`@vysmo/text`](https://www.npmjs.com/package/@vysmo/text). One `<AnimateText>` component, one hook (`useAnimateText`), 243 presets out of the box.
+
+[Live preset browser + Studio](https://vysmo.com/text) · [Source](https://github.com/vysmodev)
+
+## Install
+
+```bash
+pnpm add @vysmo/text @vysmo/text-react
+```
+
+`react` ≥ 18 is a peer dependency.
+
+## Quick start
+
+```tsx
+import { AnimateText } from "@vysmo/text-react";
+
+export function Hero() {
+  return (
+    <AnimateText as="h1" preset="enter/fade-up">
+      Hello world
+    </AnimateText>
+  );
+}
+```
+
+The component renders a single element (`<span>` by default; override via `as`), and on mount runs `animateText` against it with the props you've passed. Cleanup happens automatically on unmount.
+
+## Tree-shake the catalog
+
+Pass a preset *object* instead of a name and only that preset ships in your bundle:
+
+```tsx
+import { AnimateText } from "@vysmo/text-react";
+import { fadeUp } from "@vysmo/text";
+
+<AnimateText as="h1" preset={fadeUp}>
+  Hello world
+</AnimateText>
+```
+
+The string-name path pulls in the whole 243-preset registry; the object path is byte-for-byte just the preset you imported.
+
+## Custom choreography
+
+Skip the preset and pass `animations` directly:
+
+```tsx
+<AnimateText
+  as="h1"
+  split="character"
+  stagger={28}
+  animations={[
+    { prop: "opacity", from: 0, to: 1, duration: 600, ease: "expo.out" },
+    { prop: "translateY", from: 24, to: 0, duration: 800, ease: "back.out" },
+  ]}
+>
+  Hand-rolled
+</AnimateText>
+```
+
+## Props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `as` | `ElementType` | `"span"` | Tag name for the wrapper element. Pass `"h1"`, `"p"`, etc. for semantic markup. |
+| `children` | `ReactNode` | — | The text content. Strings are simplest; reference changes re-run the animation. |
+| `preset` | `PresetName \| Preset` | — | Preset name (string) or imported preset object (tree-shakable). |
+| `split` | `"character" \| "word" \| "line"` | preset's split, or `"character"` | Split granularity. |
+| `stagger` | `number` | `30` | Milliseconds between consecutive slices starting. |
+| `staggerOrder` | `StaggerOrder` | `"start"` | Order in which slices receive their offset. |
+| `animations` | `TextAnimationSpec[]` | — | Custom specs (used when no `preset` or to override). |
+| `perspective` | `number` | — | Container perspective in px. Required for visible 3D transforms. |
+| `perspectiveOrigin` | `string` | — | Container perspective-origin. |
+| `transformOrigin` | `TransformOrigin` | — | Origin applied to every slice. |
+| `autoPlay` | `boolean` | `true` | Begin playing automatically on mount. |
+| `delay` | `number` | — | Ms before the first play begins. |
+| `repeat` | `number \| "infinite"` | `1` | How many cycles. |
+| `repeatDelay` | `number` | `0` | Delay between cycles when `repeat > 1`. |
+| `onComplete` | `() => void` | — | Fires when the choreography finishes naturally (won't fire while looping). |
+| `className` | `string` | — | Forwarded to the wrapper element. |
+| `style` | `CSSProperties` | — | Forwarded to the wrapper element. |
+
+## Replay on the same props
+
+Re-run an animation that's already played using a `key` prop:
+
+```tsx
+<AnimateText key={replayCount} preset="emphasis/pulse">
+  Important
+</AnimateText>
+```
+
+Bumping the key fully remounts the component, so the animation runs again.
+
+## Hook (advanced)
+
+When you can't wrap the JSX (Markdown-rendered headings, MDX, third-party components), animate an external ref:
+
+```tsx
+import { useRef } from "react";
+import { useAnimateText } from "@vysmo/text-react";
+
+function MyHeading({ children }) {
+  const ref = useRef<HTMLHeadingElement>(null);
+  useAnimateText(ref, { preset: "enter/fade-up" });
+  return <h1 ref={ref}>{children}</h1>;
+}
+```
+
+## SSR
+
+The wrapper is SSR-safe: `useEffect` bodies don't run on the server, and the module body itself doesn't touch `window` / `document`. Server renders the wrapping element with its raw text; client mounts the animation.
+
+## License
+
+MIT.

package/dist/AnimateText.d.ts

@@ -0,0 +1,50 @@
+import type { CSSProperties, ElementType, ReactElement, ReactNode } from "react";
+import { type Preset, type PresetName, type SplitMode, type StaggerOrder, type TextAnimationSpec, type TransformOrigin } from "@vysmo/text";
+export interface AnimateTextProps {
+    /** Element to render. Default `"span"`. Pass `"h1"` etc. for semantic headings. */
+    as?: ElementType;
+    /** The text content. Strings work best; complex children re-run the animation when reference changes. */
+    children: ReactNode;
+    /** Preset name (e.g. `"enter/fade-up"`) or imported preset object (tree-shakable). */
+    preset?: PresetName | Preset;
+    /** Split granularity. Defaults to the preset's split, or `"character"`. */
+    split?: SplitMode;
+    /** Milliseconds between consecutive slices starting. Default `30`. */
+    stagger?: number;
+    /** Order in which slices receive their stagger offset. */
+    staggerOrder?: StaggerOrder;
+    /** Custom animation specs (used when no `preset` is set, or to override). */
+    animations?: TextAnimationSpec[];
+    /** Container `perspective` in px. Required for visible 3D transforms. */
+    perspective?: number;
+    /** Container `perspective-origin`. */
+    perspectiveOrigin?: string;
+    /** Transform origin applied to every slice. */
+    transformOrigin?: TransformOrigin;
+    /** Begin playing automatically on mount. Default `true`. */
+    autoPlay?: boolean;
+    /** Delay before the first play begins, in ms. */
+    delay?: number;
+    /** How many cycles. `1` (default), `n > 1`, or `"infinite"`. */
+    repeat?: number | "infinite";
+    /** Delay between successive cycles when `repeat > 1`. */
+    repeatDelay?: number;
+    /** Fires when the choreography finishes naturally (won't fire while looping). */
+    onComplete?: () => void;
+    /** Forwarded to the wrapper element. */
+    className?: string;
+    /** Forwarded to the wrapper element. */
+    style?: CSSProperties;
+}
+/**
+ * React wrapper around `@vysmo/text`'s `animateText`. Renders a single
+ * element (default `<span>`, override via `as`), and on mount calls
+ * `animateText` against the element with the props you've passed.
+ *
+ * On unmount the handle is `.stop()`-ed, restoring un-animated styles
+ * before React removes the DOM. Re-animation happens on prop changes
+ * (preset / stagger / repeat / etc.); for explicit replay on the same
+ * props, change a `key` prop to fully remount.
+ */
+export declare function AnimateText({ as, children, preset, split, stagger, staggerOrder, animations, perspective, perspectiveOrigin, transformOrigin, autoPlay, delay, repeat, repeatDelay, onComplete, className, style, }: AnimateTextProps): ReactElement;
+//# sourceMappingURL=AnimateText.d.ts.map

package/dist/AnimateText.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimateText.d.ts","sourceRoot":"","sources":["../src/AnimateText.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACjF,OAAO,EAIL,KAAK,MAAM,EACX,KAAK,UAAU,EACf,KAAK,SAAS,EACd,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,gBAAgB;IAC/B,mFAAmF;IACnF,EAAE,CAAC,EAAE,WAAW,CAAC;IACjB,yGAAyG;IACzG,QAAQ,EAAE,SAAS,CAAC;IACpB,sFAAsF;IACtF,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,CAAC;IAC7B,2EAA2E;IAC3E,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,6EAA6E;IAC7E,UAAU,CAAC,EAAE,iBAAiB,EAAE,CAAC;IACjC,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,+CAA+C;IAC/C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,iDAAiD;IACjD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,UAAU,CAAC,EAAE,MAAM,IAAI,CAAC;IACxB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,EAC1B,EAAW,EACX,QAAQ,EACR,MAAM,EACN,KAAK,EACL,OAAO,EACP,YAAY,EACZ,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,KAAK,EACL,MAAM,EACN,WAAW,EACX,UAAU,EACV,SAAS,EACT,KAAK,GACN,EAAE,gBAAgB,GAAG,YAAY,CAwDjC"}

package/dist/AnimateText.js

@@ -0,0 +1,77 @@
+"use client";
+import { createElement, useEffect, useRef } from "react";
+import { animateText, } from "@vysmo/text";
+/**
+ * React wrapper around `@vysmo/text`'s `animateText`. Renders a single
+ * element (default `<span>`, override via `as`), and on mount calls
+ * `animateText` against the element with the props you've passed.
+ *
+ * On unmount the handle is `.stop()`-ed, restoring un-animated styles
+ * before React removes the DOM. Re-animation happens on prop changes
+ * (preset / stagger / repeat / etc.); for explicit replay on the same
+ * props, change a `key` prop to fully remount.
+ */
+export function AnimateText({ as = "span", children, preset, split, stagger, staggerOrder, animations, perspective, perspectiveOrigin, transformOrigin, autoPlay, delay, repeat, repeatDelay, onComplete, className, style, }) {
+    const ref = useRef(null);
+    const handleRef = useRef(null);
+    // Stash the callback so its identity changing doesn't re-run the animation.
+    const onCompleteRef = useRef(onComplete);
+    onCompleteRef.current = onComplete;
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const opts = {};
+        if (preset !== undefined)
+            opts.preset = preset;
+        if (split !== undefined)
+            opts.split = split;
+        if (stagger !== undefined)
+            opts.stagger = stagger;
+        if (staggerOrder !== undefined)
+            opts.staggerOrder = staggerOrder;
+        if (animations !== undefined)
+            opts.animations = animations;
+        if (perspective !== undefined)
+            opts.perspective = perspective;
+        if (perspectiveOrigin !== undefined)
+            opts.perspectiveOrigin = perspectiveOrigin;
+        if (transformOrigin !== undefined)
+            opts.transformOrigin = transformOrigin;
+        if (autoPlay !== undefined)
+            opts.autoPlay = autoPlay;
+        if (delay !== undefined)
+            opts.delay = delay;
+        if (repeat !== undefined)
+            opts.repeat = repeat;
+        if (repeatDelay !== undefined)
+            opts.repeatDelay = repeatDelay;
+        const handle = animateText(el, opts);
+        handleRef.current = handle;
+        handle.finished
+            .then(() => onCompleteRef.current?.())
+            .catch(() => {
+            /* stopped — expected */
+        });
+        return () => {
+            handle.stop();
+            handleRef.current = null;
+        };
+    }, [
+        children,
+        preset,
+        split,
+        stagger,
+        staggerOrder,
+        animations,
+        perspective,
+        perspectiveOrigin,
+        transformOrigin,
+        autoPlay,
+        delay,
+        repeat,
+        repeatDelay,
+    ]);
+    return createElement(as, { ref, className, style }, children);
+}
+//# sourceMappingURL=AnimateText.js.map

package/dist/AnimateText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnimateText.js","sourceRoot":"","sources":["../src/AnimateText.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAEzD,OAAO,EACL,WAAW,GASZ,MAAM,aAAa,CAAC;AAuCrB;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,EAC1B,EAAE,GAAG,MAAM,EACX,QAAQ,EACR,MAAM,EACN,KAAK,EACL,OAAO,EACP,YAAY,EACZ,UAAU,EACV,WAAW,EACX,iBAAiB,EACjB,eAAe,EACf,QAAQ,EACR,KAAK,EACL,MAAM,EACN,WAAW,EACX,UAAU,EACV,SAAS,EACT,KAAK,GACY;IACjB,MAAM,GAAG,GAAG,MAAM,CAAqB,IAAI,CAAC,CAAC;IAC7C,MAAM,SAAS,GAAG,MAAM,CAA2B,IAAI,CAAC,CAAC;IAEzD,4EAA4E;IAC5E,MAAM,aAAa,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC;IACzC,aAAa,CAAC,OAAO,GAAG,UAAU,CAAC;IAEnC,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC;QACvB,IAAI,CAAC,EAAE;YAAE,OAAO;QAEhB,MAAM,IAAI,GAAuB,EAAE,CAAC;QACpC,IAAI,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAC/C,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAC5C,IAAI,OAAO,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;QAClD,IAAI,YAAY,KAAK,SAAS;YAAE,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;QACjE,IAAI,UAAU,KAAK,SAAS;YAAE,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC3D,IAAI,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAC9D,IAAI,iBAAiB,KAAK,SAAS;YAAE,IAAI,CAAC,iBAAiB,GAAG,iBAAiB,CAAC;QAChF,IAAI,eAAe,KAAK,SAAS;YAAE,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QAC1E,IAAI,QAAQ,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACrD,IAAI,KAAK,KAAK,SAAS;YAAE,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QAC5C,IAAI,MAAM,KAAK,SAAS;YAAE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QAC/C,IAAI,WAAW,KAAK,SAAS;YAAE,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;QAE9D,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;QACrC,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC;QAE3B,MAAM,CAAC,QAAQ;aACZ,IAAI,CAAC,GAAG,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,EAAE,CAAC;aACrC,KAAK,CAAC,GAAG,EAAE;YACV,wBAAwB;QAC1B,CAAC,CAAC,CAAC;QAEL,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,IAAI,EAAE,CAAC;YACd,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;QAC3B,CAAC,CAAC;IACJ,CAAC,EAAE;QACD,QAAQ;QACR,MAAM;QACN,KAAK;QACL,OAAO;QACP,YAAY;QACZ,UAAU;QACV,WAAW;QACX,iBAAiB;QACjB,eAAe;QACf,QAAQ;QACR,KAAK;QACL,MAAM;QACN,WAAW;KACZ,CAAC,CAAC;IAEH,OAAO,aAAa,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,QAAQ,CAAC,CAAC;AAChE,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { AnimateText, type AnimateTextProps } from "./AnimateText.js";
+export { useAnimateText } from "./use-animate-text.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { AnimateText } from "./AnimateText.js";
+export { useAnimateText } from "./use-animate-text.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAyB,MAAM,kBAAkB,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/use-animate-text.d.ts

@@ -0,0 +1,14 @@
+import type { RefObject } from "react";
+import { type AnimateTextOptions } from "@vysmo/text";
+/**
+ * Run `animateText` against an element you mount yourself. Handy when
+ * you can't use the `<AnimateText>` wrapper because the element is
+ * structurally part of something else (a Markdown-rendered heading, a
+ * MDX block, a third-party component) — `useAnimateText(ref, options)`
+ * lets you animate it without owning the JSX.
+ *
+ * The handle is created on mount, re-created when any option changes,
+ * and `.stop()`-ed on unmount.
+ */
+export declare function useAnimateText(ref: RefObject<HTMLElement | null>, options: AnimateTextOptions): void;
+//# sourceMappingURL=use-animate-text.d.ts.map

package/dist/use-animate-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-animate-text.d.ts","sourceRoot":"","sources":["../src/use-animate-text.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,aAAa,CAAC;AAErB;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EAClC,OAAO,EAAE,kBAAkB,GAC1B,IAAI,CAiBN"}

package/dist/use-animate-text.js

@@ -0,0 +1,32 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { animateText, } from "@vysmo/text";
+/**
+ * Run `animateText` against an element you mount yourself. Handy when
+ * you can't use the `<AnimateText>` wrapper because the element is
+ * structurally part of something else (a Markdown-rendered heading, a
+ * MDX block, a third-party component) — `useAnimateText(ref, options)`
+ * lets you animate it without owning the JSX.
+ *
+ * The handle is created on mount, re-created when any option changes,
+ * and `.stop()`-ed on unmount.
+ */
+export function useAnimateText(ref, options) {
+    const handleRef = useRef(null);
+    useEffect(() => {
+        const el = ref.current;
+        if (!el)
+            return;
+        const handle = animateText(el, options);
+        handleRef.current = handle;
+        return () => {
+            handle.stop();
+            handleRef.current = null;
+        };
+        // We deliberately depend on the whole options object — callers
+        // memoize when they want stability. Same contract as the rest of
+        // React's "options object" hooks (e.g. `useQuery`).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [ref, options]);
+}
+//# sourceMappingURL=use-animate-text.js.map

package/dist/use-animate-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-animate-text.js","sourceRoot":"","sources":["../src/use-animate-text.ts"],"names":[],"mappings":"AAAA,YAAY,CAAC;AAEb,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAE1C,OAAO,EACL,WAAW,GAGZ,MAAM,aAAa,CAAC;AAErB;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAkC,EAClC,OAA2B;IAE3B,MAAM,SAAS,GAAG,MAAM,CAA2B,IAAI,CAAC,CAAC;IAEzD,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,EAAE,GAAG,GAAG,CAAC,OAAO,CAAC;QACvB,IAAI,CAAC,EAAE;YAAE,OAAO;QAChB,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACxC,SAAS,CAAC,OAAO,GAAG,MAAM,CAAC;QAC3B,OAAO,GAAG,EAAE;YACV,MAAM,CAAC,IAAI,EAAE,CAAC;YACd,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC;QAC3B,CAAC,CAAC;QACF,+DAA+D;QAC/D,iEAAiE;QACjE,oDAAoD;QACpD,uDAAuD;IACzD,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC;AACrB,CAAC"}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vysmo/text-react",
+  "version": "0.1.0",
+  "description": "React bindings for @vysmo/text — an <AnimateText> component that drives splitText + animateText with declarative props (preset, split, stagger, repeat, etc.) and a hook for advanced cases.",
+  "license": "MIT",
+  "keywords": [
+    "react",
+    "text",
+    "animation",
+    "split-text",
+    "vysmo"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./src/index.ts",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "@vysmo/text": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitest/browser": "^3.2.4",
+    "playwright": "^1.59.1",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@vysmo/text": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json",
+    "test": "vitest run && vitest run --config vitest.ssr.config.ts",
+    "test:browser": "vitest run",
+    "test:ssr": "vitest run --config vitest.ssr.config.ts",
+    "test:watch": "vitest"
+  }
+}

package/src/AnimateText.tsx

@@ -0,0 +1,138 @@
+"use client";
+
+import { createElement, useEffect, useRef } from "react";
+import type { CSSProperties, ElementType, ReactElement, ReactNode } from "react";
+import {
+  animateText,
+  type AnimateTextHandle,
+  type AnimateTextOptions,
+  type Preset,
+  type PresetName,
+  type SplitMode,
+  type StaggerOrder,
+  type TextAnimationSpec,
+  type TransformOrigin,
+} from "@vysmo/text";
+
+export interface AnimateTextProps {
+  /** Element to render. Default `"span"`. Pass `"h1"` etc. for semantic headings. */
+  as?: ElementType;
+  /** The text content. Strings work best; complex children re-run the animation when reference changes. */
+  children: ReactNode;
+  /** Preset name (e.g. `"enter/fade-up"`) or imported preset object (tree-shakable). */
+  preset?: PresetName | Preset;
+  /** Split granularity. Defaults to the preset's split, or `"character"`. */
+  split?: SplitMode;
+  /** Milliseconds between consecutive slices starting. Default `30`. */
+  stagger?: number;
+  /** Order in which slices receive their stagger offset. */
+  staggerOrder?: StaggerOrder;
+  /** Custom animation specs (used when no `preset` is set, or to override). */
+  animations?: TextAnimationSpec[];
+  /** Container `perspective` in px. Required for visible 3D transforms. */
+  perspective?: number;
+  /** Container `perspective-origin`. */
+  perspectiveOrigin?: string;
+  /** Transform origin applied to every slice. */
+  transformOrigin?: TransformOrigin;
+  /** Begin playing automatically on mount. Default `true`. */
+  autoPlay?: boolean;
+  /** Delay before the first play begins, in ms. */
+  delay?: number;
+  /** How many cycles. `1` (default), `n > 1`, or `"infinite"`. */
+  repeat?: number | "infinite";
+  /** Delay between successive cycles when `repeat > 1`. */
+  repeatDelay?: number;
+  /** Fires when the choreography finishes naturally (won't fire while looping). */
+  onComplete?: () => void;
+  /** Forwarded to the wrapper element. */
+  className?: string;
+  /** Forwarded to the wrapper element. */
+  style?: CSSProperties;
+}
+
+/**
+ * React wrapper around `@vysmo/text`'s `animateText`. Renders a single
+ * element (default `<span>`, override via `as`), and on mount calls
+ * `animateText` against the element with the props you've passed.
+ *
+ * On unmount the handle is `.stop()`-ed, restoring un-animated styles
+ * before React removes the DOM. Re-animation happens on prop changes
+ * (preset / stagger / repeat / etc.); for explicit replay on the same
+ * props, change a `key` prop to fully remount.
+ */
+export function AnimateText({
+  as = "span",
+  children,
+  preset,
+  split,
+  stagger,
+  staggerOrder,
+  animations,
+  perspective,
+  perspectiveOrigin,
+  transformOrigin,
+  autoPlay,
+  delay,
+  repeat,
+  repeatDelay,
+  onComplete,
+  className,
+  style,
+}: AnimateTextProps): ReactElement {
+  const ref = useRef<HTMLElement | null>(null);
+  const handleRef = useRef<AnimateTextHandle | null>(null);
+
+  // Stash the callback so its identity changing doesn't re-run the animation.
+  const onCompleteRef = useRef(onComplete);
+  onCompleteRef.current = onComplete;
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    const opts: AnimateTextOptions = {};
+    if (preset !== undefined) opts.preset = preset;
+    if (split !== undefined) opts.split = split;
+    if (stagger !== undefined) opts.stagger = stagger;
+    if (staggerOrder !== undefined) opts.staggerOrder = staggerOrder;
+    if (animations !== undefined) opts.animations = animations;
+    if (perspective !== undefined) opts.perspective = perspective;
+    if (perspectiveOrigin !== undefined) opts.perspectiveOrigin = perspectiveOrigin;
+    if (transformOrigin !== undefined) opts.transformOrigin = transformOrigin;
+    if (autoPlay !== undefined) opts.autoPlay = autoPlay;
+    if (delay !== undefined) opts.delay = delay;
+    if (repeat !== undefined) opts.repeat = repeat;
+    if (repeatDelay !== undefined) opts.repeatDelay = repeatDelay;
+
+    const handle = animateText(el, opts);
+    handleRef.current = handle;
+
+    handle.finished
+      .then(() => onCompleteRef.current?.())
+      .catch(() => {
+        /* stopped — expected */
+      });
+
+    return () => {
+      handle.stop();
+      handleRef.current = null;
+    };
+  }, [
+    children,
+    preset,
+    split,
+    stagger,
+    staggerOrder,
+    animations,
+    perspective,
+    perspectiveOrigin,
+    transformOrigin,
+    autoPlay,
+    delay,
+    repeat,
+    repeatDelay,
+  ]);
+
+  return createElement(as, { ref, className, style }, children);
+}

package/src/__tests__/AnimateText.test.tsx

@@ -0,0 +1,113 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createRoot, type Root } from "react-dom/client";
+import { act } from "react";
+import { AnimateText } from "../AnimateText.js";
+
+(globalThis as unknown as { IS_REACT_ACT_ENVIRONMENT: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+describe("<AnimateText>", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    await act(async () => {
+      root.unmount();
+    });
+    container.remove();
+  });
+
+  it("renders children inside a span by default", async () => {
+    await act(async () => {
+      root.render(<AnimateText preset="enter/fade-up">Hello world</AnimateText>);
+    });
+    const span = container.querySelector("span");
+    expect(span).toBeTruthy();
+    // animateText splits the text into per-slice spans + appends a
+    // hidden screen-reader copy. Both contain the full text, so
+    // textContent doubles — verify via the SR copy attribute instead.
+    const sr = span!.querySelector("[data-text-sr]");
+    expect(sr?.textContent).toBe("Hello world");
+  });
+
+  it("renders as a different tag when `as` is set", async () => {
+    await act(async () => {
+      root.render(
+        <AnimateText as="h1" preset="enter/fade-up">
+          Headline
+        </AnimateText>,
+      );
+    });
+    const h1 = container.querySelector("h1");
+    expect(h1).toBeTruthy();
+    const sr = h1!.querySelector("[data-text-sr]");
+    expect(sr?.textContent).toBe("Headline");
+  });
+
+  it("forwards className and style", async () => {
+    await act(async () => {
+      root.render(
+        <AnimateText
+          preset="enter/fade-up"
+          className="test-class"
+          style={{ color: "red" }}
+        >
+          Styled
+        </AnimateText>,
+      );
+    });
+    const span = container.querySelector("span")!;
+    expect(span.className).toBe("test-class");
+    expect(span.style.color).toBe("red");
+  });
+
+  it("splits the text into slices via animateText", async () => {
+    await act(async () => {
+      root.render(
+        <AnimateText preset="enter/fade-up" split="character">
+          Hi
+        </AnimateText>,
+      );
+    });
+    // animateText splits the text into per-character spans wrapped in
+    // word containers — both root and inner spans use data attributes.
+    const span = container.querySelector("span")!;
+    const slices = span.querySelectorAll("[data-text-slice]");
+    expect(slices.length).toBeGreaterThan(0);
+  });
+
+  it("calls onComplete after the animation finishes", async () => {
+    let completed = false;
+    await act(async () => {
+      root.render(
+        <AnimateText
+          preset="enter/fade-up"
+          onComplete={() => {
+            completed = true;
+          }}
+        >
+          x
+        </AnimateText>,
+      );
+    });
+    // fade-up is sub-second; give it 1.5s to complete.
+    await new Promise((r) => setTimeout(r, 1500));
+    expect(completed).toBe(true);
+  });
+
+  it("stops the handle on unmount without throwing", async () => {
+    await act(async () => {
+      root.render(<AnimateText preset="enter/fade-up">Goodbye</AnimateText>);
+    });
+    await act(async () => {
+      root.unmount();
+    });
+    root = createRoot(container);
+    expect(container.querySelector("span")).toBeNull();
+  });
+});

package/src/__tests__/ssr.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+
+describe("SSR safety", () => {
+  it("window is undefined in this runtime", () => {
+    expect(typeof window).toBe("undefined");
+  });
+
+  it("module loads without DOM globals", async () => {
+    const mod = await import("../index.js");
+    expect(mod).toBeDefined();
+    expect(typeof mod.AnimateText).toBe("function");
+    expect(typeof mod.useAnimateText).toBe("function");
+  });
+});

package/src/index.ts

@@ -0,0 +1,2 @@
+export { AnimateText, type AnimateTextProps } from "./AnimateText.js";
+export { useAnimateText } from "./use-animate-text.js";

package/src/use-animate-text.ts

@@ -0,0 +1,41 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import type { RefObject } from "react";
+import {
+  animateText,
+  type AnimateTextHandle,
+  type AnimateTextOptions,
+} from "@vysmo/text";
+
+/**
+ * Run `animateText` against an element you mount yourself. Handy when
+ * you can't use the `<AnimateText>` wrapper because the element is
+ * structurally part of something else (a Markdown-rendered heading, a
+ * MDX block, a third-party component) — `useAnimateText(ref, options)`
+ * lets you animate it without owning the JSX.
+ *
+ * The handle is created on mount, re-created when any option changes,
+ * and `.stop()`-ed on unmount.
+ */
+export function useAnimateText(
+  ref: RefObject<HTMLElement | null>,
+  options: AnimateTextOptions,
+): void {
+  const handleRef = useRef<AnimateTextHandle | null>(null);
+
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    const handle = animateText(el, options);
+    handleRef.current = handle;
+    return () => {
+      handle.stop();
+      handleRef.current = null;
+    };
+    // We deliberately depend on the whole options object — callers
+    // memoize when they want stability. Same contract as the rest of
+    // React's "options object" hooks (e.g. `useQuery`).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [ref, options]);
+}