@occluze/tether 0.3.6 → 0.5.0

package/src/index.js

@@ -9,43 +9,29 @@
  */
 import { cfg, configure, isConfigured, log, warn, reportError } from './config.js';
 import { gql, TetherError, withContext } from './client.js';
-import { Cart } from './cart.js';
-import { ProductScope, scopes } from './product.js';
+import { Cart, focusables } from './cart.js';
+import { scopes } from './product.js';
 import { ListScope, listSelector } from './collection.js';
 import {
   getProduct, getProducts, getRecommendations, clearProductCache, primeProduct, normalizeProductKey,
 } from './loader.js';
 import * as plans from './selling-plans.js';
-import { resolveProductKey, setScopeStatus, isNotFound } from './status.js';
-import { diagnose } from './diagnose.js';
-import { detectMarket, rememberMarket, getLocalization, clearLocalization, toCountry, toLanguage } from './markets.js';
-import { attr, sel, get, qsa, emit, formatMoney, busy, parseJSONAttr, toAttributes } from './dom.js';
-
-export const VERSION = '0.3.6';
-
-const mountedProducts = new WeakSet();
-const mountedLists = new WeakSet();
-// Live roots, for re-rendering after a country switch (pruned when disconnected).
-const liveProducts = new Set();
-const liveLists = new Set();
-const requestToken = new WeakMap(); // product root -> latest request, so a slow old response can't win
-
-function pruneLive() {
-  liveProducts.forEach((el) => { if (!el.isConnected) liveProducts.delete(el); });
-  liveLists.forEach((l) => { if (!l.root.isConnected) liveLists.delete(l); });
-}
+import { resolveProductKey } from './status.js';
+import { attr, sel, get, qsa, emit, formatMoney, busy, parseJSONAttr, toAttributes, imageUrl } from './dom.js';
+import { loadPart, coreModules } from './lazy.js';
+import { mountedLists, liveLists, pruneLive, within, mountProduct, retryFailed, hydrateFromPage } from './mounting.js';
+
+export const VERSION = '0.5.0';
+
 let initPromise = null;
 let observer = null;
 
-function within(root, selector) {
-  return [...(root.matches?.(selector) ? [root] : []), ...qsa(root, selector)];
-}
-
 /** Mount every product scope and product list inside `root`. Safe to call repeatedly. */
 export function mount(root = document) {
   if (!isConfigured()) return 0;
   let count = 0;
   pruneLive(); // page transitions detach old roots: don't keep them alive
+  hydrateFromPage(root); // products the server already rendered: no request needed
 
   within(root, listSelector()).forEach((el) => {
     if (mountedLists.has(el)) return;
@@ -59,7 +45,10 @@ export function mount(root = document) {
 
   within(root, sel('product')).forEach((el) => { if (mountProduct(el)) count++; });
 
-  renderCountrySelects(root);
+  // The country select lives in the optional markets part: load it only when the page uses it.
+  if (within(root, `${sel('country-select')},${sel('country-bind')}`).length) {
+    loadPart('markets').then((m) => m.renderCountrySelects(root)).catch((err) => reportError(err, 'markets'));
+  }
 
   qsa(root, sel('account-link')).forEach((a) => {
     a.setAttribute('href', `https://${cfg.domain}/account`);
@@ -70,132 +59,10 @@ export function mount(root = document) {
   return count;
 }
 
-/** Mounts one product root. Returns true when a product request was started. */
-function mountProduct(el) {
-  if (mountedProducts.has(el)) return false;
-  const { key, fromUrl, raw } = 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);
-    }
-    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');
-  getProduct(key)
-    .then((p) => {
-      if (!current()) 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);
-    })
-    .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);
-      }
-    });
-  return true;
-}
-
 // ---------------------------------------------------------------------------
 // Markets: country select + switching
 // ---------------------------------------------------------------------------
 
-/**
- * select[tether-country-select]: countries the store sells to (Shopify Markets).
- * tether-country-label="{name} ({currency})" sets the option text ({name}, {code}, {currency}, {symbol}).
- * tether-country-bind="name|code|currency|symbol" shows the current country anywhere.
- */
-function renderCountrySelects(root = document) {
-  const selects = within(root, `select${sel('country-select')}`);
-  const binds = within(root, sel('country-bind'));
-  if (!selects.length && !binds.length) return Promise.resolve();
-  return getLocalization().then((loc) => {
-    const current = (cfg.country || loc.country?.isoCode || '').toUpperCase();
-    const countries = [...(loc.availableCountries || [])].sort((a, b) => a.name.localeCompare(b.name, cfg.locale || undefined));
-    const info = countries.find((c) => c.isoCode === current) || loc.country;
-    const fill = (tpl, c) => tpl.replace(/\{name\}/g, c.name).replace(/\{code\}/g, c.isoCode)
-      .replace(/\{currency\}/g, c.currency?.isoCode || '').replace(/\{symbol\}/g, c.currency?.symbol || '');
-    selects.forEach((s) => {
-      const tpl = s.getAttribute(attr('country-label')) || '{name} ({currency})';
-      s.innerHTML = '';
-      countries.forEach((c) => s.appendChild(new Option(fill(tpl, c), c.isoCode)));
-      s.value = current;
-      if (s.value !== current) s.selectedIndex = -1; // a country the store doesn't sell to
-      s.disabled = countries.length < 2 && !s.hasAttribute(attr('always-enabled'));
-    });
-    binds.forEach((el) => {
-      const k = get(el, 'country-bind') || 'name';
-      const v = { name: info?.name, code: info?.isoCode, currency: info?.currency?.isoCode, symbol: info?.currency?.symbol }[k];
-      el.textContent = v || '';
-    });
-  }).catch((err) => reportError(err, 'country select'));
-}
-
-/**
- * Switches the market: prices, currency and translations follow (@inContext), the cart's
- * buyerIdentity.countryCode is updated, and every product and list on the page re-renders.
- *   Tether.setCountry('DE')            Tether.setCountry('BE', { language: 'FR' })
- */
-export async function setCountry(code, { language, remember = true } = {}) {
-  const country = toCountry(code);
-  if (!country) throw new TetherError(`Not a country code: ${code}`, { code: 'INVALID_COUNTRY' });
-  const lang = language === undefined ? cfg.language : toLanguage(language);
-  const changed = country !== String(cfg.country || '').toUpperCase() || lang !== cfg.language;
-  cfg.country = country;
-  cfg.language = lang || undefined;
-  if (remember) rememberMarket({ country, language: lang });
-  if (!changed) { renderCountrySelects(); return Cart.state; }
-
-  clearProductCache();
-  const jobs = [];
-  if (language !== undefined) clearLocalization(); // country names follow the language
-  // Only an existing cart moves; switching country never creates one.
-  if (Cart.id()) jobs.push(Cart.setBuyerIdentity({ countryCode: country }, { create: false }).catch((err) => reportError(err, 'cart country')));
-
-  pruneLive();
-  liveLists.forEach((list) => jobs.push(list.load()));
-  liveProducts.forEach((el) => {
-    if (el.closest(listSelector())) return; // re-rendered by its list
-    mountedProducts.delete(el);
-    mountProduct(el);
-  });
-
-  renderCountrySelects();
-  emit('country-changed', { country, language: cfg.language });
-  await Promise.all(jobs);
-  return Cart.state;
-}
-
-/** 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 || '');
-}
-
 /** Call before a page transition removes `root` (closes the drawer etc.). */
 export function unmount() {
   Cart.close();
@@ -278,14 +145,43 @@ function bindControls() {
       try {
         const cart = await Cart.applyDiscount(code);
         const ok = (cart?.discountCodes || []).find((d) => d.code.toLowerCase() === code.toLowerCase())?.applicable;
+        // An invalid code doesn't stay in the cart (Shopify would warn about it on every change).
+        if (!ok) await Cart.removeDiscount(code).catch(() => {});
         form.classList.toggle('is-invalid', !ok);
         emit(ok ? 'discount-applied' : 'discount-invalid', { code }, form);
         if (ok && input) input.value = '';
       } catch (err) { form.classList.add('is-invalid'); reportError(err, 'discount'); }
     });
+  }, true); // capture: before a router (Astro's ClientRouter) turns the submit into a navigation
+  document.addEventListener('input', (e) => { e.target.closest?.(sel('discount-form'))?.classList.remove('is-invalid'); });
+
+  // Astro View Transitions (<ClientRouter />): mount every new page, close the cart while leaving.
+  if (cfg.astro !== false) {
+    document.addEventListener('astro:page-load', () => mount(document));
+    document.addEventListener('astro:before-swap', () => unmount());
+  }
+
+  // Back online after a failed load: try the failed products and lists again.
+  window.addEventListener('online', () => {
+    retryFailed();
+    liveLists.forEach((l) => { if (l.root.getAttribute(attr('state')) === 'error') l.load(); });
   });
 
-  document.addEventListener('keydown', (e) => { if (e.key === 'Escape' && Cart.isOpen()) Cart.close(); });
+  document.addEventListener('keydown', (e) => {
+    if (!Cart.isOpen()) return;
+    if (e.key === 'Escape') { Cart.close(); return; }
+    if (e.key !== 'Tab' || cfg.cartFocus === false) return;
+    // Keep Tab inside the open cart.
+    const d = Cart.drawers().find((x) => x.classList.contains(cfg.cartDrawerOpenClass));
+    const f = d ? focusables(d) : [];
+    if (!f.length) return;
+    const first = f[0];
+    const last = f[f.length - 1];
+    if (!d.contains(document.activeElement) || (e.shiftKey && document.activeElement === first) || (!e.shiftKey && document.activeElement === last)) {
+      e.preventDefault();
+      (e.shiftKey ? last : first).focus();
+    }
+  });
 }
 
 function dataKeySel() { return `[data-${cfg.prefix}-key]`; }
@@ -333,17 +229,10 @@ export function init(overrides = {}) {
     return initPromise;
   }
 
-  // Detected market (saved choice, server hint, Webflow locale) wins over the static config.
-  const market = detectMarket(cfg.markets);
-  if (market.country) cfg.country = market.country;
-  if (market.language) cfg.language = market.language;
-  if (market.locale && !overrides.locale && !window.TETHER_CONFIG?.locale) cfg.locale = market.locale;
-  if (market.sources && Object.keys(market.sources).length) log('market', market);
-
   bindControls();
   if (cfg.observe) startObserver();
 
-  initPromise = Cart.init().then(async (cart) => {
+  initPromise = applyMarket(overrides).then(() => Cart.init()).then(async (cart) => {
     // A saved cart from another market: move it to this one, so prices match the page.
     const want = cfg.country ? String(cfg.country).toUpperCase() : null;
     if (cart && want && cart.buyerIdentity?.countryCode && cart.buyerIdentity.countryCode !== want) {
@@ -355,6 +244,33 @@ export function init(overrides = {}) {
   return initPromise;
 }
 
+/**
+ * Detected market (saved choice, server hint, Webflow locale) wins over the static config.
+ * Without markets.detect only the visitor's saved choice applies, read here without loading
+ * the markets part.
+ */
+async function applyMarket(overrides) {
+  const m = cfg.markets || {};
+  if (m.detect === false) return;
+  let market = null;
+  if (m.detect) {
+    try { market = (await loadPart('markets')).detectMarket(m); } catch (err) { reportError(err, 'markets'); return; }
+  } else if (m.remember !== false) {
+    try { market = JSON.parse(localStorage.getItem(`${cfg.prefix}:market:${cfg.domain}`) || 'null'); } catch { /* none */ }
+    if (market && !/^[A-Z]{2}$/.test(market.country || '')) market = null;
+  }
+  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; // the visitor's market wins over the default
+  log('market', market);
+}
+
+/** Tether.setCountry('DE'): loads the markets part on first use. */
+export function setCountry(code, opts) {
+  return loadPart('markets').then((m) => m.setCountry(code, opts));
+}
+
 function startObserver() {
   if (observer || typeof MutationObserver === 'undefined') return;
   let t = null;
@@ -386,13 +302,16 @@ export const api = {
   normalizeProductKey,
   clearProductCache,
   formatMoney,
+  imageUrl,
   plans,
   TetherError,
   resolveProductKey,
   setCountry,
-  detectMarket: (markets) => detectMarket(markets || cfg.markets),
-  getLocalization,
-  diagnose: (opts) => diagnose({ ...opts, version: VERSION }),
+  detectMarket: (markets) => loadPart('markets').then((m) => m.detectMarket(markets || cfg.markets)),
+  getLocalization: () => loadPart('markets').then((m) => m.getLocalization()),
+  diagnose: (opts) => loadPart('diagnose').then((m) => m.diagnose({ ...opts, version: VERSION })),
+  __core: coreModules,
+  __parts: {},
   on(name, fn) {
     const h = (e) => fn(e.detail, e);
     document.addEventListener(`${cfg.prefix}:${name}`, h);
@@ -405,7 +324,8 @@ export default api;
 // Auto-start for the plain <script> setup.
 if (typeof window !== 'undefined' && typeof document !== 'undefined') {
   window.Tether = api;
-  const auto = window.TETHER_CONFIG && window.TETHER_CONFIG.autoMount !== false;
+  // Not with a framework integration (Astro), which starts Tether itself.
+  const auto = window.TETHER_CONFIG && window.TETHER_CONFIG.autoMount !== false && !window.TETHER_INTEGRATION;
   if (auto) {
     const start = () => init().then(() => mount(document));
     if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start, { once: true });

package/src/initial.js

@@ -0,0 +1,66 @@
+/**
+ * What the browser script will show first for a product, so a server can render the same
+ * (no flash when Tether takes over): the selected variant, price, purchase mode and conditions.
+ * Same rules as src/product.js: first available variant (or the one in ?variant=), subscription
+ * when the product requires a plan or defaultPurchase is 'subscription', low stock at 5 or fewer.
+ */
+import { GID, allPlans, allocationFor, findPlan, planPrice, planSavings } from './selling-plans.js';
+
+export function initialState(product, { variant, sellingPlan, defaultPurchase = 'one-time' } = {}) {
+  const vs = product?.variants?.nodes || [];
+  const gid = variant ? GID.variant(variant) : null;
+  const v = (gid && vs.find((x) => x.id === gid)) || vs.find((x) => x.availableForSale) || vs[0] || null;
+  if (!v) return null;
+  const selected = Object.fromEntries((v.selectedOptions || []).map((o) => [o.name, o.value]));
+
+  const plans = allPlans(product);
+  const fromUrl = findPlan(product, sellingPlan);
+  let plan = plans.length ? (fromUrl || plans[0]) : null;
+  if (plan && !allocationFor(v, plan.id)) plan = plans.find((p) => allocationFor(v, p.id)) || plan;
+  const wantsSub = product.requiresSellingPlan || fromUrl || defaultPurchase === 'subscription';
+  const subscriptionAvailable = plans.some((p) => allocationFor(v, p.id));
+  const purchase = plans.length && wantsSub ? 'subscription' : 'one-time';
+  const sub = purchase === 'subscription' && subscriptionAvailable;
+
+  const price = sub ? planPrice(v, plan.id) : v.price;
+  const compareAt = sub ? (allocationFor(v, plan.id)?.priceAdjustments?.[0]?.compareAtPrice || v.compareAtPrice) : v.compareAtPrice;
+  const onSale = Boolean(compareAt && parseFloat(compareAt.amount) > parseFloat(price.amount));
+  const q = v.quantityAvailable;
+
+  return {
+    variant: v,
+    selected,
+    purchase,
+    plan: sub ? plan : null,
+    /** The plan list (tether-plan-list="all"): selected one gets is-selected, unavailable ones is-unavailable. */
+    plans: plans.map((p) => ({
+      id: p.id, name: p.name, price: planPrice(v, p.id), savings: planSavings(v, p.id).percentage,
+      selected: sub && p.id === plan.id, available: Boolean(allocationFor(v, p.id)),
+    })),
+    /** Savings of the selected plan in % (tether-bind="subscription-savings"), 0 without one. */
+    savings: plan ? planSavings(v, plan.id).percentage : 0,
+    price,
+    compareAtPrice: onSale ? compareAt : null,
+    available: v.availableForSale,
+    /** The tether-show conditions, e.g. hidden={!state.show['out-of-stock']}. */
+    show: {
+      'in-stock': v.availableForSale,
+      'out-of-stock': !v.availableForSale,
+      backorder: Boolean(v.availableForSale && v.currentlyNotInStock),
+      'on-sale': onSale,
+      'not-on-sale': !onSale,
+      'has-variants': vs.length > 1,
+      'single-variant': vs.length === 1,
+      'low-stock': q != null && q > 0 && q <= 5,
+      'subscription-available': subscriptionAvailable,
+      'subscription-unavailable': !subscriptionAvailable,
+      'subscription-only': Boolean(product.requiresSellingPlan),
+      'one-time-available': !product.requiresSellingPlan,
+      'subscription-selected': sub,
+      'one-time-selected': !sub,
+    },
+    /** Option values with no available variant (given the other selected options): class is-unavailable. */
+    isUnavailable: (name, value) => !vs.some((x) => x.availableForSale && x.selectedOptions.every((o) =>
+      (o.name === name ? o.value === value : selected[o.name] === o.value))),
+  };
+}

package/src/lazy-iife.js

@@ -0,0 +1,43 @@
+/**
+ * <script> build: optional parts are separate files next to tether(.min).js, e.g.
+ * tether.markets.min.js, loaded on first use. Override the folder with config.partsUrl.
+ */
+import * as config from './config.js';
+import * as client from './client.js';
+import * as dom from './dom.js';
+import * as fragments from './fragments.js';
+import * as loader from './loader.js';
+import * as sellingPlans from './selling-plans.js';
+import * as status from './status.js';
+import * as cart from './cart.js';
+import * as product from './product.js';
+import * as collection from './collection.js';
+import * as mounting from './mounting.js';
+
+const { cfg } = config;
+
+/** The modules a part may use, shared instead of bundled twice (scripts/build.mjs maps imports to these). */
+export const coreModules = {
+  'config.js': config, 'client.js': client, 'dom.js': dom, 'fragments.js': fragments, 'loader.js': loader,
+  'selling-plans.js': sellingPlans, 'status.js': status, 'cart.js': cart, 'product.js': product,
+  'collection.js': collection, 'mounting.js': mounting,
+};
+
+const self = typeof document !== 'undefined' ? document.currentScript?.src || '' : '';
+const parts = {};
+
+export function loadPart(name) {
+  if (parts[name]) return parts[name];
+  const base = cfg.partsUrl || self.replace(/[^/]*$/, '');
+  const min = /\.min\.js(\?|$)/.test(self) || !self ? '.min' : '';
+  const url = `${base.replace(/\/?$/, '/')}tether.${name}${min}.js`;
+  parts[name] = new Promise((resolve, reject) => {
+    const s = document.createElement('script');
+    s.src = url;
+    s.async = true;
+    s.onload = () => (window.Tether?.__parts?.[name] ? resolve(window.Tether.__parts[name]) : reject(new Error(`${url} did not register`)));
+    s.onerror = () => { delete parts[name]; reject(new Error(`Could not load ${url}. Host it next to the Tether script, or set partsUrl.`)); };
+    document.head.appendChild(s);
+  });
+  return parts[name];
+}

package/src/lazy.js

@@ -0,0 +1,9 @@
+/**
+ * Optional parts that most pages never need, loaded on first use.
+ * ESM / Node: dynamic import (bundlers split these into their own chunks).
+ * The <script> build swaps this file for lazy-iife.js (see scripts/build.mjs).
+ */
+export const loadPart = (name) => (name === 'diagnose' ? import('./diagnose.js') : import('./markets-ui.js'));
+
+// Only the <script> build shares its modules with separately loaded parts.
+export const coreModules = undefined;

package/src/loader.js

@@ -74,7 +74,7 @@ async function flush() {
     parts.push(`h${i}: product(handle: $h${i}) { ...TetherProduct }`);
   });
 
-  const query = `query TetherProducts(${defs.join(', ')}) {\n  ${parts.join('\n  ')}\n}\n${productFragment()}`;
+  const query = `query TetherProducts(${defs.join(',')}) { ${parts.join(' ')} } ${productFragment()}`;
   log('fetch products', keys);
 
   const settle = (k, fn) => {
@@ -90,7 +90,11 @@ async function flush() {
     handles.forEach((h, i) => { if (data[`h${i}`]) got.set(h, data[`h${i}`]); });
 
     keys.forEach((k) => settle(k, (r) => {
-      if (got.has(k)) { if (gen === generation) primeProduct(got.get(k)); r.resolve(got.get(k)); } else {
+      if (got.has(k)) {
+        const p = got.get(k);
+        if (gen === generation) { primeProduct(p); freshAt.set(p.handle, Date.now()); freshAt.set(p.id, Date.now()); }
+        r.resolve(p);
+      } else {
         if (gen === generation) productCache.delete(k); // don't cache misses: a fix in Shopify works on next load
         r.reject(new TetherError(`Product not found: ${k}`, { code: 'NOT_FOUND' }));
       }
@@ -100,7 +104,44 @@ async function flush() {
   }
 }
 
-export function clearProductCache() { productCache.clear(); generation++; }
+export function clearProductCache() { productCache.clear(); generation++; stale.clear(); freshAt.clear(); }
+
+// ---------------------------------------------------------------------------
+// Hydration: products rendered on the server (tether/server hydrate()) are used at once and
+// refreshed once in the background, so prices and stock are live without a loading state.
+// ---------------------------------------------------------------------------
+
+const stale = new Set(); // keys of products that came from the server and weren't refreshed yet
+const freshAt = new Map(); // key -> when it was last loaded live (this page session)
+const FRESH_MS = 60000;
+
+export function hydrateProducts(products) {
+  (products || []).forEach((p) => {
+    if (!p?.id || !p.handle) return;
+    // Loaded live in the last minute (an earlier page of a View Transition visit): that copy is newer.
+    if (Date.now() - (freshAt.get(p.handle) || 0) < FRESH_MS && productCache.has(p.handle)) return;
+    primeProduct(p);
+    stale.add(p.handle);
+    stale.add(p.id);
+  });
+}
+
+/** True once per server-provided product: the caller refreshes it. */
+export function takeStale(key) {
+  const k = normalizeProductKey(key);
+  if (!stale.has(k)) return false;
+  const p = productCache.get(k);
+  stale.delete(k);
+  // Both keys point to the same product: refresh it once.
+  p?.then?.((x) => { stale.delete(x.handle); stale.delete(x.id); });
+  return true;
+}
+
+/** Fetch these products again (bypassing the cache). */
+export function refreshProducts(keys) {
+  keys.forEach((k) => productCache.delete(normalizeProductKey(k)));
+  return keys.map((k) => getProduct(k));
+}
 
 /**
  * A page of products from a collection (by handle) or from a search query.
@@ -141,11 +182,13 @@ ${fragment}`, { first, after, query: query || undefined, sortKey: sortKey || und
   return { collection: null, products: data.products.nodes, pageInfo: data.products.pageInfo };
 }
 
-export async function getRecommendations(productId, intent = 'RELATED') {
-  const data = await gql(`query TetherRecs($id: ID!, $intent: ProductRecommendationIntent) {
-  productRecommendations(productId: $id, intent: $intent) { ...TetherProduct }
+export async function getRecommendations(product, intent = 'RELATED') {
+  const key = normalizeProductKey(typeof product === 'object' ? product?.id : product);
+  const byId = key?.startsWith('gid://');
+  const data = await gql(`query TetherRecs(${byId ? '$id: ID!' : '$handle: String!'}, $intent: ProductRecommendationIntent) {
+  productRecommendations(${byId ? 'productId: $id' : 'productHandle: $handle'}, intent: $intent) { ...TetherProduct }
 }
-${productFragment()}`, { id: productId, intent });
+${productFragment()}`, byId ? { id: key, intent } : { handle: key, intent });
   const list = data.productRecommendations || [];
   list.forEach(primeProduct);
   return list;

package/src/markets-ui.js

@@ -0,0 +1,89 @@
+/**
+ * Optional part, loaded on first use: market detection, select[tether-country-select],
+ * tether-country-bind and Tether.setCountry(). See markets.js for the detection rules.
+ */
+import { cfg, reportError } from './config.js';
+import { TetherError } from './client.js';
+import { Cart } from './cart.js';
+import { listSelector } from './collection.js';
+import { clearProductCache } from './loader.js';
+import { attr, sel, get, emit } from './dom.js';
+import { within, pruneLive, liveLists, liveProducts, mountedProducts, mountProduct } from './mounting.js';
+import { rememberMarket, getLocalization, clearLocalization, toCountry, toLanguage } from './markets.js';
+
+export { detectMarket, getLocalization } from './markets.js';
+
+export /**
+ * select[tether-country-select]: countries the store sells to (Shopify Markets).
+ * tether-country-label="{name} ({currency})" sets the option text ({name}, {code}, {currency}, {symbol}).
+ * tether-country-bind="name|code|currency|symbol" shows the current country anywhere.
+ */
+function renderCountrySelects(root = document) {
+  const selects = within(root, `select${sel('country-select')}`);
+  const binds = within(root, sel('country-bind'));
+  if (!selects.length && !binds.length) return Promise.resolve();
+  return getLocalization().then((loc) => {
+    const current = (cfg.country || loc.country?.isoCode || '').toUpperCase();
+    const countries = [...(loc.availableCountries || [])].sort((a, b) => a.name.localeCompare(b.name, cfg.locale || undefined));
+    const info = countries.find((c) => c.isoCode === current) || loc.country;
+    const fill = (tpl, c) => tpl.replace(/\{name\}/g, c.name).replace(/\{code\}/g, c.isoCode)
+      .replace(/\{currency\}/g, c.currency?.isoCode || '').replace(/\{symbol\}/g, c.currency?.symbol || '');
+    selects.forEach((s) => {
+      const tpl = s.getAttribute(attr('country-label')) || '{name} ({currency})';
+      // tether-countries="NL,DE,BE": only these (in your order); otherwise every country of the store.
+      const only = (s.getAttribute(attr('countries')) || '').toUpperCase().split(/[\s,]+/).filter(Boolean);
+      const list = only.length ? only.map((c) => countries.find((x) => x.isoCode === c)).filter(Boolean) : countries;
+      s.innerHTML = '';
+      list.forEach((c) => s.appendChild(new Option(fill(tpl, c), c.isoCode)));
+      s.value = current;
+      if (s.value !== current) s.selectedIndex = -1; // a country the store doesn't sell to
+      s.disabled = list.length < 2 && !s.hasAttribute(attr('always-enabled'));
+    });
+    binds.forEach((el) => {
+      const k = get(el, 'country-bind') || 'name';
+      const v = { name: info?.name, code: info?.isoCode, currency: info?.currency?.isoCode, symbol: info?.currency?.symbol }[k];
+      el.textContent = v || '';
+    });
+  }).catch((err) => reportError(err, 'country select'));
+}
+
+/**
+ * Switches the market: prices, currency and translations follow (@inContext), the cart's
+ * buyerIdentity.countryCode is updated, and every product and list on the page re-renders.
+ *   Tether.setCountry('DE')            Tether.setCountry('BE', { language: 'FR' })
+ */
+export async function setCountry(code, { language, locale, remember = true } = {}) {
+  const country = toCountry(code);
+  if (!country) throw new TetherError(`Not a country code: ${code}`, { code: 'INVALID_COUNTRY' });
+  // Money format: the option, else a markets.locales entry for this country, else unchanged.
+  const entry = Object.values(cfg.markets?.locales || {}).find((m) => toCountry(m?.country) === country);
+  const own = locale || entry?.locale;
+  const loc = own || cfg.locale;
+  const lang = language === undefined ? cfg.language : toLanguage(language);
+  const changed = country !== String(cfg.country || '').toUpperCase() || lang !== cfg.language || loc !== cfg.locale;
+  cfg.country = country;
+  cfg.language = lang || undefined;
+  cfg.locale = loc;
+  if (remember) rememberMarket({ country, language: lang, locale: own });
+  if (!changed) { renderCountrySelects(); return Cart.state; }
+
+  clearProductCache();
+  const jobs = [];
+  if (language !== undefined) clearLocalization(); // country names follow the language
+  // Only an existing cart moves; switching country never creates one.
+  if (Cart.id()) jobs.push(Cart.setBuyerIdentity({ countryCode: country }, { create: false }).catch((err) => reportError(err, 'cart country')));
+
+  pruneLive();
+  liveLists.forEach((list) => jobs.push(list.load()));
+  liveProducts.forEach((el) => {
+    if (el.closest(listSelector())) return; // re-rendered by its list
+    mountedProducts.delete(el);
+    mountProduct(el);
+  });
+
+  renderCountrySelects();
+  emit('country-changed', { country, language: cfg.language });
+  await Promise.all(jobs);
+  return Cart.state;
+}
+

package/src/markets.js

@@ -112,7 +112,7 @@ export function detectMarket(markets = cfg.markets, env = defaultEnv()) {
 
 export function rememberMarket(market) {
   if (cfg.markets?.remember === false) return;
-  try { localStorage.setItem(storageKey(), JSON.stringify({ country: market.country, language: market.language || undefined })); } catch { /* private mode */ }
+  try { localStorage.setItem(storageKey(), JSON.stringify({ country: market.country, language: market.language || undefined, locale: market.locale || undefined })); } catch { /* private mode */ }
 }
 
 let localizationPromise = null;