@tremolo-ui/functions 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -2,20 +2,20 @@
 /**
  * clamp value between min and max
  */
-declare function clamp(value: number, min: number, max: number): number;
+export declare function clamp(value: number, min: number, max: number): number;
 /**
  * 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(value: number, min: number, max: number): number;
+export declare function normalizeValue(value: number, min: number, max: number): number;
 /**
  * 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;
+export 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.
  *
@@ -26,14 +26,8 @@ declare function rawValue(normalizedValue: number, min: number, max: number): nu
  * 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;
+export declare function stepValue(value: number, step: number): number;
+export declare function toFixed(x: number, fractionDigits?: number): number;
 /**
  * Drop the binary artefact from a computed value.
  *
@@ -54,85 +48,12 @@ declare const SIGNIFICANT_DIGITS = 15;
  * @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;
-declare function degree(radian: number): number;
-declare function mapValue(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number;
-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;
+export declare function toPrecision(x: number, significantDigits?: number): number;
+export declare function radian(degree: number): number;
+export declare function degree(radian: number): number;
+export declare function mapValue(value: number, inMin: number, inMax: number, outMin: number, outMax: number): number;
+export declare function dbToGain(db: number): number;
+export declare function gainToDb(gain: number): number;
 //#endregion
 //#region src/scales.d.ts
 /**
@@ -162,7 +83,7 @@ interface Scale {
  * The right default for anything already linear in perception: dB values,
  * pan, percentages, MIDI note numbers, semitones.
  */
-declare const linearScale: Scale;
+export declare const linearScale: Scale;
 /**
  * The power law of JUCE's `NormalisableRange::skew`, applied to `value - min`.
  *
@@ -179,12 +100,12 @@ declare const linearScale: Scale;
  *
  * @param skew the JUCE skew factor
  */
-declare function skewScale(skew: number): Scale;
+export 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;
+export 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.
@@ -196,7 +117,7 @@ declare function skewWithCenterValue(centerValue: number, min: number, max: numb
  * ratio reaches zero or crosses it. Use {@link curveScale} for a range that
  * starts at 0.
  */
-declare const exponentialScale: Scale;
+export 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
@@ -218,7 +139,7 @@ declare const exponentialScale: Scale;
  *
  * @param curve how hard the curve bends, and in which direction
  */
-declare function curveScale(curve: number): Scale;
+export 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`.
@@ -231,12 +152,12 @@ declare function curveScale(curve: number): Scale;
  *
  * @param skew the JUCE skew factor
  */
-declare function symmetricSkewScale(skew: number): Scale;
+export 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;
+export 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.
@@ -258,35 +179,13 @@ interface ValueRange {
    */
   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"];
+export declare const whiteKeys: readonly ["A", "B", "C", "D", "E", "F", "G"];
 type WhiteKey = (typeof whiteKeys)[number];
-declare const noteKeys: readonly ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
+export declare const noteKeys: readonly ["C", "C#", "D", "D#", "E", "F", "F#", "G", "G#", "A", "A#", "B"];
 type NoteKey = (typeof noteKeys)[number];
-declare function parseNoteName(noteName: string): {
+export declare function parseNoteName(noteName: string): {
   letter: WhiteKey;
   accidental: "#" | "##" | "b" | "bb" | "";
   octave: number;
@@ -294,33 +193,33 @@ declare function parseNoteName(noteName: string): {
 /**
  * Convert noteName to noteNumber
  */
-declare function noteNumber(noteName: string): number;
+export declare function noteNumber(noteName: string): number;
 /**
  * Convert noteNumber to noteName
  * C-1 = 0
  * G9 = 127
  * @param noteNumber noteNumber
  */
-declare function noteName(noteNumber: number): `${NoteKey}${number}`;
+export declare function noteName(noteNumber: number): `${NoteKey}${number}`;
 /**
  * Convert noteNumber to noteKey
  */
-declare function noteKey(noteNumber: number): NoteKey;
+export declare function noteKey(noteNumber: number): NoteKey;
 /**
  * @param note noteNumber: 0 ~ 127 or noteName e.g. 'C3'
  */
-declare function isWhiteKey(note: number | string): boolean;
+export declare function isWhiteKey(note: number | string): boolean;
 /**
  * @param note noteNumber: 0 ~ 127 or noteName e.g. 'C3'
  */
-declare function isBlackKey(note: number | string): boolean;
+export declare function isBlackKey(note: number | string): boolean;
 /**
  * @param note noteNumber: 0 ~ 127 or noteName e.g. 'C3'
  * @param detune [cent]
  * @param a4 A4 frequency [Hz]
  * @returns frequency [Hz]
  */
-declare function noteToFrequency(note: number | string, detune?: number, a4?: number): number;
+export declare function noteToFrequency(note: number | string, detune?: number, a4?: number): number;
 /**
  * Semitones above the root, for each supported scale.
  *
@@ -332,7 +231,7 @@ declare function noteToFrequency(note: number | string, detune?: number, a4?: nu
  * spellings are here because both are what someone reaches for depending on
  * whether they are thinking in keys or in modes.
  */
-declare const scaleIntervals: {
+export 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];
@@ -362,7 +261,7 @@ type ScaleName = keyof typeof scaleIntervals;
  * inScale('F#4', 'D3', 'major') // true
  * ```
  */
-declare function inScale(note: number | string, root: number | string, name: ScaleName): boolean;
+export declare function inScale(note: number | string, root: number | string, name: ScaleName): boolean;
 /**
  * The notes of a scale, ascending from `root`.
  *
@@ -377,71 +276,7 @@ declare function inScale(note: number | string, root: number | string, name: Sca
  * scaleNotes('C3', 'majorPentatonic') // [48, 50, 52, 55, 57]
  * ```
  */
-declare function scaleNotes(root: number | string, name: ScaleName, octaves?: number): number[];
-//#endregion
-//#region src/piano.d.ts
-type NoteRange = {
-  first: number;
-  last: number;
-};
-/**
- * `[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;
+export declare function scaleNotes(root: number | string, name: ScaleName, octaves?: number): number[];
 //#endregion
 //#region src/unit.d.ts
 /**
@@ -503,11 +338,7 @@ interface UnitFormatter {
  * @example
  * <NumberInput.Root {...unitFormat('Hz', { digits: 2 })} value={v} onChange={setV}>
  */
-declare function unitFormat(unit: string, options?: UnitFormatOptions): UnitFormatter;
-//#endregion
-//#region src/util.d.ts
-declare function mod(n: number, m: number): number;
-declare function xor(a?: boolean, b?: boolean): boolean;
+export declare function unitFormat(unit: string, options?: UnitFormatOptions): UnitFormatter;
 //#endregion
-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 };
+export type { NoteKey, SIPrefix, Scale, ScaleName, UnitFormatOptions, UnitFormatter, ValueRange, WhiteKey };
 //# 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/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"}
+{"version":3,"file":"index.d.cts","names":[],"sources":["../src/math.ts","../src/scales.ts","../src/midi.ts","../src/unit.ts"],"mappings":";;;;wBAGgB,MAAM,eAAe,aAAa;;;;;;;wBAUlC,eAAe,eAAe,aAAa;;;;;;wBAU3C,SAAS,yBAAyB,aAAa;;;;;;;;;;;wBAe/C,UAAU,eAAe;wBAUzB,QAAQ,WAAW;;;;;;;;;;;;;;;;;;;;;wBA+BnB,YAAY,WAAW;wBAUvB,OAAO;wBAIP,OAAO;wBAIP,SACd,eACA,eACA,eACA,gBACA;wBAKc,SAAS;wBAIT,SAAS;;;;;;;;;;;;;;;;;;UC9FR;;EAEf,YAAY,eAAe,aAAa;;EAExC,cAAc,kBAAkB,aAAa;;;;;;;;qBAmBlC,aAAa;;;;;;;;;;;;;;;;;wBAqBV,UAAU,eAAe;;;;;wBAsBzB,oBACd,qBACA,aACA;;;;;;;;;;;;qBAmBW,kBAAkB;;;;;;;;;;;;;;;;;;;;;;wBAqDf,WAAW,gBAAgB;;;;;;;;;;;;;wBAmD3B,mBAAmB,eAAe;;;;;wBAiClC,qBACd,qBACA,aACA;;;;;;;;UAkBe;EACf;EACA;;;;EAIA;;;;;;EAMA,QAAQ;;;;qBCxQG;KAED,mBAAmB;qBAElB;KAeD,kBAAkB;wBAQd,cAAc;EAOY,QAAA;EACZ;;;;;;wBAQd,WAAW;;;;;;;wBAeX,SAAS,wBAAwB;;;;wBAUjC,QAAQ,qBAAqB;;;;wBAQ7B,WAAW;;;;wBAiBX,WAAW;;;;;;;wBAUX,gBAAgB,uBAAuB,iBAAY;;;;;;;;;;;;qBAiBtD;;;;;;;;;;;;;;;;;;KAsBD,yBAAyB;;;;;;;;;;;;wBAarB,QACd,uBACA,uBACA,MAAM;;;;;;;;;;;;;;;wBAuBQ,WACd,uBACA,MAAM,WACN;;;;;;;;;;KC1LU;UAwBK;;;;;;;;;EASf,OAAO;;;;;;;;;;EAUP;;;;EAIA;;;;;EAKA;;;UAIe;EACf,SAAS;EACT,QAAQ;;;;;;;;;;;;;;;;;;wBAiCM,WACd,cACA,UAAS,oBACR"}