@barmark/score 0.0.0 → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +96 -0
- package/LICENSE +21 -0
- package/README.md +144 -1
- package/dist/element.d.ts +13 -0
- package/dist/element.js +435 -0
- package/dist/engine.d.ts +43 -0
- package/dist/engine.js +54 -0
- package/dist/engrave.d.ts +41 -0
- package/dist/engrave.js +78 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.js +3 -0
- package/dist/markup.d.ts +25 -0
- package/dist/markup.js +242 -0
- package/dist/server.d.ts +14 -0
- package/dist/server.js +26 -0
- package/dist/shell.d.ts +9 -0
- package/dist/shell.js +16 -0
- package/dist/switch.d.ts +18 -0
- package/dist/switch.js +32 -0
- package/dist/worker.d.ts +8 -0
- package/dist/worker.js +52 -0
- package/package.json +59 -5
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@barmark/score` are recorded here. The format
|
|
4
|
+
follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
|
|
5
|
+
package uses [semantic versioning](https://semver.org/).
|
|
6
|
+
|
|
7
|
+
## [Unreleased]
|
|
8
|
+
|
|
9
|
+
## [0.1.1] - 2026-11-09
|
|
10
|
+
|
|
11
|
+
Requires `@barmark/musicxml` 0.7.2.
|
|
12
|
+
|
|
13
|
+
### Fixed
|
|
14
|
+
|
|
15
|
+
- **A chord symbol is drawn as the chart spells it.** Verovio 6.4 appends
|
|
16
|
+
every `<degree>` to the kind text, `print-object="no"` or not, so
|
|
17
|
+
`D7sus4` was drawn `D7sus4(7)` and `G5(7)` as `G5(7)(no3)`. The score
|
|
18
|
+
now drops a degree that is not printed before Verovio reads the
|
|
19
|
+
MusicXML (with `@barmark/musicxml`'s next release, which hides a degree
|
|
20
|
+
its kind text already spells). `Engraved.xml` is the export unchanged.
|
|
21
|
+
The pass is linear (a single `indexOf` scan, no backtracking regex), so a
|
|
22
|
+
hostile MusicXML given to `engraveXml` cannot stall it.
|
|
23
|
+
- **The Grid / Score switch follows the element's `theme`.** It sits
|
|
24
|
+
outside the grid's themed `.bm-chart`, and render's `:host{all:initial}`
|
|
25
|
+
reset its colour and font, so on a dark page it was black text in the
|
|
26
|
+
browser's serif. It now takes render's ink and rule for `theme="dark"`,
|
|
27
|
+
for `auto` (or no theme) under a dark colour scheme, and light ones
|
|
28
|
+
otherwise and in print, honouring `--barmark-ink` and `--barmark-rule`,
|
|
29
|
+
in render's label font (`--barmark-label-font`). A page no longer has to
|
|
30
|
+
colour the host itself.
|
|
31
|
+
- **Chord accidentals and the tempo's note draw in Chromium.** Verovio
|
|
32
|
+
declares its Leipzig font (the ♯, ♭ and ♩) inside the score's SVG, in the
|
|
33
|
+
shadow root, where Chromium never registers a font face, so `C♯m7` drew
|
|
34
|
+
as `C m7`. The element now copies that face, once per document, into a
|
|
35
|
+
`<style data-barmark-score-font>` in the head. A page that copied it
|
|
36
|
+
itself can drop the copy.
|
|
37
|
+
|
|
38
|
+
## [0.1.0] - 2026-11-08
|
|
39
|
+
|
|
40
|
+
First release.
|
|
41
|
+
|
|
42
|
+
### Added
|
|
43
|
+
|
|
44
|
+
- `<barmark-score>` (import `@barmark/score/element`, which also registers
|
|
45
|
+
`<barmark-chart>`): the chart as the bar grid or as a full score, with a
|
|
46
|
+
Grid / Score switch (a keyboard radio group). Its chart comes from `text`,
|
|
47
|
+
`src` or a script child, as `<barmark-chart>`'s does, and it takes every
|
|
48
|
+
grid attribute plus `view` (`grid` | `score`) and `verovio-url` (resolved
|
|
49
|
+
against the page, http(s) only); a `viewchange` event follows the view. A
|
|
50
|
+
`view="score"` set before the chart arrives waits for it. The score engine
|
|
51
|
+
loads only on the first switch to the score, engraves at the element's
|
|
52
|
+
width (again after a resize), and shows "Loading score…" meanwhile, the
|
|
53
|
+
first time; a re-engrave keeps the score shown, marked `aria-busy`, until
|
|
54
|
+
the new one lands, so a resize does not blank it. The drawn score is one
|
|
55
|
+
image (`role="img"`) named for the chart's title, or "Score". A score that
|
|
56
|
+
can't be drawn leaves the grid with a note by the switch; a new chart or a
|
|
57
|
+
new `verovio-url` lets the Score radio try again. While `view="score"`
|
|
58
|
+
waits for its chart, Grid is the radio checked, as the grid is what
|
|
59
|
+
shows. Every element on a page shares one worker, so the first
|
|
60
|
+
`verovio-url` that loads is the one used. A shadow
|
|
61
|
+
root drawn by `renderScoreHtml` is taken over without redrawing the grid.
|
|
62
|
+
Importing the package root registers no element.
|
|
63
|
+
- `renderScoreHtml` (from `@barmark/score/server`, which never reaches
|
|
64
|
+
Verovio) draws `<barmark-score>` on the server: the bar grid, the Grid /
|
|
65
|
+
Score switch and the chart text, so the grid shows before any script runs;
|
|
66
|
+
any `view` but `"score"` reads as the grid, and `view: "score"` checks the
|
|
67
|
+
Grid radio (the grid is what shows) while the element keeps `view="score"`
|
|
68
|
+
and switches once it loads. `decodeCarried` reads the text back.
|
|
69
|
+
- `engraveChart` turns a chart into a full score (MusicXML from
|
|
70
|
+
`@barmark/musicxml`, engraved by Verovio) as one SVG column, or says why
|
|
71
|
+
it cannot (a chart that will not export, a score Verovio cannot read or
|
|
72
|
+
one with no pages: `ok: false`, never a throw; a refusal about the whole
|
|
73
|
+
chart does not read "Line 0: …").
|
|
74
|
+
- Safe, themed score markup: `cleanSvg` is an allow-list. A hand-written
|
|
75
|
+
scanner keeps only the elements and attributes Verovio emits (and its own
|
|
76
|
+
two stylesheets) and drops anything else with its content: scripts,
|
|
77
|
+
`foreignObject`, `on*` attributes, links that leave the page and
|
|
78
|
+
attributes whose value holds a character reference. It throws on markup it
|
|
79
|
+
cannot read cleanly (a self-closing `style` or `title`), which
|
|
80
|
+
`engraveChart` turns into `ok: false`. `scorePane` wraps the pages in
|
|
81
|
+
render's `.bm-chart[data-theme]` so the score follows the palette (light,
|
|
82
|
+
dark, auto, print), including the notes, which override Verovio's
|
|
83
|
+
`color="black"`; `scoreStyles` is the score's own layout. `scorePane`
|
|
84
|
+
takes the score's accessible name as an optional third argument (default
|
|
85
|
+
"Score").
|
|
86
|
+
- A shared Verovio worker: `engine()` runs every score of a page through one
|
|
87
|
+
module Worker that loads Verovio on first use, and for each element only
|
|
88
|
+
the newest request is answered (`createEngine` takes any `WorkerLike`); a
|
|
89
|
+
crashed worker rejects what is pending and is replaced on the next call.
|
|
90
|
+
- The README says how to use the element with Vite: Vite 8 (and Vite+)
|
|
91
|
+
needs no config; Vite 7 needs `optimizeDeps.exclude` and
|
|
92
|
+
`worker.format: "es"`.
|
|
93
|
+
|
|
94
|
+
[Unreleased]: https://github.com/kevinpeckham/barmark/compare/score-v0.1.1...HEAD
|
|
95
|
+
[0.1.1]: https://github.com/kevinpeckham/barmark/compare/score-v0.1.0...score-v0.1.1
|
|
96
|
+
[0.1.0]: https://github.com/kevinpeckham/barmark/releases/tag/score-v0.1.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Kevin Peckham
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,146 @@
|
|
|
1
1
|
# @barmark/score
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Shows a [barmark](https://github.com/kevinpeckham/barmark) chord chart as
|
|
4
|
+
the bar grid or as a full engraved score. The chart is exported to MusicXML
|
|
5
|
+
by `@barmark/musicxml` and engraved by Verovio in a Web Worker; the score
|
|
6
|
+
adds no music of its own.
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
npm install @barmark/score
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Two components
|
|
13
|
+
|
|
14
|
+
- **`<barmark-chart>`** from [`@barmark/render`](../render/) is the light
|
|
15
|
+
one: the bar grid, no Verovio.
|
|
16
|
+
- **`<barmark-score>`** from this package is the heavier one: the same grid,
|
|
17
|
+
plus a Grid / Score switch to a full score. Verovio (about 7 MB) loads
|
|
18
|
+
only on the first switch to the score, never on page load, and one copy
|
|
19
|
+
serves every score on the page.
|
|
20
|
+
|
|
21
|
+
Use `<barmark-chart>` when the grid is enough.
|
|
22
|
+
|
|
23
|
+
## As a web component
|
|
24
|
+
|
|
25
|
+
```html
|
|
26
|
+
<script type="module">import "@barmark/score/element";</script>
|
|
27
|
+
|
|
28
|
+
<barmark-score src="/charts/peaceful-dreams.chart.md"></barmark-score>
|
|
29
|
+
|
|
30
|
+
<barmark-score view="score" theme="dark">
|
|
31
|
+
<script type="text/barmark">
|
|
32
|
+
## Verse
|
|
33
|
+
| D | A | Bm | G |
|
|
34
|
+
</script>
|
|
35
|
+
</barmark-score>
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Importing `@barmark/score/element` also registers `<barmark-chart>` (it
|
|
39
|
+
builds on it). Importing the package root registers nothing.
|
|
40
|
+
|
|
41
|
+
The chart comes from the `text` property, the `src` URL or a child
|
|
42
|
+
`<script type="text/barmark">`, exactly as for `<barmark-chart>`. The score
|
|
43
|
+
is engraved at the element's width and again after a resize; the score shown
|
|
44
|
+
stays (with `aria-busy="true"`) until the new one is ready. To assistive
|
|
45
|
+
technology the score is one image named for the chart's title, or "Score".
|
|
46
|
+
|
|
47
|
+
| Attribute (property) | |
|
|
48
|
+
|---|---|
|
|
49
|
+
| `src`, `theme`, `bar-numbers`, `rehearsal-letters`, `numerals`, `wrap`, `show-part` | the grid's own, as in [`@barmark/render`](../render/README.md#options-and-attributes) |
|
|
50
|
+
| `view` (`view`) | `"grid"` (default) or `"score"`; the view being shown. Set before the chart arrives, `"score"` waits for it |
|
|
51
|
+
| `verovio-url` | where to load Verovio from (below) |
|
|
52
|
+
|
|
53
|
+
The `text` property is the chart's text (`null` goes back to `src` or the
|
|
54
|
+
script child). The element fires a `viewchange` event, with
|
|
55
|
+
`detail.view`, whenever the view changes, from the switch or from script.
|
|
56
|
+
|
|
57
|
+
```js
|
|
58
|
+
const score = document.querySelector("barmark-score");
|
|
59
|
+
score.addEventListener("viewchange", (e) => console.log(e.detail.view));
|
|
60
|
+
score.view = "score";
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Bundling the worker
|
|
64
|
+
|
|
65
|
+
The engine runs in a module Worker, created as
|
|
66
|
+
`new Worker(new URL("./worker.js", import.meta.url), { type: "module" })`.
|
|
67
|
+
That is the pattern Vite and webpack follow, so a bundler finds the worker
|
|
68
|
+
and Verovio for you.
|
|
69
|
+
|
|
70
|
+
Vite 8 (and Vite+) needs no config, in `vite dev` or a build. Vite 7 needs
|
|
71
|
+
two lines: its dev pre-bundler moves the element away from the worker and
|
|
72
|
+
the font it finds by URL, and it builds workers as `iife`, which cannot
|
|
73
|
+
load Verovio on demand.
|
|
74
|
+
|
|
75
|
+
```js
|
|
76
|
+
// vite.config.js, for Vite 7 (harmless on Vite 8)
|
|
77
|
+
export default {
|
|
78
|
+
optimizeDeps: { exclude: ["@barmark/score"] },
|
|
79
|
+
worker: { format: "es" },
|
|
80
|
+
};
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Without a bundler, a page's import map does not reach a worker, so the
|
|
84
|
+
worker's bare imports (`verovio/esm`, `barmark`, `@barmark/musicxml`)
|
|
85
|
+
fail. Serve a bundled `worker.js` at the package's URL. `verovio-url` can
|
|
86
|
+
then point at a Verovio module you host (for example
|
|
87
|
+
`verovio/dist/verovio-module.mjs` from the `verovio` package) instead of
|
|
88
|
+
bundling the 7 MB inside the worker; it only changes where that module
|
|
89
|
+
comes from. The URL is resolved against the page and must be http(s);
|
|
90
|
+
anything else is refused and the score is not drawn. The first
|
|
91
|
+
`verovio-url` that loads wins for the whole page: every element shares one
|
|
92
|
+
worker, so a later or different URL is not loaded.
|
|
93
|
+
|
|
94
|
+
### When the score can't be drawn
|
|
95
|
+
|
|
96
|
+
If Verovio fails to load, or rejects the MusicXML, or the chart will not
|
|
97
|
+
export, the grid stays and a note by the switch says "The score couldn't
|
|
98
|
+
be drawn". The reason goes to the console.
|
|
99
|
+
|
|
100
|
+
## On the server
|
|
101
|
+
|
|
102
|
+
```js
|
|
103
|
+
import { renderScoreHtml } from "@barmark/score/server";
|
|
104
|
+
|
|
105
|
+
const html = renderScoreHtml(chartText, { fontUrl: "/fonts/Edwin-Roman.otf" });
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
`renderScoreHtml` takes `@barmark/render`'s options plus `view`. It never
|
|
109
|
+
loads Verovio: it draws the bar grid and the Grid / Score switch in a
|
|
110
|
+
declarative shadow root, so the chart shows before any script runs. The
|
|
111
|
+
score is engraved once `<barmark-score>` upgrades in the browser, taking
|
|
112
|
+
over the markup without redrawing the grid. Like `renderChart`, insert it
|
|
113
|
+
by parsing HTML (or `setHTMLUnsafe`), not `innerHTML`.
|
|
114
|
+
|
|
115
|
+
## Engraving directly
|
|
116
|
+
|
|
117
|
+
```js
|
|
118
|
+
import createVerovioModule from "verovio/wasm";
|
|
119
|
+
import { VerovioToolkit } from "verovio/esm";
|
|
120
|
+
import { engraveChart } from "@barmark/score";
|
|
121
|
+
|
|
122
|
+
const vrv = new VerovioToolkit(await createVerovioModule());
|
|
123
|
+
const result = engraveChart(vrv, chartText, { width: 800 });
|
|
124
|
+
if (result.ok) document.body.innerHTML = result.svg;
|
|
125
|
+
else console.warn(result.reason);
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
The SVG is cleaned with an allow-list (`cleanSvg`) before it is returned;
|
|
129
|
+
`scorePane` and `scoreStyles` wrap it so it follows the grid's light and
|
|
130
|
+
dark palette. `engraveChart` and `engraveXml` drop a chord `<degree>`
|
|
131
|
+
marked `print-object="no"` before Verovio reads the MusicXML, as Verovio
|
|
132
|
+
6.4 prints every degree after the chord's text (`D7sus4(7)`); `result.xml`
|
|
133
|
+
is the export unchanged.
|
|
134
|
+
|
|
135
|
+
## Licence
|
|
136
|
+
|
|
137
|
+
This package is MIT. It uses [Verovio](https://github.com/rism-digital/verovio),
|
|
138
|
+
which is LGPL-3.0-only, as an ordinary npm dependency, loaded unchanged at
|
|
139
|
+
run time; its code is never copied into this package. barmark's own code
|
|
140
|
+
stays MIT. Verovio's licence text is
|
|
141
|
+
[COPYING.LESSER](https://github.com/rism-digital/verovio/blob/develop/COPYING.LESSER).
|
|
142
|
+
|
|
143
|
+
A site that bundles the worker ships Verovio inside its bundle. Keeping
|
|
144
|
+
Verovio a separate file (through `verovio-url`, or the bundler's own
|
|
145
|
+
chunk) and keeping its notice is the easy way to meet the LGPL. This is
|
|
146
|
+
not legal advice.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `<barmark-score>`: a chart as barmark's bar grid or as a full score, with a
|
|
3
|
+
* Grid / Score switch. Its chart comes from the `text` property, a `src` URL or
|
|
4
|
+
* a child `<script type="text/barmark">`, as `<barmark-chart>`'s does. A shadow
|
|
5
|
+
* root drawn by `renderScoreHtml` is reused. The score engine (Verovio, in a
|
|
6
|
+
* worker) loads on the first switch to the score, never before. Importing
|
|
7
|
+
* this module registers the element (once) and the font (once per document).
|
|
8
|
+
*/
|
|
9
|
+
import type { Engine } from "./engine.js";
|
|
10
|
+
type EngineFactory = () => Engine | Promise<Engine>;
|
|
11
|
+
/** For tests only: an engine to use in place of the worker's, or null for the real one. */
|
|
12
|
+
export declare function setEngineForTests(factory: EngineFactory | null): void;
|
|
13
|
+
export {};
|