npm - @aref-shojaei/router - Versions diffs - 1.0.2 → 1.1.0 - Mend

@aref-shojaei/router 1.0.2 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

package/README.md +332 -205
package/example/assets/css/styles.css +45 -45
package/example/assets/js/app.js +7 -7
package/example/assets/js/router.min.js +1 -1
package/example/index.html +26 -26
package/example/package.json +18 -18
package/example/server.js +17 -17
package/index.js +6 -4
package/package.json +48 -42
package/src/dto/route.js +13 -13
package/src/exception.js +5 -5
package/src/page.js +91 -91
package/src/route.js +103 -103
package/src/router.js +207 -207
package/src/utils/element.js +23 -23
package/src/utils/selector.js +59 -59
package/src/view.js +24 -24
package/tests/unit/element.test.js +32 -32
package/tests/unit/page.test.js +48 -48
package/tests/unit/route.test.js +82 -82
package/tests/unit/router.test.js +55 -55
package/tests/unit/selector.test.js +42 -42
package/tests/unit/view.test.js +46 -46
package/webpack.config.js +23 -0
package/.babelrc +0 -3

package/README.md CHANGED Viewed

@@ -1,205 +1,332 @@
-![SPA (1)](https://github.com/user-attachments/assets/7e76a68b-84f0-4fa7-b961-26319d3ed3bc)
-<h1 align='center'>Router - SPA Application</h1>
-> app.js
-```js
-import { Router, Route } from "@aref-shojaei/router"
-// Confgiure router system
-Router.configure({ window, document })
-// Single Route
-Route.add("/", () => "Welcome Page")
-// Group Routes
-Route.group("/auth", () => {
-    Route.add("/login", () => "Login Page")
-    Route.add("/register", () => "Register Page")
-})
-// Dynamic Route
-Route.add("/users/{id}", ({ params : { name } }) => `User#${id} Page`)
-// Redirect Routes
-Route.add("/redirection", () => Route.redirect("/"))
-// Initialize the router
-Router.run()
-```
-> index.html
-```html
-<html>
-    <head>
-        <title>SPA App</title>
-    </head>
-    <body>
-        <ul>
-            <!-- Redirect to local links -->
-            <li><a href="/">Home</a></li>
-            <li><a href="/auth/login">Login</a></li>
-            <li><a href="/auth/register">Register</a></li>
-            <li><a href="/users/2904152">Admin Page</a></li>
-            <li><a href="/redirection">Redirect to a page</a></li>
-            <!-- Redirect to external resources -->
-            <li><a href="https://github.com/ArefShojaei/Router" data-link>Github</a></li>
-        </ul>
-        <div id="root"></div>
-        <script src="app.js"></script>
-    </body>
-</html>
-```
-##  Guide :
-1. [Introduction](#introduction)
-    * [What is this library ?](#what-is-this-library)
-    * [Why should I use it ?](#why-should-i-use-it)
-    * [Is it work like SPA ?](#is-it-work-like-spa)
-2. [installation](#installation)
-3. [tutorial](#tutorial)
-<br/>
-## Introduction
-<br/>
-### What is this library ?
-> This library is for handling routes in the browser env by HTTP requests!
-```bash
-* Back-end:
-[Request] GET /blog  => [Response] HTML | JSON
-* Front-end:
-Page -> [Route] /blog -> Update content -> without refereshing -> Render template
-```
-<br>
-### Why should I use it ?
-> If you like to have application or pages not to need to referesh again for every action | request + high performance for loading content (SPA)
-<br>
-### Is it work like SPA ?
-> Sure You can get this options to use the library:
-* Add Signle Route
-* Add the group routes
-* Add middleware to every routes (back-end concept)
-* Add route redirection
-* Add pages as component or template files to specific route
-* More ...
-<br>
-## Installation
-> NPM
-```bash
-npm i @aref-shojaei/router
-```
-> Yarn
-```bash
-yarn add @aref-shojaei/router
-```
-<br/>
-> Setup - app.js
-```js
-import { Router , Route } from "@aref-shojaei/router"
-Route.add("/", () => "Welcome Page")
-Router.run()
-```
-**Note: Don't forget to read guides again!**
-<br/>
-## Tutorial
-> Route
-* Single type
-* Group type
-* Dynamic type
-```js
-import { Route } from "@aref-shojaei/router"
-// Single route
-Route.add("/", () => "Welcome Page")
-// Group routes
-Route.group("/auth", () => {
-    Route.add("/login", () => "Welcome Page")
-    Route.add("/register", () => "Welcome Page")
-})
-// Dynamic route with params
-Route.add("/users/{id}", ({ params : { id } }) => `User #{id} Page`)
-Route.add("/courses/{category}/{name}", ({ params : { category, name } }) => `Course Detail: '${category}/${name}'  Page`)
-```
-<br/>
-> Middleware
-* Note: Midddleware is a function to call before every routes
-```js
-import { Route } from "@aref-shojaei/router"
-// Middleware
-const logger = () => console.log("[LOG] my custom middleware")
-// Single route with middleware
-Route.add("/", () => "Welcome Page").middleware([logger])
-// Group routes with middleware
-Route.group("/auth", () => {
-    Route.add("/login", () => "Welcome Page")
-    Route.add("/register", () => "Welcome Page")
-}).middleware([logger])
-```
-<br/>
-> Route Redirection
-```js
-import { Route } from "@aref-shojaei/router"
-Route.add("/auth/login", () => "Welcome Page")
-Route.add("/dashboard", () => Route.redirect("/auth/login"))
-```
-<br/>
-> Route page title
-* Note: If I don't use it, page title is applied from document.title by default!
-```js
-import { Route } from "@aref-shojaei/router"
-Route.add("/", () => "Welcome Page").title("Custom Page Title | SPA")
-```
+<div align="center">
+# 🚀 Router - Lightweight JavaScript SPA Router
+A lightweight and powerful client-side routing library for building Single Page Applications (SPA) with pure JavaScript.
+Define routes, manage navigation, handle dynamic parameters, apply middleware, and create seamless page transitions without refreshing the browser.
+<img src="https://github.com/user-attachments/assets/f1831dc5-f72e-4d7a-806d-b9c01b4be29a" alt="Router SPA Banner" />
+</div>
+---
+## ✨ Features
+* 🚀 Client-side SPA routing
+* 🔗 Browser History API support
+* 📄 Single and grouped routes
+* 🔥 Dynamic route parameters
+* 🛡 Route middleware system
+* 🔀 Route redirection
+* 🏷 Dynamic page titles
+* ⚡ No page refresh navigation
+* 🪶 Lightweight and dependency-free
+* 🧩 Simple and expressive API
+---
+# 📦 Installation
+## Using NPM
+```bash
+npm install @aref-shojaei/router
+```
+## Using Yarn
+```bash
+yarn add @aref-shojaei/router
+```
+---
+# 🚀 Quick Start
+Create your `app.js` file:
+```javascript
+import { Router, Route } from "@aref-shojaei/router";
+// Configure browser environment
+Router.configure({
+    window,
+    document
+});
+// Create routes
+Route.add("/", () => "Home Page");
+Route.group("/auth", () => {
+    Route.add("/login", () => "Login Page");
+    Route.add("/register", () => "Register Page");
+});
+// Dynamic routes
+Route.add("/users/{id}", ({ params: { id } }) => {
+    return `User #${id}`;
+});
+// Start the router
+Router.run();
+```
+---
+# 🌐 HTML Integration
+The router automatically intercepts internal links and updates the page without refreshing the browser.
+```html
+<body>
+    <nav>
+        <a href="/">Home</a>
+        <a href="/auth/login">Login</a>
+        <a href="/auth/register">Register</a>
+        <a href="/users/10">User Profile</a>
+    </nav>
+    <div id="root"></div>
+    <script src="app.js"></script>
+</body>
+```
+---
+# 🏗 Router Workflow
+```txt
+User Click
+     |
+     |
+ Browser Event
+     |
+     |
+ Router Engine
+     |
+     |
+ Route Matching
+     |
+     |
+ Middleware
+     |
+     |
+ Component Rendering
+     |
+     |
+ DOM Update
+```
+---
+# 📚 Routing Guide
+## Basic Routes
+Create simple routes:
+```javascript
+Route.add("/", () => "Welcome Page");
+Route.add("/about", () => "About Page");
+```
+---
+## Route Groups
+Organize related routes together.
+```javascript
+Route.group("/auth", () => {
+    Route.add("/login", () => "Login Page");
+    Route.add("/register", () => "Register Page");
+});
+```
+Generated routes:
+```txt
+/auth/login
+/auth/register
+```
+---
+## Dynamic Routes
+Capture values directly from the URL.
+```javascript
+Route.add("/users/{id}", ({ params: { id } }) => {
+    return `User ID: ${id}`;
+});
+```
+Multiple parameters:
+```javascript
+Route.add(
+    "/courses/{category}/{name}",
+    ({ params: { category, name } }) => {
+        return `${category} / ${name}`;
+    }
+);
+```
+---
+# 🛡 Middleware
+Middleware allows you to execute custom logic before rendering a route.
+Common use cases:
+* Authentication checks
+* Logging
+* Analytics
+* Permissions
+* Data preparation
+Example:
+```javascript
+const logger = () => {
+    console.log("[LOG] Route visited");
+};
+Route.add(
+    "/dashboard",
+    () => "Dashboard"
+).middleware([logger]);
+```
+Group middleware:
+```javascript
+Route.group("/admin", () => {
+    Route.add("/users", () => "Users");
+    Route.add("/settings", () => "Settings");
+}).middleware([logger]);
+```
+---
+# 🔀 Route Redirection
+Redirect users to another route.
+```javascript
+Route.add("/login", () => "Login Page");
+Route.add("/dashboard", () => {
+    return Route.redirect("/login");
+});
+```
+---
+# 🏷 Page Titles
+Change the browser tab title dynamically.
+```javascript
+Route.add("/", () => "Home")
+    .title("My Awesome SPA");
+```
+If no title is specified, the router uses the default `document.title`.
+---
+# 📂 Example Project Structure
+```txt
+my-spa/
+|
+├── index.html
+|
+├── app.js
+|
+└── node_modules/
+```
+---
+# 💡 Use Cases
+Router can be used for:
+* Single Page Applications (SPA)
+* Dashboard interfaces
+* Admin panels
+* Personal websites
+* Progressive Web Applications
+* Educational projects to learn routing concepts
+---
+# 🔥 Why Router?
+Traditional websites require a full page reload for every navigation.
+With Router:
+```txt
+Traditional Website
+Click Link
+    |
+HTTP Request
+    |
+Server Response
+    |
+Reload Entire Page
+SPA Router
+Click Link
+    |
+JavaScript Router
+    |
+Change Route
+    |
+Update DOM
+```
+This results in a faster and smoother user experience.
+---
+# 🧠 Concepts You Will Learn
+By studying this project, you can understand:
+* Browser History API
+* URL parsing
+* Route matching algorithms
+* Dynamic parameters
+* Middleware patterns
+* Event handling
+* Client-side rendering
+* SPA architecture
+---
+# 👨‍💻 Author
+**Aref Shojaei**
+- 📧 Email: [arefshojaei82@gmail.com](mailto:arefshojaei82@gmail.com)
+- 🐙 GitHub: [@ArefShojaei](https://github.com/ArefShojaei)
+---
+# ⭐ Show Your Support
+If this project helps you understand SPA architecture and client-side routing, consider giving it a **Star ⭐ on GitHub**.
+Your support helps the project grow.

package/example/assets/css/styles.css CHANGED Viewed

@@ -1,46 +1,46 @@
-* {
-    box-sizing: border-box;
-    padding: 0;
-    margin: 0;
-    font-family: sans-serif;
-}
-body {
-    display: flex;
-    flex-direction: column;
-    align-items: center;
-    padding: 24px;
-}
-ul {
-    display: flex;
-    align-items: center;
-    margin-top: 16px;
-}
-ul li {
-    margin: 0 24px;
-    list-style: none;
-}
-ul li a {
-    padding: 4 8px;
-    color: #81a6f4;
-    text-decoration: none;
-}
-ul li a:hover {
-    color: #2b2b2a;
-    transition: all .5s ease;
-}
-#root {
-    padding: 16px;
-    text-align: center;
-    margin-top: 40px;
-    background: #ded7d7;
-    width: 600px;
-    height: 250px;
-    border-radius: 16px;
+* {
+    box-sizing: border-box;
+    padding: 0;
+    margin: 0;
+    font-family: sans-serif;
+}
+body {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    padding: 24px;
+}
+ul {
+    display: flex;
+    align-items: center;
+    margin-top: 16px;
+}
+ul li {
+    margin: 0 24px;
+    list-style: none;
+}
+ul li a {
+    padding: 4 8px;
+    color: #81a6f4;
+    text-decoration: none;
+}
+ul li a:hover {
+    color: #2b2b2a;
+    transition: all .5s ease;
+}
+#root {
+    padding: 16px;
+    text-align: center;
+    margin-top: 40px;
+    background: #ded7d7;
+    width: 600px;
+    height: 250px;
+    border-radius: 16px;
 }

package/example/assets/js/app.js CHANGED Viewed

@@ -1,8 +1,8 @@
-Router.configure({ window, document })
-Route.add("/", () => "Welcome Page")
-Route.add("/users", () => "Users Page")
-Route.add("/users/{name}", ({ params : { name } }) => `User #${name} Page`)
-Route.add("/redirection", () => Route.redirect("/"))
+Router.configure({ window, document })
+Route.add("/", () => "Welcome Page")
+Route.add("/users", () => "Users Page")
+Route.add("/users/{name}", ({ params : { name } }) => `User #${name} Page`)
+Route.add("/redirection", () => Route.redirect("/"))
 Router.run()