@getopenpay/openpay-js-react 0.0.2-beta.1 → 0.0.3-alpha.4e3a3ab

package/README.md

@@ -1,14 +1,65 @@
 # openpay-js-react
 
-React components for OpenPay.JS
+## Installation
 
-## Development
+```shell npm
+npm install @getopenpay/openpay-js-react
+```
 
-1. Install dependencies using `make install`
-2. Run `make dev` to start Vite in watch mode
-3. In another terminal, `cd` into the `example` directory and run `make dev` to start the example app
-4. Open [http://localhost:3032](http://localhost:3032) to see the example app
+```shell yarn
+yarn add @getopenpay/openpay-js-react
+```
 
-When you make changes to the library, Vite will automatically recompile it and NextJS will automatically reload the page.
+```shell pnpm
+pnpm add @getopenpay/openpay-js-react
+```
 
-If NextJS doesn't reload, you can try manually refreshing the page, or reinstalling the library using `npm install ../` in the `example` directory.
+## Usage
+
+See example usage here ([example usages](https://dash.readme.com/go/getopenpay?redirect=%2Fv1.0%2Fdocs%2Fexamples))
+
+## Concepts
+
+### Elements
+
+Elements are the embeds of secure web pages hosted on our servers. Elements must be used within the provider,`<ElementsForm />`, which provides context required by the elements.
+
+`<ElementsForm />` needs `checkoutSecureToken` which can be generated by creating a checkout session via OpenPay Python SDK. [Create Checkout Session](ref:create_checkout_session)
+
+The library provides separate card elements (Card number, expiry, CVV) and a combination these elements in a single line input field.
+
+- `<CardNumberElement />`
+- `<CardExpiryElement />`
+- `<CardCvcElement />`
+- `<CardElement />` (Combined)
+
+### Billing information
+
+Customer billing information is required to proceed checkout. You can implement the input fields for billing information in your own way. Since you're in control of these fields, you can perform custom validations, custom styling and auto-fill with user account information.  
+For OpenPay to access the input fields, please include `data-opid` attribute with predefined field names which can be accessed via `FieldName`.
+
+Available field names:
+
+- `FieldName.FIRST_NAME`
+- `FieldName.LAST_NAME`
+- `FieldName.EMAIL`
+- `FieldName.ZIP_CODE`
+- `FieldName.CITY`
+- `FieldName.STATE`
+- `FieldName.COUNTRY`
+- `FieldName.ADDRESS`
+- `FieldName.PHONE`
+
+### Styling
+
+By default, the elements provided are "Unstyled". They will have transparent background and text color adaptive to system's color scheme. You can wrap an element inside a container to which you can apply customized styling ([Examples](doc:examples)).
+
+If you want to customize the styling of the element itself you can apply via the optional `styles` prop. The following are supported properties. These support any valid CSS values.
+
+- `backgroundColor`
+- `color`
+- `fontFamily`
+- `fontSize`
+- `fontWeight`
+- `margin`
+- `padding`

package/dist/index.d.ts

@@ -1,147 +1,9 @@
 import { FC } from 'react';
 import { z } from 'zod';
 
-export declare const Appearance: z.ZodObject<{
-    theme: z.ZodEnum<[AppearanceTheme.UNSTYLED, AppearanceTheme.LIGHT, AppearanceTheme.DARK]>;
-    variables: z.ZodOptional<z.ZodObject<{
-        colorPrimary: z.ZodOptional<z.ZodString>;
-        colorBackground: z.ZodOptional<z.ZodString>;
-        colorForeground: z.ZodOptional<z.ZodString>;
-        colorText: z.ZodOptional<z.ZodString>;
-        colorDanger: z.ZodOptional<z.ZodString>;
-        fontFamily: z.ZodOptional<z.ZodString>;
-        fontSize: z.ZodOptional<z.ZodString>;
-        spacing: z.ZodOptional<z.ZodString>;
-        borderRadius: z.ZodOptional<z.ZodString>;
-        borderColor: z.ZodOptional<z.ZodString>;
-        borderWidth: z.ZodOptional<z.ZodString>;
-        focusRingColor: z.ZodOptional<z.ZodString>;
-        padding: z.ZodOptional<z.ZodString>;
-    }, "strip", z.ZodTypeAny, {
-        colorPrimary?: string | undefined;
-        colorBackground?: string | undefined;
-        colorForeground?: string | undefined;
-        colorText?: string | undefined;
-        colorDanger?: string | undefined;
-        fontFamily?: string | undefined;
-        fontSize?: string | undefined;
-        spacing?: string | undefined;
-        borderRadius?: string | undefined;
-        borderColor?: string | undefined;
-        borderWidth?: string | undefined;
-        focusRingColor?: string | undefined;
-        padding?: string | undefined;
-    }, {
-        colorPrimary?: string | undefined;
-        colorBackground?: string | undefined;
-        colorForeground?: string | undefined;
-        colorText?: string | undefined;
-        colorDanger?: string | undefined;
-        fontFamily?: string | undefined;
-        fontSize?: string | undefined;
-        spacing?: string | undefined;
-        borderRadius?: string | undefined;
-        borderColor?: string | undefined;
-        borderWidth?: string | undefined;
-        focusRingColor?: string | undefined;
-        padding?: string | undefined;
-    }>>;
-}, "strip", z.ZodTypeAny, {
-    theme: AppearanceTheme;
-    variables?: {
-        colorPrimary?: string | undefined;
-        colorBackground?: string | undefined;
-        colorForeground?: string | undefined;
-        colorText?: string | undefined;
-        colorDanger?: string | undefined;
-        fontFamily?: string | undefined;
-        fontSize?: string | undefined;
-        spacing?: string | undefined;
-        borderRadius?: string | undefined;
-        borderColor?: string | undefined;
-        borderWidth?: string | undefined;
-        focusRingColor?: string | undefined;
-        padding?: string | undefined;
-    } | undefined;
-}, {
-    theme: AppearanceTheme;
-    variables?: {
-        colorPrimary?: string | undefined;
-        colorBackground?: string | undefined;
-        colorForeground?: string | undefined;
-        colorText?: string | undefined;
-        colorDanger?: string | undefined;
-        fontFamily?: string | undefined;
-        fontSize?: string | undefined;
-        spacing?: string | undefined;
-        borderRadius?: string | undefined;
-        borderColor?: string | undefined;
-        borderWidth?: string | undefined;
-        focusRingColor?: string | undefined;
-        padding?: string | undefined;
-    } | undefined;
-}>;
+declare const AllFieldNames: z.ZodUnion<[z.ZodNativeEnum<typeof FieldName>, z.ZodNativeEnum<typeof PrivateFieldName>]>;
 
-export declare type Appearance = z.infer<typeof Appearance>;
-
-/**
- * Models shared between CDE and OpenPay.js
- * Don't forget to update shared-models.ts in the other repo's utils folder too!
- */
-/**
- * Styles and appearance
- */
-export declare enum AppearanceTheme {
-    UNSTYLED = "unstyled",
-    LIGHT = "light",
-    DARK = "dark"
-}
-
-export declare const AppearanceVariables: z.ZodObject<{
-    colorPrimary: z.ZodOptional<z.ZodString>;
-    colorBackground: z.ZodOptional<z.ZodString>;
-    colorForeground: z.ZodOptional<z.ZodString>;
-    colorText: z.ZodOptional<z.ZodString>;
-    colorDanger: z.ZodOptional<z.ZodString>;
-    fontFamily: z.ZodOptional<z.ZodString>;
-    fontSize: z.ZodOptional<z.ZodString>;
-    spacing: z.ZodOptional<z.ZodString>;
-    borderRadius: z.ZodOptional<z.ZodString>;
-    borderColor: z.ZodOptional<z.ZodString>;
-    borderWidth: z.ZodOptional<z.ZodString>;
-    focusRingColor: z.ZodOptional<z.ZodString>;
-    padding: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    colorPrimary?: string | undefined;
-    colorBackground?: string | undefined;
-    colorForeground?: string | undefined;
-    colorText?: string | undefined;
-    colorDanger?: string | undefined;
-    fontFamily?: string | undefined;
-    fontSize?: string | undefined;
-    spacing?: string | undefined;
-    borderRadius?: string | undefined;
-    borderColor?: string | undefined;
-    borderWidth?: string | undefined;
-    focusRingColor?: string | undefined;
-    padding?: string | undefined;
-}, {
-    colorPrimary?: string | undefined;
-    colorBackground?: string | undefined;
-    colorForeground?: string | undefined;
-    colorText?: string | undefined;
-    colorDanger?: string | undefined;
-    fontFamily?: string | undefined;
-    fontSize?: string | undefined;
-    spacing?: string | undefined;
-    borderRadius?: string | undefined;
-    borderColor?: string | undefined;
-    borderWidth?: string | undefined;
-    focusRingColor?: string | undefined;
-    padding?: string | undefined;
-}>;
-
-export declare type AppearanceVariables = z.infer<typeof AppearanceVariables>;
+declare type AllFieldNames = z.infer<typeof AllFieldNames>;
 
 export declare const CardCvcElement: FC<ElementProps>;
 
@@ -151,16 +13,16 @@ export declare const CardExpiryElement: FC<ElementProps>;
 
 export declare const CardNumberElement: FC<ElementProps>;
 
-declare type ElementProps = {
+export declare type ElementProps = {
     styles?: ElementsStyle;
 };
 
 declare type ElementsContextValue = {
-    contextId: string;
+    formId: string;
     formHeight: string;
     referer?: string;
     checkoutSecureToken?: string;
-    appearance?: Appearance;
+    registerIframe: (iframe: HTMLIFrameElement) => void;
 };
 
 export declare const ElementsForm: FC<ElementsFormProps>;
@@ -169,22 +31,24 @@ declare type ElementsFormChildrenProps = {
     submit: () => void;
 };
 
-declare type ElementsFormProps = {
+export declare type ElementsFormProps = {
     className?: string;
-    appearance?: Appearance;
     checkoutSecureToken?: string;
     children: (props: ElementsFormChildrenProps) => JSX.Element;
     onFocus?: (elementId: string) => void;
     onBlur?: (elementId: string) => void;
     onChange?: (elementId: string) => void;
-    onLoad?: (totalAmountAtoms: number) => void;
+    onLoad?: (totalAmountAtoms: number, currency?: string) => void;
     onLoadError?: (message: string) => void;
-    onValidationError?: (message: string, elementId?: string) => void;
+    onValidationError?: (field: AllFieldNames, errors: string[], elementId?: string) => void;
     onCheckoutStarted?: () => void;
     onCheckoutSuccess?: (invoiceUrls: string[]) => void;
     onCheckoutError?: (message: string) => void;
 };
 
+/**
+ * Styles
+ */
 declare const ElementsStyle: z.ZodObject<{
     backgroundColor: z.ZodOptional<z.ZodString>;
     color: z.ZodOptional<z.ZodString>;
@@ -194,27 +58,27 @@ declare const ElementsStyle: z.ZodObject<{
     margin: z.ZodOptional<z.ZodString>;
     padding: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    fontFamily?: string | undefined;
-    fontSize?: string | undefined;
-    padding?: string | undefined;
     backgroundColor?: string | undefined;
     color?: string | undefined;
-    fontWeight?: string | undefined;
-    margin?: string | undefined;
-}, {
     fontFamily?: string | undefined;
     fontSize?: string | undefined;
+    fontWeight?: string | undefined;
+    margin?: string | undefined;
     padding?: string | undefined;
+}, {
     backgroundColor?: string | undefined;
     color?: string | undefined;
+    fontFamily?: string | undefined;
+    fontSize?: string | undefined;
     fontWeight?: string | undefined;
     margin?: string | undefined;
+    padding?: string | undefined;
 }>;
 
 declare type ElementsStyle = z.infer<typeof ElementsStyle>;
 
 /**
- * Form field names
+ * Expected input fields
  */
 export declare enum FieldName {
     FIRST_NAME = "firstName",
@@ -228,6 +92,12 @@ export declare enum FieldName {
     PHONE = "phone"
 }
 
+declare enum PrivateFieldName {
+    CARD_NUMBER = "cardNumber",
+    CARD_EXPIRY = "cardExpiry",
+    CARD_CVC = "cardCvc"
+}
+
 export declare const useOpenPayElements: () => ElementsContextValue;
 
 export { }