@occluze/tether 0.6.8 → 0.7.1

package/src/product-render.js

@@ -1,257 +0,0 @@
-/**
- * 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);
-}

package/src/product-state.js

@@ -1,318 +0,0 @@
-/**
- * What a product scope shows for the visitor's choice: the variant, the purchase it is bought as, its prices, the
- * text of every `tether-bind` and every `tether-show` condition. Pure, no DOM and no config: the browser scope
- * (`product.js`) and the server's `initialState()` (`initial.js`) derive their view here, so a server-rendered page
- * shows what the script shows when it takes over.
- */
-import {
-  GID,
-  allPlans,
-  allocationFor,
-  findPlan,
-  planAdjustment,
-  planCheckoutCharge,
-  planPrice,
-  planSavings,
-} from './selling-plans.js';
-/** @import { Money } from './shopify-values.js' */
-/** @import { Product, ProductVariant } from './fragments.js' */
-/** @import { PlanInGroup } from './selling-plans.js' */
-
-/** @typedef {Record<string, string>} Selection Option name → chosen value. */
-/**
- * How the visitor buys. Buying once still names the product's plan when it has plans: the plan the subscription
- * binds (`subscription-price`, `plan-name`) offer next to the one-time price, and the one subscribing switches to.
- *
- * @typedef {{ kind: 'one-time', planId: string | null } | { kind: 'subscription', planId: string }} Purchase
- */
-/**
- * @typedef {object} ProductChoice What the visitor chose, before it is checked against the product.
- * @property {Selection} selected
- * @property {Purchase} purchase
- * @property {number} quantity
- */
-/**
- * @typedef {'in-stock' | 'out-of-stock' | 'backorder' | 'on-sale' | 'not-on-sale' | 'has-variants' | 'single-variant'
- *   | 'low-stock' | 'plenty-in-stock' | 'subscription-available' | 'subscription-unavailable' | 'subscription-only'
- *   | 'one-time-available' | 'subscription-selected' | 'one-time-selected' | 'has-savings'} ShowCondition
- */
-/**
- * @typedef {object} ProductView
- * @property {ProductVariant} variant
- * @property {Selection} selected The selection, matching `variant`.
- * @property {Purchase} purchase The choice, made valid for the product and `variant`.
- * @property {PlanInGroup | null} plan The purchase's plan, offered or chosen.
- * @property {boolean} isSubscription The line is bought on `plan`: subscription chosen and the variant is on it.
- * @property {boolean} subscriptionAvailable The variant is on at least one plan.
- * @property {number} quantity
- * @property {Money} price What one item costs as bought.
- * @property {Money | null} compareAtPrice Only when on sale.
- * @property {{ amount: Money | null, percentage: number }} savings What `plan` saves on the one-time price.
- * @property {Record<ShowCondition, boolean>} show
- */
-/**
- * @typedef {object} Formatters How the caller writes values as text.
- * @property {(money: Money | null) => string} money
- * @property {(percentage: number) => string} percent
- */
-/** @typedef {string | number | null | undefined} BindText What a bind writes; `null` and `undefined` clear it. */
-
-/** Money arithmetic works in hundredths, the precision Tether shows Shopify's amounts in. */
-const MINOR_UNITS_PER_UNIT = 100;
-const PERCENT = 100;
-
-/** @param {Money} money */
-const toMinorUnits = (money) => Math.round(parseFloat(money.amount) * MINOR_UNITS_PER_UNIT);
-
-/**
- * @param {number} minorUnits
- * @param {string} currencyCode
- * @returns {Money}
- */
-const fromMinorUnits = (minorUnits, currencyCode) => ({
-  amount: (minorUnits / MINOR_UNITS_PER_UNIT).toFixed(2),
-  currencyCode,
-});
-
-/**
- * @param {Money} money
- * @param {number} quantity
- */
-const timesQuantity = (money, quantity) => fromMinorUnits(toMinorUnits(money) * quantity, money.currencyCode);
-
-/**
- * @param {ProductVariant} variant
- * @returns {Selection}
- */
-export const selectionOf = (variant) =>
-  Object.fromEntries(variant.selectedOptions.map((option) => [option.name, option.value]));
-
-/**
- * @param {Product} product
- * @param {Selection} selected
- * @returns {ProductVariant | null} The variant with exactly these option values.
- */
-function findVariant(product, selected) {
-  return (
-    product.variants.nodes.find((variant) =>
-      variant.selectedOptions.every((option) => selected[option.name] === option.value),
-    ) ?? null
-  );
-}
-
-/**
- * @param {Product} product
- * @param {Selection} selected
- * @param {string} name An option name.
- * @param {string} value
- * @returns {boolean} True when a variant for sale has this value and the other selected values.
- */
-export function isValueAvailable(product, selected, name, value) {
-  return product.variants.nodes.some(
-    (variant) =>
-      variant.availableForSale &&
-      variant.selectedOptions.every((option) =>
-        option.name === name ? option.value === value : selected[option.name] === option.value,
-      ),
-  );
-}
-
-/**
- * The purchase made valid for the product and variant: one-time without plans, a subscription when the product
- * requires one, and a plan the variant is on when it is on any (else a plan of the product, for the binds to offer).
- *
- * @param {Product} product
- * @param {ProductVariant | null} variant
- * @param {{ kind: Purchase['kind'], planId: string | null }} wanted
- * @returns {Purchase}
- */
-export function normalisePurchase(product, variant, wanted) {
-  const plans = allPlans(product);
-  const known = plans.find((plan) => plan.id === wanted.planId) ?? plans[0];
-  if (!known) return { kind: 'one-time', planId: null };
-  const onVariant = allocationFor(variant, known.id)
-    ? known
-    : (plans.find((plan) => allocationFor(variant, plan.id)) ?? known);
-  if (product.requiresSellingPlan || wanted.kind === 'subscription')
-    return { kind: 'subscription', planId: onVariant.id };
-  return { kind: 'one-time', planId: onVariant.id };
-}
-
-/**
- * @typedef {object} InitialChoiceOptions
- * @property {string | null | undefined} [variant] A variant id or gid (`?variant=`); the first variant for sale without.
- * @property {string | null | undefined} [sellingPlan] A plan to subscribe on (`?selling_plan=`).
- * @property {string | null | undefined} [defaultPlan] The plan offered first, by id, name or option value.
- * @property {string | null | undefined} [defaultPurchase] `subscription` subscribes; anything else buys once.
- */
-
-/**
- * What a product starts with before the visitor chooses anything.
- *
- * @param {Product} product
- * @param {InitialChoiceOptions} options
- * @returns {Omit<ProductChoice, 'quantity'>}
- */
-export function initialChoice(product, { variant, sellingPlan, defaultPlan, defaultPurchase }) {
-  const variants = product.variants.nodes;
-  const wantedId = GID.variant(variant);
-  const start =
-    variants.find((candidate) => candidate.id === wantedId) ??
-    variants.find((candidate) => candidate.availableForSale) ??
-    variants[0] ??
-    null;
-  const fromUrl = findPlan(product, sellingPlan);
-  const offered = fromUrl ?? findPlan(product, defaultPlan);
-  const kind = fromUrl || defaultPurchase === 'subscription' ? 'subscription' : 'one-time';
-  return {
-    selected: start ? selectionOf(start) : {},
-    purchase: normalisePurchase(product, start, { kind, planId: offered?.id ?? null }),
-  };
-}
-
-/**
- * @param {ProductVariant} variant
- * @param {number} lowStock
- * @param {number} variantCount
- * @param {Pick<ProductView, 'isSubscription' | 'subscriptionAvailable' | 'compareAtPrice' | 'savings'>} sale
- * @param {boolean} requiresSellingPlan
- * @returns {Record<ShowCondition, boolean>}
- */
-function showConditions(variant, lowStock, variantCount, sale, requiresSellingPlan) {
-  const stock = variant.quantityAvailable;
-  const low = stock != null && stock > 0 && stock <= lowStock;
-  const onSale = sale.compareAtPrice !== null;
-  return {
-    'in-stock': variant.availableForSale,
-    'out-of-stock': !variant.availableForSale,
-    backorder: variant.availableForSale && variant.currentlyNotInStock,
-    'on-sale': onSale,
-    'not-on-sale': !onSale,
-    'has-variants': variantCount > 1,
-    'single-variant': variantCount === 1,
-    'low-stock': low,
-    'plenty-in-stock': variant.availableForSale && !low,
-    'subscription-available': sale.subscriptionAvailable,
-    'subscription-unavailable': !sale.subscriptionAvailable,
-    'subscription-only': requiresSellingPlan,
-    'one-time-available': !requiresSellingPlan,
-    'subscription-selected': sale.isSubscription,
-    'one-time-selected': !sale.isSubscription,
-    'has-savings': sale.isSubscription ? sale.savings.percentage > 0 : onSale,
-  };
-}
-
-/**
- * The view for the visitor's choice. A selection no variant has falls back to the first variant.
- *
- * @param {Product} product
- * @param {ProductChoice} choice
- * @param {number} lowStock `low-stock` at this many or fewer.
- * @returns {ProductView | null} `null` for a product without variants.
- */
-export function productView(product, choice, lowStock) {
-  const exact = findVariant(product, choice.selected);
-  const variant = exact ?? product.variants.nodes[0];
-  if (!variant) return null;
-  const purchase = normalisePurchase(product, variant, choice.purchase);
-  const { planId } = purchase;
-  const plans = allPlans(product);
-  const allocation = purchase.kind === 'subscription' ? allocationFor(variant, planId) : null;
-  // The plan helpers fall back to the one-time price only without a variant, which `variant` rules out.
-  const price = allocation ? (planPrice(variant, planId) ?? variant.price) : variant.price;
-  const compareAt = allocation?.priceAdjustments[0]?.compareAtPrice ?? variant.compareAtPrice;
-  const sale = {
-    isSubscription: allocation !== null,
-    subscriptionAvailable: plans.some((plan) => allocationFor(variant, plan.id)),
-    compareAtPrice: compareAt && parseFloat(compareAt.amount) > parseFloat(price.amount) ? compareAt : null,
-    savings: planSavings(variant, planId),
-  };
-  return {
-    ...sale,
-    variant,
-    selected: exact ? choice.selected : selectionOf(variant),
-    purchase,
-    plan: plans.find((plan) => plan.id === planId) ?? null,
-    quantity: choice.quantity,
-    price,
-    show: showConditions(variant, lowStock, product.variants.nodes.length, sale, product.requiresSellingPlan),
-  };
-}
-
-/**
- * The `tether-bind` values that follow the variant and purchase. Thunks, so only the binds on the page are computed.
- *
- * @param {ProductView} view
- * @param {Formatters} format
- * @returns {Map<string, () => BindText>}
- */
-export function variantBindTexts(view, format) {
-  const { variant, plan, price, compareAtPrice, quantity } = view;
-  const planId = view.purchase.planId;
-  // Prices for the quantity count one item when it is 0 (an optional bundle item).
-  const forQuantity = (/** @type {Money} */ money) => timesQuantity(money, Math.max(1, quantity));
-  const checkoutCharge = () => {
-    const charge = view.isSubscription ? (planCheckoutCharge(variant, planId) ?? price) : price;
-    return format.money(forQuantity(charge));
-  };
-  const discountPercentage = () => {
-    if (!compareAtPrice) return '0%';
-    return `${Math.round((1 - parseFloat(price.amount) / parseFloat(compareAtPrice.amount)) * PERCENT)}%`;
-  };
-  const discountAmount = () => {
-    if (!compareAtPrice) return '';
-    return format.money(fromMinorUnits(toMinorUnits(compareAtPrice) - toMinorUnits(price), price.currencyCode));
-  };
-  /** @type {Record<string, () => BindText>} */
-  const texts = {
-    price: () => format.money(price),
-    'total-price': () => format.money(forQuantity(price)),
-    'one-time-price': () => format.money(variant.price),
-    'subscription-price': () => format.money(planId ? planPrice(variant, planId) : null),
-    'subscription-savings': () => format.percent(view.savings.percentage),
-    'subscription-savings-amount': () => format.money(view.savings.amount),
-    'checkout-charge': checkoutCharge,
-    'plan-name': () => plan?.name,
-    'plan-description': () => plan?.description,
-    'plan-group': () => plan?.group.name,
-    'compare-at-price': () => format.money(compareAtPrice),
-    'unit-price': () => format.money(variant.unitPrice),
-    'discount-percentage': discountPercentage,
-    'discount-amount': discountAmount,
-    'variant-title': () => variant.title,
-    'variant-id': () => variant.id,
-    sku: () => variant.sku,
-    barcode: () => variant.barcode,
-    stock: () => variant.quantityAvailable,
-    quantity: () => quantity,
-  };
-  return new Map(Object.entries(texts));
-}
-/**
- * The `tether-plan-bind` values of one plan in a plan list, for the variant.
- *
- * @param {ProductVariant} variant
- * @param {string} planId The list item's `tether-plan-value`.
- * @param {PlanInGroup | undefined} plan The product's plan with that id.
- * @param {Formatters} format
- * @returns {Map<string, () => BindText>}
- */
-export function planBindTexts(variant, planId, plan, format) {
-  const adjustmentText = () => {
-    const adjustment = planAdjustment(plan);
-    if (!adjustment) return '';
-    return adjustment.type === 'percentage' ? `${adjustment.value}%` : format.money(adjustment.value);
-  };
-  /** @type {Record<string, () => BindText>} */
-  const texts = {
-    name: () => plan?.name,
-    // The option values alone ("1 month"), without the price text a store may put in the plan name.
-    option: () => (plan?.options ?? []).map((option) => option.value).join(', '),
-    description: () => plan?.description,
-    price: () => format.money(planPrice(variant, planId)),
-    savings: () => format.percent(planSavings(variant, planId).percentage),
-    'savings-amount': () => format.money(planSavings(variant, planId).amount),
-    adjustment: adjustmentText,
-  };
-  return new Map(Object.entries(texts));
-}