fetta 1.4.4 → 1.5.0

package/README.md

@@ -17,7 +17,7 @@ Split text into characters, words, and lines while preserving the original typog
 - **Accessible** — Automatic screen reader support, even when splitting text with nested links or emphasis
 - **TypeScript** — Full type definitions included
 - **React Component** — Declarative wrapper for React projects
-- **Built-in InView** — Viewport detection for scroll-triggered animations in React
+- **Built-in Viewport** — Viewport detection for scroll-triggered animations in React
 - **Library Agnostic** — Works with Motion, GSAP, or any animation library
 
 ## Installation
@@ -26,7 +26,10 @@ Split text into characters, words, and lines while preserving the original typog
 npm install fetta
 ```
 
-**Bundle size**: ~3.9 kB (`fetta/core`) / ~4.8 kB (`fetta/react`) — minified + compressed
+**Bundle size** (minified + brotli)
+- `fetta`: ~5.4 kB
+- `fetta/react`: ~6.7 kB
+- `fetta/motion`: ~11.2 kB
 
 ## Quick Start
 
@@ -83,13 +86,13 @@ const result = splitText(element, options);
 | `lineClass` | `string` | `"split-line"` | CSS class for line elements |
 | `mask` | `string` | — | Wrap elements in `overflow: clip` container: `"chars"`, `"words"`, or `"lines"` |
 | `autoSplit` | `boolean` | `false` | Re-split on container resize |
-| `onResize` | `function` | — | Callback after resize re-split |
-| `onSplit` | `function` | — | Callback after initial split |
+| `onResplit` | `function` | — | Callback after autoSplit/full-resplit replaces split output elements |
+| `onSplit` | `function` | — | Callback after initial split. Return animation/promise for `revertOnComplete` |
 | `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. Values can be objects or `(el, index) => object` functions |
-| `initialClasses` | `object` | — | Apply initial CSS classes to chars/words/lines after split. Values can be strings or `(el, index) => string` functions |
+| `initialClasses` | `object` | — | Apply initial CSS classes to chars/words/lines. Values are strings |
 
 #### Return Value
 
@@ -102,13 +105,57 @@ const result = splitText(element, options);
 }
 ```
 
+### `createSplitClones(splitResult, options)` (`fetta/helpers`)
+
+Builds swap/reveal DOM layers (clones + optional wrappers) without coupling to any animation library.
+
+```ts
+import { splitText } from "fetta";
+import { createSplitClones } from "fetta/helpers";
+
+const split = splitText(element, { type: "chars", mask: "chars" });
+const layers = createSplitClones(split, { unit: "chars", wrap: true });
+
+// Animate with Motion, GSAP, WAAPI, or CSS
+// ...
+
+layers.cleanup(); // removes clones/wrappers, keeps split DOM
+// layers.cleanup({ revertSplit: true }) // also calls split.revert()
+```
+
+#### Behavior
+
+- Clone is always appended to the **current parent** of the original split node.
+- `wrap: false` (default): clone is appended to existing parent (often the mask wrapper).
+- `wrap: true`: original is first moved into a track wrapper, then clone is appended there.
+- Helper never calls `splitText` and never performs animation.
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `unit` | `"chars" \| "words" \| "lines"` | — | Which split nodes to layer |
+| `wrap` | `boolean` | `false` | Wrap each original in a track wrapper (`position: relative`) |
+| `display` | `"auto" \| "inline-block" \| "block"` | `"auto"` | Track display when `wrap: true` (`lines` => `block`, others => `inline-block`) |
+| `cloneOffset.axis` | `"x" \| "y"` | `"y"` | Axis used for initial clone offset |
+| `cloneOffset.direction` | `"start" \| "end"` | `"start"` | Offset direction (`start` => negative) |
+| `cloneOffset.distance` | `string` | `"100%"` | Offset distance |
+| `trackClassName` / `cloneClassName` | `string \| (ctx) => string` | — | Class names (static or per-item) |
+| `trackStyle` / `cloneStyle` | `object \| (ctx) => object` | — | Inline styles (static or per-item) |
+
+For reveal/swap effects, use matching `mask` in `splitText` (`"chars"`, `"words"`, or `"lines"`).
+
 ### `<SplitText>` (React)
 
 ```tsx
 import { SplitText } from 'fetta/react';
 ```
 
-#### Props
+`fetta/react` forwards common wrapper DOM props (`id`, `role`, `tabIndex`, `aria-*`, `data-*`, and event handlers like `onClick`) to the wrapper element.
+
+`fetta/react` props:
+
+#### React Props
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
@@ -117,21 +164,35 @@ import { SplitText } from 'fetta/react';
 | `className` | `string` | — | Class name for wrapper element |
 | `style` | `CSSProperties` | — | Additional styles for wrapper element |
 | `ref` | `Ref<HTMLElement>` | — | Ref to container element |
-| `onSplit` | `(result) => void` | — | Called after text is split |
-| `onResize` | `(result) => void` | — | Called on autoSplit re-split |
-| `options` | `SplitOptions` | — | Split options (type, classes, mask, propIndex, disableKerning) |
+| `onSplit` | `(result) => CallbackReturn` | — | Called after text is split |
+| `onResplit` | `(result) => void` | — | Called when autoSplit/full-resplit replaces split output elements |
+| `options` | `SplitTextOptions` | — | Split options (type, classes, mask, propIndex, disableKerning) |
 | `autoSplit` | `boolean` | `false` | Re-split on container resize |
+| `waitForFonts` | `boolean` | `true` | Wait for `document.fonts.ready` before splitting (recommended for stable kerning). Set `false` for immediate split. |
 | `revertOnComplete` | `boolean` | `false` | Revert after animation completes |
-| `inView` | `boolean \| InViewOptions` | `false` | Enable viewport detection |
-| `onInView` | `(result) => void` | — | Called when element enters viewport |
-| `onLeaveView` | `(result) => void` | — | Called when element leaves viewport |
+| `onRevert` | `() => void` | — | Called when split text is reverted (manual or automatic) |
+| `viewport` | `ViewportOptions` | — | Configure viewport detection |
+| `onViewportEnter` | `(result) => CallbackReturn` | — | Called when element enters viewport |
+| `onViewportLeave` | `(result) => CallbackReturn` | — | Called when element leaves viewport |
 | `initialStyles` | `object` | — | Apply initial inline styles to chars/words/lines. Values can be objects or `(el, index) => object` functions |
-| `initialClasses` | `object` | — | Apply initial CSS classes to chars/words/lines. Values can be strings or `(el, index) => string` functions |
-| `resetOnLeave` | `boolean` | `false` | Re-apply initialStyles/initialClasses when leaving viewport |
+| `initialClasses` | `object` | — | Apply initial CSS classes to chars/words/lines. Values are strings |
+| `resetOnViewportLeave` | `boolean` | `false` | Re-apply initialStyles/initialClasses when leaving viewport |
+
+#### Shared `SplitTextOptions` (`options` prop)
+
+| Option | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `SplitType` | `"chars,words,lines"` | What to split: `"chars"`, `"words"`, `"lines"`, or combinations |
+| `charClass` | `string` | `"split-char"` | CSS class for character spans |
+| `wordClass` | `string` | `"split-word"` | CSS class for word spans |
+| `lineClass` | `string` | `"split-line"` | CSS class for line spans |
+| `mask` | `"lines" \| "words" \| "chars"` | — | Wrap elements in `overflow: clip` mask containers |
+| `propIndex` | `boolean` | `false` | Add CSS index variables (`--char-index`, `--word-index`, `--line-index`) |
+| `disableKerning` | `boolean` | `false` | Skip kerning compensation (no margin adjustments) |
 
 #### Callback Signature
 
-All callbacks (`onSplit`, `onResize`, `onInView`, `onLeaveView`) receive the same result object:
+All callbacks (`onSplit`, `onResplit`, `onViewportEnter`, `onViewportLeave`) receive:
 
 ```ts
 {
@@ -142,16 +203,85 @@ All callbacks (`onSplit`, `onResize`, `onInView`, `onLeaveView`) receive the sam
 }
 ```
 
-#### InView Options
+```ts
+type CallbackReturn =
+  | void
+  | Promise<unknown>
+  | { finished: Promise<unknown> }
+  | { then: (onFulfilled?: ((result: unknown) => unknown) | undefined) => unknown }
+  | CallbackReturn[];
+```
+
+When using `autoSplit` with `lines` in scroll-linked or scroll-triggered animations, re-attach scroll/timeline logic inside `onResplit` so it binds to the new split element references.
+
+`onRevert` is a separate zero-argument callback that fires when a split cycle actually reverts.
+
+#### Viewport Options
 
 ```ts
 {
-  amount?: number;   // How much must be visible (0-1), default: 0
-  margin?: string;   // Root margin, default: "0px"
-  once?: boolean;    // Only trigger once, default: false
+  amount?: number | "some" | "all"; // Enter threshold, default: 0
+  leave?: number | "some" | "all";  // Leave threshold, default: 0
+  margin?: string;                  // Root margin, default: "0px"
+  once?: boolean;                   // Only trigger once, default: false
+  root?: RefObject<Element>;        // Optional root element
 }
 ```
 
+### `<SplitText>` (Motion)
+
+```tsx
+import { SplitText } from "fetta/motion";
+```
+
+`fetta/motion` includes all props from `fetta/react`, plus Motion variant props. It also forwards standard Motion/DOM wrapper props (`id`, `role`, `tabIndex`, `layout`, `drag`, `data-*`, etc.) to the wrapper.
+
+Animate on exit with Motion's `AnimatePresence` (make `SplitText` the direct child):
+
+```tsx
+import { AnimatePresence } from "motion/react";
+
+<AnimatePresence>
+  {isVisible && (
+    <SplitText
+      variants={{
+        enter: { opacity: 1, y: 0 },
+        exit: { opacity: 0, y: 12 },
+      }}
+      initial="enter"
+      animate="enter"
+      exit="exit"
+      options={{ type: "words" }}
+    >
+      <h1>Goodbye</h1>
+    </SplitText>
+  )}
+</AnimatePresence>
+```
+
+#### Motion-only Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variants` | `Record<string, VariantDefinition<TCustom>>` | — | Named variant definitions |
+| `initial` | `string \| VariantDefinition<TCustom> \| false` | — | Initial variant applied instantly after split |
+| `animate` | `string \| VariantDefinition<TCustom>` | — | Base variant |
+| `exit` | `string \| VariantDefinition<TCustom> \| false` | — | Exit variant (AnimatePresence) |
+| `whileInView` | `string \| VariantDefinition<TCustom>` | — | Variant while element is in view |
+| `whileOutOfView` | `string \| VariantDefinition<TCustom>` | — | Variant after element leaves view |
+| `whileScroll` | `string \| VariantDefinition<TCustom>` | — | Scroll-driven variant (highest trigger priority) |
+| `whileHover` | `string \| VariantDefinition<TCustom>` | — | Variant on hover |
+| `whileTap` | `string \| VariantDefinition<TCustom>` | — | Variant on tap/press |
+| `whileFocus` | `string \| VariantDefinition<TCustom>` | — | Variant on focus |
+| `animateOnResplit` | `boolean` | `false` | Replay initial->animate on autoSplit/full-resplit |
+| `scroll` | `{ offset?, axis?, container? }` | — | Scroll tracking options for `whileScroll` |
+| `transition` | `AnimationOptions` | — | Global/default transition for variants |
+| `custom` | `TCustom` | — | Custom data forwarded to function variants |
+| `delayScope` | `"global" \| "local"` | `"global"` | Delay-function index scope (`globalIndex` vs relative `index`) |
+| `reducedMotion` | `"user" \| "always" \| "never"` | — | Reduced-motion behavior for this component |
+| `onHoverStart` | `() => void` | — | Called when hover starts |
+| `onHoverEnd` | `() => void` | — | Called when hover ends |
+
 ## Examples
 
 ### Vanilla JavaScript
@@ -243,7 +373,7 @@ splitText(element, { type: 'chars', propIndex: true });
 </SplitText>
 ```
 
-#### Scroll-Triggered with InView
+#### Scroll-Triggered with Viewport
 
 ```tsx
 <SplitText
@@ -251,11 +381,11 @@ splitText(element, { type: 'chars', propIndex: true });
   initialStyles={{
     words: { opacity: '0', transform: 'translateY(20px)' }
   }}
-  inView={{ amount: 0.5 }}
-  onInView={({ words }) => {
+  viewport={{ amount: 0.5 }}
+  onViewportEnter={({ words }) => {
     animate(words, { opacity: 1, y: 0 }, { delay: stagger(0.03) });
   }}
-  resetOnLeave
+  resetOnViewportLeave
 >
   <p>Animates when scrolled into view</p>
 </SplitText>
@@ -284,7 +414,10 @@ Default classes applied to split elements:
 | `.split-word` | Words | Inline positioning |
 | `.split-line` | Lines | Block display |
 
-Each element also receives a `data-index` attribute with its position.
+Split elements receive typed index attributes:
+- Characters: `data-char-index`
+- Words: `data-word-index`
+- Lines: `data-line-index`
 
 ## Font Loading
 
@@ -297,7 +430,17 @@ document.fonts.ready.then(() => {
 });
 ```
 
-The React component handles this automatically — no additional setup required.
+React and Motion components wait for fonts by default (`waitForFonts={true}`), which gives the most stable kerning.
+
+If you notice a visual shift after splitting, keep the default waiting behavior enabled.
+
+If you need immediate splitting (for example, responsiveness-first UI), you can opt out with `waitForFonts={false}`:
+
+```tsx
+<SplitText waitForFonts={false}>
+  <h1>Split Immediately</h1>
+</SplitText>
+```
 
 ## Accessibility
 
@@ -332,6 +475,7 @@ Pre-existing `aria-label` attributes are always preserved.
 ## Notes
 
 - **Ligatures are disabled** (`font-variant-ligatures: none`) because ligatures cannot span multiple elements.
+- **Authored hard breaks are preserved** — Explicit `<br>` and block-level descendants are treated as hard boundaries. In `chars`/`words` modes, hard boundaries are normalized to `<br>` in the split output.
 
 ## Browser Support
 

package/dist/chunk-FP4I6OR2.js

@@ -0,0 +1,43 @@
+// src/internal/initialStyles.ts
+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 == null) continue;
+      if (key === "cssText") {
+        if (typeof value === "string") {
+          el.style.cssText = value;
+        }
+        continue;
+      }
+      if (typeof value !== "string" && typeof value !== "number") continue;
+      const cssValue = typeof value === "number" ? String(value) : value;
+      const cssKey = key.startsWith("--") ? key : key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+      el.style.setProperty(cssKey, cssValue);
+    }
+  }
+}
+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);
+  }
+}
+
+// src/internal/waitForFontsReady.ts
+async function waitForFontsReady(waitForFonts) {
+  if (!waitForFonts) return;
+  const fonts = document.fonts;
+  const ready = fonts == null ? void 0 : fonts.ready;
+  if (!ready || typeof ready.then !== "function") return;
+  try {
+    await ready;
+  } catch (e) {
+  }
+}
+
+export { reapplyInitialClasses, reapplyInitialStyles, waitForFontsReady };

package/dist/chunk-ORMEWXMH.js

@@ -0,0 +1,33 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
+
+export { __objRest, __spreadProps, __spreadValues };