@jungherz-de/notionkit-elements 1.18.0 → 1.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jungherz-de/notionkit-elements",
-  "version": "1.18.0",
+  "version": "1.20.0",
   "description": "Vanilla JavaScript Web Components wrapping the NotionKit CSS foundation – <nk-*> custom elements with Shadow DOM, automatic theme sync and native form participation.",
   "license": "MIT",
   "author": "Jungherz GmbH <info@jungherz.com> (https://www.jungherz.com)",
@@ -63,10 +63,10 @@
     "dark-mode"
   ],
   "peerDependencies": {
-    "@jungherz-de/notionkit": ">=1.18.0"
+    "@jungherz-de/notionkit": ">=1.20.0"
   },
   "devDependencies": {
-    "@jungherz-de/notionkit": "^1.18.0",
+    "@jungherz-de/notionkit": "^1.20.0",
     "@playwright/test": "^1.50.0",
     "@rollup/plugin-node-resolve": "^15.0.0",
     "@rollup/plugin-terser": "^0.4.0",

package/src/components/forms/nk-calendar.js

@@ -2,6 +2,7 @@ import { NkFormElement } from '../../base.js';
 import { isoOf, parseDay, addDays, isoWeek, resolveLocale, firstWeekday, weekdayNames, monthGrid, stepMonth, weekLabel, CHEVRONS } from '../../util/dates.js';
 import { placeUnder } from '../../util/floating.js';
 import { deepActiveElement } from '../../util/focus.js';
+import { openLayer, closeLayer } from '../../util/layers.js';
 
 // <nk-calendar name="due" value="2026-06-02" weeks weekend="6,0"></nk-calendar>
 // <nk-calendar range value="2026-06-08/2026-06-12"></nk-calendar>
@@ -271,14 +272,13 @@ class NkCalendar extends NkFormElement {
       this._draw();
       this.emit('nk-change', { value: '', start: null, end: null, time: null });
     };
-    // Floating: a tap outside closes it and reaches nothing else; Escape closes (captured, before a modal around it).
+    // Floating: a tap outside closes it and reaches nothing else; Escape closes it, before a dialog around it (util/layers.js).
     this._onOutside = (e) => {
       const path = e.composedPath();
       if (path.includes(this) || (this._anchor && path.includes(this._anchor))) return;
       e.preventDefault(); e.stopPropagation();
       this.close();
     };
-    this._onEscape = (e) => { if (e.key === 'Escape' && this.getBoolAttr('floating') && this.getBoolAttr('open')) { e.stopPropagation(); this.close(); } };
     this._grid.addEventListener('click', this._onGrid);
     this._grid.addEventListener('keydown', this._onKey);
     this._todayBtn.addEventListener('click', this._onToday);
@@ -286,7 +286,6 @@ class NkCalendar extends NkFormElement {
     this._next.addEventListener('click', this._onNext);
     this._timeInput.addEventListener('change', this._onTime);
     this._clear.addEventListener('click', this._onClear);
-    document.addEventListener('keydown', this._onEscape, true);
     if (this.getBoolAttr('open')) document.addEventListener('click', this._onOutside, true);
   }
 
@@ -298,7 +297,7 @@ class NkCalendar extends NkFormElement {
     this._next?.removeEventListener('click', this._onNext);
     this._timeInput?.removeEventListener('change', this._onTime);
     this._clear?.removeEventListener('click', this._onClear);
-    document.removeEventListener('keydown', this._onEscape, true);
+    closeLayer(this);
     document.removeEventListener('click', this._onOutside, true);
   }
 
@@ -322,7 +321,9 @@ class NkCalendar extends NkFormElement {
       this._returnFocus = deepActiveElement();
       if (this._returnFocus?.matches(':focus-visible')) requestAnimationFrame(() => this.focusDay());
       document.addEventListener('click', this._onOutside, true);
+      if (this.getBoolAttr('floating')) openLayer(this, () => this.close());
     } else {
+      closeLayer(this);
       document.removeEventListener('click', this._onOutside, true);
       const back = this._returnFocus;
       this._returnFocus = null;

package/src/components/overlays/nk-cmdk.js

@@ -1,5 +1,6 @@
 import { NkElement } from '../../base.js';
-import { lockScroll, unlockScroll, inertOutside } from '../../util/focus.js';
+import { lockScroll, unlockScroll, inertOutside, deepActiveElement } from '../../util/focus.js';
+import { openLayer, closeLayer } from '../../util/layers.js';
 import { fuzzyScore } from '../../util/fuzzy.js';
 
 // <nk-cmdk id="palette" placeholder="Search or type a command …"></nk-cmdk>
@@ -133,14 +134,16 @@ class NkCmdk extends NkElement {
     if (open === this._wasOpen) return;
     this._wasOpen = open;
     if (open) {
-      this._returnFocus = document.activeElement;
+      this._returnFocus = deepActiveElement();
       this._input.value = '';
       this._index = 0;
       this._renderList();
       lockScroll();
       this._undoInert = inertOutside(this);
+      openLayer(this, () => this.close());
       requestAnimationFrame(() => this._input.focus({ preventScroll: true }));
     } else {
+      closeLayer(this);
       unlockScroll();
       this._undoInert?.(); this._undoInert = null;
       const back = this._returnFocus;
@@ -151,8 +154,7 @@ class NkCmdk extends NkElement {
 
   setupEvents() {
     this._onDocKey = (e) => {
-      if (this._matchesHotkey(e)) { e.preventDefault(); this.toggle(); return; }
-      if (e.key === 'Escape' && this.getBoolAttr('open')) { e.stopPropagation(); this.close(); }
+      if (this._matchesHotkey(e)) { e.preventDefault(); this.toggle(); }
     };
     this._onInput = () => { this._index = 0; this._renderList(); };
     this._onInputKey = (e) => {
@@ -181,7 +183,7 @@ class NkCmdk extends NkElement {
     this._list?.removeEventListener('mousemove', this._onListMove);
     this._list?.removeEventListener('mousedown', this._onListDown);
     this._backdrop?.removeEventListener('click', this._onBackdrop);
-    if (this._wasOpen) { unlockScroll(); this._undoInert?.(); this._undoInert = null; this._wasOpen = false; }
+    if (this._wasOpen) { closeLayer(this); unlockScroll(); this._undoInert?.(); this._undoInert = null; this._wasOpen = false; }
   }
 
   onAttributeChanged(name) {

package/src/components/overlays/nk-dialog.js

@@ -1,5 +1,6 @@
 import { NkElement } from '../../base.js';
 import { lockScroll, unlockScroll, inertOutside, firstFocusable, deepActiveElement } from '../../util/focus.js';
+import { openLayer, closeLayer } from '../../util/layers.js';
 
 // <nk-dialog id="trash" title="Move “Roadmap” to trash?" alert>
 //   The page and its sub-pages can be restored from Trash for 30 days.
@@ -79,8 +80,10 @@ class NkDialog extends NkElement {
       this.inert = false;
       lockScroll();
       this._undoInert = inertOutside(this);
+      openLayer(this, () => this.close(''));
       requestAnimationFrame(() => (this.querySelector('[autofocus]') || firstFocusable(this) || this._box).focus({ preventScroll: true }));
     } else {
+      closeLayer(this);
       unlockScroll();
       this._undoInert?.(); this._undoInert = null;
       this.inert = this._wasInert;
@@ -92,7 +95,6 @@ class NkDialog extends NkElement {
 
   setupEvents() {
     this._onBackdrop = (e) => { if (e.target === this._backdrop) this.close(''); };
-    this._onKey = (e) => { if (e.key === 'Escape' && this.getBoolAttr('open')) { e.stopPropagation(); this.close(''); } };
     // A button in the actions with a value closes it, and one with data-close
     // anywhere inside; a submit button is the form's.
     this._onClick = (e) => {
@@ -112,7 +114,6 @@ class NkDialog extends NkElement {
     this.addEventListener('click', this._onClick);
     this.addEventListener('submit', this._onSubmit);
     this._actionsSlot.addEventListener('slotchange', this._onSlot);
-    document.addEventListener('keydown', this._onKey, true);
     this._onSlot();
   }
 
@@ -121,8 +122,7 @@ class NkDialog extends NkElement {
     this.removeEventListener('click', this._onClick);
     this.removeEventListener('submit', this._onSubmit);
     this._actionsSlot?.removeEventListener('slotchange', this._onSlot);
-    document.removeEventListener('keydown', this._onKey, true);
-    if (this._wasOpen) { unlockScroll(); this._undoInert?.(); this._undoInert = null; this._wasOpen = false; }
+    if (this._wasOpen) { closeLayer(this); unlockScroll(); this._undoInert?.(); this._undoInert = null; this._wasOpen = false; }
   }
 
   onAttributeChanged(name, oldValue, value) {

package/src/components/overlays/nk-menu.js

@@ -1,5 +1,6 @@
 import { NkElement } from '../../base.js';
-import { deepActiveElement } from '../../util/focus.js';
+import { deepActiveElement, containsDeep } from '../../util/focus.js';
+import { openLayer, closeLayer } from '../../util/layers.js';
 import { placeUnder } from '../../util/floating.js';
 
 // <nk-menu>
@@ -48,15 +49,30 @@ class NkMenu extends NkElement {
       this._returnFocus = deepActiveElement();
       if (this._returnFocus?.matches(':focus-visible')) requestAnimationFrame(() => this.focusFirst());
       document.addEventListener('click', this._onOutside, true);
+      if (this.getBoolAttr('floating')) { openLayer(this, () => this.close()); this._scrollToStart(); }
     } else {
+      closeLayer(this);
       document.removeEventListener('click', this._onOutside, true);
       const back = this._returnFocus;
       this._returnFocus = null;
-      if (back?.isConnected && this.contains(document.activeElement)) back.focus({ preventScroll: true });
+      // The focus behind shadow hosts: document.activeElement stops at the
+      // host of a view that holds the menu (1.19.0).
+      const active = deepActiveElement();
+      if (back?.isConnected && active && (containsDeep(this, active) || active === document.body)) back.focus({ preventScroll: true });
     }
     this.emit('nk-toggle', { open });
   }
 
+  // A long menu opens at its top again, or at its first checked item (1.19.0):
+  // it kept where it had been scrolled to, its heading out of sight.
+  _scrollToStart() {
+    this._box.scrollTop = 0;
+    const item = this.items.find(i => i.hasAttribute('checked'))?.shadowRoot?.querySelector('.nk-menu-item');
+    if (!item) return;
+    const box = this._box.getBoundingClientRect(), r = item.getBoundingClientRect();
+    if (r.bottom > box.bottom) this._box.scrollTop += r.top - box.top - (box.height - r.height) / 2;
+  }
+
   /** Opens under `anchor` (any element, display: contents hosts included). */
   show(anchor) {
     if (anchor) {
@@ -94,17 +110,14 @@ class NkMenu extends NkElement {
       e.preventDefault(); e.stopPropagation();
       this.close();
     };
-    // Captured, so a menu inside a modal or sheet closes before they do.
-    this._onEscape = (e) => { if (e.key === 'Escape' && this.getBoolAttr('floating') && this.getBoolAttr('open')) { e.stopPropagation(); this.close(); } };
     this._onSelect = () => { if (this.getBoolAttr('floating')) this.close(); };
-    document.addEventListener('keydown', this._onEscape, true);
     this.addEventListener('nk-select', this._onSelect);
     if (this.getBoolAttr('open')) document.addEventListener('click', this._onOutside, true);
   }
 
   teardownEvents() {
     this.removeEventListener('keydown', this._onKey);
-    document.removeEventListener('keydown', this._onEscape, true);
+    closeLayer(this);
     this.removeEventListener('nk-select', this._onSelect);
     document.removeEventListener('click', this._onOutside, true);
   }

package/src/components/overlays/nk-modal.js

@@ -1,5 +1,6 @@
 import { NkElement } from '../../base.js';
-import { lockScroll, unlockScroll, inertOutside, firstFocusable } from '../../util/focus.js';
+import { lockScroll, unlockScroll, inertOutside, firstFocusable, deepActiveElement } from '../../util/focus.js';
+import { openLayer, closeLayer } from '../../util/layers.js';
 
 // <nk-modal id="settings">
 //   <nk-settings-user slot="user" name="…" mail="…"></nk-settings-user>
@@ -93,14 +94,17 @@ class NkModal extends NkElement {
     if (open === this._wasOpen) return;
     this._wasOpen = open;
     if (open) {
-      this._returnFocus = document.activeElement;
+      // Behind shadow hosts too: a trigger in a view's shadow root gets the focus back.
+      this._returnFocus = deepActiveElement();
       lockScroll();
       this._undoInert = inertOutside(this);
+      openLayer(this, () => this.close());
       requestAnimationFrame(() => {
         const target = this._rows.querySelector('.nk-tree-item.active') || firstFocusable(this) || this._box;
         target.focus({ preventScroll: true });
       });
     } else {
+      closeLayer(this);
       unlockScroll();
       this._undoInert?.(); this._undoInert = null;
       const back = this._returnFocus;
@@ -111,7 +115,6 @@ class NkModal extends NkElement {
 
   setupEvents() {
     this._onBackdrop = (e) => { if (e.target === this._backdrop) this.close(); };
-    this._onKey = (e) => { if (e.key === 'Escape' && this.getBoolAttr('open')) { e.stopPropagation(); this.close(); } };
     this._onNavClick = (e) => { const row = e.target.closest('[data-pane]'); if (row) { row.focus(); this.pane = row.dataset.pane; } };
     this._onNavKey = (e) => {
       const row = e.target.closest?.('[data-pane]');
@@ -125,7 +128,6 @@ class NkModal extends NkElement {
     };
     this._onSlot = () => this.requestNav();
     this._backdrop.addEventListener('click', this._onBackdrop);
-    document.addEventListener('keydown', this._onKey);
     this._rows.addEventListener('click', this._onNavClick);
     this._rows.addEventListener('keydown', this._onNavKey);
     this._slot.addEventListener('slotchange', this._onSlot);
@@ -133,11 +135,10 @@ class NkModal extends NkElement {
 
   teardownEvents() {
     this._backdrop?.removeEventListener('click', this._onBackdrop);
-    document.removeEventListener('keydown', this._onKey);
     this._rows?.removeEventListener('click', this._onNavClick);
     this._rows?.removeEventListener('keydown', this._onNavKey);
     this._slot?.removeEventListener('slotchange', this._onSlot);
-    if (this._wasOpen) { unlockScroll(); this._undoInert?.(); this._undoInert = null; this._wasOpen = false; }
+    if (this._wasOpen) { closeLayer(this); unlockScroll(); this._undoInert?.(); this._undoInert = null; this._wasOpen = false; }
   }
 
   onStringsChanged() { this._nav.setAttribute('aria-label', this.str('settings')); }

package/src/components/overlays/nk-peek.js

@@ -1,5 +1,6 @@
 import { NkElement } from '../../base.js';
 import { lockScroll, unlockScroll, inertOutside, deepActiveElement } from '../../util/focus.js';
+import { openLayer, closeLayer } from '../../util/layers.js';
 
 // <nk-peek id="peek" label="Database Table-View">
 //   <nk-btn slot="actions" variant="topbar" aria-label="Open as page"><svg …></svg></nk-btn>
@@ -108,8 +109,10 @@ class NkPeek extends NkElement {
         lockScroll();
         this._undoInert = inertOutside(this);
       }
+      openLayer(this, () => this.close());
       requestAnimationFrame(() => this._box.focus({ preventScroll: true }));
     } else {
+      closeLayer(this);
       if (this._modal) { this._modal = false; this._box.removeAttribute('aria-modal'); unlockScroll(); this._undoInert?.(); this._undoInert = null; }
       const active = deepActiveElement();
       const inside = active && (this.contains(active) || this._shadow.contains(active) || active === document.body);
@@ -122,7 +125,6 @@ class NkPeek extends NkElement {
   setupEvents() {
     this._onClose = () => this.close();
     this._onBackdrop = (e) => { if (e.target === this._backdrop) this.close(); };
-    this._onKey = (e) => { if (e.key === 'Escape' && this.getBoolAttr('open')) this.close(); };
     // Bubble phase, after the page's own handlers: a click that showed the
     // peek again (another row) must not close it.
     this._onOutside = (e) => {
@@ -156,7 +158,6 @@ class NkPeek extends NkElement {
     this._handle.addEventListener('pointermove', this._onResizeMove);
     this._handle.addEventListener('lostpointercapture', this._onResizeEnd);
     this._handle.addEventListener('keydown', this._onResizeKey);
-    document.addEventListener('keydown', this._onKey);
     document.addEventListener('click', this._onOutside);
     addEventListener('resize', this._onViewport);
   }
@@ -168,7 +169,7 @@ class NkPeek extends NkElement {
     this._handle?.removeEventListener('pointermove', this._onResizeMove);
     this._handle?.removeEventListener('lostpointercapture', this._onResizeEnd);
     this._handle?.removeEventListener('keydown', this._onResizeKey);
-    document.removeEventListener('keydown', this._onKey);
+    closeLayer(this);
     document.removeEventListener('click', this._onOutside);
     removeEventListener('resize', this._onViewport);
     if (this._insetApp) { this._app()?.removeAttribute('peek-inset'); this._insetApp = false; }

package/src/components/overlays/nk-pop.js

@@ -1,4 +1,5 @@
 import { NkElement } from '../../base.js';
+import { openLayer, closeLayer } from '../../util/layers.js';
 
 // <nk-pop placement="bottom-start">
 //   <nk-btn slot="trigger" variant="secondary">Options</nk-btn>
@@ -48,12 +49,10 @@ class NkPop extends NkElement {
       this.toggle();
     };
     this._onDocClick = (e) => { if (this.getBoolAttr('open') && !e.composedPath().includes(this)) this.close(); };
-    this._onKey = (e) => { if (e.key === 'Escape' && this.getBoolAttr('open')) this.close(); };
     this._onSelect = (e) => { if (e.target !== this) this.close(); };
     this._onSlot = () => this._syncSurface();
     this.addEventListener('click', this._onTrigger);
     document.addEventListener('click', this._onDocClick);
-    document.addEventListener('keydown', this._onKey);
     this._float.addEventListener('nk-select', this._onSelect);
     this._slot.addEventListener('slotchange', this._onSlot);
   }
@@ -61,7 +60,7 @@ class NkPop extends NkElement {
   teardownEvents() {
     this.removeEventListener('click', this._onTrigger);
     document.removeEventListener('click', this._onDocClick);
-    document.removeEventListener('keydown', this._onKey);
+    closeLayer(this);
     this._float?.removeEventListener('nk-select', this._onSelect);
     this._slot?.removeEventListener('slotchange', this._onSlot);
   }
@@ -70,6 +69,7 @@ class NkPop extends NkElement {
     if (name === 'bare') this._syncSurface();
     if (name === 'open') {
       const open = this.getBoolAttr('open');
+      if (open) openLayer(this, () => this.close()); else closeLayer(this);
       for (const el of this._triggerSlot.assignedElements()) el.setAttribute('aria-expanded', open ? 'true' : 'false');
       this.emit('nk-toggle', { open });
     }

package/src/components/overlays/nk-sheet.js

@@ -1,5 +1,6 @@
 import { NkElement } from '../../base.js';
 import { lockScroll, unlockScroll, inertOutside, firstFocusable, deepActiveElement } from '../../util/focus.js';
+import { openLayer, closeLayer } from '../../util/layers.js';
 
 // <nk-sheet id="more" title="More">
 //   <nk-tree manual>
@@ -52,8 +53,10 @@ class NkSheet extends NkElement {
       this._returnFocus = deepActiveElement();
       lockScroll();
       this._undoInert = inertOutside(this);
+      openLayer(this, () => this.close());
       requestAnimationFrame(() => (firstFocusable(this) || this._box).focus({ preventScroll: true }));
     } else {
+      closeLayer(this);
       unlockScroll();
       this._undoInert?.(); this._undoInert = null;
       const back = this._returnFocus;
@@ -64,15 +67,12 @@ class NkSheet extends NkElement {
 
   setupEvents() {
     this._onBackdrop = (e) => { if (e.target === this._backdrop) this.close(); };
-    this._onKey = (e) => { if (e.key === 'Escape' && this.getBoolAttr('open')) { e.stopPropagation(); this.close(); } };
     this._backdrop.addEventListener('click', this._onBackdrop);
-    document.addEventListener('keydown', this._onKey);
   }
 
   teardownEvents() {
     this._backdrop?.removeEventListener('click', this._onBackdrop);
-    document.removeEventListener('keydown', this._onKey);
-    if (this._wasOpen) { unlockScroll(); this._undoInert?.(); this._undoInert = null; this._wasOpen = false; }
+    if (this._wasOpen) { closeLayer(this); unlockScroll(); this._undoInert?.(); this._undoInert = null; this._wasOpen = false; }
   }
 
   onAttributeChanged(name, oldValue, value) {

package/src/components/overlays/nk-toast.js

@@ -1,11 +1,21 @@
 import { NkElement } from '../../base.js';
+import { deepActiveElement, containsDeep } from '../../util/focus.js';
 
 // <nk-toast id="toast"></nk-toast>   …   toast.show('Saved');
-// → <div class="nk-toast show">✓ Saved</div>
+// toast.show('Moved to trash', { action: { label: 'Undo', value: 'undo' } });
+// → <div class="nk-toast show">✓ Moved to trash<button class="t-action">Undo</button><button class="t-close">×</button></div>
 // One node, bottom-centred, auto-hides after `duration` ms (default 2200).
 // Above a tab bar at the bottom of the screen it rises 12px over the bar:
 // notionkit.css does that for class markup with :has(), which cannot see
 // into shadow roots, so the element measures the bar when it opens.
+// An action (1.19.0) – from show() or a <button slot="action"> – makes it
+// Notion's "Moved to trash · Undo": a button, and an × that closes. Such a
+// toast stays until one of them is used, unless show() names a duration,
+// and waits while the pointer or the focus is on it. The action fires
+// nk-action { action, value, label } and, unless cancelled, closes it;
+// Escape closes it while the focus is inside.
+const CLOSE_ICON = '<svg viewBox="0 0 24 24" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg>';
+
 class NkToast extends NkElement {
   static get observedAttributes() { return ['open', 'duration', 'icon']; }
 
@@ -13,19 +23,37 @@ class NkToast extends NkElement {
     this._box = this.createElement('div', ['nk-toast'], { role: 'status', 'aria-live': 'polite' });
     this._icon = document.createElement('span');
     this._msg = document.createElement('span');
-    this._box.append(this._icon, this._msg, document.createElement('slot'));
+    this._action = this.createElement('button', ['t-action'], { type: 'button' });
+    this._actionSlot = this.createElement('slot', [], { name: 'action' });
+    this._close = this.createElement('button', ['t-close'], { type: 'button' });
+    this._close.innerHTML = CLOSE_ICON;
+    this._box.append(this._icon, this._msg, document.createElement('slot'), this._actionSlot);
     this._wrapper.appendChild(this._box);
     this._sync();
   }
 
   _sync() {
-    if (this.getBoolAttr('open')) this._lift();
-    this._box.classList.toggle('show', this.getBoolAttr('open'));
+    const open = this.getBoolAttr('open');
+    if (open) this._lift();
+    this._box.classList.toggle('show', open);
     const icon = this.getAttribute('icon') ?? '✓';
     this._icon.textContent = icon;
     this._icon.style.display = icon ? '' : 'none';
+    // An empty message takes no place – with slotted text it added a second gap.
+    this._msg.style.display = this._msg.textContent ? '' : 'none';
+    // The action from show() and the × sit in the tree only when there is an
+    // action; a closed toast keeps them for its fade, out of the tab order.
+    const own = this._act, slotted = this._slotted();
+    if (own) { this._action.textContent = own.label; if (!this._action.isConnected) this._actionSlot.before(this._action); }
+    else this._action.remove();
+    if (own || slotted) { if (!this._close.isConnected) this._box.appendChild(this._close); }
+    else this._close.remove();
+    this._close.setAttribute('aria-label', this.str('close'));
+    for (const b of [this._action, this._close]) open ? b.removeAttribute('tabindex') : b.setAttribute('tabindex', '-1');
   }
 
+  _slotted() { return this._actionSlot?.assignedElements()[0] ?? null; }
+
   // A bar counts when it is rendered and ends near the bottom of the viewport –
   // the app's own bar, fixed, sticky or floating. A tab bar shown as a preview
   // somewhere in a page does not lift the toast.
@@ -40,16 +68,83 @@ class NkToast extends NkElement {
     this._box.style.bottom = rect ? `${Math.round(innerHeight - rect.top + 12)}px` : '';
   }
 
-  /** Shows `message` (or the slotted content when omitted) and hides it again after `duration`. */
-  show(message, { duration } = {}) {
+  /**
+   * Shows `message` (or the slotted content when omitted) and hides it again
+   * after `duration` ms – the attribute's, else 2200; with an `action`
+   * ({ label, value }) it stays until the action or the × is used.
+   */
+  show(message, { duration, action } = {}) {
     if (message !== undefined) this._msg.textContent = message;
+    this._shown = (this._shown ?? 0) + 1;
+    this._act = action ? { label: String(action.label ?? action.value ?? ''), value: action.value ?? action.label } : null;
+    const attr = this.getAttribute('duration'), set = attr !== null && attr.trim() !== '' && Number.isFinite(Number(attr));
+    // Number(null) is 0: without the attribute a toast used to stay for good.
+    this._ms = duration ?? (this._act || this._slotted() ? 0 : set ? Number(attr) : 2200);
+    if (this.getBoolAttr('open')) this._sync(); else this.setBoolAttr('open', true);
+    this._arm();
+  }
+
+  close() {
     clearTimeout(this._timer);
-    this.setBoolAttr('open', true);
-    const ms = duration ?? Number(this.getAttribute('duration')) ?? 2200;
-    if (ms > 0) this._timer = setTimeout(() => this.close(), ms || 2200);
+    // The focus leaves with the toast, back to where it came from.
+    const active = deepActiveElement();
+    if (active && containsDeep(this, active)) {
+      this._from?.isConnected && this._from.focus({ preventScroll: true });
+      if (containsDeep(this, deepActiveElement())) active.blur();
+    }
+    this._from = null;
+    this.setBoolAttr('open', false);
   }
 
-  close() { clearTimeout(this._timer); this.setBoolAttr('open', false); }
+  _arm() {
+    clearTimeout(this._timer);
+    if (this._ms > 0 && !this._held && this.getBoolAttr('open')) this._timer = setTimeout(() => this.close(), this._ms);
+  }
+
+  _take(act) {
+    if (!act) return;
+    // A handler that shows the next message – "Restored" – keeps it open.
+    const shown = this._shown;
+    if (this.emit('nk-action', { action: act.value, value: act.value, label: act.label }) && this._shown === shown) this.close();
+  }
+
+  setupEvents() {
+    this._onClick = (e) => {
+      const path = e.composedPath();
+      if (path.includes(this._close)) { this.close(); return; }
+      if (path.includes(this._action)) { this._take(this._act); return; }
+      const slotted = this._slotted();
+      if (slotted && path.includes(slotted)) this._take({ value: slotted.value || slotted.getAttribute('value') || slotted.textContent.trim(), label: slotted.textContent.trim() });
+    };
+    // While the pointer or the focus is on it, a toast with a duration waits.
+    this._onHold = (e) => {
+      if (e.type === 'focusin' && !this._from) this._from = e.relatedTarget ?? null;
+      this._held = true; clearTimeout(this._timer);
+    };
+    this._onRelease = (e) => {
+      if (e.relatedTarget && containsDeep(this, e.relatedTarget)) return;
+      this._held = false; this._arm();
+    };
+    this._onKey = (e) => { if (e.key === 'Escape') { e.stopPropagation(); this.close(); } };
+    this._onSlot = () => this._sync();
+    this._box.addEventListener('click', this._onClick);
+    this._box.addEventListener('pointerover', this._onHold);
+    this._box.addEventListener('pointerout', this._onRelease);
+    this._box.addEventListener('focusin', this._onHold);
+    this._box.addEventListener('focusout', this._onRelease);
+    this._box.addEventListener('keydown', this._onKey);
+    this._actionSlot.addEventListener('slotchange', this._onSlot);
+  }
+
+  teardownEvents() {
+    this._box?.removeEventListener('click', this._onClick);
+    this._box?.removeEventListener('pointerover', this._onHold);
+    this._box?.removeEventListener('pointerout', this._onRelease);
+    this._box?.removeEventListener('focusin', this._onHold);
+    this._box?.removeEventListener('focusout', this._onRelease);
+    this._box?.removeEventListener('keydown', this._onKey);
+    this._actionSlot?.removeEventListener('slotchange', this._onSlot);
+  }
 
   onAttributeChanged(name) {
     this._sync();
@@ -61,7 +156,8 @@ class NkToast extends NkElement {
   get open() { return this.getBoolAttr('open'); }
   set open(v) { this.setBoolAttr('open', v); }
   get message() { return this._msg?.textContent ?? ''; }
-  set message(v) { if (this._msg) this._msg.textContent = v; }
+  set message(v) { if (this._msg) { this._msg.textContent = v; this._sync(); } }
+  onStringsChanged() { if (this._box) this._sync(); }
 }
 
 customElements.define('nk-toast', NkToast);