@iyulab/modern-app 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [0.41.0] - 2026-10-07
+
+### Changed
+
+- **`u-group-box` derives its heading level when `level` is unset** — `h2` for a box in no other `u-group-box`
+  (the usual place, directly under `u-page-header`'s `h1`), one level deeper than the nearest enclosing box otherwise
+  (shadow roots included, capped at `h6`). The default was `h3`, so the most common composition skipped a heading
+  level on every screen (axe `heading-order`). An explicit `level` still wins; an out-of-range one now falls back to
+  the derived level instead of `3`. A box under a heading of your own should set `level`.
+
+### Fixed
+
+- **The sidebar layout's route-loading bar is out of the accessibility tree while idle, and named while it loads**
+  (new locale key `pageLoading` — en *Loading page*, ko *페이지 불러오는 중*). It was hidden with `opacity` only, so
+  every screen carried an unnamed progress bar for screen readers to meet (axe `aria-progressbar-name`).
+
+## [0.40.0] - 2026-10-07
+
+### Changed
+
+- **With `i18n` configured, i18next's language drives the whole app** — at load and on every `changeLanguage()` it is
+  handed to `@iyulab/components`' `Locale` (shell, primitives and component chrome follow, re-rendering on screen) and
+  to `<html lang>` (WCAG 3.1.1). Before, `changeLanguage('ko')` changed the app's own text while button names, empty
+  states and validation messages stayed in the old language, and a first load could show two languages when i18next's
+  `lng` differed from `<html lang>` or the browser's. Without `i18n` nothing changes — `Locale.set()` chooses.
+- **Requires `@iyulab/components` 2.8.0** (peer `>=2.8.0`) — the version whose components re-render on a locale switch.
+
 ## [0.39.0] - 2026-10-06
 
 ### Fixed

package/README.md

@@ -148,7 +148,9 @@ html`<p>${translate('common::greeting')}</p>`;
 The package's own strings — the page header's back link, empty-state copy, the shell's toggle and
 close labels, the wizard's buttons and step announcement — live in the `modern-app` namespace of
 `@iyulab/components`' `Locale`. English and Korean are built in, English being the default; pick the
-language once, with `Locale.set()` — the primitives and `@iyulab/flex-table` follow the same call.
+language once, with `Locale.set()` — the primitives and `@iyulab/flex-table` follow the same call. With
+`i18n` configured you do not call it: i18next's language (at load and on every `changeLanguage()`) is
+handed to `Locale` and to `<html lang>`.
 Register other languages, or your own wording, in the same namespace:
 
 ```typescript

package/dist/App.d.ts

@@ -14,6 +14,8 @@ declare class App {
     private _screen?;
     private _user?;
     private _gateTeardown?;
+    /** i18next 언어 → components `Locale` 동기화 해제(`unload`). */
+    private _languageSync?;
     private constructor();
     /** 싱글톤 인스턴스 반환 */
     static get instance(): App;
@@ -32,6 +34,13 @@ declare class App {
     /** 앱 로드 및 초기화 */
     load(config: AppConfig): Promise<void>;
     /** 앱 언로드 */
+    /**
+     * i18next 를 설정한 앱에서는 **i18next 가 언어의 정본**이다 — 그 언어를 셸·컴포넌트 chrome(`@iyulab/components` 의
+     * `Locale`, 이 패키지의 `modernAppLocale` 이 그것을 따른다)과 문서 `<html lang>`(WCAG 3.1.1, 낭독기 발음)에 잇는다.
+     * 종전에는 둘이 따로였다: `i18next.changeLanguage('ko')` 가 앱 문장만 바꾸고 버튼 이름·빈 상태·검증 메시지는 옛 언어로,
+     * 첫 로드에서도 i18next `lng` 와 `<html lang>`/브라우저 언어가 다르면 한 화면에 두 언어가 섰다.
+     */
+    private syncLanguage;
     unload(): void;
     /** 페이지 이동 */
     navigate(path: string): void;

package/dist/App.js

@@ -4,23 +4,24 @@ import { Router as n } from "@iyulab/router";
 import { setDefaultBaseUrl as r } from "@iyulab/components/dist/utilities/icons.js";
 import { Theme as i } from "@iyulab/components/dist/utilities/Theme.js";
 import { Toast as a } from "@iyulab/components/dist/utilities/Toast.js";
+import { Locale as o } from "@iyulab/components/dist/utilities/Locale.js";
 //#region src/App.ts
-var o = "\n:where(body) { margin: 0; }\n@media screen {\n  :where(body) { width: 100vw; height: 100vh; }\n}\n", s;
-function c() {
-	if (!s) {
+var s = "\n:where(body) { margin: 0; }\n@media screen {\n  :where(body) { width: 100vw; height: 100vh; }\n}\n", c;
+function l() {
+	if (!c) {
 		if ("adoptedStyleSheets" in document && typeof CSSStyleSheet < "u" && typeof CSSStyleSheet.prototype.replaceSync == "function") {
 			let e = new CSSStyleSheet();
-			e.replaceSync(o), document.adoptedStyleSheets = [...document.adoptedStyleSheets, e], s = e;
+			e.replaceSync(s), document.adoptedStyleSheets = [...document.adoptedStyleSheets, e], c = e;
 		} else {
 			let e = document.createElement("style");
-			e.textContent = o, document.head.prepend(e), s = e;
+			e.textContent = s, document.head.prepend(e), c = e;
 		}
 	}
 }
-var l = class o {
+var u = class s {
 	constructor() {}
 	static get instance() {
-		return o._instance ||= new o(), o._instance;
+		return s._instance ||= new s(), s._instance;
 	}
 	get config() {
 		return this._config;
@@ -43,7 +44,7 @@ var l = class o {
 	async load(a) {
 		if (this.unload(), this._config = a, await i.init(a.theme), a.iconBasepath && r(a.iconBasepath), a.i18n) {
 			for (let e of a.i18n.plugins || []) t.use(e);
-			await t.init(a.i18n);
+			await t.init(a.i18n), this.syncLanguage();
 		}
 		if (a.auth) {
 			let e = a.root || document.body, t = () => {
@@ -88,8 +89,16 @@ var l = class o {
 			useIntercept: a.useIntercept
 		});
 	}
+	syncLanguage() {
+		let e = (e) => {
+			e && e !== "cimode" && (o.set(e), typeof document < "u" && (document.documentElement.lang = e));
+		};
+		e(t.resolvedLanguage ?? t.language);
+		let n = (n) => e(t.resolvedLanguage ?? n);
+		t.on("languageChanged", n), this._languageSync = () => t.off("languageChanged", n);
+	}
 	unload() {
-		this._gateTeardown &&= (this._gateTeardown(), void 0), this._user = void 0, this._screen &&= (this._screen.destroy(), void 0), this._layout &&= (this._layout.remove(), void 0), this._router &&= (this._router.destroy(), void 0), this._config &&= void 0;
+		this._languageSync?.(), this._languageSync = void 0, this._gateTeardown &&= (this._gateTeardown(), void 0), this._user = void 0, this._screen &&= (this._screen.destroy(), void 0), this._layout &&= (this._layout.remove(), void 0), this._router &&= (this._router.destroy(), void 0), this._config &&= void 0;
 	}
 	navigate(e) {
 		this._router?.go(e);
@@ -116,7 +125,7 @@ var l = class o {
 		await a.error(e, { ...t });
 	}
 	async createLayout(e, t) {
-		e === document.body && c();
+		e === document.body && l();
 		let n;
 		if (t.type === "sidebar") {
 			let { SidebarLayout: e } = await import("./layouts/SidebarLayout.js"), r = new e();
@@ -126,4 +135,4 @@ var l = class o {
 	}
 }.instance;
 //#endregion
-export { l as app };
+export { u as app };

package/dist/components/GroupBox.d.ts

@@ -43,14 +43,18 @@ export declare class GroupBox extends StyledElement<ElementParts> {
     /** 본문 여백을 없앤다 — 표를 카드 가장자리까지 붙일 때. */
     flush: boolean;
     /**
-     * Heading level of the title in the document outline (`2`–`6`, default `3`).
+     * Heading level of the title in the document outline (`2`–`6`).
      *
-     * The box cannot know how deep it sits in the page, so whoever composes the page says so — a
-     * box placed directly under `u-page-header` (the page's `h1`) is usually `2`, and leaving it at
-     * `3` skips a level and puts it deeper than its sibling sections. This changes semantics only:
-     * the title keeps its visual size at every level. Out-of-range values fall back to `3`.
+     * Unset, it follows the boxes around it: `2` for a box that sits in no other `u-group-box` — the
+     * usual place, directly under `u-page-header` (the page's `h1`) — and one deeper than the nearest
+     * enclosing box otherwise (shadow roots included), capped at `6`. Set it when the box sits under a
+     * heading of your own (a box under your `h2` section is `3`). This changes semantics only: the title
+     * keeps its visual size at every level. Out-of-range values fall back to the derived level.
      */
-    level: GroupBoxLevel;
+    level?: GroupBoxLevel;
+    /** The level the title renders at — `level`, or the one derived from enclosing boxes. */
+    get headingLevel(): GroupBoxLevel;
+    connectedCallback(): void;
     /**
      * 액션 슬롯 배정 상태.
      * ★종전에는 'render()' 안에서 'this.querySelector()' 로 라이트 DOM 을 읽었다. 그것은

package/dist/components/GroupBox.js

@@ -7,25 +7,36 @@ import { html as a, nothing as o } from "lit";
 import { customElement as s, property as c, state as l } from "lit/decorators.js";
 import { html as u, literal as d } from "lit/static-html.js";
 //#region src/components/GroupBox.ts
-var f = {
+var f, p = {
 	2: d`h2`,
 	3: d`h3`,
 	4: d`h4`,
 	5: d`h5`,
 	6: d`h6`
-}, p = class extends n {
+}, m = class extends n {
+	static {
+		f = this;
+	}
 	constructor(...e) {
-		super(...e), this.title = "", this.divider = !1, this.flush = !1, this.level = 3, this.hasActions = !1;
+		super(...e), this.title = "", this.divider = !1, this.flush = !1, this.hasActions = !1;
 	}
 	static {
 		this.styles = [super.styles, i];
 	}
+	get headingLevel() {
+		if (this.level && p[this.level]) return this.level;
+		for (let e = this.parentNode; e; e = e instanceof ShadowRoot ? e.host : e.parentNode) if (e instanceof f) return Math.min(6, e.headingLevel + 1);
+		return 2;
+	}
+	connectedCallback() {
+		super.connectedCallback(), this.requestUpdate();
+	}
 	render() {
 		let e = !!this.title || !!this.description || this.hasActions;
 		return a`
       <div class="header ${this.divider ? "divider" : ""} ${e ? "" : "empty"}" part="header">
         <div class="titles">
-          ${u`<${f[this.level] ?? f[3]} class="title" part="title">${this.title}${this.title && this.meta ? a` <span class="meta" part="meta">${this.meta}</span>` : ""}</${f[this.level] ?? f[3]}>`}
+          ${u`<${p[this.headingLevel]} class="title" part="title">${this.title}${this.title && this.meta ? a` <span class="meta" part="meta">${this.meta}</span>` : ""}</${p[this.headingLevel]}>`}
           ${this.description ? a`<p class="description" part="description">${this.description}</p>` : o}
         </div>
         <div class="actions ${this.hasActions ? "" : "empty"}" part="actions">
@@ -38,9 +49,9 @@ var f = {
     `;
 	}
 };
-t([c({ type: String }), e("design:type", Object)], p.prototype, "title", void 0), t([c({ type: String }), e("design:type", String)], p.prototype, "meta", void 0), t([c({ type: String }), e("design:type", String)], p.prototype, "description", void 0), t([c({ type: Boolean }), e("design:type", Object)], p.prototype, "divider", void 0), t([c({ type: Boolean }), e("design:type", Object)], p.prototype, "flush", void 0), t([c({
+t([c({ type: String }), e("design:type", Object)], m.prototype, "title", void 0), t([c({ type: String }), e("design:type", String)], m.prototype, "meta", void 0), t([c({ type: String }), e("design:type", String)], m.prototype, "description", void 0), t([c({ type: Boolean }), e("design:type", Object)], m.prototype, "divider", void 0), t([c({ type: Boolean }), e("design:type", Object)], m.prototype, "flush", void 0), t([c({
 	type: Number,
 	reflect: !0
-}), e("design:type", Object)], p.prototype, "level", void 0), t([l(), e("design:type", Object)], p.prototype, "hasActions", void 0), p = t([s("u-group-box")], p);
+}), e("design:type", Object)], m.prototype, "level", void 0), t([l(), e("design:type", Object)], m.prototype, "hasActions", void 0), m = f = t([s("u-group-box")], m);
 //#endregion
-export { p as GroupBox };
+export { m as GroupBox };

package/dist/internals/locale.d.ts

@@ -17,6 +17,9 @@ export interface ModernAppLocaleStrings {
     skipToContent: string;
     /** Sidebar links with `target: '_blank'` — appended to the link's accessible name (visually hidden). */
     opensInNewTab: string;
+    /** Sidebar layout — accessible name of the route-loading bar at the top of the content (it is hidden from
+     *  assistive technology while idle). */
+    pageLoading: string;
     /** Wizard — default Back/Next action labels ("Submit" wording is the consumer's call). */
     wizardBack: string;
     wizardNext: string;

package/dist/internals/locale.js

@@ -11,6 +11,7 @@ var t = {
 	toggleSidebar: "Toggle sidebar",
 	skipToContent: "Skip to main content",
 	opensInNewTab: "(opens in a new tab)",
+	pageLoading: "Loading page",
 	wizardBack: "Back",
 	wizardNext: "Next",
 	wizardStepAnnouncement: "Step {index} of {total}: {label}"
@@ -26,6 +27,7 @@ n.register("en", t), n.register("ko", {
 	toggleSidebar: "사이드바 열고 닫기",
 	skipToContent: "본문으로 건너뛰기",
 	opensInNewTab: "(새 창에서 열림)",
+	pageLoading: "페이지 불러오는 중",
 	wizardBack: "이전",
 	wizardNext: "다음",
 	wizardStepAnnouncement: "{total}단계 중 {index}단계: {label}"
@@ -59,6 +61,7 @@ function l(e) {
 		toggleSidebar: t("toggleSidebar"),
 		skipToContent: t("skipToContent"),
 		opensInNewTab: t("opensInNewTab"),
+		pageLoading: t("pageLoading"),
 		wizardBack: t("wizardBack"),
 		wizardNext: t("wizardNext"),
 		wizardStepAnnouncement: (t, n, r) => {

package/dist/layouts/SidebarLayout.d.ts

@@ -25,6 +25,11 @@ export declare class SidebarLayout extends StyledElement<SidebarParts> {
     private static menuSeq;
     /** notice 슬롯 배정 상태 — 비었으면 스택 자체가 자리를 차지하지 않는다. */
     private hasNotice;
+    /**
+     * 라우트가 불러오는 중인가 — 본문 위 진행 막대를 보이고, 쉬는 동안은 보조기기에서도 뺀다. 종전에는 `opacity: 0` 으로만
+     * 숨어 이름 없는 진행 막대가 모든 화면의 접근성 트리에 떠 있었다(axe `aria-progressbar-name`).
+     */
+    private routeLoading;
     /**
      * 오버레이를 연 컨트롤 — 닫힐 때 포커스를 되돌릴 곳.
      * ★슬롯 배정 «시점» 에 잡는다. 렌더가 본문에 `inert` 를 걸면 그 컨트롤이 쥐던 포커스는

package/dist/layouts/SidebarLayout.js

@@ -79,18 +79,18 @@ var N = class extends i {
 		C = this;
 	}
 	constructor(...t) {
-		super(...t), this.state = "default", this.counts = {}, this.locale = "", this.hasOverlay = !1, this.openMenu = null, this.menuIds = /* @__PURE__ */ new WeakMap(), this.hasNotice = !1, this.overlayTrigger = null, this.internals = typeof this.attachInternals == "function" ? this.attachInternals() : void 0, this.currentPath = null, this.unsizedWarnKey = `unsized:${++T}`, this.isMatchedLink = (e) => this.currentPath === null || !e ? !1 : (e = typeof e == "string" ? new URLPattern(e, window.location.origin) : e, e.test(this.currentPath, window.location.origin)), this.handleToggleButtonClick = () => {
+		super(...t), this.state = "default", this.counts = {}, this.locale = "", this.hasOverlay = !1, this.openMenu = null, this.menuIds = /* @__PURE__ */ new WeakMap(), this.hasNotice = !1, this.routeLoading = !1, this.overlayTrigger = null, this.internals = typeof this.attachInternals == "function" ? this.attachInternals() : void 0, this.currentPath = null, this.unsizedWarnKey = `unsized:${++T}`, this.isMatchedLink = (e) => this.currentPath === null || !e ? !1 : (e = typeof e == "string" ? new URLPattern(e, window.location.origin) : e, e.test(this.currentPath, window.location.origin)), this.handleToggleButtonClick = () => {
 			let t = this.screenSize ?? 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 = () => {
 			this.state = "slim";
 		}, this.handleRouteBegin = (e) => {
-			this.progressBarEl.setAttribute("visible", ""), this.progressBarEl.value = 0, this.state === "modal" && (this.state = "slim"), this.state === "mobile-open" && (this.state = "mobile"), this.currentPath = e.context.path;
+			this.routeLoading = !0, this.progressBarEl.value = 0, this.state === "modal" && (this.state = "slim"), this.state === "mobile-open" && (this.state = "mobile"), this.currentPath = e.context.path;
 		}, this.handleRouteProgress = (e) => {
 			this.progressBarEl.value = e.progress;
 		}, this.handleRouteDone = (e) => {
 			this.progressBarEl.value = 100, setTimeout(() => {
-				this.progressBarEl.removeAttribute("visible");
+				this.routeLoading = !1;
 			}, 300);
 			let t = this.shadowRoot?.querySelector(".main");
 			t && (this.config?.scrollBehavior?.(e.context, t), this.focusRoute(t));
@@ -100,7 +100,7 @@ var N = class extends i {
 			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";
+				this.routeLoading = !1, this.progressBarEl.status = "default";
 			}, 300);
 		}, this.handleOverlaySlotChange = (e) => {
 			let t = o(e.target);
@@ -238,7 +238,9 @@ var N = class extends i {
       <!-- Main Content -->
       <div class="main-region">
         <main class="main" part="main" scrollable tabindex="-1" @keydown=${this._handleMainKeydown}>
-          <u-progress-bar part="progress"></u-progress-bar>
+          <u-progress-bar part="progress" class=${this.routeLoading ? "loading" : ""}
+            aria-hidden=${this.routeLoading ? d : "true"}
+            aria-label=${a(this.locale || void 0).pageLoading}></u-progress-bar>
 
           <div class="main-content" part="main-content" ?inert=${this.hasOverlay}>
             <div class="notices ${this.hasNotice ? "" : "empty"}" part="notices"
@@ -442,6 +444,6 @@ var N = class extends i {
 r([p({
 	type: String,
 	reflect: !0
-}), n("design:type", Object)], N.prototype, "state", void 0), r([p({ type: Object }), n("design:type", Object)], N.prototype, "config", void 0), r([p({ type: Object }), n("design:type", typeof Record > "u" ? Object : Record)], N.prototype, "counts", void 0), r([p({ type: String }), n("design:type", Object)], N.prototype, "locale", void 0), r([m("u-progress-bar"), n("design:type", S === void 0 ? Object : S)], N.prototype, "progressBarEl", void 0), r([h(), n("design:type", Object)], N.prototype, "hasOverlay", void 0), r([h(), n("design:type", Object)], N.prototype, "openMenu", void 0), r([h(), n("design:type", Object)], N.prototype, "hasNotice", void 0), r([h(), n("design:type", Object)], N.prototype, "currentPath", void 0), N = C = r([f("u-sidebar-layout")], N);
+}), n("design:type", Object)], N.prototype, "state", void 0), r([p({ type: Object }), n("design:type", Object)], N.prototype, "config", void 0), r([p({ type: Object }), n("design:type", typeof Record > "u" ? Object : Record)], N.prototype, "counts", void 0), r([p({ type: String }), n("design:type", Object)], N.prototype, "locale", void 0), r([m("u-progress-bar"), n("design:type", S === void 0 ? Object : S)], N.prototype, "progressBarEl", void 0), r([h(), n("design:type", Object)], N.prototype, "hasOverlay", void 0), r([h(), n("design:type", Object)], N.prototype, "openMenu", void 0), r([h(), n("design:type", Object)], N.prototype, "hasNotice", void 0), r([h(), n("design:type", Object)], N.prototype, "routeLoading", void 0), r([h(), n("design:type", Object)], N.prototype, "currentPath", void 0), N = C = r([f("u-sidebar-layout")], N);
 //#endregion
 export { N as SidebarLayout };

package/dist/layouts/SidebarLayout.styles.js

@@ -359,7 +359,7 @@ var t = e`
     transition: opacity var(--u-duration-slow, 320ms) ease, transform var(--u-duration-slow, 320ms) ease;
     pointer-events: none;
   }
-  .main u-progress-bar[visible] {
+  .main u-progress-bar.loading {
     opacity: 1;
     transform: translateY(0);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.39.0",
+  "version": "0.41.0",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -65,7 +65,7 @@
     "lit": "^3.3.3"
   },
   "peerDependencies": {
-    "@iyulab/components": ">=2.0.0",
+    "@iyulab/components": ">=2.8.0",
     "@lit/react": "^1.0.8",
     "react": "^18.0.0 || ^19.0.0"
   },
@@ -78,7 +78,7 @@
     }
   },
   "devDependencies": {
-    "@iyulab/components": ">=2.0.0",
+    "@iyulab/components": ">=2.8.0",
     "@lit/react": "^1.0.8",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.14",

package/skills/modern-app/references/components/group-box.md

@@ -34,7 +34,7 @@ a left edge without any consumer CSS.
 | `description` | `string` | — | | One line under the title — what the box holds or what its numbers are based on. Caption size, weak color. Opens the header on its own |
 | `divider` | `boolean` | `false` | | Rule between header and body. Off by default — many rules make a screen noisy |
 | `flush` | `boolean` | `false` | | Remove body padding, for tables and lists that draw their own edges |
-| `level` | `2|3|4|5|6` | `3` | ✓ | Heading level of the title in the document outline. Set `2` for a box directly under `u-page-header` (the page's `h1`), so the outline does not skip a level. Semantics only — the title looks the same at every level |
+| `level` | `2|3|4|5|6` | derived | ✓ | Heading level of the title in the document outline. Unset: `2` for a box in no other `u-group-box` (directly under `u-page-header`, the page's `h1`), one deeper than the nearest enclosing box otherwise. Set it when the box sits under a heading of your own. Semantics only — the title looks the same at every level |
 
 ## CSS Parts