@occluze/tether 0.6.7 → 0.6.8

package/src/cart/mutations.js

@@ -0,0 +1,234 @@
+/**
+ * The Storefront Cart API: loading the saved cart, creating one, and the mutations that change it. Shopify forgets a
+ * cart some days after its last change and once it has been checked out; a change that needs a cart then creates a
+ * new one with the same input, so the visitor's click still lands.
+ */
+import { cfg, log } from '../config.js';
+import { gql, unwrap, TetherError } from '../client.js';
+import { cartFragment } from '../fragments.js';
+import { GID } from '../selling-plans.js';
+import { toAttributes } from '../dom.js';
+import { customer, savedCartId, forgetSavedCart, setWarnings } from './store.js';
+/** @import { CartWarning } from '../config.js' */
+/** @import { UserError } from '../client.js' */
+/** @import { AttributeValue } from '../dom.js' */
+/** @import { ShopifyCart, Attribute } from './store.js' */
+
+/** @typedef {Record<string, AttributeValue> | { key: string | number, value?: AttributeValue }[]} Attributes */
+/**
+ * @typedef {object} LineSpec A line to add, in any of the shapes `Cart.add` takes.
+ * @property {string | number} [variantId]
+ * @property {string | number} [merchandiseId]
+ * @property {string | number} [id]
+ * @property {number | string} [quantity]
+ * @property {string | number | null} [sellingPlanId]
+ * @property {string | number | null} [sellingPlan]
+ * @property {Attributes | null} [attributes]
+ */
+/**
+ * @typedef {object} CartLineInput Shopify's `CartLineInput`.
+ * @property {string} merchandiseId
+ * @property {number} quantity
+ * @property {string} [sellingPlanId]
+ * @property {Attribute[]} [attributes]
+ */
+/**
+ * @typedef {object} CartPayload What every cart mutation answers.
+ * @property {ShopifyCart | null} cart
+ * @property {UserError[]} userErrors
+ * @property {CartWarning[]} [warnings]
+ */
+
+/**
+ * Shopify answers a cart id it can't resolve, in a mutation, with a top-level GraphQL error whose only detail is
+ * this message (no `extensions.code`). A user error on the `cartId` field is recognised by its shape instead.
+ */
+const UNKNOWN_CART_MESSAGE = /does not exist|not found|invalid id/i;
+
+/**
+ * @param {unknown} error
+ * @returns {boolean} True when `error` says Shopify doesn't have the cart, false for any other failure (the network,
+ *   the token, a line it refused), after which the saved cart is still good.
+ */
+export function isCartGone(error) {
+  if (!(error instanceof TetherError)) return false;
+  if (error.userErrors?.some((userError) => userError.field?.[0] === 'cartId')) return true;
+  return (error.errors ?? []).some((graphQLError) => UNKNOWN_CART_MESSAGE.test(graphQLError.message));
+}
+
+/**
+ * @param {string | number | LineSpec | null | undefined} input A variant id, or a line.
+ * @param {number} [quantity] For a variant id.
+ * @param {Omit<LineSpec, 'variantId' | 'quantity'>} [options] For a variant id.
+ * @returns {CartLineInput}
+ * @throws {TetherError} `ERROR` without a variant id.
+ */
+export function toLineInput(input, quantity = 1, options = {}) {
+  const spec = typeof input === 'object' && input !== null ? input : { ...options, variantId: input, quantity };
+  const merchandiseId = GID.variant(spec.merchandiseId || spec.variantId || spec.id);
+  if (!merchandiseId) throw new TetherError('add(): variantId is required');
+  const asked = parseInt(String(spec.quantity ?? 1), 10);
+  /** @type {CartLineInput} */
+  const line = { merchandiseId, quantity: Math.max(1, asked || 1) };
+  const planId = GID.sellingPlan(spec.sellingPlanId || spec.sellingPlan);
+  if (planId) line.sellingPlanId = planId;
+  const attributes = toAttributes(spec.attributes);
+  if (attributes.length) line.attributes = attributes;
+  return line;
+}
+
+/**
+ * @param {string} name The mutation, which is also its payload's field.
+ * @param {string} args The operation's variable definitions.
+ * @param {string} inner The mutation field's arguments.
+ */
+function mutationText(name, args, inner) {
+  return `mutation Tether_${name}(${args}) {
+  ${name}(${inner}) { cart { ...TetherCart } userErrors { field message } warnings { code message target } }
+}
+${cartFragment()}`;
+}
+
+/**
+ * @param {string} name
+ * @param {string} args
+ * @param {string} inner
+ * @param {Record<string, unknown>} variables
+ * @returns {Promise<ShopifyCart | null>} The cart in Shopify's answer, after keeping its warnings.
+ * @throws {TetherError} For a failed request, or the mutation's user errors.
+ */
+async function send(name, args, inner, variables) {
+  /** @type {Record<string, CartPayload | null | undefined>} */
+  const data = await gql(mutationText(name, args, inner), variables);
+  const payload = unwrap(data[name], name);
+  setWarnings(payload.warnings ?? []);
+  return payload.cart;
+}
+
+/**
+ * A new cart in the visitor's market, for the logged-in customer if there is one.
+ *
+ * @param {Record<string, unknown>} input More of Shopify's `CartInput`, e.g. the first lines.
+ * @returns {Promise<ShopifyCart | null>}
+ */
+function createCart(input) {
+  const buyerIdentity = {
+    ...(cfg.country ? { countryCode: cfg.country.toUpperCase() } : {}),
+    ...(customer.accessToken ? { customerAccessToken: customer.accessToken } : {}),
+  };
+  const withIdentity = Object.keys(buyerIdentity).length ? { buyerIdentity, ...input } : input;
+  return send('cartCreate', '$input: CartInput!', 'input: $input', { input: withIdentity });
+}
+
+/**
+ * @typedef {object} CartMutation A mutation on the saved cart.
+ * @property {string} name The mutation, e.g. `cartLinesAdd`.
+ * @property {string} args Its variable definitions besides `$cartId`.
+ * @property {string} inner Its arguments besides `cartId`.
+ * @property {Record<string, unknown>} variables
+ * @property {Record<string, unknown> | null} createInput The `CartInput` of a new cart that does what the mutation
+ *   asks, when there is no cart (or Shopify no longer has it); `null` leaves the visitor without a cart instead.
+ */
+
+/**
+ * Runs a mutation on the saved cart, or creates a cart from `createInput` when there is none to change.
+ *
+ * @param {CartMutation} mutation
+ * @returns {Promise<ShopifyCart | null>} The changed cart; `null` without a cart and without a `createInput`.
+ * @throws {TetherError} For a failed request or Shopify's user errors; also when the cart is gone and there is no
+ *   `createInput` (the saved cart is forgotten first).
+ */
+export async function mutateCart({ name, args, inner, variables, createInput }) {
+  const cartId = savedCartId();
+  if (!cartId) return createInput ? createCart(createInput) : null;
+  try {
+    return await send(name, `$cartId: ID!, ${args}`, `cartId: $cartId, ${inner}`, { ...variables, cartId });
+  } catch (error) {
+    if (!isCartGone(error)) throw error;
+    forgetSavedCart();
+    if (!createInput) throw error;
+    log('cart expired, creating a new one');
+    return createCart(createInput);
+  }
+}
+
+/**
+ * @param {string} id
+ * @returns {Promise<ShopifyCart | null>} The cart, `null` when Shopify doesn't have it (expired or checked out).
+ */
+export async function fetchCart(id) {
+  /** @type {{ cart: ShopifyCart | null }} */
+  const data = await gql(`query TetherCart($id: ID!) { cart(id: $id) { ...TetherCart } }\n${cartFragment()}`, { id });
+  return data.cart;
+}
+
+/**
+ * @param {string} id
+ * @returns {Promise<string | null>} The cart's current checkout URL, `null` when Shopify doesn't have the cart.
+ */
+export async function fetchCheckoutUrl(id) {
+  /** @type {{ cart: { checkoutUrl: string } | null }} */
+  const data = await gql('query TetherCheckout($id: ID!) { cart(id: $id) { checkoutUrl } }', { id });
+  return data.cart?.checkoutUrl ?? null;
+}
+
+/**
+ * @typedef {object} LinePatch A change to one line, for `updateLine`.
+ * @property {number} [quantity] 0 or less removes the line.
+ * @property {string | number | null} [sellingPlanId] `null` switches the line back to one-time purchase.
+ * @property {Attributes} [attributes]
+ * @property {string | number} [merchandiseId]
+ * @property {string | number} [variantId]
+ */
+
+/**
+ * @param {string} lineId
+ * @param {number | LinePatch} patch
+ * @returns {Record<string, unknown>} Shopify's `CartLineUpdateInput`.
+ */
+export function toLineUpdate(lineId, patch) {
+  const change = typeof patch === 'number' ? { quantity: patch } : patch;
+  /** @type {Record<string, unknown>} */
+  const line = { id: lineId };
+  if (change.quantity !== undefined) line['quantity'] = change.quantity;
+  if ('sellingPlanId' in change)
+    line['sellingPlanId'] = change.sellingPlanId ? GID.sellingPlan(change.sellingPlanId) : null;
+  if (change.attributes) line['attributes'] = toAttributes(change.attributes);
+  const variantId = change.merchandiseId || change.variantId;
+  if (variantId) line['merchandiseId'] = GID.variant(variantId);
+  return line;
+}
+
+/**
+ * @param {Record<string, unknown>[]} lines
+ * @returns {Promise<ShopifyCart | null>}
+ */
+export const updateLines = (lines) =>
+  mutateCart({
+    name: 'cartLinesUpdate',
+    args: '$lines: [CartLineUpdateInput!]!',
+    inner: 'lines: $lines',
+    variables: { lines },
+    createInput: null,
+  });
+
+/**
+ * @param {string[]} lineIds
+ * @returns {Promise<ShopifyCart | null>}
+ */
+export const removeLines = (lineIds) =>
+  mutateCart({
+    name: 'cartLinesRemove',
+    args: '$lineIds: [ID!]!',
+    inner: 'lineIds: $lineIds',
+    variables: { lineIds },
+    createInput: null,
+  });
+
+/**
+ * @param {string} lineId
+ * @param {number} target
+ * @returns {Promise<ShopifyCart | null>} The cart once `lineId` has `target` (0 removes it).
+ */
+export const setLineQuantity = (lineId, target) =>
+  target > 0 ? updateLines([{ id: lineId, quantity: target }]) : removeLines([lineId]);

package/src/cart/render.js

@@ -0,0 +1,294 @@
+/**
+ * Shows the cart everywhere on the page: counts, totals, `tether-show="cart-*"` conditions, the note, the discount
+ * codes and the `[tether-cart-lines]` repeaters. It renders what it is given (a `CartView`) and holds no state, so
+ * every render shows the cart as the store has it at that moment.
+ */
+import { cfg, reportError } from '../config.js';
+import { getProduct } from '../loader.js';
+import { allPlans } from '../selling-plans.js';
+import { isGreaterAmount } from '../amounts.js';
+import {
+  attr,
+  sel,
+  get,
+  qsa,
+  formatMoney,
+  setText,
+  setTextTracked,
+  setImage,
+  show,
+  repeat,
+  repeatKeyed,
+  productUrl,
+  notifyLayoutChanged,
+} from '../dom.js';
+import { isOpen, syncDrawerAria } from './drawer.js';
+/** @import { CartWarning } from '../config.js' */
+/** @import { Product } from '../fragments.js' */
+/** @import { ShopifyCart, ShopifyCartLine, PendingQuantity } from './store.js' */
+
+/**
+ * @typedef {object} CartView What a render shows.
+ * @property {ShopifyCart | null} cart
+ * @property {readonly CartWarning[]} warnings
+ * @property {ReadonlyMap<string, PendingQuantity>} pending Line id → the quantity quick clicks asked for.
+ * @property {boolean} failed The last load or change failed (`tether-show="cart-error"`).
+ */
+
+/** Shopify's title of a variant of a product without options. */
+const DEFAULT_TITLE = 'Default Title';
+
+/**
+ * @param {ShopifyCartLine} line
+ * @param {ReadonlyMap<string, PendingQuantity>} pending
+ * @returns {number} The quantity to show: the one asked for while an update is on its way.
+ */
+export const quantityOf = (line, pending) => pending.get(line.id)?.quantity ?? line.quantity;
+
+/** @param {string} gid */
+const numericId = (gid) => gid.split('/').pop() ?? gid;
+
+/**
+ * @param {ShopifyCartLine} line
+ * @returns {string} The product page, with the line's variant and plan selected.
+ */
+function lineUrl(line) {
+  const variant = line.merchandise;
+  const base = productUrl(variant.product.handle, variant.product.id);
+  const query = new URLSearchParams();
+  query.set('variant', numericId(variant.id));
+  const planId = line.sellingPlanAllocation?.sellingPlan.id;
+  if (planId) query.set('selling_plan', numericId(planId));
+  return `${base}${base.includes('?') ? '&' : '?'}${query.toString()}`;
+}
+
+/** @typedef {(line: ShopifyCartLine, view: CartView) => string | number} LineText */
+
+/** @type {LineText} */
+const productTitle = (line) => line.merchandise.product.title;
+
+/** @type {Record<string, LineText>} The text of each `tether-line` key. */
+const LINE_TEXT = {
+  title: productTitle,
+  'product-title': productTitle,
+  'variant-title': (line) => (line.merchandise.title === DEFAULT_TITLE ? '' : line.merchandise.title),
+  options: (line) =>
+    line.merchandise.selectedOptions
+      .filter((option) => option.value !== DEFAULT_TITLE)
+      .map((option) => `${option.name}: ${option.value}`)
+      .join(', '),
+  vendor: (line) => line.merchandise.product.vendor,
+  sku: (line) => line.merchandise.sku ?? '',
+  price: (line) => formatMoney(line.cost.amountPerQuantity),
+  'compare-at-price': (line) => formatMoney(line.cost.compareAtAmountPerQuantity ?? line.merchandise.compareAtPrice),
+  'line-total': (line) => formatMoney(line.cost.totalAmount),
+  'line-subtotal': (line) => formatMoney(line.cost.subtotalAmount),
+  quantity: (line, view) => quantityOf(line, view.pending),
+  plan: (line) => line.sellingPlanAllocation?.sellingPlan.name ?? '',
+  'plan-description': (line) => line.sellingPlanAllocation?.sellingPlan.description ?? '',
+  components: (line) =>
+    (line.lineComponents ?? [])
+      .map((component) => `${component.quantity} × ${component.merchandise.product.title}`)
+      .join(', '),
+};
+
+const ATTRIBUTE_KEY = 'attribute:';
+
+/**
+ * @param {ShopifyCartLine} line
+ * @param {string} key The `tether-line` value.
+ * @param {CartView} view
+ * @returns {string | number | undefined} The text for `key`, `undefined` for a key Tether doesn't know.
+ */
+function lineValue(line, key, view) {
+  if (Object.hasOwn(LINE_TEXT, key)) return LINE_TEXT[key]?.(line, view);
+  if (!key.startsWith(ATTRIBUTE_KEY)) return undefined;
+  const name = key.slice(ATTRIBUTE_KEY.length);
+  return line.attributes.find((attribute) => attribute.key === name)?.value ?? '';
+}
+
+/**
+ * Fills a `<select tether-line-plan>` with the product's plans (and one-time purchase, when the product allows it and
+ * the select isn't `subscription-only`), keeping the options when they haven't changed.
+ *
+ * @param {HTMLSelectElement} select
+ * @param {ShopifyCartLine} line
+ * @param {Product} product
+ */
+function fillPlanSelect(select, line, product) {
+  const plans = allPlans(product);
+  const allowOneTime = !product.requiresSellingPlan && get(select, 'line-plan') !== 'subscription-only';
+  const oneTime = { value: '', label: select.getAttribute(attr('one-time-label')) || 'One-time purchase' };
+  const choices = [...(allowOneTime ? [oneTime] : []), ...plans.map((plan) => ({ value: plan.id, label: plan.name }))];
+  const signature = choices.map((choice) => choice.value).join('|');
+  if (select.dataset['tetherSig'] !== signature) {
+    select.replaceChildren(
+      ...choices.map((choice) => {
+        const option = document.createElement('option');
+        option.value = choice.value;
+        option.textContent = choice.label;
+        return option;
+      }),
+    );
+    select.dataset['tetherSig'] = signature;
+  }
+  select.value = line.sellingPlanAllocation?.sellingPlan.id ?? '';
+  show(select, plans.length > 0);
+}
+
+/**
+ * @param {HTMLElement} node
+ * @param {ShopifyCartLine} line
+ * @param {CartView} view
+ */
+function renderLineState(node, line, view) {
+  const isSubscription = Boolean(line.sellingPlanAllocation);
+  node.classList.toggle('is-subscription', isSubscription);
+  // Shopify's note about this line, such as less stock than asked.
+  const warning = view.warnings.find((candidate) => candidate.target === line.id);
+  node.classList.toggle('is-warning', Boolean(warning));
+  const pending = view.pending.has(line.id);
+  node.classList.toggle('is-busy', pending);
+  if (pending) node.setAttribute('aria-busy', 'true');
+  else node.removeAttribute('aria-busy');
+  qsa(node, sel('line', 'warning')).forEach((el) => {
+    setTextTracked(el, warning?.message ?? '');
+  });
+  const conditions = {
+    subscription: isSubscription,
+    'one-time': !isSubscription,
+    'on-sale': isGreaterAmount(line.cost.compareAtAmountPerQuantity?.amount, line.cost.amountPerQuantity.amount),
+    'has-components': (line.lineComponents ?? []).length > 0,
+    warning: Boolean(warning),
+  };
+  qsa(node, sel('line-show')).forEach((el) => {
+    const key = get(el, 'line-show');
+    if (key !== null && Object.hasOwn(conditions, key)) show(el, conditions[/** @type {keyof conditions} */ (key)]);
+  });
+}
+
+/**
+ * @param {HTMLElement} node
+ * @param {ShopifyCartLine} line
+ * @param {CartView} view
+ */
+function renderLine(node, line, view) {
+  const variant = line.merchandise;
+  node.setAttribute(attr('line-id'), line.id);
+  qsa(node, sel('line')).forEach((el) => {
+    const key = get(el, 'line') ?? '';
+    if (key === 'image') {
+      setImage(el, variant.image?.url ?? variant.product.featuredImage?.url, variant.product.title);
+      return;
+    }
+    if (key === 'url') {
+      el.setAttribute('href', lineUrl(line));
+      return;
+    }
+    const value = lineValue(line, key, view);
+    if (value !== undefined) setTextTracked(el, value);
+  });
+  renderLineState(node, line, view);
+  qsa(node, `select${sel('line-plan')}`).forEach((select) => {
+    getProduct(variant.product.handle)
+      .then((product) => {
+        // The selector matches only <select> elements.
+        fillPlanSelect(/** @type {HTMLSelectElement} */ (select), line, product);
+      })
+      .catch((/** @type {unknown} */ error) => {
+        reportError(error, 'line plan options');
+      });
+  });
+}
+
+/**
+ * @param {ShopifyCart | null} cart
+ * @param {CartView} view
+ */
+function renderConditions(cart, view) {
+  const count = cart?.totalQuantity ?? 0;
+  const hasSubscription = (cart?.lines.nodes ?? []).some((line) => line.sellingPlanAllocation);
+  const conditions = {
+    'cart-empty': count === 0,
+    'cart-filled': count > 0,
+    'cart-has-subscription': hasSubscription,
+    'cart-no-subscription': !hasSubscription,
+    'cart-has-discount': (cart?.discountCodes ?? []).some((code) => code.applicable),
+    'cart-error': view.failed,
+    'cart-warning': view.warnings.length > 0,
+  };
+  qsa(document, sel('show')).forEach((el) => {
+    const key = get(el, 'show');
+    if (key === null || !Object.hasOwn(conditions, key) || el.closest(sel('product'))) return;
+    show(el, conditions[/** @type {keyof conditions} */ (key)]);
+  });
+  qsa(document, sel('checkout')).forEach((el) => {
+    el.classList.toggle('is-disabled', !count);
+    el.setAttribute('aria-disabled', String(!count));
+  });
+}
+
+/** @param {ShopifyCart | null} cart */
+function renderFields(cart) {
+  qsa(document, `textarea${sel('cart-note')},input${sel('cart-note')}`).forEach((el) => {
+    // The visitor may be typing in it.
+    if (document.activeElement !== el) setText(el, cart?.note ?? '');
+  });
+  qsa(document, sel('cart-discounts')).forEach((container) => {
+    repeat(container, cart?.discountCodes ?? [], (node, discount) => {
+      node.setAttribute(attr('discount-code'), discount.code);
+      const target = node.querySelector(sel('discount', 'code')) ?? (node.firstElementChild ? null : node);
+      if (target) setText(target, discount.code);
+      node.classList.toggle('is-inapplicable', !discount.applicable);
+    });
+  });
+}
+
+/** @param {CartView} view */
+export function renderCart(view) {
+  const { cart } = view;
+  /** @param {'subtotalAmount' | 'totalAmount' | 'checkoutChargeAmount'} key */
+  const money = (key) => (cart ? formatMoney(cart.cost[key]) : '');
+
+  syncDrawerAria(isOpen());
+  qsa(document, sel('cart-count')).forEach((el) => {
+    setTextTracked(el, cart?.totalQuantity ?? 0);
+  });
+  qsa(document, sel('cart-subtotal')).forEach((el) => {
+    setTextTracked(el, money('subtotalAmount'));
+  });
+  qsa(document, sel('cart-total')).forEach((el) => {
+    setTextTracked(el, money('totalAmount'));
+  });
+  qsa(document, sel('cart-checkout-charge')).forEach((el) => {
+    setTextTracked(el, money('checkoutChargeAmount'));
+  });
+  renderConditions(cart, view);
+  qsa(document, sel('cart-warning')).forEach((el) => {
+    setTextTracked(el, [...new Set(view.warnings.map((warning) => warning.message))].join(' '));
+  });
+  renderFields(cart);
+  qsa(document, sel('cart-lines')).forEach((container) => {
+    repeatKeyed(
+      container,
+      cart?.lines.nodes ?? [],
+      (line) => line.id,
+      (node, line) => {
+        renderLine(node, line, view);
+      },
+      { onEnter: cfg.onLineEnter, onLeave: cfg.onLineLeave },
+    );
+  });
+  if (cart) notifyLayoutChanged('cart');
+}
+
+/**
+ * Shows the count a saved cart had on the last page in the cart counts the page left at 0, until it has loaded.
+ *
+ * @param {string} count
+ */
+export function showSavedCount(count) {
+  qsa(document, sel('cart-count')).forEach((el) => {
+    if (/^\s*0?\s*$/.test(el.textContent)) el.textContent = count;
+  });
+}