@occluze/tether 0.6.7 → 0.7.0

package/src/product-events.ts

@@ -0,0 +1,115 @@
+/**
+ * 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.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');
+
+const isField = (el: Element): el is HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement =>
+  el.tagName === 'INPUT' || el.tagName === 'SELECT' || el.tagName === 'TEXTAREA';
+
+const isElement = (target: EventTarget | null): target is Element => target instanceof window.Element;
+
+/**
+ * @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: 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. */
+function onAddClick(scope: ProductScope, button: HTMLElement): void {
+  const { label, original } = addButtonLabel(button);
+  const addingText = get(button, 'adding-text');
+  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();
+    })
+    .catch((error: unknown) => {
+      reportError(error, 'add to cart render');
+    });
+}
+
+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) {
+    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(purchaseKind(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);
+  }
+}
+
+/** @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);
+  } 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(purchaseKind(value));
+  } else if (target.matches(sel('qty'))) {
+    scope.setQuantity(value);
+  }
+}
+
+export function bindProductEvents(scope: ProductScope): void {
+  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.ts

@@ -0,0 +1,218 @@
+/**
+ * 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.ts` 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.ts';
+import type { Product } from './fragments.ts';
+import type { PlanInGroup } from './selling-plans.ts';
+
+/** 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+)$/;
+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', '*'];
+
+export const isSelect = (el: Element): el is HTMLSelectElement => el.tagName === 'SELECT';
+
+/** @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. */
+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 =
+    !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 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);
+  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);
+}
+
+/** 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,
+    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),
+  }),
+);
+
+function renderTags(el: HTMLElement, product: Product): void {
+  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`.
+ */
+function renderProductBind(el: HTMLElement, key: string, product: Product): void {
+  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': {
+      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;
+    case 'tags':
+      renderTags(el, product);
+      break;
+    default:
+      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;
+    setImage(el, image?.url, image?.altText || product.title);
+  } else if (key.startsWith(METAFIELD_BIND)) {
+    renderMetafield(el, product, key.slice(METAFIELD_BIND.length));
+  }
+}
+
+function renderOptionLists(scope: RenderScope): void {
+  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];
+      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);
+    });
+  });
+}
+
+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')));
+    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);
+  });
+}
+
+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();
+    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. */
+export function writeProduct(scope: RenderScope): void {
+  scope.$(sel('bind')).forEach((el) => {
+    renderProductBind(el, get(el, 'bind') ?? '', scope.product);
+  });
+  renderOptionLists(scope);
+  renderSelects(scope);
+  renderPlanLists(scope);
+}

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));