text-guitar-chart 0.0.1

package/lib/fingeringToString.js

@@ -0,0 +1,261 @@
+//@ts-check
+
+/**
+ * Parse a string representation of a guitar fingering into internal format
+ * @param {import("svguitar").Chord} chord
+ * @param {object} [options]
+ * @param {boolean} [options.useUnicode=false] - Whether to use Unicode characters for string/fret markers
+ * @returns {string}
+ */
+export default function fingeringToString(chord, options = {}) {
+  const { useUnicode = false } = options;
+  const { fingers = [], title = "", position } = chord;
+
+  // Parse fingers to build data structure
+  const stringData = new Map(); // Map<string, Map<fret, fingerInfo>>
+  let maxFret = 0;
+  const openStrings = new Set();
+  const mutedStrings = new Set();
+
+  for (const finger of fingers) {
+    const [string, fret, opts = {}] = finger;
+    const optsObject = typeof opts === "object" ? opts : {};
+    const { text = "", color = "#000000" } = optsObject;
+
+    if (fret === 0) {
+      openStrings.add(string);
+    } else if (fret === "x") {
+      mutedStrings.add(string);
+    } else {
+      if (!stringData.has(string)) {
+        stringData.set(string, new Map());
+      }
+      stringData.get(string).set(fret, { text, color });
+      
+      if (fret > maxFret) maxFret = fret;
+    }
+  }
+
+  // Determine number of frets to show
+  const numFrets = fingers.some(f => typeof f[1] === "number" && f[1] > 0)
+    ? Math.max(3, maxFret)
+    : 3;
+
+  if (useUnicode) {
+    return buildUnicodeOutput(
+      title,
+      stringData,
+      openStrings,
+      mutedStrings,
+      numFrets,
+      position
+    );
+  } else {
+    return buildAsciiOutput(
+      title,
+      stringData,
+      openStrings,
+      mutedStrings,
+      numFrets,
+      position
+    );
+  }
+}
+
+/**
+ * Build ASCII format output
+ * @param {string} title
+ * @param {Map<number, Map<number, {text: string, color: string}>>} stringData
+ * @param {Set<number>} openStrings
+ * @param {Set<number>} mutedStrings
+ * @param {number} numFrets
+ * @param {number|undefined} position
+ * @returns {string}
+ */
+function buildAsciiOutput(
+  title,
+  stringData,
+  openStrings,
+  mutedStrings,
+  numFrets,
+  position
+) {
+  const lines = [];
+  
+  // Title section
+  if (title && title.length > 0) {
+    const clampedTitle = title.length > 15 ? title.slice(0, 15) : title;
+    lines.push(`  ${clampedTitle}`);
+    // Add separator line of # characters (exactly 6 chars minimum)
+    lines.push(`  ${'#'.repeat(Math.max(6, clampedTitle.length))}`);
+  }
+
+  // Open/muted strings line - only if there are any
+  if (openStrings.size > 0 || mutedStrings.size > 0) {
+    let openLine = "  ";
+    let lowestMarked = 6; // lowest numbered string (rightmost in display) that has a marker
+    
+    // Find lowest numbered string with a marker
+    for (let str = 6; str >= 1; str--) {
+      if (openStrings.has(str) || mutedStrings.has(str)) {
+        lowestMarked = str;
+      }
+    }
+    
+    // Show from string 6 down to lowestMarked, extending to 3 only if lowestMarked > 4
+    const showTo = lowestMarked > 4 ? 3 : lowestMarked;
+    
+    // Build line from string 6 down to showTo
+    for (let str = 6; str >= showTo; str--) {
+      if (openStrings.has(str)) {
+        openLine += "o";
+      } else if (mutedStrings.has(str)) {
+        openLine += "x";
+      } else {
+        openLine += " ";
+      }
+    }
+    
+    lines.push(openLine.trimEnd());
+  }
+
+  // Separator line before fretboard (always included)
+  lines.push(position === 1 ? "  ======" : "  ------");
+
+  // Fret lines
+  for (let fret = 1; fret <= numFrets; fret++) {
+    let line = "";
+    
+    // Add position number on first fret line if specified
+    if (fret === 1 && position !== undefined && position !== 1) {
+      line = position < 10 ? ` ${position}` : `${position}`;
+    } else {
+      line = "  ";
+    }
+
+    // Build fret line (strings 6 to 1, left to right)
+    for (let str = 6; str >= 1; str--) {
+      const fingerInfo = stringData.get(str)?.get(fret);
+      
+      if (fingerInfo) {
+        if (fingerInfo.color !== "#000000") {
+          line += "*";
+        } else if (fingerInfo.text) {
+          line += fingerInfo.text[0];
+        } else {
+          line += "o";
+        }
+      } else {
+        line += "|";
+      }
+    }
+    
+    lines.push(line);
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Build Unicode format output
+ * @param {string} title
+ * @param {Map<number, Map<number, {text: string, color: string}>>} stringData
+ * @param {Set<number>} openStrings
+ * @param {Set<number>} mutedStrings
+ * @param {number} numFrets
+ * @param {number|undefined} position
+ * @returns {string}
+ */
+function buildUnicodeOutput(
+  title,
+  stringData,
+  openStrings,
+  mutedStrings,
+  numFrets,
+  position
+) {
+  const lines = [];
+  
+  // Title section
+  if (title && title.length > 0) {
+    const clampedTitle = title.length > 15 ? title.slice(0, 15) : title;
+    lines.push(`  ${clampedTitle}`);
+    // Add separator line of # characters (exactly 6 chars minimum)
+    lines.push(`  ${'‾'.repeat(Math.max(11, clampedTitle.length))}`);
+  }
+
+  // Open/muted strings line - only if there are any
+  if (openStrings.size > 0 || mutedStrings.size > 0) {
+    let openLine = "  ";
+    let lowestMarked = 6;
+    
+    // Find lowest numbered string with a marker
+    for (let str = 6; str >= 1; str--) {
+      if (openStrings.has(str) || mutedStrings.has(str)) {
+        lowestMarked = str;
+      }
+    }
+    
+    // Show from string 6 down to lowestMarked, extending to 3 only if lowestMarked > 4
+    const showTo = lowestMarked > 4 ? 3 : lowestMarked;
+    
+    // Build line from string 6 down to showTo with spaces between characters
+    const chars = [];
+    for (let str = 6; str >= showTo; str--) {
+      if (openStrings.has(str)) {
+        chars.push("○");
+      } else if (mutedStrings.has(str)) {
+        chars.push("×");
+      } else {
+        chars.push(" ");
+      }
+    }
+    openLine += chars.join(" ");
+    
+    lines.push(openLine.trimEnd());
+  }
+
+  // Top border
+  lines.push(position === 1 ? "  ╒═╤═╤═╤═╤═╕" : "  ┌─┬─┬─┬─┬─┐");
+
+  // Fret lines
+  for (let fret = 1; fret <= numFrets; fret++) {
+    let line = "";
+    
+    // Add position number on first fret line if specified
+    if (fret === 1 && position !== undefined && position > 1) {
+      line = position < 10 ? ` ${position}` : `${position}`;
+    } else {
+      line = "  ";
+    }
+
+    // Build fret line (strings 6 to 1, left to right)
+    for (let str = 6; str >= 1; str--) {
+      const fingerInfo = stringData.get(str)?.get(fret);
+      
+      if (fingerInfo) {
+        if (fingerInfo.color !== "#000000") {
+          line += "●";
+        } else if (fingerInfo.text) {
+          line += fingerInfo.text[0];
+        } else {
+          line += "○";
+        }
+      } else {
+        line += "│";
+      }
+      if (str > 1) line += " ";
+    }
+    
+    lines.push(line);
+
+    // Add separator or bottom border
+    if (fret < numFrets) {
+      lines.push("  ├─┼─┼─┼─┼─┤");
+    } else {
+      lines.push("  └─┴─┴─┴─┴─┘");
+    }
+  }
+
+  return lines.join("\n");
+}

package/lib/layoutChordStrings.js

@@ -0,0 +1,92 @@
+//@ts-check
+
+/**
+ * Arranges an array of multi-line chord strings into a grid layout with proper padding.
+ * Empty strings are filtered out and trailing spaces are trimmed from each output line.
+ * 
+ * @param {Array<string>} strings - Array of chord strings (can be multi-line)
+ * @param {number} columns - Number of columns per row (default: 3)
+ * @param {number} spacing - Number of spaces between columns (default: 1)
+* @returns {string} - Formatted grid layout string
+ */
+export default function layoutChordStrings(strings, columns = 3, spacing = 1) {
+  // Filter out empty strings
+  const filtered = strings.filter(s => s !== '');
+  
+  // Handle empty array
+  if (filtered.length === 0) {
+    return '';
+  }
+  
+  // Trim trailing newlines from each string
+  const trimmed = filtered.map(s => s.replace(/\n+$/, ''));
+  
+  // Split each string into lines
+  const stringLines = trimmed.map(s => s.split('\n'));
+  
+  // Group strings into rows
+  const rows = [];
+  for (let i = 0; i < stringLines.length; i += columns) {
+    rows.push(stringLines.slice(i, i + columns));
+  }
+  
+  // Calculate max width for each column across all rows
+  const columnWidths = new Array(columns).fill(0);
+  for (const row of rows) {
+    row.forEach((lines, colIndex) => {
+      const maxWidth = Math.max(...lines.map(line => line.length));
+      columnWidths[colIndex] = Math.max(columnWidths[colIndex], maxWidth);
+    });
+  }
+  
+  // Build output
+  const outputRows = [];
+  
+  // Determine spacing strategy based on column width uniformity
+  // If all columns have the same width of 1: use fixed separator with spacing
+  // If all columns have the same width > 1: use 1-space separator (unless spacing overrides)
+  // If columns have different widths: use variable padding for better alignment
+  const allWidthsEqual = columnWidths.length > 0 && columnWidths.every(w => w === columnWidths[0]);
+  const firstWidth = columnWidths[0] || 0;
+  const useFixedSpacing = allWidthsEqual && firstWidth === 1;
+  
+  for (const row of rows) {
+    // Find max height in this row
+    const rowHeight = Math.max(...row.map(lines => lines.length));
+    
+    // Build each line of this row
+    const rowLines = [];
+    for (let lineIdx = 0; lineIdx < rowHeight; lineIdx++) {
+      const lineParts = [];
+      for (let colIdx = 0; colIdx < columns; colIdx++) {
+        const lines = colIdx < row.length ? row[colIdx] : [];
+        const line = lineIdx < lines.length ? lines[lineIdx] : '';
+        
+        if (!useFixedSpacing && colIdx < columns - 1 && colIdx < columnWidths.length - 1) {
+          // Variable padding: based on column widths
+          // Pad to max(current_width + 1, next_width + 1) to ensure proper alignment
+          const padWidth = Math.max(columnWidths[colIdx], columnWidths[colIdx + 1]);
+          lineParts.push(line.padEnd(padWidth + spacing));
+        } else {
+          // Fixed spacing or last column: pad to column width
+          lineParts.push(line.padEnd(columnWidths[colIdx]));
+        }
+      }
+      
+      // Join and trim
+      if (useFixedSpacing) {
+        // Fixed spacing: join with spacing + 1 separator
+        const separator = ' '.repeat(spacing + 1);
+        rowLines.push(lineParts.join(separator).trimEnd());
+      } else {
+        // Variable padding: parts already include spacing
+        rowLines.push(lineParts.join('').trimEnd());
+      }
+    }
+    outputRows.push(rowLines.join('\n'));
+  }
+  
+  // Use spacing to determine the number of blank lines between rows
+  const rowSeparator = '\n'.repeat(spacing + 1);
+  return outputRows.join(rowSeparator);
+}

package/lib/splitStringInRectangles.js

@@ -0,0 +1,132 @@
+//@ts-check
+
+/**
+ * This function takes a string and splits it into an array of strings,
+ * each of the strings is a rectangle present in the original string and
+ * separated by spaces
+ * 
+ * How it works:
+ * - convert the string into a 2D array of characters
+ * - scan the array left to right and top to bottom to find a non space character
+ * - once found search all adjacent non space characters using breadth first search, 
+ * Consider horizontal, vertical and diagonal adjacency
+ * - once exhausted the search, determine the rectangle that bounds all found characters
+ * - extract the rectangle as a string and add it to the result array
+ * - mark all characters in the rectangle as visited (set to space)
+ * - continue scanning the array until all characters are visited
+ * @param {string} str
+ * @returns {Array<string>}
+ */
+export default function splitStringInRectangles(str) {
+  // Early validation
+  if (!str || str.trim() === '') {
+    return [];
+  }
+
+  // Convert string to 2D array of characters
+  const grid = str.split('\n').map(line => line.split(''));
+  const result = [];
+
+  // 8 directions: horizontal, vertical, and diagonal
+  const directions = [
+    [-1, -1], [-1, 0], [-1, 1],
+    [0, -1],           [0, 1],
+    [1, -1],  [1, 0],  [1, 1]
+  ];
+
+  /**
+   * BFS to find all connected non-space characters
+   * @param {number} startRow
+   * @param {number} startCol
+   * @returns {{minRow: number, maxRow: number, minCol: number, maxCol: number, positions: Array<[number, number]>}}
+   */
+  function bfs(startRow, startCol) {
+    const queue = [[startRow, startCol]];
+    /** @type {Array<[number, number]>} */
+    const positions = [[startRow, startCol]];
+    let minRow = startRow;
+    let maxRow = startRow;
+    let minCol = startCol;
+    let maxCol = startCol;
+
+    // Mark starting position as visited
+    grid[startRow][startCol] = ' ';
+
+    while (queue.length > 0) {
+      const [row, col] = queue.shift();
+
+      // Check all 8 directions
+      for (const [dr, dc] of directions) {
+        const newRow = row + dr;
+        const newCol = col + dc;
+
+        // Check bounds
+        if (newRow >= 0 && newRow < grid.length &&
+            newCol >= 0 && newCol < grid[newRow].length) {
+          // Check if non-space character
+          if (grid[newRow][newCol] !== ' ') {
+            queue.push([newRow, newCol]);
+            positions.push([newRow, newCol]);
+
+            // Update bounding rectangle
+            minRow = Math.min(minRow, newRow);
+            maxRow = Math.max(maxRow, newRow);
+            minCol = Math.min(minCol, newCol);
+            maxCol = Math.max(maxCol, newCol);
+
+            // Mark as visited
+            grid[newRow][newCol] = ' ';
+          }
+        }
+      }
+    }
+
+    return { minRow, maxRow, minCol, maxCol, positions };
+  }
+
+  /**
+   * Extract rectangle string from positions
+   * @param {{minRow: number, maxRow: number, minCol: number, maxCol: number, positions: Array<[number, number]>}} bounds
+   * @returns {string}
+   */
+  function extractRectangle(bounds) {
+    const { minRow, maxRow, minCol, maxCol, positions } = bounds;
+    const height = maxRow - minRow + 1;
+    const width = maxCol - minCol + 1;
+
+    // Create 2D array filled with spaces
+    const rectGrid = Array(height).fill(null).map(() => Array(width).fill(' '));
+
+    // Place characters at their relative positions
+    for (const [row, col] of positions) {
+      const relRow = row - minRow;
+      const relCol = col - minCol;
+      // Get original character from input (before it was marked as space)
+      const lines = str.split('\n');
+      if (row < lines.length && col < lines[row].length) {
+        rectGrid[relRow][relCol] = lines[row][col];
+      }
+    }
+
+    // Convert to string, preserving internal spaces
+    return rectGrid
+      .map(row => row.join(''))
+      .join('\n');
+  }
+
+  // Scan grid left to right, top to bottom
+  for (let row = 0; row < grid.length; row++) {
+    for (let col = 0; col < grid[row].length; col++) {
+      // Find non-space character
+      if (grid[row][col] !== ' ') {
+        // BFS to find all connected characters
+        const bounds = bfs(row, col);
+        // Extract rectangle and add to result
+        const rectangle = extractRectangle(bounds);
+        result.push(rectangle);
+      }
+    }
+  }
+
+  return result;
+}