@primer-io/primer-js 0.3.11 → 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;
@@ -333,17 +369,6 @@ export type PrimerKlarnaComponentProps = {
   toggleExpand?: string;
 };
 
-export type NativePaymentComponentProps = {
-  /**  */
-  paymentMethod?: InitializedPaymentMethod | undefined;
-  /**  */
-  paymentManagers?: InitializedManagersMap;
-  /**  */
-  computedStyles?: CSSStyleDeclaration | null;
-  /**  */
-  disabled?: boolean;
-};
-
 export type PaymentMethodComponentProps = {
   /**  */
   type?: PaymentMethodType | undefined;
@@ -445,7 +470,7 @@ export type CardFormSubmitComponentProps = {
 Falls back to localized default if not explicitly set. */
   buttonText?: string;
   /**  */
-  headlessInstance?: HeadlessUtilsContextType;
+  headlessUtils?: HeadlessUtilsContextType;
   /**  */
   clientOptions?: ClientOptionsContextType;
   /**  */
@@ -539,6 +564,33 @@ Falls back to localized default if not explicitly set. */
   cardFormContext?: CardFormContext | null;
 };
 
+export type ApplePayComponentProps = {
+  /**  */
+  paymentMethod?: InitializedPaymentMethod | undefined;
+  /**  */
+  paymentManagers?: InitializedManagersMap;
+  /**  */
+  disabled?: boolean;
+};
+
+export type GooglePayComponentProps = {
+  /**  */
+  paymentMethod?: InitializedPaymentMethod | undefined;
+  /**  */
+  paymentManagers?: InitializedManagersMap;
+  /**  */
+  disabled?: boolean;
+};
+
+export type PayPalComponentProps = {
+  /**  */
+  paymentMethod?: InitializedPaymentMethod | undefined;
+  /**  */
+  paymentManagers?: InitializedManagersMap;
+  /**  */
+  disabled?: boolean;
+};
+
 export type PaymentMethodContentComponentProps = {
   /** The asset configuration containing icon and display data */
   assetConfig?: AssetConfig | null;
@@ -815,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
@@ -836,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.
@@ -876,14 +966,6 @@ export type CustomElements = {
    */
   "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.
-   * ---
-   *
-   */
-  "primer-native-payment": Partial<NativePaymentComponentProps & BaseProps & BaseEvents>;
-
   /**
    *
    * ---
@@ -1035,6 +1117,45 @@ export type CustomElements = {
    */
   "primer-input-cvv": Partial<InputCvvComponentProps & BaseProps & BaseEvents>;
 
+  /**
+   * 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
+   * ---
+   *
+   */
+  "primer-apple-pay": Partial<ApplePayComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * 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
+   * ---
+   *
+   */
+  "primer-google-pay": Partial<GooglePayComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * 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
+   * ---
+   *
+   */
+  "primer-paypal": Partial<PayPalComponentProps & BaseProps & BaseEvents>;
+
   /**
    * PaymentMethodContentComponent - renders payment method information with icon and details
    * This component encapsulates the display logic and styles for payment method content