@liquidcommerce/elements-sdk 2.6.0-beta.11 → 2.6.0-beta.110

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

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

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

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

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,24 +1,15 @@
 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 formatISOInstantToMMDDYYYY(isoInstant: string | null | undefined, timeZone?: string): string;
 export declare function capitalizeFirstLetter(text: string): string;
 export declare function splitCategoryPath(catPath?: string): {
     category: string;
     category2: string;
     category3: string;
 };
+export declare function normalizeEngravingLines(lines: readonly (string | null | undefined)[] | null | undefined): string[];
+export declare function normalizeText<T extends string | null | undefined>(value: T): T;
+export declare function normalizeEmail<T extends string | null | undefined>(value: T): T;
+export declare function normalizeCode<T extends string | null | undefined>(value: T): T;

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,18 @@
+import type { IProductStore } from '@/core/store/interfaces/product.interface';
+import type { IPLProductStore } from '@/core/store/interfaces/product-list.interface';
+import { type FulfillmentType } from '@/enums';
+import type { IProduct, IProductAvailabilityResponse } from '@/interfaces/api/product.interface';
+export interface IPrepareApiProductForStoreParams {
+    context: 'product-list' | 'product-page';
+    product: IProduct;
+    retailers: IProductAvailabilityResponse['retailers'];
+    enableShippingFulfillment: boolean;
+    enableOnDemandFulfillment?: boolean;
+    primaryFulfillmentMethod?: FulfillmentType;
+}
+export declare function buildSizeLabel(size: {
+    size: string;
+    pack: boolean;
+    packDesc: string;
+}): string;
+export declare function prepareApiProductForStore({ context, product, retailers, enableShippingFulfillment, enableOnDemandFulfillment, primaryFulfillmentMethod, }: IPrepareApiProductForStoreParams): IProductStore | IPLProductStore;

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

@@ -1,3 +1,9 @@
+export declare const BUSINESS_CONTRACT_TIMEZONE = "America/New_York";
+export declare function getDatePartsInTimezone(instant: Date, timeZone: string): {
+    year: string;
+    month: string;
+    day: string;
+} | null;
 export declare function detectUserTimezone(addressState?: string): string;
 export declare function getCurrentTimeInTimezone(timezone: string): Date;
 export declare function getCurrentTimeInUserTimezone(addressState?: string): Date;

package/docs/v1/README.md

@@ -0,0 +1,213 @@
+# 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
+- **[Accessibility](./guides/accessibility.md)** - Keyboard, screen reader, contrast and focus behaviour
+- **[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
+- **[Analytics](./reference/analytics.md)** - Google Tag Manager / GA4 integration
+- **[Telemetry](./reference/telemetry.md)** - What the SDK reports and how to control it
+
+### 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)

package/docs/v1/api/actions/address-actions.md

@@ -0,0 +1,286 @@
+# Address Actions API
+
+Address actions allow you to programmatically manage the delivery location.
+
+## actions.address.setAddressByPlacesId()
+
+Set address using a Google Places ID.
+
+### Signature
+
+```typescript
+setAddressByPlacesId(placesId: string): Promise<void>
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `placesId` | string | Yes | Google Places ID |
+
+### Example
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(
+  'ChIJOwg_06VPwokRYv534QaPC8g'
+);
+```
+
+### How to Get Places ID
+
+Visit [Google Place IDs](https://developers.google.com/maps/documentation/places/web-service/place-id#find-id) for details on obtaining a Places ID.
+
+---
+
+## actions.address.setAddressManually()
+
+Set address manually without Google Places.
+
+### Signature
+
+```typescript
+setAddressManually(
+  address: IAddressAddress,
+  coordinates: IAddressCoordinates
+): Promise<void>
+```
+
+### Parameters
+
+```typescript
+interface IAddressAddress {
+  one: string;     // Street address
+  two: string;     // Apt, suite, etc.
+  city: string;    // City name
+  state: string;   // Two-letter state code
+  zip: string;     // ZIP/postal code
+  country: string; // Country
+}
+
+interface IAddressCoordinates {
+  latitude: number;   // -90 to 90
+  longitude: number;  // -180 to 180
+}
+```
+
+### Example
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.setAddressManually(
+  {
+    one: '123 Main Street',
+    two: 'Apt 4',
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+    country: 'US'
+  },
+  {
+    latitude: 40.7128,
+    longitude: -74.0060
+  }
+);
+```
+
+### Validation
+
+The SDK validates:
+- All required fields are present (street, city, state, zip)
+- Latitude is between -90 and 90
+- Longitude is between -180 and 180
+
+> Note: the `state` field is expected to be a 2-letter code by convention, but the SDK does **not** enforce its format.
+
+### Errors
+
+**Throws `SDKError` if:**
+- `address` or `coordinates` is missing
+- A required field is missing (street, city, state, zip)
+- Latitude or longitude is non-numeric
+- Coordinates are out of range (latitude outside -90..90, longitude outside -180..180)
+
+---
+
+## actions.address.clear()
+
+Remove the current address.
+
+### Signature
+
+```typescript
+clear(): Promise<void>
+```
+
+### Example
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.clear();
+```
+
+### Effects
+
+- Clears stored address
+- Products will prompt for address on next add-to-cart
+- Cart/checkout require re-entering address
+
+---
+
+## actions.address.getDetails()
+
+Retrieve the current address.
+
+### Signature
+
+```typescript
+getDetails(): IAddressData | null
+```
+
+### Returns
+
+```typescript
+interface IAddressData {
+  id: string;  // Google Places ID (always populated when an object is returned)
+  address: {
+    one: string;
+    two: string;
+    city: string;
+    state: string;
+    zip: string;
+    country: string;
+  };
+  coordinates: {
+    latitude: number;
+    longitude: number;
+  };
+  formattedAddress: string;
+}
+```
+
+Returns `null` if no address is set. Manually-entered addresses (set via `setAddressManually`) are stored without a Google Places ID, so `getDetails()` also returns `null` for them.
+
+### Example
+
+```javascript
+const address = window.LiquidCommerce.elements.actions.address.getDetails();
+
+if (address) {
+  console.log('Current address:', address.formattedAddress);
+  console.log('Coordinates:', address.coordinates);
+} else {
+  console.log('No address set');
+}
+```
+
+### Use Cases
+
+#### Check if Address is Set
+
+```javascript
+if (!window.LiquidCommerce.elements.actions.address.getDetails()) {
+  // Prompt user to set address
+  showAddressPrompt();
+}
+```
+
+#### Display Current Address
+
+```javascript
+const address = window.LiquidCommerce.elements.actions.address.getDetails();
+
+if (address) {
+  document.getElementById('current-address').textContent = 
+    address.formattedAddress;
+}
+```
+## Events
+
+Address actions trigger events:
+
+```javascript
+// Address updated
+window.addEventListener('lce:actions.address_updated', (event) => {
+  const { googlePlacesId, address, coordinates, formattedAddress } = event.detail.data;
+  console.log('Address set:', formattedAddress);
+});
+
+// Address cleared
+window.addEventListener('lce:actions.address_cleared', () => {
+  console.log('Address cleared');
+});
+
+// Address failed
+window.addEventListener('lce:actions.address_failed', (event) => {
+  console.error('Address error:', event.detail.data.error);
+});
+```
+
+## Best Practices
+
+### Use Places ID When Available
+
+Google Places provides accurate geocoding:
+
+```javascript
+// Good - accurate and validated
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(placesId);
+
+// Less ideal - requires manual geocoding
+await window.LiquidCommerce.elements.actions.address.setAddressManually(address, coords);
+```
+
+### Validate Manual Addresses
+
+When using manual address entry:
+
+```javascript
+async function setManualAddress(address, coords) {
+  // Validate format
+  if (!address.one || !address.city || !address.state || !address.zip) {
+    throw new Error('Missing required fields');
+  }
+  
+  // Validate state
+  if (!/^[A-Z]{2}$/.test(address.state)) {
+    throw new Error('State must be 2-letter code');
+  }
+  
+  // Validate ZIP
+  if (!/^\d{5}(-\d{4})?$/.test(address.zip)) {
+    throw new Error('Invalid ZIP code');
+  }
+  
+  await window.LiquidCommerce.elements.actions.address.setAddressManually(address, coords);
+}
+```
+
+### Handle Errors
+
+```javascript
+try {
+  await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(placesId);
+  showSuccess('Address saved!');
+} catch (error) {
+  console.error('Failed to set address:', error);
+  showError('Unable to set that address. Please try again.');
+}
+```
+
+### Set Address Early
+
+Set address as soon as possible in user flow:
+
+```javascript
+window.addEventListener('lce:actions.client_ready', () => {
+  if (!window.LiquidCommerce.elements.actions.address.getDetails()) {
+    // Prompt for address on first visit
+    showAddressModal();
+  }
+}, { once: true });
+```
+
+## See Also
+
+- [Address Component Guide](../../guides/address-component.md)
+- [Address Events](../../guides/events.md#address-events)
+- [Product Component](../../guides/product-component.md#address-requirement)
+- [Cart Component](../../guides/cart-component.md#address-requirement)