@barmark/render 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+All notable changes to `@barmark/render` are recorded here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
+package uses [semantic versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-31
+
+The first release: barmark charts as an evenly spaced bar grid, as HTML
+that needs no script or as the `<barmark-chart>` web component. Requires
+`barmark` 0.2.0 or later.
+
+### Added
+
+- **`layoutChart(text)`**: the chart as data to draw. Bar lines become rows
+  with their play-order bar numbers (numbering stops after an open repeat),
+  `%` becomes the bar it copies, and text lines, directives and lines with
+  errors keep their place.
+- **Replays are drawn in full** with their own bar numbers. A replay's own
+  text lines (verse 2's words) replace the written section's in order;
+  `->` marks the bar the parser cut. Optional rehearsal letters (A, B, …,
+  AA) mark each section occurrence in play order.
+- **`renderChart(text, options)`** returns the chart as a `<barmark-chart>`
+  element holding a declarative shadow root, and `renderChartUnwrapped`
+  the bare markup (`bm-` classes) for pages that bring the stylesheet.
+  Options: `theme`, `barNumbers`, `rehearsalLetters`, `diagnostics`. All
+  chart text is escaped.
+- **Chords in canonical form,** with ♯ and ♭ glyphs and the extension as a
+  superscript; single notes ringed; note sets in braces with the root
+  underlined; groups under a tuplet count; fermatas, one-bar meters, N.C.,
+  silence and `?` each drawn distinctly.
+- **Spoken names:** every bar reads to a screen reader as music ("bar 9: A
+  seven sus four, hold"), with sections labelled by their headings and
+  repeats spoken ("play 2 times").
+- **Styles, light and dark.** The chart follows the system's colour scheme
+  (`theme: "auto"`), or is forced `light` or `dark`; printing is always
+  light, and Windows High Contrast keeps bar lines and marks visible. Both
+  palettes meet WCAG AA contrast. Everything is sized in em from
+  `--barmark-size`, and a section too wide for its container wraps its
+  rows rather than scrolling sideways. Pages restyle the chart through
+  `--barmark-font`, `--barmark-size`, `--barmark-ink`, `--barmark-paper`,
+  `--barmark-muted`, `--barmark-rule` and `--barmark-accent`, or
+  `::part()`.
+- **Edwin ships with the package,** unmodified, with its OFL licence
+  (`@barmark/render/fonts/Edwin-Roman.otf`). Pass `fontUrl` to emit its
+  `@font-face` rule before the chart, or call `fontFaceCss(url)` once per
+  page. The family is registered as "barmark Edwin"; without it the chart
+  falls back to Georgia or another serif.
+- **`<barmark-chart>`** (`import "@barmark/render/element"`): renders a
+  chart from its `src` URL or a child `<script type="text/barmark">`, and
+  again when either changes. Attributes (and matching properties):
+  `theme`, `bar-numbers="off"`, `rehearsal-letters`. It registers the font
+  itself, reuses a server-rendered shadow root (which still follows
+  `theme` and `bar-numbers`), fetches a `src` once, renders once per batch
+  of changes, and shows a failed load as an error inside the chart.
+
+### Technical
+
+- **Browser tests** (Playwright, Chromium) in CI: the chart looks pixel
+  for pixel the same on a page with hostile CSS, themes follow the system
+  and the page's custom properties, long rows wrap on a phone and at 400%
+  zoom without sideways scrolling, the element renders and re-renders, and
+  a screen reader hears "bar 9: D". Run them with `bun run test:browser`.
+
+[Unreleased]: https://github.com/kevinpeckham/barmark/compare/render-v0.1.0...HEAD
+[0.1.0]: https://github.com/kevinpeckham/barmark/releases/tag/render-v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kevin Peckham
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+# @barmark/render
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Renders [barmark](https://github.com/kevinpeckham/barmark) chord charts as
+a clean, evenly spaced bar grid that looks the same on any page, follows
+light and dark mode, scales with the reader's text size, and reads to a
+screen reader as music.
+
+```
+npm install @barmark/render
+```
+
+## As HTML (no browser JavaScript needed)
+
+```js
+import { renderChart } from "@barmark/render";
+
+const html = renderChart(chartText, { fontUrl: "/fonts/Edwin-Roman.otf" });
+```
+
+`renderChart` returns a `<barmark-chart>` element holding a declarative
+shadow root: put it in any page, server-rendered or static, and it shows
+the chart with no script. The shadow root keeps the page's CSS out, so a
+blog's resets and fonts cannot rearrange the bars. Browsers attach a
+declarative shadow root only while parsing HTML: to insert the markup from
+script, use `setHTMLUnsafe` (or the element below), not `innerHTML`.
+
+`renderChartUnwrapped(text, options)` returns the same markup without the
+shadow root (classes prefixed `bm-`), for pages that include `stylesheet`
+themselves.
+
+## As a web component
+
+```html
+<script type="module">import "@barmark/render/element";</script>
+
+<barmark-chart src="/charts/peaceful-dreams.chart.md"></barmark-chart>
+
+<barmark-chart theme="dark" rehearsal-letters>
+	<script type="text/barmark">
+		## Verse
+		| D | A | Bm | G |
+	</script>
+</barmark-chart>
+```
+
+The element renders from its `src` URL, or from a child
+`<script type="text/barmark">` (indentation is removed), and renders again
+whenever either changes; it fetches a `src` once, and renders once
+however many attributes change together. A chart rendered on the server
+by `renderChart` keeps its music until it has a source of its own, and
+still follows `theme` and `bar-numbers`.
+
+The element registers the font itself, from the `fonts/` folder beside its
+own module. If your bundler moves that file, register it yourself before
+the element loads, with `<style data-barmark-font>` holding
+`fontFaceCss(yourUrl)`; the element then leaves it alone.
+
+## Options and attributes
+
+| `renderChart` option | Element attribute (property) | Default | |
+|---|---|---|---|
+| `theme` | `theme` (`theme`) | `"auto"` | `"auto"` follows the system; `"light"` or `"dark"` force one |
+| `barNumbers` | `bar-numbers="off"` (`barNumbers`) | `true` | bar numbers at the start of each row |
+| `rehearsalLetters` | `rehearsal-letters` (`rehearsalLetters`) | `false` | boxed A, B, C… on each section as played |
+| `diagnostics` | | `false` | list the chart's errors and warnings below it |
+| `fontUrl` | | none | emit Edwin's `@font-face` rule before the chart |
+
+## Styling on purpose
+
+Set these custom properties on the element or anything above it:
+
+| Property | What it sets |
+|---|---|
+| `--barmark-font` | the chart's typeface |
+| `--barmark-size` | the base size everything scales from (default `1.25rem`) |
+| `--barmark-ink` | chords and text |
+| `--barmark-paper` | the background |
+| `--barmark-muted` | holds, bar numbers, braces, meta lines |
+| `--barmark-rule` | bar lines |
+| `--barmark-accent` | errors |
+
+```css
+barmark-chart {
+	--barmark-size: 1rem;
+	--barmark-paper: transparent;
+}
+barmark-chart::part(heading) {
+	color: teal;
+}
+```
+
+`::part()` names: `title`, `meta`, `heading`, `bar`, `chord`, `text`,
+`bar-number`, `rehearsal`. These, the custom properties and the
+attributes are the public surface: changing them is a breaking change.
+
+## Light, dark and print
+
+Both palettes meet WCAG AA contrast (4.5:1 for text). `theme="auto"`
+follows `prefers-color-scheme`; a page with its own dark-mode switch sets
+`theme` or the colour properties. Printing always uses the light palette,
+and Windows High Contrast keeps bar lines and marks visible.
+
+## Accessibility
+
+- Everything is sized in em from `--barmark-size`, so text size and zoom
+  scale the chart; a section too wide for its container wraps its rows
+  instead of scrolling sideways.
+- Every bar has a spoken name built from the parsed chart: "bar 9: A seven
+  sus four, hold", "triplet: D, E, F sharp minor", "note E", "C over E".
+  Sections are labelled by their headings, and repeats are spoken ("play
+  2 times").
+
+## The font
+
+Edwin, MuseScore's text font for music, ships unmodified in
+`@barmark/render/fonts/Edwin-Roman.otf` with its SIL Open Font License
+(`fonts/OFL.txt`). It is registered under the family name "barmark
+Edwin". Serve the file and pass its URL as `fontUrl`, or call
+`fontFaceCss(url)` once per page; without it the chart uses Georgia or
+another serif.
+
+## What it draws
+
+Chords appear in their canonical form whatever the author typed (`Cø`
+shows as Cm⁷(♭5)). `%` is drawn as the bar it copies; a replayed section
+is drawn in full with its own bar numbers, and its own lyrics replace the
+written section's. A line with an error shows as written, underlined,
+with its message. `layoutChart(text)` returns all of this as data, if
+you want to draw it yourself.
+
+## License
+
+MIT. Edwin is © MuseScore Limited, under the SIL Open Font License 1.1.

package/dist/chord.d.ts

@@ -0,0 +1,18 @@
+/** Chords and notes as display pieces: ♯ and ♭ glyphs, the suffix split for superscript. */
+import type { ChordParts } from "barmark";
+export type ChordPieces = {
+    root: string;
+    /** m, dim, aug or 5: set on the baseline. */
+    quality: string;
+    /** Extension, sus and tones: set as a superscript. */
+    superscript: string;
+    bass: string | null;
+};
+/** `F#` → `F♯`, `b9` → `♭9`, `Bbb` → `B𝄫`. */
+export declare function glyphs(text: string): string;
+export declare function typesetChord(parts: ChordParts): ChordPieces;
+/** A note set's label (`E1`, `F#`) as name and octave. */
+export declare function splitPitch(label: string): {
+    name: string;
+    octave: string | null;
+};

package/dist/chord.js

@@ -0,0 +1,24 @@
+const ACCIDENTALS = [
+    [/##/g, "𝄪"],
+    [/bb(?=\d|$|\))/g, "𝄫"],
+    [/#/g, "♯"],
+    [/(?<=[A-G]|^|\(|,)b/g, "♭"],
+];
+/** `F#` → `F♯`, `b9` → `♭9`, `Bbb` → `B𝄫`. */
+export function glyphs(text) {
+    return ACCIDENTALS.reduce((t, [re, g]) => t.replace(re, g), text);
+}
+export function typesetChord(parts) {
+    const tones = parts.tones.length ? `(${parts.tones.join(",")})` : "";
+    return {
+        root: glyphs(parts.root),
+        quality: parts.quality,
+        superscript: glyphs(`${parts.extension ?? ""}${parts.sus ?? ""}${tones}`),
+        bass: parts.bass ? glyphs(parts.bass) : null,
+    };
+}
+/** A note set's label (`E1`, `F#`) as name and octave. */
+export function splitPitch(label) {
+    const m = /^([A-G](?:##|bb|#|b)?)(-?\d+)?$/.exec(label);
+    return { name: glyphs(m?.[1] ?? label), octave: m?.[2] ?? null };
+}

package/dist/element.d.ts

@@ -0,0 +1,9 @@
+import { type RenderOptions } from "./html.js";
+type Attributes = {
+    getAttribute(name: string): string | null;
+    hasAttribute(name: string): boolean;
+};
+export declare function optionsFromAttributes(el: Attributes): RenderOptions;
+/** Chart text from a script element: blank edges and common indentation removed. */
+export declare function inlineChartText(text: string): string;
+export {};

package/dist/element.js

@@ -0,0 +1,135 @@
+/**
+ * `<barmark-chart>`: renders itself from a `src` URL or from a child
+ * `<script type="text/barmark">`, and again whenever either changes. A
+ * shadow root rendered on the server is reused. Importing this module
+ * registers the element (once) and the font (once per document).
+ */
+import { FONT_FAMILY, fontFaceCss } from "./font.js";
+import { loadErrorContent, shadowContent, THEMES } from "./html.js";
+export function optionsFromAttributes(el) {
+    const theme = el.getAttribute("theme");
+    return {
+        theme: THEMES.find((t) => t === theme) ?? "auto",
+        barNumbers: el.getAttribute("bar-numbers") !== "off",
+        rehearsalLetters: el.hasAttribute("rehearsal-letters"),
+    };
+}
+/** Chart text from a script element: blank edges and common indentation removed. */
+export function inlineChartText(text) {
+    const lines = text.replace(/^\s*\n|\n\s*$/g, "").split("\n");
+    const indents = lines.filter((l) => l.trim()).map((l) => /^[ \t]*/.exec(l)?.[0].length ?? 0);
+    const cut = Math.min(...indents, Number.POSITIVE_INFINITY);
+    return lines.map((l) => l.slice(Number.isFinite(cut) ? cut : 0).trimEnd()).join("\n");
+}
+function registerFont(doc) {
+    if (doc.querySelector("style[data-barmark-font]"))
+        return;
+    const style = doc.createElement("style");
+    style.dataset.barmarkFont = FONT_FAMILY;
+    style.textContent = fontFaceCss(new URL("../fonts/Edwin-Roman.otf", import.meta.url).href);
+    doc.head.append(style);
+}
+async function fetchText(src) {
+    const response = await fetch(src);
+    if (!response.ok)
+        throw new Error(`${response.status} ${response.statusText}`.trim());
+    return response.text();
+}
+function defineElement() {
+    class BarmarkChart extends HTMLElement {
+        static observedAttributes = ["src", "theme", "bar-numbers", "rehearsal-letters"];
+        #observer = new MutationObserver(() => this.#schedule());
+        #renders = 0;
+        #scheduled = false;
+        /** The text fetched for `src`, kept so a change of options does not fetch again. */
+        #fetched = null;
+        connectedCallback() {
+            registerFont(this.ownerDocument);
+            this.#observer.observe(this, { childList: true, subtree: true, characterData: true });
+            this.#schedule();
+        }
+        disconnectedCallback() {
+            this.#observer.disconnect();
+        }
+        attributeChangedCallback() {
+            if (this.isConnected)
+                this.#schedule();
+        }
+        get src() {
+            return this.getAttribute("src") ?? "";
+        }
+        set src(v) {
+            this.setAttribute("src", v);
+        }
+        get theme() {
+            return optionsFromAttributes(this).theme ?? "auto";
+        }
+        set theme(v) {
+            this.setAttribute("theme", v);
+        }
+        get barNumbers() {
+            return optionsFromAttributes(this).barNumbers ?? true;
+        }
+        set barNumbers(v) {
+            if (v)
+                this.removeAttribute("bar-numbers");
+            else
+                this.setAttribute("bar-numbers", "off");
+        }
+        get rehearsalLetters() {
+            return this.hasAttribute("rehearsal-letters");
+        }
+        set rehearsalLetters(v) {
+            this.toggleAttribute("rehearsal-letters", v);
+        }
+        /** Every change in one task (an upgrade sets each attribute in turn) renders once. */
+        #schedule() {
+            if (this.#scheduled)
+                return;
+            this.#scheduled = true;
+            queueMicrotask(() => {
+                this.#scheduled = false;
+                void this.#render();
+            });
+        }
+        async #render() {
+            const script = this.querySelector('script[type="text/barmark"]');
+            const options = optionsFromAttributes(this);
+            // With no source of its own, a server-rendered chart keeps its music and takes the options it can.
+            if (!this.src && !script)
+                return this.#restyle(options);
+            const render = ++this.#renders;
+            const content = await this.#content(script, options);
+            if (render !== this.#renders)
+                return;
+            (this.shadowRoot ?? this.attachShadow({ mode: "open" })).innerHTML = content;
+        }
+        async #content(script, options) {
+            if (!this.src)
+                return shadowContent(inlineChartText(script?.textContent ?? ""), options);
+            try {
+                return shadowContent(await this.#text(this.src), options);
+            }
+            catch (e) {
+                this.#fetched = null;
+                return loadErrorContent(`Could not load ${this.src}: ${e.message}`, options);
+            }
+        }
+        #text(src) {
+            if (this.#fetched?.src !== src)
+                this.#fetched = { src, text: fetchText(src) };
+            return this.#fetched.text;
+        }
+        #restyle(options) {
+            const chart = this.shadowRoot?.querySelector(".bm-chart");
+            chart?.setAttribute("data-theme", options.theme ?? "auto");
+            if (options.barNumbers === false)
+                chart?.setAttribute("data-bar-numbers", "off");
+            else
+                chart?.removeAttribute("data-bar-numbers");
+        }
+    }
+    customElements.define("barmark-chart", BarmarkChart);
+}
+if (typeof customElements !== "undefined" && !customElements.get("barmark-chart"))
+    defineElement();

package/dist/escape.d.ts

@@ -0,0 +1,2 @@
+/** Text from the chart, safe in element content and in quoted attributes. */
+export declare const escapeHtml: (text: string) => string;

package/dist/escape.js

@@ -0,0 +1,9 @@
+const ENTITIES = {
+    "&": "&",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+/** Text from the chart, safe in element content and in quoted attributes. */
+export const escapeHtml = (text) => text.replace(/[&<>"']/g, (c) => ENTITIES[c] ?? c);

package/dist/font.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Edwin is registered on the host page, not in the shadow root (some
+ * browsers ignore @font-face there), under its own family name so it can
+ * never collide with a page's fonts. The file ships unmodified (OFL).
+ */
+export declare const FONT_FAMILY = "barmark Edwin";
+/** One @font-face rule for the font at `url`; the URL cannot close the string or the <style>. */
+export declare function fontFaceCss(url: string): string;

package/dist/font.js

@@ -0,0 +1,11 @@
+/**
+ * Edwin is registered on the host page, not in the shadow root (some
+ * browsers ignore @font-face there), under its own family name so it can
+ * never collide with a page's fonts. The file ships unmodified (OFL).
+ */
+export const FONT_FAMILY = "barmark Edwin";
+/** One @font-face rule for the font at `url`; the URL cannot close the string or the <style>. */
+export function fontFaceCss(url) {
+    const safe = url.replace(/["\\<>\n\r]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase().padStart(2, "0")}`);
+    return `@font-face{font-family:"${FONT_FAMILY}";src:url("${safe}") format("opentype");font-display:swap}`;
+}

package/dist/html.d.ts

@@ -0,0 +1,16 @@
+export type RenderOptions = {
+    theme?: "auto" | "light" | "dark";
+    barNumbers?: boolean;
+    rehearsalLetters?: boolean;
+    /** List the chart's errors and warnings below it. */
+    diagnostics?: boolean;
+    /** Where the page serves Edwin-Roman.otf: emits its @font-face rule before the chart. */
+    fontUrl?: string;
+};
+export declare function renderChart(text: string, options?: RenderOptions): string;
+export declare const THEMES: readonly ["auto", "light", "dark"];
+/** What goes in the shadow root: the styles and the chart. */
+export declare const shadowContent: (text: string, options?: RenderOptions) => string;
+/** A chart that could not be loaded: the message, shown where the chart would be. */
+export declare const loadErrorContent: (message: string, options?: RenderOptions) => string;
+export declare function renderChartUnwrapped(text: string, options?: RenderOptions): string;