@lilydesignsystem/nunjucks-text-size-picker 0.1.1 → 0.2.0

package/dist/index.d.ts

@@ -70,6 +70,138 @@ function safeStorageSet(key, value) {
   }
 }
 
+// ---------------------------------------------------------------------
+// Tooltip (purely visual; the same text is already the button's
+// aria-label, so it is NOT linked with aria-describedby). Visible iff the
+// popup is closed, it has not been dismissed with Escape, and the pointer
+// is over the button or the tooltip (hoverable, WCAG 1.4.13) or the
+// button has KEYBOARD focus (:focus-visible; a mouse click's focus does
+// not count). Never interferes with the picker's own keys or closing.
+// Idempotent: wiring the same tooltip twice replaces the first wiring.
+// ---------------------------------------------------------------------
+
+const tooltipWirings = new WeakMap();
+
+function wireTooltip(root, button, selector, popup) {
+  const tooltip = root.querySelector(selector);
+  if (!tooltip || !button || !popup) return () => {};
+  const previous = tooltipWirings.get(tooltip);
+  if (previous) previous();
+
+  let hoverButton = false;
+  let hoverTooltip = false;
+  let focusButton = false;
+  let dismissed = false;
+
+  // WCAG 1.4.13 "dismissable": Escape must work wherever focus is while
+  // the tooltip is visible (pointer hover alone leaves focus elsewhere).
+  // The document listener exists only while visible; never preventDefault
+  // or stopPropagation, never move focus.
+  let docListening = false;
+  const onDocumentKeydown = (event) => {
+    if (event.key === "Escape") {
+      dismissed = true;
+      update();
+    }
+  };
+  function syncDocumentListener() {
+    const want = !tooltip.hidden;
+    if (want && !docListening) {
+      document.addEventListener("keydown", onDocumentKeydown);
+      docListening = true;
+    } else if (!want && docListening) {
+      document.removeEventListener("keydown", onDocumentKeydown);
+      docListening = false;
+    }
+  }
+
+  function update() {
+    tooltip.hidden = !(
+      popup.hidden &&
+      !dismissed &&
+      (hoverButton || hoverTooltip || focusButton)
+    );
+    syncDocumentListener();
+  }
+
+  const onButtonEnter = () => {
+    hoverButton = true;
+    dismissed = false;
+    update();
+  };
+  const onButtonLeave = () => {
+    hoverButton = false;
+    update();
+  };
+  const onTooltipEnter = () => {
+    hoverTooltip = true;
+    update();
+  };
+  const onTooltipLeave = () => {
+    hoverTooltip = false;
+    update();
+  };
+  const onButtonFocus = () => {
+    try {
+      focusButton = button.matches(":focus-visible");
+    } catch {
+      focusButton = true; // engine without :focus-visible
+    }
+    update();
+  };
+  const onButtonBlur = () => {
+    focusButton = false;
+    dismissed = false;
+    update();
+  };
+  const onButtonKeydown = (event) => {
+    if (event.key === "Escape" && !tooltip.hidden) dismissed = true;
+    update();
+  };
+  const onButtonClick = () => {
+    hoverButton = false;
+    update();
+  };
+
+  button.addEventListener("mouseenter", onButtonEnter);
+  button.addEventListener("mouseleave", onButtonLeave);
+  button.addEventListener("focus", onButtonFocus);
+  button.addEventListener("blur", onButtonBlur);
+  button.addEventListener("keydown", onButtonKeydown);
+  button.addEventListener("click", onButtonClick);
+  tooltip.addEventListener("mouseenter", onTooltipEnter);
+  tooltip.addEventListener("mouseleave", onTooltipLeave);
+
+  // The popup's own open/close (including the programmatic API) flips its
+  // `hidden` attribute; follow it so the tooltip never shows over it.
+  const observer =
+    typeof MutationObserver === "function"
+      ? new MutationObserver(update)
+      : null;
+  if (observer) observer.observe(popup, { attributes: true, attributeFilter: ["hidden"] });
+
+  update();
+
+  const destroy = () => {
+    button.removeEventListener("mouseenter", onButtonEnter);
+    button.removeEventListener("mouseleave", onButtonLeave);
+    button.removeEventListener("focus", onButtonFocus);
+    button.removeEventListener("blur", onButtonBlur);
+    button.removeEventListener("keydown", onButtonKeydown);
+    button.removeEventListener("click", onButtonClick);
+    tooltip.removeEventListener("mouseenter", onTooltipEnter);
+    tooltip.removeEventListener("mouseleave", onTooltipLeave);
+    if (observer) observer.disconnect();
+    if (docListening) {
+      document.removeEventListener("keydown", onDocumentKeydown);
+      docListening = false;
+    }
+    if (tooltipWirings.get(tooltip) === destroy) tooltipWirings.delete(tooltip);
+  };
+  tooltipWirings.set(tooltip, destroy);
+  return destroy;
+}
+
 /**
  * Wire one rendered TextSizePicker root.
  *
@@ -276,9 +408,12 @@ function initTextSizePicker(root, opts = {}) {
 
   if (initial) applySize(initial);
 
+  const tooltipDestroy = wireTooltip(root, button, ".text-size-picker-tooltip", list);
+
   return {
     setSize: applySize,
     destroy: () => {
+      tooltipDestroy();
       keyboard.destroy();
       button.removeEventListener("click", onButtonClick);
       button.removeEventListener("keydown", onButtonKeydown);

package/dist/index.js

@@ -16,6 +16,106 @@ function safeStorageSet(key, value) {
   } catch (_e) {
   }
 }
+var tooltipWirings = /* @__PURE__ */ new WeakMap();
+function wireTooltip(root, button, selector, popup) {
+  const tooltip = root.querySelector(selector);
+  if (!tooltip || !button || !popup) return () => {
+  };
+  const previous = tooltipWirings.get(tooltip);
+  if (previous) previous();
+  let hoverButton = false;
+  let hoverTooltip = false;
+  let focusButton = false;
+  let dismissed = false;
+  let docListening = false;
+  const onDocumentKeydown = (event) => {
+    if (event.key === "Escape") {
+      dismissed = true;
+      update();
+    }
+  };
+  function syncDocumentListener() {
+    const want = !tooltip.hidden;
+    if (want && !docListening) {
+      document.addEventListener("keydown", onDocumentKeydown);
+      docListening = true;
+    } else if (!want && docListening) {
+      document.removeEventListener("keydown", onDocumentKeydown);
+      docListening = false;
+    }
+  }
+  function update() {
+    tooltip.hidden = !(popup.hidden && !dismissed && (hoverButton || hoverTooltip || focusButton));
+    syncDocumentListener();
+  }
+  const onButtonEnter = () => {
+    hoverButton = true;
+    dismissed = false;
+    update();
+  };
+  const onButtonLeave = () => {
+    hoverButton = false;
+    update();
+  };
+  const onTooltipEnter = () => {
+    hoverTooltip = true;
+    update();
+  };
+  const onTooltipLeave = () => {
+    hoverTooltip = false;
+    update();
+  };
+  const onButtonFocus = () => {
+    try {
+      focusButton = button.matches(":focus-visible");
+    } catch {
+      focusButton = true;
+    }
+    update();
+  };
+  const onButtonBlur = () => {
+    focusButton = false;
+    dismissed = false;
+    update();
+  };
+  const onButtonKeydown = (event) => {
+    if (event.key === "Escape" && !tooltip.hidden) dismissed = true;
+    update();
+  };
+  const onButtonClick = () => {
+    hoverButton = false;
+    update();
+  };
+  button.addEventListener("mouseenter", onButtonEnter);
+  button.addEventListener("mouseleave", onButtonLeave);
+  button.addEventListener("focus", onButtonFocus);
+  button.addEventListener("blur", onButtonBlur);
+  button.addEventListener("keydown", onButtonKeydown);
+  button.addEventListener("click", onButtonClick);
+  tooltip.addEventListener("mouseenter", onTooltipEnter);
+  tooltip.addEventListener("mouseleave", onTooltipLeave);
+  const observer = typeof MutationObserver === "function" ? new MutationObserver(update) : null;
+  if (observer) observer.observe(popup, { attributes: true, attributeFilter: ["hidden"] });
+  update();
+  const destroy = () => {
+    button.removeEventListener("mouseenter", onButtonEnter);
+    button.removeEventListener("mouseleave", onButtonLeave);
+    button.removeEventListener("focus", onButtonFocus);
+    button.removeEventListener("blur", onButtonBlur);
+    button.removeEventListener("keydown", onButtonKeydown);
+    button.removeEventListener("click", onButtonClick);
+    tooltip.removeEventListener("mouseenter", onTooltipEnter);
+    tooltip.removeEventListener("mouseleave", onTooltipLeave);
+    if (observer) observer.disconnect();
+    if (docListening) {
+      document.removeEventListener("keydown", onDocumentKeydown);
+      docListening = false;
+    }
+    if (tooltipWirings.get(tooltip) === destroy) tooltipWirings.delete(tooltip);
+  };
+  tooltipWirings.set(tooltip, destroy);
+  return destroy;
+}
 function initTextSizePicker(root, opts = {}) {
   const noop = { setSize: () => {
   }, destroy: () => {
@@ -129,9 +229,11 @@ function initTextSizePicker(root, opts = {}) {
   if (!initial && values.includes("medium")) initial = "medium";
   if (!initial && values.length > 0) initial = values[0];
   if (initial) applySize(initial);
+  const tooltipDestroy = wireTooltip(root, button, ".text-size-picker-tooltip", list);
   return {
     setSize: applySize,
     destroy: () => {
+      tooltipDestroy();
       keyboard.destroy();
       button.removeEventListener("click", onButtonClick);
       button.removeEventListener("keydown", onButtonKeydown);

package/dist/text-size-picker.njk

@@ -86,6 +86,7 @@
 <button type="button" class="text-size-picker-button" aria-label="{{ opts.label }}" aria-haspopup="listbox" aria-expanded="false" aria-controls="{{ listId }}" data-lily-text-size-picker-button>
 {%- if caller %}{{ caller() }}{% else %}<svg class="text-size-picker-icon" viewBox="0 0 16 16" aria-hidden="true" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round" width="1.05rem" height="1.05rem"><path d="M4 13 7.2 3h1.6L12 13M5.4 9.5h5.2"/></svg>{% endif -%}
 </button>
+<div class="text-size-picker-tooltip" role="tooltip" id="{{ id }}-tooltip" hidden>{{ opts.label }}</div>
 <ul class="text-size-picker-list" id="{{ listId }}" role="listbox" aria-label="{{ opts.label }}" tabindex="-1" hidden data-lily-text-size-picker-list>
 {%- for slug in opts.sizes -%}
   <li class="text-size-picker-option" id="{{ id }}-option-{{ loop.index0 }}" role="option" aria-selected="{{ 'true' if slug == selected else 'false' }}" data-value="{{ slug }}">

package/index.md

@@ -295,6 +295,10 @@ acceptance criterion in [spec/index.md §7](./spec/index.md#7-testing-acceptance
 MIT or Apache-2.0 or GPL-2.0 or GPL-3.0 or BSD-3-Clause. Contact
 joel@joelparkerhenderson.com for other terms.
 
+## Tooltip
+
+`.text-size-picker-tooltip` (`<div role="tooltip" id="{id}-tooltip" hidden>`) is rendered right after the icon button, holding the button's `label`. `text-size-picker.client.js` shows it on pointer hover (button or tooltip) or keyboard focus (`:focus-visible`), hides it on `Escape` (focus stays) and never shows it while the popup is open. Not linked with `aria-describedby`. See `spec/index.md` (Tooltip).
+
 ---
 
 Lily™ and Lily Design System™ are trademarks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lilydesignsystem/nunjucks-text-size-picker",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "engines": {
     "node": "=26"
   },