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

package/docs/v1/guides/address-component.md

@@ -0,0 +1,441 @@
+# Address Component
+
+The Address component manages delivery location for availability checking and accurate pricing throughout the SDK.
+
+## Overview
+
+The Address component:
+- Provides location input via Google Places integration
+- Allows manual address entry
+- Stores location for cart/checkout
+- Enables location-based pricing
+- Determines product availability
+- Supports fulfillment type selection
+
+## How It Works
+
+The address component is **embedded in the product component by default**. Users set their address when viewing products, and this address is used throughout the cart and checkout flow.
+
+### Automatic Address Prompting
+
+When a user tries to add a product to cart without setting an address:
+
+1. Address input drawer opens automatically
+2. User enters their address
+3. Address is saved
+4. Add-to-cart action resumes automatically
+
+No additional code needed - this is handled automatically.
+
+## Standalone Usage
+
+Use the standalone address component when you need a dedicated address selection page:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', { env: 'production' });
+
+await client.injectAddressElement('address-container');
+
+// React to address selection by listening for the address_updated event
+window.addEventListener('lce:actions.address_updated', (event) => {
+  console.log('Address set:', event.detail.data);
+});
+```
+
+```html
+<div id="address-container"></div>
+```
+
+## Address Actions
+
+### Set Address via Google Places ID
+
+The recommended method - provides accurate geocoding:
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId('ChIJOwg_06VPwokRYv534QaPC8g');
+```
+
+If you run Google Places Autocomplete yourself with a [session token](https://developers.google.com/maps/documentation/places/web-service/session-tokens), pass the same token as the second argument. The details request then ends your session, and Google bills the autocomplete requests as one session instead of per request. Google only groups requests whose API keys belong to the same Google Cloud project, so this applies only when your autocomplete requests used the same project as LiquidCommerce's address service; a token from autocomplete requests made with an API key in another project doesn't change billing:
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(placesId, sessionToken);
+```
+
+**How to get a 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.
+
+### Set Address Manually
+
+For custom address flows without Google Places:
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.setAddressManually(
+  {
+    one: '123 Main Street',
+    two: 'Apt 4',         // Optional at runtime
+    city: 'New York',
+    state: 'NY',
+    zip: '10001',
+    country: 'US'
+  },
+  {
+    latitude: 40.7128,
+    longitude: -74.0060
+  }
+);
+```
+
+**Requirements:**
+- `one`: Street address (required)
+- `two`: Apartment, suite, etc. (optional)
+- `city`: City name (required)
+- `state`: Two-letter state code (required)
+- `zip`: ZIP/postal code (required)
+- `country`: Country code, e.g. `'US'` (required by the `IAddressAddress` type)
+- `latitude`: Number between -90 and 90 (required)
+- `longitude`: Number between -180 and 180 (required)
+
+### Get Address Details
+
+Retrieve the current address:
+
+```javascript
+const addressData = window.LiquidCommerce.elements.actions.address.getDetails();
+
+console.log(addressData);
+// {
+//   id: 'ChIJ...',
+//   address: {
+//     one: '123 Main Street',
+//     two: 'Apt 4',
+//     city: 'New York',
+//     state: 'NY',
+//     zip: '10001',
+//     country: 'US'
+//   },
+//   coordinates: {
+//     latitude: 40.7128,
+//     longitude: -74.0060
+//   },
+//   formattedAddress: '123 Main Street, Apt 4, New York, NY 10001'
+// }
+
+// Returns null if no address is set
+```
+
+### Clear Address
+
+Remove the current address:
+
+```javascript
+await window.LiquidCommerce.elements.actions.address.clear();
+```
+
+This will:
+- Clear stored address
+- Trigger address prompts on next cart action
+- Update all components that depend on location
+
+## Events
+
+### Address Updated
+
+Fired when a new address is set:
+
+```javascript
+window.addEventListener('lce:actions.address_updated', (event) => {
+  const { address, coordinates, formattedAddress } = event.detail.data;
+  
+  console.log('New address:', formattedAddress);
+  console.log('Coordinates:', coordinates);
+});
+```
+
+### Address Cleared
+
+Fired when address is removed:
+
+```javascript
+window.addEventListener('lce:actions.address_cleared', (event) => {
+  console.log('Address has been cleared');
+});
+```
+
+### Address Failed
+
+Fired when address setting fails:
+
+```javascript
+window.addEventListener('lce:actions.address_failed', (event) => {
+  const { error } = event.detail.data;
+  console.error('Address error:', error);
+});
+```
+
+## Customization
+
+### Theme Configuration
+
+Customize address component appearance:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    address: {
+      theme: {
+        backgroundColor: '#ffffff'
+      }
+    }
+  }
+});
+```
+
+## Use Cases
+
+### Dedicated Location Page
+
+Create a dedicated page for address selection:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Set Delivery Location</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+</head>
+<body>
+  <h1>Where should we deliver?</h1>
+  <div id="address"></div>
+  
+  <script>
+    window.addEventListener('lce:actions.client_ready', async () => {
+      await window.LiquidCommerce.elements.injectAddressElement('address');
+    }, { once: true });
+    
+    window.addEventListener('lce:actions.address_updated', () => {
+      // Redirect to product page after address is set
+      window.location.href = '/products';
+    });
+  </script>
+</body>
+</html>
+```
+
+### Custom Address Input with Validation
+
+```javascript
+document.getElementById('save-address-btn').addEventListener('click', async () => {
+  const address = {
+    one: document.getElementById('street').value,
+    two: document.getElementById('apt').value,
+    city: document.getElementById('city').value,
+    state: document.getElementById('state').value,
+    zip: document.getElementById('zip').value
+  };
+  
+  // Get coordinates from your geocoding service
+  const coords = await geocodeAddress(address);
+  
+  try {
+    await window.LiquidCommerce.elements.actions.address.setAddressManually(address, coords);
+    showSuccessMessage('Address saved!');
+  } catch (error) {
+    showErrorMessage('Invalid address');
+  }
+});
+```
+
+### Pre-fill Address from User Account
+
+```javascript
+// After user logs in, set their saved address
+window.addEventListener('lce:actions.client_ready', async () => {
+  if (userIsLoggedIn && !currentAddressSet) {
+    await window.LiquidCommerce.elements.actions.address.setAddressManually(
+      user.savedAddress,
+      user.savedCoordinates
+    );
+  }
+}, { once: true });
+```
+
+### Location-Based Product Filtering
+
+```javascript
+window.addEventListener('lce:actions.address_updated', async (event) => {
+  const { coordinates } = event.detail.data;
+  
+  // Fetch products available in this location
+  const availableProducts = await fetch('/api/products', {
+    method: 'POST',
+    body: JSON.stringify({ latitude: coordinates.latitude, longitude: coordinates.longitude })
+  }).then(r => r.json());
+  
+  // Update UI with available products
+  displayProducts(availableProducts);
+});
+```
+
+### Multi-Location Switcher
+
+```javascript
+const locations = [
+  { name: 'Home', placesId: 'ChIJ...' },
+  { name: 'Work', placesId: 'ChIJ...' },
+  { name: 'Mom\'s House', placesId: 'ChIJ...' }
+];
+
+document.getElementById('location-select').addEventListener('change', async (e) => {
+  const selectedLocation = locations[e.target.value];
+  
+  await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(
+    selectedLocation.placesId
+  );
+  
+  showNotification(`Switched to ${selectedLocation.name}`);
+});
+```
+
+## Address Persistence
+
+### Storage
+
+Addresses are stored in:
+- SDK internal store
+- LocalStorage (for persistence)
+- Session (until explicitly cleared)
+
+### Lifespan
+
+Addresses persist:
+- Across page refreshes
+- Across browser sessions
+- Until explicitly cleared by user or code
+
+### Privacy
+
+Addresses are:
+- Stored locally in the browser
+- Sent to LiquidCommerce servers for availability/product loading; the address id (with the cart id) may also be persisted server-side as a session fallback when localStorage is unavailable (and a delete request is sent when the address is cleared)
+- Cleared when user logs out (if you implement logout handling)
+
+## Best Practices
+
+### Request Early
+
+Set address as early as possible in the user flow:
+
+```javascript
+// On homepage or landing page
+window.addEventListener('lce:actions.client_ready', () => {
+  const currentAddress = window.LiquidCommerce.elements.actions.address.getDetails();
+  
+  if (!currentAddress) {
+    // Show address prompt
+    showAddressPrompt();
+  }
+}, { once: true });
+```
+
+### Provide Context
+
+Explain why you need the address:
+
+```html
+<div class="address-explainer">
+  <h2>Where should we deliver?</h2>
+  <p>We need your location to show available products and accurate pricing.</p>
+  <div id="address"></div>
+</div>
+```
+
+### Validate Manually Entered Addresses
+
+When using manual address entry, validate before setting:
+
+```javascript
+async function setAddress(address, coords) {
+  // Validate format
+  if (!address.one || !address.city || !address.state || !address.zip) {
+    throw new Error('Missing required address fields');
+  }
+  
+  // Validate state code
+  if (address.state.length !== 2) {
+    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');
+  }
+  
+  // Validate coordinates
+  if (coords.latitude < -90 || coords.latitude > 90) {
+    throw new Error('Invalid latitude');
+  }
+  
+  if (coords.longitude < -180 || coords.longitude > 180) {
+    throw new Error('Invalid longitude');
+  }
+  
+  // Set address
+  await window.LiquidCommerce.elements.actions.address.setAddressManually(address, coords);
+}
+```
+
+### Handle Errors Gracefully
+
+```javascript
+try {
+  await window.LiquidCommerce.elements.actions.address.setAddressByPlacesId(placesId);
+} catch (error) {
+  console.error('Failed to set address:', error);
+  
+  // Show user-friendly error
+  showError('Unable to set that address. Please try again or enter manually.');
+  
+  // Fall back to manual entry
+  showManualAddressForm();
+}
+```
+## Troubleshooting
+
+### Address Not Persisting
+
+1. Check localStorage is not disabled
+2. Verify no errors in console
+3. Ensure `clear()` is not being called unintentionally
+4. Check that address was set successfully (no errors thrown)
+
+### Products Not Updating After Address Change
+
+1. Products should automatically rerender when address changes
+2. Check console for errors
+3. Verify address was actually set (not just input changed)
+4. Try manually rerendering product components
+
+### Invalid Address Errors
+
+1. Ensure all required fields are provided
+2. Verify coordinates are within valid ranges
+3. Check state code is 2 letters
+4. Validate ZIP code format
+5. Use Places ID method for most accurate results
+
+## See Also
+
+- [Product Component](./product-component.md) - Uses address for availability
+- [Cart Component](./cart-component.md) - Requires address for adding items
+- [Actions API](../api/actions/address-actions.md) - Address actions reference
+- [Events](./events.md) - All available events