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 +21 -21
- package/README.md +285 -39
- package/dist/index-DYUdG69c.d.ts +482 -0
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/react.d.ts +9 -30
- package/dist/react.js +38 -34
- package/dist/{src-bibmHRHk.js → src-cI0CYV46.js} +253 -390
- package/package.json +10 -7
- package/dist/index-BJkz6K5r.d.ts +0 -566
|
@@ -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 {
|
|
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 {
|
|
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 {
|
|
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
|
-
/**
|
|
7
|
+
/** Gives you `edit`, `save`, `cancel` and `isEditing`. */
|
|
19
8
|
readonly ref?: Ref<TadabutHandle<Row>>;
|
|
20
9
|
};
|
|
21
10
|
/**
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
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 {
|
|
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
|
|
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
|
-
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
19
|
-
*
|
|
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
|
|
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;
|