@libraz/libcantus 0.9.3 → 0.9.4

package/dist/{function-DVH4Eusr.d.ts → function-DNugAOrt.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-y_ak9_Hi.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).
  *
@@ -107,13 +107,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;
@@ -177,9 +197,10 @@ declare function analyzeChord(chord: Chord, key: KeyScale): ChordAnalysis;
 /**
  * The secondary dominant (V7) that tonicizes a scale degree.
  *
- * @param targetDegree 0-based scale degree to tonicize.
+ * @param targetDegree 0-based scale degree to tonicize, in 0..6.
  * @param key The prevailing key.
  * @returns A dominant-seventh chord a fifth above the target's root.
+ * @throws If `targetDegree` is not an integer in 0..6.
  * @category Functional Harmony
  */
 declare function secondaryDominant(targetDegree: number, key: KeyScale): Chord;