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.
@@ -0,0 +1,482 @@
1
+ import { Config } from "datatables.net";
2
+ /** Options every editor has. */
3
+ type BaseEditor = {
4
+ /** Extra classes for the input, like `'form-control'`. */
5
+ readonly className?: string;
6
+ };
7
+ /** What a custom editor's `create` receives. */
8
+ type EditorContext<Value> = {
9
+ /** The field's value when the row opened. */
10
+ readonly value: Value;
11
+ /** The `className` from the editor config. Put it on your element. */
12
+ readonly className?: string;
13
+ /** Call it when the user changes the value. */
14
+ readonly onChange: (value: Value) => void;
15
+ };
16
+ /** What a custom editor's `create` returns. */
17
+ type EditorInstance<Value> = {
18
+ /** Goes into the cell. */
19
+ readonly element: HTMLElement;
20
+ /** What the user has entered so far. */
21
+ readonly getValue: () => Value;
22
+ /** Must not call `onChange`. */
23
+ readonly setValue: (value: Value) => void;
24
+ /** Moves the cursor into your editor. */
25
+ readonly focus: () => void;
26
+ /** Remove the element and tear down any widget you created. */
27
+ readonly destroy: () => void;
28
+ };
29
+ /** For `boolean` columns. `null` shows unchecked; it never returns `null`. */
30
+ type CheckboxEditor = BaseEditor & {
31
+ /** Picks this editor. */
32
+ readonly type: "checkbox";
33
+ };
34
+ /**
35
+ * Bring your own editor (Select2, a date picker library…). Works on any
36
+ * column, objects included. `create` runs every time a row is opened; call
37
+ * `context.onChange` when the user changes the value.
38
+ *
39
+ * @example
40
+ * {
41
+ * type: 'custom',
42
+ * create: (context) => {
43
+ * const input = document.createElement('input');
44
+ * input.value = context.value ?? '';
45
+ * input.addEventListener('input', () => context.onChange(input.value));
46
+ * return {
47
+ * element: input,
48
+ * getValue: () => input.value,
49
+ * setValue: (value) => { input.value = value ?? ''; },
50
+ * focus: () => input.focus(),
51
+ * destroy: () => input.remove(),
52
+ * };
53
+ * },
54
+ * }
55
+ */
56
+ type CustomEditor<Value> = BaseEditor & {
57
+ /** Picks this editor. */
58
+ readonly type: "custom";
59
+ /** Builds your editor. Runs every time a row opens. */
60
+ readonly create: (context: EditorContext<Value>) => EditorInstance<Value>;
61
+ };
62
+ /**
63
+ * For `string` columns holding `'YYYY-MM-DD'`. Anything else, like
64
+ * `'2024-01-05T00:00:00'`, shows as empty and saves as `null`. Empty gives
65
+ * `null`.
66
+ *
67
+ * @example
68
+ * { type: 'date', min: '2020-01-01', max: '2030-12-31' }
69
+ */
70
+ type DateEditor = BaseEditor & {
71
+ /** Picks this editor. */
72
+ readonly type: "date";
73
+ /** Earliest date, as `'YYYY-MM-DD'`. */
74
+ readonly min?: string;
75
+ /** Latest date, as `'YYYY-MM-DD'`. */
76
+ readonly max?: string;
77
+ };
78
+ /**
79
+ * For `number` columns. Empty gives `null`, not `0`. The options work like
80
+ * the HTML attributes.
81
+ *
82
+ * @example
83
+ * { type: 'number', min: 18, max: 65, step: 1 }
84
+ */
85
+ type NumberEditor = BaseEditor & {
86
+ /** Picks this editor. */
87
+ readonly type: "number";
88
+ /** Smallest value allowed. */
89
+ readonly min?: number;
90
+ /** Largest value allowed. */
91
+ readonly max?: number;
92
+ /** Defaults to `1`. Use `0.01` for cents, or `'any'`. */
93
+ readonly step?: number | "any";
94
+ };
95
+ /**
96
+ * Every text Tadabut shows by itself. DataTables' own texts (search, paging…)
97
+ * go in `dataTables.language` instead.
98
+ *
99
+ * The ones that include a number or a date are functions, so each language
100
+ * can put it where its grammar wants.
101
+ */
102
+ type Texts = {
103
+ /** The Edit button. */
104
+ readonly edit: string;
105
+ /** The Save button. */
106
+ readonly save: string;
107
+ /** The Cancel button. */
108
+ readonly cancel: string;
109
+ /** Shown in a select while its options load. */
110
+ readonly loading: string;
111
+ /** Under a row when `onSave` throws something that isn't an `Error`. */
112
+ readonly saveFailed: string;
113
+ /** Under a select whose options failed to load. */
114
+ readonly loadFailed: string;
115
+ /** An empty field with `required`. */
116
+ readonly required: string;
117
+ /** A text that doesn't match `pattern`. */
118
+ readonly patternMismatch: string;
119
+ /** A text shorter than `minLength`. */
120
+ readonly tooShort: (min: number) => string;
121
+ /** A text longer than `maxLength`. */
122
+ readonly tooLong: (max: number) => string;
123
+ /** A number below `min`. */
124
+ readonly tooSmall: (min: number) => string;
125
+ /** A number above `max`. */
126
+ readonly tooLarge: (max: number) => string;
127
+ /** A date before `min`, given as `'YYYY-MM-DD'`. */
128
+ readonly tooEarly: (min: string) => string;
129
+ /** A date after `max`, given as `'YYYY-MM-DD'`. */
130
+ readonly tooLate: (max: string) => string;
131
+ };
132
+ /** One choice in a select. */
133
+ type SelectOption<Value> = {
134
+ /** What the user sees. */
135
+ readonly label: string;
136
+ /** What gets saved in the row. */
137
+ readonly value: Value;
138
+ };
139
+ /** The second argument of an `options` function. */
140
+ type OptionsContext = {
141
+ /**
142
+ * Aborted when the result isn't needed anymore (the field above changed
143
+ * again, or the row closed). Pass it to `fetch`.
144
+ */
145
+ readonly signal: AbortSignal;
146
+ };
147
+ /** Can return the list directly or a promise of it. */
148
+ type SelectOptionsLoader<Value, Row> = (row: Row, context: OptionsContext) => readonly SelectOption<Value>[] | Promise<readonly SelectOption<Value>[]>;
149
+ /** Fields that hold a string, so they can store a label. */
150
+ type TextKeys<Row> = { [Key in keyof Row]: Row[Key] extends string | null | undefined ? Key : never; }[keyof Row] & string;
151
+ /**
152
+ * A dropdown for `string`, `number` or `boolean` columns. Option values must
153
+ * have the column's type (`1`, not `'1'`). A value that matches no option
154
+ * gives `null`.
155
+ *
156
+ * `options` is a list, or a function of the row. With a function you can set
157
+ * `dependsOn`: when that field changes, this select is cleared and reloaded.
158
+ *
159
+ * @example
160
+ * { type: 'select', options: [{ value: 1, label: 'Morocco' }] }
161
+ *
162
+ * {
163
+ * type: 'select',
164
+ * dependsOn: 'countryId',
165
+ * labelProp: 'cityName',
166
+ * options: (row, { signal }) => fetchCities(row.countryId, signal),
167
+ * }
168
+ */
169
+ type SelectEditor<Value, Row> = BaseEditor & {
170
+ /** Picks this editor. */
171
+ readonly type: "select";
172
+ /**
173
+ * Where to save the picked label, like `'cityName'`. The cell shows that
174
+ * field too. While options are loading, the old label is kept.
175
+ */
176
+ readonly labelProp?: TextKeys<Row>;
177
+ } & ({
178
+ /** The choices, in order. */
179
+ readonly options: readonly SelectOption<Value>[];
180
+ /** Only allowed when `options` is a function. */
181
+ readonly dependsOn?: never;
182
+ } | {
183
+ /** Gives the choices for the open row. */
184
+ readonly options: SelectOptionsLoader<Value, Row>;
185
+ /** When this field changes, the select is cleared and `options` runs again. */
186
+ readonly dependsOn?: keyof Row & string;
187
+ });
188
+ /**
189
+ * For `string` columns. The options work like the HTML attributes.
190
+ *
191
+ * @example
192
+ * { type: 'text', minLength: 2, maxLength: 50 }
193
+ */
194
+ type TextEditor = BaseEditor & {
195
+ /** Picks this editor. */
196
+ readonly type: "text";
197
+ /** Fewest characters allowed. */
198
+ readonly minLength?: number;
199
+ /** Most characters allowed. */
200
+ readonly maxLength?: number;
201
+ /** Must match the whole value, like `'[A-Z]{2}[0-9]{4}'`. No slashes, no `^`/`$`. */
202
+ readonly pattern?: string;
203
+ };
204
+ /**
205
+ * Which editors a column can have, from its value type:
206
+ *
207
+ * | Column value | Built-in editors |
208
+ * | ------------- | ------------------ |
209
+ * | `string` | text, date, select |
210
+ * | `number` | number, select |
211
+ * | `boolean` | checkbox, select |
212
+ *
213
+ * `custom` works on anything. Nullable columns get the same editors as
214
+ * non-nullable ones.
215
+ */
216
+ type EditorFor<Value, Row> = EditorForValue<NonNullable<Value>, Row> | CustomEditor<Value>;
217
+ /** The built-in editors for a non-null value type. */
218
+ 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;
219
+ /**
220
+ * Works on every editor. An empty value fails `required` and skips every
221
+ * other check. Otherwise the editor's own rules (`min`, `maxLength`…) run,
222
+ * then `validate`. The first error wins.
223
+ *
224
+ * @example
225
+ * {
226
+ * type: 'number',
227
+ * required: true,
228
+ * min: 18,
229
+ * validate: (value, row) =>
230
+ * row.active && value !== null && value > 65
231
+ * ? 'Active employees must be 65 or younger'
232
+ * : undefined,
233
+ * }
234
+ */
235
+ type ValidationOptions<Row, Value> = {
236
+ /** Does nothing on a checkbox, which is never empty. */
237
+ readonly required?: boolean;
238
+ /**
239
+ * Return an error message, or `undefined` if the value is fine. `value`
240
+ * can be `null` even on non-nullable columns, since empty inputs give
241
+ * `null`.
242
+ */
243
+ readonly validate?: (value: Value | null, row: Row) => string | undefined;
244
+ };
245
+ /**
246
+ * A table column. The `editor` has to fit the type of `prop`, so a number
247
+ * field can't get a text input. Columns without an editor are read-only.
248
+ *
249
+ * @example
250
+ * const columns: Column<Employee>[] = [
251
+ * { title: 'ID', prop: 'id' },
252
+ * { title: 'Age', prop: 'age', editor: { type: 'number', required: true, min: 18 } },
253
+ * ];
254
+ */
255
+ type Column<Row extends object> = { readonly [Key in keyof Row & string]: ColumnFor<Row, Key>; }[keyof Row & string];
256
+ /** One column, for one field. `Column` is the union of these. */
257
+ type ColumnFor<Row extends object, Key extends keyof Row & string> = {
258
+ /** Header text. */
259
+ readonly title: string;
260
+ /** The field this column shows. */
261
+ readonly prop: Key;
262
+ /** Makes the column editable. Leave it out for a read-only column. */
263
+ readonly editor?: EditorFor<Row[Key], Row> & ValidationOptions<Row, Row[Key]>;
264
+ /**
265
+ * The cell's text when the row isn't open. It's shown as text, not HTML.
266
+ * Search uses it; sorting still uses the raw value.
267
+ *
268
+ * @example
269
+ * render: (value) => `${value} MAD`
270
+ */
271
+ readonly render?: (value: Row[Key], row: Row) => string;
272
+ /** Like `'60px'` or `'20%'`. */
273
+ readonly width?: string;
274
+ /** Hidden columns still keep their value in the row, but can't be edited. */
275
+ readonly visible?: boolean;
276
+ /** `false` turns off sorting by this column. */
277
+ readonly orderable?: boolean;
278
+ /** `false` leaves this column out of the search. */
279
+ readonly searchable?: boolean;
280
+ /** Classes for the cells (header too), not for the input. */
281
+ readonly className?: string;
282
+ };
283
+ /** The second argument of `onSave`. */
284
+ type SaveContext<Row extends object> = {
285
+ /** The row as it was before editing. */
286
+ readonly previous: Row;
287
+ };
288
+ /** How rows are edited. */
289
+ type EditingOptions = {
290
+ /**
291
+ * `'single'` (default) allows one open row at a time. `'multiple'` allows
292
+ * any number, each saved on its own.
293
+ */
294
+ readonly mode?: "single" | "multiple";
295
+ /**
296
+ * Adds an Edit/Save/Cancel column at the end. Defaults to `true`. Turn it
297
+ * off if you open rows yourself with `edit()`.
298
+ */
299
+ readonly button?: boolean;
300
+ };
301
+ /**
302
+ * Extra CSS classes for the table and its buttons. They're added next to the
303
+ * `tdb-` classes, not instead of them.
304
+ *
305
+ * @example
306
+ * // Bootstrap 5
307
+ * {
308
+ * table: 'table table-striped table-hover',
309
+ * button: 'btn btn-sm',
310
+ * edit: 'btn-outline-primary',
311
+ * save: 'btn-primary',
312
+ * cancel: 'btn-outline-secondary',
313
+ * }
314
+ */
315
+ type TableClassNames = {
316
+ /** On the `<table>`. */
317
+ readonly table?: string;
318
+ /** All three buttons. */
319
+ readonly button?: string;
320
+ /** Edit button only. */
321
+ readonly edit?: string;
322
+ /** Save button only. */
323
+ readonly save?: string;
324
+ /** Cancel button only. */
325
+ readonly cancel?: string;
326
+ };
327
+ /**
328
+ * Any {@link https://datatables.net/reference/option/ | DataTables option},
329
+ * extensions included, except the ones Tadabut has to own: `data`,
330
+ * `columns`, `columnDefs` (use the column options), and `ajax`/`serverSide`
331
+ * (load rows yourself and call `setData`).
332
+ *
333
+ * @example
334
+ * { order: [[1, 'asc']], pageLength: 20, language: { search: 'Rechercher :' } }
335
+ */
336
+ type DataTablesSettings = Omit<Config, "data" | "columns" | "columnDefs" | "ajax" | "serverSide">;
337
+ /** Options for `new Tadabut()`. */
338
+ type TadabutOptions<Row extends object> = {
339
+ /** The rows. The array is copied, never changed. */
340
+ readonly data: readonly Row[];
341
+ /** The columns, in order. */
342
+ readonly columns: readonly Column<Row>[];
343
+ /**
344
+ * The field that identifies a row, like `'id'`. Values must be unique.
345
+ * Required as soon as a column has an `editor`.
346
+ */
347
+ readonly rowId?: keyof Row & string;
348
+ /** How rows are edited. */
349
+ readonly editing?: EditingOptions;
350
+ /** Your classes for the table and buttons. */
351
+ readonly classNames?: TableClassNames;
352
+ /** DataTables' own options, passed through. */
353
+ readonly dataTables?: DataTablesSettings;
354
+ /**
355
+ * Tadabut's own texts, like `fr`. Whatever you leave out stays in English.
356
+ *
357
+ * @example
358
+ * texts: { ...fr, save: 'Valider' }
359
+ */
360
+ readonly texts?: Partial<Texts>;
361
+ /**
362
+ * Called with the edited row once it passes validation. May be async.
363
+ *
364
+ * Return a row to replace the edited one (useful for fields the server
365
+ * sets, like `updatedAt`), or nothing to keep it. Throw to reject the
366
+ * save: the row stays open and the error message is shown under it.
367
+ */
368
+ readonly onSave?: (row: Row, context: SaveContext<Row>) => Row | void | Promise<Row | void>;
369
+ };
370
+ /**
371
+ * A DataTables table with row editing.
372
+ *
373
+ * @typeParam Row - Usually inferred from `data`.
374
+ *
375
+ * @example
376
+ * const table = new Tadabut(container, {
377
+ * data: [{ id: 1, name: 'Amina' }],
378
+ * rowId: 'id',
379
+ * columns: [
380
+ * { title: 'ID', prop: 'id' },
381
+ * { title: 'Name', prop: 'name' },
382
+ * ],
383
+ * });
384
+ */
385
+ declare class Tadabut<Row extends object> {
386
+ /** The DataTables instance. */
387
+ private readonly dataTable;
388
+ /** The `<table>` Tadabut created. */
389
+ private readonly tableEl;
390
+ /** The field that identifies a row. */
391
+ private readonly rowId;
392
+ /** The user's columns, without the actions column. */
393
+ private readonly columns;
394
+ /** `editing` with its defaults filled in. */
395
+ private readonly editing;
396
+ /** The user's classes, or `{}`. */
397
+ private readonly classNames;
398
+ /** The user's texts over English. */
399
+ private readonly texts;
400
+ /** The user's save callback. */
401
+ private readonly onSave;
402
+ /** Whether the Edit/Save/Cancel column exists. */
403
+ private readonly hasActions;
404
+ /** Whether any column has an editor. */
405
+ private readonly hasEditor;
406
+ /** Open rows, by row id. */
407
+ private readonly sessions;
408
+ /**
409
+ * Builds the table inside `container`, which should be empty.
410
+ *
411
+ * @throws If a column has an `editor` and there's no `rowId`.
412
+ * @throws If a hidden column (`visible: false`) has an `editor`.
413
+ * @throws If a select's `labelProp` is its own column.
414
+ */
415
+ constructor(container: HTMLElement, options: TadabutOptions<Row>);
416
+ /**
417
+ * Replaces all rows. Sorting, search and the page are kept.
418
+ *
419
+ * Open rows are closed first, and their unsaved changes are lost.
420
+ */
421
+ setData(rows: readonly Row[]): void;
422
+ /**
423
+ * Opens a row for editing.
424
+ *
425
+ * @param id The value of the row's `rowId` field.
426
+ * @returns `false` if the row doesn't exist, is already open, another row
427
+ * is open in `'single'` mode, nothing is editable, or the row is on a
428
+ * page that hasn't been displayed yet.
429
+ */
430
+ edit(id: string | number): boolean;
431
+ /**
432
+ * Closes a row and throws away its changes. Does nothing if the row isn't
433
+ * open, or while it's saving.
434
+ */
435
+ cancel(id: string | number): void;
436
+ /** Whether a row is open for editing. */
437
+ isEditing(id: string | number): boolean;
438
+ /**
439
+ * Validates the open row, then calls `onSave`.
440
+ *
441
+ * Invalid fields show their errors and `onSave` isn't called. While
442
+ * `onSave` runs the row is locked. If it throws, the row stays open and
443
+ * the error message is shown under it. The table only changes on success.
444
+ *
445
+ * @returns `true` once the row is saved and closed.
446
+ */
447
+ save(id: string | number): Promise<boolean>;
448
+ /** Removes the table. Open rows are closed without saving. */
449
+ destroy(): void;
450
+ /** The row with this id, or `undefined`. */
451
+ private findRow;
452
+ /** Only for when the rows are about to go away: cells aren't restored. */
453
+ private destroySessions;
454
+ /** Also works after the session is gone, so a row can always be unlocked. */
455
+ private setSaving;
456
+ /**
457
+ * Shows the error in a child row under the row. The message gets its own
458
+ * class because Bootstrap colors every cell, which hides a color on the
459
+ * `<tr>`. Set as text: it often comes from a server.
460
+ */
461
+ private showSaveError;
462
+ /** Removes the error row under a row, if any. */
463
+ private clearSaveError;
464
+ /**
465
+ * `undefined` for rows DataTables doesn't know, like the save error row or
466
+ * a table inside a custom editor.
467
+ */
468
+ private rowIdOf;
469
+ /**
470
+ * Handles Edit, Save and Cancel. One listener on the table, because
471
+ * DataTables keeps replacing rows. An arrow function, so `this` stays
472
+ * bound and `destroy` can remove it.
473
+ */
474
+ private readonly onClick;
475
+ /** Enter saves, Escape cancels. */
476
+ private readonly onKeyDown;
477
+ }
478
+ /** English, the default. */
479
+ declare const en: Texts;
480
+ /** French. */
481
+ declare const fr: Texts;
482
+ export { EditorInstance as C, EditorContext as S, Texts as _, EditingOptions as a, CustomEditor as b, TadabutOptions as c, EditorFor as d, TextEditor as f, SelectOptionsLoader as g, SelectOption as h, DataTablesSettings as i, Column as l, SelectEditor as m, en as n, SaveContext as o, OptionsContext as p, Tadabut as r, TableClassNames as s, fr as t, ValidationOptions as u, NumberEditor as v, CheckboxEditor as x, DateEditor as y };
package/dist/index.d.ts CHANGED
@@ -1,2 +1,2 @@
1
- import { _ as EditorContext, a as Column, c as TextEditor, d as SelectOption, f as SelectOptionsLoader, g as CheckboxEditor, h as CustomEditor, i as TadabutOptions, l as OptionsContext, m as DateEditor, n as EditingOptions, o as ValidationOptions, p as NumberEditor, r as SaveContext, s as EditorFor, t as Tadabut, u as SelectEditor, v as EditorInstance } from "./index-BJkz6K5r.js";
2
- export { type CheckboxEditor, type Column, type CustomEditor, type DateEditor, type EditingOptions, type EditorContext, type EditorFor, type EditorInstance, type NumberEditor, type OptionsContext, type SaveContext, type SelectEditor, type SelectOption, type SelectOptionsLoader, Tadabut, type TadabutOptions, type TextEditor, type ValidationOptions };
1
+ import { C as EditorInstance, S as EditorContext, _ as Texts, a as EditingOptions, b as CustomEditor, c as TadabutOptions, d as EditorFor, f as TextEditor, g as SelectOptionsLoader, h as SelectOption, i as DataTablesSettings, l as Column, m as SelectEditor, n as en, o as SaveContext, p as OptionsContext, r as Tadabut, s as TableClassNames, t as fr, u as ValidationOptions, v as NumberEditor, x as CheckboxEditor, y as DateEditor } from "./index-DYUdG69c.js";
2
+ export { type CheckboxEditor, type Column, type CustomEditor, type DataTablesSettings, type DateEditor, type EditingOptions, type EditorContext, type EditorFor, type EditorInstance, type NumberEditor, type OptionsContext, type SaveContext, type SelectEditor, type SelectOption, type SelectOptionsLoader, type TableClassNames, Tadabut, type TadabutOptions, type TextEditor, type Texts, type ValidationOptions, en, fr };
package/dist/index.js CHANGED
@@ -1 +1 @@
1
- export { t as Tadabut } from "./src-bibmHRHk.js";
1
+ export { n as Tadabut, r as en, t as fr } from "./src-cI0CYV46.js";
package/dist/react.d.ts CHANGED
@@ -1,37 +1,16 @@
1
- import { i as TadabutOptions, t as Tadabut$1 } from "./index-BJkz6K5r.js";
1
+ import { c as TadabutOptions, r as Tadabut$1 } from "./index-DYUdG69c.js";
2
2
  import { ReactElement, Ref } from "react";
3
- /**
4
- * What a `ref` on the `Tadabut` component gets: the core's editing methods.
5
- * They work the same way, with the same return values.
6
- *
7
- * There is no `setData`: in React, the rows come from the `data` prop.
8
- *
9
- * @typeParam Row - The shape of one row.
10
- */
3
+ /** What the `ref` gets. No `setData`: change the `data` prop instead. */
11
4
  export type TadabutHandle<Row extends object> = Pick<Tadabut$1<Row>, "edit" | "save" | "cancel" | "isEditing">;
12
- /**
13
- * Props of the React `Tadabut` component: the core options, plus `ref`.
14
- *
15
- * @typeParam Row - The shape of one row. Usually worked out from `data`.
16
- */
5
+ /** The core options, plus `ref`. */
17
6
  export type TadabutProps<Row extends object> = TadabutOptions<Row> & {
18
- /** Gets the editing methods, to call them from your own buttons or code. */
7
+ /** Gives you `edit`, `save`, `cancel` and `isEditing`. */
19
8
  readonly ref?: Ref<TadabutHandle<Row>>;
20
9
  };
21
10
  /**
22
- * A Tadabut table as a React component.
23
- *
24
- * React only renders an empty `<div>`. The table inside it is created and
25
- * owned by the core, so React never touches it.
26
- *
27
- * - New `data` updates the table in place: sorting, search and the current
28
- * page are kept.
29
- * - New `columns`, `rowId`, `editing.mode` or `editing.button` rebuild the
30
- * table, and any row being edited is lost. Define `columns` outside the
31
- * component, or with `useMemo`.
32
- * - `onSave` can be a new function on every render. The table always calls
33
- * the latest one, without being rebuilt.
34
- *
35
- * @typeParam Row - The shape of one row. Usually worked out from `data`.
11
+ * New `data` updates the table in place. Changing `columns`, `rowId`,
12
+ * `dataTables` or `texts` rebuilds it (and closes open rows), so keep those
13
+ * stable with a constant or `useMemo`. `editing`, `classNames` and `onSave` can be
14
+ * inline: they're compared by value or read through a ref.
36
15
  */
37
- export declare function Tadabut<Row extends object>({ data, columns, rowId, editing, onSave, ref }: TadabutProps<Row>): ReactElement;
16
+ export declare function Tadabut<Row extends object>({ data, columns, rowId, editing, classNames, dataTables, texts, onSave, ref }: TadabutProps<Row>): ReactElement;
package/dist/react.js CHANGED
@@ -1,54 +1,42 @@
1
- import { t as Tadabut$1 } from "./src-bibmHRHk.js";
1
+ import { n as Tadabut$1 } from "./src-cI0CYV46.js";
2
2
  import { useEffect, useImperativeHandle, useRef } from "react";
3
3
  import { jsx } from "react/jsx-runtime";
4
4
  // src/react/index.tsx
5
5
  /**
6
- * React adapter for Tadabut.
6
+ * The React component.
7
+ *
8
+ * @packageDocumentation
9
+ * @module tadabut/react
7
10
  *
8
11
  * @example
12
+ * ```tsx
9
13
  * import { Tadabut } from 'tadabut/react';
10
14
  *
11
15
  * <Tadabut data={employees} columns={columns} rowId='id' />
12
- *
13
- * @packageDocumentation
16
+ * ```
14
17
  */
15
18
  /**
16
- * A Tadabut table as a React component.
17
- *
18
- * React only renders an empty `<div>`. The table inside it is created and
19
- * owned by the core, so React never touches it.
20
- *
21
- * - New `data` updates the table in place: sorting, search and the current
22
- * page are kept.
23
- * - New `columns`, `rowId`, `editing.mode` or `editing.button` rebuild the
24
- * table, and any row being edited is lost. Define `columns` outside the
25
- * component, or with `useMemo`.
26
- * - `onSave` can be a new function on every render. The table always calls
27
- * the latest one, without being rebuilt.
28
- *
29
- * @typeParam Row - The shape of one row. Usually worked out from `data`.
19
+ * New `data` updates the table in place. Changing `columns`, `rowId`,
20
+ * `dataTables` or `texts` rebuilds it (and closes open rows), so keep those
21
+ * stable with a constant or `useMemo`. `editing`, `classNames` and `onSave` can be
22
+ * inline: they're compared by value or read through a ref.
30
23
  */
31
- function Tadabut({ data, columns, rowId, editing, onSave, ref }) {
32
- /** The empty `<div>` React renders. The core builds the table inside it. */
24
+ function Tadabut({ data, columns, rowId, editing, classNames, dataTables, texts, onSave, ref }) {
25
+ /** The `<div>` the core builds the table in. */
33
26
  const containerRef = useRef(null);
34
- /**
35
- * The live core table, for `setData` and the ref's methods.
36
- * `null` before the first build and after unmount.
37
- */
27
+ /** The core table. `null` before the first build and after unmount. */
38
28
  const tableRef = useRef(null);
39
- /**
40
- * The latest `data`. When the table is rebuilt, it starts from the current
41
- * rows instead of the ones from the first render. Kept in a ref so `data`
42
- * stays out of the build effect's dependencies.
43
- */
29
+ /** The latest rows, so a rebuild doesn't go back to the first ones. */
44
30
  const dataRef = useRef(data);
45
- /**
46
- * The latest `onSave`. The core gets a function that never changes and
47
- * calls this one, so a new `onSave` doesn't rebuild the table.
48
- */
31
+ /** The latest `onSave`, so a new one doesn't rebuild the table. */
49
32
  const onSaveRef = useRef(onSave);
50
33
  const mode = editing?.mode;
51
34
  const button = editing?.button;
35
+ const tableClass = classNames?.table;
36
+ const buttonClass = classNames?.button;
37
+ const editClass = classNames?.edit;
38
+ const saveClass = classNames?.save;
39
+ const cancelClass = classNames?.cancel;
52
40
  useEffect(() => {
53
41
  const container = containerRef.current;
54
42
  if (!container) return;
@@ -60,6 +48,15 @@ function Tadabut({ data, columns, rowId, editing, onSave, ref }) {
60
48
  mode,
61
49
  button
62
50
  },
51
+ dataTables,
52
+ texts,
53
+ classNames: {
54
+ table: tableClass,
55
+ button: buttonClass,
56
+ edit: editClass,
57
+ save: saveClass,
58
+ cancel: cancelClass
59
+ },
63
60
  onSave: (row, context) => onSaveRef.current?.(row, context)
64
61
  });
65
62
  tableRef.current = table;
@@ -70,8 +67,15 @@ function Tadabut({ data, columns, rowId, editing, onSave, ref }) {
70
67
  }, [
71
68
  columns,
72
69
  rowId,
70
+ dataTables,
71
+ texts,
73
72
  mode,
74
- button
73
+ button,
74
+ tableClass,
75
+ buttonClass,
76
+ editClass,
77
+ saveClass,
78
+ cancelClass
75
79
  ]);
76
80
  useEffect(() => {
77
81
  dataRef.current = data;