@occluze/tether 0.6.6 → 0.6.8

package/src/client.js

@@ -1,35 +1,79 @@
 /**
- * Storefront API client: one fetch wrapper with @inContext, retries and
- * readable errors. Exposed as Tether.query() for anything Tether doesn't cover.
+ * The one Storefront API client: a fetch wrapper that adds the market (`@inContext`), retries what Shopify asks to be
+ * retried, and turns every failure into a `TetherError`. The browser (`gql`, also `Tether.query()`) and the server
+ * helpers (`request` with their own config) share it.
  */
 import { cfg, log } from './config.js';
+import { toCountry, toLanguage } from './market-codes.js';
+/** @import { TetherConfig } from './config.js' */
+
+/**
+ * @typedef {'NOT_FOUND' | 'NETWORK' | 'NOT_CONFIGURED' | 'NOT_LOGGED_IN' | 'NOT_ALLOWED' | 'INVALID'
+ *   | 'INVALID_COUNTRY' | 'INVALID_DISCOUNT' | 'SESSION_ENDED' | 'TOKEN_FAILED' | 'ERROR' | `HTTP_${number}`}
+ *   TetherErrorCode
+ */
+/** @typedef {{ message: string, extensions?: { code?: string } }} GraphQLError */
+/** @typedef {{ data?: unknown, errors?: GraphQLError[] }} GraphQLResponse The response shape the GraphQL spec sets. */
+/** @typedef {{ message: string, field?: string[] | null, code?: string | null }} UserError */
+/**
+ * @typedef {object} TetherErrorDetails
+ * @property {TetherErrorCode} [code] Default `HTTP_<status>` with a status, else `ERROR`.
+ * @property {number} [status] The HTTP status of the response that failed.
+ * @property {GraphQLError[]} [errors] The GraphQL errors of that response.
+ * @property {readonly UserError[]} [userErrors] A mutation's user errors.
+ */
 
 export class TetherError extends Error {
+  /**
+   * @param {string} message
+   * @param {TetherErrorDetails} [details]
+   */
   constructor(message, { status, errors, userErrors, code } = {}) {
     super(message);
     this.name = 'TetherError';
-    this.code = code || (status ? `HTTP_${status}` : 'ERROR');
+    /** @type {TetherErrorCode} */
+    this.code = code ?? (status ? `HTTP_${status}` : 'ERROR');
+    /** @type {number | undefined} */
     this.status = status;
+    /** @type {GraphQLError[] | undefined} */
     this.errors = errors;
+    /** @type {readonly UserError[] | undefined} */
     this.userErrors = userErrors;
   }
 }
 
+/**
+ * What a request needs from a config: the browser's `cfg`, or a config the server helpers build.
+ *
+ * @typedef {Pick<TetherConfig, 'domain' | 'token' | 'apiVersion' | 'country' | 'language' | 'maxAge' | 'retries'>
+ *   & { fetch?: typeof fetch }} StorefrontConfig
+ */
+/** @typedef {{ context?: boolean }} RequestOptions `context: false` sends the query without `@inContext`. */
+
+/**
+ * @param {Pick<TetherConfig, 'domain' | 'apiVersion'>} [conf]
+ * @returns {string} The Storefront GraphQL endpoint of `conf`'s store.
+ */
 export function endpoint(conf = cfg) {
   return `https://${conf.domain}/api/${conf.apiVersion}/graphql.json`;
 }
 
 /**
- * Adds @inContext(country, language) to the first operation in the document,
- * so prices, currency and translations follow the configured market.
- * Operations are always written first, fragments after, so the first match is
- * the operation.
+ * Adds @inContext(country, language) to the first operation in the document, so prices, currency and translations
+ * follow the configured market. Operations are always written first, fragments after, so the first match is the
+ * operation. A country or language that isn't a valid code is left out.
+ *
+ * @param {string} query
+ * @param {{ country?: string | undefined, language?: string | undefined }} [ctx]
+ * @returns {string}
  */
 export function withContext(query, ctx = cfg) {
   const args = [];
-  if (ctx.country) args.push(`country: ${String(ctx.country).toUpperCase()}`);
-  if (ctx.language) args.push(`language: ${String(ctx.language).toUpperCase().replace('-', '_')}`);
-  if (!args.length || /@inContext/.test(query)) return query;
+  const country = toCountry(ctx.country);
+  const language = toLanguage(ctx.language);
+  if (country) args.push(`country: ${country}`);
+  if (language) args.push(`language: ${language}`);
+  if (!args.length || query.includes('@inContext')) return query;
 
   const tag = `@inContext(${args.join(', ')})`;
   // Named (query Name($x: T)), anonymous (query { … }) and shorthand ({ … }) queries.
@@ -37,95 +81,187 @@ export function withContext(query, ctx = cfg) {
   return query.replace(/^(\s*(?:query|mutation)(?:\s+\w+)?\s*(?:\([^)]*\))?)/, `$1 ${tag}`);
 }
 
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Backoff after a network error or a 429/5xx: this times 2^attempt. */
+const RETRY_BACKOFF_MS = 300;
+/** Backoff after Shopify's `THROTTLED` error, which asks for a longer wait: this times 2^attempt. */
+const THROTTLE_BACKOFF_MS = 500;
+/** Shopify's status for a request its bot protection rejected; retrying doesn't help. */
+const SECURITY_REJECTION = 430;
+
+/**
+ * `quantityAvailable` needs the token's `unauthenticated_read_product_inventory` scope; without it Shopify refuses the
+ * whole query with an error naming the field. That refusal is learned once per page and store: every later query to
+ * the store goes out without the field, so stock levels are unknown and everything else works for one extra request.
+ */
+const INVENTORY_FIELD = 'quantityAvailable';
+
+/** @type {Set<string>} The stores (domain, version and token) whose token can't read inventory. */
+const storesWithoutInventory = new Set();
 
-/** What a status means, for errors Shopify sends without a message (401/403 have none). */
+/** @param {StorefrontConfig} conf */
+const storeOf = (conf) => `${conf.domain} ${conf.apiVersion} ${conf.token}`;
+
+/** @param {number} ms */
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * What a status means, for errors Shopify sends without a message (401/403 have none).
+ *
+ * @param {number} status
+ * @param {StorefrontConfig} conf
+ */
 function statusText(status, conf) {
   if (status === 401 || status === 403) {
-    return `Shopify rejected the Storefront token for ${conf.domain} (${status}): use the public Storefront API token (Headless channel)${/^shpat_/.test(conf.token) ? ', not an Admin API token (shpat_…)' : ''}`;
+    const adminHint = conf.token.startsWith('shpat_') ? ', not an Admin API token (shpat_…)' : '';
+    return `Shopify rejected the Storefront token for ${conf.domain} (${status}): use the public Storefront API token (Headless channel)${adminHint}`;
   }
-  return status === 404 ? `Store or API version not found (404): check domain ${conf.domain} and apiVersion ${conf.apiVersion}` : `HTTP ${status} from ${conf.domain}`;
+  if (status === 404) {
+    return `Store or API version not found (404): check domain ${conf.domain} and apiVersion ${conf.apiVersion}`;
+  }
+  return `HTTP ${status} from ${conf.domain}`;
 }
 
 /**
- * One Storefront API request with retries, for any config object (the browser's shared config,
- * or the server module's own). gql() below is the browser version.
+ * @param {Response} res
+ * @param {GraphQLError[]} errors
+ * @param {StorefrontConfig} conf
  */
-export async function request(conf, query, variables = {}, { context = true } = {}) {
-  if (!conf.domain || !conf.token) {
-    throw new TetherError('Tether is not configured: domain and token are required', { code: 'NOT_CONFIGURED' });
-  }
-
-  // Shopify caches the response of an identical query text (prices included, for hours after a
-  // change). A time bucket in a comment keeps answers at most maxAge seconds old (default 60).
-  let text = context ? withContext(query, conf) : query;
-  const age = conf.maxAge ?? 60;
-  if (age > 0 && !/^\s*mutation\b/.test(text)) text += ` #${Math.floor(Date.now() / (age * 1000))}`;
-  const body = JSON.stringify({ query: text, variables });
-  let attempt = 0;
+function graphQLFailure(res, errors, conf) {
+  const message = errors
+    .map((error) => error.message)
+    .filter(Boolean)
+    .join(' | ');
+  let text = message || 'Storefront API error';
+  if (!res.ok) text = res.status === 401 || res.status === 403 || !message ? statusText(res.status, conf) : message;
+  return new TetherError(text, { status: res.status, errors });
+}
 
-  for (;;) {
-    let res;
-    try {
-      res = await (conf.fetch || fetch)(endpoint(conf), {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-          'X-Shopify-Storefront-Access-Token': conf.token,
-        },
-        body,
-      });
-    } catch (err) {
-      if (attempt++ < conf.retries) { await sleep(300 * 2 ** attempt); continue; }
-      throw new TetherError(`Network error: ${err.message}`, { code: 'NETWORK' });
-    }
+/**
+ * @typedef {{ kind: 'data', data: unknown }
+ *   | { kind: 'retry', backoffMs: number }
+ *   | { kind: 'inventory-refused' }} Attempt
+ */
 
-    if (res.status === 430) throw new TetherError('Shopify security rejection (430)', { status: 430 });
+/**
+ * One request. Failures that retrying can't fix throw.
+ *
+ * @param {StorefrontConfig} conf
+ * @param {string} query
+ * @param {Record<string, unknown>} variables
+ * @param {boolean} canRetry False on the last attempt: a retryable failure then throws too.
+ * @returns {Promise<Attempt>}
+ */
+async function attempt(conf, query, variables, canRetry) {
+  let res;
+  try {
+    res = await (conf.fetch ?? fetch)(endpoint(conf), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', 'X-Shopify-Storefront-Access-Token': conf.token },
+      body: JSON.stringify({ query, variables }),
+    });
+  } catch (error) {
+    if (canRetry) return { kind: 'retry', backoffMs: RETRY_BACKOFF_MS };
+    throw new TetherError(`Network error: ${error instanceof Error ? error.message : String(error)}`, {
+      code: 'NETWORK',
+    });
+  }
+  if (res.status === SECURITY_REJECTION) {
+    throw new TetherError('Shopify security rejection (430)', { status: SECURITY_REJECTION });
+  }
+  if (canRetry && (res.status === 429 || res.status >= 500)) {
+    return { kind: 'retry', backoffMs: RETRY_BACKOFF_MS };
+  }
 
-    const retryable = res.status === 429 || res.status >= 500;
-    if (retryable && attempt++ < conf.retries) {
-      log('retry', res.status, attempt);
-      await sleep(300 * 2 ** attempt);
-      continue;
+  /** @type {unknown} */
+  let json;
+  try {
+    json = await res.json();
+  } catch {
+    const text = res.ok ? `Invalid response (${res.status})` : statusText(res.status, conf);
+    throw new TetherError(text, { status: res.status });
+  }
+  // The Storefront API answers in the shape the GraphQL spec sets, or with an error page that isn't JSON.
+  const { data, errors = [] } = /** @type {GraphQLResponse | null} */ (json) ?? {};
+  if (errors.length) {
+    if (query.includes(INVENTORY_FIELD) && errors.some((error) => error.message.includes(INVENTORY_FIELD))) {
+      return { kind: 'inventory-refused' };
     }
-
-    let json;
-    try { json = await res.json(); } catch {
-      throw new TetherError(res.ok ? `Invalid response (${res.status})` : statusText(res.status, conf), { status: res.status });
+    if (canRetry && errors.some((error) => error.extensions?.code === 'THROTTLED')) {
+      return { kind: 'retry', backoffMs: THROTTLE_BACKOFF_MS };
     }
+    throw graphQLFailure(res, errors, conf);
+  }
+  if (!res.ok) throw new TetherError(statusText(res.status, conf), { status: res.status });
+  return { kind: 'data', data };
+}
 
-    if (json.errors?.length) {
-      // Token without unauthenticated_read_product_inventory: drop the field and retry.
-      const inventoryDenied = json.errors.some((e) => /quantityAvailable/.test(e.message || ''));
-      if (inventoryDenied && /\bquantityAvailable\b/.test(body)) {
-        log('no inventory permission, retrying without quantityAvailable');
-        return request(conf, query.replace(/\bquantityAvailable\b/g, ''), variables, { context });
-      }
-      // An older apiVersion without cart warnings (before 2024-07): retry without them.
-      if (json.errors.some((e) => /'warnings'/.test(e.message || '')) && /warnings \{ code message target \}/.test(query)) {
-        return request(conf, query.replace(/ warnings \{ code message target \}/g, ''), variables, { context });
-      }
-      const throttled = json.errors.some((e) => e.extensions?.code === 'THROTTLED');
-      if (throttled && attempt++ < conf.retries) { await sleep(500 * 2 ** attempt); continue; }
-      const message = json.errors.map((e) => e.message).filter(Boolean).join(' | ');
-      throw new TetherError(res.ok ? message || 'Storefront API error' : (res.status === 401 || res.status === 403 || !message ? statusText(res.status, conf) : message), {
-        status: res.status, errors: json.errors,
-      });
+/**
+ * One Storefront API request, for any config: the browser's shared one (`gql`) or one the server helpers build.
+ * Queries carry a time bucket so Shopify's cache of an identical query text is at most `maxAge` seconds old, and
+ * leave out inventory for a store whose token can't read it (`INVENTORY_FIELD`).
+ *
+ * @template T The shape of the query's `data`, which the caller's query text decides.
+ * @param {StorefrontConfig} conf
+ * @param {string} query
+ * @param {Record<string, unknown>} [variables]
+ * @param {RequestOptions} [options]
+ * @returns {Promise<T>}
+ * @throws {TetherError} `NOT_CONFIGURED` without a domain or token, `NETWORK` when the store can't be reached,
+ *   `HTTP_<status>` for an HTTP or GraphQL failure.
+ */
+export async function request(conf, query, variables = {}, { context = true } = {}) {
+  if (!conf.domain || !conf.token) {
+    throw new TetherError('Tether is not configured: domain and token are required', { code: 'NOT_CONFIGURED' });
+  }
+  let text = context ? withContext(query, conf) : query;
+  if (conf.maxAge > 0 && !/^\s*mutation\b/.test(text)) {
+    text += ` #${Math.floor(Date.now() / (conf.maxAge * 1000))}`;
+  }
+  const store = storeOf(conf);
+  let retries = 0;
+  for (;;) {
+    const sent = storesWithoutInventory.has(store) ? text.replaceAll(INVENTORY_FIELD, '') : text;
+    const outcome = await attempt(conf, sent, variables, retries < conf.retries);
+    switch (outcome.kind) {
+      case 'data':
+        // The query text decides the shape of `data`; the caller's `T` states it.
+        return /** @type {T} */ (outcome.data);
+      case 'inventory-refused':
+        log(`the token can't read inventory: ${INVENTORY_FIELD} is left out from now on`);
+        storesWithoutInventory.add(store);
+        break;
+      case 'retry':
+        retries += 1;
+        log('retry', retries);
+        await sleep(outcome.backoffMs * 2 ** retries);
+        break;
     }
-    if (!res.ok) throw new TetherError(statusText(res.status, conf), { status: res.status });
-
-    return json.data;
   }
 }
 
-export const gql = (query, variables, opts) => request(cfg, query, variables, opts);
+/**
+ * `request` with the browser's shared config.
+ *
+ * @template T
+ * @param {string} query
+ * @param {Record<string, unknown>} [variables]
+ * @param {RequestOptions} [options]
+ * @returns {Promise<T>}
+ */
+export const gql = (query, variables, options) => request(cfg, query, variables, options);
 
-/** Throws on mutation userErrors, returns the payload otherwise. */
+/**
+ * @template {{ userErrors?: readonly UserError[] | null }} Payload
+ * @param {Payload | null | undefined} payload A mutation's payload.
+ * @param {string} name The mutation, for the error message.
+ * @returns {Payload}
+ * @throws {TetherError} `ERROR` on an empty payload or on user errors (in `userErrors`).
+ */
 export function unwrap(payload, name) {
   if (!payload) throw new TetherError(`${name}: empty response`);
-  const errs = payload.userErrors || [];
-  if (errs.length) {
-    throw new TetherError(errs.map((e) => e.message).join(' | '), { userErrors: errs });
+  const userErrors = payload.userErrors ?? [];
+  if (userErrors.length) {
+    throw new TetherError(userErrors.map((error) => error.message).join(' | '), { userErrors });
   }
   return payload;
 }

package/src/collection.js

@@ -1,114 +1,183 @@
 /**
- * Product lists: [tether-collection="handle"] or [tether-products="search query"].
- * The first child of [tether-list] is the card template; every card becomes a
- * product scope, so all product attributes work inside cards (including
- * quick-add with a subscription toggle).
+ * Product lists: [tether-collection="handle"], [tether-products="search query"] and [tether-recommendations]. The
+ * first child of [tether-list] is the card template; every card becomes a product scope, so all product attributes
+ * work inside cards (including quick-add with a subscription toggle).
  */
 import { reportError } from './config.js';
 import { TetherError } from './client.js';
-import { attr, sel, get, has, scoped, emit, setText, setImage, repeat, notifyLayoutChanged, busy, show } from './dom.js';
+import {
+  attr,
+  sel,
+  get,
+  has,
+  scoped,
+  emit,
+  setText,
+  setStoreHtml,
+  setImage,
+  repeat,
+  notifyLayoutChanged,
+  busy,
+  show,
+} from './dom.js';
 import { getProducts, getRecommendations } from './loader.js';
 import { setScopeStatus, isNotFound, resolveProductKey } from './status.js';
+/** @import { Product } from './fragments.js' */
+/** @import { Collection, PageInfo, ProductQuery } from './loader.js' */
+
+/** `tether-products="url:q"`: the search in the page's `?q=`, for a results page on a static site. */
+const URL_QUERY_SOURCE = 'url:';
 
 export const listSelector = () => `${sel('collection')},${sel('products')},${sel('recommendations')}`;
 
+/**
+ * @param {EventTarget | null} target
+ * @returns {target is Element}
+ */
+const isElement = (target) => target instanceof window.Element;
+
+/**
+ * @param {string | null} raw A `tether-limit`.
+ * @returns {number | undefined} The limit; `undefined` for none, zero or not a number.
+ */
+const toLimit = (raw) => parseInt(raw ?? '', 10) || undefined;
+
+/**
+ * @param {string | null} raw A `tether-intent`.
+ * @returns {'RELATED' | 'COMPLEMENTARY'} Shopify's recommendation intent, `RELATED` unless `COMPLEMENTARY` is written.
+ */
+const toIntent = (raw) => (raw === 'COMPLEMENTARY' ? 'COMPLEMENTARY' : 'RELATED');
+
 export class ListScope {
+  /** @param {HTMLElement} root */
   constructor(root) {
     this.root = root;
+    /** @type {Product[]} */
     this.products = [];
+    /** @type {PageInfo | null} */
     this.pageInfo = null;
+    /** @type {Collection | null} */
     this.collection = null;
+    /** Counts loads, so only the latest one renders. */
+    this.loadToken = 0;
     setScopeStatus(root, 'loading');
-    root.addEventListener('click', (e) => {
-      const more = e.target.closest?.(sel('load-more'));
-      if (more && more.closest(listSelector()) === root) {
-        e.preventDefault();
-        busy(more, () => this.load(true));
-      }
+    root.addEventListener('click', (event) => {
+      if (!isElement(event.target)) return;
+      const more = event.target.closest(sel('load-more'));
+      if (more?.closest(listSelector()) !== root) return;
+      event.preventDefault();
+      void busy(more, () => this.load(true));
     });
   }
 
-  $(s) { return scoped(this.root, s, listSelector()); }
+  /** @param {string} selector */
+  $(selector) {
+    return scoped(this.root, selector, listSelector());
+  }
 
+  /** @returns {ProductQuery} The collection or search query of the list's attributes. */
   options() {
-    const r = this.root;
-    const opts = {
-      first: parseInt(get(r, 'limit') || '', 10) || undefined,
-      sortKey: get(r, 'sort') || undefined,
-      reverse: get(r, 'reverse') === 'true',
-    };
-    if (has(r, 'collection')) opts.collection = get(r, 'collection');
-    else {
-      // url:q = the search in the page's ?q= (a results page on a static site).
-      const raw = get(r, 'products') || '';
-      opts.query = raw.startsWith('url:') ? new URL(window.location.href).searchParams.get(raw.slice(4)) || '' : raw;
+    const { root } = this;
+    /** @type {ProductQuery} */
+    const query = { reverse: get(root, 'reverse') === 'true' };
+    const first = toLimit(get(root, 'limit'));
+    if (first) query.first = first;
+    const sortKey = get(root, 'sort');
+    if (sortKey) query.sortKey = sortKey;
+    if (has(root, 'collection')) {
+      query.collection = get(root, 'collection') ?? '';
+      return query;
     }
-    return opts;
+    const raw = get(root, 'products') ?? '';
+    query.query = raw.startsWith(URL_QUERY_SOURCE)
+      ? new URL(window.location.href).searchParams.get(raw.slice(URL_QUERY_SOURCE.length)) || ''
+      : raw;
+    return query;
   }
 
+  /**
+   * The product of a recommendations list: a handle, `url:…` (one dynamic product page), or empty inside a product
+   * scope for that product.
+   *
+   * @returns {Promise<Product[]>}
+   * @throws {TetherError} `NOT_FOUND` when there is no product to recommend for.
+   */
+  async loadRecommendations() {
+    let { key } = resolveProductKey(this.root, window.location, 'recommendations');
+    const scope = this.root.closest(sel('product'));
+    if (!key && scope) ({ key } = resolveProductKey(scope));
+    if (!key) throw new TetherError('No product for recommendations', { code: 'NOT_FOUND' });
+    return getRecommendations(key, toIntent(get(this.root, 'intent')));
+  }
+
+  /** @param {boolean} [more] Appends the next page instead of replacing the products. */
   async load(more = false) {
-    const token = (this.loadToken = (this.loadToken || 0) + 1);
+    this.loadToken += 1;
+    const token = this.loadToken;
     const stale = () => token !== this.loadToken;
     try {
       if (has(this.root, 'recommendations')) {
-        // A handle, url:handle (one dynamic product page), or empty inside a product: that product.
-        let { key } = resolveProductKey(this.root, window.location, 'recommendations');
-        const scope = this.root.closest(sel('product'));
-        if (!key && scope) ({ key } = resolveProductKey(scope));
-        if (!key) throw new TetherError('No product for recommendations', { code: 'NOT_FOUND' });
-        const recs = await getRecommendations(key, get(this.root, 'intent') || 'RELATED');
+        const recommendations = await this.loadRecommendations();
         if (stale()) return;
-        const limit = parseInt(get(this.root, 'limit') || '', 10);
-        this.products = limit ? recs.slice(0, limit) : recs;
+        const limit = toLimit(get(this.root, 'limit'));
+        this.products = limit ? recommendations.slice(0, limit) : recommendations;
       } else {
-        const res = await getProducts({ ...this.options(), after: more ? this.pageInfo?.endCursor : null });
+        const page = await getProducts({ ...this.options(), after: more ? (this.pageInfo?.endCursor ?? null) : null });
         if (stale()) return;
-        this.collection = res.collection;
-        this.pageInfo = res.pageInfo;
-        this.products = more ? [...this.products, ...res.products] : res.products;
+        this.collection = page.collection;
+        this.pageInfo = page.pageInfo;
+        this.products = more ? [...this.products, ...page.products] : page.products;
       }
       this.render();
       setScopeStatus(this.root, 'ready');
       emit('list-ready', { products: this.products, collection: this.collection }, this.root);
-    } catch (err) {
+    } catch (error) {
       if (stale()) return;
-      // Keep what's already rendered on a failed "load more"; otherwise show the error state.
-      if (!more) setScopeStatus(this.root, isNotFound(err) ? 'not-found' : 'error', err);
+      // A failed "load more" keeps what is rendered; otherwise the list shows its error state.
+      if (!more) setScopeStatus(this.root, isNotFound(error) ? 'not-found' : 'error', error);
       // A missing product for recommendations is a page detail, not an error to report.
-      if (!(isNotFound(err) && has(this.root, 'recommendations'))) reportError(err, 'list load failed');
-      emit('error', { error: err, context: 'list' }, this.root);
+      if (!(isNotFound(error) && has(this.root, 'recommendations'))) reportError(error, 'list load failed');
+      emit('error', { error, context: 'list' }, this.root);
     }
   }
 
   render() {
-    const c = this.collection;
+    const { collection } = this;
     this.$(sel('collection-bind')).forEach((el) => {
-      switch (get(el, 'collection-bind')) {
-        case 'title': return setText(el, c?.title || '');
-        case 'description': el.innerHTML = c?.descriptionHtml || ''; return undefined;
-        case 'image': return setImage(el, c?.image?.url, c?.image?.altText || c?.title);
-        case 'count': return setText(el, this.products.length);
-        default: return undefined;
+      switch (get(el, 'collection-bind') ?? '') {
+        case 'title':
+          setText(el, collection?.title ?? '');
+          break;
+        case 'description':
+          setStoreHtml(el, collection?.descriptionHtml);
+          break;
+        case 'image':
+          setImage(el, collection?.image?.url, collection?.image?.altText || collection?.title);
+          break;
+        case 'count':
+          setText(el, this.products.length);
+          break;
       }
     });
 
     this.$(sel('list')).forEach((container) => {
-      repeat(container, this.products, (node, p) => {
-        node.setAttribute(attr('product'), p.handle);
+      repeat(container, this.products, (node, product) => {
+        node.setAttribute(attr('product'), product.handle);
         node.removeAttribute(attr('state'));
       });
-      // Cards are new elements: mount them (product data is already cached).
+      // Cards are new elements: mounting them uses the product data already cached.
       emit('list-rendered', { container }, this.root);
     });
 
     const empty = this.products.length === 0;
     this.$(sel('show')).forEach((el) => {
-      const k = get(el, 'show');
-      if (k === 'list-empty') show(el, empty);
-      if (k === 'list-filled') show(el, !empty);
+      const key = get(el, 'show');
+      if (key === 'list-empty') show(el, empty);
+      if (key === 'list-filled') show(el, !empty);
+    });
+    this.$(sel('load-more')).forEach((el) => {
+      show(el, Boolean(this.pageInfo?.hasNextPage));
     });
-    this.$(sel('load-more')).forEach((el) => show(el, Boolean(this.pageInfo?.hasNextPage)));
     notifyLayoutChanged('list');
   }
 }
-