feat: add PenPointer and StrokeMotion

Author: nicholaswmin

.gitignore

@@ -5,3 +5,6 @@ npm-debug.log*
 # llm
 AGENTS.md
 .claude/
+
+# artifacts
+docs/spec/*.zip

README.md

@@ -13,7 +13,7 @@ npm i github:TheProfs/pointerdriver
 ## Usage  
 
 ```js
-import { DragMotion } from 'pointerdriver'
+import { DragMotion, GlideMotion, StrokeMotion } from 'pointerdriver'
 
 const el = document.querySelector('#el')
 
@@ -23,7 +23,8 @@ await new DragMotion(el, [
 ]).perform()
 ```
 
-`DragMotion` points are `[x, y, ms]`.  
+`DragMotion` (mouse), `GlideMotion` (finger), and `StrokeMotion` (pen)  
+take points as `[x, y, ms]`.  
 `ms` is the timestamp offset since the start of the motion.  
 Timestamps must be non-decreasing.  
 

index.js

@@ -1,2 +1,3 @@
 export { DragMotion } from './src/motions/drag/index.js'
 export { GlideMotion } from './src/motions/glide/index.js'
+export { StrokeMotion } from './src/motions/stroke/index.js'

package.json

@@ -10,7 +10,7 @@
   "bin": {
     "pointerdriver": "bin/pointerdriver.js"
   },
-  "files": ["index.js", "src/", "bin/", "docs/"],
+  "files": ["index.js", "src/", "bin/", "docs/", "!docs/spec/*.zip"],
   "scripts": {
     "start": "node ./bin/pointerdriver.js",
     "test": "node --test --test-concurrency=1 --test-timeout=5000 \"**/*.test.js\""

src/motions/stroke/index.js

@@ -0,0 +1,84 @@
+import { Motion } from '../../motion/index.js'
+
+const normalizePoints = raw => {
+  if (!Array.isArray(raw))
+    throw new TypeError('StrokeMotion.points must be [x, y, ms][]')
+
+  const points = raw.map((p, i) => {
+    if (!Array.isArray(p) || p.length !== 3)
+      throw new TypeError(`points[${i}] must be [x, y, ms]`)
+
+    const [x, y, createdAt] = p
+
+    if (
+      ![x, y, createdAt]
+        .every(n => typeof n === 'number' && Number.isFinite(n))
+    )
+      throw new TypeError(`points[${i}] must contain finite numbers`)
+
+    if (createdAt < 0)
+      throw new RangeError(`points[${i}][2] must be >= 0`)
+
+    return { x, y, createdAt }
+  })
+
+  for (let i = 1; i < points.length; i++) {
+    if (points[i].createdAt < points[i - 1].createdAt)
+      throw new RangeError(
+        `points[${i}][2] must be >= points[${i - 1}][2]`
+      )
+  }
+
+  return points
+}
+
+export class StrokeMotion extends Motion {
+  #points
+
+  constructor(el, points, opts) {
+    super(el, opts)
+    this.#points = normalizePoints(points)
+  }
+
+  get device() { return 'pen' }
+
+  async perform() {
+    const points = this.#points
+    if (!points.length) return
+
+    const pointer = this.pointer({ primary: true })
+
+    let point = points[0]
+    let target = this.hit(point)
+
+    pointer.enter(target, point)
+    pointer.down(target, point, 0, points.length)
+
+    try {
+      this.touchstart(pointer, point)
+
+      for (let i = 1; i < points.length; i++) {
+        await this.delay(points[i].createdAt - points[i - 1].createdAt)
+
+        target = this.hit(points[i])
+        point = points[i]
+
+        pointer.move(target, point, i, points.length)
+        this.touchmove(pointer, point)
+      }
+
+      pointer.up(target, point, points.length - 1, points.length)
+      pointer.leave(target, point)
+
+      this.touchend(pointer, point)
+    } catch (err) {
+      pointer.cancel(target, point)
+      this.touchcancel(pointer, point)
+      throw new Error(
+        `stroke aborted: ${err?.message ?? String(err)}`,
+        { cause: err }
+      )
+    }
+  }
+}
+

src/motions/stroke/test/main.test.js

@@ -0,0 +1,191 @@
+import { test } from 'node:test'
+import { mockDOM, mockListen } from '#test/utils'
+import { StrokeMotion } from '../index.js'
+
+test('StrokeMotion', async t => {
+  t.beforeEach(t => Object.assign(t, { mockDOM, mockListen }).mockDOM())
+
+  await t.test('points with non-array input', async t => {
+    await t.test('throws TypeError', t => {
+      const el = document.createElement('div')
+
+      t.assert.throws(
+        () => new StrokeMotion(el, null),
+        { name: 'TypeError', message: /StrokeMotion\.points/i }
+      )
+    })
+  })
+
+  await t.test('points with negative timestamps', async t => {
+    await t.test('throws RangeError', t => {
+      const el = document.createElement('div')
+
+      t.assert.throws(
+        () => new StrokeMotion(el, [[10, 10, -1]]),
+        { name: 'RangeError', message: />= 0/i }
+      )
+    })
+  })
+
+  await t.test('points with decreasing timestamps', async t => {
+    await t.test('throws RangeError', t => {
+      const el = document.createElement('div')
+
+      t.assert.throws(
+        () => new StrokeMotion(el, [
+          [10, 10, 1],
+          [11, 11, 0],
+        ]),
+        { name: 'RangeError', message: /points\[1\]\[2\]/i }
+      )
+    })
+  })
+
+  await t.test('pen stroke within element', async t => {
+    t.beforeEach(t => Object.assign(t, {
+      stage: document.body.appendChild(
+        Object.assign(document.createElement('div'), { id: 'stage' })
+      ),
+      a: document.createElement('div'),
+    }))
+
+    t.beforeEach(t => {
+      t.a.id = 'a'
+      t.stage.append(t.a)
+      document.elementFromPoint = () => t.a
+    })
+
+    await t.test('dispatches expected event sequence', async t => {
+      const dispatched = t.mockListen([
+        'pointerover',
+        'pointerenter',
+        'pointerdown',
+        'touchstart',
+        'gotpointercapture',
+        'pointermove',
+        'touchmove',
+        'pointerup',
+        'lostpointercapture',
+        'pointerout',
+        'pointerleave',
+        'touchend',
+      ])
+
+      await new StrokeMotion(t.stage, [
+        [10, 10, 0],
+        [11, 11, 0],
+      ]).perform()
+
+      t.assert.eventSequence(dispatched, [
+        'pointerover@a',
+        'pointerenter@HTML',
+        'pointerenter@BODY',
+        'pointerenter@stage',
+        'pointerenter@a',
+        'pointerdown@a',
+        'touchstart@a',
+        'pointermove@a',
+        'touchmove@a',
+        'pointerup@a',
+        'pointerout@a',
+        'pointerleave@a',
+        'pointerleave@stage',
+        'pointerleave@BODY',
+        'pointerleave@HTML',
+        'touchend@a',
+      ])
+    })
+
+    await t.test('dispatches pointermove for each point after first', async t => {
+      const dispatched = t.mockListen(['pointermove'])
+
+      await new StrokeMotion(t.stage, [
+        [10, 10, 0],
+        [11, 11, 0],
+        [12, 12, 0],
+      ]).perform()
+
+      t.assert.strictEqual(dispatched.length, 2)
+    })
+
+    await t.test('uses pointerType pen', async t => {
+      const dispatched = t.mockListen([
+        'pointerover',
+        'pointerenter',
+        'pointerdown',
+        'pointermove',
+        'pointerup',
+        'pointerout',
+        'pointerleave',
+      ])
+
+      await new StrokeMotion(t.stage, [
+        [10, 10, 0],
+        [11, 11, 0],
+      ]).perform()
+
+      t.assert.everyPartialEqual(dispatched, { pointerType: 'pen' })
+    })
+  })
+
+  await t.test('hit-test miss mid-motion', async t => {
+    t.beforeEach(t => Object.assign(t, {
+      stage: document.body.appendChild(
+        Object.assign(document.createElement('div'), { id: 'stage' })
+      ),
+      a: document.createElement('div'),
+    }))
+
+    t.beforeEach(t => {
+      t.a.id = 'a'
+      t.stage.append(t.a)
+      document.elementFromPoint = x => (x < 20 ? t.a : null)
+    })
+
+    await t.test('rejects with hit-test missed error', async t => {
+      await t.assert.rejects(
+        () => new StrokeMotion(t.stage, [
+          [10, 10, 0],
+          [30, 10, 0],
+        ]).perform(),
+        { name: 'Error', message: /hit-test missed/i }
+      )
+    })
+
+    await t.test('dispatches pointercancel then leave then touchcancel', async t => {
+      const dispatched = t.mockListen([
+        'pointerover',
+        'pointerenter',
+        'pointerdown',
+        'touchstart',
+        'pointercancel',
+        'pointerout',
+        'pointerleave',
+        'touchcancel',
+      ])
+
+      await new StrokeMotion(t.stage, [
+        [10, 10, 0],
+        [30, 10, 0],
+      ]).perform().catch(() => null)
+
+      t.assert.eventSequence(dispatched, [
+        'pointerover@a',
+        'pointerenter@HTML',
+        'pointerenter@BODY',
+        'pointerenter@stage',
+        'pointerenter@a',
+        'pointerdown@a',
+        'touchstart@a',
+        'pointercancel@a',
+        'pointerout@a',
+        'pointerleave@a',
+        'pointerleave@stage',
+        'pointerleave@BODY',
+        'pointerleave@HTML',
+        'touchcancel@a',
+      ])
+    })
+  })
+})
+