@iyulab/modern-app 0.20.1 → 0.22.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## [0.22.0] - 2026-09-18
+
+### Added
+
+- **`SidebarLayout` gained a `slot="overlay"`** — a route-independent panel shown above the main
+  content (e.g. a record detail), independent of the current route, without wrapping every route in
+  a shared layout or losing that route's scroll position. Fill the slot to show it; remove or
+  reassign the slotted node to dismiss it (`hidden` does not close it). Mirrors
+  `u-master-detail-layout`'s existing `slot="detail"` idiom rather than a new one. Adds a
+  `:state(overlay)` custom state, `inert` on the route content while the overlay has content, and a
+  built-in close button that fires a non-cancelable `overlay-close` event; the React wrapper maps
+  this to `onOverlayClose`. Documented in the layout skill reference under "Overlay content".
+
+### Fixed
+
+- **The shell's keyboard scroll handling no longer intercepts a scrollable container nested inside
+  route content.** Space, Page Up/Down, Home, End and the arrow keys inside a nested scroll box
+  (a detail pane, a split view) were previously captured and cancelled by the shell instead of
+  scrolling that box.
+- **The mobile layout (`state="mobile"`/`"mobile-open"`) no longer loses internal scrolling.** The
+  shell's scroll region lacked an explicit minimum-size override, so it could grow to the full
+  content height and stop scrolling within the viewport instead.
+- **An open overlay prints in normal document flow instead of being clipped** to the main content's
+  box, and no longer renders off-screen if opened while the content underneath was scrolled.
+- The documented "Overlay content" example now actually closes the overlay (it previously toggled
+  `hidden`, which does not empty the slot).
+
+## [0.21.0] - 2026-09-17
+
+### Added
+
+- **`translate()` — a reactive translation directive**, exported from `@iyulab/modern-app`. It is
+  bound to the i18next instance `app.load({ i18n })` initializes and re-renders its part when the
+  language changes, when resources arrive later, and once i18next finishes initializing (until then
+  it renders an empty string rather than the key). A disconnected template stops listening and
+  catches up when reconnected. Sidebar item labels already accept a directive result, so
+  `label: translate('nav::home')` now works without a third-party package; the documentation
+  previously pointed to `lit-i18n` for this. Migrating is an import swap plus dropping
+  `initLitI18n` from `i18n.plugins`.
+
+### Fixed
+
+- **A collapsed sidebar no longer leaves translated items without an accessible name.** In the
+  collapsed state the item label was removed with `hidden`, which also removes it from the
+  accessibility tree; an `aria-label` was substituted only when the label was a plain string, so an
+  item labelled with a directive was announced with no name. The label is now hidden visually and
+  stays in the accessibility tree, so it names the link, button or group whatever its type. Items
+  no longer carry an `aria-label` in the collapsed state.
+
 ## [0.20.1] - 2026-09-17
 
 ### Fixed

package/README.md

@@ -113,8 +113,8 @@ await app.load({
 app.i18n.t('common::greeting');
 app.i18n.changeLanguage('ko');
 
-// Reactive translations in Lit templates
-import { translate } from 'lit-i18n';
+// Reactive translations in Lit templates — and in shell labels
+import { translate } from '@iyulab/modern-app';
 html`<p>${translate('common::greeting')}</p>`;
 ```
 
@@ -263,7 +263,7 @@ contrast likewise comes from that package's tokens.
 | [layout.md](./docs/layout.md) | Sidebar layout, all menu item types, responsive behaviour |
 | [theme.md](./docs/theme.md) | Theme init, runtime switching, token layers, shell surface tokens |
 | [notifications.md](./docs/notifications.md) | Toast methods and options |
-| [i18n.md](./docs/i18n.md) | i18next setup, plugins, lit-i18n usage |
+| [i18n.md](./docs/i18n.md) | i18next setup, plugins, the `translate()` directive |
 | [configuration.md](./docs/configuration.md) | Full TypeScript interface reference |
 
 ## License

package/dist/components/SidebarButton.js

@@ -3,11 +3,11 @@ import t from "../_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorate.js
 import { StyledElement as n } from "../internals/StyledElement.js";
 import { DEFAULT_NAV_ICON as r } from "../internals/nav-icon.js";
 import { styles as i } from "./SidebarButton.styles.js";
-import { html as a, nothing as o } from "lit";
-import { customElement as s, property as c } from "lit/decorators.js";
+import { html as a } from "lit";
+import { customElement as o, property as s } from "lit/decorators.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
 //#region src/components/SidebarButton.ts
-var l = class extends n {
+var c = class extends n {
 	constructor(...e) {
 		super(...e), this.compact = !1;
 	}
@@ -15,24 +15,23 @@ var l = class extends n {
 		this.styles = [super.styles, i];
 	}
 	render() {
-		let e = this.compact && typeof this.label == "string" ? this.label : o;
 		return a`
-      <button part="base" ?compact=${this.compact} aria-label=${e}>
+      <button part="base" ?compact=${this.compact}>
         <u-icon part="icon"
           .lib=${this.lib}
           .name=${this.icon}
           .fallback=${r}
         ></u-icon>
-        <span part="label" ?hidden=${this.compact}>
+        <span part="label" ?compact=${this.compact}>
           ${this.label}
         </span>
       </button>
     `;
 	}
 };
-t([c({
+t([s({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Object)], l.prototype, "compact", void 0), t([c({ type: String }), e("design:type", String)], l.prototype, "icon", void 0), t([c({ type: String }), e("design:type", String)], l.prototype, "lib", void 0), t([c({ type: String }), e("design:type", Object)], l.prototype, "label", void 0), l = t([s("u-sidebar-button")], l);
+}), e("design:type", Object)], c.prototype, "compact", void 0), t([s({ type: String }), e("design:type", String)], c.prototype, "icon", void 0), t([s({ type: String }), e("design:type", String)], c.prototype, "lib", void 0), t([s({ type: String }), e("design:type", Object)], c.prototype, "label", void 0), c = t([o("u-sidebar-button")], c);
 //#endregion
-export { l as SidebarButton };
+export { c as SidebarButton };

package/dist/components/SidebarButton.styles.js

@@ -55,6 +55,22 @@ var t = e`
     overflow: hidden;
     text-overflow: ellipsis;
   }
+
+  /*
+   * 접힌 상태의 라벨 - 시각적으로만 숨긴다. 접근성 트리에는 남아 항목의 이름이 된다
+   * (hidden 은 트리에서도 빼서 이름 없는 항목을 만들었다). 절대배치라 flex 배치와 gap 에 끼지 않는다.
+   */
+  [part~='label'][compact] {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
 `;
 //#endregion
 export { t as styles };

package/dist/components/SidebarGroup.js

@@ -4,11 +4,11 @@ import { StyledElement as n } from "../internals/StyledElement.js";
 import { DEFAULT_NAV_ICON as r } from "../internals/nav-icon.js";
 import { SidebarLink as i } from "./SidebarLink.js";
 import { styles as a } from "./SidebarGroup.styles.js";
-import { html as o, nothing as s } from "lit";
-import { customElement as c, property as l } from "lit/decorators.js";
+import { html as o } from "lit";
+import { customElement as s, property as c } from "lit/decorators.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
 //#region src/components/SidebarGroup.ts
-var u = class extends n {
+var l = class extends n {
 	constructor(...e) {
 		super(...e), this.compact = !1, this.selected = !1, this.collapsed = !0, this.handleButtonClick = (e) => {
 			this.compact ? ((this.shadowRoot?.querySelector("slot")?.assignedElements({ flatten: !0 }).find((e) => e instanceof i))?.renderRoot.querySelector("u-link"))?.click() : this.collapsed = !this.collapsed;
@@ -18,12 +18,10 @@ var u = class extends n {
 		this.styles = [super.styles, a];
 	}
 	render() {
-		let e = this.compact && typeof this.label == "string" ? this.label : s;
 		return o`
       <button part="header"
         ?compact=${this.compact}
         ?selected=${this.selected}
-        aria-label=${e}
         @click=${this.handleButtonClick}>
         <!--
           ⚠ ?hidden 을 걸지 않는다. 접힌 상태에서는 라벨과 캐럿이 모두 숨으므로,
@@ -36,7 +34,7 @@ var u = class extends n {
           .name=${this.icon}
           .fallback=${r}
         ></u-icon>
-        <span class="label" part="label" ?hidden=${this.compact}>
+        <span class="label" part="label" ?compact=${this.compact}>
           ${this.label}
         </span>
         <u-icon class="caret" part="caret" ?hidden=${this.compact}
@@ -53,15 +51,15 @@ var u = class extends n {
     `;
 	}
 };
-t([l({
+t([c({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Boolean)], u.prototype, "compact", void 0), t([l({
+}), e("design:type", Boolean)], l.prototype, "compact", void 0), t([c({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Boolean)], u.prototype, "selected", void 0), t([l({
+}), e("design:type", Boolean)], l.prototype, "selected", void 0), t([c({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Boolean)], u.prototype, "collapsed", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "icon", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "lib", void 0), t([l({ type: String }), e("design:type", Object)], u.prototype, "label", void 0), u = t([c("u-sidebar-group")], u);
+}), e("design:type", Boolean)], l.prototype, "collapsed", void 0), t([c({ type: String }), e("design:type", String)], l.prototype, "icon", void 0), t([c({ type: String }), e("design:type", String)], l.prototype, "lib", void 0), t([c({ type: String }), e("design:type", Object)], l.prototype, "label", void 0), l = t([s("u-sidebar-group")], l);
 //#endregion
-export { u as SidebarGroup };
+export { l as SidebarGroup };

package/dist/components/SidebarGroup.styles.js

@@ -93,6 +93,22 @@ var t = e`
     height: 0;
     opacity: 0;
   }
+
+  /*
+   * 접힌 상태의 라벨 - 시각적으로만 숨긴다. 접근성 트리에는 남아 항목의 이름이 된다
+   * (hidden 은 트리에서도 빼서 이름 없는 항목을 만들었다). 절대배치라 flex 배치와 gap 에 끼지 않는다.
+   */
+  [part~='label'][compact] {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
 `;
 //#endregion
 export { t as styles };

package/dist/components/SidebarLink.js

@@ -15,14 +15,12 @@ var l = class extends n {
 		this.styles = [super.styles, i];
 	}
 	render() {
-		let e = this.compact && typeof this.label == "string" ? this.label : o;
 		return a`
       <u-link
         .href=${this.href || "#"}
         .navigate=${this.navigate}
         .target=${this.target}
         aria-current=${this.selected ? "page" : o}
-        aria-label=${e}
       >
         <div class="container" part="base" ?compact=${this.compact}>
           <u-icon part="icon"
@@ -30,7 +28,7 @@ var l = class extends n {
             .name=${this.icon}
             .fallback=${r}
           ></u-icon>
-          <span part="label" ?hidden=${this.compact}>
+          <span part="label" ?compact=${this.compact}>
             ${this.label}
           </span>
         </div>

package/dist/components/SidebarLink.styles.js

@@ -69,6 +69,22 @@ var t = e`
     overflow: hidden;
     text-overflow: ellipsis;
   }
+
+  /*
+   * 접힌 상태의 라벨 - 시각적으로만 숨긴다. 접근성 트리에는 남아 항목의 이름이 된다
+   * (hidden 은 트리에서도 빼서 이름 없는 항목을 만들었다). 절대배치라 flex 배치와 gap 에 끼지 않는다.
+   */
+  [part~='label'][compact] {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+    border: 0;
+  }
 `;
 //#endregion
 export { t as styles };

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export { ActionBar } from './components/ActionBar.js';
 export { MasterDetailLayout } from './components/MasterDetailLayout.js';
 export { Wizard } from './components/Wizard.js';
 export type { WizardStep, WizardStepState, WizardStepChangeDetail } from './components/Wizard.js';
+export { translate } from './translate.js';
 export { registerLocale, setDefaultLocale, getLocaleStrings, getDefaultLocale, } from './internals/locale.js';
 export type { ModernAppLocaleStrings } from './internals/locale.js';
 export { ScreenObserver } from './internals/ScreenObserver.js';

package/dist/index.js

@@ -10,7 +10,8 @@ import { EmptyState as f } from "./components/EmptyState.js";
 import { ActionBar as p } from "./components/ActionBar.js";
 import { MasterDetailLayout as m } from "./components/MasterDetailLayout.js";
 import { Wizard as h } from "./components/Wizard.js";
+import { translate as g } from "./translate.js";
 //#region src/index.ts
-var g = t;
+var _ = t;
 //#endregion
-export { p as ActionBar, f as EmptyState, c as GroupBox, u as InfoField, l as InfoSection, m as MasterDetailLayout, s as PageHeader, e as ScreenObserver, h as Wizard, t as app, g as default, n as filterSidebarItems, r as getDefaultLocale, i as getLocaleStrings, d as isBlank, a as registerLocale, o as setDefaultLocale };
+export { p as ActionBar, f as EmptyState, c as GroupBox, u as InfoField, l as InfoSection, m as MasterDetailLayout, s as PageHeader, e as ScreenObserver, h as Wizard, t as app, _ as default, n as filterSidebarItems, r as getDefaultLocale, i as getLocaleStrings, d as isBlank, a as registerLocale, o as setDefaultLocale, g as translate };

package/dist/internals/locale.d.ts

@@ -26,7 +26,7 @@ export interface ModernAppLocaleStrings {
     /** Empty state — records exist but the current query matched none. */
     noResultsTitle: string;
     noResultsDescription: string;
-    /** Master-detail layout — accessible label for the overlay-mode close button. */
+    /** Accessible label for an overlay-mode close button (master-detail layout, sidebar layout overlay). */
     detailClose: string;
     /** Sidebar layout — accessible label for the mobile-header menu toggle button. */
     toggleMobileMenu: string;

package/dist/layouts/SidebarLayout.d.ts

@@ -12,6 +12,14 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     /** 크롬 문자열(토글 버튼 접근성 라벨 등) 로케일 — `registerLocale`로 등록한 언어 태그 */
     locale: string;
     progressBarEl: UProgressBar;
+    /** overlay 슬롯 배정 상태 — CSS `:has()`로는 알 수 없다(`internals/slotted.ts` 참조). */
+    private hasOverlay;
+    /**
+     * `:state(overlay)`를 싣는 자리. `MasterDetailLayout`과 동일 패턴.
+     * ⚠생성자에서 한 번만 붙인다 — `attachInternals()`는 같은 인스턴스에 두 번 부르면
+     *   `NotSupportedError`이고, `connectedCallback`은 재연결마다 다시 돈다.
+     */
+    private readonly internals;
     /** 현재 라우터 컨텍스트 */
     context: RouteContext | null;
     /**
@@ -24,6 +32,7 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected willUpdate(changedProperties: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
     protected firstUpdated(changedProperties: PropertyValues): void;
     /**
      * 개발 모드 사용 안내: 이 셸은 `:host { height: 100% }` 로 부모를 채우는데, 부모(커스텀
@@ -61,6 +70,8 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     private handleRouteDone;
     /** 라우트 에러 핸들러 */
     private handleRouteError;
+    private handleOverlaySlotChange;
+    private handleOverlayClose;
     /** .main 키보드 스크롤 핸들러 (WCAG 2.1 SC 2.1.1) */
     private _handleMainKeydown;
     /** 화면 크기 변경에 따른 사이드바 상태 업데이트 */

package/dist/layouts/SidebarLayout.js

@@ -4,32 +4,44 @@ import n from "../_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorateMet
 import r from "../_virtual/_@oxc-project_runtime@0.150.0/helpers/esm/decorate.js";
 import { StyledElement as i } from "../internals/StyledElement.js";
 import { getLocaleStrings as a } from "../internals/locale.js";
+import { slotHasContent as o } from "../internals/slotted.js";
 import "../components/SidebarSection.js";
-import { DEFAULT_NAV_ICON as o } from "../internals/nav-icon.js";
+import { DEFAULT_NAV_ICON as s } from "../internals/nav-icon.js";
 import "../components/SidebarLink.js";
 import "../components/SidebarGroup.js";
 import "../components/SidebarButton.js";
-import { styles as s } from "./SidebarLayout.styles.js";
-import { html as c, nothing as l } from "lit";
-import { customElement as u, property as d, query as f, state as p } from "lit/decorators.js";
+import { styles as c } from "./SidebarLayout.styles.js";
+import { html as l, nothing as u } from "lit";
+import { customElement as d, property as f, query as p, state as m } from "lit/decorators.js";
 import "@iyulab/components/dist/components/button/UButton.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
-import { unsafeHTML as m } from "lit/directives/unsafe-html.js";
-import { repeat as h } from "lit/directives/repeat.js";
-import { ifDefined as g } from "lit/directives/if-defined.js";
-import { createDevWarner as _ } from "@iyulab/components/dist/utilities/devWarning.js";
-import { UProgressBar as v } from "@iyulab/components/dist/components/progress-bar/UProgressBar.js";
+import { unsafeHTML as h } from "lit/directives/unsafe-html.js";
+import { repeat as g } from "lit/directives/repeat.js";
+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 y = _("@iyulab/modern-app"), b = 0;
-function x(e) {
+var b = v("@iyulab/modern-app"), x = 0;
+function S(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";
 }
-var S = class extends i {
+function C(e) {
+	let t = getComputedStyle(e);
+	return (t.overflowY === "auto" || t.overflowY === "scroll") && e.scrollHeight > e.clientHeight;
+}
+function w(e, t) {
+	for (let n of e) if (n instanceof HTMLElement) {
+		if (C(n)) return n === t;
+		if (n === t) break;
+	}
+	return !0;
+}
+var T = class extends i {
 	constructor(...t) {
-		super(...t), this.state = "default", this.locale = "", this.context = null, this.unsizedWarnKey = `unsized:${++b}`, 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:${++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 = () => {
 			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 = () => {
@@ -48,11 +60,15 @@ var S = class extends i {
 			this.progressBarEl.status = "error", this.progressBarEl.value = 100, setTimeout(() => {
 				this.progressBarEl.removeAttribute("visible"), this.progressBarEl.status = "default";
 			}, 300);
+		}, this.handleOverlaySlotChange = (e) => {
+			this.hasOverlay = o(e.target);
+		}, this.handleOverlayClose = () => {
+			this.fire("overlay-close", { cancelable: !1 });
 		}, this._handleMainKeydown = (e) => {
 			let t = e.composedPath()[0];
-			if (t instanceof HTMLElement && x(t)) return;
+			if (t instanceof HTMLElement && S(t)) return;
 			let n = this.shadowRoot?.querySelector(".main");
-			if (!n) return;
+			if (!n || !w(e.composedPath(), n)) return;
 			let r = n.clientHeight;
 			switch (e.key) {
 				case " ":
@@ -83,7 +99,7 @@ var S = class extends i {
 		};
 	}
 	static {
-		this.styles = [super.styles, s];
+		this.styles = [super.styles, c];
 	}
 	get mainElement() {
 		return this.shadowRoot?.querySelector(".main") ?? null;
@@ -97,6 +113,9 @@ var S = class extends i {
 	willUpdate(e) {
 		super.willUpdate(e), e.has("config") && (this.styles = this.config?.styles);
 	}
+	updated(e) {
+		super.updated(e), e.has("hasOverlay") && this.internals?.states?.[this.hasOverlay ? "add" : "delete"]("overlay");
+	}
 	firstUpdated(e) {
 		super.firstUpdated(e), this.warnIfUnsized();
 	}
@@ -104,11 +123,11 @@ var S = class extends i {
 		process.env.NODE_ENV !== "production" && requestAnimationFrame(() => {
 			if (!this.isConnected) return;
 			let e = this.getBoundingClientRect().height;
-			e >= 200 || y(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 || 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).`);
 		});
 	}
 	render() {
-		return this.config ? c`
+		return this.config ? l`
       <!-- Mobile Header -->
       <div class="mobile-header" part="mobile-header" ?hidden="${!this.state.startsWith("mobile")}">
         ${this.renderLogo()}
@@ -145,38 +164,51 @@ var S = class extends i {
 
         <!-- Sidebar Navigation Menu -->
         <nav class="sidebar-main" part="sidebar-main" scrollable
-          aria-label=${this.config.mainAriaLabel ?? l}>
-          ${h(t(this.config.main ?? [], this.config.hasPermission), (e, t) => t, (e) => this.renderItem(e))}
+          aria-label=${this.config.mainAriaLabel ?? u}>
+          ${g(t(this.config.main ?? [], this.config.hasPermission), (e, t) => t, (e) => this.renderItem(e))}
         </nav>
 
         <!-- Sidebar Footer -->
         <div class="sidebar-footer" part="sidebar-footer">
-          ${h(t(this.config.footer ?? [], this.config.hasPermission), (e, t) => t, (e) => this.renderItem(e))}
+          ${g(t(this.config.footer ?? [], this.config.hasPermission), (e, t) => t, (e) => this.renderItem(e))}
         </div>
       </aside>
 
       <!-- Main Content -->
-      <div class="main" part="main" scrollable tabindex="-1" @keydown=${this._handleMainKeydown}>
-        <u-progress-bar part="progress"></u-progress-bar>
+      <div class="main-region">
+        <div class="main" part="main" scrollable tabindex="-1" @keydown=${this._handleMainKeydown}>
+          <u-progress-bar part="progress"></u-progress-bar>
 
-        <slot></slot>
+          <div class="main-content" ?inert=${this.hasOverlay}>
+            <slot></slot>
+          </div>
+        </div>
+
+        <div class="overlay ${this.hasOverlay ? "" : "empty"}" part="overlay">
+          <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-button>
+          <slot name="overlay" @slotchange=${this.handleOverlaySlotChange}></slot>
+        </div>
       </div>
 
       <!-- Backdrop for modal state -->
       <div class="backdrop" ?hidden="${this.state !== "modal"}"
         @click="${this.handleBackdropClick}"
       ></div>
-    ` : l;
+    ` : u;
 	}
 	renderItem(e) {
-		if (!e) return l;
+		if (!e) return u;
 		if (e.type === "html") {
 			let t = e.render(this.state);
-			return typeof t == "string" ? m(t) : c`${t}`;
+			return typeof t == "string" ? h(t) : l`${t}`;
 		}
-		if (e.type === "button") return c`
+		if (e.type === "button") return l`
         <u-sidebar-button
-          id=${g(e.id)}
+          id=${_(e.id)}
           ?compact=${this.state === "slim"}
           .icon="${e.icon}"
           .lib="${e.lib}"
@@ -187,7 +219,7 @@ var S = class extends i {
       `;
 		if (e.type === "link") {
 			let t = this.isMatchedLink(e.pattern || e.href);
-			return c`
+			return l`
         <u-sidebar-link
           ?compact=${this.state === "slim"}
           ?selected=${t}
@@ -202,18 +234,18 @@ var S = class extends i {
         ></u-sidebar-link>
       `;
 		}
-		if (e.type === "section") return c`
+		if (e.type === "section") return l`
         <u-sidebar-section
           ?compact=${this.state === "slim"}
           .mainTitle="${e.title}"
           .subTitle="${e.subTitle}"
           .styles="${e.styles}">
-          ${h(e.items, (e, t) => t, (e) => this.renderItem(e))}
+          ${g(e.items, (e, t) => t, (e) => this.renderItem(e))}
         </u-sidebar-section>
       `;
 		if (e.type === "group") {
 			let t = e.items.some((e) => this.isMatchedLink(e.pattern || e.href));
-			return c`
+			return l`
         <u-sidebar-group
           ?compact=${this.state === "slim"}
           ?selected=${t}
@@ -222,34 +254,34 @@ var S = class extends i {
           .lib="${e.lib}"
           .label="${e.label}"
           .styles="${e.styles}">
-          ${h(e.items, (e, t) => t, (e) => this.renderItem(e))}
+          ${g(e.items, (e, t) => t, (e) => this.renderItem(e))}
         </u-sidebar-group>
       `;
 		}
-		return l;
+		return u;
 	}
 	renderLogo() {
 		let e = this.config?.logo, t = this.config?.title ?? "Home";
-		if (!e || typeof e == "string") return e ? c`
+		if (!e || typeof e == "string") return e ? l`
         <u-link class="logo-link" aria-label=${t}>
           <u-icon class="logo"
             .name="${e}"
-            .fallback=${o}
+            .fallback=${s}
           ></u-icon>
         </u-link>
-      ` : c`<u-icon class="logo"></u-icon>`;
+      ` : l`<u-icon class="logo"></u-icon>`;
 		if (typeof e == "function") {
 			let n = e(this.state);
-			return c`
+			return l`
         <u-link class="logo-link" aria-label=${t}>
           <span class="logo">
-            ${typeof n == "string" ? m(n) : n}
+            ${typeof n == "string" ? h(n) : n}
           </span>
         </u-link>
       `;
 		}
-		return c`
-      <u-link class="logo-link" .href=${e.href} aria-label=${e.alt ? l : t}>
+		return l`
+      <u-link class="logo-link" .href=${e.href} aria-label=${e.alt ? u : t}>
         <img class="logo"
           src="${e.src}"
           alt="${e.alt ?? ""}"
@@ -258,9 +290,9 @@ var S = class extends i {
     `;
 	}
 };
-r([d({
+r([f({
 	type: String,
 	reflect: !0
-}), n("design:type", Object)], S.prototype, "state", void 0), r([d({ type: Object }), n("design:type", Object)], S.prototype, "config", void 0), r([d({ type: String }), n("design:type", Object)], S.prototype, "locale", void 0), r([f("u-progress-bar"), n("design:type", v === void 0 ? Object : v)], S.prototype, "progressBarEl", void 0), r([p(), n("design:type", Object)], S.prototype, "context", void 0), S = r([u("u-sidebar-layout")], S);
+}), 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);
 //#endregion
-export { S as SidebarLayout };
+export { T as SidebarLayout };

package/dist/layouts/SidebarLayout.styles.js

@@ -183,15 +183,29 @@ var t = e`
    *   (CSS 2.1 §10.6.4: 절대배치 자손의 containing block 은 가장 가까운 positioned
    *   조상의 «패딩 박스»이고, 그 경계는 조상 자신의 padding 값에 밀리지 않는다).
    *   풀블리드를 원하는 소비자는 layout.styles.main = { padding: '0' } 로 되돌린다. */
-  .main {
+  .main-region {
     position: relative;
     flex: 1;
+    /* :host([state="mobile"]) 은 flex-direction: column 이라 이 축(높이)이 주축이 된다 —
+       min-height: 0 없이는 flex item 의 자동 최소 크기가 콘텐츠 기준(.main 의 min-content
+       높이)으로 잡혀, flex-shrink 가 있어도 뷰포트보다 작게 줄지 못한다. 그 결과 .main 의
+       overflow: auto 가 한 번도 발동하지 않고 셸 전체가 콘텐츠 높이만큼 부풀어 오른다. */
+    min-height: 0;
+  }
+
+  .main {
+    position: relative;
+    height: 100%;
     padding: var(--u-space-3xl, 32px);
     background: var(--u-bg-color, #FFFFFF);
     overflow: auto;
     outline: none;
   }
 
+  .main-content {
+    height: 100%;
+  }
+
   .main u-progress-bar {
     --progress-bar-height: 4px;
     --progress-bar-track-color: transparent;
@@ -211,6 +225,25 @@ var t = e`
     transform: translateY(0);
   }
 
+  .overlay {
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+    padding: var(--u-space-3xl, 32px);
+    overflow: auto;
+    background: var(--u-panel-bg-color, #FFFFFF);
+  }
+  .overlay.empty {
+    display: none;
+  }
+
+  .overlay-close {
+    position: absolute;
+    top: var(--u-space-sm, 8px);
+    right: var(--u-space-sm, 8px);
+    z-index: 2;
+  }
+
   /* Backdrop for modal mode */
   .backdrop {
     position: absolute;
@@ -242,10 +275,28 @@ var t = e`
     .main u-progress-bar {
       display: none;
     }
+    .main-region {
+      height: auto;
+    }
     .main {
+      height: auto;
       padding: 0;
       overflow: visible;
     }
+    .main-content {
+      height: auto;
+    }
+    :host(:state(overlay)) .main-content {
+      display: none;
+    }
+    :host(:state(overlay)) .overlay {
+      position: static;
+      padding: 0;
+      overflow: visible;
+    }
+    .overlay-close {
+      display: none;
+    }
   }
 `;
 //#endregion

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

@@ -12,7 +12,7 @@ export type { SidebarSectionConfig } from '../components/SidebarSection';
 export type { SidebarGroupConfig } from '../components/SidebarGroup';
 export type { SidebarButtonConfig } from '../components/SidebarButton';
 /** 사이드바 레이아웃 컴포넌트의 요소(part) 타입 */
-export type SidebarParts = 'host' | 'mobile-header' | 'sidebar' | 'sidebar-header' | 'sidebar-main' | 'sidebar-footer' | 'main' | 'progress';
+export type SidebarParts = 'host' | 'mobile-header' | 'sidebar' | 'sidebar-header' | 'sidebar-main' | 'sidebar-footer' | 'main' | 'progress' | 'overlay' | 'overlay-close';
 /** 사이드바 상태 타입 */
 export type SidebarState = 'default' | 'slim' | 'modal' | 'mobile' | 'mobile-open';
 /** 사이드바 안에 HTML 또는 엘리먼트를 직접 렌더링하는 설정 */

package/dist/react.d.ts

@@ -9,7 +9,9 @@ export type { ScreenSize, ScreenObserverConfig, ScreenResizeEvent } from './inte
  * a raw custom element handles that correctly under React 19 (property assignment) but not
  * React 18 (JSX attributes stringify), so this wrapper keeps `config` working on both.
  */
-export declare const SidebarLayout: import('@lit/react').ReactWebComponent<SidebarLayoutElement, {}>;
+export declare const SidebarLayout: import('@lit/react').ReactWebComponent<SidebarLayoutElement, {
+    onOverlayClose: EventName<CustomEvent>;
+}>;
 export type SidebarLayoutProps = React.ComponentProps<typeof SidebarLayout>;
 /**
  * React wrapper for `<u-wizard>`. `Wizard` dispatches a `step-change` custom event, but a raw

package/dist/react.js

@@ -8,7 +8,7 @@ var a = i({
 	react: r,
 	tagName: "u-sidebar-layout",
 	elementClass: n,
-	events: {}
+	events: { onOverlayClose: "overlay-close" }
 }), o = i({
 	react: r,
 	tagName: "u-wizard",

package/dist/translate.d.ts

@@ -0,0 +1,39 @@
+import { AsyncDirective } from 'lit/async-directive.js';
+import { TOptions } from 'i18next';
+/**
+ * `app.load({ i18n })` 가 초기화하는 i18next 에 붙는 반응형 번역 디렉티브.
+ *
+ * ★**왜 이 패키지가 갖는가**: i18next 를 초기화하고(`app.load`) 노출하는(`app.i18n`) 것이 이미 이
+ *   패키지이고, 셸 설정의 `label` 은 `string | DirectiveResult` 로 **디렉티브를 받도록** 설계돼 있다.
+ *   그런데 그 디렉티브가 없어서 소비자는 서드파티를 따로 들여와야 했다 — 이미 소유한 개념의
+ *   프리미티브를 내놓지 않은 자리다.
+ *
+ * ★**구독은 Lit 의 연결 수명 주기로 관리한다** — `disconnected()` 에서 풀고 `reconnected()` 에서 다시
+ *   붙으며 그 사이의 변경을 따라잡는다. 주기적으로 끊긴 파트를 훑는 레지스트리가 필요 없다.
+ *
+ * 갱신 계기는 셋이다: 언어 변경 · 나중에 도착한 리소스(백엔드가 네임스페이스를 늦게 싣는 경우) ·
+ * 초기화 완료(셸 설정은 초기화 **전에** 만들어진다 — 그때는 빈 문자열을 그린다. 키를 그리면
+ * 번역 전 키가 화면에 잠깐 비친다).
+ *
+ * @example
+ * ```ts
+ * import { translate } from '@iyulab/modern-app';
+ * html`<h1>${translate('common::title')}</h1>`;
+ * app.load({ layout: { type: 'sidebar', main: [{ type: 'link', label: translate('nav::home'), href: '/' }] } });
+ * ```
+ */
+declare class TranslateDirective extends AsyncDirective {
+    private keys;
+    private options?;
+    private subscribed;
+    render(keys: string | string[], options?: TOptions): string;
+    protected disconnected(): void;
+    protected reconnected(): void;
+    private translate;
+    private readonly refresh;
+    private subscribe;
+    private unsubscribe;
+}
+/** 현재 언어의 번역을 그리고, 언어·리소스가 바뀌면 그 자리를 다시 그린다. */
+export declare const translate: (keys: string | string[], options?: TOptions | undefined) => import('lit-html/directive.js').DirectiveResult<typeof TranslateDirective>;
+export {};

package/dist/translate.js

@@ -0,0 +1,31 @@
+import e from "i18next";
+import { AsyncDirective as t, directive as n } from "lit/async-directive.js";
+var r = n(class extends t {
+	constructor(...e) {
+		super(...e), this.keys = "", this.subscribed = !1, this.refresh = () => {
+			this.setValue(this.translate());
+		};
+	}
+	render(e, t) {
+		return this.keys = e, this.options = t, this.isConnected && this.subscribe(), this.translate();
+	}
+	disconnected() {
+		this.unsubscribe();
+	}
+	reconnected() {
+		this.subscribe(), this.refresh();
+	}
+	translate() {
+		if (!e.isInitialized) return "";
+		let t = e.t(this.keys, this.options);
+		return typeof t == "string" ? t : "";
+	}
+	subscribe() {
+		this.subscribed || (this.subscribed = !0, e.on("languageChanged", this.refresh), e.on("initialized", this.refresh), e.store?.on("added", this.refresh));
+	}
+	unsubscribe() {
+		this.subscribed && (this.subscribed = !1, e.off("languageChanged", this.refresh), e.off("initialized", this.refresh), e.store?.off("added", this.refresh));
+	}
+});
+//#endregion
+export { r as translate };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.20.1",
+  "version": "0.22.0",
   "keywords": [
     "iyulab",
     "web-framework",

package/skills/modern-app/SKILL.md

@@ -131,11 +131,14 @@ await app.load({
 app.i18n.t('namespace::key');
 ```
 
-Use in Lit templates with `lit-i18n`:
+Use in Lit templates — and as a sidebar item `label` — with the `translate()` directive. It
+re-renders when the language changes or resources arrive, and renders an empty string until i18next
+is initialized:
 
 ```typescript
-import { translate } from 'lit-i18n';
+import { translate } from '@iyulab/modern-app';
 html`<p>${translate('namespace::greeting')}</p>`;
+// layout: { main: [{ type: 'link', label: translate('nav::home'), href: '/' }] }
 ```
 
 ---

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

@@ -258,6 +258,8 @@ Parts available for `styles` overrides on the root layout:
 | `sidebar-footer` | Pinned footer area |
 | `main` | Main content area |
 | `progress` | Top progress bar |
+| `overlay` | Route-independent overlay panel above `main` |
+| `overlay-close` | Overlay's close button |
 
 ---
 
@@ -298,6 +300,44 @@ To keep a piece of chrome on paper, restore it through its part:
 ⚠ Heights or `overflow` set through `layout.styles` are inline styles and still apply when
 printing — scope such values to the screen in your own CSS instead.
 
+## Overlay content
+
+`<u-sidebar-layout>` has a second slot, `slot="overlay"`, that floats above `main` — independent
+of routing. Fill it to show a panel (e.g. a record's detail) over whatever screen is currently
+active, without wrapping every route or losing that screen's scroll position; empty it to remove
+the panel. The route content underneath becomes `inert` while the overlay has content, and a
+built-in close button fires `overlay-close` (not cancelable) when clicked:
+
+```html
+<u-sidebar-layout id="shell">
+  <!-- route content goes in the default slot, e.g. via app.load()'s <u-outlet> -->
+</u-sidebar-layout>
+
+<script>
+  function openOrderDetail(order) {
+    const panel = document.createElement('div');
+    panel.slot = 'overlay';
+    panel.textContent = `Order #${order.id}`;
+    shell.appendChild(panel);
+  }
+
+  shell.addEventListener('overlay-close', () => {
+    shell.querySelector('[slot="overlay"]')?.remove();
+  });
+</script>
+```
+
+⚠ `hidden`/`display: none` on the slotted panel does not close the overlay — the slot must
+actually be emptied (removed or reassigned) for `slotHasContent` to see it as closed.
+
+To keep the underlying route mounted while a URL parameter drives the overlay open/closed (so a
+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`.
+
+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.
+
 ## Responsive behaviour
 
 | Screen width | Sidebar state |