@iyulab/modern-app 0.32.0 → 0.33.1

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [0.33.1] - 2026-09-30
+
+### Fixed
+
+- **Sidebar links with `target: '_blank'` now say so to screen readers** — their accessible name ends
+  with a visually hidden "(opens in a new tab)", in the collapsed sidebar too. The text is the new
+  `opensInNewTab` string of the `modern-app` locale namespace (English and Korean built in).
+
+### Changed
+
+- Optional React peers promise only the tested majors: `@lit/react ^1.0.8` and
+  `react ^18.0.0 || ^19.0.0` (were `>=` ranges with no upper bound).
+
+### Documentation
+
+- README: the Accessibility section links the KWCAG 2.2 table in `@iyulab/components`.
+
+## [0.33.0] - 2026-09-30
+
+### Added
+
+- **«Skip to main content» link in the sidebar layout** — the shell's first Tab stop, shown only while
+  it has focus (`part="skip-link"`). Activating it moves focus the way a finished route does: to the
+  screen's `[autofocus]` element, else to the route area. A keyboard user no longer tabs through the
+  whole menu on every screen (WCAG 2.4.1 Bypass Blocks). The text is the new `skipToContent` key of
+  `modernAppLocale` (English and Korean built in).
+
+### Changed
+
+- **The route area (`part="main"`) is a `<main>` element**, so screen readers list it as the main
+  landmark. It was a `<div>`. Styling through `::part(main)` and `layout.styles` is unchanged. If your
+  route screens render their own `<main>`, change it to a `<div>` or `<section>` — a page should have
+  one main landmark.
+
 ## [0.32.0] - 2026-09-28
 
 ### Changed

package/README.md

@@ -276,11 +276,15 @@ conformance claim for the success criteria it does not list.
 |---|---|---|
 | SC 2.5.8 Target Size (Minimum) | Every pointer target this package renders itself — sidebar links, buttons and group headers (expanded and compact), the sidebar logo and toggle, wizard steps, the page header's back link — is at least 24×24 CSS px or meets the spacing exception (24px between centers), and is actually hit at that position | `tests/browser/target-size.browser.test.ts` (real Chromium) |
 | SC 2.1.1 Keyboard (pointer-cursor check) | Nothing this package renders shows a pointer cursor without being an interactive element — the sidebar logo is a link | `tests/browser/target-size.browser.test.ts` |
+| SC 2.4.1 Bypass Blocks | The sidebar layout's first Tab stop is a «Skip to main content» link, visible when focused and at least 24px tall; it moves focus to the screen's `[autofocus]` element or to the route area, which is the page's single `<main>` landmark | `tests/browser/sidebar-layout-skip-link.browser.test.ts` |
+| SC 3.2.5 Change on Request (new tabs) | A sidebar link with `target: '_blank'` ends its accessible name with a localized, visually hidden "(opens in a new tab)" — expanded and collapsed | `tests/browser/sidebar-link-new-tab-name.browser.test.ts` |
 
 Buttons placed through slots or rendered as `u-button` without size overrides (wizard back/next, the
 master-detail close button) follow `@iyulab/components`, which measures them in its own gate. Color
 contrast likewise comes from that package's tokens.
 
+For **KWCAG 2.2** (the Korean web accessibility standard), the `@iyulab/components` README has a table of all 33 check items — which are guaranteed by a test across the sibling packages, which are shared with the app, and which do not apply: [KWCAG 2.2 대응표](https://github.com/iyulab/node-components#kwcag-22-대응표).
+
 ## Documentation
 
 | Guide | Description |

package/dist/components/SidebarLink.js

@@ -1,45 +1,47 @@
 import e from "../_virtual/_@oxc-project_runtime@0.151.0/helpers/esm/decorateMetadata.js";
 import t from "../_virtual/_@oxc-project_runtime@0.151.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 "./SidebarLink.styles.js";
+import { getLocaleStrings as r } from "../internals/locale.js";
+import { DEFAULT_NAV_ICON as i } from "../internals/nav-icon.js";
+import { styles as a } from "./SidebarLink.styles.js";
 import "@iyulab/router";
-import { html as a, nothing as o } from "lit";
-import { customElement as s, property as c } from "lit/decorators.js";
+import { html as o, nothing as s } from "lit";
+import { customElement as c, property as l } from "lit/decorators.js";
 import "@iyulab/components/dist/components/icon/UIcon.js";
 //#region src/components/SidebarLink.ts
-var l = class extends n {
+var u = class extends n {
 	constructor(...e) {
 		super(...e), this.selected = !1, this.compact = !1;
 	}
 	static {
-		this.styles = [super.styles, i];
+		this.styles = [super.styles, a];
 	}
 	render() {
-		return a`
+		return o`
       <u-link
         .href=${this.href || "#"}
         .navigate=${this.navigate}
         .target=${this.target}
-        aria-current=${this.selected ? "page" : o}
+        aria-current=${this.selected ? "page" : s}
       >
         <div class="container" part="base" ?compact=${this.compact}>
           <u-icon part="icon"
             .lib=${this.lib}
             .name=${this.icon}
-            .fallback=${r}
+            .fallback=${i}
           ></u-icon>
           <span part="label" ?compact=${this.compact}>
             ${this.label}
           </span>
+          ${this.target === "_blank" ? o`<span class="new-tab-hint">${r().opensInNewTab}</span>` : s}
         </div>
       </u-link>
     `;
 	}
 };
-t([c({
+t([l({
 	type: Boolean,
 	reflect: !0
-}), e("design:type", Object)], l.prototype, "selected", void 0), t([c({ type: Boolean }), 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), t([c({ type: String }), e("design:type", String)], l.prototype, "href", void 0), t([c({ type: String }), e("design:type", Object)], l.prototype, "pattern", void 0), t([c({ type: String }), e("design:type", String)], l.prototype, "navigate", void 0), t([c({ type: String }), e("design:type", String)], l.prototype, "target", void 0), l = t([s("u-sidebar-link")], l);
+}), e("design:type", Object)], u.prototype, "selected", void 0), t([l({ type: Boolean }), e("design:type", Object)], u.prototype, "compact", 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), t([l({ type: String }), e("design:type", String)], u.prototype, "href", void 0), t([l({ type: String }), e("design:type", Object)], u.prototype, "pattern", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "navigate", void 0), t([l({ type: String }), e("design:type", String)], u.prototype, "target", void 0), u = t([c("u-sidebar-link")], u);
 //#endregion
-export { l as SidebarLink };
+export { u as SidebarLink };

package/dist/components/SidebarLink.styles.js

@@ -74,6 +74,8 @@ var t = e`
    * 접힌 상태의 라벨 - 시각적으로만 숨긴다. 접근성 트리에는 남아 항목의 이름이 된다
    * (hidden 은 트리에서도 빼서 이름 없는 항목을 만들었다). 절대배치라 flex 배치와 gap 에 끼지 않는다.
    */
+  /* 새 창 알림 — 화면에는 없고 링크의 접근성 이름에만 붙는다(KWCAG 7.2.1). */
+  .new-tab-hint,
   [part~='label'][compact] {
     position: absolute;
     width: 1px;

package/dist/internals/locale.d.ts

@@ -13,6 +13,10 @@ export interface ModernAppLocaleStrings {
     toggleMobileMenu: string;
     /** Sidebar layout — accessible label for the sidebar-header collapse/expand toggle button. */
     toggleSidebar: string;
+    /** Sidebar layout — the «skip to main content» link, the first Tab stop of the shell. */
+    skipToContent: string;
+    /** Sidebar links with `target: '_blank'` — appended to the link's accessible name (visually hidden). */
+    opensInNewTab: string;
     /** Wizard — default Back/Next action labels ("Submit" wording is the consumer's call). */
     wizardBack: string;
     wizardNext: string;

package/dist/internals/locale.js

@@ -9,6 +9,8 @@ var t = {
 	detailClose: "Close",
 	toggleMobileMenu: "Toggle menu",
 	toggleSidebar: "Toggle sidebar",
+	skipToContent: "Skip to main content",
+	opensInNewTab: "(opens in a new tab)",
 	wizardBack: "Back",
 	wizardNext: "Next",
 	wizardStepAnnouncement: "Step {index} of {total}: {label}"
@@ -22,6 +24,8 @@ n.register("en", t), n.register("ko", {
 	detailClose: "닫기",
 	toggleMobileMenu: "메뉴 열고 닫기",
 	toggleSidebar: "사이드바 열고 닫기",
+	skipToContent: "본문으로 건너뛰기",
+	opensInNewTab: "(새 창에서 열림)",
 	wizardBack: "이전",
 	wizardNext: "다음",
 	wizardStepAnnouncement: "{total}단계 중 {index}단계: {label}"
@@ -53,6 +57,8 @@ function l(e) {
 		detailClose: t("detailClose"),
 		toggleMobileMenu: t("toggleMobileMenu"),
 		toggleSidebar: t("toggleSidebar"),
+		skipToContent: t("skipToContent"),
+		opensInNewTab: t("opensInNewTab"),
 		wizardBack: t("wizardBack"),
 		wizardNext: t("wizardNext"),
 		wizardStepAnnouncement: (t, n, r) => {

package/dist/layouts/SidebarLayout.d.ts

@@ -111,6 +111,10 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
      * 그리기 전에 올 수 있고, 그때 찾으면 `[autofocus]` 가 아직 없다.
      */
     private focusRoute;
+    /** 본문의 시작으로 포커스 — 화면이 선언한 `[autofocus]`, 없으면 본문(`main`) 자체. */
+    private focusContentStart;
+    /** «본문 바로가기» — 라우트 완료와 같은 규칙으로 본문의 시작에 포커스를 둔다(`#517`). */
+    private handleSkipLinkClick;
     /** 라우트 에러 핸들러 */
     private handleRouteError;
     private handleOverlaySlotChange;

package/dist/layouts/SidebarLayout.js

@@ -74,6 +74,10 @@ var j = class extends i {
 			}, 300);
 			let t = this.shadowRoot?.querySelector(".main");
 			t && (this.config?.scrollBehavior?.(e.context, t), this.focusRoute(t));
+		}, this.handleSkipLinkClick = (e) => {
+			e.preventDefault();
+			let t = this.shadowRoot?.querySelector(".main");
+			t && this.focusContentStart(this.hasOverlay ? [] : this.routeContent(), t);
 		}, this.handleRouteError = (e) => {
 			this.progressBarEl.status = "error", this.progressBarEl.value = 100, setTimeout(() => {
 				this.progressBarEl.removeAttribute("visible"), this.progressBarEl.status = "default";
@@ -156,6 +160,11 @@ var j = class extends i {
 	}
 	render() {
 		return this.config ? l`
+      <!-- 반복 영역 건너뛰기(WCAG 2.4.1) — 셸의 첫 Tab. 포커스될 때만 보인다. -->
+      <a class="skip-link" part="skip-link" href="#" @click=${this.handleSkipLinkClick}>
+        ${a(this.locale || void 0).skipToContent}
+      </a>
+
       <!-- Mobile Header -->
       <div class="mobile-header" part="mobile-header" ?hidden="${!this.state.startsWith("mobile")}">
         ${this.renderLogo()}
@@ -204,7 +213,7 @@ var j = class extends i {
 
       <!-- Main Content -->
       <div class="main-region">
-        <div class="main" part="main" scrollable tabindex="-1" @keydown=${this._handleMainKeydown}>
+        <main class="main" part="main" scrollable tabindex="-1" @keydown=${this._handleMainKeydown}>
           <u-progress-bar part="progress"></u-progress-bar>
 
           <div class="main-content" part="main-content" ?inert=${this.hasOverlay}>
@@ -215,7 +224,7 @@ var j = class extends i {
             </div>
             <slot></slot>
           </div>
-        </div>
+        </main>
 
         <div class="overlay ${this.hasOverlay ? "" : "empty"}" part="overlay">
           <u-button class="overlay-close" part="overlay-close" variant="ghost"
@@ -341,11 +350,13 @@ var j = class extends i {
 		let t = this.routeContent();
 		if (await Promise.all(t.map((e) => e.updateComplete)), this.hasOverlay || !e.isConnected) return;
 		let n = k();
-		if (n && t.some((e) => A(e, n))) return;
-		let r = b(t, "[autofocus]", y);
-		r?.focus();
-		let i = k();
-		r && i && A(r, i) || e.focus({ preventScroll: !0 });
+		n && t.some((e) => A(e, n)) || this.focusContentStart(t, e);
+	}
+	focusContentStart(e, t) {
+		let n = b(e, "[autofocus]", y);
+		n?.focus();
+		let r = k();
+		n && r && A(n, r) || t.focus({ preventScroll: !0 });
 	}
 	overlayPanels() {
 		return (this.shadowRoot?.querySelector("slot[name=\"overlay\"]"))?.assignedElements({ flatten: !0 }) ?? [];

package/dist/layouts/SidebarLayout.styles.js

@@ -72,6 +72,35 @@ var t = e`
     color: var(--u-txt-color-hover, #1565C0);
   }
 
+  /* 본문 바로가기 — 포커스될 때만 보인다(보이지 않을 때는 자리도 차지하지 않는다). */
+  .skip-link {
+    position: absolute;
+    top: 8px;
+    left: 8px;
+    z-index: calc(var(--u-layer-shell, 1000) + 2);
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+  .skip-link:focus {
+    width: auto;
+    height: auto;
+    min-height: 24px;
+    overflow: visible;
+    clip-path: none;
+    display: inline-flex;
+    align-items: center;
+    padding: 6px 12px;
+    border-radius: var(--u-radius-md, 4px);
+    background: var(--u-bg-color, #FFFFFF);
+    color: var(--u-txt-color, #212121);
+    box-shadow: 0 0 0 2px var(--u-primary-color, #1976D2);
+    text-decoration: none;
+    outline: none;
+  }
+
   /* Sidebar Container */
   .sidebar {
     position: relative;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.32.0",
+  "version": "0.33.1",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -65,8 +65,8 @@
   },
   "peerDependencies": {
     "@iyulab/components": ">=1.49.0",
-    "@lit/react": ">=1.0.8",
-    "react": ">=18.0.0"
+    "@lit/react": "^1.0.8",
+    "react": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
     "@lit/react": {

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

@@ -257,6 +257,7 @@ Parts available for `styles` overrides on the root layout:
 | Part | Element |
 |------|---------|
 | `host` | Outer layout shell |
+| `skip-link` | «Skip to main content» link — the shell's first Tab stop, shown only while focused |
 | `mobile-header` | Top bar shown on mobile |
 | `sidebar` | Sidebar panel |
 | `sidebar-header` | Logo + title area |
@@ -333,6 +334,15 @@ 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.
 
+### Skip link and main landmark
+
+The route area is a `<main>` landmark (`part="main"`), so a screen reader can jump to it. The shell's
+first Tab stop is a **«Skip to main content»** link (`part="skip-link"`, localized — `skipToContent` in
+`modernAppLocale`), visible only while it has focus. Activating it moves focus by the same rule as a
+finished route (steps 2 and 3 below): your screen's `[autofocus]` element, else `main` itself — so a
+keyboard user does not tab through the whole menu on every screen (WCAG 2.4.1 Bypass Blocks). Do not put
+another `<main>` in your route screens; the shell already provides it.
+
 ### Focus when a route finishes
 
 On every `route-done` the shell places focus so the keyboard works on the new screen without a