@iyulab/router 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,94 @@
 # Changelog
 
+## [0.15.0] - 2026-09-16
+
+### Changed
+
+- **`<u-outlet>` now grows when a screen overflows a fixed-height parent.** 0.14.0 declared
+  `display: block; height: 100%`, which gives a screen the height it needs to fill a sized
+  parent but also pins the outlet to exactly that height. A screen taller than the parent
+  therefore overflowed the outlet's box instead of growing it, and a scrolling ancestor adds
+  its end padding to the scrollable area of its *in-flow children*, not of what those children
+  overflow with. The end gutter dropped out of the scrollable area: scrolling to the bottom of
+  a long screen left the content flush against the container's edge, while the gutter survived
+  on the other three sides.
+
+  Swapping `height` for `min-height` is not the fix. A percentage height only resolves against
+  a parent whose `height` is specified, and a minimum does not satisfy that — so on a block (or
+  flex) box a descendant's `height: 100%` computes to `auto`, and every layout built to fill the
+  viewport collapses to its content height.
+
+  A grid container gives both behaviors at once. A grid item stretches to its area by default,
+  which fills without resolving a percentage, so the chain survives while the container's own
+  height is indefinite — and because that height is `auto`, the box grows past the minimum when
+  content demands it. The rule is now:
+
+  ```css
+  :where(u-outlet) { display: grid; min-height: 100%; }
+  ```
+
+  Multiple children behave as before: a track stretches, but an item with a definite height does
+  not. The rule deliberately omits `align-content` and relies on the initial `normal` — setting
+  `align-content: start` stops the track from stretching and silently voids the fill chain.
+
+  Specificity is still zero, so an application's own `u-outlet { … }` rule wins without
+  `!important`, exactly as in 0.14.0. `u-outlet { display: block; height: 100% }` restores the
+  0.14.0 box model and `u-outlet { display: inline }` restores the pre-0.14.0 one.
+
+### Contract addition
+
+- **Making the outlet *smaller* now takes two declarations.** `min-height` is a floor, so
+  `u-outlet { height: 200px }` on its own still measures the parent's height. Write
+  `u-outlet { min-height: 0; height: 200px }`. Making the outlet larger, or replacing its
+  `display`, needs nothing extra. This is the only behavioral difference for an application
+  that was already overriding the rule.
+
+### Tests
+
+- The browser suite covering the outlet's box model grows from 9 cases to 15. The overflow
+  topology — a parent with a definite height holding a taller child — was not covered before,
+  which is why the previous rule shipped green: the suite pinned "an auto-height parent leaves
+  the outlet auto" but never its opposite. Also pinned now: the two-declaration override above,
+  multiple children keeping their own heights, and `align-content` breaking the fill chain.
+
+## [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

package/README.md

@@ -141,6 +141,65 @@ const routes = [
 - `<u-link>`: SPA-aware anchor element
 - `<u-outlet>`: render target for matched route output
 
+## Outlet Layout
+
+`<u-outlet>` declares its own box model. 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: grid; min-height: 100%; }
+```
+
+The outlet has to be two things at once, and no single declaration gives both:
+
+1. **It passes a sized parent's height down**, so a screen's `height: 100%` resolves here.
+2. **It grows with a screen taller than the parent**, so the overflow stays inside the
+   outlet's box rather than escaping it.
+
+`height: 100%` gives only the first. It pins the outlet to the parent's height, so a taller
+screen overflows the outlet — and a scrolling ancestor adds its end padding to the scrollable
+area of its in-flow children, not of what those children overflow with. The end gutter drops
+out: scrolling to the bottom of a long screen leaves the content flush against the container's
+edge while the gutter survives on the other three sides.
+
+`min-height: 100%` alone breaks the first. A percentage height only resolves against a parent
+whose `height` is specified, and a minimum does not satisfy that — so on a block (or flex) box
+a descendant's `height: 100%` computes to `auto` and every fill-the-viewport layout collapses
+to its content height.
+
+A grid container gives both. A grid item stretches to its area by default, which fills without
+resolving a percentage, so the chain survives while the container's own height is indefinite —
+and because that height is `auto`, the box grows past the minimum when content demands it.
+Multiple children are unaffected: a track stretches, but an item with a definite height does not.
+
+The rule deliberately omits `align-content`; it relies on the initial `normal`. Setting
+`align-content: start` stops the track from stretching and silently voids case 1.
+
+When the parent's own height is `auto`, `min-height: 100%` resolves to `auto` too, so ordinary
+document flow and printing are unaffected.
+
+### Overriding it
+
+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 { 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 */
+@media print { u-outlet { … } }                /* wins */
+```
+
+> **Making the outlet *smaller* takes two declarations, not one.** `min-height` is a floor, so
+> `u-outlet { height: 200px }` on its own still measures the parent's height. Write
+> `u-outlet { min-height: 0; height: 200px }`. Making it *larger*, or replacing `display`, needs
+> nothing extra. This is the only contract addition in 0.15.0.
+
+The rule is not media-scoped: the outlet is a block-level box on screen and in print alike.
+
 `<u-link>` supports `href`, `target`, `rel`, and `navigate`.
 
 ```html

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

package/dist/react.js

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

package/dist/{share-A3Fla8oW.js → share-RyrbTDel.js}

@@ -3,9 +3,96 @@ 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>` 로 대신한다.
+* ⚠매체를 가르지 않는다 — 인라인 컨테이너는 화면에서도 의도된 적이 없다(라인 박스 때문에
+*   높이를 줄 수도, 백분율로 채울 수도 없었다). 인쇄에만 한정하면 화면·인쇄가 서로 다른
+*   상자 모델을 갖게 되어 같은 부류의 차이가 다음에 또 난다.
+*
+* ## 왜 `grid` + `min-height` 인가 — 두 요구가 한 선언으로는 안 된다
+*
+* 아웃렛은 **동시에 두 가지**여야 한다:
+*   ⑴부모가 높이를 가지면 **그 높이를 자손에게 물려준다**(자손의 `height:100%` 가 여기서 풀린다)
+*   ⑵화면이 부모보다 크면 **자기도 함께 자란다**(넘침이 아웃렛 «밖» 으로 새지 않는다)
+*
+* 🔴`height: 100%` 는 ⑴만 준다. 0.14.0 이 그 판이었다 — 콘텐츠 영역이 고정 높이일 때
+*   아웃렛이 그 높이로 **못 박히고**
+*   화면이 밖으로 넘쳐, 스크롤 컨테이너의 끝 패딩이 스크롤 영역에서 빠진다 — 긴 화면을 끝까지
+*   내리면 **내용이 바닥에 붙는다**(거터가 위·좌·우에만 남는다).
+* 🔴`min-height: 100%` 만으로는 ⑴이 깨진다. 백분율 높이는 부모의 **`height`** 가 명시됐을 때만
+*   풀리고 `min-height` 는 그 조건을 만족시키지 않는다(CSS2.1 §10.5) — 그래서 `block` 이든
+*   `flex` 든 `min-height` 로 바꾸면 자손의 `height:100%` 가 `auto` 로 풀려 화면이 무너진다.
+* ✅`grid` 만 둘을 함께 준다. 그리드 항목의 기본 `align-self: stretch` 가 «백분율을 푸는 것» 이
+*   아니라 **영역을 채우는 것**이라, 컨테이너 높이가 부정(indefinite)이어도 ⑴이 성립한다.
+*   그리고 컨테이너 높이가 `auto` 라 내용이 크면 ⑵대로 자란다.
+*
+* 실측(chromium · 셸 본문 720px `padding:32px` `overflow:auto` / 화면 1588px):
+*
+* | 규칙                             | 전체높이: 표 | 넘침: `scrollHeight` | 아웃렛 박스 |
+* |----------------------------------|-------------:|---------------------:|------------:|
+* | `inline`(0.13.0 이전)            |          616 |                    — |           — |
+* | `block; height:100%`(0.14.0)     |          616 |            🔴 1620   |  656(고정)  |
+* | `contents`                       |          616 |                 1652 |  0(박스 없음)|
+* | **`grid; min-height:100%`**      |      **616** |             **1652** | **1588**    |
+* | `flex column; min-height:100%`   |        🔴 0  |                 1652 |        1588 |
+* | `block; min-height:100%`         |        🔴 0  |                 1652 |        1588 |
+*
+* ⚠**`contents` 를 택하지 않은 이유는 수치가 아니라 박스다** — 박스가 사라지면 소비자의
+*   `u-outlet { padding }`·`{ background }` 와 `getBoundingClientRect()` 가 **오류 없이 아무 일도
+*   안 하게** 된다. 아웃렛이 높이를 끊는 증상 자체가 「내 CSS 가 안 먹는다」로 나타나므로,
+*   그 부류를 새로 만들지 않는다. grid 는 `contents` 의 두 수치를 내면서 박스를 남긴다.
+* ⚠**`align-content` 를 선언하지 말 것** — `start` 를 주면 트랙이 늘어나지 않아 ⑴이 조용히
+*   깨진다(실측: 자손 400px → 0px). 기본값 `normal` 이어야 한다.
+* ⚠**자식이 둘 이상이어도 block 과 같다**(실측: 20px·30px 자식이 각각 20·30 그대로) — 트랙은
+*   늘어나지만 높이가 정해진 항목은 `stretch` 대상이 아니다.
+* ⚠**부모 높이가 `auto` 면 `min-height:100%` 도 `auto` 로 풀린다** — 일반 문서 흐름과 인쇄를
+*   가두지 않는다.
+* 🔴**소비자가 아웃렛을 «줄이려면» `height` 만으로는 부족하고 `min-height: 0` 이 함께 필요하다**
+*   — 0.14.0 대비 유일한 계약 추가이며 README·CHANGELOG·참조 문서에 적혀 있다.
+*/
+var OUTLET_DISPLAY_CSS = ":where(u-outlet) { display: grid; min-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());
+	}
 	/**
 	* 주어진 렌더링 옵션에 따라 컨텐츠를 렌더링합니다.
 	*
@@ -1059,12 +1146,12 @@ function catchBasepath(basepath) {
 	return basepath;
 }
 //#endregion
-//#region \0@oxc-project+runtime@0.149.0/helpers/esm/decorateMetadata.js
+//#region \0@oxc-project+runtime@0.150.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.149.0/helpers/esm/decorate.js
+//#region \0@oxc-project+runtime@0.150.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iyulab/router",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "description": "A modern client-side router for web applications with support for Lit and React components",
   "keywords": [
     "lit",
@@ -71,6 +71,7 @@
     }
   },
   "devDependencies": {
+    "@vitest/browser-playwright": "^5.0.0",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
@@ -80,6 +81,6 @@
     "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`) |
 

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

@@ -38,6 +38,66 @@ export function AppRoot() {
 }
 ```
 
+## Outlet Layout
+
+`<u-outlet>` declares its own box model. 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: grid; min-height: 100%; }
+```
+
+The outlet has to be two things at once, and no single declaration gives both:
+
+1. **It passes a sized parent's height down**, so a screen's `height: 100%` resolves here.
+2. **It grows with a screen taller than the parent**, so the overflow stays inside the
+   outlet's box rather than escaping it.
+
+`height: 100%` gives only the first. It pins the outlet to the parent's height, so a taller
+screen overflows the outlet — and a scrolling ancestor adds its end padding to the scrollable
+area of its in-flow children, not of what those children overflow with. The end gutter drops
+out: scrolling to the bottom of a long screen leaves the content flush against the container's
+edge while the gutter survives on the other three sides.
+
+`min-height: 100%` alone breaks the first. A percentage height only resolves against a parent
+whose `height` is specified, and a minimum does not satisfy that — so on a block (or flex) box
+a descendant's `height: 100%` computes to `auto` and every fill-the-viewport layout collapses
+to its content height.
+
+A grid container gives both. A grid item stretches to its area by default, which fills without
+resolving a percentage, so the chain survives while the container's own height is indefinite —
+and because that height is `auto`, the box grows past the minimum when content demands it.
+Multiple children are unaffected: a track stretches, but an item with a definite height does not.
+
+The rule deliberately omits `align-content`; it relies on the initial `normal`. Setting
+`align-content: start` stops the track from stretching and silently voids case 1.
+
+When the parent's own height is `auto`, `min-height: 100%` resolves to `auto` too, so ordinary
+document flow and printing are unaffected.
+
+### Overriding it
+
+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 { 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 */
+@media print { u-outlet { … } }                /* wins */
+```
+
+> **Making the outlet *smaller* takes two declarations, not one.** `min-height` is a floor, so
+> `u-outlet { height: 200px }` on its own still measures the parent's height. Write
+> `u-outlet { min-height: 0; height: 200px }`. Making it *larger*, or replacing `display`, needs
+> nothing extra. This is the only contract addition in 0.15.0.
+
+The rule is not media-scoped: the outlet is a block-level box on screen and in print alike.
+
+
 ## Nested Outlet Rule
 
 A parent route must render `<u-outlet>` to host child route content.