Transaction Report Kit

A comprehensive React component library for transaction reporting, analysis, and cashflow visualization. Built with TypeScript and designed to be framework-agnostic with zero conflicts.

Features

• Transaction reporting and analysis
• Cashflow visualization and projections
• Category breakdown analysis
• Period-based analysis
• Excel export functionality
• Fully typed with TypeScript
• Zero bundle size overhead (peer dependencies)
• Tailwind CSS support

Installation

npm install @your-org/transaction-report-kit

Peer Dependencies

This package requires React 18+ as a peer dependency:

npm install react react-dom

Tailwind CSS

This package uses Tailwind CSS. Make sure to include the package in your Tailwind config:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    './node_modules/@your-org/transaction-report-kit/dist/**/*.{js,mjs}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Quick Start

import { TransactionReport } from '@your-org/transaction-report-kit';
import type { Transaction } from '@your-org/transaction-report-kit';

const transactions: Transaction[] = [
  {
    account_number: "12345",
    date: "2025-01-01",
    description: "Payment",
    amount: -100,
    balance: 900,
    fees: 0,
    interest: 0,
    category: "utilities",
    period: "Jan 2025",
    trans_type: "debit",
    code: "TXN001"
  },
  // ... more transactions
];

function App() {
  return <TransactionReport data={transactions} currencySymbol="R" />;
}

API Reference

Components

TransactionReport

Main component that includes all features.

Props:

• data?: Transaction[] - Optional array of transactions to display
• currencySymbol?: string - Currency symbol to use (default: "R" for South African Rand)

<TransactionReport data={transactions} currencySymbol="R" />
// Or use a different currency
<TransactionReport data={transactions} currencySymbol="$" />
<TransactionReport data={transactions} currencySymbol="€" />

SummaryDashboard

Dashboard showing summary statistics.

Props:

• summaryStats: SummaryStats - Summary statistics object
• currencySymbol?: string - Currency symbol to use (default: "R")

CategoryBreakdown

Visual breakdown of transactions by category.

Props:

• categories: CategoryData[] - Array of category data
• currencySymbol?: string - Currency symbol to use (default: "R")

PeriodAnalysis

Analysis of transactions grouped by time period.

Props:

• periods: PeriodData[] - Array of period data
• currencySymbol?: string - Currency symbol to use (default: "R")

CashflowProjection

Cashflow projection component.

Props:

• transactions: Transaction[] - Array of transactions
• organizationName: string - Organization name for the report
• currencySymbol?: string - Currency symbol to use (default: "R")

CashflowVisualization

Visual representation of cashflow.

Props:

• transactions: Transaction[] - Array of transactions
• currencySymbol?: string - Currency symbol to use (default: "R")

TransactionList

List view of transactions with filters.

Props:

• transactions: Transaction[] - Array of transactions
• currencySymbol?: string - Currency symbol to use (default: "R")

Types

Transaction

interface Transaction {
  account_number: string;
  date: string;
  description: string;
  amount: number;
  balance: number;
  fees: number;
  interest: number;
  category: string;
  period: string;
  trans_type: 'credit' | 'debit';
  code: string;
}

CashflowData

interface CashflowData {
  period: string;
  income: number;
  expenses: number;
  net: number;
  runningBalance: number;
}

Utility Functions

calculateSummaryStats

function calculateSummaryStats(transactions: Transaction[]): SummaryStats

calculateCategoryBreakdown

function calculateCategoryBreakdown(transactions: Transaction[]): CategoryData[]

calculatePeriodAnalysis

function calculatePeriodAnalysis(transactions: Transaction[]): PeriodData[]

exportToExcel

function exportToExcel(
  transactions: Transaction[],
  summaryStats: SummaryStats,
  categories: CategoryData[],
  periods: PeriodData[],
  organizationName: string
): void

Usage Examples

With API Data

import { TransactionReport } from '@your-org/transaction-report-kit';
import { useEffect, useState } from 'react';

function App() {
  const [transactions, setTransactions] = useState([]);

  useEffect(() => {
    fetch('/api/transactions')
      .then(res => res.json())
      .then(data => setTransactions(data));
  }, []);

  return <TransactionReport data={transactions} />;
}

Individual Components

import {
  SummaryDashboard,
  CategoryBreakdown,
  calculateSummaryStats,
  calculateCategoryBreakdown
} from '@your-org/transaction-report-kit';

function CustomDashboard({ transactions }) {
  const summaryStats = calculateSummaryStats(transactions);
  const categories = calculateCategoryBreakdown(transactions);

  return (
    <div>
      <SummaryDashboard summaryStats={summaryStats} />
      <CategoryBreakdown categories={categories} />
    </div>
  );
}

Publishing

To npm

1. Update version in package.json
2. Update package name to your organization
3. Build the package:

npm run build:lib

4. Publish:

npm publish

Local Development

For local development and testing:

npm link

Then in your consuming project:

npm link @your-org/transaction-report-kit

Private Registry

For private use, publish to a private npm registry or use GitHub Packages.

Configuration

Package Name

Update the package name in package.json:

{
  "name": "@your-company/transaction-report-kit"
}

Repository

Update the repository URL:

{
  "repository": {
    "type": "git",
    "url": "https://github.com/your-org/transaction-report-kit.git"
  }
}

License

MIT

Support

For issues and questions, please open an issue on GitHub.