@occluze/tether 0.6.7 → 0.7.0

package/src/fragments.ts

@@ -0,0 +1,261 @@
+/**
+ * The GraphQL fragments of what Tether renders. They are built at call time because the list sizes and metafields come
+ * from the config; the browser passes its validated `cfg`, the server helpers their own. Operations put these after
+ * the operation, where `withContext` expects them.
+ */
+import { cfg } from './config.ts';
+import { toMetafieldIdentifier } from './config-sections.ts';
+import type { TetherConfig, MetafieldIdentifier } from './config.ts';
+import type { Money } from './shopify-values.ts';
+import type { StoreAccess } from './client.ts';
+
+export interface Image {
+  url: string;
+  altText: string | null;
+  width: number | null;
+  height: number | null;
+}
+
+/** An option value's swatch: a colour, an image, or both, as the merchant set them in the admin. */
+interface Swatch {
+  color: string | null;
+  image: { previewImage: Image | null } | null;
+}
+
+export type SellingPlanAdjustmentValue =
+  | { __typename: 'SellingPlanPercentagePriceAdjustment'; adjustmentPercentage: number }
+  | { __typename: 'SellingPlanFixedAmountPriceAdjustment'; adjustmentAmount: Money }
+  | { __typename: 'SellingPlanFixedPriceAdjustment'; price: Money };
+
+export interface SellingPlan {
+  id: string;
+  name: string;
+  description: string | null;
+  recurringDeliveries: boolean;
+  options: { name: string; value: string }[];
+  priceAdjustments: { orderCount: number | null; adjustmentValue: SellingPlanAdjustmentValue }[];
+}
+
+export interface SellingPlanGroup {
+  name: string;
+  appName: string | null;
+  options: { name: string; values: string[] }[];
+  sellingPlans: { nodes: SellingPlan[] };
+}
+
+/** A variant's price on one plan. */
+export interface SellingPlanAllocation {
+  sellingPlan: { id: string };
+  /** What the customer pays at checkout (more for a prepaid plan). */
+  checkoutChargeAmount: Money;
+  remainingBalanceChargeAmount: Money;
+  priceAdjustments: { price: Money; compareAtPrice: Money; perDeliveryPrice: Money; unitPrice: Money | null }[];
+}
+
+export interface ProductVariant {
+  id: string;
+  title: string;
+  availableForSale: boolean;
+  currentlyNotInStock: boolean;
+  /** Absent when the store's token can't read inventory. */
+  quantityAvailable?: number | null;
+  sku: string | null;
+  barcode: string | null;
+  selectedOptions: { name: string; value: string }[];
+  image: Image | null;
+  price: Money;
+  compareAtPrice: Money | null;
+  unitPrice: Money | null;
+  sellingPlanAllocations: { nodes: SellingPlanAllocation[] };
+}
+
+export interface Metafield {
+  namespace: string;
+  key: string;
+  type: string;
+  value: string;
+  /** A file reference's image. */
+  reference: { image?: Image } | null;
+}
+
+/** The fields of `fragment TetherProduct`. */
+export interface Product {
+  id: string;
+  handle: string;
+  title: string;
+  description: string;
+  descriptionHtml: string;
+  productType: string;
+  vendor: string;
+  tags: string[];
+  availableForSale: boolean;
+  publishedAt: string | null;
+  onlineStoreUrl: string | null;
+  requiresSellingPlan: boolean;
+  seo: { title: string | null; description: string | null };
+  featuredImage: Image | null;
+  images: { nodes: Image[] };
+  options: { name: string; optionValues: { name: string; swatch: Swatch | null }[] }[];
+  priceRange: { minVariantPrice: Money; maxVariantPrice: Money };
+  compareAtPriceRange: { minVariantPrice: Money; maxVariantPrice: Money };
+  /** Present when metafields are configured; `null` for one that isn't set. */
+  metafields?: (Metafield | null)[];
+  sellingPlanGroups: { nodes: SellingPlanGroup[] };
+  variants: { nodes: ProductVariant[] };
+}
+
+export type ProductFragmentConfig = Pick<
+  TetherConfig,
+  'imagesFirst' | 'variantsFirst' | 'sellingPlanGroupsFirst' | 'sellingPlansFirst' | 'metafields'
+>;
+
+const MONEY = 'amount currencyCode';
+/** What a token reads unless the store turned out to refuse more (client.ts). */
+const FULL_ACCESS: StoreAccess = { inventory: true };
+
+/** The stock field, for a token that may read inventory. */
+const inventoryField = (access: StoreAccess): string => (access.inventory ? 'quantityAvailable' : '');
+const IMAGE = 'url altText width height';
+
+/**
+ * The `metafields(identifiers:)` field. A fragment can't declare variables, so the identifiers are written into the
+ * text: only valid ones (`toMetafieldIdentifier`), each quoted as a string literal.
+ */
+function metafieldsField(metafields: ProductFragmentConfig['metafields']) {
+  const identifiers: MetafieldIdentifier[] = [];
+  for (const ref of metafields) {
+    const identifier = toMetafieldIdentifier(ref);
+    if (identifier) identifiers.push(identifier);
+  }
+  if (!identifiers.length) return '';
+  const list = identifiers
+    .map(({ namespace, key }) => `{namespace: ${JSON.stringify(namespace)}, key: ${JSON.stringify(key)}}`)
+    .join(', ');
+  return `metafields(identifiers: [${list}]) {
+    namespace key type value
+    reference { ... on MediaImage { image { ${IMAGE} } } }
+  }`;
+}
+
+const SELLING_PLAN_FIELDS = `
+  id name description recurringDeliveries
+  options { name value }
+  priceAdjustments {
+    orderCount
+    adjustmentValue {
+      __typename
+      ... on SellingPlanPercentagePriceAdjustment { adjustmentPercentage }
+      ... on SellingPlanFixedAmountPriceAdjustment { adjustmentAmount { ${MONEY} } }
+      ... on SellingPlanFixedPriceAdjustment { price { ${MONEY} } }
+    }
+  }`;
+
+const ALLOCATION_FIELDS = `
+  sellingPlan { id }
+  checkoutChargeAmount { ${MONEY} }
+  remainingBalanceChargeAmount { ${MONEY} }
+  priceAdjustments {
+    price { ${MONEY} }
+    compareAtPrice { ${MONEY} }
+    perDeliveryPrice { ${MONEY} }
+    unitPrice { ${MONEY} }
+  }`;
+
+/**
+ * @param o The list sizes and metafields.
+ * @param access What the token may read.
+ * @returns `fragment TetherProduct on Product`.
+ */
+export function productFragment(o: ProductFragmentConfig = cfg, access: StoreAccess = FULL_ACCESS): string {
+  return `
+fragment TetherProduct on Product {
+  id handle title description descriptionHtml productType vendor tags
+  availableForSale publishedAt onlineStoreUrl requiresSellingPlan
+  seo { title description }
+  featuredImage { ${IMAGE} }
+  images(first: ${o.imagesFirst}) { nodes { ${IMAGE} } }
+  options { name optionValues { name swatch { color image { previewImage { ${IMAGE} } } } } }
+  priceRange { minVariantPrice { ${MONEY} } maxVariantPrice { ${MONEY} } }
+  compareAtPriceRange { minVariantPrice { ${MONEY} } maxVariantPrice { ${MONEY} } }
+  ${metafieldsField(o.metafields)}
+  sellingPlanGroups(first: ${o.sellingPlanGroupsFirst}) {
+    nodes {
+      name appName
+      options { name values }
+      sellingPlans(first: ${o.sellingPlansFirst}) { nodes { ${SELLING_PLAN_FIELDS} } }
+    }
+  }
+  variants(first: ${o.variantsFirst}) {
+    nodes {
+      id title availableForSale currentlyNotInStock ${inventoryField(access)} sku barcode
+      selectedOptions { name value }
+      image { ${IMAGE} }
+      price { ${MONEY} }
+      compareAtPrice { ${MONEY} }
+      unitPrice { ${MONEY} }
+      sellingPlanAllocations(first: ${o.sellingPlansFirst}) { nodes { ${ALLOCATION_FIELDS} } }
+    }
+  }
+}`;
+}
+
+/**
+ * @param access What the token may read.
+ * @returns `fragment TetherCart on Cart`.
+ */
+export function cartFragment(access: StoreAccess = FULL_ACCESS): string {
+  return `
+fragment TetherCart on Cart {
+  id checkoutUrl totalQuantity note createdAt updatedAt
+  attributes { key value }
+  buyerIdentity { countryCode email }
+  discountCodes { code applicable }
+  cost {
+    subtotalAmount { ${MONEY} }
+    totalAmount { ${MONEY} }
+    checkoutChargeAmount { ${MONEY} }
+  }
+  lines(first: 100) {
+    nodes {
+      id quantity
+      attributes { key value }
+      cost {
+        totalAmount { ${MONEY} }
+        subtotalAmount { ${MONEY} }
+        amountPerQuantity { ${MONEY} }
+        compareAtAmountPerQuantity { ${MONEY} }
+      }
+      discountAllocations { discountedAmount { ${MONEY} } }
+      sellingPlanAllocation {
+        sellingPlan { id name description recurringDeliveries options { name value } }
+        checkoutChargeAmount { ${MONEY} }
+        priceAdjustments { price { ${MONEY} } compareAtPrice { ${MONEY} } perDeliveryPrice { ${MONEY} } }
+      }
+      merchandise {
+        ... on ProductVariant {
+          id title sku availableForSale requiresShipping ${inventoryField(access)}
+          image { ${IMAGE} }
+          price { ${MONEY} }
+          compareAtPrice { ${MONEY} }
+          selectedOptions { name value }
+          product { id title handle vendor featuredImage { ${IMAGE} } }
+        }
+      }
+      ... on ComponentizableCartLine {
+        lineComponents {
+          id quantity
+          merchandise { ... on ProductVariant { id title product { title handle } } }
+        }
+      }
+    }
+  }
+}`;
+}
+
+/** The collection fields Tether renders, for inside a `collection { }` selection. */
+export function collectionFields(): string {
+  return `
+  id handle title description descriptionHtml
+  image { ${IMAGE} }
+  seo { title description }`;
+}

package/src/globals.d.ts

@@ -0,0 +1,15 @@
+/**
+ * What Tether reads from and sets on `window`, for sites that use the `<script>` build or `window.Tether`. Only the
+ * published declarations carry it (scripts/build.ts adds it to the generated `index.d.ts`): the source reads these
+ * names as unknown and validates them, so they stay out of its own program.
+ */
+import type { Tether, TetherConfig } from './index.ts';
+
+declare global {
+  interface Window {
+    Tether: Tether;
+    TETHER_CONFIG?: TetherConfig;
+    TETHER_COUNTRY?: string;
+    TETHER_LANGUAGE?: string;
+  }
+}

package/src/images.ts

@@ -0,0 +1,91 @@
+/**
+ * Shopify images on the page: sized through the CDN's URL parameters, written to an `<img>` or as a CSS background,
+ * and never downloaded twice when the server already rendered the same image.
+ */
+import { attr } from './markup.ts';
+
+/** Shopify CDN parameters. */
+export interface ImageSize {
+  width?: string | number | null;
+  height?: string | number | null;
+  /** `center`, `top`, `bottom`, `left` or `right`; only applies with a width or height. */
+  crop?: string | null;
+}
+
+/**
+ * Shopify CDN image at a size: `imageUrl(url, { width: 800 })`. Use the same width as the element's max-width
+ * attribute, so the browser script keeps the image instead of loading it again.
+ *
+ * @returns The sized URL; `url` itself when it is empty or not absolute.
+ */
+export function imageUrl<Url extends string | null | undefined>(
+  url: Url,
+  { width, height, crop }: ImageSize = {},
+): Url {
+  if (!url) return url;
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch (error) {
+    // A relative or malformed URL has no CDN parameters to set: it is used as written.
+    if (error instanceof TypeError) return url;
+    throw error;
+  }
+  if (width) parsed.searchParams.set('width', String(width));
+  if (height) parsed.searchParams.set('height', String(height));
+  if (crop) parsed.searchParams.set('crop', crop);
+  // `url` is a non-empty string here, so `Url` is a string type.
+  return parsed.toString() as Url;
+}
+
+/** @returns `name` as Webflow's custom attribute, or in valid HTML as `<prefix>-name` / `data-name`. */
+function sizeAttribute(el: Element, name: string): string | null {
+  return el.getAttribute(name) ?? el.getAttribute(attr(name)) ?? el.getAttribute(`data-${name}`);
+}
+
+/** @param el The element whose max-width / max-height / crop attributes size the image. */
+export function cdnUrl<Url extends string | null | undefined>(url: Url, el: Element | null | undefined): Url {
+  if (!url || !el) return url;
+  const width = sizeAttribute(el, 'max-width');
+  const height = sizeAttribute(el, 'max-height');
+  return imageUrl(url, { width, height, crop: width || height ? sizeAttribute(el, 'crop') : null });
+}
+
+/** @returns The URL without its query (the size parameters). */
+const withoutQuery = (url: string) => url.replace(/\?.*$/, '');
+
+/** @returns True for the same image at any size parameters: the server-rendered one is kept. */
+export function sameImage(a: string | null | undefined, b: string | null | undefined): boolean {
+  if (!a || !b) return false;
+  return withoutQuery(a) === withoutQuery(b);
+}
+
+/**
+ * A CSS `url()` for an image URL from Shopify. Characters that would end the string are escaped, so the URL can't
+ * add declarations; only http(s), relative and data:image URLs are used.
+ */
+function cssUrl(url: string): string {
+  const hasScheme = /^\s*[a-z][a-z0-9+.-]*:/i.test(url);
+  if (hasScheme && !/^\s*(https?:|data:image\/)/i.test(url)) return 'none';
+  const escaped = url.replace(/["\\\n\r\f]/g, (char) => `\\${char.charCodeAt(0).toString(16)} `);
+  return `url("${escaped}")`;
+}
+
+/** Shows `url` in `el`: as the `src` of an `<img>` (lazy unless it says otherwise), else as its background image. */
+export function setImage(el: HTMLElement, url: string | null | undefined, alt?: string | null): void {
+  if (!url) return;
+  const src = cdnUrl(url, el);
+  if (el.tagName !== 'IMG') {
+    el.style.backgroundImage = cssUrl(src);
+    return;
+  }
+  if (sameImage(el.getAttribute('src'), src)) {
+    if (alt != null && !el.getAttribute('alt')) el.setAttribute('alt', alt);
+    return;
+  }
+  el.removeAttribute('srcset');
+  el.removeAttribute('sizes');
+  el.setAttribute('src', src);
+  if (alt != null) el.setAttribute('alt', alt);
+  if (!el.getAttribute('loading')) el.setAttribute('loading', 'lazy');
+}