@iyulab/router 0.5.1 → 0.5.2

package/dist/index.d.ts

@@ -18,22 +18,38 @@ declare interface BaseRouteConfig {
      */
     title?: string;
     /**
-     * 라우트에 대응하는 렌더링 함수
-     * - 라우트 정보를 받아 HTMLElement, ReactElement, 또는 LitElement TemplateResult를 반환합니다.
-     * @param info 라우팅 정보
+     * 라우터 경로는 string 또는 URLPattern을 사용할 수 있습니다.
+     * string일 경우 자동으로 URLPattern으로 변환됩니다.
+     * @default '/'
+     * @example
+     * - "/user/:id/:name"
+     * - "/user/:id/:name?"
+     * - "/user/:id/:name*"
+     * - "/user/:id/:name+"
+     * - "/user/:id/:name{1,3}"
+     * @link
+     * https://developer.mozilla.org/en-US/docs/Web/API/URLPattern
+     */
+    path?: string | URLPattern;
+    /**
+     * 라우트 정보를 받아 렌더링 결과를 반환합니다.
+     * @param ctx 현재 라우팅 정보 및, 진행 상태 콜백을 포함하는 Context 객체가 인자로 전달됩니다.
      * @example
      * ```typescript
      * const route = {
-     *    path: '/user',
-     *    render: (info) => html`<user-page .routeInfo=${info}></user-page>`,
+     *    path: '/user:id',
+     *    render: async (ctx) => {
+     *      // 사용자 정보를 비동기로 가져오는 예시
+     *      const userId = ctx.params.id;
+     *      ctx.progress(30);
+     *      const userData = await fetchUserData(userId);
+     *      ctx.progress(70);
+     *      return html`<user-profile .data=${userData}></user-profile>`;
+     *   }
      * }
      * ```
      */
-    render?: (info: RouteInfo) => Promise<RenderResult> | RenderResult;
-    /**
-     * 중첩 라우트
-     */
-    children?: RouteConfig[];
+    render?: (ctx: RouteContext) => Promise<RenderResult> | RenderResult;
     /**
      * 라우터 URL 변경시 렌더링을 강제할지 여부
      * - 기본값으로 children을 가질때 false로 설정되며, children이 없을 경우 true로 설정됩니다.
@@ -56,20 +72,47 @@ export declare class ContentRenderError extends RouteError {
     constructor(original?: Error | any);
 }
 
-/**
- * 인덱스 라우트 타입
- */
-declare interface IndexRouteConfig extends BaseRouteConfig {
+export declare type FallbackRenderResult = HTMLElement | ReactElement | TemplateResult<1>;
+
+export declare interface FallbackRouteConfig {
     /**
-     * true일 경우 인덱스 라우트입니다.
-     * path는 강제로 빈 문자열로 설정됩니다.
+     * 브라우저의 타이틀이 설정에 따라 변경됩니다.
      */
-    index: true;
+    title?: string;
     /**
-     * 인덱스 라우트의 URLPattern (자동 설정됨)
-     * 부모 라우트의 basepath를 상속받습니다.
+     * 라우팅 실패 시 표시할 렌더링 결과를 반환합니다.
+     * - 오류가 발생할 경우 또는 렌더링 결과가 false일 경우 호출됩니다.
+     * @param ctx 현재 라우팅 정보 및 오류 정보를 포함하는 Context 객체가 인자로 전달됩니다.
+     * @example
+     * ```typescript
+     * const fallbackRoute = {
+     *    title: 'Not Found',
+     *    render: (ctx) => {
+     *      if (ctx.error) {
+     *        return html`<error-page .error=${ctx.error}></error-page>`;
+     *      }
+     *      return html`<not-found-page></not-found-page>`;
+     *    }
+     * }
+     * ```
      */
-    path?: URLPattern;
+    render?: (ctx: FallbackRouteContext) => Promise<FallbackRenderResult> | FallbackRenderResult;
+}
+
+export declare interface FallbackRouteContext extends RouteContext {
+    /**
+     * 라우팅 에러 정보
+     * - 라우팅 중 발생한 에러 정보를 포함합니다.
+     */
+    error: RouteError;
+}
+
+declare interface IndexRouteConfig extends BaseRouteConfig {
+    /**
+     * 현재 경로의 인덱스 라우트임을 나타냅니다.
+     * - 인덱스 라우트는 부모 경로와 동일한 경로를 가지며, path는 자동으로 설정됩니다.
+     */
+    index: true;
 }
 
 /**
@@ -113,6 +156,18 @@ export declare class Link extends LitElement {
     static styles: CSSResult;
 }
 
+declare interface NonIndexRouteConfig extends BaseRouteConfig {
+    /**
+     * 인덱스 라우트가 아님을 나타냅니다.
+     */
+    index?: false;
+    /**
+     * 하위 라우트 설정, 재귀적으로 RouteConfig 배열을 가질 수 있습니다.
+     * - 하위 라우트가 있는 경우, 부모 라우트의 경로를 기준으로 매칭됩니다.
+     */
+    children?: RouteConfig[];
+}
+
 /**
  * 페이지를 찾을 수 없을 때 발생하는 에러
  */
@@ -149,101 +204,27 @@ export declare class OutletMissingError extends RouteError {
     constructor();
 }
 
-/**
- * 경로 라우트 타입
- */
-declare interface PathRouteConfig extends BaseRouteConfig {
-    /**
-     * 라우터 경로는 string 또는 URLPattern을 사용할 수 있습니다.
-     * string일 경우 자동으로 URLPattern으로 변환됩니다.
-     * @example
-     * - "/user/:id/:name"
-     * - "/user/:id/:name?"
-     * - "/user/:id/:name*"
-     * - "/user/:id/:name+"
-     * - "/user/:id/:name{1,3}"
-     * @link
-     * https://developer.mozilla.org/en-US/docs/Web/API/URLPattern
-     */
-    path: string | URLPattern;
-}
-
 declare interface RenderOption {
     id?: string;
     force?: boolean;
     content: RenderResult;
 }
 
-declare type RenderResult = HTMLElement | ReactElement | TemplateResult<1>;
+export declare type RenderResult = HTMLElement | ReactElement | TemplateResult<1> | false;
 
 /**
  * 라우트 시작 이벤트
  */
 export declare class RouteBeginEvent extends RouteEvent {
-    constructor(routeInfo: RouteInfo);
-}
-
-/**
- * 라우트 타입 (인덱스 라우트 또는 경로 라우트)
- */
-export declare type RouteConfig = IndexRouteConfig | PathRouteConfig;
-
-/**
- * 라우트 완료 이벤트
- */
-export declare class RouteDoneEvent extends RouteEvent {
-    constructor(routeInfo: RouteInfo);
-}
-
-/**
- * 라우팅 에러 정보
- */
-export declare class RouteError extends Error {
-    /**
-     * 에러 코드
-     * - HTTP 상태 코드 또는 커스텀 에러 코드
-     * @example 404, 500, 'ROUTE_NOT_FOUND'
-     */
-    code: number | string;
-    /**
-     * 원본 에러 객체
-     * - 원본 Error 객체 또는 예외 정보
-     */
-    original?: Error | any;
-    /**
-     * 에러 발생 시간
-     * - 에러가 발생한 시간 (ISO 8601 형식)
-     */
-    timestamp: string;
-    constructor(code: number | string, message: string, original?: Error | any);
+    constructor(context: RouteContext);
 }
 
-/**
- * 라우트 에러 이벤트
- */
-export declare class RouteErrorEvent extends RouteEvent {
-    /** 에러 정보 */
-    readonly error: RouteError;
-    constructor(error: RouteError, routeInfo: RouteInfo);
-}
-
-/** 라우터 이벤트 기본 클래스 */
-declare abstract class RouteEvent extends Event {
-    /** 라우팅 정보 */
-    readonly routeInfo: RouteInfo;
-    /** 이벤트 발생 시간 */
-    readonly timestamp: string;
-    constructor(type: string, routeInfo: RouteInfo, cancelable?: boolean);
-    /** 이벤트가 취소되었는지 확인 */
-    get cancelled(): boolean;
-    /** 이벤트 취소 */
-    cancel(): void;
-}
+export declare type RouteConfig = IndexRouteConfig | NonIndexRouteConfig;
 
 /**
  * 라우터 정보
  */
-export declare interface RouteInfo {
+export declare interface RouteContext {
     /**
      * 전체 URL 정보
      * - 도메인 이름을 포함한 URL의 전체 경로입니다.
@@ -305,6 +286,73 @@ export declare interface RouteInfo {
      * @example #profile
      */
     hash?: string;
+    /**
+     * 현재 라우팅의 진행 상태를 업데이트하여, window 객체의 'route-progress' 이벤트를 트리거합니다.
+     * 여러 라우팅이 호출되는 경우, 가장 최근의 라우팅의 진행 상태만 반영되며, 나머지는 무시됩니다.
+     * @param value 진행 상태 값 (0~100)
+     */
+    progress: (value: number) => void;
+}
+
+/**
+ * 라우트 완료 이벤트
+ */
+export declare class RouteDoneEvent extends RouteEvent {
+    constructor(context: RouteContext);
+}
+
+/**
+ * 라우팅 에러 정보
+ */
+export declare class RouteError extends Error {
+    /**
+     * 에러 코드
+     * - HTTP 상태 코드 또는 커스텀 에러 코드
+     * @example 404, 500, 'ROUTE_NOT_FOUND'
+     */
+    code: number | string;
+    /**
+     * 원본 에러 객체
+     * - 원본 Error 객체 또는 예외 정보
+     */
+    original?: Error | any;
+    /**
+     * 에러 발생 시간
+     * - 에러가 발생한 시간 (ISO 8601 형식)
+     */
+    timestamp: string;
+    constructor(code: number | string, message: string, original?: Error | any);
+}
+
+/**
+ * 라우트 에러 이벤트
+ */
+export declare class RouteErrorEvent extends RouteEvent {
+    /** 에러 정보 */
+    readonly error: RouteError;
+    constructor(context: RouteContext, error: RouteError);
+}
+
+/** 라우터 이벤트 기본 클래스 */
+declare abstract class RouteEvent extends Event {
+    /** 라우팅 정보 */
+    readonly context: RouteContext;
+    /** 이벤트 발생 시간 */
+    readonly timestamp: string;
+    constructor(type: string, context: RouteContext, cancelable?: boolean);
+    /** 이벤트가 취소되었는지 확인 */
+    get cancelled(): boolean;
+    /** 이벤트 취소 */
+    cancel(): void;
+}
+
+/**
+ * 라우트 진행 이벤트
+ */
+export declare class RouteProgressEvent extends RouteEvent {
+    /** 진행 상태 값 (0~100) */
+    readonly progress: number;
+    constructor(context: RouteContext, progress: number);
 }
 
 /**
@@ -314,21 +362,20 @@ export declare class Router {
     private readonly _rootElement;
     private readonly _basepath;
     private readonly _routes;
+    private readonly _fallback?;
     /** 현재 라우팅 요청 ID */
     private _requestID?;
     /** 현재 라우팅 정보 */
-    private _routeInfo?;
+    private _context?;
     constructor(config: RouterConfig);
-    /** 초기 라우팅 처리, TODO: 제거 */
-    private waitConnected;
     /** 객체를 정리하고 이벤트 리스너를 제거합니다. */
     destroy(): void;
     /** 라우터의 기본 경로 반환 */
     get basepath(): string;
-    /** 등록된 라우트 반환 */
+    /** 등록된 라우트 정보 반환 */
     get routes(): RouteConfig[];
     /** 현재 라우팅 정보 반환 */
-    get routeInfo(): RouteInfo | undefined;
+    get context(): RouteContext | undefined;
     /**
      * 지정한 경로의 클라이언트 라우팅을 수행합니다. 상대경로일 경우 basepath와 조합되어 이동합니다.
      * @param href 이동할 경로
@@ -360,12 +407,22 @@ export declare interface RouterConfig {
      * - 라우트는 URLPattern을 사용하여 경로를 탐색합니다.
      * - 라우트는 렌더링할 엘리먼트 또는 컴포넌트를 지정합니다.
      */
-    routes: RouteConfig[];
+    routes?: RouteConfig[];
+    /**
+     * 라우트 매칭 실패 또는 오류 발생 시 대체 라우트 설정
+     * - 지정된 설정이 없을 경우, 기본 오류 페이지가 렌더링됩니다.
+     */
+    fallback?: FallbackRouteConfig;
     /**
      * `a` 태그 클릭 시 클라이언트 라우팅을 수행할지 여부를 설정합니다.
      * @default true
      */
     useIntercept?: boolean;
+    /**
+     * 초기 로드 시 현재 URL로 라우팅을 자동으로 수행할지 여부를 설정합니다.
+     * @default true
+     */
+    initialLoad?: boolean;
 }
 
 export declare const ULink: ReactWebComponent<Link, {}>;
@@ -375,12 +432,9 @@ export declare const UOutlet: ReactWebComponent<Outlet, {}>;
 export { }
 
 declare global {
-  interface Window {
-    route: RouteInfo;
-  }
-
   interface WindowEventMap {
     'route-begin': RouteBeginEvent;
+    'route-progress': RouteProgressEvent;
     'route-done': RouteDoneEvent;
     'route-error': RouteErrorEvent;
   }

package/dist/index.js

@@ -2,7 +2,7 @@ import React from "react";
 import { LitElement, html, css, render } from "lit";
 import { state, property, customElement } from "lit/decorators.js";
 import { createRoot } from "react-dom/client";
-import { unsafeSVG } from "lit/directives/unsafe-svg.js";
+import { unsafeHTML } from "lit-html/directives/unsafe-html.js";
 const e = /* @__PURE__ */ new Set(["children", "localName", "ref", "style", "className"]), n = /* @__PURE__ */ new WeakMap(), t = (e2, t2, o2, l, a) => {
   const s = a?.[t2];
   void 0 === s ? (e2[t2] = o2, null == o2 && t2 in HTMLElement.prototype && e2.removeAttribute(t2)) : o2 !== l && ((e3, t3, o3) => {
@@ -65,7 +65,9 @@ function parseUrl(url, basepath) {
     pathname: urlObj.pathname,
     query: new URLSearchParams(urlObj.search),
     hash: urlObj.hash,
-    params: {}
+    params: {},
+    progress: () => {
+    }
   };
 }
 function absolutePath(...paths) {
@@ -214,7 +216,10 @@ class Outlet extends LitElement {
     this.routeId = id;
     this.clear();
     if (!this.container) {
-      throw new Error("DOM이 초기화되지 않았습니다.");
+      throw new Error("Outlet container is not initialized.");
+    }
+    if (content === false) {
+      throw new Error("Content is false, cannot render.");
     }
     if (content instanceof HTMLElement) {
       this.container.appendChild(content);
@@ -292,9 +297,9 @@ class ContentRenderError extends RouteError {
   }
 }
 class RouteEvent extends Event {
-  constructor(type, routeInfo, cancelable = false) {
+  constructor(type, context, cancelable = false) {
     super(type, { bubbles: true, composed: true, cancelable });
-    this.routeInfo = routeInfo;
+    this.context = context;
     this.timestamp = (/* @__PURE__ */ new Date()).toISOString();
   }
   /** 이벤트가 취소되었는지 확인 */
@@ -309,30 +314,72 @@ class RouteEvent extends Event {
   }
 }
 class RouteBeginEvent extends RouteEvent {
-  constructor(routeInfo) {
-    super("route-begin", routeInfo, false);
+  constructor(context) {
+    super("route-begin", context, false);
+  }
+}
+class RouteProgressEvent extends RouteEvent {
+  constructor(context, progress) {
+    super("route-progress", context, false);
+    this.progress = progress;
   }
 }
 class RouteDoneEvent extends RouteEvent {
-  constructor(routeInfo) {
-    super("route-done", routeInfo, false);
+  constructor(context) {
+    super("route-done", context, false);
   }
 }
 class RouteErrorEvent extends RouteEvent {
-  constructor(error, routeInfo) {
-    super("route-error", routeInfo, false);
+  constructor(context, error) {
+    super("route-error", context, false);
     this.error = error;
   }
 }
-const __vite_glob_0_0 = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M15 8a6.97 6.97 0 0 0-1.71-4.584l-9.874 9.875A7 7 0 0 0 15 8M2.71 12.584l9.874-9.875a7 7 0 0 0-9.874 9.874ZM16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0"/>\n</svg>';
-const __vite_glob_0_1 = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M8.186 1.113a.5.5 0 0 0-.372 0L1.846 3.5l2.404.961L10.404 2zm3.564 1.426L5.596 5 8 5.961 14.154 3.5zm3.25 1.7-6.5 2.6v7.922l6.5-2.6V4.24zM7.5 14.762V6.838L1 4.239v7.923zM7.443.184a1.5 1.5 0 0 1 1.114 0l7.129 2.852A.5.5 0 0 1 16 3.5v8.662a1 1 0 0 1-.629.928l-7.185 2.874a.5.5 0 0 1-.372 0L.63 13.09a1 1 0 0 1-.63-.928V3.5a.5.5 0 0 1 .314-.464z"/>\n</svg>';
-const __vite_glob_0_2 = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.15.15 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.2.2 0 0 1-.054.06.1.1 0 0 1-.066.017H1.146a.1.1 0 0 1-.066-.017.2.2 0 0 1-.054-.06.18.18 0 0 1 .002-.183L7.884 2.073a.15.15 0 0 1 .054-.057m1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767z"/>\n  <path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0M7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0z"/>\n</svg>';
-const __vite_glob_0_3 = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M8 5a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3m4 3a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3M5.5 7a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0m.5 6a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3"/>\n  <path d="M16 8c0 3.15-1.866 2.585-3.567 2.07C11.42 9.763 10.465 9.473 10 10c-.603.683-.475 1.819-.351 2.92C9.826 14.495 9.996 16 8 16a8 8 0 1 1 8-8m-8 7c.611 0 .654-.171.655-.176.078-.146.124-.464.07-1.119-.014-.168-.037-.37-.061-.591-.052-.464-.112-1.005-.118-1.462-.01-.707.083-1.61.704-2.314.369-.417.845-.578 1.272-.618.404-.038.812.026 1.16.104.343.077.702.186 1.025.284l.028.008c.346.105.658.199.953.266.653.148.904.083.991.024C14.717 9.38 15 9.161 15 8a7 7 0 1 0-7 7"/>\n</svg>';
-const __vite_glob_0_4 = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M11 5a3 3 0 1 1-6 0 3 3 0 0 1 6 0M8 7a2 2 0 1 0 0-4 2 2 0 0 0 0 4m0 5.996V14H3s-1 0-1-1 1-4 6-4q.845.002 1.544.107a4.5 4.5 0 0 0-.803.918A11 11 0 0 0 8 10c-2.29 0-3.516.68-4.168 1.332-.678.678-.83 1.418-.832 1.664zM9 13a1 1 0 0 1 1-1v-1a2 2 0 1 1 4 0v1a1 1 0 0 1 1 1v2a1 1 0 0 1-1 1h-4a1 1 0 0 1-1-1zm3-3a1 1 0 0 0-1 1v1h2v-1a1 1 0 0 0-1-1"/>\n</svg>';
-const __vite_glob_0_5 = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M11.742 10.344a6.5 6.5 0 1 0-1.397 1.398h-.001q.044.06.098.115l3.85 3.85a1 1 0 0 0 1.415-1.414l-3.85-3.85a1 1 0 0 0-.115-.1zM12 6.5a5.5 5.5 0 1 1-11 0 5.5 5.5 0 0 1 11 0"/>\n</svg>';
-const __vite_glob_0_6 = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M8.5 5.6a.5.5 0 1 0-1 0v2.9h-3a.5.5 0 0 0 0 1H8a.5.5 0 0 0 .5-.5z"/>\n  <path d="M6.5 1A.5.5 0 0 1 7 .5h2a.5.5 0 0 1 0 1v.57c1.36.196 2.594.78 3.584 1.64l.012-.013.354-.354-.354-.353a.5.5 0 0 1 .707-.708l1.414 1.415a.5.5 0 1 1-.707.707l-.353-.354-.354.354-.013.012A7 7 0 1 1 7 2.071V1.5a.5.5 0 0 1-.5-.5M8 3a6 6 0 1 0 .001 12A6 6 0 0 0 8 3"/>\n</svg>';
-const __vite_glob_0_7 = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M10.706 3.294A12.6 12.6 0 0 0 8 3C5.259 3 2.723 3.882.663 5.379a.485.485 0 0 0-.048.736.52.52 0 0 0 .668.05A11.45 11.45 0 0 1 8 4q.946 0 1.852.148zM8 6c-1.905 0-3.68.56-5.166 1.526a.48.48 0 0 0-.063.745.525.525 0 0 0 .652.065 8.45 8.45 0 0 1 3.51-1.27zm2.596 1.404.785-.785q.947.362 1.785.907a.482.482 0 0 1 .063.745.525.525 0 0 1-.652.065 8.5 8.5 0 0 0-1.98-.932zM8 10l.933-.933a6.5 6.5 0 0 1 2.013.637c.285.145.326.524.1.75l-.015.015a.53.53 0 0 1-.611.09A5.5 5.5 0 0 0 8 10m4.905-4.905.747-.747q.886.451 1.685 1.03a.485.485 0 0 1 .047.737.52.52 0 0 1-.668.05 11.5 11.5 0 0 0-1.811-1.07M9.02 11.78c.238.14.236.464.04.66l-.707.706a.5.5 0 0 1-.707 0l-.707-.707c-.195-.195-.197-.518.04-.66A2 2 0 0 1 8 11.5c.374 0 .723.102 1.021.28zm4.355-9.905a.53.53 0 0 1 .75.75l-10.75 10.75a.53.53 0 0 1-.75-.75z"/>\n</svg>';
-const __vite_glob_0_8 = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M16 4.5a4.5 4.5 0 0 1-1.703 3.526L13 5l2.959-1.11q.04.3.041.61"/>\n  <path d="M11.5 9c.653 0 1.273-.139 1.833-.39L12 5.5 11 3l3.826-1.53A4.5 4.5 0 0 0 7.29 6.092l-6.116 5.096a2.583 2.583 0 1 0 3.638 3.638L9.908 8.71A4.5 4.5 0 0 0 11.5 9m-1.292-4.361-.596.893.809-.27a.25.25 0 0 1 .287.377l-.596.893.809-.27.158.475-1.5.5a.25.25 0 0 1-.287-.376l.596-.893-.809.27a.25.25 0 0 1-.287-.377l.596-.893-.809.27-.158-.475 1.5-.5a.25.25 0 0 1 .287.376M3 14a1 1 0 1 1 0-2 1 1 0 0 1 0 2"/>\n</svg>';
+const ban = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M15 8a6.97 6.97 0 0 0-1.71-4.584l-9.874 9.875A7 7 0 0 0 15 8M2.71 12.584l9.874-9.875a7 7 0 0 0-9.874 9.874ZM16 8A8 8 0 1 1 0 8a8 8 0 0 1 16 0"/>\n</svg>';
+const __vite_glob_0_0 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  default: ban
+}, Symbol.toStringTag, { value: "Module" }));
+const boxSeam = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M8.186 1.113a.5.5 0 0 0-.372 0L1.846 3.5l2.404.961L10.404 2zm3.564 1.426L5.596 5 8 5.961 14.154 3.5zm3.25 1.7-6.5 2.6v7.922l6.5-2.6V4.24zM7.5 14.762V6.838L1 4.239v7.923zM7.443.184a1.5 1.5 0 0 1 1.114 0l7.129 2.852A.5.5 0 0 1 16 3.5v8.662a1 1 0 0 1-.629.928l-7.185 2.874a.5.5 0 0 1-.372 0L.63 13.09a1 1 0 0 1-.63-.928V3.5a.5.5 0 0 1 .314-.464z"/>\n</svg>';
+const __vite_glob_0_1 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  default: boxSeam
+}, Symbol.toStringTag, { value: "Module" }));
+const exclamationTriangle = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M7.938 2.016A.13.13 0 0 1 8.002 2a.13.13 0 0 1 .063.016.15.15 0 0 1 .054.057l6.857 11.667c.036.06.035.124.002.183a.2.2 0 0 1-.054.06.1.1 0 0 1-.066.017H1.146a.1.1 0 0 1-.066-.017.2.2 0 0 1-.054-.06.18.18 0 0 1 .002-.183L7.884 2.073a.15.15 0 0 1 .054-.057m1.044-.45a1.13 1.13 0 0 0-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767z"/>\n  <path d="M7.002 12a1 1 0 1 1 2 0 1 1 0 0 1-2 0M7.1 5.995a.905.905 0 1 1 1.8 0l-.35 3.507a.552.552 0 0 1-1.1 0z"/>\n</svg>';
+const __vite_glob_0_2 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  default: exclamationTriangle
+}, Symbol.toStringTag, { value: "Module" }));
+const palette = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M8 5a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3m4 3a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3M5.5 7a1.5 1.5 0 1 1-3 0 1.5 1.5 0 0 1 3 0m.5 6a1.5 1.5 0 1 0 0-3 1.5 1.5 0 0 0 0 3"/>\n  <path d="M16 8c0 3.15-1.866 2.585-3.567 2.07C11.42 9.763 10.465 9.473 10 10c-.603.683-.475 1.819-.351 2.92C9.826 14.495 9.996 16 8 16a8 8 0 1 1 8-8m-8 7c.611 0 .654-.171.655-.176.078-.146.124-.464.07-1.119-.014-.168-.037-.37-.061-.591-.052-.464-.112-1.005-.118-1.462-.01-.707.083-1.61.704-2.314.369-.417.845-.578 1.272-.618.404-.038.812.026 1.16.104.343.077.702.186 1.025.284l.028.008c.346.105.658.199.953.266.653.148.904.083.991.024C14.717 9.38 15 9.161 15 8a7 7 0 1 0-7 7"/>\n</svg>';
+const __vite_glob_0_3 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  default: palette
+}, Symbol.toStringTag, { value: "Module" }));
+const personLock = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M11 5a3 3 0 1 1-6 0 3 3 0 0 1 6 0M8 7a2 2 0 1 0 0-4 2 2 0 0 0 0 4m0 5.996V14H3s-1 0-1-1 1-4 6-4q.845.002 1.544.107a4.5 4.5 0 0 0-.803.918A11 11 0 0 0 8 10c-2.29 0-3.516.68-4.168 1.332-.678.678-.83 1.418-.832 1.664zM9 13a1 1 0 0 1 1-1v-1a2 2 0 1 1 4 0v1a1 1 0 0 1 1 1v2a1 1 0 0 1-1 1h-4a1 1 0 0 1-1-1zm3-3a1 1 0 0 0-1 1v1h2v-1a1 1 0 0 0-1-1"/>\n</svg>';
+const __vite_glob_0_4 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  default: personLock
+}, Symbol.toStringTag, { value: "Module" }));
+const search = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M11.742 10.344a6.5 6.5 0 1 0-1.397 1.398h-.001q.044.06.098.115l3.85 3.85a1 1 0 0 0 1.415-1.414l-3.85-3.85a1 1 0 0 0-.115-.1zM12 6.5a5.5 5.5 0 1 1-11 0 5.5 5.5 0 0 1 11 0"/>\n</svg>';
+const __vite_glob_0_5 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  default: search
+}, Symbol.toStringTag, { value: "Module" }));
+const stopwatch = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M8.5 5.6a.5.5 0 1 0-1 0v2.9h-3a.5.5 0 0 0 0 1H8a.5.5 0 0 0 .5-.5z"/>\n  <path d="M6.5 1A.5.5 0 0 1 7 .5h2a.5.5 0 0 1 0 1v.57c1.36.196 2.594.78 3.584 1.64l.012-.013.354-.354-.354-.353a.5.5 0 0 1 .707-.708l1.414 1.415a.5.5 0 1 1-.707.707l-.353-.354-.354.354-.013.012A7 7 0 1 1 7 2.071V1.5a.5.5 0 0 1-.5-.5M8 3a6 6 0 1 0 .001 12A6 6 0 0 0 8 3"/>\n</svg>';
+const __vite_glob_0_6 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  default: stopwatch
+}, Symbol.toStringTag, { value: "Module" }));
+const wifiOff = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M10.706 3.294A12.6 12.6 0 0 0 8 3C5.259 3 2.723 3.882.663 5.379a.485.485 0 0 0-.048.736.52.52 0 0 0 .668.05A11.45 11.45 0 0 1 8 4q.946 0 1.852.148zM8 6c-1.905 0-3.68.56-5.166 1.526a.48.48 0 0 0-.063.745.525.525 0 0 0 .652.065 8.45 8.45 0 0 1 3.51-1.27zm2.596 1.404.785-.785q.947.362 1.785.907a.482.482 0 0 1 .063.745.525.525 0 0 1-.652.065 8.5 8.5 0 0 0-1.98-.932zM8 10l.933-.933a6.5 6.5 0 0 1 2.013.637c.285.145.326.524.1.75l-.015.015a.53.53 0 0 1-.611.09A5.5 5.5 0 0 0 8 10m4.905-4.905.747-.747q.886.451 1.685 1.03a.485.485 0 0 1 .047.737.52.52 0 0 1-.668.05 11.5 11.5 0 0 0-1.811-1.07M9.02 11.78c.238.14.236.464.04.66l-.707.706a.5.5 0 0 1-.707 0l-.707-.707c-.195-.195-.197-.518.04-.66A2 2 0 0 1 8 11.5c.374 0 .723.102 1.021.28zm4.355-9.905a.53.53 0 0 1 .75.75l-10.75 10.75a.53.53 0 0 1-.75-.75z"/>\n</svg>';
+const __vite_glob_0_7 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  default: wifiOff
+}, Symbol.toStringTag, { value: "Module" }));
+const wrenchAdjustable = '<svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" fill="currentColor" viewBox="0 0 16 16">\n  <path d="M16 4.5a4.5 4.5 0 0 1-1.703 3.526L13 5l2.959-1.11q.04.3.041.61"/>\n  <path d="M11.5 9c.653 0 1.273-.139 1.833-.39L12 5.5 11 3l3.826-1.53A4.5 4.5 0 0 0 7.29 6.092l-6.116 5.096a2.583 2.583 0 1 0 3.638 3.638L9.908 8.71A4.5 4.5 0 0 0 11.5 9m-1.292-4.361-.596.893.809-.27a.25.25 0 0 1 .287.377l-.596.893.809-.27.158.475-1.5.5a.25.25 0 0 1-.287-.376l.596-.893-.809.27a.25.25 0 0 1-.287-.377l.596-.893-.809.27-.158-.475 1.5-.5a.25.25 0 0 1 .287.376M3 14a1 1 0 1 1 0-2 1 1 0 0 1 0 2"/>\n</svg>';
+const __vite_glob_0_8 = /* @__PURE__ */ Object.freeze(/* @__PURE__ */ Object.defineProperty({
+  __proto__: null,
+  default: wrenchAdjustable
+}, Symbol.toStringTag, { value: "Module" }));
 const styles = css`
   :host {
     display: flex;
@@ -392,9 +439,19 @@ var __decorateClass = (decorators, target, key, kind) => {
   if (kind && result) __defProp(target, key, result);
   return result;
 };
-const icons = Object.entries(/* @__PURE__ */ Object.assign({ "../assets/ban.svg": __vite_glob_0_0, "../assets/box-seam.svg": __vite_glob_0_1, "../assets/exclamation-triangle.svg": __vite_glob_0_2, "../assets/palette.svg": __vite_glob_0_3, "../assets/person-lock.svg": __vite_glob_0_4, "../assets/search.svg": __vite_glob_0_5, "../assets/stopwatch.svg": __vite_glob_0_6, "../assets/wifi-off.svg": __vite_glob_0_7, "../assets/wrench-adjustable.svg": __vite_glob_0_8 })).reduce((acc, [path, content]) => {
+const icons = Object.entries(/* @__PURE__ */ Object.assign({
+  "../assets/ban.svg": __vite_glob_0_0,
+  "../assets/box-seam.svg": __vite_glob_0_1,
+  "../assets/exclamation-triangle.svg": __vite_glob_0_2,
+  "../assets/palette.svg": __vite_glob_0_3,
+  "../assets/person-lock.svg": __vite_glob_0_4,
+  "../assets/search.svg": __vite_glob_0_5,
+  "../assets/stopwatch.svg": __vite_glob_0_6,
+  "../assets/wifi-off.svg": __vite_glob_0_7,
+  "../assets/wrench-adjustable.svg": __vite_glob_0_8
+})).reduce((acc, [path, content]) => {
   const name = path.split("/").pop()?.replace(".svg", "") || "";
-  acc[name] = content;
+  acc[name] = content.default;
   return acc;
 }, {});
 let ErrorPage = class extends LitElement {
@@ -402,7 +459,7 @@ let ErrorPage = class extends LitElement {
     const error = this.error || this.getDefaultError();
     const icon = this.getErrorIcon(error.code);
     return html`
-      <div class="icon">${icon}</div>
+      <div class="icon">${unsafeHTML(icon)}</div>
       <div class="code">${error.code}</div>
       <div class="message">${error.message}</div>
     `;
@@ -417,25 +474,25 @@ let ErrorPage = class extends LitElement {
     const numericCode = typeof code === "string" ? parseInt(code) : code;
     switch (codeStr) {
       case "OUTLET_NOT_FOUND":
-        return unsafeSVG(icons["box-seam"] || "📦");
+        return icons["box-seam"] || "📦";
       case "CONTENT_LOAD_FAILED":
-        return unsafeSVG(icons["wifi-off"] || "📡");
+        return icons["wifi-off"] || "📡";
       case "RENDER_FAILED":
-        return unsafeSVG(icons["palette"] || "🎨");
+        return icons["palette"] || "🎨";
     }
     switch (numericCode) {
       case 404:
-        return unsafeSVG(icons["search"] || "🔍");
+        return icons["search"] || "🔍";
       case 403:
-        return unsafeSVG(icons["ban"] || "🚫");
+        return icons["ban"] || "🚫";
       case 401:
-        return unsafeSVG(icons["person-lock"] || "🔐");
+        return icons["person-lock"] || "🔐";
       case 429:
-        return unsafeSVG(icons["stopwatch"] || "⏱️");
+        return icons["stopwatch"] || "⏱️";
       case 503:
-        return unsafeSVG(icons["wrench-adjustable"] || "🛠️");
+        return icons["wrench-adjustable"] || "🛠️";
       default:
-        return unsafeSVG(icons["exclamation-triangle"] || "⚠️");
+        return icons["exclamation-triangle"] || "⚠️";
     }
   }
 };
@@ -491,51 +548,41 @@ function findAnchorFromEvent(e2) {
 function setRoutes(routes, basepath) {
   for (const route of routes) {
     route.id ||= getRandomID();
-    if ("index" in route && route.index) {
+    if (route.index === true) {
       route.path = new URLPattern({ pathname: `${basepath}{/}?` });
-    } else if ("path" in route && route.path) {
+      route.force ||= true;
+    } else {
       if (typeof route.path === "string") {
         const absolutePathStr = absolutePath(basepath, route.path);
         route.path = new URLPattern({ pathname: `${absolutePathStr}{/}?` });
+      } else if (route.path instanceof URLPattern) ;
+      else {
+        route.path = new URLPattern({ pathname: `${basepath}{/}?` });
       }
-    } else {
-      throw new Error('Route must have either "index" or "path" property defined.');
-    }
-    if (route.children && route.children.length > 0) {
-      let childBasepath;
-      if ("index" in route) {
-        childBasepath = basepath;
+      if (route.children && route.children.length > 0) {
+        const childBasepath = route.path.pathname.replace("{/}?", "");
+        route.children = setRoutes(route.children, childBasepath);
+        route.force ||= false;
       } else {
-        if (typeof route.path === "string") {
-          childBasepath = absolutePath(basepath, route.path);
-        } else {
-          childBasepath = route.path.pathname.replace("{/}?", "");
-        }
+        route.force ||= true;
       }
-      route.children = setRoutes(route.children, childBasepath);
-      route.force ||= false;
-    } else {
-      route.force ||= true;
     }
   }
   return routes;
 }
 function getRoutes(pathname, routes) {
   for (const route of routes) {
-    if (route.children) {
+    if (route.index !== true && route.children && route.children.length > 0) {
       const childRoutes = getRoutes(pathname, route.children);
       if (childRoutes.length > 0) {
         return [route, ...childRoutes];
       }
     }
-    let matches = false;
-    if ("index" in route && route.index && route.path) {
-      matches = route.path.test({ pathname });
-    } else if ("path" in route && route.path instanceof URLPattern) {
-      matches = route.path.test({ pathname });
-    }
-    if (matches) {
-      return [route];
+    if (route.path instanceof URLPattern) {
+      const isMatch = route.path.test({ pathname });
+      if (isMatch) return [route];
+    } else {
+      throw new Error("Route path must be an instance of URLPattern, Something wrong in setRoutes function.");
     }
   }
   return [];
@@ -565,44 +612,36 @@ class Router {
     };
     this._rootElement = config.root;
     this._basepath = absolutePath(config.basepath || "/");
-    this._routes = setRoutes(config.routes, this._basepath);
-    this.waitConnected();
+    this._routes = setRoutes(config.routes || [], this._basepath);
+    this._fallback = config.fallback;
     window.removeEventListener("popstate", this.handleWindowPopstate);
     window.addEventListener("popstate", this.handleWindowPopstate);
     if (config.useIntercept !== false) {
       this._rootElement.removeEventListener("click", this.handleRootClick);
       this._rootElement.addEventListener("click", this.handleRootClick);
     }
-  }
-  /** 초기 라우팅 처리, TODO: 제거 */
-  async waitConnected() {
-    let outlet = findOutlet(this._rootElement);
-    let count = 0;
-    while (!outlet && count < 20) {
-      await new Promise((resolve) => setTimeout(resolve, 50));
-      outlet = findOutlet(this._rootElement);
-      count++;
+    if (config.initialLoad !== false) {
+      void this.go(window.location.href);
     }
-    this.handleWindowPopstate();
   }
   /** 객체를 정리하고 이벤트 리스너를 제거합니다. */
   destroy() {
     window.removeEventListener("popstate", this.handleWindowPopstate);
     this._rootElement.removeEventListener("click", this.handleRootClick);
-    this._routeInfo = void 0;
     this._requestID = void 0;
+    this._context = void 0;
   }
   /** 라우터의 기본 경로 반환 */
   get basepath() {
     return this._basepath;
   }
-  /** 등록된 라우트 반환 */
+  /** 등록된 라우트 정보 반환 */
   get routes() {
     return this._routes;
   }
   /** 현재 라우팅 정보 반환 */
-  get routeInfo() {
-    return this._routeInfo;
+  get context() {
+    return this._context;
   }
   /**
    * 지정한 경로의 클라이언트 라우팅을 수행합니다. 상대경로일 경우 basepath와 조합되어 이동합니다.
@@ -611,34 +650,48 @@ class Router {
   async go(href) {
     const requestID = getRandomID();
     this._requestID = requestID;
-    const routeInfo = parseUrl(href, this._basepath);
-    if (routeInfo.href === this._routeInfo?.href) return;
+    const context = parseUrl(href, this._basepath);
+    if (context.href === this._context?.href) return;
+    const progressCallback = (value) => {
+      if (this._requestID !== requestID) return;
+      const progress = Math.max(0, Math.min(100, Math.round(value)));
+      window.dispatchEvent(new RouteProgressEvent(context, progress));
+    };
+    context.progress = progressCallback;
+    if (context.href !== window.location.href) {
+      window.history.pushState({ basepath: context.basepath }, "", context.href);
+    } else {
+      window.history.replaceState({ basepath: context.basepath }, "", context.href);
+    }
     let outlet = void 0;
     try {
       if (this._requestID !== requestID) return;
-      window.dispatchEvent(new RouteBeginEvent(routeInfo));
-      const routes = getRoutes(routeInfo.pathname, this._routes);
+      window.dispatchEvent(new RouteBeginEvent(context));
+      const routes = getRoutes(context.pathname, this._routes);
       const lastRoute = routes[routes.length - 1];
-      if (lastRoute && "path" in lastRoute && lastRoute.path instanceof URLPattern) {
-        routeInfo.params = lastRoute.path.exec({ pathname: routeInfo.pathname })?.pathname.groups || {};
+      if (lastRoute && lastRoute.path instanceof URLPattern) {
+        context.params = lastRoute.path.exec({ pathname: context.pathname })?.pathname.groups || {};
       }
-      this._routeInfo = routeInfo;
-      window.route = routeInfo;
+      this._context = context;
       outlet = findOutletOrThrow(this._rootElement);
       let title = void 0;
       let content = null;
       let element = null;
       if (routes.length === 0) {
-        throw new NotFoundError(routeInfo.href);
+        throw new NotFoundError(context.href);
       }
       for (const route of routes) {
         if (this._requestID !== requestID) return;
         if (!route.render) continue;
         try {
-          content = await route.render(routeInfo);
+          content = await route.render(context);
+          if (content === false || content === null) {
+            throw new Error("Failed to load content for the route.");
+          }
         } catch (LoadError) {
           throw new ContentLoadError(LoadError);
         }
+        if (this._requestID !== requestID) return;
         try {
           element = await outlet.renderContent({ id: route.id, content, force: route.force });
         } catch (renderError) {
@@ -648,29 +701,29 @@ class Router {
         title = route.title || title;
       }
       document.title = title || document.title;
-      if (this._requestID !== requestID) return;
-      if (routeInfo.href !== window.location.href) {
-        window.history.pushState({ basepath: routeInfo.basepath }, "", routeInfo.href);
-      } else {
-        window.history.replaceState({ basepath: routeInfo.basepath }, "", routeInfo.href);
-      }
-      window.dispatchEvent(new RouteDoneEvent(routeInfo));
+      window.dispatchEvent(new RouteDoneEvent(context));
     } catch (error) {
       const routeError = error instanceof RouteError ? error : new RouteError(
         error.status || error.code || "UNKNOWN_ERROR",
         error.message || "An unexpected error occurred",
         error
       );
-      window.dispatchEvent(new RouteErrorEvent(routeError, routeInfo));
-      console.error("Routing error:", error.original || error);
+      window.dispatchEvent(new RouteErrorEvent(context, routeError));
+      console.error("Routing error:", routeError.original);
       try {
-        const errorPage = new ErrorPage();
-        errorPage.error = error;
-        if (outlet) {
-          outlet.renderContent({ id: "#", content: errorPage, force: true });
+        if (this._fallback && this._fallback.render && outlet) {
+          const fallbackContent = await this._fallback.render({ ...context, error: routeError });
+          outlet.renderContent({ id: "#fallback", content: fallbackContent, force: true });
+          document.title = this._fallback.title || document.title;
         } else {
-          document.body.innerHTML = "";
-          document.body.appendChild(errorPage);
+          const errorContent = new ErrorPage();
+          errorContent.error = error;
+          if (outlet) {
+            outlet.renderContent({ id: "#error", content: errorContent, force: true });
+          } else {
+            document.body.innerHTML = "";
+            document.body.appendChild(errorContent);
+          }
         }
       } catch (pageError) {
         console.error("Failed to render error component:", pageError);
@@ -690,6 +743,7 @@ export {
   RouteDoneEvent,
   RouteError,
   RouteErrorEvent,
+  RouteProgressEvent,
   Router,
   ULink,
   UOutlet

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/router",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "A modern client-side router for web applications with support for Lit and React components",
   "keywords": [
     "lit",
@@ -42,7 +42,7 @@
   "devDependencies": {
     "@lit/react": "^1.0.8",
     "@types/node": "^24.10.1",
-    "@types/react": "^19.2.4",
+    "@types/react": "^19.2.5",
     "@types/react-dom": "^19.2.3",
     "typescript": "^5.9.3",
     "vite": "^7.2.2",