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 CHANGED
@@ -5,10 +5,14 @@
5
5
  [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
6
6
  [![DataTables 3](https://img.shields.io/badge/DataTables-3.x-0d6efd)](https://datatables.net)
7
7
  [![Status](https://img.shields.io/badge/status-early%20development-orange)](#roadmap)
8
+ [![npm](https://img.shields.io/npm/v/tadabut)](https://www.npmjs.com/package/tadabut)
9
+ [![Docs](https://img.shields.io/badge/docs-API%20reference-blue)](https://ayem1412.github.io/tadabut/)
8
10
  [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./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. Two things change that:
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` wins over a select's label.
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 | Used on |
196
- | ------------------------ | ------------------------------------------------- |
197
- | `tdb-input` | every input |
198
- | `tdb-input-text` | text inputs |
199
- | `tdb-input-number` | number inputs |
200
- | `tdb-input-date` | date inputs |
201
- | `tdb-input-checkbox` | checkboxes |
202
- | `tdb-input-select` | selects |
203
- | `tdb-error` | a field's error message, under its input |
204
- | `tdb-save-error` | the line (`<tr>`) under a row that failed to save |
205
- | `tdb-save-error-message` | the message inside that line |
206
- | `tdb-row-editing` | a row while it's being edited |
207
- | `tdb-row-saving` | a row while it's being saved |
208
- | `tdb-actions` | the column with the buttons, header too |
209
- | `tdb-button` | every button |
210
- | `tdb-button-edit` | the Edit button |
211
- | `tdb-button-save` | the Save button |
212
- | `tdb-button-cancel` | the Cancel 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` | the Edit, Save and Cancel buttons |
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-save-error-message {
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. Messages are in English for now. You'll be able to change them when translations are added.
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
- return res.json(); // [{ value, label }, …]
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
- Outside edit mode, the city cell needs a `render` to show a name instead of an id. See [What cells show](#what-cells-show).
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 are in English for now.
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 buttons column. Start edits from your own code. <kbd>Enter</kbd> and <kbd>Escape</kbd> still work.
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
- `setData` and `destroy` cancel any row being edited first. Unsaved changes are lost.
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 a new function on every render. The table always calls the latest one.
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` and `isEditing`, the same as the core. Before the table is built, or after it's gone, `edit` and `save` give `false` and `cancel` does nothing.
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
- - [ ] Keyboard navigation, translations, theming
659
-
660
- Later: adding and deleting rows, popup editing, changing many rows in one go, server-side mode, Vue and jQuery adapters.
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