air

Utilidad ligera para animaciones web: animacion declarativa con la Web Animations API, triggers de scroll, scroll suave y helpers (stagger, split, tween, easings).

Instalacion

npm install @angelardanaz/air

API

animate(targets, keyframes, options)

Animaciones con la Web Animations API, con normalizacion de keyframes y soporte integrado para scrollTrigger.

• targets: Element o iterable de elementos (NodeList, array).
• keyframes: array de fotogramas, objeto { from, to } o solo { to }. Si solo se declara el final, el inicio se rellena leyendo estilos computados (transform, translate/x/y, valores numericos).
• options principales:
  • duration (ms, 600 por defecto) y delay.
  • easing: nombre abreviado (i1, o3, li, etc.), string CSS o cubic-bezier(...).
  • stagger: funcion (index, total) => delay. Usa stagger() de la libreria para obtenerla facilmente.
  • onComplete: callback al terminar cada animacion ([{ el, animation }]).
  • scrollTrigger: objeto de opciones de scrollTrigger para animacion manual ligada al scroll.
• Devuelve { el, animation } (modo Web Animations) o { el, trigger } (modo scrollTrigger).

Ejemplo con solo to y stagger:

import { animate, stagger } from "@angelardanaz/air";

const cards = document.querySelectorAll(".card");

animate(cards, { to: { opacity: 1, y: 0 } }, {
  duration: 700,
  easing: "io2",
  delay: 150,
  stagger: stagger(80, { from: "center" }),
});

scrollTrigger(options)

Vincula el progreso de una animacion (o cualquier callback) al desplazamiento usando el scroll nativo del navegador o una instancia de scroll.

• scroll: instancia de scroll o deja vacio para usar el scroll nativo del navegador.
• trigger: elemento o funcion que lo devuelve.
• start / end: numero (px), string tipo "top center" (elemento viewport) o funcion que recibe { el, vh, current, maxScroll, rect, top, bottom } y devuelve una posicion absoluta.
• Callbacks: onEnter, onLeave, onUpdate({ progress, rawProgress, current, start, end, entered, el, direction, velocity }).
• Flags: once (destruye tras el primer paso), scrub (true sin suavizado o numero en ms para amortiguar), markers (muestra lineas de inicio/fin) y pin (sticky mientras se esta dentro del rango).
• Devuelve { recalc, destroy, state }.

Ejemplo ligando una animacion manual:

import { animate, scroll } from "@angelardanaz/air";

const scroller = new scroll();
const hero = document.querySelector(".hero");

animate(hero, { to: { y: -120, opacity: 0 } }, {
  easing: "io3",
  scrollTrigger: {
    scroll: scroller,
    start: "top top",
    end: "bottom center",
    scrub: 180,
  },
});

scroll (clase)

Motor de scroll suave con soporte para rueda, tactil y teclado. Respeta prefers-reduced-motion desactivando la inercia.

• Opciones: container (por defecto [data-scroll-container] o documento), content (primer hijo por defecto), damping (0.1), wheelMultiplier / touchMultiplier (1), keyStep (80), easing (funcion), smoothToDuration (0), autoResize (true).
• Estado expuesto: current, target, maxScroll, state.reduceMotion, velocity, direction.
• onUpdate(fn): se llama en cada frame y devuelve una funcion para desuscribirse.
• scrollTo(y, { immediate, duration, easing }): mueve a la posicion objetivo, respetando limites; devuelve una promesa que resuelve al finalizar.
• enable(), disable(), destroy(): control del ciclo de vida.

tween(options)

Interpolacion generica sin tocar el DOM, basada en requestAnimationFrame.

• from y to: numero, array o objeto; los campos ausentes se rellenan con cero.
• duration (600), delay (0), easing (nombre abreviado o funcion), autoplay (true).
• Callbacks: onStart, onUpdate({ value, progress, rawProgress }), onComplete.
• Control: play(), pause(), resume(), cancel(), seek(p), isActive(), progress().

Ejemplo basico actualizando estilos sin Web Animations:

import { tween } from "@angelardanaz/air";

const box = document.querySelector(".box");

const control = tween({
  from: { x: 0, opacity: 0.4 },
  to: { x: 180, opacity: 1 },
  duration: 900,
  easing: "io3",
  onUpdate: ({ value }) => {
    box.style.transform = `translateX(${value.x}px)`;
    box.style.opacity = value.opacity;
  },
});

// control.pause(); control.resume(); control.seek(0.5); control.cancel();

stagger(each = 50, { from = "start" })

Genera una funcion para escalonar retardos: desde el inicio, el final o el centro. Ideal para pasarlo a options.stagger de animate.

split(el, mode = "letters")

Divide el texto de un elemento en spans para animarlos por separado. Modos: "letters", "words", "lines". Devuelve el array de spans generados y aplica clases split-wrapper + letter|word|line para estilizarlos.

Easings y helpers

• EASINGS: mapa de nombres abreviados (li, i1..i6, o1..o6, io1..io6) a puntos de curva.
• DEFAULT_EASING_NAME: li (lineal).
• easingNameToFn(name|fn): devuelve una funcion de easing (o la misma si ya es funcion).
• easingNameToTiming(name): devuelve string cubic-bezier(...) para usar en CSS.
• cubicBezier(x1, y1, x2, y2): genera un easing personalizado.

Demo local

Hay un ejemplo rapido en demo/ (ignorado en git y fuera del paquete npm). Levanta un server estatico y abre demo/index.html, por ejemplo:

python -m http.server 4173 --directory demo
# o cualquier servidor estatico (npx serve demo, http-server demo, etc.)

Build/minificado

Genera el bundle ESM minificado en dist/air.min.js con:

npm run build

Se ejecuta automaticamente en npm publish via prepublishOnly.

Tests

npm test