tadabut 0.2.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/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,27 +171,131 @@ 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:
@@ -432,7 +540,7 @@ The checks run in this order, and the first error wins:
432
540
 
433
541
  `pattern` has to match the whole value, like the HTML attribute. A checkbox is never empty, so `required` does nothing on it.
434
542
 
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.
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).
436
544
 
437
545
  ### Chained selects
438
546
 
@@ -458,11 +566,13 @@ const columns: Column<Employee>[] = [
458
566
  type: 'select',
459
567
  required: true,
460
568
  dependsOn: 'countryId',
569
+ labelProp: 'cityName',
461
570
  options: async (row, { signal }) => {
462
571
  if (row.countryId === null) return [];
463
572
 
464
573
  const res = await fetch(`/api/cities?country=${row.countryId}`, { signal });
465
- 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 }));
466
576
  },
467
577
  },
468
578
  },
@@ -482,7 +592,18 @@ If `options` throws, the select stays empty and "Could not load the options." sh
482
592
 
483
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.
484
594
 
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).
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.
486
607
 
487
608
  ### Saving
488
609
 
@@ -527,7 +648,7 @@ The table's data only changes when saving works, so there's nothing to undo when
527
648
 
528
649
  ### Editing options
529
650
 
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.
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`.
531
652
 
532
653
  `editing` changes how that works:
533
654
 
@@ -646,6 +767,8 @@ export default function Employees() {
646
767
 
647
768
  ## Roadmap
648
769
 
770
+ Done:
771
+
649
772
  - [x] Project setup
650
773
  - [x] Thin wrapper: typed columns, data loading, cleanup
651
774
  - [x] React adapter
@@ -655,9 +778,27 @@ export default function Employees() {
655
778
  - [x] Chained selects
656
779
  - [x] Show labels instead of raw values in cells
657
780
  - [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.
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.
661
802
 
662
803
  ## Contributing
663
804