elementdrawing 1.0.0

package/src/js/router.js

@@ -0,0 +1,483 @@
+/**
+ * Client-Side Router
+ * ElementDrawing Framework - Route definition, matching, navigation,
+ * History API, hash fallback, guards, lazy loading, nested routes,
+ * named routes, transitions, and query string parsing.
+ */
+
+'use strict';
+
+// ─── Route Definition ─────────────────────────────────────────────────────────
+
+/**
+ * Create a route configuration.
+ * @param {Object} config
+ * @param {string} config.path - URL path pattern
+ * @param {Function|string} config.component - Component to render
+ * @param {string} [config.name] - Named route
+ * @param {Object} [config.meta] - Route metadata
+ * @param {Function} [config.redirect] - Redirect function or path
+ * @param {Function} [config.beforeEnter] - Navigation guard
+ * @param {Array} [config.children] - Child routes
+ * @param {Object} [config.props] - Props to pass to component
+ * @returns {Object} Route configuration
+ */
+function createRoute(config) {
+  return {
+    path: config.path,
+    component: config.component,
+    name: config.name || null,
+    meta: config.meta || {},
+    redirect: config.redirect || null,
+    beforeEnter: config.beforeEnter || null,
+    children: (config.children || []).map((child) => {
+      // Inherit parent path prefix
+      if (config.path && config.path !== '/' && child.path && !child.path.startsWith('/')) {
+        child.path = config.path.replace(/\/$/, '') + '/' + child.path;
+      }
+      return createRoute(child);
+    }),
+    props: config.props || {},
+    _regex: null,
+    _paramNames: [],
+  };
+}
+
+// ─── Path Matching ────────────────────────────────────────────────────────────
+
+/**
+ * Compile a path pattern into a regex.
+ * Supports :param, :param?, *wildcard
+ * @param {string} path
+ * @returns {{ regex: RegExp, paramNames: string[] }}
+ */
+function compilePath(path) {
+  const paramNames = [];
+  let regexStr = '^' + path
+    .replace(/\//g, '\\/')
+    .replace(/:([^/]+)/g, (_, paramName) => {
+      if (paramName.endsWith('?')) {
+        paramNames.push(paramName.slice(0, -1));
+        return '(?:([^/]+))?';
+      }
+      paramNames.push(paramName);
+      return '([^/]+)';
+    })
+    .replace(/\*([^/]*)/, '(?:.*)') +
+    '(?:\\?.*)?$';
+
+  return { regex: new RegExp(regexStr), paramNames };
+}
+
+/**
+ * Match a path against a route pattern.
+ * @param {string} pattern - Route pattern (e.g., '/users/:id')
+ * @param {string} path - Actual path to match
+ * @param {boolean} [exact=true] - Require exact match
+ * @returns {Object|null} Match result with params, or null
+ */
+function matchPath(pattern, path, exact) {
+  exact = exact !== false;
+  const { regex, paramNames } = compilePath(pattern);
+  const match = path.match(regex);
+
+  if (!match) return null;
+
+  const params = {};
+  paramNames.forEach((name, i) => {
+    params[name] = match[i + 1] !== undefined ? decodeURIComponent(match[i + 1]) : undefined;
+  });
+
+  // Check if remaining path exists for non-exact match
+  const matchedLength = match[0].length;
+  if (exact && matchedLength < path.length) {
+    // Check for query string
+    if (path[matchedLength] !== '?') return null;
+  }
+
+  return {
+    path: match[0].replace(/\?.*$/, ''),
+    params,
+    isExact: matchedLength === path.length || path[matchedLength] === '?',
+  };
+}
+
+/**
+ * Match a path against all registered routes.
+ * @param {string} path
+ * @param {Array} routes
+ * @returns {Object|null} Matched route with params
+ */
+function matchRoute(path, routes) {
+  for (let i = 0; i < routes.length; i++) {
+    const route = routes[i];
+    const match = matchPath(route.path, path, !route.children || route.children.length === 0);
+
+    if (match) {
+      const result = { route, match };
+
+      // Check children for nested matching
+      if (route.children && route.children.length > 0) {
+        const remainingPath = path.slice(match.path.length) || '/';
+        const childMatch = matchRoute(remainingPath, route.children);
+        if (childMatch) {
+          result.child = childMatch;
+          Object.assign(result.match.params, childMatch.match.params);
+        }
+      }
+
+      return result;
+    }
+  }
+  return null;
+}
+
+// ─── Query String Parsing ─────────────────────────────────────────────────────
+
+/**
+ * Parse a query string into an object.
+ * @param {string} qs
+ * @returns {Object}
+ */
+function parseQuery(qs) {
+  if (!qs) return {};
+  qs = qs.replace(/^\?/, '');
+  const params = {};
+  qs.split('&').forEach((pair) => {
+    const [key, val] = pair.split('=');
+    if (!key) return;
+    const decoded = decodeURIComponent(val || '');
+    if (params[decodeURIComponent(key)]) {
+      if (!Array.isArray(params[decodeURIComponent(key)])) {
+        params[decodeURIComponent(key)] = [params[decodeURIComponent(key)]];
+      }
+      params[decodeURIComponent(key)].push(decoded);
+    } else {
+      params[decodeURIComponent(key)] = decoded;
+    }
+  });
+  return params;
+}
+
+/**
+ * Stringify an object into a query string.
+ * @param {Object} params
+ * @returns {string}
+ */
+function stringifyQuery(params) {
+  if (!params) return '';
+  return Object.keys(params)
+    .filter((k) => params[k] !== undefined && params[k] !== null)
+    .map((k) => encodeURIComponent(k) + '=' + encodeURIComponent(params[k]))
+    .join('&');
+}
+
+// ─── Router Class ─────────────────────────────────────────────────────────────
+
+function Router(options) {
+  options = options || {};
+  this.routes = [];
+  this.currentRoute = null;
+  this.currentParams = {};
+  this.currentQuery = {};
+  this.beforeEachGuards = [];
+  this.afterEachGuards = [];
+  this._listeners = [];
+  this._mode = options.mode || 'history'; // 'history' | 'hash'
+  this._base = options.base || '';
+  this._transition = options.transition || null;
+  this._namedRoutes = {};
+
+  // Register routes
+  if (options.routes) {
+    options.routes.forEach((r) => this.addRoute(r));
+  }
+
+  // Bind popstate
+  this._onPopState = this._onPopState.bind(this);
+}
+
+/**
+ * Add a route to the router.
+ * @param {Object} routeConfig
+ */
+Router.prototype.addRoute = function (routeConfig) {
+  const route = createRoute(routeConfig);
+  this.routes.push(route);
+  if (route.name) {
+    this._namedRoutes[route.name] = route;
+  }
+  return this;
+};
+
+/**
+ * Remove a route by path.
+ * @param {string} path
+ */
+Router.prototype.removeRoute = function (path) {
+  const idx = this.routes.findIndex((r) => r.path === path);
+  if (idx !== -1) this.routes.splice(idx, 1);
+  return this;
+};
+
+// ─── Navigation ───────────────────────────────────────────────────────────────
+
+/**
+ * Navigate to a path.
+ * @param {string} path
+ * @param {Object} [query]
+ * @returns {Promise<boolean>}
+ */
+Router.prototype.push = function (path, query) {
+  return this._navigate(path, query, 'push');
+};
+
+/**
+ * Replace current history entry.
+ * @param {string} path
+ * @param {Object} [query]
+ * @returns {Promise<boolean>}
+ */
+Router.prototype.replace = function (path, query) {
+  return this._navigate(path, query, 'replace');
+};
+
+/**
+ * Navigate by history offset.
+ * @param {number} offset
+ */
+Router.prototype.go = function (offset) {
+  window.history.go(offset);
+};
+
+/**
+ * Go back one entry.
+ */
+Router.prototype.back = function () { this.go(-1); };
+
+/**
+ * Go forward one entry.
+ */
+Router.prototype.forward = function () { this.go(1); };
+
+/**
+ * Navigate to a named route.
+ * @param {string} name
+ * @param {Object} [params]
+ * @param {Object} [query]
+ * @returns {Promise<boolean>}
+ */
+Router.prototype.pushByName = function (name, params, query) {
+  const route = this._namedRoutes[name];
+  if (!route) return Promise.reject(new Error('Route not found: ' + name));
+  const path = buildPath(route.path, params);
+  return this.push(path, query);
+};
+
+// ─── Internal Navigation ──────────────────────────────────────────────────────
+
+Router.prototype._navigate = async function (path, query, action) {
+  const fullPath = this._base + path + (query ? '?' + stringifyQuery(query) : '');
+
+  // Run beforeEach guards
+  const toRoute = matchRoute(path, this.routes);
+  const fromRoute = this.currentRoute;
+
+  for (const guard of this.beforeEachGuards) {
+    const result = await guard(toRoute, fromRoute);
+    if (result === false) return false;
+    if (typeof result === 'string') {
+      return this.push(result);
+    }
+    if (typeof result === 'object' && result.path) {
+      return this.push(result.path, result.query);
+    }
+  }
+
+  // Run route-level beforeEnter guard
+  if (toRoute && toRoute.route && toRoute.route.beforeEnter) {
+    const result = await toRoute.route.beforeEnter(toRoute, fromRoute);
+    if (result === false) return false;
+    if (typeof result === 'string') return this.push(result);
+  }
+
+  // Update history
+  if (this._mode === 'history') {
+    if (action === 'push') {
+      window.history.pushState({ path: fullPath }, '', fullPath);
+    } else {
+      window.history.replaceState({ path: fullPath }, '', fullPath);
+    }
+  } else {
+    window.location.hash = path;
+  }
+
+  // Update current state
+  const parsedPath = this._parseFullPath(fullPath);
+  this.currentRoute = toRoute;
+  this.currentParams = toRoute ? toRoute.match.params : {};
+  this.currentQuery = parsedPath.query;
+
+  // Run afterEach guards
+  for (const guard of this.afterEachGuards) {
+    guard(toRoute, fromRoute);
+  }
+
+  // Notify listeners
+  this._notifyListeners(toRoute, fromRoute);
+
+  return true;
+};
+
+Router.prototype._parseFullPath = function (fullPath) {
+  const [path, qs] = fullPath.split('?');
+  return { path, query: parseQuery(qs) };
+};
+
+Router.prototype._onPopState = function () {
+  const path = this._mode === 'history'
+    ? window.location.pathname.slice(this._base.length) || '/'
+    : window.location.hash.slice(1) || '/';
+  this.replace(path);
+};
+
+// ─── Route Guards ─────────────────────────────────────────────────────────────
+
+/**
+ * Register a beforeEach guard.
+ * @param {Function} guard - (to, from) => boolean | string | { path, query }
+ * @returns {Function} Remove guard function
+ */
+Router.prototype.beforeEach = function (guard) {
+  this.beforeEachGuards.push(guard);
+  return () => {
+    const idx = this.beforeEachGuards.indexOf(guard);
+    if (idx !== -1) this.beforeEachGuards.splice(idx, 1);
+  };
+};
+
+/**
+ * Register an afterEach guard.
+ * @param {Function} guard - (to, from) => void
+ * @returns {Function} Remove guard function
+ */
+Router.prototype.afterEach = function (guard) {
+  this.afterEachGuards.push(guard);
+  return () => {
+    const idx = this.afterEachGuards.indexOf(guard);
+    if (idx !== -1) this.afterEachGuards.splice(idx, 1);
+  };
+};
+
+// ─── Lazy Loading ─────────────────────────────────────────────────────────────
+
+/**
+ * Create a lazy-loaded route component.
+ * @param {Function} loader - () => Promise<Component>
+ * @returns {Function} Lazy component
+ */
+Router.prototype.lazy = function (loader) {
+  let cachedComponent = null;
+  return function LazyComponent(props) {
+    if (cachedComponent) return cachedComponent(props);
+    return loader().then((module) => {
+      cachedComponent = module.default || module;
+      return cachedComponent(props);
+    });
+  };
+};
+
+// ─── Active Route Detection ───────────────────────────────────────────────────
+
+/**
+ * Check if a path is currently active.
+ * @param {string} path
+ * @param {boolean} [exact=false]
+ * @returns {boolean}
+ */
+Router.prototype.isActive = function (path, exact) {
+  if (!this.currentRoute) return false;
+  const currentPath = this.currentRoute.match ? this.currentRoute.match.path : '';
+  if (exact) return currentPath === path;
+  return currentPath.startsWith(path);
+};
+
+// ─── Listener Management ──────────────────────────────────────────────────────
+
+Router.prototype.onRouteChange = function (callback) {
+  this._listeners.push(callback);
+  return () => {
+    const idx = this._listeners.indexOf(callback);
+    if (idx !== -1) this._listeners.splice(idx, 1);
+  };
+};
+
+Router.prototype._notifyListeners = function (to, from) {
+  this._listeners.forEach((cb) => {
+    try { cb(to, from); } catch (e) { console.error('[Router] Listener error:', e); }
+  });
+};
+
+// ─── Start/Stop ───────────────────────────────────────────────────────────────
+
+/**
+ * Start listening for navigation events.
+ */
+Router.prototype.start = function () {
+  if (this._mode === 'history') {
+    window.addEventListener('popstate', this._onPopState);
+    // Navigate to current URL
+    const path = window.location.pathname.slice(this._base.length) || '/';
+    this.replace(path);
+  } else {
+    window.addEventListener('hashchange', this._onPopState);
+    const hash = window.location.hash.slice(1) || '/';
+    this.replace(hash);
+  }
+};
+
+/**
+ * Stop the router.
+ */
+Router.prototype.stop = function () {
+  if (this._mode === 'history') {
+    window.removeEventListener('popstate', this._onPopState);
+  } else {
+    window.removeEventListener('hashchange', this._onPopState);
+  }
+};
+
+// ─── Helper: Build path from pattern and params ──────────────────────────────
+
+function buildPath(pattern, params) {
+  params = params || {};
+  return pattern.replace(/:([^/?]+)/g, (_, name) => {
+    if (name.endsWith('?')) name = name.slice(0, -1);
+    return params[name] !== undefined ? encodeURIComponent(params[name]) : '';
+  }).replace(/\/+/g, '/').replace(/\/$/, '') || '/';
+}
+
+// ─── Factory ──────────────────────────────────────────────────────────────────
+
+/**
+ * Create a new router instance.
+ * @param {Object} [options]
+ * @returns {Router}
+ */
+function createRouter(options) {
+  return new Router(options);
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+module.exports = {
+  Router,
+  createRouter,
+  createRoute,
+  matchPath,
+  matchRoute,
+  compilePath,
+  parseQuery,
+  stringifyQuery,
+  buildPath,
+};