@liquidcommerce/elements-sdk 2.7.0 → 2.7.2

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://assets-elements.liquidcommerce.us/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.elements.actions.cart.openCart();
+```
+
+### Adding to Cart Programmatically
+
+```javascript
+await window.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,281 @@
+# 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.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. (optional)
+  city: string;   // City name
+  state: string;  // Two-letter state code
+  zip: string;    // ZIP/postal code
+}
+
+interface IAddressCoordinates {
+  latitude: number;   // -90 to 90
+  longitude: number;  // -180 to 180
+}
+```
+
+### Example
+
+```javascript
+await window.elements.actions.address.setAddressManually(
+  {
+    one: '123 Main Street',
+    two: 'Apt 4',
+    city: 'New York',
+    state: 'NY',
+    zip: '10001'
+  },
+  {
+    latitude: 40.7128,
+    longitude: -74.0060
+  }
+);
+```
+
+### Validation
+
+The SDK validates:
+- All required fields are present
+- State is 2-letter code
+- Latitude is between -90 and 90
+- Longitude is between -180 and 180
+
+### Errors
+
+**Throws `SDKError` if:**
+- Required fields are missing
+- Coordinates are out of range
+- Address format is invalid
+
+---
+
+## actions.address.clear()
+
+Remove the current address.
+
+### Signature
+
+```typescript
+clear(): Promise<void>
+```
+
+### Example
+
+```javascript
+await window.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 or generated ID
+  address: {
+    one: string;
+    two?: string;
+    city: string;
+    state: string;
+    zip: string;
+  };
+  coordinates: {
+    latitude: number;
+    longitude: number;
+  };
+  formattedAddress: string;
+}
+```
+
+Returns `null` if no address is set.
+
+### Example
+
+```javascript
+const address = window.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.elements.actions.address.getDetails()) {
+  // Prompt user to set address
+  showAddressPrompt();
+}
+```
+
+#### Display Current Address
+
+```javascript
+const address = window.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 { 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.elements.actions.address.setAddressByPlacesId(placesId);
+
+// Less ideal - requires manual geocoding
+await window.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.elements.actions.address.setAddressManually(address, coords);
+}
+```
+
+### Handle Errors
+
+```javascript
+try {
+  await window.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.elements.actions.address.getDetails()) {
+    // Prompt for address on first visit
+    showAddressModal();
+  }
+});
+```
+
+## 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)