@mx-cartographer/experiences

@mx-cartographer/experiences is a React-based library of financial experience widgets designed for seamless integration within the MX ecosystem. It provides a robust collection of modular widgets (e.g., Accounts, Budgets, Cashflow) built on top of Material UI (MUI) ^MUI_VER and the MXUI design system ^MXUI_VER, powered by MobX ^MOBX_VER for scalable state management.

Documentation

• Architecture Overview
• Widget Catalog
• State Management
• API and Data
• Styling and Theming
• Testing

Tech Stack

The library is built using a modern React stack, leveraging industry-standard tools for building performant and accessible UI components.

| Component | Technology | Description | | :--- | :--- | :--- | | Framework | React | Core library for building declarative UI components. | | Language | TypeScript | Provides static typing for improved maintainability and developer experience. | | Styling | Material UI (MUI) | Base UI component framework and styling system. | | Design System | @mxenabled/mxui | MX-themed overrides and consistent UI primitives. | | State Management | MobX | Scalable and observable state management for complex widget interactions. | | Data Visualization | D3.js | Powering complex charts and interactive data representations. | | Build Tool | Vite | Next-generation frontend tooling for fast builds and development. | | Testing | Vitest | Modern testing framework compatible with the Vite ecosystem. | | Documentation | Storybook | Component-driven development environment and live documentation. |

Table of Contents

• Getting Started
• Installation
• Usage
• Architecture
• Project Structure
• Testing
• Contributing
• Support

Getting Started

Prerequisites

• Node.js: v18.0.0 or higher
• Yarn: 4.11.0 ^YARN_VER
• React: 18.3.1 ^REACT_VER
• MobX: 6.13.6 ^MOBX_VER

Installation

Install the library using yarn:

yarn add @mx-cartographer/experiences

The QA storybook containing the latest Experience changes is accessible here.

Usage

Integrating a Widget

To use an experience widget, import it from its feature-specific entry point. Most widgets are designed to automatically wrap themselves in a WidgetContainer for consistent layout.

import React from 'react';
import { AccountsWidget } from '@mx-cartographer/experiences/accounts';

const MyDashboard = () => {
  return (
    <div style={{ height: '600px', width: '100%' }}>
      <AccountsWidget 
        onBackClick={() => console.log('User clicked back')} 
      />
    </div>
  );
};

Common Configuration

Widgets often accept sx props for styling and specific callbacks for navigation or analytics.

import { BudgetsWidget } from '@mx-cartographer/experiences/budgets';

<BudgetsWidget 
  sx={{ m: 2, borderRadius: '8px' }}
  onBudgetClick={(budgetId) => navigate(`/budgets/${budgetId}`)}
/>

Architecture

The project follows a modular architecture where feature widgets leverage shared infrastructure and a unified design system.

graph TB
    subgraph "Consumer Application"
        App[React Application]
    end

    subgraph "@mx-cartographer/experiences"
        subgraph "Common Infrastructure (src/common)"
            WC[WidgetContainer]
            GP[WidgetContainerProvider]
            GS[GlobalUiStore / GlobalCopyStore]
            API[WidgetApi / Fetch]
        end

        subgraph "Experience Widgets (src/[feature])"
            AW[AccountsWidget]
            BW[BudgetsWidget]
            CW[CashflowWidget]
        end

        subgraph "State Management"
            MX[MobX]
        end

        subgraph "UI Foundation"
            MUI[Material UI]
            MXUI[@mxenabled/mxui]
        end
    end

    App --> AW
    App --> BW
    AW --> WC
    BW --> WC
    WC --> GP
    AW --> GS
    AW --> API
    GS --> MX
    AW --> MXUI
    MXUI --> MUI

Key Design Patterns

• Container Pattern: Widgets are wrapped in WidgetContainer ^1 to provide consistent headers, action buttons, and navigation.
• Context-Driven Layout: The WidgetContainerProvider ^2 calculates container dimensions to enable internal responsive rendering logic.
• State Isolation: Each feature (e.g., Budgets, Accounts) maintains its own MobX store, while sharing global state through GlobalUiStore and GlobalCopyStore ^3.
• Responsive Primitives: All components use the useScreenSize hook ^4 for consistent behavior across mobile, tablet, and desktop viewports.

Project Structure

The codebase is organized by feature, with a shared common directory for cross-cutting concerns and a core directory for centralized types and constants.

graph TD
    src["src/"]
    src --> core["core/ (Centralized TypeScript types and constants)"]
    src --> common["common/ (Shared components, hooks, stores, and API utilities)"]
    src --> accounts["accounts/ (Accounts summary, details, and connection management)"]
    src --> budgets["budgets/ (Budget tracking, bubble charts, and categorization)"]
    src --> cashflow["cashflow/ (Cashflow forecasting and event management)"]
    src --> dashboard["dashboard/ (Aggregate view of multiple experience widgets)"]
    src --> debts["debts/ (Debt tracking and payoff visualization)"]
    src --> finstrong["finstrong/ (Financial health scoring and reporting)"]
    src --> goals["goals/ (Savings goal setting, tracking, and progress visualization)"]
    src --> networth["networth/ (Asset and liability tracking with historical trends)"]
    src --> spending["spending/ (Categorized spending analysis)"]
    src --> transactions["transactions/ (Detailed transaction history and rules)"]
    src --> trends["trends/ (Longitudinal spending and income analysis)"]

Testing

The library uses Vitest ^5 and @testing-library/react ^6 for comprehensive unit and integration testing.

# Run all tests
yarn test

# Run tests with interactive UI and coverage reporting
yarn testui

# Run tests in headless mode (CI)
yarn citest

Verification logic and test setups are maintained in src/common/tests and vitest.setup.insights.tsx.

Contributing

1. Local Development: Preview widgets in isolation using Storybook.

   yarn storybook

2. Linting: Maintain code quality and standards.

   yarn lint

3. Building: Generate production-ready artifacts.

   yarn build

Support

For technical assistance or internal inquiries:

• Team: MX Cartographer
• Docs: MX Developer Portal
• Slack: https://mx.enterprise.slack.com/archives/C08M61HSWRF #web-experiences-dev-all

Copyright (c) 2026 MX Technologies, Inc. All Rights Reserved.