@inglorious/web 2.3.0 → 2.5.0

package/README.md

@@ -441,6 +441,43 @@ api.notify("navigate", "/users/456")
 
 // Or navigate back in history
 api.notify("navigate", -1)
+
+// With options
+api.notify("navigate", {
+  to: "/users/456",
+  replace: true, // Replace current history entry
+  force: true, // Force navigation even if path is identical
+})
+```
+
+### 4. Lazy Loading Routes
+
+You can improve performance by lazy-loading routes. Instead of a string, provide a function that returns a dynamic import.
+
+**Note:** The imported module must use a named export for the entity type (not `export default`), so the router can register it with a unique name in the store.
+
+```javascript
+// store.js
+const entities = {
+  router: {
+    type: "router",
+    routes: {
+      "/": "homePage",
+      // Lazy load: returns a Promise resolving to a module
+      "/admin": () => import("./pages/admin.js"),
+    },
+  },
+}
+```
+
+```javascript
+// pages/admin.js
+import { html } from "@inglorious/web"
+
+// Must be a named export matching the type name you want to use
+export const adminPage = {
+  render: () => html`<h1>Admin Area</h1>`,
+}
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "A new web framework that leverages the power of the Inglorious Store combined with the performance and simplicity of lit-html.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -38,7 +38,7 @@
   },
   "dependencies": {
     "lit-html": "^3.3.1",
-    "@inglorious/store": "7.1.3",
+    "@inglorious/store": "7.1.4",
     "@inglorious/utils": "3.7.0"
   },
   "devDependencies": {

package/src/mount.js

@@ -11,19 +11,20 @@ export function mount(store, renderFn, element) {
   const api = { ...store._api }
   api.render = createRender(api)
 
-  let renderScheduled = false
+  // let renderScheduled = false
 
-  const scheduleRender = () => {
-    if (!renderScheduled) {
-      renderScheduled = true
-      requestAnimationFrame(() => {
-        renderScheduled = false
-        render(renderFn(api), element)
-      })
-    }
-  }
+  // const scheduleRender = () => {
+  //   if (!renderScheduled) {
+  //     renderScheduled = true
+  //     requestAnimationFrame(() => {
+  //       renderScheduled = false
+  //     })
+  //     render(renderFn(api), element)
+  //   }
+  // }
 
-  const unsubscribe = store.subscribe(scheduleRender)
+  // const unsubscribe = store.subscribe(scheduleRender)
+  const unsubscribe = store.subscribe(() => render(renderFn(api), element))
   store.notify("init")
 
   return unsubscribe

package/src/router.js

@@ -1,71 +1,58 @@
-const SKIP_FULL_MATCH_GROUP = 1 // .match() result at index 0 is the full string
-const REMOVE_COLON_PREFIX = 1
-
 /**
- * @typedef {Object} RouterEntity
- * @property {string} id - The unique identifier for the router entity.
- * @property {Object.<string, string>} routes - A map of URL patterns to entity types.
- * @property {string} [path] - The current URL path.
- * @property {string} [route] - The entity type for the current route.
- * @property {Object.<string, string>} [params] - The parameters extracted from the URL.
- * @property {Object.<string, string>} [query] - The query parameters from the URL.
- * @property {string} [hash] - The URL hash.
+ * @typedef {import("../types/router").RouterType} RouterType
+ * @typedef {import("../types/router").RouterEntity} RouterEntity
+ * @typedef {import("../types/router").Api} Api
  */
 
+const SKIP_FULL_MATCH_GROUP = 1 // .match() result at index 0 is the full string
+const REMOVE_COLON_PREFIX = 1
+
 /**
- * A client-side router type for an entity-based system. It handles URL changes,
- * link interception, and history management (pushState, replaceState, popstate).
- * @type {import('@inglorious/engine/types/type.js').Type}
+ * Client-side router for entity-based systems. Handles URL changes, link interception, and browser history management.
+ * @type {RouterType}
  */
 export const router = {
   /**
-   * Initializes the router. It handles the initial route, sets up a `popstate`
-   * listener for browser navigation, and intercepts clicks on local `<a>` links.
+   * Initializes the router entity.
+   * Sets up the initial route and event listeners for navigation.
    * @param {RouterEntity} entity - The router entity.
-   * @param {*} payload - The message payload (unused).
-   * @param {import('../types/router.js').RouterApi} api - The router API.
+   * @param {void} payload - Unused payload.
+   * @param {Api} api - The application API.
    */
   init(entity, payload, api) {
     // Handle initial route
-    const initialPath = window.location.pathname
+    const { pathname, search } = window.location
+    const initialPath = pathname + search
     const route = findRoute(entity.routes, initialPath)
+    const entityId = entity.id
 
     if (route) {
-      entity.path = route.path
-      entity.route = route.entityType
-      entity.params = route.params
-
-      const query = Object.fromEntries(
-        new URLSearchParams(window.location.search),
-      )
-      entity.query = query
-      entity.hash = window.location.hash
+      api.notify(`#${entityId}:navigate`, {
+        to: initialPath,
+        params: route.params,
+        replace: true,
+      })
     }
 
-    const id = entity.id
     // Listen for browser back/forward
     window.addEventListener("popstate", () => {
-      const path = window.location.pathname
-      const { routes } = api.getEntity(id)
+      const path = window.location.pathname + window.location.search
+      const { routes } = api.getEntity(entityId)
       const route = findRoute(routes, path)
 
       if (route) {
-        api.notify("routeSync", {
-          path: route.path,
+        api.notify(`#${entityId}:routeSync`, {
           entityType: route.entityType,
+          path,
           params: route.params,
-          query: Object.fromEntries(
-            new URLSearchParams(window.location.search),
-          ),
-          hash: window.location.hash,
         })
       }
     })
 
     // Intercept link clicks
-    document.addEventListener("click", (e) => {
+    document.addEventListener("click", (event) => {
       // Find the closest <a> tag (handles clicks on children)
-      const link = e.target.closest("a")
+      const link = event.target.closest("a")
 
       if (!link) return
 
@@ -84,7 +71,7 @@ export const router = {
       if (!["http:", "https:"].includes(link.protocol)) return
 
       // Prevent default and use router
-      e.preventDefault()
+      event.preventDefault()
 
       const path = link.pathname + link.search + link.hash
       api.notify("navigate", path)
@@ -92,22 +79,16 @@ export const router = {
   },
 
   /**
-   * Navigates to a new route, updating the browser's history and the router entity state.
+   * Handles navigation to a new route.
    * @param {RouterEntity} entity - The router entity.
-   * @param {string|number|import('../types/router.js').NavigatePayload} payload - The navigation payload.
-   * Can be a path string, a number for `history.go()`, or an object with navigation options.
-   * @param {string|number} payload.to - The destination path or history offset.
-   * @param {Object} [payload.params] - Route parameters to build the path from a pattern.
-   * @param {boolean} [payload.replace] - If true, uses `history.replaceState` instead of `pushState`.
-   * @param {Object} [payload.state] - Additional state to store in the browser's history.
-   * @param {import('../types/router.js').RouterApi} api - The router API.
+   * @param {string|number|{to: string, params?: object, replace?: boolean, state?: object}} payload - The navigation target or options.
+   * @param {Api} api - The application API.
    */
-  navigate(entity, payload, api) {
-    if (["number", "string"].includes(typeof payload)) {
-      payload = { to: payload }
-    }
-
-    const { to, params, replace, state = {} } = payload
+  async navigate(entity, payload, api) {
+    const options = ["number", "string"].includes(typeof payload)
+      ? { to: payload }
+      : payload
+    const { to, params, replace, force, state = {} } = options
 
     // Numeric navigation (back/forward)
     if (typeof to === "number") {
@@ -133,61 +114,107 @@ export const router = {
       return
     }
 
-    // Prevent navigation if the full path (including query/hash) is identical.
-    const currentFullPath =
-      entity.path + window.location.search + window.location.hash
-    if (path === currentFullPath) {
-      return
+    if (!force) {
+      // Prevent navigation if the full path (including query/hash) is identical.
+      const currentFullPath =
+        entity.path + window.location.search + window.location.hash
+      if (path === currentFullPath) {
+        return
+      }
     }
 
-    // Parse query string
-    const [pathname, search] = path.split("?")
-    const query = search ? Object.fromEntries(new URLSearchParams(search)) : {}
-
-    // Update entity with routing info
-    entity.path = pathname
-    entity.route = route.entityType
-    entity.params = route.params
-    entity.query = query
-    entity.hash = window.location.hash
-
-    // Prepare history state
-    const historyState = {
-      ...state,
-      route: route.entityType,
-      params: route.params,
-      query,
-      path: pathname,
+    // Asynchronous navigation
+    if (typeof route.entityType === "function") {
+      entity.loading = true
+      entity.error = null
+      const entityId = entity.id
+
+      try {
+        const module = await route.entityType()
+        api.notify(`#${entityId}:loadSuccess`, {
+          module,
+          route,
+          path,
+          replace,
+          state,
+        })
+      } catch (error) {
+        api.notify(`#${entityId}:loadError`, { error, path })
+      }
+
+      return
     }
 
-    // Navigate
-    const method = replace ? "replaceState" : "pushState"
-    history[method](historyState, "", path)
+    // Synchronous navigation
+
+    doNavigate(
+      entity,
+      {
+        entityType: route.entityType,
+        path,
+        params: route.params,
+        replace,
+        state,
+      },
+      api,
+    )
+  },
+
+  /**
+   * Handles the successful loading of a lazy route module.
+   * @param {RouterEntity} entity - The router entity.
+   * @param {{module: object, route: object, path: string, replace: boolean, state: object}} payload - The success payload.
+   * @param {Api} api - The application API.
+   */
+  loadSuccess(entity, payload, api) {
+    const { module, route, path, replace, state } = payload
+
+    const [[typeName, type]] = Object.entries(module)
 
-    api.notify("routeChange", historyState)
+    api.notify("morph", { name: typeName, type })
+
+    entity.routes[route.pattern] = typeName
+
+    // Complete the navigation
+    entity.loading = false
+
+    doNavigate(
+      entity,
+      { entityType: typeName, path, params: route.params, replace, state },
+      api,
+    )
+  },
+
+  /**
+   * Handles errors during lazy route loading.
+   * @param {RouterEntity} entity - The router entity.
+   * @param {{error: Error, path: string}} payload - The error payload.
+   */
+  loadError(entity, payload) {
+    const { error, path } = payload
+    console.error(`Failed to load route ${path}:`, error)
+    entity.path = path
+    entity.loading = false
+    entity.error = error
   },
 
   /**
-   * Synchronizes the router entity's state with data from a routing event,
-   * typically triggered by a `popstate` event (browser back/forward).
-   * @param {RouterEntity} entity - The router entity to update.
-   * @param {import('../types/router.js').RouteSyncPayload} payload - The new route state.
+   * Synchronizes the router state with the browser's history (e.g., on popstate).
+   * @param {RouterEntity} entity - The router entity.
+   * @param {{entityType: string, path: string, params: object}} payload - The sync payload.
    */
   routeSync(entity, payload) {
-    entity.path = payload.path
-    entity.route = payload.entityType
-    entity.params = payload.params
-    entity.query = payload.query
-    entity.hash = payload.hash
+    updateRouter(entity, payload)
   },
 }
 
 /**
  * Builds a URL path by substituting parameters into a route pattern.
- * Example: `buildPath("/users/:userId", { userId: "123" })` returns `"/users/123"`.
  * @param {string} pattern - The route pattern (e.g., "/users/:userId").
- * @param {Object.<string, string>} [params={}] - The parameters to substitute.
+ * @param {Record<string, string>} [params={}] - The parameters to substitute.
  * @returns {string} The constructed path.
+ * @example
+ * buildPath("/users/:userId", { userId: "123" }) // returns "/users/123"
  */
 function buildPath(pattern, params = {}) {
   let path = pattern
@@ -200,9 +227,9 @@ function buildPath(pattern, params = {}) {
 /**
  * Finds a matching route configuration for a given URL path.
  * It supports parameterized routes and a fallback "*" route.
- * @param {Object.<string, string>} routes - The routes configuration map.
+ * @param {Record<string, string>} routes - The routes configuration map.
  * @param {string} path - The URL path to match.
- * @returns {{pattern: string, entityType: string, params: Object, path: string}|null}
+ * @returns {{pattern: string, entityType: string, params: Record<string, string>, path: string}|null}
  * The matched route object or null if no match is found.
  */
 function findRoute(routes, path) {
@@ -226,7 +253,7 @@ function findRoute(routes, path) {
  * Matches a URL path against a route pattern and extracts any parameters.
  * @param {string} pattern - The route pattern (e.g., "/users/:userId").
  * @param {string} path - The URL path to match (e.g., "/users/123").
- * @returns {Object.<string, string>|null} An object of extracted parameters,
+ * @returns {Record<string, string>|null} An object of extracted parameters,
  * or null if the path does not match the pattern.
  */
 function matchRoute(pattern, path) {
@@ -246,9 +273,10 @@ function matchRoute(pattern, path) {
 
 /**
  * Parses a route pattern and extracts the names of its parameters.
- * Example: `getParamNames("/users/:userId/posts/:postId")` returns `["userId", "postId"]`.
  * @param {string} pattern - The route pattern.
  * @returns {string[]} An array of parameter names.
+ * @example
+ * getParamNames("/users/:userId/posts/:postId") // returns ["userId", "postId"]
  */
 function getParamNames(pattern) {
   const matches = pattern.match(/:(\w+)/g)
@@ -266,3 +294,52 @@ function patternToRegex(pattern) {
     .replace(/:(\w+)/g, "([^\\/]+)")
   return new RegExp(`^${regexPattern}$`)
 }
+
+/**
+ * Performs the actual navigation by updating entity state and browser history.
+ * @param {RouterEntity} entity - The router entity.
+ * @param {object} options - Navigation options.
+ * @param {string} options.entityType - The type of the entity to render.
+ * @param {string} options.path - The full path.
+ * @param {object} options.params - The route parameters.
+ * @param {boolean} [options.replace] - Whether to replace the current history entry.
+ * @param {object} [options.state] - Additional state to save in history.
+ * @param {Api} api - The application API.
+ */
+function doNavigate(entity, { entityType, path, params, replace, state }, api) {
+  updateRouter(entity, { entityType, path, params })
+
+  // Prepare history state
+  const historyState = {
+    ...state,
+    route: entity.route,
+    params: entity.params,
+    query: entity.query,
+    path: entity.path,
+  }
+
+  // Navigate
+  const method = replace ? "replaceState" : "pushState"
+  history[method](historyState, "", path)
+
+  api.notify("routeChange", historyState)
+}
+
+/**
+ * Updates the router entity's internal state.
+ * @param {RouterEntity} entity - The router entity.
+ * @param {object} options - The update options.
+ * @param {string} options.entityType - The matched entity type.
+ * @param {string} options.path - The full path.
+ * @param {object} options.params - The extracted parameters.
+ */
+function updateRouter(entity, { entityType, path, params }) {
+  const [pathname, search] = path.split("?")
+  const query = search ? Object.fromEntries(new URLSearchParams(search)) : {}
+
+  entity.path = pathname
+  entity.route = entityType
+  entity.params = params
+  entity.query = query
+  entity.hash = window.location.hash
+}

package/src/router.test.js

@@ -54,11 +54,11 @@ describe("router", () => {
 
       router.init(entity, {}, api)
 
-      expect(entity.path).toBe("/users/123")
-      expect(entity.route).toBe("userPage")
-      expect(entity.params).toEqual({ id: "123" })
-      expect(entity.query).toEqual({ sort: "asc" })
-      expect(entity.hash).toBe("#details")
+      expect(api.notify).toHaveBeenCalledWith("#router:navigate", {
+        to: "/users/123?sort=asc",
+        params: { id: "123" },
+        replace: true,
+      })
     })
 
     it("should set up a popstate listener", () => {
@@ -138,21 +138,79 @@ describe("router", () => {
         expect.any(Object),
       )
     })
+
+    it("should navigate if the path is identical but force is true", () => {
+      entity.path = "/users"
+      vi.spyOn(window, "location", "get").mockReturnValue({
+        pathname: "/users",
+        search: "",
+        hash: "",
+      })
+
+      router.navigate(entity, { to: "/users", force: true }, api)
+
+      expect(history.pushState).toHaveBeenCalled()
+      expect(api.notify).toHaveBeenCalledWith("routeChange", expect.any(Object))
+    })
   })
 
   describe("routeSync()", () => {
     it("should update the entity state from a payload", () => {
       const payload = {
-        path: "/new",
+        path: "/new?a=1",
         entityType: "newPage",
         params: {},
-        query: { a: "1" },
-        hash: "#section",
       }
+
+      vi.spyOn(window, "location", "get").mockReturnValue({ hash: "#section" })
+
       router.routeSync(entity, payload)
+
       expect(entity.path).toBe("/new")
       expect(entity.route).toBe("newPage")
       expect(entity.query).toEqual({ a: "1" })
+      expect(entity.hash).toBe("#section")
+    })
+  })
+
+  describe("loadSuccess()", () => {
+    it("should handle lazy loaded modules", () => {
+      const module = { myPage: { render: () => {} } }
+      const route = { pattern: "/lazy", params: {} }
+      const payload = {
+        module,
+        route,
+        path: "/lazy",
+        replace: false,
+        state: {},
+      }
+
+      router.loadSuccess(entity, payload, api)
+
+      expect(api.notify).toHaveBeenCalledWith("morph", {
+        name: "myPage",
+        type: module.myPage,
+      })
+      expect(entity.routes["/lazy"]).toBe("myPage")
+      expect(entity.loading).toBe(false)
+      expect(entity.route).toBe("myPage")
+      expect(history.pushState).toHaveBeenCalled()
+    })
+  })
+
+  describe("loadError()", () => {
+    it("should handle load errors", () => {
+      const error = new Error("Failed")
+      const payload = { error, path: "/lazy" }
+      const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {})
+
+      router.loadError(entity, payload)
+
+      expect(entity.path).toBe("/lazy")
+      expect(entity.loading).toBe(false)
+      expect(entity.error).toBe(error)
+
+      consoleSpy.mockRestore()
     })
   })
 })

package/types/router.d.ts

@@ -66,46 +66,65 @@ export interface RouteSyncPayload {
 }
 
 /**
- * The API object provided to the router for interacting with the host system.
+ * API from @inglorious/store
  */
-export interface RouterApi {
-  /** Retrieves an entity by its ID. */
-  getEntity(id: string | number): { routes: RoutesConfig }
-  /** Dispatches an event to the system. */
-  notify(eventName: "routeSync", payload: RouteSyncPayload): void
-  notify(eventName: "navigate", payload: string): void
-}
+export type { Api as StoreApi } from "@inglorious/store"
 
 /**
- * The router implementation.
+ * Client-side router for entity-based systems. Handles URL changes, link interception, and browser history management.
  */
-export declare const router: {
+export interface RouterType {
   /**
    * Initializes the router, sets up a popstate listener to handle browser navigation,
    * and intercepts clicks on local links.
    * @param entity The router state entity.
    * @param payload The initialization payload (currently unused).
-   * @param api The API for interacting with the host system.
+   * @param api The store API for interacting with the system.
    */
-  init(entity: RouterEntity, payload: any, api: RouterApi): void
+  init(entity: RouterEntity, payload: any, api: StoreApi): void
 
   /**
-   * Navigates to a new route programmatically.
-   * @param entity The router state entity.
-   * @param payload The navigation details.
-   * @param api The API for interacting with the host system.
+   * Navigates to a new route, updating the browser's history and the router entity state.
+   * @param {RouterEntity} entity - The router entity.
+   * @param {string|number|NavigatePayload} payload - The navigation payload.
+   * Can be a path string, a number for `history.go()`, or an object with navigation options.
+   * @param {string|number} payload.to - The destination path or history offset.
+   * @param {RouteParams} [payload.params] - Route parameters to build the path from a pattern.
+   * @param {boolean} [payload.replace] - If true, uses `history.replaceState` instead of `pushState`.
+   * @param {Record<string, any>} [payload.state] - Additional state to store in the browser's history.
+   * @param {StoreApi} api - The store API.
    */
   navigate(
     entity: RouterEntity,
     payload: string | number | NavigatePayload,
-    api: RouterApi,
+    api: StoreApi,
   ): void
 
   /**
-   * Synchronizes the router entity's state with the provided route information.
-   * Typically called in response to a `popstate` event.
-   * @param entity The router state entity.
-   * @param payload The new route information.
+   * Synchronizes the router entity's state with data from a routing event,
+   * typically triggered by a `popstate` event (browser back/forward).
+   * @param {RouterEntity} entity - The router entity to update.
+   * @param {RouteSyncPayload} payload - The new route state.
+   * @param {StoreApi} api - The store API.
+   */
+  routeSync(
+    entity: RouterEntity,
+    payload: RouteSyncPayload,
+    api: StoreApi,
+  ): void
+
+  /**
+   * Handles successful async route loading.
+   * @param {RouterEntity} entity - The router entity to update.
+   * @param {Object} payload - The load success payload.
+   * @param {StoreApi} api - The store API.
+   */
+  loadSuccess(entity: RouterEntity, payload: any, api: StoreApi): void
+
+  /**
+   * Handles async route loading errors.
+   * @param {RouterEntity} entity - The router entity.
+   * @param {Object} payload - The error payload.
    */
-  routeSync(entity: RouterEntity, payload: RouteSyncPayload): void
+  loadError(entity: RouterEntity, payload: any): void
 }