@px-petals/roku.motion-web 0.0.0-stage → 1.0.0

package/motion/motion.nested.js

@@ -0,0 +1,345 @@
+/**
+ * The state machines of nested artboards. A bundle's `nested` lists each
+ * nested artboard that runs a machine of its own: the machine, where each of
+ * its animations sits on the precomp's timeline, and the layer's id. Each
+ * runs through the same flow as the bundle's own machine, with its animations
+ * as the flow's, and its clock moves the precomp layer's time remap, which
+ * the renderer reads from the slot named by the layer's `nid`.
+ *
+ * A nested machine takes the bundle's inputs of the same name, and
+ * is advanced by the player's clock. Its pointer listeners are watched as
+ * `<sid>/<rid>`: the renderer records a nested layer's groups under the
+ * layer's `nid`, since the nested artboard numbers its objects from 0 as the
+ * bundle's own does.
+ *
+ * Its focus nodes are in the host's focus tree, named the same way. A focus
+ * or blur on one runs that machine's Focus and Blur listeners, a key bound to
+ * one runs in that machine (`bindings`), and a focus action the machine runs
+ * goes to `options.focus`.
+ */
+
+import { createStage } from '../mixer/mixer.stage.js'
+import { createFlow } from './motion.flow.js'
+
+/**
+ * @typedef {object} NestedEntry
+ * @property {string}                                                         sid          the layer's id, which names its time remap slot
+ * @property {number}                                                         fps          the precomp timeline's frame rate
+ * @property {any}                                                            machine      a dotLottie state machine naming `animations`
+ * @property {Record<string, {start: number, frames: number, loop: boolean}>} animations
+ * @property {Record<string, any>}                                            inputs       what the instance sets on the machine's inputs
+ * @property {number}                                                         [speed]      how fast the instance plays its machine; 1 without
+ * @property {string[]}                                                       [shared]     the machine's inputs that are properties of the host's view model, which it is bound to: what the machine sets on them reaches the host
+ * @property {any[]}                                                          [remoteKeys] the machine's key listeners, each with the `target` focus node of its own artboard that hears it
+ */
+
+/**
+ * @typedef {object} NestedOptions
+ * @property {(changes: Record<string, any>) => void}             [write]  a machine set view-model properties of the host: their names, with the values
+ * @property {(sid: string, values: Record<string, any>) => void} [values] a machine set values: all of its inputs, as it now has them (a list row's own machine sets properties of the row's view model)
+ * @property {(action: any, sid: string) => void}                 [focus]  a machine ran a focus action (FocusTarget with its own artboard's rid, FocusMove, FocusClear); `sid` is the machine's
+ */
+
+/**
+ * @param   {NestedEntry[] | undefined}                                                                                                                                                                                                                                                                                                                                                                                                                    entries   a bundle's `nested`
+ * @param   {NestedOptions}                                                                                                                                                                                                                                                                                                                                                                                                                                [options]
+ * @returns {{ tick: (seconds: number) => void, takeInputs: (inputs: Record<string, any>) => void, apply: (slots: Record<string, any>, fps: number) => void, pointerTargets: () => Record<string, string[]>, pointer: (type: string, target: string) => boolean, focusEvent: (type: 'Focus' | 'Blur', sid: string, rid: string) => boolean, act: (sid: string, actions: any[]) => boolean, bindings: () => any[], flushFocus: () => void, count: number }}
+ */
+export function createNested(entries, options) {
+  /** @type {any[]} */
+  const items = []
+  const list = entries || []
+  /** @type {{ action: any, sid: string }[] | null} focus actions the machines ran as they started, before the host's focus tree was there */
+  let early = []
+  const onFocus = (/** @type {any} */ action, /** @type {string} */ sid) => {
+    if (early) early.push({ action, sid })
+    else if (options && options.focus) options.focus(action, sid)
+  }
+  for (let n = 0; n < list.length; n++) items.push(createItem(list[n], (options && options.write) || null, onFocus, (options && options.values) || null))
+
+  return {
+    count: items.length,
+
+    /**
+     * Once the focus tree is there: the focus actions machines ran as they
+     * started (a state that focuses a node) take effect.
+     */
+    flushFocus() {
+      const queued = early || []
+      early = null
+      for (let n = 0; n < queued.length; n++) onFocus(queued[n].action, queued[n].sid)
+    },
+
+    /**
+     * The key bindings of the machines' focus nodes, named by the host's
+     * tree: each `target` is `<sid>/<rid>`, and `scope` is the machine the
+     * actions run in.
+     *
+     * @returns {any[]}
+     */
+    bindings() {
+      const found = []
+      for (let n = 0; n < items.length; n++) {
+        const keys = items[n].entry.remoteKeys || []
+        for (let k = 0; k < keys.length; k++) found.push(extend(keys[k], { target: items[n].entry.sid + '/' + keys[k].target, scope: items[n].entry.sid }))
+      }
+      return found
+    },
+
+    /**
+     * A node of a machine's artboard gained or lost focus: its Focus or Blur
+     * listeners run.
+     *
+     * @param   {'Focus' | 'Blur'} type
+     * @param   {string}           sid  the machine's, `row` for a list row's own
+     * @param   {string}           rid  the node in the machine's artboard, "" for the artboard
+     * @returns {boolean}               whether a machine owns it
+     */
+    focusEvent(type, sid, rid) {
+      for (let n = 0; n < items.length; n++) {
+        if (items[n].entry.sid !== sid) continue
+        items[n].flow.focusEvent(type, rid)
+        return true
+      }
+      return false
+    },
+
+    /**
+     * Runs the actions of a key binding in the machine it belongs to.
+     *
+     * @param   {string}  sid
+     * @param   {any[]}   actions
+     * @returns {boolean}         whether a machine owns it
+     */
+    act(sid, actions) {
+      for (let n = 0; n < items.length; n++) {
+        if (items[n].entry.sid !== sid) continue
+        items[n].flow.act(actions)
+        return true
+      }
+      return false
+    },
+
+    /**
+     * Moves every nested machine's clock on.
+     *
+     * @param {number} seconds
+     */
+    tick(seconds) {
+      for (let n = 0; n < items.length; n++) advance(items[n], seconds)
+    },
+
+    /**
+     * Gives each machine the inputs it has by name.
+     *
+     * @param {Record<string, any>} inputs
+     */
+    takeInputs(inputs) {
+      for (let n = 0; n < items.length; n++) {
+        /** @type {Record<string, any>} */
+        const own = {}
+        let any = false
+        for (const name in inputs) {
+          if (items[n].names[name]) {
+            own[name] = inputs[name]
+            any = true
+          }
+        }
+        if (!any) continue
+        // what the host sets is what the machine already has: it is not the machine's to write back
+        for (const name in own) if (items[n].synced) items[n].synced[name] = own[name]
+        items[n].flow.takeInputs(own)
+      }
+    },
+
+    /**
+     * Where the machines' pointer listeners are: each target's `<sid>/<rid>`
+     * and the interaction types on it. A listener on the whole artboard
+     * is not offered by Rive, and is not watched.
+     *
+     * @returns {Record<string, string[]>}
+     */
+    pointerTargets() {
+      /** @type {Record<string, string[]>} */
+      const found = {}
+      for (let n = 0; n < items.length; n++) {
+        const targets = items[n].flow.pointerTargets()
+        // a list row's own machine names its shapes as the row's Lottie does; a nested artboard's are under its layer's id
+        const prefix = items[n].entry.sid === 'row' ? '' : items[n].entry.sid + '/'
+        for (const rid in targets) if (rid !== '') found[prefix + rid] = targets[rid]
+      }
+      return found
+    },
+
+    /**
+     * A pointer event on a target of `pointerTargets`.
+     *
+     * @param   {string}  type
+     * @param   {string}  target `<sid>/<rid>`
+     * @returns {boolean}        whether a nested machine owns the target
+     */
+    pointer(type, target) {
+      const at = target.indexOf('/')
+      for (let n = 0; n < items.length; n++) {
+        const isRow = at < 0 && items[n].entry.sid === 'row'
+        if (!isRow && (at < 0 || items[n].entry.sid !== target.slice(0, at))) continue
+        items[n].flow.pointer(type, isRow ? target : target.slice(at + 1))
+        return true
+      }
+      return false
+    },
+
+    /**
+     * Writes where each layer's time remap is into the animation's slots,
+     * in seconds of an animation at `fps`.
+     *
+     * @param {Record<string, any>} slots
+     * @param {number}              fps
+     */
+    apply(slots, fps) {
+      for (let n = 0; n < items.length; n++) {
+        const item = items[n]
+        if (item.stage) {
+          applyPoses(item, slots, fps)
+          continue
+        }
+        if (!item.segment) continue
+        const frame = item.segment.start + Math.min(item.time * item.entry.fps, item.segment.frames)
+        slots[item.entry.sid] = frame / fps
+      }
+    },
+  }
+}
+
+/**
+ * @param {NestedEntry}                                                 entry
+ * @param {((changes: Record<string, any>) => void) | null}             write
+ * @param {(action: any, sid: string) => void}                          onFocus
+ * @param {((sid: string, values: Record<string, any>) => void) | null} onValues
+ */
+function createItem(entry, write, onFocus, onValues) {
+  /** @type {Record<string, boolean>} */
+  const names = {}
+  const inputs = entry.machine.inputs || []
+  for (let n = 0; n < inputs.length; n++) names[inputs[n].name] = true
+
+  const shared = entry.shared || []
+  /** @type {any} */
+  const item = { entry, names, segment: null, loops: false, time: 0, isDone: false, flow: null, synced: null, stage: null }
+  // several layers play several animations at once, which a stage keeps the clocks of, as the host's does
+  const isMixed = Array.isArray(entry.machine.layers) && entry.machine.layers.length > 1
+  /** @type {Record<string, any>} */
+  const timed = {}
+  for (const id in entry.animations) timed[id] = { start: entry.animations[id].start, frames: entry.animations[id].frames, loop: entry.animations[id].loop, fps: entry.fps }
+  if (isMixed) item.stage = createStage(timed)
+  /** @type {any} */
+  const hooks = {
+      play(/** @type {string} */ animation, /** @type {boolean} */ loops) {
+        item.segment = entry.animations[animation]
+        item.loops = loops
+        item.time = 0
+        item.isDone = false
+      },
+      valuesChanged(/** @type {Record<string, any>} */ values) {
+        if (onValues) onValues(entry.sid, values)
+        if (!item.synced || !write) return
+        // a machine that sets a property of the host's view model (a listener, a state's action) tells the host
+        /** @type {Record<string, any>} */
+        const changes = {}
+        let any = false
+        for (let n = 0; n < shared.length; n++) {
+          const name = shared[n]
+          if (values[name] === undefined || values[name] === item.synced[name]) continue
+          item.synced[name] = values[name]
+          changes[name] = values[name]
+          any = true
+        }
+        if (any) write(changes)
+      },
+      stateChanged() {},
+      event() {},
+      error() {},
+      focus(/** @type {any} */ action) {
+        onFocus(action, entry.sid)
+      },
+  }
+  if (item.stage) {
+    hooks.layer = (/** @type {number} */ layer, /** @type {any} */ state, /** @type {number} */ fadeMs, /** @type {number[] | undefined} */ ease) => item.stage.enter(layer, state, fadeMs, ease)
+    hooks.elapsed = (/** @type {number} */ layer) => item.stage.elapsedMs(layer)
+  }
+  item.flow = createFlow({ machine: entry.machine, animations: isMixed ? timed : entry.animations, data: {}, remoteKeys: [] }, hooks)
+  item.flow.start(entry.inputs || {})
+  // what it starts with is the host's default instance: nothing to tell the host yet
+  if (shared.length) {
+    item.synced = {}
+    for (let n = 0; n < shared.length; n++) item.synced[shared[n]] = item.flow.values[shared[n]]
+  }
+  return item
+}
+
+/**
+ * @param {any}    item
+ * @param {number} seconds
+ */
+function advance(item, seconds) {
+  if (item.stage) {
+    const done = item.stage.advance(seconds * (item.entry.speed > 0 ? item.entry.speed : 1))
+    for (let n = 0; n < done.length; n++) item.flow.finished(done[n])
+    return
+  }
+  if (!item.segment) return
+  item.time += seconds * (item.entry.speed > 0 ? item.entry.speed : 1)
+  const length = item.segment.frames / item.entry.fps
+  if (item.time < length) return
+
+  if (item.loops) {
+    item.time %= length
+    return
+  }
+  item.time = length
+  if (item.isDone) return
+  // the animation ended: its OnComplete interactions may start another
+  item.isDone = true
+  item.flow.finished()
+}
+
+/**
+ * What a machine with several layers shows: the time remap follows the first
+ * layer, and the poses of them all are in a slot of their own, for the
+ * properties that say which segments key them to mix.
+ *
+ * @param {any}                 item
+ * @param {Record<string, any>} slots
+ * @param {number}              fps
+ */
+function applyPoses(item, slots, fps) {
+  const entry = item.entry
+  const lead = item.stage.lead()
+  if (lead) {
+    const segment = entry.animations[lead.animation]
+    slots[entry.sid] = (segment.start + Math.min(lead.time * entry.fps, segment.frames)) / fps
+  }
+  const poses = item.stage.poses(item.flow.values)
+  /** @type {{ start: number, frame: number, weight: number }[]} */
+  const found = []
+  for (let n = 0; n < poses.length; n++) {
+    const segment = entry.animations[poses[n].animation]
+    if (segment) found.push({ start: segment.start, frame: Math.min(poses[n].time * entry.fps, segment.frames), weight: poses[n].weight })
+  }
+  slots['pz:' + entry.sid] = found
+}
+
+/**
+ * A copy of an object with fields added over it (the 2014 baseline has no `Object.assign`).
+ *
+ * @param   {Record<string, any>} base
+ * @param   {Record<string, any>} more
+ * @returns {Record<string, any>}
+ */
+export function extend(base, more) {
+  /** @type {Record<string, any>} */
+  const found = {}
+  for (const name in base) found[name] = base[name]
+  for (const name in more) found[name] = more[name]
+  return found
+}