lyrics-structure 1.0.6 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## [1.2.0] - 2024-03-XX
+
+### Changed
+- Simplified the lyrics format to use clear section markers
+- Updated documentation with clearer examples
+- Improved type definitions for better TypeScript support
+
+### Added
+- Support for section indications in parentheses
+- Better handling of repeated sections
+- More intuitive content structure
+
+### Removed
+- Slide-based content splitting
+- Special command tags
+- Complex formatting options
+
+## [1.1.0] - 2024-03-XX
+
+### Added
+- Initial release
+- `getParts` function for basic content extraction
+- `getSlideParts` function for slide-based content splitting
+- Support for special command tags
+- Comprehensive test suite
+- TypeScript types and documentation
+
+### Features
+- Bracketed section parsing
+- Special command tag handling
+- Slide splitting based on content length
+- Empty line separation
+- Long line handling (>40 characters)
+- Whitespace preservation
+- Unicode support in tags
+
+### Test Coverage
+- Basic functionality tests
+- Slide splitting tests
+- Special command tests
+- Edge case handling 

package/README.md

@@ -1,84 +1,54 @@
-# Lyrics Structure
-
-A utility library for structuring and formatting song lyrics and text content.
-
-## Features
-
-- Split text into natural sections based on structure
-- Process bracketed content while maintaining structure
-- Intelligent text segmentation for readability
-- Efficient handling of repeated sections with simple tag references
-
-## Usage
-
-```typescript
-import { getParts, getSlideParts } from 'lyrics-structure';
-
-// Split text into parts based on bracketed content
-const parts = getParts(text);
-
-// Split text into natural sections for presentation
-const slideParts = getSlideParts(text, maxLinesPerSlide);
-```
-
-## Bracketed Content Format
-
-When structuring your lyrics or text content:
-- Define a section with both opening and closing tags: `[section]content[/section]`
-- For repeated sections, simply use the tag name again: `[section]`
-- The library will automatically reuse the content from the first definition
-
-This approach eliminates redundancy and makes lyric management much simpler, especially for songs with repeated choruses or sections.
-
-## Example
-
-```typescript
-// Example with bracketed content
-const lyrics = `[verse1]
-Morning light breaks through my window
-Another day to find my way
-The journey starts with just one step
-I'm moving forward, come what may
-[/verse1]
-
-[chorus]
-This is the moment, this is the time
-Hearts united, rhythm and rhyme
-Together we rise, together we stand
-Voices in harmony across the land
-[/chorus]
-
-[verse2]
-Challenges come and challenges go
-But strength inside continues to grow
-With every obstacle that I face
-I find my courage, I find my place
-[/verse2]
-
-[chorus]`;
-
-// Get the individual parts (verses and chorus)
-const parts = getParts(lyrics);
-console.log(parts);
-// Output will be an array with the content of verse1, chorus, verse2, and chorus again
-// Note that [chorus] is referenced twice but only defined once
-
-// Get slide-friendly sections
-const slides = getSlideParts(lyrics, 4);
-console.log(slides);
-// Output will break the content into slide-sized chunks with at most 4 lines each
-```
-
-## Implementation
-
-This library is used in the Stage app ([stage.loha.dev](https://stage.loha.dev)) for lyrics display and presentation.
-
-## Installation
-
-```bash
-npm install lyrics-structure
-```
-
-## License
-
-ISC 
+# Lyrics Parser
+
+A TypeScript library for parsing lyrics with bracketed sections and special commands. Supports splitting text into structured parts with names and indications.
+
+## Installation
+
+```bash
+npm install lyrics-parser
+```
+
+## Usage
+
+```typescript
+import { getLyricsParts } from 'lyrics-parser';
+
+const lyrics = `[verse 1] (first time)
+This is the first verse content
+[/verse 1]
+
+[chorus]
+This is the chorus content
+[/chorus]
+
+[verse 2]
+This is the second verse content
+[/verse 2]`;
+
+const parts = getLyricsParts(lyrics);
+// Result: Array of LyricPart objects with name, repetition, indication, and content
+```
+
+## Features
+
+- Extracts content from bracketed sections
+- Handles section names and indications
+- Supports repeated sections
+- Preserves non-bracketed content
+- TypeScript support
+
+## Example Format
+
+```text
+[partname] (indication)
+content
+[/partname]
+
+[another part]
+more content
+[/another part]
+```
+
+## License
+
+MIT 

package/index.ts

@@ -1,175 +1,2 @@
-/**
- * Splits text into parts based on bracketed content while maintaining its structure.
- * Does not consider line length or formatting.
- * 
- * @param text - The input text to be split into parts
- * @returns An array of content strings
- */
-export const getParts = (text?: string): string[] => {
-    if (!text) return [];
-  
-    // Process parts in brackets and create a map
-    const partsMap = new Map<string, string>();
-    
-    // First pass: extract all content with closing tags
-    const cleanedText = text.replace(
-        /\[(.*?)\]([\s\S]*?)\[\/\1\]/g,
-        (match, key, content) => {
-            if (!partsMap.has(key)) {
-                partsMap.set(key, content.trim());
-            }
-            return `[${key}]`;
-        },
-    );
-    
-    // Second pass: handle validation and solo tags that should reuse content
-    const processedText = cleanedText.replace(
-        /\[([^\]]+)\](?!\s*\[\/)(?!\s*\])/g, // Match tags that don't have a closing tag after them
-        (match, key) => {
-            if (partsMap.has(key)) {
-                return match; // Keep the reference if we already have content for this key
-            } else {
-                console.warn(`Warning: Tag [${key}] has no content and was not previously defined`);
-                return ''; // Remove invalid tags
-            }
-        }
-    );
-  
-    const result: string[] = [];
-    const parts = processedText
-        .trim()
-        .split(/\[([^\]]+)\]/)
-        .filter(Boolean);
-  
-    parts.forEach((part) => {
-        if (partsMap.has(part)) {
-            // Add the stored part content
-            result.push(partsMap.get(part)!);
-        } else if (part.trim()) {
-            // Add non-bracketed content
-            result.push(part.trim());
-        }
-    });
-  
-    return result;
-}
-
-/**
- * Splits text into natural sections based on text structure.
- * Works with plain text without requiring markdown or special formatting.
- * Empty lines are treated as natural separators between parts.
- * 
- * @param text - The input text to be split into sections
- * @param maxLinesPerSlide - Maximum number of lines to include in a single slide (default: 6)
- * @returns An array of content sections
- */
-export const getSlideParts = (text?: string, maxLinesPerSlide: number = 6): string[] => {
-    if (!text) return [];
-
-    // Process parts in brackets and create a map for the entire text first
-    const partsMap = new Map<string, string>();
-    
-    // Extract all content with closing tags
-    text.replace(
-        /\[(.*?)\]([\s\S]*?)\[\/\1\]/g,
-        (match, key, content) => {
-            if (!partsMap.has(key)) {
-                partsMap.set(key, content.trim());
-            }
-            return match; // Return original match to not modify the text yet
-        },
-    );
-
-    // Now split by empty lines to respect user-defined separations
-    const paragraphBlocks = text.split(/\n\s*\n/)
-        .filter(block => block.trim().length > 0)
-        .map(block => block.trim());
-    
-    const result: string[] = [];
-    
-    // Process each paragraph block separately
-    paragraphBlocks.forEach(block => {
-        // Check if this block is a solo tag reference
-        const soloTagMatch = block.match(/^\s*\[([^\]]+)\]\s*$/);
-        if (soloTagMatch && partsMap.has(soloTagMatch[1])) {
-            // This is a solo tag reference, process the referenced content
-            const referencedContent = partsMap.get(soloTagMatch[1])!;
-            processContent(referencedContent, result, maxLinesPerSlide);
-        } else {
-            // Process bracketed content within this regular block
-            const blockParts = getParts(block);
-            blockParts.forEach(part => {
-                processContent(part, result, maxLinesPerSlide);
-            });
-        }
-    });
-
-    return result;
-}
-
-/**
- * Helper function to process content and add it to the result array
- */
-function processContent(content: string, result: string[], maxLinesPerSlide: number): void {
-    // Check if content has line breaks that should be respected
-    const lines = content.split('\n').filter(line => line.trim().length > 0);
-    
-    // If we have multiple lines and more than maxLinesPerSlide, create slides based on line count
-    if (lines.length > 1) {
-        if (lines.length > maxLinesPerSlide) {
-            // Break into multiple slides based on maxLinesPerSlide
-            let currentSlide: string[] = [];
-            
-            lines.forEach(line => {
-                if (currentSlide.length >= maxLinesPerSlide) {
-                    result.push(currentSlide.join('\n'));
-                    currentSlide = [];
-                }
-                currentSlide.push(line);
-            });
-            
-            // Add the final slide if it exists
-            if (currentSlide.length > 0) {
-                result.push(currentSlide.join('\n'));
-            }
-        } else {
-            // Just use the whole content as a single slide
-            result.push(content);
-        }
-    } else {
-        // For single large paragraphs (no line breaks), try to find natural sentence groups
-        const sentences = content.split(/(?<=[.!?])\s+/)
-            .filter(s => s.trim().length > 0);
-        
-        // Group sentences into reasonable chunks
-        const sentenceGroups: string[] = [];
-        let currentGroup: string[] = [];
-        let currentLength = 0;
-        
-        sentences.forEach(sentence => {
-            // Natural breakpoint based on content and length
-            // Group 3-5 sentences together or until we reach ~300 chars
-            if (currentGroup.length >= 4 || currentLength > 250) {
-                sentenceGroups.push(currentGroup.join(' '));
-                currentGroup = [];
-                currentLength = 0;
-            }
-            
-            currentGroup.push(sentence);
-            currentLength += sentence.length;
-        });
-        
-        // Add the last group if it exists
-        if (currentGroup.length > 0) {
-            sentenceGroups.push(currentGroup.join(' '));
-        }
-        
-        // If we created multiple groups, use them
-        if (sentenceGroups.length > 1) {
-            result.push(...sentenceGroups);
-        } else {
-            // Otherwise just use the whole part
-            result.push(content);
-        }
-    }
-}
+export * from './slide.js';
+export * from './lyrics.js';

package/jest.config.js

@@ -0,0 +1,14 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+export default {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      useESM: true,
+    }],
+  },
+}; 

package/lyrics.test.ts

@@ -0,0 +1,66 @@
+import { getLyricsParts } from './lyrics';
+
+const testLyrics = `[partname 1] (indication 1)
+
+content 1
+
+[/partname 1]
+
+[partname 1] (indication 2)
+
+[partname 2]
+
+content 2
+
+[/partname 2]
+
+[interlude 1]
+
+[partname 3]
+
+content without partname container`;
+
+describe('getLyricsParts', () => {
+    it('should correctly parse lyrics into parts', () => {
+        const result = getLyricsParts(testLyrics);
+        
+        expect(result).toEqual([
+            {
+                name: 'partname 1',
+                repetition: false,
+                indication: 'indication 1',
+                content: 'content 1'
+            },
+            {
+                name: 'partname 1',
+                repetition: true,
+                indication: 'indication 2',
+                content: 'content 1'
+            },
+            {
+                name: 'partname 2',
+                repetition: false,
+                indication: null,
+                content: 'content 2'
+            },
+            {
+                name: 'interlude 1',
+                repetition: false,
+                indication: null,
+                content: undefined
+            },
+            {
+                name: 'partname 3',
+                repetition: false,
+                indication: null,
+                content: undefined
+            },
+            {
+                name: undefined,
+                repetition: false,
+                indication: null,
+                content: 'content without partname container'
+            }
+        ]);
+    });
+}); 

package/lyrics.ts

@@ -0,0 +1,81 @@
+export type LyricPart = {
+    name: string | undefined;
+    repetition: boolean;
+    indication: string | null;
+    content: string | undefined;
+};
+/**
+ * Splits lyrics into structured parts, handling named sections, repetitions, and indications.
+ * Works with lyrics formatted using square brackets for section names and optional parentheses for indications.
+ * 
+ * Example input:
+ * ```
+ * [verse 1] (first time)
+ * Lyrics content here
+ * [/verse 1]
+ * 
+ * [chorus]
+ * Chorus lyrics
+ * [/chorus]
+ * ```
+ * 
+ * @param lyrics - The input lyrics text to be parsed into parts
+ * @returns Array of LyricPart objects containing structured lyrics data
+ */
+
+export function getLyricsParts(lyrics: string): LyricPart[] {
+    const parts: LyricPart[] = [];
+    const seenParts = new Map<string, number>();
+    const partContentMap = new Map<string, string>();
+
+    // First pass: extract all content with closing tags
+    const cleanedText = lyrics.replace(
+        /\[([^\]]+)\](?:\s*\(([^)]+)\))?\s*([\s\S]*?)\[\/\1\]/g,
+        (match, key: string, indication: string | undefined, content: string) => {
+            if (!partContentMap.has(key)) {
+                partContentMap.set(key, content.trim());
+            }
+            return `[${key}]${indication ? ` (${indication})` : ''}`;
+        }
+    );
+
+    // Split the lyrics into lines and process them
+    const lines = cleanedText.split('\n');
+    let currentPart: LyricPart | null = null;
+
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+
+        // Check for part start
+        const partStartMatch = line.match(/^\[([^\]]+)\](?:\s*\(([^)]+)\))?$/);
+        if (partStartMatch) {
+            const partName = partStartMatch[1];
+            const indication = partStartMatch[2] || null;
+            
+            // Check if this part has been seen before
+            const partCount = (seenParts.get(partName) || 0) + 1;
+            seenParts.set(partName, partCount);
+
+            currentPart = {
+                name: partName,
+                repetition: partCount > 1,
+                indication,
+                content: partContentMap.get(partName)
+            };
+            parts.push(currentPart);
+            continue;
+        }
+
+        // Handle content without a part container
+        if (line && !line.startsWith('[') && !line.startsWith('[/')) {
+            parts.push({
+                name: undefined,
+                repetition: false,
+                indication: null,
+                content: line
+            });
+        }
+    }
+
+    return parts;
+} 

package/package.json

@@ -1,20 +1,26 @@
 {
   "name": "lyrics-structure",
-  "version": "1.0.6",
+  "version": "1.2.0",
+  "description": "Parser for lyrics with structured sections, names, and indications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
-    "test": "node dist/test.js",
-    "build": "tsc"
+    "build": "tsc",
+    "test": "jest",
+    "test:watch": "jest --watch"
   },
-  "keywords": [],
+  "keywords": [
+    "lyrics",
+    "parser",
+    "slides",
+    "sections"
+  ],
   "author": "",
-  "license": "ISC",
-  "type": "module",
-  "description": "",
+  "license": "MIT",
   "devDependencies": {
-    "@types/node": "^22.13.10",
-    "ts-node": "^10.9.2",
-    "typescript": "^5.8.2"
+    "@types/jest": "^29.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
   }
 }

package/slide.test.ts

@@ -0,0 +1,67 @@
+import { getSlideParts } from './slide.js';
+
+describe('Comprehensive Tests', () => {
+    test('handles all cases in one comprehensive input', () => {
+        const comprehensiveInput = `
+[verse]
+First line of verse
+Second line of verse
+Third line of verse
+Fourth line of verse
+Fifth line of verse
+[/verse]
+[verse]
+(inside parentheses)
+Regular text line 1
+Regular text line 2
+
+[chorus]
+First chorus line
+Second chorus line
+[/chorus]
+
+[verse 1]
+This is a very long line that should be considered too long for the slide
+This is another very long line that should also be considered too long
+Short line 1
+Short line 2
+[/verse 1]
+
+Regular line 1
+Regular line 2
+
+More content
+
+This is a very long line that exceeds forty characters for testing purposes
+This is another very long line that also exceeds the forty character limit
+Another very long line that should be considered too long for the slide
+And yet another very long line that should be split into a new section
+Regular line
+
+[verse 2]
+    First line with spaces    
+  Second line with spaces  
+[/verse 2]
+
+[chorus]`;
+
+        expect(getSlideParts(comprehensiveInput)).toEqual([
+            'First line of verse\nSecond line of verse\nThird line of verse\nFourth line of verse',
+            'Fifth line of verse',
+            'First line of verse\nSecond line of verse\nThird line of verse\nFourth line of verse',
+            'Fifth line of verse',
+            'Regular text line 1\nRegular text line 2',
+            'First chorus line\nSecond chorus line',
+            'This is a very long line that should be considered too long for the slide\nThis is another very long line that should also be considered too long',
+            'Short line 1\nShort line 2',
+            'Regular line 1\nRegular line 2',
+            'More content',
+            'This is a very long line that exceeds forty characters for testing purposes\nThis is another very long line that also exceeds the forty character limit',
+            'Another very long line that should be considered too long for the slide\nAnd yet another very long line that should be split into a new section',
+            'Regular line',
+            'First line with spaces\nSecond line with spaces',
+            'First chorus line\nSecond chorus line'
+        ]);
+    });
+
+});