@occluze/tether 0.6.8 → 0.7.1

package/src/index.js

@@ -1,353 +0,0 @@
-/**
- * Tether's entry: `window.Tether`, `init()`, `mount()` and the start of the plain `<script>` setup.
- *
- *   <script>window.TETHER_CONFIG = { domain: 'x.myshopify.com', token: '...' }</script>
- *   <script src="tether.min.js" defer></script>
- *
- * With page transitions (Barba, Swup): set `autoMount: false`, call `Tether.init()` once and
- * `Tether.mount(container)` after every page enter.
- */
-import { cfg, configure, isConfigured, log, warn, reportError } from './config.js';
-import { gql, TetherError, withContext } from './client.js';
-import { Cart } from './cart.js';
-import { scopes } from './product.js';
-import { ListScope, listSelector } from './collection.js';
-import {
-  getProduct,
-  getProducts,
-  getRecommendations,
-  clearProductCache,
-  primeProduct,
-  normalizeProductKey,
-} from './loader.js';
-import * as plans from './selling-plans.js';
-import { resolveProductKey } from './status.js';
-import { sel, emit, formatMoney, imageUrl } from './dom.js';
-import { loadPart, coreModules } from './lazy.js';
-import {
-  mountedLists,
-  liveLists,
-  pruneLive,
-  within,
-  mountProduct,
-  hydrateFromPage,
-  settleMarket,
-  trackMarket,
-} from './mounting.js';
-import { applyStartMarket, setCountry } from './page-market.js';
-import { accountApi, mountAccountIfUsed } from './account-api.js';
-import { bindCartControls } from './controls/cart-controls.js';
-import { bindDiscountControls } from './controls/discount.js';
-import { addGroup, bindExtrasControls } from './controls/extras.js';
-import { bindNavigation, rememberDocumentMount } from './controls/navigation.js';
-/** @import { TetherConfig, TetherOptions, MarketsConfig } from './config.js' */
-/** @import { ShopifyCart } from './cart/store.js' */
-/** @import { ProductScope } from './product.js' */
-/** @import { DiagnoseOptions } from './diagnose.js' */
-
-export { addGroup, setCountry };
-
-export const VERSION = '0.6.8';
-
-/** The events the analytics part reports, buffered from `init()` until the part has loaded. */
-const ANALYTICS_EVENTS = ['product-ready', 'list-ready', 'cart-updated', 'cart-toggled', 'checkout', 'search'];
-
-/** Milliseconds `observe` waits after the last added node, so a burst of additions mounts once. */
-const OBSERVE_DEBOUNCE_MS = 50;
-
-/**
- * @typedef {object} TetherGlobals What the page sets on `window` for Tether, and `window.Tether` itself.
- * @property {TetherOptions} [TETHER_CONFIG] The site's config; `configure()` validates it.
- * @property {string} [TETHER_INTEGRATION] Set by a framework integration (Astro) that starts Tether itself.
- * @property {TetherApi} [Tether]
- */
-
-/** @returns {Window & TetherGlobals} */
-const pageGlobals = () => window;
-
-/** @type {Promise<TetherApi | null> | null} */
-let initPromise = null;
-
-/** @type {MutationObserver | null} */
-let observer = null;
-
-/** @type {Event[] | null} The analytics part's queue, created once by the first `init()` with `analytics`. */
-let analyticsQueue = null;
-
-/** @type {boolean} The document-wide listeners are bound once, by the first configured `init()`. */
-let controlsBound = false;
-
-/**
- * Mounts the lists of `root` and the product scopes in them as they render.
- *
- * @param {ParentNode} root
- * @returns {number} The lists mounted.
- */
-function mountLists(root) {
-  let count = 0;
-  within(root, listSelector()).forEach((el) => {
-    if (mountedLists.has(el)) return;
-    mountedLists.add(el);
-    count++;
-    const list = new ListScope(el);
-    liveLists.add(list);
-    el.addEventListener(`${cfg.prefix}:list-rendered`, (event) => {
-      // The list emits this CustomEvent once its products are in the page.
-      mount(/** @type {CustomEvent<{ container: ParentNode }>} */ (event).detail.container);
-    });
-    void trackMarket(list.load());
-  });
-  return count;
-}
-
-/**
- * Loads each optional part `root` uses: the country select, customer accounts and search as you type.
- *
- * @param {ParentNode} root
- */
-function mountParts(root) {
-  if (within(root, `${sel('country-select')},${sel('country-bind')}`).length) {
-    loadPart('markets')
-      .then((part) => part.renderCountrySelects(root))
-      .catch((/** @type {unknown} */ error) => {
-        reportError(error, 'markets');
-      });
-  }
-  mountAccountIfUsed(root);
-  if (within(root, sel('search')).length) {
-    loadPart('search')
-      .then((part) => {
-        part.mountSearch(root);
-      })
-      .catch((/** @type {unknown} */ error) => {
-        reportError(error, 'search');
-      });
-  }
-}
-
-/**
- * Mounts every product scope and product list inside `root`. Safe to call repeatedly.
- *
- * @param {ParentNode} [root]
- * @returns {number} The scopes and lists newly mounted.
- */
-export function mount(root = document) {
-  if (!isConfigured()) return 0;
-  if (root === document) rememberDocumentMount();
-  // Page transitions detach old roots: they aren't kept alive.
-  pruneLive();
-  // Products the server rendered into the page need no request.
-  hydrateFromPage(root.ownerDocument ?? document);
-  let count = mountLists(root);
-  within(root, sel('product')).forEach((el) => {
-    if (mountProduct(el)) count++;
-  });
-  mountParts(root);
-  settleMarket();
-  Cart.render();
-  log(`mounted ${count} scope(s)`, root);
-  return count;
-}
-
-/** Call before a page transition removes the page: closes the cart drawer. */
-export function unmount() {
-  Cart.close();
-}
-
-/**
- * @param {Element | null | undefined} el
- * @returns {ProductScope | null} The product scope `el` is in.
- */
-export function getScope(el) {
-  const root = el?.closest(sel('product'));
-  return root ? (scopes.get(root) ?? null) : null;
-}
-
-function bindControls() {
-  if (controlsBound) return;
-  controlsBound = true;
-  bindCartControls();
-  bindDiscountControls();
-  bindExtrasControls();
-  bindNavigation({ ready: () => initPromise ?? Promise.resolve(null), mount, unmount });
-}
-
-/** Buffers Tether's events until the analytics part has loaded, so none are missed. */
-function startAnalyticsQueue() {
-  /** @type {Event[]} */
-  const queue = [];
-  analyticsQueue = queue;
-  ANALYTICS_EVENTS.forEach((name) => {
-    document.addEventListener(`${cfg.prefix}:${name}`, (event) => queue.push(event));
-  });
-  document.addEventListener('astro:page-load', () => queue.push(new CustomEvent(`${cfg.prefix}:page`)));
-  loadPart('analytics')
-    .then((part) => part.startAnalytics(queue))
-    .catch((/** @type {unknown} */ error) => {
-      reportError(error, 'analytics');
-    });
-}
-
-/**
- * A saved cart from another market moves to this one, so its prices match the page's.
- *
- * @param {ShopifyCart | null} cart
- * @returns {Promise<ShopifyCart | null>}
- */
-async function cartInPageMarket(cart) {
-  const country = cfg.country?.toUpperCase();
-  const cartCountry = cart?.buyerIdentity.countryCode;
-  if (!cart || !country || !cartCountry || cartCountry === country) return cart;
-  try {
-    return await Cart.setBuyerIdentity({ countryCode: country }, { create: false });
-  } catch (error) {
-    reportError(error, 'cart country');
-    return cart;
-  }
-}
-
-/**
- * Configures Tether (`window.TETHER_CONFIG` with `overrides` over it), applies the visitor's market and loads the
- * cart. A second call without overrides returns the first one's promise.
- *
- * @param {TetherOptions} [overrides]
- * @returns {Promise<TetherApi | null>} `null` without a domain and token, when Tether stays idle.
- */
-export function init(overrides = {}) {
-  if (initPromise && !Object.keys(overrides).length) return initPromise;
-  configure({ ...pageGlobals().TETHER_CONFIG, ...overrides });
-  if (!isConfigured()) {
-    warn('TETHER_CONFIG is missing domain or token. Tether is idle.');
-    initPromise = Promise.resolve(null);
-    return initPromise;
-  }
-  bindControls();
-  if (cfg.observe) startObserver();
-  if (cfg.analytics && !analyticsQueue) startAnalyticsQueue();
-  initPromise = applyStartMarket(overrides)
-    .then(() => Cart.init())
-    .then(cartInPageMarket)
-    .then((cart) => {
-      emit('ready', { cart });
-      return api;
-    });
-  return initPromise;
-}
-
-/** `observe`: mounts the elements added to the page later. */
-function startObserver() {
-  if (observer || typeof MutationObserver === 'undefined') return;
-  /** @type {ReturnType<typeof setTimeout> | undefined} */
-  let timer;
-  /** @type {Set<Element>} */
-  const queued = new Set();
-  observer = new MutationObserver((mutations) => {
-    mutations.forEach((mutation) => {
-      mutation.addedNodes.forEach((node) => {
-        if (node instanceof window.Element) queued.add(node);
-      });
-    });
-    clearTimeout(timer);
-    timer = setTimeout(() => {
-      queued.forEach((node) => {
-        if (node.isConnected) mount(node);
-      });
-      queued.clear();
-    }, OBSERVE_DEBOUNCE_MS);
-  });
-  observer.observe(document.body, { childList: true, subtree: true });
-}
-
-/**
- * @param {MarketsConfig | null} [markets] Default `markets` of the config.
- */
-const detectMarket = (markets) => loadPart('markets').then((part) => part.detectMarket(markets ?? cfg.markets));
-
-const getLocalization = () => loadPart('markets').then((part) => part.getLocalization());
-
-/** @param {Omit<DiagnoseOptions, 'version'>} [options] */
-const diagnose = (options) => loadPart('diagnose').then((part) => part.diagnose({ ...options, version: VERSION }));
-
-/**
- * Listens to the Tether event `<prefix>:<name>`.
- *
- * @param {string} name
- * @param {(detail: unknown, event: CustomEvent) => void} listener
- * @returns {() => void} Stops listening.
- */
-function on(name, listener) {
-  /** @param {Event} event */
-  const handler = (event) => {
-    const custom = /** @type {CustomEvent} Tether's events are CustomEvents. */ (event);
-    listener(custom.detail, custom);
-  };
-  document.addEventListener(`${cfg.prefix}:${name}`, handler);
-  return () => {
-    document.removeEventListener(`${cfg.prefix}:${name}`, handler);
-  };
-}
-
-export const api = {
-  VERSION,
-  init,
-  mount,
-  unmount,
-  /** @returns {TetherConfig} */
-  get config() {
-    return cfg;
-  },
-  /** @returns {Promise<TetherApi | null>} */
-  get ready() {
-    return initPromise ?? Promise.resolve(null);
-  },
-  query: gql,
-  withContext,
-  cart: Cart,
-  getProduct,
-  getProducts,
-  getRecommendations,
-  getScope,
-  addGroup,
-  account: accountApi,
-  primeProduct,
-  normalizeProductKey,
-  clearProductCache,
-  formatMoney,
-  imageUrl,
-  plans,
-  TetherError,
-  resolveProductKey,
-  setCountry,
-  detectMarket,
-  getLocalization,
-  diagnose,
-  __core: coreModules,
-  // The `<script>` build's parts register here when their file has loaded.
-  __parts: /** @type {Record<string, unknown>} */ ({}),
-  on,
-};
-
-/** @typedef {typeof api} TetherApi */
-
-export default api;
-
-/**
- * The plain `<script>` setup starts by itself, unless `autoMount: false` or a framework integration (Astro), which
- * starts Tether itself.
- */
-function autoStart() {
-  const globals = pageGlobals();
-  globals.Tether = api;
-  if (!globals.TETHER_CONFIG || globals.TETHER_CONFIG.autoMount === false || globals.TETHER_INTEGRATION) return;
-  const start = () => {
-    init()
-      .then(() => mount(document))
-      .catch((/** @type {unknown} */ error) => {
-        reportError(error, 'init');
-      });
-  };
-  if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', start, { once: true });
-  else start();
-}
-
-if (typeof window !== 'undefined' && typeof document !== 'undefined') autoStart();

package/src/initial.js

@@ -1,87 +0,0 @@
-/**
- * What the browser script shows first for a product, as plain data, so a server renders the same and nothing flashes
- * when Tether takes over. Public as `initialState()` of `@occluze/tether/server`; the rules are `product-state.js`'s,
- * the ones the browser scope uses.
- */
-import { DEFAULTS } from './config.js';
-import { initialChoice, isValueAvailable, productView } from './product-state.js';
-import { allPlans, allocationFor, planPrice, planSavings } from './selling-plans.js';
-/** @import { Money } from './shopify-values.js' */
-/** @import { Product, ProductVariant } from './fragments.js' */
-/** @import { PlanInGroup } from './selling-plans.js' */
-/** @import { Selection, ShowCondition } from './product-state.js' */
-
-/**
- * @typedef {object} InitialOptions
- * @property {string | null | undefined} [variant] The page's `?variant=`; the first variant for sale without.
- * @property {string | null | undefined} [sellingPlan] The page's `?selling_plan=`: subscribes on that plan.
- * @property {string | null | undefined} [defaultPurchase] `subscription` subscribes on the first plan.
- * @property {number | undefined} [lowStock] `low-stock` at this many or fewer.
- */
-/**
- * @typedef {object} InitialPlan A plan in the plan list (`tether-plan-list`).
- * @property {string} id
- * @property {string} name
- * @property {Money | null} price On this plan, for the variant.
- * @property {number} savings In %, 0 without savings.
- * @property {boolean} selected `is-selected`: the line is bought on this plan.
- * @property {boolean} available The variant is on this plan; `is-unavailable` when not.
- */
-/**
- * @typedef {object} InitialState
- * @property {ProductVariant} variant
- * @property {Selection} selected Option name → value of the variant: `is-selected` on those buttons.
- * @property {'one-time' | 'subscription'} purchase
- * @property {PlanInGroup | null} plan The plan the line is bought on, `null` when bought once.
- * @property {InitialPlan[]} plans
- * @property {number} savings The offered plan's savings in % (`tether-bind="subscription-savings"`), 0 without.
- * @property {Money} price
- * @property {Money | null} compareAtPrice Only when on sale.
- * @property {boolean} available
- * @property {Record<ShowCondition, boolean>} show The `tether-show` conditions: `hidden={!state.show['out-of-stock']}`.
- * @property {Record<string, string[]>} unavailable Per option, the values without a variant for sale (given the other
- *   selected values), as plain data for frameworks that serialise props.
- * @property {(name: string, value: string) => boolean} isUnavailable The same as a function: `is-unavailable`.
- */
-
-/**
- * @param {Product | null | undefined} product
- * @param {InitialOptions} [options]
- * @returns {InitialState | null} `null` without a product or variants.
- */
-export function initialState(product, options = {}) {
-  if (!product) return null;
-  const { variant, sellingPlan, defaultPurchase = DEFAULTS.defaultPurchase, lowStock = DEFAULTS.lowStock } = options;
-  const choice = initialChoice(product, { variant, sellingPlan, defaultPurchase });
-  const view = productView(product, { ...choice, quantity: 1 }, lowStock);
-  if (!view) return null;
-  const { selected, isSubscription } = view;
-  const isUnavailable = (/** @type {string} */ name, /** @type {string} */ value) =>
-    !isValueAvailable(product, selected, name, value);
-  return {
-    variant: view.variant,
-    selected,
-    purchase: view.purchase.kind,
-    plan: isSubscription ? view.plan : null,
-    plans: allPlans(product).map((plan) => ({
-      id: plan.id,
-      name: plan.name,
-      price: planPrice(view.variant, plan.id),
-      savings: planSavings(view.variant, plan.id).percentage,
-      selected: isSubscription && plan.id === view.purchase.planId,
-      available: Boolean(allocationFor(view.variant, plan.id)),
-    })),
-    savings: view.savings.percentage,
-    price: view.price,
-    compareAtPrice: view.compareAtPrice,
-    available: view.variant.availableForSale,
-    show: view.show,
-    unavailable: Object.fromEntries(
-      product.options.map((option) => [
-        option.name,
-        option.optionValues.map((value) => value.name).filter((value) => isUnavailable(option.name, value)),
-      ]),
-    ),
-    isUnavailable,
-  };
-}

package/src/lazy-iife.js

@@ -1,116 +0,0 @@
-/**
- * `<script>` build: the optional parts are separate files next to tether(.min).js (tether.markets.min.js), loaded on
- * first use. `partsUrl` sets another folder. A part registers itself in `window.Tether.__parts` and uses the core
- * modules in `window.Tether.__core` instead of bundling copies of them.
- */
-import * as config from './config.js';
-import * as client from './client.js';
-import * as dom from './dom.js';
-import * as fragments from './fragments.js';
-import * as loader from './loader.js';
-import * as sellingPlans from './selling-plans.js';
-import * as status from './status.js';
-import * as cart from './cart.js';
-import * as product from './product.js';
-import * as collection from './collection.js';
-import * as mounting from './mounting.js';
-import * as marketCodes from './market-codes.js';
-import * as shopifyValues from './shopify-values.js';
-import * as storeHtml from './store-html.js';
-/** @import { Parts, PartName } from './lazy.js' */
-
-const { cfg } = config;
-
-/**
- * The modules a part may use, shared instead of bundled twice (scripts/build.mjs maps a part's imports to these).
- *
- * @type {Record<string, object>}
- */
-export const coreModules = {
-  'config.js': config,
-  'client.js': client,
-  'dom.js': dom,
-  'fragments.js': fragments,
-  'loader.js': loader,
-  'selling-plans.js': sellingPlans,
-  'status.js': status,
-  'cart.js': cart,
-  'product.js': product,
-  'collection.js': collection,
-  'mounting.js': mounting,
-  'market-codes.js': marketCodes,
-  'shopify-values.js': shopifyValues,
-  'store-html.js': storeHtml,
-};
-
-const MINIFIED_SCRIPT = /\.min\.js(\?|$)/;
-const coreScript = typeof document === 'undefined' ? '' : (document.currentScript?.getAttribute('src') ?? '');
-const coreScriptUrl = coreScript ? new URL(coreScript, document.baseURI).href : '';
-
-/** @type {Map<PartName, Promise<unknown>>} Parts loaded or loading. */
-const parts = new Map();
-
-/**
- * The folder parts load from: `partsUrl`, else the core script's own folder. A `partsUrl` must be https or on this
- * site, because the parts run with the same access as the core (the account part holds customer sessions).
- *
- * @throws {Error} For a `partsUrl` that is neither.
- */
-function partsFolder() {
-  if (!cfg.partsUrl) return coreScriptUrl.replace(/[^/]*$/, '');
-  const folder = new URL(cfg.partsUrl, document.baseURI);
-  if (folder.protocol !== 'https:' && folder.origin !== window.location.origin) {
-    throw new Error(`partsUrl must be https or on this site: ${folder.href}`);
-  }
-  return folder.href;
-}
-
-/**
- * @param {PartName} name
- * @param {string} url
- * @returns {Promise<unknown>}
- */
-function loadScript(name, url) {
-  return new Promise((resolve, reject) => {
-    const script = document.createElement('script');
-    script.src = url;
-    script.async = true;
-    script.onload = () => {
-      const { Tether } = /** @type {Window & { Tether?: { __parts?: Record<string, unknown> } }} */ (window);
-      const part = Tether?.__parts?.[name];
-      if (part) resolve(part);
-      else reject(new Error(`${url} did not register`));
-    };
-    script.onerror = () => {
-      parts.delete(name);
-      reject(new Error(`Could not load ${url}. Host it next to the Tether script, or set partsUrl.`));
-    };
-    document.head.appendChild(script);
-  });
-}
-
-/**
- * @template {PartName} Name
- * @param {Name} name
- * @returns {Promise<Parts[Name]>}
- * @throws {Error} (rejected) When the part's file can't be loaded or doesn't register.
- */
-export function loadPart(name) {
-  let loading = parts.get(name);
-  if (!loading) {
-    let folder;
-    try {
-      folder = partsFolder();
-    } catch (error) {
-      return Promise.reject(error instanceof Error ? error : new Error(String(error)));
-    }
-    const suffix = MINIFIED_SCRIPT.test(coreScriptUrl) || !coreScriptUrl ? '.min' : '';
-    loading = loadScript(name, `${folder.replace(/\/?$/, '/')}tether.${name}${suffix}.js`);
-    parts.set(name, loading);
-  }
-  // A part's file is built from the module `Parts[Name]` names (scripts/build.mjs), and registers that module.
-  return /** @type {Promise<Parts[Name]>} */ (loading);
-}
-
-// Parts that load other parts (account → account-pages) use this same loader.
-coreModules['lazy.js'] = { loadPart, coreModules };

package/src/lazy.js

@@ -1,39 +0,0 @@
-/**
- * Optional parts that most pages never need, loaded on first use. In the ESM and Node builds they are dynamic
- * imports, which bundlers split into their own chunks; the `<script>` build swaps this file for `lazy-iife.js`
- * (scripts/build.mjs).
- */
-
-/**
- * @typedef {{
- *   diagnose: typeof import('./diagnose.js'),
- *   markets: typeof import('./markets-ui.js'),
- *   search: typeof import('./search.js'),
- *   extras: typeof import('./extras.js'),
- *   account: typeof import('./account.js'),
- *   'account-pages': typeof import('./account-pages.js'),
- *   analytics: typeof import('./analytics.js'),
- * }} Parts
- */
-/** @typedef {keyof Parts} PartName */
-
-/** @type {{ [Name in PartName]: () => Promise<Parts[Name]> }} */
-const PARTS = {
-  diagnose: () => import('./diagnose.js'),
-  markets: () => import('./markets-ui.js'),
-  search: () => import('./search.js'),
-  extras: () => import('./extras.js'),
-  account: () => import('./account.js'),
-  'account-pages': () => import('./account-pages.js'),
-  analytics: () => import('./analytics.js'),
-};
-
-/**
- * @template {PartName} Name
- * @param {Name} name
- * @returns {Promise<Parts[Name]>}
- */
-export const loadPart = (name) => PARTS[name]();
-
-/** Only the `<script>` build shares its modules with separately loaded parts. */
-export const coreModules = undefined;