ascii-tabs 0.10.3 → 0.11.2

package/README.md

@@ -24,6 +24,14 @@ import { parse, format } from 'ascii-tabs';
 
 No bundler? Load it from a CDN instead, see [Usage](#usage). Full documentation and a live, editable demo: **https://libasoles.github.io/ascii-tabs/**
 
+## Used in
+
+`ascii-tabs` runs in production on [acordesdeguitarra.com.ar](https://acordesdeguitarra.com.ar/en):
+
+- [Tabs for arpeggios](https://acordesdeguitarra.com.ar/en/articles/tabs-for-arpeggios): an article with arpeggio tabs.
+- [Create guitar tabs](https://acordesdeguitarra.com.ar/en/create-guitar-tabs): write your own tabs online.
+- [Carcassi preludes](https://acordesdeguitarra.com.ar/en/articles/carcassi-preludes): integrated with sheet music (partituras).
+
 ## See it in action
 
 ### Edit and organize tabs
@@ -54,12 +62,12 @@ Design notes: [spec](docs/spec-v0.1.md), [glossary](GLOSSARY.md), [ADRs](docs/ad
 ## Usage
 
 ```html
-<script type="module" src="https://cdn.jsdelivr.net/gh/libasoles/ascii-tabs@0.10.3/ascii-tabs.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/gh/libasoles/ascii-tabs@0.11.2/ascii-tabs.js"></script>
 
 <ascii-tabs></ascii-tabs>
 ```
 
-A bare `<ascii-tabs>` is editable: a hint, one Sheet per Tab with copy and delete buttons, and an add button. Click a string and type the fret number (0–24); move with the arrow keys, Enter and Tab. Press Cmd+Right Arrow or Alt+Right Arrow to copy all six strings of the current column into the next column, replacing its contents, and move the cursor there. Press Cmd+0 or Alt+0 to fill only the empty cells of the current column with zeros, keeping existing frets and the cursor in place.
+A bare `<ascii-tabs>` is editable: a hint, one Sheet per Tab with copy and delete buttons, and an add button. Click a string and type the fret number (0–24, or up to `max-fret`); move with the arrow keys, Enter and Tab. Press Cmd+Right Arrow or Alt+Right Arrow to copy all six strings of the current column into the next column, replacing its contents, and move the cursor there. Press Shift+Up Arrow or Shift+Down Arrow to re-finger the current note (or the whole selection) on the next String up or down that keeps its pitch, for example a 7 on String 5 becomes a 2 on String 4; nothing happens when no such position exists. Press Cmd+0 or Alt+0 to fill only the empty cells of the current column with zeros, keeping existing frets and the cursor in place.
 
 Drag from an empty cell or a blank area of a Sheet to select notes inside a rectangle. Drag any selected note to move the group, keeping its relative columns and strings; occupied destination cells are replaced. Cmd+Right Arrow or Alt+Right Arrow duplicates the selected group immediately after its last column and selects the duplicate. Cmd/Ctrl+C or the Sheet's copy button copies the selection as ASCII; Cmd/Ctrl+V pastes ASCII at the current column, preserving string positions. Delete or Backspace removes the selected notes, and Escape clears the selection.
 
@@ -401,7 +409,7 @@ E|-----3-|</pre>
 The copy button copies the same plain ASCII. `parse` and `format` are exported as pure functions:
 
 ```js
-import { parse, format } from 'https://cdn.jsdelivr.net/gh/libasoles/ascii-tabs@0.10.3/ascii-tabs.js';
+import { parse, format } from 'https://cdn.jsdelivr.net/gh/libasoles/ascii-tabs@0.11.2/ascii-tabs.js';
 
 const tab = parse('1 -3--5-\n2 ------\n3 ------\n4 ------\n5 ------\n6 ------'); // one Tab: Column[]
 format(tab, { spacing: 2 }); // "1 -3--5-\n2 ------\n..."
@@ -565,14 +573,32 @@ Changing or removing the attribute updates the view immediately.
 
 ## String labels
 
+`max-fret` (property `maxFret`) sets the highest Fret the editor accepts when typing or re-fingering with Shift+Up/Down Arrow. It defaults to `24`; use `max-fret="19"` for a classical guitar. Values outside 1–24 fall back to 24. It does not rewrite notes already in `value`.
+
+```html
+<ascii-tabs max-fret="19"></ascii-tabs>
+```
+
 Strings are labelled `1`–`6` by default, on screen and in copied text. `labels="notes"` names them using `tuning` (standard tuning by default: `e B G D A E`, String 1 to 6). `labels="none"` hides the labels and uses their space for Columns. This also applies to copied text. The `labels` property accepts `"numbers"`, `"notes"`, or `"none"`; other values fall back to numbers. Parsing accepts all three styles whatever the attribute says.
 
 ```html
 <ascii-tabs></ascii-tabs>                  <!-- 1 -3--5- -->
-<ascii-tabs labels="notes"></ascii-tabs>   <!-- e|-3--5- -->
+<ascii-tabs labels="notes"></ascii-tabs>   <!-- e -3--5- -->
 <ascii-tabs labels="none"></ascii-tabs>    <!-- -3--5- -->
 ```
 
+String labels have no bars by default. Add the boolean `string-bars` attribute
+(or set `element.stringBars = true`) to draw a `|` at the start of each String,
+independently of the labels. The bars also appear in copied ASCII. Remove the
+attribute or set the property to `false` to hide them.
+
+```html
+<ascii-tabs labels="notes" string-bars></ascii-tabs> <!-- e |-3--5- -->
+<ascii-tabs labels="none" string-bars></ascii-tabs>  <!-- |-3--5- -->
+```
+
+The standalone formatter accepts the same option: `format(tab, { stringBars: true })`.
+
 ## Tool position
 
 A Sheet's tools (copy, delete) stand in a column to the right of the Staves by default, and the Staves leave room for them. `tools="top"` lines them up in a row above the first String instead. Also available as the `tools` property.

package/ascii-tabs.js

@@ -26,11 +26,12 @@ const labelStyle = value => (value === 'notes' || value === 'none' ? value : 'nu
 const stringLabels = (labels, tuning) => {
   if (labelStyle(labels) === 'none') return Array(STRING_COUNT).fill('');
   if (labelStyle(labels) === 'numbers') return ['1 ', '2 ', '3 ', '4 ', '5 ', '6 '];
-  const names = tuning.map((name, s) => `${s === 0 ? name.toLowerCase() : name}|`);
+  const names = tuning.map((name, s) => `${s === 0 ? name.toLowerCase() : name} `);
   const width = Math.max(...names.map(name => name.length));
   return names.map(name => name.padEnd(width, ' '));
 };
 const labelWidth = (labels, tuning) => stringLabels(labels, tuning)[0].length;
+const prefixWidth = (labels, tuning, stringBars) => labelWidth(labels, tuning) + (stringBars ? 1 : 0);
 const notationStyle = value => (value === 'letters' || value === 'solfege' ? value : 'frets');
 const NOTE_NAMES = {
   letters: ['C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'],
@@ -176,7 +177,7 @@ function layout(tab, spacing, capacity, notation, tuning, sizes = []) {
 }
 
 // One Tab as plain ASCII, every Staff cut right after its last Column
-function format(tab, { spacing = DEFAULT_SPACING, labels = 'numbers', notation = 'frets', tuning = STANDARD_TUNING, width = Infinity, annotations = [], annotationFit = 'overflow' } = {}) {
+function format(tab, { spacing = DEFAULT_SPACING, labels = 'numbers', stringBars = false, notation = 'frets', tuning = STANDARD_TUNING, width = Infinity, annotations = [], annotationFit = 'overflow' } = {}) {
   tuning = normalizeTuning(tuning);
   annotations = normalizeAnnotations([annotations], [tab])[0] ?? [];
   const names = stringLabels(labels, tuning);
@@ -184,14 +185,14 @@ function format(tab, { spacing = DEFAULT_SPACING, labels = 'numbers', notation =
   if (!columns.length) return '';
   const lead = '-'.repeat(leadingDashes(spacing));
   const trail = '-'.repeat(spacing - lead.length);
-  const capacity = width - labelWidth(labels, tuning);
+  const capacity = width - prefixWidth(labels, tuning, stringBars);
   const sizes = annotationSizes(columns, annotations, normalizeAnnotationFit(annotationFit), { spacing, notation, tuning, capacity });
   return layout(columns, spacing, capacity, notation, tuning, sizes)
     .map(([start, end]) => {
       const offsets = columnOffsets(columns, start, end, spacing, notation, tuning, sizes);
-      const lines = annotationLines(annotations, start, end, offsets, labelWidth(labels, tuning));
+      const lines = annotationLines(annotations, start, end, offsets, prefixWidth(labels, tuning, stringBars));
       for (let s = 0; s < STRING_COUNT; s++) {
-        let line = names[s];
+        let line = names[s] + (stringBars ? '|' : '');
         for (let c = start; c < end; c++) {
           const digits = sizes[c] ?? columnDigits(columns[c], notation, tuning);
           const fret = fretText(columns[c][s], s, notation, tuning);
@@ -229,7 +230,7 @@ function parse(ascii) {
       continue;
     }
     const label = LABEL_PATTERN.exec(line);
-    if (!label && !/^\s*-/.test(line)) return fail(`unexpected line "${line.trim()}"`);
+    if (!label && !/^\s*[-|]/.test(line)) return fail(`unexpected line "${line.trim()}"`);
     const body = label ? line.slice(label[0].length) : line;
     if (!/^[-|\d\s]*$/.test(body.replace(/\(\d*\)/g, ''))) return fail(`unexpected characters in "${line.trim()}"`);
     group.push(body);
@@ -453,6 +454,7 @@ ascii-tabs .ascii-tabs-text-editor:focus { border-bottom-color: var(--ascii-tabs
 
 ascii-tabs .ascii-tabs-line { display: block; height: 1.5em; line-height: 1.5em; }
 ascii-tabs .ascii-tabs-label { color: var(--ascii-tabs-dash); }
+ascii-tabs .ascii-tabs-bar { display: inline-block; flex: 0 0 1ch; }
 ascii-tabs .ascii-tabs-string { color: var(--ascii-tabs-string); }
 ascii-tabs .ascii-tabs-cell {
   display: inline-block; height: 1.5em;
@@ -785,7 +787,7 @@ class AsciiTabs extends Base {
     }
   }
 
-  static observedAttributes = ['readonly', 'spacing', 'labels', 'notation', 'tuning', 'lang', 'tools', 'annotations-editable', 'titles-editable', 'annotation-fit'];
+  static observedAttributes = ['readonly', 'spacing', 'labels', 'string-bars', 'notation', 'tuning', 'lang', 'tools', 'annotations-editable', 'titles-editable', 'annotation-fit', 'max-fret'];
 
   // Strings: the `lang` preset (English by default) with `messages` merged over it
   get #text() {
@@ -830,6 +832,14 @@ class AsciiTabs extends Base {
     this.setAttribute('labels', labelStyle(value));
   }
 
+  get stringBars() {
+    return this.hasAttribute('string-bars');
+  }
+
+  set stringBars(on) {
+    this.toggleAttribute('string-bars', Boolean(on));
+  }
+
   get notation() {
     return notationStyle(this.getAttribute('notation'));
   }
@@ -846,6 +856,16 @@ class AsciiTabs extends Base {
     this.setAttribute('tuning', normalizeTuning(value).join(' '));
   }
 
+  // Highest Fret the editor accepts: 24 by default, lower for instruments with fewer frets
+  get maxFret() {
+    const n = Math.floor(Number(this.getAttribute('max-fret')));
+    return Number.isFinite(n) && n >= 1 && n <= MAX_FRET ? n : MAX_FRET;
+  }
+
+  set maxFret(value) {
+    this.setAttribute('max-fret', value);
+  }
+
   get tools() {
     return toolsPosition(this.getAttribute('tools'));
   }
@@ -881,7 +901,7 @@ class AsciiTabs extends Base {
 
   attributeChangedCallback(name) {
     if (name === 'spacing') return this.#applySpacing();
-    if (name === 'labels' || name === 'tuning') {
+    if (name === 'labels' || name === 'string-bars' || name === 'tuning') {
       this.#measure();
       return this.#render();
     }
@@ -911,7 +931,7 @@ class AsciiTabs extends Base {
       return;
     }
     // Properties set before the element was upgraded shadow the accessors
-    for (const name of ['value', 'columnLayout', 'annotations', 'tabTitles', 'annotationsEditable', 'titlesEditable', 'annotationFit', 'readonly', 'spacing', 'labels', 'notation', 'tuning', 'tools', 'variant', 'theme', 'messages']) {
+    for (const name of ['value', 'columnLayout', 'annotations', 'tabTitles', 'annotationsEditable', 'titlesEditable', 'annotationFit', 'readonly', 'spacing', 'labels', 'stringBars', 'notation', 'tuning', 'maxFret', 'tools', 'variant', 'theme', 'messages']) {
       if (Object.hasOwn(this, name)) {
         const own = this[name];
         delete this[name];
@@ -1110,7 +1130,7 @@ class AsciiTabs extends Base {
     if (!charWidth) return;
     this.#scheduleOverflow();
     const chars = Math.floor(width / charWidth);
-    const capacity = Math.max(chars - labelWidth(this.labels, this.tuning), 4 * (this.#spacing + 1));
+    const capacity = Math.max(chars - prefixWidth(this.labels, this.tuning, this.stringBars), 4 * (this.#spacing + 1));
     const signature = `${width}:${charWidth}`;
     const annotationResized = this.#annotationMeasure !== signature;
     this.#annotationMeasure = signature;
@@ -1188,6 +1208,7 @@ class AsciiTabs extends Base {
         for (let s = 0; s < STRING_COUNT; s++) {
           html += '<span class="ascii-tabs-line">';
           if (labels !== 'none') html += `<span class="ascii-tabs-label" style="flex-basis:${gutter}ch">${names[s]}</span>`;
+          if (this.stringBars) html += '<span class="ascii-tabs-bar ascii-tabs-string" aria-hidden="true">|</span>';
           if (geometry) html += `<span class="ascii-tabs-area" data-t="${t}" data-s="${s}" style="width:${geometry.width}px">`;
           for (let c = start; c < end; c++) {
             const isCur = this.#cur && this.#cur.t === t && this.#cur.c === c && this.#cur.s === s;
@@ -1239,7 +1260,7 @@ class AsciiTabs extends Base {
       const annotations = entries.filter(a => a.column >= start && a.column < end && (a.html ?? a.text));
       if (!annotations.length && !(this.annotationsEditable && !this.readonly)) return;
       const band = this.#el('div', 'ascii-tabs-annotations');
-      if (geometry) band.style.width = `calc(${geometry.width}px + ${labelWidth(this.labels, this.tuning)}ch)`;
+      if (geometry) band.style.width = `calc(${geometry.width}px + ${prefixWidth(this.labels, this.tuning, this.stringBars)}ch)`;
       staff.prepend(band);
       const shown = shownAnnotations(entries);
       for (const entry of annotations) {
@@ -1653,6 +1674,33 @@ class AsciiTabs extends Base {
     this.#goTo(t, c, s + d);
   }
 
+  // Shift+Up/Down: re-finger the focused or selected notes on the nearest String that keeps their
+  // pitch and puts every one of them within 0..maxFret. Strings are assumed to descend in pitch.
+  #refinger(d) {
+    const notes = (this.#selection.length ? this.#selection : [this.#cur]).filter(p => this.#tabs[p.t][p.c]?.[p.s] != null);
+    if (!notes.length) return;
+    const tuning = this.tuning;
+    const depth = [0];
+    for (let s = 1; s < STRING_COUNT; s++) depth[s] = depth[s - 1] + ((tuningPitch(tuning[s - 1]) - tuningPitch(tuning[s]) + 11) % 12 + 1);
+    for (let step = 1; step < STRING_COUNT; step++) {
+      const moved = notes.map(p => {
+        const to = p.s + d * step;
+        const note = this.#tabs[p.t][p.c][p.s];
+        return { ...p, to, fret: fretValue(note) + depth[to] - depth[p.s], note };
+      });
+      if (moved.some(m => m.to < 0 || m.to >= STRING_COUNT || !isFret(m.fret) || m.fret > this.maxFret)) {
+        if (moved.some(m => m.to < 0 || m.to >= STRING_COUNT)) return;
+        continue;
+      }
+      for (const m of moved) this.#setFret(m.t, m.c, m.s, null);
+      for (const m of moved) this.#setFret(m.t, m.c, m.to, typeof m.note === 'object' ? { ...m.note, fret: m.fret } : m.fret);
+      const { t, c, s } = this.#cur;
+      if (this.#selection.length) this.#selection = moved.map(m => ({ t: m.t, c: m.c, s: m.to }));
+      this.#goTo(t, c, s + d * step, this.#selection.length > 0);
+      return this.#emitChange(this.#selection.length ? null : this.#cur);
+    }
+  }
+
   // Typing writes to the value straight away, so `change` follows every keystroke
   #edit(draft, keepParentheses = true) {
     this.#selection = [];
@@ -1670,7 +1718,7 @@ class AsciiTabs extends Base {
   #typeDigit(d) {
     if (this.#draft === null || this.#draft === '') return this.#edit(d);
     const next = this.#draft + d;
-    if (/^(0|[1-9][0-9]?)$/.test(next) && Number(next) <= MAX_FRET) this.#edit(next);
+    if (/^(0|[1-9][0-9]?)$/.test(next) && Number(next) <= this.maxFret) this.#edit(next);
   }
 
   #parenthesize() {
@@ -1751,10 +1799,10 @@ class AsciiTabs extends Base {
         return this.#moveHorizontal(-1);
       case 'ArrowUp':
         e.preventDefault();
-        return this.#moveVertical(-1);
+        return e.shiftKey ? this.#refinger(-1) : this.#moveVertical(-1);
       case 'ArrowDown':
         e.preventDefault();
-        return this.#moveVertical(1);
+        return e.shiftKey ? this.#refinger(1) : this.#moveVertical(1);
       case 'Backspace': {
         e.preventDefault();
         const { t, c, s } = this.#cur;
@@ -1786,7 +1834,7 @@ class AsciiTabs extends Base {
     const last = Math.max(...this.#selection.map(p => p.c));
     const columns = Array.from({ length: last - first + 1 }, emptyColumn);
     for (const { t, c, s } of this.#selection) columns[c - first][s] = this.#tabs[t][c][s];
-    return format(columns, { spacing: this.#spacing, labels: this.labels, notation: this.notation, tuning: this.tuning });
+    return format(columns, { spacing: this.#spacing, labels: this.labels, stringBars: this.stringBars, notation: this.notation, tuning: this.tuning });
   }
 
   #onCopy = e => {
@@ -1975,7 +2023,7 @@ class AsciiTabs extends Base {
   async copy(index = 0) {
     const tab = this.#tabs[index];
     if (!tab) return;
-    await copyText(this.#selection.length && this.#selection[0].t === index ? this.#selectionText() : format(tab, { spacing: this.#spacing, labels: this.labels, notation: this.notation, tuning: this.tuning, width: this.#capacity + labelWidth(this.labels, this.tuning), annotations: this.#annotations[index], annotationFit: this.#annotationFit() }));
+    await copyText(this.#selection.length && this.#selection[0].t === index ? this.#selectionText() : format(tab, { spacing: this.#spacing, labels: this.labels, stringBars: this.stringBars, notation: this.notation, tuning: this.tuning, width: this.#capacity + prefixWidth(this.labels, this.tuning, this.stringBars), annotations: this.#annotations[index], annotationFit: this.#annotationFit() }));
     const button = this.#sheetEls[index]?.querySelector('.ascii-tabs-copy');
     if (!button) return;
     this.#flashCopied(button);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ascii-tabs",
-  "version": "0.10.3",
+  "version": "0.11.2",
   "description": "A zero-dependency web component to write and show guitar tabs as plain ASCII.",
   "type": "module",
   "main": "./ascii-tabs.js",