@mx-cartographer/experiences 8.0.0-alpha.v2 → 8.0.1

package/CHANGELOG.md

@@ -1,7 +1,18 @@
+## [8.0.1] - 04-06-2026
+
+- **UPDATED** - Documentation to reflect the move of shared types and constants to `src/core`
+- **UPDATED** - Technical support Slack channel reference to the new enterprise link
+- **UPDATED** - Installation and publishing guides to reflect Yarn-only project mandate
+- **UPDATED** - Architectural diagrams to include the new `src/core` layer
+
 ## [8.0.0] - 04-02-2026
 
 - **UPDATED** - types by moving from common/types to core/types (BREAKING CHANGE)
 
+## [7.13.21] - 04-03-2026
+
+- **FIXED** - `Spending` widget treating negative transactions as expenses
+
 ## [7.13.20] - 04-02-2026
 
 - **ADDED** - DonutChartV2 component for Insights MUI Refresh.

package/README.md

@@ -1,16 +1,197 @@
-- [Getting Started](#getting-started)
-<!-- - [Merging and Publishing](#merging-and-publishing) -->
-- [React Library Application Template](#react-library-application-template)
+# @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.
 
-## Getting started
-In order to run the project you will need to make sure that you have yarn installed. It must be higher than 1.22 in order to do that you must have corepack enabled. Do not just run "npm i" to install dependencies, all packages must be installed with yarn.
+| 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. |
 
-1. Install [yarn](https://yarnpkg.com/getting-started/install)
-1. From the project root dir, run `yarn` or `yarn install` to install dependencies
-1. To start the project run `yarn dev`
-1. The storybook project should automatically run in your local browser
-1. The QA storybook containing the latest Experience changes is [accessible here](https://experiences.kube.qa.internal.mx/?path=/docs/experiences-introduction--docs)
+## 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.11.0 [^YARN_VER]
+- **React**: 18.3.1 [^REACT_VER]
+- **MobX**: 6.13.6 [^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 -->
 
@@ -25,37 +206,23 @@ In order to run the project you will need to make sure that you have yarn instal
 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. -->
 
-
-## React Library Application Template
-
-This template is used to create projects in the Cartographer group
-
-### Create a Cartographer group project from the template
-
-1. Go to the [Cartographer group](https://gitlab.mx.com/mx/money-experiences/moneymap/cartographer) and click "New Project"
-1. Click "Create from Template"
-1. Open the "Groups" tab
-1. Click "Use Template" in the React Library Application row
-1. Enter the project name and ensure that the visitibliy is set to internal. Add a description if needed
-1. Click "Create project" and you've created your project
-
-### Next steps:
-
-#### Protect the Master branch
-
-Note: A maintainer or owner will need to do this part
-
-1. Open Settings > Repository for the repo
-1. Expand the "Selected branches" section
-1. For the master branch, set the "Allowed to merge" option to "Developers + Maintainers" and the "Allowed to push" option to "No one"
-
-#### Merge Request Approvals
-
-1. Open Settings > General for the repo
-1. Expand the "Merge request approvals section"
-1. Change approvals required to 1
-
-#### Issue board
-
-Under Issues > Boards, create a new board to track issues for that specific repo. Copy the labels/lists from the scoped issue board in the Cartographer group to create this one. The labels will be the same, but the new issue board will only shows issues created for this specific repo.
-
+## 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:267](package.json#L267)
+[^6]: [package.json:160](package.json#L160)
+[^MUI_VER]: [package.json:188](package.json#L188)
+[^MXUI_VER]: [package.json:196](package.json#L196)
+[^MOBX_VER]: [package.json:202](package.json#L202)
+[^REACT_VER]: [package.json:206](package.json#L206)
+[^YARN_VER]: [package.json:284](package.json#L284)

package/dist/{SpendingLegend-BgjazduU.mjs → SpendingLegend-BCnXkPCD.mjs}

@@ -13,31 +13,31 @@ import { u as R } from "./useAriaLive-MkYebyUR.mjs";
 import { u as v } from "./hooks-BxkfR-Ff.mjs";
 import { u as V } from "./useScreenSize-B6JyS_Lj.mjs";
 import { f as b } from "./NumberFormatting-QCaNwbjv.mjs";
-const D = 5, B = (i, l, g, c) => c.reduce((o, n) => {
+const D = 5, B = (i, l, g, m) => m.reduce((o, n) => {
   const a = i.find((s) => s.guid === n.category_guid);
   if (!a) return o;
   const t = a.parent_guid ?? a.guid, r = i.find((s) => s.guid === t);
-  if (!r) return o;
-  const m = {
+  if (!r || n.total <= 0) return o;
+  const c = {
     guid: a.guid,
     name: a.guid === t ? `${l.parent_category_totals_label_general} ${a.name}` : a.name,
     color: _(r.guid, g),
     amount: n.total
   }, e = o.find((s) => s.guid === t);
-  return e ? (e.amount += n.total, e.categoryTotals?.push(m)) : o.push({
+  return e ? (e.amount += n.total, e.categoryTotals?.push(c)) : o.push({
     guid: t,
     name: r.name,
     color: _(r.guid, g),
-    categoryTotals: [m],
+    categoryTotals: [c],
     amount: n.total
   }), o;
-}, []), nt = (i, l, g, c) => {
-  const n = B(i, l, g, c).filter(
+}, []), nt = (i, l, g, m) => {
+  const n = B(i, l, g, m).filter(
     (e) => e.guid !== p.INCOME && e.guid !== p.INVESTMENTS && e.guid !== p.TRANSFER && e.amount > 0
   ).sort((e, s) => s.amount - e.amount), a = n.reduce(
     (e, s) => e + s.amount,
     0
-  ), t = n.length > D ? D : n.length, r = n.slice(0, t), m = r.map((e) => ({
+  ), t = n.length > D ? D : n.length, r = n.slice(0, t), c = r.map((e) => ({
     id: e.guid,
     color: _(e.guid, g),
     label: e.name,
@@ -54,7 +54,7 @@ const D = 5, B = (i, l, g, c) => c.reduce((o, n) => {
       name: l.saving_goal_other,
       categoryTotals: e,
       amount: s
-    }), m.push({
+    }), c.push({
       id: "other",
       color: g.palette.categories.others || "",
       label: l.saving_goal_other,
@@ -63,15 +63,15 @@ const D = 5, B = (i, l, g, c) => c.reduce((o, n) => {
   }
   return {
     categoryData: r,
-    donutData: m,
+    donutData: c,
     totalAmount: a
   };
 }, et = (i, l, g) => {
-  const c = i.filter(
+  const m = i.filter(
     (t) => t.guid === p.INCOME || t.parent_guid === p.INCOME
-  ), o = l.filter((t) => c.some((r) => r.guid === t.category_guid)).sort((t, r) => t.total - r.total).map((t, r) => ({
+  ), o = l.filter((t) => m.some((r) => r.guid === t.category_guid)).sort((t, r) => t.total - r.total).map((t, r) => ({
     guid: t.category_guid,
-    name: i.find((m) => m.guid === t.category_guid)?.name,
+    name: i.find((c) => c.guid === t.category_guid)?.name,
     color: g[r],
     categoryTotals: [],
     amount: Math.abs(t.total)
@@ -93,13 +93,13 @@ const D = 5, B = (i, l, g, c) => c.reduce((o, n) => {
   data: i,
   isIncome: l = !1,
   onSelected: g,
-  onViewTransactions: c,
+  onViewTransactions: m,
   selectedId: o,
   size: n = 150,
   totalLabel: a,
   variant: t = "mini"
 }) => {
-  const { spending: r } = v(), m = A(), { isTablet: e } = V(), { announce: s, ariaLive: C } = R(), u = T.useMemo(
+  const { spending: r } = v(), c = A(), { isTablet: e } = V(), { announce: s, ariaLive: C } = R(), u = T.useMemo(
     () => o ? i.categoryData.find((x) => x.guid === o) : void 0,
     [o]
   );
@@ -109,8 +109,8 @@ const D = 5, B = (i, l, g, c) => c.reduce((o, n) => {
       s(`${u.name}: ${x}`);
     }
   }, [u, s, t]);
-  const E = i.donutData.length > 0 ? i.donutData : [{ id: "0", color: m.palette.divider, value: 100 }], I = () => {
-    c?.(o);
+  const E = i.donutData.length > 0 ? i.donutData : [{ id: "0", color: c.palette.divider, value: 100 }], I = () => {
+    m?.(o);
   }, w = e ? 32 : 48;
   return /* @__PURE__ */ f(N, { children: [
     C,
@@ -161,7 +161,7 @@ const D = 5, B = (i, l, g, c) => c.reduce((o, n) => {
     ] }) }) })
   ] });
 }, rt = k(P), at = ({ data: i, onSelected: l, selectedId: g }) => {
-  const c = (o, n) => {
+  const m = (o, n) => {
     (o.key === "Enter" || o.key === " ") && (o.preventDefault(), l(n));
   };
   return /* @__PURE__ */ d(h, { gap: 8, height: "100%", justifyContent: "center", my: "auto", children: i.categoryData.map((o) => /* @__PURE__ */ f(
@@ -173,7 +173,7 @@ const D = 5, B = (i, l, g, c) => c.reduce((o, n) => {
       direction: "row",
       gap: 8,
       onClick: () => l(o.guid),
-      onKeyDown: (n) => c(n, o.guid),
+      onKeyDown: (n) => m(n, o.guid),
       role: "button",
       sx: { cursor: "pointer" },
       tabIndex: 0,

package/dist/finstrong/index.es.js

@@ -51,7 +51,7 @@ import { ChartsXAxis as Zn } from "@mui/x-charts/ChartsXAxis";
 import { ChartsYAxis as Jn } from "@mui/x-charts/ChartsYAxis";
 import { startOfMonth as Dt } from "date-fns/startOfMonth";
 import { endOfMonth as It } from "date-fns/endOfMonth";
-import { g as eo, S as to, b as no } from "../SpendingLegend-BgjazduU.mjs";
+import { g as eo, S as to, b as no } from "../SpendingLegend-BCnXkPCD.mjs";
 import { formatISO as oo } from "date-fns/formatISO";
 import { fromUnixTime as ro } from "date-fns/fromUnixTime";
 import { startOfToday as st } from "date-fns/startOfToday";

package/dist/spending/index.es.js

@@ -8,7 +8,7 @@ import C from "@mui/material/Stack";
 import N from "@mui/material/Tab";
 import it from "@mui/material/Tabs";
 import _t from "@mui/material/styles/useTheme";
-import { g as rt, a as st, S as $, b as Y } from "../SpendingLegend-BgjazduU.mjs";
+import { g as rt, a as st, S as $, b as Y } from "../SpendingLegend-BCnXkPCD.mjs";
 import { Text as T, Icon as bt } from "@mxenabled/mxui";
 import { f as R } from "../NumberFormatting-QCaNwbjv.mjs";
 import { u as I, l as A, d as lt, b as V, a as F, h as ct, g as yt } from "../hooks-BxkfR-Ff.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mx-cartographer/experiences",
-  "version": "8.0.0-alpha.v2",
+  "version": "8.0.1",
   "description": "Library containing experience widgets",
   "author": "MX",
   "license": "MIT",