npm - @liquidcommerce/elements-sdk - Versions diffs - 2.6.0-beta.95 → 2.6.0-beta.97 - Mend

@liquidcommerce/elements-sdk 2.6.0-beta.95 → 2.6.0-beta.97

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 (53) 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

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

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

package/package.json CHANGED Viewed

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.6.0-beta.95",
+  "version": "2.6.0-beta.97",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",