mui-universal-table 1.0.7 → 1.0.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +141 -30
- package/dist/index.esm.js +155 -89
- package/dist/index.esm.js.map +1 -1
- package/dist/index.js +155 -89
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -62,41 +62,46 @@ function MyTable() {
|
|
|
62
62
|
|
|
63
63
|
## Props
|
|
64
64
|
|
|
65
|
-
| Prop | Type
|
|
66
|
-
| ------------------ |
|
|
67
|
-
| `data` | `array`
|
|
68
|
-
| `headers` | `array`
|
|
69
|
-
| `name` | `string`
|
|
70
|
-
| `loading` | `bool`
|
|
71
|
-
| `setLoading` | `func`
|
|
72
|
-
| `
|
|
73
|
-
| `
|
|
74
|
-
| `
|
|
75
|
-
| `
|
|
76
|
-
| `
|
|
77
|
-
| `
|
|
78
|
-
| `
|
|
79
|
-
| `
|
|
80
|
-
| `
|
|
81
|
-
| `
|
|
65
|
+
| Prop | Type | Default | Description |
|
|
66
|
+
| ------------------ | ---------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
67
|
+
| `data` | `array` | **required** | Array of data objects to display |
|
|
68
|
+
| `headers` | `array` | **required** | Array of header configuration objects |
|
|
69
|
+
| `name` | `string` | - | Table title |
|
|
70
|
+
| `loading` | `bool` | `false` | Shows skeleton loading state over the table |
|
|
71
|
+
| `setLoading` | `func` | - | Called when the table needs new data. In async mode receives a payload object (see [Async Mode](#async--server-side-mode)); otherwise called with `true` |
|
|
72
|
+
| `onReload` | `func` | - | Preferred reload callback — fires when the user clicks the reload button. Takes priority over `setLoading` for reload |
|
|
73
|
+
| `asyncPages` | `number` | - | Enables server-side search and sort. Set to the number of pages to request. When provided, `setLoading` is called with a payload object instead of `true` |
|
|
74
|
+
| `selectRows` | `bool` | `false` | Enable row selection |
|
|
75
|
+
| `selectID` | `string` | - | Property to use as unique identifier for selection |
|
|
76
|
+
| `onSelection` | `func` | - | Callback when rows are selected |
|
|
77
|
+
| `subTable` | `bool` | `false` | Whether this is a nested sub-table |
|
|
78
|
+
| `hideBadge` | `bool` | `false` | Hide badges on expandable rows |
|
|
79
|
+
| `reloadBtnLoading` | `bool` | `false` | Loading state for reload button |
|
|
80
|
+
| `lazyloading` | `bool` | `false` | Enable lazy loading indicator |
|
|
81
|
+
| `currentPage` | `number` | - | Current page for lazy loading |
|
|
82
|
+
| `totalPages` | `number` | - | Total pages for lazy loading |
|
|
83
|
+
| `selectIcon` | `element` | - | Custom icon for selection action |
|
|
84
|
+
| `pageSizeOptions` | `number[]` | - | Override default page size options (e.g. `[10, 25, 50]`) |
|
|
85
|
+
| `persistSearch` | `bool` | `false` | Persist the search term to `sessionStorage` (requires `name` prop) |
|
|
82
86
|
|
|
83
87
|
## Header Configuration
|
|
84
88
|
|
|
85
89
|
Each header object can have the following properties:
|
|
86
90
|
|
|
87
|
-
| Property | Type | Description
|
|
88
|
-
| ------------ | --------- |
|
|
89
|
-
| `id` | `string` | **Required** - Column identifier (matches data property)
|
|
90
|
-
| `label` | `string` | **Required** - Display label for column
|
|
91
|
-
| `searchable` | `bool` | Whether this column is searchable
|
|
92
|
-
| `numeric` | `bool` | Right-align column for numeric data
|
|
93
|
-
| `date` | `bool` | Format as date/time
|
|
94
|
-
| `
|
|
95
|
-
| `
|
|
96
|
-
| `
|
|
97
|
-
| `
|
|
98
|
-
| `
|
|
99
|
-
| `
|
|
91
|
+
| Property | Type | Description |
|
|
92
|
+
| ------------ | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
93
|
+
| `id` | `string` | **Required** - Column identifier (matches data property) |
|
|
94
|
+
| `label` | `string` | **Required** - Display label for column |
|
|
95
|
+
| `searchable` | `bool` | Whether this column is searchable |
|
|
96
|
+
| `numeric` | `bool` | Right-align column for numeric data |
|
|
97
|
+
| `date` | `bool` | Format as date/time |
|
|
98
|
+
| `sortable` | `bool` | In async mode, marks this column as server-sortable — clicking the header calls `setLoading` with a payload instead of sorting client-side. Has no effect when `asyncPages` is not set. |
|
|
99
|
+
| `component` | `func` | Custom render function `(rowData) => ReactElement` |
|
|
100
|
+
| `cellProps` | `object` | Additional props for table cells |
|
|
101
|
+
| `subRow` | `bool` | Column contains expandable sub-table data |
|
|
102
|
+
| `iconColor` | `string` | Color for expand/collapse icons |
|
|
103
|
+
| `openIcon` | `element` | Custom icon for expanding |
|
|
104
|
+
| `closeIcon` | `element` | Custom icon for collapsing |
|
|
100
105
|
|
|
101
106
|
## Advanced Examples
|
|
102
107
|
|
|
@@ -150,6 +155,112 @@ const headers = [
|
|
|
150
155
|
];
|
|
151
156
|
```
|
|
152
157
|
|
|
158
|
+
````
|
|
159
|
+
|
|
160
|
+
The callback receives `{ searchTerm, direction, column, pages }`.
|
|
161
|
+
|
|
162
|
+
## Async / Server-side Mode
|
|
163
|
+
|
|
164
|
+
Set `asyncPages` to a positive number to enable server-side search and sort. Instead of filtering the data in-browser, the table calls `setLoading` with a payload object so your API handler can fetch the correct page.
|
|
165
|
+
|
|
166
|
+
### Payload shape
|
|
167
|
+
|
|
168
|
+
Every `setLoading` call in async mode passes the same object:
|
|
169
|
+
|
|
170
|
+
```ts
|
|
171
|
+
{
|
|
172
|
+
searchTerm: string, // current search input
|
|
173
|
+
column: string, // column id being sorted (empty string if none)
|
|
174
|
+
direction: "asc" | "desc",
|
|
175
|
+
pages: number, // value of the asyncPages prop
|
|
176
|
+
}
|
|
177
|
+
````
|
|
178
|
+
|
|
179
|
+
This payload is sent on:
|
|
180
|
+
|
|
181
|
+
- **Search** — debounced 500 ms after the user stops typing
|
|
182
|
+
- **Sort** — immediately when the user clicks a sortable column header
|
|
183
|
+
- **Reload** — when the user clicks the reload button (using the current search/sort state)
|
|
184
|
+
|
|
185
|
+
### Example
|
|
186
|
+
|
|
187
|
+
```jsx
|
|
188
|
+
function ServerSideTable() {
|
|
189
|
+
const [loading, setLoading] = React.useState(false);
|
|
190
|
+
const [data, setData] = React.useState([]);
|
|
191
|
+
|
|
192
|
+
const fetchData = async ({
|
|
193
|
+
searchTerm = "",
|
|
194
|
+
column = "",
|
|
195
|
+
direction = "asc",
|
|
196
|
+
pages = 1,
|
|
197
|
+
} = {}) => {
|
|
198
|
+
setLoading(true);
|
|
199
|
+
try {
|
|
200
|
+
const result = await myApi.getUsers({
|
|
201
|
+
searchTerm,
|
|
202
|
+
column,
|
|
203
|
+
direction,
|
|
204
|
+
pages,
|
|
205
|
+
});
|
|
206
|
+
setData(result);
|
|
207
|
+
} finally {
|
|
208
|
+
setLoading(false);
|
|
209
|
+
}
|
|
210
|
+
};
|
|
211
|
+
|
|
212
|
+
React.useEffect(() => {
|
|
213
|
+
fetchData();
|
|
214
|
+
}, []);
|
|
215
|
+
|
|
216
|
+
return (
|
|
217
|
+
<UniversalTable
|
|
218
|
+
data={data}
|
|
219
|
+
headers={headers}
|
|
220
|
+
name="Users"
|
|
221
|
+
loading={loading}
|
|
222
|
+
setLoading={fetchData}
|
|
223
|
+
asyncPages={1}
|
|
224
|
+
/>
|
|
225
|
+
);
|
|
226
|
+
}
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
> **Note:** When `asyncPages` is set, client-side search is disabled — the table renders whatever is in `data` as-is. For sorting, behaviour depends on the `sortable` flag on each header column (see below).
|
|
230
|
+
|
|
231
|
+
### Column-level sort behaviour in async mode
|
|
232
|
+
|
|
233
|
+
In async mode, each column independently controls whether sorting is handled by the server or the client:
|
|
234
|
+
|
|
235
|
+
| Header has `sortable: true` | Clicking the column header |
|
|
236
|
+
| --------------------------- | -------------------------------------------------------------------- |
|
|
237
|
+
| Yes | Calls `setLoading` with the sort payload — your API handles the sort |
|
|
238
|
+
| No (default) | Sorts the currently loaded `data` client-side |
|
|
239
|
+
|
|
240
|
+
This lets you mix server-sorted and client-sorted columns in the same table — for example, server-sort on a large indexed column while still allowing client-side sort on a small computed field.
|
|
241
|
+
|
|
242
|
+
```jsx
|
|
243
|
+
const headers = [
|
|
244
|
+
{ id: "name", label: "Name", searchable: true, sortable: true }, // → API
|
|
245
|
+
{ id: "status", label: "Status", sortable: true }, // → API
|
|
246
|
+
{ id: "localScore", label: "Score", numeric: true }, // → client-side
|
|
247
|
+
];
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
### Reload button
|
|
251
|
+
|
|
252
|
+
For the reload button, prefer providing an `onReload` callback. It takes priority over `setLoading` and gives you explicit control:
|
|
253
|
+
|
|
254
|
+
```jsx
|
|
255
|
+
<UniversalTable
|
|
256
|
+
...
|
|
257
|
+
onReload={() => fetchData({ searchTerm: currentSearch, column, direction, pages: 1 })}
|
|
258
|
+
reloadBtnLoading={loading}
|
|
259
|
+
/>
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
If you only provide `setLoading`, the reload button will call it with the current search/sort state automatically.
|
|
263
|
+
|
|
153
264
|
## License
|
|
154
265
|
|
|
155
266
|
MIT
|