@occluze/tether 0.4.0 → 0.6.0

package/src/product.js

@@ -5,7 +5,7 @@
 import { cfg, reportError } from './config.js';
 import {
   attr, sel, get, has, qsa, scoped, emit, formatMoney, formatDate, setText, setImage, show,
-  setSelected, repeat, productUrl, notifyLayoutChanged, watchImages, busy, parseJSONAttr, toAttributes,
+  setSelected, repeat, productUrl, notifyLayoutChanged, watchImages, busy, parseJSONAttr, toAttributes, sameImage, hasTemplate, formatPercent,
 } from './dom.js';
 import { Cart } from './cart.js';
 import { STATUS_KEYS, ownedBy } from './status.js';
@@ -25,6 +25,13 @@ function metafieldValue(product, ref) {
   return mf || null;
 }
 
+// Option names as written in the markup (the build's language), by product handle. With another
+// language Shopify translates them (Size -> Größe), so attributes are matched by position instead.
+const knownOptionNames = new Map();
+export function rememberOptionNames(products) {
+  (products || []).forEach((p) => { if (p?.handle && !knownOptionNames.has(p.handle)) knownOptionNames.set(p.handle, (p.options || []).map((o) => o.name)); });
+}
+
 export class ProductScope {
   constructor(root, product) {
     this.root = root;
@@ -76,6 +83,14 @@ export class ProductScope {
 
   // ------------------------------------------------------------ state
 
+  /** The product's option name for a name used in the markup (same name, or same position). */
+  optName(authored) {
+    const opts = this.product?.options || [];
+    if (!authored || opts.some((o) => o.name === authored)) return authored;
+    const i = (knownOptionNames.get(this.product.handle) || []).indexOf(authored);
+    return i >= 0 && opts[i] ? opts[i].name : authored;
+  }
+
   initSelection() {
     const vs = this.product.variants.nodes;
     const first = vs.find((v) => v.availableForSale) || vs[0];
@@ -152,7 +167,16 @@ export class ProductScope {
 
   select(name, value) {
     if (this.selected[name] === value) return;
-    this.selected[name] = value;
+    const vs = this.product.variants.nodes.filter((v) => v.selectedOptions.some((o) => o.name === name && o.value === value));
+    if (!vs.length) return; // a value no variant has: nothing to select, keep the visitor's choice
+    const next = { ...this.selected, [name]: value };
+    if (!vs.some((v) => v.selectedOptions.every((o) => next[o.name] === o.value))) {
+      // That combination doesn't exist: the closest variant with this value (most other choices kept, available first).
+      const score = (v) => v.selectedOptions.filter((o) => o.name !== name && this.selected[o.name] === o.value).length * 2 + (v.availableForSale ? 1 : 0);
+      const best = vs.reduce((a, b) => (score(b) > score(a) ? b : a));
+      best.selectedOptions.forEach((o) => { next[o.name] = o.value; });
+    }
+    this.selected = next;
     this.renderVariant();
   }
 
@@ -208,7 +232,7 @@ export class ProductScope {
       const opt = t.closest(sel('option-value'));
       if (own(opt) && opt.closest(sel('option-list'))) {
         e.preventDefault();
-        this.select(get(opt.closest(sel('option-list')), 'option-list'), get(opt, 'option-value'));
+        this.select(this.optName(get(opt.closest(sel('option-list')), 'option-list')), get(opt, 'option-value'));
         return;
       }
 
@@ -234,7 +258,7 @@ export class ProductScope {
     this.root.addEventListener('change', (e) => {
       const t = e.target;
       if (!own(t)) return;
-      if (t.matches(`select${sel('option')}`)) this.select(get(t, 'option'), t.value);
+      if (t.matches(`select${sel('option')}`)) this.select(this.optName(get(t, 'option')), t.value);
       else if (t.matches(`select${sel('variant-select')}`)) this.selectVariant(t.value);
       else if (t.matches(`select${sel('plan')}`)) {
         if (t.value) this.selectPlan(t.value); else this.setPurchase('one-time');
@@ -266,6 +290,11 @@ export class ProductScope {
   // ------------------------------------------------------------ render
 
   renderProduct() {
+    const p0 = this.product;
+    if (!knownOptionNames.has(p0.handle)) {
+      const authored = this.$(`${sel('option-list')},select${sel('option')}`).map((e) => get(e, 'option-list') || get(e, 'option'));
+      if (authored.some((n) => p0.options.some((o) => o.name === n))) rememberOptionNames([p0]);
+    }
     const p = this.product;
 
     this.$(sel('bind')).forEach((el) => {
@@ -289,7 +318,11 @@ export class ProductScope {
           el.setAttribute('href', productUrl(p.handle, p.id));
           if (key === 'url' && !el.firstElementChild && !el.textContent.trim()) setText(el, p.title);
           return undefined;
-        case 'images':
+        case 'images': {
+          // Server-rendered gallery with the same images: keep it as it is.
+          const imgs = [...el.children].map((n) => (n.tagName === 'IMG' ? n : n.querySelector('img')));
+          if (!hasTemplate(el) && imgs.length === p.images.nodes.length && imgs.every((im, i) => sameImage(im?.getAttribute('src'), p.images.nodes[i].url))) return undefined;
+        }
           return repeat(el, p.images.nodes, (node, img) => {
             const target = node.matches(`img,${sel('bind', 'image')}`) ? node : node.querySelector('img') || node;
             setImage(target, img.url, img.altText || p.title);
@@ -316,7 +349,7 @@ export class ProductScope {
     });
 
     this.$(sel('option-list')).forEach((container) => {
-      const name = get(container, 'option-list');
+      const name = this.optName(get(container, 'option-list'));
       const opt = p.options.find((o) => o.name === name);
       if (!opt || (opt.optionValues.length <= 1 && has(container, 'hide-single'))) return show(container, false);
       return repeat(container, opt.optionValues, (node, v) => {
@@ -330,7 +363,7 @@ export class ProductScope {
     });
 
     this.$(`select${sel('option')}`).forEach((s) => {
-      const opt = p.options.find((o) => o.name === get(s, 'option'));
+      const opt = p.options.find((o) => o.name === this.optName(get(s, 'option')));
       if (!opt) return show(s, false);
       s.innerHTML = '';
       opt.optionValues.forEach((v) => s.appendChild(new Option(v.name, v.name)));
@@ -395,7 +428,7 @@ export class ProductScope {
     const total = { amount: (parseFloat(price.amount) * Math.max(1, this.quantity)).toFixed(2), currencyCode: price.currencyCode };
 
     const fm = formatMoney;
-    const pct = (n) => (n ? `${n}%` : '');
+    const pct = (n) => formatPercent(n);
     // Text binds: name -> value (functions, so only the binds on the page are computed).
     const text = {
       price: () => fm(price),
@@ -404,7 +437,8 @@ export class ProductScope {
       'subscription-price': () => fm(subPrice),
       'subscription-savings': () => pct(savings.percentage),
       'subscription-savings-amount': () => fm(savings.amount),
-      'checkout-charge': () => fm(sub ? planCheckoutCharge(v, this.planId) : price),
+      // What the visitor pays today for the chosen quantity (prepaid plans charge more up front).
+      'checkout-charge': () => { const c = sub ? planCheckoutCharge(v, this.planId) : price; return c && fm({ amount: (parseFloat(c.amount) * Math.max(1, this.quantity)).toFixed(2), currencyCode: c.currencyCode }); },
       'plan-name': () => plan?.name,
       'plan-description': () => plan?.description,
       'plan-group': () => plan?.group?.name,
@@ -425,10 +459,10 @@ export class ProductScope {
       else if (text[k]) setText(el, text[k]());
     });
 
-    this.$(sel('option-selected')).forEach((el) => setText(el, this.selected[get(el, 'option-selected')] || ''));
+    this.$(sel('option-selected')).forEach((el) => setText(el, this.selected[this.optName(get(el, 'option-selected'))] || ''));
 
     this.$(sel('option-list')).forEach((container) => {
-      const name = get(container, 'option-list');
+      const name = this.optName(get(container, 'option-list'));
       qsa(container, sel('option-value')).forEach((node) => {
         const value = get(node, 'option-value');
         setSelected(node, this.selected[name] === value);
@@ -438,7 +472,7 @@ export class ProductScope {
       });
     });
 
-    this.$(`select${sel('option')}`).forEach((s) => { s.value = this.selected[get(s, 'option')] || ''; });
+    this.$(`select${sel('option')}`).forEach((s) => { s.value = this.selected[this.optName(get(s, 'option'))] || ''; });
     this.$(`select${sel('variant-select')}`).forEach((s) => { s.value = v.id; });
 
     // Subscription UI
@@ -462,6 +496,7 @@ export class ProductScope {
         const k = get(el, 'plan-bind');
         const val = {
           name: () => planObj?.name,
+          option: () => (planObj?.options || []).map((o) => o.value).join(', '), // e.g. "1 month", without the store's price text
           description: () => planObj?.description,
           price: () => fm(planPrice(v, id)),
           savings: () => pct(s.percentage),
@@ -474,6 +509,7 @@ export class ProductScope {
 
     this.$(`select${sel('plan')}`).forEach((s) => { s.value = sub ? this.planId : ''; });
 
+    const low = v.quantityAvailable != null && v.quantityAvailable > 0 && v.quantityAvailable <= (cfg.lowStock ?? 5);
     const conds = {
       'in-stock': v.availableForSale,
       'out-of-stock': !v.availableForSale,
@@ -482,7 +518,8 @@ export class ProductScope {
       'not-on-sale': !onSale,
       'has-variants': p.variants.nodes.length > 1,
       'single-variant': p.variants.nodes.length === 1,
-      'low-stock': v.quantityAvailable != null && v.quantityAvailable > 0 && v.quantityAvailable <= 5,
+      'low-stock': low,
+      'plenty-in-stock': v.availableForSale && !low,
       'subscription-available': this.subscriptionAvailable,
       'subscription-unavailable': !this.subscriptionAvailable,
       'subscription-only': Boolean(p.requiresSellingPlan),
@@ -528,5 +565,6 @@ export class ProductScope {
       product: p, variant: v, selected: { ...this.selected },
       purchase: this.purchase, sellingPlanId: sub ? this.planId : null,
     }, this.root);
+
   }
 }

package/src/search.js

@@ -0,0 +1,153 @@
+/**
+ * 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">
+ *     <div tether-search-results>
+ *       <div tether-search-products><a><img tether-search-bind="image" max-width="120"><span tether-search-bind="title"></span> <span tether-search-bind="price"></span></a></div>
+ *       <div tether-search-queries><a><span tether-search-bind="text"></span></a></div>
+ *       <div tether-search-collections><a><span tether-search-bind="title"></span></a></div>
+ *       <p tether-show="search-empty">No results</p>
+ *     </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).
+ */
+import { cfg, reportError } from './config.js';
+import { gql } from './client.js';
+import { attr, sel, get, qsa, setText, setImage, repeat, show, formatMoney, productUrl, emit } from './dom.js';
+
+const QUERY = `query TetherPredictive($q: String!, $limit: Int!) {
+  predictiveSearch(query: $q, limit: $limit, limitScope: EACH, types: [PRODUCT, COLLECTION, QUERY]) {
+    products { id handle title availableForSale featuredImage { url altText } priceRange { minVariantPrice { amount currencyCode } } }
+    collections { handle title image { url altText } }
+    queries { text }
+  }
+}`;
+
+const mounted = new WeakSet();
+let uid = 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); } });
+}
+
+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');
+    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');
+    }
+  }
+
+  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);
+    });
+    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);
+    });
+    fill('search-collections', collections, (node, c) => {
+      binds(node, { title: c.title, image: c.image });
+      link(node, `${(cfg.collectionPath || '/collection').replace(/\/$/, '')}/${c.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)}`);
+    });
+    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);
+    });
+    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]);
+    });
+  }
+
+  function link(node, href) {
+    const a = node.tagName === 'A' ? node : node.querySelector('a');
+    if (a) { a.setAttribute('href', href); a.setAttribute('role', 'option'); }
+  }
+
+  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); });
+}

package/src/server.js

@@ -0,0 +1,251 @@
+/**
+ * @occluze/tether/server: Shopify product data at build time or on the server (Astro, Eleventy,
+ * Node, Cloudflare Workers). No browser APIs. Uses the same queries as the browser script, so
+ * products handed over with hydrate() are exactly what Tether expects and need no extra request.
+ *
+ *   import { createStorefront } from '@occluze/tether/server';
+ *   const shop = createStorefront({ domain, token, country: 'NL' });
+ *   const product = await shop.getProduct('coffee-box');
+ *   const all = await shop.allProducts();
+ */
+import { DEFAULTS } from './config.js';
+import { request, withContext, TetherError } from './client.js';
+import { productFragment, collectionFields } from './fragments.js';
+import * as plans from './selling-plans.js';
+import { imageUrl, formatPercent } from './dom.js';
+import { initialState } from './initial.js';
+
+export { imageUrl, initialState, formatPercent };
+
+export { TetherError, plans, withContext };
+
+const isGid = (v) => typeof v === 'string' && v.startsWith('gid://');
+
+/** Handle, numeric id, gid or product URL -> handle or gid. */
+export function productKey(raw) {
+  const v = String(raw ?? '').trim();
+  if (!v) return null;
+  if (isGid(v)) return v;
+  if (/^\d+$/.test(v)) return `gid://shopify/Product/${v}`;
+  const m = v.match(/\/products\/([^/?#]+)/);
+  return m ? m[1] : v;
+}
+
+/** Money as text, e.g. formatMoney({ amount: '30.0', currencyCode: 'EUR' }, 'nl-NL') -> "€ 30,00". */
+export function formatMoney(money, locale) {
+  if (!money) return '';
+  const amount = parseFloat(money.amount);
+  if (Number.isNaN(amount)) return '';
+  try {
+    return new Intl.NumberFormat(locale || undefined, { style: 'currency', currency: money.currencyCode }).format(amount);
+  } catch {
+    return `${money.currencyCode} ${amount.toFixed(2)}`;
+  }
+}
+
+/** productPath '/products' -> /products/<handle>; templates '/p?handle={handle}' and '{id}' work too. */
+export function productUrl(handle, { productPath = '/product', id } = {}) {
+  if (!/\{(handle|id)\}/.test(productPath)) return `${productPath.replace(/\/$/, '')}/${handle}`;
+  return productPath.replace(/\{handle\}/g, encodeURIComponent(handle || '')).replace(/\{id\}/g, encodeURIComponent(id ? String(id).split('/').pop() : ''));
+}
+
+/** JSON for a <script> tag: escapes < so product text can never close the tag. */
+const safeJson = (v) => JSON.stringify(v).replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+
+// createStorefront(import.meta.env) works too: these env names map to domain and token.
+const ENV = {
+  domain: ['PUBLIC_SHOPIFY_DOMAIN', 'PUBLIC_SHOPIFY_STORE_DOMAIN', 'SHOPIFY_DOMAIN'],
+  token: ['PUBLIC_SHOPIFY_STOREFRONT_TOKEN', 'PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN', 'SHOPIFY_STOREFRONT_TOKEN'],
+};
+
+export function createStorefront(options = {}) {
+  const known = Object.fromEntries(Object.entries(options).filter(([k]) => k in DEFAULTS || k === 'fetch' || k === 'pageSize' || k === 'siteUrl'));
+  const conf = { ...DEFAULTS, ...known };
+  for (const [key, names] of Object.entries(ENV)) if (!conf[key]) conf[key] = names.map((n) => options[n]).find(Boolean) || '';
+  conf.domain = String(conf.domain || '').replace(/^https?:\/\//, '').replace(/\/.*$/, '');
+  if (!conf.domain || !conf.token) {
+    throw new TetherError('createStorefront needs domain and token: pass them, or import.meta.env with PUBLIC_SHOPIFY_DOMAIN and PUBLIC_SHOPIFY_STOREFRONT_TOKEN', { code: 'NOT_CONFIGURED' });
+  }
+  const pageSize = options.pageSize || 25;
+  const q = (query, variables, opts) => request(conf, query, variables, opts);
+  const fragment = () => productFragment(conf);
+
+  async function getProduct(raw) {
+    const key = productKey(raw);
+    if (!key) return null;
+    const data = isGid(key)
+      ? await q(`query TetherServerProductById($id: ID!) { node(id: $id) { ... on Product { ...TetherProduct } } }\n${fragment()}`, { id: key })
+      : await q(`query TetherServerProduct($handle: String!) { product(handle: $handle) { ...TetherProduct } }\n${fragment()}`, { handle: key });
+    const p = isGid(key) ? data.node : data.product;
+    return p && p.id ? p : null;
+  }
+
+  async function getProducts({ collection, query, first = pageSize, after = null, sortKey, reverse = false, filters } = {}) {
+    if (collection) {
+      const data = await q(`query TetherServerCollection($handle: String!, $first: Int!, $after: String, $sortKey: ProductCollectionSortKeys, $reverse: Boolean, $filters: [ProductFilter!]) {
+  collection(handle: $handle) {
+    ${collectionFields()}
+    products(first: $first, after: $after, sortKey: $sortKey, reverse: $reverse, filters: $filters) {
+      nodes { ...TetherProduct }
+      pageInfo { hasNextPage endCursor }
+    }
+  }
+}
+${fragment()}`, { handle: collection, first, after, sortKey: sortKey || undefined, reverse, filters: filters || undefined });
+      if (!data.collection) return { collection: null, products: [], pageInfo: { hasNextPage: false, endCursor: null } };
+      const { products, ...rest } = data.collection;
+      return { collection: rest, products: products.nodes, pageInfo: products.pageInfo };
+    }
+    const data = await q(`query TetherServerProducts($first: Int!, $after: String, $query: String, $sortKey: ProductSortKeys, $reverse: Boolean) {
+  products(first: $first, after: $after, query: $query, sortKey: $sortKey, reverse: $reverse) {
+    nodes { ...TetherProduct }
+    pageInfo { hasNextPage endCursor }
+  }
+}
+${fragment()}`, { first, after, query: query || undefined, sortKey: sortKey || undefined, reverse });
+    return { collection: null, products: data.products.nodes, pageInfo: data.products.pageInfo };
+  }
+
+  /** Every product (of a collection or a search), page by page. For getStaticPaths(). */
+  async function allProducts(opts = {}) {
+    const out = [];
+    let after = null;
+    for (let i = 0; i < 500; i++) {
+      const page = await getProducts({ ...opts, first: pageSize, after });
+      out.push(...page.products);
+      if (!page.pageInfo.hasNextPage) break;
+      after = page.pageInfo.endCursor;
+    }
+    return out;
+  }
+
+  async function getCollection(handle, opts = {}) {
+    const page = await getProducts({ ...opts, collection: handle });
+    return page.collection ? { ...page.collection, products: page.products, pageInfo: page.pageInfo } : null;
+  }
+
+  async function allCollections() {
+    const out = [];
+    let after = null;
+    for (let i = 0; i < 100; i++) {
+      const data = await q(`query TetherServerCollections($first: Int!, $after: String) {
+  collections(first: $first, after: $after) { nodes { ${collectionFields()} } pageInfo { hasNextPage endCursor } }
+}`, { first: 100, after });
+      out.push(...data.collections.nodes);
+      if (!data.collections.pageInfo.hasNextPage) break;
+      after = data.collections.pageInfo.endCursor;
+    }
+    return out;
+  }
+
+  /** By product id (gid or numeric) or handle, so it can run next to getProduct(handle). */
+  async function getRecommendations(product, intent = 'RELATED') {
+    const key = productKey(typeof product === 'object' ? product?.id : product);
+    const byId = key?.startsWith('gid://');
+    const data = await q(`query TetherServerRecs(${byId ? '$id: ID!' : '$handle: String!'}, $intent: ProductRecommendationIntent) {
+  productRecommendations(${byId ? 'productId: $id' : 'productHandle: $handle'}, intent: $intent) { ...TetherProduct }
+}
+${fragment()}`, byId ? { id: key, intent } : { handle: key, intent });
+    return data.productRecommendations || [];
+  }
+
+  /**
+   * A <script> tag that hands products to the browser script: Tether renders them at once,
+   * without its own request, then refreshes prices and stock in the background.
+   * Put it anywhere in the page (Astro: <Fragment set:html={shop.hydrate(products)} />).
+   */
+  /**
+   * { card: true } for lists (home, collections, recommendations): about 40% smaller, without
+   * descriptions, extra images and variant images (cards show the main image). Price, stock and
+   * plans per variant stay. The full product comes with the background refresh.
+   */
+  function hydrate(products, { card = false } = {}) {
+    let list = (Array.isArray(products) ? products : [products]).filter(Boolean);
+    if (card) list = list.map(slim);
+    const payload = { v: 1, at: new Date().toISOString(), country: conf.country || null, language: conf.language || null, products: list };
+    return `<script type="application/json" data-tether-hydrate>${safeJson(payload)}</script>`;
+  }
+
+  /**
+   * schema.org data for search engines (Google's product rich results): a Product, or a ProductGroup
+   * with one Product per variant (price, currency, stock, sku, image, link to ?variant=).
+   * jsonLd(product, { url: 'https://shop.example/products/x' }) -> the <script> tag; jsonLdData() -> the object.
+   */
+  function jsonLdData(p, { url, brand } = {}) {
+    if (!p) return null;
+    const pageUrl = url || (conf.siteUrl ? new URL(productUrl(p.handle, { productPath: conf.productPath, id: p.id }), conf.siteUrl).toString() : undefined);
+    const vid = (v) => String(v.id).split('/').pop();
+    const withVariant = (v) => (pageUrl ? `${pageUrl}${pageUrl.includes('?') ? '&' : '?'}variant=${vid(v)}` : undefined);
+    const text = (p.description || '').trim() || undefined;
+    const images = (p.images?.nodes || []).map((i) => i.url).filter(Boolean);
+    const brandName = brand || p.vendor;
+    // Only buyable on a subscription: the plan price is the price (the first plan the variant has).
+    const priceOf = (v) => {
+      if (!p.requiresSellingPlan) return v.price;
+      const plan = plans.allPlans(p).find((pl) => plans.allocationFor(v, pl.id));
+      return plan ? plans.planPrice(v, plan.id) : v.price;
+    };
+    const offer = (v) => ({
+      '@type': 'Offer',
+      price: priceOf(v)?.amount,
+      priceCurrency: priceOf(v)?.currencyCode,
+      availability: `https://schema.org/${v.availableForSale ? (v.currentlyNotInStock ? 'BackOrder' : 'InStock') : 'OutOfStock'}`,
+      url: withVariant(v),
+    });
+    const vs = p.variants?.nodes || [];
+    const clean = (o) => JSON.parse(JSON.stringify(o)); // drops undefined
+    if (vs.length <= 1) {
+      const v = vs[0];
+      return clean({
+        '@context': 'https://schema.org', '@type': 'Product', name: p.title, description: text, url: pageUrl,
+        image: images, sku: v?.sku || undefined, brand: brandName ? { '@type': 'Brand', name: brandName } : undefined,
+        offers: v ? offer(v) : undefined,
+      });
+    }
+    const varies = { size: 'https://schema.org/size', color: 'https://schema.org/color', colour: 'https://schema.org/color', material: 'https://schema.org/material' };
+    return clean({
+      '@context': 'https://schema.org', '@type': 'ProductGroup', name: p.title, description: text, url: pageUrl,
+      productGroupID: String(p.id).split('/').pop(), image: images,
+      brand: brandName ? { '@type': 'Brand', name: brandName } : undefined,
+      variesBy: [...new Set((p.options || []).map((o) => varies[o.name.toLowerCase()]).filter(Boolean))],
+      hasVariant: vs.map((v) => ({
+        '@type': 'Product',
+        name: `${p.title} - ${v.title}`,
+        sku: v.sku || undefined,
+        image: v.image?.url || images[0],
+        ...Object.fromEntries((v.selectedOptions || []).filter((o) => varies[o.name.toLowerCase()]).map((o) => [varies[o.name.toLowerCase()].split('/').pop(), o.value])),
+        offers: offer(v),
+      })),
+    });
+  }
+  const jsonLd = (p, opts) => (p ? `<script type="application/ld+json">${safeJson(jsonLdData(p, opts))}</script>` : '');
+
+  function slim(p) {
+    return {
+      ...p,
+      description: '', descriptionHtml: '',
+      images: { nodes: (p.images?.nodes || []).slice(0, 1) },
+      variants: { nodes: (p.variants?.nodes || []).map((v) => ({ ...v, image: null })) },
+    };
+  }
+
+  return {
+    config: conf,
+    query: q,
+    getProduct,
+    getProducts,
+    allProducts,
+    getCollection,
+    allCollections,
+    getRecommendations,
+    hydrate,
+    formatMoney: (money, locale = conf.locale) => formatMoney(money, locale),
+    formatPercent: (n, locale = conf.locale) => formatPercent(n, locale),
+    imageUrl,
+    jsonLd,
+    jsonLdData,
+    initialState: (product, opts = {}) => initialState(product, { defaultPurchase: conf.defaultPurchase, lowStock: conf.lowStock, ...opts }),
+    productUrl: (handle, opts = {}) => productUrl(handle, { productPath: conf.productPath, ...opts }),
+    plans,
+  };
+}

package/src/status.js

@@ -11,8 +11,8 @@ import { attr, sel, get, scoped, show } from './dom.js';
  *   "url:path"            the last segment of the page path (/shop/coffee-box -> coffee-box)
  * Returns { key, fromUrl, raw }. key is null when the URL has no value.
  */
-export function resolveProductKey(el, location = window.location) {
-  const raw = (get(el, 'product') || '').trim();
+export function resolveProductKey(el, location = window.location, name = 'product') {
+  const raw = (get(el, name) || '').trim();
   if (!raw.toLowerCase().startsWith('url:')) return { key: raw || null, fromUrl: false, raw };
   const what = raw.slice(4).trim();
   let key = null;
@@ -53,12 +53,7 @@ export function setScopeStatus(root, status, err) {
   scoped(root, sel('show'), boundary()).forEach((el) => {
     const k = get(el, 'show');
     if (!STATUS_KEYS.includes(k)) return;
-    const visible = k === status;
-    show(el, visible);
-    // Blocks hidden by a Webflow class (display: none) still need to appear.
-    if (visible && typeof getComputedStyle === 'function' && getComputedStyle(el).display === 'none') {
-      el.style.display = el.getAttribute(attr('display')) || 'block';
-    }
+    show(el, k === status);
   });
 
   if (status === 'error' || notFound) {

package/types/astro.d.ts

@@ -0,0 +1,15 @@
+import type { TetherConfig } from './index.js';
+
+type Serializable<T> = { [K in keyof T as T[K] extends ((...args: any[]) => any) | null | undefined ? (Exclude<T[K], null | undefined> extends (...args: any[]) => any ? never : K) : K]: T[K] };
+
+export interface TetherAstroOptions extends Partial<Serializable<TetherConfig>> {
+  /** Add the Tether script to every page (default true). False: import and init it yourself. */
+  inject?: boolean;
+}
+
+/**
+ * Astro integration: Tether on every page, store and token from .env
+ * (PUBLIC_SHOPIFY_DOMAIN, PUBLIC_SHOPIFY_STOREFRONT_TOKEN). Functions (onError, hooks) go in
+ * window.TETHER_CONFIG in your layout.
+ */
+export default function tether(options?: TetherAstroOptions): { name: string; hooks: Record<string, (...args: any[]) => unknown> };