kashi 1.0.2 → 1.1.1

package/README.md

@@ -1,3 +1,10 @@
+<div align="center">
+  <a href="https://gitlab.com/lucasmc64/kashi">GitLab</a> • 
+  <a href="https://www.npmjs.com/package/kashi">NPM</a> • 
+  <a href="https://unpkg.com/browse/kashi@latest">CDN</a> • 
+  <a href="https://ko-fi.com/lucasmc64">Ko-fi</a>
+</div>
+
 ![Kashi](https://gitlab.com/lucasmc64/kashi/-/raw/main/readme/cover.png)
 
 # 🎤 Kashi
@@ -6,32 +13,16 @@
 
 This project is a dependency-free library that aims to provide a way to correctly read, format, structure, and display song lyrics.
 
-## 📜 Some details
-
-This project was created using tools to make development as easy as possible:
-
-- [Node.JS](https://nodejs.org/)
-  It is only necessary to globally install the following packages that facilitate development.
-  
-- [Webpack](https://webpack.js.org/)
-  A static module bundler for modern JavaScript/TypeScript applications.
-
-## 🪬 Overview
-
-### 🔗 Useful links
-
-**Repository**: https://gitlab.com/lucasmc64/kashi
+## 📜 Features
 
-**CDN**: https://unpkg.com/browse/kashi@latest
-
-**Website**: -
-
-### 🐙 Repository details
-
-Below is the branch structure/pattern created for this project:
-
-- **main**: If there is more than one developer or the sprint tasks are divided, this will be the place to gather the codes and resolve conflicts before the modifications go to testing.
-- **TG-(number)**: It covers all the code produced to meet the needs exposed by a task and uses the same code as the task created in Taiga.
+- [x] 🎵 Process and list song lyrics in .lrc files
+- [x] 💪 Supports both directly inputting the .lrc file and a URL that returns it
+- [x] ✉️ Implements the Observer pattern and emits events at each step of the process whenever something changes
+- [x] ✏️ Allows you to enter custom text when the lyrics line is empty
+- [ ] 🎤 Synchronizes the lyrics with the music that is playing
+- [ ] 🎩 Supports multiple lyrics for the same song (useful to keep track of the original lyrics and their translation)
+- [ ] 🧞 Supports the [Walaoke extension](https://en.wikipedia.org/wiki/LRC_(file_format)#Walaoke_extension)
+- [ ] 🕖️ Supports the [A2 extension](https://en.wikipedia.org/wiki/LRC_(file_format)#A2_extension_(Enhanced_LRC_format))
 
 ## 🎨 How to use it in my project?
 
@@ -77,7 +68,11 @@ The HTML is very similar to the classic scripts version, just change the `.js` e
 > **Note**: Please read the [previous section](#classic-scripts) to get the details involved in importing and choosing a package version, they are the same here.
 
 ```html
-<script src="https://unpkg.com/kashi@X.Y.Z/kashi.mjs" type="module" defer></script>
+<script
+  src="https://unpkg.com/kashi@X.Y.Z/kashi.mjs"
+  type="module"
+  defer
+></script>
 ```
 
 ```javascript
@@ -133,18 +128,65 @@ export const KashiWrapper = (props: KashiProps) => {
 };
 ```
 
-## 🧐 Properties and options
+## 🧐 Constructor properties
 
 You must pass some properties to Kashi to define what lyrics display and where. Here are its specifications:
 
-| Property    | Type             | Default value | Is required? | Description                               |
-| ----------- | ---------------- | ------------- | ------------ | ----------------------------------------- |
-| `file`      | `Blob` or `File` | -             | No           | Lyrics file                               |
-| `url`       | `string`         | -             | No           | Lyrics url                                |
-| `container` | `HTMLDivElement` | -             | Yes          | Element where the lyrics will be inserted |
+| Property        | Type               | Default value | Is required? | Description                               |
+| --------------- | ------------------ | ------------- | ------------ | ----------------------------------------- |
+| `file`          | `Blob` (or `File`) | -             | No           | Lyrics file                               |
+| `url`           | `string`           | -             | No           | Lyrics url                                |
+| `container`     | `HTMLDivElement`   | -             | Yes          | Element where the lyrics will be inserted |
+| `emptyLineText` | `string`           | `🎝`           | No           | Custom text for empty lines of the lyrics |
 
 > Neither `file` nor `url` are “mandatory”, but **at least one of these properties must be specified**, otherwise an error will be thrown.
 
+## 👾 Generated HTML structure
+
+The `div#kashi` represents the `container` passed to `Kashi` where the song lyrics will be inserted.
+
+Each line of lyrics present in the lrc file will be wrapped by a `<p></p>` tag and inserted into the `container`.
+
+Here's an example:
+
+```html
+<div id="kashi">
+  <!-- ... -->
+  <p>Binkusu no sake wo todoke ni yuku yo</p>
+  <p>Umikaze kimakase namimakase</p>
+  <p>Shio no mukou de yuuhi mo sawagu</p>
+  <p>Sora nya wa wo kaku tori no uta</p>
+  <!-- ... -->
+</div>
+```
+
+## 📂 Methods and attributes
+
+The instance generated by `Kashi` has some public methods and attributes that can be used to query or change properties on the fly.
+
+| Name               | Type      | Description                                                  |
+| ------------------ | --------- | ------------------------------------------------------------ |
+| `url`              | Attribute | Returns the url from the current lyrics if it was fetched from a link |
+| `file`             | Attribute | Returns the file from the current lyrics                     |
+| `emptyLineText`    | Attribute | Returns the default text set for empty lines                 |
+| `setUrl`           | Method    | Function capable of changing the current lyrics file by passing the **url** of the new file |
+| `setFile`          | Method    | Function capable of changing the current lyrics file by passing the the new **file** |
+| `setEmptyLineText` | Method    | Function capable of changing the text defined for empty lines |
+| `subscribe`        | Method    | Function capable of defining a callback to be executed when a given event is triggered |
+| `unsubscribe`      | Method    | Function capable of making a callback to stop listening to an event |
+| `notify`           | Method    | Function capable of triggering an event                      |
+
+## 🍾 Events
+
+When creating a new instance using `Kashi` you will have access to the `subscribe`, `unsubscribe` and `notify` methods, these methods can be used respectively to listen for an event, stop listening for an event and manually trigger an event. Below is the list of events triggered internally:
+
+| Event               | Data                        | Trigger                                                      |
+| ------------------- | --------------------------- | ------------------------------------------------------------ |
+| `urlSet`            | `{ url: string }`           | When instantiating by informing `url` or calling the `setUrl` method |
+| `fileSet`           | `{ file: Blob }`            | When instantiating or calling the `setFile` method (when calling the `setUrl` method the file will be fetched and the `setFile` method called) |
+| `emptyLineTextSet`  | `{ emptyLineText: string }` | When instantiating by informing `emptyLineText` or calling the `setEmptyLineText` method |
+| `lyricLinesUpdated` | `{ lyricLines: string[] }`  | When inserting/updating lyrics in HTML                       |
+
 ## 🤔 How do I run the project on my machine?
 
 The first step is to clone the project, either via terminal or even by downloading the compressed file (.zip). After that, go ahead.
@@ -165,7 +207,7 @@ You can also create a demo project using React and use [npm link](https://docs.n
 
 Now you are running the project beautifully!
 
-### ✏️ License
+## ✏️ License
 
 This project is under the GPL v3 license. See the [LICENSE](https://gitlab.com/lucasmc64/kashi/-/blob/main/LICENSE) for more information.
 

package/kashi.d.ts

@@ -0,0 +1,28 @@
+// Generated by dts-bundle-generator v9.5.1
+
+export type KashiUrl = string | null;
+export type KashiFile = Blob | null;
+export type EventName = string;
+export type EventData = any;
+export type EventCallback = (data: EventData) => void;
+export interface KashiProps {
+	url?: KashiUrl;
+	file?: KashiFile;
+	container: HTMLDivElement;
+	emptyLineText?: string;
+}
+export declare class Kashi {
+	#private;
+	constructor(props: KashiProps);
+	get url(): KashiUrl;
+	get file(): KashiFile;
+	get emptyLineText(): string;
+	setUrl(url: string): Promise<void>;
+	setFile(file: Blob): Promise<void>;
+	setEmptyLineText(text: string): void;
+	subscribe(event: EventName, fn: EventCallback): void;
+	unsubscribe(event: EventName, fn: EventCallback): void;
+	notify(event: EventName, data?: EventData): void;
+}
+
+export {};

package/kashi.js

@@ -1 +1 @@
-!function(e,t){if("object"==typeof exports&&"object"==typeof module)module.exports=t();else if("function"==typeof define&&define.amd)define([],t);else{var r=t();for(var i in r)("object"==typeof exports?exports:e)[i]=r[i]}}(self,()=>(()=>{"use strict";var e={d:(t,r)=>{for(var i in r)e.o(r,i)&&!e.o(t,i)&&Object.defineProperty(t,i,{enumerable:!0,get:r[i]})},o:(e,t)=>Object.prototype.hasOwnProperty.call(e,t),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},t={};e.r(t),e.d(t,{Kashi:()=>w});const r=/\[\d{2}:\d{2}.\d{2}\]/,i=/^\[\d{2}:\d{2}.\d{2}\](.*)$/;var n,o,s,a,l,f,c,h,d,u=function(e,t,r,i,n){if("m"===i)throw new TypeError("Private method is not writable");if("a"===i&&!n)throw new TypeError("Private accessor was defined without a setter");if("function"==typeof t?e!==t||!n:!t.has(e))throw new TypeError("Cannot write private member to an object whose class did not declare it");return"a"===i?n.call(e,r):n?n.value=r:t.set(e,r),r},p=function(e,t,r,i){if("a"===r&&!i)throw new TypeError("Private accessor was defined without a getter");if("function"==typeof t?e!==t||!i:!t.has(e))throw new TypeError("Cannot read private member from an object whose class did not declare it");return"m"===r?i:"a"===r?i.call(e):i?i.value:t.get(e)};class w{constructor(e){if(n.add(this),o.set(this,null),s.set(this,null),a.set(this,[]),l.set(this,void 0),f.set(this,new Map),e.url&&e.file)throw new Error("Cannot specify both url and file");if(!e.url&&!e.file)throw new Error("Must specify either url or file");e.url?this.setUrl(e.url):e.file&&this.setFile(e.file),u(this,l,e.container,"f")}get url(){return p(this,o,"f")}get file(){return p(this,s,"f")}async setUrl(e){try{const t=await fetch(e);if(!t.ok)throw new Error(`HTTP error! status: ${t.status}`);const r=t.headers.get("Content-Type");if(!r||!r.includes("text/plain"))throw new Error("Invalid content type. Expected text/plain.");const i=await t.blob();u(this,o,e,"f"),this.notify("urlSet",{url:e}),this.setFile(i)}catch(e){throw new Error("Failed to fetch the lyric file.")}}async setFile(e){const t=await p(this,n,"m",c).call(this,e);u(this,a,p(this,n,"m",h).call(this,t),"f"),u(this,s,e,"f"),this.notify("fileSet",{file:e}),p(this,n,"m",d).call(this)}subscribe(e,t){p(this,f,"f").set(e,[...p(this,f,"f").get(e)??[],t])}unsubscribe(e,t){const r=p(this,f,"f").get(e);r&&r.length>1?p(this,f,"f").set(e,[...r.filter(e=>e!==t)]):p(this,f,"f").delete(e)}notify(e,t){[...p(this,f,"f").get(e)??[]].forEach(e=>{e(t)})}}return o=new WeakMap,s=new WeakMap,a=new WeakMap,l=new WeakMap,f=new WeakMap,n=new WeakSet,c=async function(e){return new Promise((t,r)=>{const i=new FileReader;i.onload=e=>{"string"==typeof e.target?.result?t(e.target.result):r(new Error("Failed to read file content."))},i.onerror=()=>r(new Error("Error reading file.")),i.readAsText(e)})},h=function(e){return e.split("\n").reduce((e,t)=>{const r=t.trim();return i.test(r)?[...e,r]:e},[])},d=function(){p(this,l,"f").innerHTML=p(this,a,"f").map(e=>`<p>${e.replace(r,"")||"🎝"}</p>`).join(""),this.notify("lyricLinesUpdated",{lyricLines:p(this,a,"f")})},t})());
+!function(e,t){if("object"==typeof exports&&"object"==typeof module)module.exports=t();else if("function"==typeof define&&define.amd)define([],t);else{var r=t();for(var i in r)("object"==typeof exports?exports:e)[i]=r[i]}}(self,()=>(()=>{"use strict";var e={d:(t,r)=>{for(var i in r)e.o(r,i)&&!e.o(t,i)&&Object.defineProperty(t,i,{enumerable:!0,get:r[i]})},o:(e,t)=>Object.prototype.hasOwnProperty.call(e,t),r:e=>{"undefined"!=typeof Symbol&&Symbol.toStringTag&&Object.defineProperty(e,Symbol.toStringTag,{value:"Module"}),Object.defineProperty(e,"__esModule",{value:!0})}},t={};e.r(t),e.d(t,{Kashi:()=>w});const r=/\[\d{2}:\d{2}.\d{2}\]/,i=/^\[\d{2}:\d{2}.\d{2}\](.*)$/;var n,s,o,a,f,l,h,c,d,u,p=function(e,t,r,i,n){if("m"===i)throw new TypeError("Private method is not writable");if("a"===i&&!n)throw new TypeError("Private accessor was defined without a setter");if("function"==typeof t?e!==t||!n:!t.has(e))throw new TypeError("Cannot write private member to an object whose class did not declare it");return"a"===i?n.call(e,r):n?n.value=r:t.set(e,r),r},y=function(e,t,r,i){if("a"===r&&!i)throw new TypeError("Private accessor was defined without a getter");if("function"==typeof t?e!==t||!i:!t.has(e))throw new TypeError("Cannot read private member from an object whose class did not declare it");return"m"===r?i:"a"===r?i.call(e):i?i.value:t.get(e)};class w{constructor(e){if(n.add(this),s.set(this,null),o.set(this,null),a.set(this,[]),f.set(this,void 0),l.set(this,new Map),h.set(this,void 0),e.url&&e.file)throw new Error("Cannot specify both url and file");if(!e.url&&!e.file)throw new Error("Must specify either url or file");e.emptyLineText&&this.setEmptyLineText(e.emptyLineText),p(this,f,e.container,"f"),this.subscribe("fileSet",y(this,n,"m",u).bind(this)),this.subscribe("emptyLineTextSet",y(this,n,"m",u).bind(this)),e.url?this.setUrl(e.url):e.file&&this.setFile(e.file)}get url(){return y(this,s,"f")}get file(){return y(this,o,"f")}get emptyLineText(){return y(this,h,"f")}async setUrl(e){try{const t=await fetch(e);if(!t.ok)throw new Error(`HTTP error! status: ${t.status}`);const r=t.headers.get("Content-Type");if(!r||!r.includes("text/plain"))throw new Error("Invalid content type. Expected text/plain.");const i=await t.blob();p(this,s,e,"f"),this.notify("urlSet",{url:e}),this.setFile(i)}catch(e){throw new Error("Failed to fetch the lyric file.")}}async setFile(e){const t=await y(this,n,"m",c).call(this,e);p(this,a,y(this,n,"m",d).call(this,t),"f"),p(this,o,e,"f"),this.notify("fileSet",{file:e})}setEmptyLineText(e){p(this,h,e,"f"),this.notify("emptyLineTextSet",{emptyLineText:e})}subscribe(e,t){y(this,l,"f").set(e,[...y(this,l,"f").get(e)??[],t])}unsubscribe(e,t){const r=y(this,l,"f").get(e);r&&r.length>1?y(this,l,"f").set(e,[...r.filter(e=>e!==t)]):y(this,l,"f").delete(e)}notify(e,t){[...y(this,l,"f").get(e)??[]].forEach(e=>{e(t)})}}return s=new WeakMap,o=new WeakMap,a=new WeakMap,f=new WeakMap,l=new WeakMap,h=new WeakMap,n=new WeakSet,c=async function(e){return new Promise((t,r)=>{const i=new FileReader;i.onload=e=>{"string"==typeof e.target?.result?t(e.target.result):r(new Error("Failed to read file content."))},i.onerror=()=>r(new Error("Error reading file.")),i.readAsText(e)})},d=function(e){return e.split("\n").reduce((e,t)=>{const r=t.trim();return i.test(r)?[...e,r]:e},[])},u=function(){y(this,f,"f").innerHTML=y(this,a,"f").map(e=>`<p>${e.replace(r,"")||(y(this,h,"f")??"🎝")}</p>`).join(""),this.notify("lyricLinesUpdated",{lyricLines:y(this,a,"f")})},t})());

package/kashi.mjs

@@ -1 +1 @@
-const t=/\[\d{2}:\d{2}.\d{2}\]/,e=/^\[\d{2}:\d{2}.\d{2}\](.*)$/;var r,i,n,s,o,a,l,f,h,c=function(t,e,r,i,n){if("m"===i)throw new TypeError("Private method is not writable");if("a"===i&&!n)throw new TypeError("Private accessor was defined without a setter");if("function"==typeof e?t!==e||!n:!e.has(t))throw new TypeError("Cannot write private member to an object whose class did not declare it");return"a"===i?n.call(t,r):n?n.value=r:e.set(t,r),r},w=function(t,e,r,i){if("a"===r&&!i)throw new TypeError("Private accessor was defined without a getter");if("function"==typeof e?t!==e||!i:!e.has(t))throw new TypeError("Cannot read private member from an object whose class did not declare it");return"m"===r?i:"a"===r?i.call(t):i?i.value:e.get(t)};class u{constructor(t){if(r.add(this),i.set(this,null),n.set(this,null),s.set(this,[]),o.set(this,void 0),a.set(this,new Map),t.url&&t.file)throw new Error("Cannot specify both url and file");if(!t.url&&!t.file)throw new Error("Must specify either url or file");t.url?this.setUrl(t.url):t.file&&this.setFile(t.file),c(this,o,t.container,"f")}get url(){return w(this,i,"f")}get file(){return w(this,n,"f")}async setUrl(t){try{const e=await fetch(t);if(!e.ok)throw new Error(`HTTP error! status: ${e.status}`);const r=e.headers.get("Content-Type");if(!r||!r.includes("text/plain"))throw new Error("Invalid content type. Expected text/plain.");const n=await e.blob();c(this,i,t,"f"),this.notify("urlSet",{url:t}),this.setFile(n)}catch(t){throw new Error("Failed to fetch the lyric file.")}}async setFile(t){const e=await w(this,r,"m",l).call(this,t);c(this,s,w(this,r,"m",f).call(this,e),"f"),c(this,n,t,"f"),this.notify("fileSet",{file:t}),w(this,r,"m",h).call(this)}subscribe(t,e){w(this,a,"f").set(t,[...w(this,a,"f").get(t)??[],e])}unsubscribe(t,e){const r=w(this,a,"f").get(t);r&&r.length>1?w(this,a,"f").set(t,[...r.filter(t=>t!==e)]):w(this,a,"f").delete(t)}notify(t,e){[...w(this,a,"f").get(t)??[]].forEach(t=>{t(e)})}}i=new WeakMap,n=new WeakMap,s=new WeakMap,o=new WeakMap,a=new WeakMap,r=new WeakSet,l=async function(t){return new Promise((e,r)=>{const i=new FileReader;i.onload=t=>{"string"==typeof t.target?.result?e(t.target.result):r(new Error("Failed to read file content."))},i.onerror=()=>r(new Error("Error reading file.")),i.readAsText(t)})},f=function(t){return t.split("\n").reduce((t,r)=>{const i=r.trim();return e.test(i)?[...t,i]:t},[])},h=function(){w(this,o,"f").innerHTML=w(this,s,"f").map(e=>`<p>${e.replace(t,"")||"🎝"}</p>`).join(""),this.notify("lyricLinesUpdated",{lyricLines:w(this,s,"f")})};export{u as Kashi};
+const t=/\[\d{2}:\d{2}.\d{2}\]/,e=/^\[\d{2}:\d{2}.\d{2}\](.*)$/;var i,r,s,n,o,a,h,l,f,c,u=function(t,e,i,r,s){if("m"===r)throw new TypeError("Private method is not writable");if("a"===r&&!s)throw new TypeError("Private accessor was defined without a setter");if("function"==typeof e?t!==e||!s:!e.has(t))throw new TypeError("Cannot write private member to an object whose class did not declare it");return"a"===r?s.call(t,i):s?s.value=i:e.set(t,i),i},w=function(t,e,i,r){if("a"===i&&!r)throw new TypeError("Private accessor was defined without a getter");if("function"==typeof e?t!==e||!r:!e.has(t))throw new TypeError("Cannot read private member from an object whose class did not declare it");return"m"===i?r:"a"===i?r.call(t):r?r.value:e.get(t)};class d{constructor(t){if(i.add(this),r.set(this,null),s.set(this,null),n.set(this,[]),o.set(this,void 0),a.set(this,new Map),h.set(this,void 0),t.url&&t.file)throw new Error("Cannot specify both url and file");if(!t.url&&!t.file)throw new Error("Must specify either url or file");t.emptyLineText&&this.setEmptyLineText(t.emptyLineText),u(this,o,t.container,"f"),this.subscribe("fileSet",w(this,i,"m",c).bind(this)),this.subscribe("emptyLineTextSet",w(this,i,"m",c).bind(this)),t.url?this.setUrl(t.url):t.file&&this.setFile(t.file)}get url(){return w(this,r,"f")}get file(){return w(this,s,"f")}get emptyLineText(){return w(this,h,"f")}async setUrl(t){try{const e=await fetch(t);if(!e.ok)throw new Error(`HTTP error! status: ${e.status}`);const i=e.headers.get("Content-Type");if(!i||!i.includes("text/plain"))throw new Error("Invalid content type. Expected text/plain.");const s=await e.blob();u(this,r,t,"f"),this.notify("urlSet",{url:t}),this.setFile(s)}catch(t){throw new Error("Failed to fetch the lyric file.")}}async setFile(t){const e=await w(this,i,"m",l).call(this,t);u(this,n,w(this,i,"m",f).call(this,e),"f"),u(this,s,t,"f"),this.notify("fileSet",{file:t})}setEmptyLineText(t){u(this,h,t,"f"),this.notify("emptyLineTextSet",{emptyLineText:t})}subscribe(t,e){w(this,a,"f").set(t,[...w(this,a,"f").get(t)??[],e])}unsubscribe(t,e){const i=w(this,a,"f").get(t);i&&i.length>1?w(this,a,"f").set(t,[...i.filter(t=>t!==e)]):w(this,a,"f").delete(t)}notify(t,e){[...w(this,a,"f").get(t)??[]].forEach(t=>{t(e)})}}r=new WeakMap,s=new WeakMap,n=new WeakMap,o=new WeakMap,a=new WeakMap,h=new WeakMap,i=new WeakSet,l=async function(t){return new Promise((e,i)=>{const r=new FileReader;r.onload=t=>{"string"==typeof t.target?.result?e(t.target.result):i(new Error("Failed to read file content."))},r.onerror=()=>i(new Error("Error reading file.")),r.readAsText(t)})},f=function(t){return t.split("\n").reduce((t,i)=>{const r=i.trim();return e.test(r)?[...t,r]:t},[])},c=function(){w(this,o,"f").innerHTML=w(this,n,"f").map(e=>`<p>${e.replace(t,"")||(w(this,h,"f")??"🎝")}</p>`).join(""),this.notify("lyricLinesUpdated",{lyricLines:w(this,n,"f")})};export{d as Kashi};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kashi",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Singing at the top of my lungs",
   "type": "module",
   "author": "lucasmc64",
@@ -21,8 +21,9 @@
     "song"
   ],
   "scripts": {
+    "prestart": "npm run build",
     "start": "gulp watchAll",
-    "build": "rm -rf dist && gulp compileAll && cat ./package.json | grep -v '\"private\":' > dist/package.json && \\cp LICENSE dist && \\cp README.md dist",
+    "build": "rm -rf dist && gulp compileAll && ./node_modules/.bin/dts-bundle-generator -o ./dist/kashi.d.ts ./src/index.ts && cat ./package.json | grep -v '\"private\":' > dist/package.json && \\cp LICENSE dist && \\cp README.md dist",
     "test": "NODE_OPTIONS=--experimental-vm-modules jest",
     "test:watch": "npm test -- --watch",
     "test:coverage": "npm test -- --coverage"