@mx-cartographer/experiences

@mx-cartographer/experiences is a React library of financial widgets for MX applications. Each widget (for example Accounts, Budgets, and Cashflow) has its own entry point. The widgets use Material UI (MUI), the MXUI design system, and MobX for state management. The package.json file lists the versions of each package.

Documentation

• Architecture Overview
• Widget Catalog
• State Management
• API and Data
• Styling and Theming
• Testing
• Insights V2 Action Blocks

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
• Testing
• Contributing
• Support

Getting Started

Prerequisites

You need these tools to work in this repo:

• Node.js: 22 (>=22.12). CI uses node:22-alpine (pinned, not the moving lts tag).
• Yarn: the version in the packageManager field of package.json. Enable Corepack to get it.

Installation

Install the library using yarn:

yarn add @mx-cartographer/experiences

Your app must install the packages listed under peerDependencies in package.json.

Your app must also install the MUI X packages at the versions listed under peerDependencies in package.json. experiences, mxui, and your app then share one copy. The data grid packages are needed only for widgets that show a table.

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

Usage

Integrating a Widget

Import each widget from its feature entry point. A widget reads its data from a GlobalStore, so render it inside a GlobalDataProvider. Most widgets wrap themselves in a WidgetContainer for a consistent layout.

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

const globalStore = new GlobalStore();
globalStore.loadData();

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

Common Configuration

Most full widgets accept the WidgetProps type from src/core/types/Widgets.ts: an sx prop for styles, a title, and navigation callbacks such as onBackClick and onMenuClick.

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

<BubbleBudgetsWidget
  sx={{ m: 2, borderRadius: '8px' }}
  onBackClick={() => navigate('/')}
/>

Architecture

Each feature widget uses shared code in src/core (types, constants, MobX stores, API classes, and utilities) and src/common (shared components, hooks, and context providers). The Architecture Overview describes how these parts connect, and the Widget Catalog lists each feature directory and its entry points.

Testing

The library uses Vitest and React Testing Library (@testing-library/react) for unit and integration tests.

# Run all tests
yarn test

# Run tests with interactive UI and coverage reporting
yarn testui

# Run tests in headless mode (CI)
yarn citest

The test configuration is in vitest.config.ts and tests/setup.ts. docs/TESTING.md tells you how to write tests.

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.