@liquidcommerce/elements-sdk 2.6.0-beta.13 → 2.6.0-beta.131

package/docs/v1/guides/accessibility.md

@@ -0,0 +1,298 @@
+# 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 onto the first control inside it — the panel's close
+  button, the address field — and remembers the control that opened it. Focus lands on a
+  control rather than on the panel itself so the focus ring shows a sighted keyboard user
+  where they now are; the dialog's role and name are announced either way as focus crosses
+  into it. Views whose point is the text at the top of them (the order confirmation) focus
+  that heading instead.
+- **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.
+
+### Retailer shopping from the cart
+
+The opt-in `cart.layout.showShopRetailerButton` uses a native **Shop {retailer}** button with
+normal Tab, Enter and Space behavior, a 44px minimum target height and a visible focus ring.
+It appears beside the unmet-minimum warning on desktop and below it on mobile. Warning updates
+retain the button node and its focus; if it disappears because the minimum is met or eligibility
+changes, focus moves to the containing fulfillment before its item controls. The host handles
+focus after closing the drawer and navigating in response to `cart_shop_retailer`.
+
+The button text, border and focus ring use `global.theme.primaryColor`; check that color against
+the cart background as part of your theme contrast review.
+
+### 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" |
+| Express checkout payment failed | "Express checkout failed. …" |
+| Card form could not load Stripe.js | The reason and what to do, e.g. "Your cookie settings are blocking our secure payment form. …" (assertive) |
+| 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`.
+- Checkout's **Delivery Method** section is an accordion whose header is a real `button` carrying
+  `aria-expanded`, and whose two methods are a `radiogroup` of `radio` cards. Choosing one re-prices
+  the order, so selection does not follow focus here either: arrow keys move between the methods and
+  `Enter` / `Space` commits, rather than committing a switch the shopper was only passing through.
+  A method that cannot fulfil is `aria-disabled` and not activatable, but the **Change Location**
+  button inside it stays reachable — it is the way out of that state, so it must not be sealed in
+  with the option it sits under. Each card names the method, its fee and its timing, or, when it
+  cannot fulfil, the reason why.
+- 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. A closed store that schedules delivery leads
+  with that instead ("Columbus Avenue Wines, closed now, schedule delivery"), followed by
+  "next arrival Thu, Oct 8, 1 PM – 2 PM ET" only when the server sends a next window; its card
+  stays enabled.
+- The California Proposition 65 warning on the product is a native `<details>` / `<summary>`
+  disclosure: the summary is a button that exposes its expanded state, and `Enter` / `Space` toggle
+  it with no scripting involved. Its `+` / `−` indicator is decorative and hidden. In checkout it is
+  a plain link whose accessible name ends "(opens in a new tab)", since following it leaves the
+  purchase mid-flow; the `·` separator is hidden.
+
+### Headings
+
+The product element emits a level-1 title, and every section caption below it sits at level 2 —
+`Size`, `Delivers to:`, `Shipping From:` and `About this product:` — so the whole element is
+reachable by heading navigation with no level skipped. 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.
+
+A caption can do both jobs at once: `Shipping From:` is a heading *and* names the retailer card
+beneath it through `aria-labelledby`. Heading ids are scoped to the product, so each product
+element on a page labels its own sections.
+
+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.
+
+### Express checkout
+
+The Apple Pay and Google Pay buttons are rendered by Stripe inside an iframe, so their own labels
+and keyboard behaviour are Stripe's. What the SDK owns around them:
+
+- The **"Express Checkout" heading** is an `h3`, matching the other checkout section headings. It is
+  rendered only by the `section` variant; injected on their own the buttons carry no heading, and the
+  host page's own outline supplies it.
+- The **`OR` divider** is decorative and carries `aria-hidden="true"`, so "OR" is not announced as
+  content between the buttons and the section below.
+- When the shopper's device offers **no wallet**, the heading and the divider are removed from the
+  accessibility tree along with the buttons, so no orphan rule or empty heading is left behind. The block is also removed on a gift order, which express cannot place, and where a
+  payment method is already bound to the checkout. It is offered to every shopper otherwise.
+- The **wallet sheet is browser UI**, not an SDK overlay: the browser owns focus while it is open and
+  returns it to the button that opened it. Dismissing the sheet changes nothing in the page, so
+  nothing is announced.
+- Failures are announced assertively, because the shopper has just authorised a payment and the sheet
+  that showed the error has already closed. Confirming the sheet places the order outright, so there
+  is nothing to announce on the success path beyond the order confirmation itself.
+
+### 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.
+
+`defaultTextColor` also colours the product's California Proposition 65 warning, which is legally
+required copy, so it always uses the full-strength token, never a lighter variant — make sure it
+reaches 4.5:1 on your product background. The checkout's warning panel does not use it: it is a
+fixed colour pair chosen by `global.layout.poweredByMode` (over 13:1 in both `light` and `dark`), so
+set that to `dark` if your checkout is dark.
+
+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.
+
+If the card form cannot load Stripe.js — a consent tool holding the script back, a blocker, or a failed request — the reason and a keyboard-operable **Try again** button take the card form's place, and the message is announced assertively. While a retry runs the button stays focusable (`aria-disabled`, not `disabled`), so focus is not lost; if the retry fails, focus moves to the new **Try again** button, and if it succeeds, to the card form's container.
+
+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.
+
+### Wallet payment actions
+
+The payment action's accessible name matches its visible label, including the
+selected Apple Pay or Google Pay wallet and retry/processing states. Adjacent
+instructions explain whether the action opens the wallet or retries saving already
+authorized details. These actions save the payment method; order placement is a
+separate step.
+
+### Recorded marketing choices
+
+Checkout suppresses each email/SMS consent checkbox only after the corresponding
+recorded account choice is confirmed. Suppressed controls are hidden visually and
+from the accessibility tree; unknown choices retain their named, keyboard-operable
+checkboxes. Clearing account preferences reveals the controls and synchronizes
+`aria-checked` with the current guest defaults. A shopper's explicit checkbox edit
+keeps that channel visible when account data arrives later.
+
+### Delivery date and arrival windows
+
+The delivery picker is a named native modal dialog opened from each delivery's Schedule delivery or Edit control. Dates and arrival windows are radio groups with one tab stop each and arrow-key selection; the date strip scrolls inside the dialog and unavailable dates are disabled. While windows load, the dialog is marked busy and shows a loading line; Cancel and Close stay available. Changes are drafts until Save; Cancel, Close and Escape discard them, and closing returns focus to the opening control. The dialog stays the same modal while it is open: a date or window change updates its contents in place, so it is not announced again. Save errors keep the dialog open and move focus to the error. Success is announced politely; errors and an expired or unavailable window are announced assertively, each with its own message. The time zone is named once above the windows ("Times in Eastern Time"); the first window's accessible name also carries its "Order by" time. The window list scrolls inside the dialog, and the chosen or focused window is kept in view as the picker opens, the date changes and arrow keys move.