vector-score 1.1.0 → 1.2.1

package/README.md

@@ -5,41 +5,33 @@
 [![Bundlephobia](https://img.shields.io/bundlephobia/minzip/vector-score)](https://bundlephobia.com/package/vector-score)
 ![NPM Downloads](https://img.shields.io/npm/d18m/vector-score)
 
-A lightweight, SVG-based TypeScript library for rendering musical staves, notes, and rhythm patterns in the browser.
+A lightweight, SVG-based TypeScript library for rendering simple musical notation, rhythm staves, and guitar chords. Designed for simple displaying musical information for musical oriented web applications.
 
-## Features
-
-* **Multiple Staff Types**: Supports Treble, Bass, Alto, and Grand staves (MusicStaff and ScrollingStaff).
-* [**Music Staff**](#Standard-Music-Staff):Standard music staff for notation.
-* [**Rhythm Staff**](#Rhythm-Staff): Dedicated staff for rhythm exercises with customizable time signatures and bar handling.
-* [**Scrolling Staff**](#Scrolling-Staff) Staff made to allow for 'endless' style of notes.
-* **SVG Rendering**: Scalable Vector graphics suitable for any screen size.
-* **Flexible Note Input**: Simple string-based syntax for defining notes.
-
-## Installation
-
-```bash
-npm i vector-score
-````
+<br/>
 
-## Development
+## Features
 
-To start the development server with a playground:
+### Rendering Standard Musical Notation
+* Supports grand, treble, bass, and alto clefs.
+* Easy to add notes and provides justifying alignment functions.
+* Simple single line staff for display chords, notes, or scales.
+* [**Go to Music Staffs**](#Grand-Staff) 
 
-```bash
-npm run dev
-```
+### Render and Display Guitar Chords
+* Write explicitly which string, fret, and optionally finger to display on the diagram.
+* Supports explicity barre chords.
+* Label each string below diagram, useful for showing tuning of chord.
+* [**Go to Guitar Chords**](#Guitar-Chords)
 
-To build the library for production:
+### Extra Classes
+* Dedicated staff for rhythm exercises with customizable time signatures and bar handling. [**Go to Rhythm Staff**](#Rhythm-Staff)
+* Staff made to allow for 'endless' style of notes. [**Go to Scrolling Staff**](#Scrolling-Staff)
 
-```bash
-npm run build
-```
+<br />
 
 ## Usage
 
 ### 1. Setup HTML
-
 Create a container element in your HTML where the staff will be rendered.
 
 ```html
@@ -47,8 +39,7 @@ Create a container element in your HTML where the staff will be rendered.
 ```
 
 ### 2. Import and Initialize
-
-### Standard Music Staff
+Import desired class (MusicStaff, GuitarChord, etc.). Declare variable with reference to container element. Pass in options for specific class (options are typed).
 
 ```typescript
 import { MusicStaff } from 'vector-score';
@@ -64,19 +55,43 @@ const staff = new MusicStaff(container, {
 });
 
 // Draw a C Minor scale (quarter notes)
-// Format: NoteName + Accidental(optional) + Octave + Duration
 staff.drawNote(['C4q', 'D4q', 'Eb4q', 'F4q', 'G4q', 'Ab4q', 'Bb4q', 'C5q']);
-
-// Draw a C Chord
-staff.drawChord(['C4w', 'E4w', 'G4w']);
-
-// Evenly space all notes on the staff
 staff.justifyNotes();
 ```
-#### Resulting Staff
+
+### Resulting Staff
 ![Alt Text](https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/MusicStaffTrebleResult.svg)
 
-### Grand Staff
+<br/>
+
+## Notes
+
+### CSS Classes
+Listed below will be all the specific classes that can be targeted to change their repsective elements styling. All elements that are designed to be targeted with classes are prefixed with `vs-`.
+
+* `svg.vs-svg-renderer-root`: The actual svg element.
+* `g.vs-svg-renderer-parent`: The main group element.
+* `text.vs-guitar-text-base && text.vs-guitar-text-small`: The \<text\> elements for the labels on the guitar chord diagram.
+* `circle.vs-guitar-fret-dot`: The element for the guitar fret dots.
+* `rect.vs-guitar-barre`: The element for the guitar barre lines.
+* `g.vs-scrolling-notes-layer > g.vs-note-wrapper`: Targeting the scrolling staff's notes, which a transition property can be added for smooth animation.
+
+Example
+
+```css
+/* Target and change the fret dot colors */
+.vs-guitar-fret-dot {
+  fill: oklch(67% 0.05 240.864);
+}
+```
+
+<br />
+
+## Grand Staff
+
+See [**Note String Syntax**](#Note-String-Syntax) to see how to write notes on music staff (i.e. ['G4q', 'E4h', 'C4w', "A3h", "F3h"] )
+
+See [**MusicStaffOptions**](#MusicStaffOptions) to see how configuration options during class instantiation.
 
 ```typescript
 import { MusicStaff } from 'vector-score';
@@ -93,10 +108,51 @@ grandStaff.drawNote(['G4q', 'E4h', 'C4w', "A3h", "F3h"]);
 
 grandStaff.drawChord(["G3w", "C4w", "E4w"]);
 ```
-#### Resulting Staff
+### Resulting Staff
 ![Alt Text](https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/MusicStaffGrandResult.svg)
 
-### Rhythm Staff
+<br/>
+
+## Guitar Chords
+
+See [**Guitar String Syntax**](#Guitar-String-Syntax) to see how to write **frets**, **fingers**, and **barre lines** on Guitar Chord diagrams (i.e., `"x32010"`, `"032010"`).
+
+See [**GuitarChordOptions**](#GuitarChordOptions) to see how configuration options during class instantiation.
+
+```typescript
+import { GuitarChord } from 'vector-score';
+
+const grandStaff = new GuitarChord(container, {
+  fretCount: 5,
+  stringCount: 6,
+  stringLabels: ["E", "A", "D", "G", "B", "E"],
+  inlineChordsAmount: 2, // Choose how many chords are in a single line
+  scale: 1,
+  color: "var(--font-color)",
+  backgroundColor: "white"
+});
+
+// C chord
+guitarChordsSection.addChord("x32010", "032010", {
+  label: "C",
+});
+
+// Bbmaj7 Barre Chord (Automatically calculates the starting fret and barre positioning)
+const frets = "687766";
+const fingers = "142311";
+const barres = guitarChordsSection.determineBarreOptions(frets, fingers, [6]);
+
+guitarChordsSection.addChord(frets, fingers, {
+  label: "Bbmaj7",
+  barres: barres
+});
+```
+### Result
+![Alt Text](https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/GuitarChordsResult.svg)
+
+<br />
+
+## Rhythm Staff
 
 ```typescript
 import { RhythmStaff } from 'vector-score';
@@ -122,10 +178,12 @@ rhythm.drawNote(['q', 'q']);
 // Increment the UI to show the first beat in the bar
 rhythm.incrementCurrentBeatUI();
 ```
-#### Resulting Staff
+### Resulting Staff
 ![Alt Text](https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/RhythmStaffResult.svg)
 
-### Scrolling Staff
+<br />
+
+## Scrolling Staff
 
 ```typescript
 import { ScrollingStaff } from 'vector-score';
@@ -165,9 +223,11 @@ scrollingStaff.queueNotes([
 
 // The button event listener calls 'advanceNotes()' to move the notes over, one step at a time.
 ```
-#### Resulting Staff
+### Resulting Staff
 ![Alt Text](https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/ScrollingStaffResult.webp)
 
+<br />
+
 ## Note String Syntax
 
 Notes are defined using a specific string format parsed by the library:
@@ -188,6 +248,35 @@ Notes are defined using a specific string format parsed by the library:
 * `F#5q`: F Sharp, Octave 5, Quarter note
 * `Bb3e`: B Flat, Octave 3, Eighth note
 
+<br />
+
+## Guitar String Syntax
+
+Chords are defined using two continuous strings: one for **frets** and one for **fingers**. The length of both strings must match the configured string count of the diagram (default is 6). Notes are written in ***string order***, with the first character representing the lowest string (e.g., low E in standard tuning).
+
+### Frets String format: `[xX\da-zA-Z]+`
+* `x` or `X`: Muted string.
+* `0`: Open string.
+* `1-9`: Fretted at the specified fret.
+* `a-z` / `A-Z`: Base-36 alphanumeric encoding for double-digit frets (e.g., `a` = 10, `b` = 11, `c` = 12).
+
+### Fingers String format: `[\d]+`
+* `0`: No finger labeled.
+* `1-9`: Finger number to display on the dot.
+
+**Example:**
+* `guitarChordsSection.addChord("x32010", "032010")`: Displays an open C major chord.
+  * The lowest string is muted (`x`) and has no finger label (`0`).
+  * The A string is played at the 3rd fret (`3`) with the 3rd finger (`3`).
+  * *Note: The `startFret` option is now automatically calculated based on the lowest fretted note if left undefined.*
+
+### Barre Lines
+Barre lines can be added dynamically using the built-in helper method, `determineBarreOptions(frets, fingers, barreFrets)`. 
+* Pass in your fret string, finger string, and an array of the target frets you wish to barre. 
+* The method will automatically calculate the stretch (`fromString` to `toString`) based on the matching finger numbers and return a definition array to pass directly into your `addChord` options.
+
+<br />
+
 ## API Reference
 
 ### MusicStaff Class
@@ -202,6 +291,22 @@ Notes are defined using a specific string format parsed by the library:
 | `changeChordByIndex(notes: string[], index: number)` | Replaces a chord at a specific index with a new chord. |
 | `destroy()` | Destroys internal arrays and elements |
 
+<br/>
+
+### GuitarChord Class
+
+| Method | Description |
+| :--- | :--- |
+| `addChord(frets: string, fingers: string, options?: GuitarChordDrawOptions)` | Draws notes on the diagram using string configurations. Options include manual `startFret`, `label`, and `barres`. |
+| `modifyChordByIndex(frets: string, fingers: string, chordIndex: number, options?: GuitarChordDrawOptions)` | Modifies the chord at the specified index with new definitions and options. |
+| `determineBarreOptions(frets: string, fingers: string, barreFrets: number[])` | Automatically calculates barre line dimensions based on fingering and returns `GuitarBarreDef[]` to be used in chord options. |
+| `removeChordByIndex(chordIndex: number)` | Removes the chord diagram at the specified index and recalculates layout. |
+| `clearAllChords()` | Removes all chords in the container. |
+| `destroy()` | Destroys internal arrays and elements. |
+
+
+<br/>
+
 ### RhythmStaff Class
 
 | Method | Description |
@@ -214,6 +319,8 @@ Notes are defined using a specific string format parsed by the library:
 | `resetCurrentBeatUI()` | Must be called if current beat goes over the total beats in the bar to reset its state |
 | `destroy()` | Destroys internal arrays and elements |
 
+<br/>
+
 ### ScrollingStaff Class
 
 | Method | Description |
@@ -223,6 +330,8 @@ Notes are defined using a specific string format parsed by the library:
 | `clearAllNote()` | Clears all notes on the staff |
 | `destroy()` | Destroys internal arrays and elements | 
 
+<br />
+
 ## Configuration Options
 
 ### MusicStaffOptions
@@ -236,6 +345,16 @@ Notes are defined using a specific string format parsed by the library:
 * `staffColor`: CSS color string for lines and notes.
 * `staffBackgroundColor`: CSS color string for background.
 
+### GuitarChordOptions
+* `stringCount`: Amount of strings to show in diagram, default is 6.
+* `fretCount`: Amount of frets to show in diagram, default is 5.
+* `stringLabels`: Labels to show under each string in each chord diagram. Provided string values will display in order of strings in this array value.
+* `inlineChordsAmount`: Max amount of chords to display on a single line (default: 2).
+* `scale`: Zoom factor (default: 1).
+* `color`: CSS color string for lines and notes.
+* `backgroundColor`: CSS color string for background.
+* `width`: Total width of the SVG in pixels, overrides inlineChordAmount auto width calculation (default: undefined).
+
 ### RhythmStaffOptions
 * `topNumber`: The top number of the time signature (e.g., 4 for 4/4 time).
 * `barsCount`: Number of measures to draw.

package/dist/classes/GuitarChord.d.ts

@@ -0,0 +1,108 @@
+import { GuitarBarreDef, GuitarChordDrawOptions } from '../types';
+export type GuitarChordOptions = {
+    width?: number;
+    inlineChordsAmount?: number;
+    scale?: number;
+    stringCount?: number;
+    fretCount?: number;
+    stringLabels?: string[];
+    color?: string;
+    backgroundColor?: string;
+};
+export default class GuitarChord {
+    private svgRendererInstance;
+    private options;
+    private chordEntries;
+    private cursorX;
+    private cursorY;
+    private readonly diagramWidth;
+    private readonly diagramHeight;
+    private readonly gridTopY;
+    private readonly rowHeight;
+    /**
+     * Creates an instance of a GuitarChord diagram renderer.
+     *
+     * @param rootElementCtx - The element (div) reference that the chord diagram(s) will be appended to.
+     * @param options - Optional configuration. Can adjust total width, scale, string/fret count, and coloring.
+     * All config options are in the type GuitarChordOptions.
+    */
+    constructor(rootElementCtx: HTMLElement, options?: GuitarChordOptions);
+    private getDotsToHide;
+    private drawFretDots;
+    private drawStringLabels;
+    private drawBarre;
+    private renderChordDiagram;
+    private relayoutChords;
+    /**
+     * Adds a new chord diagram. Diagrams are placed left-to-right in the order added, wrapping to a
+     * new row automatically once the configured width is exceeded.
+     *
+     * @param frets - A string, with each value being ordered low-to-high (e.g. first position in string 0 is the low E string)
+     * * `x` - muted string
+     * * `0` - open string
+     * * `1...n` - fretted at the given absolute fret number (e.g. `3`)
+     * @param fingers - A string, with each value being ordered low-to-high (e.g. first position in string 0 is the low E string)
+     * * `0` - No finger labeled
+     * * `1...n` - Finger labeled as number provided
+     *
+     * @param options - Optional per-chord settings: `startFret` (default `1`, for diagrams higher up the neck)
+     * and `label` (a chord name drawn above the diagram).
+     *
+     * @returns The index of the newly added chord, for later use with the CRUD-by-index methods.
+     *
+     * @throws {Error} If fret or finger's string length doesn't match the configured string count.
+     *
+     * @example
+     * // Draw an open C major chord
+     * guitarChord.addChord("x32010", "032010", { label: "C" });
+    */
+    addChord(frets: string, fingers: string, options?: GuitarChordDrawOptions): number;
+    /**
+     * Replaces the chord diagram at the specified index with a new one, in place.
+     *
+    * @param frets - A string, with each value being ordered low-to-high (e.g. first position in string 0 is the low E string)
+     * * `x` - muted string
+     * * `0` - open string
+     * * `1...n` - fretted at the given absolute fret number (e.g. `3`)
+     * @param fingers - A string, with each value being ordered low-to-high (e.g. first position in string 0 is the low E string)
+     * * `0` - No finger labeled
+     * * `1...n` - Finger labeled as number provided
+     *
+     * @param chordIndex - The index of the chord to replace (as returned by addChord).
+     *
+     * @param options - Optional per-chord settings, see addChord.
+     *
+     * @returns void
+     *
+     * @throws {Error} If the index is out of bounds, or if chordDef is invalid (see addChord).
+     *
+     * @example
+     * // Change chord at index 0 to a D major chord
+     * guitarChord.modifyChordByIndex("xx0232", "000132", 0, { label: "D" });
+     *
+    */
+    modifyChordByIndex(frets: string, fingers: string, chordIndex: number, options?: GuitarChordDrawOptions): void;
+    /**
+     * Removes the chord diagram at the specified index. Remaining chords are re-flowed to close the gap.
+     * @param chordIndex - The index of the chord to remove.
+     * @returns void
+     * @throws {Error} If the index is out of bounds.
+    */
+    removeChordByIndex(chordIndex: number): void;
+    /**
+     * Removes all chord diagrams and resets internal positioning.
+     * @returns void
+    */
+    clearAllChords(): void;
+    /**
+     * * Used to automatically determine options for creating barre lines.
+     * * The returned value then can be used in addChord and modifyChord methods.
+     * @returns GuitarBarreDef[]
+    */
+    determineBarreOptions(frets: string, fingers: string, barreFrets: number[]): GuitarBarreDef[];
+    /**
+     * Removes the root svg element and cleans up arrays.
+     * @returns void
+    */
+    destroy(): void;
+}

package/dist/classes/SVGRenderer.d.ts

@@ -17,6 +17,21 @@ type DrawRectOptions = {
     x?: number;
     y?: number;
     fill?: string;
+    rx?: number;
+    classes?: string | string[];
+};
+type DrawCircleOptions = {
+    filled?: boolean;
+    fill?: string;
+    strokeWidth?: number;
+    classes?: string | string[];
+};
+type DrawTextOptions = {
+    fontSize?: number;
+    anchor?: "start" | "middle" | "end";
+    fill?: string;
+    fontWeight?: string;
+    classes?: string | string[];
 };
 export default class SVGRenderer {
     private rootElementRef;
@@ -31,10 +46,12 @@ export default class SVGRenderer {
     private totalHeight;
     constructor(rootElementCtx: HTMLElement, options: SVGRendererOptions);
     private makeGlyphDefs;
+    private addNamespacedClassesToElement;
     createGroup(className?: string): SVGGElement;
     commitElementsToDOM(elements: SVGElement[] | SVGElement, parent?: HTMLElement | SVGElement): void;
     getLayerByName(name: LayerNames): SVGGElement;
     addTotalRootSvgHeight(amount: number): void;
+    setTotalRootSvgHeight(amount: number): void;
     addTotalRootSvgYOffset(amount: number): void;
     applySizingToRootSvg(): void;
     get rootSvgElement(): SVGElement;
@@ -42,6 +59,8 @@ export default class SVGRenderer {
     drawLine(x1: number, y1: number, x2: number, y2: number, parent: SVGElement): void;
     drawRect(width: number, height: number, parent: SVGElement, options?: DrawRectOptions): SVGRectElement;
     drawGlyph(glyphName: GlyphNames, parent: SVGElement, options?: DrawGlyphOptions): void;
+    drawCircle(cx: number, cy: number, radius: number, parent: SVGElement, options?: DrawCircleOptions): SVGCircleElement;
+    drawText(text: string, x: number, y: number, parent: SVGElement, options?: DrawTextOptions): SVGTextElement;
     destroy(): void;
 }
 export {};

package/dist/constants.d.ts

@@ -17,3 +17,22 @@ export declare const HALF_NOTE_LEDGER_LINE_WIDTH = 12.5;
 export declare const CHORD_MAX_CONSECUTIVE_ACCIDENTALS = 3;
 export declare const staffParams: Record<StaffTypes, StaffParams>;
 export declare const durationBeatValueMap: Record<Durations, number>;
+export declare const GUITAR_STRING_COUNT_DEFAULT = 6;
+export declare const GUITAR_FRET_COUNT_DEFAULT = 5;
+export declare const GUITAR_STRING_SPACING = 22;
+export declare const GUITAR_FRET_SPACING = 30;
+export declare const GUITAR_DOT_RADIUS = 10;
+export declare const GUITAR_MARKER_RADIUS = 6;
+export declare const GUITAR_STRING_LABEL_OFFSET = 4;
+export declare const GUITAR_STRING_LABEL_HEIGHT: number;
+export declare const GUITAR_DIAGRAM_H_SPACING = 51;
+export declare const GUITAR_DIAGRAM_V_SPACING = 12;
+export declare const GUITAR_DIAGRAM_TOP_PADDING = 4;
+export declare const GUITAR_DIAGRAM_BOTTOM_PADDING = 1;
+export declare const GUITAR_NUT_THICKNESS = 4;
+export declare const GUITAR_NUT_X_OFFSET = 1;
+export declare const GUITAR_NUT_SPACE_ABOVE: number;
+export declare const GUITAR_FONT_BASE = 16;
+export declare const GUITAR_FONT_SMALL = 12;
+export declare const GUITAR_LABEL_HEIGHT = 16;
+export declare const GUITAR_FRET_LABEL_OFFSET_X = 2;

package/dist/helpers/guitarHelpers.d.ts

@@ -0,0 +1,5 @@
+import { GuitarStringState } from '../types';
+export declare function createStateStrings(frets: string[], fingers: string[]): GuitarStringState[];
+export declare function calculateStartFret(fretParts: string[], fretCount: number): number;
+export declare function parseFretsEntry(frets: string): string[];
+export declare function parseFingersEntry(fingers: string): string[];

package/dist/index.d.ts

@@ -1,7 +1,10 @@
 export { default as MusicStaff } from './classes/MusicStaff';
 export { default as RhythmStaff } from './classes/RhythmStaff';
 export { default as ScrollingStaff } from './classes/ScrollingStaff';
+export { default as GuitarChord } from './classes/GuitarChord';
 export type { MusicStaffOptions } from './classes/MusicStaff';
 export type { RhythmStaffOptions } from './classes/RhythmStaff';
 export type { ScrollingStaffOptions } from './classes/ScrollingStaff';
+export type { GuitarChordOptions } from './classes/GuitarChord';
 export type { StaffTypes } from './types';
+export type { GuitarChordDrawOptions, GuitarBarreDef } from './types';

package/dist/types.d.ts

@@ -14,3 +14,18 @@ export type KeySignatureDef = {
     type: AccidentalType;
     count: number;
 };
+export type GuitarStringState = {
+    fret: string;
+    finger: string;
+};
+export type GuitarBarreDef = {
+    fret: number;
+    fromString: number;
+    toString: number;
+    finger?: number;
+};
+export type GuitarChordDrawOptions = {
+    startFret?: number;
+    label?: string;
+    barres?: GuitarBarreDef[];
+};