@musodojo/music-theory-data 31.0.0 → 31.1.0

package/README.md

@@ -1,166 +1,93 @@
 # Muso Dojo | Music Theory Data
 
-**Empower your music applications with a comprehensive, type-safe, and
-musician-friendly TypeScript/JavaScript library for notes, dyads, modes, scales,
-chord pitch collections, chord progression templates, and more.**
-
-## Community & Support
-
-Have a question, a suggestion, or want to report a bug? Get in touch!
-
-- **📢 Ask a Question or Share an Idea:** Use
-  [GitHub Discussions](https://github.com/conor-dowdall/music-theory-data/discussions).
-- **🐞 Report a Bug or Flaw in the Data:** Open a
-  [GitHub Issue](https://github.com/conor-dowdall/music-theory-data/issues).
-
-## Available Note Collections
-
-- ✅ Diatonic Modes
-- ✅ Pentatonic Variants
-- ✅ Major Variants
-- ✅ Minor Variants
-- ✅ Dominant Variants
-- ✅ Harmonic Minor Modes
-- ✅ Melodic Minor Modes
-- ✅ Diminished Variants
-- ✅ Augmented Variants
-- ✅ Other Note Collections, including notes and dyads
-
-## Available Chord Progressions
-
-- ✅ 4-bar foundational loops
-- ✅ 8-bar loops
-- ✅ 12-bar blues
-
-## Features
-
-- **Fully Typed:** Written in TypeScript with comprehensive type definitions for
-  a great developer experience.
-- **Deno First, NPM Ready:** A modern Deno module that is also published to npm
-  for use in Node.js projects.
-
-### Rich Data Structures
-
-Access detailed information for notes, dyads, scales, modes, chord pitch
-collections, chord progression templates, and more, including intervals, integer
-notations, and common names.
-
-```ts
-// src/data/note-collections/diatonic-modes.ts
-// @ts-ignore
-const ionian: ModalScaleCollection = {
-  category: "scale",
-  rotation: 0,
-  rotatedScale: "ionian",
-  mostSimilarScale: "ionian",
-  primaryName: "Major",
-  names: ["Major", "Ionian", "Major Scale", "Ionian Mode", "Diatonic Major"],
-  intervals: ["1", "2", "3", "4", "5", "6", "7", "8"],
-  integers: [0, 2, 4, 5, 7, 9, 11],
-  type: [
-    "major",
-    "ionian",
-    "mode",
-    "scale",
-    "church mode",
-    "diatonic mode",
-    "heptatonic",
-    "first diatonic mode",
-    "do mode",
-  ],
-  characteristics: [
-    "bright",
-    "happy",
-    "stable",
-    "uplifting",
-    "consonant",
-    "western",
-    "foundational",
-    "simple",
-    "pop music",
-    "major tonality",
-    "commonly used western scale",
-  ],
-  pattern: ["whole", "whole", "half", "whole", "whole", "whole", "half"],
-  patternShort: ["W", "W", "H", "W", "W", "W", "H"],
-} as const;
-```
-
-### Practical Utility Functions
-
-Helpers for common tasks like generating note names from a root note and a set
-of intervals. For the full implementation details, refer to the source file.
-
-```ts
-export function getNoteNamesFromRootAndIntervals(
-  // @ts-ignore
-  rootNote: RootNote,
-  intervals: readonly Interval[],
-  options: TransformIntervalsOptions = {},
-): NoteName[] {
-  // This is a simplified representation for documentation purposes.
-  // The actual implementation is in src/utils/note-names.ts
-  return [];
-}
-```
+A type-safe TypeScript/JavaScript library of music theory data and helpers for
+music apps, education tools, practice tools, and creative coding projects.
+
+It includes typed datasets for notes, intervals, scales, modes, chord pitch
+collections, chord progressions, string instrument tunings, note colors, MIDI
+helpers, and naming utilities.
+
+## What's Included
+
+- **Note collections:** notes, dyads, scales, modes, arpeggios, and chord pitch
+  collections, grouped into families such as diatonic modes, pentatonic
+  variants, major/minor/dominant variants, harmonic minor modes, melodic minor
+  modes, diminished variants, and augmented variants.
+- **Chord progressions:** 4-bar foundational loops, 8-bar loops, and 12-bar
+  blues progressions with roman symbols, scale degrees, qualities, and bar
+  durations.
+- **Labels and theory primitives:** note names, root notes, intervals, chromatic
+  indexes, roman numerals, chord qualities, and conversion helpers.
+- **Application helpers:** note-name generation, interval transforms, chord
+  progression resolution, chord spelling, MIDI helpers, note colors, contrast
+  helpers, and string instrument tunings.
+- **TypeScript-first API:** exported data, utility functions, and types are
+  designed to work well with autocomplete and compile-time checking.
+
+For exhaustive data, types, and function signatures, use the
+[JSR API documentation](https://jsr.io/@musodojo/music-theory-data/doc). The
+`tests/` directory also contains practical examples of supported behavior.
+
+## Package Registries
+
+- [JSR package](https://jsr.io/@musodojo/music-theory-data)
+- [npm package](https://www.npmjs.com/package/@musodojo/music-theory-data)
 
 ## Installation
 
 ### Deno / JSR
 
-Install the package from the JSR registry:
-
 ```bash
 deno add jsr:@musodojo/music-theory-data
 ```
 
-Then import it into your project:
-
 ```ts
-import * as music_theory_data from "@musodojo/music-theory-data";
+import * as musicTheoryData from "jsr:@musodojo/music-theory-data";
 ```
 
 ### Node.js / npm
 
-Install the package from the npm registry:
-
 ```bash
 npm install @musodojo/music-theory-data
 ```
 
-Then import it into your project:
-
 ```ts
-import * as music_theory_data from "@musodojo/music-theory-data";
+import * as musicTheoryData from "@musodojo/music-theory-data";
 ```
 
-## Usage Examples
+## Usage
 
-Note: the `tests/` directory contains many useful examples.
-
-The code below shows how to access and print some of the data.
+### Get Note Names
 
 ```ts
-import * as music_theory_data from "jsr:@musodojo/music-theory-data";
+import * as musicTheoryData from "jsr:@musodojo/music-theory-data";
 
-// Get the notes of A Harmonic Minor
-const notes1 = music_theory_data.getNoteNamesForRootAndNoteCollectionKey(
+const aHarmonicMinor = musicTheoryData.getNoteNamesForRootAndNoteCollectionKey(
   "A",
   "harmonicMinor",
 );
-console.log(notes1);
+
+console.log(aHarmonicMinor);
 // ["A", "B", "C", "D", "E", "F", "G♯", "A"]
 
-// Automatically knows whether to use flats or sharps
-const notes2 = music_theory_data.getNoteNamesForRootAndNoteCollectionKey(
+const fMajor = musicTheoryData.getNoteNamesForRootAndNoteCollectionKey(
   "F",
   "ionian",
 );
-console.log(notes2);
-//  ["F", "G", "A", "B♭", "C", "D", "E", "F"];
 
-// Get the full data structure for the Ionian mode (Major Scale)
-const ionian = music_theory_data.noteCollections.ionian;
+console.log(fMajor);
+// ["F", "G", "A", "B♭", "C", "D", "E", "F"]
+```
+
+### Inspect A Note Collection
+
+```ts
+import {
+  groupedNoteCollections,
+  noteCollections,
+} from "jsr:@musodojo/music-theory-data";
+
+const ionian = noteCollections.ionian;
 
 console.log(ionian.primaryName);
 // "Major"
@@ -168,170 +95,40 @@ console.log(ionian.primaryName);
 console.log(ionian.intervals);
 // ["1", "2", "3", "4", "5", "6", "7", "8"]
 
-// Log an array of all available Note Collection Keys
-console.log(Object.keys(music_theory_data.noteCollections));
-// ["ionian", "dorian", "phrygian", ...]
-
-// Log an array of all available Grouped Note Collections Keys
-console.log(Object.keys(music_theory_data.groupedNoteCollections));
+console.log(Object.keys(groupedNoteCollections));
 // ["diatonicModes", "pentatonicVariants", ...]
+```
+
+Each collection includes structured fields such as names, intervals, integer
+notation, type tags, and musical characteristics. See the generated docs or
+source files for complete schemas.
 
-// Get a chord progression
-const oneSixFourFive = music_theory_data.chordProgressions.oneSixFourFive;
+### Resolve Chord Progressions
+
+```ts
+import {
+  chordProgressions,
+  getChordProgressionChordNames,
+  getChordProgressionRomanSymbols,
+  getChordProgressionTotalDurationInBars,
+} from "jsr:@musodojo/music-theory-data";
+
+const oneSixFourFive = chordProgressions.oneSixFourFive;
 
 console.log(oneSixFourFive.chords.map((chord) => chord.romanSymbol));
 // ["I", "vi", "IV", "V"]
 
-console.log(oneSixFourFive.chords);
-// [
-//   { romanSymbol: "I", degree: "1", quality: "M", durationInBars: 1 },
-//   { romanSymbol: "vi", degree: "6", quality: "m", durationInBars: 1 },
-//   { romanSymbol: "IV", degree: "4", quality: "M", durationInBars: 1 },
-//   { romanSymbol: "V", degree: "5", quality: "M", durationInBars: 1 },
-// ]
-
-console.log(
-  music_theory_data.getChordProgressionRomanSymbols("oneSixFourFive"),
-);
+console.log(getChordProgressionRomanSymbols("oneSixFourFive"));
 // ["I", "vi", "IV", "V"]
 
-console.log(
-  music_theory_data.getChordProgressionChordNames(
-    "C",
-    "oneSixFourFive",
-  ),
-);
+console.log(getChordProgressionChordNames("C", "oneSixFourFive"));
 // ["CM", "Am", "FM", "GM"]
 
-console.log(
-  music_theory_data.getChordProgressionUniqueChordNames(
-    "C",
-    "oneFourOneFiveSplitReturn",
-  ),
-);
-// ["CM", "FM", "GM"]
-
-// Chord-change references return one item each time the chord changes in
-// progression.chords. Durations are not expanded here.
-console.log(
-  music_theory_data.getChordProgressionChordChangeReferences(
-    "C",
-    "oneOneFiveFive",
-  ),
-);
-// [
-//   { rootNote: "C", chordName: "CM", noteCollectionKey: "major" },
-//   { rootNote: "G", chordName: "GM", noteCollectionKey: "major" },
-// ]
-
-// Unique chord references return each distinct chord once, preserving the
-// first-seen order from the chord-change list.
-console.log(
-  music_theory_data.getChordProgressionUniqueChordReferences(
-    "C",
-    "oneFourOneFiveSplitReturn",
-  ),
-);
-// [
-//   { rootNote: "C", chordName: "CM", noteCollectionKey: "major" },
-//   { rootNote: "F", chordName: "FM", noteCollectionKey: "major" },
-//   { rootNote: "G", chordName: "GM", noteCollectionKey: "major" },
-// ]
-
-// Chord references by bar return the song/practice order grouped by bar. A
-// 2-bar chord appears in two bars, and split bars contain multiple references.
-console.log(
-  music_theory_data.getChordProgressionChordReferencesByBar(
-    "C",
-    "oneOneFiveFive",
-  ),
-);
-// [
-//   [{ rootNote: "C", chordName: "CM", noteCollectionKey: "major" }],
-//   [{ rootNote: "C", chordName: "CM", noteCollectionKey: "major" }],
-//   [{ rootNote: "G", chordName: "GM", noteCollectionKey: "major" }],
-//   [{ rootNote: "G", chordName: "GM", noteCollectionKey: "major" }],
-// ]
-
-console.log(
-  music_theory_data.getChordProgressionChordReferencesByBar(
-    "C",
-    "oneFourOneFiveSplitReturn",
-  )[6],
-);
-// [
-//   { rootNote: "C", chordName: "CM", noteCollectionKey: "major" },
-//   { rootNote: "G", chordName: "GM", noteCollectionKey: "major" },
-// ]
-
-// Song chord references flatten the bar-structured references into one ordered
-// list for apps that want one diagram/card per chord occurrence.
-console.log(
-  music_theory_data.getChordProgressionSongChordReferences(
-    "C",
-    "oneOneFiveFive",
-  ).map((reference) => reference.chordName),
-);
-// ["CM", "CM", "GM", "GM"]
-
-// In Muso Dojo, "Each Chord Once" should import
-// getChordProgressionUniqueChordReferences. "Full Song Order" should import
-// getChordProgressionSongChordReferences, or flatten
-// getChordProgressionChordReferencesByBar locally when bar grouping is needed.
-
-console.log(
-  music_theory_data.getChordProgressionTotalDurationInBars("twelveBarBlues"),
-);
-// 12
-
-console.log(
-  music_theory_data.getChordProgressionChordReferencesByBar(
-    "C",
-    "twelveBarBlues",
-  ).length,
-);
+console.log(getChordProgressionTotalDurationInBars("twelveBarBlues"));
 // 12
-
-console.log(
-  music_theory_data.getChordProgressionUniqueChordReferences(
-    "C",
-    "twelveBarBlues",
-  ),
-);
-// [
-//   { rootNote: "C", chordName: "C7", noteCollectionKey: "dominant7" },
-//   { rootNote: "F", chordName: "F7", noteCollectionKey: "dominant7" },
-//   { rootNote: "G", chordName: "G7", noteCollectionKey: "dominant7" },
-// ]
-
-console.log(music_theory_data.chordProgressionBarGroups);
-// [
-//   { totalBars: 4, progressionKeys: ["oneOneFiveFive", ...] },
-//   { totalBars: 8, progressionKeys: ["oneFourOneFiveSplitReturn"] },
-//   { totalBars: 12, progressionKeys: ["twelveBarBlues", "twelveBarBluesQuickChange"] },
-// ]
-
-console.log(music_theory_data.getChordProgressionKeysForTotalBars(12));
-// ["twelveBarBlues", "twelveBarBluesQuickChange"]
 ```
 
-## Note Colors And Chromatic Indexes
-
-Note color collections use 12 chromatic slots. In absolute mode, each index is a
-pitch class where index `0` is C and index `7` is G. In relative mode, each
-index is measured from a musical root where index `0` is the root and index `7`
-is the fifth.
-
-`noteLabelCollections.noteNamesFlat` is the default label set for absolute note
-colors, and `noteLabelCollections.intervalsFlat` is the default label set for
-relative note colors. `ChromaticIndex` is the shared `0`-to-`11` pitch-class
-shape used by chromatic tuples, note labels, root-note integers, and filled
-chromatic interval helpers. `ChromaticMode` is the shared `"absolute"` or
-`"relative"` mode used by note colors and label collections.
-
-Chromatic indexes must be integers. Helpers such as `normalizeChromaticIndex`
-wrap negative or large semitone values into the `0`-to-`11` range, but reject
-fractional or non-finite values.
+### Use Note Colors And Chromatic Indexes
 
 ```ts
 import {
@@ -344,6 +141,7 @@ const absoluteIndex = getNoteColorIndex({
   midi: 67,
   mode: "absolute",
 });
+
 console.log(absoluteIndex);
 // 7, the pitch class G
 
@@ -352,6 +150,7 @@ const relativeIndex = getNoteColorIndex({
   mode: "relative",
   rootPitchClass: 2,
 });
+
 console.log(relativeIndex);
 // 7, A as the fifth above D
 
@@ -359,16 +158,17 @@ console.log(getNoteColorLabels(colorCollections.musoDojoRootAndFifth));
 // ["1", "♭2", "2", "♭3", "3", "4", "♭5", "5", "♭6", "6", "♭7", "7"]
 ```
 
-Color values may be hex strings or `null`. A `null` value means there is
-intentionally no semantic color for that pitch or degree; consuming apps should
-choose their own visual fallback through theme or UI settings.
-
-Regular note collection interval arrays remain variable length because chords,
-dyads, arpeggios, and scales have different natural sizes. Helpers that opt into
-`fillChromatic: true` return a fixed 12-slot chromatic tuple.
+Note color collections use 12 chromatic slots. Absolute mode treats index `0` as
+C; relative mode treats index `0` as the chosen musical root.
 
 ## API Documentation
 
-For a full list of all available data, types, and utility functions, please see
-the
+For the full list of available data, types, and utility functions, see the
 **[auto-generated API documentation on JSR](https://jsr.io/@musodojo/music-theory-data/doc)**.
+
+## Community & Support
+
+- Ask questions or share ideas in
+  [GitHub Discussions](https://github.com/conor-dowdall/music-theory-data/discussions).
+- Report bugs or data issues in
+  [GitHub Issues](https://github.com/conor-dowdall/music-theory-data/issues).

package/esm/src/data/chord-progressions/mod.d.ts

@@ -15,8 +15,11 @@ declare const _chordProgressions: {
     readonly twelveBarBlues: ChordProgression;
     readonly twelveBarBluesQuickChange: ChordProgression;
 };
+/** A key for one of the built-in chord progression templates. */
 export type ChordProgressionKey = keyof typeof _chordProgressions;
+/** Built-in chord progression templates keyed by progression id. */
 export declare const chordProgressions: Record<ChordProgressionKey, ChordProgression>;
+/** Built-in chord progression keys grouped by total duration in bars. */
 export declare const chordProgressionBarGroups: readonly ChordProgressionBarGroup<ChordProgressionKey>[];
 export {};
 //# sourceMappingURL=mod.d.ts.map

package/esm/src/data/chord-progressions/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../src/src/data/chord-progressions/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,wBAAwB,EAEzB,MAAM,gCAAgC,CAAC;AAqJxC,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;CAed,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAElE,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,mBAAmB,EAAE,gBAAgB,CACxD,CAAC;AAiBrB,eAAO,MAAM,yBAAyB,EAAE,SAAS,wBAAwB,CACvE,mBAAmB,CACpB,EAM0C,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../src/src/data/chord-progressions/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,wBAAwB,EAEzB,MAAM,gCAAgC,CAAC;AAqJxC,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;CAed,CAAC;AAEX,iEAAiE;AACjE,MAAM,MAAM,mBAAmB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAElE,oEAAoE;AACpE,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,mBAAmB,EAAE,gBAAgB,CACxD,CAAC;AAiBrB,yEAAyE;AACzE,eAAO,MAAM,yBAAyB,EAAE,SAAS,wBAAwB,CACvE,mBAAmB,CACpB,EAM0C,CAAC"}

package/esm/src/data/chord-progressions/mod.js

@@ -141,6 +141,7 @@ const _chordProgressions = {
     twelveBarBlues,
     twelveBarBluesQuickChange,
 };
+/** Built-in chord progression templates keyed by progression id. */
 export const chordProgressions = _chordProgressions;
 const chordProgressionsByTotalBars = Object.entries(chordProgressions)
     .reduce((groups, [key, progression]) => {
@@ -154,6 +155,7 @@ const chordProgressionsByTotalBars = Object.entries(chordProgressions)
     }
     return groups;
 }, new Map());
+/** Built-in chord progression keys grouped by total duration in bars. */
 export const chordProgressionBarGroups = Array.from(chordProgressionsByTotalBars, ([totalBars, progressionKeys]) => ({
     totalBars,
     progressionKeys,

package/esm/src/data/chords/mod.d.ts

@@ -3,15 +3,25 @@ declare const _triadChordQualities: readonly ["M", "m", "°", "+"];
 declare const _seventhChordQualities: readonly ["M7", "m7", "7", "ø7", "m7♭5", "°7", "m(M7)", "+M7", "M7♯5"];
 declare const _upperCaseRomanNumerals: readonly ["I", "II", "III", "IV", "V", "VI", "VII"];
 declare const _lowerCaseRomanNumerals: readonly ["i", "ii", "iii", "iv", "v", "vi", "vii"];
+/** A supported triad chord quality suffix. */
 export type Triad = (typeof _triadChordQualities)[number];
+/** A supported seventh-chord quality suffix. */
 export type SeventhChord = (typeof _seventhChordQualities)[number];
+/** Any supported chord quality suffix. */
 export type ChordQuality = Triad | SeventhChord;
+/** An uppercase roman numeral for scale degrees one through seven. */
 export type UpperCaseRomanNumeral = (typeof _upperCaseRomanNumerals)[number];
+/** A lowercase roman numeral for scale degrees one through seven. */
 export type LowerCaseRomanNumeral = (typeof _lowerCaseRomanNumerals)[number];
+/** Any supported roman numeral scale-degree symbol. */
 export type RomanNumeral = UpperCaseRomanNumeral | LowerCaseRomanNumeral;
+/** A roman-numeral triad symbol with an optional triad quality suffix. */
 export type RomanTriad = `${RomanNumeral}` | `${RomanNumeral}${Triad}`;
+/** A roman-numeral seventh-chord symbol with a seventh quality suffix. */
 export type RomanSeventhChord = `${RomanNumeral}${SeventhChord}`;
+/** The letter case used when rendering a roman numeral chord symbol. */
 export type RomanNumeralCase = "upper" | "lower";
+/** Rendering metadata for converting a chord quality into roman notation. */
 export interface ChordQualityRomanRendering {
     readonly numeralCase: RomanNumeralCase;
     readonly suffix: string;
@@ -22,6 +32,7 @@ export declare const triadChordQualities: readonly Triad[];
 export declare const seventhChordQualities: readonly SeventhChord[];
 /** The complete set of supported chord suffix qualities. */
 export declare const chordQualities: readonly ChordQuality[];
+/** Maps each supported chord quality to its matching note-collection key. */
 export type ChordQualityNoteCollectionKeyMap = Record<ChordQuality, NoteCollectionKey>;
 /** Note-collection keys for every supported chord quality. */
 export declare const chordQualityNoteCollectionKeys: ChordQualityNoteCollectionKeyMap;
@@ -43,6 +54,7 @@ export declare const melodicMinorSeventhChords: SeventhChord[];
 export declare const upperCaseRomanNumerals: readonly UpperCaseRomanNumeral[];
 /** An array mapping 7 index scale degrees to their corresponding lower-case Roman numerals. */
 export declare const lowerCaseRomanNumerals: readonly LowerCaseRomanNumeral[];
+/** Returns the note-collection key that describes the notes in a chord quality. */
 export declare function getChordQualityNoteCollectionKey(quality: ChordQuality): NoteCollectionKey;
 export {};
 //# sourceMappingURL=mod.d.ts.map

package/esm/src/data/chords/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../src/src/data/chords/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,QAAA,MAAM,oBAAoB,+BAAgC,CAAC;AAE3D,QAAA,MAAM,sBAAsB,wEAUlB,CAAC;AAEX,QAAA,MAAM,uBAAuB,qDAQnB,CAAC;AAEX,QAAA,MAAM,uBAAuB,qDAQnB,CAAC;AAEX,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1D,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AACnE,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,YAAY,CAAC;AAEhD,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAC7E,MAAM,MAAM,YAAY,GAAG,qBAAqB,GAAG,qBAAqB,CAAC;AAEzE,MAAM,MAAM,UAAU,GAAG,GAAG,YAAY,EAAE,GAAG,GAAG,YAAY,GAAG,KAAK,EAAE,CAAC;AACvE,MAAM,MAAM,iBAAiB,GAAG,GAAG,YAAY,GAAG,YAAY,EAAE,CAAC;AACjE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAkBD,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,EAAE,SAAS,KAAK,EAAyB,CAAC;AAE1E,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,EAAE,SAAS,YAAY,EACjC,CAAC;AAEzB,4DAA4D;AAC5D,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAGjD,CAAC;AAEF,MAAM,MAAM,gCAAgC,GAAG,MAAM,CACnD,YAAY,EACZ,iBAAiB,CAClB,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,EAAE,gCACZ,CAAC;AAElC,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,EAAE,WAAW,CACnD,YAAY,EACZ,0BAA0B,CAe1B,CAAC;AAEH,+FAA+F;AAC/F,eAAO,MAAM,cAAc,EAAE,KAAK,EAQxB,CAAC;AAEX,uGAAuG;AACvG,eAAO,MAAM,qBAAqB,EAAE,YAAY,EAQtC,CAAC;AAEX,+FAA+F;AAC/F,eAAO,MAAM,mBAAmB,EAAE,KAAK,EAQ7B,CAAC;AAEX,uGAAuG;AACvG,eAAO,MAAM,0BAA0B,EAAE,YAAY,EAQ3C,CAAC;AAEX,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,EAAE,KAAK,EAQ5B,CAAC;AAEX,sGAAsG;AACtG,eAAO,MAAM,yBAAyB,EAAE,YAAY,EAQ1C,CAAC;AAEX,+FAA+F;AAC/F,eAAO,MAAM,sBAAsB,EAAE,SAAS,qBAAqB,EAC1C,CAAC;AAE1B,+FAA+F;AAC/F,eAAO,MAAM,sBAAsB,EAAE,SAAS,qBAAqB,EAC1C,CAAC;AAE1B,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,YAAY,GACpB,iBAAiB,CAEnB"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../src/src/data/chords/mod.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,QAAA,MAAM,oBAAoB,+BAAgC,CAAC;AAE3D,QAAA,MAAM,sBAAsB,wEAUlB,CAAC;AAEX,QAAA,MAAM,uBAAuB,qDAQnB,CAAC;AAEX,QAAA,MAAM,uBAAuB,qDAQnB,CAAC;AAEX,8CAA8C;AAC9C,MAAM,MAAM,KAAK,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1D,gDAAgD;AAChD,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,0CAA0C;AAC1C,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,YAAY,CAAC;AAEhD,sEAAsE;AACtE,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,qEAAqE;AACrE,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,uDAAuD;AACvD,MAAM,MAAM,YAAY,GAAG,qBAAqB,GAAG,qBAAqB,CAAC;AAEzE,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAAG,GAAG,YAAY,EAAE,GAAG,GAAG,YAAY,GAAG,KAAK,EAAE,CAAC;AAEvE,0EAA0E;AAC1E,MAAM,MAAM,iBAAiB,GAAG,GAAG,YAAY,GAAG,YAAY,EAAE,CAAC;AAEjE,wEAAwE;AACxE,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,OAAO,CAAC;AAEjD,6EAA6E;AAC7E,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAkBD,2DAA2D;AAC3D,eAAO,MAAM,mBAAmB,EAAE,SAAS,KAAK,EAAyB,CAAC;AAE1E,6DAA6D;AAC7D,eAAO,MAAM,qBAAqB,EAAE,SAAS,YAAY,EACjC,CAAC;AAEzB,4DAA4D;AAC5D,eAAO,MAAM,cAAc,EAAE,SAAS,YAAY,EAGjD,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,gCAAgC,GAAG,MAAM,CACnD,YAAY,EACZ,iBAAiB,CAClB,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,8BAA8B,EAAE,gCACZ,CAAC;AAElC,yEAAyE;AACzE,eAAO,MAAM,2BAA2B,EAAE,WAAW,CACnD,YAAY,EACZ,0BAA0B,CAe1B,CAAC;AAEH,+FAA+F;AAC/F,eAAO,MAAM,cAAc,EAAE,KAAK,EAQxB,CAAC;AAEX,uGAAuG;AACvG,eAAO,MAAM,qBAAqB,EAAE,YAAY,EAQtC,CAAC;AAEX,+FAA+F;AAC/F,eAAO,MAAM,mBAAmB,EAAE,KAAK,EAQ7B,CAAC;AAEX,uGAAuG;AACvG,eAAO,MAAM,0BAA0B,EAAE,YAAY,EAQ3C,CAAC;AAEX,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,EAAE,KAAK,EAQ5B,CAAC;AAEX,sGAAsG;AACtG,eAAO,MAAM,yBAAyB,EAAE,YAAY,EAQ1C,CAAC;AAEX,+FAA+F;AAC/F,eAAO,MAAM,sBAAsB,EAAE,SAAS,qBAAqB,EAC1C,CAAC;AAE1B,+FAA+F;AAC/F,eAAO,MAAM,sBAAsB,EAAE,SAAS,qBAAqB,EAC1C,CAAC;AAE1B,mFAAmF;AACnF,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,YAAY,GACpB,iBAAiB,CAEnB"}

package/esm/src/data/chords/mod.js

@@ -134,6 +134,7 @@ export const melodicMinorSeventhChords = [
 export const upperCaseRomanNumerals = _upperCaseRomanNumerals;
 /** An array mapping 7 index scale degrees to their corresponding lower-case Roman numerals. */
 export const lowerCaseRomanNumerals = _lowerCaseRomanNumerals;
+/** Returns the note-collection key that describes the notes in a chord quality. */
 export function getChordQualityNoteCollectionKey(quality) {
     return chordQualityNoteCollectionKeys[quality];
 }

package/esm/src/data/chromatic.d.ts

@@ -1,3 +1,4 @@
+/** The number of pitch classes in 12-tone equal-tempered chromatic space. */
 export declare const CHROMATIC_NOTE_COUNT: 12;
 /** A zero-indexed chromatic pitch-class or relative degree slot. */
 export type ChromaticIndex = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11;
@@ -18,6 +19,7 @@ export type ChromaticTuple<T> = readonly [
     T,
     T
 ];
+/** The ordered set of all valid chromatic indexes from C/root through B/7. */
 export declare const CHROMATIC_INDEXES: ChromaticTuple<ChromaticIndex>;
 /** A variable-length set of chromatic indexes, such as the pitch classes in a scale or dyad. */
 export type ChromaticIndexSet = readonly ChromaticIndex[];

package/esm/src/data/chromatic.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chromatic.d.ts","sourceRoot":"","sources":["../../../src/src/data/chromatic.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,oBAAoB,EAAG,EAAW,CAAC;AAEhD,oEAAoE;AACpE,MAAM,MAAM,cAAc,GACtB,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,EAAE,GACF,EAAE,CAAC;AAEP,mDAAmD;AACnD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC;AAEpD,iFAAiF;AACjF,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,SAAS;IACvC,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;CACF,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,cAAc,CAanD,CAAC;AAEX,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,SAAS,cAAc,EAAE,CAAC"}
+{"version":3,"file":"chromatic.d.ts","sourceRoot":"","sources":["../../../src/src/data/chromatic.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,eAAO,MAAM,oBAAoB,EAAG,EAAW,CAAC;AAEhD,oEAAoE;AACpE,MAAM,MAAM,cAAc,GACtB,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,CAAC,GACD,EAAE,GACF,EAAE,CAAC;AAEP,mDAAmD;AACnD,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,UAAU,CAAC;AAEpD,iFAAiF;AACjF,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,SAAS;IACvC,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;IACD,CAAC;CACF,CAAC;AAEF,8EAA8E;AAC9E,eAAO,MAAM,iBAAiB,EAAE,cAAc,CAAC,cAAc,CAanD,CAAC;AAEX,gGAAgG;AAChG,MAAM,MAAM,iBAAiB,GAAG,SAAS,cAAc,EAAE,CAAC"}

package/esm/src/data/chromatic.js

@@ -1,4 +1,6 @@
+/** The number of pitch classes in 12-tone equal-tempered chromatic space. */
 export const CHROMATIC_NOTE_COUNT = 12;
+/** The ordered set of all valid chromatic indexes from C/root through B/7. */
 export const CHROMATIC_INDEXES = [
     0,
     1,

package/esm/src/data/colors/mod.d.ts

@@ -1,8 +1,12 @@
 import { type NoteLabelCollectionKey, type NoteLabelGroup } from "../labels/note-label-collections.js";
 import type { ChromaticMode, ChromaticTuple } from "../chromatic.js";
+/** Whether a note color collection uses absolute pitch classes or root-relative degrees. */
 export type NoteColorMode = ChromaticMode;
+/** A single note color value, or `null` when no semantic color is assigned. */
 export type NoteColorValue = string | null;
+/** A fixed 12-slot color tuple for absolute pitch classes or relative degrees. */
 export type NoteColorTuple = ChromaticTuple<NoteColorValue>;
+/** Metadata and color values for a named 12-slot note color collection. */
 export interface NoteColorCollection {
     readonly name: string;
     readonly shortName?: string;
@@ -11,16 +15,24 @@ export interface NoteColorCollection {
     readonly labelCollectionKey?: NoteLabelCollectionKey;
     readonly colors: NoteColorTuple;
 }
+/** Backwards-compatible alias for a single note color value. */
 export type Color = NoteColorValue;
+/** Backwards-compatible alias for a 12-slot note color tuple. */
 export type ColorGroup = NoteColorTuple;
+/** Backwards-compatible alias for a note color collection. */
 export type ColorCollection = NoteColorCollection;
+/** Default label collection keys for absolute and relative note color modes. */
 export type DefaultNoteColorLabelCollectionKeys = Readonly<Record<NoteColorMode, NoteLabelCollectionKey>> & Readonly<{
     absolute: "noteNamesFlat";
     relative: "intervalsFlat";
 }>;
+/** The default note label collection key used for each note color mode. */
 export declare const defaultNoteColorLabelCollectionKeys: DefaultNoteColorLabelCollectionKeys;
+/** Returns the default label collection key for an absolute or relative color mode. */
 export declare function getDefaultNoteColorLabelCollectionKey(mode: NoteColorMode): NoteLabelCollectionKey;
+/** Returns the explicit or default label collection key for a note color collection. */
 export declare function getNoteColorLabelCollectionKey(collection: NoteColorCollection): NoteLabelCollectionKey;
+/** Returns the 12 labels that should be displayed with a note color collection. */
 export declare function getNoteColorLabels(collection: NoteColorCollection): NoteLabelGroup;
 declare const _colorCollections: {
     readonly musoDojo: {
@@ -56,7 +68,9 @@ declare const _colorCollections: {
         readonly colors: readonly ["#E21C48", "#F26622", "#F99D1C", "#FFCC33", "#FFF32B", "#BCD85F", "#62BC47", "#009C95", "#0071BB", "#5E50A1", "#8D5BA6", "#CF3E96"];
     };
 };
+/** A key for one of the built-in note color collections. */
 export type ColorCollectionKey = keyof typeof _colorCollections;
+/** Built-in absolute and relative note color palettes. */
 export declare const colorCollections: Record<ColorCollectionKey, NoteColorCollection>;
 export {};
 //# sourceMappingURL=mod.d.ts.map

package/esm/src/data/colors/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../src/src/data/colors/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,sBAAsB,EAE3B,KAAK,cAAc,EACpB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAErE,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC;AAC1C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,IAAI,CAAC;AAC3C,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;AAE5D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,sBAAsB,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC;AAED,MAAM,MAAM,KAAK,GAAG,cAAc,CAAC;AACnC,MAAM,MAAM,UAAU,GAAG,cAAc,CAAC;AACxC,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,MAAM,MAAM,mCAAmC,GAC3C,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,sBAAsB,CAAC,CAAC,GACvD,QAAQ,CAAC;IACT,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,eAAe,CAAC;CAC3B,CAAC,CAAC;AAEL,eAAO,MAAM,mCAAmC,EAC9C,mCAGC,CAAC;AAEJ,wBAAgB,qCAAqC,CACnD,IAAI,EAAE,aAAa,GAClB,sBAAsB,CAExB;AAED,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,mBAAmB,GAC9B,sBAAsB,CAMxB;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,mBAAmB,GAC9B,cAAc,CAGhB;AAED,QAAA,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuFb,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAEhE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,kBAAkB,EAClB,mBAAmB,CACA,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../../../src/src/data/colors/mod.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,sBAAsB,EAE3B,KAAK,cAAc,EACpB,MAAM,qCAAqC,CAAC;AAC7C,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAErE,4FAA4F;AAC5F,MAAM,MAAM,aAAa,GAAG,aAAa,CAAC;AAE1C,+EAA+E;AAC/E,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,IAAI,CAAC;AAE3C,kFAAkF;AAClF,MAAM,MAAM,cAAc,GAAG,cAAc,CAAC,cAAc,CAAC,CAAC;AAE5D,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,sBAAsB,CAAC;IACrD,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;CACjC;AAED,gEAAgE;AAChE,MAAM,MAAM,KAAK,GAAG,cAAc,CAAC;AAEnC,iEAAiE;AACjE,MAAM,MAAM,UAAU,GAAG,cAAc,CAAC;AAExC,8DAA8D;AAC9D,MAAM,MAAM,eAAe,GAAG,mBAAmB,CAAC;AAElD,gFAAgF;AAChF,MAAM,MAAM,mCAAmC,GAC3C,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,sBAAsB,CAAC,CAAC,GACvD,QAAQ,CAAC;IACT,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,eAAe,CAAC;CAC3B,CAAC,CAAC;AAEL,2EAA2E;AAC3E,eAAO,MAAM,mCAAmC,EAC9C,mCAGC,CAAC;AAEJ,uFAAuF;AACvF,wBAAgB,qCAAqC,CACnD,IAAI,EAAE,aAAa,GAClB,sBAAsB,CAExB;AAED,wFAAwF;AACxF,wBAAgB,8BAA8B,CAC5C,UAAU,EAAE,mBAAmB,GAC9B,sBAAsB,CAMxB;AAED,mFAAmF;AACnF,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,mBAAmB,GAC9B,cAAc,CAGhB;AAED,QAAA,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuFb,CAAC;AAEX,4DAA4D;AAC5D,MAAM,MAAM,kBAAkB,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAEhE,0DAA0D;AAC1D,eAAO,MAAM,gBAAgB,EAAE,MAAM,CACnC,kBAAkB,EAClB,mBAAmB,CACA,CAAC"}