@inglorious/web 3.0.1 → 4.0.1

package/README.md

@@ -367,12 +367,12 @@ No additional configuration is needed.
 
 ### 1. Setup the Router
 
-To enable the router, add it to your store's types and create a `router` entity. The entity's `routes` property maps URL patterns to the entity types that represent your pages.
+To enable the router, add it to your store's types and create a `router` entity. Register route patterns using the router module helpers (`setRoutes`, `addRoute`) — routes are configured at module level and not stored on the router entity itself.
 
 ```javascript
 // store.js
 import { createStore, html } from "@inglorious/web"
-import { router } from "@inglorious/web/router"
+import { router, setRoutes } from "@inglorious/web/router"
 
 const types = {
   // 1. Add the router type to your store's types
@@ -395,14 +395,9 @@ const types = {
 }
 
 const entities = {
-  // 3. Create the router entity
+  // 3. Create the router entity (no `routes` here)
   router: {
     type: "router",
-    routes: {
-      "/": "homePage",
-      "/users/:id": "userPage",
-      "*": "notFoundPage", // Fallback for unmatched routes
-    },
   },
   userPage: {
     type: "userPage",
@@ -411,6 +406,13 @@ const entities = {
 }
 
 export const store = createStore({ types, entities })
+
+// Register routes at module level
+setRoutes({
+  "/": "homePage",
+  "/users/:id": "userPage",
+  "*": "notFoundPage",
+})
 ```
 
 ### 2. Render the Current Route
@@ -456,22 +458,23 @@ api.notify("navigate", {
 
 ### 4. Lazy Loading Routes
 
-You can improve performance by lazy-loading routes. Instead of a string, provide a function that returns a dynamic import.
+You can improve performance by lazy-loading routes. Use a loader function that returns a dynamic import when registering the route via `setRoutes`.
 
 **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"),
-    },
-  },
+  router: { type: "router" },
 }
+
+export const store = createStore({ types, entities })
+
+setRoutes({
+  "/": "homePage",
+  // Lazy load: returns a Promise resolving to a module
+  "/admin": () => import("./pages/admin.js"),
+})
 ```
 
 ```javascript
@@ -538,22 +541,18 @@ const types = {
 }
 
 const entities = {
-  router: {
-    type: "router",
-    routes: {
-      "/login": "loginPage",
-      "/admin": "adminPage",
-    },
-  },
-  adminPage: {
-    type: "adminPage",
-  },
-  loginPage: {
-    type: "loginPage",
-  },
+  router: { type: "router" },
+  adminPage: { type: "adminPage" },
+  loginPage: { type: "loginPage" },
 }
 
 export const store = createStore({ types, entities })
+
+// Register routes via the router module API
+setRoutes({
+  "/login": "loginPage",
+  "/admin": "adminPage",
+})
 ```
 
 #### How Type Composition Works

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/web",
-  "version": "3.0.1",
+  "version": "4.0.1",
   "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",
@@ -53,8 +53,8 @@
   },
   "files": [
     "src",
-    "!src/**/*.test.js",
-    "types"
+    "types",
+    "!src/**/*.test.js"
   ],
   "publishConfig": {
     "access": "public"
@@ -63,8 +63,9 @@
     "**/*.css"
   ],
   "dependencies": {
+    "@lit-labs/ssr-client": "^1.1.8",
     "lit-html": "^3.3.1",
-    "@inglorious/store": "8.0.1",
+    "@inglorious/store": "9.0.0",
     "@inglorious/utils": "3.7.1"
   },
   "devDependencies": {

package/src/mount.js

@@ -1,3 +1,4 @@
+import { hydrate } from "@lit-labs/ssr-client"
 import { html, render } from "lit-html"
 
 /**
@@ -11,20 +12,19 @@ export function mount(store, renderFn, element) {
   const api = { ...store._api }
   api.render = createRender(api)
 
-  // let renderScheduled = false
+  let shouldHydrate = element.hasChildNodes()
 
-  // const scheduleRender = () => {
-  //   if (!renderScheduled) {
-  //     renderScheduled = true
-  //     requestAnimationFrame(() => {
-  //       renderScheduled = false
-  //     })
-  //     render(renderFn(api), element)
-  //   }
-  // }
+  const unsubscribe = store.subscribe(() => {
+    const template = renderFn(api)
+
+    if (shouldHydrate) {
+      hydrate(template, element)
+      shouldHydrate = false
+    } else {
+      render(template, element)
+    }
+  })
 
-  // const unsubscribe = store.subscribe(scheduleRender)
-  const unsubscribe = store.subscribe(() => render(renderFn(api), element))
   store.notify("init")
 
   return unsubscribe

package/src/router/index.js

@@ -7,6 +7,18 @@
 const SKIP_FULL_MATCH_GROUP = 1 // .match() result at index 0 is the full string
 const REMOVE_COLON_PREFIX = 1
 
+/**
+ * Route configuration map. Keys are route patterns (e.g. `/users/:id`) and
+ * values are either a string type name or a loader function that returns a
+ * module exporting a type.
+ * @type {Record<string, string|function>}
+ */
+const routeConfig = {}
+
+/**
+ * Guard to ensure global listeners are only attached once.
+ * @type {boolean}
+ */
 let areListenersInitialized = false
 
 /**
@@ -25,7 +37,7 @@ export const router = {
     // Handle initial route
     const { pathname, search } = window.location
     const initialPath = pathname + search
-    const route = findRoute(entity.routes, initialPath)
+    const route = findRoute(routeConfig, initialPath)
     const entityId = entity.id
 
     if (route) {
@@ -40,19 +52,9 @@ export const router = {
     areListenersInitialized = true
 
     // Listen for browser back/forward
-    window.addEventListener("popstate", () => {
-      const path = window.location.pathname + window.location.search
-      const { routes } = api.getEntity(entityId)
-      const route = findRoute(routes, path)
-
-      if (route) {
-        api.notify(`#${entityId}:routeSync`, {
-          entityType: route.entityType,
-          path,
-          params: route.params,
-        })
-      }
-    })
+    window.addEventListener("popstate", () =>
+      api.notify(`#${entityId}:popstate`, payload),
+    )
 
     // Intercept link clicks
     document.addEventListener("click", (event) => {
@@ -79,20 +81,42 @@ export const router = {
       event.preventDefault()
 
       const path = link.pathname + link.search + link.hash
-      api.notify("navigate", path)
+      api.notify(`#${entityId}:navigate`, path)
     })
   },
 
-  create(entity) {
-    entity.routes ??= {}
-  },
+  /**
+   * Handles browser `popstate` events.
+   * Attempts to match the current location to a route and updates the router
+   * entity state. If the matched route is lazy (a loader function) it will
+   * attempt to load the module first.
+   * @param {RouterEntity} entity
+   * @param {Object} payload
+   * @param {Api} api
+   */
+  async popstate(entity, payload, api) {
+    const path = window.location.pathname + window.location.search
+    const route = findRoute(routeConfig, path)
+    const entityId = entity.id
 
-  routeAdd(entity, route) {
-    entity.routes[route.path] = route.entityType
-  },
+    if (route) {
+      if (typeof route.entityType === "function") {
+        entity.isLoading = true
+        entity.error = null
+
+        try {
+          const module = await route.entityType()
+          api.notify(`#${entityId}:routeLoadSuccess`, { module, route })
+          api.notify(`#${entityId}:popstate`, payload)
+        } catch (error) {
+          api.notify(`#${entityId}:routeLoadError`, { error, path })
+        }
+
+        return
+      }
 
-  routeRemove(entity, path) {
-    delete [entity.routes[path]]
+      updateRouter(entity, route)
+    }
   },
 
   /**
@@ -122,9 +146,10 @@ export const router = {
     }
 
     // If "to" is already a final path (like "/users/1"), use it directly
-    // The router will match it against patterns in entity.routes
+    // The router will match it against patterns in routeConfig
 
-    const route = findRoute(entity.routes, path)
+    const route = findRoute(routeConfig, path)
+    const entityId = entity.id
 
     if (!route) {
       console.warn(`No route matches path: ${path}`)
@@ -142,64 +167,57 @@ export const router = {
 
     // Asynchronous navigation
     if (typeof route.entityType === "function") {
-      entity.loading = true
+      entity.isLoading = true
       entity.error = null
-      const entityId = entity.id
 
       try {
         const module = await route.entityType()
-        api.notify(`#${entityId}:loadSuccess`, {
-          module,
-          route,
-          path,
-          replace,
-          state,
-        })
+        api.notify(`#${entityId}:routeLoadSuccess`, { module, route })
+        api.notify(`#${entityId}:navigate`, payload)
       } catch (error) {
-        api.notify(`#${entityId}:loadError`, { error, path })
+        api.notify(`#${entityId}:routeLoadError`, { error, path })
       }
 
       return
     }
 
-    // Synchronous navigation
+    updateRouter(entity, route)
 
-    doNavigate(
-      entity,
-      {
-        entityType: route.entityType,
-        path,
-        params: route.params,
-        replace,
-        state,
-      },
-      api,
-    )
+    // 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)
   },
 
   /**
-   * 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.
+   * Handles successful loading of a lazily-loaded route module.
+   * Registers the loaded type in the runtime type registry via `api.setType`
+   * and updates the `routeConfig` entry for the pattern.
+   * @param {RouterEntity} entity
+   * @param {{module: object, route: {pattern: string, entityType: string}}} payload
+   * @param {Api} api
    */
-  loadSuccess(entity, payload, api) {
-    const { module, route, path, replace, state } = payload
-
-    const [[typeName, type]] = Object.entries(module)
-
-    api.notify("morph", { name: typeName, type })
+  routeLoadSuccess(entity, payload, api) {
+    const { module, route } = payload
 
-    entity.routes[route.pattern] = typeName
+    const [typeName, type] = Object.entries(module).find(
+      ([, type]) => type?.render,
+    )
 
-    // Complete the navigation
-    entity.loading = false
+    api.setType(typeName, type)
+    routeConfig[route.pattern] = typeName
 
-    doNavigate(
-      entity,
-      { entityType: typeName, path, params: route.params, replace, state },
-      api,
-    )
+    entity.isLoading = false
   },
 
   /**
@@ -207,22 +225,56 @@ export const router = {
    * @param {RouterEntity} entity - The router entity.
    * @param {{error: Error, path: string}} payload - The error payload.
    */
-  loadError(entity, payload) {
+  routeLoadError(entity, payload) {
     const { error, path } = payload
     console.error(`Failed to load route ${path}:`, error)
     entity.path = path
-    entity.loading = false
+    entity.isLoading = false
     entity.error = error
   },
+}
 
-  /**
-   * 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) {
-    updateRouter(entity, payload)
-  },
+/**
+ * Retrieves the current route configuration.
+ * @returns {Record<string, string|function>} The current route configuration.
+ */
+export function getRoutes() {
+  return routeConfig
+}
+
+/**
+ * Retrieves a single route configuration given its path.
+ * @param {string} path - The path of the route to retrieve.
+ * @returns {string|function|undefined} The route configuration or undefined if not found.
+ */
+export function getRoute(path) {
+  return routeConfig[path]
+}
+
+/**
+ * Sets or updates routes in the route configuration.
+ * Can be used both during initialization and at any point to add or update routes dynamically.
+ * @param {Record<string, string|function>} routes - An object mapping route paths/patterns to entity type names or loader functions.
+ */
+export function setRoutes(routes) {
+  Object.assign(routeConfig, routes)
+}
+
+/**
+ * Adds a single route to the route configuration.
+ * @param {string} path - The route path or pattern (e.g., "/users/:userId").
+ * @param {string|function} route - The entity type name or a function that dynamically loads it.
+ */
+export function addRoute(path, route) {
+  routeConfig[path] = route
+}
+
+/**
+ * Removes a route from the route configuration.
+ * @param {string} path - The route path or pattern to remove.
+ */
+export function removeRoute(path) {
+  delete routeConfig[path]
 }
 
 /**
@@ -244,25 +296,30 @@ function buildPath(pattern, params = {}) {
 /**
  * Finds a matching route configuration for a given URL path.
  * It supports parameterized routes and a fallback "*" route.
- * @param {Record<string, string>} routes - The routes configuration map.
- * @param {string} path - The URL path to match.
+ * @param {Record<string, string>} routeConfig - The routes configuration map.
+ * @param {string} pathname - The URL path to match.
  * @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) {
-  const [pathname] = path.split("?")
+function findRoute(routeConfig, pathname) {
+  const [path, search] = pathname.split("?")
   let fallbackRoute = null
 
-  for (const [pattern, entityType] of Object.entries(routes)) {
+  for (const [pattern, entityType] of Object.entries(routeConfig)) {
     if (pattern === "*") {
-      fallbackRoute = { pattern, entityType, params: {}, path: pathname }
+      fallbackRoute = { pattern, entityType, params: {}, path }
       continue
     }
-    const params = matchRoute(pattern, pathname)
+
+    const params = matchRoute(pattern, path)
     if (params !== null) {
-      return { pattern, entityType, params, path: pathname }
+      const query = search
+        ? Object.fromEntries(new URLSearchParams(search))
+        : {}
+      return { pattern, entityType, params, path, query }
     }
   }
+
   return fallbackRoute
 }
 
@@ -312,50 +369,18 @@ function patternToRegex(pattern) {
   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.
+ * @param {string} options.path - The full path (pathname only, no query).
+ * @param {object} options.params - The extracted route parameters.
+ * @param {object} [options.query] - The parsed query parameters.
  */
-function updateRouter(entity, { entityType, path, params }) {
-  const [pathname, search] = path.split("?")
-  const query = search ? Object.fromEntries(new URLSearchParams(search)) : {}
-
-  entity.path = pathname
+function updateRouter(entity, { entityType, path, params, query }) {
   entity.route = entityType
+  entity.path = path
   entity.params = params
   entity.query = query
   entity.hash = window.location.hash

package/types/router.d.ts

@@ -26,8 +26,6 @@ export type QueryParams = Record<string, string>
 export interface RouterEntity {
   /** A unique identifier for the router entity. */
   id: string | number
-  /** The route configuration. */
-  routes: RoutesConfig
   /** The current active path, without query string or hash. */
   path?: string
   /** The entity type of the current active route. */
@@ -38,6 +36,10 @@ export interface RouterEntity {
   query?: QueryParams
   /** The hash from the current URL. */
   hash?: string
+  /** Whether a route is currently loading asynchronously. */
+  isLoading?: boolean
+  /** An error that occurred during route loading. */
+  error?: Error | null
 }
 
 /**
@@ -98,7 +100,7 @@ export interface RouterType {
     entity: RouterEntity,
     payload: string | number | NavigatePayload,
     api: StoreApi,
-  ): void
+  ): void | Promise<void>
 
   /**
    * Synchronizes the router entity's state with data from a routing event,
@@ -112,19 +114,61 @@ export interface RouterType {
     payload: RouteSyncPayload,
     api: StoreApi,
   ): void
+  /**
+   * Handles browser `popstate` events. May perform async loading for lazy routes.
+   */
+  popstate(
+    entity: RouterEntity,
+    payload: any,
+    api: StoreApi,
+  ): void | Promise<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.
+   * Handles successful async route loading for a pattern.
+   * Registers the loaded type and updates runtime route config.
    */
-  loadSuccess(entity: RouterEntity, payload: any, api: StoreApi): void
+  routeLoadSuccess(entity: RouterEntity, payload: any, api: StoreApi): void
 
   /**
-   * Handles async route loading errors.
-   * @param {RouterEntity} entity - The router entity.
-   * @param {Object} payload - The error payload.
+   * Handles errors that occurred while loading a lazy route.
    */
-  loadError(entity: RouterEntity, payload: any): void
+  routeLoadError(entity: RouterEntity, payload: any): void
 }
+
+/**
+ * Returns the current route configuration.
+ * @returns {Record<string, string|function>} The current route configuration.
+ */
+export function getRoutes(): Record<string, string | (() => Promise<any>)>
+
+/**
+ * Retrieves a single route configuration given its path.
+ * @param {string} path - The path of the route to retrieve.
+ * @returns {string|function|undefined} The route configuration or undefined if not found.
+ */
+export function getRoute(path: string): string | (() => Promise<any>)
+
+/**
+ * Sets or updates routes in the route configuration.
+ * Can be used both during initialization and at any point to add or update routes dynamically.
+ * @param routes An object mapping route paths/patterns to entity type names or loader functions.
+ */
+export function setRoutes(
+  routes: Record<string, string | (() => Promise<any>)>,
+): void
+
+/**
+ * Adds a single route to the route configuration.
+ * @param path The route path or pattern (e.g., "/users/:userId").
+ * @param route The entity type name or a function that dynamically loads it.
+ */
+export function addRoute(
+  path: string,
+  route: string | (() => Promise<any>),
+): void
+
+/**
+ * Removes a route from the route configuration.
+ * @param path The route path or pattern to remove.
+ */
+export function removeRoute(path: string): void