@tremolo-ui/dom 0.7.0 → 0.8.0

package/src/number-input/stepper-drag.ts

@@ -0,0 +1,139 @@
+import { type ValueRange } from '@tremolo-ui/functions'
+
+import { applyDelta } from '../input/apply-delta'
+import { DEFAULT_DRAG_SENSITIVITY } from '../input/defaults'
+import {
+  mapModifier,
+  selectModifier,
+  type InputEventOption,
+  type ModifierValue,
+} from '../input/modifiers'
+import { createDrag } from '../pointer/drag'
+
+export interface StepperDragOptions {
+  /** The value now, read when the drag starts moving it. */
+  getValue: () => number
+  /**
+   * The range the value moves across. Its `step` is what one step of the drag
+   * is worth; see `numberInputRanges` for the one a number input uses.
+   */
+  range: ValueRange
+  /**
+   * How many pixels of vertical movement make one step.
+   *
+   * @default 1
+   */
+  pixels?: number
+  /**
+   * How much a step is worth, per modifier key: `0.1` makes the same movement
+   * count a tenth as much. Pressing or releasing the key mid-drag does not
+   * move the value.
+   *
+   * @default { default: 1, shift: 0.1 }
+   */
+  sensitivity?: ModifierValue<number>
+  /** Hide the pointer and keep it from hitting the edge of the screen. */
+  pointerLock?: boolean
+  /** Called with the new value whenever the drag moves it. */
+  onChange: (value: number) => void
+}
+
+export interface StepperDragInstance {
+  /** Replace the given options. `pointerLock` reaches the next drag. */
+  update: (options: Partial<StepperDragOptions>) => void
+  /**
+   * Whether the drag in progress has moved the value. A stepper button's
+   * press-and-hold repeat stands down once it has, so the value is not moved
+   * twice.
+   */
+  moved: () => boolean
+  destroy: () => void
+}
+
+/**
+ * Drag up and down on the steppers of a number input to move its value, one
+ * `step` every `pixels` — up raises it, as on a knob.
+ *
+ * Counted from where the drag started moving rather than added up per
+ * event, so rounding cannot accumulate. The start is taken on the first
+ * move, not on pointerdown: a stepper button acts on pointerdown, so by then
+ * the value may already have been nudged once, and the drag carries on from
+ * there.
+ */
+export function createStepperDrag(
+  element: Element,
+  options: StepperDragOptions,
+): StepperDragInstance {
+  let opts = options
+  let origin: { y: number; value: number } | null = null
+  let moved = false
+  /**
+   * Which sensitivity the drag is counting at, and where the previous event
+   * was — a key produces no pointer event of its own, so a change is only
+   * seen on the next move and has to be dated back to the one before it.
+   */
+  let factor = 1
+  let previousY = 0
+
+  const drag = createDrag(element, {
+    threshold: 1,
+    cursor: 'ns-resize',
+    pointerLock: opts.pointerLock,
+    onDragStart: (state) => {
+      origin = null
+      moved = false
+      factor = selectModifier(
+        opts.sensitivity ?? DEFAULT_DRAG_SENSITIVITY,
+        state.event,
+      ).value
+    },
+    onDrag: (state) => {
+      const { y } = state
+      if (!origin) {
+        origin = { y, value: opts.getValue() }
+        previousY = y
+        return
+      }
+
+      const sensitivity = opts.sensitivity ?? DEFAULT_DRAG_SENSITIVITY
+      // Pressing or releasing the key mid-drag must not move the value, so the
+      // travel so far is folded into the origin and measuring starts again
+      // from the previous event: that event's own distance belongs to the new
+      // sensitivity.
+      const next = selectModifier(sensitivity, state.event).value
+      if (next !== factor) {
+        origin = { y: previousY, value: opts.getValue() }
+        factor = next
+      }
+      previousY = y
+
+      const steps = Math.round(-(y - origin.y) / (opts.pixels ?? 1))
+      if (steps === 0) return
+      moved = true
+
+      // The sensitivity as an amount per step, carried over as a modifier map
+      // rather than resolved here: that keeps `step` out of the pipeline for
+      // a modifier entry, since naming one is a request to move off the grid.
+      const step = opts.range.step ?? 1
+      const amounts = mapModifier(sensitivity, (f): InputEventOption => [
+        'raw',
+        step * f,
+      ])
+      opts.onChange(
+        applyDelta(origin.value, steps, amounts, opts.range, state.event),
+      )
+    },
+    onDragEnd: () => {
+      moved = false
+    },
+  })
+
+  return {
+    update: (next) => {
+      opts = { ...opts, ...next }
+      if ('pointerLock' in next) drag.update({ pointerLock: opts.pointerLock })
+    },
+    moved: () => moved,
+    destroy: () => drag.destroy(),
+  }
+}

package/src/number-input/text.ts

@@ -0,0 +1,100 @@
+/**
+ * Reading a number out of the text of a number input, and keeping the caret
+ * in place while the number under it changes.
+ *
+ * The text is whatever `format` made of the value — `"440 Hz"`, `"-6.0 dB"` —
+ * or a half-typed entry, so none of this assumes the text is a number alone.
+ */
+
+/** The signs a number can carry. U+2212 is what some `Intl.NumberFormat` locales write. */
+const SIGNS = '+-\u2212'
+
+/** Where the number is in the text; the rest, on either side, is the unit. */
+export interface NumberSpan {
+  start: number
+  end: number
+}
+
+/**
+ * Where the number is in the text: from its first digit to its last, with the
+ * sign and the decimal point in front of it. Whatever is left on either side
+ * is taken for the unit, so it does not matter whether a space separates them,
+ * or what the number looks like — `+6.0`, `1e+21`, `1,000` and `1:30` are each
+ * one number. `null` when the text has no digit at all.
+ */
+export function numberSpan(text: string): NumberSpan | null {
+  const first = text.search(/\d/)
+  if (first === -1) return null
+  let start = first
+  if (text[start - 1] === '.') start -= 1
+  if (start > 0 && SIGNS.includes(text[start - 1])) start -= 1
+  return { start, end: text.search(/\d\D*$/) + 1 }
+}
+
+/** A plain number, and nothing else: no grouping, no other separators. */
+const PLAIN_NUMBER =
+  /^[+\-\u2212]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+\-\u2212]?\d+)?$/
+
+/**
+ * The number in the text, with the unit after it ignored: the default `parse`
+ * of a number input.
+ *
+ * `NaN`, which leaves the value alone, whenever the number cannot be read
+ * safely, rather than a part of it: text with no number, a number that is not
+ * a plain one (`1,000` would otherwise read as 1, and `1:30` as 1), and text
+ * with something in front of the number, which can change what it means (the
+ * `L` of a pan reading `L 30`). A `format` that writes any of those needs its
+ * own `parse`.
+ */
+export function parseNumberText(text: string): number {
+  const span = numberSpan(text)
+  if (!span || text.slice(0, span.start).trim() !== '') return NaN
+  const number = text.slice(span.start, span.end)
+  return PLAIN_NUMBER.test(number)
+    ? Number(number.replace(/\u2212/g, '-'))
+    : NaN
+}
+
+/**
+ * The index the caret is measured against: the decimal point, or where one
+ * would go if the number has none — in front of an exponent, if there is one.
+ *
+ * Measuring from an end instead would slide the caret across a digit whenever
+ * the number changed length — `9.9` to `10.0` gains a character in front, `10`
+ * to `9` loses one, and so does `9e+9` to `1e+10` behind — which is exactly
+ * what stepping does.
+ */
+function decimalAnchor(text: string, span: NumberSpan) {
+  const number = text.slice(span.start, span.end)
+  const exponent = number.search(/[eE][+\-\u2212]?\d/)
+  const mantissa = exponent === -1 ? number : number.slice(0, exponent)
+  const dot = mantissa.indexOf('.')
+  return span.start + (dot === -1 ? mantissa.length : dot)
+}
+
+const NO_NUMBER: NumberSpan = { start: 0, end: 0 }
+
+/**
+ * Where the caret is, relative to the decimal point, so that it can be put
+ * back at the same digit once the value has changed. See
+ * {@link caretAtDecimalOffset}.
+ */
+export function caretDecimalOffset(text: string, caret: number): number {
+  return caret - decimalAnchor(text, numberSpan(text) ?? NO_NUMBER)
+}
+
+/**
+ * The caret position `offset` characters from the decimal point of the new
+ * text, kept within the number.
+ *
+ * @example
+ * // The caret sits in front of the point of "9.9" when ArrowUp turns it
+ * // into "10.0"
+ * const offset = caretDecimalOffset('9.9', 1) // 0
+ * caretAtDecimalOffset('10.0', offset) // 2: still in front of the point
+ */
+export function caretAtDecimalOffset(text: string, offset: number): number {
+  const span = numberSpan(text) ?? NO_NUMBER
+  const place = decimalAnchor(text, span) + offset
+  return Math.max(span.start, Math.min(place, span.end))
+}

package/src/number-input/value.ts

@@ -0,0 +1,129 @@
+import { type Scale, type ValueRange } from '@tremolo-ui/functions'
+
+import { applyDelta } from '../input/apply-delta'
+import {
+  selectModifier,
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+} from '../input/modifiers'
+
+/**
+ * The value a number input edits, and how far it may go.
+ *
+ * Unlike a slider, either end may be left open, and `clampValue: false` lets
+ * the value past the ends that are set.
+ */
+export interface NumberInputValueOptions {
+  min?: number
+  max?: number
+  step?: number
+  scale?: Scale
+  /**
+   * Keep the value between `min` and `max`.
+   *
+   * @default true
+   */
+  clampValue?: boolean
+}
+
+/** The ranges {@link nudgeNumberInput} moves a value across. */
+export interface NumberInputRanges {
+  /** For a `normalized` amount, which needs a finite span to take a share of. */
+  normalized: ValueRange
+  /** For a `raw` amount, which does not. */
+  raw: ValueRange
+}
+
+/**
+ * The ranges a number input moves its value across, with the open ends
+ * filled in.
+ *
+ * A normalized amount needs a finite span even when an end is unbounded or
+ * clamping is off. Safe integers provide one without overflowing the span a
+ * scale calculates. A raw amount needs no span, so its open ends can cover
+ * every finite number instead of stopping at the safe-integer range.
+ */
+export function numberInputRanges({
+  min,
+  max,
+  step,
+  scale,
+  clampValue = true,
+}: NumberInputValueOptions): NumberInputRanges {
+  const lo = clampValue ? min : undefined
+  const hi = clampValue ? max : undefined
+  return {
+    normalized: {
+      min: lo ?? Number.MIN_SAFE_INTEGER,
+      max: hi ?? Number.MAX_SAFE_INTEGER,
+      step,
+      scale,
+    },
+    raw: {
+      min: lo ?? -Number.MAX_VALUE,
+      max: hi ?? Number.MAX_VALUE,
+      step,
+      scale,
+    },
+  }
+}
+
+/**
+ * Move a number input's value by one press of a key, a wheel notch or a
+ * stepper, picking the range that suits the kind of amount. See `applyDelta`.
+ */
+export function nudgeNumberInput(
+  value: number,
+  direction: number,
+  options: ModifierValue<InputEventOption>,
+  ranges: NumberInputRanges,
+  modifiers?: ModifierState,
+): number {
+  const [mode] = selectModifier(options, modifiers).value
+  return applyDelta(
+    value,
+    direction,
+    options,
+    mode === 'raw' ? ranges.raw : ranges.normalized,
+    modifiers,
+  )
+}
+
+/**
+ * Where the value stands against the ends: whether it can go no further
+ * down or up, and whether it lies outside them — which only an unclamped
+ * input, or a value set from outside, can do.
+ */
+export function numberInputBounds(
+  value: number,
+  { min, max, clampValue = true }: NumberInputValueOptions,
+) {
+  return {
+    atMin: clampValue && min !== undefined && value <= min,
+    atMax: clampValue && max !== undefined && value >= max,
+    outOfRange:
+      (min !== undefined && value < min) || (max !== undefined && value > max),
+  }
+}
+
+/**
+ * The value typed text commits to, or `null` when there is no number in it.
+ *
+ * Text with no number is not a value: the input should go back to what it
+ * was showing rather than commit a zero the user never typed. What is read
+ * is clamped here and not while typing, since clamping as the user types
+ * would make "1500" impossible to enter into an input whose max is 100.
+ */
+export function commitNumberInputText(
+  text: string,
+  parse: (text: string) => number,
+  { min, max, clampValue = true }: NumberInputValueOptions,
+): number | null {
+  const parsed = parse(text)
+  if (!Number.isFinite(parsed)) return null
+  let committed = parsed
+  if (clampValue && min !== undefined) committed = Math.max(committed, min)
+  if (clampValue && max !== undefined) committed = Math.min(committed, max)
+  return committed
+}

package/src/options/replace.ts

@@ -0,0 +1,22 @@
+/**
+ * The `update()` argument that leaves an instance with exactly `next` as its
+ * options.
+ *
+ * `update()` merges into what the instance has, which suits a wrapper that
+ * pushes one setting at a time. A wrapper handed the whole new set instead —
+ * a Svelte action, a Vue composable — has to clear what the new set no longer
+ * carries, or a handler taken away, or an option left to its default, keeps
+ * working.
+ *
+ * @example
+ * instance.update(replaceOptions(previous, next))
+ */
+export function replaceOptions<T extends object>(
+  previous: T | undefined,
+  next: T | undefined,
+): Partial<T> {
+  const cleared = Object.fromEntries(
+    Object.keys(previous ?? {}).map((key) => [key, undefined]),
+  ) as Partial<T>
+  return { ...cleared, ...next }
+}

package/src/piano/index.ts

@@ -1,6 +1,11 @@
 import { createDrag } from '../pointer/drag'
 
 import { noteAt, type PianoLayout } from './layout'
+import {
+  isEditableTarget,
+  type KeyboardShortcuts,
+  type KeyboardShortcutsScope,
+} from './shortcuts'
 
 /**
  * What asked for a note to sound.
@@ -33,6 +38,26 @@ export interface PianoInputOptions {
    */
   midiMax?: number
 
+  /**
+   * Play notes from the computer keyboard: `keys[i]` plays
+   * `layout.noteRange.first + i`. `SHORTCUTS` has ready-made layouts.
+   *
+   * A held key keeps its note until it is released, the focus leaves (with
+   * `root`), or the window loses focus. Changing the keys, the scope or the
+   * note range releases every note a key is holding, since the key would
+   * mean something else on release.
+   */
+  keyboardShortcuts?: KeyboardShortcuts
+
+  /**
+   * Where keyboard shortcuts listen: on the element (`root`), which has to
+   * be focusable, or anywhere on the page (`window`). Keys typed into an
+   * editable element are ignored either way.
+   *
+   * @default 'root'
+   */
+  keyboardShortcutsScope?: KeyboardShortcutsScope
+
   /** Called when a note starts sounding, not for each source that asks. */
   onPlayNote?: (note: number, velocity?: number) => void
   /** Called once the last source holding a note has let go. */
@@ -49,8 +74,8 @@ export interface PianoInputInstance {
   update: (options: Partial<PianoInputOptions>) => void
 
   /**
-   * Start a note from something other than a pointer: a keyboard shortcut, a
-   * MIDI message, an imperative call.
+   * Start a note from something other than a pointer or a shortcut: a MIDI
+   * message, an imperative call.
    */
   noteOn: (
     note: number,
@@ -87,6 +112,11 @@ export function createPianoInput(
   const held = new Map<number, Set<NoteSource>>()
   /** The note each pointer is currently on. */
   const pointerNotes = new Map<number, number>()
+  /**
+   * The note each held shortcut key is playing, by `code` — the physical key,
+   * so that releasing it with a different modifier or layout still matches.
+   */
+  const shortcutNotes = new Map<string, number>()
 
   function activeNotes(): number[] {
     return [...held.keys()].sort((a, b) => a - b)
@@ -156,6 +186,97 @@ export function createPianoInput(
     }
   }
 
+  /** The note a shortcut key plays, or null when it has none. */
+  function shortcutNote(key: string) {
+    const keys = opts.keyboardShortcuts?.keys
+    if (!keys || key === '') return null
+    const { first, last } = opts.layout.noteRange
+    const index = keys.indexOf(key)
+    const note = first + index
+    return index === -1 || note > last ? null : note
+  }
+
+  function onKeyDown(event: KeyboardEvent) {
+    const id = event.code || event.key
+    if (event.repeat || shortcutNotes.has(id)) return
+    if (isEditableTarget(event.target)) return
+    const note = shortcutNote(event.key)
+    if (note === null) return
+    shortcutNotes.set(id, note)
+    noteOn(note, { source: `keyboard:${id}` })
+  }
+
+  function onKeyUp(event: KeyboardEvent) {
+    const id = event.code || event.key
+    const note = shortcutNotes.get(id)
+    if (note === undefined) return
+    shortcutNotes.delete(id)
+    noteOff(note, { source: `keyboard:${id}` })
+  }
+
+  function releaseShortcuts() {
+    for (const [id, note] of shortcutNotes) {
+      noteOff(note, { source: `keyboard:${id}` })
+    }
+    shortcutNotes.clear()
+  }
+
+  function onFocusOut(event: Event) {
+    const next = (event as FocusEvent).relatedTarget
+    // Moving between the keys and whatever else is inside keeps them held.
+    if (next instanceof Node && element.contains(next)) return
+    releaseShortcuts()
+  }
+
+  /** The scope the listeners are bound for, or null when none are. */
+  let boundScope: KeyboardShortcutsScope | null = null
+
+  function bindShortcuts() {
+    const scope = opts.keyboardShortcuts
+      ? (opts.keyboardShortcutsScope ?? 'root')
+      : null
+    if (scope === boundScope) return
+    unbindShortcuts()
+    const win = globalThis.window
+    if (!scope || !win) return
+    const target: EventTarget = scope === 'window' ? win : element
+    target.addEventListener('keydown', onKeyDown as EventListener)
+    target.addEventListener('keyup', onKeyUp as EventListener)
+    if (scope === 'root') element.addEventListener('focusout', onFocusOut)
+    // A key released while the window is in the background never sends its
+    // keyup, so everything is let go when the focus leaves the page.
+    win.addEventListener('blur', releaseShortcuts)
+    boundScope = scope
+  }
+
+  function unbindShortcuts() {
+    const win = globalThis.window
+    if (!boundScope || !win) return
+    const target: EventTarget = boundScope === 'window' ? win : element
+    target.removeEventListener('keydown', onKeyDown as EventListener)
+    target.removeEventListener('keyup', onKeyUp as EventListener)
+    element.removeEventListener('focusout', onFocusOut)
+    win.removeEventListener('blur', releaseShortcuts)
+    boundScope = null
+  }
+
+  /**
+   * What the held keys were started against. Compared by value: a caller
+   * who writes the keys inline hands over a new array on every update, and
+   * releasing on that would stop a note as soon as anything re-renders.
+   */
+  function shortcutMapping() {
+    const { first, last } = opts.layout.noteRange
+    return [
+      opts.keyboardShortcuts?.keys.join('\u0000') ?? '',
+      opts.keyboardShortcutsScope ?? 'root',
+      first,
+      last,
+    ].join('\u0001')
+  }
+
+  bindShortcuts()
+
   const drag = createDrag(element, {
     multiPointer: true,
     onDragStart: (state) =>
@@ -171,7 +292,10 @@ export function createPianoInput(
 
   return {
     update: (next) => {
+      const mapping = shortcutMapping()
       opts = { ...opts, ...next }
+      if (shortcutMapping() !== mapping) releaseShortcuts()
+      bindShortcuts()
 
       const midiMax = opts.midiMax ?? 127
       const stoppedNotes = activeNotes().filter((note) => note > midiMax)
@@ -191,6 +315,8 @@ export function createPianoInput(
     activeNotes,
     destroy: () => {
       drag.destroy()
+      unbindShortcuts()
+      shortcutNotes.clear()
       // Anything still held is released, so a caller that mirrors these
       // callbacks into a synth is not left with a stuck note.
       const notes = activeNotes()

package/src/piano/layout.ts

@@ -181,3 +181,22 @@ export function noteAt(
 
   return null
 }
+
+/**
+ * The white key width that makes the keyboard exactly `width` wide, for a
+ * keyboard that follows the size of its container.
+ *
+ * Solved from {@link pianoWidth} rather than by dividing among the white
+ * keys, so that a range that starts or ends on a black key — which sticks out
+ * by a fraction of a white key — still fills the container. The width grows
+ * linearly with the white key width, so two samples pin it down.
+ */
+export function fitWhiteKeyWidth(
+  width: number,
+  layout: Omit<PianoLayout, 'whiteKeyWidth'>,
+): number {
+  const at = (whiteKeyWidth: number) => pianoWidth({ ...layout, whiteKeyWidth })
+  const slope = at(2) - at(1)
+  if (slope <= 0) return 0
+  return (width - (at(1) - slope)) / slope
+}

package/src/piano/shortcuts.ts

@@ -0,0 +1,86 @@
+export type KeyboardShortcuts = {
+  /**
+   * Keys laid out from `noteRange.first`, one entry per semitone.
+   *
+   * An empty string leaves that note without a shortcut: `KeyboardEvent.key` is
+   * never empty, so the entry can never match. Use it to skip the black keys
+   * (see {@link SHORTCUTS.HOME_ROW_NATURAL}) and keep the remaining entries
+   * lined up with the notes.
+   */
+  keys: string[]
+}
+
+/**
+ * Ready-made keyboard layouts. Both assume `noteRange.first` is a C.
+ */
+export const SHORTCUTS = {
+  /** Every semitone from C, over the two rows of a QWERTY keyboard. */
+  HOME_ROW: {
+    keys: [
+      'a',
+      'w',
+      's',
+      'e',
+      'd',
+      'f',
+      't',
+      'g',
+      'y',
+      'h',
+      'u',
+      'j',
+      'k',
+      'o',
+      'l',
+      'p',
+      ';',
+    ],
+  },
+  /** The white keys only, on the home row. Black keys have no shortcut. */
+  HOME_ROW_NATURAL: {
+    keys: [
+      'a',
+      '',
+      's',
+      '',
+      'd',
+      'f',
+      '',
+      'g',
+      '',
+      'h',
+      '',
+      'j',
+      'k',
+      '',
+      'l',
+      '',
+      ';',
+    ],
+  },
+}
+
+/**
+ * Where keyboard shortcuts listen. `root` handles keys only while the piano
+ * or one of its descendants has focus; `window` handles them anywhere on the
+ * page except in editable elements.
+ */
+export type KeyboardShortcutsScope = 'root' | 'window'
+
+/**
+ * Whether a key press was typed into something: shortcuts must not play a
+ * note for a letter that is going into a text field.
+ */
+export function isEditableTarget(target: EventTarget | null) {
+  if (!(target instanceof HTMLElement)) return false
+  if (target.matches('input, textarea, select')) return true
+
+  for (let element: HTMLElement | null = target; element;) {
+    const contentEditable = element.getAttribute('contenteditable')
+    if (contentEditable !== null)
+      return contentEditable.toLowerCase() !== 'false'
+    element = element.parentElement
+  }
+
+  return false
+}