@iyulab/router 0.1.0

package/dist/main.d.ts

@@ -0,0 +1,382 @@
+import { ComponentType } from 'react';
+import { CSSResult } from 'lit';
+import { LitElement } from 'lit';
+import { ReactWebComponent } from '@lit/react';
+import { TemplateResult } from 'lit-html';
+
+/**
+ * 현재 경로상의 basepath를 반환합니다.
+ * @example
+ * catchBasePath('/app/:id') => '/app/123'
+ */
+export declare function catchBasepath(basepath: string): string;
+
+/**
+ * pathname 경로를 조합하여 반환합니다.
+ * - 절대 경로로 반환됩니다.
+ */
+export declare function combinePath(...paths: string[]): string;
+
+/**
+ * 랜덤한 ID를 생성합니다.
+ * - https일 경우 crypto.randomUUID()를 사용합니다.
+ * - 그 외의 경우 crypto.getRandomValues()를 사용합니다.
+ */
+export declare function getRandomID(): string;
+
+/**
+ * /foo/* -> /foo/bar/baz 와 같은 와일드카드 패턴을 처리하기 위한 함수
+ */
+export declare function getTailGroup(groups: {
+    [key: string]: string | undefined;
+}): string | undefined;
+
+/**
+ * 인덱스 라우트는 path가 없는 라우트입니다.
+ */
+export declare type IndexRoute = {
+    /**
+     * 라우터의 basepath를 따르는 라우트입니다.
+     */
+    index: true;
+    path?: undefined;
+};
+
+export declare const Link: ReactWebComponent<ULink, {}>;
+
+/**
+ * 인덱스 라우트가 아닌 라우트는 path가 필수입니다.
+ */
+export declare type NonIndexRoute = {
+    index?: undefined;
+    /**
+     * 라우터 경로는 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;
+};
+
+export declare const Outlet: ReactWebComponent<UOutlet, {}>;
+
+/**
+ * URL 문자열을 파싱하여 새로운 URL 정보를 반환합니다.
+ * - ?로 시작하는 쿼리스트링, #으로 시작하는 해시값은 현재 경로에서 추가됩니다.
+ * - 상대경로는 basepath를 기준으로 절대경로로 변환됩니다.
+ */
+export declare function parseURL(url: string, basepath: string): RouteInfo;
+
+declare interface RenderComponentOption extends RenderOption {
+    component: ComponentType;
+}
+
+declare interface RenderElementOption extends RenderOption {
+    element: typeof LitElement | string;
+}
+
+declare interface RenderOption {
+    id?: string;
+    force?: boolean;
+}
+
+/**
+ * 라우트 타입
+ */
+export declare type Route = (NonIndexRoute | IndexRoute) & {
+    /**
+     * 라우터에서 사용하는 식별자
+     */
+    id?: string;
+    /**
+     * 라우터 URL 변경시 렌더링을 강제할지 여부
+     * - 기본값으로 children을 가질때 false로 설정되며, children이 없을 경우 true로 설정됩니다.
+     * - true로 설정하면 기존 렌더링을 무시하고 새로 렌더링합니다.
+     */
+    force?: boolean;
+    /**
+     * 라우터에서 사용하는 URLPattern
+     */
+    pattern?: URLPattern;
+    /**
+     * 엘리먼트 또는 컴포넌트를 렌더링하기 전에 호출되는 함수
+     * @param 라우터 URL 정보
+     */
+    loader?: (url: RouteURL) => Promise<any>;
+    /**
+     * 브라우저의 타이틀이 설정에 따라 변경됩니다.
+     */
+    title?: string;
+    /**
+     * 중첩 라우트
+     */
+    children?: Route[];
+    /**
+     * 렌더링할 LitElement
+     * - LitElement 클래스 또는 태그 이름을 사용합니다.
+     * @example
+     * ```typescript
+     * import { UserPage } from './pages';
+     * const route = {
+     *    path: '/user',
+     *    element: 'user-page' | UserPage,
+     * }
+     * ```
+     */
+    element?: typeof LitElement | string;
+    /**
+     * 렌더링할 ReactComponent
+     * - ReactComponent의 모듈을 사용합니다.
+     * @example
+     * ```typescript
+     * import { UserPage } from './pages';
+     * const route = {
+     *    path: '/user',
+     *    component: UserPage,
+     * }
+     * ```
+     */
+    component?: ComponentType;
+};
+
+/**
+ * 라우터 정보
+ */
+export declare interface RouteInfo extends RouteURL {
+    /**
+     * 엘리먼트 또는 컴포넌트 렌더링 전에 호출되는 함수에서 반환된 데이터
+     */
+    data?: any;
+}
+
+export declare class Router {
+    private readonly _rootElement;
+    private readonly _notfound;
+    private readonly _basepath;
+    private readonly _routes;
+    private _routeInfo?;
+    private requestID?;
+    get basepath(): string;
+    get routeInfo(): RouteInfo | undefined;
+    constructor(config: RouterConfig);
+    /**
+     * 라우터 연결
+     */
+    connect(): void;
+    /**
+     * 라우터 연결 해제
+     */
+    disconnect(): void;
+    /**
+     * 지정한 경로로 이동
+     * - 클라이언트 사이드 라우팅을 수행합니다.
+     * - 상대경로일 경우 basepath와 조합되어 이동합니다.
+     * - 라우터에 포함되지 않은 경로로 이동할 경우 다른 방법으로 처리하세요.
+     * @param href 이동할 경로
+     */
+    go(href: string): Promise<void>;
+    /**
+     * 라우터 기본 경로로 이동
+     */
+    goBase(): Promise<void>;
+    /**
+     * 라우트 URLPattern 생성
+     */
+    private setRoutes;
+    /**
+     * URLPattern을 필요할 때 동적으로 생성
+     */
+    private ensurePattern;
+    /**
+     * 경로와 일치하는 라우트를 찾습니다.
+     * URLPattern을 사용하여 경로를 비교하고 재귀적으로 자식 라우트도 검색합니다.
+     */
+    private getRoutes;
+    /**
+     * 라우팅 진행률 Dispatch
+     */
+    private dispatchProgress;
+    /**
+     * 브라우저 히스토리 이벤트가 발생했을 때 라우팅 처리
+     */
+    private onPopstate;
+    /**
+     * Outlet 엘리먼트를 찾습니다.
+     */
+    private getOutlet;
+}
+
+/**
+ * 라우터 설정
+ */
+export declare interface RouterConfig {
+    /**
+     * 라우터가 연결될 최상위 엘리먼트
+     */
+    root: HTMLElement;
+    /**
+     * 라우터의 기본 경로
+     * - 라우터의 기본 경로는 URL의 시작점입니다.
+     * - URLPattern을 사용하여 경로를 탐색합니다.
+     */
+    basepath?: string;
+    /**
+     * 라우트 설정
+     * - 라우트는 URLPattern을 사용하여 경로를 탐색합니다.
+     * - 라우트는 렌더링할 엘리먼트 또는 컴포넌트를 지정합니다.
+     */
+    routes: Route[];
+    /**
+     * 라우터가 URL을 찾지 못했을 때 렌더링할 엘리먼트
+     */
+    notfound: typeof LitElement | string;
+}
+
+/**
+ * 라우터 URL 정보
+ */
+export declare interface RouteURL {
+    /**
+     * 전체 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;
+}
+
+export declare class ULink extends LitElement {
+    private static externalLinks;
+    private isExternalLink;
+    /**
+     * a 태그의 href 속성 및 새로운 페이지로 이동할 때 사용될 링크입니다.
+     */
+    link: string;
+    /**
+     * - 속성을 정의하지 않으면 basepath로 이동합니다.
+     * - http 로 시작하면 새로운 페이지를 로드합니다.
+     * - 절대경로일 경우 basepath로 시작하면 클라이언트 라우팅을 합니다. 그렇지 않으면 새로운 페이지를 로드합니다.
+     * - 상대경로로 시작하면 (현재의 basepath + 상대경로)로 클라이언트 라우팅을 합니다.
+     * - ?로 시작하면 현재 경로에 쿼리스트링을 추가하고, 클라이언트 라우팅을 합니다.
+     * - #으로 시작하면 현재 경로에 해시를 추가하고, hashchange 이벤트를 발생시킵니다.
+     */
+    href?: string;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changedProperties: any): Promise<void>;
+    render(): TemplateResult<1>;
+    /**
+     * 링크 엘리먼트의 마우스 이벤트 핸들러
+     * - 새로운 탭에서 열기: 마우스 중간 버튼 또는 Ctrl 키를 누릅니다.
+     * - 새로운 페이지로 이동: http로 시작하거나 절대경로일 경우 새로운 페이지로 이동합니다.
+     * - 클라이언트 라우팅: 상대경로로 시작하면 클라이언트 라우팅을 합니다.
+     */
+    private handleMouseEvent;
+    /**
+     * 클라이언트 라우팅을 위해 popstate 이벤트를 발생시킵니다.
+     */
+    private dispatchPopstate;
+    /**
+     * 클라이언트 라우팅을 위해 hashchange 이벤트를 발생시킵니다.
+     * - 해시이벤트를 받으면 현재 페이지에서 해당 태그위치로 스크롤합니다.
+     * - 스크롤 조절은 따로 구현해야 합니다.
+     */
+    private dispatchHashchange;
+    /**
+     * link로 사용할 URL을 반환합니다.
+     */
+    private getLink;
+    /**
+     * 기본 a 태그의 클릭 이벤트를 막습니다.
+     */
+    private preventClickEvent;
+    /**
+     * 외부 링크인지 확인합니다.
+     */
+    private checkExternalLink;
+    static styles: CSSResult;
+}
+
+export declare class UOutlet extends LitElement {
+    private routeId?;
+    private root?;
+    private reactRoot?;
+    private litRoot?;
+    protected createRenderRoot(): this;
+    render(): TemplateResult<1>;
+    /**
+     * 기존 렌더링된 DOM을 제거하고, LitElement를 삽입합니다.
+     * - 이전 ID와 동일하고, 강제 렌더링이 아닌 경우, 이전 DOM을 반환합니다.
+     */
+    renderElement({ id, element, force }: RenderElementOption): Promise<Element | null | undefined>;
+    /**
+     * 기존 렌더링된 DOM을 제거하고, React 컴포넌트를 삽입합니다.
+     * - 이전 ID와 동일하고, 강제 렌더링이 아닌 경우, 이전 DOM을 반환합니다.
+     */
+    renderComponent({ id, component, force }: RenderComponentOption): Promise<HTMLDivElement | undefined>;
+    /**
+     * 기존 DOM을 라이프 사이클에 맞게 제거합니다.
+     */
+    clearRoot(): void;
+}
+
+export { }