Release v2.1.0 (#46)

* Added ability to sort playlists by different criteria (index, duration, views, channel name, upload date)
* Fixed several bugs
    * Bug with mutation observer not disconnecting when navigating between playlists
    * Bug where timestamps were not being summed properly
* Migrated to pnpm from npm
* Addressed vulnerabilities reported by pnpm audit and dependabot
* Added i18n support
    * Added translations for english, spanish (es, es-419, es-us), portuguese (pt-PT, pt-BR), chinese (zh-Hans-CN, zh-Hant-TW)
* Refactored several parts of codebase to reduce complexity
* Added & updated documentation (README, testing, adding translations)

---------

Signed-off-by: dependabot[bot] <[email protected]>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.eslintrc.cjs

@@ -12,5 +12,8 @@ module.exports = {
   },
   rules: {
     "no-unused-vars": "warn"
+  },
+  globals: {
+    chrome: true
   }
 };

.gitignore

@@ -1,6 +1,3 @@
-# Local
-docs/
-
 # Logs
 logs
 *.log

.husky/pre-commit

@@ -1,4 +1,4 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-npx lint-staged
+pnpm exec lint-staged

.node-version

@@ -0,0 +1 @@
+20.11.1

.npmrc

@@ -0,0 +1,2 @@
+node-version=20.11.1
+engine-strict=true

.nvmrc

@@ -0,0 +1 @@
+20.11.1

README.md

@@ -1,68 +1,170 @@
-# Youtube Playlist Duration Calculator
+# YouTube Playlist Duration Calculator
 
-A Firefox & Chrome web extension that calculates & displays the total duration of a youtube playlist.
+A web extension for Chrome & Firefox that calculates & displays the total
+duration of a YouTube playlist.
 
 <img src="screenshots/banner.png">
 
 ## Previews
 
 <p align="center">
-  <img src="screenshots/default.png" width="800">
+  <img src="screenshots/default.jpeg" width="800">
 </p>
 
 <p align="center">
   <img src="screenshots/example1.png" width="400">
-  <img src="screenshots/example1_2.png" width="400">
+  <img src="screenshots/example2.png" width="400">
 </p>
 
-## Installation
+## Get the extension
+
+The extension is available for download at:
 
 - Chrome: [Web Store](https://chrome.google.com/webstore/detail/youtube-playlist-duration/pijbakhgmhhadeakaocjfockpndcpobk)
 - Firefox: [Firefox Add-ons](https://addons.mozilla.org/firefox/addon/youtube-playlist-duration-calc/)
 
-Alternatively, you can install the extension manually using the following instructions:-
+## Features
+
+- Calculate & display the total duration of a YouTube playlist
+- Sort playlists with 100 videos or less, by the following criteria:
+  - Duration
+  - Channel Name
+  - Index
+  - Views (only for some locales)
+  - Upload Date (only for public playlists & some locales)
+- Translations for several locales (en, es, pt, zh)
+
+> **Note:** The sorting feature is only enabled for playlists containing 100
+> videos or less. This is because for larger playlists (>100 videos), YouTube
+> only loads the next 100 videos after you scroll to the bottom of the page.
+> This can often produce inconsistent & inaccurate sorting results, so it has
+> been disabled for now.
+
+## Getting Started
+
+This section will explain how to get the project setup locally for development.
+
+### Dependencies
+
+To work with this project, you will need the following dependencies:
+
+- Node.js v20+
+  - https://nodejs.org/en/download
+  - https://github.com/Schniz/fnm
+  - https://github.com/nvm-sh/nvm
+- pnpm
+  - https://pnpm.io/
+
+### Get the Source
+
+This project is hosted at:
+https://github.com/nrednav/youtube-playlist-duration-calculator
+
+You can clone the project locally via:
+
+HTTPS:
+
+```
+git clone https://github.com/nrednav/youtube-playlist-duration-calculator.git
+```
+
+SSH:
+
+```
+git clone [email protected]:nrednav/youtube-playlist-duration-calculator.git
+```
+
+### Installation
+
+To install the project's dependencies:
+
+```
+cd youtube-playlist-duration-calculator/
+pnpm install
+```
+
+### Building
+
+Build the extension for a specific browser using:
+
+```
+pnpm run build:chrome
+pnpm run build:firefox
+```
+
+This will output the extension files into a sub-directory named `dist` within
+the `youtube-playlist-duration-calculator` directory.
+
+### Run
+
+#### Automatic
+
+Run the project in development mode with:
+
+```
+pnpm run dev
+```
+
+This will do the following:
+
+- Determine the browser via the environment variable `VITE_TARGET_BROWSER`
+  - It will default to Chrome if the variable is undefined
+- Build the extension for the selected browser
+- Open the selected browser
+- Automatically & temporarily load the extension in the opened browser
+- Open a test YouTube
+  [playlist](https://www.youtube.com/playlist?list=PLAhTBeRe8IhMmRve_rSfAgL_dtEXkKh8Z)
+  overview page
 
-For Chrome:
+#### Manual
 
-1. Download this project as a zip file.
-2. Navigate to `chrome://extensions` in Google Chrome or a chromium-based fork such as Brave Browser.
-3. Check the box for **Developer Mode**
-4. Look for a button that says **Load unpacked extension** and click it
-5. Select the project zip file you downloaded in Step 1.
-6. You should now see the extension installed amongst your other extensions.
-7. To verify that it works, navigate to a youtube playlist overview page, for example: https://www.youtube.com/playlist?list=PLAhTBeRe8IhMmRve_rSfAgL_dtEXkKh8Z
-8. You should see the playlist's total duration appear under the playlist title.
+To install & run the extension manually, follow these steps:
 
-For Firefox:
+Firefox:
 
-1. Download this project as a zip file.
-2. Extract out the ytpdc-firefox folder
-3. Install Mozilla's web-ext tool: [Link to workshop](https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext/)
-4. Navigate to the ytpdc-firefox directory in a command-line tool of your choice, and run `web-ext run` to test the add-on in a temporary browser
-5. Follow the instructions available in Mozilla's web-ext workshop at the link provided above to sign the extension yourself with `web-ext sign`
-6. Once you have signed it, you should find a .xpi file located within a folder named 'web-ext-artifacts' inside the ytpdc-firefox folder
-7. Navigate to `about:addons` via the address bar in Firefox, click the cog-wheel on the top right, choose `Install Add-on from file` and select the `.xpi` file from the previous step
+- Build the extension with `pnpm run build:firefox`
+- Install the `web-ext` tool from Mozilla
+  - Link: https://extensionworkshop.com/documentation/develop/getting-started-with-web-ext/
+- Test the extension by running `web-ext run` from within `dist/` directory
+  - Visit any YouTube playlist overview page and verify the extension
+    calculates & displays the playlist duration
+- Sign the extension with `web-ext sign`
+  - Follow the instructions on the same page linked above
+  - You will need to run this command within the `dist` directory too
+  - At the end, you should have a `.xpi` file generated within a sub-directory
+    named `web-ext-artifacts`
+- In your Firefox browser
+  - Navigate to `about:addons` via the address bar
+  - Click the cogwheel button located at the top-right of the page
+  - From the dropdown, select `Install Add-on From File`
+  - Locate & select the `.xpi` file generated in a previous step
+  - The extension should now be installed
 
-## Development
+Chrome:
 
-- Clone this repository
-- Install dependencies
+- Build the extension with `pnpm run build:chrome`
+- In your Chrome browser
+  - Navigate to `chrome://extensions` via the address bar
+  - Select the checkbox next to `Developer Mode`
+  - Click the button named `Load Unpacked Extension`
+  - Locate & select the `dist` sub-directory within the
+    `youtube-playlist-duration-calculator` directory
+  - The extension should now be installed
 
-  ```
-  npm install
-  ```
+To verify the extension works, visit any YouTube playlist overview page & verify
+that you see the duration calculated & displayed within the playlist information
+panel located on the left-hand side of the page.
 
-- Build the extension
+## Issues & Requests
 
-  ```
-  npm run build:chrome
-  npm run build:firefox
-  ```
+If you wish to request a new feature or report a bug, please open an issue by
+clicking
+[here](https://github.com/nrednav/youtube-playlist-duration-calculator/issues/new).
 
-  This will output the extension into the `dist` folder
+## Translations
 
-- Run the extension in development mode
+For a list of locales currently supported by the extension, please see
+[public/\_locales](./public/_locales/)
 
-  ```
-  npm run dev
-  ```
+Additional translations are most welcome! Please see
+[docs/translations.md](./docs/translations.md) for more details.

docs/testing.md

@@ -0,0 +1,62 @@
+# Testing
+
+This document describes the process involved in testing the extension.
+
+## Types of Playlists
+
+- Public
+  - Less than 100 videos
+    - https://www.youtube.com/playlist?list=PLrtg3MOb7tvG9h9rll5V9O96owfcBpROG
+    - https://www.youtube.com/playlist?list=PLBsP89CPrMePWBCMIp0naluIz67UwRX9B
+  - More than 100 videos
+    - https://www.youtube.com/playlist?list=PLBsP89CPrMeM2MmF4suOeT0vsic9nEC2Y
+- Private
+  - Regular
+  - Watch Later
+    - https://www.youtube.com/playlist?list=WL
+  - Liked Videos
+    - https://www.youtube.com/playlist?list=LL
+- Has unavailable videos
+  - https://www.youtube.com/playlist?list=PL3HWFB6aFvWBXGsbVJhJJK1ykcqlVz5lI
+
+## Pre-requisites
+
+- Ensure that both Chrome & Firefox are installed
+- Ensure the extension has been installed & enabled in both browsers
+
+## Process
+
+- For each type of playlist
+  - [ ] Visit playlist page
+  - [ ] Verify the following
+    - [ ] A summary section is displayed within the playlist information panel
+          located on the left-hand side of the page
+    - [ ] The summary section displays the following:
+      - [ ] Total duration (hh:mm:ss)
+      - [ ] Videos counted
+      - [ ] Videos not counted
+      - [ ] For playlists with 100 videos or less
+        - [ ] Sort dropdown
+      - [ ] For playlists with more than 100 videos
+        - [ ] Tooltip
+    - [ ] For playlists with 100 videos or less
+      - [ ] Clicking on the sort dropdown displays the following sort criteria
+        - [ ] Index (Ascending/Descending)
+        - [ ] Duration (Shortest/Longest)
+        - [ ] Channel Name (A-Z/Z-A)
+        - [ ] Views (Most/Least)
+        - [ ] (For public playlists only) Upload Date (Earliest/Latest)
+      - [ ] Clicking on a sort criterion updates the order of videos in the playlist
+    - [ ] For playlists with more than 100 videos
+      - [ ] Scrolling to the bottom updates the summary section to display the text
+            "Calculating..."
+      - [ ] After the next batch of videos have been loaded, the summary section
+            updates to display new information
+    - [ ] For private playlists
+      - [ ] Removing a video triggers a recalculation of the playlist duration
+    - [ ] For playlists that have unavailable videos
+      - [ ] The duration is still calculated
+      - [ ] The number of videos not counted is displayed in the playlist
+            summary section
+      - [ ] Selecting the "Show unavailable videos" settings triggers a
+            recalulation of the playlist duration

docs/translations.md

@@ -0,0 +1,32 @@
+# Translations
+
+This document describes the process involved in submitting additional
+translations for the extension.
+
+## Pre-requisites
+
+- An understanding of JSON
+
+## Process
+
+### Adding new translations
+
+- Download the project repository as a ZIP file
+- Extract it to a folder
+- Within the extracted folder, navigate into the `public/_locales` folder
+- Make a copy of the `en` folder
+- Rename the copy to `<locale-code>`
+  - `<locale-code>` should be replaced with the locale code for the translations
+    you are adding
+  - For a full list of supported locale codes, please see: https://developer.chrome.com/docs/extensions/reference/api/i18n#locales
+- Edit the `messages.json` file within `<localeCode>` to add your translations
+  - You only have to update the values of the `message` properties throughout
+    the file
+- Once you have finished adding translations
+  - Create a new issue by visiting this [link](https://github.com/nrednav/youtube-playlist-duration-calculator/issues/new)
+  - Attach the `messages.json` file containing your translations to the issue
+
+### Updating existing translations
+
+- Same as above except instead of copying the `en` folder, you can directly edit
+  the `messages.json` file in the existing locale folder

jsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "src/*": ["./src/*"]
+    }
+  }
+}