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

package/bands/bands.js

@@ -0,0 +1,390 @@
+/**
+ * Layout bands that blend. Where the converter says a band's layout can be
+ * interpolated up to the next band (`lerp`: nothing wraps, clamps or appears
+ * between their widths), every laid-out box's position and size is a straight
+ * line in the width, so a canvas between the two bands draws the mix of
+ * their variants, weighted `t = (w - w0) / (w1 - w0)`.
+ *
+ * Rive's `layout` fit sizes the artboard to the whole canvas, so a layout
+ * can depend on the height too, and the converter then writes a grid: a row
+ * of the same bands for each height band. Inside a cell of the grid where
+ * nothing reflows (`cell`) every box is affine in both the width and the
+ * height, so the canvas draws the bilinear mix of the cell's four corners,
+ * weighted (1 - u)(1 - v), u(1 - v), (1 - u)v and uv, `u` being how far the
+ * width is across the cell and `v` the height. `cellOf` finds the cell.
+ *
+ * `linkBands` does that by giving each corner's variant of an animation, per
+ * property it shares with its neighbours', an evaluator that blends their
+ * values by two live weights. The animation is then drawn as always (alone,
+ * or as the pose mixer's carrier or source), and at `u = v = 0` is exactly
+ * the corner's own. Properties tagged `rid` match between bands the way they
+ * match between the animations of one artboard.
+ */
+
+import { evaluator } from '../lottie/lottie.props.js'
+import { mixValues } from '../mixer/mixer.mix.js'
+
+/** @import { Evaluator } from '../lottie/lottie.props.js' */
+
+/** No slots: a property's keyframes, with the drawn animation's own slots going over the result */
+const NO_SLOTS = {}
+
+/**
+ * @typedef {object} Blend
+ * @property {any}        band the band the canvas has room for
+ * @property {any | null} next the band after it, when the canvas is inside a segment that blends
+ * @property {number}     t    next's weight, 0 to 1; 0 without a next
+ */
+
+/**
+ * Where a canvas width falls among the bands: the widest band it has room
+ * for (the narrowest when it has room for none), and how far it is toward
+ * the next, when that segment can be interpolated.
+ *
+ * @param   {any[] | undefined} bands a bundle's `bands`, narrowest first
+ * @param   {number}            width the canvas's width in CSS pixels
+ * @returns {Blend | null}            null without bands
+ */
+export function blendOf(bands, width) {
+  if (!bands || !bands.length) return null
+  let at = 0
+  for (let n = 1; n < bands.length; n++) if (bands[n].width <= width) at = n
+
+  const band = bands[at]
+  const next = bands[at + 1]
+  if (!band.lerp || !next || width <= band.width) return { band, next: null, t: 0 }
+  return { band, next, t: Math.min(1, (width - band.width) / (next.width - band.width)) }
+}
+
+/**
+ * A band of the layout grid, at one width and height.
+ *
+ * @typedef {object} Corner
+ * @property {number}                             width
+ * @property {number}                             height
+ * @property {Record<string, string> | undefined} animations the animation that stands for each of the bundle's own here; none at the artboard's own size
+ * @property {boolean}                            lerp       the segment to the next, wider corner in its row blends
+ * @property {boolean}                            rise       the segment to the next, taller corner in its column blends
+ * @property {boolean}                            cell       the whole rectangle up to the diagonal corner blends bilinearly
+ */
+
+/**
+ * The layout grid of a bundle: its bands as one row, or the rows of its
+ * `grid` when the layout depends on the height.
+ *
+ * @typedef {object} Grid
+ * @property {Corner[][]}              rows  shortest first, each row narrowest first; every row holds the same widths
+ * @property {[number, number] | null} range the heights the layout was solved over, when the converter says
+ */
+
+/**
+ * @param   {any}         manifest
+ * @returns {Grid | null}          null without bands
+ */
+export function gridOf(manifest) {
+  const bands = manifest.bands
+  if (!bands || !bands.length) return null
+
+  const range = manifest.heightRange && manifest.heightRange.length === 2 ? /** @type {[number, number]} */ ([ manifest.heightRange[0], manifest.heightRange[1] ]) : null
+  const listed = manifest.grid && manifest.grid.rows
+  if (listed && listed.length) {
+    const rows = []
+    for (let j = 0; j < listed.length; j++) {
+      const row = []
+      for (let i = 0; i < listed[j].bands.length; i++) row.push(cornerOf(listed[j].bands[i], listed[j].height))
+      rows.push(row)
+    }
+    return { rows, range }
+  }
+
+  const row = []
+  for (let i = 0; i < bands.length; i++) row.push(cornerOf(bands[i], bands[i].height || 0))
+  return { rows: [ row ], range }
+}
+
+/**
+ * @param   {any}    band
+ * @param   {number} height
+ * @returns {Corner}
+ */
+function cornerOf(band, height) {
+  return { width: band.width, height, animations: band.animations, lerp: !!band.lerp, rise: !!band.rise, cell: !!band.cell }
+}
+
+/**
+ * Where a canvas falls in the layout grid.
+ *
+ * @typedef {object} Cell
+ * @property {Corner}      corner the corner the canvas has room for: the widest, tallest band that fits, else the narrowest, shortest
+ * @property {Corner|null} right  the next, wider corner, when the canvas is inside a segment that blends in the width
+ * @property {Corner|null} up     the next, taller corner, when it is inside one that blends in the height
+ * @property {Corner|null} diag   the corner across, when it is inside a cell that blends in both
+ * @property {number}      u      how far across to `right`, 0 to 1; 0 without one
+ * @property {number}      v      how far up to `up`, 0 to 1; 0 without one
+ * @property {number}      width  the artboard's width: the canvas's where the layout is exact for it, else 0 for the picture's own
+ * @property {number}      height the artboard's height, likewise
+ */
+
+/**
+ * The cell of the grid for a canvas size: the corner the canvas has room for,
+ * the corners it blends toward, and the weights, where the converter says the
+ * segments or cell can be interpolated. A canvas past the grid is the edge
+ * corner, scaled by the fit. Where the layout does not depend on the height
+ * (one row) and the converter says what range it checked, the artboard is the
+ * canvas's height within that range, as Rive sizes it.
+ *
+ * @param   {Grid}   grid
+ * @param   {number} width  the canvas's width in CSS pixels
+ * @param   {number} height its height
+ * @returns {Cell}
+ */
+export function cellOf(grid, width, height) {
+  const rows = grid.rows
+  let j = 0
+  for (let n = 1; n < rows.length; n++) if (rows[n][0].height <= height) j = n
+  const row = rows[j]
+  let i = 0
+  for (let n = 1; n < row.length; n++) if (row[n].width <= width) i = n
+
+  const corner = row[i]
+  const right = row[i + 1] || null
+  const up = rows[j + 1] ? rows[j + 1][i] : null
+  const isU = !!right && corner.lerp && width > corner.width
+  const isV = !!up && corner.rise && height > corner.height
+
+  // both ways only inside a cell the converter checked; a cell that reflows plays its corner
+  const isBoth = isU && isV
+  const canU = isU && (!isBoth || corner.cell)
+  const canV = isV && (!isBoth || corner.cell)
+  const u = canU ? Math.min(1, (width - corner.width) / (/** @type {Corner} */ (right).width - corner.width)) : 0
+  const v = canV ? Math.min(1, (height - corner.height) / (/** @type {Corner} */ (up).height - corner.height)) : 0
+
+  let artboardHeight = 0
+  if (canV) artboardHeight = height
+  else if (rows.length === 1 && grid.range) artboardHeight = Math.max(grid.range[0], Math.min(grid.range[1], height))
+  return {
+    corner,
+    right: canU ? right : null,
+    up: canV ? up : null,
+    diag: canU && canV ? rows[j + 1][i + 1] : null,
+    u,
+    v,
+    width: canU ? width : 0,
+    height: artboardHeight,
+  }
+}
+
+/**
+ * Whether any band of a bundle blends into a neighbour.
+ *
+ * @param   {any}     manifest
+ * @returns {boolean}
+ */
+export function hasBlend(manifest) {
+  const bands = manifest.bands || []
+  for (let n = 0; n < bands.length - 1; n++) if (bands[n].lerp) return true
+  const rows = (manifest.grid && manifest.grid.rows) || []
+  for (let j = 0; j < rows.length; j++) {
+    for (let i = 0; i < rows[j].bands.length; i++) if (rows[j].bands[i].lerp || rows[j].bands[i].rise) return true
+  }
+  return false
+}
+
+/**
+ * Links every blending corner's variants to its neighbours'. Call it with all
+ * the bundle's parsed Lotties loaded and none yet drawn or mixed.
+ *
+ * @param {any}                       manifest
+ * @param {Record<string, any>}       lotties  parsed Lottie JSON by animation id, changed in place
+ * @param {{ t: number, v?: number }} live     the weights toward the next, wider corner (`t`) and the next, taller one (`v`); set them before a draw
+ */
+export function linkBands(manifest, lotties, live) {
+  const grid = gridOf(manifest)
+  if (!grid) return
+  const ids = baseIds(manifest)
+
+  /** @param {Corner | undefined} from @param {boolean} on @returns {Corner | null} */
+  const neighbour = (from, on) => (on && from ? from : null)
+
+  // every target's values are read before any is linked, since a target links onward itself
+  /** @type {Record<string, Record<string, { property: any, at: Evaluator }>>} */
+  const targets = {}
+  /** @type {{ corner: Corner, right: Corner | null, up: Corner | null, diag: Corner | null }[]} */
+  const links = []
+  const rows = grid.rows
+  for (let j = 0; j < rows.length; j++) {
+    for (let i = 0; i < rows[j].length; i++) {
+      const corner = rows[j][i]
+      const right = neighbour(rows[j][i + 1], corner.lerp || corner.cell)
+      const up = neighbour(rows[j + 1] && rows[j + 1][i], corner.rise || corner.cell)
+      const diag = neighbour(rows[j + 1] && rows[j + 1][i + 1], corner.cell)
+      if (!right && !up) continue
+      links.push({ corner, right, up, diag })
+      for (let k = 0; k < ids.length; k++) {
+        const others = [ right, up, diag ]
+        for (let m = 0; m < others.length; m++) {
+          const other = others[m]
+          if (!other) continue
+          const id = variantId(other, ids[k])
+          if (lotties[id] && !targets[id]) targets[id] = collect(lotties[id])
+        }
+      }
+    }
+  }
+
+  for (let n = 0; n < links.length; n++) {
+    const entry = links[n]
+    for (let k = 0; k < ids.length; k++) {
+      const from = lotties[variantId(entry.corner, ids[k])]
+      if (!from) continue
+      const at = (/** @type {Corner | null} */ other) => (other ? targets[variantId(other, ids[k])] : undefined)
+      link(from, { right: at(entry.right), up: at(entry.up), diag: at(entry.diag) }, live)
+    }
+  }
+}
+
+/**
+ * @typedef {Record<string, { property: any, at: Evaluator }>} Targets
+ */
+
+/**
+ * @param {any}                                               lottie a corner's variant
+ * @param {{ right?: Targets, up?: Targets, diag?: Targets }} to     the neighbours', by `rid`
+ * @param {{ t: number, v?: number }}                         live
+ */
+function link(lottie, to, live) {
+  visit(lottie, (property) => {
+    const right = differing(property, to.right)
+    const up = differing(property, to.up)
+    const diag = differing(property, to.diag)
+    if (!right && !up && !diag) return
+
+    const own = evaluator(property, NO_SLOTS)
+    property.mx = (/** @type {number} */ frame) => {
+      const value = own(frame)
+      const u = live.t
+      const v = live.v || 0
+      if (u > 0 && v > 0) {
+        // bilinear: along the bottom edge and the top one, then between them
+        const across = right ? mixValues(value, right(frame), u) : value
+        const lift = up ? up(frame) : value
+        const top = diag ? mixValues(lift, diag(frame), u) : lift
+        return mixValues(across, top, v)
+      }
+      if (u > 0) return right ? mixValues(value, right(frame), u) : value
+      if (v > 0) return up ? mixValues(value, up(frame), v) : value
+      return value
+    }
+  })
+}
+
+/**
+ * A neighbour's evaluator for a property, when its values differ from the property's.
+ *
+ * @param   {any}                 property
+ * @param   {Targets | undefined} targets
+ * @returns {Evaluator | null}
+ */
+function differing(property, targets) {
+  const other = targets && targets[property.rid]
+  return other && !isSame(property, other.property) ? other.at : null
+}
+
+/**
+ * Whether two properties hold the same values, which need no blending.
+ *
+ * @param   {any}     a
+ * @param   {any}     b
+ * @returns {boolean}
+ */
+function isSame(a, b) {
+  return a.a === b.a && JSON.stringify(a.k) === JSON.stringify(b.k)
+}
+
+/**
+ * Every tagged property of a Lottie by its `rid`; the first of a repeated one wins.
+ *
+ * @param   {any}                                              lottie
+ * @returns {Record<string, { property: any, at: Evaluator }>}
+ */
+function collect(lottie) {
+  /** @type {Record<string, { property: any, at: Evaluator }>} */
+  const found = {}
+  visit(lottie, (property) => {
+    if (!found[property.rid]) found[property.rid] = { property, at: evaluator(property, NO_SLOTS) }
+  })
+  return found
+}
+
+/**
+ * Calls back for every tagged property under a node, in assets as in layers.
+ *
+ * @param {any}                     node
+ * @param {(property: any) => void} found
+ */
+function visit(node, found) {
+  if (node === null || typeof node !== 'object') return
+  if (Array.isArray(node)) {
+    for (let n = 0; n < node.length; n++) visit(node[n], found)
+    return
+  }
+  if (typeof node.rid === 'string' && 'k' in node) found(node)
+  for (const key in node) {
+    if (key === 'k' || key === 'rid') continue
+    visit(node[key], found)
+  }
+}
+
+/**
+ * Every band the manifest lists, those of the authored height and the grid's.
+ *
+ * @param   {any}   manifest
+ * @returns {any[]}
+ */
+function everyBand(manifest) {
+  const found = (manifest.bands || []).slice()
+  const rows = (manifest.grid && manifest.grid.rows) || []
+  for (let j = 0; j < rows.length; j++) for (let i = 0; i < rows[j].bands.length; i++) found.push(rows[j].bands[i])
+  return found
+}
+
+/**
+ * The animations that are a layout band's variant of another, not an animation of the bundle's own.
+ *
+ * @param   {any}                     manifest
+ * @returns {Record<string, boolean>}
+ */
+export function variantIds(manifest) {
+  /** @type {Record<string, boolean>} */
+  const found = {}
+  const bands = everyBand(manifest)
+  for (let n = 0; n < bands.length; n++) {
+    for (const id in bands[n].animations || {}) found[bands[n].animations[id]] = true
+  }
+  return found
+}
+
+/**
+ * The bundle's own animations: those no band lists as its variant.
+ *
+ * @param   {any}      manifest
+ * @returns {string[]}
+ */
+function baseIds(manifest) {
+  const isVariant = variantIds(manifest)
+  const ids = []
+  for (const id in manifest.animations) if (!isVariant[id]) ids.push(id)
+  return ids
+}
+
+/**
+ * An animation's variant in a band: the animation itself in the band at the
+ * artboard's own size.
+ *
+ * @param   {{ animations?: Record<string, string> }} band
+ * @param   {string}                                  id
+ * @returns {string}
+ */
+function variantId(band, id) {
+  return (band.animations && band.animations[id]) || id
+}

package/bundle/bundle.fonts.js

@@ -0,0 +1,55 @@
+/**
+ * The fonts a bundle's text overlays use, registered under a family name of
+ * their own so they never shadow the page's. FontFace where the browser has
+ * it, which says when the font is ready; an @font-face rule elsewhere, which
+ * the canvas picks up once the browser has fetched it.
+ */
+
+import { fileUrl } from './bundle.js'
+
+/** @import { Bundle } from './bundle.js' */
+
+/** Families registered so far, by URL, so a bundle loaded twice registers once */
+/** @type {Record<string, string>} */
+const registered = {}
+
+/**
+ * @param   {Bundle}                          bundle
+ * @returns {Promise<Record<string, string>>}        font name → the family to draw with
+ */
+export function loadFonts(bundle) {
+  /** @type {Record<string, string>} */
+  const families = {}
+  const pending = []
+  const fonts = bundle.manifest.fonts || {}
+  for (const name in fonts) {
+    const url = fileUrl(bundle, fonts[name])
+    const family = registered[url] || 'motion-' + Object.keys(registered).length + '-' + name.replace(/[^\w-]+/g, '_')
+    families[name] = family
+    if (registered[url]) continue
+
+    registered[url] = family
+    pending.push(register(family, url))
+  }
+  return Promise.all(pending).then(() => families)
+}
+
+/**
+ * @param   {string}        family
+ * @param   {string}        url
+ * @returns {Promise<void>}
+ */
+function register(family, url) {
+  const FontFaceClass = /** @type {any} */ (window).FontFace
+  const fontSet = /** @type {any} */ (document).fonts
+  if (FontFaceClass && fontSet) {
+    const face = new FontFaceClass(family, 'url("' + url + '")')
+    // a font that fails to load leaves its text in the fallback font
+    return face.load().then(() => fontSet.add(face), () => undefined)
+  }
+
+  const style = document.createElement('style')
+  style.appendChild(document.createTextNode('@font-face { font-family: "' + family + '"; src: url("' + url + '"); }'))
+  document.head.appendChild(style)
+  return Promise.resolve()
+}

package/bundle/bundle.js

@@ -0,0 +1,75 @@
+/**
+ * A bundle over HTTP: motion.json, then the files it names, each resolved
+ * against motion.json's own folder. XMLHttpRequest rather than fetch, which
+ * some of the WebViews this runs in predate.
+ */
+
+/**
+ * @typedef {object} Bundle
+ * @property {any}    manifest motion.json
+ * @property {string} base     motion.json's folder, ending in "/"
+ */
+
+/**
+ * @param   {string}          url motion.json's URL
+ * @returns {Promise<Bundle>}
+ */
+export function loadBundle(url) {
+  return loadJson(url).then((manifest) => {
+    const isReadable = manifest && typeof manifest.motion === 'number' && manifest.animations
+    if (!isReadable) throw new Error(url + ' is not a Motion bundle')
+    // a file stretched to hold a nested artboard's animation (for a player that cannot run the machine) loops and ends where its own keys do
+    for (const id in manifest.animations) {
+      const entry = manifest.animations[id]
+      if (entry && entry.own > 0 && entry.own < entry.frames) entry.frames = entry.own
+    }
+    return { manifest, base: url.replace(/[^/]*$/, '') }
+  })
+}
+
+/**
+ * @param   {Bundle} bundle
+ * @param   {string} file   relative to motion.json
+ * @returns {string}
+ */
+export function fileUrl(bundle, file) {
+  return bundle.base + file.split('/').map(encodeURIComponent).join('/')
+}
+
+/**
+ * @param   {string}       url
+ * @returns {Promise<any>}
+ */
+export function loadJson(url) {
+  return new Promise((resolve, reject) => {
+    const request = new XMLHttpRequest()
+    request.open('GET', url, true)
+    request.onload = () => {
+      const isOk = request.status >= 200 && request.status < 300
+      if (!isOk) {
+        reject(new Error('cannot load ' + url + ' (HTTP ' + request.status + ')'))
+        return
+      }
+      try {
+        resolve(JSON.parse(request.responseText))
+      } catch (error) {
+        reject(new Error(url + ' is not JSON: ' + /** @type {Error} */ (error).message))
+      }
+    }
+    request.onerror = () => reject(new Error('cannot load ' + url))
+    request.send()
+  })
+}
+
+/**
+ * @param   {string}                    url
+ * @returns {Promise<HTMLImageElement>}
+ */
+export function loadImage(url) {
+  return new Promise((resolve, reject) => {
+    const image = new Image()
+    image.onload = () => resolve(image)
+    image.onerror = () => reject(new Error('cannot load ' + url))
+    image.src = url
+  })
+}

package/focus/focus.direction.js

@@ -0,0 +1,46 @@
+/**
+ * Directional focus, as Rive moves it for the arrow keys and the
+ * up/down/left/right focus actions: from the focused node's centre to the
+ * stop in that direction with the lowest score, where a stop is in the
+ * direction when its centre is further that way, and
+ *
+ * score = distance along the direction + weight * distance across it
+ *
+ * The weight is 2 for up and down and 36 for left and right, fitted to what
+ * `@rive-app/canvas` chooses (the parity scorecard's `focus-*` fixtures and the
+ * tests here hold it); a tie goes to the stop earlier in Tab order.
+ */
+
+/** How much a unit across the direction costs, against a unit along it */
+const ACROSS = { up: 2, down: 2, left: 36, right: 36 }
+
+/**
+ * @param   {string}                                             direction up, down, left or right
+ * @param   {{ x: number, y: number }}                           from      the focused node's centre
+ * @param   {string[]}                                           stops     the candidates, in Tab order
+ * @param   {(rid: string) => ({ x: number, y: number } | null)} centerOf  null for a node with no geometry drawn
+ * @returns {string | null}                                                the stop to focus, or null when none lies that way
+ */
+export function pickInDirection(direction, from, stops, centerOf) {
+  const weight = ACROSS[/** @type {keyof typeof ACROSS} */ (direction)]
+  if (weight === undefined) return null
+  const isVertical = direction === 'up' || direction === 'down'
+  const sign = direction === 'down' || direction === 'right' ? 1 : -1
+
+  /** @type {string | null} */
+  let best = null
+  let bestScore = Infinity
+  for (let n = 0; n < stops.length; n++) {
+    const center = centerOf(stops[n])
+    if (!center) continue
+    const along = (isVertical ? center.y - from.y : center.x - from.x) * sign
+    const across = Math.abs(isVertical ? center.x - from.x : center.y - from.y)
+    if (along <= 0) continue
+    const score = along + weight * across
+    if (score < bestScore) {
+      bestScore = score
+      best = stops[n]
+    }
+  }
+  return best
+}