vector-score 1.2.0 → 1.3.0

package/README.md

@@ -1,4 +1,6 @@
-![Alt Text](https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/vector-score-icon.svg)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/vector-score-icon.svg" alt="Vector Score Logo" />
+</p>
 
 # Vector Score
 ![NPM Version](https://img.shields.io/npm/v/vector-score)
@@ -7,7 +9,8 @@
 
 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.
 
-<br/>
+[**See CSS class styling guide**](#Notes)
+
 
 ## Features
 
@@ -15,7 +18,7 @@ A lightweight, SVG-based TypeScript library for rendering simple musical notatio
 * 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**](#Standard-Music-Staff) 
+* [**Go to Music Staffs**](#Grand-Staff) 
 
 ### Render and Display Guitar Chords
 * Write explicitly which string, fret, and optionally finger to display on the diagram.
@@ -27,23 +30,6 @@ A lightweight, SVG-based TypeScript library for rendering simple musical notatio
 * 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)
 
-<br />
-
-## Notes
-
-* Main targeting class for css is 'vs-svg-renderer-parent'
-  * Could be useful if needing to add in specific colors or styling to any SVG element rendered.
-
-
-<br />
-
-## Installation
-
-```bash
-npm i vector-score
-```
-
-<br />
 
 ## Usage
 
@@ -67,24 +53,96 @@ const staff = new MusicStaff(container, {
   width: 400,
   scale: 1.2,
   spaceBelow: 1,
-  keySignature: "Bb"
+  keySignature: "Bb",
 });
 
 // Draw a C Minor scale (quarter notes)
-// Format: NoteName + Accidental(optional) + Octave + Duration
 staff.drawNote(['C4q', 'D4q', 'Eb4q', 'F4q', 'G4q', 'Ab4q', 'Bb4q', 'C5q']);
+staff.justifyNotes();
+```
 
-// Draw a C Chord
-staff.drawChord(['C4w', 'E4w', 'G4w']);
 
-// Evenly space all notes on the staff
-staff.justifyNotes();
+## Notes
+
+### CSS Classes & Theming
+The GuitarChord diagram uses CSS classes for styling. All elements that can be targeted for theming are prefixed with `.vs-`.
+
+#### General SVG Classes
+* `svg.vs-svg-renderer-root`: The root SVG element.
+* `g.vs-svg-renderer-parent`: The main parent group element containing all drawn elements.
+
+#### Staff Theming
+* `.vs-staff-layer`: The layer containing the staff lines, clef, and time signature.
+* `.vs-notes-layer`: The layer containing all notes, chords, stems, and rests.
+* `.vs-ui-layer`: Contains UI elements like the RhythmStaff beat tracker.
+  * `vs-rhythm-current-beat`: Targets the highlighting rectangle for the current beat in the RhythmStaff. Also possible to add in transition animation on `x` property.
+
+#### Guitar Chord Theming
+The `GuitarChord` class is entirely styled via CSS. Here are the specific layout targets:
+* **Text & Labels:**
+  * `.vs-guitar-text`: Base class for all text elements in the diagram.
+  * `.vs-guitar-diagram-label`: The chord name label above the diagram.
+  * `.vs-guitar-fret-label`: The fret number indicator (e.g., "5fr").
+  * `.vs-guitar-fret-text`: The finger numbers inside the dots and barres.
+* **Grid Lines:**
+  * `.vs-guitar-group-fret-lines`: The horizontal fret lines and the top nut.
+  * `.vs-guitar-group-string-lines`: The vertical string lines.
+* **Dots & Markers:**
+  * `.vs-guitar-fret-muted`: The 'X' markers for muted strings above the nut.
+  * `.vs-guitar-fret-open`: The 'O' outline markers for open strings above the nut.
+  * `.vs-guitar-fret-dot`: The parent group for fretted dots.
+  * `.vs-guitar-fret-circle`: The actual SVG circle shape for a fretted note.
+* **Barres:**
+  * `.vs-guitar-group-barre`: The group containing the elements for the barre line.
+  * `.vs-guitar-barre`: The rectangle element spanning across strings for barre chords.
+
+#### Scrolling Staff Theming
+* `g.vs-scrolling-notes-layer > g`: Targets the scrolling staff's notes, where a transition property can be added for smooth animation.
+
+
+**Example: Custom Staff Theme Implementation**
+```css
+  /* Adds background color to root SVG element */
+  svg.vs-svg-renderer-root {
+    background-color: white;
+  }
+  
+  /* Set base staff color */
+  .vs-staff-layer,
+  .vs-notes-layer {
+    color: #d4d4d8;
+  }
+
+  /* Animate current beat rect UI  */
+  .vs-rhythm-current-beat {
+    transition: x 0.2s ease-in
+  }
 ```
 
-### Resulting Staff
-![Alt Text](https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/MusicStaffTrebleResult.svg)
+**Example: Custom Guitar Chord Theme Implementation**
+```css
+/* Set base grid colors */
+.vs-guitar-group-fret-lines,
+.vs-guitar-group-string-lines {
+  color: #d4d4d8;
+}
+
+/* Format the text labels */
+.vs-guitar-text { fill: #1a1827; }
+.vs-guitar-fret-text { fill: #ffffff; }
+
+/* Style the open/muted markers */
+.vs-guitar-fret-muted { color: #dc2626; }
+.vs-guitar-fret-open { color: #3b82f6; }
+
+/* Apply alternating fret dot colors */
+.vs-guitar-fret-dot { color: oklch(50% 0.05 220); }
 
-<br/>
+.vs-guitar-fret-dot:nth-child(odd of .vs-guitar-fret-dot) { color: oklch(60% 0.25 200); }
+
+/* Style the barre */
+.vs-guitar-barre { fill: #1e40af; }
+```
 
 ## Grand Staff
 
@@ -110,7 +168,6 @@ grandStaff.drawChord(["G3w", "C4w", "E4w"]);
 ### Resulting Staff
 ![Alt Text](https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/MusicStaffGrandResult.svg)
 
-<br/>
 
 ## Guitar Chords
 
@@ -124,11 +181,10 @@ import { GuitarChord } from 'vector-score';
 const grandStaff = new GuitarChord(container, {
   fretCount: 5,
   stringCount: 6,
-  stringLabels: ["E", "A", "D", "G", "B", "E"],
-  width: 300,
+  stringLabels: ["E", "A", "D", "G", "B", "E"], // Labels under each string, in order
+  inlineChordsAmount: 4, // Choose how many chords are in a single line
+  centerChords: true, // Centers the diagrams inside their rows
   scale: 1,
-  color: "var(--font-color)",
-  backgroundColor: "var(--bg-color)"
 });
 
 // C chord
@@ -137,9 +193,9 @@ guitarChordsSection.addChord("x32010", "032010", {
 });
 
 // Bbmaj7 Barre Chord (Automatically calculates the starting fret and barre positioning)
-const frets = "x13231";
-const fingers = "013241";
-const barres = guitarChordsSection.determineBarreOptions(frets, fingers, [1]);
+const frets = "687766";
+const fingers = "142311";
+const barres = guitarChordsSection.determineBarreOptions(frets, fingers, [6]);
 
 guitarChordsSection.addChord(frets, fingers, {
   label: "Bbmaj7",
@@ -149,7 +205,6 @@ guitarChordsSection.addChord(frets, fingers, {
 ### Result
 ![Alt Text](https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/GuitarChordsResult.svg)
 
-<br />
 
 ## Rhythm Staff
 
@@ -180,7 +235,6 @@ rhythm.incrementCurrentBeatUI();
 ### Resulting Staff
 ![Alt Text](https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/RhythmStaffResult.svg)
 
-<br />
 
 ## Scrolling Staff
 
@@ -225,7 +279,6 @@ scrollingStaff.queueNotes([
 ### Resulting Staff
 ![Alt Text](https://raw.githubusercontent.com/DrakeB1234/VectorScore/master/public/ScrollingStaffResult.webp)
 
-<br />
 
 ## Note String Syntax
 
@@ -247,7 +300,6 @@ 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
 
@@ -274,7 +326,6 @@ Barre lines can be added dynamically using the built-in helper method, `determin
 * 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
 
@@ -290,7 +341,6 @@ Barre lines can be added dynamically using the built-in helper method, `determin
 | `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
 
@@ -304,7 +354,6 @@ Barre lines can be added dynamically using the built-in helper method, `determin
 | `destroy()` | Destroys internal arrays and elements. |
 
 
-<br/>
 
 ### RhythmStaff Class
 
@@ -318,7 +367,6 @@ Barre lines can be added dynamically using the built-in helper method, `determin
 | `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
 
@@ -329,7 +377,6 @@ Barre lines can be added dynamically using the built-in helper method, `determin
 | `clearAllNote()` | Clears all notes on the staff |
 | `destroy()` | Destroys internal arrays and elements | 
 
-<br />
 
 ## Configuration Options
 
@@ -341,17 +388,18 @@ Barre lines can be added dynamically using the built-in helper method, `determin
 * `spaceAbove`: Padding units above the staff (in staff line spaces).
 * `spaceBelow`: Padding units below the staff (in staff line spaces).
 * `noteStartX`: Position where notes start to draw.
-* `staffColor`: CSS color string for lines and notes.
-* `staffBackgroundColor`: CSS color string for background.
+* `svgAutoFill`: Sets inline styles on root SVG element to allow for screen scaling (default: true).
+
 
 ### 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.
-* `width`: Total width of the SVG in pixels.
+* `inlineChordsAmount`: Max amount of chords to display on a single line (default: 2).
+* `centerChords`: Boolean to center the chord diagrams on their respective rows (default: true).
 * `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).
+* `svgAutoFill`: Sets inline styles on root SVG element to allow for screen scaling (default: true).
 
 ### RhythmStaffOptions
 * `topNumber`: The top number of the time signature (e.g., 4 for 4/4 time).
@@ -367,6 +415,7 @@ Barre lines can be added dynamically using the built-in helper method, `determin
 * `staffColor`: CSS color string for lines and notes.
 * `staffBackgroundColor`: CSS color string for background.
 * `currentBeatUIColor`: CSS color string for current beat UI indicator.
+* `svgAutoFill`: Sets inline styles on root SVG element to allow for screen scaling (default: true).
 
 ### ScrollingStaffOptions
 * `width`: Total width of the SVG in pixels.
@@ -378,3 +427,4 @@ Barre lines can be added dynamically using the built-in helper method, `determin
 * `staffColor`: CSS color string for lines and notes.
 * `staffBackgroundColor`: CSS color string for background.
 * `onNotesOut`: Callback function for when there are no more notes on the staff to advance.
+* `svgAutoFill`: Sets inline styles on root SVG element to allow for screen scaling (default: true).

package/dist/classes/GuitarChord.d.ts

@@ -1,12 +1,13 @@
 import { GuitarBarreDef, GuitarChordDrawOptions } from '../types';
 export type GuitarChordOptions = {
     width?: number;
+    inlineChordsAmount?: number;
+    centerChords?: boolean;
     scale?: number;
     stringCount?: number;
     fretCount?: number;
     stringLabels?: string[];
-    color?: string;
-    backgroundColor?: string;
+    svgAutoFill?: boolean;
 };
 export default class GuitarChord {
     private svgRendererInstance;
@@ -26,7 +27,8 @@ export default class GuitarChord {
      * All config options are in the type GuitarChordOptions.
     */
     constructor(rootElementCtx: HTMLElement, options?: GuitarChordOptions);
-    private drawStringDots;
+    private getDotsToHide;
+    private drawFretDots;
     private drawStringLabels;
     private drawBarre;
     private renderChordDiagram;

package/dist/classes/MusicStaff.d.ts

@@ -7,8 +7,7 @@ export type MusicStaffOptions = {
     keySignature?: string;
     spaceAbove?: number;
     spaceBelow?: number;
-    staffColor?: string;
-    staffBackgroundColor?: string;
+    svgAutoFill?: boolean;
 };
 export default class MusicStaff {
     private svgRendererInstance;

package/dist/classes/RhythmStaff.d.ts

@@ -5,9 +5,7 @@ export type RhythmStaffOptions = {
     barsCount?: number;
     spaceAbove?: number;
     spaceBelow?: number;
-    staffColor?: string;
-    staffBackgroundColor?: string;
-    currentBeatUIColor?: string;
+    svgAutoFill?: boolean;
 };
 export default class RhythmStaff {
     private rendererInstance;

package/dist/classes/SVGRenderer.d.ts

@@ -4,55 +4,69 @@ type SVGRendererOptions = {
     width: number;
     height: number;
     scale: number;
-    staffColor: string;
-    staffBackgroundColor: string;
     useGlyphs: GlyphNames[];
+    svgAutoFill: boolean;
 };
-type LayerNames = 'staff' | 'notes' | 'ui';
 type DrawGlyphOptions = {
     yOffset?: number;
     xOffset?: number;
 };
+type DrawLineOptions = {
+    strokeWidth?: number;
+    classes?: string | string[];
+};
 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";
+    baseline?: "central";
     fill?: string;
     fontWeight?: string;
+    classes?: string | string[];
 };
 export default class SVGRenderer {
     private rootElementRef;
     private svgElementRef;
     private parentGroupContainer;
-    private musicStaffLayer;
-    private musicNotesLayer;
-    private musicUILayer;
+    private layers;
     private width;
     private scale;
     private totalYOffset;
     private totalHeight;
     constructor(rootElementCtx: HTMLElement, options: SVGRendererOptions);
     private makeGlyphDefs;
+    private addNamespacedClassesToElement;
+    /**
+     * Creates a layer that is appended to parent element.
+     * layerName arg is the key that is appended to the internal list of layers, which
+     * can be used in method getLayer() arg. Best to call on construction.
+     *
+     * @param {string} layerName
+     * @returns {SVGGElement}
+     */
+    createLayer(layerName: string): SVGGElement;
+    getLayer(layerName: string): SVGGElement | null;
     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;
     get parentGroupElement(): SVGElement;
-    drawLine(x1: number, y1: number, x2: number, y2: number, parent: SVGElement): void;
+    drawLine(x1: number, y1: number, x2: number, y2: number, parent: SVGElement, options?: DrawLineOptions): 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;

package/dist/classes/ScrollingStaff.d.ts

@@ -6,8 +6,7 @@ export type ScrollingStaffOptions = {
     staffType?: StaffTypes;
     spaceAbove?: number;
     spaceBelow?: number;
-    staffColor?: string;
-    staffBackgroundColor?: string;
+    svgAutoFill?: boolean;
     onNotesOut?: () => void;
 };
 export type NoteSequence = (string | string[])[];

package/dist/constants.d.ts

@@ -25,14 +25,14 @@ 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 = 40;
-export declare const GUITAR_DIAGRAM_V_SPACING = 16;
+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_LABEL_FONT_SIZE = 16;
-export declare const GUITAR_FINGER_FONT_SIZE = 14;
-export declare const GUITAR_FRET_LABEL_FONT_SIZE = 14;
+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: number;
+export declare const GUITAR_FRET_LABEL_OFFSET_X = 2;