@iyulab/modern-app 0.22.0 → 0.23.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # Changelog
 
+## [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
+
+- **A wide route content no longer pushes the desktop shell past the viewport.** In 0.22.0 the
+  scroll region's wrapper lacked a horizontal minimum-size override, so a body wider than the
+  available width (a data grid whose columns sum past the viewport) grew the wrapper beyond the
+  viewport: the right-hand columns were clipped and neither the content area nor the page scrolled
+  horizontally. The wide content now scrolls inside the content area again, as it did before 0.22.0.
+  This is the horizontal counterpart of the mobile height fix shipped in 0.22.0.
+
 ## [0.22.0] - 2026-09-18
 
 ### Added

package/dist/layouts/SidebarLayout.js

@@ -179,7 +179,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>

package/dist/layouts/SidebarLayout.styles.js

@@ -186,11 +186,16 @@ var t = e`
   .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 가 한 번도 발동하지 않고 셸 전체가 콘텐츠 높이만큼 부풀어 오른다. */
+    /* flex item 의 자동 최소 크기는 콘텐츠 기준(.main 의 min-content)이다 — 이 래퍼는
+       overflow 가 visible 이라 그 하한이 그대로 살아, flex-shrink 가 있어도 셸 밖으로
+       커진다. 그러면 .main 의 overflow: auto 가 한 번도 발동하지 않는다. 주축이 어느 쪽이든
+       같은 원인이라 두 축을 함께 푼다:
+         · 높이 — :host([state="mobile"]) 은 flex-direction: column 이라 min-height 가 필요하다.
+           없으면 셸 전체가 콘텐츠 높이만큼 부풀어 오른다.
+         · 너비 — 데스크톱(row)에서는 min-width 가 필요하다. 없으면 넓은 표 하나가 셸을
+           뷰포트 밖으로 밀어 오른쪽 열이 잘리고 가로 스크롤도 생기지 않는다. */
     min-height: 0;
+    min-width: 0;
   }
 
   .main {
@@ -206,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

@@ -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' | '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 또는 엘리먼트를 직접 렌더링하는 설정 */

package/package.json

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

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

@@ -256,7 +256,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 +335,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.