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

package/script/rive/context/lists/lists.values.js

@@ -0,0 +1,281 @@
+/**
+ * A `ViewModelAdapter` over a player's values store (the flat, dotted
+ * `values` the Motion player holds), with lists that land as list rows.
+ *
+ * A list property holds its items (`{ viewModel?, instance?, values? }` or an
+ * instance's name) in the store. The adapter gives a script each item as a
+ * view model of its own; a script's `push`, `insert`, `swap`, `remove` and
+ * the writes inside an item become a new array of items written back through
+ * `store.write`, which the player turns into rows (`list/` keeps a row whose
+ * item is unchanged and makes a new one for one that differs).
+ *
+ * ```js
+ * const vm = createValuesViewModel({
+ *   data: bundle.manifest.data,
+ *   values: () => flow.values,
+ *   write: (key, value) => motion.setInputs({ [key]: value }),
+ * })
+ * // after the player's `values` event:
+ * vm.refresh()
+ * ```
+ */
+
+import { inputValue, propertyOf } from '../../../../motion/motion.values.js'
+
+/** @import { ViewModelAdapter } from '../context.viewmodel.js' */
+
+/**
+ * @typedef {object} ValuesStore
+ * @property {any} [data]                                    the bundle's view model (`manifest.data`): property types, enum names
+ * @property {() => Record<string, any>} values              the live values by dotted path
+ * @property {(key: string, value: any) => void} write       sets one value (a list as its array of items); the player reacts and the store then reports it
+ * @property {(path: string, item: Record<string, any>) => Record<string, any>} [defaults]  a list item's values by property name before the item sets its own (`list/list.items.js`'s `itemValues` over the row's data)
+ */
+
+/**
+ * @typedef {object} Item
+ * @property {Record<string, any>} rec  `{ viewModel?, instance?, values }`
+ * @property {string | null} owner      the list property it sits in
+ * @property {string} source            the list property its defaults and kinds come from (kept when it leaves the list)
+ * @property {ViewModelAdapter} adapter
+ */
+
+/**
+ * @typedef {ViewModelAdapter & { refresh: () => void }} ValuesViewModel
+ */
+
+/**
+ * @param   {ValuesStore} store
+ * @returns {ValuesViewModel}
+ */
+export function createValuesViewModel(store) {
+  /** @type {Record<string, { fn: (value: any) => void, last: string }[]>} */
+  const subscribers = {}
+  /** @type {Record<string, Item[]>} items by list property, as last read */
+  const known = {}
+  /** @type {Item[]} every item made, so an adapter the script hands back finds its record */
+  const all = []
+
+  /**
+   * @param   {any} value
+   * @returns {string}
+   */
+  const sig = (value) => (Array.isArray(value) ? JSON.stringify(value) : String(value))
+
+  /**
+   * @param   {string} path
+   * @returns {string | undefined}
+   */
+  const kindOf = (path) => {
+    const p = propertyOf(store.data, path)
+    if (p) return p.type
+    const values = store.values()
+    const v = values[path]
+    if (v !== undefined) return Array.isArray(v) ? 'list' : typeof v === 'number' ? 'number' : typeof v === 'boolean' ? 'boolean' : 'string'
+    const prefix = path + '.'
+    for (const key in values) if (key.indexOf(prefix) === 0) return 'viewModel'
+    return undefined
+  }
+
+  /**
+   * @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].last = sig(store.values()[path])
+      copy[n].fn(value)
+    }
+  }
+
+  /**
+   * Writes the list's items, so the player makes its rows.
+   *
+   * @param {string} path
+   */
+  const commit = (path) => {
+    const items = known[path] || []
+    /** @type {any[]} */
+    const array = []
+    for (let n = 0; n < items.length; n++) array.push(items[n].rec)
+    store.write(path, array)
+    notify(path, array.length)
+  }
+
+  /**
+   * An item as a view model of its own.
+   *
+   * @param   {Record<string, any>} rec
+   * @param   {string | null}       owner
+   * @param   {string}              source
+   * @returns {Item}
+   */
+  const makeItem = (rec, owner, source) => {
+    /** @type {Record<string, ((value: any) => void)[]>} */
+    const subs = {}
+    /** @type {Item} */
+    const item = {
+      rec,
+      owner,
+      source,
+      adapter: {
+        get: (path) => {
+          const own = item.rec.values
+          if (own && path in own) return own[path]
+          const base = store.defaults ? store.defaults(item.source, item.rec) : {}
+          return base[path]
+        },
+        set: (path, value) => {
+          const r = item.rec
+          r.values = r.values || {}
+          if (r.values[path] === value) return
+          r.values[path] = value
+          if (subs[path]) subs[path].slice().forEach((fn) => fn(value))
+          if (item.owner) commit(item.owner)
+        },
+        kind: (path) => {
+          const v = item.adapter.get(path)
+          return typeof v === 'number' ? 'number' : typeof v === 'boolean' ? 'boolean' : typeof v === 'string' ? 'string' : undefined
+        },
+        subscribe: (path, fn) => {
+          const list = subs[path] || (subs[path] = [])
+          list.push(fn)
+          return () => {
+            const at = list.indexOf(fn)
+            if (at >= 0) list.splice(at, 1)
+          }
+        },
+        instance: (_path, name) => makeItem({ viewModel: item.rec.viewModel, instance: name === undefined ? item.rec.instance : name }, null, item.source).adapter,
+      },
+    }
+    all.push(item)
+    return item
+  }
+
+  /**
+   * The items of a list, in the store's order; an item the script already holds
+   * is the same object again.
+   *
+   * @param   {string} path
+   * @returns {Item[]}
+   */
+  const itemsOf = (path) => {
+    const raw = store.values()[path]
+    const array = Array.isArray(raw) ? raw : []
+    const before = (known[path] || []).slice()
+    /** @type {Item[]} */
+    const out = []
+    for (let n = 0; n < array.length; n++) {
+      const el = array[n]
+      const rec = typeof el === 'string' ? { instance: el } : el && typeof el === 'object' ? el : {}
+      let at = -1
+      for (let k = 0; k < before.length && at < 0; k++) if (before[k].rec === rec) at = k
+      if (at < 0) {
+        const s = sig(rec)
+        for (let k = 0; k < before.length && at < 0; k++) if (sig(before[k].rec) === s) at = k
+      }
+      if (at >= 0) {
+        const item = before.splice(at, 1)[0]
+        item.rec = rec
+        out.push(item)
+      } else out.push(makeItem(rec, path, path))
+    }
+    known[path] = out
+    return out
+  }
+
+  /**
+   * @param   {ViewModelAdapter} a
+   * @returns {Item | undefined}
+   */
+  const findByAdapter = (a) => {
+    for (let n = 0; n < all.length; n++) if (all[n].adapter === a) return all[n]
+    return undefined
+  }
+
+  /** @type {ValuesViewModel} */
+  const adapter = {
+    get(path) {
+      const v = store.values()[path]
+      const p = propertyOf(store.data, path)
+      return p && p.values && typeof v === 'number' ? p.values[v] : v
+    },
+    set(path, value) {
+      const next = inputValue(store.data, path, value)
+      if (store.values()[path] === next) return
+      store.write(path, next)
+      notify(path, value)
+    },
+    kind: kindOf,
+    subscribe(path, fn) {
+      const list = subscribers[path] || (subscribers[path] = [])
+      const entry = { fn, last: sig(store.values()[path]) }
+      list.push(entry)
+      return () => {
+        const at = list.indexOf(entry)
+        if (at >= 0) list.splice(at, 1)
+      }
+    },
+    fire(path) {
+      notify(path, true)
+    },
+    listSize: (path) => itemsOf(path).length,
+    listGet: (path, index) => {
+      const items = itemsOf(path)
+      return items[index] ? items[index].adapter : undefined
+    },
+    listInsert(path, item, index) {
+      const items = itemsOf(path)
+      const added = findByAdapter(item)
+      if (!added) return
+      added.owner = path
+      items.splice(index, 0, added)
+      commit(path)
+    },
+    listRemove(path, index) {
+      const items = itemsOf(path)
+      if (index < 0 || index >= items.length) return undefined
+      const out = items.splice(index, 1)[0]
+      out.owner = null
+      commit(path)
+      return out.adapter
+    },
+    listClear(path) {
+      const items = itemsOf(path)
+      if (!items.length) return
+      for (let n = 0; n < items.length; n++) items[n].owner = null
+      items.length = 0
+      commit(path)
+    },
+    listSwap(path, a, b) {
+      const items = itemsOf(path)
+      const t = items[a]
+      items[a] = items[b]
+      items[b] = t
+      commit(path)
+    },
+    instance(path, name) {
+      if (kindOf(path) !== 'list') return undefined
+      const first = itemsOf(path)[0]
+      return makeItem({ viewModel: first ? first.rec.viewModel : undefined, instance: name }, null, path).adapter
+    },
+    /** Tells subscribers about what the player changed since: call it after the player's `values` event */
+    refresh() {
+      for (const path in subscribers) {
+        const now = sig(store.values()[path])
+        const list = subscribers[path].slice()
+        for (let n = 0; n < list.length; n++) {
+          if (list[n].last === now) continue
+          list[n].last = now
+          const v = store.values()[path]
+          list[n].fn(Array.isArray(v) ? v.length : adapter.get(path))
+        }
+      }
+    },
+  }
+
+  return adapter
+}

package/script/rive/host/host.globals.js

@@ -0,0 +1,44 @@
+/**
+ * The globals a Rive script sees beyond Luau's standard library: `Vector`,
+ * `Color`, `Mat2D`, `Path`, `Paint`, `Gradient`, the values of the converter,
+ * listener action and layout protocols (`DataValue`, `PointerEvent`, `Vec2D`),
+ * and `late` (the placeholder an input's default is written with, which holds
+ * nil until the player sets it).
+ */
+
+import { EMPTY, NativeFunction } from '../../luau/vm/vm.value.js'
+import { installColor } from '../api/math/math.color.js'
+import { installMat2D } from '../api/math/math.mat2d.js'
+import { installVector } from '../api/math/math.vector.js'
+import { installPaint } from '../api/draw/draw.paint.js'
+import { installPath } from '../api/draw/draw.path.js'
+import { installAudio } from '../api/media/media.audio.js'
+import { installImage } from '../api/media/media.image.js'
+import { installMesh } from '../api/media/media.mesh.js'
+import { installPointer } from '../api/pointer/pointer.event.js'
+import { installFont } from '../api/text/text.font.js'
+import { installText } from '../api/text/text.js'
+import { installData } from '../api/data/data.value.js'
+
+/**
+ * @param {import('../../luau/luau.js').Luau} luau
+ * @param {{ audio?: import('../api/media/media.audio.js').AudioEvent[], fallback?: () => any }} [host]  where recorded audio goes; the font text uses when a run names none
+ */
+export function installGlobals(luau, host) {
+  const vm = luau.vm
+  installVector(vm)
+  installColor(vm)
+  installMat2D(vm)
+  installPath(vm)
+  installPaint(vm)
+  installImage(vm)
+  installMesh(vm)
+  installAudio(vm, (host && host.audio) || [])
+  installFont(vm)
+  installText(vm, (host && host.fallback) || (() => ({ name: '', ascent: -0.8, descent: 0.2, capHeight: -0.7, xHeight: -0.5, weight: 400, isItalic: false })))
+  installPointer(vm)
+  installData(vm)
+  vm.globals.set('late', new NativeFunction('late', function () {
+    return EMPTY
+  }))
+}