npm - @liquidcommerce/elements-sdk - Versions diffs - 2.6.0-beta.11 → 2.6.0-beta.110 - Mend

@liquidcommerce/elements-sdk 2.6.0-beta.11 → 2.6.0-beta.110

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

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

@@ -0,0 +1,410 @@
+# Quick Start
+Get a product display with add-to-cart functionality working on your page in under 5 minutes.
+## What You'll Build
+A fully functional product page with:
+- Product images and details
+- Size selection
+- Fulfillment options (shipping/on-demand delivery)
+- Add to cart button
+- Shopping cart drawer
+- Complete checkout flow
+## Prerequisites
+- A LiquidCommerce API key (contact your LiquidCommerce representative)
+- A product identifier
+- A web page or HTML file
+## Step 1: Add the SDK Script
+Add the Elements SDK script tag to your HTML `<head>`:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Product Page</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+</head>
+<body>
+  <!-- We'll add the product here -->
+</body>
+</html>
+```
+**Replace `YOUR_API_KEY`** with your actual API key.
+## Step 2: Add a Product Container
+Create a container where the product will be displayed:
+```html
+<body>
+  <h1>Our Premium Whiskey</h1>
+  <!-- Product will be injected here -->
+  <div id="product-display"></div>
+</body>
+```
+## Step 3: Configure the Product (Declarative)
+Add product configuration using HTML data attributes on the script tag:
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-container-1="product-display"
+  data-product-1="00619947000020"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+```
+**New attributes:**
+- `data-container-1="product-display"` - Points to the container ID
+- `data-product-1="00619947000020"` - The product identifier
+The numbers (1) connect the container to its product. For multiple products, increment the number:
+- `data-container-2` with `data-product-2`
+- `data-container-3` with `data-product-3`
+- etc.
+## Complete Example
+Here's the complete HTML for a working product page:
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Premium Whiskey - Buy Online</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    data-container-1="product-display"
+    data-product-1="00619947000020"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+  <style>
+    body {
+      font-family: Arial, sans-serif;
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 20px;
+    }
+    h1 {
+      text-align: center;
+    }
+  </style>
+</head>
+<body>
+  <h1>Our Premium Whiskey</h1>
+  <div id="product-display"></div>
+</body>
+</html>
+```
+That's it! Save the file and open it in a browser. You should see:
+1. Product images in a carousel
+2. Product name and description
+3. Size selector
+4. Fulfillment type selector (shipping/delivery)
+5. Retailer selection
+6. Add to cart button
+When you click "Add to Cart," a cart drawer slides in from the right with checkout functionality.
+## Alternative: Programmatic Setup
+If you prefer JavaScript over HTML attributes:
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <title>My Product Page</title>
+  <script
+    defer
+    data-liquid-commerce-elements
+    data-token="YOUR_API_KEY"
+    data-env="production"
+    type="text/javascript"
+    src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+  ></script>
+  <script defer>
+    // Wait for SDK to be ready
+    window.addEventListener('lce:actions.client_ready', async (event) => {
+      const client = window.LiquidCommerce.elements;
+      // Inject the product
+      await client.injectProductElement([
+        {
+          containerId: 'product-display',
+          identifier: '00619947000020'
+        }
+      ]);
+    }, { once: true });
+  </script>
+</head>
+<body>
+  <h1>Our Premium Whiskey</h1>
+  <div id="product-display"></div>
+</body>
+</html>
+```
+Or with NPM:
+```javascript
+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',
+      identifier: '00619947000020'
+    }
+  ]);
+}
+initProduct();
+```
+## Multiple Products
+To display multiple products on one page:
+```html
+<script
+  defer
+  data-liquid-commerce-elements
+  data-token="YOUR_API_KEY"
+  data-env="production"
+  data-container-1="product-1"
+  data-product-1="00619947000020"
+  data-container-2="product-2"
+  data-product-2="08504405135"
+  data-container-3="product-3"
+  data-product-3="08068660001"
+  type="text/javascript"
+  src="https://elements.reservebar-worker.workers.dev/all/elements.js"
+></script>
+<div id="product-1"></div>
+<div id="product-2"></div>
+<div id="product-3"></div>
+```
+Or programmatically:
+```javascript
+await client.injectProductElement([
+  { containerId: 'product-1', identifier: '00619947000020' },
+  { containerId: 'product-2', identifier: '08504405135' },
+  { containerId: 'product-3', identifier: '08068660001' }
+]);
+```
+## What Happens Automatically
+The SDK handles everything for you:
+1. **Address Collection** - If needed, prompts for delivery location
+2. **Availability Check** - Shows only available fulfillment options
+3. **Cart Management** - Maintains cart across page refreshes and tabs
+4. **Checkout Flow** - Complete payment and order processing
+5. **Error Handling** - Graceful error messages and recovery
+6. **Mobile Responsiveness** - Works on all screen sizes
+## Customization
+Want to customize the look, visit the Elements Builder in our [Partner Portal](https://app.liquidcommerce.co/)? Want to manually override your theme, you can pass a `customTheme: IClientCustomThemeConfig` configuration:
+```html
+<script>
+window.addEventListener('lce:actions.client_ready', async () => {
+  const client = window.LiquidCommerce.elements;
+  // You can customize after initialization
+  // See Theming Guide for more options
+}, { once: true });
+</script>
+```
+Or with NPM:
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  env: 'production',
+  customTheme: {
+    global: {
+      theme: {
+        primaryColor: '#007bff',
+        buttonCornerRadius: '8px',
+        headingFont: {
+          name: 'Poppins',
+          weights: [400, 600]
+        }
+      }
+    }
+  }
+});
+```
+## Testing Different Products
+To test with different products, simply change the product identifier:
+```html
+<!-- Replace with your product UPC -->
+data-product-1="YOUR_PRODUCT_IDENTIFIER"
+```
+Contact your LiquidCommerce representative for available product identifiers.
+## Troubleshooting
+### Product Not Showing
+1. **Check the browser console** for errors
+2. **Verify your API key** is correct
+3. **Confirm the product identifier** exists in your catalog
+4. **Check the container ID** matches your HTML
+### Styling Issues
+The product uses Shadow DOM for style encapsulation. To customize:
+- Use the `customTheme` configuration option
+- See [Theming Guide](../guides/theming.md) for detailed customization
+### Cart Not Opening
+The cart should open automatically after adding a product. If it doesn't:
+1. Check browser console for JavaScript errors
+2. Verify no other scripts are conflicting
+3. Try manually opening: `window.LiquidCommerce.elements.actions.cart.openCart()`
+## Next Steps
+Now that you have a basic product working:
+- **[Core Concepts](./concepts.md)** - Understand how the SDK works
+- **[Product Component Guide](../guides/product-component.md)** - Deep dive into product features
+- **[Cart Component Guide](../guides/cart-component.md)** - Learn about cart functionality
+- **[Checkout Component Guide](../guides/checkout-component.md)** - Customize the checkout experience
+- **[Theming Guide](../guides/theming.md)** - Make it match your brand
+- **[Events](../guides/events.md)** - React to user actions
+- **[API Reference](../api/client.md)** - Explore all available methods
+## Complete Working Example
+Try this complete example with your API key:
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Whiskey Shop</title>
+  <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>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif;
+      background: #f5f5f5;
+    }
+    header {
+      background: white;
+      padding: 20px;
+      box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+      margin-bottom: 40px;
+    }
+    .container {
+      max-width: 1200px;
+      margin: 0 auto;
+      padding: 0 20px;
+    }
+    h1 {
+      text-align: center;
+      color: #333;
+    }
+    #product {
+      background: white;
+      border-radius: 8px;
+      padding: 20px;
+      box-shadow: 0 2px 8px rgba(0,0,0,0.1);
+    }
+  </style>
+</head>
+<body>
+  <header>
+    <div class="container">
+      <h1>🥃 Premium Spirits Collection</h1>
+    </div>
+  </header>
+  <div class="container">
+    <div id="product"></div>
+  </div>
+</body>
+</html>
+```
+Replace `YOUR_API_KEY` with your actual key and you're ready to go!

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

@@ -0,0 +1,214 @@
+# 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 and managed focus — there is nothing to switch on. Colour contrast is the exception:
+the SDK renders your theme's colours exactly as given, so that part is yours — see
+[Colour and contrast](#colour-and-contrast).
+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, `<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 meet the WCAG contrast minimums (the SDK renders your colours as given) |
+| 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, `Home` / `End` for the ends |
+| 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 |
+| Tip amount | `Tab` to the group, `←` `→` to move, `Enter` / `Space` to choose, `Home` / `End` for the ends |
+| 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`, the token already used for text on that fill — so setting the pair
+`primaryColor` / `selectedTextColor` to a combination that clears 3:1 covers the ring too.
+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 …, $…, Ships in 2-3 days, delivery $…" |
+| Delivery method switched | "Shipping selected. 5 options available. Shipping from …, $…, Ships in 2-3 days, delivery $…" |
+| 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. Product sizes are a `listbox`; the delivery options
+  under each method are a `radiogroup`.
+- The delivery-method controls are a `tablist` of `tab`s. Only one method's options are rendered at
+  a time, so the selected tab carries `aria-controls` and the region it swaps in is the matching
+  `tabpanel`, labelled by that tab; the inactive tab points at nothing, because there is nothing
+  there to point at. A method switched off by configuration renders no tab at all, and the region
+  then falls back to its own label rather than naming a tab that does not exist. Choosing an option
+  closes the panel, so arrow keys move without choosing and `Enter` / `Space` commits — a
+  deliberate departure from the radio-group model, which would otherwise select a neighbour and
+  end the interaction before the shopper reached the option they wanted.
+- 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. A field that has a visible `<label>`
+  is never *also* given an `aria-label`, which would replace the label's text rather than add to
+  it.
+- **Required fields** carry `aria-required="true"`, so they announce as required. The visible `*`
+  is reinforcement and is `aria-hidden`, since the state is already spoken; each form section
+  explains the glyph with a "Fields marked * are required." line above its fields (3.3.2).
+- An option in a single-select group carries its **whole** visible content in its accessible name.
+  `option` and `radio` have presentational children, so the name is the only channel: a delivery
+  option names the retailer, the price, the timing, the delivery fee and — for same-day — the
+  store address and whether it is currently closed.
+### Headings
+The product element emits a level-1 title with its sections (`Size`, `About this product:`) at
+level 2, and an overlay supplies its own heading at the top of its content, because the page behind
+it is out of the accessibility tree while it is open.
+Captions that label a single value — the `Delivers to:` and `Shipping From:` lines — are **not**
+headings, so they do not turn up in a heading list as headings that head nothing. `Shipping From:`
+names the card it captions with `aria-labelledby`; `Delivers to:` is hidden from assistive
+technology because the control beside it already announces the address.
+The checkout element has its own outline and is not covered by the above. Where any element's
+top-level heading sits in **your** page's outline is yours to place.
+### 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 renders the colours you supply exactly as given — it does not adjust them.** Contrast is
+therefore yours to get right: check each foreground token against the surface the Element sits on
+and make sure it reaches 4.5:1 for text (WCAG 1.4.3) and 3:1 for borders, icons and the focus ring
+(WCAG 1.4.11).
+The tokens worth checking are `defaultTextColor`, `linkTextColor`, `warningColor`, `errorColor` and
+`successColor` against `drawerBackgroundColor` (or whatever your page puts behind the Element), plus
+`selectedTextColor` against `primaryColor` for text on brand-filled buttons and badges.
+Every token ships with a default that already passes on a light surface. Two are easy to forget
+because they are optional — leave them out to keep the compliant defaults, or set them explicitly to
+keep those details on-brand:
+```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
+    }
+  }
+}
+```
+### 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,
+  });
+}
+```
+**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 colour tokens to check for contrast
+- [Best Practices](./best-practices.md)
+- [Browser Support](../reference/browser-support.md)
+## Checkout initialization and payment recovery
+Checkout announces loading or initialization failure in a status region. If initialization fails, payment fields are withheld and a keyboard-operable **Retry checkout** button retries the same checkout. The button is disabled while loading.
+Save Payment Information remains disabled until checkout initializes. During payment save it stays busy until the server responds. Recoverable billing/prepare errors are announced while the mounted card fields and billing input remain available for correction and retry.