# @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](docs/ARCHITECTURE.md)
- [Widget Catalog](docs/WIDGETS.md)
- [State Management](docs/STATE_MANAGEMENT.md)
- [API and Data](docs/API_AND_DATA.md)
- [Styling and Theming](docs/STYLING_AND_THEMING.md)
- [Testing](docs/TESTING.md)

## 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](https://reactjs.org/) | Core library for building declarative UI components. |
| **Language** | [TypeScript](https://www.typescriptlang.org/) | Provides static typing for improved maintainability and developer experience. |
| **Styling** | [Material UI (MUI)](https://mui.com/) | Base UI component framework and styling system. |
| **Design System** | [@mxenabled/mxui](https://mx.atlassian.net/wiki) | MX-themed overrides and consistent UI primitives. |
| **State Management** | [MobX](https://mobx.js.org/) | Scalable and observable state management for complex widget interactions. |
| **Data Visualization** | [D3.js](https://d3js.org/) | Powering complex charts and interactive data representations. |
| **Build Tool** | [Vite](https://vitejs.dev/) | Next-generation frontend tooling for fast builds and development. |
| **Testing** | [Vitest](https://vitest.dev/) | Modern testing framework compatible with the Vite ecosystem. |
| **Documentation** | [Storybook](https://storybook.js.org/) | Component-driven development environment and live documentation. |

## Table of Contents
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Usage](#usage)
- [Architecture](#architecture)
- [Project Structure](#project-structure)
- [Testing](#testing)
- [Contributing](#contributing)
- [Support](#support)

## Getting Started

### Prerequisites
- **Node.js**: v18.0.0 or higher
- **Yarn**: 4.15.0 [^YARN_VER]
- **React**: 19.x [^REACT_VER]
- **MobX**: 6.15.0 [^MOBX_VER]

### Installation

Install the library using yarn:

```bash
yarn add @mx-cartographer/experiences
```

The QA storybook containing the latest Experience changes is [accessible here](https://experiences.kube.qa.internal.mx/?path=/docs/experiences-introduction--docs).

## 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.

```tsx
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.

```tsx
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.

```mermaid
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.

```mermaid
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.

```bash
# 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__](src/common/__tests__) and [vitest.setup.insights.tsx](vitest.setup.insights.tsx).

## Contributing

1. **Local Development**: Preview widgets in isolation using Storybook.
   ```bash
   yarn storybook
   ```
2. **Linting**: Maintain code quality and standards.
   ```bash
   yarn lint
   ```
3. **Building**: Generate production-ready artifacts.
   ```bash
   yarn build
   ```

<!-- Commented this out to prevent exposing internal operations in the npm registry -->

<!-- ## Publishing alpha versions
1. Bump the version in package.json using the format `major.minor.patch-alpha.<yourinitials><n>` See [the version history](https://www.npmjs.com/package/@mx-cartographer/experiences?activeTab=versions) for examples.
1. Run `npm publish --tag alpha`.


## Merging and Publishing
1. Update CHANGELOG.md and include the version to publish using the standard `major.minor.patch`. If there are breaking changes, we bump the major, new feature we bump minor and bug fixes or minor changes, we bump patch.
1. Request a MR review by commenting `shipit --review`
1. Once the MR is approved, comment `shipit --publish-version=major|minor|patch`.
2. Shipit will bump the version in package.json, merge and publish the package to npm. -->

## Support

For technical assistance or internal inquiries:
- **Team**: MX Cartographer
- **Docs**: [MX Developer Portal](https://mx.atlassian.net/wiki)
- **Slack**: https://mx.enterprise.slack.com/archives/C08M61HSWRF #web-experiences-dev-all

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

[^1]: [src/common/components/WidgetContainer.tsx:55](src/common/components/WidgetContainer.tsx#L55)
[^2]: [src/common/context/WidgetContainerProvider.tsx:10](src/common/context/WidgetContainerProvider.tsx#L10)
[^3]: [src/common/context/GlobalStoreProvider.tsx:10](src/common/context/GlobalStoreProvider.tsx#L10)
[^4]: [src/common/hooks/useScreenSize.tsx:4](src/common/hooks/useScreenSize.tsx#L4)
[^5]: [package.json:187](package.json#L187)
[^6]: [package.json:229](package.json#L229)
[^MUI_VER]: [package.json:195](package.json#L195)
[^MXUI_VER]: [package.json:203](package.json#L203)
[^MOBX_VER]: [package.json:209](package.json#L209)
[^REACT_VER]: [package.json:213](package.json#L213)
[^YARN_VER]: [package.json:297](package.json#L297)