@tremolo-ui/functions 0.5.0 → 0.7.0

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/piano.ts

@@ -1,163 +0,0 @@
-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)
-  )
-}
-
-/** 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 {
-  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] +
-    (octave + octaveOffset) * 7
-
-  return isBlackKey(note)
-    ? whiteKeysIn * slot - blackKeyWidth(layout) / 2
-    : whiteKeysIn * slot
-}
-
-/**
- * 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 (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/types.ts

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

package/src/util.ts

@@ -1,42 +0,0 @@
-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
-}