@occluze/tether 0.6.8 → 0.7.1

package/src/diagnose.js

@@ -1,295 +0,0 @@
-/**
- * `Tether.diagnose()`: one call in the browser console that explains what's wrong on a page. Logs a readable report
- * and returns it as an object. The markup checks are in diagnose-markup.js.
- *
- *   await Tether.diagnose()
- *   await Tether.diagnose({ silent: true })   // just the object
- */
-import { cfg, isConfigured } from './config.js';
-import { gql, endpoint } from './client.js';
-import { sel, get, qsa } from './dom.js';
-import { getProduct } from './loader.js';
-import { allPlans } from './selling-plans.js';
-import { resolveProductKey } from './status.js';
-import { apiVersionStatus } from './api-version.js';
-import { loadPart } from './lazy.js';
-import { checkMarkup, didYouMean } from './diagnose-markup.js';
-/** @import { ApiVersionStatus } from './api-version.js' */
-/** @import { DetectedMarket } from './markets.js' */
-/** @import { Problem } from './diagnose-markup.js' */
-/** @import { Product } from './fragments.js' */
-
-export { apiVersionStatus, checkMarkup, didYouMean };
-
-/**
- * @typedef {object} MarketReport The market in use (a visitor's choice included), and what detection would pick.
- * @property {string | null} country
- * @property {string | null} language
- * @property {string | null} locale
- * @property {DetectedMarket | null} detected `null` without `markets.detect`.
- */
-/** @typedef {{ name: string, url: string, currency: string }} ShopReport */
-/**
- * @typedef {{ key: string, handle: string, title: string, plans: number, requiresSellingPlan: boolean }
- *   | { key: string, error: string | undefined }} ProductReport
- */
-/** @typedef {{ product: string, group: string, plan: string, id: string }} SellingPlanReport */
-/**
- * @typedef {object} DiagnoseReport
- * @property {string | undefined} version
- * @property {Record<string, unknown>} config The config, with the token masked.
- * @property {ApiVersionStatus} apiVersion
- * @property {MarketReport} market
- * @property {boolean} reachable
- * @property {ShopReport | null} shop
- * @property {number | null} latencyMs
- * @property {ProductReport[]} products
- * @property {SellingPlanReport[]} sellingPlans
- * @property {Problem[]} problems
- */
-/**
- * @typedef {{ kind: 'not-configured' }
- *   | { kind: 'reachable', shop: ShopReport, latencyMs: number }
- *   | { kind: 'unreachable', error: unknown, latencyMs: number }} StorefrontCheck
- */
-/**
- * @typedef {object} DiagnoseOptions
- * @property {ParentNode} [root]
- * @property {boolean} [silent] Return the report without logging it.
- * @property {string} [version] Tether's version, for the report.
- * @property {Date} [now] The date the API version's support is measured against.
- */
-
-/** Products checked at most, so a long CMS page doesn't send a request per card. */
-const MAX_PRODUCTS_CHECKED = 20;
-/** Matches the warning window of `apiVersionStatus`. */
-const API_UPGRADE_WARNING_MONTHS = 3;
-const TOKEN_EDGE_CHARACTERS = 4;
-
-/** @param {string} token */
-function maskToken(token) {
-  if (!token) return '(missing)';
-  return `${token.slice(0, TOKEN_EDGE_CHARACTERS)}…${token.slice(-TOKEN_EDGE_CHARACTERS)} (${token.length} chars)`;
-}
-
-/**
- * @param {unknown} error
- * @param {string} fallback
- * @returns {string} The error's message, else its code (a `TetherError` has one), else `fallback`.
- */
-function errorText(error, fallback) {
-  if (error instanceof Error && error.message) return error.message;
-  /** @type {unknown} */
-  const code = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : undefined;
-  return typeof code === 'string' && code ? code : fallback;
-}
-
-/** @returns {Record<string, unknown>} */
-function configSummary() {
-  return {
-    domain: cfg.domain || '(missing)',
-    token: maskToken(cfg.token),
-    apiVersion: cfg.apiVersion,
-    endpoint: cfg.domain ? endpoint() : null,
-    country: cfg.country,
-    language: cfg.language,
-    locale: cfg.locale,
-    markets: cfg.markets,
-    prefix: cfg.prefix,
-    productPath: cfg.productPath,
-    metafields: cfg.metafields,
-    autoMount: cfg.autoMount,
-    observe: cfg.observe,
-    onError: typeof cfg.onError === 'function',
-  };
-}
-
-/**
- * Detection runs in the markets part, which init has already loaded whenever `markets.detect` is set.
- *
- * @returns {Promise<MarketReport>}
- */
-async function marketSummary() {
-  return {
-    country: cfg.country || null,
-    language: cfg.language || null,
-    locale: cfg.locale || null,
-    detected: cfg.markets?.detect ? (await loadPart('markets')).detectMarket(cfg.markets) : null,
-  };
-}
-
-/**
- * @param {ApiVersionStatus} status
- * @returns {Problem | null} An error for an unsupported version, a warning when support ends soon.
- */
-function apiVersionProblem({ ok, monthsLeft, note }) {
-  if (ok && (monthsLeft === undefined || monthsLeft >= API_UPGRADE_WARNING_MONTHS)) return null;
-  return { level: ok ? 'warn' : 'error', message: `apiVersion ${cfg.apiVersion}: ${note}` };
-}
-
-/** @returns {Promise<StorefrontCheck>} */
-async function checkStorefront() {
-  if (!isConfigured()) return { kind: 'not-configured' };
-  const startedAt = Date.now();
-  try {
-    /** @type {{ shop: { name: string, primaryDomain: { url: string }, paymentSettings: { currencyCode: string } } }} */
-    const data = await gql(
-      'query TetherDiagnose { shop { name primaryDomain { url } paymentSettings { currencyCode } } }',
-      {},
-      { context: false },
-    );
-    const shop = {
-      name: data.shop.name,
-      url: data.shop.primaryDomain.url,
-      currency: data.shop.paymentSettings.currencyCode,
-    };
-    return { kind: 'reachable', shop, latencyMs: Date.now() - startedAt };
-  } catch (error) {
-    return { kind: 'unreachable', error, latencyMs: Date.now() - startedAt };
-  }
-}
-
-/**
- * Options a visitor can't choose on this page get the first available variant's value.
- *
- * @param {ParentNode} root
- * @param {string} key
- * @param {Product} product
- * @returns {Problem[]}
- */
-function checkOptions(root, key, product) {
-  /** @type {Problem[]} */
-  const problems = [];
-  const names = product.options.map((option) => option.name);
-  const roots = qsa(root, sel('product')).filter(
-    (el) => resolveProductKey(el).key === key && el.querySelector(sel('add-to-cart')),
-  );
-  for (const el of roots) {
-    const shown = new Set(
-      qsa(el, `${sel('option-list')},select${sel('option')}`).map(
-        (list) => get(list, 'option-list') || get(list, 'option'),
-      ),
-    );
-    if (!shown.size && qsa(el, `select${sel('variant-select')}`).length) continue;
-    // Translated option names (a language in the market) don't match the names in the markup.
-    if (!cfg.language) {
-      for (const name of shown) {
-        if (!name || names.includes(name)) continue;
-        problems.push({
-          level: 'warn',
-          message: `Product "${product.handle}" has no option "${name}" (its options: ${names.join(', ') || 'none'}).${didYouMean(name, names)}`,
-        });
-      }
-    }
-    for (const option of product.options) {
-      if (option.optionValues.length <= 1 || shown.has(option.name)) continue;
-      problems.push({
-        level: 'warn',
-        message: `Product "${product.handle}": option "${option.name}" (${option.optionValues.length} values) has no tether-option-list, so visitors can't choose it.`,
-      });
-    }
-  }
-  return problems;
-}
-
-/**
- * Loads the page's products and adds what it finds about each to `report`.
- *
- * @param {ParentNode} root
- * @param {DiagnoseReport} report
- */
-async function checkProducts(root, report) {
-  const allKeys = qsa(root, sel('product')).map((el) => resolveProductKey(el).key);
-  const keys = [...new Set(allKeys.filter((key) => key !== null && key !== ''))].slice(0, MAX_PRODUCTS_CHECKED);
-  const results = await Promise.allSettled(keys.map((key) => getProduct(key)));
-  results.forEach((result, index) => {
-    const key = keys[index] ?? '';
-    if (result.status === 'rejected') {
-      const reason = errorText(result.reason, 'not loaded');
-      report.products.push({ key, error: result.reason instanceof Error ? result.reason.message : undefined });
-      report.problems.push({
-        level: 'error',
-        message: `Product "${key}": ${reason}. Is it published to the Headless channel?`,
-      });
-      return;
-    }
-    const product = result.value;
-    const plans = allPlans(product);
-    report.products.push({
-      key,
-      handle: product.handle,
-      title: product.title,
-      plans: plans.length,
-      requiresSellingPlan: product.requiresSellingPlan,
-    });
-    for (const plan of plans) {
-      report.sellingPlans.push({ product: product.handle, group: plan.group.name, plan: plan.name, id: plan.id });
-    }
-    report.problems.push(...checkOptions(root, key, product));
-  });
-}
-
-/**
- * @param {DiagnoseOptions} [options]
- * @returns {Promise<DiagnoseReport>} What's wrong on the page: config, token, API version, products, plans, markup.
- */
-export async function diagnose({ root = document, silent = false, version, now = new Date() } = {}) {
-  const storefront = await checkStorefront();
-  /** @type {DiagnoseReport} */
-  const report = {
-    version,
-    config: configSummary(),
-    apiVersion: apiVersionStatus(cfg.apiVersion, now),
-    market: await marketSummary(),
-    reachable: storefront.kind === 'reachable',
-    shop: storefront.kind === 'reachable' ? storefront.shop : null,
-    latencyMs: storefront.kind === 'not-configured' ? null : storefront.latencyMs,
-    products: [],
-    sellingPlans: [],
-    problems: [],
-  };
-  switch (storefront.kind) {
-    case 'not-configured':
-      report.problems.push({ level: 'error', message: 'TETHER_CONFIG needs domain and token.' });
-      break;
-    case 'unreachable':
-      report.problems.push({
-        level: 'error',
-        message: `Storefront API not reachable: ${errorText(storefront.error, 'unknown error')}`,
-      });
-      break;
-    case 'reachable':
-      await checkProducts(root, report);
-      break;
-  }
-  const versionProblem = apiVersionProblem(report.apiVersion);
-  if (versionProblem) report.problems.push(versionProblem);
-  if (typeof document !== 'undefined') report.problems.push(...checkMarkup(root));
-  if (!silent) print(report);
-  return report;
-}
-
-/** @param {DiagnoseReport} report */
-function print(report) {
-  const errors = report.problems.filter((problem) => problem.level === 'error').length;
-  const warnings = report.problems.length - errors;
-  console.group(`[${cfg.prefix}] diagnose: ${errors ? `${errors} error(s)` : 'no errors'}, ${warnings} warning(s)`);
-  console.log('version', report.version, '| API', report.apiVersion.version, `(${report.apiVersion.note})`);
-  console.log('config', report.config);
-  const { country, language, detected } = report.market;
-  const inUse = [country, language].filter(Boolean).join(' / ') || 'the store default';
-  console.log('market', `in use: ${inUse}`, detected ? `(detection picks ${JSON.stringify(detected)})` : '');
-  console.log(
-    report.shop
-      ? `Storefront API reachable: ${report.shop.name} (${report.latencyMs ?? 0} ms)`
-      : 'Storefront API NOT reachable',
-  );
-  if (report.products.length) console.table(report.products);
-  if (report.sellingPlans.length) console.table(report.sellingPlans);
-  else if (report.reachable) console.log('No selling plans on the products of this page.');
-  for (const problem of report.problems) {
-    if (problem.level === 'error') console.error(problem.message, problem.el ?? '');
-    else console.warn(problem.message, problem.el ?? '');
-  }
-  console.groupEnd();
-}

package/src/dom.js

@@ -1,287 +0,0 @@
-/**
- * The browser modules' DOM toolkit: what Shopify values look like on the page (money, dates, text, images, lists)
- * and how elements show, hide and report layout changes. Attribute names go through `attr()` so the prefix is
- * configurable. The optional parts import all of it from here (`window.Tether.__core['dom.js']`).
- */
-import { cfg, reportError, warn } from './config.js';
-import { attr, emit, get } from './markup.js';
-import { storeHtmlFragment } from './store-html.js';
-import { formatMoney as formatMoneyIn, productUrl as productUrlFor } from './shopify-values.js';
-/** @import { Money } from './shopify-values.js' */
-
-export { attr, sel, get, has, qsa, scoped, emit } from './markup.js';
-export { imageUrl, cdnUrl, sameImage, setImage } from './images.js';
-export { hasTemplate, repeat, repeatKeyed } from './repeaters.js';
-
-/**
- * State Tether keeps on elements, as `data-tether-*` attributes whatever the prefix: sites style and test against
- * these names, so they stay fixed where the `tether-*` markup attributes follow `prefix`.
- */
-const SEEN = 'data-tether-seen';
-const SHOWN = 'data-tether-shown';
-const PREVIOUS_DISPLAY = 'data-tether-prev-display';
-
-/** Async renders change the page height in bursts; one notification per burst. */
-const LAYOUT_DEBOUNCE_MS = 120;
-
-/**
- * The product page of a product (`productPath`).
- *
- * @param {string | null | undefined} handle
- * @param {string | null} [id]
- */
-export function productUrl(handle, id) {
-  return productUrlFor(cfg.productPath || '/product', handle, id);
-}
-
-/**
- * `Intl` throws a RangeError for a locale or currency it doesn't know; the caller then shows a plain fallback.
- *
- * @template T
- * @param {() => T} format
- * @param {T} fallback
- * @returns {T}
- */
-function formatOr(format, fallback) {
-  try {
-    return format();
-  } catch (error) {
-    if (error instanceof RangeError) return fallback;
-    throw error;
-  }
-}
-
-/**
- * `30` → `30%` (en, nl) or `30 %` (de, fr), in the configured locale.
- *
- * @param {number | null | undefined} percentage
- * @param {string | undefined} [locale]
- * @returns {string} `''` for no or a zero percentage.
- */
-export function formatPercent(percentage, locale = cfg.locale) {
-  if (!percentage) return '';
-  const format = () =>
-    new Intl.NumberFormat(locale || undefined, { style: 'percent', maximumFractionDigits: 0 }).format(percentage / 100);
-  return formatOr(format, `${percentage}%`);
-}
-
-/**
- * Money in the configured locale, through the site's `formatMoney` when it has one.
- *
- * @param {Money | null | undefined} money
- */
-export function formatMoney(money) {
-  if (!money) return '';
-  if (cfg.formatMoney) return cfg.formatMoney(money, cfg.locale);
-  return formatMoneyIn(money, cfg.locale);
-}
-
-/**
- * @param {string | null | undefined} iso
- * @returns {string} The date in the configured locale, `''` without one.
- */
-export function formatDate(iso) {
-  if (!iso) return '';
-  return formatOr(() => new Date(iso).toLocaleDateString(cfg.locale || undefined), '');
-}
-
-/**
- * Writes HTML from the Shopify admin (product and collection descriptions) into `el`, with script removed
- * (`store-html.js`). Everything else from Shopify is written as text (`setText`).
- *
- * @param {Element} el
- * @param {string | null | undefined} html
- */
-export function setStoreHtml(el, html) {
-  el.replaceChildren(storeHtmlFragment(html, el.ownerDocument));
-}
-
-/**
- * @param {Element} el
- * @returns {el is HTMLInputElement | HTMLTextAreaElement}
- */
-const isTextField = (el) => el.tagName === 'INPUT' || el.tagName === 'TEXTAREA';
-
-/**
- * @param {Element} el
- * @returns {el is HTMLInputElement}
- */
-const isInput = (el) => el.tagName === 'INPUT';
-
-/**
- * Sets the text of `el`, or its value when it is a form field.
- *
- * @param {Element} el
- * @param {string | number | boolean | null | undefined} value `null` and `undefined` clear it.
- */
-export function setText(el, value) {
-  const text = value == null ? '' : String(value);
-  if (isTextField(el)) el.value = text;
-  else el.textContent = text;
-}
-
-/** @param {Element} el */
-const readText = (el) => (isTextField(el) ? el.value : el.textContent);
-
-/**
- * `setText` that hands a change after the first render to `onValueChange`, for scramble and roll effects.
- *
- * @param {HTMLElement} el
- * @param {string | number | boolean | null | undefined} value
- */
-export function setTextTracked(el, value) {
-  const before = readText(el);
-  setText(el, value);
-  if (before !== readText(el) && el.hasAttribute(SEEN) && cfg.onValueChange) {
-    try {
-      cfg.onValueChange(el, before);
-    } catch (error) {
-      reportError(error, 'onValueChange');
-    }
-  }
-  el.setAttribute(SEEN, '1');
-}
-
-/**
- * Shows an element hidden before the script ran (a class, an inline `display: none`, a `hidden` attribute), as
- * `block` or the value of `tether-display`.
- *
- * @param {HTMLElement} el
- */
-function reveal(el) {
-  if (el.hasAttribute(SHOWN)) return;
-  el.setAttribute(SHOWN, '');
-  el.removeAttribute('hidden');
-  const previous = el.getAttribute(PREVIOUS_DISPLAY);
-  if (previous !== null) {
-    el.style.display = previous;
-    el.removeAttribute(PREVIOUS_DISPLAY);
-  } else if (el.style.display === 'none') {
-    el.style.display = '';
-  }
-  if (typeof getComputedStyle === 'function' && getComputedStyle(el).display === 'none') {
-    el.style.display = el.getAttribute(attr('display')) || 'block';
-  }
-}
-
-/**
- * Shows or hides `el`, restoring its own display value when shown again.
- *
- * @param {HTMLElement} el
- * @param {boolean} visible
- */
-export function show(el, visible) {
-  if (visible) {
-    reveal(el);
-    return;
-  }
-  el.removeAttribute(SHOWN);
-  // The display value to restore is a real one, never 'none'.
-  if (!el.hasAttribute(PREVIOUS_DISPLAY) && el.style.display !== 'none') {
-    el.setAttribute(PREVIOUS_DISPLAY, el.style.display);
-  }
-  el.style.display = 'none';
-}
-
-/**
- * Marks an option button or input as chosen: `is-selected`, `aria-pressed`, and its own or inner radio/checkbox.
- *
- * @param {Element} el
- * @param {boolean} selected
- */
-export function setSelected(el, selected) {
-  el.classList.toggle('is-selected', selected);
-  el.setAttribute('aria-pressed', selected ? 'true' : 'false');
-  if (isInput(el) && (el.type === 'radio' || el.type === 'checkbox')) el.checked = selected;
-  const input = el.querySelector('input[type="radio"],input[type="checkbox"]');
-  if (input && isInput(input)) input.checked = selected;
-}
-
-/** @type {ReturnType<typeof setTimeout> | undefined} */
-let layoutTimer;
-
-/**
- * Async renders change the page height after the site's page-transition hooks ran. After a burst of them this calls
- * `onLayoutChange` (else refreshes ScrollTrigger) and emits `tether:layout-changed`.
- *
- * @param {string} reason
- */
-export function notifyLayoutChanged(reason) {
-  clearTimeout(layoutTimer);
-  layoutTimer = setTimeout(() => {
-    // GSAP's ScrollTrigger, when the site has it, measures positions that a height change makes stale.
-    const { ScrollTrigger } = /** @type {Window & { ScrollTrigger?: { refresh?: () => void } }} */ (window);
-    if (cfg.onLayoutChange) cfg.onLayoutChange(reason);
-    else ScrollTrigger?.refresh?.();
-    emit('layout-changed', { reason });
-  }, LAYOUT_DEBOUNCE_MS);
-}
-
-/**
- * Notifies a layout change (`<reason>:images`) once every image in `root` that is still loading has loaded or failed.
- *
- * @param {ParentNode} root
- * @param {string} reason
- */
-export function watchImages(root, reason) {
-  const loading = [...root.querySelectorAll('img')].filter((img) => !img.complete);
-  let left = loading.length;
-  const done = () => {
-    left -= 1;
-    if (left === 0) notifyLayoutChanged(`${reason}:images`);
-  };
-  loading.forEach((img) => {
-    img.addEventListener('load', done, { once: true });
-    img.addEventListener('error', done, { once: true });
-  });
-}
-
-/**
- * Runs `task` with `aria-busy` on `el`; does nothing while `el` is already busy.
- *
- * @template T
- * @param {Element} el
- * @param {() => T | Promise<T>} task
- * @returns {Promise<T | undefined>} The task's result, `undefined` when it didn't run.
- */
-export function busy(el, task) {
-  if (el.getAttribute('aria-busy') === 'true') return Promise.resolve(undefined);
-  el.setAttribute('aria-busy', 'true');
-  return Promise.resolve()
-    .then(task)
-    .finally(() => {
-      el.removeAttribute('aria-busy');
-    });
-}
-
-/**
- * @param {Element | null | undefined} el
- * @param {string} name
- * @returns {unknown} The attribute's JSON, `null` when it is missing or not JSON (with a warning).
- */
-export function parseJSONAttr(el, name) {
-  const raw = el ? get(el, name) : null;
-  if (!raw) return null;
-  try {
-    return /** @type {unknown} */ (JSON.parse(raw));
-  } catch {
-    warn(`invalid JSON in ${attr(name)}`, el);
-    return null;
-  }
-}
-
-/** @typedef {string | number | boolean | null | undefined} AttributeValue */
-
-/**
- * `{ a: 1 }` or `[{ key, value }]` → `[{ key, value }]` as Shopify wants cart and line attributes.
- *
- * @param {Record<string, AttributeValue> | { key: string | number, value?: AttributeValue }[] | null | undefined} attributes
- * @returns {{ key: string, value: string }[]}
- */
-export function toAttributes(attributes) {
-  if (!attributes) return [];
-  if (Array.isArray(attributes)) {
-    return attributes.map((attribute) => ({ key: String(attribute.key), value: String(attribute.value ?? '') }));
-  }
-  return Object.entries(attributes).map(([key, value]) => ({ key, value: String(value ?? '') }));
-}