@occluze/tether 0.6.8 → 0.7.0

package/dist/types/src/loader.d.ts

@@ -0,0 +1,84 @@
+import { productKey } from './shopify-values.js';
+import type { Product, Image } from './fragments.js';
+import type { ProductConnection } from './product-shape.js';
+/** Accepts a handle, numeric id, gid or a full product URL. */
+export declare const normalizeProductKey: typeof productKey;
+/** Puts a product the page already has (from a collection query) in the cache, under its handle and its id. */
+export declare function primeProduct(product: Product | null | undefined): void;
+/**
+ * @param rawKey A handle, numeric id, gid or product URL.
+ * @throws {TetherError} `NOT_FOUND` (rejected) for an empty key or a product the store doesn't have.
+ */
+export declare function getProduct(rawKey: string | number | null | undefined): Promise<Product>;
+/** Forgets every product, for a new market: requests already sent no longer fill the cache. */
+export declare function clearProductCache(): void;
+/**
+ * Uses products the server rendered, unless the page loaded the same product live in the last `FRESH_MS` (an earlier
+ * page of a View Transition visit), whose copy is newer.
+ */
+export declare function hydrateProducts(products: readonly Product[] | null | undefined): void;
+/** @returns True once per server-rendered product: the caller then refreshes it. */
+export declare function takeStale(rawKey: string | number | null | undefined): boolean;
+/** Loads this product again, past the cache. Products refreshed in the same tick go out as one request. */
+export declare function refreshProduct(key: string | number): Promise<Product>;
+export interface PageInfo {
+    hasNextPage: boolean;
+    endCursor: string | null;
+}
+export interface Collection {
+    id: string;
+    handle: string;
+    title: string;
+    description: string;
+    descriptionHtml: string;
+    image: Image | null;
+    seo: {
+        title: string | null;
+        description: string | null;
+    };
+}
+export interface ProductPage {
+    collection: Collection | null;
+    products: Product[];
+    pageInfo: PageInfo;
+}
+export interface ProductQuery {
+    /** A collection handle; without one, a search. */
+    collection?: string;
+    /** Storefront search syntax, for a search. */
+    query?: string;
+    first?: number;
+    /** The cursor of the page before. */
+    after?: string | null;
+    /** `ProductCollectionSortKeys` for a collection, `ProductSortKeys` for a search. */
+    sortKey?: string;
+    reverse?: boolean;
+    /** `ProductFilter` values, for a collection. */
+    filters?: unknown[];
+}
+/** A collection's answer: `null` for a handle the store doesn't have. Its other fields are written as text. */
+export declare const isCollectionAnswer: import("./client.js").DataCheck<{
+    collection: (Collection & {
+        products: ProductConnection;
+    }) | null;
+}>;
+export declare const isSearchAnswer: import("./client.js").DataCheck<{
+    products: ProductConnection;
+}>;
+export declare const isRecommendationsAnswer: import("./client.js").DataCheck<{
+    productRecommendations: Product[] | null;
+}>;
+/**
+ * A page of products from a collection (by handle) or from a search. Every product on it is cached.
+ *
+ * @throws {TetherError} `NOT_FOUND` for a collection the store doesn't have.
+ */
+export declare function getProducts({ collection, query, first, after, sortKey, reverse, filters, }?: ProductQuery): Promise<ProductPage>;
+/**
+ * Shopify's recommendations for a product. Every product in them is cached.
+ *
+ * @param product A product, or its handle, id or gid.
+ */
+export declare function getRecommendations(product: string | number | {
+    id: string;
+} | null | undefined, intent?: 'RELATED' | 'COMPLEMENTARY'): Promise<Product[]>;

package/dist/types/src/market-codes.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Country and language codes as Shopify's `@inContext` takes them, parsed by the module the Worker uses for the
+ * login's market, so the browser and the Worker accept and refuse the same values.
+ */
+export { toCountry, toLanguage } from '../server/src/shared/market-codes.js';
+export type { CountryCode, LanguageCode } from '../server/src/shared/market-codes.js';

package/dist/types/src/markets-ui.d.ts

@@ -0,0 +1,32 @@
+import { Cart } from './cart.js';
+import type { Localization } from './markets.js';
+export { detectMarket } from './markets.js';
+/**
+ * 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 declare function getLocalization(): Promise<Localization>;
+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;
+}
+/**
+ * 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 declare function renderCountrySelects(root?: ParentNode): Promise<void>;
+/**
+ * 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 declare function setCountry(code: string, { language, locale, remember }?: SetCountryOptions): Promise<typeof Cart.state>;

package/dist/types/src/markets.d.ts

@@ -0,0 +1,72 @@
+import type { MarketsConfig } from './config.js';
+import type { CountryCode, LanguageCode } from './market-codes.js';
+/** 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;
+}
+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[];
+    })[];
+}
+/** The localStorage key of the visitor's market: `<prefix>:market:<domain>`. */
+export declare const storageKey: () => string;
+/**
+ * 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 declare function readSavedMarket(storage?: Pick<Storage, 'getItem'>): Market | null;
+/**
+ * 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 declare function detectMarket(markets?: MarketsConfig | null | undefined, env?: MarketEnv): DetectedMarket;
+/** Saves the visitor's choice for the next pages, unless `markets.remember` is false. */
+export declare function rememberMarket(market: {
+    country: CountryCode;
+    language?: string | null | undefined;
+    locale?: string | null | undefined;
+}): void;
+export {};

package/dist/types/src/markup.d.ts

@@ -0,0 +1,131 @@
+import type { ShopifyCart } from './cart/store.js';
+import type { CartLineInput } from './cart/mutations.js';
+import type { CartWarning } from './config.js';
+import type { Product, ProductVariant } from './fragments.js';
+import type { Collection } from './loader.js';
+import type { ProductScope } from './product.js';
+import type { Purchase } from './product-state.js';
+import type { SearchResults } from './search.js';
+/** @returns The prefixed attribute name: `product` → `tether-product`. */
+export declare const attr: (name: string) => string;
+/** @returns A selector for the attribute, with that exact value when given. */
+export declare const sel: (name: string, value?: string) => string;
+export declare const get: (el: Element, name: string) => string | null;
+export declare const has: (el: Element, name: string) => boolean;
+/**
+ * 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 declare function qsa(root: ParentNode | null | undefined, selector: string): HTMLElement[];
+/** @returns Matches in `root` whose nearest `scopeSelector` ancestor is `root` itself, not a nested scope. */
+export declare const scoped: (root: Element | null | undefined, selector: string, scopeSelector: string) => HTMLElement[];
+/**
+ * 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 declare const ANALYTICS_EVENTS: readonly ["product-ready", "list-ready", "cart-updated", "cart-toggled", "checkout", "search"];
+export type AnalyticsEventName = (typeof ANALYTICS_EVENTS)[number];
+/** @returns The bubbling event `<prefix>:<name>`, known to `isOwnEvent`. */
+export declare function ownEvent<Name extends keyof TetherEvents>(name: Name, detail: TetherEvents[Name]): CustomEvent<TetherEvents[Name]>;
+/** @returns True for an event `ownEvent` created as `name`, false for any other, such as one another script dispatched. */
+export declare function isOwnEvent<Name extends keyof TetherEvents>(event: Event, name: Name): event is CustomEvent<TetherEvents[Name]>;
+/** Dispatches the bubbling event `<prefix>:<name>`. */
+export declare function emit<Name extends keyof TetherEvents>(name: Name, detail: TetherEvents[Name], target?: EventTarget): void;

package/dist/types/src/mounting.d.ts

@@ -0,0 +1,46 @@
+/** A mounted `ListScope`. */
+interface MountedList {
+    root: Element;
+    load: (more?: boolean) => Promise<unknown>;
+}
+export declare const mountedProducts: WeakSet<Element>;
+export declare const mountedLists: WeakSet<Element>;
+/** Product roots to re-render after a country switch; pruned once disconnected. */
+export declare const liveProducts: Set<HTMLElement>;
+/** Lists to reload after a country switch; pruned once disconnected. */
+export declare const liveLists: Set<MountedList>;
+/** Forgets roots a page transition removed, so they aren't kept alive. */
+export declare function pruneLive(): void;
+/** @returns `root` itself when it matches, then the matches inside it. */
+export declare function within(root: ParentNode & Partial<Pick<Element, 'matches'>>, selector: string): HTMLElement[];
+/**
+ * Mounts one product root.
+ *
+ * @returns True when a product request was started.
+ */
+export declare function mountProduct(el: HTMLElement): boolean;
+/** Loads again the product scopes that failed on a network or API error, for when the browser is back online. */
+export declare function retryFailed(): void;
+/**
+ * Lists, and anything else that loads prices, hold `html.tether-market-pending` until they are in.
+ *
+ * @returns `loading` itself.
+ */
+export declare const trackMarket: <T>(loading: Promise<T>) => Promise<T>;
+/** After a mount: drops `html.tether-market-pending` once this page's products are live. */
+export declare function settleMarket(): void;
+/**
+ * Uses the products in the page's hydrate tags (`tether/server` `hydrate()`) without a request. A tag made for another
+ * market is skipped, and marks the page (`html.tether-market-pending`) until the live prices are in, so CSS can hide
+ * prices meanwhile.
+ *
+ * Trust: a hydrate tag is part of the page, written by the site's own build like the rest of its HTML and scripts, so
+ * its prices and products are shown until the background refresh replaces them. Whoever can write a tag into the page
+ * can already write a script there; the shape check (`isProductShape`) is for a truncated or hand-written tag, which
+ * is skipped instead of failing a render.
+ *
+ * @param root Where to look: the document for a mount (a tag may sit in `<head>` or anywhere else on the page), the
+ *   added elements for `observe`.
+ */
+export declare function hydrateFromPage(root?: Document | Element): void;
+export {};

package/dist/types/src/page-market.d.ts

@@ -0,0 +1,27 @@
+import type { TetherOptions } from './config.js';
+import type { Parts } from './lazy.js';
+import type { ShopifyCart } from './cart/store.js';
+export type SetCountryOptions = Parameters<Parts['markets']['setCountry']>[1];
+/**
+ * Sets `cfg`'s market for the first page, over the configured one.
+ *
+ * @param overrides What `init()` was called with: a `locale` there wins over the visitor's.
+ */
+export declare function applyStartMarket(overrides: TetherOptions): Promise<void>;
+/**
+ * The market to switch to on arriving at the current page. A page built for a market switches to it; the first page
+ * without one after such a page switches back to the visitor's own choice, else to the configured market.
+ *
+ * @returns `null` when the page stays in the market in use.
+ */
+export declare function marketForArrival(): {
+    country: string;
+    language: string | undefined;
+    locale: string | undefined;
+} | null;
+/**
+ * `Tether.setCountry('DE')`: loads the markets part on first use.
+ *
+ * @returns The cart once everything is in the new market.
+ */
+export declare function setCountry(code: string, options?: SetCountryOptions): Promise<ShopifyCart | null>;

package/dist/types/src/presets/barba.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Preset for sites with page transitions (Barba, Swup), smooth scroll (Lenis) and GSAP. Nothing is read from globals
+ * except GSAP and ScrollTrigger by default: pass in what your site has.
+ *
+ *   import Tether from "@occluze/tether";
+ *   import { barbaPreset } from "@occluze/tether/presets/barba";
+ *
+ *   Tether.init({
+ *     ...window.TETHER_CONFIG,
+ *     ...barbaPreset({
+ *       lenis: () => myLenis,                      // resized after async renders
+ *       lockScroll: (drawer) => myLock.lock(drawer),  // when the cart opens
+ *       unlockScroll: () => myLock.unlock(),       // when the cart closes
+ *       onValueChange: (el, previous) => {},       // e.g. a text scramble
+ *     }),
+ *   });
+ *
+ *   // once per page container, e.g. in Barba's beforeEnter AND once():
+ *   Tether.mount(container);
+ *   // when leaving a page:
+ *   Tether.unmount();
+ */
+import type { TetherConfig } from '../config.js';
+/** `gsap`, `lenis` and `scrollTrigger` are getters, read each time they are used, so an instance made later is found. */
+interface BarbaPresetOptions {
+    /** Default `window.gsap`. */
+    gsap?: () => unknown;
+    /** Resized after async renders. */
+    lenis?: (() => unknown) | null;
+    /** Default `window.ScrollTrigger`, refreshed after async renders. */
+    scrollTrigger?: () => unknown;
+    /** When the cart opens. */
+    lockScroll?: ((drawer: HTMLElement) => void) | null;
+    /** When the cart closes. */
+    unlockScroll?: (() => void) | null;
+    /** After a cart line animated in or out. */
+    onResize?: (() => void) | null;
+    onValueChange?: TetherConfig['onValueChange'];
+    /** Animate cart lines in and out (default true). */
+    animateLines?: boolean;
+    /** Seconds. */
+    lineDuration?: number;
+}
+/** The hooks the preset always sets, and `onValueChange` as passed (`null` when it isn't). */
+type BarbaPresetConfig = {
+    autoMount: false;
+} & {
+    [Hook in 'onLayoutChange' | 'onCartOpen' | 'onCartClose' | 'onLineEnter' | 'onLineLeave']: NonNullable<TetherConfig[Hook]>;
+} & Pick<TetherConfig, 'onValueChange'>;
+export type { BarbaPresetOptions, BarbaPresetConfig };
+/**
+ * Hooks for sites with page transitions, smooth scroll and GSAP: spread into `Tether.init()`.
+ */
+export declare function barbaPreset(options?: BarbaPresetOptions): BarbaPresetConfig;
+/** @alias `barbaPreset`, for `import barbaPreset from '@occluze/tether/presets/barba'`. */
+export default barbaPreset;

package/dist/types/src/product-events.d.ts

@@ -0,0 +1,2 @@
+import type { ProductScope } from './product.js';
+export declare function bindProductEvents(scope: ProductScope): void;

package/dist/types/src/product-render.d.ts

@@ -0,0 +1,17 @@
+import type { Product } from './fragments.js';
+import type { PlanInGroup } from './selling-plans.js';
+/** The product scope as its renders see it. */
+export interface RenderScope {
+    readonly root: HTMLElement;
+    readonly product: Product;
+    readonly plans: PlanInGroup[];
+    /** Matches in this scope, the root included. */
+    $: (selector: string) => HTMLElement[];
+    /** The product's option name for one written in the markup. */
+    optName: (authored: string | null) => string;
+}
+export declare const isSelect: (el: Element) => el is HTMLSelectElement;
+/** @returns The `<select>` elements in the scope that match `selector`. */
+export declare const selectsIn: (scope: RenderScope, selector: string) => HTMLSelectElement[];
+/** Writes what depends on the product alone: its binds, option and plan lists and the selects' options. */
+export declare function writeProduct(scope: RenderScope): void;

package/dist/types/src/product-shape.d.ts

@@ -0,0 +1,88 @@
+import type { Product } from './fragments.js';
+import type { PageInfo } from './loader.js';
+/** A page of a GraphQL connection of products. */
+export interface ProductConnection {
+    nodes: Product[];
+    pageInfo: PageInfo;
+}
+/** A Storefront API `MoneyV2`. */
+export declare const MONEY: {
+    readonly amount: "string";
+    readonly currencyCode: "string";
+};
+/**
+ * A product's id, handle and title, and every list and price a render walks without a fallback: images, options,
+ * variants (each with an id, a price and its options) and the price range. Text fields are written as text, and the
+ * selling plan lists are read with a fallback, so they need no check.
+ */
+export declare const PRODUCT: {
+    readonly id: "string";
+    readonly handle: "string";
+    readonly title: "string";
+    readonly options: readonly ["object"];
+    readonly images: {
+        readonly nodes: readonly ["object"];
+    };
+    readonly priceRange: {
+        readonly minVariantPrice: {
+            readonly amount: "string";
+            readonly currencyCode: "string";
+        };
+        readonly maxVariantPrice: {
+            readonly amount: "string";
+            readonly currencyCode: "string";
+        };
+    };
+    readonly variants: {
+        readonly nodes: readonly [{
+            readonly id: "string";
+            readonly price: {
+                readonly amount: "string";
+                readonly currencyCode: "string";
+            };
+            readonly selectedOptions: readonly ["object"];
+        }];
+    };
+};
+/** A page of products, with the `pageInfo` paging reads. */
+export declare const PRODUCT_CONNECTION: {
+    readonly nodes: readonly [{
+        readonly id: "string";
+        readonly handle: "string";
+        readonly title: "string";
+        readonly options: readonly ["object"];
+        readonly images: {
+            readonly nodes: readonly ["object"];
+        };
+        readonly priceRange: {
+            readonly minVariantPrice: {
+                readonly amount: "string";
+                readonly currencyCode: "string";
+            };
+            readonly maxVariantPrice: {
+                readonly amount: "string";
+                readonly currencyCode: "string";
+            };
+        };
+        readonly variants: {
+            readonly nodes: readonly [{
+                readonly id: "string";
+                readonly price: {
+                    readonly amount: "string";
+                    readonly currencyCode: "string";
+                };
+                readonly selectedOptions: readonly ["object"];
+            }];
+        };
+    }];
+    readonly pageInfo: {
+        readonly hasNextPage: "boolean";
+    };
+};
+/** True for a value with the structure of `PRODUCT` and a non-empty id and handle. */
+export declare const isProductShape: (value: unknown) => value is Product;
+/**
+ * A node a lookup by gid answers: a product, or a node of another type, for which `... on Product` selects no field
+ * (no `id`).
+ */
+export declare const PRODUCT_NODE: (node: unknown) => boolean;