@occluze/tether 0.6.6 → 0.6.8

package/src/presets/barba.js

@@ -1,6 +1,6 @@
 /**
- * Preset for sites with page transitions (Barba, Swup, …), smooth scroll (Lenis)
- * and GSAP. Nothing is read from globals: pass in what your site has.
+ * Preset for sites with page transitions (Barba, Swup), smooth scroll (Lenis) and GSAP. Nothing is read from globals
+ * except GSAP and ScrollTrigger by default: pass in what your site has.
  *
  *   import Tether from "@occluze/tether";
  *   import { barbaPreset } from "@occluze/tether/presets/barba";
@@ -20,76 +20,166 @@
  *   // when leaving a page:
  *   Tether.unmount();
  */
+/** @import { TetherConfig } from '../config.js' */
 
-const LINE_DURATION = 0.3;
+/**
+ * GSAP isn't a dependency, so the two calls this preset makes are described here.
+ *
+ * @typedef {Record<string, string | number | (() => void)>} TweenVars
+ * @typedef {object} Gsap
+ * @property {(target: HTMLElement, from: TweenVars, to: TweenVars) => unknown} fromTo
+ * @property {(target: HTMLElement, to: TweenVars) => unknown} to
+ */
+
+/**
+ * @typedef {object} BarbaPresetOptions Each getter may also be the value itself.
+ * @property {() => unknown} [gsap] Default `window.gsap`.
+ * @property {(() => unknown) | null} [lenis] Resized after async renders.
+ * @property {() => unknown} [scrollTrigger] Default `window.ScrollTrigger`, refreshed after async renders.
+ * @property {((drawer: HTMLElement) => void) | null} [lockScroll] When the cart opens.
+ * @property {(() => void) | null} [unlockScroll] When the cart closes.
+ * @property {(() => void) | null} [onResize] After a cart line animated in or out.
+ * @property {((el: HTMLElement, previousText: string) => void) | null} [onValueChange]
+ * @property {boolean} [animateLines] Animate cart lines in and out (default true).
+ * @property {number} [lineDuration] Seconds.
+ */
+
+/**
+ * @typedef {Pick<TetherConfig, 'autoMount' | 'onLayoutChange' | 'onCartOpen' | 'onCartClose' | 'onLineEnter'
+ *   | 'onLineLeave' | 'onValueChange'>} BarbaPresetConfig
+ */
+
+const LINE_DURATION_SECONDS = 0.3;
+/** @returns {TweenVars} A new object each time: GSAP writes into the vars it is given. */
+const collapsed = () => ({
+  height: 0,
+  paddingTop: 0,
+  paddingBottom: 0,
+  borderBottomWidth: 0,
+  opacity: 0,
+  overflow: 'hidden',
+});
+const ANIMATED_PROPS = 'height,paddingTop,paddingBottom,borderBottomWidth,opacity,overflow';
 
 const reducedMotion = () =>
   typeof window.matchMedia === 'function' && window.matchMedia('(prefers-reduced-motion: reduce)').matches;
 
+/**
+ * @param {unknown} option
+ * @returns {unknown} What a getter option returns, or the option itself when it is the value.
+ */
+function current(option) {
+  if (typeof option !== 'function') return option;
+  // Every function option of this preset is a getter that takes no arguments.
+  const getter = /** @type {() => unknown} */ (option);
+  return getter();
+}
+
+/**
+ * Calls `target[method]()` when it has one: Lenis and ScrollTrigger are optional and versions differ.
+ *
+ * @param {unknown} target
+ * @param {string} method
+ */
+function callIfPresent(target, method) {
+  if (typeof target !== 'object' || target === null) return;
+  /** @type {unknown} */
+  const fn = Reflect.get(target, method);
+  // A method of `target`, called on it.
+  if (typeof fn === 'function') /** @type {(this: unknown) => unknown} */ (fn).call(target);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Gsap}
+ */
+const isGsap = (value) =>
+  typeof value === 'object' &&
+  value !== null &&
+  typeof Reflect.get(value, 'fromTo') === 'function' &&
+  typeof Reflect.get(value, 'to') === 'function';
+
+/**
+ * Hooks for sites with page transitions, smooth scroll and GSAP: spread into `Tether.init()`.
+ *
+ * @param {BarbaPresetOptions} [options]
+ * @returns {BarbaPresetConfig}
+ */
 export function barbaPreset(options = {}) {
   const {
-    gsap = () => window.gsap,
+    gsap = () => /** @type {unknown} */ (Reflect.get(window, 'gsap')),
     lenis = null,
-    scrollTrigger = () => window.ScrollTrigger,
+    scrollTrigger = () => /** @type {unknown} */ (Reflect.get(window, 'ScrollTrigger')),
     lockScroll = null,
     unlockScroll = null,
     onResize = null,
     onValueChange = null,
     animateLines = true,
-    lineDuration = LINE_DURATION,
+    lineDuration = LINE_DURATION_SECONDS,
   } = options;
 
-  const get = (v) => (typeof v === 'function' ? v() : v);
+  /** Whether this preset holds the scroll lock, so a modal's own lock stays intact. */
   let locked = false;
 
-  const canAnimate = (node) => animateLines && get(gsap) && !reducedMotion() && node.offsetHeight > 0;
+  /**
+   * @param {HTMLElement} node
+   * @returns {Gsap | null} GSAP, when this line should animate.
+   */
+  const animator = (node) => {
+    if (!animateLines || reducedMotion() || node.offsetHeight <= 0) return null;
+    const animation = current(gsap);
+    return isGsap(animation) ? animation : null;
+  };
 
   return {
     autoMount: false,
 
     onLayoutChange() {
-      get(lenis)?.resize?.();
-      get(scrollTrigger)?.refresh?.();
+      callIfPresent(current(lenis), 'resize');
+      callIfPresent(current(scrollTrigger), 'refresh');
     },
 
     onCartOpen(drawers) {
-      if (!locked && typeof lockScroll === 'function' && drawers[0]) {
-        lockScroll(drawers[0]);
-        locked = true;
-      }
+      const drawer = drawers[0];
+      if (locked || typeof lockScroll !== 'function' || !drawer) return;
+      lockScroll(drawer);
+      locked = true;
     },
 
     onCartClose() {
-      // Only release what we locked, so a modal's own lock stays intact.
       if (locked && typeof unlockScroll === 'function') unlockScroll();
       locked = false;
     },
 
     onLineEnter(node) {
-      const g = get(gsap);
-      if (!canAnimate(node)) return;
-      const st = getComputedStyle(node);
-      g.fromTo(node, {
-        height: 0, paddingTop: 0, paddingBottom: 0, borderBottomWidth: 0, opacity: 0, overflow: 'hidden',
-      }, {
+      const animation = animator(node);
+      if (!animation) return;
+      const style = getComputedStyle(node);
+      animation.fromTo(node, collapsed(), {
         height: node.offsetHeight,
-        paddingTop: st.paddingTop,
-        paddingBottom: st.paddingBottom,
-        borderBottomWidth: st.borderBottomWidth,
+        paddingTop: style.paddingTop,
+        paddingBottom: style.paddingBottom,
+        borderBottomWidth: style.borderBottomWidth,
         opacity: 1,
         duration: lineDuration,
-        clearProps: 'height,paddingTop,paddingBottom,borderBottomWidth,opacity,overflow',
+        clearProps: ANIMATED_PROPS,
         onComplete: () => onResize?.(),
       });
     },
 
     onLineLeave(node, done) {
-      const g = get(gsap);
-      if (!canAnimate(node)) { done(); return; }
-      g.to(node, {
-        height: 0, paddingTop: 0, paddingBottom: 0, borderBottomWidth: 0, opacity: 0, overflow: 'hidden',
+      const animation = animator(node);
+      if (!animation) {
+        done();
+        return;
+      }
+      animation.to(node, {
+        ...collapsed(),
         duration: lineDuration,
-        onComplete: () => { done(); onResize?.(); },
+        onComplete: () => {
+          done();
+          onResize?.();
+        },
       });
     },
 

package/src/product-events.js

@@ -0,0 +1,130 @@
+/**
+ * A product scope's clicks and changes: option and plan buttons, purchase toggles, quantity steppers, the selects and
+ * add to cart. One delegated listener of each kind on the root, so cards a list re-renders need no new listeners.
+ */
+import { reportError } from './config.js';
+import { sel, get, emit, setText, busy } from './dom.js';
+import { addButtonLabel } from './variant-render.js';
+/** @import { ProductScope } from './product.js' */
+
+const productSelector = () => sel('product');
+
+/**
+ * @param {Element} el
+ * @returns {el is HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement}
+ */
+const isField = (el) => el.tagName === 'INPUT' || el.tagName === 'SELECT' || el.tagName === 'TEXTAREA';
+
+/**
+ * @param {EventTarget | null} target
+ * @returns {target is Element}
+ */
+const isElement = (target) => target instanceof window.Element;
+
+/**
+ * @param {ProductScope} scope
+ * @param {Element} target
+ * @param {string} selector
+ * @returns {HTMLElement | null} The nearest `selector` around `target` that belongs to the scope, not to a nested one.
+ *   Typed as an HTML element, as `qsa` types its matches.
+ */
+function closestOwn(scope, target, selector) {
+  const el = /** @type {HTMLElement | null} */ (target.closest(selector));
+  return el?.closest(productSelector()) === scope.root ? el : null;
+}
+
+/**
+ * Adds to the cart with `aria-busy` on the button and `tether-adding-text` as its label meanwhile.
+ *
+ * @param {ProductScope} scope
+ * @param {HTMLElement} button
+ */
+function onAddClick(scope, button) {
+  const { label, original } = addButtonLabel(button);
+  const addingText = get(button, 'adding-text');
+  void busy(button, async () => {
+    if (addingText) setText(label, addingText);
+    try {
+      await scope.addToCart();
+    } catch (error) {
+      reportError(error, 'add to cart failed');
+      emit('error', { error, context: 'add-to-cart' }, scope.root);
+    } finally {
+      if (addingText) setText(label, original);
+    }
+  }).then(() => {
+    // The mode-dependent labels (tether-subscribe-text, tether-soldout-text) wait for aria-busy to clear.
+    scope.renderVariant();
+  });
+}
+
+/**
+ * @param {ProductScope} scope
+ * @param {Event} event
+ * @param {Element} target
+ */
+function onClick(scope, event, target) {
+  const optionValue = closestOwn(scope, target, sel('option-value'));
+  const optionList = optionValue?.closest(sel('option-list'));
+  if (optionValue && optionList) {
+    event.preventDefault();
+    scope.select(scope.optName(get(optionList, 'option-list')), get(optionValue, 'option-value') ?? '');
+    return;
+  }
+  const plan = closestOwn(scope, target, sel('plan-value'));
+  if (plan) {
+    event.preventDefault();
+    scope.selectPlan(get(plan, 'plan-value'));
+    return;
+  }
+  const purchase = closestOwn(scope, target, `${sel('purchase')}:not(select)`);
+  if (purchase) {
+    // A radio or checkbox input keeps its own click, so it shows checked.
+    if (purchase.tagName !== 'INPUT') event.preventDefault();
+    scope.setPurchase(get(purchase, 'purchase'));
+    return;
+  }
+  const plus = closestOwn(scope, target, sel('qty-plus'));
+  const minus = plus ? null : closestOwn(scope, target, sel('qty-minus'));
+  if (plus || minus) {
+    event.preventDefault();
+    scope.setQuantity(scope.quantity + (plus ? 1 : -1));
+    return;
+  }
+  const add = closestOwn(scope, target, sel('add-to-cart'));
+  if (add) {
+    event.preventDefault();
+    onAddClick(scope, add);
+  }
+}
+
+/**
+ * @param {ProductScope} scope
+ * @param {Element} target A form field in the scope.
+ */
+function onChange(scope, target) {
+  const value = isField(target) ? target.value : '';
+  if (target.matches(`select${sel('option')}`)) {
+    scope.select(scope.optName(get(target, 'option')), value);
+  } else if (target.matches(`select${sel('variant-select')}`)) {
+    scope.selectVariant(value);
+  } else if (target.matches(`select${sel('plan')}`)) {
+    if (value) scope.selectPlan(value);
+    else scope.setPurchase('one-time');
+  } else if (target.matches(`select${sel('purchase')}`)) {
+    scope.setPurchase(value);
+  } else if (target.matches(sel('qty'))) {
+    scope.setQuantity(value);
+  }
+}
+
+/** @param {ProductScope} scope */
+export function bindProductEvents(scope) {
+  scope.root.addEventListener('click', (event) => {
+    if (isElement(event.target)) onClick(scope, event, event.target);
+  });
+  scope.root.addEventListener('change', (event) => {
+    const { target } = event;
+    if (isElement(target) && target.closest(productSelector()) === scope.root) onChange(scope, target);
+  });
+}

package/src/product-render.js

@@ -0,0 +1,257 @@
+/**
+ * The DOM writes of a product scope that depend on the product alone, once per product: its binds, the option and
+ * plan lists and the options of its selects. `variant-render.js` writes what follows the visitor's choice.
+ */
+import {
+  attr,
+  sel,
+  get,
+  has,
+  qsa,
+  formatMoney,
+  formatDate,
+  setText,
+  setImage,
+  setStoreHtml,
+  show,
+  repeat,
+  hasTemplate,
+  sameImage,
+  productUrl,
+} from './dom.js';
+/** @import { Product, Image } from './fragments.js' */
+/** @import { PlanInGroup } from './selling-plans.js' */
+
+/**
+ * @typedef {object} RenderScope The product scope as its renders see it.
+ * @property {HTMLElement} root
+ * @property {Product} product
+ * @property {PlanInGroup[]} plans
+ * @property {(selector: string) => HTMLElement[]} $ Matches in this scope, the root included.
+ * @property {(authored: string | null) => string} optName The product's option name for one written in the markup.
+ */
+/**
+ * The shape `fragments.js` selects for an option value's swatch, which it types as `unknown`.
+ *
+ * @typedef {{ color: string | null, image: { previewImage: Image | null } | null } | null} Swatch
+ */
+
+/** `tether-bind="image:2"`: the second product image. */
+const NTH_IMAGE_BIND = /^image:(\d+)$/;
+const METAFIELD_BIND = 'metafield:';
+const MULTI_LINE_METAFIELD = /^(rich_text|multi_line_text)_field$/;
+/** `tether-plan-list` values that list every plan, not one group: Webflow's Designer can't always leave it empty. */
+const ALL_PLAN_GROUPS = ['', 'true', 'all', '*'];
+
+/**
+ * @param {Element} el
+ * @returns {el is HTMLSelectElement}
+ */
+export const isSelect = (el) => el.tagName === 'SELECT';
+
+/**
+ * @param {RenderScope} scope
+ * @param {string} selector
+ * @returns {HTMLSelectElement[]} The `<select>` elements in the scope that match `selector`.
+ */
+export const selectsIn = (scope, selector) => scope.$(`select${selector}`).filter(isSelect);
+
+/**
+ * Leaves a server-rendered gallery with the same images as it is.
+ *
+ * @param {HTMLElement} el
+ * @param {Product} product
+ */
+function renderGallery(el, product) {
+  const images = product.images.nodes;
+  const rendered = [...el.children].map((node) => (node.tagName === 'IMG' ? node : node.querySelector('img')));
+  const same =
+    !hasTemplate(el) &&
+    rendered.length === images.length &&
+    rendered.every((img, index) => sameImage(img?.getAttribute('src'), images[index]?.url));
+  if (same) return;
+  repeat(el, images, (node, image) => {
+    const target = node.matches(`img,${sel('bind', 'image')}`) ? node : (qsa(node, 'img')[0] ?? node);
+    setImage(target, image.url, image.altText || product.title);
+  });
+}
+
+/**
+ * @param {HTMLElement} el
+ * @param {Product} product
+ * @param {string} ref `namespace.key`
+ */
+function renderMetafield(el, product, ref) {
+  const dot = ref.indexOf('.');
+  const namespace = ref.slice(0, dot);
+  const key = ref.slice(dot + 1);
+  const metafield = (product.metafields ?? []).find((field) => field?.namespace === namespace && field.key === key);
+  if (!metafield) {
+    setText(el, '');
+    return;
+  }
+  const image = metafield.reference?.image;
+  if (image) {
+    setImage(el, image.url, image.altText);
+    return;
+  }
+  if (MULTI_LINE_METAFIELD.test(metafield.type)) el.style.whiteSpace = 'pre-line';
+  setText(el, metafield.value);
+}
+
+/** @type {Map<string, (product: Product) => string>} The product binds written as text. */
+const PRODUCT_TEXTS = new Map(
+  Object.entries({
+    title: (product) => product.title,
+    'description-text': (product) => product.description,
+    vendor: (product) => product.vendor,
+    type: (product) => product.productType,
+    handle: (product) => product.handle,
+    'published-at': (product) => formatDate(product.publishedAt),
+    'min-price': (product) => formatMoney(product.priceRange.minVariantPrice),
+    'max-price': (product) => formatMoney(product.priceRange.maxVariantPrice),
+  }),
+);
+
+/**
+ * @param {HTMLElement} el
+ * @param {Product} product
+ */
+function renderTags(el, product) {
+  const exclude = (el.getAttribute('exclude') ?? '')
+    .split(',')
+    .map((tag) => tag.trim())
+    .filter(Boolean);
+  const tags = product.tags.filter((tag) => !exclude.includes(tag));
+  repeat(el, tags, (node, tag) => {
+    setText(node, tag);
+  });
+}
+
+/**
+ * A `tether-bind` of the product itself; binds of the variant are left to `writeVariant`.
+ *
+ * @param {HTMLElement} el
+ * @param {string} key
+ * @param {Product} product
+ */
+function renderProductBind(el, key, product) {
+  const text = PRODUCT_TEXTS.get(key);
+  if (text) {
+    setText(el, text(product));
+    return;
+  }
+  switch (key) {
+    case 'description':
+      setStoreHtml(el, product.descriptionHtml);
+      break;
+    case 'featured-image':
+      setImage(el, product.featuredImage?.url, product.featuredImage?.altText || product.title);
+      break;
+    case 'url':
+    case 'link':
+      el.setAttribute('href', productUrl(product.handle, product.id));
+      if (key === 'url' && !el.firstElementChild && !el.textContent.trim()) setText(el, product.title);
+      break;
+    case 'images':
+      renderGallery(el, product);
+      break;
+    case 'tags':
+      renderTags(el, product);
+      break;
+    default:
+      renderIndexedBind(el, key, product);
+  }
+}
+
+/**
+ * `image:<n>` (falling back to the featured image) and `metafield:<namespace.key>`.
+ *
+ * @param {HTMLElement} el
+ * @param {string} key
+ * @param {Product} product
+ */
+function renderIndexedBind(el, key, product) {
+  const nth = NTH_IMAGE_BIND.exec(key);
+  if (nth) {
+    const image = product.images.nodes[Number(nth[1]) - 1] ?? product.featuredImage;
+    setImage(el, image?.url, image?.altText || product.title);
+  } else if (key.startsWith(METAFIELD_BIND)) {
+    renderMetafield(el, product, key.slice(METAFIELD_BIND.length));
+  }
+}
+
+/** @param {RenderScope} scope */
+function renderOptionLists(scope) {
+  const { product } = scope;
+  scope.$(sel('option-list')).forEach((container) => {
+    const name = scope.optName(get(container, 'option-list'));
+    const option = product.options.find((candidate) => candidate.name === name);
+    if (!option || (option.optionValues.length <= 1 && has(container, 'hide-single'))) {
+      show(container, false);
+      return;
+    }
+    repeat(container, option.optionValues, (node, value) => {
+      node.setAttribute(attr('option-value'), value.name);
+      const text = qsa(node, sel('bind', 'option-value'))[0];
+      if (text) setText(text, value.name);
+      else if (!node.firstElementChild) setText(node, value.name);
+      const swatchEl = qsa(node, sel('bind', 'swatch'))[0];
+      // fragments.js selects `swatch { color image { previewImage { … } } }`.
+      const swatch = /** @type {Swatch} */ (value.swatch);
+      if (!swatchEl || !swatch) return;
+      if (swatch.color) swatchEl.style.backgroundColor = swatch.color;
+      if (swatch.image?.previewImage) setImage(swatchEl, swatch.image.previewImage.url, value.name);
+    });
+  });
+}
+
+/** @param {RenderScope} scope */
+function renderSelects(scope) {
+  const { product } = scope;
+  selectsIn(scope, sel('option')).forEach((select) => {
+    const option = product.options.find((candidate) => candidate.name === scope.optName(get(select, 'option')));
+    if (!option) {
+      show(select, false);
+      return;
+    }
+    select.replaceChildren(...option.optionValues.map((value) => new Option(value.name, value.name)));
+  });
+  selectsIn(scope, sel('variant-select')).forEach((select) => {
+    select.replaceChildren(...product.variants.nodes.map((variant) => new Option(variant.title, variant.id)));
+  });
+  selectsIn(scope, sel('plan')).forEach((select) => {
+    const plans = scope.plans.map((plan) => new Option(plan.name, plan.id));
+    const oneTime = !product.requiresSellingPlan && get(select, 'plan') !== 'subscription-only';
+    const oneTimeLabel = select.getAttribute(attr('one-time-label')) || 'One-time purchase';
+    select.replaceChildren(...(oneTime ? [new Option(oneTimeLabel, '')] : []), ...plans);
+  });
+}
+
+/** @param {RenderScope} scope */
+function renderPlanLists(scope) {
+  scope.$(sel('plan-list')).forEach((container) => {
+    // The value is a selling plan group's name, or one of ALL_PLAN_GROUPS.
+    const raw = (get(container, 'plan-list') ?? '').trim();
+    const group = ALL_PLAN_GROUPS.includes(raw.toLowerCase()) ? null : raw;
+    const plans = scope.plans.filter((plan) => !group || plan.group.name === group);
+    repeat(container, plans, (node, plan) => {
+      node.setAttribute(attr('plan-value'), plan.id);
+      if (!node.firstElementChild && !node.querySelector(sel('plan-bind'))) setText(node, plan.name);
+    });
+  });
+}
+
+/**
+ * Writes what depends on the product alone: its binds, option and plan lists and the selects' options.
+ *
+ * @param {RenderScope} scope
+ */
+export function writeProduct(scope) {
+  scope.$(sel('bind')).forEach((el) => {
+    renderProductBind(el, get(el, 'bind') ?? '', scope.product);
+  });
+  renderOptionLists(scope);
+  renderSelects(scope);
+  renderPlanLists(scope);
+}