@primer-io/primer-js 0.0.1 → 0.0.3

package/dist/jsx/index.d.ts

@@ -0,0 +1,528 @@
+/**
+ * This type can be used to create scoped tags for your components.
+ *
+ * Usage:
+ *
+ * ```ts
+ * import type { ScopedElements } from "path/to/library/jsx-integration";
+ *
+ * declare module "my-library" {
+ *   namespace JSX {
+ *     interface IntrinsicElements
+ *       extends ScopedElements<'test-', ''> {}
+ *   }
+ * }
+ * ```
+ *
+ */
+export type ScopedElements<Prefix extends string = "", Suffix extends string = ""> = {
+  [Key in keyof CustomElements as `${Prefix}${Key}${Suffix}`]: CustomElements[Key];
+};
+
+type BaseProps = {
+  /** Content added between the opening and closing tags of the element */
+  children?: any;
+  /** Used for declaratively styling one or more elements using CSS (Cascading Stylesheets) */
+  class?: string;
+  /** Used for declaratively styling one or more elements using CSS (Cascading Stylesheets) */
+  className?: string;
+  /** Takes an object where the key is the class name(s) and the value is a boolean expression. When true, the class is applied, and when false, it is removed. */
+  classList?: Record<string, boolean | undefined>;
+  /** Specifies the text direction of the element. */
+  dir?: "ltr" | "rtl";
+  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
+  exportparts?: string;
+  /** For <label> and <output>, lets you associate the label with some control. */
+  htmlFor?: string;
+  /** Specifies whether the element should be hidden. */
+  hidden?: boolean | string;
+  /** A unique identifier for the element. */
+  id?: string;
+  /** Keys tell React which array item each component corresponds to */
+  key?: string | number;
+  /** Specifies the language of the element. */
+  lang?: string;
+  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
+  part?: string;
+  /** Use the ref attribute with a variable to assign a DOM element to the variable once the element is rendered. */
+  ref?: unknown | ((e: unknown) => void);
+  /** Adds a reference for a custom element slot */
+  slot?: string;
+  /** Prop for setting inline styles */
+  style?: Record<string, string | number>;
+  /** Overrides the default Tab button behavior. Avoid using values other than -1 and 0. */
+  tabIndex?: number;
+  /** Specifies the tooltip text for the element. */
+  title?: string;
+  /** Passing 'no' excludes the element content from being translated. */
+  translate?: "yes" | "no";
+};
+
+type BaseEvents = {};
+
+export type PrimerCheckoutComponentProps = {
+  /**  */
+  "custom-styles"?: string;
+  /**  */
+  "client-token"?: string;
+  /**  */
+  options?: PrimerCheckoutOptions;
+  /**  */
+  "disable-loader"?: boolean;
+  /**  */
+  defaultSlot?: HTMLSlotElement;
+  /**  */
+  locale?: LocaleCode | undefined;
+  /**  */
+  sdkContextController?: SDKContextController;
+  /**  */
+  sdkStateController?: SdkStateController;
+  /**  */
+  primerEventsController?: PrimerEventsController;
+  /**  */
+  styleProcessingController?: StyleProcessingController;
+};
+
+export type ButtonComponentProps = {
+  /**  */
+  variant?: "primary" | "secondary" | "tertiary";
+  /**  */
+  disabled?: boolean;
+  /**  */
+  buttonType?: "button" | "submit" | "reset";
+};
+
+export type PrimerCheckoutStateComponentProps = {
+  /**  */
+  type?: "complete" | "failure";
+  /**  */
+  description?: string | undefined;
+};
+
+export type PrimerIconComponentProps = {
+  /**  */
+  color?: string;
+  /**  */
+  size?: "lg" | "sm";
+  /** The name of the icon to draw - available names can be found under library.ts file */
+  name?: IconName | undefined;
+};
+
+export type InputComponentProps = {
+  /**  */
+  value?: string;
+  /**  */
+  placeholder?: string;
+  /**  */
+  disabled?: boolean;
+  /**  */
+  name?: string;
+  /**  */
+  type?: InputType;
+  /**  */
+  required?: boolean;
+  /**  */
+  readonly?: boolean;
+  /**  */
+  pattern?: string;
+  /**  */
+  minlength?: number | undefined;
+  /**  */
+  maxlength?: number | undefined;
+  /**  */
+  min?: string;
+  /**  */
+  max?: string;
+  /**  */
+  step?: string;
+  /**  */
+  autocomplete?: string;
+  /**  */
+  id?: string;
+  /** Get the validity state of the input element */
+  validity?: ValidityState;
+  /** Get the validation message of the input element */
+  validationMessage?: string;
+  /** Fired when the input receives focus */
+  onfocus?: (e: CustomEvent<FocusEvent>) => void;
+  /** Fired when the input loses focus */
+  onblur?: (e: CustomEvent<FocusEvent>) => void;
+  /** Fired when the input fails validation */
+  oninvalid?: (e: CustomEvent<Event>) => void;
+  /** Fired when the input value changes */
+  oninput?: (e: CustomEvent<never>) => void;
+  /** Fired when the input value is committed */
+  onchange?: (e: CustomEvent<never>) => void;
+};
+
+export type InputErrorComponentProps = {
+  /** ID of the form control this error message is associated with */
+  for?: string;
+  /** Whether the error is currently active/visible */
+  active?: boolean;
+};
+
+export type InputLabelComponentProps = {
+  /** ID of the form control this label is associated with */
+  for?: string;
+  /** Whether the label should appear disabled */
+  disabled?: boolean;
+};
+
+export type InputWrapperComponentProps = {
+  /**  */
+  focusWithin?: boolean;
+  /**  */
+  "has-error"?: boolean;
+
+  /**  */
+  "onwrapper-click"?: (e: CustomEvent<CustomEvent>) => void;
+};
+
+export type SpinnerComponentProps = {
+  /** Color of the spinner
+Defaults to the design system loader color */
+  color?: string;
+  /** Size of the spinner
+Available values: 'small', 'medium', 'large' or a custom number as string */
+  size?: SpinnerSize | string;
+  /** Whether to use compact mode (minimal margins)
+Useful when embedding in inputs */
+  compact?: boolean;
+};
+
+export type CardFormComponentProps = {
+  /** Payment managers injected from context */
+  paymentManagers?: InitializedManagersMap;
+};
+
+export type NativePaymentComponentProps = {
+  /**  */
+  paymentMethod?: InitializedPaymentMethod | undefined;
+  /**  */
+  paymentManagers?: InitializedManagersMap;
+};
+
+export type PaymentMethodComponentProps = {
+  /**  */
+  type?: PaymentMethodType | undefined;
+  /**  */
+  paymentMethods?: PaymentsObject | null;
+};
+
+export type PrimerCheckoutCompleteComponentProps = {};
+
+export type PrimerCheckoutFailureComponentProps = {
+  /**  */
+  sdkState?: HeadlessSDKState | undefined;
+};
+
+export type PrimerMainComponentProps = {
+  /**  */
+  paymentMethods?: PaymentsObject | null;
+  /**  */
+  sdkState?: SdkStateContext | undefined;
+};
+
+export type RedirectPaymentComponentProps = {
+  /**  */
+  paymentMethod?: InitializedPaymentMethod | undefined;
+  /**  */
+  paymentManagers?: InitializedManagersMap;
+  /**  */
+  sdkState?: SdkStateContext | undefined;
+};
+
+export type CardFormSubmitComponentProps = {
+  /** The button text to display.
+Falls back to localized default if not explicitly set. */
+  buttonText?: string;
+  /** The button variant to use. */
+  variant?: string;
+  /** Whether the button is disabled. */
+  disabled?: boolean;
+};
+
+export type CardNetworkSelectorComponentProps = {
+  /** Card networks context from provider */
+  cardNetworks?: CardNetworksContext | null;
+  /** Dispatched when a network is selected with the network name as detail */
+  "onnetwork-selected"?: (e: CustomEvent<CustomEvent>) => void;
+};
+
+export type InputCardExpiryComponentProps = {
+  /** The input label text.
+Falls back to localized default if not explicitly set. */
+  label?: string;
+  /** The input placeholder text.
+Falls back to localized default if not explicitly set.
+When explicitly set to empty string, no placeholder will be displayed. */
+  placeholder?: string;
+  /** The input aria-label attribute.
+Falls back to localized default if not explicitly set. */
+  "aria-label"?: string;
+  /**  */
+  cardFormContext?: CardFormContext | null;
+};
+
+export type InputCardHolderNameComponentProps = {
+  /** The input label text.
+Falls back to localized default if not explicitly set. */
+  label?: string;
+  /** The input placeholder text.
+Falls back to localized default if not explicitly set.
+When explicitly set to empty string, no placeholder will be displayed. */
+  placeholder?: string;
+  /** The input aria-label attribute.
+Falls back to localized default if not explicitly set. */
+  "aria-label"?: string;
+  /**  */
+  cardFormContext?: CardFormContext | null;
+};
+
+export type InputCardNumberComponentProps = {
+  /** The input label text.
+Falls back to localized default if not explicitly set. */
+  label?: string;
+  /** The input placeholder text.
+Falls back to localized default if not explicitly set.
+When explicitly set to empty string, no placeholder will be displayed. */
+  placeholder?: string;
+  /** The input aria-label attribute.
+Falls back to localized default if not explicitly set. */
+  "aria-label"?: string;
+  /**  */
+  cardFormContext?: CardFormContext | null;
+};
+
+export type InputCvvComponentProps = {
+  /** The input label text.
+Falls back to localized default if not explicitly set. */
+  label?: string;
+  /** The input placeholder text.
+Falls back to localized default if not explicitly set.
+When explicitly set to empty string, no placeholder will be displayed. */
+  placeholder?: string;
+  /** The input aria-label attribute.
+Falls back to localized default if not explicitly set. */
+  "aria-label"?: string;
+  /**  */
+  cardFormContext?: CardFormContext | null;
+};
+
+export type CustomElements = {
+  /**
+   *
+   * ---
+   *
+   */
+  "primer-checkout": Partial<PrimerCheckoutComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   *
+   * ---
+   *
+   */
+  "primer-button": Partial<ButtonComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   *
+   * ---
+   *
+   */
+  "primer-checkout-state": Partial<PrimerCheckoutStateComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   *
+   * ---
+   *
+   */
+  "primer-icon": Partial<PrimerIconComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * A fully type-safe input component that wraps the native HTML input element
+   * while providing additional functionality and styling.
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **focus** - Fired when the input receives focus
+   * - **blur** - Fired when the input loses focus
+   * - **invalid** - Fired when the input fails validation
+   * - **input** - Fired when the input value changes
+   * - **change** - Fired when the input value is committed
+   *
+   * ### **Methods:**
+   *  - **focus(options: _FocusOptions_): _void_** - Focus the input element
+   * - **blur(): _void_** - Remove focus from the input element
+   * - **select(): _void_** - Select all text in the input element
+   * - **setSelectionRange(start: _number_, end: _number_, direction: _'forward' | 'backward' | 'none'_): _void_** - Set the selection range of the input element
+   * - **checkValidity(): _boolean_** - Check if the input element is valid
+   * - **reportValidity(): _boolean_** - Report the validity of the input element
+   * - **addEventListener(type: _K_, listener: _(ev: InputEventMap[K]) => void_, options: _boolean | AddEventListenerOptions_): _void_** - Type safe event dispatcher - allows consumers to use proper types
+   * when listening to events from this component
+   * - **removeEventListener(type: _K_, listener: _(ev: InputEventMap[K]) => void_, options: _boolean | EventListenerOptions_): _void_** - Type safe event dispatcher removal
+   *
+   * ### **CSS Parts:**
+   *  - **input** - The native input element
+   */
+  "primer-input": Partial<InputComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * Input error component for displaying form validation messages
+   * ---
+   *
+   *
+   * ### **Slots:**
+   *  - _default_ - Default slot for error message content
+   */
+  "primer-input-error": Partial<InputErrorComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * Input label component for form elements
+   * ---
+   *
+   *
+   * ### **Slots:**
+   *  - _default_ - Default slot for label text content
+   */
+  "primer-input-label": Partial<InputLabelComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * 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
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **wrapper-click**
+   */
+  "primer-input-wrapper": Partial<InputWrapperComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * Spinner component with configurable size and color
+   * Adapted to work both standalone and within input components
+   * ---
+   *
+   */
+  "primer-spinner": Partial<SpinnerComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * CardFormComponent serves as a container for card input components.
+   * It handles form submission, validation, and provides context to child components.
+   * ---
+   *
+   */
+  "primer-card-form": Partial<CardFormComponentProps & 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>;
+
+  /**
+   *
+   * ---
+   *
+   */
+  "primer-payment-method": Partial<PaymentMethodComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   *
+   * ---
+   *
+   */
+  "primer-checkout-complete": Partial<PrimerCheckoutCompleteComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   *
+   * ---
+   *
+   */
+  "primer-checkout-failure": Partial<PrimerCheckoutFailureComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   *
+   * ---
+   *
+   */
+  "primer-main": Partial<PrimerMainComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   *
+   * ---
+   *
+   */
+  "primer-redirect-payment": Partial<RedirectPaymentComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * A form submit button component for card forms.
+   * Provides a consistent submit button with translation support.
+   * ---
+   *
+   */
+  "primer-card-form-submit": Partial<CardFormSubmitComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * Component for displaying and selecting card networks
+   * Uses context directly rather than properties
+   * ---
+   *
+   *
+   * ### **Events:**
+   *  - **network-selected** - Dispatched when a network is selected with the network name as detail
+   */
+  "primer-card-network-selector": Partial<CardNetworkSelectorComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   *
+   * ---
+   *
+   *
+   * ### **Methods:**
+   *
+   *
+   */
+  "primer-input-card-expiry": Partial<InputCardExpiryComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   *
+   * ---
+   *
+   *
+   * ### **Methods:**
+   *
+   *
+   */
+  "primer-input-card-holder-name": Partial<InputCardHolderNameComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   * Card number input component with dynamic card network detection and selection
+   * ---
+   *
+   *
+   * ### **Methods:**
+   *
+   *
+   */
+  "primer-input-card-number": Partial<InputCardNumberComponentProps & BaseProps & BaseEvents>;
+
+  /**
+   *
+   * ---
+   *
+   *
+   * ### **Methods:**
+   *
+   *
+   */
+  "primer-input-cvv": Partial<InputCvvComponentProps & BaseProps & BaseEvents>;
+};