@tremolo-ui/dom 0.6.0 → 0.7.0

package/src/file/drop-zone.ts

@@ -0,0 +1,202 @@
+import { matchesAccept } from './accept'
+
+/** What is in the air over the element. */
+export interface DropZoneState {
+  /** Files are being dragged over the element. */
+  over: boolean
+  /**
+   * None of what is being dragged matches `accept`, as far as can be told
+   * before the drop.
+   *
+   * The browser reports the type of what is being dragged but withholds the
+   * name, so a rule written as an extension cannot be decided yet and is not
+   * counted against the drag. It is decided on the drop, where the name is.
+   */
+  invalid: boolean
+}
+
+export interface DropZoneOptions {
+  /**
+   * Which files to take, written the way the `accept` attribute of a file
+   * input is: a comma separated list of extensions (`.wav`), MIME types
+   * (`audio/wav`) and type groups (`audio/*`).
+   */
+  accept?: string
+  /**
+   * Take more than one file from a single drop. With it off, only the first
+   * accepted file is reported, as a file input without `multiple` does.
+   *
+   * @default false
+   */
+  multiple?: boolean
+  /**
+   * Refuse the drop. The drag is still swallowed rather than let through: an
+   * unhandled drop makes the browser leave the page and open the file.
+   *
+   * @default false
+   */
+  disabled?: boolean
+
+  /** Called with the dropped files that match `accept`. */
+  onDrop?: (files: File[], event: DragEvent) => void
+  /**
+   * Called with the dropped files that do not match `accept`, so that the
+   * reason can be shown.
+   */
+  onReject?: (files: File[], event: DragEvent) => void
+  /** Called whenever {@link DropZoneInstance.state} would change. */
+  onStateChange?: (state: DropZoneState) => void
+}
+
+export interface DropZoneInstance {
+  /** What is in the air over the element, right now. */
+  readonly state: DropZoneState
+  /** Replace the given options, keeping the listeners in place. */
+  update: (options: DropZoneOptions) => void
+  destroy: () => void
+}
+
+/**
+ * Take files dropped onto an element.
+ *
+ * ```ts
+ * const zone = createDropZone(element, {
+ *   accept: 'audio/*',
+ *   onDrop: (files) => load(files[0]),
+ * })
+ * ```
+ *
+ * The element needs no attribute of its own: a drop target is made by
+ * cancelling `dragover`, which this does.
+ */
+export function createDropZone(
+  element: Element,
+  options: DropZoneOptions = {},
+): DropZoneInstance {
+  let opts = options
+  let state: DropZoneState = { over: false, invalid: false }
+
+  /**
+   * `dragenter` and `dragleave` fire for descendants too, so moving between
+   * two children of the zone leaves before it enters. Counting the pairs is
+   * what keeps the state from flickering off in the middle of the element.
+   */
+  let depth = 0
+
+  function setState(next: DropZoneState) {
+    if (next.over === state.over && next.invalid === state.invalid) return
+    state = next
+    opts.onStateChange?.(state)
+  }
+
+  function carriesFiles(transfer: DataTransfer | null) {
+    // `types` is the only thing that can be trusted during a drag; `files` is
+    // empty until the drop.
+    return !!transfer?.types.includes('Files')
+  }
+
+  /** Whether anything being dragged could still be accepted. */
+  function anyAcceptable(transfer: DataTransfer | null) {
+    const items = Array.from(transfer?.items ?? []).filter(
+      (item) => item.kind === 'file',
+    )
+    // Some browsers hand over no items at all, only the `Files` type. Nothing
+    // is known, so nothing is refused.
+    if (items.length === 0) return true
+    return items.some((item) => matchesAccept({ type: item.type }, opts.accept))
+  }
+
+  function onDragEnter(event: DragEvent) {
+    if (!carriesFiles(event.dataTransfer)) return
+    // Cancelled as well as `dragover`: a target that only cancels one of the
+    // two is not a drop target in every browser.
+    event.preventDefault()
+    depth += 1
+    setState({ over: true, invalid: !anyAcceptable(event.dataTransfer) })
+  }
+
+  function onDragOver(event: DragEvent) {
+    if (!carriesFiles(event.dataTransfer)) return
+    event.preventDefault()
+    if (event.dataTransfer) {
+      // Decides the cursor the pointer shows, and whether a drop is offered.
+      event.dataTransfer.dropEffect =
+        opts.disabled || state.invalid ? 'none' : 'copy'
+    }
+    // A drag that began outside the document can arrive without a `dragenter`
+    // the listener saw, so the state is settled here too.
+    if (!state.over) {
+      depth = Math.max(depth, 1)
+      setState({ over: true, invalid: !anyAcceptable(event.dataTransfer) })
+    }
+  }
+
+  function onDragLeave(event: DragEvent) {
+    if (!carriesFiles(event.dataTransfer)) return
+    depth = Math.max(0, depth - 1)
+    if (depth === 0) setState({ over: false, invalid: false })
+  }
+
+  function onDrop(event: DragEvent) {
+    if (!carriesFiles(event.dataTransfer)) return
+    // Always cancelled, even while disabled: an unhandled drop makes the
+    // browser leave the page and open the file.
+    event.preventDefault()
+    depth = 0
+    setState({ over: false, invalid: false })
+    if (opts.disabled) return
+
+    const dropped = Array.from(event.dataTransfer?.files ?? [])
+    const accepted: File[] = []
+    const rejected: File[] = []
+    for (const file of dropped) {
+      if (matchesAccept(file, opts.accept)) accepted.push(file)
+      else rejected.push(file)
+    }
+
+    if (rejected.length > 0) opts.onReject?.(rejected, event)
+    const taken = opts.multiple ? accepted : accepted.slice(0, 1)
+    if (taken.length > 0) opts.onDrop?.(taken, event)
+  }
+
+  /**
+   * A drag that ends anywhere else — dropped on another element, cancelled
+   * with Esc, taken out of the window — sends no `dragleave` here, and the
+   * element would stay marked as a drop target for good.
+   */
+  function onDragEndAnywhere() {
+    depth = 0
+    setState({ over: false, invalid: false })
+  }
+
+  const handlers = {
+    dragenter: onDragEnter,
+    dragover: onDragOver,
+    dragleave: onDragLeave,
+    drop: onDrop,
+  } as const
+
+  for (const [type, handler] of Object.entries(handlers)) {
+    element.addEventListener(type, handler as EventListener)
+  }
+
+  const doc = element.ownerDocument
+  doc?.addEventListener('dragend', onDragEndAnywhere)
+  doc?.addEventListener('drop', onDragEndAnywhere)
+
+  return {
+    get state() {
+      return state
+    },
+    update: (next) => {
+      opts = { ...opts, ...next }
+    },
+    destroy: () => {
+      for (const [type, handler] of Object.entries(handlers)) {
+        element.removeEventListener(type, handler as EventListener)
+      }
+      doc?.removeEventListener('dragend', onDragEndAnywhere)
+      doc?.removeEventListener('drop', onDragEndAnywhere)
+    },
+  }
+}

package/src/index.ts

@@ -13,6 +13,23 @@ export {
   type DrawingState,
   type DrawingStateValue,
 } from './canvas/context'
+export { matchesAccept, type AcceptCandidate } from './file/accept'
+export {
+  createDropZone,
+  type DropZoneInstance,
+  type DropZoneOptions,
+  type DropZoneState,
+} from './file/drop-zone'
+export { applyDelta } from './input/apply-delta'
+export {
+  mapModifier,
+  selectModifier,
+  type InputEventOption,
+  type Modifier,
+  type ModifierMap,
+  type ModifierState,
+  type ModifierValue,
+} from './input/modifiers'
 export {
   createMIDIAccess,
   NOT_SUPPORTED,
@@ -30,6 +47,15 @@ export {
   type MIDIInputInstance,
 } from './midi/input'
 export { createMIDIMessage, type MIDIMessageInstance } from './midi/message'
+export {
+  blackKeyWidth,
+  getNoteRangeArray,
+  noteAt,
+  notePosition,
+  pianoWidth,
+  type NoteRange,
+  type PianoLayout,
+} from './piano/layout'
 export {
   createPianoInput,
   type NoteSource,

package/src/input/apply-delta.ts

@@ -0,0 +1,73 @@
+import {
+  clamp,
+  linearScale,
+  stepValue,
+  toPrecision,
+  type ValueRange,
+} from '@tremolo-ui/functions'
+
+import {
+  selectModifier,
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+} from './modifiers'
+
+/**
+ * Move a value by an amount of input, as reported by a wheel or an arrow key.
+ *
+ * The pipeline matches {@link createDragValue}: scale, then step, then clamp.
+ * Which key or which sign of `deltaY` counts as which direction is left to the
+ * caller, since it differs per component.
+ *
+ * @param direction which way, and how many times, to apply the option. The
+ * size of one step is `option[1]`, so this is normally `1` or `-1`.
+ *
+ * @param modifiers the event, for `options` that name a modifier key. See
+ * {@link selectModifier}.
+ *
+ * @example
+ * // ArrowDown on a slider whose keyboard option is ['raw', 1]
+ * applyDelta(value, -1, keyboard, { min, max, step, scale })
+ *
+ * @example
+ * // Shift+ArrowDown, where `keyboard` is { default: …, shift: ['raw', 0.1] }
+ * applyDelta(value, -1, keyboard, range, event)
+ */
+export function applyDelta(
+  value: number,
+  direction: number,
+  options: ModifierValue<InputEventOption>,
+  { min, max, step, scale = linearScale }: ValueRange,
+  modifiers?: ModifierState,
+): number {
+  if (min >= max) throw new RangeError('requirements: min < max')
+  if (step !== undefined && (!Number.isFinite(step) || step <= 0)) {
+    throw new RangeError(
+      'applyDelta step: requirements: finite and greater than 0',
+    )
+  }
+
+  const {
+    value: [mode, amount],
+    modifier,
+  } = selectModifier(options, modifiers)
+
+  const x = direction * amount
+  const next =
+    mode === 'normalized'
+      ? scale.denormalize(scale.normalize(value, min, max) + x, min, max)
+      : value + x
+
+  // Naming a modifier is a deliberate request to move off the grid, so `step`
+  // does not apply to it. Without this a finer amount would round straight
+  // back to where it started: `stepValue(3 + 0.1, 1)` is 3.
+  const quantum = modifier === null ? step : undefined
+  const stepped = quantum !== undefined ? stepValue(next, quantum) : next
+
+  // Rounded before the clamp, so that `min` and `max` still have the last
+  // word and the value can land on them exactly. Without this the artefact
+  // accumulates: with no `step` to round it back, twelve presses of a 0.1
+  // modifier amount reach 5.699999999999998 rather than 5.7.
+  return clamp(toPrecision(stepped), min, max)
+}

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/piano/index.ts

@@ -1,7 +1,7 @@
-import { noteAt, type PianoLayout } from '@tremolo-ui/functions'
-
 import { createDrag } from '../pointer/drag'
 
+import { noteAt, type PianoLayout } from './layout'
+
 /**
  * What asked for a note to sound.
  *

package/src/piano/layout.ts

@@ -0,0 +1,183 @@
+import {
+  isBlackKey,
+  isWhiteKey,
+  noteKey,
+  noteKeys,
+  type NoteKey,
+} from '@tremolo-ui/functions'
+
+export type NoteRange = {
+  first: number
+  last: number
+}
+
+/**
+ * `[noteRange.first, noteRange.first + 1, ..., noteRange.last]`
+ */
+export function getNoteRangeArray(noteRange: NoteRange): number[] {
+  return Array.from(
+    { length: noteRange.last - noteRange.first + 1 },
+    (_, i) => i + noteRange.first,
+  )
+}
+
+/**
+ * The geometry of a drawn keyboard.
+ *
+ * One description is shared by the drawing and the hit testing, so a key cannot
+ * be drawn somewhere other than where it responds.
+ */
+export interface PianoLayout {
+  noteRange: NoteRange
+
+  /** Width of a white key, excluding {@link PianoLayout.keyGap}. */
+  whiteKeyWidth: number
+
+  /**
+   * Space between two white keys. Part of the slot a white key occupies, so it
+   * still belongs to one of the keys for the purpose of hit testing.
+   *
+   * @default 1
+   */
+  keyGap?: number
+
+  /**
+   * Width of a black key, as a fraction of {@link PianoLayout.whiteKeyWidth}.
+   *
+   * @default 0.65
+   */
+  blackKeyWidthRatio?: number
+
+  /**
+   * Height of a black key, as a fraction of the height of the keyboard.
+   *
+   * @default 0.6
+   */
+  blackKeyHeightRatio?: number
+}
+
+const DEFAULT_KEY_GAP = 1
+const DEFAULT_BLACK_KEY_WIDTH_RATIO = 0.65
+const DEFAULT_BLACK_KEY_HEIGHT_RATIO = 0.6
+
+/**
+ * How many white keys sit at or before each pitch class, counting from C.
+ *
+ * A black key shares the number of the white key to its left plus one, which
+ * puts it on the boundary between the two; {@link notePosition} then shifts it
+ * back by half its width to centre it there.
+ */
+const whiteKeysBefore: Record<NoteKey, number> = {
+  C: 0,
+  'C#': 1,
+  D: 1,
+  'D#': 2,
+  E: 2,
+  F: 3,
+  'F#': 4,
+  G: 4,
+  'G#': 5,
+  A: 5,
+  'A#': 6,
+  B: 6,
+}
+
+/** Width of a black key in pixels. */
+export function blackKeyWidth(layout: PianoLayout): number {
+  return (
+    layout.whiteKeyWidth *
+    (layout.blackKeyWidthRatio ?? DEFAULT_BLACK_KEY_WIDTH_RATIO)
+  )
+}
+
+function rawNotePosition(note: number, layout: PianoLayout): number {
+  const slot = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP)
+  const target = noteKey(note)
+  const first = noteKey(layout.noteRange.first)
+
+  const octave = Math.floor((note - layout.noteRange.first) / 12)
+  const octaveOffset =
+    noteKeys.indexOf(first) > noteKeys.indexOf(target) ? 1 : 0
+  const whiteKeysIn =
+    whiteKeysBefore[target] -
+    whiteKeysBefore[first] +
+    (octave + octaveOffset) * 7
+
+  return isBlackKey(note)
+    ? whiteKeysIn * slot - blackKeyWidth(layout) / 2
+    : whiteKeysIn * slot
+}
+
+function pianoBounds(layout: PianoLayout) {
+  const notes = getNoteRangeArray(layout.noteRange)
+  if (notes.length === 0) return { left: 0, right: 0 }
+
+  let left = Infinity
+  let right = -Infinity
+  const whiteWidth = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP)
+  for (const note of notes) {
+    const noteLeft = rawNotePosition(note, layout)
+    const width = isBlackKey(note) ? blackKeyWidth(layout) : whiteWidth
+    left = Math.min(left, noteLeft)
+    right = Math.max(right, noteLeft + width)
+  }
+  return { left, right }
+}
+
+/** Width of the whole keyboard in pixels. */
+export function pianoWidth(layout: PianoLayout): number {
+  const { left, right } = pianoBounds(layout)
+  return right - left
+}
+
+/**
+ * Offset of the left edge of a key from the left edge of the keyboard, in
+ * pixels.
+ *
+ * Notes outside `noteRange` are placed too, so the value is negative below
+ * `noteRange.first`.
+ */
+export function notePosition(note: number, layout: PianoLayout): number {
+  return rawNotePosition(note, layout) - pianoBounds(layout).left
+}
+
+/**
+ * The note drawn at a point, or null where there is none.
+ *
+ * Black keys are tested first, so they win where they overlap a white one. A
+ * white key covers its gap as well as its width, so the whole width of the
+ * keyboard belongs to some key and a click cannot fall between two.
+ *
+ * @param x offset from the left edge of the keyboard, in pixels
+ * @param y offset from its top edge, in pixels
+ * @param height height of the keyboard, in pixels
+ */
+export function noteAt(
+  x: number,
+  y: number,
+  height: number,
+  layout: PianoLayout,
+): number | null {
+  if (x < 0 || x >= pianoWidth(layout) || y < 0 || y >= height) return null
+
+  const notes = getNoteRangeArray(layout.noteRange)
+  const blackHeight =
+    height * (layout.blackKeyHeightRatio ?? DEFAULT_BLACK_KEY_HEIGHT_RATIO)
+
+  if (y < blackHeight) {
+    for (const note of notes) {
+      if (isWhiteKey(note)) continue
+      const left = notePosition(note, layout)
+      if (left <= x && x < left + blackKeyWidth(layout)) return note
+    }
+  }
+
+  const slot = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP)
+  for (const note of notes) {
+    if (isBlackKey(note)) continue
+    const left = notePosition(note, layout)
+    if (left <= x && x < left + slot) return note
+  }
+
+  return null
+}