@tremolo-ui/dom 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tremolo-ui/dom",
-  "version": "0.7.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.7.0"
+    "@tremolo-ui/functions": "^0.8.0"
   },
   "files": [
     "dist",

package/src/file/accept.ts

@@ -56,3 +56,20 @@ export function matchesAccept(
 
   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

@@ -1,4 +1,4 @@
-import { matchesAccept } from './accept'
+import { matchesAccept, partitionByAccept } from './accept'
 
 /** What is in the air over the element. */
 export interface DropZoneState {
@@ -41,7 +41,8 @@ export interface DropZoneOptions {
   onDrop?: (files: File[], event: DragEvent) => void
   /**
    * Called with the dropped files that do not match `accept`, so that the
-   * reason can be shown.
+   * 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. */
@@ -146,17 +147,14 @@ export function createDropZone(
     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)
-    }
+    const { accepted, rejected } = partitionByAccept(
+      event.dataTransfer?.files ?? [],
+      opts.accept,
+    )
 
-    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)
+    if (rejected.length > 0) opts.onReject?.(rejected, event)
   }
 
   /**

package/src/index.ts

@@ -13,7 +13,11 @@ export {
   type DrawingState,
   type DrawingStateValue,
 } from './canvas/context'
-export { matchesAccept, type AcceptCandidate } from './file/accept'
+export {
+  matchesAccept,
+  partitionByAccept,
+  type AcceptCandidate,
+} from './file/accept'
 export {
   createDropZone,
   type DropZoneInstance,
@@ -21,6 +25,22 @@ export {
   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,
@@ -30,6 +50,15 @@ export {
   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,
@@ -47,8 +76,30 @@ 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,
@@ -56,12 +107,28 @@ export {
   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,
@@ -78,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,
@@ -91,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/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,
+}

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