npm - @liquidcommerce/elements-sdk - Versions diffs - 2.7.24 → 2.7.26 - Mend

@liquidcommerce/elements-sdk 2.7.24 → 2.7.26

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 (91) hide show

package/docs/v1/guides/accessibility.md ADDED Viewed

@@ -0,0 +1,190 @@
+# Accessibility Guide
+What the Elements SDK does for accessibility, what it needs from your page, and how to verify it.
+## Overview
+Elements target **WCAG 2.1 Level AA**. Every element ships with keyboard support, screen-reader
+announcements, managed focus and enforced colour contrast — there is nothing to switch on.
+Accessibility is shared between the SDK and the host page:
+| The SDK owns | Your page owns |
+|---|---|
+| Roles, names and states of everything inside an element | Page structure: landmarks, heading order, `<html lang>` |
+| Keyboard operation of every control it renders | Contrast of your own content, and the surface you place elements on |
+| Focus movement into and out of its overlays | A theme whose colours are legible (the SDK corrects what it can, and logs when it does) |
+| Announcing its own content changes | Not hiding or `inert`-ing the element container |
+| Reflow down to a 320px viewport | Layout around the element at 400% zoom |
+## Keyboard navigation
+Every control is reachable and operable with a keyboard alone. Related controls are grouped into
+a **single tab stop** with arrow keys inside it, so a long list of retailers or sizes is not a
+tab-through slog.
+| Widget | Keys |
+|---|---|
+| Size selector (product) | `Tab` to the group, `←` `→` to move, `Enter` / `Space` to choose, `Home` / `End` for the ends |
+| Size dropdown (product list) | `Enter` / `Space` / `↓` opens, `↑` `↓` moves, `Enter` chooses, `Esc` closes |
+| Delivery method tabs (Shipping / Same-Day) | `←` `→` switches method immediately; unavailable methods are skipped |
+| Retailer / delivery-option lists | `↑` `↓` moves, `Enter` / `Space` chooses, `Home` / `End` for the ends |
+| Retailer carousel | `←` `→` moves, `Enter` / `Space` chooses |
+| Product image thumbnails | `←` `→` moves, `Enter` / `Space` shows the image |
+| Quantity steppers | `Tab` to each button, `Enter` / `Space` to step |
+| Address field | Type to search, `↑` `↓` through suggestions, `Enter` selects, `Esc` dismisses |
+| Cart / checkout drawer, modals | `Tab` cycles inside the panel only, `Esc` closes |
+Arrow keys change the selection immediately only where that is cheap and reversible (the delivery
+method tabs). Where choosing has a side effect the user cannot navigate back out of — picking a
+retailer closes the panel — arrow keys move focus and `Enter` commits.
+### Focus management
+- **Opening an overlay** moves focus into it and remembers the control that opened it.
+- **Closing** returns focus to that control, even when a re-render has replaced it.
+- **While an overlay is open** focus is trapped inside it and the rest of the page is `inert` and
+  `aria-hidden`, so a screen reader cannot wander behind the dialog.
+- **In-place content swaps** (Buy Now → address form, Add to Cart → personalize) re-seat focus on
+  the new view's heading; nothing is left focused on a destroyed node.
+- **After a re-render** focus returns to the control that caused it — the quantity stepper you
+  pressed, the delivery-method tab you switched to.
+- **Nothing hidden is focusable.** Collapsed panels are removed from the tab order and the
+  accessibility tree, and closed overlays have their content torn down.
+### Focus indicator
+A 2px ring in `--focus-ring-color`, offset 2px from the control. Controls that span their
+container's full width use an inset ring instead, because an outward ring on those is clipped by
+the scrolling panel around them. On primary-coloured fills the ring switches to
+`--selected-text-color`, which is guaranteed legible against that fill.
+The ring targets `:focus` as well as `:focus-visible`, so browsers without `:focus-visible`
+support still show it.
+## Screen reader support
+Elements are Web Components inside a shadow root, which is fully visible to assistive technology.
+### Announcements
+Content that appears or changes without navigation is announced through a shared live region
+(`role="status"`, `aria-live="polite"`; `role="alert"` for errors) that lives at the end of
+`document.body` and survives re-renders.
+| What happened | What is announced |
+|---|---|
+| Buy Now pressed | "Enter delivery address" |
+| Address saved | "Delivery address updated. Now delivering to …" |
+| Delivery option chosen | "Delivery option updated. Shipping from …, $…" |
+| Delivery method switched | "Shipping selected. 5 options available." |
+| Size chosen | "Size 750 ML selected" |
+| Quantity stepped | "Tito's Handmade Vodka, quantity 4" |
+| Personalization saved / removed | "Personalization saved" / "Personalization removed" |
+| Cart or checkout opened / closed | "Shopping cart opened" / "Shopping cart closed" |
+| Panel closed (product) | "Closed. Back to product options." |
+| Item added / removed, promo applied, totals changed | The new state, e.g. "Promo code SPRING applied, $5.00 off" |
+| Product list filtered or searched | "12 products found, showing 12" |
+| Validation failed | The field name and the error, interrupting (assertive) |
+| Carousel image changed | "Image 2 of 4" |
+Live regions are never written into a component template: components replace their whole subtree
+on render, and a live region recreated with its text already in place is not announced. Use
+`this.announcer.announce(message)` from a component instead.
+### Names, roles and states
+- Dialogs carry `role="dialog"`, an accessible name, and `aria-modal` when they cover the page.
+- Single-select groups are `listbox` / `radiogroup` with `option` / `radio` children carrying
+  `aria-selected` / `aria-checked` — not toggle buttons with `aria-pressed`, which would describe
+  each choice as an independent on/off switch.
+- Unavailable controls are `aria-disabled` **and** genuinely inert: they cannot be activated.
+- Icon-only buttons take their name from the button's `aria-label`.
+- Visible label text is always contained in the accessible name (2.5.3 Label in Name), so speech
+  input works: saying "click See Delivery Options" activates the button that reads that way.
+- Fields whose design has no room for a visible label (promo code, gift card) get an
+  `aria-label` instead — no rendered label, no layout change.
+### Images and icons
+- Product photos use the product name as their alt text; a photo painted as a CSS background is
+  exposed with `role="img"` and the same name.
+- Decorative images inside a named control use `alt=""` so the control is not announced twice.
+- Every inline SVG icon renders `aria-hidden="true" focusable="false"`. Icons that carry meaning
+  on their own opt in to a name: `CloseIcon({ label: 'Close' })`.
+## Colour and contrast
+Element colours come from your theme, and a brand palette chosen to look right often does not
+clear WCAG: white on a mid-tone brand fill is around 3:1, well under the 4.5:1 body text needs.
+The SDK therefore **measures your theme at runtime and corrects the foreground when it fails**:
+1. The surface each element renders on is resolved — a themed token for overlays, otherwise the
+   real background behind the element, measured from your page.
+2. Each foreground token is checked against that surface: text, links, warning/error/success,
+   input borders and the focus ring, plus on-primary text against `primaryColor`.
+3. Failing tokens are shifted in lightness — same hue, same saturation, away from the background
+   — until they pass 4.5:1 (text) or 3:1 (borders, focus ring).
+4. Backgrounds, fills and brand colours are never changed. Compliant themes are untouched.
+Corrections are applied as inline custom properties on the element host and logged:
+```
+Theme colour adjusted for accessibility: defaultTextColor was #FFFFFF (3.02:1 against #E7751E),
+which is below the required 4.5:1. Using #2B2B2B (4.69:1) instead. Set a compliant colour in
+your theme to control this yourself.
+```
+**To keep full control of your palette, supply colours that already pass.** Two tokens exist for
+exactly that and are worth setting explicitly:
+```javascript
+customTheme: {
+  global: {
+    theme: {
+      inputBorderColor: '#767C85', // form field boundaries, needs 3:1 on your surface
+      focusRingColor: '#1D4ED8'    // keyboard focus ring, needs 3:1 on your surface
+    }
+  }
+}
+```
+The SDK cannot see through a background image: if an element sits on one, surface-relative
+corrections are skipped rather than guessed, and the contrast of that text is yours to get right.
+### Zoom, reflow and text spacing
+Elements reflow down to a 320px CSS viewport (400% zoom on a 1280px screen) without horizontal
+scrolling. Labels wrap instead of truncating, so they survive user text-spacing overrides.
+## Verifying it
+**Keyboard:** unplug the mouse and complete a purchase. Every control must be reachable, every
+focus ring visible, and focus must never land on `<body>`.
+**Announcements** without a screen reader — the live regions are plain DOM:
+```javascript
+for (const region of document.querySelectorAll('[data-lce-live-region]')) {
+  new MutationObserver(() => console.log('[SR]', region.textContent)).observe(region, {
+    childList: true, subtree: true, characterData: true,
+  });
+}
+```
+**Contrast corrections** — inspect the element host:
+```javascript
+document.querySelector('lce-element[product]').getAttribute('style');
+// "--default-text-color: #2b2b2b; --focus-ring-color: #163ca7; …"
+```
+**Screen readers:** verify with VoiceOver (Safari/macOS), NVDA (Firefox/Windows) or TalkBack
+(Chrome/Android) — the pairings that matter most for a storefront.
+## See Also
+- [Theming Guide](./theming.md) — the tokens the contrast guard reads
+- [Best Practices](./best-practices.md)
+- [Browser Support](../reference/browser-support.md)

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

@@ -214,7 +214,7 @@ Create a dedicated page for address selection:
   <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
@@ -260,7 +260,7 @@ window.addEventListener('lce:actions.client_ready', async () => {
       user.savedCoordinates
     );
   }
-});
+}, { once: true });
 ```
 ### Location-Based Product Filtering
@@ -338,7 +338,7 @@ window.addEventListener('lce:actions.client_ready', () => {
     // Show address prompt
     showAddressPrompt();
   }
-});
+}, { once: true });
 ```
 ### Provide Context

package/docs/v1/guides/best-practices.md CHANGED Viewed

@@ -41,7 +41,7 @@ if (window.LiquidCommerce.elements) {
   // Wait for initialization
   window.addEventListener('lce:actions.client_ready', () => {
     window.LiquidCommerce.elements.actions.cart.openCart();
-  });
+  }, { once: true });
 }
 ```

package/docs/v1/guides/cart-component.md CHANGED Viewed

@@ -6,6 +6,7 @@ The Cart component provides a slide-out drawer for managing shopping cart items,
 The Cart component automatically:
 - Displays cart items with images and details
+- Removes white / near-white backgrounds from item images so products blend into the drawer (automatic, not host-configurable)
 - Groups items by retailer
 - Shows real-time pricing and totals
 - Supports quantity updates
@@ -240,7 +241,7 @@ Show cart subtotal anywhere on your page:
 <script>
 window.addEventListener('lce:actions.client_ready', () => {
   window.LiquidCommerce.elements.ui.cartSubtotal('cart-total');
-});
+}, { once: true });
 </script>
 ```
@@ -260,7 +261,7 @@ window.addEventListener('lce:actions.client_ready', () => {
   window.LiquidCommerce.elements.ui.cartItemsCount('items-count', {
     hideZero: true  // Hide when cart is empty
   });
-});
+}, { once: true });
 </script>
 ```
@@ -342,6 +343,17 @@ window.addEventListener('lce:actions.cart_item_quantity_decrease', (event) => {
 });
 ```
+### Engraving Updated
+Fired when a cart line item's engraving is added or edited from the drawer (see [Engraving](#engraving)):
+```javascript
+window.addEventListener('lce:actions.cart_item_engraving_updated', (event) => {
+  const { cartId, itemId, engravingLines, previousEngravingLines } = event.detail.data;
+  console.log(`Engraving updated for ${itemId}:`, engravingLines);
+});
+```
 ### Promo Code Events
 ```javascript
@@ -546,6 +558,26 @@ Items are automatically grouped by retailer in the cart:
 └─────────────────────────────────────┘
 ```
+## Order Minimums
+Retailers can require a minimum purchase amount before their items can be checked out. The cart enforces this per retailer:
+- When a retailer's minimum is not met, the cart drawer shows a per-retailer alert reading `+$X needed for order minimum`, where `$X` is the remaining amount required for that retailer.
+- The **Checkout** button is disabled until every retailer's minimum is met. (It is also disabled while the cart is loading/updating or when the cart is empty.)
+No configuration is required — the minimums are defined by each retailer and enforced automatically.
+## Engraving
+For engravable items, shoppers can add or edit engraving directly from a cart line item, without leaving the drawer.
+- If an engravable item has no engraving yet, the line item shows an **Add personalization** action (with the engraving fee) that opens the engraving form.
+- If the item already has engraving, its engraving is shown on the line item with an **Edit** button that reopens the form.
+The form respects the item's engraving constraints — `maxLines`, `maxCharsPerLine`, and the per-item `fee`. Saving emits [`lce:actions.cart_item_engraving_updated`](#engraving-updated) with the item's `engravingLines` and `previousEngravingLines`.
+**Note:** This in-drawer editing is distinct from the `engravingLines` array passed to [`addProduct`](#add-product-to-cart), which pre-fills engraving at the time an item is added.
 ## Checkout Navigation
 ### Checkout Drawer (Default)
@@ -647,7 +679,7 @@ Pre-load cart on page load for faster access:
 window.addEventListener('lce:actions.client_ready', () => {
   // Cart loads automatically, but you can pre-fetch if needed
   window.LiquidCommerce.elements.actions.cart.getDetails();
-});
+}, { once: true });
 ```
 ### Provide Visual Feedback

package/docs/v1/guides/events.md CHANGED Viewed

@@ -16,12 +16,18 @@ window.addEventListener('lce:actions.client_ready', (event) => {
     originalEvent,
     actionNamespace,
     eventId,
-    timestamp
+    timestamp,
+    sdkVersion,
+    env,
+    tenantName,
+    tenantCode
   } = metadata;
-});
+}, { once: true });
 ```
-`data` is event-specific. `metadata` describes the event (name, namespace, timestamp, etc).
+`data` is event-specific. `metadata` carries the same ten fields on **every** event — including
+`sdkVersion`, `env`, `tenantName` and `tenantCode`, so partner/tenant identification is already
+present and does not need to be re-derived in your analytics layer.
 ## Event Namespaces
@@ -43,7 +49,14 @@ window.addEventListener('lce:actions', (event) => {
 ### `lce:actions.client_ready`
-Fires once when the SDK finishes initializing and is ready for actions.
+Fires when the SDK finishes initializing and is ready for actions.
+> **Always register this listener with `{ once: true }`.** The specific topic
+> `lce:actions.client_ready` is dispatched **twice** — once synchronously, and once again on a
+> microtask, so that listeners attached immediately after `await Elements(...)` resolves still catch
+> it. Without `{ once: true }`, a handler registered before initialization runs **twice**, which
+> double-injects components and double-counts analytics. (The namespace-level `lce:actions` listener
+> receives it only once.)
 **Data includes:** `isReady`, `message`, `timestamp`, `version`.
@@ -55,7 +68,7 @@ window.addEventListener('lce:actions.client_ready', (event) => {
   if (data.isReady) {
     console.log('Elements SDK ready', data.version);
   }
-});
+}, { once: true });
 ```
 ## Product Events

package/docs/v1/guides/product-component.md CHANGED Viewed

@@ -148,6 +148,8 @@ Products with multiple images display in an interactive carousel:
 - Thumbnail preview
 - Lazy loading for performance
+**Background removal:** Product images (the main detail image and the gallery) automatically have their white/near-white background removed so photos blend into the surrounding page background instead of sitting on a white box. The SDK picks the technique per image based on the host background — blending the white away on light backgrounds, or keying it out to true transparency on dark or transparent backgrounds — and skips SVG artwork, which is already transparent. This is applied automatically and is not currently host-configurable.
 ### Size Selection
 For products with multiple sizes:
@@ -206,8 +208,8 @@ For products with multiple retailers:
 **Popup View**
 - "See Delivery Options" button (shows the available fulfillment count, e.g. "See Delivery Options (3)")
-- Modal with full retailer list
-- Filter and search capabilities
+- Opens a plain, scrollable list of the available delivery/retailer options
+- No filtering or search — select a retailer from the list to choose it
 ### Personalization/Engraving
@@ -366,6 +368,7 @@ const client = await Elements('YOUR_API_KEY', {
         showOnlyMainImage: false,  // Show all images or just the main one
         showTitle: true,
         showDescription: true,
+        descriptionPosition: 'below',  // Description placement: 'above' or 'below'
         showQuantityCounter: true,
         showOffHours: true,  // Show when retailer is closed
         quantityCounterStyle: 'outlined',  // or 'ghost'
@@ -376,6 +379,7 @@ const client = await Elements('YOUR_API_KEY', {
         addToCartButtonShowTotalPrice: true,
         buyNowButtonText: 'Buy Now',
         preSaleButtonText: 'Pre-Order',
+        prioritizeEngraving: false,  // Show engraving option before add-to-cart
         noAvailabilityText: 'Not available in your area'
       }
     }

package/docs/v1/guides/product-list-component.md CHANGED Viewed

@@ -260,18 +260,19 @@ Each product card shows:
 - Product name
 - Brand
 - Price (or price range for multiple sizes)
-- Rating (if available)
 - Clickable image/card linking to the product detail page (when `productUrl` is configured)
 - "Add to Cart" button (optional)
 - Availability indicator
+Product card images automatically have their white/near-white backgrounds removed so the product blends into the surrounding card and page background. This treatment is applied at render time and is not host-configurable.
 ### Card Interaction
 **Click on card:** Navigate to product detail page (if `productUrl` configured — see [Product URL Map](#product-url-map) for partner-owned PDP URLs that aren't derivable from a token).
 **Quick Add:** Add product to cart directly from list view (if enabled)
-**Click on image:** Open image in lightbox or navigate to product page
+**Click on image:** Navigate to the configured `productUrl` (only when `productUrl` is set — otherwise the image is not a link)
 ## Customization
@@ -514,10 +515,8 @@ The product list component includes:
 ### Optimization Features
 - **Image lazy loading**: Images load as they enter viewport
-- **Virtual scrolling**: Only renders visible products
+- **Progressive loading**: Products load in batches via an `IntersectionObserver` sentinel as you scroll — each page is appended to the grid and loaded cards remain in the DOM
 - **Debounced search**: Reduces API calls during typing
-- **Filter caching**: Caches filter results
-- **Progressive loading**: Loads in batches
 ### Large Catalogs

package/docs/v1/guides/theming.md CHANGED Viewed

@@ -27,7 +27,12 @@ const client = await Elements('YOUR_API_KEY', {
         errorColor: '#dc3545',
         warningColor: '#ffc107',
         successColor: '#28a745',
-        drawerBackgroundColor: '#ffffff'
+        drawerBackgroundColor: '#ffffff',
+        // Optional. Omit either one and the runtime contrast guard picks a
+        // WCAG-compliant value for you; set them to keep these details on-brand.
+        inputBorderColor: '#d4d4d8',
+        focusRingColor: '#007bff'
       }
     }
   }
@@ -53,6 +58,12 @@ customTheme: {
 }
 ```
+**Constraints:**
+- Only Google Fonts are supported. Each font's `name` must be a valid Google Font name (for example, `'Poppins'` or `'Inter'`).
+- `Poppins` is always loaded as the default font regardless of your configuration, so it remains available even if you do not specify it.
+- Font loading requires network access to `fonts.googleapis.com` and `fonts.gstatic.com`. If your environment enforces a Content Security Policy or routes traffic through a proxy, allow these hosts so fonts can load.
 ### Border Radius
 ```javascript
@@ -77,12 +88,16 @@ customTheme: {
       personalizationCardStyle: 'outlined',  // or 'filled'
       allowPromoCodes: true,
       inputFieldStyle: 'outlined',  // or 'filled'
+      enableOrderedProductSizes: true,  // enable custom ordering of the size selectors
+      orderedProductSizes: ['750ml', '1L', '1.75L'],  // order applied to product and product-list size selectors
       poweredByMode: 'light'  // or 'dark'  (note: showPoweredBy is controlled server-side and cannot be overridden via customTheme)
     }
   }
 }
 ```
+`enableOrderedProductSizes` and `orderedProductSizes` control the ordering of the size selectors rendered by the product and product-list components. When `enableOrderedProductSizes` is `true`, size options are sorted to match the sequence in the `orderedProductSizes` string array. Updating either key triggers a targeted rerender of the affected size selectors.
 ## Component Themes
 ### Product Component

package/docs/v1/integration/vanilla-js.md CHANGED Viewed

@@ -55,7 +55,7 @@ window.addEventListener('lce:actions.client_ready', async () => {
   await client.injectProductElement([
     { containerId: 'product', identifier: '00619947000020' }
   ]);
-});
+}, { once: true });
 </script>
 <div id="product"></div>

package/docs/v1/reference/analytics.md ADDED Viewed

@@ -0,0 +1,108 @@
+# Analytics & Google Tag Manager
+The SDK ships with a built-in Google Tag Manager (GTM) / Google Analytics 4 (GA4) integration. It automatically pushes GA4 ecommerce events for the interactions your shoppers perform in Elements components — product views, cart changes, checkout steps, purchases, and more.
+This runs entirely inside the SDK. In most cases you do not need to configure or code anything.
+## What You Need To Do
+**Typically nothing.** The integration is automatic in production and staging. The SDK receives its GTM container configuration from the LiquidCommerce platform (per partner) and initializes itself after the DOM is ready.
+It coexists with a host site's own GTM — see [Coexisting With Your Own GTM](#coexisting-with-your-own-gtm) below.
+## Supported Environments
+GTM initialization and every event push are enabled in production and staging. When the SDK is running in development or Builder mode, no container is loaded and no events are sent.
+Events are suppressed when any of the following is true:
+- `window` is undefined (server-side rendering).
+- The SDK is running in Builder mode.
+- The environment is `development`.
+The environment defaults to `production` when none is provided, so a standard production embed is analytics-enabled out of the box; a staging embed is also analytics-enabled when server GTM config is enabled for the partner.
+## How It Works
+### Container injection
+When enabled, the SDK injects the GTM container script:
+```
+https://www.googletagmanager.com/gtm.js?id=<containerId>
+```
+The script is appended to `<head>` with `async` and `crossorigin="anonymous"`, and the SDK waits for GTM to initialize before flushing events.
+### dataLayer and gtag
+The SDK initializes the standard GTM globals **without clobbering an existing setup**:
+- `window.dataLayer` is created only if it does not already exist.
+- `window.gtag` is defined only if it is not already present.
+Events are delivered using Google's recommended `window.dataLayer.push()` pattern.
+### Event queueing
+Events fired before GTM finishes initializing are queued (up to 100, oldest dropped first) and flushed once the container is ready. Queued events older than 30 seconds at flush time are discarded.
+## Coexisting With Your Own GTM
+The SDK detects an already-present partner/host GTM container rather than replacing it. When a host GTM install (an existing `gtag` function or an existing `googletagmanager.com/gtm.js` script tag) is detected, the SDK integrates with it.
+When both the LiquidCommerce container and a partner container are initialized, events are sent to both using GA4's `send_to` targeting (a dual-container send). Only containers that are actually initialized are added to `send_to`, so events are never routed to a container that failed to load.
+If the LiquidCommerce container can't be loaded, the SDK falls back — in order — to the partner container, any initialized GTM container on the page, or the basic `dataLayer` — so event tracking degrades gracefully instead of failing.
+## Source Tracking (`tenant_*`)
+Every event automatically carries source-tracking fields identifying the tenant and the SDK build:
+| Field | Value |
+| --- | --- |
+| `tenant_name` | Partner name |
+| `tenant_code` | Partner code |
+| `tenant_env` | SDK environment |
+| `tenant_source` | SDK package description and version |
+## Events
+All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `value`, `currency` — the SDK uses `USD`, `coupon`, etc.).
+### Standard GA4 ecommerce events
+| Event | Fired when |
+| --- | --- |
+| `view_item` | A shopper views a product |
+| `view_item_list` | A shopper views a list of products |
+| `select_item` | A shopper selects a product from a list |
+| `add_to_cart` | A shopper adds an item to the cart |
+| `view_cart` | A shopper views the cart |
+| `remove_from_cart` | A shopper removes an item from the cart |
+| `begin_checkout` | A shopper begins checkout |
+| `add_shipping_info` | Shipping info is added during checkout |
+| `add_payment_info` | Payment info is added during checkout |
+| `purchase` | A purchase completes |
+### Custom events
+| Event | Fired when |
+| --- | --- |
+| `promo_code_attempt` | A promo code is submitted |
+| `promo_code_applied` | A promo code is successfully applied |
+| `promo_code_failed` | A promo code fails to apply |
+| `gift_card_attempt` | A gift card is submitted |
+| `gift_card_applied` | A gift card is successfully applied |
+| `gift_card_failed` | A gift card fails to apply |
+| `address_updated` | An address is successfully updated |
+| `address_failed` | An address operation fails |
+| `product_no_availability` | A product has no availability for any size/fulfillment |
+| `product_size_no_availability` | A selected size has no availability |
+| `product_fulfillment_no_availability` | A selected fulfillment type has no availability |
+## Related Docs
+- [Events Guide](../guides/events.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/browser-support.md CHANGED Viewed

@@ -25,7 +25,9 @@ In non-browser environments, initialization is skipped. If you call the SDK on t
 it returns `null` and logs a warning instead of throwing.
 Call `Elements`, `ElementsCheckout`, or `ElementsBuilder` from client-only code (e.g., after mount)
-to render components.
+to render components. `Elements` and `ElementsBuilder` resolve to no-op stubs from the main SSR
+entry; `ElementsCheckout` ships in its own tree-shaken entry with a separate stub, so it is safe to
+import even if you never use the other two.
 ## Polyfills (Legacy Browsers)

package/docs/v1/reference/error-handling.md CHANGED Viewed

@@ -29,7 +29,7 @@ try {
 }
 ```
-> A well-formed entry with an invalid product identifier does **not** throw — it renders an error view inside the component and sets an error in the store. `try/catch` here only catches structural input errors (a non-array argument or an empty array).
+> A well-formed entry with an invalid product identifier does **not** throw — it renders an error view inside the component and sets an error in the store. `try/catch` here only catches malformed input: a missing or non-string `identifier`, a `fulfillmentType` other than `shipping`/`onDemand`, or a `quantity` below 1. An **empty array logs a warning and resolves** — it does not throw and emits no event.
 ## Error Isolation
@@ -68,6 +68,14 @@ window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
 When a component fails to load, the SDK renders an error view inside the container and logs details to the console.
+## Global Error Interception
+On load, the SDK installs its own global handlers by reassigning `window.onerror` and `window.onunhandledrejection`. Each incoming error or rejection is classified by an `isSDKError` heuristic that inspects the error's message, stack, and source — matching a script `src` ending in `/elements.js`, known SDK class and directory patterns, and an `isSdk` flag on `SDKError` instances.
+When an error is classified as SDK-originated, the handler logs it to the console and returns `true` (for `onerror`) or calls `event.preventDefault()` (for `onunhandledrejection`), so the error is swallowed and never reaches your app. Errors that are not classified as SDK-originated are chained to any handler that was already installed before the SDK loaded.
+> **Implications:** SDK-originated errors are intentionally suppressed and will **not** surface in your host error monitoring (e.g. Sentry). Conversely, the heuristic is pattern-based and can occasionally match a non-SDK error, causing it to be swallowed too. If you rely on catching failures, use the `*_failed` events and `try/catch` described above rather than global error monitoring.
 ## Related Docs
 - [Events Guide](../guides/events.md)