@primer-io/primer-js 0.1.0 → 0.1.2

package/dist/primer-loader.d.ts

@@ -1,35 +1,3 @@
-/**
- * Injects the CSS loader styles into the page
- * These styles display a loading indicator before JavaScript initializes
- *
- * Unlike theme styles, loader styles should take precedence over merchant styles
- * to ensure the loading indicator is visible. We append them to the end of the head.
- */
-export declare function injectLoaderStyles(): void;
-/**
- * Injects all required theme CSS variables into the page
- * This should be called before components are rendered to ensure
- * they have access to all design tokens
- *
- * Theme styles are prepended to the document head to allow merchant styles
- * to override our default variables.
- */
-export declare function injectThemeStyles(): void;
-/**
- * Utility function to inject only the light theme CSS variables
- * @returns {void}
- */
-export declare function injectLightTheme(): void;
-/**
- * Utility function to inject only the dark theme CSS variables
- * @returns {void}
- */
-export declare function injectDarkTheme(): void;
-/**
- * Main function to load the Primer SDK with all required dependencies and styles
- * @returns {Promise<void>} A promise that resolves when loading is complete
- */
-export declare function loadPrimer(): Promise<void>;
 export type CardNetwork = {
 	displayName: string;
 	network: string;
@@ -2304,6 +2272,7 @@ export interface InitializedManagersMap extends Map<PaymentMethodType, Initializ
 	get<T extends PaymentMethodType>(key: T): ManagerByType<T> | undefined;
 }
 export type RedirectPaymentMethodTypes = Exclude<PaymentMethodType, typeof PaymentMethodType.STRIPE_ACH | typeof PaymentMethodType.PAYMENT_CARD | typeof PaymentMethodType.KLARNA | typeof PaymentMethodType.PAYPAL | typeof PaymentMethodType.GOOGLE_PAY | typeof PaymentMethodType.APPLE_PAY>;
+export type NativePaymentMethodTypes = typeof PaymentMethodType.PAYPAL | typeof PaymentMethodType.GOOGLE_PAY | typeof PaymentMethodType.APPLE_PAY;
 export type RedirectPaymentMethod = {
 	type: RedirectPaymentMethodTypes;
 	managerType: HeadlessManagerType.REDIRECT;
@@ -2333,7 +2302,7 @@ export type PaymentMethodByType<T extends PaymentMethodType> = Extract<Initializ
 export interface InitializedPaymentMethodMap extends Map<PaymentMethodType, InitializedPaymentMethod> {
 	get<T extends PaymentMethodType>(key: T): PaymentMethodByType<T> | undefined;
 }
-declare class InitializedPayments {
+export declare class InitializedPayments {
 	private readonly _methods;
 	constructor(map: InitializedPaymentMethodMap);
 	get<T extends RedirectPaymentMethodTypes>(type: T): RedirectPaymentMethod | undefined;
@@ -2667,7 +2636,16 @@ declare const targetLocales = [
 	`zh-TW`,
 ] as const;
 export type LocaleCode = typeof sourceLocale | (typeof targetLocales)[number];
-declare class PrimerCheckoutComponent extends LitElement implements PrimerCheckoutType {
+/**
+ * PrimerCheckoutComponent implements the main checkout experience.
+ * This component includes a CSS-only loader that displays before the JavaScript
+ * is fully loaded, ensuring users see a loading indicator immediately.
+ *
+ * The loader can be disabled by:
+ * 1. Adding the 'loader-disabled' attribute to the component
+ * 2. Setting the CSS custom property --primer-loader-disabled: 1
+ */
+export declare class PrimerCheckoutComponent extends LitElement implements PrimerCheckoutType {
 	set jsInitialized(value: boolean);
 	get jsInitialized(): boolean;
 	static styles: CSSResult[];
@@ -2710,6 +2688,10 @@ declare class PrimerCheckoutComponent extends LitElement implements PrimerChecko
  * Size options for the spinner component
  */
 export type SpinnerSize = "small" | "medium" | "large";
+/**
+ * Spinner component with configurable size and color
+ * Adapted to work both standalone and within input components
+ */
 declare class SpinnerComponent extends LitElement {
 	/**
 	 * Color of the spinner
@@ -2738,6 +2720,15 @@ declare global {
 		"primer-spinner": SpinnerComponent;
 	}
 }
+/**
+ * A wrapper component for input elements that handles focus styling and interactions.
+ * Provides an improved user experience by making the entire wrapper clickable to focus the inner input.
+ *
+ * Features:
+ * - Automatically focuses primer-input elements when wrapper is clicked
+ * - Dispatches wrapper-click events for iframe-based hosted inputs
+ * - Sets proper cursor styling to indicate text input functionality
+ */
 declare class InputWrapperComponent extends LitElement {
 	static styles: CSSResult[];
 	focusWithin: boolean;
@@ -2762,6 +2753,12 @@ declare global {
 		"primer-input-wrapper": InputWrapperComponent;
 	}
 }
+/**
+ * Input label component for form elements
+ *
+ * @element primer-input-label
+ * @slot - Default slot for label text content
+ */
 declare class InputLabelComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -2823,6 +2820,12 @@ declare global {
 		"primer-button": ButtonComponent;
 	}
 }
+/**
+ * Input error component for displaying form validation messages
+ *
+ * @element primer-input-error
+ * @slot - Default slot for error message content
+ */
 declare class InputErrorComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -2880,6 +2883,20 @@ export type InputEventMap = {
 	blur: FocusEvent;
 	invalid: Event;
 };
+/**
+ * A fully type-safe input component that wraps the native HTML input element
+ * while providing additional functionality and styling.
+ *
+ * @element primer-input
+ *
+ * @fires input - Fired when the input value changes
+ * @fires change - Fired when the input value is committed
+ * @fires focus - Fired when the input receives focus
+ * @fires blur - Fired when the input loses focus
+ * @fires invalid - Fired when the input fails validation
+ *
+ * @csspart input - The native input element
+ */
 declare class InputComponent extends LitElement {
 	static styles: CSSResult[];
 	private inputElement;
@@ -2969,10 +2986,20 @@ declare global {
 		"primer-input": InputComponent;
 	}
 }
+/**
+ * Event detail interface for expanded-changed event
+ */
+export interface ExpandedChangedDetail {
+	expanded: boolean;
+}
 /**
  * Button variant types
  */
 export type ButtonVariant = "primary" | "secondary" | "tertiary";
+/**
+ * A collapsable component that smoothly expands and collapses content.
+ * Uses CSS Grid for smooth animation and incorporates the primary button.
+ */
 declare class CollapsableComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -3030,6 +3057,23 @@ declare global {
 		"primer-collapsable": CollapsableComponent;
 	}
 }
+/**
+ * A reusable atomic error message component that displays error information
+ * with appropriate styling and accessibility attributes.
+ *
+ * This component is fully accessible and designed to work with screen readers.
+ * It includes animations for visibility transitions.
+ *
+ * @element primer-error-message
+ *
+ * @attr {string} message - The error message text to display
+ * @attr {boolean} visible - Whether the error message is visible
+ * @attr {string} role - Accessibility role (defaults to "alert")
+ *
+ * @csspart error-message - The main error message container
+ * @csspart error-icon - The error icon container
+ * @csspart error-content - The error text content
+ */
 declare class ErrorMessageComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -3062,6 +3106,15 @@ declare global {
 		"primer-error-message": ErrorMessageComponent;
 	}
 }
+/**
+ * This component renders Klarna payment method in a card-like (accordion) container with
+ * payment categories options to choose from.
+ *
+ * [ Pay with Klarna    v ] --> accordion header
+ *
+ * [ Pay Now ] [ Buy now, pay later ] --> payment categories options from Klarna
+ * [ Continue with Klarna ] --> opens a Klarna popup
+ */
 declare class PrimerKlarnaComponent extends LitElement {
 	static styles: CSSResult[];
 	paymentManagers: InitializedManagersMap;
@@ -3133,6 +3186,10 @@ declare global {
 		"primer-main": PrimerMainComponent;
 	}
 }
+/**
+ * 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: CSSResult[];
 	paymentMethod: InitializedPaymentMethod | undefined;
@@ -3158,6 +3215,10 @@ declare global {
 		"primer-native-payment": NativePaymentComponent;
 	}
 }
+/**
+ * CardFormComponent serves as a container for card input components.
+ * It handles form submission, validation, and provides context to child components.
+ */
 declare class CardFormComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -3554,6 +3615,9 @@ declare abstract class AbstractCardInputComponent extends LitElement implements
 	 */
 	protected renderInput(): typeof nothing | TemplateResult<1>;
 }
+/**
+ * Card number input component with dynamic card network detection and selection
+ */
 declare class InputCardNumberComponent extends AbstractCardInputComponent {
 	static styles: CSSResult[];
 	/**
@@ -3611,6 +3675,10 @@ declare global {
 	}
 }
 export type ClientOptionsContext = PrimerCheckoutOptions | null;
+/**
+ * A form submit button component for card forms.
+ * Provides a consistent submit button with translation support.
+ */
 declare class CardFormSubmitComponent extends LitElement {
 	static styles: CSSResult[];
 	private readonly _userAssignedProps;
@@ -3642,6 +3710,12 @@ declare global {
 		"primer-card-form-submit": CardFormSubmitComponent;
 	}
 }
+/**
+ * Component for displaying and selecting card networks
+ * Uses context directly rather than properties
+ *
+ * @fires network-selected - Dispatched when a network is selected with the network name as detail
+ */
 declare class CardNetworkSelectorComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -3716,11 +3790,17 @@ declare class CardNetworkSelectorComponent extends LitElement {
 	 */
 	private setNetworkOptionRef;
 	/**
-	 * Lifecycle: Add document event listener when connected
+	 * Attach event listener to the component for keydown events
+	 * and to document for click outside and mousemove
 	 */
 	connectedCallback(): void;
 	/**
-	 * Lifecycle: Remove document event listener when disconnected
+	 * Handle document-level keydown events, but only when dropdown is open
+	 * This allows keyboard navigation to continue working
+	 */
+	private handleDocumentKeyDown;
+	/**
+	 * Lifecycle: Remove all event listeners when disconnected
 	 */
 	disconnectedCallback(): void;
 	render(): TemplateResult<1>;
@@ -3759,6 +3839,9 @@ export interface VaultManagerEventMap {
 	"close-error": VaultManagerEvents["closeError"];
 	"primer-vault-payment-error": VaultManagerEvents["vaultPaymentError"];
 }
+/**
+ * VaultManagerComponent - displays and manages saved payment methods
+ */
 declare class VaultManagerComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -3825,6 +3908,12 @@ declare class VaultManagerComponent extends LitElement {
 	private renderPaymentMethodItem;
 	render(): typeof nothing | TemplateResult<1>;
 }
+/**
+ * VaultPaymentMethodItemComponent - displays a single payment method
+ * Uses the VaultManagerController for display formatting
+ * Now supports selection via the simplified button checked state
+ * Enhanced with smooth transitions between edit and payment modes
+ */
 declare class VaultPaymentMethodItemComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -3874,6 +3963,9 @@ declare global {
 		"primer-vault-payment-method-item": VaultPaymentMethodItemComponent;
 	}
 }
+/**
+ * VaultManagerHeaderComponent - displays the header for the vault manager
+ */
 declare class VaultManagerHeaderComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -3903,6 +3995,9 @@ declare global {
 		"primer-vault-manager-header": VaultManagerHeaderComponent;
 	}
 }
+/**
+ * VaultDeleteConfirmationComponent - displays confirmation UI for deleting a payment method
+ */
 declare class VaultDeleteConfirmationComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -3944,6 +4039,9 @@ declare global {
 		"primer-vault-delete-confirmation": VaultDeleteConfirmationComponent;
 	}
 }
+/**
+ * VaultEmptyStateComponent - displays when no payment methods are available
+ */
 declare class VaultEmptyStateComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -3956,6 +4054,9 @@ declare global {
 		"primer-vault-empty-state": VaultEmptyStateComponent;
 	}
 }
+/**
+ * VaultErrorMessageComponent - displays error messages with improved visuals
+ */
 declare class VaultErrorMessageComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -3981,6 +4082,11 @@ declare global {
 		"primer-vault-error-message": VaultErrorMessageComponent;
 	}
 }
+/**
+ * A submit button component for vault payment flows.
+ * Provides a consistent submit button with translation support.
+ * Integrates with the vault manager context to handle payment submission.
+ */
 declare class VaultPaymentSubmitComponent extends LitElement {
 	static styles: CSSResult[];
 	private readonly _userAssignedProps;
@@ -4024,6 +4130,11 @@ declare global {
 		"primer-vault-payment-submit": VaultPaymentSubmitComponent;
 	}
 }
+/**
+ * CVV Input component for vault payment methods
+ * Renders a secure iframe for CVV input when required by the selected payment method
+ * Uses dedicated CVV context to minimize re-renders
+ */
 declare class VaultCvvInputComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -4068,6 +4179,10 @@ declare global {
 		"primer-vault-manager": VaultManagerComponent;
 	}
 }
+/**
+ * Component for showing/hiding other payment methods when vault is present
+ * Utilizes the collapsable component for smooth transitions
+ */
 declare class ShowOtherPaymentsComponent extends LitElement {
 	static styles: CSSResult[];
 	private isShowingOtherPayments;
@@ -4104,6 +4219,14 @@ declare global {
 		"primer-checkout-error": PrimerCheckoutErrorComponent;
 	}
 }
+/**
+ * A container component that connects to the SDK state context
+ * and displays appropriate error messages based on error state.
+ *
+ * This component handles both process errors (typically from backend)
+ * and validation errors (typically from client-side), managing when
+ * and how they are displayed based on the current SDK state.
+ */
 declare class ErrorMessageContainerComponent extends LitElement {
 	static styles: CSSResult[];
 	/**
@@ -4126,10 +4249,79 @@ declare global {
 		"primer-error-message-container": ErrorMessageContainerComponent;
 	}
 }
+/**
+ * Injects the CSS loader styles into the page
+ * These styles display a loading indicator before JavaScript initializes
+ *
+ * Unlike theme styles, loader styles should take precedence over merchant styles
+ * to ensure the loading indicator is visible. We append them to the end of the head.
+ */
+export declare function injectLoaderStyles(): void;
+/**
+ * Injects all required theme CSS variables into the page
+ * This should be called before components are rendered to ensure
+ * they have access to all design tokens
+ *
+ * Theme styles are prepended to the document head to allow merchant styles
+ * to override our default variables.
+ */
+export declare function injectThemeStyles(): void;
+/**
+ * Utility function to inject only the light theme CSS variables
+ * @returns {void}
+ */
+export declare function injectLightTheme(): void;
+/**
+ * Utility function to inject only the dark theme CSS variables
+ * @returns {void}
+ */
+export declare function injectDarkTheme(): void;
+/**
+ * Main function to load the Primer SDK with all required dependencies and styles
+ * @returns {Promise<void>} A promise that resolves when loading is complete
+ */
+export declare function loadPrimer(): Promise<void>;
 declare global {
 	interface HTMLElementTagNameMap {
 		"primer-checkout": PrimerCheckoutComponent;
 	}
 }
 
+export {
+	ButtonComponent as Button,
+	CardFormComponent as CardForm,
+	CardFormSubmitComponent as CardFormSubmit,
+	CardNetworkSelectorComponent as CardFormCardNetworkSelector,
+	CollapsableComponent as Collapsable,
+	ErrorMessageComponent as ErrorMessage,
+	ErrorMessageContainerComponent as ErrorMessageContainer,
+	InputCardExpiryComponent as CardFormExpiry,
+	InputCardHolderNameComponent as CardFormName,
+	InputCardNumberComponent as CardFormCardNumber,
+	InputComponent as Input,
+	InputCvvComponent as CardFormCVV,
+	InputErrorComponent as CardFormError,
+	InputLabelComponent as InputLabel,
+	InputWrapperComponent as InputWrapper,
+	NativePaymentComponent as NativePayment,
+	PaymentMethodComponent as PaymentMethod,
+	PrimerCheckoutCompleteComponent as PrimerCheckoutComplete,
+	PrimerCheckoutErrorComponent as PrimerCheckoutFailure,
+	PrimerCheckoutStateComponent as PrimerCheckoutState,
+	PrimerIconComponent as PrimerIcon,
+	PrimerKlarnaComponent as PrimerKlarna,
+	PrimerMainComponent as PrimerMain,
+	RedirectPaymentComponent as RedirectPayment,
+	ShowOtherPaymentsComponent as ShowOtherPayments,
+	SpinnerComponent as Spinner,
+	VaultCvvInputComponent as VaultCvvInput,
+	VaultDeleteConfirmationComponent as VaultDeleteConfirmation,
+	VaultEmptyStateComponent as VaultEmptyState,
+	VaultErrorMessageComponent as VaultErrorMessage,
+	VaultManagerComponent as VaultManager,
+	VaultManagerHeaderComponent as VaultManagerHeader,
+	VaultPaymentMethodItemComponent as VaultPaymentMethodItem,
+	VaultPaymentSubmitComponent as VaultPaymentSubmit,
+};
+
 export {};