@jay-framework/wix-cart 0.15.0

package/dist/index.client-VoD54p4E.d.ts

@@ -0,0 +1,436 @@
+import * as _jay_framework_runtime from '@jay-framework/runtime';
+import { HTMLElementProxy, HTMLElementCollectionProxy } from '@jay-framework/runtime';
+import { Getter } from '@jay-framework/reactive';
+import { currentCart } from '@wix/ecom';
+import { LineItem, Cart } from '@wix/auto_sdk_ecom_current-cart';
+import { BuildDescriptors } from '@wix/sdk-types';
+import * as _jay_framework_fullstack_component from '@jay-framework/fullstack-component';
+import { Signals, PageProps } from '@jay-framework/fullstack-component';
+import * as _jay_framework_component from '@jay-framework/component';
+
+/**
+ * Cart Helper Types and Functions
+ *
+ * Shared types and mappers for cart operations.
+ * Used by both context and components.
+ */
+
+type CurrentCartClient = BuildDescriptors<typeof currentCart, {}>;
+type EstimateMethod = CurrentCartClient['estimateCurrentCartTotals'];
+type EstimateTotalsResult = Awaited<ReturnType<EstimateMethod>>;
+/**
+ * Cart line item for display
+ */
+interface CartLineItem {
+    lineItemId: string;
+    productId: string;
+    productName: string;
+    productUrl: string;
+    variantName: string;
+    sku: string;
+    image: {
+        url: string;
+        altText: string;
+    };
+    quantity: number;
+    unitPrice: {
+        amount: string;
+        formattedAmount: string;
+    };
+    lineTotal: {
+        amount: string;
+        formattedAmount: string;
+    };
+    lineDiscount: {
+        amount: string;
+        formattedAmount: string;
+    };
+    hasDiscount: boolean;
+}
+/**
+ * Cart summary for display
+ */
+interface CartSummary {
+    itemCount: number;
+    subtotal: {
+        amount: string;
+        formattedAmount: string;
+    };
+    discount: {
+        amount: string;
+        formattedAmount: string;
+    };
+    hasDiscount: boolean;
+    estimatedTax: {
+        amount: string;
+        formattedAmount: string;
+    };
+    showTax: boolean;
+    estimatedTotal: {
+        amount: string;
+        formattedAmount: string;
+    };
+    currency: string;
+}
+/**
+ * Full cart state
+ */
+interface CartState {
+    cartId: string;
+    isEmpty: boolean;
+    lineItems: CartLineItem[];
+    summary: CartSummary;
+    appliedCoupon: string;
+    hasAppliedCoupon: boolean;
+}
+/**
+ * Cart indicator data (lightweight)
+ */
+interface CartIndicatorState {
+    itemCount: number;
+    hasItems: boolean;
+}
+/**
+ * Map cart line item from Wix API to our format
+ */
+declare function mapLineItem(item: LineItem): CartLineItem;
+/**
+ * Map cart to our summary format (basic - without estimate totals)
+ */
+declare function mapCartSummary(cart: Cart | null): CartSummary;
+/**
+ * Map cart to full state (basic - without estimate totals)
+ */
+declare function mapCartToState(cart: Cart | null): CartState;
+/**
+ * Get empty cart state
+ */
+declare function getEmptyCartState(): CartState;
+/**
+ * Map cart to indicator state (lightweight)
+ */
+declare function mapCartToIndicator(cart: Cart | null): CartIndicatorState;
+/**
+ * Get the current cart, treating 404 as an empty cart.
+ *
+ * The Wix Cart API returns 404 when no cart exists (before first item is added).
+ * This helper normalizes that case to return null, which the mappers handle as empty.
+ */
+declare function getCurrentCartOrNull(cartClient: CurrentCartClient): Promise<Cart | null>;
+/**
+ * Estimate the current cart totals, treating 404 as an empty cart.
+ *
+ * This API provides complete price totals including tax calculations.
+ * Use this for cart pages where accurate totals are needed.
+ *
+ * @see https://dev.wix.com/docs/sdk/backend-modules/ecom/current-cart/estimate-current-cart-totals
+ */
+declare function estimateCurrentCartTotalsOrNull(cartClient: CurrentCartClient): Promise<EstimateTotalsResult | null>;
+/**
+ * Map estimate totals response to CartState.
+ * The estimate response includes calculated totals with tax.
+ */
+declare function mapEstimateTotalsToState(estimate: EstimateTotalsResult | null): CartState;
+
+/**
+ * Configuration passed from server to client for Wix Cart.
+ */
+interface WixCartInitData {
+    /** Enable client-side cart operations */
+    enableClientCart: boolean;
+}
+/**
+ * Reactive cart indicator state.
+ * Signals update automatically when cart operations occur.
+ */
+interface ReactiveCartIndicator {
+    /** Number of items in cart (reactive signal) */
+    itemCount: Getter<number>;
+    /** Whether cart has items (reactive signal) */
+    hasItems: Getter<boolean>;
+}
+/**
+ * Result of a cart operation that modifies items.
+ */
+interface CartOperationResult {
+    /** Updated cart state after the operation */
+    cartState: CartState;
+}
+/**
+ * Options for add to cart operation.
+ * Used by consumers (wix-stores, wix-stores-v1) to pass variant information.
+ */
+interface AddToCartOptions {
+    /** Variant ID for the product */
+    variantId?: string;
+    /** Custom text fields as (key, value) pairs */
+    customTextFields?: Record<string, string>;
+    /** Modifiers as (key, value) pairs */
+    modifiers?: Record<string, string>;
+    /** Product slug for building the correct product page URL in cart */
+    productSlug?: string;
+}
+/**
+ * Client-side Wix Cart context interface.
+ * Provides reactive cart indicator and encapsulated cart operations.
+ */
+interface WixCartContext {
+    /**
+     * Reactive cart indicator signals.
+     * Use these in render functions for automatic updates.
+     */
+    cartIndicator: ReactiveCartIndicator;
+    /**
+     * Refresh cart indicator from server.
+     * Call this after external cart changes or on page load.
+     */
+    refreshCartIndicator(): Promise<void>;
+    /**
+     * Get full cart state with estimated totals (subtotal, tax, total).
+     * Handles 404 (no cart) as empty cart.
+     * Use this for cart pages where accurate totals are needed.
+     */
+    getEstimatedCart(): Promise<CartState>;
+    /**
+     * Add a product to the cart.
+     * Automatically updates the cart indicator signals.
+     *
+     * @param productId - The product ID to add
+     * @param quantity - Number of items to add (default: 1)
+     * @param options - Variant and modifier options
+     * @returns Updated cart state
+     */
+    addToCart(productId: string, quantity?: number, options?: AddToCartOptions): Promise<CartOperationResult>;
+    /**
+     * Remove line items from the cart.
+     * Automatically updates the cart indicator signals.
+     *
+     * @param lineItemIds - Array of line item IDs to remove
+     * @returns Updated cart state
+     */
+    removeLineItems(lineItemIds: string[]): Promise<CartOperationResult>;
+    /**
+     * Update a line item's quantity.
+     * If quantity is 0, the item is removed.
+     * Automatically updates the cart indicator signals.
+     *
+     * @param lineItemId - The line item ID to update
+     * @param quantity - New quantity (0 removes the item)
+     * @returns Updated cart state
+     */
+    updateLineItemQuantity(lineItemId: string, quantity: number): Promise<CartOperationResult>;
+    /**
+     * Clear all items from the cart.
+     * Automatically updates the cart indicator signals.
+     */
+    clearCart(): Promise<void>;
+    /**
+     * Apply a coupon code to the cart.
+     * Automatically updates the cart indicator signals.
+     *
+     * @param couponCode - The coupon code to apply
+     * @returns Updated cart state
+     */
+    applyCoupon(couponCode: string): Promise<CartOperationResult>;
+    /**
+     * Remove applied coupon from the cart.
+     * Automatically updates the cart indicator signals.
+     *
+     * @returns Updated cart state
+     */
+    removeCoupon(): Promise<CartOperationResult>;
+}
+/**
+ * Context marker for client-side Wix Cart operations.
+ */
+declare const WIX_CART_CONTEXT: _jay_framework_runtime.ContextMarker<WixCartContext>;
+/**
+ * Initialize and register the Wix Cart client context.
+ * Called during client-side initialization.
+ *
+ * Assumes WIX_CLIENT_CONTEXT is already initialized with a valid client.
+ *
+ * @returns The created context for immediate use (e.g., to call refreshCartIndicator)
+ */
+declare function provideWixCartContext(): WixCartContext;
+
+interface CartIndicatorViewState {
+  itemCount: number,
+  hasItems: boolean,
+  isLoading: boolean,
+  justAdded: boolean
+}
+
+type CartIndicatorSlowViewState = {};
+
+type CartIndicatorFastViewState = Pick<CartIndicatorViewState, 'itemCount' | 'hasItems' | 'isLoading' | 'justAdded'>;
+
+type CartIndicatorInteractiveViewState = Pick<CartIndicatorViewState, 'itemCount' | 'hasItems' | 'isLoading' | 'justAdded'>;
+
+
+interface CartIndicatorRefs {
+  cartButton: HTMLElementProxy<CartIndicatorViewState, HTMLButtonElement>,
+  cartLink: HTMLElementProxy<CartIndicatorViewState, HTMLAnchorElement>
+}
+
+interface WixCartService {
+    cart: BuildDescriptors<typeof currentCart, {}>;
+}
+/**
+ * Server service marker for Wix Cart.
+ * Use with `.withServices(WIX_CART_SERVICE)` in component definitions.
+ */
+declare const WIX_CART_SERVICE: _jay_framework_fullstack_component.ServiceMarker<WixCartService>;
+
+interface CartIndicatorFastCarryForward {
+}
+/**
+ * Cart Indicator Component
+ *
+ * Displays cart item count in site header.
+ * Automatically updates when items are added to cart.
+ */
+declare const cartIndicator: _jay_framework_fullstack_component.JayStackComponentDefinition<CartIndicatorRefs, CartIndicatorSlowViewState, CartIndicatorFastViewState, CartIndicatorInteractiveViewState, [WixCartService], [Signals<CartIndicatorFastViewState>, CartIndicatorFastCarryForward, WixCartContext], PageProps, {}, _jay_framework_component.JayComponentCore<PageProps, CartIndicatorInteractiveViewState>>;
+
+interface ImageOfLineItemOfCartPageViewState {
+  url: string,
+  altText: string
+}
+
+interface UnitPriceOfLineItemOfCartPageViewState {
+  amount: string,
+  formattedAmount: string
+}
+
+interface LineTotalOfLineItemOfCartPageViewState {
+  amount: string,
+  formattedAmount: string
+}
+
+interface LineDiscountOfLineItemOfCartPageViewState {
+  amount: string,
+  formattedAmount: string
+}
+
+interface LineItemOfCartPageViewState {
+  lineItemId: string,
+  productId: string,
+  productName: string,
+  productUrl: string,
+  variantName: string,
+  sku: string,
+  image: ImageOfLineItemOfCartPageViewState,
+  quantity: number,
+  isUpdatingQuantity: boolean,
+  unitPrice: UnitPriceOfLineItemOfCartPageViewState,
+  lineTotal: LineTotalOfLineItemOfCartPageViewState,
+  lineDiscount: LineDiscountOfLineItemOfCartPageViewState,
+  hasDiscount: boolean,
+  isRemoving: boolean
+}
+
+interface SubtotalOfSummaryOfCartPageViewState {
+  amount: string,
+  formattedAmount: string
+}
+
+interface DiscountOfSummaryOfCartPageViewState {
+  amount: string,
+  formattedAmount: string
+}
+
+interface EstimatedTaxOfSummaryOfCartPageViewState {
+  amount: string,
+  formattedAmount: string
+}
+
+interface EstimatedTotalOfSummaryOfCartPageViewState {
+  amount: string,
+  formattedAmount: string
+}
+
+interface SummaryOfCartPageViewState {
+  itemCount: number,
+  subtotal: SubtotalOfSummaryOfCartPageViewState,
+  discount: DiscountOfSummaryOfCartPageViewState,
+  hasDiscount: boolean,
+  estimatedTax: EstimatedTaxOfSummaryOfCartPageViewState,
+  showTax: boolean,
+  estimatedTotal: EstimatedTotalOfSummaryOfCartPageViewState,
+  currency: string
+}
+
+interface CouponOfCartPageViewState {
+  code: string,
+  isApplying: boolean,
+  appliedCode: string,
+  hasAppliedCoupon: boolean,
+  errorMessage: string,
+  hasError: boolean
+}
+
+interface CartPageViewState {
+  cartId: string,
+  isEmpty: boolean,
+  isLoading: boolean,
+  lineItems: Array<LineItemOfCartPageViewState>,
+  summary: SummaryOfCartPageViewState,
+  coupon: CouponOfCartPageViewState,
+  isCheckingOut: boolean,
+  emptyCartMessage: string
+}
+
+type CartPageSlowViewState = Pick<CartPageViewState, 'cartId' | 'emptyCartMessage'>;
+
+type CartPageFastViewState = Pick<CartPageViewState, 'isEmpty' | 'isLoading' | 'isCheckingOut'> & {
+    lineItems: Array<CartPageViewState['lineItems'][number]>;
+    summary: CartPageViewState['summary'];
+    coupon: CartPageViewState['coupon'];
+};
+
+type CartPageInteractiveViewState = Pick<CartPageViewState, 'isEmpty' | 'isLoading' | 'isCheckingOut'> & {
+    lineItems: Array<CartPageViewState['lineItems'][number]>;
+    summary: CartPageViewState['summary'];
+    coupon: CartPageViewState['coupon'];
+};
+
+
+interface CartPageRefs {
+  checkoutButton: HTMLElementProxy<CartPageViewState, HTMLButtonElement>,
+  continueShoppingLink: HTMLElementProxy<CartPageViewState, HTMLAnchorElement>,
+  clearCartButton: HTMLElementProxy<CartPageViewState, HTMLButtonElement>,
+  emptyCartLink: HTMLElementProxy<CartPageViewState, HTMLAnchorElement>,
+  lineItems: {
+    productLink: HTMLElementCollectionProxy<LineItemOfCartPageViewState, HTMLAnchorElement>,
+    quantity: HTMLElementCollectionProxy<LineItemOfCartPageViewState, HTMLInputElement>,
+    decrementButton: HTMLElementCollectionProxy<LineItemOfCartPageViewState, HTMLButtonElement>,
+    incrementButton: HTMLElementCollectionProxy<LineItemOfCartPageViewState, HTMLButtonElement>,
+    removeButton: HTMLElementCollectionProxy<LineItemOfCartPageViewState, HTMLButtonElement>
+  },
+  coupon: {
+    code: HTMLElementProxy<CouponOfCartPageViewState, HTMLInputElement>,
+    applyButton: HTMLElementProxy<CouponOfCartPageViewState, HTMLButtonElement>,
+    removeButton: HTMLElementProxy<CouponOfCartPageViewState, HTMLButtonElement>
+  }
+}
+
+interface CartPageSlowCarryForward {
+}
+interface CartPageFastCarryForward {
+}
+/**
+ * Cart Page Component
+ *
+ * Full shopping cart page with:
+ * - Line item display with images, names, variants
+ * - Quantity adjustment (increment/decrement/input)
+ * - Item removal
+ * - Cart summary (subtotal, discounts, total)
+ * - Coupon code application
+ * - Checkout button
+ */
+declare const cartPage: _jay_framework_fullstack_component.JayStackComponentDefinition<CartPageRefs, CartPageSlowViewState, CartPageFastViewState, CartPageInteractiveViewState, [CartPageSlowCarryForward, WixCartService], [Signals<CartPageFastViewState>, CartPageFastCarryForward, WixCartContext], PageProps, {}, _jay_framework_component.JayComponentCore<PageProps, CartPageInteractiveViewState>>;
+
+declare const init: _jay_framework_fullstack_component.JayInit<WixCartInitData>;
+
+export { type AddToCartOptions as A, type CartOperationResult as C, type ReactiveCartIndicator as R, type WixCartService as W, WIX_CART_SERVICE as a, WIX_CART_CONTEXT as b, type WixCartContext as c, type WixCartInitData as d, mapCartSummary as e, mapCartToState as f, mapCartToIndicator as g, getEmptyCartState as h, getCurrentCartOrNull as i, estimateCurrentCartTotalsOrNull as j, mapEstimateTotalsToState as k, type CartState as l, mapLineItem as m, type CartLineItem as n, type CartSummary as o, provideWixCartContext as p, type CartIndicatorState as q, cartIndicator as r, cartPage as s, init as t };

package/dist/index.client.d.ts

@@ -0,0 +1,8 @@
+export { A as AddToCartOptions, q as CartIndicatorState, n as CartLineItem, C as CartOperationResult, l as CartState, o as CartSummary, R as ReactiveCartIndicator, b as WIX_CART_CONTEXT, c as WixCartContext, r as cartIndicator, s as cartPage, t as init } from './index.client-VoD54p4E.js';
+import '@jay-framework/runtime';
+import '@jay-framework/reactive';
+import '@wix/ecom';
+import '@wix/auto_sdk_ecom_current-cart';
+import '@wix/sdk-types';
+import '@jay-framework/fullstack-component';
+import '@jay-framework/component';