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

package/motion/motion.flow.js

@@ -0,0 +1,403 @@
+/**
+ * The flow of a playing Motion, as Roku's runs it (motion.flow.bs): which
+ * state is active, what the inputs hold, and when live values change.
+ *
+ * With a state machine, states are entered by name, run their entry
+ * actions and play their animation; the machine then settles, taking any
+ * transitions whose guards now pass. Without one, the bundle's initial
+ * animation plays. The flow owns the state and the values; the player it is
+ * given draws.
+ *
+ * A machine may have several layers, each in a state of its own. With the
+ * `layer` hook the flow reports every layer's states (and the cross-fade of
+ * the transition that entered one) and reads how long each has played, so
+ * exit times are exact; without it, the first layer plays by `play` alone,
+ * as on Roku.
+ */
+
+import { defaults, exists, find, interactionActions, isEvent, layersOf, nextExit, perform, pointerTargetsOf, takeTransition } from './motion.machine.js'
+import { inputValue } from './motion.values.js'
+
+/** Most transitions one change can chain through before the machine is taken to be cycling */
+const MAX_SETTLE = 16
+
+/**
+ * @typedef {object} Hooks
+ * @property {(animation: string, loops: boolean) => void}                          play          show an animation
+ * @property {(values: Record<string, any>) => void}                                valuesChanged
+ * @property {(state: string, layer: number) => void}                               stateChanged
+ * @property {(event: string) => void}                                              event         a custom event the machine fired, or `openUrl:<url>`
+ * @property {(message: string) => void}                                            error
+ * @property {(action: any) => void}                                                [focus]       a focus action (FocusTarget, FocusMove, FocusClear) ran
+ * @property {(layer: number, state: any, fadeMs: number, ease?: number[]) => void} [layer]       a layer entered a state, fading in along `ease`'s curve; replaces `play`
+ * @property {(layer: number) => number}                                            [elapsed]     ms the layer's current state has played, unwrapped
+ */
+
+/**
+ * @param {any}   manifest a bundle's motion.json
+ * @param {Hooks} hooks
+ */
+export function createFlow(manifest, hooks) {
+  const graph = exists(manifest.machine) ? manifest.machine : null
+  const graphs = graph ? layersOf(graph) : []
+  const isMixed = typeof hooks.layer === 'function'
+  /** @type {Record<string, any>} */
+  let values = {}
+  /** @type {Record<string, boolean>} */
+  let events = {}
+  /** @type {string[]} each layer's current state */
+  let currents = []
+  /** @type {number[]} the latest exit time, in ms, a layer's current state has passed; -1 for none */
+  let crossed = []
+  let animation = ''
+  /** @type {Record<string, string>} */
+  let transitions = {}
+  /** Entry actions and listeners that run while a state is being entered must not settle the machine under it */
+  let busy = 0
+
+  /**
+   * The defaults, with the caller's inputs over them; then the first state.
+   *
+   * @param {Record<string, any>}    inputs
+   * @param {string}                 [requested] a state to start in instead of the machine's own
+   * @param {Record<string, string>} [followers] without a machine, the animation each one's end plays next
+   */
+  function start(inputs, requested, followers) {
+    values = defaultValues()
+    events = {}
+    transitions = followers || {}
+    currents = []
+    crossed = []
+    mergeInputs(inputs)
+    hooks.valuesChanged(values)
+
+    if (!graph) {
+      showAnimation(firstAnimation(requested))
+      return
+    }
+    busy++
+    for (let n = 0; n < graphs.length; n++) {
+      currents[n] = ''
+      crossed[n] = -1
+      enter(n, requested && find(graphs[n], requested) ? requested : graphs[n].initial, 0)
+    }
+    busy--
+    settle()
+  }
+
+  /** The view model's default instance, then the machine's own input values for anything it leaves out. */
+  function defaultValues() {
+    /** @type {Record<string, any>} */
+    const result = {}
+    const data = manifest.data || {}
+    const instance = data.instances && typeof data.defaultInstance === 'string' ? data.instances[data.defaultInstance] : null
+    if (instance) for (const name in instance) result[name] = instance[name]
+    if (graph) {
+      const inputs = defaults(graph)
+      for (const name in inputs) if (!(name in result)) result[name] = inputs[name]
+    }
+    return result
+  }
+
+  /** @param {string} [requested] */
+  function firstAnimation(requested) {
+    const candidates = [ requested, manifest.initial ]
+    for (let n = 0; n < candidates.length; n++) if (candidates[n] && manifest.animations[candidates[n]]) return /** @type {string} */ (candidates[n])
+    for (const id in manifest.animations) return id
+    return ''
+  }
+
+  // States
+  // ■■■■■■
+
+  /**
+   * The caller asked for a state: enter it directly, in the layer that has it.
+   *
+   * @param {string} name a machine state, or an animation without a machine
+   */
+  function jumpTo(name) {
+    if (!graph) {
+      showAnimation(name)
+      return
+    }
+    let layer = -1
+    for (let n = 0; n < graphs.length && layer < 0; n++) if (find(graphs[n], name)) layer = n
+    if (layer < 0) {
+      hooks.error("unknown state '" + name + "'")
+      return
+    }
+    enter(layer, name, 0)
+    settle()
+  }
+
+  /**
+   * Without a machine, a state is an animation, played once.
+   *
+   * @param {string} name
+   */
+  function showAnimation(name) {
+    currents = [ name ]
+    hooks.stateChanged(name, 0)
+    play(name, false)
+  }
+
+  /**
+   * Leaving the previous state runs its exit actions; entering runs the new
+   * one's entry actions and plays its animation.
+   *
+   * @param {number}   layer
+   * @param {string}   name
+   * @param {number}   fadeMs how long the outgoing state fades into this one
+   * @param {number[]} [ease] the fade's cubic curve, `[x1, y1, x2, y2]`; linear without
+   */
+  function enter(layer, name, fadeMs, ease) {
+    const layerGraph = graphs[layer]
+    busy++
+    const leaving = find(layerGraph, currents[layer])
+    if (leaving) run(leaving.exitActions)
+
+    const state = find(layerGraph, name)
+    if (!state) {
+      busy--
+      return
+    }
+    currents[layer] = name
+    crossed[layer] = -1
+    hooks.stateChanged(name, layer)
+    run(state.entryActions)
+    if (isMixed) {
+      if (typeof state.animation === 'string' || state.blend) /** @type {NonNullable<Hooks['layer']>} */ (hooks.layer)(layer, state, fadeMs, ease)
+    } else if (layer === 0 && typeof state.animation === 'string') {
+      play(state.animation, state.loop === true)
+    }
+    busy--
+  }
+
+  /**
+   * Takes transitions until none passes, then clears the events this round
+   * consumed. Every layer sees the same events in a round.
+   */
+  function settle() {
+    if (!graph) return
+    for (let n = 0; n < MAX_SETTLE; n++) {
+      /** @type {any[]} */
+      const taken = []
+      for (let layer = 0; layer < graphs.length; layer++) taken.push(takeTransition(graphs[layer], currents[layer], values, events, clockOf(layer)))
+      if (!taken.some(Boolean)) break
+      // an event that moved the machine is spent
+      events = {}
+      for (let layer = 0; layer < graphs.length; layer++) {
+        if (taken[layer]) enter(layer, taken[layer].toState, taken[layer].durationMs || 0, taken[layer].ease)
+      }
+    }
+    events = {}
+    hooks.valuesChanged(values)
+  }
+
+  /**
+   * How long a layer's state has played, for exit times; null when the
+   * player does not say, and exit times fall back to the whole timeline.
+   *
+   * @param   {number}                                     layer
+   * @returns {{ elapsed: number, length: number } | null}
+   */
+  function clockOf(layer) {
+    if (!hooks.elapsed) return null
+    return { elapsed: hooks.elapsed(layer), length: lengthOf(find(graphs[layer], currents[layer])) }
+  }
+
+  /**
+   * A state's timeline in ms: its animation's, or a blend's longest.
+   *
+   * @param   {any}    state
+   * @returns {number}
+   */
+  function lengthOf(state) {
+    if (!state) return 0
+    const ids = []
+    if (state.blend) for (let n = 0; n < state.blend.animations.length; n++) ids.push(state.blend.animations[n].animation)
+    else ids.push(state.animation)
+
+    let longest = 0
+    for (let n = 0; n < ids.length; n++) {
+      const entry = manifest.animations[ids[n]]
+      if (entry && entry.fps > 0) longest = Math.max(longest, (entry.frames / entry.fps) * 1000)
+    }
+    return longest
+  }
+
+  /**
+   * Time has passed: a transition waiting on an exit time may now go. Called
+   * as the player advances; settles only when a layer crosses an exit time.
+   */
+  function tick() {
+    if (!graph || !hooks.elapsed) return
+    for (let layer = 0; layer < graphs.length; layer++) {
+      const state = find(graphs[layer], currents[layer])
+      const next = nextExit(state, lengthOf(state), crossed[layer])
+      if (next < 0 || hooks.elapsed(layer) < next) continue
+
+      crossed[layer] = next
+      settle()
+      return
+    }
+  }
+
+  /**
+   * @param {string}  id
+   * @param {boolean} loops
+   */
+  function play(id, loops) {
+    if (!manifest.animations[id]) {
+      hooks.error("unknown animation '" + id + "'")
+      return
+    }
+    animation = id
+    hooks.play(id, loops)
+  }
+
+  // Inputs and interactions
+  // ■■■■■■■■■■■■■■■■■■■■■■■
+
+  /**
+   * Live values: changed ones are held, an Event input set to true fires.
+   *
+   * @param {Record<string, any>} inputs
+   */
+  function takeInputs(inputs) {
+    if (!mergeInputs(inputs)) return
+    hooks.valuesChanged(values)
+    settle()
+  }
+
+  /**
+   * @param   {Record<string, any>} inputs
+   * @returns {boolean}                    whether anything changed or fired
+   */
+  function mergeInputs(inputs) {
+    let changed = false
+    for (const name in inputs || {}) {
+      // an enum may be given by name; the machine compares its index
+      const value = inputValue(manifest.data, name, inputs[name])
+      if (graph && isEvent(graph, name)) {
+        if (value === true) {
+          events[name] = true
+          changed = true
+        }
+      } else if (values[name] !== value) {
+        values[name] = value
+        changed = true
+      }
+    }
+    return changed
+  }
+
+  /**
+   * Runs the actions of a key binding.
+   *
+   * @param {any[]} actions
+   */
+  function act(actions) {
+    if (!graph) return
+    run(actions)
+    settle()
+  }
+
+  /**
+   * Focus moved onto or off a node: the Focus or Blur listeners on it run.
+   *
+   * @param {'Focus' | 'Blur'} type
+   * @param {string}           target the node's `rid`, "" for the artboard
+   */
+  function focusEvent(type, target) {
+    if (!graph) return
+    run(interactionActions(graph, type, '', target))
+    if (!busy) settle()
+  }
+
+  /**
+   * A tap or click on the animation. Called by the host, it clicks every
+   * Click listener, as OK does; from a click on the canvas, only the listeners
+   * with no target of their own, which watch the whole artboard (those with
+   * a target are clicked by `pointer`, where the pointer hit it).
+   *
+   * @param {boolean} [isUntargeted] click only the listeners that have no target
+   */
+  function click(isUntargeted) {
+    if (!graph) return
+    run(interactionActions(graph, 'Click', '', isUntargeted ? '' : undefined))
+    settle()
+  }
+
+  /**
+   * A pointer event on a target: runs the actions of the interactions of that type on it.
+   *
+   * @param {string} type   Click, PointerDown, PointerUp, PointerEnter, PointerExit or PointerMove
+   * @param {string} target the `rid` of the shape or group, or "" for the listeners without a target
+   */
+  function pointer(type, target) {
+    if (!graph) return
+    run(interactionActions(graph, type, '', target))
+    settle()
+  }
+
+  /**
+   * The pointer interactions' targets, for the player to watch.
+   *
+   * @returns {Record<string, string[]>} each target's `rid` ("" for none) → the interaction types on it
+   */
+  function pointerTargets() {
+    return graph ? pointerTargetsOf(graph) : {}
+  }
+
+  /**
+   * A layer's active state played to its end: its OnComplete interactions
+   * run, or without a machine, the animation `transitions` names for it plays.
+   *
+   * @param {number} [layer]
+   */
+  function finished(layer) {
+    const index = layer || 0
+    if (!graph) {
+      const next = transitions[currents[0]]
+      if (next) showAnimation(next)
+      return
+    }
+    run(interactionActions(graphs[index], 'OnComplete', currents[index]))
+    settle()
+  }
+
+  /** @param {any[]} actions */
+  function run(actions) {
+    if (!graph || !actions || !actions.length) return
+    const effects = perform(actions, graph, values, events)
+    for (let n = 0; n < effects.events.length; n++) hooks.event(effects.events[n])
+    if (effects.changed) hooks.valuesChanged(values)
+    if (hooks.focus) for (let n = 0; n < effects.focus.length; n++) hooks.focus(effects.focus[n])
+  }
+
+  return {
+    start,
+    jumpTo,
+    takeInputs,
+    act,
+    focusEvent,
+    click,
+    pointer,
+    pointerTargets,
+    finished,
+    tick,
+    get state() {
+      return currents[0] || ''
+    },
+    get states() {
+      return currents.slice()
+    },
+    get animation() {
+      return animation
+    },
+    get values() {
+      return values
+    },
+  }
+}

package/motion/motion.keys.js

@@ -0,0 +1,150 @@
+/**
+ * Keys and taps as a bundle's keyboard listeners name them. A bundle's
+ * `remoteKeys` use Rive's key names (`enter`, `space`, `up`); a DOM key
+ * event, or a Roku remote's name, becomes those here, so the same bundle
+ * answers a keyboard, a TV remote's arrows and a Roku remote alike.
+ */
+
+/** Roku remote names → Rive key names, as Roku's Motion maps them (motion.flow.bs) */
+const ROKU = {
+  OK: [ 'enter', 'kpEnter', 'space' ],
+  back: [ 'escape', 'backspace' ],
+  up: [ 'up' ],
+  down: [ 'down' ],
+  left: [ 'left' ],
+  right: [ 'right' ],
+  play: [ 'space' ],
+}
+
+/** `KeyboardEvent.key` values → Rive key names; older browsers send the short forms */
+const DOM_KEYS = {
+  Enter: 'enter',
+  ' ': 'space',
+  Spacebar: 'space',
+  Escape: 'escape',
+  Esc: 'escape',
+  Backspace: 'backspace',
+  ArrowUp: 'up',
+  Up: 'up',
+  ArrowDown: 'down',
+  Down: 'down',
+  ArrowLeft: 'left',
+  Left: 'left',
+  ArrowRight: 'right',
+  Right: 'right',
+  Tab: 'tab',
+  Delete: 'deleteKey',
+  Del: 'deleteKey',
+  Insert: 'insert',
+  Home: 'home',
+  End: 'end',
+  PageUp: 'pageUp',
+  PageDown: 'pageDown',
+}
+
+/** `keyCode` → Rive key names, for browsers that predate `key` */
+const KEY_CODES = { 8: 'backspace', 9: 'tab', 13: 'enter', 27: 'escape', 32: 'space', 33: 'pageUp', 34: 'pageDown', 35: 'end', 36: 'home', 37: 'left', 38: 'up', 39: 'right', 40: 'down', 45: 'insert', 46: 'deleteKey' }
+
+/** `KeyboardEvent.code` values that are not a letter, digit or function key → Rive key names */
+const DOM_CODES = {
+  NumpadEnter: 'kpEnter',
+  NumpadDecimal: 'kpDecimal',
+  NumpadDivide: 'kpDivide',
+  NumpadMultiply: 'kpMultiply',
+  NumpadSubtract: 'kpSubtract',
+  NumpadAdd: 'kpAdd',
+  Minus: 'minus',
+  Equal: 'equal',
+  Comma: 'comma',
+  Period: 'period',
+  Slash: 'slash',
+  Semicolon: 'semicolon',
+  Quote: 'apostrophe',
+  Backquote: 'graveAccent',
+  BracketLeft: 'leftBracket',
+  BracketRight: 'rightBracket',
+  Backslash: 'backslash',
+}
+
+/**
+ * The Rive key names a key stands for: a Roku remote name maps to its
+ * group, anything else is lowercased as given.
+ *
+ * @param   {string}   key
+ * @returns {string[]}
+ */
+export function keyNames(key) {
+  const roku = ROKU[/** @type {keyof typeof ROKU} */ (key)]
+  return roku ? roku : [ key.toLowerCase() ]
+}
+
+/**
+ * The Rive key name for a DOM keyboard event, or "" for a key no bundle listens for.
+ * `code` (the physical key, as Rive reads it) comes first, then `key`, then
+ * `keyCode` for browsers that predate both.
+ *
+ * @param   {{ key?: string, keyCode?: number, code?: string }} event
+ * @returns {string}
+ */
+export function keyFromEvent(event) {
+  const code = event.code
+  if (code) {
+    const letter = /^Key([A-Z])$/.exec(code)
+    if (letter) return letter[1].toLowerCase()
+    const digit = /^(Digit|Numpad)(\d)$/.exec(code)
+    if (digit) return (digit[1] === 'Digit' ? 'key' : 'kp') + digit[2]
+    const numbered = /^F(\d{1,2})$/.exec(code)
+    if (numbered) return 'f' + numbered[1]
+    const named = DOM_CODES[/** @type {keyof typeof DOM_CODES} */ (code)]
+    if (named) return named
+  }
+  const byKey = event.key ? DOM_KEYS[/** @type {keyof typeof DOM_KEYS} */ (event.key)] : undefined
+  if (byKey) return byKey
+
+  const byCode = event.keyCode ? KEY_CODES[/** @type {keyof typeof KEY_CODES} */ (event.keyCode)] : undefined
+  if (byCode) return byCode
+
+  // a printable key is listened for by its own character, lowercased; a digit is `key0`
+  if (event.key && event.key.length === 1) return /\d/.test(event.key) ? 'key' + event.key : event.key.toLowerCase()
+  return ''
+}
+
+/**
+ * The modifiers held during a DOM keyboard event, as a KeyboardInput's mask: 1 shift, 2 ctrl, 4 alt, 8 meta.
+ *
+ * @param   {{ shiftKey?: boolean, ctrlKey?: boolean, altKey?: boolean, metaKey?: boolean }} event
+ * @returns {number}
+ */
+export function modifiersFromEvent(event) {
+  return (event.shiftKey ? 1 : 0) + (event.ctrlKey ? 2 : 0) + (event.altKey ? 4 : 0) + (event.metaKey ? 8 : 0)
+}
+
+/**
+ * A key the host names as a string: `tab`, `OK`, `a`, with modifiers in front
+ * (`shift+tab`, `ctrl+a`).
+ *
+ * @param   {string}                                         text
+ * @returns {{ names: string[], mods: number, key: string }}
+ */
+export function parseKey(text) {
+  const parts = text.split('+')
+  let mods = 0
+  while (parts.length > 1) {
+    const part = parts[0].toLowerCase()
+    const bit = part === 'shift' ? 1 : part === 'ctrl' || part === 'control' ? 2 : part === 'alt' ? 4 : part === 'meta' || part === 'cmd' ? 8 : 0
+    if (!bit) break
+    mods += bit
+    parts.shift()
+  }
+  const key = parts.join('+')
+  return { names: keyNames(key), mods, key }
+}
+
+/**
+ * Whether a key clicks, as OK does on Roku: Enter, or Roku's OK.
+ *
+ * @param {string} key
+ */
+export function isClick(key) {
+  return key === 'OK' || key === 'enter'
+}