@iyulab/components 1.38.0 → 1.39.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [1.39.0] - 2026-09-08
+
+### Fixed
+
+- **A toast raised while a modal is open is no longer hidden behind it.** `Toast` hardcoded
+  `z-index: 9999` on its container while `OverlayManager` assigned open overlays a value
+  *above* 9999, so a toast could never appear over an open `u-dialog` or `u-drawer` — the
+  most common place an application reports a failure. Stacking is now a contract owned by
+  `OverlayManager`: overlays are assigned from a bounded band, and the notification layer sits
+  above that band by construction. Read `OverlayManager.notificationZIndex` instead of
+  hardcoding a value for any surface that must stay visible over an overlay.
+
+- **`Toast` no longer returns a promise that never settles, and no longer drops toasts
+  silently.** The container cache was keyed by a string derived from the target
+  (`"<position>@<id>"`), which collided when a different element reused the same `id`, never
+  cached at all for targets without an `id` (the fallback embedded `Date.now()`), and made the
+  cleanup path recompute a key that could miss. A cached container that had left the document
+  was still handed back, and an element appended to a detached container never connects — so
+  its `updateComplete` never resolves and `await Toast.success(...)` hung forever with no error
+  and no toast. Containers are now keyed by the target element itself and validated on every
+  cache hit. Passing a target that is not in the document now warns and returns instead of
+  hanging.
+
+### Changed
+
+- **Overlay z-index is derived from how many overlays are open at once, not from how many have
+  ever been opened.** The previous counter increased monotonically and never reset, leaving the
+  overlay band unbounded. Relative stacking between simultaneously open overlays is unchanged.
+
+### Added
+
+- **`OverlayManager.notificationZIndex`** — the z-index of the notification layer, guaranteed to
+  sit above the entire overlay band.
+
 ## [1.38.0] - 2026-09-08
 
 ### Changed

package/dist/utilities/OverlayManager.d.ts

@@ -1,17 +1,49 @@
 import { FocusTrap } from 'focus-trap';
 /**
- * OverlayManager는 열린 오버레이의 스택을 관리합니다.
+ * OverlayManager는 **겹치는 표면 전체의 층(layer)을 소유**합니다.
  *
- * - 오버레이 스택 순서 관리 (z-index 자동 증가)
+ * - 오버레이 스택 순서 관리 (z-index 자동 할당)
+ * - **알림 층 z-index 제공** — 알림은 오버레이의 형제가 아니라 그 «위» 채널이다
  * - body scroll lock 참조 카운팅
  * - topmost 판별 (ESC 키 처리용)
  * - focus-trap trapStack 공유
+ *
+ * ## 층 스케일 — 왜 두 개의 «띠»인가
+ *
+ * 겹침을 컴포넌트마다 따로 정하면 어긋난다. 실측(2026-09-08)으로 `Toast` 가 자기 컨테이너에
+ * `z-index: 9999` 를 박고 있었고 이 매니저가 오버레이에 **9999 «초과»** 를 주고 있어,
+ * ***모달 안에서 띄운 오류 토스트가 구조적으로 항상 가려졌다.*** 알림이 도달하지 않는 것은
+ * 조용한 실패라 아무도 보지 못했다.
+ *
+ * ⇒ 층을 **이름 있는 띠**로 고정한다(디자인 시스템의 표준 관용구다 — 겹침은 협상이 아니라
+ * 계약이다):
+ *
+ * | 띠 | 범위 | 소유 |
+ * |---|---|---|
+ * | 오버레이 | `9999` ~ `9999 + OVERLAY_BAND` | `u-dialog`·`u-drawer` 등 `UOverlayElement` 계열 |
+ * | **알림** | `notificationZIndex` | `Toast` — **오버레이 띠보다 항상 위** |
+ *
+ * ⚠**띠에 상한이 있는 것이 이 계약의 핵심이다.** 종전 `zCounter` 는 «지금까지 열린 총합»이라
+ * 단조 증가해 **상한이 없었고**, 상한이 없으면 «알림이 항상 위»를 어떤 상수로도 보장할 수
+ * 없다. 이제 **동시에 열린 깊이**(`stack.length`)로 할당하므로 띠 안에 갇힌다.
+ * 동시 오버레이가 `OVERLAY_BAND` 를 넘으면 그 이상은 같은 값을 공유한다(서로 간 겹침 순서만
+ * 포기하고, **알림이 위**라는 불변식은 유지된다) — 실제 앱이 도달하는 상태가 아니지만,
+ * 도달하더라도 무엇이 깨지는지 정해져 있는 편이 낫다.
  */
 export declare class OverlayManager {
     /** 열린 오버레이 스택 */
     private static readonly stack;
-    /** z-index 카운터 */
-    private static zCounter;
+    /** 오버레이 띠의 시작 값 */
+    private static readonly OVERLAY_BASE;
+    /** 오버레이 띠의 폭 — 이 수를 넘는 «동시» 오버레이는 최상단 값을 공유한다 */
+    private static readonly OVERLAY_BAND;
+    /**
+     * 알림 층의 z-index. **오버레이 띠 전체보다 항상 위**임이 보장된다.
+     *
+     * 토스트·스낵바처럼 «오버레이 위에서도 반드시 보여야 하는» 표면이 쓴다. 직접 상수를
+     * 박지 말고 이 값을 읽을 것 — 그래야 띠가 조정돼도 따라온다.
+     */
+    static get notificationZIndex(): number;
     /** body scroll lock 참조 카운트 */
     private static lockCount;
     /** scroll lock 이전 body overflow 값 */

package/dist/utilities/OverlayManager.js

@@ -1,18 +1,53 @@
 //#region src/utilities/OverlayManager.ts
 /**
-* OverlayManager는 열린 오버레이의 스택을 관리합니다.
+* OverlayManager는 **겹치는 표면 전체의 층(layer)을 소유**합니다.
 *
-* - 오버레이 스택 순서 관리 (z-index 자동 증가)
+* - 오버레이 스택 순서 관리 (z-index 자동 할당)
+* - **알림 층 z-index 제공** — 알림은 오버레이의 형제가 아니라 그 «위» 채널이다
 * - body scroll lock 참조 카운팅
 * - topmost 판별 (ESC 키 처리용)
 * - focus-trap trapStack 공유
+*
+* ## 층 스케일 — 왜 두 개의 «띠»인가
+*
+* 겹침을 컴포넌트마다 따로 정하면 어긋난다. 실측(2026-09-08)으로 `Toast` 가 자기 컨테이너에
+* `z-index: 9999` 를 박고 있었고 이 매니저가 오버레이에 **9999 «초과»** 를 주고 있어,
+* ***모달 안에서 띄운 오류 토스트가 구조적으로 항상 가려졌다.*** 알림이 도달하지 않는 것은
+* 조용한 실패라 아무도 보지 못했다.
+*
+* ⇒ 층을 **이름 있는 띠**로 고정한다(디자인 시스템의 표준 관용구다 — 겹침은 협상이 아니라
+* 계약이다):
+*
+* | 띠 | 범위 | 소유 |
+* |---|---|---|
+* | 오버레이 | `9999` ~ `9999 + OVERLAY_BAND` | `u-dialog`·`u-drawer` 등 `UOverlayElement` 계열 |
+* | **알림** | `notificationZIndex` | `Toast` — **오버레이 띠보다 항상 위** |
+*
+* ⚠**띠에 상한이 있는 것이 이 계약의 핵심이다.** 종전 `zCounter` 는 «지금까지 열린 총합»이라
+* 단조 증가해 **상한이 없었고**, 상한이 없으면 «알림이 항상 위»를 어떤 상수로도 보장할 수
+* 없다. 이제 **동시에 열린 깊이**(`stack.length`)로 할당하므로 띠 안에 갇힌다.
+* 동시 오버레이가 `OVERLAY_BAND` 를 넘으면 그 이상은 같은 값을 공유한다(서로 간 겹침 순서만
+* 포기하고, **알림이 위**라는 불변식은 유지된다) — 실제 앱이 도달하는 상태가 아니지만,
+* 도달하더라도 무엇이 깨지는지 정해져 있는 편이 낫다.
 */
 var OverlayManager = class {
 	static {
 		this.stack = [];
 	}
 	static {
-		this.zCounter = 0;
+		this.OVERLAY_BASE = 9999;
+	}
+	static {
+		this.OVERLAY_BAND = 1e3;
+	}
+	/**
+	* 알림 층의 z-index. **오버레이 띠 전체보다 항상 위**임이 보장된다.
+	*
+	* 토스트·스낵바처럼 «오버레이 위에서도 반드시 보여야 하는» 표면이 쓴다. 직접 상수를
+	* 박지 말고 이 값을 읽을 것 — 그래야 띠가 조정돼도 따라온다.
+	*/
+	static get notificationZIndex() {
+		return this.OVERLAY_BASE + this.OVERLAY_BAND + 1;
 	}
 	static {
 		this.lockCount = 0;
@@ -38,7 +73,7 @@ var OverlayManager = class {
 	*/
 	static add(overlay, lockBody = true) {
 		this.stack.push(overlay);
-		overlay.style.zIndex = String(9999 + ++this.zCounter);
+		overlay.style.zIndex = String(this.OVERLAY_BASE + Math.min(this.stack.length, this.OVERLAY_BAND));
 		if (lockBody) {
 			if (this.lockCount === 0) {
 				this.savedOverflow = document.body.style.overflow;

package/dist/utilities/Toast.d.ts

@@ -20,8 +20,20 @@ export interface ToastOptions {
  * 토스트 알림 유틸리티 클래스입니다.
  */
 export declare class Toast {
+    /**
+     * 위치별 컨테이너를 **타깃 엘리먼트 자신에 키잉**한다.
+     *
+     * 종전에는 `"<position>@<id>"` 문자열이 키였고, 그 파생이 세 가지를 동시에 깨뜨렸다:
+     * ⑴같은 `id`를 가진 «다른» 엘리먼트가 같은 키로 충돌한다(SPA 라우트 교체가 화면
+     * 엘리먼트를 같은 `id`로 다시 만드는 것은 평범한 패턴이다) ⑵`id`가 없으면 폴백이
+     * `el-${Date.now()}` 라 호출마다 키가 달라져 캐시가 성립하지 않고 컨테이너가 쌓인다
+     * ⑶그 불안정한 키를 `hide` 정리 경로가 **다시 계산**하므로 `containers.delete()` 가
+     * 빗나가 항목이 영구히 남는다.
+     *
+     * `WeakMap` 은 셋을 전부 구조적으로 없앤다 — 엘리먼트 동일성이 곧 키라 충돌이 불가능하고,
+     * `id` 유무에 의존하지 않으며, 타깃이 버려지면 그 항목도 함께 수거된다.
+     */
     private static containers;
-    private static elements;
     /**
      * 모든 Toast 호출에 적용될 전역 기본 옵션입니다. 개별 호출의 `options`가 우선합니다.
      *
@@ -47,8 +59,13 @@ export declare class Toast {
     static error(content: string, options?: ToastOptions): Promise<void>;
     /** 토스트 알림을 생성합니다. */
     static show(status?: AlertStatus, content?: string, options?: ToastOptions): Promise<void>;
-    /** 컨테이너 키를 생성합니다. */
-    private static getContainerKey;
-    /** 위치에 맞는 컨테이너 엘리먼트를 가져오거나, 생성합니다. */
+    /**
+     * 위치에 맞는 컨테이너 엘리먼트를 가져오거나, 생성합니다.
+     *
+     * ⚠**캐시 적중은 그 컨테이너가 «여전히 쓸 수 있는가»를 확인한 뒤에만 유효하다.** 호스트가
+     * 갈아끼워지면(`body.innerHTML = ''`, 셸 재구축) 캐시된 컨테이너는 문서에서 떨어진 채
+     * 남는데, 거기에 append 된 엘리먼트는 **연결되지 않아 `updateComplete` 가 영원히 해소되지
+     * 않는다**. 낡은 항목은 버리고 새로 만든다.
+     */
     private static getOrCreateContainer;
 }

package/dist/utilities/Toast.js

@@ -1,3 +1,4 @@
+import { OverlayManager } from "./OverlayManager.js";
 import { UAlert } from "../components/alert/UAlert.js";
 //#region src/utilities/Toast.ts
 /**
@@ -5,10 +6,7 @@ import { UAlert } from "../components/alert/UAlert.js";
 */
 var Toast = class {
 	static {
-		this.containers = /* @__PURE__ */ new Map();
-	}
-	static {
-		this.elements = /* @__PURE__ */ new Set();
+		this.containers = /* @__PURE__ */ new WeakMap();
 	}
 	static {
 		this.DefaultOptions = {};
@@ -52,36 +50,46 @@ var Toast = class {
 		el.title = merged.title || "";
 		el.closable = merged.closable ?? true;
 		el.duration = merged.duration ?? 4e3;
-		this.elements.add(el);
 		const position = merged.position || "top-right";
 		const target = merged.target || document.body;
 		const container = this.getOrCreateContainer(position, target);
 		container.appendChild(el);
+		if (!el.isConnected) {
+			container.removeChild(el);
+			console.warn("[@iyulab/components] Toast was not shown: the target element is not in the document.\n  A toast can only render inside a connected element — pass a target that is attached,\n  or omit `target` to use document.body.");
+			return;
+		}
 		await el.updateComplete;
 		el.show();
 		el.addEventListener("hide", async (e) => {
 			if (e.target !== el) return;
 			await new Promise((resolve) => setTimeout(resolve, 200));
 			el.remove();
-			this.elements.delete(el);
 			if (!container.hasChildNodes()) {
-				const containerKey = this.getContainerKey(position, target);
 				container.remove();
-				this.containers.delete(containerKey);
+				this.containers.get(target)?.delete(position);
 			}
 		});
 	}
-	/** 컨테이너 키를 생성합니다. */
-	static getContainerKey(position, target) {
-		return `${position}@${target === document.body ? "body" : target.id || `el-${Date.now()}`}`;
-	}
-	/** 위치에 맞는 컨테이너 엘리먼트를 가져오거나, 생성합니다. */
+	/**
+	* 위치에 맞는 컨테이너 엘리먼트를 가져오거나, 생성합니다.
+	*
+	* ⚠**캐시 적중은 그 컨테이너가 «여전히 쓸 수 있는가»를 확인한 뒤에만 유효하다.** 호스트가
+	* 갈아끼워지면(`body.innerHTML = ''`, 셸 재구축) 캐시된 컨테이너는 문서에서 떨어진 채
+	* 남는데, 거기에 append 된 엘리먼트는 **연결되지 않아 `updateComplete` 가 영원히 해소되지
+	* 않는다**. 낡은 항목은 버리고 새로 만든다.
+	*/
 	static getOrCreateContainer(position, target) {
-		const key = this.getContainerKey(position, target);
-		let container = this.containers.get(key);
-		if (container) return container;
-		container = document.createElement("div");
-		container.style.zIndex = "9999";
+		let byPosition = this.containers.get(target);
+		if (!byPosition) {
+			byPosition = /* @__PURE__ */ new Map();
+			this.containers.set(target, byPosition);
+		}
+		const cached = byPosition.get(position);
+		if (cached && cached.isConnected && cached.parentNode === target) return cached;
+		if (cached) byPosition.delete(position);
+		const container = document.createElement("div");
+		container.style.zIndex = String(OverlayManager.notificationZIndex);
 		container.style.display = "flex";
 		container.style.gap = "10px";
 		const isTargeted = target !== document.body;
@@ -114,7 +122,7 @@ var Toast = class {
 		}
 		container.style.transform = transformParts.length ? transformParts.join(" ") : "";
 		target.appendChild(container);
-		this.containers.set(key, container);
+		byPosition.set(position, container);
 		return container;
 	}
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@iyulab/components",
   "description": "web-components library based on lit-element made by iyulab",
-  "version": "1.38.0",
+  "version": "1.39.0",
   "keywords": [
     "iyulab",
     "components",

package/skills/iyulab-components/references/utilities/overlay-manager.md

@@ -4,7 +4,20 @@
 import { OverlayManager } from '@iyulab/components';
 ```
 
-Internal static manager for the overlay stack. Used by `UOverlayElement` (`u-dialog`, `u-drawer`) to track open overlays, assign z-index, and manage body scroll locking.
+Internal static manager that **owns the layer scale for every stacking surface**. Used by `UOverlayElement` (`u-dialog`, `u-drawer`) to track open overlays, assign z-index, and manage body scroll locking — and read by `Toast` for the notification layer.
+
+## Layer scale
+
+Stacking is a contract, not a negotiation between components. Two bands exist, and the notification band is **always above** the overlay band:
+
+| Band | Value | Owned by |
+|------|-------|----------|
+| Overlay | `9999 + depth`, capped at `9999 + 1000` | `UOverlayElement` subclasses (`u-dialog`, `u-drawer`, custom overlays) |
+| **Notification** | `OverlayManager.notificationZIndex` | `Toast` |
+
+Overlay z-index comes from **how many overlays are open at once** (stack depth), not from how many have ever been opened. That is what bounds the band — and a bounded band is what lets the notification layer sit above it by construction. More than 1000 simultaneous overlays share the top value: they stop stacking relative to each other, but notifications stay above them.
+
+> **Do not hardcode a z-index for a surface that must appear above overlays.** Read `OverlayManager.notificationZIndex` so the value follows the scale.
 
 > **Note:** You generally do not need to use `OverlayManager` directly. It is called automatically by overlay components. Only use it if you are building a custom overlay component that extends `UOverlayElement`.
 
@@ -12,10 +25,11 @@ Internal static manager for the overlay stack. Used by `UOverlayElement` (`u-dia
 
 | Member | Type / Returns | Description |
 |--------|----------------|-------------|
-| `OverlayManager.add(overlay, lockBody?)` | `void` | Register an overlay; increments z-index; optionally locks body scroll |
+| `OverlayManager.add(overlay, lockBody?)` | `void` | Register an overlay; assigns a z-index from the overlay band by stack depth; optionally locks body scroll |
 | `OverlayManager.remove(overlay, lockBody?)` | `void` | Unregister an overlay; releases scroll lock if no overlays remain |
 | `OverlayManager.isTopmost(overlay)` | `boolean` | Returns `true` if the overlay is the topmost in the stack (used for ESC key handling) |
 | `OverlayManager.size` | `number` | Number of currently open overlays |
+| `OverlayManager.notificationZIndex` | `number` | z-index of the notification layer — guaranteed above the whole overlay band. Use this for toasts, snackbars, and anything else that must remain visible over an open modal |
 | `OverlayManager.trapStack` | `FocusTrap[]` | Shared focus-trap stack (used internally by focus-trap library) |
 
 ## Example (custom overlay)