@occluze/tether 0.6.8 → 0.7.0

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

@@ -1,64 +1,81 @@
 /**
  * `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.
+ * and returns it as an object. The markup checks are in diagnose-markup.ts.
  *
  *   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' */
+import { cfg, isConfigured } from './config.ts';
+import { gql, endpoint, shaped } from './client.ts';
+import { sel, get, qsa } from './dom.ts';
+import { getProduct } from './loader.ts';
+import { allPlans } from './selling-plans.ts';
+import { resolveProductKey } from './status.ts';
+import { apiVersionStatus } from './api-version.ts';
+import { loadPart } from './lazy.ts';
+import { checkMarkup, didYouMean } from './diagnose-markup.ts';
+import type { ApiVersionStatus } from './api-version.ts';
+import type { DetectedMarket } from './markets.ts';
+import type { Problem } from './diagnose-markup.ts';
+import type { Product } from './fragments.ts';
 
 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.
- */
+/** The market in use (a visitor's choice included), and what detection would pick. */
+interface MarketReport {
+  country: string | null;
+  language: string | null;
+  locale: string | null;
+  /** `null` without `markets.detect`. */
+  detected: DetectedMarket | null;
+}
+
+interface ShopReport {
+  name: string;
+  url: string;
+  currency: string;
+}
+
+type ProductReport =
+  | { key: string; handle: string; title: string; plans: number; requiresSellingPlan: boolean }
+  | { key: string; error: string | undefined };
+
+interface SellingPlanReport {
+  product: string;
+  group: string;
+  plan: string;
+  id: string;
+}
+
+export interface DiagnoseReport {
+  /** Tether's version, `''` when the caller didn't say. */
+  version: string;
+  /** The config, with the token masked. */
+  config: Record<string, unknown>;
+  apiVersion: ApiVersionStatus;
+  market: MarketReport;
+  reachable: boolean;
+  shop: ShopReport | null;
+  latencyMs: number | null;
+  products: ProductReport[];
+  sellingPlans: SellingPlanReport[];
+  problems: Problem[];
+}
+
+type StorefrontCheck =
+  | { kind: 'not-configured' }
+  | { kind: 'reachable'; shop: ShopReport; latencyMs: number }
+  | { kind: 'unreachable'; error: unknown; latencyMs: number };
+
+export interface DiagnoseOptions {
+  root?: ParentNode;
+  /** Return the report without logging it. */
+  silent?: boolean;
+  /** Tether's version, for the report. */
+  version?: string;
+  /** The date the API version's support is measured against. */
+  now?: Date;
+}
 
 /** Products checked at most, so a long CMS page doesn't send a request per card. */
 const MAX_PRODUCTS_CHECKED = 20;
@@ -66,26 +83,19 @@ const MAX_PRODUCTS_CHECKED = 20;
 const API_UPGRADE_WARNING_MONTHS = 3;
 const TOKEN_EDGE_CHARACTERS = 4;
 
-/** @param {string} token */
-function maskToken(token) {
+function maskToken(token: string): string {
   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) {
+/** The error's message, else its code (a `TetherError` has one), else `fallback`. */
+function errorText(error: unknown, fallback: string): string {
   if (error instanceof Error && error.message) return error.message;
-  /** @type {unknown} */
-  const code = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : undefined;
+  const code: unknown = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : undefined;
   return typeof code === 'string' && code ? code : fallback;
 }
 
-/** @returns {Record<string, unknown>} */
-function configSummary() {
+function configSummary(): Record<string, unknown> {
   return {
     domain: cfg.domain || '(missing)',
     token: maskToken(cfg.token),
@@ -106,10 +116,8 @@ function configSummary() {
 
 /**
  * Detection runs in the markets part, which init has already loaded whenever `markets.detect` is set.
- *
- * @returns {Promise<MarketReport>}
  */
-async function marketSummary() {
+async function marketSummary(): Promise<MarketReport> {
   return {
     country: cfg.country || null,
     language: cfg.language || null,
@@ -118,24 +126,24 @@ async function marketSummary() {
   };
 }
 
-/**
- * @param {ApiVersionStatus} status
- * @returns {Problem | null} An error for an unsupported version, a warning when support ends soon.
- */
-function apiVersionProblem({ ok, monthsLeft, note }) {
+/** An error for an unsupported version, a warning when support ends soon. */
+function apiVersionProblem({ ok, monthsLeft, note }: ApiVersionStatus): Problem | null {
   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() {
+const isShopAnswer = shaped<{
+  shop: { name: string; primaryDomain: { url: string }; paymentSettings: { currencyCode: string } };
+}>({ shop: { name: 'string', primaryDomain: { url: 'string' }, paymentSettings: { currencyCode: 'string' } } });
+
+async function checkStorefront(): Promise<StorefrontCheck> {
   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 } } }',
       {},
+      isShopAnswer,
       { context: false },
     );
     const shop = {
@@ -151,15 +159,9 @@ async function checkStorefront() {
 
 /**
  * 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 = [];
+function checkOptions(root: ParentNode, key: string, product: Product): Problem[] {
+  const problems: Problem[] = [];
   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')),
@@ -194,11 +196,8 @@ function checkOptions(root, key, product) {
 
 /**
  * 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) {
+async function checkProducts(root: ParentNode, report: DiagnoseReport): Promise<void> {
   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)));
@@ -229,14 +228,15 @@ async function checkProducts(root, report) {
   });
 }
 
-/**
- * @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() } = {}) {
+/** 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(),
+}: DiagnoseOptions = {}): Promise<DiagnoseReport> {
   const storefront = await checkStorefront();
-  /** @type {DiagnoseReport} */
-  const report = {
+  const report: DiagnoseReport = {
     version,
     config: configSummary(),
     apiVersion: apiVersionStatus(cfg.apiVersion, now),
@@ -269,8 +269,7 @@ export async function diagnose({ root = document, silent = false, version, now =
   return report;
 }
 
-/** @param {DiagnoseReport} report */
-function print(report) {
+function print(report: DiagnoseReport): void {
   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)`);

package/src/dom.ts

@@ -0,0 +1,268 @@
+/**
+ * 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.ts']`).
+ */
+import { cfg, reportError, warn } from './config.ts';
+import { attr, emit, get } from './markup.ts';
+import { storeHtmlFragment } from './store-html.ts';
+import { isRecord } from '../server/src/shared/json.ts';
+import { formatMoney as formatMoneyIn, productUrl as productUrlFor } from './shopify-values.ts';
+import type { Money } from './shopify-values.ts';
+
+export { attr, sel, get, has, qsa, scoped, emit, ownEvent, isOwnEvent, ANALYTICS_EVENTS } from './markup.ts';
+export { imageUrl, cdnUrl, sameImage, setImage } from './images.ts';
+export { hasTemplate, repeat, repeatKeyed } from './repeaters.ts';
+
+/**
+ * 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`).
+ *
+ * @returns `null` without the handle or id the path needs.
+ */
+export function productUrl(handle: string | null | undefined, id?: string | null): string | null {
+  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. */
+function formatOr<T>(format: () => T, fallback: T): T {
+  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.
+ *
+ * @returns `''` for no or a zero percentage.
+ */
+export function formatPercent(percentage: number | null | undefined, locale: string | undefined = cfg.locale): string {
+  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. */
+export function formatMoney(money: Money | null | undefined): string {
+  if (!money) return '';
+  if (cfg.formatMoney) return cfg.formatMoney(money, cfg.locale);
+  return formatMoneyIn(money, cfg.locale);
+}
+
+/** @returns The date in the configured locale, `''` without one. */
+export function formatDate(iso: string | null | undefined): string {
+  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.ts`). Everything else from Shopify is written as text (`setText`).
+ */
+export function setStoreHtml(el: Element, html: string | null | undefined): void {
+  el.replaceChildren(storeHtmlFragment(html, el.ownerDocument, cfg.embedOrigins));
+}
+
+const isTextField = (el: Element): el is HTMLInputElement | HTMLTextAreaElement =>
+  el.tagName === 'INPUT' || el.tagName === 'TEXTAREA';
+
+const isInput = (el: Element): el is HTMLInputElement => el.tagName === 'INPUT';
+
+/**
+ * Sets the text of `el`, or its value when it is a form field.
+ *
+ * @param value `null` and `undefined` clear it.
+ */
+export function setText(el: Element, value: string | number | boolean | null | undefined): void {
+  const text = value == null ? '' : String(value);
+  if (isTextField(el)) el.value = text;
+  else el.textContent = text;
+}
+
+const readText = (el: Element) => (isTextField(el) ? el.value : el.textContent);
+
+/** `setText` that hands a change after the first render to `onValueChange`, for scramble and roll effects. */
+export function setTextTracked(el: HTMLElement, value: string | number | boolean | null | undefined): void {
+  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`.
+ */
+function reveal(el: HTMLElement): void {
+  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. */
+export function show(el: HTMLElement, visible: boolean): void {
+  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. */
+export function setSelected(el: Element, selected: boolean): void {
+  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;
+}
+
+let layoutTimer: ReturnType<typeof setTimeout> | undefined;
+
+/**
+ * A global the page's own scripts set on `window`: `TETHER_CONFIG`, the site's config, `TETHER_INTEGRATION`, set by a
+ * framework integration (Astro) that starts Tether itself, and GSAP's `ScrollTrigger`. Another script wrote it, so it
+ * is read as unknown and checked where it is used.
+ */
+export const pageGlobal = (name: 'TETHER_CONFIG' | 'TETHER_INTEGRATION' | 'ScrollTrigger'): unknown =>
+  Reflect.get(window, name);
+
+/** Refreshes GSAP's ScrollTrigger, when the site has it: it measures positions that a height change makes stale. */
+function refreshScrollTrigger(): void {
+  // ScrollTrigger is a class, and `refresh` a static method of it.
+  const scrollTrigger = pageGlobal('ScrollTrigger');
+  if (typeof scrollTrigger !== 'function') return;
+  const refresh: unknown = Reflect.get(scrollTrigger, 'refresh');
+  if (typeof refresh === 'function') Reflect.apply(refresh, scrollTrigger, []);
+}
+
+/**
+ * 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`, also when either of those throws.
+ */
+export function notifyLayoutChanged(reason: string): void {
+  clearTimeout(layoutTimer);
+  layoutTimer = setTimeout(() => {
+    try {
+      if (cfg.onLayoutChange) cfg.onLayoutChange(reason);
+      else refreshScrollTrigger();
+    } catch (error) {
+      reportError(error, 'layout-changed');
+    }
+    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. */
+export function watchImages(root: ParentNode, reason: string): void {
+  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.
+ *
+ * @returns The task's result, `undefined` when it didn't run.
+ */
+export function busy<T>(el: Element, task: () => T | Promise<T>): Promise<T | undefined> {
+  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');
+    });
+}
+
+/** @returns The attribute's JSON, `null` when it is missing or not JSON (with a warning). */
+export function parseJSONAttr(el: Element | null | undefined, name: string): unknown {
+  const raw = el ? get(el, name) : null;
+  if (!raw) return null;
+  try {
+    const json: unknown = JSON.parse(raw);
+    return json;
+  } catch {
+    warn(`invalid JSON in ${attr(name)}`, el);
+    return null;
+  }
+}
+
+export type AttributeValue = string | number | boolean | null | undefined;
+
+/** @returns A JSON value as attribute text: `''` for none, an object or array as its JSON. */
+function attributeText(value: unknown): string {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  // What else parsed JSON holds: objects and arrays.
+  return JSON.stringify(value);
+}
+
+/**
+ * `tether-line-attributes`, JSON the site writes: `{ a: 1 }` or `[{ key, value }]`. An array entry that isn't an
+ * object is skipped.
+ */
+export function attributesFromJson(json: unknown): { key: string; value: string }[] {
+  if (Array.isArray(json)) {
+    const entries: unknown[] = json;
+    return entries
+      .filter(isRecord)
+      .map((entry) => ({ key: attributeText(entry['key']), value: attributeText(entry['value']) }));
+  }
+  if (!isRecord(json)) return [];
+  return Object.entries(json).map(([key, value]) => ({ key, value: attributeText(value) }));
+}
+
+/** `{ a: 1 }` or `[{ key, value }]` → `[{ key, value }]` as Shopify wants cart and line attributes. */
+export function toAttributes(
+  attributes: Record<string, AttributeValue> | { key: string | number; value?: AttributeValue }[] | null | undefined,
+): { key: string; value: string }[] {
+  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 ?? '') }));
+}