@iyulab/router 0.7.4 → 0.7.6

package/dist/react.d.ts

@@ -1,11 +1,92 @@
+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;
+    /** 렌더링할 값 */
+    value: unknown;
+}
+
 /**
  * `u-link` 웹 컴포넌트를 React에서 사용할 수 있도록 래핑한 컴포넌트입니다.
  */
-export declare const ULink: any;
+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;
+    /**
+     * 링크 대상 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: any;
+export declare const UOutlet: ReactWebComponent<UOutlet_2, {}>;
+
+/**
+ * LitElement 또는 React 컴포넌트를 렌더링해주는 웹컴포넌트 입니다.
+ */
+declare class UOutlet_2 extends HTMLElement {
+    /** 교차 렌더링 방지 id */
+    private routeId?;
+    /** 실제 렌더링 컨텐츠 */
+    private root?;
+    /**
+     * 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
+     */
+    render({ id, value, force }: RenderOption): Promise<void>;
+    /**
+     * 기존 DOM을 삭제하여, 초기 상태로 되돌립니다.
+     */
+    reset(): void;
+}
 
 export { }

package/dist/react.js

@@ -1,19 +1,24 @@
+import { s as UOutlet$1, t as ULink$1 } from "./share-sbAElOI7.js";
 import React from "react";
 import { createComponent } from "@lit/react";
-import { U as ULink$1, b as UOutlet$1 } from "./share-CG-3Tbuy.js";
-const ULink = createComponent({
-  react: React,
-  tagName: "u-link",
-  elementClass: ULink$1,
-  events: {}
+//#region src/react.ts
+/**
+* `u-link` 웹 컴포넌트를 React에서 사용할 수 있도록 래핑한 컴포넌트입니다.
+*/
+var ULink = createComponent({
+	react: React,
+	tagName: "u-link",
+	elementClass: ULink$1,
+	events: {}
 });
-const UOutlet = createComponent({
-  react: React,
-  tagName: "u-outlet",
-  elementClass: UOutlet$1,
-  events: {}
+/**
+* `u-outlet` 웹 컴포넌트를 React에서 사용할 수 있도록 래핑한 컴포넌트입니다.
+*/
+var UOutlet = createComponent({
+	react: React,
+	tagName: "u-outlet",
+	elementClass: UOutlet$1,
+	events: {}
 });
-export {
-  ULink,
-  UOutlet
-};
+//#endregion
+export { ULink, UOutlet };

package/dist/share-sbAElOI7.js

@@ -0,0 +1,237 @@
+import { LitElement, css, html, render } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+//#region src/components/UOutlet.ts
+/**
+* LitElement 또는 React 컴포넌트를 렌더링해주는 웹컴포넌트 입니다.
+*/
+var UOutlet = class extends HTMLElement {
+	/**
+	* 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
+	*/
+	async render({ id, value, force }) {
+		if (this.routeId === id && force === false) return;
+		this.routeId = id;
+		this.reset();
+		if (value === null) throw new Error("Content is null and cannot be rendered.");
+		if (typeof value !== "object") throw new Error("Content is not a valid renderable object.");
+		if (value instanceof HTMLElement) {
+			this.replaceChildren(value);
+			this.root = void 0;
+		} else if ("_$litType$" in value) this.root = render(value, this);
+		else if ("$$typeof" in value) {
+			const { createRoot } = await import("react-dom/client");
+			this.root = createRoot(this);
+			this.root.render(value);
+		} else throw new Error("not supported content type for Outlet rendering.");
+	}
+	/**
+	* 기존 DOM을 삭제하여, 초기 상태로 되돌립니다.
+	*/
+	reset() {
+		if (this.root && "_$litPart$" in this) delete this._$litPart$;
+		if (this.root && "unmount" in this.root) this.root.unmount();
+		this.root = void 0;
+		this.innerHTML = "";
+	}
+};
+customElements.define("u-outlet", UOutlet);
+//#endregion
+//#region src/internals/url-helpers.ts
+/**
+* 주어진 URL이 외부 링크인지 확인합니다.
+* 
+* @param url 확인할 URL 문자열
+* @return 외부 링크인 경우 true, 내부 링크인 경우 false
+*/
+function isExternalUrl(url) {
+	if (!url) return false;
+	url = url.trim();
+	if (/^(?:mailto:|tel:|javascript:)/i.test(url)) return true;
+	if (url.startsWith("//")) return true;
+	try {
+		const base = typeof window !== "undefined" ? window.location.origin : "http://localhost";
+		const parsed = new URL(url, base);
+		if (/^(?:ftp:|ftps:|ws:|wss:)/i.test(parsed.protocol)) return true;
+		return parsed.origin !== new URL(base).origin;
+	} catch {
+		return false;
+	}
+}
+/**
+* URL 문자열을 파싱하여 RouteContext 객체로 반환합니다.
+* - http(s)로 시작하는 절대 URL은 외부 링크로 간주됩니다.
+* - 절대경로(/...)는 그대로 사용됩니다.
+* - 상대경로는 basepath를 기준으로 절대경로로 변환됩니다. 
+* - 쿼리스트링(?)로 시작하는 쿼리는 현재 경로와 추가됩니다.
+* - 해시(#)로 시작하는 해시는 현재 경로와 추가됩니다.
+* 
+* @param url 파싱할 URL 문자열
+* @param basepath 기준이 되는 basepath 문자열
+* @returns 파싱된 RouteContext 객체
+*/
+function parseUrl(url, basepath) {
+	let urlObj;
+	basepath = catchBasepath(basepath);
+	if (url.startsWith("http")) urlObj = new URL(url);
+	else if (url.startsWith("/")) urlObj = new URL(url, window.location.origin);
+	else if (url.startsWith("?")) urlObj = new URL(window.location.pathname + url, window.location.origin);
+	else if (url.startsWith("#")) urlObj = new URL(window.location.pathname + window.location.search + url, window.location.origin);
+	else urlObj = new URL(absolutePath(basepath, url), window.location.origin);
+	return {
+		href: urlObj.href,
+		origin: urlObj.origin,
+		basepath,
+		path: urlObj.href.replace(urlObj.origin, ""),
+		pathname: urlObj.pathname,
+		query: new URLSearchParams(urlObj.search),
+		hash: urlObj.hash,
+		params: {},
+		progress: () => {},
+		meta: {}
+	};
+}
+/**
+* pathname 경로를 조합하여 절대경로를 반환합니다.
+* 
+* @param paths 조합할 경로 문자열들
+* @returns 조합된 절대경로 문자열
+*/
+function absolutePath(...paths) {
+	paths = paths.map((p) => p.replace(/^\/|\/$/g, "")).filter((p) => p.length > 0);
+	if (paths.length === 0) return "/";
+	return "/" + paths.join("/");
+}
+/**
+* basepath가 동적 패턴일 경우(RouteConfig에서 basepath가 :id 등으로 정의된 경우),
+* 현재 경로에서 해당되는 패턴의 basepath를 추출하여 반환합니다.
+* 
+* @param basepath 동적 패턴이 포함된 basepath 문자열
+* @return 현재 경로에 매칭되는 basepath 문자열
+* @example
+* catchBasePath('/app/:id') => '/app/123'
+*/
+function catchBasepath(basepath) {
+	if (basepath === "/") return basepath;
+	let pattern = new URLPattern({ pathname: basepath + "/*" });
+	let match = pattern.exec({ pathname: window.location.pathname });
+	if (match) {
+		const rawPath = match.pathname.input;
+		const restPath = match.pathname.groups?.["0"];
+		return restPath !== void 0 && restPath !== "" ? rawPath.replace("/" + restPath, "") : rawPath.replace(/\/$/, "");
+	}
+	pattern = new URLPattern({ pathname: `${basepath}{/}?` });
+	match = pattern.exec({ pathname: window.location.pathname });
+	if (match) return match.pathname.input;
+	return basepath;
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.122.0/helpers/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.122.0/helpers/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);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/components/ULink.ts
+var ULink = class ULink extends LitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.isExternal = false;
+		this.handleClick = (event) => {
+			if (event.defaultPrevented) return;
+			if (event.button !== 0) return;
+			if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+			if (this.target && this.target.toLowerCase() !== "_self") return;
+			const basepath = this.getBasepath();
+			if (!this.href) {
+				event.preventDefault();
+				this.dispatchPopstate(basepath, basepath);
+				return;
+			}
+			if (this.isExternal) return;
+			if (this.href.startsWith("#")) return;
+			event.preventDefault();
+			if (this.href.startsWith("?")) {
+				const url = window.location.pathname + this.href;
+				this.dispatchPopstate(basepath, url);
+				return;
+			}
+			if (this.href.startsWith("/")) {
+				if (!this.href.startsWith(basepath)) {
+					window.location.assign(this.href);
+					return;
+				}
+				this.dispatchPopstate(basepath, this.href);
+				return;
+			}
+			const url = absolutePath(basepath, this.href);
+			this.dispatchPopstate(basepath, url);
+		};
+	}
+	connectedCallback() {
+		super.connectedCallback();
+		this.addEventListener("click", this.handleClick);
+	}
+	disconnectedCallback() {
+		this.removeEventListener("click", this.handleClick);
+		super.disconnectedCallback();
+	}
+	willUpdate(changedProperties) {
+		super.willUpdate(changedProperties);
+		if (changedProperties.has("href")) this.isExternal = isExternalUrl(this.href || "");
+	}
+	render() {
+		return html`
+      <a target=${ifDefined(this.target)} href=${this.compute(this.href)}>
+        <slot></slot>
+      </a>
+    `;
+	}
+	/** a 태그에 주입할 href 값을 계산합니다. */
+	compute(href) {
+		const basepath = this.getBasepath();
+		if (!href) return window.location.origin + basepath;
+		if (this.isExternal) return href;
+		if (href.startsWith("/")) return href;
+		if (href.startsWith("#") || href.startsWith("?")) return href;
+		return absolutePath(basepath, href);
+	}
+	/** 클라이언트 라우팅을 위해 popstate 이벤트를 발생시킵니다. */
+	dispatchPopstate(basepath, url) {
+		window.history.pushState({ basepath }, "", url);
+		window.dispatchEvent(new PopStateEvent("popstate"));
+	}
+	/** basepath를 state에서 꺼내는 헬퍼 */
+	getBasepath() {
+		return window.history.state?.basepath || "/";
+	}
+	static {
+		this.styles = css`
+    :host {
+      cursor: pointer;
+    }
+
+    a {
+      text-decoration: none;
+
+      font-size: inherit;
+      font-weight: inherit;
+      font-family: inherit;
+      color: inherit;
+      cursor: inherit;
+    }
+  `;
+	}
+};
+__decorate([property({ type: String }), __decorateMetadata("design:type", String)], ULink.prototype, "target", void 0);
+__decorate([property({ type: String }), __decorateMetadata("design:type", String)], ULink.prototype, "href", void 0);
+ULink = __decorate([customElement("u-link")], ULink);
+//#endregion
+export { isExternalUrl as a, absolutePath as i, __decorate as n, parseUrl as o, __decorateMetadata as r, UOutlet as s, ULink as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/router",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "A modern client-side router for web applications with support for Lit and React components",
   "keywords": [
     "lit",
@@ -19,8 +19,10 @@
   },
   "files": [
     "dist",
+    "skills",
     "package.json",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "type": "module",
@@ -40,10 +42,10 @@
     "build": "vite build"
   },
   "dependencies": {
-    "lit": "^3.3.2"
+    "lit": "^3.3.2",
+    "@lit/react": "^1.0.8"
   },
   "peerDependencies": {
-    "@lit/react": ">=1.0.0",
     "react": ">=18.0.0",
     "react-dom": ">=18.0.0"
   },
@@ -53,17 +55,14 @@
     },
     "react-dom": {
       "optional": true
-    },
-    "@lit/react": {
-      "optional": true
     }
   },
   "devDependencies": {
-    "@types/node": "^25.3.2",
+    "@types/node": "^25.5.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "typescript": "^5.9.3",
-    "vite": "^7.3.1",
+    "vite": "^8.0.3",
     "vite-plugin-dts": "^4.5.4"
   }
 }

package/skills/iyulab-router/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: iyulab-router
+description: Client-side SPA router for Lit and React with URLPattern-based matching, nested routes, fallback handling, and route events. Use when working with @iyulab/router — setting up routing, defining routes, handling navigation, nested layouts with <u-outlet>, or listening to route lifecycle events.
+license: MIT
+compatibility: Browser environments only (requires URLPattern and History API)
+metadata:
+  author: iyulab
+  version: "0.7.4"
+---
+
+# @iyulab/router
+
+Client-side router supporting Lit and React renders, nested routes, and URLPattern-based matching.
+
+## Install
+
+```bash
+npm install @iyulab/router
+```
+
+## Core API
+
+| Export | Purpose |
+|---|---|
+| `Router` | Main router class |
+| `RouteConfig` | Route definition type |
+| `RouterConfig` | Constructor config type |
+| `RouteContext` | Passed to every `render()` call |
+| `FallbackRouteConfig` | Error/404 fallback definition |
+| `<u-outlet>` | Renders the matched route output |
+| `<u-link>` | Client-side navigation anchor |
+| `UOutlet`, `ULink` | React wrappers (from `@iyulab/router/react`) |
+
+## Router Setup
+
+```ts
+import { Router } from '@iyulab/router';
+import { html } from 'lit';
+
+const router = new Router({
+  root: document.body,       // required — mount element containing <u-outlet>
+  basepath: '/',             // optional
+  routes: [
+    { index: true, render: () => html`<home-page></home-page>` },
+    { path: '/user/:id', render: (ctx) => html`<user-page .id=${ctx.params.id}></user-page>` },
+  ],
+  fallback: {
+    render: (ctx) => html`<error-page .error=${ctx.error}></error-page>`
+  }
+});
+```
+
+## RouteConfig Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `path` | `string \| URLPattern` | URLPattern path; omit when `index: true` |
+| `index` | `true` | Marks route as index of its parent path |
+| `render` | `(ctx) => unknown` | Returns Lit `TemplateResult`, React element, or `HTMLElement` |
+| `children` | `RouteConfig[]` | Nested routes; parent must render `<u-outlet>` |
+| `title` | `string` | Sets `document.title` on match |
+| `meta` | `Record<string, unknown>` | Arbitrary metadata (auth, layout, analytics) |
+| `force` | `boolean` | Force re-render on URL change (default `true` for leaf routes) |
+
+## RouteContext Fields
+
+```ts
+ctx.params     // URLPattern captured params
+ctx.pathname   // path without query/hash
+ctx.path       // full path including query + hash
+ctx.query      // URLSearchParams
+ctx.meta       // merged meta from matched route chain
+ctx.progress   // (value: number) => void — report 0–100 loading progress
+```
+
+## Nested Routes
+
+Parent must include `<u-outlet>` in its render output:
+
+```ts
+{
+  path: '/dashboard',
+  render: () => html`<dashboard-layout><u-outlet></u-outlet></dashboard-layout>`,
+  children: [
+    { index: true, render: () => html`<dashboard-home></dashboard-home>` },
+    { path: 'settings', render: () => html`<dashboard-settings></dashboard-settings>` }
+  ]
+}
+```
+
+## Navigation
+
+```ts
+router.go('/path');                  // programmatic navigation
+router.go('relative-path');         // relative to basepath
+router.destroy();                   // remove event listeners
+
+// From Lit template
+html`<u-link href="/about">About</u-link>`
+
+// From React
+import { ULink } from '@iyulab/router/react';
+<ULink href="/about">About</ULink>
+```
+
+## Route Events (window)
+
+| Event | Fired when |
+|---|---|
+| `route-begin` | Navigation starts |
+| `route-progress` | Async progress update (0–100) |
+| `route-done` | Navigation completes |
+| `route-error` | Routing error occurs |
+
+## Error Types (fallback ctx.error)
+
+| Code | Class |
+|---|---|
+| `NOT_FOUND` | `NotFoundError` |
+| `CONTENT_LOAD_ERROR` | `ContentLoadError` |
+| `CONTENT_RENDER_ERROR` | `ContentRenderError` |
+
+See [references/REFERENCE.md](references/REFERENCE.md) for URL parameter patterns, React usage, and advanced examples.