@occluze/tether 0.6.6 → 0.6.8

package/src/mounting.js

@@ -1,87 +1,144 @@
-/** Product scopes and lists that are mounted, shared by index.js and the optional markets part. */
+/**
+ * The product scopes and lists on the page: mounting a product root, the live roots a country switch re-renders, and
+ * the products the server rendered into the page. Shared by `index.js` and the optional markets part.
+ */
 import { cfg, log, warn, reportError } from './config.js';
 import { ProductScope, scopes, rememberOptionNames } from './product.js';
 import { listSelector } from './collection.js';
 import { getProduct, takeStale, refreshProducts, hydrateProducts } from './loader.js';
 import { resolveProductKey, setScopeStatus, isNotFound } from './status.js';
 import { attr, get, qsa, emit } from './dom.js';
+/** @import { Product } from './fragments.js' */
+
+/** @typedef {{ root: Element, load: (more?: boolean) => Promise<unknown> }} MountedList A mounted `ListScope`. */
+
+/**
+ * The marker on the `<script type="application/json">` tags `tether/server`'s `hydrate()` writes. It is fixed, not
+ * `<prefix>-hydrate`, because the server writes it without knowing the browser's prefix.
+ */
+const HYDRATE_SELECTOR = 'script[type="application/json"][data-tether-hydrate]';
 
+/** @type {WeakSet<Element>} */
 export const mountedProducts = new WeakSet();
+/** @type {WeakSet<Element>} */
 export const mountedLists = new WeakSet();
-// Live roots, for re-rendering after a country switch (pruned when disconnected).
+/** @type {Set<HTMLElement>} Product roots to re-render after a country switch; pruned once disconnected. */
 export const liveProducts = new Set();
+/** @type {Set<MountedList>} Lists to reload after a country switch; pruned once disconnected. */
 export const liveLists = new Set();
-const requestToken = new WeakMap(); // product root -> latest request, so a slow old response can't win
+/** @type {WeakMap<Element, object>} Each product root's latest request, so a slow older response can't win. */
+const latestRequest = new WeakMap();
 
+/** Forgets roots a page transition removed, so they aren't kept alive. */
 export function pruneLive() {
-  liveProducts.forEach((el) => { if (!el.isConnected) liveProducts.delete(el); });
-  liveLists.forEach((l) => { if (!l.root.isConnected) liveLists.delete(l); });
+  liveProducts.forEach((el) => {
+    if (!el.isConnected) liveProducts.delete(el);
+  });
+  liveLists.forEach((list) => {
+    if (!list.root.isConnected) liveLists.delete(list);
+  });
 }
+
+/**
+ * @param {ParentNode & Partial<Pick<Element, 'matches'>>} root
+ * @param {string} selector
+ * @returns {HTMLElement[]} `root` itself when it matches, then the matches inside it.
+ */
 export function within(root, selector) {
-  return [...(root.matches?.(selector) ? [root] : []), ...qsa(root, selector)];
+  const self = root.matches?.(selector) ? [/** @type {HTMLElement} */ (root)] : [];
+  return [...self, ...qsa(root, selector)];
+}
+
+/**
+ * `tether-page-title="{title} | My shop"` on a product root sets `document.title`, for dynamic product pages.
+ *
+ * @param {Element} el
+ * @param {Product} product
+ */
+function applyPageTitle(el, product) {
+  const template = get(el, 'page-title');
+  if (!template || typeof document === 'undefined') return;
+  document.title = template
+    .replace(/\{title\}/g, product.title)
+    .replace(/\{vendor\}/g, product.vendor || '')
+    .replace(/\{type\}/g, product.productType || '');
 }
 
-export /** Mounts one product root. Returns true when a product request was started. */
-function mountProduct(el) {
+/**
+ * A product root without a key: on a dynamic page opened without `?handle=` (or with an empty path) it is a product
+ * that isn't there; inside a list it gets its handle when the list renders.
+ *
+ * @param {HTMLElement} el
+ * @param {{ fromUrl: boolean, raw: string }} source
+ */
+function mountWithoutKey(el, { fromUrl, raw }) {
+  if (fromUrl) {
+    mountedProducts.add(el);
+    setScopeStatus(el, 'not-found');
+    emit('product-not-found', { key: null, source: raw }, el);
+  } else if (!el.closest(listSelector())) {
+    warn(`[${attr('product')}] without a value. Bind it to the Shopify handle field, or use "url:handle".`, el);
+  }
+}
+
+/**
+ * @param {HTMLElement} el
+ * @param {string} key
+ * @param {{ fromUrl: boolean, raw: string }} source
+ * @param {unknown} error
+ */
+function showLoadFailure(el, key, { fromUrl, raw }, error) {
+  const notFound = isNotFound(error);
+  setScopeStatus(el, notFound ? 'not-found' : 'error', error);
+  if (!notFound) {
+    reportError(error, `product ${key}`);
+    emit('error', { error, context: 'product', key }, el);
+    return;
+  }
+  emit('product-not-found', { key, source: raw }, el);
+  // A typo in a URL isn't worth an alert; a CMS item pointing at a deleted product is.
+  if (fromUrl) log(`product not found: ${key}`);
+  else reportError(error, `product ${key}`);
+}
+
+/**
+ * Mounts one product root.
+ *
+ * @param {HTMLElement} el
+ * @returns {boolean} True when a product request was started.
+ */
+export function mountProduct(el) {
   if (mountedProducts.has(el)) return false;
-  const { key, fromUrl, raw } = resolveProductKey(el);
+  const { key, ...source } = resolveProductKey(el);
   if (!key) {
-    if (fromUrl) {
-      // Dynamic product page opened without ?handle= (or an empty path).
-      mountedProducts.add(el);
-      setScopeStatus(el, 'not-found');
-      emit('product-not-found', { key: null, source: raw }, el);
-    } else if (!el.closest(listSelector())) {
-      // List cards get their handle when the list renders.
-      warn(`[${attr('product')}] without a value. Bind it to the Shopify handle field, or use "url:handle".`, el);
-    }
+    mountWithoutKey(el, source);
     return false;
   }
   mountedProducts.add(el);
   liveProducts.add(el);
-  const token = {};
-  requestToken.set(el, token);
-  const current = () => requestToken.get(el) === token;
-  // A rendered scope keeps showing its content while it refreshes (e.g. country switch).
-  if (!scopes.get(el)) setScopeStatus(el, 'loading');
-  else el.setAttribute(attr('state'), 'updating');
-  const loading = getProduct(key);
-  marketPending?.add(loading);
+  const request = {};
+  latestRequest.set(el, request);
+  const isLatest = () => latestRequest.get(el) === request;
+  // A rendered scope keeps showing its content while it refreshes (a country switch).
+  if (scopes.get(el)) el.setAttribute(attr('state'), 'updating');
+  else setScopeStatus(el, 'loading');
+  const loading = trackMarket(getProduct(key));
   loading
-    .then((p) => {
-      if (!current()) return;
+    .then((product) => {
+      if (!isLatest()) return;
       const existing = scopes.get(el);
-      if (existing) existing.update(p);
-      // eslint-disable-next-line no-new
-      else new ProductScope(el, p);
-      applyPageTitle(el, p);
-      if (cfg.revalidate !== false && takeStale(key)) queueRefresh(key);
+      if (existing) existing.update(product);
+      else new ProductScope(el, product);
+      applyPageTitle(el, product);
+      if (cfg.revalidate && takeStale(key)) queueRefresh(key);
     })
-    .catch((err) => {
-      if (!current()) return;
-      const notFound = isNotFound(err);
-      setScopeStatus(el, notFound ? 'not-found' : 'error', err);
-      if (notFound) {
-        emit('product-not-found', { key, source: raw }, el);
-        // A typo in a URL isn't worth an alert; a CMS item pointing at a deleted product is.
-        if (fromUrl) log(`product not found: ${key}`); else reportError(err, `product ${key}`);
-      } else {
-        reportError(err, `product ${key}`);
-        emit('error', { error: err, context: 'product', key }, el);
-      }
+    .catch((/** @type {unknown} */ error) => {
+      if (isLatest()) showLoadFailure(el, key, source, error);
     });
   return true;
 }
 
-/** tether-page-title="{title} | My shop" on a product root sets document.title (dynamic product pages). */
-function applyPageTitle(el, p) {
-  const tpl = get(el, 'page-title');
-  if (!tpl || typeof document === 'undefined') return;
-  document.title = tpl.replace(/\{title\}/g, p.title).replace(/\{vendor\}/g, p.vendor || '').replace(/\{type\}/g, p.productType || '');
-}
-
-
-/** Product scopes that failed on a network/API error: loaded again when the browser is back online. */
+/** Loads again the product scopes that failed on a network or API error, for when the browser is back online. */
 export function retryFailed() {
   pruneLive();
   liveProducts.forEach((el) => {
@@ -91,64 +148,130 @@ export function retryFailed() {
   });
 }
 
-// Server-rendered products: one batched background request refreshes them all.
+/** @type {Set<string>} Server-rendered products to refresh in the next batch. */
 let refreshQueue = new Set();
+
+/** @param {string} key */
 function queueRefresh(key) {
   if (!refreshQueue.size) setTimeout(flushRefresh, 0);
   refreshQueue.add(key);
 }
+
+/**
+ * @param {string} key The key the refresh was asked for.
+ * @param {Product} fresh
+ */
+function applyRefresh(key, fresh) {
+  liveProducts.forEach((el) => {
+    const scope = scopes.get(el);
+    if (!scope || !el.isConnected) return;
+    const rootKey = resolveProductKey(el).key;
+    if (rootKey !== key && rootKey !== fresh.handle && rootKey !== fresh.id) return;
+    if (JSON.stringify(scope.product) !== JSON.stringify(fresh)) scope.update(fresh);
+  });
+}
+
+/** One batched background request refreshes every server-rendered product queued. */
 function flushRefresh() {
   const keys = [...refreshQueue];
   refreshQueue = new Set();
-  refreshProducts(keys).forEach((promise, i) => promise.then((fresh) => {
-    liveProducts.forEach((el) => {
-      const scope = scopes.get(el);
-      if (!scope || !el.isConnected) return;
-      const k = resolveProductKey(el).key;
-      if (k !== keys[i] && k !== fresh.handle && k !== fresh.id) return;
-      if (JSON.stringify(scope.product) !== JSON.stringify(fresh)) scope.update(fresh);
-    });
-  }).catch((err) => reportError(err, `refresh ${keys[i]}`)));
+  refreshProducts(keys).forEach((promise, index) => {
+    const key = /** @type {string} */ (keys[index]);
+    promise
+      .then((fresh) => {
+        applyRefresh(key, fresh);
+      })
+      .catch((/** @type {unknown} */ error) => {
+        reportError(error, `refresh ${key}`);
+      });
+  });
 }
 
 /**
- * <script type="application/json" data-tether-hydrate> tags written by tether/server's hydrate():
- * their products are used without a request. Ignored when they were made for another market.
+ * @type {Set<Promise<unknown>> | null} While the page's server-rendered prices are another market's: the loads to
+ *   wait for before `html.tether-market-pending` goes. `null` when no market is pending.
  */
-const readScripts = new WeakSet();
-let marketPending = null; // product loads to wait for before html.tether-market-pending goes
+let marketPending = null;
 
-/** Lists (and anything else that loads prices) wait too. */
-export const trackMarket = (p) => { marketPending?.add(p); return p; };
+/**
+ * Lists, and anything else that loads prices, hold `html.tether-market-pending` until they are in.
+ *
+ * @template T
+ * @param {Promise<T>} loading
+ * @returns {Promise<T>} `loading` itself.
+ */
+export const trackMarket = (loading) => {
+  marketPending?.add(loading);
+  return loading;
+};
 
-/** After a mount: drop html.tether-market-pending once this page's products are live. */
+/** After a mount: drops `html.tether-market-pending` once this page's products are live. */
 export function settleMarket() {
   if (!marketPending) return;
   const waits = [...marketPending];
-  Promise.allSettled(waits).then(() => {
-    if (!marketPending || waits.some((w) => !marketPending.has(w))) return;
-    if (waits.length === marketPending.size) {
-      marketPending = null;
-      document.documentElement.classList.remove(`${cfg.prefix}-market-pending`);
-    } else settleMarket(); // more products came in meanwhile
+  void Promise.allSettled(waits).then(() => {
+    if (!marketPending || waits.some((wait) => !marketPending?.has(wait))) return;
+    if (waits.length !== marketPending.size) {
+      settleMarket(); // more loads came in meanwhile
+      return;
+    }
+    marketPending = null;
+    document.documentElement.classList.remove(`${cfg.prefix}-market-pending`);
   });
 }
 
+/**
+ * What `tether/server`'s `hydrate()` writes. The tag is the site's own markup, so its shape is trusted; a product
+ * without an id or a handle is skipped.
+ *
+ * @typedef {{ country?: string | null, language?: string | null, products?: (Product | null)[] }} HydratePayload
+ */
+
+/**
+ * @param {Product | null} product
+ * @returns {product is Product}
+ */
+const isUsable = (product) => Boolean(product?.id && product.handle);
+
+/**
+ * @param {string | null | undefined} a
+ * @param {string | null | undefined} b
+ */
+const sameCode = (a, b) => (a ?? '').toUpperCase() === (b ?? '').toUpperCase();
+
+/** @type {WeakSet<Element>} Hydrate tags already read. */
+const readScripts = new WeakSet();
+
+/**
+ * Uses the products in the page's hydrate tags (`tether/server` `hydrate()`) without a request. A tag made for another
+ * market is skipped, and marks the page (`html.tether-market-pending`) until the live prices are in, so CSS can hide
+ * prices meanwhile.
+ *
+ * @param {Document | Element} [root]
+ */
 export function hydrateFromPage(root = document) {
-  qsa(root.ownerDocument || root, 'script[type="application/json"][data-tether-hydrate]').forEach((s) => {
-    if (readScripts.has(s)) return;
-    readScripts.add(s);
+  qsa(root.ownerDocument ?? root, HYDRATE_SELECTOR).forEach((script) => {
+    if (readScripts.has(script)) return;
+    readScripts.add(script);
+    /** @type {unknown} */
+    let json;
     try {
-      const data = JSON.parse(s.textContent);
-      rememberOptionNames(data.products); // the build's option names, also for other languages
-      const same = (a, b) => String(a || '').toUpperCase() === String(b || '').toUpperCase();
-      if (same(data.country, cfg.country) && same(data.language, cfg.language)) hydrateProducts(data.products);
-      else {
-        // The page was built for another market: its prices aren't this visitor's. Mark the page
-        // (html.tether-market-pending) until the live ones are in, so CSS can hide prices meanwhile.
-        log('hydration skipped: other market');
-        if (!marketPending) { marketPending = new Set(); document.documentElement.classList.add(`${cfg.prefix}-market-pending`); }
-      }
-    } catch (err) { warn('bad data-tether-hydrate', err); }
+      json = JSON.parse(script.textContent);
+    } catch (error) {
+      warn('bad data-tether-hydrate', error);
+      return;
+    }
+    const { country, language, products } = /** @type {HydratePayload | null} */ (json) ?? {};
+    const usable = Array.isArray(products) ? products.filter(isUsable) : [];
+    rememberOptionNames(usable); // the build's option names, also for other languages
+    if (sameCode(country, cfg.country) && sameCode(language, cfg.language)) {
+      hydrateProducts(usable);
+      return;
+    }
+    log('hydration skipped: other market');
+    if (!marketPending) {
+      marketPending = new Set();
+      document.documentElement.classList.add(`${cfg.prefix}-market-pending`);
+    }
   });
 }

package/src/page-market.js

@@ -0,0 +1,116 @@
+/**
+ * The market the page uses: a page built for one market (`<meta name="tether-page-country">`) wins, then the visitor's
+ * saved or detected market, then the configured one. Init applies it to `cfg` once. Astro's ClientRouter keeps the
+ * script running across pages, so each arrival asks again: the next page may be built for another market, or for none.
+ */
+import { cfg, log, reportError } from './config.js';
+import { loadPart } from './lazy.js';
+import { toCountry, toLanguage } from './market-codes.js';
+import { readSavedMarket } from './markets.js';
+/** @import { TetherOptions } from './config.js' */
+/** @import { Market, DetectedMarket } from './markets.js' */
+/** @import { SetCountryOptions } from './markets-ui.js' */
+/** @import { ShopifyCart } from './cart/store.js' */
+
+/**
+ * @typedef {object} ConfiguredMarket The market of the config, before a page's or visitor's market applied.
+ * @property {string | undefined} country
+ * @property {string | undefined} language
+ * @property {string | undefined} locale
+ */
+
+/** @type {ConfiguredMarket} */
+let configuredMarket = { country: undefined, language: undefined, locale: undefined };
+
+/** Whether the page arrived at last was built for its own market, which the next page without one switches back from. */
+let lastPageHadOwnMarket = false;
+
+/**
+ * `<meta name="tether-page-country" content="DE">`, with `tether-page-language` and `tether-page-locale`. Never
+ * remembered: it belongs to the page, not to the visitor.
+ *
+ * @returns {Market | null} `null` when the page has no valid country of its own.
+ */
+function pageMarket() {
+  /** @param {string} name */
+  const meta = (name) =>
+    document.querySelector(`meta[name="${cfg.prefix}-page-${name}"]`)?.getAttribute('content') || undefined;
+  const country = toCountry(meta('country'));
+  if (!country) return null;
+  return { country, language: toLanguage(meta('language')) ?? undefined, locale: meta('locale') };
+}
+
+/**
+ * Without `markets.detect` only the visitor's saved choice applies, read without loading the markets part.
+ *
+ * @returns {Promise<Market | DetectedMarket | null>}
+ */
+async function visitorMarket() {
+  const markets = cfg.markets ?? {};
+  if (markets.detect === false) return null;
+  if (!markets.detect) return markets.remember === false ? null : readSavedMarket();
+  try {
+    return (await loadPart('markets')).detectMarket(markets);
+  } catch (error) {
+    reportError(error, 'markets');
+    return null;
+  }
+}
+
+/**
+ * Sets `cfg`'s market for the first page, over the configured one.
+ *
+ * @param {TetherOptions} overrides What `init()` was called with: a `locale` there wins over the visitor's.
+ * @returns {Promise<void>}
+ */
+export async function applyStartMarket(overrides) {
+  configuredMarket = { country: cfg.country, language: cfg.language, locale: cfg.locale };
+  const page = pageMarket();
+  lastPageHadOwnMarket = page !== null;
+  if (page) {
+    cfg.country = page.country;
+    cfg.language = page.language;
+    if (page.locale) cfg.locale = page.locale;
+    return;
+  }
+  const market = await visitorMarket();
+  if (!market) return;
+  if (market.country) cfg.country = market.country;
+  if (market.language) cfg.language = market.language;
+  if (market.locale && !overrides.locale) cfg.locale = market.locale;
+  log('market', market);
+}
+
+/**
+ * @param {string | undefined} a
+ * @param {string | undefined} b
+ */
+const sameCode = (a, b) => (a ?? '').toUpperCase() === (b ?? '').toUpperCase();
+
+/**
+ * The market to switch to on arriving at the current page. A page built for a market switches to it; the first page
+ * without one after such a page switches back to the visitor's own choice, else to the configured market.
+ *
+ * @returns {{ country: string, language: string | undefined, locale: string | undefined } | null} `null` when the page
+ *   stays in the market in use.
+ */
+export function marketForArrival() {
+  const page = pageMarket();
+  const leftOwnMarket = page === null && lastPageHadOwnMarket;
+  lastPageHadOwnMarket = page !== null;
+  const target = page ?? (leftOwnMarket ? (readSavedMarket() ?? configuredMarket) : null);
+  if (!target?.country) return null;
+  if (sameCode(target.country, cfg.country) && sameCode(target.language, cfg.language)) return null;
+  return { country: target.country, language: target.language, locale: target.locale };
+}
+
+/**
+ * `Tether.setCountry('DE')`: loads the markets part on first use.
+ *
+ * @param {string} code
+ * @param {SetCountryOptions} [options]
+ * @returns {Promise<ShopifyCart | null>} The cart once everything is in the new market.
+ */
+export function setCountry(code, options) {
+  return loadPart('markets').then((part) => part.setCountry(code, options));
+}

package/src/parts/account-pages.js

@@ -1,3 +1,6 @@
+// The <script> build's tether.account-pages.js: registers the part where the core script's loader (lazy-iife.js) finds it.
 import * as part from '../account-pages.js';
 
-window.Tether.__parts['account-pages'] = part;
+const { Tether } = /** @type {Window & { Tether?: { __parts: Record<string, unknown> } }} */ (window);
+if (!Tether) throw new Error('tether.account-pages.js runs after the Tether script, which loads it');
+Tether.__parts['account-pages'] = part;

package/src/parts/account.js

@@ -1,3 +1,6 @@
+// The <script> build's tether.account.js: registers the part where the core script's loader (lazy-iife.js) finds it.
 import * as part from '../account.js';
 
-window.Tether.__parts.account = part;
+const { Tether } = /** @type {Window & { Tether?: { __parts: Record<string, unknown> } }} */ (window);
+if (!Tether) throw new Error('tether.account.js runs after the Tether script, which loads it');
+Tether.__parts['account'] = part;

package/src/parts/analytics.js

@@ -1,3 +1,6 @@
+// The <script> build's tether.analytics.js: registers the part where the core script's loader (lazy-iife.js) finds it.
 import * as part from '../analytics.js';
 
-window.Tether.__parts.analytics = part;
+const { Tether } = /** @type {Window & { Tether?: { __parts: Record<string, unknown> } }} */ (window);
+if (!Tether) throw new Error('tether.analytics.js runs after the Tether script, which loads it');
+Tether.__parts['analytics'] = part;

package/src/parts/diagnose.js

@@ -1,3 +1,6 @@
+// The <script> build's tether.diagnose.js: registers the part where the core script's loader (lazy-iife.js) finds it.
 import * as part from '../diagnose.js';
 
-window.Tether.__parts.diagnose = part;
+const { Tether } = /** @type {Window & { Tether?: { __parts: Record<string, unknown> } }} */ (window);
+if (!Tether) throw new Error('tether.diagnose.js runs after the Tether script, which loads it');
+Tether.__parts['diagnose'] = part;

package/src/parts/extras.js

@@ -1,3 +1,6 @@
+// The <script> build's tether.extras.js: registers the part where the core script's loader (lazy-iife.js) finds it.
 import * as part from '../extras.js';
 
-window.Tether.__parts.extras = part;
+const { Tether } = /** @type {Window & { Tether?: { __parts: Record<string, unknown> } }} */ (window);
+if (!Tether) throw new Error('tether.extras.js runs after the Tether script, which loads it');
+Tether.__parts['extras'] = part;

package/src/parts/markets.js

@@ -1,3 +1,6 @@
+// The <script> build's tether.markets.js: registers the part where the core script's loader (lazy-iife.js) finds it.
 import * as part from '../markets-ui.js';
 
-window.Tether.__parts.markets = part;
+const { Tether } = /** @type {Window & { Tether?: { __parts: Record<string, unknown> } }} */ (window);
+if (!Tether) throw new Error('tether.markets.js runs after the Tether script, which loads it');
+Tether.__parts['markets'] = part;

package/src/parts/search.js

@@ -1,3 +1,6 @@
+// The <script> build's tether.search.js: registers the part where the core script's loader (lazy-iife.js) finds it.
 import * as part from '../search.js';
 
-window.Tether.__parts.search = part;
+const { Tether } = /** @type {Window & { Tether?: { __parts: Record<string, unknown> } }} */ (window);
+if (!Tether) throw new Error('tether.search.js runs after the Tether script, which loads it');
+Tether.__parts['search'] = part;