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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tadabut",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "Typed wrapper for DataTables with row editing, rich inputs and chained selects.",
5
5
  "keywords": [
6
6
  "datatables",
@@ -20,7 +20,7 @@
20
20
  "type": "git",
21
21
  "url": "git+https://github.com/ayem1412/tadabut.git"
22
22
  },
23
- "homepage": "https://github.com/ayem1412/tadabut#readme",
23
+ "homepage": "https://ayem1412.github.io/tadabut/",
24
24
  "bugs": "https://github.com/ayem1412/tadabut/issues",
25
25
  "license": "MIT",
26
26
  "type": "module",
@@ -42,17 +42,19 @@
42
42
  "@biomejs/biome": "2.5.15",
43
43
  "@types/react": "^19.3.0",
44
44
  "@types/react-dom": "^19.3.0",
45
- "@vitejs/plugin-react": "^6.1.2",
46
- "datatables.net": "^3.1.4",
47
- "datatables.net-dt": "^3.1.4",
45
+ "@vitejs/plugin-react": "^6.2.1",
46
+ "bootstrap": "^5.3.8",
47
+ "datatables.net": "^3.1.5",
48
+ "datatables.net-bs5": "^3.1.5",
49
+ "datatables.net-dt": "^3.1.5",
48
50
  "jsdom": "^30.1.3",
49
51
  "publint": "^0.3.25",
50
52
  "react": "^19.3.1",
51
53
  "react-dom": "^19.3.1",
52
- "tsdown": "^0.23.3",
54
+ "tsdown": "^0.23.4",
53
55
  "typescript": "^7.0.2",
54
56
  "vite": "^8.3.5",
55
- "vitest": "^5.0.5"
57
+ "vitest": "^5.1.0"
56
58
  },
57
59
  "devEngines": {
58
60
  "packageManager": {
@@ -67,6 +69,7 @@
67
69
  "./package.json": "./package.json"
68
70
  },
69
71
  "scripts": {
72
+ "docs": "pnpm dlx --package typedoc@0.28.20 --package typescript@6.0.x typedoc",
70
73
  "dev": "vite",
71
74
  "build": "tsdown",
72
75
  "test": "vitest",
@@ -1,566 +0,0 @@
1
- /**
2
- * Options shared by every editor.
3
- *
4
- * Internal: users never write this type. Its fields show up on each editor.
5
- */
6
- type BaseEditor = {
7
- /**
8
- * Extra CSS classes added to the input, next to Tadabut's own `tdb-…`
9
- * classes. Use it for Tailwind or Bootstrap classes, like `'form-control'`.
10
- */
11
- readonly className?: string;
12
- };
13
- /**
14
- * What an editor receives when Tadabut creates it, at the start of a row edit.
15
- *
16
- * Custom editors get the same context as the built-in ones.
17
- *
18
- * @typeParam Value - The column's value type.
19
- */
20
- type EditorContext<Value> = {
21
- /** The value from the row when editing starts. */
22
- readonly value: Value;
23
- /**
24
- * Extra CSS classes from the editor config, if any. Add them to the
25
- * element, next to your own classes.
26
- */
27
- readonly className?: string;
28
- /**
29
- * Call this every time the user changes the value, with the new value.
30
- * Tadabut keeps track of the previous one.
31
- */
32
- readonly onChange: (value: Value) => void;
33
- };
34
- /**
35
- * A live editor: the input shown in a cell while a row is being edited.
36
- *
37
- * Every editor, built-in or custom, returns one of these. Tadabut puts
38
- * `element` in the cell, reads the value with `getValue` when saving, and
39
- * calls `destroy` when editing ends.
40
- *
41
- * @typeParam Value - The column's value type.
42
- */
43
- type EditorInstance<Value> = {
44
- /** The root element. Tadabut adds it to the cell. */
45
- readonly element: HTMLElement;
46
- /** Returns the value the user has entered so far. */
47
- readonly getValue: () => Value;
48
- /** Shows a new value, without calling `onChange`. */
49
- readonly setValue: (value: Value) => void;
50
- /** Puts the cursor in the editor. */
51
- readonly focus: () => void;
52
- /**
53
- * Removes the element and cleans up anything the editor created, like
54
- * listeners or third-party widgets. Called once, when editing ends.
55
- */
56
- readonly destroy: () => void;
57
- };
58
- /**
59
- * A checkbox, for `boolean` columns. Checked means `true`.
60
- *
61
- * A `null` value shows as unchecked. The checkbox always gives back `true`
62
- * or `false`, never `null`.
63
- *
64
- * @example
65
- * { type: 'checkbox' }
66
- */
67
- type CheckboxEditor = BaseEditor & {
68
- readonly type: "checkbox";
69
- };
70
- /**
71
- * An editor you build yourself, like a Select2 dropdown or a date picker
72
- * library. Works on any column, including object columns that have no
73
- * built-in editor.
74
- *
75
- * Tadabut calls `create` each time a row starts being edited. It gets the
76
- * starting value (which can be `null` on a nullable column), the
77
- * `className` from this config, and an `onChange` to call when the user
78
- * changes the value.
79
- *
80
- * @typeParam Value - The column's value type, including `null` if the
81
- * column can hold it.
82
- *
83
- * @example
84
- * {
85
- * type: 'custom',
86
- * create: (context) => {
87
- * const input = document.createElement('input');
88
- * input.value = context.value ?? '';
89
- * input.addEventListener('input', () => context.onChange(input.value));
90
- * return {
91
- * element: input,
92
- * getValue: () => input.value,
93
- * setValue: (value) => { input.value = value ?? ''; },
94
- * focus: () => input.focus(),
95
- * destroy: () => input.remove(),
96
- * };
97
- * },
98
- * }
99
- */
100
- type CustomEditor<Value> = BaseEditor & {
101
- readonly type: "custom";
102
- /** Builds the live editor. Called once per row edit. */
103
- readonly create: (context: EditorContext<Value>) => EditorInstance<Value>;
104
- };
105
- /**
106
- * A date picker, for `string` columns holding dates as `'YYYY-MM-DD'`.
107
- *
108
- * The options match the HTML `<input type="date">` attributes of the same
109
- * name. An empty input gives `null`.
110
- *
111
- * The column must hold exactly `'YYYY-MM-DD'`. Any other format, like
112
- * `'2024-01-05T00:00:00'`, shows as an empty input, and saving would turn it
113
- * into `null`. Convert dates to `'YYYY-MM-DD'` before giving them to the
114
- * table.
115
- *
116
- * @example
117
- * { type: 'date', min: '2020-01-01', max: '2030-12-31' }
118
- */
119
- type DateEditor = BaseEditor & {
120
- readonly type: "date";
121
- /** Earliest date allowed, as `'YYYY-MM-DD'`. */
122
- readonly min?: string;
123
- /** Latest date allowed, as `'YYYY-MM-DD'`. */
124
- readonly max?: string;
125
- };
126
- /**
127
- * A number input, for `number` columns.
128
- *
129
- * An empty input gives `null`, not `0`.
130
- *
131
- * The options match the HTML `<input type="number">` attributes of the same
132
- * name.
133
- *
134
- * @example
135
- * { type: 'number', min: 18, max: 65, step: 1 }
136
- */
137
- type NumberEditor = BaseEditor & {
138
- readonly type: "number";
139
- /** Smallest value allowed. */
140
- readonly min?: number;
141
- /** Largest value allowed. */
142
- readonly max?: number;
143
- /**
144
- * Allowed gap between values, counted from `min` (or 0).
145
- * `1` allows only whole numbers, `0.01` allows cents, and `'any'` allows
146
- * any decimal. Default: `1`.
147
- */
148
- readonly step?: number | "any";
149
- };
150
- /**
151
- * One choice in a select.
152
- *
153
- * @typeParam Value - The column's value type.
154
- */
155
- type SelectOption<Value> = {
156
- /** Text shown to the user. */
157
- readonly label: string;
158
- /** Value saved in the row when this choice is picked. */
159
- readonly value: Value;
160
- };
161
- /**
162
- * What a select's `options` function gets next to the row.
163
- */
164
- type OptionsContext = {
165
- /**
166
- * Aborted when the options aren't needed anymore: the field it depends on
167
- * changed again, or the row was closed. Pass it to `fetch` so old requests
168
- * stop.
169
- */
170
- readonly signal: AbortSignal;
171
- };
172
- /**
173
- * A select's options as a function of the row. It can return the list right
174
- * away, or a promise of it.
175
- *
176
- * @typeParam Value - The column's value type.
177
- * @typeParam Row - The shape of one row.
178
- */
179
- type SelectOptionsLoader<Value, Row> = (row: Row, context: OptionsContext) => readonly SelectOption<Value>[] | Promise<readonly SelectOption<Value>[]>;
180
- /**
181
- * A dropdown list. Works for `string`, `number` and `boolean` columns.
182
- *
183
- * Option values must have the same type as the column: a `number` column
184
- * needs `value: 1`, not `value: '1'`.
185
- *
186
- * When the row's value matches no option (or is `null`), nothing is picked
187
- * and the editor gives `null`.
188
- *
189
- * `options` is either a fixed list, or a function of the row. Only a
190
- * function can have `dependsOn`: when that field changes, this select is
191
- * cleared and its options load again.
192
- *
193
- * @typeParam Value - The column's value type.
194
- * @typeParam Row - The shape of one row.
195
- *
196
- * @example
197
- * // A fixed list
198
- * { type: 'select', options: [{ value: 1, label: 'Morocco' }] }
199
- *
200
- * // Options that depend on another field
201
- * {
202
- * type: 'select',
203
- * dependsOn: 'countryId',
204
- * options: (row, { signal }) => fetchCities(row.countryId, signal),
205
- * }
206
- */
207
- type SelectEditor<Value, Row> = BaseEditor & {
208
- readonly type: "select";
209
- } & ({
210
- /** The choices, in the order they are shown. */
211
- readonly options: readonly SelectOption<Value>[];
212
- /** Only allowed when `options` is a function. */
213
- readonly dependsOn?: never;
214
- } | {
215
- /** Gives the choices for the row being edited. */
216
- readonly options: SelectOptionsLoader<Value, Row>;
217
- /**
218
- * Another field of the row. When it changes, this select is cleared
219
- * and `options` runs again.
220
- */
221
- readonly dependsOn?: keyof Row & string;
222
- });
223
- /**
224
- * A one-line text input, for `string` columns.
225
- *
226
- * The options match the HTML `<input>` attributes of the same name.
227
- *
228
- * @example
229
- * { type: 'text', minLength: 2, maxLength: 50 }
230
- */
231
- type TextEditor = BaseEditor & {
232
- readonly type: "text";
233
- /** Fewest characters allowed. */
234
- readonly minLength?: number;
235
- /** Most characters allowed. The input stops accepting more. */
236
- readonly maxLength?: number;
237
- /**
238
- * A regular expression the whole value must match, written as a string,
239
- * like `'[A-Z]{2}[0-9]{4}'`. No `/…/` slashes and no `^` or `$`:
240
- * the browser always checks the full value.
241
- */
242
- readonly pattern?: string;
243
- };
244
- /**
245
- * The editors that fit a column, based on the type of value it holds.
246
- *
247
- * | Column value | Built-in editors | Custom editor |
248
- * | ------------- | ------------------ | ------------- |
249
- * | `string` | text, date, select | yes |
250
- * | `number` | number, select | yes |
251
- * | `boolean` | checkbox, select | yes |
252
- * | anything else | none | yes |
253
- *
254
- * For built-in editors, `null` and `undefined` are ignored, so a
255
- * `string | null` column gets the same editors as a `string` column.
256
- * A custom editor keeps the full type, `null` included, because it receives
257
- * the row's value as it is.
258
- *
259
- * @typeParam Value - The column's value type.
260
- * @typeParam Row - The shape of one row. Only selects use it, for `options`
261
- * functions and `dependsOn`.
262
- */
263
- type EditorFor<Value, Row> = EditorForValue<NonNullable<Value>, Row> | CustomEditor<Value>;
264
- type EditorForValue<Value, Row> = [Value] extends [string] ? TextEditor | DateEditor | SelectEditor<Value, Row> : [Value] extends [number] ? NumberEditor | SelectEditor<Value, Row> : [Value] extends [boolean] ? CheckboxEditor | SelectEditor<Value, Row> : never;
265
- /**
266
- * Validation options. They go on any editor, built-in or custom.
267
- *
268
- * Checks run in this order, and the first error wins:
269
- * 1. Empty value (`null`, `undefined` or `''`): an error if `required`,
270
- * otherwise no error and nothing else is checked.
271
- * 2. The editor's own rules, like `min` or `maxLength`.
272
- * 3. `validate`.
273
- *
274
- * @typeParam Row - The shape of one row.
275
- * @typeParam Value - The column's value type.
276
- *
277
- * @example
278
- * {
279
- * type: 'number',
280
- * required: true,
281
- * min: 18,
282
- * validate: (value, row) =>
283
- * row.active && value !== null && value > 65
284
- * ? 'Active employees must be 65 or younger'
285
- * : undefined,
286
- * }
287
- */
288
- type ValidationOptions<Row, Value> = {
289
- /**
290
- * The value can't be empty. Has no effect on a checkbox, which is never
291
- * empty.
292
- */
293
- readonly required?: boolean;
294
- /**
295
- * Your own check. Return an error message, or `undefined` if the value is
296
- * fine. Runs last, only on values that passed the other rules.
297
- *
298
- * `value` can be `null`, because editors give `null` when empty, even on
299
- * columns that can't hold `null`.
300
- */
301
- readonly validate?: (value: Value | null, row: Row) => string | undefined;
302
- };
303
- /**
304
- * One column of a Tadabut table.
305
- *
306
- * `prop` picks the row property to show, and `editor` (optional) must fit
307
- * that property's type: a `number` property can't have a text editor.
308
- * A column without an `editor` is read-only.
309
- *
310
- * @typeParam Row - The shape of one row.
311
- *
312
- * @example
313
- * const columns: Column<Employee>[] = [
314
- * { title: 'ID', prop: 'id' },
315
- * {
316
- * title: 'Age',
317
- * prop: 'age',
318
- * editor: { type: 'number', required: true, min: 18 },
319
- * },
320
- * ];
321
- */
322
- type Column<Row extends object> = { readonly [Key in keyof Row & string]: ColumnFor<Row, Key>; }[keyof Row & string];
323
- /** The column for one row property. `Column` is the union of these. */
324
- type ColumnFor<Row extends object, Key extends keyof Row & string> = {
325
- /** Text shown in the column header. */
326
- readonly title: string;
327
- /** Name of the row property shown in this column. */
328
- readonly prop: Key;
329
- /**
330
- * How the value is edited, and its validation rules. Leave it out for a
331
- * read-only column.
332
- */
333
- readonly editor?: EditorFor<Row[Key], Row> & ValidationOptions<Row, Row[Key]>;
334
- /**
335
- * The text shown in the cell, when the row isn't being edited.
336
- *
337
- * Without it, a select with a fixed list shows its option's label, and
338
- * any other column shows its value as text.
339
- *
340
- * The result is shown as plain text, never as HTML. Searching uses it,
341
- * sorting still uses the raw value.
342
- *
343
- * @example
344
- * render: (value, row) => row.cityName
345
- * render: (value) => `${value} MAD`
346
- */
347
- readonly render?: (value: Row[Key], row: Row) => string;
348
- };
349
- /**
350
- * Extra information `onSave` gets next to the edited row.
351
- *
352
- * @typeParam Row - The shape of one row.
353
- */
354
- type SaveContext<Row extends object> = {
355
- /** The row as it was when editing started. */
356
- readonly previous: Row;
357
- };
358
- /**
359
- * How rows are edited.
360
- */
361
- type EditingOptions = {
362
- /**
363
- * How many rows can be edited at once.
364
- *
365
- * - `'single'` (default): one row. `edit` returns `false` while another
366
- * row is open.
367
- * - `'multiple'`: any number of rows. Each one is saved or cancelled on
368
- * its own.
369
- */
370
- readonly mode?: "single" | "multiple";
371
- /**
372
- * Adds a column at the end with Edit, Save and Cancel buttons.
373
- * Default `true`. Turn it off to start editing from your own code with
374
- * `edit`, `save` and `cancel`.
375
- */
376
- readonly button?: boolean;
377
- };
378
- /**
379
- * Options for creating a Tadabut table.
380
- *
381
- * @typeParam Row - The shape of one row. Usually worked out from `data`.
382
- */
383
- type TadabutOptions<Row extends object> = {
384
- /** The rows to show. One object per row. */
385
- readonly data: readonly Row[];
386
- /** The columns to show, in order. */
387
- readonly columns: readonly Column<Row>[];
388
- /**
389
- * Name of the row property that identifies each row, like `'id'`.
390
- * Its values must be unique strings or numbers.
391
- *
392
- * Required when a column has an `editor`: editing uses it to find rows.
393
- */
394
- readonly rowId?: keyof Row & string;
395
- /** How rows are edited. Only used when a column has an `editor`. */
396
- readonly editing?: EditingOptions;
397
- /**
398
- * Called when a row is saved, after every field passed validation.
399
- * It can be async.
400
- *
401
- * - Return nothing to keep the edited row, or return a row to use that
402
- * one instead (for fields the server fills in, like `updatedAt`).
403
- * - Throw to say saving failed. The row stays open with what the user
404
- * typed, and the error's message shows under it.
405
- *
406
- * Without `onSave`, saving just updates the table.
407
- */
408
- readonly onSave?: (row: Row, context: SaveContext<Row>) => Row | void | Promise<Row | void>;
409
- };
410
- /**
411
- * A DataTables table, created and owned by Tadabut.
412
- *
413
- * @typeParam Row - The shape of one row. Usually worked out from `data`,
414
- * so there is no need to write it.
415
- *
416
- * @example
417
- * const table = new Tadabut(container, {
418
- * data: [{ id: 1, name: 'Amina' }],
419
- * rowId: 'id',
420
- * columns: [
421
- * { title: 'ID', prop: 'id' },
422
- * { title: 'Name', prop: 'name' },
423
- * ],
424
- * });
425
- */
426
- declare class Tadabut<Row extends object> {
427
- private readonly dataTable;
428
- private readonly tableEl;
429
- private readonly rowId;
430
- private readonly columns;
431
- /** The `editing` option, with its defaults filled in. */
432
- private readonly editing;
433
- private readonly onSave;
434
- /** Whether the table has the actions column, with the Edit buttons. */
435
- private readonly hasActions;
436
- /** Whether at least one column has an editor. */
437
- private readonly hasEditor;
438
- /** The rows being edited, by row id. */
439
- private readonly sessions;
440
- /**
441
- * Creates a table inside `container`.
442
- *
443
- * @param container An empty element. Tadabut adds the table to it, and
444
- * `destroy()` leaves it empty again.
445
- * @param options The data and columns to show.
446
- * @throws If a column has an `editor` but `rowId` is missing. Editing
447
- * needs `rowId` to find rows.
448
- */
449
- constructor(container: HTMLElement, options: TadabutOptions<Row>);
450
- /**
451
- * Replaces all rows without rebuilding the table.
452
- *
453
- * Sorting, search and the current page are kept. If the current page no
454
- * longer exists (fewer rows than before), DataTables shows the last one.
455
- *
456
- * Any row being edited is cancelled first. Unsaved changes are lost.
457
- *
458
- * @param rows The new rows. The array is copied, never changed.
459
- */
460
- setData(rows: readonly Row[]): void;
461
- /**
462
- * Starts editing a row: its editable cells are replaced by editors showing
463
- * the row's values.
464
- *
465
- * In `'single'` mode (the default), only one row can be open at a time.
466
- * In `'multiple'` mode, any number can.
467
- *
468
- * @param id The row's id: the value of its `rowId` field.
469
- * @returns `true` if editing started. `false` if the row doesn't exist,
470
- * it's already open, another row is open in `'single'` mode, no column
471
- * is editable, or the row is on a page that hasn't been shown yet.
472
- */
473
- edit(id: string | number): boolean;
474
- /**
475
- * Stops editing a row and puts its original values back. Unsaved changes
476
- * are lost. Does nothing if the row isn't being edited.
477
- *
478
- * @param id The row's id: the value of its `rowId` field.
479
- */
480
- cancel(id: string | number): void;
481
- /**
482
- * Tells whether a row is being edited.
483
- *
484
- * @param id The row's id: the value of its `rowId` field.
485
- */
486
- isEditing(id: string | number): boolean;
487
- /**
488
- * Validates and saves the row being edited.
489
- *
490
- * 1. Every field is validated. If one fails, its error shows under its
491
- * input, the cursor goes to the first wrong field, and `onSave` isn't
492
- * called.
493
- * 2. The row is locked while `onSave` runs.
494
- * 3. If `onSave` works, the row closes and shows the new values: the row
495
- * `onSave` returned, or else the edited row.
496
- * 4. If `onSave` throws, the row stays open with what the user typed, and
497
- * the error's message shows under the row.
498
- *
499
- * The table's data only changes when saving works.
500
- *
501
- * @param id The row's id: the value of its `rowId` field.
502
- * @returns `true` if the row was saved and closed. `false` if a field is
503
- * invalid, `onSave` failed, the row isn't being edited, it's already
504
- * saving, or editing was stopped (by `setData` or `destroy`) while
505
- * `onSave` was running.
506
- */
507
- save(id: string | number): Promise<boolean>;
508
- /**
509
- * Removes the table and everything Tadabut added to the container.
510
- * Any row being edited is cancelled first.
511
- */
512
- destroy(): void;
513
- /**
514
- * Finds a row by its id. `undefined` if there is no `rowId` option, or no
515
- * row with that id.
516
- */
517
- private findRow;
518
- /**
519
- * Destroys every open editor, without putting the cells' content back.
520
- * Used right before the rows or the whole table go away.
521
- */
522
- private destroySessions;
523
- /**
524
- * Locks or unlocks a row while it's being saved: sets the session's
525
- * `saving` flag, and `inert` and the `tdb-row-saving` class on the row.
526
- *
527
- * Works even when the session is already gone, so a row can always be
528
- * unlocked after saving.
529
- */
530
- private setSaving;
531
- /**
532
- * Shows a save error on its own line under the row, with the
533
- * `tdb-save-error` class.
534
- *
535
- * The message is set as text, never as HTML: it often comes from a server,
536
- * and HTML in it could run code in the page.
537
- */
538
- private showSaveError;
539
- /** Removes the save error under a row, if there is one. */
540
- private clearSaveError;
541
- /**
542
- * Finds the id of the row an element is in.
543
- *
544
- * `undefined` if the element isn't in a row DataTables knows, like the
545
- * save error line under a row, or a table inside a custom editor.
546
- */
547
- private rowIdOf;
548
- /**
549
- * Handles clicks on the Edit, Save and Cancel buttons.
550
- *
551
- * One listener on the whole table, not one per button: DataTables adds and
552
- * removes rows all the time (paging, `setData`), and new buttons would need
553
- * new listeners.
554
- *
555
- * An arrow function, so `this` is still the Tadabut when the browser calls
556
- * it, and the same function can be removed in `destroy`.
557
- */
558
- private readonly onClick;
559
- /**
560
- * Enter saves the row being edited, Escape cancels it.
561
- *
562
- * An arrow function, for the same reasons as `onClick`.
563
- */
564
- private readonly onKeyDown;
565
- }
566
- export { EditorContext as _, Column as a, TextEditor as c, SelectOption as d, SelectOptionsLoader as f, CheckboxEditor as g, CustomEditor as h, TadabutOptions as i, OptionsContext as l, DateEditor as m, EditingOptions as n, ValidationOptions as o, NumberEditor as p, SaveContext as r, EditorFor as s, Tadabut as t, SelectEditor as u, EditorInstance as v };