@blackpurl/bp-react-components 1.0.0

package/README.md

@@ -0,0 +1,384 @@
+# BP React Components
+
+A reusable React-based table component system built with:
+
+- React (Vite)
+- MUI (Material UI)
+- Minimal template
+- TanStack React Table
+- dnd-kit (column drag & drop)
+- Storybook for component development
+
+---
+
+## Getting Started
+
+### 1. Clone the repository
+
+```bash
+git clone <your-repository-url>
+cd bp-react-component
+```
+
+### 2. Install dependencies
+
+```bash
+npm install
+```
+
+---
+
+## Run the Application
+
+Start the development server:
+
+```bash
+npm run dev
+```
+
+Open in browser:
+
+```
+http://localhost:5173
+```
+
+---
+
+## Run Storybook
+
+Start Storybook:
+
+```bash
+npm run storybook
+```
+
+Open in browser:
+
+```
+http://localhost:6006
+```
+
+---
+
+## Project Structure
+
+```
+src
+│   ├── components
+│   │
+│   │   ├── BPTable
+│   │   │
+│   │   │   ├── components
+│   │   │   │   └── dataGridTable
+│   │   │   │       ├── grid-table-row.jsx          # Row rendering logic for DataGrid table
+│   │   │   │       ├── list-view.jsx               # Main table view component
+│   │   │   │       ├── sortable-header.jsx         # Drag-and-drop column header component
+│   │   │   │       ├── status-tabs-grouping.jsx    # Status based tab grouping for table data
+│   │   │   │       ├── table-data-grid-filter-drawer.jsx  # Drawer component for table filters
+│   │   │   │       ├── table-filters.jsx           # Filter UI for DataGrid table
+│   │   │   │       ├── table-filters-result.jsx    # Selected filter results display
+│   │   │   │       └── table-header-dnd.jsx        # Drag-and-drop logic for table headers
+│   │   │
+│   │   │   ├── utils                               # Utility/helper functions for BPTable
+│   │   │
+│   │   │   ├── BPTable.stories.jsx                 # Storybook configuration for table component
+│   │   │   ├── cellRenderers.jsx                   # Custom cell rendering logic
+│   │   │   ├── columns.js                          # Column configuration definitions
+│   │   │   ├── index.jsx                           # BPTable main export
+│   │   │   └── mockData.js                         # Sample/mock data for development and Storybook
+│   │
+│   │   ├── custom-dialog                          # Reusable dialog component
+│   │   ├── custom-popover                         # Reusable popover component
+│   │   ├── empty-content                          # Empty state component
+│   │   ├── filters-result                         # Filter result display components
+│   │   ├── iconify                                # Icon wrapper component
+│   │   ├── label                                  # Label UI components
+│   │   └── snackbar                               # Snackbar / notification component
+│   │
+│   └── stories                                    # Additional Storybook stories
+
+```
+
+---
+
+## Theme
+
+BPTable comes with a built-in Minimal UI theme.  
+No additional theme setup is required from the application side.
+
+The application uses a custom MUI theme wrapped inside:
+
+```
+src/theme/theme-wrapper.jsx
+```
+
+Storybook is configured to use the same theme via:
+
+```
+.storybook/preview.jsx
+```
+
+---
+
+## Features
+
+- Column drag & drop
+- Column resizing
+- Column visibility toggle
+- Row selection (controlled & uncontrolled)
+- Global search
+- Column filters (Drawer with accordion groups)
+- Grouping support
+- Pagination
+- Fully theme-aware UI
+
+---
+
+## Development Notes
+
+- The project uses Vite.
+- JSX files must use the `.jsx` extension.
+- Storybook preview file must also be `.jsx` if JSX is used.
+- Theme is applied globally using `ThemeWrapper`.
+
+---
+
+## 📦 Installation
+
+```bash
+npm install bp-react-components
+```
+---
+
+## 🔗 Peer Dependencies
+
+Make sure these are installed in your application:
+```bash
+npm install @mui/material @mui/x-data-grid react react-dom
+```
+---
+
+# 📦 Component Usage (BPTable)
+
+## Basic Example
+
+```jsx
+import BPTable from 'bp-react-components';
+
+<BPTable
+  data={data}
+  columns={columns}
+  getRowId={(row) => row.id}
+/>
+
+## ⚙️ Props
+
+| Prop                     | Type     | Default      | Description                         |
+|--------------------------|----------|--------------|-------------------------------------|
+| data                     | array    | []           | Table data                          |
+| columns                  | array    | []           | Column configuration                |
+| getRowId                 | function | required     | Unique row identifier               |
+| isLoading                | boolean  | false        | Show loading state                  |
+| enablePagination         | boolean  | true         | Enable pagination                   |
+| enableGrouping           | boolean  | false        | Enable tab grouping                 |
+| enableRowSelection       | boolean  | false        | Enable checkbox selection           |
+| enableColumnSorting      | boolean  | true         | Enable sorting                      |
+| enableColumnResize       | boolean  | false        | Enable column resizing              |
+| enableColumnReorder      | boolean  | false        | Enable drag & drop                  |
+| enableColumnVisibility   | boolean  | false        | Toggle column visibility            |
+| enableColumnFilters      | boolean  | true         | Enable filter drawer                |
+| enableGlobalFilter       | boolean  | true         | Enable global search                |
+| enableDensityToggle      | boolean  | false        | Toggle row density                  |
+| storageKey               | string   | undefined    | Enable local storage persistence    |
+| selectedRows             | array    | []           | Selected row IDs                    |
+| onSelectedRowsChange     | function | undefined    | Selection change handler            |
+| onRowClick               | function | undefined    | Row click handler                   |
+| rowActions               | function | undefined    | Dynamic row actions                 |
+| dateFormatter            | function | undefined    | Custom date formatting              |
+| currency                 | string   | 'USD'        | Currency code                       |
+| locale                   | string   | 'en-US'      | Locale                              |
+
+---
+
+## 🧱 Column Configuration
+
+```javascript
+const columns = [
+  {
+    accessorKey: 'DealStatus',
+    header: 'Deal Status',
+    type: 'Label',
+    isFilterable: true,
+  },
+];
+```
+
+---
+
+## 🎨 Supported Column Types
+
+| Type    | Description          |
+| ------- | -------------------- |
+| Label   | Status label         |
+| Date    | Date + time display  |
+| Amount  | Currency formatting  |
+| Avatar  | Avatar / AvatarGroup |
+| Number  | Numeric value        |
+| Boolean | Yes / No             |
+| Rating  | Star rating          |
+| Action  | Row actions          |
+
+---
+
+## 📅 Date Formatting
+
+Pass custom formatter from application:
+
+```jsx
+<BPTable
+  dateFormatter={(value) =>
+    moment(value).format('DD MMM YYYY')
+  }
+/>
+```
+
+---
+
+## 💰 Currency Formatting
+
+```jsx
+<BPTable
+  currency="USD"
+  locale="en-US"
+/>
+```
+
+---
+
+## ⚡ Row Actions
+
+```javascript
+const getRowActions = (row) => [
+  {
+    type: 'icon',
+    icon: 'solar:eye-bold',
+    label: 'View',
+    onClick: () => handleView(row),
+  },
+  {
+    type: 'button',
+    label: 'Edit',
+    variant: 'contained',
+    onClick: () => handleEdit(row),
+  },
+];
+```
+
+```jsx
+<BPTable rowActions={getRowActions} />
+```
+
+---
+
+## 🏷️ Custom Cell Renderer
+
+```javascript
+{
+  accessorKey: 'DealStatus',
+  type: 'Label',
+  cellRenderer: (value) => <Label>{value}</Label>
+}
+```
+
+---
+
+## 👤 Avatar Customization
+
+```javascript
+{
+  accessorKey: 'SalespersonNames',
+  type: 'Avatar',
+  getAvatarProps: (name) => ({
+    sx: { bgcolor: getColor(name) },
+    children: name[0]
+  })
+}
+```
+
+---
+
+## 🔍 Filtering
+
+* Global search supported
+* Column-based filtering
+* Dynamic filter drawer (based on `isFilterable`)
+
+---
+
+## 📦 Persistence
+
+Enable local storage:
+
+```jsx
+<BPTable storageKey="my-table" />
+```
+
+Automatically persists:
+
+* Pagination
+* Filters
+* Column order
+* Column visibility
+* Density
+
+---
+
+## 🎯 Row Click Handling
+
+```jsx
+<BPTable
+  onRowClick={(row) => {
+    console.log('Clicked:', row);
+  }}
+/>
+```
+
+---
+
+## 🎨 Styling & Theme
+
+* Uses Minimal UI theme internally
+* Fully isolated using Emotion cache
+* Works alongside external application themes
+
+---
+
+## 📖 Storybook (Recommended)
+
+👉 View full interactive documentation:
+
+**[Add your Chromatic link here]**
+
+---
+
+## ⚠️ Notes
+
+* Column widths are configurable (`size`, `minSize`, `maxSize`)
+* Supports dynamic rendering from application side
+* Avoid overriding internal styles unless necessary
+
+---
+
+## 🧑‍💻 Development
+
+```bash
+npm install
+npm run dev
+npm run build
+```
+
+---
+
+## 📜 License
+
+Internal use only (Blackpurl)