@occluze/tether 0.6.6 → 0.6.8

package/src/extras.js

@@ -1,63 +1,145 @@
 /**
- * Optional part with features that load when first needed: bundles (on the first "add set"
- * click), tab sync (on the first change in another tab) and shareable variant links (on the
- * first variant change, with variantUrl or tether-variant-url).
+ * Optional part with features that load when first needed: bundles (on the first "add set" click), tab sync (on the
+ * first change in another tab) and shareable variant links (on the first variant change, with `variantUrl` or
+ * `tether-variant-url`).
  */
 import { cfg, warn, reportError } from './config.js';
 import { sel, get, has, qsa, emit, parseJSONAttr, toAttributes } from './dom.js';
 import { scopes } from './product.js';
 import { Cart } from './cart.js';
+/** @import { ShopifyCart } from './cart/store.js' */
 
+/** @typedef {{ country: string, language: string | null, locale: string | undefined }} StoredMarket */
 /**
- * [tether-group] + [tether-group-add]: adds every product scope inside the group in one request.
- * Bundles, build-a-box, "complete the set". Lines get attribute _group (and tether-line-attributes).
+ * @typedef {(country: string, options: { language: string | null, locale: string | undefined, remember: boolean })
+ *   => Promise<unknown>} SetCountry
  */
-export async function addGroup(btn) {
-  const group = btn.closest(sel('group'));
+
+/**
+ * @param {Element} group
+ * @param {string | null} name The group's `tether-group` value.
+ */
+function groupAttributes(group, name) {
+  const extra = toAttributes(
+    /** @type {Parameters<typeof toAttributes>[0]} */ (parseJSONAttr(group, 'line-attributes')),
+  );
+  return name ? [{ key: '_group', value: name }, ...extra] : extra;
+}
+
+/**
+ * `[tether-group]` with `[tether-group-add]`: adds every product scope inside the group in one request, for bundles,
+ * build-a-box and "complete the set". The lines get the attribute `_group` and the group's `tether-line-attributes`.
+ *
+ * @param {Element} button
+ * @returns {Promise<ShopifyCart | null>} The cart, `null` with nothing to add or after a reported failure.
+ */
+export async function addGroup(button) {
+  const group = button.closest(sel('group'));
   if (!group) return null;
   const name = get(group, 'group');
-  const extra = toAttributes(parseJSONAttr(group, 'line-attributes'));
-  const groupAttrs = name ? [{ key: '_group', value: name }, ...extra] : extra;
-  const lines = qsa(group, sel('product'))
-    .map((el) => scopes.get(el))
-    .filter((s) => s && s.variant?.availableForSale && s.quantity > 0)
-    .map((s) => {
-      const l = s.getLine();
-      l.attributes = [...(l.attributes || []), ...groupAttrs];
-      return l;
-    });
-  if (!lines.length) { warn('group-add: nothing selected'); return null; }
+  const attributes = groupAttributes(group, name);
+  const lines = qsa(group, sel('product')).flatMap((el) => {
+    const scope = scopes.get(el);
+    if (!scope?.variant?.availableForSale || scope.quantity <= 0) return [];
+    const line = scope.getLine();
+    return line ? [{ ...line, attributes: [...(line.attributes ?? []), ...attributes] }] : [];
+  });
+  if (!lines.length) {
+    warn('group-add: nothing selected');
+    return null;
+  }
   try {
     const cart = await Cart.add(lines);
     emit('group-added', { group: name, lines }, group);
     return cart;
-  } catch (err) { reportError(err, 'group add'); return null; }
+  } catch (error) {
+    reportError(error, 'group add');
+    return null;
+  }
 }
 
-/** Another tab changed the cart (reload it here) or the visitor's market (follow it). */
-export function onStorage(e) {
-  if (e.key === cfg.storageKey || e.key === `${cfg.storageKey}:seen`) Cart.init();
-  else if (e.key === `${cfg.prefix}:market:${cfg.domain}` && e.newValue) {
-    try {
-      const m = JSON.parse(e.newValue);
-      if (m?.country) window.Tether?.setCountry(m.country, { language: m.language ?? null, locale: m.locale, remember: false }).catch(() => {});
-    } catch { /* ignore */ }
+/**
+ * Another tab writes the market as JSON; a value that isn't (written by something else under the key) is skipped.
+ *
+ * @param {string} text
+ * @returns {StoredMarket | null}
+ */
+function parseStoredMarket(text) {
+  /** @type {unknown} */
+  let value;
+  try {
+    value = JSON.parse(text);
+  } catch {
+    return null;
   }
+  if (typeof value !== 'object' || value === null) return null;
+  const { country, language, locale } = /** @type {Record<string, unknown>} */ (value);
+  if (typeof country !== 'string' || !country) return null;
+  return {
+    country,
+    language: typeof language === 'string' ? language : null,
+    locale: typeof locale === 'string' ? locale : undefined,
+  };
 }
 
-const urlKeys = new WeakMap(); // scope root -> last variant|plan, so the first render doesn't write
+/**
+ * Another tab changed the cart (it is loaded again here) or the visitor's market (this tab follows it).
+ *
+ * @param {StorageEvent} event
+ */
+export function onStorage(event) {
+  if (event.key === cfg.storageKey || event.key === `${cfg.storageKey}:seen`) {
+    Cart.init().catch((/** @type {unknown} */ error) => {
+      reportError(error, 'cart from another tab');
+    });
+    return;
+  }
+  if (event.key !== `${cfg.prefix}:market:${cfg.domain}` || !event.newValue) return;
+  const market = parseStoredMarket(event.newValue);
+  const { Tether } = /** @type {Window & { Tether?: { setCountry: SetCountry } }} */ (window);
+  if (!market || !Tether) return;
+  const options = { language: market.language, locale: market.locale, remember: false };
+  Tether.setCountry(market.country, options).catch((/** @type {unknown} */ error) => {
+    reportError(error, 'market from another tab');
+  });
+}
+
+/** @type {WeakMap<Element, string>} Scope root → its last variant and plan, so the first render doesn't write. */
+const urlKeys = new WeakMap();
+
+/** @param {string} gid */
+const numericId = (gid) => gid.split('/').pop() ?? gid;
+
+/**
+ * Safari throws a SecurityError past 100 history changes in 10 seconds; the address then keeps the previous choice
+ * until the next one.
+ *
+ * @param {URL} url
+ */
+function replaceUrlIfAllowed(url) {
+  try {
+    window.history.replaceState(window.history.state, '', url);
+  } catch {
+    // Too many changes in a row: see the function's comment.
+  }
+}
 
-/** ?variant= (and selling_plan=) follow the visitor's choice. */
+/**
+ * `?variant=` (and `selling_plan=`) follow the visitor's choice.
+ *
+ * @param {Element} root The product scope's root.
+ * @param {{ variant: { id: string }, sellingPlanId: string | null | undefined }} choice
+ */
 export function writeVariantUrl(root, { variant, sellingPlanId }) {
-  const key = `${variant.id}|${sellingPlanId || ''}`;
+  const key = `${variant.id}|${sellingPlanId ?? ''}`;
   const before = urlKeys.get(root);
   urlKeys.set(root, key);
   if (!before || before === key) return;
-  if (!has(root, 'variant-url') && !(cfg.variantUrl && document.querySelector(sel('product')) === root)) return;
-  try {
-    const u = new URL(window.location.href);
-    u.searchParams.set('variant', variant.id.split('/').pop());
-    if (sellingPlanId) u.searchParams.set('selling_plan', sellingPlanId.split('/').pop()); else u.searchParams.delete('selling_plan');
-    window.history.replaceState(window.history.state, '', u);
-  } catch { /* ignore */ }
+  const isMainProduct = cfg.variantUrl && document.querySelector(sel('product')) === root;
+  if (!has(root, 'variant-url') && !isMainProduct) return;
+  const url = new URL(window.location.href);
+  url.searchParams.set('variant', numericId(variant.id));
+  if (sellingPlanId) url.searchParams.set('selling_plan', numericId(sellingPlanId));
+  else url.searchParams.delete('selling_plan');
+  replaceUrlIfAllowed(url);
 }

package/src/fragments.js

@@ -1,27 +1,115 @@
 /**
- * GraphQL fragments. Built at call time because counts and metafields come
- * from config. Operations put these AFTER the operation (see withContext).
+ * The GraphQL fragments of what Tether renders. They are built at call time because the list sizes and metafields come
+ * from the config; the browser passes its validated `cfg`, the server helpers their own. Operations put these after
+ * the operation, where `withContext` expects them.
+ */
+import { cfg, toMetafieldIdentifier } from './config.js';
+/** @import { TetherConfig, MetafieldIdentifier } from './config.js' */
+/** @import { Money } from './shopify-values.js' */
+
+/** @typedef {{ url: string, altText: string | null, width: number | null, height: number | null }} Image */
+/**
+ * @typedef {{ __typename: 'SellingPlanPercentagePriceAdjustment', adjustmentPercentage: number }
+ *   | { __typename: 'SellingPlanFixedAmountPriceAdjustment', adjustmentAmount: Money }
+ *   | { __typename: 'SellingPlanFixedPriceAdjustment', price: Money }} SellingPlanAdjustmentValue
+ */
+/**
+ * @typedef {object} SellingPlan
+ * @property {string} id
+ * @property {string} name
+ * @property {string | null} description
+ * @property {boolean} recurringDeliveries
+ * @property {{ name: string, value: string }[]} options
+ * @property {{ orderCount: number | null, adjustmentValue: SellingPlanAdjustmentValue }[]} priceAdjustments
+ */
+/**
+ * @typedef {object} SellingPlanGroup
+ * @property {string} name
+ * @property {string | null} appName
+ * @property {{ name: string, values: string[] }[]} options
+ * @property {{ nodes: SellingPlan[] }} sellingPlans
+ */
+/**
+ * @typedef {object} SellingPlanAllocation A variant's price on one plan.
+ * @property {{ id: string }} sellingPlan
+ * @property {Money} checkoutChargeAmount What the customer pays at checkout (more for a prepaid plan).
+ * @property {Money} remainingBalanceChargeAmount
+ * @property {{ price: Money, compareAtPrice: Money, perDeliveryPrice: Money, unitPrice: Money | null }[]}
+ *   priceAdjustments
+ */
+/**
+ * @typedef {object} ProductVariant
+ * @property {string} id
+ * @property {string} title
+ * @property {boolean} availableForSale
+ * @property {boolean} currentlyNotInStock
+ * @property {number | null} [quantityAvailable] Absent when the store's token can't read inventory.
+ * @property {string | null} sku
+ * @property {string | null} barcode
+ * @property {{ name: string, value: string }[]} selectedOptions
+ * @property {Image | null} image
+ * @property {Money} price
+ * @property {Money | null} compareAtPrice
+ * @property {Money | null} unitPrice
+ * @property {{ nodes: SellingPlanAllocation[] }} sellingPlanAllocations
+ */
+/**
+ * @typedef {object} Metafield
+ * @property {string} namespace
+ * @property {string} key
+ * @property {string} type
+ * @property {string} value
+ * @property {{ image?: Image } | null} reference A file reference's image.
+ */
+/**
+ * @typedef {object} Product The fields of `fragment TetherProduct`.
+ * @property {string} id
+ * @property {string} handle
+ * @property {string} title
+ * @property {string} description
+ * @property {string} descriptionHtml
+ * @property {string} productType
+ * @property {string} vendor
+ * @property {string[]} tags
+ * @property {boolean} availableForSale
+ * @property {string | null} publishedAt
+ * @property {string | null} onlineStoreUrl
+ * @property {boolean} requiresSellingPlan
+ * @property {{ title: string | null, description: string | null }} seo
+ * @property {Image | null} featuredImage
+ * @property {{ nodes: Image[] }} images
+ * @property {{ name: string, optionValues: { name: string, swatch: unknown }[] }[]} options
+ * @property {{ minVariantPrice: Money, maxVariantPrice: Money }} priceRange
+ * @property {{ minVariantPrice: Money, maxVariantPrice: Money }} compareAtPriceRange
+ * @property {(Metafield | null)[]} [metafields] Present when metafields are configured; `null` for one that isn't set.
+ * @property {{ nodes: SellingPlanGroup[] }} sellingPlanGroups
+ * @property {{ nodes: ProductVariant[] }} variants
+ */
+
+/**
+ * @typedef {Pick<TetherConfig, 'imagesFirst' | 'variantsFirst' | 'sellingPlanGroupsFirst' | 'sellingPlansFirst'
+ *   | 'metafields'>} ProductFragmentConfig
  */
-import { cfg } from './config.js';
 
 const MONEY = 'amount currencyCode';
 const IMAGE = 'url altText width height';
 
-export function metafieldIdentifiers(o = cfg) {
-  return (o.metafields || []).map((m) => {
-    if (typeof m === 'string') {
-      const i = m.indexOf('.');
-      return { namespace: m.slice(0, i), key: m.slice(i + 1) };
-    }
-    return m;
-  }).filter((m) => m.namespace && m.key);
-}
-
-function metafieldsField(o = cfg) {
-  const ids = metafieldIdentifiers(o);
-  if (!ids.length) return '';
-  const list = ids
-    .map((m) => `{namespace: ${JSON.stringify(m.namespace)}, key: ${JSON.stringify(m.key)}}`)
+/**
+ * The `metafields(identifiers:)` field. A fragment can't declare variables, so the identifiers are written into the
+ * text: only valid ones (`toMetafieldIdentifier`), each quoted as a string literal.
+ *
+ * @param {ProductFragmentConfig['metafields']} metafields
+ */
+function metafieldsField(metafields) {
+  /** @type {MetafieldIdentifier[]} */
+  const identifiers = [];
+  for (const ref of metafields) {
+    const identifier = toMetafieldIdentifier(ref);
+    if (identifier) identifiers.push(identifier);
+  }
+  if (!identifiers.length) return '';
+  const list = identifiers
+    .map(({ namespace, key }) => `{namespace: ${JSON.stringify(namespace)}, key: ${JSON.stringify(key)}}`)
     .join(', ');
   return `metafields(identifiers: [${list}]) {
     namespace key type value
@@ -29,7 +117,7 @@ function metafieldsField(o = cfg) {
   }`;
 }
 
-export const SELLING_PLAN_FIELDS = `
+const SELLING_PLAN_FIELDS = `
   id name description recurringDeliveries
   options { name value }
   priceAdjustments {
@@ -42,7 +130,7 @@ export const SELLING_PLAN_FIELDS = `
     }
   }`;
 
-export const ALLOCATION_FIELDS = `
+const ALLOCATION_FIELDS = `
   sellingPlan { id }
   checkoutChargeAmount { ${MONEY} }
   remainingBalanceChargeAmount { ${MONEY} }
@@ -53,7 +141,10 @@ export const ALLOCATION_FIELDS = `
     unitPrice { ${MONEY} }
   }`;
 
-/** The product fields Tether renders. `o` = config (counts, metafields); the server module passes its own. */
+/**
+ * @param {ProductFragmentConfig} [o] The list sizes and metafields.
+ * @returns {string} `fragment TetherProduct on Product`.
+ */
 export function productFragment(o = cfg) {
   return `
 fragment TetherProduct on Product {
@@ -65,7 +156,7 @@ fragment TetherProduct on Product {
   options { name optionValues { name swatch { color image { previewImage { ${IMAGE} } } } } }
   priceRange { minVariantPrice { ${MONEY} } maxVariantPrice { ${MONEY} } }
   compareAtPriceRange { minVariantPrice { ${MONEY} } maxVariantPrice { ${MONEY} } }
-  ${metafieldsField(o)}
+  ${metafieldsField(o.metafields)}
   sellingPlanGroups(first: ${o.sellingPlanGroupsFirst}) {
     nodes {
       name appName
@@ -87,6 +178,7 @@ fragment TetherProduct on Product {
 }`;
 }
 
+/** @returns {string} `fragment TetherCart on Cart`. */
 export function cartFragment() {
   return `
 fragment TetherCart on Cart {
@@ -136,6 +228,7 @@ fragment TetherCart on Cart {
 }`;
 }
 
+/** @returns {string} The collection fields Tether renders, for inside a `collection { }` selection. */
 export function collectionFields() {
   return `
   id handle title description descriptionHtml

package/src/images.js

@@ -0,0 +1,104 @@
+/**
+ * Shopify images on the page: sized through the CDN's URL parameters, written to an `<img>` or as a CSS background,
+ * and never downloaded twice when the server already rendered the same image.
+ */
+import { attr } from './markup.js';
+
+/**
+ * @typedef {object} ImageSize Shopify CDN parameters.
+ * @property {string | number | null} [width]
+ * @property {string | number | null} [height]
+ * @property {string | null} [crop] `center`, `top`, `bottom`, `left` or `right`; only applies with a width or height.
+ */
+
+/**
+ * Shopify CDN image at a size: `imageUrl(url, { width: 800 })`. Use the same width as the element's max-width
+ * attribute, so the browser script keeps the image instead of loading it again.
+ *
+ * @template {string | null | undefined} Url
+ * @param {Url} url
+ * @param {ImageSize} [size]
+ * @returns {Url} The sized URL; `url` itself when it is empty or not absolute.
+ */
+export function imageUrl(url, { width, height, crop } = {}) {
+  if (!url) return url;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (error) {
+    // A relative or malformed URL has no CDN parameters to set: it is used as written.
+    if (error instanceof TypeError) return url;
+    throw error;
+  }
+  if (width) parsed.searchParams.set('width', String(width));
+  if (height) parsed.searchParams.set('height', String(height));
+  if (crop) parsed.searchParams.set('crop', crop);
+  return /** @type {Url} */ (parsed.toString());
+}
+
+/**
+ * @param {Element} el
+ * @param {string} name
+ * @returns {string | null} `name` as Webflow's custom attribute, or in valid HTML as `<prefix>-name` / `data-name`.
+ */
+function sizeAttribute(el, name) {
+  return el.getAttribute(name) ?? el.getAttribute(attr(name)) ?? el.getAttribute(`data-${name}`);
+}
+
+/**
+ * @template {string | null | undefined} Url
+ * @param {Url} url
+ * @param {Element | null | undefined} el The element whose max-width / max-height / crop attributes size the image.
+ * @returns {Url}
+ */
+export function cdnUrl(url, el) {
+  if (!url || !el) return url;
+  const width = sizeAttribute(el, 'max-width');
+  const height = sizeAttribute(el, 'max-height');
+  return imageUrl(url, { width, height, crop: width || height ? sizeAttribute(el, 'crop') : null });
+}
+
+/**
+ * @param {string | null | undefined} a
+ * @param {string | null | undefined} b
+ * @returns {boolean} True for the same image at any size parameters: the server-rendered one is kept.
+ */
+export const sameImage = (a, b) => Boolean(a && b) && a?.split('?')[0] === b?.split('?')[0];
+
+/**
+ * A CSS `url()` for an image URL from Shopify. Characters that would end the string are escaped, so the URL can't
+ * add declarations; only http(s), relative and data:image URLs are used.
+ *
+ * @param {string} url
+ */
+function cssUrl(url) {
+  const hasScheme = /^\s*[a-z][a-z0-9+.-]*:/i.test(url);
+  if (hasScheme && !/^\s*(https?:|data:image\/)/i.test(url)) return 'none';
+  const escaped = url.replace(/["\\\n\r\f]/g, (char) => `\\${char.charCodeAt(0).toString(16)} `);
+  return `url("${escaped}")`;
+}
+
+/**
+ * Shows `url` in `el`: as the `src` of an `<img>` (lazy unless it says otherwise), else as its background image.
+ *
+ * @param {HTMLElement} el
+ * @param {string | null | undefined} url
+ * @param {string | null} [alt]
+ */
+export function setImage(el, url, alt) {
+  if (!url) return;
+  const src = cdnUrl(url, el);
+  if (el.tagName !== 'IMG') {
+    el.style.backgroundImage = cssUrl(src);
+    return;
+  }
+  if (sameImage(el.getAttribute('src'), src)) {
+    if (alt != null && !el.getAttribute('alt')) el.setAttribute('alt', alt);
+    return;
+  }
+  el.removeAttribute('srcset');
+  el.removeAttribute('sizes');
+  el.setAttribute('src', src);
+  if (alt != null) el.setAttribute('alt', alt);
+  if (!el.getAttribute('loading')) el.setAttribute('loading', 'lazy');
+}