Flow Components

Flow components orchestrate complex multi-step workflows, providing a seamless user experience for multi-stage operations.

Table of Contents

• MultiStepFlow
  • Web Component Usage
  • Props
  • Events
  • Example Configurations
• Type Definitions
  • FlowConfig
  • FlowStep
  • CONSUMER_INFORMATION
  • BUSINESS_INFORMATION
• Available Steps
  • CREATE_ACCOUNT
  • CREATE_CONSUMER_ACCOUNT
  • CREATE_BUSINESS_ACCOUNT
  • ADD_BANK_ACCOUNT
  • ADD_PAYMENT_INSTRUMENT
  • CHECKOUT_CONFIRM
• Features
• Integration Patterns
• Styling & Customization
• Best Practices

MultiStepFlow

Configurable multi-step flow component for complex workflows like account creation, onboarding, and payment processes.

Web Component Usage

<alviere-multi-step-flow
  config='{"steps":[{"type":"CREATE_CONSUMER_ACCOUNT","label":"Create Account"},{"type":"ADD_BANK_ACCOUNT","label":"Add Bank"}],"amount":100.50}'
  jwt="your-jwt-token"
  public-certificate="retrieved-public-certificate"
  public-certificate-id="retrieved-public-certificate-id"
  business-uuid="businessUuid"
  amount="100.50"
  debug="false">
</alviere-multi-step-flow>

Props

Note: showProgress, showNavigation, allowSkip, and allowBack are configured within the config object, not as separate props.

Events

Event Handlers (Alternative to Event Listeners):

You can also use callback props instead of event listeners:

Example Configurations

Complete Onboarding and Payment Flow

{
  "steps": [
    {
      "type": "CREATE_ACCOUNT",
      "label": "User Account"
    },
    {
      "type": "ADD_BANK_ACCOUNT",
      "label": "Add Bank Account"
    },
    {
      "type": "CHECKOUT_CONFIRM",
      "label": "Confirm Payment"
    }
  ],
  "amount": 100.50,
  "showProgress": true,
  "showNavigation": false,
  "allowSkip": false,
  "allowBack": false
}

Type Definitions

This section contains all TypeScript interfaces and type definitions used throughout the Flow Components.

FlowConfig

The main configuration object for the multi-step flow component.

interface FlowConfig {
  steps: FlowStep[];
  title?: string;
  description?: string;
  allowSkip?: boolean;
  allowBack?: boolean;
  showProgress?: boolean;
  showNavigation?: boolean;
  amount: number | string;
}

Properties:

• steps - Array of flow steps to be executed
• title - Optional title for the flow
• description - Optional description text
• allowSkip - Whether users can skip optional steps
• allowBack - Whether users can navigate back to previous steps
• showProgress - Whether to display the progress indicator
• showNavigation - Whether to show navigation controls
• amount - The amount for payment transaction

FlowStep

Defines the structure of individual steps within a flow.

interface FlowStep {
  type: StepType;
  label: string;
  status: StepStatus;
  config?: Record<string, any>;
}

Properties:

• type - The type of step (see Available Steps)
• label - Display label for the step
• status - Current status of the step
• config - Optional configuration object for the step

Step Types:

Step Status:

CONSUMER_INFORMATION

Interface for consumer account information used in account creation steps.

interface CONSUMER_INFORMATION {
  consumer_information: {
    first_name: string
    middle_name?: string
    last_name: string
    date_of_birth?: string
    ssn?: string
    phone_number?: string
    email_address: string
  }
}

Properties:

• first_name - Consumer's first name (required)
• middle_name - Consumer's middle name (optional)
• last_name - Consumer's last name (required)
• date_of_birth - Date of birth in YYYY-MM-DD format (optional)
• ssn - Full Social Security Number (optional)
• phone_number - International format (+1***) contact phone number (optional)
• email_address - Email address (required)

BUSINESS_INFORMATION

Interface for business account information used in business account creation steps.

interface BUSINESS_INFORMATION {
  business_information: {
    business_type: string,
    business_name: string,
    doing_business_as?: string,
    state_of_incorporation: string,
    country_of_incorporation: string,
    incorporation_date?: string,
    ein?: string,
  }
}

Properties:

• business_type - Type of business entity (required)
• business_name - Legal business name (required)
• doing_business_as - DBA name if different from legal name (optional)
• state_of_incorporation - State where business is incorporated (required)
• country_of_incorporation - Country of incorporation (required)
• incorporation_date? - Date of incorporation in YYYY-MM-DD format (optional)
• ein? - Employer Identification Number (optional)

Available Steps

This section describes all available step types that can be used in a flow configuration.

CREATE_ACCOUNT

The create account step, is the first step on the onboarding flow. It consists of a wrapper around CREATE_CONSUMER_ACCOUNT and CREATE_BUSINESS_ACCOUNT forms, and it infers based on the config.formData it receives which of the two forms it will render. If no config is passed or is invalid, it will fallback to CREATE_CONSUMER_ACCOUNT.

Configuration:

{
  formData: {
    information: BUSINESS_INFORMATION | CONSUMER_INFORMATION,
    primary_address?: ADDRESS
  }
}

The step determines which form to display based on the structure of the information object. See CONSUMER_INFORMATION and BUSINESS_INFORMATION for details.

CREATE_CONSUMER_ACCOUNT

The create consumer account step will render the create consumer form and handle its state.

Configuration: Uses the CONSUMER_INFORMATION interface.

CREATE_BUSINESS_ACCOUNT

The create business account step will render the create business form and handle its state.

Configuration: Uses the BUSINESS_INFORMATION interface.

ADD_BANK_ACCOUNT

Bank account addition step for linking financial accounts to the user's profile.

CHECKOUT_CONFIRM

Confirmation step for payment and checkout processes. Requires an amount to be specified in the flow configuration.

Features

Progress Tracking

• Visual Progress Bar: Shows completion percentage
• Step Indicators: Clear indication of current step
• Status Display: Shows status of each step
• Completion Tracking: Tracks overall flow progress

Navigation Controls

• Next Button: Advances to next step when current step is complete
• Previous Button: Returns to previous step (if allowed)
• Skip Option: Skip optional steps (if configured)
• Flow Control: Automatic progression based on step completion

Step Management

• Dynamic Rendering: Renders appropriate component for each step
• State Persistence: Maintains step state across navigation
• Result Aggregation: Collects results from all completed steps
• Error Handling: Graceful error handling and recovery

User Experience

• Responsive Design: Works on all device sizes
• Accessibility: Full ARIA support and keyboard navigation
• Loading States: Visual feedback during step transitions
• Error Recovery: Clear error messages and recovery options

Integration Patterns

Event-Driven Architecture

The MultiStepFlow component emits events that can be used to integrate with external systems:

const flow = document.querySelector('alviere-multi-step-flow');

flow.addEventListener('stepcomplete', (event) => {
  const { stepIndex, stepType, result } = event.detail;
  
  // Update external systems
  updateProgress(stepIndex, stepType);
  saveStepResult(stepIndex, result);
  
  // Trigger external workflows
  if (stepType === 'CREATE_CONSUMER_ACCOUNT') {
    triggerAccountVerification(result);
  }
});

flow.addEventListener('complete', (event) => {
  const { stepResults } = event.detail;
  
  // Process complete flow results
  processOnboardingComplete(stepResults);
  
  // Navigate to next page
  window.location.href = '/dashboard';
});

flow.addEventListener('flowcomplete', (event) => {
  const { stepType, success, amount } = event.detail;
  
  // Handle flow completion
  if (success) {
    console.log(`Flow completed successfully with amount: ${amount}`);
  }
});

flow.addEventListener('reset', () => {
  // Handle flow reset
  console.log('Flow has been reset');
});

Custom Step Configuration

Steps can accept additional configuration for customization:

{
  "steps": [
    {
      "type": "CREATE_ACCOUNT",
      "label": "Create Account",
      "status": "INCOMPLETE",
      "config": {
        "formData": {...AccountData}
      }
    }
  ]
}

Flow State Management

The component maintains internal state that can be accessed:

// Get current flow state
const currentStep = flow.getAttribute('data-current-step');
const completedSteps = flow.getAttribute('data-completed-steps');

// Check if flow is complete
const isComplete = flow.hasAttribute('data-complete');

Styling & Customization

CSS Custom Properties

The component uses CSS custom properties for theming:

.alviere-multi-step-flow {
  --primary-color: #007bff;
  --success-color: #28a745;
  --error-color: #dc3545;
  --warning-color: #ffc107;
  --border-radius: 8px;
  --step-spacing: 2rem;
}

Component-Specific Styling

Individual step components can be styled:

/* Style the create account step */
.alviere-multi-step-flow .alviere-create-consumer-account {
  --form-background: #f8f9fa;
  --border-color: #dee2e6;
}

/* Style the bank account step */
.alviere-multi-step-flow .alviere-add-bank-account {
  --form-background: #ffffff;
  --border-color: #ced4da;
}

Best Practices

Flow Design

• Keep steps focused: Each step should have a single, clear purpose
• Logical progression: Steps should follow a logical order
• Clear labels: Use descriptive labels for each step
• Progress indication: Always show progress to keep users informed

Error Handling

• Graceful degradation: Handle errors without breaking the flow
• Clear messaging: Provide clear error messages and recovery options
• Retry mechanisms: Allow users to retry failed steps
• Fallback options: Provide alternative paths when possible

Performance

• Lazy loading: Load step components only when needed
• State management: Efficiently manage step state and transitions
• Memory management: Clean up resources when steps are completed
• Optimization: Minimize re-renders and unnecessary updates