@jpmorgan-payments/embedded-finance-components 0.5.96 → 0.5.97

package/README.md

@@ -10,56 +10,75 @@ While we strive to incorporate ADA (Americans with Disabilities Act) best practi
 
 ## Overview
 
-Embedded UI Components offer a seamless way to integrate sophisticated UI components into your existing applications, providing a plug-and-play solution for Embedded Finance features. These components implement complex API capabilities for client onboarding and account linking, simplifying the integration process for developers.
+The Embedded UI Components library offers a seamless way to integrate sophisticated UI capabilities into your existing web applications, providing a plug-and-play solution for Embedded Finance features.
 
 ## Important Usage Notes
 
 **All Embedded UI Components must be wrapped within the `EBComponentsProvider`.** The `EBComponentsProvider` is specifically designed for these components and is not applicable to any other client components in your application.
 
-## Setup and Configuration
+## Main Embedded UI Components Architecture Concepts
 
-### EBComponentsProvider
+The library is built on several key architectural concepts:
 
-The `EBComponentsProvider` is a crucial wrapper component that must be placed at the top level of your Embedded UI Components implementation. It handles authentication, applies theming, and provides necessary context to all child Embedded UI Components.
-It is using @tanstack/react-query for handling API calls and authentication as well as Orval generated types for the API requests and responses.
+### Integration Scenarios and Use Cases
 
-#### Key Props:
+The Embedded UI Components are designed for flexible integration into parent web applications, offering several customization points:
 
-- `apiBaseUrl`: The base URL for API calls (required)
-- `theme`: Customization options for the components' appearance (optional)
-- `headers`: Custom headers for API requests (optional)
+```mermaid
+graph LR
+    subgraph "Parent Web Application"
+        CMS["Content Management System"]
+        Theme["Theming System"]
+        RUM["Real User Monitoring"]
+        Storage[("Client ID / Platform ID / User Identity")]
+
+        subgraph "Embedded Components Integration"
+            Provider["EBComponentsProvider"]
+            Components["Embedded UI Components"]
+
+            Provider --> Components
+        end
 
-#### Usage:
+        CMS -->|"Content Tokens"| Provider
+        Theme -->|"Design Tokens"| Provider
+        RUM -->|"User Event Handler"| Components
+        Storage -->|"Client ID / Platform ID"| Components
+    end
+```
 
-```jsx
-import { EBComponentsProvider } from '@jpmorgan-payments/embedded-finance-components';
+#### Integration Flexibility
 
-const EmbeddedFinanceSection = () => {
-  return (
-    <EBComponentsProvider
-      apiBaseUrl="https://your-api-base-url.com"
-      theme={{
-        colorScheme: 'light',
-        variables: {
-          primaryColor: '#007bff',
-          fontFamily: 'Arial, sans-serif',
-        },
-      }}
-      headers={{
-        'Custom-Header': 'value',
-      }}
-    >
-      {/* Your Embedded UI Components go here */}
-    </EBComponentsProvider>
-  );
-};
-```
+1. **Runtime Customization**
+
+   - Inject design tokens to match parent app's theme or use the default ones
+   - Override content tokens from parent app's CMS systems or any other source
+   - Connect to parent app's monitoring via `userEventsHandler`
+
+2. **Component Configuration**
+   - Configure API endpoints via provider
+   - Customize component behavior through props
+
+3. **Client ID / Platform ID** (only for onboarding components)
+   - Onboarding Embedded UI Components can be used in fully controlled (client ID is provided and managed by the parent app) or uncontrolled (client ID is created from scratch by the embedded component) mode
+   - In uncontrolled mode the embedded component will create a new client and it is recommended to manage its lifecycle via the `onPostClientResponse` callback prop
+
+#### Future Extensibility
+
+1. **Field Configuration**
+
+   - Externalization of field mapping logic
+   - Custom field validation rules
+   - Dynamic form layout configuration
+   - Validation rules can be overridden from the parent app
 
-## Main concepts
+2. **Workflow Customization**
+   - Integration with Arazzo workflow definitions
+   - Custom step sequencing
+   - Conditional flow logic
 
-The Embedded UI Components are built using a sophisticated approach that leverages OpenAPI Specifications (OAS) and automated code generation to ensure type safety and consistent API integration.
+### Overall Logical Composition Diagram
 
-### Architecture Overview
+**Note:** The following diagram illustrates the component architecture using the onboarding wizard as an example:
 
 ```mermaid
 graph TB
@@ -93,14 +112,14 @@ graph TB
     end
 ```
 
-### Key Architecture Components
+### Key Principles
 
 1. **OpenAPI Specification (OAS) & Future Arazzo Flows**
 
    - OAS defines API contracts and types
-   - Source of truth for API interfaces
-   - Used to generate TypeScript types and React Query hooks
-   - Note: Arazzo Flows and automated flow generation are planned future capabilities - currently no flows are pre-configured
+   - Serves as source of truth for API interfaces
+   - Generates TypeScript types and React Query hooks
+   - Future: Arazzo Flows will enable automated flow generation (not currently available)
 
 2. **Automated Code Generation**
 
@@ -108,10 +127,9 @@ graph TB
      - TypeScript interfaces
      - Type-safe React Query hooks
      - API client utilities
-   - Future capability: Flow generation from Arazzo Flows
    - Ensures type consistency between API and UI
 
-3. **Component Architecture**
+3. **Other utility functions**
 
    Built using generated types and hooks with an opinionated layer providing:
 
@@ -123,15 +141,46 @@ graph TB
      - Cognitive load reduction
      - Intelligent navigation
 
-4. **Runtime Flow**
-   - Components make API calls to Platform Service Layer (PSL)
-   - PSL handles:
-     - Authentication & authorization
-     - Request forwarding to backend APIs
-     - Response processing
-     - Error handling
+## Embedded UI Components
 
-## Main Components
+The library currently provides the following components:
+
+### EBComponentsProvider
+
+The `EBComponentsProvider` is a crucial wrapper component that must be placed at the top level of your Embedded UI Components implementation. It handles authentication, applies theming, and provides necessary context to all child Embedded UI Components.
+It is using @tanstack/react-query for handling API calls and authentication as well as Orval generated types for the API requests and responses.
+
+#### Key Props:
+
+- `apiBaseUrl`: The base URL for API calls (required)
+- `theme`: Customization options for the components' appearance (optional)
+- `headers`: Custom headers for API requests (optional)
+
+#### Usage:
+
+```jsx
+import { EBComponentsProvider } from '@jpmorgan-payments/embedded-finance-components';
+
+const EmbeddedFinanceSection = () => {
+  return (
+    <EBComponentsProvider
+      apiBaseUrl="https://your-api-base-url.com"
+      theme={{
+        colorScheme: 'light',
+        variables: {
+          primaryColor: '#007bff',
+          fontFamily: 'Arial, sans-serif',
+        },
+      }}
+      headers={{
+        'Custom-Header': 'value',
+      }}
+    >
+      {/* Your Embedded UI Components go here */}
+    </EBComponentsProvider>
+  );
+};
+```
 
 ### 1. OnboardingWizardBasic
 
@@ -255,6 +304,8 @@ Please refer to the LinkedAccountProps interface in the codebase for more detail
 
 ## Theming
 
+The library supports comprehensive theming through the EBComponentsProvider. Components can be styled to match your application's design system using theme tokens.
+
 The `EBComponentsProvider` accepts a `theme` prop that allows for extensive customization of the components' appearance. The theme object can include the following properties:
 
 - `colorScheme`: 'dark' | 'light' | 'system'
@@ -308,6 +359,8 @@ yarn add @jpmorgan-payments/embedded-finance-components
 
 ## Contributing
 
+To contribute to the development of this library, please follow these guidelines:
+
 ### Recommended VSCode plugins:
 
 - Prettier