tadabut 0.5.0 → 0.7.0
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 +348 -39
- package/dist/{index-KmSXRJlI.d.ts → index-Cm0OsNb6.d.ts} +403 -30
- package/dist/index.d.ts +8 -2
- package/dist/index.js +1 -1
- package/dist/react.d.ts +48 -12
- package/dist/react.js +97 -27
- package/dist/{src-CBK3xu9-.js → src-D6zL6H0B.js} +1049 -80
- package/package.json +12 -8
package/README.md
CHANGED
|
@@ -25,6 +25,7 @@ DataTables is great for showing data. Editing that data inside the table is a di
|
|
|
25
25
|
- Delete a row, with a question first, or your own popup.
|
|
26
26
|
- Text, number, money, date, checkbox and select inputs, with validation.
|
|
27
27
|
- Selects that depend on another field, like country and city. Old requests get cancelled when the user changes their mind.
|
|
28
|
+
- Detail rows that open under a row, loaded from your server if you like, with JSX in React.
|
|
28
29
|
- Fully typed. The table knows what your rows look like, so a typo in a column name is a type error.
|
|
29
30
|
- No jQuery. It's built on DataTables 3, which doesn't need it anymore.
|
|
30
31
|
|
|
@@ -43,7 +44,7 @@ The core has no framework in it. Each framework gets a small adapter on top.
|
|
|
43
44
|
## Requirements
|
|
44
45
|
|
|
45
46
|
- DataTables 3: `datatables.net`, or one of its styling packages like `datatables.net-dt`
|
|
46
|
-
- React 19
|
|
47
|
+
- React 19 and `react-dom`, only if you use the React adapter
|
|
47
48
|
- A modern browser
|
|
48
49
|
|
|
49
50
|
## Installation
|
|
@@ -67,7 +68,7 @@ bun add tadabut datatables.net-dt
|
|
|
67
68
|
deno add npm:tadabut npm:datatables.net-dt
|
|
68
69
|
```
|
|
69
70
|
|
|
70
|
-
For the React adapter, you also need React 19
|
|
71
|
+
For the React adapter, you also need React 19 and `react-dom`, which your app most likely has already.
|
|
71
72
|
|
|
72
73
|
Then import DataTables and its CSS once, before you create a table:
|
|
73
74
|
|
|
@@ -170,18 +171,35 @@ A select's values must have the same type as the column. `countryId` is a number
|
|
|
170
171
|
| `text` | `string` | `''` | `minLength`, `maxLength`, `pattern` |
|
|
171
172
|
| `number` | `number` | `null` | `min`, `max`, `step` |
|
|
172
173
|
| `money` | `number` | `null` | `min`, `max`, `decimals`, `separator`, `point` |
|
|
173
|
-
| `date` | `string` | `null` | `min`, `max`
|
|
174
|
+
| `date` | `string` | `null` | `min`, `max`, `format`, `display` |
|
|
175
|
+
| `time` | `string` | `null` | `min`, `max`, `seconds` |
|
|
176
|
+
| `datetime` | `string` | `null` | `min`, `max`, `format`, `display`, `seconds` |
|
|
174
177
|
| `checkbox` | `boolean`, or `values` | never empty | `values` |
|
|
175
178
|
| `select` | same as the column | `null` | `options`, `dependsOn`, `labelProp` |
|
|
176
179
|
|
|
177
|
-
Every editor also takes `className`, for your own CSS classes.
|
|
180
|
+
Every editor also takes `className`, for your own CSS classes, and `readOnly`. See [Read-only fields](#read-only-fields).
|
|
178
181
|
|
|
179
182
|
A few things to know:
|
|
180
183
|
|
|
181
|
-
- An empty number or
|
|
184
|
+
- An empty number, date or time gives `null`, not `0` or `NaN`. A select with nothing picked gives `null` too.
|
|
182
185
|
- A checkbox shows `null` as unchecked, but keeps it: an untouched `null` is still `null` after saving. It only becomes `true` or `false` once the user clicks it.
|
|
183
186
|
- A `string | null` column gets the same editors as a `string` column. `null` shows as an empty input.
|
|
184
|
-
- Date columns
|
|
187
|
+
- Date columns hold `'YYYY-MM-DD'` unless you give a `format`. See [Dates](#dates).
|
|
188
|
+
|
|
189
|
+
#### Read-only fields
|
|
190
|
+
|
|
191
|
+
Add `readOnly: true` to any editor, and the field shows in a locked input while the row is edited:
|
|
192
|
+
|
|
193
|
+
```ts
|
|
194
|
+
{ prop: 'code', title: 'Code', editor: { type: 'text', readOnly: true } }
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
- The user sees the value but can't change it. The browser greys the input out, and Tab skips it.
|
|
198
|
+
- Saving keeps the value the row had, even one the input can't show, like a date with a time.
|
|
199
|
+
- It's never checked: `required`, `min`, `validate` and the others are skipped, since the user couldn't fix it anyway.
|
|
200
|
+
- In the new row from `add()`, it shows the value you passed to `add()`, or nothing, and stays locked. Good for fields your server fills in, like a reference number. The cursor starts in the first field that isn't read-only.
|
|
201
|
+
- It works on every editor, `custom` too: your `create` gets `context.readOnly`, and should disable its input.
|
|
202
|
+
- The cell keeps the editor's format, so a read-only `date` or `money` column still shows and sorts like the others.
|
|
185
203
|
|
|
186
204
|
#### Checkboxes with your own values
|
|
187
205
|
|
|
@@ -229,6 +247,80 @@ import { defaultMoneyFormat, formatMoney } from 'tadabut';
|
|
|
229
247
|
{ prop: 'bonus', title: 'Bonus', render: (value) => formatMoney(value, defaultMoneyFormat) }
|
|
230
248
|
```
|
|
231
249
|
|
|
250
|
+
#### Dates
|
|
251
|
+
|
|
252
|
+
`date` is for `string` columns. The input is the browser's date picker. By default, the rows hold `'2024-01-05'` (year first). If your server sends another order, say so with `format`, and pick what the cells show with `display`:
|
|
253
|
+
|
|
254
|
+
```ts
|
|
255
|
+
{
|
|
256
|
+
prop: 'hiredAt',
|
|
257
|
+
title: 'Hired',
|
|
258
|
+
editor: { type: 'date', format: 'dd/mm/yyyy', min: '01/01/2000' },
|
|
259
|
+
}
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
- `format` is how the date is written in your rows: what the server sends, and what `onSave` gets back. It defaults to `'yyyy-mm-dd'`.
|
|
263
|
+
- `display` is how the cells show it. It defaults to `format`. With ISO data and `display: 'dd/mm/yyyy'`, the cells show `05/01/2024`, but the rows keep `'2024-01-05'`.
|
|
264
|
+
- Both take `dd`, `mm` and `yyyy` in any order, with `/`, `-` or `.` between them: `'dd/mm/yyyy'`, `'mm-dd-yyyy'`, `'dd.mm.yyyy'`, and so on. TypeScript catches a typo like `'dd/mm-yyyy'`.
|
|
265
|
+
- `min` and `max` are written in `format` too. Tadabut throws an error if they aren't real dates in that format.
|
|
266
|
+
- Sorting uses the real date, whatever the format. `'12/01/2023'` comes before `'05/01/2024'`.
|
|
267
|
+
- A time after the date is dropped: `'2024-01-05T10:30:00'` shows the 5th, and saves as `'2024-01-05'`.
|
|
268
|
+
- A value that isn't a real date in `format`, like `'31/02/2024'`, shows as it is in the cell, so you can see it. The input shows it as empty, and saving turns it into `null`.
|
|
269
|
+
- The picker itself shows the date the way the computer's language does. A French computer shows `05/01/2024` and an American one `01/05/2024`. Browsers don't let a page change that.
|
|
270
|
+
|
|
271
|
+
`parseDate`, `formatDate` and `defaultDateFormat` are exported, to read and write the same formats elsewhere. `parseDate` gives `'yyyy-mm-dd'`, or `null` if it isn't a real date:
|
|
272
|
+
|
|
273
|
+
```ts
|
|
274
|
+
import { formatDate, parseDate } from 'tadabut';
|
|
275
|
+
|
|
276
|
+
parseDate('05/01/2024', 'dd/mm/yyyy'); // '2024-01-05'
|
|
277
|
+
formatDate('2024-01-05', 'dd.mm.yyyy'); // '05.01.2024'
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
A column you can't edit has no date editor, so for now, show its dates with `render`: `render: (value) => formatDate(value, 'dd/mm/yyyy')`. It sorts by the raw value, which is right for ISO dates.
|
|
281
|
+
|
|
282
|
+
#### Times
|
|
283
|
+
|
|
284
|
+
`time` is for `string` columns that hold a time of day, like `'14:30'`. The input is the browser's time picker.
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
{ prop: 'starts', title: 'Starts', editor: { type: 'time', min: '08:00', max: '18:00' } }
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
- It reads `'9:05'`, `'09:05'` and `'09:05:00'`. What comes after the seconds is ignored, like `.000` from some servers.
|
|
291
|
+
- It saves `'hh:mm'`. With `seconds: true`, the picker shows the seconds and it saves `'hh:mm:ss'`.
|
|
292
|
+
- The cells show `hh:mm` (or `hh:mm:ss`), and sorting uses the real time: `9:05` comes before `14:30`.
|
|
293
|
+
- `min` and `max` are times too. Tadabut throws an error if they aren't real times.
|
|
294
|
+
- A value that isn't a time, like `'25:00'`, shows as it is in the cell, and as empty in the input.
|
|
295
|
+
|
|
296
|
+
#### Dates with a time
|
|
297
|
+
|
|
298
|
+
`datetime` is for `string` columns that hold a date and a time. The input is the browser's date-and-time picker.
|
|
299
|
+
|
|
300
|
+
```ts
|
|
301
|
+
{
|
|
302
|
+
prop: 'lastLogin',
|
|
303
|
+
title: 'Last login',
|
|
304
|
+
editor: { type: 'datetime', format: 'dd/mm/yyyy', min: '01/01/2020 08:00' },
|
|
305
|
+
}
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
- The rows hold the date in `format`, a space, then the time: `'05/01/2024 14:30'`. With the default ISO `format`, a `T` goes between them instead, as servers send it: `'2024-01-05T14:30'`.
|
|
309
|
+
- `format`, `display` and `seconds` work like for [dates](#dates) and [times](#times). The cells always use a space: `05/01/2024 14:30`.
|
|
310
|
+
- When reading, a `T` and a space both work, and a date with no time counts as midnight.
|
|
311
|
+
- What comes after the seconds is ignored, a time zone too: `'2024-01-05T14:30:00Z'` shows 14:30, as written, not converted to the user's time.
|
|
312
|
+
- `min` and `max` are written like the data. Tadabut throws an error if they aren't real, or aren't in `format`.
|
|
313
|
+
- Sorting uses the real date and time, whatever `display` is.
|
|
314
|
+
|
|
315
|
+
`parseTime`, `formatTime`, `parseDateTime` and `formatDateTime` are exported, like the date helpers:
|
|
316
|
+
|
|
317
|
+
```ts
|
|
318
|
+
import { parseDateTime, parseTime } from 'tadabut';
|
|
319
|
+
|
|
320
|
+
parseTime('9:05'); // '09:05:00'
|
|
321
|
+
parseDateTime('05/01/2024 14:30', 'dd/mm/yyyy'); // '2024-01-05T14:30:00'
|
|
322
|
+
```
|
|
323
|
+
|
|
232
324
|
### What cells show
|
|
233
325
|
|
|
234
326
|
When a row isn't being edited, a cell shows its value as text. These change that:
|
|
@@ -236,6 +328,8 @@ When a row isn't being edited, a cell shows its value as text. These change that
|
|
|
236
328
|
- A select with a fixed list shows the option's label. A `countryId` of `1` shows "Morocco", with nothing to write.
|
|
237
329
|
- A select with `labelProp` shows that field of the row, like `cityName`. See [Chained selects](#chained-selects).
|
|
238
330
|
- A `money` editor shows its format, like `12 500.00`.
|
|
331
|
+
- A `date` editor shows its `display`, like `05/01/2024`.
|
|
332
|
+
- A `time` editor shows `09:05`, even when the data says `9:05:00`. A `datetime` editor shows its `display`, then the time, like `05/01/2024 14:30`.
|
|
239
333
|
- `render` sets the text yourself, on any column:
|
|
240
334
|
|
|
241
335
|
```ts
|
|
@@ -244,9 +338,9 @@ When a row isn't being edited, a cell shows its value as text. These change that
|
|
|
244
338
|
|
|
245
339
|
A few things to know:
|
|
246
340
|
|
|
247
|
-
- The order is: `render`, then the money format, then `labelProp`, then the fixed list's label, then the value itself.
|
|
341
|
+
- The order is: `render`, then the money or date format, then `labelProp`, then the fixed list's label, then the value itself.
|
|
248
342
|
- What `render` returns is shown as plain text, never as HTML. `<b>` shows as `<b>`, so text from a server can't break the page or run code.
|
|
249
|
-
- Searching uses both the text and the raw value, so `12500` finds `12 500.00`, and a country's id finds "Morocco". Sorting uses the raw value, so `200 MAD` comes before `1000 MAD`. A city column sorts by id, not by name.
|
|
343
|
+
- Searching uses both the text and the raw value, so `12500` finds `12 500.00`, and a country's id finds "Morocco". Sorting uses the raw value, so `200 MAD` comes before `1000 MAD`. Dates and times are the exception: they sort by the real date and time. A city column sorts by id, not by name.
|
|
250
344
|
- An empty value (`null` or `undefined`) shows an empty cell. On a nullable column, `render` gets `null` too.
|
|
251
345
|
- Editors always get the raw value. After saving or cancelling, the text is worked out again.
|
|
252
346
|
|
|
@@ -378,23 +472,28 @@ texts: { ...fr, save: 'Valider' }
|
|
|
378
472
|
texts: { edit: 'Bearbeiten', save: 'Speichern', cancel: 'Abbrechen' }
|
|
379
473
|
```
|
|
380
474
|
|
|
381
|
-
| Key
|
|
382
|
-
|
|
|
383
|
-
| `edit`, `save`, `cancel`
|
|
384
|
-
| `delete`
|
|
385
|
-
| `deleteQuestion`
|
|
386
|
-
| `confirm`, `keep`
|
|
387
|
-
| `loading`
|
|
388
|
-
| `saveFailed`
|
|
389
|
-
| `addFailed`
|
|
390
|
-
| `deleteFailed`
|
|
391
|
-
| `total`
|
|
392
|
-
| `
|
|
393
|
-
| `
|
|
394
|
-
| `
|
|
395
|
-
| `
|
|
396
|
-
| `
|
|
397
|
-
| `
|
|
475
|
+
| Key | English |
|
|
476
|
+
| ----------------------------- | --------------------------------------------------------------------------------- |
|
|
477
|
+
| `edit`, `save`, `cancel` | Edit, Save, Cancel |
|
|
478
|
+
| `delete` | Delete |
|
|
479
|
+
| `deleteQuestion` | Delete this row? |
|
|
480
|
+
| `confirm`, `keep` | Yes, delete / No |
|
|
481
|
+
| `loading` | Loading… |
|
|
482
|
+
| `saveFailed` | Could not save. |
|
|
483
|
+
| `addFailed` | Could not add. |
|
|
484
|
+
| `deleteFailed` | Could not delete. |
|
|
485
|
+
| `total` | Total |
|
|
486
|
+
| `selectRow`, `selectAll` | Select row / Select all (the checkboxes' labels, for screen readers) |
|
|
487
|
+
| `showDetail`, `hideDetail` | Show details / Hide details (the ▸ button's label, for screen readers) |
|
|
488
|
+
| `detailLoading` | Loading… (while a detail loads) |
|
|
489
|
+
| `detailFailed` | Couldn't load the details. (when `detail` throws something that isn't an `Error`) |
|
|
490
|
+
| `loadFailed` | Could not load the options. |
|
|
491
|
+
| `required` | This field is required. |
|
|
492
|
+
| `patternMismatch` | Wrong format. |
|
|
493
|
+
| `tooShort`, `tooLong` | Must be at least 2 characters. |
|
|
494
|
+
| `tooSmall`, `tooLarge` | Must be 18 or more. |
|
|
495
|
+
| `tooEarly`, `tooLate` | Must be on or after 2020-01-01. |
|
|
496
|
+
| `timeTooEarly`, `timeTooLate` | Must be at or after 08:00. |
|
|
398
497
|
|
|
399
498
|
The messages with a number or a date are functions, so you can put the value where your language needs it:
|
|
400
499
|
|
|
@@ -440,6 +539,14 @@ Tadabut doesn't ship any CSS. Everything it creates gets these classes, so you c
|
|
|
440
539
|
| `tdb-delete-question` | the "Delete this row?" text |
|
|
441
540
|
| `tdb-button-confirm` | the "Yes, delete" button |
|
|
442
541
|
| `tdb-button-keep` | the "No" button |
|
|
542
|
+
| `tdb-select` | the checkbox column, header too |
|
|
543
|
+
| `tdb-select-row` | a row's checkbox |
|
|
544
|
+
| `tdb-select-all` | the "check all" checkbox |
|
|
545
|
+
| `tdb-row-selected` | a selected row |
|
|
546
|
+
| `tdb-detail` | the ▸ column, header too |
|
|
547
|
+
| `tdb-detail-toggle` | the ▸ / ▾ button |
|
|
548
|
+
| `tdb-detail-open` | a row whose detail is open |
|
|
549
|
+
| `tdb-row-detail` | the line under a row with its detail |
|
|
443
550
|
|
|
444
551
|
To use Bootstrap, Tailwind or anything else, add your own classes. They always go next to the `tdb-` ones, never instead of them. There are two places:
|
|
445
552
|
|
|
@@ -476,6 +583,8 @@ const table = new Tadabut(container, {
|
|
|
476
583
|
| `delete` | the Delete button only |
|
|
477
584
|
| `confirm` | the "Yes, delete" button only |
|
|
478
585
|
| `keep` | the "No" button only |
|
|
586
|
+
| `select` | the selection checkboxes |
|
|
587
|
+
| `detail` | the ▸ button |
|
|
479
588
|
|
|
480
589
|
All of them are optional. Tadabut doesn't know any CSS framework: it adds the classes you give it, and nothing else. If you use Tailwind: it only keeps classes it finds in your own files. Classes in your column config count, so they work.
|
|
481
590
|
|
|
@@ -887,6 +996,136 @@ confirmDelete: async (row) => {
|
|
|
887
996
|
|
|
888
997
|
Leave it out for the question in the row. To only change its words, use `texts` (`deleteQuestion`, `confirm`, `keep`). To style it, use `classNames` (`delete`, `confirm`, `keep`).
|
|
889
998
|
|
|
999
|
+
### Selecting rows
|
|
1000
|
+
|
|
1001
|
+
Turn on `selection`, and the table gets a checkbox column at the start, with a "check all" box in the header:
|
|
1002
|
+
|
|
1003
|
+
```ts
|
|
1004
|
+
const table = new Tadabut(container, {
|
|
1005
|
+
data: employees,
|
|
1006
|
+
rowId: 'id',
|
|
1007
|
+
columns,
|
|
1008
|
+
selection: true,
|
|
1009
|
+
onSelect: (rows) => console.log(`${rows.length} selected`),
|
|
1010
|
+
});
|
|
1011
|
+
|
|
1012
|
+
table.getSelected(); // the selected rows
|
|
1013
|
+
```
|
|
1014
|
+
|
|
1015
|
+
- Ticks are kept by row id, so they stay when you change page, sort or search.
|
|
1016
|
+
- `onSelect` gets every selected row each time the selection changes, from a click or from code.
|
|
1017
|
+
- The header box is ticked when every row it takes is selected, and shows a dash when only some are.
|
|
1018
|
+
- A selected row gets the `tdb-row-selected` class. Tadabut doesn't color it: that's your CSS.
|
|
1019
|
+
- Rows that leave the table, after a delete or `setData`, are unselected.
|
|
1020
|
+
- The new row `add()` opens has no checkbox until it's saved.
|
|
1021
|
+
- `selection` needs a `rowId`, and Tadabut throws an error without one.
|
|
1022
|
+
|
|
1023
|
+
**Which rows "check all" takes,** with `checkAll`:
|
|
1024
|
+
|
|
1025
|
+
```ts
|
|
1026
|
+
selection: { checkAll: 'page' },
|
|
1027
|
+
```
|
|
1028
|
+
|
|
1029
|
+
| `checkAll` | Takes |
|
|
1030
|
+
| ---------------------- | ------------------------------------------------ |
|
|
1031
|
+
| `'searched'` (default) | every row that matches the search, on every page |
|
|
1032
|
+
| `'all'` | every row, whatever the search |
|
|
1033
|
+
| `'page'` | only the rows on the page shown |
|
|
1034
|
+
|
|
1035
|
+
Rows you ticked that "check all" doesn't take stay ticked: unticking it only unselects the rows it takes.
|
|
1036
|
+
|
|
1037
|
+
Your `order` in `dataTables` still counts your own columns: `[[0, 'asc']]` is your first column, not the checkboxes.
|
|
1038
|
+
|
|
1039
|
+
### Detail rows
|
|
1040
|
+
|
|
1041
|
+
Give `detail` a function, and each row gets a ▸ button at the start. Clicking it opens a line under the row with what the function returns:
|
|
1042
|
+
|
|
1043
|
+
```ts
|
|
1044
|
+
const table = new Tadabut(container, {
|
|
1045
|
+
data: orders,
|
|
1046
|
+
rowId: 'id',
|
|
1047
|
+
columns,
|
|
1048
|
+
detail: async (row, { signal }) => {
|
|
1049
|
+
const res = await fetch(`/api/orders/${row.id}/lines`, { signal });
|
|
1050
|
+
const lines: { label: string }[] = await res.json();
|
|
1051
|
+
|
|
1052
|
+
const list = document.createElement('ul');
|
|
1053
|
+
|
|
1054
|
+
for (const line of lines) {
|
|
1055
|
+
const item = document.createElement('li');
|
|
1056
|
+
item.textContent = line.label;
|
|
1057
|
+
list.append(item);
|
|
1058
|
+
}
|
|
1059
|
+
|
|
1060
|
+
return list;
|
|
1061
|
+
},
|
|
1062
|
+
});
|
|
1063
|
+
```
|
|
1064
|
+
|
|
1065
|
+
- It returns an element, or a string. A string is shown as plain text, never as HTML, so text from a server can't break the page. To show HTML, build the elements yourself.
|
|
1066
|
+
- It can be async. "Loading…" shows while it waits. If it throws, the error message shows in the line.
|
|
1067
|
+
- Pass `signal` to `fetch`. It's aborted when the detail closes before it finished loading, so a slow request stops instead of showing up late.
|
|
1068
|
+
- Several details can be open at once.
|
|
1069
|
+
- The ▸ button comes after the selection checkboxes and before your columns. Your `order` in `dataTables` still counts from your first column.
|
|
1070
|
+
- `detail` needs a `rowId`, and Tadabut throws an error without one.
|
|
1071
|
+
|
|
1072
|
+
**What happens to an open detail when…**
|
|
1073
|
+
|
|
1074
|
+
- **You sort, search or change page:** it stays open, and comes back when its row is shown again.
|
|
1075
|
+
- **The row is being edited:** it stays open.
|
|
1076
|
+
- **The row is saved:** `detail` runs again, so it shows the new values.
|
|
1077
|
+
- **A save or delete fails:** the error shows under the detail. Neither one replaces the other.
|
|
1078
|
+
- **The row is deleted, `setData` runs, or the table is destroyed:** it closes, and a load still running is stopped.
|
|
1079
|
+
|
|
1080
|
+
**Open it on a row click** instead of, or as well as, the button:
|
|
1081
|
+
|
|
1082
|
+
```ts
|
|
1083
|
+
onRowClick: (row) => table.toggleDetail(row.id),
|
|
1084
|
+
```
|
|
1085
|
+
|
|
1086
|
+
### Events
|
|
1087
|
+
|
|
1088
|
+
Six callbacks tell you what happened. Each one gets the row:
|
|
1089
|
+
|
|
1090
|
+
| Option | When | Gets |
|
|
1091
|
+
| ------------------ | -------------------------------------- | --------------------- |
|
|
1092
|
+
| `onEditStart` | a row opens for editing | `(row)` |
|
|
1093
|
+
| `onSaved` | after a save worked and the row closed | `(row, { previous })` |
|
|
1094
|
+
| `onAdded` | after a new row joined the table | `(row)` |
|
|
1095
|
+
| `onDeleted` | after a row left the table | `(row)` |
|
|
1096
|
+
| `onRowClick` | a row is clicked | `(row, event)` |
|
|
1097
|
+
| `onRowDoubleClick` | a row is double-clicked | `(row, event)` |
|
|
1098
|
+
|
|
1099
|
+
```ts
|
|
1100
|
+
const table = new Tadabut(container, {
|
|
1101
|
+
data: employees,
|
|
1102
|
+
rowId: 'id',
|
|
1103
|
+
columns,
|
|
1104
|
+
onSave: saveEmployee,
|
|
1105
|
+
onEditStart: (row) => row.status !== 'validated', // false keeps the row closed
|
|
1106
|
+
onSaved: (row, { previous }) => toast(`${previous.name} saved`),
|
|
1107
|
+
onRowClick: (row) => showDetails(row),
|
|
1108
|
+
});
|
|
1109
|
+
```
|
|
1110
|
+
|
|
1111
|
+
- `onSave`, `onAdd` and `onDelete` do the work and can fail. `onSaved`, `onAdded` and `onDeleted` come after, once it worked and the table changed. They're never called when it failed.
|
|
1112
|
+
- They're called the same way from the buttons and from code: `table.edit(1)` calls `onEditStart`, and `await table.save(1)` calls `onSaved`.
|
|
1113
|
+
- `onEditStart` can return `false` to keep the row closed, for rows a user can't change. `edit()` then returns `false`. It's not called for the new row `add()` opens, and it can't be async.
|
|
1114
|
+
- `onSaved` gets the row as it now is in the table (what `onSave` returned, if anything), and the row before editing.
|
|
1115
|
+
- Tadabut doesn't wait for the "after" callbacks, so async is fine. If one throws, the table is already done: the error goes to the console, and `save()` or `saveNew()` rejects.
|
|
1116
|
+
|
|
1117
|
+
**Which clicks count:** clicks on buttons, inputs, checkboxes, labels and links don't, and neither do clicks in the checkbox and buttons cells (a click that just missed a button). Clicks in a row being edited, the new row, the header, the footer or an error line don't count either. `onRowClick` works without `rowId` and without editors.
|
|
1118
|
+
|
|
1119
|
+
**Double clicks:** the browser fires two clicks before a double click, so `onRowClick` runs twice before `onRowDoubleClick`. Tadabut doesn't wait to tell them apart, because that would make every single click feel slow.
|
|
1120
|
+
|
|
1121
|
+
**Double click to edit:**
|
|
1122
|
+
|
|
1123
|
+
```ts
|
|
1124
|
+
editing: { doubleClick: true },
|
|
1125
|
+
```
|
|
1126
|
+
|
|
1127
|
+
Double-clicking a row then opens it, the same as its Edit button: `onEditStart` and the `'single'` mode still apply. `onRowDoubleClick` still fires, after the row opened.
|
|
1128
|
+
|
|
890
1129
|
### Editing options
|
|
891
1130
|
|
|
892
1131
|
When at least one column has an `editor`, the table gets one more column at the end, with an Edit button in each row. While a row is being edited, its Edit button is replaced by Save and Cancel. The labels can be changed with `texts`.
|
|
@@ -902,13 +1141,15 @@ const table = new Tadabut(container, {
|
|
|
902
1141
|
editing: {
|
|
903
1142
|
mode: 'multiple', // default: 'single'
|
|
904
1143
|
button: false, // default: true. false hides the edit button
|
|
1144
|
+
doubleClick: true, // default: false. true opens a row on double click
|
|
905
1145
|
},
|
|
906
1146
|
});
|
|
907
1147
|
```
|
|
908
1148
|
|
|
909
1149
|
- `'single'` mode: one row at a time. You can't start a new edit while another row is open.
|
|
910
1150
|
- `'multiple'` mode: several rows can be open. Each one saves on its own, so `onSave` runs once per row.
|
|
911
|
-
- `
|
|
1151
|
+
- `doubleClick: true`: double-clicking a row opens it. See [Events](#events).
|
|
1152
|
+
- `button: false`: no Edit button. Start edits from your own code, or with `doubleClick`. <kbd>Enter</kbd> and <kbd>Escape</kbd> still work. With `onDelete`, the column stays, with only the Delete button.
|
|
912
1153
|
|
|
913
1154
|
### Controlling it from code
|
|
914
1155
|
|
|
@@ -924,11 +1165,24 @@ await table.saveNew(); // validate it and call onAdd
|
|
|
924
1165
|
table.cancelNew(); // throw the new row away
|
|
925
1166
|
table.isAdding(); // true while the new row is open
|
|
926
1167
|
|
|
1168
|
+
table.select([1, 2]); // tick rows 1 and 2
|
|
1169
|
+
table.deselect([2]); // untick row 2
|
|
1170
|
+
table.clearSelection(); // untick every row
|
|
1171
|
+
table.isSelected(1); // true while row 1 is ticked
|
|
1172
|
+
table.getSelected(); // the ticked rows
|
|
1173
|
+
|
|
1174
|
+
table.openDetail(1); // open row 1's detail
|
|
1175
|
+
table.closeDetail(1); // close it
|
|
1176
|
+
table.toggleDetail(1); // open it if closed, close it if open
|
|
1177
|
+
table.isDetailOpen(1); // true while it's open, or loading
|
|
1178
|
+
|
|
927
1179
|
table.setData(newEmployees); // replace all rows, keeps sorting and search
|
|
928
1180
|
table.destroy(); // remove everything Tadabut created
|
|
929
1181
|
```
|
|
930
1182
|
|
|
931
|
-
|
|
1183
|
+
See [Reading and changing rows](#reading-and-changing-rows) for `getData`, `insertRow` and the others.
|
|
1184
|
+
|
|
1185
|
+
`edit` returns `true` if editing started. It returns `false` when the row doesn't exist, it's already open, another row is open in `'single'` mode, no column has an editor, `onEditStart` returned `false`, or the row is on a page that hasn't been shown yet. DataTables only builds a row's cells once it's shown, so go to that page first.
|
|
932
1186
|
|
|
933
1187
|
`save` returns a promise of `true` if the row was saved and closed, `false` if it wasn't: a field is invalid, `onSave` failed, the row isn't being edited, or it's already saving.
|
|
934
1188
|
|
|
@@ -938,10 +1192,58 @@ table.destroy(); // remove everything Tadabut created
|
|
|
938
1192
|
|
|
939
1193
|
`add` returns `true` if the new row opened, `false` if one is already open, no column has an editor, or a row is being edited in `'single'` mode. `saveNew` works like `save`, and throws if the saved row has no id. `cancelNew` does nothing while `onAdd` runs.
|
|
940
1194
|
|
|
1195
|
+
`select` skips ids that aren't in the table. `onSelect` is only called when something really changed. `getSelected` gives the rows in the order they were added, including rows hidden by the search or on other pages. Without `selection`, these do nothing, and `getSelected` gives `[]`. The detail methods do nothing without `detail`, and `isDetailOpen` gives `false`.
|
|
1196
|
+
|
|
941
1197
|
`setData` and `destroy` cancel any row being edited, and the new row, first. Unsaved changes are lost.
|
|
942
1198
|
|
|
943
1199
|
<kbd>Enter</kbd> saves the row you're in. <kbd>Escape</kbd> cancels it. If something else already used the key, like Select2 picking an option with <kbd>Enter</kbd>, Tadabut leaves it alone.
|
|
944
1200
|
|
|
1201
|
+
### Reading and changing rows
|
|
1202
|
+
|
|
1203
|
+
```ts
|
|
1204
|
+
table.getData(); // every row, in the order shown
|
|
1205
|
+
table.getData('searched'); // only the rows that match the search ('page': only this page)
|
|
1206
|
+
table.getRow(5); // the row with id 5, or undefined
|
|
1207
|
+
|
|
1208
|
+
table.insertRow(rowFromServer); // put a row in, or an array of rows
|
|
1209
|
+
table.updateRow({ ...table.getRow(5), name: 'Nadia' }); // replace row 5
|
|
1210
|
+
table.removeRow(5); // take row 5 out
|
|
1211
|
+
|
|
1212
|
+
table.getTotals(); // { salary: 176651.5, age: 32.5 }
|
|
1213
|
+
table.getOptions('countryId'); // [{ value: 1, label: 'Morocco' }, …]
|
|
1214
|
+
table.getApi(); // DataTables itself
|
|
1215
|
+
```
|
|
1216
|
+
|
|
1217
|
+
**Reading**
|
|
1218
|
+
|
|
1219
|
+
- `getData` and `getRow` give **copies**. Changing them changes nothing in the table: use `updateRow` for that.
|
|
1220
|
+
- `getData` follows the sorting. Its scope works like `totalRows`: `'all'` (the default), `'searched'` or `'page'`.
|
|
1221
|
+
- `getRow` gives the saved row. While a row is being edited, what's typed isn't in it until Save.
|
|
1222
|
+
|
|
1223
|
+
**Changing**
|
|
1224
|
+
|
|
1225
|
+
`insertRow`, `updateRow` and `removeRow` change the table from your code, for example when your server pushes a change. They skip the server callbacks and their events: no `onAdd`/`onAdded`, `onSave`/`onSaved`, `onDelete`/`onDeleted`, and `removeRow` never asks. Everything else follows:
|
|
1226
|
+
|
|
1227
|
+
- The totals update.
|
|
1228
|
+
- An open detail reloads after `updateRow`, and closes after `removeRow`.
|
|
1229
|
+
- A removed row leaves the selection, and `onSelect` is called.
|
|
1230
|
+
- The table stays on the page it's on.
|
|
1231
|
+
|
|
1232
|
+
When they can't:
|
|
1233
|
+
|
|
1234
|
+
- `updateRow` and `removeRow` return `false`, and change nothing, when no row has that id, or the row is being edited or deleted. That way, a change from the server never wipes what the user is typing.
|
|
1235
|
+
- `insertRow` throws if a row has no id, or its id is already in the table (or twice in the array). Either every row goes in, or none.
|
|
1236
|
+
- `updateRow` takes a whole row. To change one field, spread the current one: `{ ...table.getRow(5), name: 'Nadia' }`.
|
|
1237
|
+
|
|
1238
|
+
**Totals and options**
|
|
1239
|
+
|
|
1240
|
+
- `getTotals` gives the footer's totals by field: plain numbers for `sum`, `avg`, `min`, `max` and `count`, rounded like the footer but not formatted, or your function's text. They count the same rows as the footer.
|
|
1241
|
+
- `getOptions` gives a select's options. With a fixed list, that list. With an `options` function, the list it last loaded in an open row, or `undefined` before any row was opened. It gives `undefined` for a column that isn't a select.
|
|
1242
|
+
|
|
1243
|
+
**DataTables itself**
|
|
1244
|
+
|
|
1245
|
+
`getApi` gives the DataTables API, for anything Tadabut doesn't do, like `table.getApi().order([2, 'desc']).draw()`. Don't add or remove rows through it: that skips Tadabut, so the selection, details and open rows won't know. Use the methods above, or `setData`.
|
|
1246
|
+
|
|
945
1247
|
### React
|
|
946
1248
|
|
|
947
1249
|
Same options, as props. Keep `columns` outside your component, or in a `useMemo`, so it doesn't change on every render.
|
|
@@ -1011,17 +1313,17 @@ export default function Employees() {
|
|
|
1011
1313
|
|
|
1012
1314
|
return (
|
|
1013
1315
|
<>
|
|
1014
|
-
<button type=
|
|
1316
|
+
<button type='button' onClick={() => tableRef.current?.edit(1)}>
|
|
1015
1317
|
Edit Amina
|
|
1016
1318
|
</button>
|
|
1017
|
-
<button type=
|
|
1319
|
+
<button type='button' onClick={() => tableRef.current?.add()}>
|
|
1018
1320
|
Add an employee
|
|
1019
1321
|
</button>
|
|
1020
1322
|
|
|
1021
1323
|
<Tadabut
|
|
1022
1324
|
ref={tableRef}
|
|
1023
1325
|
data={employees}
|
|
1024
|
-
rowId=
|
|
1326
|
+
rowId='id'
|
|
1025
1327
|
columns={columns}
|
|
1026
1328
|
editing={{ mode: 'multiple' }}
|
|
1027
1329
|
onSave={(row) => saveEmployee(row)}
|
|
@@ -1041,11 +1343,14 @@ export default function Employees() {
|
|
|
1041
1343
|
```
|
|
1042
1344
|
|
|
1043
1345
|
- When `employees` changes, the table updates in place. It doesn't get rebuilt.
|
|
1044
|
-
- `onSave`, `onAdd`, `onDelete
|
|
1346
|
+
- `onSave`, `onAdd`, `onDelete`, `confirmDelete`, `onSelect` and the [events](#events) can be new functions on every render. The table always calls the latest ones.
|
|
1045
1347
|
- In `onAdd` and `onDelete`, update your state too, like above. Otherwise the next time `data` changes, the new row disappears, or the deleted one comes back.
|
|
1046
1348
|
- `totalRows` is a plain string, so writing it inline is fine. Changing it rebuilds the table, to count other rows.
|
|
1047
|
-
- `
|
|
1048
|
-
-
|
|
1349
|
+
- `selection={{ checkAll: 'page' }}` inline is fine too: only turning it on or off, or changing `checkAll`, rebuilds the table. A rebuild clears the selection.
|
|
1350
|
+
- `detail` can return JSX, async or not: `detail={(row) => <OrderLines orderId={row.id} />}`. React draws it under the row, so your components, hooks and state work inside it, and it's cleaned up when the detail closes. It can be a new function on every render: only turning it on or off rebuilds the table. This needs `react-dom`, which every React app already has.
|
|
1351
|
+
- `editing` can be a new object on every render too. The table is only rebuilt when `mode`, `button` or `doubleClick` really change. Changing `columns`, `rowId` or `editing` closes any row being edited.
|
|
1352
|
+
- The ref has the same methods as the core: `edit`, `save`, `cancel`, `delete`, `isEditing`, `add`, `saveNew`, `cancelNew`, `isAdding`, `getSelected`, `isSelected`, `select`, `deselect`, `clearSelection`, `openDetail`, `closeDetail`, `toggleDetail`, `isDetailOpen`, `getData`, `getRow`, `getApi`, `insertRow`, `updateRow`, `removeRow`, `getTotals` and `getOptions`. Before the table is built, or after it's gone, the methods that return something give `false`, `[]`, `{}` or `undefined`, and the others do nothing.
|
|
1353
|
+
- `insertRow`, `updateRow` and `removeRow` change the table, but not your `data`. The next time `data` changes, the table shows `data` again. So in React, it's usually better to change your state instead.
|
|
1049
1354
|
- There is no `setData` on the ref. To change the rows, change `data`.
|
|
1050
1355
|
|
|
1051
1356
|
## Roadmap
|
|
@@ -1071,15 +1376,19 @@ Done:
|
|
|
1071
1376
|
- [x] Checkboxes with your own values, like `'O'` and `'N'` instead of `true` and `false`
|
|
1072
1377
|
- [x] Money inputs, formatted while typing (`12 500.00`)
|
|
1073
1378
|
- [x] Totals in the footer: sum, average, min, max, count or your own
|
|
1379
|
+
- [x] A checkbox column to select rows, with "check all"
|
|
1380
|
+
- [x] More events: when editing starts (and stopping it), after saving, adding and deleting, row click and double click, and double click to edit
|
|
1381
|
+
- [x] Dates in any format (`dd/mm/yyyy`…), in the data and the cells, and sorting by the real date
|
|
1382
|
+
- [x] Detail rows that open under a row, async and with JSX in React
|
|
1383
|
+
- [x] Read-only, time and date-with-time inputs
|
|
1384
|
+
- [x] Reading and changing rows from code: `getData`, `getRow`, `insertRow`, `updateRow`, `removeRow`, `getTotals`, `getOptions` and the DataTables API
|
|
1074
1385
|
|
|
1075
1386
|
Next, roughly in this order:
|
|
1076
1387
|
|
|
1077
|
-
- [ ]
|
|
1078
|
-
- [ ] A
|
|
1079
|
-
- [ ]
|
|
1080
|
-
- [ ]
|
|
1081
|
-
- [ ] Time and read-only inputs
|
|
1082
|
-
- [ ] Methods to read rows (`getData`, `getRow`), put a row in directly without opening it, and reach the DataTables API
|
|
1388
|
+
- [ ] Totals of the ticked rows only (`totalRows: 'selected'`)
|
|
1389
|
+
- [ ] A current row: clicking a row highlights it, one at a time, apart from the checkboxes
|
|
1390
|
+
- [ ] Turning editing on and off while the table is shown
|
|
1391
|
+
- [ ] A new row that opens by itself after each `setData`, and a new row that starts with what's typed in the search box
|
|
1083
1392
|
- [ ] Keyboard navigation and theming
|
|
1084
1393
|
|
|
1085
1394
|
Later: popup editing, changing many rows in one go, server-side mode, Vue and jQuery adapters.
|