@esmx/router 3.0.0-rc.18 → 3.0.0-rc.19

package/dist/types.d.ts

@@ -0,0 +1,246 @@
+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;
+    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;
+    /**
+     * 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 {
+    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[] | undefined>;
+}
+export type RouteMatcher = (targetURL: URL, baseURL: URL) => 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;
+    /**
+     * 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;
+    unmount: () => void;
+    renderToString?: () => Awaitable<string>;
+}
+export type RouterMicroAppCallback = (router: Router) => RouterMicroAppOptions;
+export type RouterMicroApp = Record<string, RouterMicroAppCallback | undefined> | RouterMicroAppCallback;
+export interface RouterOptions {
+    /**
+     * Application mounting container
+     * - Can be a DOM selector string (e.g., '#app', '.container', '[data-mount]')
+     * - Can be an HTMLElement object
+     * - Defaults to '#root'
+     *
+     * @example
+     * ```typescript
+     * // Using ID selector
+     * new Router({ root: '#my-app' })
+     *
+     * // Using class selector
+     * new Router({ root: '.app-container' })
+     *
+     * // Using attribute selector
+     * new Router({ root: '[data-router-mount]' })
+     *
+     * // Passing DOM element directly
+     * const element = document.getElementById('app');
+     * new Router({ root: element })
+     * ```
+     */
+    root?: string | HTMLElement;
+    context?: 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;
+    rootStyle?: Partial<CSSStyleDeclaration> | false;
+    layer?: boolean;
+    zIndex?: number;
+    handleBackBoundary?: (router: Router) => void;
+    handleLayerClose?: (router: Router, data?: any) => void;
+}
+export interface RouterParsedOptions extends Readonly<Required<RouterOptions>> {
+    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;
+}
+/**
+ * Framework-agnostic link resolution result
+ */
+export interface RouterLinkResolved {
+    route: Route;
+    type: RouterLinkType;
+    isActive: boolean;
+    isExactActive: boolean;
+    isExternal: boolean;
+    tag: string;
+    attributes: RouterLinkAttributes;
+    navigate: (e?: MouseEvent) => Promise<void>;
+    getEventHandlers: (nameTransform?: (eventType: string) => string) => Record<string, (e: MouseEvent) => 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,26 @@
+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 route1 First route object
+ * @param route2 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(route1: Route, route2: Route | null, matchType: RouteMatchType): boolean;

package/dist/util.mjs

@@ -0,0 +1,53 @@
+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(route1, route2, matchType) {
+  if (!route2) return false;
+  switch (matchType) {
+    case "route":
+      return route1.config === route2.config;
+    case "exact":
+      return route1.fullPath === route2.fullPath;
+    case "include":
+      return route1.fullPath.startsWith(route2.fullPath);
+    default:
+      return false;
+  }
+}

package/dist/util.test.d.ts

@@ -0,0 +1 @@
+export {};