@topy-ai/maggie 0.8.11 → 0.8.13

package/references/web-animation-patterns.md

@@ -0,0 +1,364 @@
+# Web / UI animation patterns
+
+Engine-neutral motion vocabulary for marketing web pages, distilled from the leading
+open-source animation libraries. We adopt **patterns and per-library guidance, not
+code** — we rarely ship these libraries; we copy the technique (the eases, the
+IntersectionObserver reveal, the spring config, the Lottie workflow). Feeds
+`maggie-landing-page` (B7 motion + the mandatory tagline reveal) and
+`maggie-design-motion` (its *website* context).
+
+Rule of thumb: a marketing page needs **CSS transitions + IntersectionObserver +
+one tiny helper** far more often than a 30KB animation engine. Reach for a library
+only when the pattern below says so. Default is zero-dependency.
+
+---
+
+## 1. The libraries
+
+Each entry: what it is · core API shape (real snippet) · license · when to reach for it.
+
+### GSAP (greensock/GSAP) — v3.15
+Framework-agnostic JS animation engine: tweens, timelines, eases, plugins
+(ScrollTrigger, SplitText, MorphSVG, Flip, MotionPath). The gold standard for
+sequenced, scroll-driven work.
+```js
+gsap.registerPlugin(ScrollTrigger);
+const tl = gsap.timeline({ defaults: { ease: "power3.out", duration: 0.6 } });
+tl.from(".hero h1", { y: 40, opacity: 0 })
+  .from(".hero p",  { y: 24, opacity: 0 }, "-=0.3");   // overlap previous by 0.3s
+gsap.from(".card", {
+  scrollTrigger: { trigger: ".card", start: "top 80%", once: true },
+  y: 32, opacity: 0, stagger: 0.08,
+});
+```
+**License: custom "Standard no-charge license" (NOT MIT/OSI).** As of 2024 (Webflow)
+GSAP including all former Club plugins is 100% free for commercial use, but it is a
+proprietary license, not open source — flag it before bundling. CDN:
+`cdn.jsdelivr.net/npm/gsap@3.15/dist/gsap.min.js`.
+**Reach for it when:** a page needs a real timeline (chained, overlapping steps) or
+scroll-scrubbed sequencing beyond a one-shot reveal. Overkill for simple fades.
+
+### Motion / framer-motion (motiondivision/motion)
+Hybrid engine: a tiny imperative `animate()` for vanilla JS plus declarative
+`<motion.div>` for React/Vue. Uses the native WAAPI where possible (GPU, 120fps),
+springs, `scroll()`, `inView()`, layout transitions.
+```js
+import { animate, inView, scroll, stagger } from "motion";
+animate("#box", { x: 100, opacity: 1 }, { type: "spring", stiffness: 300, damping: 30 });
+inView(".card", (el) => { animate(el, { opacity: 1, y: 0 }); }, { amount: 0.3 });
+// React: <motion.div initial={{opacity:0,y:24}} whileInView={{opacity:1,y:0}} viewport={{once:true}}/>
+```
+**License: MIT** (core; a paid "Motion+" add-on exists but isn't required).
+**Reach for it when:** the project is already React/Vue, or you want springs +
+scroll + inView from one small MIT lib. `inView` is a clean IntersectionObserver
+wrapper — our preferred engine when a dependency is acceptable.
+
+### anime.js (juliangarnier/anime) — v4
+Small, elegant timeline/stagger/easing lib. V4 is ESM tree-shakable.
+```js
+import { animate, stagger } from "animejs";
+animate(".square", {
+  x: 320, rotate: { from: -180 }, duration: 1250,
+  delay: stagger(65, { from: "center" }), ease: "inOutQuint",
+});
+```
+**License: MIT.** **Reach for it when:** you want expressive staggers/keyframes
+lighter than GSAP and don't need ScrollTrigger-grade scroll control.
+
+### lottie-web (airbnb/lottie-web)
+Plays **Lottie JSON** (vector animations exported from After Effects via Bodymovin)
+in the browser as SVG/canvas/HTML.
+```js
+const anim = lottie.loadAnimation({
+  container: el, renderer: "svg", loop: true, autoplay: true,
+  path: "hero.json",                       // or animationData: <obj>
+});
+anim.playSegments([0, 60], true);          // play part of the timeline
+anim.setSpeed(1); anim.pause();
+```
+**License: MIT.** **Reach for it when:** a designer delivers an AE/Lottie file and
+you need a crisp, scalable, small looped illustration (see §2 Lottie workflow).
+Default to `renderer: "svg"`; switch to `canvas` for heavy/many-layer files.
+
+### rlottie (Samsung/rlottie)
+Native (C++) Lottie renderer — the runtime behind Lottie on native/embedded (not a
+web lib). Category O. **License: MIT** (mostly; some vendored parts differ, see
+COPYING). **Reach for it when:** the same Lottie JSON must also play in a native app
+(our Expo/RN surfaces) — same asset, native renderer. On web it's lottie-web.
+
+### theatre.js (theatre-js/theatre)
+In-browser motion-design **editor**: scrub a timeline, keyframe any JS object's
+props, then play the saved sequence at runtime via `@theatre/core`.
+```js
+import { getProject } from "@theatre/core";
+const sheet = getProject("Hero").sheet("Intro");
+const obj = sheet.object("Logo", { x: 0, opacity: 0 });
+obj.onValuesChange((v) => { el.style.transform = `translateX(${v.x}px)`; el.style.opacity = v.opacity; });
+sheet.sequence.play({ iterationCount: 1 });
+```
+**License: Apache-2.0.** **Reach for it when:** a complex bespoke sequence is easier
+to hand-author on a timeline than in code. Niche for marketing pages; mostly a
+design-time tool. Note for `maggie-design-motion`, not landing pages.
+
+### auto-animate (formkit/auto-animate)
+Zero-config: one call and children added/removed/moved animate automatically.
+```js
+import autoAnimate from "@formkit/auto-animate";
+autoAnimate(document.getElementById("list"));   // React: const [ref] = useAutoAnimate()
+```
+**License: MIT.** **Reach for it when:** lists, filters, accordions, or reordering UI
+need smooth transitions with no keyframes. Great low-effort polish for interactive
+sections (pricing toggles, FAQ, filtered galleries).
+
+### AOS (michalsnik/aos)
+Animate-on-scroll via HTML data-attributes + a prebuilt CSS set.
+```html
+<div data-aos="fade-up" data-aos-delay="50" data-aos-duration="800"
+     data-aos-once="true" data-aos-anchor-placement="top-center"></div>
+<script>AOS.init({ once: true, duration: 800, easing: "ease-out-cubic" });</script>
+```
+**License: MIT.** Uses IntersectionObserver internally. **Reach for it when:** a
+no-JS-authoring team wants declarative scroll reveals fast. For our output we
+usually hand-roll the same effect (§2) rather than ship AOS, but its attribute
+vocabulary (`fade-up`, `once`, per-element delay/offset) is the pattern to copy.
+
+### typed.js (mattboldt/typed.js)
+Typewriter effect.
+```js
+const typed = new Typed("#el", { strings: ["First.", "& second."], typeSpeed: 50, backSpeed: 30, loop: true });
+```
+**License: GPL — flag it.** GNU GPL, not MIT. Do **not** bundle into proprietary
+output; reimplement the ~20-line effect yourself (or use a permissive alt) if you
+need typing. **Reach for the pattern when:** a hero rotates through phrases. Keep it
+short, respect reduced-motion (render the final string statically).
+
+### tsparticles (tsparticles/tsparticles)
+Config-driven particle backgrounds/confetti.
+```js
+await tsParticles.load({ id: "tsparticles", options: {
+  background: { color: "#0d1117" },
+  particles: { number: { value: 60 }, move: { enable: true } },
+}});
+```
+**License: MIT.** **Reach for it when:** a hero wants a subtle particle/constellation
+backdrop or a celebratory confetti burst. Use sparingly — it's a performance and
+taste liability; cap particle count, pause offscreen, disable on reduced-motion.
+
+### rive (rive-app/rive-runtime)
+Interactive vector animations driven by **state machines** (inputs → states), not
+just linear playback. `rive-runtime` is the C++ core; on web you use `@rive-app/canvas`.
+```js
+import { Rive } from "@rive-app/canvas";
+const r = new Rive({ src: "button.riv", canvas, autoplay: true,
+  stateMachines: "State Machine 1", onLoad: () => r.resizeDrawingSurfaceToCanvas() });
+r.stateMachineInputs("State Machine 1").find(i => i.name === "hover").value = true;
+```
+**License: MIT.** **Reach for it when:** an element must *react* (hover/click/scroll
+drives animation state) — interactive mascots, animated toggles. Heavier workflow
+(needs the Rive editor); overkill for passive decoration — prefer Lottie for that.
+
+### vivus (maxwellito/vivus)
+Animates SVG stroke draw-on ("self-drawing" line art).
+```js
+new Vivus("my-svg", { type: "oneByOne", duration: 200, start: "inViewport" }, cb);
+// type: delayed | sync | oneByOne | scenario ; start: inViewport | manual | autostart
+```
+**License: MIT.** **Reach for it when:** a logo/icon/diagram should draw itself in.
+The same effect is achievable with CSS `stroke-dasharray`/`stroke-dashoffset` — use
+that for one element, Vivus when orchestrating many paths.
+
+### lenis (darkroomengineering/lenis)
+Smooth-scroll normalizer (momentum/eased scrolling). Already referenced by
+`maggie-clone`.
+```js
+const lenis = new Lenis({ autoRaf: true });     // or drive lenis.raf(t) in your own rAF
+lenis.on("scroll", (e) => {/* sync scroll-linked effects */});
+```
+**License: MIT.** **Reach for it when:** the design calls for premium eased scrolling
+and you pair it with scroll-triggered motion (commonly `lenis.raf` + GSAP
+ScrollTrigger). Accessibility caveat: disable/reduce under `prefers-reduced-motion`;
+never trap or override scroll in a way that breaks keyboard/anchor jumps.
+
+### barba.js (barbajs/barba)
+SPA-style page transitions over MPAs: intercepts navigation, animates the old
+container out and the new one in (no full reload).
+```js
+barba.init({ transitions: [{
+  name: "fade",
+  leave: ({ current }) => gsap.to(current.container, { opacity: 0 }),
+  enter: ({ next })    => gsap.from(next.container, { opacity: 0 }),
+}]});
+// markup: <main data-barba="wrapper"><section data-barba="container" data-barba-namespace="home">
+```
+**License: MIT.** **Reach for it when:** a multi-page marketing site wants seamless
+cross-page transitions. Needs care for SEO/analytics/scroll-restore; often more than
+a landing page needs.
+
+### react-spring (pmndrs/react-spring)
+Spring-physics animation for React (hooks).
+```js
+import { animated, useSpring } from "@react-spring/web";
+const styles = useSpring({ from: { opacity: 0, y: 24 }, to: { opacity: 1, y: 0 } });
+return <animated.div style={styles}>…</animated.div>;
+```
+**License: MIT.** **Reach for it when:** a React project wants physics-based
+(not duration-based) motion. For non-React, Motion's `spring` covers the same need.
+
+### animate.css (animate-css/animate.css)
+Prebuilt CSS keyframe classes (`animate__animated animate__fadeInUp`).
+```html
+<h1 class="animate__animated animate__fadeInUp">Hi</h1>
+```
+**License: Hippocratic License 2.1 — flag it (NOT MIT).** An ethical-source license
+with use restrictions; not OSI-approved. Treat as a caution for commercial bundling;
+the keyframe recipes (`fadeInUp`, durations, timing) are fine to **reimplement**
+yourself. **Reach for the patterns when:** you want a quick named-entrance
+vocabulary — but author your own keyframes to stay license-clean.
+
+### Category O (offline / desktop, NOT web)
+- **synfig** (synfig/synfig) — desktop 2D vector animation studio. **GPL-3.0.**
+- **friction** (friction2d/friction) — desktop motion-graphics/vector animator.
+  **GPL-3.0.** Sparse docs.
+Both are authoring tools, not runtimes. Note as offline/GPL; they can *produce*
+assets (e.g. exported video/sequences) but nothing here ships to the web.
+
+---
+
+## 2. Engine-neutral pattern set (what we actually adopt)
+
+For each pattern: the technique, which libs embody it, and where it belongs
+(**LP** = `maggie-landing-page`, **DM** = `maggie-design-motion` website context).
+
+### Eased entrances — the good cubic-beziers
+Default to expressive ease-out curves, never browser defaults (`ease`, `linear`,
+`ease-in-out`). House base curve: `cubic-bezier(0.22, 1, 0.36, 1)` ("ease-out-quint",
+~500ms for layout/position; GSAP's `power3/power4.out` equivalent). Hover
+color/opacity 300ms (never < 200ms). Other good ones: `cubic-bezier(0.16,1,0.3,1)`
+(ease-out-expo), `cubic-bezier(0.34,1.56,0.64,1)` (gentle back/overshoot).
+Libs: GSAP eases, anime `inOut*`, Motion. **LP + DM.**
+
+### Spring physics
+Duration-less, physics-based motion — natural for interactive/hover and anything
+that should feel tactile. Config shape is universal: `{ stiffness, damping, mass }`
+(Motion: `type:"spring", stiffness:300, damping:30`; react-spring: `config.gentle`).
+Libs: Motion `spring`, react-spring, GSAP (via plugins). **DM;** light touch on LP
+(mostly micro-interactions).
+
+### Scroll-reveal via IntersectionObserver — never scroll listeners
+Elements rise ~32px and fade over 600–800ms, **once**, when they cross into view.
+Always IntersectionObserver (or a lib that wraps it); never an unthrottled `scroll`
+listener. Engine-neutral baseline (no dependency):
+```js
+const io = new IntersectionObserver((entries) => {
+  for (const e of entries) if (e.isIntersecting) {
+    e.target.classList.add("in");           // CSS transitions transform+opacity
+    io.unobserve(e.target);                 // once
+  }
+}, { threshold: 0.2, rootMargin: "0px 0px -10% 0px" });
+document.querySelectorAll("[data-reveal]").forEach((el) => io.observe(el));
+```
+Libs that embody it: Motion `inView`, AOS (`data-aos` + `once`), GSAP ScrollTrigger
+(`once:true`). **LP (core) + DM.**
+
+### Stagger
+Sequence a group so items arrive one after another (reading order), stepped
+~60–80ms, capped (~400ms total for menus). Libs: GSAP `stagger`, anime
+`stagger(65,{from:"center"})`, Motion `stagger`. Hand-rolled: per-item
+`transition-delay: calc(var(--i) * 60ms)`. **LP (menu entrance, card grids) + DM.**
+
+### SVG draw-on
+Line art draws itself via `stroke-dasharray`/`stroke-dashoffset` animated to 0.
+Libs: Vivus (`type:"oneByOne"`), or pure CSS for a single path. **DM (logos,
+diagrams);** occasional LP hero accent.
+
+### Typing
+Rotate/type phrases in a hero. Pattern: type → pause → delete → next, respect
+reduced-motion by rendering the final string. Lib: typed.js (**GPL — reimplement**,
+don't bundle). **LP (hero headline variants) + DM.**
+
+### Page transitions + smooth scroll
+Cross-page: animate container out/in instead of a hard reload (barba.js, or a
+framework's view-transitions). Smooth scroll: eased momentum scrolling (lenis),
+commonly paired with scroll-triggered motion (`lenis.raf` → GSAP ScrollTrigger).
+**DM / full-site builds;** a single landing page rarely needs barba. Lenis already
+used by `maggie-clone`.
+
+### Particles
+Subtle generative backdrop or confetti. Lib: tsparticles (config: `particles.number`,
+`move`, `background`). Use sparingly; cap count, pause offscreen, kill on
+reduced-motion. **LP hero (optional accent) + DM.**
+
+### The Lottie workflow
+Pipeline: **design in After Effects → export with Bodymovin → `.json` →** play with
+**lottie-web** on web / **rlottie** on native (same JSON asset, two renderers).
+```js
+lottie.loadAnimation({ container: el, renderer: "svg", loop: true, autoplay: true, path: "hero.json" });
+```
+**When to use Lottie vs code vs looped video:**
+- **Lottie** — designer-authored vector illustration/icon motion; scalable, crisp,
+  small, loopable, recolorable, interactive (segments/speed). The default for
+  "animated illustration." Prefer `renderer:"svg"`; use `canvas` for heavy files.
+- **Code (CSS/GSAP/Motion)** — UI motion tied to the DOM: entrances, hovers,
+  scroll reveals, state changes. Anything that must respond to layout/interaction.
+- **Looped video (mp4/webm)** — photographic/complex/3D content that isn't vector
+  and doesn't need interaction or recolor. Heaviest payload; provide a poster and
+  `prefers-reduced-motion` fallback. (See `references/programmatic-video.md`.)
+Libs: lottie-web (web), rlottie (native). **DM (primary);** LP for a hero/spot
+illustration when a designer supplies the JSON.
+
+---
+
+## 3. Performance & accessibility rules (shared by all of them)
+
+- **Animate only `transform` and `opacity`.** Never `top`/`left`/`width`/`height`/
+  `margin` (they trigger layout/paint and jank). Use `transform: translate/scale`
+  for position and size. Prefer the compositor; add `will-change` only on the
+  element about to animate, and remove it after.
+- **No scroll/resize listeners for reveal.** Use IntersectionObserver for visibility
+  and `requestAnimationFrame` for any per-frame work; throttle/debounce the rest.
+  Never run animation logic directly in a `scroll` handler.
+- **Respect `prefers-reduced-motion`.** Replace movement with a plain opacity change
+  (or show the final state instantly). Gate every nontrivial effect:
+  ```css
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after { animation-duration:.01ms!important;
+      animation-iteration-count:1!important; transition-duration:.01ms!important; }
+  }
+  ```
+  In JS, branch on `matchMedia("(prefers-reduced-motion: reduce)").matches` before
+  typing, particles, smooth-scroll, or autoplay loops.
+- **Reveal once; don't re-fire** on scroll-back (`once:true` / `unobserve`).
+- **Pause offscreen / on hidden tab** (Lottie, particles, video): check
+  `document.hidden` / IntersectionObserver and stop rAF to save battery/CPU.
+- **Keep durations honest:** entrances 300–800ms; hovers 200–300ms; never block
+  interaction or delay content paint behind an animation. Don't animate above the
+  fold in a way that hides LCP text.
+
+---
+
+## License quick-reference
+
+| Library | License | Note |
+|---|---|---|
+| GSAP | Custom "no-charge" | **Not OSI/MIT.** Free (incl. all plugins) but proprietary — flag before bundling. |
+| Motion / framer-motion | MIT | Paid Motion+ add-on optional, not required. |
+| anime.js | MIT | |
+| lottie-web | MIT | |
+| rlottie | MIT | Some vendored parts differ (see COPYING). |
+| theatre.js | Apache-2.0 | |
+| auto-animate | MIT | |
+| AOS | MIT | |
+| typed.js | **GPL** | **Flag — don't bundle in proprietary output; reimplement.** |
+| tsparticles | MIT | |
+| rive-runtime | MIT | Web runtime is `@rive-app/canvas`. |
+| vivus | MIT | |
+| lenis | MIT | |
+| barba.js | MIT | |
+| react-spring | MIT | |
+| animate.css | **Hippocratic 2.1** | **Flag — ethical-source, not OSI. Reimplement keyframes.** |
+| synfig / friction | GPL-3.0 | Desktop authoring tools (category O), not web runtimes. |
+
+Most are MIT and safe to reference/learn from freely. The four to flag: **GSAP**
+(proprietary no-charge), **typed.js** (GPL), **animate.css** (Hippocratic 2.1), and
+**synfig/friction** (GPL desktop tools). For the flagged ones we adopt the *pattern*
+and author our own code.