jong-router 0.1.13 → 0.1.14

package/README.md

@@ -1,30 +1,36 @@
-# JongRouter
+[![NPM](https://nodei.co/npm/jong-router.svg?style=flat&data=v,d&color=red)](https://nodei.co/npm/jong-router/)
 
+# JongRouter
 
 
-A lightweight and simple-to-use web components router in Vanilla JavaScript with support for guards, nested routes, page not found, passing query parameters to components, passing route parameters to components, passing route data to components, and a router link for single-page application navigation without reloading the page.
 
+JongRouter is a lightweight client-side router for Web Components, built with Vanilla JavaScript.
+It enables Single Page Application (SPA) navigation without page reloads while staying framework-agnostic.
+Designed for developers who want a simple router for Web Components without bringing in a heavy framework.
 
 
 ## Features
 
-
-
-- **Routing**: Define routes and associate them with components.
-
-- **Guards**: Implement route guards to control navigation based on conditions. ([Example](https://github.com/josnin/jong-router/tree/main/samples/guards))
-
-- **Nested Routes**: Create hierarchical routes for nested components. ([Example](https://github.com/josnin/jong-router/tree/main/samples/nestedroutes))
-
-- **Page Not Found**: Handle routes that do not match any defined route. ([Example](https://github.com/josnin/jong-router/tree/main/samples/page-not-found))
-
-- **Query Parameters**: Pass query parameters to components. ([Example](https://github.com/josnin/jong-router/tree/main/samples/query-params))
-
-- **Route Parameters**: Extract and pass route parameters to components. ([Example](https://github.com/josnin/jong-router/tree/main/samples/route-params))
-
-- **Route Data**: Include additional data associated with each route. ([Example](https://github.com/josnin/jong-router/tree/main/samples/route-data))
-
-- **Router Link**: Use attribute `router-link` to navigate without reloading the page. ([Example](https://github.com/josnin/jong-router/tree/main/samples/router-link))
+* SPA Navigation
+Navigate without reloading the page using the router-link attribute.
+* Route Guards
+Protect routes with custom guard logic before navigation.
+* Nested Routing
+Easily compose child routers inside Web Components.
+* Shadow DOM Support
+Works seamlessly with Web Components using Shadow DOM.
+* Route Parameters
+Dynamic routes like `/profile/:username`.
+* Query Parameters
+Access query strings like `/profile/jong?tab=settings`.
+* Route Data
+Pass static metadata to components.
+* Programmatic Navigation
+Navigate using `router.navigateTo()`.
+* 404 Page Handling
+Built-in fallback route using **.
+* Buttons & Links Support
+Works with both <a> and <button> elements.
 
 
 
@@ -71,19 +77,23 @@ npm i jong-router
 
 ```javascript
 
-const router = new JongRouter([
+const routes = [
 
   { pattern: '/', component: import('./components/HomeComponent') },
 
   { pattern: '/about', component: import('./components/AboutComponent') },
 
-  // Add more routes as needed
+  { pattern: '**', html: `<h2>Page not found</h2>` }
 
-], document.getElementById('app') );
+]
 
+const router = new JongRouter(
+  routes,
+  document.getElementById('app')
+)
 
+router.init()
 
-router.init();
 
 ```
 
@@ -99,22 +109,19 @@ Create your web components for each route.
 
 ```javascript
 
-// Example: HomeComponent.js
-
 class HomeComponent extends HTMLElement {
 
   connectedCallback() {
 
-    this.innerHTML = '<h1>Home Component</h1>';
+    this.innerHTML = `<h1>Home Page</h1>`
 
   }
 
 }
 
+customElements.define('home-component', HomeComponent)
 
 
-customElements.define('home-component', HomeComponent);
-
 ```
 
 
@@ -137,9 +144,35 @@ Use the `router-link` attribute to create navigation links.
 
 ```
 
+Buttons also work with router-link
+```html
+<button router-link href="/about">
+Go to About
+</button>
+```
 
+4. Programmatic Navigation
+Components can navigate programmatically.
 
-4. **Guards**
+```js
+import { router } from "../router-instance"
+
+router.navigateTo("/profile/admin")
+```
+
+Example inside a component
+```js
+this.shadowRoot
+  .getElementById("btn")
+  .addEventListener("click", () => {
+
+    router.navigateTo("/profile/admin")
+
+  })
+```
+
+
+5. **Guards**
 
 
 
@@ -170,9 +203,11 @@ const router = new JongRouter([
 
 
 
-function isAuthenticated() {
+function isAuthenticated(ctx) {
 
   // Your authentication logic here
+  console.log(ctx.path)
+  console.log(ctx.params)
 
   return true;
 
@@ -182,44 +217,109 @@ function isAuthenticated() {
 
 
 
-5. **Handle Route Parameters and Query Parameters:**
-
+6. **Handle Route Parameters and Query Parameters:**
 
 
-Access route parameters and query parameters in your components.
-
-
-
-```javascript
-
-// Example: UserComponent.js
-
-class UserComponent extends HTMLElement {
-
-  connectedCallback() {
-
-    const routeParams = JSON.parse(this.getAttribute('route-params'));
+Define dynamic routes Parameter:
+```js
+{
+  pattern: "/profile/:username",
+  component: import("./ProfileComponent")
+}
+```
 
-    const queryParams = JSON.parse(this.getAttribute('query-params'));
+Access inside the component
+```js
+const params = JSON.parse(
+  this.getAttribute("route-params")
+)
 
+console.log(params.username)
+```
 
 
-    this.innerHTML = `<h1>User Details</h1>
+Define query parameter
+```js
+/profile/jong?tab=settings
+```
 
-                      <p>User ID: ${routeParams.id}</p>
+Inside component
+```js
+const query = JSON.parse(
+  this.getAttribute("query-params")
+)
 
-                      <p>Query Param: ${queryParams.example}</p>`;
+console.log(query.tab)
+```
 
-  }
+7. **Route Data**
+Attach metadata to routes
 
+```js
+{
+  pattern: "/profile/:username",
+  component: import("./ProfileComponent"),
+  data: { role: "admin" }
 }
+```
+Access in component
+```js
+const data = JSON.parse(
+  this.getAttribute("route-data")
+)
+```
 
 
+8. **Nested Routes**
+JongRouter supports child routers inside components.
 
-customElements.define('user-component', UserComponent);
+Example
+```bash
+/nested
+   ├─ /nested/c1
+   ├─ /nested/c2
+   └─ /nested/c3
+```
 
+A parent component can create its own router instance
+```js
+const childRouter = new JongRouter(
+  childRoutes,
+  this.shadowRoot.getElementById("outlet"),
+  "/nested",
+  true
+)
+
+childRouter.init()
 ```
 
+## Playground & Examples
+Playground & Examples
+The repository contains a Playground demonstrating:
+* Basic routing
+* Guarded routes
+* Nested routes
+* Query parameters
+* Route parameters
+* Programmatic navigation
+* Buttons & router-link navigation
+
+
+# Why JongRouter?
+JongRouter focuses on simplicity and Web Component compatibility.
+Unlike many routers, it:
+* Works without frameworks
+* Supports Shadow DOM
+* Keeps the API extremely small
+* Is easy to embed in micro-frontend architectures
+
+Perfect for:
+* Web Component apps
+* Micro-frontends
+* Lightweight SPAs
+* Vanilla JS projects
+
+
 ## How to run development server? 
 ```
 git clone git@github.com:josnin/jong-router.git 

package/dist/about-component.d.ts

@@ -0,0 +1,4 @@
+export declare const attachShadow: ShadowRootInit;
+export default class About extends HTMLElement {
+    constructor();
+}

package/dist/guard.d.ts

@@ -0,0 +1,2 @@
+import { GuardContext } from './jong-router';
+export declare function authencationGuard(ctx?: GuardContext): boolean;

package/dist/home-component.d.ts

@@ -0,0 +1,4 @@
+export declare const attachShadow: ShadowRootInit;
+export default class Home extends HTMLElement {
+    constructor();
+}

package/dist/jong-router.d.ts

@@ -1,26 +1,30 @@
-interface IRoute {
+export interface GuardContext {
+    path?: string;
+    params?: Record<string, string>;
+    query?: URLSearchParams;
+    data?: any;
+}
+export interface IRoute {
     pattern: string;
     component?: Promise<any>;
     html?: string;
-    guards?: (() => boolean)[];
+    children?: IRoute[];
+    guards?: ((ctx?: any) => boolean)[];
     redirect?: string;
-    data?: any;
+    data?: Record<string, any>;
 }
 declare class JongRouter {
     private routes;
     private outlet;
-    private shadowRoot1;
-    constructor(routes: IRoute[], outlet: HTMLElement, shadowRoot1?: ShadowRoot | undefined);
+    private basePath;
+    private isRoot;
+    constructor(routes: IRoute[], outlet: HTMLElement, basePath?: string, isRoot?: boolean);
     init(): void;
-    private setupNavigation;
-    private navigate;
-    private loadContent;
-    private loadComponent;
     private handleClick;
+    private navigate;
+    private renderRoute;
     private matchRoute;
-    private extractQueryParams;
     private extractRouteParams;
     navigateTo(route: string): void;
 }
-export { IRoute };
 export default JongRouter;

package/dist/jong-router.min.js

@@ -1,2 +1,2 @@
-var a=class{routes;outlet;shadowRoot1;constructor(e,n,t){this.routes=e,this.outlet=n,this.shadowRoot1=t}init(){this.setupNavigation(),this.navigate()}setupNavigation(){window.addEventListener("popstate",()=>this.navigate()),document.addEventListener("click",e=>this.handleClick(e))}navigate(){let e=window.location.pathname,n=this.routes.find(o=>this.matchRoute(o.pattern,e));if(n){if(n.guards&&n.guards.every(s=>{let i=s.bind(this)();return i||(n.redirect?this.navigateTo(n.redirect):console.warn("Guard prevented navigation, and no redirect route specified!")),i===!0})===!1)return;n.component?this.loadComponent(n.component,this.extractRouteParams(n.pattern,e),n.data):n.html?this.loadContent(n.html):console.warn("no component or html route specified!");return}let t=this.routes.find(o=>o.pattern==="**");t&&(t.component?this.loadComponent(t.component,this.extractRouteParams(t.pattern,e),t.data):t.html&&this.loadContent(t.html))}loadContent(e){this.outlet.innerHTML=e}async loadComponent(e,n,t){e.then(o=>{let s=o.default,i=new s,r=this.extractQueryParams();n&&i.setAttribute("route-params",JSON.stringify(n)),t&&i.setAttribute("route-data",JSON.stringify(t)),r&&i.setAttribute("query-params",JSON.stringify(r)),i.router=this,this.outlet.innerHTML="",this.outlet.appendChild(i)}).catch(o=>{console.error(`Error loading component: ${o}`),this.outlet.innerHTML="Component not found"})}handleClick(e){let t=e.composedPath().includes(this.shadowRoot1)?e.composedPath()[0]:e.target;if((t instanceof HTMLAnchorElement||t instanceof HTMLButtonElement)&&t.hasAttribute("router-link")){e.preventDefault();let o=t.getAttribute("href");window.history.pushState({},"",o),this.navigate()}}matchRoute(e,n){let t=e.split("/").filter(s=>s!==""),o=n.split("/").filter(s=>s!=="");return t.length===o.length&&t.every((s,i)=>s.startsWith(":")||s===o[i])}extractQueryParams(){let e=window.location.search,n=new URLSearchParams(e),t={};return n.forEach((o,s)=>{t[s]=o}),t}extractRouteParams(e,n){return e.split("/").reduce((t,o,s)=>(o.startsWith(":")&&(t[o.slice(1)]=n.split("/")[s]),t),{})}navigateTo(e){window.history.pushState({},"",e),this.navigate()}},c=a;export{c as default};
+var s=class c{routes;outlet;basePath;isRoot;constructor(t,a,i="",n=!1){this.routes=t,this.outlet=a,this.basePath=i,this.isRoot=n}init(){this.isRoot&&(window.addEventListener("popstate",()=>this.navigate()),document.addEventListener("click",t=>this.handleClick(t))),this.navigate()}handleClick(t){let i=t.composedPath().find(e=>(e instanceof HTMLAnchorElement||e instanceof HTMLButtonElement)&&e.hasAttribute("router-link"));if(!i)return;let n=i.getAttribute("href");!n||n.startsWith("http")||t instanceof MouseEvent&&(t.metaKey||t.ctrlKey||t.shiftKey||t.altKey)||(t.preventDefault(),this.navigateTo(n))}navigate(){let t=window.location.pathname,a=this.routes.find(n=>this.matchRoute(n.pattern,t));if(!a)return;let i=this.extractRouteParams(a.pattern,t);this.renderRoute(a,i)}async renderRoute(t,a){if(t.guards){let i={path:window.location.pathname,params:a,query:new URLSearchParams(window.location.search),data:t.data};if(!t.guards.every(e=>e(i))){t.redirect&&this.navigateTo(t.redirect);return}}if(t.component){let n=(await t.component).default,e=new n;if(e.setAttribute("route-params",JSON.stringify(a)),e.router=this,this.outlet.innerHTML="",this.outlet.appendChild(e),t.children){let o=e.shadowRoot?.querySelector("[router-outlet]")||e.querySelector("[router-outlet]");o&&new c(t.children,o,t.pattern).navigate()}}else t.html&&(this.outlet.innerHTML=t.html)}matchRoute(t,a){if(t==="**")return!0;let i=t.split("/").filter(Boolean),n=a.split("/").filter(Boolean);return i.length>n.length?!1:i.every((e,o)=>e.startsWith(":")||e===n[o])}extractRouteParams(t,a){let i={},n=t.split("/").filter(Boolean),e=a.split("/").filter(Boolean);return n.forEach((o,r)=>{o.startsWith(":")&&(i[o.slice(1)]=e[r])}),i}navigateTo(t){window.history.pushState({},"",t),this.navigate()}},h=s;export{h as default};
 //# sourceMappingURL=jong-router.min.js.map

package/dist/notfound-component.d.ts

@@ -0,0 +1,4 @@
+export declare const attachShadow: ShadowRootInit;
+export default class NotFound extends HTMLElement {
+    constructor();
+}

package/dist/profile-component.d.ts

@@ -0,0 +1,6 @@
+export declare const attachShadow: ShadowRootInit;
+export default class Profile extends HTMLElement {
+    router: any;
+    constructor();
+    connectedCallback(): void;
+}

package/dist/team-component.d.ts

@@ -0,0 +1,5 @@
+export declare const attachShadow: ShadowRootInit;
+export default class Team extends HTMLElement {
+    constructor();
+    connectedCallback(): void;
+}

package/package.json

@@ -1,11 +1,25 @@
 {
   "name": "jong-router",
-  "version": "0.1.13",
-  "description": "A lightweight and simple-to-use web components router in Vanilla JavaScript with support for guards, nested routes, page not found, passing query parameters to components, passing route parameters to components, passing route data to components, and a router link for single-page application navigation without reloading the page.",
+  "version": "0.1.14",
+  "description": "JongRouter is a lightweight client-side router for Web Components, built with Vanilla JavaScript. It enables Single Page Application (SPA) navigation without page reloads while staying framework-agnostic.Designed for developers who want a simple router for Web Components without bringing in a heavy framework",
   "keywords": [
+    "redgin",
+    "ScalpelJS",
     "jong-router",
+    "web-components",
     "web components router",
-    "custom elements"
+    "custom elements",
+    "vanilla javascript",
+    "spa",
+    "single-page application",
+    "client-side router",
+    "frontend router",
+    "nested routes",
+    "route guards",
+    "query parameters",
+    "route parameters",
+    "javascript router",
+    "microfrontend"
   ],
   "main": "dist/jong-router.min.js",
   "types": "dist/jong-router.d.ts",

package/router-instance.ts

@@ -0,0 +1,30 @@
+// index.ts
+import JongRouter, { IRoute } from './src/jong-router'
+import { authencationGuard } from './src/guard'
+
+const routes: IRoute[] = [
+  { pattern: '/about', html: `<h2>About Page</h2>` },
+  { pattern: '/profile/:username', component: import('./samples/profile/profile-component') },
+  { pattern: '/tryguard1/:teamId', component: import('./samples/guards/team-component'), guards: [authencationGuard], redirect: '/login' },
+  { pattern: '/login', html: `<h2>Login Page</h2>` },
+    {
+    pattern: "/programmatic",
+    component: import("./samples/programmatic/programmatic-navigation"),
+  },
+
+  {
+  pattern: '/nested',
+  component: import('./samples/nested/sample-nested'),
+  children: [
+    { pattern: '/nested/c1', html: '<p>Nested C1 Page</p>' },
+    { pattern: '/nested/c2', html: '<p>Nested C2 Page</p>' },
+    { pattern: '/nested/c3', html: '<p>Nested C3 Page</p>' },
+    { pattern: '**', html: '<p>Nested 404</p>' }
+  ]
+},
+  { pattern: '**', html: `<h2>404 Page</h2>` }
+]
+
+export const router = new JongRouter(routes, document.getElementById('app')!, '', true)
+router.init()
+