@edwinvakayil/calligraphy 1.3.0 → 1.4.0

package/dist/animation.d.ts

@@ -1,9 +1,12 @@
 import { HeroAnimation } from "./types";
 export declare function injectAnimationStyles(): void;
-/** Returns the CSS class for whole-element animations, or "" for split ones. */
 export declare function getAnimationClass(animation: HeroAnimation): string;
-/** True if the animation needs the HTML to be split into word/char spans. */
 export declare function isSplitAnimation(animation: HeroAnimation): boolean;
+/**
+ * Called by Typography after dangerouslySetInnerHTML for "thread" animation.
+ * Stamps the sine-wave Y offset as --ty on each character span.
+ */
+export declare function applyThreadOffsets(container: HTMLElement): void;
 export declare function buildSplitHTML(animation: HeroAnimation, html: string): string;
 export declare const buildStaggerHTML: (html: string) => string;
 export declare const buildLettersHTML: (html: string) => string;

package/dist/index.d.ts

@@ -21,38 +21,67 @@ declare const TypographyProvider: React.FC<TypographyProviderProps>;
 type TypographyVariant = "Display" | "H1" | "H2" | "H3" | "H4" | "H5" | "H6" | "Subheading" | "Overline" | "Body" | "Label" | "Caption";
 type TextAlign = "left" | "center" | "right" | "justify";
 /**
- * Built-in hero text entrance animations.
- * Applied via CSS keyframes — GPU-composited, 60fps safe.
+ * Hero entrance animations — all GPU-composited (transform + opacity + filter only).
  *
- * — Original —
- * rise       — smooth upward fade-in (universal default)
- * stagger    — each word rises in sequence
- * clip       — text unmasked left-to-right (editorial)
- * pop        — spring scale-in (energetic)
- * letters    — each letter slides in with a slight rotation
- * blur       — emerges from a blur (cinematic)
- * flip       — 3-D perspective rotate on entry (depth)
- * swipe      — slides in from the right
- * typewriter — character-by-character reveal
- * bounce     — drops from above with a soft bounce
+ * ── Batch 1 — originals ──────────────────────────────────────────────────
+ * rise        smooth upward fade (universal)
+ * stagger     per-word upward rise in sequence
+ * clip        text unmasked left to right
+ * pop         spring scale-in
+ * letters     each letter slides in with rotation
+ * blur        emerges from blur
+ * flip        3-D rotateX on entry
+ * swipe       slides in from the right
+ * typewriter  character-by-character reveal
+ * bounce      drops from above with bounce
  *
- * — Modern —
- * velvet     — words drift in with a soft skew (buttery & modern)
- * curtain    — each word clips upward like a rising curtain
- * morph      — squash-and-stretch spring (expressive & bold)
- * ground     — words emerge from behind the baseline (editorial)
- * cascade    — diagonal character waterfall (dynamic & layered)
- * spotlight  — expands from compressed letterspace (cinematic)
- * ink        — words fade in with a gentle scale (calm & precise)
- * hinge      — words rotate in from their left edge (mechanical)
- * stretch    — horizontal rubber-band expand (playful & punchy)
- * peel       — bottom-to-top clip reveal per word (sharp)
+ * ── Batch 2 — modern ─────────────────────────────────────────────────────
+ * velvet      words drift in with skew
+ * curtain     each word clips upward
+ * morph       squash-and-stretch spring
+ * ground      words emerge from baseline
+ * cascade     diagonal character waterfall
+ * spotlight   expands from compressed letterspace
+ * ink         words fade in with gentle scale
+ * hinge       words rotate from left edge
+ * stretch     horizontal rubber-band expand
+ * peel        bottom-to-top clip per word
+ * fold        words rotate in on Z from a folded angle
+ * shear       words skewY then settle
+ * ripple      words scale from compressed point, elastic outward wave
+ * cinch       chars pinch on scaleX then snap open with skew
+ * tiltrise    words rise while untilting from a sideways lean
+ * cardFlip    chars flip up on X from flat
+ * converge    outer words fly in, meet in center
+ * splitRise   alternating words from top/bottom
+ *
+ * ── Batch 3 — new untouched techniques ───────────────────────────────────
+ * tectonic    words slam from alternating X sides with skew — collision energy
+ * stratify    per-word Z-depth flight through blur — true depth-of-field
+ * unfurl      line expands from horizontal center — origami opening
+ * gravityWell chars fall from sky with micro-rotation physics overshoot
+ * orbit       words grow from dot while rotating on Z-axis
+ * liquid      per-word cross-axis squash then spring — fluid inertia
+ * noiseFade   3 random opacity waveforms per word — signal locking in
+ * slab        words stamp from left with scaleX — print-press energy
+ * thread      chars float on individual sine-wave Y offsets — musical
+ * billboard   whole line rotates in on Y-axis — turning sign
+ *
+ * ── Batch 7 — genuinely new mechanics ────────────────────────────────────
+ * glassReveal  backdrop-filter blur evaporates as text solidifies
+ * wordPop      per-word springs from zero scale at its own centre
+ * charDrop     chars fall under pure gravity — no overshoot or rotation
+ * scanline     single-pixel horizontal slice expands to full height
+ * chromaShift  RGB channel offsets collapse to zero (printing-register feel)
+ * wordFade     per-word cross-dissolve with warmth scale, no Y movement
+ * rotateIn     full Y-axis card-flip per word (face-up reveal)
+ * pressIn      presses to 0.92 then springs past 1 (physical button feel)
  */
-type HeroAnimation = "rise" | "stagger" | "clip" | "pop" | "letters" | "blur" | "flip" | "swipe" | "typewriter" | "bounce" | "velvet" | "curtain" | "morph" | "ground" | "cascade" | "spotlight" | "ink" | "hinge" | "stretch" | "peel";
+type HeroAnimation = "rise" | "stagger" | "clip" | "pop" | "letters" | "blur" | "flip" | "swipe" | "typewriter" | "bounce" | "velvet" | "curtain" | "morph" | "ground" | "cascade" | "spotlight" | "ink" | "hinge" | "stretch" | "peel" | "fold" | "shear" | "ripple" | "cinch" | "tiltrise" | "cardFlip" | "converge" | "splitRise" | "tectonic" | "stratify" | "unfurl" | "gravityWell" | "orbit" | "liquid" | "noiseFade" | "slab" | "thread" | "billboard" | "glassReveal" | "wordPop" | "charDrop" | "scanline" | "chromaShift" | "wordFade" | "rotateIn" | "pressIn";
 interface TypographyProps extends HTMLAttributes<HTMLElement> {
     /** Typography scale variant */
     variant?: TypographyVariant;
-    /** Google Font name e.g. "Bricolage Grotesque", "Playfair Display" */
+    /** Google Font name — auto-injects the Google Fonts <link> */
     font?: string;
     /** Text color — any valid CSS color */
     color?: string;
@@ -62,28 +91,25 @@ interface TypographyProps extends HTMLAttributes<HTMLElement> {
     as?: ElementType;
     /** Truncate to single line with ellipsis */
     truncate?: boolean;
-    /** Clamp to N lines with ellipsis */
+    /** Clamp to N lines */
     maxLines?: number;
     /**
-     * Hero entrance animation. Only applies when variant is
-     * "Display" or "H1". Injects a CSS class and keyframe stylesheet once.
+     * Hero entrance animation.
+     * Only applied on variant="Display" or variant="H1".
      */
     animation?: HeroAnimation;
     /**
      * Italic accent for Display / H1 heroes.
-     * When true, any <em> child renders in Instrument Serif italic
-     * with an accent color. Defaults to false — everything renders
-     * in the heading font/weight with no serif or italics.
+     * When true, <em> children render in Instrument Serif italic + accentColor.
+     * Default: false.
      */
     italic?: boolean;
     /**
-     * Accent color for the <em> italic span inside Display / H1.
-     * Defaults to a warm sand tone (#c8b89a).
+     * Color for the <em> italic accent span.
+     * Default: "#c8b89a" (warm sand).
      */
     accentColor?: string;
-    /** Inline style overrides */
     style?: CSSProperties;
-    /** Additional class names */
     className?: string;
 }