@primer-io/primer-js 0.3.11 → 0.4.0

package/dist/primer-loader.d.ts

@@ -191,6 +191,7 @@ declare enum EventTypes {
 	BLUR = "blur",
 	CLICK = "click",
 	CLOSE = "close",
+	ENTER = "enter",
 	CONFIRMED_KLARNA_CATEGORY = "CONFIRMED_KLARNA_CATEGORY",
 	CONFIRMED_KLARNA_CATEGORY_ERROR = "CONFIRMED_KLARNA_CATEGORY_ERROR",
 	KLARNA_SESSION_UPDATE = "KLARNA_SESSION_UPDATE",
@@ -231,6 +232,9 @@ export interface ClientSessionAddress {
 	countryCode?: string;
 	postalCode?: string;
 }
+export type NullableAddress = {
+	[K in keyof ClientSessionAddress]?: ClientSessionAddress[K] | null;
+};
 export interface ClientSession {
 	orderId?: string;
 	currencyCode?: string;
@@ -313,7 +317,7 @@ export interface InputMetadata {
 	touched: boolean;
 	submitted: boolean;
 }
-export interface PaymentMethodConfig {
+export interface PaymentMethodConfig<T = Record<string, unknown>> {
 	id: string;
 	type: PaymentMethodType;
 	name: string;
@@ -326,9 +330,9 @@ export interface PaymentMethodConfig {
 				light: string;
 			};
 			borderWidth: {
-				colored: number;
-				dark: number;
-				light: number;
+				colored: number | string;
+				dark: number | string;
+				light: number | string;
 			};
 			cornerRadius: number;
 			iconPositionRelativeToText?: "START" | "END";
@@ -348,7 +352,7 @@ export interface PaymentMethodConfig {
 			height: number;
 		};
 	};
-	options: {
+	options: T extends Record<string, unknown> ? T : {
 		captureVaultedCardCvv?: boolean;
 		clientId?: string;
 		threeDSecureToken?: string;
@@ -653,6 +657,21 @@ export interface IAssetsManager {
 		displayName?: string;
 	} | null>;
 }
+export interface CheckoutModuleConfig {
+	type: string;
+	options?: Record<string, unknown>;
+}
+export interface ClientConfiguration {
+	binDataUrl: string;
+	checkoutModules?: CheckoutModuleConfig[];
+	clientSession: ClientSession;
+	coreUrl: string;
+	env: string;
+	paymentMethods: PaymentMethodConfig[];
+	pciUrl: string;
+	primerAccountId: string;
+	settleOnAuth?: boolean;
+}
 export interface HeadlessSDKUtilities {
 	getCardNetworkAsset(network: string): {
 		cardUrl: string;
@@ -674,6 +693,7 @@ export interface HeadlessSDKUtilities {
 		goatCdnUrl: string;
 	} | undefined>;
 	getPaymentMethodConfiguration(paymentMethodType: PaymentMethodType): PaymentMethodConfig | undefined;
+	setBillingAddress(address: NullableAddress): Promise<void>;
 }
 export interface CardPaymentMethodManagerOptions {
 	onCardMetadataChange?: (metadata: {
@@ -768,6 +788,7 @@ export interface PrimerHeadlessCheckout {
 	getAssetsManager(): IAssetsManager;
 	start: () => Promise<void>;
 	refreshClientSession(): Promise<boolean>;
+	getConfiguration(): ClientConfiguration;
 	teardown?: () => void;
 }
 export interface HeadlessUniversalCheckoutOptions {
@@ -1023,6 +1044,12 @@ export interface PrimerCheckoutOptions {
 		 */
 		useBuiltInButton?: boolean;
 	};
+	/**
+	 * Enable SDK Core engine (recommended)
+	 *
+	 * @default true
+	 * @remarks Set to false to use legacy SDK engine
+	 */
 	sdkCore?: boolean;
 	disabledPayments?: boolean;
 }
@@ -1216,6 +1243,7 @@ declare class PrimerEventsController implements ReactiveController {
 export type AnalyticsContextType = AnalyticsUtils | null;
 export type EventsContextType = PrimerEventsController | null;
 export type HeadlessUtilsContextType = HeadlessSDKUtilities | null;
+export type ConfigurationContextType = ClientConfiguration | null;
 export type KlarnaCategoriesContextType = {
 	categories: KlarnaPaymentMethodCategory[];
 	isLoading: boolean;
@@ -1355,6 +1383,7 @@ declare class SDKContextController implements ReactiveController {
 	private vaultManagerCvvProvider;
 	private clientOptionsContext;
 	private headlessUtilsProvider;
+	private configurationProvider;
 	private klarnaCategoriesProvider;
 	private computedStylesProvider;
 	private analyticsProvider;
@@ -1381,6 +1410,8 @@ declare class SDKContextController implements ReactiveController {
 	setKlarnaCategories(value: KlarnaCategoriesContextType): void;
 	setClientOptions(value: PrimerCheckoutOptions | null): void;
 	setHeadlessUtils(value: HeadlessUtilsContextType): void;
+	setConfiguration(value: ConfigurationContextType): void;
+	getConfiguration(): ConfigurationContextType | undefined;
 	setAnalyticsUtils(value: AnalyticsContextType): void;
 	getAnalyticsUtils(): AnalyticsContextType | undefined;
 	setComputedStyles(value: CSSStyleDeclaration): void;
@@ -1987,6 +2018,61 @@ declare global {
 		"primer-input": InputComponent;
 	}
 }
+export interface SelectOption {
+	value: string;
+	label: string;
+}
+/**
+ * A native select dropdown component
+ *
+ * @element primer-select
+ *
+ * @fires change - Fired when selection changes
+ * @fires input - Fired when input value changes
+ * @fires focus - Fired when select receives focus
+ * @fires blur - Fired when select loses focus
+ */
+declare class SelectComponent extends LitElement {
+	static styles: import("lit").CSSResult[];
+	/**
+	 * The name attribute for the select element
+	 */
+	name: string;
+	/**
+	 * The id attribute for the select element
+	 */
+	id: string;
+	/**
+	 * The current value of the select
+	 */
+	value: string;
+	/**
+	 * Whether the select is disabled
+	 */
+	disabled: boolean;
+	/**
+	 * Whether the select is in an error state
+	 */
+	hasError: boolean;
+	/**
+	 * Placeholder text for the select
+	 */
+	placeholder: string;
+	/**
+	 * Array of options for the select
+	 */
+	options: SelectOption[];
+	private handleChange;
+	private handleFocus;
+	private handleBlur;
+	private renderSelectOptions;
+	render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+	interface HTMLElementTagNameMap {
+		"primer-select": SelectComponent;
+	}
+}
 /**
  * Event detail interface for expanded-changed event
  */
@@ -2191,6 +2277,86 @@ declare global {
 	}
 }
 export type PaymentMethodsContextType = InitializedPayments | null;
+/**
+ * Google Pay component with shadow root rendering for full-width button support.
+ *
+ * Google Pay requires special rendering logic:
+ * - Renders directly to shadow root (not button container)
+ * - Does NOT render .native-button-container div
+ * - Passes shadowRoot: true in render options
+ * - Requires retry logic for async button rendering
+ */
+declare class GooglePayComponent extends LitElement {
+	static styles: import("lit").CSSResult[];
+	paymentMethod: InitializedPaymentMethod | undefined;
+	paymentManagers: InitializedManagersMap;
+	disabled: boolean;
+	private loadManagerTask;
+	private renderButtonTask;
+	constructor();
+	attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+	protected updated(changedProperties: PropertyValues): void;
+	render(): symbol;
+}
+declare global {
+	interface HTMLElementTagNameMap {
+		"primer-google-pay": GooglePayComponent;
+	}
+}
+/**
+ * Apple Pay component with standard button container rendering.
+ *
+ * Apple Pay uses the standard button container approach:
+ * - Renders to a button container div (not shadow root)
+ * - Passes buttonHeight in render options
+ * - Uses updateOverlayForContainer for disabled state
+ * - Simpler than Google Pay's shadow root approach
+ */
+declare class ApplePayComponent extends LitElement {
+	static styles: import("lit").CSSResult[];
+	paymentMethod: InitializedPaymentMethod | undefined;
+	paymentManagers: InitializedManagersMap;
+	disabled: boolean;
+	private buttonContainerRef;
+	private loadManagerTask;
+	private renderButtonTask;
+	constructor();
+	attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+	protected updated(changedProperties: PropertyValues): void;
+	render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+	interface HTMLElementTagNameMap {
+		"primer-apple-pay": ApplePayComponent;
+	}
+}
+/**
+ * PayPal component with standard button container rendering.
+ *
+ * PayPal uses the standard button container approach:
+ * - Renders to a button container div (not shadow root)
+ * - Passes buttonHeight in render options with PayPal SDK constraints (25-55px)
+ * - Uses updateOverlayForContainer for disabled state
+ * - Warns if height exceeds maximum allowed by PayPal SDK
+ */
+declare class PayPalComponent extends LitElement {
+	static styles: import("lit").CSSResult[];
+	paymentMethod: InitializedPaymentMethod | undefined;
+	paymentManagers: InitializedManagersMap;
+	disabled: boolean;
+	private buttonContainerRef;
+	private loadManagerTask;
+	private renderButtonTask;
+	constructor();
+	attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+	protected updated(changedProperties: PropertyValues): void;
+	render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+	interface HTMLElementTagNameMap {
+		"primer-paypal": PayPalComponent;
+	}
+}
 declare class PaymentMethodComponent extends LitElement {
 	static styles: import("lit").CSSResult[];
 	type: PaymentMethodType | undefined;
@@ -2337,6 +2503,158 @@ declare global {
 		"primer-redirect-payment": RedirectPaymentComponent;
 	}
 }
+/**
+ * BillingAddressComponent provides a form for collecting billing address information.
+ *
+ * Configuration is exclusively server-side via SDK Core's checkoutModules. Field visibility
+ * is determined by the BILLING_ADDRESS module in the client session configuration.
+ *
+ * @element primer-billing-address
+ *
+ * @fires primer-billing-address-change - Fired when form data changes
+ * @fires primer-billing-address-submit - Fired when form is submitted
+ */
+declare class BillingAddressComponent extends LitElement {
+	static styles: import("lit").CSSResult[];
+	/**
+	 * Configuration from SDK Core containing checkoutModules configuration
+	 */
+	configuration: ConfigurationContextType;
+	/**
+	 * Headless SDK utilities for API methods like setBillingAddress
+	 */
+	headlessUtils: HeadlessUtilsContextType;
+	/**
+	 * Form data state
+	 */
+	private formData;
+	/**
+	 * Validation errors state
+	 */
+	private errors;
+	/**
+	 * Tracks which fields have been touched (blurred after focus)
+	 */
+	private touchedFields;
+	/**
+	 * Tracks which fields are dirty (have had input)
+	 */
+	private dirtyFields;
+	/**
+	 * Tracks which field is currently focused
+	 */
+	private focusedField;
+	/**
+	 * Tracks whether the form has been submitted
+	 * Errors only show after submit or after field blur
+	 */
+	private submitted;
+	/**
+	 * List of countries for the select dropdown
+	 * Initialize with empty array, will be populated in connectedCallback
+	 */
+	private countryOptions;
+	/**
+	 * Initialization task that waits for context availability
+	 *
+	 * Purpose: Ensures configuration and headlessUtils contexts are ready before
+	 *          attempting field configuration extraction and country initialization
+	 *
+	 * Lifecycle:
+	 * - Task runs when this.configuration or this.headlessUtils changes
+	 * - Stays pending (returns initialState) until both contexts are available
+	 * - Completes when field config is extracted and countries initialized
+	 *
+	 * Phase 2: Infrastructure setup with stub methods
+	 * Phase 3: Will extract field configuration from checkoutModules
+	 * Phase 4: Will coordinate country initialization with Task lifecycle
+	 */
+	private _initializationTask;
+	/**
+	 * Initialize countries list
+	 */
+	connectedCallback(): void;
+	/**
+	 * Extract billing address field configuration from SDK Core checkoutModules
+	 * @param configuration - Configuration context from SDK Core
+	 * @returns Field configuration object
+	 */
+	private extractFieldConfig;
+	/**
+	 * Initialize country options with two-phase loading:
+	 * 1. Synchronously load English countries first
+	 * 2. Asynchronously load locale-specific countries
+	 *
+	 * This preserves the existing behavior where users see English countries
+	 * immediately, then see localized names if available.
+	 */
+	private initializeCountryOptions;
+	/**
+	 * Get billing address field configuration from SDK Core checkoutModules.
+	 *
+	 * This getter is used during rendering after the initialization task completes.
+	 * Configuration is determined by server-side checkoutModules configuration.
+	 * If not present, defaults to all fields disabled (form hidden).
+	 */
+	private get fieldConfig();
+	/**
+	 * Default field configuration (all fields disabled).
+	 * When no configuration is provided, the form is hidden.
+	 * This matches the legacy SDK behavior where billing address is opt-in.
+	 */
+	private get defaultFieldConfig();
+	/**
+	 * Check if the form should be visible
+	 * According to legacy SDK: form is hidden if postalCode is false
+	 */
+	private get shouldShowForm();
+	/**
+	 * Handle input change events
+	 */
+	private handleInput;
+	/**
+	 * Handle focus events
+	 */
+	private handleFocus;
+	/**
+	 * Handle blur events for validation
+	 */
+	private handleBlur;
+	/**
+	 * Validate a single field
+	 */
+	private validateField;
+	/**
+	 * Validate all enabled fields
+	 */
+	private validateForm;
+	/**
+	 * Public method to validate billing address fields
+	 * Called by the parent form (card-form) when submitting
+	 * Returns true if billing address is valid
+	 * Note: Does NOT call setBillingAddress API - that happens after card validation
+	 */
+	validateForSubmission(): Promise<boolean>;
+	/**
+	 * Public method to submit billing address to SDK Core
+	 * Called by parent form ONLY after both card and billing address validation pass
+	 *
+	 * Note: headlessUtils is guaranteed to be available when this method is called,
+	 * as the component only renders (and becomes interactive) after initialization task completes.
+	 */
+	submitToSDK(): Promise<boolean>;
+	/**
+	 * Check if field should show error
+	 * Matches card input behavior: show errors after submit OR after field is dirty AND touched
+	 */
+	private shouldShowError;
+	render(): symbol | import("lit-html").TemplateResult<1> | undefined;
+}
+declare global {
+	interface HTMLElementTagNameMap {
+		"primer-billing-address": BillingAddressComponent;
+	}
+}
 /**
  * Interface for secure htmlContent access
  */
@@ -2824,6 +3142,11 @@ declare class CardFormComponent extends LitElement {
 	 */
 	private hasAssignedContent;
 	private selectedCardNetwork;
+	/**
+	 * Form-level error message to display
+	 * @private
+	 */
+	private formErrorMessage;
 	/**
 	 * Flag to track if PAYMENT_METHOD_SELECTION event has been sent
 	 * @private
@@ -3278,7 +3601,7 @@ declare class CardFormSubmitComponent extends LitElement {
 	 */
 	get buttonText(): string;
 	set buttonText(value: string);
-	headlessInstance: HeadlessUtilsContextType;
+	headlessUtils: HeadlessUtilsContextType;
 	clientOptions: ClientOptionsContextType;
 	sdkState: SdkStateContextType;
 	cardFormContext: CardFormContext | null;
@@ -3435,45 +3758,6 @@ declare global {
 		"primer-show-other-payments": ShowOtherPaymentsComponent;
 	}
 }
-/**
- * Component for rendering native payment buttons (Apple Pay, Google Pay, PayPal)
- * with proper height calculations based on design system variables.
- */
-declare class NativePaymentComponent extends LitElement {
-	static styles: import("lit").CSSResult[];
-	paymentMethod: InitializedPaymentMethod | undefined;
-	paymentManagers: InitializedManagersMap;
-	computedStyles: CSSStyleDeclaration | null;
-	disabled: boolean;
-	private _buttonId;
-	private loadManagerTask;
-	private nativeButtonTask;
-	constructor();
-	attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
-	/**
-	 * Calculates the button height by reading the computed height from the element.
-	 * The CSS already calculates the correct height using CSS variables,
-	 * so we just read the browser's computed value (which handles rem/em/% conversions).
-	 */
-	private calculateButtonHeight;
-	/**
-	 * Creates render options with appropriate styles based on payment method type
-	 */
-	private createRenderOptions;
-	protected updated(changedProperties: PropertyValues): void;
-	/**
-	 * Updates the disabled overlay based on the current disabled state
-	 */
-	private updateDisabledOverlay;
-	private updateGooglePayOverlay;
-	private updateRegularOverlay;
-	render(): symbol | import("lit-html").TemplateResult<1> | undefined;
-}
-declare global {
-	interface HTMLElementTagNameMap {
-		"primer-native-payment": NativePaymentComponent;
-	}
-}
 declare class PrimerCheckoutCompleteComponent extends LitElement {
 	render(): import("lit-html").TemplateResult<1>;
 }
@@ -3546,6 +3830,8 @@ export declare function loadPrimer(): void;
 
 export {
 	AchPaymentComponent as AchPayment,
+	ApplePayComponent as ApplePay,
+	BillingAddressComponent as BillingAddress,
 	ButtonComponent as Button,
 	CardFormComponent as CardForm,
 	CardFormSubmitComponent as CardFormSubmit,
@@ -3555,6 +3841,7 @@ export {
 	DynamicPaymentComponent as DynamicPayment,
 	ErrorMessageComponent as ErrorMessage,
 	ErrorMessageContainerComponent as ErrorMessageContainer,
+	GooglePayComponent as GooglePay,
 	InputCardExpiryComponent as CardFormExpiry,
 	InputCardHolderNameComponent as CardFormName,
 	InputCardNumberComponent as CardFormCardNumber,
@@ -3563,7 +3850,7 @@ export {
 	InputErrorComponent as CardFormError,
 	InputLabelComponent as InputLabel,
 	InputWrapperComponent as InputWrapper,
-	NativePaymentComponent as NativePayment,
+	PayPalComponent as PayPal,
 	PaymentMethodComponent as PaymentMethod,
 	PaymentMethodContainerComponent as PaymentMethodContainer,
 	PortalComponent as Portal,
@@ -3574,6 +3861,7 @@ export {
 	PrimerKlarnaComponent as PrimerKlarna,
 	PrimerMainComponent as PrimerMain,
 	RedirectPaymentComponent as RedirectPayment,
+	SelectComponent as Select,
 	ShowOtherPaymentsComponent as ShowOtherPayments,
 	SpinnerComponent as Spinner,
 	VaultCvvInputComponent as VaultCvvInput,