@tremolo-ui/functions 0.4.0 → 0.6.0

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":[],"sources":["../src/math.ts","../src/util.ts","../src/midi.ts"],"sourcesContent":["/**\n * clamp value between min and max\n */\nexport function clamp(value: number, min: number, max: number) {\n  return Math.max(min, Math.min(value, max))\n}\n\n/**\n * Normalize the value from 0 to 1\n */\nexport function normalizeValue(\n  rawValue: number,\n  min: number,\n  max: number,\n  skew = 1,\n) {\n  if (min >= max) throw new RangeError('requirements: min < max')\n  const v = clamp((rawValue - min) / (max - min), 0, 1)\n  return Math.pow(v, skew)\n}\n\n/**\n * Convert normalized values back to raw values.\n */\nexport function rawValue(\n  normalizedValue: number,\n  min: number,\n  max: number,\n  skew = 1,\n) {\n  if (min >= max) throw new RangeError('requirements: min < max')\n  const v =\n    skew == 1\n      ? clamp(normalizedValue, 0, 1)\n      : Math.exp(Math.log(clamp(normalizedValue, 0, 1)) / skew)\n  return min + v * (max - min)\n}\n\nexport function skewWithCenterValue(\n  centerValue: number,\n  min: number,\n  max: number,\n) {\n  if (!(min <= centerValue && centerValue <= max))\n    throw new RangeError('requirements: min <= centerValue <= max')\n  return Math.log(0.5) / Math.log((centerValue - min) / (max - min))\n}\n\nexport function stepValue(value: number, step: number) {\n  if (step <= 0) throw new RangeError('requirements: step > 0')\n  const quotient = Math.floor(value / step)\n  const decimalDigits = decimalPart(step)?.length\n  const v = toFixed(quotient * step, decimalDigits)\n  const next = toFixed((quotient + 1) * step, decimalDigits)\n  return Math.abs(value - v) < Math.abs(value - next) ? v : next\n}\n\nexport function toFixed(x: number, fractionDigits?: number) {\n  return Number(x.toFixed(fractionDigits))\n}\n\nexport function integerPart(x: number | string): string | undefined {\n  if (Number.isNaN(x)) {\n    return undefined\n  }\n  return String(x).split('.')[0]\n}\n\nexport function decimalPart(x: number | string): string | undefined {\n  return String(x).split('.')[1]\n}\n\nexport function radian(degree: number) {\n  return (Math.PI * degree) / 180\n}\n\nexport function degree(radian: number) {\n  return (180 * radian) / Math.PI\n}\n\nexport function mapValue(\n  value: number,\n  inMin: number,\n  inMax: number,\n  outMin: number,\n  outMax: number,\n) {\n  return ((value - inMin) / (inMax - inMin)) * (outMax - outMin) + outMin\n}\n\nexport function dbToGain(db: number) {\n  return Math.pow(10, db / 20)\n}\n\nexport function gainToDb(gain: number) {\n  return 20 * (Math.log(gain) / Math.LN10)\n}\n","type Operator = '+' | '-' | '*' | '/'\n\nexport function styleHelper(value: string | number): string\nexport function styleHelper(\n  value: string | number,\n  op: Operator,\n  influencer?: number,\n): string\nexport function styleHelper(\n  value: string | number,\n  op?: Operator,\n  influencer?: number,\n) {\n  if (op && influencer) {\n    if (typeof value == 'number') {\n      if (op == '+') return `${value + influencer}px`\n      if (op == '-') return `${value - influencer}px`\n      if (op == '*') return `${value * influencer}px`\n      if (op == '/') return `${value / influencer}px`\n    } else {\n      return `calc(${value}px ${op} ${influencer})`\n    }\n  } else {\n    if (typeof value == 'number') {\n      return `${value}px`\n    } else {\n      return value\n    }\n  }\n}\n\nexport function isEmpty(obj: object) {\n  return Object.keys(obj).length == 0\n}\n\nexport function mod(n: number, m: number) {\n  return ((n % m) + m) % m\n}\n\nexport function xor(a = false, b = false) {\n  return (a || b) && a != b\n}\n","import { mod } from './util'\n\nexport const whiteKeys = ['A', 'B', 'C', 'D', 'E', 'F', 'G'] as const\n\nexport type WhiteKey = (typeof whiteKeys)[number]\n\nexport const noteKeys = [\n  'C',\n  'C#',\n  'D',\n  'D#',\n  'E',\n  'F',\n  'F#',\n  'G',\n  'G#',\n  'A',\n  'A#',\n  'B',\n] as const\n\nexport type NoteKey = (typeof noteKeys)[number]\n\nexport function parseNoteName(noteName: string) {\n  const m = noteName.match(/^([a-g])(#{0,2}|b{0,2})(-?\\d+)$/i)\n  if (!m) throw new Error('Invalid note name')\n  const [, letter, accidental, octave] = m\n  return {\n    letter: letter.toLocaleUpperCase() as WhiteKey,\n    accidental: accidental as '#' | '##' | 'b' | 'bb' | '',\n    octave: Number(octave),\n  }\n}\n\n/**\n * Convert noteName to noteNumber\n */\nexport function noteNumber(noteName: string) {\n  const { letter, accidental, octave } = parseNoteName(noteName)\n  const noteIndex = noteKeys.indexOf(letter.toLocaleUpperCase() as NoteKey)\n  const accidentalValue = (accidental[0] == 'b' ? -1 : 1) * accidental.length\n  return noteIndex + 12 * (Number(octave) + 1) + accidentalValue\n}\n\n/**\n * Convert noteNumber to noteName\n * C-1 = 0\n * G9 = 127\n * @param noteNumber noteNumber\n */\nexport function noteName(noteNumber: number): `${NoteKey}${number}` {\n  const noteIndex = mod(noteNumber, 12)\n  const octave = Math.floor(noteNumber / 12) - 1\n  return `${noteKeys[noteIndex]}${octave}`\n}\n\n/**\n * Convert noteNumber to noteKey\n */\nexport function noteKey(noteNumber: number): NoteKey {\n  return noteKeys[mod(noteNumber, 12)]\n}\n\n/**\n * @param note noteNumber: 0 ~ 127 or noteName e.g. 'C3'\n */\nexport function isWhiteKey(note: number | string) {\n  const n = typeof note == 'string' ? noteNumber(note) : note\n  return (\n    mod(n, 12) == 0 ||\n    mod(n, 12) == 2 ||\n    mod(n, 12) == 4 ||\n    mod(n, 12) == 5 ||\n    mod(n, 12) == 7 ||\n    mod(n, 12) == 9 ||\n    mod(n, 12) == 11\n  )\n}\n\n/**\n * @param note noteNumber: 0 ~ 127 or noteName e.g. 'C3'\n */\nexport function isBlackKey(note: number | string) {\n  return !isWhiteKey(note)\n}\n\n/**\n * @param note noteNumber: 0 ~ 127 or noteName e.g. 'C3'\n * @param detune [cent]\n * @param a4 A4 frequency [Hz]\n * @returns frequency [Hz]\n */\nexport function noteToFrequency(note: number | string, detune = 0, a4 = 440) {\n  const n = typeof note == 'string' ? noteNumber(note) : note\n  return (a4 / 32) * 2 ** ((n - 9 + detune / 100) / 12)\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../src/math.ts","../src/modifiers.ts","../src/scales.ts","../src/util.ts","../src/midi.ts","../src/piano.ts","../src/unit.ts"],"sourcesContent":["/**\n * clamp value between min and max\n */\nexport function clamp(value: number, min: number, max: number) {\n  return Math.max(min, Math.min(value, max))\n}\n\n/**\n * Normalize the value from 0 to 1, spreading the range evenly.\n *\n * This is the linear mapping and takes no curve of its own; a `Scale` builds\n * whatever curve it needs on top of it.\n */\nexport function normalizeValue(value: number, min: number, max: number) {\n  if (min >= max) throw new RangeError('requirements: min < max')\n  return clamp((value - min) / (max - min), 0, 1)\n}\n\n/**\n * Convert normalized values back to raw values, spreading the range evenly.\n *\n * The inverse of {@link normalizeValue}.\n */\nexport function rawValue(normalizedValue: number, min: number, max: number) {\n  if (min >= max) throw new RangeError('requirements: min < max')\n  return min + clamp(normalizedValue, 0, 1) * (max - min)\n}\n\n/**\n * Put a value on the grid the caller asked for, rounding a half step upwards.\n *\n * The rounding is done on the quotient rather than by comparing the distance\n * to the two neighbours, because both of those carry error of their own. The\n * quotient is cleared of its artefact first: `0.15 / 0.1` is 1.4999999999999998,\n * and a value sitting exactly on a half step would otherwise fall to whichever\n * side the last bit happened to land on — 0.25 rounded up while 0.15 and 0.35\n * rounded down.\n */\nexport function stepValue(value: number, step: number) {\n  if (step <= 0) throw new RangeError('requirements: step > 0')\n  const quotient = Math.round(toPrecision(value / step))\n  // The product has its own debris to drop: 3141593 * 1e-6 is not 3.141593.\n  const stepped = toPrecision(quotient * step)\n  // Math.round answers -0 for anything in [-0.5, 0), and that reaches the\n  // caller's onChange as a value that prints as 0 but is not it.\n  return stepped === 0 ? 0 : stepped\n}\n\nexport function toFixed(x: number, fractionDigits?: number) {\n  return Number(x.toFixed(fractionDigits))\n}\n\n/**\n * The significant decimal digits a double actually carries. A double holds a\n * little under 16, so anything past this is the binary representation showing\n * through rather than information.\n */\nexport const SIGNIFICANT_DIGITS = 15\n\n/**\n * Drop the binary artefact from a computed value.\n *\n * Arithmetic on doubles leaves debris in the last couple of digits, and it\n * accumulates: adding 0.1 to 5 twelve times gives 5.699999999999998 rather\n * than 5.7, and the display of a control shows exactly that. Rounding to the\n * digits a double can carry removes it, and adds nothing back — the value was\n * already the result of a calculation whose own error is that size or larger.\n *\n * This is not the same as rounding to a `step`. {@link stepValue} puts a value\n * on a grid the caller asked for and is a decision about the value; this only\n * removes what was never in the value to begin with.\n *\n * @param significantDigits how many digits to keep. The default is the only\n * one that is purely artefact removal; a smaller number starts discarding real\n * precision.\n *\n * @example\n * toPrecision(5.1 + 0.1) // 5.2, rather than 5.199999999999999\n */\nexport function toPrecision(x: number, significantDigits = SIGNIFICANT_DIGITS) {\n  // Zero has no significant digits to round to, and a non-finite value has no\n  // decimal form to parse back.\n  if (x === 0 || !Number.isFinite(x)) return x\n  const rounded = Number(x.toPrecision(significantDigits))\n  // Rounding up at the very top of the range overflows to Infinity, which is\n  // a worse answer than the artefact.\n  return Number.isFinite(rounded) ? rounded : x\n}\n\nexport function integerPart(x: number | string): string | undefined {\n  if (Number.isNaN(x)) {\n    return undefined\n  }\n  return String(x).split('.')[0]\n}\n\nexport function decimalPart(x: number | string): string | undefined {\n  return String(x).split('.')[1]\n}\n\nexport function radian(degree: number) {\n  return (Math.PI * degree) / 180\n}\n\nexport function degree(radian: number) {\n  return (180 * radian) / Math.PI\n}\n\nexport function mapValue(\n  value: number,\n  inMin: number,\n  inMax: number,\n  outMin: number,\n  outMax: number,\n) {\n  return ((value - inMin) / (inMax - inMin)) * (outMax - outMin) + outMin\n}\n\nexport function dbToGain(db: number) {\n  return Math.pow(10, db / 20)\n}\n\nexport function gainToDb(gain: number) {\n  return 20 * (Math.log(gain) / Math.LN10)\n}\n","/**\n * Options for setting the amount of keyboard and mouse wheel changes.\n */\nexport type InputEventOption = readonly ['normalized' | 'raw', number]\n\n/**\n * A modifier key that can carry an amount of its own.\n *\n * `ctrl` and `meta` are kept apart rather than folded into one \"command\" key:\n * a plugin UI that mirrors a desktop host usually wants the same physical key\n * on every platform, not the platform's own convention.\n */\nexport type Modifier = 'shift' | 'alt' | 'ctrl' | 'meta'\n\n/** The modifier flags of a `WheelEvent` or a `KeyboardEvent`. */\nexport interface ModifierState {\n  shiftKey: boolean\n  altKey: boolean\n  ctrlKey: boolean\n  metaKey: boolean\n}\n\n/** One setting per modifier key, with `default` for none of them. */\ntype ModifierSetting = number | InputEventOption\n\nexport type ModifierMap<T extends ModifierSetting> = { default: T } & Partial<\n  Record<Modifier, T>\n>\n\n/**\n * A single setting, or one per modifier key.\n *\n * @example\n * ['raw', 1]\n * { default: ['raw', 1], shift: ['raw', 0.1] }\n */\nexport type ModifierValue<T extends ModifierSetting> = T | ModifierMap<T>\n\nexport interface SelectedInputEvent {\n  option: InputEventOption\n  /** Which modifier entry was chosen, or `null` for `default`. */\n  modifier: Modifier | null\n}\n\n/**\n * Checked in this order, and the first one that is both held and configured\n * wins. Fixing an order is what keeps two modifiers held at once from\n * behaving differently between browsers.\n */\nconst MODIFIER_ORDER = ['meta', 'ctrl', 'alt', 'shift'] as const\n\nconst MODIFIER_FLAG = {\n  meta: 'metaKey',\n  ctrl: 'ctrlKey',\n  alt: 'altKey',\n  shift: 'shiftKey',\n} as const satisfies Record<Modifier, keyof ModifierState>\n\n/**\n * A map is the only form with a `default` key, which is what tells it apart\n * from a bare setting. Tuples are arrays, so they never match.\n */\nfunction isModifierMap<T extends ModifierSetting>(\n  value: ModifierValue<T>,\n): value is ModifierMap<T> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    !Array.isArray(value) &&\n    'default' in value\n  )\n}\n\n/**\n * Pick the setting that applies, given the modifier keys being held.\n *\n * @example\n * selectModifier({ default: 1, shift: 0.1 }, event)\n */\nexport function selectModifier<T extends ModifierSetting>(\n  options: ModifierValue<T>,\n  modifiers?: ModifierState,\n): { value: T; modifier: Modifier | null } {\n  if (!isModifierMap(options)) {\n    // TypeScript cannot subtract the map from `ModifierValue<T>` while `T` is\n    // still a type parameter, so the other half has to be spelled out.\n    return { value: options as T, modifier: null }\n  }\n  if (modifiers) {\n    for (const modifier of MODIFIER_ORDER) {\n      const value = options[modifier]\n      // Compared against undefined rather than checked for truthiness: 0 is a\n      // legitimate setting.\n      if (value !== undefined && modifiers[MODIFIER_FLAG[modifier]]) {\n        return { value, modifier }\n      }\n    }\n  }\n  return { value: options.default, modifier: null }\n}\n\n/**\n * Turn every entry of a setting into another kind of setting, keeping which\n * modifier each belongs to.\n *\n * A drag sensitivity is a number and a keyboard amount is a tuple, but the two\n * describe the same thing from the caller's side. This carries one over to the\n * other so that a component can hand a sensitivity to {@link applyDelta}\n * without unpicking the modifier map itself — which matters, since naming a\n * modifier is also what takes `step` out of the pipeline.\n *\n * @example\n * mapModifier({ default: 1, shift: 0.1 }, (f) => ['raw', step * f])\n * // { default: ['raw', 1], shift: ['raw', 0.1] }\n */\nexport function mapModifier<\n  T extends ModifierSetting,\n  U extends ModifierSetting,\n>(options: ModifierValue<T>, fn: (value: T) => U): ModifierValue<U> {\n  if (!isModifierMap(options)) return fn(options as T)\n  const mapped = { default: fn(options.default) } as ModifierMap<U>\n  for (const modifier of MODIFIER_ORDER) {\n    const value = options[modifier]\n    if (value !== undefined) mapped[modifier] = fn(value)\n  }\n  return mapped\n}\n\n/**\n * Pick the amount that applies, given the modifier keys being held.\n *\n * @example\n * selectInputEvent({ default: ['raw', 1], shift: ['raw', 0.1] }, event)\n */\nexport function selectInputEvent(\n  options: ModifierValue<InputEventOption>,\n  modifiers?: ModifierState,\n): SelectedInputEvent {\n  const { value, modifier } = selectModifier(options, modifiers)\n  return { option: value, modifier }\n}\n","import { clamp, normalizeValue, rawValue, stepValue, toPrecision } from './math'\nimport {\n  type InputEventOption,\n  type ModifierState,\n  type ModifierValue,\n  selectInputEvent,\n} from './modifiers'\n\n/**\n * How a value is distributed across the travel of a control.\n *\n * `normalize` and `denormalize` are inverses of each other: the position is\n * 0 at `min` and 1 at `max`, and everything in between is up to the scale.\n *\n * `min` and `max` are arguments rather than baked into the scale, so a scale\n * holds no state and can be a module level constant. Passing the same object\n * on every render therefore costs nothing.\n *\n * @example\n * ```ts\n * exponentialScale.denormalize(0.5, 20, 20000) // 632.45…\n * ```\n */\nexport interface Scale {\n  /** Value to its position on the travel, 0-1. */\n  normalize: (value: number, min: number, max: number) => number\n  /** Position on the travel, 0-1, back to a value. */\n  denormalize: (position: number, min: number, max: number) => number\n}\n\nfunction assertRange(min: number, max: number) {\n  if (min >= max) throw new RangeError('requirements: min < max')\n}\n\nfunction assertPositiveFinite(value: number, name: string) {\n  if (!Number.isFinite(value) || value <= 0) {\n    throw new RangeError(`${name}: requirements: finite and greater than 0`)\n  }\n}\n\n/**\n * Equal travel gives an equal change in value.\n *\n * The right default for anything already linear in perception: dB values,\n * pan, percentages, MIDI note numbers, semitones.\n */\nexport const linearScale: Scale = {\n  normalize: (value, min, max) => normalizeValue(value, min, max),\n  denormalize: (position, min, max) => rawValue(position, min, max),\n}\n\n/**\n * The power law of JUCE's `NormalisableRange::skew`, applied to `value - min`.\n *\n * Use it when the value has to agree with a JUCE or iPlug2 parameter — a\n * plugin UI in a WebView, say, where the knob must sit exactly where the\n * host's automation curve puts it. {@link skewWithCenterValue} gives the\n * factor that places a chosen value at the middle of the travel.\n *\n * `skew < 1` gives the lower end more travel, `skew > 1` the upper end.\n *\n * For new designs prefer {@link exponentialScale} or {@link curveScale}: the\n * slope of this curve is either zero or infinite at `min`, so the bottom of\n * the range is a dead zone or jumps.\n *\n * @param skew the JUCE skew factor\n */\nexport function skewScale(skew: number): Scale {\n  assertPositiveFinite(skew, 'skewScale')\n  return {\n    // The two expressions JUCE uses, kept verbatim so the numbers agree with\n    // a NormalisableRange: pow() one way, exp(log()) the other.\n    normalize: (value, min, max) =>\n      Math.pow(normalizeValue(value, min, max), skew),\n    denormalize: (position, min, max) =>\n      rawValue(\n        skew === 1\n          ? position\n          : Math.exp(Math.log(clamp(position, 0, 1)) / skew),\n        min,\n        max,\n      ),\n  }\n}\n\n/**\n * The skew factor for {@link skewScale} that puts `centerValue` at the middle\n * of the travel — JUCE's `NormalisableRange::setSkewForCentre`.\n */\nexport function skewWithCenterValue(\n  centerValue: number,\n  min: number,\n  max: number,\n) {\n  assertRange(min, max)\n  if (!(min < centerValue && centerValue < max))\n    throw new RangeError('requirements: min < centerValue < max')\n  return Math.log(0.5) / Math.log((centerValue - min) / (max - min))\n}\n\n/**\n * Equal travel gives an equal *ratio*, so an octave — or a percentage — takes\n * the same distance wherever it falls.\n *\n * The scale for frequency (a filter cutoff over 20-20000 Hz), free running\n * rates, and delay times.\n *\n * Requires `min` and `max` to be non-zero and of the same sign, since no\n * ratio reaches zero or crosses it. Use {@link curveScale} for a range that\n * starts at 0.\n */\nexport const exponentialScale: Scale = {\n  normalize: (value, min, max) => {\n    assertExponentialRange(min, max)\n    // The value is clamped before the logarithm, not after: outside the range\n    // the ratio can be negative, and log() would give NaN rather than a\n    // position to clamp.\n    const start = Math.log(Math.abs(min))\n    const end = Math.log(Math.abs(max))\n    return clamp(\n      (Math.log(Math.abs(clamp(value, min, max))) - start) / (end - start),\n      0,\n      1,\n    )\n  },\n  denormalize: (position, min, max) => {\n    assertExponentialRange(min, max)\n    const start = Math.log(Math.abs(min))\n    const end = Math.log(Math.abs(max))\n    const magnitude = Math.exp(start + (end - start) * clamp(position, 0, 1))\n    return Math.sign(min) * magnitude\n  },\n}\n\nfunction assertExponentialRange(min: number, max: number) {\n  assertRange(min, max)\n  if (min === 0 || max === 0 || Math.sign(min) !== Math.sign(max)) {\n    throw new RangeError(\n      'exponentialScale: requirements: min and max are non-zero and have the same sign',\n    )\n  }\n}\n\n/**\n * An exponential bend that still passes exactly through `min` and `max`, so\n * unlike {@link exponentialScale} it works on a range that starts at 0 or\n * crosses it, and unlike {@link skewScale} its slope is neither zero nor\n * infinite at either end.\n *\n * The general purpose taper, and the same family as the curve of an envelope\n * segment (SuperCollider's `CurveWarp`).\n *\n * - `curve > 0` gives the lower end more travel — envelope times from 0 ms,\n *   delay times, anything that wants fine control near the bottom\n * - `curve < 0` gives the upper end more travel — a volume fader over\n *   -60..+6 dB that should be precise around 0 dB\n * - near 0 it is indistinguishable from {@link linearScale}, and is treated\n *   as linear to avoid dividing by zero\n *\n * {@link curveWithCenterValue} gives the curve that places a chosen value at\n * the middle of the travel.\n *\n * @param curve how hard the curve bends, and in which direction\n */\nexport function curveScale(curve: number): Scale {\n  // Beyond this the flatter half of the curve no longer has enough distinct\n  // double values for normalize and denormalize to remain inverses.\n  if (!Number.isFinite(curve) || Math.abs(curve) > 32) {\n    throw new RangeError(\n      'curveScale: requirements: finite curve from -32 to 32',\n    )\n  }\n  // The two coefficients blow up as the curve flattens: `a` divides by\n  // 1 - e^curve, which goes to 0.\n  if (Math.abs(curve) < 0.001) return linearScale\n\n  return {\n    normalize: (value, min, max) => {\n      assertRange(min, max)\n      const proportion = clamp((value - min) / (max - min), 0, 1)\n      if (proportion === 0 || proportion === 1) return proportion\n      if (curve > 0) {\n        return (\n          1 + Math.log(proportion + (1 - proportion) * Math.exp(-curve)) / curve\n        )\n      }\n      return Math.log1p(proportion * Math.expm1(curve)) / curve\n    },\n    denormalize: (position, min, max) => {\n      assertRange(min, max)\n      const p = clamp(position, 0, 1)\n      if (p === 0) return min\n      if (p === 1) return max\n      const proportion =\n        curve > 0\n          ? (Math.exp(curve * (p - 1)) * (1 - Math.exp(-curve * p))) /\n            (1 - Math.exp(-curve))\n          : Math.expm1(curve * p) / Math.expm1(curve)\n      return min + (max - min) * proportion\n    },\n  }\n}\n\n/**\n * {@link skewScale} mirrored about the middle of the range, so both halves\n * bend the same way — JUCE's `symmetricSkew`.\n *\n * For a bipolar control whose centre matters: detune over -100..+100 cents,\n * or a bipolar filter envelope amount, where the fine adjustment is around 0\n * rather than at either end.\n *\n * `skew < 1` gives the middle more travel, `skew > 1` the two ends.\n *\n * @param skew the JUCE skew factor\n */\nexport function symmetricSkewScale(skew: number): Scale {\n  assertPositiveFinite(skew, 'symmetricSkewScale')\n  return {\n    normalize: (value, min, max) => {\n      assertRange(min, max)\n      const proportion = clamp((value - min) / (max - min), 0, 1)\n      if (skew === 1) return proportion\n      const distanceFromMiddle = 2 * proportion - 1\n      return (\n        (1 +\n          Math.pow(Math.abs(distanceFromMiddle), skew) *\n            Math.sign(distanceFromMiddle)) /\n        2\n      )\n    },\n    denormalize: (position, min, max) => {\n      assertRange(min, max)\n      const p = clamp(position, 0, 1)\n      let distanceFromMiddle = 2 * p - 1\n      if (skew !== 1 && distanceFromMiddle !== 0) {\n        distanceFromMiddle =\n          Math.pow(Math.abs(distanceFromMiddle), 1 / skew) *\n          Math.sign(distanceFromMiddle)\n      }\n      return min + ((max - min) / 2) * (1 + distanceFromMiddle)\n    },\n  }\n}\n\n/**\n * The curve for {@link curveScale} that puts `centerValue` at the middle of\n * the travel — the counterpart of {@link skewWithCenterValue}.\n */\nexport function curveWithCenterValue(\n  centerValue: number,\n  min: number,\n  max: number,\n) {\n  assertRange(min, max)\n  if (!(min < centerValue && centerValue < max)) {\n    throw new RangeError('requirements: min < centerValue < max')\n  }\n  // value(0.5) - min = range / (1 + e^(curve / 2))\n  const proportion = (centerValue - min) / (max - min)\n  return 2 * Math.log(1 / proportion - 1)\n}\n\n/**\n * How a value is scaled: the range it lives in, how it is rounded, and how it\n * is distributed across the travel.\n *\n * `AxisOptions` of `@tremolo-ui/dom` extends this, so a drag and a\n * wheel / keyboard nudge run the same value pipeline.\n */\nexport interface ValueRange {\n  min: number\n  max: number\n  /**\n   * Rounding applied to the value. Left unrounded when omitted.\n   */\n  step?: number\n  /**\n   * How the value is distributed across the travel.\n   *\n   * @default linearScale\n   */\n  scale?: Scale\n}\n\n/**\n * Move a value by an amount of input, as reported by a wheel or an arrow key.\n *\n * The pipeline matches `createDragValue` of `@tremolo-ui/dom`: scale, then\n * step, then clamp. Which key or which sign of `deltaY` counts as which\n * direction is left to the caller, since it differs per component.\n *\n * @param direction which way, and how many times, to apply the option. The\n * size of one step is `option[1]`, so this is normally `1` or `-1`.\n *\n * @param modifiers the event, for `options` that name a modifier key. See\n * {@link selectInputEvent}.\n *\n * @example\n * // ArrowDown on a slider whose keyboard option is ['raw', 1]\n * applyDelta(value, -1, keyboard, { min, max, step, scale })\n *\n * @example\n * // Shift+ArrowDown, where `keyboard` is { default: …, shift: ['raw', 0.1] }\n * applyDelta(value, -1, keyboard, range, event)\n */\nexport function applyDelta(\n  value: number,\n  direction: number,\n  options: ModifierValue<InputEventOption>,\n  { min, max, step, scale = linearScale }: ValueRange,\n  modifiers?: ModifierState,\n): number {\n  assertRange(min, max)\n  if (step !== undefined) assertPositiveFinite(step, 'applyDelta step')\n\n  const {\n    option: [mode, amount],\n    modifier,\n  } = selectInputEvent(options, modifiers)\n\n  const x = direction * amount\n  const next =\n    mode === 'normalized'\n      ? scale.denormalize(scale.normalize(value, min, max) + x, min, max)\n      : value + x\n\n  // Naming a modifier is a deliberate request to move off the grid, so `step`\n  // does not apply to it. Without this a finer amount would round straight\n  // back to where it started: `stepValue(3 + 0.1, 1)` is 3.\n  const quantum = modifier === null ? step : undefined\n  const stepped = quantum !== undefined ? stepValue(next, quantum) : next\n\n  // Rounded before the clamp, so that `min` and `max` still have the last\n  // word and the value can land on them exactly. Without this the artefact\n  // accumulates: with no `step` to round it back, twelve presses of a 0.1\n  // modifier amount reach 5.699999999999998 rather than 5.7.\n  return clamp(toPrecision(stepped), min, max)\n}\n","export function mod(n: number, m: number) {\n  return ((n % m) + m) % m\n}\n\nexport function xor(a = false, b = false) {\n  return (a || b) && a !== b\n}\n","import { mod } from './util'\n\nexport const whiteKeys = ['A', 'B', 'C', 'D', 'E', 'F', 'G'] as const\n\nexport type WhiteKey = (typeof whiteKeys)[number]\n\nexport const noteKeys = [\n  'C',\n  'C#',\n  'D',\n  'D#',\n  'E',\n  'F',\n  'F#',\n  'G',\n  'G#',\n  'A',\n  'A#',\n  'B',\n] as const\n\nexport type NoteKey = (typeof noteKeys)[number]\n\nfunction assertSafeInteger(value: number, name: string) {\n  if (!Number.isSafeInteger(value)) {\n    throw new RangeError(`${name}: requirements: a safe integer`)\n  }\n}\n\nexport function parseNoteName(noteName: string) {\n  const m = noteName.match(/^([a-g])(#{0,2}|b{0,2})(-?\\d+)$/i)\n  if (!m) throw new Error('Invalid note name')\n  const [, letter, accidental, octave] = m\n  const parsedOctave = Number(octave)\n  assertSafeInteger(parsedOctave, 'octave')\n  return {\n    letter: letter.toLocaleUpperCase() as WhiteKey,\n    accidental: accidental as '#' | '##' | 'b' | 'bb' | '',\n    octave: parsedOctave,\n  }\n}\n\n/**\n * Convert noteName to noteNumber\n */\nexport function noteNumber(noteName: string) {\n  const { letter, accidental, octave } = parseNoteName(noteName)\n  const noteIndex = noteKeys.indexOf(letter.toLocaleUpperCase() as NoteKey)\n  const accidentalValue = (accidental[0] === 'b' ? -1 : 1) * accidental.length\n  const result = noteIndex + 12 * (octave + 1) + accidentalValue\n  assertSafeInteger(result, 'note number')\n  return result\n}\n\n/**\n * Convert noteNumber to noteName\n * C-1 = 0\n * G9 = 127\n * @param noteNumber noteNumber\n */\nexport function noteName(noteNumber: number): `${NoteKey}${number}` {\n  assertSafeInteger(noteNumber, 'note number')\n  const noteIndex = mod(noteNumber, 12)\n  const octave = Math.floor(noteNumber / 12) - 1\n  return `${noteKeys[noteIndex]}${octave}`\n}\n\n/**\n * Convert noteNumber to noteKey\n */\nexport function noteKey(noteNumber: number): NoteKey {\n  assertSafeInteger(noteNumber, 'note number')\n  return noteKeys[mod(noteNumber, 12)]\n}\n\n/**\n * @param note noteNumber: 0 ~ 127 or noteName e.g. 'C3'\n */\nexport function isWhiteKey(note: number | string) {\n  const n = typeof note === 'string' ? noteNumber(note) : note\n  assertSafeInteger(n, 'note number')\n  return (\n    mod(n, 12) === 0 ||\n    mod(n, 12) === 2 ||\n    mod(n, 12) === 4 ||\n    mod(n, 12) === 5 ||\n    mod(n, 12) === 7 ||\n    mod(n, 12) === 9 ||\n    mod(n, 12) === 11\n  )\n}\n\n/**\n * @param note noteNumber: 0 ~ 127 or noteName e.g. 'C3'\n */\nexport function isBlackKey(note: number | string) {\n  return !isWhiteKey(note)\n}\n\n/**\n * @param note noteNumber: 0 ~ 127 or noteName e.g. 'C3'\n * @param detune [cent]\n * @param a4 A4 frequency [Hz]\n * @returns frequency [Hz]\n */\nexport function noteToFrequency(note: number | string, detune = 0, a4 = 440) {\n  const n = typeof note === 'string' ? noteNumber(note) : note\n  assertSafeInteger(n, 'note number')\n  return (a4 / 32) * 2 ** ((n - 9 + detune / 100) / 12)\n}\n\n/**\n * Semitones above the root, for each supported scale.\n *\n * Every entry starts at 0 and stays inside one octave, so a scale is a set of\n * pitch classes rather than a set of notes: {@link inScale} compares against\n * it with the octave taken out.\n *\n * `ionian` and `aeolian` are the same sets as `major` and `naturalMinor`; both\n * spellings are here because both are what someone reaches for depending on\n * whether they are thinking in keys or in modes.\n */\nexport const scaleIntervals = {\n  major: [0, 2, 4, 5, 7, 9, 11],\n  naturalMinor: [0, 2, 3, 5, 7, 8, 10],\n  harmonicMinor: [0, 2, 3, 5, 7, 8, 11],\n  melodicMinor: [0, 2, 3, 5, 7, 9, 11],\n\n  ionian: [0, 2, 4, 5, 7, 9, 11],\n  dorian: [0, 2, 3, 5, 7, 9, 10],\n  phrygian: [0, 1, 3, 5, 7, 8, 10],\n  lydian: [0, 2, 4, 6, 7, 9, 11],\n  mixolydian: [0, 2, 4, 5, 7, 9, 10],\n  aeolian: [0, 2, 3, 5, 7, 8, 10],\n  locrian: [0, 1, 3, 5, 6, 8, 10],\n\n  majorPentatonic: [0, 2, 4, 7, 9],\n  minorPentatonic: [0, 3, 5, 7, 10],\n  blues: [0, 3, 5, 6, 7, 10],\n\n  wholeTone: [0, 2, 4, 6, 8, 10],\n  chromatic: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11],\n} as const satisfies Record<string, readonly number[]>\n\nexport type ScaleName = keyof typeof scaleIntervals\n\n/**\n * Whether a note belongs to a scale, regardless of the octave either sits in.\n *\n * @param note noteNumber: 0 ~ 127 or noteName e.g. 'C3'\n * @param root the note the scale is built on, in the same two forms\n *\n * @example\n * ```ts\n * inScale('F#4', 'D3', 'major') // true\n * ```\n */\nexport function inScale(\n  note: number | string,\n  root: number | string,\n  name: ScaleName,\n): boolean {\n  const n = typeof note === 'string' ? noteNumber(note) : note\n  const r = typeof root === 'string' ? noteNumber(root) : root\n  assertSafeInteger(n, 'note number')\n  assertSafeInteger(r, 'root note number')\n  return (scaleIntervals[name] as readonly number[]).includes(mod(n - r, 12))\n}\n\n/**\n * The notes of a scale, ascending from `root`.\n *\n * The octave above the root is not included: ask for more `octaves` instead, so\n * that concatenating the result of two calls does not repeat a note.\n *\n * @param root noteNumber: 0 ~ 127 or noteName e.g. 'C3'\n * @param octaves how many octaves to cover\n *\n * @example\n * ```ts\n * scaleNotes('C3', 'majorPentatonic') // [48, 50, 52, 55, 57]\n * ```\n */\nexport function scaleNotes(\n  root: number | string,\n  name: ScaleName,\n  octaves = 1,\n): number[] {\n  const r = typeof root === 'string' ? noteNumber(root) : root\n  assertSafeInteger(r, 'root note number')\n  if (!Number.isSafeInteger(octaves) || octaves < 0) {\n    throw new RangeError('octaves: requirements: a non-negative safe integer')\n  }\n  const intervals = scaleIntervals[name] as readonly number[]\n  return Array.from({ length: octaves }, (_, octave) =>\n    intervals.map((interval) => r + octave * 12 + interval),\n  ).flat()\n}\n","import { isBlackKey, isWhiteKey, noteKey, noteKeys, type NoteKey } from './midi'\n\nexport type NoteRange = {\n  first: number\n  last: number\n}\n\n/**\n * `[noteRange.first, noteRange.first + 1, ..., noteRange.last]`\n */\nexport function getNoteRangeArray(noteRange: NoteRange): number[] {\n  return Array.from(\n    { length: noteRange.last - noteRange.first + 1 },\n    (_, i) => i + noteRange.first,\n  )\n}\n\n/**\n * The geometry of a drawn keyboard.\n *\n * One description is shared by the drawing and the hit testing, so a key cannot\n * be drawn somewhere other than where it responds.\n */\nexport interface PianoLayout {\n  noteRange: NoteRange\n\n  /** Width of a white key, excluding {@link PianoLayout.keyGap}. */\n  whiteKeyWidth: number\n\n  /**\n   * Space between two white keys. Part of the slot a white key occupies, so it\n   * still belongs to one of the keys for the purpose of hit testing.\n   *\n   * @default 1\n   */\n  keyGap?: number\n\n  /**\n   * Width of a black key, as a fraction of {@link PianoLayout.whiteKeyWidth}.\n   *\n   * @default 0.65\n   */\n  blackKeyWidthRatio?: number\n\n  /**\n   * Height of a black key, as a fraction of the height of the keyboard.\n   *\n   * @default 0.6\n   */\n  blackKeyHeightRatio?: number\n}\n\nconst DEFAULT_KEY_GAP = 1\nconst DEFAULT_BLACK_KEY_WIDTH_RATIO = 0.65\nconst DEFAULT_BLACK_KEY_HEIGHT_RATIO = 0.6\n\n/**\n * How many white keys sit at or before each pitch class, counting from C.\n *\n * A black key shares the number of the white key to its left plus one, which\n * puts it on the boundary between the two; {@link notePosition} then shifts it\n * back by half its width to centre it there.\n */\nconst whiteKeysBefore: Record<NoteKey, number> = {\n  C: 0,\n  'C#': 1,\n  D: 1,\n  'D#': 2,\n  E: 2,\n  F: 3,\n  'F#': 4,\n  G: 4,\n  'G#': 5,\n  A: 5,\n  'A#': 6,\n  B: 6,\n}\n\n/** Width of a black key in pixels. */\nexport function blackKeyWidth(layout: PianoLayout): number {\n  return (\n    layout.whiteKeyWidth *\n    (layout.blackKeyWidthRatio ?? DEFAULT_BLACK_KEY_WIDTH_RATIO)\n  )\n}\n\nfunction rawNotePosition(note: number, layout: PianoLayout): number {\n  const slot = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP)\n  const target = noteKey(note)\n  const first = noteKey(layout.noteRange.first)\n\n  const octave = Math.floor((note - layout.noteRange.first) / 12)\n  const octaveOffset =\n    noteKeys.indexOf(first) > noteKeys.indexOf(target) ? 1 : 0\n  const whiteKeysIn =\n    whiteKeysBefore[target] -\n    whiteKeysBefore[first] +\n    (octave + octaveOffset) * 7\n\n  return isBlackKey(note)\n    ? whiteKeysIn * slot - blackKeyWidth(layout) / 2\n    : whiteKeysIn * slot\n}\n\nfunction pianoBounds(layout: PianoLayout) {\n  const notes = getNoteRangeArray(layout.noteRange)\n  if (notes.length === 0) return { left: 0, right: 0 }\n\n  let left = Infinity\n  let right = -Infinity\n  const whiteWidth = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP)\n  for (const note of notes) {\n    const noteLeft = rawNotePosition(note, layout)\n    const width = isBlackKey(note) ? blackKeyWidth(layout) : whiteWidth\n    left = Math.min(left, noteLeft)\n    right = Math.max(right, noteLeft + width)\n  }\n  return { left, right }\n}\n\n/** Width of the whole keyboard in pixels. */\nexport function pianoWidth(layout: PianoLayout): number {\n  const { left, right } = pianoBounds(layout)\n  return right - left\n}\n\n/**\n * Offset of the left edge of a key from the left edge of the keyboard, in\n * pixels.\n *\n * Notes outside `noteRange` are placed too, so the value is negative below\n * `noteRange.first`.\n */\nexport function notePosition(note: number, layout: PianoLayout): number {\n  return rawNotePosition(note, layout) - pianoBounds(layout).left\n}\n\n/**\n * The note drawn at a point, or null where there is none.\n *\n * Black keys are tested first, so they win where they overlap a white one. A\n * white key covers its gap as well as its width, so the whole width of the\n * keyboard belongs to some key and a click cannot fall between two.\n *\n * @param x offset from the left edge of the keyboard, in pixels\n * @param y offset from its top edge, in pixels\n * @param height height of the keyboard, in pixels\n */\nexport function noteAt(\n  x: number,\n  y: number,\n  height: number,\n  layout: PianoLayout,\n): number | null {\n  if (x < 0 || x >= pianoWidth(layout) || y < 0 || y >= height) return null\n\n  const notes = getNoteRangeArray(layout.noteRange)\n  const blackHeight =\n    height * (layout.blackKeyHeightRatio ?? DEFAULT_BLACK_KEY_HEIGHT_RATIO)\n\n  if (y < blackHeight) {\n    for (const note of notes) {\n      if (isWhiteKey(note)) continue\n      const left = notePosition(note, layout)\n      if (left <= x && x < left + blackKeyWidth(layout)) return note\n    }\n  }\n\n  const slot = layout.whiteKeyWidth + (layout.keyGap ?? DEFAULT_KEY_GAP)\n  for (const note of notes) {\n    if (isBlackKey(note)) continue\n    const left = notePosition(note, layout)\n    if (left <= x && x < left + slot) return note\n  }\n\n  return null\n}\n","import { toPrecision } from './math'\n\n/**\n * The SI prefixes {@link unitFormat} chooses between.\n *\n * Deliberately narrower than the full SI set: yocto through yotta are of no\n * use to an audio control, and every extra prefix is one more symbol `parse`\n * has to tell apart from a unit.\n */\nexport type SIPrefix = 'p' | 'n' | 'µ' | 'm' | '' | 'k' | 'M' | 'G'\n\n/** Ordered small to large. The empty symbol is the base unit. */\nconst PREFIXES: readonly [SIPrefix, number][] = [\n  ['p', 1e-12],\n  ['n', 1e-9],\n  ['µ', 1e-6],\n  ['m', 1e-3],\n  ['', 1],\n  ['k', 1e3],\n  ['M', 1e6],\n  ['G', 1e9],\n]\n\nconst PREFIX_SCALE = new Map<string, number>(PREFIXES)\n\n/**\n * Micro is written three ways. `µ` (U+00B5 MICRO SIGN) is what `format`\n * writes and what d3-format uses, `μ` (U+03BC GREEK SMALL LETTER MU) looks\n * identical and is what a Greek keyboard produces, and `u` is what everyone\n * actually types. All three read back the same.\n */\nconst MICRO_ALIASES: Record<string, SIPrefix> = { μ: 'µ', u: 'µ' }\n\nexport interface UnitFormatOptions {\n  /**\n   * The prefix the stored value is already in.\n   *\n   * A control that keeps milliseconds in `value` is `{ base: 'm' }` with a\n   * unit of `'s'`: 1500 then displays as `1.5s`, and `parse` gives 1500 back.\n   *\n   * @default ''\n   */\n  base?: SIPrefix\n  /**\n   * Whether to scale the number and pick a prefix at all.\n   *\n   * Turn it off for anything that is not an SI quantity. dB, %, cents and\n   * semitones do not take prefixes, and `-6dB` read as \"-6 deci-B\" is wrong\n   * rather than merely unusual.\n   *\n   * @default true\n   */\n  prefixes?: boolean\n  /**\n   * Digits after the decimal point. The number is left as-is when omitted.\n   */\n  digits?: number\n  /**\n   * Text placed between the number and the unit.\n   * @default ''\n   */\n  separator?: string\n}\n\n/** The `format` / `parse` pair a `NumberInput` takes. */\nexport interface UnitFormatter {\n  format: (value: number) => string\n  parse: (text: string) => number\n}\n\n/**\n * Divide by a prefix scale without showing the result of doing so in binary.\n *\n * `0.0005 / 1e-6` is 500.00000000000006, and with no `digits` to round it that\n * lands in the input as written.\n */\nfunction scaleBy(value: number, scale: number): number {\n  return toPrecision(value / scale)\n}\n\n/** A number, then whatever followed it. */\nconst NUMBER_THEN_REST =\n  /^([+-]?(?:\\d+(?:\\.\\d*)?|\\.\\d+)(?:[eE][+-]?\\d+)?)\\s*(.*)$/\n\n/**\n * Build the `format` and `parse` of a unit, as one pair.\n *\n * They are returned together because they have to agree: a `format` that\n * writes `1.23kHz` is only useful next to a `parse` that reads it back as\n * 1230. Spread the result into the input.\n *\n * @example\n * unitFormat('Hz')                                 // 1234 -> '1.23kHz'\n * unitFormat('s', { base: 'm' })                   // value in ms. 1500 -> '1.5s'\n * unitFormat('s', { base: 'm', digits: 2 })        // 1500 -> '1.50s'\n * unitFormat('dB', { prefixes: false, digits: 1 }) // -6.25 -> '-6.3dB'\n *\n * @example\n * <NumberInput.Root {...unitFormat('Hz', { digits: 2 })} value={v} onChange={setV}>\n */\nexport function unitFormat(\n  unit: string,\n  options: UnitFormatOptions = {},\n): UnitFormatter {\n  const { base = '', prefixes = true, digits, separator = '' } = options\n  if (unit === '' && base !== '') {\n    throw new RangeError('unitFormat: base requires a non-empty unit')\n  }\n  const baseScale = PREFIX_SCALE.get(base) ?? 1\n\n  /**\n   * `toFixed` renders anything that rounds to zero from below as `-0`, which\n   * is never what a control should show.\n   */\n  const fixed = (value: number) => {\n    const text = digits !== undefined ? value.toFixed(digits) : String(value)\n    return Number(text) === 0 ? text.replace('-', '') : text\n  }\n\n  if (!prefixes) {\n    // The stored value goes out untouched, so the symbol has to name the unit\n    // it is already in.\n    const symbol = base + unit\n    return {\n      format: (value) =>\n        Number.isFinite(value)\n          ? fixed(value) + separator + symbol\n          : String(value),\n      // Nothing after the number can change the scale, so it is all ignored:\n      // the number in front is the value, half-typed or not.\n      parse: (text) => {\n        const match = text.trim().match(NUMBER_THEN_REST)\n        if (!match) return NaN\n        const value = Number(match[1])\n        return Number.isFinite(value) ? value : NaN\n      },\n    }\n  }\n\n  return {\n    format: (value) => {\n      if (!Number.isFinite(value)) return String(value)\n      const si = value * baseScale\n      // Zero has no magnitude to read, so it stays in the base unit.\n      let index = PREFIXES.findIndex(([, scale]) => scale === 1)\n      if (si !== 0) {\n        // The largest prefix that leaves at least one digit before the point.\n        // Below the smallest prefix the number just gets small: `p` is the\n        // floor, as `G` is the ceiling.\n        const magnitude = Math.abs(si)\n        index = 0\n        for (let i = PREFIXES.length - 1; i >= 0; i--) {\n          if (magnitude >= PREFIXES[i][1]) {\n            index = i\n            break\n          }\n        }\n      }\n      let text = fixed(scaleBy(si, PREFIXES[index][1]))\n      // Rounding can carry the number up out of its own prefix — 999.99Hz at\n      // one digit is 1000.0Hz, which should read 1.0kHz. One step is always\n      // enough, since the carry is at most a factor of ten.\n      if (Math.abs(Number(text)) >= 1000 && index < PREFIXES.length - 1) {\n        index += 1\n        text = fixed(scaleBy(si, PREFIXES[index][1]))\n      }\n      return text + separator + PREFIXES[index][0] + unit\n    },\n\n    parse: (text) => {\n      const match = text.trim().match(NUMBER_THEN_REST)\n      if (!match) return NaN\n      const number = Number(match[1])\n      if (!Number.isFinite(number)) return NaN\n\n      let suffix = match[2].trim()\n      const separatorText = separator.trim()\n      if (separatorText !== '' && suffix.startsWith(separatorText)) {\n        suffix = suffix.slice(separatorText.length).trim()\n      }\n      // A bare number is in the unit the value is stored in, which is what\n      // the input shows once the format is stripped.\n      if (suffix === '') return number\n\n      // The unit symbol is matched first, so a unit that is itself a prefix\n      // letter wins over the prefix reading: `5m` for a unit of `m` is five\n      // metres, not five milli-.\n      let prefix: string | null = null\n      if (unit !== '' && suffix.endsWith(unit)) {\n        prefix = suffix.slice(0, suffix.length - unit.length)\n      } else if (suffix.length <= 1) {\n        prefix = suffix\n      }\n      if (prefix === null) return number\n\n      const normalized = MICRO_ALIASES[prefix] ?? prefix\n      const scale = PREFIX_SCALE.get(normalized)\n      // Unrecognised text after the number is ignored rather than rejected,\n      // so that a half-typed entry still yields the number in front of it.\n      if (scale === undefined) return number\n      return (number * scale) / baseScale\n    },\n  }\n}\n"],"mappings":";;;;;AAGA,SAAgB,MAAM,OAAe,KAAa,KAAa;CAC7D,OAAO,KAAK,IAAI,KAAK,KAAK,IAAI,OAAO,GAAG,CAAC;AAC3C;;;;;;;AAQA,SAAgB,eAAe,OAAe,KAAa,KAAa;CACtE,IAAI,OAAO,KAAK,MAAM,IAAI,WAAW,yBAAyB;CAC9D,OAAO,OAAO,QAAQ,QAAQ,MAAM,MAAM,GAAG,CAAC;AAChD;;;;;;AAOA,SAAgB,SAAS,iBAAyB,KAAa,KAAa;CAC1E,IAAI,OAAO,KAAK,MAAM,IAAI,WAAW,yBAAyB;CAC9D,OAAO,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,MAAM;AACrD;;;;;;;;;;;AAYA,SAAgB,UAAU,OAAe,MAAc;CACrD,IAAI,QAAQ,GAAG,MAAM,IAAI,WAAW,wBAAwB;CAG5D,MAAM,UAAU,YAFC,KAAK,MAAM,YAAY,QAAQ,IAAI,CAEjB,IAAI,IAAI;CAG3C,OAAO,YAAY,IAAI,IAAI;AAC7B;AAEA,SAAgB,QAAQ,GAAW,gBAAyB;CAC1D,OAAO,OAAO,EAAE,QAAQ,cAAc,CAAC;AACzC;;;;;;AAOA,MAAa,qBAAqB;;;;;;;;;;;;;;;;;;;;;AAsBlC,SAAgB,YAAY,GAAW,oBAAA,IAAwC;CAG7E,IAAI,MAAM,KAAK,CAAC,OAAO,SAAS,CAAC,GAAG,OAAO;CAC3C,MAAM,UAAU,OAAO,EAAE,YAAY,iBAAiB,CAAC;CAGvD,OAAO,OAAO,SAAS,OAAO,IAAI,UAAU;AAC9C;AAEA,SAAgB,YAAY,GAAwC;CAClE,IAAI,OAAO,MAAM,CAAC,GAChB;CAEF,OAAO,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9B;AAEA,SAAgB,YAAY,GAAwC;CAClE,OAAO,OAAO,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9B;AAEA,SAAgB,OAAO,QAAgB;CACrC,OAAQ,KAAK,KAAK,SAAU;AAC9B;AAEA,SAAgB,OAAO,QAAgB;CACrC,OAAQ,MAAM,SAAU,KAAK;AAC/B;AAEA,SAAgB,SACd,OACA,OACA,OACA,QACA,QACA;CACA,QAAS,QAAQ,UAAU,QAAQ,UAAW,SAAS,UAAU;AACnE;AAEA,SAAgB,SAAS,IAAY;CACnC,OAAO,KAAK,IAAI,IAAI,KAAK,EAAE;AAC7B;AAEA,SAAgB,SAAS,MAAc;CACrC,OAAO,MAAM,KAAK,IAAI,IAAI,IAAI,KAAK;AACrC;;;;;;;;AC3EA,MAAM,iBAAiB;CAAC;CAAQ;CAAQ;CAAO;AAAO;AAEtD,MAAM,gBAAgB;CACpB,MAAM;CACN,MAAM;CACN,KAAK;CACL,OAAO;AACT;;;;;AAMA,SAAS,cACP,OACyB;CACzB,OACE,OAAO,UAAU,YACjB,UAAU,QACV,CAAC,MAAM,QAAQ,KAAK,KACpB,aAAa;AAEjB;;;;;;;AAQA,SAAgB,eACd,SACA,WACyC;CACzC,IAAI,CAAC,cAAc,OAAO,GAGxB,OAAO;EAAE,OAAO;EAAc,UAAU;CAAK;CAE/C,IAAI,WACF,KAAK,MAAM,YAAY,gBAAgB;EACrC,MAAM,QAAQ,QAAQ;EAGtB,IAAI,UAAU,KAAA,KAAa,UAAU,cAAc,YACjD,OAAO;GAAE;GAAO;EAAS;CAE7B;CAEF,OAAO;EAAE,OAAO,QAAQ;EAAS,UAAU;CAAK;AAClD;;;;;;;;;;;;;;;AAgBA,SAAgB,YAGd,SAA2B,IAAuC;CAClE,IAAI,CAAC,cAAc,OAAO,GAAG,OAAO,GAAG,OAAY;CACnD,MAAM,SAAS,EAAE,SAAS,GAAG,QAAQ,OAAO,EAAE;CAC9C,KAAK,MAAM,YAAY,gBAAgB;EACrC,MAAM,QAAQ,QAAQ;EACtB,IAAI,UAAU,KAAA,GAAW,OAAO,YAAY,GAAG,KAAK;CACtD;CACA,OAAO;AACT;;;;;;;AAQA,SAAgB,iBACd,SACA,WACoB;CACpB,MAAM,EAAE,OAAO,aAAa,eAAe,SAAS,SAAS;CAC7D,OAAO;EAAE,QAAQ;EAAO;CAAS;AACnC;;;AC9GA,SAAS,YAAY,KAAa,KAAa;CAC7C,IAAI,OAAO,KAAK,MAAM,IAAI,WAAW,yBAAyB;AAChE;AAEA,SAAS,qBAAqB,OAAe,MAAc;CACzD,IAAI,CAAC,OAAO,SAAS,KAAK,KAAK,SAAS,GACtC,MAAM,IAAI,WAAW,GAAG,KAAK,0CAA0C;AAE3E;;;;;;;AAQA,MAAa,cAAqB;CAChC,YAAY,OAAO,KAAK,QAAQ,eAAe,OAAO,KAAK,GAAG;CAC9D,cAAc,UAAU,KAAK,QAAQ,SAAS,UAAU,KAAK,GAAG;AAClE;;;;;;;;;;;;;;;;;AAkBA,SAAgB,UAAU,MAAqB;CAC7C,qBAAqB,MAAM,WAAW;CACtC,OAAO;EAGL,YAAY,OAAO,KAAK,QACtB,KAAK,IAAI,eAAe,OAAO,KAAK,GAAG,GAAG,IAAI;EAChD,cAAc,UAAU,KAAK,QAC3B,SACE,SAAS,IACL,WACA,KAAK,IAAI,KAAK,IAAI,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,IAAI,GACnD,KACA,GACF;CACJ;AACF;;;;;AAMA,SAAgB,oBACd,aACA,KACA,KACA;CACA,YAAY,KAAK,GAAG;CACpB,IAAI,EAAE,MAAM,eAAe,cAAc,MACvC,MAAM,IAAI,WAAW,uCAAuC;CAC9D,OAAO,KAAK,IAAI,EAAG,IAAI,KAAK,KAAK,cAAc,QAAQ,MAAM,IAAI;AACnE;;;;;;;;;;;;AAaA,MAAa,mBAA0B;CACrC,YAAY,OAAO,KAAK,QAAQ;EAC9B,uBAAuB,KAAK,GAAG;EAI/B,MAAM,QAAQ,KAAK,IAAI,KAAK,IAAI,GAAG,CAAC;EACpC,MAAM,MAAM,KAAK,IAAI,KAAK,IAAI,GAAG,CAAC;EAClC,OAAO,OACJ,KAAK,IAAI,KAAK,IAAI,MAAM,OAAO,KAAK,GAAG,CAAC,CAAC,IAAI,UAAU,MAAM,QAC9D,GACA,CACF;CACF;CACA,cAAc,UAAU,KAAK,QAAQ;EACnC,uBAAuB,KAAK,GAAG;EAC/B,MAAM,QAAQ,KAAK,IAAI,KAAK,IAAI,GAAG,CAAC;EAEpC,MAAM,YAAY,KAAK,IAAI,SADf,KAAK,IAAI,KAAK,IAAI,GAAG,CACK,IAAI,SAAS,MAAM,UAAU,GAAG,CAAC,CAAC;EACxE,OAAO,KAAK,KAAK,GAAG,IAAI;CAC1B;AACF;AAEA,SAAS,uBAAuB,KAAa,KAAa;CACxD,YAAY,KAAK,GAAG;CACpB,IAAI,QAAQ,KAAK,QAAQ,KAAK,KAAK,KAAK,GAAG,MAAM,KAAK,KAAK,GAAG,GAC5D,MAAM,IAAI,WACR,iFACF;AAEJ;;;;;;;;;;;;;;;;;;;;;;AAuBA,SAAgB,WAAW,OAAsB;CAG/C,IAAI,CAAC,OAAO,SAAS,KAAK,KAAK,KAAK,IAAI,KAAK,IAAI,IAC/C,MAAM,IAAI,WACR,uDACF;CAIF,IAAI,KAAK,IAAI,KAAK,IAAI,MAAO,OAAO;CAEpC,OAAO;EACL,YAAY,OAAO,KAAK,QAAQ;GAC9B,YAAY,KAAK,GAAG;GACpB,MAAM,aAAa,OAAO,QAAQ,QAAQ,MAAM,MAAM,GAAG,CAAC;GAC1D,IAAI,eAAe,KAAK,eAAe,GAAG,OAAO;GACjD,IAAI,QAAQ,GACV,OACE,IAAI,KAAK,IAAI,cAAc,IAAI,cAAc,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI;GAGrE,OAAO,KAAK,MAAM,aAAa,KAAK,MAAM,KAAK,CAAC,IAAI;EACtD;EACA,cAAc,UAAU,KAAK,QAAQ;GACnC,YAAY,KAAK,GAAG;GACpB,MAAM,IAAI,MAAM,UAAU,GAAG,CAAC;GAC9B,IAAI,MAAM,GAAG,OAAO;GACpB,IAAI,MAAM,GAAG,OAAO;GACpB,MAAM,aACJ,QAAQ,IACH,KAAK,IAAI,SAAS,IAAI,EAAE,KAAK,IAAI,KAAK,IAAI,CAAC,QAAQ,CAAC,MACpD,IAAI,KAAK,IAAI,CAAC,KAAK,KACpB,KAAK,MAAM,QAAQ,CAAC,IAAI,KAAK,MAAM,KAAK;GAC9C,OAAO,OAAO,MAAM,OAAO;EAC7B;CACF;AACF;;;;;;;;;;;;;AAcA,SAAgB,mBAAmB,MAAqB;CACtD,qBAAqB,MAAM,oBAAoB;CAC/C,OAAO;EACL,YAAY,OAAO,KAAK,QAAQ;GAC9B,YAAY,KAAK,GAAG;GACpB,MAAM,aAAa,OAAO,QAAQ,QAAQ,MAAM,MAAM,GAAG,CAAC;GAC1D,IAAI,SAAS,GAAG,OAAO;GACvB,MAAM,qBAAqB,IAAI,aAAa;GAC5C,QACG,IACC,KAAK,IAAI,KAAK,IAAI,kBAAkB,GAAG,IAAI,IACzC,KAAK,KAAK,kBAAkB,KAChC;EAEJ;EACA,cAAc,UAAU,KAAK,QAAQ;GACnC,YAAY,KAAK,GAAG;GAEpB,IAAI,qBAAqB,IADf,MAAM,UAAU,GAAG,CACA,IAAI;GACjC,IAAI,SAAS,KAAK,uBAAuB,GACvC,qBACE,KAAK,IAAI,KAAK,IAAI,kBAAkB,GAAG,IAAI,IAAI,IAC/C,KAAK,KAAK,kBAAkB;GAEhC,OAAO,OAAQ,MAAM,OAAO,KAAM,IAAI;EACxC;CACF;AACF;;;;;AAMA,SAAgB,qBACd,aACA,KACA,KACA;CACA,YAAY,KAAK,GAAG;CACpB,IAAI,EAAE,MAAM,eAAe,cAAc,MACvC,MAAM,IAAI,WAAW,uCAAuC;CAG9D,MAAM,cAAc,cAAc,QAAQ,MAAM;CAChD,OAAO,IAAI,KAAK,IAAI,IAAI,aAAa,CAAC;AACxC;;;;;;;;;;;;;;;;;;;;;;AA6CA,SAAgB,WACd,OACA,WACA,SACA,EAAE,KAAK,KAAK,MAAM,QAAQ,eAC1B,WACQ;CACR,YAAY,KAAK,GAAG;CACpB,IAAI,SAAS,KAAA,GAAW,qBAAqB,MAAM,iBAAiB;CAEpE,MAAM,EACJ,QAAQ,CAAC,MAAM,SACf,aACE,iBAAiB,SAAS,SAAS;CAEvC,MAAM,IAAI,YAAY;CACtB,MAAM,OACJ,SAAS,eACL,MAAM,YAAY,MAAM,UAAU,OAAO,KAAK,GAAG,IAAI,GAAG,KAAK,GAAG,IAChE,QAAQ;CAKd,MAAM,UAAU,aAAa,OAAO,OAAO,KAAA;CAO3C,OAAO,MAAM,YANG,YAAY,KAAA,IAAY,UAAU,MAAM,OAAO,IAAI,IAMnC,GAAG,KAAK,GAAG;AAC7C;;;ACjVA,SAAgB,IAAI,GAAW,GAAW;CACxC,QAAS,IAAI,IAAK,KAAK;AACzB;AAEA,SAAgB,IAAI,IAAI,OAAO,IAAI,OAAO;CACxC,QAAQ,KAAK,MAAM,MAAM;AAC3B;;;ACJA,MAAa,YAAY;CAAC;CAAK;CAAK;CAAK;CAAK;CAAK;CAAK;AAAG;AAI3D,MAAa,WAAW;CACtB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;AAIA,SAAS,kBAAkB,OAAe,MAAc;CACtD,IAAI,CAAC,OAAO,cAAc,KAAK,GAC7B,MAAM,IAAI,WAAW,GAAG,KAAK,+BAA+B;AAEhE;AAEA,SAAgB,cAAc,UAAkB;CAC9C,MAAM,IAAI,SAAS,MAAM,kCAAkC;CAC3D,IAAI,CAAC,GAAG,MAAM,IAAI,MAAM,mBAAmB;CAC3C,MAAM,GAAG,QAAQ,YAAY,UAAU;CACvC,MAAM,eAAe,OAAO,MAAM;CAClC,kBAAkB,cAAc,QAAQ;CACxC,OAAO;EACL,QAAQ,OAAO,kBAAkB;EACrB;EACZ,QAAQ;CACV;AACF;;;;AAKA,SAAgB,WAAW,UAAkB;CAC3C,MAAM,EAAE,QAAQ,YAAY,WAAW,cAAc,QAAQ;CAC7D,MAAM,YAAY,SAAS,QAAQ,OAAO,kBAAkB,CAAY;CACxE,MAAM,mBAAmB,WAAW,OAAO,MAAM,KAAK,KAAK,WAAW;CACtE,MAAM,SAAS,YAAY,MAAM,SAAS,KAAK;CAC/C,kBAAkB,QAAQ,aAAa;CACvC,OAAO;AACT;;;;;;;AAQA,SAAgB,SAAS,YAA2C;CAClE,kBAAkB,YAAY,aAAa;CAC3C,MAAM,YAAY,IAAI,YAAY,EAAE;CACpC,MAAM,SAAS,KAAK,MAAM,aAAa,EAAE,IAAI;CAC7C,OAAO,GAAG,SAAS,aAAa;AAClC;;;;AAKA,SAAgB,QAAQ,YAA6B;CACnD,kBAAkB,YAAY,aAAa;CAC3C,OAAO,SAAS,IAAI,YAAY,EAAE;AACpC;;;;AAKA,SAAgB,WAAW,MAAuB;CAChD,MAAM,IAAI,OAAO,SAAS,WAAW,WAAW,IAAI,IAAI;CACxD,kBAAkB,GAAG,aAAa;CAClC,OACE,IAAI,GAAG,EAAE,MAAM,KACf,IAAI,GAAG,EAAE,MAAM,KACf,IAAI,GAAG,EAAE,MAAM,KACf,IAAI,GAAG,EAAE,MAAM,KACf,IAAI,GAAG,EAAE,MAAM,KACf,IAAI,GAAG,EAAE,MAAM,KACf,IAAI,GAAG,EAAE,MAAM;AAEnB;;;;AAKA,SAAgB,WAAW,MAAuB;CAChD,OAAO,CAAC,WAAW,IAAI;AACzB;;;;;;;AAQA,SAAgB,gBAAgB,MAAuB,SAAS,GAAG,KAAK,KAAK;CAC3E,MAAM,IAAI,OAAO,SAAS,WAAW,WAAW,IAAI,IAAI;CACxD,kBAAkB,GAAG,aAAa;CAClC,OAAQ,KAAK,KAAM,OAAO,IAAI,IAAI,SAAS,OAAO;AACpD;;;;;;;;;;;;AAaA,MAAa,iBAAiB;CAC5B,OAAO;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CAC5B,cAAc;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CACnC,eAAe;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CACpC,cAAc;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CAEnC,QAAQ;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CAC7B,QAAQ;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CAC7B,UAAU;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CAC/B,QAAQ;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CAC7B,YAAY;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CACjC,SAAS;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CAC9B,SAAS;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CAE9B,iBAAiB;EAAC;EAAG;EAAG;EAAG;EAAG;CAAC;CAC/B,iBAAiB;EAAC;EAAG;EAAG;EAAG;EAAG;CAAE;CAChC,OAAO;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CAEzB,WAAW;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;CAAE;CAC7B,WAAW;EAAC;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;EAAG;EAAI;CAAE;AAClD;;;;;;;;;;;;AAeA,SAAgB,QACd,MACA,MACA,MACS;CACT,MAAM,IAAI,OAAO,SAAS,WAAW,WAAW,IAAI,IAAI;CACxD,MAAM,IAAI,OAAO,SAAS,WAAW,WAAW,IAAI,IAAI;CACxD,kBAAkB,GAAG,aAAa;CAClC,kBAAkB,GAAG,kBAAkB;CACvC,OAAQ,eAAe,KAAK,CAAuB,SAAS,IAAI,IAAI,GAAG,EAAE,CAAC;AAC5E;;;;;;;;;;;;;;;AAgBA,SAAgB,WACd,MACA,MACA,UAAU,GACA;CACV,MAAM,IAAI,OAAO,SAAS,WAAW,WAAW,IAAI,IAAI;CACxD,kBAAkB,GAAG,kBAAkB;CACvC,IAAI,CAAC,OAAO,cAAc,OAAO,KAAK,UAAU,GAC9C,MAAM,IAAI,WAAW,oDAAoD;CAE3E,MAAM,YAAY,eAAe;CACjC,OAAO,MAAM,KAAK,EAAE,QAAQ,QAAQ,IAAI,GAAG,WACzC,UAAU,KAAK,aAAa,IAAI,SAAS,KAAK,QAAQ,CACxD,CAAC,CAAC,KAAK;AACT;;;;;;AC3LA,SAAgB,kBAAkB,WAAgC;CAChE,OAAO,MAAM,KACX,EAAE,QAAQ,UAAU,OAAO,UAAU,QAAQ,EAAE,IAC9C,GAAG,MAAM,IAAI,UAAU,KAC1B;AACF;AAqCA,MAAM,kBAAkB;AACxB,MAAM,gCAAgC;AACtC,MAAM,iCAAiC;;;;;;;;AASvC,MAAM,kBAA2C;CAC/C,GAAG;CACH,MAAM;CACN,GAAG;CACH,MAAM;CACN,GAAG;CACH,GAAG;CACH,MAAM;CACN,GAAG;CACH,MAAM;CACN,GAAG;CACH,MAAM;CACN,GAAG;AACL;;AAGA,SAAgB,cAAc,QAA6B;CACzD,OACE,OAAO,iBACN,OAAO,sBAAsB;AAElC;AAEA,SAAS,gBAAgB,MAAc,QAA6B;CAClE,MAAM,OAAO,OAAO,iBAAiB,OAAO,UAAU;CACtD,MAAM,SAAS,QAAQ,IAAI;CAC3B,MAAM,QAAQ,QAAQ,OAAO,UAAU,KAAK;CAE5C,MAAM,SAAS,KAAK,OAAO,OAAO,OAAO,UAAU,SAAS,EAAE;CAC9D,MAAM,eACJ,SAAS,QAAQ,KAAK,IAAI,SAAS,QAAQ,MAAM,IAAI,IAAI;CAC3D,MAAM,cACJ,gBAAgB,UAChB,gBAAgB,UACf,SAAS,gBAAgB;CAE5B,OAAO,WAAW,IAAI,IAClB,cAAc,OAAO,cAAc,MAAM,IAAI,IAC7C,cAAc;AACpB;AAEA,SAAS,YAAY,QAAqB;CACxC,MAAM,QAAQ,kBAAkB,OAAO,SAAS;CAChD,IAAI,MAAM,WAAW,GAAG,OAAO;EAAE,MAAM;EAAG,OAAO;CAAE;CAEnD,IAAI,OAAO;CACX,IAAI,QAAQ;CACZ,MAAM,aAAa,OAAO,iBAAiB,OAAO,UAAU;CAC5D,KAAK,MAAM,QAAQ,OAAO;EACxB,MAAM,WAAW,gBAAgB,MAAM,MAAM;EAC7C,MAAM,QAAQ,WAAW,IAAI,IAAI,cAAc,MAAM,IAAI;EACzD,OAAO,KAAK,IAAI,MAAM,QAAQ;EAC9B,QAAQ,KAAK,IAAI,OAAO,WAAW,KAAK;CAC1C;CACA,OAAO;EAAE;EAAM;CAAM;AACvB;;AAGA,SAAgB,WAAW,QAA6B;CACtD,MAAM,EAAE,MAAM,UAAU,YAAY,MAAM;CAC1C,OAAO,QAAQ;AACjB;;;;;;;;AASA,SAAgB,aAAa,MAAc,QAA6B;CACtE,OAAO,gBAAgB,MAAM,MAAM,IAAI,YAAY,MAAM,CAAC,CAAC;AAC7D;;;;;;;;;;;;AAaA,SAAgB,OACd,GACA,GACA,QACA,QACe;CACf,IAAI,IAAI,KAAK,KAAK,WAAW,MAAM,KAAK,IAAI,KAAK,KAAK,QAAQ,OAAO;CAErE,MAAM,QAAQ,kBAAkB,OAAO,SAAS;CAIhD,IAAI,IAFF,UAAU,OAAO,uBAAuB,iCAGxC,KAAK,MAAM,QAAQ,OAAO;EACxB,IAAI,WAAW,IAAI,GAAG;EACtB,MAAM,OAAO,aAAa,MAAM,MAAM;EACtC,IAAI,QAAQ,KAAK,IAAI,OAAO,cAAc,MAAM,GAAG,OAAO;CAC5D;CAGF,MAAM,OAAO,OAAO,iBAAiB,OAAO,UAAU;CACtD,KAAK,MAAM,QAAQ,OAAO;EACxB,IAAI,WAAW,IAAI,GAAG;EACtB,MAAM,OAAO,aAAa,MAAM,MAAM;EACtC,IAAI,QAAQ,KAAK,IAAI,OAAO,MAAM,OAAO;CAC3C;CAEA,OAAO;AACT;;;;ACpKA,MAAM,WAA0C;CAC9C,CAAC,KAAK,KAAK;CACX,CAAC,KAAK,IAAI;CACV,CAAC,KAAK,IAAI;CACV,CAAC,KAAK,IAAI;CACV,CAAC,IAAI,CAAC;CACN,CAAC,KAAK,GAAG;CACT,CAAC,KAAK,GAAG;CACT,CAAC,KAAK,GAAG;AACX;AAEA,MAAM,eAAe,IAAI,IAAoB,QAAQ;;;;;;;AAQrD,MAAM,gBAA0C;CAAE,GAAG;CAAK,GAAG;AAAI;;;;;;;AA6CjE,SAAS,QAAQ,OAAe,OAAuB;CACrD,OAAO,YAAY,QAAQ,KAAK;AAClC;;AAGA,MAAM,mBACJ;;;;;;;;;;;;;;;;;AAkBF,SAAgB,WACd,MACA,UAA6B,CAAC,GACf;CACf,MAAM,EAAE,OAAO,IAAI,WAAW,MAAM,QAAQ,YAAY,OAAO;CAC/D,IAAI,SAAS,MAAM,SAAS,IAC1B,MAAM,IAAI,WAAW,4CAA4C;CAEnE,MAAM,YAAY,aAAa,IAAI,IAAI,KAAK;;;;;CAM5C,MAAM,SAAS,UAAkB;EAC/B,MAAM,OAAO,WAAW,KAAA,IAAY,MAAM,QAAQ,MAAM,IAAI,OAAO,KAAK;EACxE,OAAO,OAAO,IAAI,MAAM,IAAI,KAAK,QAAQ,KAAK,EAAE,IAAI;CACtD;CAEA,IAAI,CAAC,UAAU;EAGb,MAAM,SAAS,OAAO;EACtB,OAAO;GACL,SAAS,UACP,OAAO,SAAS,KAAK,IACjB,MAAM,KAAK,IAAI,YAAY,SAC3B,OAAO,KAAK;GAGlB,QAAQ,SAAS;IACf,MAAM,QAAQ,KAAK,KAAK,CAAC,CAAC,MAAM,gBAAgB;IAChD,IAAI,CAAC,OAAO,OAAO;IACnB,MAAM,QAAQ,OAAO,MAAM,EAAE;IAC7B,OAAO,OAAO,SAAS,KAAK,IAAI,QAAQ;GAC1C;EACF;CACF;CAEA,OAAO;EACL,SAAS,UAAU;GACjB,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,OAAO,OAAO,KAAK;GAChD,MAAM,KAAK,QAAQ;GAEnB,IAAI,QAAQ,SAAS,WAAW,GAAG,WAAW,UAAU,CAAC;GACzD,IAAI,OAAO,GAAG;IAIZ,MAAM,YAAY,KAAK,IAAI,EAAE;IAC7B,QAAQ;IACR,KAAK,IAAI,IAAI,SAAS,SAAS,GAAG,KAAK,GAAG,KACxC,IAAI,aAAa,SAAS,EAAE,CAAC,IAAI;KAC/B,QAAQ;KACR;IACF;GAEJ;GACA,IAAI,OAAO,MAAM,QAAQ,IAAI,SAAS,MAAM,CAAC,EAAE,CAAC;GAIhD,IAAI,KAAK,IAAI,OAAO,IAAI,CAAC,KAAK,OAAQ,QAAQ,SAAS,SAAS,GAAG;IACjE,SAAS;IACT,OAAO,MAAM,QAAQ,IAAI,SAAS,MAAM,CAAC,EAAE,CAAC;GAC9C;GACA,OAAO,OAAO,YAAY,SAAS,MAAM,CAAC,KAAK;EACjD;EAEA,QAAQ,SAAS;GACf,MAAM,QAAQ,KAAK,KAAK,CAAC,CAAC,MAAM,gBAAgB;GAChD,IAAI,CAAC,OAAO,OAAO;GACnB,MAAM,SAAS,OAAO,MAAM,EAAE;GAC9B,IAAI,CAAC,OAAO,SAAS,MAAM,GAAG,OAAO;GAErC,IAAI,SAAS,MAAM,EAAE,CAAC,KAAK;GAC3B,MAAM,gBAAgB,UAAU,KAAK;GACrC,IAAI,kBAAkB,MAAM,OAAO,WAAW,aAAa,GACzD,SAAS,OAAO,MAAM,cAAc,MAAM,CAAC,CAAC,KAAK;GAInD,IAAI,WAAW,IAAI,OAAO;GAK1B,IAAI,SAAwB;GAC5B,IAAI,SAAS,MAAM,OAAO,SAAS,IAAI,GACrC,SAAS,OAAO,MAAM,GAAG,OAAO,SAAS,KAAK,MAAM;QAC/C,IAAI,OAAO,UAAU,GAC1B,SAAS;GAEX,IAAI,WAAW,MAAM,OAAO;GAE5B,MAAM,aAAa,cAAc,WAAW;GAC5C,MAAM,QAAQ,aAAa,IAAI,UAAU;GAGzC,IAAI,UAAU,KAAA,GAAW,OAAO;GAChC,OAAQ,SAAS,QAAS;EAC5B;CACF;AACF"}

package/dist/index.d.cts

@@ -4,16 +4,57 @@
  */
 declare function clamp(value: number, min: number, max: number): number;
 /**
- * Normalize the value from 0 to 1
+ * Normalize the value from 0 to 1, spreading the range evenly.
+ *
+ * This is the linear mapping and takes no curve of its own; a `Scale` builds
+ * whatever curve it needs on top of it.
  */
-declare function normalizeValue(rawValue: number, min: number, max: number, skew?: number): number;
+declare function normalizeValue(value: number, min: number, max: number): number;
 /**
- * Convert normalized values back to raw values.
+ * Convert normalized values back to raw values, spreading the range evenly.
+ *
+ * The inverse of {@link normalizeValue}.
+ */
+declare function rawValue(normalizedValue: number, min: number, max: number): number;
+/**
+ * Put a value on the grid the caller asked for, rounding a half step upwards.
+ *
+ * The rounding is done on the quotient rather than by comparing the distance
+ * to the two neighbours, because both of those carry error of their own. The
+ * quotient is cleared of its artefact first: `0.15 / 0.1` is 1.4999999999999998,
+ * and a value sitting exactly on a half step would otherwise fall to whichever
+ * side the last bit happened to land on — 0.25 rounded up while 0.15 and 0.35
+ * rounded down.
  */
-declare function rawValue(normalizedValue: number, min: number, max: number, skew?: number): number;
-declare function skewWithCenterValue(centerValue: number, min: number, max: number): number;
 declare function stepValue(value: number, step: number): number;
 declare function toFixed(x: number, fractionDigits?: number): number;
+/**
+ * The significant decimal digits a double actually carries. A double holds a
+ * little under 16, so anything past this is the binary representation showing
+ * through rather than information.
+ */
+declare const SIGNIFICANT_DIGITS = 15;
+/**
+ * Drop the binary artefact from a computed value.
+ *
+ * Arithmetic on doubles leaves debris in the last couple of digits, and it
+ * accumulates: adding 0.1 to 5 twelve times gives 5.699999999999998 rather
+ * than 5.7, and the display of a control shows exactly that. Rounding to the
+ * digits a double can carry removes it, and adds nothing back — the value was
+ * already the result of a calculation whose own error is that size or larger.
+ *
+ * This is not the same as rounding to a `step`. {@link stepValue} puts a value
+ * on a grid the caller asked for and is a decision about the value; this only
+ * removes what was never in the value to begin with.
+ *
+ * @param significantDigits how many digits to keep. The default is the only
+ * one that is purely artefact removal; a smaller number starts discarding real
+ * precision.
+ *
+ * @example
+ * toPrecision(5.1 + 0.1) // 5.2, rather than 5.199999999999999
+ */
+declare function toPrecision(x: number, significantDigits?: number): number;
 declare function integerPart(x: number | string): string | undefined;
 declare function decimalPart(x: number | string): string | undefined;
 declare function radian(degree: number): number;
@@ -22,6 +63,224 @@ declare function mapValue(value: number, inMin: number, inMax: number, outMin: n
 declare function dbToGain(db: number): number;
 declare function gainToDb(gain: number): number;
 //#endregion
+//#region src/modifiers.d.ts
+/**
+ * Options for setting the amount of keyboard and mouse wheel changes.
+ */
+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.
+ */
+type Modifier = 'shift' | 'alt' | 'ctrl' | 'meta';
+/** The modifier flags of a `WheelEvent` or a `KeyboardEvent`. */
+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;
+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] }
+ */
+type ModifierValue<T extends ModifierSetting> = T | ModifierMap<T>;
+interface SelectedInputEvent {
+  option: InputEventOption;
+  /** Which modifier entry was chosen, or `null` for `default`. */
+  modifier: Modifier | null;
+}
+/**
+ * Pick the setting that applies, given the modifier keys being held.
+ *
+ * @example
+ * selectModifier({ default: 1, shift: 0.1 }, event)
+ */
+declare function selectModifier<T extends ModifierSetting>(options: ModifierValue<T>, modifiers?: ModifierState): {
+  value: T;
+  modifier: 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] }
+ */
+declare function mapModifier<T extends ModifierSetting, U extends ModifierSetting>(options: ModifierValue<T>, fn: (value: T) => U): ModifierValue<U>;
+/**
+ * Pick the amount that applies, given the modifier keys being held.
+ *
+ * @example
+ * selectInputEvent({ default: ['raw', 1], shift: ['raw', 0.1] }, event)
+ */
+declare function selectInputEvent(options: ModifierValue<InputEventOption>, modifiers?: ModifierState): SelectedInputEvent;
+//#endregion
+//#region src/scales.d.ts
+/**
+ * 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…
+ * ```
+ */
+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;
+}
+/**
+ * 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.
+ */
+declare const linearScale: Scale;
+/**
+ * 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
+ */
+declare function skewScale(skew: number): Scale;
+/**
+ * The skew factor for {@link skewScale} that puts `centerValue` at the middle
+ * of the travel — JUCE's `NormalisableRange::setSkewForCentre`.
+ */
+declare function skewWithCenterValue(centerValue: number, min: number, max: number): number;
+/**
+ * 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.
+ */
+declare const exponentialScale: Scale;
+/**
+ * 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
+ */
+declare function curveScale(curve: number): Scale;
+/**
+ * {@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
+ */
+declare function symmetricSkewScale(skew: number): Scale;
+/**
+ * The curve for {@link curveScale} that puts `centerValue` at the middle of
+ * the travel — the counterpart of {@link skewWithCenterValue}.
+ */
+declare function curveWithCenterValue(centerValue: number, min: number, max: number): number;
+/**
+ * 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.
+ */
+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)
+ */
+declare function applyDelta(value: number, direction: number, options: ModifierValue<InputEventOption>, { min, max, step, scale }: ValueRange, modifiers?: ModifierState): number;
+//#endregion
 //#region src/midi.d.ts
 declare const whiteKeys: readonly ["A", "B", "C", "D", "E", "F", "G"];
 type WhiteKey = (typeof whiteKeys)[number];
@@ -62,20 +321,193 @@ declare function isBlackKey(note: number | string): boolean;
  * @returns frequency [Hz]
  */
 declare function noteToFrequency(note: number | string, detune?: number, a4?: number): number;
+/**
+ * Semitones above the root, for each supported scale.
+ *
+ * Every entry starts at 0 and stays inside one octave, so a scale is a set of
+ * pitch classes rather than a set of notes: {@link inScale} compares against
+ * it with the octave taken out.
+ *
+ * `ionian` and `aeolian` are the same sets as `major` and `naturalMinor`; both
+ * spellings are here because both are what someone reaches for depending on
+ * whether they are thinking in keys or in modes.
+ */
+declare const scaleIntervals: {
+  readonly major: readonly [0, 2, 4, 5, 7, 9, 11];
+  readonly naturalMinor: readonly [0, 2, 3, 5, 7, 8, 10];
+  readonly harmonicMinor: readonly [0, 2, 3, 5, 7, 8, 11];
+  readonly melodicMinor: readonly [0, 2, 3, 5, 7, 9, 11];
+  readonly ionian: readonly [0, 2, 4, 5, 7, 9, 11];
+  readonly dorian: readonly [0, 2, 3, 5, 7, 9, 10];
+  readonly phrygian: readonly [0, 1, 3, 5, 7, 8, 10];
+  readonly lydian: readonly [0, 2, 4, 6, 7, 9, 11];
+  readonly mixolydian: readonly [0, 2, 4, 5, 7, 9, 10];
+  readonly aeolian: readonly [0, 2, 3, 5, 7, 8, 10];
+  readonly locrian: readonly [0, 1, 3, 5, 6, 8, 10];
+  readonly majorPentatonic: readonly [0, 2, 4, 7, 9];
+  readonly minorPentatonic: readonly [0, 3, 5, 7, 10];
+  readonly blues: readonly [0, 3, 5, 6, 7, 10];
+  readonly wholeTone: readonly [0, 2, 4, 6, 8, 10];
+  readonly chromatic: readonly [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11];
+};
+type ScaleName = keyof typeof scaleIntervals;
+/**
+ * Whether a note belongs to a scale, regardless of the octave either sits in.
+ *
+ * @param note noteNumber: 0 ~ 127 or noteName e.g. 'C3'
+ * @param root the note the scale is built on, in the same two forms
+ *
+ * @example
+ * ```ts
+ * inScale('F#4', 'D3', 'major') // true
+ * ```
+ */
+declare function inScale(note: number | string, root: number | string, name: ScaleName): boolean;
+/**
+ * The notes of a scale, ascending from `root`.
+ *
+ * The octave above the root is not included: ask for more `octaves` instead, so
+ * that concatenating the result of two calls does not repeat a note.
+ *
+ * @param root noteNumber: 0 ~ 127 or noteName e.g. 'C3'
+ * @param octaves how many octaves to cover
+ *
+ * @example
+ * ```ts
+ * scaleNotes('C3', 'majorPentatonic') // [48, 50, 52, 55, 57]
+ * ```
+ */
+declare function scaleNotes(root: number | string, name: ScaleName, octaves?: number): number[];
 //#endregion
-//#region src/types.d.ts
+//#region src/piano.d.ts
+type NoteRange = {
+  first: number;
+  last: number;
+};
 /**
- * Options for setting the amount of keyboard and mouse wheel changes.
+ * `[noteRange.first, noteRange.first + 1, ..., noteRange.last]`
+ */
+declare function getNoteRangeArray(noteRange: NoteRange): number[];
+/**
+ * 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.
+ */
+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;
+}
+/** Width of a black key in pixels. */
+declare function blackKeyWidth(layout: PianoLayout): number;
+/** Width of the whole keyboard in pixels. */
+declare function pianoWidth(layout: PianoLayout): number;
+/**
+ * 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`.
+ */
+declare function notePosition(note: number, layout: PianoLayout): number;
+/**
+ * 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
+ */
+declare function noteAt(x: number, y: number, height: number, layout: PianoLayout): number | null;
+//#endregion
+//#region src/unit.d.ts
+/**
+ * The SI prefixes {@link unitFormat} chooses between.
+ *
+ * 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.
+ */
+type SIPrefix = 'p' | 'n' | 'µ' | 'm' | '' | 'k' | 'M' | 'G';
+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. */
+interface UnitFormatter {
+  format: (value: number) => string;
+  parse: (text: string) => number;
+}
+/**
+ * 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.
+ *
+ * @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
+ * <NumberInput.Root {...unitFormat('Hz', { digits: 2 })} value={v} onChange={setV}>
  */
-type InputEventOption = ['normalized' | 'raw', number];
+declare function unitFormat(unit: string, options?: UnitFormatOptions): UnitFormatter;
 //#endregion
 //#region src/util.d.ts
-type Operator = '+' | '-' | '*' | '/';
-declare function styleHelper(value: string | number): string;
-declare function styleHelper(value: string | number, op: Operator, influencer?: number): string;
-declare function isEmpty(obj: object): boolean;
 declare function mod(n: number, m: number): number;
 declare function xor(a?: boolean, b?: boolean): boolean;
 //#endregion
-export { type InputEventOption, type NoteKey, type WhiteKey, clamp, dbToGain, decimalPart, degree, gainToDb, integerPart, isBlackKey, isEmpty, isWhiteKey, mapValue, mod, normalizeValue, noteKey, noteKeys, noteName, noteNumber, noteToFrequency, parseNoteName, radian, rawValue, skewWithCenterValue, stepValue, styleHelper, toFixed, whiteKeys, xor };
+export { type InputEventOption, type Modifier, type ModifierMap, type ModifierState, type ModifierValue, type NoteKey, type NoteRange, type PianoLayout, SIGNIFICANT_DIGITS, type SIPrefix, type Scale, type ScaleName, type SelectedInputEvent, type UnitFormatOptions, type UnitFormatter, type ValueRange, type WhiteKey, applyDelta, blackKeyWidth, clamp, curveScale, curveWithCenterValue, dbToGain, decimalPart, degree, exponentialScale, gainToDb, getNoteRangeArray, inScale, integerPart, isBlackKey, isWhiteKey, linearScale, mapModifier, mapValue, mod, normalizeValue, noteAt, noteKey, noteKeys, noteName, noteNumber, notePosition, noteToFrequency, parseNoteName, pianoWidth, radian, rawValue, scaleIntervals, scaleNotes, selectInputEvent, selectModifier, skewScale, skewWithCenterValue, stepValue, symmetricSkewScale, toFixed, toPrecision, unitFormat, whiteKeys, xor };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.cts","names":[],"sources":["../src/math.ts","../src/midi.ts","../src/types.ts","../src/util.ts"],"mappings":";;AAGA;;iBAAgB,KAAA,CAAM,KAAA,UAAe,GAAA,UAAa,GAAA;;;;iBAOlC,cAAA,CACd,QAAA,UACA,GAAA,UACA,GAAA,UACA,IAAA;;;AAJF;iBAcgB,QAAA,CACd,eAAA,UACA,GAAA,UACA,GAAA,UACA,IAAA;AAAA,iBAUc,mBAAA,CACd,WAAA,UACA,GAAA,UACA,GAAA;AAAA,iBAOc,SAAA,CAAU,KAAA,UAAe,IAAA;AAAA,iBASzB,OAAA,CAAQ,CAAA,UAAW,cAAA;AAAA,iBAInB,WAAA,CAAY,CAAA;AAAA,iBAOZ,WAAA,CAAY,CAAA;AAAA,iBAIZ,MAAA,CAAO,MAAA;AAAA,iBAIP,MAAA,CAAO,MAAA;AAAA,iBAIP,QAAA,CACd,KAAA,UACA,KAAA,UACA,KAAA,UACA,MAAA,UACA,MAAA;AAAA,iBAKc,QAAA,CAAS,EAAA;AAAA,iBAIT,QAAA,CAAS,IAAA;;;cC5FZ,SAAA;AAAA,KAED,QAAA,WAAmB,SAAA;AAAA,cAElB,QAAA;AAAA,KAeD,OAAA,WAAkB,QAAA;AAAA,iBAEd,aAAA,CAAc,QAAA;UAKY,QAAA;;;;;ADlB1C;;iBC2BgB,UAAA,CAAW,QAAA;;;;;;;iBAaX,QAAA,CAAS,UAAA,cAAwB,OAAA;AD1BjD;;;AAAA,iBCmCgB,OAAA,CAAQ,UAAA,WAAqB,OAAA;;;;iBAO7B,UAAA,CAAW,IAAA;;;AD5B3B;iBC4CgB,UAAA,CAAW,IAAA;;;;;;;iBAUX,eAAA,CAAgB,IAAA,mBAAuB,MAAA,WAAY,EAAA;;;;ADzFnE;;KEAY,gBAAA;;;KCHP,QAAA;AAAA,iBAEW,WAAA,CAAY,KAAA;AAAA,iBACZ,WAAA,CACd,KAAA,mBACA,EAAA,EAAI,QAAA,EACJ,UAAA;AAAA,iBAyBc,OAAA,CAAQ,GAAA;AAAA,iBAIR,GAAA,CAAI,CAAA,UAAW,CAAA;AAAA,iBAIf,GAAA,CAAI,CAAA,YAAW,CAAA"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/math.ts","../src/modifiers.ts","../src/scales.ts","../src/midi.ts","../src/piano.ts","../src/unit.ts","../src/util.ts"],"mappings":";;;;iBAGgB,MAAM,eAAe,aAAa;;;;;;;iBAUlC,eAAe,eAAe,aAAa;;;;;;iBAU3C,SAAS,yBAAyB,aAAa;;;;;;;;;;;iBAe/C,UAAU,eAAe;iBAUzB,QAAQ,WAAW;;;;;;cAStB;;;;;;;;;;;;;;;;;;;;;iBAsBG,YAAY,WAAW;iBAUvB,YAAY;iBAOZ,YAAY;iBAIZ,OAAO;iBAIP,OAAO;iBAIP,SACd,eACA,eACA,eACA,gBACA;iBAKc,SAAS;iBAIT,SAAS;;;;;;KCvHb;;;;;;;;KASA;;UAGK;EACf;EACA;EACA;EACA;;;KAIG,2BAA2B;KAEpB,YAAY,UAAU;EAAqB,SAAS;IAAM,QACpE,OAAO,UAAU;;;;;;;;KAUP,cAAc,UAAU,mBAAmB,IAAI,YAAY;UAEtD;EACf,QAAQ;;EAER,UAAU;;;;;;;;iBAsCI,eAAe,UAAU,iBACvC,SAAS,cAAc,IACvB,YAAY;EACT,OAAO;EAAG,UAAU;;;;;;;;;;;;;;;;iBAiCT,YACd,UAAU,iBACV,UAAU,iBACV,SAAS,cAAc,IAAI,KAAK,OAAO,MAAM,IAAI,cAAc;;;;;;;iBAgBjD,iBACd,SAAS,cAAc,mBACvB,YAAY,gBACX;;;;;;;;;;;;;;;;;;UClHc;;EAEf,YAAY,eAAe,aAAa;;EAExC,cAAc,kBAAkB,aAAa;;;;;;;;cAmBlC,aAAa;;;;;;;;;;;;;;;;;iBAqBV,UAAU,eAAe;;;;;iBAsBzB,oBACd,qBACA,aACA;;;;;;;;;;;;cAmBW,kBAAkB;;;;;;;;;;;;;;;;;;;;;;iBAqDf,WAAW,gBAAgB;;;;;;;;;;;;;iBAmD3B,mBAAmB,eAAe;;;;;iBAiClC,qBACd,qBACA,aACA;;;;;;;;UAkBe;EACf;EACA;;;;EAIA;;;;;;EAMA,QAAQ;;;;;;;;;;;;;;;;;;;;;;;iBAwBM,WACd,eACA,mBACA,SAAS,cAAc,qBACrB,KAAK,KAAK,MAAM,SAAuB,YACzC,YAAY;;;cCpTD;KAED,mBAAmB;cAElB;KAeD,kBAAkB;iBAQd,cAAc;EAOY,QAAA;EACZ;;;;;;iBAQd,WAAW;;;;;;;iBAeX,SAAS,wBAAwB;;;;iBAUjC,QAAQ,qBAAqB;;;;iBAQ7B,WAAW;;;;iBAiBX,WAAW;;;;;;;iBAUX,gBAAgB,uBAAuB,iBAAY;;;;;;;;;;;;cAiBtD;;;;;;;;;;;;;;;;;;KAsBD,yBAAyB;;;;;;;;;;;;iBAarB,QACd,uBACA,uBACA,MAAM;;;;;;;;;;;;;;;iBAuBQ,WACd,uBACA,MAAM,WACN;;;KCxLU;EACV;EACA;;;;;iBAMc,kBAAkB,WAAW;;;;;;;UAa5B;EACf,WAAW;;EAGX;;;;;;;EAQA;;;;;;EAOA;;;;;;EAOA;;;iBA8Bc,cAAc,QAAQ;;iBA0CtB,WAAW,QAAQ;;;;;;;;iBAYnB,aAAa,cAAc,QAAQ;;;;;;;;;;;;iBAenC,OACd,WACA,WACA,gBACA,QAAQ;;;;;;;;;;KC/IE;UAwBK;;;;;;;;;EASf,OAAO;;;;;;;;;;EAUP;;;;EAIA;;;;;EAKA;;;UAIe;EACf,SAAS;EACT,QAAQ;;;;;;;;;;;;;;;;;;iBAiCM,WACd,cACA,UAAS,oBACR;;;iBCvGa,IAAI,WAAW;iBAIf,IAAI,aAAW"}