@lilydesignsystem/web-components-theme-picker 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -7,7 +7,14 @@
  *
  * The control is an icon button that opens a dropdown listbox
  * (WAI-ARIA APG listbox pattern). It is not a native `<select>`.
+ *
+ * Depends on `@lilydesignsystem/web-components-headless`'s
+ * `<lily-icon-button>` for the trigger button, composed in `#render()`
+ * rather than hand-rolled. Imported here (not only from `index.ts`) so
+ * `lily-icon-button` is registered regardless of which module a
+ * consumer (or this package's own tests) imports first.
  */
+
 /**
  * Default button icon: a bundled SVG (contrast/half-circle), not a
  * Unicode character. Reversed 2026-09-16 from the font-dependent-glyph
@@ -70,6 +77,8 @@ declare function nextThemePickerId(): string;
 declare class ThemePicker extends HTMLElement {
     #private;
     static get observedAttributes(): string[];
+    /** id of the rendered `<div class="theme-picker-tooltip">`. */
+    get tooltipId(): string;
     get label(): string;
     set label(v: string);
     get themesUrl(): string;

package/dist/index.js

@@ -1,4 +1,8 @@
+// lily-design-system-web-components-theme-picker/index.ts
+import "@lilydesignsystem/web-components-headless";
+
 // lily-design-system-web-components-theme-picker/theme-picker.ts
+import "@lilydesignsystem/web-components-headless";
 var SVG_NS = "http://www.w3.org/2000/svg";
 function themeName(theme) {
   return theme.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
@@ -45,6 +49,8 @@ var ThemePicker = class extends HTMLElement {
   // Rendered-DOM references. Null until #render() has run.
   #rootEl = null;
   #inputEl = null;
+  // The real <button>, nested one level inside the composed
+  // <lily-icon-button> host (see #render()) — not #rootEl's direct child.
   #buttonEl = null;
   #listEl = null;
   #optionEls = [];
@@ -53,6 +59,59 @@ var ThemePicker = class extends HTMLElement {
   #activeIndex = -1;
   // Stable ids for the button/listbox aria wiring.
   #baseId = nextThemePickerId();
+  // Tooltip: shown while the pointer is over the button or the tooltip
+  // itself (hoverable, WCAG 1.4.13) or while the button has keyboard
+  // focus; Escape dismisses it without moving focus; never shown while
+  // the popup is open, since the popup then explains the control.
+  #tooltipEl = null;
+  #hoverButton = false;
+  #hoverTooltip = false;
+  #focusButton = false;
+  #tipDismissed = false;
+  // Escape anywhere dismisses a visible tooltip (WCAG 1.4.13: dismissable
+  // without moving pointer or focus), so a hover-only tooltip (focus
+  // elsewhere) still closes. The document listener exists only while
+  // the tooltip is visible; it neither prevents default nor stops
+  // propagation, and never moves focus.
+  #tipDocListening = false;
+  #onTipDocKeydown = (event) => {
+    if (event.key === "Escape" && this.#tooltipVisible()) {
+      this.#tipDismissed = true;
+      this.#syncTooltip();
+    }
+  };
+  #setTipDocListener(on) {
+    if (on === this.#tipDocListening || typeof document === "undefined") return;
+    this.#tipDocListening = on;
+    if (on) document.addEventListener("keydown", this.#onTipDocKeydown);
+    else document.removeEventListener("keydown", this.#onTipDocKeydown);
+  }
+  #tooltipVisible() {
+    return !this.#open && !this.#tipDismissed && (this.#hoverButton || this.#hoverTooltip || this.#focusButton);
+  }
+  /** Write the tooltip's text and `hidden` in place; idempotent. */
+  #syncTooltip() {
+    const el = this.#tooltipEl;
+    if (!el) return;
+    if (el.textContent !== this.label) el.textContent = this.label;
+    const hide = !this.#tooltipVisible();
+    this.#setTipDocListener(!hide);
+    if (el.hasAttribute("hidden") !== hide) {
+      if (hide) el.setAttribute("hidden", "");
+      else el.removeAttribute("hidden");
+    }
+  }
+  #resetTooltip() {
+    this.#setTipDocListener(false);
+    this.#hoverButton = false;
+    this.#hoverTooltip = false;
+    this.#focusButton = false;
+    this.#tipDismissed = false;
+  }
+  /** id of the rendered `<div class="theme-picker-tooltip">`. */
+  get tooltipId() {
+    return `${this.#baseId}-tooltip`;
+  }
   // Typeahead buffer: APG listbox behaviour. Reset after a pause.
   #typeahead = "";
   #typeaheadTimer;
@@ -250,6 +309,7 @@ var ThemePicker = class extends HTMLElement {
     }
   }
   disconnectedCallback() {
+    this.#resetTooltip();
     document.removeEventListener("click", this.#onDocumentClick);
     clearTimeout(this.#typeaheadTimer);
     this.#appliedValue = "";
@@ -459,6 +519,7 @@ var ThemePicker = class extends HTMLElement {
    */
   #syncState() {
     if (!this.#rootEl) return;
+    this.#syncTooltip();
     const value = this.value;
     if (this.#inputEl) this.#inputEl.value = value;
     if (this.#buttonEl) {
@@ -496,20 +557,68 @@ var ThemePicker = class extends HTMLElement {
     input.name = this.name;
     input.value = this.value;
     root.appendChild(input);
-    const button = document.createElement("button");
-    button.type = "button";
-    button.className = "theme-picker-button";
-    button.setAttribute("aria-label", this.label);
-    button.setAttribute("aria-haspopup", "listbox");
-    button.setAttribute("aria-expanded", "false");
-    button.setAttribute("aria-controls", this.listId);
-    button.appendChild(this.renderButtonContent());
-    button.addEventListener("click", () => {
+    const iconButtonHost = document.createElement("lily-icon-button");
+    iconButtonHost.setAttribute("base-class", "theme-picker-button");
+    iconButtonHost.setAttribute("label", this.label);
+    iconButtonHost.setAttribute("aria-haspopup", "listbox");
+    iconButtonHost.setAttribute("aria-expanded", "false");
+    iconButtonHost.setAttribute("aria-controls", this.listId);
+    iconButtonHost.appendChild(this.renderButtonContent());
+    iconButtonHost.addEventListener("click", () => {
       if (this.#open) this.closeList();
       else this.openList();
     });
-    button.addEventListener("keydown", this.#onButtonKeydown);
-    root.appendChild(button);
+    iconButtonHost.addEventListener("keydown", this.#onButtonKeydown);
+    root.appendChild(iconButtonHost);
+    this.#resetTooltip();
+    const tooltip = document.createElement("div");
+    tooltip.className = "theme-picker-tooltip";
+    tooltip.setAttribute("role", "tooltip");
+    tooltip.id = this.tooltipId;
+    tooltip.setAttribute("hidden", "");
+    tooltip.textContent = this.label;
+    tooltip.addEventListener("mouseenter", () => {
+      this.#hoverTooltip = true;
+      this.#syncTooltip();
+    });
+    tooltip.addEventListener("mouseleave", () => {
+      this.#hoverTooltip = false;
+      this.#syncTooltip();
+    });
+    this.#tooltipEl = tooltip;
+    iconButtonHost.addEventListener("mouseenter", () => {
+      this.#hoverButton = true;
+      this.#tipDismissed = false;
+      this.#syncTooltip();
+    });
+    iconButtonHost.addEventListener("mouseleave", () => {
+      this.#hoverButton = false;
+      this.#syncTooltip();
+    });
+    iconButtonHost.addEventListener("click", () => {
+      this.#hoverButton = false;
+      this.#syncTooltip();
+    });
+    iconButtonHost.addEventListener("focusin", () => {
+      try {
+        this.#focusButton = this.#buttonEl?.matches(":focus-visible") ?? false;
+      } catch {
+        this.#focusButton = true;
+      }
+      this.#syncTooltip();
+    });
+    iconButtonHost.addEventListener("focusout", () => {
+      this.#focusButton = false;
+      this.#tipDismissed = false;
+      this.#syncTooltip();
+    });
+    iconButtonHost.addEventListener("keydown", (event) => {
+      if (event.key === "Escape" && this.#tooltipVisible()) {
+        this.#tipDismissed = true;
+        this.#syncTooltip();
+      }
+    });
+    root.appendChild(tooltip);
     const list = document.createElement("ul");
     list.className = "theme-picker-list";
     list.id = this.listId;
@@ -533,10 +642,10 @@ var ThemePicker = class extends HTMLElement {
     root.appendChild(list);
     this.#rootEl = root;
     this.#inputEl = input;
-    this.#buttonEl = button;
     this.#listEl = list;
     this.#optionEls = optionEls;
     this.replaceChildren(root);
+    this.#buttonEl = iconButtonHost.querySelector("button");
   }
 };
 function parseCsv(s) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lilydesignsystem/web-components-theme-picker",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "engines": {
     "node": "=26"
   },
@@ -23,6 +23,9 @@
   "scripts": {
     "prepublishOnly": "cd .. && npm run build"
   },
+  "dependencies": {
+    "@lilydesignsystem/web-components-headless": "^0.1.0"
+  },
   "keywords": [
     "lily",
     "design",