tadabut 0.1.0 → 0.3.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 CHANGED
@@ -1,21 +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.
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
@@ -5,10 +5,14 @@
5
5
  [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
6
6
  [![DataTables 3](https://img.shields.io/badge/DataTables-3.x-0d6efd)](https://datatables.net)
7
7
  [![Status](https://img.shields.io/badge/status-early%20development-orange)](#roadmap)
8
+ [![npm](https://img.shields.io/npm/v/tadabut)](https://www.npmjs.com/package/tadabut)
9
+ [![Docs](https://img.shields.io/badge/docs-API%20reference-blue)](https://ayem1412.github.io/tadabut/)
8
10
  [![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
9
11
 
10
12
  Tadabut wraps [DataTables](https://datatables.net) and adds what it doesn't give you for free: editing rows, real inputs in the cells, and selects that depend on each other.
11
13
 
14
+ 📖 [API reference](https://ayem1412.github.io/tadabut/): every option and type, from the code's own comments.
15
+
12
16
  > [!WARNING]
13
17
  > Tadabut is new. Until 1.0, the API can change between `0.x` versions, so pin the version you use and read the changelog before you update.
14
18
 
@@ -154,7 +158,7 @@ A select's values must have the same type as the column. `countryId` is a number
154
158
  | `number` | `number` | `null` | `min`, `max`, `step` |
155
159
  | `date` | `string` | `null` | `min`, `max` |
156
160
  | `checkbox` | `boolean` | never empty | none |
157
- | `select` | same as the column | `null` | `options`, `dependsOn` |
161
+ | `select` | same as the column | `null` | `options`, `dependsOn`, `labelProp` |
158
162
 
159
163
  Every editor also takes `className`, for your own CSS classes.
160
164
 
@@ -167,61 +171,270 @@ A few things to know:
167
171
 
168
172
  ### What cells show
169
173
 
170
- When a row isn't being edited, a cell shows its value as text. Two things change that:
174
+ When a row isn't being edited, a cell shows its value as text. Three things change that:
171
175
 
172
176
  - A select with a fixed list shows the option's label. A `countryId` of `1` shows "Morocco", with nothing to write.
177
+ - A select with `labelProp` shows that field of the row, like `cityName`. See [Chained selects](#chained-selects).
173
178
  - `render` sets the text yourself, on any column:
174
179
 
175
180
  ```ts
176
181
  { 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
  ```
182
183
 
183
184
  A few things to know:
184
185
 
185
- - `render` wins over a select's label.
186
+ - The order is: `render`, then `labelProp`, then the fixed list's label, then the value itself.
186
187
  - 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
188
  - 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
189
  - An empty value (`null` or `undefined`) shows an empty cell. On a nullable column, `render` gets `null` too.
189
190
  - Editors always get the raw value. After saving or cancelling, the text is worked out again.
190
191
 
192
+ ### Column options
193
+
194
+ A few more column settings, passed to DataTables:
195
+
196
+ ```ts
197
+ const columns: Column<Employee>[] = [
198
+ { prop: 'id', title: 'ID', width: '60px', className: 'dt-center' },
199
+ { prop: 'name', title: 'Name', editor: { type: 'text' } },
200
+ { prop: 'countryCode', title: 'Code', visible: false },
201
+ { prop: 'salary', title: 'Salary', orderable: false, searchable: false },
202
+ ];
203
+ ```
204
+
205
+ | Option | What it does |
206
+ | ------------ | --------------------------------------------------------------------------- |
207
+ | `width` | the column's width, like `'60px'` or `'20%'` |
208
+ | `visible` | `false` hides the column. Its value stays in the row, and `onSave` gets it. |
209
+ | `orderable` | `false`: clicking the header doesn't sort by it |
210
+ | `searchable` | `false`: the search box ignores it |
211
+ | `className` | classes for the column's cells, header included |
212
+
213
+ `className` here is for the cells. The input's classes go in the editor's `className`.
214
+
215
+ A hidden column can't have an `editor`: nobody could see the input. Tadabut throws an error when you try.
216
+
217
+ ### DataTables settings
218
+
219
+ `dataTables` passes DataTables' own settings through as they are: paging, page sizes, the default order, the texts, and the settings of extensions like Buttons. See [DataTables' options](https://datatables.net/reference/option/) for the full list.
220
+
221
+ ```ts
222
+ const table = new Tadabut(container, {
223
+ data: employees,
224
+ rowId: 'id',
225
+ columns,
226
+ dataTables: {
227
+ order: [[1, 'asc']], // sort by the second column
228
+ pageLength: 20,
229
+ lengthMenu: [10, 20, 50, -1], // -1 means "All"
230
+ language: {
231
+ search: 'Rechercher :',
232
+ lengthMenu: '_MENU_ lignes par page',
233
+ info: 'Lignes _START_ à _END_ sur _TOTAL_',
234
+ zeroRecords: 'Aucune ligne trouvée',
235
+ paginate: { first: 'Premier', previous: 'Précédent', next: 'Suivant', last: 'Dernier' },
236
+ },
237
+ },
238
+ });
239
+ ```
240
+
241
+ Columns are counted from 0, in the order of your `columns`. The Edit button column always comes last, so it never moves your columns.
242
+
243
+ Five settings aren't allowed, because Tadabut controls them:
244
+
245
+ - `data` and `columns`: Tadabut makes them from its own `data` and `columns`.
246
+ - `columnDefs`: use the column options above instead.
247
+ - `ajax` and `serverSide`: DataTables would load and replace rows behind Tadabut's back. Load the rows yourself and call `setData`.
248
+
249
+ These are type errors, and Tadabut's own values win even in plain JavaScript.
250
+
251
+ `language` only changes DataTables' texts. For Tadabut's own texts, see [Texts and translations](#texts-and-translations).
252
+
253
+ In React, keep `dataTables` outside your component or in a `useMemo`, like `columns`. A new object on every render rebuilds the table.
254
+
255
+ ### Texts and translations
256
+
257
+ Tadabut's own texts (the Edit, Save and Cancel buttons, "Loading…", and the error messages) are in English by default. French comes built in:
258
+
259
+ ```ts
260
+ import { Tadabut, fr } from 'tadabut';
261
+
262
+ const table = new Tadabut(container, { data, columns, rowId: 'id', texts: fr });
263
+ ```
264
+
265
+ Change only some of them, or write your own language. Whatever you leave out stays in English:
266
+
267
+ ```ts
268
+ texts: { ...fr, save: 'Valider' }
269
+
270
+ texts: { edit: 'Bearbeiten', save: 'Speichern', cancel: 'Abbrechen' }
271
+ ```
272
+
273
+ | Key | English |
274
+ | ------------------------ | ------------------------------- |
275
+ | `edit`, `save`, `cancel` | Edit, Save, Cancel |
276
+ | `loading` | Loading… |
277
+ | `saveFailed` | Could not save. |
278
+ | `loadFailed` | Could not load the options. |
279
+ | `required` | This field is required. |
280
+ | `patternMismatch` | Wrong format. |
281
+ | `tooShort`, `tooLong` | Must be at least 2 characters. |
282
+ | `tooSmall`, `tooLarge` | Must be 18 or more. |
283
+ | `tooEarly`, `tooLate` | Must be on or after 2020-01-01. |
284
+
285
+ The messages with a number or a date are functions, so you can put the value where your language needs it:
286
+
287
+ ```ts
288
+ texts: {
289
+ tooSmall: (min) => `Mindestens ${min}.`;
290
+ }
291
+ ```
292
+
293
+ `saveFailed` only shows when `onSave` throws something that isn't an `Error`. When it throws an `Error`, its own message is shown.
294
+
295
+ DataTables' own texts (search, paging, "Showing 1 to 10") are set separately, with `dataTables.language`. See [DataTables settings](#datatables-settings).
296
+
297
+ In React, `texts={fr}` is fine. A new object on every render (like `texts={{ ...fr, save: 'Valider' }}` written inline) rebuilds the table each time, so put it in a constant or a `useMemo`.
298
+
191
299
  ### Styling
192
300
 
193
301
  Tadabut doesn't ship any CSS. Everything it creates gets these classes, so you can style it however you want:
194
302
 
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 error under a row that failed to save |
205
- | `tdb-row-saving` | a row while it's being saved |
206
- | `tdb-actions` | the column with the buttons, header too |
207
- | `tdb-button` | every button |
208
- | `tdb-button-edit` | the Edit button |
209
- | `tdb-button-save` | the Save button |
210
- | `tdb-button-cancel` | the Cancel button |
211
-
212
- To use Bootstrap, Tailwind or anything else, put your classes in `className`. They get added next to the `tdb-` ones.
303
+ | Class | Used on |
304
+ | ------------------------ | ------------------------------------------------- |
305
+ | `tdb-input` | every input |
306
+ | `tdb-input-text` | text inputs |
307
+ | `tdb-input-number` | number inputs |
308
+ | `tdb-input-date` | date inputs |
309
+ | `tdb-input-checkbox` | checkboxes |
310
+ | `tdb-input-select` | selects |
311
+ | `tdb-error` | a field's error message, under its input |
312
+ | `tdb-save-error` | the line (`<tr>`) under a row that failed to save |
313
+ | `tdb-save-error-message` | the message inside that line |
314
+ | `tdb-row-editing` | a row while it's being edited |
315
+ | `tdb-row-saving` | a row while it's being saved |
316
+ | `tdb-actions` | the column with the buttons, header too |
317
+ | `tdb-button` | every button |
318
+ | `tdb-button-edit` | the Edit button |
319
+ | `tdb-button-save` | the Save button |
320
+ | `tdb-button-cancel` | the Cancel button |
321
+
322
+ 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:
323
+
324
+ - `className` on an editor, for its input.
325
+ - `classNames` on the table, for the `<table>` and the buttons.
326
+
327
+ ```ts
328
+ const table = new Tadabut(container, {
329
+ data: employees,
330
+ rowId: 'id',
331
+ columns: [
332
+ { prop: 'id', title: 'ID' },
333
+ {
334
+ prop: 'name',
335
+ title: 'Name',
336
+ editor: { type: 'text', className: 'w-full rounded border px-2 py-1' },
337
+ },
338
+ ],
339
+ classNames: {
340
+ table: 'w-full text-sm',
341
+ button: 'rounded px-2 py-1',
342
+ save: 'bg-blue-600 text-white',
343
+ },
344
+ });
345
+ ```
346
+
347
+ | `classNames` key | Added to |
348
+ | ---------------- | --------------------------------- |
349
+ | `table` | the `<table>` |
350
+ | `button` | the Edit, Save and Cancel buttons |
351
+ | `edit` | the Edit button only |
352
+ | `save` | the Save button only |
353
+ | `cancel` | the Cancel button only |
354
+
355
+ 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.
356
+
357
+ 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.
358
+
359
+ #### With Bootstrap 5
360
+
361
+ Install the Bootstrap version of DataTables instead of `datatables.net-dt`, and Bootstrap itself:
362
+
363
+ ```sh
364
+ pnpm add tadabut datatables.net-bs5 bootstrap
365
+ ```
366
+
367
+ Import them once:
213
368
 
214
369
  ```ts
215
- // Bootstrap
216
- { prop: 'name', title: 'Name', editor: { type: 'text', className: 'form-control' } }
370
+ import 'bootstrap/dist/css/bootstrap.min.css';
371
+ import 'datatables.net-bs5';
372
+ import 'datatables.net-bs5/css';
373
+ ```
374
+
375
+ Then give the editors and the table Bootstrap's classes:
376
+
377
+ ```ts
378
+ const columns: Column<Employee>[] = [
379
+ { prop: 'id', title: 'ID' },
380
+ {
381
+ prop: 'name',
382
+ title: 'Name',
383
+ editor: { type: 'text', className: 'form-control form-control-sm' },
384
+ },
385
+ {
386
+ prop: 'countryId',
387
+ title: 'Country',
388
+ editor: {
389
+ type: 'select',
390
+ className: 'form-select form-select-sm',
391
+ options: [
392
+ { value: 1, label: 'Morocco' },
393
+ { value: 2, label: 'France' },
394
+ ],
395
+ },
396
+ },
397
+ { prop: 'active', title: 'Active', editor: { type: 'checkbox', className: 'form-check-input' } },
398
+ ];
217
399
 
218
- // Tailwind
219
- { prop: 'name', title: 'Name', editor: { type: 'text', className: 'w-full rounded border px-2 py-1' } }
400
+ const table = new Tadabut(container, {
401
+ data: employees,
402
+ rowId: 'id',
403
+ columns,
404
+ classNames: {
405
+ table: 'table table-striped table-hover align-middle',
406
+ button: 'btn btn-sm',
407
+ edit: 'btn-outline-primary',
408
+ save: 'btn-primary',
409
+ cancel: 'btn-outline-secondary',
410
+ },
411
+ });
220
412
  ```
221
413
 
222
- If you use Tailwind: it only keeps classes it finds in your own files. Classes in your column config count, so they work.
414
+ Error messages and the rows being edited need a few lines of your own CSS:
223
415
 
224
- The table itself is styled by the DataTables package you install: `datatables.net-dt` for the default look, `datatables.net-bs5` for Bootstrap 5, and so on.
416
+ ```css
417
+ /* Errors in Bootstrap's red. Use the message's class, not the row's:
418
+ Bootstrap sets a color on every table cell. */
419
+ .tdb-error,
420
+ .tdb-save-error-message {
421
+ color: var(--bs-form-invalid-color);
422
+ font-size: 0.875em;
423
+ }
424
+
425
+ /* While editing, line the inputs up at the top, so an error under one
426
+ input doesn't move the others. */
427
+ .table > tbody > tr.tdb-row-editing > td {
428
+ vertical-align: top;
429
+ }
430
+
431
+ .tdb-row-saving {
432
+ opacity: 0.5;
433
+ }
434
+ ```
435
+
436
+ > [!TIP]
437
+ > 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.
225
438
 
226
439
  ### Custom editors
227
440
 
@@ -327,7 +540,7 @@ The checks run in this order, and the first error wins:
327
540
 
328
541
  `pattern` has to match the whole value, like the HTML attribute. A checkbox is never empty, so `required` does nothing on it.
329
542
 
330
- 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.
543
+ Errors show under their input when the user saves, and a row can't be saved until every field is valid. To change the messages, see [Texts and translations](#texts-and-translations).
331
544
 
332
545
  ### Chained selects
333
546
 
@@ -353,11 +566,13 @@ const columns: Column<Employee>[] = [
353
566
  type: 'select',
354
567
  required: true,
355
568
  dependsOn: 'countryId',
569
+ labelProp: 'cityName',
356
570
  options: async (row, { signal }) => {
357
571
  if (row.countryId === null) return [];
358
572
 
359
573
  const res = await fetch(`/api/cities?country=${row.countryId}`, { signal });
360
- return res.json(); // [{ value, label }, …]
574
+ const cities: { id: number; name: string }[] = await res.json();
575
+ return cities.map((city) => ({ value: city.id, label: city.name }));
361
576
  },
362
577
  },
363
578
  },
@@ -377,7 +592,18 @@ If `options` throws, the select stays empty and "Could not load the options." sh
377
592
 
378
593
  `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.
379
594
 
380
- Outside edit mode, the city cell needs a `render` to show a name instead of an id. See [What cells show](#what-cells-show).
595
+ #### Saving the label too: `labelProp`
596
+
597
+ The city's value is an id, like `12`, but people need to see "Casablanca". With options from a function, Tadabut only knows the names while the row is open, so it can't show them in the cell by itself. That's what `labelProp` is for: a field of the row where the picked option's label is saved.
598
+
599
+ With `labelProp: 'cityName'`:
600
+
601
+ - The cell shows `row.cityName`. No `render` needed.
602
+ - When the user picks Casablanca and saves, the row gets `cityId: 12` **and** `cityName: 'Casablanca'`. `onSave` gets both, and the cell shows the new name.
603
+ - Nothing picked saves `null` in both. `required` still stops the save.
604
+ - While the options are still loading, `cityName` keeps its old value, which is still right: the id didn't change either.
605
+
606
+ `labelProp` works with a fixed list too. It must be a text field of the row (`string`, nullable or optional ones too), so `labelProp: 'age'` is a type error. It can't be the column's own `prop`: saving would write the label over the id, so Tadabut throws an error.
381
607
 
382
608
  ### Saving
383
609
 
@@ -422,7 +648,7 @@ The table's data only changes when saving works, so there's nothing to undo when
422
648
 
423
649
  ### Editing options
424
650
 
425
- 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.
651
+ 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`.
426
652
 
427
653
  `editing` changes how that works:
428
654
 
@@ -541,6 +767,8 @@ export default function Employees() {
541
767
 
542
768
  ## Roadmap
543
769
 
770
+ Done:
771
+
544
772
  - [x] Project setup
545
773
  - [x] Thin wrapper: typed columns, data loading, cleanup
546
774
  - [x] React adapter
@@ -549,10 +777,28 @@ export default function Employees() {
549
777
  - [x] Row editing: save, cancel, validation errors
550
778
  - [x] Chained selects
551
779
  - [x] Show labels instead of raw values in cells
552
- - [ ] First release (0.1.0)
553
- - [ ] Keyboard navigation, translations, theming
554
-
555
- Later: adding and deleting rows, popup editing, changing many rows in one go, server-side mode, Vue and jQuery adapters.
780
+ - [x] First release (0.1.0)
781
+ - [x] Your own classes on the table and buttons (`classNames`), and a Bootstrap 5 recipe
782
+ - [x] API reference site
783
+ - [x] Pass DataTables settings through (paging, page sizes, default order, language, extensions like Buttons), and column `width`, `visible`, `orderable`, `searchable` and `className`
784
+ - [x] Selects that also save their label in the row (`labelProp`), so the cell shows the new label after a save
785
+ - [x] Translations for Tadabut's own texts (buttons and error messages), French built in
786
+
787
+ Next, roughly in this order:
788
+
789
+ - [ ] Adding new rows, and deleting rows, with a confirmation step
790
+ - [ ] Checkboxes with your own values, like `'O'` and `'N'` instead of `true` and `false`
791
+ - [ ] Money inputs, formatted while typing (`12 500.00`)
792
+ - [ ] Dates as `dd/mm/yyyy`, in the input and when sorting
793
+ - [ ] Totals in the footer
794
+ - [ ] A checkbox column to select rows, with "check all"
795
+ - [ ] More events: when editing starts, after saving, row click and double click
796
+ - [ ] Detail rows that open under a row
797
+ - [ ] Time and read-only inputs
798
+ - [ ] Methods to read rows (`getData`, `getRow`), add and remove rows from code, and reach the DataTables API
799
+ - [ ] Keyboard navigation and theming
800
+
801
+ Later: popup editing, changing many rows in one go, server-side mode, Vue and jQuery adapters.
556
802
 
557
803
  ## Contributing
558
804