@hosanna/chordpro 1.1.0

package/dist/index.mjs

@@ -0,0 +1,54 @@
+import {
+  ChordFinder,
+  Editor,
+  preloadEditor,
+  registerChordproMode,
+  registerChordproSnippets
+} from "./chunk-QZY7KJWK.mjs";
+import {
+  convertToChordProDetailed,
+  detectSourceFormat,
+  slugifyTitle,
+  toChordPro
+} from "./chunk-6VAMM7S3.mjs";
+import {
+  ChordProRenderer,
+  ChordRoll,
+  GuitarDiagram,
+  PianoDiagram
+} from "./chunk-CTBAE2XK.mjs";
+import {
+  DefaultChordDictionary,
+  buildChordProText,
+  chordDictionary,
+  getNoteValue,
+  getSuggestedCapo,
+  parseChordPro,
+  parseLineSegments,
+  transposeChord,
+  transposeNote
+} from "./chunk-PENNIH4J.mjs";
+export {
+  ChordFinder,
+  ChordProRenderer,
+  ChordRoll,
+  DefaultChordDictionary,
+  Editor,
+  GuitarDiagram,
+  PianoDiagram,
+  buildChordProText,
+  chordDictionary,
+  convertToChordProDetailed,
+  detectSourceFormat,
+  getNoteValue,
+  getSuggestedCapo,
+  parseChordPro,
+  parseLineSegments,
+  preloadEditor,
+  registerChordproMode,
+  registerChordproSnippets,
+  slugifyTitle,
+  toChordPro,
+  transposeChord,
+  transposeNote
+};

package/dist/parser/index.d.mts

@@ -0,0 +1,185 @@
+interface SegmentAST {
+    chord: string;
+    text: string;
+    timing?: number;
+}
+interface MeasureAST {
+    chords: SegmentAST[];
+    endBarline: string;
+}
+interface LineAST {
+    type: "lyrics" | "comment" | "comment_box" | "tab" | "empty" | "chord-section";
+    text?: string;
+    segments?: SegmentAST[];
+    measures?: MeasureAST[];
+    startBarline?: string;
+}
+interface SectionAST {
+    type: "verse" | "chorus" | "bridge" | "tab" | "comment" | "grid" | "new_song";
+    label?: string;
+    lines: LineAST[];
+    repeat?: string;
+}
+interface SongAST {
+    metadata: {
+        title?: string;
+        subtitle?: string;
+        artist?: string;
+        composer?: string;
+        copyright?: string;
+        album?: string;
+        key?: string;
+        originalKey?: string;
+        tempo?: string;
+        time?: string;
+        capo?: string;
+        songNumber?: string;
+        youtube?: string;
+        ccli?: string;
+        duration?: string;
+        [key: string]: string | undefined;
+    };
+    sections: SectionAST[];
+}
+declare function parseLineSegments(lineText: string): SegmentAST[];
+declare function parseChordPro(content: string): SongAST;
+declare function buildChordProText(metadata: {
+    [key: string]: string | undefined;
+}, bodyContent: string): string;
+
+declare function getNoteValue(note: string): number | undefined;
+declare function getSuggestedCapo(originalKey: string | undefined, transposeVal: number): {
+    capo: number;
+    chordShape: string;
+} | null;
+declare function transposeNote(note: string, semitones: number, preferFlats?: boolean): string;
+declare function transposeChord(chord: string, semitones: number): string;
+
+/**
+ * Chord Dictionary — interval-driven engine
+ * ------------------------------------------
+ * Instead of hand-listing a fingering per chord symbol, chords are derived from
+ * music theory:
+ *
+ *   1. Parse "root + quality (+ /bass)" out of the symbol (English or PT-BR/PT-PT
+ *      note names).
+ *   2. Look up the quality's semitone INTERVALS (a registry, not a switch).
+ *   3. Piano is 100% computed from those intervals — every quality, any root,
+ *      no hardcoding, no fallback needed.
+ *   4. Guitar fingerings are physical shapes on 6 strings, which can't be
+ *      derived from pure interval math the way piano can (open strings,
+ *      playability, hand span). So guitar uses a small, honest hybrid:
+ *        a) A curated table of well-known open-position shapes (exact, best-sounding).
+ *        b) Two movable CAGED "barre templates" (E-form / A-form) covering the
+ *           7 qualities that have a standard, universally-taught movable shape
+ *           (major, minor, 7, m7, maj7, sus2, sus4) — these transpose correctly
+ *           to ANY root via simple math (shift = target - templateRoot).
+ *        c) A power-chord (5) formula, which is pure math on any string.
+ *        d) For qualities with no standard movable shape (dim7, aug, 9, 6,
+ *           extended/altered chords, ...), we fall back to the nearest simpler
+ *           quality's shape and flag the result as `approximate: true`, rather
+ *           than silently returning something wrong or nothing at all.
+ */
+interface ChordFingering {
+    chord: string;
+    /** Canonical quality id resolved for this chord, e.g. "m7", "maj7", "9". */
+    qualityId: string;
+    /** Human readable quality label, e.g. "Minor 7th". */
+    qualityLabel: string;
+    guitar?: {
+        frets: number[];
+        fingers?: number[];
+        barre?: number;
+        /** True when no standard shape exists for this exact quality and we
+         *  substituted the nearest simpler quality's shape (e.g. dim7 -> minor shape). */
+        approximate?: boolean;
+    };
+    piano: {
+        notes: string[];
+        highlightKeys: number[];
+    };
+}
+interface IChordDictionary {
+    getFingering: (chord: string) => ChordFingering | null;
+}
+declare class DefaultChordDictionary implements IChordDictionary {
+    getFingering(chord: string): ChordFingering | null;
+}
+declare const chordDictionary: DefaultChordDictionary;
+
+/**
+ * txtToChordPro.ts
+ * ------------------------------------------------------------------------
+ * Universal chord-sheet -> ChordPro converter.
+ *
+ * Handles three input flavours out of the box:
+ *   - "ultimate-guitar"  -> bracket section headers ([Verse], [Chorus 1], [Intro]),
+ *                           English metadata (Capo:, Tuning:, Key:), trailing
+ *                           repeat notation ("... let it be x2").
+ *   - "cifraclub"        -> Portuguese metadata (Tom:, Capotraste:, Intérprete:),
+ *                           syllable-hyphenated lyrics used purely to align
+ *                           chords over multi-syllable Portuguese words
+ *                           (e.g. "Deus-que-tomou-meu-lugar"), Portuguese
+ *                           section labels (Refrão, Verso, Ponte, Introdução...).
+ *   - "plain"            -> generic chord-line-over-lyric-line sheets with no
+ *                           site-specific quirks. Also the safe fallback.
+ *
+ * Source format is auto-detected by default (source: 'auto'), but can be
+ * forced via options.source. Chord <-> lyric alignment is done by column
+ * position (not just token order), so mid-word chords and chords that spill
+ * past the end of a lyric line are placed exactly like a human would expect:
+ *
+ *   Am         C/G        F          C
+ *   Let it be, let it be, let it be, let it be
+ *
+ *   -> Let i[Am]t be, let [C/G]it be, let [F]it be, let [C]it be
+ *
+ * ------------------------------------------------------------------------
+ */
+type SourceFormat = "ultimate-guitar" | "cifraclub" | "plain";
+type SourceOption = SourceFormat | "auto";
+interface ConversionOptions {
+    /** Force a source format instead of auto-detecting. Default: 'auto'. */
+    source?: SourceOption;
+    /** Emit {start_of_verse}/{start_of_chorus}/etc. Default: true. */
+    detectSections?: boolean;
+    /**
+     * Require every token on a candidate chord line to be a valid chord
+     * (true) vs. a majority (>=80%, false). Default: true. Turning this off
+     * helps with messy OCR/paste artifacts but raises false-positive risk.
+     */
+    strictChordDetection?: boolean;
+    /**
+     * Undo CifraClub-style syllable hyphenation ("Deus-que-tomou-meu-lugar"
+     * -> "Deus que tomou meu lugar") before merging chords in. 'auto' only
+     * does this when the detected/forced source is 'cifraclub'. Default: 'auto'.
+     */
+    dehyphenateSyllables?: boolean | "auto";
+    /**
+     * Reattach trailing repeat markers ("x2", "2x", "(2x)") to the end of the
+     * merged lyric line instead of treating them as stray chord tokens.
+     * Default: true.
+     */
+    keepRepeatMarkers?: boolean;
+    /**
+     * Tag names used for non-standard section types (intro/outro/solo/etc).
+     * Override if your ChordPro/AST parser expects different tag names.
+     * Defaults match the {start_of_part}/{end_of_part} convention.
+     */
+    partTagNames?: {
+        start: string;
+        end: string;
+    };
+}
+interface ConversionResult {
+    chordpro: string;
+    title: string | null;
+    detectedSource: SourceFormat;
+    warnings: string[];
+}
+declare function detectSourceFormat(input: string): SourceFormat;
+declare function slugifyTitle(title: string | null): string;
+declare function convertToChordProDetailed(input: string, options?: ConversionOptions): ConversionResult;
+declare function toChordPro(input: string, options?: ConversionOptions): string;
+
+export { type ChordFingering, type ConversionOptions, type ConversionResult, DefaultChordDictionary, type IChordDictionary, type LineAST, type MeasureAST, type SectionAST, type SegmentAST, type SongAST, type SourceFormat, type SourceOption, buildChordProText, chordDictionary, convertToChordProDetailed, detectSourceFormat, getNoteValue, getSuggestedCapo, parseChordPro, parseLineSegments, slugifyTitle, toChordPro, transposeChord, transposeNote };

package/dist/parser/index.d.ts

@@ -0,0 +1,185 @@
+interface SegmentAST {
+    chord: string;
+    text: string;
+    timing?: number;
+}
+interface MeasureAST {
+    chords: SegmentAST[];
+    endBarline: string;
+}
+interface LineAST {
+    type: "lyrics" | "comment" | "comment_box" | "tab" | "empty" | "chord-section";
+    text?: string;
+    segments?: SegmentAST[];
+    measures?: MeasureAST[];
+    startBarline?: string;
+}
+interface SectionAST {
+    type: "verse" | "chorus" | "bridge" | "tab" | "comment" | "grid" | "new_song";
+    label?: string;
+    lines: LineAST[];
+    repeat?: string;
+}
+interface SongAST {
+    metadata: {
+        title?: string;
+        subtitle?: string;
+        artist?: string;
+        composer?: string;
+        copyright?: string;
+        album?: string;
+        key?: string;
+        originalKey?: string;
+        tempo?: string;
+        time?: string;
+        capo?: string;
+        songNumber?: string;
+        youtube?: string;
+        ccli?: string;
+        duration?: string;
+        [key: string]: string | undefined;
+    };
+    sections: SectionAST[];
+}
+declare function parseLineSegments(lineText: string): SegmentAST[];
+declare function parseChordPro(content: string): SongAST;
+declare function buildChordProText(metadata: {
+    [key: string]: string | undefined;
+}, bodyContent: string): string;
+
+declare function getNoteValue(note: string): number | undefined;
+declare function getSuggestedCapo(originalKey: string | undefined, transposeVal: number): {
+    capo: number;
+    chordShape: string;
+} | null;
+declare function transposeNote(note: string, semitones: number, preferFlats?: boolean): string;
+declare function transposeChord(chord: string, semitones: number): string;
+
+/**
+ * Chord Dictionary — interval-driven engine
+ * ------------------------------------------
+ * Instead of hand-listing a fingering per chord symbol, chords are derived from
+ * music theory:
+ *
+ *   1. Parse "root + quality (+ /bass)" out of the symbol (English or PT-BR/PT-PT
+ *      note names).
+ *   2. Look up the quality's semitone INTERVALS (a registry, not a switch).
+ *   3. Piano is 100% computed from those intervals — every quality, any root,
+ *      no hardcoding, no fallback needed.
+ *   4. Guitar fingerings are physical shapes on 6 strings, which can't be
+ *      derived from pure interval math the way piano can (open strings,
+ *      playability, hand span). So guitar uses a small, honest hybrid:
+ *        a) A curated table of well-known open-position shapes (exact, best-sounding).
+ *        b) Two movable CAGED "barre templates" (E-form / A-form) covering the
+ *           7 qualities that have a standard, universally-taught movable shape
+ *           (major, minor, 7, m7, maj7, sus2, sus4) — these transpose correctly
+ *           to ANY root via simple math (shift = target - templateRoot).
+ *        c) A power-chord (5) formula, which is pure math on any string.
+ *        d) For qualities with no standard movable shape (dim7, aug, 9, 6,
+ *           extended/altered chords, ...), we fall back to the nearest simpler
+ *           quality's shape and flag the result as `approximate: true`, rather
+ *           than silently returning something wrong or nothing at all.
+ */
+interface ChordFingering {
+    chord: string;
+    /** Canonical quality id resolved for this chord, e.g. "m7", "maj7", "9". */
+    qualityId: string;
+    /** Human readable quality label, e.g. "Minor 7th". */
+    qualityLabel: string;
+    guitar?: {
+        frets: number[];
+        fingers?: number[];
+        barre?: number;
+        /** True when no standard shape exists for this exact quality and we
+         *  substituted the nearest simpler quality's shape (e.g. dim7 -> minor shape). */
+        approximate?: boolean;
+    };
+    piano: {
+        notes: string[];
+        highlightKeys: number[];
+    };
+}
+interface IChordDictionary {
+    getFingering: (chord: string) => ChordFingering | null;
+}
+declare class DefaultChordDictionary implements IChordDictionary {
+    getFingering(chord: string): ChordFingering | null;
+}
+declare const chordDictionary: DefaultChordDictionary;
+
+/**
+ * txtToChordPro.ts
+ * ------------------------------------------------------------------------
+ * Universal chord-sheet -> ChordPro converter.
+ *
+ * Handles three input flavours out of the box:
+ *   - "ultimate-guitar"  -> bracket section headers ([Verse], [Chorus 1], [Intro]),
+ *                           English metadata (Capo:, Tuning:, Key:), trailing
+ *                           repeat notation ("... let it be x2").
+ *   - "cifraclub"        -> Portuguese metadata (Tom:, Capotraste:, Intérprete:),
+ *                           syllable-hyphenated lyrics used purely to align
+ *                           chords over multi-syllable Portuguese words
+ *                           (e.g. "Deus-que-tomou-meu-lugar"), Portuguese
+ *                           section labels (Refrão, Verso, Ponte, Introdução...).
+ *   - "plain"            -> generic chord-line-over-lyric-line sheets with no
+ *                           site-specific quirks. Also the safe fallback.
+ *
+ * Source format is auto-detected by default (source: 'auto'), but can be
+ * forced via options.source. Chord <-> lyric alignment is done by column
+ * position (not just token order), so mid-word chords and chords that spill
+ * past the end of a lyric line are placed exactly like a human would expect:
+ *
+ *   Am         C/G        F          C
+ *   Let it be, let it be, let it be, let it be
+ *
+ *   -> Let i[Am]t be, let [C/G]it be, let [F]it be, let [C]it be
+ *
+ * ------------------------------------------------------------------------
+ */
+type SourceFormat = "ultimate-guitar" | "cifraclub" | "plain";
+type SourceOption = SourceFormat | "auto";
+interface ConversionOptions {
+    /** Force a source format instead of auto-detecting. Default: 'auto'. */
+    source?: SourceOption;
+    /** Emit {start_of_verse}/{start_of_chorus}/etc. Default: true. */
+    detectSections?: boolean;
+    /**
+     * Require every token on a candidate chord line to be a valid chord
+     * (true) vs. a majority (>=80%, false). Default: true. Turning this off
+     * helps with messy OCR/paste artifacts but raises false-positive risk.
+     */
+    strictChordDetection?: boolean;
+    /**
+     * Undo CifraClub-style syllable hyphenation ("Deus-que-tomou-meu-lugar"
+     * -> "Deus que tomou meu lugar") before merging chords in. 'auto' only
+     * does this when the detected/forced source is 'cifraclub'. Default: 'auto'.
+     */
+    dehyphenateSyllables?: boolean | "auto";
+    /**
+     * Reattach trailing repeat markers ("x2", "2x", "(2x)") to the end of the
+     * merged lyric line instead of treating them as stray chord tokens.
+     * Default: true.
+     */
+    keepRepeatMarkers?: boolean;
+    /**
+     * Tag names used for non-standard section types (intro/outro/solo/etc).
+     * Override if your ChordPro/AST parser expects different tag names.
+     * Defaults match the {start_of_part}/{end_of_part} convention.
+     */
+    partTagNames?: {
+        start: string;
+        end: string;
+    };
+}
+interface ConversionResult {
+    chordpro: string;
+    title: string | null;
+    detectedSource: SourceFormat;
+    warnings: string[];
+}
+declare function detectSourceFormat(input: string): SourceFormat;
+declare function slugifyTitle(title: string | null): string;
+declare function convertToChordProDetailed(input: string, options?: ConversionOptions): ConversionResult;
+declare function toChordPro(input: string, options?: ConversionOptions): string;
+
+export { type ChordFingering, type ConversionOptions, type ConversionResult, DefaultChordDictionary, type IChordDictionary, type LineAST, type MeasureAST, type SectionAST, type SegmentAST, type SongAST, type SourceFormat, type SourceOption, buildChordProText, chordDictionary, convertToChordProDetailed, detectSourceFormat, getNoteValue, getSuggestedCapo, parseChordPro, parseLineSegments, slugifyTitle, toChordPro, transposeChord, transposeNote };