@iyulab/router 0.9.3 → 0.10.1

package/dist/index.js

@@ -1,4 +1,4 @@
-import { a as isExternalUrl, i as absolutePath, n as __decorate, o as parseUrl, r as __decorateMetadata, s as UOutlet, t as ULink } from "./share-DC0R4F2d.js";
+import { a as isExternalUrl, i as absolutePath, n as __decorate, o as parseUrl, r as __decorateMetadata, s as UOutlet, t as ULink } from "./share-C2LbLiIW.js";
 import { LitElement, css, html } from "lit";
 import { customElement, property } from "lit/decorators.js";
 //#region src/types/RouteError.ts
@@ -113,7 +113,6 @@ var RouteErrorEvent = class extends RouteEvent {
 };
 //#endregion
 //#region src/components/UErrorPage.ts
-var _ref, _ref2;
 var UErrorPage = class UErrorPage extends LitElement {
 	constructor(error) {
 		super();
@@ -205,8 +204,8 @@ var UErrorPage = class UErrorPage extends LitElement {
   `;
 	}
 };
-__decorate([property({ type: Object }), __decorateMetadata("design:type", typeof (_ref2 = typeof RouteError !== "undefined" && RouteError) === "function" ? _ref2 : Object)], UErrorPage.prototype, "error", void 0);
-UErrorPage = __decorate([customElement("u-error-page"), __decorateMetadata("design:paramtypes", [typeof (_ref = typeof RouteError !== "undefined" && RouteError) === "function" ? _ref : Object])], UErrorPage);
+__decorate([property({ type: Object }), __decorateMetadata("design:type", typeof RouteError === "undefined" ? Object : RouteError)], UErrorPage.prototype, "error", void 0);
+UErrorPage = __decorate([customElement("u-error-page"), __decorateMetadata("design:paramtypes", [typeof RouteError === "undefined" ? Object : RouteError])], UErrorPage);
 //#endregion
 //#region src/internals/crypto-helpers.ts
 /**
@@ -217,7 +216,7 @@ UErrorPage = __decorate([customElement("u-error-page"), __decorateMetadata("desi
 * @return 랜덤한 ID 문자열
 */
 function getRandomID() {
-	return window.isSecureContext ? window.crypto.randomUUID() : window.crypto.getRandomValues(new Uint32Array(1))[0].toString(16);
+	return window.isSecureContext ? window.crypto.randomUUID() : window.crypto.getRandomValues(/* @__PURE__ */ new Uint32Array(1))[0].toString(16);
 }
 //#endregion
 //#region src/internals/element-helpers.ts
@@ -402,7 +401,9 @@ var Router = class {
 				if (anchor.hasAttribute("download")) return;
 				if (anchor.getAttribute("rel") === "external") return;
 				if (anchor.target && anchor.target !== "") return;
-				if (this._basepath !== "/" && !new URL(anchor.href).pathname.startsWith(this._basepath)) return;
+				const pathname = new URL(anchor.href).pathname;
+				if (this._basepath !== "/" && !pathname.startsWith(this._basepath)) return;
+				if (getRoutes(this._routes, pathname).length === 0) return;
 				e.preventDefault();
 				await this.go(anchor.href);
 			} catch {}

package/dist/internals/RouteTracker.d.ts

@@ -0,0 +1,22 @@
+import { RouteConfig } from '../types/RouteConfig.js';
+/**
+ * 라우팅 체인 상태를 추적합니다.
+ * - 방문한 href를 기록하여 리다이렉트 사이클을 감지합니다.
+ * - 이미 실행된 route enter를 기록하여 중복 실행을 방지합니다.
+ */
+export declare class RouteTracker {
+    private readonly _history;
+    private readonly _processed;
+    /** 새 네비게이션 시작 시 상태를 초기화합니다. */
+    reset(): void;
+    /**
+     * href 방문을 기록하고 사이클 여부를 반환합니다.
+     * @returns 사이클이 감지되면 true
+     */
+    visit(href: string): boolean;
+    /**
+     * route enter를 아직 실행하지 않았다면 키를 등록하고 true를 반환합니다.
+     * 이미 실행된 route라면 false를 반환합니다 (중첩 라우트 redirect 체인에서 중복 방지).
+     */
+    enter(route: RouteConfig): boolean;
+}

package/dist/internals/crypto-helpers.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 브라우저에서 랜덤한 문자열ID를 생성합니다.
+ * - https일 경우 crypto.randomUUID()를 사용합니다.
+ * - 그 외의 경우 crypto.getRandomValues()를 사용합니다.
+ *
+ * @return 랜덤한 ID 문자열
+ */
+export declare function getRandomID(): string;

package/dist/internals/element-helpers.d.ts

@@ -0,0 +1,36 @@
+import { UOutlet } from '../components/UOutlet';
+/**
+ * `u-outlet` 엘리먼트를 찾아 반환합니다.
+ *
+ * @param element 검색을 시작할 HTMLElement
+ * @param skip element 자신을 검사에서 제외할지 여부 (기본값: false)
+ * @returns 찾은 UOutlet 엘리먼트 또는 undefined
+ */
+export declare function findOutlet(element: HTMLElement, skip?: boolean): UOutlet | undefined;
+/**
+ * `u-outlet` 엘리먼트를 찾아 반환합니다. 없으면 에러를 던집니다.
+ *
+ * @param element 검색을 시작할 HTMLElement
+ * @param skip element 자신을 검사에서 제외할지 여부 (기본값: false)
+ *
+ * @returns 찾은 UOutlet 엘리먼트
+ * @throws OutletMissingError `u-outlet` 엘리먼트를 찾지 못한 경우
+ */
+export declare function findOutletOrThrow(element: HTMLElement, skip?: boolean): UOutlet;
+/**
+ * 주어진 엘리먼트 내에서 `u-outlet`이 준비될 때까지 대기합니다.
+ *
+ * @param element 대기할 엘리먼트
+ * @param timeout 타임아웃 시간(밀리초, 기본값: 10_000ms)
+ * @param skip element 자신을 검사에서 제외할지 여부 (기본값: false)
+ *
+ * @returns 준비된 `u-outlet` 엘리먼트
+ */
+export declare function waitOutlet(element: HTMLElement, timeout?: number, skip?: boolean): Promise<UOutlet>;
+/**
+ * 이벤트에서 composedPath()/closest를 사용하여 A 태그를 찾아 반환합니다.
+ *
+ * @param event 이벤트 객체
+ * @returns 찾은 A 태그 엘리먼트 또는 null
+ */
+export declare function findAnchorFrom(event: Event): HTMLAnchorElement | null;

package/dist/internals/route-helpers.d.ts

@@ -0,0 +1,21 @@
+import { RouteConfig } from '../types/RouteConfig';
+/**
+ * 라우트들을 다음 사항에 따라 재귀적으로 재설정합니다.
+ * - 각 라우트에 고유 `id`를 랜덤하게 부여합니다.
+ * - `path`를 URLPattern 객체로 변환합니다.
+ * - 자식 라우트가 있으면 재귀적으로 재설정합니다.
+ *
+ * @param routes 설정할 라우트 배열
+ * @param basepath 기준이 되는 basepath 문자열
+ * @returns 재설정된 라우트 배열
+ */
+export declare function setRoutes(routes: RouteConfig[], basepath: string): RouteConfig[];
+/**
+ * URLPattern을 사용하여 경로와 일치하는 라우트들을 자식 라우트까지 포함하여 반환합니다.
+ * 반환된 배열은 상위 라우트부터 하위 라우트 순서로 정렬됩니다.
+ *
+ * @param routes 검사할 라우트 배열
+ * @param pathname 검사할 경로 이름
+ * @returns 일치하는 라우트 배열
+ */
+export declare function getRoutes(routes: RouteConfig[], pathname: string): RouteConfig[];

package/dist/internals/url-helpers.d.ts

@@ -0,0 +1,38 @@
+import { RouteContext } from '../types/RouteContext';
+/**
+ * 주어진 URL이 외부 링크인지 확인합니다.
+ *
+ * @param url 확인할 URL 문자열
+ * @return 외부 링크인 경우 true, 내부 링크인 경우 false
+ */
+export declare function isExternalUrl(url: string): boolean;
+/**
+ * URL 문자열을 파싱하여 RouteContext 객체로 반환합니다.
+ * - http(s)로 시작하는 절대 URL은 외부 링크로 간주됩니다.
+ * - 절대경로(/...)는 그대로 사용됩니다.
+ * - 상대경로는 basepath를 기준으로 절대경로로 변환됩니다.
+ * - 쿼리스트링(?)로 시작하는 쿼리는 현재 경로와 추가됩니다.
+ * - 해시(#)로 시작하는 해시는 현재 경로와 추가됩니다.
+ *
+ * @param url 파싱할 URL 문자열
+ * @param basepath 기준이 되는 basepath 문자열
+ * @returns 파싱된 RouteContext 객체
+ */
+export declare function parseUrl(url: string, basepath: string): RouteContext;
+/**
+ * pathname 경로를 조합하여 절대경로를 반환합니다.
+ *
+ * @param paths 조합할 경로 문자열들
+ * @returns 조합된 절대경로 문자열
+ */
+export declare function absolutePath(...paths: string[]): string;
+/**
+ * basepath가 동적 패턴일 경우(RouteConfig에서 basepath가 :id 등으로 정의된 경우),
+ * 현재 경로에서 해당되는 패턴의 basepath를 추출하여 반환합니다.
+ *
+ * @param basepath 동적 패턴이 포함된 basepath 문자열
+ * @return 현재 경로에 매칭되는 basepath 문자열
+ * @example
+ * catchBasePath('/app/:id') => '/app/123'
+ */
+export declare function catchBasepath(basepath: string): string;

package/dist/react.d.ts

@@ -1,100 +1,10 @@
-import { CSSResult } from 'lit';
-import { LitElement } from 'lit';
-import { PropertyValues } from 'lit';
-import { ReactWebComponent } from '@lit/react';
-import { TemplateResult } from 'lit-html';
-
-/** 렌더링 옵션 */
-declare interface RenderOption {
-    /** 교차 렌더링 방지 ID */
-    id?: string;
-    /** 강제 렌더링 여부 */
-    force?: boolean;
-}
-
-/**
- * `u-link` 웹 컴포넌트를 React에서 사용할 수 있도록 래핑한 컴포넌트입니다.
- */
-export declare const ULink: ReactWebComponent<ULink_2, {}>;
-
-/**
- * - 클라이언트 라우팅을 지원하는 링크 엘리먼트입니다.
- * - 내부 링크는 클라이언트 라우팅을 수행하고, 외부 링크는 브라우저 기본 네비게이션을 사용합니다.
- * - Ctrl/Meta/Shift/Alt, 중클릭/우클릭 등은 브라우저 기본 동작(새 탭, 컨텍스트 메뉴 등)을 그대로 유지합니다.
- */
-declare class ULink_2 extends LitElement {
-    /** 외부 링크 여부 */
-    private isExternal;
-    /**
-     * 링크 대상 target 속성
-     *
-     * - `_self`: 현재 창에서 링크 열기 (기본값)
-     * - `_blank`: 새 탭/창에서 링크 열기
-     * - `_parent`: 부모 프레임에서 링크 열기
-     * - `_top`: 최상위 프레임에서 링크 열기
-     */
-    target?: string;
-    /**
-     * 링크 관계 rel 속성
-     *
-     * - `noopener`: target이 _blank인 경우 보안 강화 (window.opener 차단)
-     * - `noreferrer`: target이 _blank인 경우 보안 강화 + Referer 헤더 제거
-     * - `external`: 외부 링크임을 명시 (SEO/접근성에 도움)
-     * - `nofollow`: 검색 엔진이 링크를 따라가지 않도록 지시 (SEO에 영향)
-     * - 그 외 rel 값도 그대로 전달됩니다.
-     */
-    rel?: string;
-    /**
-     * 링크 대상 URL, 다음 사항에 따라 SPA 라우팅 또는 브라우저 네비게이션이 결정됩니다.
-     *
-     * - 속성을 정의하지 않으면 설정에서 지정한 `basepath`로 SPA 라우팅합니다.
-     * - http(s)로 시작하면 외부 링크로 간주하고 브라우저 네비게이션을 사용합니다.
-     * - 절대경로(/...)의 경우 `basepath`로 시작하면 SPA 라우팅합니다, 이외 브라우저 네비게이션을 사용합니다.
-     * - 상대경로는 (basepath + 상대경로)로 결합하여 SPA 라우팅합니다.
-     * - ?로 시작하면 현재 경로에 쿼리스트링을 추가하여 SPA 라우팅합니다.
-     * - #으로 시작하면 브라우저 기본 동작을 사용합니다.
-     */
-    href?: string;
-    connectedCallback(): void;
-    disconnectedCallback(): void;
-    protected willUpdate(changedProperties: PropertyValues): void;
-    render(): TemplateResult<1>;
-    /** a 태그에 주입할 href 값을 계산합니다. */
-    private compute;
-    /**
-     * 클릭 가로채기 핸들러
-     * - 좌클릭(0) + 보조키 없음(ctrl/meta/shift/alt 없음) + target이 _self일 때만 SPA 라우팅 고려
-     * - 그 외(중클릭/우클릭/보조키/target=_blank 등)는 브라우저 기본 동작 유지
-     */
-    private handleClick;
-    /** 클라이언트 라우팅을 위해 popstate 이벤트를 발생시킵니다. */
-    private dispatchPopstate;
-    /** basepath를 state에서 꺼내는 헬퍼 */
-    private getBasepath;
-    static styles: CSSResult;
-}
-
-/**
- * `u-outlet` 웹 컴포넌트를 React에서 사용할 수 있도록 래핑한 컴포넌트입니다.
- */
-export declare const UOutlet: ReactWebComponent<UOutlet_2, {}>;
-
-/**
- * LitElement 또는 React 컴포넌트를 렌더링해주는 웹컴포넌트 입니다.
- */
-declare class UOutlet_2 extends HTMLElement {
-    /** 교차 렌더링 방지 id */
-    private routeId?;
-    /** 실제 렌더링 컨텐츠 */
-    private root?;
-    /**
-     * 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
-     */
-    render(value: unknown, options?: RenderOption): Promise<void>;
-    /**
-     * 기존 DOM을 삭제하여, 초기 상태로 되돌립니다.
-     */
-    reset(): void;
-}
-
-export { }
+import { ULink as ULinkElement } from './components/ULink.js';
+import { UOutlet as UOutletElement } from './components/UOutlet.js';
+/**
+ * `u-link` 웹 컴포넌트를 React에서 사용할 수 있도록 래핑한 컴포넌트입니다.
+ */
+export declare const ULink: import('@lit/react').ReactWebComponent<ULinkElement, {}>;
+/**
+ * `u-outlet` 웹 컴포넌트를 React에서 사용할 수 있도록 래핑한 컴포넌트입니다.
+ */
+export declare const UOutlet: import('@lit/react').ReactWebComponent<UOutletElement, {}>;

package/dist/react.js

@@ -1,4 +1,4 @@
-import { s as UOutlet$1, t as ULink$1 } from "./share-DC0R4F2d.js";
+import { s as UOutlet$1, t as ULink$1 } from "./share-C2LbLiIW.js";
 import React from "react";
 import { createComponent } from "@lit/react";
 //#region src/react.ts

package/dist/{share-DC0R4F2d.js → share-C2LbLiIW.js}

@@ -126,12 +126,12 @@ function catchBasepath(basepath) {
 	return basepath;
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.127.0/helpers/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.138.0/helpers/esm/decorateMetadata.js
 function __decorateMetadata(k, v) {
 	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.127.0/helpers/decorate.js
+//#region \0@oxc-project+runtime@0.138.0/helpers/esm/decorate.js
 function __decorate(decorators, target, key, desc) {
 	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
 	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);

package/dist/types/NavigateOptions.d.ts

@@ -0,0 +1,25 @@
+/**
+ * go() 메서드에 전달할 네비게이션 옵션
+ */
+export interface NavigateOptions {
+    /**
+     * 리다이렉트로 인한 네비게이션 여부.
+     * - `true`이면 히스토리에 새 항목을 추가하지 않고 현재 항목을 교체합니다(replaceState).
+     * - 뒤로가기 버튼이 리다이렉트 경유지를 건너뛰게 됩니다.
+     * - 리다이렉트 사이클 감지에 사용됩니다.
+     * @default false
+     */
+    isRedirect?: boolean;
+    /**
+     * 히스토리에 새 항목을 추가하지 않고 현재 항목을 교체합니다(replaceState).
+     * - `isRedirect`와 달리 리다이렉트 체인 추적에는 영향을 주지 않습니다.
+     * @default false
+     */
+    replace?: boolean;
+    /**
+     * pushState / replaceState 호출 시 함께 저장할 커스텀 상태 객체.
+     * - `history.state`로 다시 읽을 수 있습니다.
+     * @example { from: '/login', referrer: 'email-link' }
+     */
+    state?: Record<string, unknown>;
+}

package/dist/types/RouteConfig.d.ts

@@ -0,0 +1,133 @@
+import { RouteContext, FallbackRouteContext } from './RouteContext';
+/**
+ * 공통 라우트 속성
+ */
+interface BaseRouteConfig {
+    /**
+     * 라우터에서 사용하는 식별자
+     */
+    id?: string;
+    /**
+     * 브라우저의 타이틀이 설정에 따라 변경됩니다.
+     */
+    title?: string;
+    /**
+     * 라우터 경로는 string 또는 URLPattern을 사용할 수 있습니다.
+     * string일 경우 자동으로 URLPattern으로 변환됩니다.
+     * @default '/'
+     * @example
+     * - "/user/:id/:name"
+     * - "/user/:id/:name?"
+     * - "/user/:id/:name*"
+     * - "/user/:id/:name+"
+     * @link
+     * https://developer.mozilla.org/en-US/docs/Web/API/URLPattern
+     */
+    path?: string | URLPattern;
+    /**
+     * 라우트 정보를 받아 렌더링 결과를 반환합니다.
+     * @param ctx 현재 라우팅 정보 및, 진행 상태 콜백을 포함하는 Context 객체가 인자로 전달됩니다.
+     * @example
+     * ```typescript
+     * const route = {
+     *    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>`;
+     *   }
+     * }
+     * ```
+     * @remarks
+     * `render`는 Lit `TemplateResult`, `HTMLElement`, **또는 React 엘리먼트**를 반환할 수 있습니다.
+     * React 엘리먼트를 직접 반환하면 내부 `<u-outlet>`이 `createRoot`/`root.unmount()`를
+     * 자동으로 관리합니다 — React 루트를 직접 만들어 컨테이너 `HTMLElement`로 감싸 반환하면
+     * 이 자동 해제 지점을 우회하게 되어 라우트 전환마다 unmount가 호출되지 않는 누수가 생깁니다.
+     * @example
+     * ```tsx
+     * const route = {
+     *   path: '/users/:id',
+     *   render: (ctx) => <UserProfilePage userId={ctx.params.id} />, // React 엘리먼트를 직접 반환
+     * };
+     * ```
+     */
+    render?: (ctx: RouteContext) => Promise<unknown> | unknown;
+    /**
+     * 이 라우트 진입 전에 호출되는 enter 함수입니다.
+     * - `string` 반환: 해당 경로로 redirect
+     * - `false` 반환: 네비게이션 취소
+     * - `true` 반환: 통과
+     * @example
+     * ```typescript
+     * { path: '/admin', enter: (ctx) => ctx.metadata.role === 'admin' || '/forbidden' }
+     * ```
+     */
+    enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
+    /**
+     * 라우터 URL 변경시 렌더링을 강제할지 여부
+     * - 기본값으로 children을 가질때 false로 설정되며, children이 없을 경우 true로 설정됩니다.
+     * - true로 설정하면 기존 렌더링을 무시하고 새로 렌더링합니다.
+     */
+    force?: boolean;
+    /**
+     * 경로 매칭시 대소문자 구분 여부
+     * @default false
+     */
+    ignoreCase?: boolean;
+    /**
+     * 라우트에 연결할 메타데이터
+     * - 인증, SEO, 분석 등의 용도로 사용할 수 있습니다.
+     * @example
+     * ```typescript
+     * { path: '/admin', metadata: { requiresAuth: true, role: 'admin' } }
+     * ```
+     */
+    metadata?: Record<string, unknown>;
+}
+interface IndexRouteConfig extends BaseRouteConfig {
+    /**
+     * 현재 경로의 인덱스 라우트임을 나타냅니다.
+     * - 인덱스 라우트는 부모 경로와 동일한 경로를 가지며, path는 자동으로 설정됩니다.
+     */
+    index: true;
+}
+interface NonIndexRouteConfig extends BaseRouteConfig {
+    /**
+     * 인덱스 라우트가 아님을 나타냅니다.
+     */
+    index?: false;
+    /**
+     * 하위 라우트 설정, 재귀적으로 RouteConfig 배열을 가질 수 있습니다.
+     * - 하위 라우트가 있는 경우, 부모 라우트의 경로를 기준으로 매칭됩니다.
+     */
+    children?: RouteConfig[];
+}
+export type RouteConfig = IndexRouteConfig | NonIndexRouteConfig;
+export interface FallbackRouteConfig {
+    /**
+     * 브라우저의 타이틀이 설정에 따라 변경됩니다.
+     */
+    title?: string;
+    /**
+     * 라우팅 실패 시 표시할 렌더링 결과를 반환합니다.
+     * - 오류가 발생할 경우 또는 렌더링 결과가 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>`;
+     *    }
+     * }
+     * ```
+     */
+    render?: (ctx: FallbackRouteContext) => Promise<unknown> | unknown;
+}
+export {};

package/dist/types/RouteContext.d.ts

@@ -0,0 +1,85 @@
+import { RouteError } from './RouteError';
+/**
+ * 라우터 정보
+ */
+export interface RouteContext {
+    /**
+     * 전체 URL 정보
+     * - 도메인 이름을 포함한 URL의 전체 경로입니다.
+     * @example https://www.iyulab.com/home/user/1?name=iyu#profile
+     */
+    href: string;
+    /**
+     * URL 도메인 이름
+     * - URL의 도메인 이름입니다.
+     * @example https://www.iyulab.com
+     */
+    origin: string;
+    /**
+     * 라우터 URL 기본 경로
+     * - 라우터의 현재 basepath입니다.
+     * @example
+     * if basepath is /app/:id
+     * set basepath to /app/123
+     */
+    basepath: string;
+    /**
+     * 라우터 URL 전체 경로
+     * - 도메인 이름을 제외한 URL의 전체 경로입니다.
+     * @example /home/user/1?name=iyu#profile
+     */
+    path: string;
+    /**
+     * 라우터 URL 절대 경로
+     * - 쿼리스트링과 해시를 제외한 URL 경로입니다.
+     * @example /home/user/1
+     */
+    pathname: string;
+    /**
+     * 라우터 URL 파라미터
+     * - URLPattern을 사용하여 파싱된 파라미터입니다.
+     * @example 만약 URL이 /user/:id/:name 일경우
+     * ```typescript
+     * const id = params.id;
+     * const name = params.name;
+     * ```
+     */
+    params: {
+        [key: string]: string | undefined;
+    };
+    /**
+     * 라우터 URL 쿼리스트링
+     * - URLSearchParams를 사용하여 파싱된 쿼리스트링입니다.
+     * @example 만약 URL이 ?page=1&size=10 일경우
+     * ```typescript
+     * const page = query.get('page');
+     * const size = query.get('size');
+     * ```
+     */
+    query: URLSearchParams;
+    /**
+     * 라우터 URL 해시
+     * - URL의 해시값입니다. 해시값은 하나만 사용할 수 있습니다.
+     * - #profile#user 두개 이상의 해시값은 하나로 취급합니다.
+     * @example #profile
+     */
+    hash?: string;
+    /**
+     * 현재 라우팅의 진행 상태를 업데이트하여, window 객체의 'route-progress' 이벤트를 트리거합니다.
+     * 여러 라우팅이 호출되는 경우, 가장 최근의 라우팅의 진행 상태만 반영되며, 나머지는 무시됩니다.
+     * @param value 진행 상태 값 (0~100)
+     */
+    progress: (value: number) => void;
+    /**
+     * 매칭된 라우트 체인의 병합된 메타데이터
+     * - 부모 라우트에서 자식 라우트 순서로 병합됩니다.
+     */
+    metadata: Record<string, unknown>;
+}
+export interface FallbackRouteContext extends RouteContext {
+    /**
+     * 라우팅 에러 정보
+     * - 라우팅 중 발생한 에러 정보를 포함합니다.
+     */
+    error: RouteError;
+}

package/dist/types/RouteError.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 라우팅 에러 정보
+ */
+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 NotFoundError extends RouteError {
+    constructor(path: string, original?: Error | any);
+}
+/**
+ * enter 가드가 false를 반환하여 접근이 거부되었을 때 발생하는 에러
+ */
+export declare class AccessDeniedError extends RouteError {
+    constructor(path: string);
+}
+/**
+ * u-outlet 요소를 찾을 수 없을 때 발생하는 에러
+ */
+export declare class OutletMissingError extends RouteError {
+    constructor();
+}
+/**
+ * 컨텐츠 로드시 나타나는 에러
+ */
+export declare class ContentLoadError extends RouteError {
+    constructor(original?: Error | any);
+}
+/**
+ * 컨텐츠 렌더링시 발생하는 에러
+ */
+export declare class ContentRenderError extends RouteError {
+    constructor(original?: Error | any);
+}

package/dist/types/RouteEvent.d.ts

@@ -0,0 +1,43 @@
+import { RouteContext } from './RouteContext';
+import { RouteError } from './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 RouteBeginEvent extends RouteEvent {
+    constructor(context: RouteContext);
+}
+/**
+ * 라우트 진행 이벤트
+ */
+export declare class RouteProgressEvent extends RouteEvent {
+    /** 진행 상태 값 (0~100) */
+    readonly progress: number;
+    constructor(context: RouteContext, progress: number);
+}
+/**
+ * 라우트 완료 이벤트
+ */
+export declare class RouteDoneEvent extends RouteEvent {
+    constructor(context: RouteContext);
+}
+/**
+ * 라우트 에러 이벤트
+ */
+export declare class RouteErrorEvent extends RouteEvent {
+    /** 에러 정보 */
+    readonly error: RouteError;
+    constructor(context: RouteContext, error: RouteError);
+}
+export {};