@lilydesignsystem/nunjucks-text-size-picker 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,399 @@
+// TextSizePicker client-side runtime.
+//
+// Pairs with text-size-picker.njk. The macro renders the markup with
+// `data-lily-text-size-picker-*` hooks; this module picks them up in
+// 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.
+//
+// B. The text-size LIFECYCLE (unchanged):
+//   0. Read the consumer's `value` prop from
+//      `data-lily-text-size-picker-value`. This is the only channel by
+//      which `opts.value` reaches the client, and it is what keeps the
+//      pre-hydration paint honest.
+//   1. Set `data-text-size="{slug}"` on the resolved target
+//      (default <html>).
+//   2. Optionally persist to localStorage.
+//   3. Mirror the active slug into the hidden input (form
+//      participation) and onto the options' aria-selected state.
+//   4. Call opts.onChange(slug).
+//
+// The consumer owns the actual typography via CSS keyed on
+// `[data-text-size="{slug}"]`. This module makes no visual decisions.
+//
+// There is deliberately no system-preference detection: unlike
+// `prefers-color-scheme` (theme-picker) and `navigator.languages`
+// (locale-picker), the web platform exposes no OS "preferred text
+// size" signal.
+//
+// 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
+ * title-cased, so "x-large" renders as "X Large".
+ *
+ * Mirrors `themeName` in theme-picker and `localeName` in
+ * locale-picker. This is the JS statement of the rule the macro applies
+ * in template syntax with `| replace(r/-/g, " ") | title`; a Nunjucks
+ * macro cannot call into this module, and delegating would force every
+ * consumer to register a custom filter, so the two are kept in
+ * agreement by a test rather than by delegation.
+ */
+function sizeName(size) {
+  return String(size || "")
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+}
+
+function safeStorageGet(key) {
+  try {
+    return localStorage.getItem(key);
+  } catch (_e) {
+    return null;
+  }
+}
+
+function safeStorageSet(key, value) {
+  try {
+    localStorage.setItem(key, value);
+  } catch (_e) {
+    // ignore quota / privacy errors
+  }
+}
+
+/** jsdom and older browsers do not always implement scrollIntoView. */
+function scrollIntoViewIfPossible(el) {
+  if (el && typeof el.scrollIntoView === "function") {
+    el.scrollIntoView({ block: "nearest" });
+  }
+}
+
+/**
+ * Wire one rendered TextSizePicker root.
+ *
+ * @param {HTMLElement} root - The <div data-lily-text-size-picker-root>.
+ * @param {{onChange?: (size:string)=>void, target?: HTMLElement|null}=} opts
+ * @returns {{setSize: (size: string) => void, destroy: () => void}}
+ */
+function initTextSizePicker(root, opts = {}) {
+  const noop = { setSize: () => {}, destroy: () => {} };
+  if (typeof document === "undefined" || !root) return noop;
+
+  const button = root.querySelector("[data-lily-text-size-picker-button]");
+  const list = root.querySelector("[data-lily-text-size-picker-list]");
+  const input = root.querySelector("[data-lily-text-size-picker-input]");
+  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") || "";
+  // The consumer's `value` prop. The macro emits it as a data
+  // attribute rather than baking it into a control the browser would
+  // paint before hydration.
+  const valueAttr = root.getAttribute("data-lily-text-size-picker-value") || "";
+
+  let current = "";
+  let open = false;
+  let activeIndex = -1;
+  let typeahead = "";
+  let typeaheadTimer;
+
+  // -----------------------------------------------------------------
+  // Applying a size
+  // -----------------------------------------------------------------
+
+  // The size the DOM currently carries. Applying is idempotent: a
+  // size already applied is a no-op, so `onChange` fires once per
+  // changed value. `setSize` on the returned api is this same
+  // function, so without the guard a consumer that mirrors the value
+  // back from `onChange` re-enters it forever.
+  let appliedValue = "";
+
+  function applySize(slug) {
+    if (!slug) return;
+    if (slug === appliedValue) return;
+    appliedValue = slug;
+    current = slug;
+    const target = opts.target || document.documentElement;
+    target.setAttribute("data-text-size", slug);
+    if (storageKey) safeStorageSet(storageKey, slug);
+    // The hidden input carries the value into any enclosing form.
+    if (input) input.value = slug;
+    // Keep the listbox's selected state in sync with the applied size.
+    options.forEach((o, i) => {
+      o.setAttribute("aria-selected", values[i] === slug ? "true" : "false");
+    });
+    if (typeof opts.onChange === "function") opts.onChange(slug);
+  }
+
+  // -----------------------------------------------------------------
+  // Open / close / active-option movement
+  // -----------------------------------------------------------------
+
+  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
+    // aria-activedescendant off rather than pointing at an id that
+    // does not exist.
+    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);
+    // Focus moves to the listbox; the active option is conveyed via
+    // aria-activedescendant, per the APG listbox pattern.
+    list.focus({ preventScroll: true });
+  }
+
+  function closeList(refocus = true) {
+    if (!open) return;
+    open = false;
+    list.hidden = true;
+    button.setAttribute("aria-expanded", "false");
+    setActive(-1);
+    if (refocus) button.focus({ preventScroll: true });
+  }
+
+  function choose(index) {
+    const slug = values[index];
+    if (slug) applySize(slug);
+    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;
+      }
+    }
+  }
+
+  // -----------------------------------------------------------------
+  // Event handlers
+  // -----------------------------------------------------------------
+
+  function onButtonClick() {
+    if (open) closeList();
+    else openList();
+  }
+
+  function onButtonKeydown(event) {
+    switch (event.key) {
+      case "ArrowDown":
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        openList();
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        openList(options.length - 1);
+        break;
+    }
+  }
+
+  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
+        ? event.target.closest('[role="option"]')
+        : null;
+    if (!li) return;
+    const index = options.indexOf(li);
+    if (index >= 0) choose(index);
+  }
+
+  function onRootFocusOut(event) {
+    const next = event.relatedTarget;
+    if (next && root.contains(next)) return;
+    closeList(false);
+  }
+
+  function onDocumentClick(event) {
+    if (!open) return;
+    const t = event.target;
+    if (t && !root.contains(t)) closeList(false);
+  }
+
+  button.addEventListener("click", onButtonClick);
+  button.addEventListener("keydown", onButtonKeydown);
+  list.addEventListener("keydown", onListKeydown);
+  list.addEventListener("click", onListClick);
+  root.addEventListener("focusout", onRootFocusOut);
+  document.addEventListener("click", onDocumentClick);
+
+  // -----------------------------------------------------------------
+  // §5.1 initial value resolution
+  // value attribute > storage > default > "medium" > first
+  //
+  // Unchanged by the icon-button release: `value` already beat
+  // storage here, so unlike theme-picker there is no precedence
+  // reversal to warn about.
+  // -----------------------------------------------------------------
+
+  let initial = "";
+
+  // 1. value prop — read from `data-lily-text-size-picker-value`.
+  initial = valueAttr;
+
+  // 2. storage
+  if (!initial && storageKey) initial = safeStorageGet(storageKey) || "";
+
+  // 3. default-value
+  if (!initial && defaultValue) initial = defaultValue;
+
+  // 4. "medium" if present
+  if (!initial && values.includes("medium")) initial = "medium";
+
+  // 5. first option
+  if (!initial && values.length > 0) initial = values[0];
+
+  if (initial) applySize(initial);
+
+  return {
+    setSize: applySize,
+    destroy: () => {
+      clearTimeout(typeaheadTimer);
+      button.removeEventListener("click", onButtonClick);
+      button.removeEventListener("keydown", onButtonKeydown);
+      list.removeEventListener("keydown", onListKeydown);
+      list.removeEventListener("click", onListClick);
+      root.removeEventListener("focusout", onRootFocusOut);
+      document.removeEventListener("click", onDocumentClick);
+    },
+  };
+}
+
+/**
+ * Find every [data-lily-text-size-picker-root] and wire it.
+ *
+ * @param {{onChange?: (size:string)=>void, target?: HTMLElement|null}=} opts
+ * @returns {Array<{setSize: (size:string)=>void, destroy: ()=>void}>}
+ */
+function autoInit(opts = {}) {
+  if (typeof document === "undefined") return [];
+  const roots = Array.from(
+    document.querySelectorAll("[data-lily-text-size-picker-root]"),
+  );
+  return roots.map((root) => initTextSizePicker(root, opts));
+}
+
+export { autoInit, initTextSizePicker, sizeName };

package/dist/index.js

@@ -0,0 +1,237 @@
+// lily-design-system-nunjucks-text-size-picker/text-size-picker.client.js
+var TYPEAHEAD_RESET_MS = 500;
+function sizeName(size) {
+  return String(size || "").split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+function safeStorageGet(key) {
+  try {
+    return localStorage.getItem(key);
+  } catch (_e) {
+    return null;
+  }
+}
+function safeStorageSet(key, value) {
+  try {
+    localStorage.setItem(key, value);
+  } catch (_e) {
+  }
+}
+function scrollIntoViewIfPossible(el) {
+  if (el && typeof el.scrollIntoView === "function") {
+    el.scrollIntoView({ block: "nearest" });
+  }
+}
+function initTextSizePicker(root, opts = {}) {
+  const noop = { setSize: () => {
+  }, destroy: () => {
+  } };
+  if (typeof document === "undefined" || !root) return noop;
+  const button = root.querySelector("[data-lily-text-size-picker-button]");
+  const list = root.querySelector("[data-lily-text-size-picker-list]");
+  const input = root.querySelector("[data-lily-text-size-picker-input]");
+  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;
+    if (slug === appliedValue) return;
+    appliedValue = slug;
+    current = slug;
+    const target = opts.target || document.documentElement;
+    target.setAttribute("data-text-size", slug);
+    if (storageKey) safeStorageSet(storageKey, slug);
+    if (input) input.value = slug;
+    options.forEach((o, i) => {
+      o.setAttribute("aria-selected", values[i] === slug ? "true" : "false");
+    });
+    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);
+    list.focus({ preventScroll: true });
+  }
+  function closeList(refocus = true) {
+    if (!open) return;
+    open = false;
+    list.hidden = true;
+    button.setAttribute("aria-expanded", "false");
+    setActive(-1);
+    if (refocus) button.focus({ preventScroll: true });
+  }
+  function choose(index) {
+    const slug = values[index];
+    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;
+      }
+    }
+  }
+  function onButtonClick() {
+    if (open) closeList();
+    else openList();
+  }
+  function onButtonKeydown(event) {
+    switch (event.key) {
+      case "ArrowDown":
+      case "Enter":
+      case " ":
+        event.preventDefault();
+        openList();
+        break;
+      case "ArrowUp":
+        event.preventDefault();
+        openList(options.length - 1);
+        break;
+      default:
+        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;
+    const index = options.indexOf(li);
+    if (index >= 0) choose(index);
+  }
+  function onRootFocusOut(event) {
+    const next = event.relatedTarget;
+    if (next && root.contains(next)) return;
+    closeList(false);
+  }
+  function onDocumentClick(event) {
+    if (!open) return;
+    const t = event.target;
+    if (t && !root.contains(t)) closeList(false);
+  }
+  button.addEventListener("click", onButtonClick);
+  button.addEventListener("keydown", onButtonKeydown);
+  list.addEventListener("keydown", onListKeydown);
+  list.addEventListener("click", onListClick);
+  root.addEventListener("focusout", onRootFocusOut);
+  document.addEventListener("click", onDocumentClick);
+  let initial = "";
+  initial = valueAttr;
+  if (!initial && storageKey) initial = safeStorageGet(storageKey) || "";
+  if (!initial && defaultValue) initial = defaultValue;
+  if (!initial && values.includes("medium")) initial = "medium";
+  if (!initial && values.length > 0) initial = values[0];
+  if (initial) applySize(initial);
+  return {
+    setSize: applySize,
+    destroy: () => {
+      clearTimeout(typeaheadTimer);
+      button.removeEventListener("click", onButtonClick);
+      button.removeEventListener("keydown", onButtonKeydown);
+      list.removeEventListener("keydown", onListKeydown);
+      list.removeEventListener("click", onListClick);
+      root.removeEventListener("focusout", onRootFocusOut);
+      document.removeEventListener("click", onDocumentClick);
+    }
+  };
+}
+function autoInit(opts = {}) {
+  if (typeof document === "undefined") return [];
+  const roots = Array.from(
+    document.querySelectorAll("[data-lily-text-size-picker-root]")
+  );
+  return roots.map((root) => initTextSizePicker(root, opts));
+}
+export {
+  autoInit,
+  initTextSizePicker,
+  sizeName
+};

package/dist/text-size-picker.njk

@@ -0,0 +1,101 @@
+{#
+  TextSizePicker macro — icon button that opens a listbox of text sizes.
+
+  HTML tag: <div> (root), <button> + <ul role="listbox">
+  CSS class: text-size-picker
+  Companion runtime: text-size-picker.client.js
+
+  BREAKING (Unreleased): this macro no longer renders a native
+  <select>. It renders an icon button (a bundled stroke-drawn "A" SVG,
+  viewBox 0 0 16 16 — reversed 2026-09-16 from the Unicode glyph
+  U+0041 LATIN CAPITAL LETTER A) that opens a listbox, matching
+  theme-picker and locale-picker. All three helpers are now the same
+  shape.
+
+  Params (single `opts` object):
+    label         — string, required. aria-label for the button AND the
+                    listbox. The button is icon-only, so this is the
+                    ONLY accessible name it has.
+    sizes         — array<string>, required. Available size slugs.
+    value         — string. Initial slug, emitted as
+                    data-lily-text-size-picker-value for the client to
+                    read.
+    defaultValue  — string. Initial slug when nothing else is supplied.
+    storageKey    — string. If non-empty, client.js persists to localStorage.
+    name          — string. Hidden-input `name` (default "text-size").
+    sizeLabels    — object<string,string>. Pretty label per slug.
+    id            — string. Id prefix for the listbox and its options.
+                    Defaults to "text-size-picker-{name}". Supply an
+                    explicit id when rendering two instances that share
+                    a `name`.
+    classes       — string. Extra CSS classes on the root <div>.
+    attributes    — object. Extra HTML attributes spread onto the root.
+
+  There is deliberately NO detection prop. Unlike theme-picker's
+  `prefers-color-scheme` and locale-picker's `navigator.languages`,
+  the web platform exposes no OS "preferred text size" signal, so
+  there is nothing to detect.
+
+  Custom icon: call the macro with a `{% call %}` block and the block
+  body replaces the default icon inside the button:
+
+    {% call textSizePicker({label: "Text size", sizes: [...]}) %}
+      <svg aria-hidden="true">…</svg>
+    {% endcall %}
+
+  Usage:
+    {% from "./text-size-picker.njk" import textSizePicker %}
+    {{ textSizePicker({
+      label: "Text size",
+      sizes: ["small", "medium", "large", "x-large"],
+      storageKey: "lily-text-size"
+    }) }}
+
+  Then load text-size-picker.client.js once and call autoInit().
+
+  NOTE: the button does nothing until text-size-picker.client.js runs.
+  See docs/ssr.md — this is a real no-JS regression from the old
+  <select>.
+
+  Spec: spec/index.md §4.1 (macro parameters), §4.2 (DOM contract).
+#}
+{%- macro textSizePicker(opts) -%}
+{%- set name = opts.name | default("text-size") -%}
+{%- set value = opts.value | default("") -%}
+{%- set storageKey = opts.storageKey | default("") -%}
+{%- set defaultValue = opts.defaultValue | default("") -%}
+{%- set sizeLabels = opts.sizeLabels | default({}) -%}
+{%- set id = opts.id | default("text-size-picker-" + name) -%}
+{%- set listId = id + "-list" -%}
+{#- Server-side selected resolution. localStorage is client-only —
+    there is no storage at render time — so the client may correct this
+    after hydration; the point is that the server markup always marks
+    exactly one option aria-selected. -#}
+{%- set fallback = "medium" if "medium" in opts.sizes else opts.sizes[0] -%}
+{%- set selected = value or defaultValue or fallback -%}
+<div
+  class="text-size-picker{% if opts.classes %} {{ opts.classes }}{% endif %}"
+  data-lily-text-size-picker-root
+  data-lily-text-size-picker-name="{{ name }}"
+  data-lily-text-size-picker-storage-key="{{ storageKey }}"
+  data-lily-text-size-picker-default-value="{{ defaultValue }}"
+  {%- if value %} data-lily-text-size-picker-value="{{ value }}"{% endif %}
+  {%- if opts.attributes %}{% for k, v in opts.attributes %} {{ k }}="{{ v }}"{% endfor %}{% endif %}
+>
+<input type="hidden" name="{{ name }}" value="{{ selected }}" data-lily-text-size-picker-input>
+<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>
+<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 }}">
+    {%- if sizeLabels[slug] -%}
+      {{ sizeLabels[slug] }}
+    {%- else -%}
+      {{ slug | replace(r/-/g, " ") | title }}
+    {%- endif -%}
+  </li>
+{%- endfor -%}
+</ul>
+</div>
+{%- endmacro -%}

package/index.md

@@ -0,0 +1,300 @@
+# TextSizePicker (Nunjucks helper)
+
+A reusable, headless Nunjucks 3 + vanilla-JS text-size control that
+applies the chosen size to the document root via `data-text-size`,
+with optional `localStorage` persistence.
+
+The single source of truth is [spec/index.md](./spec/index.md). This file is the
+user guide.
+
+> **BREAKING (Unreleased).** This helper no longer renders a native
+> `<select>`. It renders an icon button that opens a listbox, matching
+> `theme-picker` and `locale-picker`. Consumers must now load
+> `text-size-picker.client.js` — without it the button is inert. See
+> [CHANGELOG.md](./CHANGELOG.md) for the migration, and
+> [docs/ssr.md](./docs/ssr.md) for the no-JS consequences.
+
+## Why this exists
+
+Most text-size controls couple selection, persistence, and the actual
+typographic scale into one opinionated widget. This one splits the
+contract cleanly:
+
+- **This helper** owns the `data-text-size` lifecycle, accessibility,
+  and persistence — via a Nunjucks macro for the markup and a small
+  ES module for the runtime.
+- **Your CSS** owns the actual typography, keyed on
+  `[data-text-size="{slug}"]`.
+- **Consumers** own the visual style of the control via the
+  `text-size-picker` class hooks.
+
+The helper is a direct port of the Svelte canonical
+`@lilydesignsystem/svelte-text-size-picker`. The DOM contract and
+behaviour match clause-for-clause; only the framework idioms differ.
+
+## How the pieces fit
+
+The helper is a **macro + client.js** pair:
+
+- The macro (`text-size-picker.njk`) renders the markup server-side or
+  at static-site build time.
+- The client (`text-size-picker.client.js`) is an ES module the
+  consumer loads once per page. It picks up the markup via
+  `data-lily-text-size-picker-*` hooks and owns **both** the
+  browser-side lifecycle (storage, `data-text-size` apply, change
+  events) **and** the whole listbox interaction (open/close, focus,
+  keyboard, typeahead).
+
+```
+Nunjucks render time                 │  Browser runtime
+                                      │
+{{ textSizePicker({…}) }}            │  import { autoInit } from
+   │                                  │    "./text-size-picker.client.js";
+   ▼                                  │  autoInit();
+<div class="text-size-picker"         │     │
+  data-lily-text-size-picker-root     │     ▼
+  data-lily-text-size-picker-*>       │  finds [data-lily-text-size-picker-root]
+  <input type="hidden">               │     │
+  <button aria-haspopup="listbox">    │     ▼
+    <span aria-hidden="true">A</span> │  resolves initial slug
+  </button>                           │     │
+  <ul role="listbox" hidden>          │     ▼
+    <li role="option">Medium</li>     │  applySize(slug):
+    …                                 │    - target.dataset.textSize = slug
+  </ul>                               │    - localStorage.setItem(...)
+</div>                                │    - hidden input + aria-selected
+                                      │    - opts.onChange(slug)
+                                      │  …and wires the listbox keyboard
+```
+
+## Install
+
+Copy the core files into your project or wire as a workspace
+dependency:
+
+| File                          | Purpose                |
+| ----------------------------- | ---------------------- |
+| `text-size-picker.njk`       | The Nunjucks macro.    |
+| `text-size-picker.client.js` | The ES-module runtime. |
+
+Runtime dependencies: `nunjucks` ≥ 3 server-side and standard DOM
+APIs client-side.
+
+## Quick start
+
+1. Render the macro in your Nunjucks template:
+
+```njk
+{% from "./lily-design-system-nunjucks-text-size-picker/text-size-picker.njk" import textSizePicker %}
+
+{{ textSizePicker({
+    label: "Text size",
+    sizes: ["small", "medium", "large", "x-large"],
+    storageKey: "lily-text-size"
+}) }}
+
+{# The control is icon-only, so it never shows the active size.
+   Pair it with a status region — see docs/accessibility.md. #}
+<p class="text-size-picker-status" aria-live="polite"></p>
+```
+
+2. Load the client.js once per page. **This is not optional** — the
+   button does not open without it:
+
+```html
+<script type="module">
+  import { autoInit } from "/path/to/text-size-picker.client.js";
+  const status = document.querySelector(".text-size-picker-status");
+  autoInit({
+    onChange(slug) {
+      status.textContent = `Text size: ${slug}`;
+    },
+  });
+</script>
+```
+
+3. Style each size in your CSS. **This is the half that actually
+   satisfies WCAG 1.4.4** — the helper only signals the choice:
+
+```css
+[data-text-size="small"] {
+  font-size: 0.875rem;
+}
+[data-text-size="medium"] {
+  font-size: 1rem;
+}
+[data-text-size="large"] {
+  font-size: 1.25rem;
+}
+[data-text-size="x-large"] {
+  font-size: 1.5rem;
+}
+```
+
+Use relative units throughout. Absolute `px` defeats both this control
+and the user's own browser settings.
+
+When the user picks `large`, the client:
+
+- sets `data-text-size="large"` on `<html>`,
+- writes `"large"` to `localStorage["lily-text-size"]`,
+- mirrors `"large"` into the hidden input and the options'
+  `aria-selected`,
+- fires `onChange("large")` if provided.
+
+A worked end-to-end example, including the type scale, is in
+[`examples/01-basic.njk`](./examples/01-basic.njk).
+
+## Markup
+
+```html
+<div class="text-size-picker" data-lily-text-size-picker-root …>
+  <input type="hidden" name="text-size" value="medium" />
+  <button
+    type="button"
+    class="text-size-picker-button"
+    aria-label="Text size"
+    aria-haspopup="listbox"
+    aria-expanded="false"
+    aria-controls="text-size-picker-text-size-list"
+  >
+    <svg class="text-size-picker-icon" viewBox="0 0 16 16" aria-hidden="true" width="1.05rem" height="1.05rem">…</svg>
+  </button>
+  <ul
+    class="text-size-picker-list"
+    id="text-size-picker-text-size-list"
+    role="listbox"
+    aria-label="Text size"
+    tabindex="-1"
+    hidden
+  >
+    <li
+      class="text-size-picker-option"
+      role="option"
+      aria-selected="true"
+      data-value="medium"
+    >
+      Medium
+    </li>
+    …
+  </ul>
+</div>
+```
+
+The package ships **no CSS at all**, including none for positioning the
+open listbox. Style it with `.text-size-picker-list:not([hidden])` —
+never `display: block`, which would override the `hidden` attribute
+that is the open-state contract.
+
+### Why the icon is a stroke-drawn "A"
+
+A bundled outline SVG (`viewBox="0 0 16 16"`), not a Unicode character
+(reversed 2026-09-16). It renders identically everywhere, unlike a
+font-dependent glyph, and reads as the conventional text-size
+affordance.
+
+Override it with a `{% call %}` block:
+
+```njk
+{% call textSizePicker({label: "Text size", sizes: ["small", "large"]}) %}
+    <span aria-hidden="true">Aa</span>
+{% endcall %}
+```
+
+The block replaces the **icon**, not the label, and does not render
+options. Keep whatever you put there `aria-hidden="true"` — the
+accessible name must stay on `aria-label`.
+
+## Initial size
+
+The initial slug on `initTextSizePicker(root)` resolves to the first
+non-empty value of:
+
+1. `data-lily-text-size-picker-value` (i.e. `opts.value`).
+2. `localStorage.getItem(storageKey)` (when set and readable).
+3. `data-lily-text-size-picker-default-value` (i.e. `opts.defaultValue`).
+4. `"medium"` if present among the option values.
+5. The first option value, or `""` if none.
+
+## Macro parameters
+
+Full table in [spec/index.md §4.1](./spec/index.md#41-macro-parameters).
+Required: `label`, `sizes`. Optional: `value`, `defaultValue`,
+`storageKey`, `name` (default `"text-size"`), `sizeLabels`, `id`
+(default `"text-size-picker-{name}"`), `classes`, `attributes`.
+
+`label` is the accessible name for **both** the button and the
+listbox. The button is icon-only, so this is the only accessible name
+it has — it is load-bearing.
+
+Default option labels title-case the slug per hyphen-word
+(`x-large` → `X Large`). Pass `sizeLabels` to override any label;
+typeahead matches the rendered label, so overrides participate.
+
+There is deliberately **no** detection prop: unlike
+`prefers-color-scheme` and `navigator.languages`, the web platform
+exposes no OS "preferred text size" signal.
+
+## Client.js API
+
+```js
+import {
+  initTextSizePicker,
+  autoInit,
+  sizeName,
+} from "./text-size-picker.client.js";
+```
+
+- `autoInit(opts?)` — find every
+  `[data-lily-text-size-picker-root]` and wire it.
+- `initTextSizePicker(root, opts?)` — wire a single root; returns
+  `{setSize, destroy}`.
+- `sizeName(slug)` — `"x-large"` → `"X Large"`. The JS statement of
+  the label rule the macro applies in template syntax.
+
+Optional `opts`:
+
+- `onChange(size)` — fired once per applied change; receives the slug.
+- `target` — element receiving `data-text-size` (defaults to
+  `<html>`).
+
+## Keyboard
+
+Owned entirely by the client.js; none of it works before that module
+runs. On the button: `ArrowDown` / `Enter` / `Space` open (`ArrowUp`
+opens on the last option). On the list: arrows move and clamp,
+`Home` / `End` jump, `PageUp` / `PageDown` move by ten (clamped),
+`Enter` / `Space` select, `Escape` closes unchanged, `Tab` closes and
+moves on — focus goes to the button first, so the default Tab proceeds
+from the picker's position — and printable characters run APG
+typeahead (a repeated character cycles through its matches). Full
+table in [docs/accessibility.md](./docs/accessibility.md).
+
+## Accessibility
+
+- WCAG 2.2 AAA target; WAI-ARIA APG listbox pattern.
+- Directly supports WCAG 1.4.4 (Resize Text) — provided your CSS
+  actually delivers the resize.
+- `aria-label` is the only accessible name the button has.
+- **Without JavaScript the button cannot be operated at all**, which
+  the old native `<select>` could. This matters more for a text-size
+  control than for its siblings; browser zoom remains the backstop.
+
+The honest tradeoffs — the `aria-label` dependency and weaker AT
+support than a native `<select>` — are documented in
+[docs/accessibility.md](./docs/accessibility.md), and the SSR and
+no-JS consequences in [docs/ssr.md](./docs/ssr.md).
+
+## Testing
+
+`pnpm test` under a vitest + jsdom setup exercises every numbered
+acceptance criterion in [spec/index.md §7](./spec/index.md#7-testing-acceptance-criteria).
+
+## License
+
+MIT or Apache-2.0 or GPL-2.0 or GPL-3.0 or BSD-3-Clause. Contact
+joel@joelparkerhenderson.com for other terms.
+
+---
+
+Lily™ and Lily Design System™ are trademarks.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@lilydesignsystem/nunjucks-text-size-picker",
+  "version": "0.1.0",
+  "engines": {
+    "node": "=26"
+  },
+  "description": "Lily Design System - Nunjucks 3 text size picker",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./template": "./dist/text-size-picker.njk"
+  },
+  "files": [
+    "dist",
+    "index.md",
+    "README.md"
+  ],
+  "scripts": {
+    "prepublishOnly": "cd .. && npm run build"
+  },
+  "keywords": [
+    "lily",
+    "design",
+    "system",
+    "nunjucks",
+    "text-size",
+    "picker"
+  ],
+  "author": "Joel Parker Henderson <joel@joelparkerhenderson.com>",
+  "license": "MIT OR Apache-2.0 OR GPL-2.0-only OR GPL-3.0-only OR BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LilyDesignSystem/lily-design-system-nunjucks-helpers.git",
+    "directory": "lily-design-system-nunjucks-text-size-picker"
+  },
+  "homepage": "https://lilydesignsystem.com/",
+  "bugs": {
+    "url": "https://github.com/LilyDesignSystem/lily-design-system/issues"
+  }
+}