@maravilla-labs/frames 0.2.0 → 0.3.2

package/README.md

@@ -94,6 +94,65 @@ Anything the Web Animations API supports as a keyframe is valid in
 }
 ```
 
+## CSS-class animations (Animate.css and friends)
+
+Use `kind: "css"` to schedule an animation defined as CSS `@keyframes`
+and triggered by a class — for example anything from
+[Animate.css](https://animate.style/):
+
+```ts
+{
+  kind: "css",
+  at: 1400,
+  duration: 1000,    // optional — defaults to the longest keyframes duration on the element
+  selector: ".badge",
+  classes: ["animate__animated", "animate__bounceInDown"],
+}
+```
+
+The helper adds the classes, captures the resulting CSS animation as
+a WAAPI `Animation` object via `Element.getAnimations()`, and drives
+its `currentTime` exactly like every other slot. The visual is the
+class's native CSS animation; the timing is yours to control.
+
+The stylesheet that defines the keyframes must be loaded before
+`defineTimeline` runs. The simplest pattern is to `await` the page
+`load` event first inside a `<script type="module">`:
+
+```ts
+await new Promise(r => addEventListener("load", r, { once: true }));
+defineTimeline({ /* ... */ });
+```
+
+This works for any library that exposes its motion as CSS classes
+plus shipped `@keyframes` — Animate.css, Magic, your own custom
+keyframes — not just Animate.css specifically.
+
+When you pass an explicit `duration`, the helper writes
+`animation-duration` inline with `!important` so it beats any
+`@media (prefers-reduced-motion: reduce)` rule the library ships with
+(Animate.css collapses to 1 ms otherwise). You opted into this
+timeline; the helper assumes you mean it.
+
+### Pre-hiding the element
+
+If you need the element invisible *before* its `at` time, use
+`visibility: hidden` in your baseline CSS — not `opacity: 0`. The
+helper flips `visibility: visible` automatically when the css
+instruction fires.
+
+```css
+.badge { visibility: hidden; }
+```
+
+Why not `opacity: 0`? Animate.css's "*In" keyframes (`bounceInDown`,
+`fadeInUp`, etc.) define opacity at the start and middle of the
+animation but **not at 100%**. CSS fills missing keyframe values with
+the element's underlying cascade value — so a baseline of
+`opacity: 0` makes the animation interpolate `1 → 0` at the tail end
+and the element fades back out as soon as it lands. `visibility` is
+not animated by the keyframes, so it stays cleanly out of the way.
+
 ## Video
 
 Use `kind: "video"` to schedule a `<video>` element on the timeline.

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 /**
- * @maravilla-labs/frames — declare a timeline of animations and video
- * playback for a page. The same declaration works two ways:
+ * @maravilla-labs/frames — declare a timeline of animations, video, and
+ * CSS-class-driven animations (Animate.css, etc.) for a page. The same
+ * declaration works two ways:
  *
  * - In a normal browser, each item plays at its scheduled `at` time.
  * - Inside the Maravilla renderer, the timeline is stepped frame by
@@ -30,7 +31,30 @@ export type VideoInstr = {
     /** CSS selector for the `<video>` element. */
     selector: string;
 };
-export type Instr = AnimationInstr | VideoInstr;
+/**
+ * Drive a CSS-class-triggered animation (Animate.css, Magic, your own
+ * `@keyframes`) through the same timeline as everything else. The
+ * classes are added to the element, the resulting CSS animations are
+ * captured via `Element.getAnimations()`, and the helper drives their
+ * `currentTime` exactly like a WAAPI animation.
+ *
+ * Make sure the stylesheet that defines the keyframes is loaded *before*
+ * `defineTimeline` runs — otherwise the class addition produces no
+ * animation to drive.
+ */
+export type CssClassInstr = {
+    /** Discriminator — required. */
+    kind: "css";
+    /** When on the timeline the animation starts, in milliseconds. */
+    at: number;
+    /** How long the animation runs. Defaults to the longest CSS @keyframes duration on the element. */
+    duration?: number;
+    /** CSS selector for the target element. */
+    selector: string;
+    /** Class names to add, e.g. `["animate__animated", "animate__bounceInDown"]`. */
+    classes: string[];
+};
+export type Instr = AnimationInstr | VideoInstr | CssClassInstr;
 export type TimelineSchema = {
     duration: number;
     instructions: Instr[];

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,MAAM,cAAc,GAAG;IAC3B,yDAAyD;IACzD,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,cAAc,GAAG,UAAU,CAAC;AAChD,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,KAAK,EAAE,CAAA;CAAE,CAAC;AAEzE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,UAAU,EAAE;YAAE,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;SAAE,CAAC;QACrD,yBAAyB,CAAC,EAAE,OAAO,CAAC;KACrC;CACF;AAMD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CAqD3D"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,cAAc,GAAG;IAC3B,yDAAyD;IACzD,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,wFAAwF;IACxF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,uDAAuD;IACvD,IAAI,EAAE,OAAO,CAAC;IACd,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,gCAAgC;IAChC,IAAI,EAAE,KAAK,CAAC;IACZ,kEAAkE;IAClE,EAAE,EAAE,MAAM,CAAC;IACX,mGAAmG;IACnG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,KAAK,GAAG,cAAc,GAAG,UAAU,GAAG,aAAa,CAAC;AAChE,MAAM,MAAM,cAAc,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,KAAK,EAAE,CAAA;CAAE,CAAC;AAEzE,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,MAAM;QACd,UAAU,EAAE;YAAE,UAAU,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;SAAE,CAAC;QACrD,yBAAyB,CAAC,EAAE,OAAO,CAAC;KACrC;CACF;AAaD,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,IAAI,CA6H3D"}

package/dist/index.js

@@ -1,6 +1,7 @@
 /**
- * @maravilla-labs/frames — declare a timeline of animations and video
- * playback for a page. The same declaration works two ways:
+ * @maravilla-labs/frames — declare a timeline of animations, video, and
+ * CSS-class-driven animations (Animate.css, etc.) for a page. The same
+ * declaration works two ways:
  *
  * - In a normal browser, each item plays at its scheduled `at` time.
  * - Inside the Maravilla renderer, the timeline is stepped frame by
@@ -8,7 +9,7 @@
  */
 export function defineTimeline(schema) {
     const rendererPresent = typeof window !== "undefined" && window.__mvFramesRendererPresent === true;
-    const slots = schema.instructions.map((i) => {
+    const slots = schema.instructions.flatMap((i) => {
         const el = document.querySelector(i.selector);
         if (!el)
             throw new Error(`defineTimeline: no element matches ${i.selector}`);
@@ -21,16 +22,67 @@ export function defineTimeline(schema) {
             const duration = i.duration ?? Math.min(naturalMs, schema.duration - i.at);
             el.pause();
             el.currentTime = seek / 1000;
-            return { kind: "video", at: i.at, duration, seek, el };
+            return [{ kind: "video", at: i.at, duration, seek, el }];
         }
+        if (i.kind === "css") {
+            if (!(el instanceof HTMLElement)) {
+                throw new Error(`defineTimeline: ${i.selector} must be an HTMLElement for kind: "css"`);
+            }
+            // In browser preview, defer adding the classes until the scheduled
+            // time — the CSS animation then plays naturally from t=0.
+            if (!rendererPresent) {
+                return [{
+                        kind: "css-pending",
+                        at: i.at,
+                        el,
+                        classes: i.classes,
+                        duration: i.duration ?? null,
+                    }];
+            }
+            // In renderer mode, add the classes now to materialise the CSS
+            // animations as WAAPI Animation objects, then pause and drive them
+            // via applyState.
+            const before = new Set(el.getAnimations());
+            el.classList.add(...i.classes);
+            const newAnims = el.getAnimations().filter((a) => !before.has(a));
+            if (newAnims.length === 0) {
+                throw new Error(`defineTimeline: classes [${i.classes.join(", ")}] produced no animation on ${i.selector}. ` +
+                    `Is the stylesheet that defines those keyframes loaded before defineTimeline runs?`);
+            }
+            const natural = newAnims.reduce((max, a) => {
+                const t = a.effect?.getTiming();
+                const d = typeof t?.duration === "number" ? t.duration : 0;
+                return Math.max(max, d);
+            }, 0);
+            // Always honour the user's explicit `duration` (or fall back to the
+            // longest captured CSS animation). Override `animation-duration`
+            // inline with !important so a stylesheet's
+            // `@media (prefers-reduced-motion: reduce)` rule — which Animate.css
+            // ships and which collapses durations to 1ms — can't silently shrink
+            // the timeline. Users opt into this helper specifically to drive
+            // motion; "reduced motion" applies to involuntary motion, not the
+            // timeline they're authoring.
+            const duration = i.duration ?? (natural > 0 ? natural : Math.max(0, schema.duration - i.at));
+            el.style.setProperty("animation-duration", duration + "ms", "important");
+            el.style.visibility = "visible";
+            return newAnims.map((anim) => {
+                anim.effect?.updateTiming({ duration });
+                anim.pause();
+                anim.currentTime = 0;
+                return { kind: "animation", at: i.at, duration, anim };
+            });
+        }
+        // Standard WAAPI animation.
         const duration = i.duration ?? Math.max(0, schema.duration - i.at);
         const anim = el.animate(i.props, { duration, fill: "both" });
         anim.pause();
-        return { kind: "animation", at: i.at, duration, anim };
+        return [{ kind: "animation", at: i.at, duration, anim }];
     });
     window.__mvFrames = {
         async applyState(t) {
             for (const s of slots) {
+                if (s.kind === "css-pending")
+                    continue; // only relevant in browser preview
                 const local = clamp(t - s.at, 0, s.duration);
                 if (s.kind === "video") {
                     s.el.pause();
@@ -50,6 +102,26 @@ export function defineTimeline(schema) {
                     s.el.currentTime = s.seek / 1000;
                     void s.el.play();
                 }
+                else if (s.kind === "css-pending") {
+                    // Override `animation-duration` BEFORE adding the classes so
+                    // the inline !important rule beats Animate.css's
+                    // `prefers-reduced-motion` media query (which would otherwise
+                    // collapse the animation to 1ms). If the user didn't pass an
+                    // explicit duration, leave it alone and let the stylesheet's
+                    // default apply.
+                    if (s.duration !== null) {
+                        s.el.style.setProperty("animation-duration", s.duration + "ms", "important");
+                    }
+                    // Flip visibility on so users can keep the element
+                    // `visibility: hidden` in baseline CSS to hide it before its
+                    // `at` time. Visibility isn't an animatable property in
+                    // Animate.css keyframes, so it doesn't conflict with the
+                    // animation the way `opacity: 0` would (a baseline opacity
+                    // gets pulled into undefined keyframe slots and can make
+                    // "*In" animations fade back out — surprising).
+                    s.el.style.visibility = "visible";
+                    s.el.classList.add(...s.classes);
+                }
                 else {
                     s.anim.play();
                 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/frames",
-  "version": "0.2.0",
+  "version": "0.3.2",
   "description": "Tiny vanilla helper for declaring Web Animations API timelines that the Maravilla runtime renderer drives frame-accurately.",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -1,6 +1,7 @@
 /**
- * @maravilla-labs/frames — declare a timeline of animations and video
- * playback for a page. The same declaration works two ways:
+ * @maravilla-labs/frames — declare a timeline of animations, video, and
+ * CSS-class-driven animations (Animate.css, etc.) for a page. The same
+ * declaration works two ways:
  *
  * - In a normal browser, each item plays at its scheduled `at` time.
  * - Inside the Maravilla renderer, the timeline is stepped frame by
@@ -33,7 +34,31 @@ export type VideoInstr = {
   selector: string;
 };
 
-export type Instr = AnimationInstr | VideoInstr;
+/**
+ * Drive a CSS-class-triggered animation (Animate.css, Magic, your own
+ * `@keyframes`) through the same timeline as everything else. The
+ * classes are added to the element, the resulting CSS animations are
+ * captured via `Element.getAnimations()`, and the helper drives their
+ * `currentTime` exactly like a WAAPI animation.
+ *
+ * Make sure the stylesheet that defines the keyframes is loaded *before*
+ * `defineTimeline` runs — otherwise the class addition produces no
+ * animation to drive.
+ */
+export type CssClassInstr = {
+  /** Discriminator — required. */
+  kind: "css";
+  /** When on the timeline the animation starts, in milliseconds. */
+  at: number;
+  /** How long the animation runs. Defaults to the longest CSS @keyframes duration on the element. */
+  duration?: number;
+  /** CSS selector for the target element. */
+  selector: string;
+  /** Class names to add, e.g. `["animate__animated", "animate__bounceInDown"]`. */
+  classes: string[];
+};
+
+export type Instr = AnimationInstr | VideoInstr | CssClassInstr;
 export type TimelineSchema = { duration: number; instructions: Instr[] };
 
 declare global {
@@ -45,13 +70,20 @@ declare global {
 
 type AnimSlot = { kind: "animation"; at: number; duration: number; anim: Animation };
 type VideoSlot = { kind: "video"; at: number; duration: number; seek: number; el: HTMLVideoElement };
-type Slot = AnimSlot | VideoSlot;
+type CssPendingSlot = {
+  kind: "css-pending";
+  at: number;
+  el: HTMLElement;
+  classes: string[];
+  duration: number | null;
+};
+type Slot = AnimSlot | VideoSlot | CssPendingSlot;
 
 export function defineTimeline(schema: TimelineSchema): void {
   const rendererPresent =
     typeof window !== "undefined" && window.__mvFramesRendererPresent === true;
 
-  const slots: Slot[] = schema.instructions.map((i) => {
+  const slots: Slot[] = schema.instructions.flatMap<Slot>((i) => {
     const el = document.querySelector(i.selector);
     if (!el) throw new Error(`defineTimeline: no element matches ${i.selector}`);
 
@@ -64,18 +96,71 @@ export function defineTimeline(schema: TimelineSchema): void {
       const duration = i.duration ?? Math.min(naturalMs, schema.duration - i.at);
       el.pause();
       el.currentTime = seek / 1000;
-      return { kind: "video", at: i.at, duration, seek, el };
+      return [{ kind: "video", at: i.at, duration, seek, el }];
+    }
+
+    if (i.kind === "css") {
+      if (!(el instanceof HTMLElement)) {
+        throw new Error(`defineTimeline: ${i.selector} must be an HTMLElement for kind: "css"`);
+      }
+      // In browser preview, defer adding the classes until the scheduled
+      // time — the CSS animation then plays naturally from t=0.
+      if (!rendererPresent) {
+        return [{
+          kind: "css-pending",
+          at: i.at,
+          el,
+          classes: i.classes,
+          duration: i.duration ?? null,
+        }];
+      }
+      // In renderer mode, add the classes now to materialise the CSS
+      // animations as WAAPI Animation objects, then pause and drive them
+      // via applyState.
+      const before = new Set(el.getAnimations());
+      el.classList.add(...i.classes);
+      const newAnims = el.getAnimations().filter((a) => !before.has(a));
+      if (newAnims.length === 0) {
+        throw new Error(
+          `defineTimeline: classes [${i.classes.join(", ")}] produced no animation on ${i.selector}. ` +
+            `Is the stylesheet that defines those keyframes loaded before defineTimeline runs?`
+        );
+      }
+      const natural = newAnims.reduce((max, a) => {
+        const t = a.effect?.getTiming();
+        const d = typeof t?.duration === "number" ? t.duration : 0;
+        return Math.max(max, d);
+      }, 0);
+      // Always honour the user's explicit `duration` (or fall back to the
+      // longest captured CSS animation). Override `animation-duration`
+      // inline with !important so a stylesheet's
+      // `@media (prefers-reduced-motion: reduce)` rule — which Animate.css
+      // ships and which collapses durations to 1ms — can't silently shrink
+      // the timeline. Users opt into this helper specifically to drive
+      // motion; "reduced motion" applies to involuntary motion, not the
+      // timeline they're authoring.
+      const duration = i.duration ?? (natural > 0 ? natural : Math.max(0, schema.duration - i.at));
+      el.style.setProperty("animation-duration", duration + "ms", "important");
+      el.style.visibility = "visible";
+      return newAnims.map<AnimSlot>((anim) => {
+        anim.effect?.updateTiming({ duration });
+        anim.pause();
+        anim.currentTime = 0;
+        return { kind: "animation", at: i.at, duration, anim };
+      });
     }
 
+    // Standard WAAPI animation.
     const duration = i.duration ?? Math.max(0, schema.duration - i.at);
     const anim = el.animate(i.props, { duration, fill: "both" });
     anim.pause();
-    return { kind: "animation", at: i.at, duration, anim };
+    return [{ kind: "animation", at: i.at, duration, anim }];
   });
 
   window.__mvFrames = {
     async applyState(t: number) {
       for (const s of slots) {
+        if (s.kind === "css-pending") continue; // only relevant in browser preview
         const local = clamp(t - s.at, 0, s.duration);
         if (s.kind === "video") {
           s.el.pause();
@@ -94,6 +179,25 @@ export function defineTimeline(schema: TimelineSchema): void {
         if (s.kind === "video") {
           s.el.currentTime = s.seek / 1000;
           void s.el.play();
+        } else if (s.kind === "css-pending") {
+          // Override `animation-duration` BEFORE adding the classes so
+          // the inline !important rule beats Animate.css's
+          // `prefers-reduced-motion` media query (which would otherwise
+          // collapse the animation to 1ms). If the user didn't pass an
+          // explicit duration, leave it alone and let the stylesheet's
+          // default apply.
+          if (s.duration !== null) {
+            s.el.style.setProperty("animation-duration", s.duration + "ms", "important");
+          }
+          // Flip visibility on so users can keep the element
+          // `visibility: hidden` in baseline CSS to hide it before its
+          // `at` time. Visibility isn't an animatable property in
+          // Animate.css keyframes, so it doesn't conflict with the
+          // animation the way `opacity: 0` would (a baseline opacity
+          // gets pulled into undefined keyframe slots and can make
+          // "*In" animations fade back out — surprising).
+          s.el.style.visibility = "visible";
+          s.el.classList.add(...s.classes);
         } else {
           s.anim.play();
         }