@tremolo-ui/functions 0.5.0 → 0.6.0

package/src/piano.ts

@@ -84,33 +84,14 @@ export function blackKeyWidth(layout: PianoLayout): number {
   )
 }
 
-/** Width of the whole keyboard in pixels. */
-export function pianoWidth(layout: PianoLayout): number {
-  const whiteKeys = getNoteRangeArray(layout.noteRange).filter(isWhiteKey)
-  return (
-    (layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP)) *
-    whiteKeys.length
-  )
-}
-
-/**
- * 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 {
+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)
-  // A note whose pitch class comes before the first one belongs to the octave
-  // above the one the division above gives.
   const octaveOffset =
     noteKeys.indexOf(first) > noteKeys.indexOf(target) ? 1 : 0
-
   const whiteKeysIn =
     whiteKeysBefore[target] -
     whiteKeysBefore[first] +
@@ -121,6 +102,39 @@ export function notePosition(note: number, layout: PianoLayout): number {
     : 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.
  *
@@ -138,7 +152,7 @@ export function noteAt(
   height: number,
   layout: PianoLayout,
 ): number | null {
-  if (y < 0 || y >= height) return null
+  if (x < 0 || x >= pianoWidth(layout) || y < 0 || y >= height) return null
 
   const notes = getNoteRangeArray(layout.noteRange)
   const blackHeight =

package/src/scales.ts

@@ -1,6 +1,10 @@
-import { clamp, normalizeValue, rawValue, stepValue } from './math'
-
-import type { InputEventOption } from './types'
+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.
@@ -28,6 +32,12 @@ 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.
  *
@@ -56,6 +66,7 @@ export const linearScale: Scale = {
  * @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.
@@ -81,8 +92,9 @@ export function skewWithCenterValue(
   min: number,
   max: number,
 ) {
-  if (!(min <= centerValue && centerValue <= max))
-    throw new RangeError('requirements: min <= centerValue <= max')
+  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))
 }
 
@@ -103,15 +115,20 @@ export const exponentialScale: Scale = {
     // 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(clamp(value, min, max) / min) / Math.log(max / min),
+      (Math.log(Math.abs(clamp(value, min, max))) - start) / (end - start),
       0,
       1,
     )
   },
   denormalize: (position, min, max) => {
     assertExponentialRange(min, max)
-    return min * Math.pow(max / min, clamp(position, 0, 1))
+    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
   },
 }
 
@@ -146,31 +163,40 @@ function assertExponentialRange(min: number, max: number) {
  * @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
 
-  const grow = Math.exp(curve)
-
-  // value(position) = b - a * e^(curve * position), fixed so that
-  // value(0) = min and value(1) = max.
-  const coefficients = (min: number, max: number) => {
-    const a = (max - min) / (1 - grow)
-    return { a, b: min + a }
-  }
-
   return {
     normalize: (value, min, max) => {
       assertRange(min, max)
-      const { a, b } = coefficients(min, max)
-      // Clamped before the logarithm: far outside the range `(b - value) / a`
-      // turns negative and log() would give NaN.
-      return clamp(Math.log((b - clamp(value, min, max)) / a) / curve, 0, 1)
+      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 { a, b } = coefficients(min, max)
-      return b - a * Math.pow(grow, clamp(position, 0, 1))
+      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
     },
   }
 }
@@ -188,6 +214,7 @@ export function curveScale(curve: number): Scale {
  * @param skew the JUCE skew factor
  */
 export function symmetricSkewScale(skew: number): Scale {
+  assertPositiveFinite(skew, 'symmetricSkewScale')
   return {
     normalize: (value, min, max) => {
       assertRange(min, max)
@@ -265,20 +292,47 @@ export interface ValueRange {
  * @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,
-  [mode, amount]: InputEventOption,
+  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'
+    mode === 'normalized'
       ? scale.denormalize(scale.normalize(value, min, max) + x, min, max)
       : value + x
-  return clamp(step ? stepValue(next, step) : next, min, max)
+
+  // 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/unit.ts

@@ -1,73 +1,204 @@
+import { toPrecision } from './math'
+
 /**
- * Units a value can be displayed in, as `[symbol, scale]` pairs ordered from
- * the smallest scale up. A value is shown in the largest unit that does not
- * exceed it.
+ * The SI prefixes {@link unitFormat} chooses between.
  *
- * @example
- * [['Hz', 1], ['kHz', 1000]]
- * [['ms', 1], ['s', 1000]]
+ * Deliberately narrower than the full SI set: yocto through yotta are of no
+ * use to an audio control, and every extra prefix is one more symbol `parse`
+ * has to tell apart from a unit.
  */
-export type Units = [string, number][]
+export type SIPrefix = 'p' | 'n' | 'µ' | 'm' | '' | 'k' | 'M' | 'G'
+
+/** Ordered small to large. The empty symbol is the base unit. */
+const PREFIXES: readonly [SIPrefix, number][] = [
+  ['p', 1e-12],
+  ['n', 1e-9],
+  ['µ', 1e-6],
+  ['m', 1e-3],
+  ['', 1],
+  ['k', 1e3],
+  ['M', 1e6],
+  ['G', 1e9],
+]
+
+const PREFIX_SCALE = new Map<string, number>(PREFIXES)
 
 /**
- * Pick the unit a value is displayed in: the largest one whose scale does not
- * exceed the magnitude of the value.
+ * Micro is written three ways. `µ` (U+00B5 MICRO SIGN) is what `format`
+ * writes and what d3-format uses, `μ` (U+03BC GREEK SMALL LETTER MU) looks
+ * identical and is what a Greek keyboard produces, and `u` is what everyone
+ * actually types. All three read back the same.
  */
-export function selectUnit(units: Units, value: number): [string, number] {
-  let i = 0
-  for (; i < units.length; i++) {
-    if (Math.abs(units[i][1]) > Math.abs(value)) break
-  }
-  return units[Math.max(0, i - 1)]
+const MICRO_ALIASES: Record<string, SIPrefix> = { μ: 'µ', u: 'µ' }
+
+export interface UnitFormatOptions {
+  /**
+   * The prefix the stored value is already in.
+   *
+   * A control that keeps milliseconds in `value` is `{ base: 'm' }` with a
+   * unit of `'s'`: 1500 then displays as `1.5s`, and `parse` gives 1500 back.
+   *
+   * @default ''
+   */
+  base?: SIPrefix
+  /**
+   * Whether to scale the number and pick a prefix at all.
+   *
+   * Turn it off for anything that is not an SI quantity. dB, %, cents and
+   * semitones do not take prefixes, and `-6dB` read as "-6 deci-B" is wrong
+   * rather than merely unusual.
+   *
+   * @default true
+   */
+  prefixes?: boolean
+  /**
+   * Digits after the decimal point. The number is left as-is when omitted.
+   */
+  digits?: number
+  /**
+   * Text placed between the number and the unit.
+   * @default ''
+   */
+  separator?: string
+}
+
+/** The `format` / `parse` pair a `NumberInput` takes. */
+export interface UnitFormatter {
+  format: (value: number) => string
+  parse: (text: string) => number
 }
 
 /**
- * Render a value as text, in the unit that suits its magnitude.
- *
- * @param units a single symbol appended as-is, or a list to choose from.
- * @param digit digits after the decimal point. Left as-is when omitted.
+ * Divide by a prefix scale without showing the result of doing so in binary.
  *
- * @example
- * formatValue(1234, [['Hz', 1], ['kHz', 1000]], 2) // '1.23kHz'
- * formatValue(1.5, 'Hz')                           // '1.5Hz'
+ * `0.0005 / 1e-6` is 500.00000000000006, and with no `digits` to round it that
+ * lands in the input as written.
  */
-export function formatValue(
-  value: number,
-  units?: string | Units,
-  digit?: number,
-): string {
-  const fixed = (v: number) =>
-    digit != undefined ? v.toFixed(digit) : String(v)
-  if (!units || typeof units == 'string') {
-    return fixed(value) + (units ?? '')
-  }
-  const [unit, scale] = selectUnit(units, value)
-  return fixed(value / scale) + unit
+function scaleBy(value: number, scale: number): number {
+  return toPrecision(value / scale)
 }
 
+/** A number, then whatever followed it. */
+const NUMBER_THEN_REST =
+  /^([+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?)\s*(.*)$/
+
 /**
- * Read a value back out of text, undoing the scaling of {@link formatValue}.
+ * Build the `format` and `parse` of a unit, as one pair.
+ *
+ * They are returned together because they have to agree: a `format` that
+ * writes `1.23kHz` is only useful next to a `parse` that reads it back as
+ * 1230. Spread the result into the input.
  *
- * With a list of units the text has to be a number followed by an optional
- * unit and nothing else, since the unit decides the scale; anything else reads
- * as 0. With a single unit, or none, the first number found anywhere in the
- * text is taken, so a half-typed entry still yields something.
+ * @example
+ * unitFormat('Hz')                                 // 1234 -> '1.23kHz'
+ * unitFormat('s', { base: 'm' })                   // value in ms. 1500 -> '1.5s'
+ * unitFormat('s', { base: 'm', digits: 2 })        // 1500 -> '1.50s'
+ * unitFormat('dB', { prefixes: false, digits: 1 }) // -6.25 -> '-6.3dB'
  *
  * @example
- * parseValue('1.23kHz', [['Hz', 1], ['kHz', 1000]]) // 1230
- * parseValue('4abc')                                // 4
+ * <NumberInput.Root {...unitFormat('Hz', { digits: 2 })} value={v} onChange={setV}>
  */
-export function parseValue(text: string, units?: string | Units): number {
-  const str = text.trim()
+export function unitFormat(
+  unit: string,
+  options: UnitFormatOptions = {},
+): UnitFormatter {
+  const { base = '', prefixes = true, digits, separator = '' } = options
+  if (unit === '' && base !== '') {
+    throw new RangeError('unitFormat: base requires a non-empty unit')
+  }
+  const baseScale = PREFIX_SCALE.get(base) ?? 1
+
+  /**
+   * `toFixed` renders anything that rounds to zero from below as `-0`, which
+   * is never what a control should show.
+   */
+  const fixed = (value: number) => {
+    const text = digits !== undefined ? value.toFixed(digits) : String(value)
+    return Number(text) === 0 ? text.replace('-', '') : text
+  }
 
-  if (!units || typeof units == 'string') {
-    const m = str.match(/-?\d+(\.\d+)?/)
-    const v = Number(m?.[0] ?? '0')
-    return isNaN(v) ? 0 : v
+  if (!prefixes) {
+    // The stored value goes out untouched, so the symbol has to name the unit
+    // it is already in.
+    const symbol = base + unit
+    return {
+      format: (value) =>
+        Number.isFinite(value)
+          ? fixed(value) + separator + symbol
+          : String(value),
+      // Nothing after the number can change the scale, so it is all ignored:
+      // the number in front is the value, half-typed or not.
+      parse: (text) => {
+        const match = text.trim().match(NUMBER_THEN_REST)
+        if (!match) return NaN
+        const value = Number(match[1])
+        return Number.isFinite(value) ? value : NaN
+      },
+    }
   }
 
-  const m = str.match(/^(-?\d+(\.\d+)?)\s*(\w*)$/)
-  if (!m) return 0
-  const found = units.find(([unit]) => unit == m[3])
-  return (Number(m[1]) || 0) * (found ? found[1] : 1)
+  return {
+    format: (value) => {
+      if (!Number.isFinite(value)) return String(value)
+      const si = value * baseScale
+      // Zero has no magnitude to read, so it stays in the base unit.
+      let index = PREFIXES.findIndex(([, scale]) => scale === 1)
+      if (si !== 0) {
+        // The largest prefix that leaves at least one digit before the point.
+        // Below the smallest prefix the number just gets small: `p` is the
+        // floor, as `G` is the ceiling.
+        const magnitude = Math.abs(si)
+        index = 0
+        for (let i = PREFIXES.length - 1; i >= 0; i--) {
+          if (magnitude >= PREFIXES[i][1]) {
+            index = i
+            break
+          }
+        }
+      }
+      let text = fixed(scaleBy(si, PREFIXES[index][1]))
+      // Rounding can carry the number up out of its own prefix — 999.99Hz at
+      // one digit is 1000.0Hz, which should read 1.0kHz. One step is always
+      // enough, since the carry is at most a factor of ten.
+      if (Math.abs(Number(text)) >= 1000 && index < PREFIXES.length - 1) {
+        index += 1
+        text = fixed(scaleBy(si, PREFIXES[index][1]))
+      }
+      return text + separator + PREFIXES[index][0] + unit
+    },
+
+    parse: (text) => {
+      const match = text.trim().match(NUMBER_THEN_REST)
+      if (!match) return NaN
+      const number = Number(match[1])
+      if (!Number.isFinite(number)) return NaN
+
+      let suffix = match[2].trim()
+      const separatorText = separator.trim()
+      if (separatorText !== '' && suffix.startsWith(separatorText)) {
+        suffix = suffix.slice(separatorText.length).trim()
+      }
+      // A bare number is in the unit the value is stored in, which is what
+      // the input shows once the format is stripped.
+      if (suffix === '') return number
+
+      // The unit symbol is matched first, so a unit that is itself a prefix
+      // letter wins over the prefix reading: `5m` for a unit of `m` is five
+      // metres, not five milli-.
+      let prefix: string | null = null
+      if (unit !== '' && suffix.endsWith(unit)) {
+        prefix = suffix.slice(0, suffix.length - unit.length)
+      } else if (suffix.length <= 1) {
+        prefix = suffix
+      }
+      if (prefix === null) return number
+
+      const normalized = MICRO_ALIASES[prefix] ?? prefix
+      const scale = PREFIX_SCALE.get(normalized)
+      // Unrecognised text after the number is ignored rather than rejected,
+      // so that a half-typed entry still yields the number in front of it.
+      if (scale === undefined) return number
+      return (number * scale) / baseScale
+    },
+  }
 }

package/src/util.ts

@@ -1,42 +1,7 @@
-type Operator = '+' | '-' | '*' | '/'
-
-export function styleHelper(value: string | number): string
-export function styleHelper(
-  value: string | number,
-  op: Operator,
-  influencer?: number,
-): string
-export function styleHelper(
-  value: string | number,
-  op?: Operator,
-  influencer?: number,
-) {
-  if (op && influencer) {
-    if (typeof value == 'number') {
-      if (op == '+') return `${value + influencer}px`
-      if (op == '-') return `${value - influencer}px`
-      if (op == '*') return `${value * influencer}px`
-      if (op == '/') return `${value / influencer}px`
-    } else {
-      return `calc(${value}px ${op} ${influencer})`
-    }
-  } else {
-    if (typeof value == 'number') {
-      return `${value}px`
-    } else {
-      return value
-    }
-  }
-}
-
-export function isEmpty(obj: object) {
-  return Object.keys(obj).length == 0
-}
-
 export function mod(n: number, m: number) {
   return ((n % m) + m) % m
 }
 
 export function xor(a = false, b = false) {
-  return (a || b) && a != b
+  return (a || b) && a !== b
 }

package/src/types.ts

@@ -1,4 +0,0 @@
-/**
- * Options for setting the amount of keyboard and mouse wheel changes.
- */
-export type InputEventOption = ['normalized' | 'raw', number]