Merge pull request #823 from paypal/feature/ppcpsdk-4152-card-fields-components

Created card fields components

Author: AleGastelum

.changeset/cold-regions-rescue.md

@@ -0,0 +1,5 @@
+---
+"@paypal/react-paypal-js": minor
+---
+
+Created V6 React Card Field components for each field type

.changeset/quick-chefs-occur.md

@@ -0,0 +1,5 @@
+---
+"@paypal/paypal-js": minor
+---
+
+Updated V6 card fields types to include session and field destroy methods

packages/paypal-js/types/v6/components/card-fields.d.ts

@@ -135,6 +135,27 @@ export type CardFieldOptions = {
 
 export type StateType = "canceled" | "failed" | "succeeded";
 
+export type CardFieldComponent = HTMLElement & {
+    /**
+     * Use this method to destroy the Card Field component and clean up any associated resources. After calling this method, the Card Field component will no longer be usable.
+     * 
+     * @example
+     * ```typescript
+     * const numberField = cardFieldsInstance.createCardFieldsComponent({
+            type: "number",
+            placeholder: "Enter a number",
+        });
+        document
+            .querySelector("#paypal-card-fields-number-container")
+            .appendChild(numberField);
+            
+        // Later, when you want to clean up:
+        numberField.destroy();
+    * ```
+    */
+    destroy(): void;
+};
+
 type BaseCardFieldsSession = {
     /**
      * Use this method to create and configure individual Card Field components.
@@ -153,7 +174,7 @@ type BaseCardFieldsSession = {
           .appendChild(numberField);
      * ```
      */
-    createCardFieldsComponent: (config: CardFieldOptions) => HTMLElement;
+    createCardFieldsComponent: (config: CardFieldOptions) => CardFieldComponent;
     /**
      * Use this method to register event listeners and set callbacks for them.
      * 
@@ -187,6 +208,15 @@ type BaseCardFieldsSession = {
      * ```
      */
     update: (options: UpdateOptions) => void;
+    /**
+     * Use this method to destroy the Card Fields session instance and clean up any associated resources. After calling this method, the Card Fields session instance will no longer be usable.
+     *
+     * @example
+     * ```typescript
+     * cardFieldsInstance.destroy();
+     * ```
+     */
+    destroy: () => void;
 };
 
 export type OneTimePaymentFlowResponse = {

packages/react-paypal-js/src/v6/components/PayPalCardCvvField.test.tsx

@@ -0,0 +1,49 @@
+import React from "react";
+import { render } from "@testing-library/react";
+
+import { PayPalCardCvvField } from "./PayPalCardCvvField";
+import { PayPalCardField } from "./PayPalCardField";
+
+jest.mock("./PayPalCardField", () => ({
+    PayPalCardField: jest.fn(() => <div data-testid="mock-card-field" />),
+}));
+
+const mockPayPalCardField = PayPalCardField as jest.MockedFunction<
+    typeof PayPalCardField
+>;
+
+const fieldType = "cvv";
+
+describe("PayPalCardCvvField", () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it("Should pass type='cvv' to PayPalCardField", () => {
+        render(<PayPalCardCvvField />);
+        expect(mockPayPalCardField.mock.calls[0][0]).toEqual(
+            expect.objectContaining({ type: fieldType }),
+        );
+    });
+
+    it("should render PayPalCardField with the correct props", () => {
+        const testProps = {
+            placeholder: "Enter CVV",
+            containerClassName: "test-container",
+            style: {
+                input: {
+                    background: "lightgray",
+                },
+            },
+        };
+
+        render(<PayPalCardCvvField {...testProps} />);
+
+        expect(mockPayPalCardField.mock.calls[0][0]).toEqual(
+            expect.objectContaining({
+                type: fieldType,
+                ...testProps,
+            }),
+        );
+    });
+});

packages/react-paypal-js/src/v6/components/PayPalCardCvvField.tsx

@@ -0,0 +1,46 @@
+import React from "react";
+
+import { PayPalCardField } from "./PayPalCardField";
+
+import type { CardFieldOptions } from "../types";
+import type { PayPalCardFieldsProvider } from "./PayPalCardFieldsProvider";
+
+type PayPalCardCvvFieldProps = Omit<CardFieldOptions, "type"> & {
+    containerStyles?: React.CSSProperties;
+    containerClassName?: string;
+};
+
+/**
+ * `PayPalCardCvvField` is a component that renders a CVV field using the PayPal Card Fields SDK. It must be used within a {@link PayPalCardFieldsProvider} component.
+ *
+ * @example
+ * // Basic usage creating a CVV field
+ * <PayPalCardCvvField
+ *   placeholder="Enter CVV"
+ *   containerStyles={{ height: "3rem", marginBottom: "1rem" }}
+ * />
+ */
+export const PayPalCardCvvField = ({
+    containerStyles,
+    containerClassName,
+    placeholder,
+    label,
+    style,
+    ariaDescription,
+    ariaLabel,
+    ariaInvalidErrorMessage,
+}: PayPalCardCvvFieldProps): JSX.Element | null => {
+    return (
+        <PayPalCardField
+            type="cvv"
+            containerStyles={containerStyles}
+            containerClassName={containerClassName}
+            placeholder={placeholder}
+            label={label}
+            style={style}
+            ariaDescription={ariaDescription}
+            ariaLabel={ariaLabel}
+            ariaInvalidErrorMessage={ariaInvalidErrorMessage}
+        />
+    );
+};

packages/react-paypal-js/src/v6/components/PayPalCardExpiryField.test.tsx

@@ -0,0 +1,49 @@
+import React from "react";
+import { render } from "@testing-library/react";
+
+import { PayPalCardExpiryField } from "./PayPalCardExpiryField";
+import { PayPalCardField } from "./PayPalCardField";
+
+jest.mock("./PayPalCardField", () => ({
+    PayPalCardField: jest.fn(() => <div data-testid="mock-card-field" />),
+}));
+
+const mockPayPalCardField = PayPalCardField as jest.MockedFunction<
+    typeof PayPalCardField
+>;
+
+const fieldType = "expiry";
+
+describe("PayPalCardExpiryField", () => {
+    beforeEach(() => {
+        jest.clearAllMocks();
+    });
+
+    it("Should pass type='expiry' to PayPalCardField", () => {
+        render(<PayPalCardExpiryField />);
+        expect(mockPayPalCardField.mock.calls[0][0]).toEqual(
+            expect.objectContaining({ type: fieldType }),
+        );
+    });
+
+    it("should render PayPalCardField with the correct props", () => {
+        const testProps = {
+            placeholder: "Enter expiry date",
+            containerClassName: "test-container",
+            style: {
+                input: {
+                    background: "lightgray",
+                },
+            },
+        };
+
+        render(<PayPalCardExpiryField {...testProps} />);
+
+        expect(mockPayPalCardField.mock.calls[0][0]).toEqual(
+            expect.objectContaining({
+                type: fieldType,
+                ...testProps,
+            }),
+        );
+    });
+});

packages/react-paypal-js/src/v6/components/PayPalCardExpiryField.tsx

@@ -0,0 +1,46 @@
+import React from "react";
+
+import { PayPalCardField } from "./PayPalCardField";
+
+import type { CardFieldOptions } from "../types";
+import type { PayPalCardFieldsProvider } from "./PayPalCardFieldsProvider";
+
+type PayPalCardExpiryFieldProps = Omit<CardFieldOptions, "type"> & {
+    containerStyles?: React.CSSProperties;
+    containerClassName?: string;
+};
+
+/**
+ * `PayPalCardExpiryField` is a component that renders an expiry field using the PayPal Card Fields SDK. It must be used within a {@link PayPalCardFieldsProvider} component.
+ *
+ * @example
+ * // Basic usage creating an expiry field
+ * <PayPalCardExpiryField
+ *   placeholder="Enter an expiry date"
+ *   containerStyles={{ height: "3rem", marginBottom: "1rem" }}
+ * />
+ */
+export const PayPalCardExpiryField = ({
+    containerStyles,
+    containerClassName,
+    placeholder,
+    label,
+    style,
+    ariaDescription,
+    ariaLabel,
+    ariaInvalidErrorMessage,
+}: PayPalCardExpiryFieldProps): JSX.Element | null => {
+    return (
+        <PayPalCardField
+            type="expiry"
+            containerStyles={containerStyles}
+            containerClassName={containerClassName}
+            placeholder={placeholder}
+            label={label}
+            style={style}
+            ariaDescription={ariaDescription}
+            ariaLabel={ariaLabel}
+            ariaInvalidErrorMessage={ariaInvalidErrorMessage}
+        />
+    );
+};