@occluze/tether 0.6.8 → 0.7.0

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

@@ -1,10 +1,10 @@
 /**
  * ProductScope: everything inside [tether-product="<handle>"] binds to one Shopify product: options, variants,
  * quantity, subscriptions and add to cart. The scope holds the visitor's choice and the actions on it;
- * `product-state.js` derives what the choice shows, `product-render.js` and `variant-render.js` write it, and
- * `product-events.js` turns clicks and changes into actions.
+ * `product-state.ts` derives what the choice shows, `product-render.ts` and `variant-render.ts` write it, and
+ * `product-events.ts` turns clicks and changes into actions.
  */
-import { cfg } from './config.js';
+import { cfg } from './config.ts';
 import {
   attr,
   sel,
@@ -16,41 +16,45 @@ import {
   notifyLayoutChanged,
   watchImages,
   parseJSONAttr,
-  toAttributes,
-} from './dom.js';
-import { Cart } from './cart.js';
-import { allPlans, allocationFor, findPlan, GID } from './selling-plans.js';
-import { initialChoice, normalisePurchase, productView, selectionOf } from './product-state.js';
-import { writeProduct } from './product-render.js';
-import { writeVariant } from './variant-render.js';
-import { bindProductEvents } from './product-events.js';
-/** @import { Product, ProductVariant } from './fragments.js' */
-/** @import { PlanInGroup } from './selling-plans.js' */
-/** @import { Purchase, Selection } from './product-state.js' */
+  attributesFromJson,
+} from './dom.ts';
+import { Cart } from './cart.ts';
+import { allPlans, allocationFor, findPlan, GID } from './selling-plans.ts';
+import {
+  initialChoice,
+  linePurchase,
+  normalisePurchase,
+  productView,
+  purchasePlanId,
+  selectionOf,
+} from './product-state.ts';
+import { writeProduct } from './product-render.ts';
+import { writeVariant } from './variant-render.ts';
+import { bindProductEvents } from './product-events.ts';
+import type { Product, ProductVariant } from './fragments.ts';
+import type { ShopifyCart } from './cart/store.ts';
+import type { PlanInGroup } from './selling-plans.ts';
+import type { Purchase, Selection } from './product-state.ts';
 
-/**
- * @typedef {object} CartLineInput What a scope adds to the cart.
- * @property {string} merchandiseId
- * @property {number} quantity
- * @property {string} [sellingPlanId]
- * @property {{ key: string, value: string }[]} [attributes]
- */
+/** What a scope adds to the cart. */
+interface CartLineInput {
+  merchandiseId: string;
+  quantity: number;
+  sellingPlanId?: string;
+  attributes?: { key: string; value: string }[];
+}
 
-/** @type {WeakMap<Element, ProductScope>} */
-export const scopes = new WeakMap();
+export const scopes = new WeakMap<Element, ProductScope>();
 
 const productSelector = () => sel('product');
 
 /**
  * Option names as written in the markup (the build's language), by product handle. In another language Shopify
  * translates them (Size → Größe), so markup names that aren't the product's are matched by position.
- *
- * @type {Map<string, string[]>}
  */
-const knownOptionNames = new Map();
+const knownOptionNames = new Map<string, string[]>();
 
-/** @param {readonly Pick<Product, 'handle' | 'options'>[]} products */
-export function rememberOptionNames(products) {
+export function rememberOptionNames(products: readonly Pick<Product, 'handle' | 'options'>[]): void {
   products.forEach((product) => {
     if (!knownOptionNames.has(product.handle)) {
       knownOptionNames.set(
@@ -61,23 +65,16 @@ export function rememberOptionNames(products) {
   });
 }
 
-/**
- * @param {Element} el
- * @returns {el is HTMLInputElement}
- */
-const isInput = (el) => el.tagName === 'INPUT';
+const isInput = (el: Element): el is HTMLInputElement => el.tagName === 'INPUT';
 
-/**
- * @param {Element} el
- * @returns {el is HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement}
- */
-const isField = (el) => el.tagName === 'INPUT' || el.tagName === 'SELECT' || el.tagName === 'TEXTAREA';
+const isField = (el: Element): el is HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement =>
+  el.tagName === 'INPUT' || el.tagName === 'SELECT' || el.tagName === 'TEXTAREA';
 
 /**
- * @param {HTMLElement} el A `tether-line-attribute` field.
- * @returns {string | null} Its value for the cart line; `null` for an unchecked or empty field.
+ * @param el A `tether-line-attribute` field.
+ * @returns Its value for the cart line; `null` for an unchecked or empty field.
  */
-function lineAttributeValue(el) {
+function lineAttributeValue(el: HTMLElement): string | null {
   if (isInput(el) && el.type === 'checkbox') {
     if (!el.checked) return null;
     return el.value && el.value !== 'on' ? el.value : 'Yes';
@@ -87,11 +84,16 @@ function lineAttributeValue(el) {
 }
 
 export class ProductScope {
-  /**
-   * @param {HTMLElement} root
-   * @param {Product} product
-   */
-  constructor(root, product) {
+  readonly root: HTMLElement;
+  product: Product;
+  plans: PlanInGroup[];
+  selected: Selection;
+  /** How the visitor buys; `setPurchase` and `selectPlan` change it. */
+  purchase: Purchase;
+  variant: ProductVariant | null;
+  quantity: number;
+
+  constructor(root: HTMLElement, product: Product) {
     this.root = root;
     this.product = product;
     this.plans = allPlans(product);
@@ -102,11 +104,8 @@ export class ProductScope {
       defaultPlan: get(root, 'default-plan'),
       defaultPurchase: get(root, 'default-purchase') || cfg.defaultPurchase,
     });
-    /** @type {Selection} */
     this.selected = choice.selected;
-    /** @type {Purchase} */
-    this.purchaseChoice = choice.purchase;
-    /** @type {ProductVariant | null} */
+    this.purchase = choice.purchase;
     this.variant = null;
     this.quantity = has(root, 'quantity') ? Math.max(0, parseInt(get(root, 'quantity') ?? '', 10) || 0) : 1;
 
@@ -122,12 +121,8 @@ export class ProductScope {
     emit('product-ready', { product, scope: this }, root);
   }
 
-  /**
-   * New data for the same product (a country switch). Keeps the visitor's choice.
-   *
-   * @param {Product} product
-   */
-  update(product) {
+  /** New data for the same product (a country switch). Keeps the visitor's choice. */
+  update(product: Product): void {
     const variantId = this.variant?.id;
     this.product = product;
     this.plans = allPlans(product);
@@ -141,20 +136,17 @@ export class ProductScope {
     emit('product-updated', { product, scope: this }, this.root);
   }
 
-  /**
-   * @param {string} selector
-   * @returns {HTMLElement[]} Matches in this scope, including the root itself (a card link with tether-bind="link").
-   */
-  $(selector) {
+  /** @returns Matches in this scope, including the root itself (a card link with tether-bind="link"). */
+  $(selector: string): HTMLElement[] {
     const inner = scoped(this.root, selector, productSelector());
     return this.root.matches(selector) ? [this.root, ...inner] : inner;
   }
 
   /**
-   * @param {string | null} authored An option name in the markup.
-   * @returns {string} The product's option of that name, or at that position in the build's language.
+   * @param authored An option name in the markup.
+   * @returns The product's option of that name, or at that position in the build's language.
    */
-  optName(authored) {
+  optName(authored: string | null): string {
     if (!authored) return '';
     const { options } = this.product;
     if (options.some((option) => option.name === authored)) return authored;
@@ -162,57 +154,35 @@ export class ProductScope {
     return options[index]?.name ?? authored;
   }
 
-  /** @returns {'one-time' | 'subscription'} */
-  get purchase() {
-    return this.purchaseChoice.kind;
-  }
-
-  /** @param {string} kind */
-  set purchase(kind) {
-    const wanted = kind === 'subscription' ? 'subscription' : 'one-time';
-    this.purchaseChoice = normalisePurchase(this.product, this.variant, { kind: wanted, planId: this.planId });
-  }
-
-  /** @returns {string | null} The plan bought on, or offered while buying once. */
-  get planId() {
-    return this.purchaseChoice.planId;
-  }
-
-  /** @param {string | null} planId */
-  set planId(planId) {
-    this.purchaseChoice = normalisePurchase(this.product, this.variant, { kind: this.purchase, planId });
-  }
-
-  /** @returns {PlanInGroup | null} */
-  get plan() {
-    return this.plans.find((plan) => plan.id === this.planId) ?? null;
+  get plan(): PlanInGroup | null {
+    const planId = purchasePlanId(this.purchase);
+    return this.plans.find((plan) => plan.id === planId) ?? null;
   }
 
   /** True when the current variant can be bought on a plan. */
-  get subscriptionAvailable() {
+  get subscriptionAvailable(): boolean {
     return this.plans.some((plan) => allocationFor(this.variant, plan.id));
   }
 
-  get isSubscription() {
-    return this.purchase === 'subscription' && allocationFor(this.variant, this.planId) !== null;
+  /** True when the line is bought on a plan: subscribing, and the variant is on the plan. */
+  get isSubscription(): boolean {
+    return linePurchase(this.purchase, this.variant).kind === 'subscription';
   }
 
-  /** @returns {CartLineInput | null} What would be added to the cart right now. */
-  getLine() {
+  /** @returns What would be added to the cart right now. */
+  getLine(): CartLineInput | null {
     if (!this.variant) return null;
-    /** @type {CartLineInput} */
-    const line = { merchandiseId: this.variant.id, quantity: this.quantity };
-    if (this.isSubscription && this.planId) line.sellingPlanId = this.planId;
+    const line: CartLineInput = { merchandiseId: this.variant.id, quantity: this.quantity };
+    const bought = linePurchase(this.purchase, this.variant);
+    if (bought.kind === 'subscription') line.sellingPlanId = bought.planId;
     const attributes = this.collectAttributes();
     if (attributes.length) line.attributes = attributes;
     return line;
   }
 
-  /** @returns {{ key: string, value: string }[]} `tether-line-attributes` and the filled `tether-line-attribute` fields. */
-  collectAttributes() {
-    // The site's own JSON: toAttributes writes every value with String(), whatever its type.
-    const json = /** @type {Parameters<typeof toAttributes>[0]} */ (parseJSONAttr(this.root, 'line-attributes'));
-    const fixed = toAttributes(json);
+  /** @returns `tether-line-attributes` and the filled `tether-line-attribute` fields. */
+  collectAttributes(): { key: string; value: string }[] {
+    const fixed = attributesFromJson(parseJSONAttr(this.root, 'line-attributes'));
     const fields = this.$(sel('line-attribute')).flatMap((el) => {
       const value = lineAttributeValue(el);
       return value === null ? [] : [{ key: get(el, 'line-attribute') ?? '', value }];
@@ -223,11 +193,8 @@ export class ProductScope {
   /**
    * Selects an option value. A combination no variant has moves to the closest variant with the value: the most other
    * choices kept, then one for sale.
-   *
-   * @param {string} name
-   * @param {string} value
    */
-  select(name, value) {
+  select(name: string, value: string): void {
     if (this.selected[name] === value) return;
     const withValue = this.product.variants.nodes.filter((variant) =>
       variant.selectedOptions.some((option) => option.name === name && option.value === value),
@@ -237,7 +204,7 @@ export class ProductScope {
     if (!firstWithValue) return;
     const next = { ...this.selected, [name]: value };
     if (!withValue.some((variant) => variant.selectedOptions.every((option) => next[option.name] === option.value))) {
-      const score = (/** @type {ProductVariant} */ variant) => {
+      const score = (variant: ProductVariant) => {
         const kept = variant.selectedOptions.filter(
           (option) => option.name !== name && this.selected[option.name] === option.value,
         ).length;
@@ -254,34 +221,31 @@ export class ProductScope {
     this.renderVariant();
   }
 
-  /** @param {string} id A variant gid or numeric id. */
-  selectVariant(id) {
+  /** @param id A variant gid or numeric id. */
+  selectVariant(id: string): void {
     const variant = this.product.variants.nodes.find((candidate) => candidate.id === GID.variant(id));
     if (!variant) return;
     this.selected = selectionOf(variant);
     this.renderVariant();
   }
 
-  /** @param {string | null} mode `subscription`, else buying once. */
-  setPurchase(mode) {
-    const kind = mode === 'subscription' ? 'subscription' : 'one-time';
-    const next = normalisePurchase(this.product, this.variant, { kind, planId: this.planId });
+  setPurchase(kind: Purchase['kind']): void {
+    const next = normalisePurchase(this.product, this.variant, kind, purchasePlanId(this.purchase));
     // The product decides when the wanted kind isn't possible (no plans, or a plan required).
-    if (next.kind === this.purchase) return;
-    this.purchaseChoice = next;
+    if (next.kind === this.purchase.kind) return;
+    this.purchase = next;
     this.renderVariant();
   }
 
-  /** @param {string | null} ref A plan id, numeric id, name or option value. */
-  selectPlan(ref) {
+  /** @param ref A plan id, numeric id, name or option value. */
+  selectPlan(ref: string | null): void {
     const plan = findPlan(this.product, ref);
     if (!plan) return;
-    this.purchaseChoice = { kind: 'subscription', planId: plan.id };
+    this.purchase = { kind: 'subscription', planId: plan.id };
     this.renderVariant();
   }
 
-  /** @param {number | string} quantity */
-  setQuantity(quantity) {
+  setQuantity(quantity: number | string): void {
     const minimum = has(this.root, 'quantity') ? 0 : 1;
     this.quantity = Math.max(minimum, parseInt(String(quantity), 10) || 0);
     this.$(sel('qty')).forEach((el) => {
@@ -290,8 +254,8 @@ export class ProductScope {
     this.renderVariant();
   }
 
-  /** @returns {Promise<unknown>} The cart after adding; `null` when the variant can't be added. */
-  async addToCart() {
+  /** @returns The cart after adding; `null` when the variant can't be added. */
+  async addToCart(): Promise<ShopifyCart | null> {
     if (!this.variant?.availableForSale) return null;
     const line = this.getLine();
     if (!line || line.quantity < 1) return null;
@@ -301,7 +265,7 @@ export class ProductScope {
   }
 
   /** Learns the markup's option names when they are the product's, then writes the product. */
-  renderProduct() {
+  renderProduct(): void {
     const { product } = this;
     if (!knownOptionNames.has(product.handle)) {
       const authored = this.$(`${sel('option-list')},select${sel('option')}`).map(
@@ -315,10 +279,10 @@ export class ProductScope {
   }
 
   /** Derives the view of the current choice, keeps its variant, selection and purchase, and writes it. */
-  renderVariant() {
+  renderVariant(): void {
     const view = productView(
       this.product,
-      { selected: this.selected, purchase: this.purchaseChoice, quantity: this.quantity },
+      { selected: this.selected, purchase: this.purchase, quantity: this.quantity },
       cfg.lowStock,
     );
     if (!view) {
@@ -327,7 +291,7 @@ export class ProductScope {
     }
     this.variant = view.variant;
     this.selected = view.selected;
-    this.purchaseChoice = view.purchase;
+    this.purchase = view.purchase;
     writeVariant(this, view);
     emit(
       'variant-changed',
@@ -336,7 +300,7 @@ export class ProductScope {
         variant: view.variant,
         selected: { ...view.selected },
         purchase: view.purchase.kind,
-        sellingPlanId: view.isSubscription ? view.purchase.planId : null,
+        sellingPlanId: view.line.kind === 'subscription' ? view.line.planId : null,
       },
       this.root,
     );

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

@@ -2,46 +2,37 @@
  * Lists rendered from a template: a repeater's first child in the designer is the template, and every item gets a
  * copy of it. The other children are placeholder content and are removed.
  */
-import { cfg, reportError, warn } from './config.js';
+import { cfg, reportError, warn } from './config.ts';
 
-/** @type {WeakMap<Element, HTMLElement | null>} Each repeater's template, captured on first render. */
-const templates = new WeakMap();
+/** Each repeater's template, captured on first render. */
+const templates = new WeakMap<Element, HTMLElement | null>();
 
-/**
- * @param {Element} container
- * @returns {boolean} True once the repeater's template has been captured (it may be empty after that).
- */
-export const hasTemplate = (container) => Boolean(templates.get(container));
+/** @returns True once the repeater's template has been captured (it may be empty after that). */
+export const hasTemplate = (container: Element): boolean => Boolean(templates.get(container));
 
 /**
  * A deep copy of a template. `cloneNode` is typed as returning a `Node`; a copy of an element is an element of the
  * same kind.
- *
- * @param {HTMLElement} template
  */
-const copyOf = (template) => /** @type {HTMLElement} */ (template.cloneNode(true));
+const copyOf = (template: HTMLElement) => template.cloneNode(true) as HTMLElement;
 
-/** @param {Element} container */
-function templateOf(container) {
+function templateOf(container: Element): HTMLElement | null {
   const known = templates.get(container);
   if (known !== undefined) return known;
   const first = container.firstElementChild;
   // Repeaters are HTML lists in the designer; their first child is an HTML element.
-  const template = first ? copyOf(/** @type {HTMLElement} */ (first)) : null;
+  const template = first ? copyOf(first as HTMLElement) : null;
   templates.set(container, template);
   container.replaceChildren();
   return template;
 }
 
-/**
- * Rebuilds the list on every render. Fine for images, tags, options.
- *
- * @template Item
- * @param {Element} container
- * @param {readonly Item[]} items
- * @param {(node: HTMLElement, item: Item, index: number) => void} render
- */
-export function repeat(container, items, render) {
+/** Rebuilds the list on every render. Fine for images, tags, options. */
+export function repeat<Item>(
+  container: Element,
+  items: readonly Item[],
+  render: (node: HTMLElement, item: Item, index: number) => void,
+): void {
   const template = templateOf(container);
   if (!template) {
     if (items.length) warn('repeater without a template child', container);
@@ -55,18 +46,14 @@ export function repeat(container, items, render) {
   });
 }
 
-/**
- * @typedef {object} KeyedHooks
- * @property {((node: HTMLElement) => void) | null} [onEnter] Runs on a node inserted for a new item.
- * @property {((node: HTMLElement, done: () => void) => void) | null} [onLeave] Runs on a node whose item is gone;
- *   `done()` removes it.
- */
+interface KeyedHooks {
+  /** Runs on a node inserted for a new item. */
+  onEnter?: ((node: HTMLElement) => void) | null;
+  /** Runs on a node whose item is gone; `done()` removes it. */
+  onLeave?: ((node: HTMLElement, done: () => void) => void) | null;
+}
 
-/**
- * @param {HTMLElement} node
- * @param {KeyedHooks['onLeave']} onLeave
- */
-function leave(node, onLeave) {
+function leave(node: HTMLElement, onLeave: KeyedHooks['onLeave']): void {
   const done = () => {
     node.remove();
   };
@@ -85,12 +72,15 @@ function leave(node, onLeave) {
 /**
  * Inserts the nodes of new items next to the item before them, leaving the existing nodes where they are.
  *
- * @param {Element} container
- * @param {HTMLElement[]} wanted Every item's node, in order.
- * @param {Set<HTMLElement>} fresh The nodes not yet in the container.
- * @param {KeyedHooks['onEnter']} onEnter
+ * @param wanted Every item's node, in order.
+ * @param fresh The nodes not yet in the container.
  */
-function insertFresh(container, wanted, fresh, onEnter) {
+function insertFresh(
+  container: Element,
+  wanted: HTMLElement[],
+  fresh: Set<HTMLElement>,
+  onEnter: KeyedHooks['onEnter'],
+): void {
   wanted.forEach((node, index) => {
     if (!fresh.has(node)) return;
     const previous = wanted[index - 1];
@@ -108,15 +98,14 @@ function insertFresh(container, wanted, fresh, onEnter) {
 /**
  * Keyed repeater: keeps existing nodes, inserts new ones, removes old ones. Used for cart lines, so values can
  * animate and lines can slide in and out.
- *
- * @template Item
- * @param {Element} container
- * @param {readonly Item[]} items
- * @param {(item: Item, index: number) => string | number} keyOf
- * @param {(node: HTMLElement, item: Item, index: number, isNew: boolean) => void} render
- * @param {KeyedHooks} [hooks]
  */
-export function repeatKeyed(container, items, keyOf, render, { onEnter, onLeave } = {}) {
+export function repeatKeyed<Item>(
+  container: Element,
+  items: readonly Item[],
+  keyOf: (item: Item, index: number) => string | number,
+  render: (node: HTMLElement, item: Item, index: number, isNew: boolean) => void,
+  { onEnter, onLeave }: KeyedHooks = {},
+): void {
   const template = templateOf(container);
   if (!template) {
     warn('repeater without a template child', container);
@@ -125,16 +114,15 @@ export function repeatKeyed(container, items, keyOf, render, { onEnter, onLeave
 
   const keyAttribute = `data-${cfg.prefix}-key`;
   const leavingAttribute = `data-${cfg.prefix}-leaving`;
+  // The list's children are copies of its template, HTML elements like it.
   const live = () =>
-    [.../** @type {HTMLCollectionOf<HTMLElement>} */ (container.children)].filter(
+    [...(container.children as HTMLCollectionOf<HTMLElement>)].filter(
       (node) => node.hasAttribute(keyAttribute) && !node.hasAttribute(leavingAttribute),
     );
 
   const existing = new Map(live().map((node) => [node.getAttribute(keyAttribute), node]));
-  /** @type {HTMLElement[]} */
-  const wanted = [];
-  /** @type {Set<HTMLElement>} */
-  const fresh = new Set();
+  const wanted: HTMLElement[] = [];
+  const fresh = new Set<HTMLElement>();
 
   items.forEach((item, index) => {
     const key = String(keyOf(item, index));