@liquidcommerce/elements-sdk 2.7.25 → 2.7.26

package/dist/types/static/icon/filter.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const FilterIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const FilterIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/icon.a11y.d.ts

@@ -0,0 +1 @@
+export declare function iconA11yAttributes(label?: string): string;

package/dist/types/static/icon/icon.types.d.ts

@@ -3,4 +3,5 @@ export interface IconProps {
     height?: number;
     className?: string;
     color?: string | null;
+    label?: string;
 }

package/dist/types/static/icon/index.d.ts

@@ -7,6 +7,7 @@ export * from './chevron-left.icon';
 export * from './chevron-up.icon';
 export * from './close.icon';
 export * from './error-info.icon';
+export * from './icon.a11y';
 export * from './icon.types';
 export * from './info.icon';
 export * from './loading-spinner.icon';

package/dist/types/static/icon/info.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const InfoIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const InfoIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/loading-spinner.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const LoadingSpinnerIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const LoadingSpinnerIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/search.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const SearchIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const SearchIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/success.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const SuccessIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const SuccessIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/trash.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const TrashIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const TrashIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/static/icon/warning.icon.d.ts

@@ -1,2 +1,2 @@
 import type { IconProps } from './icon.types';
-export declare const WarningIcon: ({ width, height, className, color }: IconProps) => string;
+export declare const WarningIcon: ({ width, height, className, color, label }: IconProps) => string;

package/dist/types/utils/color-contrast.d.ts

@@ -0,0 +1,16 @@
+export interface IRgbColor {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+export declare const TEXT_CONTRAST_MIN = 4.5;
+export declare const NON_TEXT_CONTRAST_MIN = 3;
+export declare function parseColor(value: string | null | undefined): IRgbColor | null;
+export declare function toHexColor({ r, g, b }: IRgbColor): string;
+export declare function compositeOver(foreground: IRgbColor, background: IRgbColor): IRgbColor;
+export declare function relativeLuminance({ r, g, b }: IRgbColor): number;
+export declare function contrastRatio(foreground: IRgbColor, background: IRgbColor): number;
+export declare function meetsContrast(foreground: IRgbColor, background: IRgbColor, minRatio: number): boolean;
+export declare function ensureContrast(foreground: IRgbColor, background: IRgbColor, minRatio: number): IRgbColor;
+export declare function ensureContrastAgainstAll(foreground: IRgbColor, backgrounds: IRgbColor[], minRatio: number): IRgbColor;

package/docs/v1/README.md

@@ -32,6 +32,7 @@ In-depth guides for each major component:
 - **[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
+- **[Accessibility](./guides/accessibility.md)** - Keyboard, screen reader, contrast and focus behaviour
 - **[Events](./guides/events.md)** - Event system and subscriptions
 - **[Best Practices](./guides/best-practices.md)** - Patterns, tips, and recommendations
 
@@ -83,6 +84,8 @@ Technical reference and troubleshooting:
 - **[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
+- **[Analytics](./reference/analytics.md)** - Google Tag Manager / GA4 integration
+- **[Telemetry](./reference/telemetry.md)** - What the SDK reports and how to control it
 
 ### Examples
 

package/docs/v1/api/actions/address-actions.md

@@ -275,7 +275,7 @@ window.addEventListener('lce:actions.client_ready', () => {
     // Prompt for address on first visit
     showAddressModal();
   }
-});
+}, { once: true });
 ```
 
 ## See Also

package/docs/v1/api/client.md

@@ -256,7 +256,7 @@ window.addEventListener('lce:actions.client_ready', ( event ) => {
 
   // Safe to use client
   window.LiquidCommerce.elements.injectProductElement([...]);
-});
+}, { once: true });
 ```
 
 ## Client Interface
@@ -488,7 +488,8 @@ const config: ILiquidCommerceElementsConfig = {
   env: 'production'
 };
 
-const client: ILiquidCommerceElementsClient = await Elements('KEY', config);
+// Elements() resolves to `null` on failure, so the type is nullable.
+const client: ILiquidCommerceElementsClient | null = await Elements('KEY', config);
 ```
 
 ### Type Exports
@@ -566,7 +567,7 @@ if (window.LiquidCommerce?.elements) {
   // Wait for client ready
   window.addEventListener('lce:actions.client_ready', () => {
     window.LiquidCommerce.elements.actions.cart.openCart();
-  });
+  }, { once: true });
 }
 ```
 

package/docs/v1/api/configuration.md

@@ -74,9 +74,22 @@ interface IGlobalTheme {
   warningColor: string;
   successColor: string;
   drawerBackgroundColor: string;
+
+  /**
+   * Boundary color for form fields. Optional; defaults to a neutral that clears the 3:1
+   * contrast required by WCAG 1.4.11.
+   */
+  inputBorderColor?: string;
+
+  /** Keyboard focus ring color. Must reach 3:1 against the surface behind the control. */
+  focusRingColor?: string;
 }
 ```
 
+> `inputBorderColor` and `focusRingColor` are optional. If you omit them — or supply a value that
+> fails contrast — the runtime contrast guard substitutes a compliant color. Set them explicitly to
+> keep those two details on-brand. See [Accessibility](../guides/accessibility.md).
+
 | Property | Type | Description |
 |----------|------|-------------|
 | `buttonCornerRadius` | `string` | CSS border-radius for buttons (e.g., `'8px'`) |

package/docs/v1/api/ui-helpers.md

@@ -136,7 +136,7 @@ window.LiquidCommerce.elements.ui.cartItemsCount('items-count', { hideZero: fals
 <script>
 window.addEventListener('lce:actions.client_ready', () => {
   window.LiquidCommerce.elements.ui.cartButton('cart-btn', true);
-});
+}, { once: true });
 </script>
 ```
 
@@ -153,7 +153,7 @@ window.addEventListener('lce:actions.client_ready', () => {
 window.addEventListener('lce:actions.client_ready', () => {
   window.LiquidCommerce.elements.ui.cartItemsCount('item-count');
   window.LiquidCommerce.elements.ui.cartSubtotal('cart-total');
-});
+}, { once: true });
 </script>
 ```
 

package/docs/v1/getting-started/concepts.md

@@ -117,7 +117,7 @@ window.addEventListener('lce:actions.client_ready', (event) => {
   
   // Safe to use client
   window.LiquidCommerce.elements.actions.cart.openCart();
-});
+}, { once: true });
 ```
 
 ## Declarative vs Programmatic
@@ -197,7 +197,7 @@ window.addEventListener('lce:actions.client_ready', async () => {
   await window.LiquidCommerce.elements.injectProductElement([
     { containerId: 'dynamic-product', identifier: selectedProductId }
   ]);
-});
+}, { once: true });
 </script>
 ```
 
@@ -327,20 +327,37 @@ The SDK is designed to fail gracefully and not crash your site.
 
 ### Error Isolation
 
-SDK errors are logged and also emitted as a `*_FAILED` event, then re-thrown so your code can catch them:
+Most action failures are **not** thrown. Action methods take one of three paths, so `try/catch`
+alone is not enough to detect failure:
+
+| Situation | Behaviour |
+|---|---|
+| Malformed argument (missing `identifier`, invalid `fulfillmentType`, `quantity < 1`) | Throws `SDKError` — `try/catch` catches it |
+| Empty array or no arguments | Logs a warning and **resolves**. No event, no throw. |
+| Valid input that fails at runtime (product not found, unavailable variant, API error) | Publishes `lce:actions.cart_product_add_failed` and **resolves** |
+
+So listen for the `*_failed` event **and** wrap the call in `try/catch`:
 
 ```javascript
-// The SDK emits CART_PRODUCT_ADD_FAILED and re-throws, so this catch runs
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  console.log('Add to cart failed:', event.detail.data);
+});
+
 try {
-  await window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid data */]);
+  // Throws only if the argument itself is malformed.
+  await window.LiquidCommerce.elements.actions.cart.addProduct([
+    { identifier: '00619947000020', fulfillmentType: 'shipping', quantity: 1 }
+  ]);
 } catch (error) {
-  console.log('This error is re-thrown by the SDK and caught here');
+  console.log('Malformed input rejected by the SDK');
 }
 
-// Your page keeps working
+// Either way, your page keeps working
 console.log('Page still functional');
 ```
 
+See [Error Handling](../reference/error-handling.md) for the full matrix.
+
 ### Error Types
 
 The SDK uses a custom `SDKError` class for all errors:

package/docs/v1/getting-started/installation.md

@@ -37,7 +37,7 @@ The path segment selects which bundle is served:
 | Path | Bundle |
 |------|--------|
 | `/all/elements.js` | Full SDK bundle (product, cart, checkout, and all other elements) |
-| `/checkout/elements.js` | Checkout-only bundle (tree-shaken, smaller) |
+| `/checkout/checkout.js` | Checkout-only bundle (tree-shaken, smaller) |
 | `/all/beta/elements.js` | Beta channel of the full SDK bundle |
 
 ### Script Attributes
@@ -87,7 +87,7 @@ If you only need checkout functionality (without product displays or cart), use
   data-token="YOUR_API_KEY"
   data-env="production"
   type="text/javascript"
-  src="https://elements.reservebar-worker.workers.dev/checkout/elements.js"
+  src="https://elements.reservebar-worker.workers.dev/checkout/checkout.js"
 ></script>
 ```
 

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

@@ -165,7 +165,7 @@ If you prefer JavaScript over HTML attributes:
           identifier: '00619947000020'
         }
       ]);
-    });
+    }, { once: true });
   </script>
 </head>
 <body>
@@ -181,10 +181,15 @@ Or with NPM:
 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',
@@ -256,7 +261,7 @@ window.addEventListener('lce:actions.client_ready', async () => {
   
   // You can customize after initialization
   // See Theming Guide for more options
-});
+}, { once: true });
 </script>
 ```
 

package/docs/v1/guides/accessibility.md

@@ -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

@@ -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

@@ -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

@@ -241,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>
 ```
 
@@ -261,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>
 ```
 
@@ -679,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

@@ -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/theming.md

@@ -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'
       }
     }
   }

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

@@ -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/error-handling.md

@@ -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