@liquidcommerce/elements-sdk 2.6.0-beta.13 → 2.6.0-beta.130

package/docs/v1/README.md

@@ -0,0 +1,214 @@
+# 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.*`
+- **[Analytics Actions](./api/actions/analytics-actions.md)** - `actions.analytics.*`
+
+### 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,290 @@
+# 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, sessionToken?: string): Promise<void>
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `placesId` | string | Yes | Google Places ID |
+| `sessionToken` | string | No | Google Places session token of the autocomplete requests that returned `placesId`. The details request ends that session, so Google bills the autocomplete requests as one session instead of per request. Applies only when the autocomplete requests used an API key in the same Google Cloud project as LiquidCommerce's address service. |
+
+### Example
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(
+  'ChIJOwg_06VPwokRYv534QaPC8g'
+);
+
+// With the session token your own Places Autocomplete requests used
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(placesId, sessionToken);
+```
+
+### 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)