@nevios/storefront-kit 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,931 @@
+import * as React from 'react';
+import { StorefrontClient, Money, Product, ProductMedia, ProductVariant, CollectionDetail, ProductSort, Cart, AddLineInput, CartLine, Checkout, CreateCheckoutInput, SetAddressInput, ShippingQuote, PaymentMethod, OrderStatus, Customer, MagicLinkResult, ReorderResult } from '@nevios/storefront-js';
+
+/**
+ * NeviosProvider — puts a configured storefront client on React context so
+ * every kit component + hook can reach it. Wrap your app once at the root.
+ *
+ *   import { createStorefrontClient } from "@nevios/storefront-js";
+ *   import { NeviosProvider } from "@nevios/storefront-kit";
+ *
+ *   const client = createStorefrontClient({ publishableKey, market });
+ *   <NeviosProvider client={client}>{children}</NeviosProvider>
+ */
+
+interface NeviosProviderProps {
+    client: StorefrontClient;
+    children: React.ReactNode;
+}
+declare function NeviosProvider({ client, children }: NeviosProviderProps): React.ReactElement;
+/** Access the storefront client from any kit component / hook. */
+declare function useStorefront(): StorefrontClient;
+/** Non-throwing client access — returns null when no <NeviosProvider> is
+ *  mounted. For presentational components that want optional client config
+ *  (e.g. `imageBase` for responsive images) but must still render standalone. */
+declare function useStorefrontOptional(): StorefrontClient | null;
+
+/**
+ * Theme contract — the customization surface (layer 1) merchants edit in
+ * `nevios.config.ts`. Tokens are injected as CSS custom properties on a
+ * wrapper, so every kit component reads `var(--nv-…)` and re-skins with zero
+ * code. Mirrors the internal `/design` token model, pointed outward.
+ *
+ *   <ThemeProvider theme={{ brand: "#b1442e", radius: "12px" }}>
+ *     {storefront}
+ *   </ThemeProvider>
+ */
+
+/** The full token set. All optional — unset tokens fall back to defaults. */
+interface StorefrontTheme {
+    /** Primary brand / CTA color. */
+    brand?: string;
+    brandForeground?: string;
+    background?: string;
+    foreground?: string;
+    muted?: string;
+    border?: string;
+    /** Corner radius for cards/inputs/buttons. */
+    radius?: string;
+    /** Base font family. */
+    fontFamily?: string;
+}
+/** Resolve a theme into the CSS-var style object the provider applies. */
+declare function themeToCssVars(theme?: StorefrontTheme): React.CSSProperties;
+interface ThemeProviderProps {
+    theme?: StorefrontTheme;
+    children: React.ReactNode;
+    /** Wrapper element (default `div`). */
+    as?: keyof React.JSX.IntrinsicElements;
+}
+declare function ThemeProvider({ theme, children, as: Tag, }: ThemeProviderProps): React.ReactElement;
+
+/**
+ * English message bundle — the canonical key set. Every other locale bundle is
+ * typed as `Messages` (a `Record<MessageKey, string>`), so the compiler forces
+ * it to define exactly these keys: a missing or stray key is a type error.
+ *
+ * Keys are dot-namespaced by surface (`cart.*`, `checkout.*`, `order.*`).
+ * `{name}` placeholders are interpolated by `t(key, { name })`. Plural keys end
+ * in a CLDR category (`.one` / `.few` / `.many` / `.other`); call them via the
+ * base key with a `count` var — `t("shipping.days", { count })` — and the
+ * provider picks the category for the active locale via `Intl.PluralRules`.
+ */
+declare const en: {
+    "common.free": string;
+    "common.close": string;
+    "common.loadingShort": string;
+    "catalog.addToCart": string;
+    "catalog.noProducts": string;
+    "catalog.soldOut": string;
+    "catalog.addError": string;
+    "catalog.inStock": string;
+    "catalog.preorder": string;
+    "catalog.filters.sort": string;
+    "catalog.filters.sortNewest": string;
+    "catalog.filters.sortOldest": string;
+    "catalog.filters.sortTitleAsc": string;
+    "catalog.filters.sortTitleDesc": string;
+    "catalog.filters.sortPriceAsc": string;
+    "catalog.filters.sortPriceDesc": string;
+    "catalog.filters.priceRange": string;
+    "catalog.filters.min": string;
+    "catalog.filters.max": string;
+    "catalog.filters.tags": string;
+    "catalog.filters.inStockOnly": string;
+    "catalog.filters.clear": string;
+    "catalog.backInStock.prompt": string;
+    "catalog.backInStock.email": string;
+    "catalog.backInStock.notify": string;
+    "catalog.backInStock.success": string;
+    "catalog.backInStock.error": string;
+    "cart.title": string;
+    "cart.empty": string;
+    "cart.remove": string;
+    "cart.increaseQty": string;
+    "cart.decreaseQty": string;
+    "cart.checkout": string;
+    "cart.subtotal": string;
+    "cart.tax": string;
+    "cart.total": string;
+    "totals.subtotal": string;
+    "totals.discount": string;
+    "totals.shipping": string;
+    "totals.paymentFee": string;
+    "totals.taxIncluded": string;
+    "totals.total": string;
+    "checkout.stepAddress": string;
+    "checkout.stepShipping": string;
+    "checkout.stepPayment": string;
+    "checkout.loading": string;
+    "checkout.empty": string;
+    "checkout.shippingAddress": string;
+    "checkout.continueToShipping": string;
+    "checkout.email": string;
+    "checkout.firstName": string;
+    "checkout.lastName": string;
+    "checkout.company": string;
+    "checkout.address": string;
+    "checkout.apartment": string;
+    "checkout.city": string;
+    "checkout.postalCode": string;
+    "checkout.country": string;
+    "checkout.phone": string;
+    "checkout.shippingMethod": string;
+    "checkout.continueToPayment": string;
+    "checkout.loadingShipping": string;
+    "checkout.noShipping": string;
+    "checkout.payment": string;
+    "checkout.loadingPayment": string;
+    "checkout.noPayment": string;
+    "checkout.payNow": string;
+    "checkout.placeOrder": string;
+    "checkout.gatewayRedirectNote": string;
+    "checkout.thankYou": string;
+    "checkout.orderPlacedBody": string;
+    "shipping.days.one": string;
+    "shipping.days.few": string;
+    "shipping.days.many": string;
+    "shipping.days.other": string;
+    "shipping.daysRange": string;
+    "order.title": string;
+    "order.placedOn": string;
+    "order.loading": string;
+    "order.loadError": string;
+    "order.notFound": string;
+    "order.confirmLoading": string;
+    "order.confirmLoadError": string;
+    "order.confirmed": string;
+    "order.items": string;
+    "order.shipping": string;
+    "order.shipsTo": string;
+    "order.tracking": string;
+    "order.payment": string;
+    "order.method": string;
+    "order.status": string;
+    "order.downloadInvoice": string;
+    "order.contactSupport": string;
+    "order.trackOrder": string;
+    "order.phase.placed": string;
+    "order.phase.paid": string;
+    "order.phase.fulfilled": string;
+    "order.phase.shipped": string;
+    "order.phase.delivered": string;
+    "order.terminal.cancelled": string;
+    "order.terminal.refunded": string;
+    "order.terminal.returned": string;
+    "error.notFound.title": string;
+    "error.notFound.body": string;
+    "error.generic.title": string;
+    "error.generic.body": string;
+    "error.home": string;
+    "account.title": string;
+    "account.signIn": string;
+    "account.signInBlurb": string;
+    "account.email": string;
+    "account.sendLink": string;
+    "account.checkEmail": string;
+    "account.signOut": string;
+    "account.greeting": string;
+    "account.orders": string;
+    "account.noOrders": string;
+    "account.addresses": string;
+    "account.noAddresses": string;
+    "account.viewOrder": string;
+    "account.verifying": string;
+    "account.verifyError": string;
+    "account.openDevLink": string;
+    "account.profile": string;
+    "account.editProfile": string;
+    "account.firstName": string;
+    "account.lastName": string;
+    "account.phone": string;
+    "account.acceptsMarketing": string;
+    "account.save": string;
+    "account.cancel": string;
+    "account.saved": string;
+    "account.saveError": string;
+    "account.addAddress": string;
+    "account.editAddress": string;
+    "account.deleteAddress": string;
+    "account.confirmDelete": string;
+    "account.setDefault": string;
+    "account.default": string;
+    "account.company": string;
+    "account.address": string;
+    "account.addressLine2": string;
+    "account.city": string;
+    "account.postalCode": string;
+    "account.country": string;
+    "account.reorder": string;
+    "account.reorderDone": string;
+    "account.reorderPartial": string;
+    "account.reorderError": string;
+};
+/** Every message key, derived from the English bundle (the source of truth). */
+type MessageKey = keyof typeof en;
+/** A complete message bundle for one locale. */
+type Messages = Record<MessageKey, string>;
+
+/**
+ * I18nProvider + useT — the kit's translation layer. UI strings are bundled
+ * (zero network calls); product/collection *content* is localized server-side
+ * via the SDK's `X-Locale`. Wrap your app once with the resolved locale:
+ *
+ *   <I18nProvider locale="cs-CZ">{app}</I18nProvider>   // auto-picks the cs pack
+ *   <I18nProvider locale="fr-FR" messages={fr}>…        // bring your own pack
+ *
+ * Components call `const t = useT()` and `t("checkout.payNow")`. Pluralize with
+ * a `count` var — `t("shipping.days", { count })` — resolved via Intl.PluralRules
+ * for the active locale. With no provider mounted, `useT` falls back to English,
+ * so kit components never crash un-wrapped.
+ */
+
+type TVars = Record<string, string | number>;
+type TFunction = (key: MessageKey | (string & {}), vars?: TVars) => string;
+/** Pick a bundled pack by language subtag ("cs-CZ" → cs); default English. */
+declare function bundledMessages(locale?: string): Messages;
+interface I18nValue {
+    locale: string;
+    messages: Messages;
+    t: TFunction;
+}
+interface I18nProviderProps {
+    /** BCP-47 locale — drives pluralization + (when `messages` is omitted) which
+     *  bundled pack is used. */
+    locale?: string;
+    /** Override / extend the messages. Merged over the bundled pack for `locale`,
+     *  so you can ship custom copy or add a locale the kit doesn't bundle. */
+    messages?: Partial<Messages>;
+    children: React.ReactNode;
+}
+declare function I18nProvider({ locale, messages, children, }: I18nProviderProps): React.ReactElement;
+/** Full i18n context — locale + messages + t. Falls back to English when no
+ *  <I18nProvider> is mounted. */
+declare function useI18n(): I18nValue;
+/** The translate function for the active locale. */
+declare function useT(): TFunction;
+
+/**
+ * Czech message bundle. Typed as `Messages`, so the compiler guarantees it
+ * stays in sync with the canonical English key set in `en.ts`. Czech uses four
+ * plural categories (one / few / many / other) — see `shipping.days.*`.
+ */
+
+declare const cs: Messages;
+
+/**
+ * MarketSwitcher — lets a shopper change market (and with it currency + locale).
+ * Headless about *how* you switch: pass `hrefFor` to navigate to each market's
+ * domain/path (the storefront resolves the market from there), or `onSelect`
+ * to handle it yourself (e.g. set a cookie + reload). Feed it the list from
+ * `client.markets()`.
+ *
+ *   <MarketSwitcher markets={markets} current={market}
+ *     hrefFor={(m) => m.domain ? `https://${m.domain}` : `/${m.handle}`} />
+ */
+
+/** The minimal market shape the switcher needs. Both the SDK's
+ *  `StorefrontMarket` (from `client.markets()`) and a hand-written config entry
+ *  satisfy it — `label` wins for display, else `name (CURRENCY)`. */
+interface MarketOption {
+    handle: string;
+    label?: string;
+    name?: string;
+    currency?: string;
+    locale?: string;
+    domain?: string | null;
+}
+interface MarketSwitcherProps {
+    markets: readonly MarketOption[];
+    /** Current market handle (the selected option). */
+    current?: string;
+    /** Map a market → the URL to switch to. When set, changing the select
+     *  navigates there. */
+    hrefFor?: (market: MarketOption) => string;
+    /** Or handle the switch yourself (cookie + reload). Takes precedence over
+     *  `hrefFor` if both are given. */
+    onSelect?: (market: MarketOption) => void;
+    /** Option label. Default: `label`, else `"Name (CURRENCY)"`, else handle. */
+    renderLabel?: (market: MarketOption) => string;
+    "aria-label"?: string;
+    className?: string;
+    style?: React.CSSProperties;
+}
+declare function MarketSwitcher({ markets, current, hrefFor, onSelect, renderLabel, "aria-label": ariaLabel, className, style, }: MarketSwitcherProps): React.ReactElement | null;
+
+/**
+ * Money formatting + display. `formatMoney` is the headless helper; `PriceMoney`
+ * renders the display price with an optional struck-through compare-at.
+ */
+
+/** Format minor units (cents) + currency → a localized string ("2 999,00 Kč"). */
+declare function formatCents(cents: number, currency: string, locale?: string): string;
+/** Format a Money → a localized currency string. */
+declare function formatMoney(money: Money, locale?: string): string;
+interface PriceMoneyProps {
+    money: Money;
+    /** Show the struck-through compare-at price when one is set. */
+    showCompareAt?: boolean;
+    /** Override the formatting locale (defaults to the I18nProvider locale). */
+    locale?: string;
+}
+declare function PriceMoney({ money, showCompareAt, locale, }: PriceMoneyProps): React.ReactElement;
+
+/**
+ * ProductCard — a product tile for grids (collection pages, search). Image +
+ * title + price range. Presentational: pass a `Product`; pass `href` to make
+ * the whole tile a link to the PDP. Override via the slot registry to restyle
+ * just this without touching the rest.
+ */
+
+interface ProductCardProps {
+    product: Product;
+    /** When set, the whole card links here (the eshop owns its URL scheme). */
+    href?: string;
+    locale?: string;
+}
+declare function ProductCard({ product, href, locale }: ProductCardProps): React.ReactElement;
+
+/**
+ * ProductGallery — the PDP image gallery: a main image + thumbnail strip.
+ * Client-interactive (thumbnail selects the main image). Presentational data.
+ */
+
+interface ProductGalleryProps {
+    media: ProductMedia[];
+    alt?: string;
+}
+declare function ProductGallery({ media, alt }: ProductGalleryProps): React.ReactElement;
+
+/**
+ * VariantPicker — one selector row per product option (Color, Size…). Resolves
+ * the matching variant from the selected values and reports it via `onChange`,
+ * so the PDP knows which variant to price + add to cart. Defaults to the first
+ * variant. Single-option-less products (one default variant) render nothing.
+ */
+
+interface VariantPickerProps {
+    product: Product;
+    onChange?: (variant: ProductVariant | null) => void;
+}
+declare function VariantPicker({ product, onChange }: VariantPickerProps): React.ReactElement | null;
+
+/**
+ * ProductDetailPage — the PDP composition: gallery + title + live price for the
+ * selected variant + variant picker + an add-to-cart slot. Presentational:
+ * the Remix loader fetches the `Product`, this renders it. `addToCart` is a
+ * render slot the cart phase (P2) fills with an <AddToCart> bound to the
+ * currently-selected variant.
+ */
+
+interface ProductDetailPageProps {
+    product: Product;
+    locale?: string;
+    /** Render slot for the add-to-cart control, bound to the selected variant. */
+    addToCart?: (variant: ProductVariant | null) => React.ReactNode;
+}
+declare function ProductDetailPage({ product, locale, addToCart, }: ProductDetailPageProps): React.ReactElement;
+
+/**
+ * CollectionPage — collection header + a responsive grid of ProductCards in the
+ * collection's curated order. Presentational: the Remix loader fetches the
+ * `CollectionDetail` (collection + its products), this renders it. `productHref`
+ * lets the eshop own its URL scheme.
+ */
+
+interface CollectionPageProps {
+    collection: CollectionDetail;
+    /** Map a product → its PDP URL (the eshop owns routing). */
+    productHref?: (product: Product) => string;
+    locale?: string;
+}
+declare function CollectionPage({ collection, productHref, locale, }: CollectionPageProps): React.ReactElement;
+
+/**
+ * StockBadge — a small availability pill for a variant. Reads
+ * `variant.availability.status` (in_stock | preorder | out_of_stock) and renders
+ * a themed label. Renders nothing for an untracked in-stock variant when
+ * `hideInStock` is set (keeps the PDP quiet for always-available goods).
+ */
+
+interface StockBadgeProps {
+    variant: ProductVariant | null;
+    /** Don't render anything when the variant is in stock (default false). */
+    hideInStock?: boolean;
+}
+declare function StockBadge({ variant, hideInStock }: StockBadgeProps): React.ReactElement | null;
+
+/**
+ * BackInStockForm — an email capture shown when a variant is out of stock.
+ * Submits to `client.catalog.inventory.subscribe(variantId, email)`. Renders
+ * nothing unless the variant's status is `out_of_stock`, so it's safe to drop
+ * straight into a PDP next to (or instead of) the add-to-cart button.
+ */
+
+interface BackInStockFormProps {
+    variant: ProductVariant | null;
+    /** Prefill the email (e.g. the signed-in customer's). */
+    defaultEmail?: string;
+    onSuccess?: () => void;
+}
+declare function BackInStockForm({ variant, defaultEmail, onSuccess, }: BackInStockFormProps): React.ReactElement | null;
+
+/**
+ * Product list filter + sort controls — presentational + controlled. Each holds
+ * no state; the parent owns a `ProductListOptions` object, passes the current
+ * value in, and re-queries on change. Themeable via `--nv-*`.
+ *
+ *   const [opts, setOpts] = React.useState<ProductListOptions>({ sort: "newest" });
+ *   <SortSelect value={opts.sort} onChange={(sort) => setOpts({ ...opts, sort, offset: 0 })} />
+ *   // re-run client.catalog.products(opts) when opts changes
+ */
+
+interface SortSelectProps {
+    value?: ProductSort;
+    onChange: (sort: ProductSort) => void;
+}
+declare function SortSelect({ value, onChange }: SortSelectProps): React.ReactElement;
+interface AvailabilityFilterProps {
+    checked?: boolean;
+    onChange: (checked: boolean) => void;
+}
+declare function AvailabilityFilter({ checked, onChange, }: AvailabilityFilterProps): React.ReactElement;
+interface PriceRangeFilterProps {
+    /** Current bounds in cents (undefined = open-ended). */
+    minCents?: number;
+    maxCents?: number;
+    currency: string;
+    onChange: (minCents: number | undefined, maxCents: number | undefined) => void;
+    locale?: string;
+}
+/** Two minor-unit (cents) inputs. Emits cents; renders the currency symbol as a
+ *  hint via the active locale. Empty input → undefined (open-ended). */
+declare function PriceRangeFilter({ minCents, maxCents, currency, onChange, locale, }: PriceRangeFilterProps): React.ReactElement;
+interface TagFilterProps {
+    /** All selectable tags (the eshop supplies these, e.g. from its nav). */
+    tags: string[];
+    selected?: string[];
+    onChange: (selected: string[]) => void;
+}
+/** Toggleable tag chips. Multi-select; emits the selected list. */
+declare function TagFilter({ tags, selected, onChange }: TagFilterProps): React.ReactElement | null;
+
+/**
+ * CartProvider + useCart — shared cart state for the whole app. The drawer, the
+ * PDP add-to-cart, and a header cart count all read the same cart and re-render
+ * together. Wraps the SDK's cart namespace (which holds the token) with React
+ * state. Mount once inside <NeviosProvider>.
+ *
+ *   <NeviosProvider client={client}>
+ *     <CartProvider>{app}</CartProvider>
+ *   </NeviosProvider>
+ */
+
+interface CartState {
+    cart: Cart | null;
+    /** True while a cart request is in flight. */
+    loading: boolean;
+    itemCount: number;
+    addLine(input: AddLineInput): Promise<Cart>;
+    updateLine(lineId: string, quantity: number): Promise<Cart>;
+    removeLine(lineId: string): Promise<Cart>;
+    /** Re-fetch the cart from the server. */
+    refresh(): Promise<void>;
+}
+declare function CartProvider({ children }: {
+    children: React.ReactNode;
+}): React.ReactElement;
+declare function useCart(): CartState;
+
+/**
+ * AddToCart — the PDP buy button. Bound to a selected variant; adds it to the
+ * shared cart. Drop into ProductDetailPage's `addToCart` slot:
+ *
+ *   <ProductDetailPage product={p} addToCart={(v) => <AddToCart variant={v} />} />
+ */
+
+interface AddToCartProps {
+    variant: ProductVariant | null;
+    quantity?: number;
+    /** Button label. Defaults to "Add to cart". */
+    children?: React.ReactNode;
+    onAdded?: () => void;
+}
+declare function AddToCart({ variant, quantity, children, onAdded, }: AddToCartProps): React.ReactElement;
+
+/**
+ * CartLineItem — one cart row: thumbnail, title + variant, a quantity stepper,
+ * line total, and remove. Wired to the shared cart (update/remove).
+ */
+
+interface CartLineItemProps {
+    line: CartLine;
+    locale?: string;
+}
+declare function CartLineItem({ line, locale }: CartLineItemProps): React.ReactElement;
+
+/**
+ * CartSummary — subtotal / tax / total + a checkout CTA. Reads the shared cart.
+ * The checkout action is the eshop's (a link to its checkout route, or a
+ * callback) — the P3 checkout phase wires it.
+ */
+
+interface CartSummaryProps {
+    /** Checkout button label (defaults to the localized "Checkout"). */
+    checkoutLabel?: string;
+    /** Link to the eshop's checkout route. */
+    checkoutHref?: string;
+    /** Or a callback (e.g. checkout.create() then navigate). */
+    onCheckout?: () => void;
+    locale?: string;
+}
+declare function CartSummary({ checkoutLabel, checkoutHref, onCheckout, locale, }: CartSummaryProps): React.ReactElement | null;
+
+/**
+ * CartDrawer — a slide-in panel with the cart lines + summary. Controlled
+ * (`open`/`onClose`). Reads the shared cart; the checkout CTA is passed through
+ * to CartSummary.
+ */
+
+interface CartDrawerProps extends CartSummaryProps {
+    open: boolean;
+    onClose: () => void;
+    /** Drawer heading (defaults to the localized "Cart"). */
+    title?: string;
+}
+declare function CartDrawer({ open, onClose, title, ...summary }: CartDrawerProps): React.ReactElement | null;
+
+/**
+ * CheckoutProvider + useCheckout — shared checkout state for the flow. Wraps the
+ * SDK's checkout namespace (which holds the token, created from the cart token)
+ * with React state, so AddressForm, ShippingPicker, PaymentSection, and
+ * OrderSummary all read and mutate the same checkout and re-render together.
+ *
+ * Mount inside <NeviosProvider> on the checkout route:
+ *   <CheckoutProvider>{<CheckoutFlow />}</CheckoutProvider>
+ *
+ * The provider resumes an in-progress checkout from the stored token on mount;
+ * call `create(cartToken)` from the cart's "Checkout" CTA to start one.
+ */
+
+/** Outcome of `pay()` — a gateway redirect, or a placed order. */
+type PayResult = {
+    kind: "redirect";
+    url: string;
+} | {
+    kind: "order";
+    checkout: Checkout;
+};
+interface PayOptions {
+    /** Where the gateway returns the customer after paying. */
+    returnUrl?: string;
+    /** Where the gateway returns the customer on cancel. */
+    cancelUrl?: string;
+    /** Idempotency key for the place-order call. Defaults to the checkout token,
+     *  which makes completing the same checkout retry-safe. */
+    idempotencyKey?: string;
+    /** Redirect the browser to the gateway automatically (gateway methods only).
+     *  Default true; pass false to handle the redirect yourself. */
+    redirect?: boolean;
+}
+interface CheckoutState {
+    checkout: Checkout | null;
+    /** True while a checkout request is in flight. */
+    loading: boolean;
+    /** The last error from a checkout op (cleared on the next successful op). */
+    error: Error | null;
+    /** Snapshot the cart into a fresh checkout and hold its token. */
+    create(cartToken: string, input?: CreateCheckoutInput): Promise<Checkout>;
+    /** Set email + shipping (and optional billing) address. */
+    setAddress(input: SetAddressInput): Promise<Checkout>;
+    /** Available shipping options for the current address. */
+    shippingQuotes(): Promise<ShippingQuote[]>;
+    /** Choose a shipping method + rate. */
+    setShippingMethod(methodId: string, rateId: string): Promise<Checkout>;
+    /** Apply / remove a discount code. */
+    applyDiscount(code: string): Promise<Checkout>;
+    removeDiscount(code: string): Promise<Checkout>;
+    /** Enabled payment methods for the market — the picker rows. */
+    paymentMethods(): Promise<PaymentMethod[]>;
+    /** Choose a payment method (folds any surcharge into the total). */
+    setPaymentMethod(method: string): Promise<Checkout>;
+    /** Place the order. Gateway methods start the payment and (by default)
+     *  redirect the browser to the gateway; cod/bank/manual complete directly. */
+    pay(opts?: PayOptions): Promise<PayResult>;
+    /** Re-fetch the checkout from the server. */
+    refresh(): Promise<void>;
+    /** Forget the checkout token (e.g. after the order is placed). */
+    clear(): void;
+}
+declare function CheckoutProvider({ children, }: {
+    children: React.ReactNode;
+}): React.ReactElement;
+declare function useCheckout(): CheckoutState;
+
+/**
+ * CheckoutFlow — the multi-step checkout, composed: address → shipping →
+ * payment, with a live OrderSummary alongside. Drop it onto your checkout route
+ * inside <CheckoutProvider>; it resumes the checkout from the stored token.
+ *
+ *   <CheckoutProvider>
+ *     <CheckoutFlow onOrderPlaced={(c) => navigate(`/order/${c.order_id}`)} />
+ *   </CheckoutProvider>
+ *
+ * Each step is a standalone component (AddressForm / ShippingPicker /
+ * PaymentSection) — use them directly for a fully custom layout.
+ */
+
+interface CheckoutFlowProps {
+    /** If set and no checkout exists yet, create one from this cart token. */
+    cartToken?: string;
+    /** Called when a (non-gateway) order is placed. Gateway flows redirect away
+     *  before this fires. */
+    onOrderPlaced?: (checkout: Checkout) => void;
+    /** Rendered when there's nothing to check out (no checkout, no cart token). */
+    emptyState?: React.ReactNode;
+    /** Rendered after a successful order (else a default confirmation). */
+    renderConfirmation?: (checkout: Checkout) => React.ReactNode;
+    /** Gateway return/cancel URLs (forwarded to PaymentSection). */
+    returnUrl?: string;
+    cancelUrl?: string;
+    locale?: string;
+}
+declare function CheckoutFlow({ cartToken, onOrderPlaced, emptyState, renderConfirmation, returnUrl, cancelUrl, locale, }: CheckoutFlowProps): React.ReactElement;
+
+/**
+ * AddressForm — collects email + shipping address (the checkout's first step).
+ * On submit it calls `setAddress` on the shared checkout, then `onComplete`.
+ * Controlled locally; seeds from the checkout if one already has an address
+ * (resumed flow). Billing defaults to the shipping address (same_as_shipping).
+ */
+
+interface AddressFormProps {
+    /** Override the section heading (defaults to the localized "Shipping address"). */
+    title?: string;
+    /** Override the submit label (defaults to the localized "Continue to shipping"). */
+    submitLabel?: string;
+    /** Called after the address is saved. */
+    onComplete?: () => void;
+}
+declare function AddressForm({ title, submitLabel, onComplete, }: AddressFormProps): React.ReactElement;
+
+/**
+ * ShippingPicker — fetches the shipping options for the checkout's address and
+ * lets the customer pick one. Selecting a row calls `setShippingMethod` (which
+ * recomputes totals). Requires the address step to be done first.
+ */
+
+interface ShippingPickerProps {
+    /** Override the section heading (defaults to the localized "Shipping method"). */
+    title?: string;
+    /** Override the submit label (defaults to "Continue to payment"). */
+    submitLabel?: string;
+    /** Called once a method is selected and saved. */
+    onComplete?: () => void;
+    locale?: string;
+}
+declare function ShippingPicker({ title, submitLabel, onComplete, locale, }: ShippingPickerProps): React.ReactElement;
+
+/**
+ * PaymentSection — lists the enabled payment methods, lets the customer pick
+ * one, and places the order. The category drives the final action:
+ *   • gateway        → `pay()` starts the payment and redirects to the gateway
+ *   • cod/bank/manual → `pay()` completes the order directly → `onOrderPlaced`
+ * The storefront never embeds a gateway — paying a card means a redirect.
+ */
+
+interface PaymentSectionProps {
+    title?: string;
+    /** Where the gateway returns the customer after paying (gateway methods).
+     *  Defaults to the current URL. */
+    returnUrl?: string;
+    cancelUrl?: string;
+    /** Called when a non-gateway order is placed (gateway flows redirect away). */
+    onOrderPlaced?: (checkout: Checkout) => void;
+    locale?: string;
+}
+declare function PaymentSection({ title, returnUrl, cancelUrl, onOrderPlaced, locale, }: PaymentSectionProps): React.ReactElement;
+
+/**
+ * OrderSummary — the checkout's running total: line items + the full breakdown
+ * (subtotal · discount · shipping · tax · surcharge · total). Reads the shared
+ * checkout; pass `checkout` explicitly to render it standalone (e.g. SSR).
+ */
+
+interface OrderSummaryProps {
+    /** Override the shared checkout (else read from <CheckoutProvider>). */
+    checkout?: Checkout;
+    /** Hide the line items, show totals only. */
+    totalsOnly?: boolean;
+    locale?: string;
+}
+declare function OrderSummary({ checkout: override, totalsOnly, locale, }: OrderSummaryProps): React.ReactElement | null;
+
+interface OrderStatusState {
+    order: OrderStatus | null;
+    loading: boolean;
+    error: Error | null;
+    reload(): void;
+}
+declare function useOrderStatus(statusToken: string | null, initial?: OrderStatus | null): OrderStatusState;
+
+/**
+ * OrderConfirmation — the compact post-checkout "thank you" block. Drop it on
+ * the return route after `checkout.complete()` / a gateway redirect back, keyed
+ * by the order's status token (`checkout.order_status_token`). Pass a
+ * pre-fetched `order` to render server-side.
+ */
+
+interface OrderConfirmationProps {
+    /** The order's status token (from `checkout.order_status_token`). */
+    statusToken?: string | null;
+    /** Pre-fetched order (SSR / loader) — skips the client fetch. */
+    order?: OrderStatus;
+    /** Link to the full order status page. */
+    statusHref?: string;
+    /** Heading copy (defaults to the localized "Thank you for your order!"). */
+    title?: string;
+    locale?: string;
+}
+declare function OrderConfirmation({ statusToken, order: initial, statusHref, title, locale, }: OrderConfirmationProps): React.ReactElement;
+
+/**
+ * OrderStatusPage — the full post-purchase status view: phase timeline (or a
+ * terminal banner), line items, totals, shipping method + tracking, the
+ * redacted delivery location, and payment. Keyed by the order's status token;
+ * pass a pre-fetched `order` to render server-side (Remix loader).
+ */
+
+interface OrderStatusPageProps {
+    statusToken?: string | null;
+    /** Pre-fetched order (SSR / loader) — skips the client fetch. */
+    order?: OrderStatus;
+    /** Contact-support callback (shown when the order allows it). */
+    onContactSupport?: () => void;
+    locale?: string;
+}
+declare function OrderStatusPage({ statusToken, order: initial, onContactSupport, locale, }: OrderStatusPageProps): React.ReactElement;
+
+/**
+ * AccountProvider + useAccount — shared logged-in-customer state. Resolves the
+ * session on mount (account.me); LoginForm / AccountDashboard / OrderHistory all
+ * read the same customer. Mount inside <NeviosProvider> (it needs the client).
+ */
+
+interface AccountState {
+    customer: Customer | null;
+    signedIn: boolean;
+    /** True until the initial session check resolves. */
+    loading: boolean;
+    requestMagicLink(email: string): Promise<MagicLinkResult>;
+    /** Exchange a magic token for a session (sets `customer`). */
+    verify(token: string): Promise<Customer>;
+    logout(): Promise<void>;
+    refresh(): Promise<void>;
+}
+declare function AccountProvider({ children }: {
+    children: React.ReactNode;
+}): React.ReactElement;
+declare function useAccount(): AccountState;
+type VerifyStatus = "idle" | "verifying" | "success" | "error";
+/** Drive the magic-link callback route: pass the token from the URL, get back a
+ *  status to render (and redirect on "success"). */
+declare function useMagicLinkVerify(token: string | null): {
+    status: VerifyStatus;
+};
+
+/**
+ * LoginForm — passwordless sign-in. Enter an email → we email a one-time link →
+ * "check your email". For test keys the API returns the link, which we surface
+ * as a dev shortcut so you can sign in without a real inbox.
+ */
+
+interface LoginFormProps {
+    /** Route that handles the magic link (default "/account/verify"). The dev
+     *  shortcut links here as `${verifyPath}?token=…`. */
+    verifyPath?: string;
+    onSent?: (email: string) => void;
+}
+declare function LoginForm({ verifyPath, onSent }: LoginFormProps): React.ReactElement;
+
+/**
+ * AccountDashboard — the signed-in header: greeting + sign-out. Compose
+ * OrderHistory / AddressBook (or your own) beneath it. Renders nothing while the
+ * session is still resolving; render <LoginForm> yourself when not signed in.
+ */
+
+interface AccountDashboardProps {
+    children?: React.ReactNode;
+}
+declare function AccountDashboard({ children }: AccountDashboardProps): React.ReactElement | null;
+
+/**
+ * OrderHistory — the signed-in customer's past orders, each linking to its
+ * public status page. Fetches on mount once signed in.
+ */
+
+interface OrderHistoryProps {
+    /** Map an order's status token → its status-page URL (default `/order/{token}`). */
+    statusHref?: (statusToken: string) => string;
+    /** Where to send the shopper after a successful reorder (default `/cart`).
+     *  Ignored when `onReorder` is provided. */
+    cartHref?: string;
+    /** Called after a reorder succeeds — override the default navigation. */
+    onReorder?: (result: ReorderResult) => void;
+    locale?: string;
+}
+declare function OrderHistory({ statusHref, cartHref, onReorder, locale, }: OrderHistoryProps): React.ReactElement;
+
+/**
+ * AddressBook — the signed-in customer's saved addresses with full management:
+ * add, edit, delete, and set-default. Each mutation calls the SDK then refetches
+ * the list. The form is the shared <AddressForm>.
+ */
+
+declare function AddressBook(): React.ReactElement;
+
+/**
+ * ProfileEditor — view + edit the signed-in customer's name, phone, and
+ * marketing consent (email is identity, shown read-only). Calls
+ * `account.updateProfile` and refreshes the shared account state on save.
+ */
+
+declare function ProfileEditor(): React.ReactElement | null;
+
+/**
+ * ProductJsonLd — schema.org/Product structured data for rich results (price,
+ * availability, brand). Drop it in the PDP <head> (or anywhere; it's a script).
+ * Availability maps from the variant stock state the storefront now projects.
+ *
+ *   <ProductJsonLd product={product} url={`https://shop.example.com/products/${product.handle}`} />
+ */
+
+interface ProductJsonLdProps {
+    product: Product;
+    /** Absolute canonical URL of this product page. */
+    url: string;
+    /** Origin used to absolutize relative media URLs (defaults to `url`'s origin). */
+    baseUrl?: string;
+    /** Brand name (defaults to `product.vendor`). */
+    brandName?: string;
+}
+declare function ProductJsonLd({ product, url, baseUrl, brandName, }: ProductJsonLdProps): React.ReactElement;
+
+/**
+ * BreadcrumbJsonLd — schema.org/BreadcrumbList for the trail Google shows under
+ * a result. Pass the crumbs in order (Home → Collection → Product); each needs
+ * an absolute URL.
+ *
+ *   <BreadcrumbJsonLd items={[
+ *     { name: "Home", url: "https://shop.example.com/" },
+ *     { name: "Shoes", url: "https://shop.example.com/collections/shoes" },
+ *     { name: product.title, url: productUrl },
+ *   ]} />
+ */
+
+interface BreadcrumbItem {
+    name: string;
+    url: string;
+}
+interface BreadcrumbJsonLdProps {
+    items: BreadcrumbItem[];
+}
+declare function BreadcrumbJsonLd({ items }: BreadcrumbJsonLdProps): React.ReactElement | null;
+
+/**
+ * OrganizationJsonLd — schema.org/Organization for the shop itself. Mount once
+ * (e.g. in the root layout): one Organization per domain is the best practice.
+ *
+ *   <OrganizationJsonLd name={shop.name} url="https://shop.example.com" logo={shop.logo} />
+ */
+
+interface OrganizationJsonLdProps {
+    name: string;
+    url?: string;
+    /** Logo URL (absolute). */
+    logo?: string;
+    /** Social / profile URLs. */
+    sameAs?: string[];
+}
+declare function OrganizationJsonLd({ name, url, logo, sameAs, }: OrganizationJsonLdProps): React.ReactElement;
+
+/**
+ * JSON-LD helpers. Structured data is *data*, but it's embedded in an inline
+ * `<script>` in the HTML, so it must be escaped against the one thing that can
+ * break out of that context: a literal `</script>` (and stray `<`, `>`, `&`).
+ * `serializeJsonLd` hex-escapes those; `<JsonLd>` renders the script tag.
+ */
+
+/** JSON-safe + HTML-script-safe serialization for embedding in `<script>`. */
+declare function serializeJsonLd(data: unknown): string;
+/** Strip HTML tags + collapse whitespace → plain text (for JSON-LD descriptions). */
+declare function stripHtml(html: string | null | undefined): string | undefined;
+/** Absolutize a possibly-relative URL against an origin. */
+declare function absoluteUrl(url: string, base?: string): string;
+interface JsonLdProps {
+    data: unknown;
+}
+/** Render a JSON-LD `<script>` for the given (already-shaped) data object. */
+declare function JsonLd({ data }: JsonLdProps): React.ReactElement;
+
+export { AccountDashboard, type AccountDashboardProps, AccountProvider, type AccountState, AddToCart, type AddToCartProps, AddressBook, AddressForm, type AddressFormProps, AvailabilityFilter, type AvailabilityFilterProps, BackInStockForm, type BackInStockFormProps, type BreadcrumbItem, BreadcrumbJsonLd, type BreadcrumbJsonLdProps, CartDrawer, type CartDrawerProps, CartLineItem, type CartLineItemProps, CartProvider, type CartState, CartSummary, type CartSummaryProps, CheckoutFlow, type CheckoutFlowProps, CheckoutProvider, type CheckoutState, CollectionPage, type CollectionPageProps, I18nProvider, type I18nProviderProps, type I18nValue, JsonLd, type JsonLdProps, LoginForm, type LoginFormProps, type MarketOption, MarketSwitcher, type MarketSwitcherProps, type MessageKey, type Messages, NeviosProvider, type NeviosProviderProps, OrderConfirmation, type OrderConfirmationProps, OrderHistory, type OrderHistoryProps, OrderStatusPage, type OrderStatusPageProps, type OrderStatusState, OrderSummary, type OrderSummaryProps, OrganizationJsonLd, type OrganizationJsonLdProps, type PayOptions, type PayResult, PaymentSection, type PaymentSectionProps, PriceMoney, type PriceMoneyProps, PriceRangeFilter, type PriceRangeFilterProps, ProductCard, type ProductCardProps, ProductDetailPage, type ProductDetailPageProps, ProductGallery, type ProductGalleryProps, ProductJsonLd, type ProductJsonLdProps, ProfileEditor, ShippingPicker, type ShippingPickerProps, SortSelect, type SortSelectProps, StockBadge, type StockBadgeProps, type StorefrontTheme, type TFunction, type TVars, TagFilter, type TagFilterProps, ThemeProvider, type ThemeProviderProps, VariantPicker, type VariantPickerProps, type VerifyStatus, absoluteUrl, bundledMessages, cs, en, formatCents, formatMoney, serializeJsonLd, stripHtml, themeToCssVars, useAccount, useCart, useCheckout, useI18n, useMagicLinkVerify, useOrderStatus, useStorefront, useStorefrontOptional, useT };