@tspro/web-music-score 2.0.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [3.0.0] - 2025-08-31
+Major update and brought some important changes.
+### ** Breaking Changes **
+- Removed old way of creating scores using MDocument, MMeasure, etc. Use DocumentBuilder instead.
+- Removed DocumentOptions. Replaced using functions addScoreConfiguration() and setMeasuresPerRow() in DocumentBuilder.
+- Tie and slur removed from NoteOptions. Use addConnective() in DocumentBuilder.
+
+## Added
+- Score configuration with multiple staves and tabs per row.
+- Connective.Slide.
+- Draw Connectives in tabs.
+
+## Changed
+- Lots of undocumented fixes, changes and improvements.
+
 ## [2.0.0] - 2025-07-28
 Major update and brought many changes.
 ### ** Breaking Changes **

package/README.md

@@ -21,6 +21,15 @@ This is a work in progress project. Expect changes, bugs, or unexpected behavior
 
 Enough changes until next major update!
 
+## Version 3 Update
+
+**Breaking:** Version 3 is another major update and brought some important changes.
+
+* Support score configuration with multiple notation lines (combination of staves and tabs).
+* Introduced DocumentBuilder to create scores, removed old way.
+* DocumentOptions functionality is replaced using functions addScoreConfiguration() and setMeasuresPerRow() in DocumentBuilder.
+* Add ties, slurs and slides using addConnective() in DocumentBuilder. Tie and span options removed from NoteOptions.
+
 ## Installation
 
 ```sh
@@ -62,13 +71,13 @@ It declares global variable `WebMusicScore` that contains `Core`, `Audio`, `Theo
 and `Pieces` as corresponding subpath modules (excluding `react-ui` and `audio-cg`).
 
 ```html
-<script src="https://unpkg.com/@tspro/web-music-score@2.0.0"></script>
+<script src="https://unpkg.com/@tspro/web-music-score@3"></script>
+<script src="https://unpkg.com/@tspro/web-music-score@3.0.0"></script>
+<script src="https://unpkg.com/@tspro/web-music-score@3.0.0/dist/iife/index.global.js"></script>
 
 <!--
-    It is recommended to use version number (e.g. @2.0.0, at least use @2). This way
-    if there is breaking change between versions your code does not stop working.
-
-    TODO: Add direct link to bundle.
+    Use one of above. It is recommended to use version number (e.g. @3.0.0 or at least @3).
+    This way if there is breaking change between versions your code does not stop working.
 -->
 
 <script>
@@ -79,66 +88,119 @@ and `Pieces` as corresponding subpath modules (excluding `react-ui` and `audio-c
 
 ## API
 
-Typedoc API reference is available [here](https://pahkasoft.github.io). It has no comments but
-is mostly self explanatory and gives idea of full API.
+Typedoc API reference is available [here](https://pahkasoft.github.io).
+It is not commented but is mostly self explanatory and gives idea of full API.
 
 Following is the main interface explained.
 
-### Create Document
+### Create DocumentBuilder
+
+Documents are created using `DocumentBuilder`.
 
 ```js
-let doc = new Score.MDocument(staffPreset: Score.StaffPreset, options: Score.DocumentOptions);
+let builder = new Score.DocumentBuilder();
+
+// Here build document, e.g.
+builder
+    .addMEasure()
+    .addNote(0, "C3", Theory.NoteLength.Quarter)
+    // etc.
+
+// When ready, get document:
+let doc = builder.getDocument();
 ```
+
+### Set Score Configuration
+Setting score configuration takes place in first measure of next row.
+
+#### Using preset values
+```js
+builder.setScoreConfiguration(staffPreset: Score.StaffPreset);
+```
+
 `staffPreset` can be:
 * `Score.StaffPreset.Treble`: Staff with treble (G-) clef.
 * `Score.StaffPreset.Bass`: Staff with bass (F-) clef.
 * `Score.StaffPreset.Grand`: Both treble and bas staves.
-* `Score.StaffPreset.GuitarTreble`: `Treble` but one octave lower.
+* `Score.StaffPreset.GuitarTreble`: Same as `Treble` but one octave down.
 * `Score.StaffPreset.GuitarTab`: Guitar tab only.
 * `Score.StaffPreset.GuitarCombined`: Treble and tab for guitar.
 
-Second argument is optional `DocumentOptions`:
-```ts
-DocumentOptions = { measuresPerRow?: number, tuning?: string }
+```js
+// Example
+builder.setScoreConfiguration(Score.StaffPreset.GuitarCombined);
 ```
 
-Default tuning is `"Standard"`. `Theory.TuningNameList` is array of available tuning names.
+#### Using configuration objects
+```js
+builder.setScoreConfiguration(config: Score.StaffConfig | Score.TabConfig);
+builder.setScoreConfiguration(config: (Score.StaffConfig | Score.TabConfig)[]);
+```
+
+`config` is `StaffConfig`, `TabConfig` or array of combination.
+
+`StaffConfig` contains following properties:
+* `type`: "staff"
+* `clef`: Clef can be `Score.Clef.G` or `Score.Clef.F`.
+* `isOctaveDown`: boolean (optional)
+* `minNote`: string (optional), minimum note allowed in staff.
+* `maxNote`: string (optional), maximum note allowed in staff.
+* `voiceIds`: number[] (optional), array of voice ids are visible on this staff.
+* `isGrand`: boolean (optional), use this to create grand staff.
+
+`TabConfig` contains following properties:
+* `type`: "tab"
+* `tuning`: string | string[] (optional), tuning name or array of 6 note names for tuning.
+* `voiceIds`: number[] (optional), array of voice ids are visible on this tab.
 
 ```js
-// Example
-let doc = new Score.MDocument(Score.StaffPreset.GuitarCombined, { tuning: "Drop D" });
+// Example: Staff and tab for guitar
+builder.setScoreConfiguration([
+    { type: "staff", clef: Score.Clef.G, isOctaveDown: true },
+    { type: "tab", tuning: "Drop D" }
+]);
+
+// Example: Grand staff
+builder.setScoreConfiguration([
+    { type: "staff", clef: Score.Clef.G, isGrand: true },
+    { type: "staff", clef: Score.Clef.F, isGrand: true }
+]);
 ```
 
-### Set Header
+### Set Automatic Measures Per Row
+```ts
+builder.setMesuresPerRow(measuresPerRow: number)
+```
 
+`measuresPerRow` can be integer >= 1, or Infinity (default).
+
+### Set Header
 ```js
-doc.setHeader(title?: string, composer?: string, arranger?: string);
+builder.setHeader(title?: string, composer?: string, arranger?: string);
 
 // Example
-doc.setHeader("Demo Song");
+builder.setHeader("Demo Song");
 ```
 
 ### Add Measure
-
 ```js
-let m = doc.addMeasure();
+builder.addMeasure();
 ```
 
 ### End Row
-
 ```js
-m.endRow();
+builder.endRow();
 ```
 
-Manually induce row change. Next measure that is added will start new row.
+Manually induce row change. Next measure that is added will begin new row.
 
-### Set Signature
+### Set Key Signature
 
 ```js
-m.setKeySignature(tonic: string, scaleType: Theory.ScaleType);
+builder.setKeySignature(tonic: string, scaleType: Theory.ScaleType);
 
 // Example: Am
-m.setKeySignature("A", Theory.ScaleType.Aeolian);
+builder.setKeySignature("A", Theory.ScaleType.Aeolian);
 ```
 
 `tonic` is scale tonic/root note, e.g. "C" (in "C Major").
@@ -160,11 +222,12 @@ m.setKeySignature("A", Theory.ScaleType.Aeolian);
  - `Theory.ScaleType.MinorHexatonicBlues`
  - `Theory.ScaleType.HeptatonicBlues`
 
+### Set Time Signature
 ```js
-m.setTimeSignature(timeSignature: string);
+builder.setTimeSignature(timeSignature: string);
 
 // Example
-m.setTimeSignature("3/4");
+builder.setTimeSignature("3/4");
 ```
 
 timeSignature can be:
@@ -174,11 +237,12 @@ timeSignature can be:
 - `"6/8"`
 - `"9/8"`
 
+### Set Tempo
 ```js
-m.setTempo(beatsPerMinute: number, beatLength?: Theory.NoteLength, dotted?: boolean);
+builder.setTempo(beatsPerMinute: number, beatLength?: Theory.NoteLength, dotted?: boolean);
 
 // Example
-m.setTempo(100, Theory.NoteLength.Quarter);
+builder.setTempo(100, Theory.NoteLength.Quarter);
 ```
 
 `beatsPerMinute` is self explanatory.
@@ -190,12 +254,12 @@ m.setTempo(100, Theory.NoteLength.Quarter);
 ### Add Note Or Chord
 
 ```js
-m.addNote(voiceId: number, note: string, noteLength: Theory.NoteLength, noteOptions?: Score.NoteOptions);
-m.addChord(voiceId: number, notes: string[], noteLength: Theory.NoteLength, noteOptions?: Score.NoteOptions);
+builder.addNote(voiceId: number, note: string, noteLength: Theory.NoteLength, noteOptions?: Score.NoteOptions);
+builder.addChord(voiceId: number, notes: string[], noteLength: Theory.NoteLength, noteOptions?: Score.NoteOptions);
 
 // Examples
-m.addNote(0, "C4", Theory.NoteLength.Half, { dotted: true });
-m.addChord(1, ["C3", "E3", "G3"], Theory.NoteLength.Whole, { arpeggio: Score.Arpeggio.Down });
+builder.addNote(0, "C4", Theory.NoteLength.Half, { dotted: true });
+builder.addChord(1, ["C3", "E3", "G3"], Theory.NoteLength.Whole, { arpeggio: Score.Arpeggio.Down });
 ```
 
 `voiceId` can be `0`, `1`, `2` or `3`.
@@ -222,20 +286,16 @@ m.addChord(1, ["C3", "E3", "G3"], Theory.NoteLength.Whole, { arpeggio: Score.Arp
 | arpeggio    | `Score.Arpeggio.Up/Down` \| `boolean`  | Play column in arpeggio. |
 | staccato    | `boolean`               | Play column in staccato. |
 | diamond     | `boolean`               | Diamond shaped note head. |
-| tieSpan     | `number` \| `TieType.Stub/ToMeasureEnd` | How many notes this tie spans. |
-| tieAnchor   | `Score.NoteAnchor.Auto/Above/Center/Below/StemTip` | Tie attach point. |
-| slurSpan    | `number`                | How many notes this slur spans. |
-| slurAnchor  | `Score.NoteAnchor.Auto/Above/Center/Below/StemTip` | Slur attach point. |
 | triplet     | `boolean`               | Set this note part of triplet. |
 | string      | `number` \| `number[]`  | String number for guitar tab. Array of string numbers for chord. |
 
 ### Add Rest
 
 ```js    
-m.addRest(voideId: number, restLength: Theory.NoteLength, restOptions?: Score.RestOptions);
+builder.addRest(voideId: number, restLength: Theory.NoteLength, restOptions?: Score.RestOptions);
 
 // Example
-m.addRest(0, Theory.NoteLength.Sixteenth);
+builder.addRest(0, Theory.NoteLength.Sixteenth);
 ```
 
  `voiceId` can be `0`, `1`, `2` or `3`.
@@ -254,27 +314,47 @@ m.addRest(0, Theory.NoteLength.Sixteenth);
 ### Add Fermata
 
 ```js
-m.addFermata(fermata?: Score.Fermata);
+builder.addFermata(fermata?: Score.Fermata);
 
 // Example
-m.addFermata(Score.Fermata.AtMeasureEnd);
+builder.addFermata(Score.Fermata.AtMeasureEnd);
 ```
 
 `fermata` is typeof `Score.Fermata` and can be:
 - `Score.Fermata.AtNote`: Adds fermata anchored to previously added note, chord or rest.
 - `Score.Fermata.AtMeasureEnd`: Adds fermata at the end of measure.
 
+### Add Connective (tie, slur)
+
+```js
+// Add tie
+builder.addConnective(connective: Score.Connetive.Tie, span?: Score.ConnectiveSpan, noteAnchor?: Score.NoteAnchor);
+
+// Add slur
+builder.addConnective(connective: Score.Connetive.Slur, span?: Score.ConnectiveSpan, noteAnchor?: Score.NoteAnchor);
+
+// Add slide
+builder.addConnective(connective: Score.Connetive.Slide, noteAnchor?: Score.NoteAnchor);
+```
+
+- `span` describes how many notes the connective is across.
+  It is integer >= 2 (for tie it can be also `Score.TieType.Stub|ToMeasureEnd`).
+  Default value is 2.
+- `noteAnchor` describes the attach point of connective to note.
+  It can be `Score.NoteAnchor.Auto|Above|Center|Below|StemTip`.
+  Default value is `Score.NoteAnchor.Auto`.
+
 ### Add Navigation
 
 Add navigational element to measure.
 
 ```js
-m.addNavigation(navigation: Score.Navigation, ...args?);
+builder.addNavigation(navigation: Score.Navigation, ...args?);
 
 // Examples
-m.addNavigation(Score.Navigation.StartRepeat);
-m.addNavigation(Score.Navigation.EndRepeat, 3);
-m.addNavigation(Score.Navigation.Ending, 1, 2);
+builder.addNavigation(Score.Navigation.StartRepeat);
+builder.addNavigation(Score.Navigation.EndRepeat, 3);
+builder.addNavigation(Score.Navigation.Ending, 1, 2);
 ```
 
 `navigation` can be:
@@ -299,10 +379,10 @@ m.addNavigation(Score.Navigation.Ending, 1, 2);
 Add text label anchored to previously added note, chord or rest.
 
 ```js
-m.addLabel(label: Score.Label, text: string);
+builder.addLabel(label: Score.Label, text: string);
 
 // Example
-m.addLabel(Score.Label.Chord, "Am);
+builder.addLabel(Score.Label.Chord, "Am);
 ```
 
 `label` can be:
@@ -314,10 +394,10 @@ m.addLabel(Score.Label.Chord, "Am);
 Add annotation text anchored to previously added note, chord or rest.
 
 ```js
-m.addAnnotation(annotation: Score.Annotation, text: string);
+builder.addAnnotation(annotation: Score.Annotation, text: string);
 
 // Example
-m.addAnnotation(Score.Annotation.Tempo, "accel.");
+builder.addAnnotation(Score.Annotation.Tempo, "accel.");
 ```
 
 `annotation` can be:
@@ -329,10 +409,10 @@ m.addAnnotation(Score.Annotation.Tempo, "accel.");
 Adds extension line to element, for example to previously added annotation.
 
 ```js
-m.addExtension(extensionLength: number, visible?: boolean);
+builder.addExtension(extensionLength: number, visible?: boolean);
 
 // Example
-m.addAnnotation(Score.Annotation.Tempo, "accel.").addExtension(Theory.NoteLength.Whole * 2, true);
+builder.addAnnotation(Score.Annotation.Tempo, "accel.").addExtension(Theory.NoteLength.Whole * 2, true);
 ```
 
 `extensionLength` is `number` but `Theory.NoteLength` values can be used as number and multiplied to set desired extension length.
@@ -342,31 +422,32 @@ m.addAnnotation(Score.Annotation.Tempo, "accel.").addExtension(Theory.NoteLength
 ### Guitar Tab
 
 This library has preliminary guitar tabs rendering. 
-Create document with `Score.StaffPreset.GuitarTab` or `Score.StaffPreset.GuitarCombined`, and specify tuning (defaults to `"Standard"` if omitted).
-
-```js
-let doc = new Score.MDocument(Score.StaffPreset.GuitarCombined, { tuning: "Standard" });
-```
+Create document with `Score.StaffPreset.GuitarTab` or `Score.StaffPreset.GuitarCombined`, or set score configuration with TabConfig.
 
 Add notes with `{ string: number | number[] }` to specify which string the fret number is rendered in guitar tab.
 
 ```js
 // Single note
-m.addNote(0, "G3", Theory.NoteLength.Eighth, { string: 3 });
+builder.addNote(0, "G3", Theory.NoteLength.Eighth, { string: 3 });
 
 // Multi note
-m.addChord(0, ["E4", "C3"], Theory.NoteLength.Eighth, { string: [1, 5] });
+builder.addChord(0, ["E4", "C3"], Theory.NoteLength.Eighth, { string: [1, 5] });
 ```
 
 ### Queueing
 
-Adding stuff to measures can be queued like this:
+`DocumentBuilder` operations can be queued.
 
 ```js
-doc.addMeasure()
+let doc = new Score.DocumentBuilder()
+    .addScoreConfiguration({ type: "staff", clef: Score.Clef.G, isOctavewDown: true })
+    .setMeasuresPerRow(4)
+    .addMeasure()
     .addNote(1, "C3", Theory.NoteLength.Quarter)
     .addChord(1, ["C3", "E3", "G3"], Theory.NoteLength.Quarter).addLabel(Score.Label.Chord, "C")
-    .addRest(1, Theory.NoteLength.Quarter);
+    .addRest(1, Theory.NoteLength.Quarter)
+    // etc.
+    .getDEocument();
 ```
 
 ### Beams

package/dist/audio/index.d.mts

@@ -1,4 +1,4 @@
-import { N as Note } from '../note-CraqEy8x.mjs';
+import { N as Note } from '../note-B5ZtlHc8.mjs';
 
 /** @public */
 interface Instrument {

package/dist/audio/index.js

@@ -1,4 +1,4 @@
-/* WebMusicScore v2.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v3.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;

package/dist/audio/index.mjs

@@ -1,7 +1,7 @@
-/* WebMusicScore v2.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v3.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 import {
   __publicField
-} from "../chunk-2EPWQZKJ.mjs";
+} from "../chunk-ZWFAOHYM.mjs";
 
 // src/audio/index.ts
 import { Note, PitchNotation, SymbolSet } from "@tspro/web-music-score/theory";

package/dist/audio-cg/index.js

@@ -1,4 +1,4 @@
-/* WebMusicScore v2.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v3.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 "use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;

package/dist/audio-cg/index.mjs

@@ -1,7 +1,7 @@
-/* WebMusicScore v2.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v3.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 import {
   __publicField
-} from "../chunk-2EPWQZKJ.mjs";
+} from "../chunk-ZWFAOHYM.mjs";
 
 // src/audio-cg/index.ts
 import * as Tone from "tone";

package/dist/{chunk-2EPWQZKJ.mjs → chunk-ZWFAOHYM.mjs}

@@ -1,4 +1,4 @@
-/* WebMusicScore v2.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v3.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
@@ -6,4 +6,4 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
 export {
   __publicField
 };
-//# sourceMappingURL=chunk-2EPWQZKJ.mjs.map
+//# sourceMappingURL=chunk-ZWFAOHYM.mjs.map

package/dist/core/index.js

@@ -1,4 +1,4 @@
-/* WebMusicScore v2.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v3.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -61,7 +61,7 @@ function init() {
     return;
   }
   initialized = true;
-  console.log("%cWebMusicScore v2.0.0 (cjs) initialized.", "background: black; color: white; padding: 2px;");
+  console.log("%cWebMusicScore v3.0.0 (cjs) initialized.", "background: black; color: white; padding: 2px;");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/core/index.mjs

@@ -1,7 +1,7 @@
-/* WebMusicScore v2.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
+/* WebMusicScore v3.0.0 | (c) 2023 PahkaSoft | MIT License | Includes: Tone.js (MIT License) */
 import {
   __publicField
-} from "../chunk-2EPWQZKJ.mjs";
+} from "../chunk-ZWFAOHYM.mjs";
 
 // src/core/error.ts
 var MusicErrorType = /* @__PURE__ */ ((MusicErrorType2) => {
@@ -35,7 +35,7 @@ function init() {
     return;
   }
   initialized = true;
-  console.log("%cWebMusicScore v2.0.0 (esm) initialized.", "background: black; color: white; padding: 2px;");
+  console.log("%cWebMusicScore v3.0.0 (esm) initialized.", "background: black; color: white; padding: 2px;");
 }
 export {
   MusicError,

package/dist/{guitar-kbJYu3Am.d.mts → guitar-zASF7B1g.d.mts}

@@ -1,4 +1,4 @@
-import { N as Note } from './note-CraqEy8x.mjs';
+import { N as Note } from './note-B5ZtlHc8.mjs';
 
 /** @public */
 declare enum Handedness {