@liquidcommerce/elements-sdk 2.6.0-beta.9 → 2.6.0-beta.91

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

@@ -1,12 +1,15 @@
 import { BaseComponent } from '@/core/base-component.service';
+import { type DisplayModeType } from '@/enums';
 export interface IEngravingFormComponentParams {
     identifier: string;
-    context: 'product' | 'cart';
+    context: 'product' | 'cart' | 'product-list';
+    slug?: string;
     lines: string[];
     maxLines: number;
     maxCharsPerLine: number;
     fee: number;
     location?: string;
+    displayMode?: DisplayModeType;
 }
 export declare class EngravingFormComponent extends BaseComponent<IEngravingFormComponentParams, null> {
     get hostClasses(): string[];
@@ -15,10 +18,12 @@ export declare class EngravingFormComponent extends BaseComponent<IEngravingForm
     private addToCartButton;
     private fulfillmentId;
     private partNumber;
+    private isPresale;
     beforeConnected(): void;
     private calculateTotalPrice;
     private productInformationSection;
     private addToCartButtonText;
+    private getFulfillmentData;
     private retailersSection;
     private engravingLinesSection;
     private actionButtonsSection;

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

@@ -2,12 +2,17 @@ import { BaseComponent } from '@/core/base-component.service';
 import type { IProductComponent } from '@/interfaces/configs';
 export interface IEngravingViewComponentParams {
     identifier: string;
-    context: 'cart' | 'checkout';
+    context: 'cart' | 'checkout' | 'product-list';
+    slug?: string;
+    productListMaxLines?: number;
+    productListMaxCharsPerLine?: number;
+    productListLocation?: string;
 }
 export declare class EngravingViewComponent extends BaseComponent<IEngravingViewComponentParams, IProductComponent> {
     get hostClasses(): string[];
     private engravingQuantityFee;
     private engravingLines;
+    private isEngravingRequired;
     private handleEdit;
     private handleRemove;
     protected template(): HTMLElement | HTMLElement[] | string;

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/lce-element/lce-element.component.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentType } from '@/enums';
-export declare class LceElementComponent extends HTMLElement {
+import { SafeHTMLElement } from '@/utils/dom-compat';
+export declare class LceElementComponent extends SafeHTMLElement {
     private _initialized;
     protected _container: ShadowRoot | null;
     private _wrappedComponentRerender;

package/dist/types/modules/ui-components/promo-code-ticker/promo-code-ticker.component.d.ts

@@ -1,7 +1,7 @@
 import { BaseComponent, type IOnStoreChanged } from '@/core/base-component.service';
 import type { IPromoTicker } from '@/interfaces/configs';
 export interface IPromoCodeTickerParams {
-    context: 'cart' | 'checkout';
+    context: 'cart';
     tickers: IPromoTicker[];
 }
 export declare class PromoCodeTickerComponent extends BaseComponent<IPromoCodeTickerParams, null> {

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

@@ -2,6 +2,10 @@ import { BaseCommand } from '@/core/command/base-command.service';
 import type { IDrawerContentConfig } from '@/core/store/interfaces/core.interface';
 export declare class UICommands extends BaseCommand {
     static getInstance(): UICommands;
-    openDrawer(contentType: IDrawerContentConfig['type'], data?: Record<string, any>): void;
+    openDrawer({ mode, contentType, data, }: {
+        mode?: 'drawer' | 'modal';
+        contentType: IDrawerContentConfig['type'];
+        data?: Record<string, any>;
+    }): void;
     closeDrawer(): void;
 }

package/dist/types/ssr/stub.checkout.d.ts

@@ -0,0 +1,6 @@
+export type { DebugMode, ElementsEnv } from '../enums/core.enum';
+export { DEBUG_MODE, ELEMENTS_ENV } from '../enums/core.enum';
+export type { IElementsCheckoutActions, IElementsCheckoutClient, } from '../interfaces/client.interface';
+export type { IInjectedComponent } from '../interfaces/component.interface';
+export type { ILiquidCommerceElementsCheckoutClientConfig } from '../interfaces/config.interface';
+export declare function ElementsCheckout(..._args: any[]): Promise<null>;

package/dist/types/ssr/stub.d.ts

@@ -0,0 +1,10 @@
+export { SDKError, isSDKError } from '../core/sdk-error-handler';
+export type { CartEventLevel, CartEventType, CheckoutEventLevel, CheckoutEventType, ComponentType, DebugMode, DisplayModeType, ElementsEnv, FulfillmentType, NavigationSourceType, } from '../enums/core.enum';
+export { CART_EVENT_LEVEL, CART_EVENT_TYPE, CHECKOUT_EVENT_LEVEL, CHECKOUT_EVENT_TYPE, COMPONENT_TYPE, DEBUG_MODE, DISPLAY_MODE, ELEMENTS_ACTIONS_EVENT, ELEMENTS_ENV, ELEMENTS_FORM, FULFILLMENT_TYPE, NAVIGATION_SOURCE, } from '../enums/core.enum';
+export type { ILiquidCommerceElementsActions, ILiquidCommerceElementsBuilderClient, ILiquidCommerceElementsClient, } from '../interfaces/client.interface';
+export type { IInjectedComponent } from '../interfaces/component.interface';
+export type { IElementsProxyConfig, ILiquidCommerceElementsBuilderConfig, ILiquidCommerceElementsCheckoutConfig, ILiquidCommerceElementsConfig, ILiquidCommerceElementsDevelopmentConfig, } from '../interfaces/config.interface';
+export type * from '../interfaces/configs';
+export type { IBuilderInjectElementParams, IInjectCheckoutBuilderParams, IInjectCheckoutParams, IInjectProductElement, IInjectProductListFiltersParams, IInjectProductListParams, IInjectProductListSearchParams, ProductListFilterType, } from '../interfaces/injection.interface';
+export declare function Elements(..._args: any[]): Promise<null>;
+export declare function ElementsBuilder(..._args: any[]): Promise<null>;

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/dist/types/utils/dom-compat.d.ts

@@ -0,0 +1,2 @@
+export declare const SafeHTMLElement: typeof HTMLElement;
+export declare function isHTMLElement(value: unknown): value is HTMLElement;

package/dist/types/utils/format.d.ts

@@ -1,21 +1,7 @@
 export declare function centToDollar(cent: number): number;
 export declare function formatCentToDollarText(cent: number, showZeroDecimals?: boolean): string;
 export declare function htmlStringToElement(htmlString: string): HTMLElement;
-export declare function format24TimeTo12(time24h: string): string;
 export declare function formatISODateToMMDDYYYY(isoDateString: string | null | undefined): string;
-export declare function validateMinimumAge(birthDate: string | Date | null | undefined, minimumAge?: number, minimumYear?: number): {
-    isValid: boolean;
-    age: number | null;
-    error?: string;
-};
-export declare function buildFormattedAddressString(address: {
-    one: string;
-    two: string;
-    city: string;
-    state: string;
-    zip: string;
-    country?: string;
-}): string;
 export declare function capitalizeFirstLetter(text: string): string;
 export declare function splitCategoryPath(catPath?: string): {
     category: string;

package/dist/types/utils/image-bg-removal.d.ts

@@ -0,0 +1,3 @@
+export declare const IMG_BG_REMOVAL_HOST_CLASS = "lc-bg-removal";
+export declare function applyImageBackgroundTreatment(target: HTMLElement | null, imageUrl: string | undefined | null, bgProbe?: Element): void;
+export declare const getImageBgRemovalStyles: () => string;

package/dist/types/utils/product-selection.d.ts

@@ -0,0 +1,16 @@
+import type { IProductFulfillmentStore, IProductSizeStore } from '@/core/store/interfaces/product.interface';
+import { type FulfillmentType } from '@/enums';
+export interface ISizeSelectionResult {
+    selectedFulfillmentType: FulfillmentType;
+    selectedFulfillment: IProductFulfillmentStore | null;
+    selectedFulfillmentId: string | null;
+    productHasAvailability: boolean;
+    fulfillmentHasAvailability: boolean;
+}
+export interface IFulfillmentTypeChangeResult {
+    selectedFulfillment: IProductFulfillmentStore | null;
+    selectedFulfillmentId: string | null;
+    fulfillmentHasAvailability: boolean;
+}
+export declare function calculateSizeSelection(productSize: IProductSizeStore, currentFulfillmentType: FulfillmentType): ISizeSelectionResult;
+export declare function calculateFulfillmentTypeChange(productSize: IProductSizeStore, newFulfillmentType: FulfillmentType): IFulfillmentTypeChangeResult | null;

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

@@ -0,0 +1,15 @@
+import type { IProductStore } from '@/core/store/interfaces/product.interface';
+import type { IPLProductStore } from '@/core/store/interfaces/product-list.interface';
+import type { IProduct, IProductAvailabilityResponse } from '@/interfaces/api/product.interface';
+export interface IPrepareApiProductForStoreParams {
+    context: 'product-list' | 'product-page';
+    product: IProduct;
+    retailers: IProductAvailabilityResponse['retailers'];
+    enableShippingFulfillment: boolean;
+}
+export declare function buildSizeLabel(size: {
+    size: string;
+    pack: boolean;
+    packDesc: string;
+}): string;
+export declare function prepareApiProductForStore({ context, product, retailers, enableShippingFulfillment, }: IPrepareApiProductForStoreParams): IProductStore | IPLProductStore;

package/docs/v1/README.md

@@ -0,0 +1,210 @@
+# Elements SDK v1 Documentation
+
+Welcome to the comprehensive documentation for the LiquidCommerce Elements SDK v1.
+
+## What is Elements SDK?
+
+The Elements SDK is a Web Components-based e-commerce SDK that allows you to add product displays, shopping carts, and checkout flows to any website with minimal code.
+
+## Quick Links
+
+- **[Installation](./getting-started/installation.md)** - Get started in minutes
+- **[Quick Start](./getting-started/quick-start.md)** - Build your first product page
+- **[API Reference](./api/client.md)** - Complete API documentation
+
+## Documentation Sections
+
+### Getting Started
+
+Essential guides for new users:
+
+- **[Installation](./getting-started/installation.md)** - CDN, NPM, and framework integration
+- **[Quick Start](./getting-started/quick-start.md)** - Your first product page in 5 minutes
+- **[Core Concepts](./getting-started/concepts.md)** - Understand how the SDK works
+
+### Component Guides
+
+In-depth guides for each major component:
+
+- **[Product Component](./guides/product-component.md)** - Display products with add-to-cart functionality
+- **[Cart Component](./guides/cart-component.md)** - Shopping cart and item management
+- **[Checkout Component](./guides/checkout-component.md)** - Complete purchase flow
+- **[Address Component](./guides/address-component.md)** - Delivery location management
+- **[Product List Component](./guides/product-list-component.md)** - Filterable product catalogs
+- **[Theming](./guides/theming.md)** - Customize appearance and branding
+- **[Events](./guides/events.md)** - Event system and subscriptions
+- **[Best Practices](./guides/best-practices.md)** - Patterns, tips, and recommendations
+
+### API Reference
+
+Complete API documentation:
+
+**Core API:**
+- **[Client API](./api/client.md)** - Main SDK client interface
+- **[Injection Methods](./api/injection-methods.md)** - Component injection
+- **[UI Helpers](./api/ui-helpers.md)** - Cart buttons and UI elements
+- **[Configuration](./api/configuration.md)** - All configuration options
+- **[TypeScript Types](./api/typescript-types.md)** - Type definitions
+
+**Actions API:**
+- **[Product Actions](./api/actions/product-actions.md)** - `actions.product.*`
+- **[Address Actions](./api/actions/address-actions.md)** - `actions.address.*`
+- **[Cart Actions](./api/actions/cart-actions.md)** - `actions.cart.*`
+- **[Checkout Actions](./api/actions/checkout-actions.md)** - `actions.checkout.*`
+
+### Architecture (To Be Done In Future Versions)
+
+Deep dive into SDK internals:
+
+- **[Overview](./architecture/overview.md)** - System architecture
+- **[Initialization](./architecture/initialization.md)** - Phased initialization process
+- **[State Management](./architecture/state-management.md)** - Store service and persistence
+- **[Event System](./architecture/event-system.md)** - PubSub architecture
+- **[Web Components](./architecture/web-components.md)** - Component factory and Shadow DOM
+- **[Build System](./architecture/build-system.md)** - Bundles and tree-shaking
+
+### Framework Integration
+
+Integration guides for popular frameworks:
+
+- **[React](./integration/react.md)** - React integration patterns and hooks
+- **[Next.js](./integration/nextjs.md)** - Next.js setup with SSR considerations
+- **[Vue](./integration/vue.md)** - Vue component integration
+- **[Angular](./integration/angular.md)** - Angular client-only setup
+- **[Laravel](./integration/laravel.md)** - Blade + CDN integration
+- **[Vanilla JavaScript](./integration/vanilla-js.md)** - Pure JavaScript integration
+- **[Proxy Setup](./integration/proxy-setup.md)** - Ad blocker avoidance
+
+### Reference
+
+Technical reference and troubleshooting:
+
+- **[Browser Support](./reference/browser-support.md)** - Compatibility matrix
+- **[Troubleshooting](./reference/troubleshooting.md)** - Common issues and solutions
+- **[Error Handling](./reference/error-handling.md)** - Error types and debugging
+- **[Performance](./reference/performance.md)** - Optimization tips and best practices
+
+### Examples
+
+Practical examples with working code:
+
+- **[Simple Product Page](./examples/simple-product-page.md)** - Basic PDP implementation
+- **[Multi-Product Page](./examples/multi-product-page.md)** - Multiple products on one page
+- **[Complete Checkout Flow](./examples/checkout-flow.md)** - Full e-commerce flow
+- **[Custom Theming](./examples/custom-theming.md)** - Brand customization examples
+- **[Advanced Patterns](./examples/advanced-patterns.md)** - Complex integration scenarios
+
+## Common Tasks
+
+### Adding a Product
+
+**Declarative (HTML):**
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-container-1="product"
+  data-product-1="00619947000020"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+
+<div id="product"></div>
+```
+
+**Programmatic (JavaScript):**
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+await client.injectProductElement([
+  { containerId: 'product', identifier: '00619947000020' }
+]);
+```
+
+### Opening the Cart
+
+```javascript
+window.LiquidCommerce.elements.actions.cart.openCart();
+```
+
+### Adding to Cart Programmatically
+
+```javascript
+await window.LiquidCommerce.elements.actions.cart.addProduct([
+  {
+    identifier: '00619947000020',
+    fulfillmentType: 'shipping',
+    quantity: 1
+  }
+], true);  // true = open cart after adding
+```
+
+### Listening for Events
+
+```javascript
+window.addEventListener('lce:actions.cart_item_added', (event) => {
+  console.log('Item added to cart:', event.detail.data);
+});
+```
+
+### Customizing Theme
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff',
+        buttonCornerRadius: '8px'
+      }
+    }
+  }
+});
+```
+
+## Key Concepts
+
+### Web Components
+The SDK uses native Web Components for framework-agnostic integration and style encapsulation.
+
+### Shadow DOM
+Components use Shadow DOM to prevent CSS conflicts and ensure consistent styling.
+
+### Auto-Initialization
+When using the CDN, the SDK automatically initializes based on HTML data attributes.
+
+### Event-Driven
+The SDK publishes events for all user interactions, allowing you to react to changes.
+
+### State Persistence
+Cart and address data persist across sessions using localStorage with API fallback.
+
+## Browser Requirements
+
+- Chrome 66+ (March 2018)
+- Firefox 60+ (May 2018)
+- Safari 12+ (September 2018)
+- Edge 79+ (January 2020)
+
+Requires Web Components and Shadow DOM support.
+
+## Support
+
+For assistance, contact your LiquidCommerce representative.
+
+## Version History
+
+This is the v1 documentation. Future versions will be documented in separate directories (`v2/`, `v3/`, etc.).
+
+## Contributing
+
+Found an issue in the documentation? Contact your LiquidCommerce representative with suggestions.
+
+---
+
+## Navigation
+
+- [← Back to Repository](../)
+- [Getting Started →](./getting-started/installation.md)