anton-abyzov/vskill

GSAP

Contrat HyperFrames

HyperFrames contrôle GSAP via son adaptateur gsap d'exécution. Créez une timeline en pause de manière synchrone, enregistrez-la dans window.__timelines avec le data-composition-id exact, et laissez HyperFrames la parcourir.

<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });

  tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
  tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);

  window.__timelines["main"] = tl; // la clé doit être égale à data-composition-id sur la racine de la composition
</script>

• La clé du registre doit correspondre au data-composition-id de la racine de la composition.
• N'appelez pas tl.play() pour un mouvement critique au rendu.
• Ne construisez pas de timelines dans du code asynchrone, des minuteries ou des gestionnaires d'événements.
• Gardez les boucles finies. HyperFrames rend des durées vidéo finies.

Méthodes de Tweening de Base

• gsap.to(cibles, vars) — anime de l'état actuel vers vars. Le plus courant.
• gsap.from(cibles, vars) — anime de vars vers l'état actuel (entrées).
• gsap.fromTo(cibles, varsDépart, varsArrivée) — début et fin explicites.
• gsap.set(cibles, vars) — applique immédiatement (durée 0).

Utilisez toujours les noms de propriétés en camelCase (par ex. backgroundColor, rotationX).

Variables Communes

• duration — secondes (par défaut 0.5).
• delay — secondes avant le début.
• ease — "power1.out" (par défaut), "power3.inOut", "back.out(1.7)", "elastic.out(1, 0.3)", "none".
• stagger — nombre 0.1 ou objet : { amount: 0.3, from: "center" }, { each: 0.1, from: "random" }.
• overwrite — false (par défaut), true, ou "auto".
• repeat — nombre fini ; jamais -1 dans HyperFrames. Calculez les répétitions à partir de la durée visible. yoyo — alterne la direction avec la répétition.
• onComplete, onStart, onUpdate — callbacks.
• immediateRender — par défaut true pour from()/fromTo(). Mettez false sur les tweens ultérieurs ciblant la même propriété + élément pour éviter l'écrasement.

Transformations et CSS

Préférez les alias de transformation de GSAP plutôt que la chaîne transform brute :

Propriété GSAP	Équivalent
x, y, z	translateX/Y/Z (px)
xPercent, yPercent	translateX/Y en %
scale, scaleX, scaleY	scale
rotation	rotate (deg)
rotationX, rotationY	rotate 3D
skewX, skewY	skew
transformOrigin	transform-origin

• autoAlpha — préférez à opacity. À 0 : définit également visibility: hidden.
• Variables CSS — "--hue": 180.
• svgOrigin (SVG uniquement) — origine dans l'espace de coordonnées SVG global. Ne combinez pas avec transformOrigin.
• Rotation directionnelle — "360_cw", "-170_short", "90_ccw".
• clearProps — "all" ou séparé par des virgules ; supprime les styles en ligne à la fin.
• Valeurs relatives — "+=20", "-=10", "*=2".

Valeurs Basées sur des Fonctions

gsap.to(".item", {
  x: (i, target, targets) => i * 50,
  stagger: 0.1,
});

Easing

Easing intégrés : power1–power4, back, bounce, circ, elastic, expo, sine. Chacun a .in, .out, .inOut.

Valeurs par Défaut

gsap.defaults({ duration: 0.6, ease: "power2.out" });

Contrôle des Tweens

const tween = gsap.to(".box", { x: 100 });
tween.pause();
tween.play();
tween.reverse();
tween.kill();
tween.progress(0.5);
tween.time(0.2);

gsap.matchMedia() (Responsive + Accessibilité)

Exécute la configuration uniquement lorsqu'une requête média correspond ; se rétablit automatiquement lorsqu'elle cesse de correspondre.

let mm = gsap.matchMedia();
mm.add(
  {
    isDesktop: "(min-width: 800px)",
    reduceMotion: "(prefers-reduced-motion: reduce)",
  },
  (context) => {
    const { isDesktop, reduceMotion } = context.conditions;
    gsap.to(".box", {
      rotation: isDesktop ? 360 : 180,
      duration: reduceMotion ? 0 : 2,
    });
  },
);

---

Timelines

Créer une Timeline

const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });
tl.to(".a", { x: 100 }).to(".b", { y: 50 }).to(".c", { opacity: 0 });

Paramètre de Position

Le troisième argument contrôle le placement :

• Absolu : 1 — à 1s
• Relatif : "+=0.5" — après la fin ; "-=0.2" — avant la fin
• Label : "intro", "intro+=0.3"
• Alignement : "<" — même début que le précédent ; ">" — après la fin du précédent ; "<0.2" — 0.2s après le début du précédent

tl.to(".a", { x: 100 }, 0);
tl.to(".b", { y: 50 }, "<"); // même début que .a
tl.to(".c", { opacity: 0 }, "<0.2"); // 0.2s après le début de .b

Labels

tl.addLabel("intro", 0);
tl.to(".a", { x: 100 }, "intro");
tl.addLabel("outro", "+=0.5");
tl.play("outro");
tl.tweenFromTo("intro", "outro");

Options de Timeline

• paused: true — crée en pause ; appelez .play() pour démarrer.
• repeat, yoyo — appliquez à toute la timeline.
• defaults — variables fusionnées dans chaque tween enfant.

Imbrication de Timelines

const master = gsap.timeline();
const child = gsap.timeline();
child.to(".a", { x: 100 }).to(".b", { y: 50 });
master.add(child, 0);

Contrôle de Lecture

tl.play(), tl.pause(), tl.reverse(), tl.restart(), tl.time(2), tl.progress(0.5), tl.kill().

---

Performance

Préférez Transformation et Opacité

Animer x, y, scale, rotation, opacity reste sur le compositeur. Évitez width, height, top, left lorsque des transformations obtiennent le même effet.

will-change

will-change: transform;

Uniquement sur les éléments qui animent réellement.

gsap.quickTo() pour les Mises à Jour Fréquentes

let xTo = gsap.quickTo("#id", "x", { duration: 0.4, ease: "power3" }),
  yTo = gsap.quickTo("#id", "y", { duration: 0.4, ease: "power3" });
container.addEventListener("mousemove", (e) => {
  xTo(e.pageX);
  yTo(e.pageY);
});

Stagger > Plusieurs Tweens

Utilisez stagger plutôt que des tweens séparés avec des retards manuels.

Nettoyage

Mettez en pause ou tuez les animations hors écran.

---

Références (chargées à la demande)

• references/effects.md — Effets prêts à l'emploi : texte machine à écrire, visualiseur audio. Lisez lorsque vous avez besoin de modèles d'effets prêts à l'emploi pour HyperFrames.

Bonnes Pratiques

• Utilisez les noms de propriétés en camelCase ; préférez les alias de transformation et autoAlpha.
• Préférez les timelines à l'enchaînement avec delay ; utilisez le paramètre de position.
• Ajoutez des labels avec addLabel() pour un séquencement lisible.
• Passez les valeurs par défaut dans le constructeur de la timeline.
• Stockez la valeur de retour du tween/timeline lors du contrôle de la lecture.

À Ne Pas Faire

• Animer les propriétés de mise en page (width/height/top/left) lorsque les transformations suffisent.
• Utiliser à la fois svgOrigin et transformOrigin sur le même élément SVG.
• Enchaîner les animations avec delay lorsqu'une timeline peut les séquencer.
• Créer des tweens avant que le DOM n'existe.
• Sauter le nettoyage — tuez toujours les tweens lorsqu'ils ne sont plus nécessaires.
• Utiliser des valeurs de répétition infinies dans les compositions HyperFrames. Utilisez des nombres de répétition finis calculés à partir de la durée visible.

Crédits et Références

• Source de l'adaptateur HyperFrames : packages/core/src/runtime/adapters/gsap.ts.
• Documentation GSAP : https://gsap.com/docs/v3/
• Comportement de pause et de recherche de timeline GSAP : https://gsap.com/docs/v3/GSAP/Timeline/pause%28%29/