@occluze/tether 0.6.8 → 0.7.0

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

@@ -0,0 +1,110 @@
+import type { Money } from './shopify-values.js';
+import type { Product, ProductVariant } from './fragments.js';
+import type { PlanInGroup } from './selling-plans.js';
+/** Option name → chosen value. */
+export type Selection = Record<string, string>;
+/**
+ * How the visitor wants to buy. Buying once keeps the plan offered next to the one-time price (the subscription
+ * binds `subscription-price` and `plan-name` show it, and subscribing switches to it); `null` for a product without
+ * plans.
+ */
+export type Purchase = {
+    kind: 'one-time';
+    offeredPlanId: string | null;
+} | {
+    kind: 'subscription';
+    planId: string;
+};
+/** How the line is bought: on a plan only when the visitor subscribes and the variant is on that plan. */
+type LinePurchase = {
+    kind: 'one-time';
+} | {
+    kind: 'subscription';
+    planId: string;
+};
+/** What the visitor chose, before it is checked against the product. */
+interface ProductChoice {
+    selected: Selection;
+    purchase: Purchase;
+    quantity: number;
+}
+export type ShowCondition = 'in-stock' | 'out-of-stock' | 'backorder' | 'on-sale' | 'not-on-sale' | 'has-variants' | 'single-variant' | 'low-stock' | 'plenty-in-stock' | 'subscription-available' | 'subscription-unavailable' | 'subscription-only' | 'one-time-available' | 'subscription-selected' | 'one-time-selected' | 'has-savings';
+export interface ProductView {
+    variant: ProductVariant;
+    /** The selection, matching `variant`. */
+    selected: Selection;
+    /** The choice, made valid for the product and `variant`. */
+    purchase: Purchase;
+    /** The purchase's plan, offered or chosen. */
+    plan: PlanInGroup | null;
+    /** How the line is bought. */
+    line: LinePurchase;
+    /** The variant is on at least one plan. */
+    subscriptionAvailable: boolean;
+    quantity: number;
+    /** What one item costs as bought. */
+    price: Money;
+    /** Only when on sale. */
+    compareAtPrice: Money | null;
+    /** What `plan` saves on the one-time price. */
+    savings: {
+        amount: Money | null;
+        percentage: number;
+    };
+    show: Record<ShowCondition, boolean>;
+}
+/** How the caller writes values as text. */
+export interface Formatters {
+    money: (money: Money | null) => string;
+    percent: (percentage: number) => string;
+}
+/** What a bind writes; `null` and `undefined` clear it. */
+type BindText = string | number | null | undefined;
+export declare const selectionOf: (variant: ProductVariant) => Selection;
+/**
+ * @param name An option name.
+ * @returns True when a variant for sale has this value and the other selected values.
+ */
+export declare function isValueAvailable(product: Product, selected: Selection, name: string, value: string): boolean;
+/** @returns The plan subscribed on, or offered while buying once. */
+export declare const purchasePlanId: (purchase: Purchase) => string | null;
+/** @returns On the plan when subscribing and the variant is on it, else once. */
+export declare function linePurchase(purchase: Purchase, variant: ProductVariant | null): LinePurchase;
+/**
+ * The purchase the visitor wants, made valid for the product and variant: one-time without plans, a subscription when
+ * the product requires one, and a plan the variant is on when it is on any (else a plan of the product, for the binds
+ * to offer).
+ *
+ * @param kind The way of buying the visitor asked for.
+ * @param preferredPlanId The plan to keep when it is the product's: the visitor's last one.
+ */
+export declare function normalisePurchase(product: Product, variant: ProductVariant | null, kind: Purchase['kind'], preferredPlanId: string | null): Purchase;
+interface InitialChoiceOptions {
+    /** A variant id or gid (`?variant=`); the first variant for sale without. */
+    variant?: string | null | undefined;
+    /** A plan to subscribe on (`?selling_plan=`). */
+    sellingPlan?: string | null | undefined;
+    /** The plan offered first, by id, name or option value. */
+    defaultPlan?: string | null | undefined;
+    /** `subscription` subscribes; anything else buys once. */
+    defaultPurchase?: string | null | undefined;
+}
+/** What a product starts with before the visitor chooses anything. */
+export declare function initialChoice(product: Product, { variant, sellingPlan, defaultPlan, defaultPurchase }: InitialChoiceOptions): Omit<ProductChoice, 'quantity'>;
+/**
+ * The view for the visitor's choice. A selection no variant has falls back to the first variant.
+ *
+ * @param lowStock `low-stock` at this many or fewer.
+ * @returns `null` for a product without variants.
+ */
+export declare function productView(product: Product, choice: ProductChoice, lowStock: number): ProductView | null;
+/** The `tether-bind` values that follow the variant and purchase. Thunks, so only the binds on the page are computed. */
+export declare function variantBindTexts(view: ProductView, format: Formatters): Map<string, () => BindText>;
+/**
+ * The `tether-plan-bind` values of one plan in a plan list, for the variant.
+ *
+ * @param planId The list item's `tether-plan-value`.
+ * @param plan The product's plan with that id.
+ */
+export declare function planBindTexts(variant: ProductVariant, planId: string, plan: PlanInGroup | undefined, format: Formatters): Map<string, () => BindText>;
+export {};

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

@@ -0,0 +1,66 @@
+import type { Product, ProductVariant } from './fragments.js';
+import type { ShopifyCart } from './cart/store.js';
+import type { PlanInGroup } from './selling-plans.js';
+import type { Purchase, Selection } from './product-state.js';
+/** What a scope adds to the cart. */
+interface CartLineInput {
+    merchandiseId: string;
+    quantity: number;
+    sellingPlanId?: string;
+    attributes?: {
+        key: string;
+        value: string;
+    }[];
+}
+export declare const scopes: WeakMap<Element, ProductScope>;
+export declare function rememberOptionNames(products: readonly Pick<Product, 'handle' | 'options'>[]): void;
+export declare class ProductScope {
+    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);
+    /** New data for the same product (a country switch). Keeps the visitor's choice. */
+    update(product: Product): void;
+    /** @returns Matches in this scope, including the root itself (a card link with tether-bind="link"). */
+    $(selector: string): HTMLElement[];
+    /**
+     * @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: string | null): string;
+    get plan(): PlanInGroup | null;
+    /** True when the current variant can be bought on a plan. */
+    get subscriptionAvailable(): boolean;
+    /** True when the line is bought on a plan: subscribing, and the variant is on the plan. */
+    get isSubscription(): boolean;
+    /** @returns What would be added to the cart right now. */
+    getLine(): CartLineInput | null;
+    /** @returns `tether-line-attributes` and the filled `tether-line-attribute` fields. */
+    collectAttributes(): {
+        key: string;
+        value: string;
+    }[];
+    /**
+     * 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.
+     */
+    select(name: string, value: string): void;
+    /** @param id A variant gid or numeric id. */
+    selectVariant(id: string): void;
+    setPurchase(kind: Purchase['kind']): void;
+    /** @param ref A plan id, numeric id, name or option value. */
+    selectPlan(ref: string | null): void;
+    setQuantity(quantity: number | string): void;
+    /** @returns The cart after adding; `null` when the variant can't be added. */
+    addToCart(): Promise<ShopifyCart | null>;
+    /** Learns the markup's option names when they are the product's, then writes the product. */
+    renderProduct(): void;
+    /** Derives the view of the current choice, keeps its variant, selection and purchase, and writes it. */
+    renderVariant(): void;
+}
+export {};

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

@@ -0,0 +1,16 @@
+/** @returns True once the repeater's template has been captured (it may be empty after that). */
+export declare const hasTemplate: (container: Element) => boolean;
+/** Rebuilds the list on every render. Fine for images, tags, options. */
+export declare function repeat<Item>(container: Element, items: readonly Item[], render: (node: HTMLElement, item: Item, index: number) => void): void;
+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;
+}
+/**
+ * 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.
+ */
+export declare 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;
+export {};

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

@@ -0,0 +1,33 @@
+import type { Money } from './shopify-values.js';
+interface SearchImage {
+    url: string;
+    altText: string | null;
+}
+interface SearchProduct {
+    id: string;
+    handle: string;
+    title: string;
+    availableForSale: boolean;
+    featuredImage: SearchImage | null;
+    priceRange: {
+        minVariantPrice: Money;
+    };
+}
+interface SearchCollection {
+    handle: string;
+    title: string;
+    image: SearchImage | null;
+}
+interface SearchQuery {
+    text: string;
+}
+export interface SearchResults {
+    products: SearchProduct[];
+    collections: SearchCollection[];
+    queries: SearchQuery[];
+}
+/**
+ * Sets up every `[tether-search]` in `root` (and `root` itself) once.
+ */
+export declare function mountSearch(root?: ParentNode & Partial<Pick<Element, 'matches'>>): void;
+export {};

package/dist/types/src/selling-plans.d.ts

@@ -0,0 +1,64 @@
+import type { Money } from './shopify-values.js';
+import type { SellingPlan, SellingPlanGroup, SellingPlanAllocation } from './fragments.js';
+/** A plan with the group it belongs to. */
+export type PlanInGroup = SellingPlan & {
+    group: SellingPlanGroup;
+};
+export interface ProductWithPlans {
+    sellingPlanGroups?: {
+        nodes: SellingPlanGroup[];
+    } | null;
+}
+/** A variant as far as plans go. A cart line's variant has no allocations. */
+export interface VariantWithPlans {
+    price: Money;
+    sellingPlanAllocations?: {
+        nodes: SellingPlanAllocation[];
+    } | null;
+}
+export type PlanAdjustment = {
+    type: 'percentage';
+    value: number;
+} | {
+    type: 'amount';
+    value: Money;
+} | {
+    type: 'price';
+    value: Money;
+};
+/**
+ * @param value A gid, a numeric id, or anything else.
+ * @param type The Shopify type, e.g. `ProductVariant`.
+ * @returns The gid of a numeric id; a gid or other value as written; `null` when empty.
+ */
+export declare function toGid(value: unknown, type: string): string | null;
+export declare const GID: {
+    product: (value: unknown) => string | null;
+    variant: (value: unknown) => string | null;
+    sellingPlan: (value: unknown) => string | null;
+};
+/** @returns All plans of the product, flattened. */
+export declare function allPlans(product: ProductWithPlans | null | undefined): PlanInGroup[];
+export declare function hasPlans(product: ProductWithPlans | null | undefined): boolean;
+/** @returns The variant's allocation on the plan; `null` when the variant isn't in it. */
+export declare function allocationFor(variant: VariantWithPlans | null | undefined, planId: string | null | undefined): SellingPlanAllocation | null;
+/** @returns The plans this variant can be bought on. */
+export declare function plansForVariant(product: ProductWithPlans | null | undefined, variant: VariantWithPlans | null | undefined): PlanInGroup[];
+/** @returns The price per delivery on the plan; the one-time price when the variant isn't on it. */
+export declare function planPrice(variant: VariantWithPlans | null | undefined, planId: string | null | undefined): Money | null;
+/** @returns What the customer pays at checkout on the plan (prepaid plans charge more up front). */
+export declare function planCheckoutCharge(variant: VariantWithPlans | null | undefined, planId: string | null | undefined): Money | null;
+/** @returns What the plan saves on the one-time price; no amount and 0% when it saves nothing. */
+export declare function planSavings(variant: VariantWithPlans | null | undefined, planId: string | null | undefined): {
+    amount: Money | null;
+    percentage: number;
+};
+/**
+ * @returns The plan's own discount, whatever the variant: a percentage, a fixed amount off or a fixed price.
+ */
+export declare function planAdjustment(plan: Pick<SellingPlan, 'priceAdjustments'> | null | undefined): PlanAdjustment | null;
+/**
+ * Finds a plan by id, numeric id, name or option value (case-insensitive), so Webflow editors can write
+ * `tether-default-plan="Every month"`.
+ */
+export declare function findPlan(product: ProductWithPlans | null | undefined, ref: string | null | undefined): PlanInGroup | null;

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

@@ -0,0 +1,88 @@
+import { withContext, TetherError } from './client.js';
+import * as plans from './selling-plans.js';
+import { imageUrl, formatPercent } from './dom.js';
+import { initialState } from './initial.js';
+import { STORE_ENV_NAMES, formatMoney, productKey } from './shopify-values.js';
+import type { TetherConfig, TetherOptions } from './config.js';
+import type { Product } from './fragments.js';
+import type { Money } from './shopify-values.js';
+import type { InitialOptions, InitialState } from './initial.js';
+import type { JsonLdOptions } from './storefront/json-ld.js';
+export { imageUrl, initialState, formatPercent, formatMoney, productKey };
+export { TetherError, plans, withContext };
+export type { StorefrontOptions, HydrateOptions };
+export type { Money } from './shopify-values.js';
+export type { Product as ShopifyProduct, ProductVariant as ShopifyVariant } from './fragments.js';
+export type { ShopifyCart, ShopifyCartLine } from './cart/store.js';
+export type { Collection as ShopifyCollection, ProductQuery } from './loader.js';
+export type { InitialOptions, InitialState } from './initial.js';
+export type { ImageSize } from './images.js';
+export type { JsonLdOptions } from './storefront/json-ld.js';
+/** What `createStorefront()` returns. */
+export type Storefront = ReturnType<typeof createStorefront>;
+/** The options only a storefront has. */
+interface ServerOptions {
+    /** Replaces the global `fetch` (tests, caching). */
+    fetch?: typeof fetch;
+    /** Products per request for `allProducts()` (default 25). */
+    pageSize?: number;
+    /** The site's address, for product URLs in `jsonLd()` without `url`. */
+    siteUrl?: string;
+}
+/**
+ * The config options, or an `import.meta.env` spread into them: its `PUBLIC_SHOPIFY_*` names give the domain and
+ * token, its other keys are ignored.
+ */
+type StorefrontOptions = TetherOptions & ServerOptions & StoreEnv;
+/** The environment names that give the domain and the token. */
+type StoreEnv = Partial<Record<(typeof STORE_ENV_NAMES)['domain' | 'token'][number], string>>;
+type ServerConfig = TetherConfig & ServerOptions;
+interface HydrateOptions {
+    card?: boolean;
+    images?: number;
+}
+/**
+ * @returns `productPath` `/products` → `/products/<handle>`; templates with `{handle}` and `{id}` work too. `null` when
+ *   the path needs a handle or an id that is empty.
+ */
+export declare function productUrl(handle: string, { productPath, id }?: {
+    productPath?: string;
+    id?: string;
+}): string | null;
+/**
+ * A storefront: the store's products and collections for the server, and the tags that hand them to the page.
+ *
+ * @throws {TetherError} `NOT_CONFIGURED` without a domain and a token.
+ */
+export declare function createStorefront(options?: StorefrontOptions): {
+    hydrate: (products: Product | null | undefined | (Product | null | undefined)[], { card, images }?: HydrateOptions) => string;
+    formatMoney: (money: Money | null | undefined, locale?: string | undefined) => string;
+    formatPercent: (percentage: number, locale?: string | undefined) => string;
+    imageUrl: typeof imageUrl;
+    jsonLd: (product: Product | null | undefined, jsonLdOptions?: JsonLdOptions) => string;
+    jsonLdData: (product: Product | null | undefined, jsonLdOptions?: JsonLdOptions) => Record<string, unknown> | null;
+    initialState: {
+        (product: Product, initialOptions?: InitialOptions): InitialState;
+        (product: Product | null | undefined, initialOptions?: InitialOptions): InitialState | null;
+    };
+    productUrl: (handle: string, urlOptions?: {
+        productPath?: string;
+        id?: string;
+    }) => string | null;
+    plans: typeof plans;
+    getProduct: (raw: string | number | null | undefined) => Promise<Product | null>;
+    getProducts: (options?: import("./storefront/catalog.js").CatalogQuery) => Promise<import("./loader.js").ProductPage>;
+    allProducts: (options?: Omit<import("./storefront/catalog.js").CatalogQuery, "first" | "after">) => Promise<Product[]>;
+    getCollection: (handle: string, options?: Omit<import("./storefront/catalog.js").CatalogQuery, "collection">) => Promise<(import("./loader.js").Collection & {
+        products: Product[];
+        pageInfo: import("./loader.js").PageInfo;
+    }) | null>;
+    allCollections: () => Promise<import("./loader.js").Collection[]>;
+    getRecommendations: (product: string | number | {
+        id: string;
+    } | null | undefined, intent?: "RELATED" | "COMPLEMENTARY") => Promise<Product[]>;
+    config: ServerConfig;
+    query: <T>(query: string, variables?: Record<string, unknown>, requestOptions?: {
+        context?: boolean;
+    }) => Promise<T>;
+};

package/dist/types/src/shopify-values.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Conversions of Shopify values that the browser script and the server helpers (`src/server.ts`, `src/astro.ts`)
+ * share, so a server-rendered page and the script that takes it over agree. Pure: no config, no DOM.
+ */
+/** A Storefront API `MoneyV2`. */
+export interface Money {
+    amount: string;
+    currencyCode: string;
+}
+/** The `.env` names a store's domain and public Storefront token are read from, first match wins. */
+export declare const STORE_ENV_NAMES: {
+    readonly domain: readonly ["PUBLIC_SHOPIFY_DOMAIN", "PUBLIC_SHOPIFY_STORE_DOMAIN", "SHOPIFY_DOMAIN"];
+    readonly token: readonly ["PUBLIC_SHOPIFY_STOREFRONT_TOKEN", "PUBLIC_SHOPIFY_STOREFRONT_ACCESS_TOKEN", "SHOPIFY_STOREFRONT_TOKEN"];
+};
+/**
+ * True for an absolute https URL. Links and redirects that come from Shopify (checkout, status pages,
+ * tracking) are only used when this holds.
+ */
+export declare function isHttpsUrl(url: unknown): url is string;
+/**
+ * True for a token Shopify issues as a secret (`shpat_` Admin, `shpss_` shared secret, `shpca_` client credentials,
+ * `shppa_` private app, `shpua_` user). The public Storefront token has no such prefix. A secret token must never
+ * reach a page.
+ */
+export declare function isSecretShopifyToken(token: string): boolean;
+/**
+ * Money as text in `locale`, e.g. `{ amount: '30.0', currencyCode: 'EUR' }` in `nl-NL` → `€ 30,00`.
+ *
+ * @param locale An `Intl` locale; the runtime's own when absent.
+ * @returns `''` without money or with an amount that isn't a number.
+ */
+export declare function formatMoney(money: Money | null | undefined, locale: string | undefined): string;
+/**
+ * A product page's path. `productPath` is a folder (`/product` → `/product/<handle>`) or a template with `{handle}`
+ * and `{id}` (the numeric product id), e.g. `/product?handle={handle}`.
+ *
+ * @param id A product gid or numeric id.
+ * @returns `null` when the path needs a handle or an id the product lacks: no link beats a wrong one.
+ */
+export declare function productUrl(productPath: string, handle: string | null | undefined, id?: string | null): string | null;
+/**
+ * The key Tether loads a product by: a handle, or a product gid.
+ *
+ * @param raw A handle, a numeric id, a gid or a product URL (`…/products/<handle>`).
+ */
+export declare function productKey(raw: string | number | null | undefined): string | null;

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

@@ -0,0 +1,33 @@
+interface ProductKeySource {
+    /** The product to load; `null` when the attribute or the page URL has none. */
+    key: string | null;
+    /** The key comes from the page URL (`url:…`). */
+    fromUrl: boolean;
+    /** The attribute's value as written. */
+    raw: string;
+}
+type ScopeStatus = 'loading' | 'ready' | 'error' | 'not-found';
+/**
+ * Reads a `tether-product` value:
+ * - `coffee-box`: a handle, numeric id, gid or product URL;
+ * - `url:handle`: `?handle=` from the page URL (any parameter: `url:p` reads `?p=`);
+ * - `url:path`: the last segment of the page path (`/shop/coffee-box` → `coffee-box`).
+ *
+ * @param name The attribute, without prefix.
+ */
+export declare function resolveProductKey(el: Element, location?: Pick<Location, 'pathname' | 'search'>, name?: string): ProductKeySource;
+/** The values of `tether-show` that follow the scope's state. */
+export declare const STATUS_KEYS: readonly ScopeStatus[];
+/** @returns True for a `TetherError` with code `NOT_FOUND`. */
+export declare const isNotFound: (error: unknown) => boolean;
+/** @returns The selector of every scope that owns its state elements; the nearest one wins. */
+export declare const boundary: () => string;
+/** @returns True when `el` belongs to the scope `root`, not to a scope nested in it. */
+export declare const ownedBy: (el: Element, root: Element) => boolean;
+/**
+ * Sets `tether-state` (loading | ready | error) and `tether-error` (not-found or an error code) on `root`, toggles
+ * `tether-show="loading|ready|error|not-found"` inside it, and disables its add-to-cart buttons when there's no
+ * product.
+ */
+export declare function setScopeStatus(root: Element, status: ScopeStatus, error?: unknown): void;
+export {};

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

@@ -0,0 +1,12 @@
+/**
+ * The browser's `localStorage` and `sessionStorage`, which may be blocked: accessing them throws in private mode, in
+ * sandboxed frames and where the visitor blocks site data, and writing throws when they are full. Tether then keeps
+ * nothing between pages: a read finds nothing, and a write or removal does nothing. Each call catches on its own, so a
+ * blocked area never stops a call on the other.
+ */
+type StorageArea = 'localStorage' | 'sessionStorage';
+/** @returns `null` when nothing is stored under `key`, or the storage is blocked. */
+export declare function getStored(key: string, area?: StorageArea): string | null;
+export declare function setStored(key: string, value: string, area?: StorageArea): void;
+export declare function removeStored(key: string, area?: StorageArea): void;
+export {};

package/dist/types/src/store-html.d.ts

@@ -0,0 +1,39 @@
+/**
+ * HTML written in the Shopify admin (product and collection descriptions), made safe to insert into the site. Store
+ * staff and apps that can edit products are not trusted to act on the storefront, where customer sessions live. Only
+ * elements and attributes that show content are kept (an allow-list, so markup nobody reviewed is never let in):
+ * text formatting, lists, tables, images, links and video embeds look as written, inline `style` included, because
+ * the Shopify editor writes its formatting there. Script, page-wide `<style>` and forms (which could post the
+ * visitor's input anywhere) are removed, and embeds run sandboxed.
+ *
+ * A description stays where it is written, so it can't be laid over the page as a fake login (a phishing form on the
+ * shop's own origin). Removed for that: `id` (it would clobber `window.<id>` and the site's own ids); `class`, which
+ * would let a description borrow the site's own overlay or modal classes; and every style that takes content out of
+ * the flow (`position`, `inset`, `z-index`), moves it from where the flow put it (transforms, motion paths, negative
+ * margins, and negative indents and spacing beyond the small values that tighten text, `NEGATIVE_LIMITS`), copies it
+ * elsewhere (reflections) or sizes it to the window (viewport and container-query units).
+ * Outlines, shadows, filters, border-image and mask-border outsets, text decoration and text stroke paint beyond their
+ * element, so they are kept only while every number they give is a pixel length of a few dozen pixels at most
+ * (`MAX_PAINT_PX`): enough to set off an image or a callout, too little to cover the page.
+ * Styles that fetch anything go too.
+ *
+ * A frame shows whatever its origin serves, sized as the description likes, so a frame from a page store staff can
+ * write would be that fake login. Frames are kept only from the video players in `EMBED_ORIGINS` and the origins the
+ * site adds (`embedOrigins`), never from the site's own origin, where a sandbox can be lifted from inside. What an
+ * allowed frame shows is up to its host: the host's player, and whatever that player lets its users add (a call to
+ * action, an email gate). An origin a site adds is trusted the same way.
+ *
+ * Not prevented: content wider than the description (a table or embed on a narrow screen, or a box given a large
+ * width in pixels) overflows beside it, as in any HTML, and a capped shadow or outline still paints just past it. Tether
+ * doesn't clip the element it fills (`contain: paint`, `overflow`), because that would cut off those wide tables and
+ * embeds, stop margins collapsing through it and make it contain floats, changing how ordinary descriptions look. A
+ * site that wants the clip sets it on that element in its own CSS.
+ */
+/**
+ * Store HTML as a fragment of content elements only.
+ *
+ * @param document The document the fragment is for.
+ * @param embedOrigins Origins iframes may load from besides the video players in `EMBED_ORIGINS`: the config's
+ *   `embedOrigins`, already checked to be https origins.
+ */
+export declare function storeHtmlFragment(html: string | null | undefined, document?: Document, embedOrigins?: readonly string[]): DocumentFragment;

package/dist/types/src/storefront/catalog.d.ts

@@ -0,0 +1,38 @@
+import type { StorefrontConfig } from '../client.js';
+import type { ProductFragmentConfig, Product } from '../fragments.js';
+import type { Collection, PageInfo, ProductPage } from '../loader.js';
+/** What the catalog needs of a storefront's config. */
+type CatalogConfig = StorefrontConfig & ProductFragmentConfig;
+/** A page of a collection's products, or of a search. */
+export interface CatalogQuery {
+    /** A collection handle; without one, a search. */
+    collection?: string;
+    /** Storefront search syntax; `null` or `''` is every product. */
+    query?: string | null;
+    /** Default the storefront's `pageSize`. */
+    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[];
+}
+type CollectionWithProducts = Collection & {
+    products: Product[];
+    pageInfo: PageInfo;
+};
+type RecommendationIntent = 'RELATED' | 'COMPLEMENTARY';
+/** @param pageSize Products per page when a query doesn't say. */
+export declare function createCatalog(conf: CatalogConfig, pageSize: number): {
+    getProduct: (raw: string | number | null | undefined) => Promise<Product | null>;
+    getProducts: (options?: CatalogQuery) => Promise<ProductPage>;
+    allProducts: (options?: Omit<CatalogQuery, "first" | "after">) => Promise<Product[]>;
+    getCollection: (handle: string, options?: Omit<CatalogQuery, "collection">) => Promise<CollectionWithProducts | null>;
+    allCollections: () => Promise<Collection[]>;
+    getRecommendations: (product: string | number | {
+        id: string;
+    } | null | undefined, intent?: RecommendationIntent) => Promise<Product[]>;
+};
+export {};

package/dist/types/src/storefront/json-ld.d.ts

@@ -0,0 +1,20 @@
+import type { Product } from '../fragments.js';
+export interface JsonLdOptions {
+    /** The product page's absolute URL; default from the storefront's `siteUrl`. */
+    url?: string;
+    /** Default the product's vendor. */
+    brand?: string;
+}
+/** Where the product pages are. */
+interface JsonLdSite {
+    productPath: string;
+    siteUrl: string | undefined;
+}
+/**
+ * Text for a `<script>` tag: `<` is escaped so product text can never close the tag, and U+2028 / U+2029 so older
+ * JavaScript parsers read it.
+ */
+export declare const scriptJson: (value: unknown) => string;
+/** @returns The schema.org object, `null` without a product. */
+export declare function jsonLdData(product: Product | null | undefined, options: JsonLdOptions, site: JsonLdSite): Record<string, unknown> | null;
+export {};

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

@@ -0,0 +1,14 @@
+import type { ProductView } from './product-state.js';
+import type { RenderScope } from './product-render.js';
+/**
+ * The element of an add-to-cart button that holds its label, with the label as written kept in
+ * `data-tether-label`, so mode-dependent texts (`tether-subscribe-text`, `tether-soldout-text`) can be undone.
+ */
+export declare function addButtonLabel(button: HTMLElement): {
+    label: HTMLElement;
+    original: string;
+};
+/**
+ * Writes what follows the variant and purchase.
+ */
+export declare function writeVariant(scope: RenderScope, view: ProductView): void;