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

package/dist/types/core/a11y/glyph-button.d.ts

@@ -0,0 +1,8 @@
+export interface IGlyphButtonParams {
+    glyph: string;
+    label: string;
+    className?: string;
+    focusKey?: string;
+    enabled?: boolean;
+}
+export declare function createGlyphButton({ glyph, label, className, focusKey, enabled }: IGlyphButtonParams): HTMLButtonElement;

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

@@ -1,3 +1,5 @@
 export { type AnnouncementPoliteness, AnnouncerService } from '@/core/a11y/announcer.service';
 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';

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

@@ -0,0 +1,16 @@
+export type RovingOrientation = 'horizontal' | 'vertical' | 'both';
+type SelectionAttribute = 'aria-selected' | 'aria-checked';
+export interface IRovingFocusOptions {
+    items: HTMLElement[];
+    orientation?: RovingOrientation;
+    selectionFollowsFocus?: boolean;
+    onActivate?: (item: HTMLElement, index: number) => void;
+}
+export declare function updateSelection(items: HTMLElement[], selected: HTMLElement | null, attribute?: SelectionAttribute): void;
+export declare function applyOptionSemantics(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/modules/address/address-display.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 { IAddressComponent } from '@/interfaces/configs';
 import type { IAddressOptions } from './address.interface';
 export interface IAddressDisplayComponentParams {
@@ -8,6 +8,8 @@ export interface IAddressDisplayComponentParams {
 }
 export declare class AddressDisplayComponent extends BaseComponent<IAddressDisplayComponentParams, IAddressComponent> {
     get hostClasses(): string[];
+    private lastAnnouncedAddress;
     constructor();
+    onStoreChanged(changes: IOnStoreChanged[]): boolean | undefined;
     protected template(): HTMLElement[];
 }

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

@@ -1,11 +1,16 @@
 import type { IProductFulfillmentStore } from '@/core/store/interfaces/product.interface';
 import { type FulfillmentType } from '@/enums';
 import type { IProductSizeAttributes } from '@/interfaces/api/product.interface';
-export declare function renderPopupRetailerCard({ fulfillment, selectedFulfillmentType, isSelected, selectedSizeAttributes, }: {
+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 focusSelectedFulfillmentTab(root: ParentNode): boolean;
+export declare function renderPopupRetailerCard({ fulfillment, selectedFulfillmentType, isSelected, selectedSizeAttributes, interactive, }: {
     fulfillment: IProductFulfillmentStore;
     selectedFulfillmentType: FulfillmentType;
     isSelected: boolean;
     selectedSizeAttributes: IProductSizeAttributes | null;
+    interactive?: boolean;
 }): HTMLElement;
 export declare function renderFulfillmentTabsContainer({ shippingFulfillments, onDemandFulfillments, shippingSelected, onDemandSelected, onTabClick, enableShippingFulfillment, enableOnDemandFulfillment, }: {
     shippingFulfillments: IProductFulfillmentStore[];

package/dist/types/modules/product/components/product-add-to-cart-section.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 { IProductComponent } from '@/interfaces/configs';
 export interface IAddToCartSectionComponentParams {
     productId: string;
@@ -8,10 +8,13 @@ export declare class ProductAddToCartSectionComponent extends BaseComponent<IAdd
     private qtyIncreaseButton;
     private qtyDecreaseButton;
     private quantityText;
+    private pendingFocusKey;
     get hostClasses(): string[];
     get hostAttributes(): Record<string, string>;
     constructor();
     private getProductId;
+    onStoreChanged(changes: IOnStoreChanged[]): boolean | undefined;
+    afterRender(): void;
     private getAvailableQuantity;
     private isFulfillmentClosed;
     private isButtonLoading;
@@ -19,6 +22,8 @@ export declare class ProductAddToCartSectionComponent extends BaseComponent<IAdd
     private handleAddToCart;
     private handleQuantityChange;
     private calculateTotalPrice;
+    private stepperFocusKey;
+    private createStepper;
     private createQuantityContainer;
     private getSizeAttributes;
     private openEngravingForm;

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

@@ -36,5 +36,6 @@ export declare class ProductImageCarouselComponent extends BaseComponent<IImageC
     private updateTransform;
     private nextImage;
     private previousImage;
+    private mainImageLabel;
     protected template(): HTMLElement[];
 }

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

@@ -8,6 +8,7 @@ export declare class ProductRetailersCarouselComponent extends BaseComponent<IPr
     private listViewport;
     private listContainer;
     private retailerCards;
+    private pendingTabFocus;
     private isDragging;
     private hasMoved;
     private startX;

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

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

package/dist/types/modules/product-list/components/card-components/product-quantity-selector.d.ts

@@ -5,6 +5,7 @@ export interface IQuantitySelectorParams {
     maxQuantity: number;
     cardStyle: PLCCardStyle;
     disabled?: boolean;
+    productName?: string;
     onChange: (quantity: number) => void;
 }
-export declare const createQuantitySelector: ({ initialQuantity, minQuantity, maxQuantity, cardStyle, disabled, onChange, }: IQuantitySelectorParams) => HTMLElement;
+export declare const createQuantitySelector: ({ initialQuantity, minQuantity, maxQuantity, cardStyle, disabled, productName, onChange, }: IQuantitySelectorParams) => HTMLElement;

package/dist/types/modules/theme-provider/services/contrast-guard.service.d.ts

@@ -0,0 +1,19 @@
+import type { IGlobalTheme } from '@/interfaces/configs';
+import { type IRgbColor } from '@/utils/color-contrast';
+interface IGuardedHost {
+    apply: () => void;
+}
+export declare class ContrastGuardService {
+    private readonly logger;
+    private readonly hosts;
+    private readonly reported;
+    static getInstance(): ContrastGuardService;
+    register(host: IGuardedHost): () => void;
+    refreshAll(): void;
+    computeOverrides(theme: Partial<IGlobalTheme> | undefined, surface: IRgbColor | null): Record<string, string>;
+    private token;
+    private correctAgainstAll;
+    private correct;
+    private report;
+}
+export {};

package/dist/types/modules/ui-components/input/input.component.d.ts

@@ -20,6 +20,7 @@ export interface IInputComponentParams {
     onValidation?: (isValid: boolean, errors: string[]) => void;
     onChange?: (value: string) => void;
     label?: string;
+    ariaLabel?: string;
     name: string;
     autocomplete?: boolean;
     disabled?: boolean;

package/dist/types/modules/ui-components/lce-element/lce-element.component.d.ts

@@ -1,12 +1,20 @@
-import type { ComponentType } from '@/enums';
+import { type ComponentType } from '@/enums';
 import { SafeHTMLElement } from '@/utils/dom-compat';
 export declare class LceElementComponent extends SafeHTMLElement {
     private _initialized;
     protected _container: ShadowRoot | null;
     private _wrappedComponentRerender;
+    private _contentType;
+    private _appliedContrastVariables;
+    private _unregisterContrastGuard;
     constructor();
     initialize(contentType: ComponentType, contentElement: HTMLElement): void;
     rerender(context?: string): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private applyContrastCorrections;
+    private resolveSurfaceColor;
+    private measureHostSurfaceColor;
     private applyBasicStyles;
     private isCSSStyleSheetSupported;
     private applyThemeStyles;

package/dist/types/static/icon/arrow-right.icon.d.ts

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

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

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

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

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

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

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

package/dist/types/static/icon/chevron-down.icon.d.ts

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

package/dist/types/static/icon/chevron-left.icon.d.ts

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

package/dist/types/static/icon/chevron-up.icon.d.ts

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

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

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

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

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

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