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

package/motion/motion.machine.js

@@ -0,0 +1,382 @@
+/**
+ * The state machine engine for dotLottie machines, as Roku's Motion runs it
+ * (runtime/roku/components/motion/state/state.bs): it answers "which state
+ * next?" and runs actions against a values table. It holds no state of its
+ * own; the flow owns the current state, the values and the pending events.
+ */
+
+/**
+ * @typedef {{ initial: string, states: any[], inputs?: any[], interactions?: any[], layers?: any[] }} Graph
+ * @typedef {Record<string, any>} Values  input name → value
+ * @typedef {Record<string, boolean>} Events  pending events, name → true
+ * @typedef {{ changed: boolean, events: string[], focus: any[] }} Effects  `focus`: the focus actions (FocusTarget, FocusMove, FocusClear) to run once the values are set
+ * @typedef {{ elapsed: number, length: number }} Clock  how long the current state has played, and how long its timeline is, in ms
+ * @typedef {import('../script/play/play.js').Scripts} Scripts  the scripts a bundle runs; without them a Script guard fails and a RunScript action does nothing
+ */
+
+/**
+ * @param   {any}     graph
+ * @returns {boolean}
+ */
+export function exists(graph) {
+  return !!graph && Array.isArray(graph.states) && typeof graph.initial === 'string'
+}
+
+/**
+ * @param {Graph}  graph
+ * @param {string} name
+ */
+export function find(graph, name) {
+  for (let n = 0; n < graph.states.length; n++) if (graph.states[n].name === name) return graph.states[n]
+  return null
+}
+
+/**
+ * The graphs of a machine's layers, each with the machine's inputs and
+ * interactions, which layers share. A machine without `layers` is one layer.
+ *
+ * @param   {Graph}   graph
+ * @returns {Graph[]}
+ */
+export function layersOf(graph) {
+  const layers = graph.layers
+  if (!layers || layers.length < 2) return [ graph ]
+  return layers.map((/** @type {any} */ layer, /** @type {number} */ n) => (n === 0 ? graph : { initial: layer.initial, states: layer.states, inputs: graph.inputs, interactions: graph.interactions }))
+}
+
+/**
+ * Every input's authored value; events have none.
+ *
+ * @param   {Graph}  graph
+ * @returns {Values}
+ */
+export function defaults(graph) {
+  /** @type {Values} */
+  const values = {}
+  const inputs = graph.inputs || []
+  for (let n = 0; n < inputs.length; n++) if (inputs[n].type !== 'Event') values[inputs[n].name] = inputs[n].value
+  return values
+}
+
+/**
+ * @param {Graph}  graph
+ * @param {string} name
+ */
+export function isEvent(graph, name) {
+  const inputs = graph.inputs || []
+  for (let n = 0; n < inputs.length; n++) if (inputs[n].name === name) return inputs[n].type === 'Event'
+  return false
+}
+
+// Transitions
+// ■■■■■■■■■■■
+
+/**
+ * Global states' transitions are checked first, then the current state's;
+ * the first whose guards all pass wins. A transition back into the current
+ * state from a global one is skipped, or it would fire forever.
+ *
+ * @param   {Graph}        graph
+ * @param   {string}       current
+ * @param   {Values}       values
+ * @param   {Events}       events
+ * @param   {Clock | null} [clock] the current state's time, for exit times; without it exit times are not checked
+ * @param   {Scripts | null} [scripts]
+ * @returns {string}               the next state, or ""
+ */
+export function nextState(graph, current, values, events, clock, scripts) {
+  const transition = takeTransition(graph, current, values, events, clock || null, scripts || null)
+  return transition ? transition.toState : ''
+}
+
+/**
+ * The transition `nextState` takes, whole: its `durationMs` is how long the
+ * outgoing and incoming states cross-fade.
+ *
+ * @param   {Graph}        graph
+ * @param   {string}       current
+ * @param   {Values}       values
+ * @param   {Events}       events
+ * @param   {Clock | null} clock
+ * @param   {Scripts | null} [scripts]
+ * @returns {any}                  the transition, or null
+ */
+export function takeTransition(graph, current, values, events, clock, scripts) {
+  for (let n = 0; n < graph.states.length; n++) {
+    const state = graph.states[n]
+    if (state.type !== 'GlobalState') continue
+    const transition = firstPassing(state.transitions, values, events, current, clock, scripts || null)
+    if (transition) return transition
+  }
+
+  const state = find(graph, current)
+  return state ? firstPassing(state.transitions, values, events, '', clock, scripts || null) : null
+}
+
+/**
+ * When a transition's exit time is reached, in ms into its state.
+ *
+ * @param   {any}    transition
+ * @param   {number} length     the state's timeline, in ms
+ * @returns {number}            0 for a transition without an exit time
+ */
+export function exitMs(transition, length) {
+  const exit = transition.exitTime
+  if (!exit) return 0
+  return typeof exit.ms === 'number' ? exit.ms : (exit.fraction || 0) * length
+}
+
+/**
+ * The earliest exit time among a state's transitions after `after`, in ms.
+ *
+ * @param   {any}    state
+ * @param   {number} length the state's timeline, in ms
+ * @param   {number} after  an exit time already reached, or -1
+ * @returns {number}        -1 when no exit time is left
+ */
+export function nextExit(state, length, after) {
+  let next = -1
+  const list = (state && state.transitions) || []
+  for (let n = 0; n < list.length; n++) {
+    if (!list[n].exitTime) continue
+    const at = exitMs(list[n], length)
+    if (at > after && (next < 0 || at < next)) next = at
+  }
+  return next
+}
+
+/**
+ * @param {any[]}        transitions
+ * @param {Values}       values
+ * @param {Events}       events
+ * @param {string}       skip        a target to pass over, or ""
+ * @param {Clock | null} clock
+ * @param {Scripts | null} scripts
+ */
+function firstPassing(transitions, values, events, skip, clock, scripts) {
+  const list = transitions || []
+  for (let n = 0; n < list.length; n++) {
+    const transition = list[n]
+    if (transition.toState === skip) continue
+
+    // with a clock, an exit time is checked exactly and replaces the guard that waits for the whole timeline
+    const isTimed = !!clock && !!transition.exitTime
+    if (isTimed && clock.elapsed < exitMs(transition, clock.length)) continue
+    if (guardsPass(transition.guards, values, events, isTimed, scripts)) return transition
+  }
+  return null
+}
+
+/**
+ * @param {any[]}   guards  no guards always pass
+ * @param {Values}  values
+ * @param {Events}  events
+ * @param {boolean} isTimed the transition's exit time is checked apart; its `exit` guard is skipped
+ * @param {Scripts | null} scripts
+ */
+function guardsPass(guards, values, events, isTimed, scripts) {
+  const list = guards || []
+  for (let n = 0; n < list.length; n++) {
+    if (isTimed && list[n].exit === true) continue
+    if (!guardPasses(list[n], values, events, scripts)) return false
+  }
+  return true
+}
+
+/**
+ * A guard compares only values of its own type, as the Roku engine must.
+ *
+ * @param {any}    guard
+ * @param {Values} values
+ * @param {Events} events
+ * @param {Scripts | null} scripts
+ */
+function guardPasses(guard, values, events, scripts) {
+  if (guard.type === 'Event') return events[guard.inputName] === true
+  // a scripted condition: the script says; with no way to run it, it does not pass
+  if (guard.type === 'Script') return !!scripts && scripts.evaluate(guard, values)
+
+  const value = values[guard.inputName]
+  const expected = resolve(guard.compareTo, values)
+  const condition = guard.conditionType
+
+  const isNumeric = guard.type === 'Numeric' && typeof value === 'number' && typeof expected === 'number'
+  if (isNumeric) return compare(value, condition, expected)
+
+  const isBoolean = guard.type === 'Boolean' && typeof value === 'boolean' && typeof expected === 'boolean'
+  const isString = guard.type === 'String' && typeof value === 'string' && typeof expected === 'string'
+  if (!isBoolean && !isString) return false
+
+  return condition === 'NotEqual' ? value !== expected : value === expected
+}
+
+/**
+ * @param {number} a
+ * @param {string} condition
+ * @param {number} b
+ */
+function compare(a, condition, b) {
+  switch (condition) {
+    case 'NotEqual': return a !== b
+    case 'GreaterThan': return a > b
+    case 'GreaterThanOrEqual': return a >= b
+    case 'LessThan': return a < b
+    case 'LessThanOrEqual': return a <= b
+    default: return a === b
+  }
+}
+
+// Actions
+// ■■■■■■■
+
+/**
+ * Runs actions against the values. SetFrame, SetProgress and SetTheme have
+ * nothing to act on here and are skipped, as on Roku.
+ *
+ * @param   {any[]}   actions
+ * @param   {Graph}   graph
+ * @param   {Values}  values  updated in place
+ * @param   {Events}  events  updated in place: Fire adds a pending event
+ * @param   {Scripts | null} [scripts]  runs a RunScript action
+ * @param   {string}  [trigger] the interaction the actions run for, which a script's pointer event is of
+ * @returns {Effects}
+ */
+export function perform(actions, graph, values, events, scripts, trigger) {
+  /** @type {Effects} */
+  const effects = { changed: false, events: [], focus: [] }
+  const list = actions || []
+  for (let n = 0; n < list.length; n++) runOne(list[n], graph, values, events, effects, scripts || null, trigger || '')
+  return effects
+}
+
+/**
+ * @param {any}     action
+ * @param {Graph}   graph
+ * @param {Values}  values
+ * @param {Events}  events
+ * @param {Effects} effects
+ * @param {Scripts | null} scripts
+ * @param {string}  trigger
+ */
+function runOne(action, graph, values, events, effects, scripts, trigger) {
+  const name = action.inputName
+  const current = values[name]
+  switch (action.type) {
+    case 'Fire':
+      events[name] = true
+      break
+    case 'FireCustomEvent':
+      effects.events.push(action.value)
+      break
+    case 'FocusTarget':
+    case 'FocusMove':
+    case 'FocusClear':
+      effects.focus.push(action)
+      break
+    case 'OpenUrl':
+      effects.events.push('openUrl:' + action.url)
+      break
+    case 'RunScript':
+      if (scripts && scripts.perform(action, trigger, values, events)) effects.changed = true
+      break
+    case 'Toggle':
+      if (typeof current === 'boolean') setValue(values, name, !current, effects)
+      break
+    case 'Increment':
+    case 'Decrement':
+      if (typeof current === 'number') setValue(values, name, current + stepSize(action, values), effects)
+      break
+    case 'Reset':
+      setValue(values, name, defaults(graph)[name], effects)
+      break
+    case 'SetBoolean':
+    case 'SetNumeric':
+    case 'SetString':
+      setValue(values, name, resolve(action.value, values), effects)
+      break
+    default:
+  }
+}
+
+/**
+ * The action's value, or 1 when it names no number; negative to decrement.
+ *
+ * @param {any}    action
+ * @param {Values} values
+ */
+function stepSize(action, values) {
+  const size = resolve(action.value, values)
+  const step = typeof size === 'number' ? size : 1
+  return action.type === 'Decrement' ? -step : step
+}
+
+/**
+ * A literal, or "$name" naming another input.
+ *
+ * @param {any}    value
+ * @param {Values} values
+ */
+function resolve(value, values) {
+  return typeof value === 'string' && value.charAt(0) === '$' ? values[value.slice(1)] : value
+}
+
+/**
+ * @param {Values}  values
+ * @param {string}  name
+ * @param {any}     value
+ * @param {Effects} effects
+ */
+function setValue(values, name, value, effects) {
+  if (value === undefined || value === null) return
+  if (values[name] === value) return
+  values[name] = value
+  effects.changed = true
+}
+
+// Interactions
+// ■■■■■■■■■■■■
+
+/**
+ * Every action the matching interactions run, in order.
+ *
+ * @param   {Graph}  graph
+ * @param   {string} kind      "Click", "OnComplete", or a pointer interaction ("PointerEnter", ...)
+ * @param   {string} stateName for lifecycle interactions; "" matches any
+ * @param   {string} [target]  a pointer interaction's target `rid`; "" for those without a target; omitted matches any
+ * @returns {any[]}
+ */
+export function interactionActions(graph, kind, stateName, target) {
+  const actions = []
+  const list = graph.interactions || []
+  for (let n = 0; n < list.length; n++) {
+    const interaction = list[n]
+    const isStateMatch = stateName === '' || typeof interaction.stateName !== 'string' || interaction.stateName === stateName
+    const isTargetMatch = target === undefined || (interaction.target ? interaction.target.rid : '') === target
+    if (interaction.type === kind && isStateMatch && isTargetMatch) for (let k = 0; k < interaction.actions.length; k++) actions.push(interaction.actions[k])
+  }
+  return actions
+}
+
+/** The interactions a pointer sets off */
+const POINTER_TYPES = [ 'Click', 'PointerDown', 'PointerUp', 'PointerEnter', 'PointerExit', 'PointerMove' ]
+
+/**
+ * Where the pointer interactions listen: each target's `rid`, or "" for the
+ * listeners without one, which watch the whole artboard, and the types on it.
+ *
+ * @param   {Graph}                    graph
+ * @returns {Record<string, string[]>}
+ */
+export function pointerTargetsOf(graph) {
+  /** @type {Record<string, string[]>} */
+  const found = {}
+  const list = graph.interactions || []
+  for (let n = 0; n < list.length; n++) {
+    const interaction = list[n]
+    if (POINTER_TYPES.indexOf(interaction.type) < 0) continue
+    const rid = interaction.target ? interaction.target.rid : ''
+    if (!found[rid]) found[rid] = []
+    if (found[rid].indexOf(interaction.type) < 0) found[rid].push(interaction.type)
+  }
+  return found
+}