@esmx/router 3.0.0-rc.103

package/dist/router-link.mjs

@@ -0,0 +1,139 @@
+const CSS_CLASSES = {
+  BASE: "router-link",
+  ACTIVE: "router-link-active",
+  EXACT_ACTIVE: "router-link-exact-active"
+};
+function normalizeNavigationType(props) {
+  if (props.replace) {
+    console.warn(
+      '[RouterLink] The `replace` property is deprecated and will be removed in a future version.\nPlease use `type="replace"` instead.\nBefore: <RouterLink replace={true} />\nAfter:  <RouterLink type="replace" />'
+    );
+    return "replace";
+  }
+  return props.type || "push";
+}
+function getEventTypeList(eventType) {
+  const events = Array.isArray(eventType) ? eventType : [eventType];
+  const validEvents = events.filter((type) => typeof type === "string").map((type) => type.trim()).filter(Boolean);
+  return validEvents.length ? validEvents : ["click"];
+}
+function shouldHandleNavigation(e) {
+  var _a;
+  if (e.defaultPrevented) return false;
+  if (e instanceof MouseEvent) {
+    if (e.metaKey || e.altKey || e.ctrlKey || e.shiftKey) return false;
+    if (e.button !== void 0 && e.button !== 0) return false;
+  }
+  (_a = e.preventDefault) == null ? void 0 : _a.call(e);
+  return true;
+}
+async function executeNavigation(router, props, linkType) {
+  const { to, layerOptions } = props;
+  switch (linkType) {
+    case "push":
+      await router.push(to);
+      break;
+    case "replace":
+      await router.replace(to);
+      break;
+    case "pushWindow":
+      await router.pushWindow(to);
+      break;
+    case "replaceWindow":
+      await router.replaceWindow(to);
+      break;
+    case "pushLayer":
+      await router.pushLayer(
+        layerOptions ? typeof to === "string" ? { path: to, layer: layerOptions } : { ...to, layer: layerOptions } : to
+      );
+      break;
+    default:
+      await router.push(to);
+  }
+}
+function createNavigateFunction(router, props, navigationType) {
+  return async (e) => {
+    if (shouldHandleNavigation(e)) {
+      await executeNavigation(router, props, navigationType);
+    }
+  };
+}
+function computeAttributes(href, navigationType, isExternal, isActive, isExactActive, activeClass) {
+  const isNewWindow = navigationType === "pushWindow";
+  const classes = [CSS_CLASSES.BASE];
+  if (isActive) {
+    classes.push(activeClass || CSS_CLASSES.ACTIVE);
+  }
+  if (isExactActive) {
+    classes.push(CSS_CLASSES.EXACT_ACTIVE);
+  }
+  const attributes = {
+    href,
+    class: classes.join(" ")
+  };
+  if (isNewWindow) {
+    attributes.target = "_blank";
+  }
+  const relParts = [];
+  if (isNewWindow) {
+    relParts.push("noopener", "noreferrer");
+  }
+  if (isExternal) {
+    relParts.push("external", "nofollow");
+  }
+  if (relParts.length > 0) {
+    attributes.rel = relParts.join(" ");
+  }
+  return attributes;
+}
+function createEventHandlersGenerator(router, props, navigationType, eventTypes) {
+  return (format) => {
+    const handlers = {};
+    const navigate = createNavigateFunction(router, props, navigationType);
+    eventTypes.forEach((eventType) => {
+      var _a;
+      const eventName = (_a = format == null ? void 0 : format(eventType)) != null ? _a : eventType.toLowerCase();
+      handlers[eventName] = (event) => {
+        var _a2;
+        (_a2 = props.beforeNavigate) == null ? void 0 : _a2.call(props, event, eventType);
+        return navigate(event);
+      };
+    });
+    return handlers;
+  };
+}
+export function createLinkResolver(router, props) {
+  const route = router.resolve(props.to);
+  const type = normalizeNavigationType(props);
+  const href = route.url.href;
+  const isActive = router.isRouteMatched(route, props.exact);
+  const isExactActive = router.isRouteMatched(route, "exact");
+  const isExternal = route.url.origin !== router.route.url.origin;
+  const attributes = computeAttributes(
+    href,
+    type,
+    isExternal,
+    isActive,
+    isExactActive,
+    props.activeClass
+  );
+  const eventTypes = getEventTypeList(props.event || "click");
+  const createEventHandlers = createEventHandlersGenerator(
+    router,
+    props,
+    type,
+    eventTypes
+  );
+  const navigate = createNavigateFunction(router, props, type);
+  return {
+    route,
+    type,
+    isActive,
+    isExactActive,
+    isExternal,
+    tag: props.tag || "a",
+    attributes,
+    navigate,
+    createEventHandlers
+  };
+}

package/dist/router.d.ts

@@ -0,0 +1,122 @@
+import { MicroApp } from './micro-app';
+import { Navigation } from './navigation';
+import { Route } from './route';
+import { RouteTransition } from './route-transition';
+import type { RouteConfirmHook, RouteLayerResult, RouteLocationInput, RouteMatchType, RouteNotifyHook, RouterLinkProps, RouterLinkResolved, RouterOptions, RouterParsedOptions } from './types';
+import { RouterMode, RouteType } from './types';
+export declare class Router {
+    readonly options: RouterOptions;
+    readonly parsedOptions: RouterParsedOptions;
+    readonly isLayer: boolean;
+    readonly navigation: Navigation;
+    readonly microApp: MicroApp;
+    readonly transition: RouteTransition;
+    get route(): Route;
+    get context(): Record<string | symbol, unknown>;
+    get data(): Record<string | symbol, unknown>;
+    get root(): string | HTMLElement;
+    get mode(): RouterMode;
+    get base(): URL;
+    get req(): import("http").IncomingMessage | null;
+    get res(): import("http").ServerResponse<import("http").IncomingMessage> | null;
+    constructor(options: RouterOptions);
+    push(toInput: RouteLocationInput): Promise<Route>;
+    replace(toInput: RouteLocationInput): Promise<Route>;
+    pushWindow(toInput: RouteLocationInput): Promise<Route>;
+    replaceWindow(toInput: RouteLocationInput): Promise<Route>;
+    restartApp(toInput?: RouteLocationInput): Promise<Route>;
+    back(): Promise<Route | null>;
+    go(index: number): Promise<Route | null>;
+    forward(): Promise<Route | null>;
+    /**
+     * Parse route location without performing actual navigation
+     *
+     * This method is used to parse route configuration and return the corresponding route object,
+     * but does not trigger actual page navigation. It is mainly used for the following scenarios:
+     * - Generate link URLs without jumping
+     * - Pre-check route matching
+     * - Get route parameters, meta information, etc.
+     * - Test the validity of route configuration
+     *
+     * @param toInput Target route location, can be a string path or route configuration object
+     * @returns Parsed route object containing complete route information
+     *
+     * @example
+     * ```typescript
+     * // Parse string path
+     * const route = router.resolve('/user/123');
+     * const url = route.url.href; // Get complete URL
+     *
+     * // Parse named route
+     * const userRoute = router.resolve({
+     *   name: 'user',
+     *   params: { id: '123' }
+     * });
+     * console.log(userRoute.params.id); // '123'
+     *
+     * // Check route validity
+     * const testRoute = router.resolve('/some/path');
+     * if (testRoute.matched.length > 0) {
+     *   // Route matched successfully
+     * }
+     * ```
+     */
+    resolve(toInput: RouteLocationInput, toType?: RouteType): Route;
+    /**
+     * Check if the route matches the current route
+     *
+     * @param toRoute Target route object to compare
+     * @param matchType Match type
+     * - 'route': Route-level matching, compare if route configurations are the same
+     * - 'exact': Exact matching, compare if paths are completely the same
+     * - 'include': Include matching, check if current path contains target path
+     * @returns Whether it matches
+     */
+    isRouteMatched(toRoute: Route, matchType?: RouteMatchType): boolean;
+    /**
+     * Resolve router link configuration and return complete link data
+     *
+     * This method analyzes router link properties and returns a comprehensive
+     * link resolution result including route information, navigation functions,
+     * HTML attributes, and event handlers. It's primarily used for:
+     * - Framework-agnostic link component implementation
+     * - Generating link attributes and navigation handlers
+     * - Computing active states and CSS classes
+     * - Creating event handlers for different frameworks
+     *
+     * @param props Router link configuration properties
+     * @returns Complete link resolution result with all necessary data
+     *
+     * @example
+     * ```typescript
+     * // Basic link resolution
+     * const linkData = router.resolveLink({
+     *   to: '/user/123',
+     *   type: 'push'
+     * });
+     *
+     * // Access resolved data
+     * console.log(linkData.route.path); // '/user/123'
+     * console.log(linkData.attributes.href); // Full href URL
+     * console.log(linkData.isActive); // Active state
+     *
+     * // Use navigation function
+     * linkData.navigate(); // Programmatic navigation
+     *
+     * // Get event handlers for React
+     * const handlers = linkData.createEventHandlers(name => `on${name.charAt(0).toUpperCase() + name.slice(1)}`);
+     * // handlers.onClick for React
+     * ```
+     */
+    resolveLink(props: RouterLinkProps): RouterLinkResolved;
+    createLayer(toInput: RouteLocationInput): Promise<{
+        promise: Promise<RouteLayerResult>;
+        router: Router;
+    }>;
+    pushLayer(toInput: RouteLocationInput): Promise<RouteLayerResult>;
+    closeLayer(data?: any): void;
+    renderToString(throwError?: boolean): Promise<string | null>;
+    beforeEach(guard: RouteConfirmHook): () => void;
+    afterEach(guard: RouteNotifyHook): () => void;
+    destroy(): void;
+}

package/dist/router.mjs

@@ -0,0 +1,355 @@
+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 { LAYER_ID } from "./increment-id.mjs";
+import { MicroApp } from "./micro-app.mjs";
+import { Navigation } from "./navigation.mjs";
+import { parsedOptions } from "./options.mjs";
+import { Route } from "./route.mjs";
+import { RouteTransition } from "./route-transition.mjs";
+import { createLinkResolver } from "./router-link.mjs";
+import { RouterMode, RouteType } from "./types.mjs";
+import { isNotNullish, isPlainObject, isRouteMatched } from "./util.mjs";
+export class Router {
+  constructor(options) {
+    __publicField(this, "options");
+    __publicField(this, "parsedOptions");
+    __publicField(this, "isLayer");
+    __publicField(this, "navigation");
+    __publicField(this, "microApp", new MicroApp());
+    // Route transition manager
+    __publicField(this, "transition", new RouteTransition(this));
+    this.options = options;
+    this.parsedOptions = parsedOptions(options);
+    this.isLayer = this.parsedOptions.layer;
+    this.navigation = new Navigation(
+      this.parsedOptions,
+      (url, state) => {
+        this.transition.to(RouteType.unknown, {
+          url,
+          state
+        });
+      }
+    );
+  }
+  get route() {
+    const route = this.transition.route;
+    if (route === null) {
+      throw new Error(
+        "No active route found. Please navigate to a route first using router.push() or router.replace()."
+      );
+    }
+    return route;
+  }
+  get context() {
+    return this.parsedOptions.context;
+  }
+  get data() {
+    return this.parsedOptions.data;
+  }
+  get root() {
+    return this.parsedOptions.root;
+  }
+  get mode() {
+    return this.parsedOptions.mode;
+  }
+  get base() {
+    return this.parsedOptions.base;
+  }
+  get req() {
+    var _a;
+    return (_a = this.parsedOptions.req) != null ? _a : null;
+  }
+  get res() {
+    var _a;
+    return (_a = this.parsedOptions.res) != null ? _a : null;
+  }
+  push(toInput) {
+    return this.transition.to(RouteType.push, toInput);
+  }
+  replace(toInput) {
+    return this.transition.to(RouteType.replace, toInput);
+  }
+  pushWindow(toInput) {
+    return this.transition.to(RouteType.pushWindow, toInput);
+  }
+  replaceWindow(toInput) {
+    return this.transition.to(RouteType.replaceWindow, toInput);
+  }
+  restartApp(toInput) {
+    return this.transition.to(
+      RouteType.restartApp,
+      toInput != null ? toInput : this.route.url.href
+    );
+  }
+  async back() {
+    const result = await this.navigation.go(-1);
+    if (result === null) {
+      this.parsedOptions.handleBackBoundary(this);
+      return null;
+    }
+    return this.transition.to(RouteType.back, {
+      url: result.url,
+      state: result.state
+    });
+  }
+  async go(index) {
+    if (index === 0) return null;
+    const result = await this.navigation.go(index);
+    if (result === null) {
+      if (index < 0) {
+        this.parsedOptions.handleBackBoundary(this);
+      }
+      return null;
+    }
+    return this.transition.to(RouteType.go, {
+      url: result.url,
+      state: result.state
+    });
+  }
+  async forward() {
+    const result = await this.navigation.go(1);
+    if (result === null) return null;
+    return this.transition.to(RouteType.forward, {
+      url: result.url,
+      state: result.state
+    });
+  }
+  /**
+   * Parse route location without performing actual navigation
+   *
+   * This method is used to parse route configuration and return the corresponding route object,
+   * but does not trigger actual page navigation. It is mainly used for the following scenarios:
+   * - Generate link URLs without jumping
+   * - Pre-check route matching
+   * - Get route parameters, meta information, etc.
+   * - Test the validity of route configuration
+   *
+   * @param toInput Target route location, can be a string path or route configuration object
+   * @returns Parsed route object containing complete route information
+   *
+   * @example
+   * ```typescript
+   * // Parse string path
+   * const route = router.resolve('/user/123');
+   * const url = route.url.href; // Get complete URL
+   *
+   * // Parse named route
+   * const userRoute = router.resolve({
+   *   name: 'user',
+   *   params: { id: '123' }
+   * });
+   * console.log(userRoute.params.id); // '123'
+   *
+   * // Check route validity
+   * const testRoute = router.resolve('/some/path');
+   * if (testRoute.matched.length > 0) {
+   *   // Route matched successfully
+   * }
+   * ```
+   */
+  resolve(toInput, toType) {
+    var _a, _b;
+    return new Route({
+      options: this.parsedOptions,
+      toType,
+      toInput,
+      from: (_b = (_a = this.transition.route) == null ? void 0 : _a.url) != null ? _b : null
+    });
+  }
+  /**
+   * Check if the route matches the current route
+   *
+   * @param toRoute Target route object to compare
+   * @param matchType Match type
+   * - 'route': Route-level matching, compare if route configurations are the same
+   * - 'exact': Exact matching, compare if paths are completely the same
+   * - 'include': Include matching, check if current path contains target path
+   * @returns Whether it matches
+   */
+  isRouteMatched(toRoute, matchType = "include") {
+    const currentRoute = this.transition.route;
+    if (!currentRoute) return false;
+    return isRouteMatched(currentRoute, toRoute, matchType);
+  }
+  /**
+   * Resolve router link configuration and return complete link data
+   *
+   * This method analyzes router link properties and returns a comprehensive
+   * link resolution result including route information, navigation functions,
+   * HTML attributes, and event handlers. It's primarily used for:
+   * - Framework-agnostic link component implementation
+   * - Generating link attributes and navigation handlers
+   * - Computing active states and CSS classes
+   * - Creating event handlers for different frameworks
+   *
+   * @param props Router link configuration properties
+   * @returns Complete link resolution result with all necessary data
+   *
+   * @example
+   * ```typescript
+   * // Basic link resolution
+   * const linkData = router.resolveLink({
+   *   to: '/user/123',
+   *   type: 'push'
+   * });
+   *
+   * // Access resolved data
+   * console.log(linkData.route.path); // '/user/123'
+   * console.log(linkData.attributes.href); // Full href URL
+   * console.log(linkData.isActive); // Active state
+   *
+   * // Use navigation function
+   * linkData.navigate(); // Programmatic navigation
+   *
+   * // Get event handlers for React
+   * const handlers = linkData.createEventHandlers(name => `on${name.charAt(0).toUpperCase() + name.slice(1)}`);
+   * // handlers.onClick for React
+   * ```
+   */
+  resolveLink(props) {
+    return createLinkResolver(this, props);
+  }
+  async createLayer(toInput) {
+    var _a;
+    const layerOptions = isPlainObject(toInput) && toInput.layer || {};
+    const zIndex = (_a = layerOptions.zIndex) != null ? _a : this.parsedOptions.zIndex + LAYER_ID.next();
+    let promiseResolve;
+    let promise = new Promise((resolve) => {
+      promiseResolve = resolve;
+    });
+    const router = new Router({
+      rootStyle: {
+        position: "fixed",
+        top: "0",
+        left: "0",
+        width: "100%",
+        height: "100%",
+        zIndex: String(zIndex),
+        background: "rgba(0,0,0,.6)",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center"
+      },
+      ...this.options,
+      context: this.parsedOptions.context,
+      mode: RouterMode.memory,
+      root: void 0,
+      ...layerOptions.routerOptions,
+      handleBackBoundary(router2) {
+        router2.destroy();
+        promiseResolve({
+          type: "close",
+          route: router2.route
+        });
+      },
+      handleLayerClose(router2, data) {
+        router2.destroy();
+        if (isNotNullish(data)) {
+          promiseResolve({
+            type: "success",
+            route: router2.route,
+            data
+          });
+        } else {
+          promiseResolve({
+            type: "close",
+            route: router2.route
+          });
+        }
+      },
+      layer: true
+    });
+    const initRoute = await router.replace(toInput);
+    router.afterEach(async (to, from) => {
+      if (![
+        RouteType.pushWindow,
+        RouteType.replaceWindow,
+        RouteType.replace,
+        RouteType.restartApp,
+        RouteType.pushLayer
+      ].includes(to.type))
+        return;
+      let keepAlive = false;
+      if (layerOptions.keepAlive === "exact") {
+        keepAlive = to.path === initRoute.path;
+      } else if (layerOptions.keepAlive === "include") {
+        keepAlive = to.path.startsWith(initRoute.path);
+      } else if (typeof layerOptions.keepAlive === "function") {
+        keepAlive = await layerOptions.keepAlive(to, from, router);
+      } else {
+        if (layerOptions.shouldClose) {
+          console.warn(
+            "[esmx-router] RouteLayerOptions.shouldClose is deprecated. Use keepAlive instead. Note: shouldClose returns true to close, keepAlive returns true to keep alive."
+          );
+          keepAlive = !await layerOptions.shouldClose(
+            to,
+            from,
+            router
+          );
+        } else {
+          keepAlive = to.path === initRoute.path;
+        }
+      }
+      if (!keepAlive) {
+        router.destroy();
+        promiseResolve({
+          type: "push",
+          route: to
+        });
+      }
+    });
+    if (layerOptions.push) {
+      router.navigation.pushHistoryState(
+        router.route.state,
+        router.route.url
+      );
+      promise = promise.then(async (result) => {
+        await this.navigation.backHistoryState();
+        return result;
+      });
+    }
+    if (layerOptions.autoPush) {
+      promise = promise.then(async (result) => {
+        if (result.type === "push") {
+          await this.push(result.route.url.href);
+        }
+        return result;
+      });
+    }
+    return {
+      promise,
+      router
+    };
+  }
+  async pushLayer(toInput) {
+    const result = await this.transition.to(RouteType.pushLayer, toInput);
+    return result.handleResult;
+  }
+  closeLayer(data) {
+    if (!this.isLayer) return;
+    this.parsedOptions.handleLayerClose(this, data);
+  }
+  async renderToString(throwError = false) {
+    var _a, _b;
+    try {
+      const result = await ((_b = (_a = this.microApp.app) == null ? void 0 : _a.renderToString) == null ? void 0 : _b.call(_a));
+      return result != null ? result : null;
+    } catch (e) {
+      if (throwError) throw e;
+      else console.error(e);
+      return null;
+    }
+  }
+  beforeEach(guard) {
+    return this.transition.beforeEach(guard);
+  }
+  afterEach(guard) {
+    return this.transition.afterEach(guard);
+  }
+  destroy() {
+    this.transition.destroy();
+    this.navigation.destroy();
+    this.microApp.destroy();
+  }
+}

package/dist/scroll.d.ts

@@ -0,0 +1,33 @@
+/** Internal {@link ScrollToOptions | `ScrollToOptions`}: `left` and `top` properties always have values */
+interface _ScrollPosition extends ScrollToOptions {
+    left: number;
+    top: number;
+}
+export interface ScrollPositionElement extends ScrollToOptions {
+    /**
+     * A valid CSS selector. Some special characters need to be escaped (https://mathiasbynens.be/notes/css-escapes).
+     * @example
+     * Here are some examples:
+     *
+     * - `.title`
+     * - `.content:first-child`
+     * - `#marker`
+     * - `#marker\~with\~symbols`
+     * - `#marker.with.dot`: Selects `class="with dot" id="marker"`, not `id="marker.with.dot"`
+     *
+     */
+    el: string | Element;
+}
+/** Scroll parameters */
+export type ScrollPosition = ScrollToOptions | ScrollPositionElement;
+/** Get current window scroll position */
+export declare const winScrollPos: () => _ScrollPosition;
+/** Scroll to specified position */
+export declare function scrollToPosition(position: ScrollPosition): void;
+/** Stored scroll positions */
+export declare const scrollPositions: Map<string, _ScrollPosition>;
+/** Save scroll position */
+export declare function saveScrollPosition(key: string, scrollPosition?: _ScrollPosition): void;
+/** Get saved scroll position */
+export declare function getSavedScrollPosition(key: string, defaultValue?: _ScrollPosition | null): _ScrollPosition | null;
+export {};

package/dist/scroll.mjs

@@ -0,0 +1,49 @@
+export const winScrollPos = () => ({
+  left: window.scrollX,
+  top: window.scrollY
+});
+function getElementPosition(el, offset) {
+  const docRect = document.documentElement.getBoundingClientRect();
+  const elRect = el.getBoundingClientRect();
+  return {
+    behavior: offset.behavior,
+    left: elRect.left - docRect.left - (offset.left || 0),
+    top: elRect.top - docRect.top - (offset.top || 0)
+  };
+}
+export function scrollToPosition(position) {
+  if ("el" in position) {
+    const positionEl = position.el;
+    const el = typeof positionEl === "string" ? document.querySelector(positionEl) : positionEl;
+    if (!el) return;
+    position = getElementPosition(el, position);
+  }
+  if ("scrollBehavior" in document.documentElement.style) {
+    window.scrollTo(position);
+  } else {
+    window.scrollTo(
+      Number.isFinite(position.left) ? position.left : window.scrollX,
+      Number.isFinite(position.top) ? position.top : window.scrollY
+    );
+  }
+}
+export const scrollPositions = /* @__PURE__ */ new Map();
+const POSITION_KEY = "__scroll_position_key";
+export function saveScrollPosition(key, scrollPosition = winScrollPos()) {
+  scrollPosition = { ...scrollPosition };
+  scrollPositions.set(key, scrollPosition);
+  try {
+    if (location.href !== key) return;
+    const stateCopy = {
+      ...history.state || {},
+      [POSITION_KEY]: scrollPosition
+    };
+    history.replaceState(stateCopy, "");
+  } catch (error) {
+  }
+}
+export function getSavedScrollPosition(key, defaultValue = null) {
+  const scroll = scrollPositions.get(key) || history.state[POSITION_KEY];
+  scrollPositions.delete(key);
+  return scroll || defaultValue;
+}