# 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://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)