@occluze/tether 0.6.7 → 0.6.8

package/src/initial.js

@@ -1,75 +1,87 @@
 /**
- * What the browser script will show first for a product, so a server can render the same
- * (no flash when Tether takes over): the selected variant, price, purchase mode and conditions.
- * Same rules as src/product.js: first available variant (or the one in ?variant=), subscription
- * when the product requires a plan or defaultPurchase is 'subscription', low stock at 5 or fewer.
+ * 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 { GID, allPlans, allocationFor, findPlan, planPrice, planSavings } from './selling-plans.js';
+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' */
 
-export function initialState(product, { variant, sellingPlan, defaultPurchase = 'one-time', lowStock = 5 } = {}) {
-  const vs = product?.variants?.nodes || [];
-  const gid = variant ? GID.variant(variant) : null;
-  const v = (gid && vs.find((x) => x.id === gid)) || vs.find((x) => x.availableForSale) || vs[0] || null;
-  if (!v) return null;
-  const selected = Object.fromEntries((v.selectedOptions || []).map((o) => [o.name, o.value]));
-
-  const plans = allPlans(product);
-  const fromUrl = findPlan(product, sellingPlan);
-  let plan = plans.length ? (fromUrl || plans[0]) : null;
-  if (plan && !allocationFor(v, plan.id)) plan = plans.find((p) => allocationFor(v, p.id)) || plan;
-  const wantsSub = product.requiresSellingPlan || fromUrl || defaultPurchase === 'subscription';
-  const subscriptionAvailable = plans.some((p) => allocationFor(v, p.id));
-  const purchase = plans.length && wantsSub ? 'subscription' : 'one-time';
-  const sub = purchase === 'subscription' && subscriptionAvailable;
-
-  const price = sub ? planPrice(v, plan.id) : v.price;
-  const compareAt = sub ? (allocationFor(v, plan.id)?.priceAdjustments?.[0]?.compareAtPrice || v.compareAtPrice) : v.compareAtPrice;
-  const onSale = Boolean(compareAt && parseFloat(compareAt.amount) > parseFloat(price.amount));
-  const q = v.quantityAvailable;
-  const low = q != null && q > 0 && q <= lowStock;
-  const savingsNow = sub ? planSavings(v, plan.id).percentage : 0;
+/**
+ * @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: v,
+    variant: view.variant,
     selected,
-    purchase,
-    plan: sub ? plan : null,
-    /** The plan list (tether-plan-list="all"): selected one gets is-selected, unavailable ones is-unavailable. */
-    plans: plans.map((p) => ({
-      id: p.id, name: p.name, price: planPrice(v, p.id), savings: planSavings(v, p.id).percentage,
-      selected: sub && p.id === plan.id, available: Boolean(allocationFor(v, p.id)),
+    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 of the selected plan in % (tether-bind="subscription-savings"), 0 without one. */
-    savings: plan ? planSavings(v, plan.id).percentage : 0,
-    price,
-    compareAtPrice: onSale ? compareAt : null,
-    available: v.availableForSale,
-    /** The tether-show conditions, e.g. hidden={!state.show['out-of-stock']}. */
-    show: {
-      'in-stock': v.availableForSale,
-      'out-of-stock': !v.availableForSale,
-      backorder: Boolean(v.availableForSale && v.currentlyNotInStock),
-      'on-sale': onSale,
-      'not-on-sale': !onSale,
-      'has-variants': vs.length > 1,
-      'single-variant': vs.length === 1,
-      'low-stock': low,
-      'plenty-in-stock': v.availableForSale && !low,
-      'subscription-available': subscriptionAvailable,
-      'subscription-unavailable': !subscriptionAvailable,
-      'subscription-only': Boolean(product.requiresSellingPlan),
-      'one-time-available': !product.requiresSellingPlan,
-      'subscription-selected': sub,
-      'one-time-selected': !sub,
-      'has-savings': sub ? savingsNow > 0 : onSale,
-    },
-    /** Option values without an available variant, as plain data (for frameworks that serialise props). */
-    unavailable: Object.fromEntries((product.options || []).map((o) => [o.name, o.optionValues.map((x) => x.name).filter((n) => isUnavail(o.name, n))])),
-    /** Option values with no available variant (given the other selected options): class is-unavailable. */
-    isUnavailable: (name, value) => isUnavail(name, value),
+    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,
   };
-  function isUnavail(name, value) {
-    return !vs.some((x) => x.availableForSale && x.selectedOptions.every((o) =>
-      (o.name === name ? o.value === value : selected[o.name] === o.value)));
-  }
 }

package/src/lazy-iife.js

@@ -1,6 +1,7 @@
 /**
- * <script> build: optional parts are separate files next to tether(.min).js, e.g.
- * tether.markets.min.js, loaded on first use. Override the folder with config.partsUrl.
+ * `<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';
@@ -13,34 +14,103 @@ 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 imports to these). */
+/**
+ * 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,
+  '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 self = typeof document !== 'undefined' ? document.currentScript?.src || '' : '';
-const parts = {};
+const MINIFIED_SCRIPT = /\.min\.js(\?|$)/;
+const coreScript = typeof document === 'undefined' ? '' : (document.currentScript?.getAttribute('src') ?? '');
+const coreScriptUrl = coreScript ? new URL(coreScript, document.baseURI).href : '';
 
-export function loadPart(name) {
-  if (parts[name]) return parts[name];
-  const base = cfg.partsUrl || self.replace(/[^/]*$/, '');
-  const min = /\.min\.js(\?|$)/.test(self) || !self ? '.min' : '';
-  const url = `${base.replace(/\/?$/, '/')}tether.${name}${min}.js`;
-  parts[name] = new Promise((resolve, reject) => {
-    const s = document.createElement('script');
-    s.src = url;
-    s.async = true;
-    s.onload = () => (window.Tether?.__parts?.[name] ? resolve(window.Tether.__parts[name]) : reject(new Error(`${url} did not register`)));
-    s.onerror = () => { delete parts[name]; reject(new Error(`Could not load ${url}. Host it next to the Tether script, or set partsUrl.`)); };
-    document.head.appendChild(s);
+/** @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);
   });
-  return parts[name];
 }
 
-// Parts that load other parts (account -> account-pages) use this same loader.
+/**
+ * @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,8 +1,23 @@
 /**
- * Optional parts that most pages never need, loaded on first use.
- * ESM / Node: dynamic import (bundlers split these into their own chunks).
- * The <script> build swaps this file for lazy-iife.js (see scripts/build.mjs).
+ * 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'),
@@ -12,7 +27,13 @@ const PARTS = {
   '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.
+/** Only the `<script>` build shares its modules with separately loaded parts. */
 export const coreModules = undefined;