@occluze/tether 0.6.6 → 0.6.8

package/src/account/order-list.js

@@ -0,0 +1,91 @@
+/**
+ * The customer's recent orders (`tether-orders`), with `tether-show="orders-loading"` while they load and
+ * `orders-empty` when there are none yet.
+ */
+import { reportError } from '../config.js';
+import { orderUrl, localDate } from '../account-links.js';
+import { formatMoney, get, qsa, repeat, sel, setImage, setText } from '../dom.js';
+import { ownValue, showIn } from './markup.js';
+import { fillLines } from './order-lines.js';
+/** @import { Money } from '../shopify-values.js' */
+/** @import { OrderLine } from './order-lines.js' */
+
+/**
+ * @typedef {object} AccountOrder A node of `ORDERS_QUERY` (account-ops.js).
+ * @property {string} id
+ * @property {string} name
+ * @property {string} processedAt
+ * @property {string | null} financialStatus
+ * @property {string | null} fulfillmentStatus
+ * @property {string | null} statusPageUrl
+ * @property {Money} totalPrice
+ * @property {{ nodes: OrderLine[] }} lineItems
+ */
+
+/** How many orders a `tether-orders` list shows without `tether-limit`. */
+const DEFAULT_ORDER_COUNT = 10;
+
+/**
+ * @param {AccountOrder} order
+ * @returns {Record<string, string | undefined>} The text of each `tether-order-bind` value.
+ */
+const orderTexts = (order) => ({
+  name: order.name,
+  date: localDate(order.processedAt),
+  total: formatMoney(order.totalPrice),
+  status: order.financialStatus?.toLowerCase(),
+  fulfillment: order.fulfillmentStatus?.toLowerCase(),
+  items: order.lineItems.nodes.map((line) => `${line.quantity}× ${line.title}`).join(', '),
+});
+
+/**
+ * @param {HTMLElement} node A copy of the list's template.
+ * @param {AccountOrder} order
+ */
+function fillOrder(node, order) {
+  const lines = order.lineItems.nodes;
+  const url = orderUrl(order);
+  const texts = orderTexts(order);
+  qsa(node, sel('order-bind')).forEach((el) => {
+    const key = get(el, 'order-bind') ?? '';
+    if (key === 'url') {
+      if (url) el.setAttribute('href', url);
+      return;
+    }
+    if (key === 'image') {
+      const image = lines.find((line) => line.image)?.image;
+      if (image) setImage(el, image.url, image.altText || lines[0]?.title || '');
+      return;
+    }
+    const text = ownValue(texts, key);
+    if (text !== undefined) setText(el, text);
+  });
+  qsa(node, sel('order-lines')).forEach((box) => {
+    fillLines(box, lines, null);
+  });
+  if (get(node, 'order-bind') === 'url' && url) node.setAttribute('href', url);
+}
+
+/**
+ * Fills every `tether-orders` list in `root`. A failure is reported and leaves the lists empty, without claiming the
+ * customer has no orders.
+ *
+ * @param {ParentNode} root
+ * @param {(first: number) => Promise<AccountOrder[]>} loadOrders
+ */
+export async function renderOrderList(root, loadOrders) {
+  const lists = qsa(root, sel('orders'));
+  const first = lists[0];
+  if (!first) return;
+  showIn(root, 'show', { 'orders-loading': true, 'orders-empty': false });
+  const limit = Number.parseInt(get(first, 'limit') || String(DEFAULT_ORDER_COUNT), 10) || DEFAULT_ORDER_COUNT;
+  /** @type {AccountOrder[] | null} `null` after a failure. */
+  const orders = await loadOrders(limit).catch((/** @type {unknown} */ error) => {
+    reportError(error, 'orders');
+    return null;
+  });
+  showIn(root, 'show', { 'orders-loading': false, 'orders-empty': orders?.length === 0 });
+  lists.forEach((list) => {
+    repeat(list, orders ?? [], fillOrder);
+  });
+}

package/src/account/order-page.js

@@ -0,0 +1,192 @@
+/**
+ * The order page (`tether-order`): one order in full, with its lines, totals, addresses, shipments and what can be
+ * returned. `tether-order-state` and `tether-order-show` follow the load: `loading`, then `ready`, `not-found` or
+ * `error`.
+ */
+import { reportError } from '../config.js';
+import { isHttpsUrl, localDate } from '../account-links.js';
+import { attr, formatMoney, get, qsa, repeat, sel, setText, show } from '../dom.js';
+import { addressText, bindsIn, enumText, ownValue, showIn } from './markup.js';
+import { fillLines } from './order-lines.js';
+import { order } from './operations.js';
+/** @import { Money } from '../shopify-values.js' */
+/** @import { OrderLine } from './order-lines.js' */
+
+/**
+ * @typedef {object} Fulfillment
+ * @property {string} status
+ * @property {string} createdAt
+ * @property {string | null} estimatedDeliveryAt
+ * @property {string | null} latestShipmentStatus
+ * @property {{ company: string | null, number: string | null, url: string | null }[]} trackingInformation
+ */
+/**
+ * @typedef {object} OrderDetail The order page's document in account-ops.js.
+ * @property {string} id
+ * @property {string} name
+ * @property {string} processedAt
+ * @property {string | null} cancelledAt
+ * @property {string | null} financialStatus
+ * @property {string | null} fulfillmentStatus
+ * @property {string | null} statusPageUrl
+ * @property {Money} totalPrice
+ * @property {Money | null} subtotal
+ * @property {Money | null} totalShipping
+ * @property {Money | null} totalTax
+ * @property {{ formatted: string[] } | null} shippingAddress
+ * @property {{ formatted: string[] } | null} billingAddress
+ * @property {{ nodes: (OrderLine & { id: string })[] }} lineItems
+ * @property {{ nodes: Fulfillment[] }} fulfillments
+ * @property {{ returnableLineItems: { nodes: { quantity: number, lineItem: { id: string } | null }[] } } | null}
+ *   returnInformation
+ * @property {{ nodes: { id: string, status: string }[] }} returns
+ */
+/** @typedef {'loading' | 'ready' | 'not-found' | 'error'} OrderState */
+
+/**
+ * @param {HTMLElement} el
+ * @returns {string | null} The order `tether-order` names: an id, or `url:<param>` for one in the page's URL.
+ */
+function orderKey(el) {
+  const raw = get(el, 'order') || '';
+  if (!raw.startsWith('url:')) return raw;
+  return new URL(window.location.href).searchParams.get(raw.slice('url:'.length) || 'id');
+}
+
+/**
+ * Every state but `ready`, which shows with the order.
+ *
+ * @param {HTMLElement} el
+ * @param {Exclude<OrderState, 'ready'>} state
+ */
+export function showOrderState(el, state) {
+  el.setAttribute(attr('order-state'), state);
+  showIn(el, 'order-show', {
+    loading: state === 'loading',
+    ready: false,
+    'not-found': state === 'not-found',
+    error: state === 'error',
+  });
+}
+
+/**
+ * @param {OrderDetail} detail
+ * @returns {Record<string, string>} The text of each `tether-order-bind` value.
+ */
+const orderTexts = (detail) => ({
+  name: detail.name,
+  date: localDate(detail.processedAt),
+  total: formatMoney(detail.totalPrice),
+  subtotal: formatMoney(detail.subtotal),
+  shipping: formatMoney(detail.totalShipping),
+  tax: formatMoney(detail.totalTax),
+  status: enumText(detail.financialStatus),
+  fulfillment: enumText(detail.fulfillmentStatus),
+  'shipping-address': addressText(detail.shippingAddress),
+  'billing-address': addressText(detail.billingAddress),
+  items: detail.lineItems.nodes.map((line) => `${line.quantity}× ${line.title || line.name}`).join(', '),
+  cancelled: detail.cancelledAt ? localDate(detail.cancelledAt) : '',
+});
+
+/**
+ * One shipment row: its status and dates, and its tracking link, hidden without an https one.
+ *
+ * @param {HTMLElement} row
+ * @param {Fulfillment} fulfillment
+ */
+function fillFulfillment(row, fulfillment) {
+  const tracking = fulfillment.trackingInformation[0];
+  /** @type {Record<string, string>} */
+  const texts = {
+    status: enumText(fulfillment.latestShipmentStatus || fulfillment.status),
+    date: localDate(fulfillment.createdAt),
+    eta: fulfillment.estimatedDeliveryAt ? localDate(fulfillment.estimatedDeliveryAt) : '',
+    company: tracking?.company || '',
+    number: tracking?.number || '',
+  };
+  bindsIn(row, 'fulfillment-bind').forEach((el) => {
+    const key = get(el, 'fulfillment-bind') ?? '';
+    if (key === 'url') {
+      const url = tracking?.url;
+      const linked = isHttpsUrl(url);
+      if (linked && url) el.setAttribute('href', url);
+      show(el, linked);
+      return;
+    }
+    const text = ownValue(texts, key);
+    if (text !== undefined) setText(el, text);
+  });
+}
+
+/**
+ * @param {HTMLElement} el
+ * @param {OrderDetail} detail
+ */
+function fillOrder(el, detail) {
+  const returnable = new Map(
+    (detail.returnInformation?.returnableLineItems.nodes ?? []).map((entry) => [
+      entry.lineItem?.id ?? '',
+      entry.quantity,
+    ]),
+  );
+  const shipments = detail.fulfillments.nodes;
+  const texts = orderTexts(detail);
+  qsa(el, sel('order-bind')).forEach((bind) => {
+    const key = get(bind, 'order-bind') ?? '';
+    if (key === 'url') {
+      if (detail.statusPageUrl && isHttpsUrl(detail.statusPageUrl)) bind.setAttribute('href', detail.statusPageUrl);
+      return;
+    }
+    const text = ownValue(texts, key);
+    if (text !== undefined) setText(bind, text);
+  });
+  qsa(el, sel('order-lines')).forEach((box) => {
+    fillLines(box, detail.lineItems.nodes, returnable);
+  });
+  qsa(el, sel('order-fulfillments')).forEach((box) => {
+    repeat(box, shipments, fillFulfillment);
+  });
+  const returnRequested = el.dataset['tetherReturned'] === '1';
+  showIn(el, 'order-show', {
+    loading: false,
+    ready: true,
+    error: false,
+    'not-found': false,
+    cancelled: Boolean(detail.cancelledAt),
+    shipped: shipments.length > 0,
+    returnable: [...returnable.values()].some((quantity) => quantity > 0),
+    'has-returns': !returnRequested && detail.returns.nodes.length > 0,
+    'return-requested': returnRequested,
+  });
+  el.setAttribute(attr('order-state'), 'ready');
+}
+
+/**
+ * Loads and renders the order `el` names. A failure is reported and shows the error state.
+ *
+ * @param {HTMLElement} el
+ */
+export async function renderOrder(el) {
+  const key = orderKey(el);
+  if (!key) {
+    el.setAttribute(attr('order-state'), 'not-found');
+    showIn(el, 'order-show', { 'not-found': true });
+    return;
+  }
+  showOrderState(el, 'loading');
+  /** @type {OrderDetail | null} */
+  let detail;
+  try {
+    detail = await order(key);
+  } catch (error) {
+    reportError(error, 'order');
+    showOrderState(el, 'error');
+    return;
+  }
+  if (!detail) {
+    showOrderState(el, 'not-found');
+    return;
+  }
+  el.dataset['tetherOrderId'] = detail.id;
+  fillOrder(el, detail);
+}

package/src/account/page-events.js

@@ -0,0 +1,288 @@
+/**
+ * What the visitor does on the account pages: the profile and address forms, the address buttons, subscription
+ * actions and return requests. Each change marks its form or row busy (`aria-busy`, `is-busy`), then sets
+ * `tether-form-state` to `saved` or `error` with Shopify's message in `tether-form-error`.
+ */
+import { attr, get, qsa, sel, setText } from '../dom.js';
+import {
+  saveAddress,
+  deleteAddress,
+  subscriptionAction,
+  requestReturn,
+  updateProfile,
+  pagesContext,
+} from './operations.js';
+import { renderAddresses, shownAddress } from './addresses-view.js';
+import { renderSubscriptions } from './subscriptions-view.js';
+import { renderOrder } from './order-page.js';
+import { TetherError } from '../client.js';
+/** @import { ReturnLine } from './operations.js' */
+/** @import { SubscriptionAction } from '../../server/src/shared/account-ops.js' */
+
+/** @type {readonly SubscriptionAction[]} */
+const SUBSCRIPTION_ACTIONS = ['pause', 'resume', 'skip', 'unskip', 'cancel'];
+
+/**
+ * @param {string | null} value
+ * @returns {value is SubscriptionAction}
+ */
+const isSubscriptionAction = (value) => SUBSCRIPTION_ACTIONS.some((action) => action === value);
+
+/**
+ * @param {Element} el
+ * @returns {el is HTMLInputElement}
+ */
+const isInput = (el) => el.tagName === 'INPUT';
+
+/**
+ * @param {Element} el
+ * @returns {el is HTMLFormElement}
+ */
+const isForm = (el) => el.tagName === 'FORM';
+
+/**
+ * @param {HTMLFormElement} form
+ * @returns {Record<string, string>} The form's text fields by name.
+ */
+function fieldsOf(form) {
+  /** @type {Record<string, string>} */
+  const fields = {};
+  for (const field of form.elements) {
+    if (!isInput(field) && field.tagName !== 'SELECT' && field.tagName !== 'TEXTAREA') continue;
+    const input = /** @type {HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement} */ (field);
+    if (!input.name || input.type === 'submit' || input.type === 'button' || input.type === 'checkbox') continue;
+    fields[input.name] = input.value;
+  }
+  return fields;
+}
+
+/**
+ * @param {unknown} error
+ * @returns {string} What to tell the customer: Shopify's own messages when it refused the input.
+ */
+function messageOf(error) {
+  const userErrors = error instanceof TetherError ? (error.userErrors ?? []) : [];
+  const message = userErrors.map((userError) => userError.message).join(' ');
+  if (message) return message;
+  const text = error instanceof Error && error.message ? error.message : 'Something went wrong';
+  return text.replace(/^Customer accounts: /, '');
+}
+
+/**
+ * Runs one change for `el`; a second one while it is on its way (Enter, a double click) is ignored. The failure is
+ * shown in `el` (`tether-form-error`), the place the customer looks.
+ *
+ * @param {HTMLElement} el
+ * @param {() => Promise<void>} change
+ * @returns {Promise<'saved' | 'error' | 'busy'>}
+ */
+async function act(el, change) {
+  if (el.getAttribute('aria-busy') === 'true') return 'busy';
+  el.classList.add('is-busy');
+  el.setAttribute('aria-busy', 'true');
+  el.setAttribute(attr('form-state'), 'pending');
+  const errorBoxes = qsa(el, sel('form-error'));
+  errorBoxes.forEach((box) => {
+    setText(box, '');
+  });
+  try {
+    await change();
+    el.setAttribute(attr('form-state'), 'saved');
+    return 'saved';
+  } catch (error) {
+    el.setAttribute(attr('form-state'), 'error');
+    errorBoxes.forEach((box) => {
+      setText(box, messageOf(error));
+    });
+    return 'error';
+  } finally {
+    el.classList.remove('is-busy');
+    el.removeAttribute('aria-busy');
+  }
+}
+
+/**
+ * @param {Element} button
+ * @returns {boolean} True when the button asks no `tether-confirm` question, or the visitor agreed.
+ */
+const confirmed = (button) => {
+  const question = get(button, 'confirm');
+  return !question || window.confirm(question);
+};
+
+/** @param {HTMLFormElement} form */
+const addressFormReset = (form) => {
+  form.reset();
+  delete form.dataset['tetherAddressId'];
+};
+
+/** @param {SubmitEvent} event */
+function onSubmit(event) {
+  const form = event.target;
+  if (!(form instanceof window.HTMLFormElement)) return;
+  if (form.matches(sel('profile-form'))) {
+    event.preventDefault();
+    void act(form, async () => {
+      await updateProfile(fieldsOf(form));
+      await pagesContext().bindCustomer(document);
+    });
+  } else if (form.matches(sel('address-form'))) {
+    event.preventDefault();
+    const id = form.dataset['tetherAddressId'];
+    const box = form.elements.namedItem('isDefault');
+    const isDefault = box instanceof window.HTMLInputElement && box.checked;
+    void act(form, async () => {
+      await saveAddress(fieldsOf(form), { id, isDefault });
+      addressFormReset(form);
+      await renderAddresses(document);
+    });
+  }
+}
+
+/**
+ * Fills the address form with a shown address, to edit it.
+ *
+ * @param {string} id
+ */
+function editAddress(id) {
+  const address = shownAddress(id);
+  const form = document.querySelector(sel('address-form'));
+  if (!address || !form || !isForm(form)) return;
+  form.dataset['tetherAddressId'] = address.id;
+  for (const field of form.elements) {
+    if (!isInput(field) && field.tagName !== 'SELECT' && field.tagName !== 'TEXTAREA') continue;
+    const input = /** @type {HTMLInputElement} */ (field);
+    if (input.name === 'isDefault') input.checked = address.isDefault;
+    else if (input.name && Object.hasOwn(address, input.name)) {
+      const value = Object.entries(address).find(([key]) => key === input.name)?.[1];
+      input.value = typeof value === 'string' ? value : '';
+    }
+  }
+  form.scrollIntoView({ block: 'nearest' });
+}
+
+/**
+ * @param {MouseEvent} event
+ * @param {Element} target
+ * @returns {boolean} True when the click was on an address button.
+ */
+function onAddressClick(event, target) {
+  const row = target.closest('[data-tether-address]');
+  const id = row instanceof window.HTMLElement ? row.dataset['tetherAddress'] : undefined;
+  if (target.closest(sel('address-new'))) {
+    const form = document.querySelector(sel('address-form'));
+    if (form && isForm(form)) addressFormReset(form);
+    return true;
+  }
+  if (!(row instanceof window.HTMLElement) || !id) return false;
+  const deleteButton = target.closest(sel('address-delete'));
+  if (deleteButton) {
+    event.preventDefault();
+    if (!confirmed(deleteButton)) return true;
+    void act(row, async () => {
+      await deleteAddress(id);
+      await renderAddresses(document);
+    });
+  } else if (target.closest(sel('address-default'))) {
+    event.preventDefault();
+    void act(row, async () => {
+      await saveAddress(null, { id, isDefault: true });
+      await renderAddresses(document);
+    });
+  } else if (target.closest(sel('address-edit'))) {
+    event.preventDefault();
+    editAddress(id);
+  } else {
+    return false;
+  }
+  return true;
+}
+
+/** @param {HTMLElement} button A `tether-subscription-action` button. */
+function onSubscriptionAction(button) {
+  const row = button.closest('[data-tether-subscription]');
+  const action = get(button, 'subscription-action');
+  const disabled = ('disabled' in button && button.disabled === true) || button.classList.contains('is-disabled');
+  if (!(row instanceof window.HTMLElement) || !isSubscriptionAction(action) || disabled || !confirmed(button)) return;
+  const id = row.dataset['tetherSubscription'] ?? '';
+  row.setAttribute(attr('subscription-state'), 'pending');
+  void act(row, async () => {
+    await subscriptionAction(id, action);
+    await renderSubscriptions(document);
+  }).then((outcome) => {
+    const state = outcome === 'error' ? 'error' : 'done';
+    // The re-render may have replaced the row: mark the one that shows this subscription now.
+    qsa(document, '[data-tether-subscription]')
+      .filter((candidate) => candidate === row || candidate.dataset['tetherSubscription'] === id)
+      .forEach((candidate) => {
+        candidate.setAttribute(attr('subscription-state'), state);
+      });
+  });
+}
+
+/**
+ * @param {HTMLElement} row A line row of the order page.
+ * @returns {ReturnLine}
+ */
+function returnLineOf(row) {
+  const quantity = row.querySelector(sel('return-quantity'));
+  const reason = row.querySelector(sel('return-reason'));
+  const note = row.querySelector(sel('return-note'));
+  /** @param {Element | null} field */
+  const valueOf = (field) => (field && 'value' in field && typeof field.value === 'string' ? field.value : '');
+  /** @type {ReturnLine} */
+  const line = { lineItemId: row.dataset['tetherLine'] ?? '', quantity: Number.parseInt(valueOf(quantity) || '0', 10) };
+  const reasonId = valueOf(reason);
+  if (reasonId) line.reasonId = reasonId;
+  const noteText = valueOf(note);
+  if (noteText) line.note = noteText;
+  return line;
+}
+
+/** @param {HTMLElement} button A `tether-order-return` button. */
+function onReturnRequest(button) {
+  const scope = button.closest(sel('order'));
+  if (!(scope instanceof window.HTMLElement)) return;
+  const orderId = scope.dataset['tetherOrderId'];
+  if (!orderId) return;
+  const lines = qsa(scope, '[data-tether-line]')
+    .map(returnLineOf)
+    .filter((line) => line.quantity > 0);
+  if (!lines.length || !confirmed(button)) return;
+  void act(scope, async () => {
+    await requestReturn(orderId, lines);
+    scope.dataset['tetherReturned'] = '1';
+    await renderOrder(scope);
+  });
+}
+
+/** @param {MouseEvent} event */
+function onClick(event) {
+  const target = event.target;
+  if (!(target instanceof window.Element)) return;
+  if (onAddressClick(event, target)) return;
+  const subscriptionButton = target.closest(sel('subscription-action'));
+  if (subscriptionButton instanceof window.HTMLElement) {
+    event.preventDefault();
+    onSubscriptionAction(subscriptionButton);
+    return;
+  }
+  const returnButton = target.closest(sel('order-return'));
+  if (returnButton instanceof window.HTMLElement) {
+    event.preventDefault();
+    onReturnRequest(returnButton);
+  }
+}
+
+/** Listens on the document once, for every account page rendered into it. */
+export function listenToPages() {
+  // Capture: before a router (Astro's ClientRouter) turns the submit into a navigation with the fields in the URL.
+  document.addEventListener('submit', onSubmit, true);
+  document.addEventListener('input', (event) => {
+    const target = event.target;
+    if (target instanceof window.HTMLElement && target.closest(sel('profile-form'))) {
+      target.dataset['tetherTouched'] = '1';
+    }
+  });
+  document.addEventListener('click', onClick);
+}