@edwinvakayil/calligraphy 1.4.0 → 1.5.0

package/dist/index.js

@@ -530,6 +530,17 @@ function wrapSplitRise(html) {
 function wrapThread(html) {
     return wrapChars(html, "rts-thread-ch", 0.04);
 }
+/**
+ * Called by Typography after dangerouslySetInnerHTML for "thread" animation.
+ * Stamps the sine-wave Y offset as --ty on each character span.
+ */
+function applyThreadOffsets(container) {
+    const spans = container.querySelectorAll(".rts-thread-ch");
+    spans.forEach((el, i) => {
+        const offset = Math.sin(i * 0.85) * 22;
+        el.style.setProperty("--ty", `${offset.toFixed(1)}px`);
+    });
+}
 // ─── Public API ───────────────────────────────────────────────────────────────
 function buildSplitHTML(animation, html) {
     switch (animation) {
@@ -570,6 +581,88 @@ function buildSplitHTML(animation, html) {
         default: return html;
     }
 }
+// ─── Custom motion builder ────────────────────────────────────────────────────
+/**
+ * Injects a one-off @keyframes rule with a generated name and returns that name.
+ * Deduped by a hash of the keyframe body so the same keyframe is only injected once.
+ */
+function injectCustomKeyframes(keyframeBody) {
+    const hash = keyframeBody
+        .split("")
+        .reduce((acc, ch) => (Math.imul(31, acc) + ch.charCodeAt(0)) | 0, 0)
+        .toString(36)
+        .replace("-", "n");
+    const name = `rts-custom-${hash}`;
+    if (typeof document === "undefined")
+        return name;
+    if (document.getElementById(name))
+        return name;
+    const style = document.createElement("style");
+    style.id = name;
+    style.textContent = `@keyframes ${name} { ${keyframeBody} }`;
+    document.head.appendChild(style);
+    return name;
+}
+/**
+ * Builds the innerHTML for a custom motionConfig.
+ * - split "none"  → returns the raw html unchanged; caller applies class to element
+ * - split "words" → wraps each word in a span with the animation + stagger delay
+ * - split "chars" → wraps each character in a span with the animation + stagger delay
+ *
+ * Returns { html, animationValue } where animationValue is the full CSS animation
+ * shorthand to set on each span (or on the element itself when split is "none").
+ */
+function buildCustomHTML(html, keyframeName, duration, easing, delay, fillMode, split, staggerDelay) {
+    var _a;
+    const baseAnimation = `${keyframeName} ${duration} ${easing} ${delay} ${fillMode}`;
+    if (split === "none") {
+        return { html, baseAnimation };
+    }
+    if (split === "words") {
+        const tokens = (_a = html.match(/(<em>[\s\S]*?<\/em>|[^\s]+)/g)) !== null && _a !== void 0 ? _a : [];
+        const result = tokens.map((tok, i) => {
+            const totalDelay = i === 0
+                ? delay
+                : `${(parseFloat(delay) + i * staggerDelay).toFixed(3)}s`;
+            const anim = `${keyframeName} ${duration} ${easing} ${totalDelay} ${fillMode}`;
+            if (tok.startsWith("<em>")) {
+                return `<em><span style="display:inline-block;animation:${anim}">${tok.slice(4, -5)}</span></em>`;
+            }
+            return `<span style="display:inline-block;animation:${anim}">${tok}</span>`;
+        });
+        return { html: result.join(" "), baseAnimation };
+    }
+    // chars
+    const result = [];
+    let inEm = false, charIndex = 0, i = 0;
+    while (i < html.length) {
+        if (html.startsWith("<em>", i)) {
+            inEm = true;
+            i += 4;
+            continue;
+        }
+        if (html.startsWith("</em>", i)) {
+            inEm = false;
+            i += 5;
+            continue;
+        }
+        const ch = html[i];
+        if (ch === " ") {
+            result.push(" ");
+            i++;
+            continue;
+        }
+        const totalDelay = charIndex === 0
+            ? delay
+            : `${(parseFloat(delay) + charIndex * staggerDelay).toFixed(3)}s`;
+        const anim = `${keyframeName} ${duration} ${easing} ${totalDelay} ${fillMode}`;
+        const span = `<span style="display:inline-block;animation:${anim}">${ch}</span>`;
+        result.push(inEm ? `<em>${span}</em>` : span);
+        charIndex++;
+        i++;
+    }
+    return { html: result.join(""), baseAnimation };
+}
 
 // ─── Defaults ─────────────────────────────────────────────────────────────────
 const DEFAULT_THEME = {
@@ -607,7 +700,7 @@ function useTypographyTheme() {
     return react.useContext(TypographyContext);
 }
 
-// ─── Static maps ─────────────────────────────────────────────────────────────
+// ─── Variant → HTML tag map ───────────────────────────────────────────────────
 const variantTagMap = {
     Display: "h1",
     H1: "h1",
@@ -622,6 +715,7 @@ const variantTagMap = {
     Label: "label",
     Caption: "span",
 };
+// ─── Variant → base CSS styles ────────────────────────────────────────────────
 const variantStyleMap = {
     Display: {
         fontSize: "clamp(2.5rem, 6vw, 5rem)",
@@ -697,9 +791,15 @@ const variantStyleMap = {
         letterSpacing: "0.03em",
     },
 };
-// ─── Constants ───────────────────────────────────────────────────────────────
+// ─── Constants ────────────────────────────────────────────────────────────────
+// Always pre-loaded for hero variants so toggling italic is instant with no FOUC
 const INSTRUMENT_SERIF_URL = "https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&display=swap";
-// ─── Helpers ─────────────────────────────────────────────────────────────────
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+/**
+ * Serialise React children to a raw HTML string.
+ * Handles plain strings and <em>text</em> elements.
+ * Used to feed text into the animation split-builders.
+ */
 function childrenToHTML(children) {
     var _a, _b;
     return ((_b = (_a = react.Children.map(children, (child) => {
@@ -707,12 +807,19 @@ function childrenToHTML(children) {
             return String(child);
         }
         if (react.isValidElement(child) && child.type === "em") {
-            const inner = typeof child.props.children === "string" ? child.props.children : "";
+            const inner = typeof child.props.children === "string"
+                ? child.props.children
+                : "";
             return `<em>${inner}</em>`;
         }
         return "";
     })) === null || _a === void 0 ? void 0 : _a.join("")) !== null && _b !== void 0 ? _b : "");
 }
+/**
+ * Standard (no-animation) render path.
+ * Clones <em> children with explicit inline styles so the font switch is
+ * guaranteed — parent fontFamily cannot override a child's own inline style.
+ */
 function renderChildrenWithEmStyles(children, italic, accentColor, headingFont) {
     const italicStyle = {
         fontFamily: "'Instrument Serif', serif",
@@ -733,6 +840,11 @@ function renderChildrenWithEmStyles(children, italic, accentColor, headingFont)
         return child;
     });
 }
+/**
+ * Animation (dangerouslySetInnerHTML) render path.
+ * After the DOM is written we walk it and stamp inline styles onto every
+ * <em> and <em > span — guaranteed to beat any inherited fontFamily.
+ */
 function applyEmStylesDOM(container, italic, accentColor, headingFont) {
     const apply = (el) => {
         if (italic) {
@@ -742,7 +854,9 @@ function applyEmStylesDOM(container, italic, accentColor, headingFont) {
             el.style.color = accentColor;
         }
         else {
-            el.style.fontFamily = headingFont ? `'${headingFont}', sans-serif` : "inherit";
+            el.style.fontFamily = headingFont
+                ? `'${headingFont}', sans-serif`
+                : "inherit";
             el.style.fontStyle = "normal";
             el.style.fontWeight = "inherit";
             el.style.color = "inherit";
@@ -751,61 +865,98 @@ function applyEmStylesDOM(container, italic, accentColor, headingFont) {
     container.querySelectorAll("em").forEach(apply);
     container.querySelectorAll("em > span").forEach(apply);
 }
-// ─── Component ───────────────────────────────────────────────────────────────
+// ─── Component ────────────────────────────────────────────────────────────────
 const Typography = (_a) => {
-    var _b;
-    var { variant = "Body", font: fontProp, color: colorProp, animation: animationProp, italic: italicProp, accentColor: accentColorProp, align, className, style, children, as, truncate, maxLines } = _a, rest = __rest(_a, ["variant", "font", "color", "animation", "italic", "accentColor", "align", "className", "style", "children", "as", "truncate", "maxLines"]);
+    var _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    var { variant = "Body", font: fontProp, color: colorProp, animation: animationProp, motionConfig, motionRef, italic: italicProp, accentColor: accentColorProp, align, className, style, children, as, truncate, maxLines } = _a, rest = __rest(_a, ["variant", "font", "color", "animation", "motionConfig", "motionRef", "italic", "accentColor", "align", "className", "style", "children", "as", "truncate", "maxLines"]);
     const theme = useTypographyTheme();
     const isHero = variant === "Display" || variant === "H1";
     const ref = react.useRef(null);
-    // Prop wins; fall back to theme; fall back to built-in default
+    // Prop wins → theme → built-in default
     const font = fontProp !== null && fontProp !== void 0 ? fontProp : (theme.font || undefined);
     const color = colorProp !== null && colorProp !== void 0 ? colorProp : (theme.color || undefined);
-    const animation = isHero ? ((_b = animationProp !== null && animationProp !== void 0 ? animationProp : theme.animation) !== null && _b !== void 0 ? _b : undefined) : undefined;
-    const italic = italicProp !== null && italicProp !== void 0 ? italicProp : theme.italic;
-    const accentColor = accentColorProp !== null && accentColorProp !== void 0 ? accentColorProp : theme.accentColor;
-    // ── useInsertionEffect: inject <link> and <style> tags ────────────────────
-    //
-    // WHY useInsertionEffect instead of plain render-phase calls:
-    //
-    // 1. Server safety — useInsertionEffect (like all effects) is never called
-    //    on the server, so document.createElement / document.head never run
-    //    during SSR. The isBrowser guard in ssr.ts is a belt-and-suspenders
-    //    backup, but the effect boundary is the real guarantee.
-    //
-    // 2. Correctness — React 18 concurrent mode can call the render function
-    //    multiple times before committing. Doing DOM work in render can fire
-    //    those side-effects redundantly or out of order. useInsertionEffect
-    //    fires synchronously before the browser paints, once per commit.
-    //
-    // 3. No FOUC — because it fires before paint (earlier than useLayoutEffect),
-    //    the <style> tag is in the DOM before any text is visible, so there is
-    //    no flash of unstyled / wrong-font text.
+    const animation = isHero
+        ? ((_b = animationProp !== null && animationProp !== void 0 ? animationProp : theme.animation) !== null && _b !== void 0 ? _b : undefined)
+        : undefined;
+    const italic = (_c = italicProp !== null && italicProp !== void 0 ? italicProp : theme.italic) !== null && _c !== void 0 ? _c : false;
+    const accentColor = (_d = accentColorProp !== null && accentColorProp !== void 0 ? accentColorProp : theme.accentColor) !== null && _d !== void 0 ? _d : "#c8b89a";
+    // ── Font & style injection ─────────────────────────────────────────────────
     react.useInsertionEffect(() => {
-        // Instrument Serif — always pre-load for hero so toggling italic is instant
         if (isHero) {
             injectFont(INSTRUMENT_SERIF_URL);
         }
-        // Heading Google Font
         if (font && GOOGLE_FONTS.includes(font)) {
             injectFont(buildFontUrl(font));
         }
-        // Animation keyframe stylesheet
         if (animation && isHero) {
             injectAnimationStyles();
         }
-    }, [isHero, font, animation]);
-    // ── useEffect: re-stamp inline styles on <em> after DOM updates ───────────
+        // Inject custom keyframes as soon as the prop arrives
+        if (motionConfig === null || motionConfig === void 0 ? void 0 : motionConfig.keyframes) {
+            injectCustomKeyframes(motionConfig.keyframes);
+        }
+    }, [isHero, font, animation, motionConfig === null || motionConfig === void 0 ? void 0 : motionConfig.keyframes]);
+    // ── Re-stamp <em> inline styles after every relevant change ───────────────
     react.useEffect(() => {
         if (!isHero || !animation || !ref.current)
             return;
         applyEmStylesDOM(ref.current, italic, accentColor, font);
+        if (animation === "thread")
+            applyThreadOffsets(ref.current);
     }, [italic, accentColor, font, animation, isHero]);
+    // ── motionRef callback — fires after mount and on every re-render ──────────
+    // motionRef wins over animation and motionConfig — the user drives the DOM.
+    react.useEffect(() => {
+        if (!motionRef)
+            return;
+        motionRef(ref.current);
+    });
+    // ── Strip lingering CSS properties after animation ends ───────────────────
+    react.useEffect(() => {
+        const el = ref.current;
+        if (!el || !animation)
+            return;
+        const cleanup = () => {
+            if (animation === "maskSweep") {
+                el.style.setProperty("mask-image", "none");
+                el.style.setProperty("-webkit-mask-image", "none");
+            }
+            if (animation === "gradSweep") {
+                el.style.animation = "none";
+            }
+        };
+        el.addEventListener("animationend", cleanup, { once: true });
+        return () => el.removeEventListener("animationend", cleanup);
+    }, [animation]);
     const Tag = (as !== null && as !== void 0 ? as : variantTagMap[variant]);
-    // ── Animation path: build inner HTML ─────────────────────────────────────
+    // ── Build inner HTML — priority: motionRef > motionConfig > animation ──────
     let animClass = "";
     let heroHTML = null;
-    if (animation && isHero) {
+    let customAnimStyle;
+    // motionRef — no HTML manipulation needed, user handles everything via ref
+    if (motionRef) ;
+    // motionConfig — works on any variant, not just heroes
+    else if (motionConfig === null || motionConfig === void 0 ? void 0 : motionConfig.keyframes) {
+        const keyframeName = injectCustomKeyframes(motionConfig.keyframes);
+        const duration = (_e = motionConfig.duration) !== null && _e !== void 0 ? _e : "0.8s";
+        const easing = (_f = motionConfig.easing) !== null && _f !== void 0 ? _f : "cubic-bezier(0.16,1,0.3,1)";
+        const delay = (_g = motionConfig.delay) !== null && _g !== void 0 ? _g : "0s";
+        const fillMode = (_h = motionConfig.fillMode) !== null && _h !== void 0 ? _h : "both";
+        const split = (_j = motionConfig.split) !== null && _j !== void 0 ? _j : "none";
+        const staggerDelay = (_k = motionConfig.staggerDelay) !== null && _k !== void 0 ? _k : (split === "chars" ? 0.04 : 0.07);
+        const rawHTML = childrenToHTML(children);
+        const { html, baseAnimation } = buildCustomHTML(rawHTML, keyframeName, duration, easing, delay, fillMode, split, staggerDelay);
+        if (split === "none") {
+            // Apply animation directly on the element via inline style
+            customAnimStyle = baseAnimation;
+            heroHTML = rawHTML;
+        }
+        else {
+            heroHTML = html;
+        }
+    }
+    // Built-in animation preset
+    else if (animation && isHero) {
         const rawHTML = childrenToHTML(children);
         if (isSplitAnimation(animation)) {
             heroHTML = buildSplitHTML(animation, rawHTML);
@@ -816,8 +967,12 @@ const Typography = (_a) => {
         }
     }
     // ── Computed container styles ─────────────────────────────────────────────
-    const computedStyle = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, variantStyleMap[variant]), (font ? { fontFamily: `'${font}', sans-serif` } : {})), (color ? { color } : {})), (align ? { textAlign: align } : {})), (truncate
-        ? { overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }
+    const computedStyle = Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, variantStyleMap[variant]), (font ? { fontFamily: `'${font}', sans-serif` } : {})), (color ? { color } : {})), (align ? { textAlign: align } : {})), (truncate
+        ? {
+            overflow: "hidden",
+            textOverflow: "ellipsis",
+            whiteSpace: "nowrap",
+        }
         : {})), (maxLines && !truncate
         ? {
             display: "-webkit-box",
@@ -825,12 +980,16 @@ const Typography = (_a) => {
             WebkitBoxOrient: "vertical",
             overflow: "hidden",
         }
-        : {})), { margin: 0, padding: 0 }), style);
-    // ── Render: animation path (dangerouslySetInnerHTML) ──────────────────────
+        : {})), (customAnimStyle ? { animation: customAnimStyle } : {})), { margin: 0, padding: 0 }), style);
+    // ── Render: animation path ────────────────────────────────────────────────
+    //
+    // key={animation} forces React to unmount + remount the element when the
+    // animation value changes, guaranteeing the CSS keyframe fires from frame 0
+    // on every switch.
     if (heroHTML !== null) {
         return (jsxRuntime.jsx(Tag, Object.assign({ ref: ref, className: [animClass, className].filter(Boolean).join(" "), style: computedStyle, dangerouslySetInnerHTML: { __html: heroHTML } }, rest), animation));
     }
-    // ── Render: standard path ────────────────────────────────────────────────
+    // ── Render: standard path ─────────────────────────────────────────────────
     const processedChildren = isHero
         ? renderChildrenWithEmStyles(children, italic, accentColor, font)
         : children;
@@ -844,4 +1003,5 @@ exports.buildFontUrl = buildFontUrl;
 exports.default = Typography;
 exports.injectFont = injectFont;
 exports.preloadFonts = preloadFonts;
+exports.useTypographyTheme = useTypographyTheme;
 //# sourceMappingURL=index.js.map