mui-react-components/README.md

Custom Mui Components

A powerful, modular, and developer-friendly React component suite built on top of Material-UI, designed to simplify complex UI needs for enterprise-grade applications. This suite enhances your design system with rich UX patterns, interactive UI behavior, loading skeletons, and advanced data grid functionality — all while maintaining consistency, performance, and accessibility.

**Note**: This lightweight and type-safe package is written in TypeScript and offers full support for all hooks across all modern browsers.

## Installation

Install the package:

```bash
npm install mui-react-components
# or
pnpm add mui-react-components
```

## Authors

![NPM](https://img.shields.io/badge/Author-React_Developers-red) ![npm](https://img.shields.io/npm/v/mui-react-components?color=1C939D) ![npm](https://img.shields.io/npm/dt/mui-react-components) ![NPM](https://img.shields.io/npm/l/mui-react-components) ![NPM](https://img.shields.io/npm/unpacked-size/mui-react-components)

## Features

### ✅ ContextMenuWrapper

Displays a customizable context menu with support for light/dark themes, keyboard navigation, accessibility compliance, and automatic positioning. Handles items, dividers, icons, shortcuts, and click events.

```tsx
<ContextMenuWrapper
  options={[
    { label: 'Edit', icon: <EditIcon />, onClick: handleEdit },
    { label: 'Copy', shortcut: '⌘C', onClick: handleCopy },
    'divider',
    { label: 'Delete', disabled: true, onClick: handleDelete }
  ]}
  theme="dark"
  onShow={() => console.log('Menu opened')}
  onHide={() => console.log('Menu closed')}
  currentInstance={this}
>
  <div>Right-click here</div>
</ContextMenuWrapper>
```

### ✅ AnimatedWrapper

A lightweight wrapper component that applies animations to its children with customizable animation type and delay. Ideal for enhancing UI transitions smoothly.

```tsx
<AnimatedWrapper animationClass="animate__fadeIn" delay={1}>
  <div>Hello with delay</div>
</AnimatedWrapper>
```

### ✅ RichTextEditor

Provides a fully-featured WYSIWYG editor with HTML conversion, customizable toolbar, and responsive design for rich text input.

```tsx
<RichTextEditor
  initialHtml="<p>Initial content</p>"
  onChange={(html) => console.log(html)}
  placeholder="Type your text here..."
  minHeight="300px"
/>
```

### ✅ FilePreview

Displays a styled file card with an icon based on file type, filename with ellipsis handling, file size, and an optional download action.

```tsx
<FilePreview
  primaryKey="file123"
  filename="example.pdf"
  size="2.3 MB"
  onDownload={(id) => console.log('Download:', id)}
/>
```

### ✅ UploadFile

Renders an icon button for file uploads with visual feedback for different upload states (loading, success, error). It supports disabling, color customization, and a hidden file input for seamless UX.

```tsx
<UploadFile
  isUpload={true}
  color="#1976d2"
  state={{
    isUploaded: false,
    isUploadError: false,
    isLoadingUpload: true,
  }}
  onFileSelect={(file) => console.log(file)}
/>

const handleFileSelect = async (files: any) => {
  setState({ isUploaded: false, isUploadError: false, isLoadingUpload: true });

  try {
    await _promise(2000);
    setState({ isUploaded: true, isUploadError: false, isLoadingUpload: false });
  } catch (err) {
    setState({ isUploaded: false, isUploadError: true, isLoadingUpload: false });
  }
};
```

### ✅ DownloadFile

Renders an icon button for file downloads with visual feedback for different states (loading, success, error). It supports color customization and disables interaction during loading.

```tsx
<DownloadFile
  isDownload={true}
  color="primary"
  state={{
    isDownloaded: false,
    isDownloadError: false,
    isLoadingDownload: true,
  }}
  onDownload={() => console.log('Download initiated')}
/>
```

### ✅ LabeledValue

Displays a simple key-value label pair in a single line, with optional styling.

```tsx
<LabeledValue label="Name" value="ABC" />
```

### ✅ DetailsCard

Renders a card with a title and grid-based layout of labeled values. It supports custom spacing, responsive behavior, and optional card shadow.

```tsx
<DetailsCard title="Details" spacing={2} details={[{ label: 'Name', value: 'XYZ' }]} />
```

### ✅ FieldSkeleton

Simulates form field placeholders with optional label skeletons, useful for loading states in forms or input sections.

```jsx
<FieldSkeleton length={3} spacing={2} isLabel={true} responsive={{ xs: 12, sm: 6, md: 4 }} />
```

### ✅ FileSkeleton

Displays one or more placeholder file cards mimicking the layout of file previews. Useful during file list loading.

```tsx
<FileSkeleton length={3} width={350} borderColor="#dfdfdf" />
```

### ✅ TableSkeleton

Shows a full table layout with skeleton headers and rows. Includes a toolbar area for filters or search bars.

```tsx
<TableSkeleton rows={6} columns={6} />
```

### ✅ CardSkeleton

Simulates a card layout with a title and multiple row placeholders, ideal for stat or summary cards.

```tsx
<CardSkeleton />
```

### ✅ LineChartSkeleton

Represents a placeholder for a line chart with gridlines and axis lines to simulate loading of chart data.

```tsx
<LineChartSkeleton />
```

### ✅ PieChartSkeleton

Displays a skeleton placeholder for a pie chart inside a card layout. Includes a title and circular loading element.

```tsx
<PieChartSkeleton />
```

## ✅ MuiDataGrid

The `MuiDataGrid` is a **powerful and reusable data table component** designed to support complex UI/UX needs like formatting, interactivity, actions, and advanced data handling.

### Features

#### 1. **Text Column**
```js
{ field: 'adjustmentName', headerName: 'Name', width: 200 }
```
* Shows plain text with fixed width
* Auto truncation via `textEllipsis`

#### 2. **Currency Formatting**
```js
{ field: 'adjustmentAmount', dataType: 'currency', currencyOptions: { currencyCode: 'USD', decimal: 2 }, align: 'right' }
```
* Formats numbers as currency
* Right-aligned for readability

#### 3. **Boolean/Status**
```js
{ field: 'adjustmentStatus', dataType: 'boolean' }
```
* Visual true/false representation

#### 4. **Date Formatting**
```js
{ field: 'adjustmentDate', dataType: 'Date', dateFormat: 'MMM DD, YYYY' }
```
* Human-readable date display

#### 5. **Progress Bar**
```js
{ field: 'completionPercent', dataType: 'progress' }
```
* Visual percentage indicator

#### 6. **Feedback/Rating**
```js
{ field: 'qualityRating', dataType: 'feedback' }
```
* Star-based visual rating

#### 7. **Custom Actions**
```js
{
  field: 'actions',
  renderCell: (row) => <Button onClick={() => handleAction(row)}>Process</Button>
}
```

### Example Usage

```jsx
const columns = [
  // Basic string with ellipsis
  {
    field: 'name',
    headerName: 'Name',
    width: 200,
  },

  // Currency
  {
    field: 'amount',
    headerName: 'Amount',
    dataType: 'currency',
    currencyOptions: {
      currencyCode: 'USD',
      decimal: 2,
    },
    align: 'right',
  },

  // Status (boolean)
  {
    field: 'status',
    headerName: 'Status',
    dataType: 'boolean',
  },

  // Date
  {
    field: 'Date',
    headerName: 'Date',
    dataType: 'Date',
    dateFormat: 'MMM DD, YYYY',
  },

  // Progress
  {
    field: 'completionPercent',
    headerName: 'Completion',
    dataType: 'progress',
  },

  // Rating
  {
    field: 'rating',
    headerName: 'Quality',
    dataType: 'feedback',
  },

  // Custom render
  {
    field: 'actions',
    headerName: 'Actions',
    renderCell: (row) => (
      <Button variant="outlined" onClick={() => handleAction(row)}>
        Process
      </Button>
    ),
  },
];

const onUpload = async (data: any) => {
  console.log('Data:', data);
  return new Promise() < string > ((resolve) => setTimeout(() => resolve('success'), 2000));
};

const onDownload = () => {
  return new Promise((resolve) => {
    setTimeout(() => {
      resolve({
        data: [{ name: 'John Doe', age: 30 }],
        filename: 'test',
        extension: '.xlsx',
      });
    }, 1000);
  });
};

<MuiDataGrid
  data={data}
  isLoading={isLoading}
  columns={columns}
  childrens={expandableColumns}
  options={{
    height: 600,
    color: '#3f51b5',
    fontSize: '0.875rem',
    headerBackgroundColor: '#f5f5f5',
    enableStrikyHeader: true,
    enableSerialNumber: true,
    enableCellClick: true,
    textEllipsis: 30,

    // Pagination
    paginationOptions: {
      rowPerPage: [5, 10, 20],
      isFirstLastPageButton: true,
      isTotalRows: true,
      onPageClick: handlePageChange,
      pageNumber: page,
      pageSize: pageSize,
      totalCount: totalCount,
    },

    // Toolbar
    toolbarOptions: {
      onUpload: handleImport,
      onDownload: handleExport,
      isManageColumn: true,
      enableDeleteAll: true,
      toolbarActions: [
        {
          icon: SaveAlt,
          tooltip: 'Export',
          onClick: () => console.log('Export clicked'),
        },
        {
          icon: CloudUpload,
          tooltip: 'Import',
          onClick: () => console.log('Import clicked'),
        },
      ],
    },

    // Row actions
    rowActions: [
      {
        icon: Visibility,
        color: 'primary',
        tooltip: 'View',
        onClick: handleView,
      },
      {
        icon: Edit,
        color: 'secondary',
        tooltip: 'Edit',
        onClick: handleEdit,
      },
      {
        icon: Delete,
        color: 'error',
        tooltip: 'Delete',
        onClick: handleDelete,
      },
    ],

    // Filtering
    filterOptions: {
      enableMultipleColumnSelection: true,
      onQuerySearch: (value, columns) => {
        console.log(`Searching for "${value}" in columns:`, columns);
        // Implement your search logic here
      },
    },

    // Currency formatting
    currencyOptions: {
      currencyCode: 'USD',
      locale: 'en-US',
      decimal: 2,
    },

    // Date formatting
    dateFormat: 'MMM DD, YYYY HH:mm',
  }}
/>;
```

## License

MIT
```