@tremolo-ui/functions 0.4.0 → 0.6.0

package/src/modifiers.ts

@@ -0,0 +1,141 @@
+/**
+ * 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>
+
+export interface SelectedInputEvent {
+  option: InputEventOption
+  /** Which modifier entry was chosen, or `null` for `default`. */
+  modifier: Modifier | null
+}
+
+/**
+ * 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
+}
+
+/**
+ * Pick the amount that applies, given the modifier keys being held.
+ *
+ * @example
+ * selectInputEvent({ default: ['raw', 1], shift: ['raw', 0.1] }, event)
+ */
+export function selectInputEvent(
+  options: ModifierValue<InputEventOption>,
+  modifiers?: ModifierState,
+): SelectedInputEvent {
+  const { value, modifier } = selectModifier(options, modifiers)
+  return { option: value, modifier }
+}

package/src/piano.ts

@@ -0,0 +1,177 @@
+import { isBlackKey, isWhiteKey, noteKey, noteKeys, type NoteKey } from './midi'
+
+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
+}

package/src/scales.ts

@@ -0,0 +1,338 @@
+import { clamp, normalizeValue, rawValue, stepValue, toPrecision } from './math'
+import {
+  type InputEventOption,
+  type ModifierState,
+  type ModifierValue,
+  selectInputEvent,
+} from './modifiers'
+
+/**
+ * How a value is distributed across the travel of a control.
+ *
+ * `normalize` and `denormalize` are inverses of each other: the position is
+ * 0 at `min` and 1 at `max`, and everything in between is up to the scale.
+ *
+ * `min` and `max` are arguments rather than baked into the scale, so a scale
+ * holds no state and can be a module level constant. Passing the same object
+ * on every render therefore costs nothing.
+ *
+ * @example
+ * ```ts
+ * exponentialScale.denormalize(0.5, 20, 20000) // 632.45…
+ * ```
+ */
+export interface Scale {
+  /** Value to its position on the travel, 0-1. */
+  normalize: (value: number, min: number, max: number) => number
+  /** Position on the travel, 0-1, back to a value. */
+  denormalize: (position: number, min: number, max: number) => number
+}
+
+function assertRange(min: number, max: number) {
+  if (min >= max) throw new RangeError('requirements: min < max')
+}
+
+function assertPositiveFinite(value: number, name: string) {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new RangeError(`${name}: requirements: finite and greater than 0`)
+  }
+}
+
+/**
+ * Equal travel gives an equal change in value.
+ *
+ * The right default for anything already linear in perception: dB values,
+ * pan, percentages, MIDI note numbers, semitones.
+ */
+export const linearScale: Scale = {
+  normalize: (value, min, max) => normalizeValue(value, min, max),
+  denormalize: (position, min, max) => rawValue(position, min, max),
+}
+
+/**
+ * The power law of JUCE's `NormalisableRange::skew`, applied to `value - min`.
+ *
+ * Use it when the value has to agree with a JUCE or iPlug2 parameter — a
+ * plugin UI in a WebView, say, where the knob must sit exactly where the
+ * host's automation curve puts it. {@link skewWithCenterValue} gives the
+ * factor that places a chosen value at the middle of the travel.
+ *
+ * `skew < 1` gives the lower end more travel, `skew > 1` the upper end.
+ *
+ * For new designs prefer {@link exponentialScale} or {@link curveScale}: the
+ * slope of this curve is either zero or infinite at `min`, so the bottom of
+ * the range is a dead zone or jumps.
+ *
+ * @param skew the JUCE skew factor
+ */
+export function skewScale(skew: number): Scale {
+  assertPositiveFinite(skew, 'skewScale')
+  return {
+    // The two expressions JUCE uses, kept verbatim so the numbers agree with
+    // a NormalisableRange: pow() one way, exp(log()) the other.
+    normalize: (value, min, max) =>
+      Math.pow(normalizeValue(value, min, max), skew),
+    denormalize: (position, min, max) =>
+      rawValue(
+        skew === 1
+          ? position
+          : Math.exp(Math.log(clamp(position, 0, 1)) / skew),
+        min,
+        max,
+      ),
+  }
+}
+
+/**
+ * The skew factor for {@link skewScale} that puts `centerValue` at the middle
+ * of the travel — JUCE's `NormalisableRange::setSkewForCentre`.
+ */
+export function skewWithCenterValue(
+  centerValue: number,
+  min: number,
+  max: number,
+) {
+  assertRange(min, max)
+  if (!(min < centerValue && centerValue < max))
+    throw new RangeError('requirements: min < centerValue < max')
+  return Math.log(0.5) / Math.log((centerValue - min) / (max - min))
+}
+
+/**
+ * Equal travel gives an equal *ratio*, so an octave — or a percentage — takes
+ * the same distance wherever it falls.
+ *
+ * The scale for frequency (a filter cutoff over 20-20000 Hz), free running
+ * rates, and delay times.
+ *
+ * Requires `min` and `max` to be non-zero and of the same sign, since no
+ * ratio reaches zero or crosses it. Use {@link curveScale} for a range that
+ * starts at 0.
+ */
+export const exponentialScale: Scale = {
+  normalize: (value, min, max) => {
+    assertExponentialRange(min, max)
+    // The value is clamped before the logarithm, not after: outside the range
+    // the ratio can be negative, and log() would give NaN rather than a
+    // position to clamp.
+    const start = Math.log(Math.abs(min))
+    const end = Math.log(Math.abs(max))
+    return clamp(
+      (Math.log(Math.abs(clamp(value, min, max))) - start) / (end - start),
+      0,
+      1,
+    )
+  },
+  denormalize: (position, min, max) => {
+    assertExponentialRange(min, max)
+    const start = Math.log(Math.abs(min))
+    const end = Math.log(Math.abs(max))
+    const magnitude = Math.exp(start + (end - start) * clamp(position, 0, 1))
+    return Math.sign(min) * magnitude
+  },
+}
+
+function assertExponentialRange(min: number, max: number) {
+  assertRange(min, max)
+  if (min === 0 || max === 0 || Math.sign(min) !== Math.sign(max)) {
+    throw new RangeError(
+      'exponentialScale: requirements: min and max are non-zero and have the same sign',
+    )
+  }
+}
+
+/**
+ * An exponential bend that still passes exactly through `min` and `max`, so
+ * unlike {@link exponentialScale} it works on a range that starts at 0 or
+ * crosses it, and unlike {@link skewScale} its slope is neither zero nor
+ * infinite at either end.
+ *
+ * The general purpose taper, and the same family as the curve of an envelope
+ * segment (SuperCollider's `CurveWarp`).
+ *
+ * - `curve > 0` gives the lower end more travel — envelope times from 0 ms,
+ *   delay times, anything that wants fine control near the bottom
+ * - `curve < 0` gives the upper end more travel — a volume fader over
+ *   -60..+6 dB that should be precise around 0 dB
+ * - near 0 it is indistinguishable from {@link linearScale}, and is treated
+ *   as linear to avoid dividing by zero
+ *
+ * {@link curveWithCenterValue} gives the curve that places a chosen value at
+ * the middle of the travel.
+ *
+ * @param curve how hard the curve bends, and in which direction
+ */
+export function curveScale(curve: number): Scale {
+  // Beyond this the flatter half of the curve no longer has enough distinct
+  // double values for normalize and denormalize to remain inverses.
+  if (!Number.isFinite(curve) || Math.abs(curve) > 32) {
+    throw new RangeError(
+      'curveScale: requirements: finite curve from -32 to 32',
+    )
+  }
+  // The two coefficients blow up as the curve flattens: `a` divides by
+  // 1 - e^curve, which goes to 0.
+  if (Math.abs(curve) < 0.001) return linearScale
+
+  return {
+    normalize: (value, min, max) => {
+      assertRange(min, max)
+      const proportion = clamp((value - min) / (max - min), 0, 1)
+      if (proportion === 0 || proportion === 1) return proportion
+      if (curve > 0) {
+        return (
+          1 + Math.log(proportion + (1 - proportion) * Math.exp(-curve)) / curve
+        )
+      }
+      return Math.log1p(proportion * Math.expm1(curve)) / curve
+    },
+    denormalize: (position, min, max) => {
+      assertRange(min, max)
+      const p = clamp(position, 0, 1)
+      if (p === 0) return min
+      if (p === 1) return max
+      const proportion =
+        curve > 0
+          ? (Math.exp(curve * (p - 1)) * (1 - Math.exp(-curve * p))) /
+            (1 - Math.exp(-curve))
+          : Math.expm1(curve * p) / Math.expm1(curve)
+      return min + (max - min) * proportion
+    },
+  }
+}
+
+/**
+ * {@link skewScale} mirrored about the middle of the range, so both halves
+ * bend the same way — JUCE's `symmetricSkew`.
+ *
+ * For a bipolar control whose centre matters: detune over -100..+100 cents,
+ * or a bipolar filter envelope amount, where the fine adjustment is around 0
+ * rather than at either end.
+ *
+ * `skew < 1` gives the middle more travel, `skew > 1` the two ends.
+ *
+ * @param skew the JUCE skew factor
+ */
+export function symmetricSkewScale(skew: number): Scale {
+  assertPositiveFinite(skew, 'symmetricSkewScale')
+  return {
+    normalize: (value, min, max) => {
+      assertRange(min, max)
+      const proportion = clamp((value - min) / (max - min), 0, 1)
+      if (skew === 1) return proportion
+      const distanceFromMiddle = 2 * proportion - 1
+      return (
+        (1 +
+          Math.pow(Math.abs(distanceFromMiddle), skew) *
+            Math.sign(distanceFromMiddle)) /
+        2
+      )
+    },
+    denormalize: (position, min, max) => {
+      assertRange(min, max)
+      const p = clamp(position, 0, 1)
+      let distanceFromMiddle = 2 * p - 1
+      if (skew !== 1 && distanceFromMiddle !== 0) {
+        distanceFromMiddle =
+          Math.pow(Math.abs(distanceFromMiddle), 1 / skew) *
+          Math.sign(distanceFromMiddle)
+      }
+      return min + ((max - min) / 2) * (1 + distanceFromMiddle)
+    },
+  }
+}
+
+/**
+ * The curve for {@link curveScale} that puts `centerValue` at the middle of
+ * the travel — the counterpart of {@link skewWithCenterValue}.
+ */
+export function curveWithCenterValue(
+  centerValue: number,
+  min: number,
+  max: number,
+) {
+  assertRange(min, max)
+  if (!(min < centerValue && centerValue < max)) {
+    throw new RangeError('requirements: min < centerValue < max')
+  }
+  // value(0.5) - min = range / (1 + e^(curve / 2))
+  const proportion = (centerValue - min) / (max - min)
+  return 2 * Math.log(1 / proportion - 1)
+}
+
+/**
+ * How a value is scaled: the range it lives in, how it is rounded, and how it
+ * is distributed across the travel.
+ *
+ * `AxisOptions` of `@tremolo-ui/dom` extends this, so a drag and a
+ * wheel / keyboard nudge run the same value pipeline.
+ */
+export interface ValueRange {
+  min: number
+  max: number
+  /**
+   * Rounding applied to the value. Left unrounded when omitted.
+   */
+  step?: number
+  /**
+   * How the value is distributed across the travel.
+   *
+   * @default linearScale
+   */
+  scale?: Scale
+}
+
+/**
+ * Move a value by an amount of input, as reported by a wheel or an arrow key.
+ *
+ * The pipeline matches `createDragValue` of `@tremolo-ui/dom`: 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 selectInputEvent}.
+ *
+ * @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 {
+  assertRange(min, max)
+  if (step !== undefined) assertPositiveFinite(step, 'applyDelta step')
+
+  const {
+    option: [mode, amount],
+    modifier,
+  } = selectInputEvent(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)
+}