@pascal-app/editor 1.0.1 → 1.0.4

package/src/lib/keyboard-pan.test.ts

@@ -0,0 +1,184 @@
+import { afterAll, beforeAll, expect, test } from 'bun:test'
+import {
+  acceptsKeyboardPan,
+  advanceKeyboardPanMotion,
+  clearKeyboardPanKeys,
+  createKeyboardPanMotion,
+  hasKeyboardPanInput,
+  isKeyboardPanKey,
+  KEYBOARD_PAN_RAMP_SECONDS,
+  KEYBOARD_PAN_START_FRACTION,
+  KEYBOARD_PAN_STOP_SECONDS,
+  type KeyboardPanState,
+  keyboardPanSpeed,
+  setKeyboardPanKey,
+  syncKeyboardPanMotion,
+} from './keyboard-pan'
+
+const idle = (): KeyboardPanState => ({
+  forward: false,
+  backward: false,
+  left: false,
+  right: false,
+})
+
+/**
+ * Frames every `1000 / hz` ms from `phaseMs`; `codes` go down at `pressMs` and
+ * up `holdMs` later, synced at the edges like the views do. Returns the total
+ * travel in cruise-seconds and how long the glide lasted.
+ */
+function simulate({
+  codes = ['KeyD'],
+  holdMs,
+  hz = 60,
+  phaseMs = 0,
+  pressMs = 1000,
+}: {
+  codes?: string[]
+  holdMs: number
+  hz?: number
+  phaseMs?: number
+  pressMs?: number
+}) {
+  const motion = createKeyboardPanMotion()
+  const keys = idle()
+  const releaseMs = pressMs + holdMs
+  let x = 0
+  let y = 0
+  let pressed = false
+  let released = false
+  let restMs = releaseMs
+  for (let now = phaseMs; now < releaseMs + 2000; now += 1000 / hz) {
+    if (!pressed && now >= pressMs) {
+      syncKeyboardPanMotion(motion, keys, pressMs)
+      for (const code of codes) setKeyboardPanKey(keys, code, true)
+      pressed = true
+    }
+    if (!released && now >= releaseMs) {
+      syncKeyboardPanMotion(motion, keys, releaseMs)
+      clearKeyboardPanKeys(keys)
+      released = true
+    }
+    if (advanceKeyboardPanMotion(motion, keys, now)) restMs = now
+    x += motion.stepX
+    y += motion.stepY
+  }
+  return { x, y, glideMs: restMs - releaseMs, motion }
+}
+
+const key = (init: Partial<KeyboardEvent>) => ({ target: null, ...init }) as KeyboardEvent
+
+// No DOM in this runner: stand in for the element classes the editable check reads.
+const DOM_CLASSES = ['HTMLElement', 'HTMLInputElement', 'HTMLTextAreaElement', 'HTMLSelectElement']
+const stubbed: string[] = []
+beforeAll(() => {
+  const scope = globalThis as Record<string, unknown>
+  for (const name of DOM_CLASSES) {
+    if (scope[name]) continue
+    scope[name] = class {}
+    stubbed.push(name)
+  }
+})
+afterAll(() => {
+  for (const name of stubbed) delete (globalThis as Record<string, unknown>)[name]
+})
+
+test('physical WASD keys drive a screen-space direction; letters on other layouts do not', () => {
+  const state = idle()
+  expect(isKeyboardPanKey('KeyZ')).toBe(false)
+  expect(setKeyboardPanKey(state, 'KeyW', true)).toBe(true)
+  expect(setKeyboardPanKey(state, 'KeyW', true)).toBe(false)
+  setKeyboardPanKey(state, 'KeyD', true)
+  const motion = createKeyboardPanMotion()
+  syncKeyboardPanMotion(motion, state, 0)
+  advanceKeyboardPanMotion(motion, state, 100)
+  expect(motion.stepX).toBeGreaterThan(0)
+  expect(motion.stepY).toBeCloseTo(motion.stepX)
+  setKeyboardPanKey(state, 'KeyA', true)
+  advanceKeyboardPanMotion(motion, state, 200)
+  expect(motion.stepX).toBe(0)
+  expect(motion.stepY).toBeGreaterThan(0)
+  clearKeyboardPanKeys(state)
+  expect(hasKeyboardPanInput(state)).toBe(false)
+})
+
+test('modifier chords stay shortcuts, and typing in a field never pans', () => {
+  expect(acceptsKeyboardPan(key({}))).toBe(true)
+  for (const modifier of ['metaKey', 'ctrlKey', 'altKey'] as const)
+    expect(acceptsKeyboardPan(key({ [modifier]: true }))).toBe(false)
+  const Input = (globalThis as unknown as { HTMLInputElement: new () => EventTarget })
+    .HTMLInputElement
+  expect(acceptsKeyboardPan(key({ target: new Input() }))).toBe(false)
+})
+
+test('cruise speed scales with the visible width within fixed bounds', () => {
+  expect(keyboardPanSpeed(0)).toBe(0.5)
+  expect(keyboardPanSpeed(20)).toBeCloseTo(6)
+  expect(keyboardPanSpeed(1000)).toBe(30)
+})
+
+test('a press starts just under cruise and reaches it within the ramp', () => {
+  const at = (holdSeconds: number) => {
+    const motion = createKeyboardPanMotion()
+    syncKeyboardPanMotion(motion, idle(), 0)
+    advanceKeyboardPanMotion(motion, { ...idle(), right: true }, holdSeconds * 1000)
+    return motion.velocityX
+  }
+  expect(at(0.001)).toBeCloseTo(KEYBOARD_PAN_START_FRACTION, 2)
+  expect(at(KEYBOARD_PAN_RAMP_SECONDS / 2)).toBeGreaterThan(KEYBOARD_PAN_START_FRACTION)
+  expect(at(KEYBOARD_PAN_RAMP_SECONDS / 2)).toBeLessThan(1)
+  expect(at(KEYBOARD_PAN_RAMP_SECONDS)).toBe(1)
+})
+
+test('a tap moves a small, predictable amount and a hold travels at cruise', () => {
+  // 100 ms ramping up from the start fraction, plus a short glide.
+  const tap = simulate({ holdMs: 100 }).x
+  expect(tap).toBeGreaterThan(0.1 * KEYBOARD_PAN_START_FRACTION)
+  expect(tap).toBeLessThan(0.1)
+  const hold = simulate({ holdMs: 2000 }).x
+  expect(hold).toBeGreaterThan(1.98)
+  expect(hold).toBeLessThan(2.02)
+})
+
+test('a tap counts from the key events, not from the frames around them', () => {
+  const taps = [0, 5, 11, 16].map((phaseMs) => simulate({ holdMs: 100, phaseMs }).x)
+  const slowFrames = [0, 40, 80].map((phaseMs) => simulate({ holdMs: 100, hz: 10, phaseMs }).x)
+  for (const tap of [...taps, ...slowFrames]) expect(tap).toBeCloseTo(taps[0] ?? 0, 2)
+  // Shorter than a frame still moves, by its own length.
+  expect(simulate({ holdMs: 8, phaseMs: 1 }).x).toBeGreaterThan(0.006)
+})
+
+test('release comes to rest within the stop time, with a barely visible glide', () => {
+  const hold = simulate({ codes: ['KeyW'], holdMs: 1000 })
+  expect(hold.glideMs).toBeLessThanOrEqual(KEYBOARD_PAN_STOP_SECONDS * 1000 + 1000 / 60)
+  // Glide under 3% of a cruise-second: about 1% of the view width.
+  const held1s = 1 - ((1 - KEYBOARD_PAN_START_FRACTION) * KEYBOARD_PAN_RAMP_SECONDS) / 3
+  expect(hold.y - held1s).toBeGreaterThan(0)
+  expect(hold.y - held1s).toBeLessThan(0.03)
+  expect(hold.motion.velocityY).toBe(0)
+})
+
+test('travel does not depend on the frame rate', () => {
+  const at60 = simulate({ holdMs: 1000 }).x
+  expect(simulate({ holdMs: 1000, hz: 144 }).x).toBeCloseTo(at60, 3)
+  expect(simulate({ holdMs: 1000, hz: 20 }).x).toBeCloseTo(at60, 2)
+})
+
+test('diagonals move no faster than a straight press', () => {
+  const straight = simulate({ holdMs: 1000 })
+  const diagonal = simulate({ codes: ['KeyD', 'KeyW'], holdMs: 1000 })
+  expect(Math.hypot(diagonal.x, diagonal.y)).toBeCloseTo(straight.x)
+  expect(diagonal.x).toBeCloseTo(diagonal.y)
+})
+
+test('a press during the glide resumes from the current speed', () => {
+  const motion = createKeyboardPanMotion()
+  const right = { ...idle(), right: true }
+  syncKeyboardPanMotion(motion, idle(), 0)
+  syncKeyboardPanMotion(motion, right, 1000)
+  syncKeyboardPanMotion(motion, idle(), 1002)
+  const glidingSpeed = motion.velocityX
+  expect(glidingSpeed).toBeGreaterThan(KEYBOARD_PAN_START_FRACTION)
+  advanceKeyboardPanMotion(motion, right, 1003)
+  expect(motion.velocityX).toBeGreaterThanOrEqual(glidingSpeed)
+})

package/src/lib/keyboard-pan.ts

@@ -0,0 +1,238 @@
+// WASD navigation shared by the 3D camera and the 2D floor plan, so both views
+// move the same way. Keys match by physical position (`event.code`): the
+// cluster stays under the left hand on any layout (Z/Q/S/D on AZERTY).
+
+export type KeyboardPanState = {
+  forward: boolean
+  backward: boolean
+  left: boolean
+  right: boolean
+}
+
+// Tuning. Speeds are in visible view widths per second, so a pan feels the
+// same at any zoom; the world-unit clamps only bite on tiny or huge views.
+/** Cruise speed once a key is held, in view widths per second. */
+export const KEYBOARD_PAN_CRUISE_VIEW_WIDTHS_PER_SECOND = 0.3
+/** Share of cruise speed a fresh press starts at. */
+export const KEYBOARD_PAN_START_FRACTION = 0.55
+/** Seconds of holding to reach cruise speed. */
+export const KEYBOARD_PAN_RAMP_SECONDS = 0.22
+/** Seconds to come to rest after the last key is released. */
+export const KEYBOARD_PAN_STOP_SECONDS = 0.09
+const KEYBOARD_PAN_MIN_SPEED = 0.5
+const KEYBOARD_PAN_MAX_SPEED = 30
+// A stalled frame (tab switch, long task) must not turn into one big jump.
+const KEYBOARD_PAN_MAX_STEP_SECONDS = 0.25
+// Release decays exponentially; three time constants leave 5%, then it snaps to rest.
+const KEYBOARD_PAN_STOP_TIME_CONSTANT = KEYBOARD_PAN_STOP_SECONDS / 3
+const KEYBOARD_PAN_REST_FRACTION = 0.05
+
+export function isEditableKeyboardTarget(target: EventTarget | null) {
+  return (
+    target instanceof HTMLInputElement ||
+    target instanceof HTMLTextAreaElement ||
+    target instanceof HTMLSelectElement ||
+    (target instanceof HTMLElement && target.isContentEditable)
+  )
+}
+
+export function setKeyboardPanKey(
+  state: KeyboardPanState,
+  code: string,
+  pressed: boolean,
+): boolean {
+  if (code === 'KeyW') {
+    const changed = state.forward !== pressed
+    state.forward = pressed
+    return changed
+  }
+  if (code === 'KeyS') {
+    const changed = state.backward !== pressed
+    state.backward = pressed
+    return changed
+  }
+  if (code === 'KeyA') {
+    const changed = state.left !== pressed
+    state.left = pressed
+    return changed
+  }
+  if (code === 'KeyD') {
+    const changed = state.right !== pressed
+    state.right = pressed
+    return changed
+  }
+  return false
+}
+
+export function isKeyboardPanKey(code: string): boolean {
+  return code === 'KeyW' || code === 'KeyA' || code === 'KeyS' || code === 'KeyD'
+}
+
+export function hasKeyboardPanInput(state: KeyboardPanState): boolean {
+  return state.forward || state.backward || state.left || state.right
+}
+
+export function clearKeyboardPanKeys(state: KeyboardPanState) {
+  state.forward = false
+  state.backward = false
+  state.left = false
+  state.right = false
+}
+
+/** Pan keys are ignored with a modifier held (shortcuts) or while typing. */
+export function acceptsKeyboardPan(event: KeyboardEvent) {
+  return (
+    !(event.metaKey || event.ctrlKey || event.altKey) && !isEditableKeyboardTarget(event.target)
+  )
+}
+
+/** Cruise speed, in world units per second, for a view `viewWidth` wide. */
+export function keyboardPanSpeed(viewWidth: number) {
+  return Math.min(
+    Math.max(viewWidth * KEYBOARD_PAN_CRUISE_VIEW_WIDTHS_PER_SECOND, KEYBOARD_PAN_MIN_SPEED),
+    KEYBOARD_PAN_MAX_SPEED,
+  )
+}
+
+/**
+ * Per-view motion carried between frames. Velocity and step are screen space
+ * (+x right, +y forward) in shares of cruise speed; multiply the step by
+ * `keyboardPanSpeed` for world units.
+ */
+export type KeyboardPanMotion = {
+  holding: boolean
+  /** Time on the ramp's clock, so a press during the glide resumes its speed. */
+  heldSeconds: number
+  velocityX: number
+  velocityY: number
+  /** This frame's travel, in cruise-seconds. */
+  stepX: number
+  stepY: number
+  // Travel integrated at key edges since the last frame.
+  pendingX: number
+  pendingY: number
+  /** `performance.now()` the motion was last advanced to; null before the first press. */
+  time: number | null
+}
+
+export function createKeyboardPanMotion(): KeyboardPanMotion {
+  return {
+    holding: false,
+    heldSeconds: 0,
+    velocityX: 0,
+    velocityY: 0,
+    stepX: 0,
+    stepY: 0,
+    pendingX: 0,
+    pendingY: 0,
+    time: null,
+  }
+}
+
+export function resetKeyboardPanMotion(motion: KeyboardPanMotion) {
+  motion.holding = false
+  motion.heldSeconds = 0
+  motion.velocityX = 0
+  motion.velocityY = 0
+  motion.stepX = 0
+  motion.stepY = 0
+  motion.pendingX = 0
+  motion.pendingY = 0
+  motion.time = null
+}
+
+// Speed eases out of the start fraction into cruise: s(u) = S + (1 - S)(2u - u²), u = t / ramp.
+const rampSpeed = (seconds: number) => {
+  const u = Math.min(seconds / KEYBOARD_PAN_RAMP_SECONDS, 1)
+  return KEYBOARD_PAN_START_FRACTION + (1 - KEYBOARD_PAN_START_FRACTION) * (2 * u - u * u)
+}
+
+// ∫₀ᵗ s, exact, so the distance does not depend on the frame rate.
+const rampDistance = (seconds: number) => {
+  const u = seconds / KEYBOARD_PAN_RAMP_SECONDS
+  const eased = u < 1 ? u * u - (u * u * u) / 3 : u - 1 / 3
+  return (
+    KEYBOARD_PAN_START_FRACTION * seconds +
+    (1 - KEYBOARD_PAN_START_FRACTION) * KEYBOARD_PAN_RAMP_SECONDS * eased
+  )
+}
+
+const rampSecondsForSpeed = (speed: number) => {
+  const eased = (speed - KEYBOARD_PAN_START_FRACTION) / (1 - KEYBOARD_PAN_START_FRACTION)
+  if (eased <= 0) return 0
+  if (eased >= 1) return KEYBOARD_PAN_RAMP_SECONDS
+  return KEYBOARD_PAN_RAMP_SECONDS * (1 - Math.sqrt(1 - eased))
+}
+
+/**
+ * Integrates `motion` up to `now` (`performance.now()`) under `keys`. Call it
+ * with the keys as they were just before one changes, so a press or release
+ * counts from the moment it happened rather than from the next frame.
+ */
+export function syncKeyboardPanMotion(
+  motion: KeyboardPanMotion,
+  keys: KeyboardPanState,
+  now: number,
+) {
+  const elapsed = motion.time === null ? 0 : (now - motion.time) / 1000
+  motion.time = motion.time === null ? now : Math.max(motion.time, now)
+  const dt = Math.min(Math.max(elapsed, 0), KEYBOARD_PAN_MAX_STEP_SECONDS)
+  const horizontal = (keys.right ? 1 : 0) - (keys.left ? 1 : 0)
+  const vertical = (keys.forward ? 1 : 0) - (keys.backward ? 1 : 0)
+
+  if (horizontal !== 0 || vertical !== 0) {
+    if (!motion.holding) {
+      motion.holding = true
+      motion.heldSeconds = rampSecondsForSpeed(Math.hypot(motion.velocityX, motion.velocityY))
+    }
+    const from = motion.heldSeconds
+    motion.heldSeconds = from + dt
+    // Diagonals travel at the same speed as straight moves.
+    const length = Math.hypot(horizontal, vertical)
+    const distance = rampDistance(motion.heldSeconds) - rampDistance(from)
+    const speed = rampSpeed(motion.heldSeconds)
+    motion.pendingX += (horizontal / length) * distance
+    motion.pendingY += (vertical / length) * distance
+    motion.velocityX = (horizontal / length) * speed
+    motion.velocityY = (vertical / length) * speed
+    return
+  }
+
+  motion.holding = false
+  motion.heldSeconds = 0
+  if (motion.velocityX === 0 && motion.velocityY === 0) return
+  const decay = Math.exp(-dt / KEYBOARD_PAN_STOP_TIME_CONSTANT)
+  const glide = KEYBOARD_PAN_STOP_TIME_CONSTANT * (1 - decay)
+  motion.pendingX += motion.velocityX * glide
+  motion.pendingY += motion.velocityY * glide
+  motion.velocityX *= decay
+  motion.velocityY *= decay
+  if (Math.hypot(motion.velocityX, motion.velocityY) < KEYBOARD_PAN_REST_FRACTION) {
+    motion.velocityX = 0
+    motion.velocityY = 0
+  }
+}
+
+/**
+ * Once per frame: syncs `motion` to `now` and leaves the travel since the
+ * last frame in `stepX`/`stepY`. Returns false once the
+ * view is at rest with nothing left to apply.
+ */
+export function advanceKeyboardPanMotion(
+  motion: KeyboardPanMotion,
+  keys: KeyboardPanState,
+  now: number,
+): boolean {
+  syncKeyboardPanMotion(motion, keys, now)
+  motion.stepX = motion.pendingX
+  motion.stepY = motion.pendingY
+  motion.pendingX = 0
+  motion.pendingY = 0
+  return (
+    motion.holding ||
+    motion.velocityX !== 0 ||
+    motion.velocityY !== 0 ||
+    motion.stepX !== 0 ||
+    motion.stepY !== 0
+  )
+}