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

package/script/rive/context/context.viewmodel.js

@@ -0,0 +1,302 @@
+/**
+ * The view model a script reaches through its context: `ViewModel` (named
+ * properties, nested view models) and the typed properties it hands out
+ * (`Property` for numbers, strings, booleans, colours and enums;
+ * `PropertyTrigger`; `PropertyViewModel`). All of it is a thin skin over a
+ * `ViewModelAdapter` the player implements, so the host never knows which
+ * player it runs in.
+ *
+ * Paths are dotted: a script that asks a view model at `a.b` for `c` reads
+ * the adapter at `a.b.c`.
+ */
+
+import { LuaClosure, NativeFunction, fail } from '../../luau/vm/vm.value.js'
+import { decodeUtf8, encodeUtf8 } from '../../luau/luau.convert.js'
+import { Wrapped, defineType, text } from '../api/api.type.js'
+import { listType } from './lists/lists.js'
+
+/**
+ * What a player gives the host to read and write its view model.
+ *
+ * @typedef {object} ViewModelAdapter
+ * @property {(path: string) => any} get  the value at a dotted path: a number, string, boolean (a colour is an ARGB number, an enum its value name), or undefined when there is none
+ * @property {(path: string, value: any) => void} set
+ * @property {(path: string, fn: (value: any) => void) => (() => void)} subscribe  calls `fn` when the value changes (or a trigger fires); returns how to stop
+ * @property {(path: string) => (string | undefined)} [kind]  `number`, `string`, `boolean`, `color`, `enum`, `trigger`, `viewModel`, `list`, or undefined for no such property; without it the kind is read from the value's type
+ * @property {(path: string) => void} [fire]  fires a trigger; without it a trigger is set to `true`
+ * @property {(path: string) => number} [listSize]  the items of a list property
+ * @property {(path: string, index: number) => (ViewModelAdapter | undefined)} [listGet]  the view model of item `index` (0-based), as an adapter of its own whose paths start at its root
+ * @property {(path: string, item: ViewModelAdapter, index: number) => void} [listInsert]  puts a view model into the list at `index` (0-based); the list notifies its subscribers
+ * @property {(path: string, index: number) => (ViewModelAdapter | undefined)} [listRemove]  takes item `index` out and returns it
+ * @property {(path: string, a: number, b: number) => void} [listSwap]  swaps two items
+ * @property {(path: string) => void} [listClear]  empties the list in one change; without it `clear` removes the items one by one
+ * @property {(path: string, name?: string) => (ViewModelAdapter | undefined)} [instance]  a new instance of the view model at `path` ('' for the root), from the named instance of the file when `name` is given; not in any list yet
+ *
+ * The three asset kinds `image`, `font` and `blob` hold an asset's name (`get` gives it, `set` takes it).
+ */
+
+/**
+ * The state every view model object of one script host shares.
+ *
+ * @typedef {object} Scope
+ * @property {ViewModelAdapter} adapter
+ * @property {Record<string, PropertyData>} props  property objects by `kind:path`, so a property is the same object each time it is asked for
+ * @property {(fn: any, args: any[]) => void} call  calls a Lua function, keeping the host's error handling
+ * @property {() => void} wake  tells the host something changed
+ * @property {(adapter: ViewModelAdapter) => Scope} [scopeFor]  the scope of another adapter (a list's item); without it items get scopes of their own
+ * @property {(kind: string, name: string) => any} [asset]  an asset's Lua value (`image`, `font`, `blob`) by name
+ */
+
+/**
+ * @typedef {object} PropertyData
+ * @property {Scope}    scope
+ * @property {string}   path
+ * @property {string}   kind
+ * @property {{ cb: any, anchor: any }[]} listeners
+ * @property {(() => void) | null} unsubscribe
+ * @property {any}      wrapper
+ */
+
+/**
+ * @param   {Scope}  scope
+ * @param   {string} path
+ * @returns {string | undefined}
+ */
+function kindOf(scope, path) {
+  const a = scope.adapter
+  if (a.kind) return a.kind(path)
+  const v = a.get(path)
+  return typeof v === 'number' ? 'number' : typeof v === 'string' ? 'string' : typeof v === 'boolean' ? 'boolean' : Array.isArray(v) ? 'list' : undefined
+}
+
+/**
+ * @param   {string} kind
+ * @returns {boolean} whether the property holds an asset's name
+ */
+function isAsset(kind) {
+  return kind === 'image' || kind === 'font' || kind === 'blob'
+}
+
+/**
+ * A host value as the Lua value a property holds.
+ *
+ * @param   {any} v
+ * @returns {any}
+ */
+function toLuaValue(v) {
+  return typeof v === 'string' ? encodeUtf8(v) : v === null ? undefined : v
+}
+
+/**
+ * @param   {string} kind
+ * @param   {any}    v     a Lua value
+ * @returns {any}    the host value to store
+ */
+function fromLuaValue(kind, v) {
+  if (isAsset(kind)) {
+    const name = v instanceof Wrapped && v.host ? v.host.name : undefined
+    if (typeof name !== 'string') throw fail('a ' + kind + ' property takes a ' + kind)
+    return name
+  }
+  if (kind === 'number' || kind === 'color') {
+    if (typeof v !== 'number') throw fail('a ' + kind + ' property takes a number')
+    return v
+  }
+  if (kind === 'boolean') {
+    if (typeof v !== 'boolean') throw fail('a boolean property takes a boolean')
+    return v
+  }
+  if (kind === 'string' || kind === 'enum') {
+    if (typeof v !== 'string') throw fail('a ' + kind + ' property takes a string')
+    return decodeUtf8(v)
+  }
+  throw fail('cannot set a ' + kind + ' property')
+}
+
+// Properties
+// ■■■■■■■■■■
+
+/**
+ * Adds a listener or takes one away; both take `(callback)` or `(anchor, callback)`.
+ *
+ * @param {PropertyData} p
+ * @param {any[]}        args  with the property first
+ * @param {boolean}      add
+ */
+function listen(p, args, add) {
+  const withAnchor = args[2] !== undefined
+  const cb = withAnchor ? args[2] : args[1]
+  const anchor = withAnchor ? args[1] : undefined
+  if (!(cb instanceof NativeFunction) && !(cb instanceof LuaClosure)) throw fail('addListener needs a function')
+  if (add) {
+    p.listeners.push({ cb, anchor })
+    if (!p.unsubscribe) {
+      p.unsubscribe = p.scope.adapter.subscribe(p.path, function () {
+        const snapshot = p.listeners.slice()
+        for (let n = 0; n < snapshot.length; n++) p.scope.call(snapshot[n].cb, [ snapshot[n].anchor !== undefined ? snapshot[n].anchor : p.wrapper ])
+        p.scope.wake()
+      })
+    }
+    return
+  }
+  for (let n = 0; n < p.listeners.length; n++) {
+    if (p.listeners[n].cb === cb) {
+      p.listeners.splice(n, 1)
+      break
+    }
+  }
+  if (p.listeners.length === 0 && p.unsubscribe) {
+    p.unsubscribe()
+    p.unsubscribe = null
+  }
+}
+
+/**
+ * @param   {PropertyData} p
+ * @returns {any}  the asset the property names, or nil
+ */
+function assetValue(p) {
+  const name = p.scope.adapter.get(p.path)
+  return typeof name === 'string' && p.scope.asset ? p.scope.asset(p.kind, name) : undefined
+}
+
+/** @type {Record<string, (p: PropertyData, args: any[]) => any>} */
+export const listenerMethods = {
+  addListener: (p, args) => listen(p, args, true),
+  removeListener: (p, args) => listen(p, args, false),
+}
+
+export const Property = defineType('Property', {
+  fields: {
+    value: {
+      get: (p) => (isAsset(p.kind) ? assetValue(p) : toLuaValue(p.scope.adapter.get(p.path))),
+      set: (p, v) => {
+        p.scope.adapter.set(p.path, fromLuaValue(p.kind, v))
+      },
+    },
+  },
+  methods: listenerMethods,
+})
+
+export const PropertyTrigger = defineType('PropertyTrigger', {
+  methods: {
+    addListener: listenerMethods.addListener,
+    removeListener: listenerMethods.removeListener,
+    fire: (p) => {
+      const a = p.scope.adapter
+      if (a.fire) a.fire(p.path)
+      else a.set(p.path, true)
+    },
+  },
+})
+
+export const PropertyViewModel = defineType('PropertyViewModel', {
+  fields: {
+    value: { get: (p) => viewModelAt(p.scope, p.path) },
+  },
+  methods: listenerMethods,
+})
+
+const PropertyList = listType({ listenerMethods, scopeOf, viewModelAt })
+
+/**
+ * The one property object for a path and kind.
+ *
+ * @param   {Scope}  scope
+ * @param   {string} path
+ * @param   {string} kind
+ * @returns {any}    its Lua wrapper
+ */
+function propertyAt(scope, path, kind) {
+  const key = kind + ':' + path
+  let p = scope.props[key]
+  if (!p) {
+    p = { scope, path, kind, listeners: [], unsubscribe: null, wrapper: null }
+    const type = kind === 'trigger' ? PropertyTrigger : kind === 'viewModel' ? PropertyViewModel : kind === 'list' ? PropertyList : Property
+    p.wrapper = type.wrap(p)
+    scope.props[key] = p
+  }
+  return p.wrapper
+}
+
+// View models
+// ■■■■■■■■■■■
+
+/**
+ * @typedef {object} ViewModelData
+ * @property {Scope}  scope
+ * @property {string} prefix  '' or a dotted path ending in '.'
+ */
+
+/**
+ * @param   {Scope}  scope
+ * @param   {string} path  the dotted path of the view model; '' for the root
+ * @returns {any}    a ViewModel wrapper
+ */
+export function viewModelAt(scope, path) {
+  return ViewModel.wrap({ scope, prefix: path === '' ? '' : path + '.' })
+}
+
+/**
+ * @param   {string} kind  what the method wants
+ * @returns {(h: ViewModelData, args: any[]) => any}
+ */
+function getter(kind) {
+  return function (h, args) {
+    const name = text(args, 1, 'get' + kind)
+    const path = h.prefix + name
+    const actual = kindOf(h.scope, path)
+    // without kinds from the adapter, a number may be a colour
+    const ok = actual === kind || (kind === 'color' && actual === 'number' && !h.scope.adapter.kind) || (kind === 'enum' && actual === 'string' && !h.scope.adapter.kind)
+    return ok ? propertyAt(h.scope, path, kind) : undefined
+  }
+}
+
+/**
+ * The scope of another adapter (a list's item, a new instance) beside this one.
+ *
+ * @param   {Scope}            scope
+ * @param   {ViewModelAdapter} adapter
+ * @returns {Scope}
+ */
+export function scopeOf(scope, adapter) {
+  if (scope.scopeFor) return scope.scopeFor(adapter)
+  return { adapter, props: {}, call: scope.call, wake: scope.wake, asset: scope.asset }
+}
+
+/** @type {Record<string, (h: ViewModelData, args: any[]) => any>} */
+const viewModelMethods = {
+  getNumber: getter('number'),
+  getString: getter('string'),
+  getBoolean: getter('boolean'),
+  getColor: getter('color'),
+  getEnum: getter('enum'),
+  getTrigger: getter('trigger'),
+  getViewModel: getter('viewModel'),
+  // lists, assets and creating instances need a player behind them
+  getList: getter('list'),
+  getImage: getter('image'),
+  getFont: getter('font'),
+  getBlob: getter('blob'),
+  // a new instance of this view model, optionally from a named instance of the file
+  instance: (h, args) => {
+    const a = h.scope.adapter
+    const made = a.instance ? a.instance(h.prefix === '' ? '' : h.prefix.slice(0, -1), args[1] === undefined ? undefined : text(args, 1, 'instance')) : undefined
+    return made ? viewModelAt(scopeOf(h.scope, made), '') : undefined
+  },
+  getIndex: () => -1,
+}
+
+export const ViewModel = defineType('ViewModel', {
+  fields: {
+    name: { get: () => '' },
+  },
+  methods: viewModelMethods,
+  // `vm.title` reads the property of that name, as a typed script's `Data.X` does
+  index: (h, key) => {
+    if (typeof key !== 'string') return undefined
+    const path = h.prefix + decodeUtf8(key)
+    const kind = kindOf(h.scope, path)
+    return kind === undefined ? undefined : propertyAt(h.scope, path, kind)
+  },
+})

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

@@ -0,0 +1,160 @@
+/**
+ * `PropertyList`: a view-model list property a script reads and changes,
+ * as Rive documents it. Items are view models, 1-based: `list[1]`,
+ * `list.length`, `push`, `insert(vm, index)`, `swap`, `pop`, `shift`,
+ * `clear`, `remove`, `removeAllOf`, `removeAt`, and `addListener`.
+ *
+ * The items are adapters of their own (`ViewModelAdapter.listGet`), so an item
+ * is read and written like any view model; what changes the list goes through
+ * `listInsert`, `listRemove` and `listSwap`, which the player turns into rows.
+ */
+
+import { fail } from '../../../luau/vm/vm.value.js'
+import { Wrapped, defineType, num } from '../../api/api.type.js'
+
+/** @import { PropertyData, ViewModelData } from '../context.viewmodel.js' */
+
+/**
+ * @typedef {object} ListDeps  what the view model gives the list type (passed in, so the two modules do not import each other)
+ * @property {Record<string, (p: PropertyData, args: any[]) => any>} listenerMethods
+ * @property {(scope: any, adapter: any) => any} scopeOf
+ * @property {(scope: any, path: string) => any} viewModelAt
+ */
+
+/** @type {ListDeps} */
+let deps
+
+/**
+ * @param   {PropertyData} p
+ * @returns {import('../context.viewmodel.js').ViewModelAdapter}
+ */
+function adapterOf(p) {
+  return p.scope.adapter
+}
+
+/**
+ * @param   {PropertyData} p
+ * @returns {number}
+ */
+function sizeOf(p) {
+  const a = adapterOf(p)
+  return a.listSize ? a.listSize(p.path) : 0
+}
+
+/**
+ * @param   {PropertyData} p
+ * @param   {number}       index  0-based
+ * @returns {any}                 the item's ViewModel, or nil
+ */
+function itemAt(p, index) {
+  const a = adapterOf(p)
+  const item = index >= 0 && a.listGet ? a.listGet(p.path, index) : undefined
+  return item ? deps.viewModelAt(deps.scopeOf(p.scope, item), '') : undefined
+}
+
+/**
+ * @param   {any[]}  args
+ * @param   {number} i
+ * @param   {string} fname
+ * @returns {import('../context.viewmodel.js').ViewModelAdapter} the adapter of a view model argument that is an instance
+ */
+function instanceArg(args, i, fname) {
+  const w = args[i]
+  /** @type {ViewModelData | undefined} */
+  const h = w instanceof Wrapped ? w.host : undefined
+  if (!h || !h.scope || h.prefix !== '') throw fail("invalid argument #" + (i + 1) + " to '" + fname + "' (ViewModel instance expected)")
+  return h.scope.adapter
+}
+
+/**
+ * @param   {PropertyData} p
+ * @param   {number}       index  0-based
+ * @returns {any}                 what was removed, as a ViewModel
+ */
+function take(p, index) {
+  const a = adapterOf(p)
+  if (index < 0 || index >= sizeOf(p) || !a.listRemove) return undefined
+  const item = a.listRemove(p.path, index)
+  return item ? deps.viewModelAt(deps.scopeOf(p.scope, item), '') : undefined
+}
+
+/**
+ * @param   {PropertyData} p
+ * @param   {import('../context.viewmodel.js').ViewModelAdapter} item
+ * @returns {number}  its 0-based place, -1 when absent
+ */
+function find(p, item) {
+  const a = adapterOf(p)
+  const n = sizeOf(p)
+  for (let i = 0; i < n; i++) if (a.listGet && a.listGet(p.path, i) === item) return i
+  return -1
+}
+
+/**
+ * @param   {PropertyData} p
+ * @param   {number}       n  1-based index, as a script writes it
+ * @param   {string}       fname
+ * @param   {number}       max  the highest allowed
+ * @returns {number}          0-based
+ */
+function place(p, n, fname, max) {
+  if (n !== Math.floor(n) || n < 1 || n > max) throw fail("invalid index to '" + fname + "' (" + n + ' of ' + max + ')')
+  return n - 1
+}
+
+/**
+ * @param   {ListDeps} d
+ * @returns {import('../../api/api.type.js').HostType}
+ */
+export function listType(d) {
+  deps = d
+  const listenerMethods = d.listenerMethods
+  return defineType('PropertyList', {
+    fields: {
+      length: { get: (p) => sizeOf(p) },
+    },
+    methods: {
+      addListener: listenerMethods.addListener,
+      removeListener: listenerMethods.removeListener,
+      push: (p, args) => {
+        const a = adapterOf(p)
+        if (a.listInsert) a.listInsert(p.path, instanceArg(args, 1, 'push'), sizeOf(p))
+      },
+      insert: (p, args) => {
+        const a = adapterOf(p)
+        const at = place(p, num(args, 2, 'insert'), 'insert', sizeOf(p) + 1)
+        if (a.listInsert) a.listInsert(p.path, instanceArg(args, 1, 'insert'), at)
+      },
+      swap: (p, args) => {
+        const a = adapterOf(p)
+        const n = sizeOf(p)
+        const i = place(p, num(args, 1, 'swap'), 'swap', n)
+        const j = place(p, num(args, 2, 'swap'), 'swap', n)
+        if (a.listSwap && i !== j) a.listSwap(p.path, i, j)
+      },
+      pop: (p) => take(p, sizeOf(p) - 1),
+      shift: (p) => take(p, 0),
+      clear: (p) => {
+        const a = adapterOf(p)
+        if (a.listClear) return void a.listClear(p.path)
+        for (let n = sizeOf(p) - 1; n >= 0; n--) take(p, n)
+      },
+      removeAt: (p, args) => {
+        take(p, place(p, num(args, 1, 'removeAt'), 'removeAt', sizeOf(p)))
+      },
+      remove: (p, args) => {
+        const at = find(p, instanceArg(args, 1, 'remove'))
+        if (at >= 0) take(p, at)
+      },
+      removeAllOf: (p, args) => {
+        const item = instanceArg(args, 1, 'removeAllOf')
+        for (let at = find(p, item); at >= 0; at = find(p, item)) take(p, at)
+      },
+    },
+    meta: {
+      __len: (vm, args) => sizeOf(args[0].host),
+    },
+    // `list[1]`: items are 1-based
+    index: (p, key) => (typeof key === 'number' ? itemAt(p, key - 1) : undefined),
+  })
+}