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

package/motion/motion.values.js

@@ -0,0 +1,364 @@
+/**
+ * Live data: view-model values to slot values in Lottie units (as Roku's
+ * Motion.Task patches them, bundle.bs), to tint colours for raster sheets
+ * (motion.tint.bs), and from the string pairs a host such as maestro-web-sdk
+ * holds, typed by the bundle's own property declarations.
+ */
+
+import { applyConverter, reverseConverter } from './motion.convert.js'
+
+/**
+ * A bundle's `data` block: the view model's properties (nested ones by dotted
+ * path, enums with their `values`, images with their `images`), its slots,
+ * the write-backs (`writes`) and instances.
+ * @typedef {{ properties?: any[], slots?: any[], writes?: any[], instances?: Record<string, any>, defaultInstance?: string }} Data
+ */
+
+/**
+ * A colour as a caller gives it: an ARGB number (as Rive and JSON hold it),
+ * `#RRGGBB`, `#AARRGGBB`, `0x`-prefixed, or `[r, g, b, a]` in 0-1.
+ *
+ * @param   {any}             value
+ * @returns {number[] | null}       `[r, g, b, a]` in 0-1
+ */
+export function rgba(value) {
+  if (Array.isArray(value)) return value
+  if (typeof value === 'number' && isFinite(value)) {
+    // above 2^31 a colour isn't safe for bit operations, so it's split by division
+    let whole = Math.floor(value)
+    const channels = []
+    for (let n = 0; n < 4; n++) {
+      channels.unshift((whole % 256) / 255)
+      whole = Math.floor(whole / 256)
+    }
+    return [ channels[1], channels[2], channels[3], channels[0] ]
+  }
+  if (typeof value === 'string') {
+    const hex = value.replace(/^#|^0x/i, '')
+    const isHex = /^[0-9a-f]{6}([0-9a-f]{2})?$/i.test(hex)
+    if (!isHex) return null
+    const byte = (/** @type {number} */ at) => parseInt(hex.slice(at, at + 2), 16) / 255
+    return hex.length === 6 ? [ byte(0), byte(2), byte(4), 1 ] : [ byte(2), byte(4), byte(6), byte(0) ]
+  }
+  return null
+}
+
+/**
+ * A view-model value in a slot's Lottie units: colours as `[r, g, b, 1]`,
+ * alphas and percents ×100, radians to degrees.
+ *
+ * @param {any}    value
+ * @param {string} conversion color, alpha, percent, degrees, number, text or image
+ * @param {any}    [property] the view-model property the value is of: an enum names its values, an image its assets
+ */
+export function convert(value, conversion, property) {
+  if (conversion === 'color' || conversion === 'alpha') {
+    const colour = rgba(value)
+    if (!colour) return undefined
+    return conversion === 'alpha' ? colour[3] * 100 : [ colour[0], colour[1], colour[2], 1 ]
+  }
+  if (conversion === 'text') return property && property.values && typeof value === 'number' && property.values[value] !== undefined ? property.values[value] : value
+  if (conversion === 'image') return assetId(value, property)
+  if (typeof value !== 'number') return undefined
+  if (conversion === 'percent') return value * 100
+  if (conversion === 'degrees') return (value * 180) / Math.PI
+  return value
+}
+
+/**
+ * The Lottie asset an image value picks: by the asset's name, by its Lottie
+ * id, or by its index in the file.
+ *
+ * @param {any} value
+ * @param {any} [property]
+ */
+function assetId(value, property) {
+  const images = (property && property.images) || {}
+  if (typeof value === 'string') {
+    if (images[value]) return images[value]
+    return /^image_\d+$/.test(value) ? value : undefined
+  }
+  return typeof value === 'number' ? 'image_' + value : undefined
+}
+
+/**
+ * The slot table for a set of values: slot id → Lottie value, for every slot
+ * some input fills. A 2-D slot keeps its base value on an axis no source fills.
+ *
+ * @param   {Data}                      data
+ * @param   {Record<string, any>}       values
+ * @param   {(message: string) => void} [warn] a converter this player does not know
+ * @returns {Record<string, any>}
+ */
+export function slotValues(data, values, warn) {
+  /** @type {Record<string, any>} */
+  const table = {}
+  const slots = (data && data.slots) || []
+  for (let n = 0; n < slots.length; n++) {
+    const slot = slots[n]
+    const value = slotValue(slot, values, data, warn)
+    if (value !== undefined) table[slot.sid] = value
+  }
+  return table
+}
+
+/**
+ * A view-model property's declaration, by its dotted path.
+ *
+ * @param   {Data}   data
+ * @param   {string} path
+ * @returns {any}
+ */
+export function propertyOf(data, path) {
+  const properties = (data && data.properties) || []
+  for (let n = 0; n < properties.length; n++) if (properties[n].name === path) return properties[n]
+  return null
+}
+
+/**
+ * What a source reads: its view-model value, through its converter.
+ *
+ * @param {any}                       source
+ * @param {Record<string, any>}       values
+ * @param {Data}                      data
+ * @param {(message: string) => void} [warn]
+ */
+function sourceValue(source, values, data, warn) {
+  const raw = values[source.path]
+  if (raw === undefined || !source.converter) return raw
+  const property = propertyOf(data, source.path)
+  return applyConverter(source.converter, raw, { read: (path) => values[path], names: property && property.values, warn })
+}
+
+/**
+ * @param {any}                       slot
+ * @param {Record<string, any>}       values
+ * @param {Data}                      data
+ * @param {(message: string) => void} [warn]
+ */
+function slotValue(slot, values, data, warn) {
+  const sources = slot.sources || []
+  if (!sources.length) return undefined
+
+  const isPair = slot.type === 'Position' || slot.type === 'Vector'
+  if (!isPair) {
+    const raw = sourceValue(sources[0], values, data, warn)
+    return raw === undefined ? undefined : convert(raw, slot.conversion, propertyOf(data, sources[0].path))
+  }
+
+  const pair = Array.isArray(slot.base) ? slot.base.slice() : [ 0, 0 ]
+  let found = false
+  for (let n = 0; n < sources.length; n++) {
+    const raw = sourceValue(sources[n], values, data, warn)
+    if (raw === undefined) continue
+    const converted = convert(raw, slot.conversion)
+    if (converted === undefined) continue
+    pair[sources[n].axis || 0] = converted
+    found = true
+  }
+  return found ? pair : undefined
+}
+
+/**
+ * Inputs with nested objects flattened to dotted paths: `{ player: { score: 3 } }`
+ * is `{ 'player.score': 3 }`. Arrays (a list's items) are values, not paths.
+ *
+ * @param   {Record<string, any>} inputs
+ * @returns {Record<string, any>}
+ */
+export function flattenInputs(inputs) {
+  /** @type {Record<string, any>} */
+  const result = {}
+  const visit = (/** @type {Record<string, any>} */ object, /** @type {string} */ prefix) => {
+    for (const key in object) {
+      const value = object[key]
+      const isGroup = typeof value === 'object' && value !== null && !Array.isArray(value)
+      if (isGroup) visit(value, prefix + key + '.')
+      else result[prefix + key] = value
+    }
+  }
+  visit(inputs || {}, '')
+  return result
+}
+
+/**
+ * An input as the flow holds it: an enum given by name becomes its index, so
+ * the machine's numeric guards compare it.
+ *
+ * @param   {Data}   data
+ * @param   {string} name  the input's dotted path
+ * @param   {any}    value
+ * @returns {any}
+ */
+export function inputValue(data, name, value) {
+  const property = propertyOf(data, name)
+  if (!property || !property.values || typeof value !== 'string') return value
+  const index = property.values.indexOf(value)
+  if (index >= 0) return index
+  return isFinite(Number(value)) && value !== '' ? Number(value) : value
+}
+
+/**
+ * The values a host sees: an enum as the name of its value.
+ *
+ * @param   {Data}                data
+ * @param   {Record<string, any>} values
+ * @returns {Record<string, any>}
+ */
+export function publicValues(data, values) {
+  /** @type {Record<string, any>} */
+  const result = {}
+  for (const name in values) {
+    const property = propertyOf(data, name)
+    const named = property && property.values && typeof values[name] === 'number' ? property.values[values[name]] : undefined
+    result[name] = named === undefined ? values[name] : named
+  }
+  return result
+}
+
+/**
+ * A property the animation draws, back in the view model's units.
+ *
+ * @param {any} write   a `data.writes` entry
+ * @param {any} drawn   the Lottie property's value
+ * @param {any} current the view-model value now, whose alpha a colour keeps
+ */
+export function writtenValue(write, drawn, current) {
+  const isPair = write.type === 'Position' || write.type === 'Vector'
+  let value = isPair && Array.isArray(drawn) ? drawn[write.axis || 0] : drawn
+  switch (write.conversion) {
+    case 'color': {
+      if (!Array.isArray(value)) return undefined
+      const colour = rgba(current)
+      const alpha = colour ? Math.round(colour[3] * 255) : 255
+      const channel = (/** @type {number} */ at) => Math.round(value[at] * 255)
+      return alpha * 16777216 + channel(0) * 65536 + channel(1) * 256 + channel(2)
+    }
+    case 'percent':
+      value = value / 100
+      break
+    case 'degrees':
+      value = (value * Math.PI) / 180
+      break
+    case 'alpha':
+      return undefined
+    default:
+      break
+  }
+  if (typeof value !== 'number' || !isFinite(value)) return undefined
+  return write.converter ? reverseConverter(write.converter, value) : value
+}
+
+/**
+ * Each tint's live colour and opacity, for raster sheets: the slot's input
+ * when it has one, else the tint's own.
+ *
+ * @param   {any[]}                                           tints  a raster entry's `tints`
+ * @param   {Data}                                            data
+ * @param   {Record<string, any>}                             values
+ * @returns {{ sid: string, rgb: number[], alpha: number }[]}
+ */
+export function tintColors(tints, data, values) {
+  const result = []
+  for (let n = 0; n < (tints || []).length; n++) {
+    const tint = tints[n]
+    const live = rgba(slotInput(data, tint.sid, values))
+    const liveAlpha = tint.alphaSid ? alphaOf(data, tint.alphaSid, values) : undefined
+    result.push({ sid: tint.sid, rgb: live ? live.slice(0, 3) : tint.color, alpha: typeof liveAlpha === 'number' ? liveAlpha : tint.alpha })
+  }
+  return result
+}
+
+/**
+ * @param {Data}                data
+ * @param {string}              sid
+ * @param {Record<string, any>} values
+ */
+function slotInput(data, sid, values) {
+  const slot = findSlot(data, sid)
+  return slot ? values[slot.sources[0].path] : undefined
+}
+
+/**
+ * A Rive colour carries its alpha; a Rive opacity is 0-1; a Lottie one 0-100.
+ *
+ * @param {Data}                data
+ * @param {string}              sid
+ * @param {Record<string, any>} values
+ */
+function alphaOf(data, sid, values) {
+  const slot = findSlot(data, sid)
+  if (!slot) return undefined
+  const raw = values[slot.sources[0].path]
+  if (raw === undefined) return undefined
+  if (slot.conversion === 'alpha') {
+    const colour = rgba(raw)
+    return colour && colour.length > 3 ? colour[3] : undefined
+  }
+  if (typeof raw !== 'number') return undefined
+  return slot.conversion === 'percent' ? raw : raw / 100
+}
+
+/**
+ * @param {Data}   data
+ * @param {string} sid
+ */
+export function findSlot(data, sid) {
+  const slots = (data && data.slots) || []
+  for (let n = 0; n < slots.length; n++) {
+    const slot = slots[n]
+    if (slot.sid === sid && slot.sources && slot.sources.length) return slot
+  }
+  return null
+}
+
+/**
+ * Values from `{ key, value }` string pairs, typed by the view model's own
+ * property declarations, so a colour named anything reads as a colour. A key
+ * the bundle doesn't declare is kept as given.
+ *
+ * @param   {Data}                             data
+ * @param   {{ key: string, value: string }[]} pairs
+ * @returns {Record<string, any>}
+ */
+export function fromPairs(data, pairs) {
+  /** @type {Record<string, string>} */
+  const types = {}
+  const properties = (data && data.properties) || []
+  for (let n = 0; n < properties.length; n++) types[properties[n].name] = properties[n].type
+
+  /** @type {Record<string, any>} */
+  const values = {}
+  for (let n = 0; n < (pairs || []).length; n++) {
+    const { key, value } = pairs[n]
+    if (!key) continue
+    values[key] = typed(value, types[key])
+  }
+  return values
+}
+
+/**
+ * A list as the JSON text of its items; text that is not a list is an empty one.
+ *
+ * @param {string} value
+ */
+function jsonList(value) {
+  try {
+    const items = JSON.parse(value)
+    return Array.isArray(items) ? items : []
+  } catch {
+    return []
+  }
+}
+
+/**
+ * @param {string} value
+ * @param {string} [type]
+ */
+function typed(value, type) {
+  if (type === 'number') return Number(value)
+  if (type === 'boolean') return value === 'true'
+  if (type === 'list') return jsonList(value)
+  if (type === 'color') return isFinite(Number(value)) && value !== '' ? Number(value) : value
+  return value
+}