@k2b/ui 0.11.0 → 0.12.0

package/dist/ssr/feedback/toast.js

@@ -1,30 +1,47 @@
 import { getK2bPortalRoot } from "../internal/portal";
 import { resolveUiMessages } from "../intl/messages";
-const DEFAULT_DURATION_MS = 3000;
-const MAX_VISIBLE_TOASTS = 5;
+/** Visible toasts on a wide viewport; the rail's narrow layout shows fewer. */
+const MAX_VISIBLE_TOASTS = 3;
+const MAX_VISIBLE_TOASTS_NARROW = 2;
+/** The same media query that moves the rail to the top edge in the stylesheet. */
+const NARROW_RAIL_QUERY = "(max-width: 47.999rem), (max-height: 29.999rem)";
 const ANIMATION_MS = 200;
+/** Reading time: a short message stays 4 s, longer text about 1 s more per 30 characters, up to 12 s. */
+const READ_BASE_MS = 4_000;
+const READ_FREE_CHARACTERS = 40;
+const READ_MS_PER_CHARACTER = 35;
+const READ_MAX_MS = 12_000;
+/** Errors and toasts with an action stay long enough to reach them with a keyboard or a screen magnifier. */
+const REACHABLE_MS = 8_000;
+/** An error longer than this stays until it is closed, so it can be read and copied. */
+const STICKY_ERROR_CHARACTERS = 120;
+/** A live region needs a moment between being found and being written to. */
+const ANNOUNCE_DELAY_MS = 100;
+const ANNOUNCEMENT_LIFETIME_MS = 7_000;
 export const K2B_TOAST_CONTAINER_ID = "k2b-ui-toast-container";
 const CONTAINER_ATTRIBUTE = "data-k2b-toast-container";
+const LIVE_ATTRIBUTE = "data-k2b-toast-live";
 const VARIANT_STYLES = {
   default: {
     tone: "info",
-    iconClass: "ti-info-circle",
-    titleKey: "info"
+    iconClass: "ti-info-circle"
   },
   success: {
     tone: "success",
-    iconClass: "ti-check",
-    titleKey: "success"
+    iconClass: "ti-circle-check"
   },
   error: {
     tone: "danger",
-    iconClass: "ti-x",
-    titleKey: "error"
+    iconClass: "ti-alert-circle"
   }
 };
 
-/** Default titles follow the document locale, like the other imperative `@k2b/ui` surfaces. */
-const defaultTitle = variant => resolveUiMessages()[VARIANT_STYLES[variant].titleKey];
+/** How long a toast stays when the caller passes no duration. */
+const defaultDuration = (variant, text, hasAction) => {
+  if (variant === "error" && text.length > STICKY_ERROR_CHARACTERS) return 0;
+  const reading = Math.min(READ_MAX_MS, READ_BASE_MS + Math.max(0, text.length - READ_FREE_CHARACTERS) * READ_MS_PER_CHARACTER);
+  return variant === "error" || hasAction ? Math.max(REACHABLE_MS, reading) : reading;
+};
 const normalizedIconClass = iconClass => {
   const tokens = iconClass.split(/\s+/).filter(Boolean).filter(token => token !== "ti");
   return ["ti", ...tokens].join(" ");
@@ -32,35 +49,133 @@ const normalizedIconClass = iconClass => {
 const applyIconClass = (icon, iconClass) => {
   icon.className = normalizedIconClass(iconClass);
 };
-const applyLiveRegion = (element, variant) => {
-  const isError = variant === "error";
-  element.setAttribute("role", isError ? "alert" : "status");
-  element.setAttribute("aria-live", isError ? "assertive" : "polite");
-  element.setAttribute("aria-atomic", "true");
-};
 const liveToasts = new Set();
+
+/**
+ * Cards under the pointer or holding keyboard focus. While the rail holds any, no toast times out, so nothing moves
+ * under the pointer or out from under focus because a neighbour expired.
+ */
+const pointerHolds = new Set();
+const focusHolds = new Set();
+const railHeld = () => pointerHolds.size + focusHolds.size > 0;
+
+/**
+ * Firefox and WebKit fire no focusout when a focused element leaves the document, and WebKit no pointerleave when
+ * the hovered element inside a card is removed, as when custom content replaces a button or the rail's scope
+ * unmounts. While anything holds the rail, a change to the document or the pointer moving onto something else
+ * drops the holds that no longer apply, so one stale hold never freezes the rail.
+ */
+const releaseStaleHolds = pointerTarget => {
+  for (const card of Array.from(pointerHolds)) if (!card.isConnected || pointerTarget !== undefined && !card.contains(pointerTarget)) setHold(pointerHolds, card, false);
+  for (const card of Array.from(focusHolds)) if (!card.isConnected || !card.contains(card.ownerDocument.activeElement)) setHold(focusHolds, card, false);
+};
+const watchStaleHolds = doc => {
+  const observer = new MutationObserver(() => releaseStaleHolds());
+  observer.observe(doc, {
+    childList: true,
+    subtree: true
+  });
+  const onPointerOver = event => releaseStaleHolds(event.target instanceof Node ? event.target : null);
+  doc.addEventListener("pointerover", onPointerOver, true);
+  return () => {
+    observer.disconnect();
+    doc.removeEventListener("pointerover", onPointerOver, true);
+  };
+};
+let unwatchStaleHolds = null;
+function setHold(holds, card, held) {
+  const wasHeld = railHeld();
+  if (held) holds.add(card);else holds.delete(card);
+  if (railHeld() !== wasHeld) {
+    for (const item of Array.from(liveToasts)) (wasHeld ? item.resume : item.pause)();
+    unwatchStaleHolds?.();
+    unwatchStaleHolds = wasHeld ? null : watchStaleHolds(card.ownerDocument);
+  }
+  // A released card may be the one the rail limit had to wait for.
+  if (!held) enforceCap();
+}
+const VISUALLY_HIDDEN = "position:absolute;width:1px;height:1px;margin:-1px;padding:0;border:0;overflow:hidden;clip-path:inset(50%);white-space:nowrap;";
+
+/**
+ * Two persistent, empty live regions beside the rail: polite for every toast, assertive for errors. A region that
+ * already exists when its text arrives is announced reliably, unlike one inserted with its text already inside.
+ * They sit outside the rail because the rail moves into a fresh top-layer element for every toast.
+ */
+const ensureLiveRegions = root => {
+  const existing = Array.from(root.children).find(child => child.hasAttribute(LIVE_ATTRIBUTE));
+  if (existing instanceof HTMLElement) return existing;
+  const live = document.createElement("div");
+  live.setAttribute(LIVE_ATTRIBUTE, "");
+  live.style.cssText = VISUALLY_HIDDEN;
+  for (const assertive of [false, true]) {
+    const region = document.createElement("div");
+    region.setAttribute("role", assertive ? "alert" : "status");
+    region.setAttribute("aria-live", assertive ? "assertive" : "polite");
+    // Both roles are atomic by default, which would read every line still in the region again with each new one.
+    region.setAttribute("aria-atomic", "false");
+    region.dataset.politeness = assertive ? "assertive" : "polite";
+    live.appendChild(region);
+  }
+  root.appendChild(live);
+  return live;
+};
+
+/** Each announcement is its own line, so a burst of toasts or a repeated message is still read. */
+const announce = (root, text, assertive) => {
+  if (!root || !text) return;
+  const region = ensureLiveRegions(root).querySelector(`[data-politeness="${assertive ? "assertive" : "polite"}"]`);
+  if (!region) return;
+  const line = document.createElement("div");
+  line.textContent = text;
+  setTimeout(() => {
+    region.appendChild(line);
+    setTimeout(() => line.remove(), ANNOUNCEMENT_LIFETIME_MS);
+  }, ANNOUNCE_DELAY_MS);
+};
 const ensureContainer = () => {
   if (typeof document === "undefined") return null;
   const root = getK2bPortalRoot();
+  ensureLiveRegions(root);
   let container = root.querySelector(`[${CONTAINER_ATTRIBUTE}]`);
   if (container) return container;
   container = document.createElement("div");
   container.id = K2B_TOAST_CONTAINER_ID;
   container.setAttribute(CONTAINER_ATTRIBUTE, "");
   container.setAttribute("popover", "manual");
+  container.setAttribute("role", "region");
+  container.setAttribute("aria-label", resolveUiMessages().notifications);
   // Keep the source rail geometry inline: it must defeat UA popover defaults
   // even when a consumer has not loaded the optional package stylesheet yet.
-  // The stylesheet only moves the rail to the top edge on narrow viewports
-  // through the two edge variables.
-  container.style.cssText = "position:fixed;left:auto;right:env(safe-area-inset-right,0px);" + "top:var(--k2b-toast-rail-top,auto);bottom:var(--k2b-toast-rail-bottom,env(safe-area-inset-bottom,0px));" + "z-index:50;box-sizing:border-box;display:flex;flex-direction:column;gap:0.5rem;" + "width:min(22rem,calc(100vw - env(safe-area-inset-left,0px) - env(safe-area-inset-right,0px)));" + "height:auto;max-width:100vw;" + "max-height:calc(100dvh - env(safe-area-inset-top,0px) - env(safe-area-inset-bottom,0px));" + "margin:0;padding:1rem;border:0;background:transparent;overflow-x:hidden;overflow-y:auto;overscroll-behavior:contain;" + "pointer-events:none;";
+  // The stylesheet only moves the rail to the top edge, and to the full width
+  // of a phone, through the rail variables.
+  container.style.cssText = "position:fixed;left:var(--k2b-toast-rail-left,auto);right:env(safe-area-inset-right,0px);" + "top:var(--k2b-toast-rail-top,auto);bottom:var(--k2b-toast-rail-bottom,env(safe-area-inset-bottom,0px));" + "z-index:50;box-sizing:border-box;display:flex;flex-direction:var(--k2b-toast-rail-direction,column);" + "width:var(--k2b-toast-rail-width,min(24rem,calc(100vw - env(safe-area-inset-left,0px) - env(safe-area-inset-right,0px))));" + "height:auto;max-width:100vw;" + "max-height:calc(100dvh - env(safe-area-inset-top,0px) - var(--k2b-toast-offset-top,0px) - env(safe-area-inset-bottom,0px));" + "margin:0;padding:var(--k2b-toast-rail-padding,0.75rem 1rem);border:0;background:transparent;overflow-x:hidden;overflow-y:auto;overscroll-behavior:contain;" + "pointer-events:none;";
   root.appendChild(container);
   return container;
 };
+
+/** Moving nodes resets their scroll offsets and drops focus; a custom slot can hold a scrolled list or a focused control. */
+const captureViewState = container => {
+  const focused = document.activeElement instanceof HTMLElement && container.contains(document.activeElement) ? document.activeElement : null;
+  const scrolled = Array.from(container.querySelectorAll("*")).filter(element => element.scrollTop || element.scrollLeft).map(element => [element, element.scrollTop, element.scrollLeft]);
+  const railTop = container.scrollTop;
+  return rail => {
+    rail.scrollTop = railTop;
+    for (const [element, top, left] of scrolled) {
+      element.scrollTop = top;
+      element.scrollLeft = left;
+    }
+    if (focused?.isConnected && rail.contains(focused)) focused.focus({
+      preventScroll: true
+    });
+  };
+};
 const promoteToTopLayer = container => {
   if (typeof container.showPopover !== "function" || !container.isConnected) return container;
   let active = container;
+  let restore = null;
   try {
     if (container.matches(":popover-open") || document.querySelector("dialog:modal")) {
+      restore = captureViewState(container);
       const next = container.cloneNode(false);
       while (container.firstChild) next.appendChild(container.firstChild);
       const root = container.parentElement ?? getK2bPortalRoot();
@@ -72,6 +187,8 @@ const promoteToTopLayer = container => {
   } catch {
     active.removeAttribute("popover");
   }
+  // Offsets apply only once the rail is rendered again, so after it is shown.
+  restore?.(active);
   return active;
 };
 
@@ -90,17 +207,66 @@ const hideEmptyContainers = () => {
     }
   }
 };
-const renderLead = (lead, variant, iconClassOverride) => {
-  const style = VARIANT_STYLES[variant];
-  lead.replaceChildren();
-  lead.className = "k2b-toast__icon";
-  lead.dataset.tone = style.tone;
-  const icon = document.createElement("i");
-  applyIconClass(icon, iconClassOverride ?? style.iconClass);
-  icon.setAttribute("aria-hidden", "true");
-  lead.appendChild(icon);
-  return icon;
+
+/**
+ * Every toast and custom slot sits in a slot that grows from and collapses to zero height, so its neighbours glide
+ * instead of jumping when it arrives or leaves. The card carries the chrome and `data-open` / `data-closing`.
+ */
+
+const railItem = card => {
+  card.addEventListener("pointerenter", () => setHold(pointerHolds, card, true));
+  card.addEventListener("pointerleave", () => setHold(pointerHolds, card, false));
+  card.addEventListener("focusin", () => setHold(focusHolds, card, true));
+  card.addEventListener("focusout", event => {
+    if (!card.contains(event.relatedTarget)) setHold(focusHolds, card, false);
+  });
+  const slot = document.createElement("div");
+  slot.className = "k2b-toast-slot";
+  slot.dataset.state = "entering";
+  const clip = document.createElement("div");
+  clip.className = "k2b-toast-slot__clip";
+  clip.appendChild(card);
+  slot.appendChild(clip);
+  return {
+    slot,
+    open: () => {
+      // The entering state must be laid out once before it changes, or nothing transitions.
+      slot.getBoundingClientRect();
+      requestAnimationFrame(() => {
+        if (card.dataset.closing) return;
+        slot.dataset.state = "open";
+        card.dataset.open = "true";
+      });
+    },
+    close: onRemoved => {
+      slot.dataset.state = "closing";
+      card.dataset.closing = "true";
+      // A card that leaves under the pointer or with focus no longer holds the rail.
+      if (pointerHolds.has(card)) setHold(pointerHolds, card, false);
+      if (focusHolds.has(card)) setHold(focusHolds, card, false);
+      setTimeout(() => {
+        slot.remove();
+        hideEmptyContainers();
+        onRemoved?.();
+      }, ANIMATION_MS);
+    }
+  };
 };
+
+/**
+ * The rail is full: older timed confirmations leave first, then older errors and sticky toasts. Running progress, the
+ * newest toast, and a toast under the pointer or with focus stay; the rail waits until they are released.
+ */
+function enforceCap() {
+  const narrow = typeof matchMedia === "function" && matchMedia(NARROW_RAIL_QUERY).matches;
+  const cap = narrow ? MAX_VISIBLE_TOASTS_NARROW : MAX_VISIBLE_TOASTS;
+  while (liveToasts.size > cap) {
+    const older = Array.from(liveToasts).slice(0, -1).filter(item => !item.held());
+    const victim = older.find(item => !item.keep()) ?? older.find(item => !item.progress());
+    if (!victim) return;
+    victim.dismiss();
+  }
+}
 const showToast = (description, options) => {
   const initialContainer = ensureContainer();
   if (!initialContainer) {
@@ -110,40 +276,70 @@ const showToast = (description, options) => {
       update: noop
     };
   }
+  const messages = resolveUiMessages();
+  const doc = initialContainer.ownerDocument;
+  // Focus returns here when a focused toast closes and no other toast can take it.
+  const opener = doc.activeElement instanceof HTMLElement && !doc.activeElement.closest(`[${CONTAINER_ATTRIBUTE}]`) ? doc.activeElement : null;
   let dismissed = false;
   let dismissTimer = null;
   let currentVariant = options?.variant ?? "default";
   let currentProgress = options?.progress ?? null;
-  let currentDuration = options?.duration ?? DEFAULT_DURATION_MS;
-  let remainingDuration = currentDuration;
+  let currentAction = options?.action ?? null;
+  let explicitDuration = options?.duration;
+  let remainingDuration = 0;
   let timerStartedAt = 0;
-  let pausedByPointer = false;
-  let pausedByFocus = false;
-  const toastElement = document.createElement("div");
+  let lastAnnouncement = "";
+  const toastElement = doc.createElement("div");
   toastElement.className = "k2b-toast";
   toastElement.dataset.tone = VARIANT_STYLES[currentVariant].tone;
   toastElement.dataset.k2bToast = "";
-  const leadElement = document.createElement("div");
-  let leadIconElement = renderLead(leadElement, currentVariant, options?.iconClass);
-  const contentElement = document.createElement("div");
+  const leadElement = doc.createElement("div");
+  leadElement.className = "k2b-toast__icon";
+  leadElement.setAttribute("aria-hidden", "true");
+  const leadIconElement = doc.createElement("i");
+  leadElement.appendChild(leadIconElement);
+  const renderLead = iconClassOverride => {
+    leadElement.dataset.tone = VARIANT_STYLES[currentVariant].tone;
+    applyIconClass(leadIconElement, iconClassOverride ?? VARIANT_STYLES[currentVariant].iconClass);
+  };
+  renderLead(options?.iconClass);
+  const contentElement = doc.createElement("div");
   contentElement.className = "k2b-toast__content";
-  applyLiveRegion(contentElement, currentVariant);
-  const titleElement = document.createElement("div");
+  const titleElement = doc.createElement("div");
   titleElement.className = "k2b-toast__title";
-  titleElement.textContent = options?.title ?? defaultTitle(currentVariant);
-  const descriptionElement = document.createElement("div");
+  const renderTitle = title => {
+    titleElement.textContent = title ?? "";
+    titleElement.hidden = !title;
+  };
+  renderTitle(options?.title);
+  const descriptionElement = doc.createElement("div");
   descriptionElement.className = "k2b-toast__description";
   descriptionElement.textContent = description;
   contentElement.append(titleElement, descriptionElement);
-  const closeButton = document.createElement("button");
+  const closeButton = doc.createElement("button");
   closeButton.type = "button";
   closeButton.className = "k2b-toast__close";
-  closeButton.setAttribute("aria-label", options?.dismissLabel ?? resolveUiMessages().dismissNotification);
-  const closeIcon = document.createElement("i");
+  closeButton.setAttribute("aria-label", options?.dismissLabel ?? messages.dismissNotification);
+  const closeIcon = doc.createElement("i");
   closeIcon.className = "ti ti-x";
   closeIcon.setAttribute("aria-hidden", "true");
   closeButton.appendChild(closeIcon);
+
+  // Inside the content, so a titled progress toast can place the bar between its title and its summary line.
+  const progressElement = doc.createElement("progress");
+  progressElement.className = "k2b-toast__progress";
+  progressElement.max = 1;
+  contentElement.appendChild(progressElement);
   toastElement.append(leadElement, contentElement, closeButton);
+  const item = railItem(toastElement);
+  const text = () => [titleElement.textContent, descriptionElement.textContent].filter(Boolean).join(". ");
+  const effectiveDuration = () => explicitDuration ?? defaultDuration(currentVariant, text(), currentAction !== null);
+  /** The error word is read before the message; the action is left out. */
+  const spoken = () => currentVariant === "error" ? `${resolveUiMessages().error}: ${text()}` : text();
+  const say = () => {
+    lastAnnouncement = spoken();
+    announce(item.slot.parentElement?.parentElement ?? null, lastAnnouncement, currentVariant === "error");
+  };
   const clearDismissTimer = () => {
     if (dismissTimer === null) return;
     clearTimeout(dismissTimer);
@@ -155,132 +351,176 @@ const showToast = (description, options) => {
     clearDismissTimer();
   };
   const resumeDismissTimer = () => {
-    if (dismissed || currentProgress !== null || currentDuration === 0 || remainingDuration <= 0 || pausedByPointer || pausedByFocus) return;
+    if (dismissed || currentProgress !== null || remainingDuration <= 0 || railHeld() || doc.hidden) return;
     clearDismissTimer();
     timerStartedAt = Date.now();
     dismissTimer = setTimeout(() => dismiss(), remainingDuration);
   };
-  const resetDismissTimer = duration => {
+  const resetDismissTimer = () => {
     clearDismissTimer();
-    currentDuration = duration;
-    remainingDuration = duration;
+    remainingDuration = effectiveDuration();
     resumeDismissTimer();
   };
+  const onVisibilityChange = () => doc.hidden ? pauseDismissTimer() : resumeDismissTimer();
+
+  /** The close button of the nearest open toast in one direction, past neighbours that are still closing. */
+  const nearestOpenClose = step => {
+    for (let slot = step(item.slot); slot; slot = step(slot)) {
+      const button = slot.querySelector(".k2b-toast:not([data-closing]) .k2b-toast__close");
+      if (button) return button;
+    }
+    return null;
+  };
+
+  /** A focused toast hands focus to its neighbour, or back to where the user was, instead of dropping it on the page. */
+  const moveFocusAway = () => {
+    if (!toastElement.contains(doc.activeElement)) return;
+    const next = nearestOpenClose(slot => slot.nextElementSibling) ?? nearestOpenClose(slot => slot.previousElementSibling);
+    const target = next ?? (opener?.isConnected ? opener : null);
+    if (target) target.focus({
+      preventScroll: true
+    });else doc.activeElement?.blur();
+  };
   const dismiss = () => {
     if (dismissed) return;
     dismissed = true;
     clearDismissTimer();
-    liveToasts.delete(handle);
-    toastElement.dataset.closing = "true";
-    setTimeout(() => {
-      toastElement.remove();
-      hideEmptyContainers();
-    }, ANIMATION_MS);
+    liveToasts.delete(live);
+    doc.removeEventListener("visibilitychange", onVisibilityChange);
+    moveFocusAway();
+    item.close();
   };
-  const progressElement = document.createElement("progress");
-  progressElement.className = "k2b-toast__progress";
-  progressElement.max = 1;
   const renderProgress = () => {
     progressElement.hidden = currentProgress === null;
-    progressElement.setAttribute("aria-label", titleElement.textContent || descriptionElement.textContent || "");
+    toastElement.dataset.progress = String(currentProgress !== null);
+    const title = titleElement.textContent;
+    const summary = descriptionElement.textContent ?? "";
+    progressElement.setAttribute("aria-label", title || summary);
+    // With a title, the message is the summary line under the bar ("6 of 12 files"), read instead of a bare percentage.
+    if (typeof currentProgress === "number" && title && summary) progressElement.setAttribute("aria-valuetext", summary);else progressElement.removeAttribute("aria-valuetext");
     if (typeof currentProgress === "number") progressElement.value = Number.isFinite(currentProgress) ? Math.max(0, Math.min(1, currentProgress)) : 0;else progressElement.removeAttribute("value");
   };
-  contentElement.append(progressElement);
   renderProgress();
   let actionElement = null;
-  const renderAction = action => {
-    actionElement?.remove();
-    actionElement = null;
-    if (!action) return;
+  const createAction = action => {
+    let element;
     if ("href" in action) {
-      const link = document.createElement("a");
-      link.href = action.href;
-      actionElement = link;
+      element = doc.createElement("a");
+      element.href = action.href;
     } else {
-      const button = document.createElement("button");
-      button.type = "button";
-      actionElement = button;
+      element = doc.createElement("button");
+      element.type = "button";
     }
-    actionElement.className = "k2b-toast__action";
-    actionElement.textContent = action.label;
-    actionElement.addEventListener("click", event => {
-      event.stopPropagation();
+    element.className = "k2b-toast__action";
+    element.textContent = action.label;
+    element.addEventListener("click", () => {
       if ("onClick" in action) action.onClick();else dismiss();
     });
-    contentElement.appendChild(actionElement);
+    return element;
+  };
+  const renderAction = action => {
+    const previous = actionElement;
+    currentAction = action ?? null;
+    actionElement = action ? createAction(action) : null;
+    if (actionElement) contentElement.appendChild(actionElement);
+    // The keyboard stays in the toast, on the new action or the close button, instead of falling to the page.
+    if (previous?.contains(doc.activeElement)) (actionElement ?? closeButton).focus({
+      preventScroll: true
+    });
+    previous?.remove();
   };
   renderAction(options?.action);
   const update = (nextDescription, nextOptions) => {
     if (dismissed) return;
+    const has = key => nextOptions !== undefined && Object.prototype.hasOwnProperty.call(nextOptions, key);
+    const previousProgress = currentProgress;
     descriptionElement.textContent = nextDescription;
     const variantChanged = nextOptions?.variant !== undefined && nextOptions.variant !== currentVariant;
     if (variantChanged) {
       currentVariant = nextOptions.variant;
       toastElement.dataset.tone = VARIANT_STYLES[currentVariant].tone;
-      leadIconElement = renderLead(leadElement, currentVariant, nextOptions.iconClass);
-      applyLiveRegion(contentElement, currentVariant);
+      renderLead(nextOptions.iconClass);
     } else if (nextOptions?.iconClass !== undefined) {
       applyIconClass(leadIconElement, nextOptions.iconClass);
     }
-    if (nextOptions && Object.prototype.hasOwnProperty.call(nextOptions, "title")) {
-      titleElement.textContent = nextOptions.title ?? "";
-    } else if (variantChanged) {
-      titleElement.textContent = defaultTitle(currentVariant);
-    }
-    if (nextOptions && Object.prototype.hasOwnProperty.call(nextOptions, "action")) renderAction(nextOptions.action);
-    if (nextOptions && Object.prototype.hasOwnProperty.call(nextOptions, "duration")) {
-      currentDuration = nextOptions.duration ?? DEFAULT_DURATION_MS;
-    }
-    if (nextOptions && Object.prototype.hasOwnProperty.call(nextOptions, "progress")) currentProgress = nextOptions.progress ?? null;
+    if (has("title")) renderTitle(nextOptions.title);
+    if (has("action")) renderAction(nextOptions.action);
+    if (has("duration")) explicitDuration = nextOptions.duration;
+    if (has("progress")) currentProgress = nextOptions.progress ?? null;
     if (nextOptions?.dismissLabel) closeButton.setAttribute("aria-label", nextOptions.dismissLabel);
     renderProgress();
-    resetDismissTimer(currentDuration);
+    resetDismissTimer();
+
+    // Progress is announced at its start, half way, and its end, never at every step, and only with something new to say.
+    // The comparison includes the error word, so a change to an error with the same text is still announced.
+    const ticking = previousProgress !== null && currentProgress !== null;
+    const halfway = typeof currentProgress === "number" && currentProgress >= 0.5 && !(typeof previousProgress === "number" && previousProgress >= 0.5);
+    if ((!ticking || halfway || variantChanged) && spoken() !== lastAnnouncement) say();
+    // Finished progress or a new duration can make this toast one the rail limit removes.
+    enforceCap();
   };
-  toastElement.addEventListener("click", () => {
-    if (currentProgress === null) dismiss();
-  });
-  closeButton.addEventListener("click", event => {
+  closeButton.addEventListener("click", () => dismiss());
+  toastElement.addEventListener("keydown", event => {
+    if (event.key !== "Escape" || event.defaultPrevented) return;
+    event.preventDefault();
     event.stopPropagation();
     dismiss();
   });
-  toastElement.addEventListener("pointerenter", () => {
-    pausedByPointer = true;
-    pauseDismissTimer();
-  });
-  toastElement.addEventListener("pointerleave", () => {
-    pausedByPointer = false;
-    resumeDismissTimer();
-  });
-  toastElement.addEventListener("focusin", () => {
-    pausedByFocus = true;
-    pauseDismissTimer();
-  });
-  toastElement.addEventListener("focusout", event => {
-    if (toastElement.contains(event.relatedTarget)) return;
-    pausedByFocus = false;
-    resumeDismissTimer();
-  });
+  doc.addEventListener("visibilitychange", onVisibilityChange);
   const handle = {
     dismiss,
     update
   };
-  liveToasts.add(handle);
-  if (liveToasts.size > MAX_VISIBLE_TOASTS) liveToasts.values().next().value?.dismiss();
-  promoteToTopLayer(initialContainer).appendChild(toastElement);
-  requestAnimationFrame(() => {
-    if (!dismissed) toastElement.dataset.open = "true";
-  });
-  resetDismissTimer(currentDuration);
+  const live = {
+    dismiss,
+    keep: () => currentVariant === "error" || currentProgress !== null || effectiveDuration() === 0,
+    progress: () => currentProgress !== null,
+    held: () => pointerHolds.has(toastElement) || focusHolds.has(toastElement),
+    pause: pauseDismissTimer,
+    resume: resumeDismissTimer
+  };
+  liveToasts.add(live);
+  promoteToTopLayer(initialContainer).appendChild(item.slot);
+  item.open();
+  say();
+  enforceCap();
+  resetDismissTimer();
   return handle;
 };
+
+/*
+ * A custom slot shares the rail, chrome, and enter/leave motion with toasts, so it stacks beside them in the same
+ * corner instead of covering them. It has no timer, close button, or live region of its own, and neither the
+ * toast limit nor `dismissAll` removes it: the application that placed it decides when it goes.
+ */
+const showCustom = content => {
+  const initialContainer = ensureContainer();
+  if (!initialContainer) return {
+    dismiss: () => {}
+  };
+  let dismissed = false;
+  const slotElement = document.createElement("div");
+  slotElement.className = "k2b-toast";
+  slotElement.dataset.k2bToast = "";
+  slotElement.dataset.custom = "true";
+  slotElement.append(content);
+  const item = railItem(slotElement);
+  const dismiss = () => {
+    if (dismissed) return;
+    dismissed = true;
+    item.close();
+  };
+  promoteToTopLayer(initialContainer).appendChild(item.slot);
+  item.open();
+  return {
+    dismiss
+  };
+};
 export const isPointInsideToast = (x, y) => {
   if (typeof document === "undefined") return false;
-  const containers = Array.from(document.querySelectorAll(`[${CONTAINER_ATTRIBUTE}]`));
-  for (const container of containers) {
-    for (const child of Array.from(container.children)) {
-      const rect = child.getBoundingClientRect();
-      if (x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom) return true;
-    }
+  for (const card of Array.from(document.querySelectorAll(`[${CONTAINER_ATTRIBUTE}] [data-k2b-toast]`))) {
+    const rect = card.getBoundingClientRect();
+    if (x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom) return true;
   }
   return false;
 };
@@ -293,8 +533,9 @@ toastFn.error = (description, options) => showToast(description, {
   ...options,
   variant: "error"
 });
+toastFn.custom = showCustom;
 toastFn.dismissAll = () => {
-  for (const handle of Array.from(liveToasts)) handle.dismiss();
+  for (const item of Array.from(liveToasts)) item.dismiss();
 };
 export const toast = toastFn;
 //# sourceMappingURL=toast.js.map