@vanduo-oss/framework 1.4.3 → 1.4.4

package/README.md

@@ -1,4 +1,4 @@
-# Vanduo Framework v1.4.3
+# Vanduo Framework v1.4.4
 
 <p align="center">
   <img src="vanduo-banner.svg" alt="Vanduo Framework Banner" width="100%">
@@ -22,15 +22,23 @@ Vanduo is a zero-dependency UI framework built with HTML, CSS, and vanilla JavaS
 - Strict design token API under `--vd-*`
 - Built-in dark, light, and system theming
 - Theme customizer with color, font, and radius controls
+- Theme Switcher menu variant for icon-only light/dark/system selection in navbars
 - Playwright-based browser coverage across Chromium, Firefox, and WebKit
 
+## What's New in 1.4.4
+
+- **Theme Switcher menu variant** — `.vd-theme-switcher[data-theme-ui="menu"]` opens an icon-only picker; option click applies the theme without cycling on toggle. Cycle (`button[data-toggle="theme"]`) and select variants are unchanged.
+- **New stylesheet** — `css/components/theme-switcher.css` for menu layout, active state, and navbar alignment.
+- **Optional tooltips** — add `data-tooltip` on the toggle or menu options when the Tooltips component is loaded (opt-in).
+- Normative API: [openspec/specs/theme-switcher/spec.md](openspec/specs/theme-switcher/spec.md).
+
 ## Quick Start
 
 ### CDN
 
 ```html
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.4.3/dist/vanduo.min.css">
-<script src="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.4.3/dist/vanduo.min.js"></script>
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.4.4/dist/vanduo.min.css">
+<script src="https://cdn.jsdelivr.net/gh/vanduo-oss/framework@v1.4.4/dist/vanduo.min.js"></script>
 <script>
   Vanduo.init();
 </script>
@@ -114,6 +122,7 @@ framework/
 ├── dist/         # Built artifacts
 ├── tests/        # Playwright fixtures and specs
 ├── scripts/      # Build, verification, and inventory scripts
+├── openspec/     # Spec-driven change proposals and component specs
 └── docs/*.md     # Release and architecture notes
 ```
 
@@ -129,11 +138,14 @@ pnpm test
 pnpm run stats:css
 ```
 
+CI runs **Chromium Desktop smoke tests on pull requests** and the **full cross-browser Playwright matrix on push to `main`** (see [`.github/workflows/tests.yml`](.github/workflows/tests.yml) and [QA-Automation-Strategy.md](QA-Automation-Strategy.md)).
+
 ## Release Notes
 
 - Architecture notes: [ARCHITECTURE.md](ARCHITECTURE.md)
 - Token model: [TOKENS.md](TOKENS.md)
 - `1.4.1` token migration notes: [changes-v141.md](changes-v141.md)
+- Theme Switcher spec: [openspec/specs/theme-switcher/spec.md](openspec/specs/theme-switcher/spec.md)
 - QA strategy: [QA-Automation-Strategy.md](QA-Automation-Strategy.md)
 - Contributor workflow: [CONTRIBUTING.md](CONTRIBUTING.md)
 

package/css/components/theme-switcher.css

@@ -0,0 +1,129 @@
+/**
+ * Vanduo Framework - Theme Switcher
+ * Icon-only menu variant for explicit theme selection
+ */
+
+:root {
+  --vd-theme-switcher-menu-bg: var(--vd-color-white);
+  --vd-theme-switcher-menu-border-color: var(--vd-border-color);
+  --vd-theme-switcher-option-hover-bg: var(--vd-bg-secondary);
+  --vd-theme-switcher-option-active-bg: var(--vd-color-primary-alpha-10);
+  --vd-theme-switcher-option-active-color: var(--vd-color-primary);
+  --vd-theme-switcher-z-index: 1000;
+}
+
+[data-theme="dark"] {
+  --vd-theme-switcher-menu-bg: var(--vd-bg-primary);
+  --vd-theme-switcher-option-hover-bg: var(--vd-bg-secondary);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme]) {
+    --vd-theme-switcher-menu-bg: var(--vd-bg-primary);
+    --vd-theme-switcher-option-hover-bg: var(--vd-bg-secondary);
+  }
+}
+
+.vd-theme-switcher {
+  position: relative;
+  display: inline-block;
+}
+
+.vd-theme-switcher-toggle {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.375rem;
+  height: 2.375rem;
+  padding: 0;
+  border: 1px solid var(--vd-border-color);
+  border-radius: var(--vd-btn-border-radius, var(--vd-card-border-radius));
+  background: transparent;
+  color: var(--vd-text-secondary);
+  cursor: pointer;
+  font-size: 1.15rem;
+  line-height: 1;
+  transition: color 0.2s, border-color 0.2s, background 0.2s;
+}
+
+.vd-theme-switcher-toggle:hover,
+.vd-theme-switcher-toggle:focus-visible {
+  color: var(--vd-color-primary);
+  border-color: var(--vd-color-primary);
+  background: var(--vd-color-primary-alpha-10);
+  outline: none;
+}
+
+.vd-theme-switcher-menu {
+  position: absolute;
+  top: calc(100% + 0.375rem);
+  left: 0;
+  z-index: var(--vd-theme-switcher-z-index);
+  display: none;
+  flex-direction: column;
+  gap: 0.25rem;
+  min-width: auto;
+  padding: 0.375rem;
+  margin: 0;
+  background: var(--vd-theme-switcher-menu-bg, #ffffff);
+  border: 1px solid var(--vd-theme-switcher-menu-border-color);
+  border-radius: var(--vd-btn-border-radius, var(--vd-card-border-radius));
+  box-shadow: var(--vd-shadow-lg);
+  list-style: none;
+  isolation: isolate;
+  backdrop-filter: none;
+  -webkit-backdrop-filter: none;
+  visibility: hidden;
+  pointer-events: none;
+  transform: translateY(-6px);
+  transition: visibility var(--vd-transition-duration-base, 0.2s) var(--vd-transition-ease, ease),
+              transform var(--vd-transition-duration-base, 0.2s) var(--vd-transition-ease, ease);
+}
+
+.vd-theme-switcher-menu-end .vd-theme-switcher-menu,
+.vd-theme-switcher.vd-theme-switcher-menu-end .vd-theme-switcher-menu {
+  right: 0;
+  left: auto;
+}
+
+.vd-theme-switcher.is-open .vd-theme-switcher-menu,
+.vd-theme-switcher-menu.is-open {
+  display: flex;
+  visibility: visible;
+  pointer-events: auto;
+  transform: translateY(0);
+}
+
+.vd-theme-switcher-option,
+.vd-theme-switcher-menu [data-theme-value] {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 2.375rem;
+  height: 2.375rem;
+  padding: 0;
+  border: 1px solid transparent;
+  border-radius: var(--vd-btn-border-radius-sm, var(--vd-radius-fib-3));
+  background: transparent;
+  color: var(--vd-text-secondary);
+  cursor: pointer;
+  font-size: 1.15rem;
+  line-height: 1;
+  transition: color 0.2s, background 0.2s, border-color 0.2s;
+}
+
+.vd-theme-switcher-option:hover,
+.vd-theme-switcher-option:focus-visible,
+.vd-theme-switcher-menu [data-theme-value]:hover,
+.vd-theme-switcher-menu [data-theme-value]:focus-visible {
+  color: var(--vd-text-primary);
+  background: var(--vd-theme-switcher-option-hover-bg);
+  outline: none;
+}
+
+.vd-theme-switcher-option.is-active,
+.vd-theme-switcher-menu [data-theme-value].is-active {
+  color: var(--vd-theme-switcher-option-active-color);
+  background: var(--vd-theme-switcher-option-active-bg);
+  border-color: var(--vd-color-primary-alpha-20, transparent);
+}

package/css/vanduo.css

@@ -53,6 +53,7 @@
 @import url('components/spinner.css');
 @import url('components/button-group.css');
 @import url('components/theme-customizer.css');
+@import url('components/theme-switcher.css');
 @import url('components/image-box.css');
 @import url('components/doc-tabs.css');
 @import url('components/doc-search.css');

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "1.4.3",
-  "builtAt": "2026-05-28T13:14:25.371Z",
-  "commit": "02ef7f6",
+  "version": "1.4.4",
+  "builtAt": "2026-06-07T19:14:20.877Z",
+  "commit": "781df0d",
   "mode": "development+production"
 }

package/dist/vanduo.cjs.js

@@ -1,4 +1,4 @@
-/*! Vanduo v1.4.3 | Built: 2026-05-28T13:14:25.371Z | git:02ef7f6 | development */
+/*! Vanduo v1.4.4 | Built: 2026-06-07T19:14:20.877Z | git:781df0d | development */
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -201,7 +201,7 @@ module.exports = __toCommonJS(index_exports);
 // js/vanduo.js
 (function() {
   "use strict";
-  const VANDUO_VERSION = true ? "1.4.3" : "0.0.0-dev";
+  const VANDUO_VERSION = true ? "1.4.4" : "0.0.0-dev";
   const hasOwn = Object.prototype.hasOwnProperty;
   const Vanduo2 = {
     version: VANDUO_VERSION,
@@ -486,9 +486,10 @@ module.exports = __toCommonJS(index_exports);
     init: function(root) {
       const snippets = this.queryWithin(root, ".vd-code-snippet");
       snippets.forEach((snippet) => {
-        if (!snippet.dataset.initialized) {
-          this.initSnippet(snippet);
+        if (snippet.dataset.initialized === "true") {
+          return;
         }
+        this.initSnippet(snippet);
       });
     },
     /**
@@ -496,7 +497,9 @@ module.exports = __toCommonJS(index_exports);
      * @param {HTMLElement} snippet - Code snippet container element
      */
     initSnippet: function(snippet) {
-      snippet.dataset.initialized = "true";
+      if (snippet.dataset.initialized === "true") {
+        return;
+      }
       snippet._codeSnippetCleanup = [];
       const toggle = snippet.querySelector(".vd-code-snippet-toggle");
       const content = snippet.querySelector(".vd-code-snippet-content");
@@ -524,6 +527,7 @@ module.exports = __toCommonJS(index_exports);
       lineNumberPanes.forEach((pane) => {
         this.addLineNumbers(pane);
       });
+      snippet.dataset.initialized = "true";
     },
     /**
      * Initialize collapsible functionality
@@ -533,13 +537,14 @@ module.exports = __toCommonJS(index_exports);
      */
     initCollapsible: function(snippet, toggle, content) {
       const isExpanded = snippet.dataset.expanded === "true";
-      toggle.setAttribute("aria-expanded", isExpanded);
-      content.dataset.visible = isExpanded;
+      toggle.setAttribute("aria-expanded", isExpanded ? "true" : "false");
+      content.dataset.visible = isExpanded ? "true" : "false";
       this.addListener(snippet, toggle, "click", () => {
         const expanded = snippet.dataset.expanded === "true";
-        snippet.dataset.expanded = !expanded;
-        toggle.setAttribute("aria-expanded", !expanded);
-        content.dataset.visible = !expanded;
+        const nextExpanded = !expanded;
+        snippet.dataset.expanded = nextExpanded ? "true" : "false";
+        toggle.setAttribute("aria-expanded", nextExpanded ? "true" : "false");
+        content.dataset.visible = nextExpanded ? "true" : "false";
         if (!expanded) {
           const extractPanes = content.querySelectorAll("[data-extract]:not([data-extracted])");
           extractPanes.forEach((pane) => {
@@ -5070,21 +5075,45 @@ module.exports = __toCommonJS(index_exports);
 // js/components/theme-switcher.js
 (function() {
   "use strict";
+  const THEME_MODES = ["system", "light", "dark"];
+  const THEME_ICON_CLASSES = {
+    system: "ph ph-desktop",
+    light: "ph ph-sun",
+    dark: "ph ph-moon"
+  };
+  const THEME_LABELS = {
+    system: "Theme: System",
+    light: "Theme: Light",
+    dark: "Theme: Dark"
+  };
+  const THEME_OPTION_TOOLTIPS = {
+    system: "Use system preference",
+    light: "Light theme",
+    dark: "Dark theme"
+  };
   const ThemeSwitcher = {
     isInitialized: false,
     _mediaQuery: null,
     _onMediaChange: null,
+    menuInstances: /* @__PURE__ */ new Map(),
     getToggles: function(root) {
+      const scope = root || document;
+      const toggles = window.Vanduo && typeof window.Vanduo.queryAll === "function" ? window.Vanduo.queryAll(scope, '[data-toggle="theme"]') : Array.from(scope.querySelectorAll('[data-toggle="theme"]'));
+      return toggles.filter(function(toggle) {
+        return !toggle.closest('.vd-theme-switcher[data-theme-ui="menu"]');
+      });
+    },
+    getMenuSwitchers: function(root) {
+      const scope = root || document;
       if (window.Vanduo && typeof window.Vanduo.queryAll === "function") {
-        return window.Vanduo.queryAll(root, '[data-toggle="theme"]');
+        return window.Vanduo.queryAll(scope, '.vd-theme-switcher[data-theme-ui="menu"]');
       }
-      return Array.from(document.querySelectorAll('[data-toggle="theme"]'));
+      return Array.from(scope.querySelectorAll('.vd-theme-switcher[data-theme-ui="menu"]'));
     },
     init: function(root) {
       this.STORAGE_KEY = "vanduo-theme-preference";
       this.state = {
         preference: this.getPreference()
-        // 'light', 'dark', or 'system'
       };
       if (this.isInitialized) {
         this.applyTheme();
@@ -5101,6 +5130,9 @@ module.exports = __toCommonJS(index_exports);
       return this.getStorageValue(this.STORAGE_KEY, "system");
     },
     setPreference: function(pref) {
+      if (!THEME_MODES.includes(pref)) {
+        return;
+      }
       this.state.preference = pref;
       this.setStorageValue(this.STORAGE_KEY, pref);
       this.applyTheme();
@@ -5154,8 +5186,8 @@ module.exports = __toCommonJS(index_exports);
       };
       this._mediaQuery.addEventListener("change", this._onMediaChange);
     },
-    // Helper to facilitate UI creation if needed, though often UI is in HTML
     renderUI: function(root) {
+      this.renderMenuSwitchers(root);
       const toggles = this.getToggles(root);
       toggles.forEach((toggle) => {
         if (toggle.getAttribute("data-theme-initialized") === "true") {
@@ -5173,7 +5205,7 @@ module.exports = __toCommonJS(index_exports);
           toggle._themeToggleHandler = onChange;
         } else {
           const onClick = () => {
-            const modes = ["system", "light", "dark"];
+            const modes = THEME_MODES;
             const nextIndex = (modes.indexOf(this.state.preference) + 1) % modes.length;
             this.setPreference(modes[nextIndex]);
           };
@@ -5182,6 +5214,188 @@ module.exports = __toCommonJS(index_exports);
         }
         toggle.setAttribute("data-theme-initialized", "true");
       });
+      this.updateUI(root);
+    },
+    renderMenuSwitchers: function(root) {
+      const switchers = this.getMenuSwitchers(root);
+      switchers.forEach((switcher) => {
+        if (switcher.getAttribute("data-theme-menu-initialized") === "true") {
+          return;
+        }
+        const toggle = switcher.querySelector(".vd-theme-switcher-toggle");
+        const menu = switcher.querySelector(".vd-theme-switcher-menu");
+        if (!toggle || !menu) {
+          return;
+        }
+        const options = menu.querySelectorAll("[data-theme-value]");
+        const cleanupFunctions = [];
+        toggle.setAttribute("aria-haspopup", "true");
+        toggle.setAttribute("aria-expanded", "false");
+        menu.setAttribute("aria-hidden", "true");
+        const toggleClickHandler = (e) => {
+          e.preventDefault();
+          e.stopPropagation();
+          this.toggleMenu(switcher, toggle, menu);
+        };
+        toggle.addEventListener("click", toggleClickHandler);
+        cleanupFunctions.push(() => toggle.removeEventListener("click", toggleClickHandler));
+        options.forEach((option) => {
+          const optionClickHandler = (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            const value = option.getAttribute("data-theme-value");
+            if (value) {
+              this.setPreference(value);
+            }
+            this.closeMenu(switcher, toggle, menu);
+          };
+          option.addEventListener("click", optionClickHandler);
+          cleanupFunctions.push(() => option.removeEventListener("click", optionClickHandler));
+          const optionKeydownHandler = (e) => {
+            if (e.key === "Enter" || e.key === " ") {
+              e.preventDefault();
+              optionClickHandler(e);
+            }
+          };
+          option.addEventListener("keydown", optionKeydownHandler);
+          cleanupFunctions.push(() => option.removeEventListener("keydown", optionKeydownHandler));
+        });
+        const toggleKeydownHandler = (e) => {
+          if (e.key === "ArrowDown" || e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            if (!menu.classList.contains("is-open")) {
+              this.openMenu(switcher, toggle, menu);
+            }
+          } else if (e.key === "Escape" && menu.classList.contains("is-open")) {
+            e.preventDefault();
+            this.closeMenu(switcher, toggle, menu);
+          }
+        };
+        toggle.addEventListener("keydown", toggleKeydownHandler);
+        cleanupFunctions.push(() => toggle.removeEventListener("keydown", toggleKeydownHandler));
+        const menuKeydownHandler = (e) => {
+          this.handleMenuKeydown(e, switcher, toggle, menu, options);
+        };
+        menu.addEventListener("keydown", menuKeydownHandler);
+        cleanupFunctions.push(() => menu.removeEventListener("keydown", menuKeydownHandler));
+        const documentClickHandler = (e) => {
+          if (!switcher.contains(e.target) && menu.classList.contains("is-open")) {
+            this.closeMenu(switcher, toggle, menu);
+          }
+        };
+        document.addEventListener("click", documentClickHandler);
+        cleanupFunctions.push(() => document.removeEventListener("click", documentClickHandler));
+        this.menuInstances.set(switcher, { toggle, menu, cleanup: cleanupFunctions });
+        switcher.setAttribute("data-theme-menu-initialized", "true");
+        this.initMenuTooltips(switcher);
+      });
+    },
+    initMenuTooltips: function(switcher) {
+      const tooltips = window.Vanduo && typeof window.Vanduo.getComponent === "function" ? window.Vanduo.getComponent("tooltips") : null;
+      if (tooltips && typeof tooltips.init === "function") {
+        tooltips.init(switcher);
+      }
+    },
+    closeOtherMenus: function(exceptMenu) {
+      this.menuInstances.forEach((instance, switcher) => {
+        if (instance.menu !== exceptMenu && instance.menu.classList.contains("is-open")) {
+          this.closeMenu(switcher, instance.toggle, instance.menu);
+        }
+      });
+    },
+    toggleMenu: function(switcher, toggle, menu) {
+      if (menu.classList.contains("is-open")) {
+        this.closeMenu(switcher, toggle, menu);
+      } else {
+        this.openMenu(switcher, toggle, menu);
+      }
+    },
+    openMenu: function(switcher, toggle, menu) {
+      this.closeOtherMenus(menu);
+      switcher.classList.add("is-open");
+      menu.classList.add("is-open");
+      toggle.setAttribute("aria-expanded", "true");
+      menu.setAttribute("aria-hidden", "false");
+      const activeOption = menu.querySelector("[data-theme-value].is-active") || menu.querySelector("[data-theme-value]");
+      if (activeOption) {
+        setTimeout(() => activeOption.focus(), 0);
+      }
+    },
+    closeMenu: function(switcher, toggle, menu) {
+      switcher.classList.remove("is-open");
+      menu.classList.remove("is-open");
+      toggle.setAttribute("aria-expanded", "false");
+      menu.setAttribute("aria-hidden", "true");
+    },
+    handleMenuKeydown: function(e, switcher, toggle, menu, options) {
+      const items = Array.from(options);
+      const currentIndex = items.indexOf(document.activeElement);
+      if (e.key === "Escape") {
+        e.preventDefault();
+        this.closeMenu(switcher, toggle, menu);
+        toggle.focus();
+        return;
+      }
+      if (e.key === "ArrowDown") {
+        e.preventDefault();
+        const nextIndex = currentIndex < items.length - 1 ? currentIndex + 1 : 0;
+        items[nextIndex].focus();
+        return;
+      }
+      if (e.key === "ArrowUp") {
+        e.preventDefault();
+        const prevIndex = currentIndex > 0 ? currentIndex - 1 : items.length - 1;
+        items[prevIndex].focus();
+      }
+    },
+    updateMenuSwitcher: function(switcher) {
+      const toggle = switcher.querySelector(".vd-theme-switcher-toggle");
+      const menu = switcher.querySelector(".vd-theme-switcher-menu");
+      if (!toggle || !menu) {
+        return;
+      }
+      const pref = this.state.preference;
+      const icon = toggle.querySelector("[data-theme-icon]");
+      const label = THEME_LABELS[pref] || THEME_LABELS.system;
+      if (icon) {
+        icon.className = THEME_ICON_CLASSES[pref] || THEME_ICON_CLASSES.system;
+      }
+      toggle.setAttribute("aria-label", label);
+      if (toggle.hasAttribute("data-tooltip")) {
+        toggle.setAttribute("data-tooltip", label);
+        this.refreshTooltipContent(toggle, label);
+      }
+      menu.querySelectorAll("[data-theme-value]").forEach((option) => {
+        const value = option.getAttribute("data-theme-value");
+        const isActive = value === pref;
+        option.classList.toggle("is-active", isActive);
+        option.setAttribute("aria-checked", isActive ? "true" : "false");
+        const tooltipText = THEME_OPTION_TOOLTIPS[value];
+        if (tooltipText && option.hasAttribute("data-tooltip")) {
+          option.setAttribute("data-tooltip", tooltipText);
+          this.refreshTooltipContent(option, tooltipText);
+        }
+      });
+    },
+    refreshTooltipContent: function(element, text) {
+      const tooltips = window.Vanduo && typeof window.Vanduo.getComponent === "function" ? window.Vanduo.getComponent("tooltips") : null;
+      if (!tooltips || typeof tooltips.update !== "function") {
+        return;
+      }
+      tooltips.update(element, text);
+    },
+    updateCycleToggle: function(toggle) {
+      const pref = this.state.preference;
+      const icon = toggle.querySelector("[data-theme-icon]");
+      const label = THEME_LABELS[pref] || THEME_LABELS.system;
+      if (icon) {
+        icon.className = THEME_ICON_CLASSES[pref] || THEME_ICON_CLASSES.system;
+      }
+      toggle.setAttribute("aria-label", label);
+      if (toggle.hasAttribute("data-tooltip")) {
+        toggle.setAttribute("data-tooltip", label);
+        this.refreshTooltipContent(toggle, label);
+      }
     },
     updateUI: function(root) {
       const toggles = this.getToggles(root);
@@ -5193,11 +5407,26 @@ module.exports = __toCommonJS(index_exports);
           if (span) {
             span.textContent = this.state.preference.charAt(0).toUpperCase() + this.state.preference.slice(1);
           }
+          if (toggle.querySelector("[data-theme-icon]")) {
+            this.updateCycleToggle(toggle);
+          }
         }
       });
+      this.getMenuSwitchers(root).forEach((switcher) => {
+        this.updateMenuSwitcher(switcher);
+      });
     },
     destroyAll: function(root) {
       const scope = root || document;
+      this.getMenuSwitchers(scope).forEach((switcher) => {
+        const instance = this.menuInstances.get(switcher);
+        if (instance) {
+          instance.cleanup.forEach((fn) => fn());
+          this.closeMenu(switcher, instance.toggle, instance.menu);
+          this.menuInstances.delete(switcher);
+        }
+        switcher.removeAttribute("data-theme-menu-initialized");
+      });
       const toggles = this.getToggles(scope).filter(function(toggle) {
         return toggle.getAttribute("data-theme-initialized") === "true";
       });