@tspro/web-music-score 4.0.0 → 4.1.0

package/dist/react-ui/index.js

@@ -1,4 +1,4 @@
-/* WebMusicScore v4.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v4.1.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
@@ -200,34 +200,54 @@ var DefaultColors = {
   TextColor: "white"
 };
 var FretPosition = class {
+  /**
+   * Create new fret position object instance.
+   * @param guitarCtx - Guitar context.
+   * @param stringId - String index in range [0, 5].
+   * @param fretId - Fret index, 0 = open string fret position.
+   * @param chromaticId - Chromatic id.
+   */
   constructor(guitarCtx, stringId, fretId, chromaticId) {
     this.guitarCtx = guitarCtx;
     this.stringId = stringId;
     this.fretId = fretId;
     this.chromaticId = chromaticId;
+    /** Note of this fret position. */
     __publicField(this, "note");
+    /** Is note of this fret position a scale note? */
     __publicField(this, "isScaleNote");
+    /** Is note of this fret position a scale root note? */
     __publicField(this, "isScaleRootNote");
+    /** Is note circle/text of this fret position visible? */
     __publicField(this, "isVisible", false);
+    /** Text (e.g. note name) of this fret position. */
     __publicField(this, "text", "");
+    /** Text color. */
     __publicField(this, "textColor", DefaultColors.TextColor);
+    /** Fill color of note circle. */
     __publicField(this, "fillColor");
+    /** Border color of note circle. */
     __publicField(this, "borderColor");
+    /** Is barre? (Reserved for future) */
     __publicField(this, "isBarre", false);
     let { scale } = guitarCtx;
     this.note = scale.getPreferredChromaticNote(chromaticId);
     this.isScaleNote = scale.isScaleNote(this.note);
     this.isScaleRootNote = scale.isScaleRootNote(this.note);
   }
+  /** Chromatic class getter. */
   get chromaticClass() {
     return import_theory3.Note.getChromaticClass(this.chromaticId);
   }
+  /** Show note circle/text of this fret position. */
   show() {
     this.isVisible = true;
   }
+  /** Hide note circle/text of this fret position. */
   hide() {
     this.isVisible = false;
   }
+  /** Set default note name. */
   setDefaultText() {
     let { pitchNotation, scale, guitarNoteLabel } = this.guitarCtx;
     switch (guitarNoteLabel) {
@@ -242,20 +262,31 @@ var FretPosition = class {
         break;
     }
   }
+  /** Set default fill color of note circle. */
   setDefaultFillColor() {
     this.fillColor = this.isScaleRootNote ? DefaultColors.ScaleRootNoteColor : this.isScaleNote ? DefaultColors.ScaleNoteColor : DefaultColors.NonScaleNoteColor;
   }
+  /** Set default border color of note circle. */
   setDefaultBorderColor(showBorder = false) {
     this.borderColor = showBorder ? DefaultColors.DefaultBorderColor : void 0;
   }
 };
 var GuitarContext = class _GuitarContext {
+  /**
+   * Create new guitar context object instance.
+   * @param tuningName - Tuning name (e.g. "Standard").
+   * @param scale - Scale.
+   * @param handedness - Handedness.
+   * @param pitchNotation - Pitch notation.
+   * @param guitarNoteLabel - Guitar note label type.
+   */
   constructor(tuningName, scale, handedness, pitchNotation, guitarNoteLabel) {
     this.tuningName = tuningName;
     this.scale = scale;
     this.handedness = handedness;
     this.pitchNotation = pitchNotation;
     this.guitarNoteLabel = guitarNoteLabel;
+    /** Maximum fret index value. */
     __publicField(this, "maxFretId");
     __publicField(this, "fretPositionTable");
     __publicField(this, "tuningStrings");
@@ -270,6 +301,12 @@ var GuitarContext = class _GuitarContext {
       }
     }
   }
+  /**
+   * Get fret position object.
+   * @param stringId - String index in range [0,5].
+   * @param fretId - Fret index, 0 = open string fret position.
+   * @returns - Fret position object.
+   */
   getFretPosition(stringId, fretId) {
     if (!import_ts_utils_lib2.Utils.Is.isInteger(stringId) || stringId < 0 || stringId > 5) {
       throw new import_core.MusicError(import_core.MusicErrorType.InvalidArg, `Invalid stringId: + ${stringId}`);
@@ -279,24 +316,58 @@ var GuitarContext = class _GuitarContext {
       return this.fretPositionTable[stringId][fretId];
     }
   }
+  /**
+   * Get tuning value (Note) of given string.
+   * @param stringId - STring index in range [0, 5].
+   * @returns - Note of given string played unfretted.
+   */
   getStringTuning(stringId) {
     return this.tuningStrings[stringId];
   }
+  /**
+   * Get tuning overview (e.g. "E2 - A2 - D3 - G3 - B3 - E4").
+   * @returns - Tuning overview string.
+   */
   getTuningOverview() {
     return this.tuningStrings.slice().reverse().map((note) => note.format(this.pitchNotation, import_theory2.SymbolSet.Unicode)).join(" - ");
   }
+  /**
+   * Create copy of this guitar context with new tuning name.
+   * @param tuningName - New tuning name.
+   * @returns - Guitar context.
+   */
   alterTuningName(tuningName) {
     return tuningName === this.tuningName ? this : new _GuitarContext(tuningName, this.scale, this.handedness, this.pitchNotation, this.guitarNoteLabel);
   }
+  /**
+   * Create copy of this guitar context with new scale.
+   * @param scale - New scale.
+   * @returns - Guitar context.
+   */
   alterScale(scale) {
     return import_theory3.Scale.equals(scale, this.scale) ? this : new _GuitarContext(this.tuningName, scale, this.handedness, this.pitchNotation, this.guitarNoteLabel);
   }
+  /**
+   * Create copy of this guitar context with handedness.
+   * @param handedness - New handedness.
+   * @returns - Guitar context.
+   */
   alterHandedness(handedness) {
     return handedness === this.handedness ? this : new _GuitarContext(this.tuningName, this.scale, handedness, this.pitchNotation, this.guitarNoteLabel);
   }
+  /**
+   * Create copy of this guitar context with new pitch notation.
+   * @param pitchNotation - New pitch notation.
+   * @returns - Guitar context.
+   */
   alterPitchNotation(pitchNotation) {
     return pitchNotation === this.pitchNotation ? this : new _GuitarContext(this.tuningName, this.scale, this.handedness, pitchNotation, this.guitarNoteLabel);
   }
+  /**
+   * Create copy of this guitar context with new guitar note label type.
+   * @param guitarNoteLabel - New guitar note label type.
+   * @returns - Guitar context.
+   */
   alterGuitarNoteLabel(guitarNoteLabel) {
     return guitarNoteLabel === this.guitarNoteLabel ? this : new _GuitarContext(this.tuningName, this.scale, this.handedness, this.pitchNotation, guitarNoteLabel);
   }
@@ -370,6 +441,12 @@ var Fret = class _Fret {
   }
 };
 var FretPositionData = class {
+  /**
+   * Create new fret position data instance.
+   * @param fretPosition - Fret position.
+   * @param cellRect - Rect of fret position cell (space around string and between fret and next fret).
+   * @param noteRect - Rect to display note name in circle.
+   */
   constructor(fretPosition, cellRect, noteRect) {
     this.fretPosition = fretPosition;
     this.cellRect = cellRect;

package/dist/react-ui/index.mjs

@@ -1,7 +1,7 @@
-/* WebMusicScore v4.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v4.1.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 import {
   __publicField
-} from "../chunk-D643HZHM.mjs";
+} from "../chunk-MHNTJ6FU.mjs";
 
 // src/react-ui/circle-of-fifths.tsx
 import * as React from "react";
@@ -159,34 +159,54 @@ var DefaultColors = {
   TextColor: "white"
 };
 var FretPosition = class {
+  /**
+   * Create new fret position object instance.
+   * @param guitarCtx - Guitar context.
+   * @param stringId - String index in range [0, 5].
+   * @param fretId - Fret index, 0 = open string fret position.
+   * @param chromaticId - Chromatic id.
+   */
   constructor(guitarCtx, stringId, fretId, chromaticId) {
     this.guitarCtx = guitarCtx;
     this.stringId = stringId;
     this.fretId = fretId;
     this.chromaticId = chromaticId;
+    /** Note of this fret position. */
     __publicField(this, "note");
+    /** Is note of this fret position a scale note? */
     __publicField(this, "isScaleNote");
+    /** Is note of this fret position a scale root note? */
     __publicField(this, "isScaleRootNote");
+    /** Is note circle/text of this fret position visible? */
     __publicField(this, "isVisible", false);
+    /** Text (e.g. note name) of this fret position. */
     __publicField(this, "text", "");
+    /** Text color. */
     __publicField(this, "textColor", DefaultColors.TextColor);
+    /** Fill color of note circle. */
     __publicField(this, "fillColor");
+    /** Border color of note circle. */
     __publicField(this, "borderColor");
+    /** Is barre? (Reserved for future) */
     __publicField(this, "isBarre", false);
     let { scale } = guitarCtx;
     this.note = scale.getPreferredChromaticNote(chromaticId);
     this.isScaleNote = scale.isScaleNote(this.note);
     this.isScaleRootNote = scale.isScaleRootNote(this.note);
   }
+  /** Chromatic class getter. */
   get chromaticClass() {
     return Note2.getChromaticClass(this.chromaticId);
   }
+  /** Show note circle/text of this fret position. */
   show() {
     this.isVisible = true;
   }
+  /** Hide note circle/text of this fret position. */
   hide() {
     this.isVisible = false;
   }
+  /** Set default note name. */
   setDefaultText() {
     let { pitchNotation, scale, guitarNoteLabel } = this.guitarCtx;
     switch (guitarNoteLabel) {
@@ -201,20 +221,31 @@ var FretPosition = class {
         break;
     }
   }
+  /** Set default fill color of note circle. */
   setDefaultFillColor() {
     this.fillColor = this.isScaleRootNote ? DefaultColors.ScaleRootNoteColor : this.isScaleNote ? DefaultColors.ScaleNoteColor : DefaultColors.NonScaleNoteColor;
   }
+  /** Set default border color of note circle. */
   setDefaultBorderColor(showBorder = false) {
     this.borderColor = showBorder ? DefaultColors.DefaultBorderColor : void 0;
   }
 };
 var GuitarContext = class _GuitarContext {
+  /**
+   * Create new guitar context object instance.
+   * @param tuningName - Tuning name (e.g. "Standard").
+   * @param scale - Scale.
+   * @param handedness - Handedness.
+   * @param pitchNotation - Pitch notation.
+   * @param guitarNoteLabel - Guitar note label type.
+   */
   constructor(tuningName, scale, handedness, pitchNotation, guitarNoteLabel) {
     this.tuningName = tuningName;
     this.scale = scale;
     this.handedness = handedness;
     this.pitchNotation = pitchNotation;
     this.guitarNoteLabel = guitarNoteLabel;
+    /** Maximum fret index value. */
     __publicField(this, "maxFretId");
     __publicField(this, "fretPositionTable");
     __publicField(this, "tuningStrings");
@@ -229,6 +260,12 @@ var GuitarContext = class _GuitarContext {
       }
     }
   }
+  /**
+   * Get fret position object.
+   * @param stringId - String index in range [0,5].
+   * @param fretId - Fret index, 0 = open string fret position.
+   * @returns - Fret position object.
+   */
   getFretPosition(stringId, fretId) {
     if (!Utils2.Is.isInteger(stringId) || stringId < 0 || stringId > 5) {
       throw new MusicError(MusicErrorType.InvalidArg, `Invalid stringId: + ${stringId}`);
@@ -238,24 +275,58 @@ var GuitarContext = class _GuitarContext {
       return this.fretPositionTable[stringId][fretId];
     }
   }
+  /**
+   * Get tuning value (Note) of given string.
+   * @param stringId - STring index in range [0, 5].
+   * @returns - Note of given string played unfretted.
+   */
   getStringTuning(stringId) {
     return this.tuningStrings[stringId];
   }
+  /**
+   * Get tuning overview (e.g. "E2 - A2 - D3 - G3 - B3 - E4").
+   * @returns - Tuning overview string.
+   */
   getTuningOverview() {
     return this.tuningStrings.slice().reverse().map((note) => note.format(this.pitchNotation, SymbolSet2.Unicode)).join(" - ");
   }
+  /**
+   * Create copy of this guitar context with new tuning name.
+   * @param tuningName - New tuning name.
+   * @returns - Guitar context.
+   */
   alterTuningName(tuningName) {
     return tuningName === this.tuningName ? this : new _GuitarContext(tuningName, this.scale, this.handedness, this.pitchNotation, this.guitarNoteLabel);
   }
+  /**
+   * Create copy of this guitar context with new scale.
+   * @param scale - New scale.
+   * @returns - Guitar context.
+   */
   alterScale(scale) {
     return Scale2.equals(scale, this.scale) ? this : new _GuitarContext(this.tuningName, scale, this.handedness, this.pitchNotation, this.guitarNoteLabel);
   }
+  /**
+   * Create copy of this guitar context with handedness.
+   * @param handedness - New handedness.
+   * @returns - Guitar context.
+   */
   alterHandedness(handedness) {
     return handedness === this.handedness ? this : new _GuitarContext(this.tuningName, this.scale, handedness, this.pitchNotation, this.guitarNoteLabel);
   }
+  /**
+   * Create copy of this guitar context with new pitch notation.
+   * @param pitchNotation - New pitch notation.
+   * @returns - Guitar context.
+   */
   alterPitchNotation(pitchNotation) {
     return pitchNotation === this.pitchNotation ? this : new _GuitarContext(this.tuningName, this.scale, this.handedness, pitchNotation, this.guitarNoteLabel);
   }
+  /**
+   * Create copy of this guitar context with new guitar note label type.
+   * @param guitarNoteLabel - New guitar note label type.
+   * @returns - Guitar context.
+   */
   alterGuitarNoteLabel(guitarNoteLabel) {
     return guitarNoteLabel === this.guitarNoteLabel ? this : new _GuitarContext(this.tuningName, this.scale, this.handedness, this.pitchNotation, guitarNoteLabel);
   }
@@ -329,6 +400,12 @@ var Fret = class _Fret {
   }
 };
 var FretPositionData = class {
+  /**
+   * Create new fret position data instance.
+   * @param fretPosition - Fret position.
+   * @param cellRect - Rect of fret position cell (space around string and between fret and next fret).
+   * @param noteRect - Rect to display note name in circle.
+   */
   constructor(fretPosition, cellRect, noteRect) {
     this.fretPosition = fretPosition;
     this.cellRect = cellRect;

package/dist/scale-DQNA-YLD.d.ts

@@ -0,0 +1,230 @@
+import { N as Note, S as SymbolSet } from './note-eA2xPPiG.js';
+import { K as KeySignature } from './tempo-Bp1UzsrZ.js';
+
+/** Interval direction type. */
+type IntervalDirection = "Unison" | "Ascending" | "Descending";
+/** Interval quality type. */
+type IntervalQuality = "Perfect" | "Major" | "minor" | "Augmented" | "Doubly Augmented" | "diminished" | "doubly diminished";
+/**
+ * Validate interval quality of unkown value.
+ * @param q - Interval quality to validate.
+ * @returns - Interval quality if valid, else throws.
+ */
+declare function validateIntervalQuality(q: unknown): IntervalQuality;
+/** Interval class. */
+declare class Interval {
+    readonly note1: Note;
+    readonly note2: Note;
+    /** Interval direction. */
+    readonly direction: IntervalDirection;
+    /** Number of semitones. */
+    readonly semitones: number;
+    /** Interval quantity. */
+    readonly quantity: number;
+    /** Interval quality. */
+    readonly quality: IntervalQuality;
+    private constructor();
+    /**
+     * Get interval between given two notes.
+     * @param note1 - First note.
+     * @param note2 - Second note.
+     * @returns - Interval if valid, or undefined.
+     */
+    static get(note1: Note, note2: Note): Interval | undefined;
+    /**
+     * Get string presentation of interval (e.g. "Descending Major 2").
+     * @returns - Interval string.
+     */
+    toString(): string;
+    /**
+     * Get abbrevated string presentation of interval (e.g. "↓M2").
+     * @returns - Interval abbrevated string.
+     */
+    toAbbrString(): string;
+}
+
+/** Degree type. */
+type Degree = 1 | 2 | "b3" | 3 | 4 | "b5" | 5 | "#5" | 6 | "bb7" | "b7" | 7 | "#7" | "b9" | 9 | "#9" | 11 | 13;
+/** Scale type enum. */
+declare enum ScaleType {
+    /** Major scale. */
+    Major = "Major",
+    /** Natural minor scale. */
+    NaturalMinor = "Natural Minor",
+    /** Harmonic minor scale. */
+    HarmonicMinor = "Harmonic Minor",
+    /** Mode: Ionian. */
+    Ionian = "Ionian",
+    /** Mode: Dorian. */
+    Dorian = "Dorian",
+    /** Mode: Phrygian. */
+    Phrygian = "Phrygian",
+    /** Mode: Lydian. */
+    Lydian = "Lydian",
+    /** Mode: Mixolydian. */
+    Mixolydian = "Mixolydian",
+    /** Mode: Aeolian (minor). */
+    Aeolian = "Aeolian",
+    /** Mode: Locrian (rare). */
+    Locrian = "Locrian",
+    /** Major pentatonic scale. */
+    MajorPentatonic = "Major Pentatonic",
+    /** Minor pentatoni scale. */
+    MinorPentatonic = "Minor Pentatonic",
+    /** Major hexatonic blues scale. */
+    MajorHexatonicBlues = "Major Hexatonic Blues",
+    /** Minor hexatonic blues scale. */
+    MinorHexatonicBlues = "Minor Hexatonic Blues",
+    /** Heptatonic blues scale. */
+    HeptatonicBlues = "Heptatonic Blues"
+}
+/** Scale class. */
+declare class Scale extends KeySignature {
+    readonly tonic: string;
+    readonly scaleType: ScaleType;
+    /** Degrees of scale notes. */
+    private readonly scaleDegrees;
+    /** Scale notes. */
+    private readonly scaleNotes;
+    /** Degrees (or undefined) of chromatic classes. */
+    private readonly chromaticClassDegree;
+    /**
+     * Create nev scale object instance.
+     * @param tonic - Tonic (e.g. "C" in "C Major").
+     * @param scaleType - Scale typo ("e.g. "Major" in "C Major").
+     */
+    constructor(tonic: string, scaleType: ScaleType);
+    /**
+     * Compare if two scales equals.
+     * @param a - Scale a.
+     * @param b - Scale b.
+     * @returns - Boolean equality of given scales.
+     */
+    static equals(a: Scale | null | undefined, b: Scale | null | undefined): boolean;
+    /**
+     * Get scale name.
+     * @param symbolSet - Symbol set to format scale name in ascii or unicode.
+     * @returns - Scale name string.
+     */
+    getScaleName(symbolSet?: SymbolSet): string;
+    /**
+     * Get scale notes.
+     * @param bottomNote - Computed scale notes begin no lower than this note.
+     * @param numOctaves - How many octaves?
+     * @returns - Array of scale notes.
+     */
+    getScaleNotes(bottomNote: string, numOctaves: number): ReadonlyArray<Note>;
+    /**
+     * Get scale overview (e.g. "C - D - E - F - G - A - B" for "C Major" scale).
+     * @returns - Scale overview string.
+     */
+    getScaleOverview(): string;
+    /**
+     * Get scale steps, array of 1 (half step) and 2 (whole step), (e.g. [2, 2, 1, 2, 2, 2, 1] for Major scale).
+     * @returns - Array of scale steps.
+     */
+    getScaleSteps(): number[];
+    /**
+     * Get scale steps string presentation, array of "H" (half step) and "W" (whole step), (e.g. ["W", "W", "H", "W", "W", "W", "H"] for Major scale).
+     * @returns - Array of scale steps string presentation.
+     */
+    getScaleStringSteps(): string[];
+    /**
+     * Test if given note is scale note.
+     * @param note - Note to test.
+     * @returns - True/false.
+     */
+    isScaleNote(note: Note): boolean;
+    /**
+     * Test if given note is scale root note.
+     * @param note - Note to test.
+     * @returns - True/false.
+     */
+    isScaleRootNote(note: Note): boolean;
+    /**
+     * Get interval value between scale root note and given note.
+     * @param note - Note.
+     * @returns - Interval.
+     */
+    getIntervalFromRootNote(note: Note): Interval;
+    private preferredChromaticNoteCache;
+    /**
+     * Get preferred chromatic note from given chromatic id.
+     * @param chromaticId - Chromatic id.
+     * @returns - Note.
+     */
+    getPreferredChromaticNote(chromaticId: number): Note;
+}
+/** Scale factory class. */
+declare class ScaleFactory {
+    readonly type: ScaleType;
+    private tonicList;
+    private scaleMap;
+    /**
+     * Create new scale factory object instance.
+     * @param type - Scale type.
+     */
+    constructor(type: ScaleType);
+    /**
+     * Get list of tonics (e.g. "C", "C#", ... for Major scale type).
+     * @returns - Array of tonics.
+     */
+    getTonicList(): ReadonlyArray<string>;
+    /**
+     * Get default tonic.
+     * @returns - Default tonic.
+     */
+    getDefaultTonic(): string;
+    /**
+     * Get scale type.
+     * @returns - SCale type.
+     */
+    getType(): ScaleType;
+    /**
+     * Get scale by given tonic.
+     * @param tonic - Tonic (e.g. "C").
+     * @returns - Scale.
+     */
+    getScale(tonic: string): Scale;
+    /**
+     * Test if this scale factory has scale for given tonic value.
+     * @param tonic - Tonic.
+     * @returns - True/false.
+     */
+    hasScale(tonic: string): boolean;
+}
+/**
+ * Get array of scale factories, has some title string between to category.
+ * @returns - Array of scale factories.
+ */
+declare function getScaleFactoryList(): ReadonlyArray<ScaleFactory | string>;
+/**
+ * Get scale factory for given scale type.
+ * @param scaleType - Scale type.
+ * @returns - Scale factory.
+ */
+declare function getScaleFactory(scaleType: ScaleType | `${ScaleType}`): ScaleFactory;
+/**
+ * Validate scale type.
+ * @param scaleType - Scale type of unknown value.
+ * @returns - Scale type if given argument was valid scale type, or throws.
+ */
+declare function validateScaleType(scaleType: unknown): ScaleType;
+/**
+ * Get scale.
+ * @param tonic - Tonic (e.g. "C").
+ * @param scaleType - Scale type (e.g. "Major").
+ */
+declare function getScale(tonic: string, scaleType: ScaleType | `${ScaleType}`): Scale;
+/**
+ * Get scale.
+ * @param scale - Scale name (e.g. "C Major").
+ */
+declare function getScale(scale: string): Scale;
+/**
+ * Get default scale ("C Major").
+ * @returns - Default scale.
+ */
+declare function getDefaultScale(): Scale;
+
+export { type Degree as D, type IntervalDirection as I, ScaleType as S, type IntervalQuality as a, Interval as b, Scale as c, ScaleFactory as d, getScaleFactory as e, validateScaleType as f, getScaleFactoryList as g, getScale as h, getDefaultScale as i, validateIntervalQuality as v };