@libraz/libcantus 0.9.3 → 0.9.5

package/dist/{function-DVH4Eusr.d.ts → function-CxixTB02.d.cts}

@@ -1,5 +1,5 @@
-import { K as KeyScale } from './types-MGP29r3t.js';
-import { C as Chord } from './index-Bt4tOUD9.js';
+import { K as KeyScale } from './types-BN6_Q9Kl.cjs';
+import { C as Chord } from './index-oTQbYYIs.cjs';
 
 /**
  * Borrowed chords (modal interchange) and the Neapolitan.
@@ -14,7 +14,7 @@ import { C as Chord } from './index-Bt4tOUD9.js';
  *
  * @category Functional Harmony
  */
-type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
+type BorrowedSource = 'parallelMinor' | 'parallelMajor' | 'neapolitan' | null;
 /**
  * Whether a chord is borrowed from the parallel mode (modal interchange).
  *
@@ -22,7 +22,7 @@ type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
  * {@link parallelKey} — e.g. iv, bVI, or bVII in a major key, or the Picardy
  * tonic and major IV in a minor key. Two non-diatonic families are excluded:
  * chords diatonic to neither mode (they are chromatic, not borrowed), and, in
- * a minor key, chords explained by the harmonic minor scale (the major
+ * a minor key, chords explained by the altered minor forms (the major
  * dominant and raised-leading-tone chords), which are in-key alterations
  * rather than interchange even though they happen to fit the parallel major.
  *
@@ -37,7 +37,7 @@ declare function isBorrowedChord(chord: Chord, key: KeyScale): boolean;
  *
  * The Neapolitan (major triad on b2) is recognized first, since it sits
  * outside both parallel modes; parallel-mode borrowing follows the
- * {@link isBorrowedChord} rules. Diatonic chords, harmonic-minor alterations,
+ * {@link isBorrowedChord} rules. Diatonic chords and altered-minor chords,
  * and unrecognized chromatic chords all yield null.
  *
  * @param chord The chord to classify.
@@ -85,6 +85,96 @@ type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
  */
 declare function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence;
 
+/**
+ * Roman-numeral parsing and formatting.
+ *
+ * The {@link ROMAN_STYLE} table is the single source of truth for both
+ * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
+ * inverses by construction.
+ */
+
+/**
+ * Build the chord denoted by a Roman numeral in a key.
+ *
+ * Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`
+ * suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions
+ * (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash
+ * (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree
+ * whose root becomes a local major tonic for the applied chord. Inverted chords
+ * carry a `bassPc`.
+ *
+ * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
+ * `m7b5`), since no half-diminished triad exists. Extension and added-tone
+ * suffixes are the canonical case-sensitive forms emitted by
+ * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
+ * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
+ * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
+ * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
+ * A figure string that is neither a recognized inversion nor a supported
+ * quality suffix throws rather than silently degrading to a triad.
+ *
+ * @param text The Roman numeral.
+ * @param key The prevailing key.
+ * @returns The chord.
+ * @example
+ * ```ts
+ * import { romanToChord, majorKey } from '@libraz/libcantus';
+ * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
+ * ```
+ * @category Functional Harmony
+ */
+declare function romanToChord(text: string, key: KeyScale): Chord;
+/**
+ * Options for {@link chordToRoman}.
+ *
+ * @category Functional Harmony
+ */
+type ChordToRomanOptions = {
+    /**
+     * Render a tonicizing chord as an applied numeral (`V7/V`, `viio7/ii`)
+     * instead of naming its root against the home key (`II7`, `#ivo7`).
+     *
+     * Off by default: naming the root is always a correct spelling, whereas
+     * whether a chromatic dominant is genuinely applied is a reading only the
+     * caller can make. Turning it on makes {@link chordToRoman} the exact inverse
+     * of {@link romanToChord} for the chords {@link secondaryDominant} builds.
+     */
+    applied?: boolean;
+};
+/**
+ * Render a chord as a Roman numeral relative to a key.
+ *
+ * Diatonic roots take their scale-degree numeral directly, so numerals are
+ * correct in both major and minor keys (and any custom scale). The quality
+ * selects the case and suffix; chromatic roots receive a flat/sharp spelling by
+ * convention. A key that is not heptatonic has no numeral of its own for every
+ * degree, so its roots are named against its parallel major.
+ *
+ * When the chord carries a `bassPc` on a chord tone, a figured-bass inversion
+ * (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true seventh
+ * chords; added-tone and extended qualities have no lossless figure and render
+ * in root position instead (the bass is dropped, pitch classes are preserved).
+ *
+ * A `bassPc` that is *not* a chord tone — a pedal or passing bass such as
+ * `C/D` — is likewise dropped, and the numeral names the upper chord alone.
+ * Roman-numeral notation spends its slash on applied chords (`V7/V`), so there
+ * is no unambiguous way to write such a bass; a caller that must keep it should
+ * read `chord.bassPc` alongside the numeral.
+ *
+ * @param chord The chord to name.
+ * @param key The prevailing key.
+ * @param opts `applied` renders tonicizing chords as `V7/V`-style numerals.
+ * @returns The Roman numeral string.
+ * @example
+ * ```ts
+ * import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';
+ * chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)
+ * chordToRoman(makeChord(2, 'dom7'), majorKey(0), { applied: true }); // => 'V7/V'
+ * ```
+ * @category Functional Harmony
+ */
+declare function chordToRoman(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): string;
+
 /**
  * Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key
  * mirroring, and full chord analysis.
@@ -107,13 +197,33 @@ type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
  */
 declare function isMinorKey(key: KeyScale): boolean;
 /**
- * The harmonic function of a chord in a key, from its root's offset above the
- * tonic. The mapping follows common-practice major-key function and is a useful
- * approximation in minor and for borrowed chords.
+ * The harmonic function of a chord in a key.
+ *
+ * The root's offset above the tonic gives the baseline mapping, which follows
+ * common-practice major-key function and is a useful approximation in minor and
+ * for borrowed chords. Chord quality then refines it where the sonority settles
+ * an ambiguity the root offset cannot:
+ *
+ * - A chord that *sounds* like a dominant — a major third with a minor seventh,
+ *   or a diminished-family chord — and is not diatonic to the key has dominant
+ *   function when its root resolves down a fifth or by a semitone onto a
+ *   diatonic degree. This is what makes an applied dominant (`A7` in C, which
+ *   tonicizes ii) and its tritone substitute (`Db7`) read as dominant rather
+ *   than inheriting the function of the degree they happen to sit on.
+ * - The Neapolitan is subdominant.
+ * - A major triad on bVI or bVII of a major key is subdominant — the borrowed
+ *   pop cadence chord, distinct from the bVII7 above, which has a seventh and
+ *   is a dominant sonority.
  *
  * @param chord The chord.
  * @param key The prevailing key.
  * @returns The harmonic function.
+ * @example
+ * ```ts
+ * import { functionOf, makeChord, majorKey } from '@libraz/libcantus';
+ * functionOf(makeChord(9, 'dom7'), majorKey(0)); // 'dominant' — A7 tonicizes ii
+ * functionOf(makeChord(10, 'maj'), majorKey(0)); // 'subdominant' — borrowed bVII
+ * ```
  * @category Functional Harmony
  */
 declare function functionOf(chord: Chord, key: KeyScale): HarmonicFunction;
@@ -164,6 +274,7 @@ declare function parallelKey(key: KeyScale): KeyScale;
  *
  * @param chord The chord to analyze.
  * @param key The prevailing key.
+ * @param opts Options used when rendering the Roman numeral.
  * @returns The chord analysis.
  * @example
  * ```ts
@@ -173,15 +284,16 @@ declare function parallelKey(key: KeyScale): KeyScale;
  * ```
  * @category Functional Harmony
  */
-declare function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis;
+declare function analyzeChord(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): ChordAnalysis;
 /**
  * The secondary dominant (V7) that tonicizes a scale degree.
  *
  * @param targetDegree 0-based scale degree to tonicize.
  * @param key The prevailing key.
  * @returns A dominant-seventh chord a fifth above the target's root.
+ * @throws If `targetDegree` is not an integer naming a degree in `key`.
  * @category Functional Harmony
  */
 declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord;
 
-export { type BorrowedSource as B, type Cadence as C, type HarmonicFunction as H, type ChordAnalysis as a, analyzeChord as b, borrowedSource as c, detectCadence as d, isDiatonic as e, functionOf as f, isMinorKey as g, isBorrowedChord as i, parallelKey as p, secondaryDominant as s };
+export { type BorrowedSource as B, type Cadence as C, type HarmonicFunction as H, type ChordAnalysis as a, type ChordToRomanOptions as b, analyzeChord as c, borrowedSource as d, chordToRoman as e, detectCadence as f, functionOf as g, isDiatonic as h, isBorrowedChord as i, isMinorKey as j, parallelKey as p, romanToChord as r, secondaryDominant as s };

package/dist/{function-DYt4iKsn.d.cts → function-DTCt675z.d.ts}

@@ -1,5 +1,5 @@
-import { K as KeyScale } from './types-MGP29r3t.cjs';
-import { C as Chord } from './index-BNlGP86A.cjs';
+import { K as KeyScale } from './types-BN6_Q9Kl.js';
+import { C as Chord } from './index-COw1Ky9g.js';
 
 /**
  * Borrowed chords (modal interchange) and the Neapolitan.
@@ -14,7 +14,7 @@ import { C as Chord } from './index-BNlGP86A.cjs';
  *
  * @category Functional Harmony
  */
-type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
+type BorrowedSource = 'parallelMinor' | 'parallelMajor' | 'neapolitan' | null;
 /**
  * Whether a chord is borrowed from the parallel mode (modal interchange).
  *
@@ -22,7 +22,7 @@ type BorrowedSource = 'parallel-minor' | 'parallel-major' | 'neapolitan' | null;
  * {@link parallelKey} — e.g. iv, bVI, or bVII in a major key, or the Picardy
  * tonic and major IV in a minor key. Two non-diatonic families are excluded:
  * chords diatonic to neither mode (they are chromatic, not borrowed), and, in
- * a minor key, chords explained by the harmonic minor scale (the major
+ * a minor key, chords explained by the altered minor forms (the major
  * dominant and raised-leading-tone chords), which are in-key alterations
  * rather than interchange even though they happen to fit the parallel major.
  *
@@ -37,7 +37,7 @@ declare function isBorrowedChord(chord: Chord, key: KeyScale): boolean;
  *
  * The Neapolitan (major triad on b2) is recognized first, since it sits
  * outside both parallel modes; parallel-mode borrowing follows the
- * {@link isBorrowedChord} rules. Diatonic chords, harmonic-minor alterations,
+ * {@link isBorrowedChord} rules. Diatonic chords and altered-minor chords,
  * and unrecognized chromatic chords all yield null.
  *
  * @param chord The chord to classify.
@@ -85,6 +85,96 @@ type Cadence = 'authentic' | 'plagal' | 'half' | 'deceptive' | null;
  */
 declare function detectCadence(from: Chord, to: Chord, key: KeyScale): Cadence;
 
+/**
+ * Roman-numeral parsing and formatting.
+ *
+ * The {@link ROMAN_STYLE} table is the single source of truth for both
+ * directions, so {@link chordToRoman} and {@link romanToChord} stay mutual
+ * inverses by construction.
+ */
+
+/**
+ * Build the chord denoted by a Roman numeral in a key.
+ *
+ * Supports accidentals (`bVII`, `#iv`), case-based triad quality, the `o`/`ø`/`+`
+ * suffixes, sevenths (`V7`, `viio7`, `Imaj7`), figured-bass inversions
+ * (`V6`, `V64`, `V65`, `V43`, `V42`), and applied/secondary chords via a slash
+ * (`V7/V`, `viio/ii`). The target after the slash is read as a scale degree
+ * whose root becomes a local major tonic for the applied chord. Inverted chords
+ * carry a `bassPc`.
+ *
+ * The `ø` glyph always denotes the half-diminished seventh (`iiø` == `iiø7` ==
+ * `m7b5`), since no half-diminished triad exists. Extension and added-tone
+ * suffixes are the canonical case-sensitive forms emitted by
+ * {@link chordToRoman} and honor the numeral case: `V9` -> `dom9`, `ii9` ->
+ * `min9`, `Imaj9` -> `maj9`, `V11` -> `11`, `V13` -> `13`, `Iadd6`/`iadd6` ->
+ * `6`/`min6`, `I69` -> `6/9`, `Isus2`/`Isus4`, `Iadd9`/`Iadd11`, `Ib5` ->
+ * `majb5`, `I5` -> `5`, and the altered dominants `V7b9`/`V7#9`/`V7#11`/`V7b13`.
+ * A figure string that is neither a recognized inversion nor a supported
+ * quality suffix throws rather than silently degrading to a triad.
+ *
+ * @param text The Roman numeral.
+ * @param key The prevailing key.
+ * @returns The chord.
+ * @example
+ * ```ts
+ * import { romanToChord, majorKey } from '@libraz/libcantus';
+ * romanToChord('V7', majorKey(0)); // G7 in C major: { rootPc: 7, quality: 'dom7', ... }
+ * ```
+ * @category Functional Harmony
+ */
+declare function romanToChord(text: string, key: KeyScale): Chord;
+/**
+ * Options for {@link chordToRoman}.
+ *
+ * @category Functional Harmony
+ */
+type ChordToRomanOptions = {
+    /**
+     * Render a tonicizing chord as an applied numeral (`V7/V`, `viio7/ii`)
+     * instead of naming its root against the home key (`II7`, `#ivo7`).
+     *
+     * Off by default: naming the root is always a correct spelling, whereas
+     * whether a chromatic dominant is genuinely applied is a reading only the
+     * caller can make. Turning it on makes {@link chordToRoman} the exact inverse
+     * of {@link romanToChord} for the chords {@link secondaryDominant} builds.
+     */
+    applied?: boolean;
+};
+/**
+ * Render a chord as a Roman numeral relative to a key.
+ *
+ * Diatonic roots take their scale-degree numeral directly, so numerals are
+ * correct in both major and minor keys (and any custom scale). The quality
+ * selects the case and suffix; chromatic roots receive a flat/sharp spelling by
+ * convention. A key that is not heptatonic has no numeral of its own for every
+ * degree, so its roots are named against its parallel major.
+ *
+ * When the chord carries a `bassPc` on a chord tone, a figured-bass inversion
+ * (`6`, `64`, `65`, `43`, `42`) is emitted for plain triads and true seventh
+ * chords; added-tone and extended qualities have no lossless figure and render
+ * in root position instead (the bass is dropped, pitch classes are preserved).
+ *
+ * A `bassPc` that is *not* a chord tone — a pedal or passing bass such as
+ * `C/D` — is likewise dropped, and the numeral names the upper chord alone.
+ * Roman-numeral notation spends its slash on applied chords (`V7/V`), so there
+ * is no unambiguous way to write such a bass; a caller that must keep it should
+ * read `chord.bassPc` alongside the numeral.
+ *
+ * @param chord The chord to name.
+ * @param key The prevailing key.
+ * @param opts `applied` renders tonicizing chords as `V7/V`-style numerals.
+ * @returns The Roman numeral string.
+ * @example
+ * ```ts
+ * import { chordToRoman, makeChord, majorKey } from '@libraz/libcantus';
+ * chordToRoman(makeChord(7, 'dom7'), majorKey(0)); // => 'V7' (G7 in C major)
+ * chordToRoman(makeChord(2, 'dom7'), majorKey(0), { applied: true }); // => 'V7/V'
+ * ```
+ * @category Functional Harmony
+ */
+declare function chordToRoman(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): string;
+
 /**
  * Harmonic function (tonic / subdominant / dominant), diatonicity, parallel-key
  * mirroring, and full chord analysis.
@@ -107,13 +197,33 @@ type HarmonicFunction = 'tonic' | 'subdominant' | 'dominant';
  */
 declare function isMinorKey(key: KeyScale): boolean;
 /**
- * The harmonic function of a chord in a key, from its root's offset above the
- * tonic. The mapping follows common-practice major-key function and is a useful
- * approximation in minor and for borrowed chords.
+ * The harmonic function of a chord in a key.
+ *
+ * The root's offset above the tonic gives the baseline mapping, which follows
+ * common-practice major-key function and is a useful approximation in minor and
+ * for borrowed chords. Chord quality then refines it where the sonority settles
+ * an ambiguity the root offset cannot:
+ *
+ * - A chord that *sounds* like a dominant — a major third with a minor seventh,
+ *   or a diminished-family chord — and is not diatonic to the key has dominant
+ *   function when its root resolves down a fifth or by a semitone onto a
+ *   diatonic degree. This is what makes an applied dominant (`A7` in C, which
+ *   tonicizes ii) and its tritone substitute (`Db7`) read as dominant rather
+ *   than inheriting the function of the degree they happen to sit on.
+ * - The Neapolitan is subdominant.
+ * - A major triad on bVI or bVII of a major key is subdominant — the borrowed
+ *   pop cadence chord, distinct from the bVII7 above, which has a seventh and
+ *   is a dominant sonority.
  *
  * @param chord The chord.
  * @param key The prevailing key.
  * @returns The harmonic function.
+ * @example
+ * ```ts
+ * import { functionOf, makeChord, majorKey } from '@libraz/libcantus';
+ * functionOf(makeChord(9, 'dom7'), majorKey(0)); // 'dominant' — A7 tonicizes ii
+ * functionOf(makeChord(10, 'maj'), majorKey(0)); // 'subdominant' — borrowed bVII
+ * ```
  * @category Functional Harmony
  */
 declare function functionOf(chord: Chord, key: KeyScale): HarmonicFunction;
@@ -164,6 +274,7 @@ declare function parallelKey(key: KeyScale): KeyScale;
  *
  * @param chord The chord to analyze.
  * @param key The prevailing key.
+ * @param opts Options used when rendering the Roman numeral.
  * @returns The chord analysis.
  * @example
  * ```ts
@@ -173,15 +284,16 @@ declare function parallelKey(key: KeyScale): KeyScale;
  * ```
  * @category Functional Harmony
  */
-declare function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis;
+declare function analyzeChord(chord: Chord, key: KeyScale, opts?: ChordToRomanOptions): ChordAnalysis;
 /**
  * The secondary dominant (V7) that tonicizes a scale degree.
  *
  * @param targetDegree 0-based scale degree to tonicize.
  * @param key The prevailing key.
  * @returns A dominant-seventh chord a fifth above the target's root.
+ * @throws If `targetDegree` is not an integer naming a degree in `key`.
  * @category Functional Harmony
  */
 declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord;
 
-export { type BorrowedSource as B, type Cadence as C, type HarmonicFunction as H, type ChordAnalysis as a, analyzeChord as b, borrowedSource as c, detectCadence as d, isDiatonic as e, functionOf as f, isMinorKey as g, isBorrowedChord as i, parallelKey as p, secondaryDominant as s };
+export { type BorrowedSource as B, type Cadence as C, type HarmonicFunction as H, type ChordAnalysis as a, type ChordToRomanOptions as b, analyzeChord as c, borrowedSource as d, chordToRoman as e, detectCadence as f, functionOf as g, isDiatonic as h, isBorrowedChord as i, isMinorKey as j, parallelKey as p, romanToChord as r, secondaryDominant as s };