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

package/src/scroll.ts

@@ -0,0 +1,106 @@
+/** 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 const winScrollPos = (): _ScrollPosition => ({
+    left: window.scrollX,
+    top: window.scrollY
+});
+
+/** Get element position for scrolling in document */
+function getElementPosition(
+    el: Element,
+    offset: ScrollToOptions
+): _ScrollPosition {
+    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)
+    };
+}
+
+/** Scroll to specified position */
+export function scrollToPosition(position: ScrollPosition): void {
+    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
+        );
+    }
+}
+
+/** Stored scroll positions */
+export const scrollPositions = new Map<string, _ScrollPosition>();
+
+const POSITION_KEY = '__scroll_position_key';
+
+/** Save scroll position */
+export function saveScrollPosition(
+    key: string,
+    scrollPosition = winScrollPos()
+) {
+    scrollPosition = { ...scrollPosition };
+    scrollPositions.set(key, scrollPosition);
+
+    try {
+        if (location.href !== key) return;
+        // preserve the existing history state as it could be overridden by the user
+        const stateCopy = {
+            ...(history.state || {}),
+            [POSITION_KEY]: scrollPosition
+        };
+        history.replaceState(stateCopy, '');
+    } catch (error) {}
+}
+
+/** Get saved scroll position */
+export function getSavedScrollPosition(
+    key: string,
+    defaultValue: _ScrollPosition | null = null
+): _ScrollPosition | null {
+    const scroll = scrollPositions.get(key) || history.state?.[POSITION_KEY];
+
+    // Saved scroll position should not be used multiple times, next time should use newly saved position
+    scrollPositions.delete(key);
+    return scroll || defaultValue;
+}

package/src/types.ts

@@ -0,0 +1,415 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { MatchFunction } from 'path-to-regexp';
+import type { Route } from './route';
+import type { Router } from './router';
+
+// Re-export Route type for backward compatibility
+export type { Route };
+
+// ============================================================================
+// Utility types
+// ============================================================================
+export type Awaitable<T> = T | Promise<T>;
+
+// ============================================================================
+// Core enums
+// ============================================================================
+export enum RouterMode {
+    history = 'history',
+    memory = 'memory'
+}
+
+export enum RouteType {
+    push = 'push',
+    replace = 'replace',
+    restartApp = 'restartApp',
+    go = 'go',
+    forward = 'forward',
+    back = 'back',
+    unknown = 'unknown',
+    pushWindow = 'pushWindow',
+    replaceWindow = 'replaceWindow',
+    pushLayer = 'pushLayer'
+}
+
+// ============================================================================
+// Hook function types
+// ============================================================================
+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;
+
+// ============================================================================
+// Basic data types
+// ============================================================================
+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';
+
+// ============================================================================
+// Route location and config types
+// ============================================================================
+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;
+}
+
+// ============================================================================
+// Router Layer types
+// ============================================================================
+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'
+>;
+
+// ============================================================================
+// Router MicroApp types
+// ============================================================================
+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;
+
+// ============================================================================
+// Router core types
+// ============================================================================
+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;
+}
+
+// ============================================================================
+// RouterLink types
+// ============================================================================
+
+/**
+ * Router link navigation types
+ */
+export type RouterLinkType =
+    | 'push'
+    | 'replace'
+    | 'pushWindow'
+    | 'replaceWindow'
+    | 'pushLayer';
+
+/**
+ * Router link attributes generated by the source code
+ */
+export interface RouterLinkAttributes {
+    // Always generated
+    href: string;
+    class: string;
+
+    // Conditionally generated
+    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 {
+    // Basic information
+    route: Route;
+    type: RouterLinkType;
+    isActive: boolean;
+    isExactActive: boolean;
+    isExternal: boolean;
+    tag: string;
+
+    // Element attributes
+    attributes: RouterLinkAttributes;
+
+    // Navigation function
+    navigate: (e: Event) => Promise<void>;
+
+    // Event handling
+    createEventHandlers: (
+        format?: (eventType: string) => string
+    ) => Record<string, (e: Event) => Promise<void>>;
+}

package/src/util.ts

@@ -0,0 +1,184 @@
+import type { Route, RouteConfirmHookResult, RouteMatchType } from './types';
+export const isBrowser = typeof window === 'object';
+
+export function isNotNullish(value: unknown): boolean {
+    return (
+        value !== undefined &&
+        value !== null &&
+        !Number.isNaN(
+            value instanceof Number
+                ? value.valueOf() // For new Number() cases
+                : value
+        )
+    );
+}
+
+export function isPlainObject(o: unknown): o is Record<string, any> {
+    return (
+        o?.constructor === Object ||
+        Object.prototype.toString.call(o) === '[object Object]'
+    );
+}
+
+/**
+ * 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 function isNonEmptyPlainObject(
+    value: unknown
+): value is Record<string, any> {
+    if (!isPlainObject(value)) {
+        return false;
+    }
+    // Only check enumerable string keys to ensure valid properties of plain object
+    return Object.keys(value as Record<string, any>).length > 0;
+}
+
+export const removeFromArray = <T>(arr: T[], ele: T) => {
+    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: unknown
+): result is Exclude<RouteConfirmHookResult, void> {
+    return (
+        result === false ||
+        typeof result === 'function' ||
+        typeof result === 'string' ||
+        isPlainObject(result)
+    );
+}
+
+export function isUrlEqual(url1: URL, url2?: URL | null): boolean {
+    // If url2 doesn't exist, return false
+    if (!url2) {
+        return false;
+    }
+
+    // If it's the same object reference, return true directly
+    if (url1 === url2) {
+        return true;
+    }
+
+    // Copy and sort query parameters
+    (url1 = new URL(url1)).searchParams.sort();
+    (url2 = new URL(url2)).searchParams.sort();
+    // Normalize trailing empty hash:
+    // new URL('https://a.com/path#').href includes a trailing '#',
+    // but new URL('https://a.com/path').href does not.
+    // Assigning hash to itself triggers the setter to re-normalize the URL,
+    // ensuring both forms produce the same href.
+    url1.hash = url1.hash;
+    url2.hash = url2.hash;
+    return url1.href === url2.href;
+}
+
+/**
+ * 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 function isRouteMatched(
+    fromRoute: Route,
+    toRoute: Route | null,
+    matchType: RouteMatchType
+): boolean {
+    if (!toRoute) return false;
+
+    switch (matchType) {
+        case 'route':
+            // Route-level matching - compare route configurations
+            return fromRoute.config === toRoute.config;
+
+        case 'exact':
+            // Exact matching - full paths are identical
+            return fromRoute.fullPath === toRoute.fullPath;
+
+        case 'include':
+            // Include matching - route1 path contains route2 path
+            return fromRoute.fullPath.startsWith(toRoute.fullPath);
+
+        default:
+            return false;
+    }
+}
+
+export function decodeParams<T extends Record<string, string | string[]>>(
+    params: T
+): T {
+    const result = {} as T;
+
+    for (const key in params) {
+        const value = params[key];
+        if (Array.isArray(value)) {
+            result[key] = value.map((item) =>
+                decodeURIComponent(item)
+            ) as T[typeof key];
+        } else {
+            result[key] = decodeURIComponent(value) as T[typeof key];
+        }
+    }
+
+    return result;
+}
+
+/**
+ * Validates that SSR renderToString output contains exactly one root HTML element.
+ * Non-production only - throws if validation fails.
+ */
+export function validateSsrRootElement(html: string): void {
+    const trimmed = html.trim();
+    const firstMatch = trimmed.match(/^<([a-zA-Z][^\s>]*)/);
+    const firstTag = firstMatch?.[1];
+    const lastTag = trimmed.match(/<\/([a-zA-Z][^\s>]*)>\s*$/)?.[1];
+    if (!firstTag || firstTag !== lastTag) {
+        throw new Error(
+            'SSR renderToString() must return exactly one root HTML element. ' +
+                'Current output: ' +
+                trimmed.slice(0, 100)
+        );
+    }
+    // Find the ROOT element's matching close tag by depth-counting occurrences
+    // of the root tag, so a single root that nests same-tag children (e.g. a
+    // `<div>` wrapping child `<div>`s — very common) is not mistaken for
+    // multiple roots. A naive "first `</tag>`" scan matches an inner close and
+    // wrongly reports trailing content. Anything after the matched root close is
+    // a sibling root → invalid.
+    const tagRe = new RegExp(`<(/?)${firstTag}(?:\\s[^>]*)?(/?)>`, 'g');
+    let depth = 0;
+    let rootCloseEnd = -1;
+    let tag: RegExpExecArray | null = 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)
+        );
+    }
+}