fetta 1.4.2 → 1.4.4

package/README.md

@@ -6,11 +6,11 @@ Split text into characters, words, and lines while preserving the original typog
 
 ## Features
 
-- **Kerning Compensation** — Measures kerning between character pairs, applies margin adjustments to maintain original spacing
-- **Nested Elements** — Preserves inline HTML elements (`<a>`, `<em>`, `<strong>`, etc.) with all attributes intact
-- **Line Detection** — Detects lines based on Y-position clustering, works with any container width
-- **Dash Handling** — Allows text to wrap naturally after em-dashes, en-dashes, and hyphens
-- **Auto Re-split** — Automatically re-splits on container resize with debouncing
+- **Kerning Compensation** — Maintains original character spacing when splitting by chars
+- **Nested Elements** — Preserves `<a>`, `<em>`, `<strong>` and other inline elements with all attributes
+- **Line Detection** — Automatically groups words into lines
+- **Dash Handling** — Allows text to wrap naturally after em-dashes, en-dashes, hyphens, and slashes
+- **Auto Re-split** — Re-splits on container resize
 - **Auto-Revert** — Restore original HTML after animations
 - **Masking** — Wrap elements in clip containers for reveal animations
 - **Emoji Support** — Properly handles compound emojis and complex Unicode characters
@@ -26,6 +26,8 @@ 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
+
 ## Quick Start
 
 ### Vanilla JavaScript
@@ -79,15 +81,15 @@ const result = splitText(element, options);
 | `charClass` | `string` | `"split-char"` | CSS class for character elements |
 | `wordClass` | `string` | `"split-word"` | CSS class for word elements |
 | `lineClass` | `string` | `"split-line"` | CSS class for line elements |
-| `mask` | `"lines" \| "words" \| "chars"` | — | Wraps elements in `overflow: clip` container for reveal animations |
+| `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 |
 | `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 |
+| `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 |
 
 #### Return Value
 
@@ -110,19 +112,36 @@ import { SplitText } from 'fetta/react';
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `children` | `ReactElement` | — | Single element to split |
-| `onSplit` | `function` | — | Called after text is split |
-| `onResize` | `function` | — | Called on autoSplit re-split |
-| `options` | `object` | — | Split options (type, classes, mask, propIndex, disableKerning) |
+| `children` | `ReactElement` | — | Single React element to split |
+| `as` | `keyof JSX.IntrinsicElements` | `"div"` | Wrapper element type |
+| `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) |
 | `autoSplit` | `boolean` | `false` | Re-split on container resize |
 | `revertOnComplete` | `boolean` | `false` | Revert after animation completes |
 | `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 |
+| `onInView` | `(result) => void` | — | Called when element enters viewport |
+| `onLeaveView` | `(result) => void` | — | 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 |
 
+#### Callback Signature
+
+All callbacks (`onSplit`, `onResize`, `onInView`, `onLeaveView`) receive the same result object:
+
+```ts
+{
+  chars: HTMLSpanElement[];
+  words: HTMLSpanElement[];
+  lines: HTMLSpanElement[];
+  revert: () => void;
+}
+```
+
 #### InView Options
 
 ```ts
@@ -135,72 +154,58 @@ import { SplitText } from 'fetta/react';
 
 ## Examples
 
-### Masked Line Reveal
+### Vanilla JavaScript
 
-```tsx
-<SplitText
-  options={{ type: 'lines', mask: 'lines' }}
-  onSplit={({ lines }) => {
-    animate(lines, { y: ['100%', 0] }, { delay: stagger(0.1) });
-  }}
->
-  <p>Each line reveals from below</p>
-</SplitText>
-```
+#### Basic
 
-### Scroll-Triggered Animation
+```js
+import { splitText } from 'fetta';
+import { animate, stagger } from 'motion';
 
-```tsx
-<SplitText
-  options={{ type: 'words' }}
-  initialStyles={{
-    words: { opacity: '0', transform: 'translateY(20px)' }
-  }}
-  inView={{ amount: 0.5 }}
-  onInView={({ words }) => {
-    animate(words, { opacity: 1, y: 0 }, { delay: stagger(0.03) });
-  }}
-  resetOnLeave
->
-  <p>Animates when scrolled into view</p>
-</SplitText>
+const { words } = splitText(document.querySelector('h1'));
+
+animate(words, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.05) });
 ```
 
-### Auto-Revert After Animation
+#### Masked Line Reveal
 
-```tsx
-<SplitText
-  revertOnComplete
-  onSplit={({ chars }) => {
-    return animate(chars, { opacity: [0, 1] }, { delay: stagger(0.02) });
-  }}
->
-  <h1>Reverts to original HTML after animation</h1>
-</SplitText>
+```js
+splitText(element, {
+  type: 'lines',
+  mask: 'lines',
+  onSplit: ({ lines }) => {
+    animate(lines, { y: ['100%', '0%'] }, { delay: stagger(0.1) });
+  }
+});
 ```
 
-### Responsive Re-split
+#### With GSAP
 
-```tsx
-<SplitText
-  autoSplit
-  onSplit={({ lines }) => animateLines(lines)}
-  onResize={({ lines }) => animateLines(lines)}
->
-  <p>Re-animates when container resizes</p>
-</SplitText>
+```js
+import { splitText } from 'fetta';
+import gsap from 'gsap';
+
+splitText(element, {
+  revertOnComplete: true,
+  onSplit: ({ words }) => {
+    return gsap.from(words, {
+      opacity: 0,
+      y: 20,
+      stagger: 0.05,
+      duration: 0.6,
+    });
+  }
+});
 ```
 
-### CSS-Only Animation with Index Props
+#### CSS-Only with Index Props
 
-```tsx
-<SplitText options={{ type: 'chars', propIndex: true }}>
-  <h1 className="stagger-fade">Hello</h1>
-</SplitText>
+```js
+splitText(element, { type: 'chars', propIndex: true });
 ```
 
 ```css
-.stagger-fade .split-char {
+.split-char {
   opacity: 0;
   animation: fade-in 0.5s forwards;
   animation-delay: calc(var(--char-index) * 0.03s);
@@ -211,38 +216,61 @@ import { SplitText } from 'fetta/react';
 }
 ```
 
-### With GSAP
+### React
+
+#### Basic
 
 ```tsx
-import { SplitText } from 'fetta/react';
-import gsap from 'gsap';
-
 <SplitText
-  revertOnComplete
   onSplit={({ words }) => {
-    return gsap.from(words, {
-      opacity: 0,
-      y: 20,
-      stagger: 0.05,
-      duration: 0.6,
-    });
+    animate(words, { opacity: [0, 1], y: [20, 0] }, { delay: stagger(0.05) });
   }}
 >
-  <h1>Works with GSAP</h1>
+  <h1>Hello World</h1>
 </SplitText>
 ```
 
-### Nested HTML Elements
+#### Masked Line Reveal
+
+```tsx
+<SplitText
+  options={{ type: 'lines', mask: 'lines' }}
+  onSplit={({ lines }) => {
+    animate(lines, { y: ['100%', '0%'] }, { delay: stagger(0.1) });
+  }}
+>
+  <p>Each line reveals from below</p>
+</SplitText>
+```
+
+#### Scroll-Triggered with InView
+
+```tsx
+<SplitText
+  options={{ type: 'words' }}
+  initialStyles={{
+    words: { opacity: '0', transform: 'translateY(20px)' }
+  }}
+  inView={{ amount: 0.5 }}
+  onInView={({ words }) => {
+    animate(words, { opacity: 1, y: 0 }, { delay: stagger(0.03) });
+  }}
+  resetOnLeave
+>
+  <p>Animates when scrolled into view</p>
+</SplitText>
+```
 
-Fetta preserves inline elements like links, emphasis, and other formatting. Attributes (href, class, id, data-*, etc.) are maintained.
+#### Auto-Revert After Animation
 
 ```tsx
 <SplitText
+  revertOnComplete
   onSplit={({ chars }) => {
-    animate(chars, { opacity: [0, 1] }, { delay: stagger(0.02) });
+    return animate(chars, { opacity: [0, 1] }, { delay: stagger(0.02) });
   }}
 >
-  <p>Click <a href="/signup">here</a> to <em>get started</em></p>
+  <h1>Reverts to original HTML after animation</h1>
 </SplitText>
 ```
 
@@ -258,11 +286,52 @@ Default classes applied to split elements:
 
 Each element also receives a `data-index` attribute with its position.
 
+## Font Loading
+
+For accurate kerning measurements, fonts must be fully loaded before splitting. When using custom fonts in vanilla JS, wait for `document.fonts.ready`:
+
+```ts
+document.fonts.ready.then(() => {
+  const { words } = splitText(element);
+  animate(words, { opacity: [0, 1] });
+});
+```
+
+The React component handles this automatically — no additional setup required.
+
+## Accessibility
+
+Fetta automatically handles accessibility to ensure split text remains readable by screen readers.
+
+**Headings and landmarks** — For elements that support `aria-label` natively (headings, `<section>`, `<nav>`, etc.), Fetta adds `aria-hidden="true"` to each split span and an `aria-label` on the parent:
+
+```html
+<!-- After splitting <h1>Hello World</h1> -->
+<h1 aria-label="Hello World">
+  <span class="split-word" aria-hidden="true">Hello</span>
+  <span class="split-word" aria-hidden="true">World</span>
+</h1>
+```
+
+**Generic elements and nested content** — For `<span>`, `<div>`, `<p>`, or text containing inline elements like links, Fetta wraps the visual content with `aria-hidden="true"` and adds a screen-reader-only copy that preserves the semantic structure:
+
+```html
+<!-- After splitting <p>Click <a href="/signup">here</a> to start</p> -->
+<p>
+  <span aria-hidden="true" data-fetta-visual="true">
+    <!-- Split visual content -->
+  </span>
+  <span class="fetta-sr-only" data-fetta-sr-copy="true">
+    Click <a href="/signup">here</a> to start
+  </span>
+</p>
+```
+
+Pre-existing `aria-label` attributes are always preserved.
+
 ## Notes
 
-- **Fonts must be loaded** before splitting. The React component waits for `document.fonts.ready` automatically.
 - **Ligatures are disabled** (`font-variant-ligatures: none`) because ligatures cannot span multiple elements.
-- **Accessibility**: Automatic screen reader support for both simple text and text with nested elements like links.
 
 ## Browser Support
 
@@ -273,6 +342,8 @@ Requires:
 - `IntersectionObserver`
 - `Intl.Segmenter`
 
+**Safari note** — Kerning compensation works but may be slightly less accurate due to Safari's unique font rendering. Differences are typically imperceptible and vary by font, but if you're using `revert()` and notice a subtle shift in some characters, you can bypass compensation with `disableKerning: true`.
+
 ## License
 
 MIT

package/dist/{chunk-24TCJGUM.js → chunk-Y4GCLM4K.js}

@@ -122,58 +122,9 @@ function copyKerningStyles(target, styles) {
     if (value) target.style.setProperty(prop, value);
   });
 }
-function buildCanvasFontString(styles) {
-  const fontStyle = styles.fontStyle || "normal";
-  const fontWeight = styles.fontWeight || "normal";
-  const fontSize = styles.fontSize || "16px";
-  const fontFamily = styles.fontFamily || "sans-serif";
-  return [fontStyle, fontWeight, fontSize, fontFamily].filter(Boolean).join(" ");
-}
-function applyKerningStylesToCanvas(ctx, styles) {
-  ctx.font = buildCanvasFontString(styles);
-  const ctxAny = ctx;
-  const setIfExists = (prop, value) => {
-    if (!value || value === "normal") return;
-    if (prop in ctxAny) ctxAny[prop] = value;
-  };
-  setIfExists("fontKerning", styles.getPropertyValue("font-kerning"));
-  setIfExists("fontVariantLigatures", styles.getPropertyValue("font-variant-ligatures"));
-  setIfExists("fontFeatureSettings", styles.getPropertyValue("font-feature-settings"));
-  setIfExists("fontVariationSettings", styles.getPropertyValue("font-variation-settings"));
-  setIfExists("fontOpticalSizing", styles.getPropertyValue("font-optical-sizing"));
-  setIfExists("fontSizeAdjust", styles.getPropertyValue("font-size-adjust"));
-  setIfExists("fontStretch", styles.getPropertyValue("font-stretch"));
-  setIfExists("fontVariantCaps", styles.getPropertyValue("font-variant-caps"));
-  setIfExists("fontVariantNumeric", styles.getPropertyValue("font-variant-numeric"));
-  setIfExists("fontVariantEastAsian", styles.getPropertyValue("font-variant-east-asian"));
-  setIfExists("fontSynthesis", styles.getPropertyValue("font-synthesis"));
-  setIfExists("fontSynthesisWeight", styles.getPropertyValue("font-synthesis-weight"));
-  setIfExists("fontSynthesisStyle", styles.getPropertyValue("font-synthesis-style"));
-  setIfExists("letterSpacing", styles.getPropertyValue("letter-spacing"));
-  setIfExists("wordSpacing", styles.getPropertyValue("word-spacing"));
-  setIfExists("textRendering", styles.getPropertyValue("text-rendering"));
-  setIfExists("direction", styles.getPropertyValue("direction"));
-}
 function buildKerningStyleKey(styles) {
   return KERNING_STYLE_PROPS.map((prop) => styles.getPropertyValue(prop)).join("|");
 }
-function shouldUseDomKerning(styles) {
-  const textTransform = styles.getPropertyValue("text-transform");
-  if (textTransform && textTransform !== "none") return true;
-  const fontVariant = styles.getPropertyValue("font-variant");
-  if (fontVariant && fontVariant !== "normal") return true;
-  const fontStretch = styles.getPropertyValue("font-stretch");
-  if (fontStretch && fontStretch !== "normal" && fontStretch !== "100%") return true;
-  const fontFeatureSettings = styles.getPropertyValue("font-feature-settings");
-  if (fontFeatureSettings && fontFeatureSettings !== "normal") return true;
-  const fontVariationSettings = styles.getPropertyValue("font-variation-settings");
-  if (fontVariationSettings && fontVariationSettings !== "normal") return true;
-  const fontOpticalSizing = styles.getPropertyValue("font-optical-sizing");
-  if (fontOpticalSizing && fontOpticalSizing !== "auto") return true;
-  const fontSizeAdjust = styles.getPropertyValue("font-size-adjust");
-  if (fontSizeAdjust && fontSizeAdjust !== "none") return true;
-  return false;
-}
 var isSafariBrowser = null;
 function isSafari() {
   if (isSafariBrowser !== null) return isSafariBrowser;
@@ -181,29 +132,6 @@ function isSafari() {
   isSafariBrowser = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
   return isSafariBrowser;
 }
-function measureKerningCanvas(styleSource, chars, styles) {
-  const kerningMap = /* @__PURE__ */ new Map();
-  if (chars.length < 2) return kerningMap;
-  const canvas = document.createElement("canvas");
-  const ctx = canvas.getContext("2d");
-  if (!ctx) return kerningMap;
-  const computedStyles = styles != null ? styles : getComputedStyle(styleSource);
-  applyKerningStylesToCanvas(ctx, computedStyles);
-  const charWidths = /* @__PURE__ */ new Map();
-  for (const char of new Set(chars)) {
-    charWidths.set(char, ctx.measureText(char).width);
-  }
-  for (let i = 0; i < chars.length - 1; i++) {
-    const char1 = chars[i];
-    const char2 = chars[i + 1];
-    const pairWidth = ctx.measureText(char1 + char2).width;
-    const kerning = pairWidth - charWidths.get(char1) - charWidths.get(char2);
-    if (Math.abs(kerning) > 1e-3) {
-      kerningMap.set(i + 1, kerning);
-    }
-  }
-  return kerningMap;
-}
 function measureKerningDOM(container, styleSource, chars, styles) {
   const kerningMap = /* @__PURE__ */ new Map();
   if (chars.length < 2) return kerningMap;
@@ -242,10 +170,47 @@ function measureKerningDOM(container, styleSource, chars, styles) {
   container.removeChild(measurer);
   return kerningMap;
 }
+function measureKerningRange(container, styleSource, chars, styles) {
+  const kerningMap = /* @__PURE__ */ new Map();
+  if (chars.length < 2) return kerningMap;
+  const measurer = document.createElement("span");
+  measurer.style.cssText = "position:absolute;visibility:hidden;white-space:pre;";
+  const computedStyles = styles != null ? styles : getComputedStyle(styleSource);
+  copyKerningStyles(measurer, computedStyles);
+  container.appendChild(measurer);
+  const range = document.createRange();
+  const measureWidth = () => {
+    const textNode = measurer.firstChild;
+    if (!textNode) return 0;
+    range.selectNodeContents(textNode);
+    return range.getBoundingClientRect().width;
+  };
+  const charWidths = /* @__PURE__ */ new Map();
+  for (const char of new Set(chars)) {
+    measurer.textContent = char;
+    charWidths.set(char, measureWidth());
+  }
+  for (let i = 0; i < chars.length - 1; i++) {
+    const char1 = chars[i];
+    const char2 = chars[i + 1];
+    measurer.textContent = char1 + char2;
+    const kerning = measureWidth() - charWidths.get(char1) - charWidths.get(char2);
+    if (Math.abs(kerning) > 1e-3) {
+      kerningMap.set(i + 1, kerning);
+    }
+  }
+  range.detach();
+  container.removeChild(measurer);
+  return kerningMap;
+}
 function measureKerning(container, styleSource, chars, styles) {
   if (chars.length < 2) return /* @__PURE__ */ new Map();
+  if (!container.isConnected) {
+    console.warn("splitText: kerning measurement requires a connected DOM element. Skipping kerning.");
+    return /* @__PURE__ */ new Map();
+  }
   const computedStyles = styles != null ? styles : getComputedStyle(styleSource);
-  return isSafari() || shouldUseDomKerning(computedStyles) ? measureKerningDOM(container, styleSource, chars, computedStyles) : measureKerningCanvas(styleSource, chars, computedStyles);
+  return isSafari() ? measureKerningDOM(container, styleSource, chars, computedStyles) : measureKerningRange(container, styleSource, chars, computedStyles);
 }
 var srOnlyStylesInjected = false;
 function injectSrOnlyStyles() {

package/dist/index.js

@@ -1 +1 @@
-export { splitText } from './chunk-24TCJGUM.js';
+export { splitText } from './chunk-Y4GCLM4K.js';

package/dist/react.js

@@ -1,4 +1,4 @@
-import { splitText, __spreadProps, __spreadValues, normalizeToPromise } from './chunk-24TCJGUM.js';
+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';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fetta",
-  "version": "1.4.2",
+  "version": "1.4.4",
   "description": "Text splitting library with kerning compensation for animations",
   "type": "module",
   "sideEffects": false,
@@ -80,11 +80,20 @@
   "keywords": [
     "text",
     "split",
+    "split-text",
+    "splittext",
+    "text-animation",
+    "text-effect",
     "animation",
     "motion",
     "kerning",
     "typography",
-    "gsap"
+    "gsap",
+    "javascript",
+    "typescript",
+    "react",
+    "web-animation",
+    "accessible"
   ],
   "license": "MIT",
   "author": "dimi",