@occluze/tether 0.6.8 → 0.7.0

package/src/presets/barba.ts

@@ -0,0 +1,194 @@
+/**
+ * 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";
+ *
+ *   Tether.init({
+ *     ...window.TETHER_CONFIG,
+ *     ...barbaPreset({
+ *       lenis: () => myLenis,                      // resized after async renders
+ *       lockScroll: (drawer) => myLock.lock(drawer),  // when the cart opens
+ *       unlockScroll: () => myLock.unlock(),       // when the cart closes
+ *       onValueChange: (el, previous) => {},       // e.g. a text scramble
+ *     }),
+ *   });
+ *
+ *   // once per page container, e.g. in Barba's beforeEnter AND once():
+ *   Tether.mount(container);
+ *   // when leaving a page:
+ *   Tether.unmount();
+ */
+import type { TetherConfig } from '../config.ts';
+
+// GSAP isn't a dependency, so the two calls this preset makes are described here.
+type TweenVars = Record<string, string | number | (() => void)>;
+interface Gsap {
+  fromTo: (target: HTMLElement, from: TweenVars, to: TweenVars) => unknown;
+  to: (target: HTMLElement, to: TweenVars) => unknown;
+}
+
+/** `gsap`, `lenis` and `scrollTrigger` are getters, read each time they are used, so an instance made later is found. */
+interface BarbaPresetOptions {
+  /** Default `window.gsap`. */
+  gsap?: () => unknown;
+  /** Resized after async renders. */
+  lenis?: (() => unknown) | null;
+  /** Default `window.ScrollTrigger`, refreshed after async renders. */
+  scrollTrigger?: () => unknown;
+  /** When the cart opens. */
+  lockScroll?: ((drawer: HTMLElement) => void) | null;
+  /** When the cart closes. */
+  unlockScroll?: (() => void) | null;
+  /** After a cart line animated in or out. */
+  onResize?: (() => void) | null;
+  onValueChange?: TetherConfig['onValueChange'];
+  /** Animate cart lines in and out (default true). */
+  animateLines?: boolean;
+  /** Seconds. */
+  lineDuration?: number;
+}
+
+/** The hooks the preset always sets, and `onValueChange` as passed (`null` when it isn't). */
+type BarbaPresetConfig = { autoMount: false } & {
+  [Hook in 'onLayoutChange' | 'onCartOpen' | 'onCartClose' | 'onLineEnter' | 'onLineLeave']: NonNullable<
+    TetherConfig[Hook]
+  >;
+} & Pick<TetherConfig, 'onValueChange'>;
+
+export type { BarbaPresetOptions, BarbaPresetConfig };
+
+const LINE_DURATION_SECONDS = 0.3;
+/** @returns A new object each time: GSAP writes into the vars it is given. */
+const collapsed = (): TweenVars => ({
+  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;
+
+const GETTER_OPTIONS = ['gsap', 'lenis', 'scrollTrigger'] as const;
+
+/**
+ * @throws {TypeError} When a getter option is a value, which JavaScript callers can pass: a value that is a function
+ *   (ScrollTrigger is a class) can't be told from a getter.
+ */
+function checkGetters(options: BarbaPresetOptions) {
+  for (const name of GETTER_OPTIONS) {
+    const option: unknown = options[name];
+    if (option !== undefined && option !== null && typeof option !== 'function') {
+      throw new TypeError(`barbaPreset: ${name} must be a function that returns it, such as () => ${name}`);
+    }
+  }
+}
+
+/**
+ * Calls `target[method]()` when it has one: Lenis and ScrollTrigger are optional and versions differ.
+ *
+ * @param target An object, or a class with a static method (`ScrollTrigger.refresh()`).
+ */
+function callIfPresent(target: unknown, method: string) {
+  if ((typeof target !== 'object' && typeof target !== 'function') || target === null) return;
+  const fn: unknown = Reflect.get(target, method);
+  // A method of `target`, called on it.
+  if (typeof fn === 'function') (fn as (this: unknown) => unknown).call(target);
+}
+
+const isGsap = (value: unknown): value is Gsap =>
+  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()`.
+ */
+export function barbaPreset(options: BarbaPresetOptions = {}): BarbaPresetConfig {
+  checkGetters(options);
+  const {
+    gsap = (): unknown => Reflect.get(window, 'gsap'),
+    lenis = null,
+    scrollTrigger = (): unknown => Reflect.get(window, 'ScrollTrigger'),
+    lockScroll = null,
+    unlockScroll = null,
+    onResize = null,
+    onValueChange = null,
+    animateLines = true,
+    lineDuration = LINE_DURATION_SECONDS,
+  } = options;
+
+  /** Whether this preset holds the scroll lock, so a modal's own lock stays intact. */
+  let locked = false;
+
+  /** @returns GSAP, when this line should animate. */
+  const animator = (node: HTMLElement): Gsap | null => {
+    if (!animateLines || reducedMotion() || node.offsetHeight <= 0) return null;
+    const animation = gsap();
+    return isGsap(animation) ? animation : null;
+  };
+
+  return {
+    autoMount: false,
+
+    onLayoutChange() {
+      callIfPresent(lenis?.(), 'resize');
+      callIfPresent(scrollTrigger(), 'refresh');
+    },
+
+    onCartOpen(drawers) {
+      const drawer = drawers[0];
+      if (locked || !lockScroll || !drawer) return;
+      lockScroll(drawer);
+      locked = true;
+    },
+
+    onCartClose() {
+      if (locked && unlockScroll) unlockScroll();
+      locked = false;
+    },
+
+    onLineEnter(node) {
+      const animation = animator(node);
+      if (!animation) return;
+      const style = getComputedStyle(node);
+      animation.fromTo(node, collapsed(), {
+        height: node.offsetHeight,
+        paddingTop: style.paddingTop,
+        paddingBottom: style.paddingBottom,
+        borderBottomWidth: style.borderBottomWidth,
+        opacity: 1,
+        duration: lineDuration,
+        clearProps: ANIMATED_PROPS,
+        onComplete: () => onResize?.(),
+      });
+    },
+
+    onLineLeave(node, done) {
+      const animation = animator(node);
+      if (!animation) {
+        done();
+        return;
+      }
+      animation.to(node, {
+        ...collapsed(),
+        duration: lineDuration,
+        onComplete: () => {
+          done();
+          onResize?.();
+        },
+      });
+    },
+
+    onValueChange,
+  };
+}
+
+/** @alias `barbaPreset`, for `import barbaPreset from '@occluze/tether/presets/barba'`. */
+export default barbaPreset;

package/src/{product-events.js → product-events.ts}

@@ -2,47 +2,33 @@
  * 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' */
+import { reportError } from './config.ts';
+import { sel, get, emit, setText, busy } from './dom.ts';
+import { addButtonLabel } from './variant-render.ts';
+import type { ProductScope } from './product.ts';
+import type { Purchase } from './product-state.ts';
 
 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';
+const isField = (el: Element): el is HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement =>
+  el.tagName === 'INPUT' || el.tagName === 'SELECT' || el.tagName === 'TEXTAREA';
 
-/**
- * @param {EventTarget | null} target
- * @returns {target is Element}
- */
-const isElement = (target) => target instanceof window.Element;
+const isElement = (target: EventTarget | null): target is Element => 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.
+ * @returns 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));
+function closestOwn(scope: ProductScope, target: Element, selector: string): HTMLElement | null {
+  const el = target.closest<HTMLElement>(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) {
+/** Adds to the cart with `aria-busy` on the button and `tether-adding-text` as its label meanwhile. */
+function onAddClick(scope: ProductScope, button: HTMLElement): void {
   const { label, original } = addButtonLabel(button);
   const addingText = get(button, 'adding-text');
-  void busy(button, async () => {
+  busy(button, async () => {
     if (addingText) setText(label, addingText);
     try {
       await scope.addToCart();
@@ -52,18 +38,17 @@ function onAddClick(scope, button) {
     } 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();
-  });
+  })
+    .then(() => {
+      // The mode-dependent labels (tether-subscribe-text, tether-soldout-text) wait for aria-busy to clear.
+      scope.renderVariant();
+    })
+    .catch((error: unknown) => {
+      reportError(error, 'add to cart render');
+    });
 }
 
-/**
- * @param {ProductScope} scope
- * @param {Event} event
- * @param {Element} target
- */
-function onClick(scope, event, target) {
+function onClick(scope: ProductScope, event: Event, target: Element): void {
   const optionValue = closestOwn(scope, target, sel('option-value'));
   const optionList = optionValue?.closest(sel('option-list'));
   if (optionValue && optionList) {
@@ -81,7 +66,7 @@ function onClick(scope, event, target) {
   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'));
+    scope.setPurchase(purchaseKind(get(purchase, 'purchase')));
     return;
   }
   const plus = closestOwn(scope, target, sel('qty-plus'));
@@ -98,11 +83,12 @@ function onClick(scope, event, target) {
   }
 }
 
-/**
- * @param {ProductScope} scope
- * @param {Element} target A form field in the scope.
- */
-function onChange(scope, target) {
+/** @returns The kind a `tether-purchase` value asks for: `subscription`, else buying once. */
+const purchaseKind = (value: string | null): Purchase['kind'] =>
+  value === 'subscription' ? 'subscription' : 'one-time';
+
+/** @param target A form field in the scope. */
+function onChange(scope: ProductScope, target: Element): void {
   const value = isField(target) ? target.value : '';
   if (target.matches(`select${sel('option')}`)) {
     scope.select(scope.optName(get(target, 'option')), value);
@@ -112,14 +98,13 @@ function onChange(scope, target) {
     if (value) scope.selectPlan(value);
     else scope.setPurchase('one-time');
   } else if (target.matches(`select${sel('purchase')}`)) {
-    scope.setPurchase(value);
+    scope.setPurchase(purchaseKind(value));
   } else if (target.matches(sel('qty'))) {
     scope.setQuantity(value);
   }
 }
 
-/** @param {ProductScope} scope */
-export function bindProductEvents(scope) {
+export function bindProductEvents(scope: ProductScope): void {
   scope.root.addEventListener('click', (event) => {
     if (isElement(event.target)) onClick(scope, event, event.target);
   });

package/src/{product-render.js → product-render.ts}

@@ -1,6 +1,6 @@
 /**
  * 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.
+ * plan lists and the options of its selects. `variant-render.ts` writes what follows the visitor's choice.
  */
 import {
   attr,
@@ -18,23 +18,20 @@ import {
   hasTemplate,
   sameImage,
   productUrl,
-} from './dom.js';
-/** @import { Product, Image } from './fragments.js' */
-/** @import { PlanInGroup } from './selling-plans.js' */
+} from './dom.ts';
+import type { Product } from './fragments.ts';
+import type { PlanInGroup } from './selling-plans.ts';
 
-/**
- * @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
- */
+/** The product scope as its renders see it. */
+export interface RenderScope {
+  readonly root: HTMLElement;
+  readonly product: Product;
+  readonly plans: PlanInGroup[];
+  /** Matches in this scope, the root included. */
+  $: (selector: string) => HTMLElement[];
+  /** The product's option name for one written in the markup. */
+  optName: (authored: string | null) => string;
+}
 
 /** `tether-bind="image:2"`: the second product image. */
 const NTH_IMAGE_BIND = /^image:(\d+)$/;
@@ -43,26 +40,14 @@ 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';
+export const isSelect = (el: Element): el is HTMLSelectElement => 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);
+/** @returns The `<select>` elements in the scope that match `selector`. */
+export const selectsIn = (scope: RenderScope, selector: string): HTMLSelectElement[] =>
+  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) {
+/** Leaves a server-rendered gallery with the same images as it is. */
+function renderGallery(el: HTMLElement, product: Product): void {
   const images = product.images.nodes;
   const rendered = [...el.children].map((node) => (node.tagName === 'IMG' ? node : node.querySelector('img')));
   const same =
@@ -76,12 +61,8 @@ function renderGallery(el, product) {
   });
 }
 
-/**
- * @param {HTMLElement} el
- * @param {Product} product
- * @param {string} ref `namespace.key`
- */
-function renderMetafield(el, product, ref) {
+/** @param ref `namespace.key` */
+function renderMetafield(el: HTMLElement, product: Product, ref: string): void {
   const dot = ref.indexOf('.');
   const namespace = ref.slice(0, dot);
   const key = ref.slice(dot + 1);
@@ -99,8 +80,8 @@ function renderMetafield(el, product, ref) {
   setText(el, metafield.value);
 }
 
-/** @type {Map<string, (product: Product) => string>} The product binds written as text. */
-const PRODUCT_TEXTS = new Map(
+/** The product binds written as text. */
+const PRODUCT_TEXTS = new Map<string, (product: Product) => string>(
   Object.entries({
     title: (product) => product.title,
     'description-text': (product) => product.description,
@@ -113,11 +94,7 @@ const PRODUCT_TEXTS = new Map(
   }),
 );
 
-/**
- * @param {HTMLElement} el
- * @param {Product} product
- */
-function renderTags(el, product) {
+function renderTags(el: HTMLElement, product: Product): void {
   const exclude = (el.getAttribute('exclude') ?? '')
     .split(',')
     .map((tag) => tag.trim())
@@ -130,12 +107,8 @@ function renderTags(el, product) {
 
 /**
  * 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) {
+function renderProductBind(el: HTMLElement, key: string, product: Product): void {
   const text = PRODUCT_TEXTS.get(key);
   if (text) {
     setText(el, text(product));
@@ -149,10 +122,12 @@ function renderProductBind(el, key, product) {
       setImage(el, product.featuredImage?.url, product.featuredImage?.altText || product.title);
       break;
     case 'url':
-    case 'link':
-      el.setAttribute('href', productUrl(product.handle, product.id));
+    case 'link': {
+      const url = productUrl(product.handle, product.id);
+      if (url) el.setAttribute('href', url);
       if (key === 'url' && !el.firstElementChild && !el.textContent.trim()) setText(el, product.title);
       break;
+    }
     case 'images':
       renderGallery(el, product);
       break;
@@ -164,14 +139,8 @@ function renderProductBind(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) {
+/** `image:<n>` (falling back to the featured image) and `metafield:<namespace.key>`. */
+function renderIndexedBind(el: HTMLElement, key: string, product: Product): void {
   const nth = NTH_IMAGE_BIND.exec(key);
   if (nth) {
     const image = product.images.nodes[Number(nth[1]) - 1] ?? product.featuredImage;
@@ -181,8 +150,7 @@ function renderIndexedBind(el, key, product) {
   }
 }
 
-/** @param {RenderScope} scope */
-function renderOptionLists(scope) {
+function renderOptionLists(scope: RenderScope): void {
   const { product } = scope;
   scope.$(sel('option-list')).forEach((container) => {
     const name = scope.optName(get(container, 'option-list'));
@@ -197,8 +165,7 @@ function renderOptionLists(scope) {
       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);
+      const { swatch } = value;
       if (!swatchEl || !swatch) return;
       if (swatch.color) swatchEl.style.backgroundColor = swatch.color;
       if (swatch.image?.previewImage) setImage(swatchEl, swatch.image.previewImage.url, value.name);
@@ -206,8 +173,7 @@ function renderOptionLists(scope) {
   });
 }
 
-/** @param {RenderScope} scope */
-function renderSelects(scope) {
+function renderSelects(scope: RenderScope): void {
   const { product } = scope;
   selectsIn(scope, sel('option')).forEach((select) => {
     const option = product.options.find((candidate) => candidate.name === scope.optName(get(select, 'option')));
@@ -228,8 +194,7 @@ function renderSelects(scope) {
   });
 }
 
-/** @param {RenderScope} scope */
-function renderPlanLists(scope) {
+function renderPlanLists(scope: RenderScope): void {
   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();
@@ -242,12 +207,8 @@ function renderPlanLists(scope) {
   });
 }
 
-/**
- * Writes what depends on the product alone: its binds, option and plan lists and the selects' options.
- *
- * @param {RenderScope} scope
- */
-export function writeProduct(scope) {
+/** Writes what depends on the product alone: its binds, option and plan lists and the selects' options. */
+export function writeProduct(scope: RenderScope): void {
   scope.$(sel('bind')).forEach((el) => {
     renderProductBind(el, get(el, 'bind') ?? '', scope.product);
   });

package/src/product-shape.ts

@@ -0,0 +1,49 @@
+/**
+ * The structure of Tether's product fragment, checked on a value read from the page or from a Storefront answer
+ * before it is used as a `Product`. Rendering walks the product's lists and prices without checking each step, so a
+ * truncated or hand-written entry, or an answer missing fields, would otherwise fail deep inside a render instead of
+ * being skipped or refused.
+ */
+import { matches } from './client.ts';
+import { field, isRecord } from '../server/src/shared/json.ts';
+import type { Shape } from './client.ts';
+import type { Product } from './fragments.ts';
+import type { PageInfo } from './loader.ts';
+
+/** A page of a GraphQL connection of products. */
+export interface ProductConnection {
+  nodes: Product[];
+  pageInfo: PageInfo;
+}
+
+/** A Storefront API `MoneyV2`. */
+export const MONEY = { amount: 'string', currencyCode: 'string' } as const satisfies Shape;
+
+/**
+ * A product's id, handle and title, and every list and price a render walks without a fallback: images, options,
+ * variants (each with an id, a price and its options) and the price range. Text fields are written as text, and the
+ * selling plan lists are read with a fallback, so they need no check.
+ */
+export const PRODUCT = {
+  id: 'string',
+  handle: 'string',
+  title: 'string',
+  options: ['object'],
+  images: { nodes: ['object'] },
+  priceRange: { minVariantPrice: MONEY, maxVariantPrice: MONEY },
+  variants: { nodes: [{ id: 'string', price: MONEY, selectedOptions: ['object'] }] },
+} as const satisfies Shape;
+
+/** A page of products, with the `pageInfo` paging reads. */
+export const PRODUCT_CONNECTION = { nodes: [PRODUCT], pageInfo: { hasNextPage: 'boolean' } } as const satisfies Shape;
+
+/** True for a value with the structure of `PRODUCT` and a non-empty id and handle. */
+export const isProductShape = (value: unknown): value is Product =>
+  field(value, 'id') !== '' && field(value, 'handle') !== '' && matches(value, PRODUCT);
+
+/**
+ * A node a lookup by gid answers: a product, or a node of another type, for which `... on Product` selects no field
+ * (no `id`).
+ */
+export const PRODUCT_NODE = (node: unknown): boolean =>
+  isRecord(node) && (node['id'] === undefined || matches(node, PRODUCT));