@tremolo-ui/dom 0.6.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tremolo-ui/dom",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "framework-agnostic DOM layer used in @tremolo-ui/*",
   "type": "module",
   "sideEffects": false,
@@ -19,7 +19,7 @@
     "format": "prettier --write ."
   },
   "dependencies": {
-    "@tremolo-ui/functions": "^0.6.0"
+    "@tremolo-ui/functions": "^0.8.0"
   },
   "files": [
     "dist",

package/src/file/accept.ts

@@ -0,0 +1,75 @@
+/**
+ * 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
+}
+
+/**
+ * Split files into those that satisfy `accept` and those that do not, keeping
+ * their order. See {@link matchesAccept}.
+ */
+export function partitionByAccept(
+  files: Iterable<File>,
+  accept?: string,
+): { accepted: File[]; rejected: File[] } {
+  const accepted: File[] = []
+  const rejected: File[] = []
+  for (const file of files) {
+    if (matchesAccept(file, accept)) accepted.push(file)
+    else rejected.push(file)
+  }
+  return { accepted, rejected }
+}

package/src/file/drop-zone.ts

@@ -0,0 +1,200 @@
+import { matchesAccept, partitionByAccept } 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. It comes after `onDrop` for the same drop, so a list
+   * of rejected files can be cleared in `onDrop` and filled here.
+   */
+  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 { accepted, rejected } = partitionByAccept(
+      event.dataTransfer?.files ?? [],
+      opts.accept,
+    )
+
+    const taken = opts.multiple ? accepted : accepted.slice(0, 1)
+    if (taken.length > 0) opts.onDrop?.(taken, event)
+    if (rejected.length > 0) opts.onReject?.(rejected, 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,52 @@ export {
   type DrawingState,
   type DrawingStateValue,
 } from './canvas/context'
+export {
+  matchesAccept,
+  partitionByAccept,
+  type AcceptCandidate,
+} from './file/accept'
+export {
+  createDropZone,
+  type DropZoneInstance,
+  type DropZoneOptions,
+  type DropZoneState,
+} from './file/drop-zone'
+export { applyDelta } from './input/apply-delta'
+export { checkSteps, type CheckStepsOptions } from './input/check-steps'
+export {
+  DEFAULT_DRAG_SENSITIVITY,
+  DEFAULT_KEYBOARD_OPTIONS,
+  DEFAULT_WHEEL_OPTIONS,
+} from './input/defaults'
+export {
+  arrowKeyDirection,
+  arrowKeyMove,
+  isArrowKey,
+  wheelDirection,
+  wheelMove,
+  type ArrowKey,
+  type AxisMove,
+  type WheelDirectionOptions,
+} from './input/direction'
+export {
+  mapModifier,
+  selectModifier,
+  type InputEventOption,
+  type Modifier,
+  type ModifierMap,
+  type ModifierState,
+  type ModifierValue,
+} from './input/modifiers'
+export {
+  KNOB_VIEWBOX_SIZE,
+  knobAngles,
+  knobArcPath,
+  knobArcPoint,
+  knobArcRadius,
+  type KnobAngleOptions,
+  type KnobAngles,
+} from './knob/geometry'
 export {
   createMIDIAccess,
   NOT_SUPPORTED,
@@ -30,12 +76,59 @@ export {
   type MIDIInputInstance,
 } from './midi/input'
 export { createMIDIMessage, type MIDIMessageInstance } from './midi/message'
+export {
+  createStepperDrag,
+  type StepperDragInstance,
+  type StepperDragOptions,
+} from './number-input/stepper-drag'
+export {
+  commitNumberInputText,
+  numberInputBounds,
+  numberInputRanges,
+  nudgeNumberInput,
+  type NumberInputRanges,
+  type NumberInputValueOptions,
+} from './number-input/value'
+export {
+  caretAtDecimalOffset,
+  caretDecimalOffset,
+  numberSpan,
+  parseNumberText,
+  type NumberSpan,
+} from './number-input/text'
+export { replaceOptions } from './options/replace'
+export {
+  blackKeyWidth,
+  fitWhiteKeyWidth,
+  getNoteRangeArray,
+  noteAt,
+  notePosition,
+  pianoWidth,
+  type NoteRange,
+  type PianoLayout,
+} from './piano/layout'
+export {
+  SHORTCUTS,
+  type KeyboardShortcuts,
+  type KeyboardShortcutsScope,
+} from './piano/shortcuts'
 export {
   createPianoInput,
   type NoteSource,
   type PianoInputInstance,
   type PianoInputOptions,
 } from './piano'
+export {
+  clampPoint,
+  createPointsEditor,
+  POINT_AXIS,
+  POINTS_EDITOR_DEFAULT_KEYBOARD,
+  POINTS_EDITOR_DEFAULT_WHEEL,
+  type PointPosition,
+  type PointsEditorInstance,
+  type PointsEditorOptions,
+  type PointsEditorPoint,
+} from './points-editor'
 export {
   createDrag,
   type DragInstance,
@@ -52,11 +145,17 @@ export {
   type DragValueOptions,
   type MappingContext,
 } from './pointer/drag-value'
+export {
+  createLongPress,
+  type LongPressInstance,
+  type LongPressOptions,
+} from './pointer/long-press'
 export {
   createWheel,
   type WheelInstance,
   type WheelOptions,
 } from './pointer/wheel'
+export { valuePercent } from './position'
 export {
   createSelectionBox,
   selectionBoxCovers,
@@ -65,4 +164,6 @@ export {
   type SelectionBoxOptions,
   type SelectionBoxRect,
 } from './selection/box'
+export { sliderMarks, type MarksOptions, type SliderMark } from './slider/marks'
+export { cssLength, visuallyHiddenStyle } from './style'
 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)
+}

package/src/input/check-steps.ts

@@ -0,0 +1,144 @@
+import { linearScale, type ValueRange } from '@tremolo-ui/functions'
+
+import { applyDelta } from './apply-delta'
+import {
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+} from './modifiers'
+
+/** Positions probed across the travel. The ends are left out so that the
+ * clamp at `min` and `max` cannot be mistaken for a press that does nothing. */
+const PROBES = [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]
+
+const NONE: ModifierState = {
+  shiftKey: false,
+  altKey: false,
+  ctrlKey: false,
+  metaKey: false,
+}
+
+const MODIFIER_STATE: Record<string, ModifierState> = {
+  shift: { ...NONE, shiftKey: true },
+  alt: { ...NONE, altKey: true },
+  ctrl: { ...NONE, ctrlKey: true },
+  meta: { ...NONE, metaKey: true },
+}
+
+/** The held keys that select each entry of a modifier-aware input option. */
+function entries(options: ModifierValue<InputEventOption>): ModifierState[] {
+  if (Array.isArray(options)) return [NONE]
+  return Object.keys(options).map((key) => MODIFIER_STATE[key] ?? NONE)
+}
+
+interface Outcome {
+  /** The press changed the value at least once across the travel. */
+  moved: boolean
+  /** The change reached the displayed text at least once. */
+  visible: boolean
+}
+
+/**
+ * Press every entry of `options` at nine points along the travel and report
+ * whether anything came of it.
+ *
+ * Run against `applyDelta` itself rather than against a reading of `step`:
+ * the whole point is that the amount, the step and the scale interact, and
+ * the pipeline is the only thing that knows how.
+ */
+function probe(
+  options: ModifierValue<InputEventOption>,
+  range: ValueRange,
+  format?: (value: number) => string,
+): Outcome {
+  const { min, max, scale = linearScale } = range
+  const outcome: Outcome = { moved: false, visible: false }
+  for (const modifiers of entries(options)) {
+    for (const position of PROBES) {
+      const value = scale.denormalize(position, min, max)
+      const up = applyDelta(value, 1, options, range, modifiers)
+      const down = applyDelta(value, -1, options, range, modifiers)
+      if (up !== value || down !== value) outcome.moved = true
+      if (!format) continue
+      const shown = format(value)
+      if (format(up) !== shown || format(down) !== shown) outcome.visible = true
+    }
+  }
+  return outcome
+}
+
+export interface CheckStepsOptions {
+  /** The component, for the message. */
+  component: string
+  /** The axis, for a component that has more than one. */
+  axis?: string
+  /**
+   * The range to probe, or `null` to check nothing. An unbounded input has no
+   * travel to sample, so `NumberInput` passes `null` when `min` and `max` are
+   * not both there.
+   */
+  range: ValueRange | null
+  keyboard?: ModifierValue<InputEventOption> | null
+  wheel?: ModifierValue<InputEventOption> | null
+  /**
+   * How the value is displayed, where the component shows one. Called with
+   * probe values only.
+   */
+  format?: (value: number) => string
+}
+
+/**
+ * The warnings to show when a key press or a wheel notch cannot produce a
+ * change the user can see. Empty when there is nothing to say.
+ *
+ * Two settings that are each fine on their own can cancel out, and nothing
+ * fails when they do — the control simply sits there:
+ *
+ * - **`step` coarser than the amount.** `keyboard={['raw', 0.1]}` with
+ *   `step={1}` rounds every press straight back to where it started
+ * - **the display coarser than the amount.** A `format` showing two decimals
+ *   of a kHz value cannot show a press worth 1 Hz
+ *
+ * The second is only reported when the press is invisible at *every* point
+ * along the travel. A display that rounds is a deliberate choice and is
+ * normally right — it is being too coarse everywhere that makes it a mistake.
+ *
+ * **Meant for development builds only.** It probes the whole travel, so call
+ * it behind an inline `process.env.NODE_ENV` check: the bundler then drops
+ * the call, and this function and its messages with it.
+ */
+export function checkSteps({
+  component,
+  axis,
+  range,
+  keyboard,
+  wheel,
+  format,
+}: CheckStepsOptions): string[] {
+  if (!range || !(range.min < range.max)) return []
+  const where = axis ? `${component} (${axis})` : component
+  const warnings: string[] = []
+  for (const [name, options] of [
+    ['keyboard', keyboard],
+    ['wheel', wheel],
+  ] as const) {
+    if (!options) continue
+    const { moved, visible } = probe(options, range, format)
+    if (!moved) {
+      warnings.push(
+        `[tremolo-ui] ${where}: \`${name}\` cannot move the value.` +
+          (range.step !== undefined
+            ? ` Each press is smaller than \`step\` (${range.step}), so it rounds`
+            : ' Each press rounds') +
+          ' straight back to where it started.',
+      )
+    } else if (format && !visible) {
+      warnings.push(
+        `[tremolo-ui] ${where}: \`${name}\` moves the value, but \`format\`` +
+          ' shows the same text before and after, everywhere in the range.' +
+          ' The display is too coarse for it to be seen.',
+      )
+    }
+  }
+  return warnings
+}

package/src/input/defaults.ts

@@ -0,0 +1,32 @@
+import { type InputEventOption, type ModifierValue } from './modifiers'
+
+/**
+ * The keyboard amount used by Knob, NumberInput, Slider, and XYPad by default:
+ * 1 per press in the units of the value, and 0.1 with shift held. That is one
+ * `step` only while `step` is 1; a coarser `step` rounds 1 straight back, which
+ * `checkSteps` warns about.
+ *
+ * A modifier entry is not snapped to `step`, which is what lets the finer
+ * amount move at all — see `applyDelta`.
+ */
+export const DEFAULT_KEYBOARD_OPTIONS: ModifierValue<InputEventOption> = {
+  default: ['raw', 1],
+  shift: ['raw', 0.1],
+}
+
+/**
+ * The wheel amount used by Knob, NumberInput, Slider, and XYPad by default.
+ *
+ * Browsers turn shift+wheel into horizontal scrolling, which empties `deltaY`
+ * and fills `deltaX`, so no modifier is bound here.
+ */
+export const DEFAULT_WHEEL_OPTIONS: ModifierValue<InputEventOption> = ['raw', 1]
+
+/**
+ * The drag sensitivity used by value controls by default. Shift makes the
+ * same movement cover a tenth of the range, matching the arrow keys.
+ */
+export const DEFAULT_DRAG_SENSITIVITY: ModifierValue<number> = {
+  default: 1,
+  shift: 0.1,
+}