@primer-io/primer-js 0.0.3 → 0.1.0

package/dist/jsx/index.d.ts

@@ -67,8 +67,11 @@ export type PrimerCheckoutComponentProps = {
   "client-token"?: string;
   /**  */
   options?: PrimerCheckoutOptions;
+  /** Whether the component has completed initialization and loading
+This is used to control the CSS-only loader visibility */
+  "js-initialized"?: boolean;
   /**  */
-  "disable-loader"?: boolean;
+  jsInitialized?: boolean;
   /**  */
   defaultSlot?: HTMLSlotElement;
   /**  */
@@ -81,6 +84,10 @@ export type PrimerCheckoutComponentProps = {
   primerEventsController?: PrimerEventsController;
   /**  */
   styleProcessingController?: StyleProcessingController;
+  /**  */
+  vaultManagerController?: VaultManagerController;
+  /**  */
+  cardNetworkController?: CardNetworkController;
 };
 
 export type ButtonComponentProps = {
@@ -88,8 +95,20 @@ export type ButtonComponentProps = {
   variant?: "primary" | "secondary" | "tertiary";
   /**  */
   disabled?: boolean;
+  /** Loading state of the button
+When true, the button will display a spinner and be disabled */
+  loading?: boolean;
   /**  */
   buttonType?: "button" | "submit" | "reset";
+  /** Selection state of the button
+- default: Not checked
+- checked: Button is checked */
+  selectionState?: ButtonSelectionState;
+  /** Indicates if this button is selectable/checkable */
+  selectable?: boolean;
+
+  /**  */
+  "onselection-change"?: (e: CustomEvent<CustomEvent>) => void;
 };
 
 export type PrimerCheckoutStateComponentProps = {
@@ -99,11 +118,39 @@ export type PrimerCheckoutStateComponentProps = {
   description?: string | undefined;
 };
 
+export type CollapsableComponentProps = {
+  /** The header text for the collapsable */
+  header?: string;
+  /** Whether the collapsable is expanded by default */
+  expanded?: boolean;
+  /** Text for expand button (for accessibility) */
+  expandText?: string;
+  /** Text for collapse button (for accessibility) */
+  collapseText?: string;
+  /** ARIA label for the collapsable header */
+  ariaLabel?: string;
+  /** The button variant to use */
+  buttonVariant?: ButtonVariant;
+
+  /**  */
+  "onexpanded-changed"?: (e: CustomEvent<CustomEvent>) => void;
+};
+
+export type ErrorMessageComponentProps = {
+  /** The error message text to display */
+  message?: string;
+  /** Whether the error message is visible */
+  visible?: boolean;
+  /** Accessibility role for the error message
+Defaults to "alert" for proper screen reader announcements */
+  role?: string;
+};
+
 export type PrimerIconComponentProps = {
   /**  */
   color?: string;
   /**  */
-  size?: "lg" | "sm";
+  size?: "lg" | "md" | "sm";
   /** The name of the icon to draw - available names can be found under library.ts file */
   name?: IconName | undefined;
 };
@@ -196,32 +243,50 @@ export type CardFormComponentProps = {
   paymentManagers?: InitializedManagersMap;
 };
 
+export type ErrorMessageContainerComponentProps = {
+  /**  */
+  "show-processing-errors"?: boolean;
+};
+
+export type PrimerKlarnaComponentProps = {
+  /**  */
+  paymentManagers?: InitializedManagersMap;
+  /**  */
+  sdkState?: SdkStateContext;
+  /**  */
+  headlessUtils?: HeadlessUnitilsContext;
+  /**  */
+  klarnaCategories?: KlarnaCategoriesContext | null;
+};
+
 export type NativePaymentComponentProps = {
   /**  */
   paymentMethod?: InitializedPaymentMethod | undefined;
   /**  */
   paymentManagers?: InitializedManagersMap;
+  /**  */
+  computedStyles?: CSSStyleDeclaration | null;
 };
 
 export type PaymentMethodComponentProps = {
   /**  */
   type?: PaymentMethodType | undefined;
   /**  */
-  paymentMethods?: PaymentsObject | null;
+  paymentMethods?: PaymentMethodsContext;
 };
 
 export type PrimerCheckoutCompleteComponentProps = {};
 
-export type PrimerCheckoutFailureComponentProps = {
+export type PrimerCheckoutErrorComponentProps = {
   /**  */
-  sdkState?: HeadlessSDKState | undefined;
+  sdkState?: SdkStateContext;
 };
 
 export type PrimerMainComponentProps = {
   /**  */
-  paymentMethods?: PaymentsObject | null;
+  paymentMethods?: PaymentMethodsContext;
   /**  */
-  sdkState?: SdkStateContext | undefined;
+  sdkState?: SdkStateContext;
 };
 
 export type RedirectPaymentComponentProps = {
@@ -230,13 +295,44 @@ export type RedirectPaymentComponentProps = {
   /**  */
   paymentManagers?: InitializedManagersMap;
   /**  */
-  sdkState?: SdkStateContext | undefined;
+  sdkState?: SdkStateContext;
+  /**  */
+  headlessUtils?: HeadlessUnitilsContext;
+};
+
+export type ShowOtherPaymentsComponentProps = {
+  /** Consume the vault manager context to interact with vault state */
+  vaultManager?: VaultManagerContext;
+};
+
+export type VaultManagerComponentProps = {
+  /** Strongly typed event declarations */
+  addEventListener?: <K extends keyof VaultManagerEventMap>(
+    type: K,
+    listener: (ev: VaultManagerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ) => void;
+  /**  */
+  removeEventListener?: <K extends keyof VaultManagerEventMap>(
+    type: K,
+    listener: (ev: VaultManagerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ) => void;
+  /** The vault manager core context from the SDK
+Contains vault-related functionality and state */
+  vaultManagerContext?: VaultManagerContext;
 };
 
 export type CardFormSubmitComponentProps = {
   /** The button text to display.
 Falls back to localized default if not explicitly set. */
   buttonText?: string;
+  /**  */
+  headlessInstance?: HeadlessUnitilsContext;
+  /**  */
+  clientOptions?: ClientOptionsContext;
+  /**  */
+  sdkState?: SdkStateContext;
   /** The button variant to use. */
   variant?: string;
   /** Whether the button is disabled. */
@@ -245,12 +341,16 @@ Falls back to localized default if not explicitly set. */
 
 export type CardNetworkSelectorComponentProps = {
   /** Card networks context from provider */
-  cardNetworks?: CardNetworksContext | null;
+  cardNetworks?: CardNetworksContext;
+  /**  */
+  headlessUtils?: HeadlessUnitilsContext;
   /** Dispatched when a network is selected with the network name as detail */
   "onnetwork-selected"?: (e: CustomEvent<CustomEvent>) => void;
 };
 
 export type InputCardExpiryComponentProps = {
+  /**  */
+  computedStyles?: CSSStyleDeclaration | null;
   /** The input label text.
 Falls back to localized default if not explicitly set. */
   label?: string;
@@ -266,6 +366,8 @@ Falls back to localized default if not explicitly set. */
 };
 
 export type InputCardHolderNameComponentProps = {
+  /**  */
+  computedStyles?: CSSStyleDeclaration | null;
   /** The input label text.
 Falls back to localized default if not explicitly set. */
   label?: string;
@@ -281,6 +383,8 @@ Falls back to localized default if not explicitly set. */
 };
 
 export type InputCardNumberComponentProps = {
+  /**  */
+  computedStyles?: CSSStyleDeclaration | null;
   /** The input label text.
 Falls back to localized default if not explicitly set. */
   label?: string;
@@ -296,6 +400,8 @@ Falls back to localized default if not explicitly set. */
 };
 
 export type InputCvvComponentProps = {
+  /**  */
+  computedStyles?: CSSStyleDeclaration | null;
   /** The input label text.
 Falls back to localized default if not explicitly set. */
   label?: string;
@@ -310,9 +416,145 @@ Falls back to localized default if not explicitly set. */
   cardFormContext?: CardFormContext | null;
 };
 
+export type VaultCvvInputComponentProps = {
+  /**  */
+  computedStyles?: CSSStyleDeclaration | null;
+  /**  */
+  paymentMethod?: PaymentCardVaultedMethod | null;
+  /** Form context for checking form dirty state */
+  vaultManagerFormContext?: VaultManagerContext;
+  /** CVV-specific context for dedicated CVV handling
+Separated to minimize re-renders on frequent CVV input changes */
+  vaultManagerCvvContext?: VaultItemContext;
+};
+
+export type VaultDeleteConfirmationComponentProps = {
+  /** Whether a delete operation is in progress */
+  isDeleting?: boolean;
+  /** The ID of the payment method being deleted */
+  paymentMethodId?: string;
+  /** Payment method name to display in confirmation */
+  paymentMethodName?: string;
+  /** Strongly typed event declarations */
+  addEventListener?: <K extends keyof VaultManagerEventMap>(
+    type: K,
+    listener: (ev: VaultManagerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ) => void;
+  /**  */
+  removeEventListener?: <K extends keyof VaultManagerEventMap>(
+    type: K,
+    listener: (ev: VaultManagerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ) => void;
+  /** Consume the vault manager context to access payment method info */
+  vaultManager?: VaultManagerContext;
+  /**  */
+  "onconfirm-delete"?: (e: CustomEvent<CustomEvent>) => void;
+  /**  */
+  "oncancel-delete"?: (e: CustomEvent<CustomEvent>) => void;
+};
+
+export type VaultEmptyStateComponentProps = {};
+
+export type VaultErrorMessageComponentProps = {
+  /** The error message to display */
+  errorMessage?: string;
+  /** Strongly typed event declarations */
+  addEventListener?: <K extends keyof VaultManagerEventMap>(
+    type: K,
+    listener: (ev: VaultManagerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ) => void;
+  /**  */
+  removeEventListener?: <K extends keyof VaultManagerEventMap>(
+    type: K,
+    listener: (ev: VaultManagerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ) => void;
+  /**  */
+  "onclose-error"?: (e: CustomEvent<CustomEvent>) => void;
+};
+
+export type VaultManagerHeaderComponentProps = {
+  /** Whether we're in edit mode */
+  isEditMode?: boolean;
+  /** Whether we have payment methods to edit */
+  hasPaymentMethods?: boolean;
+  /** Strongly typed event declarations */
+  addEventListener?: <K extends keyof VaultManagerEventMap>(
+    type: K,
+    listener: (ev: VaultManagerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ) => void;
+  /**  */
+  removeEventListener?: <K extends keyof VaultManagerEventMap>(
+    type: K,
+    listener: (ev: VaultManagerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ) => void;
+  /**  */
+  "ontoggle-edit-mode"?: (e: CustomEvent<CustomEvent>) => void;
+};
+
+export type VaultPaymentMethodItemComponentProps = {
+  /**  */
+  headlessUtils?: HeadlessUnitilsContext;
+  /** Whether the component is in edit mode */
+  isEditMode?: boolean;
+  /** Strongly typed event declarations */
+  addEventListener?: <K extends keyof VaultManagerEventMap>(
+    type: K,
+    listener: (ev: VaultManagerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ) => void;
+  /**  */
+  removeEventListener?: <K extends keyof VaultManagerEventMap>(
+    type: K,
+    listener: (ev: VaultManagerEventMap[K]) => void,
+    options?: boolean | AddEventListenerOptions,
+  ) => void;
+  /** Consume the vault manager context */
+  vaultManagerContext?: VaultManagerContext;
+  /**  */
+  vaultItemContext?: VaultItemContext;
+  /** The payment method to display */
+  paymentMethod?: VaultedPaymentMethod | null;
+  /**  */
+  "ondelete-payment-method"?: (e: CustomEvent<CustomEvent>) => void;
+};
+
+export type VaultPaymentSubmitComponentProps = {
+  /** The button text to display.
+Falls back to localized default if not explicitly set. */
+  buttonText?: string;
+  /**  */
+  headlessInstance?: HeadlessUnitilsContext;
+  /**  */
+  sdkState?: SdkStateContext;
+  /** The button variant to use. */
+  variant?: string;
+  /** Whether the button is disabled.
+This property allows external disabling of the button
+regardless of the context state. */
+  disabled?: boolean;
+  /**  */
+  vaultItemContext?: VaultItemContext;
+  /**  */
+  vaultManager?: VaultManagerContext;
+  /**  */
+  clientOptions?: PrimerCheckoutOptions | null;
+};
+
 export type CustomElements = {
   /**
+   * 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
    * ---
    *
    */
@@ -322,6 +564,9 @@ export type CustomElements = {
    *
    * ---
    *
+   *
+   * ### **Events:**
+   *  - **selection-change**
    */
   "primer-button": Partial<ButtonComponentProps & BaseProps & BaseEvents>;
 
@@ -332,6 +577,37 @@ export type CustomElements = {
    */
   "primer-checkout-state": Partial<PrimerCheckoutStateComponentProps & BaseProps & BaseEvents>;
 
+  /**
+   * A collapsable component that smoothly expands and collapses content.
+   * Uses CSS Grid for smooth animation and incorporates the primary button.
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **expanded-changed**
+   *
+   * ### **Methods:**
+   *  - **expand(): _void_** - Expand the collapsable programmatically
+   * - **collapse(): _void_** - Collapse the collapsable programmatically
+   */
+  "primer-collapsable": Partial<CollapsableComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * 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.
+   * ---
+   *
+   *
+   * ### **CSS Parts:**
+   *  - **error-message** - The main error message container
+   * - **error-icon** - The error icon container
+   * - **error-content** - The error text content
+   */
+  "primer-error-message": Partial<ErrorMessageComponentProps & BaseProps & BaseEvents>;
+
   /**
    *
    * ---
@@ -420,6 +696,31 @@ export type CustomElements = {
    */
   "primer-card-form": Partial<CardFormComponentProps & BaseProps & BaseEvents>;
 
+  /**
+   * 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.
+   * ---
+   *
+   */
+  "primer-error-message-container": Partial<ErrorMessageContainerComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * 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
+   * ---
+   *
+   */
+  "primer-klarna": Partial<PrimerKlarnaComponentProps & BaseProps & BaseEvents>;
+
   /**
    * Component for rendering native payment buttons (Apple Pay, Google Pay, PayPal)
    * with proper height calculations based on design system variables.
@@ -447,7 +748,7 @@ export type CustomElements = {
    * ---
    *
    */
-  "primer-checkout-failure": Partial<PrimerCheckoutFailureComponentProps & BaseProps & BaseEvents>;
+  "primer-checkout-error": Partial<PrimerCheckoutErrorComponentProps & BaseProps & BaseEvents>;
 
   /**
    *
@@ -463,6 +764,21 @@ export type CustomElements = {
    */
   "primer-redirect-payment": Partial<RedirectPaymentComponentProps & BaseProps & BaseEvents>;
 
+  /**
+   * Component for showing/hiding other payment methods when vault is present
+   * Utilizes the collapsable component for smooth transitions
+   * ---
+   *
+   */
+  "primer-show-other-payments": Partial<ShowOtherPaymentsComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * VaultManagerComponent - displays and manages saved payment methods
+   * ---
+   *
+   */
+  "primer-vault-manager": Partial<VaultManagerComponentProps & BaseProps & BaseEvents>;
+
   /**
    * A form submit button component for card forms.
    * Provides a consistent submit button with translation support.
@@ -489,6 +805,10 @@ export type CustomElements = {
    *
    * ### **Methods:**
    *
+   * - **getError(): _string|null_** - Get the error code from the hosted input controller when the input is submitted or touched
+   *
+   * Can be used instead of the error returned by the `validate()` method since internally `primer-sdk-web`
+   * uses the same logic to compute the error code
    *
    */
   "primer-input-card-expiry": Partial<InputCardExpiryComponentProps & BaseProps & BaseEvents>;
@@ -500,6 +820,10 @@ export type CustomElements = {
    *
    * ### **Methods:**
    *
+   * - **getError(): _string|null_** - Get the error code from the hosted input controller when the input is submitted or touched
+   *
+   * Can be used instead of the error returned by the `validate()` method since internally `primer-sdk-web`
+   * uses the same logic to compute the error code
    *
    */
   "primer-input-card-holder-name": Partial<InputCardHolderNameComponentProps & BaseProps & BaseEvents>;
@@ -512,6 +836,10 @@ export type CustomElements = {
    * ### **Methods:**
    *
    *
+   * - **getError(): _string|null_** - Get the error code from the hosted input controller when the input is submitted or touched
+   *
+   * Can be used instead of the error returned by the `validate()` method since internally `primer-sdk-web`
+   * uses the same logic to compute the error code
    */
   "primer-input-card-number": Partial<InputCardNumberComponentProps & BaseProps & BaseEvents>;
 
@@ -522,7 +850,83 @@ export type CustomElements = {
    *
    * ### **Methods:**
    *
+   * - **getError(): _string|null_** - Get the error code from the hosted input controller when the input is submitted or touched
+   *
+   * Can be used instead of the error returned by the `validate()` method since internally `primer-sdk-web`
+   * uses the same logic to compute the error code
    *
    */
   "primer-input-cvv": Partial<InputCvvComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * 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
+   * ---
+   *
+   *
+   * ### **Methods:**
+   *  - **onCvvInputChange()** - Update CVV metadata in the context when input changes
+   */
+  "primer-vault-cvv-input": Partial<VaultCvvInputComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * VaultDeleteConfirmationComponent - displays confirmation UI for deleting a payment method
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **confirm-delete**
+   * - **cancel-delete**
+   */
+  "primer-vault-delete-confirmation": Partial<VaultDeleteConfirmationComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * VaultEmptyStateComponent - displays when no payment methods are available
+   * ---
+   *
+   */
+  "primer-vault-empty-state": Partial<VaultEmptyStateComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * VaultErrorMessageComponent - displays error messages with improved visuals
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **close-error**
+   */
+  "primer-vault-error-message": Partial<VaultErrorMessageComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * VaultManagerHeaderComponent - displays the header for the vault manager
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **toggle-edit-mode**
+   */
+  "primer-vault-manager-header": Partial<VaultManagerHeaderComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * 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
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **delete-payment-method**
+   */
+  "primer-vault-payment-method-item": Partial<VaultPaymentMethodItemComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * 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.
+   * ---
+   *
+   */
+  "primer-vault-payment-submit": Partial<VaultPaymentSubmitComponentProps & BaseProps & BaseEvents>;
 };