@occluze/tether 0.6.8 → 0.7.0

package/src/controls/{discount.js → discount.ts}

@@ -3,43 +3,25 @@
  * (`tether-discount-remove` inside `tether-discount-code`), delegated from the document. A code Shopify refuses marks
  * the form `is-invalid` (and the input `aria-invalid`) until the visitor types again.
  */
-import { reportError } from '../config.js';
-import { TetherError } from '../client.js';
-import { Cart } from '../cart.js';
-import { attr, sel, busy, emit } from '../dom.js';
+import { reportError } from '../config.ts';
+import { TetherError } from '../client.ts';
+import { Cart } from '../cart.ts';
+import { attr, sel, busy, emit } from '../dom.ts';
 
-/**
- * @param {EventTarget | null} target
- * @returns {target is Element}
- */
-const isElement = (target) => target instanceof window.Element;
+const isElement = (target: EventTarget | null): target is Element => target instanceof window.Element;
 
-/**
- * @param {Element} form
- * @returns {HTMLInputElement | null}
- */
-function codeInputOf(form) {
+function codeInputOf(form: Element): HTMLInputElement | null {
   const input = form.querySelector(sel('discount-input')) ?? form.querySelector('input');
   return input instanceof window.HTMLInputElement ? input : null;
 }
 
-/**
- * @param {Element} form
- * @param {HTMLInputElement | null} input
- * @param {boolean} invalid
- */
-function markInvalid(form, input, invalid) {
+function markInvalid(form: Element, input: HTMLInputElement | null, invalid: boolean): void {
   form.classList.toggle('is-invalid', invalid);
   if (invalid) input?.setAttribute('aria-invalid', 'true');
   else input?.removeAttribute('aria-invalid');
 }
 
-/**
- * @param {Element} form
- * @param {HTMLInputElement | null} input
- * @param {string} code
- */
-async function applyCode(form, input, code) {
+async function applyCode(form: Element, input: HTMLInputElement | null, code: string): Promise<void> {
   try {
     await Cart.applyDiscount(code);
     markInvalid(form, input, false);
@@ -52,8 +34,7 @@ async function applyCode(form, input, code) {
   }
 }
 
-/** @param {SubmitEvent} event */
-function onSubmit(event) {
+function onSubmit(event: SubmitEvent): void {
   const { target } = event;
   const form = isElement(target) ? target.closest(sel('discount-form')) : null;
   if (!form) return;
@@ -64,8 +45,7 @@ function onSubmit(event) {
   void busy(form, () => applyCode(form, input, code));
 }
 
-/** @param {Event} event */
-function onInput(event) {
+function onInput(event: Event): void {
   const { target } = event;
   if (!isElement(target)) return;
   const form = target.closest(sel('discount-form'));
@@ -74,21 +54,20 @@ function onInput(event) {
   target.removeAttribute('aria-invalid');
 }
 
-/** @param {MouseEvent} event */
-function onClick(event) {
+function onClick(event: MouseEvent): void {
   const { target } = event;
   const remove = isElement(target) ? target.closest(sel('discount-remove')) : null;
   if (!remove) return;
   event.preventDefault();
   const code = remove.closest(sel('discount-code'))?.getAttribute(attr('discount-code'));
   if (!code) return;
-  Cart.removeDiscount(code).catch((/** @type {unknown} */ error) => {
+  Cart.removeDiscount(code).catch((error: unknown) => {
     reportError(error, 'discount');
   });
 }
 
 /** Binds the document-wide listeners, once per page load of the script. */
-export function bindDiscountControls() {
+export function bindDiscountControls(): void {
   // Capture: the submit is handled before a router (Astro's ClientRouter) turns it into a navigation.
   document.addEventListener('submit', onSubmit, true);
   document.addEventListener('input', onInput);

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

@@ -3,28 +3,20 @@
  * group add buttons, the cart or market changing in another tab, and shareable variant links. A part that can't load
  * (a self-hosted site without `tether.extras.min.js`) is reported, so the missing file shows.
  */
-import { cfg, reportError } from '../config.js';
-import { attr, sel, busy } from '../dom.js';
-import { loadPart } from '../lazy.js';
-/** @import { ShopifyCart } from '../cart/store.js' */
+import { cfg, reportError } from '../config.ts';
+import { attr, sel, busy, isOwnEvent } from '../dom.ts';
+import { loadPart } from '../lazy.ts';
+import type { ShopifyCart } from '../cart/store.ts';
 
-/** @typedef {Parameters<typeof import('../extras.js').writeVariantUrl>[1]} VariantChoice */
+/** `[tether-group]` with `[tether-group-add]`: adds every product scope inside the group in one request. */
+export const addGroup = (button: Element): Promise<ShopifyCart | null> =>
+  loadPart('extras').then((part) => part.addGroup(button));
 
-/**
- * `[tether-group]` with `[tether-group-add]`: adds every product scope inside the group in one request.
- *
- * @param {Element} button
- * @returns {Promise<ShopifyCart | null>}
- */
-export const addGroup = (button) => loadPart('extras').then((part) => part.addGroup(button));
-
-/** @param {unknown} error */
-const reportExtrasError = (error) => {
+const reportExtrasError = (error: unknown) => {
   reportError(error, 'extras');
 };
 
-/** @param {MouseEvent} event */
-function onClick(event) {
+function onClick(event: MouseEvent): void {
   const { target } = event;
   const button = target instanceof window.Element ? target.closest(sel('group-add')) : null;
   if (!button) return;
@@ -32,8 +24,7 @@ function onClick(event) {
   busy(button, () => addGroup(button)).catch(reportExtrasError);
 }
 
-/** @param {StorageEvent} event */
-function onStorage(event) {
+function onStorage(event: StorageEvent): void {
   if (!cfg.domain || !event.key?.startsWith(`${cfg.prefix}:`)) return;
   loadPart('extras')
     .then((part) => {
@@ -42,8 +33,9 @@ function onStorage(event) {
     .catch(reportExtrasError);
 }
 
-/** @param {CustomEvent<VariantChoice>} event `tether:variant-changed`, which a product scope emits. */
-function onVariantChanged(event) {
+/** @param event `tether:variant-changed`, which a product scope emits; one another script dispatches is ignored. */
+function onVariantChanged(event: Event): void {
+  if (!isOwnEvent(event, 'variant-changed')) return;
   const { target } = event;
   if (!(target instanceof window.Element)) return;
   if (!cfg.variantUrl && !target.hasAttribute(attr('variant-url'))) return;
@@ -55,9 +47,8 @@ function onVariantChanged(event) {
 }
 
 /** Binds the document-wide listeners, once per page load of the script. */
-export function bindExtrasControls() {
+export function bindExtrasControls(): void {
   document.addEventListener('click', onClick);
   window.addEventListener('storage', onStorage);
-  // Only product scopes emit this event, always with a CustomEvent.
-  document.addEventListener(`${cfg.prefix}:variant-changed`, /** @type {EventListener} */ (onVariantChanged));
+  document.addEventListener(`${cfg.prefix}:variant-changed`, onVariantChanged);
 }

package/src/controls/{navigation.js → navigation.ts}

@@ -3,31 +3,29 @@
  * `astro:before-swap`) mounts each new page in its market and closes the cart while leaving; a country select
  * switches the market; back online, what failed to load loads again.
  */
-import { cfg, reportError } from '../config.js';
-import { attr, sel } from '../dom.js';
-import { liveLists, retryFailed } from '../mounting.js';
-import { marketForArrival, setCountry } from '../page-market.js';
+import { cfg, reportError } from '../config.ts';
+import { attr, sel } from '../dom.ts';
+import { liveLists, retryFailed } from '../mounting.ts';
+import { marketForArrival, setCountry } from '../page-market.ts';
 
-/**
- * @typedef {object} PageHooks What the entry module does for a page.
- * @property {() => Promise<unknown>} ready Settles once `init()` has applied the visitor's market.
- * @property {(root: Document) => unknown} mount
- * @property {() => void} unmount
- */
+/** What the entry module does for a page. */
+interface PageHooks {
+  /** Settles once `init()` has applied the visitor's market. */
+  ready: () => Promise<unknown>;
+  mount: (root: Document) => unknown;
+  unmount: () => void;
+}
 
-/**
- * The body the last full-document mount ran on: Astro's first `astro:page-load` comes after that mount.
- *
- * @type {HTMLElement | null} */
-let mountedBody = null;
+/** The body the last full-document mount ran on: Astro's first `astro:page-load` comes after that mount. */
+let mountedBody: HTMLElement | null = null;
 
 /** Records a mount of the whole document, so the `astro:page-load` of the same page sends no second round of requests. */
-export function rememberDocumentMount() {
+export function rememberDocumentMount(): void {
   mountedBody = document.body;
 }
 
-/** @param {PageHooks} hooks */
-async function onPageLoad(hooks) {
+/** Mounts the page Astro swapped in. It rejects when `init()` failed or the mount threw; the listener reports that. */
+async function onPageLoad(hooks: PageHooks): Promise<void> {
   await hooks.ready();
   const target = marketForArrival();
   if (!target) {
@@ -42,10 +40,11 @@ async function onPageLoad(hooks) {
   hooks.mount(document);
 }
 
-/** @param {PageHooks} hooks */
-function bindAstroRouter(hooks) {
+function bindAstroRouter(hooks: PageHooks): void {
   document.addEventListener('astro:page-load', () => {
-    void onPageLoad(hooks);
+    onPageLoad(hooks).catch((error: unknown) => {
+      reportError(error, 'page mount');
+    });
   });
   document.addEventListener('astro:before-swap', () => {
     mountedBody = null;
@@ -53,12 +52,11 @@ function bindAstroRouter(hooks) {
   });
 }
 
-/** @param {Event} event */
-function onChange(event) {
+function onChange(event: Event): void {
   const { target } = event;
   if (!(target instanceof window.HTMLSelectElement) || !target.matches(sel('country-select'))) return;
   if (!target.value) return;
-  setCountry(target.value).catch((/** @type {unknown} */ error) => {
+  setCountry(target.value).catch((error: unknown) => {
     reportError(error, 'country');
   });
 }
@@ -71,12 +69,8 @@ function onOnline() {
   });
 }
 
-/**
- * Binds the document-wide listeners, once per page load of the script.
- *
- * @param {PageHooks} hooks
- */
-export function bindNavigation(hooks) {
+/** Binds the document-wide listeners, once per page load of the script. */
+export function bindNavigation(hooks: PageHooks): void {
   if (cfg.astro) bindAstroRouter(hooks);
   document.addEventListener('change', onChange);
   window.addEventListener('online', onOnline);

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

@@ -2,19 +2,22 @@
  * The markup half of `Tether.diagnose()`: problems that show without the network. It knows every value and attribute
  * name Tether reads, so a typo gets a "did you mean".
  */
-import { cfg } from './config.js';
-import { attr, sel, get, qsa, hasTemplate } from './dom.js';
-import { resolveProductKey, boundary } from './status.js';
+import { cfg } from './config.ts';
+import { attr, sel, get, qsa, hasTemplate } from './dom.ts';
+import { resolveProductKey, boundary } from './status.ts';
 
-/** @typedef {'error' | 'warn'} ProblemLevel */
-/**
- * @typedef {object} Problem
- * @property {ProblemLevel} level
- * @property {string} message
- * @property {string} [element] The element, described for people: `<div#id.class>`.
- * @property {Element} [el] The element itself, for the console.
- */
-/** @typedef {(level: ProblemLevel, message: string, el?: Element) => void} AddProblem */
+type ProblemLevel = 'error' | 'warn';
+
+export interface Problem {
+  level: ProblemLevel;
+  message: string;
+  /** The element, described for people: `<div#id.class>`. */
+  element?: string;
+  /** The element itself, for the console. */
+  el?: Element;
+}
+
+type AddProblem = (level: ProblemLevel, message: string, el?: Element) => void;
 
 /** Every `tether-show` value. */
 const SHOW = new Set([
@@ -139,14 +142,9 @@ const IMAGE_BIND = /^image:\d+$/;
 /** The class names of an element that its description shows. */
 const DESCRIBED_CLASSES = 2;
 
-/**
- * @param {string} from
- * @param {string} to
- * @returns {number} The Levenshtein distance: the fewest single-character edits from one to the other.
- */
-function editDistance(from, to) {
-  /** @type {number[]} */
-  let previous = Array.from({ length: to.length + 1 }, (_, index) => index);
+/** The Levenshtein distance: the fewest single-character edits from one string to the other. */
+function editDistance(from: string, to: string): number {
+  let previous: number[] = Array.from({ length: to.length + 1 }, (_, index) => index);
   for (let i = 1; i <= from.length; i++) {
     const row = [i];
     for (let j = 1; j <= to.length; j++) {
@@ -159,14 +157,13 @@ function editDistance(from, to) {
 }
 
 /**
- * @param {string} value What the markup says.
- * @param {Iterable<string>} options What Tether reads.
- * @param {string} [prefix] Put before the suggestion, e.g. `tether-`.
- * @returns {string} ` Did you mean "…"?` for an option close enough to `value`, else `''`.
+ * @param value What the markup says.
+ * @param options What Tether reads.
+ * @param prefix Put before the suggestion, e.g. `tether-`.
+ * @returns ` Did you mean "…"?` for an option close enough to `value`, else `''`.
  */
-export function didYouMean(value, options, prefix = '') {
-  /** @type {string | null} */
-  let best = null;
+export function didYouMean(value: string, options: Iterable<string>, prefix = ''): string {
+  let best: string | null = null;
   let bestDistance = Infinity;
   for (const option of options) {
     const distance = editDistance(value, option);
@@ -179,11 +176,8 @@ export function didYouMean(value, options, prefix = '') {
   return best !== null && bestDistance <= closeEnough ? ` Did you mean "${prefix}${best}"?` : '';
 }
 
-/**
- * @param {Element} el
- * @returns {string} `<div#id.first.second>`.
- */
-function describe(el) {
+/** `el` described for people: `<div#id.first.second>`. */
+function describe(el: Element): string {
   const id = el.id ? `#${el.id}` : '';
   const classes = el.className && typeof el.className === 'string' ? el.className.trim().split(/\s+/) : [];
   const classText = classes.length ? `.${classes.slice(0, DESCRIBED_CLASSES).join('.')}` : '';
@@ -192,11 +186,7 @@ function describe(el) {
 
 const listSelector = () => `${sel('collection')},${sel('products')},${sel('recommendations')}`;
 
-/**
- * @param {ParentNode} root
- * @param {AddProblem} add
- */
-function checkProductKeys(root, add) {
+function checkProductKeys(root: ParentNode, add: AddProblem): void {
   qsa(root, sel('product')).forEach((el) => {
     // A list card gets its handle when the list renders.
     if (el.closest(listSelector()) && el.closest(sel('list'))) return;
@@ -213,11 +203,7 @@ function checkProductKeys(root, add) {
   });
 }
 
-/**
- * @param {ParentNode} root
- * @param {AddProblem} add
- */
-function checkPlacement(root, add) {
+function checkPlacement(root: ParentNode, add: AddProblem): void {
   for (const name of PRODUCT_ONLY) {
     qsa(root, sel(name)).forEach((el) => {
       if (el.closest(sel('product'))) return;
@@ -242,11 +228,7 @@ function checkPlacement(root, add) {
   });
 }
 
-/**
- * @param {ParentNode} root
- * @param {AddProblem} add
- */
-function checkValues(root, add) {
+function checkValues(root: ParentNode, add: AddProblem): void {
   qsa(root, sel('show')).forEach((el) => {
     const value = get(el, 'show') ?? '';
     if (!SHOW.has(value)) add('warn', `Unknown ${attr('show')}="${value}".${didYouMean(value, SHOW)}`, el);
@@ -258,11 +240,7 @@ function checkValues(root, add) {
   });
 }
 
-/**
- * @param {ParentNode} root
- * @param {AddProblem} add
- */
-function checkMetafieldBinds(root, add) {
+function checkMetafieldBinds(root: ParentNode, add: AddProblem): void {
   qsa(root, sel('bind')).forEach((el) => {
     const value = get(el, 'bind') || '';
     if (!value.startsWith(METAFIELD_BIND)) return;
@@ -278,14 +256,10 @@ function checkMetafieldBinds(root, add) {
 
 /**
  * Typos in attribute names (tether-bnd, tether-add-to-card) do nothing, silently. Each unknown name is reported once.
- *
- * @param {ParentNode} root
- * @param {AddProblem} add
  */
-function checkAttributeNames(root, add) {
+function checkAttributeNames(root: ParentNode, add: AddProblem): void {
   const prefix = `${cfg.prefix}-`;
-  /** @type {Set<string>} */
-  const reported = new Set();
+  const reported = new Set<string>();
   qsa(root, '*').forEach((el) => {
     for (const { name: fullName } of el.attributes) {
       if (!fullName.startsWith(prefix)) continue;
@@ -297,11 +271,7 @@ function checkAttributeNames(root, add) {
   });
 }
 
-/**
- * @param {ParentNode} root
- * @param {AddProblem} add
- */
-function checkCartAndScopes(root, add) {
+function checkCartAndScopes(root: ParentNode, add: AddProblem): void {
   const drawers = qsa(root, sel('cart-drawer')).length;
   if (qsa(root, sel('cart-open')).length && !drawers) {
     add('warn', `${attr('cart-open')} exists but there is no ${attr('cart-drawer')} on this page.`);
@@ -312,15 +282,10 @@ function checkCartAndScopes(root, add) {
   });
 }
 
-/**
- * @param {ParentNode} [root]
- * @returns {Problem[]} The markup problems in `root`, in page order per check.
- */
-export function checkMarkup(root = document) {
-  /** @type {Problem[]} */
-  const problems = [];
-  /** @type {AddProblem} */
-  const add = (level, message, el) => {
+/** The markup problems in `root`, in page order per check. */
+export function checkMarkup(root: ParentNode = document): Problem[] {
+  const problems: Problem[] = [];
+  const add: AddProblem = (level, message, el) => {
     problems.push(el ? { level, message, element: describe(el), el } : { level, message });
   };
   checkProductKeys(root, add);