@edwinvakayil/calligraphy 1.4.0 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @edwinvakayil/calligraphy
 
-A lightweight **React + TypeScript** typography component with automatic **Google Fonts** support, **hero entrance animations**, and an **italic accent toggle**.
+A lightweight **React + TypeScript** typography component with automatic **Google Fonts** support, **30+ hero entrance animations**, **custom motion config**, and an **italic accent toggle**.
 
 ---
 
@@ -44,20 +44,20 @@ The `font` prop auto-injects the matching Google Font `<link>` tag — no manual
 
 ## Variants
 
-| Variant      | Tag      | Role                              |
-|--------------|----------|-----------------------------------|
-| `Display`    | `h1`     | Hero / landing page headline      |
-| `H1`         | `h1`     | Primary page heading              |
-| `H2`         | `h2`     | Section heading                   |
-| `H3`         | `h3`     | Sub-section heading               |
-| `H4`         | `h4`     | Card / panel heading              |
-| `H5`         | `h5`     | Small heading                     |
-| `H6`         | `h6`     | Micro heading                     |
-| `Subheading` | `h6`     | Supporting subtitle               |
-| `Overline`   | `span`   | ALL CAPS label above a heading    |
-| `Body`       | `p`      | Main body copy                    |
-| `Label`      | `label`  | Form labels, tags                 |
-| `Caption`    | `span`   | Image captions, fine print        |
+| Variant      | Tag      | Role                           |
+|--------------|----------|--------------------------------|
+| `Display`    | `h1`     | Hero / landing page headline   |
+| `H1`         | `h1`     | Primary page heading           |
+| `H2`         | `h2`     | Section heading                |
+| `H3`         | `h3`     | Sub-section heading            |
+| `H4`         | `h4`     | Card / panel heading           |
+| `H5`         | `h5`     | Small heading                  |
+| `H6`         | `h6`     | Micro heading                  |
+| `Subheading` | `h6`     | Supporting subtitle            |
+| `Overline`   | `span`   | ALL CAPS label above a heading |
+| `Body`       | `p`      | Main body copy                 |
+| `Label`      | `label`  | Form labels, tags              |
+| `Caption`    | `span`   | Image captions, fine print     |
 
 ---
 
@@ -65,18 +65,20 @@ The `font` prop auto-injects the matching Google Font `<link>` tag — no manual
 
 ```ts
 interface TypographyProps {
-  variant?:     TypographyVariant    // default: "Body"
-  font?:        string               // Google Font name e.g. "Bricolage Grotesque"
-  color?:       string               // Any CSS color value
-  align?:       "left" | "center" | "right" | "justify"
-  as?:          ElementType          // Override rendered HTML tag
-  truncate?:    boolean              // Single-line ellipsis
-  maxLines?:    number               // Multi-line line-clamp
-  animation?:   HeroAnimation        // Entrance animation (Display / H1 only)
-  italic?:      boolean              // default: true — show serif italic accent on <em>
-  accentColor?: string               // default: "#c8b89a" — color for <em> italic text
-  className?:   string
-  style?:       CSSProperties
+  variant?:      TypographyVariant    // default: "Body"
+  font?:         string               // Google Font name e.g. "Bricolage Grotesque"
+  color?:        string               // Any CSS color value
+  align?:        "left" | "center" | "right" | "justify"
+  as?:           ElementType          // Override rendered HTML tag
+  truncate?:     boolean              // Single-line ellipsis
+  maxLines?:     number               // Multi-line line-clamp
+  animation?:    HeroAnimation        // Built-in entrance animation (Display / H1 only)
+  motionConfig?: MotionConfig         // Custom keyframe animation — any variant
+  motionRef?:    (el: HTMLElement | null) => void  // Direct DOM access for GSAP / Framer
+  italic?:       boolean              // default: false — serif italic accent on <em>
+  accentColor?:  string               // default: "#c8b89a" — color for <em> italic text
+  className?:    string
+  style?:        CSSProperties
 }
 ```
 
@@ -84,7 +86,7 @@ interface TypographyProps {
 
 ## Hero Animations
 
-The `animation` prop works on `Display` and `H1` variants only. It injects a tiny stylesheet once (no external dependency) and applies a CSS keyframe entrance.
+The `animation` prop works on `Display` and `H1` variants. It injects a tiny stylesheet once (no external dependency) and applies a CSS keyframe entrance.
 
 ```tsx
 <Typography variant="Display" font="Bricolage Grotesque" animation="rise">
@@ -94,141 +96,220 @@ The `animation` prop works on `Display` and `H1` variants only. It injects a tin
 
 ### Available animations
 
-| Value         | Description                                           |
-|---------------|-------------------------------------------------------|
-| `rise`        | Smooth upward fade-in — clean, universal              |
-| `stagger`     | Each word rises in sequence                           |
-| `clip`        | Text unmasked left to right — editorial feel          |
-| `pop`         | Spring scale-in — energetic and confident             |
-| `letters`     | Each letter slides in with a slight rotation          |
-| `blur`        | Emerges from a blur — cinematic and dreamy            |
-| `flip`        | 3-D perspective rotate on entry — depth and gravitas  |
-| `swipe`       | Slides in from the right — directional flow           |
-| `typewriter`  | Character-by-character reveal — focused               |
-| `bounce`      | Drops from above with a soft bounce                   |
+#### Original
+
+| Value        | Description                                          |
+|--------------|------------------------------------------------------|
+| `rise`       | Smooth upward fade-in — clean, universal             |
+| `stagger`    | Each word rises in sequence                          |
+| `clip`       | Text unmasked left to right — editorial feel         |
+| `pop`        | Spring scale-in — energetic and confident            |
+| `letters`    | Each letter slides in with a slight rotation         |
+| `blur`       | Emerges from a blur — cinematic and dreamy           |
+| `flip`       | 3-D perspective rotate on entry — depth and gravitas |
+| `swipe`      | Slides in from the right — directional flow          |
+| `typewriter` | Character-by-character reveal — focused              |
+| `bounce`     | Drops from above with a soft bounce                  |
+
+#### Modern
+
+| Value       | Description                                              |
+|-------------|----------------------------------------------------------|
+| `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               |
+| `ripple`    | Words scale out from a compressed point — elastic        |
+| `cinch`     | Characters pinch then snap open — crisp & mechanical     |
+| `tiltrise`  | Words rise while untilting from a lean — editorial       |
+
+#### New mechanics
+
+| Value        | Description                                              |
+|--------------|----------------------------------------------------------|
+| `unfurl`     | Line expands from horizontal center — origami opening    |
+| `billboard`  | Whole line rotates in on Y-axis — turning sign           |
+| `tectonic`   | Words slam from alternating sides with skew              |
+| `stratify`   | Per-word Z-depth flight through blur — depth-of-field    |
+| `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     |
+| `slab`       | Words stamp from left with scaleX — print-press energy   |
+| `thread`     | Characters float on individual sine-wave Y offsets       |
+| `glassReveal`| Backdrop blur evaporates as text solidifies              |
+| `wordPop`    | Per-word spring from zero scale at its own centre        |
+| `scanline`   | Single-pixel horizontal slice expands to full height     |
+| `chromaShift`| RGB channel offsets collapse to zero — printing register |
+| `wordFade`   | Per-word cross-dissolve with warmth scale                |
+| `rotateIn`   | Full Y-axis card-flip per word — face-up reveal          |
+| `pressIn`    | Presses to 0.92 then springs past 1 — physical button    |
+| `unfurl`     | Text splits open from center — origami feel              |
+| `dissolve`   | Characters dissolve in with random micro-rotation        |
+| `depth`      | Z-axis push from far to near — immersive 3D              |
+| `maskSweep`  | Mask-image sweep reveals text left to right              |
+| `gradSweep`  | Gradient sweep across text then resolves to solid        |
 
 All animations use only `transform`, `opacity`, and `filter` — GPU-composited, no layout thrashing, 60fps safe.
 
 ---
 
-## Italic Accent
+## Custom Motion — `motionConfig`
 
-When `italic={true}` (the default), any `<em>` tag inside a `Display` or `H1` hero renders in **Instrument Serif italic** with an accent color. This creates a classic editorial contrast between a bold sans-serif header and a refined serif word.
+When the built-in presets don't fit, write your own keyframe. Works on **any variant**, not just heroes.
 
 ```tsx
-// With italic accent (default)
-<Typography variant="Display" font="Bricolage Grotesque">
-  Build with <em>intention</em>
-</Typography>
+import { Typography, type MotionConfig } from "@edwinvakayil/calligraphy";
+```
 
-// Turn off — everything renders in the heading font
-<Typography variant="Display" font="Bricolage Grotesque" italic={false}>
-  Build with <em>intention</em>
+### Whole-element animation
+
+```tsx
+<Typography
+  variant="H2"
+  font="Syne"
+  motionConfig={{
+    keyframes: `from { opacity: 0; transform: translateY(24px) skewX(6deg); }
+                to   { opacity: 1; transform: none; }`,
+    duration: "0.8s",
+    easing:   "cubic-bezier(0.16, 1, 0.3, 1)",
+    delay:    "0.1s",
+  }}
+>
+  Section heading
 </Typography>
 ```
 
-### Custom accent color
+### Per-word stagger
 
 ```tsx
 <Typography
   variant="Display"
   font="Bricolage Grotesque"
-  accentColor="#7F77DD"
+  motionConfig={{
+    keyframes:    `from { opacity: 0; transform: translateX(-20px) rotate(-4deg); }
+                  to   { opacity: 1; transform: none; }`,
+    duration:     "0.65s",
+    split:        "words",
+    staggerDelay: 0.09,
+  }}
 >
-  Crafted with <em>precision</em>
+  Design with <em>intention</em>
 </Typography>
 ```
 
-The `accentColor` prop only affects the `<em>` italic span. It has no effect when `italic={false}`.
-
----
-
-## Examples
-
-### Overline + Display combo
+### Per-character stagger
 
 ```tsx
-<Typography variant="Overline" color="#6366f1">
-  New Feature
-</Typography>
 <Typography
   variant="Display"
-  font="Bricolage Grotesque"
-  animation="clip"
-  accentColor="#6366f1"
+  motionConfig={{
+    keyframes:    `from { opacity: 0; transform: scaleY(0) translateY(10px); }
+                  to   { opacity: 1; transform: none; }`,
+    duration:     "0.5s",
+    split:        "chars",
+    staggerDelay: 0.035,
+  }}
 >
-  Build faster with <em>types</em>
+  Motion
 </Typography>
 ```
 
-### Body + Caption
+### `MotionConfig` shape
 
-```tsx
-<Typography variant="Body" font="Lora">
-  A well-set paragraph in a refined serif font brings reading pleasure.
-</Typography>
-<Typography variant="Caption" color="#888">
-  Fig. 1 — System architecture overview
-</Typography>
+```ts
+interface MotionConfig {
+  keyframes:     string                          // CSS keyframe body (without @keyframes name {})
+  duration?:     string                          // default: "0.8s"
+  easing?:       string                          // default: "cubic-bezier(0.16, 1, 0.3, 1)"
+  delay?:        string                          // default: "0s"
+  fillMode?:     "none"|"forwards"|"backwards"|"both"  // default: "both"
+  split?:        "none" | "words" | "chars"      // default: "none"
+  staggerDelay?: number                          // seconds between spans; default 0.07 (words) / 0.04 (chars)
+}
 ```
 
-### Truncation
+---
+
+## Direct DOM Access — `motionRef`
+
+For full control with GSAP, Framer Motion, or the Web Animations API. The ref callback fires after mount and on every re-render.
+
+`motionRef` takes priority over both `animation` and `motionConfig`.
 
 ```tsx
-{/* Single line */}
-<Typography variant="H2" truncate>
-  This very long title will be cut off with an ellipsis
+// Web Animations API
+<Typography
+  variant="Display"
+  font="Bricolage Grotesque"
+  motionRef={(el) => {
+    if (!el) return;
+    el.animate(
+      [{ opacity: 0, transform: "translateY(32px)" }, { opacity: 1, transform: "none" }],
+      { duration: 900, easing: "cubic-bezier(0.16,1,0.3,1)", fill: "both" }
+    );
+  }}
+>
+  Full control
 </Typography>
 
-{/* Multi-line clamp */}
-<Typography variant="Body" maxLines={3}>
-  This paragraph will show at most three lines...
+// GSAP
+<Typography
+  variant="H1"
+  motionRef={(el) => {
+    if (!el) return;
+    gsap.from(el, { opacity: 0, y: 40, duration: 0.9, ease: "power3.out" });
+  }}
+>
+  GSAP powered
 </Typography>
 ```
 
-### Override HTML tag
+### Priority order
 
-```tsx
-<Typography variant="H2" as="div">
-  Renders as a div, styled as H2
-</Typography>
+```
+motionRef  >  motionConfig  >  animation  >  no animation
 ```
 
 ---
 
-## Pre-loading fonts
+## Italic Accent
 
-To avoid FOUT (flash of unstyled text), pre-load fonts at the top of your app:
+When `italic={true}`, any `<em>` tag inside a `Display` or `H1` hero renders in **Instrument Serif italic** with an accent color. Off by default.
 
 ```tsx
-import { preloadFonts } from "@edwinvakayil/calligraphy";
-
-// In your _app.tsx / main.tsx / layout.tsx
-preloadFonts(["Bricolage Grotesque", "Instrument Serif", "DM Sans"]);
-```
+// Off by default
+<Typography variant="Display" font="Bricolage Grotesque">
+  Build with <em>intention</em>
+</Typography>
 
----
+// Turn on
+<Typography variant="Display" font="Bricolage Grotesque" italic>
+  Build with <em>intention</em>
+</Typography>
 
-## Recommended hero font pairings
+// Custom accent color
+<Typography variant="Display" font="Bricolage Grotesque" italic accentColor="#7F77DD">
+  Crafted with <em>precision</em>
+</Typography>
+```
 
-| Heading font           | Style      | Works well for               |
-|------------------------|------------|------------------------------|
-| `Bricolage Grotesque`  | Bold sans  | Startups, SaaS, modern brand |
-| `Syne`                 | Geometric  | Creative, portfolio, agency  |
-| `Fraunces`             | Serif      | Editorial, luxury, fashion   |
-| `Bebas Neue`           | Condensed  | Sports, bold campaigns       |
-| `Playfair Display`     | Serif      | Journalism, books, culture   |
-| `Outfit`               | Clean sans | Apps, dashboards, fintech    |
+`accentColor` has no effect when `italic={false}`.
 
-All are on Google Fonts and auto-injected when passed to the `font` prop.
+---
 
 ## TypographyProvider
- 
+
 Wrap your app (or a section of it) with `TypographyProvider` to set defaults once. Any prop passed directly to `<Typography>` still wins — the provider is just the fallback.
- 
+
 ```tsx
-import { TypographyProvider, Typography } from "react-type-scale";
- 
+import { TypographyProvider, Typography } from "@edwinvakayil/calligraphy";
+
 export default function App() {
   return (
     <TypographyProvider
@@ -240,21 +321,16 @@ export default function App() {
         color:       "#1a1a1a",
       }}
     >
-      {/* Inherits font, accentColor, italic, animation from theme */}
+      {/* Inherits all theme values */}
       <Typography variant="Display">
         Build with <em>intention</em>
       </Typography>
- 
-      {/* Overrides just the animation — everything else from theme */}
+
+      {/* Overrides just the animation */}
       <Typography variant="H1" animation="clip">
         Another hero heading
       </Typography>
- 
-      {/* Overrides font only */}
-      <Typography variant="Body" font="Lora">
-        Body copy in a different font.
-      </Typography>
- 
+
       {/* italic=false wins over theme's italic=true */}
       <Typography variant="Display" italic={false}>
         No serif accent here
@@ -263,33 +339,33 @@ export default function App() {
   );
 }
 ```
- 
+
 ### Theme shape
- 
+
 ```ts
 interface TypographyTheme {
-  font?:        string          // Google Font name applied to all variants
+  font?:        string          // Google Font applied to all variants
   accentColor?: string          // <em> accent color for Display / H1
   italic?:      boolean         // italic accent on/off for Display / H1
   animation?:   HeroAnimation   // entrance animation for Display / H1
   color?:       string          // default text color for all variants
 }
 ```
- 
+
 ### Priority order
- 
+
 ```
 Explicit prop  >  TypographyProvider theme  >  built-in default
 ```
- 
+
 ### Nesting providers
- 
-Providers can be nested. The nearest one wins:
- 
+
+The nearest provider wins:
+
 ```tsx
 <TypographyProvider theme={{ font: "Bricolage Grotesque", color: "#111" }}>
   <Typography variant="H1">Uses Bricolage Grotesque</Typography>
- 
+
   <TypographyProvider theme={{ font: "Playfair Display", accentColor: "#e11d48" }}>
     <Typography variant="Display">
       Uses Playfair Display with red accent
@@ -298,12 +374,157 @@ Providers can be nested. The nearest one wins:
 </TypographyProvider>
 ```
 
+---
+
+## Examples
+
+### Overline + Display combo
+
+```tsx
+<Typography variant="Overline" color="#6366f1">New Feature</Typography>
+<Typography variant="Display" font="Bricolage Grotesque" animation="clip" accentColor="#6366f1">
+  Build faster with <em>types</em>
+</Typography>
+```
+
+### Body + Caption
+
+```tsx
+<Typography variant="Body" font="Lora">
+  A well-set paragraph in a refined serif font brings reading pleasure.
+</Typography>
+<Typography variant="Caption" color="#888">
+  Fig. 1 — System architecture overview
+</Typography>
+```
+
+### Truncation
+
+```tsx
+<Typography variant="H2" truncate>
+  This very long title will be cut off with an ellipsis
+</Typography>
+
+<Typography variant="Body" maxLines={3}>
+  This paragraph will show at most three lines...
+</Typography>
+```
+
+### Override HTML tag
+
+```tsx
+<Typography variant="H2" as="div">
+  Renders as a div, styled as H2
+</Typography>
+```
+
+---
+
+## Pre-loading fonts
+
+To avoid FOUT (flash of unstyled text), pre-load fonts at the top of your app:
+
+```tsx
+import { preloadFonts } from "@edwinvakayil/calligraphy";
+
+// In your _app.tsx / main.tsx / layout.tsx
+preloadFonts(["Bricolage Grotesque", "Instrument Serif", "DM Sans"]);
+```
+
+---
+
+## Recommended hero font pairings
+
+| Heading font          | Style      | Works well for               |
+|-----------------------|------------|------------------------------|
+| `Bricolage Grotesque` | Bold sans  | Startups, SaaS, modern brand |
+| `Syne`                | Geometric  | Creative, portfolio, agency  |
+| `Fraunces`            | Serif      | Editorial, luxury, fashion   |
+| `Bebas Neue`          | Condensed  | Sports, bold campaigns       |
+| `Playfair Display`    | Serif      | Journalism, books, culture   |
+| `Outfit`              | Clean sans | Apps, dashboards, fintech    |
+
+---
+
+## SSR & Next.js
+
+`@edwinvakayil/calligraphy` is fully SSR-safe. All DOM work (`<link>` and `<style>` injection) happens inside `useInsertionEffect`, which React never calls on the server. The text renders in the server HTML; animations play after hydration.
+
+### Next.js App Router
+
+```tsx
+// app/layout.tsx
+import { TypographyProvider } from "@edwinvakayil/calligraphy";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <TypographyProvider theme={{ font: "Bricolage Grotesque", accentColor: "#6366f1" }}>
+          {children}
+        </TypographyProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx
+// app/page.tsx — Server Component
+import { Typography } from "@edwinvakayil/calligraphy";
+
+export default function Page() {
+  return (
+    <Typography variant="Display" animation="rise">
+      Renders on the server, <em>animates</em> on the client
+    </Typography>
+  );
+}
+```
+
+### Next.js Pages Router
+
+```tsx
+// pages/_app.tsx
+import { TypographyProvider } from "@edwinvakayil/calligraphy";
+import type { AppProps } from "next/app";
+
+export default function App({ Component, pageProps }: AppProps) {
+  return (
+    <TypographyProvider theme={{ font: "Syne" }}>
+      <Component {...pageProps} />
+    </TypographyProvider>
+  );
+}
+```
+
+### What renders where
+
+| Prop | Server | Client |
+|------|--------|--------|
+| `variant`, `font`, `color`, `align`, `truncate`, `maxLines` | Inline styles in HTML | Hydrated |
+| `animation` | Class name in HTML | Keyframe `<style>` injected, animation plays |
+| `motionConfig` | Raw HTML (split spans present) | Animation applied after hydration |
+| `motionRef` | Plain HTML | Callback fires after hydration |
+| `italic` / `accentColor` | Inline styles on `<em>` | No flash on hydration |
+
+---
+
+## Build & Publish
+
+```bash
+npm install
+npm run build          # outputs CJS + ESM + .d.ts to /dist
+npm pack               # inspect the tarball before publishing
+npm publish --access public
+```
+
+---
+
 ## License
 
 Copyright (c) 2025 Edwin Vakayil. All rights reserved.
 
-This package is proprietary software. You may install and use it for personal
-or internal business purposes, but you may not copy, modify, distribute, or
-create derivative works from it without explicit written permission from the author.
+This package is proprietary software. You may install and use it for personal or internal business purposes, but you may not copy, modify, distribute, or create derivative works from it without explicit written permission from the author.
 
 See the [LICENSE](./LICENSE) file for full terms.

package/dist/animation.d.ts

@@ -10,3 +10,22 @@ 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;
+/**
+ * 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.
+ */
+declare function injectCustomKeyframes(keyframeBody: string): string;
+/**
+ * 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").
+ */
+export declare function buildCustomHTML(html: string, keyframeName: string, duration: string, easing: string, delay: string, fillMode: string, split: "none" | "words" | "chars", staggerDelay: number): {
+    html: string;
+    baseAnimation: string;
+};
+export { injectCustomKeyframes };