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

package/motion/motion.convert.js

@@ -0,0 +1,404 @@
+/**
+ * Data converters: the declarative descriptors a bundle's `data.slots` carry
+ * on a source (rive2lottie writes them, dotlottie.converters.js lists them),
+ * applied to a view-model value on its way to a slot, and reversed for a bind
+ * that writes back. A descriptor type this code does not know warns once and
+ * passes the value through.
+ *
+ * The same arithmetic runs at build time for the default instance
+ * (dotlottie.convert.js in the converter) and on Roku (bundle.convert.bs).
+ */
+
+/**
+ * @typedef {object} ConvertContext
+ * @property {(path: string) => any}     [read]  a view-model property's value, by dotted path
+ * @property {string[]}                  [names] the names of an enum the value indexes
+ * @property {(message: string) => void} [warn]
+ * @property {import('../script/play/play.js').Scripts} [scripts]  runs the bundle's script converters
+ * @property {string}                     [type]   the bound property's type, so a script is given a colour as one
+ * @property {Record<string, any>}         [values] every live value, which a script can read
+ */
+
+/**
+ * Operations of an `operation` descriptor and a formula, by name.
+ * @type {Record<string, (a: number, b: number) => number>}
+ */
+const OPERATIONS = {
+  add: (a, b) => a + b,
+  sub: (a, b) => a - b,
+  mul: (a, b) => a * b,
+  div: (a, b) => (b === 0 ? 0 : a / b),
+  mod: (a, b) => (b === 0 ? 0 : a % b),
+  sqrt: (a) => Math.sqrt(a),
+  pow: (a, b) => Math.pow(a, b),
+  exp: (a) => Math.exp(a),
+  log: (a) => Math.log(a),
+  cos: (a) => Math.cos(a),
+  sin: (a) => Math.sin(a),
+  tan: (a) => Math.tan(a),
+  acos: (a) => Math.acos(a),
+  asin: (a) => Math.asin(a),
+  atan: (a) => Math.atan(a),
+  atan2: (a, b) => Math.atan2(a, b),
+  round: (a) => Math.round(a),
+  floor: (a) => Math.floor(a),
+  ceil: (a) => Math.ceil(a),
+}
+
+/**
+ * Formula functions: the arguments are a list.
+ * @type {Record<string, (args: number[]) => number>}
+ */
+const FUNCTIONS = {
+  min: (args) => Math.min.apply(Math, args),
+  max: (args) => Math.max.apply(Math, args),
+  round: (args) => Math.round(args[0]),
+  ceil: (args) => Math.ceil(args[0]),
+  floor: (args) => Math.floor(args[0]),
+  sqrt: (args) => Math.sqrt(args[0]),
+  pow: (args) => Math.pow(args[0], args[1]),
+  exp: (args) => Math.exp(args[0]),
+  log: (args) => Math.log(args[0]),
+  cos: (args) => Math.cos(args[0]),
+  sin: (args) => Math.sin(args[0]),
+  tan: (args) => Math.tan(args[0]),
+  acos: (args) => Math.acos(args[0]),
+  asin: (args) => Math.asin(args[0]),
+  atan: (args) => Math.atan(args[0]),
+  atan2: (args) => Math.atan2(args[0], args[1]),
+  random: () => Math.random(),
+}
+
+/**
+ * Binding strength of a formula's operation tokens: the rest bind tightest.
+ * @type {Record<string, number>}
+ */
+const PRECEDENCE = { add: 1, sub: 1, mul: 2, div: 2, mod: 2 }
+
+/**
+ * Unknown descriptor types already warned about
+ * @type {Record<string, boolean>}
+ */
+const warned = {}
+
+/**
+ * Whether a value is a number the converters can work on.
+ * @param {any} value
+ */
+function numeric(value) {
+  const n = typeof value === 'number' ? value : parseFloat(value)
+  return isFinite(n) ? n : 0
+}
+
+/**
+ * Applies a descriptor to a view-model value.
+ *
+ * @param   {any}            descriptor
+ * @param   {any}            value
+ * @param   {ConvertContext} [context]
+ * @returns {any}
+ */
+export function applyConverter(descriptor, value, context) {
+  const ctx = context || {}
+  switch (descriptor && descriptor.type) {
+    case 'negate':
+      return !value
+    case 'range':
+      return range(descriptor, numeric(value))
+    case 'round':
+      return roundTo(numeric(value), descriptor.decimals)
+    case 'operation':
+      return operate(descriptor.op, numeric(value), operand(descriptor, ctx))
+    case 'formula':
+      return formula(descriptor.tokens || [], numeric(value), ctx)
+    case 'toString':
+      return toText(descriptor, value, ctx)
+    case 'toNumber':
+      return numeric(value)
+    case 'pad':
+      return pad(descriptor, String(value === undefined || value === null ? '' : value))
+    case 'trim': {
+      let text = String(value === undefined || value === null ? '' : value)
+      if (descriptor.trimStart) text = text.replace(/^\s+/, '')
+      if (descriptor.trimEnd) text = text.replace(/\s+$/, '')
+      return text
+    }
+    case 'removeZeros':
+      return trimZeros(String(value === undefined || value === null ? '' : value))
+    case 'enumToUint':
+      return enumIndex(value, ctx.names)
+    case 'listLength':
+      return Array.isArray(value) ? value.length : 0
+    case 'solo':
+      return soloVisibility(descriptor, value)
+    case 'group': {
+      let result = value
+      const items = descriptor.items || []
+      // only the first link sees the enum names
+      for (let n = 0; n < items.length; n++) result = applyConverter(items[n], result, n === 0 ? ctx : { read: ctx.read, warn: ctx.warn, scripts: ctx.scripts, values: ctx.values })
+      return result
+    }
+    case 'script':
+      // run by the bundle's script host; without one the value passes through
+      if (ctx.scripts) return ctx.scripts.convert(descriptor, value, false, ctx.type === 'color' ? 'color' : undefined, ctx.values)
+      warnUnknown(descriptor, ctx)
+      return value
+    default:
+      warnUnknown(descriptor, ctx)
+      return value
+  }
+}
+
+/**
+ * Undoes a descriptor for a bind that writes a property back into the view
+ * model. What cannot be undone (a formula, a rounding) passes the value on.
+ *
+ * @param   {any}            descriptor
+ * @param   {any}            value      the target property's value
+ * @param   {ConvertContext} [context]
+ * @returns {any}
+ */
+export function reverseConverter(descriptor, value, context) {
+  const ctx = context || {}
+  switch (descriptor && descriptor.type) {
+    case 'negate':
+      return !value
+    case 'range':
+      return unrange(descriptor, numeric(value))
+    case 'operation': {
+      /** @type {Record<string, string>} */
+      const inverses = { add: 'sub', sub: 'add', mul: 'div', div: 'mul' }
+      const inverse = inverses[descriptor.op]
+      return inverse ? operate(inverse, numeric(value), operand(descriptor, ctx)) : value
+    }
+    case 'toString':
+      return numeric(value)
+    case 'toNumber':
+      return String(value)
+    case 'group': {
+      let result = value
+      const items = descriptor.items || []
+      for (let n = items.length - 1; n >= 0; n--) result = reverseConverter(items[n], result, ctx)
+      return result
+    }
+    case 'script':
+      return ctx.scripts ? ctx.scripts.convert(descriptor, value, true) : value
+    default:
+      return value
+  }
+}
+
+/**
+ * Applies descriptors in order.
+ *
+ * @param {any}            descriptor a descriptor, or null for none
+ * @param {any}            value
+ * @param {ConvertContext} [context]
+ */
+export function convertValue(descriptor, value, context) {
+  return descriptor ? applyConverter(descriptor, value, context) : value
+}
+
+/**
+ * @param {any}            descriptor
+ * @param {ConvertContext} ctx
+ */
+function warnUnknown(descriptor, ctx) {
+  const type = descriptor && descriptor.type
+  if (warned[type] || !ctx.warn) return
+  warned[type] = true
+  ctx.warn("data converter '" + type + "' is not known to this player; its value passes through")
+}
+
+/**
+ * The right-hand side of an operation: a literal, or another property's value.
+ *
+ * @param {any}            descriptor
+ * @param {ConvertContext} ctx
+ */
+function operand(descriptor, ctx) {
+  if (typeof descriptor.path === 'string') return numeric(ctx.read ? ctx.read(descriptor.path) : 0)
+  return numeric(descriptor.value)
+}
+
+/**
+ * @param {string} op
+ * @param {number} a
+ * @param {number} b
+ */
+function operate(op, a, b) {
+  const fn = OPERATIONS[op]
+  return fn ? fn(a, b) : a
+}
+
+/**
+ * @param {number} value
+ * @param {number} decimals
+ */
+function roundTo(value, decimals) {
+  const scale = Math.pow(10, decimals || 0)
+  return Math.round(value * scale) / scale
+}
+
+/**
+ * A range mapper: the input's position in its range, placed in the output's.
+ *
+ * @param {any}    d
+ * @param {number} input
+ */
+function range(d, input) {
+  const low = Math.min(d.minInput, d.maxInput)
+  const high = Math.max(d.minInput, d.maxInput)
+  let x = input
+  if (d.modulo && high > low) x = low + ((((x - low) % (high - low)) + (high - low)) % (high - low))
+  if (d.clampLower && x < low) x = low
+  if (d.clampUpper && x > high) x = high
+
+  const span = d.maxInput - d.minInput
+  let t = span === 0 ? 0 : (x - d.minInput) / span
+  if (d.hold) t = t >= 1 ? 1 : 0
+  if (d.reverse) t = 1 - t
+  return d.minOutput + t * (d.maxOutput - d.minOutput)
+}
+
+/**
+ * @param {any}    d
+ * @param {number} output
+ */
+function unrange(d, output) {
+  const span = d.maxOutput - d.minOutput
+  let t = span === 0 ? 0 : (output - d.minOutput) / span
+  if (d.reverse) t = 1 - t
+  let x = d.minInput + t * (d.maxInput - d.minInput)
+  const low = Math.min(d.minInput, d.maxInput)
+  const high = Math.max(d.minInput, d.maxInput)
+  if (d.clampLower && x < low) x = low
+  if (d.clampUpper && x > high) x = high
+  return x
+}
+
+/**
+ * A formula's tokens read as an infix expression.
+ *
+ * @param {any[]}          tokens
+ * @param {number}         input
+ * @param {ConvertContext} ctx
+ */
+function formula(tokens, input, ctx) {
+  let at = 0
+
+  /** @param {number} minimum */
+  function expression(minimum) {
+    /** @type {number} */
+    let left = operandOf()
+    while (at < tokens.length && tokens[at].token === 'op') {
+      const op = tokens[at].op
+      const strength = PRECEDENCE[op] || 3
+      if (strength < minimum) break
+      at++
+      left = operate(op, left, expression(strength + 1))
+    }
+    return left
+  }
+
+  /** @returns {number} */
+  function operandOf() {
+    const token = tokens[at++]
+    if (!token) return 0
+    if (token.token === 'input') return input
+    if (token.token === 'value') return typeof token.path === 'string' ? numeric(ctx.read ? ctx.read(token.path) : 0) : numeric(token.value)
+    if (token.token === 'open') {
+      /** @type {number} */
+      const inner = expression(0)
+      if (at < tokens.length && tokens[at].token === 'close') at++
+      return inner
+    }
+    if (token.token === 'op' && token.op === 'sub') return -operandOf()
+    if (token.token === 'fn') {
+      const args = []
+      while (at < tokens.length && tokens[at].token !== 'close') {
+        args.push(expression(0))
+        if (at < tokens.length && tokens[at].token === 'sep') at++
+      }
+      at++
+      const fn = FUNCTIONS[token.fn]
+      return fn ? fn(args) : 0
+    }
+    return 0
+  }
+
+  const result = expression(0)
+  return isFinite(result) ? result : 0
+}
+
+/**
+ * ToString: a number to text at the converter's precision, a colour to hex,
+ * an enum index to its name.
+ *
+ * @param {any}            d
+ * @param {any}            value
+ * @param {ConvertContext} ctx
+ */
+function toText(d, value, ctx) {
+  if (typeof value === 'boolean') return value ? 'true' : 'false'
+  if (typeof value === 'string') return value
+  if (ctx.names && typeof value === 'number' && ctx.names[value] !== undefined) return ctx.names[value]
+  if (typeof value !== 'number') return value === undefined || value === null ? '' : String(value)
+
+  // Rive holds numbers as 32-bit floats, which rounds 25.55 to 25.5499992
+  const single = Math.fround ? Math.fround(value) : value
+  let text = d.round ? single.toFixed(d.decimals || 0) : single.toFixed(6)
+  if (d.trimZeros) text = trimZeros(text)
+  return text
+}
+
+/** @param {string} text */
+function trimZeros(text) {
+  return text.indexOf('.') < 0 ? text : text.replace(/0+$/, '').replace(/\.$/, '')
+}
+
+/**
+ * @param {any}    d
+ * @param {string} text
+ */
+function pad(d, text) {
+  const filler = String(d.text || '')
+  if (!filler) return text
+  const wanted = Math.max(d.length, text.length)
+  let result = text
+  while (result.length < wanted) result = d.atEnd ? result + filler : filler + result
+  return d.atEnd ? result.slice(0, wanted) : result.slice(result.length - wanted)
+}
+
+/**
+ * A Solo option's visibility, in percent: 100 when the bound value names it,
+ * 0 otherwise. A number names an option by its place among the Solo's options
+ * (`index`), an enum or a string by name (`names`, the ones that pick the
+ * option; an enum's value is its index, which `ids` lists). A descriptor with
+ * neither is an option no value reaches.
+ *
+ * @param {any}            d
+ * @param {any}            value
+ */
+function soloVisibility(d, value) {
+  if (Array.isArray(d.names)) {
+    if (typeof value === 'string') return d.names.indexOf(value) >= 0 ? 100 : 0
+    return Array.isArray(d.ids) && typeof value === 'number' && d.ids.indexOf(value) >= 0 ? 100 : 0
+  }
+  if (typeof d.index === 'number') return Math.round(numeric(value)) === d.index ? 100 : 0
+  return 0
+}
+
+/**
+ * An enum value as its index, from an index or a name.
+ *
+ * @param {any}      value
+ * @param {string[]} [names]
+ */
+function enumIndex(value, names) {
+  if (typeof value === 'string' && names) {
+    const at = names.indexOf(value)
+    if (at >= 0) return at
+  }
+  return numeric(value)
+}