eleva 1.0.0-rc.3 → 1.0.0-rc.4

package/src/plugins/Router.js

@@ -0,0 +1,1217 @@
+"use strict";
+
+/**
+ * @typedef {import('eleva').Eleva} Eleva
+ * @typedef {import('eleva').Signal} Signal
+ * @typedef {import('eleva').ComponentDefinition} ComponentDefinition
+ */
+
+/**
+ * Simple error handler for the core router.
+ * Can be overridden by error handling plugins.
+ * Provides consistent error formatting and logging for router operations.
+ * @private
+ */
+const CoreErrorHandler = {
+  /**
+   * Handles router errors with basic formatting.
+   * @param {Error} error - The error to handle.
+   * @param {string} context - The context where the error occurred.
+   * @param {Object} details - Additional error details.
+   * @throws {Error} The formatted error.
+   */
+  handle(error, context, details = {}) {
+    const message = `[ElevaRouter] ${context}: ${error.message}`;
+    const formattedError = new Error(message);
+
+    // Preserve original error details
+    formattedError.originalError = error;
+    formattedError.context = context;
+    formattedError.details = details;
+
+    console.error(message, { error, context, details });
+    throw formattedError;
+  },
+
+  /**
+   * Logs a warning without throwing an error.
+   * @param {string} message - The warning message.
+   * @param {Object} details - Additional warning details.
+   */
+  warn(message, details = {}) {
+    console.warn(`[ElevaRouter] ${message}`, details);
+  },
+
+  /**
+   * Logs an error without throwing.
+   * @param {string} message - The error message.
+   * @param {Error} error - The original error.
+   * @param {Object} details - Additional error details.
+   */
+  log(message, error, details = {}) {
+    console.error(`[ElevaRouter] ${message}`, { error, details });
+  },
+};
+
+/**
+ * @typedef {Object} RouteLocation
+ * @property {string} path - The path of the route (e.g., '/users/123').
+ * @property {Object<string, string>} query - An object representing the query parameters.
+ * @property {string} fullUrl - The complete URL including hash, path, and query string.
+ * @property {Object<string, string>} params - An object containing dynamic route parameters.
+ * @property {Object<string, any>} meta - The meta object associated with the matched route.
+ * @property {string} [name] - The optional name of the matched route.
+ * @property {RouteDefinition} matched - The raw route definition object that was matched.
+ */
+
+/**
+ * @typedef {(to: RouteLocation, from: RouteLocation | null) => boolean | string | {path: string} | void | Promise<boolean | string | {path: string} | void>} NavigationGuard
+ * A function that acts as a guard for navigation. It runs *before* the navigation is confirmed.
+ * It can return:
+ * - `true` or `undefined`: to allow navigation.
+ * - `false`: to abort the navigation.
+ * - a `string` (path) or a `location object`: to redirect to a new route.
+ */
+
+/**
+ * @typedef {(...args: any[]) => void | Promise<void>} NavigationHook
+ * A function that acts as a lifecycle hook, typically for side effects. It does not affect navigation flow.
+ */
+
+/**
+ * @typedef {Object} RouterPlugin
+ * @property {string} name - The plugin name.
+ * @property {string} [version] - The plugin version.
+ * @property {Function} install - The install function that receives the router instance.
+ * @property {Function} [destroy] - Optional cleanup function called when the router is destroyed.
+ */
+
+/**
+ * @typedef {Object} RouteDefinition
+ * @property {string} path - The URL path pattern (e.g., '/', '/about', '/users/:id', '*').
+ * @property {string | ComponentDefinition | (() => Promise<{default: ComponentDefinition}>)} component - The component to render. Can be a registered name, a definition object, or an async import function.
+ * @property {string | ComponentDefinition | (() => Promise<{default: ComponentDefinition}>)} [layout] - An optional layout component to wrap the route's component.
+ * @property {string} [name] - An optional name for the route.
+ * @property {Object<string, any>} [meta] - Optional metadata for the route (e.g., for titles, auth flags).
+ * @property {NavigationGuard} [beforeEnter] - A route-specific guard executed before entering the route.
+ * @property {NavigationHook} [afterEnter] - A hook executed *after* the route has been entered and the new component is mounted.
+ * @property {NavigationGuard} [beforeLeave] - A guard executed *before* leaving the current route.
+ * @property {NavigationHook} [afterLeave] - A hook executed *after* leaving the current route and its component has been unmounted.
+ */
+
+/**
+ * @class Router
+ * @classdesc A powerful, reactive, and flexible Router Plugin for Eleva.js.
+ * This class manages all routing logic, including state, navigation, and rendering.
+ * @private
+ */
+class Router {
+  /**
+   * Creates an instance of the Router.
+   * @param {Eleva} eleva - The Eleva framework instance.
+   * @param {RouterOptions} options - The configuration options for the router.
+   */
+  constructor(eleva, options = {}) {
+    /** @type {Eleva} The Eleva framework instance. */
+    this.eleva = eleva;
+
+    /** @type {RouterOptions} The merged router options. */
+    this.options = {
+      mode: "hash",
+      queryParam: "view",
+      viewSelector: "root",
+      ...options,
+    };
+
+    /** @private @type {RouteDefinition[]} The processed list of route definitions. */
+    this.routes = this._processRoutes(options.routes || []);
+
+    /** @private @type {import('eleva').Emitter} The shared Eleva event emitter for global hooks. */
+    this.emitter = this.eleva.emitter;
+
+    /** @private @type {boolean} A flag indicating if the router has been started. */
+    this.isStarted = false;
+
+    /** @private @type {boolean} A flag to prevent navigation loops from history events. */
+    this._isNavigating = false;
+
+    /** @private @type {Array<() => void>} A collection of cleanup functions for event listeners. */
+    this.eventListeners = [];
+
+    /** @type {Signal<RouteLocation | null>} A reactive signal holding the current route's information. */
+    this.currentRoute = new this.eleva.signal(null);
+
+    /** @type {Signal<RouteLocation | null>} A reactive signal holding the previous route's information. */
+    this.previousRoute = new this.eleva.signal(null);
+
+    /** @type {Signal<Object<string, string>>} A reactive signal holding the current route's parameters. */
+    this.currentParams = new this.eleva.signal({});
+
+    /** @type {Signal<Object<string, string>>} A reactive signal holding the current route's query parameters. */
+    this.currentQuery = new this.eleva.signal({});
+
+    /** @type {Signal<import('eleva').MountResult | null>} A reactive signal for the currently mounted layout instance. */
+    this.currentLayout = new this.eleva.signal(null);
+
+    /** @type {Signal<import('eleva').MountResult | null>} A reactive signal for the currently mounted view (page) instance. */
+    this.currentView = new this.eleva.signal(null);
+
+    /** @private @type {Map<string, RouterPlugin>} Map of registered plugins by name. */
+    this.plugins = new Map();
+
+    /** @type {Object} The error handler instance. Can be overridden by plugins. */
+    this.errorHandler = CoreErrorHandler;
+
+    this._validateOptions();
+  }
+
+  /**
+   * Validates the provided router options.
+   * @private
+   * @throws {Error} If the routing mode is invalid.
+   */
+  _validateOptions() {
+    if (!["hash", "query", "history"].includes(this.options.mode)) {
+      this.errorHandler.handle(
+        new Error(
+          `Invalid routing mode: ${this.options.mode}. Must be "hash", "query", or "history".`
+        ),
+        "Configuration validation failed"
+      );
+    }
+  }
+
+  /**
+   * Pre-processes route definitions to parse their path segments for efficient matching.
+   * @private
+   * @param {RouteDefinition[]} routes - The raw route definitions.
+   * @returns {RouteDefinition[]} The processed routes.
+   */
+  _processRoutes(routes) {
+    const processedRoutes = [];
+    for (const route of routes) {
+      try {
+        processedRoutes.push({
+          ...route,
+          segments: this._parsePathIntoSegments(route.path),
+        });
+      } catch (error) {
+        this.errorHandler.warn(
+          `Invalid path in route definition "${route.path || "undefined"}": ${error.message}`,
+          { route, error }
+        );
+      }
+    }
+    return processedRoutes;
+  }
+
+  /**
+   * Parses a route path string into an array of static and parameter segments.
+   * @private
+   * @param {string} path - The path pattern to parse.
+   * @returns {Array<{type: 'static' | 'param', value?: string, name?: string}>} An array of segment objects.
+   * @throws {Error} If the route path is not a valid string.
+   */
+  _parsePathIntoSegments(path) {
+    if (!path || typeof path !== "string") {
+      this.errorHandler.handle(
+        new Error("Route path must be a non-empty string"),
+        "Path parsing failed",
+        { path }
+      );
+    }
+
+    const normalizedPath = path.replace(/\/+/g, "/").replace(/\/$/, "") || "/";
+
+    if (normalizedPath === "/") {
+      return [];
+    }
+
+    return normalizedPath
+      .split("/")
+      .filter(Boolean)
+      .map((segment) => {
+        if (segment.startsWith(":")) {
+          const paramName = segment.substring(1);
+          if (!paramName) {
+            this.errorHandler.handle(
+              new Error(`Invalid parameter segment: ${segment}`),
+              "Path parsing failed",
+              { segment, path }
+            );
+          }
+          return { type: "param", name: paramName };
+        }
+        return { type: "static", value: segment };
+      });
+  }
+
+  /**
+   * Finds the view element within a container using multiple selector strategies.
+   * @private
+   * @param {HTMLElement} container - The parent element to search within.
+   * @returns {HTMLElement} The found view element or the container itself as a fallback.
+   */
+  _findViewElement(container) {
+    const selector = this.options.viewSelector;
+    return (
+      container.querySelector(`#${selector}`) ||
+      container.querySelector(`.${selector}`) ||
+      container.querySelector(`[data-${selector}]`) ||
+      container.querySelector(selector) ||
+      container
+    );
+  }
+
+  /**
+   * Starts the router, initializes event listeners, and performs the initial navigation.
+   * @returns {Promise<void>}
+   */
+  async start() {
+    if (this.isStarted) {
+      this.errorHandler.warn("Router is already started");
+      return;
+    }
+    if (typeof window === "undefined") {
+      this.errorHandler.warn(
+        "Router start skipped: `window` object not available (SSR environment)"
+      );
+      return;
+    }
+    if (
+      typeof document !== "undefined" &&
+      !document.querySelector(this.options.mount)
+    ) {
+      this.errorHandler.warn(
+        `Mount element "${this.options.mount}" was not found in the DOM. The router will not start.`,
+        { mountSelector: this.options.mount }
+      );
+      return;
+    }
+    const handler = () => this._handleRouteChange();
+    if (this.options.mode === "hash") {
+      window.addEventListener("hashchange", handler);
+      this.eventListeners.push(() =>
+        window.removeEventListener("hashchange", handler)
+      );
+    } else {
+      window.addEventListener("popstate", handler);
+      this.eventListeners.push(() =>
+        window.removeEventListener("popstate", handler)
+      );
+    }
+    this.isStarted = true;
+    await this._handleRouteChange();
+  }
+
+  /**
+   * Stops the router and cleans up all event listeners and mounted components.
+   * @returns {Promise<void>}
+   */
+  async destroy() {
+    if (!this.isStarted) return;
+
+    // Clean up plugins
+    for (const plugin of this.plugins.values()) {
+      if (typeof plugin.destroy === "function") {
+        try {
+          await plugin.destroy(this);
+        } catch (error) {
+          this.errorHandler.log(`Plugin ${plugin.name} destroy failed`, error);
+        }
+      }
+    }
+
+    this.eventListeners.forEach((cleanup) => cleanup());
+    this.eventListeners = [];
+    if (this.currentLayout.value) {
+      await this.currentLayout.value.unmount();
+    }
+    this.isStarted = false;
+  }
+
+  /**
+   * Programmatically navigates to a new route.
+   * @param {string | {path: string, query?: object, params?: object, replace?: boolean, state?: object}} location - The target location as a string or object.
+   * @param {object} [params] - Optional route parameters (for string-based location).
+   * @returns {Promise<void>}
+   */
+  async navigate(location, params = {}) {
+    try {
+      const target =
+        typeof location === "string" ? { path: location, params } : location;
+      let path = this._buildPath(target.path, target.params || {});
+      const query = target.query || {};
+
+      if (Object.keys(query).length > 0) {
+        const queryString = new URLSearchParams(query).toString();
+        if (queryString) path += `?${queryString}`;
+      }
+
+      if (this._isSameRoute(path, target.params, query)) {
+        return;
+      }
+
+      const navigationSuccessful = await this._proceedWithNavigation(path);
+
+      if (navigationSuccessful) {
+        this._isNavigating = true;
+        const state = target.state || {};
+        const replace = target.replace || false;
+        const historyMethod = replace ? "replaceState" : "pushState";
+
+        if (this.options.mode === "hash") {
+          if (replace) {
+            const newUrl = `${window.location.pathname}${window.location.search}#${path}`;
+            window.history.replaceState(state, "", newUrl);
+          } else {
+            window.location.hash = path;
+          }
+        } else {
+          const url =
+            this.options.mode === "query" ? this._buildQueryUrl(path) : path;
+          history[historyMethod](state, "", url);
+        }
+        queueMicrotask(() => {
+          this._isNavigating = false;
+        });
+      }
+    } catch (error) {
+      this.errorHandler.log("Navigation failed", error);
+      await this.emitter.emit("router:onError", error);
+    }
+  }
+
+  /**
+   * Builds a URL for query mode.
+   * @private
+   * @param {string} path - The path to set as the query parameter.
+   * @returns {string} The full URL with the updated query string.
+   */
+  _buildQueryUrl(path) {
+    const urlParams = new URLSearchParams(window.location.search);
+    urlParams.set(this.options.queryParam, path.split("?")[0]);
+    return `${window.location.pathname}?${urlParams.toString()}`;
+  }
+
+  /**
+   * Checks if the target route is identical to the current route.
+   * @private
+   * @param {string} path - The target path with query string.
+   * @param {object} params - The target params.
+   * @param {object} query - The target query.
+   * @returns {boolean} - True if the routes are the same.
+   */
+  _isSameRoute(path, params, query) {
+    const current = this.currentRoute.value;
+    if (!current) return false;
+    const [targetPath, queryString] = path.split("?");
+    const targetQuery = query || this._parseQuery(queryString || "");
+    return (
+      current.path === targetPath &&
+      JSON.stringify(current.params) === JSON.stringify(params || {}) &&
+      JSON.stringify(current.query) === JSON.stringify(targetQuery)
+    );
+  }
+
+  /**
+   * Injects dynamic parameters into a path string.
+   * @private
+   */
+  _buildPath(path, params) {
+    let result = path;
+    for (const [key, value] of Object.entries(params)) {
+      // Fix: Handle special characters and ensure proper encoding
+      const encodedValue = encodeURIComponent(String(value));
+      result = result.replace(new RegExp(`:${key}\\b`, "g"), encodedValue);
+    }
+    return result;
+  }
+
+  /**
+   * The handler for browser-initiated route changes (e.g., back/forward buttons).
+   * @private
+   */
+  async _handleRouteChange() {
+    if (this._isNavigating) return;
+    const from = this.currentRoute.value;
+    const toLocation = this._getCurrentLocation();
+
+    const navigationSuccessful = await this._proceedWithNavigation(
+      toLocation.fullUrl
+    );
+
+    // If navigation was blocked by a guard, revert the URL change
+    if (!navigationSuccessful && from) {
+      this.navigate({ path: from.path, query: from.query, replace: true });
+    }
+  }
+
+  /**
+   * Manages the core navigation lifecycle. Runs guards before committing changes.
+   * @private
+   * @param {string} fullPath - The full path (e.g., '/users/123?foo=bar') to navigate to.
+   * @returns {Promise<boolean>} - `true` if navigation succeeded, `false` if aborted.
+   */
+  async _proceedWithNavigation(fullPath) {
+    const from = this.currentRoute.value;
+    const [path, queryString] = (fullPath || "/").split("?");
+    const toLocation = {
+      path: path.startsWith("/") ? path : `/${path}`,
+      query: this._parseQuery(queryString),
+      fullUrl: fullPath,
+    };
+
+    let toMatch = this._matchRoute(toLocation.path);
+
+    if (!toMatch) {
+      const notFoundRoute = this.routes.find((route) => route.path === "*");
+      if (notFoundRoute) {
+        toMatch = {
+          route: notFoundRoute,
+          params: { pathMatch: toLocation.path.substring(1) },
+        };
+      } else {
+        await this.emitter.emit(
+          "router:onError",
+          new Error(`Route not found: ${toLocation.path}`),
+          toLocation,
+          from
+        );
+        return false;
+      }
+    }
+
+    const to = {
+      ...toLocation,
+      params: toMatch.params,
+      meta: toMatch.route.meta || {},
+      name: toMatch.route.name,
+      matched: toMatch.route,
+    };
+
+    try {
+      // 1. Run all *pre-navigation* guards.
+      const canNavigate = await this._runGuards(to, from, toMatch.route);
+      if (!canNavigate) return false;
+
+      // 2. Resolve async components *before* touching the DOM.
+      const { layoutComponent, pageComponent } = await this._resolveComponents(
+        toMatch.route
+      );
+
+      // 3. Unmount the previous view/layout.
+      if (from) {
+        const toLayout = toMatch.route.layout || this.options.globalLayout;
+        const fromLayout = from.matched.layout || this.options.globalLayout;
+
+        const tryUnmount = async (instance) => {
+          if (!instance) return;
+
+          try {
+            await instance.unmount();
+          } catch (error) {
+            this.errorHandler.warn("Error during component unmount", {
+              error,
+              instance,
+            });
+          }
+        };
+
+        if (toLayout !== fromLayout) {
+          await tryUnmount(this.currentLayout.value);
+          this.currentLayout.value = null;
+        } else {
+          await tryUnmount(this.currentView.value);
+          this.currentView.value = null;
+        }
+
+        // 4. Call `afterLeave` hook *after* the old component has been unmounted.
+        if (from.matched.afterLeave) {
+          await from.matched.afterLeave(to, from);
+          await this.emitter.emit("router:afterLeave", to, from);
+        }
+      }
+
+      // 5. Update reactive state.
+      this.previousRoute.value = from;
+      this.currentRoute.value = to;
+      this.currentParams.value = to.params || {};
+      this.currentQuery.value = to.query || {};
+
+      // 6. Render the new components.
+      await this._render(layoutComponent, pageComponent, to);
+
+      // 7. Run post-navigation hooks.
+      if (toMatch.route.afterEnter) {
+        await toMatch.route.afterEnter(to, from);
+        await this.emitter.emit("router:afterEnter", to, from);
+      }
+      await this.emitter.emit("router:afterEach", to, from);
+
+      return true;
+    } catch (error) {
+      this.errorHandler.log("Error during navigation", error, { to, from });
+      await this.emitter.emit("router:onError", error, to, from);
+      return false;
+    }
+  }
+
+  /**
+   * Executes all applicable navigation guards for a transition in order.
+   * @private
+   * @returns {Promise<boolean>} - `false` if navigation should be aborted.
+   */
+  async _runGuards(to, from, route) {
+    const guards = [
+      ...(this.options.onBeforeEach ? [this.options.onBeforeEach] : []),
+      ...(from && from.matched.beforeLeave ? [from.matched.beforeLeave] : []),
+      ...(route.beforeEnter ? [route.beforeEnter] : []),
+    ];
+    for (const guard of guards) {
+      const result = await guard(to, from);
+      if (result === false) return false;
+      if (typeof result === "string" || typeof result === "object") {
+        this.navigate(result);
+        return false;
+      }
+    }
+    return true;
+  }
+
+  /**
+   * Resolves a string component definition to a component object.
+   * @private
+   * @param {string} def - The component name to resolve.
+   * @returns {ComponentDefinition} The resolved component.
+   * @throws {Error} If the component is not registered.
+   */
+  _resolveStringComponent(def) {
+    const componentDef = this.eleva._components.get(def);
+    if (!componentDef) {
+      this.errorHandler.handle(
+        new Error(`Component "${def}" not registered.`),
+        "Component resolution failed",
+        {
+          componentName: def,
+          availableComponents: Array.from(this.eleva._components.keys()),
+        }
+      );
+    }
+    return componentDef;
+  }
+
+  /**
+   * Resolves a function component definition to a component object.
+   * @private
+   * @param {Function} def - The function to resolve.
+   * @returns {Promise<ComponentDefinition>} The resolved component.
+   * @throws {Error} If the function fails to load the component.
+   */
+  async _resolveFunctionComponent(def) {
+    try {
+      const funcStr = def.toString();
+      const isAsyncImport =
+        funcStr.includes("import(") || funcStr.startsWith("() =>");
+
+      const result = await def();
+      return isAsyncImport ? result.default || result : result;
+    } catch (error) {
+      this.errorHandler.handle(
+        new Error(`Failed to load async component: ${error.message}`),
+        "Component resolution failed",
+        { function: def.toString(), error }
+      );
+    }
+  }
+
+  /**
+   * Validates a component definition object.
+   * @private
+   * @param {any} def - The component definition to validate.
+   * @returns {ComponentDefinition} The validated component.
+   * @throws {Error} If the component definition is invalid.
+   */
+  _validateComponentDefinition(def) {
+    if (!def || typeof def !== "object") {
+      this.errorHandler.handle(
+        new Error(`Invalid component definition: ${typeof def}`),
+        "Component validation failed",
+        { definition: def }
+      );
+    }
+
+    if (
+      typeof def.template !== "function" &&
+      typeof def.template !== "string"
+    ) {
+      this.errorHandler.handle(
+        new Error("Component missing template property"),
+        "Component validation failed",
+        { definition: def }
+      );
+    }
+
+    return def;
+  }
+
+  /**
+   * Resolves a component definition to a component object.
+   * @private
+   * @param {any} def - The component definition to resolve.
+   * @returns {Promise<ComponentDefinition | null>} The resolved component or null.
+   */
+  async _resolveComponent(def) {
+    if (def === null || def === undefined) {
+      return null;
+    }
+
+    if (typeof def === "string") {
+      return this._resolveStringComponent(def);
+    }
+
+    if (typeof def === "function") {
+      return await this._resolveFunctionComponent(def);
+    }
+
+    if (def && typeof def === "object") {
+      return this._validateComponentDefinition(def);
+    }
+
+    this.errorHandler.handle(
+      new Error(`Invalid component definition: ${typeof def}`),
+      "Component resolution failed",
+      { definition: def }
+    );
+  }
+
+  /**
+   * Asynchronously resolves the layout and page components for a route.
+   * @private
+   * @param {RouteDefinition} route - The route to resolve components for.
+   * @returns {Promise<{layoutComponent: ComponentDefinition | null, pageComponent: ComponentDefinition}>}
+   */
+  async _resolveComponents(route) {
+    const effectiveLayout = route.layout || this.options.globalLayout;
+
+    try {
+      const [layoutComponent, pageComponent] = await Promise.all([
+        this._resolveComponent(effectiveLayout),
+        this._resolveComponent(route.component),
+      ]);
+
+      if (!pageComponent) {
+        this.errorHandler.handle(
+          new Error(
+            `Page component is null or undefined for route: ${route.path}`
+          ),
+          "Component resolution failed",
+          { route: route.path }
+        );
+      }
+
+      return { layoutComponent, pageComponent };
+    } catch (error) {
+      this.errorHandler.log(
+        `Error resolving components for route ${route.path}`,
+        error,
+        { route: route.path }
+      );
+      throw error;
+    }
+  }
+
+  /**
+   * Renders the components for the current route into the DOM.
+   * @private
+   * @param {ComponentDefinition | null} layoutComponent - The pre-loaded layout component.
+   * @param {ComponentDefinition} pageComponent - The pre-loaded page component.
+   */
+  async _render(layoutComponent, pageComponent) {
+    const mountEl = document.querySelector(this.options.mount);
+    if (!mountEl) {
+      this.errorHandler.handle(
+        new Error(`Mount element "${this.options.mount}" not found.`),
+        { mountSelector: this.options.mount }
+      );
+    }
+
+    if (layoutComponent) {
+      const layoutInstance = await this.eleva.mount(
+        mountEl,
+        this._wrapComponentWithChildren(layoutComponent)
+      );
+      this.currentLayout.value = layoutInstance;
+      const viewEl = this._findViewElement(layoutInstance.container);
+      const viewInstance = await this.eleva.mount(
+        viewEl,
+        this._wrapComponentWithChildren(pageComponent)
+      );
+      this.currentView.value = viewInstance;
+    } else {
+      const viewInstance = await this.eleva.mount(
+        mountEl,
+        this._wrapComponentWithChildren(pageComponent)
+      );
+      this.currentView.value = viewInstance;
+      this.currentLayout.value = null;
+    }
+  }
+
+  /**
+   * Creates a getter function for router context properties.
+   * @private
+   * @param {string} property - The property name to access.
+   * @param {any} defaultValue - The default value if property is undefined.
+   * @returns {Function} A getter function.
+   */
+  _createRouteGetter(property, defaultValue) {
+    return () => this.currentRoute.value?.[property] ?? defaultValue;
+  }
+
+  /**
+   * Wraps a component definition to inject router-specific context into its setup function.
+   * @private
+   * @param {ComponentDefinition} component - The component to wrap.
+   * @returns {ComponentDefinition} The wrapped component definition.
+   */
+  _wrapComponent(component) {
+    const originalSetup = component.setup;
+    const self = this;
+
+    return {
+      ...component,
+      async setup(ctx) {
+        ctx.router = {
+          navigate: self.navigate.bind(self),
+          current: self.currentRoute,
+          previous: self.previousRoute,
+
+          // Route property getters
+          get params() {
+            return self._createRouteGetter("params", {})();
+          },
+          get query() {
+            return self._createRouteGetter("query", {})();
+          },
+          get path() {
+            return self._createRouteGetter("path", "/")();
+          },
+          get fullUrl() {
+            return self._createRouteGetter("fullUrl", window.location.href)();
+          },
+          get meta() {
+            return self._createRouteGetter("meta", {})();
+          },
+        };
+
+        return originalSetup ? await originalSetup(ctx) : {};
+      },
+    };
+  }
+
+  /**
+   * Recursively wraps all child components to ensure they have access to router context.
+   * @private
+   * @param {ComponentDefinition} component - The component to wrap.
+   * @returns {ComponentDefinition} The wrapped component definition.
+   */
+  _wrapComponentWithChildren(component) {
+    const wrappedComponent = this._wrapComponent(component);
+
+    // If the component has children, wrap them too
+    if (
+      wrappedComponent.children &&
+      typeof wrappedComponent.children === "object"
+    ) {
+      const wrappedChildren = {};
+      for (const [selector, childComponent] of Object.entries(
+        wrappedComponent.children
+      )) {
+        wrappedChildren[selector] =
+          this._wrapComponentWithChildren(childComponent);
+      }
+      wrappedComponent.children = wrappedChildren;
+    }
+
+    return wrappedComponent;
+  }
+
+  /**
+   * Gets the current location information from the browser's window object.
+   * @private
+   * @returns {Omit<RouteLocation, 'params' | 'meta' | 'name' | 'matched'>}
+   */
+  _getCurrentLocation() {
+    if (typeof window === "undefined")
+      return { path: "/", query: {}, fullUrl: "" };
+    let path, queryString, fullUrl;
+    switch (this.options.mode) {
+      case "hash":
+        fullUrl = window.location.hash.slice(1) || "/";
+        [path, queryString] = fullUrl.split("?");
+        break;
+      case "query":
+        const urlParams = new URLSearchParams(window.location.search);
+        path = urlParams.get(this.options.queryParam) || "/";
+        queryString = window.location.search.slice(1);
+        fullUrl = path;
+        break;
+      default: // 'history' mode
+        path = window.location.pathname || "/";
+        queryString = window.location.search.slice(1);
+        fullUrl = `${path}${queryString ? "?" + queryString : ""}`;
+    }
+    return {
+      path: path.startsWith("/") ? path : `/${path}`,
+      query: this._parseQuery(queryString),
+      fullUrl,
+    };
+  }
+
+  /**
+   * Parses a query string into a key-value object.
+   * @private
+   */
+  _parseQuery(queryString) {
+    const query = {};
+    if (queryString) {
+      new URLSearchParams(queryString).forEach((value, key) => {
+        query[key] = value;
+      });
+    }
+    return query;
+  }
+
+  /**
+   * Matches a given path against the registered routes.
+   * @private
+   * @param {string} path - The path to match.
+   * @returns {{route: RouteDefinition, params: Object<string, string>} | null} The matched route and its params, or null.
+   */
+  _matchRoute(path) {
+    const pathSegments = path.split("/").filter(Boolean);
+
+    for (const route of this.routes) {
+      // Handle the root path as a special case.
+      if (route.path === "/") {
+        if (pathSegments.length === 0) return { route, params: {} };
+        continue;
+      }
+
+      if (route.segments.length !== pathSegments.length) continue;
+
+      const params = {};
+      let isMatch = true;
+      for (let i = 0; i < route.segments.length; i++) {
+        const routeSegment = route.segments[i];
+        const pathSegment = pathSegments[i];
+        if (routeSegment.type === "param") {
+          params[routeSegment.name] = decodeURIComponent(pathSegment);
+        } else if (routeSegment.value !== pathSegment) {
+          isMatch = false;
+          break;
+        }
+      }
+      if (isMatch) return { route, params };
+    }
+    return null;
+  }
+
+  /** Registers a global pre-navigation guard. */
+  onBeforeEach(guard) {
+    this.options.onBeforeEach = guard;
+  }
+  /** Registers a global hook that runs after a new route component has been mounted *if* the route has an `afterEnter` hook. */
+  onAfterEnter(hook) {
+    this.emitter.on("router:afterEnter", hook);
+  }
+  /** Registers a global hook that runs after a route component has been unmounted *if* the route has an `afterLeave` hook. */
+  onAfterLeave(hook) {
+    this.emitter.on("router:afterLeave", hook);
+  }
+  /** Registers a global hook that runs after a navigation has been confirmed and all hooks have completed. */
+  onAfterEach(hook) {
+    this.emitter.on("router:afterEach", hook);
+  }
+  /** Registers a global error handler for navigation. */
+  onError(handler) {
+    this.emitter.on("router:onError", handler);
+  }
+
+  /**
+   * Registers a plugin with the router.
+   * @param {RouterPlugin} plugin - The plugin to register.
+   */
+  use(plugin, options = {}) {
+    if (typeof plugin.install !== "function") {
+      this.errorHandler.handle(
+        new Error("Plugin must have an install method"),
+        "Plugin registration failed",
+        { plugin }
+      );
+    }
+
+    // Check if plugin is already registered
+    if (this.plugins.has(plugin.name)) {
+      this.errorHandler.warn(`Plugin "${plugin.name}" is already registered`, {
+        existingPlugin: this.plugins.get(plugin.name),
+      });
+      return;
+    }
+
+    this.plugins.set(plugin.name, plugin);
+    plugin.install(this, options);
+  }
+
+  /**
+   * Gets all registered plugins.
+   * @returns {RouterPlugin[]} Array of registered plugins.
+   */
+  getPlugins() {
+    return Array.from(this.plugins.values());
+  }
+
+  /**
+   * Gets a plugin by name.
+   * @param {string} name - The plugin name.
+   * @returns {RouterPlugin | undefined} The plugin or undefined.
+   */
+  getPlugin(name) {
+    return this.plugins.get(name);
+  }
+
+  /**
+   * Removes a plugin from the router.
+   * @param {string} name - The plugin name.
+   * @returns {boolean} True if the plugin was removed.
+   */
+  removePlugin(name) {
+    const plugin = this.plugins.get(name);
+    if (!plugin) return false;
+
+    // Call destroy if available
+    if (typeof plugin.destroy === "function") {
+      try {
+        plugin.destroy(this);
+      } catch (error) {
+        this.errorHandler.log(`Plugin ${name} destroy failed`, error);
+      }
+    }
+
+    return this.plugins.delete(name);
+  }
+
+  /**
+   * Sets a custom error handler. Used by error handling plugins.
+   * @param {Object} errorHandler - The error handler object with handle, warn, and log methods.
+   */
+  setErrorHandler(errorHandler) {
+    if (
+      errorHandler &&
+      typeof errorHandler.handle === "function" &&
+      typeof errorHandler.warn === "function" &&
+      typeof errorHandler.log === "function"
+    ) {
+      this.errorHandler = errorHandler;
+    } else {
+      console.warn(
+        "[ElevaRouter] Invalid error handler provided. Must have handle, warn, and log methods."
+      );
+    }
+  }
+}
+
+/**
+ * @typedef {Object} RouterOptions
+ * @property {string} mount - A CSS selector for the main element where the app is mounted.
+ * @property {RouteDefinition[]} routes - An array of route definitions.
+ * @property {'hash' | 'query' | 'history'} [mode='hash'] - The routing mode.
+ * @property {string} [queryParam='page'] - The query parameter to use in 'query' mode.
+ * @property {string} [viewSelector='view'] - The selector for the view element within a layout.
+ * @property {boolean} [autoStart=true] - Whether to start the router automatically.
+ * @property {NavigationGuard} [onBeforeEach] - A global guard executed before every navigation.
+ * @property {string | ComponentDefinition | (() => Promise<{default: ComponentDefinition}>)} [globalLayout] - A global layout for all routes. Can be overridden by a route's specific layout.
+ */
+
+/**
+ * @class 🚀 RouterPlugin
+ * @classdesc A powerful, reactive, and flexible Router Plugin for Eleva.js applications.
+ * This plugin provides comprehensive client-side routing functionality including:
+ * - Multiple routing modes (hash, history, query)
+ * - Navigation guards and lifecycle hooks
+ * - Reactive state management
+ * - Component resolution and lazy loading
+ * - Layout and page component separation
+ * - Plugin system for extensibility
+ * - Advanced error handling
+ *
+ * @example
+ * // Install the plugin
+ * const app = new Eleva("myApp");
+ *
+ * const HomePage = { template: () => `<h1>Home</h1>` };
+ * const AboutPage = { template: () => `<h1>About Us</h1>` };
+ * const UserPage = {
+ *   template: (ctx) => `<h1>User: ${ctx.router.params.id}</h1>`
+ * };
+ *
+ * app.use(RouterPlugin, {
+ *   mount: '#app',
+ *   mode: 'hash',
+ *   routes: [
+ *     { path: '/', component: HomePage },
+ *     { path: '/about', component: AboutPage },
+ *     { path: '/users/:id', component: UserPage }
+ *   ]
+ * });
+ */
+export const RouterPlugin = {
+  /**
+   * Unique identifier for the plugin
+   * @type {string}
+   */
+  name: "router",
+
+  /**
+   * Plugin version
+   * @type {string}
+   */
+  version: "1.0.0-rc.1",
+
+  /**
+   * Plugin description
+   * @type {string}
+   */
+  description: "Client-side routing for Eleva applications",
+
+  /**
+   * Installs the RouterPlugin into an Eleva instance.
+   *
+   * @param {Eleva} eleva - The Eleva instance
+   * @param {RouterOptions} options - Router configuration options
+   * @param {string} options.mount - A CSS selector for the main element where the app is mounted
+   * @param {RouteDefinition[]} options.routes - An array of route definitions
+   * @param {'hash' | 'query' | 'history'} [options.mode='hash'] - The routing mode
+   * @param {string} [options.queryParam='page'] - The query parameter to use in 'query' mode
+   * @param {string} [options.viewSelector='view'] - The selector for the view element within a layout
+   * @param {boolean} [options.autoStart=true] - Whether to start the router automatically
+   * @param {NavigationGuard} [options.onBeforeEach] - A global guard executed before every navigation
+   * @param {string | ComponentDefinition | (() => Promise<{default: ComponentDefinition}>)} [options.globalLayout] - A global layout for all routes
+   *
+   * @example
+   * // main.js
+   * import Eleva from './eleva.js';
+   * import { RouterPlugin } from './plugins/RouterPlugin.js';
+   *
+   * const app = new Eleva('myApp');
+   *
+   * const HomePage = { template: () => `<h1>Home</h1>` };
+   * const AboutPage = { template: () => `<h1>About Us</h1>` };
+   *
+   * app.use(RouterPlugin, {
+   *  mount: '#app',
+   *  routes: [
+   *    { path: '/', component: HomePage },
+   *    { path: '/about', component: AboutPage }
+   *  ]
+   * });
+   */
+  install(eleva, options = {}) {
+    if (!options.mount) {
+      throw new Error("[RouterPlugin] 'mount' option is required");
+    }
+
+    if (!options.routes || !Array.isArray(options.routes)) {
+      throw new Error("[RouterPlugin] 'routes' option must be an array");
+    }
+
+    /**
+     * Registers a component definition with the Eleva instance.
+     * This method handles both inline component objects and pre-registered component names.
+     *
+     * @param {any} def - The component definition to register
+     * @param {string} type - The type of component for naming (e.g., "Route", "Layout")
+     * @returns {string | null} The registered component name or null if no definition provided
+     */
+    const register = (def, type) => {
+      if (!def) return null;
+
+      if (typeof def === "object" && def !== null && !def.name) {
+        const name = `Eleva${type}Component_${Math.random()
+          .toString(36)
+          .slice(2, 11)}`;
+
+        try {
+          eleva.component(name, def);
+          return name;
+        } catch (error) {
+          throw new Error(
+            `[RouterPlugin] Failed to register ${type} component: ${error.message}`
+          );
+        }
+      }
+      return def;
+    };
+
+    if (options.globalLayout) {
+      options.globalLayout = register(options.globalLayout, "GlobalLayout");
+    }
+
+    (options.routes || []).forEach((route) => {
+      route.component = register(route.component, "Route");
+      if (route.layout) {
+        route.layout = register(route.layout, "RouteLayout");
+      }
+    });
+
+    const router = new Router(eleva, options);
+    eleva.router = router;
+
+    if (options.autoStart !== false) {
+      queueMicrotask(() => router.start());
+    }
+
+    // Add plugin metadata to the Eleva instance
+    if (!eleva.plugins) {
+      eleva.plugins = new Map();
+    }
+    eleva.plugins.set(this.name, {
+      name: this.name,
+      version: this.version,
+      description: this.description,
+      options,
+    });
+
+    // Add utility methods for manual router access
+    eleva.navigate = router.navigate.bind(router);
+    eleva.getCurrentRoute = () => router.currentRoute.value;
+    eleva.getRouteParams = () => router.currentParams.value;
+    eleva.getRouteQuery = () => router.currentQuery.value;
+
+    return router;
+  },
+
+  /**
+   * Uninstalls the plugin from the Eleva instance
+   *
+   * @param {Eleva} eleva - The Eleva instance
+   */
+  async uninstall(eleva) {
+    if (eleva.router) {
+      await eleva.router.destroy();
+      delete eleva.router;
+    }
+
+    // Remove plugin metadata
+    if (eleva.plugins) {
+      eleva.plugins.delete(this.name);
+    }
+
+    // Remove utility methods
+    delete eleva.navigate;
+    delete eleva.getCurrentRoute;
+    delete eleva.getRouteParams;
+    delete eleva.getRouteQuery;
+  },
+};