animate_it 0.3.2 → 0.4.0

data/lib/animate_it/runtime/runtime.js

@@ -0,0 +1,385 @@
+// AnimateIt client runtime: plays a recorded track document against a
+// once-rendered scene DOM.
+(function (global) {
+  "use strict";
+
+  var Easing = {
+    linear: function (p) { return p; },
+    ease_in: function (p) { return p * p; },
+    ease_out: function (p) { return 1 - (1 - p) * (1 - p); },
+    ease_in_out: function (p) {
+      if (p < 0.5) return 2 * p * p;
+      var q = -2 * p + 2;
+      return 1 - (q * q) / 2;
+    }
+  };
+
+  function round4(value) {
+    var rounded = Math.round(Math.abs(value) * 1e4) / 1e4;
+    return value < 0 ? -rounded : rounded;
+  }
+
+  function formatComputed(value) {
+    return Number.isInteger(value) ? value.toFixed(1) : String(value);
+  }
+
+  function interpolate(input, frames, values, easingName) {
+    var n = frames.length;
+    if (input < frames[0]) return { raw: values[0] };
+    if (input > frames[n - 1]) return { raw: values[n - 1] };
+
+    var left = 0;
+    if (input > frames[0]) {
+      left = -1;
+      for (var i = 0; i < n - 1; i += 1) {
+        if (input >= frames[i] && input <= frames[i + 1]) { left = i; break; }
+      }
+      if (left === -1) left = n - 2;
+    }
+
+    var start = frames[left];
+    var end = frames[left + 1];
+    if (end === start) return { raw: values[left] };
+
+    var progress = (input - start) / (end - start);
+    var eased = (Easing[easingName] || Easing.ease_out)(progress);
+    return { computed: values[left] + (values[left + 1] - values[left]) * eased };
+  }
+
+  function compileTrack(track) {
+    if (track.t === "rle") {
+      var expanded = [];
+      for (var i = 0; i < track.r.length; i += 1) {
+        var value = track.r[i][0];
+        for (var j = 0; j < track.r[i][1]; j += 1) expanded.push(value);
+      }
+      return {
+        valueAt: function (frame) {
+          if (!expanded.length) return "";
+          return expanded[Math.min(frame, expanded.length - 1)];
+        }
+      };
+    }
+
+    var frames = track.k.map(function (pair) { return pair[0]; });
+    var values = track.k.map(function (pair) { return pair[1]; });
+    var unit = track.u || "";
+    var easing = track.e || "ease_out";
+    return {
+      valueAt: function (frame) {
+        var result = interpolate(frame, frames, values, easing);
+        if ("raw" in result) return String(result.raw) + unit;
+        return formatComputed(round4(result.computed)) + unit;
+      }
+    };
+  }
+
+  // Pause native CSS/Web Animations and seek them to deterministic frame
+  // time. Layers use scene-local time so delayed scenes start at zero.
+  var animationCache = typeof WeakMap === "undefined" ? null : new WeakMap();
+
+  function seekAnimations(root, frame, fps) {
+    if (!root || typeof root.getAnimations !== "function") return [];
+
+    var frameRate = Number(fps);
+    if (!(frameRate > 0)) return [];
+
+    var currentTime = (frame / frameRate) * 1000;
+    var animations = Array.prototype.slice.call(root.getAnimations({ subtree: true }));
+    var cached = animationCache && animationCache.get(root);
+    if (cached) {
+      cached.forEach(function (animation) {
+        if (animation.playState !== "idle" && animations.indexOf(animation) === -1) animations.push(animation);
+      });
+    }
+    animations.forEach(function (animation) {
+      animation.pause();
+      animation.currentTime = currentTime;
+    });
+    if (animationCache) animationCache.set(root, animations);
+    return animations;
+  }
+
+  function createPlayer(doc, root) {
+    var duration = doc.duration;
+    var varBindings = [];
+    var group;
+    var name;
+
+    for (group in doc.groups || {}) {
+      var groupSelector = (doc.groupSelectors || {})[group] || '[data-animate-vars="' + group + '"]';
+      var els = root.querySelectorAll(groupSelector);
+      if (!els.length) continue;
+      for (name in doc.groups[group]) {
+        varBindings.push({
+          els: els,
+          name: name,
+          track: compileTrack(doc.groups[group][name]),
+          last: null,
+          initialized: false
+        });
+      }
+    }
+
+    var textBindings = [];
+    for (name in doc.texts || {}) {
+      var textSelector = (doc.textSelectors || {})[name] || '[data-animate-text="' + name + '"]';
+      var textEls = root.querySelectorAll(textSelector);
+      if (!textEls.length) continue;
+      textBindings.push({ els: textEls, track: compileTrack(doc.texts[name]), last: null });
+    }
+
+    var layers = (doc.layers || []).map(function (layer) {
+      return {
+        els: root.querySelectorAll(layer.sel),
+        from: layer.from,
+        to: layer.to,
+        origin: Number(layer.origin) || 0,
+        active: null
+      };
+    });
+
+    var current = -1;
+
+    function setFrame(n) {
+      var frame = Math.max(0, Math.min(duration - 1, Math.round(Number(n) || 0)));
+      current = frame;
+
+      layers.forEach(function (layer) {
+        var active = frame >= layer.from && frame < layer.to;
+        if (active === layer.active) return;
+        layer.active = active;
+        layer.els.forEach(function (el) { el.classList.toggle("is-active", active); });
+      });
+
+      varBindings.forEach(function (binding) {
+        var value = binding.track.valueAt(frame);
+        if (binding.initialized && value === binding.last) return;
+        binding.initialized = true;
+        binding.last = value;
+        binding.els.forEach(function (el) {
+          if (value === null) el.style.removeProperty(binding.name);
+          else el.style.setProperty(binding.name, value);
+        });
+      });
+
+      textBindings.forEach(function (binding) {
+        var value = binding.track.valueAt(frame);
+        if (value === binding.last) return;
+        binding.last = value;
+        binding.els.forEach(function (el) { el.textContent = value; });
+      });
+
+      if (layers.length) {
+        layers.forEach(function (layer) {
+          if (!layer.active) return;
+          layer.els.forEach(function (el) {
+            seekAnimations(el, frame - layer.origin, doc.fps);
+          });
+        });
+      } else {
+        seekAnimations(root, frame, doc.fps);
+      }
+      return frame;
+    }
+
+    return {
+      duration: duration,
+      fps: doc.fps,
+      setFrame: setFrame,
+      currentFrame: function () { return current; }
+    };
+  }
+
+  // Owns wall-clock playback for production embeds. Audio starts only from
+  // this transport, so a browser-blocked autoplay attempt falls back to the
+  // visible Play control instead of silently advancing the picture.
+  function createTransport(player, audios, options) {
+    var settings = options || {};
+    var shouldLoop = settings.loop !== false;
+    var button = settings.button || null;
+    var duration = player.duration;
+    var fps = player.fps;
+    var frame = player.currentFrame() < 0 ? 0 : player.currentFrame();
+    var animationFrame = null;
+    var startedAt = 0;
+    var startedFrame = frame;
+
+    audios.forEach(function (el) {
+      var gain = Number(el.dataset.gain);
+      if (Number.isFinite(gain)) el.volume = Math.max(0, Math.min(1, gain));
+      el.loop = el.dataset.loop === "true";
+    });
+
+    function audioWindow(el) {
+      var start = Number(el.dataset.fromFrame) || 0;
+      var rawLength = Number(el.dataset.durationFrames);
+      return { start: start, length: rawLength > 0 ? rawLength : duration - start };
+    }
+
+    function audioTime(el, localTime) {
+      if (el.dataset.loop !== "true" || !Number.isFinite(el.duration) || el.duration <= 0) return localTime;
+      return localTime % el.duration;
+    }
+
+    function updateButton(playing) {
+      if (!button) return;
+      button.textContent = playing ? "Pause" : "Play";
+      button.setAttribute("aria-pressed", playing ? "true" : "false");
+    }
+
+    function prepareAudio(el, currentFrame, shouldPlay) {
+      var window = audioWindow(el);
+      var within = currentFrame >= window.start && currentFrame < window.start + window.length;
+      if (!within) {
+        if (!el.paused) el.pause();
+        return Promise.resolve();
+      }
+
+      var begin = function () {
+        var time = audioTime(el, (currentFrame - window.start) / fps);
+        if (!shouldPlay || el.paused) el.currentTime = time;
+        if (!shouldPlay) {
+          if (!el.paused) el.pause();
+          return Promise.resolve();
+        }
+        if (!el.paused) return Promise.resolve();
+        return Promise.resolve(el.play());
+      };
+
+      if (el.readyState >= 1) return begin();
+      return new Promise(function (resolve, reject) {
+        el.addEventListener("loadedmetadata", function () {
+          begin().then(resolve, reject);
+        }, { once: true });
+        el.addEventListener("error", function () {
+          reject(new Error("AnimateIt audio failed to load"));
+        }, { once: true });
+      });
+    }
+
+    function syncAudio(currentFrame, shouldPlay) {
+      return Promise.all(audios.map(function (el) {
+        return prepareAudio(el, currentFrame, shouldPlay);
+      }));
+    }
+
+    function stopAudio() {
+      audios.forEach(function (el) { if (!el.paused) el.pause(); });
+    }
+
+    function pause() {
+      if (animationFrame !== null) global.cancelAnimationFrame(animationFrame);
+      animationFrame = null;
+      syncAudio(frame, false);
+      updateButton(false);
+    }
+
+    function seek(nextFrame) {
+      frame = player.setFrame(nextFrame);
+      if (animationFrame !== null) {
+        stopAudio();
+        startedAt = global.performance.now();
+        startedFrame = frame;
+        syncAudio(frame, true).catch(pause);
+      } else {
+        syncAudio(frame, false);
+      }
+      return frame;
+    }
+
+    function tick(now) {
+      if (animationFrame === null) return;
+      var next = startedFrame + Math.floor(((now - startedAt) / 1000) * fps);
+      if (next >= duration) {
+        if (!shouldLoop) {
+          frame = player.setFrame(duration - 1);
+          pause();
+          return;
+        }
+        frame = player.setFrame(0);
+        stopAudio();
+        startedAt = now;
+        startedFrame = 0;
+        syncAudio(frame, true).catch(pause);
+      } else if (next !== frame) {
+        frame = player.setFrame(next);
+        syncAudio(frame, true).catch(pause);
+      }
+      if (animationFrame !== null) animationFrame = global.requestAnimationFrame(tick);
+    }
+
+    function play() {
+      if (animationFrame !== null) return Promise.resolve();
+      if (frame >= duration - 1) frame = player.setFrame(0);
+      startedAt = global.performance.now();
+      startedFrame = frame;
+      updateButton(true);
+      animationFrame = global.requestAnimationFrame(tick);
+      return syncAudio(frame, true).catch(function (error) {
+        pause();
+        throw error;
+      });
+    }
+
+    function toggle() {
+      return animationFrame === null ? play() : (pause(), Promise.resolve());
+    }
+
+    if (button) button.addEventListener("click", function () { toggle().catch(function () {}); });
+    updateButton(false);
+
+    return {
+      play: play,
+      pause: pause,
+      toggle: toggle,
+      seek: seek,
+      playing: function () { return animationFrame !== null; },
+      currentFrame: function () { return frame; }
+    };
+  }
+
+  function boot() {
+    var script = document.querySelector("script[data-animate-it-tracks]");
+    if (!script) return;
+    var player = createPlayer(JSON.parse(script.textContent), document);
+    player.setFrame(0);
+    global.__animateIt = { totalFrames: player.duration, setFrame: player.setFrame };
+    global.AnimateItRuntime = player;
+    if (script.dataset.animateItTransport === "true") {
+      var transport = createTransport(
+        player,
+        Array.prototype.slice.call(document.querySelectorAll("audio[data-from-frame]")),
+        {
+          loop: script.dataset.animateItLoop === "true",
+          button: document.querySelector("[data-animate-it-play]")
+        }
+      );
+      global.AnimateItTransport = transport;
+      if (script.dataset.animateItAutoplay === "true") transport.play().catch(function () {});
+    }
+    document.documentElement.dataset.animateItReady = "1";
+  }
+
+  var api = {
+    Easing: Easing,
+    round4: round4,
+    formatComputed: formatComputed,
+    interpolate: interpolate,
+    compileTrack: compileTrack,
+    seekAnimations: seekAnimations,
+    createPlayer: createPlayer,
+    createTransport: createTransport
+  };
+
+  if (typeof module !== "undefined" && module.exports) {
+    module.exports = api;
+  } else {
+    global.AnimateItRuntimeApi = api;
+    if (document.readyState === "loading") {
+      document.addEventListener("DOMContentLoaded", boot);
+    } else {
+      boot();
+    }
+  }
+})(typeof window !== "undefined" ? window : globalThis);

data/lib/animate_it/runtime.rb

@@ -0,0 +1,11 @@
+module AnimateIt
+  # The client-side playback runtime, inlined into the player page via
+  # `javascript_tag` (no asset-pipeline coupling).
+  module Runtime
+    module_function
+
+    def source
+      @source ||= File.read(File.expand_path("runtime/runtime.js", __dir__)).freeze
+    end
+  end
+end

data/lib/animate_it/scene.rb

@@ -2,6 +2,7 @@ module AnimateIt
   class Scene
     include AnimationHelpers
     include ViewHelpers
+    include TextEffects
 
     attr_reader :context, :props, :view_context
 
@@ -49,6 +50,29 @@ module AnimateIt
         @animations ||= AnimationSet.new
       end
 
+      # Register pure per-frame CSS-variable math for client recording.
+      def track_vars(name = :root, &block)
+        raise ArgumentError, "track_vars requires a block" unless block
+
+        own_var_groups[name.to_sym] = block
+      end
+
+      def var_groups
+        inherited = superclass.respond_to?(:var_groups) ? superclass.var_groups : {}
+        inherited.merge(own_var_groups)
+      end
+
+      def text_track(key, &block)
+        raise ArgumentError, "text_track requires a block" unless block
+
+        own_text_tracks[key.to_sym] = block
+      end
+
+      def text_tracks
+        inherited = superclass.respond_to?(:text_tracks) ? superclass.text_tracks : {}
+        inherited.merge(own_text_tracks)
+      end
+
       # Composition class this scene belongs to. Set by the engine when the
       # scene is mounted via `composition.scene MyScene` / single-scene
       # auto-mount; lets animation property procs reach `Composition.beats`.
@@ -112,6 +136,14 @@ module AnimateIt
         @disable_fragment_caching == true
       end
 
+      def own_var_groups
+        @own_var_groups ||= {}
+      end
+
+      def own_text_tracks
+        @own_text_tracks ||= {}
+      end
+
       # Class-side mirror of ViewHelpers#stub_methods so class-method
       # fixture builders (which run before any Scene instance exists)
       # can also use the helper to define singleton-method stubs on
@@ -165,7 +197,7 @@ module AnimateIt
     # programmatic (no sidecar template) or has multiple acts.
     def body
       tag.div(class: self.class.canvas_class, style: canvas_style) do
-        absolute_fill(style: animation_var_style) do
+        absolute_fill(style: animation_var_style, **animate_wrapper_attributes) do
           parts = []
           parts << generated_animation_styles if self.class.animations.elements.any?
           parts << render_scene_template(self.class.template)
@@ -178,7 +210,7 @@ module AnimateIt
     # get the same wrapper + animation-var div around custom content.
     def with_canvas(&block)
       tag.div(class: self.class.canvas_class, style: canvas_style) do
-        absolute_fill(style: animation_var_style) do
+        absolute_fill(style: animation_var_style, **animate_wrapper_attributes) do
           parts = []
           parts << generated_animation_styles if self.class.animations.elements.any?
           parts << view_context.capture(&block) if block
@@ -189,10 +221,26 @@ module AnimateIt
 
     # CSS var bag computed from this frame's animations. Available inside
     # custom render methods that want extra inline styles.
-    def animation_vars(**extras)
+    def animation_vars(group = nil, **extras)
+      return Style.vars(**evaluate_var_group(group), **extras) if group
+
       Style.vars(**self.class.animations.vars_for(self), **extras)
     end
 
+    def evaluate_var_group(name)
+      block = self.class.var_groups[name.to_sym]
+      raise Error, "Unknown track_vars group :#{name} on #{self.class}" unless block
+
+      instance_exec(&block)
+    end
+
+    def evaluate_text_track(key)
+      block = self.class.text_tracks[key.to_sym]
+      raise Error, "Unknown text_track :#{key} on #{self.class}" unless block
+
+      instance_exec(&block)
+    end
+
     delegate :composition_class, to: :class
 
     private
@@ -209,6 +257,12 @@ module AnimateIt
       view_context.capture(...)
     end
 
+    def animate_wrapper_attributes
+      return {} unless self.class.animations.elements.any?
+
+      { data: { animate_vars: Tracks::Recorder::ANIMATE_GROUP } }
+    end
+
     def generated_animation_styles
       view_context.tag.style(self.class.animations.css_rules.html_safe)
     end

data/lib/animate_it/text_effects.rb

@@ -0,0 +1,104 @@
+module AnimateIt
+  # Declarative word-by-word headline reveals that can be recorded as compact
+  # keyframe tracks while retaining server-rendered fallback values.
+  module TextEffects
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+
+    module ClassMethods
+      def word_reveal(key, text, start:, offset: 0, stagger: 4, dur: 12, rise: 18)
+        own_word_reveals[key.to_sym] = { kind: :rise, text:, start:, offset:, stagger:, dur:, rise: }
+      end
+
+      def punch_reveal(key, text, start:, offset: 0, stagger: 5, dur: 10)
+        own_word_reveals[key.to_sym] = { kind: :punch, text:, start:, offset:, stagger:, dur: }
+      end
+
+      def word_reveals_registry
+        inherited = superclass.respond_to?(:word_reveals_registry) ? superclass.word_reveals_registry : {}
+        inherited.merge(own_word_reveals)
+      end
+
+      def own_word_reveals
+        @own_word_reveals ||= {}
+      end
+    end
+
+    def word_reveal_tracks(key)
+      spec = self.class.word_reveals_registry.fetch(key.to_sym)
+      base = resolve_reveal_start(spec)
+      spec[:text].split.each_with_index.flat_map do |_word, index|
+        from = base + (index * spec[:stagger])
+        to = from + spec[:dur]
+        if spec[:kind] == :punch
+          [
+            { var: "#{key}-w#{index}-op", frames: [from, to], values: [0, 1], unit: "" },
+            {
+              var: "#{key}-w#{index}-sc",
+              frames: [from, from + (spec[:dur] * 0.6).round, to],
+              values: [1.3, 1.06, 1.0],
+              unit: ""
+            }
+          ]
+        else
+          [
+            { var: "#{key}-w#{index}-op", frames: [from, to], values: [0, 1], unit: "" },
+            { var: "#{key}-w#{index}-y", frames: [from, to], values: [spec[:rise], 0], unit: "px" }
+          ]
+        end
+      end
+    end
+
+    def reveal_words(key)
+      spec = self.class.word_reveals_registry.fetch(key.to_sym)
+      static = word_reveal_tracks(key).to_h do |track|
+        value = interpolate(
+          local_frame,
+          track[:frames],
+          track[:values],
+          easing: :ease_out,
+          extrapolate_left: :clamp,
+          extrapolate_right: :clamp
+        ).round(4)
+        [track[:var].to_sym, "#{value}#{track[:unit]}"]
+      end
+
+      spans = spec[:text].split.each_with_index.map do |word, index|
+        tag.span(word, style: reveal_word_style(spec, key, index))
+      end
+
+      tag.span(
+        safe_join(spans, " "),
+        data: { animate_vars: reveal_group(key) },
+        style: Style.build("display: contents", Style.vars(**static))
+      )
+    end
+
+    def reveal_plain_words(key)
+      spec = self.class.word_reveals_registry.fetch(key.to_sym)
+      safe_join(spec[:text].split.map { |word| tag.span(word) }, " ")
+    end
+
+    def reveal_group(key)
+      "textfx-#{key.to_s.tr("_", "-")}"
+    end
+
+    private
+
+    def resolve_reveal_start(spec)
+      base = spec[:start].is_a?(Symbol) ? beat_frame(spec[:start]) : spec[:start]
+      base + spec[:offset]
+    end
+
+    def reveal_word_style(spec, key, index)
+      if spec[:kind] == :punch
+        "display:inline-block; opacity: var(--#{key}-w#{index}-op, 0); " \
+          "transform: scale(var(--#{key}-w#{index}-sc, 1.3));"
+      else
+        "display:inline-block; opacity: var(--#{key}-w#{index}-op, 0); " \
+          "transform: translateY(var(--#{key}-w#{index}-y, #{spec[:rise]}px));"
+      end
+    end
+  end
+end

data/lib/animate_it/track_document_schema.rb

@@ -0,0 +1,71 @@
+module AnimateIt
+  # Validates the server/browser track-document boundary before embedding it.
+  module TrackDocumentSchema
+    CURRENT_VERSION = 2
+    SUPPORTED_VERSIONS = [1, CURRENT_VERSION].freeze
+
+    module_function
+
+    def validate!(document)
+      data = document.respond_to?(:as_json) ? document.as_json : document
+      raise Error, "AnimateIt track document must be a JSON object" unless data.is_a?(Hash)
+
+      version = data["v"]
+      unless SUPPORTED_VERSIONS.include?(version)
+        raise Error,
+              "Unsupported AnimateIt track schema #{version.inspect}; " \
+              "supported versions are #{SUPPORTED_VERSIONS.join(", ")}"
+      end
+
+      validate_positive_number!(data, "fps")
+      validate_positive_integer!(data, "duration")
+      validate_hash!(data, "groups")
+      validate_hash!(data, "texts")
+      validate_array!(data, "layers")
+      validate_v2!(data) if version == CURRENT_VERSION
+      data
+    end
+
+    def validate_v2!(data)
+      validate_hash!(data, "groupSelectors")
+      validate_hash!(data, "textSelectors")
+      validate_selector_keys!(data["groups"], data["groupSelectors"], "group")
+      validate_selector_keys!(data["texts"], data["textSelectors"], "text")
+    end
+    private_class_method :validate_v2!
+
+    def validate_selector_keys!(tracks, selectors, kind)
+      extra = selectors.keys - tracks.keys
+      return if extra.empty?
+
+      raise Error, "AnimateIt v2 #{kind} selectors reference missing tracks: #{extra.join(", ")}"
+    end
+    private_class_method :validate_selector_keys!
+
+    def validate_positive_number!(data, key)
+      value = data[key]
+      return if value.is_a?(Numeric) && value.positive?
+
+      raise Error, "AnimateIt track document #{key} must be a positive number"
+    end
+    private_class_method :validate_positive_number!
+
+    def validate_positive_integer!(data, key)
+      value = data[key]
+      return if value.is_a?(Integer) && value.positive?
+
+      raise Error, "AnimateIt track document #{key} must be a positive integer"
+    end
+    private_class_method :validate_positive_integer!
+
+    def validate_hash!(data, key)
+      raise Error, "AnimateIt track document #{key} must be an object" unless data[key].is_a?(Hash)
+    end
+    private_class_method :validate_hash!
+
+    def validate_array!(data, key)
+      raise Error, "AnimateIt track document #{key} must be an array" unless data[key].is_a?(Array)
+    end
+    private_class_method :validate_array!
+  end
+end