@liquidcommerce/elements-sdk 2.6.0-beta.40 → 2.6.0-beta.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/README.md +79 -171
  2. package/dist/index.checkout.esm.js +6799 -6800
  3. package/dist/index.esm.js +11112 -11109
  4. package/dist/types/auto-initialize/shared-utils.d.ts +5 -0
  5. package/dist/types/core/pubsub/interfaces/checkout.interface.d.ts +1 -0
  6. package/docs/gitbook/actions.md +160 -0
  7. package/docs/gitbook/address.md +48 -0
  8. package/docs/gitbook/cart.md +65 -0
  9. package/docs/gitbook/checkout.md +131 -0
  10. package/docs/gitbook/events.md +137 -0
  11. package/docs/gitbook/overview.md +166 -0
  12. package/docs/gitbook/product.md +64 -0
  13. package/docs/gitbook/quick-start-guide.md +393 -0
  14. package/docs/v1/README.md +210 -0
  15. package/docs/v1/api/actions/address-actions.md +281 -0
  16. package/docs/v1/api/actions/cart-actions.md +337 -0
  17. package/docs/v1/api/actions/checkout-actions.md +387 -0
  18. package/docs/v1/api/actions/product-actions.md +115 -0
  19. package/docs/v1/api/client.md +482 -0
  20. package/docs/v1/api/configuration.md +1 -0
  21. package/docs/v1/api/injection-methods.md +247 -0
  22. package/docs/v1/api/typescript-types.md +1 -0
  23. package/docs/v1/api/ui-helpers.md +200 -0
  24. package/docs/v1/examples/advanced-patterns.md +96 -0
  25. package/docs/v1/examples/checkout-flow.md +91 -0
  26. package/docs/v1/examples/custom-theming.md +63 -0
  27. package/docs/v1/examples/multi-product-page.md +90 -0
  28. package/docs/v1/examples/simple-product-page.md +89 -0
  29. package/docs/v1/getting-started/concepts.md +507 -0
  30. package/docs/v1/getting-started/installation.md +328 -0
  31. package/docs/v1/getting-started/quick-start.md +405 -0
  32. package/docs/v1/guides/address-component.md +431 -0
  33. package/docs/v1/guides/best-practices.md +324 -0
  34. package/docs/v1/guides/cart-component.md +737 -0
  35. package/docs/v1/guides/checkout-component.md +672 -0
  36. package/docs/v1/guides/events.md +191 -0
  37. package/docs/v1/guides/product-component.md +686 -0
  38. package/docs/v1/guides/product-list-component.md +598 -0
  39. package/docs/v1/guides/theming.md +216 -0
  40. package/docs/v1/integration/angular.md +39 -0
  41. package/docs/v1/integration/laravel.md +41 -0
  42. package/docs/v1/integration/nextjs.md +60 -0
  43. package/docs/v1/integration/proxy-setup.md +89 -0
  44. package/docs/v1/integration/react.md +64 -0
  45. package/docs/v1/integration/vanilla-js.md +84 -0
  46. package/docs/v1/integration/vue.md +34 -0
  47. package/docs/v1/reference/browser-support.md +35 -0
  48. package/docs/v1/reference/error-handling.md +70 -0
  49. package/docs/v1/reference/performance.md +54 -0
  50. package/docs/v1/reference/troubleshooting.md +64 -0
  51. package/package.json +1 -1
  52. package/docs/actions.md +0 -320
  53. package/docs/address.md +0 -242
  54. package/docs/browser-support.md +0 -279
  55. package/docs/cart.md +0 -387
  56. package/docs/checkout.md +0 -420
  57. package/docs/configuration.md +0 -1017
  58. package/docs/events.md +0 -181
  59. package/docs/product-list.md +0 -311
  60. package/docs/product.md +0 -250
  61. package/docs/proxy.md +0 -228
  62. package/docs/theming.md +0 -682
  63. package/docs/troubleshooting.md +0 -793
package/README.md CHANGED
@@ -10,7 +10,7 @@ Elements SDK
10
10
  [![JavaScript](https://img.shields.io/badge/JavaScript-ES6+-F7DF1E?style=for-the-badge&logo=javascript&logoColor=black)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
11
11
  [![TypeScript](https://img.shields.io/badge/TypeScript-5+-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
12
12
  [![Zero Dependencies](https://img.shields.io/badge/Dependencies-Zero-brightgreen)](./package.json)
13
- [![Browser Support](https://img.shields.io/badge/Browsers-2018+-4285F4?logo=googlechrome&logoColor=white)](./docs/browser-support.md)
13
+ [![Browser Support](https://img.shields.io/badge/Browsers-2018+-4285F4?logo=googlechrome&logoColor=white)](./docs/v1/reference/browser-support.md)
14
14
 
15
15
  **Add product displays, shopping carts, and checkout flows to any website**
16
16
 
@@ -18,28 +18,38 @@ Elements SDK
18
18
 
19
19
  ---
20
20
 
21
- ## Installation
21
+ ## Overview
22
+
23
+ Elements SDK is a Web Components-based e-commerce SDK that lets you add product displays, a cart, and checkout to any site with minimal code. It’s framework-agnostic, fully themeable, and works via CDN or NPM.
24
+
25
+ ## What You Can Build
26
+
27
+ - Product pages with variants, fulfillment options, and add-to-cart
28
+ - Cart drawer with promo codes and totals
29
+ - Checkout drawer or hosted checkout page
30
+ - Multi-product grids and searchable lists
31
+ - Address capture for delivery availability and pricing
22
32
 
23
- ### CDN
33
+ ## Installation
24
34
 
25
- Add a single script tag to your page's `<head>` section:
35
+ ### CDN (Fastest)
26
36
 
27
37
  ```html
28
38
  <script
29
39
  defer
30
- type="text/javascript"
31
40
  data-liquid-commerce-elements
32
41
  data-token="YOUR_API_KEY"
33
42
  data-env="production"
43
+ data-container-1="product"
44
+ data-product-1="00619947000020"
45
+ type="text/javascript"
34
46
  src="https://assets-elements.liquidcommerce.us/all/elements.js"
35
47
  ></script>
36
- ```
37
48
 
38
- > **Tip:** While we recommend the `<head>` section, the script works anywhere on your page—place it wherever fits your setup best.
39
- >
40
- > **About `defer`:** The script is optimized to load without blocking your page content, keeping your site fast no matter where you place it.
49
+ <div id="product"></div>
50
+ ```
41
51
 
42
- ### NPM
52
+ ### NPM (Programmatic)
43
53
 
44
54
  ```bash
45
55
  npm install @liquidcommerce/elements-sdk
@@ -49,197 +59,95 @@ npm install @liquidcommerce/elements-sdk
49
59
  import { Elements } from '@liquidcommerce/elements-sdk';
50
60
 
51
61
  const client = await Elements('YOUR_API_KEY', { env: 'production' });
62
+ await client.injectProductElement([
63
+ { containerId: 'product', identifier: '00619947000020' }
64
+ ]);
52
65
  ```
53
66
 
54
- ---
55
-
56
- ## SDK Architecture
67
+ ## Core Concepts (Short)
57
68
 
58
- The SDK attaches to the window object, providing methods for injection, UI helpers, and actions:
59
-
60
- ```
61
- window.elements
62
- ├── injectProductElement(params[])
63
- ├── injectAddressElement(containerId, options?)
64
- ├── injectCartElement(containerId)
65
- ├── injectCheckoutElement(params)
66
- ├── injectProductList(params)
67
- ├── injectProductListSearch(params)
68
- ├── injectProductListFilters(params)
69
- ├── getInjectedComponents()
70
- │
71
- ├── ui
72
- │ ├── cartButton(containerId, showCount?)
73
- │ ├── floatingCartButton(showCount?)
74
- │ ├── cartSubtotal(elementId)
75
- │ └── cartItemsCount(elementId, options?)
76
- │
77
- └── actions
78
- ├── product
79
- │ └── getDetails(identifier)
80
- │
81
- ├── address
82
- │ ├── setAddressByPlacesId(placesId)
83
- │ ├── setAddressManually(address, coords)
84
- │ ├── getDetails()
85
- │ └── clear()
86
- │
87
- ├── cart
88
- │ ├── openCart()
89
- │ ├── closeCart()
90
- │ ├── toggleCart()
91
- │ ├── addProduct(items[], openCart?)
92
- │ ├── applyPromoCode(code)
93
- │ ├── removePromoCode()
94
- │ ├── resetCart()
95
- │ └── getDetails()
96
- │
97
- └── checkout
98
- ├── openCheckout()
99
- ├── closeCheckout()
100
- ├── toggleCheckout()
101
- ├── exitCheckout()
102
- ├── addProduct(items[], openCheckout?)
103
- ├── applyPromoCode(code)
104
- ├── removePromoCode()
105
- ├── applyGiftCard(code)
106
- ├── removeGiftCard(code)
107
- ├── toggleIsGift(active?)
108
- ├── toggleBillingSameAsShipping(active?)
109
- ├── toggleMarketingPreferences(field, active)
110
- ├── updateCustomerInfo(params)
111
- ├── updateBillingInfo(params)
112
- ├── updateGiftInfo(params)
113
- └── getDetails()
114
- ```
115
-
116
- ---
69
+ - **Web Components + Shadow DOM** for framework-agnostic UI and style isolation
70
+ - **Declarative setup** via HTML data attributes
71
+ - **Programmatic setup** via `Elements()` client for dynamic injection
72
+ - **Events** for analytics and custom UI
73
+ - **Actions API** for cart/checkout control
117
74
 
118
75
  ## Components
119
76
 
120
- ### [Product](docs/product.md)
121
- Display product details with variants, pricing, and add-to-cart functionality. Automatically adapts to customer's delivery location.
122
-
123
- ### [Address](docs/address.md)
124
- Manage delivery location for availability and pricing. Embedded in product by default - standalone injection only needed for dedicated address pages.
125
-
126
- ### [Cart](docs/cart.md)
127
- Shopping cart drawer with real-time updates, quantity controls, and promo codes. Syncs across tabs and persists between sessions.
128
-
129
- ### [Checkout](docs/checkout.md)
130
- Complete purchase flow with customer info, payment, and order confirmation. Available as drawer or hosted page.
77
+ - **Product**: Images, variants, fulfillment, add-to-cart
78
+ - **Cart**: Drawer with items, totals, promo codes
79
+ - **Checkout**: Drawer or hosted page with full purchase flow
80
+ - **Address**: Delivery location capture
81
+ - **Product List**: Filterable, searchable grids
131
82
 
132
- ### [Product List](docs/product-list.md)
133
- Filterable, searchable product catalog with infinite scroll. Perfect for category pages and search results.
83
+ ## Key Methods (High Level)
134
84
 
135
- ---
136
-
137
- ## Getting Started
138
-
139
- ### Declarative Setup (HTML Attributes)
140
-
141
- Add products with zero JavaScript using data attributes:
85
+ - `injectProductElement`, `injectCartElement`, `injectCheckoutElement`, `injectAddressElement`
86
+ - `ui.cartButton`, `ui.floatingCartButton`, `ui.cartSubtotal`, `ui.cartItemsCount`
87
+ - `actions.product`, `actions.cart`, `actions.checkout`, `actions.address`
142
88
 
143
- ```html
144
- <!-- Method 1: Direct attributes -->
145
- <div id="product-1"></div>
146
- <script
147
- defer
148
- type="text/javascript"
149
- data-liquid-commerce-elements
150
- data-token="YOUR_API_KEY"
151
- data-container-1="product-1"
152
- data-product-1="00619947000020"
153
- src="https://assets-elements.liquidcommerce.us/all/elements.js"
154
- ></script>
155
-
156
- <!-- Method 2: JSON configuration -->
157
- <script data-liquid-commerce-elements-products type="application/json">
158
- [{ "containerId": "product-1", "identifier": "00619947000020" }]
159
- </script>
160
-
161
- <!-- Method 3: Annotated elements -->
162
- <div data-lce-product="00619947000020"></div>
89
+ ```javascript
90
+ // Example: add a product and open cart
91
+ await window.elements.actions.cart.addProduct([
92
+ { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
93
+ ], true);
163
94
  ```
164
95
 
165
- See [Product documentation](docs/product.md) for all declarative options.
166
-
167
- ### Programmatic Setup (JavaScript API)
96
+ ## Events (High Level)
168
97
 
169
- Full control with the client instance:
98
+ Listen for SDK events to drive analytics or custom UI:
170
99
 
171
100
  ```javascript
172
- const client = await Elements('YOUR_API_KEY', { env: 'production' });
173
-
174
- // Inject products
175
- await client.injectProductElement([
176
- { containerId: 'pdp-1', identifier: '00619947000020' }
177
- ]);
101
+ window.addEventListener('lce:actions.product_loaded', (event) => {
102
+ console.log('Loaded:', event.detail.data.identifier);
103
+ });
178
104
 
179
- // Use actions
180
- client.actions.cart.openCart();
181
- await client.actions.cart.addProduct([
182
- { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
183
- ]);
105
+ window.addEventListener('lce:actions.checkout_submit_completed', (event) => {
106
+ console.log('Order:', event.detail.data.orderId);
107
+ });
184
108
  ```
185
109
 
186
- See component docs for complete programmatic APIs.
187
-
188
- ### TypeScript Support
110
+ ## Theming
189
111
 
190
- For TypeScript projects, import types directly from the package:
191
-
192
- ```typescript
193
- import { Elements } from '@liquidcommerce/elements-sdk';
194
- import type {
195
- ILiquidCommerceElementsClient,
196
- ILiquidCommerceElementsConfig,
197
- IInjectProductElement,
198
- IInjectCheckoutParams,
199
- IInjectedComponent,
200
- IAddProductParams
201
- } from '@liquidcommerce/elements-sdk';
202
-
203
- const config: ILiquidCommerceElementsConfig = {
112
+ ```javascript
113
+ const client = await Elements('YOUR_API_KEY', {
204
114
  env: 'production',
205
115
  customTheme: {
206
- global: { colors: { primary: '#007bff' } }
116
+ global: {
117
+ theme: {
118
+ primaryColor: '#007bff',
119
+ buttonCornerRadius: '8px'
120
+ }
121
+ }
207
122
  }
208
- };
209
-
210
- const client: ILiquidCommerceElementsClient = await Elements('YOUR_API_KEY', config);
123
+ });
211
124
  ```
212
125
 
213
- ---
214
-
215
- ## Documentation
126
+ ## Integrations
216
127
 
217
- ### Component Guides
218
- - [Product](docs/product.md) - Product display and add-to-cart
219
- - [Address](docs/address.md) - Delivery location management
220
- - [Cart](docs/cart.md) - Shopping cart functionality
221
- - [Checkout](docs/checkout.md) - Purchase flow
222
- - [Product List](docs/product-list.md) - Catalog browsing
128
+ Works with any framework. See:
223
129
 
224
- ### Reference
225
- - [Actions](docs/actions.md) - Programmatic control
226
- - [Events](docs/events.md) - Event system
227
- - [Theming](docs/theming.md) - Customization
130
+ - [React](./docs/v1/integration/react.md)
131
+ - [Next.js](./docs/v1/integration/nextjs.md)
132
+ - [Vue](./docs/v1/integration/vue.md)
133
+ - [Angular](./docs/v1/integration/angular.md)
134
+ - [Laravel](./docs/v1/integration/laravel.md)
135
+ - [Vanilla JS](./docs/v1/integration/vanilla-js.md)
136
+ - [Proxy Setup](./docs/v1/integration/proxy-setup.md)
228
137
 
229
- ### Technical
230
- - [Proxy Setup](docs/proxy.md) - Ad blocker avoidance
231
- - [Browser Support](docs/browser-support.md) - Compatibility
232
- - [Troubleshooting](docs/troubleshooting.md) - Common issues
138
+ ## Documentation (v1)
233
139
 
234
- ---
140
+ - [Start Here](./docs/v1/README.md)
141
+ - [Getting Started](./docs/v1/getting-started/installation.md)
142
+ - [Guides](./docs/v1/guides/)
143
+ - [API Reference](./docs/v1/api/)
144
+ - [Examples](./docs/v1/examples/)
145
+ - [Reference](./docs/v1/reference/)
235
146
 
236
147
  ## Browser Support
237
148
 
238
- Supports 2018+ browsers: Chrome 66+, Firefox 60+, Safari 12+, Edge 79+.
239
-
240
- See [Browser Support](docs/browser-support.md) for details.
241
-
242
- ---
149
+ Chrome 66+, Firefox 60+, Safari 12+, Edge 79+.
150
+ See [Browser Support](./docs/v1/reference/browser-support.md) for details.
243
151
 
244
152
  ## Support
245
153