bookez_test/readme.md

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

# BookEz React Components

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

Use full page layouts we've already tested and used or layout individual components however you choose.
Brand components with your company colors, fonts, and more.

All you need to get started is our development credentials.

# Overview

**BookEz** 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.

## Installation

```plaintext
npm install bookez
```

or

```plaintext
yarn install bookez
```

## Usage

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.

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

```tsx
import React from "react";
import { BookezUIProvider, BookezThemeProvider } from "bookez";

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>
  );
};
```

### Store token, theme and currencyCode in localStorage

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

### Error and Success Handling

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

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

# Components

### Bank Accounts & Transactions

#### Linked Accounts & Transaction Categorization

**LinkedAccountscomponent** Displays all accounts connected to Layer including embedded banking, Plaid, and custom accounts.

**BankingData** component handles displaying both categorized transactions and the workflow for categorizing new transactions as they are imported into Layer.

```tsx
import { Banking } from "bookez";

<Banking>
  <Banking.LinkedAccountsComponent title="" />
  <Banking.BankingData />
</Banking>;
```

#### Props

- `title` (Optional): The title of the Linked Account section. Default: `"Banking"`.

### Reporting

#### Profit And Loss Chart

```tsx
import {
  Accounting,
  DetailedCharts,
  Expanse,
  Revenue,
  Summaries,
} from "bookez";

<Accounting>
  <Summaries
    stringOverrides={{
      title: "Dashboard",
      revenueLabel: "Revenue",
      expensesLabel: "Expenses",
      netProfitLabel: "Net Profit",
    }}
  />
  <DetailedCharts />
  <Revenue />
  <Expanse />
</Accounting>;
```

Here are details of component:

- **Summaries** Displays Summary of Revenue, Exapnse and Net Profit.

- **DetailedCharts** Displays chart view of Revenue, Exapnse.

- **Revenue** component is responsible for displaying categorized revenue in a pie chart view and Table Grid.

- **Expanse** component handles displaying categorized Expanse and Table Grid.

#### Props

- `stringOverrides` (Optional): Labels for summary. Default values are given in above example.

### Invoice

The Invoice component provides a comprehensive view of invoices along with an optional filter panel to categorize and display them. It includes features for filtering by status, startDate, and endDate. The filters are customizable, and you can choose which filters to display via the allowableFields prop.

#### Component Structure

The component consists of two main sub-components:

**InvoiceFilter** Allows users to filter invoices based on specific fields.

**InvoiceTable** Displays the filtered invoice data in a table.

#### Usage

```tsx
import { Invoice } from "bookez";

<Invoice>
  <Invoice.InvoiceFilter
    title="Invoices"
    clearFilterText="clear all Filters"
    btnText="Apply Filter"
    FilterFieldsLabel={{
      status: "Select Status",
      startDate: "Invoice Start Date",
      endDate: "Invoice End Date",
    }}
    allowableFields={["status", "startDate", "endDate"]}
  />
  <Invoice.InvoiceTable />
</Invoice>;
```

#### Props

All Props are optional. Default values are given in Above example of usage.

- `title` (Optional): The title of the filter section. Default: `"Invoices"`.

- `clearFilterText` (Optional): Text for the "clear filters" button. Default: `"Clear all Filters"`.

- `btnText` (Optional): Text for the "apply filter" button. Default: `"Apply Filter"`.

- `FilterFieldsLabel` (Optional): Labels for filter fields. This should be an object with keys as the filter field names (status, startDate, endDate), and their corresponding values as the display labels. Default labels are:

  - `status`: `"Select Status"`

  - `startDate`: `"Invoice Start Date"`

  - `endDate`: `"Invoice End Date"`

  - `allowableFields` (Optional): An array of filter fields that you want to display in the filter UI. Valid values are:

    - `"status"` (for selecting the invoice status)

    - `"startDate"` (for selecting the invoice start date)

    - `"endDate"` (for selecting the invoice end date)

### Customer

The Customer component provides a comprehensive view of customer data.

#### Usage

```tsx
import { Customer } from "bookez";

<Customer>
  <Customer.CustomerTable title="Customers" isSearch={true} filter={true} />
</Customer>;
```

#### Props

All Props are optional. Default values are given in Above example of usage.

- `title` (Optional): The title of the Customer section. Default: `"Customers"`.

- `isSearch` (Optional): Specifies whether the search filter is required for the component. When enabled, it allows users to search through the displayed data.. Default: `true`.

- `filter` (Optional): Defines whether filtering (including the archive filter) is enabled. If true, it allows users to apply filters, including viewing archived items.. Default: `true`.

### Payment

The Payment component provides a comprehensive view of payments along with an optional filter panel to categorize and display them. It includes features for filtering by status, startDate, and endDate. The filters are customizable, and you can choose which filters to display via the allowableFields prop.

#### Component Structure

The component consists of two main sub-components:

**PaymentFilter** Allows users to filter payments based on specific fields.

**PaymentTable** Displays the filtered payment data in a table.

#### Usage

```tsx
import { Payment } from "bookez";

<Payment>
  <Payment.PaymentFilter
    title="Payments"
    clearFilterText="Clear all Filter"
    btnText="Apply Filter"
    FilterFieldsLabel={{
      status: "Select Payment Method",
      startDate: "Payment Start Date",
      endDate: "Payment End Date",
      customer: "Select Customer",
    }}
    allowableFields={["status", "startDate", "endDate", "customer"]}
  />
  <Payment.PaymentTable />
</Payment>;
```

#### Props

All Props are optional. Default values are given in Above example of usage.

- `title` (Optional): The title of the filter section. Default: `"Invoices"`.

- `clearFilterText` (Optional): Text for the "clear filters" button. Default: `"Clear all Filters"`.

- `btnText` (Optional): Text for the "apply filter" button. Default: `"Apply Filter"`.

- `FilterFieldsLabel` (Optional): Labels for filter fields. This should be an object with keys as the filter field names (status, startDate, endDate), and their corresponding values as the display labels. Default labels are:

  - `status`: `"Select Status"`

  - `startDate`: `"Invoice Start Date"`

  - `endDate`: `"Invoice End Date"`
  - `customer`: `"Select Customer"`

  - `allowableFields` (Optional): An array of filter fields that you want to display in the filter UI. Valid values are:

    - `"status"` (for selecting the invoice status)

    - `"startDate"` (for selecting the invoice start date)

    - `"endDate"` (for selecting the invoice end date)
    - `"customer"` (for selecting the customer)

### Reports

The Report component provides a comprehensive report for data.

#### Usage

```tsx
import { Report } from "bookez";

<Report
  stringOverrides={{
    netProfitLabel: "Net Profit",
    profitBeforeTaxesLabel: "Profit Before Taxes",
  }}
  withDownloadButton={true}
/>;
```

#### Props

All Props are optional. Default values are given in Above example of usage.

- `withDownloadButton` (Optional): whether user can download report for the Records. Default: `true`.

- `stringOverrides` (Optional): Labels for reports. This should be an object with keys as the filter field names (netProfitLabel, profitBeforeTaxesLabel), and their corresponding values as the display labels. Default labels are:

  - `netProfitLabel`: `"Net Profit"`

  - `profitBeforeTaxesLabel`: `"Profit Before Taxes"`

### General Ledger

#### Usage

```tsx
import { GeneralLedger } from "bookez";

<GeneralLedger
  withExpandAllButton={true}
  withDownloadButton={true}
  stringOverrides={{
    chartOfAccountTable: {
      addAccountButtonText: "Add Account",
      nameColumnHeader: "Name",
      typeColumnHeader: "Type",
      balanceColumnHeader: "Balance",
      subtypeColumnHeader: "Sub-Type",
    },
    journalTable: {
      idLabel: "Entry ID",
      dateLabel: "Date",
      accountLabel: "Accounts",
      transactionLabel: "Transaction",
      debitLabel: "Debit",
      creditLabel: "Credit",
    },
    journalEntry: {
      modalLabel: "Transaction source",
      sourceDetails: {
        label: "Source Information",
        sourceLabel: "Source",
        recipientLabel: "Recipient Name",
        dateLabel: "Remarks",
      },
      invoice: {
        invoiceTagLabel: "Invoice Tag",
        invoiceAmountTagLabel: "Invoice Amount",
      },
      transactionTimeLine: {
        transactionLabel: "Transaction",
        effectiveDateLabel: "Voucher Date",
        creationDateLabel: "Voucher CreationDate",
        reversalLabel: "Reversal",
      },
      journalDetails: {
        headerLabel: "Journal Details",
        accountLabel: "Account",
        debitLabel: "Debit",
        creditLabel: "Credit",
        totalLabel: "Total",
      },
      paymentDetails: {
        headerLabel: "Payment Details",
        paymentTagLabel: "Payment ID",
        totalLabel: "Total Amount",
        paymentDateLabel: "Payment Date",
      },
      invoiceList: {
        invoiceTableHeaderLabel: "Invoice List",
        invoiceIdLabel: "Invoice ID",
        invoiceAmountLabel: "Invoice Amount",
        redemptionTypeAccountLabel: "Redemption Type Account",
      },
      creditMemoList: {
        creditMemoTableHeaderLabel: "Credit Memo List",
        creditMemoIdLabel: "Credit Memo ID",
        creditMemoAmountLabel: "Amount",
        creditMemoDateLabel: "Date",
      },
      voucherWriteOffDetails: {
        headerLabel: "Voucher Details",
        voucherIdLabel: "Voucher ID",
        totalAmountLabel: "Total Amount",
        writeOffDateLabel: "Payment Date",
      },
      refundDetails: {
        headerLabel: "Refund Details",
        refundIdLabel: "Refund ID",
        totalAmountLabel: "Total Amount",
        refundDateLabel: "Refund Date",
      },
    },
    listing: {
      dateLabel: "Date",
      journalIdLabel: "Journal ID",
      sourceLabel: "Source",
      debitLabel: "Debit",
      creditLabel: "Credit",
      runningBalanceLabel: "Running Balance",
    },
  }}
/>;
```

#### Props

All Props are optional. Default values are given in Above example of usage.

- `withExpandAllButton` (Optional): whether user can expand collpase report for the Records. Default: `true`.
- `withDownloadButton` (Optional): whether user can download report for the Records. Default: `true`.

- `stringOverrides` (Optional): Labels for reports. This should be an object with keys as the filter field names, and their corresponding values as the display labels. Default labels are:

  - default values given in above example.

---

### 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:**

```tsx
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",
  },
};
```

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

---