@primer-io/primer-js 0.3.12 → 0.4.0

package/dist/jsx/index.d.ts

@@ -244,6 +244,31 @@ export type PortalComponentProps = {
   oneventName?: (e: CustomEvent<CustomEvent>) => void;
 };
 
+export type SelectComponentProps = {
+  /** 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 */
+  "has-error"?: boolean;
+  /** Placeholder text for the select */
+  placeholder?: string;
+  /** Array of options for the select */
+  options?: SelectOption[];
+  /** Fired when selection changes */
+  onchange?: (e: CustomEvent<CustomEvent>) => void;
+  /** Fired when input value changes */
+  oninput?: (e: CustomEvent<CustomEvent>) => void;
+  /** Fired when select receives focus */
+  onfocus?: (e: CustomEvent<CustomEvent>) => void;
+  /** Fired when select loses focus */
+  onblur?: (e: CustomEvent<CustomEvent>) => void;
+};
+
 export type SpinnerComponentProps = {
   /** Color of the spinner
 Defaults to the design system loader color */
@@ -277,6 +302,17 @@ export type AchPaymentComponentProps = {
   "onprimer-ach-mandate-declined"?: (e: CustomEvent<CustomEvent>) => void;
 };
 
+export type BillingAddressComponentProps = {
+  /** Configuration from SDK Core containing checkoutModules configuration */
+  configuration?: ConfigurationContextType;
+  /** Headless SDK utilities for API methods like setBillingAddress */
+  headlessUtils?: HeadlessUtilsContextType;
+  /** Fired when form data changes */
+  "onprimer-billing-address-change"?: (e: CustomEvent<CustomEvent>) => void;
+  /** Fired when form is submitted */
+  "onprimer-billing-address-submit"?: (e: CustomEvent<CustomEvent>) => void;
+};
+
 export type CardFormComponentProps = {
   /**  */
   "hide-labels"?: boolean;
@@ -434,7 +470,7 @@ export type CardFormSubmitComponentProps = {
 Falls back to localized default if not explicitly set. */
   buttonText?: string;
   /**  */
-  headlessInstance?: HeadlessUtilsContextType;
+  headlessUtils?: HeadlessUtilsContextType;
   /**  */
   clientOptions?: ClientOptionsContextType;
   /**  */
@@ -831,6 +867,19 @@ export type CustomElements = {
    */
   "primer-portal": Partial<PortalComponentProps & BaseProps & BaseEvents>;
 
+  /**
+   * A native select dropdown component
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **change** - Fired when selection changes
+   * - **input** - Fired when input value changes
+   * - **focus** - Fired when select receives focus
+   * - **blur** - Fired when select loses focus
+   */
+  "primer-select": Partial<SelectComponentProps & BaseProps & BaseEvents>;
+
   /**
    * Spinner component with configurable size and color
    * Adapted to work both standalone and within input components
@@ -852,6 +901,31 @@ export type CustomElements = {
    */
   "primer-ach-payment": Partial<AchPaymentComponentProps & BaseProps & BaseEvents>;
 
+  /**
+   * 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.
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **primer-billing-address-change** - Fired when form data changes
+   * - **primer-billing-address-submit** - Fired when form is submitted
+   *
+   * ### **Methods:**
+   *  - **validateForSubmission(): _Promise<boolean>_** - 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
+   * - **submitToSDK(): _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.
+   */
+  "primer-billing-address": Partial<BillingAddressComponentProps & BaseProps & BaseEvents>;
+
   /**
    * CardFormComponent serves as a container for card input components.
    * It handles form submission, validation, and provides context to child components.

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
  */
@@ -2417,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
  */
@@ -2904,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
@@ -3358,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;
@@ -3588,6 +3831,7 @@ export declare function loadPrimer(): void;
 export {
 	AchPaymentComponent as AchPayment,
 	ApplePayComponent as ApplePay,
+	BillingAddressComponent as BillingAddress,
 	ButtonComponent as Button,
 	CardFormComponent as CardForm,
 	CardFormSubmitComponent as CardFormSubmit,
@@ -3617,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,