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

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { createListboxKeyboard } from '@lilydesignsystem/nunjucks-listbox-behavior';
+
 // TextSizePicker client-side runtime.
 //
 // Pairs with text-size-picker.njk. The macro renders the markup with
@@ -5,9 +7,11 @@
 // the browser and owns two things:
 //
 // A. The listbox INTERACTION (new in the icon-button release): open /
-//    close, focus movement, the APG listbox keyboard contract, and
-//    typeahead. None of this exists in the server markup — the button
-//    is inert until this module runs. See docs/ssr.md.
+//    close and focus movement here; the APG listbox keyboard contract
+//    itself is delegated to the shared
+//    @lilydesignsystem/nunjucks-listbox-behavior module. None of this
+//    exists in the server markup — the button is inert until this
+//    module runs. See docs/ssr.md.
 //
 // B. The text-size LIFECYCLE (unchanged):
 //   0. Read the consumer's `value` prop from
@@ -31,8 +35,6 @@
 //
 // See spec/index.md §4.3 (client.js exports), §5 (behaviour).
 
-/** How long the typeahead buffer survives between keystrokes, in ms. */
-const TYPEAHEAD_RESET_MS = 500;
 
 /**
  * Resolve a size slug to its display label: each hyphen-separated word
@@ -68,11 +70,136 @@ function safeStorageSet(key, value) {
   }
 }
 
-/** jsdom and older browsers do not always implement scrollIntoView. */
-function scrollIntoViewIfPossible(el) {
-  if (el && typeof el.scrollIntoView === "function") {
-    el.scrollIntoView({ block: "nearest" });
+// ---------------------------------------------------------------------
+// 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;
 }
 
 /**
@@ -93,7 +220,6 @@ function initTextSizePicker(root, opts = {}) {
 
   const options = Array.from(list.querySelectorAll('[role="option"]'));
   const values = options.map((o) => o.getAttribute("data-value") || "");
-  const labels = options.map((o) => (o.textContent || "").trim());
 
   const storageKey =
     root.getAttribute("data-lily-text-size-picker-storage-key") || "";
@@ -106,9 +232,6 @@ function initTextSizePicker(root, opts = {}) {
 
   let current = "";
   let open = false;
-  let activeIndex = -1;
-  let typeahead = "";
-  let typeaheadTimer;
 
   // -----------------------------------------------------------------
   // Applying a size
@@ -140,22 +263,13 @@ function initTextSizePicker(root, opts = {}) {
 
   // -----------------------------------------------------------------
   // Open / close / active-option movement
+  //
+  // Arrow move/clamp, Home/End, typeahead, PageUp/PageDown, and
+  // Enter/Space/Escape/Tab are owned by the shared listbox-behavior
+  // controller below (`keyboard`); this picker only decides what
+  // open/close/choose mean.
   // -----------------------------------------------------------------
 
-  function setActive(index) {
-    activeIndex = index;
-    options.forEach((o, i) => {
-      if (i === index) o.setAttribute("data-active", "");
-      else o.removeAttribute("data-active");
-    });
-    if (index >= 0 && options[index]) {
-      list.setAttribute("aria-activedescendant", options[index].id);
-      scrollIntoViewIfPossible(options[index]);
-    } else {
-      list.removeAttribute("aria-activedescendant");
-    }
-  }
-
   function openList(startIndex) {
     const selected = values.indexOf(current);
     // An empty list has no option to activate; -1 keeps
@@ -172,7 +286,7 @@ function initTextSizePicker(root, opts = {}) {
     open = true;
     list.hidden = false;
     button.setAttribute("aria-expanded", "true");
-    setActive(start);
+    keyboard.setActive(start);
     // Focus moves to the listbox; the active option is conveyed via
     // aria-activedescendant, per the APG listbox pattern.
     list.focus({ preventScroll: true });
@@ -183,7 +297,7 @@ function initTextSizePicker(root, opts = {}) {
     open = false;
     list.hidden = true;
     button.setAttribute("aria-expanded", "false");
-    setActive(-1);
+    keyboard.setActive(-1);
     if (refocus) button.focus({ preventScroll: true });
   }
 
@@ -193,39 +307,26 @@ function initTextSizePicker(root, opts = {}) {
     closeList();
   }
 
-  function moveActive(delta) {
-    if (options.length === 0) return;
-    // Clamp rather than wrap, matching the canonical Svelte helper.
-    const next = Math.min(Math.max(activeIndex + delta, 0), options.length - 1);
-    setActive(next);
-  }
-
-  function runTypeahead(char) {
-    const lower = char.toLowerCase();
-    // APG listbox typeahead: a single character moves to the NEXT
-    // option starting with it, and repeating that character keeps
-    // cycling. Only a buffer of differing characters refines the
-    // match, and that buffer stays anchored on the active option.
-    const sameCharRun =
-      typeahead === "" || Array.from(typeahead).every((c) => c === lower);
-    typeahead += lower;
-    clearTimeout(typeaheadTimer);
-    typeaheadTimer = setTimeout(() => {
-      typeahead = "";
-    }, TYPEAHEAD_RESET_MS);
-    const query = sameCharRun ? lower : typeahead;
-    const anchor = activeIndex < 0 ? 0 : activeIndex;
-    const start = sameCharRun ? anchor + 1 : anchor;
-    // Search forward, wrapping once — typeahead wraps even though the
-    // arrows clamp, or options above the cursor would be untypable.
-    for (let n = 0; n < options.length; n++) {
-      const i = (start + n) % options.length;
-      if (labels[i].toLowerCase().startsWith(query)) {
-        setActive(i);
-        return;
-      }
-    }
-  }
+  const keyboard = createListboxKeyboard(list, {
+    clamp: true,
+    typeahead: true,
+    pageSize: 10,
+    onActivate: choose,
+    onEscape: () => closeList(),
+    onTabOut: () => {
+      // Tab moves on — but focus goes to the button FIRST, without
+      // cancelling the key (the shared controller never prevents Tab's
+      // default). Hiding the focused list drops focus to <body>, and
+      // the browser then computes the default Tab move from the top of
+      // the document, so tabbing out of an open picker teleported the
+      // user to the page's first tab stop. From the button, the default
+      // Tab lands exactly where leaving the picker should. Guard the
+      // METHOD, not just the element: this shape has bitten these
+      // helpers before.
+      button?.focus?.({ preventScroll: true });
+      closeList(false);
+    },
+  });
 
   // -----------------------------------------------------------------
   // Event handlers
@@ -251,66 +352,6 @@ function initTextSizePicker(root, opts = {}) {
     }
   }
 
-  function onListKeydown(event) {
-    switch (event.key) {
-      case "ArrowDown":
-        event.preventDefault();
-        moveActive(1);
-        break;
-      case "ArrowUp":
-        event.preventDefault();
-        moveActive(-1);
-        break;
-      case "Home":
-        event.preventDefault();
-        setActive(0);
-        break;
-      case "End":
-        event.preventDefault();
-        setActive(options.length - 1);
-        break;
-      case "Enter":
-      case " ":
-        event.preventDefault();
-        if (activeIndex >= 0) choose(activeIndex);
-        break;
-      case "Escape":
-        event.preventDefault();
-        closeList();
-        break;
-      case "PageUp":
-        event.preventDefault();
-        moveActive(-10);
-        break;
-      case "PageDown":
-        // ±10, clamped: an APG-optional key for long lists.
-        event.preventDefault();
-        moveActive(10);
-        break;
-      case "Tab":
-        // Tab moves on — but focus goes to the button FIRST, without
-        // cancelling the key. Hiding the focused list drops focus to
-        // <body>, and the browser then computes the default Tab move
-        // from the top of the document, so tabbing out of an open
-        // picker teleported the user to the page's first tab stop.
-        // From the button, the default Tab lands exactly where leaving
-        // the picker should. Guard the METHOD, not just the element:
-        // this shape has bitten these helpers before.
-        button?.focus?.({ preventScroll: true });
-        closeList(false);
-        break;
-      default:
-        if (
-          event.key.length === 1 &&
-          !event.ctrlKey &&
-          !event.metaKey &&
-          !event.altKey
-        ) {
-          runTypeahead(event.key);
-        }
-    }
-  }
-
   function onListClick(event) {
     const li =
       event.target && event.target.closest
@@ -335,7 +376,6 @@ function initTextSizePicker(root, opts = {}) {
 
   button.addEventListener("click", onButtonClick);
   button.addEventListener("keydown", onButtonKeydown);
-  list.addEventListener("keydown", onListKeydown);
   list.addEventListener("click", onListClick);
   root.addEventListener("focusout", onRootFocusOut);
   document.addEventListener("click", onDocumentClick);
@@ -368,13 +408,15 @@ function initTextSizePicker(root, opts = {}) {
 
   if (initial) applySize(initial);
 
+  const tooltipDestroy = wireTooltip(root, button, ".text-size-picker-tooltip", list);
+
   return {
     setSize: applySize,
     destroy: () => {
-      clearTimeout(typeaheadTimer);
+      tooltipDestroy();
+      keyboard.destroy();
       button.removeEventListener("click", onButtonClick);
       button.removeEventListener("keydown", onButtonKeydown);
-      list.removeEventListener("keydown", onListKeydown);
       list.removeEventListener("click", onListClick);
       root.removeEventListener("focusout", onRootFocusOut);
       document.removeEventListener("click", onDocumentClick);

package/dist/index.js

@@ -1,5 +1,5 @@
 // lily-design-system-nunjucks-text-size-picker/text-size-picker.client.js
-var TYPEAHEAD_RESET_MS = 500;
+import { createListboxKeyboard } from "@lilydesignsystem/nunjucks-listbox-behavior";
 function sizeName(size) {
   return String(size || "").split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
 }
@@ -16,10 +16,105 @@ function safeStorageSet(key, value) {
   } catch (_e) {
   }
 }
-function scrollIntoViewIfPossible(el) {
-  if (el && typeof el.scrollIntoView === "function") {
-    el.scrollIntoView({ block: "nearest" });
+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: () => {
@@ -32,15 +127,11 @@ function initTextSizePicker(root, opts = {}) {
   if (!button || !list) return noop;
   const options = Array.from(list.querySelectorAll('[role="option"]'));
   const values = options.map((o) => o.getAttribute("data-value") || "");
-  const labels = options.map((o) => (o.textContent || "").trim());
   const storageKey = root.getAttribute("data-lily-text-size-picker-storage-key") || "";
   const defaultValue = root.getAttribute("data-lily-text-size-picker-default-value") || "";
   const valueAttr = root.getAttribute("data-lily-text-size-picker-value") || "";
   let current = "";
   let open = false;
-  let activeIndex = -1;
-  let typeahead = "";
-  let typeaheadTimer;
   let appliedValue = "";
   function applySize(slug) {
     if (!slug) return;
@@ -56,26 +147,13 @@ function initTextSizePicker(root, opts = {}) {
     });
     if (typeof opts.onChange === "function") opts.onChange(slug);
   }
-  function setActive(index) {
-    activeIndex = index;
-    options.forEach((o, i) => {
-      if (i === index) o.setAttribute("data-active", "");
-      else o.removeAttribute("data-active");
-    });
-    if (index >= 0 && options[index]) {
-      list.setAttribute("aria-activedescendant", options[index].id);
-      scrollIntoViewIfPossible(options[index]);
-    } else {
-      list.removeAttribute("aria-activedescendant");
-    }
-  }
   function openList(startIndex) {
     const selected = values.indexOf(current);
     const start = options.length === 0 ? -1 : typeof startIndex === "number" ? startIndex : selected >= 0 ? selected : 0;
     open = true;
     list.hidden = false;
     button.setAttribute("aria-expanded", "true");
-    setActive(start);
+    keyboard.setActive(start);
     list.focus({ preventScroll: true });
   }
   function closeList(refocus = true) {
@@ -83,7 +161,7 @@ function initTextSizePicker(root, opts = {}) {
     open = false;
     list.hidden = true;
     button.setAttribute("aria-expanded", "false");
-    setActive(-1);
+    keyboard.setActive(-1);
     if (refocus) button.focus({ preventScroll: true });
   }
   function choose(index) {
@@ -91,30 +169,18 @@ function initTextSizePicker(root, opts = {}) {
     if (slug) applySize(slug);
     closeList();
   }
-  function moveActive(delta) {
-    if (options.length === 0) return;
-    const next = Math.min(Math.max(activeIndex + delta, 0), options.length - 1);
-    setActive(next);
-  }
-  function runTypeahead(char) {
-    const lower = char.toLowerCase();
-    const sameCharRun = typeahead === "" || Array.from(typeahead).every((c) => c === lower);
-    typeahead += lower;
-    clearTimeout(typeaheadTimer);
-    typeaheadTimer = setTimeout(() => {
-      typeahead = "";
-    }, TYPEAHEAD_RESET_MS);
-    const query = sameCharRun ? lower : typeahead;
-    const anchor = activeIndex < 0 ? 0 : activeIndex;
-    const start = sameCharRun ? anchor + 1 : anchor;
-    for (let n = 0; n < options.length; n++) {
-      const i = (start + n) % options.length;
-      if (labels[i].toLowerCase().startsWith(query)) {
-        setActive(i);
-        return;
-      }
+  const keyboard = createListboxKeyboard(list, {
+    clamp: true,
+    typeahead: true,
+    pageSize: 10,
+    onActivate: choose,
+    onEscape: () => closeList(),
+    onTabOut: () => {
+      var _a;
+      (_a = button == null ? void 0 : button.focus) == null ? void 0 : _a.call(button, { preventScroll: true });
+      closeList(false);
     }
-  }
+  });
   function onButtonClick() {
     if (open) closeList();
     else openList();
@@ -135,52 +201,6 @@ function initTextSizePicker(root, opts = {}) {
         break;
     }
   }
-  function onListKeydown(event) {
-    var _a;
-    switch (event.key) {
-      case "ArrowDown":
-        event.preventDefault();
-        moveActive(1);
-        break;
-      case "ArrowUp":
-        event.preventDefault();
-        moveActive(-1);
-        break;
-      case "Home":
-        event.preventDefault();
-        setActive(0);
-        break;
-      case "End":
-        event.preventDefault();
-        setActive(options.length - 1);
-        break;
-      case "Enter":
-      case " ":
-        event.preventDefault();
-        if (activeIndex >= 0) choose(activeIndex);
-        break;
-      case "Escape":
-        event.preventDefault();
-        closeList();
-        break;
-      case "PageUp":
-        event.preventDefault();
-        moveActive(-10);
-        break;
-      case "PageDown":
-        event.preventDefault();
-        moveActive(10);
-        break;
-      case "Tab":
-        (_a = button == null ? void 0 : button.focus) == null ? void 0 : _a.call(button, { preventScroll: true });
-        closeList(false);
-        break;
-      default:
-        if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
-          runTypeahead(event.key);
-        }
-    }
-  }
   function onListClick(event) {
     const li = event.target && event.target.closest ? event.target.closest('[role="option"]') : null;
     if (!li) return;
@@ -199,7 +219,6 @@ function initTextSizePicker(root, opts = {}) {
   }
   button.addEventListener("click", onButtonClick);
   button.addEventListener("keydown", onButtonKeydown);
-  list.addEventListener("keydown", onListKeydown);
   list.addEventListener("click", onListClick);
   root.addEventListener("focusout", onRootFocusOut);
   document.addEventListener("click", onDocumentClick);
@@ -210,13 +229,14 @@ 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: () => {
-      clearTimeout(typeaheadTimer);
+      tooltipDestroy();
+      keyboard.destroy();
       button.removeEventListener("click", onButtonClick);
       button.removeEventListener("keydown", onButtonKeydown);
-      list.removeEventListener("keydown", onListKeydown);
       list.removeEventListener("click", onListClick);
       root.removeEventListener("focusout", onRootFocusOut);
       document.removeEventListener("click", onDocumentClick);

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.0",
+  "version": "0.2.0",
   "engines": {
     "node": "=26"
   },
@@ -24,6 +24,9 @@
   "scripts": {
     "prepublishOnly": "cd .. && npm run build"
   },
+  "dependencies": {
+    "@lilydesignsystem/nunjucks-listbox-behavior": "^0.1.0"
+  },
   "keywords": [
     "lily",
     "design",