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 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 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.
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
- | `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. |
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
- - `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.
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` and `confirmDelete` can be new functions on every render. The table always calls the latest ones.
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
- - `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.
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
- * For `string` columns holding `'YYYY-MM-DD'`. Anything else, like
83
- * `'2024-01-05T00:00:00'`, shows as empty and saves as `null`. Empty gives
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
- * { type: 'date', min: '2020-01-01', max: '2030-12-31' }
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, as `'YYYY-MM-DD'`. */
120
+ /** Earliest date, written in `format`. */
93
121
  readonly min?: string;
94
- /** Latest date, as `'YYYY-MM-DD'`. */
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?: 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, or it's on a page that hasn't been displayed yet.
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 { defaultMoneyFormat as C, CheckboxEditor as D, CustomEditor as E, EditorContext as O, MoneyFormat as S, DateEditor as T, SelectOption as _, EditingOptions as a, NumberEditor as b, TadabutOptions as c, TotalRows as d, ValidationOptions as f, SelectEditor as g, OptionsContext as h, DataTablesSettings as i, EditorInstance as k, Column as l, TextEditor as m, en as n, SaveContext as o, EditorFor as p, Tadabut as r, TableClassNames as s, fr as t, TotalFunction as u, SelectOptionsLoader as v, formatMoney as w, MoneyEditor as x, Texts as y };
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
- import { C as defaultMoneyFormat, D as CheckboxEditor, E as CustomEditor, O as EditorContext, S as MoneyFormat, T as DateEditor, _ as SelectOption, a as EditingOptions, b as NumberEditor, c as TadabutOptions, d as TotalRows, f as ValidationOptions, g as SelectEditor, h as OptionsContext, i as DataTablesSettings, k as EditorInstance, l as Column, m as TextEditor, n as en, o as SaveContext, p as EditorFor, r as Tadabut, s as TableClassNames, t as fr, u as TotalFunction, v as SelectOptionsLoader, w as formatMoney, x as MoneyEditor, y as Texts } from "./index-KmSXRJlI.js";
2
- export { type CheckboxEditor, type Column, type CustomEditor, type DataTablesSettings, type DateEditor, type EditingOptions, type EditorContext, type EditorFor, type EditorInstance, type MoneyEditor, type MoneyFormat, type NumberEditor, type OptionsContext, type SaveContext, type SelectEditor, type SelectOption, type SelectOptionsLoader, type TableClassNames, Tadabut, type TadabutOptions, type TextEditor, type Texts, type TotalFunction, type TotalRows, type ValidationOptions, defaultMoneyFormat, en, formatMoney, fr };
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-CBK3xu9-.js";
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";