gclass-anims 1.0.0-beta.1

package/README.md

@@ -0,0 +1,98 @@
+# GClass
+
+A Tailwind-style utility layer on top of GSAP which I started developing for fun but it got WAY out of hand
+
+Framework-agnostic: works in vanilla JS, React, Vue, Svelte, or any bundler.
+
+## Installation
+
+```
+npm install gclass-anims
+```
+
+GSAP is installed automatically as a dependency.
+
+> GSAP is not bundled into this package. It is used under the Webflow Standard
+> No-Charge GSAP License and installed separately via npm.
+
+## Quick start
+
+Import the public API and call `initAnimations()` once the DOM is ready.
+
+### Vanilla JS
+
+```html
+<script type="module">
+  import { initAnimations } from 'gclass-anims'
+  initAnimations()
+</script>
+```
+
+### React (any component)
+
+```jsx
+import { useEffect } from 'react'
+import { initAnimations } from 'gclass-anims'
+
+function App() {
+  useEffect(() => {
+    initAnimations()
+    // optional cleanup: re-call to reset, or call a returned teardown
+  }, [])
+  return <div>...</div>
+}
+```
+
+### Vue
+
+```js
+import { onMounted } from 'vue'
+import { initAnimations } from 'gclass-anims'
+
+export default {
+  setup() {
+    onMounted(() => initAnimations())
+  },
+}
+```
+
+## Usage
+
+Add utility classes to your markup. Everything is class-driven — no config.
+
+```html
+<div class="spawn-up">reveals sliding up on scroll</div>
+<div class="float">loops a floating animation</div>
+<button class="magnet click-expand">magnet + click</button>
+```
+
+### Toggling animations
+
+```js
+import { initAnimations, toggleAnimations } from 'gclass-anims'
+
+toggleAnimations() // persists the choice to localStorage and reloads
+```
+
+### Custom animations
+
+Add entries to `customAnims` (a class, `from` state, and a `play` callback) and
+they integrate with the existing scroll/leave/order/delay/ease machinery.
+
+```js
+import { customAnims } from 'gclass-anims'
+
+customAnims.push({
+  sel: '.whirl',
+  from: { opacity: 0, rotation: 90, scale: 0.7 },
+  play: (el, delay, dur, ease) =>
+    gsap.fromTo(el, { opacity: 0, rotation: 90, scale: 0.7 }, {
+      ease, duration: dur, delay, rotation: 0, scale: 1, opacity: 1,
+    }),
+})
+```
+
+## License
+
+MIT — except GSAP, which is used under the Webflow Standard No-Charge GSAP
+License and is not bundled or redistributed.

package/index.d.ts

@@ -0,0 +1,180 @@
+// Type definitions for gclass (GClass)
+// A Tailwind-style utility layer on top of GSAP.
+// This file describes the public API exported from index.js.
+
+// --- AnimToggle ------------------------------------------------------------
+
+/** Boots the GSAP animation system (idempotent). */
+export function initAnimations(): void
+/** Toggle animations on/off and reload the page. */
+export function toggleAnimations(): void
+/** Force animations off (wins over any stored preference) and reload. */
+export function enableReducedMotion(): void
+/** Clear the forced reduced-motion override and reload. */
+export function disableReducedMotion(): void
+
+// --- Listeners -------------------------------------------------------------
+
+/** Type of a function an onComplete hook resolves to. */
+export type CompleteHandler = (el: HTMLElement) => void
+
+/**
+ * Register a named onComplete handler, referenced from markup via
+ * `on-<kind>-complete-<name>` (spawn / loop / click).
+ */
+export function registerComplete(name: string, fn: CompleteHandler): CompleteHandler
+
+/**
+ * Boot the engine directly, bypassing AnimToggle. Returns a teardown function
+ * that removes all listeners/observers/tweens created by this run.
+ */
+export default function initListeners(): () => void
+
+// --- onComplete config -----------------------------------------------------
+
+/** Per-element timing/ease classes bundled for `build`/`setup` handlers. */
+export interface LoopCtx {
+  edelay: number
+  amount: number
+  etime: number
+  ease: string
+  time: number
+  mH: number
+  mV: number
+  radiateZ: number | null
+}
+
+/**
+ * A declarative animation definition. Add entries to `animations` or push to
+ * `customAnims`. The engine inspects which fields are present and wires up the
+ * matching behaviour (scroll / order / leave / appear / loop) automatically.
+ */
+export interface AnimationConfig {
+  /** The className you put on elements, e.g. ".spawn-up". */
+  sel: string
+  /** Optional hidden starting state (enables leave/scroll reversal). */
+  from?: Record<string, any>
+  /** Entrance (load / appear / scroll-enter) tween. Return a tween or timeline. */
+  play?: (el: HTMLElement, delay: number, dur: number, ease: string) => any
+  /** Looping animation. Return a tween/timeline; engine applies repeat(-1). */
+  build?: (el: HTMLElement, ctx: LoopCtx) => any
+  /** Storage key for the loop tween on the element (defaults to `sel`). */
+  key?: string
+  /** Marks a TextPlugin typewriter entry. */
+  typewriter?: boolean
+  /** Marks a per-part (SplitText) typewriter entry. */
+  typewriterSplit?: boolean
+  /** Set false to skip generating a `.spawn-text-<name>` variant. Default true. */
+  text?: boolean
+  /** Set false to keep `build` but skip the always-on repeat. Default true. */
+  loop?: boolean
+  /** "Special abilities" hook. If it returns a function, that runs on teardown. */
+  setup?: (el: HTMLElement, ctx: LoopCtx) => void | (() => void)
+}
+
+/** A spawnConfigs entry (has a `play`). */
+export interface SpawnConfig {
+  sel: string
+  from?: Record<string, any>
+  play: (el: HTMLElement, delay: number, dur: number, ease: string) => any
+  typewriter?: boolean
+  typewriterSplit?: boolean
+  text: boolean
+}
+
+/** A loopConfigs entry (has a `build`). */
+export interface LoopConfig {
+  sel: string
+  build: (el: HTMLElement, ctx: LoopCtx) => any
+  key: string
+  loop: boolean
+}
+
+/** Result of `normalize()`. */
+export interface NormalizedConfig {
+  all: AnimationConfig[]
+  spawnConfigs: SpawnConfig[]
+  loopConfigs: LoopConfig[]
+}
+
+// --- Config ----------------------------------------------------------------
+
+export interface Defaults {
+  orderDivide: number
+  spawnDelayMultiplier: number
+  spawnOffset: number
+  clickOffset: number
+  clickExpandOffset: number
+  clickDuration: number
+  ease: string
+  effectDelay: number
+  effectDuration: number
+  effectOffset: number
+  progressStart: string
+  progressEnd: string
+  textStagger: number
+  typewriterSplitCharDuration: number
+  minTextPartDuration: number
+}
+
+/** Global timing / ease defaults (edit to tweak global behaviour). */
+export const defaults: Defaults
+
+/** Built-in animation definitions (add / remove entries here). */
+export const animations: AnimationConfig[]
+
+/** Derived spawn/loop views of the config, plus the merged `all` list. */
+export function normalize(extra?: AnimationConfig[]): NormalizedConfig
+
+// --- CustomAnims -----------------------------------------------------------
+
+/** User-supplied animations, merged into the engine at init time. */
+export const customAnims: AnimationConfig[]
+
+/** Example manual helper (not wired into listeners). */
+export function Example(target: any, customVars: object): any
+
+// --- Animations ------------------------------------------------------------
+
+/** A GSAP tweenable target (element / selector / array). */
+export type TweenTarget = any
+
+/** Spawn an element vertically by `dir` px. */
+export function SpawnV(target: TweenTarget, delay: number, dir: number, dur: number, ease: string): any
+/** Spawn an element horizontally by `dir` px. */
+export function SpawnH(target: TweenTarget, delay: number, dir: number, dur: number, ease: string): any
+export function expandV(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function expandH(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function expandA(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function typewriter(target: TweenTarget, text: string, dur: number, delay: number, ease: string): any
+export function spawnSpinCCW(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function spawnSpinCW(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function spawnFade(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function spawnBlur(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function spawnXUp(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function spawnXDown(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function spawnYRight(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function spawnYLeft(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function expandRight(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function expandLeft(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function expandUp(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function expandDown(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function countUp(target: TweenTarget, delay: number, dur: number, ease: string): any
+/** Reads a count element's start (`.spawn-num-N`, else 0), target number, and decimals. */
+export function countTargetVars(target: TweenTarget): { start: number; end: number; decimals: number }
+export function verticalmove(target: TweenTarget, amount: number, dur: number, ease: string): any
+export function expandmove(target: TweenTarget, amount: number, dur: number, ease: string): any
+export function magnet(target: TweenTarget, x: number, y: number, scale: number, dur: number, ease: string): any
+export function magnet3d(target: TweenTarget, x: number, y: number, scale: number, rotX: number, rotY: number, dur: number, ease: string): any
+export function reset(target: TweenTarget, dur: number, ease: string): any
+export function spinCW(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function spinCCW(target: TweenTarget, delay: number, dur: number, ease: string): any
+export function bounce(delay: number, target: TweenTarget, amount: number, dur: number, ease: string): any
+export function shake(delay: number, target: TweenTarget, amount: number, dur: number, ease: string): any
+export function bell(delay: number, target: TweenTarget, amount: number, dur: number, ease: string): any
+export function pulse(delay: number, target: TweenTarget, amount: number, dur: number, ease: string): any
+export function radiate(delay: number, target: TweenTarget, amount: number, dur: number, ease: string, zIndex: any): any
+export function hover(delay: number, target: TweenTarget, amount: number, dur: number, ease: string): any
+export function marquee(target: TweenTarget, dir: string, duration: number, xOffset?: number, yOffset?: number, noRepeat?: boolean): any
+export function flip(state: any, ease: string, dur: number): any
+export function animatecss(target: TweenTarget, dur: number, delay: number, ease: string, propertyS: any, propertySValue: any, propertyE: any, propertyEValue: any): any

package/index.js

@@ -0,0 +1,5 @@
+export { initAnimations, toggleAnimations, enableReducedMotion, disableReducedMotion } from './AnimToggle.js'
+export { default as initListeners, registerComplete } from './Listeners.js'
+export { customAnims } from './CustomAnims.js'
+export { defaults, animations, normalize } from './Config.js'
+export * from './Animations.js'

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "gclass-anims",
+  "version": "1.0.0-beta.1",
+  "description": "A Tailwind-style utility layer on top of GSAP. Framework-agnostic — works in vanilla JS, React, Vue, Svelte, or any bundler.",
+  "type": "module",
+  "main": "index.js",
+  "module": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "AnimToggle.js",
+    "Listeners.js",
+    "Animations.js",
+    "Config.js",
+    "CustomAnims.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "gsap",
+    "animation",
+    "scrolltrigger",
+    "splittext",
+    "utilities",
+    "framework-agnostic",
+    "css-classes"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Saturn-sepehr/GClass.git",
+    "directory": "/"
+  },
+  "homepage": "https://github.com/Saturn-sepehr/GClass#readme",
+  "dependencies": {
+    "gsap": "^3.15.0"
+  },
+  "peerDependenciesMeta": {},
+  "engines": {
+    "node": ">=16"
+  }
+}