@liquidcommerce/elements-sdk 2.6.7 → 2.7.1

package/dist/types/modules/product-list/product-list-card.component.d.ts

@@ -0,0 +1,30 @@
+import type { IProductListProduct } from 'core/store/interfaces/product-list.interface';
+import type { IProductListComponent } from 'interfaces/configs';
+import { BaseComponent } from '@/core/base-component.service';
+import type { IFulfillment } from '@/interfaces/api/product.interface';
+export interface IProductListCardParams {
+    product: IProductListProduct;
+    shippingFulfillment: IFulfillment | null;
+    onDemandFulfillment: IFulfillment | null;
+    productUrl?: string;
+}
+export declare class ProductListCardComponent extends BaseComponent<IProductListCardParams, IProductListComponent> {
+    private selectedSize;
+    private unsubscribeFromState?;
+    constructor();
+    get hostClasses(): string[];
+    protected connected(): Promise<void>;
+    disconnected(): void;
+    private reRender;
+    protected template(): HTMLElement[];
+    private generateProductUrl;
+    private createVariantStandard;
+    private createImageSection;
+    private createContentSection;
+    private createPricePersonalizationSection;
+    private createSizesSection;
+    private handleDeliveryOptionsClick;
+    private createFulfillmentSectionWrapper;
+    createFulfillmentTextSection(selectedFulfillmentType: string, selectedFulfillmentRetailerName: string): HTMLElement;
+    private createAddToCartSection;
+}

package/dist/types/modules/product-list/product-list.commands.d.ts

@@ -1,17 +1,76 @@
+import type { IModalContentConfig } from 'core/store/interfaces/core.interface';
+import type { IProductSizeStore } from 'core/store/interfaces/product.interface';
+import type { IProductListProduct, IProductListStore } from 'core/store/interfaces/product-list.interface';
 import { BaseCommand } from '@/core/command/base-command.service';
-import type { IProduct } from '@/interfaces/api/product.interface';
-import type { IProductSearchParams, IProductSearchResponse } from '@/interfaces/api/product-list.interface';
+import { type FulfillmentType } from '@/enums';
+import type { IFulfillment, IProduct, IProductSizeAttributes, IRetailer } from '@/interfaces/api/product.interface';
+import type { IFilterSchema, INavigationResponse, IProductSearchParams, IProductSearchResponse } from '@/interfaces/api/product-list.interface';
+import type { ProductListFilterType } from '@/interfaces/core.interface';
 import { type AddItemParams } from '@/modules/cart/cart.commands';
+import type { IExtendedFilterSchema, IPagination, IProductAvailabilityData, IProductListFilters } from './product-list.interface';
+type StateListener = (state: IProductListStore) => void;
 export declare class ProductListCommands extends BaseCommand {
     private readonly uiCommands;
     private readonly cartCommands;
     private readonly checkoutCommands;
+    private readonly FILTER_TYPE_MAP;
+    private listeners;
     constructor();
     static getInstance(): ProductListCommands;
+    subscribe(listener: StateListener): () => void;
+    private getStoreState;
+    updateSearchTerm(searchTerm: string): void;
+    setLoading(isLoading: boolean): void;
+    private notifyListeners;
+    private initializeProductFulfillment;
+    private transformProductVariantsToFulfillments;
+    private transformSingleProduct;
+    private transformProductSize;
+    private addShippingFulfillments;
+    private addOnDemandFulfillments;
+    loadInitialProducts(page: number, perPage: number, searchTerm: string, currentFilters: IProductListFilters, configuredFilters: ProductListFilterType[]): Promise<void>;
+    loadMoreProducts(perPage: number, searchTerm: string, currentFilters: IProductListFilters, configuredFilters: ProductListFilterType[]): Promise<void>;
     getProductList(params: IProductSearchParams): Promise<IProductSearchResponse>;
+    syncFiltersFromComponent(filters: IProductListFilters): void;
+    getSanitizedFilters(filters: IFilterSchema[], configuredFilters: ProductListFilterType[]): IExtendedFilterSchema[];
+    buildSearchParams(page: number, perPage: number, searchTerm: string, currentFilters: IProductListFilters, configuredFilters: ProductListFilterType[]): IProductSearchParams;
+    private buildFilters;
+    private addToggleFilters;
+    private getBooleanFilterValue;
+    private addEngravingFilter;
+    private addPresaleFilter;
+    private addFulfillmentFilter;
+    private addPriceFilter;
+    private addDynamicFilters;
+    setGridConfig(rows: number, columns: number): void;
+    getItemsPerPage(): number;
+    updatePagination(navigation: INavigationResponse | undefined): IPagination;
+    createInitialPagination(): IPagination;
+    mergeRetailers(existingRetailers: Record<string, IRetailer>, newRetailers: Record<string, IRetailer>): Record<string, IRetailer>;
+    extractProductCardData(product: IProductListProduct, retailers: Record<string, IRetailer>): {
+        product: IProductListProduct;
+        retailer: IRetailer;
+    } | null;
+    private getFilterKeyToTypeMap;
     addToCart(params: AddItemParams): Promise<void>;
     addPresaleToCart(params: AddItemParams): Promise<void>;
     trackViewItemList(products: IProduct[]): void;
-    trackSelectItem(product: IProduct): void;
+    trackSelectItem(product: IProductListProduct): void;
     private convertProductToBaseItem;
+    openProductListModal(productId: string, contentType: IModalContentConfig['type'], data?: Record<string, any>): void;
+    closeProductListModal(productId: string): void;
+    selectFulfillmentType: (productId: string, selectedFulfillmentType: FulfillmentType) => Promise<void>;
+    selectFulfillment: (productId: string, fulfillmentId: string) => Promise<void>;
+    selectSize: (productId: string, sizeId: string) => Promise<void>;
+    private getFulfillmentForSize;
+    updateQuantity: (productId: string, quantity: number) => void;
+    getAvailabilityData(params: {
+        product: IProductListProduct;
+        size?: IProductSizeStore;
+        shippingFulfillment?: IFulfillment | null;
+        onDemandFulfillment?: IFulfillment | null;
+        state?: string;
+    }): IProductAvailabilityData;
+    isPresaleActive(sizeAttributes: IProductSizeAttributes): boolean;
 }
+export {};

package/dist/types/modules/product-list/product-list.component.d.ts

@@ -1,73 +1,45 @@
+import type { IProductListComponent } from 'interfaces/configs';
 import { BaseComponent, type IOnStoreChanged } from '@/core/base-component.service';
-import type { ProductListCardVariantType, ProductListFilterType } from '@/interfaces/core.interface';
+import type { ProductListFilterType } from '@/interfaces/core.interface';
 export interface IProductListComponentParams {
-    cardVariant: ProductListCardVariantType;
     rows: number;
     columns: number;
-    fillCard: boolean;
     filters: ProductListFilterType[];
     productUrl?: string;
 }
-export declare class ProductListComponent extends BaseComponent<IProductListComponentParams> {
+export declare class ProductListComponent extends BaseComponent<IProductListComponentParams, IProductListComponent> {
     private products;
     private retailers;
     private pagination;
-    private filters;
-    private searchFilter;
-    private currentFilters;
     private cardsContainer;
-    private filtersContainer;
-    private searchContainer;
     private sentinelElement;
-    private personalizedSwitch;
-    private preOrderSwitch;
-    private deliveryRadios;
-    private deliveryRadioLabels;
     private loadingState;
     private scrollObserver;
     private initializationPromise;
-    private filterDebounceTimer;
-    private readonly FILTER_DEBOUNCE_MS;
-    private filterButton;
+    private unsubscribeFromState?;
     get hostClasses(): string[];
     constructor();
     protected connected(): Promise<void>;
-    disconnectedCallback(): void;
+    disconnected(): void;
     private initializeComponent;
-    protected template(): HTMLElement[];
+    private handleStateUpdate;
+    private updateLoadingState;
+    private hasProductsChanged;
+    private updateProductData;
+    private handleProductRendering;
+    private renderSimplifiedProducts;
     private setLoadingState;
     private renderCurrentState;
     private loadInitialProducts;
-    private updateFiltersComponent;
     private loadMoreProducts;
-    private mergeRetailers;
-    private updatePagination;
-    private buildApiParams;
-    private buildFiltersFromState;
-    private syncFiltersFromResponse;
-    private onFilterChange;
-    private resetPagination;
-    private updateFiltersUI;
-    private updatePersonalizedSwitch;
-    private updatePreOrderSwitch;
-    private updateDeliveryOptions;
-    private updateRadioLabel;
-    private isPersonalizationDisabled;
-    private isPreOrderDisabled;
-    private isSameDayDeliveryDisabled;
+    private buildCurrentFiltersFromState;
+    private mapStateFilterToComponentFilter;
     private createCardsContainer;
-    private getResponsiveColumns;
     private renderLoadingState;
     private renderProducts;
     private appendNewProducts;
     private createProductCard;
-    private filterSanitizedFilters;
-    private buildFiltersParams;
-    private createSearchContainer;
-    private createFiltersContainer;
-    private storeFilterElementReferences;
-    private openFiltersDrawer;
-    private createFilterButton;
+    private getResponsiveColumns;
     private setupInfiniteScroll;
     private createScrollSentinel;
     private updateSentinel;
@@ -79,6 +51,7 @@ export declare class ProductListComponent extends BaseComponent<IProductListComp
     private showErrorState;
     private clearCardsContainer;
     private cleanupScrollObserver;
-    onStoreWatch(changes: IOnStoreChanged[]): Promise<void>;
     private doCleanup;
+    onStoreWatch(changes: IOnStoreChanged[]): Promise<void>;
+    protected template(): HTMLElement[];
 }

package/dist/types/{enums/cloud.enum.d.ts → modules/product-list/product-list.constants.d.ts}

@@ -1,4 +1,4 @@
-export declare const ENUM_FILTER_KEYS: {
+export declare const FILTER_KEYS: {
     readonly BRANDS: "brands";
     readonly FLAVOR: "flavor";
     readonly FULFILLMENT: "fulfillment";
@@ -18,3 +18,22 @@ export declare const ENUM_FILTER_KEYS: {
     readonly MATERIALS: "materials";
     readonly COLLECTION_TAGS: "collectionTags";
 };
+export declare const FULFILLMENT_OPTIONS: {
+    readonly ALL: "all";
+    readonly SHIPPING: "shipping";
+    readonly ON_DEMAND: "onDemand";
+};
+export declare const PRICE_OPTIONS: {
+    readonly MIN: "0";
+    readonly MAX: "1000";
+};
+export declare const FILTER_VALUE_OPTIONS: {
+    readonly YES: "YES";
+    readonly NO: "NO";
+};
+export declare const FILTER_LOADING_STATE: {
+    readonly IDLE: "idle";
+    readonly LOADING_INITIAL: "loading_initial";
+    readonly LOADING_MORE: "loading_more";
+    readonly ERROR: "error";
+};

package/dist/types/modules/product-list/product-list.interface.d.ts

@@ -1,24 +1,24 @@
+import type { IProductFulfillmentStore, IProductSizeStore } from 'core/store/interfaces/product.interface';
 import type { IFilterValue } from '@/interfaces/api/product-list.interface';
+export interface IPriceConfig {
+    min?: string;
+    max?: string;
+}
 export interface IProductListFilters {
-    personalized: boolean;
-    preOrder: boolean;
-    deliveryOptions: 'all' | 'shipping' | 'onDemand';
-    price?: {
-        min?: string;
-        max?: string;
-    };
-    [key: string]: any;
+    price?: IPriceConfig;
+    [key: string]: boolean | string | string[] | IPriceConfig | undefined;
 }
 export interface IExtendedFilterSchema {
-    category: string;
+    type: string;
     values: IFilterValue[];
 }
 export interface IProductListSearch {
-    searchTerm?: string;
+    searchTerm: string;
 }
 export interface IPagination {
     currentPage: number;
     totalPages: number;
+    totalCount: number;
     hasMorePages: boolean;
 }
 export interface ICheckboxLabelStates {
@@ -31,20 +31,6 @@ export interface ICheckboxLabelStates {
     iconElement: HTMLElement | null;
     hasUserInteraction: boolean;
 }
-export interface ICurrentFilters {
-    personalized: boolean;
-    preOrder: boolean;
-    deliveryOptions: 'all' | 'shipping' | 'onDemand';
-    price?: {
-        min?: string;
-        max?: string;
-    };
-    [key: string]: any;
-}
-export interface IPriceConfig {
-    min: string;
-    max: string;
-}
 export interface ICreateCheckboxItemParams {
     filter: IExtendedFilterSchema;
     state: ICheckboxLabelStates;
@@ -75,3 +61,26 @@ export interface IRenderCheckboxItemsParams {
 export interface ICreateFiltersContainerParams {
     isDrawerMode?: boolean;
 }
+export interface IProductAvailabilityData {
+    hasAvailability: boolean;
+    upc: string;
+    fulfillmentId: string;
+    partNumber: string;
+    quantity: number;
+    state: string;
+    isPresale: boolean;
+    isPresaleActive: boolean;
+    presaleShipBy: string | null;
+}
+export interface IProductVariantParams {
+    image: string;
+    name: string;
+    size: string | null;
+    price: number;
+    availability: IProductAvailabilityData;
+    hasPersonalization: boolean;
+    sizes: Record<string, IProductSizeStore>;
+    maxQuantityPerOrder: number;
+    shippingVariants: Record<string, IProductFulfillmentStore>;
+    onDemandVariants: Record<string, IProductFulfillmentStore>;
+}

package/dist/types/modules/product-list/styles/product-list-card.style.d.ts

@@ -0,0 +1 @@
+export declare const getProductListCardStyles: () => string;

package/dist/types/modules/product-list/styles/product-list-filters.style.d.ts

@@ -0,0 +1 @@
+export declare const getProductListFiltersStyles: () => string;

package/dist/types/modules/product-list/styles/register-styles.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modules/theme-provider/constants/component-groupings.d.ts

@@ -3,3 +3,4 @@ export declare const productGroupComponents: ComponentType[];
 export declare const addressGroupComponents: ComponentType[];
 export declare const cartGroupComponents: ComponentType[];
 export declare const checkoutGroupComponents: ComponentType[];
+export declare const productListGroupComponent: ComponentType[];

package/dist/types/modules/theme-provider/constants/css-variable-mappings.d.ts

@@ -1,2 +1,2 @@
-export type StylesheetType = 'global' | 'ui' | 'product' | 'address' | 'cart' | 'checkout';
+export type StylesheetType = 'global' | 'ui' | 'product' | 'address' | 'cart' | 'checkout' | 'product-list';
 export declare function getCSSVariableMapping(componentPrefix: string): Record<string, string>;

package/dist/types/modules/theme-provider/services/style-registry.service.d.ts

@@ -0,0 +1,16 @@
+import type { StylesheetType } from '../constants/css-variable-mappings';
+export type StyleGetter = () => string;
+declare class StyleRegistryService {
+    private static instance;
+    private registry;
+    private constructor();
+    static getInstance(): StyleRegistryService;
+    register(type: StylesheetType, getter: StyleGetter, priority?: number): void;
+    getStyleGetters(type: StylesheetType): StyleGetter[];
+    getStyles(type: StylesheetType): string[];
+    hasStyles(type: StylesheetType): boolean;
+    getRegisteredTypes(): StylesheetType[];
+    clear(): void;
+}
+export declare const styleRegistry: StyleRegistryService;
+export { StyleRegistryService };

package/dist/types/modules/theme-provider/services/stylesheet-generator.service.d.ts

@@ -9,5 +9,4 @@ export declare class StylesheetGeneratorService {
     private createStylesheet;
     private isCSSStyleSheetSupported;
     updateVariablesInStylesheet(type: StylesheetType, themeConfig: any, prefix: string): void;
-    private getStylesheetStyles;
 }

package/dist/types/modules/theme-provider/styles/register-styles.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/modules/theme-provider/theme-provider.service.d.ts

@@ -1,5 +1,5 @@
 import { type ComponentType } from '@/enums';
-import type { ConfigsKeyType, ConfigsType, IAllConfigs, UpdateAddressComponent, UpdateCartComponent, UpdateCheckoutComponent, UpdateComponentGlobalConfigs, UpdateProductComponent } from '@/interfaces/configs';
+import type { ConfigsKeyType, ConfigsType, IAllConfigs, UpdateAddressComponent, UpdateCartComponent, UpdateCheckoutComponent, UpdateComponentGlobalConfigs, UpdateProductComponent, UpdateProductListComponent } from '@/interfaces/configs';
 import { type GeneratedStylesheet } from './services/stylesheet-generator.service';
 export declare class ThemeProviderService {
     private data;
@@ -14,6 +14,7 @@ export declare class ThemeProviderService {
     updateAddressComponent(data: UpdateAddressComponent): void;
     updateCartComponent(data: UpdateCartComponent): void;
     updateCheckoutComponent(data: UpdateCheckoutComponent): void;
+    updateProductListComponent(data: UpdateProductListComponent): void;
     getConfigs<T = any>(type: ConfigsKeyType): T;
     getComponentConfig(componentType: ComponentType): ConfigsType | undefined;
     getStylesheet(componentType: ComponentType): GeneratedStylesheet[];

package/dist/types/modules/ui-components/engraving/engraving-form.component.d.ts

@@ -1,12 +1,23 @@
+import type { IProductListProduct } from 'core/store/interfaces/product-list.interface';
+import type { IFulfillment } from 'interfaces/api/product.interface';
 import { BaseComponent } from '@/core/base-component.service';
+import { type DisplayModeType, type NavigationSourceType } from '@/enums';
+import type { IProductListComponent } from '@/interfaces/configs';
 export interface IEngravingFormComponentParams {
     identifier: string;
-    context: 'product' | 'cart';
+    context: 'product' | 'cart' | 'product-list';
     lines: string[];
     maxLines: number;
     maxCharsPerLine: number;
     fee: number;
     location?: string;
+    displayMode?: DisplayModeType;
+    navigationSource?: NavigationSourceType;
+    product?: IProductListProduct;
+    shippingFulfillment?: IFulfillment | null;
+    onDemandFulfillment?: IFulfillment | null;
+    showCollections?: boolean;
+    config?: IProductListComponent;
 }
 export declare class EngravingFormComponent extends BaseComponent<IEngravingFormComponentParams, null> {
     get hostClasses(): string[];
@@ -20,6 +31,7 @@ export declare class EngravingFormComponent extends BaseComponent<IEngravingForm
     private calculateTotalPrice;
     private productInformationSection;
     private addToCartButtonText;
+    private getFulfillmentData;
     private retailersSection;
     private engravingLinesSection;
     private actionButtonsSection;

package/dist/types/modules/ui-components/input/index.d.ts

@@ -1,2 +1 @@
-export * from './birthdate-input.component';
 export * from './input.component';

package/dist/types/modules/ui-components/input/input.component.d.ts

@@ -5,9 +5,13 @@ export interface IInputValidation {
     max?: number;
     pattern?: string;
     customValidator?: (value: string) => string | null;
+    minYear?: number;
+    maxYear?: number;
+    minAge?: number;
+    maxAge?: number;
 }
 export interface IInputComponentParams {
-    inputType: 'text' | 'number' | 'email' | 'tel' | 'date';
+    inputType: 'text' | 'number' | 'email' | 'tel' | 'date' | 'birthdate';
     value?: string | null;
     placeholder?: string;
     className?: string;
@@ -31,6 +35,9 @@ export declare class InputComponent extends BaseComponent<IInputComponentParams,
     private validateEmail;
     private validateTel;
     private validateDate;
+    private parseDateString;
+    private calculateAge;
+    private validateDateConstraints;
     private isFieldComplete;
     private validateInput;
     private scheduleValidation;

package/dist/types/modules/ui-components/modal/modal.component.d.ts

@@ -0,0 +1,23 @@
+import { BaseComponent, type IOnStoreChanged } from '@/core/base-component.service';
+export declare class ModalComponent extends BaseComponent {
+    private isOpen;
+    private wrapperElement;
+    private modalElement;
+    private backdropElement;
+    private contentContainer;
+    private currentContentType;
+    private readonly boundHandleKeydown;
+    constructor();
+    disconnected(): void;
+    onStoreChanged(changes: IOnStoreChanged[]): boolean;
+    private openWithContent;
+    private open;
+    private close;
+    private cleanupCurrentContent;
+    private handleBackdropClick;
+    private handleKeydown;
+    private updateModalContentTypeClass;
+    private updateModalState;
+    private isElementsEnabled;
+    protected template(): HTMLElement;
+}

package/dist/types/modules/ui-components/styles/modal.style.d.ts

@@ -0,0 +1 @@
+export declare function getModalStyles(): string;

package/dist/types/modules/ui-components/ui.commands.d.ts

@@ -1,7 +1,9 @@
 import { BaseCommand } from '@/core/command/base-command.service';
-import type { IDrawerContentConfig } from '@/core/store/interfaces/core.interface';
+import type { IDrawerContentConfig, IModalContentConfig } from '@/core/store/interfaces/core.interface';
 export declare class UICommands extends BaseCommand {
     static getInstance(): UICommands;
     openDrawer(contentType: IDrawerContentConfig['type'], data?: Record<string, any>): void;
     closeDrawer(): void;
+    openModal(contentType: IModalContentConfig['type'], data?: Record<string, any>): void;
+    closeModal(): void;
 }

package/dist/types/static/icon/check.icon.d.ts

@@ -0,0 +1,2 @@
+import type { IconProps } from './icon.types';
+export declare const CheckIcon: ({ width, height, className, color }: IconProps) => string;

package/dist/types/static/icon/index.d.ts

@@ -1,5 +1,6 @@
 export * from './arrow-right.icon';
 export * from './bag.icon';
+export * from './check.icon';
 export * from './checkbox.icon';
 export * from './chevron-down.icon';
 export * from './chevron-left.icon';

package/docs/gitbook/actions.md

@@ -0,0 +1,160 @@
+# Actions
+
+Actions let you control Elements programmatically after the SDK initializes. All actions live under `window.elements.actions.*`.
+
+## Quick start
+```js
+window.addEventListener('lce:actions.client_ready', () => {
+  window.elements.actions.cart.openCart();
+});
+```
+
+## Product actions
+- `actions.product.getDetails(identifier)`
+  Returns the current loaded product data (price, size, fulfillment, retailer, quantity, images, etc.). The product must already be injected and loaded.
+
+```js
+const product = window.elements.actions.product.getDetails('00619947000020');
+console.log(product.name, product.price);
+```
+
+## Cart actions
+- `actions.cart.openCart()`
+  Opens the cart drawer.
+- `actions.cart.closeCart()`
+  Closes the cart drawer.
+- `actions.cart.toggleCart()`
+  Toggles the cart drawer open/closed.
+- `actions.cart.addProduct(params[], openCart?)`
+  Adds one or more products to the cart. If no address is set, the SDK prompts for one and retries automatically.
+- `actions.cart.applyPromoCode(promoCode)`
+  Applies a promo code (replaces any existing code).
+- `actions.cart.removePromoCode()`
+  Removes the active promo code.
+- `actions.cart.resetCart()`
+  Clears all cart items (no undo).
+- `actions.cart.getDetails()`
+  Returns current cart data (items, totals, promo, retailers, etc.).
+
+```js
+await window.elements.actions.cart.addProduct([
+  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+], true);
+
+await window.elements.actions.cart.applyPromoCode('SUMMER20');
+await window.elements.actions.cart.removePromoCode();
+await window.elements.actions.cart.resetCart();
+
+const cart = window.elements.actions.cart.getDetails();
+```
+
+## Checkout actions
+- `actions.checkout.openCheckout()`
+  Opens the checkout drawer.
+- `actions.checkout.closeCheckout()`
+  Closes the checkout drawer.
+- `actions.checkout.toggleCheckout()`
+  Toggles the checkout drawer open/closed.
+- `actions.checkout.exitCheckout()`
+  Navigates away from checkout (requires `exitUrl` config).
+- `actions.checkout.addProduct(params[], openCheckout?)`
+  Adds products directly to checkout (bypasses cart).
+- `actions.checkout.applyPromoCode(promoCode)`
+  Applies a promo code in checkout.
+- `actions.checkout.removePromoCode()`
+  Removes the active promo code.
+- `actions.checkout.applyGiftCard(code)`
+  Applies a gift card.
+- `actions.checkout.removeGiftCard(code)`
+  Removes a gift card.
+- `actions.checkout.toggleIsGift(active?)`
+  Enables/disables gift mode (or toggles when omitted).
+- `actions.checkout.toggleBillingSameAsShipping(active?)`
+  Sets billing address to match shipping.
+- `actions.checkout.toggleMarketingPreferences(field, active)`
+  Sets marketing opt-in (`canEmail` or `canSms`).
+- `actions.checkout.updateCustomerInfo(fields)`
+  Prefills customer info (name, email, phone, birthdate, etc.).
+- `actions.checkout.updateBillingInfo(fields)`
+  Prefills billing address fields.
+- `actions.checkout.updateGiftInfo(fields)`
+  Prefills gift recipient information.
+
+```js
+window.elements.actions.checkout.openCheckout();
+window.elements.actions.checkout.closeCheckout();
+window.elements.actions.checkout.toggleCheckout();
+
+await window.elements.actions.checkout.addProduct([
+  { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+], true);
+
+await window.elements.actions.checkout.applyPromoCode('WELCOME10');
+await window.elements.actions.checkout.applyGiftCard('GIFT-1234-5678');
+
+await window.elements.actions.checkout.toggleIsGift(true);
+await window.elements.actions.checkout.toggleBillingSameAsShipping(false);
+await window.elements.actions.checkout.toggleMarketingPreferences('canEmail', true);
+
+window.elements.actions.checkout.updateCustomerInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  email: 'john@example.com'
+});
+
+window.elements.actions.checkout.updateBillingInfo({
+  firstName: 'John',
+  lastName: 'Doe',
+  addressOne: '789 Elm St',
+  city: 'Chicago',
+  state: 'IL',
+  zipCode: '60601'
+});
+
+window.elements.actions.checkout.updateGiftInfo({
+  firstName: 'Jane',
+  lastName: 'Smith',
+  message: 'Happy Birthday!'
+});
+```
+
+## Address actions
+- `actions.address.setAddressByPlacesId(placesId)`
+  Sets address using a Google Places ID (recommended).
+- `actions.address.setAddressManually(address, coordinates)`
+  Sets address with your own address + lat/long data.
+- `actions.address.getDetails()`
+  Returns the current address (or null if not set).
+- `actions.address.clear()`
+  Removes the stored address and resets availability.
+
+```js
+await window.elements.actions.address.setAddressByPlacesId('ChIJOwg_06VPwokRYv534QaPC8g');
+
+await window.elements.actions.address.setAddressManually(
+  { one: '123 Main Street', city: 'New York', state: 'NY', zip: '10001' },
+  { latitude: 40.7128, longitude: -74.0060 }
+);
+
+const address = window.elements.actions.address.getDetails();
+await window.elements.actions.address.clear();
+```
+
+## UI helpers (non-actions)
+These helpers live under `window.elements.ui.*` and are commonly used with actions.
+
+- `ui.cartButton(containerId, showItemsCount?)`
+  Renders a cart button inside the given container.
+- `ui.floatingCartButton(showItemsCount?)`
+  Renders a floating cart button (bottom-right).
+- `ui.cartSubtotal(elementId)`
+  Keeps an element updated with cart subtotal.
+- `ui.cartItemsCount(elementId, { hideZero })`
+  Keeps an element updated with cart item count.
+
+```js
+window.elements.ui.cartButton('header-cart', true);
+window.elements.ui.floatingCartButton(true);
+window.elements.ui.cartSubtotal('cart-total');
+window.elements.ui.cartItemsCount('items-count', { hideZero: true });
+```