@iyulab/router 0.12.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [0.14.0] - 2026-09-16
+
+### Changed
+
+- **`<u-outlet>` now declares its own `display: block`.** A custom element's UA default is
+  `inline`, and the outlet had no styles of its own — so a container meant to hold a route's
+  block-level screen generated an inline box. Consumers had to restate `u-outlet { display: block }`
+  in every application that cared, which is a rule only the package that defines the element can
+  reasonably own.
+
+  Two independent applications reported this from opposite directions on the same day — one
+  through printing (a short document gaining a blank trailing page), one through screen layout
+  (a table not reaching the bottom of the viewport). Both traced it to the same missing
+  declaration.
+
+  The declaration is `display: block; height: 100%`. The height half is not cosmetic: changing
+  `display` alone also changes which box a percentage height resolves against. While the outlet
+  was inline it was not a block container, so a screen's `height: 100%` resolved against the
+  block above it; making the outlet a block moves that reference onto the outlet itself, whose
+  height is `auto`, which silently voids the percentage and collapses full-height layouts to
+  their content height (measured: 747px → 60px for a screen built on
+  `@iyulab/modern-app`'s master-detail layout). `height: 100%` restores the chain, and resolves
+  to `auto` whenever the parent's height is `auto` — so ordinary document flow and printing,
+  where the shell releases its height, are unaffected.
+
+  The rule is adopted as a constructable stylesheet on whichever tree the outlet is connected to
+  (the document, or the shadow root when the outlet lives in one), written as
+  `:where(u-outlet)` so its specificity is zero — any `u-outlet { … }` rule an application writes
+  still wins without `!important`, regardless of sheet order. Where constructable sheets are not
+  available the rule is added as a `<style>` element instead.
+
+  **This changes layout in normal flow**, not only when printing: an inline box and a block box
+  differ in margin collapsing, and a block outlet can be given a height or a percentage size,
+  which an inline one silently ignored. Applications that place the outlet inside a flex or grid
+  container see no change — flex and grid items were already blockified. To keep the previous
+  behavior, set `u-outlet { display: inline }`; to keep the box but not the height, set
+  `u-outlet { height: auto }`. Neither needs `!important`.
+
+## [0.13.0] - 2026-09-13
+
+### Removed
+
+- **`RouteConfig.force`** — deprecated in 0.12.0, removed as announced. It only ever expressed
+  the two values `key` already covers: `force: false` is `key: () => ''` (keep the mounted
+  content across every navigation that matches the route), `force: true` is the default
+  (`ctx => ctx.href` — remount when the URL changes at all). Replace one with the other; a
+  route that never set `force` is unaffected. The property is gone from the type, so a stale
+  usage fails at compile time rather than silently doing nothing.
+
 ## [0.12.0] - 2026-09-13
 
 ### Added

package/README.md

@@ -141,6 +141,36 @@ const routes = [
 - `<u-link>`: SPA-aware anchor element
 - `<u-outlet>`: render target for matched route output
 
+## Outlet Layout
+
+`<u-outlet>` declares its own `display: block`. A custom element's UA default is
+`inline`, which would put a route's block-level screen inside an inline box — so the
+outlet adopts a single rule on whichever tree it is connected to (the document, or the
+shadow root if it lives in one):
+
+```css
+:where(u-outlet) { display: block; height: 100%; }
+```
+
+`height: 100%` is part of the same rule for a reason. A percentage height resolves against
+the nearest block container, so making the outlet a block moves that reference from the box
+*above* the outlet onto the outlet itself — and an `auto` height there voids the percentage
+silently, collapsing a full-height screen to its content height. Declaring `height: 100%`
+keeps the chain intact, and resolves to `auto` whenever the parent's height is `auto`, so
+ordinary document flow and printing are unaffected.
+
+The `:where()` wrapper makes the rule's specificity zero, so **any** `u-outlet { … }`
+rule your application writes wins, regardless of sheet order and without `!important`:
+
+```css
+u-outlet { display: flex; }          /* wins */
+u-outlet { height: auto; }           /* keep the box, drop the fill */
+u-outlet { display: inline; }        /* restores the pre-0.14.0 behavior */
+@media print { u-outlet { … } }      /* wins */
+```
+
+The rule is not media-scoped: the outlet is a block box on screen and in print alike.
+
 `<u-link>` supports `href`, `target`, `rel`, and `navigate`.
 
 ```html

package/dist/components/ULink.d.ts

@@ -64,7 +64,7 @@ export declare class ULink extends LitElement {
     /**
      * 호스트에 세팅된 `aria-current`/`aria-label`은 실제 접근 가능한(포커스 대상)
      * 엘리먼트가 아니라 — 그 안쪽 shadow DOM 의 네이티브 `<a>`다. 섀도우 경계를
-     * 넘지 않으므로 접근성 트리에 자동 반영되지 않는다(docket #45 실측 — 속성은
+     * 넘지 않으므로 접근성 트리에 자동 반영되지 않는다(실측 — 속성은
      * 붙어 있는데 접근성 트리의 `aria-current`는 계속 비어 있음). `render()`가 이
      * 값을 읽어 내부 `<a>`에 직접 옮긴다.
      *

package/dist/components/UOutlet.d.ts

@@ -22,6 +22,7 @@ declare class UOutlet extends HTMLElement {
     private root?;
     /** 진행 중인 render — 다음 render 는 이것이 끝난 뒤 판정한다 */
     private pending?;
+    connectedCallback(): void;
     /**
      * 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
      *

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-ByPkeTq1.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-tRZgJ1SR.js";
 import { LitElement, css, html } from "lit";
 import { customElement, property } from "lit/decorators.js";
 //#region src/types/RouteError.ts
@@ -302,13 +302,12 @@ var createURLPattern = URLPattern;
 * `key` 가 없을 때의 기본 식별 키 — «언제 새로 만드는가» 의 기본 규칙.
 *
 * 자식이 없는 라우트는 URL(`href`) 이 조금이라도 바뀌면 새로 마운트하고, 자식을 가진 라우트
-* (레이아웃)는 상수 키로 유지된다 — 종전의 `force` 기본값(leaf true · parent false)과 같은
-* 결과다. 다만 종전 코드는 `route.force ||= true` 라서 소비자가 leaf 에 `force: false` 를
-* 명시해도 `true` 로 덮였다(`false || true`). `force` 는 deprecate 됐지만 이 판에서는
-* 존중한다: `false` 는 «유지», `true` 는 «새로».
+* (레이아웃)는 상수 키로 유지된다. 그 밖의 규칙은 소비자가 `key` 로 직접 준다 — 예전의
+* `force` 불리언은 이 두 값(«유지»·«새로»)밖에 표현하지 못해 `key` 로 대체됐고 0.13.0 에서
+* 제거됐다(`force: false` ≡ `key: () => ''` · `force: true` ≡ 기본값).
 */
-function defaultKey(route, hasChildren) {
-	return route.force === false || hasChildren && route.force !== true ? () => "" : (ctx) => ctx.href;
+function defaultKey(hasChildren) {
+	return hasChildren ? () => "" : (ctx) => ctx.href;
 }
 /**
 * 라우트들을 다음 사항에 따라 재귀적으로 재설정합니다.
@@ -326,15 +325,15 @@ function setRoutes(routes, basepath) {
 		route.ignoreCase ||= false;
 		if (route.index === true) {
 			route.path = new createURLPattern({ pathname: `${basepath}{/}?` }, { ignoreCase: route.ignoreCase });
-			route.key ??= defaultKey(route, false);
+			route.key ??= defaultKey(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.key ??= defaultKey(route, true);
-			} else route.key ??= defaultKey(route, false);
+				route.key ??= defaultKey(true);
+			} else route.key ??= defaultKey(false);
 		}
 	}
 	return routes;

package/dist/react.js

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

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

@@ -3,9 +3,64 @@ import { customElement, property } from "lit/decorators.js";
 import { ifDefined } from "lit/directives/if-defined.js";
 //#region src/components/UOutlet.ts
 /**
+* `<u-outlet>` 의 기본 표시 방식.
+*
+* ★커스텀 엘리먼트의 UA 기본값은 `inline` 이다 — 라우트 화면(블록 요소들)을 인라인 상자에
+*   담으면 block-in-inline 분할이 생겨, 인쇄에서 짧은 문서에 빈 꼬리 쪽이 붙는다. 컨테이너
+*   요소의 표시 방식은 그것을 정의한 쪽이 선언해야 하고, 그 쪽은 이 패키지다.
+* ★`:where(u-outlet)` 로 특이도를 0 으로 둔다 — 소비자의 `u-outlet { … }` 규칙이 시트 순서와
+*   무관하게 `!important` 없이 이긴다.
+* ⚠constructable 시트(`adoptedStyleSheets`)를 쓴다 — `<style>` 요소와 달리 CSP 의 인라인
+*   스타일 제한에 걸리지 않는다. 지원하지 않는 환경에서는 `<style>` 로 대신한다.
+* ⚠매체를 가르지 않는다 — 인라인 컨테이너는 화면에서도 의도된 적이 없다(라인 박스 때문에
+*   높이를 줄 수도, 백분율로 채울 수도 없었다). 인쇄에만 한정하면 화면·인쇄가 서로 다른
+*   상자 모델을 갖게 되어 같은 부류의 차이가 다음에 또 난다.
+* 🔴`height: 100%` 가 함께 있어야 한다 — `display` 만 바꾸면 **백분율 높이의 기준 상자가
+*   바뀐다.** 종전(inline)에는 아웃렛이 블록 컨테이너가 아니라, 라우트 화면의 `height: 100%`
+*   가 그 «위» 의 블록(셸의 본문 영역)에 대해 풀렸다. 아웃렛을 block 으로 만들면 기준이
+*   아웃렛 자신이 되는데 그 높이가 `auto` 라 백분율이 무효가 되고, 화면을 채우도록 만들어진
+*   레이아웃(`u-master-detail-layout` 의 `:host{height:100%}` 등)이 내용 높이로 무너진다.
+*   실측(chromium): 같은 화면이 inline 747px → block 60px → block+height:100% 747px.
+*   ⚠부모 높이가 `auto` 면 `100%` 는 `auto` 로 풀리므로 인쇄(셸이 높이를 놓는다)와 일반
+*   문서 흐름에는 영향이 없다 — 이 선언이 «채우기» 를 강요하는 것은 부모가 높이를 가진
+*   경우뿐이고, 그것이 종전 동작이다.
+*/
+var OUTLET_DISPLAY_CSS = ":where(u-outlet) { display: block; height: 100%; }";
+/** 시트를 이미 채택한 트리 — 같은 트리에 두 번 넣지 않는다. */
+var styledRoots = /* @__PURE__ */ new WeakSet();
+/**
+* 아웃렛이 실제로 속한 트리에 표시 규칙을 채택한다.
+*
+* ⚠`document` 로 못박지 않는다 — 섀도 루트 안의 `<u-outlet>` 은 문서 시트가 닿지 않아
+*   기본 `inline` 그대로 남는다. 아웃렛을 라이트 DOM 에 두는 것이 이 생태계의 관례이지만,
+*   그 관례를 어긴 배치에서 조용히 규칙이 사라지는 쪽이 더 나쁘다.
+*/
+function adoptOutletDisplay(node) {
+	const isDocument = node.nodeType === 9;
+	const isShadowRoot = node.nodeType === 11 && "host" in node;
+	if (!isDocument && !isShadowRoot) return;
+	const root = node;
+	if (styledRoots.has(root)) return;
+	styledRoots.add(root);
+	if ("adoptedStyleSheets" in root && typeof CSSStyleSheet !== "undefined" && typeof CSSStyleSheet.prototype.replaceSync === "function") {
+		const sheet = new CSSStyleSheet();
+		sheet.replaceSync(OUTLET_DISPLAY_CSS);
+		root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+		return;
+	}
+	const ownerDocument = isDocument ? root : node.ownerDocument;
+	if (!ownerDocument) return;
+	const style = ownerDocument.createElement("style");
+	style.textContent = OUTLET_DISPLAY_CSS;
+	(isDocument ? root.head : root)?.prepend(style);
+}
+/**
 * LitElement 또는 React 컴포넌트를 렌더링해주는 웹컴포넌트 입니다.
 */
 var UOutlet = class extends HTMLElement {
+	connectedCallback() {
+		adoptOutletDisplay(this.getRootNode());
+	}
 	/**
 	* 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
 	*
@@ -1120,7 +1175,7 @@ var ULink = class ULink extends LitElement {
 	/**
 	* 호스트에 세팅된 `aria-current`/`aria-label`은 실제 접근 가능한(포커스 대상)
 	* 엘리먼트가 아니라 — 그 안쪽 shadow DOM 의 네이티브 `<a>`다. 섀도우 경계를
-	* 넘지 않으므로 접근성 트리에 자동 반영되지 않는다(docket #45 실측 — 속성은
+	* 넘지 않으므로 접근성 트리에 자동 반영되지 않는다(실측 — 속성은
 	* 붙어 있는데 접근성 트리의 `aria-current`는 계속 비어 있음). `render()`가 이
 	* 값을 읽어 내부 `<a>`에 직접 옮긴다.
 	*

package/dist/types/RouteConfig.d.ts

@@ -90,13 +90,6 @@ interface BaseRouteConfig {
      * ```
      */
     key?: (ctx: RouteContext) => string;
-    /**
-     * @deprecated `key`로 표현하세요 — `force: false`는 `key: () => ''`(상수 키)와 같고 `force: true`는
-     * 기본값과 같습니다. 이 판에서는 동작을 유지하며, 다음 minor에서 제거됩니다.
-     * ⚠이전 판에서는 자식이 없는 라우트에 `force: false`를 줘도 무시됐습니다(기본값 적용 순서의 결함).
-     * 이제 `force: false`는 모든 라우트에서 «유지»를 뜻합니다.
-     */
-    force?: boolean;
     /**
      * 경로 매칭시 대소문자 구분 여부
      * @default false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/router",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "A modern client-side router for web applications with support for Lit and React components",
   "keywords": [
     "lit",
@@ -71,13 +71,16 @@
     }
   },
   "devDependencies": {
+    "@vitest/browser-playwright": "^5.0.0",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "happy-dom": "^20.10.6",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "typescript": "^6.0.2",
     "vite": "^8.1.4",
     "vite-plugin-dts": "^5.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.0"
   }
 }

package/skills/iyulab-router/SKILL.md

@@ -27,7 +27,7 @@ npm install @iyulab/router
 | `RouterConfig` | Constructor config type |
 | `RouteContext` | Passed to every `render()` call |
 | `FallbackRouteConfig` | Error/404 fallback definition |
-| `<u-outlet>` | Renders the matched route output |
+| `<u-outlet>` | Renders the matched route output (a block box — see `references/components.md`) |
 | `<u-link>` | Client-side navigation anchor |
 | `UOutlet`, `ULink` | React wrappers (from `@iyulab/router/react`) |
 
@@ -72,7 +72,6 @@ const router = new Router({
 | `title` | `string` | Sets `document.title` on match |
 | `metadata` | `Record<string, unknown>` | Arbitrary metadata (auth, layout, analytics) |
 | `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

@@ -38,6 +38,36 @@ export function AppRoot() {
 }
 ```
 
+## Outlet Layout
+
+`<u-outlet>` declares its own `display: block`. A custom element's UA default is
+`inline`, which would put a route's block-level screen inside an inline box — so the
+outlet adopts a single rule on whichever tree it is connected to (the document, or the
+shadow root if it lives in one):
+
+```css
+:where(u-outlet) { display: block; height: 100%; }
+```
+
+`height: 100%` is part of the same rule for a reason. A percentage height resolves against
+the nearest block container, so making the outlet a block moves that reference from the box
+*above* the outlet onto the outlet itself — and an `auto` height there voids the percentage
+silently, collapsing a full-height screen to its content height. Declaring `height: 100%`
+keeps the chain intact, and resolves to `auto` whenever the parent's height is `auto`, so
+ordinary document flow and printing are unaffected.
+
+The `:where()` wrapper makes the rule's specificity zero, so **any** `u-outlet { … }`
+rule your application writes wins, regardless of sheet order and without `!important`:
+
+```css
+u-outlet { display: flex; }          /* wins */
+u-outlet { height: auto; }           /* keep the box, drop the fill */
+u-outlet { display: inline; }        /* restores the pre-0.14.0 behavior */
+@media print { u-outlet { … } }      /* wins */
+```
+
+The rule is not media-scoped: the outlet is a block box on screen and in print alike.
+
 ## Nested Outlet Rule
 
 A parent route must render `<u-outlet>` to host child route content.