@occluze/tether 0.6.6 → 0.6.8

package/src/repeaters.js

@@ -0,0 +1,173 @@
+/**
+ * Lists rendered from a template: a repeater's first child in the designer is the template, and every item gets a
+ * copy of it. The other children are placeholder content and are removed.
+ */
+import { cfg, reportError, warn } from './config.js';
+
+/** @type {WeakMap<Element, HTMLElement | null>} Each repeater's template, captured on first render. */
+const templates = new WeakMap();
+
+/**
+ * @param {Element} container
+ * @returns {boolean} True once the repeater's template has been captured (it may be empty after that).
+ */
+export const hasTemplate = (container) => Boolean(templates.get(container));
+
+/**
+ * A deep copy of a template. `cloneNode` is typed as returning a `Node`; a copy of an element is an element of the
+ * same kind.
+ *
+ * @param {HTMLElement} template
+ */
+const copyOf = (template) => /** @type {HTMLElement} */ (template.cloneNode(true));
+
+/** @param {Element} container */
+function templateOf(container) {
+  const known = templates.get(container);
+  if (known !== undefined) return known;
+  const first = container.firstElementChild;
+  // Repeaters are HTML lists in the designer; their first child is an HTML element.
+  const template = first ? copyOf(/** @type {HTMLElement} */ (first)) : null;
+  templates.set(container, template);
+  container.replaceChildren();
+  return template;
+}
+
+/**
+ * Rebuilds the list on every render. Fine for images, tags, options.
+ *
+ * @template Item
+ * @param {Element} container
+ * @param {readonly Item[]} items
+ * @param {(node: HTMLElement, item: Item, index: number) => void} render
+ */
+export function repeat(container, items, render) {
+  const template = templateOf(container);
+  if (!template) {
+    if (items.length) warn('repeater without a template child', container);
+    return;
+  }
+  container.replaceChildren();
+  items.forEach((item, index) => {
+    const node = copyOf(template);
+    render(node, item, index);
+    container.appendChild(node);
+  });
+}
+
+/**
+ * @typedef {object} KeyedHooks
+ * @property {((node: HTMLElement) => void) | null} [onEnter] Runs on a node inserted for a new item.
+ * @property {((node: HTMLElement, done: () => void) => void) | null} [onLeave] Runs on a node whose item is gone;
+ *   `done()` removes it.
+ */
+
+/**
+ * @param {HTMLElement} node
+ * @param {KeyedHooks['onLeave']} onLeave
+ */
+function leave(node, onLeave) {
+  const done = () => {
+    node.remove();
+  };
+  if (!onLeave) {
+    done();
+    return;
+  }
+  try {
+    onLeave(node, done);
+  } catch (error) {
+    reportError(error, 'repeater onLeave');
+    done();
+  }
+}
+
+/**
+ * Inserts the nodes of new items next to the item before them, leaving the existing nodes where they are.
+ *
+ * @param {Element} container
+ * @param {HTMLElement[]} wanted Every item's node, in order.
+ * @param {Set<HTMLElement>} fresh The nodes not yet in the container.
+ * @param {KeyedHooks['onEnter']} onEnter
+ */
+function insertFresh(container, wanted, fresh, onEnter) {
+  wanted.forEach((node, index) => {
+    if (!fresh.has(node)) return;
+    const previous = wanted[index - 1];
+    if (previous?.parentNode === container) previous.after(node);
+    else container.prepend(node);
+    if (!onEnter) return;
+    try {
+      onEnter(node);
+    } catch (error) {
+      reportError(error, 'repeater onEnter');
+    }
+  });
+}
+
+/**
+ * Keyed repeater: keeps existing nodes, inserts new ones, removes old ones. Used for cart lines, so values can
+ * animate and lines can slide in and out.
+ *
+ * @template Item
+ * @param {Element} container
+ * @param {readonly Item[]} items
+ * @param {(item: Item, index: number) => string | number} keyOf
+ * @param {(node: HTMLElement, item: Item, index: number, isNew: boolean) => void} render
+ * @param {KeyedHooks} [hooks]
+ */
+export function repeatKeyed(container, items, keyOf, render, { onEnter, onLeave } = {}) {
+  const template = templateOf(container);
+  if (!template) {
+    warn('repeater without a template child', container);
+    return;
+  }
+
+  const keyAttribute = `data-${cfg.prefix}-key`;
+  const leavingAttribute = `data-${cfg.prefix}-leaving`;
+  const live = () =>
+    [.../** @type {HTMLCollectionOf<HTMLElement>} */ (container.children)].filter(
+      (node) => node.hasAttribute(keyAttribute) && !node.hasAttribute(leavingAttribute),
+    );
+
+  const existing = new Map(live().map((node) => [node.getAttribute(keyAttribute), node]));
+  /** @type {HTMLElement[]} */
+  const wanted = [];
+  /** @type {Set<HTMLElement>} */
+  const fresh = new Set();
+
+  items.forEach((item, index) => {
+    const key = String(keyOf(item, index));
+    let node = existing.get(key);
+    if (node) existing.delete(key);
+    else {
+      node = copyOf(template);
+      node.setAttribute(keyAttribute, key);
+      fresh.add(node);
+    }
+    render(node, item, index, fresh.has(node));
+    wanted.push(node);
+  });
+
+  const staying = wanted.filter((node) => !fresh.has(node));
+  const current = live().filter((node) => staying.includes(node));
+  const inOrder = current.length === staying.length && current.every((node, index) => node === staying[index]);
+
+  if (!inOrder) {
+    existing.forEach((node) => {
+      node.remove();
+    });
+    wanted.forEach((node) => container.appendChild(node));
+    return;
+  }
+
+  insertFresh(container, wanted, fresh, onEnter);
+
+  existing.forEach((node) => {
+    node.setAttribute(leavingAttribute, '');
+    node.removeAttribute(keyAttribute);
+    node.style.pointerEvents = 'none';
+    node.inert = true;
+    leave(node, onLeave);
+  });
+}

package/src/search.js

@@ -1,6 +1,5 @@
 /**
- * Search as you type (Shopify predictive search). Optional part: loaded only on pages with
- * [tether-search].
+ * Search as you type (Shopify predictive search). Optional part: loaded only on pages with [tether-search].
  *
  *   <form tether-search action="/search">            <!-- Enter: your full results page -->
  *     <input tether-search-input name="q" type="search" placeholder="Search">
@@ -12,13 +11,31 @@
  *     </div>
  *   </form>
  *
- * Each list's first child is the template. The root gets is-open while there are results (or none)
- * to show, and tether-search-state="loading|ready|empty|error". Arrow keys move through the results,
- * Escape closes. tether-search-limit (default 6), tether-search-min (characters, default 2).
+ * Each list's first child is the template. The root gets is-open while there are results (or none) to show, and
+ * tether-search-state="idle|loading|ready|empty|error". Arrow keys move through the results, Escape closes.
+ * tether-search-limit (default 6), tether-search-min (characters, default 2).
  */
-import { cfg, reportError } from './config.js';
+import { cfg, log, reportError } from './config.js';
 import { gql } from './client.js';
 import { attr, sel, get, qsa, setText, setImage, repeat, show, formatMoney, productUrl, emit } from './dom.js';
+import { within } from './mounting.js';
+/** @import { Money } from './shopify-values.js' */
+
+/** @typedef {{ url: string, altText: string | null }} SearchImage */
+/**
+ * @typedef {object} SearchProduct
+ * @property {string} id
+ * @property {string} handle
+ * @property {string} title
+ * @property {boolean} availableForSale
+ * @property {SearchImage | null} featuredImage
+ * @property {{ minVariantPrice: Money }} priceRange
+ */
+/** @typedef {{ handle: string, title: string, image: SearchImage | null }} SearchCollection */
+/** @typedef {{ text: string }} SearchQuery */
+/** @typedef {{ products: SearchProduct[], collections: SearchCollection[], queries: SearchQuery[] }} SearchResults */
+/** @typedef {'idle' | 'loading' | 'ready' | 'empty' | 'error'} SearchState */
+/** @typedef {{ title?: string, price?: string, text?: string, image?: SearchImage | null }} BindValues */
 
 const QUERY = `query TetherPredictive($q: String!, $limit: Int!) {
   predictiveSearch(query: $q, limit: $limit, limitScope: EACH, types: [PRODUCT, COLLECTION, QUERY]) {
@@ -28,126 +45,279 @@ const QUERY = `query TetherPredictive($q: String!, $limit: Int!) {
   }
 }`;
 
+const DEFAULT_LIMIT = 6;
+const DEFAULT_MIN_CHARACTERS = 2;
+const DEFAULT_ACTION = '/search';
+
+/** @type {WeakSet<Element>} */
 const mounted = new WeakSet();
-let uid = 0;
+let searchBoxCount = 0;
 
-export function mountSearch(root = document) {
-  const roots = [...(root.matches?.(sel('search')) ? [root] : []), ...qsa(root, sel('search'))];
-  roots.forEach((el) => { if (!mounted.has(el)) { mounted.add(el); setup(el); } });
+/**
+ * @param {Element} el
+ * @param {string} name
+ * @param {number} fallback
+ * @returns {number} The attribute as an integer; `fallback` when it is missing, zero or not a number.
+ */
+function integerAttribute(el, name, fallback) {
+  return parseInt(get(el, name) || '', 10) || fallback;
+}
+
+/**
+ * @param {Element} node
+ * @returns {Element | null} `node` when it is a link, else its first link.
+ */
+const linkIn = (node) => (node.tagName === 'A' ? node : node.querySelector('a'));
+
+/**
+ * @param {HTMLElement} node
+ * @param {BindValues} values
+ */
+function bindValues(node, values) {
+  qsa(node, sel('search-bind')).forEach((el) => {
+    const field = get(el, 'search-bind');
+    if (field === 'image') setImage(el, values.image?.url, values.image?.altText || values.title);
+    else if (field === 'title' || field === 'price' || field === 'text') {
+      if (values[field] != null) setText(el, values[field]);
+    }
+  });
 }
 
-function setup(rootEl) {
-  const input = rootEl.querySelector(sel('search-input')) || rootEl.querySelector('input');
-  const results = rootEl.querySelector(sel('search-results'));
-  if (!input || !results) return;
-  const limit = parseInt(get(rootEl, 'search-limit') || '6', 10) || 6;
-  const min = parseInt(get(rootEl, 'search-min') || '2', 10) || 2;
-  const id = results.id || (results.id = `${cfg.prefix}-search-${++uid}`);
-  input.setAttribute('role', 'combobox');
-  input.setAttribute('aria-autocomplete', 'list');
-  input.setAttribute('aria-controls', id);
-  input.setAttribute('aria-expanded', 'false');
-  input.setAttribute('autocomplete', 'off');
-  if (!results.hasAttribute('role')) results.setAttribute('role', 'listbox');
-  results.hidden = true;
-
-  let token = 0;
-  let timer = null;
-  let last = '';
-  const cache = new Map(); // term -> results, for typing back and forth
-
-  const setState = (state) => rootEl.setAttribute(attr('search-state'), state);
-  const open = (yes) => {
-    rootEl.classList.toggle('is-open', yes);
-    results.hidden = !yes;
-    input.setAttribute('aria-expanded', String(yes));
-    if (!yes) input.removeAttribute('aria-activedescendant');
-  };
-  const items = () => qsa(results, '[role="option"]');
-
-  async function run(term) {
-    const t = ++token;
-    if (term.length < min) { open(false); setState('idle'); return; }
-    setState('loading');
+/**
+ * @param {Element} node
+ * @param {string} href
+ */
+function linkOption(node, href) {
+  const link = linkIn(node);
+  if (!link) return;
+  link.setAttribute('href', href);
+  link.setAttribute('role', 'option');
+}
+
+/** One `[tether-search]` root: its input, its results and the search in flight. */
+class SearchBox {
+  /**
+   * @param {HTMLElement} root
+   * @param {HTMLInputElement} input
+   * @param {HTMLElement} results
+   */
+  constructor(root, input, results) {
+    this.root = root;
+    this.input = input;
+    this.results = results;
+    this.limit = integerAttribute(root, 'search-limit', DEFAULT_LIMIT);
+    this.minCharacters = integerAttribute(root, 'search-min', DEFAULT_MIN_CHARACTERS);
+    if (!results.id) {
+      searchBoxCount += 1;
+      results.id = `${cfg.prefix}-search-${searchBoxCount}`;
+    }
+    this.resultsId = results.id;
+    /** Counts searches, so only the latest one renders. */
+    this.searchNumber = 0;
+    /** @type {ReturnType<typeof setTimeout> | undefined} */
+    this.timer = undefined;
+    this.lastTerm = '';
+    /** @type {Map<string, SearchResults | null>} Results per term, for typing back and forth. */
+    this.cache = new Map();
+    this.setUpAria();
+    this.listen();
+  }
+
+  setUpAria() {
+    this.input.setAttribute('role', 'combobox');
+    this.input.setAttribute('aria-autocomplete', 'list');
+    this.input.setAttribute('aria-controls', this.resultsId);
+    this.input.setAttribute('aria-expanded', 'false');
+    this.input.setAttribute('autocomplete', 'off');
+    if (!this.results.hasAttribute('role')) this.results.setAttribute('role', 'listbox');
+    this.results.hidden = true;
+  }
+
+  listen() {
+    this.input.addEventListener('input', () => {
+      const term = this.input.value.trim();
+      if (term === this.lastTerm) return;
+      this.lastTerm = term;
+      clearTimeout(this.timer);
+      this.timer = setTimeout(() => void this.search(term), cfg.searchDelay);
+    });
+    this.input.addEventListener('focus', () => {
+      if (this.input.value.trim().length >= this.minCharacters && this.options().length) this.open(true);
+    });
+    this.input.addEventListener('keydown', (event) => {
+      this.onKeydown(event);
+    });
+    document.addEventListener('click', (event) => {
+      // A click event's target is always a node.
+      if (!this.root.contains(/** @type {Node | null} */ (event.target))) this.open(false);
+    });
+  }
+
+  /** @param {SearchState} state */
+  setState(state) {
+    this.root.setAttribute(attr('search-state'), state);
+  }
+
+  /** @param {boolean} open */
+  open(open) {
+    this.root.classList.toggle('is-open', open);
+    this.results.hidden = !open;
+    this.input.setAttribute('aria-expanded', String(open));
+    if (!open) this.input.removeAttribute('aria-activedescendant');
+  }
+
+  options() {
+    return qsa(this.results, '[role="option"]');
+  }
+
+  /**
+   * @param {string} term
+   * @returns {Promise<SearchResults | null>}
+   */
+  async fetchResults(term) {
+    const cached = this.cache.get(term);
+    if (cached) return cached;
+    /** @type {{ predictiveSearch: SearchResults | null }} */
+    const data = await gql(QUERY, { q: term, limit: this.limit });
+    this.cache.set(term, data.predictiveSearch);
+    return data.predictiveSearch;
+  }
+
+  /** @param {string} term */
+  async search(term) {
+    this.searchNumber += 1;
+    const searchNumber = this.searchNumber;
+    if (term.length < this.minCharacters) {
+      this.open(false);
+      this.setState('idle');
+      return;
+    }
+    this.setState('loading');
     try {
-      const data = cache.get(term) || (await gql(QUERY, { q: term, limit })).predictiveSearch;
-      cache.set(term, data);
-      if (t !== token) return; // a newer search is on its way
-      render(data, term);
-    } catch (err) {
-      if (t !== token) return;
-      setState('error');
-      reportError(err, 'search');
+      const results = await this.fetchResults(term);
+      if (searchNumber === this.searchNumber) this.render(results, term);
+    } catch (error) {
+      // A newer search owns the state and reports its own failure.
+      if (searchNumber !== this.searchNumber) {
+        log('a superseded search failed', error);
+        return;
+      }
+      this.setState('error');
+      reportError(error, 'search');
     }
   }
 
-  function render(data, term) {
-    const products = data?.products || [];
-    const collections = data?.collections || [];
-    const queries = (data?.queries || []).filter((q) => q.text.toLowerCase() !== term.toLowerCase());
-    const fill = (name, list, each) => qsa(results, sel(name)).forEach((c) => {
-      repeat(c, list, each);
-      show(c, list.length > 0);
+  /**
+   * @template Item
+   * @param {string} name The list attribute, e.g. `search-products`.
+   * @param {readonly Item[]} items
+   * @param {(node: HTMLElement, item: Item) => void} render
+   */
+  fillList(name, items, render) {
+    qsa(this.results, sel(name)).forEach((list) => {
+      repeat(list, items, render);
+      show(list, items.length > 0);
     });
-    fill('search-products', products, (node, p) => {
-      binds(node, { title: p.title, price: formatMoney(p.priceRange?.minVariantPrice), image: p.featuredImage });
-      link(node, productUrl(p.handle, p.id));
-      node.classList.toggle('is-sold-out', !p.availableForSale);
+  }
+
+  /** @param {string} text */
+  queryUrl(text) {
+    const action = this.root.getAttribute('action') || DEFAULT_ACTION;
+    const separator = action.includes('?') ? '&' : '?';
+    return `${action}${separator}${this.input.name || 'q'}=${encodeURIComponent(text)}`;
+  }
+
+  /**
+   * @param {SearchResults | null} results
+   * @param {string} term
+   */
+  render(results, term) {
+    const products = results?.products ?? [];
+    const collections = results?.collections ?? [];
+    const queries = (results?.queries ?? []).filter((query) => query.text.toLowerCase() !== term.toLowerCase());
+    this.fillList('search-products', products, (node, product) => {
+      const price = formatMoney(product.priceRange.minVariantPrice);
+      bindValues(node, { title: product.title, price, image: product.featuredImage });
+      linkOption(node, productUrl(product.handle, product.id));
+      node.classList.toggle('is-sold-out', !product.availableForSale);
     });
-    fill('search-collections', collections, (node, c) => {
-      binds(node, { title: c.title, image: c.image });
-      link(node, `${(cfg.collectionPath || '/collection').replace(/\/$/, '')}/${c.handle}`);
+    this.fillList('search-collections', collections, (node, collection) => {
+      bindValues(node, { title: collection.title, image: collection.image });
+      linkOption(node, `${(cfg.collectionPath || '/collection').replace(/\/$/, '')}/${collection.handle}`);
     });
-    fill('search-queries', queries, (node, q) => {
-      binds(node, { text: q.text });
-      const a = node.tagName === 'A' ? node : node.querySelector('a');
-      const action = rootEl.getAttribute('action') || '/search';
-      if (a) a.setAttribute('href', `${action}${action.includes('?') ? '&' : '?'}${input.name || 'q'}=${encodeURIComponent(q.text)}`);
+    this.fillList('search-queries', queries, (node, query) => {
+      bindValues(node, { text: query.text });
+      linkIn(node)?.setAttribute('href', this.queryUrl(query.text));
     });
     const count = products.length + collections.length + queries.length;
-    qsa(rootEl, sel('show')).forEach((el) => {
-      const k = get(el, 'show');
-      if (k === 'search-empty') show(el, count === 0);
-      if (k === 'search-results') show(el, count > 0);
+    this.showCount(count);
+    this.setState(count ? 'ready' : 'empty');
+    this.open(true);
+    emit('search', { term, products, collections, queries }, this.root);
+  }
+
+  /** @param {number} count */
+  showCount(count) {
+    qsa(this.root, sel('show')).forEach((el) => {
+      const condition = get(el, 'show');
+      if (condition === 'search-empty') show(el, count === 0);
+      if (condition === 'search-results') show(el, count > 0);
+    });
+    this.options().forEach((option, index) => {
+      option.id ||= `${this.resultsId}-${index}`;
+      option.setAttribute('aria-selected', 'false');
     });
-    items().forEach((el, i) => { el.id ||= `${id}-${i}`; el.setAttribute('aria-selected', 'false'); });
-    setState(count ? 'ready' : 'empty');
-    open(true);
-    emit('search', { term, products, collections, queries }, rootEl);
   }
 
-  function binds(node, values) {
-    qsa(node, sel('search-bind')).forEach((el) => {
-      const k = get(el, 'search-bind');
-      if (k === 'image') setImage(el, values.image?.url, values.image?.altText || values.title);
-      else if (values[k] != null) setText(el, values[k]);
+  /**
+   * @param {HTMLElement[]} options
+   * @param {number} index
+   */
+  highlight(options, index) {
+    options.forEach((option, optionIndex) => {
+      option.setAttribute('aria-selected', String(optionIndex === index));
     });
+    const option = options[index];
+    if (!option) return;
+    this.input.setAttribute('aria-activedescendant', option.id);
+    // jsdom has no scrollIntoView.
+    /** @type {Partial<Pick<HTMLElement, 'scrollIntoView'>>} */ (option).scrollIntoView?.({ block: 'nearest' });
   }
 
-  function link(node, href) {
-    const a = node.tagName === 'A' ? node : node.querySelector('a');
-    if (a) { a.setAttribute('href', href); a.setAttribute('role', 'option'); }
+  /** @param {KeyboardEvent} event */
+  onKeydown(event) {
+    const options = this.options();
+    const current = options.findIndex((option) => option.getAttribute('aria-selected') === 'true');
+    if (event.key === 'ArrowDown' && options.length) {
+      event.preventDefault();
+      this.open(true);
+      this.highlight(options, (current + 1) % options.length);
+    } else if (event.key === 'ArrowUp' && options.length) {
+      event.preventDefault();
+      this.highlight(options, current <= 0 ? options.length - 1 : current - 1);
+    } else if (event.key === 'Enter' && current >= 0) {
+      event.preventDefault();
+      options[current]?.click();
+    } else if (event.key === 'Escape') {
+      this.open(false);
+    }
   }
+}
 
-  input.addEventListener('input', () => {
-    const term = input.value.trim();
-    if (term === last) return;
-    last = term;
-    clearTimeout(timer);
-    timer = setTimeout(() => run(term), cfg.searchDelay ?? 150);
-  });
-  input.addEventListener('focus', () => { if (input.value.trim().length >= min && items().length) open(true); });
-  input.addEventListener('keydown', (e) => {
-    const list = items();
-    const cur = list.findIndex((el) => el.getAttribute('aria-selected') === 'true');
-    const move = (i) => {
-      list.forEach((el, j) => el.setAttribute('aria-selected', String(j === i)));
-      if (list[i]) { input.setAttribute('aria-activedescendant', list[i].id); list[i].scrollIntoView?.({ block: 'nearest' }); }
-    };
-    if (e.key === 'ArrowDown' && list.length) { e.preventDefault(); open(true); move((cur + 1) % list.length); }
-    else if (e.key === 'ArrowUp' && list.length) { e.preventDefault(); move(cur <= 0 ? list.length - 1 : cur - 1); }
-    else if (e.key === 'Enter' && cur >= 0) { e.preventDefault(); list[cur].click(); }
-    else if (e.key === 'Escape') { open(false); }
-  });
-  document.addEventListener('click', (e) => { if (!rootEl.contains(e.target)) open(false); });
+/**
+ * Sets up every `[tether-search]` in `root` (and `root` itself) once.
+ *
+ * @param {ParentNode & Partial<Pick<Element, 'matches'>>} [root]
+ */
+export function mountSearch(root = document) {
+  for (const el of within(root, sel('search'))) {
+    if (mounted.has(el)) continue;
+    mounted.add(el);
+    // The markup names an input element; a site without one gets the first input.
+    const input = /** @type {HTMLInputElement | null} */ (
+      el.querySelector(sel('search-input')) ?? el.querySelector('input')
+    );
+    const results = /** @type {HTMLElement | null} */ (el.querySelector(sel('search-results')));
+    if (input && results) new SearchBox(el, input, results);
+  }
 }