@jungherz-de/notionkit-elements 1.19.0 → 1.20.0

package/CHANGELOG.md

@@ -4,6 +4,38 @@ 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.
@@ -746,6 +778,7 @@ 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

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.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.19.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>
 
@@ -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.0/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.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.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.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 -->
@@ -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.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.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.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.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.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.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.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.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.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.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.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.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.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.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.0/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.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.19.0 · wrapping NotionKit CSS v1.19.1 · 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-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);