@solidrt/core 0.0.57 → 0.0.58

package/AGENTS.md

@@ -361,7 +361,17 @@ latest (solid-js 1.x, off Solid 2.0 entirely). The recipe that works is
   `<View2d pointer>` take a feed and spread it on their built-in leaf) and
   bind its gestures `drag` (one pointer), `pan` (two), `pinch`, `twist`,
   `wheel` and `mouseDelta` (raw motion while pointerLocked()). One
-  merged recognizer serves them, so they arbitrate in the arena as one. A
+  merged recognizer serves them, so they arbitrate in the arena as one.
+  Each gesture takes a chord in the key-spec grammar: `pointer.drag("Ctrl")`
+  fires only when the event that opens the gesture carries Ctrl, and then
+  instead of the bare `drag` (the most specific bound chord wins, as a
+  key spec does), held for the whole gesture - so plain drag on `rotate`
+  and `drag("Ctrl")` on `pan` is one binding each, the every-viewport
+  default. A bracketed spec may end in its button (`drag("Right")`,
+  `drag("Shift+Middle")`; bare means Left), a discriminator rather than
+  a modifier: a right drag feeds only Right specs. Touch carries no
+  modifiers or buttons: a chord is the desktop path, the bare binding
+  stays for fingers. A
   detached d-* leaf has no layout box: give the feed `{ layout }` or it
   throws at the first press. `invert(source)` and `scale(source, k)` are
   the two processors: keys and sticks move the CAMERA where a drag moves

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/core",
-  "version": "0.0.57",
+  "version": "0.0.58",
   "license": "MIT",
   "funding": "https://github.com/sponsors/wellawaretech",
   "author": "Antoine van Wel",
@@ -31,7 +31,7 @@
     "AGENTS.md"
   ],
   "devDependencies": {
-    "@solidrt/flux-types": "0.0.57"
+    "@solidrt/flux-types": "0.0.58"
   },
   "peerDependencies": {
     "@solidjs/signals": "2.0.0-rc.6",

package/src/index.ts

@@ -37,7 +37,7 @@ export type { KeyboardDevice, KeyboardVec2Keys } from "./input-keyboard"
 export { gamepad } from "./input-gamepad"
 export type { GamepadDevice } from "./input-gamepad"
 export { createPointerFeed } from "./input-pointer"
-export type { PointerFeed, PointerFeedOptions } from "./input-pointer"
+export type { PointerFeed, PointerFeedOptions, PointerSource } from "./input-pointer"
 export type {
   Element,
   LayoutProps,

package/src/input-chord.ts

@@ -0,0 +1,44 @@
+// Modifier chords, the vocabulary two devices share: a spec names
+// modifiers ahead of what it qualifies ("Shift+Tab" on the keyboard,
+// "Ctrl" on a pointer gesture), the event must carry them, a bare spec
+// ignores them (a shifted W still walks, a Ctrl-drag still drags), and
+// among the specs one event satisfies the most specific wins - Unreal's
+// chord blocker, Three's OrbitControls picking PAN over ROTATE at
+// mousedown; Godot and Unity fire both by default and every app writes
+// the exclusion itself. Which event resolves a chord is the device's
+// call: the keyboard settles each key down, the pointer feed the event
+// that opens a gesture bracket.
+
+export type Modifier = "shiftKey" | "ctrlKey" | "altKey" | "metaKey"
+/** The modifier flags every key, pointer and wheel event carries. */
+export type Modified = Record<Modifier, boolean>
+
+const MODIFIERS: Record<string, Modifier> = { Shift: "shiftKey", Ctrl: "ctrlKey", Control: "ctrlKey", Alt: "altKey", Meta: "metaKey" }
+// The canonical order a chord is spelled in, so one modifier set has one name.
+const ORDER: Modifier[] = ["shiftKey", "ctrlKey", "altKey", "metaKey"]
+const NAMES: Record<Modifier, string> = { shiftKey: "Shift", ctrlKey: "Ctrl", altKey: "Alt", metaKey: "Meta" }
+
+/** The modifiers `parts` name (["Ctrl", "Shift"]), deduplicated, in
+ * canonical order; `what` and `text` name the caller and its spec in the
+ * throw on an unknown name. */
+export function parseModifiers(what: string, text: string, parts: string[]): Modifier[] {
+  let mods = new Set<Modifier>()
+  for (let part of parts) {
+    let mod = MODIFIERS[part]
+    if (!mod) throw new Error(`${what}: unknown modifier "${part}" in "${text}" (Shift, Ctrl, Alt or Meta)`)
+    mods.add(mod)
+  }
+  return ORDER.filter(m => mods.has(m))
+}
+
+/** The canonical spelling of a modifier set: "Shift+Ctrl"; "" for none. */
+export let chordName = (mods: Modifier[]): string => mods.map(m => NAMES[m]).join("+")
+
+/** Of `items`, those whose modifiers the event carries, narrowed to the
+ * most specific (the longest modifier lists, all of them on a tie);
+ * empty when none match. */
+export function mostSpecific<T>(items: T[], mods: (item: T) => Modifier[], event: Modified): T[] {
+  let hits = items.filter(item => mods(item).every(m => event[m]))
+  let most = hits.reduce((n, item) => Math.max(n, mods(item).length), 0)
+  return hits.filter(item => mods(item).length === most)
+}

package/src/input-keyboard.ts

@@ -8,11 +8,12 @@
 // a shifted "W".
 //
 // A spec may name modifiers ahead of the key ("Shift+Tab", "Ctrl+KeyS";
-// Shift, Ctrl, Alt, Meta): the down must carry them, while a bare spec
-// ignores them (a shifted W still walks). Within one source the most
-// specific matching spec wins a down, so `axis("Shift+Tab", "Tab")` reads
-// -1, not 0, on Shift+Tab; and an up releases on the key alone, so a
-// modifier let go first cannot leave the key stuck.
+// the chord vocabulary of input-chord.ts, shared with the pointer feed):
+// the down must carry them, while a bare spec ignores them (a shifted W
+// still walks). Within one source the most specific matching spec wins
+// a down, so `axis("Shift+Tab", "Tab")` reads -1, not 0, on Shift+Tab;
+// and an up releases on the key alone, so a modifier let go first
+// cannot leave the key stuck.
 //
 // Held state is a count behind a signal, so a source's rate is reactive
 // (a held key wakes a control's frame loop) and a blur - the up that never
@@ -27,10 +28,8 @@ import { createSignal } from "@solidjs/signals"
 import type { KeyEvent } from "./types"
 import type { InputSource } from "./input-map"
 import type { Vec2 } from "./input-axes"
-
-type Modifier = "shiftKey" | "ctrlKey" | "altKey" | "metaKey"
-
-const MODIFIERS: Record<string, Modifier> = { Shift: "shiftKey", Ctrl: "ctrlKey", Control: "ctrlKey", Alt: "altKey", Meta: "metaKey" }
+import { mostSpecific, parseModifiers } from "./input-chord"
+import type { Modifier } from "./input-chord"
 
 // A parsed spec: the text as given (the held-state key and the label),
 // the key it names, and the modifiers the down must carry.
@@ -41,13 +40,7 @@ function parse(what: string, text: unknown): Spec {
   let parts = text.split("+")
   let key = parts.pop()!
   if (key.length === 0) throw new Error(`keyboard.${what}: "${text}" names no key`)
-  let mods: Modifier[] = []
-  for (let part of parts) {
-    let mod = MODIFIERS[part]
-    if (!mod) throw new Error(`keyboard.${what}: unknown modifier "${part}" in "${text}" (Shift, Ctrl, Alt or Meta)`)
-    if (!mods.includes(mod)) mods.push(mod)
-  }
-  return { text, key, mods }
+  return { text, key, mods: parseModifiers(`keyboard.${what}`, text, parts) }
 }
 
 // A key matches its physical code or its logical key; a letter code
@@ -75,11 +68,7 @@ function held(specs: Spec[]) {
       // moves "Tab" to "Shift+Tab" and back), an up frees them all.
       let onKey = specs.filter(s => matches(event, s.key))
       for (let s of onKey) down.delete(s.text)
-      if (isDown) {
-        let hits = onKey.filter(s => s.mods.every(m => event[m]))
-        let most = hits.reduce((n, s) => Math.max(n, s.mods.length), 0)
-        for (let s of hits) if (s.mods.length === most) down.add(s.text)
-      }
+      if (isDown) for (let s of mostSpecific(onKey, s => s.mods, event)) down.add(s.text)
       setCount(down.size)
     },
     blur() {

package/src/input-map.ts

@@ -213,7 +213,8 @@ function checkValue(what: string, kind: ActionKind, v: unknown): void {
 
 function checkSource(source: unknown): InputSource {
   let s = source as InputSource
-  if (!s || typeof s !== "object" || (s.kind !== "button" && s.kind !== "axis" && s.kind !== "vec2") || typeof s.label !== "string") {
+  // A pointer gesture is a callable source (`pointer.drag("Ctrl")` is its chord variant).
+  if (!s || (typeof s !== "object" && typeof s !== "function") || (s.kind !== "button" && s.kind !== "axis" && s.kind !== "vec2") || typeof s.label !== "string") {
     throw new Error(`createInputMap: not an input source: ${String(source)}`)
   }
   return s

package/src/input-pointer.ts

@@ -33,6 +33,30 @@
 // Brackets fire on the press itself, before the recognizer's slop, so a
 // glide stops the moment a finger lands.
 //
+// Chords: every source is also callable with a modifier spec, and
+// `pointer.drag("Ctrl")` is the variant that fires only when the event
+// opening the gesture carries Ctrl - and then instead of the bare `drag`,
+// as the keyboard's most specific spec wins a key down (input-chord.ts,
+// the one grammar for both devices). That is the every-viewport default,
+// plain drag orbits and Ctrl-drag pans, as one binding each. A chord is
+// resolved once per bracket, at the event that opens it (the down that
+// starts a drag, the second down that starts pan/pinch/twist, the up
+// that hands the gesture back to drag), and held for the bracket, so a
+// modifier tapped mid-drag cannot split one gesture across two actions
+// (Three decides at mousedown; Unreal's continuous chord splits). The
+// unbracketed wheel and mouseDelta resolve per event. Touch carries no
+// modifiers, so a chord binding is the desktop path and the bare one
+// stays for fingers.
+//
+// Buttons: a bracketed spec may end in the button that opens it, as a
+// key spec ends in its key - `pointer.drag("Right")`, `drag("Shift+Middle")`
+// (Left, Middle, Right; bare means Left) - so Three's right-drag pan is
+// a binding too. A button is a discriminator, not a modifier: a right
+// drag feeds only Right specs, and the chord rule picks among those. One
+// button per pointer: a second button pressed while the first is held
+// joins nothing, and only the held button's release closes the gesture.
+// The wheel and mouseDelta have no button; a button word on them throws.
+//
 // The element's laid-out box normalizes the travel: read at the press
 // through getLayoutBox (the untransformed read, so a designSize fit or
 // an ancestor transform never skews it), or from `layout` when given -
@@ -49,6 +73,8 @@ import { pointerLocked } from "./window"
 import type { PointerEvent, WheelEvent } from "./types"
 import type { DeltaSink, InputSource } from "./input-map"
 import type { Vec2 } from "./input-axes"
+import { chordName, mostSpecific, parseModifiers } from "./input-chord"
+import type { Modified, Modifier } from "./input-chord"
 
 // Octaves per wheel-delta unit: the zoom exponent both cameras used
 // (0.0015 per unit) taken in log2, so a 100-unit notch zooms about a
@@ -60,6 +86,16 @@ const WHEEL_OCTAVES = 0.0015 / Math.LN2
 // turn is the ~0.002 rad/px of Three's PointerLockControls.
 const MOUSE_PX_PER_UNIT = 1500
 
+/**
+ * A pointer gesture as a source. Bound as is, it fires on the primary
+ * button under any modifiers; called with a spec ("Ctrl", "Shift+Alt",
+ * "Right", "Shift+Middle") it is the variant that fires only when the
+ * event opening the gesture carries those modifiers and that button, and
+ * then instead of the bare one: the most specific bound chord wins. The
+ * same spec returns the same source, so unbind by identity works.
+ */
+export type PointerSource<K extends "axis" | "vec2"> = InputSource<K> & ((chord: string) => InputSource<K>)
+
 export interface PointerFeed {
   /** Spread on the element whose pointer events feed the sources. */
   handlers: {
@@ -70,20 +106,20 @@ export interface PointerFeed {
     onWheel(event: WheelEvent): void
   }
   /** One pointer's travel, in element heights; bracketed. */
-  drag: InputSource<"vec2">
+  drag: PointerSource<"vec2">
   /** Two or more pointers' focal travel, in element heights; bracketed. */
-  pan: InputSource<"vec2">
+  pan: PointerSource<"vec2">
   /** Span change of two pointers, in octaves (spreading positive), with
    * the focal point; bracketed. */
-  pinch: InputSource<"axis">
+  pinch: PointerSource<"axis">
   /** Rotation of the pointer pair, in turns, with the focal point; bracketed. */
-  twist: InputSource<"axis">
+  twist: PointerSource<"axis">
   /** Wheel notches in octaves (wheel up positive), with the cursor as the
    * focal point; unbracketed. */
-  wheel: InputSource<"axis">
+  wheel: PointerSource<"axis">
   /** Raw mouse motion while the pointer is locked, in view-height
    * equivalents (see MOUSE_PX_PER_UNIT); unbracketed. */
-  mouseDelta: InputSource<"vec2">
+  mouseDelta: PointerSource<"vec2">
 }
 
 export interface PointerFeedOptions {
@@ -93,33 +129,86 @@ export interface PointerFeedOptions {
   layout?: () => { width: number; height: number } | null
 }
 
-type Sinks = Set<DeltaSink>
+// Button names a bracketed spec may end in, to the event's button index.
+const BUTTONS: Record<string, number> = { Left: 0, Middle: 1, Right: 2 }
+const PRIMARY = 0
 
-function source<K extends "axis" | "vec2">(kind: K, label: string, sinks: Sinks): InputSource<K> {
-  return {
-    kind,
-    label,
-    deltas(sink) {
-      sinks.add(sink)
-      return () => {
-        sinks.delete(sink)
+// One gesture's sinks, bucketed by spec (the bare source is the empty
+// chord on the primary button). A bracket opens the buckets of the
+// button that opened it whose modifiers the opening event carries,
+// narrowed to the most specific among those with a sink bound, and
+// delivers to them until it closes; an unbracketed send resolves the
+// same way per event. Sinks are live sets, as before chords: a consumer
+// bound mid-gesture joins it.
+type Bucket = { mods: Modifier[]; button: number; sinks: Set<DeltaSink>; source: InputSource }
+
+function gesture<K extends "axis" | "vec2">(kind: K, label: string, buttons: boolean) {
+  let buckets = new Map<string, Bucket>()
+  let open: Set<DeltaSink>[] = []
+  let variant = (mods: Modifier[], button: number): InputSource<K> => {
+    let name = [chordName(mods), button === PRIMARY ? "" : Object.keys(BUTTONS)[button]!].filter(Boolean).join("+")
+    let bucket = buckets.get(name)
+    if (!bucket) {
+      let sinks = new Set<DeltaSink>()
+      let source: InputSource<K> = {
+        kind,
+        label: name ? `${label} (${name})` : label,
+        deltas(sink) {
+          sinks.add(sink)
+          return () => {
+            sinks.delete(sink)
+          }
+        },
       }
+      bucket = { mods, button, sinks, source }
+      buckets.set(name, bucket)
+    }
+    return bucket.source as InputSource<K>
+  }
+  let bare = variant([], PRIMARY)
+  let spec = (text: string): InputSource<K> => {
+    if (typeof text !== "string" || text.length === 0) throw new Error(`${label}: expected a spec such as "Ctrl", "Shift+Alt"${buttons ? ', "Right" or "Shift+Middle"' : ""}, got ${String(text)}`)
+    let parts = text.split("+")
+    let button = PRIMARY
+    if (parts[parts.length - 1]! in BUTTONS) {
+      if (!buttons) throw new Error(`${label}: has no button, but "${text}" names one`)
+      button = BUTTONS[parts.pop()!]!
+    }
+    return variant(parseModifiers(label, text, parts), button)
+  }
+  let source: PointerSource<K> = Object.assign(spec, { kind, label: bare.label, deltas: bare.deltas! })
+  let resolve = (event: Modified, button: number): Set<DeltaSink>[] =>
+    mostSpecific(
+      [...buckets.values()].filter(b => b.sinks.size > 0 && b.button === button),
+      b => b.mods,
+      event,
+    ).map(b => b.sinks)
+  return {
+    source,
+    begin(event: Modified, button: number) {
+      open = resolve(event, button)
+      for (let sinks of open) sinks.forEach(k => k.begin())
+    },
+    delta(value: number | Vec2, focal?: Vec2) {
+      for (let sinks of open) sinks.forEach(k => k.delta(value, focal))
+    },
+    end() {
+      for (let sinks of open) sinks.forEach(k => k.end())
+      open = []
+    },
+    send(event: Modified, value: number | Vec2, focal?: Vec2) {
+      for (let sinks of resolve(event, PRIMARY)) sinks.forEach(k => k.delta(value, focal))
     },
   }
 }
 
 export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed {
-  let sinks = {
-    drag: new Set<DeltaSink>(),
-    pan: new Set<DeltaSink>(),
-    pinch: new Set<DeltaSink>(),
-    twist: new Set<DeltaSink>(),
-    wheel: new Set<DeltaSink>(),
-    mouseDelta: new Set<DeltaSink>(),
-  }
-  let begin = (s: Sinks) => s.forEach(k => k.begin())
-  let end = (s: Sinks) => s.forEach(k => k.end())
-  let delta = (s: Sinks, value: number | Vec2, focal?: Vec2) => s.forEach(k => k.delta(value, focal))
+  let drag = gesture("vec2", "pointer drag", true)
+  let pan = gesture("vec2", "pointer two-finger pan", true)
+  let pinch = gesture("axis", "pointer pinch", true)
+  let twist = gesture("axis", "pointer twist", true)
+  let wheel = gesture("axis", "pointer wheel", false)
+  let mouseDelta = gesture("vec2", "mouse motion (pointer locked)", false)
 
   // The element's box, read at each press (see the header). A detached
   // leaf has no layout box and must bring `layout`: normalizing by
@@ -138,76 +227,80 @@ export function createPointerFeed(options: PointerFeedOptions = {}): PointerFeed
   let focalOf = (x: number, y: number): Vec2 | undefined => (box.width > 0 && box.height > 0 ? [x / box.width, y / box.height] : undefined)
 
   let transform = createTransform({
+    buttons: "any",
     onTransformMove: t => {
       let h = unit()
       let travel: Vec2 = [t.dx / h, t.dy / h]
       if (t.pointers >= 2) {
-        if (t.dx !== 0 || t.dy !== 0) delta(sinks.pan, travel)
+        if (t.dx !== 0 || t.dy !== 0) pan.delta(travel)
         let focal = focalOf(t.x, t.y)
-        if (t.scale !== 1) delta(sinks.pinch, Math.log2(t.scale), focal)
-        if (t.rotation !== 0) delta(sinks.twist, t.rotation / (2 * Math.PI), focal)
+        if (t.scale !== 1) pinch.delta(Math.log2(t.scale), focal)
+        if (t.rotation !== 0) twist.delta(t.rotation / (2 * Math.PI), focal)
       } else if (t.dx !== 0 || t.dy !== 0) {
-        delta(sinks.drag, travel)
+        drag.delta(travel)
       }
     },
   })
 
-  // Pointers down on the element, for the gesture brackets: the first
-  // press opens drag, a second closes it and opens the two-pointer
-  // gestures, and the count coming back down reverses that.
-  let downs = new Set<number>()
-  let landed = (id: number) => {
-    if (downs.has(id)) return
-    downs.add(id)
-    if (downs.size === 1) begin(sinks.drag)
+  // Pointers down on the element with the button that pressed them, for
+  // the gesture brackets: the first press opens drag, a second closes it
+  // and opens the two-pointer gestures, and the count coming back down
+  // reverses that. The event that opens a bracket resolves its chord,
+  // and the pointer it opens for supplies the button (the drag that
+  // resumes when a second pointer lifts belongs to the one still down).
+  let downs = new Map<number, number>()
+  let landed = (e: PointerEvent, button: number) => {
+    downs.set(e.pointerId, button)
+    if (downs.size === 1) drag.begin(e, button)
     if (downs.size === 2) {
-      end(sinks.drag)
-      begin(sinks.pan)
-      begin(sinks.pinch)
-      begin(sinks.twist)
+      drag.end()
+      pan.begin(e, button)
+      pinch.begin(e, button)
+      twist.begin(e, button)
     }
   }
-  let lifted = (id: number) => {
-    if (!downs.delete(id)) return
+  let lifted = (e: PointerEvent) => {
+    downs.delete(e.pointerId)
     if (downs.size === 1) {
-      end(sinks.pan)
-      end(sinks.pinch)
-      end(sinks.twist)
-      begin(sinks.drag)
+      pan.end()
+      pinch.end()
+      twist.end()
+      drag.begin(e, [...downs.values()][0]!)
     }
-    if (downs.size === 0) end(sinks.drag)
+    if (downs.size === 0) drag.end()
   }
 
   return {
     handlers: {
       onPointerDown(e) {
-        if (e.button != null && e.button !== 0) return
+        if (downs.has(e.pointerId)) return
         if (downs.size === 0) box = size(e)
-        landed(e.pointerId)
+        landed(e, e.button ?? PRIMARY)
         transform.handlers.onPointerDown(e)
       },
       onPointerMove(e) {
         if (pointerLocked() && e.pointerType === "mouse" && (e.movementX !== 0 || e.movementY !== 0)) {
-          delta(sinks.mouseDelta, [e.movementX / MOUSE_PX_PER_UNIT, e.movementY / MOUSE_PX_PER_UNIT])
+          mouseDelta.send(e, [e.movementX / MOUSE_PX_PER_UNIT, e.movementY / MOUSE_PX_PER_UNIT])
         }
         transform.handlers.onPointerMove(e)
       },
       onPointerUp(e) {
+        if (downs.get(e.pointerId) !== (e.button ?? PRIMARY)) return
         transform.handlers.onPointerUp(e)
-        lifted(e.pointerId)
+        lifted(e)
       },
       onPointerLeave() {},
       onWheel(e) {
         if (e.deltaY === 0) return
         box = size(e)
-        delta(sinks.wheel, -e.deltaY * WHEEL_OCTAVES, focalOf(e.localX, e.localY))
+        wheel.send(e, -e.deltaY * WHEEL_OCTAVES, focalOf(e.localX, e.localY))
       },
     },
-    drag: source("vec2", "pointer drag", sinks.drag),
-    pan: source("vec2", "pointer two-finger pan", sinks.pan),
-    pinch: source("axis", "pointer pinch", sinks.pinch),
-    twist: source("axis", "pointer twist", sinks.twist),
-    wheel: source("axis", "pointer wheel", sinks.wheel),
-    mouseDelta: source("vec2", "mouse motion (pointer locked)", sinks.mouseDelta),
+    drag: drag.source,
+    pan: pan.source,
+    pinch: pinch.source,
+    twist: twist.source,
+    wheel: wheel.source,
+    mouseDelta: mouseDelta.source,
   }
 }

package/src/transform.ts

@@ -47,6 +47,9 @@ export type TransformDelta = {
 }
 
 export interface TransformOptions {
+  /** Which mouse buttons open a gesture: the primary only (default), or
+   * any - the pointer feed's choice, which tells its buttons apart itself. */
+  buttons?: "primary" | "any"
   onTransformStart?: () => void
   /** Streams one delta per frame; compose them multiplicatively (scale) / additively (dx, dy, rotation). */
   onTransformMove?: (t: TransformDelta) => void
@@ -251,7 +254,7 @@ export function createTransform(options: TransformOptions) {
 
   let handlers = {
     onPointerDown: (e: PointerEvent) => {
-      if (e.button != null && e.button !== 0) return
+      if (options.buttons !== "any" && e.button != null && e.button !== 0) return
       if (pointers.has(e.pointerId)) return
       if (active) {
         // A finger joining an established gesture belongs to it outright; if