@px-petals/roku.motion-web 1.0.0 → 1.1.0

package/script/rive/api/text/text.layout.js

@@ -0,0 +1,259 @@
+/**
+ * Lays styled runs out in lines: greedy wrapping at the box width (at spaces,
+ * or anywhere with `wordBreak: 'breakAll'`, and inside a word wider than the
+ * box), alignment, line and paragraph spacing, an ellipsis for fixed text that
+ * overflows. Plain numbers and arrays in and out, so the BrightScript side can
+ * follow it. It does not shape (no ligatures, kerning or bidi): a glyph is a
+ * codepoint with the advance its font gives it plus the run's letter spacing.
+ */
+
+/**
+ * @typedef {object} Run
+ * @property {string} text
+ * @property {import('./text.font.js').FontInfo} font  completed
+ * @property {number} size
+ * @property {number} lineHeight   0 for the font's own
+ * @property {number} letterSpacing
+ */
+
+/**
+ * @typedef {object} LayoutOptions
+ * @property {string} sizing     `autoWidth`, `autoHeight` or `fixed`
+ * @property {string} overflow   `visible`, `hidden`, `clipped` or `ellipsis`
+ * @property {string} align      `left`, `center` or `right`
+ * @property {string} wrap       `wrap` or `noWrap`
+ * @property {string} wordBreak  `normal` or `breakAll`
+ * @property {string} origin     `top` or `baseline`
+ * @property {string} direction  `ltr` or `rtl`
+ * @property {number} maxWidth   0 for none
+ * @property {number} maxHeight  0 for none
+ * @property {number} paragraphSpacing
+ */
+
+/**
+ * @typedef {object} Glyph
+ * @property {number} id
+ * @property {Run}    run
+ * @property {number} cp
+ * @property {number} advance
+ * @property {number} x          pen position on the line
+ * @property {number} y          baseline
+ * @property {number} textIndex  1-based codepoint index
+ */
+
+/**
+ * @typedef {object} Line
+ * @property {number} index
+ * @property {number} x
+ * @property {number} top
+ * @property {number} baseline
+ * @property {number} bottom
+ * @property {number} width
+ * @property {number} firstIndex
+ * @property {number} lastIndex
+ * @property {Glyph[]} glyphs
+ * @property {string} text
+ */
+
+/**
+ * @typedef {object} Layout
+ * @property {Line[]} lines
+ * @property {number} width
+ * @property {number} height
+ * @property {number} length  codepoints
+ */
+
+/**
+ * @param   {string} s
+ * @returns {number[]} its codepoints
+ */
+export function codepoints(s) {
+  /** @type {number[]} */
+  const out = []
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i)
+    const d = i + 1 < s.length ? s.charCodeAt(i + 1) : 0
+    if (c >= 0xd800 && c < 0xdc00 && d >= 0xdc00 && d < 0xe000) {
+      out.push((c - 0xd800) * 1024 + (d - 0xdc00) + 0x10000)
+      i++
+    } else out.push(c)
+  }
+  return out
+}
+
+/**
+ * @param   {number} cp
+ * @returns {string}
+ */
+function char(cp) {
+  if (cp < 0x10000) return String.fromCharCode(cp)
+  const v = cp - 0x10000
+  return String.fromCharCode(0xd800 + (v >> 10), 0xdc00 + (v & 1023))
+}
+
+/**
+ * @param   {Run} run
+ * @param   {number} cp
+ * @returns {number}
+ */
+function advanceOf(run, cp) {
+  const f = run.font
+  return (f.advance ? f.advance(cp) : 0.5) * run.size + run.letterSpacing
+}
+
+/**
+ * @param   {Run} run
+ * @returns {number}
+ */
+function heightOf(run) {
+  const f = /** @type {any} */ (run.font)
+  return run.lineHeight > 0 ? run.lineHeight : (f.descent - f.ascent) * run.size
+}
+
+/**
+ * @param   {Run[]}         runs
+ * @param   {LayoutOptions} o
+ * @returns {Layout}
+ */
+export function layoutText(runs, o) {
+  /** @type {Glyph[]} */
+  const all = []
+  let count = 0
+  for (let r = 0; r < runs.length; r++) {
+    const cps = codepoints(runs[r].text)
+    const f = runs[r].font
+    for (let k = 0; k < cps.length; k++) {
+      count++
+      all.push({ id: f.glyphId ? f.glyphId(cps[k]) : cps[k], run: runs[r], cp: cps[k], advance: cps[k] === 10 ? 0 : advanceOf(runs[r], cps[k]), x: 0, y: 0, textIndex: count })
+    }
+  }
+
+  const limit = o.wrap !== 'noWrap' && o.sizing !== 'autoWidth' && o.maxWidth > 0 ? o.maxWidth : Infinity
+  /** @type {{ glyphs: Glyph[], first: boolean }[]} */
+  const broken = []
+  /** @type {Glyph[]} */
+  let line = []
+  let width = 0
+  let softAt = 0
+  let first = true
+  const flush = () => {
+    broken.push({ glyphs: line, first })
+    first = false
+  }
+  for (let n = 0; n < all.length; n++) {
+    const g = all[n]
+    if (g.cp === 10) {
+      flush()
+      first = true
+      line = []
+      width = 0
+      softAt = 0
+      continue
+    }
+    if (g.cp !== 32 && width + g.advance > limit && line.length > 0) {
+      if (o.wordBreak !== 'breakAll' && softAt > 0) {
+        const rest = line.splice(softAt)
+        flush()
+        line = rest
+        width = 0
+        for (let k = 0; k < rest.length; k++) width += rest[k].advance
+      } else {
+        flush()
+        line = []
+        width = 0
+      }
+      softAt = 0
+    }
+    line.push(g)
+    width += g.advance
+    if (g.cp === 32) softAt = line.length
+  }
+  flush()
+
+  const fallback = runs[0]
+  /** @type {Line[]} */
+  const lines = []
+  let top = 0
+  let widest = 0
+  for (let n = 0; n < broken.length; n++) {
+    const gs = broken[n].glyphs
+    let w = 0
+    let end = gs.length
+    while (end > 0 && gs[end - 1].cp === 32) end--
+    for (let k = 0; k < end; k++) w += gs[k].advance
+    let lineH = 0
+    let asc = 0
+    let desc = 0
+    /** @type {Run[]} */
+    const used = []
+    for (let k = 0; k < gs.length; k++) if (used.indexOf(gs[k].run) < 0) used.push(gs[k].run)
+    if (!used.length && fallback) used.push(fallback)
+    for (let k = 0; k < used.length; k++) {
+      const f = /** @type {any} */ (used[k].font)
+      lineH = Math.max(lineH, heightOf(used[k]))
+      asc = Math.max(asc, -f.ascent * used[k].size)
+      desc = Math.max(desc, f.descent * used[k].size)
+    }
+    if (n > 0 && broken[n].first) top += o.paragraphSpacing
+    const baseline = top + asc + (lineH - asc - desc) / 2
+    const firstIndex = gs.length ? gs[0].textIndex : n > 0 ? lines[n - 1].lastIndex + 2 : 1
+    lines.push({ index: n + 1, x: 0, top, baseline, bottom: top + lineH, width: w, firstIndex, lastIndex: gs.length ? gs[gs.length - 1].textIndex : firstIndex - 1, glyphs: gs, text: '' })
+    if (w > widest) widest = w
+    top += lineH
+  }
+
+  // fixed text that overflows keeps the lines that fit; ellipsis ends the last in an ellipsis character
+  if (o.sizing === 'fixed' && o.maxHeight > 0 && (o.overflow === 'ellipsis' || o.overflow === 'hidden') && lines.length > 1) {
+    let keep = lines.length
+    while (keep > 1 && lines[keep - 1].bottom > o.maxHeight) keep--
+    if (keep < lines.length) {
+      lines.length = keep
+      if (o.overflow === 'ellipsis') ellipsize(lines[keep - 1], limit)
+      top = lines[keep - 1].bottom
+      widest = 0
+      for (let n = 0; n < lines.length; n++) widest = Math.max(widest, lines[n].width)
+    }
+  }
+
+  const boxWidth = o.sizing === 'autoWidth' || !(o.maxWidth > 0) ? widest : o.maxWidth
+  const shift = o.origin === 'baseline' && lines.length ? -lines[0].baseline : 0
+  for (let n = 0; n < lines.length; n++) {
+    const l = lines[n]
+    l.x = o.align === 'right' ? boxWidth - l.width : o.align === 'center' ? (boxWidth - l.width) / 2 : 0
+    l.top += shift
+    l.baseline += shift
+    l.bottom += shift
+    let pen = l.x
+    let s = ''
+    for (let k = 0; k < l.glyphs.length; k++) {
+      const g = l.glyphs[k]
+      g.x = pen
+      g.y = l.baseline
+      pen += g.advance
+      s += char(g.cp)
+    }
+    l.text = s
+  }
+  return { lines, width: boxWidth, height: top + shift, length: count }
+}
+
+/**
+ * @param {Line}   line
+ * @param {number} limit
+ */
+function ellipsize(line, limit) {
+  const gs = line.glyphs
+  if (!gs.length) return
+  const run = gs[gs.length - 1].run
+  const dots = advanceOf(run, 0x2026)
+  let w = 0
+  for (let k = 0; k < gs.length; k++) w += gs[k].advance
+  while (gs.length > 1 && w + dots > limit) {
+    const g = /** @type {Glyph} */ (gs.pop())
+    w -= g.advance
+  }
+  const at = gs[gs.length - 1].textIndex
+  gs.push({ id: 0x2026, run, cp: 0x2026, advance: dots, x: 0, y: 0, textIndex: at + 1 })
+  line.width = w + dots
+  line.lastIndex = at + 1
+}

package/script/rive/context/context.js

@@ -0,0 +1,76 @@
+/**
+ * The `Context` a script's `init` receives and the `DataContext` it can ask
+ * for: where the script reaches its view model (the one bound to its node,
+ * the artboard's root one, global ones by name), asks to be updated again
+ * (`markNeedsUpdate`) and logs.
+ */
+
+import { EMPTY, LuaTable, NativeFunction } from '../../luau/vm/vm.value.js'
+import { decodeUtf8, encodeUtf8 } from '../../luau/luau.convert.js'
+import { defineType, text } from '../api/api.type.js'
+import { viewModelAt } from './context.viewmodel.js'
+
+/** @import { Scope, ViewModelAdapter } from './context.viewmodel.js' */
+
+/**
+ * What a context stands on: the host's view of the world.
+ *
+ * @typedef {object} ContextEnv
+ * @property {(adapter: ViewModelAdapter) => Scope} scopeFor
+ * @property {ViewModelAdapter | null} immediate  the view model bound to the script's node
+ * @property {ViewModelAdapter | null} root       the artboard's own view model
+ * @property {ViewModelAdapter | null} parent     the view model of the enclosing data context
+ * @property {Record<string, ViewModelAdapter>} globals  global view models by name
+ * @property {() => void} markNeedsUpdate
+ * @property {{ image: (n: string) => any, font: (n: string) => any, audio: (n: string) => any }} [assets]  what `image`, `font` and `audio` hand out
+ * @property {(message: string) => void} log
+ */
+
+/**
+ * @param   {ContextEnv} env
+ * @param   {ViewModelAdapter | null | undefined} adapter
+ * @returns {any}  a ViewModel, or nil
+ */
+function viewModelOf(env, adapter) {
+  return adapter ? viewModelAt(env.scopeFor(adapter), '') : undefined
+}
+
+export const DataContext = defineType('DataContext', {
+  methods: {
+    viewModel: (d) => viewModelOf(d.env, d.adapter),
+    parent: (d) => (d.parent ? DataContext.wrap({ env: d.env, adapter: d.parent, parent: null }) : undefined),
+  },
+})
+
+export const Context = defineType('Context', {
+  // Rive's own docs call it `context.log('x')` and others `context:log('x')`, so it is a field holding a function that takes the message last
+  fields: {
+    log: {
+      get: (env) => new NativeFunction('Context.log', function (vm, args) {
+        const last = args[args.length - 1]
+        env.log(typeof last === 'string' ? decodeUtf8(last) : '')
+        return EMPTY
+      }),
+    },
+  },
+  methods: {
+    viewModel: (env) => viewModelOf(env, env.immediate),
+    rootViewModel: (env) => viewModelOf(env, env.root),
+    globalViewModel: (env, args) => viewModelOf(env, env.globals[text(args, 1, 'globalViewModel')]),
+    globalViewModelNames: (env) => {
+      const t = new LuaTable()
+      const names = Object.keys(env.globals).map(encodeUtf8)
+      t.setRange(1, names, 0, names.length)
+      return t
+    },
+    dataContext: (env) => (env.immediate ? DataContext.wrap({ env, adapter: env.immediate, parent: env.parent }) : undefined),
+    markNeedsUpdate: (env) => {
+      env.markNeedsUpdate()
+    },
+    image: (env, args) => (env.assets ? env.assets.image(text(args, 1, 'image')) : undefined),
+    blob: () => undefined,
+    font: (env, args) => (env.assets ? env.assets.font(text(args, 1, 'font')) : undefined),
+    audio: (env, args) => (env.assets ? env.assets.audio(text(args, 1, 'audio')) : undefined),
+    shader: () => undefined,
+  },
+})

package/script/rive/context/context.memory.js

@@ -0,0 +1,196 @@
+/**
+ * A view model held in memory, implementing `ViewModelAdapter`: for tests,
+ * for a player with no view model of its own, and as the reference for what
+ * an adapter does. Nested objects are nested view models; a property
+ * changes (and notifies) only when its value does.
+ *
+ * ```js
+ * const vm = createMemoryViewModel({ score: 0, arrow1: { position: 0 } }, { colors: [ 'tint' ] })
+ * vm.set('arrow1.position', 12)
+ * vm.get('arrow1.position')    // 12
+ * ```
+ */
+
+/** @import { ViewModelAdapter } from './context.viewmodel.js' */
+
+/**
+ * @typedef {ViewModelAdapter & { values: Record<string, any>, kinds: Record<string, string>, lists: Record<string, MemoryViewModel[]>, snapshot: () => Record<string, any> }} MemoryViewModel
+ */
+
+/**
+ * Dotted keys as nested objects, which is what `createMemoryViewModel` takes.
+ *
+ * @param   {Record<string, any>} flat
+ * @returns {Record<string, any>}
+ */
+function nest(flat) {
+  /** @type {Record<string, any>} */
+  const out = {}
+  for (const key in flat) {
+    const parts = key.split('.')
+    let at = out
+    for (let n = 0; n < parts.length - 1; n++) at = at[parts[n]] || (at[parts[n]] = {})
+    at[parts[parts.length - 1]] = flat[key]
+  }
+  return out
+}
+
+/**
+ * @param   {Record<string, any>} [initial]  property values; an object value is a nested view model
+ * @param   {object} [options]
+ * @param   {string[]} [options.colors]    dotted paths of colour properties (ARGB numbers)
+ * @param   {string[]} [options.triggers]  paths of triggers
+ * @param   {string[]} [options.enums]     paths of enum properties (strings)
+ * @param   {string[]} [options.images]    paths of image properties (an asset's name)
+ * @param   {string[]} [options.fonts]     paths of font properties (an asset's name)
+ * @param   {Record<string, Record<string, any>>} [options.instances]  named instances for `instance(name)`, as initial objects
+ * @returns {MemoryViewModel}
+ */
+export function createMemoryViewModel(initial, options) {
+  const o = options || {}
+  /** @type {Record<string, any>} */
+  const values = {}
+  /** @type {Record<string, string>} */
+  const kinds = {}
+  /** @type {Record<string, ((value: any) => void)[]>} */
+  const subscribers = {}
+  /** @type {Record<string, MemoryViewModel[]>} list properties: their items, each a view model of its own */
+  const lists = {}
+
+  /**
+   * @param {string} path
+   * @param {any}    value
+   */
+  const define = (path, value) => {
+    if (Array.isArray(value)) {
+      kinds[path] = 'list'
+      lists[path] = value.map((item) => (item && typeof item.subscribe === 'function' ? item : createMemoryViewModel(item, o)))
+      return
+    }
+    if (value !== null && typeof value === 'object') {
+      kinds[path] = 'viewModel'
+      for (const key in value) define(path === '' ? key : path + '.' + key, value[key])
+      return
+    }
+    values[path] = value
+    kinds[path] = typeof value === 'number' ? 'number' : typeof value === 'boolean' ? 'boolean' : 'string'
+  }
+  if (initial) for (const key in initial) define(key, initial[key])
+  /**
+   * @param {string[] | undefined} paths
+   * @param {string}               kind
+   */
+  const tag = (paths, kind) => {
+    if (paths) for (let n = 0; n < paths.length; n++) kinds[paths[n]] = kind
+  }
+  tag(o.colors, 'color')
+  tag(o.triggers, 'trigger')
+  tag(o.enums, 'enum')
+  tag(o.images, 'image')
+  tag(o.fonts, 'font')
+
+  /**
+   * @param {string} path
+   * @param {any}    value
+   */
+  const notify = (path, value) => {
+    const list = subscribers[path]
+    if (!list) return
+    const copy = list.slice()
+    for (let n = 0; n < copy.length; n++) copy[n](value)
+  }
+
+  /**
+   * @param {string} path
+   */
+  const changed = (path) => notify(path, lists[path].length)
+
+  return {
+    values,
+    kinds,
+    lists,
+    listSize: (path) => (lists[path] ? lists[path].length : 0),
+    listGet: (path, index) => (lists[path] ? lists[path][index] : undefined),
+    listInsert(path, item, index) {
+      const list = lists[path]
+      if (!list) return
+      list.splice(index, 0, /** @type {MemoryViewModel} */ (item))
+      changed(path)
+    },
+    listRemove(path, index) {
+      const list = lists[path]
+      if (!list || index < 0 || index >= list.length) return undefined
+      const out = list.splice(index, 1)[0]
+      changed(path)
+      return out
+    },
+    listClear(path) {
+      const list = lists[path]
+      if (!list || !list.length) return
+      list.length = 0
+      changed(path)
+    },
+    listSwap(path, a, b) {
+      const list = lists[path]
+      if (!list) return
+      const t = list[a]
+      list[a] = list[b]
+      list[b] = t
+      changed(path)
+    },
+    instance(path, name) {
+      if (name !== undefined && o.instances && o.instances[name]) return createMemoryViewModel(o.instances[name], o)
+      const prefix = path === '' ? '' : path + '.'
+      /** @type {Record<string, any>} */
+      const copy = {}
+      /** @type {string[]} */
+      const colors = []
+      /** @type {string[]} */
+      const enums = []
+      /** @type {string[]} */
+      const triggers = []
+      /** @type {string[]} */
+      const images = []
+      /** @type {string[]} */
+      const fonts = []
+      for (const key in kinds) {
+        if (key.indexOf(prefix) !== 0 || key === path) continue
+        const rest = key.slice(prefix.length)
+        const kind = kinds[key]
+        if (kind === 'viewModel') continue
+        copy[rest] = kind === 'list' ? [] : values[key]
+        if (kind === 'color') colors.push(rest)
+        else if (kind === 'enum') enums.push(rest)
+        else if (kind === 'trigger') triggers.push(rest)
+        else if (kind === 'image') images.push(rest)
+        else if (kind === 'font') fonts.push(rest)
+      }
+      return createMemoryViewModel(nest(copy), { colors, enums, triggers, images, fonts, instances: o.instances })
+    },
+    get: (path) => values[path],
+    kind: (path) => kinds[path],
+    set(path, value) {
+      if (kinds[path] === undefined) kinds[path] = typeof value === 'number' ? 'number' : typeof value === 'boolean' ? 'boolean' : 'string'
+      if (values[path] === value) return
+      values[path] = value
+      notify(path, value)
+    },
+    fire(path) {
+      notify(path, true)
+    },
+    subscribe(path, fn) {
+      const list = subscribers[path] || (subscribers[path] = [])
+      list.push(fn)
+      return function () {
+        const at = list.indexOf(fn)
+        if (at >= 0) list.splice(at, 1)
+      }
+    },
+    snapshot() {
+      /** @type {Record<string, any>} */
+      const out = {}
+      for (const key in values) out[key] = values[key]
+      return out
+    },
+  }
+}