@liquidcommerce/elements-sdk 2.7.33 → 2.7.35

package/dist/types/core/a11y/index.d.ts

@@ -2,4 +2,5 @@ export { type AnnouncementPoliteness, AnnouncerService } from '@/core/a11y/annou
 export { A11Y_PERSIST_ATTRIBUTE, FocusManagerService } from '@/core/a11y/focus-manager.service';
 export { getFocusableElements, isFocusable, isVisible, safeFocus } from '@/core/a11y/focusable';
 export { type IGlyphButtonParams, createGlyphButton } from '@/core/a11y/glyph-button';
-export { type IRovingFocusOptions, type RovingOrientation, applyOptionSemantics, focusSelectedItem, updateSelection, wireRovingFocus, } from '@/core/a11y/single-select';
+export { markRequired } from '@/core/a11y/required';
+export { type IRovingFocusOptions, type RovingOrientation, applyOptionSemantics, applyRadioSemantics, focusSelectedItem, updateSelection, wireRovingFocus, } from '@/core/a11y/single-select';

package/dist/types/core/a11y/required.d.ts

@@ -0,0 +1 @@
+export declare function markRequired(element: HTMLElement, isRequired?: boolean): void;

package/dist/types/core/a11y/single-select.d.ts

@@ -1,5 +1,5 @@
 export type RovingOrientation = 'horizontal' | 'vertical' | 'both';
-type SelectionAttribute = 'aria-selected' | 'aria-checked';
+type SelectionAttribute = 'aria-selected' | 'aria-checked' | 'aria-pressed';
 export interface IRovingFocusOptions {
     items: HTMLElement[];
     orientation?: RovingOrientation;
@@ -11,6 +11,10 @@ export declare function applyOptionSemantics(element: HTMLElement, { label, sele
     label: string;
     selected: boolean;
 }): void;
+export declare function applyRadioSemantics(element: HTMLElement, { label, selected }: {
+    label: string;
+    selected: boolean;
+}): void;
 export declare function focusSelectedItem(root: ParentNode, itemSelector: string): boolean;
 export declare function wireRovingFocus({ items, orientation, selectionFollowsFocus, onActivate }: IRovingFocusOptions): void;
 export {};

package/dist/types/core/store/interfaces/checkout.interface.d.ts

@@ -30,6 +30,7 @@ export interface ICheckoutPaymentFormStore {
     isSaving: boolean;
 }
 export interface ICheckoutStore {
+    initialized: boolean;
     token: string;
     cartId: string;
     presale: ICheckoutPresale | null;

package/dist/types/modules/checkout/checkout.commands.d.ts

@@ -6,6 +6,11 @@ import type { AddItemParams } from '@/modules/cart/cart.commands';
 import type { PresaleExpiredReason } from '@/modules/checkout/components';
 export declare class CheckoutCommands extends BaseCommand {
     private readonly uiCommands;
+    private lastLoadParams;
+    private paymentGeneration;
+    private confirmedPayment;
+    assertPaymentReady(): void;
+    retryLoadCheckout(): Promise<void>;
     constructor();
     static getInstance(): CheckoutCommands;
     addPresaleItem(params: AddItemParams): Promise<void>;
@@ -14,10 +19,11 @@ export declare class CheckoutCommands extends BaseCommand {
         cartId?: string;
         isForPresale?: boolean;
     }): Promise<void>;
+    private showAlreadyCompletedCheckout;
     loadCheckoutFromResponse(response: ICheckoutPrepare): void;
     toggleIsGift(active?: boolean): Promise<void>;
     toggleBillingSameAsShipping(active?: boolean): Promise<void>;
-    toggleMarketingPreferences(fieldName: 'canEmail' | 'canSms', active?: boolean): Promise<void>;
+    toggleMarketingPreferences(fieldName: 'canEmail' | 'canSms', active?: boolean): Promise<boolean>;
     getPaymentSession(): Promise<void>;
     confirmPaymentSession(confirmationTokenId: string, setupIntentId: string): Promise<ICheckoutPaymentMethodStore>;
     applyPromoCode(code: string): Promise<void>;

package/dist/types/modules/checkout/checkout.component.d.ts

@@ -1,4 +1,4 @@
-import { BaseComponent } from '@/core/base-component.service';
+import { BaseComponent, type IOnStoreChanged } from '@/core/base-component.service';
 import type { ICheckoutComponent } from '@/interfaces/configs';
 export interface ICheckoutComponentParams {
     checkoutId: string;
@@ -7,6 +7,9 @@ export interface ICheckoutComponentParams {
 }
 export declare class CheckoutComponent extends BaseComponent<ICheckoutComponentParams, ICheckoutComponent> {
     constructor();
+    onStoreWatch(_changes: IOnStoreChanged[]): void;
+    private updateInitializationState;
+    afterRender(): void;
     protected template(): HTMLElement[];
     private createHeader;
 }

package/dist/types/modules/checkout/components/checkout-billing.component.d.ts

@@ -8,6 +8,9 @@ export declare class CheckoutBillingComponent extends BaseComponent<ICheckoutBil
     private billingData;
     get hostClasses(): string[];
     constructor();
+    private pendingToggleFocus;
+    protected afterRender(): void;
+    private readonly onBillingSameAsShippingToggle;
     private billingSameAsShippingToggle;
     private updateSaveButtonState;
     protected template(): HTMLElement[];

package/dist/types/modules/checkout/components/checkout-order-summary.component.d.ts

@@ -6,6 +6,8 @@ export declare class CheckoutOrderSummaryComponent extends BaseComponent<null, I
     onStoreWatch(changes: IOnStoreChanged[]): void;
     private updateZeroAmountElement;
     protected afterRender(): void;
+    private paintMarketingCheckbox;
+    private toggleMarketingPreference;
     private handleEmailToggle;
     private handleSmsToggle;
     private marketingOptInsContainer;

package/dist/types/modules/checkout/components/checkout-send-as-gift.component.d.ts

@@ -3,5 +3,8 @@ import type { ICheckoutComponent } from '@/interfaces/configs';
 export declare class CheckoutSendAsGiftComponent extends BaseComponent<null, ICheckoutComponent> {
     get hostClasses(): string[];
     constructor();
+    private pendingToggleFocus;
+    protected afterRender(): void;
+    private readonly onToggle;
     protected template(): HTMLElement[];
 }

package/dist/types/modules/checkout/components/checkout-stripe-form.component.d.ts

@@ -26,12 +26,14 @@ export interface IStripeFormStatus {
 }
 export declare class CheckoutStripeFormComponent extends SafeHTMLElement {
     private _initialized;
+    private _lifecycleGeneration;
     private _stripe;
     private _stripeElements;
     private _paymentElement;
     private _isProcessing;
     private _isFormComplete;
     private _hasUsedCurrentSession;
+    private _pendingConfirmation;
     private _stripeConfig;
     private _sessionRefreshPromise;
     initialize({ data }: {
@@ -45,7 +47,6 @@ export declare class CheckoutStripeFormComponent extends SafeHTMLElement {
     private handleSubmit;
     private requestSessionRefresh;
     private refreshPaymentSession;
-    private resetForm;
     private updateStripeFormStatus;
     private createConfirmationTokenId;
     disconnected(): Promise<void>;

package/dist/types/modules/checkout/components/checkout-tips.component.d.ts

@@ -4,6 +4,8 @@ export declare class CheckoutTipsComponent extends BaseComponent<null, ICheckout
     private isInitialized;
     get hostClasses(): string[];
     constructor();
+    private pendingTipFocus;
+    private restoreTipFocus;
     protected afterRender(): void;
     private getTipSelection;
     private getOnDemandFulfillments;

package/dist/types/modules/checkout/components/required-fields-legend.d.ts

@@ -0,0 +1 @@
+export declare function requiredFieldsLegend(className?: string): HTMLElement;

package/dist/types/modules/checkout/payment-session-error.d.ts

@@ -0,0 +1,4 @@
+import { SDKError } from '@/core/sdk-error-handler';
+export declare class PaymentSessionRefreshError extends SDKError {
+    constructor(message: string);
+}

package/dist/types/modules/product/components/components.d.ts

@@ -2,17 +2,33 @@ import type { IProductFulfillmentStore } from '@/core/store/interfaces/product.i
 import { type FulfillmentType } from '@/enums';
 import type { IProductSizeAttributes } from '@/interfaces/api/product.interface';
 export declare const FULFILLMENT_TAB_SELECTOR = ".fulfillment-tab";
-export declare function fulfillmentSelectedMessage(fulfillment: IProductFulfillmentStore, type: FulfillmentType): string;
-export declare function fulfillmentTypeMessage(type: FulfillmentType, optionCount: number): string;
+export declare function fulfillmentTabId(idPrefix: string, type: FulfillmentType): string;
+export declare function fulfillmentExpectationText(fulfillment: IProductFulfillmentStore, selectedSizeAttributes: IProductSizeAttributes | null, onDemandSelected: boolean): string;
+export declare function fulfillmentFeeText(fulfillment: IProductFulfillmentStore, { prefix, freeLabel }?: {
+    prefix?: string | undefined;
+    freeLabel?: string | undefined;
+}): string;
+export declare function fulfillmentOptionLabel({ fulfillment, selectedFulfillmentType, selectedSizeAttributes, }: {
+    fulfillment: IProductFulfillmentStore;
+    selectedFulfillmentType: FulfillmentType;
+    selectedSizeAttributes: IProductSizeAttributes | null;
+}): string;
+export declare function fulfillmentSelectedMessage(fulfillment: IProductFulfillmentStore, type: FulfillmentType, selectedSizeAttributes: IProductSizeAttributes | null): string;
+export declare function fulfillmentTypeMessage(type: FulfillmentType, optionCount: number, autoSelected?: {
+    fulfillment: IProductFulfillmentStore;
+    selectedSizeAttributes: IProductSizeAttributes | null;
+} | null): string;
 export declare function focusSelectedFulfillmentTab(root: ParentNode): boolean;
-export declare function renderPopupRetailerCard({ fulfillment, selectedFulfillmentType, isSelected, selectedSizeAttributes, interactive, }: {
+export declare function applyFulfillmentPanelSemantics(panel: HTMLElement, tabsContainer: HTMLElement, panelId: string, selectedTabId: string): void;
+export declare function renderPopupRetailerCard({ fulfillment, selectedFulfillmentType, isSelected, selectedSizeAttributes, interactive, disabled, }: {
     fulfillment: IProductFulfillmentStore;
     selectedFulfillmentType: FulfillmentType;
     isSelected: boolean;
     selectedSizeAttributes: IProductSizeAttributes | null;
     interactive?: boolean;
+    disabled?: boolean;
 }): HTMLElement;
-export declare function renderFulfillmentTabsContainer({ shippingFulfillments, onDemandFulfillments, shippingSelected, onDemandSelected, onTabClick, enableShippingFulfillment, enableOnDemandFulfillment, primaryFulfillmentMethod, }: {
+export declare function renderFulfillmentTabsContainer({ shippingFulfillments, onDemandFulfillments, shippingSelected, onDemandSelected, onTabClick, enableShippingFulfillment, enableOnDemandFulfillment, primaryFulfillmentMethod, idPrefix, panelId, }: {
     shippingFulfillments: IProductFulfillmentStore[];
     onDemandFulfillments: IProductFulfillmentStore[];
     shippingSelected: boolean;
@@ -21,4 +37,6 @@ export declare function renderFulfillmentTabsContainer({ shippingFulfillments, o
     enableShippingFulfillment: boolean;
     enableOnDemandFulfillment: boolean;
     primaryFulfillmentMethod: FulfillmentType;
+    idPrefix: string;
+    panelId: string;
 }): HTMLElement;

package/dist/types/modules/product/components/product-retailers-carousel.component.d.ts

@@ -20,6 +20,8 @@ export declare class ProductRetailersCarouselComponent extends BaseComponent<IPr
     afterRender(): void;
     private cacheElements;
     private getProductId;
+    private get instanceIdPrefix();
+    private selectedSizeAttributes;
     onStoreWatch(changes: IOnStoreChanged[]): void;
     private updateSelectedCard;
     private scrollToIndex;

package/dist/types/modules/product/components/product-retailers-popup-list.component.d.ts

@@ -9,11 +9,13 @@ export interface IProductRetailersPopupListComponentParams {
 export declare class ProductRetailersPopupListComponent extends BaseComponent<IProductRetailersPopupListComponentParams, IProductComponent> {
     get hostClasses(): string[];
     private get isProductContext();
+    private get instanceIdPrefix();
     private productPath;
     beforeSetupStoreWatchers(): void;
     private pendingTabFocus;
     protected afterRender(): void;
     private onFulfillmentTabClick;
+    private selectedSizeAttributes;
     private announceSelectedFulfillment;
     private announceFulfillmentTypeChange;
     private onRetailerCardClick;

package/docs/v1/guides/accessibility.md

@@ -5,13 +5,15 @@ What the Elements SDK does for accessibility, what it needs from your page, and
 ## 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.
+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, heading order, `<html lang>` |
+| 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 |
@@ -27,10 +29,11 @@ tab-through slog.
 |---|---|
 | 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 |
+| 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 |
@@ -77,8 +80,8 @@ Content that appears or changes without navigation is announced through a shared
 |---|---|
 | 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." |
+| 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" |
@@ -98,13 +101,45 @@ on render, and a live region recreated with its text already in place is not ann
 - 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.
+  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.
+  `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
 
@@ -171,3 +206,9 @@ for (const region of document.querySelectorAll('[data-lce-live-region]')) {
 - [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.

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.7.33",
+  "version": "2.7.35",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -14,7 +14,7 @@
   },
   "module": "./dist/index.esm.js",
   "types": "./dist/types/index.d.ts",
-  "packageManager": "pnpm@11.22.0",
+  "packageManager": "pnpm@11.24.0",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -64,7 +64,9 @@
     "clean": "rm -rf dist umd node_modules && pnpm install && pnpm build:all",
     "prepublishOnly": "pnpm run build",
     "deprecate:old": "npm deprecate @liquidcommerceteam/elements-sdk@\"*\" \"Package moved to @liquidcommerce/elements-sdk\"",
-    "prepare": "husky"
+    "prepare": "husky",
+    "test": "vitest run",
+    "test:browser": "playwright test"
   },
   "keywords": [
     "liquidcommerce",
@@ -107,9 +109,10 @@
     "theming"
   ],
   "devDependencies": {
-    "@biomejs/biome": "^2.5.9",
+    "@biomejs/biome": "^2.5.11",
     "@commitlint/cli": "^21.2.2",
     "@commitlint/config-conventional": "^21.2.2",
+    "@playwright/test": "1.60.0",
     "@rollup/plugin-alias": "^6.0.0",
     "@rollup/plugin-commonjs": "^29.0.3",
     "@rollup/plugin-json": "^6.1.0",
@@ -123,16 +126,18 @@
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^26.2.0",
+    "@types/node": "^26.4.0",
     "conventional-changelog": "8.1.3",
     "husky": "^9.1.7",
+    "jsdom": "26.1.0",
     "process": "^0.11.10",
-    "rollup": "^4.62.4",
+    "rollup": "^4.63.1",
     "rollup-obfuscator": "^4.1.1",
     "rollup-plugin-typescript2": "^0.37.0",
     "semantic-release": "^25.0.9",
     "ts-node": "^10.9.2",
-    "typescript": "6.0.3"
+    "typescript": "6.0.3",
+    "vitest": "2.1.9"
   },
   "engines": {
     "node": ">=22"