@barmark/render 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -6,6 +6,27 @@ package uses [semantic versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-11-02
+
+Charts that scroll instead of wrapping. barmark.dev's home page uses it.
+
+### Added
+
+- **`wrap: false`** (attribute `wrap="off"`, property `wrap`): a section
+  wider than the chart's box keeps its rows and columns rather than
+  wrapping them, and the chart overflows for its page to scroll.
+
+## [0.5.0] - 2026-11-02
+
+The spoken name of a chord, for other tools. barmark.dev's /try page
+uses it.
+
+### Added
+
+- **`speakChord(record, key?)`**: the spoken name the chart gives a chord
+  ("C minor seven flat five"; with a key, its degree too), for screen
+  readers and other tools.
+
 ## [0.4.0] - 2026-11-01
 
 Chords as Nashville numbers or Roman numerals, and a little air between
@@ -158,7 +179,9 @@ that needs no script or as the `<barmark-chart>` web component. Requires
   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.4.0...HEAD
+[Unreleased]: https://github.com/kevinpeckham/barmark/compare/render-v0.6.0...HEAD
+[0.6.0]: https://github.com/kevinpeckham/barmark/compare/render-v0.5.0...render-v0.6.0
+[0.5.0]: https://github.com/kevinpeckham/barmark/compare/render-v0.4.0...render-v0.5.0
 [0.4.0]: https://github.com/kevinpeckham/barmark/compare/render-v0.3.0...render-v0.4.0
 [0.3.0]: https://github.com/kevinpeckham/barmark/compare/render-v0.2.1...render-v0.3.0
 [0.2.1]: https://github.com/kevinpeckham/barmark/compare/render-v0.2.0...render-v0.2.1

package/README.md

@@ -76,6 +76,7 @@ the element loads, with `<style data-barmark-font>` holding
 | `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 |
 | `numerals` | `numerals` (`numerals`) | none | `"nashville"` (6m⁷) or `"roman"` (vi⁷): each chord as its degree in its bar's key |
+| `wrap` | `wrap="off"` (`wrap`) | `true` | wrap a section's rows when it is wider than the chart's box; off, rows keep their columns and the chart overflows, for its page to scroll |
 | `diagnostics` | | `false` | list the chart's errors and warnings below it |
 | `fontUrl` | | none | emit Edwin's `@font-face` rule before the chart |
 | (the `text` argument) | (`text`) | `null` | the chart to draw; wins over `src` and the script child |
@@ -92,6 +93,21 @@ no key, note sets, N.C., `?` and `--` look as they always do, and a
 screen reader hears both: "bar 5: five, A seven". Numbered chords carry
 `data-numeral`. It's a view: the music and bar numbers don't change.
 
+### Spoken names
+
+`speakChord(record, key?)` gives a chord the name a screen reader hears
+in the chart, for other tools that want to say a chord aloud:
+
+```ts
+import { parseChord } from "barmark";
+import { speakChord } from "@barmark/render";
+
+const r = parseChord("Cø");
+if (r.ok) speakChord(r.value); // "C minor seven flat five"
+```
+
+With a key, it speaks the degree too, as the numerals view does.
+
 ## Styling on purpose
 
 Set these custom properties on the element or anything above it:

package/dist/element.js

@@ -14,6 +14,7 @@ export function optionsFromAttributes(el) {
         theme: THEMES.find((t) => t === theme) ?? "auto",
         barNumbers: el.getAttribute("bar-numbers") !== "off",
         rehearsalLetters: el.hasAttribute("rehearsal-letters"),
+        wrap: el.getAttribute("wrap") !== "off",
         ...(numerals ? { numerals } : {}),
     };
 }
@@ -48,7 +49,14 @@ async function fetchText(src) {
 }
 function defineElement() {
     class BarmarkChart extends HTMLElement {
-        static observedAttributes = ["src", "theme", "bar-numbers", "rehearsal-letters", "numerals"];
+        static observedAttributes = [
+            "src",
+            "theme",
+            "bar-numbers",
+            "rehearsal-letters",
+            "numerals",
+            "wrap",
+        ];
         #observer = new MutationObserver(() => this.#schedule());
         #renders = 0;
         #scheduled = false;
@@ -103,6 +111,15 @@ function defineElement() {
             else
                 this.setAttribute("bar-numbers", "off");
         }
+        get wrap() {
+            return optionsFromAttributes(this).wrap ?? true;
+        }
+        set wrap(v) {
+            if (v)
+                this.removeAttribute("wrap");
+            else
+                this.setAttribute("wrap", "off");
+        }
         get rehearsalLetters() {
             return this.hasAttribute("rehearsal-letters");
         }
@@ -167,6 +184,10 @@ function defineElement() {
                 chart?.setAttribute("data-bar-numbers", "off");
             else
                 chart?.removeAttribute("data-bar-numbers");
+            if (options.wrap === false)
+                chart?.setAttribute("data-wrap", "off");
+            else
+                chart?.removeAttribute("data-wrap");
         }
     }
     customElements.define("barmark-chart", BarmarkChart);

package/dist/html.d.ts

@@ -9,6 +9,11 @@ export type RenderOptions = {
     fontUrl?: string;
     /** Show each chord as its degree in the bar's key, where the chart names one. Off by default. */
     numerals?: Numerals;
+    /**
+     * Wrap a section's rows when it is wider than the chart's box (the default).
+     * With `false` rows keep their columns, and the page scrolls the chart instead.
+     */
+    wrap?: boolean;
 };
 export declare function renderChart(text: string, options?: RenderOptions): string;
 export declare const THEMES: readonly ["auto", "light", "dark"];

package/dist/html.js

@@ -15,6 +15,7 @@ function elementAttributes(options) {
         options.barNumbers === false ? ' bar-numbers="off"' : "",
         options.rehearsalLetters ? " rehearsal-letters" : "",
         numeralsOf(options) ? ` numerals="${numeralsOf(options)}"` : "",
+        options.wrap === false ? ' wrap="off"' : "",
     ].join("");
 }
 export const THEMES = ["auto", "light", "dark"];
@@ -35,7 +36,7 @@ function chartHtml(text, options) {
         barNumbers: options.barNumbers ?? true,
         numerals: numeralsOf(options),
     };
-    return `<div class="bm-chart" data-theme="${themeOf(options)}"${settings.barNumbers ? "" : ' data-bar-numbers="off"'}>${headerHtml(model)}${model.blocks.map((b) => blockHtml(b, settings)).join("")}${options.diagnostics ? diagnosticsHtml(model) : ""}</div>`;
+    return `<div class="bm-chart" data-theme="${themeOf(options)}"${settings.barNumbers ? "" : ' data-bar-numbers="off"'}${options.wrap === false ? ' data-wrap="off"' : ""}>${headerHtml(model)}${model.blocks.map((b) => blockHtml(b, settings)).join("")}${options.diagnostics ? diagnosticsHtml(model) : ""}</div>`;
 }
 function headerHtml(model) {
     const title = model.title

package/dist/index.d.ts

@@ -2,5 +2,6 @@ export type { Numerals } from "./chord.js";
 export { FONT_FAMILY, fontFaceCss } from "./font.js";
 export { type RenderOptions, renderChart, renderChartUnwrapped } from "./html.js";
 export { layoutChart } from "./model.js";
+export { speakChord } from "./speech.js";
 export { stylesheet } from "./styles.js";
 export type * from "./types.js";

package/dist/index.js

@@ -1,4 +1,5 @@
 export { FONT_FAMILY, fontFaceCss } from "./font.js";
 export { renderChart, renderChartUnwrapped } from "./html.js";
 export { layoutChart } from "./model.js";
+export { speakChord } from "./speech.js";
 export { stylesheet } from "./styles.js";

package/dist/styles.js

@@ -84,6 +84,7 @@ const css = `
 .bm-times{font:italic 1.2em/1 Georgia,serif;text-transform:none;letter-spacing:0;color:var(--bm-muted)}
 .bm-grid{display:grid;grid-template-columns:${em(GUTTER)} repeat(var(--bm-cols),auto) auto;width:max-content;max-width:100%}
 .bm-chart[data-bar-numbers="off"] .bm-grid{grid-template-columns:repeat(var(--bm-cols),auto) auto}
+.bm-chart[data-wrap="off"] .bm-grid{max-width:none}
 .bm-row{display:contents}
 .bm-row+.bm-row>*{margin-top:${em(ROW_GAP)}}
 .bm-row+.bm-row>.bm-bar-number{margin-top:${at(SIZES.barNumber, ROW_GAP)}}
@@ -131,7 +132,7 @@ const css = `
 	.bm-bar[data-cut]{outline-color:CanvasText}
 }
 ${FIT_STEPS.map((w) => {
-    const g = `.bm-grid[data-fit="${w}"]`;
+    const g = `.bm-chart:not([data-wrap="off"]) .bm-grid[data-fit="${w}"]`;
     return `@container bm (max-width:${w}em){${g}{display:block}${g}>.bm-row{display:flex;flex-wrap:wrap;row-gap:${em(ROW_GAP)}}${g} .bm-empty{display:none}${g} .bm-bar{flex:0 1 auto;max-width:100%;border-left:.075em solid var(--bm-rule);margin-left:-.075em}${g} :is(.bm-bar-body,.bm-group,.bm-notes){flex-wrap:wrap}${g} .bm-bar-body>*{flex:1 1 auto;min-width:auto}}`;
 }).join("\n")}
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@barmark/render",
-	"version": "0.4.0",
+	"version": "0.6.0",
 	"description": "Render barmark chord charts as a clean, accessible bar grid: HTML with Declarative Shadow DOM, or the <barmark-chart> web component.",
 	"type": "module",
 	"exports": {