@iyulab/modern-app 0.52.1 → 0.53.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## [0.53.0] - 2026-10-13
+
+### Added
+
+- **Unsaved changes are not dropped without asking.** A screen registers one check —
+  `UnsavedChangesController(host, () => dirty)` (Lit), `useUnsavedChanges(dirty)` (`/react`) or
+  `trackUnsavedChanges(() => dirty)` — and both ways of leaving ask it. Before a navigation (a link,
+  `app.navigate()`, the sidebar, a selection channel, Back and Forward) the shell asks «Discard unsaved changes?» in
+  an in-app dialog — **Discard** leaves, **Keep editing** stays with the screen and the address unchanged. Leaving
+  the document (reload, another site, closing the tab) gets the browser's own `beforeunload` confirmation. When
+  nothing is unsaved, nothing is asked and nothing waits. A check that throws counts as unsaved. Keep the draft on
+  `input` rather than `change` — `change` fires only when a field is left.
+- `confirmDiscardChanges(options?)` asks the same question anywhere — a modal drawer's cancellable `hide` event is
+  the place for «close without saving». `hasUnsavedChanges()` reads every registered check. `unsavedChangesGuard`
+  wires the same behaviour into a `Router` an app builds itself (`new Router({ leave: unsavedChangesGuard })`).
+- `AppConfig.leave` — a global check of your own, asked before the unsaved-changes one (`@iyulab/router`'s
+  `RouterConfig.leave`). `RouteLeaveContext` is re-exported.
+- Built-in strings `discardTitle`, `discardMessage`, `discardConfirm`, `discardCancel` (English and Korean).
+
+### Changed
+
+- **Requires `@iyulab/router` 0.24** (peer `^0.24.0`) — the version with `leave` guards.
+
+### Documentation
+
+- The installation section says how to check the 0.51 peer move: `npm ls @iyulab/router @iyulab/modern-app` should
+  list one version of each. An upgrade does not always fail when an older copy stays — in a workspace where another
+  package declares them as broad peers (`"*"`), the older copy keeps satisfying that package and stays installed with
+  no install error. Remove the older entries from the lockfile and `node_modules`, then install again.
+  `@iyulab/router` 0.23.1 names this cause when a second copy loads.
+
 ## [0.52.1] - 2026-10-12
 
 ### Fixed

package/README.md

@@ -8,6 +8,12 @@ A client-side SPA framework built on [Lit Element](https://lit.dev/) by iyulab.
 npm install @iyulab/modern-app
 ```
 
+`@iyulab/router` and `@iyulab/components` are peer dependencies — npm 7+ and pnpm install them for you, and the
+app shares the shell's copy. After installing or upgrading, `npm ls @iyulab/router @iyulab/modern-app` should list
+one version of each. In a workspace where another package declares them as broad peers (`"*"`), an upgrade can
+leave the older copy installed with no install error; remove the older entries from the lockfile and
+`node_modules`, then install again.
+
 ## When to use it
 
 | ✅ Good fit | ❌ Not a good fit |

package/dist/App.js

@@ -1,28 +1,29 @@
 import { ScreenObserver as e } from "./internals/ScreenObserver.js";
 import { defaultFallback as t } from "./defaultFallback.js";
-import n from "i18next";
-import { Router as r } from "@iyulab/router";
-import { setDefaultBaseUrl as i } from "@iyulab/components/dist/utilities/icons.js";
-import { Theme as a } from "@iyulab/components/dist/utilities/Theme.js";
-import { Toast as o } from "@iyulab/components/dist/utilities/Toast.js";
-import { Locale as s } from "@iyulab/components/dist/utilities/Locale.js";
+import { unsavedChangesGuard as n } from "./unsaved.js";
+import r from "i18next";
+import { Router as i } from "@iyulab/router";
+import { setDefaultBaseUrl as a } from "@iyulab/components/dist/utilities/icons.js";
+import { Theme as o } from "@iyulab/components/dist/utilities/Theme.js";
+import { Toast as s } from "@iyulab/components/dist/utilities/Toast.js";
+import { Locale as c } from "@iyulab/components/dist/utilities/Locale.js";
 //#region src/App.ts
-var c = "\n:where(body) { margin: 0; }\n@media screen {\n  :where(body) { width: 100vw; height: 100vh; }\n}\n", l;
-function u() {
-	if (!l) {
+var l = "\n:where(body) { margin: 0; }\n@media screen {\n  :where(body) { width: 100vw; height: 100vh; }\n}\n", u;
+function d() {
+	if (!u) {
 		if ("adoptedStyleSheets" in document && typeof CSSStyleSheet < "u" && typeof CSSStyleSheet.prototype.replaceSync == "function") {
 			let e = new CSSStyleSheet();
-			e.replaceSync(c), document.adoptedStyleSheets = [...document.adoptedStyleSheets, e], l = e;
+			e.replaceSync(l), document.adoptedStyleSheets = [...document.adoptedStyleSheets, e], u = e;
 		} else {
 			let e = document.createElement("style");
-			e.textContent = c, document.head.prepend(e), l = e;
+			e.textContent = l, document.head.prepend(e), u = e;
 		}
 	}
 }
-var d = class c {
+var f = class l {
 	constructor() {}
 	static get instance() {
-		return c._instance ||= new c(), c._instance;
+		return l._instance ||= new l(), l._instance;
 	}
 	get config() {
 		return this._config;
@@ -37,22 +38,22 @@ var d = class c {
 		return this._user;
 	}
 	get theme() {
-		return a;
+		return o;
 	}
 	get i18n() {
-		return n;
+		return r;
 	}
-	async load(o) {
-		if (this.unload(), this._config = o, await a.init(o.theme), o.iconBasepath && i(o.iconBasepath), o.i18n) {
-			for (let e of o.i18n.plugins || []) n.use(e);
-			await n.init(o.i18n), this.syncLanguage();
+	async load(s) {
+		if (this.unload(), this._config = s, await o.init(s.theme), s.iconBasepath && a(s.iconBasepath), s.i18n) {
+			for (let e of s.i18n.plugins || []) r.use(e);
+			await r.init(s.i18n), this.syncLanguage();
 		}
-		if (o.auth) {
-			let e = o.root || document.body, t = () => {
-				this.load(o);
+		if (s.auth) {
+			let e = s.root || document.body, t = () => {
+				this.load(s);
 			}, n;
 			try {
-				n = await o.auth.me();
+				n = await s.auth.me();
 			} catch (e) {
 				n = {
 					status: "unknown",
@@ -60,8 +61,8 @@ var d = class c {
 				};
 			}
 			if (n?.status === "unknown") {
-				if (!o.auth.renderUnavailable) throw n.error;
-				let r = o.auth.renderUnavailable({
+				if (!s.auth.renderUnavailable) throw n.error;
+				let r = s.auth.renderUnavailable({
 					root: e,
 					error: n.error,
 					retry: t
@@ -70,7 +71,7 @@ var d = class c {
 				return;
 			}
 			if (n?.status === "anonymous") {
-				let n = o.auth.renderLogin({
+				let n = s.auth.renderLogin({
 					root: e,
 					onSuccess: t
 				});
@@ -78,33 +79,37 @@ var d = class c {
 				return;
 			}
 			if (n?.status !== "authenticated") throw TypeError("auth.me() must return { status: 'authenticated', user } | { status: 'anonymous' } | { status: 'unknown', error }");
-			this._user = n.user, await o.auth.onAuthenticated?.(n.user);
+			this._user = n.user, await s.auth.onAuthenticated?.(n.user);
 		}
-		let s = o.root || document.body;
-		this._layout = await this.createLayout(s, o.layout), this._screen = new e({
-			element: s,
-			breakpoints: o.layout.breakpoints || [768, 1024]
+		let c = s.root || document.body;
+		this._layout = await this.createLayout(c, s.layout), this._screen = new e({
+			element: c,
+			breakpoints: s.layout.breakpoints || [768, 1024]
 		});
-		let c = document.createElement("u-outlet");
-		this._layout.appendChild(c), this._router = new r({
+		let l = document.createElement("u-outlet");
+		this._layout.appendChild(l), this._router = new i({
 			root: this._layout,
-			basepath: o.basepath,
-			mode: o.routerMode,
-			routes: o.routes,
-			fallback: o.fallback ?? t,
-			enter: o.enter,
-			initialLoad: o.initialLoad,
-			useIntercept: o.useIntercept,
-			scrollRestoration: o.scrollRestoration !== !1 && !o.layout.scrollBehavior && { container: () => this._layout?.mainElement }
+			basepath: s.basepath,
+			mode: s.routerMode,
+			routes: s.routes,
+			fallback: s.fallback ?? t,
+			enter: s.enter,
+			leave: (e) => {
+				let t = !s.leave || s.leave(e);
+				return t === !1 ? !1 : t === !0 ? n(e) : Promise.resolve(t).then((t) => t !== !1 && n(e));
+			},
+			initialLoad: s.initialLoad,
+			useIntercept: s.useIntercept,
+			scrollRestoration: s.scrollRestoration !== !1 && !s.layout.scrollBehavior && { container: () => this._layout?.mainElement }
 		});
 	}
 	syncLanguage() {
 		let e = (e) => {
-			e && e !== "cimode" && (s.set(e), typeof document < "u" && (document.documentElement.lang = e));
+			e && e !== "cimode" && (c.set(e), typeof document < "u" && (document.documentElement.lang = e));
 		};
-		e(n.resolvedLanguage ?? n.language);
-		let t = (t) => e(n.resolvedLanguage ?? t);
-		n.on("languageChanged", t), this._languageSync = () => n.off("languageChanged", t);
+		e(r.resolvedLanguage ?? r.language);
+		let t = (t) => e(r.resolvedLanguage ?? t);
+		r.on("languageChanged", t), this._languageSync = () => r.off("languageChanged", t);
 	}
 	unload() {
 		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;
@@ -119,22 +124,22 @@ var d = class c {
 		t === void 0 ? delete r[e] : r[e] = t, n.counts = r;
 	}
 	async notice(e, t) {
-		await o.notice(e, { ...t });
+		await s.notice(e, { ...t });
 	}
 	async info(e, t) {
-		await o.info(e, { ...t });
+		await s.info(e, { ...t });
 	}
 	async warning(e, t) {
-		await o.warning(e, { ...t });
+		await s.warning(e, { ...t });
 	}
 	async success(e, t) {
-		await o.success(e, { ...t });
+		await s.success(e, { ...t });
 	}
 	async error(e, t) {
-		await o.error(e, { ...t });
+		await s.error(e, { ...t });
 	}
 	async createLayout(e, t) {
-		e === document.body && u();
+		e === document.body && d();
 		let n;
 		if (t.type === "sidebar") {
 			let { SidebarLayout: e } = await import("./layouts/SidebarLayout.js"), r = new e();
@@ -144,4 +149,4 @@ var d = class c {
 	}
 }.instance;
 //#endregion
-export { d as app };
+export { f as app };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type * from './types/AppConfigs';
 export type * from './types/AppOptions';
 export type * from './types/AuthConfig';
 export type { SidebarPermissionGuard } from './layouts/SidebarPermission';
-export type { RouteConfig, RouteContext, FallbackRouteConfig } from '@iyulab/router';
+export type { RouteConfig, RouteContext, FallbackRouteConfig, RouteLeaveContext } from '@iyulab/router';
 export { RouteError, NotFoundError, AccessDeniedError, ContentLoadError, ContentRenderError, OutletMissingError, } from '@iyulab/router';
 export { defaultFallback } from './defaultFallback.js';
 export type { SidebarIconsConfig, SidebarLayoutConfig, SidebarItem, SidebarLogoConfig, SidebarLinkConfig, SidebarSectionConfig, SidebarGroupConfig, SidebarButtonConfig, SidebarMenuConfig, SidebarMenuItemConfig, SidebarHtmlConfig, SidebarState, } from './layouts/SidebarLayout.types';
@@ -22,6 +22,8 @@ export { MasterDetailLayout } from './components/MasterDetailLayout.js';
 export type { MasterDetailLayoutEventMap } from './components/MasterDetailLayout.js';
 export { Wizard } from './components/Wizard.js';
 export type { WizardStep, WizardStepState, WizardStepChangeDetail, WizardEventMap } from './components/Wizard.js';
+export { trackUnsavedChanges, hasUnsavedChanges, confirmDiscardChanges, unsavedChangesGuard, UnsavedChangesController, } from './unsaved.js';
+export type { DiscardChangesOptions } from './unsaved.js';
 export { translate } from './translate.js';
 export { modernAppLocale, getLocaleStrings, getDefaultLocale, } from './internals/locale.js';
 export type { ModernAppLocaleStrings, ModernAppMessageKey } from './internals/locale.js';

package/dist/index.js

@@ -2,20 +2,21 @@ import { ScreenObserver as e } from "./internals/ScreenObserver.js";
 import { getDefaultLocale as t, getLocaleStrings as n, modernAppLocale as r } from "./internals/locale.js";
 import { EmptyState as i } from "./components/EmptyState.js";
 import { defaultFallback as a } from "./defaultFallback.js";
-import { app as o } from "./App.js";
-import { filterSidebarItems as s } from "./layouts/filterSidebarItems.js";
-import { PageHeader as c } from "./components/PageHeader.js";
-import { GroupBox as l } from "./components/GroupBox.js";
-import { InfoSection as u } from "./components/InfoSection.js";
-import { InfoField as d, isBlank as f } from "./components/InfoField.js";
-import { TimelineItem as p } from "./components/TimelineItem.js";
-import { Timeline as m } from "./components/Timeline.js";
-import { ActionBar as h } from "./components/ActionBar.js";
-import { MasterDetailLayout as g } from "./components/MasterDetailLayout.js";
-import { Wizard as _ } from "./components/Wizard.js";
-import { translate as v } from "./translate.js";
-import { AccessDeniedError as y, ContentLoadError as b, ContentRenderError as x, NotFoundError as S, OutletMissingError as C, RouteError as w } from "@iyulab/router";
+import { UnsavedChangesController as o, confirmDiscardChanges as s, hasUnsavedChanges as c, trackUnsavedChanges as l, unsavedChangesGuard as u } from "./unsaved.js";
+import { app as d } from "./App.js";
+import { filterSidebarItems as f } from "./layouts/filterSidebarItems.js";
+import { PageHeader as p } from "./components/PageHeader.js";
+import { GroupBox as m } from "./components/GroupBox.js";
+import { InfoSection as h } from "./components/InfoSection.js";
+import { InfoField as g, isBlank as _ } from "./components/InfoField.js";
+import { TimelineItem as v } from "./components/TimelineItem.js";
+import { Timeline as y } from "./components/Timeline.js";
+import { ActionBar as b } from "./components/ActionBar.js";
+import { MasterDetailLayout as x } from "./components/MasterDetailLayout.js";
+import { Wizard as S } from "./components/Wizard.js";
+import { translate as C } from "./translate.js";
+import { AccessDeniedError as w, ContentLoadError as T, ContentRenderError as E, NotFoundError as D, OutletMissingError as O, RouteError as k } from "@iyulab/router";
 //#region src/index.ts
-var T = o;
+var A = d;
 //#endregion
-export { y as AccessDeniedError, h as ActionBar, b as ContentLoadError, x as ContentRenderError, i as EmptyState, l as GroupBox, d as InfoField, u as InfoSection, g as MasterDetailLayout, S as NotFoundError, C as OutletMissingError, c as PageHeader, w as RouteError, e as ScreenObserver, m as Timeline, p as TimelineItem, _ as Wizard, o as app, T as default, a as defaultFallback, s as filterSidebarItems, t as getDefaultLocale, n as getLocaleStrings, f as isBlank, r as modernAppLocale, v as translate };
+export { w as AccessDeniedError, b as ActionBar, T as ContentLoadError, E as ContentRenderError, i as EmptyState, m as GroupBox, g as InfoField, h as InfoSection, x as MasterDetailLayout, D as NotFoundError, O as OutletMissingError, p as PageHeader, k as RouteError, e as ScreenObserver, y as Timeline, v as TimelineItem, o as UnsavedChangesController, S as Wizard, d as app, s as confirmDiscardChanges, A as default, a as defaultFallback, f as filterSidebarItems, t as getDefaultLocale, n as getLocaleStrings, c as hasUnsavedChanges, _ as isBlank, r as modernAppLocale, l as trackUnsavedChanges, C as translate, u as unsavedChangesGuard };

package/dist/internals/locale.d.ts

@@ -32,6 +32,13 @@ export interface ModernAppLocaleStrings {
     /** 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;
+    /** Unsaved changes — the confirmation asked before a screen with unsaved changes is left (`confirmDiscardChanges`). */
+    discardTitle: string;
+    discardMessage: string;
+    /** The button that leaves and drops the changes. */
+    discardConfirm: string;
+    /** The button that stays. */
+    discardCancel: string;
     /** Wizard — default Back/Next action labels ("Submit" wording is the consumer's call). */
     wizardBack: string;
     wizardNext: string;

package/dist/internals/locale.js

@@ -19,6 +19,10 @@ var t = {
 	skipToContent: "Skip to main content",
 	opensInNewTab: "(opens in a new tab)",
 	pageLoading: "Loading page",
+	discardTitle: "Discard unsaved changes?",
+	discardMessage: "Changes on this screen have not been saved.",
+	discardConfirm: "Discard",
+	discardCancel: "Keep editing",
 	wizardBack: "Back",
 	wizardNext: "Next",
 	wizardStepAnnouncement: "Step {index} of {total}: {label}"
@@ -42,6 +46,10 @@ n.register("en", t), n.register("ko", {
 	skipToContent: "본문으로 건너뛰기",
 	opensInNewTab: ", 새 창에서 열림",
 	pageLoading: "페이지 불러오는 중",
+	discardTitle: "저장하지 않은 변경을 버릴까요?",
+	discardMessage: "이 화면에서 바꾼 내용이 저장되지 않았습니다.",
+	discardConfirm: "버리기",
+	discardCancel: "계속 편집",
 	wizardBack: "이전",
 	wizardNext: "다음",
 	wizardStepAnnouncement: "{total}단계 중 {index}단계: {label}"
@@ -71,6 +79,10 @@ function i(e) {
 		skipToContent: t("skipToContent"),
 		opensInNewTab: t("opensInNewTab"),
 		pageLoading: t("pageLoading"),
+		discardTitle: t("discardTitle"),
+		discardMessage: t("discardMessage"),
+		discardConfirm: t("discardConfirm"),
+		discardCancel: t("discardCancel"),
 		wizardBack: t("wizardBack"),
 		wizardNext: t("wizardNext"),
 		wizardStepAnnouncement: (t, n, i) => r(e, "wizardStepAnnouncement", {

package/dist/react.d.ts

@@ -8,6 +8,18 @@ import { TimelineItemColor } from './components/TimelineItem.js';
 import { InfoFieldFormat, InfoFieldSize, InfoFieldTrend, InfoFieldTone } from './components/InfoField.js';
 export { ScreenObserver } from './internals/ScreenObserver.js';
 export type { ScreenSize, ScreenObserverConfig, ScreenResizeEvent } from './internals/ScreenObserver.js';
+/**
+ * React 화면의 «저장 안 한 변경» — 마운트된 동안 판정을 등록한다(`trackUnsavedChanges`). 셸(`app.load()`)이 떠나기 전에
+ * «변경을 버릴까요?» 를 묻고, 문서 이탈(새로 고침 · 탭 닫기)에는 브라우저 확인이 걸린다. 값은 매 렌더의 것을 본다.
+ *
+ * ```tsx
+ * function OrderForm() {
+ *   const [draft, setDraft] = useState(initial);
+ *   useUnsavedChanges(draft !== initial);
+ * }
+ * ```
+ */
+export declare function useUnsavedChanges(dirty: boolean): void;
 /**
  * React wrapper for `<u-sidebar-layout>`. `config` is an `@property({ type: Object })` —
  * a raw custom element handles that correctly under React 19 (property assignment) but not

package/dist/react.js

@@ -1,19 +1,24 @@
 import { ScreenObserver as e } from "./internals/ScreenObserver.js";
-import { Wizard as t } from "./components/Wizard.js";
-import { SidebarLayout as n } from "./layouts/SidebarLayout.js";
-import r from "react";
-import { createComponent as i } from "@lit/react";
+import { trackUnsavedChanges as t } from "./unsaved.js";
+import { Wizard as n } from "./components/Wizard.js";
+import { SidebarLayout as r } from "./layouts/SidebarLayout.js";
+import i from "react";
+import { createComponent as a } from "@lit/react";
 //#region src/react.ts
-var a = i({
-	react: r,
+function o(e) {
+	let n = i.useRef(e);
+	n.current = e, i.useEffect(() => t(() => n.current), []);
+}
+var s = a({
+	react: i,
 	tagName: "u-sidebar-layout",
-	elementClass: n,
+	elementClass: r,
 	events: { onOverlayClose: "overlay-close" }
-}), o = i({
-	react: r,
+}), c = a({
+	react: i,
 	tagName: "u-wizard",
-	elementClass: t,
+	elementClass: n,
 	events: { onStepChange: "step-change" }
 });
 //#endregion
-export { e as ScreenObserver, a as SidebarLayout, o as Wizard };
+export { e as ScreenObserver, s as SidebarLayout, c as Wizard, o as useUnsavedChanges };

package/dist/types/AppConfigs.d.ts

@@ -1,5 +1,5 @@
 import { InitOptions, Module, Newable, NewableModule } from 'i18next';
-import { RouteConfig, FallbackRouteConfig, RouteContext } from '@iyulab/router';
+import { RouteConfig, FallbackRouteConfig, RouteContext, RouteLeaveContext } from '@iyulab/router';
 import { ThemeInitOptions } from '@iyulab/components/dist/utilities/Theme.js';
 import { SidebarLayoutConfig } from '../layouts/SidebarLayout.types';
 import { AuthGateConfig } from './AuthConfig';
@@ -72,6 +72,16 @@ export interface AppConfig {
      * ```
      */
     enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
+    /**
+     * 모든 라우트 전환 전에, 지금 화면을 떠나기 전에 호출되는 글로벌 leave 함수입니다(`@iyulab/router` 의 `RouterConfig.leave`).
+     * - `false` 반환: 이동 취소(화면과 주소가 그대로)
+     * - `true`/무반환: 통과
+     *
+     * 저장 안 한 변경은 이것 없이 막힌다 — 화면이 `trackUnsavedChanges(isDirty)`(Lit `UnsavedChangesController` · React
+     * `useUnsavedChanges`)로 판정을 등록하면 셸이 이 함수 다음에 «변경을 버릴까요?» 를 묻고, 문서 이탈(새로 고침 · 탭 닫기)에는
+     * 브라우저 확인을 건다. 이 함수는 그 밖의 «떠나도 되는가» 판정의 자리다.
+     */
+    leave?: (ctx: RouteLeaveContext) => Promise<boolean> | boolean;
     /**
      * 초기 로드 시 현재 URL로 라우팅을 자동으로 수행할지 여부를 설정합니다.
      * @default true

package/dist/unsaved.d.ts

@@ -0,0 +1,49 @@
+import { ReactiveController, ReactiveControllerHost } from 'lit';
+import { RouteLeaveContext } from '@iyulab/router';
+/**
+ * 화면의 «저장 안 한 변경» 판정을 등록한다 — 돌려받은 함수로 해제한다(화면이 사라질 때).
+ *
+ * 등록이 하나라도 있는 동안 문서 이탈에 `beforeunload` 확인이 걸린다(판정이 `true` 일 때만 묻는다).
+ * @example
+ * ```ts
+ * const release = trackUnsavedChanges(() => form.dirty);
+ * // 화면이 내려갈 때
+ * release();
+ * ```
+ */
+export declare function trackUnsavedChanges(isDirty: () => boolean): () => void;
+/** 등록된 판정 중 하나라도 «저장 안 한 변경이 있다» 인가. 던지는 판정은 «있다» 로 본다(잃는 쪽보다 묻는 쪽). */
+export declare function hasUnsavedChanges(): boolean;
+/** `confirmDiscardChanges` 의 문구 — 주지 않은 것은 `modernAppLocale` 의 `discard*` 문자열(영어·한국어 내장). */
+export interface DiscardChangesOptions {
+    title?: string;
+    message?: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+}
+/**
+ * «변경을 버리고 떠날까요?» 를 묻는다 — 버리면 `true`. 판정 없이 늘 묻는다(묻기 전에 판정은 호출하는 쪽이 —
+ * `hasUnsavedChanges()` 나 자기 폼의 상태). 모달 서랍을 닫기 전처럼 라우터 밖의 «떠남» 에도 같은 문장을 쓴다.
+ */
+export declare function confirmDiscardChanges(options?: DiscardChangesOptions): Promise<boolean>;
+/**
+ * 라우터 `leave` 가드 — 저장 안 한 변경이 있으면 `confirmDiscardChanges()` 로 묻는다. `app.load()` 가 이미 배선한다.
+ * `Router` 를 직접 만드는 앱: `new Router({ …, leave: unsavedChangesGuard })`.
+ */
+export declare function unsavedChangesGuard(_ctx?: RouteLeaveContext): boolean | Promise<boolean>;
+/**
+ * Lit 요소의 «저장 안 한 변경» — 연결된 동안 판정을 등록하고, 떨어지면 해제한다.
+ * @example
+ * ```ts
+ * class OrderPage extends LitElement {
+ *   private unsaved = new UnsavedChangesController(this, () => this.form.dirty);
+ * }
+ * ```
+ */
+export declare class UnsavedChangesController implements ReactiveController {
+    private readonly isDirty;
+    private release?;
+    constructor(host: ReactiveControllerHost, isDirty: () => boolean);
+    hostConnected(): void;
+    hostDisconnected(): void;
+}

package/dist/unsaved.js

@@ -0,0 +1,43 @@
+import { getLocaleStrings as e } from "./internals/locale.js";
+//#region src/unsaved.ts
+var t = /* @__PURE__ */ new Set(), n = (e) => {
+	i() && (e.preventDefault(), e.returnValue = "");
+};
+function r(e) {
+	return t.size === 0 && typeof window < "u" && window.addEventListener("beforeunload", n), t.add(e), () => {
+		t.delete(e) && t.size === 0 && typeof window < "u" && window.removeEventListener("beforeunload", n);
+	};
+}
+function i() {
+	for (let e of t) try {
+		if (e()) return !0;
+	} catch (e) {
+		return console.error("Unsaved-changes check failed — treating the screen as unsaved:", e), !0;
+	}
+	return !1;
+}
+async function a(t) {
+	let n = e(), { Dialog: r } = await import("@iyulab/components/dist/utilities/Dialog.js");
+	return r.confirm(t?.message ?? n.discardMessage, {
+		title: t?.title ?? n.discardTitle,
+		confirmLabel: t?.confirmLabel ?? n.discardConfirm,
+		cancelLabel: t?.cancelLabel ?? n.discardCancel,
+		confirmColor: "danger"
+	});
+}
+function o(e) {
+	return !i() || a();
+}
+var s = class {
+	constructor(e, t) {
+		this.isDirty = t, e.addController(this);
+	}
+	hostConnected() {
+		this.release ??= r(this.isDirty);
+	}
+	hostDisconnected() {
+		this.release?.(), this.release = void 0;
+	}
+};
+//#endregion
+export { s as UnsavedChangesController, a as confirmDiscardChanges, i as hasUnsavedChanges, r as trackUnsavedChanges, o as unsavedChangesGuard };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/modern-app",
   "description": "web-framework by iyulab based on lit-element",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "keywords": [
     "iyulab",
     "web-framework",
@@ -65,7 +65,7 @@
   },
   "peerDependencies": {
     "@iyulab/components": ">=2.8.0",
-    "@iyulab/router": "^0.23.0",
+    "@iyulab/router": "^0.24.0",
     "@lit/react": "^1.0.8",
     "react": "^18.0.0 || ^19.0.0"
   },
@@ -79,7 +79,7 @@
   },
   "devDependencies": {
     "@iyulab/components": "^2.20.3",
-    "@iyulab/router": "^0.23.0",
+    "@iyulab/router": "^0.24.0",
     "@lit/react": "^1.0.8",
     "@types/node": "^26.1.1",
     "@types/react": "^19.3.0",

package/skills/modern-app/SKILL.md

@@ -20,6 +20,12 @@ A client-side SPA framework built on Lit Element. Provides a single `app` single
 npm install @iyulab/modern-app
 ```
 
+`@iyulab/router` and `@iyulab/components` are peer dependencies — npm 7+ and pnpm install them for you, and the
+app shares the shell's copy. After installing or upgrading, `npm ls @iyulab/router @iyulab/modern-app` should list
+one version of each. In a workspace where another package declares them as broad peers (`"*"`), an upgrade can
+leave the older copy installed with no install error; remove the older entries from the lockfile and
+`node_modules`, then install again.
+
 ---
 
 ## Bootstrap
@@ -230,6 +236,29 @@ Sidebar states: `'default'` | `'slim'` | `'modal'` | `'mobile'` | `'mobile-open'
 
 ---
 
+## Unsaved changes
+
+Register a screen's «unsaved» check; the shell asks before any navigation (in-app dialog: Discard / Keep editing,
+Back/Forward included) and the browser asks before the document is left (`beforeunload`). Clean screens ask nothing.
+
+```ts
+import { UnsavedChangesController, confirmDiscardChanges } from '@iyulab/modern-app';
+// Lit
+private unsaved = new UnsavedChangesController(this, () => this.form.dirty);
+// React: useUnsavedChanges(dirty) from '@iyulab/modern-app/react'
+// Plain: const release = trackUnsavedChanges(() => dirty);
+// A modal drawer's close is not a navigation — ask from its cancellable `hide` event:
+drawer.addEventListener('hide', async (e) => {
+  if (!form.dirty) return;
+  e.preventDefault();
+  if (await confirmDiscardChanges()) { form.reset(); drawer.hide(); }
+});
+```
+
+`app.load({ leave })` runs first; `Router` built by hand: `new Router({ leave: unsavedChangesGuard })`.
+Track the draft on `input`, not `change` — `change` fires only when the field is left, so text typed before Escape
+or Back would read as clean.
+
 ## Routes with progress
 
 ```typescript

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

@@ -28,6 +28,12 @@ interface AppConfig {
    */
   enter?: (ctx: RouteContext) => Promise<string | boolean> | string | boolean;
 
+  /**
+   * Global guard called before the current screen is replaced (after the route `leave` guards).
+   * `false` = stay. Unsaved changes do not need it — see «Unsaved changes» in routing.md.
+   */
+  leave?: (ctx: RouteLeaveContext) => Promise<boolean> | boolean;
+
   /** Auto-navigate to the current URL on load. Default: true */
   initialLoad?: boolean;
 
@@ -134,6 +140,12 @@ interface RouteConfig {
    */
   enter?: (context: RouteContext) => Promise<string | boolean> | string | boolean;
 
+  /**
+   * Guard called before this route's screen is replaced — `false` stays (Back/Forward included).
+   * Gets `{ from, to }`; `to` is the destination's address.
+   */
+  leave?: (context: RouteLeaveContext) => Promise<boolean> | boolean;
+
   /** Child routes, matched relative to this route's path. */
   children?: RouteConfig[];