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

package/script/rive/api/pointer/pointer.route.js

@@ -0,0 +1,69 @@
+/**
+ * Pointer events into scripted nodes. `routePointer` takes one pointer event
+ * in the player's space and offers it to the nodes that listen, top-most
+ * first, until one claims it with `event:hit()`; a node that is not hit but
+ * was under the pointer before gets a `pointerExit`.
+ *
+ * ```js
+ * const nodes = [ { host, world: [1, 0, 0, 1, 40, 20], contains: (x, y) => hits.test('7', x, y) } ]
+ * routePointer(nodes, 'down', x, y, id, seconds)
+ * ```
+ *
+ * The player's pointer module (`pointer/`) calls this where it hit-tests its
+ * listeners; `contains` is its hit test of the node's shape.
+ */
+
+/**
+ * @typedef {object} PointerNode
+ * @property {{ pointer: (type: string, x: number, y: number, id?: number, time?: number) => { hit: boolean, translucent: boolean } }} host  the script's host
+ * @property {number[]} [world]                    the node's world matrix [xx, xy, yx, yy, tx, ty]; identity when absent
+ * @property {(x: number, y: number) => boolean} [contains]  whether the point is on the node (in the player's space); absent counts as always
+ * @property {boolean} [inside]                    kept by the router
+ */
+
+/**
+ * @param   {number[] | undefined} m
+ * @param   {number} x
+ * @param   {number} y
+ * @returns {number[]} [x, y] in the node's space
+ */
+function local(m, x, y) {
+  if (!m) return [ x, y ]
+  const det = m[0] * m[3] - m[1] * m[2]
+  if (det === 0) return [ x, y ]
+  const dx = x - m[4]
+  const dy = y - m[5]
+  return [ (m[3] * dx - m[2] * dy) / det, (m[0] * dy - m[1] * dx) / det ]
+}
+
+/**
+ * @param   {PointerNode[]} nodes  in draw order, top-most last
+ * @param   {'down' | 'move' | 'up' | 'exit'} type
+ * @param   {number} x
+ * @param   {number} y
+ * @param   {number} [id]
+ * @param   {number} [time]
+ * @returns {boolean} whether a node claimed the event
+ */
+export function routePointer(nodes, type, x, y, id, time) {
+  let claimed = false
+  for (let n = nodes.length - 1; n >= 0; n--) {
+    const node = nodes[n]
+    const on = type !== 'exit' && !claimed && (!node.contains || node.contains(x, y))
+    if (!on) {
+      if (node.inside) {
+        node.inside = false
+        const p = local(node.world, x, y)
+        node.host.pointer('exit', p[0], p[1], id, time)
+      }
+      continue
+    }
+    const p = local(node.world, x, y)
+    const result = node.host.pointer(type, p[0], p[1], id, time)
+    node.inside = type !== 'up' || node.inside
+    if (result.hit) {
+      if (!result.translucent) claimed = true
+    }
+  }
+  return claimed
+}

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

@@ -0,0 +1,129 @@
+/**
+ * `Font`: a font a script measures and draws with. The host holds no font
+ * data: the player gives it a `FontInfo`, the metrics and advances of a font
+ * its bundle carries (from `bundle/bundle.fonts.js`' registered face measured
+ * on a canvas, or from opentype.js at conversion), and the host lays text out
+ * with them. Without one, text is laid out with a fixed fallback.
+ */
+
+import { LuaTable } from '../../../luau/vm/vm.value.js'
+import { decodeUtf8 } from '../../../luau/luau.convert.js'
+import { defineType, num, text } from '../api.type.js'
+import { statics } from '../api.statics.js'
+import { newPath } from '../draw/draw.path.js'
+
+/**
+ * @typedef {object} FontInfo
+ * @property {string}  name
+ * @property {number}  [ascent]     per 1 point of size, negative up (default -0.8)
+ * @property {number}  [descent]    positive down (default 0.2)
+ * @property {number}  [capHeight]  negative up
+ * @property {number}  [xHeight]    negative up
+ * @property {number}  [weight]     1 to 1000, 400 regular
+ * @property {boolean} [isItalic]
+ * @property {(codepoint: number) => number} [advance]   the advance of a character in em (default 0.5)
+ * @property {(codepoint: number) => boolean} [hasGlyph]
+ * @property {(codepoint: number) => number} [glyphId]   default the codepoint itself
+ * @property {(glyphId: number) => any[]} [glyphPath]    the outline as Path commands `{ t, p }` in 1 point units
+ * @property {Record<string, number>} [axes]
+ * @property {string[]} [features]
+ */
+
+/**
+ * @param   {FontInfo} info
+ * @returns {Required<Pick<FontInfo, 'name' | 'ascent' | 'descent' | 'capHeight' | 'xHeight' | 'weight' | 'isItalic'>> & FontInfo}
+ */
+export function completeFont(info) {
+  return /** @type {any} */ ({
+    ascent: -0.8,
+    descent: 0.2,
+    capHeight: -0.7,
+    xHeight: -0.5,
+    weight: 400,
+    isItalic: false,
+    ...info,
+  })
+}
+
+/**
+ * A `FontInfo` whose advances are measured by a function of one character,
+ * such as `(c) => ctx.measureText(c).width / ctx.font size`.
+ *
+ * @param   {string} name
+ * @param   {(character: string) => number} measure  the character's advance in em
+ * @param   {Partial<FontInfo>} [metrics]
+ * @returns {FontInfo}
+ */
+export function measuredFont(name, measure, metrics) {
+  return { name, ...metrics, advance: (cp) => measure(String.fromCharCode(cp)) }
+}
+
+export const Font = defineType('Font', {
+  fields: {
+    ascent: { get: (f) => f.ascent },
+    descent: { get: (f) => f.descent },
+    capHeight: { get: (f) => f.capHeight },
+    xHeight: { get: (f) => f.xHeight },
+    weight: { get: (f) => f.weight },
+    isItalic: { get: (f) => f.isItalic },
+    axes: { get: (f) => tableOf(f.axes ? Object.keys(f.axes) : []) },
+    features: { get: (f) => tableOf(f.features || []) },
+  },
+  methods: {
+    lineHeight: (f, args) => (f.descent - f.ascent) * num(args, 1, 'lineHeight'),
+    hasGlyph: (f, args) => (f.hasGlyph ? f.hasGlyph(num(args, 1, 'hasGlyph')) : true),
+    axisValue: (f, args) => (f.axes ? f.axes[text(args, 1, 'axisValue')] || 0 : 0),
+    withOptions: (f, args) => {
+      const axes = args[1] instanceof LuaTable ? merged(f.axes, plain(args[1])) : f.axes
+      const features = args[2] instanceof LuaTable ? Object.keys(plain(args[2])) : f.features
+      return Font.wrap({ ...f, axes, features })
+    },
+    glyphPath: (f, args) => newPath(f.glyphPath ? f.glyphPath(num(args, 1, 'glyphPath')) : []),
+  },
+})
+
+/**
+ * @param   {Record<string, number> | undefined} base
+ * @param   {Record<string, number>} over
+ * @returns {Record<string, number>}
+ */
+function merged(base, over) {
+  /** @type {Record<string, number>} */
+  const out = {}
+  for (const k in base) out[k] = base[k]
+  for (const k in over) out[k] = over[k]
+  return out
+}
+
+/**
+ * @param   {string[]} names
+ * @returns {LuaTable}
+ */
+function tableOf(names) {
+  const t = new LuaTable()
+  t.setRange(1, names, 0, names.length)
+  return t
+}
+
+/**
+ * @param   {LuaTable} t
+ * @returns {Record<string, number>}  its string keys with number values
+ */
+function plain(t) {
+  /** @type {Record<string, number>} */
+  const out = {}
+  for (let at = t.advance(0); at !== null; at = t.advance(at)) {
+    if (typeof t.ck === 'string' && typeof t.cv === 'number') out[decodeUtf8(t.ck)] = t.cv
+  }
+  return out
+}
+
+/**
+ * Installs the `Font` global.
+ *
+ * @param {import('../../../luau/vm/vm.js').VM} vm
+ */
+export function installFont(vm) {
+  // there is no decoder here: a font a script brings as bytes is nil, as for bytes that are not a font
+  vm.globals.set('Font', statics('Font', { decode: () => undefined }))
+}

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

@@ -0,0 +1,278 @@
+/**
+ * `Text`: styled runs a script lays out and draws. `Text.new()`, `append`,
+ * `clear`, `draw`, `bounds`, `line`, `lines`, `hitTest`, `caret`,
+ * `selectionRects`, and the layout fields (`sizing`, `overflow`, `align`,
+ * `wrap`, `wordBreak`, `origin`, `direction`, `maxWidth`, `maxHeight`,
+ * `paragraphSpacing`). Layout is `text.layout.js`, with the metrics of the
+ * fonts the player gave the host; the draw is recorded as
+ *
+ * `{ kind: 'text', runs, lines, text, transform, clips, opacity, color, paint, ...layout }`
+ *
+ * where each run is `{ text, font, size, lineHeight, letterSpacing, paint, foregroundColor }`
+ * (`font` an asset name, `paint` a snapshot or null) and each line
+ * `{ x, top, baseline, bottom, width, firstIndex, lastIndex, text }`. A run
+ * with no paint draws only when `Text:draw` is given one.
+ */
+
+import { LuaTable, Vector } from '../../../luau/vm/vm.value.js'
+import { decodeUtf8 } from '../../../luau/luau.convert.js'
+import { badArg, defineType, num, text, wrapped } from '../api.type.js'
+import { statics } from '../api.statics.js'
+import { Mat2D } from '../math/math.mat2d.js'
+import { Paint, snapshotPaint } from '../draw/draw.paint.js'
+import { newPath } from '../draw/draw.path.js'
+import { Renderer } from '../draw/draw.renderer.js'
+import { stamp } from '../media/media.draw.js'
+import { Font } from './text.font.js'
+import { layoutText } from './text.layout.js'
+
+/** @import { Layout, LayoutOptions, Run } from './text.layout.js' */
+
+/**
+ * @typedef {object} TextData
+ * @property {{ run: Run, paint: any, foreground: number }[]} runs
+ * @property {LayoutOptions} o
+ * @property {Layout | null} laid
+ * @property {() => any} fallback  the font for a run with none
+ */
+
+/** @type {Record<string, string>} the fields that hold a name */
+const NAMES = { sizing: 'autoWidth', overflow: 'visible', align: 'left', wrap: 'wrap', wordBreak: 'normal', origin: 'top', direction: 'ltr' }
+/** @type {string[]} */
+const NUMBERS = [ 'maxWidth', 'maxHeight', 'paragraphSpacing' ]
+
+/**
+ * @param   {TextData} h
+ * @returns {Layout}
+ */
+function laid(h) {
+  if (!h.laid) {
+    const runs = []
+    for (let n = 0; n < h.runs.length; n++) runs.push(h.runs[n].run)
+    h.laid = layoutText(runs, h.o)
+  }
+  return h.laid
+}
+
+/** @type {Record<string, { get: (h: any) => any, set: (h: any, v: any) => void }>} */
+const fields = {
+  isEmpty: { get: (h) => laid(h).length === 0, set: () => {} },
+  lineCount: { get: (h) => laid(h).lines.length, set: () => {} },
+  length: { get: (h) => laid(h).length, set: () => {} },
+}
+for (const name in NAMES) {
+  fields[name] = {
+    get: (h) => h.o[name],
+    set: (h, v) => {
+      if (typeof v !== 'string') throw badArg(0, name, 'string', [ v ])
+      h.o[name] = decodeUtf8(v)
+      h.laid = null
+    },
+  }
+}
+for (let n = 0; n < NUMBERS.length; n++) {
+  const name = NUMBERS[n]
+  fields[name] = {
+    get: (h) => h.o[name],
+    set: (h, v) => {
+      if (typeof v !== 'number') throw badArg(0, name, 'number', [ v ])
+      h.o[name] = v
+      h.laid = null
+    },
+  }
+}
+
+/**
+ * @param   {any}  style  a Lua table
+ * @param   {TextData} h
+ * @returns {{ run: Run, paint: any, foreground: number }}
+ */
+function runOf(style, h) {
+  const t = style instanceof LuaTable ? style : new LuaTable()
+  const f = t.getStr('font')
+  const size = t.getStr('size')
+  const lineHeight = t.getStr('lineHeight')
+  const letterSpacing = t.getStr('letterSpacing')
+  const fg = t.getStr('foregroundColor')
+  return {
+    run: {
+      text: '',
+      font: Font.is(f) ? Font.unwrap(f) : h.fallback(),
+      size: typeof size === 'number' ? size : 16,
+      lineHeight: typeof lineHeight === 'number' ? lineHeight : 0,
+      letterSpacing: typeof letterSpacing === 'number' ? letterSpacing : 0,
+    },
+    paint: Paint.unwrap(t.getStr('paint')) || null,
+    foreground: typeof fg === 'number' ? fg : 0xff000000,
+  }
+}
+
+/**
+ * @param   {TextData} h
+ * @param   {number}   index  1-based codepoint index
+ * @returns {{ line: import('./text.layout.js').Line, x: number } | null}
+ */
+function locate(h, index) {
+  const lines = laid(h).lines
+  for (let n = 0; n < lines.length; n++) {
+    const l = lines[n]
+    if (index >= l.firstIndex && index <= l.lastIndex + 1) {
+      for (let k = 0; k < l.glyphs.length; k++) if (l.glyphs[k].textIndex === index) return { line: l, x: l.glyphs[k].x }
+      return { line: l, x: l.x + l.width }
+    }
+  }
+  return null
+}
+
+export const Glyph = defineType('Glyph', {
+  fields: {
+    id: { get: (g) => g.id },
+    font: { get: (g) => Font.wrap(g.run.font) },
+    size: { get: (g) => g.run.size },
+    x: { get: (g) => g.x },
+    y: { get: (g) => g.y },
+    advance: { get: (g) => g.advance },
+    textIndex: { get: (g) => g.textIndex },
+    direction: { get: () => 'ltr' },
+    isColor: { get: () => false },
+    transform: { get: (g) => Mat2D.wrap([ g.run.size, 0, 0, g.run.size, g.x, g.y ]) },
+  },
+  methods: {
+    path: (g) => {
+      const f = g.run.font
+      const cmds = f.glyphPath ? f.glyphPath(g.id) : []
+      return newPath(cmds.map((/** @type {any} */ c) => ({ t: c.t, p: c.p.map((/** @type {number} */ v, /** @type {number} */ i) => v * g.run.size + (i % 2 ? g.y : g.x)) })))
+    },
+  },
+})
+
+export const TextLine = defineType('TextLine', {
+  fields: {
+    index: { get: (l) => l.index },
+    x: { get: (l) => l.x },
+    top: { get: (l) => l.top },
+    baseline: { get: (l) => l.baseline },
+    bottom: { get: (l) => l.bottom },
+    width: { get: (l) => l.width },
+    direction: { get: () => 'ltr' },
+    firstIndex: { get: (l) => l.firstIndex },
+    lastIndex: { get: (l) => l.lastIndex },
+    glyphCount: { get: (l) => l.glyphs.length },
+  },
+  methods: {
+    glyph: (l, args) => {
+      const g = l.glyphs[num(args, 1, 'glyph') - 1]
+      return g ? Glyph.wrap(g) : undefined
+    },
+    glyphs: (l) => list(l.glyphs.map((/** @type {any} */ g) => Glyph.wrap(g))),
+  },
+})
+
+/**
+ * @param   {any[]} items
+ * @returns {LuaTable}
+ */
+function list(items) {
+  const t = new LuaTable()
+  t.setRange(1, items, 0, items.length)
+  return t
+}
+
+export const Text = defineType('Text', {
+  fields,
+  methods: {
+    append: (h, args) => {
+      const r = runOf(args[2], h)
+      r.run.text = text(args, 1, 'append')
+      h.runs.push(r)
+      h.laid = null
+    },
+    clear: (h) => {
+      h.runs.length = 0
+      h.laid = null
+    },
+    draw: (h, args) => {
+      const rec = wrapped(args, 1, Renderer, 'draw')
+      const given = args[2] === undefined ? null : wrapped(args, 2, Paint, 'draw')
+      const l = laid(h)
+      const out = /** @type {any} */ (stamp(rec, 'text'))
+      const color = rec.state.color
+      out.runs = h.runs.map((/** @type {any} */ r) => {
+        const p = given || r.paint
+        return {
+          text: r.run.text,
+          font: r.run.font.name,
+          size: r.run.size,
+          lineHeight: r.run.lineHeight,
+          letterSpacing: r.run.letterSpacing,
+          paint: p ? snapshotPaint(p, color) : null,
+          foregroundColor: r.foreground,
+        }
+      })
+      if (!out.runs.some((/** @type {any} */ r) => r.paint)) return
+      out.paint = given ? snapshotPaint(given, color) : null
+      out.lines = l.lines.map((n) => ({ x: n.x, top: n.top, baseline: n.baseline, bottom: n.bottom, width: n.width, firstIndex: n.firstIndex, lastIndex: n.lastIndex, text: n.text }))
+      out.text = out.lines.map((/** @type {any} */ n) => n.text).join('\n')
+      out.width = l.width
+      out.height = l.height
+      for (const k in h.o) out[k] = h.o[/** @type {keyof LayoutOptions} */ (k)]
+      rec.drawings.push(out)
+    },
+    bounds: (h) => {
+      const l = laid(h)
+      const top = l.lines.length ? l.lines[0].top : 0
+      return [ new Vector(0, top, 0), new Vector(l.width, top + l.height, 0) ]
+    },
+    line: (h, args) => {
+      const l = laid(h).lines[num(args, 1, 'line') - 1]
+      return l ? TextLine.wrap(l) : undefined
+    },
+    lines: (h) => list(laid(h).lines.map((l) => TextLine.wrap(l))),
+    hitTest: (h, args) => {
+      const p = args[1]
+      if (!(p instanceof Vector)) throw badArg(1, 'hitTest', 'Vector', args)
+      const lines = laid(h).lines
+      let line = lines[0]
+      for (let n = 0; n < lines.length; n++) if (p.y >= lines[n].top) line = lines[n]
+      if (!line) return 1
+      for (let k = 0; k < line.glyphs.length; k++) {
+        const g = line.glyphs[k]
+        if (p.x < g.x + g.advance / 2) return g.textIndex
+      }
+      return line.lastIndex + 1
+    },
+    caret: (h, args) => {
+      const at = locate(h, num(args, 1, 'caret'))
+      return at ? [ at.x, at.line.top, at.line.bottom ] : undefined
+    },
+    selectionRects: (h, args) => {
+      const from = num(args, 1, 'selectionRects')
+      const to = num(args, 2, 'selectionRects')
+      const out = []
+      const lines = laid(h).lines
+      for (let n = 0; n < lines.length; n++) {
+        for (let k = 0; k < lines[n].glyphs.length; k++) {
+          const g = lines[n].glyphs[k]
+          if (g.textIndex < from || g.textIndex >= to) continue
+          const r = new LuaTable()
+          r.set('min', new Vector(g.x, lines[n].top, 0))
+          r.set('max', new Vector(g.x + g.advance, lines[n].bottom, 0))
+          out.push(r)
+        }
+      }
+      return list(out)
+    },
+  },
+})
+
+/**
+ * Installs the `Text` global. A run with no font uses `fallback()`'s.
+ *
+ * @param {import('../../../luau/vm/vm.js').VM} vm
+ * @param {() => any} fallback  a completed FontInfo
+ */
+export function installText(vm, fallback) {
+  vm.globals.set('Text', statics('Text', {
+    new: () => Text.wrap({ runs: [], o: { ...NAMES, maxWidth: 0, maxHeight: 0, paragraphSpacing: 0 }, laid: null, fallback }),
+  }))
+}