@esmx/router 3.0.0-rc.103

package/dist/route-transition.mjs

@@ -0,0 +1,356 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import { Route } from "./route.mjs";
+import {
+  createRouteTask,
+  RouteTaskController
+} from "./route-task.mjs";
+import {
+  getSavedScrollPosition,
+  saveScrollPosition,
+  scrollToPosition
+} from "./scroll.mjs";
+import { RouteType } from "./types.mjs";
+import {
+  isBrowser,
+  isRouteMatched,
+  isUrlEqual,
+  isValidConfirmHookResult,
+  removeFromArray
+} from "./util.mjs";
+export const ROUTE_TRANSITION_HOOKS = {
+  async fallback(to, from, router) {
+    if (to.matched.length === 0) {
+      return router.parsedOptions.fallback;
+    }
+  },
+  async override(to, from, router) {
+    var _a, _b;
+    const result = await ((_b = (_a = to.config) == null ? void 0 : _a.override) == null ? void 0 : _b.call(_a, to, from, router));
+    if (isValidConfirmHookResult(result)) {
+      return result;
+    }
+  },
+  async asyncComponent(to, from, router) {
+    await Promise.all(
+      to.matched.map(async (matched) => {
+        const { asyncComponent, component } = matched;
+        if (!component && typeof asyncComponent === "function") {
+          try {
+            const result = await asyncComponent();
+            matched.component = result;
+          } catch (e) {
+            const error = e instanceof Error ? e : new Error(String(e));
+            throw new Error(
+              "Async component '".concat(matched.compilePath, "' is not a valid component. Original error: ").concat(error.message)
+            );
+          }
+        }
+      })
+    );
+  },
+  async beforeLeave(to, from, router) {
+    if (!(from == null ? void 0 : from.matched.length)) return;
+    const leavingRoutes = from.matched.filter(
+      (fromRoute) => !to.matched.some((toRoute) => toRoute === fromRoute)
+    );
+    for (let i = leavingRoutes.length - 1; i >= 0; i--) {
+      const route = leavingRoutes[i];
+      if (route.beforeLeave) {
+        const result = await route.beforeLeave(to, from, router);
+        if (isValidConfirmHookResult(result)) {
+          return result;
+        }
+      }
+    }
+  },
+  async beforeEnter(to, from, router) {
+    if (!to.matched.length) return;
+    const enteringRoutes = to.matched.filter(
+      (toRoute) => !(from == null ? void 0 : from.matched.some((fromRoute) => fromRoute === toRoute))
+    );
+    for (const route of enteringRoutes) {
+      if (route.beforeEnter) {
+        const result = await route.beforeEnter(to, from, router);
+        if (isValidConfirmHookResult(result)) {
+          return result;
+        }
+      }
+    }
+  },
+  async beforeUpdate(to, from, router) {
+    if (!isRouteMatched(to, from, "route")) return;
+    if (!from || to.matched.length !== from.matched.length) return;
+    const isSameRouteSet = to.matched.every(
+      (toRoute, index) => toRoute === from.matched[index]
+    );
+    if (!isSameRouteSet) return;
+    if (!isRouteMatched(to, from, "exact")) {
+      for (const route of to.matched) {
+        if (route.beforeUpdate) {
+          const result = await route.beforeUpdate(to, from, router);
+          if (isValidConfirmHookResult(result)) {
+            return result;
+          }
+        }
+      }
+    }
+  },
+  async beforeEach(to, from, router) {
+    const transition = router.transition;
+    for (const guard of transition.guards.beforeEach) {
+      const result = await guard(to, from, router);
+      if (isValidConfirmHookResult(result)) {
+        return result;
+      }
+    }
+  },
+  async confirm(to, from, router) {
+    if (to.confirm) {
+      const result = await to.confirm(to, from, router);
+      if (isValidConfirmHookResult(result)) {
+        return result;
+      }
+    }
+    if (isBrowser && "scrollRestoration" in window.history)
+      window.history.scrollRestoration = "manual";
+    if (from && isBrowser && !router.isLayer)
+      switch (to.type) {
+        case RouteType.push:
+        case RouteType.replace: {
+          if (!to.keepScrollPosition) {
+            saveScrollPosition(from.url.href);
+            scrollToPosition({ left: 0, top: 0 });
+          } else {
+            to.applyNavigationState({
+              __keepScrollPosition: to.keepScrollPosition
+            });
+          }
+          break;
+        }
+        case RouteType.go:
+        case RouteType.forward:
+        case RouteType.back:
+        // for popstate
+        case RouteType.unknown: {
+          saveScrollPosition(from.url.href);
+          setTimeout(async () => {
+            const state = window.history.state;
+            if (state == null ? void 0 : state.__keepScrollPosition) {
+              return;
+            }
+            const savedPosition = getSavedScrollPosition(
+              to.url.href,
+              { left: 0, top: 0 }
+            );
+            if (!savedPosition) return;
+            await router.parsedOptions.nextTick();
+            scrollToPosition(savedPosition);
+          });
+          break;
+        }
+      }
+    switch (to.type) {
+      case RouteType.push:
+        return ROUTE_TYPE_HANDLERS.push;
+      case RouteType.replace:
+        return ROUTE_TYPE_HANDLERS.replace;
+      case RouteType.restartApp:
+        return ROUTE_TYPE_HANDLERS.restartApp;
+      case RouteType.pushWindow:
+        return ROUTE_TYPE_HANDLERS.pushWindow;
+      case RouteType.replaceWindow:
+        return ROUTE_TYPE_HANDLERS.replaceWindow;
+      case RouteType.pushLayer:
+        return ROUTE_TYPE_HANDLERS.pushLayer;
+      default:
+        return ROUTE_TYPE_HANDLERS.default;
+    }
+  }
+};
+export const ROUTE_TYPE_HANDLERS = {
+  push(to, from, router) {
+    router.transition.route = to;
+    router.microApp._update(router);
+    if (!isUrlEqual(to.url, from == null ? void 0 : from.url)) {
+      const newState = router.navigation.push(to.state, to.url);
+      to.applyNavigationState(newState);
+    } else {
+      const newState = router.navigation.replace(to.state, to.url);
+      to.applyNavigationState(newState);
+    }
+  },
+  replace(to, from, router) {
+    router.transition.route = to;
+    router.microApp._update(router);
+    const newState = router.navigation.replace(to.state, to.url);
+    to.applyNavigationState(newState);
+  },
+  restartApp(to, from, router) {
+    router.transition.route = to;
+    router.microApp._update(router, true);
+    const newState = router.navigation.replace(to.state, to.url);
+    to.applyNavigationState(newState);
+  },
+  pushWindow(to, from, router) {
+    return router.parsedOptions.fallback(to, from, router);
+  },
+  replaceWindow(to, from, router) {
+    return router.parsedOptions.fallback(to, from, router);
+  },
+  async pushLayer(to, from, router) {
+    const { promise } = await router.createLayer(to);
+    return promise;
+  },
+  default(to, from, router) {
+    router.transition.route = to;
+    router.microApp._update(router);
+    if (!isUrlEqual(to.url, from == null ? void 0 : from.url)) {
+      const newState = router.navigation.replace(to.state, to.url);
+      to.applyNavigationState(newState);
+    }
+  }
+};
+const ROUTE_TRANSITION_PIPELINE = {
+  [RouteType.push]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    ROUTE_TRANSITION_HOOKS.override,
+    ROUTE_TRANSITION_HOOKS.beforeLeave,
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    ROUTE_TRANSITION_HOOKS.beforeUpdate,
+    ROUTE_TRANSITION_HOOKS.beforeEnter,
+    ROUTE_TRANSITION_HOOKS.asyncComponent,
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.replace]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    ROUTE_TRANSITION_HOOKS.override,
+    ROUTE_TRANSITION_HOOKS.beforeLeave,
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    ROUTE_TRANSITION_HOOKS.beforeUpdate,
+    ROUTE_TRANSITION_HOOKS.beforeEnter,
+    ROUTE_TRANSITION_HOOKS.asyncComponent,
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.pushWindow]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    ROUTE_TRANSITION_HOOKS.override,
+    // ROUTE_TRANSITION_HOOKS.beforeLeave
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    // ROUTE_TRANSITION_HOOKS.beforeUpdate
+    // ROUTE_TRANSITION_HOOKS.beforeEnter
+    // ROUTE_TRANSITION_HOOKS.asyncComponent
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.replaceWindow]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    ROUTE_TRANSITION_HOOKS.override,
+    ROUTE_TRANSITION_HOOKS.beforeLeave,
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    // ROUTE_TRANSITION_HOOKS.beforeUpdate
+    // ROUTE_TRANSITION_HOOKS.beforeEnter
+    // ROUTE_TRANSITION_HOOKS.asyncComponent
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.pushLayer]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    ROUTE_TRANSITION_HOOKS.override,
+    // ROUTE_TRANSITION_HOOKS.beforeLeave
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    // ROUTE_TRANSITION_HOOKS.beforeUpdate
+    // ROUTE_TRANSITION_HOOKS.beforeEnter
+    // ROUTE_TRANSITION_HOOKS.asyncComponent
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.restartApp]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    // ROUTE_TRANSITION_HOOKS.override,
+    ROUTE_TRANSITION_HOOKS.beforeLeave,
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    ROUTE_TRANSITION_HOOKS.beforeUpdate,
+    ROUTE_TRANSITION_HOOKS.beforeEnter,
+    ROUTE_TRANSITION_HOOKS.asyncComponent,
+    ROUTE_TRANSITION_HOOKS.confirm
+  ],
+  [RouteType.unknown]: [
+    ROUTE_TRANSITION_HOOKS.fallback,
+    // ROUTE_TRANSITION_HOOKS.override,
+    ROUTE_TRANSITION_HOOKS.beforeLeave,
+    ROUTE_TRANSITION_HOOKS.beforeEach,
+    ROUTE_TRANSITION_HOOKS.beforeUpdate,
+    ROUTE_TRANSITION_HOOKS.beforeEnter,
+    ROUTE_TRANSITION_HOOKS.asyncComponent,
+    ROUTE_TRANSITION_HOOKS.confirm
+  ]
+};
+export class RouteTransition {
+  constructor(router) {
+    __publicField(this, "router");
+    __publicField(this, "route", null);
+    // Task controller for the current transition.
+    __publicField(this, "_controller", null);
+    // Guard arrays, responsible for storing navigation guards.
+    __publicField(this, "guards", {
+      beforeEach: [],
+      afterEach: []
+    });
+    this.router = router;
+  }
+  beforeEach(guard) {
+    this.guards.beforeEach.push(guard);
+    return () => {
+      removeFromArray(this.guards.beforeEach, guard);
+    };
+  }
+  afterEach(guard) {
+    this.guards.afterEach.push(guard);
+    return () => {
+      removeFromArray(this.guards.afterEach, guard);
+    };
+  }
+  destroy() {
+    var _a;
+    (_a = this._controller) == null ? void 0 : _a.abort();
+    this._controller = null;
+  }
+  async to(toType, toInput) {
+    var _a;
+    const from = this.route;
+    const to = await this._runTask(
+      new Route({
+        options: this.router.parsedOptions,
+        toType,
+        toInput,
+        from: (_a = from == null ? void 0 : from.url) != null ? _a : null
+      }),
+      from
+    );
+    if (typeof to.handle === "function") {
+      to.handleResult = await to.handle(to, from, this.router);
+    }
+    if (to.handle) {
+      for (const guard of this.guards.afterEach) {
+        guard(to, from, this.router);
+      }
+    }
+    return to;
+  }
+  async _runTask(to, from) {
+    var _a;
+    (_a = this._controller) == null ? void 0 : _a.abort();
+    this._controller = new RouteTaskController();
+    const taskFunctions = ROUTE_TRANSITION_PIPELINE[to.type] || ROUTE_TRANSITION_PIPELINE[RouteType.unknown];
+    const tasks = taskFunctions.map((taskFn) => ({
+      name: taskFn.name,
+      task: taskFn
+    }));
+    return createRouteTask({
+      to,
+      from,
+      tasks,
+      controller: this._controller,
+      router: this.router
+    });
+  }
+}

package/dist/route.d.ts

@@ -0,0 +1,77 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type RouteConfirmHook, type RouteHandleHook, type RouteHandleResult, type RouteLayerOptions, type RouteLocationInput, type RouteMatchResult, type RouteMeta, type RouteOptions, type RouteParsedConfig, type RouteState, RouteType } from './types';
+/**
+ * Configuration for non-enumerable properties in Route class
+ * These properties will be hidden during object traversal and serialization
+ */
+export declare const NON_ENUMERABLE_PROPERTIES: string[];
+/**
+ * Append user-provided parameters to URL path
+ * @param match Route matching result
+ * @param toInput User-provided route location object
+ * @param base Base URL
+ * @param to Current parsed URL object
+ */
+export declare function applyRouteParams(match: RouteMatchResult, toInput: RouteLocationInput, base: URL, to: URL): void;
+/**
+ * Route class provides complete route object functionality
+ */
+export declare class Route {
+    private _handled;
+    private _handle;
+    private _handleResult;
+    private readonly _options;
+    readonly statusCode: number | null;
+    readonly state: RouteState;
+    readonly keepScrollPosition: boolean;
+    /** Custom confirm handler that overrides default route-transition confirm logic */
+    readonly confirm: RouteConfirmHook | null;
+    /** Layer configuration for layer routes */
+    readonly layer: RouteLayerOptions | null;
+    readonly type: RouteType;
+    readonly req: IncomingMessage | null;
+    readonly res: ServerResponse | null;
+    readonly context: Record<string | symbol, any>;
+    readonly url: URL;
+    readonly path: string;
+    readonly fullPath: string;
+    readonly hash: string;
+    readonly params: Record<string, string>;
+    readonly paramsArray: Record<string, string[]>;
+    readonly query: Record<string, string | undefined>;
+    readonly queryArray: Record<string, string[] | undefined>;
+    readonly meta: RouteMeta;
+    readonly matched: readonly RouteParsedConfig[];
+    readonly config: RouteParsedConfig | null;
+    /** @deprecated Use `url.pathname` instead. */
+    get pathname(): string;
+    /** @deprecated Use `url.href` instead. */
+    get href(): string;
+    constructor(routeOptions?: Partial<RouteOptions>);
+    get isPush(): boolean;
+    get handle(): RouteHandleHook | null;
+    set handle(val: RouteHandleHook | null);
+    get handleResult(): RouteHandleResult | null;
+    set handleResult(val: RouteHandleResult | null);
+    /**
+     * Set handle function with validation logic wrapper
+     */
+    setHandle(val: RouteHandleHook | null): void;
+    /**
+     * Apply navigation-generated state to current route
+     * Used by route handlers to add system state like pageId
+     * @param navigationState Navigation-generated state to apply
+     */
+    applyNavigationState(navigationState: Partial<RouteState>): void;
+    /**
+     * Sync all properties of current route to target route object
+     * Used for route object updates in reactive systems
+     * @param targetRoute Target route object
+     */
+    syncTo(targetRoute: Route): void;
+    /**
+     * Clone current route instance
+     * Returns a new Route instance with same configuration and state
+     */
+    clone(): Route;
+}

package/dist/route.mjs

@@ -0,0 +1,223 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+import { parseLocation, resolveRouteLocationInput } from "./location.mjs";
+import { parsedOptions } from "./options.mjs";
+import {
+  RouteType
+} from "./types.mjs";
+import { decodeParams, isNonEmptyPlainObject, isPlainObject } from "./util.mjs";
+export const NON_ENUMERABLE_PROPERTIES = [
+  // Private fields - internal implementation details
+  "_handled",
+  "_handle",
+  "_handleResult",
+  "_options",
+  // SSR-specific properties - meaningless in client environment
+  "req",
+  "res",
+  // Internal context - used by framework internally
+  "context",
+  // Status code - internal status information
+  "statusCode",
+  // Route behavior overrides - framework internal logic
+  "confirm",
+  // Layer configuration - used for layer routes
+  "layer"
+];
+export function applyRouteParams(match, toInput, base, to) {
+  if (!isPlainObject(toInput) || !isNonEmptyPlainObject(toInput.params) || !match.matches.length) {
+    return;
+  }
+  const lastMatch = match.matches[match.matches.length - 1];
+  const current = to.pathname.split("/");
+  const next = new URL(
+    lastMatch.compile(toInput.params).substring(1),
+    base
+  ).pathname.split("/");
+  next.forEach((item, index) => {
+    current[index] = item || current[index];
+  });
+  to.pathname = current.join("/");
+  Object.assign(match.params, toInput.params);
+}
+export class Route {
+  constructor(routeOptions = {}) {
+    // Private fields for handle validation
+    __publicField(this, "_handled", false);
+    __publicField(this, "_handle", null);
+    __publicField(this, "_handleResult", null);
+    __publicField(this, "_options");
+    // Public properties
+    __publicField(this, "statusCode", null);
+    __publicField(this, "state");
+    __publicField(this, "keepScrollPosition");
+    /** Custom confirm handler that overrides default route-transition confirm logic */
+    __publicField(this, "confirm");
+    /** Layer configuration for layer routes */
+    __publicField(this, "layer");
+    // Read-only properties
+    __publicField(this, "type");
+    __publicField(this, "req");
+    __publicField(this, "res");
+    __publicField(this, "context");
+    __publicField(this, "url");
+    __publicField(this, "path");
+    __publicField(this, "fullPath");
+    __publicField(this, "hash");
+    __publicField(this, "params", {});
+    __publicField(this, "paramsArray", {});
+    __publicField(this, "query", {});
+    __publicField(this, "queryArray", {});
+    __publicField(this, "meta");
+    __publicField(this, "matched");
+    __publicField(this, "config");
+    var _a;
+    const {
+      toType = RouteType.push,
+      from = null,
+      options = parsedOptions()
+    } = routeOptions;
+    this._options = options;
+    this.type = toType;
+    this.req = options.req;
+    this.res = options.res;
+    this.context = options.context;
+    const base = options.base;
+    const toInput = resolveRouteLocationInput(routeOptions.toInput, from);
+    const to = options.normalizeURL(parseLocation(toInput, base), from);
+    let match = null;
+    if (to.origin === base.origin && to.pathname.startsWith(base.pathname)) {
+      const isLayer = toType === RouteType.pushLayer || options.layer;
+      match = options.matcher(to, base, (config) => {
+        if (isLayer) {
+          return config.layer !== false;
+        }
+        return config.layer !== true;
+      });
+    }
+    if (match) {
+      applyRouteParams(match, toInput, base, to);
+      const decodedParams = decodeParams(match.params);
+      for (const key in decodedParams) {
+        const value = decodedParams[key];
+        if (Array.isArray(value)) {
+          this.params[key] = value[0] || "";
+          this.paramsArray[key] = value;
+        } else {
+          this.params[key] = value;
+          this.paramsArray[key] = [value];
+        }
+      }
+    }
+    this.url = to;
+    this.path = match ? to.pathname.substring(base.pathname.length - 1) : to.pathname;
+    this.fullPath = (match ? this.path : to.pathname) + to.search + to.hash;
+    this.matched = match ? match.matches : Object.freeze([]);
+    this.keepScrollPosition = Boolean(toInput.keepScrollPosition);
+    this.confirm = toInput.confirm || null;
+    this.layer = toType === RouteType.pushLayer && toInput.layer ? toInput.layer : null;
+    this.config = this.matched.length > 0 ? this.matched[this.matched.length - 1] : null;
+    this.meta = ((_a = this.config) == null ? void 0 : _a.meta) || {};
+    const state = {};
+    if (toInput.state) {
+      Object.assign(state, toInput.state);
+    }
+    this.state = state;
+    for (const key of new Set(to.searchParams.keys())) {
+      this.query[key] = to.searchParams.get(key);
+      this.queryArray[key] = to.searchParams.getAll(key);
+    }
+    this.hash = to.hash;
+    if (typeof toInput.statusCode === "number") {
+      this.statusCode = toInput.statusCode;
+    }
+    for (const property of NON_ENUMERABLE_PROPERTIES) {
+      Object.defineProperty(this, property, { enumerable: false });
+    }
+  }
+  /** @deprecated Use `url.pathname` instead. */
+  get pathname() {
+    return this.url.pathname;
+  }
+  /** @deprecated Use `url.href` instead. */
+  get href() {
+    return this.url.href;
+  }
+  get isPush() {
+    return this.type.startsWith("push");
+  }
+  // handle related getter/setter
+  get handle() {
+    return this._handle;
+  }
+  set handle(val) {
+    this.setHandle(val);
+  }
+  get handleResult() {
+    return this._handleResult;
+  }
+  set handleResult(val) {
+    this._handleResult = val;
+  }
+  /**
+   * Set handle function with validation logic wrapper
+   */
+  setHandle(val) {
+    if (typeof val !== "function") {
+      this._handle = null;
+      return;
+    }
+    const self = this;
+    this._handle = function handle(to, from, router) {
+      if (self._handled) {
+        throw new Error(
+          "Route handle hook can only be called once per navigation"
+        );
+      }
+      self._handled = true;
+      return val.call(this, to, from, router);
+    };
+  }
+  /**
+   * Apply navigation-generated state to current route
+   * Used by route handlers to add system state like pageId
+   * @param navigationState Navigation-generated state to apply
+   */
+  applyNavigationState(navigationState) {
+    Object.assign(this.state, navigationState);
+  }
+  /**
+   * Sync all properties of current route to target route object
+   * Used for route object updates in reactive systems
+   * @param targetRoute Target route object
+   */
+  syncTo(targetRoute) {
+    Object.assign(targetRoute, this);
+    for (const property of NON_ENUMERABLE_PROPERTIES) {
+      if (!(property in this && property in targetRoute)) continue;
+      const value = Reflect.get(this, property);
+      Reflect.set(targetRoute, property, value);
+    }
+  }
+  /**
+   * Clone current route instance
+   * Returns a new Route instance with same configuration and state
+   */
+  clone() {
+    const toInput = {
+      path: this.fullPath,
+      state: { ...this.state },
+      ...this.confirm && { confirm: this.confirm },
+      ...this.layer && { layer: this.layer },
+      ...this.statusCode !== null && { statusCode: this.statusCode }
+    };
+    const options = this._options;
+    const clonedRoute = new Route({
+      options,
+      toType: this.type,
+      toInput
+    });
+    return clonedRoute;
+  }
+}

package/dist/router-link.d.ts

@@ -0,0 +1,10 @@
+import type { Router } from './router';
+import type { RouterLinkProps, RouterLinkResolved } from './types';
+/**
+ * Framework-agnostic link resolver
+ *
+ * @param router Router instance
+ * @param props Link configuration
+ * @returns Resolution result
+ */
+export declare function createLinkResolver(router: Router, props: RouterLinkProps): RouterLinkResolved;