@iyulab/router 0.11.4 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## [0.12.0] - 2026-09-13
+
+### Added
+
+- **`RouteConfig.key` — the route decides when its content is remounted.** Each navigation
+  computes `key(ctx)`; while it is unchanged the outlet keeps the mounted content and re-renders
+  it in place with the new `ctx` — a Lit template is rendered into the same part (elements and
+  their state survive, only bindings change), a React element into the same root (component
+  state survives, props change), and an `HTMLElement` is left as it is. A changed key unmounts
+  and mounts fresh, as every navigation did before. Click interception, `go()` and `popstate`
+  all follow the one rule because it lives on the route, not on the call. The default is
+  `ctx => ctx.href` for leaf routes, so nothing changes until a route opts in:
+  `{ path: '/orders', key: ctx => ctx.pathname, render: ctx => html`<orders-page .selectedId=${ctx.query.get('id')}></orders-page>` }`
+  keeps the list — its scroll, selection and loaded rows — while `?id=` opens and closes a
+  detail overlay.
+
+### Changed
+
+- **A layout route (one with `children`) is now re-rendered in place when a child changes.** It
+  was already kept across child navigations, but its `render(ctx)` result was thrown away, so a
+  layout could never react to the current `ctx` (an active-menu highlight, a breadcrumb). It now
+  receives the new `ctx` through the same in-place path; its inner `<u-outlet>` and the child
+  content are untouched.
+- **Outlet renders are serialised.** A render that arrives while a React mount is still awaiting
+  its dynamic import now waits for that mount instead of racing it.
+
+### Fixed
+
+- **`force: false` on a leaf route was silently ignored.** Defaults were applied with
+  `route.force ||= true`, which turns an explicit `false` into `true` — the documented option
+  could not be set on the routes it was documented for. `force` is now deprecated in favour of
+  `key` (`false` ≡ a constant key, `true` ≡ the default) and, for this release, honoured as
+  written on every route.
+
+### Deprecated
+
+- `RouteConfig.force` — use `key`. Still honoured in this release; removed in the next minor.
+
+## [0.11.5] - 2026-09-10
+
+### Fixed
+
+- **`u-error-page`'s three colour hooks were documented as having no default.** They were
+  described as falling back to the inherited colour, when the host block in fact declares a
+  concrete colour for each — `--error-icon-color` `#4a5568` (dark `#a0aec0`),
+  `--error-code-color` `#1a202c` (dark `#f7fafc`), `--error-message-color` `#718096`
+  (dark `#cbd5e0`). A consumer reading the old text would expect the page to pick up the
+  surrounding colour and find that it does not. The documentation now also states the
+  consequence those literals carry: this page does not follow the host application's design
+  tokens, and replacing it wholesale is what `fallback.render` is for. No behaviour changed.
+
 ## [0.11.4] - 2026-09-01
 
 ### Fixed

package/dist/components/UErrorPage.d.ts

@@ -9,9 +9,13 @@ import { TemplateResult } from 'lit-html';
  * 아니다. 다만 라우팅 실패 시 실제 DOM에 렌더되므로, 기본 화면의 색만 가볍게
  * 맞추고 싶은 소비자를 위해 세 색상 훅을 남겨 둔다(전체 교체는 `fallback.render`).
  *
- * @cssprop --error-icon-color - 아이콘 색. 기본값 없음(미지정 시 상속된 색 사용)
- * @cssprop --error-code-color - 에러 코드 텍스트 색. 기본값 없음(미지정 시 상속된 색 사용)
- * @cssprop --error-message-color - 에러 메시지 텍스트 색. 기본값 없음(미지정 시 상속된 색 사용)
+ * @cssprop --error-icon-color - 아이콘 색. 기본값 `#4a5568`(다크 `#a0aec0`)
+ * @cssprop --error-code-color - 에러 코드 텍스트 색. 기본값 `#1a202c`(다크 `#f7fafc`)
+ * @cssprop --error-message-color - 에러 메시지 텍스트 색. 기본값 `#718096`(다크 `#cbd5e0`)
+ *
+ * ⚠세 값은 아래 `static styles` 의 `:host` 에서 **구체적인 색으로 선언된다** — 지정하지
+ * 않으면 주변 색을 상속하는 것이 아니라 위 기본값이 적용된다. 리터럴이므로 이 페이지는
+ * 호스트 앱의 디자인 토큰을 따르지 않는다.
  */
 export declare class UErrorPage extends LitElement {
     constructor(error?: RouteError);

package/dist/components/UOutlet.d.ts

@@ -1,9 +1,12 @@
 /** 렌더링 옵션 */
 interface RenderOption {
-    /** 교차 렌더링 방지 ID */
+    /** 교차 렌더링 방지 ID — 어느 라우트의 콘텐츠인가 */
     id?: string;
-    /** 강제 렌더링 여부 */
-    force?: boolean;
+    /**
+     * 라우트의 식별 키(`RouteConfig.key` 의 결과). 같은 라우트 + 같은 키면 기존 콘텐츠를
+     * 유지한 채 제자리 갱신하고, 바뀌면 내리고 새로 마운트한다.
+     */
+    key?: string;
 }
 /**
  * LitElement 또는 React 컴포넌트를 렌더링해주는 웹컴포넌트 입니다.
@@ -11,12 +14,25 @@ interface RenderOption {
 declare class UOutlet extends HTMLElement {
     /** 교차 렌더링 방지 id */
     private routeId?;
+    /** 마지막으로 렌더한 라우트의 식별 키 */
+    private routeKey?;
+    /** 마운트된 콘텐츠의 종류 */
+    private kind?;
     /** 실제 렌더링 컨텐츠 */
     private root?;
+    /** 진행 중인 render — 다음 render 는 이것이 끝난 뒤 판정한다 */
+    private pending?;
     /**
      * 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
+     *
+     * 같은 라우트(`id`)에 같은 키(`key`)로 다시 불리면 **제자리 갱신**한다 — Lit 템플릿은
+     * 같은 파트에 다시 렌더(요소·상태 유지, 바인딩만 갱신), React 엘리먼트는 같은 root 에 다시
+     * 렌더(컴포넌트 상태 유지), `HTMLElement` 는 기존 인스턴스를 그대로 둔다. 매번 `reset()`
+     * 을 먼저 부르던 종전 동작이 «쿼리스트링만 바뀌어도 페이지가 재마운트되는» 원인이었다
+     * (Lit 의 `render` 도 React 의 `root.render` 도 같은 컨테이너에 다시 부르면 조정한다).
      */
     render(value: unknown, options?: RenderOption): Promise<void>;
+    private mount;
     /**
      * 기존 DOM을 삭제하여, 초기 상태로 되돌립니다.
      */

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-BOhUKwJL.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-ByPkeTq1.js";
 import { LitElement, css, html } from "lit";
 import { customElement, property } from "lit/decorators.js";
 //#region src/types/RouteError.ts
@@ -299,6 +299,18 @@ function findAnchorFrom(event) {
 */
 var createURLPattern = URLPattern;
 /**
+* `key` 가 없을 때의 기본 식별 키 — «언제 새로 만드는가» 의 기본 규칙.
+*
+* 자식이 없는 라우트는 URL(`href`) 이 조금이라도 바뀌면 새로 마운트하고, 자식을 가진 라우트
+* (레이아웃)는 상수 키로 유지된다 — 종전의 `force` 기본값(leaf true · parent false)과 같은
+* 결과다. 다만 종전 코드는 `route.force ||= true` 라서 소비자가 leaf 에 `force: false` 를
+* 명시해도 `true` 로 덮였다(`false || true`). `force` 는 deprecate 됐지만 이 판에서는
+* 존중한다: `false` 는 «유지», `true` 는 «새로».
+*/
+function defaultKey(route, hasChildren) {
+	return route.force === false || hasChildren && route.force !== true ? () => "" : (ctx) => ctx.href;
+}
+/**
 * 라우트들을 다음 사항에 따라 재귀적으로 재설정합니다.
 * - 각 라우트에 고유 `id`를 랜덤하게 부여합니다.
 * - `path`를 URLPattern 객체로 변환합니다.
@@ -314,15 +326,15 @@ function setRoutes(routes, basepath) {
 		route.ignoreCase ||= false;
 		if (route.index === true) {
 			route.path = new createURLPattern({ pathname: `${basepath}{/}?` }, { ignoreCase: route.ignoreCase });
-			route.force ||= true;
+			route.key ??= defaultKey(route, false);
 		} else {
 			if (typeof route.path === "string") route.path = new createURLPattern({ pathname: `${absolutePath(basepath, route.path)}{/}?` }, { ignoreCase: route.ignoreCase });
 			else if (route.path instanceof URLPattern) {} else route.path = new createURLPattern({ pathname: `${basepath}{/}?` }, { ignoreCase: route.ignoreCase });
 			if (route.children && route.children.length > 0) {
 				const childBasepath = route.path.pathname.replace("{/}?", "");
 				route.children = setRoutes(route.children, childBasepath);
-				route.force ||= false;
-			} else route.force ||= true;
+				route.key ??= defaultKey(route, true);
+			} else route.key ??= defaultKey(route, false);
 		}
 	}
 	return routes;
@@ -517,7 +529,7 @@ var Router = class {
 				try {
 					await outlet.render(content, {
 						id: route.id,
-						force: route.force
+						key: route.key?.(context)
 					});
 				} catch (e) {
 					throw new ContentRenderError(e);
@@ -536,10 +548,7 @@ var Router = class {
 					...context,
 					error: routeError
 				}) : new UErrorPage(routeError);
-				if (outlet) outlet.render(content, {
-					id: getRandomID(),
-					force: true
-				});
+				if (outlet) outlet.render(content, { id: getRandomID() });
 				else {
 					document.body.innerHTML = "";
 					document.body.appendChild(content instanceof Node ? content : new UErrorPage(routeError));

package/dist/react.js

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

package/dist/{share-BOhUKwJL.js → share-ByPkeTq1.js}

@@ -8,24 +8,48 @@ import { ifDefined } from "lit/directives/if-defined.js";
 var UOutlet = class extends HTMLElement {
 	/**
 	* 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
+	*
+	* 같은 라우트(`id`)에 같은 키(`key`)로 다시 불리면 **제자리 갱신**한다 — Lit 템플릿은
+	* 같은 파트에 다시 렌더(요소·상태 유지, 바인딩만 갱신), React 엘리먼트는 같은 root 에 다시
+	* 렌더(컴포넌트 상태 유지), `HTMLElement` 는 기존 인스턴스를 그대로 둔다. 매번 `reset()`
+	* 을 먼저 부르던 종전 동작이 «쿼리스트링만 바뀌어도 페이지가 재마운트되는» 원인이었다
+	* (Lit 의 `render` 도 React 의 `root.render` 도 같은 컨테이너에 다시 부르면 조정한다).
 	*/
 	async render(value, options) {
-		if (this.routeId === options?.id && options?.force === false) return;
-		this.routeId = options?.id;
-		this.reset();
+		const prev = this.pending;
+		const run = (async () => {
+			if (prev) await prev.catch(() => void 0);
+			await this.mount(value, options);
+		})();
+		this.pending = run;
+		try {
+			await run;
+		} finally {
+			if (this.pending === run) this.pending = void 0;
+		}
+	}
+	async mount(value, options) {
 		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) {
+		const kind = contentKind(value);
+		const inPlace = this.kind !== void 0 && this.kind === kind && this.routeId === options?.id && this.routeKey === options?.key;
+		this.routeId = options?.id;
+		this.routeKey = options?.key;
+		if (inPlace) {
+			if (kind === "lit") this.root = render(value, this);
+			else if (kind === "react") this.root.render(value);
+			return;
+		}
+		this.reset();
+		this.kind = kind;
+		if (kind === "element") {
 			this.replaceChildren(value);
 			this.root = void 0;
-		} else if ("_$litType$" in value) this.root = render(value, this);
-		else if ("$$typeof" in value) {
+		} else if (kind === "lit") this.root = render(value, this);
+		else {
 			const { createRoot } = await import("react-dom/client");
 			this.root = createRoot(this);
 			this.root.render(value);
-		} else {
-			const receivedType = value?.constructor?.name ?? typeof value;
-			throw new Error(`Unsupported content type for Outlet rendering: received ${receivedType}. Expected an HTMLElement, a Lit TemplateResult, or a React element.`);
 		}
 	}
 	/**
@@ -35,9 +59,18 @@ var UOutlet = class extends HTMLElement {
 		if (this.root && "_$litPart$" in this) delete this._$litPart$;
 		if (this.root && "unmount" in this.root) this.root.unmount();
 		this.root = void 0;
+		this.kind = void 0;
 		this.innerHTML = "";
 	}
 };
+/** 렌더 가능한 세 종류 중 무엇인가 — 아니면 서술적으로 던진다. */
+function contentKind(value) {
+	if (value instanceof HTMLElement) return "element";
+	if ("_$litType$" in value) return "lit";
+	if ("$$typeof" in value) return "react";
+	const receivedType = value?.constructor?.name ?? typeof value;
+	throw new Error(`Unsupported content type for Outlet rendering: received ${receivedType}. Expected an HTMLElement, a Lit TemplateResult, or a React element.`);
+}
 customElements.define("u-outlet", UOutlet);
 //#endregion
 //#region node_modules/urlpattern-polyfill/dist/urlpattern.js
@@ -1026,12 +1059,12 @@ function catchBasepath(basepath) {
 	return basepath;
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.149.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.148.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.149.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/RouteConfig.d.ts

@@ -67,9 +67,34 @@ interface BaseRouteConfig {
      */
     enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
     /**
-     * 라우터 URL 변경시 렌더링을 강제할지 여부
-     * - 기본값으로 children을 가질때 false로 설정되며, children이 없을 경우 true로 설정됩니다.
-     * - true로 설정하면 기존 렌더링을 무시하고 새로 렌더링합니다.
+     * 이 라우트의 콘텐츠를 **언제 새로 만들 것인가**를 정하는 식별 키입니다.
+     *
+     * 네비게이션마다 `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;
+    /**
+     * @deprecated `key`로 표현하세요 — `force: false`는 `key: () => ''`(상수 키)와 같고 `force: true`는
+     * 기본값과 같습니다. 이 판에서는 동작을 유지하며, 다음 minor에서 제거됩니다.
+     * ⚠이전 판에서는 자식이 없는 라우트에 `force: false`를 줘도 무시됐습니다(기본값 적용 순서의 결함).
+     * 이제 `force: false`는 모든 라우트에서 «유지»를 뜻합니다.
      */
     force?: boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/router",
-  "version": "0.11.4",
+  "version": "0.12.0",
   "description": "A modern client-side router for web applications with support for Lit and React components",
   "keywords": [
     "lit",
@@ -75,7 +75,7 @@
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "happy-dom": "^20.10.6",
-    "typescript": "^5.9.3",
+    "typescript": "^6.0.2",
     "vite": "^8.1.4",
     "vite-plugin-dts": "^5.0.3",
     "vitest": "^4.1.10"

package/skills/iyulab-router/SKILL.md

@@ -71,7 +71,8 @@ const router = new Router({
 | `children` | `RouteConfig[]` | Nested routes; parent must render `<u-outlet>` |
 | `title` | `string` | Sets `document.title` on match |
 | `metadata` | `Record<string, unknown>` | Arbitrary metadata (auth, layout, analytics) |
-| `force` | `boolean` | Force re-render on URL change (default `true` for leaf routes) |
+| `key` | `(ctx) => string` | When to remount: content is kept and re-rendered in place while the key is unchanged (Lit: same part, React: same root, `HTMLElement`: instance kept). Default `ctx => ctx.href` for leaf routes, a constant for routes with `children`. `key: ctx => ctx.pathname` keeps a page across query-string changes |
+| `force` | `boolean` | **Deprecated** — use `key`. `false` ≡ constant key (keep), `true` ≡ default |
 
 ## RouteContext Fields
 

package/skills/iyulab-router/references/components.md

@@ -49,11 +49,16 @@ A parent route must render `<u-outlet>` to host child route content.
 custom properties are available to lightly restyle it without replacing
 `fallback.render` entirely:
 
-| Custom Property | Description | Default |
-| --- | --- | --- |
-| `--error-icon-color` | Icon color | none — inherits the ambient text color |
-| `--error-code-color` | Error code text color | none — inherits the ambient text color |
-| `--error-message-color` | Error message text color | none — inherits the ambient text color |
+| Custom Property | Description | Default (light) | Default (dark) |
+| --- | --- | --- | --- |
+| `--error-icon-color` | Icon color | `#4a5568` | `#a0aec0` |
+| `--error-code-color` | Error code text color | `#1a202c` | `#f7fafc` |
+| `--error-message-color` | Error message text color | `#718096` | `#cbd5e0` |
+
+The defaults are concrete colors set on `:host`, not inherited — the dark column applies
+under `prefers-color-scheme: dark`. Because they are literals rather than design tokens,
+this page does not follow a host application's theme; set the three properties (or supply
+your own `fallback.render`) if it has to.
 
 ```css
 u-error-page {