Merge pull request #790 from cjyuan/todo-new

Update todo-list to demonstrate testing with ESM

Author: cjyuan

Sprint-3/todo-list/00-what_is_ES_modules.md

@@ -0,0 +1,16 @@
+# What is JavaScript Modules?
+JavaScript modules let us organize code into separate files, making the code easier to manage and reuse. We can export parts of one file (like functions or variables) and import them into another to keep our code clean and modular.
+
+## Different Module Systems
+
+JavaScript has two main ways to handle modules:
+
+- **CommonJS** is the older format used mostly in Node.js. It uses `require` and `module.exports`.
+
+- **ES Modules** (ESM) are the modern, standard way for browsers and Node.js. They use `import` and `export`.
+
+They are **not** fully compatible. At CYF, you should use ESM, not CommonJS.
+
+## Where can I learn ESM?
+- [Modules, introduction](https://javascript.info/modules-intro)
+- [JavaScript modules -- JavaScript | MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)

Sprint-3/todo-list/01-using_esm_with_nodejs_and_jest.md

@@ -0,0 +1,50 @@
+# Using ESM with Node.js, Jest, and `jsdom`
+
+## Node.js 
+
+Node.js supports both CommonJS and ESM, with CommonJS being the default module system.
+
+To use ESM, we can add `"type": "module"` to `package.json`, or we can name the JavaScript files
+with `.mjs` file extension.
+
+**Important**:
+- Avoid mixing CommonJS and ESM in the same project. At CYF you should only use ESM.
+
+
+## Jest
+
+[Jest’s support for ESM](https://jestjs.io/docs/ecmascript-modules) is still experimental, and may require additional configuration to work correctly.
+
+One way to execute Jest test script that uses ESM is to 
+
+1. **Update the custom `test` script in `package.json`**:
+```javascript
+"scripts": {
+  "test": "NODE_OPTIONS=--experimental-vm-modules jest"
+}
+```
+
+**Note**: On Windows, use **`set`** instead
+```javascript
+"scripts": {
+  "test": "set NODE_OPTIONS=--experimental-vm-modules && jest"
+}
+```
+
+
+2. **Run a specific Jest test script using**: 
+
+```
+npm test -- <test_script_filename>
+```
+
+**Note**: The `--` is optional if you do not have arguments to be forwarded to the underlying 
+`jest` command.
+
+
+## `jsdom`
+
+[**`jsdom`**](https://github.com/jsdom/jsdom), a pure-JavaScript implementation of DOM for 
+use with Node.js, **does not yet support** `<script type="module">` tags in HTML.
+
+Testing an ESM-based application with `jsdom` requires additional configuration and third-party tooling.

Sprint-3/todo-list/02-guide_to_modularize_code.md

@@ -0,0 +1,55 @@
+# Why modularize code?
+
+Modularizing code means breaking a program into smaller, self-contained pieces (modules),
+each responsible for a specific functionality. This approach offers several key advantages:
+
+- Reusability – You can use the same code in different parts of a project or in other projects.
+- Maintainability – It's easier to fix bugs or update features when code is organized into smaller parts.
+- Separation of Concerns – Each part of the code handles a specific task, keeping things clear and organized.
+- Team Collaboration – Multiple people can work on different modules at the same time without conflict.
+- Scalability – You can add new features more easily as the project grows.
+- Testing – Smaller modules are easier to test individually.
+- Readability – Modular code is easier to read, understand, and navigate.
+
+## How to break a program into smaller modules?
+
+This is a relatively big topic and you will learn more about how to modularize a web app in the 
+SDC course.
+
+For starters, we recommend focusing on breaking a web app into the **non-UI part** and 
+the **UI part**. Some of the advantages of doing so include:
+
+1. Easier Testing
+    - Non-UI code can be tested independently with unit tests.
+    - You don't need browser environments or DOM simulations (e.g., `jsdom`) for testing logic.
+
+2. Easier Collaboration
+    - UI developers and business-logic developers can work more independently.
+    - Clearer separation of concerns makes the codebase easier to maintain over time.
+
+### The Non-UI Part of a Web App
+
+This is the part of the app that works behind the scenes, without any user interface (UI).
+
+It focuses on:
+- ✅ How to represent data in the app
+- ✅ What operations are needed to support data access and manipulation
+
+### The UI Part of a Web App
+
+This is the part of the app that interacts with the user interface (UI).
+
+It focuses on:
+- ✅ How to collect user input
+- ✅ How to present data on the screen
+- ✅ Calling functions in the non-UI part to process the data
+
+### Dependencies
+
+The UI parts can depend on the non-UI parts (e.g. call functions from the non-UI parts). But the non-UI parts should not depend on the UI parts.
+
+### Example: The ToDo App
+- The non-UI part is implemented in `todos.mjs`
+- The UI part is implemented in `script.mjs`
+  
+Note: For a larger codebase, each part could be divided into multiple modules or files.

Sprint-3/todo-list/README.md

@@ -1,66 +1,94 @@
-# Todo-list
+# ToDo List App
 
-## Explanation
+The files in this folder implements a ToDo List App that allows a user to
+- Create a new ToDo task
+- Delete a ToDo task
+- Display all ToDo tasks
+- Changing the "completed" status of a ToDo task
 
-This is a super handy, super simple to do list.
+Each ToDo task has two properties:
+  - `task`: A string describing the task 
+  - `completed`: a Boolean value that indicates whether the task is completed or not 
 
-You will be given a list of tasks which are "To Do". We call these tasks "ToDos"
+## Installation
 
-Each item in the list should have 2 buttons:
+Run the following command in this directory to install all required dependencies: 
+```
+  npm install
+```
+> This will install
+- `jest` - for running unix test
+- `http-server` - for serving `index.html` over HTTP
+ 
+**Note:** If you are using a Windows CLI, replace `package.json` by `package.json-windows`.
 
-- One to click when the ToDo has been completed - it will apply a line-through style to the text of the ToDo.
-- A second to delete the ToDo. This could be used to delete completed ToDos from the list, or remove ToDos that we are no longer interested in doing.
+## Running the App 
 
-We also want to be able to add ToDos to the list using an input field and a button. When ToDos are created this way they should be added to the list with the 2 above buttons.
+Since the app uses **ES modules**, the HTML file **must be loaded via HTTP/HTTPS** rather than
+directly from the file system.
 
-More details for the implementation of this challenge can be found in `script.js`
+Make sure you run the server in this directory where `index.html` is located.
 
-## Installation
+Two possible ways to serve `index.html` over HTTP:
 
-To view the website, open index.html in a browser.
+#### Option 1: `http-server`
 
-## Example Solution
+1. Run 
+   ```
+   npm run serve
+   ```
+   > Here, `serve` is a shortcut defined in `package.json` for running `http-server`.
+  
+  
+2. Open one of the URLs shown in the terminal (e.g., `http://127.0.0.1:8080`).
 
-A basic example of this can website can be found here
 
-https://chrisowen101.github.io/ToDoListSolution/
+#### Option 2: Open `index.html` with Live Server in VSCode.
 
-This covers only the basic tasks, not the advanced tasks.
 
-## Instructions
+## Understanding how the code is organized as ES modules
 
-The `populateTodoList()` function should iterate over the list of todos that we are given at the start, it should create a `<li>` for the todo along with some other stuff that you can find in index.html and below.
+- [What is ES Modules?](00-what_is_ES_modules.md)
+- [How to use ES modules with Node.js and Jest?](01-using_esm_with_nodejs_and_jest.md)
+- [A guide to modularize a web app](02-guide_to_modularize_code.md)
 
-The items in the todo list are currently hard-coded into the HTML, refactor the code so that this function creates them and adds the following functionality to them:
+---
 
-Each todo should have this HTML inside it:
+## Exercise Instructions
 
-```html
-<span class="badge bg-primary rounded-pill">
-  <i class="fa fa-check" aria-hidden="true"></i>
-  <i class="fa fa-trash" aria-hidden="true"></i>
-</span>
-```
+In this exercise, your objective is to extend the ToDo app by implementing new features. 
+Start with the main feature and then try the stretch goals if you have extra time.
+
+### Main Feature: Mass delete of completed ToDos
+
+Add a button that deletes all completed tasks at once.
+
+Steps:
+1. In `index.html`, add a "Delete completed tasks" button.
 
-The first `<i>` tag needs an event listener that applies a line-through text-decoration styling to the text of the todo. It should remove the styling if it is clicked again.
+2. In `todos.mjs`, implement a function `deleteCompleted(todoList)` that removes all completed 
+   ToDos from the given list.
 
-The second `<i>` tag needs an event listener that deletes the parent `<li>` element from the `<ul>`.
+3. In `todos.test.mjs`, write a Jest test that verifies `deleteCompleted()` works correctly.
 
-## Advanced Challenge
+4. In `script.js`, call `deleteCompleted()` whenever the new button is clicked.
+    - ⚠️ You should not need to modify the `render()` function.
 
-### Mass delete of completed ToDos
+### Stretch 1: Add deadlines for ToDos
 
-Develop the ToDo list further and allow users to delete all completed ToDos.
+Allow users to set and view deadlines for their tasks.
+    - When creating a ToDo, let the user select a deadline using an HTML **datepicker** input.
+    - If no date is selected, the ToDo has **no deadline**.
+    - When rendering a ToDo in the list, display the deadline only if it exists.
 
-Add a button that users can click that will iterate through the list of ToDos and then delete them only if they have been completed.
+### Stretch 2: Extra Challenge – Show time remaining
 
-## Extra Advanced Challenge
+Instead of showing the deadline as a date, display how many days are left until the 
+deadline (relative to today).
+    - Decide how overdue ToDos should be handled and then implement your chosen solution.
 
-### Set deadlines for ToDos
+👉 Hint: You can use the [JavaScript Date API](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date)
+to calculate the difference.
 
-We want users to be able to set, and see, deadlines for their ToDos.
 
-When creating ToDos we want the user to be able to use a datepicker input so they can see when they need to complete the ToDo. The date can be added to the ToDo in the list. If there is no date set when the ToDo is created then this can be skipped.
 
-EXTRA CHALLENGE: instead of displaying the date on the ToDo, implement a countdown of days left until the deadline. You can use the Javascript Date reference to accomplish this:
-https://www.w3schools.com/jsref/jsref_obj_date.asp

Sprint-3/todo-list/assets/world.jpg

@@ -1,27 +1,40 @@
 <!DOCTYPE html>
 <html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Title here</title>
-    <link rel="stylesheet" href="style.css" />
-  </head>
-  <body>
-    <form>
-      <div>
-        <input type="text" placeholder="New todo..." />
-      </div>
-      <div>
-        <button type="submit">Add Todo</button>
-        <button
-          type="button"
-          id="remove-all-completed"
-          class="btn btn-primary mb-3"
-        >
-          Remove all completed
-        </button>
-      </div>
-    </form>
-    <script src="script.js"></script>
-  </body>
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
+  <title>ToDo List</title>
+  <link rel="stylesheet" href="style.css" />
+  <link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css" rel="stylesheet">
+
+  <script type="module" src="script.mjs"></script>
+</head>
+<body>
+  <div class="todo-container">
+    <h1>My ToDo List</h1>
+
+    <div class="todo-input">
+      <input type="text" id="new-task-input" placeholder="Enter a new task..." />
+      <button id="add-task-btn">Add</button>
+    </div>
+
+    <ul id="todo-list" class="todo-list">      
+    </ul>
+
+    <!-- 
+      This is a template for the To-do list item. 
+      It can simplify the creation of list item node in JS script.
+    -->
+    <template id="todo-item-template">
+      <li class="todo-item"> <!-- include class "completed" if the task completed state is true -->
+        <span class="description">Task description</span>
+        <div class="actions">
+          <button class="complete-btn"><span class="fa-solid fa-check" aria-hidden="true"></span></button>
+          <button class="delete-btn"><span class="fa-solid fa-trash" aria-hidden="true"></span></button>
+        </div>
+      </li>
+    </template>
+
+  </div>
+</body>
 </html>

Sprint-3/todo-list/index.html

@@ -3,8 +3,10 @@
   "version": "1.0.0",
   "license": "CC-BY-SA-4.0",
   "description": "You must update this package",
+  "type": "module",
   "scripts": {
-    "test": "jest --config=../jest.config.js todo-list"
+    "serve": "http-server",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest"
   },
   "repository": {
     "type": "git",
@@ -13,5 +15,9 @@
   "bugs": {
     "url": "https://github.com/CodeYourFuture/CYF-Coursework-Template/issues"
   },
-  "homepage": "https://github.com/CodeYourFuture/CYF-Coursework-Template#readme"
+  "homepage": "https://github.com/CodeYourFuture/CYF-Coursework-Template#readme",
+  "devDependencies": {
+    "http-server": "^14.1.1",
+    "jest": "^30.0.4"
+  }
 }

Sprint-3/todo-list/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "todo-list",
+  "version": "1.0.0",
+  "license": "CC-BY-SA-4.0",
+  "description": "You must update this package",
+  "type": "module",
+  "scripts": {
+    "serve": "http-server",    
+    "test": "set NODE_OPTIONS=--experimental-vm-modules && jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CodeYourFuture/CYF-Coursework-Template.git"
+  },
+  "bugs": {
+    "url": "https://github.com/CodeYourFuture/CYF-Coursework-Template/issues"
+  },
+  "homepage": "https://github.com/CodeYourFuture/CYF-Coursework-Template#readme",
+  "devDependencies": {
+    "http-server": "^14.1.1",    
+    "jest": "^30.0.4"
+  }
+}