ziko 0.50.2 → 0.51.0

package/dist/ziko.js

@@ -2,7 +2,7 @@
 /*
   Project: ziko.js
   Author: Zakaria Elalaoui
-  Date : Wed Dec 03 2025 10:48:15 GMT+0100 (UTC+01:00)
+  Date : Wed Dec 03 2025 10:58:16 GMT+0100 (UTC+01:00)
   Git-Repo : https://github.com/zakarialaoui10/ziko.js
   Git-Wiki : https://github.com/zakarialaoui10/ziko.js/wiki
   Released under MIT License
@@ -2026,38 +2026,137 @@
         }
     }
 
-    function ptr_details_setter(){
-        switch(this.currentEvent){
-            case "pointerdown" : {
-                this.dx = parseInt(this.event.offsetX);
-                this.dy = parseInt(this.event.offsetY);
+    function ptr_details_setter() {
+        const rect = this.targetElement.getBoundingClientRect();
+        const e = this.event;
+        let x = (e.clientX - rect.left) | 0;
+        let y = (e.clientY - rect.top) | 0;
+
+        if(this.cache.useNormalisedCoordinates){
+            const w = this.targetElement.clientWidth;
+            const h = this.targetElement.clientHeight;
+            x = +((x / w) * 2 - 1).toFixed(8);
+            y = +((y / h) * -2 + 1).toFixed(8);
+        }
+        switch (this.currentEvent) {
+
+            case "pointerdown":
+                this.dx = x;
+                this.dy = y;
                 this.isDown = true;
-            } break;
-            case "pointermove" : {
-                this.mx = parseInt(this.event.offsetX);
-                this.my = parseInt(this.event.offsetY);
+                break;
+
+            case "pointermove":
+                this.mx = x;
+                this.my = y;
                 this.isMoving = true;
-            } break;
-            case "pointerup" : {
-                this.ux = parseInt(this.event.offsetX);
-                this.uy = parseInt(this.event.offsetY);
+                break;
+
+            case "pointerup":
+                this.ux = x;
+                this.uy = y;
                 this.isDown = false;
-                console.log(this.target.width);
-                const delta_x=(this.ux-this.dx)/this.target.width;
-                const delta_y=(this.dy-this.uy)/this.target.height;
-                const HORIZONTAL_SWIPPE=(delta_x<0)?"left":(delta_x>0)?"right":"none";
-                const VERTICAL_SWIPPE=(delta_y<0)?"bottom":(delta_y>0)?"top":"none";
-                this.swippe={
-                    h:HORIZONTAL_SWIPPE,
-                    v:VERTICAL_SWIPPE,
-                    delta_x,
-                    delta_y
-                };
-            } break;
+                this.isMoving = false;
+                break;
+        }
+    }
+
+    function mouse_details_setter() {
+        const rect = this.targetElement.getBoundingClientRect();
+        const e = this.event;
+        let x = (e.clientX - rect.left) | 0;
+        let y = (e.clientY - rect.top) | 0;
+
+        if(this.cache.useNormalisedCoordinates){
+            const w = this.targetElement.clientWidth;
+            const h = this.targetElement.clientHeight;
+            x = +((x / w) * 2 - 1).toFixed(8);
+            y = +((y / h) * -2 + 1).toFixed(8);
+        }
+
+        switch (this.currentEvent) {
+
+            case "mousedown":
+                this.dx = x;
+                this.dy = y;
+                this.isDown = true;
+                break;
+
+            case "mousemove":
+                this.mx = x;
+                this.my = y;
+                this.isMoving = true;
+                break;
+
+            case "mouserup":
+                this.ux = x;
+                this.uy = y;
+                this.isDown = false;
+                this.isMoving = false;
+                break;
+        }
+    }
+
+    function touch_details_setter() {
+        const e = this.event;
+        const touch = e.touches?.[0] || e.changedTouches?.[0];
+
+        if (!touch) return; // should never happen but safe
+
+        const rect = this.targetElement.getBoundingClientRect();
+        let x = touch.clientX - rect.left;
+        let y = touch.clientY - rect.top;
+
+        if(this.cache.useNormalisedCoordinates){
+            const w = this.targetElement.clientWidth;
+            const h = this.targetElement.clientHeight;
+            x = +((x / w) * 2 - 1).toFixed(8);
+            y = +((y / h) * -2 + 1).toFixed(8);
+        }
+
+        switch (this.currentEvent) {
+            case "touchstart":
+                this.dx = x;
+                this.dy = y;
+                this.isDown = true;
+                break;
+
+            case "touchmove":
+                this.mx = x;
+                this.my = y;
+                this.isMoving = true;
+                break;
+
+            case "touchend":
+                this.ux = x;
+                this.uy = y;
+                this.isDown = false;
+                break;
+        }
+    }
+
+    class CoordinatesBasedEvent extends ZikoEvent{
+        constructor(signature, target = null, Events = [], details_setter, customizer){
+            super(signature, target, Events, details_setter, customizer);
+            Object.assign(this.cache,{
+                useNormalisedCoordinates : false
+            });
+            this.isDown = false;
+            this.isMoving = false;
+            this.dx = 0;
+            this.dy = 0;
+            this.mx = 0;
+            this.my = 0;
+            this.ux = 0;
+            this.uy = 0;
+        }
+        get isDragging(){
+            return this.isDown && this.isMoving
+        }
+        useNormalisedCoordinates(enable = true){
+            this.cache.useNormalisedCoordinates = enable;
+            return this;
         }
-        // if(this.currentEvent==="click") this.dx = 0
-        // else this.dx = 1
-        // console.log(this.currentEvent)
     }
 
     class ClickAwayEvent extends Event {
@@ -2288,25 +2387,25 @@
         key_details_setter, 
         customizer
     );
-    const bind_mouse_event = (target, customizer) => new ZikoEvent(
+    const bind_mouse_event = (target, customizer) => new CoordinatesBasedEvent(
         'mouse',
         target,
         EventsMap.Mouse,
-        null,
+        mouse_details_setter,
         customizer
     );
-    const bind_pointer_event = (target, customizer) => new ZikoEvent(
+    const bind_pointer_event = (target, customizer) => new CoordinatesBasedEvent(
         'ptr',
         target,
         EventsMap.Ptr, 
         ptr_details_setter, 
         customizer
     );
-    const bind_touch_event = (target, customizer) => new ZikoEvent(
+    const bind_touch_event = (target, customizer) => new CoordinatesBasedEvent(
         'touch',
         target,
         EventsMap.Touch,
-        null,
+        touch_details_setter,
         customizer
     );
     const bind_wheel_event = (target, customizer) => new ZikoEvent(

package/dist/ziko.mjs

@@ -2,7 +2,7 @@
 /*
   Project: ziko.js
   Author: Zakaria Elalaoui
-  Date : Wed Dec 03 2025 10:48:15 GMT+0100 (UTC+01:00)
+  Date : Wed Dec 03 2025 10:58:16 GMT+0100 (UTC+01:00)
   Git-Repo : https://github.com/zakarialaoui10/ziko.js
   Git-Wiki : https://github.com/zakarialaoui10/ziko.js/wiki
   Released under MIT License
@@ -2020,38 +2020,137 @@ function key_details_setter(){
     }
 }
 
-function ptr_details_setter(){
-    switch(this.currentEvent){
-        case "pointerdown" : {
-            this.dx = parseInt(this.event.offsetX);
-            this.dy = parseInt(this.event.offsetY);
+function ptr_details_setter() {
+    const rect = this.targetElement.getBoundingClientRect();
+    const e = this.event;
+    let x = (e.clientX - rect.left) | 0;
+    let y = (e.clientY - rect.top) | 0;
+
+    if(this.cache.useNormalisedCoordinates){
+        const w = this.targetElement.clientWidth;
+        const h = this.targetElement.clientHeight;
+        x = +((x / w) * 2 - 1).toFixed(8);
+        y = +((y / h) * -2 + 1).toFixed(8);
+    }
+    switch (this.currentEvent) {
+
+        case "pointerdown":
+            this.dx = x;
+            this.dy = y;
             this.isDown = true;
-        } break;
-        case "pointermove" : {
-            this.mx = parseInt(this.event.offsetX);
-            this.my = parseInt(this.event.offsetY);
+            break;
+
+        case "pointermove":
+            this.mx = x;
+            this.my = y;
             this.isMoving = true;
-        } break;
-        case "pointerup" : {
-            this.ux = parseInt(this.event.offsetX);
-            this.uy = parseInt(this.event.offsetY);
+            break;
+
+        case "pointerup":
+            this.ux = x;
+            this.uy = y;
             this.isDown = false;
-            console.log(this.target.width);
-            const delta_x=(this.ux-this.dx)/this.target.width;
-            const delta_y=(this.dy-this.uy)/this.target.height;
-            const HORIZONTAL_SWIPPE=(delta_x<0)?"left":(delta_x>0)?"right":"none";
-            const VERTICAL_SWIPPE=(delta_y<0)?"bottom":(delta_y>0)?"top":"none";
-            this.swippe={
-                h:HORIZONTAL_SWIPPE,
-                v:VERTICAL_SWIPPE,
-                delta_x,
-                delta_y
-            };
-        } break;
+            this.isMoving = false;
+            break;
+    }
+}
+
+function mouse_details_setter() {
+    const rect = this.targetElement.getBoundingClientRect();
+    const e = this.event;
+    let x = (e.clientX - rect.left) | 0;
+    let y = (e.clientY - rect.top) | 0;
+
+    if(this.cache.useNormalisedCoordinates){
+        const w = this.targetElement.clientWidth;
+        const h = this.targetElement.clientHeight;
+        x = +((x / w) * 2 - 1).toFixed(8);
+        y = +((y / h) * -2 + 1).toFixed(8);
+    }
+
+    switch (this.currentEvent) {
+
+        case "mousedown":
+            this.dx = x;
+            this.dy = y;
+            this.isDown = true;
+            break;
+
+        case "mousemove":
+            this.mx = x;
+            this.my = y;
+            this.isMoving = true;
+            break;
+
+        case "mouserup":
+            this.ux = x;
+            this.uy = y;
+            this.isDown = false;
+            this.isMoving = false;
+            break;
+    }
+}
+
+function touch_details_setter() {
+    const e = this.event;
+    const touch = e.touches?.[0] || e.changedTouches?.[0];
+
+    if (!touch) return; // should never happen but safe
+
+    const rect = this.targetElement.getBoundingClientRect();
+    let x = touch.clientX - rect.left;
+    let y = touch.clientY - rect.top;
+
+    if(this.cache.useNormalisedCoordinates){
+        const w = this.targetElement.clientWidth;
+        const h = this.targetElement.clientHeight;
+        x = +((x / w) * 2 - 1).toFixed(8);
+        y = +((y / h) * -2 + 1).toFixed(8);
+    }
+
+    switch (this.currentEvent) {
+        case "touchstart":
+            this.dx = x;
+            this.dy = y;
+            this.isDown = true;
+            break;
+
+        case "touchmove":
+            this.mx = x;
+            this.my = y;
+            this.isMoving = true;
+            break;
+
+        case "touchend":
+            this.ux = x;
+            this.uy = y;
+            this.isDown = false;
+            break;
+    }
+}
+
+class CoordinatesBasedEvent extends ZikoEvent{
+    constructor(signature, target = null, Events = [], details_setter, customizer){
+        super(signature, target, Events, details_setter, customizer);
+        Object.assign(this.cache,{
+            useNormalisedCoordinates : false
+        });
+        this.isDown = false;
+        this.isMoving = false;
+        this.dx = 0;
+        this.dy = 0;
+        this.mx = 0;
+        this.my = 0;
+        this.ux = 0;
+        this.uy = 0;
+    }
+    get isDragging(){
+        return this.isDown && this.isMoving
+    }
+    useNormalisedCoordinates(enable = true){
+        this.cache.useNormalisedCoordinates = enable;
+        return this;
     }
-    // if(this.currentEvent==="click") this.dx = 0
-    // else this.dx = 1
-    // console.log(this.currentEvent)
 }
 
 class ClickAwayEvent extends Event {
@@ -2282,25 +2381,25 @@ const bind_key_event = (target, customizer) => new ZikoEvent(
     key_details_setter, 
     customizer
 );
-const bind_mouse_event = (target, customizer) => new ZikoEvent(
+const bind_mouse_event = (target, customizer) => new CoordinatesBasedEvent(
     'mouse',
     target,
     EventsMap.Mouse,
-    null,
+    mouse_details_setter,
     customizer
 );
-const bind_pointer_event = (target, customizer) => new ZikoEvent(
+const bind_pointer_event = (target, customizer) => new CoordinatesBasedEvent(
     'ptr',
     target,
     EventsMap.Ptr, 
     ptr_details_setter, 
     customizer
 );
-const bind_touch_event = (target, customizer) => new ZikoEvent(
+const bind_touch_event = (target, customizer) => new CoordinatesBasedEvent(
     'touch',
     target,
     EventsMap.Touch,
-    null,
+    touch_details_setter,
     customizer
 );
 const bind_wheel_event = (target, customizer) => new ZikoEvent(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ziko",
-  "version": "0.50.2",
+  "version": "0.51.0",
   "description": "A versatile JavaScript library offering a rich set of Hyperscript Based UI components, advanced mathematical utilities, interactivity ,animations, client side routing and more ...",
   "keywords": [
     "front-end",

package/src/__helpers__/checkers/index.js

@@ -1 +1,2 @@
 export const is_primitive = value => typeof value !== 'object' && typeof value !== 'function' || value === null;
+export const is_async = fn => fn && fn.constructor && fn.constructor.name === "AsyncFunction";

package/src/events/binders/coordinates-based-event.js

@@ -0,0 +1,25 @@
+import { ZikoEvent } from "../ziko-event.js";
+
+export class CoordinatesBasedEvent extends ZikoEvent{
+    constructor(signature, target = null, Events = [], details_setter, customizer){
+        super(signature, target, Events, details_setter, customizer)
+        Object.assign(this.cache,{
+            useNormalisedCoordinates : false
+        })
+        this.isDown = false;
+        this.isMoving = false;
+        this.dx = 0;
+        this.dy = 0;
+        this.mx = 0;
+        this.my = 0;
+        this.ux = 0;
+        this.uy = 0;
+    }
+    get isDragging(){
+        return this.isDown && this.isMoving
+    }
+    useNormalisedCoordinates(enable = true){
+        this.cache.useNormalisedCoordinates = enable;
+        return this;
+    }
+}

package/src/events/binders/index.js

@@ -2,8 +2,13 @@ import { ZikoEvent } from "../ziko-event.js";
 import { EventsMap } from "../events-map/index.js";
 import {
     ptr_details_setter,
-    key_details_setter
+    key_details_setter,
+    mouse_details_setter,
+    touch_details_setter
 } from '../details-setter/index.js'
+import {
+    CoordinatesBasedEvent
+} from './coordinates-based-event.js'
 import { 
     register_click_away_event,
     register_view_event,
@@ -48,25 +53,25 @@ export const bind_key_event = (target, customizer) => new ZikoEvent(
     key_details_setter, 
     customizer
 );
-export const bind_mouse_event = (target, customizer) => new ZikoEvent(
+export const bind_mouse_event = (target, customizer) => new CoordinatesBasedEvent(
     'mouse',
     target,
     EventsMap.Mouse,
-    null,
+    mouse_details_setter,
     customizer
 );
-export const bind_pointer_event = (target, customizer) => new ZikoEvent(
+export const bind_pointer_event = (target, customizer) => new CoordinatesBasedEvent(
     'ptr',
     target,
     EventsMap.Ptr, 
     ptr_details_setter, 
     customizer
 );
-export const bind_touch_event = (target, customizer) => new ZikoEvent(
+export const bind_touch_event = (target, customizer) => new CoordinatesBasedEvent(
     'touch',
     target,
     EventsMap.Touch,
-    null,
+    touch_details_setter,
     customizer
 );
 export const bind_wheel_event = (target, customizer) => new ZikoEvent(

package/src/events/details-setter/index.js

@@ -1,2 +1,4 @@
 export * from './key.js'
-export * from './pointer.js'
+export * from './pointer.js'
+export * from './mouse.js'
+export * from './touch.js'

package/src/events/details-setter/mouse.js

@@ -0,0 +1,35 @@
+export function mouse_details_setter() {
+    const rect = this.targetElement.getBoundingClientRect();
+    const e = this.event;
+    let x = (e.clientX - rect.left) | 0;
+    let y = (e.clientY - rect.top) | 0;
+
+    if(this.cache.useNormalisedCoordinates){
+        const w = this.targetElement.clientWidth;
+        const h = this.targetElement.clientHeight;
+        x = +((x / w) * 2 - 1).toFixed(8);
+        y = +((y / h) * -2 + 1).toFixed(8);
+    }
+
+    switch (this.currentEvent) {
+
+        case "mousedown":
+            this.dx = x;
+            this.dy = y;
+            this.isDown = true;
+            break;
+
+        case "mousemove":
+            this.mx = x;
+            this.my = y;
+            this.isMoving = true;
+            break;
+
+        case "mouserup":
+            this.ux = x;
+            this.uy = y;
+            this.isDown = false;
+            this.isMoving = false;
+            break;
+    }
+}

package/src/events/details-setter/pointer.js

@@ -1,33 +1,35 @@
-export function ptr_details_setter(){
-    switch(this.currentEvent){
-        case "pointerdown" : {
-            this.dx = parseInt(this.event.offsetX);
-            this.dy = parseInt(this.event.offsetY);
-            this.isDown = true
-        }; break;
-        case "pointermove" : {
-            this.mx = parseInt(this.event.offsetX);
-            this.my = parseInt(this.event.offsetY);
-            this.isMoving = true
-        }; break;
-        case "pointerup" : {
-            this.ux = parseInt(this.event.offsetX);
-            this.uy = parseInt(this.event.offsetY);
+export function ptr_details_setter() {
+    const rect = this.targetElement.getBoundingClientRect();
+    const e = this.event;
+    let x = (e.clientX - rect.left) | 0;
+    let y = (e.clientY - rect.top) | 0;
+
+    if(this.cache.useNormalisedCoordinates){
+        const w = this.targetElement.clientWidth;
+        const h = this.targetElement.clientHeight;
+        x = +((x / w) * 2 - 1).toFixed(8);
+        y = +((y / h) * -2 + 1).toFixed(8);
+    }
+    switch (this.currentEvent) {
+
+        case "pointerdown":
+            this.dx = x;
+            this.dy = y;
+            this.isDown = true;
+            break;
+
+        case "pointermove":
+            this.mx = x;
+            this.my = y;
+            this.isMoving = true;
+            break;
+
+        case "pointerup":
+            this.ux = x;
+            this.uy = y;
             this.isDown = false;
-            console.log(this.target.width)
-            const delta_x=(this.ux-this.dx)/this.target.width;
-            const delta_y=(this.dy-this.uy)/this.target.height;
-            const HORIZONTAL_SWIPPE=(delta_x<0)?"left":(delta_x>0)?"right":"none";
-            const VERTICAL_SWIPPE=(delta_y<0)?"bottom":(delta_y>0)?"top":"none";
-            this.swippe={
-                h:HORIZONTAL_SWIPPE,
-                v:VERTICAL_SWIPPE,
-                delta_x,
-                delta_y
-            }
-        }; break;
+            this.isMoving = false;
+            break;
     }
-    // if(this.currentEvent==="click") this.dx = 0
-    // else this.dx = 1
-    // console.log(this.currentEvent)
-}
+}
+

package/src/events/details-setter/touch.js

@@ -0,0 +1,37 @@
+export function touch_details_setter() {
+    const e = this.event;
+    const touch = e.touches?.[0] || e.changedTouches?.[0];
+
+    if (!touch) return; // should never happen but safe
+
+    const rect = this.targetElement.getBoundingClientRect();
+    let x = touch.clientX - rect.left;
+    let y = touch.clientY - rect.top;
+
+    if(this.cache.useNormalisedCoordinates){
+        const w = this.targetElement.clientWidth;
+        const h = this.targetElement.clientHeight;
+        x = +((x / w) * 2 - 1).toFixed(8);
+        y = +((y / h) * -2 + 1).toFixed(8);
+    }
+
+    switch (this.currentEvent) {
+        case "touchstart":
+            this.dx = x;
+            this.dy = y;
+            this.isDown = true;
+            break;
+
+        case "touchmove":
+            this.mx = x;
+            this.my = y;
+            this.isMoving = true;
+            break;
+
+        case "touchend":
+            this.ux = x;
+            this.uy = y;
+            this.isDown = false;
+            break;
+    }
+}

package/src/router/file-based-router/index.js

@@ -0,0 +1,46 @@
+import { 
+    get_root,
+    normalize_path,
+    routes_matcher,
+    is_dynamic,
+    dynamic_routes_parser
+ } from "../utils/index.js"
+export async function createSPAFileBasedRouter(
+  pages, 
+  target = globalThis?.document?.body
+) {
+  if(!(target instanceof HTMLElement) && target?.element instanceof HTMLElement) target = target?.element;
+  if (!(target instanceof HTMLElement)) {
+    throw new Error("Invalid mount target: must be HTMLElement or UIElement");
+  }
+  let path = decodeURIComponent(globalThis.location.pathname.replace(/\/$/, ''));
+  const routes = Object.keys(pages);
+  const root = get_root(routes);
+
+  const pairs = {};
+  for (const route of routes) {
+    const module = await pages[route]();
+    const modComponent = await module.default;
+    pairs[normalize_path(route, root)] = modComponent;
+  }
+
+  let mask = null;
+  let component = null;
+
+  for (const [routePath, comp] of Object.entries(pairs)) {
+    if (routes_matcher(routePath, `/${path}`)) {
+      mask = routePath;
+      component = comp;
+      break;
+    }
+  }
+
+  if (!mask) return; // no route matched
+
+  const params = is_dynamic(mask) ? dynamic_routes_parser(mask, path) : undefined;
+  const mounted = params ? await component(params) : await component();
+
+  if(mounted instanceof HTMLElement) target.append(mounted);
+  else mounted.mount(target);
+
+}

package/src/router/index.js

@@ -0,0 +1,2 @@
+export * from './file-based-router/index.js'
+export * from './utils/index.js'

package/src/router/utils/dynamic-routes-parser.js

@@ -0,0 +1,76 @@
+export function dynamic_routes_parser(mask, route) {
+  const maskSegments = mask.split("/").filter(Boolean);
+  const routeSegments = route.split("/").filter(Boolean);
+  const params = {};
+  let i = 0, j = 0;
+  while (i < maskSegments.length && j < routeSegments.length) {
+    const maskSegment = maskSegments[i];
+    const routeSegment = routeSegments[j];
+    if (maskSegment.startsWith("[...") && maskSegment.endsWith("]")) {
+      const paramName = maskSegment.slice(4, -1);
+      const remainingMaskSegments = maskSegments.length - i - 1;
+      if (remainingMaskSegments === 0) {
+        params[paramName] = routeSegments.slice(j).join("/");
+        break;
+      }
+      let requiredSegments = 0;
+      for (let k = i + 1; k < maskSegments.length; k++) {
+        if (!maskSegments[k].endsWith("]+")) requiredSegments++;
+      }
+      const remainingRouteSegments = routeSegments.length - j;
+      const segmentsToConsume = remainingRouteSegments - requiredSegments;
+      if (segmentsToConsume >= 1) {
+        params[paramName] = routeSegments
+          .slice(j, j + segmentsToConsume)
+          .join("/");
+        j += segmentsToConsume;
+      } 
+      else return {};
+      i++;
+      continue;
+    }
+    if (maskSegment.startsWith("[") && maskSegment.endsWith("]+")) {
+      const paramName = maskSegment.slice(1, -2);
+      if (routeSegment) {
+        params[paramName] = routeSegment;
+        j++;
+      }
+      i++;
+      continue;
+    }
+    if (maskSegment.startsWith("[") && maskSegment.endsWith("]")) {
+      const paramName = maskSegment.slice(1, -1);
+      params[paramName] = routeSegment;
+    } 
+    else if (maskSegment !== routeSegment) return {};
+    i++;
+    j++;
+  }
+  return params;
+}
+
+
+// console.log("\n=== PARSER TESTS ===");
+// console.log(dynamic_routes_parser("/user/[id]+", "/user"));
+// // 👉 {}
+
+// console.log(dynamic_routes_parser("/user/[id]+", "/user/42"));
+// // 👉 { id: "42" }
+
+// console.log(dynamic_routes_parser("/blog/[...slug]", "/blog/2025/oct/post"));
+// // 👉 { slug: "2025/oct/post" }
+
+// console.log(
+//   dynamic_routes_parser("/product/[category]/[id]+", "/product/electronics"),
+// );
+// // 👉 { category: "electronics" }
+
+// console.log("\n=== FIX TEST ===");
+// console.log(dynamic_routes_parser("/[...slug]/[id]", "/sl1/sl2/9"));
+// // 👉 { slug: "sl1/sl2", id: "9" }
+
+// console.log(dynamic_routes_parser("/[slug]/[...id]", "/sl1/id1/id2"));
+// // 👉 { slug: "sl1", id: "id1/id2" }
+
+// console.log(dynamic_routes_parser("/blog/lang/[lang]/id/[id]", "/blog/lang/en/id/10"));
+// // 👉 { lang: "en", id: "10" }

package/src/router/utils/get-root.js

@@ -0,0 +1,16 @@
+export function get_root(paths) {
+   if (paths.length === 0) return '';
+   const splitPaths = paths.map(path => path.split('/'));
+   const minLength = Math.min(...splitPaths.map(parts => parts.length));
+   let commonParts = [];
+   for (let i = 0; i < minLength; i++) {
+       const part = splitPaths[0][i]; 
+       if (splitPaths.every(parts => parts[i] === part || parts[i].startsWith('['))) {
+           commonParts.push(part);
+       } 
+       else break; 
+       
+   }
+   const root = commonParts.join('/') + (commonParts.length ? '/' : '');
+   return root;
+}

package/src/router/utils/index.js

@@ -0,0 +1,5 @@
+export * from './normalize-path.js'
+export * from './routes-matcher.js'
+export * from './routes-grouper.js'
+export * from './dynamic-routes-parser.js'
+export * from './get-root.js'

package/src/router/utils/normalize-path.js

@@ -0,0 +1,17 @@
+export function normalize_path(inputPath, root = './src/pages', extensions = ['js', 'ts']) {
+    if(root.at(-1)==="/") root = root.slice(0, -1)
+    const normalizedPath = inputPath.replace(/\\/g, '/')
+                                    // .replace(/\[(\w+)\]/g, '$1/:$1');
+    const parts = normalizedPath.split('/');
+    const rootParts = root.split('/');
+    const rootIndex = parts.indexOf(rootParts[rootParts.length - 1]);
+    if (rootIndex !== -1) {
+        const subsequentParts = parts.slice(rootIndex + 1);
+        const lastPart = subsequentParts[subsequentParts.length - 1];
+        const isIndexFile = lastPart === 'index.js' || lastPart === 'index.ts';
+        const hasValidExtension = extensions.some(ext => lastPart === `.${ext}` || lastPart.endsWith(`.${ext}`));
+        if (isIndexFile) return '/' + (subsequentParts.length > 1 ? subsequentParts.slice(0, -1).join('/') : '');
+        if (hasValidExtension) return '/' + subsequentParts.join('/').replace(/\.(js|ts)$/, '');
+    }
+    return '';
+ }

package/src/router/utils/routes-grouper.js

@@ -0,0 +1,22 @@
+export function is_dynamic(path) {
+  const DynamicPattern = /(:\w+|\[\.\.\.\w+\]|\[\w+\]\+?)/;
+  return DynamicPattern.test(path);
+}
+export function routes_grouper(routeMap) {
+  const grouped = {
+    static: {},
+    dynamic: {},
+  };
+  for (const [path, value] of Object.entries(routeMap)) {
+    if (is_dynamic(path)) {
+      const segments = path.split("/").filter(Boolean);
+      const optionalIndex = segments.findIndex(seg => seg.endsWith("]+"));
+      const hasInvalidOptional =
+        optionalIndex !== -1 && optionalIndex !== segments.length - 1;
+      if (hasInvalidOptional) throw new Error(`Invalid optional param position in route: "${path}" — optional parameters can only appear at the end.`);
+      grouped.dynamic[path] = value;
+    } 
+    else grouped.static[path] = value;
+  }
+  return grouped;
+}

package/src/router/utils/routes-matcher.js

@@ -0,0 +1,60 @@
+export function routes_matcher(mask, route) {
+  const maskSegments = mask.split("/").filter(Boolean);
+  const routeSegments = route.split("/").filter(Boolean);
+  let i = 0, j = 0;
+  while (i < maskSegments.length && j < routeSegments.length) {
+    const maskSegment = maskSegments[i];
+    const routeSegment = routeSegments[j];
+    if (maskSegment.startsWith("[...") && maskSegment.endsWith("]")) {
+      const remainingMaskSegments = maskSegments.length - i - 1;
+      if (remainingMaskSegments === 0) return true;
+      // Calculate minimum required route segments for remaining mask
+      let requiredSegments = 0;
+      for (let k = i + 1; k < maskSegments.length; k++) {
+        if (!maskSegments[k].endsWith("]+")) {
+          requiredSegments++;
+        }
+      }
+      const remainingRouteSegments = routeSegments.length - j;
+      if (remainingRouteSegments < requiredSegments) return false;
+      const segmentsToConsume = remainingRouteSegments - requiredSegments;
+      if (segmentsToConsume < 1) return false;
+      j += segmentsToConsume;
+      i++;
+      continue;
+    }
+    if (maskSegment.startsWith("[") && maskSegment.endsWith("]+")) {
+      if (routeSegment) j++;
+      i++;
+      continue;
+    }
+    if (maskSegment.startsWith("[") && maskSegment.endsWith("]")) {
+      i++;
+      j++;
+      continue;
+    }
+    if (maskSegment !== routeSegment) return false;
+    i++;
+    j++;
+  }
+  while (i < maskSegments.length) {
+    const seg = maskSegments[i];
+    if (seg.endsWith("]+")) {
+      i++;
+      continue;
+    }
+    return false;
+  }
+  return i === maskSegments.length && j === routeSegments.length;
+}
+
+
+// // DEMO
+// console.log("=== EXISTING TESTS ===");
+// console.log(routes_matcher("/user/[id]+", "/user")); // true
+// console.log(routes_matcher("/user/[id]+", "/user/42")); // true
+// console.log(routes_matcher("/blog/[...slug]", "/blog/a/b")); // true
+// console.log(routes_matcher("/blog/[id]", "/blog")); // false
+// console.log(routes_matcher("/product/:id", "/product/99")); // true
+
+

package/types/index.d.ts

@@ -1,4 +1,5 @@
 export type * from './math'
 export type * from './time'
+export type * from './router'
 export type * from './hooks'
 export type * from './data'

package/types/router/file-based-router/index.d.ts

@@ -0,0 +1,20 @@
+// createSPAFileBasedRouter.d.ts
+
+import { UIElement } from '../../../src/ui/constructors/UIElement.js'
+
+/**
+ * Creates a SPA (Single Page Application) file-based router.
+ * Automatically loads and mounts the component corresponding to the current path.
+ * Supports dynamic routes and parameter extraction.
+ *
+ * @param pages - An object mapping route paths to async module functions that return a component.
+ *                Example: { "/user/[id]": () => import("./pages/user/[id].js") }
+ * @param target - Optional DOM element to mount the component. Defaults to `document.body`.
+ */
+export function createSPAFileBasedRouter(
+  pages: Record<
+    string, 
+    () => Promise<{ default: (param? : Record<string, string>) => UIElement }>
+  >,
+  target?: HTMLElement | UIElement
+): Promise<void>;

package/types/router/index.d.ts

@@ -0,0 +1,2 @@
+export type * from './file-based-router'
+export type * from './utils'

package/types/router/utils/dynamic-routes-parser.d.ts

@@ -0,0 +1,14 @@
+// dynamic_routes_parser.d.ts
+
+/**
+ * Parses a route according to a dynamic mask and returns extracted parameters.
+ *
+ * @param mask - The dynamic route mask (e.g., "/user/[id]+", "/blog/[...slug]").
+ * @param route - The actual route to parse (e.g., "/user/42", "/blog/2025/oct/post").
+ * @returns An object mapping parameter names to their corresponding values.
+ *          Returns an empty object if the route does not match the mask.
+ */
+export declare function dynamic_routes_parser(
+  mask: string,
+  route: string
+): Record<string, string>;

package/types/router/utils/get-root.d.ts

@@ -0,0 +1,11 @@
+// get_root.d.ts
+
+/**
+ * Finds the common root path among an array of paths.
+ * Dynamic segments (e.g., `[id]`) are considered as matching any segment.
+ *
+ * @param paths - An array of route paths (e.g., ["/user/42", "/user/99"]).
+ * @returns The common root path as a string (e.g., "/user/").
+ *          Returns an empty string if no common root exists.
+ */
+export declare function get_root(paths: string[]): string;

package/types/router/utils/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './dynamic-routes-parser.d.ts'
+export type * from './routes-matcher.d.ts'
+export type * from './get-root.d.ts'
+export type * from './routes-grouper.d.ts'
+export type * from './normalize-path.d.ts'

package/types/router/utils/normalize-path.d.ts

@@ -0,0 +1,15 @@
+// normalize_path.d.ts
+
+/**
+ * Normalizes a file path into a route path.
+ *
+ * @param inputPath - The file path to normalize (e.g., "./src/pages/user/[id].ts").
+ * @param root - The root directory to consider as the base (default: "./src/pages").
+ * @param extensions - Array of valid file extensions (default: ["js", "ts"]).
+ * @returns A normalized route path (e.g., "/user/[id]") or an empty string if it cannot be normalized.
+ */
+export declare function normalize_path(
+  inputPath: string,
+  root?: string,
+  extensions?: string[]
+): string;

package/types/router/utils/routes-grouper.d.ts

@@ -0,0 +1,29 @@
+// routes_utils.d.ts
+
+/**
+ * Checks if a route path is dynamic.
+ * Dynamic segments include:
+ *   - Parameters like "[id]"
+ *   - Catch-all segments like "[...slug]"
+ *   - Optional segments like "[id]+"
+ *
+ * @param path - The route path to check.
+ * @returns `true` if the path is dynamic, otherwise `false`.
+ */
+export function is_dynamic(path: string): boolean;
+
+/**
+ * Groups routes into static and dynamic categories.
+ * Throws an error if an optional parameter appears anywhere but the end of the path.
+ *
+ * @param routeMap - An object mapping route paths to their handlers/values.
+ * @returns An object with two properties:
+ *   - `static`: Routes with no dynamic segments.
+ *   - `dynamic`: Routes with dynamic segments.
+ */
+export function routes_grouper<T>(
+  routeMap: Record<string, T>
+): {
+  static: Record<string, T>;
+  dynamic: Record<string, T>;
+};

package/types/router/utils/routes-matcher.d.ts

@@ -0,0 +1 @@
+export declare function routes_matcher(mask: string, route: string): boolean;