@iyulab/router 0.15.1 → 0.15.2

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.15.2] - 2026-09-23
+
+### Fixed
+
+- **A wide descendant no longer widens the route screen past the outlet.** 0.15.0 made
+  `<u-outlet>` a grid container without declaring a column track. The implicit column is `auto`,
+  and a grid item's default `min-width: auto` passes its content's minimum width up to the track,
+  so a wide table widened the whole screen — even inside an `overflow-x: auto` box — and anything
+  aligned to the screen's right edge, such as a toolbar's last button, was pushed off screen. The
+  track is now `minmax(0, 1fr)`: the screen is exactly as wide as the outlet, a narrow screen still
+  fills it, and wide content scrolls inside its own box. Print is unaffected (the outlet is a block
+  box there). The rule keeps zero specificity, so `u-outlet { grid-template-columns: auto; }`
+  restores the previous track.
+
 ## [0.15.1] - 2026-09-17
 
 ### Fixed

package/README.md

@@ -149,7 +149,7 @@ rules on whichever tree it is connected to (the document, or the shadow root if
 one):
 
 ```css
-:where(u-outlet) { display: grid; min-height: 100%; }
+:where(u-outlet) { display: grid; grid-template-columns: minmax(0, 1fr); min-height: 100%; }
 @media print { :where(u-outlet) { display: block; } }
 ```
 
@@ -181,6 +181,13 @@ The rule deliberately omits `align-content`; it relies on the initial `normal`.
 When the parent's own height is `auto`, `min-height: 100%` resolves to `auto` too, so ordinary
 document flow is unaffected.
 
+The column track is bound to the outlet's width with `minmax(0, 1fr)`. Without it the implicit
+column is `auto`, and a grid item's default `min-width: auto` passes its content's minimum width up
+to the track — so a wide table inside a screen widened the whole screen past the outlet, even when
+the table sat in an `overflow-x: auto` box, and anything aligned to the screen's right edge (a
+toolbar's last button) ended up off screen. With the track bound, the screen is exactly as wide as
+the outlet, a narrow screen still fills it, and wide content scrolls inside its own box.
+
 ### Printing
 
 In print media the outlet is a plain block box instead of a grid container. A grid container is
@@ -202,6 +209,7 @@ application writes wins, regardless of sheet order and without `!important`:
 
 ```css
 u-outlet { display: flex; }                    /* wins */
+u-outlet { grid-template-columns: auto; }      /* restores the 0.15.1 column track */
 u-outlet { display: contents; }                /* remove the box entirely */
 u-outlet { display: block; height: 100%; }     /* restores the 0.14.0 behavior */
 u-outlet { display: inline; }                  /* restores the pre-0.14.0 behavior */

package/dist/index.d.ts

@@ -1,9 +1,619 @@
-export * from './types/NavigateOptions';
-export * from './types/RouteConfig';
-export * from './types/RouteContext';
-export * from './types/RouteError';
-export * from './types/RouteEvent';
-export * from './types/RouterConfig';
-export * from './components/UOutlet';
-export * from './components/ULink';
-export { Router } from './Router';
+import { CSSResult } from 'lit';
+import { LitElement } from 'lit';
+import { PropertyValues } from 'lit';
+import { TemplateResult } from 'lit-html';
+
+/**
+ * enter 가드가 false를 반환하여 접근이 거부되었을 때 발생하는 에러
+ */
+export declare class AccessDeniedError extends RouteError {
+    constructor(path: string);
+}
+
+/**
+ * 공통 라우트 속성
+ */
+declare 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;
+    /**
+     * 이 라우트의 콘텐츠를 **언제 새로 만들 것인가**를 정하는 식별 키입니다.
+     *
+     * 네비게이션마다 `key(ctx)`를 계산해 직전 값과 비교합니다.
+     * - 키가 **바뀌면** 기존 콘텐츠를 내리고 새로 마운트합니다.
+     * - 키가 **같으면** 콘텐츠를 유지한 채 `render(ctx)`의 결과로 **제자리 갱신**합니다 —
+     *   Lit 템플릿은 같은 파트에 다시 렌더(DOM·요소 상태 유지, 바인딩만 갱신), React 엘리먼트는
+     *   같은 root에 다시 렌더(컴포넌트 상태 유지, props만 갱신), `HTMLElement`는 기존 인스턴스를
+     *   그대로 둡니다(조정할 수단이 없습니다). 새 `ctx`는 따로 전달되지 않고 `render(ctx)`를
+     *   통해 도달합니다.
+     *
+     * 기본값: 자식 라우트가 없으면 `ctx => ctx.href`(URL이 조금이라도 바뀌면 새로), 자식 라우트가
+     * 있으면 상수(레이아웃은 유지하고 자식만 바뀝니다).
+     *
+     * @example
+     * ```typescript
+     * // 쿼리스트링만 바뀌면 페이지를 유지하고 prop만 갱신 — 목록 상태·스크롤이 살아남습니다
+     * { path: '/orders', key: ctx => ctx.pathname,
+     *   render: ctx => html`<orders-page .selectedId=${ctx.query.get('id')}></orders-page>` }
+     * // params가 바뀌어도 유지
+     * { path: '/orders/:id', key: () => 'orders', render: ctx => html`...` }
+     * ```
+     */
+    key?: (ctx: RouteContext) => string;
+    /**
+     * 경로 매칭시 대소문자 구분 여부
+     * @default false
+     */
+    ignoreCase?: boolean;
+    /**
+     * 라우트에 연결할 메타데이터
+     * - 인증, SEO, 분석 등의 용도로 사용할 수 있습니다.
+     * @example
+     * ```typescript
+     * { path: '/admin', metadata: { requiresAuth: true, role: 'admin' } }
+     * ```
+     */
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * 컨텐츠 로드시 나타나는 에러
+ */
+export declare class ContentLoadError extends RouteError {
+    constructor(original?: Error | any);
+}
+
+/**
+ * 컨텐츠 렌더링시 발생하는 에러
+ */
+export declare class ContentRenderError extends RouteError {
+    constructor(original?: Error | any);
+}
+
+export declare 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 declare interface FallbackRouteContext extends RouteContext {
+    /**
+     * 라우팅 에러 정보
+     * - 라우팅 중 발생한 에러 정보를 포함합니다.
+     */
+    error: RouteError;
+}
+
+declare interface IndexRouteConfig extends BaseRouteConfig {
+    /**
+     * 현재 경로의 인덱스 라우트임을 나타냅니다.
+     * - 인덱스 라우트는 부모 경로와 동일한 경로를 가지며, path는 자동으로 설정됩니다.
+     */
+    index: true;
+}
+
+/**
+ * go() 메서드에 전달할 네비게이션 옵션
+ */
+export declare 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>;
+}
+
+declare interface NonIndexRouteConfig extends BaseRouteConfig {
+    /**
+     * 인덱스 라우트가 아님을 나타냅니다.
+     */
+    index?: false;
+    /**
+     * 하위 라우트 설정, 재귀적으로 RouteConfig 배열을 가질 수 있습니다.
+     * - 하위 라우트가 있는 경우, 부모 라우트의 경로를 기준으로 매칭됩니다.
+     */
+    children?: RouteConfig[];
+}
+
+/**
+ * 페이지를 찾을 수 없을 때 발생하는 에러
+ */
+export declare class NotFoundError extends RouteError {
+    constructor(path: string, original?: Error | any);
+}
+
+/**
+ * u-outlet 요소를 찾을 수 없을 때 발생하는 에러
+ */
+export declare class OutletMissingError extends RouteError {
+    constructor();
+}
+
+/** 렌더링 옵션 */
+declare interface RenderOption {
+    /** 교차 렌더링 방지 ID — 어느 라우트의 콘텐츠인가 */
+    id?: string;
+    /**
+     * 라우트의 식별 키(`RouteConfig.key` 의 결과). 같은 라우트 + 같은 키면 기존 콘텐츠를
+     * 유지한 채 제자리 갱신하고, 바뀌면 내리고 새로 마운트한다.
+     */
+    key?: string;
+}
+
+/**
+ * 라우트 시작 이벤트
+ */
+export declare class RouteBeginEvent extends RouteEvent {
+    constructor(context: RouteContext);
+}
+
+export declare type RouteConfig = IndexRouteConfig | NonIndexRouteConfig;
+
+/**
+ * 라우터 정보
+ */
+export declare 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 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);
+}
+
+/**
+ * `lit-element`, `react`를 지원하는 SPA 클라이언트 라우터 객체입니다.
+ */
+export declare class Router {
+    private readonly _rootElement;
+    private readonly _basepath;
+    private readonly _routes;
+    private readonly _fallback?;
+    private readonly _enter?;
+    private readonly _tracker;
+    /** 현재 라우팅 요청 ID */
+    private _requestID?;
+    /** 현재 라우팅 정보 */
+    private _context?;
+    constructor(config: RouterConfig);
+    /** 객체를 정리하고 이벤트 리스너를 제거합니다. */
+    destroy(): void;
+    /** 라우터의 기본 경로 반환 */
+    get basepath(): string;
+    /** 등록된 라우트 정보 반환 */
+    get routes(): RouteConfig[];
+    /** 현재 라우팅 정보 반환 */
+    get context(): RouteContext | undefined;
+    /**
+     * 지정한 경로의 클라이언트 라우팅을 수행합니다. 상대경로일 경우 basepath와 조합되어 이동합니다.
+     * @param href 이동할 경로
+     * @param options 네비게이션 옵션
+     * @param routes (internal) 호출자가 이미 계산한 라우트 매칭 결과가 있으면 재사용합니다.
+     *   `handleRootElementClick`이 가로채기 여부 판단을 위해 미리 계산한 결과를 전달해
+     *   동일 pathname에 대한 getRoutes 중복 호출을 피하는 용도입니다. 외부에서 사용하지 마세요.
+     */
+    go(href: string, options?: NavigateOptions, routes?: RouteConfig[]): Promise<undefined>;
+    /** 브라우저 히스토리 이벤트가 발생시 라우팅 처리 */
+    private handleWindowPopstate;
+    /** 클릭 이벤트에서 라우터로 처리할 앵커를 찾아 클라이언트 라우팅 수행 */
+    private handleRootElementClick;
+}
+
+/**
+ * 라우터 설정
+ */
+export declare interface RouterConfig {
+    /**
+     * 라우터가 연결될 최상위 엘리먼트
+     */
+    root: HTMLElement;
+    /**
+     * 라우터의 기본 경로
+     * - 라우터의 기본 경로는 URL의 시작점입니다.
+     * - URLPattern을 사용하여 경로를 탐색합니다.
+     * @default  '/'
+     */
+    basepath?: string;
+    /**
+     * 라우트 설정
+     * - 라우트는 URLPattern을 사용하여 경로를 탐색합니다.
+     * - 라우트는 렌더링할 엘리먼트 또는 컴포넌트를 지정합니다.
+     */
+    routes?: RouteConfig[];
+    /**
+     * 모든 라우트 전환 전에 호출되는 글로벌 enter 함수입니다.
+     * - `string` 반환: 해당 경로로 redirect
+     * - `false` 반환: 네비게이션 취소
+     * - `true` 반환: 통과
+     * @example
+     * ```typescript
+     * enter: async (ctx) => {
+     *   if (!isAuthenticated() && ctx.pathname !== '/login') return '/login';
+     * }
+     * ```
+     */
+    enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
+    /**
+     * 라우트 매칭 실패 또는 오류 발생 시 대체 라우트 설정
+     * - 지정된 설정이 없을 경우, 기본 오류 페이지가 렌더링됩니다.
+     */
+    fallback?: FallbackRouteConfig;
+    /**
+     * `a` 태그 클릭 시 클라이언트 라우팅을 수행할지 여부를 설정합니다.
+     * @default true
+     */
+    useIntercept?: boolean;
+    /**
+     * 초기 로드 시 현재 URL로 라우팅을 자동으로 수행할지 여부를 설정합니다.
+     * @default true
+     */
+    initialLoad?: boolean;
+}
+
+/**
+ * - 클라이언트 라우팅을 지원하는 링크 엘리먼트입니다.
+ * - 내부 링크는 클라이언트 라우팅을 수행하고, 외부 링크는 브라우저 기본 네비게이션을 사용합니다.
+ * - Ctrl/Meta/Shift/Alt, 중클릭/우클릭 등은 브라우저 기본 동작(새 탭, 컨텍스트 메뉴 등)을 그대로 유지합니다.
+ */
+export declare class ULink 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;
+    /**
+     * 이 링크를 라우터가 처리할지, 브라우저의 문서 이동에 맡길지.
+     *
+     * - `router`(기본): 종전 동작 그대로 — 같은 오리진이면 SPA 이동, 아니면 브라우저에 맡긴다.
+     * - `document`: 라우터가 **가로채지 않는다.** 같은 오리진이지만 SPA 라우트가 아닌 경로
+     *   (정적 문서 사이트, 서버 렌더 페이지, 파일 다운로드 엔드포인트, 인증 리다이렉트)를 가리킬 때 쓴다.
+     *
+     * ⚠**「외부 오리진」이 아니라 「다른 문서」다.** 종전에는 이 구분이 **오리진 비교 하나**로만
+     * 결정돼서, 같은 오리진의 비-SPA 경로를 가리킬 수단이 없었다 — 라우터가 클릭을 가로채고
+     * 등록되지 않은 라우트이므로 화면이 not-found 로 떨어졌다. 빠져나갈 길이 셋뿐이었고
+     * (다른 오리진 · `target="_blank"` · `#` 프래그먼트) 셋 다 요구와 다르다:
+     * 같은 오리진이어야 하고(쿠키·세션·역방향 프록시), **같은 탭**이어야 하며, 다른 문서다.
+     *
+     * ```html
+     * <u-link href="/help/" navigate="document">Help</u-link>
+     * ```
+     *
+     * ⚠**자동 판정을 넓히지 않는다.** 「등록된 라우트와 대조해 미등록이면 문서 이동」도 가능하지만
+     * 라우트가 늦게 등록되면 판정이 **시점에 의존**하게 된다. 명시 선언이 예측 가능하다.
+     */
+    navigate?: "router" | "document";
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * 호스트에 세팅된 `aria-current`/`aria-label`은 실제 접근 가능한(포커스 대상)
+     * 엘리먼트가 아니라 — 그 안쪽 shadow DOM 의 네이티브 `<a>`다. 섀도우 경계를
+     * 넘지 않으므로 접근성 트리에 자동 반영되지 않는다(실측 — 속성은
+     * 붙어 있는데 접근성 트리의 `aria-current`는 계속 비어 있음). `render()`가 이
+     * 값을 읽어 내부 `<a>`에 직접 옮긴다.
+     *
+     * 둘 다 Lit 리액티브 프로퍼티로 선언돼 있지 않아 `observedAttributes`에 없다 —
+     * 그 목록에 없는 속성은 `attributeChangedCallback` 자체가 호출되지 않는다
+     * (커스텀 엘리먼트 표준 동작). 초기 렌더는 되지만 연결 후 동적 변경은 반영되지
+     * 않았다 — 목록에 명시적으로 추가해야 한다.
+     */
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, old: string | null, value: string | null): 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;
+}
+
+/**
+ * LitElement 또는 React 컴포넌트를 렌더링해주는 웹컴포넌트 입니다.
+ */
+export declare class UOutlet extends HTMLElement {
+    /** 교차 렌더링 방지 id */
+    private routeId?;
+    /** 마지막으로 렌더한 라우트의 식별 키 */
+    private routeKey?;
+    /** 마운트된 콘텐츠의 종류 */
+    private kind?;
+    /** 실제 렌더링 컨텐츠 */
+    private root?;
+    /** 진행 중인 render — 다음 render 는 이것이 끝난 뒤 판정한다 */
+    private pending?;
+    connectedCallback(): void;
+    /**
+     * 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
+     *
+     * 같은 라우트(`id`)에 같은 키(`key`)로 다시 불리면 **제자리 갱신**한다 — Lit 템플릿은
+     * 같은 파트에 다시 렌더(요소·상태 유지, 바인딩만 갱신), React 엘리먼트는 같은 root 에 다시
+     * 렌더(컴포넌트 상태 유지), `HTMLElement` 는 기존 인스턴스를 그대로 둔다. 매번 `reset()`
+     * 을 먼저 부르던 종전 동작이 «쿼리스트링만 바뀌어도 페이지가 재마운트되는» 원인이었다
+     * (Lit 의 `render` 도 React 의 `root.render` 도 같은 컨테이너에 다시 부르면 조정한다).
+     */
+    render(value: unknown, options?: RenderOption): Promise<void>;
+    private mount;
+    /**
+     * 기존 DOM을 삭제하여, 초기 상태로 되돌립니다.
+     */
+    reset(): void;
+}
+
+export { }
+
+
+declare global {
+    interface HTMLElementTagNameMap {
+        'u-outlet': UOutlet;
+    }
+}
+
+
+/**
+ * 전역 WindowEventMap에 라우터 이벤트 타입
+ */
+declare global {
+    interface WindowEventMap {
+        'route-begin': RouteBeginEvent;
+        'route-progress': RouteProgressEvent;
+        'route-done': RouteDoneEvent;
+        'route-error': RouteErrorEvent;
+    }
+}

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-Cwn-vX3y.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-DxyaaBox.js";
 import { LitElement, css, html } from "lit";
 import { customElement, property } from "lit/decorators.js";
 //#region src/types/RouteError.ts