@tremolo-ui/dom 0.6.0 → 0.8.0

package/src/input/direction.ts

@@ -0,0 +1,107 @@
+/**
+ * Which way an input moves a value, before any amount is applied.
+ *
+ * `applyDelta` takes the direction as given, since which key or which sign of
+ * `deltaY` counts as "up" differs per control. The answers are collected here
+ * so that every wrapper gives the same one: a knob that turns the other way
+ * in one framework would be a bug nobody could see from the code.
+ *
+ * Two families, by what the control looks like:
+ *
+ * - **one value** (`Knob`, `Slider`, `NumberInput`): right and up raise it
+ * - **a position on screen** (`XYPad`, `PointsEditor`): in screen coordinates,
+ *   x growing rightwards and y growing downwards, plus which axis moves
+ *
+ * A control that runs the other way (`reverse`) flips the result itself.
+ */
+
+/** One of the four arrow keys, as `KeyboardEvent.key` names it. */
+export type ArrowKey = 'ArrowRight' | 'ArrowLeft' | 'ArrowUp' | 'ArrowDown'
+
+/** Is `key` one of the four arrow keys? */
+export function isArrowKey(key: string): key is ArrowKey {
+  return (
+    key === 'ArrowRight' ||
+    key === 'ArrowLeft' ||
+    key === 'ArrowUp' ||
+    key === 'ArrowDown'
+  )
+}
+
+/** A move along one of the two axes of a position on screen. */
+export interface AxisMove {
+  /** 0 = x, 1 = y. */
+  axis: 0 | 1
+  /** `1` towards the right or the bottom, `-1` towards the left or the top. */
+  direction: 1 | -1
+}
+
+/**
+ * The direction an arrow key moves a single value: right and up raise it.
+ * `null` for any other key.
+ */
+export function arrowKeyDirection(key: string): 1 | -1 | null {
+  if (!isArrowKey(key)) return null
+  return key === 'ArrowRight' || key === 'ArrowUp' ? 1 : -1
+}
+
+/**
+ * The axis and direction an arrow key moves a position on screen. `null` for
+ * any other key.
+ *
+ * The key picks the axis, whichever element inside the control holds the
+ * focus: a two-dimensional control is one control to the person moving it.
+ */
+export function arrowKeyMove(key: string): AxisMove | null {
+  if (!isArrowKey(key)) return null
+  return {
+    axis: key === 'ArrowRight' || key === 'ArrowLeft' ? 0 : 1,
+    direction: key === 'ArrowLeft' || key === 'ArrowUp' ? -1 : 1,
+  }
+}
+
+export interface WheelDirectionOptions {
+  /**
+   * Read horizontal scrolling as well, for a control laid out horizontally:
+   * scrolling right raises the value. Vertical scrolling still counts when
+   * there is no horizontal movement.
+   *
+   * @default false
+   */
+  horizontal?: boolean
+}
+
+/**
+ * The direction one wheel event moves a single value: scrolling up raises it.
+ * `null` when the event carries no movement the control reads.
+ */
+export function wheelDirection(
+  event: Pick<WheelEvent, 'deltaX' | 'deltaY'>,
+  { horizontal = false }: WheelDirectionOptions = {},
+): 1 | -1 | null {
+  if (horizontal && event.deltaX !== 0) return event.deltaX > 0 ? 1 : -1
+  if (event.deltaY === 0) return null
+  return event.deltaY > 0 ? -1 : 1
+}
+
+/**
+ * The axis and direction one wheel event moves a position on screen. `null`
+ * when the event carries no movement.
+ *
+ * Scrolling moves y, and shift switches to x. Browsers turn shift+wheel into
+ * horizontal scrolling: `deltaY` comes out empty and `deltaX` carries the
+ * movement. Reading whichever axis moved keeps shift working as the x-axis
+ * modifier — and picks up a trackpad's own horizontal gesture, which never
+ * had a modifier.
+ */
+export function wheelMove(
+  event: Pick<WheelEvent, 'deltaX' | 'deltaY' | 'shiftKey'>,
+): AxisMove | null {
+  const horizontal = event.deltaX !== 0
+  const delta = horizontal ? event.deltaX : event.deltaY
+  if (delta === 0) return null
+  return {
+    axis: horizontal || event.shiftKey ? 0 : 1,
+    direction: delta < 0 ? -1 : 1,
+  }
+}

package/src/input/modifiers.ts

@@ -0,0 +1,121 @@
+/**
+ * Options for setting the amount of keyboard and mouse wheel changes.
+ */
+export type InputEventOption = readonly ['normalized' | 'raw', number]
+
+/**
+ * A modifier key that can carry an amount of its own.
+ *
+ * `ctrl` and `meta` are kept apart rather than folded into one "command" key:
+ * a plugin UI that mirrors a desktop host usually wants the same physical key
+ * on every platform, not the platform's own convention.
+ */
+export type Modifier = 'shift' | 'alt' | 'ctrl' | 'meta'
+
+/** The modifier flags of a `WheelEvent` or a `KeyboardEvent`. */
+export interface ModifierState {
+  shiftKey: boolean
+  altKey: boolean
+  ctrlKey: boolean
+  metaKey: boolean
+}
+
+/** One setting per modifier key, with `default` for none of them. */
+type ModifierSetting = number | InputEventOption
+
+export type ModifierMap<T extends ModifierSetting> = { default: T } & Partial<
+  Record<Modifier, T>
+>
+
+/**
+ * A single setting, or one per modifier key.
+ *
+ * @example
+ * ['raw', 1]
+ * { default: ['raw', 1], shift: ['raw', 0.1] }
+ */
+export type ModifierValue<T extends ModifierSetting> = T | ModifierMap<T>
+
+/**
+ * Checked in this order, and the first one that is both held and configured
+ * wins. Fixing an order is what keeps two modifiers held at once from
+ * behaving differently between browsers.
+ */
+const MODIFIER_ORDER = ['meta', 'ctrl', 'alt', 'shift'] as const
+
+const MODIFIER_FLAG = {
+  meta: 'metaKey',
+  ctrl: 'ctrlKey',
+  alt: 'altKey',
+  shift: 'shiftKey',
+} as const satisfies Record<Modifier, keyof ModifierState>
+
+/**
+ * A map is the only form with a `default` key, which is what tells it apart
+ * from a bare setting. Tuples are arrays, so they never match.
+ */
+function isModifierMap<T extends ModifierSetting>(
+  value: ModifierValue<T>,
+): value is ModifierMap<T> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    'default' in value
+  )
+}
+
+/**
+ * Pick the setting that applies, given the modifier keys being held.
+ *
+ * @example
+ * selectModifier({ default: 1, shift: 0.1 }, event)
+ */
+export function selectModifier<T extends ModifierSetting>(
+  options: ModifierValue<T>,
+  modifiers?: ModifierState,
+): { value: T; modifier: Modifier | null } {
+  if (!isModifierMap(options)) {
+    // TypeScript cannot subtract the map from `ModifierValue<T>` while `T` is
+    // still a type parameter, so the other half has to be spelled out.
+    return { value: options as T, modifier: null }
+  }
+  if (modifiers) {
+    for (const modifier of MODIFIER_ORDER) {
+      const value = options[modifier]
+      // Compared against undefined rather than checked for truthiness: 0 is a
+      // legitimate setting.
+      if (value !== undefined && modifiers[MODIFIER_FLAG[modifier]]) {
+        return { value, modifier }
+      }
+    }
+  }
+  return { value: options.default, modifier: null }
+}
+
+/**
+ * Turn every entry of a setting into another kind of setting, keeping which
+ * modifier each belongs to.
+ *
+ * A drag sensitivity is a number and a keyboard amount is a tuple, but the two
+ * describe the same thing from the caller's side. This carries one over to the
+ * other so that a component can hand a sensitivity to {@link applyDelta}
+ * without unpicking the modifier map itself — which matters, since naming a
+ * modifier is also what takes `step` out of the pipeline.
+ *
+ * @example
+ * mapModifier({ default: 1, shift: 0.1 }, (f) => ['raw', step * f])
+ * // { default: ['raw', 1], shift: ['raw', 0.1] }
+ */
+export function mapModifier<
+  T extends ModifierSetting,
+  U extends ModifierSetting,
+>(options: ModifierValue<T>, fn: (value: T) => U): ModifierValue<U> {
+  if (!isModifierMap(options)) return fn(options as T)
+  const mapped = { default: fn(options.default) } as ModifierMap<U>
+  for (const modifier of MODIFIER_ORDER) {
+    const value = options[modifier]
+    if (value !== undefined) mapped[modifier] = fn(value)
+  }
+  return mapped
+}

package/src/knob/geometry.ts

@@ -0,0 +1,100 @@
+import { radian, type Scale } from '@tremolo-ui/functions'
+
+/**
+ * Width and height of the viewBox a knob is drawn in. The arcs and the thumb
+ * are laid out in these units, and the SVG scales them to the knob's size.
+ */
+export const KNOB_VIEWBOX_SIZE = 100
+
+const center = KNOB_VIEWBOX_SIZE / 2
+
+export interface KnobAngleOptions {
+  value: number
+  min: number
+  max: number
+  scale: Scale
+  /** Where the active arc starts from, so that it can grow from the middle. */
+  startValue: number
+  /** How far the knob turns from `min` to `max`, in degrees. */
+  angleRange: number
+}
+
+/**
+ * The angles a knob is drawn with, in degrees clockwise from the top.
+ *
+ * The travel is centred on the top, so `angleRange` of 270 runs from -135 to
+ * 135. Derived from the value alone, so a wrapper can call it while rendering.
+ */
+export interface KnobAngles {
+  /** The value, normalized to 0..1 along the scale. */
+  p: number
+  /** Where the travel starts. */
+  r1: number
+  /** Where the active arc starts: the lower of the value and `startValue`. */
+  r2: number
+  /** Where the active arc ends: the higher of the value and `startValue`. */
+  r3: number
+  /** Where the travel ends. */
+  r4: number
+}
+
+export function knobAngles({
+  value,
+  min,
+  max,
+  scale,
+  startValue,
+  angleRange,
+}: KnobAngleOptions): KnobAngles {
+  const p = scale.normalize(value, min, max)
+  const s = scale.normalize(startValue, min, max)
+  const r1 = -angleRange / 2
+  const r2 = r1 + Math.min(p, s) * angleRange
+  const r3 = r1 + Math.max(p, s) * angleRange
+  const r4 = angleRange / 2
+  return { p, r1, r2, r3, r4 }
+}
+
+/**
+ * The point at `angle` on a circle of `radius` around the centre of the
+ * viewBox.
+ *
+ * The radius depends on the stroke of the line being drawn, which each arc
+ * has its own of, so the point is found per arc rather than once for the knob.
+ */
+export function knobArcPoint(angle: number, radius: number) {
+  return {
+    x: center + radius * Math.cos(radian(angle - 90)),
+    y: center + radius * Math.sin(radian(angle - 90)),
+  }
+}
+
+/**
+ * The radius that keeps a stroke of `strokeWidth` inside the viewBox: half of
+ * the stroke falls outside the path it is drawn along.
+ */
+export function knobArcRadius(strokeWidth: number | string | undefined) {
+  const width =
+    typeof strokeWidth === 'number'
+      ? strokeWidth
+      : Number.parseFloat(String(strokeWidth))
+  return Number.isFinite(width) ? center - width / 2 : center
+}
+
+/** Build an SVG path for an arc, splitting full turns into drawable segments. */
+export function knobArcPath(
+  startAngle: number,
+  endAngle: number,
+  radius: number,
+) {
+  const start = knobArcPoint(startAngle, radius)
+  const sweep = endAngle - startAngle
+  const segmentCount = Math.max(1, Math.ceil(Math.abs(sweep) / 180))
+  const segmentSweep = sweep / segmentCount
+  let path = `M ${start.x} ${start.y}`
+  for (let i = 1; i <= segmentCount; i += 1) {
+    const end = knobArcPoint(startAngle + segmentSweep * i, radius)
+    path += ` A ${radius} ${radius} 0 0 ${segmentSweep >= 0 ? 1 : 0} ${end.x} ${end.y}`
+  }
+  return path
+}

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
+}