@jungherz-de/notionkit-elements 1.19.0 → 1.20.1

package/CHANGELOG.md

@@ -4,6 +4,66 @@ 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.1] – 2026-10-14
+
+Elements only; NotionKit CSS stays at 1.20.0 (peer `>= 1.20.0`).
+
+### Fixed
+- **`<nk-tooltip>` follows the pointer and the focus inside a shadow root
+  (#3).** Moving from one `[data-tooltip]` to the next in the same shadow
+  root never updated the tooltip – the first one stayed, or none appeared –
+  for the pointer and for Tab alike; `<nk-copy-field icons secret>` kept
+  saying "Show" over Copy, an app's toolbar or chart bars in one root did
+  the same. `pointerover`, `focusin` and `focusout` carry a `relatedTarget`,
+  and when target and `relatedTarget` share a shadow tree the DOM standard
+  ends the event path at its host, so the listeners on the document never
+  heard of the move. The tooltip now also reads `pointermove` (no
+  `relatedTarget`, it always reaches the document) and acts only when the
+  element under the pointer changes, so a hand resting on the page leaves a
+  tooltip the keyboard or `show(rect)` opened alone; and it catches a key
+  that moved the focus – Tab, Option+Tab in Safari, the arrow keys of a
+  roving tab stop that moves the focus in its own `keydown` – on `keyup`,
+  against the focus recorded before the key went down. Nested shadow roots
+  are followed too. A focus move by script alone inside one shadow root
+  stays unseen. Reported by Mailverse.
+- **Leaving the window** over a `[data-tooltip]` left its tooltip standing,
+  and one still waiting appeared after the pointer had gone. It now goes
+  with the pointer (`pointerout` without a `relatedTarget`); a tooltip the
+  keyboard or `show(rect)` opened is not the pointer's and stays. Found
+  while testing #3.
+
+## [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.
@@ -746,6 +806,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.1]: https://github.com/JUNGHERZ/NotionKit-Elements/releases/tag/v1.20.1
+[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

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.19.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.1-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.19.0-lightgrey?style=flat-square" alt="Changelog"></a>
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/changelog-v1.20.1-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>
 
@@ -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.19.1/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.19.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.1/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
   <nk-field label="Display name" desc="Shown next to your comments">
@@ -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 |

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: notionkit-elements
-description: NotionKit Elements is a vanilla-JS Web Components library (v1.19.0) wrapping NotionKit CSS v1.19.1 – 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.1) 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.19.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.19.1/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.19.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.1/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 -->
@@ -2560,7 +2562,7 @@ One inverted pill at the bottom centre, above every overlay; over a tab bar at t
 
 ### 3.76 `<nk-tooltip>` – Tooltip
 
-Notion’s hover hint in the toast’s colours, a shortcut muted beside it. One `<nk-tooltip>` without `for` serves every element with `data-tooltip` (and `data-tooltip-key`) on the page, inside shadow roots too – a whole toolbar in one element; with `for` it belongs to one element and shows its own content and `shortcut`. It appears after `delay` ms (400) under the pointer and at once on keyboard focus, never on touch; leaving, a press, blur, scrolling and Escape hide it. It sits 6px below its target and centred, above it where the window ends, 8px inside the window – `placeNear` in `util/floating.js`. `show(target, text, shortcut)` takes an element or a rect, for what has no element of its own: the bars of a chart. The target’s `aria-describedby` names it while it shows. Hover the buttons. A tooltip shown with `show(rect, …)` stays until `hide()`, the pointer on another `[data-tooltip]`, a press or Escape; the wheel hides it too, also inside a shadow root. A line break in the text is kept.
+Notion’s hover hint in the toast’s colours, a shortcut muted beside it. One `<nk-tooltip>` without `for` serves every element with `data-tooltip` (and `data-tooltip-key`) on the page, inside shadow roots too – a whole toolbar in one element, and it follows pointer and keyboard from one such element to the next within the same shadow root; with `for` it belongs to one element and shows its own content and `shortcut`. It appears after `delay` ms (400) under the pointer and at once on keyboard focus, never on touch; leaving – the window too –, a press, blur, scrolling and Escape hide it. It sits 6px below its target and centred, above it where the window ends, 8px inside the window – `placeNear` in `util/floating.js`. `show(target, text, shortcut)` takes an element or a rect, for what has no element of its own: the bars of a chart. The target’s `aria-describedby` names it while it shows. Hover the buttons. A tooltip shown with `show(rect, …)` stays until `hide()`, the pointer on another `[data-tooltip]`, a press or Escape; the wheel hides it too, also inside a shadow root. A line break in the text is kept.
 
 ```html
 <div style="display:flex;gap:16px;align-items:center;padding:4px 0 44px">
@@ -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.19.1/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.19.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.1/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.19.1/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.19.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.1/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.19.1/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.19.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.1/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.19.1/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.19.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.1/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.19.1/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.19.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.1/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.19.1/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.19.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.1/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.19.1/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.19.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.1/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.19.1/notionkit.min.css">
-  <script src="https://cdn.jsdelivr.net/npm/@jungherz-de/notionkit-elements@1.19.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.1/dist/notionkit-elements.min.js"></script>
 </head>
 <body class="nk-body">
 <!-- A narrow column, centred: layout is yours, so it is inline. -->
@@ -3761,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` |
@@ -3837,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.19.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.1` – 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.19.0 · wrapping NotionKit CSS v1.19.1 · MIT · Jungherz GmbH*
+*NotionKit Elements v1.20.1 · 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-theme-toggle.js

@@ -8,62 +8,203 @@ import '@jungherz-de/notionkit/notionkit-styles.js';
 // system preference on first connect when <html> carries no theme yet, and
 // accepts postMessage({ nkTheme }) from a parent page (the landing page's
 // embedded demo uses that).
-class NkThemeToggle extends NkElement {
-  static get observedAttributes() { return ['storage-key', 'title'];
+//
+// <nk-theme-toggle modes="auto light dark"> adds a third state (1.20.0):
+// `auto` follows prefers-color-scheme, live, and is what no stored value
+// means – so the documented inline script before first paint keeps working
+// and a choice made without `modes` still counts. The glyph then shows the
+// mode (☀️, 🌙, both for auto) instead of the next theme, the title names
+// the mode and the next one, other tabs follow through the storage event,
+// and `theme-color` keeps <meta name="theme-color"> in step. Two states stay
+// the default, where nothing about this element changes.
+const GLYPH = { light: '☀️', dark: '🌙' };
 
-  }
+class NkThemeToggle extends NkElement {
+  static get observedAttributes() { return ['storage-key', 'title', 'modes', 'theme-color']; }
 
   render() {
     this._btn = this.createElement('button', ['nk-topbar-btn', 'nk-theme-toggle'], { type: 'button' });
-    this._syncTitle();
     this._wrapper.appendChild(this._btn);
-    const root = document.documentElement;
+    this._readThemeColors();
+    if (this.auto) {
+      // With `auto` this element owns the theme: a stored choice, else the
+      // system. The inline script before first paint has set the same value.
+      this._applyMode();
+    } else {
+      const root = document.documentElement;
+      let stored = null;
+      try { stored = localStorage.getItem(this.storageKey); } catch {}
+      if (stored === 'light' || stored === 'dark') root.setAttribute('data-theme', stored);
+      else if (!root.hasAttribute('data-theme')) root.setAttribute('data-theme', this.systemTheme);
+      this._syncThemeColor();
+      this._syncGlyph();
+      this._syncTitle();
+    }
+  }
+
+  // ── Modes ──
+
+  /** The states offered, in the author's order; without a theme among them the default two. */
+  get modes() {
+    const list = [...new Set((this.getAttribute('modes') || '').toLowerCase().split(/\s+/))].filter(m => m === 'auto' || m === 'light' || m === 'dark');
+    return list.some(m => m !== 'auto') ? list : ['light', 'dark'];
+  }
+
+  /** Whether `auto` is offered – the only thing that changes this element's behaviour. */
+  get auto() { return this.modes.includes('auto'); }
+
+  /** One query object per element: a listener on a throwaway one is neither removable nor safe from collection. */
+  get systemQuery() { return (this._query ??= matchMedia('(prefers-color-scheme: dark)')); }
+
+  get systemTheme() { return this.systemQuery.matches ? 'dark' : 'light'; }
+
+  /** The mode in force: 'auto' (nothing stored), 'light' or 'dark'. Without `auto` the theme on screen. */
+  get mode() {
+    if (!this.auto) return getCurrentTheme();
     let stored = null;
-    try { stored = localStorage.getItem(this.storageKey); } catch {}
-    if (stored === 'light' || stored === 'dark') root.setAttribute('data-theme', stored);
-    else if (!root.hasAttribute('data-theme')) root.setAttribute('data-theme', matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+    try { stored = localStorage.getItem(this.storageKey); } catch { return this._unsaved || 'auto'; }
+    if (stored === 'light' || stored === 'dark') return stored;
+    return this._unsaved || 'auto';
+  }
+
+  /** The theme on screen for a mode: `auto` is whatever the system says. */
+  themeFor(mode = this.mode) { return mode === 'auto' ? this.systemTheme : mode; }
+
+  /**
+   * The mode a click moves to. From `auto` to the theme that is *not* on
+   * screen, then to the other one, then back to `auto` – so every click but
+   * the last changes something visibly. Without `auto` it cycles the themes.
+   */
+  nextMode(mode = this.mode) {
+    const modes = this.modes, themes = modes.filter(m => m !== 'auto'), system = this.systemTheme;
+    if (!modes.includes('auto')) return themes[(themes.indexOf(mode) + 1) % themes.length];
+    if (mode === 'auto') return themes.find(m => m !== system) ?? themes[0];
+    if (mode !== system) return themes.includes(system) ? system : 'auto';
+    return 'auto';
+  }
+
+  // ── Applying ──
+
+  _applyMode(mode = this.mode) {
+    const theme = this.themeFor(mode);
+    const root = document.documentElement;
+    // Only on a change: the observer in base.js mirrors data-theme into every
+    // element, and auto re-applies the same value on every system change.
+    if (root.getAttribute('data-theme') !== theme) root.setAttribute('data-theme', theme);
+    this._syncThemeColor(mode);
     this._syncGlyph();
+    this._syncTitle();
+  }
+
+  /** The page's own theme-color values, per medium, before this element touched them. */
+  _readThemeColors() {
+    this._bars = [...document.querySelectorAll('meta[name="theme-color"]')].map(meta => ({
+      meta, dark: (meta.getAttribute('media') || '').includes('dark'), content: meta.getAttribute('content'),
+    }));
+  }
+
+  /**
+   * `theme-color`: while a theme is fixed every meta carries the colour of
+   * that theme, so the browser bar follows the choice; back on `auto` each
+   * one carries its own again. The colours are the page's – never invented.
+   */
+  _syncThemeColor(mode = this.mode) {
+    if (!this.hasAttribute('theme-color') || !this._bars?.length) return;
+    const auto = mode === 'auto', dark = this.themeFor(mode) === 'dark';
+    const fixed = (this._bars.find(bar => bar.dark === dark) ?? this._bars[0]).content;
+    for (const bar of this._bars) if (bar.content !== null) bar.meta.setAttribute('content', auto ? bar.content : fixed);
   }
 
   _syncGlyph() {
-    if (this._btn) this._btn.textContent = getCurrentTheme() === 'dark' ? '☀️' : '🌙';
+    if (!this._btn) return;
+    if (!this.auto) {
+      // Two states: the glyph is the next theme, as it has always been.
+      this._btn.replaceChildren(getCurrentTheme() === 'dark' ? GLYPH.light : GLYPH.dark);
+      this._btn.removeAttribute('aria-label');
+      return;
+    }
+    const mode = this.mode;
+    const glyph = this.createElement('span', ['nk-theme-glyph'], { 'aria-hidden': 'true' });
+    if (mode === 'auto') glyph.classList.add('auto');
+    for (const text of mode === 'auto' ? [GLYPH.light, GLYPH.dark] : [GLYPH[mode]]) {
+      glyph.appendChild(Object.assign(document.createElement('span'), { textContent: text }));
+    }
+    this._btn.replaceChildren(glyph);
+    // Two emojis are no accessible name; the title's text is.
+    this._btn.setAttribute('aria-label', this._titleText());
   }
 
   _syncTheme(theme) {
     super._syncTheme(theme);
     this._syncGlyph();
+    this._syncTitle();
+  }
+
+  _titleText() {
+    const own = this.getAttribute('title');
+    if (own) return own;
+    if (!this.auto) return this.str('toggleTheme');
+    const name = (mode) => this.str(mode === 'auto' ? 'themeAuto' : mode === 'dark' ? 'themeDark' : 'themeLight');
+    return this.str('appearance').replace('{mode}', name(this.mode)).replace('{next}', name(this.nextMode()));
   }
 
+  _syncTitle() { if (this._btn) this._btn.title = this._titleText(); }
+  onStringsChanged() { this._syncTitle(); if (this.auto) this._syncGlyph(); }
+
   setupEvents() {
-    this._onClick = () => this.apply(getCurrentTheme() === 'dark' ? 'light' : 'dark');
-    this._onMessage = (e) => { const t = e.data?.nkTheme; if (t === 'light' || t === 'dark') this.apply(t); };
+    this._onClick = () => this.apply(this.nextMode());
+    this._onMessage = (e) => { const t = e.data?.nkTheme; if (t === 'light' || t === 'dark' || (t === 'auto' && this.auto)) this.apply(t); };
+    // `auto` has to notice a system switch while the page is open, and a
+    // choice made in another tab. Both only matter where `auto` is offered.
+    this._onSystem = () => { if (this.mode === 'auto') this._applyMode(); };
+    this._onStorage = (e) => { if (e.key === this.storageKey || e.key === null) this._applyMode(); };
     this._btn.addEventListener('click', this._onClick);
     window.addEventListener('message', this._onMessage);
+    if (this.auto) {
+      this.systemQuery.addEventListener('change', this._onSystem);
+      window.addEventListener('storage', this._onStorage);
+    }
   }
 
   teardownEvents() {
     this._btn?.removeEventListener('click', this._onClick);
     window.removeEventListener('message', this._onMessage);
+    if (this._onSystem) this.systemQuery.removeEventListener('change', this._onSystem);
+    window.removeEventListener('storage', this._onStorage);
   }
 
-  _syncTitle() { this._btn.title = this.getAttribute('title') || this.str('toggleTheme'); }
-  onStringsChanged() { this._syncTitle(); }
-
   onAttributeChanged(name) {
-    if (name === 'title' && this._btn) this._syncTitle();
+    if (!this._btn) return;
+    if (name === 'modes') {
+      // Re-arm: the listeners above hang on whether `auto` is offered.
+      if (this.isConnected) { this.teardownEvents(); this.setupEvents(); }
+      this.auto ? this._applyMode() : this._syncGlyph();
+    }
+    this._syncTitle();
   }
 
-  /** Sets the theme on <html>, persists it and reports it. */
-  apply(theme) {
-    document.documentElement.setAttribute('data-theme', theme);
-    try { localStorage.setItem(this.storageKey, theme); } catch {}
-    this._syncGlyph();
-    this.emit('nk-change', { value: theme });
+  /**
+   * Sets the mode on <html>, persists it and reports it. `light` / `dark`
+   * are stored, `auto` (only where it is offered) clears the entry – that is
+   * what the inline script before first paint reads.
+   */
+  apply(mode) {
+    const wanted = mode === 'auto' && this.auto ? 'auto' : mode === 'light' || mode === 'dark' ? mode : this.themeFor(mode);
+    try {
+      if (wanted === 'auto') localStorage.removeItem(this.storageKey);
+      else localStorage.setItem(this.storageKey, wanted);
+      this._unsaved = null;
+    } catch { this._unsaved = wanted; }
+    this._applyMode(wanted);
+    this.emit('nk-change', { value: this.auto ? wanted : this.themeFor(wanted), theme: this.themeFor(wanted) });
   }
 
   get storageKey() { return this.getAttribute('storage-key') || 'nk-theme'; }
-  get value() { return getCurrentTheme(); }
+  /** The mode: 'auto' | 'light' | 'dark'. Without `auto` the theme, as before. */
+  get value() { return this.auto ? this.mode : getCurrentTheme(); }
   set value(v) { this.apply(v); }
+  /** The theme on screen – 'light' or 'dark', whatever the mode. */
+  get theme() { return this.themeFor(); }
 }
 
 customElements.define('nk-theme-toggle', NkThemeToggle);

package/dist/components/nk-tooltip.js

@@ -24,6 +24,17 @@ import '@jungherz-de/notionkit/notionkit-styles.js';
 // [data-tooltip], a press or Escape. A line break in the text is kept.
 // While it shows, the target's aria-describedby names it (in the same
 // document or shadow root).
+//
+// Following the pointer and the focus inside a shadow root (1.20.1):
+// pointerover, focusin and focusout carry a relatedTarget, and when target
+// and relatedTarget share a shadow tree the DOM standard ends the event path
+// at its host – the document never hears of a move from one [data-tooltip]
+// to the next in the same root. So the pointer is also read from
+// pointermove, which has no relatedTarget, and acted on only when the
+// element under it changes; and a key that moved the focus – Tab, the arrow
+// keys of a group – is caught on keyup, comparing the focused element with
+// the one before the key went down. A move by script alone inside one
+// shadow root stays unseen.
 const hostSheet = new CSSStyleSheet();
 hostSheet.replaceSync(`:host { display: block; position: fixed; top: 0; left: 0; z-index: 130; pointer-events: none; }`);
 let count = 0;
@@ -101,14 +112,50 @@ class NkTooltip extends NkElement {
     this.show(el, own ? null : el.getAttribute('data-tooltip'), own ? this.getAttribute('shortcut') : el.getAttribute('data-tooltip-key'));
   }
 
+  /**
+   * The pointer is over `el` now (null: no [data-tooltip]). pointerover acts
+   * on every boundary it crosses, as it always has; pointermove – the only
+   * one that reaches the document from inside a shadow root – only when the
+   * element under the pointer changed, so a hand resting on the page leaves
+   * a tooltip the keyboard or show(rect) opened alone.
+   */
+  _pointer(e, move) {
+    const el = e.pointerType === 'touch' ? null : this._targetOf(e);
+    if (move && el === this._hover) return;
+    this._hover = el;
+    if (el === this._target) return;
+    this.hide();
+    if (!el) return;
+    this._target = el;
+    this._timer = setTimeout(() => this._showFor(el), this._delay);
+  }
+
   setupEvents() {
-    this._onOver = (e) => {
-      const el = e.pointerType === 'touch' ? null : this._targetOf(e);
-      if (el === this._target) return;
+    this._onOver = (e) => this._pointer(e, false);
+    this._onMove = (e) => this._pointer(e, true);
+    // The pointer left the window (no relatedTarget): a tooltip – shown or
+    // still waiting – for what it was on goes with it. One the keyboard or
+    // show(rect) opened is not the pointer's and stays.
+    this._onOut = (e) => {
+      if (e.relatedTarget || e.pointerType === 'touch') return;
+      if (this._target && this._target === this._hover) this.hide();
+      this._hover = null;
+    };
+    // Capture, before an element's own keydown moves the focus (a roving tab
+    // stop does); not for a held key's repeats, so keyup compares with where
+    // the focus was before the key went down.
+    this._onKeyDown = (e) => { if (!e.repeat) this._focusBefore = deepActiveElement(); };
+    this._onKeyUp = (e) => {
+      const active = deepActiveElement();
+      if (active === this._focusBefore) return;
+      this._focusBefore = active;
+      // keyup goes to the focused element, so its path is the focus's path.
+      const el = this._targetOf(e);
+      if (el && el === this._target) return;   // focusin got there first
       this.hide();
-      if (!el) return;
+      if (!el || !active?.matches(':focus-visible')) return;
       this._target = el;
-      this._timer = setTimeout(() => this._showFor(el), this._delay);
+      this._showFor(el);
     };
     this._onFocus = (e) => {
       const el = this._targetOf(e);
@@ -120,7 +167,11 @@ class NkTooltip extends NkElement {
     this._onHide = () => this.hide();
     this._onKey = (e) => { if (e.key === 'Escape' && this.open) this.hide(); };
     document.addEventListener('pointerover', this._onOver);
+    document.addEventListener('pointermove', this._onMove, { capture: true, passive: true });
+    document.addEventListener('pointerout', this._onOut);
     document.addEventListener('focusin', this._onFocus);
+    document.addEventListener('keydown', this._onKeyDown, true);
+    document.addEventListener('keyup', this._onKeyUp, true);
     document.addEventListener('focusout', this._onHide);
     document.addEventListener('pointerdown', this._onHide, true);
     document.addEventListener('scroll', this._onHide, true);
@@ -131,13 +182,18 @@ class NkTooltip extends NkElement {
 
   teardownEvents() {
     document.removeEventListener('pointerover', this._onOver);
+    document.removeEventListener('pointermove', this._onMove, { capture: true });
+    document.removeEventListener('pointerout', this._onOut);
     document.removeEventListener('focusin', this._onFocus);
+    document.removeEventListener('keydown', this._onKeyDown, true);
+    document.removeEventListener('keyup', this._onKeyUp, true);
     document.removeEventListener('focusout', this._onHide);
     document.removeEventListener('pointerdown', this._onHide, true);
     document.removeEventListener('scroll', this._onHide, true);
     document.removeEventListener('wheel', this._onHide, { capture: true });
     document.removeEventListener('keydown', this._onKey);
     this.hide();
+    this._hover = this._focusBefore = null;
   }
 
   onAttributeChanged(name) { if (name === 'shortcut' && !this._text.data) this._fill(null); if (name === 'for') this.hide(); }