text-guitar-chart 0.0.1

package/AGENTS.md

@@ -0,0 +1,18 @@
+AGENTS.md - Repository Agent Guidelines
+Build: `npm install`; Types: `npm run build:types` (tsc JSDoc declarations only).
+Test all: `npm test` (runs Node builtin test runner on `test/*.test.js`).
+Watch tests: `npm run test:watch`.
+Single test file: `node --test test/editableSVGuitar.test.js`.
+Single test by name: `node --test test/editableSVGuitar.test.js --test-name-pattern 'EditableSVGuitarChord'`.
+No linter configured; keep style consistent; propose ESLint only if requested (do not add unasked).
+Modules: ESM (`"type":"module"`); always include `.js` extension in relative imports.
+Exports: prefer named exports; update `types/` via build when adding API.
+Formatting: 2-space indent, semicolons, trailing commas only where existing pattern; keep lines < 100 chars.
+Naming: constants/enums UPPER_SNAKE_CASE; functions & variables camelCase; generators use verbNoun (e.g., generateInversions).
+Types: use JSDoc `@typedef`, `@template`, `@param`, `@returns`; keep `//@ts-check` at top of new JS files.
+Data structures: prefer immutable operations; clearly document and minimize in-place mutation.
+Tests: use `describe` + `test`; assertions via `node:assert/strict`; avoid flaky/time-based tests.
+Test additions: place in `test/` with `.test.js`; keep one concern per `describe`; avoid console logs (remove debug prints).
+Performance: prefer simple loops over heavy abstractions in hot paths; avoid allocating inside tight generators unnecessarily.
+Public API stability: avoid breaking existing exported names; add new exports rather than renaming.
+Do not add new tooling/config (linters, formatters, CI) unless explicitly requested.

package/FORMAT.md

@@ -0,0 +1,277 @@
+# How to represent a fingering using text
+
+2 formats are supported. A concise ascii one that is designed to be edited easily and a nicer one that uses unicode, looks better but is more difficult to edit.
+
+## General rules and semantic
+The diagram represent a fragment of a guitar fretboard with low pitch string on the left and high pitch on the right. They are formed by 3 sections:
+- title (optional)
+- open strings (optional)
+- fretboard (mandatory)
+
+### String numbering
+Strings are numbered 1-6 from right to left in the diagram. In standard guitar tuning:
+- String 6 (leftmost) is the lowest pitch (E2)
+- String 1 (rightmost) is the highest pitch (E4)
+
+### Color values
+The format supports two colors for fingering markers:
+- `#000000` (black) for regular fingering positions
+- `#e74c3c` (red/root marker color) for special positions (typically root notes)
+
+Any color value other than `#000000` is treated as a root marker and rendered with the special marker symbol.
+
+## ascii format
+
+### title section
+The title (optional) is max 15 characters all on the same line. If this section is included it is separated from the section underneath by a line of "#". The line is as long as the title above, with a minimum of 6 characters.
+
+### open string section
+The open string section is optional and separated from the section underneath by "------" or "======". This separator is always included as it is the first line of the fretboard section.
+- "------" is used when no fret position is set, or when the fret position is written on the first line of the fretboard section (including position 1)
+- "======" is used as an alternate representation when the fret position is 1 (in this case, the position number is not written on the fretboard line)
+
+Note: Position 1 can be represented in two ways:
+1. Using "------" with " 1" written on the first fretboard line
+2. Using "======" with no position number on the fretboard line
+
+This section contains up to 6 elements (one for each string). Trailing spaces are trimmed from the line. Each position can be:
+- " " (space) means that the string at this position is neither muted nor played
+- "x" means that the string at this position is muted
+- "o" means that the string at this position is played (open string) 
+
+### fretboard section
+This section is mandatory and at least 3 rows long (3 frets).
+The first line can optionally have an indication of the starting fret on the left, right-justified in a 2-character field (e.g., " 5" for fret 5, "15" for fret 15).
+
+These different characters are used:
+- "|" indicates that there is no fingering in this position
+- "o" indicates that this position is fingered with a regular dot (color #000000)
+- "*" indicates that this position is fingered with a root marker (non-black color, typically #e74c3c)
+- any other character is displayed as text on the fretboard at that position (commonly used for finger numbers or note names)
+
+Examples:
+
+```
+  A min
+  ######
+  oo   o
+  ------
+  ||||o|
+  ||o*||
+  ||||||
+
+  D
+  ######
+  xoo
+  ------
+  ||||||
+  |||o|o
+  ||||*|
+
+  G 7
+  ######
+  xx
+  ------
+ 5||*|||
+  ||||o|
+  |||o|o
+
+  E dom 7
+  #######
+  x    x
+  ------
+  |||3||
+  |51|||
+  ||||7|
+
+  Dominant 7
+  ##########
+  xx
+  ======
+  ||*|||
+  ||||o|
+  |||o|o
+
+```
+
+## unicode format
+
+### title section
+The title (optional) is max 15 characters all on the same line. If this section is included it is separated from the section underneath by a line of "‾". The line is as long as the title above and at least 11 characters
+
+### open string section
+The open string section is optional and separated from the section underneath by "┌─┬─┬─┬─┬─┐" or "╒═╤═╤═╤═╕". This separator is always included as it is the first line of the fretboard section.
+- "┌─┬─┬─┬─┬─┐" is used when no fret position is set, or when the fret position is written on the second line of the fretboard section (including position 1)
+- "╒═╤═╤═╤═╕" is used as an alternate representation when the fret position is 1 (in this case, the position number is not written on the fretboard)
+
+Note: Position 1 can be represented in two ways:
+1. Using "┌─┬─┬─┬─┬─┐" with " 1" written on the second line of the fretboard section
+2. Using "╒═╤═╤═╤═╕" with no position number on the fretboard
+
+This section contains up to 6 elements (one for each string) separated by spaces. Trailing spaces are trimmed from the line. Each position can be:
+- " " (space) means that the string at this position is neither muted nor played
+- "×" means that the string at this position is muted
+- "○" means that the string at this position is played (open string)
+
+### fretboard section
+This section is mandatory and at least 3 frets long. It is built as a grid:
+```
+  ┌─┬─┬─┬─┬─┐
+  │ │ │ │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ │ │
+  └─┴─┴─┴─┴─┘
+```
+The second line can optionally have an indication of the starting fret on the left, right-justified in a 2-character field (e.g., " 5" for fret 5, "15" for fret 15).
+
+The even rows contain characters representing the fingering:
+- "│" indicates that there is no fingering in this position
+- "○" indicates that this position is fingered with a regular dot (color #000000)
+- "●" indicates that this position is fingered with a root marker (non-black color, typically #e74c3c)
+- any other character is displayed as text on the fretboard at that position (commonly used for finger numbers or note names)
+
+Example:
+```
+  A minor
+  ‾‾‾‾‾‾‾‾‾‾‾
+  ○ ○       ○
+  ╒═╤═╤═╤═╤═╕
+  │ │ │ │ ○ │
+  ├─┼─┼─┼─┼─┤
+  │ │ ○ ● │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ │ │
+  └─┴─┴─┴─┴─┘
+
+  D
+  ‾‾‾‾‾‾‾‾‾‾‾
+  × ○ ○
+  ╒═╤═╤═╤═╤═╕
+  │ │ │ │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ ○ │ ○
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ ● │
+  └─┴─┴─┴─┴─┘
+
+  G 7
+  ‾‾‾‾‾‾‾‾‾‾‾
+  × ×
+  ┌─┬─┬─┬─┬─┐
+ 5│ │ ● │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ ○ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ ○ │ ○
+  └─┴─┴─┴─┴─┘
+
+  E dom 7
+  ‾‾‾‾‾‾‾‾‾‾‾
+  ×         ×
+  ┌─┬─┬─┬─┬─┐
+  │ │ │ 3 │ │
+  ├─┼─┼─┼─┼─┤
+  │ 5 1 │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ 7 │
+  └─┴─┴─┴─┴─┘
+
+  Dominant 7
+  ‾‾‾‾‾‾‾‾‾‾‾
+  × ×
+  ╒═╤═╤═╤═╤═╕
+  │ │ ● │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ ○ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ ○ │ ○
+  └─┴─┴─┴─┴─┘
+
+```
+
+## Edge cases and special behaviors
+
+### Missing sections
+- If no title is provided, the title and separator lines are omitted
+- If no open strings are defined (no string with fret 0 or "x"), the open string section is omitted
+- The fretboard section is always present (minimum 3 frets)
+
+### Empty chords
+An empty chord (no fingerings) renders as just the fretboard grid with no markers.
+
+ASCII format:
+```
+  ------
+  ||||||
+  ||||||
+  ||||||
+```
+
+Unicode format:
+```
+  ┌─┬─┬─┬─┬─┐
+  │ │ │ │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ │ │
+  └─┴─┴─┴─┴─┘
+```
+
+### All open strings
+All six strings can be marked as open.
+
+ASCII format:
+```
+  E major
+  #######
+  oooooo
+  ------
+  ||||||
+  ||||||
+  ||||||
+```
+
+Unicode format:
+```
+  E major
+  ‾‾‾‾‾‾‾‾‾‾‾
+  ○ ○ ○ ○ ○ ○
+  ╒═╤═╤═╤═╤═╕
+  │ │ │ │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ │ │
+  └─┴─┴─┴─┴─┘
+```
+
+### All muted strings
+All six strings can be marked as muted.
+
+ASCII format:
+```
+  Muted
+  #####
+  xxxxxx
+  ------
+  ||||||
+  ||||||
+  ||||||
+```
+
+Unicode format:
+```
+  Muted
+  ‾‾‾‾‾‾‾‾‾‾‾
+  × × × × × ×
+  ┌─┬─┬─┬─┬─┐
+  │ │ │ │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ │ │
+  ├─┼─┼─┼─┼─┤
+  │ │ │ │ │ │
+  └─┴─┴─┴─┴─┘
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 text-guitar-chart
+
+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

@@ -0,0 +1,41 @@
+# Text Guitar Chart
+
+This library allows to write fretboard charts in a text format that is easy to read. It also includes utilities to convert the charts in svg using [svguitar](https://github.com/omnibrain/svguitar).
+
+See the [format](FORMAT.md)
+
+# How to use
+Use [the editor](https://sithmel.github.io/text-guitar-chart/) to edit the fingering you like. Copy paste the fretboard chart wherever you like!
+
+# Utilities
+Here is a list of utilities it provides:
+- EditableSVGuitarChord an editable chord chart utility
+- stringToFingering transforms a text representation of a fingering into data that can be used to render that fingering using SVGuitar
+- fingeringToString transforms SVGuitar data format into a text representation of a fingering
+
+## TypeScript Support
+
+This library includes TypeScript declarations generated from JSDoc comments:
+
+```bash
+npm run build:types
+```
+
+## Development
+
+### Running Tests
+
+```bash
+npm test
+npm run test:watch  # Watch mode
+```
+
+### Generate Type Declarations
+
+```bash
+npm run build:types
+```
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

package/docs/app.js

@@ -0,0 +1,172 @@
+//@ts-check
+import { EditableSVGuitarChord } from '../lib/editableSVGuitar.js';
+import { SVGuitarChord } from 'svguitar';
+import splitStringInRectangles from '../lib/splitStringInRectangles.js';
+import stringToFingering from '../lib/stringToFingering.js';
+import layoutChordStrings from '../lib/layoutChordStrings.js';
+
+/** @type {HTMLElement} */
+const editor = /** @type {HTMLElement} */(document.getElementById('editor'));
+/** @type {HTMLElement} */
+const output = /** @type {HTMLElement} */(document.getElementById('output'));
+/** @type {HTMLElement} */
+const outputAscii = /** @type {HTMLElement} */(document.getElementById('output-ascii'));
+/** @type {HTMLElement} */
+const outputUnicode = /** @type {HTMLElement} */(document.getElementById('output-unicode'));
+
+
+if (!editor || !outputAscii || !outputUnicode) {
+  throw new Error('Required DOM elements not found');
+}
+
+const editable = new EditableSVGuitarChord(editor)
+  .chord({ fingers: [], barres: [] })
+  .configure({ frets: 5, noPosition: true })
+  .draw();
+
+editable.onChange(() => {
+  updateJSON();
+});
+
+/** Update JSON panel */
+function updateJSON() {
+  output.textContent = JSON.stringify(editable.getChord(), null, 2);
+  outputAscii.textContent = editable.toString({ useUnicode: false });
+  outputUnicode.textContent = editable.toString({ useUnicode: true });
+}
+
+document.getElementById('clear')?.addEventListener('click', () => {
+  editable.chord({ fingers: [], barres: [] }).redraw();
+  updateJSON();
+});
+
+document.getElementById('copy-json')?.addEventListener('click', () => {
+  navigator.clipboard.writeText(output.textContent || '').catch(err => {
+    console.error('Failed to copy JSON:', err);
+  });
+});
+
+document.getElementById('copy-ascii')?.addEventListener('click', () => {
+  navigator.clipboard.writeText(outputAscii.textContent || '').catch(err => {
+    console.error('Failed to copy ASCII:', err);
+  });
+});
+
+document.getElementById('copy-unicode')?.addEventListener('click', () => {
+  navigator.clipboard.writeText(outputUnicode.textContent || '').catch(err => {
+    console.error('Failed to copy Unicode:', err);
+  });
+});
+
+// Initial panel fill
+updateJSON();
+
+// Tab switching
+document.getElementById('tab-editor')?.addEventListener('click', () => {
+  document.getElementById('tab-editor')?.classList.add('active');
+  document.getElementById('tab-batch')?.classList.remove('active');
+  document.getElementById('interactive-editor')?.classList.add('active');
+  document.getElementById('batch-converter')?.classList.remove('active');
+});
+
+document.getElementById('tab-batch')?.addEventListener('click', () => {
+  document.getElementById('tab-batch')?.classList.add('active');
+  document.getElementById('tab-editor')?.classList.remove('active');
+  document.getElementById('batch-converter')?.classList.add('active');
+  document.getElementById('interactive-editor')?.classList.remove('active');
+});
+
+// Batch conversion
+document.getElementById('convert-btn')?.addEventListener('click', () => {
+  const textarea = /** @type {HTMLTextAreaElement} */(document.getElementById('batch-input'));
+  const chordGrid = document.getElementById('chord-grid');
+  
+  if (!textarea || !chordGrid) {
+    console.error('Required elements not found');
+    return;
+  }
+
+  const input = textarea.value;
+  if (!input.trim()) {
+    console.warn('No input provided');
+    return;
+  }
+
+  try {
+    // Clear previous results
+    chordGrid.innerHTML = '';
+
+    // Split input into rectangles
+    const rectangles = splitStringInRectangles(input);
+    
+    if (rectangles.length === 0) {
+      console.warn('No chord diagrams found in input');
+      return;
+    }
+
+    // Convert each rectangle to a chord and render
+    rectangles.forEach((rectangle, index) => {
+      try {
+        const chordConfig = stringToFingering(rectangle);
+        if (chordConfig == null) {
+          return;
+        }
+        
+        // Create container for this chord
+        const container = document.createElement('div');
+        container.className = 'chord-container';
+        chordGrid.appendChild(container);
+
+        // Render the chord
+        const chart = new SVGuitarChord(container);
+        const frets = Math.max(...chordConfig.fingers.map(f => (typeof f[1] === 'number' ? f[1] : 0)), 3);
+        const noPosition = chordConfig.position === 0 || (chordConfig.position === undefined);
+        chart
+          .chord(chordConfig)
+          .configure({ frets, noPosition })
+          .draw();
+      } catch (err) {
+        console.error(`Error rendering chord ${index + 1}:`, err);
+      }
+    });
+  } catch (err) {
+    console.error('Error during batch conversion:', err);
+  }
+});
+
+/**
+ * 
+ * @param {number} columnNumber 
+ */
+function layout (columnNumber){
+  const textarea = /** @type {HTMLTextAreaElement} */(document.getElementById('batch-input'));
+    if (!textarea) {
+    console.error('Required elements not found');
+    return;
+  }
+
+  const input = textarea.value;
+  if (!input.trim()) {
+    console.warn('No input provided');
+    return;
+  }
+  // Split input into rectangles
+  const rectangles = splitStringInRectangles(input);
+  const layout = layoutChordStrings(rectangles, columnNumber, 3);
+  textarea.value = layout;
+}
+
+// Batch conversion
+document.getElementById('layout-2-btn')?.addEventListener('click', () => {
+  layout(2);
+});
+
+// Batch conversion
+document.getElementById('layout-3-btn')?.addEventListener('click', () => {
+  layout(3);
+});
+
+// Batch conversion
+document.getElementById('layout-4-btn')?.addEventListener('click', () => {
+  layout(4);
+});