animate_it 0.4.0 → 0.5.0

data/lib/animate_it/embed_helper.rb

@@ -1,15 +1,38 @@
+require "json"
+
 module AnimateIt
+  class EmbedBuilder
+    attr_reader :composition
+
+    def initialize(view, composition, navigation: {})
+      @view = view
+      @composition = composition
+      @navigation = navigation
+    end
+
+    def chapter_navigation(**attributes, &block)
+      custom = block.present?
+      preset = if attributes.key?(:preset)
+                 attributes.delete(:preset)
+               elsif !custom
+                 @navigation.fetch(:preset, :pills)
+               end
+      mobile = if attributes.key?(:mobile)
+                 attributes.delete(:mobile)
+               elsif !custom
+                 @navigation[:mobile]
+               end
+      style = ["--animate-it-chapter-count: #{@composition.chapters.count}", attributes.delete(:style)].compact.join(";")
+      ChapterNavigationBuilder.new(@view, @composition, interactive: true, preset:, mobile:, frame: 0)
+                              .render(**attributes, style:, &block)
+    end
+  end
+
   module EmbedHelper
     def animate_it_player(composition_id, title: nil, **attributes)
-      AnimateIt.load_compositions!
-      composition = AnimateIt.registry.fetch(composition_id)
-      raise ArgumentError, "AnimateIt composition #{composition_id.inspect} is not public" unless composition.public_player?
-
-      prefix = respond_to?(:request) && request ? request.script_name.to_s : ""
-      source = "#{prefix}#{AnimateIt.config.mount_path}/public/compositions/" \
-               "#{ERB::Util.url_encode(composition.id)}/player"
+      composition = public_animate_it_composition!(composition_id)
       defaults = {
-        src: source,
+        src: animate_it_public_player_path(composition),
         title: title || composition.id,
         loading: "lazy",
         allow: "autoplay; fullscreen",
@@ -18,5 +41,174 @@ module AnimateIt
       }
       tag.iframe(**defaults, **attributes)
     end
+
+    def animate_it_embed(
+      composition_id,
+      poster:,
+      variants: [],
+      navigation: { preset: :pills },
+      load_when_visible: 0.25,
+      play_when_visible: 2.0 / 3,
+      pause_offscreen: true,
+      reduced_motion: :poster,
+      autoplay: true,
+      title: nil,
+      **attributes,
+      &block
+    )
+      composition = public_animate_it_composition!(composition_id)
+      navigation = navigation == false ? false : (navigation || {}).to_h.deep_symbolize_keys
+      resolved_variants = resolve_animate_it_variants(composition, poster, variants)
+      validate_animate_it_variant_chapters!(resolved_variants)
+      manifest = animate_it_embed_manifest(
+        title: title || composition.id,
+        variants: resolved_variants,
+        load_when_visible:,
+        play_when_visible:,
+        pause_offscreen:,
+        reduced_motion:,
+        autoplay:
+      )
+      builder = EmbedBuilder.new(self, composition, navigation: navigation || {})
+      navigation_html = if navigation
+                          block ? capture(builder, &block) : builder.chapter_navigation(class: "animate-it-embed__navigation")
+                        end
+      classes = ["animate-it-embed", attributes.delete(:class)].compact.join(" ")
+      data = (attributes.delete(:data) || {}).merge(animate_it_embed: true)
+
+      safe_join(
+        [
+          stylesheet_link_tag(animate_it_embed_asset_path("embed.css"), data: { animate_it_embed_asset: "style" }),
+          javascript_include_tag(
+            animate_it_embed_asset_path("embed.js"), defer: true, data: { animate_it_embed_asset: "script" }
+          ),
+          tag.public_send("animate-it-embed", **attributes, class: classes, data:) do
+            safe_join([
+              navigation_html,
+              animate_it_embed_viewport(resolved_variants, title || composition.id),
+              tag.script(ERB::Util.json_escape(JSON.generate(manifest)).html_safe,
+                         type: "application/json", data: { animate_it_embed_manifest: true })
+            ].compact)
+          end
+        ]
+      )
+    end
+
+    private
+
+    def public_animate_it_composition!(composition_id)
+      AnimateIt.load_compositions!
+      composition = AnimateIt.registry.fetch(composition_id)
+      raise ArgumentError, "AnimateIt composition #{composition_id.inspect} is not public" unless composition.public_player?
+
+      composition
+    end
+
+    def animate_it_mount_prefix
+      respond_to?(:request) && request ? request.script_name.to_s : ""
+    end
+
+    def animate_it_public_player_path(composition)
+      id = ERB::Util.url_encode(composition.id)
+      "#{animate_it_mount_prefix}#{AnimateIt.config.mount_path}/public/compositions/#{id}/player"
+    end
+
+    def animate_it_embed_asset_path(filename)
+      version = ERB::Util.url_encode(AnimateIt::VERSION)
+      "#{animate_it_mount_prefix}#{AnimateIt.config.mount_path}/assets/#{version}/#{filename}"
+    end
+
+    def resolve_animate_it_variants(composition, poster, variants)
+      raise ArgumentError, "animate_it_embed requires a poster" if poster.blank?
+
+      primary = animate_it_variant_hash(composition, poster:, media: nil)
+      responsive = Array(variants).map do |variant|
+        attributes = variant.to_h.deep_symbolize_keys
+        target = public_animate_it_composition!(attributes.fetch(:composition))
+        media = attributes.fetch(:media).to_s
+        raise ArgumentError, "AnimateIt variant media query must not be blank" if media.blank?
+
+        animate_it_variant_hash(target, poster: attributes.fetch(:poster), media:)
+      end
+      duplicate_media = responsive.group_by { |variant| variant.fetch("media") }.select { |_media, group| group.many? }.keys
+      raise ArgumentError, "AnimateIt variant media queries must be unique: #{duplicate_media.join(", ")}" if duplicate_media.any?
+
+      [primary, *responsive]
+    end
+
+    def animate_it_variant_hash(composition, poster:, media:)
+      raise ArgumentError, "AnimateIt variant poster must not be blank" if poster.blank?
+
+      manifest = composition.player_manifest.as_json
+      {
+        "media" => media,
+        "composition" => manifest,
+        "poster" => poster.to_s,
+        "source" => animate_it_public_player_path(composition)
+      }
+    end
+
+    def validate_animate_it_variant_chapters!(variants)
+      expected = variants.first.dig("composition", "chapters").map { |chapter| chapter.values_at("name", "label") }
+      variants.drop(1).each do |variant|
+        actual = variant.dig("composition", "chapters").map { |chapter| chapter.values_at("name", "label") }
+        next if actual == expected
+
+        raise ArgumentError, "AnimateIt responsive variants must expose the same ordered chapter names and labels"
+      end
+    end
+
+    def animate_it_embed_manifest(title:, variants:, load_when_visible:, play_when_visible:, pause_offscreen:, reduced_motion:, autoplay:)
+      load_ratio = Float(load_when_visible)
+      play_ratio = Float(play_when_visible)
+      unless load_ratio.between?(0, 1) && play_ratio.between?(0, 1)
+        raise ArgumentError, "AnimateIt visibility thresholds must be between 0 and 1"
+      end
+      raise ArgumentError, "AnimateIt reduced_motion must be :poster" unless reduced_motion.to_s == "poster"
+
+      {
+        "version" => 1,
+        "title" => title,
+        "variants" => variants,
+        "options" => {
+          "loadWhenVisible" => load_ratio,
+          "playWhenVisible" => play_ratio,
+          "pauseOffscreen" => pause_offscreen == true,
+          "reducedMotion" => reduced_motion.to_s,
+          "autoplay" => autoplay == true,
+          "readyTimeout" => 5000,
+          "crossfadeDuration" => 120
+        }
+      }
+    rescue TypeError, ArgumentError => e
+      raise e if e.message.start_with?("AnimateIt")
+
+      raise ArgumentError, "AnimateIt visibility thresholds must be numbers between 0 and 1"
+    end
+
+    def animate_it_embed_viewport(variants, title)
+      primary = variants.first
+      sources = variants.drop(1).map do |variant|
+        tag.source(media: variant.fetch("media"), srcset: variant.fetch("poster"))
+      end
+      poster = tag.picture(
+        safe_join([*sources, image_tag(primary.fetch("poster"), alt: title, loading: "eager")]),
+        class: "animate-it-embed__poster", data: { animate_it_embed_poster: true }
+      )
+      viewport = tag.div(class: "animate-it-embed__viewport", data: { animate_it_embed_viewport: true }) do
+        safe_join(
+          [
+            poster,
+            tag.div(tag.div("", class: "animate-it-embed__frame", data: { animate_it_embed_frame: true }),
+                    class: "animate-it-embed__shell", data: { animate_it_embed_shell: true }),
+            tag.button(
+              "Play", type: "button", class: "animate-it-embed__control", hidden: true,
+                      data: { animate_it_embed_control: true }, aria: { label: "Play animation", pressed: "false" }
+            )
+          ]
+        )
+      end
+      safe_join([viewport, tag.noscript(image_tag(primary.fetch("poster"), alt: title))])
+    end
   end
 end

data/lib/animate_it/embed_runtime/embed.js

@@ -0,0 +1,338 @@
+(function (global) {
+  "use strict";
+
+  if (!global.customElements || global.customElements.get("animate-it-embed")) return;
+
+  function clamp(value, min, max) { return Math.max(min, Math.min(max, value)); }
+
+  class AnimateItEmbed extends HTMLElement {
+    connectedCallback() {
+      if (this.connected) return;
+      this.connected = true;
+      this.manifest = JSON.parse(this.querySelector("[data-animate-it-embed-manifest]").textContent);
+      this.options = this.manifest.options;
+      this.viewport = this.querySelector("[data-animate-it-embed-viewport]");
+      this.frame = this.querySelector("[data-animate-it-embed-frame]");
+      this.control = this.querySelector("[data-animate-it-embed-control]");
+      this.chapterControls = Array.from(this.querySelectorAll("[data-animate-it-chapter]"));
+      this.reducedMotion = global.matchMedia("(prefers-reduced-motion: reduce)");
+      this.userPaused = false;
+      this.userStarted = this.options.autoplay;
+      this.visibleRatio = 0;
+      this.playerReady = false;
+      this.currentChapter = null;
+      this.playing = false;
+      this.boundMessage = this.receiveMessage.bind(this);
+      this.boundVisibility = this.syncPlayback.bind(this);
+      this.boundVariantChange = this.variantChanged.bind(this);
+      this.boundReducedMotion = this.reducedMotionChanged.bind(this);
+      this.boundControl = this.toggle.bind(this);
+      this.boundResize = this.scaleFrame.bind(this);
+      global.addEventListener("message", this.boundMessage);
+      document.addEventListener("visibilitychange", this.boundVisibility);
+      this.control.addEventListener("click", this.boundControl);
+      this.reducedMotion.addEventListener("change", this.boundReducedMotion);
+      this.chapterControls.forEach((control) => {
+        control.addEventListener("click", () => this.seekChapter(control.dataset.animateItChapter));
+      });
+      if ("ResizeObserver" in global) {
+        this.resizeObserver = new global.ResizeObserver(this.boundResize);
+        this.resizeObserver.observe(this.viewport);
+      } else {
+        global.addEventListener("resize", this.boundResize);
+      }
+      this.setupVariants();
+      this.setupVisibility();
+      this.applyReducedMotion();
+    }
+
+    disconnectedCallback() {
+      global.removeEventListener("message", this.boundMessage);
+      document.removeEventListener("visibilitychange", this.boundVisibility);
+      this.control && this.control.removeEventListener("click", this.boundControl);
+      this.reducedMotion && this.reducedMotion.removeEventListener("change", this.boundReducedMotion);
+      this.resizeObserver && this.resizeObserver.disconnect();
+      global.removeEventListener("resize", this.boundResize);
+      this.intersectionObserver && this.intersectionObserver.disconnect();
+      (this.variantQueries || []).forEach((entry) => entry.query.removeEventListener("change", this.boundVariantChange));
+      this.cancelLoad();
+      this.clearReadyTimer();
+      this.removePlayer();
+      this.connected = false;
+    }
+
+    setupVariants() {
+      this.variantQueries = this.manifest.variants.filter((variant) => variant.media).map((variant) => ({
+        variant: variant,
+        query: global.matchMedia(variant.media)
+      }));
+      this.variantQueries.forEach((entry) => entry.query.addEventListener("change", this.boundVariantChange));
+      this.activateVariant(this.selectedVariant());
+    }
+
+    selectedVariant() {
+      const matched = this.variantQueries.find((entry) => entry.query.matches);
+      return matched ? matched.variant : this.manifest.variants[0];
+    }
+
+    variantChanged() {
+      const variant = this.selectedVariant();
+      if (this.variant && variant.source === this.variant.source) return;
+      this.activateVariant(variant);
+    }
+
+    activateVariant(variant) {
+      const resumeChapter = this.currentChapter;
+      this.cancelLoad();
+      this.clearReadyTimer();
+      this.removePlayer();
+      this.variant = variant;
+      this.resumeChapter = resumeChapter;
+      this.playerReady = false;
+      this.dataset.playerReady = "false";
+      const composition = variant.composition;
+      this.style.setProperty("--animate-it-crossfade-duration", `${this.options.crossfadeDuration}ms`);
+      this.viewport.style.aspectRatio = `${composition.width} / ${composition.height}`;
+      this.scaleFrame();
+      this.updateChapters(0, null);
+      if (!this.reducedMotion.matches && this.visibleRatio >= this.options.loadWhenVisible) this.scheduleLoad();
+    }
+
+    setupVisibility() {
+      if (!global.IntersectionObserver) {
+        this.visibleRatio = 1;
+        if (!this.reducedMotion.matches) this.scheduleLoad();
+        return;
+      }
+      const thresholds = Array.from(new Set([0, this.options.loadWhenVisible, this.options.playWhenVisible, 1])).sort();
+      this.intersectionObserver = new IntersectionObserver((entries) => {
+        const entry = entries[entries.length - 1];
+        this.visibleRatio = entry && entry.isIntersecting && entry.boundingClientRect.height > 0 ?
+          entry.intersectionRect.height / entry.boundingClientRect.height : 0;
+        if (this.visibleRatio >= this.options.loadWhenVisible && !this.iframe && !this.reducedMotion.matches) this.scheduleLoad();
+        this.syncPlayback();
+      }, { threshold: thresholds });
+      this.intersectionObserver.observe(this.viewport);
+    }
+
+    applyReducedMotion() {
+      this.dataset.reducedMotion = this.reducedMotion.matches ? "true" : "false";
+      if (this.reducedMotion.matches) {
+        this.cancelLoad();
+        this.removePlayer();
+      }
+    }
+
+    reducedMotionChanged() {
+      this.applyReducedMotion();
+      if (!this.reducedMotion.matches && this.visibleRatio >= this.options.loadWhenVisible) this.scheduleLoad();
+    }
+
+    scheduleLoad() {
+      if (this.iframe || this.loadHandle) return;
+      const load = () => {
+        this.loadHandle = null;
+        if (!this.reducedMotion.matches && this.visibleRatio >= this.options.loadWhenVisible) this.mountPlayer();
+      };
+      if ("requestIdleCallback" in global) this.loadHandle = global.requestIdleCallback(load, { timeout: 800 });
+      else this.loadHandle = global.setTimeout(load, 0);
+    }
+
+    cancelLoad() {
+      if (!this.loadHandle) return;
+      if ("cancelIdleCallback" in global) global.cancelIdleCallback(this.loadHandle);
+      else global.clearTimeout(this.loadHandle);
+      this.loadHandle = null;
+    }
+
+    mountPlayer() {
+      if (this.iframe) return;
+      const composition = this.variant.composition;
+      const separator = this.variant.source.includes("?") ? "&" : "?";
+      const iframe = document.createElement("iframe");
+      iframe.src = `${this.variant.source}${separator}embedded=1&host_navigation=${this.chapterControls.length ? "1" : "0"}`;
+      iframe.title = this.manifest.title;
+      iframe.loading = "eager";
+      iframe.tabIndex = -1;
+      iframe.setAttribute("aria-hidden", "true");
+      iframe.setAttribute("allow", "autoplay");
+      iframe.width = composition.width;
+      iframe.height = composition.height;
+      iframe.addEventListener("load", () => {
+        if (iframe !== this.iframe) return;
+        if (!iframe.contentDocument || !iframe.contentDocument.querySelector("[data-animate-it-tracks]")) {
+          this.fail(new Error("AnimateIt player returned an invalid document"));
+          return;
+        }
+        this.readyTimer = global.setTimeout(() => this.degradedReady(), this.options.readyTimeout);
+      }, { once: true });
+      iframe.addEventListener("error", () => this.fail(new Error("AnimateIt player failed to load")), { once: true });
+      this.iframe = iframe;
+      this.frame.replaceChildren(iframe);
+      this.scaleFrame();
+    }
+
+    removePlayer() {
+      if (this.iframe) {
+        this.send("pause");
+        this.iframe.remove();
+      }
+      this.iframe = null;
+      this.playerReady = false;
+      this.playing = false;
+      if (this.control) this.control.hidden = true;
+    }
+
+    scaleFrame() {
+      if (!this.variant || !this.viewport) return;
+      const composition = this.variant.composition;
+      const scale = this.viewport.clientWidth / composition.width;
+      this.frame.style.width = `${composition.width}px`;
+      this.frame.style.height = `${composition.height}px`;
+      this.frame.style.transform = `scale(${scale})`;
+    }
+
+    receiveMessage(event) {
+      if (!this.iframe || event.source !== this.iframe.contentWindow || event.origin !== global.location.origin) return;
+      const message = event.data || {};
+      if (message.namespace !== "animate-it" || !message.event) return;
+      const detail = message.detail || {};
+      if (message.event === "ready") this.ready(detail);
+      else if (message.event === "framechange") this.frameChanged(detail);
+      else if (message.event === "chapterchange") this.chapterChanged(detail);
+      else if (message.event === "play") this.setPlaying(true);
+      else if (message.event === "pause" || message.event === "ended") this.setPlaying(false);
+      else if (message.event === "error") this.fail(new Error(detail.message || "AnimateIt player error"));
+      this.dispatchEvent(new CustomEvent(`animateit:${message.event}`, { detail }));
+    }
+
+    ready(detail) {
+      this.clearReadyTimer();
+      this.playerReady = true;
+      this.dataset.playerReady = "true";
+      this.dataset.playerReadiness = "complete";
+      this.control.hidden = false;
+      if (this.resumeChapter) this.send("seekChapter", { chapter: this.resumeChapter });
+      this.updateChapters(detail.frame || 0, detail.chapter);
+      this.syncPlayback();
+    }
+
+    degradedReady() {
+      if (!this.iframe || this.playerReady) return;
+      this.playerReady = true;
+      this.dataset.playerReady = "true";
+      this.dataset.playerReadiness = "degraded";
+      this.control.hidden = false;
+      this.syncPlayback();
+      this.dispatchEvent(new CustomEvent("animateit:degradedready"));
+    }
+
+    fail(error) {
+      this.clearReadyTimer();
+      this.dataset.playerReady = "false";
+      this.dataset.playerError = "true";
+      this.playerReady = false;
+      this.control.hidden = true;
+      this.dispatchEvent(new CustomEvent("animateit:error", { detail: { message: error.message } }));
+    }
+
+    clearReadyTimer() {
+      if (this.readyTimer) global.clearTimeout(this.readyTimer);
+      this.readyTimer = null;
+    }
+
+    frameChanged(detail) {
+      this.lastFrame = Number(detail.frame) || 0;
+      this.updateChapters(this.lastFrame, detail.chapter);
+    }
+
+    chapterChanged(detail) {
+      this.currentChapter = detail.chapter || null;
+      this.updateChapters(Number(detail.frame) || 0, this.currentChapter);
+    }
+
+    updateChapters(frame, namedChapter) {
+      const chapters = this.variant.composition.chapters;
+      let currentIndex = -1;
+      for (let index = chapters.length - 1; index >= 0; index -= 1) {
+        if (frame >= chapters[index].startFrame) { currentIndex = index; break; }
+      }
+      if (namedChapter) currentIndex = chapters.findIndex((chapter) => chapter.name === namedChapter);
+      const current = currentIndex >= 0 ? chapters[currentIndex] : null;
+      this.currentChapter = current && current.name;
+      const progress = current ? (current.durationFrames === 1 ? 1 :
+        clamp((frame - current.startFrame) / (current.durationFrames - 1), 0, 1)) : 0;
+      this.chapterControls.forEach((control) => {
+        const index = chapters.findIndex((chapter) => chapter.name === control.dataset.animateItChapter);
+        const state = currentIndex < 0 || index > currentIndex ? "upcoming" : (index < currentIndex ? "completed" : "current");
+        const position = currentIndex < 0 ? "hidden" :
+          (index === currentIndex ? "current" : (index === currentIndex - 1 ? "previous" : (index === currentIndex + 1 ? "next" : "hidden")));
+        control.dataset.chapterState = state;
+        control.dataset.chapterPosition = position;
+        control.style.setProperty("--animate-it-chapter-progress", String(state === "completed" ? 1 : (state === "current" ? progress : 0)));
+        control.style.setProperty("--animate-it-chapter-active", state === "current" ? "1" : "0");
+        control.style.setProperty("--animate-it-chapter-complete", state === "completed" ? "1" : "0");
+        if (state === "current") control.setAttribute("aria-current", "step");
+        else control.removeAttribute("aria-current");
+      });
+    }
+
+    seekChapter(name) {
+      if (!this.playerReady) { this.resumeChapter = name; return; }
+      this.send("seekChapter", { chapter: name });
+    }
+
+    seek(frame) {
+      this.send("seek", { frame: Number(frame) || 0 });
+    }
+
+    play() {
+      this.userStarted = true;
+      this.userPaused = false;
+      this.send("play");
+    }
+
+    pause() {
+      this.userPaused = true;
+      this.send("pause");
+    }
+
+    playingState() {
+      return this.playing;
+    }
+
+    currentFrame() {
+      return this.lastFrame || 0;
+    }
+
+    toggle() {
+      if (!this.playerReady) return;
+      this.userStarted = true;
+      this.userPaused = this.playing;
+      this.send(this.playing ? "pause" : "play");
+    }
+
+    syncPlayback() {
+      if (!this.playerReady) return;
+      const inViewport = this.visibleRatio >= this.options.playWhenVisible;
+      const shouldPlay = this.userStarted && !this.userPaused && !document.hidden &&
+        (inViewport || !this.options.pauseOffscreen);
+      if (shouldPlay && !this.playing) this.send("play");
+      else if (!shouldPlay && this.playing) this.send("pause");
+    }
+
+    send(command, detail) {
+      if (!this.iframe || !this.iframe.contentWindow) return;
+      this.iframe.contentWindow.postMessage(Object.assign({ namespace: "animate-it", command }, detail || {}), global.location.origin);
+    }
+
+    setPlaying(playing) {
+      this.playing = playing;
+      this.control.textContent = playing ? "Pause" : "Play";
+      this.control.setAttribute("aria-label", playing ? "Pause animation" : "Play animation");
+      this.control.setAttribute("aria-pressed", playing ? "true" : "false");
+    }
+  }
+
+  global.customElements.define("animate-it-embed", AnimateItEmbed);
+})(typeof window !== "undefined" ? window : globalThis);

data/lib/animate_it/embed_runtime.rb

@@ -0,0 +1,13 @@
+module AnimateIt
+  module EmbedRuntime
+    module_function
+
+    def javascript
+      @javascript ||= File.read(File.expand_path("embed_runtime/embed.js", __dir__)).freeze
+    end
+
+    def stylesheet
+      EmbedStyles.source
+    end
+  end
+end