@iyulab/modern-app 0.29.0 → 0.30.1

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## [0.30.1] - 2026-09-28
+
+### Fixed
+
+- **A route screen can declare its first focus.** On every route change the shell moved focus to
+  the content area unconditionally, so a screen that focused its own input on entry — a scan field,
+  a search box — had that focus taken back, and `autofocus` in the screen did nothing. Route
+  changes now follow the overlay panel's rule: focus the screen already moved into the content
+  stays; else an `[autofocus]` element in the content (through shadow roots, after the screen's
+  first render) receives it; else the content area, as before.
+
+## [0.30.0] - 2026-09-27
+
+### Added
+
+- **`noticesAriaLabel`** in the sidebar layout config. When set, the app-level notice stack
+  (`slot="notice"`) is a `role="region"` landmark with that name, so screen-reader users can jump
+  back to the notices currently shown. Without it, the only way to name the stack was to wrap the
+  notices in your own labelled section — which moved the stack's spacing and full width from each
+  notice onto the wrapper. The same shape as `mainAriaLabel`; unset keeps today's unnamed container,
+  and an empty stack is not rendered, so no empty landmark appears.
+
+### Fixed
+
+- **Escape inside the overlay now closes a drawer or dialog opened in the panel before the
+  overlay.** 0.28.0 promised that an Escape consumed inside the panel closes only that layer, but
+  that held only for layers listening before the shell: the shell listens on `window` from the
+  moment the overlay opens, so a `u-drawer` or `u-dialog` opened afterwards listened later. The
+  shell judged first, closed the overlay and marked the key consumed — and the drawer, seeing it
+  consumed, stayed open: the outer layer closed and the inner one remained. The shell now decides
+  after every layer has, and no longer marks the Escape consumed.
+
 ## [0.29.0] - 2026-09-27
 
 ### Fixed

package/dist/layouts/SidebarLayout.d.ts

@@ -98,6 +98,19 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     private handleRouteProgress;
     /** 라우트 변경 완료 핸들러 */
     private handleRouteDone;
+    /** 라우트 본문(기본 슬롯)에 배정된 요소들 */
+    private routeContent;
+    /**
+     * 라우트 완료 후 포커스 — 오버레이 패널과 같은 규칙이다.
+     * ① 화면이 이미 본문 안으로 옮겨 두었으면 건드리지 않는다
+     * ② 본문 안의 `[autofocus]`(섀도 경계 안쪽까지)
+     * ③ 그 밖에는 `.main` — 마우스 없이 키보드로 스크롤할 수 있고, 새 화면의 시작이 된다.
+     * 오버레이가 열려 있으면 아무것도 하지 않는다 — 아래 라우트는 inert 이고 사용자의 포커스는 패널에 있다.
+     *
+     * 판정은 본문 요소들의 첫 렌더를 기다린 뒤에 한다 — `route-done` 은 화면이 자기 템플릿을
+     * 그리기 전에 올 수 있고, 그때 찾으면 `[autofocus]` 가 아직 없다.
+     */
+    private focusRoute;
     /** 라우트 에러 핸들러 */
     private handleRouteError;
     private handleOverlaySlotChange;
@@ -118,9 +131,17 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
      */
     private restoreOverlayFocus;
     /**
-     * 패널 안의 Escape 는 닫기 버튼과 같은 `overlay-close` 를 낸다.
-     * window 버블 단계에서 받는다 — 패널 안의 목록·팝오버가 자기 층을 닫으며 먹은 키
-     * (`defaultPrevented`)는 그 층의 몫이다. 한 번의 Escape 는 한 층만 닫는다.
+     * 패널 안의 Escape 는 닫기 버튼과 같은 `overlay-close` 를 낸다 — 단, **안쪽 층이 모두 판정한 뒤에**.
+     *
+     * 셸의 오버레이는 가장 바깥 층이다. 그런데 window 의 같은 단계 리스너는 «등록 순서» 로 돌고,
+     * 셸은 오버레이가 열릴 때 등록하므로 패널 안에서 «나중에» 연 층(`u-drawer`·`u-dialog` — 역시
+     * window 에서 받는다)보다 먼저 돈다. 거기서 판정하면 바깥이 닫히고 안쪽이 남는다(거꾸로다).
+     * ⇒ 리스너에서는 판정하지 않고 **디스패치가 끝난 뒤**(다음 태스크) `defaultPrevented` 를 본다 —
+     *   그때는 어느 순서로 등록된 층이든 이미 자기 몫을 가져갔다. 한 번의 Escape 는 한 층만 닫는다.
+     * ⚠마이크로태스크로는 부족하다 — 네이티브 이벤트에서는 리스너 사이마다 마이크로태스크가 비워져,
+     *   뒤에 등록된 층보다 먼저 돈다.
+     * ⚠셸은 `preventDefault` 하지 않는다 — 가장 바깥 층이 키를 «먹었다» 고 표시하면 안쪽 층의 가드
+     *   (`defaultPrevented` 면 닫지 않는다)를 오염시킨다.
      * 경로에 패널이 없으면(사이드바, 패널 위에 띄운 대화상자) 받지 않는다.
      */
     private handleOverlayEscape;

package/dist/layouts/SidebarLayout.js

@@ -52,7 +52,28 @@ function D(e, t) {
 	}
 	return !1;
 }
-var O = class extends i {
+function O(e, t) {
+	let n = (e) => {
+		let r = e instanceof Element ? [e] : Array.from(e.children);
+		for (let e of r) {
+			let r = document.createTreeWalker(e, NodeFilter.SHOW_ELEMENT);
+			for (let e = r.currentNode; e; e = r.nextNode()) {
+				if (e.matches(t)) return e;
+				if (e.shadowRoot) {
+					let t = n(e.shadowRoot);
+					if (t) return t;
+				}
+			}
+		}
+		return null;
+	};
+	for (let t of e) {
+		let e = n(t);
+		if (e) return e;
+	}
+	return null;
+}
+var k = class extends i {
 	static {
 		b = this;
 	}
@@ -71,7 +92,7 @@ var O = class extends i {
 				this.progressBarEl.removeAttribute("visible");
 			}, 300);
 			let t = this.shadowRoot?.querySelector(".main");
-			t && (this.config?.scrollBehavior?.(e.context, t), this.hasOverlay || t.focus({ preventScroll: !0 }));
+			t && (this.config?.scrollBehavior?.(e.context, t), this.focusRoute(t));
 		}, this.handleRouteError = (e) => {
 			this.progressBarEl.status = "error", this.progressBarEl.value = 100, setTimeout(() => {
 				this.progressBarEl.removeAttribute("visible"), this.progressBarEl.status = "default";
@@ -86,9 +107,11 @@ var O = class extends i {
 		}, this.handleNoticeSlotChange = (e) => {
 			this.hasNotice = o(e.target);
 		}, this.handleOverlayEscape = (e) => {
-			if (e.key !== "Escape" || e.defaultPrevented || e.isComposing || !this.hasOverlay) return;
+			if (e.key !== "Escape" || e.isComposing || !this.hasOverlay) return;
 			let t = this.shadowRoot?.querySelector(".overlay");
-			t && e.composedPath().includes(t) && (e.preventDefault(), this.handleOverlayClose());
+			t && e.composedPath().includes(t) && setTimeout(() => {
+				!e.defaultPrevented && this.hasOverlay && this.handleOverlayClose();
+			}, 0);
 		}, this.handleOverlayClose = () => {
 			this.fire("overlay-close", { cancelable: !1 });
 		}, this._handleMainKeydown = (e) => {
@@ -207,7 +230,9 @@ var O = class extends i {
           <u-progress-bar part="progress"></u-progress-bar>
 
           <div class="main-content" part="main-content" ?inert=${this.hasOverlay}>
-            <div class="notices ${this.hasNotice ? "" : "empty"}" part="notices">
+            <div class="notices ${this.hasNotice ? "" : "empty"}" part="notices"
+              role=${this.config.noticesAriaLabel ? "region" : u}
+              aria-label=${this.config.noticesAriaLabel ?? u}>
               <slot name="notice" @slotchange=${this.handleNoticeSlotChange}></slot>
             </div>
             <slot></slot>
@@ -331,6 +356,19 @@ var O = class extends i {
       </u-link>
     `;
 	}
+	routeContent() {
+		return (this.shadowRoot?.querySelector(".main-content > slot:not([name])"))?.assignedElements({ flatten: !0 }) ?? [];
+	}
+	async focusRoute(e) {
+		let t = this.routeContent();
+		if (await Promise.all(t.map((e) => e.updateComplete)), this.hasOverlay || !e.isConnected) return;
+		let n = E();
+		if (n && t.some((e) => D(e, n))) return;
+		let r = O(t, "[autofocus]");
+		r?.focus();
+		let i = E();
+		r && i && D(r, i) || e.focus({ preventScroll: !0 });
+	}
 	overlayPanels() {
 		return (this.shadowRoot?.querySelector("slot[name=\"overlay\"]"))?.assignedElements({ flatten: !0 }) ?? [];
 	}
@@ -357,6 +395,6 @@ var O = class extends i {
 r([f({
 	type: String,
 	reflect: !0
-}), n("design:type", Object)], O.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], O.prototype, "config", void 0), r([f({ type: String }), n("design:type", Object)], O.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", y === void 0 ? Object : y)], O.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], O.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], O.prototype, "hasNotice", void 0), r([m(), n("design:type", Object)], O.prototype, "context", void 0), O = b = r([d("u-sidebar-layout")], O);
+}), n("design:type", Object)], k.prototype, "state", void 0), r([f({ type: Object }), n("design:type", Object)], k.prototype, "config", void 0), r([f({ type: String }), n("design:type", Object)], k.prototype, "locale", void 0), r([p("u-progress-bar"), n("design:type", y === void 0 ? Object : y)], k.prototype, "progressBarEl", void 0), r([m(), n("design:type", Object)], k.prototype, "hasOverlay", void 0), r([m(), n("design:type", Object)], k.prototype, "hasNotice", void 0), r([m(), n("design:type", Object)], k.prototype, "context", void 0), k = b = r([d("u-sidebar-layout")], k);
 //#endregion
-export { O as SidebarLayout };
+export { k as SidebarLayout };

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

@@ -78,6 +78,13 @@ export interface SidebarLayoutConfig {
      * 별개 값이다. 미지정 시 종전과 동일하게 랜드마크 이름이 없다(breaking 아님).
      */
     mainAriaLabel?: string;
+    /**
+     * 앱 수준 공지 스택(`slot="notice"`)의 접근 가능한 이름. 지정하면 스택이 `role="region"` +
+     * `aria-label` 인 랜드마크가 되어, 스크린리더 사용자가 «지금 떠 있는 공지들» 로 건너뛰어
+     * 다시 읽을 수 있다(`region` 은 이름이 있을 때만 랜드마크다). 공지가 없으면 스택 자체가 없으므로
+     * 빈 랜드마크는 생기지 않는다. 미지정 시 종전과 같이 이름 없는 컨테이너다.
+     */
+    noticesAriaLabel?: string;
     /**
      * 메뉴 항목 권한 필터 판정. 지정하면 `requirePermission`/`requireAnyPermission` 를 만족하지
      * 않는 항목을 숨기고, 항목이 모두 걸러진 section/group 은 통째로 숨긴다.

package/package.json

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

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

@@ -21,10 +21,13 @@ interface SidebarLayoutConfig {
   /** Accessible name for the main nav landmark (`<nav class="sidebar-main">`), reflected as `aria-label`. Unset by default. */
   mainAriaLabel?: string;
 
+  /** Accessible name for the app-level notice stack (`slot="notice"`). When set, the stack is a `role="region"` landmark with this `aria-label`. Unset by default. */
+  noticesAriaLabel?: string;
+
   /** Permission filter — hides items (and emptied section/groups) whose requirement fails. Unset shows everything. See "권한 기반 메뉴 필터" below. */
   hasPermission?: (code: string) => boolean;
 
-  /** 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. */
+  /** Called on `route-done` (before the shell places focus — see *Focus when a route finishes*) 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. */
@@ -330,6 +333,23 @@ told apart in CSS; notices are rare and short-lived.
 While the overlay is open, `part="main-content"` becomes a box at the area's height, because a
 stacking context needs one — route content is inert and under the overlay then.
 
+### Focus when a route finishes
+
+On every `route-done` the shell places focus so the keyboard works on the new screen without a
+click — by the same rule as the overlay panel (see *What the shell owns, and what it does not*):
+
+1. **If your screen already moved focus into the route content** (a `focus()` in `firstUpdated`,
+   say), the shell leaves it there.
+2. **Else an `[autofocus]` element in the route content** — found through shadow roots, so an input
+   inside your page component's own template counts. The shell waits for the screen's first render
+   before looking.
+3. **Else `part="main"`**, the scroll container — arrow keys and Page Down scroll the new screen,
+   and it marks where the new screen starts.
+
+So a screen that must receive input on entry — a barcode scan field, a search box — only needs
+`autofocus` on that control. While the overlay is open the shell does none of this: the route
+underneath is inert and focus stays in the panel.
+
 ## Printing
 
 On print media the shell drops its app chrome and lets the content flow across pages: the
@@ -396,7 +416,7 @@ from either re-implementing what the shell already does, or dropping what it doe
 | Keeping the route mounted underneath | shell | the overlay is independent of routing |
 | Moving focus into the panel when it opens | shell | an `[autofocus]` element in your panel, else its first input control, else `part="overlay-close"`. If you already moved focus into the panel, the shell leaves it there |
 | Restoring focus when it closes | shell | back to the control that held focus when the panel opened — only if focus fell to `<body>`; if you moved it somewhere on purpose, that stands. With no such control (opened from code), focus goes to `part="main"` |
-| Escape to close | shell | Escape inside the panel fires the same `overlay-close` as the button — you still empty the slot. An Escape already consumed inside the panel (an open list or popover calling `preventDefault()`) closes only that layer |
+| Escape to close | shell | Escape inside the panel fires the same `overlay-close` as the button — you still empty the slot. The shell decides **after** every layer inside the panel has: an Escape consumed there (`preventDefault()` — an open list, popover, drawer or dialog, whenever it was opened) closes only that layer. The shell does not mark the Escape consumed itself |
 | **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 |
 
@@ -435,6 +455,10 @@ Put them in `slot="notice"`; the shell stacks them at the top of the route conte
 - **Full width.** Each notice takes the width of the content box, whatever its text length.
 - **Empty takes no space** — the stack has no margin while nothing is slotted.
 - **Inert with the route content** while the overlay is open.
+- **A named landmark on request.** Set `noticesAriaLabel` in the layout config and the stack
+  becomes a `role="region"` with that name, so screen-reader users can jump back to the notices
+  currently shown. Put the notices in the slot directly — wrapping them in your own named section
+  puts the stack's spacing and width on the wrapper instead of on each notice.
 - Which surface a notice is (toast, banner or modal) is decided by *who ends it* — a notice the time
   ends is a toast (`app.success`), not a slotted banner.