bookez_package

````markdown # 📚 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:** ```plaintext node_modules dist ``` --- ### `postcss.config.mjs` This file configures **PostCSS** plugins used in your CSS processing pipeline. **Content:** ```js 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):** ```plaintext 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 ```mermaid 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:** ```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", }, }; ``` --- ### 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); }; ``` ### Import and use components in your React app in order to use it: ```tsx 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](#readmemd) section above.** --- ## 🚀 Happy Building!