@getopenpay/openpay-js-react 0.0.2 → 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

@@ -0,0 +1,103 @@
+import { FC } from 'react';
+import { z } from 'zod';
+
+declare const AllFieldNames: z.ZodUnion<[z.ZodNativeEnum<typeof FieldName>, z.ZodNativeEnum<typeof PrivateFieldName>]>;
+
+declare type AllFieldNames = z.infer<typeof AllFieldNames>;
+
+export declare const CardCvcElement: FC<ElementProps>;
+
+export declare const CardElement: FC<ElementProps>;
+
+export declare const CardExpiryElement: FC<ElementProps>;
+
+export declare const CardNumberElement: FC<ElementProps>;
+
+export declare type ElementProps = {
+    styles?: ElementsStyle;
+};
+
+declare type ElementsContextValue = {
+    formId: string;
+    formHeight: string;
+    referer?: string;
+    checkoutSecureToken?: string;
+    registerIframe: (iframe: HTMLIFrameElement) => void;
+};
+
+export declare const ElementsForm: FC<ElementsFormProps>;
+
+declare type ElementsFormChildrenProps = {
+    submit: () => void;
+};
+
+export declare type ElementsFormProps = {
+    className?: string;
+    checkoutSecureToken?: string;
+    children: (props: ElementsFormChildrenProps) => JSX.Element;
+    onFocus?: (elementId: string) => void;
+    onBlur?: (elementId: string) => void;
+    onChange?: (elementId: string) => void;
+    onLoad?: (totalAmountAtoms: number, currency?: string) => void;
+    onLoadError?: (message: 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>;
+    fontFamily: z.ZodOptional<z.ZodString>;
+    fontSize: z.ZodOptional<z.ZodString>;
+    fontWeight: z.ZodOptional<z.ZodString>;
+    margin: z.ZodOptional<z.ZodString>;
+    padding: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    backgroundColor?: string | undefined;
+    color?: 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>;
+
+/**
+ * Expected input fields
+ */
+export declare enum FieldName {
+    FIRST_NAME = "firstName",
+    LAST_NAME = "lastName",
+    EMAIL = "email",
+    ZIP_CODE = "zipCode",
+    CITY = "city",
+    STATE = "state",
+    COUNTRY = "country",
+    ADDRESS = "address",
+    PHONE = "phone"
+}
+
+declare enum PrivateFieldName {
+    CARD_NUMBER = "cardNumber",
+    CARD_EXPIRY = "cardExpiry",
+    CARD_CVC = "cardCvc"
+}
+
+export declare const useOpenPayElements: () => ElementsContextValue;
+
+export { }