@occluze/tether 0.7.0 → 0.7.1

package/src/markets-ui.ts

@@ -1,227 +0,0 @@
-/**
- * Optional part, loaded on first use: market detection, the store's countries (`Tether.getLocalization()`),
- * `select[tether-country-select]`, `tether-country-bind` and `Tether.setCountry()`. See markets.ts for the detection
- * rules.
- */
-import { cfg, reportError } from './config.ts';
-import { gql, shaped, TetherError } from './client.ts';
-import { Cart } from './cart.ts';
-import { listSelector } from './collection.ts';
-import { clearProductCache } from './loader.ts';
-import { attr, sel, get, emit } from './dom.ts';
-import { within, pruneLive, liveLists, liveProducts, mountedProducts, mountProduct } from './mounting.ts';
-import { rememberMarket } from './markets.ts';
-import { toCountry, toLanguage } from './market-codes.ts';
-import type { LocalizedCountry, Localization } from './markets.ts';
-import type { CountryCode, LanguageCode } from './market-codes.ts';
-
-export { detectMarket } from './markets.ts';
-
-const DEFAULT_LABEL = '{name} ({currency})';
-const DEFAULT_BIND = 'name';
-
-let localizationPromise: Promise<Localization> | null = null;
-
-/** Forgets the cached localization, for when country names change language. */
-function clearLocalization(): void {
-  localizationPromise = null;
-}
-
-const LOCALIZATION_QUERY = `query TetherLocalization {
-  localization {
-    country { isoCode name currency { isoCode symbol } }
-    language { isoCode name }
-    availableCountries { isoCode name currency { isoCode symbol } availableLanguages { isoCode name } }
-  }
-}`;
-
-/** A country with the code, name and currency the country select and binds read. */
-const COUNTRY = { isoCode: 'string', name: 'string', currency: 'object' } as const;
-const isLocalizationAnswer = shaped<{ localization: Localization }>({
-  localization: { country: COUNTRY, availableCountries: [COUNTRY] },
-});
-
-/**
- * The countries the store sells to (Shopify Markets), with their currency. Cached per page; a failed request is not
- * cached, so the next call tries again.
- */
-export function getLocalization(): Promise<Localization> {
-  localizationPromise ??= gql(LOCALIZATION_QUERY, {}, isLocalizationAnswer).then(
-    (data) => data.localization,
-    (error: unknown) => {
-      localizationPromise = null;
-      throw error;
-    },
-  );
-  return localizationPromise;
-}
-
-interface SetCountryOptions {
-  /** A Shopify language; `null` clears it. Default: the `markets.locales` entry for the country, else unchanged. */
-  language?: string | null | undefined;
-  /** The money format. Default: the `markets.locales` entry, else unchanged. */
-  locale?: string | undefined;
-  /** Save the choice for the next pages (default true). */
-  remember?: boolean | undefined;
-}
-
-/**
- * @param field A `tether-country-bind` value or a label placeholder: `name`, `code`, `currency`, `symbol`.
- * @returns `''` for any other field.
- */
-function countryField(country: LocalizedCountry, field: string): string {
-  switch (field) {
-    case 'name':
-      return country.name;
-    case 'code':
-      return country.isoCode;
-    case 'currency':
-      return country.currency.isoCode;
-    case 'symbol':
-      return country.currency.symbol;
-    default:
-      return '';
-  }
-}
-
-/** @param template `tether-country-label`, e.g. `{name} ({currency})`. */
-const fillLabel = (template: string, country: LocalizedCountry) =>
-  template.replace(/\{(name|code|currency|symbol)\}/g, (_match, field: string) => countryField(country, field));
-
-/**
- * @param countries The store's countries, sorted by name.
- * @param current The country in use.
- */
-function fillCountrySelect(select: HTMLSelectElement, countries: LocalizedCountry[], current: string): void {
-  const template = select.getAttribute(attr('country-label')) || DEFAULT_LABEL;
-  // tether-countries="NL,DE,BE": only these, in that order; otherwise every country of the store.
-  const only = (select.getAttribute(attr('countries')) || '')
-    .toUpperCase()
-    .split(/[\s,]+/)
-    .filter(Boolean);
-  const listed = only.length
-    ? only
-        .map((code) => countries.find((country) => country.isoCode === code))
-        .filter((country) => country !== undefined)
-    : countries;
-  select.replaceChildren(...listed.map((country) => new Option(fillLabel(template, country), country.isoCode)));
-  select.value = current;
-  // A country the store doesn't sell to selects nothing.
-  if (select.value !== current) select.selectedIndex = -1;
-  select.disabled = listed.length < 2 && !select.hasAttribute(attr('always-enabled'));
-}
-
-function fillCountries(selects: HTMLSelectElement[], binds: HTMLElement[], localization: Localization): void {
-  const current = (cfg.country || localization.country.isoCode).toUpperCase();
-  const countries = [...localization.availableCountries].sort((a, b) =>
-    a.name.localeCompare(b.name, cfg.locale || undefined),
-  );
-  const inUse = countries.find((country) => country.isoCode === current) ?? localization.country;
-  selects.forEach((select) => {
-    fillCountrySelect(select, countries, current);
-  });
-  binds.forEach((el) => {
-    el.textContent = countryField(inUse, get(el, 'country-bind') || DEFAULT_BIND);
-  });
-}
-
-/**
- * Fills `select[tether-country-select]` with the countries the store sells to (Shopify Markets), and
- * `tether-country-bind="name|code|currency|symbol"` with the current country. `tether-country-label` sets the option
- * text from `{name}`, `{code}`, `{currency}` and `{symbol}`. A failure is reported, never thrown.
- */
-export function renderCountrySelects(root: ParentNode = document): Promise<void> {
-  // The selector matches `select` elements only.
-  const selects = within(root, `select${sel('country-select')}`) as HTMLSelectElement[];
-  const binds = within(root, sel('country-bind'));
-  if (!selects.length && !binds.length) return Promise.resolve();
-  return getLocalization()
-    .then((localization) => {
-      fillCountries(selects, binds, localization);
-    })
-    .catch((error: unknown) => {
-      reportError(error, 'country select');
-    });
-}
-
-/** The `markets.locales` entry for `country`. */
-const localeEntryFor = (country: CountryCode) =>
-  Object.values(cfg.markets?.locales ?? {}).find((entry) => toCountry(entry.country) === country);
-
-/**
- * @param language The `setCountry()` option.
- * @param entry The `markets.locales` entry for the country.
- * @returns The option, else the entry's language (which may have none), else unchanged.
- */
-function languageFor(
-  language: string | null | undefined,
-  entry: { language?: string } | undefined,
-): LanguageCode | null | undefined {
-  if (language !== undefined) return toLanguage(language);
-  if (!entry) return cfg.language;
-  return entry.language ? toLanguage(entry.language) : undefined;
-}
-
-/**
- * Loads every live product and list again in the market `cfg` now holds, and moves an existing cart to `country`.
- *
- * @returns The cart update and the list loads.
- */
-function rerenderInMarket(country: CountryCode): Promise<unknown>[] {
-  clearProductCache();
-  const jobs: Promise<unknown>[] = [];
-  // Only an existing cart moves; switching country never creates one.
-  if (Cart.id()) {
-    jobs.push(
-      Cart.setBuyerIdentity({ countryCode: country }, { create: false }).catch((error: unknown) => {
-        reportError(error, 'cart country');
-      }),
-    );
-  }
-  pruneLive();
-  liveLists.forEach((list) => jobs.push(list.load()));
-  liveProducts.forEach((el) => {
-    // A product inside a list is re-rendered by its list.
-    if (el.closest(listSelector())) return;
-    mountedProducts.delete(el);
-    mountProduct(el);
-  });
-  return jobs;
-}
-
-/**
- * Switches the market: prices, currency and translations follow (`@inContext`), the cart's
- * `buyerIdentity.countryCode` is updated, and every product and list on the page re-renders.
- *
- *   Tether.setCountry('DE')            Tether.setCountry('BE', { language: 'FR' })
- *
- * @returns The cart once everything is in the new market.
- * @throws {TetherError} `INVALID_COUNTRY` for anything that isn't a country code.
- */
-export async function setCountry(
-  code: string,
-  { language, locale, remember = true }: SetCountryOptions = {},
-): Promise<typeof Cart.state> {
-  const country = toCountry(code);
-  if (!country) throw new TetherError(`Not a country code: ${code}`, { code: 'INVALID_COUNTRY' });
-  const entry = localeEntryFor(country);
-  const ownLocale = locale || entry?.locale;
-  const nextLocale = ownLocale || cfg.locale;
-  const nextLanguage = languageFor(language, entry);
-  const changed = country !== cfg.country || nextLanguage !== cfg.language || nextLocale !== cfg.locale;
-  cfg.country = country;
-  cfg.language = nextLanguage || undefined;
-  cfg.locale = nextLocale;
-  if (remember) rememberMarket({ country, language: nextLanguage, locale: ownLocale });
-  if (!changed) {
-    void renderCountrySelects();
-    return Cart.state;
-  }
-  // Country names follow the language.
-  if (language !== undefined) clearLocalization();
-  const jobs = rerenderInMarket(country);
-  void renderCountrySelects();
-  emit('country-changed', { country, language: cfg.language });
-  await Promise.all(jobs);
-  return Cart.state;
-}

package/src/markets.ts

@@ -1,246 +0,0 @@
-/**
- * Markets: which country and language prices, currency and translations follow.
- *
- *   markets: {
- *     detect: true,                       // or a list: ['saved', 'server', 'webflow']
- *     locales: {                          // Webflow Localization: locale subdirectory or <html lang>
- *       de: { country: 'DE', language: 'DE', locale: 'de-DE' },
- *       'fr-be': { country: 'BE', language: 'FR' },
- *     },
- *     cookie: 'tether_country',           // a cookie your server or Worker sets (from cf-ipcountry)
- *     remember: true,                     // keep the visitor's tether-country-select choice
- *   }
- *
- * Sources, first match wins per field:
- *   saved   the visitor's own choice (localStorage), from tether-country-select / Tether.setCountry()
- *   server  window.TETHER_COUNTRY, <meta name="tether-country" content="DE">, or the cookie
- *   webflow locale subdirectory (/de/...) or <html lang="de-DE">, through `locales`
- * then the static `country` / `language` config. Without `detect`, only `saved` applies, so a country select keeps
- * working across pages; `detect: false` turns even that off. Tether never calls an IP lookup service: a country from
- * the visitor's IP only comes from the site's own server (see README).
- */
-import { MARKET_SOURCES, cfg, parseMarkets } from './config.ts';
-import { toCountry, toLanguage } from './market-codes.ts';
-import { getStored, setStored } from './storage.ts';
-import type { MarketsConfig } from './config.ts';
-import type { CountryCode, LanguageCode } from './market-codes.ts';
-
-/** A market a visitor chose, as `setCountry()` stores it. */
-export interface Market {
-  country: CountryCode;
-  language: LanguageCode | undefined;
-  /** An `Intl` locale for money and dates. */
-  locale: string | undefined;
-}
-
-export type MarketSource = 'saved' | 'server' | 'webflow';
-type MarketField = 'country' | 'language' | 'locale';
-type MarketSources = Partial<Record<MarketField, MarketSource>>;
-
-/** The fields detection found, and the source each came from. */
-export interface DetectedMarket {
-  country?: CountryCode;
-  language?: LanguageCode;
-  locale?: string;
-  /** Absent when `detect: false` turns detection off. */
-  sources?: MarketSources;
-}
-
-/** What detection reads, passed in so it runs on any document. */
-interface MarketEnv {
-  document: Pick<Document, 'cookie' | 'querySelector' | 'documentElement'> | null;
-  location: Pick<Location, 'pathname'> | null;
-  /** `localStorage`, read through `getStored`, which finds nothing where the browser blocks it. */
-  storage: Pick<Storage, 'getItem'>;
-  /** Where `TETHER_COUNTRY` and `TETHER_LANGUAGE` are read from (`window`). */
-  global: object;
-}
-
-/** A source's raw values. */
-interface MarketHint {
-  country?: unknown;
-  language?: unknown;
-  locale?: unknown;
-}
-
-interface NamedCode {
-  isoCode: string;
-  name: string;
-}
-
-interface Currency {
-  isoCode: string;
-  symbol: string;
-}
-
-export type LocalizedCountry = NamedCode & { currency: Currency };
-
-/** The store's markets, from the Storefront API's `localization`. */
-export interface Localization {
-  /** The country of the current `@inContext`. */
-  country: LocalizedCountry;
-  language: NamedCode;
-  availableCountries: (LocalizedCountry & { availableLanguages: NamedCode[] })[];
-}
-
-const DEFAULT_COOKIE = 'tether_country';
-
-/** The localStorage key of the visitor's market: `<prefix>:market:<domain>`. */
-export const storageKey = (): string => `${cfg.prefix}:market:${cfg.domain}`;
-
-const pageStorage: Pick<Storage, 'getItem'> = { getItem: (key) => getStored(key) };
-
-/** The page this script runs on. */
-function pageEnv(): MarketEnv {
-  const hasWindow = typeof window !== 'undefined';
-  return {
-    document: typeof document !== 'undefined' ? document : null,
-    location: hasWindow ? window.location : null,
-    storage: pageStorage,
-    global: hasWindow ? window : {},
-  };
-}
-
-/** The JSON value of `text`, `null` for text that isn't JSON (a key another script wrote). */
-function parseJsonOrNull(text: string): unknown {
-  try {
-    return JSON.parse(text) as unknown;
-  } catch (error) {
-    if (error instanceof SyntaxError) return null;
-    throw error;
-  }
-}
-
-/** `value` as a market, when it has a valid country. A language or locale that isn't valid is left out. */
-function toMarket(value: unknown): Market | null {
-  if (typeof value !== 'object' || value === null) return null;
-  const country = toCountry(Reflect.get(value, 'country'));
-  if (!country) return null;
-  const locale: unknown = Reflect.get(value, 'locale');
-  return {
-    country,
-    language: toLanguage(Reflect.get(value, 'language')) ?? undefined,
-    locale: typeof locale === 'string' && locale ? locale : undefined,
-  };
-}
-
-/**
- * The visitor's saved market (`setCountry()`, `tether-country-select`), validated: storage is written by other tabs,
- * older versions and other scripts too.
- *
- * @param storage Default `localStorage`.
- * @returns `null` when nothing valid is saved.
- */
-export function readSavedMarket(storage: Pick<Storage, 'getItem'> = pageStorage): Market | null {
-  const text = storage.getItem(storageKey());
-  return text ? toMarket(parseJsonOrNull(text)) : null;
-}
-
-function readCookie(doc: Pick<Document, 'cookie'> | null, name: string): string | null {
-  if (!doc || !name) return null;
-  const cookie = doc.cookie
-    .split(';')
-    .map((part) => part.trim())
-    .find((part) => part.startsWith(`${name}=`));
-  return cookie ? decodeURIComponent(cookie.slice(name.length + 1)) : null;
-}
-
-/** The entry of `locales` for `key`, ignoring case. */
-function lookupLocale(locales: MarketsConfig['locales'], key: string | undefined): MarketHint | null {
-  if (!locales || !key) return null;
-  const wanted = key.toLowerCase();
-  const found = Object.keys(locales).find((name) => name.toLowerCase() === wanted);
-  return found ? (locales[found] ?? null) : null;
-}
-
-function readServerHint(markets: MarketsConfig, env: MarketEnv): MarketHint {
-  const meta = (name: string) => env.document?.querySelector(`meta[name="${name}"]`)?.getAttribute('content');
-  const globalCountry: unknown = Reflect.get(env.global, 'TETHER_COUNTRY');
-  const globalLanguage: unknown = Reflect.get(env.global, 'TETHER_LANGUAGE');
-  const pageCountry = meta('tether-country') || readCookie(env.document, markets.cookie || DEFAULT_COOKIE);
-  return {
-    country: globalCountry || pageCountry,
-    language: globalLanguage || meta('tether-language'),
-  };
-}
-
-function readWebflowLocale(markets: MarketsConfig, env: MarketEnv): MarketHint | null {
-  const segment = (env.location?.pathname ?? '/').split('/').find((part) => part !== '');
-  const fromPath = lookupLocale(markets.locales, segment);
-  if (fromPath) return fromPath;
-  const lang = env.document?.documentElement.getAttribute('lang');
-  if (!lang) return null;
-  const mapped = lookupLocale(markets.locales, lang) ?? lookupLocale(markets.locales, lang.split('-')[0]);
-  if (mapped) return { locale: lang, ...mapped };
-  if (markets.locales && markets.strict) return null;
-  // Unmapped: the language from <html lang>, a country only from a region subtag (de-CH -> CH).
-  const region = lang.split('-')[1];
-  return { language: lang, country: region?.length === 2 ? region : null, locale: lang };
-}
-
-function readSource(source: MarketSource, markets: MarketsConfig, env: MarketEnv): MarketHint | null {
-  switch (source) {
-    case 'saved':
-      return markets.remember === false ? null : readSavedMarket(env.storage);
-    case 'server':
-      return readServerHint(markets, env);
-    case 'webflow':
-      return readWebflowLocale(markets, env);
-  }
-}
-
-/**
- * @param detect Validated: a list holds only known sources.
- * @returns Without `detect`, only the visitor's own choice from a country select.
- */
-function sourcesFor(detect: MarketsConfig['detect']): readonly MarketSource[] {
-  if (!detect) return ['saved'];
-  return detect === true ? MARKET_SOURCES : detect;
-}
-
-/**
- * The market the page's sources point to. Reads the DOM and storage only, so it can run on any `env`.
- *
- * @returns Only the fields found; `{}` with `detect: false`.
- */
-export function detectMarket(
-  markets: MarketsConfig | null | undefined = cfg.markets,
-  env: MarketEnv = pageEnv(),
-): DetectedMarket {
-  // The config's own `markets` was validated by `configure()`; one passed in by the site's code is validated here.
-  const config = (markets === cfg.markets ? markets : parseMarkets(markets)) ?? {};
-  if (config.detect === false) return {};
-  const sources: MarketSources = {};
-  const found: DetectedMarket = { sources };
-  for (const source of sourcesFor(config.detect)) {
-    const hint = readSource(source, config, env);
-    if (!hint) continue;
-    const country = toCountry(hint.country);
-    const language = toLanguage(hint.language);
-    const locale = typeof hint.locale === 'string' && hint.locale ? hint.locale : null;
-    if (country && !found.country) {
-      found.country = country;
-      sources.country = source;
-    }
-    if (language && !found.language) {
-      found.language = language;
-      sources.language = source;
-    }
-    if (locale && !found.locale) {
-      found.locale = locale;
-      sources.locale = source;
-    }
-  }
-  return found;
-}
-
-/** Saves the visitor's choice for the next pages, unless `markets.remember` is false. */
-export function rememberMarket(market: {
-  country: CountryCode;
-  language?: string | null | undefined;
-  locale?: string | null | undefined;
-}): void {
-  if (cfg.markets?.remember === false) return;
-  const saved = { country: market.country, language: market.language || undefined, locale: market.locale || undefined };
-  setStored(storageKey(), JSON.stringify(saved));
-}

package/src/markup.ts

@@ -1,127 +0,0 @@
-/**
- * How Tether finds its markup: attribute names carry the configured prefix (`tether-product`, or `wfs-product` with
- * `prefix: 'wfs'`), and so do the selectors and the DOM events built from them.
- */
-import { cfg } from './config.ts';
-import type { ShopifyCart } from './cart/store.ts';
-import type { CartLineInput } from './cart/mutations.ts';
-import type { CartWarning } from './config.ts';
-import type { Product, ProductVariant } from './fragments.ts';
-import type { Collection } from './loader.ts';
-import type { ProductScope } from './product.ts';
-import type { Purchase } from './product-state.ts';
-import type { SearchResults } from './search.ts';
-
-/** @returns The prefixed attribute name: `product` → `tether-product`. */
-export const attr = (name: string): string => `${cfg.prefix}-${name}`;
-
-/** @returns A selector for the attribute, with that exact value when given. */
-export const sel = (name: string, value?: string): string =>
-  value === undefined ? `[${attr(name)}]` : `[${attr(name)}="${value}"]`;
-
-export const get = (el: Element, name: string): string | null => el.getAttribute(attr(name));
-
-export const has = (el: Element, name: string): boolean => el.hasAttribute(attr(name));
-
-/**
- * Tether's attributes go on HTML elements, so matches are typed as such. An SVG element that carries one still has
- * the `style`, `dataset` and attribute methods Tether uses.
- *
- * @returns The matches in `root`, none without a root.
- */
-export function qsa(root: ParentNode | null | undefined, selector: string): HTMLElement[] {
-  if (!root) return [];
-  return [...root.querySelectorAll<HTMLElement>(selector)];
-}
-
-/** @returns Matches in `root` whose nearest `scopeSelector` ancestor is `root` itself, not a nested scope. */
-export const scoped = (root: Element | null | undefined, selector: string, scopeSelector: string): HTMLElement[] =>
-  qsa(root, selector).filter((el) => el.closest(scopeSelector) === root);
-
-/**
- * The events Tether dispatches, as `<prefix>:<name>` (`tether:cart-updated`), bubbling up to `document`, with the
- * detail each carries. `emit` takes only these, and `Tether.on()` passes on only the events `emit` dispatched, so a listener gets the
- * detail its event really has.
- */
-export interface TetherEvents {
-  ready: { cart: ShopifyCart | null };
-  'product-ready': { product: Product; scope: ProductScope };
-  'product-updated': { product: Product; scope: ProductScope };
-  /** `key` is null when the scope names no product; `source` is what it named. */
-  'product-not-found': { key: string | null; source: string };
-  'variant-changed': {
-    product: Product;
-    variant: ProductVariant;
-    selected: Record<string, string>;
-    purchase: Purchase['kind'];
-    sellingPlanId: string | null;
-  };
-  'product-added': { product: Product; variant: ProductVariant; line: CartLineInput };
-  added: { cart: ShopifyCart; lines: CartLineInput[] };
-  'group-added': { group: string | null; lines: CartLineInput[] };
-  'cart-warning': { warnings: readonly CartWarning[] };
-  'cart-updated': { cart: ShopifyCart | null; reason: string };
-  'cart-toggled': { open: boolean };
-  'cart-error': { error: unknown };
-  checkout: { url: string; cart: ShopifyCart | null };
-  'list-ready': { products: Product[]; collection: Collection | null };
-  /** A list's cards were drawn (again): `container` holds them. */
-  'list-rendered': { container: Element };
-  /** The search part's suggestions for `term`. */
-  search: SearchResults & { term: string };
-  'country-changed': { country: string; language: string | undefined };
-  'discount-applied': { code: string };
-  'discount-invalid': { code: string };
-  'layout-changed': { reason: string };
-  error: { error: unknown; context: string; key?: string | null };
-  'account-login': Record<string, never>;
-  'account-logout': Record<string, never>;
-  /** A login that failed: `expired` (it took too long, or came back to another browser) or `error`. */
-  'account-error': { error: 'expired' | 'error' };
-  'account-updated': { what: 'profile' | 'addresses' | 'subscriptions' | 'orders' };
-}
-
-/** The events the analytics part reports, which the core buffers from `init()` until the part has loaded. */
-export const ANALYTICS_EVENTS = [
-  'product-ready',
-  'list-ready',
-  'cart-updated',
-  'cart-toggled',
-  'checkout',
-  'search',
-] as const satisfies readonly (keyof TetherEvents)[];
-
-export type AnalyticsEventName = (typeof ANALYTICS_EVENTS)[number];
-
-/**
- * The events Tether created, with the name each was created under. Any script can dispatch a `<prefix>:<name>` event
- * with any detail; only an event in here carries the detail `TetherEvents` gives its name.
- */
-const ownEvents = new WeakMap<Event, keyof TetherEvents>();
-
-/** @returns The bubbling event `<prefix>:<name>`, known to `isOwnEvent`. */
-export function ownEvent<Name extends keyof TetherEvents>(
-  name: Name,
-  detail: TetherEvents[Name],
-): CustomEvent<TetherEvents[Name]> {
-  const event = new CustomEvent(`${cfg.prefix}:${name}`, { detail, bubbles: true });
-  ownEvents.set(event, name);
-  return event;
-}
-
-/** @returns True for an event `ownEvent` created as `name`, false for any other, such as one another script dispatched. */
-export function isOwnEvent<Name extends keyof TetherEvents>(
-  event: Event,
-  name: Name,
-): event is CustomEvent<TetherEvents[Name]> {
-  return ownEvents.get(event) === name;
-}
-
-/** Dispatches the bubbling event `<prefix>:<name>`. */
-export function emit<Name extends keyof TetherEvents>(
-  name: Name,
-  detail: TetherEvents[Name],
-  target: EventTarget = document,
-): void {
-  target.dispatchEvent(ownEvent(name, detail));
-}