@ixfx/components 0.14.3 → 0.14.4

package/dist/index.d.ts

@@ -2571,6 +2571,23 @@ interface PillRendererOptions {
   queueDisplay?: PillQueueDisplay;
   /** Extra margin (px) added to the default spacing on each side, letting pills avoid eg. a fixed header/footer/notch. */
   safeArea?: PillSafeArea;
+  /**
+   * Render the toasts in the browser's top layer (via the Popover API), so they
+   * appear above modal `<dialog>` backdrops and other popovers regardless of any
+   * `z-index`. Each time a new toast arrives the container is re-promoted, so a
+   * dialog opened after earlier toasts doesn't keep covering later ones.
+   * Browsers without the Popover API silently fall back to normal stacking.
+   *
+   * Caveat: a modal dialog makes the rest of the page inert, including toasts, so
+   * they show above it but can't be clicked until it closes (timed dismissal is
+   * unaffected). Default `true`. Set `false` to manage stacking yourself with `zIndex`.
+   */
+  topLayer?: boolean;
+  /**
+   * `z-index` for the toast layer when `topLayer` is `false`. Ignored otherwise.
+   * Leave unset to take no part in z-ordering.
+   */
+  zIndex?: number;
 }
 declare function createPillRenderer(options?: PillRendererOptions): NotificationRenderer;
 //#endregion

package/dist/index.js

@@ -10572,11 +10572,15 @@ function restingTransform(edges, dx, dy) {
 	if (edges.horizontal === `middle`) return `translateX(-50%) translate(${dx}px, ${dy}px)`;
 	return `translate(${dx}px, ${dy}px)`;
 }
+function supportsPopover(el) {
+	return typeof el.showPopover === `function` && typeof el.hidePopover === `function`;
+}
 function createPillRenderer(options = {}) {
 	const position = options.position ?? `top-right`;
 	const queueDisplay = options.queueDisplay ?? `list`;
 	const safeArea = options.safeArea ?? {};
 	const edges = edgesOf(position);
+	const useTopLayer = options.topLayer ?? true;
 	let container = null;
 	let hooks = null;
 	const pills = /* @__PURE__ */ new Map();
@@ -10588,9 +10592,20 @@ function createPillRenderer(options = {}) {
 		container.className = `ixfx-notification-container`;
 		container.setAttribute(`role`, `region`);
 		container.setAttribute(`aria-label`, `Notifications`);
+		container.style.cssText = `pointer-events: none;`;
+		if (useTopLayer && supportsPopover(container)) {
+			container.setAttribute(`popover`, `manual`);
+			container.style.cssText += `position: fixed; inset: 0 auto auto 0; width: 0; height: 0; margin: 0; padding: 0; border: 0; overflow: visible; background: transparent; color: inherit;`;
+		} else if (!useTopLayer && options.zIndex !== void 0) container.style.cssText += `position: fixed; inset: 0 auto auto 0; width: 0; height: 0; z-index: ${options.zIndex};`;
 		document.body.appendChild(container);
 		return container;
 	}
+	/** Put the container on top of the top-layer stack (above anything opened since it was last shown). */
+	function promote(cont) {
+		if (!cont.hasAttribute(`popover`)) return;
+		if (cont.matches(`:popover-open`)) cont.hidePopover();
+		cont.showPopover();
+	}
 	function updateAttributes(el, notification) {
 		el.setAttribute(`notification-type`, notification.type);
 		el.setAttribute(`message`, notification.message);
@@ -10675,6 +10690,7 @@ function createPillRenderer(options = {}) {
 	}
 	function setNotifications(notifications, _queueSize) {
 		const cont = ensureContainer();
+		let added = false;
 		const idsToKeep = new Set(notifications.map((n) => n.id));
 		for (const notification of notifications) {
 			const existing = pills.get(notification.id);
@@ -10689,8 +10705,10 @@ function createPillRenderer(options = {}) {
 				notification
 			});
 			cont.appendChild(el);
+			added = true;
 			measureRowHeight(el);
 		}
+		if (added) promote(cont);
 		for (const [id] of pills) if (!idsToKeep.has(id)) dismiss(id);
 		requestAnimationFrame(() => applyLayout(notifications));
 	}

package/docs-user/index.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
-  "version": "0.14.3",
-  "generated": "2026-10-16T15:45:06.852Z",
+  "version": "0.14.4",
+  "generated": "2026-10-16T16:32:35.695Z",
   "components": [
     {
       "name": "ac-text",

package/docs-user/notifier.md

@@ -97,6 +97,22 @@ NotificationManager.configure({
 | `position` | `'top-left' \| 'top-middle' \| 'top-right' \| 'bottom-left' \| 'bottom-middle' \| 'bottom-right'` | `'top-right'` | Which corner/edge pills anchor to, and the direction they slide in/out from. |
 | `queueDisplay` | `'list' \| 'stack'` | `'list'` | How queued (non-front) messages are shown — see below. |
 | `safeArea` | `{ top?, right?, bottom?, left? }` (px) | `{}` | Extra margin added on top of the default spacing, e.g. to avoid a fixed header/footer/notch. |
+| `topLayer` | `boolean` | `true` | Show toasts in the browser's top layer so they sit above modal dialogs and popovers. See [Stacking with dialogs](#stacking-with-dialogs-and-popovers). |
+| `zIndex` | `number` | — | Only used when `topLayer` is `false`: the `z-index` of the toast layer, for apps that manage stacking themselves. |
+
+### Stacking with dialogs and popovers
+
+A modal `<dialog>` (opened with `showModal()`) and its backdrop live in the browser's *top layer*, which no `z-index` can beat. So by default the pill renderer puts its container in the top layer too, using the [Popover API](https://developer.mozilla.org/docs/Web/API/Popover_API) (`popover="manual"`), and toasts appear above the backdrop.
+
+- **Order follows time.** Top-layer elements stack in the order they were shown. Each time a *new* toast arrives the container is re-shown, so it ends up above a dialog opened after earlier toasts. An already-visible toast is not re-promoted if a dialog opens later; the next toast will be.
+- **Modal dialogs make the page inert.** While a modal dialog is open, everything outside it, including toasts in the top layer, cannot be clicked or focused. Toasts are visible and still time out, but tap-to-dismiss only works once the dialog closes. If toasts must be clickable over a modal, open that dialog non-modally (`show()`), or render toasts inside the dialog.
+- **Manual control.** Pass `topLayer: false` to opt out. Toasts then stack normally; give them a `zIndex` above your own layers if needed:
+
+```typescript
+createPillRenderer({ topLayer: false, zIndex: 1000 });
+```
+
+- **Older browsers** without the Popover API fall back to normal stacking automatically.
 
 ### `queueDisplay: 'list'`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ixfx/components",
   "type": "module",
-  "version": "0.14.3",
+  "version": "0.14.4",
   "packageManager": "pnpm@10.0.0",
   "description": "Web components for ixfx — Lit-based UI toolkit",
   "author": "Clint Heyer",