@esmx/router 3.0.0-rc.12 → 3.0.0-rc.120

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,50 @@
+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) {
+  var _a;
+  const scroll = scrollPositions.get(key) || ((_a = history.state) == null ? void 0 : _a[POSITION_KEY]);
+  scrollPositions.delete(key);
+  return scroll || defaultValue;
+}

package/dist/types.d.ts

@@ -0,0 +1,312 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { MatchFunction } from 'path-to-regexp';
+import type { Route } from './route';
+import type { Router } from './router';
+export type { Route };
+export type Awaitable<T> = T | Promise<T>;
+export declare enum RouterMode {
+    history = "history",
+    memory = "memory"
+}
+export declare enum RouteType {
+    push = "push",
+    replace = "replace",
+    restartApp = "restartApp",
+    go = "go",
+    forward = "forward",
+    back = "back",
+    unknown = "unknown",
+    pushWindow = "pushWindow",
+    replaceWindow = "replaceWindow",
+    pushLayer = "pushLayer"
+}
+export type RouteConfirmHookResult = void | false | RouteLocationInput | RouteHandleHook;
+export type RouteConfirmHook = (to: Route, from: Route | null, router: Router) => Awaitable<RouteConfirmHookResult>;
+export type RouteVerifyHook = (to: Route, from: Route | null, router: Router) => Awaitable<boolean>;
+export type RouteHandleHook = (to: Route, from: Route | null, router: Router) => Awaitable<RouteHandleResult>;
+export type RouteNotifyHook = (to: Route, from: Route | null, router: Router) => void;
+export type RouteMeta = Record<string | symbol, unknown>;
+export type RouteState = Record<string, unknown>;
+export type RouteHandleResult = unknown | null | void;
+/**
+ * Route matching type
+ * - 'route': Route-level matching, compare if route configurations are the same
+ * - 'exact': Exact matching, compare if paths are exactly the same
+ * - 'include': Include matching, check if current path contains target path
+ */
+export type RouteMatchType = 'route' | 'exact' | 'include';
+export interface RouteLocation {
+    path?: string;
+    url?: string | URL;
+    params?: Record<string, string>;
+    query?: Record<string, string | undefined>;
+    queryArray?: Record<string, string[] | undefined>;
+    hash?: string;
+    state?: RouteState;
+    /** When `true`, maintains current scroll position after navigation (default behavior scrolls to top) */
+    keepScrollPosition?: boolean;
+    statusCode?: number | null;
+    layer?: RouteLayerOptions | null;
+    confirm?: RouteConfirmHook | null;
+}
+export type RouteLocationInput = RouteLocation | string;
+export interface RouteConfig {
+    /** Pass a URL-encoded path */
+    path: string;
+    component?: unknown;
+    children?: RouteConfig[];
+    redirect?: RouteLocationInput | RouteConfirmHook;
+    meta?: RouteMeta;
+    app?: string | RouterMicroAppCallback;
+    asyncComponent?: () => Promise<unknown>;
+    beforeEnter?: RouteConfirmHook;
+    beforeUpdate?: RouteConfirmHook;
+    beforeLeave?: RouteConfirmHook;
+    /** Mark this route as only effective in layer mode */
+    layer?: boolean;
+    /**
+     * Require an index child route to match the parent path
+     *
+     * When set to `true`, the parent route will not match its own path
+     * if no child route matches. The parent route requires a `path: ''`
+     * index child route to match the parent path itself.
+     *
+     * - `requireIndex: false` (default): If no child route matches,
+     *   the matcher falls back to matching the parent route itself
+     * - `requireIndex: true`: If no child route matches, the parent
+     *   route is skipped entirely (no fallback to self-match)
+     *
+     * @default false
+     *
+     * @example
+     * ```typescript
+     * // requireIndex: true - /A won't match without index child
+     * {
+     *   path: '/A',
+     *   requireIndex: true,
+     *   children: [
+     *     { path: '', component: IndexComponent },  // /A matches this
+     *     { path: 'a', component: AComponent }       // /A/a matches this
+     *   ]
+     * }
+     *
+     * // Default behavior - /A matches even without index child
+     * {
+     *   path: '/A',
+     *   children: [
+     *     { path: 'a', component: AComponent }  // /A/a matches, /A also matches (parent self)
+     *   ]
+     * }
+     * ```
+     */
+    requireIndex?: boolean;
+    /**
+     * Route override function for hybrid app development
+     *
+     * Note: Override is not executed during initial route loading
+     *
+     * @param to Target route
+     * @param from Source route
+     * @returns Function to execute instead of default routing, or void for default
+     *
+     * @example
+     * ```typescript
+     * override: (to, from) => {
+     *   if (isInApp()) {
+     *     return () => JSBridge.openNative();
+     *   }
+     * }
+     * ```
+     */
+    override?: RouteConfirmHook;
+}
+export interface RouteParsedConfig extends RouteConfig {
+    /** Require an index child route to match the parent path (always has a value after parsing) */
+    requireIndex: boolean;
+    compilePath: string;
+    children: RouteParsedConfig[];
+    match: MatchFunction;
+    compile: (params?: Record<string, string>) => string;
+}
+export interface RouteMatchResult {
+    readonly matches: readonly RouteParsedConfig[];
+    readonly params: Record<string, string | string[]>;
+}
+export type RouteMatcher = (to: URL, base: URL, cb?: (item: RouteParsedConfig) => boolean) => RouteMatchResult;
+/**
+ * Route constructor options interface
+ */
+export interface RouteOptions {
+    /** Router parsed options */
+    options?: RouterParsedOptions;
+    /** Route type */
+    toType?: RouteType;
+    /** Target route location */
+    toInput?: RouteLocationInput;
+    /** Source URL */
+    from?: URL | null;
+}
+export interface RouteLayerOptions {
+    /**
+     * Layer zIndex value
+     * If not set, will automatically use incremental layer value (1000 + increment)
+     */
+    zIndex?: number;
+    /**
+     * Hook function to determine layer keep-alive behavior before route closure
+     * Determines whether the layer should remain open during navigation
+     * - 'exact': Keep layer alive only when navigating to the exact initial path (default)
+     * - 'include': Keep layer alive when navigating to paths that start with the initial path
+     * - function: Custom logic to determine if the layer should be kept alive
+     * @default 'exact'
+     * @example
+     * ```typescript
+     * // Default behavior - keep only when navigating back to initial path
+     * keepAlive: 'exact'
+     *
+     * // Keep layer alive for all sub-paths (paths starting with the initial path)
+     * keepAlive: 'include'
+     *
+     * // Custom logic
+     * keepAlive: (to, from, router) => to.query.keepLayer === 'true'
+     * ```
+     */
+    keepAlive?: 'exact' | 'include' | RouteVerifyHook;
+    /**
+     * @deprecated Use keepAlive instead
+     * Verification hook function before route closure
+     * @returns Return true to allow closure, false to prevent closure
+     */
+    shouldClose?: RouteVerifyHook;
+    /**
+     * Whether to automatically record route history
+     * @default true
+     */
+    autoPush?: boolean;
+    /**
+     * Route navigation mode control
+     * - When autoPush is true:
+     *   - true: Use push mode (add new history record)
+     *   - false: Use replace mode (replace current history record)
+     * @default true
+     */
+    push?: boolean;
+    /**
+     * Router options for creating the layer instance
+     * These options will be merged with the default router configuration
+     */
+    routerOptions?: RouterLayerOptions;
+}
+export type RouteLayerResult = {
+    type: 'close';
+    route: Route;
+} | {
+    type: 'push';
+    route: Route;
+} | {
+    type: 'success';
+    route: Route;
+    data?: any;
+};
+/**
+ * Router options for creating layer instances
+ * Excludes handler functions and layer fields which are handled internally by createLayer
+ */
+export type RouterLayerOptions = Omit<RouterOptions, 'handleBackBoundary' | 'handleLayerClose' | 'layer'>;
+export interface RouterMicroAppOptions {
+    mount: (el: HTMLElement) => void;
+    hydration?: (el: HTMLElement) => void;
+    unmount: () => void;
+    renderToString?: () => Awaitable<string>;
+}
+export type RouterMicroAppCallback = (router: Router) => RouterMicroAppOptions;
+export type RouterMicroApp = Record<string, RouterMicroAppCallback | undefined> | RouterMicroAppCallback;
+export interface RouterOptions {
+    /**
+     * Application mount container ID
+     * - Pure string ID, no '#' prefix needed
+     * - Client-side: uses document.getElementById(appId)
+     * - Server-side: generates <div id="${appId}"> wrapper
+     * - Defaults to 'app'
+     *
+     * @example
+     * ```typescript
+     * new Router({ appId: 'app' })
+     * ```
+     */
+    appId?: string;
+    context?: Record<string | symbol, unknown>;
+    data?: Record<string | symbol, unknown>;
+    routes?: RouteConfig[];
+    mode?: RouterMode;
+    /** Optional in browser, but required on server side */
+    base?: URL;
+    req?: IncomingMessage | null;
+    res?: ServerResponse | null;
+    apps?: RouterMicroApp;
+    normalizeURL?: (to: URL, from: URL | null) => URL;
+    fallback?: RouteHandleHook;
+    nextTick?: () => Awaitable<void>;
+    rootStyle?: Partial<CSSStyleDeclaration> | false | null;
+    layer?: boolean;
+    zIndex?: number;
+    handleBackBoundary?: (router: Router) => void;
+    handleLayerClose?: (router: Router, data?: any) => void;
+    resolveLink?: (link: RouterLinkResolved, props: RouterLinkProps) => RouterLinkResolved;
+}
+export interface RouterParsedOptions extends Readonly<Required<RouterOptions>> {
+    readonly compiledRoutes: readonly RouteParsedConfig[];
+    readonly matcher: RouteMatcher;
+}
+/**
+ * Router link navigation types
+ */
+export type RouterLinkType = 'push' | 'replace' | 'pushWindow' | 'replaceWindow' | 'pushLayer';
+/**
+ * Router link attributes generated by the source code
+ */
+export interface RouterLinkAttributes {
+    href: string;
+    class: string;
+    target?: '_blank';
+    rel?: string;
+}
+/**
+ * Framework-agnostic link configuration interface
+ */
+export interface RouterLinkProps {
+    to: RouteLocationInput;
+    type?: RouterLinkType;
+    /**
+     * @deprecated Use type='replace' instead
+     */
+    replace?: boolean;
+    exact?: RouteMatchType;
+    activeClass?: string;
+    event?: string | string[];
+    tag?: string;
+    layerOptions?: RouteLayerOptions;
+    /**
+     * Hook function called before navigation occurs
+     * @param event - The DOM event that triggered the navigation
+     * @param eventName - The name of the event that triggered navigation
+     *
+     * Can prevent default event to block the default navigation handling logic.
+     * Call event.preventDefault() to stop the navigation from proceeding.
+     */
+    beforeNavigate?: (event: Event, eventName: string) => void;
+}
+/**
+ * Framework-agnostic link resolution result
+ */
+export interface RouterLinkResolved {
+    route: Route;
+    type: RouterLinkType;
+    isActive: boolean;
+    isExactActive: boolean;
+    isExternal: boolean;
+    tag: string;
+    attributes: RouterLinkAttributes;
+    navigate: (e: Event) => Promise<void>;
+    createEventHandlers: (format?: (eventType: string) => string) => Record<string, (e: Event) => Promise<void>>;
+}

package/dist/types.mjs

@@ -0,0 +1,18 @@
+export var RouterMode = /* @__PURE__ */ ((RouterMode2) => {
+  RouterMode2["history"] = "history";
+  RouterMode2["memory"] = "memory";
+  return RouterMode2;
+})(RouterMode || {});
+export var RouteType = /* @__PURE__ */ ((RouteType2) => {
+  RouteType2["push"] = "push";
+  RouteType2["replace"] = "replace";
+  RouteType2["restartApp"] = "restartApp";
+  RouteType2["go"] = "go";
+  RouteType2["forward"] = "forward";
+  RouteType2["back"] = "back";
+  RouteType2["unknown"] = "unknown";
+  RouteType2["pushWindow"] = "pushWindow";
+  RouteType2["replaceWindow"] = "replaceWindow";
+  RouteType2["pushLayer"] = "pushLayer";
+  return RouteType2;
+})(RouteType || {});

package/dist/util.d.ts

@@ -0,0 +1,32 @@
+import type { Route, RouteConfirmHookResult, RouteMatchType } from './types';
+export declare const isBrowser: boolean;
+export declare function isNotNullish(value: unknown): boolean;
+export declare function isPlainObject(o: unknown): o is Record<string, any>;
+/**
+ * Check if value is a valid non-empty plain object
+ * Only check enumerable string keys to ensure it's a proper plain object
+ * @param value Value to check
+ * @returns true if it's a valid non-empty plain object
+ */
+export declare function isNonEmptyPlainObject(value: unknown): value is Record<string, any>;
+export declare const removeFromArray: <T>(arr: T[], ele: T) => void;
+export declare function isValidConfirmHookResult(result: unknown): result is Exclude<RouteConfirmHookResult, void>;
+export declare function isUrlEqual(url1: URL, url2?: URL | null): boolean;
+/**
+ * Compare if two routes match
+ *
+ * @param fromRoute First route object
+ * @param toRoute Second route object, may be null
+ * @param matchType Match type
+ * - 'route': Route-level matching, compare if route configurations are the same
+ * - 'exact': Exact matching, compare if full paths are the same
+ * - 'include': Include matching, check if route1 path starts with route2 path
+ * @returns Whether they match
+ */
+export declare function isRouteMatched(fromRoute: Route, toRoute: Route | null, matchType: RouteMatchType): boolean;
+export declare function decodeParams<T extends Record<string, string | string[]>>(params: T): T;
+/**
+ * Validates that SSR renderToString output contains exactly one root HTML element.
+ * Non-production only - throws if validation fails.
+ */
+export declare function validateSsrRootElement(html: string): void;

package/dist/util.mjs

@@ -0,0 +1,100 @@
+export const isBrowser = typeof window === "object";
+export function isNotNullish(value) {
+  return value !== void 0 && value !== null && !Number.isNaN(
+    value instanceof Number ? value.valueOf() : value
+  );
+}
+export function isPlainObject(o) {
+  return (o == null ? void 0 : o.constructor) === Object || Object.prototype.toString.call(o) === "[object Object]";
+}
+export function isNonEmptyPlainObject(value) {
+  if (!isPlainObject(value)) {
+    return false;
+  }
+  return Object.keys(value).length > 0;
+}
+export const removeFromArray = (arr, ele) => {
+  if (!Array.isArray(arr) || arr.length === 0) return;
+  const i = Number.isNaN(ele) ? (
+    // If ele is NaN, use findIndex to search for NaN, because NaN !== NaN, so we can't use indexOf directly
+    arr.findIndex((item) => Number.isNaN(item))
+  ) : arr.indexOf(ele);
+  if (i === -1) return;
+  arr.splice(i, 1);
+};
+export function isValidConfirmHookResult(result) {
+  return result === false || typeof result === "function" || typeof result === "string" || isPlainObject(result);
+}
+export function isUrlEqual(url1, url2) {
+  if (!url2) {
+    return false;
+  }
+  if (url1 === url2) {
+    return true;
+  }
+  (url1 = new URL(url1)).searchParams.sort();
+  (url2 = new URL(url2)).searchParams.sort();
+  url1.hash = url1.hash;
+  url2.hash = url2.hash;
+  return url1.href === url2.href;
+}
+export function isRouteMatched(fromRoute, toRoute, matchType) {
+  if (!toRoute) return false;
+  switch (matchType) {
+    case "route":
+      return fromRoute.config === toRoute.config;
+    case "exact":
+      return fromRoute.fullPath === toRoute.fullPath;
+    case "include":
+      return fromRoute.fullPath.startsWith(toRoute.fullPath);
+    default:
+      return false;
+  }
+}
+export function decodeParams(params) {
+  const result = {};
+  for (const key in params) {
+    const value = params[key];
+    if (Array.isArray(value)) {
+      result[key] = value.map(
+        (item) => decodeURIComponent(item)
+      );
+    } else {
+      result[key] = decodeURIComponent(value);
+    }
+  }
+  return result;
+}
+export function validateSsrRootElement(html) {
+  var _a;
+  const trimmed = html.trim();
+  const firstMatch = trimmed.match(/^<([a-zA-Z][^\s>]*)/);
+  const firstTag = firstMatch == null ? void 0 : firstMatch[1];
+  const lastTag = (_a = trimmed.match(/<\/([a-zA-Z][^\s>]*)>\s*$/)) == null ? void 0 : _a[1];
+  if (!firstTag || firstTag !== lastTag) {
+    throw new Error(
+      "SSR renderToString() must return exactly one root HTML element. Current output: " + trimmed.slice(0, 100)
+    );
+  }
+  const tagRe = new RegExp("<(/?)".concat(firstTag, "(?:\\s[^>]*)?(/?)>"), "g");
+  let depth = 0;
+  let rootCloseEnd = -1;
+  let tag = tagRe.exec(trimmed);
+  while (tag !== null) {
+    if (tag[1] === "/") {
+      depth--;
+      if (depth === 0) {
+        rootCloseEnd = tagRe.lastIndex;
+        break;
+      }
+    } else if (tag[2] !== "/") {
+      depth++;
+    }
+    tag = tagRe.exec(trimmed);
+  }
+  if (rootCloseEnd === -1 || trimmed.slice(rootCloseEnd).trim().length > 0) {
+    throw new Error(
+      "SSR renderToString() must return exactly one root HTML element. Current output: " + trimmed.slice(0, 100)
+    );
+  }
+}

package/package.json

@@ -1,9 +1,34 @@
 {
     "name": "@esmx/router",
+    "description": "Framework-agnostic universal router for browser and Node.js SSR, with micro-frontend and layer navigation support",
+    "keywords": [
+        "router",
+        "routing",
+        "ssr",
+        "micro-frontend",
+        "typescript",
+        "universal",
+        "navigation",
+        "esmx",
+        "esm",
+        "spa",
+        "framework",
+        "frontend"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/esmnext/esmx.git",
+        "directory": "packages/router"
+    },
+    "homepage": "https://github.com/esmnext/esmx",
+    "bugs": {
+        "url": "https://github.com/esmnext/esmx/issues"
+    },
+    "license": "MIT",
     "template": "library",
     "scripts": {
         "lint:js": "biome check --write --no-errors-on-unmatched",
-        "lint:css": "stylelint '**/*.{css,vue}' --fix --aei",
+        "lint:css": "pnpm run lint:js",
         "lint:type": "tsc --noEmit",
         "test": "vitest run --pass-with-no-tests",
         "coverage": "vitest run --coverage --pass-with-no-tests",
@@ -28,22 +53,18 @@
         }
     ],
     "dependencies": {
-        "path-to-regexp": "^6.2.2",
-        "url-parse": "^1.5.10"
+        "path-to-regexp": "^6.2.2"
     },
     "devDependencies": {
-        "@biomejs/biome": "1.9.4",
-        "@esmx/lint": "3.0.0-rc.12",
-        "@gez/lint": "3.0.0-rc.9",
-        "@types/node": "22.13.10",
-        "@types/url-parse": "^1.4.11",
-        "@vitest/coverage-v8": "3.0.8",
-        "stylelint": "16.15.0",
-        "typescript": "5.8.2",
-        "unbuild": "2.0.0",
-        "vitest": "3.0.8"
+        "@biomejs/biome": "2.3.7",
+        "@types/node": "^24.0.0",
+        "@vitest/coverage-v8": "3.2.6",
+        "happy-dom": "^20.0.10",
+        "typescript": "5.9.3",
+        "unbuild": "3.6.1",
+        "vitest": "3.2.6"
     },
-    "version": "3.0.0-rc.12",
+    "version": "3.0.0-rc.120",
     "type": "module",
     "private": false,
     "exports": {
@@ -62,5 +83,11 @@
         "template",
         "public"
     ],
-    "gitHead": "7d2c2fc4fe2cc98ebdbc12560f19637ca04398e5"
+    "gitHead": "3e692857ccb65e7d1fdf689e30eb5d935e8bda77",
+    "engines": {
+        "node": ">=24"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
 }