@tremolo-ui/functions 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -16,8 +16,45 @@ declare function normalizeValue(value: number, min: number, max: number): number
  * 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 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;
@@ -26,11 +63,76 @@ 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/types.d.ts
+//#region src/modifiers.d.ts
 /**
  * Options for setting the amount of keyboard and mouse wheel changes.
  */
-type InputEventOption = ['normalized' | 'raw', number];
+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
 /**
@@ -166,16 +268,18 @@ interface ValueRange {
  * @param direction which way, and how many times, to apply the option. The
  * size of one step is `option[1]`, so this is normally `1` or `-1`.
  *
+ * @param modifiers the event, for `options` that name a modifier key. See
+ * {@link selectInputEvent}.
+ *
  * @example
  * // ArrowDown on a slider whose keyboard option is ['raw', 1]
  * applyDelta(value, -1, keyboard, { min, max, step, scale })
+ *
+ * @example
+ * // Shift+ArrowDown, where `keyboard` is { default: …, shift: ['raw', 0.1] }
+ * applyDelta(value, -1, keyboard, range, event)
  */
-declare function applyDelta(value: number, direction: number, [mode, amount]: InputEventOption, {
-  min,
-  max,
-  step,
-  scale
-}: ValueRange): number;
+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"];
@@ -341,52 +445,69 @@ declare function noteAt(x: number, y: number, height: number, layout: PianoLayou
 //#endregion
 //#region src/unit.d.ts
 /**
- * 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]]
- */
-type Units = [string, number][];
-/**
- * Pick the unit a value is displayed in: the largest one whose scale does not
- * exceed the magnitude of the value.
+ * 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.
  */
-declare function selectUnit(units: Units, value: number): [string, number];
+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;
+}
 /**
- * Render a value as text, in the unit that suits its magnitude.
+ * Build the `format` and `parse` of a unit, as one pair.
  *
- * @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.
+ * 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
- * formatValue(1234, [['Hz', 1], ['kHz', 1000]], 2) // '1.23kHz'
- * formatValue(1.5, 'Hz')                           // '1.5Hz'
- */
-declare function formatValue(value: number, units?: string | Units, digit?: number): string;
-/**
- * Read a value back out of text, undoing the scaling of {@link formatValue}.
- *
- * 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.
+ * 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}>
  */
-declare function parseValue(text: string, units?: string | Units): 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 NoteRange, type PianoLayout, type Scale, type ScaleName, type Units, type ValueRange, type WhiteKey, applyDelta, blackKeyWidth, clamp, curveScale, curveWithCenterValue, dbToGain, decimalPart, degree, exponentialScale, formatValue, gainToDb, getNoteRangeArray, inScale, integerPart, isBlackKey, isEmpty, isWhiteKey, linearScale, mapValue, mod, normalizeValue, noteAt, noteKey, noteKeys, noteName, noteNumber, notePosition, noteToFrequency, parseNoteName, parseValue, pianoWidth, radian, rawValue, scaleIntervals, scaleNotes, selectUnit, skewScale, skewWithCenterValue, stepValue, styleHelper, symmetricSkewScale, 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.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/math.ts","../src/types.ts","../src/scales.ts","../src/midi.ts","../src/piano.ts","../src/unit.ts","../src/util.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","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"}