Skip to content

Commit 0efcaab

Browse files
vivekkeyvalueVivek
vivekkeyvalue
and
Vivek
authored
feat: add readme file (#2)
Co-authored-by: Vivek <[email protected]>
1 parent 6dc6b11 commit 0efcaab

File tree

2 files changed

+270
-42
lines changed

2 files changed

+270
-42
lines changed

‎README.md‎

Lines changed: 269 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,295 @@
1-
<div align="center">
2-
<img align="center" width="230" src="https://i.imgur.com/iHgtvmg.png" />
3-
<h2>Typescript Library Boilerplate Basic</h2>
4-
<blockquote>Minimal Library Starter Kit for your Typescript projects</blockquote>
5-
6-
<a href="https://www.npmjs.com/package/@hodgef/ts-library-boilerplate-basic"><img src="https://badgen.net/npm/v/@hodgef/ts-library-boilerplate-basic?color=blue" alt="npm version"></a> <a href="https://github.com/hodgef/ts-library-boilerplate"><img src="https://img.shields.io/github/last-commit/hodgef/ts-library-boilerplate" alt="latest commit"></a> <a href="https://github.com/hodgef/ts-library-boilerplate-basic/actions"><img alt="Build Status" src="https://github.com/hodgef/ts-library-boilerplate-basic/workflows/Build/badge.svg?color=green" /></a> <a href="https://github.com/hodgef/ts-library-boilerplate-basic/actions"> <img alt="Publish Status" src="https://github.com/hodgef/ts-library-boilerplate-basic/workflows/Publish/badge.svg?color=green" /></a>
1+
# React Material Table Component
72

8-
<strong>For a plain Javascript alternative, check out [js-library-boilerplate-basic](https://github.com/hodgef/js-library-boilerplate-basic).</strong>
3+
[![npm version](https://badgen.net/npm/v/@keyvalue/material-table-component?color=blue)](https://www.npmjs.com/package/@keyvalue/material-table-component)
4+
[![Downloads](https://img.shields.io/npm/dw/@keyvalue/material-table-component?label=Downloads)](https://www.npmjs.com/package/@keyvalue/material-table-component)
5+
[![CI/CD](https://github.com/KeyValueSoftwareSystems/material-table-component/actions/workflows/deploy.yml/badge.svg)](https://github.com/KeyValueSoftwareSystems/material-table-component)
96

7+
<div align="center">
8+
<!-- TODO: Add screenshot of the table component in action -->
9+
<img src="./src/assets/material-table-example.png" alt="Material Table Component Example" width="800" height="400"/>
1010
</div>
1111

12-
## ⭐️ Features
12+
>A customizable & responsive Material Design table component for React projects with advanced features like multi-level data display, sorting, filtering, pagination, and row selection.
1313
14-
- Webpack 5
15-
- Babel 7
16-
- Hot reloading (`npm start`)
17-
- Automatic Types file generation (index.d.ts)
18-
- UMD exports, so your library works everywhere.
19-
- Jest unit testing
20-
- Customizable file headers for your build [(Example 1)](https://github.com/hodgef/ts-library-boilerplate-basic/blob/master/build/index.js) [(Example2)](https://github.com/hodgef/ts-library-boilerplate-basic/blob/master/build/css/index.css)
21-
- Daily [dependabot](https://dependabot.com) dependency updates
14+
Try the live demo using this codesandbox link [here](https://codesandbox.io/s/material-table-example)
2215

23-
## 📦 Getting Started
16+
## Installation
2417

18+
The easiest way to use material-table-component is to install it from npm and build it into your app with Webpack.
19+
20+
```bash
21+
npm install @keyvalue/material-table-component
2522
```
26-
git clone https://github.com/hodgef/ts-library-boilerplate-basic.git myLibrary
27-
npm install
23+
24+
You'll need to install React and Material-UI separately since they aren't included in the package.
25+
26+
## Usage
27+
28+
Material Table Component can be used in its basic form by providing the `columns` and `data` props:
29+
30+
```jsx
31+
import { GenericTable } from '@keyvalue/material-table-component';
32+
33+
<GenericTable
34+
columns={columns}
35+
data={data}
36+
/>
2837
```
2938

30-
## 💎 Customization
39+
The columns prop is an array of column definitions with the following structure:
3140

32-
> Before shipping, make sure to:
41+
```jsx
42+
const columns = [
43+
{
44+
key: "name",
45+
label: "Name",
46+
},
47+
{
48+
key: "age",
49+
label: "Age",
50+
}
51+
];
52+
```
3353

34-
1. Edit `LICENSE` file
35-
2. Edit `package.json` information (These will be used to generate the headers for your built files)
36-
3. Edit `library: "MyLibrary"` with your library's export name in `./webpack.config.js`
54+
The data prop should be an array of objects matching the column keys:
3755

38-
## 🚀 Deployment
56+
```jsx
57+
const data = [
58+
{
59+
id: "row-1",
60+
name: 'John Doe',
61+
age: 30,
62+
children: [] // Optional children for multi-level tables
63+
},
64+
{
65+
id: "row-2",
66+
name: 'Jane Smith',
67+
age: 25,
68+
children: []
69+
}
70+
];
71+
```
3972

40-
1. `npm publish`
41-
2. Your users can include your library as usual
73+
### Multi-Level Table Example
4274

43-
### npm
75+
The component supports multi-level data display with parent-child relationships:
4476

77+
```jsx
78+
<GenericTable
79+
data={[
80+
{
81+
id: "parent-1",
82+
investor: "Parent Company",
83+
grossInvestment: -1000000,
84+
children: [
85+
{
86+
id: "child-1",
87+
investor: "Subsidiary A",
88+
grossInvestment: -600000,
89+
children: []
90+
},
91+
{
92+
id: "child-2",
93+
investor: "Subsidiary B",
94+
grossInvestment: -400000,
95+
children: []
96+
}
97+
]
98+
}
99+
]}
100+
columns={[
101+
{
102+
key: "investor",
103+
label: "Investor",
104+
},
105+
{
106+
key: "grossInvestment",
107+
label: "Investment",
108+
}
109+
]}
110+
meta={{
111+
chartType: "MULTI_LEVEL_TABLE",
112+
columns: [
113+
{
114+
id: "investor",
115+
name: "Investor",
116+
type: "string",
117+
},
118+
{
119+
id: "grossInvestment",
120+
name: "Investment",
121+
type: "currency",
122+
currencyFormat: {
123+
currency: "dollar",
124+
scale: 2,
125+
},
126+
}
127+
]
128+
}}
129+
/>
45130
```
46-
import MyLibrary from 'my-library';
47-
const libraryInstance = new MyLibrary();
48-
...
131+
132+
## Props
133+
134+
Props that can be passed to the component are listed below:
135+
136+
<table>
137+
<thead>
138+
<tr>
139+
<th>Prop</th>
140+
<th>Description</th>
141+
<th>Default</th>
142+
</tr>
143+
</thead>
144+
<tbody>
145+
<tr>
146+
<td><code><b>data:</b> Row&lt;T&gt;[]</code></td>
147+
<td>An array of data objects to be displayed in the table. Each row can have a `children` array for multi-level tables.</td>
148+
<td><code>[]</code></td>
149+
</tr>
150+
<tr>
151+
<td><code><b>columns:</b> Column&lt;T&gt;[]</code></td>
152+
<td>An array of column definition objects with `key` and `label` properties</td>
153+
<td><code>[]</code></td>
154+
</tr>
155+
<tr>
156+
<td><code><b>meta?:</b> object</code></td>
157+
<td>Metadata for the table including column types and formatting options</td>
158+
<td><code>undefined</code></td>
159+
</tr>
160+
<tr>
161+
<td><code><b>actions?:</b> RowAction[]</code></td>
162+
<td>Array of action objects for row-level operations</td>
163+
<td><code>[]</code></td>
164+
</tr>
165+
<tr>
166+
<td><code><b>onViewRow?:</b> function</code></td>
167+
<td>Callback function triggered when a row is clicked</td>
168+
<td><code>undefined</code></td>
169+
</tr>
170+
<tr>
171+
<td><code><b>isLoading?:</b> boolean</code></td>
172+
<td>Flag to indicate if data is being loaded</td>
173+
<td><code>false</code></td>
174+
</tr>
175+
<tr>
176+
<td><code><b>depth?:</b> number | null</code></td>
177+
<td>Controls the depth of expanded rows in multi-level tables</td>
178+
<td><code>null</code></td>
179+
</tr>
180+
<tr>
181+
<td><code><b>showTotal?:</b> boolean</code></td>
182+
<td>Whether to show totals for numeric columns</td>
183+
<td><code>false</code></td>
184+
</tr>
185+
<tr>
186+
<td><code><b>tableHeaderStyles?:</b> React.CSSProperties</code></td>
187+
<td>Custom styles for the table header</td>
188+
<td><code>undefined</code></td>
189+
</tr>
190+
<tr>
191+
<td><code><b>tableCellStyles?:</b> React.CSSProperties</code></td>
192+
<td>Custom styles for table cells</td>
193+
<td><code>undefined</code></td>
194+
</tr>
195+
<tr>
196+
<td><code><b>rowColors?:</b> string[]</code></td>
197+
<td>Array of colors to be used for alternating rows</td>
198+
<td><code>undefined</code></td>
199+
</tr>
200+
</tbody>
201+
</table>
202+
203+
## Column Types and Formatting
204+
205+
The `meta.columns` property allows you to specify the type and formatting for each column:
206+
207+
```jsx
208+
meta={{
209+
chartType: "MULTI_LEVEL_TABLE",
210+
columns: [
211+
{
212+
id: "name",
213+
name: "Name",
214+
type: "string",
215+
},
216+
{
217+
id: "amount",
218+
name: "Amount",
219+
type: "currency",
220+
currencyFormat: {
221+
currency: "dollar",
222+
scale: 2,
223+
},
224+
},
225+
{
226+
id: "percentage",
227+
name: "Percentage",
228+
type: "percentage",
229+
scale: 2,
230+
},
231+
{
232+
id: "date",
233+
name: "Date",
234+
type: "date",
235+
dateFormat: "MM/DD/YYYY",
236+
}
237+
]
238+
}}
49239
```
50240

51-
### self-host/cdn
241+
Supported column types include:
242+
- `string` - Text data
243+
- `number` - Numeric data
244+
- `currency` - Monetary values with currency formatting
245+
- `percentage` - Percentage values
246+
- `date` - Date values with formatting options
247+
- `boolean` - True/false values
248+
249+
## Row Actions
52250

251+
You can define actions that appear for each row:
252+
253+
```jsx
254+
actions={[
255+
{
256+
label: "View Details",
257+
icon: "visibility",
258+
action: (rowId) => handleViewDetails(rowId),
259+
condition: (rowId) => hasDetails(rowId)
260+
},
261+
{
262+
label: "Edit",
263+
icon: "edit",
264+
action: (rowId) => handleEdit(rowId)
265+
}
266+
]}
53267
```
54-
<script src="build/index.js"></script>
55268

56-
const MyLibrary = window.MyLibrary.default;
57-
const libraryInstance = new MyLibrary();
58-
...
269+
## Style Customizations
270+
271+
You can customize the appearance of the table using the style props:
272+
273+
```jsx
274+
<GenericTable
275+
columns={columns}
276+
data={data}
277+
tableHeaderStyles={{
278+
background: "#1a237e",
279+
color: "#ffffff",
280+
fontSize: "1rem",
281+
}}
282+
tableCellStyles={{
283+
padding: "12px 16px",
284+
}}
285+
rowColors={["#f5f5f5", "#ffffff"]}
286+
/>
59287
```
60288

61-
## ✅ Libraries built with this boilerplate
289+
## Contributing
290+
291+
Contributions are welcome! Please feel free to submit a Pull Request.
62292

63-
> Made a library using this starter kit? Share it here by [submitting a pull request](https://github.com/hodgef/ts-library-boilerplate-basic/pulls)!
293+
## License
64294

65-
- [simple-keyboard](https://github.com/hodgef/simple-keyboard) - Javascript Virtual Keyboard
66-
- [react-simple-keyboard](https://github.com/hodgef/react-simple-keyboard) - React Virtual Keyboard
67-
- [simple-keyboard-layouts](https://github.com/hodgef/simple-keyboard-layouts) - Keyboard layouts for simple-keyboard
295+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "material-table-component",
2+
"name": "@keyvalue/material-table-component",
33
"version": "0.1.7",
44
"description": "A flexible and customizable table component built with React and Material-UI",
55
"main": "build/index.js",

0 commit comments

Comments
 (0)