@jungherz-de/notionkit-elements 1.18.0 → 1.20.0

package/CHANGELOG.md

@@ -4,6 +4,52 @@ All notable changes to NotionKit Elements are documented here. The format follow
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [1.20.0] – 2026-10-12
+
+Built against NotionKit CSS 1.20.0 (peer `>= 1.20.0`).
+
+### Added
+- **`<nk-theme-toggle modes="auto light dark">` – a third state that follows
+  the system.** `auto` is what no stored value means, so the documented
+  inline script before first paint keeps working and a choice made without
+  `modes` still counts; while it is in force the element follows
+  `prefers-color-scheme` live, which the toggle never did. A click goes from
+  `auto` to the theme *not* on screen, then to the other one, then back, so
+  every click but the last changes something visibly. The glyph shows the
+  mode – `.nk-theme-glyph`, sun and moon diagonally for `auto` – instead of
+  the next theme, and the title names the mode and the next step (four new
+  texts: `appearance`, `themeAuto`, `themeLight`, `themeDark`). A choice made
+  in another tab arrives through the `storage` event. `value` returns
+  `auto | light | dark`, the new `theme` what is on screen, `nk-change`
+  reports both; `nextMode()` and `themeFor(mode)` are public.
+  **Two states stay the default**, where nothing about this element changes.
+  Requested by Mailverse (#2).
+- `theme-color` keeps `<meta name="theme-color">` in step: while a theme is
+  fixed every bar carries that theme's colour, back on `auto` each one
+  carries its own again. The colours are the page's, never invented.
+
+### Fixed
+- The toggle added its system-preference listener to a throwaway
+  `matchMedia()` object and removed it from a second one, so it was never
+  released and could be collected with its query. One query per element now.
+- A mode whose write failed (Safari's private mode refuses to store but
+  reads) is kept in the element until the page reloads, instead of falling
+  back to `auto` on the next read.
+
+## [1.19.0] – 2026-09-25
+
+Built against NotionKit CSS 1.19.1 (peer `>= 1.19.1`). Auxdesk's wish 24 and what SupaGantt's mock-ups found – 14, 15 and 16 – together with a toast that never hid.
+
+### Added
+- **`<nk-toast>` with an action.** `toast.show('Moved to trash', { action: { label: 'Undo', value: 'undo' } })`, or a `<button slot="action">`, gives the toast a button and an ×, as Notion's "Moved to trash · Undo". 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 the toast – a handler that shows the next message, "Restored", keeps it open; Escape closes it while the focus is inside, and the focus goes back to where it came from (Auxdesk's wish 24, which showed "A new version of Auxdesk · Reload" as a banner under the topbar). The demo's trash toast offers Undo.
+
+### Fixed
+- **A toast without a `duration` attribute hides by itself again.** `show()` read the missing attribute as 0 – "stay" – so every such toast stayed on screen since 1.0.0, the demo's too; the default of 2200ms applies again, and a set attribute or `show()`'s `duration` still win.
+- **Escape closes the layer that opened last.** A floating date picker or menu opened from a `<nk-dialog>` and the dialog both listened for Escape on the document in the capture phase, where `stopPropagation()` does not part them, so one Escape closed both. The overlays – modal, sheet, dialog, side peek, palette, popover, floating menu and date picker – now join one stack while they are open, and Escape goes to its top only; a second one closes the dialog (SupaGantt's finding 15).
+- **The focus goes back into a shadow root.** `<nk-menu>` checked `document.activeElement`, `<nk-modal>` and `<nk-cmdk>` remembered it – both stop at the host of a view that holds the trigger, so the focus ended on `<body>`. They look behind shadow hosts now, like the dialog and the sheet (SupaGantt's finding 14).
+- **A long floating menu opens at its top again** – or with its first checked item in view. It kept the place it had been scrolled to, its heading out of sight (SupaGantt's finding 16).
+- **A toast whose message is empty takes no place**, so static text in its slot no longer stands a second gap away from the icon.
+
 ## [1.18.0] – 2026-09-25
 
 Built against NotionKit CSS 1.18.0 (peer `>= 1.18.0`). What LearnHub and Auxdesk found after their move to 1.17.0: LearnHub's finding 17 and Auxdesk's 26, 27 and 28.
@@ -732,6 +778,8 @@ built and tested against NotionKit CSS 1.1.1 (peer range `>= 1.0.0`).
   import, never in the core bundle – shadow-less, adding `nk-block-host` to
   itself so the foundation's editor adapter rules apply.
 
+[1.20.0]: https://github.com/JUNGHERZ/NotionKit-Elements/releases/tag/v1.20.0
+[1.19.0]: https://github.com/JUNGHERZ/NotionKit-Elements/releases/tag/v1.19.0
 [1.18.0]: https://github.com/JUNGHERZ/NotionKit-Elements/releases/tag/v1.18.0
 [1.17.0]: https://github.com/JUNGHERZ/NotionKit-Elements/releases/tag/v1.17.0
 [1.16.0]: https://github.com/JUNGHERZ/NotionKit-Elements/releases/tag/v1.16.0

package/README.md

@@ -1,11 +1,11 @@
 <h1 align="center">🧩 NotionKit Elements</h1>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/@jungherz-de/notionkit-elements"><img src="https://img.shields.io/badge/version-1.18.0-2383e2?style=flat-square" alt="Version"></a>
+  <a href="https://www.npmjs.com/package/@jungherz-de/notionkit-elements"><img src="https://img.shields.io/badge/version-1.20.0-2383e2?style=flat-square" alt="Version"></a>
   <a href="#"><img src="https://img.shields.io/badge/vanilla_JS-no_dependencies-448361?style=flat-square" alt="Vanilla JS"></a>
   <a href="#"><img src="https://img.shields.io/badge/elements-88-529cca?style=flat-square" alt="88 Elements"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-9065b0?style=flat-square" alt="MIT License"></a>
-  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-v1.18.0-lightgrey?style=flat-square" alt="Changelog"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-v1.20.0-lightgrey?style=flat-square" alt="Changelog"></a>
   <a href="https://www.npmjs.com/package/@jungherz-de/notionkit-elements"><img src="https://img.shields.io/badge/npm-%40jungherz--de%2Fnotionkit--elements-cb3837?style=flat-square&logo=npm" alt="npm"></a>
 </p>
 
@@ -59,7 +59,7 @@ It is the **app layer** of the NotionKit family – three layers, one design lan
 | 🧩 **88 Elements** | Forms with copy field, image picker and date picker, content blocks with bookmarks, app shell & tree with the ☰ drawer and the collapsing sidebar, page shell with properties, panels, avatars and steps, overlays (modal, sheet, dialog, resizable side peek, tooltip, ⌘K palette, menus that float in and become sheets on a phone, popover, emoji picker, toast), database table, board, list, calendar & gallery with toolbar and filter pills, comments, AI thread |
 | 🎛️ **Form participation** | Input, textarea, select, switch, check, radio, slider, segmented and model card work natively with `<form>` via `ElementInternals`; radios group across shadow roots |
 | 🌗 **Theme sync** | One observer mirrors `data-theme` on `<html>` into every element |
-| 🪶 **Lightweight** | 288 KB minified / 58 KB gzipped (IIFE, foundation sheet included), no external dependencies |
+| 🪶 **Lightweight** | 292 KB minified / 59 KB gzipped (IIFE, foundation sheet included), no external dependencies |
 | 📦 **Five bundle shapes** | IIFE, minified IIFE, ESM, minified ESM with a source map (`esm.min.js`), and per-component ESM entries on a stable `base.js`, which import NotionKit's sheet instead of carrying a copy |
 | 🤖 **AI-ready** | `SKILL.md` with copy-paste markup, six app skeletons and the rules – an agent given only that file built a working app in the release test |
 
@@ -71,8 +71,8 @@ It is the **app layer** of the NotionKit family – three layers, one design lan
 <!DOCTYPE html>
 <html lang="en" data-theme="light">
 <head>
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.18.0/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.18.0/dist/notionkit-elements.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.20.0/notionkit.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.20.0/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
   <nk-field label="Display name" desc="Shown next to your comments">
@@ -104,7 +104,7 @@ Without a build step, an import map can point at the minified module instead: `"
 
 Do not mix the full bundle with the per-component files: each brings its own `NkElement`. With the bundle, take `componentsSheet` and `NkElement` from the bundle (`NotionKitElements.componentsSheet` from the `<script>` build).
 
-Two prerequisites, always: `notionkit.css` on the document (the peer dependency, `>= 1.18.0`; 1.18.0 brings a bar and its label in one row, stacked properties that keep to their card on a phone and icons in the copy field, 1.17.0 brings a step's label and a gallery card as links, 1.16.0 brings `--nk-block-space` and `flush` for blocks in a column, keeps a wide progress bar and a stretched button's label in shape and lays floating menus above dialogs, 1.15.0 brings table text with a tone and a second line, 1.14.0 brings the gallery view and a banner action that stands at the right edge again, 1.13.0 keeps fields inside narrow panels, leaves a page without icon its padding under the cover and makes cover heights tokens, 1.12.0 brings a tag or button beside a panel's title, lists and grids without outer margin, text values, steps with states in any order and in a row, scrolling tabs, a cap for full pages and buttons per table row, 1.11.0 keeps a floating menu inside an open modal or dialog in place and inside the window and brings the banner's action as a button, fields that share a row and tooltips of several lines, 1.10.1 lets a disabled button show its tooltip, 1.10.0 brings the collapsing sidebar, the resizable side peek, the dialog and the tooltip, 1.9.0 the date picker and the calendar view, 1.8.0 the side peek, the bookmark, the copy field and pictures on the profile row, 1.7.0 the sheet, menus that float in and become sheets on a phone, the sidebar drawer, the database toolbar with filter pills and the steps, 1.7.1 minified files that carry all of it, 1.6.0 page properties, page options, list view, panels, prose and the avatar, 1.5.1 the safe areas, 1.5.0 the Notion-2025 tokens, the nine tag colours and the filled inputs; from 1.5.0 on, Elements and the foundation share one version number – the elements are built and tested against the same release) and `class="nk-body"` on `<body>`. The elements ship no visual CSS of their own – every rule comes from the foundation. The bundle injects the design tokens once as `@layer notionkit-defaults`, so any plain `:root { --nk-accent: … }` of yours re-brands every element in both themes.
+Two prerequisites, always: `notionkit.css` on the document (the peer dependency, `>= 1.19.1`; 1.19.1 keeps a toast with an × at its height, 1.19.0 brings the toast with an action, 1.18.0 brings a bar and its label in one row, stacked properties that keep to their card on a phone and icons in the copy field, 1.17.0 brings a step's label and a gallery card as links, 1.16.0 brings `--nk-block-space` and `flush` for blocks in a column, keeps a wide progress bar and a stretched button's label in shape and lays floating menus above dialogs, 1.15.0 brings table text with a tone and a second line, 1.14.0 brings the gallery view and a banner action that stands at the right edge again, 1.13.0 keeps fields inside narrow panels, leaves a page without icon its padding under the cover and makes cover heights tokens, 1.12.0 brings a tag or button beside a panel's title, lists and grids without outer margin, text values, steps with states in any order and in a row, scrolling tabs, a cap for full pages and buttons per table row, 1.11.0 keeps a floating menu inside an open modal or dialog in place and inside the window and brings the banner's action as a button, fields that share a row and tooltips of several lines, 1.10.1 lets a disabled button show its tooltip, 1.10.0 brings the collapsing sidebar, the resizable side peek, the dialog and the tooltip, 1.9.0 the date picker and the calendar view, 1.8.0 the side peek, the bookmark, the copy field and pictures on the profile row, 1.7.0 the sheet, menus that float in and become sheets on a phone, the sidebar drawer, the database toolbar with filter pills and the steps, 1.7.1 minified files that carry all of it, 1.6.0 page properties, page options, list view, panels, prose and the avatar, 1.5.1 the safe areas, 1.5.0 the Notion-2025 tokens, the nine tag colours and the filled inputs; from 1.5.0 on, Elements and the foundation share one version number – the elements are built and tested against the same release) and `class="nk-body"` on `<body>`. The elements ship no visual CSS of their own – every rule comes from the foundation. The bundle injects the design tokens once as `@layer notionkit-defaults`, so any plain `:root { --nk-accent: … }` of yours re-brands every element in both themes.
 
 ## Elements
 
@@ -161,6 +161,10 @@ The elements on the page take new texts at once, after `setStrings()` and when `
 | `commandPlaceholder` | `nk-cmdk` | `placeholder` | Search or type a command … | Suchen oder Befehl eingeben … |
 | `emojiPlaceholder` | `nk-emoji-picker` | `placeholder` | Search… | Suchen … |
 | `toggleTheme` | `nk-theme-toggle` | `title` | Toggle light / dark | Hell / Dunkel |
+| `appearance` | `nk-theme-toggle` (`modes` with `auto`) | `title` | Appearance: {mode} – click: {next} | Darstellung: {mode} – Klick: {next} |
+| `themeAuto` | `nk-theme-toggle` (`modes` with `auto`) | – | automatic (follows the system) | automatisch (wie das System) |
+| `themeLight` | `nk-theme-toggle` (`modes` with `auto`) | – | light | hell |
+| `themeDark` | `nk-theme-toggle` (`modes` with `auto`) | – | dark | dunkel |
 | `synced` | `nk-synced` | `badge` | ⟳ synced | ⟳ synchronisiert |
 | `message` | `nk-ai-input-row` | – | Message | Nachricht |
 | `comment` | `nk-comments` | – | Comment | Kommentar |
@@ -184,7 +188,7 @@ A step of `<nk-steps>` with `href` and a card of `<nk-gallery-view>` whose row h
 - Form controls are form-associated custom elements: `FormData`, `reset`, `required` and `<fieldset disabled>` just work. `<nk-radio>`s with the same `name` form a real group across shadow roots, with one tab stop and arrow keys.
 - Elements that copy light-DOM children (`nk-select` options, breadcrumb crumbs) watch them; `element.refresh()` is the escape hatch. Listeners are re-armed on every connect, so a moved element keeps working.
 - `::slotted()` matches only the assigned node: pass icons directly (`<span slot="icon">📁</span>`), never wrapped. For the same reason there is no `<nk-prose>`: rendered Markdown goes into a light-DOM `<div class="nk-prose">`, which reads the same rules as the editor adapter.
-- Overlays (`nk-modal`, `nk-sheet`, `nk-peek`, `nk-cmdk`, `nk-toast`, a floating `nk-menu`) go directly under `<body>`. The modal, the sheet and the palette lock scroll and make the rest of the page `inert` – the side peek only as a sheet on a phone, beside the page it leaves it usable; all of them return focus to the control that had it.
+- Overlays (`nk-modal`, `nk-sheet`, `nk-peek`, `nk-cmdk`, `nk-toast`, a floating `nk-menu`) go directly under `<body>`. The modal, the sheet and the palette lock scroll and make the rest of the page `inert` – the side peek only as a sheet on a phone, beside the page it leaves it usable; all of them return focus to the control that had it, inside a shadow root too. Escape closes the layer that opened last: a date picker or menu opened from a dialog first, then the dialog.
 - The editor stays an adapter: `nk-block-host` is the shell, `docs-editor.js` the TipTap recipe (used in the demo app). `<nk-editor>` follows in v1.1 as an optional import, never in the core bundle.
 
 ## Development

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: notionkit-elements
-description: NotionKit Elements is a vanilla-JS Web Components library (v1.18.0) wrapping NotionKit CSS v1.18.0 – the calm, document-centric design system in the Notion idiom. 88 custom elements with the `nk-` prefix, Shadow DOM, automatic light/dark sync via data-theme on <html>, and form-associated controls. Use this reference whenever generating HTML that uses <nk-*> tags to get attributes, slots, events and composition right.
+description: NotionKit Elements is a vanilla-JS Web Components library (v1.20.0) wrapping NotionKit CSS v1.20.0 – the calm, document-centric design system in the Notion idiom. 88 custom elements with the `nk-` prefix, Shadow DOM, automatic light/dark sync via data-theme on <html>, and form-associated controls. Use this reference whenever generating HTML that uses <nk-*> tags to get attributes, slots, events and composition right.
 ---
 
 # NotionKit Elements – AI Component Reference
@@ -21,8 +21,8 @@ description: NotionKit Elements is a vanilla-JS Web Components library (v1.18.0)
 <head>
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.18.0/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.18.0/dist/notionkit-elements.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.20.0/notionkit.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.20.0/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
   <nk-btn variant="primary">Save</nk-btn>
@@ -1177,7 +1177,7 @@ Give it plain `<span>` or `<a>` children; they are cloned into the bar with sepa
 
 ### 3.33 `<nk-theme-toggle>` – Theme toggle
 
-The ☀️/🌙 button. Flips `data-theme` on `<html>`, remembers the choice in `localStorage`, applies a stored or system preference on first connect when `<html>` has no theme yet, and accepts `postMessage({ nkTheme })` from a parent page. `apply(theme)` does everything a click does: sets, persists and fires `nk-change`.
+The ☀️/🌙 button. Flips `data-theme` on `<html>`, remembers the choice in `localStorage`, applies a stored or system preference on first connect when `<html>` has no theme yet, and accepts `postMessage({ nkTheme })` from a parent page. `apply(mode)` does everything a click does: sets, persists and fires `nk-change`.`modes="auto light dark"` adds a third state: auto follows `prefers-color-scheme`, live, and is what no stored value means – so the inline script before first paint keeps working and a choice made without `modes` still counts. A click then goes from auto to the theme not on screen, to the other one, back to auto, so every click but the last changes something. The glyph shows the mode (`nk-theme-glyph`, sun and moon diagonally for auto) instead of the next theme, the title names the mode and the next one, and another tab's choice arrives through the `storage` event. Two states stay the default, where nothing about this element changes.
 
 ```html
 <nk-theme-toggle></nk-theme-toggle>
@@ -1185,14 +1185,16 @@ The ☀️/🌙 button. Flips `data-theme` on `<html>`, remembers the choice in
 
 | Attribute | Type | Default | Description |
 |---|---|---|---|
-| `storage-key` | string | `nk-theme` | localStorage key. |
-| `title` | string | – | Tooltip. |
+| `modes` | string | `light dark` | The states offered, e.g. `auto light dark`; without `auto` among them nothing changes. |
+| `storage-key` | string | `nk-theme` | localStorage key; `auto` is no entry. |
+| `theme-color` | boolean | – | Keeps `<meta name="theme-color">` in step: while a theme is fixed every bar carries that theme's colour – the page's own, never invented. |
+| `title` | string | – | Tooltip; replaces the built-in text. |
 
-**Events:** `nk-change` `{ value: 'light' | 'dark' }` – Theme applied.
+**Events:** `nk-change` `{ value: 'auto' | 'light' | 'dark', theme: 'light' | 'dark' }` – Mode applied; `theme` is what is on screen (without `auto` both are the theme).
 
-**Properties:** `value` · **Methods:** `apply(theme)`
+**Properties:** `value`, `theme`, `mode`, `modes` · **Methods:** `apply(mode)`, `nextMode()`, `themeFor(mode)`
 
-**Replaces:** `.nk-theme-toggle`
+**Replaces:** `.nk-theme-toggle`, `.nk-theme-glyph`
 
 ```html
 <!-- equivalent class markup -->
@@ -2531,29 +2533,29 @@ Search field, 8-column grid, category strip. Ships with a built-in set (names fo
 
 ### 3.75 `<nk-toast>` – Toast
 
-One inverted pill at the bottom centre, above every overlay; over a tab bar at the bottom of the screen it rises 12px above the bar. `toast.show("Saved")` shows it and hides it after `duration` ms; `open` is the state.
+One inverted pill at the bottom centre, above every overlay; over a tab bar at the bottom of the screen it rises 12px above the bar. `toast.show("Saved")` shows it and hides it after `duration` ms; `open` is the state. With an action – `show("Moved to trash", { action: { label: "Undo", value: "undo" } })` or a `<button slot="action">` – it is Notion’s toast with a button and an ×: it 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` and, unless cancelled, closes it; Escape closes it while the focus is inside.
 
 ```html
-<nk-toast open duration="0">Settings saved</nk-toast>
+<nk-toast open duration="0" icon="🗑️">Moved to trash<button slot="action" value="undo">Undo</button></nk-toast>
 ```
 
 | Attribute | Type | Default | Description |
 |---|---|---|---|
 | `open` | boolean | – | Visible. |
-| `duration` | ms | `2200` | Auto-hide delay (0 = stay). |
+| `duration` | ms | `2200` | Auto-hide delay (0 = stay); a toast with an action stays unless show() names one. |
 | `icon` | string | `✓` | Leading glyph. |
 
-**Slots:** `(default)` – Static content (when `show()` gets no message).
+**Slots:** `(default)` – Static content (when `show()` gets no message). · `action` – A button for the action; its `value` goes out with `nk-action`.
 
-**Events:** `nk-toggle` `{ open }` – Shown / hidden.
+**Events:** `nk-toggle` `{ open }` – Shown / hidden. · `nk-action` `{ action, value, label }` – The action used; cancel it to keep the toast.
 
-**Properties:** `open`, `message` · **Methods:** `show(message?, { duration })`, `close()`
+**Properties:** `open`, `message` · **Methods:** `show(message?, { duration, action: { label, value } })`, `close()`
 
-**Replaces:** `.nk-toast`, `.show`
+**Replaces:** `.nk-toast`, `.show`, `.t-action`, `.t-close`
 
 ```html
 <!-- equivalent class markup -->
-<div class="nk-toast show">✓ <span>Settings saved</span></div>
+<div class="nk-toast show">🗑️ <span>Moved to trash</span><button class="t-action" type="button">Undo</button><button class="t-close" type="button" aria-label="Close"><svg viewBox="0 0 24 24" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></div>
 ```
 
 **Small screens:** Unchanged.
@@ -3150,8 +3152,8 @@ Eight skeletons, one per app shape, mirroring the NotionKit CSS SKILL.md. Copy o
 <html lang="en" data-theme="light">
 <head>
   <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.18.0/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.18.0/dist/notionkit-elements.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.20.0/notionkit.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.20.0/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
 <nk-app>
@@ -3232,8 +3234,8 @@ Rules of the shell: `nk-sidebar`, `nk-topbar` and `nk-page` are `display: conten
 <html lang="en" data-theme="light">
 <head>
   <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.18.0/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.18.0/dist/notionkit-elements.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.20.0/notionkit.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.20.0/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
 <nk-app>
@@ -3340,8 +3342,8 @@ Data contract: `columns` describe the properties (`type`: text | select | multi-
 <html lang="en" data-theme="light">
 <head>
   <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.18.0/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.18.0/dist/notionkit-elements.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.20.0/notionkit.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.20.0/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
 <nk-app>
@@ -3400,8 +3402,8 @@ Data contract: `columns` describe the properties (`type`: text | select | multi-
 <html lang="en" data-theme="light">
 <head>
   <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.18.0/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.18.0/dist/notionkit-elements.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.20.0/notionkit.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.20.0/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
 <!-- your app -->
@@ -3478,8 +3480,8 @@ The open/close contract is one attribute: `settings.open = true`, `settings.show
 <html lang="en" data-theme="light">
 <head>
   <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.18.0/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.18.0/dist/notionkit-elements.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.20.0/notionkit.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.20.0/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
 <div class="nk-page" style="padding-top:48px">
@@ -3525,8 +3527,8 @@ The open/close contract is one attribute: `settings.open = true`, `settings.show
 <html lang="en" data-theme="light">
 <head>
   <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.18.0/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.18.0/dist/notionkit-elements.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.20.0/notionkit.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.20.0/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
 <nk-page narrow icon="📘" cover>
@@ -3570,8 +3572,8 @@ Note `narrow`: the page is the document, so there is no inner scroll wrapper –
 <html lang="en" data-theme="light">
 <head>
   <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.18.0/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.18.0/dist/notionkit-elements.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.20.0/notionkit.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.20.0/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
 <nk-app>
@@ -3625,8 +3627,8 @@ Note `narrow`: the page is the document, so there is no inner scroll wrapper –
 <html lang="en" data-theme="light">
 <head>
   <meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.18.0/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.18.0/dist/notionkit-elements.min.js"></script>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit@1.20.0/notionkit.min.css">
+  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.20.0/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
 <!-- A narrow column, centred: layout is yours, so it is inline. -->
@@ -3720,6 +3722,9 @@ Form controls additionally re-dispatch a native, bubbling `change` event, so `fo
 | A `<div style="display:flex">` around `<nk-progress wide label>` in a panel so the label stays beside the bar | Not needed: with a `label` the element sets bar and label in one `.nk-progress-row` – beside each other in a flex column too |
 | `copy-label="⧉"` or other glyphs to save room in `<nk-copy-field>` on a phone | Nothing: on a phone the buttons show icons by themselves, the words stay their names; `icons` does it at every width |
 | `<nk-tab-bar>` kept on the last tab while a page from the drawer is open | Set `value` to that page's own value: a value no item has marks the `drawer` item ("More"), as on iOS |
+| A banner under the topbar for "New version · Reload", or a toast plus a separate Undo button | `toast.show('Moved to trash', { action: { label: 'Undo', value: 'undo' } })` – a button and an ×, it stays until used; `nk-action` names the action |
+| `stopImmediatePropagation()` or a check of your own so that Escape in a dialog closes only its date picker | Nothing: Escape closes the layer that opened last – the floating date picker or menu first, then the dialog |
+| A `focusBack()` helper after a menu, the modal or the palette opened from a view's shadow root | Nothing: the overlays find the focused control behind shadow hosts and give the focus back to it |
 
 
 # 7. Quick Reference
@@ -3758,7 +3763,7 @@ Form controls additionally re-dispatch a native, bubbling `change` event, so `fo
 | `<nk-tree-item>` | shell | `icon`, `label`, `value`, `href` | `(default)`, `icon`, `end` | `nk-select`, `nk-toggle`, `nk-action` |
 | `<nk-topbar>` | shell | – | `(default)`, `actions` | – |
 | `<nk-breadcrumb>` | shell | `separator` | `(default)` | `nk-select` |
-| `<nk-theme-toggle>` | shell | `storage-key`, `title` | – | `nk-change` |
+| `<nk-theme-toggle>` | shell | `modes`, `storage-key`, `theme-color`, `title` | – | `nk-change` |
 | `<nk-tab-bar>` | shell | `value`, `always`, `fixed`, `floating` | `(default)` | `nk-change`, `nk-select` |
 | `<nk-tab-bar-item>` | shell | `icon`, `value`, `label`, `href` | `(default)`, `icon` | `nk-select` |
 | `<nk-page>` | page | `icon`, `full`, `small`, `cover` | `(default)`, `cover`, `icon` | `nk-action` |
@@ -3800,7 +3805,7 @@ Form controls additionally re-dispatch a native, bubbling `change` event, so `fo
 | `<nk-menu-item>` | overlays | `icon`, `shortcut`, `value`, `danger` | `(default)`, `icon` | `nk-select`, `nk-change` |
 | `<nk-pop>` | overlays | `open`, `placement`, `bare` | `trigger`, `(default)` | `nk-toggle` |
 | `<nk-emoji-picker>` | overlays | `placeholder`, `value` | – | `nk-select` |
-| `<nk-toast>` | overlays | `open`, `duration`, `icon` | `(default)` | `nk-toggle` |
+| `<nk-toast>` | overlays | `open`, `duration`, `icon` | `(default)`, `action` | `nk-toggle`, `nk-action` |
 | `<nk-tooltip>` | overlays | `for`, `shortcut`, `delay`, `placement` | `(default)` | – |
 | `<nk-database>` | data | `view`, `add-view` | `(default)`, `tools`, `filters` | `nk-view-change`, `nk-action`, `nk-select / nk-change / nk-action` |
 | `<nk-table-view>` | data | `name`, `label`, `badge`, `count` | – | `nk-select`, `nk-change`, `nk-action` |
@@ -3834,10 +3839,10 @@ Form controls additionally re-dispatch a native, bubbling `change` event, so `fo
 | Texts | `src/util/strings.js` – the English and German dictionary and `setStrings()`; `NkElement#str(key)` reads it in the element's language, `onStringsChanged()` runs after `setStrings()` and when `<html lang>` changes |
 | Components | `src/components/{forms,content,shell,page,overlays,data}/nk-*.js`, one tag per file, `customElements.define` at the bottom |
 | Build | Rollup: IIFE, minified IIFE, ESM, and per-component ESM entries on a stable `dist/components/base.js` that import NotionKit's sheet (`@jungherz-de/notionkit/notionkit-styles.js`) instead of inlining it; the full bundles inline it and export `componentsSheet` |
-| Peer | `@jungherz-de/notionkit >= 1.18.0` – from 1.5.0 on the elements and the foundation share one version number; the bundle embeds that release's stylesheet, so keep them in step |
+| Peer | `@jungherz-de/notionkit >= 1.20.0` – from 1.5.0 on the elements and the foundation share one version number; the bundle embeds that release's stylesheet, so keep them in step |
 
 Lifecycle: construct (attach shadow, adopt sheets) → first connect (wrapper + `render()`) → every connect (`setupEvents()`, theme registration, light-DOM observer) → `attributeChangedCallback` → `onAttributeChanged` → disconnect (`teardownEvents()`, unregister).
 
 
 ---
-*NotionKit Elements v1.18.0 · wrapping NotionKit CSS v1.18.0 · MIT · Jungherz GmbH*
+*NotionKit Elements v1.20.0 · wrapping NotionKit CSS v1.20.0 · MIT · Jungherz GmbH*

package/dist/components/base.js

@@ -18,6 +18,7 @@ const BUILT_IN = {
     commentPlaceholder: 'Comment …', send: 'Send', askPlaceholder: 'Ask something …',
     commandPlaceholder: 'Search or type a command …', emojiPlaceholder: 'Search…',
     toggleTheme: 'Toggle light / dark', synced: '⟳ synced',
+    appearance: 'Appearance: {mode} – click: {next}', themeAuto: 'automatic (follows the system)', themeLight: 'light', themeDark: 'dark',
     message: 'Message', breadcrumb: 'Breadcrumb', commandPalette: 'Command palette', comment: 'Comment',
     searchEmoji: 'Search emoji', settings: 'Settings', title: 'Title', changeIcon: 'Change icon',
     add: 'Add', more: 'More',
@@ -32,6 +33,7 @@ const BUILT_IN = {
     commentPlaceholder: 'Kommentieren …', send: 'Senden', askPlaceholder: 'Frag etwas …',
     commandPlaceholder: 'Suchen oder Befehl eingeben …', emojiPlaceholder: 'Suchen …',
     toggleTheme: 'Hell / Dunkel', synced: '⟳ synchronisiert',
+    appearance: 'Darstellung: {mode} – Klick: {next}', themeAuto: 'automatisch (wie das System)', themeLight: 'hell', themeDark: 'dunkel',
     message: 'Nachricht', breadcrumb: 'Pfad', commandPalette: 'Befehlspalette', comment: 'Kommentar',
     searchEmoji: 'Emoji suchen', settings: 'Einstellungen', title: 'Titel', changeIcon: 'Symbol ändern',
     add: 'Hinzufügen', more: 'Mehr',

package/dist/components/nk-calendar.js

@@ -1,7 +1,8 @@
 import { NkFormElement } from './base.js';
 import { p as parseDay, i as isoOf, C as CHEVRONS, r as resolveLocale, f as firstWeekday, m as monthGrid, w as weekLabel, a as weekdayNames, b as isoWeek, s as stepMonth, c as addDays } from './shared/dates-a32DcW1l.js';
 import { p as placeUnder } from './shared/floating-DOK73b_D.js';
-import { d as deepActiveElement } from './shared/focus-C4tbSNND.js';
+import { d as deepActiveElement } from './shared/focus-D55JGjRA.js';
+import { c as closeLayer, o as openLayer } from './shared/layers-D9YYYA5g.js';
 import '@jungherz-de/notionkit/notionkit-styles.js';
 
 // <nk-calendar name="due" value="2026-06-02" weeks weekend="6,0"></nk-calendar>
@@ -272,14 +273,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);
@@ -287,7 +287,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);
   }
 
@@ -299,7 +298,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);
   }
 
@@ -323,7 +322,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/dist/components/nk-cmdk.js

@@ -1,5 +1,6 @@
 import { NkElement } from './base.js';
-import { l as lockScroll, i as inertOutside, u as unlockScroll } from './shared/focus-C4tbSNND.js';
+import { d as deepActiveElement, l as lockScroll, i as inertOutside, u as unlockScroll } from './shared/focus-D55JGjRA.js';
+import { o as openLayer, c as closeLayer } from './shared/layers-D9YYYA5g.js';
 import '@jungherz-de/notionkit/notionkit-styles.js';
 
 // Subsequence scoring for the command palette: every query character must
@@ -153,14 +154,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;
@@ -171,8 +174,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) => {
@@ -201,7 +203,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/dist/components/nk-dialog.js

@@ -1,5 +1,6 @@
 import { NkElement } from './base.js';
-import { d as deepActiveElement, l as lockScroll, i as inertOutside, f as firstFocusable, u as unlockScroll } from './shared/focus-C4tbSNND.js';
+import { d as deepActiveElement, l as lockScroll, i as inertOutside, f as firstFocusable, u as unlockScroll } from './shared/focus-D55JGjRA.js';
+import { o as openLayer, c as closeLayer } from './shared/layers-D9YYYA5g.js';
 import '@jungherz-de/notionkit/notionkit-styles.js';
 
 // <nk-dialog id="trash" title="Move “Roadmap” to trash?" alert>
@@ -80,8 +81,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;
@@ -93,7 +96,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) => {
@@ -113,7 +115,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();
   }
 
@@ -122,8 +123,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/dist/components/nk-menu.js

@@ -1,5 +1,6 @@
 import { NkElement } from './base.js';
-import { d as deepActiveElement } from './shared/focus-C4tbSNND.js';
+import { d as deepActiveElement, c as containsDeep } from './shared/focus-D55JGjRA.js';
+import { o as openLayer, c as closeLayer } from './shared/layers-D9YYYA5g.js';
 import { p as placeUnder } from './shared/floating-DOK73b_D.js';
 import '@jungherz-de/notionkit/notionkit-styles.js';
 
@@ -49,15 +50,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) {
@@ -95,17 +111,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);
   }