lyrics-structure 1.0.0

package/README.md

@@ -0,0 +1,35 @@
+# 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
+
+## 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);
+```
+
+## 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 

package/index.ts

@@ -0,0 +1,147 @@
+/**
+ * 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.
+ * 
+ * @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 [];
+
+    // Extract bracketed content first
+    const basicParts = getParts(text);
+    const result: string[] = [];
+    
+    basicParts.forEach(part => {
+        // Check if content has line breaks that should be respected
+        const lines = part.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 {
+                // Split by natural paragraph breaks (empty lines)
+                const paragraphs = part.split(/\n\s*\n/)
+                    .filter(p => p.trim().length > 0)
+                    .map(p => p.trim());
+                
+                // If we have multiple paragraphs, use those as natural breaks
+                if (paragraphs.length > 1) {
+                    result.push(...paragraphs);
+                } else {
+                    // Just use the whole part as a single slide
+                    result.push(part);
+                }
+            }
+        } else {
+            // For single large paragraphs (no line breaks), try to find natural sentence groups
+            const sentences = part.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(part);
+            }
+        }
+    });
+
+    return result;
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "lyrics-structure",
+  "version": "1.0.0",
+  "main": "index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "test": "npx ts-node test.ts",
+    "build": "tsc"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "description": "",
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2"
+  }
+}

package/test.ts

@@ -0,0 +1,173 @@
+import * as assert from 'assert';
+import { getParts, getSlideParts } from './index';
+
+// Test data
+const lyricsSample = `
+[verse1]
+I still hear your voice when you sleep next to me
+I still feel your touch in my dreams
+Forgive me my weakness, but I don't know why
+Without you it's hard to survive
+[/verse1]
+
+[chorus]
+'Cause every time we touch, I get this feeling
+And every time we kiss, I swear I could fly
+Can't you feel my heart beat fast?
+I want this to last
+Need you by my side
+[/chorus]
+
+[verse2]
+Your arms are my castle, your heart is my sky
+They wipe away tears that I cry
+The good and the bad times, we've been through them all
+You make me rise when I fall
+[/verse2]
+
+[chorus]
+`;
+
+const bibleSample = `
+In the beginning God created the heavens and the earth. Now the earth was formless and empty, darkness was over the surface of the deep, and the Spirit of God was hovering over the waters.
+
+And God said, "Let there be light," and there was light. God saw that the light was good, and he separated the light from the darkness. God called the light "day," and the darkness he called "night." And there was evening, and there was morning—the first day.
+
+[psalm23]
+The LORD is my shepherd, I lack nothing. 
+He makes me lie down in green pastures, 
+he leads me beside quiet waters, 
+he refreshes my soul.
+[/psalm23]
+
+five
+short
+lines
+should
+be one slide
+
+very long line that should be split into two lines but has been sent on one line intead
+`;
+
+console.log('Running tests for text processing functions...');
+
+// Test getParts with lyrics
+console.log('\n----- Testing getParts with lyrics -----');
+const lyricsParts = getParts(lyricsSample);
+console.log(`Found ${lyricsParts.length} parts`);
+lyricsParts.forEach((part, i) => {
+    console.log(`\nPart ${i + 1}:`);
+    console.log(part);
+});
+assert.strictEqual(lyricsParts.length, 4, 'Should extract 4 parts from lyrics (verse1, chorus, verse2, repeated chorus)');
+
+// Test that the repeated chorus matches the original chorus
+const chorusContent = lyricsParts[1]; // First chorus (index 1)
+const repeatedChorus = lyricsParts[3]; // Last part (index 3) should be repeated chorus
+console.log('\nVerifying repeated chorus:');
+console.log(`Original chorus: "${chorusContent.substring(0, 20)}..."`);
+console.log(`Repeated chorus: "${repeatedChorus.substring(0, 20)}..."`);
+assert.strictEqual(repeatedChorus, chorusContent, 'Repeated chorus should match the original chorus content');
+
+// Test getParts with Bible verses
+console.log('\n----- Testing getParts with Bible verses -----');
+const bibleParts = getParts(bibleSample);
+console.log(`Found ${bibleParts.length} parts`);
+bibleParts.forEach((part, i) => {
+    console.log(`\nPart ${i + 1}:`);
+    console.log(part);
+});
+assert.strictEqual(bibleParts.length, 3, 'Should extract 3 parts from Bible verses (main text, psalm23, and the "five short lines" section)');
+
+// Test getSlideParts with lyrics
+console.log('\n----- Testing getSlideParts with lyrics -----');
+const lyricsSlides = getSlideParts(lyricsSample);
+console.log(`Found ${lyricsSlides.length} slides`);
+lyricsSlides.forEach((slide, i) => {
+    console.log(`\nSlide ${i + 1}:`);
+    console.log(slide);
+});
+// This should now include the repeated chorus
+assert.strictEqual(lyricsSlides.length, 4, 'Should have 4 slides including the repeated chorus');
+
+// Test getSlideParts with Bible verses (default maxLinesPerSlide: 6)
+console.log('\n----- Testing getSlideParts with Bible verses (default maxLinesPerSlide) -----');
+const bibleSlides = getSlideParts(bibleSample);
+console.log(`Found ${bibleSlides.length} slides`);
+bibleSlides.forEach((slide, i) => {
+    console.log(`\nSlide ${i + 1} (${slide.length} characters):`);
+    console.log('-'.repeat(40));
+    console.log(slide);
+    console.log('-'.repeat(40));
+});
+
+// Test getSlideParts with Bible verses and custom maxLinesPerSlide = 2
+console.log('\n----- Testing getSlideParts with Bible verses (maxLinesPerSlide: 2) -----');
+const bibleSlidesTighter = getSlideParts(bibleSample, 2);
+console.log(`Found ${bibleSlidesTighter.length} slides (with maxLinesPerSlide: 2)`);
+bibleSlidesTighter.forEach((slide, i) => {
+    console.log(`\nSlide ${i + 1} (${slide.length} characters):`);
+    console.log('-'.repeat(40));
+    console.log(slide);
+    console.log('-'.repeat(40));
+});
+
+// Test handling of long lines that need to be split
+console.log('\n----- Testing getSlideParts with long lines -----');
+const longLineText = `
+This is a normal line.
+This is another normal line.
+very long line that should be split into two lines but has been sent on one line instead and should be handled properly by the getSlideParts function for better readability
+Last normal line.
+`;
+
+const longLineSlides = getSlideParts(longLineText);
+console.log(`Found ${longLineSlides.length} slides for long line text`);
+longLineSlides.forEach((slide, i) => {
+    console.log(`\nSlide ${i + 1}:`);
+    console.log('-'.repeat(40));
+    console.log(slide);
+    console.log('-'.repeat(40));
+});
+
+// Test edge cases
+console.log('\n----- Testing edge cases -----');
+
+// Empty string
+const emptyResult = getSlideParts('');
+console.log(`Empty string produced ${emptyResult.length} slides`);
+assert.strictEqual(emptyResult.length, 0, 'Empty string should produce 0 slides');
+
+// Single line
+const singleLineResult = getSlideParts('Just one line');
+console.log(`Single line produced ${singleLineResult.length} slides`);
+console.log(singleLineResult[0]);
+assert.strictEqual(singleLineResult.length, 1, 'Single line should produce 1 slide');
+assert.strictEqual(singleLineResult[0], 'Just one line', 'Content should match input');
+
+// Nested tags
+const nestedTagsText = `
+[outer]
+Some text
+[inner]
+Nested content
+[/inner]
+More outer text
+[/outer]
+`;
+
+const nestedParts = getParts(nestedTagsText);
+console.log('\nNested tags test:');
+console.log(`Found ${nestedParts.length} parts`);
+nestedParts.forEach((part, i) => {
+    console.log(`Part ${i + 1}: ${part}`);
+});
+
+// Test with maxLinesPerSlide = 1 (extreme case)
+console.log('\n----- Testing with maxLinesPerSlide = 1 -----');
+const extremeSlides = getSlideParts(bibleSample, 1);
+console.log(`Found ${extremeSlides.length} slides with maxLinesPerSlide = 1`);
+assert.ok(extremeSlides.length > bibleSlides.length, 'Setting maxLinesPerSlide = 1 should produce more slides');
+
+console.log('\nAll tests completed successfully!');
+console.log('\nAll additional tests completed successfully!'); 

package/tsconfig.json

@@ -0,0 +1,113 @@
+{
+  "compilerOptions": {
+    /* Visit https://aka.ms/tsconfig to read more about this file */
+
+    /* Projects */
+    // "incremental": true,                              /* Save .tsbuildinfo files to allow for incremental compilation of projects. */
+    // "composite": true,                                /* Enable constraints that allow a TypeScript project to be used with project references. */
+    // "tsBuildInfoFile": "./.tsbuildinfo",              /* Specify the path to .tsbuildinfo incremental compilation file. */
+    // "disableSourceOfProjectReferenceRedirect": true,  /* Disable preferring source files instead of declaration files when referencing composite projects. */
+    // "disableSolutionSearching": true,                 /* Opt a project out of multi-project reference checking when editing. */
+    // "disableReferencedProjectLoad": true,             /* Reduce the number of projects loaded automatically by TypeScript. */
+
+    /* Language and Environment */
+    "target": "es2016",                                  /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
+    // "lib": [],                                        /* Specify a set of bundled library declaration files that describe the target runtime environment. */
+    // "jsx": "preserve",                                /* Specify what JSX code is generated. */
+    // "libReplacement": true,                           /* Enable lib replacement. */
+    // "experimentalDecorators": true,                   /* Enable experimental support for legacy experimental decorators. */
+    // "emitDecoratorMetadata": true,                    /* Emit design-type metadata for decorated declarations in source files. */
+    // "jsxFactory": "",                                 /* Specify the JSX factory function used when targeting React JSX emit, e.g. 'React.createElement' or 'h'. */
+    // "jsxFragmentFactory": "",                         /* Specify the JSX Fragment reference used for fragments when targeting React JSX emit e.g. 'React.Fragment' or 'Fragment'. */
+    // "jsxImportSource": "",                            /* Specify module specifier used to import the JSX factory functions when using 'jsx: react-jsx*'. */
+    // "reactNamespace": "",                             /* Specify the object invoked for 'createElement'. This only applies when targeting 'react' JSX emit. */
+    // "noLib": true,                                    /* Disable including any library files, including the default lib.d.ts. */
+    // "useDefineForClassFields": true,                  /* Emit ECMAScript-standard-compliant class fields. */
+    // "moduleDetection": "auto",                        /* Control what method is used to detect module-format JS files. */
+
+    /* Modules */
+    "module": "commonjs",                                /* Specify what module code is generated. */
+    // "rootDir": "./",                                  /* Specify the root folder within your source files. */
+    // "moduleResolution": "node10",                     /* Specify how TypeScript looks up a file from a given module specifier. */
+    // "baseUrl": "./",                                  /* Specify the base directory to resolve non-relative module names. */
+    // "paths": {},                                      /* Specify a set of entries that re-map imports to additional lookup locations. */
+    // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
+    // "typeRoots": [],                                  /* Specify multiple folders that act like './node_modules/@types'. */
+    // "types": [],                                      /* Specify type package names to be included without being referenced in a source file. */
+    // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
+    // "moduleSuffixes": [],                             /* List of file name suffixes to search when resolving a module. */
+    // "allowImportingTsExtensions": true,               /* Allow imports to include TypeScript file extensions. Requires '--moduleResolution bundler' and either '--noEmit' or '--emitDeclarationOnly' to be set. */
+    // "rewriteRelativeImportExtensions": true,          /* Rewrite '.ts', '.tsx', '.mts', and '.cts' file extensions in relative import paths to their JavaScript equivalent in output files. */
+    // "resolvePackageJsonExports": true,                /* Use the package.json 'exports' field when resolving package imports. */
+    // "resolvePackageJsonImports": true,                /* Use the package.json 'imports' field when resolving imports. */
+    // "customConditions": [],                           /* Conditions to set in addition to the resolver-specific defaults when resolving imports. */
+    // "noUncheckedSideEffectImports": true,             /* Check side effect imports. */
+    // "resolveJsonModule": true,                        /* Enable importing .json files. */
+    // "allowArbitraryExtensions": true,                 /* Enable importing files with any extension, provided a declaration file is present. */
+    // "noResolve": true,                                /* Disallow 'import's, 'require's or '<reference>'s from expanding the number of files TypeScript should add to a project. */
+
+    /* JavaScript Support */
+    // "allowJs": true,                                  /* Allow JavaScript files to be a part of your program. Use the 'checkJS' option to get errors from these files. */
+    // "checkJs": true,                                  /* Enable error reporting in type-checked JavaScript files. */
+    // "maxNodeModuleJsDepth": 1,                        /* Specify the maximum folder depth used for checking JavaScript files from 'node_modules'. Only applicable with 'allowJs'. */
+
+    /* Emit */
+    "declaration": true,                              /* Generate .d.ts files from TypeScript and JavaScript files in your project. */
+    // "declarationMap": true,                           /* Create sourcemaps for d.ts files. */
+    // "emitDeclarationOnly": true,                      /* Only output d.ts files and not JavaScript files. */
+    // "sourceMap": true,                                /* Create source map files for emitted JavaScript files. */
+    // "inlineSourceMap": true,                          /* Include sourcemap files inside the emitted JavaScript. */
+    // "noEmit": true,                                   /* Disable emitting files from a compilation. */
+    // "outFile": "./",                                  /* Specify a file that bundles all outputs into one JavaScript file. If 'declaration' is true, also designates a file that bundles all .d.ts output. */
+    "outDir": "./dist",                                   /* Specify an output folder for all emitted files. */
+    // "removeComments": true,                           /* Disable emitting comments. */
+    // "importHelpers": true,                            /* Allow importing helper functions from tslib once per project, instead of including them per-file. */
+    // "downlevelIteration": true,                       /* Emit more compliant, but verbose and less performant JavaScript for iteration. */
+    // "sourceRoot": "",                                 /* Specify the root path for debuggers to find the reference source code. */
+    // "mapRoot": "",                                    /* Specify the location where debugger should locate map files instead of generated locations. */
+    // "inlineSources": true,                            /* Include source code in the sourcemaps inside the emitted JavaScript. */
+    // "emitBOM": true,                                  /* Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files. */
+    // "newLine": "crlf",                                /* Set the newline character for emitting files. */
+    // "stripInternal": true,                            /* Disable emitting declarations that have '@internal' in their JSDoc comments. */
+    // "noEmitHelpers": true,                            /* Disable generating custom helper functions like '__extends' in compiled output. */
+    // "noEmitOnError": true,                            /* Disable emitting files if any type checking errors are reported. */
+    // "preserveConstEnums": true,                       /* Disable erasing 'const enum' declarations in generated code. */
+    // "declarationDir": "./",                           /* Specify the output directory for generated declaration files. */
+
+    /* Interop Constraints */
+    // "isolatedModules": true,                          /* Ensure that each file can be safely transpiled without relying on other imports. */
+    // "verbatimModuleSyntax": true,                     /* Do not transform or elide any imports or exports not marked as type-only, ensuring they are written in the output file's format based on the 'module' setting. */
+    // "isolatedDeclarations": true,                     /* Require sufficient annotation on exports so other tools can trivially generate declaration files. */
+    // "erasableSyntaxOnly": true,                       /* Do not allow runtime constructs that are not part of ECMAScript. */
+    // "allowSyntheticDefaultImports": true,             /* Allow 'import x from y' when a module doesn't have a default export. */
+    "esModuleInterop": true,                             /* Emit additional JavaScript to ease support for importing CommonJS modules. This enables 'allowSyntheticDefaultImports' for type compatibility. */
+    // "preserveSymlinks": true,                         /* Disable resolving symlinks to their realpath. This correlates to the same flag in node. */
+    "forceConsistentCasingInFileNames": true,            /* Ensure that casing is correct in imports. */
+
+    /* Type Checking */
+    "strict": true,                                      /* Enable all strict type-checking options. */
+    // "noImplicitAny": true,                            /* Enable error reporting for expressions and declarations with an implied 'any' type. */
+    // "strictNullChecks": true,                         /* When type checking, take into account 'null' and 'undefined'. */
+    // "strictFunctionTypes": true,                      /* When assigning functions, check to ensure parameters and the return values are subtype-compatible. */
+    // "strictBindCallApply": true,                      /* Check that the arguments for 'bind', 'call', and 'apply' methods match the original function. */
+    // "strictPropertyInitialization": true,             /* Check for class properties that are declared but not set in the constructor. */
+    // "strictBuiltinIteratorReturn": true,              /* Built-in iterators are instantiated with a 'TReturn' type of 'undefined' instead of 'any'. */
+    // "noImplicitThis": true,                           /* Enable error reporting when 'this' is given the type 'any'. */
+    // "useUnknownInCatchVariables": true,               /* Default catch clause variables as 'unknown' instead of 'any'. */
+    // "alwaysStrict": true,                             /* Ensure 'use strict' is always emitted. */
+    // "noUnusedLocals": true,                           /* Enable error reporting when local variables aren't read. */
+    // "noUnusedParameters": true,                       /* Raise an error when a function parameter isn't read. */
+    // "exactOptionalPropertyTypes": true,               /* Interpret optional property types as written, rather than adding 'undefined'. */
+    // "noImplicitReturns": true,                        /* Enable error reporting for codepaths that do not explicitly return in a function. */
+    // "noFallthroughCasesInSwitch": true,               /* Enable error reporting for fallthrough cases in switch statements. */
+    // "noUncheckedIndexedAccess": true,                 /* Add 'undefined' to a type when accessed using an index. */
+    // "noImplicitOverride": true,                       /* Ensure overriding members in derived classes are marked with an override modifier. */
+    // "noPropertyAccessFromIndexSignature": true,       /* Enforces using indexed accessors for keys declared using an indexed type. */
+    // "allowUnusedLabels": true,                        /* Disable error reporting for unused labels. */
+    // "allowUnreachableCode": true,                     /* Disable error reporting for unreachable code. */
+
+    /* Completeness */
+    // "skipDefaultLibCheck": true,                      /* Skip type checking .d.ts files that are included with TypeScript. */
+    "skipLibCheck": true                                 /* Skip type checking all .d.ts files. */
+  }
+}