@liquidcommerce/elements-sdk 2.6.7 → 2.7.1

package/docs/v1/reference/error-handling.md

@@ -0,0 +1,70 @@
+# Error Handling
+
+The SDK emits errors as events and (when applicable) throws a custom `SDKError`. Your app should handle both.
+
+## SDKError
+
+All SDK errors use a custom error class:
+
+```typescript
+class SDKError extends Error {
+  constructor(message: string, reThrow?: boolean);
+  name: 'SDKError';
+  isSdk: boolean;
+  reThrow: boolean;
+}
+```
+
+## Catching Errors
+
+```javascript
+try {
+  await window.elements.injectProductElement([
+    { containerId: 'product', identifier: 'invalid_id' }
+  ]);
+} catch (error) {
+  if (error.name === 'SDKError') {
+    console.error('SDK Error:', error);
+  }
+}
+```
+
+## Error Isolation
+
+The SDK catches and contains its own errors so your app keeps running:
+
+```javascript
+window.elements.actions.cart.addProduct([/* invalid */]);
+console.log('App still working');
+```
+
+## Error Events
+
+Listen for failure events to show user-friendly messages or trigger retries:
+
+```javascript
+// Cart add failed
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  console.error('Failed to add:', event.detail.data.error);
+});
+
+// Address failed
+window.addEventListener('lce:actions.address_failed', (event) => {
+  console.error('Address error:', event.detail.data.error);
+});
+
+// Checkout submit failed
+window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
+  console.error('Checkout failed:', event.detail.data.error);
+});
+```
+
+## UI Errors
+
+When a component fails to load, the SDK renders an error view inside the container and logs details to the console.
+
+## Related Docs
+
+- [Events Guide](../guides/events.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/performance.md

@@ -0,0 +1,54 @@
+# Performance Guide
+
+The SDK is optimized out of the box. These tweaks help reduce load time and layout shift.
+
+## 1) Load Non-Blocking
+
+```html
+<script defer data-liquid-commerce-elements ...></script>
+```
+
+## 2) Use the Checkout-Only Build When Appropriate
+
+If you only need checkout, use the tree-shaken build:
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+```
+
+## 3) Inject Components When Needed
+
+Inject above-the-fold products first, then load the rest:
+
+```javascript
+await client.injectProductElement([
+  { containerId: 'hero-product', identifier: '001' }
+]);
+
+setTimeout(async () => {
+  await client.injectProductElement([
+    { containerId: 'related-1', identifier: '002' },
+    { containerId: 'related-2', identifier: '003' }
+  ]);
+}, 1000);
+```
+
+## 4) Reserve Space to Prevent Layout Shift
+
+```css
+#product {
+  min-height: 600px;
+}
+```
+
+## 5) Let the SDK Handle Media Optimization
+
+The SDK automatically:
+- Lazy loads images
+- Uses responsive image sizes
+- Virtualizes carousel images
+
+## Related Docs
+
+- [Best Practices](../guides/best-practices.md)
+- [Product Component](../guides/product-component.md)

package/docs/v1/reference/troubleshooting.md

@@ -0,0 +1,64 @@
+# Troubleshooting
+
+Common setup issues and how to resolve them.
+
+## SDK Script Not Loading
+
+**Symptoms:** 404/CORS in Network tab, `window.elements` is undefined.
+
+**Fixes:**
+- Verify the script URL and that the tag includes `data-liquid-commerce-elements`.
+- Check ad blockers; proxy the API if needed.
+- Confirm `data-env` is set correctly.
+
+## Web Components Error
+
+**Symptoms:** Console logs about Custom Elements or Shadow DOM.
+
+**Fix:** Add the Web Components polyfill before the SDK:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
+<script defer data-liquid-commerce-elements ...></script>
+```
+
+## Product Not Showing
+
+**Symptoms:** Empty container or error view.
+
+**Fixes:**
+- Confirm the container ID matches your HTML.
+- Verify the product identifier exists.
+- Check for errors in the console or network tab.
+
+## Cart Drawer Not Opening
+
+**Symptoms:** Add to cart works but cart stays closed.
+
+**Fixes:**
+- Ensure a cart button is configured or call `window.elements.actions.cart.openCart()`.
+- Check for JavaScript errors in the console.
+
+## Checkout Issues
+
+**Symptoms:** Checkout fails to load or submit.
+
+**Fixes:**
+- Verify you are on a supported browser.
+- Look for `checkout_*_failed` events in the console.
+- Check for Stripe-related errors in the browser console.
+
+## Address/Availability Problems
+
+**Symptoms:** Products show unavailable or address prompts fail.
+
+**Fixes:**
+- Make sure the address is set and valid.
+- Listen for `lce:actions.address_failed` to surface errors.
+
+## Related Docs
+
+- [Installation](../getting-started/installation.md)
+- [Browser Support](./browser-support.md)
+- [Error Handling](./error-handling.md)
+- [Proxy Setup](../integration/proxy-setup.md)

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.6.7",
+  "version": "2.7.1",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -13,21 +13,23 @@
     "url": "https://github.com/liquidcommerce/elements-sdk/issues"
   },
   "module": "./dist/index.esm.js",
-  "browser": "./umd/elements.js",
   "types": "./dist/types/index.d.ts",
   "packageManager": "pnpm@10.0.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
       "import": "./dist/index.esm.js",
-      "browser": "./umd/elements.js",
       "default": "./dist/index.esm.js"
     },
+    "./checkout": {
+      "types": "./dist/types/index.checkout.d.ts",
+      "import": "./dist/index.checkout.esm.js",
+      "default": "./dist/index.checkout.esm.js"
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
-    "umd",
     "docs",
     "README.md",
     "LICENSE"
@@ -39,21 +41,26 @@
   "type": "module",
   "sideEffects": [
     "dist/index.esm.js",
+    "dist/index.checkout.esm.js",
     "umd/elements.js",
+    "umd/elements-checkout.js",
     "src/index.ts",
-    "src/index.umd.ts"
+    "src/index.umd.ts",
+    "src/index.checkout.ts",
+    "src/index.checkout.umd.ts"
   ],
   "scripts": {
     "build": "rollup -c",
+    "build:checkout": "rollup -c rollup.config.checkout.mjs",
     "build:dev": "rollup -c --environment NODE_ENV:development",
     "dev": "rollup -c -w",
     "type-check": "tsc --noEmit",
     "lint": "pnpm biome lint --write",
     "format": "biome format --write",
     "check": "pnpm biome check --write .",
-    "fl": "pnpm check && pnpm build:dev",
+    "fl": "pnpm check && pnpm build && pnpm build:checkout",
     "changelog": "conventional-changelog -p angular -i CHANGELOG.md -s",
-    "clean": "rm -rf dist umd node_modules && pnpm install && pnpm build",
+    "clean": "rm -rf dist umd node_modules && pnpm install && pnpm build && pnpm build:checkout",
     "prepublishOnly": "pnpm run build",
     "deprecate:old": "npm deprecate @liquidcommerceteam/elements-sdk@\"*\" \"Package moved to @liquidcommerce/elements-sdk\"",
     "prepare": "husky"
@@ -70,9 +77,9 @@
     "embeddable commerce"
   ],
   "devDependencies": {
-    "@biomejs/biome": "2.3.10",
-    "@commitlint/cli": "^20.2.0",
-    "@commitlint/config-conventional": "^20.2.0",
+    "@biomejs/biome": "2.3.12",
+    "@commitlint/cli": "^20.3.1",
+    "@commitlint/config-conventional": "^20.3.1",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "^29.0.0",
     "@rollup/plugin-json": "^6.1.0",
@@ -86,11 +93,11 @@
     "@semantic-release/npm": "^13.1.3",
     "@semantic-release/release-notes-generator": "^14.1.0",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^25.0.3",
+    "@types/node": "^25.0.10",
     "conventional-changelog-cli": "^5.0.0",
     "husky": "^9.1.7",
     "process": "^0.11.10",
-    "rollup": "^4.54.0",
+    "rollup": "^4.56.0",
     "rollup-obfuscator": "^4.1.1",
     "rollup-plugin-typescript2": "^0.36.0",
     "semantic-release": "^25.0.2",

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

@@ -1,37 +0,0 @@
-import { BaseComponent } from '@/core/base-component.service';
-import type { IFulfillment, IProduct } from '@/interfaces/api/product.interface';
-import type { ProductListCardVariantType } from '@/interfaces/core.interface';
-export interface IProductListCardParams {
-    variant: ProductListCardVariantType;
-    fillCard: boolean;
-    product: IProduct;
-    shippingFulfillment: IFulfillment | null;
-    onDemandFulfillment: IFulfillment | null;
-    productUrl?: string;
-}
-export interface IProductAvailabilityData {
-    hasAvailability: boolean;
-    upc: string;
-    fulfillmentId: string;
-    partNumber: string;
-    quantity: number;
-    state: string;
-    isPresale: boolean;
-    isPresaleActive: boolean;
-}
-export interface IProductVariantParams {
-    image: string;
-    name: string;
-    size: string | null;
-    price: number;
-    availability: IProductAvailabilityData;
-}
-export declare class ProductListCardComponent extends BaseComponent<IProductListCardParams> {
-    get hostClasses(): string[];
-    private getAvailabilityData;
-    private isPresaleActive;
-    private handleAddToCart;
-    protected template(): HTMLElement[];
-    private generateProductUrl;
-    private createVariantStandard;
-}

package/dist/types/modules/product-list/components/product-list-filters-subcomponents/index.d.ts

@@ -1,6 +0,0 @@
-export * from './product-list-apply-filter-button.component';
-export * from './product-list-checkbox-filter.components';
-export * from './product-list-delivery-options-filter.components';
-export * from './product-list-price-filter.components';
-export * from './product-list-search.component';
-export * from './product-list-toggle-filters.components';

package/dist/types/modules/product-list/components/product-list-filters-subcomponents/product-list-apply-filter-button.component.d.ts

@@ -1 +0,0 @@
-export declare function createApplyFiltersButton(onCloseDrawer: VoidFunction): HTMLElement;

package/dist/types/modules/product-list/components/product-list-filters-subcomponents/product-list-delivery-options-filter.components.d.ts

@@ -1,16 +0,0 @@
-export interface ICreateDeliveryOptionsFilterParams {
-    currentFilters?: {
-        deliveryOptions?: string;
-        personalized?: boolean;
-        preOrder?: boolean;
-    };
-    deliveryCollapsed: boolean;
-    isSameDayDeliveryDisabled: boolean;
-    onDeliveryOptionsChange?: (value: 'all' | 'shipping' | 'onDemand') => void;
-    onToggleCollapse: () => void;
-}
-export declare function createDeliveryOptionsFilter(params: ICreateDeliveryOptionsFilterParams): {
-    elements: HTMLElement[];
-    chevronContainer: HTMLElement;
-    deliveryOptionsList: HTMLElement;
-};

package/dist/types/modules/product-list/components/product-list-filters-subcomponents/product-list-search.component.d.ts

@@ -1,16 +0,0 @@
-import { BaseComponent } from '@/core/base-component.service';
-export interface IProductListSearchParams {
-    searchTerm?: string;
-    handleInputChange?: (search: string) => void;
-    clearSearch?: VoidFunction;
-}
-export declare class ProductListSearchComponent extends BaseComponent<IProductListSearchParams> {
-    private searchInput?;
-    private clearButton?;
-    private readonly ALLOWED_CHARACTERS;
-    private readonly MAX_LENGTH;
-    get hostClasses(): string[];
-    protected template(): HTMLElement[];
-    private sanitizeInput;
-    private updateClearButtonVisibility;
-}

package/dist/types/modules/product-list/components/product-list-filters-subcomponents/product-list-toggle-filters.components.d.ts

@@ -1,18 +0,0 @@
-export interface ICreatePersonalizedFilterParams {
-    currentFilters?: {
-        personalized?: boolean;
-        deliveryOptions?: string;
-    };
-    isPersonalizationDisabled: boolean;
-    onPersonalizedChange?: (enabled: boolean) => void;
-}
-export interface ICreatePreOrderFilterParams {
-    currentFilters?: {
-        preOrder?: boolean;
-        deliveryOptions?: string;
-    };
-    isPreOrderDisabled: boolean;
-    onPreOrderChange?: (enabled: boolean) => void;
-}
-export declare function createPersonalizedFilter(params: ICreatePersonalizedFilterParams): HTMLElement[];
-export declare function createPreOrderFilter(params: ICreatePreOrderFilterParams): HTMLElement[];

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

@@ -1 +0,0 @@
-export * from './address.style';

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

@@ -1 +0,0 @@
-export * from './cart.style';

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

@@ -1 +0,0 @@
-export * from './checkout.style';

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

@@ -1,3 +0,0 @@
-export * from './image-carousel.style';
-export * from './product.style';
-export * from './retailers.style';

package/dist/types/modules/theme-provider/styles/product-list/index.d.ts

@@ -1 +0,0 @@
-export * from './product-list.style';

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

@@ -1,3 +0,0 @@
-export * from './drawer.style';
-export * from './loading.style';
-export * from './promo-code-ticker.style';

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

@@ -1,53 +0,0 @@
-import { BaseComponent } from '@/core/base-component.service';
-export interface IBirthdateValidation {
-    required?: boolean;
-    minYear?: number;
-    maxYear?: number;
-    minAge?: number;
-    maxAge?: number;
-    customValidator?: (date: string) => string | null;
-}
-export interface IBirthdateInputComponentParams {
-    value?: string;
-    className?: string;
-    validation?: IBirthdateValidation;
-    onValidation?: (isValid: boolean, errors: string[]) => void;
-    onChange?: (value: string) => void;
-    label?: string;
-    name: string;
-    disabled?: boolean;
-}
-export declare class BirthdateInputComponent extends BaseComponent<IBirthdateInputComponentParams, null> {
-    get hostClasses(): string[];
-    private monthInput;
-    private dayInput;
-    private yearInput;
-    private errorContainer;
-    private validationTimeout;
-    afterRender(): void;
-    private populateInitialValue;
-    private setupEventListeners;
-    private formatMonth;
-    private formatDay;
-    private formatYear;
-    private padMonthOnBlur;
-    private padDayOnBlur;
-    private handleNavigation;
-    private handleChange;
-    private isFieldsComplete;
-    private scheduleValidation;
-    private getFormattedValue;
-    private validateDate;
-    private calculateAge;
-    private validateInput;
-    private showErrors;
-    private clearErrors;
-    getValue(): string;
-    setValue(value: string): void;
-    validate(): boolean;
-    focus(): void;
-    disable(): void;
-    enable(): void;
-    clear(): void;
-    protected template(): HTMLElement[];
-}