tadabut 0.5.0 → 0.6.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 +162 -29
- package/dist/{index-KmSXRJlI.d.ts → index-C_77p8Jv.d.ts} +166 -13
- package/dist/index.d.ts +8 -2
- package/dist/index.js +1 -1
- package/dist/react.d.ts +23 -8
- package/dist/react.js +55 -10
- package/dist/{src-CBK3xu9-.js → src-BxdYoViF.js} +418 -37
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -170,7 +170,7 @@ A select's values must have the same type as the column. `countryId` is a number
|
|
|
170
170
|
| `text` | `string` | `''` | `minLength`, `maxLength`, `pattern` |
|
|
171
171
|
| `number` | `number` | `null` | `min`, `max`, `step` |
|
|
172
172
|
| `money` | `number` | `null` | `min`, `max`, `decimals`, `separator`, `point` |
|
|
173
|
-
| `date` | `string` | `null` | `min`, `max`
|
|
173
|
+
| `date` | `string` | `null` | `min`, `max`, `format`, `display` |
|
|
174
174
|
| `checkbox` | `boolean`, or `values` | never empty | `values` |
|
|
175
175
|
| `select` | same as the column | `null` | `options`, `dependsOn`, `labelProp` |
|
|
176
176
|
|
|
@@ -181,7 +181,7 @@ A few things to know:
|
|
|
181
181
|
- An empty number or date gives `null`, not `0` or `NaN`. A select with nothing picked gives `null` too.
|
|
182
182
|
- 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
183
|
- A `string | null` column gets the same editors as a `string` column. `null` shows as an empty input.
|
|
184
|
-
- Date columns
|
|
184
|
+
- Date columns hold `'YYYY-MM-DD'` unless you give a `format`. See [Dates](#dates).
|
|
185
185
|
|
|
186
186
|
#### Checkboxes with your own values
|
|
187
187
|
|
|
@@ -229,6 +229,38 @@ import { defaultMoneyFormat, formatMoney } from 'tadabut';
|
|
|
229
229
|
{ prop: 'bonus', title: 'Bonus', render: (value) => formatMoney(value, defaultMoneyFormat) }
|
|
230
230
|
```
|
|
231
231
|
|
|
232
|
+
#### Dates
|
|
233
|
+
|
|
234
|
+
`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`:
|
|
235
|
+
|
|
236
|
+
```ts
|
|
237
|
+
{
|
|
238
|
+
prop: 'hiredAt',
|
|
239
|
+
title: 'Hired',
|
|
240
|
+
editor: { type: 'date', format: 'dd/mm/yyyy', min: '01/01/2000' },
|
|
241
|
+
}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
- `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'`.
|
|
245
|
+
- `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'`.
|
|
246
|
+
- 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'`.
|
|
247
|
+
- `min` and `max` are written in `format` too. Tadabut throws an error if they aren't real dates in that format.
|
|
248
|
+
- Sorting uses the real date, whatever the format. `'12/01/2023'` comes before `'05/01/2024'`.
|
|
249
|
+
- A time after the date is dropped: `'2024-01-05T10:30:00'` shows the 5th, and saves as `'2024-01-05'`.
|
|
250
|
+
- 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`.
|
|
251
|
+
- 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.
|
|
252
|
+
|
|
253
|
+
`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:
|
|
254
|
+
|
|
255
|
+
```ts
|
|
256
|
+
import { formatDate, parseDate } from 'tadabut';
|
|
257
|
+
|
|
258
|
+
parseDate('05/01/2024', 'dd/mm/yyyy'); // '2024-01-05'
|
|
259
|
+
formatDate('2024-01-05', 'dd.mm.yyyy'); // '05.01.2024'
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
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.
|
|
263
|
+
|
|
232
264
|
### What cells show
|
|
233
265
|
|
|
234
266
|
When a row isn't being edited, a cell shows its value as text. These change that:
|
|
@@ -236,6 +268,7 @@ When a row isn't being edited, a cell shows its value as text. These change that
|
|
|
236
268
|
- A select with a fixed list shows the option's label. A `countryId` of `1` shows "Morocco", with nothing to write.
|
|
237
269
|
- A select with `labelProp` shows that field of the row, like `cityName`. See [Chained selects](#chained-selects).
|
|
238
270
|
- A `money` editor shows its format, like `12 500.00`.
|
|
271
|
+
- A `date` editor shows its `display`, like `05/01/2024`.
|
|
239
272
|
- `render` sets the text yourself, on any column:
|
|
240
273
|
|
|
241
274
|
```ts
|
|
@@ -244,9 +277,9 @@ When a row isn't being edited, a cell shows its value as text. These change that
|
|
|
244
277
|
|
|
245
278
|
A few things to know:
|
|
246
279
|
|
|
247
|
-
- The order is: `render`, then the money format, then `labelProp`, then the fixed list's label, then the value itself.
|
|
280
|
+
- The order is: `render`, then the money or date format, then `labelProp`, then the fixed list's label, then the value itself.
|
|
248
281
|
- 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.
|
|
282
|
+
- 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 are the exception: they sort by the real date. A city column sorts by id, not by name.
|
|
250
283
|
- An empty value (`null` or `undefined`) shows an empty cell. On a nullable column, `render` gets `null` too.
|
|
251
284
|
- Editors always get the raw value. After saving or cancelling, the text is worked out again.
|
|
252
285
|
|
|
@@ -378,23 +411,24 @@ texts: { ...fr, save: 'Valider' }
|
|
|
378
411
|
texts: { edit: 'Bearbeiten', save: 'Speichern', cancel: 'Abbrechen' }
|
|
379
412
|
```
|
|
380
413
|
|
|
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
|
-
| `
|
|
393
|
-
| `
|
|
394
|
-
| `
|
|
395
|
-
| `
|
|
396
|
-
| `
|
|
397
|
-
| `
|
|
414
|
+
| Key | English |
|
|
415
|
+
| ------------------------ | -------------------------------------------------------------------- |
|
|
416
|
+
| `edit`, `save`, `cancel` | Edit, Save, Cancel |
|
|
417
|
+
| `delete` | Delete |
|
|
418
|
+
| `deleteQuestion` | Delete this row? |
|
|
419
|
+
| `confirm`, `keep` | Yes, delete / No |
|
|
420
|
+
| `loading` | Loading… |
|
|
421
|
+
| `saveFailed` | Could not save. |
|
|
422
|
+
| `addFailed` | Could not add. |
|
|
423
|
+
| `deleteFailed` | Could not delete. |
|
|
424
|
+
| `total` | Total |
|
|
425
|
+
| `selectRow`, `selectAll` | Select row / Select all (the checkboxes' labels, for screen readers) |
|
|
426
|
+
| `loadFailed` | Could not load the options. |
|
|
427
|
+
| `required` | This field is required. |
|
|
428
|
+
| `patternMismatch` | Wrong format. |
|
|
429
|
+
| `tooShort`, `tooLong` | Must be at least 2 characters. |
|
|
430
|
+
| `tooSmall`, `tooLarge` | Must be 18 or more. |
|
|
431
|
+
| `tooEarly`, `tooLate` | Must be on or after 2020-01-01. |
|
|
398
432
|
|
|
399
433
|
The messages with a number or a date are functions, so you can put the value where your language needs it:
|
|
400
434
|
|
|
@@ -440,6 +474,10 @@ Tadabut doesn't ship any CSS. Everything it creates gets these classes, so you c
|
|
|
440
474
|
| `tdb-delete-question` | the "Delete this row?" text |
|
|
441
475
|
| `tdb-button-confirm` | the "Yes, delete" button |
|
|
442
476
|
| `tdb-button-keep` | the "No" button |
|
|
477
|
+
| `tdb-select` | the checkbox column, header too |
|
|
478
|
+
| `tdb-select-row` | a row's checkbox |
|
|
479
|
+
| `tdb-select-all` | the "check all" checkbox |
|
|
480
|
+
| `tdb-row-selected` | a selected row |
|
|
443
481
|
|
|
444
482
|
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
483
|
|
|
@@ -476,6 +514,7 @@ const table = new Tadabut(container, {
|
|
|
476
514
|
| `delete` | the Delete button only |
|
|
477
515
|
| `confirm` | the "Yes, delete" button only |
|
|
478
516
|
| `keep` | the "No" button only |
|
|
517
|
+
| `select` | the selection checkboxes |
|
|
479
518
|
|
|
480
519
|
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
520
|
|
|
@@ -887,6 +926,89 @@ confirmDelete: async (row) => {
|
|
|
887
926
|
|
|
888
927
|
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
928
|
|
|
929
|
+
### Selecting rows
|
|
930
|
+
|
|
931
|
+
Turn on `selection`, and the table gets a checkbox column at the start, with a "check all" box in the header:
|
|
932
|
+
|
|
933
|
+
```ts
|
|
934
|
+
const table = new Tadabut(container, {
|
|
935
|
+
data: employees,
|
|
936
|
+
rowId: 'id',
|
|
937
|
+
columns,
|
|
938
|
+
selection: true,
|
|
939
|
+
onSelect: (rows) => console.log(`${rows.length} selected`),
|
|
940
|
+
});
|
|
941
|
+
|
|
942
|
+
table.getSelected(); // the selected rows
|
|
943
|
+
```
|
|
944
|
+
|
|
945
|
+
- Ticks are kept by row id, so they stay when you change page, sort or search.
|
|
946
|
+
- `onSelect` gets every selected row each time the selection changes, from a click or from code.
|
|
947
|
+
- The header box is ticked when every row it takes is selected, and shows a dash when only some are.
|
|
948
|
+
- A selected row gets the `tdb-row-selected` class. Tadabut doesn't color it: that's your CSS.
|
|
949
|
+
- Rows that leave the table, after a delete or `setData`, are unselected.
|
|
950
|
+
- The new row `add()` opens has no checkbox until it's saved.
|
|
951
|
+
- `selection` needs a `rowId`, and Tadabut throws an error without one.
|
|
952
|
+
|
|
953
|
+
**Which rows "check all" takes,** with `checkAll`:
|
|
954
|
+
|
|
955
|
+
```ts
|
|
956
|
+
selection: { checkAll: 'page' },
|
|
957
|
+
```
|
|
958
|
+
|
|
959
|
+
| `checkAll` | Takes |
|
|
960
|
+
| ---------------------- | ------------------------------------------------ |
|
|
961
|
+
| `'searched'` (default) | every row that matches the search, on every page |
|
|
962
|
+
| `'all'` | every row, whatever the search |
|
|
963
|
+
| `'page'` | only the rows on the page shown |
|
|
964
|
+
|
|
965
|
+
Rows you ticked that "check all" doesn't take stay ticked: unticking it only unselects the rows it takes.
|
|
966
|
+
|
|
967
|
+
Your `order` in `dataTables` still counts your own columns: `[[0, 'asc']]` is your first column, not the checkboxes.
|
|
968
|
+
|
|
969
|
+
### Events
|
|
970
|
+
|
|
971
|
+
Six callbacks tell you what happened. Each one gets the row:
|
|
972
|
+
|
|
973
|
+
| Option | When | Gets |
|
|
974
|
+
| ------------------ | -------------------------------------- | --------------------- |
|
|
975
|
+
| `onEditStart` | a row opens for editing | `(row)` |
|
|
976
|
+
| `onSaved` | after a save worked and the row closed | `(row, { previous })` |
|
|
977
|
+
| `onAdded` | after a new row joined the table | `(row)` |
|
|
978
|
+
| `onDeleted` | after a row left the table | `(row)` |
|
|
979
|
+
| `onRowClick` | a row is clicked | `(row, event)` |
|
|
980
|
+
| `onRowDoubleClick` | a row is double-clicked | `(row, event)` |
|
|
981
|
+
|
|
982
|
+
```ts
|
|
983
|
+
const table = new Tadabut(container, {
|
|
984
|
+
data: employees,
|
|
985
|
+
rowId: 'id',
|
|
986
|
+
columns,
|
|
987
|
+
onSave: saveEmployee,
|
|
988
|
+
onEditStart: (row) => row.status !== 'validated', // false keeps the row closed
|
|
989
|
+
onSaved: (row, { previous }) => toast(`${previous.name} saved`),
|
|
990
|
+
onRowClick: (row) => showDetails(row),
|
|
991
|
+
});
|
|
992
|
+
```
|
|
993
|
+
|
|
994
|
+
- `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.
|
|
995
|
+
- They're called the same way from the buttons and from code: `table.edit(1)` calls `onEditStart`, and `await table.save(1)` calls `onSaved`.
|
|
996
|
+
- `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.
|
|
997
|
+
- `onSaved` gets the row as it now is in the table (what `onSave` returned, if anything), and the row before editing.
|
|
998
|
+
- 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.
|
|
999
|
+
|
|
1000
|
+
**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.
|
|
1001
|
+
|
|
1002
|
+
**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.
|
|
1003
|
+
|
|
1004
|
+
**Double click to edit:**
|
|
1005
|
+
|
|
1006
|
+
```ts
|
|
1007
|
+
editing: { doubleClick: true },
|
|
1008
|
+
```
|
|
1009
|
+
|
|
1010
|
+
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.
|
|
1011
|
+
|
|
890
1012
|
### Editing options
|
|
891
1013
|
|
|
892
1014
|
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 +1024,15 @@ const table = new Tadabut(container, {
|
|
|
902
1024
|
editing: {
|
|
903
1025
|
mode: 'multiple', // default: 'single'
|
|
904
1026
|
button: false, // default: true. false hides the edit button
|
|
1027
|
+
doubleClick: true, // default: false. true opens a row on double click
|
|
905
1028
|
},
|
|
906
1029
|
});
|
|
907
1030
|
```
|
|
908
1031
|
|
|
909
1032
|
- `'single'` mode: one row at a time. You can't start a new edit while another row is open.
|
|
910
1033
|
- `'multiple'` mode: several rows can be open. Each one saves on its own, so `onSave` runs once per row.
|
|
911
|
-
- `
|
|
1034
|
+
- `doubleClick: true`: double-clicking a row opens it. See [Events](#events).
|
|
1035
|
+
- `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
1036
|
|
|
913
1037
|
### Controlling it from code
|
|
914
1038
|
|
|
@@ -924,11 +1048,17 @@ await table.saveNew(); // validate it and call onAdd
|
|
|
924
1048
|
table.cancelNew(); // throw the new row away
|
|
925
1049
|
table.isAdding(); // true while the new row is open
|
|
926
1050
|
|
|
1051
|
+
table.select([1, 2]); // tick rows 1 and 2
|
|
1052
|
+
table.deselect([2]); // untick row 2
|
|
1053
|
+
table.clearSelection(); // untick every row
|
|
1054
|
+
table.isSelected(1); // true while row 1 is ticked
|
|
1055
|
+
table.getSelected(); // the ticked rows
|
|
1056
|
+
|
|
927
1057
|
table.setData(newEmployees); // replace all rows, keeps sorting and search
|
|
928
1058
|
table.destroy(); // remove everything Tadabut created
|
|
929
1059
|
```
|
|
930
1060
|
|
|
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.
|
|
1061
|
+
`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
1062
|
|
|
933
1063
|
`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
1064
|
|
|
@@ -938,6 +1068,8 @@ table.destroy(); // remove everything Tadabut created
|
|
|
938
1068
|
|
|
939
1069
|
`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
1070
|
|
|
1071
|
+
`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 `[]`.
|
|
1072
|
+
|
|
941
1073
|
`setData` and `destroy` cancel any row being edited, and the new row, first. Unsaved changes are lost.
|
|
942
1074
|
|
|
943
1075
|
<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.
|
|
@@ -1041,11 +1173,12 @@ export default function Employees() {
|
|
|
1041
1173
|
```
|
|
1042
1174
|
|
|
1043
1175
|
- When `employees` changes, the table updates in place. It doesn't get rebuilt.
|
|
1044
|
-
- `onSave`, `onAdd`, `onDelete
|
|
1176
|
+
- `onSave`, `onAdd`, `onDelete`, `confirmDelete`, `onSelect` and the [events](#events) can be new functions on every render. The table always calls the latest ones.
|
|
1045
1177
|
- 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
1178
|
- `totalRows` is a plain string, so writing it inline is fine. Changing it rebuilds the table, to count other rows.
|
|
1047
|
-
- `
|
|
1048
|
-
-
|
|
1179
|
+
- `selection={{ checkAll: 'page' }}` inline is fine too: only turning it on or off, or changing `checkAll`, rebuilds the table. A rebuild clears the selection.
|
|
1180
|
+
- `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.
|
|
1181
|
+
- The ref has the same methods as the core: `edit`, `save`, `cancel`, `delete`, `isEditing`, `add`, `saveNew`, `cancelNew`, `isAdding`, `getSelected`, `isSelected`, `select`, `deselect` and `clearSelection`. Before the table is built, or after it's gone, the methods that return something give `false` (`[]` for `getSelected`), and the others do nothing.
|
|
1049
1182
|
- There is no `setData` on the ref. To change the rows, change `data`.
|
|
1050
1183
|
|
|
1051
1184
|
## Roadmap
|
|
@@ -1071,12 +1204,12 @@ Done:
|
|
|
1071
1204
|
- [x] Checkboxes with your own values, like `'O'` and `'N'` instead of `true` and `false`
|
|
1072
1205
|
- [x] Money inputs, formatted while typing (`12 500.00`)
|
|
1073
1206
|
- [x] Totals in the footer: sum, average, min, max, count or your own
|
|
1207
|
+
- [x] A checkbox column to select rows, with "check all"
|
|
1208
|
+
- [x] More events: when editing starts (and stopping it), after saving, adding and deleting, row click and double click, and double click to edit
|
|
1209
|
+
- [x] Dates in any format (`dd/mm/yyyy`…), in the data and the cells, and sorting by the real date
|
|
1074
1210
|
|
|
1075
1211
|
Next, roughly in this order:
|
|
1076
1212
|
|
|
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
1213
|
- [ ] Detail rows that open under a row
|
|
1081
1214
|
- [ ] Time and read-only inputs
|
|
1082
1215
|
- [ ] Methods to read rows (`getData`, `getRow`), put a row in directly without opening it, and reach the DataTables API
|
|
@@ -78,21 +78,56 @@ type CustomEditor<Value> = BaseEditor & {
|
|
|
78
78
|
/** Builds your editor. Runs every time a row opens. */
|
|
79
79
|
readonly create: (context: EditorContext<Value>) => EditorInstance<Value>;
|
|
80
80
|
};
|
|
81
|
+
/** The separators a date format can use. */
|
|
82
|
+
type DateSeparator = "/" | "-" | ".";
|
|
81
83
|
/**
|
|
82
|
-
*
|
|
83
|
-
*
|
|
84
|
-
* `null`.
|
|
84
|
+
* How a date is written: `dd`, `mm` and `yyyy` in any order, with `/`, `-`
|
|
85
|
+
* or `.` between them.
|
|
85
86
|
*
|
|
86
87
|
* @example
|
|
87
|
-
*
|
|
88
|
+
* 'dd/mm/yyyy'
|
|
89
|
+
*/
|
|
90
|
+
type DateFormat = { [S in DateSeparator]: `dd${S}mm${S}yyyy` | `mm${S}dd${S}yyyy` | `yyyy${S}mm${S}dd` | `yyyy${S}dd${S}mm` | `dd${S}yyyy${S}mm` | `mm${S}yyyy${S}dd`; }[DateSeparator];
|
|
91
|
+
/** ISO, what `<input type="date">` and most servers use. */
|
|
92
|
+
declare const defaultDateFormat: DateFormat;
|
|
93
|
+
/**
|
|
94
|
+
* Reads a date written in `format`, and gives it as `'yyyy-mm-dd'`. A time
|
|
95
|
+
* after it is dropped. `null` if it isn't a real date, like `31/02/2024`.
|
|
96
|
+
*
|
|
97
|
+
* @example
|
|
98
|
+
* parseDate('05/01/2024', 'dd/mm/yyyy'); // '2024-01-05'
|
|
99
|
+
*/
|
|
100
|
+
declare function parseDate(value: string, format: DateFormat): string | null;
|
|
101
|
+
/**
|
|
102
|
+
* Writes a `'yyyy-mm-dd'` date in `format`. Only give it dates `parseDate`
|
|
103
|
+
* returned: it checks nothing.
|
|
104
|
+
*
|
|
105
|
+
* @example
|
|
106
|
+
* formatDate('2024-01-05', 'dd.mm.yyyy'); // '05.01.2024'
|
|
107
|
+
*/
|
|
108
|
+
declare function formatDate(iso: string, format: DateFormat): string;
|
|
109
|
+
/**
|
|
110
|
+
* For `string` columns holding a date written in `format`. A time after the
|
|
111
|
+
* date is dropped. Anything else shows as empty and saves as `null`. Empty
|
|
112
|
+
* gives `null`.
|
|
113
|
+
*
|
|
114
|
+
* @example
|
|
115
|
+
* { type: 'date', format: 'dd/mm/yyyy', min: '01/01/2020' }
|
|
88
116
|
*/
|
|
89
117
|
type DateEditor = BaseEditor & {
|
|
90
118
|
/** Picks this editor. */
|
|
91
119
|
readonly type: "date";
|
|
92
|
-
/** Earliest date,
|
|
120
|
+
/** Earliest date, written in `format`. */
|
|
93
121
|
readonly min?: string;
|
|
94
|
-
/** Latest date,
|
|
122
|
+
/** Latest date, written in `format`. */
|
|
95
123
|
readonly max?: string;
|
|
124
|
+
/**
|
|
125
|
+
* How the date is written in your rows: what the server sends and what
|
|
126
|
+
* `onSave` gets. Defaults to `'yyyy-mm-dd'`.
|
|
127
|
+
*/
|
|
128
|
+
readonly format?: DateFormat;
|
|
129
|
+
/** How the cell shows it. Defaults to `format`. */
|
|
130
|
+
readonly display?: DateFormat;
|
|
96
131
|
};
|
|
97
132
|
/** How a money input and its cells look. */
|
|
98
133
|
type MoneyFormat = {
|
|
@@ -172,6 +207,10 @@ type Texts = {
|
|
|
172
207
|
readonly deleteFailed: string;
|
|
173
208
|
/** In the footer's first cell, when that column has no total of its own. */
|
|
174
209
|
readonly total: string;
|
|
210
|
+
/** The label of each row's checkbox, for screen readers. */
|
|
211
|
+
readonly selectRow: string;
|
|
212
|
+
/** The label of the header checkbox. */
|
|
213
|
+
readonly selectAll: string;
|
|
175
214
|
/** Shown in a select while its options load. */
|
|
176
215
|
readonly loading: string;
|
|
177
216
|
/** Under a row when `onSave` throws something that isn't an `Error`. */
|
|
@@ -325,8 +364,6 @@ type TotalFunction<Row extends object> = (rows: readonly Row[]) => string;
|
|
|
325
364
|
* number columns. `count` and a function work everywhere.
|
|
326
365
|
*/
|
|
327
366
|
type TotalFor<Value, Row extends object> = [NonNullable<Value>] extends [number] ? NumberTotal | "count" | TotalFunction<Row> : "count" | TotalFunction<Row>;
|
|
328
|
-
/** Which rows the totals count. */
|
|
329
|
-
type TotalRows = "searched" | "all" | "page";
|
|
330
367
|
/**
|
|
331
368
|
* A table column. The `editor` has to fit the type of `prop`, so a number
|
|
332
369
|
* field can't get a text input. Columns without an editor are read-only.
|
|
@@ -374,6 +411,11 @@ type ColumnFor<Row extends object, Key extends keyof Row & string> = {
|
|
|
374
411
|
/** Classes for the cells (header too), not for the input. */
|
|
375
412
|
readonly className?: string;
|
|
376
413
|
};
|
|
414
|
+
/**
|
|
415
|
+
* Which rows something counts: every row matching the search (on every
|
|
416
|
+
* page), every row, or the rows on the page shown.
|
|
417
|
+
*/
|
|
418
|
+
type RowScope = "searched" | "all" | "page";
|
|
377
419
|
/** The second argument of `onSave`. */
|
|
378
420
|
type SaveContext<Row extends object> = {
|
|
379
421
|
/** The row as it was before editing. */
|
|
@@ -392,6 +434,11 @@ type EditingOptions = {
|
|
|
392
434
|
* shows if `onDelete` is set.
|
|
393
435
|
*/
|
|
394
436
|
readonly button?: boolean;
|
|
437
|
+
/**
|
|
438
|
+
* Double-clicking a row opens it for editing. Defaults to `false`.
|
|
439
|
+
* `onRowDoubleClick` still fires.
|
|
440
|
+
*/
|
|
441
|
+
readonly doubleClick?: boolean;
|
|
395
442
|
};
|
|
396
443
|
/**
|
|
397
444
|
* Extra CSS classes for the table and its buttons. They're added next to the
|
|
@@ -408,6 +455,7 @@ type EditingOptions = {
|
|
|
408
455
|
* delete: 'btn-outline-danger',
|
|
409
456
|
* confirm: 'btn-danger',
|
|
410
457
|
* keep: 'btn-outline-secondary',
|
|
458
|
+
* select: 'form-check-input',
|
|
411
459
|
* }
|
|
412
460
|
*/
|
|
413
461
|
type TableClassNames = {
|
|
@@ -427,6 +475,8 @@ type TableClassNames = {
|
|
|
427
475
|
readonly confirm?: string;
|
|
428
476
|
/** The button that keeps the row instead. */
|
|
429
477
|
readonly keep?: string;
|
|
478
|
+
/** The selection checkboxes, header included. */
|
|
479
|
+
readonly select?: string;
|
|
430
480
|
};
|
|
431
481
|
/**
|
|
432
482
|
* Any {@link https://datatables.net/reference/option/ | DataTables option},
|
|
@@ -438,6 +488,14 @@ type TableClassNames = {
|
|
|
438
488
|
* { order: [[1, 'asc']], pageLength: 20, language: { search: 'Rechercher :' } }
|
|
439
489
|
*/
|
|
440
490
|
type DataTablesSettings = Omit<Config, "data" | "columns" | "columnDefs" | "ajax" | "serverSide">;
|
|
491
|
+
/** Options for `selection`. */
|
|
492
|
+
type SelectionOptions = {
|
|
493
|
+
/**
|
|
494
|
+
* Which rows the header checkbox selects. Defaults to `'searched'`: every
|
|
495
|
+
* row that matches the search, on every page.
|
|
496
|
+
*/
|
|
497
|
+
readonly checkAll?: RowScope;
|
|
498
|
+
};
|
|
441
499
|
/** Options for `new Tadabut()`. */
|
|
442
500
|
type TadabutOptions<Row extends object> = {
|
|
443
501
|
/** The rows. The array is copied, never changed. */
|
|
@@ -469,7 +527,20 @@ type TadabutOptions<Row extends object> = {
|
|
|
469
527
|
*
|
|
470
528
|
* Does nothing unless a column has `total`.
|
|
471
529
|
*/
|
|
472
|
-
readonly totalRows?:
|
|
530
|
+
readonly totalRows?: RowScope;
|
|
531
|
+
/**
|
|
532
|
+
* Adds a first column with a checkbox on each row, and one in the header to
|
|
533
|
+
* check them all. `true` uses the defaults. Needs `rowId`.
|
|
534
|
+
*
|
|
535
|
+
* @example
|
|
536
|
+
* selection: { checkAll: 'page' }
|
|
537
|
+
*/
|
|
538
|
+
readonly selection?: boolean | SelectionOptions;
|
|
539
|
+
/**
|
|
540
|
+
* Called with the selected rows each time the selection changes, by a
|
|
541
|
+
* click or from code.
|
|
542
|
+
*/
|
|
543
|
+
readonly onSelect?: (rows: readonly Row[]) => void;
|
|
473
544
|
/**
|
|
474
545
|
* Called with the edited row once it passes validation. May be async.
|
|
475
546
|
*
|
|
@@ -515,6 +586,37 @@ type TadabutOptions<Row extends object> = {
|
|
|
515
586
|
* confirmDelete: (row) => window.confirm(`Delete ${row.name}?`)
|
|
516
587
|
*/
|
|
517
588
|
readonly confirmDelete?: false | ((row: Row) => boolean | Promise<boolean>);
|
|
589
|
+
/**
|
|
590
|
+
* Called when a row opens for editing: by the Edit button, a double click,
|
|
591
|
+
* or `edit()`. Return `false` to keep it closed; `edit()` then returns
|
|
592
|
+
* `false`. Not called for the new row `add()` opens.
|
|
593
|
+
*
|
|
594
|
+
* @example
|
|
595
|
+
* onEditStart: (row) => row.status !== 'validated'
|
|
596
|
+
*/
|
|
597
|
+
readonly onEditStart?: (row: Row) => boolean | void;
|
|
598
|
+
/**
|
|
599
|
+
* Called after a save worked and the row closed, with the row as it is now
|
|
600
|
+
* in the table (what `onSave` returned, if anything) and the row before
|
|
601
|
+
* editing.
|
|
602
|
+
*/
|
|
603
|
+
readonly onSaved?: (row: Row, context: SaveContext<Row>) => void;
|
|
604
|
+
/** Called after a new row joined the table, with the row as saved. */
|
|
605
|
+
readonly onAdded?: (row: Row) => void;
|
|
606
|
+
/** Called after a row left the table, with that row. */
|
|
607
|
+
readonly onDeleted?: (row: Row) => void;
|
|
608
|
+
/**
|
|
609
|
+
* Called when a row is clicked. Clicks on buttons, inputs and checkboxes
|
|
610
|
+
* don't count, and neither do clicks in a row being edited, the new row,
|
|
611
|
+
* or an error line.
|
|
612
|
+
*/
|
|
613
|
+
readonly onRowClick?: (row: Row, event: MouseEvent) => void;
|
|
614
|
+
/**
|
|
615
|
+
* Called when a row is double-clicked, with the same rules as
|
|
616
|
+
* `onRowClick`. The browser fires two clicks first, so `onRowClick` runs
|
|
617
|
+
* twice before it.
|
|
618
|
+
*/
|
|
619
|
+
readonly onRowDoubleClick?: (row: Row, event: MouseEvent) => void;
|
|
518
620
|
};
|
|
519
621
|
/**
|
|
520
622
|
* A DataTables table with row editing.
|
|
@@ -537,7 +639,7 @@ declare class Tadabut<Row extends object> {
|
|
|
537
639
|
/** The `<table>` Tadabut created. */
|
|
538
640
|
private readonly tableEl;
|
|
539
641
|
/** The field that identifies a row. */
|
|
540
|
-
private readonly rowId
|
|
642
|
+
private readonly rowId?;
|
|
541
643
|
/** The user's columns, without the actions column. */
|
|
542
644
|
private readonly columns;
|
|
543
645
|
/** `editing` with its defaults filled in. */
|
|
@@ -563,19 +665,37 @@ declare class Tadabut<Row extends object> {
|
|
|
563
665
|
/** Rows waiting for `onDelete`, by row id. */
|
|
564
666
|
private readonly deleting;
|
|
565
667
|
/** The row `add()` opened, if any. */
|
|
566
|
-
private newRow
|
|
668
|
+
private newRow?;
|
|
567
669
|
/** Whether any column has a `total`, so the table has a footer. */
|
|
568
670
|
private readonly hasTotals;
|
|
569
671
|
/** Which rows the totals count, with its default filled in. */
|
|
570
672
|
private readonly totalRows;
|
|
673
|
+
/** How many columns Tadabut adds before yours: 1 with `selection`. */
|
|
674
|
+
private readonly offset;
|
|
675
|
+
/** The ticked rows. Only with `selection`. */
|
|
676
|
+
private readonly selection?;
|
|
677
|
+
/** Asked before a row opens. */
|
|
678
|
+
private readonly onEditStart;
|
|
679
|
+
/** The user's after-save callback. */
|
|
680
|
+
private readonly onSaved;
|
|
681
|
+
/** The user's after-add callback. */
|
|
682
|
+
private readonly onAdded;
|
|
683
|
+
/** The user's after-delete callback. */
|
|
684
|
+
private readonly onDeleted;
|
|
685
|
+
/** The user's row click callback. */
|
|
686
|
+
private readonly onRowClick;
|
|
687
|
+
/** The user's row double click callback. */
|
|
688
|
+
private readonly onRowDoubleClick;
|
|
571
689
|
/**
|
|
572
690
|
* Builds the table inside `container`, which should be empty.
|
|
573
691
|
*
|
|
574
692
|
* @throws If a column has an `editor` and there's no `rowId`.
|
|
575
693
|
* @throws If `onDelete` is set and there's no `rowId`.
|
|
694
|
+
* @throws If `selection` is on and there's no `rowId`.
|
|
576
695
|
* @throws If a hidden column (`visible: false`) has an `editor`.
|
|
577
696
|
* @throws If a select's `labelProp` is its own column.
|
|
578
697
|
* @throws If a money editor's `separator` and `point` are the same.
|
|
698
|
+
* @throws If a date editor's `min` or `max` isn't a real date in its `format`.
|
|
579
699
|
*/
|
|
580
700
|
constructor(container: HTMLElement, options: TadabutOptions<Row>);
|
|
581
701
|
/**
|
|
@@ -591,7 +711,8 @@ declare class Tadabut<Row extends object> {
|
|
|
591
711
|
* @param id The value of the row's `rowId` field.
|
|
592
712
|
* @returns `false` if the row doesn't exist, is already open, another row
|
|
593
713
|
* or the new row is open in `'single'` mode, nothing is editable, the row
|
|
594
|
-
* is being deleted,
|
|
714
|
+
* is being deleted, it's on a page that hasn't been displayed yet, or
|
|
715
|
+
* `onEditStart` returned `false`.
|
|
595
716
|
*/
|
|
596
717
|
edit(id: string | number): boolean;
|
|
597
718
|
/**
|
|
@@ -607,6 +728,25 @@ declare class Tadabut<Row extends object> {
|
|
|
607
728
|
add(defaults?: Partial<Row>): boolean;
|
|
608
729
|
/** Whether a new row is open. */
|
|
609
730
|
isAdding(): boolean;
|
|
731
|
+
/**
|
|
732
|
+
* The selected rows, in the order they were added. Rows the search hides,
|
|
733
|
+
* or on other pages, are in it too. Always `[]` without `selection`.
|
|
734
|
+
*/
|
|
735
|
+
getSelected(): Row[];
|
|
736
|
+
/** Whether a row is selected. Always `false` without `selection`. */
|
|
737
|
+
isSelected(id: string | number): boolean;
|
|
738
|
+
/**
|
|
739
|
+
* Selects rows by id. Ids not in the table are skipped. Does nothing
|
|
740
|
+
* without `selection`.
|
|
741
|
+
*
|
|
742
|
+
* @example
|
|
743
|
+
* table.select([1, 2]);
|
|
744
|
+
*/
|
|
745
|
+
select(ids: readonly (string | number)[]): void;
|
|
746
|
+
/** Unselects rows by id. Does nothing without `selection`. */
|
|
747
|
+
deselect(ids: readonly (string | number)[]): void;
|
|
748
|
+
/** Unselects every row. Does nothing without `selection`. */
|
|
749
|
+
clearSelection(): void;
|
|
610
750
|
/**
|
|
611
751
|
* Closes the new row and throws it away. Does nothing if there's none, or
|
|
612
752
|
* while it's saving.
|
|
@@ -697,9 +837,22 @@ declare class Tadabut<Row extends object> {
|
|
|
697
837
|
* delete and `setData` all redraw.
|
|
698
838
|
*/
|
|
699
839
|
private readonly updateTotals;
|
|
840
|
+
/** Your column's index as DataTables counts it. */
|
|
841
|
+
private dtIndex;
|
|
842
|
+
/**
|
|
843
|
+
* The row a click landed on, or `undefined` if it doesn't count: buttons,
|
|
844
|
+
* inputs, links, the checkbox and buttons cells, the new row, a row being
|
|
845
|
+
* edited, the header, the footer and error lines.
|
|
846
|
+
*/
|
|
847
|
+
private clickedRow;
|
|
848
|
+
/**
|
|
849
|
+
* Row clicks and double clicks. A double click also opens the row with
|
|
850
|
+
* `editing.doubleClick`. An arrow function, so `destroy` can remove it.
|
|
851
|
+
*/
|
|
852
|
+
private readonly onRowEvent;
|
|
700
853
|
}
|
|
701
854
|
/** English, the default. */
|
|
702
855
|
declare const en: Texts;
|
|
703
856
|
/** French. */
|
|
704
857
|
declare const fr: Texts;
|
|
705
|
-
export {
|
|
858
|
+
export { parseDate as A, MoneyFormat as C, DateFormat as D, DateEditor as E, CheckboxEditor as M, EditorContext as N, defaultDateFormat as O, EditorInstance as P, MoneyEditor as S, formatMoney as T, SelectEditor as _, EditingOptions as a, Texts as b, TableClassNames as c, Column as d, TotalFunction as f, OptionsContext as g, TextEditor as h, DataTablesSettings as i, CustomEditor as j, formatDate as k, TadabutOptions as l, EditorFor as m, en as n, SaveContext as o, ValidationOptions as p, Tadabut as r, SelectionOptions as s, fr as t, RowScope as u, SelectOption as v, defaultMoneyFormat as w, NumberEditor as x, SelectOptionsLoader as y };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,2 +1,8 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* Editable, typed DataTables. The React component lives in `tadabut/react`.
|
|
3
|
+
*
|
|
4
|
+
* @packageDocumentation
|
|
5
|
+
* @module tadabut
|
|
6
|
+
*/
|
|
7
|
+
import { A as parseDate, C as MoneyFormat, D as DateFormat, E as DateEditor, M as CheckboxEditor, N as EditorContext, O as defaultDateFormat, P as EditorInstance, S as MoneyEditor, T as formatMoney, _ as SelectEditor, a as EditingOptions, b as Texts, c as TableClassNames, d as Column, f as TotalFunction, g as OptionsContext, h as TextEditor, i as DataTablesSettings, j as CustomEditor, k as formatDate, l as TadabutOptions, m as EditorFor, n as en, o as SaveContext, p as ValidationOptions, r as Tadabut, s as SelectionOptions, t as fr, u as RowScope, v as SelectOption, w as defaultMoneyFormat, x as NumberEditor, y as SelectOptionsLoader } from "./index-C_77p8Jv.js";
|
|
8
|
+
export { type CheckboxEditor, type Column, type CustomEditor, type DataTablesSettings, type DateEditor, type DateFormat, type EditingOptions, type EditorContext, type EditorFor, type EditorInstance, type MoneyEditor, type MoneyFormat, type NumberEditor, type OptionsContext, type RowScope, type SaveContext, type SelectEditor, type SelectOption, type SelectOptionsLoader, type SelectionOptions, type TableClassNames, Tadabut, type TadabutOptions, type TextEditor, type Texts, type TotalFunction, type ValidationOptions, defaultDateFormat, defaultMoneyFormat, en, formatDate, formatMoney, fr, parseDate };
|
package/dist/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export { n as Tadabut, i as defaultMoneyFormat, r as en, a as formatMoney, t as fr } from "./src-
|
|
1
|
+
export { n as Tadabut, o as defaultDateFormat, i as defaultMoneyFormat, r as en, s as formatDate, a as formatMoney, t as fr, c as parseDate } from "./src-BxdYoViF.js";
|