tadabut 0.0.0-stage → 0.2.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/LICENSE +21 -0
- package/README.md +671 -2
- package/dist/index-D2g9_Fd9.d.ts +603 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/dist/react.d.ts +39 -0
- package/dist/react.js +110 -0
- package/dist/src-C4vgw-1w.js +982 -0
- package/package.json +77 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Anas Youssef El Mahdad
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,672 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ⵜⴰⴷⴰⴱⵓⵜ · Tadabut
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://github.com/ayem1412/tadabut/actions/workflows/ci.yml)
|
|
4
|
+
[](./LICENSE)
|
|
5
|
+
[](https://www.typescriptlang.org/)
|
|
6
|
+
[](https://datatables.net)
|
|
7
|
+
[](#roadmap)
|
|
8
|
+
[](./CONTRIBUTING.md)
|
|
9
|
+
|
|
10
|
+
Tadabut wraps [DataTables](https://datatables.net) and adds what it doesn't give you for free: editing rows, real inputs in the cells, and selects that depend on each other.
|
|
11
|
+
|
|
12
|
+
> [!WARNING]
|
|
13
|
+
> Tadabut is new. Until 1.0, the API can change between `0.x` versions, so pin the version you use and read the changelog before you update.
|
|
14
|
+
|
|
15
|
+
## Why
|
|
16
|
+
|
|
17
|
+
DataTables is great for showing data. Editing that data inside the table is a different story: you either buy the Editor extension or write a lot of code yourself. Tadabut is that code, written once.
|
|
18
|
+
|
|
19
|
+
- Edit a row in place, then save or cancel. Saving can be async. If it fails, the row stays open with what the user typed, so nothing is lost.
|
|
20
|
+
- Text, number, date, checkbox and select inputs, with validation.
|
|
21
|
+
- Selects that depend on another field, like country and city. Old requests get cancelled when the user changes their mind.
|
|
22
|
+
- Fully typed. The table knows what your rows look like, so a typo in a column name is a type error.
|
|
23
|
+
- No jQuery. It's built on DataTables 3, which doesn't need it anymore.
|
|
24
|
+
|
|
25
|
+
## Framework support
|
|
26
|
+
|
|
27
|
+
The core has no framework in it. Each framework gets a small adapter on top.
|
|
28
|
+
|
|
29
|
+
| Target | Status |
|
|
30
|
+
| ---------- | --------- |
|
|
31
|
+
| TypeScript | Supported |
|
|
32
|
+
| JavaScript | Supported |
|
|
33
|
+
| React | Supported |
|
|
34
|
+
| Vue | Planned |
|
|
35
|
+
| jQuery | Planned |
|
|
36
|
+
|
|
37
|
+
## Requirements
|
|
38
|
+
|
|
39
|
+
- DataTables 3: `datatables.net`, or one of its styling packages like `datatables.net-dt`
|
|
40
|
+
- React 19, only if you use the React adapter
|
|
41
|
+
- A modern browser
|
|
42
|
+
|
|
43
|
+
## Installation
|
|
44
|
+
|
|
45
|
+
Install Tadabut with DataTables. `datatables.net-dt` is DataTables with its default look:
|
|
46
|
+
|
|
47
|
+
```sh
|
|
48
|
+
pnpm add tadabut datatables.net-dt
|
|
49
|
+
# or
|
|
50
|
+
npm install tadabut datatables.net-dt
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
For the React adapter, you also need React 19, which your app most likely has already.
|
|
54
|
+
|
|
55
|
+
Then import DataTables and its CSS once, before you create a table:
|
|
56
|
+
|
|
57
|
+
```ts
|
|
58
|
+
import 'datatables.net-dt';
|
|
59
|
+
import 'datatables.net-dt/css';
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Tadabut works with any DataTables 3 styling package: `datatables.net-bs5` for Bootstrap 5, and so on.
|
|
63
|
+
|
|
64
|
+
## Usage
|
|
65
|
+
|
|
66
|
+
### Create a table
|
|
67
|
+
|
|
68
|
+
Give Tadabut the type of your rows. Every column's `prop` is checked against it.
|
|
69
|
+
|
|
70
|
+
The examples on this page all use this `Employee` type.
|
|
71
|
+
|
|
72
|
+
```ts
|
|
73
|
+
import 'datatables.net-dt';
|
|
74
|
+
import 'datatables.net-dt/css';
|
|
75
|
+
import { Tadabut, type Column } from 'tadabut';
|
|
76
|
+
|
|
77
|
+
type Employee = {
|
|
78
|
+
id: number;
|
|
79
|
+
name: string;
|
|
80
|
+
age: number;
|
|
81
|
+
salary: number;
|
|
82
|
+
hiredAt: string; // 'YYYY-MM-DD'
|
|
83
|
+
active: boolean;
|
|
84
|
+
countryId: number | null;
|
|
85
|
+
countryCode: string | null;
|
|
86
|
+
cityId: number | null;
|
|
87
|
+
cityName: string;
|
|
88
|
+
};
|
|
89
|
+
|
|
90
|
+
const employees: Employee[] = [
|
|
91
|
+
{
|
|
92
|
+
id: 1,
|
|
93
|
+
name: 'Amina',
|
|
94
|
+
age: 29,
|
|
95
|
+
salary: 12000,
|
|
96
|
+
hiredAt: '2024-01-05',
|
|
97
|
+
active: true,
|
|
98
|
+
countryId: 1,
|
|
99
|
+
countryCode: 'MA',
|
|
100
|
+
cityId: 10,
|
|
101
|
+
cityName: 'Rabat',
|
|
102
|
+
},
|
|
103
|
+
];
|
|
104
|
+
|
|
105
|
+
const columns: Column<Employee>[] = [
|
|
106
|
+
{ prop: 'id', title: 'ID' },
|
|
107
|
+
{ prop: 'name', title: 'Name' },
|
|
108
|
+
{ prop: 'age', title: 'Age' },
|
|
109
|
+
];
|
|
110
|
+
|
|
111
|
+
const container = document.querySelector<HTMLElement>('#employees')!;
|
|
112
|
+
|
|
113
|
+
const table = new Tadabut(container, {
|
|
114
|
+
data: employees,
|
|
115
|
+
rowId: 'id',
|
|
116
|
+
columns,
|
|
117
|
+
});
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
- The first argument is an empty element. Tadabut builds the table inside it.
|
|
121
|
+
- `rowId` is the property that identifies a row. Methods like `edit(id)` use it.
|
|
122
|
+
- A column without an `editor` can't be edited.
|
|
123
|
+
|
|
124
|
+
### Editable columns
|
|
125
|
+
|
|
126
|
+
Add an `editor` to a column to make it editable. Its `type` picks the input, and the options you can use with it.
|
|
127
|
+
|
|
128
|
+
```ts
|
|
129
|
+
const columns: Column<Employee>[] = [
|
|
130
|
+
{ prop: 'id', title: 'ID' },
|
|
131
|
+
{ prop: 'name', title: 'Name', editor: { type: 'text' } },
|
|
132
|
+
{ prop: 'age', title: 'Age', editor: { type: 'number', step: 1 } },
|
|
133
|
+
{ prop: 'hiredAt', title: 'Hired', editor: { type: 'date' } },
|
|
134
|
+
{ prop: 'active', title: 'Active', editor: { type: 'checkbox' } },
|
|
135
|
+
{
|
|
136
|
+
prop: 'countryId',
|
|
137
|
+
title: 'Country',
|
|
138
|
+
editor: {
|
|
139
|
+
type: 'select',
|
|
140
|
+
options: [
|
|
141
|
+
{ value: 1, label: 'Morocco' },
|
|
142
|
+
{ value: 2, label: 'France' },
|
|
143
|
+
],
|
|
144
|
+
},
|
|
145
|
+
},
|
|
146
|
+
];
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
A select's values must have the same type as the column. `countryId` is a number, so `value: '1'` is a type error.
|
|
150
|
+
|
|
151
|
+
| Type | Value | When empty | Options |
|
|
152
|
+
| ---------- | ------------------ | ----------- | ----------------------------------- |
|
|
153
|
+
| `text` | `string` | `''` | `minLength`, `maxLength`, `pattern` |
|
|
154
|
+
| `number` | `number` | `null` | `min`, `max`, `step` |
|
|
155
|
+
| `date` | `string` | `null` | `min`, `max` |
|
|
156
|
+
| `checkbox` | `boolean` | never empty | none |
|
|
157
|
+
| `select` | same as the column | `null` | `options`, `dependsOn` |
|
|
158
|
+
|
|
159
|
+
Every editor also takes `className`, for your own CSS classes.
|
|
160
|
+
|
|
161
|
+
A few things to know:
|
|
162
|
+
|
|
163
|
+
- An empty number or date gives `null`, not `0` or `NaN`. A select with nothing picked gives `null` too.
|
|
164
|
+
- A checkbox is always `true` or `false`. A `null` value shows as unchecked.
|
|
165
|
+
- A `string | null` column gets the same editors as a `string` column. `null` shows as an empty input.
|
|
166
|
+
- 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.
|
|
167
|
+
|
|
168
|
+
### What cells show
|
|
169
|
+
|
|
170
|
+
When a row isn't being edited, a cell shows its value as text. Two things change that:
|
|
171
|
+
|
|
172
|
+
- A select with a fixed list shows the option's label. A `countryId` of `1` shows "Morocco", with nothing to write.
|
|
173
|
+
- `render` sets the text yourself, on any column:
|
|
174
|
+
|
|
175
|
+
```ts
|
|
176
|
+
{ prop: 'salary', title: 'Salary', render: (value) => `${value} MAD` }
|
|
177
|
+
|
|
178
|
+
// A select whose options come from a function: Tadabut can't know the
|
|
179
|
+
// label, but the row usually has it.
|
|
180
|
+
{ prop: 'cityId', title: 'City', render: (value, row) => row.cityName, editor: { … } }
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
A few things to know:
|
|
184
|
+
|
|
185
|
+
- `render` wins over a select's label.
|
|
186
|
+
- What `render` returns is shown as plain text, never as HTML. `<b>` shows as `<b>`, so text from a server can't break the page or run code.
|
|
187
|
+
- Searching uses the text. Sorting uses the raw value, so `200 MAD` comes before `1000 MAD`. A city column sorts by id, not by name.
|
|
188
|
+
- An empty value (`null` or `undefined`) shows an empty cell. On a nullable column, `render` gets `null` too.
|
|
189
|
+
- Editors always get the raw value. After saving or cancelling, the text is worked out again.
|
|
190
|
+
|
|
191
|
+
### Styling
|
|
192
|
+
|
|
193
|
+
Tadabut doesn't ship any CSS. Everything it creates gets these classes, so you can style it however you want:
|
|
194
|
+
|
|
195
|
+
| Class | Used on |
|
|
196
|
+
| ------------------------ | ------------------------------------------------- |
|
|
197
|
+
| `tdb-input` | every input |
|
|
198
|
+
| `tdb-input-text` | text inputs |
|
|
199
|
+
| `tdb-input-number` | number inputs |
|
|
200
|
+
| `tdb-input-date` | date inputs |
|
|
201
|
+
| `tdb-input-checkbox` | checkboxes |
|
|
202
|
+
| `tdb-input-select` | selects |
|
|
203
|
+
| `tdb-error` | a field's error message, under its input |
|
|
204
|
+
| `tdb-save-error` | the line (`<tr>`) under a row that failed to save |
|
|
205
|
+
| `tdb-save-error-message` | the message inside that line |
|
|
206
|
+
| `tdb-row-editing` | a row while it's being edited |
|
|
207
|
+
| `tdb-row-saving` | a row while it's being saved |
|
|
208
|
+
| `tdb-actions` | the column with the buttons, header too |
|
|
209
|
+
| `tdb-button` | every button |
|
|
210
|
+
| `tdb-button-edit` | the Edit button |
|
|
211
|
+
| `tdb-button-save` | the Save button |
|
|
212
|
+
| `tdb-button-cancel` | the Cancel button |
|
|
213
|
+
|
|
214
|
+
To use Bootstrap, Tailwind or anything else, add your own classes. They always go next to the `tdb-` ones, never instead of them. There are two places:
|
|
215
|
+
|
|
216
|
+
- `className` on an editor, for its input.
|
|
217
|
+
- `classNames` on the table, for the `<table>` and the buttons.
|
|
218
|
+
|
|
219
|
+
```ts
|
|
220
|
+
const table = new Tadabut(container, {
|
|
221
|
+
data: employees,
|
|
222
|
+
rowId: 'id',
|
|
223
|
+
columns: [
|
|
224
|
+
{ prop: 'id', title: 'ID' },
|
|
225
|
+
{
|
|
226
|
+
prop: 'name',
|
|
227
|
+
title: 'Name',
|
|
228
|
+
editor: { type: 'text', className: 'w-full rounded border px-2 py-1' },
|
|
229
|
+
},
|
|
230
|
+
],
|
|
231
|
+
classNames: {
|
|
232
|
+
table: 'w-full text-sm',
|
|
233
|
+
button: 'rounded px-2 py-1',
|
|
234
|
+
save: 'bg-blue-600 text-white',
|
|
235
|
+
},
|
|
236
|
+
});
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
| `classNames` key | Added to |
|
|
240
|
+
| ---------------- | --------------------------------- |
|
|
241
|
+
| `table` | the `<table>` |
|
|
242
|
+
| `button` | the Edit, Save and Cancel buttons |
|
|
243
|
+
| `edit` | the Edit button only |
|
|
244
|
+
| `save` | the Save button only |
|
|
245
|
+
| `cancel` | the Cancel button only |
|
|
246
|
+
|
|
247
|
+
All of them are optional. Tadabut doesn't know any CSS framework: it adds the classes you give it, and nothing else. If you use Tailwind: it only keeps classes it finds in your own files. Classes in your column config count, so they work.
|
|
248
|
+
|
|
249
|
+
DataTables' own parts (the search box, the page size, the paging buttons) are styled by the DataTables package you install: `datatables.net-dt` for the default look, `datatables.net-bs5` for Bootstrap 5, and so on.
|
|
250
|
+
|
|
251
|
+
#### With Bootstrap 5
|
|
252
|
+
|
|
253
|
+
Install the Bootstrap version of DataTables instead of `datatables.net-dt`, and Bootstrap itself:
|
|
254
|
+
|
|
255
|
+
```sh
|
|
256
|
+
pnpm add tadabut datatables.net-bs5 bootstrap
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
Import them once:
|
|
260
|
+
|
|
261
|
+
```ts
|
|
262
|
+
import 'bootstrap/dist/css/bootstrap.min.css';
|
|
263
|
+
import 'datatables.net-bs5';
|
|
264
|
+
import 'datatables.net-bs5/css';
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Then give the editors and the table Bootstrap's classes:
|
|
268
|
+
|
|
269
|
+
```ts
|
|
270
|
+
const columns: Column<Employee>[] = [
|
|
271
|
+
{ prop: 'id', title: 'ID' },
|
|
272
|
+
{
|
|
273
|
+
prop: 'name',
|
|
274
|
+
title: 'Name',
|
|
275
|
+
editor: { type: 'text', className: 'form-control form-control-sm' },
|
|
276
|
+
},
|
|
277
|
+
{
|
|
278
|
+
prop: 'countryId',
|
|
279
|
+
title: 'Country',
|
|
280
|
+
editor: {
|
|
281
|
+
type: 'select',
|
|
282
|
+
className: 'form-select form-select-sm',
|
|
283
|
+
options: [
|
|
284
|
+
{ value: 1, label: 'Morocco' },
|
|
285
|
+
{ value: 2, label: 'France' },
|
|
286
|
+
],
|
|
287
|
+
},
|
|
288
|
+
},
|
|
289
|
+
{ prop: 'active', title: 'Active', editor: { type: 'checkbox', className: 'form-check-input' } },
|
|
290
|
+
];
|
|
291
|
+
|
|
292
|
+
const table = new Tadabut(container, {
|
|
293
|
+
data: employees,
|
|
294
|
+
rowId: 'id',
|
|
295
|
+
columns,
|
|
296
|
+
classNames: {
|
|
297
|
+
table: 'table table-striped table-hover align-middle',
|
|
298
|
+
button: 'btn btn-sm',
|
|
299
|
+
edit: 'btn-outline-primary',
|
|
300
|
+
save: 'btn-primary',
|
|
301
|
+
cancel: 'btn-outline-secondary',
|
|
302
|
+
},
|
|
303
|
+
});
|
|
304
|
+
```
|
|
305
|
+
|
|
306
|
+
Error messages and the rows being edited need a few lines of your own CSS:
|
|
307
|
+
|
|
308
|
+
```css
|
|
309
|
+
/* Errors in Bootstrap's red. Use the message's class, not the row's:
|
|
310
|
+
Bootstrap sets a color on every table cell. */
|
|
311
|
+
.tdb-error,
|
|
312
|
+
.tdb-save-error-message {
|
|
313
|
+
color: var(--bs-form-invalid-color);
|
|
314
|
+
font-size: 0.875em;
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
/* While editing, line the inputs up at the top, so an error under one
|
|
318
|
+
input doesn't move the others. */
|
|
319
|
+
.table > tbody > tr.tdb-row-editing > td {
|
|
320
|
+
vertical-align: top;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
.tdb-row-saving {
|
|
324
|
+
opacity: 0.5;
|
|
325
|
+
}
|
|
326
|
+
```
|
|
327
|
+
|
|
328
|
+
> [!TIP]
|
|
329
|
+
> Each DataTables styling package needs one exact version of `datatables.net`. Don't add `datatables.net` yourself next to it. If you have to, use the same version as the styling package. Two different versions means two copies of DataTables: the table works, but the Bootstrap look doesn't show up on the search box and the paging buttons.
|
|
330
|
+
|
|
331
|
+
### Custom editors
|
|
332
|
+
|
|
333
|
+
If the built-in inputs aren't enough, write your own. Select2, a date picker library, an input for a column that holds an object: anything works, on any column.
|
|
334
|
+
|
|
335
|
+
`create` runs every time a row starts being edited. It gets the starting value, the `className`, and an `onChange` function. It returns the editor.
|
|
336
|
+
|
|
337
|
+
Here is Select2:
|
|
338
|
+
|
|
339
|
+
```ts
|
|
340
|
+
import $ from 'jquery';
|
|
341
|
+
import 'select2';
|
|
342
|
+
|
|
343
|
+
const countryColumn: Column<Employee> = {
|
|
344
|
+
prop: 'countryCode', // string | null
|
|
345
|
+
title: 'Country',
|
|
346
|
+
editor: {
|
|
347
|
+
type: 'custom',
|
|
348
|
+
create: (context) => {
|
|
349
|
+
// Select2 adds its own elements next to the <select>,
|
|
350
|
+
// so wrap it: the wrapper is what goes in the cell.
|
|
351
|
+
const wrapper = document.createElement('div');
|
|
352
|
+
const select = document.createElement('select');
|
|
353
|
+
wrapper.appendChild(select);
|
|
354
|
+
|
|
355
|
+
const $select = $(select).select2({
|
|
356
|
+
width: '100%',
|
|
357
|
+
data: [
|
|
358
|
+
{ id: 'MA', text: 'Morocco' },
|
|
359
|
+
{ id: 'FR', text: 'France' },
|
|
360
|
+
],
|
|
361
|
+
});
|
|
362
|
+
|
|
363
|
+
// Nothing picked gives null, not the text 'null'.
|
|
364
|
+
const read = () => ($select.val() as string | null) ?? null;
|
|
365
|
+
|
|
366
|
+
$select.val(context.value).trigger('change.select2');
|
|
367
|
+
|
|
368
|
+
// The user picked something: tell Tadabut.
|
|
369
|
+
$select.on('select2:select', () => context.onChange(read()));
|
|
370
|
+
|
|
371
|
+
return {
|
|
372
|
+
element: wrapper,
|
|
373
|
+
getValue: read,
|
|
374
|
+
// Update Select2's display only. This does not call onChange.
|
|
375
|
+
setValue: (value) => $select.val(value).trigger('change.select2'),
|
|
376
|
+
focus: () => $select.select2('open'),
|
|
377
|
+
destroy: () => {
|
|
378
|
+
$select.select2('destroy');
|
|
379
|
+
wrapper.remove();
|
|
380
|
+
},
|
|
381
|
+
};
|
|
382
|
+
},
|
|
383
|
+
},
|
|
384
|
+
};
|
|
385
|
+
```
|
|
386
|
+
|
|
387
|
+
Rules for any custom editor:
|
|
388
|
+
|
|
389
|
+
- Call `context.onChange` when the user changes the value. Only then.
|
|
390
|
+
- `setValue` changes what's shown, without calling `onChange`.
|
|
391
|
+
- `destroy` cleans up everything, including the widget's own cleanup, then removes the element.
|
|
392
|
+
- On a nullable column, `context.value` can be `null`.
|
|
393
|
+
|
|
394
|
+
Select2 needs jQuery. Tadabut doesn't, so install jQuery yourself if you use Select2.
|
|
395
|
+
|
|
396
|
+
### Validation
|
|
397
|
+
|
|
398
|
+
`required` works on every editor. For anything the built-in rules don't cover, `validate` returns an error message, or `undefined` if the value is fine. It also gets the whole row.
|
|
399
|
+
|
|
400
|
+
```ts
|
|
401
|
+
{
|
|
402
|
+
prop: 'age',
|
|
403
|
+
title: 'Age',
|
|
404
|
+
editor: {
|
|
405
|
+
type: 'number',
|
|
406
|
+
required: true,
|
|
407
|
+
min: 18,
|
|
408
|
+
validate: (value, row) =>
|
|
409
|
+
row.active && value !== null && value > 65
|
|
410
|
+
? 'Active employees must be 65 or younger'
|
|
411
|
+
: undefined,
|
|
412
|
+
},
|
|
413
|
+
}
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
Built-in rules:
|
|
417
|
+
|
|
418
|
+
| Editor | Rules |
|
|
419
|
+
| -------- | ----------------------------------- |
|
|
420
|
+
| text | `minLength`, `maxLength`, `pattern` |
|
|
421
|
+
| number | `min`, `max` |
|
|
422
|
+
| date | `min`, `max` |
|
|
423
|
+
| checkbox | none |
|
|
424
|
+
| select | none |
|
|
425
|
+
| custom | none |
|
|
426
|
+
|
|
427
|
+
The checks run in this order, and the first error wins:
|
|
428
|
+
|
|
429
|
+
1. Empty (`null`, `undefined` or `''`): an error if `required`. If not, nothing else is checked, so an empty optional field never fails `min` or your `validate`.
|
|
430
|
+
2. The built-in rules.
|
|
431
|
+
3. Your `validate`. It only runs if the built-in rules passed.
|
|
432
|
+
|
|
433
|
+
`pattern` has to match the whole value, like the HTML attribute. A checkbox is never empty, so `required` does nothing on it.
|
|
434
|
+
|
|
435
|
+
Errors show under their input when the user saves, and a row can't be saved until every field is valid. Messages are in English for now. You'll be able to change them when translations are added.
|
|
436
|
+
|
|
437
|
+
### Chained selects
|
|
438
|
+
|
|
439
|
+
A select's `options` can be a function of the row instead of a fixed list. Add `dependsOn` and the select follows another field: when that field changes, the select is cleared and its options load again.
|
|
440
|
+
|
|
441
|
+
```ts
|
|
442
|
+
const columns: Column<Employee>[] = [
|
|
443
|
+
{
|
|
444
|
+
prop: 'countryId',
|
|
445
|
+
title: 'Country',
|
|
446
|
+
editor: {
|
|
447
|
+
type: 'select',
|
|
448
|
+
options: [
|
|
449
|
+
{ value: 1, label: 'Morocco' },
|
|
450
|
+
{ value: 2, label: 'France' },
|
|
451
|
+
],
|
|
452
|
+
},
|
|
453
|
+
},
|
|
454
|
+
{
|
|
455
|
+
prop: 'cityId',
|
|
456
|
+
title: 'City',
|
|
457
|
+
editor: {
|
|
458
|
+
type: 'select',
|
|
459
|
+
required: true,
|
|
460
|
+
dependsOn: 'countryId',
|
|
461
|
+
options: async (row, { signal }) => {
|
|
462
|
+
if (row.countryId === null) return [];
|
|
463
|
+
|
|
464
|
+
const res = await fetch(`/api/cities?country=${row.countryId}`, { signal });
|
|
465
|
+
return res.json(); // [{ value, label }, …]
|
|
466
|
+
},
|
|
467
|
+
},
|
|
468
|
+
},
|
|
469
|
+
];
|
|
470
|
+
```
|
|
471
|
+
|
|
472
|
+
How it works:
|
|
473
|
+
|
|
474
|
+
- When a row opens, every `options` function runs with the row's values. The current value is kept while it loads, and picked once the options arrive.
|
|
475
|
+
- While loading, the select is disabled and shows "Loading…". A function that returns the list right away (no promise) skips that step. That's useful for filtering a list you already have.
|
|
476
|
+
- When a field changes, everything below it in the chain is cleared, then reloads. With Country → Region → City, changing the country clears both the region and the city.
|
|
477
|
+
- A cleared field is `null`, and the functions below it still run. That's why the example checks `row.countryId === null`. Returning `[]` right away costs nothing.
|
|
478
|
+
- If the user changes the country again before the cities come back, the old request is cancelled through `signal`. Pass it to `fetch` so the request really stops. Even if you don't, a late answer is thrown away.
|
|
479
|
+
- Cancelling or saving the row, `setData` and `destroy` cancel every request still running.
|
|
480
|
+
|
|
481
|
+
If `options` throws, the select stays empty and "Could not load the options." shows under it. The row can't be saved while that message is there. Changing the field it depends on tries again, or the user can cancel the row.
|
|
482
|
+
|
|
483
|
+
`dependsOn` only works with a function. With a fixed list, it's a type error. It must be another field of the row, so a typo is a type error too.
|
|
484
|
+
|
|
485
|
+
Outside edit mode, the city cell needs a `render` to show a name instead of an id. See [What cells show](#what-cells-show).
|
|
486
|
+
|
|
487
|
+
### Saving
|
|
488
|
+
|
|
489
|
+
`onSave` gets the edited row and the row as it was before editing. It can be async.
|
|
490
|
+
|
|
491
|
+
```ts
|
|
492
|
+
import type { SaveContext } from 'tadabut';
|
|
493
|
+
|
|
494
|
+
async function saveEmployee(row: Employee, { previous }: SaveContext<Employee>) {
|
|
495
|
+
console.log(`Saving ${previous.name} as ${row.name}`);
|
|
496
|
+
|
|
497
|
+
const res = await fetch(`/api/employees/${row.id}`, {
|
|
498
|
+
method: 'PUT',
|
|
499
|
+
headers: { 'Content-Type': 'application/json' },
|
|
500
|
+
body: JSON.stringify(row),
|
|
501
|
+
});
|
|
502
|
+
|
|
503
|
+
if (!res.ok) throw new Error('Could not save the employee');
|
|
504
|
+
|
|
505
|
+
// Optional: the server's version replaces the row.
|
|
506
|
+
return (await res.json()) as Employee;
|
|
507
|
+
}
|
|
508
|
+
|
|
509
|
+
const table = new Tadabut(container, {
|
|
510
|
+
data: employees,
|
|
511
|
+
rowId: 'id',
|
|
512
|
+
columns,
|
|
513
|
+
onSave: saveEmployee,
|
|
514
|
+
});
|
|
515
|
+
```
|
|
516
|
+
|
|
517
|
+
What happens when you save:
|
|
518
|
+
|
|
519
|
+
1. Every field is validated. If one fails, its error shows under its input, the cursor goes to the first wrong field, and `onSave` isn't called.
|
|
520
|
+
2. The row is locked while `onSave` runs. Clicking or typing in it does nothing, and it gets the `tdb-row-saving` class.
|
|
521
|
+
3. If `onSave` works, the row closes and shows the new values. If you return a row, that one is used instead. That's handy for fields the server fills in, like `updatedAt`.
|
|
522
|
+
4. If `onSave` throws, the row stays open with everything the user typed, and your error message shows under the row. They can fix it and save again, or cancel.
|
|
523
|
+
|
|
524
|
+
The table's data only changes when saving works, so there's nothing to undo when it fails.
|
|
525
|
+
|
|
526
|
+
`onSave` is optional. Without it, saving just updates the table.
|
|
527
|
+
|
|
528
|
+
### Editing options
|
|
529
|
+
|
|
530
|
+
When at least one column has an `editor`, the table gets one more column at the end, with an Edit button in each row. While a row is being edited, its Edit button is replaced by Save and Cancel. The labels are in English for now.
|
|
531
|
+
|
|
532
|
+
`editing` changes how that works:
|
|
533
|
+
|
|
534
|
+
```ts
|
|
535
|
+
const table = new Tadabut(container, {
|
|
536
|
+
data: employees,
|
|
537
|
+
rowId: 'id',
|
|
538
|
+
columns,
|
|
539
|
+
onSave: saveEmployee,
|
|
540
|
+
editing: {
|
|
541
|
+
mode: 'multiple', // default: 'single'
|
|
542
|
+
button: false, // default: true. false hides the edit button
|
|
543
|
+
},
|
|
544
|
+
});
|
|
545
|
+
```
|
|
546
|
+
|
|
547
|
+
- `'single'` mode: one row at a time. You can't start a new edit while another row is open.
|
|
548
|
+
- `'multiple'` mode: several rows can be open. Each one saves on its own, so `onSave` runs once per row.
|
|
549
|
+
- `button: false`: no buttons column. Start edits from your own code. <kbd>Enter</kbd> and <kbd>Escape</kbd> still work.
|
|
550
|
+
|
|
551
|
+
### Controlling it from code
|
|
552
|
+
|
|
553
|
+
```ts
|
|
554
|
+
table.edit(5); // start editing the row with id 5
|
|
555
|
+
await table.save(5); // validate and save it
|
|
556
|
+
table.cancel(5); // cancel and restore its old values
|
|
557
|
+
table.isEditing(5); // true while row 5 is open
|
|
558
|
+
|
|
559
|
+
table.setData(newEmployees); // replace all rows, keeps sorting and search
|
|
560
|
+
table.destroy(); // remove everything Tadabut created
|
|
561
|
+
```
|
|
562
|
+
|
|
563
|
+
`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.
|
|
564
|
+
|
|
565
|
+
`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.
|
|
566
|
+
|
|
567
|
+
`cancel` does nothing if the row isn't being edited, or while it's saving.
|
|
568
|
+
|
|
569
|
+
`setData` and `destroy` cancel any row being edited first. Unsaved changes are lost.
|
|
570
|
+
|
|
571
|
+
<kbd>Enter</kbd> saves the row you're in. <kbd>Escape</kbd> cancels it. If something else already used the key, like Select2 picking an option with <kbd>Enter</kbd>, Tadabut leaves it alone.
|
|
572
|
+
|
|
573
|
+
### React
|
|
574
|
+
|
|
575
|
+
Same options, as props. Keep `columns` outside your component, or in a `useMemo`, so it doesn't change on every render.
|
|
576
|
+
|
|
577
|
+
A whole file you can copy:
|
|
578
|
+
|
|
579
|
+
```tsx
|
|
580
|
+
import 'datatables.net-dt';
|
|
581
|
+
import 'datatables.net-dt/css';
|
|
582
|
+
|
|
583
|
+
import { useRef, useState } from 'react';
|
|
584
|
+
import type { Column } from 'tadabut';
|
|
585
|
+
import { Tadabut, type TadabutHandle } from 'tadabut/react';
|
|
586
|
+
|
|
587
|
+
type Employee = { id: number; name: string; countryId: number | null };
|
|
588
|
+
|
|
589
|
+
const columns: Column<Employee>[] = [
|
|
590
|
+
{ prop: 'id', title: 'ID' },
|
|
591
|
+
{ prop: 'name', title: 'Name', editor: { type: 'text', required: true } },
|
|
592
|
+
{
|
|
593
|
+
prop: 'countryId',
|
|
594
|
+
title: 'Country',
|
|
595
|
+
editor: {
|
|
596
|
+
type: 'select',
|
|
597
|
+
options: [
|
|
598
|
+
{ value: 1, label: 'Morocco' },
|
|
599
|
+
{ value: 2, label: 'France' },
|
|
600
|
+
],
|
|
601
|
+
},
|
|
602
|
+
},
|
|
603
|
+
];
|
|
604
|
+
|
|
605
|
+
async function saveEmployee(row: Employee): Promise<void> {
|
|
606
|
+
const res = await fetch(`/api/employees/${row.id}`, {
|
|
607
|
+
method: 'PUT',
|
|
608
|
+
headers: { 'Content-Type': 'application/json' },
|
|
609
|
+
body: JSON.stringify(row),
|
|
610
|
+
});
|
|
611
|
+
|
|
612
|
+
if (!res.ok) throw new Error('Could not save the employee');
|
|
613
|
+
}
|
|
614
|
+
|
|
615
|
+
export default function Employees() {
|
|
616
|
+
const [employees] = useState<Employee[]>([
|
|
617
|
+
{ id: 1, name: 'Amina', countryId: 1 },
|
|
618
|
+
{ id: 2, name: 'Paul', countryId: 2 },
|
|
619
|
+
]);
|
|
620
|
+
const tableRef = useRef<TadabutHandle<Employee>>(null);
|
|
621
|
+
|
|
622
|
+
return (
|
|
623
|
+
<>
|
|
624
|
+
<button type="button" onClick={() => tableRef.current?.edit(1)}>
|
|
625
|
+
Edit Amina
|
|
626
|
+
</button>
|
|
627
|
+
|
|
628
|
+
<Tadabut
|
|
629
|
+
ref={tableRef}
|
|
630
|
+
data={employees}
|
|
631
|
+
rowId="id"
|
|
632
|
+
columns={columns}
|
|
633
|
+
editing={{ mode: 'multiple' }}
|
|
634
|
+
onSave={(row) => saveEmployee(row)}
|
|
635
|
+
/>
|
|
636
|
+
</>
|
|
637
|
+
);
|
|
638
|
+
}
|
|
639
|
+
```
|
|
640
|
+
|
|
641
|
+
- When `employees` changes, the table updates in place. It doesn't get rebuilt.
|
|
642
|
+
- `onSave` can be a new function on every render. The table always calls the latest one.
|
|
643
|
+
- `editing` can be a new object on every render too. The table is only rebuilt when `mode` or `button` really change. Changing `columns`, `rowId` or `editing` closes any row being edited.
|
|
644
|
+
- The ref has `edit`, `save`, `cancel` and `isEditing`, the same as the core. Before the table is built, or after it's gone, `edit` and `save` give `false` and `cancel` does nothing.
|
|
645
|
+
- There is no `setData` on the ref. To change the rows, change `data`.
|
|
646
|
+
|
|
647
|
+
## Roadmap
|
|
648
|
+
|
|
649
|
+
- [x] Project setup
|
|
650
|
+
- [x] Thin wrapper: typed columns, data loading, cleanup
|
|
651
|
+
- [x] React adapter
|
|
652
|
+
- [x] Inputs: text, number, date, checkbox, select
|
|
653
|
+
- [x] Custom editors (Select2, date pickers, …)
|
|
654
|
+
- [x] Row editing: save, cancel, validation errors
|
|
655
|
+
- [x] Chained selects
|
|
656
|
+
- [x] Show labels instead of raw values in cells
|
|
657
|
+
- [x] First release (0.1.0)
|
|
658
|
+
- [ ] Keyboard navigation, translations, theming
|
|
659
|
+
|
|
660
|
+
Later: adding and deleting rows, popup editing, changing many rows in one go, server-side mode, Vue and jQuery adapters.
|
|
661
|
+
|
|
662
|
+
## Contributing
|
|
663
|
+
|
|
664
|
+
Help is welcome. Read [CONTRIBUTING.md](./CONTRIBUTING.md) to get set up, and please follow the [code of conduct](./CODE_OF_CONDUCT.md).
|
|
665
|
+
|
|
666
|
+
## Not affiliated with DataTables
|
|
667
|
+
|
|
668
|
+
Tadabut is an independent project. It isn't made by SpryMedia or the DataTables team, and it doesn't contain any code from DataTables Editor.
|
|
669
|
+
|
|
670
|
+
## License
|
|
671
|
+
|
|
672
|
+
[MIT](./LICENSE) © Anas Youssef ELMAHDAD
|