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 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, only if you use the React adapter
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, which your app most likely has already.
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 date gives `null`, not `0` or `NaN`. A select with nothing picked gives `null` too.
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 must hold `'YYYY-MM-DD'`. Something like `'2024-01-05T00:00:00'` shows as empty, and saving turns it into `null`. Convert your dates first.
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 | English |
382
- | ------------------------ | ------------------------------- |
383
- | `edit`, `save`, `cancel` | Edit, Save, Cancel |
384
- | `delete` | Delete |
385
- | `deleteQuestion` | Delete this row? |
386
- | `confirm`, `keep` | Yes, delete / No |
387
- | `loading` | Loading… |
388
- | `saveFailed` | Could not save. |
389
- | `addFailed` | Could not add. |
390
- | `deleteFailed` | Could not delete. |
391
- | `total` | Total |
392
- | `loadFailed` | Could not load the options. |
393
- | `required` | This field is required. |
394
- | `patternMismatch` | Wrong format. |
395
- | `tooShort`, `tooLong` | Must be at least 2 characters. |
396
- | `tooSmall`, `tooLarge` | Must be 18 or more. |
397
- | `tooEarly`, `tooLate` | Must be on or after 2020-01-01. |
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
- - `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.
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
- `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, 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.
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="button" onClick={() => tableRef.current?.edit(1)}>
1316
+ <button type='button' onClick={() => tableRef.current?.edit(1)}>
1015
1317
  Edit Amina
1016
1318
  </button>
1017
- <button type="button" onClick={() => tableRef.current?.add()}>
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="id"
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` and `confirmDelete` can be new functions on every render. The table always calls the latest ones.
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
- - `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.
1048
- - 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.
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
- - [ ] Dates as `dd/mm/yyyy`, in the input and when sorting
1078
- - [ ] A checkbox column to select rows, with "check all"
1079
- - [ ] More events: when editing starts, after saving, row click and double click
1080
- - [ ] Detail rows that open under a row
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.