@fertilizer-shop/ag-grid-components

A comprehensive, reusable AG Grid component library for React applications with modern TypeScript support, enhanced performance, and rich feature set.

Features

• 🚀 Modern React Patterns: Built with React 18+ hooks and TypeScript
• 🎨 Rich Cell Renderers: Currency, Date, Status, Boolean, and Action renderers
• 📊 Export Capabilities: CSV, Excel, and PDF export with customization
• 🔍 Advanced Filtering: Quick filter, column filters, and custom filter options
• 📱 Responsive Design: Mobile-friendly toolbar and grid layout
• ⚡ Performance Optimized: Virtual scrolling, debounced operations, and memory management
• 🎯 Accessibility: ARIA labels, keyboard navigation, and screen reader support
• 🛠️ Highly Configurable: Extensive configuration options for all features
• 📈 Performance Monitoring: Built-in performance metrics and optimization suggestions

Installation

npm install @fertilizer-shop/ag-grid-components
# or
yarn add @fertilizer-shop/ag-grid-components

Peer Dependencies

Make sure you have the following peer dependencies installed:

npm install react react-dom ag-grid-react ag-grid-community antd dayjs

Quick Start

import React from 'react';
import { DataGrid, GridColumn, GridAction } from '@fertilizer-shop/ag-grid-components';

const MyComponent = () => {
  const data = [
    { id: 1, name: 'Product 1', price: 100, status: 'active', date: '2023-01-01' },
    { id: 2, name: 'Product 2', price: 200, status: 'inactive', date: '2023-01-02' },
  ];

  const columns: GridColumn[] = [
    { field: 'name', headerName: 'Product Name', width: 200 },
    { field: 'price', headerName: 'Price', type: 'currency', width: 120 },
    { field: 'status', headerName: 'Status', type: 'status', width: 100 },
    { field: 'date', headerName: 'Date', type: 'date', width: 120 },
  ];

  const actions: GridAction[] = [
    {
      id: 'edit',
      icon: 'edit',
      tooltip: 'Edit Product',
      onClick: (data) => console.log('Edit:', data),
      color: '#1890ff'
    },
    {
      id: 'delete',
      icon: 'delete',
      tooltip: 'Delete Product',
      onClick: (data) => console.log('Delete:', data),
      color: '#ff4d4f',
      confirmMessage: 'Are you sure you want to delete this item?'
    }
  ];

  return (
    <DataGrid
      data={data}
      columns={columns}
      actions={actions}
      enableExport={true}
      enableSearch={true}
      enableSelection={true}
      height={400}
    />
  );
};

Components

DataGrid

The main grid component with comprehensive features.

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | data | any[] | - | Grid data array | | columns | GridColumn[] | - | Column definitions | | actions | GridAction[] | [] | Row action buttons | | loading | boolean \| LoadingState | false | Loading state | | error | boolean \| ErrorState | false | Error state | | config | GridConfig | {} | Grid configuration | | height | number \| string | 500 | Grid height | | enableExport | boolean | true | Enable export functionality | | enableSearch | boolean | true | Enable quick search | | enableSelection | boolean | false | Enable row selection |

Cell Renderers

CurrencyCellRenderer

Renders currency values with proper formatting and localization.

const column: GridColumn = {
  field: 'price',
  headerName: 'Price',
  type: 'currency',
  cellRenderer: CurrencyCellRenderer,
  cellRendererParams: {
    config: {
      currency: 'INR',
      locale: 'en-IN',
      symbol: '₹'
    }
  }
};

StatusCellRenderer

Renders status values as colored badges with icons.

const column: GridColumn = {
  field: 'status',
  headerName: 'Status',
  type: 'status',
  cellRenderer: StatusCellRenderer,
  cellRendererParams: {
    config: {
      active: { color: '#52c41a', text: 'Active', variant: 'success' },
      inactive: { color: '#d9d9d9', text: 'Inactive', variant: 'default' }
    }
  }
};

DateCellRenderer

Renders dates with formatting and relative time indicators.

const column: GridColumn = {
  field: 'createdAt',
  headerName: 'Created',
  type: 'date',
  cellRenderer: DateCellRenderer,
  cellRendererParams: {
    config: {
      format: 'DD/MM/YYYY',
      showTime: false,
      highlightToday: true
    }
  }
};

ActionCellRenderer

Renders action buttons with loading states and permissions.

const actions: GridAction[] = [
  {
    id: 'edit',
    icon: 'edit',
    tooltip: 'Edit Item',
    onClick: async (data) => {
      // Handle edit action
    },
    disabled: (data) => data.status === 'locked',
    loading: (data) => editingIds.includes(data.id)
  }
];

Configuration

Grid Configuration

const config: GridConfig = {
  pagination: {
    enabled: true,
    pageSize: 50,
    pageSizeOptions: [25, 50, 100, 200]
  },
  selection: {
    mode: 'multiple',
    checkboxSelection: true
  },
  sorting: {
    enabled: true,
    multiSort: true
  },
  filtering: {
    enabled: true,
    quickFilter: true,
    floatingFilter: true
  },
  virtualization: {
    enabled: true,
    rowBuffer: 10
  }
};

Export Configuration

const exportOptions: ExportOptions = {
  filename: 'my-export',
  format: 'excel',
  title: 'Product Report',
  subtitle: 'Generated on ' + new Date().toLocaleDateString(),
  includeHeaders: true,
  customStyles: {
    header: { fontWeight: 'bold', backgroundColor: '#f0f0f0' },
    cell: { fontSize: '12px' }
  }
};

Hooks

useGridState

Manages grid state with reducer pattern.

import { useGridState } from '@fertilizer-shop/ag-grid-components';

const { gridState, updateGridState } = useGridState({
  columns,
  data,
  loading: { loading: false },
  error: { error: false }
});

useGridExport

Handles data export functionality.

import { useGridExport } from '@fertilizer-shop/ag-grid-components';

const { exportData } = useGridExport(gridApi, data, columns);

// Export to Excel
exportData({ format: 'excel', filename: 'report' });

useGridPerformance

Monitors and optimizes grid performance.

import { useGridPerformance } from '@fertilizer-shop/ag-grid-components';

const { metrics, startMeasurement, endMeasurement } = useGridPerformance(true);

Styling

The components use CSS-in-JS for styling and support theme customization:

const theme: GridTheme = {
  name: 'custom',
  primaryColor: '#1890ff',
  backgroundColor: '#ffffff',
  borderColor: '#d9d9d9'
};

<DataGrid theme={theme} ... />

Performance Tips

1. Enable Virtualization: For large datasets (>1000 rows)
2. Use Column Types: Leverage built-in column types for better performance
3. Debounce Search: Quick filter is automatically debounced
4. Optimize Cell Renderers: Keep custom renderers lightweight
5. Monitor Performance: Use enablePerformanceMonitoring in development

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import type { 
  GridColumn, 
  GridAction, 
  DataGridProps, 
  DataGridRef 
} from '@fertilizer-shop/ag-grid-components';

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the LICENSE file for details.

Changelog

See CHANGELOG.md for release history.