# 📚 BookEz Software – Project Documentation

A comprehensive documentation for your BookEz npm package, which includes React component libraries and utilities for book-keeping, accounting, banking, and finance applications.

---

## 📋 Index

1. [Overview](#overview)
2. [File & Configuration Summary](#file--configuration-summary)
   1. [.gitattributes](#gitattributes)
   2. [.gitignore](#gitignore)
   3. [postcss.config.mjs](#postcssconfigmjs)
   4. [package.json](#packagejson)
   5. [package-lock.json](#package-lockjson)
   6. [tsconfig.json](#tsconfigjson)
   7. [tsup.config.ts](#tsupconfigts)
   8. [readme.md](#readmemd)
3. [Core Architecture](#core-architecture)
   - [Component Structure](#component-structure)
   - [Build & TypeScript Pipeline](#build--typescript-pipeline)
   - [UI Theming & Customization](#ui-theming--customization)
4. [Dependency Management](#dependency-management)
5. [Development Workflow](#development-workflow)
6. [Appendix: Diagrams](#appendix-diagrams)

---

## Overview

**BookEz Software** is a modular npm package providing reusable React UI components and utilities for building accounting, banking, and finance apps — with special support for transaction tables, Plaid bank integrations, state/context management, and highly customizable theming.

---

## File & Configuration Summary

Below you'll find a description and explanation for every key configuration and documentation file.

### `.gitattributes`

| Setting       | Purpose                                                                                                                       |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `* text=auto` | **Automatically normalizes line endings** to LF (Unix style) during git checkout/commit, ensuring cross-platform consistency. |

**Example:**

```plaintext
# Auto detect text files and perform LF normalization
* text=auto
```

.gitignore

| Pattern | What it Does | | -------------- | ----------------------------------------------------------------------- | | node_modules | Ignores the local dependencies folder (auto-generated by npm/yarn/pnpm) | | dist | Prevents build artifacts from being committed to source control |

Example:

node_modules
dist

postcss.config.mjs

This file configures PostCSS plugins used in your CSS processing pipeline.

Content:

export default { plugins: { "@tailwindcss/postcss": {} } };

• Enables: Tailwind CSS via PostCSS for advanced utility-first CSS support.
• Extensible: Add other PostCSS plugins as needed.

package.json

Your main npm manifest, describing the package, dependencies, scripts, and build definitions.

| Key | Description | | ------------------- | ---------------------------------------------------------------------------- | | name | Package name (bookez_software) | | version | Current version (1.0.1) | | keywords | Useful for npm search & discoverability (book-keeping, finance, plaid, etc.) | | license | MIT | | main/module/types | Entrypoints for CJS, ESM, and TypeScript types | | scripts | Build, Dev, and Lint commands | | peerDependencies | Ensures compatibility with React 18/19 (and ReactDOM) | | dependencies | UI, state, form, API, and chart utilities (see table below) | | devDependencies | Build, type, and style tooling | | exports | Dual ESM/CJS support |

Notable Dependencies

| Dependency | Purpose | | ------------------------------------------------ | -------------------------------------------------- | | @radix-ui/* | Accessible, headless React UI Primitives | | @tailwindcss/postcss, tailwindcss, postcss | Utility-first CSS framework, processed via PostCSS | | @tanstack/react-table | Advanced data grid and table rendering | | axios | HTTP client for API requests | | chart.js, react-chartjs-2, recharts | Data visualization and charting libraries | | class-variance-authority, clsx | Conditional CSS class management | | cmdk | Command palette UI | | date-fns, moment | Date/time processing utilities | | framer-motion | Animation and transition library | | lucide-react | Icon library | | next-themes | Theme switching for Next.js/React | | react-day-picker | Calendar and date-picker components | | react-hook-form | Form management and validation | | react-plaid-link | Plaid API integration for banking | | react-select | Select/Combobox UI component | | xlsx | Excel/CSV import and export |

package-lock.json

• Purpose: Locks the entire dependency tree for deterministic installs.
• Ensures: Same working set for every developer/CI run.
• Auto-generated: Do not edit manually.

readme.md

Your primary documentation and onboarding guide. Key sections:

• Project Summary: Overview, feature list.
• Getting Started: Prerequisites, installation steps, version requirements.
• Usage:
  • How to store tokens & settings in localStorage.
  • Provider/component usage in React tree.
  • Theme customization instructions (with property list).
  • Error/success callback handling.
• Scripts: Dev/build scripts for contributors.
• Project Structure: Directory layout and content purpose.
• License: MIT.

Core Architecture

Component Structure

Your library is composed of:

• Reusable UI Components: (Dropdowns, dialogs, skeleton loaders, checkboxes, etc.)
• Banking Data Table: Categorization, review, and management of bank transactions.
• Plaid Integration: Components and utilities for securely connecting bank accounts.
• Form Integration: Seamless integration with react-hook-form for validation.
• Providers: React context providers for global banking/account state.

Component Directory Tree (from README):

src/
  components/       # Reusable UI components
  pages/Banking/    # Banking-related pages and logic
  providers/        # React context providers
  axios/            # API utilities
  lib/              # Utility functions

Build & TypeScript Pipeline

Build Pipeline Flow

graph TD
  A["src/index.ts"] --> B["tsup (tsup.config.ts)"]
  B --> C["Transpile TypeScript to JS"]
  C --> D["Bundle (CJS + ESM)"]
  C --> E["Emit type declarations"]
  D & E --> F["dist/"]

• Entry: src/index.ts
• Bundler: tsup
• Outputs: CJS (index.js), ESM (index.mjs), types (index.d.ts), and sourcemaps.

Usage

UI Theming & Customization

The theme system is highly customizable via a BookEZTheme object. Both light and dark themes are supported, with granular controls for UI element colors, radii, borders, font weights, etc.

Example Theme Object Structure:

const BookEZTheme = {
  light: {
    btn_filled_bg: "",
    btn_filled_text_color: "",
    btn_filled_hover_bg: "",
    btn_filled_hover_color: "",
    btn_ghost_border_color: "",
    btn_ghost_hover_bg_color: "",
    btn_outlined_border_color: "",
    btn_outlined_font_color: "",
    btn_outlined_bg_color: "",
    btn_outlined_hover_bg_color: "",
    btn_outlined_hover_font_color: "",
    card_border_color: "",
    card_bg_color: "",
    card_bg_color_secondary: "",
    card_bg_color_secondary_light: "",
    card_bg_green: "",
    card_bg_blue: "",
    font_color_gray_1: "",
    font_color_gray_2: "",
    font_color_gray_3: "",
    font_color_header: "",
    font_color_green: "",
    font_color_green_light: "",
    font_color_blue: "",
    font_color_blue_dark: "",
    font_color_blue_light: "",
    font_color_yellow: "",
    font_color_yellow_light: "",
    font_color_filter_tab: "",
    font_applied_filter: "",
    table_header_text_color: "",
    table_text_color: "",
    table_header_bg_color: "",
    table_bg_stripe_color: "",
    table_bg_odd_stripe_color: "",
    table_border_color: "",
    revenue_bg: "",
    revenue_font_color: "",
    revenue_bg_light: "",
    expanse_bg: "",
    expanse_font_color: "",
    expanse_bg_light: "",
    net_profit_bg: "",
    net_profit_font_color: "",
    net_profit_bg_light: "",
    tab_bg_color_light: "",
    tab_active_bg_color: "",
    tab_active_font_color: "",
    select_bg: "",
    calender_hover_light: "",
    calender_selected_bg_color: "",
    calender_selected_color: "",
    calender_border_color: "",
    input_checked_color: "",
    error_text: "",
    error_transparent: "",
    error_border: "",
    accordion_bg: "",
    accordion_bg_active: "",
    accordion_hover: "",
    accordion_border_color: "",
    accordion_header_color: "",
    accordion_header_text_color: "",
    accordion_gross_profit_bg: "",
    accordion_gross_profit_text_color: "",
    accordion_net_profit_bg: "",
    accordion_net_profit_text_color: "",
    skeleton_bg: "",
    transaction_header_bg: "",
    transaction_card_bg: "",
    month_picker_font_color: "",
    month_picker_bg_hover: "",
    month_picker_border_color: "",
  },
  dark: {
    btn_filled_bg: "", // Dark blue for button background in dark mode
    btn_filled_color: "", // Light color for button text in dark mode
    // Add more properties as needed
  },
  globals: {
    card_radius: "12px",
    btn_border_radius: "8px",
    font_body_small: "12px",
    font_body_size: "14px",
    font_body_size_large: "16px",
    font_body_large: "20px",
    font_heading: "28px",
    font_body_bold: 600,
    font_body_bold_light: 400,
    font_body_bold_medium: 500,
    table_border_radius: "12px",
    tab_border_radius: "8px",
    input_border_radius: "8px",
  },
};

Store token, theme and currencyCode in localStorage

localStorage.setItem("BookezToken", "your-token-here");
localStorage.setItem("currencyCode", "your-currency-code");

Error and Success Handling

const handleError = (error) => {
  console.log("Error: ", error.message);
};

const handleSuccess = (
  apiType: "GET" | "POST" | "DOWNLOAD" | "OPTIONS",
  apiName: string,
  message: string
) => {
  console.log("Success: ", message);
};

Import and use components in your React app in order to use it:

import React from "react";
import { BookezUIProvider, BookezThemeProvider } from "bookez_software";
import App from "./App";

const Root = () => {
  const businessId = "your-business-id";
  const token = "your-token";
  return (
    <BookezUIProvider
      businessId={businessId}
      BookezToken={token}
      theme={"dark" | "light"}
      plaidClientUserName={ClientName}
      plaidClientUserId={ClientUserId}
      onError={handleError}
      onSuccess={handleSuccess}
    >
      <BookezThemeProvider theme={BookEZTheme}>
        <App />
      </BookezThemeProvider>
    </BookezUIProvider>
  );
};

TypeScript Project Settings

• Compile strictly with modern JS/DOM features.
• Only code in src/ is compiled.
• Outputs are placed in dist/.

Dependency Management

Peer Dependencies

• Ensures host app provides React & ReactDOM (v18 or v19).
• Prevents version conflicts in consumer projects.

Core Dependencies

• UI Primitives: @radix-ui
• State/Table: @tanstack/react-table, react-hook-form
• Styling: Tailwind CSS, PostCSS
• API/HTTP: axios
• Date/Time: date-fns, moment
• Charts: chart.js, react-chartjs-2, recharts
• Icons: lucide-react
• Utilities: class-variance-authority, clsx, xlsx, cmdk, framer-motion

Development Workflow

| Command | Description | | --------------- | ----------------------------------------------- | | npm run dev | Starts tsup in watch mode for rapid development | | npm run build | Builds and bundles for production |

Recommended Prerequisites:

• Node.js 20.19.0
• npm 9+
• React 18+

Conclusion

BookEz Software provides a robust, modern, and highly customizable set of banking/accounting UI components for React. With strong TypeScript support, seamless theming, and a modern build pipeline, it's ready for integration into financial SaaS applications and dashboards.

License: MIT

For more details and usage examples, see the readme.md section above.

🚀 Happy Building!