@tremolo-ui/dom 0.5.0 → 0.7.0

package/src/canvas/animation.ts

@@ -17,7 +17,7 @@ export interface AnimationFrame {
   deltaTime: number
   /** Milliseconds since the instance was created. */
   elapsedTime: number
-  /** Frames per second implied by `deltaTime`. */
+  /** Frames per second implied by `deltaTime`, or 0 when no time elapsed. */
   fps: number
 }
 
@@ -47,7 +47,7 @@ export interface AnimationCanvasOptions {
   animate?: boolean
 
   /**
-   * Size in CSS pixels. Ignored when `relativeSize` is on.
+   * Size in CSS pixels. Ignored when `resizable` is on.
    *
    * @default { width: 100, height: 100 }
    */
@@ -61,7 +61,7 @@ export interface AnimationCanvasOptions {
    *
    * @default false
    */
-  relativeSize?: boolean
+  resizable?: boolean
 
   /**
    * Carry the drawing across a resize, so that the canvas does not blank for a
@@ -86,7 +86,7 @@ export interface AnimationCanvasInstance {
    * render without restarting the animation, so the frame count and the
    * elapsed time keep running.
    *
-   * `relativeSize` and `contextAttributes` are fixed for the lifetime of the
+   * `resizable` and `contextAttributes` are fixed for the lifetime of the
    * instance and are ignored here.
    *
    * While `animate` is off this also draws a frame, since nothing else would.
@@ -119,7 +119,7 @@ export function createAnimationCanvas(
   }
   const context: CanvasRenderingContext2D = context2d
 
-  const relativeSize = opts.relativeSize ?? false
+  const resizable = opts.resizable ?? false
 
   /** Off-document canvas holding the drawing while the real one is resized. */
   let memo: HTMLCanvasElement | null = null
@@ -127,6 +127,7 @@ export function createAnimationCanvas(
 
   let width = 0
   let height = 0
+  let appliedDpr = 0
   /** Whether a size has been applied, so a frame can be drawn. */
   let sized = false
   let initialized = false
@@ -146,21 +147,20 @@ export function createAnimationCanvas(
    * Assigning to `memo.width` resets the memo's transform to the identity, so
    * the copy neither scales nor resamples.
    */
-  function takeSnapshot(): DrawingContext | null {
-    if (!(opts.reduceFlickering ?? true)) return null
+  function takeSnapshot() {
+    if (!(opts.reduceFlickering ?? true)) return false
     if (!memo) {
       memo = globalThis.document?.createElement('canvas') ?? null
       memoContext = memo?.getContext('2d', opts.contextAttributes) ?? null
     }
-    if (!memo || !memoContext) return null
+    if (!memo || !memoContext) return false
 
-    const state = readDrawingState(context)
     memo.width = canvas.width
     memo.height = canvas.height
     if (canvas.width > 0 && canvas.height > 0) {
       memoContext.drawImage(canvas, 0, 0)
     }
-    return state
+    return true
   }
 
   /**
@@ -172,13 +172,12 @@ export function createAnimationCanvas(
    * snapshot is rescaled once, from its full resolution.
    */
   function restoreSnapshot(
-    state: DrawingContext | null,
+    hasSnapshot: boolean,
     previousWidth: number,
     previousHeight: number,
   ) {
-    if (!state || !memo || !memoContext) return
+    if (!hasSnapshot || !memo) return
     if (memo.width <= 0 || memo.height <= 0) return
-    writeDrawingState(context, state)
     context.drawImage(memo, 0, 0, previousWidth, previousHeight)
   }
 
@@ -186,60 +185,76 @@ export function createAnimationCanvas(
     const dpr = devicePixelRatio()
     const previousWidth = width
     const previousHeight = height
-    const state = takeSnapshot()
+    const previousDpr = appliedDpr
+    const state: DrawingContext | null = sized
+      ? readDrawingState(context)
+      : null
+    const hasSnapshot = sized && takeSnapshot()
     applyDevicePixelRatio(canvas, context, w, h, dpr)
     width = w
     height = h
+    appliedDpr = dpr
     sized = true
-    restoreSnapshot(state, previousWidth, previousHeight)
+    // Restore pixels while the reset context still has neutral alpha,
+    // compositing, filter, and shadow settings.
+    restoreSnapshot(hasSnapshot, previousWidth, previousHeight)
+    if (state) {
+      writeDrawingState(context, state, dpr / previousDpr)
+    }
   }
 
-  function drawFrame() {
+  function applyDevicePixelRatioIfNeeded() {
+    if (sized && devicePixelRatio() !== appliedDpr) {
+      applySize(width, height)
+    }
+  }
+
+  function drawFrame(timestamp = performance.now()) {
     if (!sized) return
+    applyDevicePixelRatioIfNeeded()
     if (!initialized) {
       initialized = true
       opts.init?.(context, { width, height })
     }
-    const now = performance.now()
-    const deltaTime = now - previousTime
-    previousTime = now
+    const deltaTime = timestamp - previousTime
+    previousTime = timestamp
     count += 1
     opts.draw(context, {
       width,
       height,
       count,
       deltaTime,
-      elapsedTime: now - startTime,
-      fps: 1000 / deltaTime,
+      elapsedTime: timestamp - startTime,
+      fps: deltaTime > 0 ? 1000 / deltaTime : 0,
     })
   }
 
-  function tick() {
+  function tick(timestamp: DOMHighResTimeStamp) {
     // Scheduled before drawing so that a slow frame does not delay the next
     // request, matching how requestAnimationFrame loops are usually written.
     frameId = requestAnimationFrame(tick)
-    drawFrame()
+    drawFrame(timestamp)
   }
 
   function startLoop() {
-    if (frameId != null) return
+    if (frameId !== null) return
     previousTime = performance.now()
     frameId = requestAnimationFrame(tick)
   }
 
   function stopLoop() {
-    if (frameId == null) return
+    if (frameId === null) return
     cancelAnimationFrame(frameId)
     frameId = null
   }
 
   let observer: ResizeObserver | null = null
 
-  if (relativeSize) {
+  if (resizable) {
     const parent = canvas.parentElement
     if (!parent) {
       throw new Error(
-        'createAnimationCanvas: relativeSize needs the canvas to have a parent element',
+        'createAnimationCanvas: resizable needs the canvas to have a parent element',
       )
     }
     // The observer reports the current size as soon as it starts, so it is the
@@ -249,7 +264,9 @@ export function createAnimationCanvas(
     observer = new ResizeObserver((entries) => {
       for (const entry of entries) {
         const { width: w, height: h } = entry.contentRect
-        applySize(w, h)
+        if (w !== width || h !== height || devicePixelRatio() !== appliedDpr) {
+          applySize(w, h)
+        }
         // With the loop running the next frame covers the new size already.
         if (!(opts.animate ?? true)) drawFrame()
       }
@@ -272,14 +289,15 @@ export function createAnimationCanvas(
       opts = {
         ...opts,
         ...next,
-        relativeSize,
+        resizable,
         contextAttributes: opts.contextAttributes,
       }
 
-      if (!relativeSize) {
+      if (!resizable) {
         const { width: w = 100, height: h = 100 } = opts.size ?? {}
-        if (w != width || h != height) applySize(w, h)
+        if (w !== width || h !== height) applySize(w, h)
       }
+      applyDevicePixelRatioIfNeeded()
 
       const animating = opts.animate ?? true
       if (animating && !wasAnimating) startLoop()

package/src/canvas/context.ts

@@ -1,7 +1,8 @@
 /**
- * The properties of a 2D context that survive `save()` / `restore()`, and so
- * are what has to be carried across a resize by hand: setting `canvas.width`
- * resets the context to its defaults.
+ * The assignable parts of a 2D context's drawing state. They have to be
+ * carried across a resize by hand because setting `canvas.width` resets the
+ * context to its defaults. The transform and line dash are handled separately
+ * by {@link DrawingContext} because they are exposed through methods.
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/save
  */
@@ -19,20 +20,33 @@ export const drawingState = [
   'shadowBlur',
   'shadowColor',
   'globalCompositeOperation',
+  'filter',
   'font',
+  'fontKerning',
+  'fontStretch',
+  'fontVariantCaps',
   'textAlign',
   'textBaseline',
   'direction',
+  'letterSpacing',
+  'textRendering',
+  'wordSpacing',
   'imageSmoothingEnabled',
+  'imageSmoothingQuality',
 ] as const
 
 export type DrawingState = (typeof drawingState)[number]
 export type DrawingStateValue = CanvasRenderingContext2D[DrawingState]
-export type DrawingContext = Pick<CanvasRenderingContext2D, DrawingState>
+export type DrawingContext = Pick<CanvasRenderingContext2D, DrawingState> & {
+  /** The current line dash sequence. */
+  lineDash: number[]
+  /** The current transformation matrix. */
+  transform: DOMMatrix
+}
 
 export function isDrawingState(value: unknown): value is DrawingState {
   const names: readonly string[] = drawingState
-  return typeof value == 'string' && names.includes(value)
+  return typeof value === 'string' && names.includes(value)
 }
 
 /** Copy the drawing state off a context, to put back after a resize. */
@@ -43,6 +57,8 @@ export function readDrawingState(
   for (const property of drawingState) {
     ;(state[property] as DrawingStateValue) = context[property]
   }
+  state.lineDash = context.getLineDash()
+  state.transform = context.getTransform()
   return state
 }
 
@@ -50,10 +66,21 @@ export function readDrawingState(
 export function writeDrawingState(
   context: CanvasRenderingContext2D,
   state: DrawingContext,
+  transformScale = 1,
 ) {
   for (const property of drawingState) {
     ;(context[property] as DrawingStateValue) = state[property]
   }
+  context.setLineDash(state.lineDash)
+  const { a, b, c, d, e, f } = state.transform
+  context.setTransform(
+    a * transformScale,
+    b * transformScale,
+    c * transformScale,
+    d * transformScale,
+    e * transformScale,
+    f * transformScale,
+  )
 }
 
 /**

package/src/file/accept.ts

@@ -0,0 +1,58 @@
+/**
+ * What an `accept` rule is matched against.
+ *
+ * `File` satisfies it, and so does `DataTransferItem` — which matters while a
+ * drag is still in the air, since the browser reports the type of what is
+ * being dragged but withholds the name.
+ */
+export interface AcceptCandidate {
+  /** The file name, when it is known. */
+  name?: string
+  /** The MIME type, or `''` when the browser has no type for it. */
+  type: string
+}
+
+/**
+ * Does a file satisfy an `accept` attribute?
+ *
+ * `accept` is written the way the HTML attribute is: a comma separated list of
+ * extensions (`.wav`), MIME types (`audio/wav`) and type groups (`audio/*`).
+ * Anything that matches one entry is accepted, and an empty or missing
+ * `accept` takes everything.
+ *
+ * **The browser's own `accept` is only a hint to the file picker.** A person
+ * can switch it to "All Files", drag a file in, or pick one the picker was
+ * never asked about, so what arrives still has to be checked.
+ *
+ * A rule that cannot be decided is not treated as a rejection: with no `name`,
+ * an extension rule says nothing either way, and `accept=".wav"` reports a
+ * match rather than refusing a file it has not seen the name of. The name is
+ * there by the time the file is dropped, which is when the answer counts.
+ */
+export function matchesAccept(
+  candidate: AcceptCandidate,
+  accept?: string,
+): boolean {
+  const rules = (accept ?? '')
+    .split(',')
+    .map((rule) => rule.trim().toLowerCase())
+    .filter(Boolean)
+  if (rules.length === 0) return true
+
+  const name = candidate.name?.toLowerCase()
+  const type = candidate.type.toLowerCase()
+  let undecided = false
+
+  for (const rule of rules) {
+    if (rule.startsWith('.')) {
+      if (name === undefined) undecided = true
+      else if (name.endsWith(rule)) return true
+    } else if (rule.endsWith('/*')) {
+      if (type.startsWith(rule.slice(0, -1))) return true
+    } else if (type === rule) {
+      return true
+    }
+  }
+
+  return undecided
+}

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,26 +13,55 @@ 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,
   PERMISSION_DENIED,
+  UNAVAILABLE,
   type MIDIAccessError,
   type MIDIAccessInstance,
+  type MIDIAccessOptions,
   type MIDIAccessState,
 } from './midi/access'
 export {
   createMIDIInput,
+  PITCH_BEND_CENTER,
   type MIDIInputHandlers,
   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,
   type PianoInputInstance,
   type PianoInputOptions,
-} from './piano/input'
+} from './piano'
 export {
   createDrag,
   type DragInstance,
@@ -48,10 +77,18 @@ export {
   type DragValueMapping,
   type DragValueOptions,
   type MappingContext,
-} from './pointer/dragValue'
+} from './pointer/drag-value'
 export {
   createWheel,
   type WheelInstance,
   type WheelOptions,
 } from './pointer/wheel'
+export {
+  createSelectionBox,
+  selectionBoxCovers,
+  type SelectionBoxBeginOptions,
+  type SelectionBoxInstance,
+  type SelectionBoxOptions,
+  type SelectionBoxRect,
+} from './selection/box'
 export { toXY, type XY, type XYInput } from './xy'

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