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

package/docs/v1/getting-started/quick-start.md

@@ -0,0 +1,410 @@
+# Quick Start
+
+Get a product display with add-to-cart functionality working on your page in under 5 minutes.
+
+## What You'll Build
+
+A fully functional product page with:
+- Product images and details
+- Size selection
+- Fulfillment options (shipping/on-demand delivery)
+- Add to cart button
+- Shopping cart drawer
+- Complete checkout flow
+
+## Prerequisites
+
+- A LiquidCommerce API key (contact your LiquidCommerce representative)
+- A product identifier
+- A web page or HTML file
+
+## Step 1: Add the SDK Script
+
+Add the Elements SDK script tag to your HTML `<head>`:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Product Page</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>
+  <!-- We'll add the product here -->
+</body>
+</html>
+```
+
+**Replace `YOUR_API_KEY`** with your actual API key.
+
+## Step 2: Add a Product Container
+
+Create a container where the product will be displayed:
+
+```html
+<body>
+  <h1>Our Premium Whiskey</h1>
+  
+  <!-- Product will be injected here -->
+  <div id="product-display"></div>
+</body>
+```
+
+## Step 3: Configure the Product (Declarative)
+
+Add product configuration using HTML data attributes on the script tag:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-container-1="product-display"
+  data-product-1="00619947000020"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+```
+
+**New attributes:**
+- `data-container-1="product-display"` - Points to the container ID
+- `data-product-1="00619947000020"` - The product identifier
+
+The numbers (1) connect the container to its product. For multiple products, increment the number:
+- `data-container-2` with `data-product-2`
+- `data-container-3` with `data-product-3`
+- etc.
+
+## Complete Example
+
+Here's the complete HTML for a working product page:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Premium Whiskey - Buy Online</title>
+  
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    data-container-1="product-display"
+    data-product-1="00619947000020"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+  
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+    h1 {
+      text-align: center;
+    }
+  </style>
+</head>
+<body>
+  <h1>Our Premium Whiskey</h1>
+  <div id="product-display"></div>
+</body>
+</html>
+```
+
+That's it! Save the file and open it in a browser. You should see:
+1. Product images in a carousel
+2. Product name and description
+3. Size selector
+4. Fulfillment type selector (shipping/delivery)
+5. Retailer selection
+6. Add to cart button
+
+When you click "Add to Cart," a cart drawer slides in from the right with checkout functionality.
+
+## Alternative: Programmatic Setup
+
+If you prefer JavaScript over HTML attributes:
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Product Page</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>
+  
+  <script defer>
+    // Wait for SDK to be ready
+    window.addEventListener('lce:actions.client_ready', async (event) => {
+      const client = window.LiquidCommerce.elements;
+      
+      // Inject the product
+      await client.injectProductElement([
+        {
+          containerId: 'product-display',
+          identifier: '00619947000020'
+        }
+      ]);
+    }, { once: true });
+  </script>
+</head>
+<body>
+  <h1>Our Premium Whiskey</h1>
+  <div id="product-display"></div>
+</body>
+</html>
+```
+
+Or with NPM:
+
+```javascript
+import { Elements } from '@liquidcommerce/elements-sdk';
+
+async function initProduct() {
+  // Elements() resolves to `null` if initialization fails — it never throws.
+  const client = await Elements('YOUR_API_KEY', {
+    env: 'production'
+  });
+
+  if (!client) {
+    return;
+  }
+
+  await client.injectProductElement([
+    {
+      containerId: 'product-display',
+      identifier: '00619947000020'
+    }
+  ]);
+}
+
+initProduct();
+```
+
+## Multiple Products
+
+To display multiple products on one page:
+
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  
+  data-container-1="product-1"
+  data-product-1="00619947000020"
+  data-container-2="product-2"
+  data-product-2="08504405135"
+  data-container-3="product-3"
+  data-product-3="08068660001"
+  
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+
+<div id="product-1"></div>
+<div id="product-2"></div>
+<div id="product-3"></div>
+```
+
+Or programmatically:
+
+```javascript
+await client.injectProductElement([
+  { containerId: 'product-1', identifier: '00619947000020' },
+  { containerId: 'product-2', identifier: '08504405135' },
+  { containerId: 'product-3', identifier: '08068660001' }
+]);
+```
+
+## What Happens Automatically
+
+The SDK handles everything for you:
+
+1. **Address Collection** - If needed, prompts for delivery location
+2. **Availability Check** - Shows only available fulfillment options
+3. **Cart Management** - Maintains cart across page refreshes and tabs
+4. **Checkout Flow** - Complete payment and order processing
+5. **Error Handling** - Graceful error messages and recovery
+6. **Mobile Responsiveness** - Works on all screen sizes
+
+## Customization
+
+Want to customize the look, visit the Elements Builder in our [Partner Portal](https://app.liquidcommerce.co/)? Want to manually override your theme, you can pass a `customTheme: IClientCustomThemeConfig` configuration:
+
+```html
+<script>
+window.addEventListener('lce:actions.client_ready', async () => {
+  const client = window.LiquidCommerce.elements;
+  
+  // You can customize after initialization
+  // See Theming Guide for more options
+}, { once: true });
+</script>
+```
+
+Or with NPM:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff',
+        buttonCornerRadius: '8px',
+        headingFont: {
+          name: 'Poppins',
+          weights: [400, 600]
+        }
+      }
+    }
+  }
+});
+```
+
+## Testing Different Products
+
+To test with different products, simply change the product identifier:
+
+```html
+<!-- Replace with your product UPC -->
+data-product-1="YOUR_PRODUCT_IDENTIFIER"
+```
+
+Contact your LiquidCommerce representative for available product identifiers.
+
+## Troubleshooting
+
+### Product Not Showing
+
+1. **Check the browser console** for errors
+2. **Verify your API key** is correct
+3. **Confirm the product identifier** exists in your catalog
+4. **Check the container ID** matches your HTML
+
+### Styling Issues
+
+The product uses Shadow DOM for style encapsulation. To customize:
+
+- Use the `customTheme` configuration option
+- See [Theming Guide](../guides/theming.md) for detailed customization
+
+### Cart Not Opening
+
+The cart should open automatically after adding a product. If it doesn't:
+
+1. Check browser console for JavaScript errors
+2. Verify no other scripts are conflicting
+3. Try manually opening: `window.LiquidCommerce.elements.actions.cart.openCart()`
+
+## Next Steps
+
+Now that you have a basic product working:
+
+- **[Core Concepts](./concepts.md)** - Understand how the SDK works
+- **[Product Component Guide](../guides/product-component.md)** - Deep dive into product features
+- **[Cart Component Guide](../guides/cart-component.md)** - Learn about cart functionality
+- **[Checkout Component Guide](../guides/checkout-component.md)** - Customize the checkout experience
+- **[Theming Guide](../guides/theming.md)** - Make it match your brand
+- **[Events](../guides/events.md)** - React to user actions
+- **[API Reference](../api/client.md)** - Explore all available methods
+
+## Complete Working Example
+
+Try this complete example with your API key:
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Whiskey Shop</title>
+  
+  <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>
+  
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif;
+      background: #f5f5f5;
+    }
+    
+    header {
+      background: white;
+      padding: 20px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      margin-bottom: 40px;
+    }
+    
+    .container {
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 0 20px;
+    }
+    
+    h1 {
+      text-align: center;
+      color: #333;
+    }
+    
+    #product {
+      background: white;
+      border-radius: 8px;
+      padding: 20px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="container">
+      <h1>🥃 Premium Spirits Collection</h1>
+    </div>
+  </header>
+  
+  <div class="container">
+    <div id="product"></div>
+  </div>
+</body>
+</html>
+```
+
+Replace `YOUR_API_KEY` with your actual key and you're ready to go!