scroll-text-reveal 0.1.0

package/README.md

@@ -0,0 +1,149 @@
+# scroll-text-reveal
+
+A tiny TypeScript library that reveals text line by line when it enters the
+viewport. Built for static websites with GSAP, ScrollTrigger, and SplitText.
+
+## Features
+
+- Line-by-line masked text reveal
+- One small function and seven practical options
+- Configurable duration, trigger delay, line stagger, distance, start position,
+  and easing
+- Optional animation for elements visible during initialization
+- Responsive line re-splitting after font loading and width changes
+- Automatic screen-reader attributes through SplitText
+- Automatic `prefers-reduced-motion` safeguard
+- Duplicate initialization protection
+- ESM, CommonJS, and TypeScript declarations
+
+## Installation
+
+```bash
+pnpm add scroll-text-reveal gsap
+```
+
+```bash
+npm install scroll-text-reveal gsap
+```
+
+```bash
+yarn add scroll-text-reveal gsap
+```
+
+GSAP 3.13 or newer is required.
+
+## Quick start
+
+Add a selector to the text you want to reveal:
+
+```html
+<h2 data-scroll-text-reveal>
+  A heading that reveals one line at a time.
+</h2>
+```
+
+Initialize it once after the page markup is available:
+
+```ts
+import { scrollTextReveal } from "scroll-text-reveal";
+
+scrollTextReveal("[data-scroll-text-reveal]");
+```
+
+The function accepts a CSS selector, one `HTMLElement`, or an iterable
+collection of `HTMLElement`s.
+
+## Configuration
+
+```ts
+scrollTextReveal(".reveal-heading", {
+  duration: 0.85,
+  delay: 0,
+  stagger: 0.1,
+  distance: 115,
+  start: 86,
+  ease: "power3.out",
+  animateInitiallyVisible: false,
+});
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `duration` | `number` | `0.85` | Animation duration in seconds |
+| `delay` | `number` | `0` | Pause after the element reaches its viewport start position |
+| `stagger` | `number` | `0.1` | Delay between consecutive lines in seconds |
+| `distance` | `number` | `115` | Initial vertical offset as a percentage of each line |
+| `start` | `number` | `86` | Viewport percentage at which the reveal starts |
+| `ease` | `string` | `power3.out` | GSAP easing name |
+| `animateInitiallyVisible` | `boolean` | `false` | Animate text already visible during initialization |
+
+`start: 86` means that the animation is triggered when the top of the element
+reaches a point 86% down the viewport.
+
+### Delayed reveal
+
+`delay` starts after ScrollTrigger activates the animation:
+
+```ts
+scrollTextReveal(".delayed-heading", {
+  delay: 0.5,
+});
+```
+
+### Initially visible text
+
+By default, text already visible when `scrollTextReveal()` runs is left
+untouched. Enable its animation explicitly:
+
+```ts
+scrollTextReveal(".hero-heading", {
+  animateInitiallyVisible: true,
+  delay: 0.2,
+});
+```
+
+### Direct elements
+
+```ts
+const heading = document.querySelector<HTMLElement>(".heading");
+
+if (heading) {
+  scrollTextReveal(heading);
+}
+```
+
+```ts
+scrollTextReveal(document.querySelectorAll<HTMLElement>(".reveal"));
+```
+
+Calling `scrollTextReveal()` more than once for an element is safe. An element
+that has already been initialized is ignored.
+
+## Accessibility
+
+When a visitor requests reduced motion, the function returns before splitting
+or animating any text.
+
+SplitText uses `aria: "auto"` so the original text is exposed as a single
+accessible label while generated lines are hidden from screen readers. For text
+containing interactive nested elements such as links, review the alternative
+accessibility strategy in the
+[SplitText documentation](https://gsap.com/docs/v3/Plugins/SplitText/).
+
+## Browser support
+
+The library targets modern browsers supported by GSAP and requires a browser
+DOM. Call it after the relevant HTML has been parsed, either from a module at
+the end of `body` or after `DOMContentLoaded`.
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+pnpm build:docs
+```
+
+Use `pnpm dev` to open the demo.

package/dist/ScrollTextReveal.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A CSS selector, HTML element, or iterable collection of HTML elements.
+ */
+export type ScrollTextRevealTarget = string | HTMLElement | Iterable<HTMLElement>;
+/**
+ * Controls the line reveal animation.
+ */
+export interface ScrollTextRevealOptions {
+    /** Animation duration in seconds. */
+    duration?: number;
+    /** Delay in seconds after the element reaches its viewport start position. */
+    delay?: number;
+    /** Delay in seconds between consecutive lines. */
+    stagger?: number;
+    /** Initial vertical offset as a percentage of each line. */
+    distance?: number;
+    /** Viewport percentage at which the animation starts. */
+    start?: number;
+    /** Any GSAP ease name accepted by gsap.from(). */
+    ease?: string;
+    /** Animate elements already visible when scrollTextReveal() is called. */
+    animateInitiallyVisible?: boolean;
+}
+export interface ScrollTextRevealDefaults {
+    readonly duration: number;
+    readonly delay: number;
+    readonly stagger: number;
+    readonly distance: number;
+    readonly start: number;
+    readonly ease: string;
+    readonly animateInitiallyVisible: boolean;
+}
+export declare const scrollTextRevealDefaults: ScrollTextRevealDefaults;
+/**
+ * Reveals text line by line when it enters the viewport.
+ *
+ * Calling the function more than once for the same element is safe: an element
+ * is initialized only once.
+ *
+ * @example
+ * scrollTextReveal("[data-scroll-text-reveal]", {
+ *   duration: 0.9,
+ *   delay: 0.15,
+ *   stagger: 0.08,
+ * });
+ */
+export declare const scrollTextReveal: (target: ScrollTextRevealTarget, options?: ScrollTextRevealOptions) => void;

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";var g=Object.create;var i=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var x=Object.getOwnPropertyNames;var R=Object.getPrototypeOf,w=Object.prototype.hasOwnProperty;var S=(t,e)=>{for(var r in e)i(t,r,{get:e[r],enumerable:!0})},d=(t,e,r,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let l of x(e))!w.call(t,l)&&l!==r&&i(t,l,{get:()=>e[l],enumerable:!(n=v(e,l))||n.enumerable});return t};var E=(t,e,r)=>(r=t!=null?g(R(t)):{},d(e||!t||!t.__esModule?i(r,"default",{value:t,enumerable:!0}):r,t)),M=t=>d(i({},"__esModule",{value:!0}),t);var L={};S(L,{scrollTextReveal:()=>y,scrollTextRevealDefaults:()=>c});module.exports=M(L);var a=E(require("gsap"),1),p=require("gsap/ScrollTrigger"),s=require("gsap/SplitText"),c=Object.freeze({duration:.85,delay:0,stagger:.1,distance:115,start:86,ease:"power3.out",animateInitiallyVisible:!1}),m=new WeakSet,T=!1,h=()=>{T||(a.default.registerPlugin(p.ScrollTrigger,s.SplitText),T=!0)},f=t=>typeof HTMLElement<"u"&&t instanceof HTMLElement,H=t=>{if(typeof document>"u")throw new Error("scrollTextReveal requires a browser DOM.");if(typeof t=="string")try{return Array.from(document.querySelectorAll(t))}catch{throw new TypeError(`scrollTextReveal received an invalid selector: "${t}".`)}if(f(t))return[t];if(t&&typeof t[Symbol.iterator]=="function"){let e=Array.from(t);if(e.every(f))return e}throw new TypeError("scrollTextReveal target must be a CSS selector, HTMLElement, or iterable of HTMLElements.")},o=(t,e,r,n=Number.POSITIVE_INFINITY)=>{if(!Number.isFinite(e)||e<r||e>n){let l=Number.isFinite(n)?`between ${r} and ${n}`:`greater than or equal to ${r}`;throw new RangeError(`scrollTextReveal option "${t}" must be ${l}.`)}return e},I=t=>{let e={...c,...t};if(o("duration",e.duration,0),o("delay",e.delay,0),o("stagger",e.stagger,0),o("distance",e.distance,0),o("start",e.start,0,100),typeof e.ease!="string"||!e.ease.trim())throw new TypeError('scrollTextReveal option "ease" must be a non-empty string.');if(typeof e.animateInitiallyVisible!="boolean")throw new TypeError('scrollTextReveal option "animateInitiallyVisible" must be a boolean.');return e},O=t=>{let e=t.getBoundingClientRect();return e.top<window.innerHeight&&e.bottom>0},y=(t,e={})=>{if(typeof window>"u")throw new Error("scrollTextReveal requires a browser DOM.");let r=I(e),n=H(t);if(!(window.matchMedia?.("(prefers-reduced-motion: reduce)").matches||n.length===0)){h();for(let l of n){if(m.has(l))continue;let u=O(l);u&&!r.animateInitiallyVisible||(s.SplitText.create(l,{type:"lines",mask:"lines",linesClass:"scroll-text-reveal-line",autoSplit:!0,aria:"auto",onSplit:b=>a.default.from(b.lines,{yPercent:r.distance,opacity:0,duration:r.duration,delay:r.delay,stagger:r.stagger,ease:r.ease,...u?{}:{scrollTrigger:{trigger:l,start:`top ${r.start}%`,once:!0}}})}),m.add(l))}}};0&&(module.exports={scrollTextReveal,scrollTextRevealDefaults});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { scrollTextReveal, scrollTextRevealDefaults, } from "./ScrollTextReveal.js";
+export type { ScrollTextRevealDefaults, ScrollTextRevealOptions, ScrollTextRevealTarget, } from "./ScrollTextReveal.js";

package/dist/index.js

@@ -0,0 +1 @@
+import u from"gsap";import{ScrollTrigger as f}from"gsap/ScrollTrigger";import{SplitText as d}from"gsap/SplitText";var m=Object.freeze({duration:.85,delay:0,stagger:.1,distance:115,start:86,ease:"power3.out",animateInitiallyVisible:!1}),a=new WeakSet,s=!1,p=()=>{s||(u.registerPlugin(f,d),s=!0)},c=t=>typeof HTMLElement<"u"&&t instanceof HTMLElement,y=t=>{if(typeof document>"u")throw new Error("scrollTextReveal requires a browser DOM.");if(typeof t=="string")try{return Array.from(document.querySelectorAll(t))}catch{throw new TypeError(`scrollTextReveal received an invalid selector: "${t}".`)}if(c(t))return[t];if(t&&typeof t[Symbol.iterator]=="function"){let e=Array.from(t);if(e.every(c))return e}throw new TypeError("scrollTextReveal target must be a CSS selector, HTMLElement, or iterable of HTMLElements.")},o=(t,e,r,n=Number.POSITIVE_INFINITY)=>{if(!Number.isFinite(e)||e<r||e>n){let l=Number.isFinite(n)?`between ${r} and ${n}`:`greater than or equal to ${r}`;throw new RangeError(`scrollTextReveal option "${t}" must be ${l}.`)}return e},b=t=>{let e={...m,...t};if(o("duration",e.duration,0),o("delay",e.delay,0),o("stagger",e.stagger,0),o("distance",e.distance,0),o("start",e.start,0,100),typeof e.ease!="string"||!e.ease.trim())throw new TypeError('scrollTextReveal option "ease" must be a non-empty string.');if(typeof e.animateInitiallyVisible!="boolean")throw new TypeError('scrollTextReveal option "animateInitiallyVisible" must be a boolean.');return e},g=t=>{let e=t.getBoundingClientRect();return e.top<window.innerHeight&&e.bottom>0},v=(t,e={})=>{if(typeof window>"u")throw new Error("scrollTextReveal requires a browser DOM.");let r=b(e),n=y(t);if(!(window.matchMedia?.("(prefers-reduced-motion: reduce)").matches||n.length===0)){p();for(let l of n){if(a.has(l))continue;let i=g(l);i&&!r.animateInitiallyVisible||(d.create(l,{type:"lines",mask:"lines",linesClass:"scroll-text-reveal-line",autoSplit:!0,aria:"auto",onSplit:T=>u.from(T.lines,{yPercent:r.distance,opacity:0,duration:r.duration,delay:r.delay,stagger:r.stagger,ease:r.ease,...i?{}:{scrollTrigger:{trigger:l,start:`top ${r.start}%`,once:!0}}})}),a.add(l))}}};export{v as scrollTextReveal,m as scrollTextRevealDefaults};

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "scroll-text-reveal",
+  "version": "0.1.0",
+  "description": "A tiny GSAP-powered line reveal for text entering the viewport.",
+  "keywords": [
+    "text-reveal",
+    "scroll-animation",
+    "split-text",
+    "gsap",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dmitry-conquer/scroll-text-reveal.git"
+  },
+  "homepage": "https://github.com/dmitry-conquer/scroll-text-reveal#readme",
+  "bugs": {
+    "url": "https://github.com/dmitry-conquer/scroll-text-reveal/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "packageManager": "pnpm@11.10.0",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "dev": "vite --config vite.docs.config.ts --open",
+    "build": "tsup src/index.ts --format esm,cjs --clean --minify && tsc -p tsconfig.build.json",
+    "build:docs": "vite build --config vite.docs.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepack": "pnpm run build",
+    "prepublishOnly": "pnpm run typecheck && pnpm test"
+  },
+  "peerDependencies": {
+    "gsap": ">=3.13.0 <4"
+  },
+  "devDependencies": {
+    "gsap": "^3.15.0",
+    "happy-dom": "^20.11.0",
+    "tsup": "^8.5.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.1.5",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}