@occluze/tether 0.6.7 → 0.7.0

package/src/cart/checkout.ts

@@ -0,0 +1,101 @@
+/**
+ * Sending the visitor to Shopify's checkout. The URL comes from Shopify at click time, because the cart's checkout URL
+ * changes with its market and customer; the account part resolves a logged-in customer's own (`setCheckoutResolver`).
+ */
+import { cfg, reportError } from '../config.ts';
+import { TetherError } from '../client.ts';
+import { isHttpsUrl } from '../shopify-values.ts';
+import { emit } from '../dom.ts';
+import { fetchCheckoutUrl } from './mutations.ts';
+import { currentCart, savedCartId } from './store.ts';
+import type { CheckoutTarget } from '../config.ts';
+
+type CheckoutUrlAnswer = { kind: 'url'; url: string | null } | { kind: 'failed'; error: unknown };
+
+/**
+ * The logged-in customer's checkout URL for the cart; `null` when nobody is logged in, so the cart's own checkout URL
+ * is used.
+ */
+type CheckoutResolver = () => Promise<string | null>;
+
+let resolveAccountCheckout: CheckoutResolver | null = null;
+
+/** Sets the account part's checkout URL, or clears it with `null`. A URL it answers opens checkout logged in. */
+export function setCheckoutResolver(resolver: CheckoutResolver | null): void {
+  resolveAccountCheckout = resolver;
+}
+
+/**
+ * @returns Shopify's answer as a value, so the request can run alongside the account's and its failure is read only
+ *   when its URL is the one used.
+ */
+const askCheckoutUrl = (cartId: string): Promise<CheckoutUrlAnswer> =>
+  fetchCheckoutUrl(cartId).then(
+    (url) => ({ kind: 'url', url }),
+    (error: unknown) => ({ kind: 'failed', error }),
+  );
+
+/**
+ * @returns The logged-in customer's checkout URL. When the account can't give one, the failure is reported and the
+ *   cart's own checkout URL is used, which still checks out (without the login).
+ */
+async function accountCheckoutUrl(): Promise<string | null> {
+  if (!resolveAccountCheckout) return null;
+  try {
+    const url = await resolveAccountCheckout();
+    // Shopify's checkout shows the customer as logged in only with this parameter.
+    return url && `${url}${url.includes('?') ? '&' : '?'}logged_in=true`;
+  } catch (error) {
+    reportError(error, 'account checkout');
+    return null;
+  }
+}
+
+/** @throws {TetherError} `ERROR` without a checkout URL (the cart is empty or Shopify no longer has it). */
+async function checkoutUrl(cartId: string): Promise<string> {
+  const cartAnswer = askCheckoutUrl(cartId);
+  const accountUrl = await accountCheckoutUrl();
+  if (accountUrl) return accountUrl;
+  const answer = await cartAnswer;
+  if (answer.kind === 'failed') throw answer.error;
+  if (!answer.url) throw new TetherError('No checkoutUrl (cart empty or expired)');
+  return answer.url;
+}
+
+/**
+ * A new tab's `opener` gives the checkout page a handle on this one; a browser that doesn't let a script clear it
+ * leaves the tab as it opened.
+ */
+function detachOpenerIfAllowed(tab: Window) {
+  try {
+    tab.opener = null;
+  } catch {
+    // The browser keeps `opener` read-only: see the function's comment.
+  }
+}
+
+/**
+ * Goes to Shopify's checkout. With `_blank` the tab opens inside the click (Safari blocks `window.open` after an
+ * await) and gets its URL once there is one.
+ *
+ * @returns The checkout URL, `null` with nothing to check out or after a reported failure.
+ */
+export async function checkout(target: CheckoutTarget = cfg.checkoutTarget): Promise<string | null> {
+  const cartId = savedCartId();
+  const cart = currentCart();
+  if (!cartId || (cart && !cart.totalQuantity)) return null;
+  const tab = target === '_blank' ? window.open('', '_blank') : null;
+  if (tab) detachOpenerIfAllowed(tab);
+  try {
+    const url = await checkoutUrl(cartId);
+    if (!isHttpsUrl(url)) throw new TetherError('The checkout URL is not https: not opened');
+    emit('checkout', { url, cart: currentCart() });
+    if (tab && !tab.closed) tab.location.href = url;
+    else window.location.href = url;
+    return url;
+  } catch (error) {
+    tab?.close();
+    reportError(error, 'checkout failed');
+    return null;
+  }
+}

package/src/cart/drawer.ts

@@ -0,0 +1,125 @@
+/**
+ * The cart drawer: every `[tether-cart-drawer]` on the page opens and closes together, as a modal dialog. Focus moves
+ * into the open cart, Tab stays inside it and focus returns on close (`cartFocus`). A page without a drawer (a cart
+ * built in React, Svelte or Vue) still has an open state, for `Tether.cart.subscribe`.
+ */
+import { cfg } from '../config.ts';
+import { sel, get, qsa, emit } from '../dom.ts';
+
+const FOCUSABLE =
+  'a[href],button:not([disabled]),input:not([disabled]),select:not([disabled]),textarea:not([disabled]),[tabindex]:not([tabindex="-1"])';
+
+/** Long enough for the drawer's open transition to make its content visible: hidden elements can't take focus. */
+const FOCUS_AFTER_OPEN_MS = 60;
+
+/** The open state of a page without a drawer element. */
+let openWithoutDrawer = false;
+
+/** Where focus was before the cart opened. */
+let returnFocus: HTMLElement | null = null;
+
+const isFocusable = (el: Element | null): el is HTMLElement => el !== null && 'focus' in el;
+
+/** @returns The visible focusable elements inside `drawer`, in document order. */
+const focusables = (drawer: ParentNode): HTMLElement[] =>
+  qsa(drawer, FOCUSABLE).filter((el) => el.offsetParent !== null || el === document.activeElement);
+
+/** Every cart drawer on the page. */
+export const drawers = (): HTMLElement[] => qsa(document, sel('cart-drawer'));
+
+const isOpenDrawer = (drawer: HTMLElement) => drawer.classList.contains(cfg.cartDrawerOpenClass);
+
+/** True while a drawer, or the drawer-less cart, is open. */
+export function isOpen(): boolean {
+  const all = drawers();
+  return all.length ? all.some(isOpenDrawer) : openWithoutDrawer;
+}
+
+/**
+ * `aria-expanded` on the open buttons, and dialog semantics on the drawers unless their markup has its own. A closed
+ * drawer is hidden from screen readers and, with `cartFocus`, out of the Tab order (inert), like a closed dialog.
+ */
+export function syncDrawerAria(open: boolean): void {
+  qsa(document, sel('cart-open')).forEach((button) => {
+    button.setAttribute('aria-expanded', String(open));
+  });
+  drawers().forEach((drawer) => {
+    if (!drawer.hasAttribute('role')) drawer.setAttribute('role', 'dialog');
+    if (!drawer.hasAttribute('aria-label') && !drawer.hasAttribute('aria-labelledby')) {
+      drawer.setAttribute('aria-label', get(drawer, 'cart-label') || 'Cart');
+    }
+    drawer.setAttribute('aria-modal', String(open));
+    if (isOpenDrawer(drawer)) return;
+    drawer.setAttribute('aria-hidden', 'true');
+    if (cfg.cartFocus) drawer.inert = true;
+  });
+}
+
+function focusInto(drawer: HTMLElement) {
+  const target = focusables(drawer)[0] ?? drawer;
+  if (target === drawer && !drawer.hasAttribute('tabindex')) drawer.tabIndex = -1;
+  target.focus({ preventScroll: true });
+}
+
+/** Opens every drawer except `tether-cart-drawer="manual"` ones, which the site opens itself. */
+export function openCart(): void {
+  if (isOpen()) return;
+  openWithoutDrawer = true;
+  const opened = drawers().filter((drawer) => get(drawer, 'cart-drawer') !== 'manual');
+  opened.forEach((drawer) => {
+    drawer.inert = false;
+    drawer.classList.add(cfg.cartDrawerOpenClass);
+    drawer.setAttribute('aria-hidden', 'false');
+  });
+  syncDrawerAria(true);
+  const [first] = opened;
+  if (cfg.cartFocus && first) {
+    returnFocus = isFocusable(document.activeElement) ? document.activeElement : null;
+    setTimeout(() => {
+      focusInto(first);
+    }, FOCUS_AFTER_OPEN_MS);
+  }
+  cfg.onCartOpen?.(opened);
+  emit('cart-toggled', { open: true });
+}
+
+export function closeCart(): void {
+  if (!isOpen()) return;
+  openWithoutDrawer = false;
+  const all = drawers();
+  const hadFocus = all.some((drawer) => drawer.contains(document.activeElement));
+  all.forEach((drawer) => {
+    drawer.classList.remove(cfg.cartDrawerOpenClass);
+    drawer.setAttribute('aria-hidden', 'true');
+    if (cfg.cartFocus) drawer.inert = true;
+  });
+  syncDrawerAria(false);
+  if (hadFocus && returnFocus?.isConnected) returnFocus.focus({ preventScroll: true });
+  returnFocus = null;
+  cfg.onCartClose?.(all);
+  emit('cart-toggled', { open: false });
+}
+
+export function toggleCart(): void {
+  if (isOpen()) closeCart();
+  else openCart();
+}
+
+/**
+ * Keeps Tab inside the open drawer (`cartFocus`): from the last focusable element it wraps to the first, with Shift
+ * from the first to the last, and from outside the drawer it goes in. For a document `keydown` listener.
+ */
+export function trapFocus(event: KeyboardEvent): void {
+  if (event.key !== 'Tab' || !cfg.cartFocus || !isOpen()) return;
+  const drawer = drawers().find(isOpenDrawer);
+  if (!drawer) return;
+  const inside = focusables(drawer);
+  const first = inside[0];
+  const last = inside.at(-1);
+  if (!first || !last) return;
+  const active = document.activeElement;
+  const leaving = event.shiftKey ? active === first : active === last;
+  if (drawer.contains(active) && !leaving) return;
+  event.preventDefault();
+  (event.shiftKey ? last : first).focus();
+}

package/src/cart/mutations.ts

@@ -0,0 +1,237 @@
+/**
+ * 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.ts';
+import { gql, orNull, shaped, unwrap, TetherError } from '../client.ts';
+import { cartFragment } from '../fragments.ts';
+import { GID } from '../selling-plans.ts';
+import { toAttributes } from '../dom.ts';
+import { CART } from './cart-shape.ts';
+import { savedCartId, forgetSavedCart, setWarnings } from './store.ts';
+import type { CartWarning } from '../config.ts';
+import type { QueryText, UserError } from '../client.ts';
+import type { AttributeValue } from '../dom.ts';
+import type { ShopifyCart, Attribute } from './store.ts';
+
+export type Attributes = Record<string, AttributeValue> | { key: string | number; value?: AttributeValue }[];
+
+/** A line to add, in any of the shapes `Cart.add` takes. */
+export interface LineSpec {
+  variantId?: string | number;
+  merchandiseId?: string | number;
+  id?: string | number;
+  quantity?: number | string;
+  sellingPlanId?: string | number | null;
+  sellingPlan?: string | number | null;
+  attributes?: Attributes | null;
+}
+
+/** Shopify's `CartLineInput`. */
+export interface CartLineInput {
+  merchandiseId: string;
+  quantity: number;
+  sellingPlanId?: string;
+  attributes?: Attribute[];
+}
+
+/** What every cart mutation answers. Its lists are read with a fallback, so `isPayloadOf` checks the cart alone. */
+interface CartPayload {
+  cart: ShopifyCart | null;
+  userErrors?: UserError[] | null;
+  warnings?: CartWarning[];
+}
+
+/**
+ * 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;
+
+/** @returns A check of a mutation's answer: a `null` payload (which `unwrap` refuses), or one with a cart or `null`. */
+const isPayloadOf = (name: string) =>
+  shaped<Record<string, CartPayload | null>>({ [name]: orNull({ cart: orNull(CART) }) });
+
+/**
+ * @returns 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: unknown): boolean {
+  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 input A variant id, or a line.
+ * @param quantity For a variant id.
+ * @param options For a variant id.
+ * @throws {TetherError} `ERROR` without a variant id.
+ */
+export function toLineInput(
+  input: string | number | LineSpec | null | undefined,
+  quantity = 1,
+  options: Omit<LineSpec, 'variantId' | 'quantity'> = {},
+): CartLineInput {
+  const spec: LineSpec =
+    typeof input === 'object' && input !== null
+      ? input
+      : { ...options, quantity, ...(input === null || input === undefined ? {} : { variantId: input }) };
+  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);
+  const line: CartLineInput = { 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 name The mutation, which is also its payload's field.
+ * @param args The operation's variable definitions.
+ * @param inner The mutation field's arguments.
+ */
+function mutationText(name: string, args: string, inner: string): QueryText {
+  return (access) => `mutation Tether_${name}(${args}) {
+  ${name}(${inner}) { cart { ...TetherCart } userErrors { field message } warnings { code message target } }
+}
+${cartFragment(access)}`;
+}
+
+/**
+ * @returns 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: string,
+  args: string,
+  inner: string,
+  variables: Record<string, unknown>,
+): Promise<ShopifyCart | null> {
+  const data = await gql(mutationText(name, args, inner), variables, isPayloadOf(name));
+  const payload = unwrap(data[name], name);
+  setWarnings(payload.warnings ?? []);
+  return payload.cart;
+}
+
+/**
+ * A new cart in the visitor's market.
+ *
+ * @param input More of Shopify's `CartInput`, e.g. the first lines.
+ */
+function createCart(input: Record<string, unknown>): Promise<ShopifyCart | null> {
+  const withIdentity = cfg.country ? { buyerIdentity: { countryCode: cfg.country }, ...input } : input;
+  return send('cartCreate', '$input: CartInput!', 'input: $input', { input: withIdentity });
+}
+
+/** A mutation on the saved cart. */
+interface CartMutation {
+  /** The mutation, e.g. `cartLinesAdd`. */
+  name: string;
+  /** Its variable definitions besides `$cartId`. */
+  args: string;
+  /** Its arguments besides `cartId`. */
+  inner: string;
+  variables: Record<string, unknown>;
+  /**
+   * 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.
+   */
+  createInput: Record<string, unknown> | null;
+}
+
+/**
+ * Runs a mutation on the saved cart, or creates a cart from `createInput` when there is none to change.
+ *
+ * @returns 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,
+}: CartMutation): Promise<ShopifyCart | null> {
+  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);
+  }
+}
+
+/** @returns The cart, `null` when Shopify doesn't have it (expired or checked out). */
+export async function fetchCart(id: string): Promise<ShopifyCart | null> {
+  const data = await gql(
+    (access) => `query TetherCart($id: ID!) { cart(id: $id) { ...TetherCart } }\n${cartFragment(access)}`,
+    { id },
+    shaped<{ cart: ShopifyCart | null }>({ cart: orNull(CART) }),
+  );
+  return data.cart;
+}
+
+/** @returns The cart's current checkout URL, `null` when Shopify doesn't have the cart. */
+export async function fetchCheckoutUrl(id: string): Promise<string | null> {
+  const data = await gql(
+    'query TetherCheckout($id: ID!) { cart(id: $id) { checkoutUrl } }',
+    { id },
+    shaped<{ cart: { checkoutUrl: string } | null }>({ cart: orNull({ checkoutUrl: 'string' }) }),
+  );
+  return data.cart?.checkoutUrl ?? null;
+}
+
+/** A change to one line, for `updateLine`. */
+export interface LinePatch {
+  /** 0 or less removes the line. */
+  quantity?: number;
+  /** `null` switches the line back to one-time purchase. */
+  sellingPlanId?: string | number | null;
+  attributes?: Attributes;
+  merchandiseId?: string | number;
+  variantId?: string | number;
+}
+
+/** @returns Shopify's `CartLineUpdateInput`. */
+export function toLineUpdate(lineId: string, patch: number | LinePatch): Record<string, unknown> {
+  const change: LinePatch = typeof patch === 'number' ? { quantity: patch } : patch;
+  const line: Record<string, unknown> = { 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;
+}
+
+export const updateLines = (lines: Record<string, unknown>[]): Promise<ShopifyCart | null> =>
+  mutateCart({
+    name: 'cartLinesUpdate',
+    args: '$lines: [CartLineUpdateInput!]!',
+    inner: 'lines: $lines',
+    variables: { lines },
+    createInput: null,
+  });
+
+export const removeLines = (lineIds: string[]): Promise<ShopifyCart | null> =>
+  mutateCart({
+    name: 'cartLinesRemove',
+    args: '$lineIds: [ID!]!',
+    inner: 'lineIds: $lineIds',
+    variables: { lineIds },
+    createInput: null,
+  });
+
+/** @returns The cart once `lineId` has `target` (0 removes it). */
+export const setLineQuantity = (lineId: string, target: number): Promise<ShopifyCart | null> =>
+  target > 0 ? updateLines([{ id: lineId, quantity: target }]) : removeLines([lineId]);