jc-react-datatable 1.0.0

package/README.md

@@ -0,0 +1,198 @@
+# JC React DataTable
+
+A modern, highly customizable, and performance-optimized React DataTable library. Built with pure JavaScript (ES6+) and React Hooks, offering a robust set of features with zero external logic dependencies.
+
+![Version](https://img.shields.io/npm/v/jc-react-datatable?style=flat-square)
+![License](https://img.shields.io/npm/l/jc-react-datatable?style=flat-square)
+![Downloads](https://img.shields.io/npm/dm/jc-react-datatable?style=flat-square)
+
+## ✨ Features
+
+- **🚀 High Performance**: Optimized with `useMemo` and `useCallback` for efficient rendering.
+- **🔍 Advanced Filtering**: Column-specific search with support for custom filter functions.
+- **⇅ Sorting**: Multi-type sorting (String, Number, Date, Custom).
+- **📄 Pagination**: Built-in client-side pagination with customizable page sizes.
+- **📱 Responsive Design**: 
+    - Auto-enables horizontal scrolling on small screens.
+    - Smart column filter positioning (prevents overflow on edge columns).
+    - Mobile-friendly layout.
+- **🎨 Modern UI**:
+    - Clean, sticky headers.
+    - Hover effects and polished aesthetics.
+    - Toggleable filter inputs via icons (keeps UI clean).
+- **↕️ Scrollable Body**: Optional `maxHeight` prop for fixed-header scrolling tables.
+- **📦 Zero Heavy Deps**: Only React and PropTypes.
+
+---
+
+## 📦 Installation
+
+Install the package via npm:
+
+```bash
+npm install jc-react-datatable
+```
+
+---
+
+## 🚀 Usage
+
+### 1. Import Component & Styles
+
+```jsx
+import { DataTable } from 'jc-react-datatable';
+import 'jc-react-datatable/dist/style.css'; // Import default styles
+```
+
+### 2. Define Columns & Data
+
+```jsx
+const columns = [
+  { 
+    key: 'id', 
+    header: 'ID', 
+    width: '60px', 
+    sortable: true 
+  },
+  { 
+    key: 'name', 
+    header: 'Name', 
+    sortable: true, 
+    searchable: true 
+  },
+  { 
+    key: 'role', 
+    header: 'Role', 
+    sortable: true, 
+    searchable: true 
+  },
+  {
+    key: 'joined',
+    header: 'Joined Date',
+    sortable: true,
+    render: (row) => new Date(row.joined).toLocaleDateString()
+  },
+  { 
+    key: 'actions', 
+    header: 'Actions', 
+    render: (row) => <button onClick={() => alert(row.name)}>Edit</button> 
+  }
+];
+
+const data = [
+  { id: 1, name: 'John Doe', role: 'Admin', joined: '2023-01-15' },
+  { id: 2, name: 'Jane Smith', role: 'User', joined: '2023-02-20' },
+  // ... more data
+];
+```
+
+### 3. Render the Table
+
+```jsx
+function App() {
+  return (
+    <div style={{ padding: '20px' }}>
+      <h1>User Directory</h1>
+      
+      <DataTable 
+        columns={columns} 
+        data={data} 
+        pagination={true}
+        pageSizeOptions={[5, 10, 20]}
+        defaultPageSize={10}
+        onRowClick={(row) => console.log('Clicked Row:', row)}
+        maxHeight="400px" // Enable vertical scroll
+        loading={false}
+      />
+    </div>
+  );
+}
+```
+
+---
+
+## 📖 API Reference
+
+### `DataTable` Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `Array` | **Required** | Array of column definitions (see below). |
+| `data` | `Array` | **Required** | Array of data objects to display. |
+| `pagination` | `Boolean` | `true` | Enable/Disable pagination. |
+| `pageSizeOptions` | `Array` | `[5, 10, 20, 50]` | Dropdown options for "Rows per page". |
+| `defaultPageSize` | `Number` | `10` | Initial number of rows per page. |
+| `onRowClick` | `Function` | `undefined` | Callback function when a row is clicked: `(row) => {}`. |
+| `loading` | `Boolean` | `false` | Shows a loading spinner if true. |
+| `noDataText` | `String` | `'No records found'` | Custom message when data is empty/filtered out. |
+| `maxHeight` | `String` | `undefined` | Sets a fixed height (e.g., `"300px"`). Enables vertical scrolling with **sticky headers**. |
+| `className` | `String` | `''` | Extra CSS class for the wrapper div. |
+
+### `Column` Definition Object
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `key` | `String` | **Required**. Unique key corresponding to the field in the data object. |
+| `header` | `String` | **Required**. The text to display in the table header. |
+| `width` | `String` | Optional. CSS width (e.g., `"150px"`, `"20%"`). |
+| `sortable` | `Boolean` | Enable sorting for this column. |
+| `searchable` | `Boolean` | Enable text filtering (search) for this column. |
+| `render` | `Function` | Custom cell renderer: `(row, index) => ReactNode`. |
+| `sortFn` | `Function` | Custom sort logic: `(a, b) => number` (-1, 0, 1). |
+| `filterFn` | `Function` | Custom filter logic: `(value, filterText, row) => boolean`. |
+
+---
+
+## 🛠 customization
+
+### CSS Overrides
+The library allows easy styling overrides via standard CSS.
+
+```css
+/* Example: Dark Header */
+.jc-datatable-th {
+  background-color: #2d3748;
+  color: #ffffff;
+}
+
+/* Example: Row Hover Color */
+.jc-datatable-tr:hover {
+  background-color: #ebf8ff;
+}
+
+/* Example: Active Page Button */
+.jc-datatable-pagination-btn:not(:disabled):hover {
+  border-color: #3182ce;
+  color: #3182ce;
+}
+```
+
+---
+
+## 💻 Development
+
+Clone the repository and run locally:
+
+1. **Install Dependencies**
+   ```bash
+   npm install
+   ```
+
+2. **Start Dev Server** (Demo App)
+   ```bash
+   npm run dev
+   ```
+
+3. **Build Library**
+   ```bash
+   npm run build
+   ```
+
+---
+
+## 📄 License
+
+MIT © [Jay Patel](https://github.com/jaypatel)
+
+---
+*Built with ❤️ using React*.