Matt Levine Money Stuff Email Reader

A React application that helps users read Matt Levine's "Money Stuff" emails by providing main content with pop-over footnotes.

How to Use

1. Paste Email HTML: Open the application. You will see a text area where you can paste the raw HTML content of a Matt Levine "Money Stuff" email.
2. Parse Email: Click the "Parse Email" button. The application will process the HTML.
3. Read with Pop-over Footnotes: The application will display the email content.
4. Interactive Footnotes: Click on a footnote reference (e.g., [1]) in the main content. The corresponding footnote will appear in a pop-over.

Features

• Pop-over Footnotes: Displays footnotes in a pop-over when the corresponding reference in the main text is clicked.
• Interactive Footnote System: Clickable footnote references in the main text trigger a pop-over displaying the corresponding footnote content.
• HTML Parsing: Parses raw HTML from Matt Levine's "Money Stuff" emails to extract main content and footnotes.
• Responsive Design: Adapts to different screen sizes for optimal viewing.
• MUI Components: Utilizes Material-UI for a clean and modern user interface.

Technology Stack

• Frontend: Vite + React 18 + TypeScript
• UI Library: Material-UI (MUI) v5
• Build Tool: Vite
• Package Manager: npm

Project Structure

The project follows a standard Vite + React application structure:

mattreader/
├── public/             # Static assets
├── src/                # Application source code
│   ├── components/     # React components
│   ├── utils/          # Utility functions (e.g., emailParser.ts)
│   ├── hooks/          # Custom React hooks
│   ├── App.tsx         # Main application component
│   ├── main.tsx        # Entry point of the application
│   └── index.css       # Global styles
├── .github/            # GitHub Actions Workflows
│   └── workflows/
│       └── deploy-gh-pages.yml # Workflow for GitHub Pages deployment
├── dist/               # Production build output (static files)
├── tests/              # Test files
├── .gitignore          # Files ignored by Git
├── ARCHITECTURE_PLAN.md # Detailed architecture document
├── index.html          # Main HTML file for development
├── package.json        # Project metadata and dependencies
├── tsconfig.json       # TypeScript compiler options
└── vite.config.ts      # Vite configuration

For a more detailed component architecture, see the ARCHITECTURE_PLAN.md file.

Getting Started / Development

To get a local copy up and running, follow these simple steps.

Prerequisites

• Node.js and npm (Node Package Manager) must be installed on your system.

Installation & Setup

1. Clone the repository:

   git clone https://github.com/your-username/money_reader

   (Replace your-username with the actual username or organization if this is a remote repository. If it's local, you might skip this or adjust.)

2. Navigate to the project directory:

   cd money_reader

3. Install NPM packages:

   npm install

Running the Development Server

To start the development server and view the application in your browser:

npm run dev

This will typically open the application at http://localhost:5173 (Vite's default) or another port if specified. Check your terminal output for the exact address.

Building the Application

To create a production build of the application:

npm run build

This command bundles the application and outputs the static files to the dist directory. This directory contains everything needed to deploy the application.

Running as a Static Website

The dist directory generated by the build process is a self-contained static website. You can host these files on any static file server or platform.

Here are a couple of ways to serve the dist directory locally for testing:

1. Using npx serve (requires Node.js): If you have Node.js installed, you can use the serve package to quickly start a local server.

   npx serve dist

   This will typically make the application available at http://localhost:3000 or another port. Check your terminal output for the exact address.

2. Opening dist/index.html directly in a browser: You can also open the dist/index.html file directly in your web browser.

   file:///path/to/your/project/money_reader/dist/index.html
   

   Note: While this works for simple cases, some browser features or routing configurations might not work as expected when opened via the file:// protocol. Using a local HTTP server (like npx serve) is generally recommended for a more accurate testing environment.

The dist directory can be uploaded to services like GitHub Pages, Netlify, Vercel, AWS S3, or any other static hosting provider.

Note for GitHub Pages Deployment: The vite.config.ts is configured with base: '/money_reader/' to ensure correct asset loading when deployed to GitHub Pages under a repository named money_reader. If deploying to a different path or platform, this configuration might need adjustment.

Automated Deployment

Deployment to GitHub Pages is automated using GitHub Actions. The workflow is defined in .github/workflows/deploy-gh-pages.yml and triggers on pushes to the main branch. This means that any changes merged into the main branch will automatically be built and deployed to the live GitHub Pages site.

Testing

This project includes tests for the email parsing functionality.

Automated Parser Test

The primary automated test validates the email parsing logic. It checks if footnotes are correctly identified and extracted.

To run this test:

npm run test:parser

This command executes the tests/test_parser.js script.

Manual End-to-End Testing

For manual testing of the user interface and overall application flow:

1. Start the development server:

   npm run dev

2. Open the application in your browser.
3. Use sample email HTML (e.g., from tests/test_email.html or the examples in tests/test_parser.js) to paste into the input field.
4. Verify that the email parses correctly and that clicking on footnote references opens a pop-over with the correct footnote content.

For more detailed testing information, including specific checks and how to use the browser console for tests, please refer to the tests/README.md file.