@iyulab/modern-app 0.22.1 → 0.24.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## [0.24.0] - 2026-09-22
+
+### Fixed
+
+- **The shell draws its own chrome without reaching the network.** The mobile and sidebar
+  toggles were hard-coded to `lib="bootstrap"`, which `@iyulab/components` resolves over a CDN.
+  An app that registers its own bundled icons still could not reach those two, because the shell
+  never routed through that registration — so on a network-isolated deployment the toggles
+  stayed blank and a failing request repeated on every render. Working around it from outside
+  meant intercepting a globally registered library name, with an unclear blast radius. Both
+  toggles now resolve from the bundled internal set, as the overlay close button already did.
+- That asymmetry was a small defect of its own: one shell drew two different close glyphs, a
+  CDN-backed one in the mobile header and a bundled one on the overlay. **The visible change is
+  a slightly different stroke on three controls.**
+
+### Added
+
+- **`icons` config.** Overrides both the source and the individual names, per key. It takes
+  names as well as the library because the defaults are bundled-set names and another set is not
+  guaranteed to carry them — pointing the shell at your own icons needs both halves. See
+  `docs/configuration.md`.
+
+### Changed
+
+- 🔴 **The `@iyulab/components` peer range is now `>=1.43.0`** (was `>=1.42.0`). The shell's
+  chrome depends on `menu-2` and `layout-sidebar` existing in that package's built-in set, and
+  those names arrive in **1.43.0**. The old range admitted 1.42.x, which would have let
+  `components@1.42.4` install alongside this version with no warning at all — and then the shell
+  icons would be blank whether or not the deployment had network access, which is a wider
+  failure than the one this release fixes. Publishing in the right order does not prevent that:
+  ordering is a property of how we release, while the range is what a consumer is allowed to
+  install.
+
+### Notes
+
+- The regression test resolves each default name **against the bundle** rather than only
+  asserting which name the shell asks for. Asserting the name alone would let a typo blank the
+  icon with every assertion still passing.
+
+## [0.23.0] - 2026-09-21
+
+### Fixed
+
+- **Route content no longer paints through an open overlay.** The overlay frame sits at
+  `z-index: 1`, while route content routinely holds positioned descendants with a higher one —
+  a data grid's sticky header row and pinned columns sit at 2–4. Neither the content area nor
+  its wrapper established a stacking context, so those competed with the overlay frame in the
+  same context and won: the list showed through the panel meant to cover it. While the overlay
+  is open, the wrapper holding route content is now its own stacking context, so no `z-index`
+  in route content can outrank the panel. Raising the frame's own `z-index` was rejected as a
+  fix — it only moves the finish line, and a larger value in route content would win again.
+  The boundary applies only while the overlay is open, so nothing else about how route content
+  paints changes.
+
+### Added
+
+- **`part="main-content"`** on the wrapper holding route content, so the `inert` the shell
+  applies while the overlay is open is visible from outside. It is applied to this wrapper and
+  not to `part="main"` — that one is the scroll container and stays interactive — which made it
+  easy to read `inert` off `part="main"`, see `false`, and conclude the shell was not applying
+  it at all.
+
+### Documentation
+
+- **The overlay's ownership contract is now written down** — what the shell provides (placement,
+  paint order, `inert`, the close affordance, keeping the route mounted) and what stays with the
+  consumer (moving and restoring focus, Escape-to-close, any scrim, the panel's accessible
+  name). `docs/layout.md` had never documented the overlay slot at all, and its parts table was
+  missing `overlay` and `overlay-close`; both now match the skill pack's reference.
+
 ## [0.22.1] - 2026-09-19
 
 ### Fixed

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type * from './types/AppConfigs';
 export type * from './types/AppOptions';
 export type * from './types/AuthConfig';
 export type { SidebarPermissionGuard } from './layouts/SidebarPermission';
+export type { SidebarIconsConfig } from './layouts/SidebarLayout.types';
 export { filterSidebarItems } from './layouts/filterSidebarItems.js';
 export { PageHeader } from './components/PageHeader.js';
 export { GroupBox } from './components/GroupBox.js';

package/dist/layouts/SidebarLayout.d.ts

@@ -55,6 +55,18 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
      * 🔴로고는 홈(또는 `href`)으로 가는 **링크**다 — 종전엔 클릭만 받는 `img`·`span`·`u-icon` 이라 키보드로 닿지 않았고
      *   보조기술에 링크로 드러나지 않았다. `u-link` 는 `href` 가 없으면 basepath 로 SPA 이동하므로 종전 `app.navigate('')` 와 같다.
      */
+    /**
+     * 셸이 **자기 chrome 으로** 그리는 아이콘의 기본값 — 전부 `internal` 번들이라 네트워크를 타지 않는다.
+     *
+     * 🔴**0.24.0 이전에는 토글러 둘이 `bootstrap`(= jsdelivr CDN 조회)이었다.** 소비앱이 자기
+     * 아이콘을 빌드 시점에 전부 구워 등록해도 **셸이 쓰는 것만은 그 등록을 타지 않아**, 폐쇄망
+     * 배포에서 사이드바 토글이 빈 채로 남고 매번 실패하는 요청이 쌓였다. ⚠그리고 셸이 스스로
+     * 갈려 있었다 — 오버레이 닫기는 `internal`, 모바일 닫기는 `bootstrap` 이라 **한 셸이 서로
+     * 다른 X 를 둘 그렸다.**
+     */
+    private static readonly DEFAULT_ICONS;
+    /** 설정이 준 값이 있으면 그것을, 없으면 기본값을 돌려준다(키 단위 부분 오버라이드). */
+    private icon;
     private renderLogo;
     /** 사이드바 토글 핸들러 */
     private handleToggleButtonClick;

package/dist/layouts/SidebarLayout.js

@@ -21,27 +21,30 @@ import { ifDefined as _ } from "lit/directives/if-defined.js";
 import { createDevWarner as v } from "@iyulab/components/dist/utilities/devWarning.js";
 import { UProgressBar as y } from "@iyulab/components/dist/components/progress-bar/UProgressBar.js";
 //#region src/layouts/SidebarLayout.ts
-var b = v("@iyulab/modern-app"), x = 0;
-function S(e) {
+var b, x = v("@iyulab/modern-app"), S = 0;
+function C(e) {
 	let t = e.tagName;
 	if (t === "INPUT" || t === "TEXTAREA" || t === "SELECT" || e.isContentEditable) return !0;
 	let n = e.getAttribute("role");
 	return n === "textbox" || n === "searchbox" || n === "combobox" || n === "spinbutton";
 }
-function C(e) {
+function w(e) {
 	let t = getComputedStyle(e);
 	return (t.overflowY === "auto" || t.overflowY === "scroll") && e.scrollHeight > e.clientHeight;
 }
-function w(e, t) {
+function T(e, t) {
 	for (let n of e) if (n instanceof HTMLElement) {
-		if (C(n)) return n === t;
+		if (w(n)) return n === t;
 		if (n === t) break;
 	}
 	return !0;
 }
-var T = class extends i {
+var E = class extends i {
+	static {
+		b = this;
+	}
 	constructor(...t) {
-		super(...t), this.state = "default", this.locale = "", this.hasOverlay = !1, this.internals = typeof this.attachInternals == "function" ? this.attachInternals() : void 0, this.context = null, this.unsizedWarnKey = `unsized:${++x}`, this.isMatchedLink = (e) => !this.context || !e ? !1 : (e = typeof e == "string" ? new URLPattern(e, window.location.origin) : e, e.test(this.context.path, window.location.origin)), this.handleToggleButtonClick = () => {
+		super(...t), this.state = "default", this.locale = "", this.hasOverlay = !1, this.internals = typeof this.attachInternals == "function" ? this.attachInternals() : void 0, this.context = null, this.unsizedWarnKey = `unsized:${++S}`, this.isMatchedLink = (e) => !this.context || !e ? !1 : (e = typeof e == "string" ? new URLPattern(e, window.location.origin) : e, e.test(this.context.path, window.location.origin)), this.handleToggleButtonClick = () => {
 			let t = e.screen ?? "large";
 			t === "large" ? this.state = this.state === "default" ? "slim" : "default" : t === "medium" ? this.state = this.state === "slim" ? "modal" : "slim" : t === "small" ? this.state = this.state === "mobile" ? "mobile-open" : "mobile" : console.warn("Unknown screen size:", t);
 		}, this.handleBackdropClick = () => {
@@ -66,9 +69,9 @@ var T = class extends i {
 			this.fire("overlay-close", { cancelable: !1 });
 		}, this._handleMainKeydown = (e) => {
 			let t = e.composedPath()[0];
-			if (t instanceof HTMLElement && S(t)) return;
+			if (t instanceof HTMLElement && C(t)) return;
 			let n = this.shadowRoot?.querySelector(".main");
-			if (!n || !w(e.composedPath(), n)) return;
+			if (!n || !T(e.composedPath(), n)) return;
 			let r = n.clientHeight;
 			switch (e.key) {
 				case " ":
@@ -123,7 +126,7 @@ var T = class extends i {
 		process.env.NODE_ENV !== "production" && requestAnimationFrame(() => {
 			if (!this.isConnected) return;
 			let e = this.getBoundingClientRect().height;
-			e >= 200 || b(this.unsizedWarnKey, `u-sidebar-layout is only ${Math.round(e)}px tall — its height: 100% found no sized ancestor, so the shell sits at its own chrome height and the route area has almost no room. Give the root element a height (e.g. #app { height: 100vh } — app.load() does this for document.body).`);
+			e >= 200 || x(this.unsizedWarnKey, `u-sidebar-layout is only ${Math.round(e)}px tall — its height: 100% found no sized ancestor, so the shell sits at its own chrome height and the route area has almost no room. Give the root element a height (e.g. #app { height: 100vh } — app.load() does this for document.body).`);
 		});
 	}
 	render() {
@@ -138,8 +141,8 @@ var T = class extends i {
           aria-label=${a(this.locale || void 0).toggleMobileMenu}
           @click=${this.handleToggleButtonClick}>
           <u-icon
-            lib="bootstrap"
-            name=${this.state === "mobile-open" ? "x-lg" : "list"}
+            lib=${this.icon("lib")}
+            name=${this.state === "mobile-open" ? this.icon("close") : this.icon("menu")}
           ></u-icon>
         </u-button>
       </div>
@@ -156,8 +159,8 @@ var T = class extends i {
             aria-label=${a(this.locale || void 0).toggleSidebar}
             @click=${this.handleToggleButtonClick}>
             <u-icon
-              lib="bootstrap"
-              name="layout-sidebar"
+              lib=${this.icon("lib")}
+              name=${this.icon("sidebarToggle")}
             ></u-icon>
           </u-button>
         </div>
@@ -179,7 +182,7 @@ var T = class extends i {
         <div class="main" part="main" scrollable tabindex="-1" @keydown=${this._handleMainKeydown}>
           <u-progress-bar part="progress"></u-progress-bar>
 
-          <div class="main-content" ?inert=${this.hasOverlay}>
+          <div class="main-content" part="main-content" ?inert=${this.hasOverlay}>
             <slot></slot>
           </div>
         </div>
@@ -188,7 +191,7 @@ var T = class extends i {
           <u-button class="overlay-close" part="overlay-close" variant="ghost"
             aria-label=${a(this.locale || void 0).detailClose}
             @click=${this.handleOverlayClose}>
-            <u-icon lib="internal" name="x"></u-icon>
+            <u-icon lib=${this.icon("lib")} name=${this.icon("overlayClose")}></u-icon>
           </u-button>
           <slot name="overlay" @slotchange=${this.handleOverlaySlotChange}></slot>
         </div>
@@ -260,6 +263,18 @@ var T = class extends i {
 		}
 		return u;
 	}
+	static {
+		this.DEFAULT_ICONS = {
+			lib: "internal",
+			menu: "menu-2",
+			close: "x",
+			sidebarToggle: "layout-sidebar",
+			overlayClose: "x"
+		};
+	}
+	icon(e) {
+		return this.config?.icons?.[e] ?? b.DEFAULT_ICONS[e];
+	}
 	renderLogo() {
 		let e = this.config?.logo, t = this.config?.title ?? "Home";
 		if (!e || typeof e == "string") return e ? l`
@@ -293,6 +308,6 @@ var T = class extends i {
 r([f({
 	type: String,
 	reflect: !0
-}), n("design:type", Object)], T.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], T.prototype, "config", void 0), r([f({ type: String }), n("design:type", Object)], T.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", y === void 0 ? Object : y)], T.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], T.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], T.prototype, "context", void 0), T = r([d("u-sidebar-layout")], T);
+}), n("design:type", Object)], E.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], E.prototype, "config", void 0), r([f({ type: String }), n("design:type", Object)], E.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", y === void 0 ? Object : y)], E.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], E.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], E.prototype, "context", void 0), E = b = r([d("u-sidebar-layout")], E);
 //#endregion
-export { T as SidebarLayout };
+export { E as SidebarLayout };

package/dist/layouts/SidebarLayout.styles.js

@@ -211,6 +211,36 @@ var t = e`
     height: 100%;
   }
 
+  /*
+   * 오버레이가 열린 동안 «본문 영역»을 스태킹 컨텍스트로 만든다.
+   *
+   * 오버레이 틀은 z-index: 1 이고, 라우트 본문은 그보다 큰 z 를 일상적으로 쓴다 —
+   * 데이터 그리드의 sticky 머리행·고정 열이 2~4 에 있다. .main 도 .main-region 도
+   * 스태킹 컨텍스트를 만들지 않으므로 그것들과 오버레이 틀이 «같은 컨텍스트에서 직접
+   * 겨루고», 본문이 이긴다 — 덮으라고 띄운 패널을 목록이 뚫고 나온다.
+   *
+   * ⚠값을 올리는 처방(z-index 를 50 으로)은 소비자의 z 어휘가 커지면 같은 경주를 다시
+   *   한다. 경계를 세워야 한다.
+   *
+   * ⚠경계를 «어디에» 세우는가가 갈린다 — 넷을 픽셀 대조로 실측하고 골랐다:
+   *     · .overlay 자신을 컨텍스트로 → 자기 z 는 여전히 1 이라 바깥에서 3 에게 진다. ✗
+   *     · .main-region 을 컨텍스트로 → 본문과 오버레이를 «같은» 새 컨텍스트에 함께
+   *       가두므로 그 안에서 순서가 그대로다. ✗
+   *     · .main / .main-content 를 «상시» 컨텍스트로 → 오버레이는 이기지만 본문 안의
+   *       position: fixed 팝오버가 사이드바(z 1000) 위로 못 올라간다(상시 동작 변경).
+   *       .main 쪽은 셸 자신의 진행 막대(z 100)까지 오버레이 아래로 내린다. ✗
+   *     · 이 규칙 — 오버레이가 열린 동안만 .main-content 를 컨텍스트로 → 세 축 모두 유지. ✓
+   *
+   * ⇒ 경계가 필요한 조건은 정확히 «오버레이가 열려 있다» 이고, 그때만 세운다. 닫혀 있으면
+   *   겨룰 상대가 없다(.overlay.empty 는 display: none 이다).
+   * ⚠ .main 이 아니라 .main-content 인 것도 의도다 — 가두는 대상은 «소비자의 라우트 본문»
+   *   이지 셸 자신의 chrome 이 아니다. 진행 막대는 .main-content 밖(.main 직속)이라 이
+   *   경계에 걸리지 않고, 오버레이가 열린 채로 일어나는 라우트 전환을 계속 보고한다.
+   */
+  :host(:state(overlay)) .main-content {
+    isolation: isolate;
+  }
+
   .main u-progress-bar {
     --progress-bar-height: 4px;
     --progress-bar-track-color: transparent;

package/dist/layouts/SidebarLayout.types.d.ts

@@ -11,8 +11,36 @@ export type { SidebarLinkConfig } from '../components/SidebarLink';
 export type { SidebarSectionConfig } from '../components/SidebarSection';
 export type { SidebarGroupConfig } from '../components/SidebarGroup';
 export type { SidebarButtonConfig } from '../components/SidebarButton';
+/**
+ * 셸이 **자기 chrome 으로** 그리는 아이콘의 출처와 이름. 지정한 키만 기본값을 대체한다.
+ *
+ * 🔴**기본값은 네트워크를 타지 않는다.** `internal` 은 `@iyulab/components` 가 빌드 시점에
+ * 굽는 번들이라, 폐쇄망·오프라인 배포에서도 셸 아이콘이 비지 않는다. 0.24.0 이전에는 셸의
+ * 토글러 둘이 `bootstrap`(= jsdelivr CDN 조회)을 썼고, 소비자가 자기 아이콘을 전부 번들로
+ * 구워 등록해도 **셸이 쓰는 것만은 그 등록을 타지 않았다.**
+ *
+ * ⚠**`lib` 만 바꿀 때는 이름도 함께 봐야 한다** — 기본 이름들은 `internal` 번들의 이름이고,
+ * 다른 lib 이 같은 이름을 갖는다는 보장이 없다. 자기 아이콘 세트로 갈아끼울 때는 보통
+ * `lib` 과 이름을 함께 준다:
+ *
+ * ```ts
+ * icons: { lib: 'app', menu: 'list', close: 'x-lg', sidebarToggle: 'layout-sidebar' }
+ * ```
+ */
+export interface SidebarIconsConfig {
+    /** 아래 이름들을 해석할 아이콘 lib. 기본 `'internal'`(번들 — 네트워크 없음). */
+    lib?: string;
+    /** 모바일 헤더의 메뉴 «열기». 기본 `'menu-2'`. */
+    menu?: string;
+    /** 모바일 헤더의 메뉴 «닫기». 기본 `'x'`. */
+    close?: string;
+    /** 사이드바 접기/펼치기 토글. 기본 `'layout-sidebar'`. */
+    sidebarToggle?: string;
+    /** 오버레이 닫기 버튼. 기본 `'x'`. */
+    overlayClose?: string;
+}
 /** 사이드바 레이아웃 컴포넌트의 요소(part) 타입 */
-export type SidebarParts = 'host' | 'mobile-header' | 'sidebar' | 'sidebar-header' | 'sidebar-main' | 'sidebar-footer' | 'main' | 'progress' | 'overlay' | 'overlay-close';
+export type SidebarParts = 'host' | 'mobile-header' | 'sidebar' | 'sidebar-header' | 'sidebar-main' | 'sidebar-footer' | 'main' | 'main-content' | 'progress' | 'overlay' | 'overlay-close';
 /** 사이드바 상태 타입 */
 export type SidebarState = 'default' | 'slim' | 'modal' | 'mobile' | 'mobile-open';
 /** 사이드바 안에 HTML 또는 엘리먼트를 직접 렌더링하는 설정 */
@@ -64,6 +92,11 @@ export interface SidebarLayoutConfig {
      * "아무것도 안 함" — Vue Router의 `scrollBehavior` 미지정 기본값과 동일하다(breaking 아님).
      */
     scrollBehavior?: (context: RouteContext, main: HTMLElement) => void;
+    /**
+     * 셸 chrome 아이콘의 출처·이름 오버라이드. 지정한 키만 기본값을 대체한다.
+     * 기본값은 전부 `internal` 번들이라 **네트워크를 타지 않는다** — `SidebarIconsConfig` 참조.
+     */
+    icons?: SidebarIconsConfig;
     /** 사이드바 스타일 맵 */
     styles?: StyleMap<SidebarParts>;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.22.1",
+  "version": "0.24.0",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -64,7 +64,7 @@
     "lit": "^3.3.3"
   },
   "peerDependencies": {
-    "@iyulab/components": ">=1.42.0",
+    "@iyulab/components": ">=1.43.0",
     "@lit/react": ">=1.0.8",
     "react": ">=18.0.0"
   },

package/skills/modern-app/references/layout.md

@@ -27,6 +27,9 @@ interface SidebarLayoutConfig {
   /** Called on `route-done` (before focus moves to the container) with the new route's `RouteContext` and the scroll container itself — implement reset/save/restore here. Unset does nothing (same default as Vue Router's unset `scrollBehavior`). Also reachable outside the hook via the element's `.mainElement` accessor. */
   scrollBehavior?: (context: RouteContext, main: HTMLElement) => void;
 
+  /** Shell chrome icon source and names — `{ lib?, menu?, close?, sidebarToggle?, overlayClose? }`, only the keys you set replace the defaults. Defaults come from the bundled `internal` set, so the shell needs no network to draw its own toggles; give `lib` **and** the names to point it at your own set. */
+  icons?: SidebarIconsConfig;
+
   /** Per-part style overrides (CSS custom properties / inline styles). */
   styles?: StyleMap<SidebarParts>;
 }
@@ -256,7 +259,8 @@ Parts available for `styles` overrides on the root layout:
 | `sidebar-header` | Logo + title area |
 | `sidebar-main` | Scrollable main nav area |
 | `sidebar-footer` | Pinned footer area |
-| `main` | Main content area |
+| `main` | Main content area (the scroll container) |
+| `main-content` | Wrapper holding route content inside `main` — the shell puts `inert` here while the overlay is open |
 | `progress` | Top progress bar |
 | `overlay` | Route-independent overlay panel above `main` |
 | `overlay-close` | Overlay's close button |
@@ -334,6 +338,35 @@ To keep the underlying route mounted while a URL parameter drives the overlay op
 query-string change doesn't remount the whole screen), give the route a `key` that excludes that
 parameter — see [`docs/routing.md`](../../../docs/routing.md) `RouteConfig.key`.
 
+### What the shell owns, and what it does not
+
+The overlay is a **layer**, not a modal dialog. Splitting that precisely is what keeps a consumer
+from either re-implementing what the shell already does, or dropping what it does not.
+
+| Concern | Owner | How |
+|---|---|---|
+| Placement, size and scrolling of the panel | shell | `part="overlay"` covers the main region and scrolls on its own |
+| Painting above route content | shell | while the overlay is open, `part="main-content"` becomes its own stacking context, so a `z-index` in route content cannot paint through the panel |
+| Making route content non-interactive | shell | `inert` on `part="main-content"`, which propagates through the slot into your route content |
+| A close affordance | shell | `part="overlay-close"`, firing the non-cancelable `overlay-close` event |
+| Keeping the route mounted underneath | shell | the overlay is independent of routing |
+| **Moving focus into the panel when it opens** | **consumer** | focus the panel or its first control yourself |
+| **Restoring focus when it closes** | **consumer** | remember the trigger and re-focus it |
+| **Escape to close** | **consumer** | the shell binds no key; listen for it and empty the slot |
+| **A backdrop / dimmed scrim** | **consumer** | the panel is opaque and full-bleed by design; add a scrim inside your panel if you want one |
+| **Announcing the panel to assistive tech** | **consumer** | put `role`/`aria-label` (or `aria-modal`, if you have made it modal) on *your* panel — the shell does not know what it holds |
+
+⚠ **`inert` is applied to `part="main-content"`, not to `part="main"`.** `part="main"` is the scroll
+container and stays interactive so it can keep scrolling; the wrapper inside it is what goes inert.
+Reading `inert` off `part="main"` reports `false` and says nothing about whether the shell applied it.
+There is also no reliable way to check it by enumeration — `querySelectorAll` still returns focusable
+elements inside an inert subtree. Inertness shows up when something tries to *take* focus, not when
+you count what is there.
+
+⚠ **Page-level scroll is not locked**, deliberately. In the shell model `part="main"` is the scroller
+and the overlay covers it, so there is nothing behind it to scroll. If your app instead lets the
+document itself scroll, locking that is yours.
+
 No `overlayBreakpoint`/responsive toggle exists here — unlike `u-master-detail-layout`, this
 overlay is always an overlay, never a side-by-side pane. Use `u-master-detail-layout` instead
 when you want the panel to sit *beside* content on wide screens.