tadabut 0.2.0 → 0.4.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 +354 -45
- package/dist/index-mZisu7MG.d.ts +605 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/react.d.ts +14 -33
- package/dist/react.js +60 -38
- package/dist/src-DWwW61Yo.js +1189 -0
- package/package.json +5 -4
- package/dist/index-D2g9_Fd9.d.ts +0 -603
- package/dist/src-C4vgw-1w.js +0 -982
package/README.md
CHANGED
|
@@ -5,10 +5,14 @@
|
|
|
5
5
|
[](https://www.typescriptlang.org/)
|
|
6
6
|
[](https://datatables.net)
|
|
7
7
|
[](#roadmap)
|
|
8
|
+
[](https://www.npmjs.com/package/tadabut)
|
|
9
|
+
[](https://ayem1412.github.io/tadabut/)
|
|
8
10
|
[](./CONTRIBUTING.md)
|
|
9
11
|
|
|
10
12
|
Tadabut wraps [DataTables](https://datatables.net) and adds what it doesn't give you for free: editing rows, real inputs in the cells, and selects that depend on each other.
|
|
11
13
|
|
|
14
|
+
📖 [API reference](https://ayem1412.github.io/tadabut/): every option and type, from the code's own comments.
|
|
15
|
+
|
|
12
16
|
> [!WARNING]
|
|
13
17
|
> Tadabut is new. Until 1.0, the API can change between `0.x` versions, so pin the version you use and read the changelog before you update.
|
|
14
18
|
|
|
@@ -17,6 +21,8 @@ Tadabut wraps [DataTables](https://datatables.net) and adds what it doesn't give
|
|
|
17
21
|
DataTables is great for showing data. Editing that data inside the table is a different story: you either buy the Editor extension or write a lot of code yourself. Tadabut is that code, written once.
|
|
18
22
|
|
|
19
23
|
- Edit a row in place, then save or cancel. Saving can be async. If it fails, the row stays open with what the user typed, so nothing is lost.
|
|
24
|
+
- Add a row from your own button: it opens at the top of the table, with the same inputs and validation.
|
|
25
|
+
- Delete a row, with a question first, or your own popup.
|
|
20
26
|
- Text, number, date, checkbox and select inputs, with validation.
|
|
21
27
|
- Selects that depend on another field, like country and city. Old requests get cancelled when the user changes their mind.
|
|
22
28
|
- Fully typed. The table knows what your rows look like, so a typo in a column name is a type error.
|
|
@@ -154,7 +160,7 @@ A select's values must have the same type as the column. `countryId` is a number
|
|
|
154
160
|
| `number` | `number` | `null` | `min`, `max`, `step` |
|
|
155
161
|
| `date` | `string` | `null` | `min`, `max` |
|
|
156
162
|
| `checkbox` | `boolean` | never empty | none |
|
|
157
|
-
| `select` | same as the column | `null` | `options`, `dependsOn`
|
|
163
|
+
| `select` | same as the column | `null` | `options`, `dependsOn`, `labelProp` |
|
|
158
164
|
|
|
159
165
|
Every editor also takes `className`, for your own CSS classes.
|
|
160
166
|
|
|
@@ -167,49 +173,164 @@ A few things to know:
|
|
|
167
173
|
|
|
168
174
|
### What cells show
|
|
169
175
|
|
|
170
|
-
When a row isn't being edited, a cell shows its value as text.
|
|
176
|
+
When a row isn't being edited, a cell shows its value as text. Three things change that:
|
|
171
177
|
|
|
172
178
|
- A select with a fixed list shows the option's label. A `countryId` of `1` shows "Morocco", with nothing to write.
|
|
179
|
+
- A select with `labelProp` shows that field of the row, like `cityName`. See [Chained selects](#chained-selects).
|
|
173
180
|
- `render` sets the text yourself, on any column:
|
|
174
181
|
|
|
175
182
|
```ts
|
|
176
183
|
{ prop: 'salary', title: 'Salary', render: (value) => `${value} MAD` }
|
|
177
|
-
|
|
178
|
-
// A select whose options come from a function: Tadabut can't know the
|
|
179
|
-
// label, but the row usually has it.
|
|
180
|
-
{ prop: 'cityId', title: 'City', render: (value, row) => row.cityName, editor: { … } }
|
|
181
184
|
```
|
|
182
185
|
|
|
183
186
|
A few things to know:
|
|
184
187
|
|
|
185
|
-
- `render`
|
|
188
|
+
- The order is: `render`, then `labelProp`, then the fixed list's label, then the value itself.
|
|
186
189
|
- 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.
|
|
187
190
|
- Searching uses the text. Sorting uses the raw value, so `200 MAD` comes before `1000 MAD`. A city column sorts by id, not by name.
|
|
188
191
|
- An empty value (`null` or `undefined`) shows an empty cell. On a nullable column, `render` gets `null` too.
|
|
189
192
|
- Editors always get the raw value. After saving or cancelling, the text is worked out again.
|
|
190
193
|
|
|
194
|
+
### Column options
|
|
195
|
+
|
|
196
|
+
A few more column settings, passed to DataTables:
|
|
197
|
+
|
|
198
|
+
```ts
|
|
199
|
+
const columns: Column<Employee>[] = [
|
|
200
|
+
{ prop: 'id', title: 'ID', width: '60px', className: 'dt-center' },
|
|
201
|
+
{ prop: 'name', title: 'Name', editor: { type: 'text' } },
|
|
202
|
+
{ prop: 'countryCode', title: 'Code', visible: false },
|
|
203
|
+
{ prop: 'salary', title: 'Salary', orderable: false, searchable: false },
|
|
204
|
+
];
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
| Option | What it does |
|
|
208
|
+
| ------------ | --------------------------------------------------------------------------- |
|
|
209
|
+
| `width` | the column's width, like `'60px'` or `'20%'` |
|
|
210
|
+
| `visible` | `false` hides the column. Its value stays in the row, and `onSave` gets it. |
|
|
211
|
+
| `orderable` | `false`: clicking the header doesn't sort by it |
|
|
212
|
+
| `searchable` | `false`: the search box ignores it |
|
|
213
|
+
| `className` | classes for the column's cells, header included |
|
|
214
|
+
|
|
215
|
+
`className` here is for the cells. The input's classes go in the editor's `className`.
|
|
216
|
+
|
|
217
|
+
A hidden column can't have an `editor`: nobody could see the input. Tadabut throws an error when you try.
|
|
218
|
+
|
|
219
|
+
### DataTables settings
|
|
220
|
+
|
|
221
|
+
`dataTables` passes DataTables' own settings through as they are: paging, page sizes, the default order, the texts, and the settings of extensions like Buttons. See [DataTables' options](https://datatables.net/reference/option/) for the full list.
|
|
222
|
+
|
|
223
|
+
```ts
|
|
224
|
+
const table = new Tadabut(container, {
|
|
225
|
+
data: employees,
|
|
226
|
+
rowId: 'id',
|
|
227
|
+
columns,
|
|
228
|
+
dataTables: {
|
|
229
|
+
order: [[1, 'asc']], // sort by the second column
|
|
230
|
+
pageLength: 20,
|
|
231
|
+
lengthMenu: [10, 20, 50, -1], // -1 means "All"
|
|
232
|
+
language: {
|
|
233
|
+
search: 'Rechercher :',
|
|
234
|
+
lengthMenu: '_MENU_ lignes par page',
|
|
235
|
+
info: 'Lignes _START_ à _END_ sur _TOTAL_',
|
|
236
|
+
zeroRecords: 'Aucune ligne trouvée',
|
|
237
|
+
paginate: { first: 'Premier', previous: 'Précédent', next: 'Suivant', last: 'Dernier' },
|
|
238
|
+
},
|
|
239
|
+
},
|
|
240
|
+
});
|
|
241
|
+
```
|
|
242
|
+
|
|
243
|
+
Columns are counted from 0, in the order of your `columns`. The Edit button column always comes last, so it never moves your columns.
|
|
244
|
+
|
|
245
|
+
Five settings aren't allowed, because Tadabut controls them:
|
|
246
|
+
|
|
247
|
+
- `data` and `columns`: Tadabut makes them from its own `data` and `columns`.
|
|
248
|
+
- `columnDefs`: use the column options above instead.
|
|
249
|
+
- `ajax` and `serverSide`: DataTables would load and replace rows behind Tadabut's back. Load the rows yourself and call `setData`.
|
|
250
|
+
|
|
251
|
+
These are type errors, and Tadabut's own values win even in plain JavaScript.
|
|
252
|
+
|
|
253
|
+
`language` only changes DataTables' texts. For Tadabut's own texts, see [Texts and translations](#texts-and-translations).
|
|
254
|
+
|
|
255
|
+
In React, keep `dataTables` outside your component or in a `useMemo`, like `columns`. A new object on every render rebuilds the table.
|
|
256
|
+
|
|
257
|
+
### Texts and translations
|
|
258
|
+
|
|
259
|
+
Tadabut's own texts (the Edit, Save, Cancel and Delete buttons, the delete question, "Loading…", and the error messages) are in English by default. French comes built in:
|
|
260
|
+
|
|
261
|
+
```ts
|
|
262
|
+
import { Tadabut, fr } from 'tadabut';
|
|
263
|
+
|
|
264
|
+
const table = new Tadabut(container, { data, columns, rowId: 'id', texts: fr });
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Change only some of them, or write your own language. Whatever you leave out stays in English:
|
|
268
|
+
|
|
269
|
+
```ts
|
|
270
|
+
texts: { ...fr, save: 'Valider' }
|
|
271
|
+
|
|
272
|
+
texts: { edit: 'Bearbeiten', save: 'Speichern', cancel: 'Abbrechen' }
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
| Key | English |
|
|
276
|
+
| ------------------------ | ------------------------------- |
|
|
277
|
+
| `edit`, `save`, `cancel` | Edit, Save, Cancel |
|
|
278
|
+
| `delete` | Delete |
|
|
279
|
+
| `deleteQuestion` | Delete this row? |
|
|
280
|
+
| `confirm`, `keep` | Yes, delete / No |
|
|
281
|
+
| `loading` | Loading… |
|
|
282
|
+
| `saveFailed` | Could not save. |
|
|
283
|
+
| `addFailed` | Could not add. |
|
|
284
|
+
| `deleteFailed` | Could not delete. |
|
|
285
|
+
| `loadFailed` | Could not load the options. |
|
|
286
|
+
| `required` | This field is required. |
|
|
287
|
+
| `patternMismatch` | Wrong format. |
|
|
288
|
+
| `tooShort`, `tooLong` | Must be at least 2 characters. |
|
|
289
|
+
| `tooSmall`, `tooLarge` | Must be 18 or more. |
|
|
290
|
+
| `tooEarly`, `tooLate` | Must be on or after 2020-01-01. |
|
|
291
|
+
|
|
292
|
+
The messages with a number or a date are functions, so you can put the value where your language needs it:
|
|
293
|
+
|
|
294
|
+
```ts
|
|
295
|
+
texts: {
|
|
296
|
+
tooSmall: (min) => `Mindestens ${min}.`;
|
|
297
|
+
}
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
`saveFailed`, `addFailed` and `deleteFailed` only show when `onSave`, `onAdd` or `onDelete` throws something that isn't an `Error`. When it throws an `Error`, its own message is shown.
|
|
301
|
+
|
|
302
|
+
DataTables' own texts (search, paging, "Showing 1 to 10") are set separately, with `dataTables.language`. See [DataTables settings](#datatables-settings).
|
|
303
|
+
|
|
304
|
+
In React, `texts={fr}` is fine. A new object on every render (like `texts={{ ...fr, save: 'Valider' }}` written inline) rebuilds the table each time, so put it in a constant or a `useMemo`.
|
|
305
|
+
|
|
191
306
|
### Styling
|
|
192
307
|
|
|
193
308
|
Tadabut doesn't ship any CSS. Everything it creates gets these classes, so you can style it however you want:
|
|
194
309
|
|
|
195
|
-
| Class
|
|
196
|
-
|
|
|
197
|
-
| `tdb-input`
|
|
198
|
-
| `tdb-input-text`
|
|
199
|
-
| `tdb-input-number`
|
|
200
|
-
| `tdb-input-date`
|
|
201
|
-
| `tdb-input-checkbox`
|
|
202
|
-
| `tdb-input-select`
|
|
203
|
-
| `tdb-error`
|
|
204
|
-
| `tdb-
|
|
205
|
-
| `tdb-
|
|
206
|
-
| `tdb-row-editing`
|
|
207
|
-
| `tdb-row-saving`
|
|
208
|
-
| `tdb-
|
|
209
|
-
| `tdb-
|
|
210
|
-
| `tdb-
|
|
211
|
-
| `tdb-button
|
|
212
|
-
| `tdb-button-
|
|
310
|
+
| Class | Used on |
|
|
311
|
+
| ----------------------- | ----------------------------------------------------------- |
|
|
312
|
+
| `tdb-input` | every input |
|
|
313
|
+
| `tdb-input-text` | text inputs |
|
|
314
|
+
| `tdb-input-number` | number inputs |
|
|
315
|
+
| `tdb-input-date` | date inputs |
|
|
316
|
+
| `tdb-input-checkbox` | checkboxes |
|
|
317
|
+
| `tdb-input-select` | selects |
|
|
318
|
+
| `tdb-error` | a field's error message, under its input |
|
|
319
|
+
| `tdb-row-error` | the line (`<tr>`) under a row that failed to save or delete |
|
|
320
|
+
| `tdb-row-error-message` | the message inside that line |
|
|
321
|
+
| `tdb-row-editing` | a row while it's being edited, and the new row |
|
|
322
|
+
| `tdb-row-saving` | a row while it's being saved, added or deleted |
|
|
323
|
+
| `tdb-row-new` | the new row `add()` opens |
|
|
324
|
+
| `tdb-new-rows` | the `<tbody>` it lives in, above the others |
|
|
325
|
+
| `tdb-actions` | the column with the buttons, header too |
|
|
326
|
+
| `tdb-button` | every button |
|
|
327
|
+
| `tdb-button-edit` | the Edit button |
|
|
328
|
+
| `tdb-button-save` | the Save button |
|
|
329
|
+
| `tdb-button-cancel` | the Cancel button |
|
|
330
|
+
| `tdb-button-delete` | the Delete button |
|
|
331
|
+
| `tdb-delete-question` | the "Delete this row?" text |
|
|
332
|
+
| `tdb-button-confirm` | the "Yes, delete" button |
|
|
333
|
+
| `tdb-button-keep` | the "No" button |
|
|
213
334
|
|
|
214
335
|
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:
|
|
215
336
|
|
|
@@ -236,13 +357,16 @@ const table = new Tadabut(container, {
|
|
|
236
357
|
});
|
|
237
358
|
```
|
|
238
359
|
|
|
239
|
-
| `classNames` key | Added to
|
|
240
|
-
| ---------------- |
|
|
241
|
-
| `table` | the `<table>`
|
|
242
|
-
| `button` |
|
|
243
|
-
| `edit` | the Edit button only
|
|
244
|
-
| `save` | the Save button only
|
|
245
|
-
| `cancel` | the Cancel button only
|
|
360
|
+
| `classNames` key | Added to |
|
|
361
|
+
| ---------------- | ----------------------------- |
|
|
362
|
+
| `table` | the `<table>` |
|
|
363
|
+
| `button` | every button |
|
|
364
|
+
| `edit` | the Edit button only |
|
|
365
|
+
| `save` | the Save button only |
|
|
366
|
+
| `cancel` | the Cancel button only |
|
|
367
|
+
| `delete` | the Delete button only |
|
|
368
|
+
| `confirm` | the "Yes, delete" button only |
|
|
369
|
+
| `keep` | the "No" button only |
|
|
246
370
|
|
|
247
371
|
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.
|
|
248
372
|
|
|
@@ -299,6 +423,9 @@ const table = new Tadabut(container, {
|
|
|
299
423
|
edit: 'btn-outline-primary',
|
|
300
424
|
save: 'btn-primary',
|
|
301
425
|
cancel: 'btn-outline-secondary',
|
|
426
|
+
delete: 'btn-outline-danger',
|
|
427
|
+
confirm: 'btn-danger',
|
|
428
|
+
keep: 'btn-outline-secondary',
|
|
302
429
|
},
|
|
303
430
|
});
|
|
304
431
|
```
|
|
@@ -309,7 +436,7 @@ Error messages and the rows being edited need a few lines of your own CSS:
|
|
|
309
436
|
/* Errors in Bootstrap's red. Use the message's class, not the row's:
|
|
310
437
|
Bootstrap sets a color on every table cell. */
|
|
311
438
|
.tdb-error,
|
|
312
|
-
.tdb-
|
|
439
|
+
.tdb-row-error-message {
|
|
313
440
|
color: var(--bs-form-invalid-color);
|
|
314
441
|
font-size: 0.875em;
|
|
315
442
|
}
|
|
@@ -323,6 +450,15 @@ Error messages and the rows being edited need a few lines of your own CSS:
|
|
|
323
450
|
.tdb-row-saving {
|
|
324
451
|
opacity: 0.5;
|
|
325
452
|
}
|
|
453
|
+
|
|
454
|
+
/* Space between the buttons, and after "Delete this row?". */
|
|
455
|
+
.tdb-button + .tdb-button {
|
|
456
|
+
margin-left: 0.25rem;
|
|
457
|
+
}
|
|
458
|
+
|
|
459
|
+
.tdb-delete-question {
|
|
460
|
+
margin-right: 0.5rem;
|
|
461
|
+
}
|
|
326
462
|
```
|
|
327
463
|
|
|
328
464
|
> [!TIP]
|
|
@@ -432,7 +568,7 @@ The checks run in this order, and the first error wins:
|
|
|
432
568
|
|
|
433
569
|
`pattern` has to match the whole value, like the HTML attribute. A checkbox is never empty, so `required` does nothing on it.
|
|
434
570
|
|
|
435
|
-
Errors show under their input when the user saves, and a row can't be saved until every field is valid.
|
|
571
|
+
Errors show under their input when the user saves, and a row can't be saved until every field is valid. To change the messages, see [Texts and translations](#texts-and-translations).
|
|
436
572
|
|
|
437
573
|
### Chained selects
|
|
438
574
|
|
|
@@ -458,11 +594,13 @@ const columns: Column<Employee>[] = [
|
|
|
458
594
|
type: 'select',
|
|
459
595
|
required: true,
|
|
460
596
|
dependsOn: 'countryId',
|
|
597
|
+
labelProp: 'cityName',
|
|
461
598
|
options: async (row, { signal }) => {
|
|
462
599
|
if (row.countryId === null) return [];
|
|
463
600
|
|
|
464
601
|
const res = await fetch(`/api/cities?country=${row.countryId}`, { signal });
|
|
465
|
-
|
|
602
|
+
const cities: { id: number; name: string }[] = await res.json();
|
|
603
|
+
return cities.map((city) => ({ value: city.id, label: city.name }));
|
|
466
604
|
},
|
|
467
605
|
},
|
|
468
606
|
},
|
|
@@ -477,12 +615,24 @@ How it works:
|
|
|
477
615
|
- A cleared field is `null`, and the functions below it still run. That's why the example checks `row.countryId === null`. Returning `[]` right away costs nothing.
|
|
478
616
|
- If the user changes the country again before the cities come back, the old request is cancelled through `signal`. Pass it to `fetch` so the request really stops. Even if you don't, a late answer is thrown away.
|
|
479
617
|
- Cancelling or saving the row, `setData` and `destroy` cancel every request still running.
|
|
618
|
+
- In a new row (see [Adding](#adding)), nothing is picked yet, so the functions first run with an empty parent. Another reason to return `[]` for `null`.
|
|
480
619
|
|
|
481
620
|
If `options` throws, the select stays empty and "Could not load the options." shows under it. The row can't be saved while that message is there. Changing the field it depends on tries again, or the user can cancel the row.
|
|
482
621
|
|
|
483
622
|
`dependsOn` only works with a function. With a fixed list, it's a type error. It must be another field of the row, so a typo is a type error too.
|
|
484
623
|
|
|
485
|
-
|
|
624
|
+
#### Saving the label too: `labelProp`
|
|
625
|
+
|
|
626
|
+
The city's value is an id, like `12`, but people need to see "Casablanca". With options from a function, Tadabut only knows the names while the row is open, so it can't show them in the cell by itself. That's what `labelProp` is for: a field of the row where the picked option's label is saved.
|
|
627
|
+
|
|
628
|
+
With `labelProp: 'cityName'`:
|
|
629
|
+
|
|
630
|
+
- The cell shows `row.cityName`. No `render` needed.
|
|
631
|
+
- When the user picks Casablanca and saves, the row gets `cityId: 12` **and** `cityName: 'Casablanca'`. `onSave` gets both, and the cell shows the new name.
|
|
632
|
+
- Nothing picked saves `null` in both. `required` still stops the save.
|
|
633
|
+
- While the options are still loading, `cityName` keeps its old value, which is still right: the id didn't change either.
|
|
634
|
+
|
|
635
|
+
`labelProp` works with a fixed list too. It must be a text field of the row (`string`, nullable or optional ones too), so `labelProp: 'age'` is a type error. It can't be the column's own `prop`: saving would write the label over the id, so Tadabut throws an error.
|
|
486
636
|
|
|
487
637
|
### Saving
|
|
488
638
|
|
|
@@ -525,9 +675,106 @@ The table's data only changes when saving works, so there's nothing to undo when
|
|
|
525
675
|
|
|
526
676
|
`onSave` is optional. Without it, saving just updates the table.
|
|
527
677
|
|
|
678
|
+
### Adding
|
|
679
|
+
|
|
680
|
+
Call `add()` from your own button. An empty row opens at the top of the table, with the same inputs, validation and Save/Cancel as an edited row. Save calls `onAdd`.
|
|
681
|
+
|
|
682
|
+
```ts
|
|
683
|
+
async function createEmployee(row: Partial<Employee>): Promise<Employee> {
|
|
684
|
+
const res = await fetch('/api/employees', {
|
|
685
|
+
method: 'POST',
|
|
686
|
+
headers: { 'Content-Type': 'application/json' },
|
|
687
|
+
body: JSON.stringify(row),
|
|
688
|
+
});
|
|
689
|
+
|
|
690
|
+
if (!res.ok) throw new Error('Could not add the employee');
|
|
691
|
+
|
|
692
|
+
return res.json(); // the row with its new id
|
|
693
|
+
}
|
|
694
|
+
|
|
695
|
+
const table = new Tadabut(container, {
|
|
696
|
+
data: employees,
|
|
697
|
+
rowId: 'id',
|
|
698
|
+
columns,
|
|
699
|
+
onSave: saveEmployee,
|
|
700
|
+
onAdd: createEmployee,
|
|
701
|
+
});
|
|
702
|
+
|
|
703
|
+
addButton.addEventListener('click', () => table.add());
|
|
704
|
+
```
|
|
705
|
+
|
|
706
|
+
What happens:
|
|
707
|
+
|
|
708
|
+
1. `add()` opens the row at the top, with the cursor in the first input. Sorting, search and paging never move it: it lives in its own `<tbody>`, above the table's rows.
|
|
709
|
+
2. Save, or <kbd>Enter</kbd>, validates the fields. Cancel, or <kbd>Escape</kbd>, throws the row away.
|
|
710
|
+
3. `onAdd` gets the typed row. The row is locked while it runs.
|
|
711
|
+
4. If `onAdd` works, the row joins the table, and the table shows the page it landed on. If the search box hides it, the table stays where it is.
|
|
712
|
+
5. If `onAdd` throws, the row stays open with what the user typed, and your error message shows under it.
|
|
713
|
+
|
|
714
|
+
**What `onAdd` gets and returns:**
|
|
715
|
+
|
|
716
|
+
- It gets a `Partial` row, because the row isn't saved yet: the id, and columns without an editor, are only there if you gave them to `add()`. TypeScript makes you check them.
|
|
717
|
+
- Return the saved row, usually with the id the server made, or nothing to keep the row as typed.
|
|
718
|
+
- Either way, the row must have its `rowId`. If it doesn't, Tadabut throws `Tadabut: the added row has no "id". Return it from onAdd.` That's a mistake in your code, so it goes to the console, and the row stays open.
|
|
719
|
+
- Without `onAdd`, the row is added as typed. That's fine for a table that only lives in the page, as long as the id comes from an input or from `add({ id })`.
|
|
720
|
+
|
|
721
|
+
**Starting values:** `table.add({ country: 'MA', active: true })`. Inputs start with them, and columns without an editor show them as text. Those cells don't use the column's `render`.
|
|
722
|
+
|
|
723
|
+
**Rules:**
|
|
724
|
+
|
|
725
|
+
- One new row at a time. `add()` returns `false` if one is already open.
|
|
726
|
+
- In `'single'` mode, the new row counts as the open row: you can't add while a row is edited, and you can't edit while the new row is open. In `'multiple'` mode, both work together.
|
|
727
|
+
- `setData` and `destroy` throw the new row away, like any open row.
|
|
728
|
+
|
|
729
|
+
### Deleting
|
|
730
|
+
|
|
731
|
+
Give the table an `onDelete`, and each row gets a Delete button next to Edit. It can be async, like `onSave`.
|
|
732
|
+
|
|
733
|
+
```ts
|
|
734
|
+
async function deleteEmployee(row: Employee) {
|
|
735
|
+
const res = await fetch(`/api/employees/${row.id}`, { method: 'DELETE' });
|
|
736
|
+
|
|
737
|
+
if (!res.ok) throw new Error('Could not delete the employee');
|
|
738
|
+
}
|
|
739
|
+
|
|
740
|
+
const table = new Tadabut(container, {
|
|
741
|
+
data: employees,
|
|
742
|
+
rowId: 'id',
|
|
743
|
+
columns,
|
|
744
|
+
onSave: saveEmployee,
|
|
745
|
+
onDelete: deleteEmployee,
|
|
746
|
+
});
|
|
747
|
+
```
|
|
748
|
+
|
|
749
|
+
What happens when you click Delete:
|
|
750
|
+
|
|
751
|
+
1. The buttons are replaced by "Delete this row? [Yes, delete] [No]". The cursor goes to No, so pressing <kbd>Enter</kbd> by reflex doesn't delete anything.
|
|
752
|
+
2. No puts Edit and Delete back.
|
|
753
|
+
3. Yes calls `onDelete` with the row. The row is locked while it runs, and gets the `tdb-row-saving` class.
|
|
754
|
+
4. If `onDelete` works, the row is removed. You stay on the same page.
|
|
755
|
+
5. If `onDelete` throws, the row stays, and your error message shows under it.
|
|
756
|
+
|
|
757
|
+
A row that's being edited has Save and Cancel instead, so it can't be deleted halfway through an edit. `onDelete` needs a `rowId`, and Tadabut throws an error without one.
|
|
758
|
+
|
|
759
|
+
#### Your own question: `confirmDelete`
|
|
760
|
+
|
|
761
|
+
```ts
|
|
762
|
+
confirmDelete: false, // delete right away, no question
|
|
763
|
+
|
|
764
|
+
confirmDelete: (row) => window.confirm(`Delete ${row.name}?`), // the browser's popup
|
|
765
|
+
|
|
766
|
+
// any modal, as long as it returns true to delete
|
|
767
|
+
confirmDelete: async (row) => {
|
|
768
|
+
const result = await Swal.fire({ title: `Delete ${row.name}?`, showCancelButton: true });
|
|
769
|
+
return result.isConfirmed;
|
|
770
|
+
},
|
|
771
|
+
```
|
|
772
|
+
|
|
773
|
+
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`).
|
|
774
|
+
|
|
528
775
|
### Editing options
|
|
529
776
|
|
|
530
|
-
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
|
|
777
|
+
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`.
|
|
531
778
|
|
|
532
779
|
`editing` changes how that works:
|
|
533
780
|
|
|
@@ -546,7 +793,7 @@ const table = new Tadabut(container, {
|
|
|
546
793
|
|
|
547
794
|
- `'single'` mode: one row at a time. You can't start a new edit while another row is open.
|
|
548
795
|
- `'multiple'` mode: several rows can be open. Each one saves on its own, so `onSave` runs once per row.
|
|
549
|
-
- `button: false`: no
|
|
796
|
+
- `button: false`: no Edit button. Start edits from your own code. <kbd>Enter</kbd> and <kbd>Escape</kbd> still work. With `onDelete`, the column stays, with only the Delete button.
|
|
550
797
|
|
|
551
798
|
### Controlling it from code
|
|
552
799
|
|
|
@@ -555,6 +802,12 @@ table.edit(5); // start editing the row with id 5
|
|
|
555
802
|
await table.save(5); // validate and save it
|
|
556
803
|
table.cancel(5); // cancel and restore its old values
|
|
557
804
|
table.isEditing(5); // true while row 5 is open
|
|
805
|
+
await table.delete(5); // call onDelete, then remove the row
|
|
806
|
+
|
|
807
|
+
table.add({ country: 'MA' }); // open a new row at the top
|
|
808
|
+
await table.saveNew(); // validate it and call onAdd
|
|
809
|
+
table.cancelNew(); // throw the new row away
|
|
810
|
+
table.isAdding(); // true while the new row is open
|
|
558
811
|
|
|
559
812
|
table.setData(newEmployees); // replace all rows, keeps sorting and search
|
|
560
813
|
table.destroy(); // remove everything Tadabut created
|
|
@@ -566,7 +819,11 @@ table.destroy(); // remove everything Tadabut created
|
|
|
566
819
|
|
|
567
820
|
`cancel` does nothing if the row isn't being edited, or while it's saving.
|
|
568
821
|
|
|
569
|
-
`
|
|
822
|
+
`delete` never asks first: only the Delete button does. It returns a promise of `true` once the row is removed, `false` if it wasn't: the row doesn't exist, it's being edited, it's already being deleted, or `onDelete` failed. Without `onDelete`, it just removes the row.
|
|
823
|
+
|
|
824
|
+
`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.
|
|
825
|
+
|
|
826
|
+
`setData` and `destroy` cancel any row being edited, and the new row, first. Unsaved changes are lost.
|
|
570
827
|
|
|
571
828
|
<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.
|
|
572
829
|
|
|
@@ -612,8 +869,26 @@ async function saveEmployee(row: Employee): Promise<void> {
|
|
|
612
869
|
if (!res.ok) throw new Error('Could not save the employee');
|
|
613
870
|
}
|
|
614
871
|
|
|
872
|
+
async function createEmployee(row: Partial<Employee>): Promise<Employee> {
|
|
873
|
+
const res = await fetch('/api/employees', {
|
|
874
|
+
method: 'POST',
|
|
875
|
+
headers: { 'Content-Type': 'application/json' },
|
|
876
|
+
body: JSON.stringify(row),
|
|
877
|
+
});
|
|
878
|
+
|
|
879
|
+
if (!res.ok) throw new Error('Could not add the employee');
|
|
880
|
+
|
|
881
|
+
return res.json();
|
|
882
|
+
}
|
|
883
|
+
|
|
884
|
+
async function deleteEmployee(row: Employee): Promise<void> {
|
|
885
|
+
const res = await fetch(`/api/employees/${row.id}`, { method: 'DELETE' });
|
|
886
|
+
|
|
887
|
+
if (!res.ok) throw new Error('Could not delete the employee');
|
|
888
|
+
}
|
|
889
|
+
|
|
615
890
|
export default function Employees() {
|
|
616
|
-
const [employees] = useState<Employee[]>([
|
|
891
|
+
const [employees, setEmployees] = useState<Employee[]>([
|
|
617
892
|
{ id: 1, name: 'Amina', countryId: 1 },
|
|
618
893
|
{ id: 2, name: 'Paul', countryId: 2 },
|
|
619
894
|
]);
|
|
@@ -624,6 +899,9 @@ export default function Employees() {
|
|
|
624
899
|
<button type="button" onClick={() => tableRef.current?.edit(1)}>
|
|
625
900
|
Edit Amina
|
|
626
901
|
</button>
|
|
902
|
+
<button type="button" onClick={() => tableRef.current?.add()}>
|
|
903
|
+
Add an employee
|
|
904
|
+
</button>
|
|
627
905
|
|
|
628
906
|
<Tadabut
|
|
629
907
|
ref={tableRef}
|
|
@@ -632,6 +910,15 @@ export default function Employees() {
|
|
|
632
910
|
columns={columns}
|
|
633
911
|
editing={{ mode: 'multiple' }}
|
|
634
912
|
onSave={(row) => saveEmployee(row)}
|
|
913
|
+
onAdd={async (row) => {
|
|
914
|
+
const saved = await createEmployee(row);
|
|
915
|
+
setEmployees((current) => [...current, saved]);
|
|
916
|
+
return saved;
|
|
917
|
+
}}
|
|
918
|
+
onDelete={async (row) => {
|
|
919
|
+
await deleteEmployee(row);
|
|
920
|
+
setEmployees((current) => current.filter((e) => e.id !== row.id));
|
|
921
|
+
}}
|
|
635
922
|
/>
|
|
636
923
|
</>
|
|
637
924
|
);
|
|
@@ -639,13 +926,16 @@ export default function Employees() {
|
|
|
639
926
|
```
|
|
640
927
|
|
|
641
928
|
- When `employees` changes, the table updates in place. It doesn't get rebuilt.
|
|
642
|
-
- `onSave` can be
|
|
929
|
+
- `onSave`, `onAdd`, `onDelete` and `confirmDelete` can be new functions on every render. The table always calls the latest ones.
|
|
930
|
+
- 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.
|
|
643
931
|
- `editing` can be a new object on every render too. The table is only rebuilt when `mode` or `button` really change. Changing `columns`, `rowId` or `editing` closes any row being edited.
|
|
644
|
-
- The ref has `edit`, `save`, `cancel`
|
|
932
|
+
- The ref has the same methods as the core: `edit`, `save`, `cancel`, `delete`, `isEditing`, `add`, `saveNew`, `cancelNew` and `isAdding`. Before the table is built, or after it's gone, they give `false` and `cancel` and `cancelNew` do nothing.
|
|
645
933
|
- There is no `setData` on the ref. To change the rows, change `data`.
|
|
646
934
|
|
|
647
935
|
## Roadmap
|
|
648
936
|
|
|
937
|
+
Done:
|
|
938
|
+
|
|
649
939
|
- [x] Project setup
|
|
650
940
|
- [x] Thin wrapper: typed columns, data loading, cleanup
|
|
651
941
|
- [x] React adapter
|
|
@@ -655,9 +945,28 @@ export default function Employees() {
|
|
|
655
945
|
- [x] Chained selects
|
|
656
946
|
- [x] Show labels instead of raw values in cells
|
|
657
947
|
- [x] First release (0.1.0)
|
|
658
|
-
- [
|
|
659
|
-
|
|
660
|
-
|
|
948
|
+
- [x] Your own classes on the table and buttons (`classNames`), and a Bootstrap 5 recipe
|
|
949
|
+
- [x] API reference site
|
|
950
|
+
- [x] Pass DataTables settings through (paging, page sizes, default order, language, extensions like Buttons), and column `width`, `visible`, `orderable`, `searchable` and `className`
|
|
951
|
+
- [x] Selects that also save their label in the row (`labelProp`), so the cell shows the new label after a save
|
|
952
|
+
- [x] Translations for Tadabut's own texts (buttons and error messages), French built in
|
|
953
|
+
- [x] Deleting rows, with a question first that you can replace (`confirmDelete`)
|
|
954
|
+
- [x] Adding new rows, at the top of the table (`add()` and `onAdd`)
|
|
955
|
+
|
|
956
|
+
Next, roughly in this order:
|
|
957
|
+
|
|
958
|
+
- [ ] Checkboxes with your own values, like `'O'` and `'N'` instead of `true` and `false`
|
|
959
|
+
- [ ] Money inputs, formatted while typing (`12 500.00`)
|
|
960
|
+
- [ ] Dates as `dd/mm/yyyy`, in the input and when sorting
|
|
961
|
+
- [ ] Totals in the footer
|
|
962
|
+
- [ ] A checkbox column to select rows, with "check all"
|
|
963
|
+
- [ ] More events: when editing starts, after saving, row click and double click
|
|
964
|
+
- [ ] Detail rows that open under a row
|
|
965
|
+
- [ ] Time and read-only inputs
|
|
966
|
+
- [ ] Methods to read rows (`getData`, `getRow`), put a row in directly without opening it, and reach the DataTables API
|
|
967
|
+
- [ ] Keyboard navigation and theming
|
|
968
|
+
|
|
969
|
+
Later: popup editing, changing many rows in one go, server-side mode, Vue and jQuery adapters.
|
|
661
970
|
|
|
662
971
|
## Contributing
|
|
663
972
|
|