jong-router 0.1.13 → 0.1.15

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,37 @@ 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.
+
+Example outside component
+
+```js
+import { router } from "../router-instance"
+
+router.navigateTo("/profile/admin")
+```
 
+Example inside a component
+```js
+this.shadowRoot
+  .getElementById("btn")
+  .addEventListener("click", () => {
+
+    this.navigateTo("/profile/admin")
+
+  })
+```
 
-4. **Guards**
+
+5. **Guards**
 
 
 
@@ -147,7 +182,7 @@ Implement guards for route conditions
 
 
 
-```javascript
+```js
 
 const router = new JongRouter([
 
@@ -170,9 +205,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 +219,146 @@ function isAuthenticated() {
 
 
 
-5. **Handle Route Parameters and Query Parameters:**
+6. **Handle Route Parameters and Query Parameters:**
 
 
+Define dynamic routes Parameter:
+```js
+{
+  pattern: "/profile/:username",
+  component: import("./ProfileComponent")
+}
+```
 
-Access route parameters and query parameters in your components.
+Access inside the component
+```js
+const params = JSON.parse(
+  this.getAttribute("route-params")
+)
 
+console.log(params.username)
+```
 
 
-```javascript
+Define query parameter
+```js
+/profile/jong?tab=settings
+```
 
-// Example: UserComponent.js
+Inside component
+```js
+const query = JSON.parse(
+  this.getAttribute("query-params")
+)
 
-class UserComponent extends HTMLElement {
+console.log(query.tab)
+```
 
-  connectedCallback() {
+7. **Route Data**
+Attach metadata to routes
 
-    const routeParams = JSON.parse(this.getAttribute('route-params'));
+```js
+{
+  pattern: "/profile/:username",
+  component: import("./ProfileComponent"),
+  data: { role: "admin" }
+}
+```
+Access in component
+```js
+const data = JSON.parse(
+  this.getAttribute("route-data")
+)
+```
 
-    const queryParams = JSON.parse(this.getAttribute('query-params'));
 
+8. **Nested Routes & Sub-Outlest**
 
+JongRouter supports hierarchical routing. This allows you to render a "Shell" or "Layout" component and then inject sub-pages into it dynamically.
 
-    this.innerHTML = `<h1>User Details</h1>
+Step 1: Define Child Routes
+Create a separate file for your sub-navigation.
 
-                      <p>User ID: ${routeParams.id}</p>
+Example
+```ts
+// samples/nested/nested-routes.ts
+import { IRoute } from "../../src/jong-router"
 
-                      <p>Query Param: ${queryParams.example}</p>`;
+const routes: IRoute[] = [
+  { pattern: "/nested/c1", html: "<p>Child Page 1</p>" },
+  { pattern: "/nested/c2", html: "<p>Child Page 2</p>" },
+  { pattern: "/nested/c3", html: "<p>Child Page 3</p>" }
+]
 
-  }
+export default routes
 
-}
+```
 
+Step 2: Prepare the Parent Component
+Your parent component must contain an element with the router-outlet attribute. This is where the child routes will be rendered.
+
+A parent component can create its own router instance w children routes
+```ts
+// samples/nested/sample-nested.ts
+export default class SampleNested extends HTMLElement {
+  connectedCallback() {
+    this.innerHTML = `
+      <div class="layout">
+        <nav>
+          <a href="/nested/c1" router-link>Go to C1</a>
+          <a href="/nested/c2" router-link>Go to C2</a>
+        </nav>
+        <!-- Child routes will appear here -->
+        <div router-outlet></div> 
+      </div>
+    `;
+  }
+}
 
+```
 
-customElements.define('user-component', UserComponent);
+Step 3: Register Nested Routes
+Pass the children to the parent route. You can use a static array or a function for Lazy Loading.
+```ts
+const routes: IRoute[] = [
+  {
+    pattern: '/nested',
+    component: import('./samples/nested/sample-nested'),
+    // Lazy-load the child route definitions
+    children: () => import("./samples/nested/nested-routes") 
+  }
+]
 
 ```
 
+
+## 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,57 @@
-interface IRoute {
+/**
+ * Context passed to Route Guards to decide if a user can access a route.
+ */
+export interface GuardContext {
+    path?: string;
+    params?: Record<string, string>;
+    query?: URLSearchParams;
+    data?: any;
+}
+/**
+ * Definition of a single Route.
+ */
+export interface IRoute {
     pattern: string;
     component?: Promise<any>;
     html?: string;
-    guards?: (() => boolean)[];
+    children?: IRoute[] | (() => Promise<{
+        default: 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);
+    constructor(routes: IRoute[], outlet: HTMLElement);
+    /**
+     * Starts the router by listening to browser events and initial navigation.
+     */
     init(): void;
-    private setupNavigation;
-    private navigate;
-    private loadContent;
-    private loadComponent;
+    /**
+     * Intercepts clicks to handle internal navigation without refreshing the page.
+     */
     private handleClick;
+    /**
+     * Matches the current browser URL against the route table and triggers rendering.
+     */
+    private navigate;
+    /**
+     * Handles Guards, Component instantiation, and Nested routes.
+     */
+    private renderRoute;
+    /**
+     * Basic string matching. Supports ':param' wildcards and '**' catch-all.
+     */
     private matchRoute;
-    private extractQueryParams;
+    /**
+     * Maps URL values to parameter names based on the pattern.
+     */
     private extractRouteParams;
+    /**
+     * Programmatic navigation (e.g., router.navigateTo('/dashboard'))
+     */
     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 l=class{routes;outlet;constructor(t,i){this.routes=t,this.outlet=i}init(){window.addEventListener("popstate",()=>this.navigate()),document.addEventListener("click",t=>this.handleClick(t)),this.navigate()}handleClick(t){let a=t.composedPath().find(n=>(n instanceof HTMLAnchorElement||n instanceof HTMLButtonElement)&&n.hasAttribute("router-link"));if(!a)return;let e=a.getAttribute("href");!e||e.startsWith("http")||t instanceof MouseEvent&&(t.metaKey||t.ctrlKey||t.shiftKey||t.altKey)||(t.preventDefault(),this.navigateTo(e))}navigate(){let t=window.location.pathname,i=this.routes.sort((e,n)=>n.pattern.length-e.pattern.length).find(e=>this.matchRoute(e.pattern,t));if(!i)return;let a=this.extractRouteParams(i.pattern,t);this.renderRoute(i,a)}async renderRoute(t,i,a=this.outlet){if(t.guards){let n={path:window.location.pathname,params:i,query:new URLSearchParams(window.location.search),data:t.data};if(!t.guards.every(o=>o(n))){t.redirect&&this.navigateTo(t.redirect);return}}let e=null;if(t.component){let r=(await t.component).default;e=new r,e.setAttribute("route-params",JSON.stringify(i)),e.router=this,a.innerHTML="",a.appendChild(e)}else t.html&&(a.innerHTML=t.html);if(t.children){let n;typeof t.children=="function"?n=(await t.children()).default:n=t.children;let r=e?.shadowRoot?.querySelector("[router-outlet]")||e?.querySelector("[router-outlet]")||a,o=window.location.pathname,c=n.sort((s,h)=>h.pattern.length-s.pattern.length).find(s=>this.matchRoute(s.pattern,o));if(c){let s=this.extractRouteParams(c.pattern,o);await this.renderRoute(c,s,r)}}}matchRoute(t,i){if(t==="**")return!0;let a=t.split("/").filter(Boolean),e=i.split("/").filter(Boolean);return a.length>e.length?!1:a.every((n,r)=>n.startsWith(":")||n===e[r])}extractRouteParams(t,i){let a={},e=t.split("/").filter(Boolean),n=i.split("/").filter(Boolean);return e.forEach((r,o)=>{r.startsWith(":")&&(a[r.slice(1)]=n[o])}),a}navigateTo(t){window.history.pushState({},"",t),this.navigate()}},u=l;export{u 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.15",
+  "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,27 @@
+// index.ts
+import JongRouter, { IRoute } from './src/jong-router'
+import { authencationGuard } from './samples/guards/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: () => import("./samples/nested/nested-routes")
+  },
+  { pattern: '**', html: `<h2>404 Page</h2>` }
+]
+
+export const router = new JongRouter(routes, document.getElementById('app')!)
+router.init()
+
+
+