From 1125b92b4bc3b562cb322c2d8df4a5ce4d2f1a51 Mon Sep 17 00:00:00 2001 From: priyankakmEaton Date: Fri, 19 Apr 2024 15:58:48 +0530 Subject: [PATCH 1/2] type docs --- login-workflow/docs/API.md | 99 ++++++++++--------- login-workflow/docs/migration-guide-3-4.md | 4 +- login-workflow/docs/registration-workflow.md | 63 ++++++------ .../src/actions/RegistrationUIActions.tsx | 5 +- 4 files changed, 86 insertions(+), 85 deletions(-) diff --git a/login-workflow/docs/API.md b/login-workflow/docs/API.md index 2d1b0097..8a88ee62 100644 --- a/login-workflow/docs/API.md +++ b/login-workflow/docs/API.md @@ -1,39 +1,43 @@ # API + This document outlines the various exports and configuration options for the React Auth Workflow package. ## RegistrationContextProviderProps + The `RegistrationContextProvider` manages the state of the registration workflow. It is a React Context Provider that wraps the entire registration workflow. It is responsible for managing the state of the registration workflow and providing the necessary actions to the various screens. The `RegistrationContextProviderProps` type is used to configure the `RegistrationContextProvider`. ### Type Declaration -- **actions**: _`RegistrationUIActions`_ + +- **actions**: _`RegistrationUIActions`_ - Returns an object of functions that are used to manage the registration workflow. See [RegistrationUIActions](#registrationuiactions) for more information. -- **language**: _`string`_ +- **language**: _`string`_ - The language code to use for the registration workflow. This is used to determine which language to use for the UI and for the API calls. -- **navigate**: _`(destination: -1 | string) => void`_ +- **navigate**: _`(destination: -1 | string) => void`_ - A function that is used to navigate to a new URL. This is used to navigate to the various screens of the registration workflow and destination: -1 navigates back to the previous screen the user last visited. -- **routeConfig**: _`RouteConfig`_ +- **routeConfig**: _`RouteConfig`_ - An object that defines the various routes for the registration workflow. See [RouteConfig](#routeconfig) for more information. -- **i18n**: (optional) _`i18n`_ +- **i18n**: (optional) _`i18n`_ - An optional i18n object that is used to translate the UI. If not provided, the default i18n object will be used. -- **errorConfig**: (optional) _`ErrorContextProviderProps`_ +- **errorConfig**: (optional) _`ErrorContextProviderProps`_ - An optional object that is used to configure the error handling of the registration workflow. See [ErrorContextProviderProps](#errorcontextproviderprops) for more information. ## RegistrationUIActions ### Type Declaration -- **loadEula**: _`(language: string) => Promise`_ + +- **loadEula**: _`(language: string) => Promise`_ - A function that is used to load the EULA. This function will be called when the user lands on the EULA screen. -- **acceptEula**: _`() => Promise`_ +- **acceptEula**: _`() => Promise`_ - A function that is used to accept the EULA. This function will be called when the user clicks the Next button on the EULA screen. -- **requestRegistrationCode**: _`(email: string) => Promise`_ +- **requestRegistrationCode**: _`(email: string) => Promise`_ - A function that is used to request a registration code. This function will be called when the user lands on the Verify Code screen as well as when a user clicks the Resend Verification Code button. -- **validateUserRegistrationRequest**: _`(validationCode: string, validationEmail?: string) => Promise<{codeValid: boolean | string; accountExists?: boolean}>`_ +- **validateUserRegistrationRequest**: _`(validationCode: string, validationEmail?: string) => Promise<{codeValid: boolean | string; accountExists?: boolean}>`_ - A function that is used to validate a registration code. This function will be called when the user clicks the Next button on the Verify Code screen screen. -- **createPassword**: _`(password: string) => Promise`_ +- **createPassword**: _`(password: string) => Promise`_ - A function that is used to create a password. This function will be called when the user clicks the Next button on the Create Password screen. -- **setAccountDetails**: _`(details: AccountDetails) => Promise`_ +- **setAccountDetails**: _`(details: AccountDetails) => Promise`_ - A function that is used to set the account details. This function will be called when the user clicks the Next button on the Account Details screen. -- **completeRegistration**: _`(userData: any, validationCode: number | string, validationEmail: string) => Promise<{ email: string, organizationName: string }>`_ +- **completeRegistration**: _`(userData: object) => Promise<{ email: string, organizationName: string }>`_ - A function that is used to complete the registration. This function will be called when the user clicks the Next button on the final registration workflow screen. ## RouteConfig @@ -56,62 +60,69 @@ Type to represent the customizable route configuration of the authentication scr - The URL path for the Contact/Support screen ## ErrorContextProviderProps + The `ErrorContextProvider` manages the state of the error handling. It is a React Context Provider that is embedded into the entire authentication workflow. It is responsible for managing the state of the error handling and providing the necessary actions to the various screens. The `ErrorContextProviderProps` type is used to configure the `ErrorContextProvider`. ### Type Declaration -- **mode**: (default: "dialog") _`"dialog" | "message-box" | "none"`_ + +- **mode**: (default: "dialog") _`"dialog" | "message-box" | "none"`_ - The mode to use for displaying errors. If set to "dialog", errors will be displayed in a dialog. If set to "message-box", errors will be displayed in a message box. If set to "none", errors will not be displayed. -- **onClose**: (optional) _`() => void`_ +- **onClose**: (optional) _`() => void`_ - A function that is called when the error dialog is closed. -- **dialogConfig**: (optional) _`{ title?: string, dismissLabel?: string }`_ +- **dialogConfig**: (optional) _`{ title?: string, dismissLabel?: string }`_ - An optional object that is used to configure the error dialog. See [DialogConfig](#dialogconfig) for more information. -- **messageBoxConfig**: (optional) _`{ dismissible?: boolean, position?: "top" | "bottom", fontColor?: string, backgroundColor?: string, sx?: SxProps }`_ +- **messageBoxConfig**: (optional) _`{ dismissible?: boolean, position?: "top" | "bottom", fontColor?: string, backgroundColor?: string, sx?: SxProps }`_ - An optional object that is used to configure the error message box. See [MessageBoxConfig](#messageboxconfig) for more information. - + ## DialogConfig + Type to represent the customizable configuration of the error dialog. ### Type Declaration -- **title**: (optional) _`string`_ + +- **title**: (optional) _`string`_ - The title to display in the error dialog. -- **dismissLabel**: (optional) _`string`_ +- **dismissLabel**: (optional) _`string`_ - The label to display on the dismiss button in the error dialog. ## MessageBoxConfig + Type to represent the customizable configuration of the error message box. ### Type Declaration -- **dismissible**: (default: true) _`boolean`_ + +- **dismissible**: (default: true) _`boolean`_ - Determines if the error message box can be dismissed. -- **position**: (default: "top") _`"top" | "bottom"`_ +- **position**: (default: "top") _`"top" | "bottom"`_ - Determines if the error message box should be displayed at the top or bottom of the screen. -- **fontColor**: (default: "#ffffff") _`string`_ +- **fontColor**: (default: "#ffffff") _`string`_ - The font color to use for the error message box. -- **backgroundColor**: (default: theme.palette.error.main) _`string`_ +- **backgroundColor**: (default: theme.palette.error.main) _`string`_ - The background color to use for the error message box. ## Components -Exported components that can be used to customize the auth workflow. +Exported components that can be used to customize the auth workflow. + +- [BasicDialog](./components/basic-dialog.md) +- [ChangePasswordDialog](./components/change-password-dialog.md) +- [ErrorManager](./components/error-manager.md) +- [PasswordTextField](./components/password-text-field.md) +- [RegistrationWorkflow](./components/registration-workflow.md) +- [SetPassword](./components/set-password.md) +- [WorkflowCard](./components/workflow-card.md) -- [BasicDialog](./components/basic-dialog.md) -- [ChangePasswordDialog](./components/change-password-dialog.md) -- [ErrorManager](./components/error-manager.md) -- [PasswordTextField](./components/password-text-field.md) -- [RegistrationWorkflow](./components/registration-workflow.md) -- [SetPassword](./components/set-password.md) -- [WorkflowCard](./components/workflow-card.md) ## Screens -Exported screens that can be used to customize the auth workflow. - -- [AccountDetailsScreen](./screens/account-details.md) -- [ContactScreen](./screens/contact.md) -- [CreateAccountScreen](./screens/create-account.md) -- [CreatePasswordScreen](./screens/create-password.md) -- [EulaScreen](./screens/eula.md) -- [ForgotPasswordScreen](./screens/forgot-password.md) -- [LoginScreen](./screens/login.md) -- [ResetPasswordScreen](./screens/reset-password.md) -- [SuccessScreen](./screens/success.md) -- [VerifyCodeScreen](./screens/verify-code.md) \ No newline at end of file +Exported screens that can be used to customize the auth workflow. + +- [AccountDetailsScreen](./screens/account-details.md) +- [ContactScreen](./screens/contact.md) +- [CreateAccountScreen](./screens/create-account.md) +- [CreatePasswordScreen](./screens/create-password.md) +- [EulaScreen](./screens/eula.md) +- [ForgotPasswordScreen](./screens/forgot-password.md) +- [LoginScreen](./screens/login.md) +- [ResetPasswordScreen](./screens/reset-password.md) +- [SuccessScreen](./screens/success.md) +- [VerifyCodeScreen](./screens/verify-code.md) diff --git a/login-workflow/docs/migration-guide-3-4.md b/login-workflow/docs/migration-guide-3-4.md index 5b84486e..abb432ea 100644 --- a/login-workflow/docs/migration-guide-3-4.md +++ b/login-workflow/docs/migration-guide-3-4.md @@ -80,9 +80,7 @@ completeRegistration: async ( // after completeRegistration: async ( - userData: any, // TODO: this should be properly typed - validationCode: string | number, - validationEmail?: string + userData: object, ): Promise<{ email: string; organizationName: string }> => { ... }, diff --git a/login-workflow/docs/registration-workflow.md b/login-workflow/docs/registration-workflow.md index cd320f56..1581e095 100644 --- a/login-workflow/docs/registration-workflow.md +++ b/login-workflow/docs/registration-workflow.md @@ -7,6 +7,7 @@ The registration workflow includes screens related to user sign-up / registratio The screens in this workflow access shared data / configuration / API definitions through a `RegistrationContextProvider` which should wrap all of the relevant routes / screens. You must supply the `AuthContextProvider` with the following props / data: + - `actions`: defines the API calls / functions to execute when certain actions are performed in the UI (such as submitting the password form) - `language`: configures the language displayed on the screens - `navigate`: a function that can be called to navigate to a new route @@ -24,7 +25,7 @@ The example project includes a skeleton implementation of all required functions - This file will handle the implementation of the registration related actions (such as create password, verify code, and create account). - You can copy this file directly from the [example](../example/src/actions/RegistrationUIActions.tsx) project as a starting point and then update the implementation details if you choose. 2. You might also want to copy over the `example/src/store` and `example/src/constants` folders, which provide a very basic mechanism for storing important data using LocalStorage - - You will want to switch this out for a more secure approach before going to production with your application. + - You will want to switch this out for a more secure approach before going to production with your application. ## Example Usage @@ -37,12 +38,7 @@ The Registration Workflow is made available as a single-page, multi-step compone {/* Wrap all routes in a single shared RegistrationContextProvider */} + } @@ -61,37 +57,36 @@ For a detailed explanation of setting up routes, see the [Routing](./routing.md) ### RegistrationContextProviderProps - - -| Prop Name | Type | Description | Default | -|---|---|---|---| -| actions* | `RegistrationUIActions` | An object of functions that are used to manage the authentication workflow. See [RegistrationUIActions](#registrationuiactions) for more information | | -| language* | `string` | The language code specifying which language to use for the UI | `'en'` | -| navigate* | `(url: string) => void` | A function that is used to navigate to a new URL. This is used to navigate to the various screens of the workflow. | | -| routeConfig* | `RouteConfig` | An object that defines the various routes for the workflow. See [RouteConfig](#routeconfig) for more information. | | -| i18n | `i18n` | An optional i18n object that is used to translate the UI. This is only needed if you want to use custom translation keys / languages inside any of the workflow screens | | -| errorConfig | `ErrorContextProviderProps` | An object that is used to configure error handling within the workflow. See [Error Management](./error-management.md) for more information. | | +| Prop Name | Type | Description | Default | +| ------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | +| actions\* | `RegistrationUIActions` | An object of functions that are used to manage the authentication workflow. See [RegistrationUIActions](#registrationuiactions) for more information | | +| language\* | `string` | The language code specifying which language to use for the UI | `'en'` | +| navigate\* | `(url: string) => void` | A function that is used to navigate to a new URL. This is used to navigate to the various screens of the workflow. | | +| routeConfig\* | `RouteConfig` | An object that defines the various routes for the workflow. See [RouteConfig](#routeconfig) for more information. | | +| i18n | `i18n` | An optional i18n object that is used to translate the UI. This is only needed if you want to use custom translation keys / languages inside any of the workflow screens | | +| errorConfig | `ErrorContextProviderProps` | An object that is used to configure error handling within the workflow. See [Error Management](./error-management.md) for more information. | | ### RegistrationUIActions -| Prop Name | Type | Description | Default | -|---|---|---|---| -| loadEula | `(language: string) => Promise` | A function that is used to load the Eula content. This function will be called when the Eula screen is loaded. | | -| acceptEula | `() => Promise` | A function that is called when the user has accepted the Eula and hit the Next button. | | -| requestRegistrationCode | `(email: string) => Promise` | A function that is used to request a registration code. This function will be called when the user clicks the Next button on the Create Account screen or Resend button on Verify Code screen. | | -| validateUserRegistrationRequest | `(validationCode: string, validationEmail?: string) => Promise<{codeValid: boolean | string; accountExists?: boolean}>` | A function that is used to verify registration code. This function will be called when the user clicks the Next button on the Verify Code screen. | | -| createPassword | `(password: string) => Promise` | A function that is used to create password. This function will be called when the user clicks the Next button on the Create Password screen. | | -| setAccountDetails | `(details: { firstName: string; lastName: string; extra?: { [key: string]: boolean \| string \| number }}) => Promise` | A function that is used to set account details. This function will be called when the user clicks the Next button on the Account Details screen. | | -| completeRegistration | `(userData: any, validationCode: number \| string, validationEmail: string) => Promise<{ email: string; organizationName: string }>` | A function that is used to complete the registration workflow. This function will be called when the user clicks the Next button on the last registration workflow screen. | | +| Prop Name | Type | Description | Default | +| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --- | +| loadEula | `(language: string) => Promise` | A function that is used to load the Eula content. This function will be called when the Eula screen is loaded. | | +| acceptEula | `() => Promise` | A function that is called when the user has accepted the Eula and hit the Next button. | | +| requestRegistrationCode | `(email: string) => Promise` | A function that is used to request a registration code. This function will be called when the user clicks the Next button on the Create Account screen or Resend button on Verify Code screen. | | +| validateUserRegistrationRequest | `(validationCode: string, validationEmail?: string) => Promise<{codeValid: boolean | string; accountExists?: boolean}>` | A function that is used to verify registration code. This function will be called when the user clicks the Next button on the Verify Code screen. | | +| createPassword | `(password: string) => Promise` | A function that is used to create password. This function will be called when the user clicks the Next button on the Create Password screen. | | +| setAccountDetails | `(details: { firstName: string; lastName: string; extra?: { [key: string]: boolean \| string \| number }}) => Promise` | A function that is used to set account details. This function will be called when the user clicks the Next button on the Account Details screen. | | +| completeRegistration | `(userData: object) => Promise<{ email: string; organizationName: string }>` | A function that is used to complete the registration workflow. This function will be called when the user clicks the Next button on the last registration workflow screen. | | ### RouteConfig + The RouteConfig is an object that specifies the paths you are using for the routes / screens in your application to facilitate navigating between screens within the workflows. -| Key | Type | Description | Default | -|---|---|---|---| -| LOGIN | `string` | The URL path for the Login screen | | -| FORGOT_PASSWORD | `string` | The URL path for the Forgot Password screen | | -| RESET_PASSWORD | `string` | The URL path for the Reset Password screen | | -| REGISTER_INVITE | `string` | The URL path for the invitation-based registration workflow | | -| REGISTER_SELF | `string` | The URL path for the self-registration workflow | | -| SUPPORT | `string` | The URL path for the Contact/Support screen | | +| Key | Type | Description | Default | +| --------------- | -------- | ----------------------------------------------------------- | ------- | +| LOGIN | `string` | The URL path for the Login screen | | +| FORGOT_PASSWORD | `string` | The URL path for the Forgot Password screen | | +| RESET_PASSWORD | `string` | The URL path for the Reset Password screen | | +| REGISTER_INVITE | `string` | The URL path for the invitation-based registration workflow | | +| REGISTER_SELF | `string` | The URL path for the self-registration workflow | | +| SUPPORT | `string` | The URL path for the Contact/Support screen | | diff --git a/login-workflow/example-vite/src/actions/RegistrationUIActions.tsx b/login-workflow/example-vite/src/actions/RegistrationUIActions.tsx index 200b593b..87454cb4 100644 --- a/login-workflow/example-vite/src/actions/RegistrationUIActions.tsx +++ b/login-workflow/example-vite/src/actions/RegistrationUIActions.tsx @@ -92,10 +92,7 @@ export const ProjectRegistrationUIActions: () => RegistrationUIActions = () => ( * @returns Resolves when the code is valid. True if registration is complete, False if account information is needed. * If the code is not valid a rejection will occur with an error message. */ - validateUserRegistrationRequest: async ( - validationCode: string, - validationEmail?: string - ): Promise<{ codeValid: boolean | string; accountExists?: boolean }> => { + validateUserRegistrationRequest: async (): Promise<{ codeValid: boolean | string; accountExists?: boolean }> => { await sleep(800); if (isRandomFailure()) { From ed9268ca7356fc9cb259bdb266829e8c206bdd43 Mon Sep 17 00:00:00 2001 From: priyankakmEaton Date: Wed, 24 Apr 2024 18:44:36 +0530 Subject: [PATCH 2/2] type docs --- login-workflow/docs/migration-guide-3-4.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/login-workflow/docs/migration-guide-3-4.md b/login-workflow/docs/migration-guide-3-4.md index abb432ea..1532c995 100644 --- a/login-workflow/docs/migration-guide-3-4.md +++ b/login-workflow/docs/migration-guide-3-4.md @@ -63,8 +63,6 @@ loadEula: async (language: string): Promise => { The `userData` parameter will now pass all data collected from the registration workflow, including custom data. -The `validationCode` parameter now supports numbers or string. - ```tsx // before completeRegistration: async (