@occluze/tether 0.6.8 → 0.7.0

package/src/{extras.js → extras.ts}

@@ -3,26 +3,27 @@
  * first change in another tab) and shareable variant links (on the first variant change, with `variantUrl` or
  * `tether-variant-url`).
  */
-import { cfg, warn, reportError } from './config.js';
-import { sel, get, has, qsa, emit, parseJSONAttr, toAttributes } from './dom.js';
-import { scopes } from './product.js';
-import { Cart } from './cart.js';
-/** @import { ShopifyCart } from './cart/store.js' */
+import { cfg, warn, reportError } from './config.ts';
+import { sel, get, has, qsa, emit, parseJSONAttr, attributesFromJson } from './dom.ts';
+import { scopes } from './product.ts';
+import { Cart } from './cart.ts';
+import { isRecord } from '../server/src/shared/json.ts';
+import type { ShopifyCart } from './cart/store.ts';
 
-/** @typedef {{ country: string, language: string | null, locale: string | undefined }} StoredMarket */
-/**
- * @typedef {(country: string, options: { language: string | null, locale: string | undefined, remember: boolean })
- *   => Promise<unknown>} SetCountry
- */
+interface StoredMarket {
+  country: string;
+  language: string | null;
+  locale: string | undefined;
+}
 
-/**
- * @param {Element} group
- * @param {string | null} name The group's `tether-group` value.
- */
-function groupAttributes(group, name) {
-  const extra = toAttributes(
-    /** @type {Parameters<typeof toAttributes>[0]} */ (parseJSONAttr(group, 'line-attributes')),
-  );
+type SetCountry = (
+  country: string,
+  options: { language: string | null; locale: string | undefined; remember: boolean },
+) => Promise<unknown>;
+
+/** @param name The group's `tether-group` value. */
+function groupAttributes(group: Element, name: string | null) {
+  const extra = attributesFromJson(parseJSONAttr(group, 'line-attributes'));
   return name ? [{ key: '_group', value: name }, ...extra] : extra;
 }
 
@@ -30,10 +31,9 @@ function groupAttributes(group, name) {
  * `[tether-group]` with `[tether-group-add]`: adds every product scope inside the group in one request, for bundles,
  * build-a-box and "complete the set". The lines get the attribute `_group` and the group's `tether-line-attributes`.
  *
- * @param {Element} button
- * @returns {Promise<ShopifyCart | null>} The cart, `null` with nothing to add or after a reported failure.
+ * @returns The cart, `null` with nothing to add or after a reported failure.
  */
-export async function addGroup(button) {
+export async function addGroup(button: Element): Promise<ShopifyCart | null> {
   const group = button.closest(sel('group'));
   if (!group) return null;
   const name = get(group, 'group');
@@ -58,22 +58,16 @@ export async function addGroup(button) {
   }
 }
 
-/**
- * Another tab writes the market as JSON; a value that isn't (written by something else under the key) is skipped.
- *
- * @param {string} text
- * @returns {StoredMarket | null}
- */
-function parseStoredMarket(text) {
-  /** @type {unknown} */
-  let value;
+/** Another tab writes the market as JSON; a value that isn't (written by something else under the key) is skipped. */
+function parseStoredMarket(text: string): StoredMarket | null {
+  let value: unknown;
   try {
     value = JSON.parse(text);
   } catch {
     return null;
   }
-  if (typeof value !== 'object' || value === null) return null;
-  const { country, language, locale } = /** @type {Record<string, unknown>} */ (value);
+  if (!isRecord(value)) return null;
+  const { country, language, locale } = value;
   if (typeof country !== 'string' || !country) return null;
   return {
     country,
@@ -82,41 +76,36 @@ function parseStoredMarket(text) {
   };
 }
 
-/**
- * Another tab changed the cart (it is loaded again here) or the visitor's market (this tab follows it).
- *
- * @param {StorageEvent} event
- */
-export function onStorage(event) {
+/** Another tab changed the cart (it is loaded again here) or the visitor's market (this tab follows it). */
+export function onStorage(event: StorageEvent): void {
   if (event.key === cfg.storageKey || event.key === `${cfg.storageKey}:seen`) {
-    Cart.init().catch((/** @type {unknown} */ error) => {
+    Cart.init().catch((error: unknown) => {
       reportError(error, 'cart from another tab');
     });
     return;
   }
   if (event.key !== `${cfg.prefix}:market:${cfg.domain}` || !event.newValue) return;
   const market = parseStoredMarket(event.newValue);
-  const { Tether } = /** @type {Window & { Tether?: { setCountry: SetCountry } }} */ (window);
-  if (!market || !Tether) return;
+  // The core's `setCountry` takes the `null` language and `undefined` locale stored here, which the public type of
+  // `window.Tether` leaves out.
+  const tether = Reflect.get(window, 'Tether') as { setCountry: SetCountry } | undefined;
+  if (!market || !tether) return;
   const options = { language: market.language, locale: market.locale, remember: false };
-  Tether.setCountry(market.country, options).catch((/** @type {unknown} */ error) => {
+  tether.setCountry(market.country, options).catch((error: unknown) => {
     reportError(error, 'market from another tab');
   });
 }
 
-/** @type {WeakMap<Element, string>} Scope root → its last variant and plan, so the first render doesn't write. */
-const urlKeys = new WeakMap();
+/** Scope root → its last variant and plan, so the first render doesn't write. */
+const urlKeys = new WeakMap<Element, string>();
 
-/** @param {string} gid */
-const numericId = (gid) => gid.split('/').pop() ?? gid;
+const numericId = (gid: string) => gid.split('/').pop() ?? gid;
 
 /**
  * Safari throws a SecurityError past 100 history changes in 10 seconds; the address then keeps the previous choice
  * until the next one.
- *
- * @param {URL} url
  */
-function replaceUrlIfAllowed(url) {
+function replaceUrlIfAllowed(url: URL) {
   try {
     window.history.replaceState(window.history.state, '', url);
   } catch {
@@ -127,10 +116,12 @@ function replaceUrlIfAllowed(url) {
 /**
  * `?variant=` (and `selling_plan=`) follow the visitor's choice.
  *
- * @param {Element} root The product scope's root.
- * @param {{ variant: { id: string }, sellingPlanId: string | null | undefined }} choice
+ * @param root The product scope's root.
  */
-export function writeVariantUrl(root, { variant, sellingPlanId }) {
+export function writeVariantUrl(
+  root: Element,
+  { variant, sellingPlanId }: { variant: { id: string }; sellingPlanId: string | null | undefined },
+): void {
   const key = `${variant.id}|${sellingPlanId ?? ''}`;
   const before = urlKeys.get(root);
   urlKeys.set(root, key);

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.js → images.ts}

@@ -2,25 +2,26 @@
  * 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.js';
+import { attr } from './markup.ts';
 
-/**
- * @typedef {object} ImageSize Shopify CDN parameters.
- * @property {string | number | null} [width]
- * @property {string | number | null} [height]
- * @property {string | null} [crop] `center`, `top`, `bottom`, `left` or `right`; only applies with a width or height.
- */
+/** 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.
  *
- * @template {string | null | undefined} Url
- * @param {Url} url
- * @param {ImageSize} [size]
- * @returns {Url} The sized URL; `url` itself when it is empty or not absolute.
+ * @returns The sized URL; `url` itself when it is empty or not absolute.
  */
-export function imageUrl(url, { width, height, crop } = {}) {
+export function imageUrl<Url extends string | null | undefined>(
+  url: Url,
+  { width, height, crop }: ImageSize = {},
+): Url {
   if (!url) return url;
   let parsed;
   try {
@@ -33,59 +34,45 @@ export function imageUrl(url, { width, height, crop } = {}) {
   if (width) parsed.searchParams.set('width', String(width));
   if (height) parsed.searchParams.set('height', String(height));
   if (crop) parsed.searchParams.set('crop', crop);
-  return /** @type {Url} */ (parsed.toString());
+  // `url` is a non-empty string here, so `Url` is a string type.
+  return parsed.toString() as Url;
 }
 
-/**
- * @param {Element} el
- * @param {string} name
- * @returns {string | null} `name` as Webflow's custom attribute, or in valid HTML as `<prefix>-name` / `data-name`.
- */
-function sizeAttribute(el, name) {
+/** @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}`);
 }
 
-/**
- * @template {string | null | undefined} Url
- * @param {Url} url
- * @param {Element | null | undefined} el The element whose max-width / max-height / crop attributes size the image.
- * @returns {Url}
- */
-export function cdnUrl(url, el) {
+/** @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 });
 }
 
-/**
- * @param {string | null | undefined} a
- * @param {string | null | undefined} b
- * @returns {boolean} True for the same image at any size parameters: the server-rendered one is kept.
- */
-export const sameImage = (a, b) => Boolean(a && b) && a?.split('?')[0] === b?.split('?')[0];
+/** @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.
- *
- * @param {string} url
  */
-function cssUrl(url) {
+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.
- *
- * @param {HTMLElement} el
- * @param {string | null | undefined} url
- * @param {string | null} [alt]
- */
-export function setImage(el, url, alt) {
+/** 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') {